From 5aba3b727d13d04356886a0de2c719ccb74f1161 Mon Sep 17 00:00:00 2001 From: Payon Date: Wed, 11 Dec 2024 21:56:52 +0800 Subject: [PATCH 1/4] feat: to rst:600 fix: inconsistent_reference fix: inconsistent_reference --- reference/import.po | 34 +++++++++++++++++++++++++++++----- 1 file changed, 29 insertions(+), 5 deletions(-) diff --git a/reference/import.po b/reference/import.po index 8886f39575..ace8b8a5c3 100644 --- a/reference/import.po +++ b/reference/import.po @@ -1007,7 +1007,7 @@ msgstr "" #: ../../reference/import.rst:548 msgid "__path__ attributes on modules" -msgstr "" +msgstr "模組上的 __path__ 屬性" #: ../../reference/import.rst:550 msgid "" @@ -1016,6 +1016,9 @@ msgid "" "submodules will be found. By definition, if a module has a :attr:`!__path__` " "attribute, it is a :term:`package`." msgstr "" +":attr:`~module.__path__` 屬性應該是一個（可能為空的）\\ :term:`sequence`，其" +"包含列舉套件子模組位置的字串。根據定義，如果一個模組有 :attr:`!__path__` 屬" +"性，那麼它就是一個 :term:`package`。" #: ../../reference/import.rst:555 msgid "" @@ -1025,6 +1028,9 @@ msgid "" "during import. However, :attr:`!__path__` is typically much more constrained " "than :data:`!sys.path`." msgstr "" +"套件的 :attr:`~module.__path__` 屬性在引入其子套件時被使用。在引入機制中，其" +"功能與 :data:`sys.path` 類似，即提供在引入期間搜尋模組的位置串列。然而，:" +"attr:`!__path__` 通常比 :data:`!sys.path` 更受限制。" #: ../../reference/import.rst:562 msgid "" @@ -1032,6 +1038,8 @@ msgid "" "__path__`. :data:`sys.path_hooks` (described below) are consulted when " "traversing a package's :attr:`!__path__`." msgstr "" +":data:`sys.path` 適用的規則同樣也適用於套件的 :attr:`!__path__`。 :data:`sys." +"path_hooks` 會在遍歷套件的 :attr:`!__path__` 時被參考（於後文詳述）。" #: ../../reference/import.rst:566 msgid "" @@ -1042,10 +1050,14 @@ msgid "" "containing only :attr:`!__path__` manipulation code; the import machinery " "automatically sets :attr:`!__path__` correctly for the namespace package." msgstr "" +"套件的 ``__init__.py`` 檔案可以設定或修改套件的 :attr:`~module.__path__` 屬" +"性，這通常是 :pep:`420` 之前實作命名空間套件的方式。隨著 :pep:`420` 的採用，" +"命名空間套件不再需要提供僅包含 :attr:`!__path__` 操作程式碼的 ``__init__." +"py`` 檔案；引入機制會自動為命名空間套件正確地設定 :attr:`!__path__`。" #: ../../reference/import.rst:575 msgid "Module reprs" -msgstr "" +msgstr "模組的 reprs" #: ../../reference/import.rst:577 msgid "" @@ -1053,6 +1065,8 @@ msgid "" "attributes set above, and in the module's spec, you can more explicitly " "control the repr of module objects." msgstr "" +"預設情況下，所有模組都有可用的 repr，然而，根據上述設定及模組規格中的屬性，你" +"可以更明確地控制模組物件的 repr。" #: ../../reference/import.rst:581 msgid "" @@ -1063,10 +1077,14 @@ msgid "" "__file__``, and ``module.__loader__`` as input into the repr, with defaults " "for whatever information is missing." msgstr "" +"如果模組具有規格（\\ ``__spec__``\\ ），引入機制將嘗試從規格中產生 repr。如果" +"失敗或沒有規格，引入系統將使用模組上可用的資訊製作一個預設的 repr。它會嘗試使" +"用 ``module.__name__``、``module.__file__`` 和 ``module.__loader__`` 作為 " +"repr 的輸入，並為缺少的資訊提供預設值。" #: ../../reference/import.rst:588 msgid "Here are the exact rules used:" -msgstr "" +msgstr "以下是具體的使用規則：" #: ../../reference/import.rst:590 msgid "" @@ -1074,22 +1092,26 @@ msgid "" "used to generate the repr. The \"name\", \"loader\", \"origin\", and " "\"has_location\" attributes are consulted." msgstr "" +"如果模組具有 ``__spec__`` 屬性，則使用規格中的資訊產生 repr。會參考 " +"\"name\"、\"loader\"、\"origin\" 和 \"has_location\" 屬性。" #: ../../reference/import.rst:594 msgid "" "If the module has a ``__file__`` attribute, this is used as part of the " "module's repr." -msgstr "" +msgstr "如果模組具有 ``__file__`` 屬性，則會將其作為模組 repr 的一部分。" #: ../../reference/import.rst:597 msgid "" "If the module has no ``__file__`` but does have a ``__loader__`` that is not " "``None``, then the loader's repr is used as part of the module's repr." msgstr "" +"如果模組沒有 ``__file__`` 但有一個不為 ``None`` 的 ``__loader__`` ，則會將載" +"入器的 repr 作為模組 repr 的一部分。" #: ../../reference/import.rst:600 msgid "Otherwise, just use the module's ``__name__`` in the repr." -msgstr "" +msgstr "否則，在 repr 中只使用模組的 ``__name__``。" #: ../../reference/import.rst:602 msgid "" @@ -1097,6 +1119,8 @@ msgid "" "removed in Python 3.12 and is no longer called during the resolution of a " "module's repr." msgstr "" +":meth:`!module_repr` 自 Python 3.4 起被棄用，並在 Python 3.12 中移除，且不會" +"在解析模組的 repr 時被呼叫。" #: ../../reference/import.rst:610 msgid "Cached bytecode invalidation" From 5ced5c2918ac119d7b69a6a8ce74ecd253a248ee Mon Sep 17 00:00:00 2001 From: Payon Date: Mon, 23 Dec 2024 15:35:03 +0800 Subject: [PATCH 2/4] =?UTF-8?q?feat:=20to:=20/import.rst:676=20-=20rst:668?= =?UTF-8?q?=20=E7=9A=84=20key-off=20=E5=AF=A6=E9=9A=9B=E7=9A=84=E6=84=8F?= =?UTF-8?q?=E6=80=9D=E5=8F=AF=E4=BB=A5=E8=A8=8E=E8=AB=96?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- reference/import.po | 42 ++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 40 insertions(+), 2 deletions(-) diff --git a/reference/import.po b/reference/import.po index ace8b8a5c3..3cfb4a71ba 100644 --- a/reference/import.po +++ b/reference/import.po @@ -1124,7 +1124,7 @@ msgstr "" #: ../../reference/import.rst:610 msgid "Cached bytecode invalidation" -msgstr "" +msgstr "被快取的位元組碼的無效化" #: ../../reference/import.rst:612 msgid "" @@ -1135,6 +1135,10 @@ msgid "" "cache file by checking the stored metadata in the cache file against the " "source's metadata." msgstr "" +"在 Python 從 ``.pyc`` 檔案載入被快取的位元組碼之前，會檢查該快取是否與來源的 " +"``.py`` 檔案保持同步。預設情況下，Python 透過在寫入快取檔案時儲存來源檔案的最" +"後修改時間戳和大小來完成此操作。在執行時，引入系統會透過將快取檔案中儲存的元" +"資料 (metadata) 與來源檔案的元資料進行比對來驗證快取檔案。" #: ../../reference/import.rst:619 msgid "" @@ -1149,16 +1153,25 @@ msgid "" "Hash-based ``.pyc`` files validation behavior may be overridden with the :" "option:`--check-hash-based-pycs` flag." msgstr "" +"Python 還支援「基於雜湊」的快取檔案，這些檔案儲存來源檔案內容的雜湊值，而不是" +"其元資料。基於雜湊的 ``.pyc`` 檔案有兩種變體：需檢查和不需要檢查的。對於需檢" +"查的基於雜湊的 ``.pyc`` 檔案，Python 透過對來源檔案進行雜湊並將結果與快取檔案" +"中的雜湊進行比較來驗證快取檔案。如果發現需檢查的基於雜湊的快取檔案無效，" +"Python 會重新產生並寫入新的需檢查的基於雜湊的快取檔案。對於不需要檢查的基於雜" +"湊的 ``.pyc`` 檔案，只要檔案存在，Python 就假設快取檔案是有效的。可以使用 :" +"option:`--check-hash-based-pycs` 旗標覆蓋基於雜湊的 ``.pyc`` 檔案的驗證行為。" #: ../../reference/import.rst:630 msgid "" "Added hash-based ``.pyc`` files. Previously, Python only supported timestamp-" "based invalidation of bytecode caches." msgstr "" +"新增了基於雜湊的 ``.pyc`` 檔案。此前，Python 只支援基於時間戳的位元組碼快取無" +"效化。" #: ../../reference/import.rst:636 msgid "The Path Based Finder" -msgstr "" +msgstr "基於路徑的尋檢器" #: ../../reference/import.rst:641 msgid "" @@ -1168,6 +1181,10 @@ msgid "" "contains a list of :term:`path entries `. Each path entry names " "a location to search for modules." msgstr "" +"如前所述，Python 附帶了幾個預設的元路徑尋檢器。其中之一稱為 :term:`path " +"based finder`\\ （\\ :class:`~importlib.machinery.PathFinder`\\ ），它搜尋 :" +"term:`import path`，該路徑包含一個 :term:`路徑條目 ` 的串列。每個" +"路徑條目都指定了一個用於搜尋模組的位置。" #: ../../reference/import.rst:647 msgid "" @@ -1175,6 +1192,8 @@ msgid "" "it traverses the individual path entries, associating each of them with a " "path entry finder that knows how to handle that particular kind of path." msgstr "" +"基於路徑的尋檢器本身並不知道如何引入任何東西。相反，它遍歷各個路徑條目，並將" +"每個路徑條目與一個知道如何處理該特定路徑類型的路徑條目尋檢器關聯起來。" #: ../../reference/import.rst:651 msgid "" @@ -1186,6 +1205,11 @@ msgid "" "also handle loading all of these file types (other than shared libraries) " "from zipfiles." msgstr "" +"預設的一組路徑條目尋檢器實作了在檔案系統中尋找模組的所有語意，包括處理特殊檔" +"案類型，例如 Python 原始程式碼檔案（``.py`` 檔案）、Python 位元組程式碼檔案" +"（``.pyc`` 檔案）以及共享函式庫（例如 ``.so`` 檔案）。當標準函式庫中的 :mod:" +"`zipimport` 模組支援時，預設的路徑條目尋檢器也能處理從壓縮檔案中載入這些檔案" +"類型（共享函式庫除外）。" #: ../../reference/import.rst:658 msgid "" @@ -1193,6 +1217,8 @@ msgid "" "to URLs, database queries, or any other location that can be specified as a " "string." msgstr "" +"路徑條目不必侷限於檔案系統位置。它們可以參照 URL、資料庫查詢或任何可以作為字" +"串指定的位置。" #: ../../reference/import.rst:662 msgid "" @@ -1204,6 +1230,10 @@ msgid "" "protocol described below, which was then used to get a loader for the module " "from the web." msgstr "" +"基於路徑的尋檢器提供了額外的掛鉤和協定，讓你可以擴展和自定可搜尋的路徑條目類" +"型。例如，如果你希望支援將路徑條目作為網路 URLs，你可以撰寫一個實作 HTTP 語意" +"的掛鉤，用於在網路上尋找模組。這個掛鉤（一個可呼叫物件）會回傳一個支援下述協" +"定的 :term:`path entry finder` ，該尋檢器隨後用於從網路中獲取模組的載入器。" #: ../../reference/import.rst:670 msgid "" @@ -1215,6 +1245,11 @@ msgid "" "In particular, meta path finders operate at the beginning of the import " "process, as keyed off the :data:`sys.meta_path` traversal." msgstr "" +"提醒一句：本節與前一節都使用了 *尋檢器* 這個術語，並透過使用術語 :term:`meta " +"path finder` 和 :term:`path entry finder` 來區分它們。這兩種類型的尋檢器非常" +"相似，支援類似的協定，並在引入過程中以類似的方式運作，但請記住，它們之間有些" +"微的差異。特別是，元路徑尋檢器在引入過程的一開始運作，並通過 :data:`sys." +"meta_path` 的遍歷關閉 (key off)。" #: ../../reference/import.rst:678 msgid "" @@ -1223,6 +1258,9 @@ msgid "" "removed from :data:`sys.meta_path`, none of the path entry finder semantics " "would be invoked." msgstr "" +"相比之下，路徑條目尋檢器在某種意義上是基於路徑的尋檢器的一個實作細節。事實" +"上，如果基於路徑的尋檢器從 :data:`sys.meta_path` 中移除，路徑條目尋檢器的任何" +"語意都不會被調用。" #: ../../reference/import.rst:685 msgid "Path entry finders" From 0a724367ef67dd49637a39ec993f21fb3141c88a Mon Sep 17 00:00:00 2001 From: ken Date: Sat, 17 Jan 2026 17:36:16 +0800 Subject: [PATCH 3/4] feat: to: /import.rst:970 ^ Conflicts: ^ reference/import.po --- .github/workflows/ci.yml | 80 +- .github/workflows/deploy-gh-page.yml | 60 +- .github/workflows/py314-sync-cpython.yml | 134 +- .github/workflows/summarize_progress.yml | 88 +- .scripts/summarize_progress/main.py | 342 +- Makefile | 330 +- README.rst | 954 +- about.po | 196 +- bugs.po | 532 +- c-api/abstract.po | 94 +- c-api/allocation.po | 512 +- c-api/apiabiversion.po | 604 +- c-api/arg.po | 2552 +- c-api/bool.po | 178 +- c-api/buffer.po | 1612 +- c-api/bytearray.po | 258 +- c-api/bytes.po | 816 +- c-api/call.po | 1392 +- c-api/capsule.po | 470 +- c-api/cell.po | 218 +- c-api/code.po | 976 +- c-api/codec.po | 422 +- c-api/complex.po | 526 +- c-api/concrete.po | 216 +- c-api/contextvars.po | 530 +- c-api/conversion.po | 776 +- c-api/coro.po | 118 +- c-api/curses.po | 426 +- c-api/datetime.po | 888 +- c-api/descriptor.po | 270 +- c-api/dict.po | 1426 +- c-api/exceptions.po | 3150 +-- c-api/extension-modules.po | 768 +- c-api/file.po | 448 +- c-api/float.po | 794 +- c-api/frame.po | 536 +- c-api/function.po | 610 +- c-api/gcsupport.po | 916 +- c-api/gen.po | 260 +- c-api/hash.po | 420 +- c-api/import.po | 1116 +- c-api/index.po | 74 +- c-api/init.po | 7454 +++--- c-api/init_config.po | 6844 +++--- c-api/intro.po | 3318 +-- c-api/iter.po | 198 +- c-api/iterator.po | 304 +- c-api/lifecycle.po | 728 +- c-api/list.po | 542 +- c-api/long.po | 2068 +- c-api/mapping.po | 398 +- c-api/marshal.po | 324 +- c-api/memory.po | 2418 +- c-api/memoryview.po | 216 +- c-api/method.po | 286 +- c-api/module.po | 1816 +- c-api/monitoring.po | 604 +- c-api/none.po | 106 +- c-api/number.po | 654 +- c-api/object.po | 1948 +- c-api/objimpl.po | 56 +- c-api/perfmaps.po | 232 +- c-api/picklebuffer.po | 202 +- c-api/refcounting.po | 746 +- c-api/reflection.po | 260 +- c-api/sequence.po | 446 +- c-api/set.po | 416 +- c-api/slice.po | 430 +- c-api/stable.po | 798 +- c-api/structures.po | 2442 +- c-api/sys.po | 1156 +- c-api/time.po | 378 +- c-api/tuple.po | 672 +- c-api/type.po | 1698 +- c-api/typehints.po | 188 +- c-api/typeobj.po | 9568 ++++---- c-api/unicode.po | 4708 ++-- c-api/utilities.po | 74 +- c-api/veryhigh.po | 964 +- c-api/weakref.po | 330 +- contents.po | 48 +- copyright.po | 116 +- deprecations/c-api-pending-removal-in-3.14.po | 72 +- deprecations/c-api-pending-removal-in-3.15.po | 764 +- deprecations/c-api-pending-removal-in-3.16.po | 48 +- deprecations/c-api-pending-removal-in-3.18.po | 344 +- .../c-api-pending-removal-in-future.po | 246 +- deprecations/index.po | 3230 +-- deprecations/pending-removal-in-3.13.po | 296 +- deprecations/pending-removal-in-3.14.po | 496 +- deprecations/pending-removal-in-3.15.po | 484 +- deprecations/pending-removal-in-3.16.po | 496 +- deprecations/pending-removal-in-3.17.po | 186 +- deprecations/pending-removal-in-3.18.po | 74 +- deprecations/pending-removal-in-3.19.po | 68 +- deprecations/pending-removal-in-future.po | 882 +- distributing/index.po | 68 +- extending/building.po | 110 +- extending/embedding.po | 1426 +- extending/extending.po | 4610 ++-- extending/index.po | 248 +- extending/newtypes.po | 2198 +- extending/newtypes_tutorial.po | 4654 ++-- extending/windows.po | 476 +- faq/design.po | 3138 +-- faq/extending.po | 1024 +- faq/general.po | 1784 +- faq/gui.po | 282 +- faq/index.po | 46 +- faq/installed.po | 272 +- faq/library.po | 2698 +- faq/programming.po | 9134 +++---- faq/windows.po | 1112 +- glossary.po | 7356 +++--- howto/a-conceptual-overview-of-asyncio.po | 1836 +- howto/annotations.po | 988 +- howto/argparse-optparse.po | 332 +- howto/argparse.po | 3482 +-- howto/clinic.po | 60 +- howto/cporting.po | 100 +- howto/curses.po | 1758 +- howto/descriptor.po | 4136 ++-- howto/enum.po | 5816 ++--- howto/free-threading-extensions.po | 1446 +- howto/free-threading-python.po | 522 +- howto/functional.po | 4108 ++-- howto/gdb_helpers.po | 2324 +- howto/index.po | 294 +- howto/instrumentation.po | 1696 +- howto/ipaddress.po | 1300 +- howto/isolating-extensions.po | 1956 +- howto/logging-cookbook.po | 11716 ++++----- howto/logging.po | 3486 +-- howto/mro.po | 2444 +- howto/perf_profiling.po | 1262 +- howto/pyporting.po | 170 +- howto/regex.po | 4948 ++-- howto/remote_debugging.po | 2530 +- howto/sockets.po | 1510 +- howto/sorting.po | 1660 +- howto/timerfd.po | 976 +- howto/unicode.po | 2526 +- howto/urllib2.po | 1802 +- installing/index.po | 936 +- library/__future__.po | 672 +- library/__main__.po | 1422 +- library/_thread.po | 776 +- library/abc.po | 1358 +- library/aifc.po | 78 +- library/allos.po | 72 +- library/annotationlib.po | 2058 +- library/archiving.po | 70 +- library/argparse.po | 7830 +++--- library/array.po | 1080 +- library/ast.po | 9310 +++---- library/asynchat.po | 86 +- library/asyncio-api-index.po | 920 +- library/asyncio-dev.po | 966 +- library/asyncio-eventloop.po | 6332 ++--- library/asyncio-exceptions.po | 224 +- library/asyncio-extending.po | 310 +- library/asyncio-future.po | 912 +- library/asyncio-graph.po | 438 +- library/asyncio-llapi-index.po | 2126 +- library/asyncio-platforms.po | 392 +- library/asyncio-policy.po | 466 +- library/asyncio-protocol.po | 2736 +-- library/asyncio-queue.po | 700 +- library/asyncio-runner.po | 560 +- library/asyncio-stream.po | 1570 +- library/asyncio-subprocess.po | 1064 +- library/asyncio-sync.po | 1352 +- library/asyncio-task.po | 4106 ++-- library/asyncio.po | 464 +- library/asyncore.po | 86 +- library/atexit.po | 492 +- library/audioop.po | 78 +- library/audit_events.po | 286 +- library/base64.po | 1140 +- library/bdb.po | 1334 +- library/binary.po | 96 +- library/binascii.po | 492 +- library/bisect.po | 848 +- library/builtins.po | 222 +- library/bz2.po | 864 +- library/calendar.po | 1790 +- library/cgi.po | 96 +- library/cgitb.po | 96 +- library/chunk.po | 78 +- library/cmath.po | 1404 +- library/cmd.po | 1400 +- library/cmdline.po | 460 +- library/cmdlinelibs.po | 64 +- library/code.po | 648 +- library/codecs.po | 5880 ++--- library/codeop.po | 286 +- library/collections.abc.po | 1668 +- library/collections.po | 4408 ++-- library/colorsys.po | 200 +- library/compileall.po | 874 +- library/compression.po | 110 +- library/compression.zstd.po | 2396 +- library/concurrency.po | 80 +- library/concurrent.futures.po | 2304 +- library/concurrent.interpreters.po | 1046 +- library/concurrent.po | 74 +- library/configparser.po | 4016 +-- library/constants.po | 414 +- library/contextlib.po | 3352 +-- library/contextvars.po | 1118 +- library/copy.po | 458 +- library/copyreg.po | 198 +- library/crypt.po | 100 +- library/crypto.po | 74 +- library/csv.po | 2134 +- library/ctypes.po | 9836 ++++---- library/curses.ascii.po | 678 +- library/curses.panel.po | 258 +- library/curses.po | 5232 ++-- library/custominterp.po | 78 +- library/dataclasses.po | 3426 +-- library/datatypes.po | 98 +- library/datetime.po | 8924 +++---- library/dbm.po | 1272 +- library/debug.po | 78 +- library/decimal.po | 5910 ++--- library/development.po | 78 +- library/devmode.po | 980 +- library/dialog.po | 572 +- library/difflib.po | 2258 +- library/dis.po | 4864 ++-- library/distribution.po | 68 +- library/distutils.po | 82 +- library/doctest.po | 5818 ++--- library/email.charset.po | 716 +- library/email.compat32-message.po | 1928 +- library/email.contentmanager.po | 580 +- library/email.encoders.po | 292 +- library/email.errors.po | 360 +- library/email.examples.po | 958 +- library/email.generator.po | 658 +- library/email.header.po | 698 +- library/email.headerregistry.po | 1366 +- library/email.iterators.po | 252 +- library/email.message.po | 1844 +- library/email.mime.po | 604 +- library/email.parser.po | 764 +- library/email.po | 392 +- library/email.policy.po | 1668 +- library/email.utils.po | 562 +- library/ensurepip.po | 552 +- library/enum.po | 3796 +-- library/errno.po | 1422 +- library/exceptions.po | 3612 +-- library/faulthandler.po | 806 +- library/fcntl.po | 828 +- library/filecmp.po | 530 +- library/fileformats.po | 62 +- library/fileinput.po | 656 +- library/filesys.po | 136 +- library/fnmatch.po | 436 +- library/fractions.po | 720 +- library/frameworks.po | 84 +- library/ftplib.po | 1496 +- library/functional.po | 70 +- library/functions.po | 7936 +++--- library/functools.po | 3066 +-- library/gc.po | 1258 +- library/getopt.po | 810 +- library/getpass.po | 254 +- library/gettext.po | 1918 +- library/glob.po | 676 +- library/graphlib.po | 800 +- library/grp.po | 310 +- library/gzip.po | 910 +- library/hashlib.po | 2662 +- library/heapq.po | 1434 +- library/hmac.po | 446 +- library/html.entities.po | 154 +- library/html.parser.po | 1308 +- library/html.po | 142 +- library/http.client.po | 1672 +- library/http.cookiejar.po | 2430 +- library/http.cookies.po | 938 +- library/http.po | 2274 +- library/http.server.po | 1668 +- library/i18n.po | 74 +- library/idle.po | 3502 +-- library/imaplib.po | 1758 +- library/imghdr.po | 96 +- library/imp.po | 92 +- library/importlib.metadata.po | 1880 +- library/importlib.po | 4128 ++-- library/importlib.resources.abc.po | 468 +- library/importlib.resources.po | 720 +- library/index.po | 156 +- library/inspect.po | 4822 ++-- library/internet.po | 110 +- library/intro.po | 592 +- library/io.po | 4042 +-- library/ipaddress.po | 2324 +- library/ipc.po | 84 +- library/itertools.po | 4856 ++-- library/json.po | 2782 +-- library/keyword.po | 130 +- library/language.po | 70 +- library/linecache.po | 292 +- library/locale.po | 1966 +- library/logging.config.po | 3030 +-- library/logging.handlers.po | 3380 +-- library/logging.po | 4702 ++-- library/lzma.po | 1458 +- library/mailbox.po | 3980 +-- library/mailcap.po | 78 +- library/markup.po | 68 +- library/marshal.po | 814 +- library/math.po | 2940 +-- library/mimetypes.po | 994 +- library/mm.po | 66 +- library/mmap.po | 1258 +- library/modulefinder.po | 392 +- library/modules.po | 68 +- library/msilib.po | 78 +- library/msvcrt.po | 600 +- library/multiprocessing.po | 10158 ++++---- library/multiprocessing.shared_memory.po | 1230 +- library/netdata.po | 60 +- library/netrc.po | 314 +- library/nis.po | 78 +- library/nntplib.po | 78 +- library/numbers.po | 852 +- library/numeric.po | 82 +- library/operator.po | 1946 +- library/optparse.po | 7346 +++--- library/os.path.po | 1870 +- library/os.po | 13568 +++++----- library/ossaudiodev.po | 78 +- library/pathlib.po | 7358 +++--- library/pdb.po | 2912 +-- library/persistence.po | 78 +- library/pickle.po | 5180 ++-- library/pickletools.po | 346 +- library/pipes.po | 86 +- library/pkgutil.po | 726 +- library/platform.po | 1238 +- library/plistlib.po | 662 +- library/poplib.po | 700 +- library/posix.po | 368 +- library/pprint.po | 1216 +- library/profile.po | 2358 +- library/pty.po | 364 +- library/pwd.po | 376 +- library/py_compile.po | 430 +- library/pyclbr.po | 398 +- library/pydoc.po | 462 +- library/pyexpat.po | 2180 +- library/python.po | 76 +- library/queue.po | 1006 +- library/quopri.po | 236 +- library/random.po | 2762 +-- library/re.po | 6752 ++--- library/readline.po | 994 +- library/removed.po | 56 +- library/reprlib.po | 722 +- library/resource.po | 1182 +- library/rlcompleter.po | 230 +- library/runpy.po | 560 +- library/sched.po | 484 +- library/secrets.po | 622 +- library/security_warnings.po | 272 +- library/select.po | 2048 +- library/selectors.po | 760 +- library/shelve.po | 610 +- library/shlex.po | 1132 +- library/shutil.po | 2630 +- library/signal.po | 2446 +- library/site.po | 834 +- library/smtpd.po | 94 +- library/smtplib.po | 1652 +- library/sndhdr.po | 96 +- library/socket.po | 5600 ++--- library/socketserver.po | 1714 +- library/spwd.po | 94 +- library/sqlite3.po | 6770 ++--- library/ssl.po | 8320 +++---- library/stat.po | 956 +- library/statistics.po | 4254 ++-- library/stdtypes.po | 20426 ++++++++-------- library/string.po | 3308 +-- library/string.templatelib.po | 666 +- library/stringprep.po | 372 +- library/struct.po | 2686 +- library/subprocess.po | 4206 ++-- library/sunau.po | 80 +- library/superseded.po | 122 +- library/symtable.po | 956 +- library/sys.monitoring.po | 1466 +- library/sys.po | 5966 ++--- library/sys_path_init.po | 432 +- library/sysconfig.po | 1606 +- library/syslog.po | 458 +- library/tabnanny.po | 196 +- library/tarfile.po | 4834 ++-- library/telnetlib.po | 96 +- library/tempfile.po | 1682 +- library/termios.po | 372 +- library/test.po | 4260 ++-- library/text.po | 80 +- library/textwrap.po | 826 +- library/threading.po | 4194 ++-- library/time.po | 3614 +-- library/timeit.po | 1336 +- library/tk.po | 162 +- library/tkinter.colorchooser.po | 108 +- library/tkinter.dnd.po | 238 +- library/tkinter.font.po | 348 +- library/tkinter.messagebox.po | 550 +- library/tkinter.po | 4668 ++-- library/tkinter.scrolledtext.po | 114 +- library/tkinter.ttk.po | 4870 ++-- library/token.po | 1004 +- library/tokenize.po | 948 +- library/tomllib.po | 582 +- library/trace.po | 684 +- library/traceback.po | 1898 +- library/tracemalloc.po | 2258 +- library/tty.po | 268 +- library/turtle.po | 8876 +++---- library/types.po | 1380 +- library/typing.po | 12828 +++++----- library/unicodedata.po | 636 +- library/unittest.mock-examples.po | 3698 +-- library/unittest.mock.po | 8202 +++---- library/unittest.po | 7700 +++--- library/unix.po | 66 +- library/urllib.error.po | 242 +- library/urllib.parse.po | 2224 +- library/urllib.po | 106 +- library/urllib.request.po | 4280 ++-- library/urllib.robotparser.po | 348 +- library/uu.po | 78 +- library/uuid.po | 1352 +- library/venv.po | 2806 +-- library/warnings.po | 2598 +- library/wave.po | 686 +- library/weakref.po | 1908 +- library/webbrowser.po | 1090 +- library/windows.po | 60 +- library/winreg.po | 2038 +- library/winsound.po | 528 +- library/wsgiref.po | 2734 +-- library/xdrlib.po | 80 +- library/xml.dom.minidom.po | 1098 +- library/xml.dom.po | 2712 +- library/xml.dom.pulldom.po | 470 +- library/xml.etree.elementtree.po | 4240 ++-- library/xml.po | 406 +- library/xml.sax.handler.po | 1234 +- library/xml.sax.po | 450 +- library/xml.sax.reader.po | 856 +- library/xml.sax.utils.po | 318 +- library/xmlrpc.client.po | 1808 +- library/xmlrpc.po | 98 +- library/xmlrpc.server.po | 1384 +- library/zipapp.po | 1308 +- library/zipfile.po | 3064 +-- library/zipimport.po | 626 +- library/zlib.po | 1450 +- library/zoneinfo.po | 1552 +- license.po | 5182 ++-- reference/compound_stmts.po | 6326 ++--- reference/datamodel.po | 11406 ++++----- reference/executionmodel.po | 1928 +- reference/expressions.po | 6676 ++--- reference/grammar.po | 7734 +++--- reference/import.po | 3723 +-- reference/index.po | 84 +- reference/introduction.po | 890 +- reference/lexical_analysis.po | 5368 ++-- reference/simple_stmts.po | 3566 +-- reference/toplevel_components.po | 398 +- sphinx.po | 1002 +- tutorial/appendix.po | 552 +- tutorial/appetite.po | 392 +- tutorial/classes.po | 3734 +-- tutorial/controlflow.po | 4878 ++-- tutorial/datastructures.po | 2912 +-- tutorial/errors.po | 2880 +-- tutorial/floatingpoint.po | 1466 +- tutorial/index.po | 222 +- tutorial/inputoutput.po | 2300 +- tutorial/interactive.po | 192 +- tutorial/interpreter.po | 622 +- tutorial/introduction.po | 2536 +- tutorial/modules.po | 2494 +- tutorial/stdlib.po | 1422 +- tutorial/stdlib2.po | 1704 +- tutorial/venv.po | 848 +- tutorial/whatnow.po | 342 +- using/android.po | 404 +- using/cmdline.po | 3400 +-- using/configure.po | 4848 ++-- using/editors.po | 110 +- using/index.po | 66 +- using/ios.po | 1264 +- using/mac.po | 1456 +- using/unix.po | 856 +- using/windows.po | 6794 ++--- whatsnew/2.0.po | 3628 +-- whatsnew/2.1.po | 2430 +- whatsnew/2.2.po | 3990 +-- whatsnew/2.3.po | 6668 ++--- whatsnew/2.4.po | 5254 ++-- whatsnew/2.5.po | 7236 +++--- whatsnew/2.6.po | 10236 ++++---- whatsnew/2.7.po | 8094 +++--- whatsnew/3.0.po | 2808 +-- whatsnew/3.1.po | 1990 +- whatsnew/3.10.po | 9344 +++---- whatsnew/3.11.po | 11176 ++++----- whatsnew/3.12.po | 11472 ++++----- whatsnew/3.13.po | 12518 +++++----- whatsnew/3.14.po | 13860 +++++------ whatsnew/3.2.po | 9064 +++---- whatsnew/3.3.po | 8732 +++---- whatsnew/3.4.po | 7474 +++--- whatsnew/3.5.po | 8084 +++--- whatsnew/3.6.po | 7356 +++--- whatsnew/3.7.po | 7484 +++--- whatsnew/3.8.po | 7536 +++--- whatsnew/3.9.po | 5284 ++-- whatsnew/changelog.po | 50 +- whatsnew/index.po | 92 +- 533 files changed, 516582 insertions(+), 516447 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 702d79bbee..e3d89dfbdc 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,40 +1,40 @@ -name: build - -concurrency: preview-${{ github.ref }} - -permissions: - contents: write - pull-requests: write - -on: - pull_request: - -jobs: - ci: - runs-on: ubuntu-22.04 - steps: - - uses: actions/checkout@v5 - - - uses: actions/setup-python@v6 - with: - python-version: "3.13" - - - name: Install Dependencies - run: sudo apt-get install gettext - - - name: Install uv - uses: astral-sh/setup-uv@v7 - - - name: Build HTML Docs - run: VERSION=${{ github.event.repository.default_branch }} JOBS=4 MODE=html make all - - - name: Deploy PR Doc Preview - # PR from the forked repo would be denied as the permission is not granted. - # Allow only PR from this repo. - if: ${{ ( github.event.pull_request.head.repo.full_name == github.event.pull_request.base.repo.full_name ) }} - uses: rossjrw/pr-preview-action@v1 - with: - source-dir: ../cpython/Doc/build/html - preview-branch: gh-pages - umbrella-dir: pr-preview - action: auto +name: build + +concurrency: preview-${{ github.ref }} + +permissions: + contents: write + pull-requests: write + +on: + pull_request: + +jobs: + ci: + runs-on: ubuntu-22.04 + steps: + - uses: actions/checkout@v5 + + - uses: actions/setup-python@v6 + with: + python-version: "3.13" + + - name: Install Dependencies + run: sudo apt-get install gettext + + - name: Install uv + uses: astral-sh/setup-uv@v7 + + - name: Build HTML Docs + run: VERSION=${{ github.event.repository.default_branch }} JOBS=4 MODE=html make all + + - name: Deploy PR Doc Preview + # PR from the forked repo would be denied as the permission is not granted. + # Allow only PR from this repo. + if: ${{ ( github.event.pull_request.head.repo.full_name == github.event.pull_request.base.repo.full_name ) }} + uses: rossjrw/pr-preview-action@v1 + with: + source-dir: ../cpython/Doc/build/html + preview-branch: gh-pages + umbrella-dir: pr-preview + action: auto diff --git a/.github/workflows/deploy-gh-page.yml b/.github/workflows/deploy-gh-page.yml index c0bff8f534..5fe7bf3749 100644 --- a/.github/workflows/deploy-gh-page.yml +++ b/.github/workflows/deploy-gh-page.yml @@ -1,30 +1,30 @@ -name: deploy-gh-page - -on: - push: - branches: - - "3.14" - -jobs: - cd: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v5 - - - name: Install Dependencies - run: sudo apt-get install gettext - - - name: Install uv - uses: astral-sh/setup-uv@v7 - - - name: Build - run: JOBS=4 MODE=html make all - - - name: Deploy to gh page - uses: JamesIves/github-pages-deploy-action@v4.7.3 - with: - token: ${{ secrets.GITHUB_TOKEN }} - branch: gh-pages - folder: ../cpython/Doc/build/html - clean: true - clean-exclude: pr-preview/ +name: deploy-gh-page + +on: + push: + branches: + - "3.14" + +jobs: + cd: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v5 + + - name: Install Dependencies + run: sudo apt-get install gettext + + - name: Install uv + uses: astral-sh/setup-uv@v7 + + - name: Build + run: JOBS=4 MODE=html make all + + - name: Deploy to gh page + uses: JamesIves/github-pages-deploy-action@v4.7.3 + with: + token: ${{ secrets.GITHUB_TOKEN }} + branch: gh-pages + folder: ../cpython/Doc/build/html + clean: true + clean-exclude: pr-preview/ diff --git a/.github/workflows/py314-sync-cpython.yml b/.github/workflows/py314-sync-cpython.yml index 9f0f5af7b1..5657fcae7c 100644 --- a/.github/workflows/py314-sync-cpython.yml +++ b/.github/workflows/py314-sync-cpython.yml @@ -1,67 +1,67 @@ -name: python-3.14-sync-with-cpython - -on: - push: - branches: - - "3.14" - schedule: - - cron: "0 0 * * *" - -jobs: - sync: - runs-on: ubuntu-latest - env: - VERSION: "3.14" - BRANCH: "cron/sync/3.14" - steps: - - uses: actions/checkout@v5 - with: - ref: ${{ env.VERSION }} - - - name: Get the changes on branch (if exists) - continue-on-error: true - run: | - git fetch origin ${{ env.BRANCH }}:${{ env.BRANCH }} - git reset --hard ${{ env.BRANCH }} - - - name: Set env - run: echo "LATEST_COMMIT_ID=$(git ls-remote https://github.com/python/CPython.git $VERSION | head -c 8)" >> $GITHUB_ENV - - - name: Install Dependencies - run: sudo apt-get install gettext - - - name: Install uv - uses: astral-sh/setup-uv@v7 - - - name: Sync with CPython - run: make clone merge rm_cpython wrap - - - uses: actions/create-github-app-token@v2 - id: app-token - with: - app-id: ${{ secrets.APP_ID }} - private-key: ${{ secrets.APP_PRIVATE_KEY }} - - - name: Create Pull Request - id: cpr - uses: peter-evans/create-pull-request@v6 - with: - token: ${{ steps.app-token.outputs.token }} - commit-message: sync with cpython ${{ env.LATEST_COMMIT_ID }} - committer: GitHub - author: github-actions[bot] - base: ${{ env.VERSION }} - branch: ${{ env.BRANCH }} - delete-branch: false - title: "Sync with CPython ${{ env.VERSION }}" - body: | - Sync with CPython ${{ env.VERSION }} - draft: true - labels: | - sync-cpython - automation - - - name: Check outputs - run: | - echo "Pull Request Number - ${{ steps.cpr.outputs.pull-request-number }}" - echo "Pull Request URL - ${{ steps.cpr.outputs.pull-request-url }}" +name: python-3.14-sync-with-cpython + +on: + push: + branches: + - "3.14" + schedule: + - cron: "0 0 * * *" + +jobs: + sync: + runs-on: ubuntu-latest + env: + VERSION: "3.14" + BRANCH: "cron/sync/3.14" + steps: + - uses: actions/checkout@v5 + with: + ref: ${{ env.VERSION }} + + - name: Get the changes on branch (if exists) + continue-on-error: true + run: | + git fetch origin ${{ env.BRANCH }}:${{ env.BRANCH }} + git reset --hard ${{ env.BRANCH }} + + - name: Set env + run: echo "LATEST_COMMIT_ID=$(git ls-remote https://github.com/python/CPython.git $VERSION | head -c 8)" >> $GITHUB_ENV + + - name: Install Dependencies + run: sudo apt-get install gettext + + - name: Install uv + uses: astral-sh/setup-uv@v7 + + - name: Sync with CPython + run: make clone merge rm_cpython wrap + + - uses: actions/create-github-app-token@v2 + id: app-token + with: + app-id: ${{ secrets.APP_ID }} + private-key: ${{ secrets.APP_PRIVATE_KEY }} + + - name: Create Pull Request + id: cpr + uses: peter-evans/create-pull-request@v6 + with: + token: ${{ steps.app-token.outputs.token }} + commit-message: sync with cpython ${{ env.LATEST_COMMIT_ID }} + committer: GitHub + author: github-actions[bot] + base: ${{ env.VERSION }} + branch: ${{ env.BRANCH }} + delete-branch: false + title: "Sync with CPython ${{ env.VERSION }}" + body: | + Sync with CPython ${{ env.VERSION }} + draft: true + labels: | + sync-cpython + automation + + - name: Check outputs + run: | + echo "Pull Request Number - ${{ steps.cpr.outputs.pull-request-number }}" + echo "Pull Request URL - ${{ steps.cpr.outputs.pull-request-url }}" diff --git a/.github/workflows/summarize_progress.yml b/.github/workflows/summarize_progress.yml index 700519232e..814119c5cd 100644 --- a/.github/workflows/summarize_progress.yml +++ b/.github/workflows/summarize_progress.yml @@ -1,44 +1,44 @@ -name: summarize_progress - -on: - workflow_dispatch: - schedule: - - cron: '30 23 * * 5' - -jobs: - ci: - if: github.repository == 'python/python-docs-zh-tw' - runs-on: ubuntu-latest - permissions: - # Give the default GITHUB_TOKEN write permission to commit and push the - # added or changed files to the repository. - contents: write - steps: - - uses: actions/checkout@v5 - - - name: Install poetry - uses: abatilo/actions-poetry@v4 - - - name: Execute Check Process - run: | - chmod +x .scripts/summarize_progress.sh - .scripts/summarize_progress.sh - shell: bash - - - - name: Checkout wiki code - uses: actions/checkout@v5 - with: - repository: ${{github.repository}}.wiki - path: markdown - - - name: Copy content - run: | - cp .scripts/summarize_progress/result.md markdown/各檔案翻譯進度清單.md - shell: bash - - - name: Commit wiki code - uses: stefanzweifel/git-auto-commit-action@v7 - with: - commit_message: Weekly Update -- Summarize Progress - repository: markdown +name: summarize_progress + +on: + workflow_dispatch: + schedule: + - cron: '30 23 * * 5' + +jobs: + ci: + if: github.repository == 'python/python-docs-zh-tw' + runs-on: ubuntu-latest + permissions: + # Give the default GITHUB_TOKEN write permission to commit and push the + # added or changed files to the repository. + contents: write + steps: + - uses: actions/checkout@v5 + + - name: Install poetry + uses: abatilo/actions-poetry@v4 + + - name: Execute Check Process + run: | + chmod +x .scripts/summarize_progress.sh + .scripts/summarize_progress.sh + shell: bash + + + - name: Checkout wiki code + uses: actions/checkout@v5 + with: + repository: ${{github.repository}}.wiki + path: markdown + + - name: Copy content + run: | + cp .scripts/summarize_progress/result.md markdown/各檔案翻譯進度清單.md + shell: bash + + - name: Commit wiki code + uses: stefanzweifel/git-auto-commit-action@v7 + with: + commit_message: Weekly Update -- Summarize Progress + repository: markdown diff --git a/.scripts/summarize_progress/main.py b/.scripts/summarize_progress/main.py index b31624109c..dc10cb06ef 100644 --- a/.scripts/summarize_progress/main.py +++ b/.scripts/summarize_progress/main.py @@ -1,171 +1,171 @@ -import re -import polib -import glob -import requests - -from pathlib import Path - - -def get_open_issues_count() -> int: - ''' - Fetch GitHub API to get the number of OPEN ISSUES. - ''' - - url = f"https://api.github.com/search/issues?q=repo:python/python-docs-zh-tw+type:issue+state:open" - headers = { - "Accept": "application/vnd.github+json", - "X-GitHub-Api-Version": "2022-11-28", - } - r = requests.get(url=url, headers=headers) - result = r.json() - - return result["total_count"] - - -def get_github_issues() -> list: - ''' - Fetch GitHub API to collect the infomation of OPEN ISSUES, - including issue title and assignee. - - Steps: - 1. Fetch GitHub API and get open issue list - 2. Filter the issue if it have no "Translate" in the title - 3. Filter the issue if it have no correct filepath in the title - - Expected Output: - [ ((dirname, filename), assignee_id, issue_url), ... ] - ''' - NUMBER_OF_ISSUES = get_open_issues_count() - - url = f"https://api.github.com/search/issues?q=repo:python/python-docs-zh-tw+type:issue+state:open&per_page={NUMBER_OF_ISSUES}" - headers = { - "Accept": "application/vnd.github+json", - "X-GitHub-Api-Version": "2022-11-28", - } - r = requests.get(url=url, headers=headers) - result = r.json() - - result_list = [] - for issue in result["items"]: - assignee = issue["assignee"]["login"] if issue["assignee"] else "" - - title = issue["title"] - if "翻譯" not in title and "translate" not in title.lower(): - continue - - match = re.search( - "(?P[^\s`][a-zA-z-]+)/(?P[a-zA-Z0-9._-]+(.po)?)", title) - if not match: - continue - - dirname, filename = match.group('dirname', 'filename') - if not filename.endswith('.po'): - filename += '.po' - - result_list.append(((dirname, filename), assignee, issue["html_url"])) - - return result_list - - -def format_line_table_header() -> list: - return [f"|Filename|Progress (#string)|Issue|Assignee|\r\n", - f"|-------:|:-------|:----|:-------|\r\n"] - - -def format_line_po_issue_display(issue_link: str, issue_number: str, progress: float, create_issue_link: str) -> str: - if issue_link: - return f"[{issue_number}]({issue_link})" - if progress != 100.: - return f"[create issue]({create_issue_link})" - return "" - - -def format_line_po(filename: str, po_link: str, progress: str, num_entries: str, issue_display: str, assignee: str) -> str: - progress_display = f"{progress} %" - if progress == 100: - progress_display = "✅" - return f"|[`{filename}`]({po_link})|{progress_display} ({num_entries:,})|{issue_display}|{assignee}|\r\n" - - -if __name__ == "__main__": - issue_list = get_github_issues() - - ''' - Search all the po file in the directory, - and record the translation progress of each files. - ''' - BASE_DIR = Path("../") - summary = {} - for filepath in glob.glob(str(BASE_DIR / "**/*.po"), recursive=True): - path = Path(filepath) - filename = path.name - dirname = path.parent.name if path.parent.name != BASE_DIR.name else 'root' - po = polib.pofile(filepath) - - num_entries = len(list(filter(lambda e: not e.obsolete, po))) - num_translated = len(po.translated_entries()) - summary.setdefault(dirname, {})[filename] = { - 'po_info': { - 'num_entries': num_entries, - 'num_translated': num_translated, - 'progress': round(num_translated / num_entries * 100, 2), - }, - 'issue': '', - 'assignee': '', - } - - ''' - Unpack the open issue list, and add assignee after the progress - ''' - for (category, filename), assignee, issue_url in issue_list: - try: - summary[category][filename]['issue'] = issue_url - summary[category][filename]['assignee'] = assignee - except KeyError: - pass - - ''' - Format the lines that will be written into the markdown file, - also sort the directory name and file name. - ''' - writeliner = [] - summary_sorted = dict(sorted(summary.items())) - total_entries, total_translated = 0, 0 - for dirname, filedict in summary_sorted.items(): - dir_total_entries, dir_total_translated = 0, 0 - lines = [] - filedict_sorted = dict(sorted(filedict.items())) - for filename, filedata in filedict_sorted.items(): - file_path = f"{dirname}/{filename}" if dirname else filename - po_link = f"https://github.com/python/python-docs-zh-tw/tree/3.14/{file_path}" - issue_link = filedata['issue'] - issue_number = f"#{issue_link.split('/')[-1]}" - create_issue_link = f"https://github.com/python/python-docs-zh-tw/issues/new?title=Translate%20`{file_path}`" - issue_display = format_line_po_issue_display(issue_link, issue_number, filedata['po_info']['progress'], create_issue_link) - line_po = format_line_po( - filename, - po_link, - filedata['po_info']['progress'], - filedata['po_info']['num_entries'], - issue_display, - filedata['assignee'], - ) - lines.append(line_po) - - dir_total_entries += filedata['po_info']['num_entries'] - dir_total_translated += filedata['po_info']['num_translated'] - - dir_progress = round(dir_total_translated / dir_total_entries * 100, 2) - writeliner.append(f"## {dirname} ({dir_progress}%)\r\n") - writeliner.extend(format_line_table_header()) - writeliner.extend(lines) - - total_entries += dir_total_entries - total_translated += dir_total_translated - - overall_progress = round(total_translated / total_entries * 100, 2) - title = f"## Overall Progress: {overall_progress}% ({total_translated:,} / {total_entries:,})\r\n" - writeliner = [title] + writeliner - - with open(f"summarize_progress/result.md", "w") as file: - file.writelines(writeliner) +import re +import polib +import glob +import requests + +from pathlib import Path + + +def get_open_issues_count() -> int: + ''' + Fetch GitHub API to get the number of OPEN ISSUES. + ''' + + url = f"https://api.github.com/search/issues?q=repo:python/python-docs-zh-tw+type:issue+state:open" + headers = { + "Accept": "application/vnd.github+json", + "X-GitHub-Api-Version": "2022-11-28", + } + r = requests.get(url=url, headers=headers) + result = r.json() + + return result["total_count"] + + +def get_github_issues() -> list: + ''' + Fetch GitHub API to collect the infomation of OPEN ISSUES, + including issue title and assignee. + + Steps: + 1. Fetch GitHub API and get open issue list + 2. Filter the issue if it have no "Translate" in the title + 3. Filter the issue if it have no correct filepath in the title + + Expected Output: + [ ((dirname, filename), assignee_id, issue_url), ... ] + ''' + NUMBER_OF_ISSUES = get_open_issues_count() + + url = f"https://api.github.com/search/issues?q=repo:python/python-docs-zh-tw+type:issue+state:open&per_page={NUMBER_OF_ISSUES}" + headers = { + "Accept": "application/vnd.github+json", + "X-GitHub-Api-Version": "2022-11-28", + } + r = requests.get(url=url, headers=headers) + result = r.json() + + result_list = [] + for issue in result["items"]: + assignee = issue["assignee"]["login"] if issue["assignee"] else "" + + title = issue["title"] + if "翻譯" not in title and "translate" not in title.lower(): + continue + + match = re.search( + "(?P[^\s`][a-zA-z-]+)/(?P[a-zA-Z0-9._-]+(.po)?)", title) + if not match: + continue + + dirname, filename = match.group('dirname', 'filename') + if not filename.endswith('.po'): + filename += '.po' + + result_list.append(((dirname, filename), assignee, issue["html_url"])) + + return result_list + + +def format_line_table_header() -> list: + return [f"|Filename|Progress (#string)|Issue|Assignee|\r\n", + f"|-------:|:-------|:----|:-------|\r\n"] + + +def format_line_po_issue_display(issue_link: str, issue_number: str, progress: float, create_issue_link: str) -> str: + if issue_link: + return f"[{issue_number}]({issue_link})" + if progress != 100.: + return f"[create issue]({create_issue_link})" + return "" + + +def format_line_po(filename: str, po_link: str, progress: str, num_entries: str, issue_display: str, assignee: str) -> str: + progress_display = f"{progress} %" + if progress == 100: + progress_display = "✅" + return f"|[`{filename}`]({po_link})|{progress_display} ({num_entries:,})|{issue_display}|{assignee}|\r\n" + + +if __name__ == "__main__": + issue_list = get_github_issues() + + ''' + Search all the po file in the directory, + and record the translation progress of each files. + ''' + BASE_DIR = Path("../") + summary = {} + for filepath in glob.glob(str(BASE_DIR / "**/*.po"), recursive=True): + path = Path(filepath) + filename = path.name + dirname = path.parent.name if path.parent.name != BASE_DIR.name else 'root' + po = polib.pofile(filepath) + + num_entries = len(list(filter(lambda e: not e.obsolete, po))) + num_translated = len(po.translated_entries()) + summary.setdefault(dirname, {})[filename] = { + 'po_info': { + 'num_entries': num_entries, + 'num_translated': num_translated, + 'progress': round(num_translated / num_entries * 100, 2), + }, + 'issue': '', + 'assignee': '', + } + + ''' + Unpack the open issue list, and add assignee after the progress + ''' + for (category, filename), assignee, issue_url in issue_list: + try: + summary[category][filename]['issue'] = issue_url + summary[category][filename]['assignee'] = assignee + except KeyError: + pass + + ''' + Format the lines that will be written into the markdown file, + also sort the directory name and file name. + ''' + writeliner = [] + summary_sorted = dict(sorted(summary.items())) + total_entries, total_translated = 0, 0 + for dirname, filedict in summary_sorted.items(): + dir_total_entries, dir_total_translated = 0, 0 + lines = [] + filedict_sorted = dict(sorted(filedict.items())) + for filename, filedata in filedict_sorted.items(): + file_path = f"{dirname}/{filename}" if dirname else filename + po_link = f"https://github.com/python/python-docs-zh-tw/tree/3.14/{file_path}" + issue_link = filedata['issue'] + issue_number = f"#{issue_link.split('/')[-1]}" + create_issue_link = f"https://github.com/python/python-docs-zh-tw/issues/new?title=Translate%20`{file_path}`" + issue_display = format_line_po_issue_display(issue_link, issue_number, filedata['po_info']['progress'], create_issue_link) + line_po = format_line_po( + filename, + po_link, + filedata['po_info']['progress'], + filedata['po_info']['num_entries'], + issue_display, + filedata['assignee'], + ) + lines.append(line_po) + + dir_total_entries += filedata['po_info']['num_entries'] + dir_total_translated += filedata['po_info']['num_translated'] + + dir_progress = round(dir_total_translated / dir_total_entries * 100, 2) + writeliner.append(f"## {dirname} ({dir_progress}%)\r\n") + writeliner.extend(format_line_table_header()) + writeliner.extend(lines) + + total_entries += dir_total_entries + total_translated += dir_total_translated + + overall_progress = round(total_translated / total_entries * 100, 2) + title = f"## Overall Progress: {overall_progress}% ({total_translated:,} / {total_entries:,})\r\n" + writeliner = [title] + writeliner + + with open(f"summarize_progress/result.md", "w") as file: + file.writelines(writeliner) diff --git a/Makefile b/Makefile index 68604f2633..981a739001 100644 --- a/Makefile +++ b/Makefile @@ -1,165 +1,165 @@ -# Makefile for Chinese (Taiwan) Python Documentation -# -# Here is what you can do: -# -# - make all # Automatically build an html local version -# - make build # To build a single .po file -# - make todo # To list remaining tasks -# - make merge # To merge pot from upstream -# - make fuzzy # To find fuzzy strings -# - make progress # To compute current progression -# - make upgrade_venv # To upgrade the venv that compiles the doc -# -# Modes are: autobuild-stable, autobuild-dev, and autobuild-html, -# documented in gen/src/3.6/Doc/Makefile as we're only delegating the -# real work to the Python Doc Makefile. -# -# Credits: Python Documentation French Translation Team (https://github.com/python/python-docs-fr) - -.DEFAULT_GOAL := help # Sets default action to be help - -define PRINT_HELP_PYSCRIPT # start of Python section -import re, sys - -output = [] -# Loop through the lines in this file -for line in sys.stdin: - # if the line has a command and a comment start with - # two pound signs, add it to the output - match = re.match(r'^([a-zA-Z_-]+):.*?## (.*)$$', line) - if match: - target, help = match.groups() - output.append("%-10s %s" % (target, help)) -# Sort the output in alphanumeric order -output.sort() -# Print the help result -print('\n'.join(output)) -endef -export PRINT_HELP_PYSCRIPT # End of python section - -CPYTHON_CLONE := ../cpython -VERSION := $(or $(VERSION), 3.14) -SPHINX_CONF := $(CPYTHON_CLONE)/Doc/conf.py -LANGUAGE := zh_TW -LC_MESSAGES := $(CPYTHON_CLONE)/Doc/locales/$(LANGUAGE)/LC_MESSAGES -VENV := ~/.venvs/python-docs-i18n/ -MODE := $(or $(MODE), autobuild-dev-html) -JOBS := $(or $(JOBS), auto) - -.PHONY: all -all: prepare_deps ## Automatically build an html local version - for dirname in $$(find . -name '*.po' | xargs -n1 dirname | sort -u | grep -v '^\.$$'); do mkdir -p $(LC_MESSAGES)/$$dirname; done - for file in *.po */*.po; do ln -f $$file $(LC_MESSAGES)/$$file; done - . $(VENV)/bin/activate; $(MAKE) -C $(CPYTHON_CLONE)/Doc/ SPHINXOPTS='-j$(JOBS) -D locale_dirs=locales -D language=$(LANGUAGE) -D gettext_compact=0' $(MODE) - -.PHONY: build -build: prepare_deps ## Automatically build an html local version for a single file - @$(eval target=$(filter-out $@,$(MAKECMDGOALS))) - @if [ -z $(target) ]; then \ - echo "\x1B[1;31m""Please provide a file argument.""\x1B[m"; \ - exit 1; \ - fi - @if [ "$(suffix $(target))" != ".po" ]; then \ - echo "\x1B[1;31m""Incorrect file extension. Only '.po' files are allowed.""\x1B[m"; \ - exit 1; \ - fi - @if [[ ! -f "$(target)" ]] ; then \ - echo "\x1B[1;31m""ERROR: $(target) not exist.""\x1B[m"; \ - exit 1; \ - fi - - @$(eval dir=`echo $(target) | xargs -n1 dirname`) ## Get dir - @mkdir -p $(LC_MESSAGES)/$(dir) - @ln -f ./$(target) $(LC_MESSAGES)/$(target) - - @. $(VENV)/bin/activate; $(MAKE) -C $(CPYTHON_CLONE)/Doc/ SPHINXOPTS='-j$(JOBS) -D language=$(LANGUAGE) -D locale_dirs=locales -D gettext_compact=0' SOURCES='$(basename $(target)).rst' html - - -help: - @python3 -c "$$PRINT_HELP_PYSCRIPT" < $(MAKEFILE_LIST) - -.PHONY: prepare_deps -prepare_deps: $(VENV)/bin/sphinx-build $(VENV)/bin/blurb upgrade_venv prepare_cpython ## Prepare dependencies - -.PHONY: prepare_cpython -prepare_cpython: ## Prepare CPython clone at `../cpython/`. - git clone --depth 1 --no-single-branch https://github.com/python/cpython.git $(CPYTHON_CLONE) || echo "cpython exists" - cd $(CPYTHON_CLONE) && git checkout $(VERSION) && git pull origin $(VERSION) - mkdir -p $(LC_MESSAGES) - - -$(VENV)/bin/activate: - uv venv $(VENV) - -$(VENV)/bin/sphinx-build: $(VENV)/bin/activate - . $(VENV)/bin/activate; uv pip install sphinx python-docs-theme - -$(VENV)/bin/sphinx-lint: $(VENV)/bin/activate - . $(VENV)/bin/activate; uv pip install sphinx-lint - -$(VENV)/bin/blurb: $(VENV)/bin/activate - . $(VENV)/bin/activate; uv pip install blurb - - -.PHONY: upgrade_venv -upgrade_venv: $(VENV)/bin/activate ## Upgrade the venv that compiles the doc - @. $(VENV)/bin/activate; uv pip install -q --upgrade sphinx python-docs-theme blurb sphinx-lint - - -.PHONY: progress -progress: ## Compute current progression - @python3 -c 'import sys; print("{:.1%}".format(int(sys.argv[1]) / int(sys.argv[2])))' \ - $(shell msgcat *.po */*.po | msgattrib --translated | grep -c '^msgid') \ - $(shell msgcat *.po */*.po | grep -c '^msgid') - - -.PHONY: todo -todo: ## List remaining tasks - for file in *.po */*.po; do echo $$(msgattrib --untranslated $$file | grep ^msgid | sed 1d | wc -l ) $$file; done | grep -v ^0 | sort -gr - - -.PHONY: merge -merge: prepare_deps ## To merge pot from upstream - (cd $(CPYTHON_CLONE)/Doc; rm -f build/NEWS) - (cd $(CPYTHON_CLONE)/Doc; $(VENV)/bin/sphinx-build -Q -b gettext -D gettext_compact=0 . locales/pot/) - find $(CPYTHON_CLONE)/Doc/locales/pot/ -name '*.pot' |\ - while read -r POT;\ - do\ - PO="./$$(echo "$$POT" | sed "s#$(CPYTHON_CLONE)/Doc/locales/pot/##; s#\.pot\$$#.po#")";\ - mkdir -p "$$(dirname "$$PO")";\ - if [ -f "$$PO" ];\ - then\ - msgmerge --lang=$(LANGUAGE) --backup=off --force-po -U "$$PO" "$$POT";\ - else\ - msgcat --lang=$(LANGUAGE) -o "$$PO" "$$POT";\ - fi\ - done - - -.PHONY: update_txconfig -update_txconfig: - curl -L https://rawgit.com/python-doc-ja/cpython-doc-catalog/catalog-$(VERSION)/Doc/locales/.tx/config |\ - grep --invert-match '^file_filter = *' |\ - sed -e 's/source_file = pot\/\(.*\)\.pot/trans.zh_TW = \1.po/' |\ - sed -n 'w .tx/config' - - -.PHONY: fuzzy -fuzzy: ## Find fuzzy strings - for file in *.po */*.po; do echo $$(msgattrib --only-fuzzy --no-obsolete "$$file" | grep -c '#, fuzzy') $$file; done | grep -v ^0 | sort -gr - -.PHONY: rm_cpython -rm_cpython: ## Remove cloned cpython repo - rm -rf $(CPYTHON_CLONE) - -.PHONY: lint -lint: $(VENV)/bin/sphinx-lint ## Run sphinx-lint - $(VENV)/bin/sphinx-lint --enable default-role - -.PHONY: wrap -wrap: ## Run powrap on modified po files - uvx powrap --modified - -# This allows us to accept extra arguments (by doing nothing when we get a job that doesn't match, rather than throwing an error) -%: - @: +# Makefile for Chinese (Taiwan) Python Documentation +# +# Here is what you can do: +# +# - make all # Automatically build an html local version +# - make build # To build a single .po file +# - make todo # To list remaining tasks +# - make merge # To merge pot from upstream +# - make fuzzy # To find fuzzy strings +# - make progress # To compute current progression +# - make upgrade_venv # To upgrade the venv that compiles the doc +# +# Modes are: autobuild-stable, autobuild-dev, and autobuild-html, +# documented in gen/src/3.6/Doc/Makefile as we're only delegating the +# real work to the Python Doc Makefile. +# +# Credits: Python Documentation French Translation Team (https://github.com/python/python-docs-fr) + +.DEFAULT_GOAL := help # Sets default action to be help + +define PRINT_HELP_PYSCRIPT # start of Python section +import re, sys + +output = [] +# Loop through the lines in this file +for line in sys.stdin: + # if the line has a command and a comment start with + # two pound signs, add it to the output + match = re.match(r'^([a-zA-Z_-]+):.*?## (.*)$$', line) + if match: + target, help = match.groups() + output.append("%-10s %s" % (target, help)) +# Sort the output in alphanumeric order +output.sort() +# Print the help result +print('\n'.join(output)) +endef +export PRINT_HELP_PYSCRIPT # End of python section + +CPYTHON_CLONE := ../cpython +VERSION := $(or $(VERSION), 3.14) +SPHINX_CONF := $(CPYTHON_CLONE)/Doc/conf.py +LANGUAGE := zh_TW +LC_MESSAGES := $(CPYTHON_CLONE)/Doc/locales/$(LANGUAGE)/LC_MESSAGES +VENV := ~/.venvs/python-docs-i18n/ +MODE := $(or $(MODE), autobuild-dev-html) +JOBS := $(or $(JOBS), auto) + +.PHONY: all +all: prepare_deps ## Automatically build an html local version + for dirname in $$(find . -name '*.po' | xargs -n1 dirname | sort -u | grep -v '^\.$$'); do mkdir -p $(LC_MESSAGES)/$$dirname; done + for file in *.po */*.po; do ln -f $$file $(LC_MESSAGES)/$$file; done + . $(VENV)/bin/activate; $(MAKE) -C $(CPYTHON_CLONE)/Doc/ SPHINXOPTS='-j$(JOBS) -D locale_dirs=locales -D language=$(LANGUAGE) -D gettext_compact=0' $(MODE) + +.PHONY: build +build: prepare_deps ## Automatically build an html local version for a single file + @$(eval target=$(filter-out $@,$(MAKECMDGOALS))) + @if [ -z $(target) ]; then \ + echo "\x1B[1;31m""Please provide a file argument.""\x1B[m"; \ + exit 1; \ + fi + @if [ "$(suffix $(target))" != ".po" ]; then \ + echo "\x1B[1;31m""Incorrect file extension. Only '.po' files are allowed.""\x1B[m"; \ + exit 1; \ + fi + @if [[ ! -f "$(target)" ]] ; then \ + echo "\x1B[1;31m""ERROR: $(target) not exist.""\x1B[m"; \ + exit 1; \ + fi + + @$(eval dir=`echo $(target) | xargs -n1 dirname`) ## Get dir + @mkdir -p $(LC_MESSAGES)/$(dir) + @ln -f ./$(target) $(LC_MESSAGES)/$(target) + + @. $(VENV)/bin/activate; $(MAKE) -C $(CPYTHON_CLONE)/Doc/ SPHINXOPTS='-j$(JOBS) -D language=$(LANGUAGE) -D locale_dirs=locales -D gettext_compact=0' SOURCES='$(basename $(target)).rst' html + + +help: + @python3 -c "$$PRINT_HELP_PYSCRIPT" < $(MAKEFILE_LIST) + +.PHONY: prepare_deps +prepare_deps: $(VENV)/bin/sphinx-build $(VENV)/bin/blurb upgrade_venv prepare_cpython ## Prepare dependencies + +.PHONY: prepare_cpython +prepare_cpython: ## Prepare CPython clone at `../cpython/`. + git clone --depth 1 --no-single-branch https://github.com/python/cpython.git $(CPYTHON_CLONE) || echo "cpython exists" + cd $(CPYTHON_CLONE) && git checkout $(VERSION) && git pull origin $(VERSION) + mkdir -p $(LC_MESSAGES) + + +$(VENV)/bin/activate: + uv venv $(VENV) + +$(VENV)/bin/sphinx-build: $(VENV)/bin/activate + . $(VENV)/bin/activate; uv pip install sphinx python-docs-theme + +$(VENV)/bin/sphinx-lint: $(VENV)/bin/activate + . $(VENV)/bin/activate; uv pip install sphinx-lint + +$(VENV)/bin/blurb: $(VENV)/bin/activate + . $(VENV)/bin/activate; uv pip install blurb + + +.PHONY: upgrade_venv +upgrade_venv: $(VENV)/bin/activate ## Upgrade the venv that compiles the doc + @. $(VENV)/bin/activate; uv pip install -q --upgrade sphinx python-docs-theme blurb sphinx-lint + + +.PHONY: progress +progress: ## Compute current progression + @python3 -c 'import sys; print("{:.1%}".format(int(sys.argv[1]) / int(sys.argv[2])))' \ + $(shell msgcat *.po */*.po | msgattrib --translated | grep -c '^msgid') \ + $(shell msgcat *.po */*.po | grep -c '^msgid') + + +.PHONY: todo +todo: ## List remaining tasks + for file in *.po */*.po; do echo $$(msgattrib --untranslated $$file | grep ^msgid | sed 1d | wc -l ) $$file; done | grep -v ^0 | sort -gr + + +.PHONY: merge +merge: prepare_deps ## To merge pot from upstream + (cd $(CPYTHON_CLONE)/Doc; rm -f build/NEWS) + (cd $(CPYTHON_CLONE)/Doc; $(VENV)/bin/sphinx-build -Q -b gettext -D gettext_compact=0 . locales/pot/) + find $(CPYTHON_CLONE)/Doc/locales/pot/ -name '*.pot' |\ + while read -r POT;\ + do\ + PO="./$$(echo "$$POT" | sed "s#$(CPYTHON_CLONE)/Doc/locales/pot/##; s#\.pot\$$#.po#")";\ + mkdir -p "$$(dirname "$$PO")";\ + if [ -f "$$PO" ];\ + then\ + msgmerge --lang=$(LANGUAGE) --backup=off --force-po -U "$$PO" "$$POT";\ + else\ + msgcat --lang=$(LANGUAGE) -o "$$PO" "$$POT";\ + fi\ + done + + +.PHONY: update_txconfig +update_txconfig: + curl -L https://rawgit.com/python-doc-ja/cpython-doc-catalog/catalog-$(VERSION)/Doc/locales/.tx/config |\ + grep --invert-match '^file_filter = *' |\ + sed -e 's/source_file = pot\/\(.*\)\.pot/trans.zh_TW = \1.po/' |\ + sed -n 'w .tx/config' + + +.PHONY: fuzzy +fuzzy: ## Find fuzzy strings + for file in *.po */*.po; do echo $$(msgattrib --only-fuzzy --no-obsolete "$$file" | grep -c '#, fuzzy') $$file; done | grep -v ^0 | sort -gr + +.PHONY: rm_cpython +rm_cpython: ## Remove cloned cpython repo + rm -rf $(CPYTHON_CLONE) + +.PHONY: lint +lint: $(VENV)/bin/sphinx-lint ## Run sphinx-lint + $(VENV)/bin/sphinx-lint --enable default-role + +.PHONY: wrap +wrap: ## Run powrap on modified po files + uvx powrap --modified + +# This allows us to accept extra arguments (by doing nothing when we get a job that doesn't match, rather than throwing an error) +%: + @: diff --git a/README.rst b/README.rst index 14ff6f6038..a06fb301af 100644 --- a/README.rst +++ b/README.rst @@ -1,477 +1,477 @@ -======================================= -Python 官方說明文件臺灣繁體中文翻譯計畫 -======================================= - -.. image:: https://badgen.net/badge/chat/on%20Discord/blue - :target: https://discord.gg/44XheGXhWH - :alt: Join Chat on Discord - -這是 Python 3.14 官方說明文件的臺灣繁體中文（zh_TW）翻譯。 - -翻譯之前，請務必詳讀並同意\ `授權與 License`_。參與方式請參考\ `參與翻譯`_。 - -你可以在 https://python.github.io/python-docs-zh-tw/ 瀏覽目前翻譯的成果。 - -想問問題、認識翻譯同好，歡迎加入 Discord 頻道 `discord.gg/44XheGXhWH`_ - -.. _discord.gg/44XheGXhWH: https://discord.gg/44XheGXhWH - -.. contents:: **目錄 Table of Contents** - -授權與 License -============== - -以下為 Documentation Contribution Agreement，說明文件貢獻協議，請在貢獻以前\ -務必詳讀以下內容。原文後附有中文翻譯，但譯文不保證完全正確，請以原文為準。 - -Documentation Contribution Agreement ------------------------------------- - -NOTE REGARDING THE LICENSE FOR TRANSLATIONS: Python's documentation is -maintained using a global network of volunteers. By posting this -project on Transifex, GitHub, and other public places, and inviting -you to participate, we are proposing an agreement that you will -provide your improvements to Python's documentation or the translation -of Python's documentation for the PSF's use under the CC0 license -(available at -https://creativecommons.org/publicdomain/zero/1.0/legalcode). In -return, you may publicly claim credit for the portion of the -translation you contributed and if your translation is accepted by the -PSF, you may (but are not required to) submit a patch including an -appropriate annotation in the Misc/ACKS or TRANSLATORS file. Although -nothing in this Documentation Contribution Agreement obligates the PSF -to incorporate your textual contribution, your participation in the -Python community is welcomed and appreciated. - -You signify acceptance of this agreement by submitting your work to -the PSF for inclusion in the documentation. - -中文翻譯 -~~~~~~~~ - -請注意此予翻譯專案的授權：Python 的說明文件是以全球的志工社群來維護。透過張貼\ -此專案在 Transifex、GitHub 以及其他公眾場合，以及邀請你參與，我們向你提出一個\ -協議：你必須將你對於 Python 說明文件或是 Python 說明文件翻譯的貢獻以 CC0\ -（請參考 https://creativecommons.org/publicdomain/zero/1.0/legalcode/ -）的方式授權給 PSF 使用。你可以公開地聲明你所貢獻翻譯的部分，並且如果你的翻譯被 PSF -採用，你可以（但並不須要）送出一個修改，其包含在 Misc/ACKS 或是 TRANSLATORS -檔案裡增加合適的注釋。雖然這個說明文件貢獻協議並沒有說明 PSF 有義務納入你的\ -文本貢獻，你在 Python 社群的參與是受歡迎且受感激的。 - -你在對 PSF 送出說明文件貢獻的同時，即表示同意上述的協議。 - - -參與翻譯 -======== - -關於 po (Portable Object) 檔 ------------------------------ - -此為所需翻譯的文字檔，副檔名為 ``.po``，不同語系就會有一個 po 檔。主要內容為翻譯的參考原始字串 (*msgid*)，\ -及需要填入的翻譯字串 (*msgstr*)。有時你會看到 ``#, fuzzy`` 的註記，它代表此翻譯字串需要校閱。 - -翻譯流程 ------------- - -**請注意**: 以下基於 ``make`` 的便捷指令僅能運作於 Unix 系統上（無法使用並不影響主要翻譯流程），\ -其他作業系統的使用者在翻譯後可考慮改於 `GitHub Codespace `_ 上呼叫 ``make`` 指令。 -（參考 `project wiki 頁面 `_） - -事先需要有 -~~~~~~~~~~ - -- 一個 `GitHub 帳號 `_ -- `安裝好 git `_\ （Windows - 上請參考 https://gitforwindows.org/） -- 一個 ``.po`` 檔的編輯器。推薦使用 `Poedit `_，若熟悉 po 檔用一般文字編輯器亦可。 -- 參考 `uv Installation `_ 安裝 uv，以便在本機端預覽翻譯成果。 -- macOS 的使用者還需要先利用 `homebrew `_ 安裝 gettext，屆時 Sphinx 會使用到。 - - .. code-block:: bash - - brew install gettext - brew link gettext --force - -- 安裝 pre-commit 自動在 commit 時檢查 ``.po`` 檔格式。 - - .. code-block:: bash - - pip install pre-commit - pre-commit install - -在進行任何動作以前，你必須在 GitHub 上 fork 此專案（按下右上角的 ``Fork`` -按鈕），這樣會把整個專案複製一份到你的 GitHub 帳號底下，你可以對這個 fork -進行修改。 - -第一次貢獻以前（還沒有 clone 過） -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -請在 terminal 裡依照以下步驟： - -.. code-block:: bash - - # 用 git clone 將你的 fork 下載到本機端 - git clone git@github.com:<你的 GitHub 帳號>/python-docs-zh-tw.git - - # 進入 clone 下來的資料夾裡： - cd python-docs-zh-tw/ - - # 將 python/python-docs-zh-tw 設為 upstream remote - git remote add upstream https://github.com/python/python-docs-zh-tw.git - -每一次翻譯時 -~~~~~~~~~~~~ - -請遵照以下步驟（`GitHub Flow`_）： - -.. _GitHub Flow: https://guides.github.com/introduction/flow/ -.. _GitHub PR 文件: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request#creating-the-pull-request - -首先，`新增一個 issue `_\ -，如：「翻譯 library/math.po」，讓大家知道你正在翻譯這個檔案。待翻譯文件清單請參考\ -`此頁面 `_。 - -接著在 terminal 裡按照以下步驟： - -1. 基於最新版本的 ``upstream/3.14`` 開啟一個 branch，現在假設我們想要翻譯 library/math.po \ - 所以把這個 branch 叫做 ``library/math``： - - .. code-block:: bash - - git fetch upstream - git checkout -b library/math upstream/3.14 - -2. 接著就可以開始翻譯（翻譯時可參考\ `翻譯守則`_），你可以手動開啟 Poedit 應用程式再選 \ - library/math.po 檔案打開 - -3. 填入中譯內容並存檔以後，執行以下列指令編譯輸出完整文件，以確保你的修改沒有 reST 的語法錯誤或警告： - - - .. code-block:: bash - - make all - - - 或者只想快速檢查是否有 reST 語法錯誤： - - .. code-block:: bash - - make lint - - - 確保輸出中沒有任何警告訊息。 - - 在 ``make all`` 後，可以使用 ``make build`` 來只對單一 po 檔進行編譯，可以節省較多的時間： - - .. code-block:: bash - - make build library/math.po - - 如果你還沒有執行\ `維護、預覽`_\ 的 clone CPython 的動作，此指令會自動幫你 clone CPython，\ - 並且會使用 Sphinx 幫你檢查 reST 語法錯誤，我們盡量保持沒有 warning \ - 的狀態，因此如果有出現 warning 的話請修復它。另外也記得檢查是否符合\ - `翻譯守則`_ - -4. 輸出的文件會被放置在你的本地端 CPython clone（見\ `維護、預覽`_\ 段落的圖示）\ - 底下的 ``Doc/build/html``，可以使用 `http.server` 或其他靜態網頁伺服器即可以預覽成果。 - - .. code-block:: bash - - cd ../cpython/Doc/build/html - python3 -m http.server - - 你也可以執行下列指令請瀏覽器打開編譯出來的文件\ - 以確認整份文件的語意通暢（翻譯別的檔案時將 library/math 換成別的檔名）： - - .. code-block:: bash - - open ../cpython/Doc/build/html/library/math.html - -5. 檢查完畢後，即可以將你的翻譯 commit 起來，請使用明確的 commit message： - - .. code-block:: bash - - git add library/math.po - git commit -m "Working on library/math.po" - -6. 將你的修改 push 到你的 GitHub clone 上。為了簡單，我們可以用 ``origin HEAD`` - 來告訴 git 我們將修改 push 到 origin，branch 則和本機端的 branch 名稱一樣： - - .. code-block:: bash - - git push origin HEAD - -7. 這時候你就可以打開一個 pull request 了：請打開\ `此專案的 GitHub 頁面 `_，\ - 你會看到一個「Compare & Pull Request」按鈕，按下它就可以對此專案發送一個 pull request（參考 `GitHub PR 文件`_）。 - -8. 如果有人在 GitHub 上 review 了你的 pull request，並且你想要修改你的內容，\ - 那麼（如果你切換到了別的 branch 上）你要先切換回到你的 branch 上： - - .. code-block:: bash - - git checkout library/math - - 接著修改你要修正的問題，並再次 commit、push： - - .. code-block:: bash - - git add library/math.po - git commit -m "fix(library/math): resolve review comments" - git push origin HEAD - -這整個流程裡有幾件事情值得注意： - -- 從 upstream（我們的主要 GitHub repo）做 fetch 的動作 -- 對 origin（你的 fork）做 push -- 永遠不對 ``3.14`` branch 進行修改，請保持讓這個 branch 唯讀，可以避免掉很多問題。 - -要翻譯哪些東西 --------------- - -主要是填入翻譯字串 (*msgstr*) 以及更新有標記為 ``#, fuzzy`` 的字串。 - -其中最簡單的貢獻方式就是更新 *fuzzy entries*，讓曾經翻譯的內容保持與最新版本的文件 -同步。請參考\ `尋找有翻譯過但需校閱的 fuzzy entries`_ 段落。 - -此外，目前的目標為完成 **Tutorial** 的翻譯，因此在 ``tutorial/`` 底下的所有 -po 檔皆為首要的翻譯對象。你也可以幫忙校對已經翻譯過的內容。 - - -翻譯守則 -======== - -#. 譯文應兼顧前後文大意，在翻譯一份文件前請務必熟讀該文件的原文。 - -#. 中文句使用全形標點符號；英文句維持半形的標點符號。 - - 例如：「」（）、，。 - - 例如：Python is supported by Python Software Foundation (PSF). - -#. 中英文交雜時要插入空白；符號英文間不用。 - - 例如：使用 CPU 運算、使用「CPU」運算 - -#. 專有名詞應該參考\ `術語表 Glossary`_ 裡的翻譯方式。 - -#. 專有名詞可以選擇不翻譯。 - - 例如：CPU、Unicode - -#. 在翻譯名稱不常用或不確定的情形，宜用括號註解或直接保留原文。單頁只要首次\ - 出現有註解即可。 - - 例如：正規表示式 (regular expression) - - 例如：Network News Transfer Protocol、Portable Network Graphics - （可攜式網路圖形） - -#. 務必保留 reStructuredText 格式（如：超連結名稱） - -#. po 檔單行不應超過 79 字元寬度（Poedit 會處理，但也可以使用 `powrap - `_ - 來確保格式） - -#. 高頻詞保留原文。因為翻譯後不一定能較好理解市面上 Python 的文章。 這些高頻詞\ - 在 Glossary 中的譯文仍保持原文，並加註市面上的翻譯。 - - 例如：``int``、``float``、``str``、``bytes``、``list``、``tuple``、 - ``dict``、``set``、``iterator``、``generator``、``iterable``、 - ``pickle`` - - -括號的使用 ----------- - -如果括號中的文字包含中文，使用全形括號；如果括號中只有英文，使用半形括號並\ -比照英文的形式加入前後文的空白。 - -例如： - -- list（串列）是 Python 中很常見的資料型別。 -- 在本情況使用 ``zip(*[iter(x)]*n)`` 是很常見的情況（Python 慣例）。 -- 在超文件標示語言 (HTML) 中應注意跳脫符號。 - -reST 語法注意事項 ---------------------- - -- ``:xxx:`...``` 即為 reST 的語法，應該在譯文中保留。 - - 例如： - - .. code-block:: rst - - Avoids tests using :func:`type` or :func:`isinstance`. - - 翻譯為 - - .. code-block:: rst - - 避免使用 :func:`type` 或 :func:`isinstance` 進行測試。 - -- reST 諸多語法需要保留前後的空白。在中文裡，該空白可以用 :literal:`\\\\\ \ ` \ - 來取代，製造一個沒有寬度的分隔符號。 - - 例如當 ``:ref:`detail-instruction`` 部分會被編譯為中文時： - - .. code-block:: rst - - For more information, please see :ref:`detail-instruction`. - - 翻譯為 - - .. code-block:: rst - - 更多資訊請參考\\ :ref:`detail-instruction`。 - -- 超連結語法該要在譯文中保留原字串。 - - 例如： - - .. code-block:: rst - - `Documentation bugs`_ on the Python issue tracker - - 應翻譯為 - - .. code-block:: rst - - Python issue tracker 上\\ `文件的錯誤 `_ - - 才能正確顯示為「Python issue tracker 上\ `文件的錯誤 <#>`_」，並帶有正確連結且與\ - 前文才不會有多餘的空白。 - -- 舉例中有程式碼時，前一段經常為 ``::`` 結尾，此記號\ `具有特殊意義 - `_，\ - 除了該段落結尾為冒號外，也代表下段縮排為程式碼。翻譯時應改為 ``： ::``\ - （參考 `#568 `_）。 - - 例如： - - .. code-block:: rst - - Here is a code example:: - - import sys - print(sys.version) - - 程式碼並不會出現在 po 檔之中，故在 po 檔中會顯示為 - - .. code-block:: rst - - Here is a code example:: - - 此時翻譯應為： - - .. code-block:: rst - - 以下是個程式範例： :: - -術語表 Glossary -=============== - -為了讓翻譯保持統一，我們整理了一份\ -`術語列表 `_\ -如果翻譯過程中你覺得需要術語列表有所缺漏，請至 `Discussion \ -`_ 開啟新的討論補充術語。\ -新增的術語，將會於每次 Sprint 中共同討論是否合併進術語列表。 - - - -問題回報與討論 -============== - -如果有需要共同討論的問題，請開設一個新的 Issue_。如果是翻譯上遇到困難需要\ -幫助，則可以使用 Discord_。 - -.. _Issue: https://github.com/python/python-docs-zh-tw/issues -.. _Discord: https://discord.gg/44XheGXhWH - -另外，此翻譯的 coordinator 為 `mattwang44 `_ 和 \ -`josix `_，你也可以分別透過以下 email 聯繫：\ -``mattwang44 at gmail dot com``, ``josixwang at gmail dot com``。 - - -額外翻譯資源 -============ - -- Discord channel `discord.gg/44XheGXhWH`_ -- `Doc-SIG mailing list `_ -- `PEP 545 `_ -- `zh_CN Translation of the Python Documentation - `_ -- `Cambridge Dictionary `_ - - -維護、預覽 -========== - -以下的指令皆預設在本機端 ``python-docs-zh-tw`` clone 的根目錄執行，同時預設\ -在同一個目錄底下有一個 CPython clone，如下： - -:: - - ~/ - ├── python-docs-zh-tw/ - └── cpython/ - -若要在本機端 clone 一個 CPython，可以使用以下指令： - -.. code-block:: bash - - $ git clone --depth 1 --no-single-branch https://github.com/python/cpython.git - -這樣可以避免下載完整的 commit 歷史（對輸出文件沒什麼幫助），但仍然能把所有的 -branch clone 下來。 - -與 CPython 同步最新的 pot 檔 (目前由 GitHub Actions 定時代為執行) ----------------------------------------------------------- - -pot 檔為翻譯的樣板檔案，它包含需要翻譯的原始字串 (*msgid*) 跟其對應的空白翻譯字串 (*msgstr*)，\ -此步驟會參考最新的 CPython 中的 pot 檔來更新 po 檔。如果是之前在 po 檔中已填入過翻譯字串但參考的 \ -pot 檔的 ``msgid`` 已有變動，則此指令會自動加上 ``#, fuzzy`` 的標記，代表內容有些許差異需要更新。 - -.. code-block:: bash - - $ make merge - -尋找有翻譯過但需校閱的 fuzzy entries ---------------------------------- - -在 po 檔中，你會看到 ``#, fuzzy`` 的字樣，這就表示了接下來的字串是 fuzzy entry，需要更新翻譯。\ -你可以自行用習慣的文字編輯器、Linux 指令搜尋有包含此字樣的檔案，但請記得 ``#, fuzzy`` 標記的翻譯字串\ -有可能是尚未翻譯過的空白字串 (*msgstr*)。執行下列指令會列出有 *Fuzzy entries* 的檔案且會排除這個情形。 - -.. code-block:: bash - - $ make fuzzy - -Project History -=============== - -This translation project was created by Liang-Bo Wang in late-2015, the -translations were hosted on https://docs.python.org.tw/3, and the project -includes daily auto-build sever, documentation website enhancement for -translations and project management on the `python-doc-tw -`_ GitHub organisation. The translations -were done on Transifex, with `our own translation team and project -`_. People who've contributed -on this Transifex project are listed in `TRANSLATORS`_ - -.. _TRANSLATORS: TRANSLATORS - -In mid-2018, thanks to `PEP 545 `_ -and the Doc-SIG community, this project has migrated to Python's Github -organisation and will become the official Taiwanese Mandarin translation of the -documentation. - - -Acknowledgement -=============== - -This translation project is highly influenced by python-doc-ja_ and -python-doc-fr_'s translation architecture and workflow (i.e. a shameless -copy). We truly appreciate their contributions. - -.. _python-doc-ja: https://github.com/python-doc-ja/python-doc-ja -.. _python-doc-fr: https://github.com/python/python-docs-fr +======================================= +Python 官方說明文件臺灣繁體中文翻譯計畫 +======================================= + +.. image:: https://badgen.net/badge/chat/on%20Discord/blue + :target: https://discord.gg/44XheGXhWH + :alt: Join Chat on Discord + +這是 Python 3.14 官方說明文件的臺灣繁體中文（zh_TW）翻譯。 + +翻譯之前，請務必詳讀並同意\ `授權與 License`_。參與方式請參考\ `參與翻譯`_。 + +你可以在 https://python.github.io/python-docs-zh-tw/ 瀏覽目前翻譯的成果。 + +想問問題、認識翻譯同好，歡迎加入 Discord 頻道 `discord.gg/44XheGXhWH`_ + +.. _discord.gg/44XheGXhWH: https://discord.gg/44XheGXhWH + +.. contents:: **目錄 Table of Contents** + +授權與 License +============== + +以下為 Documentation Contribution Agreement，說明文件貢獻協議，請在貢獻以前\ +務必詳讀以下內容。原文後附有中文翻譯，但譯文不保證完全正確，請以原文為準。 + +Documentation Contribution Agreement +------------------------------------ + +NOTE REGARDING THE LICENSE FOR TRANSLATIONS: Python's documentation is +maintained using a global network of volunteers. By posting this +project on Transifex, GitHub, and other public places, and inviting +you to participate, we are proposing an agreement that you will +provide your improvements to Python's documentation or the translation +of Python's documentation for the PSF's use under the CC0 license +(available at +https://creativecommons.org/publicdomain/zero/1.0/legalcode). In +return, you may publicly claim credit for the portion of the +translation you contributed and if your translation is accepted by the +PSF, you may (but are not required to) submit a patch including an +appropriate annotation in the Misc/ACKS or TRANSLATORS file. Although +nothing in this Documentation Contribution Agreement obligates the PSF +to incorporate your textual contribution, your participation in the +Python community is welcomed and appreciated. + +You signify acceptance of this agreement by submitting your work to +the PSF for inclusion in the documentation. + +中文翻譯 +~~~~~~~~ + +請注意此予翻譯專案的授權：Python 的說明文件是以全球的志工社群來維護。透過張貼\ +此專案在 Transifex、GitHub 以及其他公眾場合，以及邀請你參與，我們向你提出一個\ +協議：你必須將你對於 Python 說明文件或是 Python 說明文件翻譯的貢獻以 CC0\ +（請參考 https://creativecommons.org/publicdomain/zero/1.0/legalcode/ +）的方式授權給 PSF 使用。你可以公開地聲明你所貢獻翻譯的部分，並且如果你的翻譯被 PSF +採用，你可以（但並不須要）送出一個修改，其包含在 Misc/ACKS 或是 TRANSLATORS +檔案裡增加合適的注釋。雖然這個說明文件貢獻協議並沒有說明 PSF 有義務納入你的\ +文本貢獻，你在 Python 社群的參與是受歡迎且受感激的。 + +你在對 PSF 送出說明文件貢獻的同時，即表示同意上述的協議。 + + +參與翻譯 +======== + +關於 po (Portable Object) 檔 +----------------------------- + +此為所需翻譯的文字檔，副檔名為 ``.po``，不同語系就會有一個 po 檔。主要內容為翻譯的參考原始字串 (*msgid*)，\ +及需要填入的翻譯字串 (*msgstr*)。有時你會看到 ``#, fuzzy`` 的註記，它代表此翻譯字串需要校閱。 + +翻譯流程 +------------ + +**請注意**: 以下基於 ``make`` 的便捷指令僅能運作於 Unix 系統上（無法使用並不影響主要翻譯流程），\ +其他作業系統的使用者在翻譯後可考慮改於 `GitHub Codespace `_ 上呼叫 ``make`` 指令。 +（參考 `project wiki 頁面 `_） + +事先需要有 +~~~~~~~~~~ + +- 一個 `GitHub 帳號 `_ +- `安裝好 git `_\ （Windows + 上請參考 https://gitforwindows.org/） +- 一個 ``.po`` 檔的編輯器。推薦使用 `Poedit `_，若熟悉 po 檔用一般文字編輯器亦可。 +- 參考 `uv Installation `_ 安裝 uv，以便在本機端預覽翻譯成果。 +- macOS 的使用者還需要先利用 `homebrew `_ 安裝 gettext，屆時 Sphinx 會使用到。 + + .. code-block:: bash + + brew install gettext + brew link gettext --force + +- 安裝 pre-commit 自動在 commit 時檢查 ``.po`` 檔格式。 + + .. code-block:: bash + + pip install pre-commit + pre-commit install + +在進行任何動作以前，你必須在 GitHub 上 fork 此專案（按下右上角的 ``Fork`` +按鈕），這樣會把整個專案複製一份到你的 GitHub 帳號底下，你可以對這個 fork +進行修改。 + +第一次貢獻以前（還沒有 clone 過） +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +請在 terminal 裡依照以下步驟： + +.. code-block:: bash + + # 用 git clone 將你的 fork 下載到本機端 + git clone git@github.com:<你的 GitHub 帳號>/python-docs-zh-tw.git + + # 進入 clone 下來的資料夾裡： + cd python-docs-zh-tw/ + + # 將 python/python-docs-zh-tw 設為 upstream remote + git remote add upstream https://github.com/python/python-docs-zh-tw.git + +每一次翻譯時 +~~~~~~~~~~~~ + +請遵照以下步驟（`GitHub Flow`_）： + +.. _GitHub Flow: https://guides.github.com/introduction/flow/ +.. _GitHub PR 文件: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request#creating-the-pull-request + +首先，`新增一個 issue `_\ +，如：「翻譯 library/math.po」，讓大家知道你正在翻譯這個檔案。待翻譯文件清單請參考\ +`此頁面 `_。 + +接著在 terminal 裡按照以下步驟： + +1. 基於最新版本的 ``upstream/3.14`` 開啟一個 branch，現在假設我們想要翻譯 library/math.po \ + 所以把這個 branch 叫做 ``library/math``： + + .. code-block:: bash + + git fetch upstream + git checkout -b library/math upstream/3.14 + +2. 接著就可以開始翻譯（翻譯時可參考\ `翻譯守則`_），你可以手動開啟 Poedit 應用程式再選 \ + library/math.po 檔案打開 + +3. 填入中譯內容並存檔以後，執行以下列指令編譯輸出完整文件，以確保你的修改沒有 reST 的語法錯誤或警告： + + + .. code-block:: bash + + make all + + + 或者只想快速檢查是否有 reST 語法錯誤： + + .. code-block:: bash + + make lint + + + 確保輸出中沒有任何警告訊息。 + + 在 ``make all`` 後，可以使用 ``make build`` 來只對單一 po 檔進行編譯，可以節省較多的時間： + + .. code-block:: bash + + make build library/math.po + + 如果你還沒有執行\ `維護、預覽`_\ 的 clone CPython 的動作，此指令會自動幫你 clone CPython，\ + 並且會使用 Sphinx 幫你檢查 reST 語法錯誤，我們盡量保持沒有 warning \ + 的狀態，因此如果有出現 warning 的話請修復它。另外也記得檢查是否符合\ + `翻譯守則`_ + +4. 輸出的文件會被放置在你的本地端 CPython clone（見\ `維護、預覽`_\ 段落的圖示）\ + 底下的 ``Doc/build/html``，可以使用 `http.server` 或其他靜態網頁伺服器即可以預覽成果。 + + .. code-block:: bash + + cd ../cpython/Doc/build/html + python3 -m http.server + + 你也可以執行下列指令請瀏覽器打開編譯出來的文件\ + 以確認整份文件的語意通暢（翻譯別的檔案時將 library/math 換成別的檔名）： + + .. code-block:: bash + + open ../cpython/Doc/build/html/library/math.html + +5. 檢查完畢後，即可以將你的翻譯 commit 起來，請使用明確的 commit message： + + .. code-block:: bash + + git add library/math.po + git commit -m "Working on library/math.po" + +6. 將你的修改 push 到你的 GitHub clone 上。為了簡單，我們可以用 ``origin HEAD`` + 來告訴 git 我們將修改 push 到 origin，branch 則和本機端的 branch 名稱一樣： + + .. code-block:: bash + + git push origin HEAD + +7. 這時候你就可以打開一個 pull request 了：請打開\ `此專案的 GitHub 頁面 `_，\ + 你會看到一個「Compare & Pull Request」按鈕，按下它就可以對此專案發送一個 pull request（參考 `GitHub PR 文件`_）。 + +8. 如果有人在 GitHub 上 review 了你的 pull request，並且你想要修改你的內容，\ + 那麼（如果你切換到了別的 branch 上）你要先切換回到你的 branch 上： + + .. code-block:: bash + + git checkout library/math + + 接著修改你要修正的問題，並再次 commit、push： + + .. code-block:: bash + + git add library/math.po + git commit -m "fix(library/math): resolve review comments" + git push origin HEAD + +這整個流程裡有幾件事情值得注意： + +- 從 upstream（我們的主要 GitHub repo）做 fetch 的動作 +- 對 origin（你的 fork）做 push +- 永遠不對 ``3.14`` branch 進行修改，請保持讓這個 branch 唯讀，可以避免掉很多問題。 + +要翻譯哪些東西 +-------------- + +主要是填入翻譯字串 (*msgstr*) 以及更新有標記為 ``#, fuzzy`` 的字串。 + +其中最簡單的貢獻方式就是更新 *fuzzy entries*，讓曾經翻譯的內容保持與最新版本的文件 +同步。請參考\ `尋找有翻譯過但需校閱的 fuzzy entries`_ 段落。 + +此外，目前的目標為完成 **Tutorial** 的翻譯，因此在 ``tutorial/`` 底下的所有 +po 檔皆為首要的翻譯對象。你也可以幫忙校對已經翻譯過的內容。 + + +翻譯守則 +======== + +#. 譯文應兼顧前後文大意，在翻譯一份文件前請務必熟讀該文件的原文。 + +#. 中文句使用全形標點符號；英文句維持半形的標點符號。 + + 例如：「」（）、，。 + + 例如：Python is supported by Python Software Foundation (PSF). + +#. 中英文交雜時要插入空白；符號英文間不用。 + + 例如：使用 CPU 運算、使用「CPU」運算 + +#. 專有名詞應該參考\ `術語表 Glossary`_ 裡的翻譯方式。 + +#. 專有名詞可以選擇不翻譯。 + + 例如：CPU、Unicode + +#. 在翻譯名稱不常用或不確定的情形，宜用括號註解或直接保留原文。單頁只要首次\ + 出現有註解即可。 + + 例如：正規表示式 (regular expression) + + 例如：Network News Transfer Protocol、Portable Network Graphics + （可攜式網路圖形） + +#. 務必保留 reStructuredText 格式（如：超連結名稱） + +#. po 檔單行不應超過 79 字元寬度（Poedit 會處理，但也可以使用 `powrap + `_ + 來確保格式） + +#. 高頻詞保留原文。因為翻譯後不一定能較好理解市面上 Python 的文章。 這些高頻詞\ + 在 Glossary 中的譯文仍保持原文，並加註市面上的翻譯。 + + 例如：``int``、``float``、``str``、``bytes``、``list``、``tuple``、 + ``dict``、``set``、``iterator``、``generator``、``iterable``、 + ``pickle`` + + +括號的使用 +---------- + +如果括號中的文字包含中文，使用全形括號；如果括號中只有英文，使用半形括號並\ +比照英文的形式加入前後文的空白。 + +例如： + +- list（串列）是 Python 中很常見的資料型別。 +- 在本情況使用 ``zip(*[iter(x)]*n)`` 是很常見的情況（Python 慣例）。 +- 在超文件標示語言 (HTML) 中應注意跳脫符號。 + +reST 語法注意事項 +--------------------- + +- ``:xxx:`...``` 即為 reST 的語法，應該在譯文中保留。 + + 例如： + + .. code-block:: rst + + Avoids tests using :func:`type` or :func:`isinstance`. + + 翻譯為 + + .. code-block:: rst + + 避免使用 :func:`type` 或 :func:`isinstance` 進行測試。 + +- reST 諸多語法需要保留前後的空白。在中文裡，該空白可以用 :literal:`\\\\\ \ ` \ + 來取代，製造一個沒有寬度的分隔符號。 + + 例如當 ``:ref:`detail-instruction`` 部分會被編譯為中文時： + + .. code-block:: rst + + For more information, please see :ref:`detail-instruction`. + + 翻譯為 + + .. code-block:: rst + + 更多資訊請參考\\ :ref:`detail-instruction`。 + +- 超連結語法該要在譯文中保留原字串。 + + 例如： + + .. code-block:: rst + + `Documentation bugs`_ on the Python issue tracker + + 應翻譯為 + + .. code-block:: rst + + Python issue tracker 上\\ `文件的錯誤 `_ + + 才能正確顯示為「Python issue tracker 上\ `文件的錯誤 <#>`_」，並帶有正確連結且與\ + 前文才不會有多餘的空白。 + +- 舉例中有程式碼時，前一段經常為 ``::`` 結尾，此記號\ `具有特殊意義 + `_，\ + 除了該段落結尾為冒號外，也代表下段縮排為程式碼。翻譯時應改為 ``： ::``\ + （參考 `#568 `_）。 + + 例如： + + .. code-block:: rst + + Here is a code example:: + + import sys + print(sys.version) + + 程式碼並不會出現在 po 檔之中，故在 po 檔中會顯示為 + + .. code-block:: rst + + Here is a code example:: + + 此時翻譯應為： + + .. code-block:: rst + + 以下是個程式範例： :: + +術語表 Glossary +=============== + +為了讓翻譯保持統一，我們整理了一份\ +`術語列表 `_\ +如果翻譯過程中你覺得需要術語列表有所缺漏，請至 `Discussion \ +`_ 開啟新的討論補充術語。\ +新增的術語，將會於每次 Sprint 中共同討論是否合併進術語列表。 + + + +問題回報與討論 +============== + +如果有需要共同討論的問題，請開設一個新的 Issue_。如果是翻譯上遇到困難需要\ +幫助，則可以使用 Discord_。 + +.. _Issue: https://github.com/python/python-docs-zh-tw/issues +.. _Discord: https://discord.gg/44XheGXhWH + +另外，此翻譯的 coordinator 為 `mattwang44 `_ 和 \ +`josix `_，你也可以分別透過以下 email 聯繫：\ +``mattwang44 at gmail dot com``, ``josixwang at gmail dot com``。 + + +額外翻譯資源 +============ + +- Discord channel `discord.gg/44XheGXhWH`_ +- `Doc-SIG mailing list `_ +- `PEP 545 `_ +- `zh_CN Translation of the Python Documentation + `_ +- `Cambridge Dictionary `_ + + +維護、預覽 +========== + +以下的指令皆預設在本機端 ``python-docs-zh-tw`` clone 的根目錄執行，同時預設\ +在同一個目錄底下有一個 CPython clone，如下： + +:: + + ~/ + ├── python-docs-zh-tw/ + └── cpython/ + +若要在本機端 clone 一個 CPython，可以使用以下指令： + +.. code-block:: bash + + $ git clone --depth 1 --no-single-branch https://github.com/python/cpython.git + +這樣可以避免下載完整的 commit 歷史（對輸出文件沒什麼幫助），但仍然能把所有的 +branch clone 下來。 + +與 CPython 同步最新的 pot 檔 (目前由 GitHub Actions 定時代為執行) +---------------------------------------------------------- + +pot 檔為翻譯的樣板檔案，它包含需要翻譯的原始字串 (*msgid*) 跟其對應的空白翻譯字串 (*msgstr*)，\ +此步驟會參考最新的 CPython 中的 pot 檔來更新 po 檔。如果是之前在 po 檔中已填入過翻譯字串但參考的 \ +pot 檔的 ``msgid`` 已有變動，則此指令會自動加上 ``#, fuzzy`` 的標記，代表內容有些許差異需要更新。 + +.. code-block:: bash + + $ make merge + +尋找有翻譯過但需校閱的 fuzzy entries +--------------------------------- + +在 po 檔中，你會看到 ``#, fuzzy`` 的字樣，這就表示了接下來的字串是 fuzzy entry，需要更新翻譯。\ +你可以自行用習慣的文字編輯器、Linux 指令搜尋有包含此字樣的檔案，但請記得 ``#, fuzzy`` 標記的翻譯字串\ +有可能是尚未翻譯過的空白字串 (*msgstr*)。執行下列指令會列出有 *Fuzzy entries* 的檔案且會排除這個情形。 + +.. code-block:: bash + + $ make fuzzy + +Project History +=============== + +This translation project was created by Liang-Bo Wang in late-2015, the +translations were hosted on https://docs.python.org.tw/3, and the project +includes daily auto-build sever, documentation website enhancement for +translations and project management on the `python-doc-tw +`_ GitHub organisation. The translations +were done on Transifex, with `our own translation team and project +`_. People who've contributed +on this Transifex project are listed in `TRANSLATORS`_ + +.. _TRANSLATORS: TRANSLATORS + +In mid-2018, thanks to `PEP 545 `_ +and the Doc-SIG community, this project has migrated to Python's Github +organisation and will become the official Taiwanese Mandarin translation of the +documentation. + + +Acknowledgement +=============== + +This translation project is highly influenced by python-doc-ja_ and +python-doc-fr_'s translation architecture and workflow (i.e. a shameless +copy). We truly appreciate their contributions. + +.. _python-doc-ja: https://github.com/python-doc-ja/python-doc-ja +.. _python-doc-fr: https://github.com/python/python-docs-fr diff --git a/about.po b/about.po index 0ebe85514f..d712ecfcae 100644 --- a/about.po +++ b/about.po @@ -1,98 +1,98 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Adrian Liaw , 2015 -# Ching-Lung Chuang, 2015 -# hsiao yi , 2016 -# aminzai , 2015 -# Liang-Bo Wang , 2015 -# Frank Jheng , 2015 -# hsiao yi , 2015 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-01-01 00:15+0000\n" -"PO-Revision-Date: 2022-05-12 00:11+0800\n" -"Last-Translator: hsiao yi \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" -"X-Generator: Poedit 3.0.1\n" - -#: ../../about.rst:3 -msgid "About this documentation" -msgstr "關於這份說明文件" - -#: ../../about.rst:6 -msgid "" -"Python's documentation is generated from `reStructuredText`_ sources using " -"`Sphinx`_, a documentation generator originally created for Python and now " -"maintained as an independent project." -msgstr "" -"Python 說明文件是透過使用 `Sphinx`_\\ （一個原為 Python 而生的文件產生器、目" -"前是以獨立專案形式來維護）將使用 `reStructuredText`_ 撰寫的原始檔轉換而成。" - -#: ../../about.rst:16 -msgid "" -"Development of the documentation and its toolchain is an entirely volunteer " -"effort, just like Python itself. If you want to contribute, please take a " -"look at the :ref:`reporting-bugs` page for information on how to do so. New " -"volunteers are always welcome!" -msgstr "" -"如同 Python 自身，透過自願者的努力下產出文件與封裝後自動化執行工具。若想要回" -"報臭蟲，請見 :ref:`reporting-bugs` 頁面，內含相關資訊。我們永遠歡迎新的自願者" -"加入！" - -#: ../../about.rst:21 -msgid "Many thanks go to:" -msgstr "致謝：" - -#: ../../about.rst:23 -msgid "" -"Fred L. Drake, Jr., the creator of the original Python documentation toolset " -"and author of much of the content;" -msgstr "" -"Fred L. Drake, Jr.，原始 Python 文件工具集的創造者以及一大部份內容的作者；" - -#: ../../about.rst:25 -msgid "" -"the `Docutils `_ project for creating " -"reStructuredText and the Docutils suite;" -msgstr "" -"創造 reStructuredText 和 Docutils 工具組的 `Docutils `_ 專案；" - -#: ../../about.rst:27 -msgid "" -"Fredrik Lundh for his Alternative Python Reference project from which Sphinx " -"got many good ideas." -msgstr "" -"Fredrik Lundh 先生，Sphinx 從他的 Alternative Python Reference 計劃中獲得許多" -"的好主意。" - -#: ../../about.rst:32 -msgid "Contributors to the Python documentation" -msgstr "Python 文件的貢獻者們" - -#: ../../about.rst:34 -msgid "" -"Many people have contributed to the Python language, the Python standard " -"library, and the Python documentation. See :source:`Misc/ACKS` in the " -"Python source distribution for a partial list of contributors." -msgstr "" -"許多人都曾為 Python 這門語言、Python 標準函式庫和 Python 說明文件貢獻過。" -"Python 所發佈的原始碼中含有部份貢獻者的清單，請見 :source:`Misc/ACKS` 。" - -#: ../../about.rst:38 -msgid "" -"It is only with the input and contributions of the Python community that " -"Python has such wonderful documentation -- Thank You!" -msgstr "" -"正因為 Python 社群的撰寫與貢獻才有這份這麼棒的說明文件 -- 感謝所有貢獻過的人" -"們！" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Adrian Liaw , 2015 +# Ching-Lung Chuang, 2015 +# hsiao yi , 2016 +# aminzai , 2015 +# Liang-Bo Wang , 2015 +# Frank Jheng , 2015 +# hsiao yi , 2015 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-01-01 00:15+0000\n" +"PO-Revision-Date: 2022-05-12 00:11+0800\n" +"Last-Translator: hsiao yi \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" +"X-Generator: Poedit 3.0.1\n" + +#: ../../about.rst:3 +msgid "About this documentation" +msgstr "關於這份說明文件" + +#: ../../about.rst:6 +msgid "" +"Python's documentation is generated from `reStructuredText`_ sources using " +"`Sphinx`_, a documentation generator originally created for Python and now " +"maintained as an independent project." +msgstr "" +"Python 說明文件是透過使用 `Sphinx`_\\ （一個原為 Python 而生的文件產生器、目" +"前是以獨立專案形式來維護）將使用 `reStructuredText`_ 撰寫的原始檔轉換而成。" + +#: ../../about.rst:16 +msgid "" +"Development of the documentation and its toolchain is an entirely volunteer " +"effort, just like Python itself. If you want to contribute, please take a " +"look at the :ref:`reporting-bugs` page for information on how to do so. New " +"volunteers are always welcome!" +msgstr "" +"如同 Python 自身，透過自願者的努力下產出文件與封裝後自動化執行工具。若想要回" +"報臭蟲，請見 :ref:`reporting-bugs` 頁面，內含相關資訊。我們永遠歡迎新的自願者" +"加入！" + +#: ../../about.rst:21 +msgid "Many thanks go to:" +msgstr "致謝：" + +#: ../../about.rst:23 +msgid "" +"Fred L. Drake, Jr., the creator of the original Python documentation toolset " +"and author of much of the content;" +msgstr "" +"Fred L. Drake, Jr.，原始 Python 文件工具集的創造者以及一大部份內容的作者；" + +#: ../../about.rst:25 +msgid "" +"the `Docutils `_ project for creating " +"reStructuredText and the Docutils suite;" +msgstr "" +"創造 reStructuredText 和 Docutils 工具組的 `Docutils `_ 專案；" + +#: ../../about.rst:27 +msgid "" +"Fredrik Lundh for his Alternative Python Reference project from which Sphinx " +"got many good ideas." +msgstr "" +"Fredrik Lundh 先生，Sphinx 從他的 Alternative Python Reference 計劃中獲得許多" +"的好主意。" + +#: ../../about.rst:32 +msgid "Contributors to the Python documentation" +msgstr "Python 文件的貢獻者們" + +#: ../../about.rst:34 +msgid "" +"Many people have contributed to the Python language, the Python standard " +"library, and the Python documentation. See :source:`Misc/ACKS` in the " +"Python source distribution for a partial list of contributors." +msgstr "" +"許多人都曾為 Python 這門語言、Python 標準函式庫和 Python 說明文件貢獻過。" +"Python 所發佈的原始碼中含有部份貢獻者的清單，請見 :source:`Misc/ACKS` 。" + +#: ../../about.rst:38 +msgid "" +"It is only with the input and contributions of the Python community that " +"Python has such wonderful documentation -- Thank You!" +msgstr "" +"正因為 Python 社群的撰寫與貢獻才有這份這麼棒的說明文件 -- 感謝所有貢獻過的人" +"們！" diff --git a/bugs.po b/bugs.po index 4bd3a6eb49..b1ccf3282d 100644 --- a/bugs.po +++ b/bugs.po @@ -1,266 +1,266 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Asoul Yang , 2016 -# Ching-Lung Chuang, 2015 -# aminzai , 2015 -# Liang-Bo Wang , 2015 -# sammy huang , 2017 -# Steven Hsu , 2021-2022 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-10-20 00:15+0000\n" -"PO-Revision-Date: 2022-08-31 12:34+0800\n" -"Last-Translator: Steven Hsu \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" -"X-Generator: Poedit 3.1.1\n" - -#: ../../bugs.rst:5 -msgid "Dealing with Bugs" -msgstr "處理錯誤 (Bug)" - -#: ../../bugs.rst:7 -msgid "" -"Python is a mature programming language which has established a reputation " -"for stability. In order to maintain this reputation, the developers would " -"like to know of any deficiencies you find in Python." -msgstr "" -"Python 已經是一個以穩定著稱的成熟程式語言。為了維持「穩定」的信譽，開發者們想" -"知道任何你在 Python 中發現的缺失。" - -#: ../../bugs.rst:11 -msgid "" -"It can be sometimes faster to fix bugs yourself and contribute patches to " -"Python as it streamlines the process and involves less people. Learn how to :" -"ref:`contribute `." -msgstr "" -"有時候自己直接修復錯誤並且送出一個修正給 Python 會比較快，因為這樣會加速流程" -"而且不會困擾到太多人。學習如何\\ :ref:`貢獻給 Python `。" - -#: ../../bugs.rst:16 -msgid "Documentation bugs" -msgstr "說明文件的錯誤" - -#: ../../bugs.rst:18 -msgid "" -"If you find a bug in this documentation or would like to propose an " -"improvement, please submit a bug report on the :ref:`issue tracker `. If you have a suggestion on how to fix it, include that as " -"well." -msgstr "" -"如果你在這份說明文件中發現了錯誤並想要提出改進方案，請將錯誤報告提交到\\ :" -"ref:`錯誤追蹤系統 (issue tracker) `。如果你有相應的修正建" -"議，請一併提交。（譯者註：如果是繁體中文說明文件翻譯相關的錯誤，請提交到 " -"https://github.com/python/python-docs-zh-tw/issues。）" - -#: ../../bugs.rst:24 -msgid "" -"If the bug or suggested improvement concerns the translation of this " -"documentation, submit the report to the `translation’s repository " -"`_ instead." -msgstr "" -"如果錯誤或建議的改進涉及此文件的翻譯，請將報告提交到\\ `翻譯存儲庫 " -"`_。" - -#: ../../bugs.rst:28 -msgid "" -"You can also open a discussion item on our `Documentation Discourse forum " -"`_." -msgstr "" -"你也可以在我們的\\ `說明文件 Discourse 討論區 `_\\ 中新增一個討論事項。" - -#: ../../bugs.rst:31 -msgid "" -"If you find a bug in the theme (HTML / CSS / JavaScript) of the " -"documentation, please submit a bug report on the `python-doc-theme issue " -"tracker `_." -msgstr "" -"如果你發現文件主題 (HTML / CSS / JavaScript) 中存在錯誤，請在 `python-doc-" -"theme 問題追蹤系統 `_\\ 上提交錯誤報" -"告。" - -#: ../../bugs.rst:37 -msgid "`Documentation bugs`_" -msgstr "`說明文件錯誤`_" - -#: ../../bugs.rst:38 -msgid "" -"A list of documentation bugs that have been submitted to the Python issue " -"tracker." -msgstr "一系列已被提交至 Python 問題追蹤系統的有關說明文件的錯誤。" - -#: ../../bugs.rst:40 -msgid "`Issue Tracking `_" -msgstr "`問題追蹤系統 `_" - -#: ../../bugs.rst:41 -msgid "" -"Overview of the process involved in reporting an improvement on the tracker." -msgstr "在追蹤系統上回報改進建議的過程簡介。" - -#: ../../bugs.rst:43 -msgid "" -"`Helping with Documentation `_" -msgstr "" -"`貢獻說明文件 `_" - -#: ../../bugs.rst:44 -msgid "" -"Comprehensive guide for individuals that are interested in contributing to " -"Python documentation." -msgstr "給有意成為 Python 說明文件貢獻者的綜合指南。" - -#: ../../bugs.rst:46 -msgid "" -"`Documentation Translations `_" -msgstr "" -"`說明文件翻譯 `_" - -#: ../../bugs.rst:47 -msgid "" -"A list of GitHub pages for documentation translation and their primary " -"contacts." -msgstr "" -"一份 GitHub 網頁的清單，裡面有各個說明文件翻譯團隊的連結，以及他們的主要聯絡" -"人。" - -#: ../../bugs.rst:53 -msgid "Using the Python issue tracker" -msgstr "使用 Python 問題追蹤系統" - -#: ../../bugs.rst:55 -msgid "" -"Issue reports for Python itself should be submitted via the GitHub issues " -"tracker (https://github.com/python/cpython/issues). The GitHub issues " -"tracker offers a web form which allows pertinent information to be entered " -"and submitted to the developers." -msgstr "" -"對於 Python 本身的問題報告，應該透過 GitHub 問題追蹤系統 (https://github.com/" -"python/cpython/issues) 提交。這個 GitHub 問題追蹤系統提供了一個網頁表單，可以" -"輸入並提交相關資訊給開發者。" - -#: ../../bugs.rst:60 -msgid "" -"The first step in filing a report is to determine whether the problem has " -"already been reported. The advantage in doing so, aside from saving the " -"developers' time, is that you learn what has been done to fix it; it may be " -"that the problem has already been fixed for the next release, or additional " -"information is needed (in which case you are welcome to provide it if you " -"can!). To do this, search the tracker using the search box at the top of the " -"page." -msgstr "" -"填寫報告的第一步，是確認該問題是否已經被回報過了。這樣做的好處，除了可以節省" -"開發者的時間，也能讓你了解目前關於該問題的處理進度；有可能已經在下一個發行版" -"本中修正了這個問題，也有可能需要更詳細的資訊（在這種情況下，如果可以，非常歡" -"迎你提供資訊！）。要確認是否重複回報，請使用頁面頂端的搜尋框來搜尋追蹤系統。" - -#: ../../bugs.rst:67 -msgid "" -"If the problem you're reporting is not already in the list, log in to " -"GitHub. If you don't already have a GitHub account, create a new account " -"using the \"Sign up\" link. It is not possible to submit a bug report " -"anonymously." -msgstr "" -"如果你想回報的問題還沒有在問題列表出現過，請登入 GitHub。如果你還沒有 GitHub " -"帳戶，請點選「Sign up」連結來建立一個新的帳戶。你無法以匿名方式提交錯誤報告。" - -#: ../../bugs.rst:72 -msgid "" -"Being now logged in, you can submit an issue. Click on the \"New issue\" " -"button in the top bar to report a new issue." -msgstr "" -"如果已經登入，那你就可以提交問題了。請點選列表頂端區域的「New issue」按鈕，來" -"回報一個新的問題。" - -#: ../../bugs.rst:75 -msgid "The submission form has two fields, \"Title\" and \"Comment\"." -msgstr "提交的表單中有兩個欄位，「Title」及「Comment」。" - -#: ../../bugs.rst:77 -msgid "" -"For the \"Title\" field, enter a *very* short description of the problem; " -"fewer than ten words is good." -msgstr "" -"在「Title」欄位，輸入對該問題\\ *非常*\\ 簡短的描述；最好少於十個單字。" - -#: ../../bugs.rst:80 -msgid "" -"In the \"Comment\" field, describe the problem in detail, including what you " -"expected to happen and what did happen. Be sure to include whether any " -"extension modules were involved, and what hardware and software platform you " -"were using (including version information as appropriate)." -msgstr "" -"在「Comment」欄位，請詳細描述該問題，包括你預期發生的情況和實際發生的情況。請" -"確定說明中包含了涉及到的任何擴充模組，以及你當時所使用的硬體和軟體平台（視情" -"況而定，可以附上版本資訊）。" - -#: ../../bugs.rst:85 -msgid "" -"Each issue report will be reviewed by a developer who will determine what " -"needs to be done to correct the problem. You will receive an update each " -"time an action is taken on the issue." -msgstr "" -"每一份問題報告都會被一位開發人員查核，並由他決定要做出什麼變更來修正這個問" -"題。每當該問題有修正動作時，你會收到更新回報。" - -#: ../../bugs.rst:92 -msgid "" -"`How to Report Bugs Effectively `_" -msgstr "" -"`如何有效地回報錯誤 `_" - -#: ../../bugs.rst:93 -msgid "" -"Article which goes into some detail about how to create a useful bug report. " -"This describes what kind of information is useful and why it is useful." -msgstr "" -"這篇文章詳細說明如何建立一份有用的錯誤報告。它描述了什麼樣的資訊是有用的，以" -"及這些資訊為什麼有用。" - -#: ../../bugs.rst:96 -msgid "" -"`Bug Writing Guidelines `_" -msgstr "" -"`錯誤撰寫指南 `_" - -#: ../../bugs.rst:97 -msgid "" -"Information about writing a good bug report. Some of this is specific to " -"the Mozilla project, but describes general good practices." -msgstr "" -"撰寫一份優良錯誤報告的相關資訊。部分的文章內容是針對 Mozilla 專案，但它也描述" -"了通用的好習慣。" - -#: ../../bugs.rst:103 -msgid "Getting started contributing to Python yourself" -msgstr "開始讓自己貢獻 Python" - -#: ../../bugs.rst:105 -msgid "" -"Beyond just reporting bugs that you find, you are also welcome to submit " -"patches to fix them. You can find more information on how to get started " -"patching Python in the `Python Developer's Guide`_. If you have questions, " -"the `core-mentorship mailing list`_ is a friendly place to get answers to " -"any and all questions pertaining to the process of fixing issues in Python." -msgstr "" -"除了只是回報你所發現的錯誤之外，同樣也歡迎你提交修正它們的修補程式 (patch)。" -"你可以在 `Python 開發者指南`_\\ 中找到如何開始修補 Python 的更多資訊。如果你" -"有任何問題，`核心導師郵寄清單`_\\ 是一個友善的地方，你可以在那裡得到，關於 " -"Python 修正錯誤的過程中，所有問題的答案。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Asoul Yang , 2016 +# Ching-Lung Chuang, 2015 +# aminzai , 2015 +# Liang-Bo Wang , 2015 +# sammy huang , 2017 +# Steven Hsu , 2021-2022 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-10-20 00:15+0000\n" +"PO-Revision-Date: 2022-08-31 12:34+0800\n" +"Last-Translator: Steven Hsu \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" +"X-Generator: Poedit 3.1.1\n" + +#: ../../bugs.rst:5 +msgid "Dealing with Bugs" +msgstr "處理錯誤 (Bug)" + +#: ../../bugs.rst:7 +msgid "" +"Python is a mature programming language which has established a reputation " +"for stability. In order to maintain this reputation, the developers would " +"like to know of any deficiencies you find in Python." +msgstr "" +"Python 已經是一個以穩定著稱的成熟程式語言。為了維持「穩定」的信譽，開發者們想" +"知道任何你在 Python 中發現的缺失。" + +#: ../../bugs.rst:11 +msgid "" +"It can be sometimes faster to fix bugs yourself and contribute patches to " +"Python as it streamlines the process and involves less people. Learn how to :" +"ref:`contribute `." +msgstr "" +"有時候自己直接修復錯誤並且送出一個修正給 Python 會比較快，因為這樣會加速流程" +"而且不會困擾到太多人。學習如何\\ :ref:`貢獻給 Python `。" + +#: ../../bugs.rst:16 +msgid "Documentation bugs" +msgstr "說明文件的錯誤" + +#: ../../bugs.rst:18 +msgid "" +"If you find a bug in this documentation or would like to propose an " +"improvement, please submit a bug report on the :ref:`issue tracker `. If you have a suggestion on how to fix it, include that as " +"well." +msgstr "" +"如果你在這份說明文件中發現了錯誤並想要提出改進方案，請將錯誤報告提交到\\ :" +"ref:`錯誤追蹤系統 (issue tracker) `。如果你有相應的修正建" +"議，請一併提交。（譯者註：如果是繁體中文說明文件翻譯相關的錯誤，請提交到 " +"https://github.com/python/python-docs-zh-tw/issues。）" + +#: ../../bugs.rst:24 +msgid "" +"If the bug or suggested improvement concerns the translation of this " +"documentation, submit the report to the `translation’s repository " +"`_ instead." +msgstr "" +"如果錯誤或建議的改進涉及此文件的翻譯，請將報告提交到\\ `翻譯存儲庫 " +"`_。" + +#: ../../bugs.rst:28 +msgid "" +"You can also open a discussion item on our `Documentation Discourse forum " +"`_." +msgstr "" +"你也可以在我們的\\ `說明文件 Discourse 討論區 `_\\ 中新增一個討論事項。" + +#: ../../bugs.rst:31 +msgid "" +"If you find a bug in the theme (HTML / CSS / JavaScript) of the " +"documentation, please submit a bug report on the `python-doc-theme issue " +"tracker `_." +msgstr "" +"如果你發現文件主題 (HTML / CSS / JavaScript) 中存在錯誤，請在 `python-doc-" +"theme 問題追蹤系統 `_\\ 上提交錯誤報" +"告。" + +#: ../../bugs.rst:37 +msgid "`Documentation bugs`_" +msgstr "`說明文件錯誤`_" + +#: ../../bugs.rst:38 +msgid "" +"A list of documentation bugs that have been submitted to the Python issue " +"tracker." +msgstr "一系列已被提交至 Python 問題追蹤系統的有關說明文件的錯誤。" + +#: ../../bugs.rst:40 +msgid "`Issue Tracking `_" +msgstr "`問題追蹤系統 `_" + +#: ../../bugs.rst:41 +msgid "" +"Overview of the process involved in reporting an improvement on the tracker." +msgstr "在追蹤系統上回報改進建議的過程簡介。" + +#: ../../bugs.rst:43 +msgid "" +"`Helping with Documentation `_" +msgstr "" +"`貢獻說明文件 `_" + +#: ../../bugs.rst:44 +msgid "" +"Comprehensive guide for individuals that are interested in contributing to " +"Python documentation." +msgstr "給有意成為 Python 說明文件貢獻者的綜合指南。" + +#: ../../bugs.rst:46 +msgid "" +"`Documentation Translations `_" +msgstr "" +"`說明文件翻譯 `_" + +#: ../../bugs.rst:47 +msgid "" +"A list of GitHub pages for documentation translation and their primary " +"contacts." +msgstr "" +"一份 GitHub 網頁的清單，裡面有各個說明文件翻譯團隊的連結，以及他們的主要聯絡" +"人。" + +#: ../../bugs.rst:53 +msgid "Using the Python issue tracker" +msgstr "使用 Python 問題追蹤系統" + +#: ../../bugs.rst:55 +msgid "" +"Issue reports for Python itself should be submitted via the GitHub issues " +"tracker (https://github.com/python/cpython/issues). The GitHub issues " +"tracker offers a web form which allows pertinent information to be entered " +"and submitted to the developers." +msgstr "" +"對於 Python 本身的問題報告，應該透過 GitHub 問題追蹤系統 (https://github.com/" +"python/cpython/issues) 提交。這個 GitHub 問題追蹤系統提供了一個網頁表單，可以" +"輸入並提交相關資訊給開發者。" + +#: ../../bugs.rst:60 +msgid "" +"The first step in filing a report is to determine whether the problem has " +"already been reported. The advantage in doing so, aside from saving the " +"developers' time, is that you learn what has been done to fix it; it may be " +"that the problem has already been fixed for the next release, or additional " +"information is needed (in which case you are welcome to provide it if you " +"can!). To do this, search the tracker using the search box at the top of the " +"page." +msgstr "" +"填寫報告的第一步，是確認該問題是否已經被回報過了。這樣做的好處，除了可以節省" +"開發者的時間，也能讓你了解目前關於該問題的處理進度；有可能已經在下一個發行版" +"本中修正了這個問題，也有可能需要更詳細的資訊（在這種情況下，如果可以，非常歡" +"迎你提供資訊！）。要確認是否重複回報，請使用頁面頂端的搜尋框來搜尋追蹤系統。" + +#: ../../bugs.rst:67 +msgid "" +"If the problem you're reporting is not already in the list, log in to " +"GitHub. If you don't already have a GitHub account, create a new account " +"using the \"Sign up\" link. It is not possible to submit a bug report " +"anonymously." +msgstr "" +"如果你想回報的問題還沒有在問題列表出現過，請登入 GitHub。如果你還沒有 GitHub " +"帳戶，請點選「Sign up」連結來建立一個新的帳戶。你無法以匿名方式提交錯誤報告。" + +#: ../../bugs.rst:72 +msgid "" +"Being now logged in, you can submit an issue. Click on the \"New issue\" " +"button in the top bar to report a new issue." +msgstr "" +"如果已經登入，那你就可以提交問題了。請點選列表頂端區域的「New issue」按鈕，來" +"回報一個新的問題。" + +#: ../../bugs.rst:75 +msgid "The submission form has two fields, \"Title\" and \"Comment\"." +msgstr "提交的表單中有兩個欄位，「Title」及「Comment」。" + +#: ../../bugs.rst:77 +msgid "" +"For the \"Title\" field, enter a *very* short description of the problem; " +"fewer than ten words is good." +msgstr "" +"在「Title」欄位，輸入對該問題\\ *非常*\\ 簡短的描述；最好少於十個單字。" + +#: ../../bugs.rst:80 +msgid "" +"In the \"Comment\" field, describe the problem in detail, including what you " +"expected to happen and what did happen. Be sure to include whether any " +"extension modules were involved, and what hardware and software platform you " +"were using (including version information as appropriate)." +msgstr "" +"在「Comment」欄位，請詳細描述該問題，包括你預期發生的情況和實際發生的情況。請" +"確定說明中包含了涉及到的任何擴充模組，以及你當時所使用的硬體和軟體平台（視情" +"況而定，可以附上版本資訊）。" + +#: ../../bugs.rst:85 +msgid "" +"Each issue report will be reviewed by a developer who will determine what " +"needs to be done to correct the problem. You will receive an update each " +"time an action is taken on the issue." +msgstr "" +"每一份問題報告都會被一位開發人員查核，並由他決定要做出什麼變更來修正這個問" +"題。每當該問題有修正動作時，你會收到更新回報。" + +#: ../../bugs.rst:92 +msgid "" +"`How to Report Bugs Effectively `_" +msgstr "" +"`如何有效地回報錯誤 `_" + +#: ../../bugs.rst:93 +msgid "" +"Article which goes into some detail about how to create a useful bug report. " +"This describes what kind of information is useful and why it is useful." +msgstr "" +"這篇文章詳細說明如何建立一份有用的錯誤報告。它描述了什麼樣的資訊是有用的，以" +"及這些資訊為什麼有用。" + +#: ../../bugs.rst:96 +msgid "" +"`Bug Writing Guidelines `_" +msgstr "" +"`錯誤撰寫指南 `_" + +#: ../../bugs.rst:97 +msgid "" +"Information about writing a good bug report. Some of this is specific to " +"the Mozilla project, but describes general good practices." +msgstr "" +"撰寫一份優良錯誤報告的相關資訊。部分的文章內容是針對 Mozilla 專案，但它也描述" +"了通用的好習慣。" + +#: ../../bugs.rst:103 +msgid "Getting started contributing to Python yourself" +msgstr "開始讓自己貢獻 Python" + +#: ../../bugs.rst:105 +msgid "" +"Beyond just reporting bugs that you find, you are also welcome to submit " +"patches to fix them. You can find more information on how to get started " +"patching Python in the `Python Developer's Guide`_. If you have questions, " +"the `core-mentorship mailing list`_ is a friendly place to get answers to " +"any and all questions pertaining to the process of fixing issues in Python." +msgstr "" +"除了只是回報你所發現的錯誤之外，同樣也歡迎你提交修正它們的修補程式 (patch)。" +"你可以在 `Python 開發者指南`_\\ 中找到如何開始修補 Python 的更多資訊。如果你" +"有任何問題，`核心導師郵寄清單`_\\ 是一個友善的地方，你可以在那裡得到，關於 " +"Python 修正錯誤的過程中，所有問題的答案。" diff --git a/c-api/abstract.po b/c-api/abstract.po index ef695f4ea5..d54530ee77 100644 --- a/c-api/abstract.po +++ b/c-api/abstract.po @@ -1,47 +1,47 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# aminzai , 2017 -# Matt Wang , 2021 -# -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2018-06-26 18:54+0800\n" -"PO-Revision-Date: 2021-12-09 21:20+0800\n" -"Last-Translator: Matt Wang \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" -"X-Generator: Poedit 3.0\n" - -#: ../../c-api/abstract.rst:7 -msgid "Abstract Objects Layer" -msgstr "抽象物件層 (Abstract Objects Layer)" - -#: ../../c-api/abstract.rst:9 -msgid "" -"The functions in this chapter interact with Python objects regardless of " -"their type, or with wide classes of object types (e.g. all numerical types, " -"or all sequence types). When used on object types for which they do not " -"apply, they will raise a Python exception." -msgstr "" -"本章中的函式與 Python 物件相互作用，無論其型別、或具有廣泛類別的物件型別（例" -"如所有數值型別或所有序列型別）。當使用於不適用的物件型別時，他們會引發一個 " -"Python 異常 (exception)。" - -#: ../../c-api/abstract.rst:14 -msgid "" -"It is not possible to use these functions on objects that are not properly " -"initialized, such as a list object that has been created by :c:func:" -"`PyList_New`, but whose items have not been set to some non-\\ ``NULL`` " -"value yet." -msgstr "" -"這些函式是不可能用於未正確初始化的物件（例如一個由 :c:func:`PyList_New` 建立" -"的 list 物件），而其中的項目沒有被設為一些非 ``NULL`` 的值。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# aminzai , 2017 +# Matt Wang , 2021 +# +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2018-06-26 18:54+0800\n" +"PO-Revision-Date: 2021-12-09 21:20+0800\n" +"Last-Translator: Matt Wang \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" +"X-Generator: Poedit 3.0\n" + +#: ../../c-api/abstract.rst:7 +msgid "Abstract Objects Layer" +msgstr "抽象物件層 (Abstract Objects Layer)" + +#: ../../c-api/abstract.rst:9 +msgid "" +"The functions in this chapter interact with Python objects regardless of " +"their type, or with wide classes of object types (e.g. all numerical types, " +"or all sequence types). When used on object types for which they do not " +"apply, they will raise a Python exception." +msgstr "" +"本章中的函式與 Python 物件相互作用，無論其型別、或具有廣泛類別的物件型別（例" +"如所有數值型別或所有序列型別）。當使用於不適用的物件型別時，他們會引發一個 " +"Python 異常 (exception)。" + +#: ../../c-api/abstract.rst:14 +msgid "" +"It is not possible to use these functions on objects that are not properly " +"initialized, such as a list object that has been created by :c:func:" +"`PyList_New`, but whose items have not been set to some non-\\ ``NULL`` " +"value yet." +msgstr "" +"這些函式是不可能用於未正確初始化的物件（例如一個由 :c:func:`PyList_New` 建立" +"的 list 物件），而其中的項目沒有被設為一些非 ``NULL`` 的值。" diff --git a/c-api/allocation.po b/c-api/allocation.po index 616ca9afcf..8fa64a7883 100644 --- a/c-api/allocation.po +++ b/c-api/allocation.po @@ -1,256 +1,256 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Liang-Bo Wang , 2016 -# Matt Wang , 2021 -# -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-09 17:02+0000\n" -"PO-Revision-Date: 2022-10-16 15:35+0800\n" -"Last-Translator: Matt Wang \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" -"X-Generator: Poedit 3.1.1\n" - -#: ../../c-api/allocation.rst:6 -msgid "Allocating Objects on the Heap" -msgstr "在 heap 上分配物件" - -#: ../../c-api/allocation.rst:17 -msgid "" -"Initialize a newly allocated object *op* with its type and initial " -"reference. Returns the initialized object. Other fields of the object are " -"not initialized. Despite its name, this function is unrelated to the " -"object's :meth:`~object.__init__` method (:c:member:`~PyTypeObject.tp_init` " -"slot). Specifically, this function does **not** call the object's :meth:`!" -"__init__` method." -msgstr "" - -#: ../../c-api/allocation.rst:24 -msgid "" -"In general, consider this function to be a low-level routine. Use :c:member:" -"`~PyTypeObject.tp_alloc` where possible. For implementing :c:member:`!" -"tp_alloc` for your type, prefer :c:func:`PyType_GenericAlloc` or :c:func:" -"`PyObject_New`." -msgstr "" - -#: ../../c-api/allocation.rst:31 -msgid "" -"This function only initializes the object's memory corresponding to the " -"initial :c:type:`PyObject` structure. It does not zero the rest." -msgstr "" - -#: ../../c-api/allocation.rst:37 -msgid "" -"This does everything :c:func:`PyObject_Init` does, and also initializes the " -"length information for a variable-size object." -msgstr "" -"它會做到 :c:func:`PyObject_Init` 的所有功能，並且會初始化一個大小可變物件的長" -"度資訊。" - -#: ../../c-api/allocation.rst:42 -msgid "" -"This function only initializes some of the object's memory. It does not " -"zero the rest." -msgstr "" - -#: ../../c-api/allocation.rst:48 -msgid "" -"Allocates a new Python object using the C structure type *TYPE* and the " -"Python type object *typeobj* (``PyTypeObject*``) by calling :c:func:" -"`PyObject_Malloc` to allocate memory and initializing it like :c:func:" -"`PyObject_Init`. The caller will own the only reference to the object (i.e. " -"its reference count will be one)." -msgstr "" -"使用 C 結構型別 *TYPE* 和 Python 型別物件 *typeobj* (``PyTypeObject*``) 分配" -"一個新的 Python 物件。它會呼叫 :c:func:`PyObject_Malloc` 來分配記憶體，並且會" -"像 :c:func:`PyObject_Init` 一樣初始化它。呼叫者會擁有該物件的唯一參照（也就是" -"它的參照計數會是 1）。" - -#: ../../c-api/allocation.rst:54 ../../c-api/allocation.rst:107 -msgid "" -"Avoid calling this directly to allocate memory for an object; call the " -"type's :c:member:`~PyTypeObject.tp_alloc` slot instead." -msgstr "" - -#: ../../c-api/allocation.rst:57 ../../c-api/allocation.rst:110 -msgid "" -"When populating a type's :c:member:`~PyTypeObject.tp_alloc` slot, :c:func:" -"`PyType_GenericAlloc` is preferred over a custom function that simply calls " -"this macro." -msgstr "" - -#: ../../c-api/allocation.rst:61 -msgid "" -"This macro does not call :c:member:`~PyTypeObject.tp_alloc`, :c:member:" -"`~PyTypeObject.tp_new` (:meth:`~object.__new__`), or :c:member:" -"`~PyTypeObject.tp_init` (:meth:`~object.__init__`)." -msgstr "" -"這個巨集不會呼叫 :c:member:`~PyTypeObject.tp_alloc`、:c:member:" -"`~PyTypeObject.tp_new` (:meth:`~object.__new__`)、或 :c:member:" -"`~PyTypeObject.tp_init` (:meth:`~object.__init__`)。" - -#: ../../c-api/allocation.rst:65 -msgid "" -"This cannot be used for objects with :c:macro:`Py_TPFLAGS_HAVE_GC` set in :c:" -"member:`~PyTypeObject.tp_flags`; use :c:macro:`PyObject_GC_New` instead." -msgstr "" -"這不能用於有在 :c:member:`~PyTypeObject.tp_flags` 中設定 :c:macro:" -"`Py_TPFLAGS_HAVE_GC` 的物件；請改用 :c:macro:`PyObject_GC_New`。" - -#: ../../c-api/allocation.rst:68 -msgid "" -"Memory allocated by this macro must be freed with :c:func:`PyObject_Free` " -"(usually called via the object's :c:member:`~PyTypeObject.tp_free` slot)." -msgstr "" - -#: ../../c-api/allocation.rst:73 ../../c-api/allocation.rst:123 -msgid "" -"The returned memory is not guaranteed to have been completely zeroed before " -"it was initialized." -msgstr "" - -#: ../../c-api/allocation.rst:78 ../../c-api/allocation.rst:128 -msgid "" -"This macro does not construct a fully initialized object of the given type; " -"it merely allocates memory and prepares it for further initialization by :c:" -"member:`~PyTypeObject.tp_init`. To construct a fully initialized object, " -"call *typeobj* instead. For example::" -msgstr "" - -#: ../../c-api/allocation.rst:83 -msgid "PyObject *foo = PyObject_CallNoArgs((PyObject *)&PyFoo_Type);" -msgstr "PyObject *foo = PyObject_CallNoArgs((PyObject *)&PyFoo_Type);" - -#: ../../c-api/allocation.rst:87 ../../c-api/allocation.rst:137 -#: ../../c-api/allocation.rst:182 ../../c-api/allocation.rst:184 -#: ../../c-api/allocation.rst:186 -msgid ":c:func:`PyObject_Free`" -msgstr ":c:func:`PyObject_Free`" - -#: ../../c-api/allocation.rst:88 -msgid ":c:macro:`PyObject_GC_New`" -msgstr ":c:macro:`PyObject_GC_New`" - -#: ../../c-api/allocation.rst:89 ../../c-api/allocation.rst:139 -msgid ":c:func:`PyType_GenericAlloc`" -msgstr ":c:func:`PyType_GenericAlloc`" - -#: ../../c-api/allocation.rst:90 ../../c-api/allocation.rst:140 -msgid ":c:member:`~PyTypeObject.tp_alloc`" -msgstr ":c:member:`~PyTypeObject.tp_alloc`" - -#: ../../c-api/allocation.rst:95 -msgid "Like :c:macro:`PyObject_New` except:" -msgstr "和 :c:macro:`PyObject_New` 類似，但有以下差異：" - -#: ../../c-api/allocation.rst:97 -msgid "" -"It allocates enough memory for the *TYPE* structure plus *size* " -"(``Py_ssize_t``) fields of the size given by the :c:member:`~PyTypeObject." -"tp_itemsize` field of *typeobj*." -msgstr "" - -#: ../../c-api/allocation.rst:100 -msgid "The memory is initialized like :c:func:`PyObject_InitVar`." -msgstr "記憶體會像 :c:func:`PyObject_InitVar` 一樣被初始化。" - -#: ../../c-api/allocation.rst:102 -msgid "" -"This is useful for implementing objects like tuples, which are able to " -"determine their size at construction time. Embedding the array of fields " -"into the same allocation decreases the number of allocations, improving the " -"memory management efficiency." -msgstr "" - -#: ../../c-api/allocation.rst:114 -msgid "" -"This cannot be used for objects with :c:macro:`Py_TPFLAGS_HAVE_GC` set in :c:" -"member:`~PyTypeObject.tp_flags`; use :c:macro:`PyObject_GC_NewVar` instead." -msgstr "" -"這不能用於有在 :c:member:`~PyTypeObject.tp_flags` 中設定 :c:macro:" -"`Py_TPFLAGS_HAVE_GC` 的物件；請改用 :c:macro:`PyObject_GC_NewVar`。" - -#: ../../c-api/allocation.rst:118 -msgid "" -"Memory allocated by this function must be freed with :c:func:`PyObject_Free` " -"(usually called via the object's :c:member:`~PyTypeObject.tp_free` slot)." -msgstr "" - -#: ../../c-api/allocation.rst:133 -msgid "" -"PyObject *list_instance = PyObject_CallNoArgs((PyObject *)&PyList_Type);" -msgstr "" -"PyObject *list_instance = PyObject_CallNoArgs((PyObject *)&PyList_Type);" - -#: ../../c-api/allocation.rst:138 -msgid ":c:macro:`PyObject_GC_NewVar`" -msgstr ":c:macro:`PyObject_GC_NewVar`" - -#: ../../c-api/allocation.rst:145 -msgid "" -"Object which is visible in Python as ``None``. This should only be accessed " -"using the :c:macro:`Py_None` macro, which evaluates to a pointer to this " -"object." -msgstr "" -"這個物件像是 Python 中的 ``None``。它只應該透過 :c:macro:`Py_None` 巨集來存" -"取，該巨集的拿到指向該物件的指標。" - -#: ../../c-api/allocation.rst:152 -msgid ":ref:`moduleobjects`" -msgstr ":ref:`moduleobjects`" - -#: ../../c-api/allocation.rst:153 -msgid "To allocate and create extension modules." -msgstr "分配記憶體和建立擴充模組。" - -#: ../../c-api/allocation.rst:157 -msgid "Deprecated aliases" -msgstr "被棄用的別名" - -#: ../../c-api/allocation.rst:159 -msgid "" -"These are :term:`soft deprecated` aliases to existing functions and macros. " -"They exist solely for backwards compatibility." -msgstr "" - -#: ../../c-api/allocation.rst:167 -msgid "Deprecated alias" -msgstr "已棄用的別名" - -#: ../../c-api/allocation.rst:168 -msgid "Function" -msgstr "函式" - -#: ../../c-api/allocation.rst:170 -msgid ":c:macro:`PyObject_New`" -msgstr ":c:macro:`PyObject_New`" - -#: ../../c-api/allocation.rst:172 -msgid ":c:macro:`PyObject_NewVar`" -msgstr ":c:macro:`PyObject_NewVar`" - -#: ../../c-api/allocation.rst:174 -msgid ":c:func:`PyObject_Init`" -msgstr ":c:func:`PyObject_Init`" - -#: ../../c-api/allocation.rst:176 -msgid ":c:func:`PyObject_InitVar`" -msgstr ":c:func:`PyObject_InitVar`" - -#: ../../c-api/allocation.rst:178 -msgid ":c:func:`PyObject_Malloc`" -msgstr ":c:func:`PyObject_Malloc`" - -#: ../../c-api/allocation.rst:180 -msgid ":c:func:`PyObject_Realloc`" -msgstr ":c:func:`PyObject_Realloc`" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Liang-Bo Wang , 2016 +# Matt Wang , 2021 +# +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-09 17:02+0000\n" +"PO-Revision-Date: 2022-10-16 15:35+0800\n" +"Last-Translator: Matt Wang \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" +"X-Generator: Poedit 3.1.1\n" + +#: ../../c-api/allocation.rst:6 +msgid "Allocating Objects on the Heap" +msgstr "在 heap 上分配物件" + +#: ../../c-api/allocation.rst:17 +msgid "" +"Initialize a newly allocated object *op* with its type and initial " +"reference. Returns the initialized object. Other fields of the object are " +"not initialized. Despite its name, this function is unrelated to the " +"object's :meth:`~object.__init__` method (:c:member:`~PyTypeObject.tp_init` " +"slot). Specifically, this function does **not** call the object's :meth:`!" +"__init__` method." +msgstr "" + +#: ../../c-api/allocation.rst:24 +msgid "" +"In general, consider this function to be a low-level routine. Use :c:member:" +"`~PyTypeObject.tp_alloc` where possible. For implementing :c:member:`!" +"tp_alloc` for your type, prefer :c:func:`PyType_GenericAlloc` or :c:func:" +"`PyObject_New`." +msgstr "" + +#: ../../c-api/allocation.rst:31 +msgid "" +"This function only initializes the object's memory corresponding to the " +"initial :c:type:`PyObject` structure. It does not zero the rest." +msgstr "" + +#: ../../c-api/allocation.rst:37 +msgid "" +"This does everything :c:func:`PyObject_Init` does, and also initializes the " +"length information for a variable-size object." +msgstr "" +"它會做到 :c:func:`PyObject_Init` 的所有功能，並且會初始化一個大小可變物件的長" +"度資訊。" + +#: ../../c-api/allocation.rst:42 +msgid "" +"This function only initializes some of the object's memory. It does not " +"zero the rest." +msgstr "" + +#: ../../c-api/allocation.rst:48 +msgid "" +"Allocates a new Python object using the C structure type *TYPE* and the " +"Python type object *typeobj* (``PyTypeObject*``) by calling :c:func:" +"`PyObject_Malloc` to allocate memory and initializing it like :c:func:" +"`PyObject_Init`. The caller will own the only reference to the object (i.e. " +"its reference count will be one)." +msgstr "" +"使用 C 結構型別 *TYPE* 和 Python 型別物件 *typeobj* (``PyTypeObject*``) 分配" +"一個新的 Python 物件。它會呼叫 :c:func:`PyObject_Malloc` 來分配記憶體，並且會" +"像 :c:func:`PyObject_Init` 一樣初始化它。呼叫者會擁有該物件的唯一參照（也就是" +"它的參照計數會是 1）。" + +#: ../../c-api/allocation.rst:54 ../../c-api/allocation.rst:107 +msgid "" +"Avoid calling this directly to allocate memory for an object; call the " +"type's :c:member:`~PyTypeObject.tp_alloc` slot instead." +msgstr "" + +#: ../../c-api/allocation.rst:57 ../../c-api/allocation.rst:110 +msgid "" +"When populating a type's :c:member:`~PyTypeObject.tp_alloc` slot, :c:func:" +"`PyType_GenericAlloc` is preferred over a custom function that simply calls " +"this macro." +msgstr "" + +#: ../../c-api/allocation.rst:61 +msgid "" +"This macro does not call :c:member:`~PyTypeObject.tp_alloc`, :c:member:" +"`~PyTypeObject.tp_new` (:meth:`~object.__new__`), or :c:member:" +"`~PyTypeObject.tp_init` (:meth:`~object.__init__`)." +msgstr "" +"這個巨集不會呼叫 :c:member:`~PyTypeObject.tp_alloc`、:c:member:" +"`~PyTypeObject.tp_new` (:meth:`~object.__new__`)、或 :c:member:" +"`~PyTypeObject.tp_init` (:meth:`~object.__init__`)。" + +#: ../../c-api/allocation.rst:65 +msgid "" +"This cannot be used for objects with :c:macro:`Py_TPFLAGS_HAVE_GC` set in :c:" +"member:`~PyTypeObject.tp_flags`; use :c:macro:`PyObject_GC_New` instead." +msgstr "" +"這不能用於有在 :c:member:`~PyTypeObject.tp_flags` 中設定 :c:macro:" +"`Py_TPFLAGS_HAVE_GC` 的物件；請改用 :c:macro:`PyObject_GC_New`。" + +#: ../../c-api/allocation.rst:68 +msgid "" +"Memory allocated by this macro must be freed with :c:func:`PyObject_Free` " +"(usually called via the object's :c:member:`~PyTypeObject.tp_free` slot)." +msgstr "" + +#: ../../c-api/allocation.rst:73 ../../c-api/allocation.rst:123 +msgid "" +"The returned memory is not guaranteed to have been completely zeroed before " +"it was initialized." +msgstr "" + +#: ../../c-api/allocation.rst:78 ../../c-api/allocation.rst:128 +msgid "" +"This macro does not construct a fully initialized object of the given type; " +"it merely allocates memory and prepares it for further initialization by :c:" +"member:`~PyTypeObject.tp_init`. To construct a fully initialized object, " +"call *typeobj* instead. For example::" +msgstr "" + +#: ../../c-api/allocation.rst:83 +msgid "PyObject *foo = PyObject_CallNoArgs((PyObject *)&PyFoo_Type);" +msgstr "PyObject *foo = PyObject_CallNoArgs((PyObject *)&PyFoo_Type);" + +#: ../../c-api/allocation.rst:87 ../../c-api/allocation.rst:137 +#: ../../c-api/allocation.rst:182 ../../c-api/allocation.rst:184 +#: ../../c-api/allocation.rst:186 +msgid ":c:func:`PyObject_Free`" +msgstr ":c:func:`PyObject_Free`" + +#: ../../c-api/allocation.rst:88 +msgid ":c:macro:`PyObject_GC_New`" +msgstr ":c:macro:`PyObject_GC_New`" + +#: ../../c-api/allocation.rst:89 ../../c-api/allocation.rst:139 +msgid ":c:func:`PyType_GenericAlloc`" +msgstr ":c:func:`PyType_GenericAlloc`" + +#: ../../c-api/allocation.rst:90 ../../c-api/allocation.rst:140 +msgid ":c:member:`~PyTypeObject.tp_alloc`" +msgstr ":c:member:`~PyTypeObject.tp_alloc`" + +#: ../../c-api/allocation.rst:95 +msgid "Like :c:macro:`PyObject_New` except:" +msgstr "和 :c:macro:`PyObject_New` 類似，但有以下差異：" + +#: ../../c-api/allocation.rst:97 +msgid "" +"It allocates enough memory for the *TYPE* structure plus *size* " +"(``Py_ssize_t``) fields of the size given by the :c:member:`~PyTypeObject." +"tp_itemsize` field of *typeobj*." +msgstr "" + +#: ../../c-api/allocation.rst:100 +msgid "The memory is initialized like :c:func:`PyObject_InitVar`." +msgstr "記憶體會像 :c:func:`PyObject_InitVar` 一樣被初始化。" + +#: ../../c-api/allocation.rst:102 +msgid "" +"This is useful for implementing objects like tuples, which are able to " +"determine their size at construction time. Embedding the array of fields " +"into the same allocation decreases the number of allocations, improving the " +"memory management efficiency." +msgstr "" + +#: ../../c-api/allocation.rst:114 +msgid "" +"This cannot be used for objects with :c:macro:`Py_TPFLAGS_HAVE_GC` set in :c:" +"member:`~PyTypeObject.tp_flags`; use :c:macro:`PyObject_GC_NewVar` instead." +msgstr "" +"這不能用於有在 :c:member:`~PyTypeObject.tp_flags` 中設定 :c:macro:" +"`Py_TPFLAGS_HAVE_GC` 的物件；請改用 :c:macro:`PyObject_GC_NewVar`。" + +#: ../../c-api/allocation.rst:118 +msgid "" +"Memory allocated by this function must be freed with :c:func:`PyObject_Free` " +"(usually called via the object's :c:member:`~PyTypeObject.tp_free` slot)." +msgstr "" + +#: ../../c-api/allocation.rst:133 +msgid "" +"PyObject *list_instance = PyObject_CallNoArgs((PyObject *)&PyList_Type);" +msgstr "" +"PyObject *list_instance = PyObject_CallNoArgs((PyObject *)&PyList_Type);" + +#: ../../c-api/allocation.rst:138 +msgid ":c:macro:`PyObject_GC_NewVar`" +msgstr ":c:macro:`PyObject_GC_NewVar`" + +#: ../../c-api/allocation.rst:145 +msgid "" +"Object which is visible in Python as ``None``. This should only be accessed " +"using the :c:macro:`Py_None` macro, which evaluates to a pointer to this " +"object." +msgstr "" +"這個物件像是 Python 中的 ``None``。它只應該透過 :c:macro:`Py_None` 巨集來存" +"取，該巨集的拿到指向該物件的指標。" + +#: ../../c-api/allocation.rst:152 +msgid ":ref:`moduleobjects`" +msgstr ":ref:`moduleobjects`" + +#: ../../c-api/allocation.rst:153 +msgid "To allocate and create extension modules." +msgstr "分配記憶體和建立擴充模組。" + +#: ../../c-api/allocation.rst:157 +msgid "Deprecated aliases" +msgstr "被棄用的別名" + +#: ../../c-api/allocation.rst:159 +msgid "" +"These are :term:`soft deprecated` aliases to existing functions and macros. " +"They exist solely for backwards compatibility." +msgstr "" + +#: ../../c-api/allocation.rst:167 +msgid "Deprecated alias" +msgstr "已棄用的別名" + +#: ../../c-api/allocation.rst:168 +msgid "Function" +msgstr "函式" + +#: ../../c-api/allocation.rst:170 +msgid ":c:macro:`PyObject_New`" +msgstr ":c:macro:`PyObject_New`" + +#: ../../c-api/allocation.rst:172 +msgid ":c:macro:`PyObject_NewVar`" +msgstr ":c:macro:`PyObject_NewVar`" + +#: ../../c-api/allocation.rst:174 +msgid ":c:func:`PyObject_Init`" +msgstr ":c:func:`PyObject_Init`" + +#: ../../c-api/allocation.rst:176 +msgid ":c:func:`PyObject_InitVar`" +msgstr ":c:func:`PyObject_InitVar`" + +#: ../../c-api/allocation.rst:178 +msgid ":c:func:`PyObject_Malloc`" +msgstr ":c:func:`PyObject_Malloc`" + +#: ../../c-api/allocation.rst:180 +msgid ":c:func:`PyObject_Realloc`" +msgstr ":c:func:`PyObject_Realloc`" diff --git a/c-api/apiabiversion.po b/c-api/apiabiversion.po index ac7a67f22c..772d791cae 100644 --- a/c-api/apiabiversion.po +++ b/c-api/apiabiversion.po @@ -1,302 +1,302 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Liang-Bo Wang , 2015 -# Matt Wang , 2022 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: 2022-01-24 22:34+0800\n" -"Last-Translator: Matt Wang \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" -"X-Generator: Poedit 3.0.1\n" - -#: ../../c-api/apiabiversion.rst:7 -msgid "API and ABI Versioning" -msgstr "API 和 ABI 版本管理" - -#: ../../c-api/apiabiversion.rst:11 -msgid "Build-time version constants" -msgstr "" - -#: ../../c-api/apiabiversion.rst:13 -msgid "" -"CPython exposes its version number in the following macros. Note that these " -"correspond to the version code is **built** with. See :c:var:`Py_Version` " -"for the version used at **run time**." -msgstr "" -"CPython 透過以下巨集 (macro) 公開其版本號。請注意，對應到的是\\ **建置 " -"(built)** 所用到的版本。關於\\ **run time** 所使用的版本，請見 :c:var:`Py_Version`。" - -#: ../../c-api/apiabiversion.rst:17 -msgid "" -"See :ref:`stable` for a discussion of API and ABI stability across versions." -msgstr "關於跨版本 API 和 ABI 穩定性的討論，請見 :ref:`stable`。" - -#: ../../c-api/apiabiversion.rst:21 -msgid "The ``3`` in ``3.4.1a2``." -msgstr "在 ``3.4.1a2`` 中的 ``3``。" - -#: ../../c-api/apiabiversion.rst:25 -msgid "The ``4`` in ``3.4.1a2``." -msgstr "在 ``3.4.1a2`` 中的 ``4``。" - -#: ../../c-api/apiabiversion.rst:29 -msgid "The ``1`` in ``3.4.1a2``." -msgstr "在 ``3.4.1a2`` 中的 ``1``。" - -#: ../../c-api/apiabiversion.rst:33 -msgid "" -"The ``a`` in ``3.4.1a2``. This can be ``0xA`` for alpha, ``0xB`` for beta, " -"``0xC`` for release candidate or ``0xF`` for final." -msgstr "" -"在 ``3.4.1a2`` 中的 ``a``。``0xA`` 代表 alpha 版本、``0xB`` 代表 beta 版本、" -"``0xC`` 為發布候選版本、``0xF`` 則為最終版。" - -#: ../../c-api/apiabiversion.rst:39 -msgid "The ``2`` in ``3.4.1a2``. Zero for final releases." -msgstr "在 ``3.4.1a2`` 中的 ``2``。零則為最終發布版本。" - -#: ../../c-api/apiabiversion.rst:43 -msgid "" -"The Python version number encoded in a single integer. " -"See :c:func:`Py_PACK_FULL_VERSION` for the encoding details." -msgstr "被編碼為單一整數的 Python 版本號。詳見 :c:func:`Py_PACK_FULL_VERSION` 以了解編碼詳細資訊。" - -#: ../../c-api/apiabiversion.rst:46 -msgid "" -"Use this for numeric comparisons, for example, ``#if PY_VERSION_HEX >= ...``." -msgstr "使用它進行數值比較，例如 ``#if PY_VERSION_HEX >= ...``。" - -#: ../../c-api/apiabiversion.rst:51 -msgid "Run-time version" -msgstr "" - -#: ../../c-api/apiabiversion.rst:55 -msgid "" -"The Python runtime version number encoded in a single constant integer. " -"See :c:func:`Py_PACK_FULL_VERSION` for the encoding details. This contains " -"the Python version used at run time." -msgstr "" -"編碼為單個常數整數的 Python runtime 版本號。詳見 :c:func:`Py_PACK_FULL_VERSION` " -"以了解編碼詳細資訊。這包含在 runtime 使用的 Python 版本。" - -#: ../../c-api/apiabiversion.rst:59 -msgid "" -"Use this for numeric comparisons, for example, ``if (Py_Version >= ...)``." -msgstr "使用它進行數值比較，例如 ``if (Py_Version >= ...)``。" - -#: ../../c-api/apiabiversion.rst:65 -msgid "Bit-packing macros" -msgstr "" - -#: ../../c-api/apiabiversion.rst:69 -msgid "" -"Return the given version, encoded as a single 32-bit integer with the " -"following structure:" -msgstr "" - -#: ../../c-api/apiabiversion.rst:75 -msgid "Argument" -msgstr "引數" - -#: ../../c-api/apiabiversion.rst:73 -msgid "No. of bits" -msgstr "" - -#: ../../c-api/apiabiversion.rst:75 -msgid "Bit mask" -msgstr "" - -#: ../../c-api/apiabiversion.rst:75 -msgid "Bit shift" -msgstr "" - -#: ../../c-api/apiabiversion.rst:73 -msgid "Example values" -msgstr "" - -#: ../../c-api/apiabiversion.rst:75 ../../c-api/apiabiversion.rst:93 -msgid "``3.4.1a2``" -msgstr "``3.4.1a2``" - -#: ../../c-api/apiabiversion.rst:75 ../../c-api/apiabiversion.rst:95 -msgid "``3.10.0``" -msgstr "``3.10.0``" - -#: ../../c-api/apiabiversion.rst:77 -msgid "*major*" -msgstr "*major*" - -#: ../../c-api/apiabiversion.rst:77 ../../c-api/apiabiversion.rst:79 -#: ../../c-api/apiabiversion.rst:81 -msgid "8" -msgstr "8" - -#: ../../c-api/apiabiversion.rst:77 -msgid "``0xFF000000``" -msgstr "``0xFF000000``" - -#: ../../c-api/apiabiversion.rst:77 -msgid "24" -msgstr "24" - -#: ../../c-api/apiabiversion.rst:77 -msgid "``0x03``" -msgstr "``0x03``" - -#: ../../c-api/apiabiversion.rst:79 -msgid "*minor*" -msgstr "" - -#: ../../c-api/apiabiversion.rst:79 -msgid "``0x00FF0000``" -msgstr "``0x00FF0000``" - -#: ../../c-api/apiabiversion.rst:79 -msgid "16" -msgstr "16" - -#: ../../c-api/apiabiversion.rst:79 -msgid "``0x04``" -msgstr "``0x04``" - -#: ../../c-api/apiabiversion.rst:79 -msgid "``0x0A``" -msgstr "``0x0A``" - -#: ../../c-api/apiabiversion.rst:81 -msgid "*micro*" -msgstr "*micro*" - -#: ../../c-api/apiabiversion.rst:81 -msgid "``0x0000FF00``" -msgstr "``0x0000FF00``" - -#: ../../c-api/apiabiversion.rst:81 -msgid "``0x01``" -msgstr "``0x01``" - -#: ../../c-api/apiabiversion.rst:81 -msgid "``0x00``" -msgstr "``0x00``" - -#: ../../c-api/apiabiversion.rst:83 -msgid "*release_level*" -msgstr "*release_level*" - -#: ../../c-api/apiabiversion.rst:83 ../../c-api/apiabiversion.rst:85 -msgid "4" -msgstr "4" - -#: ../../c-api/apiabiversion.rst:83 -msgid "``0x000000F0``" -msgstr "``0x000000F0``" - -#: ../../c-api/apiabiversion.rst:83 -msgid "``0xA``" -msgstr "``0xA``" - -#: ../../c-api/apiabiversion.rst:83 -msgid "``0xF``" -msgstr "``0xF``" - -#: ../../c-api/apiabiversion.rst:85 -msgid "*release_serial*" -msgstr "*release_serial*" - -#: ../../c-api/apiabiversion.rst:85 -msgid "``0x0000000F``" -msgstr "``0x0000000F``" - -#: ../../c-api/apiabiversion.rst:85 -msgid "0" -msgstr "0" - -#: ../../c-api/apiabiversion.rst:85 -msgid "``0x2``" -msgstr "``0x2``" - -#: ../../c-api/apiabiversion.rst:85 -msgid "``0x0``" -msgstr "``0x0``" - -#: ../../c-api/apiabiversion.rst:88 -msgid "For example:" -msgstr "例如：" - -#: ../../c-api/apiabiversion.rst:91 -msgid "Version" -msgstr "版本" - -#: ../../c-api/apiabiversion.rst:91 -msgid "``Py_PACK_FULL_VERSION`` arguments" -msgstr "``Py_PACK_FULL_VERSION`` 引數" - -#: ../../c-api/apiabiversion.rst:91 -msgid "Encoded version" -msgstr "" - -#: ../../c-api/apiabiversion.rst:93 -msgid "``(3, 4, 1, 0xA, 2)``" -msgstr "``(3, 4, 1, 0xA, 2)``" - -#: ../../c-api/apiabiversion.rst:93 -msgid "``0x030401a2``" -msgstr "``0x030401a2``" - -#: ../../c-api/apiabiversion.rst:95 -msgid "``(3, 10, 0, 0xF, 0)``" -msgstr "``(3, 10, 0, 0xF, 0)``" - -#: ../../c-api/apiabiversion.rst:95 -msgid "``0x030a00f0``" -msgstr "``0x030a00f0``" - -#: ../../c-api/apiabiversion.rst:98 -msgid "" -"Out-of range bits in the arguments are ignored. That is, the macro can be " -"defined as:" -msgstr "" - -#: ../../c-api/apiabiversion.rst:101 -msgid "" -"#ifndef Py_PACK_FULL_VERSION\n" -"#define Py_PACK_FULL_VERSION(X, Y, Z, LEVEL, SERIAL) ( \\\n" -" (((X) & 0xff) << 24) | \\\n" -" (((Y) & 0xff) << 16) | \\\n" -" (((Z) & 0xff) << 8) | \\\n" -" (((LEVEL) & 0xf) << 4) | \\\n" -" (((SERIAL) & 0xf) << 0))\n" -"#endif" -msgstr "" -"#ifndef Py_PACK_FULL_VERSION\n" -"#define Py_PACK_FULL_VERSION(X, Y, Z, LEVEL, SERIAL) ( \\\n" -" (((X) & 0xff) << 24) | \\\n" -" (((Y) & 0xff) << 16) | \\\n" -" (((Z) & 0xff) << 8) | \\\n" -" (((LEVEL) & 0xf) << 4) | \\\n" -" (((SERIAL) & 0xf) << 0))\n" -"#endif" - -#: ../../c-api/apiabiversion.rst:112 -msgid "" -"``Py_PACK_FULL_VERSION`` is primarily a macro, intended for use in ``#if`` " -"directives, but it is also available as an exported function." -msgstr "" - -#: ../../c-api/apiabiversion.rst:119 -msgid "" -"Equivalent to ``Py_PACK_FULL_VERSION(major, minor, 0, 0, 0)``. The result " -"does not correspond to any Python release, but is useful in numeric " -"comparisons." -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Liang-Bo Wang , 2015 +# Matt Wang , 2022 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: 2022-01-24 22:34+0800\n" +"Last-Translator: Matt Wang \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" +"X-Generator: Poedit 3.0.1\n" + +#: ../../c-api/apiabiversion.rst:7 +msgid "API and ABI Versioning" +msgstr "API 和 ABI 版本管理" + +#: ../../c-api/apiabiversion.rst:11 +msgid "Build-time version constants" +msgstr "" + +#: ../../c-api/apiabiversion.rst:13 +msgid "" +"CPython exposes its version number in the following macros. Note that these " +"correspond to the version code is **built** with. See :c:var:`Py_Version` " +"for the version used at **run time**." +msgstr "" +"CPython 透過以下巨集 (macro) 公開其版本號。請注意，對應到的是\\ **建置 " +"(built)** 所用到的版本。關於\\ **run time** 所使用的版本，請見 :c:var:`Py_Version`。" + +#: ../../c-api/apiabiversion.rst:17 +msgid "" +"See :ref:`stable` for a discussion of API and ABI stability across versions." +msgstr "關於跨版本 API 和 ABI 穩定性的討論，請見 :ref:`stable`。" + +#: ../../c-api/apiabiversion.rst:21 +msgid "The ``3`` in ``3.4.1a2``." +msgstr "在 ``3.4.1a2`` 中的 ``3``。" + +#: ../../c-api/apiabiversion.rst:25 +msgid "The ``4`` in ``3.4.1a2``." +msgstr "在 ``3.4.1a2`` 中的 ``4``。" + +#: ../../c-api/apiabiversion.rst:29 +msgid "The ``1`` in ``3.4.1a2``." +msgstr "在 ``3.4.1a2`` 中的 ``1``。" + +#: ../../c-api/apiabiversion.rst:33 +msgid "" +"The ``a`` in ``3.4.1a2``. This can be ``0xA`` for alpha, ``0xB`` for beta, " +"``0xC`` for release candidate or ``0xF`` for final." +msgstr "" +"在 ``3.4.1a2`` 中的 ``a``。``0xA`` 代表 alpha 版本、``0xB`` 代表 beta 版本、" +"``0xC`` 為發布候選版本、``0xF`` 則為最終版。" + +#: ../../c-api/apiabiversion.rst:39 +msgid "The ``2`` in ``3.4.1a2``. Zero for final releases." +msgstr "在 ``3.4.1a2`` 中的 ``2``。零則為最終發布版本。" + +#: ../../c-api/apiabiversion.rst:43 +msgid "" +"The Python version number encoded in a single integer. " +"See :c:func:`Py_PACK_FULL_VERSION` for the encoding details." +msgstr "被編碼為單一整數的 Python 版本號。詳見 :c:func:`Py_PACK_FULL_VERSION` 以了解編碼詳細資訊。" + +#: ../../c-api/apiabiversion.rst:46 +msgid "" +"Use this for numeric comparisons, for example, ``#if PY_VERSION_HEX >= ...``." +msgstr "使用它進行數值比較，例如 ``#if PY_VERSION_HEX >= ...``。" + +#: ../../c-api/apiabiversion.rst:51 +msgid "Run-time version" +msgstr "" + +#: ../../c-api/apiabiversion.rst:55 +msgid "" +"The Python runtime version number encoded in a single constant integer. " +"See :c:func:`Py_PACK_FULL_VERSION` for the encoding details. This contains " +"the Python version used at run time." +msgstr "" +"編碼為單個常數整數的 Python runtime 版本號。詳見 :c:func:`Py_PACK_FULL_VERSION` " +"以了解編碼詳細資訊。這包含在 runtime 使用的 Python 版本。" + +#: ../../c-api/apiabiversion.rst:59 +msgid "" +"Use this for numeric comparisons, for example, ``if (Py_Version >= ...)``." +msgstr "使用它進行數值比較，例如 ``if (Py_Version >= ...)``。" + +#: ../../c-api/apiabiversion.rst:65 +msgid "Bit-packing macros" +msgstr "" + +#: ../../c-api/apiabiversion.rst:69 +msgid "" +"Return the given version, encoded as a single 32-bit integer with the " +"following structure:" +msgstr "" + +#: ../../c-api/apiabiversion.rst:75 +msgid "Argument" +msgstr "引數" + +#: ../../c-api/apiabiversion.rst:73 +msgid "No. of bits" +msgstr "" + +#: ../../c-api/apiabiversion.rst:75 +msgid "Bit mask" +msgstr "" + +#: ../../c-api/apiabiversion.rst:75 +msgid "Bit shift" +msgstr "" + +#: ../../c-api/apiabiversion.rst:73 +msgid "Example values" +msgstr "" + +#: ../../c-api/apiabiversion.rst:75 ../../c-api/apiabiversion.rst:93 +msgid "``3.4.1a2``" +msgstr "``3.4.1a2``" + +#: ../../c-api/apiabiversion.rst:75 ../../c-api/apiabiversion.rst:95 +msgid "``3.10.0``" +msgstr "``3.10.0``" + +#: ../../c-api/apiabiversion.rst:77 +msgid "*major*" +msgstr "*major*" + +#: ../../c-api/apiabiversion.rst:77 ../../c-api/apiabiversion.rst:79 +#: ../../c-api/apiabiversion.rst:81 +msgid "8" +msgstr "8" + +#: ../../c-api/apiabiversion.rst:77 +msgid "``0xFF000000``" +msgstr "``0xFF000000``" + +#: ../../c-api/apiabiversion.rst:77 +msgid "24" +msgstr "24" + +#: ../../c-api/apiabiversion.rst:77 +msgid "``0x03``" +msgstr "``0x03``" + +#: ../../c-api/apiabiversion.rst:79 +msgid "*minor*" +msgstr "" + +#: ../../c-api/apiabiversion.rst:79 +msgid "``0x00FF0000``" +msgstr "``0x00FF0000``" + +#: ../../c-api/apiabiversion.rst:79 +msgid "16" +msgstr "16" + +#: ../../c-api/apiabiversion.rst:79 +msgid "``0x04``" +msgstr "``0x04``" + +#: ../../c-api/apiabiversion.rst:79 +msgid "``0x0A``" +msgstr "``0x0A``" + +#: ../../c-api/apiabiversion.rst:81 +msgid "*micro*" +msgstr "*micro*" + +#: ../../c-api/apiabiversion.rst:81 +msgid "``0x0000FF00``" +msgstr "``0x0000FF00``" + +#: ../../c-api/apiabiversion.rst:81 +msgid "``0x01``" +msgstr "``0x01``" + +#: ../../c-api/apiabiversion.rst:81 +msgid "``0x00``" +msgstr "``0x00``" + +#: ../../c-api/apiabiversion.rst:83 +msgid "*release_level*" +msgstr "*release_level*" + +#: ../../c-api/apiabiversion.rst:83 ../../c-api/apiabiversion.rst:85 +msgid "4" +msgstr "4" + +#: ../../c-api/apiabiversion.rst:83 +msgid "``0x000000F0``" +msgstr "``0x000000F0``" + +#: ../../c-api/apiabiversion.rst:83 +msgid "``0xA``" +msgstr "``0xA``" + +#: ../../c-api/apiabiversion.rst:83 +msgid "``0xF``" +msgstr "``0xF``" + +#: ../../c-api/apiabiversion.rst:85 +msgid "*release_serial*" +msgstr "*release_serial*" + +#: ../../c-api/apiabiversion.rst:85 +msgid "``0x0000000F``" +msgstr "``0x0000000F``" + +#: ../../c-api/apiabiversion.rst:85 +msgid "0" +msgstr "0" + +#: ../../c-api/apiabiversion.rst:85 +msgid "``0x2``" +msgstr "``0x2``" + +#: ../../c-api/apiabiversion.rst:85 +msgid "``0x0``" +msgstr "``0x0``" + +#: ../../c-api/apiabiversion.rst:88 +msgid "For example:" +msgstr "例如：" + +#: ../../c-api/apiabiversion.rst:91 +msgid "Version" +msgstr "版本" + +#: ../../c-api/apiabiversion.rst:91 +msgid "``Py_PACK_FULL_VERSION`` arguments" +msgstr "``Py_PACK_FULL_VERSION`` 引數" + +#: ../../c-api/apiabiversion.rst:91 +msgid "Encoded version" +msgstr "" + +#: ../../c-api/apiabiversion.rst:93 +msgid "``(3, 4, 1, 0xA, 2)``" +msgstr "``(3, 4, 1, 0xA, 2)``" + +#: ../../c-api/apiabiversion.rst:93 +msgid "``0x030401a2``" +msgstr "``0x030401a2``" + +#: ../../c-api/apiabiversion.rst:95 +msgid "``(3, 10, 0, 0xF, 0)``" +msgstr "``(3, 10, 0, 0xF, 0)``" + +#: ../../c-api/apiabiversion.rst:95 +msgid "``0x030a00f0``" +msgstr "``0x030a00f0``" + +#: ../../c-api/apiabiversion.rst:98 +msgid "" +"Out-of range bits in the arguments are ignored. That is, the macro can be " +"defined as:" +msgstr "" + +#: ../../c-api/apiabiversion.rst:101 +msgid "" +"#ifndef Py_PACK_FULL_VERSION\n" +"#define Py_PACK_FULL_VERSION(X, Y, Z, LEVEL, SERIAL) ( \\\n" +" (((X) & 0xff) << 24) | \\\n" +" (((Y) & 0xff) << 16) | \\\n" +" (((Z) & 0xff) << 8) | \\\n" +" (((LEVEL) & 0xf) << 4) | \\\n" +" (((SERIAL) & 0xf) << 0))\n" +"#endif" +msgstr "" +"#ifndef Py_PACK_FULL_VERSION\n" +"#define Py_PACK_FULL_VERSION(X, Y, Z, LEVEL, SERIAL) ( \\\n" +" (((X) & 0xff) << 24) | \\\n" +" (((Y) & 0xff) << 16) | \\\n" +" (((Z) & 0xff) << 8) | \\\n" +" (((LEVEL) & 0xf) << 4) | \\\n" +" (((SERIAL) & 0xf) << 0))\n" +"#endif" + +#: ../../c-api/apiabiversion.rst:112 +msgid "" +"``Py_PACK_FULL_VERSION`` is primarily a macro, intended for use in ``#if`` " +"directives, but it is also available as an exported function." +msgstr "" + +#: ../../c-api/apiabiversion.rst:119 +msgid "" +"Equivalent to ``Py_PACK_FULL_VERSION(major, minor, 0, 0, 0)``. The result " +"does not correspond to any Python release, but is useful in numeric " +"comparisons." +msgstr "" diff --git a/c-api/arg.po b/c-api/arg.po index faecd8282d..97dfd1a6a6 100644 --- a/c-api/arg.po +++ b/c-api/arg.po @@ -1,1276 +1,1276 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-10-25 00:15+0000\n" -"PO-Revision-Date: 2022-10-16 03:21+0800\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" -"X-Generator: Poedit 3.1.1\n" - -#: ../../c-api/arg.rst:6 -msgid "Parsing arguments and building values" -msgstr "剖析引數與建置數值" - -#: ../../c-api/arg.rst:8 -msgid "" -"These functions are useful when creating your own extension functions and " -"methods. Additional information and examples are available in :ref:" -"`extending-index`." -msgstr "" - -#: ../../c-api/arg.rst:12 -msgid "" -"The first three of these functions described, :c:func:`PyArg_ParseTuple`, :c:" -"func:`PyArg_ParseTupleAndKeywords`, and :c:func:`PyArg_Parse`, all use " -"*format strings* which are used to tell the function about the expected " -"arguments. The format strings use the same syntax for each of these " -"functions." -msgstr "" - -#: ../../c-api/arg.rst:19 -msgid "Parsing arguments" -msgstr "剖析引數" - -#: ../../c-api/arg.rst:21 -msgid "" -"A format string consists of zero or more \"format units.\" A format unit " -"describes one Python object; it is usually a single character or a " -"parenthesized sequence of format units. With a few exceptions, a format " -"unit that is not a parenthesized sequence normally corresponds to a single " -"address argument to these functions. In the following description, the " -"quoted form is the format unit; the entry in (round) parentheses is the " -"Python object type that matches the format unit; and the entry in [square] " -"brackets is the type of the C variable(s) whose address should be passed." -msgstr "" - -#: ../../c-api/arg.rst:33 -msgid "Strings and buffers" -msgstr "字串與緩衝區" - -#: ../../c-api/arg.rst:37 -msgid "" -"On Python 3.12 and older, the macro :c:macro:`!PY_SSIZE_T_CLEAN` must be " -"defined before including :file:`Python.h` to use all ``#`` variants of " -"formats (``s#``, ``y#``, etc.) explained below. This is not necessary on " -"Python 3.13 and later." -msgstr "" - -#: ../../c-api/arg.rst:42 -msgid "" -"These formats allow accessing an object as a contiguous chunk of memory. You " -"don't have to provide raw storage for the returned unicode or bytes area." -msgstr "" - -#: ../../c-api/arg.rst:46 -msgid "Unless otherwise stated, buffers are not NUL-terminated." -msgstr "" - -#: ../../c-api/arg.rst:48 -msgid "There are three ways strings and buffers can be converted to C:" -msgstr "" - -#: ../../c-api/arg.rst:50 -msgid "" -"Formats such as ``y*`` and ``s*`` fill a :c:type:`Py_buffer` structure. This " -"locks the underlying buffer so that the caller can subsequently use the " -"buffer even inside a :c:type:`Py_BEGIN_ALLOW_THREADS` block without the risk " -"of mutable data being resized or destroyed. As a result, **you have to " -"call** :c:func:`PyBuffer_Release` after you have finished processing the " -"data (or in any early abort case)." -msgstr "" - -#: ../../c-api/arg.rst:57 -msgid "" -"The ``es``, ``es#``, ``et`` and ``et#`` formats allocate the result buffer. " -"**You have to call** :c:func:`PyMem_Free` after you have finished processing " -"the data (or in any early abort case)." -msgstr "" - -#: ../../c-api/arg.rst:63 -msgid "" -"Other formats take a :class:`str` or a read-only :term:`bytes-like object`, " -"such as :class:`bytes`, and provide a ``const char *`` pointer to its " -"buffer. In this case the buffer is \"borrowed\": it is managed by the " -"corresponding Python object, and shares the lifetime of this object. You " -"won't have to release any memory yourself." -msgstr "" - -#: ../../c-api/arg.rst:70 -msgid "" -"To ensure that the underlying buffer may be safely borrowed, the object's :c:" -"member:`PyBufferProcs.bf_releasebuffer` field must be ``NULL``. This " -"disallows common mutable objects such as :class:`bytearray`, but also some " -"read-only objects such as :class:`memoryview` of :class:`bytes`." -msgstr "" - -#: ../../c-api/arg.rst:76 -msgid "" -"Besides this ``bf_releasebuffer`` requirement, there is no check to verify " -"whether the input object is immutable (e.g. whether it would honor a request " -"for a writable buffer, or whether another thread can mutate the data)." -msgstr "" - -#: ../../c-api/arg.rst:80 -msgid "``s`` (:class:`str`) [const char \\*]" -msgstr "``s`` (:class:`str`) [const char \\*]" - -#: ../../c-api/arg.rst:81 -msgid "" -"Convert a Unicode object to a C pointer to a character string. A pointer to " -"an existing string is stored in the character pointer variable whose address " -"you pass. The C string is NUL-terminated. The Python string must not " -"contain embedded null code points; if it does, a :exc:`ValueError` exception " -"is raised. Unicode objects are converted to C strings using ``'utf-8'`` " -"encoding. If this conversion fails, a :exc:`UnicodeError` is raised." -msgstr "" - -#: ../../c-api/arg.rst:90 -msgid "" -"This format does not accept :term:`bytes-like objects `. " -"If you want to accept filesystem paths and convert them to C character " -"strings, it is preferable to use the ``O&`` format with :c:func:" -"`PyUnicode_FSConverter` as *converter*." -msgstr "" - -#: ../../c-api/arg.rst:96 -msgid "" -"Previously, :exc:`TypeError` was raised when embedded null code points were " -"encountered in the Python string." -msgstr "" - -#: ../../c-api/arg.rst:100 -msgid "``s*`` (:class:`str` or :term:`bytes-like object`) [Py_buffer]" -msgstr "``s*`` (:class:`str` 或 :term:`bytes-like object`) [Py_buffer]" - -#: ../../c-api/arg.rst:101 -msgid "" -"This format accepts Unicode objects as well as bytes-like objects. It fills " -"a :c:type:`Py_buffer` structure provided by the caller. In this case the " -"resulting C string may contain embedded NUL bytes. Unicode objects are " -"converted to C strings using ``'utf-8'`` encoding." -msgstr "" - -#: ../../c-api/arg.rst:106 -msgid "" -"``s#`` (:class:`str`, read-only :term:`bytes-like object`) [const char \\*, :" -"c:type:`Py_ssize_t`]" -msgstr "" -"``s#`` (:class:`str`、唯讀的 :term:`bytes-like object`) [const char \\*, :c:" -"type:`Py_ssize_t`]" - -#: ../../c-api/arg.rst:107 -msgid "" -"Like ``s*``, except that it provides a :ref:`borrowed buffer `. The result is stored into two C variables, the first one a pointer " -"to a C string, the second one its length. The string may contain embedded " -"null bytes. Unicode objects are converted to C strings using ``'utf-8'`` " -"encoding." -msgstr "" - -#: ../../c-api/arg.rst:113 ../../c-api/arg.rst:614 -msgid "``z`` (:class:`str` or ``None``) [const char \\*]" -msgstr "``z`` (:class:`str` 或 ``None``) [const char \\*]" - -#: ../../c-api/arg.rst:114 -msgid "" -"Like ``s``, but the Python object may also be ``None``, in which case the C " -"pointer is set to ``NULL``." -msgstr "" - -#: ../../c-api/arg.rst:117 -msgid "" -"``z*`` (:class:`str`, :term:`bytes-like object` or ``None``) [Py_buffer]" -msgstr "" -"``z*`` (:class:`str`、:term:`bytes-like object` 或 ``None``) [Py_buffer]" - -#: ../../c-api/arg.rst:118 -msgid "" -"Like ``s*``, but the Python object may also be ``None``, in which case the " -"``buf`` member of the :c:type:`Py_buffer` structure is set to ``NULL``." -msgstr "" - -#: ../../c-api/arg.rst:121 -msgid "" -"``z#`` (:class:`str`, read-only :term:`bytes-like object` or ``None``) " -"[const char \\*, :c:type:`Py_ssize_t`]" -msgstr "" -"``z#`` (:class:`str`、唯讀的 :term:`bytes-like object` 或 ``None``) [const " -"char \\*, :c:type:`Py_ssize_t`]" - -#: ../../c-api/arg.rst:122 -msgid "" -"Like ``s#``, but the Python object may also be ``None``, in which case the C " -"pointer is set to ``NULL``." -msgstr "" - -#: ../../c-api/arg.rst:125 -msgid "``y`` (read-only :term:`bytes-like object`) [const char \\*]" -msgstr "``y`` (唯讀的 :term:`bytes-like object`) [const char \\*]" - -#: ../../c-api/arg.rst:126 -msgid "" -"This format converts a bytes-like object to a C pointer to a :ref:`borrowed " -"` character string; it does not accept Unicode " -"objects. The bytes buffer must not contain embedded null bytes; if it does, " -"a :exc:`ValueError` exception is raised." -msgstr "" - -#: ../../c-api/arg.rst:132 -msgid "" -"Previously, :exc:`TypeError` was raised when embedded null bytes were " -"encountered in the bytes buffer." -msgstr "" - -#: ../../c-api/arg.rst:136 -msgid "``y*`` (:term:`bytes-like object`) [Py_buffer]" -msgstr "``y*`` (:term:`bytes-like object`) [Py_buffer]" - -#: ../../c-api/arg.rst:137 -msgid "" -"This variant on ``s*`` doesn't accept Unicode objects, only bytes-like " -"objects. **This is the recommended way to accept binary data.**" -msgstr "" - -#: ../../c-api/arg.rst:141 -msgid "" -"``y#`` (read-only :term:`bytes-like object`) [const char \\*, :c:type:" -"`Py_ssize_t`]" -msgstr "" -"``y#`` (唯讀的 :term:`bytes-like object`) [const char \\*, :c:type:" -"`Py_ssize_t`]" - -#: ../../c-api/arg.rst:142 -msgid "" -"This variant on ``s#`` doesn't accept Unicode objects, only bytes-like " -"objects." -msgstr "" - -#: ../../c-api/arg.rst:145 -msgid "``S`` (:class:`bytes`) [PyBytesObject \\*]" -msgstr "``S`` (:class:`bytes`) [PyBytesObject \\*]" - -#: ../../c-api/arg.rst:146 -msgid "" -"Requires that the Python object is a :class:`bytes` object, without " -"attempting any conversion. Raises :exc:`TypeError` if the object is not a " -"bytes object. The C variable may also be declared as :c:expr:`PyObject*`." -msgstr "" - -#: ../../c-api/arg.rst:150 -msgid "``Y`` (:class:`bytearray`) [PyByteArrayObject \\*]" -msgstr "``Y`` (:class:`bytearray`) [PyByteArrayObject \\*]" - -#: ../../c-api/arg.rst:151 -msgid "" -"Requires that the Python object is a :class:`bytearray` object, without " -"attempting any conversion. Raises :exc:`TypeError` if the object is not a :" -"class:`bytearray` object. The C variable may also be declared as :c:expr:" -"`PyObject*`." -msgstr "" - -#: ../../c-api/arg.rst:155 -msgid "``U`` (:class:`str`) [PyObject \\*]" -msgstr "``U`` (:class:`str`) [PyObject \\*]" - -#: ../../c-api/arg.rst:156 -msgid "" -"Requires that the Python object is a Unicode object, without attempting any " -"conversion. Raises :exc:`TypeError` if the object is not a Unicode object. " -"The C variable may also be declared as :c:expr:`PyObject*`." -msgstr "" - -#: ../../c-api/arg.rst:160 -msgid "``w*`` (read-write :term:`bytes-like object`) [Py_buffer]" -msgstr "``w*`` (可讀寫 :term:`bytes-like object`) [Py_buffer]" - -#: ../../c-api/arg.rst:161 -msgid "" -"This format accepts any object which implements the read-write buffer " -"interface. It fills a :c:type:`Py_buffer` structure provided by the caller. " -"The buffer may contain embedded null bytes. The caller has to call :c:func:" -"`PyBuffer_Release` when it is done with the buffer." -msgstr "" - -#: ../../c-api/arg.rst:166 -msgid "``es`` (:class:`str`) [const char \\*encoding, char \\*\\*buffer]" -msgstr "``es`` (:class:`str`) [const char \\*encoding, char \\*\\*buffer]" - -#: ../../c-api/arg.rst:167 -msgid "" -"This variant on ``s`` is used for encoding Unicode into a character buffer. " -"It only works for encoded data without embedded NUL bytes." -msgstr "" - -#: ../../c-api/arg.rst:170 -msgid "" -"This format requires two arguments. The first is only used as input, and " -"must be a :c:expr:`const char*` which points to the name of an encoding as a " -"NUL-terminated string, or ``NULL``, in which case ``'utf-8'`` encoding is " -"used. An exception is raised if the named encoding is not known to Python. " -"The second argument must be a :c:expr:`char**`; the value of the pointer it " -"references will be set to a buffer with the contents of the argument text. " -"The text will be encoded in the encoding specified by the first argument." -msgstr "" - -#: ../../c-api/arg.rst:178 -msgid "" -":c:func:`PyArg_ParseTuple` will allocate a buffer of the needed size, copy " -"the encoded data into this buffer and adjust *\\*buffer* to reference the " -"newly allocated storage. The caller is responsible for calling :c:func:" -"`PyMem_Free` to free the allocated buffer after use." -msgstr "" - -#: ../../c-api/arg.rst:183 -msgid "" -"``et`` (:class:`str`, :class:`bytes` or :class:`bytearray`) [const char " -"\\*encoding, char \\*\\*buffer]" -msgstr "" -"``et`` (:class:`str`、:class:`bytes` 或 :class:`bytearray`) [const char " -"\\*encoding, char \\*\\*buffer]" - -#: ../../c-api/arg.rst:184 -msgid "" -"Same as ``es`` except that byte string objects are passed through without " -"recoding them. Instead, the implementation assumes that the byte string " -"object uses the encoding passed in as parameter." -msgstr "" - -#: ../../c-api/arg.rst:188 -msgid "" -"``es#`` (:class:`str`) [const char \\*encoding, char \\*\\*buffer, :c:type:" -"`Py_ssize_t` \\*buffer_length]" -msgstr "" -"``es#`` (:class:`str`) [const char \\*encoding, char \\*\\*buffer, :c:type:" -"`Py_ssize_t` \\*buffer_length]" - -#: ../../c-api/arg.rst:189 -msgid "" -"This variant on ``s#`` is used for encoding Unicode into a character buffer. " -"Unlike the ``es`` format, this variant allows input data which contains NUL " -"characters." -msgstr "" - -#: ../../c-api/arg.rst:193 -msgid "" -"It requires three arguments. The first is only used as input, and must be " -"a :c:expr:`const char*` which points to the name of an encoding as a NUL-" -"terminated string, or ``NULL``, in which case ``'utf-8'`` encoding is used. " -"An exception is raised if the named encoding is not known to Python. The " -"second argument must be a :c:expr:`char**`; the value of the pointer it " -"references will be set to a buffer with the contents of the argument text. " -"The text will be encoded in the encoding specified by the first argument. " -"The third argument must be a pointer to an integer; the referenced integer " -"will be set to the number of bytes in the output buffer." -msgstr "" - -#: ../../c-api/arg.rst:203 -msgid "There are two modes of operation:" -msgstr "有兩個操作模式：" - -#: ../../c-api/arg.rst:205 -msgid "" -"If *\\*buffer* points a ``NULL`` pointer, the function will allocate a " -"buffer of the needed size, copy the encoded data into this buffer and set " -"*\\*buffer* to reference the newly allocated storage. The caller is " -"responsible for calling :c:func:`PyMem_Free` to free the allocated buffer " -"after usage." -msgstr "" - -#: ../../c-api/arg.rst:210 -msgid "" -"If *\\*buffer* points to a non-``NULL`` pointer (an already allocated " -"buffer), :c:func:`PyArg_ParseTuple` will use this location as the buffer and " -"interpret the initial value of *\\*buffer_length* as the buffer size. It " -"will then copy the encoded data into the buffer and NUL-terminate it. If " -"the buffer is not large enough, a :exc:`ValueError` will be set." -msgstr "" - -#: ../../c-api/arg.rst:216 -msgid "" -"In both cases, *\\*buffer_length* is set to the length of the encoded data " -"without the trailing NUL byte." -msgstr "" - -#: ../../c-api/arg.rst:219 -msgid "" -"``et#`` (:class:`str`, :class:`bytes` or :class:`bytearray`) [const char " -"\\*encoding, char \\*\\*buffer, :c:type:`Py_ssize_t` \\*buffer_length]" -msgstr "" - -#: ../../c-api/arg.rst:220 -msgid "" -"Same as ``es#`` except that byte string objects are passed through without " -"recoding them. Instead, the implementation assumes that the byte string " -"object uses the encoding passed in as parameter." -msgstr "" - -#: ../../c-api/arg.rst:224 -msgid "" -"``u``, ``u#``, ``Z``, and ``Z#`` are removed because they used a legacy " -"``Py_UNICODE*`` representation." -msgstr "" - -#: ../../c-api/arg.rst:230 -msgid "Numbers" -msgstr "數字" - -#: ../../c-api/arg.rst:232 -msgid "" -"These formats allow representing Python numbers or single characters as C " -"numbers. Formats that require :class:`int`, :class:`float` or :class:" -"`complex` can also use the corresponding special methods :meth:`~object." -"__index__`, :meth:`~object.__float__` or :meth:`~object.__complex__` to " -"convert the Python object to the required type." -msgstr "" - -#: ../../c-api/arg.rst:238 -msgid "" -"For signed integer formats, :exc:`OverflowError` is raised if the value is " -"out of range for the C type. For unsigned integer formats, no range checking " -"is done --- the most significant bits are silently truncated when the " -"receiving field is too small to receive the value." -msgstr "" - -#: ../../c-api/arg.rst:244 -msgid "``b`` (:class:`int`) [unsigned char]" -msgstr "``b`` (:class:`int`) [unsigned char]" - -#: ../../c-api/arg.rst:245 -msgid "" -"Convert a nonnegative Python integer to an unsigned tiny integer, stored in " -"a C :c:expr:`unsigned char`." -msgstr "" -"將一個 Python 非負整數轉換成無符號 tiny integer（小整數），儲存在 C 的 :c:" -"expr:`unsigned`" - -#: ../../c-api/arg.rst:248 ../../c-api/arg.rst:648 -msgid "``B`` (:class:`int`) [unsigned char]" -msgstr "``B`` (:class:`int`) [unsigned char]" - -#: ../../c-api/arg.rst:249 -msgid "" -"Convert a Python integer to a tiny integer without overflow checking, stored " -"in a C :c:expr:`unsigned char`." -msgstr "" -"將一個 Python 整數轉換成 tiny integer，轉換過程無溢位檢查，儲存在 C 的 :c:" -"expr:`unsigned char`。" - -#: ../../c-api/arg.rst:252 ../../c-api/arg.rst:642 -msgid "``h`` (:class:`int`) [short int]" -msgstr "``h`` (:class:`int`) [short int]" - -#: ../../c-api/arg.rst:253 -msgid "Convert a Python integer to a C :c:expr:`short int`." -msgstr "將一個 Python 整數轉換成 C 的 :c:expr:`short int`。" - -#: ../../c-api/arg.rst:255 ../../c-api/arg.rst:651 -msgid "``H`` (:class:`int`) [unsigned short int]" -msgstr "``H`` (:class:`int`) [unsigned short int]" - -#: ../../c-api/arg.rst:256 -msgid "" -"Convert a Python integer to a C :c:expr:`unsigned short int`, without " -"overflow checking." -msgstr "" -"將一個 Python 整數轉換成 C 的 :c:expr:`unsigned short int`，轉換過程無溢位檢" -"查。" - -#: ../../c-api/arg.rst:259 ../../c-api/arg.rst:636 -msgid "``i`` (:class:`int`) [int]" -msgstr "``i`` (:class:`int`) [int]" - -#: ../../c-api/arg.rst:260 -msgid "Convert a Python integer to a plain C :c:expr:`int`." -msgstr "將一個 Python 整數轉換成 C 的 :c:expr:`int`。" - -#: ../../c-api/arg.rst:262 ../../c-api/arg.rst:654 -msgid "``I`` (:class:`int`) [unsigned int]" -msgstr "``I`` (:class:`int`) [unsigned int]" - -#: ../../c-api/arg.rst:263 -msgid "" -"Convert a Python integer to a C :c:expr:`unsigned int`, without overflow " -"checking." -msgstr "" -"將一個 Python 整數轉換成 C 的 :c:expr:`unsigned int`，轉換過程無溢位檢查。" - -#: ../../c-api/arg.rst:266 ../../c-api/arg.rst:645 -msgid "``l`` (:class:`int`) [long int]" -msgstr "``l`` (:class:`int`) [long int]" - -#: ../../c-api/arg.rst:267 -msgid "Convert a Python integer to a C :c:expr:`long int`." -msgstr "將一個 Python 整數轉換成 C 的 :c:expr:`long int`。" - -#: ../../c-api/arg.rst:269 ../../c-api/arg.rst:657 -msgid "``k`` (:class:`int`) [unsigned long]" -msgstr "``k`` (:class:`int`) [unsigned long]" - -#: ../../c-api/arg.rst:270 -msgid "" -"Convert a Python integer to a C :c:expr:`unsigned long` without overflow " -"checking." -msgstr "" -"將一個 Python 整數轉換成 C 的 :c:expr:`unsigned long`，轉換過程無溢位檢查。" - -#: ../../c-api/arg.rst:273 ../../c-api/arg.rst:283 -msgid "Use :meth:`~object.__index__` if available." -msgstr "如有提供則使用 :meth:`~object.__index__`。" - -#: ../../c-api/arg.rst:276 ../../c-api/arg.rst:660 -msgid "``L`` (:class:`int`) [long long]" -msgstr "``L`` (:class:`int`) [long long]" - -#: ../../c-api/arg.rst:277 -msgid "Convert a Python integer to a C :c:expr:`long long`." -msgstr "將一個 Python 整數轉換成 C 的 :c:expr:`long long`。" - -#: ../../c-api/arg.rst:279 ../../c-api/arg.rst:665 -msgid "``K`` (:class:`int`) [unsigned long long]" -msgstr "``K`` (:class:`int`) [unsigned long long]" - -#: ../../c-api/arg.rst:280 -msgid "" -"Convert a Python integer to a C :c:expr:`unsigned long long` without " -"overflow checking." -msgstr "" -"將一個 Python 整數轉換成 C 的 :c:expr:`unsigned long long`，轉換過程無溢位檢" -"查。" - -#: ../../c-api/arg.rst:286 ../../c-api/arg.rst:668 -msgid "``n`` (:class:`int`) [:c:type:`Py_ssize_t`]" -msgstr "``n`` (:class:`int`) [:c:type:`Py_ssize_t`]" - -#: ../../c-api/arg.rst:287 -msgid "Convert a Python integer to a C :c:type:`Py_ssize_t`." -msgstr "將一個 Python 整數轉換成 C 的 :c:type:`Py_ssize_t`。" - -#: ../../c-api/arg.rst:289 -msgid "``c`` (:class:`bytes` or :class:`bytearray` of length 1) [char]" -msgstr "``c`` (:class:`bytes` 或長度為 1 的 :class:`bytearray`) [char]" - -#: ../../c-api/arg.rst:290 -msgid "" -"Convert a Python byte, represented as a :class:`bytes` or :class:`bytearray` " -"object of length 1, to a C :c:expr:`char`." -msgstr "" - -#: ../../c-api/arg.rst:293 -msgid "Allow :class:`bytearray` objects." -msgstr "允許 :class:`bytearray` 物件。" - -#: ../../c-api/arg.rst:296 ../../c-api/arg.rst:686 -msgid "``C`` (:class:`str` of length 1) [int]" -msgstr "``C`` (長度為 1 的 :class:`str`) [int]" - -#: ../../c-api/arg.rst:297 -msgid "" -"Convert a Python character, represented as a :class:`str` object of length " -"1, to a C :c:expr:`int`." -msgstr "" - -#: ../../c-api/arg.rst:300 ../../c-api/arg.rst:693 -msgid "``f`` (:class:`float`) [float]" -msgstr "``f`` (:class:`float`) [float]" - -#: ../../c-api/arg.rst:301 -msgid "Convert a Python floating-point number to a C :c:expr:`float`." -msgstr "將一個 Python 浮點數轉換成 C 的 :c:type::c:expr:`float`。" - -#: ../../c-api/arg.rst:303 ../../c-api/arg.rst:690 -msgid "``d`` (:class:`float`) [double]" -msgstr "``d`` (:class:`float`) [double]" - -#: ../../c-api/arg.rst:304 -msgid "Convert a Python floating-point number to a C :c:expr:`double`." -msgstr "將一個 Python 浮點數轉換成 C 的 :c:type::c:expr:`double`。" - -#: ../../c-api/arg.rst:306 -msgid "``D`` (:class:`complex`) [Py_complex]" -msgstr "``D`` (:class:`complex`) [Py_complex]" - -#: ../../c-api/arg.rst:307 -msgid "Convert a Python complex number to a C :c:type:`Py_complex` structure." -msgstr "將一個 Python 複數轉換成 C 的 :c:type:`Py_complex` 結構。" - -#: ../../c-api/arg.rst:310 -msgid "Other objects" -msgstr "其他物件" - -#: ../../c-api/arg.rst:312 ../../c-api/arg.rst:699 -msgid "``O`` (object) [PyObject \\*]" -msgstr "``O`` (object) [PyObject \\*]" - -#: ../../c-api/arg.rst:313 -msgid "" -"Store a Python object (without any conversion) in a C object pointer. The C " -"program thus receives the actual object that was passed. A new :term:" -"`strong reference` to the object is not created (i.e. its reference count is " -"not increased). The pointer stored is not ``NULL``." -msgstr "" - -#: ../../c-api/arg.rst:319 -msgid "``O!`` (object) [*typeobject*, PyObject \\*]" -msgstr "``O!`` (object) [*typeobject*, PyObject \\*]" - -#: ../../c-api/arg.rst:320 -msgid "" -"Store a Python object in a C object pointer. This is similar to ``O``, but " -"takes two C arguments: the first is the address of a Python type object, the " -"second is the address of the C variable (of type :c:expr:`PyObject*`) into " -"which the object pointer is stored. If the Python object does not have the " -"required type, :exc:`TypeError` is raised." -msgstr "" - -#: ../../c-api/arg.rst:328 -msgid "``O&`` (object) [*converter*, *address*]" -msgstr "``O&`` (object) [*converter*, *address*]" - -#: ../../c-api/arg.rst:329 -msgid "" -"Convert a Python object to a C variable through a *converter* function. " -"This takes two arguments: the first is a function, the second is the address " -"of a C variable (of arbitrary type), converted to :c:expr:`void *`. The " -"*converter* function in turn is called as follows::" -msgstr "" - -#: ../../c-api/arg.rst:334 -msgid "status = converter(object, address);" -msgstr "status = converter(object, address);" - -#: ../../c-api/arg.rst:336 -msgid "" -"where *object* is the Python object to be converted and *address* is the :c:" -"expr:`void*` argument that was passed to the ``PyArg_Parse*`` function. The " -"returned *status* should be ``1`` for a successful conversion and ``0`` if " -"the conversion has failed. When the conversion fails, the *converter* " -"function should raise an exception and leave the content of *address* " -"unmodified." -msgstr "" - -#: ../../c-api/arg.rst:345 -msgid "" -"If the *converter* returns :c:macro:`!Py_CLEANUP_SUPPORTED`, it may get " -"called a second time if the argument parsing eventually fails, giving the " -"converter a chance to release any memory that it had already allocated. In " -"this second call, the *object* parameter will be ``NULL``; *address* will " -"have the same value as in the original call." -msgstr "" - -#: ../../c-api/arg.rst:351 -msgid "" -"Examples of converters: :c:func:`PyUnicode_FSConverter` and :c:func:" -"`PyUnicode_FSDecoder`." -msgstr "" - -#: ../../c-api/arg.rst:354 -msgid ":c:macro:`!Py_CLEANUP_SUPPORTED` was added." -msgstr "新增 :c:macro:`!Py_CLEANUP_SUPPORTED`。" - -#: ../../c-api/arg.rst:357 ../../c-api/arg.rst:671 -msgid "``p`` (:class:`bool`) [int]" -msgstr "``p`` (:class:`bool`) [int]" - -#: ../../c-api/arg.rst:358 -msgid "" -"Tests the value passed in for truth (a boolean **p**\\ redicate) and " -"converts the result to its equivalent C true/false integer value. Sets the " -"int to ``1`` if the expression was true and ``0`` if it was false. This " -"accepts any valid Python value. See :ref:`truth` for more information about " -"how Python tests values for truth." -msgstr "" - -#: ../../c-api/arg.rst:366 -msgid "``(items)`` (sequence) [*matching-items*]" -msgstr "``(items)`` (sequence) [*matching-items*]" - -#: ../../c-api/arg.rst:367 -msgid "" -"The object must be a Python sequence (except :class:`str`, :class:`bytes` " -"or :class:`bytearray`) whose length is the number of format units in " -"*items*. The C arguments must correspond to the individual format units in " -"*items*. Format units for sequences may be nested." -msgstr "" - -#: ../../c-api/arg.rst:372 -msgid "" -"If *items* contains format units which store a :ref:`borrowed buffer ` (``s``, ``s#``, ``z``, ``z#``, ``y``, or ``y#``) or a :" -"term:`borrowed reference` (``S``, ``Y``, ``U``, ``O``, or ``O!``), the " -"object must be a Python tuple. The *converter* for the ``O&`` format unit in " -"*items* must not store a borrowed buffer or a borrowed reference." -msgstr "" - -#: ../../c-api/arg.rst:379 -msgid "" -":class:`str` and :class:`bytearray` objects no longer accepted as a sequence." -msgstr "" - -#: ../../c-api/arg.rst:382 -msgid "" -"Non-tuple sequences are deprecated if *items* contains format units which " -"store a borrowed buffer or a borrowed reference." -msgstr "" - -#: ../../c-api/arg.rst:386 -msgid "" -"A few other characters have a meaning in a format string. These may not " -"occur inside nested parentheses. They are:" -msgstr "" - -#: ../../c-api/arg.rst:389 -msgid "``|``" -msgstr "``|``" - -#: ../../c-api/arg.rst:390 -msgid "" -"Indicates that the remaining arguments in the Python argument list are " -"optional. The C variables corresponding to optional arguments should be " -"initialized to their default value --- when an optional argument is not " -"specified, :c:func:`PyArg_ParseTuple` does not touch the contents of the " -"corresponding C variable(s)." -msgstr "" - -#: ../../c-api/arg.rst:396 -msgid "``$``" -msgstr "``$``" - -#: ../../c-api/arg.rst:397 -msgid "" -":c:func:`PyArg_ParseTupleAndKeywords` only: Indicates that the remaining " -"arguments in the Python argument list are keyword-only. Currently, all " -"keyword-only arguments must also be optional arguments, so ``|`` must always " -"be specified before ``$`` in the format string." -msgstr "" - -#: ../../c-api/arg.rst:405 -msgid "``:``" -msgstr "``:``" - -#: ../../c-api/arg.rst:406 -msgid "" -"The list of format units ends here; the string after the colon is used as " -"the function name in error messages (the \"associated value\" of the " -"exception that :c:func:`PyArg_ParseTuple` raises)." -msgstr "" - -#: ../../c-api/arg.rst:410 -msgid "``;``" -msgstr "``;``" - -#: ../../c-api/arg.rst:411 -msgid "" -"The list of format units ends here; the string after the semicolon is used " -"as the error message *instead* of the default error message. ``:`` and ``;" -"`` mutually exclude each other." -msgstr "" - -#: ../../c-api/arg.rst:415 -msgid "" -"Note that any Python object references which are provided to the caller are " -"*borrowed* references; do not release them (i.e. do not decrement their " -"reference count)!" -msgstr "" - -#: ../../c-api/arg.rst:419 -msgid "" -"Additional arguments passed to these functions must be addresses of " -"variables whose type is determined by the format string; these are used to " -"store values from the input tuple. There are a few cases, as described in " -"the list of format units above, where these parameters are used as input " -"values; they should match what is specified for the corresponding format " -"unit in that case." -msgstr "" - -#: ../../c-api/arg.rst:425 -msgid "" -"For the conversion to succeed, the *arg* object must match the format and " -"the format must be exhausted. On success, the ``PyArg_Parse*`` functions " -"return true, otherwise they return false and raise an appropriate exception. " -"When the ``PyArg_Parse*`` functions fail due to conversion failure in one of " -"the format units, the variables at the addresses corresponding to that and " -"the following format units are left untouched." -msgstr "" - -#: ../../c-api/arg.rst:434 -msgid "API Functions" -msgstr "API 函式" - -#: ../../c-api/arg.rst:438 -msgid "" -"Parse the parameters of a function that takes only positional parameters " -"into local variables. Returns true on success; on failure, it returns false " -"and raises the appropriate exception." -msgstr "" - -#: ../../c-api/arg.rst:445 -msgid "" -"Identical to :c:func:`PyArg_ParseTuple`, except that it accepts a va_list " -"rather than a variable number of arguments." -msgstr "" - -#: ../../c-api/arg.rst:451 -msgid "" -"Parse the parameters of a function that takes both positional and keyword " -"parameters into local variables. The *keywords* argument is a ``NULL``-" -"terminated array of keyword parameter names specified as null-terminated " -"ASCII or UTF-8 encoded C strings. Empty names denote :ref:`positional-only " -"parameters `. Returns true on success; on " -"failure, it returns false and raises the appropriate exception." -msgstr "" - -#: ../../c-api/arg.rst:462 -msgid "" -"The *keywords* parameter declaration is :c:expr:`char * const *` in C and :c:" -"expr:`const char * const *` in C++. This can be overridden with the :c:macro:" -"`PY_CXX_CONST` macro." -msgstr "" - -#: ../../c-api/arg.rst:466 -msgid "" -"Added support for :ref:`positional-only parameters `." -msgstr "新增對\\ :ref:`僅限位置參數 `\\ 的支援。" - -#: ../../c-api/arg.rst:470 -msgid "" -"The *keywords* parameter has now type :c:expr:`char * const *` in C and :c:" -"expr:`const char * const *` in C++, instead of :c:expr:`char **`. Added " -"support for non-ASCII keyword parameter names." -msgstr "" - -#: ../../c-api/arg.rst:479 -msgid "" -"Identical to :c:func:`PyArg_ParseTupleAndKeywords`, except that it accepts a " -"va_list rather than a variable number of arguments." -msgstr "" - -#: ../../c-api/arg.rst:485 -msgid "" -"Ensure that the keys in the keywords argument dictionary are strings. This " -"is only needed if :c:func:`PyArg_ParseTupleAndKeywords` is not used, since " -"the latter already does this check." -msgstr "" - -#: ../../c-api/arg.rst:494 -msgid "" -"Parse the parameter of a function that takes a single positional parameter " -"into a local variable. Returns true on success; on failure, it returns " -"false and raises the appropriate exception." -msgstr "" - -#: ../../c-api/arg.rst:498 -msgid "Example::" -msgstr "舉例來說： ::" - -#: ../../c-api/arg.rst:500 -msgid "" -"// Function using METH_O calling convention\n" -"static PyObject*\n" -"my_function(PyObject *module, PyObject *arg)\n" -"{\n" -" int value;\n" -" if (!PyArg_Parse(arg, \"i:my_function\", &value)) {\n" -" return NULL;\n" -" }\n" -" // ... use value ...\n" -"}" -msgstr "" - -#: ../../c-api/arg.rst:514 -msgid "" -"A simpler form of parameter retrieval which does not use a format string to " -"specify the types of the arguments. Functions which use this method to " -"retrieve their parameters should be declared as :c:macro:`METH_VARARGS` in " -"function or method tables. The tuple containing the actual parameters " -"should be passed as *args*; it must actually be a tuple. The length of the " -"tuple must be at least *min* and no more than *max*; *min* and *max* may be " -"equal. Additional arguments must be passed to the function, each of which " -"should be a pointer to a :c:expr:`PyObject*` variable; these will be filled " -"in with the values from *args*; they will contain :term:`borrowed references " -"`. The variables which correspond to optional parameters " -"not given by *args* will not be filled in; these should be initialized by " -"the caller. This function returns true on success and false if *args* is not " -"a tuple or contains the wrong number of elements; an exception will be set " -"if there was a failure." -msgstr "" - -#: ../../c-api/arg.rst:529 -msgid "" -"This is an example of the use of this function, taken from the sources for " -"the :mod:`!_weakref` helper module for weak references::" -msgstr "" - -#: ../../c-api/arg.rst:532 -msgid "" -"static PyObject *\n" -"weakref_ref(PyObject *self, PyObject *args)\n" -"{\n" -" PyObject *object;\n" -" PyObject *callback = NULL;\n" -" PyObject *result = NULL;\n" -"\n" -" if (PyArg_UnpackTuple(args, \"ref\", 1, 2, &object, &callback)) {\n" -" result = PyWeakref_NewRef(object, callback);\n" -" }\n" -" return result;\n" -"}" -msgstr "" -"static PyObject *\n" -"weakref_ref(PyObject *self, PyObject *args)\n" -"{\n" -" PyObject *object;\n" -" PyObject *callback = NULL;\n" -" PyObject *result = NULL;\n" -"\n" -" if (PyArg_UnpackTuple(args, \"ref\", 1, 2, &object, &callback)) {\n" -" result = PyWeakref_NewRef(object, callback);\n" -" }\n" -" return result;\n" -"}" - -#: ../../c-api/arg.rst:545 -msgid "" -"The call to :c:func:`PyArg_UnpackTuple` in this example is entirely " -"equivalent to this call to :c:func:`PyArg_ParseTuple`::" -msgstr "" - -#: ../../c-api/arg.rst:548 -msgid "PyArg_ParseTuple(args, \"O|O:ref\", &object, &callback)" -msgstr "PyArg_ParseTuple(args, \"O|O:ref\", &object, &callback)" - -#: ../../c-api/arg.rst:552 -msgid "" -"The value to be inserted, if any, before :c:expr:`char * const *` in the " -"*keywords* parameter declaration of :c:func:`PyArg_ParseTupleAndKeywords` " -"and :c:func:`PyArg_VaParseTupleAndKeywords`. Default empty for C and " -"``const`` for C++ (:c:expr:`const char * const *`). To override, define it " -"to the desired value before including :file:`Python.h`." -msgstr "" - -#: ../../c-api/arg.rst:566 -msgid "Building values" -msgstr "建置數值" - -#: ../../c-api/arg.rst:570 -msgid "" -"Create a new value based on a format string similar to those accepted by the " -"``PyArg_Parse*`` family of functions and a sequence of values. Returns the " -"value or ``NULL`` in the case of an error; an exception will be raised if " -"``NULL`` is returned." -msgstr "" - -#: ../../c-api/arg.rst:575 -msgid "" -":c:func:`Py_BuildValue` does not always build a tuple. It builds a tuple " -"only if its format string contains two or more format units. If the format " -"string is empty, it returns ``None``; if it contains exactly one format " -"unit, it returns whatever object is described by that format unit. To force " -"it to return a tuple of size 0 or one, parenthesize the format string." -msgstr "" - -#: ../../c-api/arg.rst:581 -msgid "" -"When memory buffers are passed as parameters to supply data to build " -"objects, as for the ``s`` and ``s#`` formats, the required data is copied. " -"Buffers provided by the caller are never referenced by the objects created " -"by :c:func:`Py_BuildValue`. In other words, if your code invokes :c:func:" -"`malloc` and passes the allocated memory to :c:func:`Py_BuildValue`, your " -"code is responsible for calling :c:func:`free` for that memory once :c:func:" -"`Py_BuildValue` returns." -msgstr "" - -#: ../../c-api/arg.rst:589 -msgid "" -"In the following description, the quoted form is the format unit; the entry " -"in (round) parentheses is the Python object type that the format unit will " -"return; and the entry in [square] brackets is the type of the C value(s) to " -"be passed." -msgstr "" - -#: ../../c-api/arg.rst:593 -msgid "" -"The characters space, tab, colon and comma are ignored in format strings " -"(but not within format units such as ``s#``). This can be used to make long " -"format strings a tad more readable." -msgstr "" - -#: ../../c-api/arg.rst:597 -msgid "``s`` (:class:`str` or ``None``) [const char \\*]" -msgstr "``s`` (:class:`str` 或 ``None``) [const char \\*]" - -#: ../../c-api/arg.rst:598 -msgid "" -"Convert a null-terminated C string to a Python :class:`str` object using " -"``'utf-8'`` encoding. If the C string pointer is ``NULL``, ``None`` is used." -msgstr "" - -#: ../../c-api/arg.rst:601 -msgid "" -"``s#`` (:class:`str` or ``None``) [const char \\*, :c:type:`Py_ssize_t`]" -msgstr "" -"``s#`` (:class:`str` 或 ``None``) [const char \\*, :c:type:`Py_ssize_t`]" - -#: ../../c-api/arg.rst:602 -msgid "" -"Convert a C string and its length to a Python :class:`str` object using " -"``'utf-8'`` encoding. If the C string pointer is ``NULL``, the length is " -"ignored and ``None`` is returned." -msgstr "" - -#: ../../c-api/arg.rst:606 -msgid "``y`` (:class:`bytes`) [const char \\*]" -msgstr "``y`` (:class:`bytes`) [const char \\*]" - -#: ../../c-api/arg.rst:607 -msgid "" -"This converts a C string to a Python :class:`bytes` object. If the C string " -"pointer is ``NULL``, ``None`` is returned." -msgstr "" - -#: ../../c-api/arg.rst:610 -msgid "``y#`` (:class:`bytes`) [const char \\*, :c:type:`Py_ssize_t`]" -msgstr "``y#`` (:class:`bytes`) [const char \\*, :c:type:`Py_ssize_t`]" - -#: ../../c-api/arg.rst:611 -msgid "" -"This converts a C string and its lengths to a Python object. If the C " -"string pointer is ``NULL``, ``None`` is returned." -msgstr "" - -#: ../../c-api/arg.rst:615 ../../c-api/arg.rst:631 -msgid "Same as ``s``." -msgstr "和 ``s`` 相同。" - -#: ../../c-api/arg.rst:617 -msgid "" -"``z#`` (:class:`str` or ``None``) [const char \\*, :c:type:`Py_ssize_t`]" -msgstr "" -"``z#`` (:class:`str` 或 ``None``) [const char \\*, :c:type:`Py_ssize_t`]" - -#: ../../c-api/arg.rst:618 ../../c-api/arg.rst:634 -msgid "Same as ``s#``." -msgstr "和 ``s#`` 相同。" - -#: ../../c-api/arg.rst:620 -msgid "``u`` (:class:`str`) [const wchar_t \\*]" -msgstr "``u`` (:class:`str`) [const wchar_t \\*]" - -#: ../../c-api/arg.rst:621 -msgid "" -"Convert a null-terminated :c:type:`wchar_t` buffer of Unicode (UTF-16 or " -"UCS-4) data to a Python Unicode object. If the Unicode buffer pointer is " -"``NULL``, ``None`` is returned." -msgstr "" - -#: ../../c-api/arg.rst:625 -msgid "``u#`` (:class:`str`) [const wchar_t \\*, :c:type:`Py_ssize_t`]" -msgstr "``u#`` (:class:`str`) [const wchar_t \\*, :c:type:`Py_ssize_t`]" - -#: ../../c-api/arg.rst:626 -msgid "" -"Convert a Unicode (UTF-16 or UCS-4) data buffer and its length to a Python " -"Unicode object. If the Unicode buffer pointer is ``NULL``, the length is " -"ignored and ``None`` is returned." -msgstr "" - -#: ../../c-api/arg.rst:630 -msgid "``U`` (:class:`str` or ``None``) [const char \\*]" -msgstr "``U`` (:class:`str` 或 ``None``) [const char \\*]" - -#: ../../c-api/arg.rst:633 -msgid "" -"``U#`` (:class:`str` or ``None``) [const char \\*, :c:type:`Py_ssize_t`]" -msgstr "" -"``U#`` (:class:`str` 或 ``None``) [const char \\*, :c:type:`Py_ssize_t`]" - -#: ../../c-api/arg.rst:637 -msgid "Convert a plain C :c:expr:`int` to a Python integer object." -msgstr "將一個 C 的 :c:expr:`int` 轉換成 Python 整數物件。" - -#: ../../c-api/arg.rst:639 -msgid "``b`` (:class:`int`) [char]" -msgstr "``b`` (:class:`int`) [char]" - -#: ../../c-api/arg.rst:640 -msgid "Convert a plain C :c:expr:`char` to a Python integer object." -msgstr "將一個 C 的 :c:expr:`char` 轉換成 Python 整數物件。" - -#: ../../c-api/arg.rst:643 -msgid "Convert a plain C :c:expr:`short int` to a Python integer object." -msgstr "將一個 C 的 :c:expr:`short int` 轉換成 Python 整數物件。" - -#: ../../c-api/arg.rst:646 -msgid "Convert a C :c:expr:`long int` to a Python integer object." -msgstr "將一個 C 的 :c:expr:`long int` 轉換成 Python 整數物件。" - -#: ../../c-api/arg.rst:649 -msgid "Convert a C :c:expr:`unsigned char` to a Python integer object." -msgstr "將一個 C 的 :c:expr:`unsigned char` 轉換成 Python 整數物件。" - -#: ../../c-api/arg.rst:652 -msgid "Convert a C :c:expr:`unsigned short int` to a Python integer object." -msgstr "將一個 C 的 :c:expr:`unsigned short int` 轉換成 Python 整數物件。" - -#: ../../c-api/arg.rst:655 -msgid "Convert a C :c:expr:`unsigned int` to a Python integer object." -msgstr "將一個 C 的 :c:expr:`unsigned int` 轉換成 Python 整數物件。" - -#: ../../c-api/arg.rst:658 -msgid "Convert a C :c:expr:`unsigned long` to a Python integer object." -msgstr "將一個 C 的 :c:expr:`unsigned long` 轉換成 Python 整數物件。" - -#: ../../c-api/arg.rst:661 -msgid "Convert a C :c:expr:`long long` to a Python integer object." -msgstr "將一個 C 的 :c:expr:`long long` 轉換成 Python 整數物件。" - -#: ../../c-api/arg.rst:666 -msgid "Convert a C :c:expr:`unsigned long long` to a Python integer object." -msgstr "將一個 C 的 :c:expr:`unsigned long long` 轉換成 Python 整數物件。" - -#: ../../c-api/arg.rst:669 -msgid "Convert a C :c:type:`Py_ssize_t` to a Python integer." -msgstr "將一個 C 的 :c:type:`Py_ssize_t` 轉換成 Python 整數。" - -#: ../../c-api/arg.rst:672 -msgid "Convert a C :c:expr:`int` to a Python :class:`bool` object." -msgstr "將一個 C 的 :c:expr:`int` 轉換成 Python :class:`bool` 物件。" - -#: ../../c-api/arg.rst:674 -msgid "" -"Be aware that this format requires an ``int`` argument. Unlike most other " -"contexts in C, variadic arguments are not coerced to a suitable type " -"automatically. You can convert another type (for example, a pointer or a " -"float) to a suitable ``int`` value using ``(x) ? 1 : 0`` or ``!!x``." -msgstr "" - -#: ../../c-api/arg.rst:682 -msgid "``c`` (:class:`bytes` of length 1) [char]" -msgstr "``c`` (長度為 1 的 :class:`bytes`) [char]" - -#: ../../c-api/arg.rst:683 -msgid "" -"Convert a C :c:expr:`int` representing a byte to a Python :class:`bytes` " -"object of length 1." -msgstr "" -"將一個 C 中代表一個位元組的 :c:expr:`int` 轉換成 Python 中長度為一的 :class:" -"`bytes`。" - -#: ../../c-api/arg.rst:687 -msgid "" -"Convert a C :c:expr:`int` representing a character to Python :class:`str` " -"object of length 1." -msgstr "" -"將一個 C 中代表一個字元的 :c:expr:`int` 轉換成 Python 中長度為一的 :class:" -"`str`。" - -#: ../../c-api/arg.rst:691 -msgid "Convert a C :c:expr:`double` to a Python floating-point number." -msgstr "將一個 C 的 :c:expr:`double` 轉換成 Python 浮點數。" - -#: ../../c-api/arg.rst:694 -msgid "Convert a C :c:expr:`float` to a Python floating-point number." -msgstr "將一個 C 的 :c:expr:`float` 轉換成 Python 浮點數。" - -#: ../../c-api/arg.rst:696 -msgid "``D`` (:class:`complex`) [Py_complex \\*]" -msgstr "``D`` (:class:`complex`) [Py_complex \\*]" - -#: ../../c-api/arg.rst:697 -msgid "Convert a C :c:type:`Py_complex` structure to a Python complex number." -msgstr "將一個 C 的 :c:type:`Py_complex` 結構轉換成 Python 複數。" - -#: ../../c-api/arg.rst:700 -msgid "" -"Pass a Python object untouched but create a new :term:`strong reference` to " -"it (i.e. its reference count is incremented by one). If the object passed in " -"is a ``NULL`` pointer, it is assumed that this was caused because the call " -"producing the argument found an error and set an exception. Therefore, :c:" -"func:`Py_BuildValue` will return ``NULL`` but won't raise an exception. If " -"no exception has been raised yet, :exc:`SystemError` is set." -msgstr "" - -#: ../../c-api/arg.rst:709 -msgid "``S`` (object) [PyObject \\*]" -msgstr "``S`` (object) [PyObject \\*]" - -#: ../../c-api/arg.rst:710 -msgid "Same as ``O``." -msgstr "和 ``O`` 相同。" - -#: ../../c-api/arg.rst:712 -msgid "``N`` (object) [PyObject \\*]" -msgstr "``N`` (object) [PyObject \\*]" - -#: ../../c-api/arg.rst:713 -msgid "" -"Same as ``O``, except it doesn't create a new :term:`strong reference`. " -"Useful when the object is created by a call to an object constructor in the " -"argument list." -msgstr "" - -#: ../../c-api/arg.rst:717 -msgid "``O&`` (object) [*converter*, *anything*]" -msgstr "``O&`` (object) [*converter*, *anything*]" - -#: ../../c-api/arg.rst:718 -msgid "" -"Convert *anything* to a Python object through a *converter* function. The " -"function is called with *anything* (which should be compatible with :c:expr:" -"`void*`) as its argument and should return a \"new\" Python object, or " -"``NULL`` if an error occurred." -msgstr "" - -#: ../../c-api/arg.rst:723 -msgid "``(items)`` (:class:`tuple`) [*matching-items*]" -msgstr "``(items)`` (:class:`tuple`) [*matching-items*]" - -#: ../../c-api/arg.rst:724 -msgid "" -"Convert a sequence of C values to a Python tuple with the same number of " -"items." -msgstr "" - -#: ../../c-api/arg.rst:726 -msgid "``[items]`` (:class:`list`) [*matching-items*]" -msgstr "``[items]`` (:class:`list`) [*matching-items*]" - -#: ../../c-api/arg.rst:727 -msgid "" -"Convert a sequence of C values to a Python list with the same number of " -"items." -msgstr "" - -#: ../../c-api/arg.rst:729 -msgid "``{items}`` (:class:`dict`) [*matching-items*]" -msgstr "``{items}`` (:class:`dict`) [*matching-items*]" - -#: ../../c-api/arg.rst:730 -msgid "" -"Convert a sequence of C values to a Python dictionary. Each pair of " -"consecutive C values adds one item to the dictionary, serving as key and " -"value, respectively." -msgstr "" - -#: ../../c-api/arg.rst:734 -msgid "" -"If there is an error in the format string, the :exc:`SystemError` exception " -"is set and ``NULL`` returned." -msgstr "" - -#: ../../c-api/arg.rst:739 -msgid "" -"Identical to :c:func:`Py_BuildValue`, except that it accepts a va_list " -"rather than a variable number of arguments." -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-10-25 00:15+0000\n" +"PO-Revision-Date: 2022-10-16 03:21+0800\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" +"X-Generator: Poedit 3.1.1\n" + +#: ../../c-api/arg.rst:6 +msgid "Parsing arguments and building values" +msgstr "剖析引數與建置數值" + +#: ../../c-api/arg.rst:8 +msgid "" +"These functions are useful when creating your own extension functions and " +"methods. Additional information and examples are available in :ref:" +"`extending-index`." +msgstr "" + +#: ../../c-api/arg.rst:12 +msgid "" +"The first three of these functions described, :c:func:`PyArg_ParseTuple`, :c:" +"func:`PyArg_ParseTupleAndKeywords`, and :c:func:`PyArg_Parse`, all use " +"*format strings* which are used to tell the function about the expected " +"arguments. The format strings use the same syntax for each of these " +"functions." +msgstr "" + +#: ../../c-api/arg.rst:19 +msgid "Parsing arguments" +msgstr "剖析引數" + +#: ../../c-api/arg.rst:21 +msgid "" +"A format string consists of zero or more \"format units.\" A format unit " +"describes one Python object; it is usually a single character or a " +"parenthesized sequence of format units. With a few exceptions, a format " +"unit that is not a parenthesized sequence normally corresponds to a single " +"address argument to these functions. In the following description, the " +"quoted form is the format unit; the entry in (round) parentheses is the " +"Python object type that matches the format unit; and the entry in [square] " +"brackets is the type of the C variable(s) whose address should be passed." +msgstr "" + +#: ../../c-api/arg.rst:33 +msgid "Strings and buffers" +msgstr "字串與緩衝區" + +#: ../../c-api/arg.rst:37 +msgid "" +"On Python 3.12 and older, the macro :c:macro:`!PY_SSIZE_T_CLEAN` must be " +"defined before including :file:`Python.h` to use all ``#`` variants of " +"formats (``s#``, ``y#``, etc.) explained below. This is not necessary on " +"Python 3.13 and later." +msgstr "" + +#: ../../c-api/arg.rst:42 +msgid "" +"These formats allow accessing an object as a contiguous chunk of memory. You " +"don't have to provide raw storage for the returned unicode or bytes area." +msgstr "" + +#: ../../c-api/arg.rst:46 +msgid "Unless otherwise stated, buffers are not NUL-terminated." +msgstr "" + +#: ../../c-api/arg.rst:48 +msgid "There are three ways strings and buffers can be converted to C:" +msgstr "" + +#: ../../c-api/arg.rst:50 +msgid "" +"Formats such as ``y*`` and ``s*`` fill a :c:type:`Py_buffer` structure. This " +"locks the underlying buffer so that the caller can subsequently use the " +"buffer even inside a :c:type:`Py_BEGIN_ALLOW_THREADS` block without the risk " +"of mutable data being resized or destroyed. As a result, **you have to " +"call** :c:func:`PyBuffer_Release` after you have finished processing the " +"data (or in any early abort case)." +msgstr "" + +#: ../../c-api/arg.rst:57 +msgid "" +"The ``es``, ``es#``, ``et`` and ``et#`` formats allocate the result buffer. " +"**You have to call** :c:func:`PyMem_Free` after you have finished processing " +"the data (or in any early abort case)." +msgstr "" + +#: ../../c-api/arg.rst:63 +msgid "" +"Other formats take a :class:`str` or a read-only :term:`bytes-like object`, " +"such as :class:`bytes`, and provide a ``const char *`` pointer to its " +"buffer. In this case the buffer is \"borrowed\": it is managed by the " +"corresponding Python object, and shares the lifetime of this object. You " +"won't have to release any memory yourself." +msgstr "" + +#: ../../c-api/arg.rst:70 +msgid "" +"To ensure that the underlying buffer may be safely borrowed, the object's :c:" +"member:`PyBufferProcs.bf_releasebuffer` field must be ``NULL``. This " +"disallows common mutable objects such as :class:`bytearray`, but also some " +"read-only objects such as :class:`memoryview` of :class:`bytes`." +msgstr "" + +#: ../../c-api/arg.rst:76 +msgid "" +"Besides this ``bf_releasebuffer`` requirement, there is no check to verify " +"whether the input object is immutable (e.g. whether it would honor a request " +"for a writable buffer, or whether another thread can mutate the data)." +msgstr "" + +#: ../../c-api/arg.rst:80 +msgid "``s`` (:class:`str`) [const char \\*]" +msgstr "``s`` (:class:`str`) [const char \\*]" + +#: ../../c-api/arg.rst:81 +msgid "" +"Convert a Unicode object to a C pointer to a character string. A pointer to " +"an existing string is stored in the character pointer variable whose address " +"you pass. The C string is NUL-terminated. The Python string must not " +"contain embedded null code points; if it does, a :exc:`ValueError` exception " +"is raised. Unicode objects are converted to C strings using ``'utf-8'`` " +"encoding. If this conversion fails, a :exc:`UnicodeError` is raised." +msgstr "" + +#: ../../c-api/arg.rst:90 +msgid "" +"This format does not accept :term:`bytes-like objects `. " +"If you want to accept filesystem paths and convert them to C character " +"strings, it is preferable to use the ``O&`` format with :c:func:" +"`PyUnicode_FSConverter` as *converter*." +msgstr "" + +#: ../../c-api/arg.rst:96 +msgid "" +"Previously, :exc:`TypeError` was raised when embedded null code points were " +"encountered in the Python string." +msgstr "" + +#: ../../c-api/arg.rst:100 +msgid "``s*`` (:class:`str` or :term:`bytes-like object`) [Py_buffer]" +msgstr "``s*`` (:class:`str` 或 :term:`bytes-like object`) [Py_buffer]" + +#: ../../c-api/arg.rst:101 +msgid "" +"This format accepts Unicode objects as well as bytes-like objects. It fills " +"a :c:type:`Py_buffer` structure provided by the caller. In this case the " +"resulting C string may contain embedded NUL bytes. Unicode objects are " +"converted to C strings using ``'utf-8'`` encoding." +msgstr "" + +#: ../../c-api/arg.rst:106 +msgid "" +"``s#`` (:class:`str`, read-only :term:`bytes-like object`) [const char \\*, :" +"c:type:`Py_ssize_t`]" +msgstr "" +"``s#`` (:class:`str`、唯讀的 :term:`bytes-like object`) [const char \\*, :c:" +"type:`Py_ssize_t`]" + +#: ../../c-api/arg.rst:107 +msgid "" +"Like ``s*``, except that it provides a :ref:`borrowed buffer `. The result is stored into two C variables, the first one a pointer " +"to a C string, the second one its length. The string may contain embedded " +"null bytes. Unicode objects are converted to C strings using ``'utf-8'`` " +"encoding." +msgstr "" + +#: ../../c-api/arg.rst:113 ../../c-api/arg.rst:614 +msgid "``z`` (:class:`str` or ``None``) [const char \\*]" +msgstr "``z`` (:class:`str` 或 ``None``) [const char \\*]" + +#: ../../c-api/arg.rst:114 +msgid "" +"Like ``s``, but the Python object may also be ``None``, in which case the C " +"pointer is set to ``NULL``." +msgstr "" + +#: ../../c-api/arg.rst:117 +msgid "" +"``z*`` (:class:`str`, :term:`bytes-like object` or ``None``) [Py_buffer]" +msgstr "" +"``z*`` (:class:`str`、:term:`bytes-like object` 或 ``None``) [Py_buffer]" + +#: ../../c-api/arg.rst:118 +msgid "" +"Like ``s*``, but the Python object may also be ``None``, in which case the " +"``buf`` member of the :c:type:`Py_buffer` structure is set to ``NULL``." +msgstr "" + +#: ../../c-api/arg.rst:121 +msgid "" +"``z#`` (:class:`str`, read-only :term:`bytes-like object` or ``None``) " +"[const char \\*, :c:type:`Py_ssize_t`]" +msgstr "" +"``z#`` (:class:`str`、唯讀的 :term:`bytes-like object` 或 ``None``) [const " +"char \\*, :c:type:`Py_ssize_t`]" + +#: ../../c-api/arg.rst:122 +msgid "" +"Like ``s#``, but the Python object may also be ``None``, in which case the C " +"pointer is set to ``NULL``." +msgstr "" + +#: ../../c-api/arg.rst:125 +msgid "``y`` (read-only :term:`bytes-like object`) [const char \\*]" +msgstr "``y`` (唯讀的 :term:`bytes-like object`) [const char \\*]" + +#: ../../c-api/arg.rst:126 +msgid "" +"This format converts a bytes-like object to a C pointer to a :ref:`borrowed " +"` character string; it does not accept Unicode " +"objects. The bytes buffer must not contain embedded null bytes; if it does, " +"a :exc:`ValueError` exception is raised." +msgstr "" + +#: ../../c-api/arg.rst:132 +msgid "" +"Previously, :exc:`TypeError` was raised when embedded null bytes were " +"encountered in the bytes buffer." +msgstr "" + +#: ../../c-api/arg.rst:136 +msgid "``y*`` (:term:`bytes-like object`) [Py_buffer]" +msgstr "``y*`` (:term:`bytes-like object`) [Py_buffer]" + +#: ../../c-api/arg.rst:137 +msgid "" +"This variant on ``s*`` doesn't accept Unicode objects, only bytes-like " +"objects. **This is the recommended way to accept binary data.**" +msgstr "" + +#: ../../c-api/arg.rst:141 +msgid "" +"``y#`` (read-only :term:`bytes-like object`) [const char \\*, :c:type:" +"`Py_ssize_t`]" +msgstr "" +"``y#`` (唯讀的 :term:`bytes-like object`) [const char \\*, :c:type:" +"`Py_ssize_t`]" + +#: ../../c-api/arg.rst:142 +msgid "" +"This variant on ``s#`` doesn't accept Unicode objects, only bytes-like " +"objects." +msgstr "" + +#: ../../c-api/arg.rst:145 +msgid "``S`` (:class:`bytes`) [PyBytesObject \\*]" +msgstr "``S`` (:class:`bytes`) [PyBytesObject \\*]" + +#: ../../c-api/arg.rst:146 +msgid "" +"Requires that the Python object is a :class:`bytes` object, without " +"attempting any conversion. Raises :exc:`TypeError` if the object is not a " +"bytes object. The C variable may also be declared as :c:expr:`PyObject*`." +msgstr "" + +#: ../../c-api/arg.rst:150 +msgid "``Y`` (:class:`bytearray`) [PyByteArrayObject \\*]" +msgstr "``Y`` (:class:`bytearray`) [PyByteArrayObject \\*]" + +#: ../../c-api/arg.rst:151 +msgid "" +"Requires that the Python object is a :class:`bytearray` object, without " +"attempting any conversion. Raises :exc:`TypeError` if the object is not a :" +"class:`bytearray` object. The C variable may also be declared as :c:expr:" +"`PyObject*`." +msgstr "" + +#: ../../c-api/arg.rst:155 +msgid "``U`` (:class:`str`) [PyObject \\*]" +msgstr "``U`` (:class:`str`) [PyObject \\*]" + +#: ../../c-api/arg.rst:156 +msgid "" +"Requires that the Python object is a Unicode object, without attempting any " +"conversion. Raises :exc:`TypeError` if the object is not a Unicode object. " +"The C variable may also be declared as :c:expr:`PyObject*`." +msgstr "" + +#: ../../c-api/arg.rst:160 +msgid "``w*`` (read-write :term:`bytes-like object`) [Py_buffer]" +msgstr "``w*`` (可讀寫 :term:`bytes-like object`) [Py_buffer]" + +#: ../../c-api/arg.rst:161 +msgid "" +"This format accepts any object which implements the read-write buffer " +"interface. It fills a :c:type:`Py_buffer` structure provided by the caller. " +"The buffer may contain embedded null bytes. The caller has to call :c:func:" +"`PyBuffer_Release` when it is done with the buffer." +msgstr "" + +#: ../../c-api/arg.rst:166 +msgid "``es`` (:class:`str`) [const char \\*encoding, char \\*\\*buffer]" +msgstr "``es`` (:class:`str`) [const char \\*encoding, char \\*\\*buffer]" + +#: ../../c-api/arg.rst:167 +msgid "" +"This variant on ``s`` is used for encoding Unicode into a character buffer. " +"It only works for encoded data without embedded NUL bytes." +msgstr "" + +#: ../../c-api/arg.rst:170 +msgid "" +"This format requires two arguments. The first is only used as input, and " +"must be a :c:expr:`const char*` which points to the name of an encoding as a " +"NUL-terminated string, or ``NULL``, in which case ``'utf-8'`` encoding is " +"used. An exception is raised if the named encoding is not known to Python. " +"The second argument must be a :c:expr:`char**`; the value of the pointer it " +"references will be set to a buffer with the contents of the argument text. " +"The text will be encoded in the encoding specified by the first argument." +msgstr "" + +#: ../../c-api/arg.rst:178 +msgid "" +":c:func:`PyArg_ParseTuple` will allocate a buffer of the needed size, copy " +"the encoded data into this buffer and adjust *\\*buffer* to reference the " +"newly allocated storage. The caller is responsible for calling :c:func:" +"`PyMem_Free` to free the allocated buffer after use." +msgstr "" + +#: ../../c-api/arg.rst:183 +msgid "" +"``et`` (:class:`str`, :class:`bytes` or :class:`bytearray`) [const char " +"\\*encoding, char \\*\\*buffer]" +msgstr "" +"``et`` (:class:`str`、:class:`bytes` 或 :class:`bytearray`) [const char " +"\\*encoding, char \\*\\*buffer]" + +#: ../../c-api/arg.rst:184 +msgid "" +"Same as ``es`` except that byte string objects are passed through without " +"recoding them. Instead, the implementation assumes that the byte string " +"object uses the encoding passed in as parameter." +msgstr "" + +#: ../../c-api/arg.rst:188 +msgid "" +"``es#`` (:class:`str`) [const char \\*encoding, char \\*\\*buffer, :c:type:" +"`Py_ssize_t` \\*buffer_length]" +msgstr "" +"``es#`` (:class:`str`) [const char \\*encoding, char \\*\\*buffer, :c:type:" +"`Py_ssize_t` \\*buffer_length]" + +#: ../../c-api/arg.rst:189 +msgid "" +"This variant on ``s#`` is used for encoding Unicode into a character buffer. " +"Unlike the ``es`` format, this variant allows input data which contains NUL " +"characters." +msgstr "" + +#: ../../c-api/arg.rst:193 +msgid "" +"It requires three arguments. The first is only used as input, and must be " +"a :c:expr:`const char*` which points to the name of an encoding as a NUL-" +"terminated string, or ``NULL``, in which case ``'utf-8'`` encoding is used. " +"An exception is raised if the named encoding is not known to Python. The " +"second argument must be a :c:expr:`char**`; the value of the pointer it " +"references will be set to a buffer with the contents of the argument text. " +"The text will be encoded in the encoding specified by the first argument. " +"The third argument must be a pointer to an integer; the referenced integer " +"will be set to the number of bytes in the output buffer." +msgstr "" + +#: ../../c-api/arg.rst:203 +msgid "There are two modes of operation:" +msgstr "有兩個操作模式：" + +#: ../../c-api/arg.rst:205 +msgid "" +"If *\\*buffer* points a ``NULL`` pointer, the function will allocate a " +"buffer of the needed size, copy the encoded data into this buffer and set " +"*\\*buffer* to reference the newly allocated storage. The caller is " +"responsible for calling :c:func:`PyMem_Free` to free the allocated buffer " +"after usage." +msgstr "" + +#: ../../c-api/arg.rst:210 +msgid "" +"If *\\*buffer* points to a non-``NULL`` pointer (an already allocated " +"buffer), :c:func:`PyArg_ParseTuple` will use this location as the buffer and " +"interpret the initial value of *\\*buffer_length* as the buffer size. It " +"will then copy the encoded data into the buffer and NUL-terminate it. If " +"the buffer is not large enough, a :exc:`ValueError` will be set." +msgstr "" + +#: ../../c-api/arg.rst:216 +msgid "" +"In both cases, *\\*buffer_length* is set to the length of the encoded data " +"without the trailing NUL byte." +msgstr "" + +#: ../../c-api/arg.rst:219 +msgid "" +"``et#`` (:class:`str`, :class:`bytes` or :class:`bytearray`) [const char " +"\\*encoding, char \\*\\*buffer, :c:type:`Py_ssize_t` \\*buffer_length]" +msgstr "" + +#: ../../c-api/arg.rst:220 +msgid "" +"Same as ``es#`` except that byte string objects are passed through without " +"recoding them. Instead, the implementation assumes that the byte string " +"object uses the encoding passed in as parameter." +msgstr "" + +#: ../../c-api/arg.rst:224 +msgid "" +"``u``, ``u#``, ``Z``, and ``Z#`` are removed because they used a legacy " +"``Py_UNICODE*`` representation." +msgstr "" + +#: ../../c-api/arg.rst:230 +msgid "Numbers" +msgstr "數字" + +#: ../../c-api/arg.rst:232 +msgid "" +"These formats allow representing Python numbers or single characters as C " +"numbers. Formats that require :class:`int`, :class:`float` or :class:" +"`complex` can also use the corresponding special methods :meth:`~object." +"__index__`, :meth:`~object.__float__` or :meth:`~object.__complex__` to " +"convert the Python object to the required type." +msgstr "" + +#: ../../c-api/arg.rst:238 +msgid "" +"For signed integer formats, :exc:`OverflowError` is raised if the value is " +"out of range for the C type. For unsigned integer formats, no range checking " +"is done --- the most significant bits are silently truncated when the " +"receiving field is too small to receive the value." +msgstr "" + +#: ../../c-api/arg.rst:244 +msgid "``b`` (:class:`int`) [unsigned char]" +msgstr "``b`` (:class:`int`) [unsigned char]" + +#: ../../c-api/arg.rst:245 +msgid "" +"Convert a nonnegative Python integer to an unsigned tiny integer, stored in " +"a C :c:expr:`unsigned char`." +msgstr "" +"將一個 Python 非負整數轉換成無符號 tiny integer（小整數），儲存在 C 的 :c:" +"expr:`unsigned`" + +#: ../../c-api/arg.rst:248 ../../c-api/arg.rst:648 +msgid "``B`` (:class:`int`) [unsigned char]" +msgstr "``B`` (:class:`int`) [unsigned char]" + +#: ../../c-api/arg.rst:249 +msgid "" +"Convert a Python integer to a tiny integer without overflow checking, stored " +"in a C :c:expr:`unsigned char`." +msgstr "" +"將一個 Python 整數轉換成 tiny integer，轉換過程無溢位檢查，儲存在 C 的 :c:" +"expr:`unsigned char`。" + +#: ../../c-api/arg.rst:252 ../../c-api/arg.rst:642 +msgid "``h`` (:class:`int`) [short int]" +msgstr "``h`` (:class:`int`) [short int]" + +#: ../../c-api/arg.rst:253 +msgid "Convert a Python integer to a C :c:expr:`short int`." +msgstr "將一個 Python 整數轉換成 C 的 :c:expr:`short int`。" + +#: ../../c-api/arg.rst:255 ../../c-api/arg.rst:651 +msgid "``H`` (:class:`int`) [unsigned short int]" +msgstr "``H`` (:class:`int`) [unsigned short int]" + +#: ../../c-api/arg.rst:256 +msgid "" +"Convert a Python integer to a C :c:expr:`unsigned short int`, without " +"overflow checking." +msgstr "" +"將一個 Python 整數轉換成 C 的 :c:expr:`unsigned short int`，轉換過程無溢位檢" +"查。" + +#: ../../c-api/arg.rst:259 ../../c-api/arg.rst:636 +msgid "``i`` (:class:`int`) [int]" +msgstr "``i`` (:class:`int`) [int]" + +#: ../../c-api/arg.rst:260 +msgid "Convert a Python integer to a plain C :c:expr:`int`." +msgstr "將一個 Python 整數轉換成 C 的 :c:expr:`int`。" + +#: ../../c-api/arg.rst:262 ../../c-api/arg.rst:654 +msgid "``I`` (:class:`int`) [unsigned int]" +msgstr "``I`` (:class:`int`) [unsigned int]" + +#: ../../c-api/arg.rst:263 +msgid "" +"Convert a Python integer to a C :c:expr:`unsigned int`, without overflow " +"checking." +msgstr "" +"將一個 Python 整數轉換成 C 的 :c:expr:`unsigned int`，轉換過程無溢位檢查。" + +#: ../../c-api/arg.rst:266 ../../c-api/arg.rst:645 +msgid "``l`` (:class:`int`) [long int]" +msgstr "``l`` (:class:`int`) [long int]" + +#: ../../c-api/arg.rst:267 +msgid "Convert a Python integer to a C :c:expr:`long int`." +msgstr "將一個 Python 整數轉換成 C 的 :c:expr:`long int`。" + +#: ../../c-api/arg.rst:269 ../../c-api/arg.rst:657 +msgid "``k`` (:class:`int`) [unsigned long]" +msgstr "``k`` (:class:`int`) [unsigned long]" + +#: ../../c-api/arg.rst:270 +msgid "" +"Convert a Python integer to a C :c:expr:`unsigned long` without overflow " +"checking." +msgstr "" +"將一個 Python 整數轉換成 C 的 :c:expr:`unsigned long`，轉換過程無溢位檢查。" + +#: ../../c-api/arg.rst:273 ../../c-api/arg.rst:283 +msgid "Use :meth:`~object.__index__` if available." +msgstr "如有提供則使用 :meth:`~object.__index__`。" + +#: ../../c-api/arg.rst:276 ../../c-api/arg.rst:660 +msgid "``L`` (:class:`int`) [long long]" +msgstr "``L`` (:class:`int`) [long long]" + +#: ../../c-api/arg.rst:277 +msgid "Convert a Python integer to a C :c:expr:`long long`." +msgstr "將一個 Python 整數轉換成 C 的 :c:expr:`long long`。" + +#: ../../c-api/arg.rst:279 ../../c-api/arg.rst:665 +msgid "``K`` (:class:`int`) [unsigned long long]" +msgstr "``K`` (:class:`int`) [unsigned long long]" + +#: ../../c-api/arg.rst:280 +msgid "" +"Convert a Python integer to a C :c:expr:`unsigned long long` without " +"overflow checking." +msgstr "" +"將一個 Python 整數轉換成 C 的 :c:expr:`unsigned long long`，轉換過程無溢位檢" +"查。" + +#: ../../c-api/arg.rst:286 ../../c-api/arg.rst:668 +msgid "``n`` (:class:`int`) [:c:type:`Py_ssize_t`]" +msgstr "``n`` (:class:`int`) [:c:type:`Py_ssize_t`]" + +#: ../../c-api/arg.rst:287 +msgid "Convert a Python integer to a C :c:type:`Py_ssize_t`." +msgstr "將一個 Python 整數轉換成 C 的 :c:type:`Py_ssize_t`。" + +#: ../../c-api/arg.rst:289 +msgid "``c`` (:class:`bytes` or :class:`bytearray` of length 1) [char]" +msgstr "``c`` (:class:`bytes` 或長度為 1 的 :class:`bytearray`) [char]" + +#: ../../c-api/arg.rst:290 +msgid "" +"Convert a Python byte, represented as a :class:`bytes` or :class:`bytearray` " +"object of length 1, to a C :c:expr:`char`." +msgstr "" + +#: ../../c-api/arg.rst:293 +msgid "Allow :class:`bytearray` objects." +msgstr "允許 :class:`bytearray` 物件。" + +#: ../../c-api/arg.rst:296 ../../c-api/arg.rst:686 +msgid "``C`` (:class:`str` of length 1) [int]" +msgstr "``C`` (長度為 1 的 :class:`str`) [int]" + +#: ../../c-api/arg.rst:297 +msgid "" +"Convert a Python character, represented as a :class:`str` object of length " +"1, to a C :c:expr:`int`." +msgstr "" + +#: ../../c-api/arg.rst:300 ../../c-api/arg.rst:693 +msgid "``f`` (:class:`float`) [float]" +msgstr "``f`` (:class:`float`) [float]" + +#: ../../c-api/arg.rst:301 +msgid "Convert a Python floating-point number to a C :c:expr:`float`." +msgstr "將一個 Python 浮點數轉換成 C 的 :c:type::c:expr:`float`。" + +#: ../../c-api/arg.rst:303 ../../c-api/arg.rst:690 +msgid "``d`` (:class:`float`) [double]" +msgstr "``d`` (:class:`float`) [double]" + +#: ../../c-api/arg.rst:304 +msgid "Convert a Python floating-point number to a C :c:expr:`double`." +msgstr "將一個 Python 浮點數轉換成 C 的 :c:type::c:expr:`double`。" + +#: ../../c-api/arg.rst:306 +msgid "``D`` (:class:`complex`) [Py_complex]" +msgstr "``D`` (:class:`complex`) [Py_complex]" + +#: ../../c-api/arg.rst:307 +msgid "Convert a Python complex number to a C :c:type:`Py_complex` structure." +msgstr "將一個 Python 複數轉換成 C 的 :c:type:`Py_complex` 結構。" + +#: ../../c-api/arg.rst:310 +msgid "Other objects" +msgstr "其他物件" + +#: ../../c-api/arg.rst:312 ../../c-api/arg.rst:699 +msgid "``O`` (object) [PyObject \\*]" +msgstr "``O`` (object) [PyObject \\*]" + +#: ../../c-api/arg.rst:313 +msgid "" +"Store a Python object (without any conversion) in a C object pointer. The C " +"program thus receives the actual object that was passed. A new :term:" +"`strong reference` to the object is not created (i.e. its reference count is " +"not increased). The pointer stored is not ``NULL``." +msgstr "" + +#: ../../c-api/arg.rst:319 +msgid "``O!`` (object) [*typeobject*, PyObject \\*]" +msgstr "``O!`` (object) [*typeobject*, PyObject \\*]" + +#: ../../c-api/arg.rst:320 +msgid "" +"Store a Python object in a C object pointer. This is similar to ``O``, but " +"takes two C arguments: the first is the address of a Python type object, the " +"second is the address of the C variable (of type :c:expr:`PyObject*`) into " +"which the object pointer is stored. If the Python object does not have the " +"required type, :exc:`TypeError` is raised." +msgstr "" + +#: ../../c-api/arg.rst:328 +msgid "``O&`` (object) [*converter*, *address*]" +msgstr "``O&`` (object) [*converter*, *address*]" + +#: ../../c-api/arg.rst:329 +msgid "" +"Convert a Python object to a C variable through a *converter* function. " +"This takes two arguments: the first is a function, the second is the address " +"of a C variable (of arbitrary type), converted to :c:expr:`void *`. The " +"*converter* function in turn is called as follows::" +msgstr "" + +#: ../../c-api/arg.rst:334 +msgid "status = converter(object, address);" +msgstr "status = converter(object, address);" + +#: ../../c-api/arg.rst:336 +msgid "" +"where *object* is the Python object to be converted and *address* is the :c:" +"expr:`void*` argument that was passed to the ``PyArg_Parse*`` function. The " +"returned *status* should be ``1`` for a successful conversion and ``0`` if " +"the conversion has failed. When the conversion fails, the *converter* " +"function should raise an exception and leave the content of *address* " +"unmodified." +msgstr "" + +#: ../../c-api/arg.rst:345 +msgid "" +"If the *converter* returns :c:macro:`!Py_CLEANUP_SUPPORTED`, it may get " +"called a second time if the argument parsing eventually fails, giving the " +"converter a chance to release any memory that it had already allocated. In " +"this second call, the *object* parameter will be ``NULL``; *address* will " +"have the same value as in the original call." +msgstr "" + +#: ../../c-api/arg.rst:351 +msgid "" +"Examples of converters: :c:func:`PyUnicode_FSConverter` and :c:func:" +"`PyUnicode_FSDecoder`." +msgstr "" + +#: ../../c-api/arg.rst:354 +msgid ":c:macro:`!Py_CLEANUP_SUPPORTED` was added." +msgstr "新增 :c:macro:`!Py_CLEANUP_SUPPORTED`。" + +#: ../../c-api/arg.rst:357 ../../c-api/arg.rst:671 +msgid "``p`` (:class:`bool`) [int]" +msgstr "``p`` (:class:`bool`) [int]" + +#: ../../c-api/arg.rst:358 +msgid "" +"Tests the value passed in for truth (a boolean **p**\\ redicate) and " +"converts the result to its equivalent C true/false integer value. Sets the " +"int to ``1`` if the expression was true and ``0`` if it was false. This " +"accepts any valid Python value. See :ref:`truth` for more information about " +"how Python tests values for truth." +msgstr "" + +#: ../../c-api/arg.rst:366 +msgid "``(items)`` (sequence) [*matching-items*]" +msgstr "``(items)`` (sequence) [*matching-items*]" + +#: ../../c-api/arg.rst:367 +msgid "" +"The object must be a Python sequence (except :class:`str`, :class:`bytes` " +"or :class:`bytearray`) whose length is the number of format units in " +"*items*. The C arguments must correspond to the individual format units in " +"*items*. Format units for sequences may be nested." +msgstr "" + +#: ../../c-api/arg.rst:372 +msgid "" +"If *items* contains format units which store a :ref:`borrowed buffer ` (``s``, ``s#``, ``z``, ``z#``, ``y``, or ``y#``) or a :" +"term:`borrowed reference` (``S``, ``Y``, ``U``, ``O``, or ``O!``), the " +"object must be a Python tuple. The *converter* for the ``O&`` format unit in " +"*items* must not store a borrowed buffer or a borrowed reference." +msgstr "" + +#: ../../c-api/arg.rst:379 +msgid "" +":class:`str` and :class:`bytearray` objects no longer accepted as a sequence." +msgstr "" + +#: ../../c-api/arg.rst:382 +msgid "" +"Non-tuple sequences are deprecated if *items* contains format units which " +"store a borrowed buffer or a borrowed reference." +msgstr "" + +#: ../../c-api/arg.rst:386 +msgid "" +"A few other characters have a meaning in a format string. These may not " +"occur inside nested parentheses. They are:" +msgstr "" + +#: ../../c-api/arg.rst:389 +msgid "``|``" +msgstr "``|``" + +#: ../../c-api/arg.rst:390 +msgid "" +"Indicates that the remaining arguments in the Python argument list are " +"optional. The C variables corresponding to optional arguments should be " +"initialized to their default value --- when an optional argument is not " +"specified, :c:func:`PyArg_ParseTuple` does not touch the contents of the " +"corresponding C variable(s)." +msgstr "" + +#: ../../c-api/arg.rst:396 +msgid "``$``" +msgstr "``$``" + +#: ../../c-api/arg.rst:397 +msgid "" +":c:func:`PyArg_ParseTupleAndKeywords` only: Indicates that the remaining " +"arguments in the Python argument list are keyword-only. Currently, all " +"keyword-only arguments must also be optional arguments, so ``|`` must always " +"be specified before ``$`` in the format string." +msgstr "" + +#: ../../c-api/arg.rst:405 +msgid "``:``" +msgstr "``:``" + +#: ../../c-api/arg.rst:406 +msgid "" +"The list of format units ends here; the string after the colon is used as " +"the function name in error messages (the \"associated value\" of the " +"exception that :c:func:`PyArg_ParseTuple` raises)." +msgstr "" + +#: ../../c-api/arg.rst:410 +msgid "``;``" +msgstr "``;``" + +#: ../../c-api/arg.rst:411 +msgid "" +"The list of format units ends here; the string after the semicolon is used " +"as the error message *instead* of the default error message. ``:`` and ``;" +"`` mutually exclude each other." +msgstr "" + +#: ../../c-api/arg.rst:415 +msgid "" +"Note that any Python object references which are provided to the caller are " +"*borrowed* references; do not release them (i.e. do not decrement their " +"reference count)!" +msgstr "" + +#: ../../c-api/arg.rst:419 +msgid "" +"Additional arguments passed to these functions must be addresses of " +"variables whose type is determined by the format string; these are used to " +"store values from the input tuple. There are a few cases, as described in " +"the list of format units above, where these parameters are used as input " +"values; they should match what is specified for the corresponding format " +"unit in that case." +msgstr "" + +#: ../../c-api/arg.rst:425 +msgid "" +"For the conversion to succeed, the *arg* object must match the format and " +"the format must be exhausted. On success, the ``PyArg_Parse*`` functions " +"return true, otherwise they return false and raise an appropriate exception. " +"When the ``PyArg_Parse*`` functions fail due to conversion failure in one of " +"the format units, the variables at the addresses corresponding to that and " +"the following format units are left untouched." +msgstr "" + +#: ../../c-api/arg.rst:434 +msgid "API Functions" +msgstr "API 函式" + +#: ../../c-api/arg.rst:438 +msgid "" +"Parse the parameters of a function that takes only positional parameters " +"into local variables. Returns true on success; on failure, it returns false " +"and raises the appropriate exception." +msgstr "" + +#: ../../c-api/arg.rst:445 +msgid "" +"Identical to :c:func:`PyArg_ParseTuple`, except that it accepts a va_list " +"rather than a variable number of arguments." +msgstr "" + +#: ../../c-api/arg.rst:451 +msgid "" +"Parse the parameters of a function that takes both positional and keyword " +"parameters into local variables. The *keywords* argument is a ``NULL``-" +"terminated array of keyword parameter names specified as null-terminated " +"ASCII or UTF-8 encoded C strings. Empty names denote :ref:`positional-only " +"parameters `. Returns true on success; on " +"failure, it returns false and raises the appropriate exception." +msgstr "" + +#: ../../c-api/arg.rst:462 +msgid "" +"The *keywords* parameter declaration is :c:expr:`char * const *` in C and :c:" +"expr:`const char * const *` in C++. This can be overridden with the :c:macro:" +"`PY_CXX_CONST` macro." +msgstr "" + +#: ../../c-api/arg.rst:466 +msgid "" +"Added support for :ref:`positional-only parameters `." +msgstr "新增對\\ :ref:`僅限位置參數 `\\ 的支援。" + +#: ../../c-api/arg.rst:470 +msgid "" +"The *keywords* parameter has now type :c:expr:`char * const *` in C and :c:" +"expr:`const char * const *` in C++, instead of :c:expr:`char **`. Added " +"support for non-ASCII keyword parameter names." +msgstr "" + +#: ../../c-api/arg.rst:479 +msgid "" +"Identical to :c:func:`PyArg_ParseTupleAndKeywords`, except that it accepts a " +"va_list rather than a variable number of arguments." +msgstr "" + +#: ../../c-api/arg.rst:485 +msgid "" +"Ensure that the keys in the keywords argument dictionary are strings. This " +"is only needed if :c:func:`PyArg_ParseTupleAndKeywords` is not used, since " +"the latter already does this check." +msgstr "" + +#: ../../c-api/arg.rst:494 +msgid "" +"Parse the parameter of a function that takes a single positional parameter " +"into a local variable. Returns true on success; on failure, it returns " +"false and raises the appropriate exception." +msgstr "" + +#: ../../c-api/arg.rst:498 +msgid "Example::" +msgstr "舉例來說： ::" + +#: ../../c-api/arg.rst:500 +msgid "" +"// Function using METH_O calling convention\n" +"static PyObject*\n" +"my_function(PyObject *module, PyObject *arg)\n" +"{\n" +" int value;\n" +" if (!PyArg_Parse(arg, \"i:my_function\", &value)) {\n" +" return NULL;\n" +" }\n" +" // ... use value ...\n" +"}" +msgstr "" + +#: ../../c-api/arg.rst:514 +msgid "" +"A simpler form of parameter retrieval which does not use a format string to " +"specify the types of the arguments. Functions which use this method to " +"retrieve their parameters should be declared as :c:macro:`METH_VARARGS` in " +"function or method tables. The tuple containing the actual parameters " +"should be passed as *args*; it must actually be a tuple. The length of the " +"tuple must be at least *min* and no more than *max*; *min* and *max* may be " +"equal. Additional arguments must be passed to the function, each of which " +"should be a pointer to a :c:expr:`PyObject*` variable; these will be filled " +"in with the values from *args*; they will contain :term:`borrowed references " +"`. The variables which correspond to optional parameters " +"not given by *args* will not be filled in; these should be initialized by " +"the caller. This function returns true on success and false if *args* is not " +"a tuple or contains the wrong number of elements; an exception will be set " +"if there was a failure." +msgstr "" + +#: ../../c-api/arg.rst:529 +msgid "" +"This is an example of the use of this function, taken from the sources for " +"the :mod:`!_weakref` helper module for weak references::" +msgstr "" + +#: ../../c-api/arg.rst:532 +msgid "" +"static PyObject *\n" +"weakref_ref(PyObject *self, PyObject *args)\n" +"{\n" +" PyObject *object;\n" +" PyObject *callback = NULL;\n" +" PyObject *result = NULL;\n" +"\n" +" if (PyArg_UnpackTuple(args, \"ref\", 1, 2, &object, &callback)) {\n" +" result = PyWeakref_NewRef(object, callback);\n" +" }\n" +" return result;\n" +"}" +msgstr "" +"static PyObject *\n" +"weakref_ref(PyObject *self, PyObject *args)\n" +"{\n" +" PyObject *object;\n" +" PyObject *callback = NULL;\n" +" PyObject *result = NULL;\n" +"\n" +" if (PyArg_UnpackTuple(args, \"ref\", 1, 2, &object, &callback)) {\n" +" result = PyWeakref_NewRef(object, callback);\n" +" }\n" +" return result;\n" +"}" + +#: ../../c-api/arg.rst:545 +msgid "" +"The call to :c:func:`PyArg_UnpackTuple` in this example is entirely " +"equivalent to this call to :c:func:`PyArg_ParseTuple`::" +msgstr "" + +#: ../../c-api/arg.rst:548 +msgid "PyArg_ParseTuple(args, \"O|O:ref\", &object, &callback)" +msgstr "PyArg_ParseTuple(args, \"O|O:ref\", &object, &callback)" + +#: ../../c-api/arg.rst:552 +msgid "" +"The value to be inserted, if any, before :c:expr:`char * const *` in the " +"*keywords* parameter declaration of :c:func:`PyArg_ParseTupleAndKeywords` " +"and :c:func:`PyArg_VaParseTupleAndKeywords`. Default empty for C and " +"``const`` for C++ (:c:expr:`const char * const *`). To override, define it " +"to the desired value before including :file:`Python.h`." +msgstr "" + +#: ../../c-api/arg.rst:566 +msgid "Building values" +msgstr "建置數值" + +#: ../../c-api/arg.rst:570 +msgid "" +"Create a new value based on a format string similar to those accepted by the " +"``PyArg_Parse*`` family of functions and a sequence of values. Returns the " +"value or ``NULL`` in the case of an error; an exception will be raised if " +"``NULL`` is returned." +msgstr "" + +#: ../../c-api/arg.rst:575 +msgid "" +":c:func:`Py_BuildValue` does not always build a tuple. It builds a tuple " +"only if its format string contains two or more format units. If the format " +"string is empty, it returns ``None``; if it contains exactly one format " +"unit, it returns whatever object is described by that format unit. To force " +"it to return a tuple of size 0 or one, parenthesize the format string." +msgstr "" + +#: ../../c-api/arg.rst:581 +msgid "" +"When memory buffers are passed as parameters to supply data to build " +"objects, as for the ``s`` and ``s#`` formats, the required data is copied. " +"Buffers provided by the caller are never referenced by the objects created " +"by :c:func:`Py_BuildValue`. In other words, if your code invokes :c:func:" +"`malloc` and passes the allocated memory to :c:func:`Py_BuildValue`, your " +"code is responsible for calling :c:func:`free` for that memory once :c:func:" +"`Py_BuildValue` returns." +msgstr "" + +#: ../../c-api/arg.rst:589 +msgid "" +"In the following description, the quoted form is the format unit; the entry " +"in (round) parentheses is the Python object type that the format unit will " +"return; and the entry in [square] brackets is the type of the C value(s) to " +"be passed." +msgstr "" + +#: ../../c-api/arg.rst:593 +msgid "" +"The characters space, tab, colon and comma are ignored in format strings " +"(but not within format units such as ``s#``). This can be used to make long " +"format strings a tad more readable." +msgstr "" + +#: ../../c-api/arg.rst:597 +msgid "``s`` (:class:`str` or ``None``) [const char \\*]" +msgstr "``s`` (:class:`str` 或 ``None``) [const char \\*]" + +#: ../../c-api/arg.rst:598 +msgid "" +"Convert a null-terminated C string to a Python :class:`str` object using " +"``'utf-8'`` encoding. If the C string pointer is ``NULL``, ``None`` is used." +msgstr "" + +#: ../../c-api/arg.rst:601 +msgid "" +"``s#`` (:class:`str` or ``None``) [const char \\*, :c:type:`Py_ssize_t`]" +msgstr "" +"``s#`` (:class:`str` 或 ``None``) [const char \\*, :c:type:`Py_ssize_t`]" + +#: ../../c-api/arg.rst:602 +msgid "" +"Convert a C string and its length to a Python :class:`str` object using " +"``'utf-8'`` encoding. If the C string pointer is ``NULL``, the length is " +"ignored and ``None`` is returned." +msgstr "" + +#: ../../c-api/arg.rst:606 +msgid "``y`` (:class:`bytes`) [const char \\*]" +msgstr "``y`` (:class:`bytes`) [const char \\*]" + +#: ../../c-api/arg.rst:607 +msgid "" +"This converts a C string to a Python :class:`bytes` object. If the C string " +"pointer is ``NULL``, ``None`` is returned." +msgstr "" + +#: ../../c-api/arg.rst:610 +msgid "``y#`` (:class:`bytes`) [const char \\*, :c:type:`Py_ssize_t`]" +msgstr "``y#`` (:class:`bytes`) [const char \\*, :c:type:`Py_ssize_t`]" + +#: ../../c-api/arg.rst:611 +msgid "" +"This converts a C string and its lengths to a Python object. If the C " +"string pointer is ``NULL``, ``None`` is returned." +msgstr "" + +#: ../../c-api/arg.rst:615 ../../c-api/arg.rst:631 +msgid "Same as ``s``." +msgstr "和 ``s`` 相同。" + +#: ../../c-api/arg.rst:617 +msgid "" +"``z#`` (:class:`str` or ``None``) [const char \\*, :c:type:`Py_ssize_t`]" +msgstr "" +"``z#`` (:class:`str` 或 ``None``) [const char \\*, :c:type:`Py_ssize_t`]" + +#: ../../c-api/arg.rst:618 ../../c-api/arg.rst:634 +msgid "Same as ``s#``." +msgstr "和 ``s#`` 相同。" + +#: ../../c-api/arg.rst:620 +msgid "``u`` (:class:`str`) [const wchar_t \\*]" +msgstr "``u`` (:class:`str`) [const wchar_t \\*]" + +#: ../../c-api/arg.rst:621 +msgid "" +"Convert a null-terminated :c:type:`wchar_t` buffer of Unicode (UTF-16 or " +"UCS-4) data to a Python Unicode object. If the Unicode buffer pointer is " +"``NULL``, ``None`` is returned." +msgstr "" + +#: ../../c-api/arg.rst:625 +msgid "``u#`` (:class:`str`) [const wchar_t \\*, :c:type:`Py_ssize_t`]" +msgstr "``u#`` (:class:`str`) [const wchar_t \\*, :c:type:`Py_ssize_t`]" + +#: ../../c-api/arg.rst:626 +msgid "" +"Convert a Unicode (UTF-16 or UCS-4) data buffer and its length to a Python " +"Unicode object. If the Unicode buffer pointer is ``NULL``, the length is " +"ignored and ``None`` is returned." +msgstr "" + +#: ../../c-api/arg.rst:630 +msgid "``U`` (:class:`str` or ``None``) [const char \\*]" +msgstr "``U`` (:class:`str` 或 ``None``) [const char \\*]" + +#: ../../c-api/arg.rst:633 +msgid "" +"``U#`` (:class:`str` or ``None``) [const char \\*, :c:type:`Py_ssize_t`]" +msgstr "" +"``U#`` (:class:`str` 或 ``None``) [const char \\*, :c:type:`Py_ssize_t`]" + +#: ../../c-api/arg.rst:637 +msgid "Convert a plain C :c:expr:`int` to a Python integer object." +msgstr "將一個 C 的 :c:expr:`int` 轉換成 Python 整數物件。" + +#: ../../c-api/arg.rst:639 +msgid "``b`` (:class:`int`) [char]" +msgstr "``b`` (:class:`int`) [char]" + +#: ../../c-api/arg.rst:640 +msgid "Convert a plain C :c:expr:`char` to a Python integer object." +msgstr "將一個 C 的 :c:expr:`char` 轉換成 Python 整數物件。" + +#: ../../c-api/arg.rst:643 +msgid "Convert a plain C :c:expr:`short int` to a Python integer object." +msgstr "將一個 C 的 :c:expr:`short int` 轉換成 Python 整數物件。" + +#: ../../c-api/arg.rst:646 +msgid "Convert a C :c:expr:`long int` to a Python integer object." +msgstr "將一個 C 的 :c:expr:`long int` 轉換成 Python 整數物件。" + +#: ../../c-api/arg.rst:649 +msgid "Convert a C :c:expr:`unsigned char` to a Python integer object." +msgstr "將一個 C 的 :c:expr:`unsigned char` 轉換成 Python 整數物件。" + +#: ../../c-api/arg.rst:652 +msgid "Convert a C :c:expr:`unsigned short int` to a Python integer object." +msgstr "將一個 C 的 :c:expr:`unsigned short int` 轉換成 Python 整數物件。" + +#: ../../c-api/arg.rst:655 +msgid "Convert a C :c:expr:`unsigned int` to a Python integer object." +msgstr "將一個 C 的 :c:expr:`unsigned int` 轉換成 Python 整數物件。" + +#: ../../c-api/arg.rst:658 +msgid "Convert a C :c:expr:`unsigned long` to a Python integer object." +msgstr "將一個 C 的 :c:expr:`unsigned long` 轉換成 Python 整數物件。" + +#: ../../c-api/arg.rst:661 +msgid "Convert a C :c:expr:`long long` to a Python integer object." +msgstr "將一個 C 的 :c:expr:`long long` 轉換成 Python 整數物件。" + +#: ../../c-api/arg.rst:666 +msgid "Convert a C :c:expr:`unsigned long long` to a Python integer object." +msgstr "將一個 C 的 :c:expr:`unsigned long long` 轉換成 Python 整數物件。" + +#: ../../c-api/arg.rst:669 +msgid "Convert a C :c:type:`Py_ssize_t` to a Python integer." +msgstr "將一個 C 的 :c:type:`Py_ssize_t` 轉換成 Python 整數。" + +#: ../../c-api/arg.rst:672 +msgid "Convert a C :c:expr:`int` to a Python :class:`bool` object." +msgstr "將一個 C 的 :c:expr:`int` 轉換成 Python :class:`bool` 物件。" + +#: ../../c-api/arg.rst:674 +msgid "" +"Be aware that this format requires an ``int`` argument. Unlike most other " +"contexts in C, variadic arguments are not coerced to a suitable type " +"automatically. You can convert another type (for example, a pointer or a " +"float) to a suitable ``int`` value using ``(x) ? 1 : 0`` or ``!!x``." +msgstr "" + +#: ../../c-api/arg.rst:682 +msgid "``c`` (:class:`bytes` of length 1) [char]" +msgstr "``c`` (長度為 1 的 :class:`bytes`) [char]" + +#: ../../c-api/arg.rst:683 +msgid "" +"Convert a C :c:expr:`int` representing a byte to a Python :class:`bytes` " +"object of length 1." +msgstr "" +"將一個 C 中代表一個位元組的 :c:expr:`int` 轉換成 Python 中長度為一的 :class:" +"`bytes`。" + +#: ../../c-api/arg.rst:687 +msgid "" +"Convert a C :c:expr:`int` representing a character to Python :class:`str` " +"object of length 1." +msgstr "" +"將一個 C 中代表一個字元的 :c:expr:`int` 轉換成 Python 中長度為一的 :class:" +"`str`。" + +#: ../../c-api/arg.rst:691 +msgid "Convert a C :c:expr:`double` to a Python floating-point number." +msgstr "將一個 C 的 :c:expr:`double` 轉換成 Python 浮點數。" + +#: ../../c-api/arg.rst:694 +msgid "Convert a C :c:expr:`float` to a Python floating-point number." +msgstr "將一個 C 的 :c:expr:`float` 轉換成 Python 浮點數。" + +#: ../../c-api/arg.rst:696 +msgid "``D`` (:class:`complex`) [Py_complex \\*]" +msgstr "``D`` (:class:`complex`) [Py_complex \\*]" + +#: ../../c-api/arg.rst:697 +msgid "Convert a C :c:type:`Py_complex` structure to a Python complex number." +msgstr "將一個 C 的 :c:type:`Py_complex` 結構轉換成 Python 複數。" + +#: ../../c-api/arg.rst:700 +msgid "" +"Pass a Python object untouched but create a new :term:`strong reference` to " +"it (i.e. its reference count is incremented by one). If the object passed in " +"is a ``NULL`` pointer, it is assumed that this was caused because the call " +"producing the argument found an error and set an exception. Therefore, :c:" +"func:`Py_BuildValue` will return ``NULL`` but won't raise an exception. If " +"no exception has been raised yet, :exc:`SystemError` is set." +msgstr "" + +#: ../../c-api/arg.rst:709 +msgid "``S`` (object) [PyObject \\*]" +msgstr "``S`` (object) [PyObject \\*]" + +#: ../../c-api/arg.rst:710 +msgid "Same as ``O``." +msgstr "和 ``O`` 相同。" + +#: ../../c-api/arg.rst:712 +msgid "``N`` (object) [PyObject \\*]" +msgstr "``N`` (object) [PyObject \\*]" + +#: ../../c-api/arg.rst:713 +msgid "" +"Same as ``O``, except it doesn't create a new :term:`strong reference`. " +"Useful when the object is created by a call to an object constructor in the " +"argument list." +msgstr "" + +#: ../../c-api/arg.rst:717 +msgid "``O&`` (object) [*converter*, *anything*]" +msgstr "``O&`` (object) [*converter*, *anything*]" + +#: ../../c-api/arg.rst:718 +msgid "" +"Convert *anything* to a Python object through a *converter* function. The " +"function is called with *anything* (which should be compatible with :c:expr:" +"`void*`) as its argument and should return a \"new\" Python object, or " +"``NULL`` if an error occurred." +msgstr "" + +#: ../../c-api/arg.rst:723 +msgid "``(items)`` (:class:`tuple`) [*matching-items*]" +msgstr "``(items)`` (:class:`tuple`) [*matching-items*]" + +#: ../../c-api/arg.rst:724 +msgid "" +"Convert a sequence of C values to a Python tuple with the same number of " +"items." +msgstr "" + +#: ../../c-api/arg.rst:726 +msgid "``[items]`` (:class:`list`) [*matching-items*]" +msgstr "``[items]`` (:class:`list`) [*matching-items*]" + +#: ../../c-api/arg.rst:727 +msgid "" +"Convert a sequence of C values to a Python list with the same number of " +"items." +msgstr "" + +#: ../../c-api/arg.rst:729 +msgid "``{items}`` (:class:`dict`) [*matching-items*]" +msgstr "``{items}`` (:class:`dict`) [*matching-items*]" + +#: ../../c-api/arg.rst:730 +msgid "" +"Convert a sequence of C values to a Python dictionary. Each pair of " +"consecutive C values adds one item to the dictionary, serving as key and " +"value, respectively." +msgstr "" + +#: ../../c-api/arg.rst:734 +msgid "" +"If there is an error in the format string, the :exc:`SystemError` exception " +"is set and ``NULL`` returned." +msgstr "" + +#: ../../c-api/arg.rst:739 +msgid "" +"Identical to :c:func:`Py_BuildValue`, except that it accepts a va_list " +"rather than a variable number of arguments." +msgstr "" diff --git a/c-api/bool.po b/c-api/bool.po index 9b11893bcc..7b00ee4200 100644 --- a/c-api/bool.po +++ b/c-api/bool.po @@ -1,89 +1,89 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Ching-Lung Chuang, 2015 -# Matt Wang , 2021 -# -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-09-23 07:52+0800\n" -"PO-Revision-Date: 2021-12-09 20:47+0800\n" -"Last-Translator: Matt Wang \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" -"X-Generator: Poedit 3.0\n" - -#: ../../c-api/bool.rst:6 -msgid "Boolean Objects" -msgstr "Boolean（布林）物件" - -#: ../../c-api/bool.rst:8 -msgid "" -"Booleans in Python are implemented as a subclass of integers. There are " -"only two booleans, :c:data:`Py_False` and :c:data:`Py_True`. As such, the " -"normal creation and deletion functions don't apply to booleans. The " -"following macros are available, however." -msgstr "" -"Python 中的 boolean 是以整數子類別化來實現的。只有 :c:data:`Py_False` 和 :c:" -"data:`Py_True` 兩個 boolean。因此一般的建立和刪除函式並不適用於 boolean。但下" -"列巨集 (macro) 是可用的。" - -#: ../../c-api/bool.rst:16 -msgid "" -"This instance of :c:type:`PyTypeObject` represents the Python boolean type; " -"it is the same object as :class:`bool` in the Python layer." -msgstr "" -"此 :c:type:`PyTypeObject` 實例代表 Python 的布林型別；它與 Python 層級中的 " -":class:`bool` 是同一個物件。" - -#: ../../c-api/bool.rst:22 -msgid "" -"Return true if *o* is of type :c:data:`PyBool_Type`. This function always " -"succeeds." -msgstr "" -"如果 *o* 的型別為 :c:data:`PyBool_Type` 則回傳真值。此函式總是會成功執行。" - -#: ../../c-api/bool.rst:28 -msgid "" -"The Python ``False`` object. This object has no methods and is :term:" -"`immortal`." -msgstr "" -"Python 的 ``False`` 物件。此物件沒有任何方法且為\\ :term:`不滅的 (immortal) " -"`。" - -#: ../../c-api/bool.rst:31 -msgid ":c:data:`Py_False` is :term:`immortal`." -msgstr ":c:data:`Py_False` 為\\ :term:`不滅的 `。" - -#: ../../c-api/bool.rst:37 -msgid "" -"The Python ``True`` object. This object has no methods and is :term:" -"`immortal`." -msgstr "" -"Python 的 ``True`` 物件。此物件沒有任何方法且為\\ :term:`不滅的 `。" - -#: ../../c-api/bool.rst:40 -msgid ":c:data:`Py_True` is :term:`immortal`." -msgstr ":c:data:`Py_True` 為\\ :term:`不滅的 `。" - -#: ../../c-api/bool.rst:46 -msgid "Return :c:data:`Py_False` from a function." -msgstr "從函式回傳 :c:data:`Py_False`。" - -#: ../../c-api/bool.rst:51 -msgid "Return :c:data:`Py_True` from a function." -msgstr "從函式回傳 :c:data:`Py_True`。" - -#: ../../c-api/bool.rst:56 -msgid "" -"Return :c:data:`Py_True` or :c:data:`Py_False`, depending on the truth value " -"of *v*." -msgstr "根據 *v* 的實際值來回傳 :c:data:`Py_True` 或者 :c:data:`Py_False`。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Ching-Lung Chuang, 2015 +# Matt Wang , 2021 +# +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-09-23 07:52+0800\n" +"PO-Revision-Date: 2021-12-09 20:47+0800\n" +"Last-Translator: Matt Wang \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" +"X-Generator: Poedit 3.0\n" + +#: ../../c-api/bool.rst:6 +msgid "Boolean Objects" +msgstr "Boolean（布林）物件" + +#: ../../c-api/bool.rst:8 +msgid "" +"Booleans in Python are implemented as a subclass of integers. There are " +"only two booleans, :c:data:`Py_False` and :c:data:`Py_True`. As such, the " +"normal creation and deletion functions don't apply to booleans. The " +"following macros are available, however." +msgstr "" +"Python 中的 boolean 是以整數子類別化來實現的。只有 :c:data:`Py_False` 和 :c:" +"data:`Py_True` 兩個 boolean。因此一般的建立和刪除函式並不適用於 boolean。但下" +"列巨集 (macro) 是可用的。" + +#: ../../c-api/bool.rst:16 +msgid "" +"This instance of :c:type:`PyTypeObject` represents the Python boolean type; " +"it is the same object as :class:`bool` in the Python layer." +msgstr "" +"此 :c:type:`PyTypeObject` 實例代表 Python 的布林型別；它與 Python 層級中的 " +":class:`bool` 是同一個物件。" + +#: ../../c-api/bool.rst:22 +msgid "" +"Return true if *o* is of type :c:data:`PyBool_Type`. This function always " +"succeeds." +msgstr "" +"如果 *o* 的型別為 :c:data:`PyBool_Type` 則回傳真值。此函式總是會成功執行。" + +#: ../../c-api/bool.rst:28 +msgid "" +"The Python ``False`` object. This object has no methods and is :term:" +"`immortal`." +msgstr "" +"Python 的 ``False`` 物件。此物件沒有任何方法且為\\ :term:`不滅的 (immortal) " +"`。" + +#: ../../c-api/bool.rst:31 +msgid ":c:data:`Py_False` is :term:`immortal`." +msgstr ":c:data:`Py_False` 為\\ :term:`不滅的 `。" + +#: ../../c-api/bool.rst:37 +msgid "" +"The Python ``True`` object. This object has no methods and is :term:" +"`immortal`." +msgstr "" +"Python 的 ``True`` 物件。此物件沒有任何方法且為\\ :term:`不滅的 `。" + +#: ../../c-api/bool.rst:40 +msgid ":c:data:`Py_True` is :term:`immortal`." +msgstr ":c:data:`Py_True` 為\\ :term:`不滅的 `。" + +#: ../../c-api/bool.rst:46 +msgid "Return :c:data:`Py_False` from a function." +msgstr "從函式回傳 :c:data:`Py_False`。" + +#: ../../c-api/bool.rst:51 +msgid "Return :c:data:`Py_True` from a function." +msgstr "從函式回傳 :c:data:`Py_True`。" + +#: ../../c-api/bool.rst:56 +msgid "" +"Return :c:data:`Py_True` or :c:data:`Py_False`, depending on the truth value " +"of *v*." +msgstr "根據 *v* 的實際值來回傳 :c:data:`Py_True` 或者 :c:data:`Py_False`。" diff --git a/c-api/buffer.po b/c-api/buffer.po index 4bf453e92e..525c00bcaa 100644 --- a/c-api/buffer.po +++ b/c-api/buffer.po @@ -1,806 +1,806 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-09 00:17+0000\n" -"PO-Revision-Date: 2018-05-23 14:30+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" - -#: ../../c-api/buffer.rst:11 -msgid "Buffer Protocol" -msgstr "緩衝協定 (Buffer Protocol)" - -#: ../../c-api/buffer.rst:18 -msgid "" -"Certain objects available in Python wrap access to an underlying memory " -"array or *buffer*. Such objects include the built-in :class:`bytes` and :" -"class:`bytearray`, and some extension types like :class:`array.array`. Third-" -"party libraries may define their own types for special purposes, such as " -"image processing or numeric analysis." -msgstr "" - -#: ../../c-api/buffer.rst:24 -msgid "" -"While each of these types have their own semantics, they share the common " -"characteristic of being backed by a possibly large memory buffer. It is " -"then desirable, in some situations, to access that buffer directly and " -"without intermediate copying." -msgstr "" - -#: ../../c-api/buffer.rst:29 -msgid "" -"Python provides such a facility at the C and Python level in the form of " -"the :ref:`buffer protocol `. This protocol has two sides:" -msgstr "" - -#: ../../c-api/buffer.rst:34 -msgid "" -"on the producer side, a type can export a \"buffer interface\" which allows " -"objects of that type to expose information about their underlying buffer. " -"This interface is described in the section :ref:`buffer-structs`; for Python " -"see :ref:`python-buffer-protocol`." -msgstr "" - -#: ../../c-api/buffer.rst:39 -msgid "" -"on the consumer side, several means are available to obtain a pointer to the " -"raw underlying data of an object (for example a method parameter). For " -"Python see :class:`memoryview`." -msgstr "" - -#: ../../c-api/buffer.rst:43 -msgid "" -"Simple objects such as :class:`bytes` and :class:`bytearray` expose their " -"underlying buffer in byte-oriented form. Other forms are possible; for " -"example, the elements exposed by an :class:`array.array` can be multi-byte " -"values." -msgstr "" - -#: ../../c-api/buffer.rst:47 -msgid "" -"An example consumer of the buffer interface is the :meth:`~io.BufferedIOBase." -"write` method of file objects: any object that can export a series of bytes " -"through the buffer interface can be written to a file. While :meth:`!write` " -"only needs read-only access to the internal contents of the object passed to " -"it, other methods such as :meth:`~io.BufferedIOBase.readinto` need write " -"access to the contents of their argument. The buffer interface allows " -"objects to selectively allow or reject exporting of read-write and read-only " -"buffers." -msgstr "" - -#: ../../c-api/buffer.rst:55 -msgid "" -"There are two ways for a consumer of the buffer interface to acquire a " -"buffer over a target object:" -msgstr "" - -#: ../../c-api/buffer.rst:58 -msgid "call :c:func:`PyObject_GetBuffer` with the right parameters;" -msgstr "以適當的參數呼叫 :c:func:`PyObject_GetBuffer`；" - -#: ../../c-api/buffer.rst:60 -msgid "" -"call :c:func:`PyArg_ParseTuple` (or one of its siblings) with one of the " -"``y*``, ``w*`` or ``s*`` :ref:`format codes `." -msgstr "" - -#: ../../c-api/buffer.rst:63 -msgid "" -"In both cases, :c:func:`PyBuffer_Release` must be called when the buffer " -"isn't needed anymore. Failure to do so could lead to various issues such as " -"resource leaks." -msgstr "" - -#: ../../c-api/buffer.rst:69 -msgid "" -"The buffer protocol is now accessible in Python, see :ref:`python-buffer-" -"protocol` and :class:`memoryview`." -msgstr "" - -#: ../../c-api/buffer.rst:75 -msgid "Buffer structure" -msgstr "緩衝區結構" - -#: ../../c-api/buffer.rst:77 -msgid "" -"Buffer structures (or simply \"buffers\") are useful as a way to expose the " -"binary data from another object to the Python programmer. They can also be " -"used as a zero-copy slicing mechanism. Using their ability to reference a " -"block of memory, it is possible to expose any data to the Python programmer " -"quite easily. The memory could be a large, constant array in a C extension, " -"it could be a raw block of memory for manipulation before passing to an " -"operating system library, or it could be used to pass around structured data " -"in its native, in-memory format." -msgstr "" - -#: ../../c-api/buffer.rst:86 -msgid "" -"Contrary to most data types exposed by the Python interpreter, buffers are " -"not :c:type:`PyObject` pointers but rather simple C structures. This allows " -"them to be created and copied very simply. When a generic wrapper around a " -"buffer is needed, a :ref:`memoryview ` object can be " -"created." -msgstr "" - -#: ../../c-api/buffer.rst:92 -msgid "" -"For short instructions how to write an exporting object, see :ref:`Buffer " -"Object Structures `. For obtaining a buffer, see :c:func:" -"`PyObject_GetBuffer`." -msgstr "" - -#: ../../c-api/buffer.rst:100 -msgid "" -"A pointer to the start of the logical structure described by the buffer " -"fields. This can be any location within the underlying physical memory block " -"of the exporter. For example, with negative :c:member:`~Py_buffer.strides` " -"the value may point to the end of the memory block." -msgstr "" - -#: ../../c-api/buffer.rst:105 -msgid "" -"For :term:`contiguous` arrays, the value points to the beginning of the " -"memory block." -msgstr "" - -#: ../../c-api/buffer.rst:110 -msgid "" -"A new reference to the exporting object. The reference is owned by the " -"consumer and automatically released (i.e. reference count decremented) and " -"set to ``NULL`` by :c:func:`PyBuffer_Release`. The field is the equivalent " -"of the return value of any standard C-API function." -msgstr "" - -#: ../../c-api/buffer.rst:117 -msgid "" -"As a special case, for *temporary* buffers that are wrapped by :c:func:" -"`PyMemoryView_FromBuffer` or :c:func:`PyBuffer_FillInfo` this field is " -"``NULL``. In general, exporting objects MUST NOT use this scheme." -msgstr "" - -#: ../../c-api/buffer.rst:124 -msgid "" -"``product(shape) * itemsize``. For contiguous arrays, this is the length of " -"the underlying memory block. For non-contiguous arrays, it is the length " -"that the logical structure would have if it were copied to a contiguous " -"representation." -msgstr "" - -#: ../../c-api/buffer.rst:129 -msgid "" -"Accessing ``((char *)buf)[0] up to ((char *)buf)[len-1]`` is only valid if " -"the buffer has been obtained by a request that guarantees contiguity. In " -"most cases such a request will be :c:macro:`PyBUF_SIMPLE` or :c:macro:" -"`PyBUF_WRITABLE`." -msgstr "" - -#: ../../c-api/buffer.rst:135 -msgid "" -"An indicator of whether the buffer is read-only. This field is controlled by " -"the :c:macro:`PyBUF_WRITABLE` flag." -msgstr "" - -#: ../../c-api/buffer.rst:140 -msgid "" -"Item size in bytes of a single element. Same as the value of :func:`struct." -"calcsize` called on non-``NULL`` :c:member:`~Py_buffer.format` values." -msgstr "" - -#: ../../c-api/buffer.rst:143 -msgid "" -"Important exception: If a consumer requests a buffer without the :c:macro:" -"`PyBUF_FORMAT` flag, :c:member:`~Py_buffer.format` will be set to " -"``NULL``, but :c:member:`~Py_buffer.itemsize` still has the value for the " -"original format." -msgstr "" - -#: ../../c-api/buffer.rst:148 -msgid "" -"If :c:member:`~Py_buffer.shape` is present, the equality ``product(shape) * " -"itemsize == len`` still holds and the consumer can use :c:member:`~Py_buffer." -"itemsize` to navigate the buffer." -msgstr "" - -#: ../../c-api/buffer.rst:152 -msgid "" -"If :c:member:`~Py_buffer.shape` is ``NULL`` as a result of a :c:macro:" -"`PyBUF_SIMPLE` or a :c:macro:`PyBUF_WRITABLE` request, the consumer must " -"disregard :c:member:`~Py_buffer.itemsize` and assume ``itemsize == 1``." -msgstr "" - -#: ../../c-api/buffer.rst:158 -msgid "" -"A *NULL* terminated string in :mod:`struct` module style syntax describing " -"the contents of a single item. If this is ``NULL``, ``\"B\"`` (unsigned " -"bytes) is assumed." -msgstr "" - -#: ../../c-api/buffer.rst:162 -msgid "This field is controlled by the :c:macro:`PyBUF_FORMAT` flag." -msgstr "此欄位受 :c:macro:`PyBUF_FORMAT` 旗標控制。" - -#: ../../c-api/buffer.rst:166 -msgid "" -"The number of dimensions the memory represents as an n-dimensional array. If " -"it is ``0``, :c:member:`~Py_buffer.buf` points to a single item representing " -"a scalar. In this case, :c:member:`~Py_buffer.shape`, :c:member:`~Py_buffer." -"strides` and :c:member:`~Py_buffer.suboffsets` MUST be ``NULL``. The maximum " -"number of dimensions is given by :c:macro:`PyBUF_MAX_NDIM`." -msgstr "" - -#: ../../c-api/buffer.rst:174 -msgid "" -"An array of :c:type:`Py_ssize_t` of length :c:member:`~Py_buffer.ndim` " -"indicating the shape of the memory as an n-dimensional array. Note that " -"``shape[0] * ... * shape[ndim-1] * itemsize`` MUST be equal to :c:member:" -"`~Py_buffer.len`." -msgstr "" - -#: ../../c-api/buffer.rst:179 -msgid "" -"Shape values are restricted to ``shape[n] >= 0``. The case ``shape[n] == 0`` " -"requires special attention. See `complex arrays`_ for further information." -msgstr "" - -#: ../../c-api/buffer.rst:183 -msgid "The shape array is read-only for the consumer." -msgstr "" - -#: ../../c-api/buffer.rst:187 -msgid "" -"An array of :c:type:`Py_ssize_t` of length :c:member:`~Py_buffer.ndim` " -"giving the number of bytes to skip to get to a new element in each dimension." -msgstr "" - -#: ../../c-api/buffer.rst:191 -msgid "" -"Stride values can be any integer. For regular arrays, strides are usually " -"positive, but a consumer MUST be able to handle the case ``strides[n] <= " -"0``. See `complex arrays`_ for further information." -msgstr "" - -#: ../../c-api/buffer.rst:195 -msgid "The strides array is read-only for the consumer." -msgstr "" - -#: ../../c-api/buffer.rst:199 -msgid "" -"An array of :c:type:`Py_ssize_t` of length :c:member:`~Py_buffer.ndim`. If " -"``suboffsets[n] >= 0``, the values stored along the nth dimension are " -"pointers and the suboffset value dictates how many bytes to add to each " -"pointer after de-referencing. A suboffset value that is negative indicates " -"that no de-referencing should occur (striding in a contiguous memory block)." -msgstr "" - -#: ../../c-api/buffer.rst:206 -msgid "" -"If all suboffsets are negative (i.e. no de-referencing is needed), then this " -"field must be ``NULL`` (the default value)." -msgstr "" - -#: ../../c-api/buffer.rst:209 -msgid "" -"This type of array representation is used by the Python Imaging Library " -"(PIL). See `complex arrays`_ for further information how to access elements " -"of such an array." -msgstr "" - -#: ../../c-api/buffer.rst:213 -msgid "The suboffsets array is read-only for the consumer." -msgstr "" - -#: ../../c-api/buffer.rst:217 -msgid "" -"This is for use internally by the exporting object. For example, this might " -"be re-cast as an integer by the exporter and used to store flags about " -"whether or not the shape, strides, and suboffsets arrays must be freed when " -"the buffer is released. The consumer MUST NOT alter this value." -msgstr "" - -#: ../../c-api/buffer.rst:224 -msgid "Constants:" -msgstr "常數：" - -#: ../../c-api/buffer.rst:228 -msgid "" -"The maximum number of dimensions the memory represents. Exporters MUST " -"respect this limit, consumers of multi-dimensional buffers SHOULD be able to " -"handle up to :c:macro:`!PyBUF_MAX_NDIM` dimensions. Currently set to 64." -msgstr "" - -#: ../../c-api/buffer.rst:237 -msgid "Buffer request types" -msgstr "" - -#: ../../c-api/buffer.rst:239 -msgid "" -"Buffers are usually obtained by sending a buffer request to an exporting " -"object via :c:func:`PyObject_GetBuffer`. Since the complexity of the logical " -"structure of the memory can vary drastically, the consumer uses the *flags* " -"argument to specify the exact buffer type it can handle." -msgstr "" - -#: ../../c-api/buffer.rst:244 -msgid "" -"All :c:type:`Py_buffer` fields are unambiguously defined by the request type." -msgstr "" - -#: ../../c-api/buffer.rst:248 -msgid "request-independent fields" -msgstr "" - -#: ../../c-api/buffer.rst:249 -msgid "" -"The following fields are not influenced by *flags* and must always be filled " -"in with the correct values: :c:member:`~Py_buffer.obj`, :c:member:" -"`~Py_buffer.buf`, :c:member:`~Py_buffer.len`, :c:member:`~Py_buffer." -"itemsize`, :c:member:`~Py_buffer.ndim`." -msgstr "" - -#: ../../c-api/buffer.rst:254 -msgid "readonly, format" -msgstr "" - -#: ../../c-api/buffer.rst:258 -msgid "" -"Controls the :c:member:`~Py_buffer.readonly` field. If set, the exporter " -"MUST provide a writable buffer or else report failure. Otherwise, the " -"exporter MAY provide either a read-only or writable buffer, but the choice " -"MUST be consistent for all consumers. For example, :c:expr:`PyBUF_SIMPLE | " -"PyBUF_WRITABLE` can be used to request a simple writable buffer." -msgstr "" - -#: ../../c-api/buffer.rst:266 -msgid "This is a :term:`soft deprecated` alias to :c:macro:`PyBUF_WRITABLE`." -msgstr "這是 :c:macro:`PyBUF_WRITABLE` 的\\ :term:`軟性棄用 `\\ 別名。" - -#: ../../c-api/buffer.rst:270 -msgid "" -"Controls the :c:member:`~Py_buffer.format` field. If set, this field MUST be " -"filled in correctly. Otherwise, this field MUST be ``NULL``." -msgstr "" - -#: ../../c-api/buffer.rst:274 -msgid "" -":c:macro:`PyBUF_WRITABLE` can be \\|'d to any of the flags in the next " -"section. Since :c:macro:`PyBUF_SIMPLE` is defined as 0, :c:macro:" -"`PyBUF_WRITABLE` can be used as a stand-alone flag to request a simple " -"writable buffer." -msgstr "" - -#: ../../c-api/buffer.rst:278 -msgid "" -":c:macro:`PyBUF_FORMAT` must be \\|'d to any of the flags except :c:macro:" -"`PyBUF_SIMPLE`, because the latter already implies format ``B`` (unsigned " -"bytes). :c:macro:`!PyBUF_FORMAT` cannot be used on its own." -msgstr "" - -#: ../../c-api/buffer.rst:284 -msgid "shape, strides, suboffsets" -msgstr "" - -#: ../../c-api/buffer.rst:286 -msgid "" -"The flags that control the logical structure of the memory are listed in " -"decreasing order of complexity. Note that each flag contains all bits of the " -"flags below it." -msgstr "" - -#: ../../c-api/buffer.rst:293 ../../c-api/buffer.rst:317 -#: ../../c-api/buffer.rst:342 -msgid "Request" -msgstr "" - -#: ../../c-api/buffer.rst:293 ../../c-api/buffer.rst:317 -#: ../../c-api/buffer.rst:342 -msgid "shape" -msgstr "" - -#: ../../c-api/buffer.rst:293 ../../c-api/buffer.rst:317 -#: ../../c-api/buffer.rst:342 -msgid "strides" -msgstr "" - -#: ../../c-api/buffer.rst:293 ../../c-api/buffer.rst:317 -#: ../../c-api/buffer.rst:342 -msgid "suboffsets" -msgstr "" - -#: ../../c-api/buffer.rst:295 ../../c-api/buffer.rst:297 -#: ../../c-api/buffer.rst:299 ../../c-api/buffer.rst:319 -#: ../../c-api/buffer.rst:321 ../../c-api/buffer.rst:323 -#: ../../c-api/buffer.rst:325 ../../c-api/buffer.rst:344 -#: ../../c-api/buffer.rst:346 ../../c-api/buffer.rst:348 -#: ../../c-api/buffer.rst:350 ../../c-api/buffer.rst:352 -#: ../../c-api/buffer.rst:354 ../../c-api/buffer.rst:356 -#: ../../c-api/buffer.rst:358 -msgid "yes" -msgstr "" - -#: ../../c-api/buffer.rst:295 ../../c-api/buffer.rst:344 -#: ../../c-api/buffer.rst:346 -msgid "if needed" -msgstr "" - -#: ../../c-api/buffer.rst:297 ../../c-api/buffer.rst:299 -#: ../../c-api/buffer.rst:301 ../../c-api/buffer.rst:319 -#: ../../c-api/buffer.rst:321 ../../c-api/buffer.rst:323 -#: ../../c-api/buffer.rst:325 ../../c-api/buffer.rst:348 -#: ../../c-api/buffer.rst:350 ../../c-api/buffer.rst:352 -#: ../../c-api/buffer.rst:354 ../../c-api/buffer.rst:356 -#: ../../c-api/buffer.rst:358 -msgid "NULL" -msgstr "NULL" - -#: ../../c-api/buffer.rst:308 -msgid "contiguity requests" -msgstr "" - -#: ../../c-api/buffer.rst:310 -msgid "" -"C or Fortran :term:`contiguity ` can be explicitly requested, " -"with and without stride information. Without stride information, the buffer " -"must be C-contiguous." -msgstr "" - -#: ../../c-api/buffer.rst:317 ../../c-api/buffer.rst:342 -msgid "contig" -msgstr "" - -#: ../../c-api/buffer.rst:319 ../../c-api/buffer.rst:325 -#: ../../c-api/buffer.rst:356 ../../c-api/buffer.rst:358 -msgid "C" -msgstr "C" - -#: ../../c-api/buffer.rst:321 -msgid "F" -msgstr "F" - -#: ../../c-api/buffer.rst:323 -msgid "C or F" -msgstr "C 或 F" - -#: ../../c-api/buffer.rst:325 -msgid ":c:macro:`PyBUF_ND`" -msgstr ":c:macro:`PyBUF_ND`" - -#: ../../c-api/buffer.rst:330 -msgid "compound requests" -msgstr "" - -#: ../../c-api/buffer.rst:332 -msgid "" -"All possible requests are fully defined by some combination of the flags in " -"the previous section. For convenience, the buffer protocol provides " -"frequently used combinations as single flags." -msgstr "" - -#: ../../c-api/buffer.rst:336 -msgid "" -"In the following table *U* stands for undefined contiguity. The consumer " -"would have to call :c:func:`PyBuffer_IsContiguous` to determine contiguity." -msgstr "" - -#: ../../c-api/buffer.rst:342 -msgid "readonly" -msgstr "" - -#: ../../c-api/buffer.rst:342 -msgid "format" -msgstr "" - -#: ../../c-api/buffer.rst:344 ../../c-api/buffer.rst:346 -#: ../../c-api/buffer.rst:348 ../../c-api/buffer.rst:350 -#: ../../c-api/buffer.rst:352 ../../c-api/buffer.rst:354 -msgid "U" -msgstr "U" - -#: ../../c-api/buffer.rst:344 ../../c-api/buffer.rst:348 -#: ../../c-api/buffer.rst:352 ../../c-api/buffer.rst:356 -msgid "0" -msgstr "0" - -#: ../../c-api/buffer.rst:346 ../../c-api/buffer.rst:350 -#: ../../c-api/buffer.rst:354 ../../c-api/buffer.rst:358 -msgid "1 or 0" -msgstr "1 或 0" - -#: ../../c-api/buffer.rst:363 -msgid "Complex arrays" -msgstr "" - -#: ../../c-api/buffer.rst:366 -msgid "NumPy-style: shape and strides" -msgstr "NumPy 風格：形狀與步幅" - -#: ../../c-api/buffer.rst:368 -msgid "" -"The logical structure of NumPy-style arrays is defined by :c:member:" -"`~Py_buffer.itemsize`, :c:member:`~Py_buffer.ndim`, :c:member:`~Py_buffer." -"shape` and :c:member:`~Py_buffer.strides`." -msgstr "" - -#: ../../c-api/buffer.rst:371 -msgid "" -"If ``ndim == 0``, the memory location pointed to by :c:member:`~Py_buffer." -"buf` is interpreted as a scalar of size :c:member:`~Py_buffer.itemsize`. In " -"that case, both :c:member:`~Py_buffer.shape` and :c:member:`~Py_buffer." -"strides` are ``NULL``." -msgstr "" - -#: ../../c-api/buffer.rst:375 -msgid "" -"If :c:member:`~Py_buffer.strides` is ``NULL``, the array is interpreted as a " -"standard n-dimensional C-array. Otherwise, the consumer must access an n-" -"dimensional array as follows:" -msgstr "" - -#: ../../c-api/buffer.rst:379 -msgid "" -"ptr = (char *)buf + indices[0] * strides[0] + ... + indices[n-1] * " -"strides[n-1];\n" -"item = *((typeof(item) *)ptr);" -msgstr "" -"ptr = (char *)buf + indices[0] * strides[0] + ... + indices[n-1] * " -"strides[n-1];\n" -"item = *((typeof(item) *)ptr);" - -#: ../../c-api/buffer.rst:385 -msgid "" -"As noted above, :c:member:`~Py_buffer.buf` can point to any location within " -"the actual memory block. An exporter can check the validity of a buffer with " -"this function:" -msgstr "" - -#: ../../c-api/buffer.rst:389 -msgid "" -"def verify_structure(memlen, itemsize, ndim, shape, strides, offset):\n" -" \"\"\"Verify that the parameters represent a valid array within\n" -" the bounds of the allocated memory:\n" -" char *mem: start of the physical memory block\n" -" memlen: length of the physical memory block\n" -" offset: (char *)buf - mem\n" -" \"\"\"\n" -" if offset % itemsize:\n" -" return False\n" -" if offset < 0 or offset+itemsize > memlen:\n" -" return False\n" -" if any(v % itemsize for v in strides):\n" -" return False\n" -"\n" -" if ndim <= 0:\n" -" return ndim == 0 and not shape and not strides\n" -" if 0 in shape:\n" -" return True\n" -"\n" -" imin = sum(strides[j]*(shape[j]-1) for j in range(ndim)\n" -" if strides[j] <= 0)\n" -" imax = sum(strides[j]*(shape[j]-1) for j in range(ndim)\n" -" if strides[j] > 0)\n" -"\n" -" return 0 <= offset+imin and offset+imax+itemsize <= memlen" -msgstr "" - -#: ../../c-api/buffer.rst:419 -msgid "PIL-style: shape, strides and suboffsets" -msgstr "" - -#: ../../c-api/buffer.rst:421 -msgid "" -"In addition to the regular items, PIL-style arrays can contain pointers that " -"must be followed in order to get to the next element in a dimension. For " -"example, the regular three-dimensional C-array ``char v[2][2][3]`` can also " -"be viewed as an array of 2 pointers to 2 two-dimensional arrays: ``char " -"(*v[2])[2][3]``. In suboffsets representation, those two pointers can be " -"embedded at the start of :c:member:`~Py_buffer.buf`, pointing to two ``char " -"x[2][3]`` arrays that can be located anywhere in memory." -msgstr "" - -#: ../../c-api/buffer.rst:430 -msgid "" -"Here is a function that returns a pointer to the element in an N-D array " -"pointed to by an N-dimensional index when there are both non-``NULL`` " -"strides and suboffsets::" -msgstr "" - -#: ../../c-api/buffer.rst:434 -msgid "" -"void *get_item_pointer(int ndim, void *buf, Py_ssize_t *strides,\n" -" Py_ssize_t *suboffsets, Py_ssize_t *indices) {\n" -" char *pointer = (char*)buf;\n" -" int i;\n" -" for (i = 0; i < ndim; i++) {\n" -" pointer += strides[i] * indices[i];\n" -" if (suboffsets[i] >=0 ) {\n" -" pointer = *((char**)pointer) + suboffsets[i];\n" -" }\n" -" }\n" -" return (void*)pointer;\n" -"}" -msgstr "" -"void *get_item_pointer(int ndim, void *buf, Py_ssize_t *strides,\n" -" Py_ssize_t *suboffsets, Py_ssize_t *indices) {\n" -" char *pointer = (char*)buf;\n" -" int i;\n" -" for (i = 0; i < ndim; i++) {\n" -" pointer += strides[i] * indices[i];\n" -" if (suboffsets[i] >=0 ) {\n" -" pointer = *((char**)pointer) + suboffsets[i];\n" -" }\n" -" }\n" -" return (void*)pointer;\n" -"}" - -#: ../../c-api/buffer.rst:449 -msgid "Buffer-related functions" -msgstr "與緩衝相關的函式" - -#: ../../c-api/buffer.rst:453 -msgid "" -"Return ``1`` if *obj* supports the buffer interface otherwise ``0``. When " -"``1`` is returned, it doesn't guarantee that :c:func:`PyObject_GetBuffer` " -"will succeed. This function always succeeds." -msgstr "" - -#: ../../c-api/buffer.rst:460 -msgid "" -"Send a request to *exporter* to fill in *view* as specified by *flags*. If " -"the exporter cannot provide a buffer of the exact type, it MUST raise :exc:" -"`BufferError`, set ``view->obj`` to ``NULL`` and return ``-1``." -msgstr "" - -#: ../../c-api/buffer.rst:465 -msgid "" -"On success, fill in *view*, set ``view->obj`` to a new reference to " -"*exporter* and return 0. In the case of chained buffer providers that " -"redirect requests to a single object, ``view->obj`` MAY refer to this object " -"instead of *exporter* (See :ref:`Buffer Object Structures `)." -msgstr "" - -#: ../../c-api/buffer.rst:470 -msgid "" -"Successful calls to :c:func:`PyObject_GetBuffer` must be paired with calls " -"to :c:func:`PyBuffer_Release`, similar to :c:func:`malloc` and :c:func:" -"`free`. Thus, after the consumer is done with the buffer, :c:func:" -"`PyBuffer_Release` must be called exactly once." -msgstr "" - -#: ../../c-api/buffer.rst:478 -msgid "" -"Release the buffer *view* and release the :term:`strong reference` (i.e. " -"decrement the reference count) to the view's supporting object, ``view-" -">obj``. This function MUST be called when the buffer is no longer being " -"used, otherwise reference leaks may occur." -msgstr "" - -#: ../../c-api/buffer.rst:483 -msgid "" -"It is an error to call this function on a buffer that was not obtained via :" -"c:func:`PyObject_GetBuffer`." -msgstr "" - -#: ../../c-api/buffer.rst:489 -msgid "" -"Return the implied :c:member:`~Py_buffer.itemsize` from :c:member:" -"`~Py_buffer.format`. On error, raise an exception and return -1." -msgstr "" - -#: ../../c-api/buffer.rst:497 -msgid "" -"Return ``1`` if the memory defined by the *view* is C-style (*order* is " -"``'C'``) or Fortran-style (*order* is ``'F'``) :term:`contiguous` or either " -"one (*order* is ``'A'``). Return ``0`` otherwise. This function always " -"succeeds." -msgstr "" - -#: ../../c-api/buffer.rst:504 -msgid "" -"Get the memory area pointed to by the *indices* inside the given *view*. " -"*indices* must point to an array of ``view->ndim`` indices." -msgstr "" - -#: ../../c-api/buffer.rst:510 -msgid "" -"Copy contiguous *len* bytes from *buf* to *view*. *fort* can be ``'C'`` or " -"``'F'`` (for C-style or Fortran-style ordering). ``0`` is returned on " -"success, ``-1`` on error." -msgstr "" - -#: ../../c-api/buffer.rst:517 -msgid "" -"Copy *len* bytes from *src* to its contiguous representation in *buf*. " -"*order* can be ``'C'`` or ``'F'`` or ``'A'`` (for C-style or Fortran-style " -"ordering or either one). ``0`` is returned on success, ``-1`` on error." -msgstr "" - -#: ../../c-api/buffer.rst:521 -msgid "This function fails if *len* != *src->len*." -msgstr "此函式在 *len* != *src->len* 時失敗。" - -#: ../../c-api/buffer.rst:526 -msgid "" -"Copy data from *src* to *dest* buffer. Can convert between C-style and or " -"Fortran-style buffers." -msgstr "" - -#: ../../c-api/buffer.rst:529 -msgid "``0`` is returned on success, ``-1`` on error." -msgstr "成功時回傳 ``0``，錯誤時回傳 ``-1``。" - -#: ../../c-api/buffer.rst:533 -msgid "" -"Fill the *strides* array with byte-strides of a :term:`contiguous` (C-style " -"if *order* is ``'C'`` or Fortran-style if *order* is ``'F'``) array of the " -"given shape with the given number of bytes per element." -msgstr "" - -#: ../../c-api/buffer.rst:540 -msgid "" -"Handle buffer requests for an exporter that wants to expose *buf* of size " -"*len* with writability set according to *readonly*. *buf* is interpreted as " -"a sequence of unsigned bytes." -msgstr "" - -#: ../../c-api/buffer.rst:544 -msgid "" -"The *flags* argument indicates the request type. This function always fills " -"in *view* as specified by flags, unless *buf* has been designated as read-" -"only and :c:macro:`PyBUF_WRITABLE` is set in *flags*." -msgstr "" - -#: ../../c-api/buffer.rst:548 -msgid "" -"On success, set ``view->obj`` to a new reference to *exporter* and return 0. " -"Otherwise, raise :exc:`BufferError`, set ``view->obj`` to ``NULL`` and " -"return ``-1``;" -msgstr "" - -#: ../../c-api/buffer.rst:552 -msgid "" -"If this function is used as part of a :ref:`getbufferproc `, " -"*exporter* MUST be set to the exporting object and *flags* must be passed " -"unmodified. Otherwise, *exporter* MUST be ``NULL``." -msgstr "" - -#: ../../c-api/buffer.rst:3 -msgid "buffer protocol" -msgstr "buffer protocol（緩衝協定）" - -#: ../../c-api/buffer.rst:3 -msgid "buffer interface" -msgstr "buffer interface（緩衝介面）" - -#: ../../c-api/buffer.rst:3 -msgid "(see buffer protocol)" -msgstr "(請見緩衝協定)" - -#: ../../c-api/buffer.rst:3 -msgid "buffer object" -msgstr "buffer object（緩衝物件）" - -#: ../../c-api/buffer.rst:32 -msgid "PyBufferProcs (C type)" -msgstr "PyBufferProcs（C 型別）" - -#: ../../c-api/buffer.rst:305 -msgid "contiguous" -msgstr "contiguous（連續的）" - -#: ../../c-api/buffer.rst:305 -msgid "C-contiguous" -msgstr "C-contiguous（C 連續的）" - -#: ../../c-api/buffer.rst:305 -msgid "Fortran contiguous" -msgstr "Fortran contiguous（Fortran 連續的）" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-09 00:17+0000\n" +"PO-Revision-Date: 2018-05-23 14:30+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" + +#: ../../c-api/buffer.rst:11 +msgid "Buffer Protocol" +msgstr "緩衝協定 (Buffer Protocol)" + +#: ../../c-api/buffer.rst:18 +msgid "" +"Certain objects available in Python wrap access to an underlying memory " +"array or *buffer*. Such objects include the built-in :class:`bytes` and :" +"class:`bytearray`, and some extension types like :class:`array.array`. Third-" +"party libraries may define their own types for special purposes, such as " +"image processing or numeric analysis." +msgstr "" + +#: ../../c-api/buffer.rst:24 +msgid "" +"While each of these types have their own semantics, they share the common " +"characteristic of being backed by a possibly large memory buffer. It is " +"then desirable, in some situations, to access that buffer directly and " +"without intermediate copying." +msgstr "" + +#: ../../c-api/buffer.rst:29 +msgid "" +"Python provides such a facility at the C and Python level in the form of " +"the :ref:`buffer protocol `. This protocol has two sides:" +msgstr "" + +#: ../../c-api/buffer.rst:34 +msgid "" +"on the producer side, a type can export a \"buffer interface\" which allows " +"objects of that type to expose information about their underlying buffer. " +"This interface is described in the section :ref:`buffer-structs`; for Python " +"see :ref:`python-buffer-protocol`." +msgstr "" + +#: ../../c-api/buffer.rst:39 +msgid "" +"on the consumer side, several means are available to obtain a pointer to the " +"raw underlying data of an object (for example a method parameter). For " +"Python see :class:`memoryview`." +msgstr "" + +#: ../../c-api/buffer.rst:43 +msgid "" +"Simple objects such as :class:`bytes` and :class:`bytearray` expose their " +"underlying buffer in byte-oriented form. Other forms are possible; for " +"example, the elements exposed by an :class:`array.array` can be multi-byte " +"values." +msgstr "" + +#: ../../c-api/buffer.rst:47 +msgid "" +"An example consumer of the buffer interface is the :meth:`~io.BufferedIOBase." +"write` method of file objects: any object that can export a series of bytes " +"through the buffer interface can be written to a file. While :meth:`!write` " +"only needs read-only access to the internal contents of the object passed to " +"it, other methods such as :meth:`~io.BufferedIOBase.readinto` need write " +"access to the contents of their argument. The buffer interface allows " +"objects to selectively allow or reject exporting of read-write and read-only " +"buffers." +msgstr "" + +#: ../../c-api/buffer.rst:55 +msgid "" +"There are two ways for a consumer of the buffer interface to acquire a " +"buffer over a target object:" +msgstr "" + +#: ../../c-api/buffer.rst:58 +msgid "call :c:func:`PyObject_GetBuffer` with the right parameters;" +msgstr "以適當的參數呼叫 :c:func:`PyObject_GetBuffer`；" + +#: ../../c-api/buffer.rst:60 +msgid "" +"call :c:func:`PyArg_ParseTuple` (or one of its siblings) with one of the " +"``y*``, ``w*`` or ``s*`` :ref:`format codes `." +msgstr "" + +#: ../../c-api/buffer.rst:63 +msgid "" +"In both cases, :c:func:`PyBuffer_Release` must be called when the buffer " +"isn't needed anymore. Failure to do so could lead to various issues such as " +"resource leaks." +msgstr "" + +#: ../../c-api/buffer.rst:69 +msgid "" +"The buffer protocol is now accessible in Python, see :ref:`python-buffer-" +"protocol` and :class:`memoryview`." +msgstr "" + +#: ../../c-api/buffer.rst:75 +msgid "Buffer structure" +msgstr "緩衝區結構" + +#: ../../c-api/buffer.rst:77 +msgid "" +"Buffer structures (or simply \"buffers\") are useful as a way to expose the " +"binary data from another object to the Python programmer. They can also be " +"used as a zero-copy slicing mechanism. Using their ability to reference a " +"block of memory, it is possible to expose any data to the Python programmer " +"quite easily. The memory could be a large, constant array in a C extension, " +"it could be a raw block of memory for manipulation before passing to an " +"operating system library, or it could be used to pass around structured data " +"in its native, in-memory format." +msgstr "" + +#: ../../c-api/buffer.rst:86 +msgid "" +"Contrary to most data types exposed by the Python interpreter, buffers are " +"not :c:type:`PyObject` pointers but rather simple C structures. This allows " +"them to be created and copied very simply. When a generic wrapper around a " +"buffer is needed, a :ref:`memoryview ` object can be " +"created." +msgstr "" + +#: ../../c-api/buffer.rst:92 +msgid "" +"For short instructions how to write an exporting object, see :ref:`Buffer " +"Object Structures `. For obtaining a buffer, see :c:func:" +"`PyObject_GetBuffer`." +msgstr "" + +#: ../../c-api/buffer.rst:100 +msgid "" +"A pointer to the start of the logical structure described by the buffer " +"fields. This can be any location within the underlying physical memory block " +"of the exporter. For example, with negative :c:member:`~Py_buffer.strides` " +"the value may point to the end of the memory block." +msgstr "" + +#: ../../c-api/buffer.rst:105 +msgid "" +"For :term:`contiguous` arrays, the value points to the beginning of the " +"memory block." +msgstr "" + +#: ../../c-api/buffer.rst:110 +msgid "" +"A new reference to the exporting object. The reference is owned by the " +"consumer and automatically released (i.e. reference count decremented) and " +"set to ``NULL`` by :c:func:`PyBuffer_Release`. The field is the equivalent " +"of the return value of any standard C-API function." +msgstr "" + +#: ../../c-api/buffer.rst:117 +msgid "" +"As a special case, for *temporary* buffers that are wrapped by :c:func:" +"`PyMemoryView_FromBuffer` or :c:func:`PyBuffer_FillInfo` this field is " +"``NULL``. In general, exporting objects MUST NOT use this scheme." +msgstr "" + +#: ../../c-api/buffer.rst:124 +msgid "" +"``product(shape) * itemsize``. For contiguous arrays, this is the length of " +"the underlying memory block. For non-contiguous arrays, it is the length " +"that the logical structure would have if it were copied to a contiguous " +"representation." +msgstr "" + +#: ../../c-api/buffer.rst:129 +msgid "" +"Accessing ``((char *)buf)[0] up to ((char *)buf)[len-1]`` is only valid if " +"the buffer has been obtained by a request that guarantees contiguity. In " +"most cases such a request will be :c:macro:`PyBUF_SIMPLE` or :c:macro:" +"`PyBUF_WRITABLE`." +msgstr "" + +#: ../../c-api/buffer.rst:135 +msgid "" +"An indicator of whether the buffer is read-only. This field is controlled by " +"the :c:macro:`PyBUF_WRITABLE` flag." +msgstr "" + +#: ../../c-api/buffer.rst:140 +msgid "" +"Item size in bytes of a single element. Same as the value of :func:`struct." +"calcsize` called on non-``NULL`` :c:member:`~Py_buffer.format` values." +msgstr "" + +#: ../../c-api/buffer.rst:143 +msgid "" +"Important exception: If a consumer requests a buffer without the :c:macro:" +"`PyBUF_FORMAT` flag, :c:member:`~Py_buffer.format` will be set to " +"``NULL``, but :c:member:`~Py_buffer.itemsize` still has the value for the " +"original format." +msgstr "" + +#: ../../c-api/buffer.rst:148 +msgid "" +"If :c:member:`~Py_buffer.shape` is present, the equality ``product(shape) * " +"itemsize == len`` still holds and the consumer can use :c:member:`~Py_buffer." +"itemsize` to navigate the buffer." +msgstr "" + +#: ../../c-api/buffer.rst:152 +msgid "" +"If :c:member:`~Py_buffer.shape` is ``NULL`` as a result of a :c:macro:" +"`PyBUF_SIMPLE` or a :c:macro:`PyBUF_WRITABLE` request, the consumer must " +"disregard :c:member:`~Py_buffer.itemsize` and assume ``itemsize == 1``." +msgstr "" + +#: ../../c-api/buffer.rst:158 +msgid "" +"A *NULL* terminated string in :mod:`struct` module style syntax describing " +"the contents of a single item. If this is ``NULL``, ``\"B\"`` (unsigned " +"bytes) is assumed." +msgstr "" + +#: ../../c-api/buffer.rst:162 +msgid "This field is controlled by the :c:macro:`PyBUF_FORMAT` flag." +msgstr "此欄位受 :c:macro:`PyBUF_FORMAT` 旗標控制。" + +#: ../../c-api/buffer.rst:166 +msgid "" +"The number of dimensions the memory represents as an n-dimensional array. If " +"it is ``0``, :c:member:`~Py_buffer.buf` points to a single item representing " +"a scalar. In this case, :c:member:`~Py_buffer.shape`, :c:member:`~Py_buffer." +"strides` and :c:member:`~Py_buffer.suboffsets` MUST be ``NULL``. The maximum " +"number of dimensions is given by :c:macro:`PyBUF_MAX_NDIM`." +msgstr "" + +#: ../../c-api/buffer.rst:174 +msgid "" +"An array of :c:type:`Py_ssize_t` of length :c:member:`~Py_buffer.ndim` " +"indicating the shape of the memory as an n-dimensional array. Note that " +"``shape[0] * ... * shape[ndim-1] * itemsize`` MUST be equal to :c:member:" +"`~Py_buffer.len`." +msgstr "" + +#: ../../c-api/buffer.rst:179 +msgid "" +"Shape values are restricted to ``shape[n] >= 0``. The case ``shape[n] == 0`` " +"requires special attention. See `complex arrays`_ for further information." +msgstr "" + +#: ../../c-api/buffer.rst:183 +msgid "The shape array is read-only for the consumer." +msgstr "" + +#: ../../c-api/buffer.rst:187 +msgid "" +"An array of :c:type:`Py_ssize_t` of length :c:member:`~Py_buffer.ndim` " +"giving the number of bytes to skip to get to a new element in each dimension." +msgstr "" + +#: ../../c-api/buffer.rst:191 +msgid "" +"Stride values can be any integer. For regular arrays, strides are usually " +"positive, but a consumer MUST be able to handle the case ``strides[n] <= " +"0``. See `complex arrays`_ for further information." +msgstr "" + +#: ../../c-api/buffer.rst:195 +msgid "The strides array is read-only for the consumer." +msgstr "" + +#: ../../c-api/buffer.rst:199 +msgid "" +"An array of :c:type:`Py_ssize_t` of length :c:member:`~Py_buffer.ndim`. If " +"``suboffsets[n] >= 0``, the values stored along the nth dimension are " +"pointers and the suboffset value dictates how many bytes to add to each " +"pointer after de-referencing. A suboffset value that is negative indicates " +"that no de-referencing should occur (striding in a contiguous memory block)." +msgstr "" + +#: ../../c-api/buffer.rst:206 +msgid "" +"If all suboffsets are negative (i.e. no de-referencing is needed), then this " +"field must be ``NULL`` (the default value)." +msgstr "" + +#: ../../c-api/buffer.rst:209 +msgid "" +"This type of array representation is used by the Python Imaging Library " +"(PIL). See `complex arrays`_ for further information how to access elements " +"of such an array." +msgstr "" + +#: ../../c-api/buffer.rst:213 +msgid "The suboffsets array is read-only for the consumer." +msgstr "" + +#: ../../c-api/buffer.rst:217 +msgid "" +"This is for use internally by the exporting object. For example, this might " +"be re-cast as an integer by the exporter and used to store flags about " +"whether or not the shape, strides, and suboffsets arrays must be freed when " +"the buffer is released. The consumer MUST NOT alter this value." +msgstr "" + +#: ../../c-api/buffer.rst:224 +msgid "Constants:" +msgstr "常數：" + +#: ../../c-api/buffer.rst:228 +msgid "" +"The maximum number of dimensions the memory represents. Exporters MUST " +"respect this limit, consumers of multi-dimensional buffers SHOULD be able to " +"handle up to :c:macro:`!PyBUF_MAX_NDIM` dimensions. Currently set to 64." +msgstr "" + +#: ../../c-api/buffer.rst:237 +msgid "Buffer request types" +msgstr "" + +#: ../../c-api/buffer.rst:239 +msgid "" +"Buffers are usually obtained by sending a buffer request to an exporting " +"object via :c:func:`PyObject_GetBuffer`. Since the complexity of the logical " +"structure of the memory can vary drastically, the consumer uses the *flags* " +"argument to specify the exact buffer type it can handle." +msgstr "" + +#: ../../c-api/buffer.rst:244 +msgid "" +"All :c:type:`Py_buffer` fields are unambiguously defined by the request type." +msgstr "" + +#: ../../c-api/buffer.rst:248 +msgid "request-independent fields" +msgstr "" + +#: ../../c-api/buffer.rst:249 +msgid "" +"The following fields are not influenced by *flags* and must always be filled " +"in with the correct values: :c:member:`~Py_buffer.obj`, :c:member:" +"`~Py_buffer.buf`, :c:member:`~Py_buffer.len`, :c:member:`~Py_buffer." +"itemsize`, :c:member:`~Py_buffer.ndim`." +msgstr "" + +#: ../../c-api/buffer.rst:254 +msgid "readonly, format" +msgstr "" + +#: ../../c-api/buffer.rst:258 +msgid "" +"Controls the :c:member:`~Py_buffer.readonly` field. If set, the exporter " +"MUST provide a writable buffer or else report failure. Otherwise, the " +"exporter MAY provide either a read-only or writable buffer, but the choice " +"MUST be consistent for all consumers. For example, :c:expr:`PyBUF_SIMPLE | " +"PyBUF_WRITABLE` can be used to request a simple writable buffer." +msgstr "" + +#: ../../c-api/buffer.rst:266 +msgid "This is a :term:`soft deprecated` alias to :c:macro:`PyBUF_WRITABLE`." +msgstr "這是 :c:macro:`PyBUF_WRITABLE` 的\\ :term:`軟性棄用 `\\ 別名。" + +#: ../../c-api/buffer.rst:270 +msgid "" +"Controls the :c:member:`~Py_buffer.format` field. If set, this field MUST be " +"filled in correctly. Otherwise, this field MUST be ``NULL``." +msgstr "" + +#: ../../c-api/buffer.rst:274 +msgid "" +":c:macro:`PyBUF_WRITABLE` can be \\|'d to any of the flags in the next " +"section. Since :c:macro:`PyBUF_SIMPLE` is defined as 0, :c:macro:" +"`PyBUF_WRITABLE` can be used as a stand-alone flag to request a simple " +"writable buffer." +msgstr "" + +#: ../../c-api/buffer.rst:278 +msgid "" +":c:macro:`PyBUF_FORMAT` must be \\|'d to any of the flags except :c:macro:" +"`PyBUF_SIMPLE`, because the latter already implies format ``B`` (unsigned " +"bytes). :c:macro:`!PyBUF_FORMAT` cannot be used on its own." +msgstr "" + +#: ../../c-api/buffer.rst:284 +msgid "shape, strides, suboffsets" +msgstr "" + +#: ../../c-api/buffer.rst:286 +msgid "" +"The flags that control the logical structure of the memory are listed in " +"decreasing order of complexity. Note that each flag contains all bits of the " +"flags below it." +msgstr "" + +#: ../../c-api/buffer.rst:293 ../../c-api/buffer.rst:317 +#: ../../c-api/buffer.rst:342 +msgid "Request" +msgstr "" + +#: ../../c-api/buffer.rst:293 ../../c-api/buffer.rst:317 +#: ../../c-api/buffer.rst:342 +msgid "shape" +msgstr "" + +#: ../../c-api/buffer.rst:293 ../../c-api/buffer.rst:317 +#: ../../c-api/buffer.rst:342 +msgid "strides" +msgstr "" + +#: ../../c-api/buffer.rst:293 ../../c-api/buffer.rst:317 +#: ../../c-api/buffer.rst:342 +msgid "suboffsets" +msgstr "" + +#: ../../c-api/buffer.rst:295 ../../c-api/buffer.rst:297 +#: ../../c-api/buffer.rst:299 ../../c-api/buffer.rst:319 +#: ../../c-api/buffer.rst:321 ../../c-api/buffer.rst:323 +#: ../../c-api/buffer.rst:325 ../../c-api/buffer.rst:344 +#: ../../c-api/buffer.rst:346 ../../c-api/buffer.rst:348 +#: ../../c-api/buffer.rst:350 ../../c-api/buffer.rst:352 +#: ../../c-api/buffer.rst:354 ../../c-api/buffer.rst:356 +#: ../../c-api/buffer.rst:358 +msgid "yes" +msgstr "" + +#: ../../c-api/buffer.rst:295 ../../c-api/buffer.rst:344 +#: ../../c-api/buffer.rst:346 +msgid "if needed" +msgstr "" + +#: ../../c-api/buffer.rst:297 ../../c-api/buffer.rst:299 +#: ../../c-api/buffer.rst:301 ../../c-api/buffer.rst:319 +#: ../../c-api/buffer.rst:321 ../../c-api/buffer.rst:323 +#: ../../c-api/buffer.rst:325 ../../c-api/buffer.rst:348 +#: ../../c-api/buffer.rst:350 ../../c-api/buffer.rst:352 +#: ../../c-api/buffer.rst:354 ../../c-api/buffer.rst:356 +#: ../../c-api/buffer.rst:358 +msgid "NULL" +msgstr "NULL" + +#: ../../c-api/buffer.rst:308 +msgid "contiguity requests" +msgstr "" + +#: ../../c-api/buffer.rst:310 +msgid "" +"C or Fortran :term:`contiguity ` can be explicitly requested, " +"with and without stride information. Without stride information, the buffer " +"must be C-contiguous." +msgstr "" + +#: ../../c-api/buffer.rst:317 ../../c-api/buffer.rst:342 +msgid "contig" +msgstr "" + +#: ../../c-api/buffer.rst:319 ../../c-api/buffer.rst:325 +#: ../../c-api/buffer.rst:356 ../../c-api/buffer.rst:358 +msgid "C" +msgstr "C" + +#: ../../c-api/buffer.rst:321 +msgid "F" +msgstr "F" + +#: ../../c-api/buffer.rst:323 +msgid "C or F" +msgstr "C 或 F" + +#: ../../c-api/buffer.rst:325 +msgid ":c:macro:`PyBUF_ND`" +msgstr ":c:macro:`PyBUF_ND`" + +#: ../../c-api/buffer.rst:330 +msgid "compound requests" +msgstr "" + +#: ../../c-api/buffer.rst:332 +msgid "" +"All possible requests are fully defined by some combination of the flags in " +"the previous section. For convenience, the buffer protocol provides " +"frequently used combinations as single flags." +msgstr "" + +#: ../../c-api/buffer.rst:336 +msgid "" +"In the following table *U* stands for undefined contiguity. The consumer " +"would have to call :c:func:`PyBuffer_IsContiguous` to determine contiguity." +msgstr "" + +#: ../../c-api/buffer.rst:342 +msgid "readonly" +msgstr "" + +#: ../../c-api/buffer.rst:342 +msgid "format" +msgstr "" + +#: ../../c-api/buffer.rst:344 ../../c-api/buffer.rst:346 +#: ../../c-api/buffer.rst:348 ../../c-api/buffer.rst:350 +#: ../../c-api/buffer.rst:352 ../../c-api/buffer.rst:354 +msgid "U" +msgstr "U" + +#: ../../c-api/buffer.rst:344 ../../c-api/buffer.rst:348 +#: ../../c-api/buffer.rst:352 ../../c-api/buffer.rst:356 +msgid "0" +msgstr "0" + +#: ../../c-api/buffer.rst:346 ../../c-api/buffer.rst:350 +#: ../../c-api/buffer.rst:354 ../../c-api/buffer.rst:358 +msgid "1 or 0" +msgstr "1 或 0" + +#: ../../c-api/buffer.rst:363 +msgid "Complex arrays" +msgstr "" + +#: ../../c-api/buffer.rst:366 +msgid "NumPy-style: shape and strides" +msgstr "NumPy 風格：形狀與步幅" + +#: ../../c-api/buffer.rst:368 +msgid "" +"The logical structure of NumPy-style arrays is defined by :c:member:" +"`~Py_buffer.itemsize`, :c:member:`~Py_buffer.ndim`, :c:member:`~Py_buffer." +"shape` and :c:member:`~Py_buffer.strides`." +msgstr "" + +#: ../../c-api/buffer.rst:371 +msgid "" +"If ``ndim == 0``, the memory location pointed to by :c:member:`~Py_buffer." +"buf` is interpreted as a scalar of size :c:member:`~Py_buffer.itemsize`. In " +"that case, both :c:member:`~Py_buffer.shape` and :c:member:`~Py_buffer." +"strides` are ``NULL``." +msgstr "" + +#: ../../c-api/buffer.rst:375 +msgid "" +"If :c:member:`~Py_buffer.strides` is ``NULL``, the array is interpreted as a " +"standard n-dimensional C-array. Otherwise, the consumer must access an n-" +"dimensional array as follows:" +msgstr "" + +#: ../../c-api/buffer.rst:379 +msgid "" +"ptr = (char *)buf + indices[0] * strides[0] + ... + indices[n-1] * " +"strides[n-1];\n" +"item = *((typeof(item) *)ptr);" +msgstr "" +"ptr = (char *)buf + indices[0] * strides[0] + ... + indices[n-1] * " +"strides[n-1];\n" +"item = *((typeof(item) *)ptr);" + +#: ../../c-api/buffer.rst:385 +msgid "" +"As noted above, :c:member:`~Py_buffer.buf` can point to any location within " +"the actual memory block. An exporter can check the validity of a buffer with " +"this function:" +msgstr "" + +#: ../../c-api/buffer.rst:389 +msgid "" +"def verify_structure(memlen, itemsize, ndim, shape, strides, offset):\n" +" \"\"\"Verify that the parameters represent a valid array within\n" +" the bounds of the allocated memory:\n" +" char *mem: start of the physical memory block\n" +" memlen: length of the physical memory block\n" +" offset: (char *)buf - mem\n" +" \"\"\"\n" +" if offset % itemsize:\n" +" return False\n" +" if offset < 0 or offset+itemsize > memlen:\n" +" return False\n" +" if any(v % itemsize for v in strides):\n" +" return False\n" +"\n" +" if ndim <= 0:\n" +" return ndim == 0 and not shape and not strides\n" +" if 0 in shape:\n" +" return True\n" +"\n" +" imin = sum(strides[j]*(shape[j]-1) for j in range(ndim)\n" +" if strides[j] <= 0)\n" +" imax = sum(strides[j]*(shape[j]-1) for j in range(ndim)\n" +" if strides[j] > 0)\n" +"\n" +" return 0 <= offset+imin and offset+imax+itemsize <= memlen" +msgstr "" + +#: ../../c-api/buffer.rst:419 +msgid "PIL-style: shape, strides and suboffsets" +msgstr "" + +#: ../../c-api/buffer.rst:421 +msgid "" +"In addition to the regular items, PIL-style arrays can contain pointers that " +"must be followed in order to get to the next element in a dimension. For " +"example, the regular three-dimensional C-array ``char v[2][2][3]`` can also " +"be viewed as an array of 2 pointers to 2 two-dimensional arrays: ``char " +"(*v[2])[2][3]``. In suboffsets representation, those two pointers can be " +"embedded at the start of :c:member:`~Py_buffer.buf`, pointing to two ``char " +"x[2][3]`` arrays that can be located anywhere in memory." +msgstr "" + +#: ../../c-api/buffer.rst:430 +msgid "" +"Here is a function that returns a pointer to the element in an N-D array " +"pointed to by an N-dimensional index when there are both non-``NULL`` " +"strides and suboffsets::" +msgstr "" + +#: ../../c-api/buffer.rst:434 +msgid "" +"void *get_item_pointer(int ndim, void *buf, Py_ssize_t *strides,\n" +" Py_ssize_t *suboffsets, Py_ssize_t *indices) {\n" +" char *pointer = (char*)buf;\n" +" int i;\n" +" for (i = 0; i < ndim; i++) {\n" +" pointer += strides[i] * indices[i];\n" +" if (suboffsets[i] >=0 ) {\n" +" pointer = *((char**)pointer) + suboffsets[i];\n" +" }\n" +" }\n" +" return (void*)pointer;\n" +"}" +msgstr "" +"void *get_item_pointer(int ndim, void *buf, Py_ssize_t *strides,\n" +" Py_ssize_t *suboffsets, Py_ssize_t *indices) {\n" +" char *pointer = (char*)buf;\n" +" int i;\n" +" for (i = 0; i < ndim; i++) {\n" +" pointer += strides[i] * indices[i];\n" +" if (suboffsets[i] >=0 ) {\n" +" pointer = *((char**)pointer) + suboffsets[i];\n" +" }\n" +" }\n" +" return (void*)pointer;\n" +"}" + +#: ../../c-api/buffer.rst:449 +msgid "Buffer-related functions" +msgstr "與緩衝相關的函式" + +#: ../../c-api/buffer.rst:453 +msgid "" +"Return ``1`` if *obj* supports the buffer interface otherwise ``0``. When " +"``1`` is returned, it doesn't guarantee that :c:func:`PyObject_GetBuffer` " +"will succeed. This function always succeeds." +msgstr "" + +#: ../../c-api/buffer.rst:460 +msgid "" +"Send a request to *exporter* to fill in *view* as specified by *flags*. If " +"the exporter cannot provide a buffer of the exact type, it MUST raise :exc:" +"`BufferError`, set ``view->obj`` to ``NULL`` and return ``-1``." +msgstr "" + +#: ../../c-api/buffer.rst:465 +msgid "" +"On success, fill in *view*, set ``view->obj`` to a new reference to " +"*exporter* and return 0. In the case of chained buffer providers that " +"redirect requests to a single object, ``view->obj`` MAY refer to this object " +"instead of *exporter* (See :ref:`Buffer Object Structures `)." +msgstr "" + +#: ../../c-api/buffer.rst:470 +msgid "" +"Successful calls to :c:func:`PyObject_GetBuffer` must be paired with calls " +"to :c:func:`PyBuffer_Release`, similar to :c:func:`malloc` and :c:func:" +"`free`. Thus, after the consumer is done with the buffer, :c:func:" +"`PyBuffer_Release` must be called exactly once." +msgstr "" + +#: ../../c-api/buffer.rst:478 +msgid "" +"Release the buffer *view* and release the :term:`strong reference` (i.e. " +"decrement the reference count) to the view's supporting object, ``view-" +">obj``. This function MUST be called when the buffer is no longer being " +"used, otherwise reference leaks may occur." +msgstr "" + +#: ../../c-api/buffer.rst:483 +msgid "" +"It is an error to call this function on a buffer that was not obtained via :" +"c:func:`PyObject_GetBuffer`." +msgstr "" + +#: ../../c-api/buffer.rst:489 +msgid "" +"Return the implied :c:member:`~Py_buffer.itemsize` from :c:member:" +"`~Py_buffer.format`. On error, raise an exception and return -1." +msgstr "" + +#: ../../c-api/buffer.rst:497 +msgid "" +"Return ``1`` if the memory defined by the *view* is C-style (*order* is " +"``'C'``) or Fortran-style (*order* is ``'F'``) :term:`contiguous` or either " +"one (*order* is ``'A'``). Return ``0`` otherwise. This function always " +"succeeds." +msgstr "" + +#: ../../c-api/buffer.rst:504 +msgid "" +"Get the memory area pointed to by the *indices* inside the given *view*. " +"*indices* must point to an array of ``view->ndim`` indices." +msgstr "" + +#: ../../c-api/buffer.rst:510 +msgid "" +"Copy contiguous *len* bytes from *buf* to *view*. *fort* can be ``'C'`` or " +"``'F'`` (for C-style or Fortran-style ordering). ``0`` is returned on " +"success, ``-1`` on error." +msgstr "" + +#: ../../c-api/buffer.rst:517 +msgid "" +"Copy *len* bytes from *src* to its contiguous representation in *buf*. " +"*order* can be ``'C'`` or ``'F'`` or ``'A'`` (for C-style or Fortran-style " +"ordering or either one). ``0`` is returned on success, ``-1`` on error." +msgstr "" + +#: ../../c-api/buffer.rst:521 +msgid "This function fails if *len* != *src->len*." +msgstr "此函式在 *len* != *src->len* 時失敗。" + +#: ../../c-api/buffer.rst:526 +msgid "" +"Copy data from *src* to *dest* buffer. Can convert between C-style and or " +"Fortran-style buffers." +msgstr "" + +#: ../../c-api/buffer.rst:529 +msgid "``0`` is returned on success, ``-1`` on error." +msgstr "成功時回傳 ``0``，錯誤時回傳 ``-1``。" + +#: ../../c-api/buffer.rst:533 +msgid "" +"Fill the *strides* array with byte-strides of a :term:`contiguous` (C-style " +"if *order* is ``'C'`` or Fortran-style if *order* is ``'F'``) array of the " +"given shape with the given number of bytes per element." +msgstr "" + +#: ../../c-api/buffer.rst:540 +msgid "" +"Handle buffer requests for an exporter that wants to expose *buf* of size " +"*len* with writability set according to *readonly*. *buf* is interpreted as " +"a sequence of unsigned bytes." +msgstr "" + +#: ../../c-api/buffer.rst:544 +msgid "" +"The *flags* argument indicates the request type. This function always fills " +"in *view* as specified by flags, unless *buf* has been designated as read-" +"only and :c:macro:`PyBUF_WRITABLE` is set in *flags*." +msgstr "" + +#: ../../c-api/buffer.rst:548 +msgid "" +"On success, set ``view->obj`` to a new reference to *exporter* and return 0. " +"Otherwise, raise :exc:`BufferError`, set ``view->obj`` to ``NULL`` and " +"return ``-1``;" +msgstr "" + +#: ../../c-api/buffer.rst:552 +msgid "" +"If this function is used as part of a :ref:`getbufferproc `, " +"*exporter* MUST be set to the exporting object and *flags* must be passed " +"unmodified. Otherwise, *exporter* MUST be ``NULL``." +msgstr "" + +#: ../../c-api/buffer.rst:3 +msgid "buffer protocol" +msgstr "buffer protocol（緩衝協定）" + +#: ../../c-api/buffer.rst:3 +msgid "buffer interface" +msgstr "buffer interface（緩衝介面）" + +#: ../../c-api/buffer.rst:3 +msgid "(see buffer protocol)" +msgstr "(請見緩衝協定)" + +#: ../../c-api/buffer.rst:3 +msgid "buffer object" +msgstr "buffer object（緩衝物件）" + +#: ../../c-api/buffer.rst:32 +msgid "PyBufferProcs (C type)" +msgstr "PyBufferProcs（C 型別）" + +#: ../../c-api/buffer.rst:305 +msgid "contiguous" +msgstr "contiguous（連續的）" + +#: ../../c-api/buffer.rst:305 +msgid "C-contiguous" +msgstr "C-contiguous（C 連續的）" + +#: ../../c-api/buffer.rst:305 +msgid "Fortran contiguous" +msgstr "Fortran contiguous（Fortran 連續的）" diff --git a/c-api/bytearray.po b/c-api/bytearray.po index 9853f9a639..1c260eb95a 100644 --- a/c-api/bytearray.po +++ b/c-api/bytearray.po @@ -1,129 +1,129 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: 2023-08-12 11:42+0800\n" -"Last-Translator: Liang-Bo Wang \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" -"X-Generator: Poedit 3.3.2\n" - -#: ../../c-api/bytearray.rst:6 -msgid "Byte Array Objects" -msgstr "位元組陣列物件 (Byte Array Objects)" - -#: ../../c-api/bytearray.rst:13 -msgid "" -"This subtype of :c:type:`PyObject` represents a Python bytearray object." -msgstr "這個 :c:type:`PyObject` 的子型別代表了 Python 的位元組陣列物件。" - -#: ../../c-api/bytearray.rst:18 -msgid "" -"This instance of :c:type:`PyTypeObject` represents the Python bytearray " -"type; it is the same object as :class:`bytearray` in the Python layer." -msgstr "" -"這個 :c:type:`PyTypeObject` 的實例代表了 Python 的位元組陣列型別；在 Python " -"層中的 :class:`bytearray` 為同一個物件。" - -#: ../../c-api/bytearray.rst:23 -msgid "Type check macros" -msgstr "型別檢查巨集" - -#: ../../c-api/bytearray.rst:27 -msgid "" -"Return true if the object *o* is a bytearray object or an instance of a " -"subtype of the bytearray type. This function always succeeds." -msgstr "" -"如果物件 *o* 是一個位元組陣列物件，或者是位元組陣列型別的子型別的實例，則回傳" -"真值。此函式總是會成功執行。" - -#: ../../c-api/bytearray.rst:33 -msgid "" -"Return true if the object *o* is a bytearray object, but not an instance of " -"a subtype of the bytearray type. This function always succeeds." -msgstr "" -"如果物件 *o* 是一個位元組陣列物件，但不是位元組陣列型別的子型別的實例，則回傳" -"真值。此函式總是會成功執行。" - -#: ../../c-api/bytearray.rst:38 -msgid "Direct API functions" -msgstr "直接 API 函式" - -#: ../../c-api/bytearray.rst:42 -msgid "" -"Return a new bytearray object from any object, *o*, that implements " -"the :ref:`buffer protocol `." -msgstr "" -"由任意物件 *o* 回傳一個新的位元組陣列物件，並實作了\\ :ref:`緩衝協定 (buffer " -"protocol) `。" - -#: ../../c-api/bytearray.rst:45 ../../c-api/bytearray.rst:52 -#: ../../c-api/bytearray.rst:59 -msgid "On failure, return ``NULL`` with an exception set." -msgstr "在失敗時，會回傳 ``NULL`` 並設定例外。" - -#: ../../c-api/bytearray.rst:50 -msgid "Create a new bytearray object from *string* and its length, *len*." -msgstr "從 *string* 及其長度 *len* 建立一個新的位元組陣列物件。" - -#: ../../c-api/bytearray.rst:57 -msgid "" -"Concat bytearrays *a* and *b* and return a new bytearray with the result." -msgstr "連接位元組陣列 *a* 和 *b*，並回傳一個包含結果的新位元組陣列。" - -#: ../../c-api/bytearray.rst:64 -msgid "Return the size of *bytearray* after checking for a ``NULL`` pointer." -msgstr "在檢查為 ``NULL`` 指標後，回傳 *bytearray* 的大小。" - -#: ../../c-api/bytearray.rst:69 -msgid "" -"Return the contents of *bytearray* as a char array after checking for a " -"``NULL`` pointer. The returned array always has an extra null byte appended." -msgstr "" -"在檢查是否為 ``NULL`` 指標後，將 *bytearray* 的內容回傳為字元陣列。回傳的陣列" -"總是會多附加一個空位元組。" - -#: ../../c-api/bytearray.rst:76 -msgid "" -"Resize the internal buffer of *bytearray* to *len*. Failure is a ``-1`` " -"return with an exception set." -msgstr "將 *bytearray* 的內部緩衝區大小調整為 *len*。失敗時會回傳 ``-1`` 並設定例外。" - -#: ../../c-api/bytearray.rst:79 -msgid "" -"A negative *len* will now result in an exception being set and -1 returned." -msgstr "負的 *len* 現在會設定例外並回傳 -1。" - -#: ../../c-api/bytearray.rst:84 -msgid "Macros" -msgstr "巨集" - -#: ../../c-api/bytearray.rst:86 -msgid "These macros trade safety for speed and they don't check pointers." -msgstr "這些巨集犧牲了安全性以換取速度，並且它們不會檢查指標。" - -#: ../../c-api/bytearray.rst:90 -msgid "Similar to :c:func:`PyByteArray_AsString`, but without error checking." -msgstr "與 :c:func:`PyByteArray_AsString` 類似，但沒有錯誤檢查。" - -#: ../../c-api/bytearray.rst:95 -msgid "Similar to :c:func:`PyByteArray_Size`, but without error checking." -msgstr "與 :c:func:`PyByteArray_Size` 類似，但沒有錯誤檢查。" - -#: ../../c-api/bytearray.rst:8 -msgid "object" -msgstr "object（物件）" - -#: ../../c-api/bytearray.rst:8 -msgid "bytearray" -msgstr "bytearray（位元組陣列）" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: 2023-08-12 11:42+0800\n" +"Last-Translator: Liang-Bo Wang \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" +"X-Generator: Poedit 3.3.2\n" + +#: ../../c-api/bytearray.rst:6 +msgid "Byte Array Objects" +msgstr "位元組陣列物件 (Byte Array Objects)" + +#: ../../c-api/bytearray.rst:13 +msgid "" +"This subtype of :c:type:`PyObject` represents a Python bytearray object." +msgstr "這個 :c:type:`PyObject` 的子型別代表了 Python 的位元組陣列物件。" + +#: ../../c-api/bytearray.rst:18 +msgid "" +"This instance of :c:type:`PyTypeObject` represents the Python bytearray " +"type; it is the same object as :class:`bytearray` in the Python layer." +msgstr "" +"這個 :c:type:`PyTypeObject` 的實例代表了 Python 的位元組陣列型別；在 Python " +"層中的 :class:`bytearray` 為同一個物件。" + +#: ../../c-api/bytearray.rst:23 +msgid "Type check macros" +msgstr "型別檢查巨集" + +#: ../../c-api/bytearray.rst:27 +msgid "" +"Return true if the object *o* is a bytearray object or an instance of a " +"subtype of the bytearray type. This function always succeeds." +msgstr "" +"如果物件 *o* 是一個位元組陣列物件，或者是位元組陣列型別的子型別的實例，則回傳" +"真值。此函式總是會成功執行。" + +#: ../../c-api/bytearray.rst:33 +msgid "" +"Return true if the object *o* is a bytearray object, but not an instance of " +"a subtype of the bytearray type. This function always succeeds." +msgstr "" +"如果物件 *o* 是一個位元組陣列物件，但不是位元組陣列型別的子型別的實例，則回傳" +"真值。此函式總是會成功執行。" + +#: ../../c-api/bytearray.rst:38 +msgid "Direct API functions" +msgstr "直接 API 函式" + +#: ../../c-api/bytearray.rst:42 +msgid "" +"Return a new bytearray object from any object, *o*, that implements " +"the :ref:`buffer protocol `." +msgstr "" +"由任意物件 *o* 回傳一個新的位元組陣列物件，並實作了\\ :ref:`緩衝協定 (buffer " +"protocol) `。" + +#: ../../c-api/bytearray.rst:45 ../../c-api/bytearray.rst:52 +#: ../../c-api/bytearray.rst:59 +msgid "On failure, return ``NULL`` with an exception set." +msgstr "在失敗時，會回傳 ``NULL`` 並設定例外。" + +#: ../../c-api/bytearray.rst:50 +msgid "Create a new bytearray object from *string* and its length, *len*." +msgstr "從 *string* 及其長度 *len* 建立一個新的位元組陣列物件。" + +#: ../../c-api/bytearray.rst:57 +msgid "" +"Concat bytearrays *a* and *b* and return a new bytearray with the result." +msgstr "連接位元組陣列 *a* 和 *b*，並回傳一個包含結果的新位元組陣列。" + +#: ../../c-api/bytearray.rst:64 +msgid "Return the size of *bytearray* after checking for a ``NULL`` pointer." +msgstr "在檢查為 ``NULL`` 指標後，回傳 *bytearray* 的大小。" + +#: ../../c-api/bytearray.rst:69 +msgid "" +"Return the contents of *bytearray* as a char array after checking for a " +"``NULL`` pointer. The returned array always has an extra null byte appended." +msgstr "" +"在檢查是否為 ``NULL`` 指標後，將 *bytearray* 的內容回傳為字元陣列。回傳的陣列" +"總是會多附加一個空位元組。" + +#: ../../c-api/bytearray.rst:76 +msgid "" +"Resize the internal buffer of *bytearray* to *len*. Failure is a ``-1`` " +"return with an exception set." +msgstr "將 *bytearray* 的內部緩衝區大小調整為 *len*。失敗時會回傳 ``-1`` 並設定例外。" + +#: ../../c-api/bytearray.rst:79 +msgid "" +"A negative *len* will now result in an exception being set and -1 returned." +msgstr "負的 *len* 現在會設定例外並回傳 -1。" + +#: ../../c-api/bytearray.rst:84 +msgid "Macros" +msgstr "巨集" + +#: ../../c-api/bytearray.rst:86 +msgid "These macros trade safety for speed and they don't check pointers." +msgstr "這些巨集犧牲了安全性以換取速度，並且它們不會檢查指標。" + +#: ../../c-api/bytearray.rst:90 +msgid "Similar to :c:func:`PyByteArray_AsString`, but without error checking." +msgstr "與 :c:func:`PyByteArray_AsString` 類似，但沒有錯誤檢查。" + +#: ../../c-api/bytearray.rst:95 +msgid "Similar to :c:func:`PyByteArray_Size`, but without error checking." +msgstr "與 :c:func:`PyByteArray_Size` 類似，但沒有錯誤檢查。" + +#: ../../c-api/bytearray.rst:8 +msgid "object" +msgstr "object（物件）" + +#: ../../c-api/bytearray.rst:8 +msgid "bytearray" +msgstr "bytearray（位元組陣列）" diff --git a/c-api/bytes.po b/c-api/bytes.po index 86da7979be..0c429824ee 100644 --- a/c-api/bytes.po +++ b/c-api/bytes.po @@ -1,408 +1,408 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-12-01 00:17+0000\n" -"PO-Revision-Date: 2018-05-23 14:04+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" - -#: ../../c-api/bytes.rst:6 -msgid "Bytes Objects" -msgstr "位元組物件 (Bytes Objects)" - -#: ../../c-api/bytes.rst:8 -msgid "" -"These functions raise :exc:`TypeError` when expecting a bytes parameter and " -"called with a non-bytes parameter." -msgstr "" - -#: ../../c-api/bytes.rst:16 -msgid "This subtype of :c:type:`PyObject` represents a Python bytes object." -msgstr "" - -#: ../../c-api/bytes.rst:21 -msgid "" -"This instance of :c:type:`PyTypeObject` represents the Python bytes type; it " -"is the same object as :class:`bytes` in the Python layer." -msgstr "" - -#: ../../c-api/bytes.rst:27 -msgid "" -"Return true if the object *o* is a bytes object or an instance of a subtype " -"of the bytes type. This function always succeeds." -msgstr "" - -#: ../../c-api/bytes.rst:33 -msgid "" -"Return true if the object *o* is a bytes object, but not an instance of a " -"subtype of the bytes type. This function always succeeds." -msgstr "" - -#: ../../c-api/bytes.rst:39 -msgid "" -"Return a new bytes object with a copy of the string *v* as value on success, " -"and ``NULL`` on failure. The parameter *v* must not be ``NULL``; it will " -"not be checked." -msgstr "" - -#: ../../c-api/bytes.rst:46 -msgid "" -"Return a new bytes object with a copy of the string *v* as value and length " -"*len* on success, and ``NULL`` on failure. If *v* is ``NULL``, the contents " -"of the bytes object are uninitialized." -msgstr "" - -#: ../../c-api/bytes.rst:53 -msgid "" -"Take a C :c:func:`printf`\\ -style *format* string and a variable number of " -"arguments, calculate the size of the resulting Python bytes object and " -"return a bytes object with the values formatted into it. The variable " -"arguments must be C types and must correspond exactly to the format " -"characters in the *format* string. The following format characters are " -"allowed:" -msgstr "" - -#: ../../c-api/bytes.rst:65 -msgid "Format Characters" -msgstr "" - -#: ../../c-api/bytes.rst:65 -msgid "Type" -msgstr "" - -#: ../../c-api/bytes.rst:65 -msgid "Comment" -msgstr "" - -#: ../../c-api/bytes.rst:67 -msgid "``%%``" -msgstr "``%%``" - -#: ../../c-api/bytes.rst:67 -msgid "*n/a*" -msgstr "*n/a*" - -#: ../../c-api/bytes.rst:67 -msgid "The literal % character." -msgstr "" - -#: ../../c-api/bytes.rst:69 -msgid "``%c``" -msgstr "``%c``" - -#: ../../c-api/bytes.rst:69 ../../c-api/bytes.rst:72 ../../c-api/bytes.rst:90 -#: ../../c-api/bytes.rst:93 -msgid "int" -msgstr "int" - -#: ../../c-api/bytes.rst:69 -msgid "A single byte, represented as a C int." -msgstr "" - -#: ../../c-api/bytes.rst:72 -msgid "``%d``" -msgstr "``%d``" - -#: ../../c-api/bytes.rst:72 -msgid "Equivalent to ``printf(\"%d\")``. [1]_" -msgstr "等價於 ``printf(\"%d\")``. [1]_" - -#: ../../c-api/bytes.rst:75 -msgid "``%u``" -msgstr "``%u``" - -#: ../../c-api/bytes.rst:75 -msgid "unsigned int" -msgstr "unsigned int" - -#: ../../c-api/bytes.rst:75 -msgid "Equivalent to ``printf(\"%u\")``. [1]_" -msgstr "等價於 ``printf(\"%u\")``. [1]_" - -#: ../../c-api/bytes.rst:78 -msgid "``%ld``" -msgstr "``%ld``" - -#: ../../c-api/bytes.rst:78 -msgid "long" -msgstr "long" - -#: ../../c-api/bytes.rst:78 -msgid "Equivalent to ``printf(\"%ld\")``. [1]_" -msgstr "等價於 ``printf(\"%ld\")``. [1]_" - -#: ../../c-api/bytes.rst:81 -msgid "``%lu``" -msgstr "``%lu``" - -#: ../../c-api/bytes.rst:81 -msgid "unsigned long" -msgstr "unsigned long" - -#: ../../c-api/bytes.rst:81 -msgid "Equivalent to ``printf(\"%lu\")``. [1]_" -msgstr "等價於 ``printf(\"%lu\")``. [1]_" - -#: ../../c-api/bytes.rst:84 -msgid "``%zd``" -msgstr "``%zd``" - -#: ../../c-api/bytes.rst:84 -msgid ":c:type:` Py_ssize_t`" -msgstr ":c:type:` Py_ssize_t`" - -#: ../../c-api/bytes.rst:84 -msgid "Equivalent to ``printf(\"%zd\")``. [1]_" -msgstr "等價於 ``printf(\"%zd\")``. [1]_" - -#: ../../c-api/bytes.rst:87 -msgid "``%zu``" -msgstr "``%zu``" - -#: ../../c-api/bytes.rst:87 -msgid "size_t" -msgstr "size_t" - -#: ../../c-api/bytes.rst:87 -msgid "Equivalent to ``printf(\"%zu\")``. [1]_" -msgstr "等價於 ``printf(\"%zu\")``. [1]_" - -#: ../../c-api/bytes.rst:90 -msgid "``%i``" -msgstr "``%i``" - -#: ../../c-api/bytes.rst:90 -msgid "Equivalent to ``printf(\"%i\")``. [1]_" -msgstr "等價於 ``printf(\"%i\")``. [1]_" - -#: ../../c-api/bytes.rst:93 -msgid "``%x``" -msgstr "``%x``" - -#: ../../c-api/bytes.rst:93 -msgid "Equivalent to ``printf(\"%x\")``. [1]_" -msgstr "等價於 ``printf(\"%x\")``. [1]_" - -#: ../../c-api/bytes.rst:96 -msgid "``%s``" -msgstr "``%s``" - -#: ../../c-api/bytes.rst:96 -msgid "const char\\*" -msgstr "const char\\*" - -#: ../../c-api/bytes.rst:96 -msgid "A null-terminated C character array." -msgstr "" - -#: ../../c-api/bytes.rst:99 -msgid "``%p``" -msgstr "``%p``" - -#: ../../c-api/bytes.rst:99 -msgid "const void\\*" -msgstr "const void\\*" - -#: ../../c-api/bytes.rst:99 -msgid "" -"The hex representation of a C pointer. Mostly equivalent to " -"``printf(\"%p\")`` except that it is guaranteed to start with the literal " -"``0x`` regardless of what the platform's ``printf`` yields." -msgstr "" - -#: ../../c-api/bytes.rst:108 -msgid "" -"An unrecognized format character causes all the rest of the format string to " -"be copied as-is to the result object, and any extra arguments discarded." -msgstr "" - -#: ../../c-api/bytes.rst:111 -msgid "" -"For integer specifiers (d, u, ld, lu, zd, zu, i, x): the 0-conversion flag " -"has effect even when a precision is given." -msgstr "" - -#: ../../c-api/bytes.rst:117 -msgid "" -"Identical to :c:func:`PyBytes_FromFormat` except that it takes exactly two " -"arguments." -msgstr "" - -#: ../../c-api/bytes.rst:123 -msgid "" -"Return the bytes representation of object *o* that implements the buffer " -"protocol." -msgstr "" - -#: ../../c-api/bytes.rst:129 -msgid "Return the length of the bytes in bytes object *o*." -msgstr "" - -#: ../../c-api/bytes.rst:134 -msgid "Similar to :c:func:`PyBytes_Size`, but without error checking." -msgstr "和 :c:func:`PyBytes_Size` 類似，但不進行錯誤檢查。" - -#: ../../c-api/bytes.rst:139 -msgid "" -"Return a pointer to the contents of *o*. The pointer refers to the internal " -"buffer of *o*, which consists of ``len(o) + 1`` bytes. The last byte in the " -"buffer is always null, regardless of whether there are any other null " -"bytes. The data must not be modified in any way, unless the object was just " -"created using ``PyBytes_FromStringAndSize(NULL, size)``. It must not be " -"deallocated. If *o* is not a bytes object at all, :c:func:" -"`PyBytes_AsString` returns ``NULL`` and raises :exc:`TypeError`." -msgstr "" - -#: ../../c-api/bytes.rst:151 -msgid "Similar to :c:func:`PyBytes_AsString`, but without error checking." -msgstr "和 :c:func:`PyBytes_AsString` 類似，但不進行錯誤檢查。" - -#: ../../c-api/bytes.rst:156 -msgid "" -"Return the null-terminated contents of the object *obj* through the output " -"variables *buffer* and *length*. Returns ``0`` on success." -msgstr "" - -#: ../../c-api/bytes.rst:160 -msgid "" -"If *length* is ``NULL``, the bytes object may not contain embedded null " -"bytes; if it does, the function returns ``-1`` and a :exc:`ValueError` is " -"raised." -msgstr "" - -#: ../../c-api/bytes.rst:164 -msgid "" -"The buffer refers to an internal buffer of *obj*, which includes an " -"additional null byte at the end (not counted in *length*). The data must " -"not be modified in any way, unless the object was just created using " -"``PyBytes_FromStringAndSize(NULL, size)``. It must not be deallocated. If " -"*obj* is not a bytes object at all, :c:func:`PyBytes_AsStringAndSize` " -"returns ``-1`` and raises :exc:`TypeError`." -msgstr "" - -#: ../../c-api/bytes.rst:171 -msgid "" -"Previously, :exc:`TypeError` was raised when embedded null bytes were " -"encountered in the bytes object." -msgstr "" - -#: ../../c-api/bytes.rst:178 -msgid "" -"Create a new bytes object in *\\*bytes* containing the contents of *newpart* " -"appended to *bytes*; the caller will own the new reference. The reference " -"to the old value of *bytes* will be stolen. If the new object cannot be " -"created, the old reference to *bytes* will still be discarded and the value " -"of *\\*bytes* will be set to ``NULL``; the appropriate exception will be set." -msgstr "" - -#: ../../c-api/bytes.rst:187 -msgid "" -"Create a new bytes object in *\\*bytes* containing the contents of *newpart* " -"appended to *bytes*. This version releases the :term:`strong reference` to " -"*newpart* (i.e. decrements its reference count)." -msgstr "" - -#: ../../c-api/bytes.rst:194 -msgid "Similar to ``sep.join(iterable)`` in Python." -msgstr "類似 Python 中的 ``sep.join(iterable)``。" - -#: ../../c-api/bytes.rst:196 -msgid "" -"*sep* must be Python :class:`bytes` object. (Note that :c:func:" -"`PyUnicode_Join` accepts ``NULL`` separator and treats it as a space, " -"whereas :c:func:`PyBytes_Join` doesn't accept ``NULL`` separator.)" -msgstr "" - -#: ../../c-api/bytes.rst:201 -msgid "" -"*iterable* must be an iterable object yielding objects that implement the :" -"ref:`buffer protocol `." -msgstr "" - -#: ../../c-api/bytes.rst:204 -msgid "" -"On success, return a new :class:`bytes` object. On error, set an exception " -"and return ``NULL``." -msgstr "" - -#: ../../c-api/bytes.rst:212 -msgid "" -"Resize a bytes object. *newsize* will be the new length of the bytes object. " -"You can think of it as creating a new bytes object and destroying the old " -"one, only more efficiently. Pass the address of an existing bytes object as " -"an lvalue (it may be written into), and the new size desired. On success, " -"*\\*bytes* holds the resized bytes object and ``0`` is returned; the address " -"in *\\*bytes* may differ from its input value. If the reallocation fails, " -"the original bytes object at *\\*bytes* is deallocated, *\\*bytes* is set to " -"``NULL``, :exc:`MemoryError` is set, and ``-1`` is returned." -msgstr "" - -#: ../../c-api/bytes.rst:226 -msgid "" -"Get the string representation of *bytes*. This function is currently used to " -"implement :meth:`!bytes.__repr__` in Python." -msgstr "" - -#: ../../c-api/bytes.rst:229 -msgid "" -"This function does not do type checking; it is undefined behavior to pass " -"*bytes* as a non-bytes object or ``NULL``." -msgstr "" - -#: ../../c-api/bytes.rst:232 -msgid "" -"If *smartquotes* is true, the representation will use a double-quoted string " -"instead of single-quoted string when single-quotes are present in *bytes*. " -"For example, the byte string ``'Python'`` would be represented as " -"``b\"'Python'\"`` when *smartquotes* is true, or ``b'\\'Python\\''`` when it " -"is false." -msgstr "" - -#: ../../c-api/bytes.rst:238 -msgid "" -"On success, this function returns a :term:`strong reference` to a :class:" -"`str` object containing the representation. On failure, this returns " -"``NULL`` with an exception set." -msgstr "" - -#: ../../c-api/bytes.rst:245 -msgid "" -"Unescape a backslash-escaped string *s*. *s* must not be ``NULL``. *len* " -"must be the size of *s*." -msgstr "" - -#: ../../c-api/bytes.rst:248 -msgid "" -"*errors* must be one of ``\"strict\"``, ``\"replace\"``, or ``\"ignore\"``. " -"If *errors* is ``NULL``, then ``\"strict\"`` is used by default." -msgstr "" - -#: ../../c-api/bytes.rst:251 -msgid "" -"On success, this function returns a :term:`strong reference` to a Python :" -"class:`bytes` object containing the unescaped string. On failure, this " -"function returns ``NULL`` with an exception set." -msgstr "" - -#: ../../c-api/bytes.rst:255 -msgid "*unicode* and *recode_encoding* are now unused." -msgstr "" - -#: ../../c-api/bytes.rst:11 -msgid "object" -msgstr "object（物件）" - -#: ../../c-api/bytes.rst:11 -msgid "bytes" -msgstr "bytes（位元組）" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-12-01 00:17+0000\n" +"PO-Revision-Date: 2018-05-23 14:04+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" + +#: ../../c-api/bytes.rst:6 +msgid "Bytes Objects" +msgstr "位元組物件 (Bytes Objects)" + +#: ../../c-api/bytes.rst:8 +msgid "" +"These functions raise :exc:`TypeError` when expecting a bytes parameter and " +"called with a non-bytes parameter." +msgstr "" + +#: ../../c-api/bytes.rst:16 +msgid "This subtype of :c:type:`PyObject` represents a Python bytes object." +msgstr "" + +#: ../../c-api/bytes.rst:21 +msgid "" +"This instance of :c:type:`PyTypeObject` represents the Python bytes type; it " +"is the same object as :class:`bytes` in the Python layer." +msgstr "" + +#: ../../c-api/bytes.rst:27 +msgid "" +"Return true if the object *o* is a bytes object or an instance of a subtype " +"of the bytes type. This function always succeeds." +msgstr "" + +#: ../../c-api/bytes.rst:33 +msgid "" +"Return true if the object *o* is a bytes object, but not an instance of a " +"subtype of the bytes type. This function always succeeds." +msgstr "" + +#: ../../c-api/bytes.rst:39 +msgid "" +"Return a new bytes object with a copy of the string *v* as value on success, " +"and ``NULL`` on failure. The parameter *v* must not be ``NULL``; it will " +"not be checked." +msgstr "" + +#: ../../c-api/bytes.rst:46 +msgid "" +"Return a new bytes object with a copy of the string *v* as value and length " +"*len* on success, and ``NULL`` on failure. If *v* is ``NULL``, the contents " +"of the bytes object are uninitialized." +msgstr "" + +#: ../../c-api/bytes.rst:53 +msgid "" +"Take a C :c:func:`printf`\\ -style *format* string and a variable number of " +"arguments, calculate the size of the resulting Python bytes object and " +"return a bytes object with the values formatted into it. The variable " +"arguments must be C types and must correspond exactly to the format " +"characters in the *format* string. The following format characters are " +"allowed:" +msgstr "" + +#: ../../c-api/bytes.rst:65 +msgid "Format Characters" +msgstr "" + +#: ../../c-api/bytes.rst:65 +msgid "Type" +msgstr "" + +#: ../../c-api/bytes.rst:65 +msgid "Comment" +msgstr "" + +#: ../../c-api/bytes.rst:67 +msgid "``%%``" +msgstr "``%%``" + +#: ../../c-api/bytes.rst:67 +msgid "*n/a*" +msgstr "*n/a*" + +#: ../../c-api/bytes.rst:67 +msgid "The literal % character." +msgstr "" + +#: ../../c-api/bytes.rst:69 +msgid "``%c``" +msgstr "``%c``" + +#: ../../c-api/bytes.rst:69 ../../c-api/bytes.rst:72 ../../c-api/bytes.rst:90 +#: ../../c-api/bytes.rst:93 +msgid "int" +msgstr "int" + +#: ../../c-api/bytes.rst:69 +msgid "A single byte, represented as a C int." +msgstr "" + +#: ../../c-api/bytes.rst:72 +msgid "``%d``" +msgstr "``%d``" + +#: ../../c-api/bytes.rst:72 +msgid "Equivalent to ``printf(\"%d\")``. [1]_" +msgstr "等價於 ``printf(\"%d\")``. [1]_" + +#: ../../c-api/bytes.rst:75 +msgid "``%u``" +msgstr "``%u``" + +#: ../../c-api/bytes.rst:75 +msgid "unsigned int" +msgstr "unsigned int" + +#: ../../c-api/bytes.rst:75 +msgid "Equivalent to ``printf(\"%u\")``. [1]_" +msgstr "等價於 ``printf(\"%u\")``. [1]_" + +#: ../../c-api/bytes.rst:78 +msgid "``%ld``" +msgstr "``%ld``" + +#: ../../c-api/bytes.rst:78 +msgid "long" +msgstr "long" + +#: ../../c-api/bytes.rst:78 +msgid "Equivalent to ``printf(\"%ld\")``. [1]_" +msgstr "等價於 ``printf(\"%ld\")``. [1]_" + +#: ../../c-api/bytes.rst:81 +msgid "``%lu``" +msgstr "``%lu``" + +#: ../../c-api/bytes.rst:81 +msgid "unsigned long" +msgstr "unsigned long" + +#: ../../c-api/bytes.rst:81 +msgid "Equivalent to ``printf(\"%lu\")``. [1]_" +msgstr "等價於 ``printf(\"%lu\")``. [1]_" + +#: ../../c-api/bytes.rst:84 +msgid "``%zd``" +msgstr "``%zd``" + +#: ../../c-api/bytes.rst:84 +msgid ":c:type:` Py_ssize_t`" +msgstr ":c:type:` Py_ssize_t`" + +#: ../../c-api/bytes.rst:84 +msgid "Equivalent to ``printf(\"%zd\")``. [1]_" +msgstr "等價於 ``printf(\"%zd\")``. [1]_" + +#: ../../c-api/bytes.rst:87 +msgid "``%zu``" +msgstr "``%zu``" + +#: ../../c-api/bytes.rst:87 +msgid "size_t" +msgstr "size_t" + +#: ../../c-api/bytes.rst:87 +msgid "Equivalent to ``printf(\"%zu\")``. [1]_" +msgstr "等價於 ``printf(\"%zu\")``. [1]_" + +#: ../../c-api/bytes.rst:90 +msgid "``%i``" +msgstr "``%i``" + +#: ../../c-api/bytes.rst:90 +msgid "Equivalent to ``printf(\"%i\")``. [1]_" +msgstr "等價於 ``printf(\"%i\")``. [1]_" + +#: ../../c-api/bytes.rst:93 +msgid "``%x``" +msgstr "``%x``" + +#: ../../c-api/bytes.rst:93 +msgid "Equivalent to ``printf(\"%x\")``. [1]_" +msgstr "等價於 ``printf(\"%x\")``. [1]_" + +#: ../../c-api/bytes.rst:96 +msgid "``%s``" +msgstr "``%s``" + +#: ../../c-api/bytes.rst:96 +msgid "const char\\*" +msgstr "const char\\*" + +#: ../../c-api/bytes.rst:96 +msgid "A null-terminated C character array." +msgstr "" + +#: ../../c-api/bytes.rst:99 +msgid "``%p``" +msgstr "``%p``" + +#: ../../c-api/bytes.rst:99 +msgid "const void\\*" +msgstr "const void\\*" + +#: ../../c-api/bytes.rst:99 +msgid "" +"The hex representation of a C pointer. Mostly equivalent to " +"``printf(\"%p\")`` except that it is guaranteed to start with the literal " +"``0x`` regardless of what the platform's ``printf`` yields." +msgstr "" + +#: ../../c-api/bytes.rst:108 +msgid "" +"An unrecognized format character causes all the rest of the format string to " +"be copied as-is to the result object, and any extra arguments discarded." +msgstr "" + +#: ../../c-api/bytes.rst:111 +msgid "" +"For integer specifiers (d, u, ld, lu, zd, zu, i, x): the 0-conversion flag " +"has effect even when a precision is given." +msgstr "" + +#: ../../c-api/bytes.rst:117 +msgid "" +"Identical to :c:func:`PyBytes_FromFormat` except that it takes exactly two " +"arguments." +msgstr "" + +#: ../../c-api/bytes.rst:123 +msgid "" +"Return the bytes representation of object *o* that implements the buffer " +"protocol." +msgstr "" + +#: ../../c-api/bytes.rst:129 +msgid "Return the length of the bytes in bytes object *o*." +msgstr "" + +#: ../../c-api/bytes.rst:134 +msgid "Similar to :c:func:`PyBytes_Size`, but without error checking." +msgstr "和 :c:func:`PyBytes_Size` 類似，但不進行錯誤檢查。" + +#: ../../c-api/bytes.rst:139 +msgid "" +"Return a pointer to the contents of *o*. The pointer refers to the internal " +"buffer of *o*, which consists of ``len(o) + 1`` bytes. The last byte in the " +"buffer is always null, regardless of whether there are any other null " +"bytes. The data must not be modified in any way, unless the object was just " +"created using ``PyBytes_FromStringAndSize(NULL, size)``. It must not be " +"deallocated. If *o* is not a bytes object at all, :c:func:" +"`PyBytes_AsString` returns ``NULL`` and raises :exc:`TypeError`." +msgstr "" + +#: ../../c-api/bytes.rst:151 +msgid "Similar to :c:func:`PyBytes_AsString`, but without error checking." +msgstr "和 :c:func:`PyBytes_AsString` 類似，但不進行錯誤檢查。" + +#: ../../c-api/bytes.rst:156 +msgid "" +"Return the null-terminated contents of the object *obj* through the output " +"variables *buffer* and *length*. Returns ``0`` on success." +msgstr "" + +#: ../../c-api/bytes.rst:160 +msgid "" +"If *length* is ``NULL``, the bytes object may not contain embedded null " +"bytes; if it does, the function returns ``-1`` and a :exc:`ValueError` is " +"raised." +msgstr "" + +#: ../../c-api/bytes.rst:164 +msgid "" +"The buffer refers to an internal buffer of *obj*, which includes an " +"additional null byte at the end (not counted in *length*). The data must " +"not be modified in any way, unless the object was just created using " +"``PyBytes_FromStringAndSize(NULL, size)``. It must not be deallocated. If " +"*obj* is not a bytes object at all, :c:func:`PyBytes_AsStringAndSize` " +"returns ``-1`` and raises :exc:`TypeError`." +msgstr "" + +#: ../../c-api/bytes.rst:171 +msgid "" +"Previously, :exc:`TypeError` was raised when embedded null bytes were " +"encountered in the bytes object." +msgstr "" + +#: ../../c-api/bytes.rst:178 +msgid "" +"Create a new bytes object in *\\*bytes* containing the contents of *newpart* " +"appended to *bytes*; the caller will own the new reference. The reference " +"to the old value of *bytes* will be stolen. If the new object cannot be " +"created, the old reference to *bytes* will still be discarded and the value " +"of *\\*bytes* will be set to ``NULL``; the appropriate exception will be set." +msgstr "" + +#: ../../c-api/bytes.rst:187 +msgid "" +"Create a new bytes object in *\\*bytes* containing the contents of *newpart* " +"appended to *bytes*. This version releases the :term:`strong reference` to " +"*newpart* (i.e. decrements its reference count)." +msgstr "" + +#: ../../c-api/bytes.rst:194 +msgid "Similar to ``sep.join(iterable)`` in Python." +msgstr "類似 Python 中的 ``sep.join(iterable)``。" + +#: ../../c-api/bytes.rst:196 +msgid "" +"*sep* must be Python :class:`bytes` object. (Note that :c:func:" +"`PyUnicode_Join` accepts ``NULL`` separator and treats it as a space, " +"whereas :c:func:`PyBytes_Join` doesn't accept ``NULL`` separator.)" +msgstr "" + +#: ../../c-api/bytes.rst:201 +msgid "" +"*iterable* must be an iterable object yielding objects that implement the :" +"ref:`buffer protocol `." +msgstr "" + +#: ../../c-api/bytes.rst:204 +msgid "" +"On success, return a new :class:`bytes` object. On error, set an exception " +"and return ``NULL``." +msgstr "" + +#: ../../c-api/bytes.rst:212 +msgid "" +"Resize a bytes object. *newsize* will be the new length of the bytes object. " +"You can think of it as creating a new bytes object and destroying the old " +"one, only more efficiently. Pass the address of an existing bytes object as " +"an lvalue (it may be written into), and the new size desired. On success, " +"*\\*bytes* holds the resized bytes object and ``0`` is returned; the address " +"in *\\*bytes* may differ from its input value. If the reallocation fails, " +"the original bytes object at *\\*bytes* is deallocated, *\\*bytes* is set to " +"``NULL``, :exc:`MemoryError` is set, and ``-1`` is returned." +msgstr "" + +#: ../../c-api/bytes.rst:226 +msgid "" +"Get the string representation of *bytes*. This function is currently used to " +"implement :meth:`!bytes.__repr__` in Python." +msgstr "" + +#: ../../c-api/bytes.rst:229 +msgid "" +"This function does not do type checking; it is undefined behavior to pass " +"*bytes* as a non-bytes object or ``NULL``." +msgstr "" + +#: ../../c-api/bytes.rst:232 +msgid "" +"If *smartquotes* is true, the representation will use a double-quoted string " +"instead of single-quoted string when single-quotes are present in *bytes*. " +"For example, the byte string ``'Python'`` would be represented as " +"``b\"'Python'\"`` when *smartquotes* is true, or ``b'\\'Python\\''`` when it " +"is false." +msgstr "" + +#: ../../c-api/bytes.rst:238 +msgid "" +"On success, this function returns a :term:`strong reference` to a :class:" +"`str` object containing the representation. On failure, this returns " +"``NULL`` with an exception set." +msgstr "" + +#: ../../c-api/bytes.rst:245 +msgid "" +"Unescape a backslash-escaped string *s*. *s* must not be ``NULL``. *len* " +"must be the size of *s*." +msgstr "" + +#: ../../c-api/bytes.rst:248 +msgid "" +"*errors* must be one of ``\"strict\"``, ``\"replace\"``, or ``\"ignore\"``. " +"If *errors* is ``NULL``, then ``\"strict\"`` is used by default." +msgstr "" + +#: ../../c-api/bytes.rst:251 +msgid "" +"On success, this function returns a :term:`strong reference` to a Python :" +"class:`bytes` object containing the unescaped string. On failure, this " +"function returns ``NULL`` with an exception set." +msgstr "" + +#: ../../c-api/bytes.rst:255 +msgid "*unicode* and *recode_encoding* are now unused." +msgstr "" + +#: ../../c-api/bytes.rst:11 +msgid "object" +msgstr "object（物件）" + +#: ../../c-api/bytes.rst:11 +msgid "bytes" +msgstr "bytes（位元組）" diff --git a/c-api/call.po b/c-api/call.po index deda7d818b..4aafeeef27 100644 --- a/c-api/call.po +++ b/c-api/call.po @@ -1,696 +1,696 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Matt Wang , 2022 -# -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-09-23 07:52+0800\n" -"PO-Revision-Date: 2022-10-16 03:20+0800\n" -"Last-Translator: Matt Wang \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" -"X-Generator: Poedit 3.1.1\n" - -#: ../../c-api/call.rst:6 -msgid "Call Protocol" -msgstr "呼叫協定 (Call Protocol)" - -#: ../../c-api/call.rst:8 -msgid "" -"CPython supports two different calling protocols: *tp_call* and vectorcall." -msgstr "CPython 支援兩種不同的呼叫協定：*tp_call* 和 vectorcall（向量呼叫）。" - -#: ../../c-api/call.rst:12 -msgid "The *tp_call* Protocol" -msgstr "*tp_call* 協定" - -#: ../../c-api/call.rst:14 -msgid "" -"Instances of classes that set :c:member:`~PyTypeObject.tp_call` are " -"callable. The signature of the slot is::" -msgstr "" -"設定 :c:member:`~PyTypeObject.tp_call` 的類別之實例都是可呼叫的。該擴充槽 " -"(slot) 的簽章為： ::" - -#: ../../c-api/call.rst:17 -msgid "" -"PyObject *tp_call(PyObject *callable, PyObject *args, PyObject *kwargs);" -msgstr "" -"PyObject *tp_call(PyObject *callable, PyObject *args, PyObject *kwargs);" - -#: ../../c-api/call.rst:19 -msgid "" -"A call is made using a tuple for the positional arguments and a dict for the " -"keyword arguments, similarly to ``callable(*args, **kwargs)`` in Python " -"code. *args* must be non-NULL (use an empty tuple if there are no arguments) " -"but *kwargs* may be *NULL* if there are no keyword arguments." -msgstr "" -"要達成一個呼叫會使用一個 tuple（元組）表示位置引數、一個 dict 表示關鍵字引" -"數，類似於 Python 程式碼中的 ``callable(*args, **kwargs)``。*args* 必須不為 " -"NULL（如果沒有引數，會使用一個空 tuple），但如果沒有關鍵字引數，*kwargs* 可以" -"是 *NULL*。" - -#: ../../c-api/call.rst:25 -msgid "" -"This convention is not only used by *tp_call*: :c:member:`~PyTypeObject." -"tp_new` and :c:member:`~PyTypeObject.tp_init` also pass arguments this way." -msgstr "" -"這個慣例不僅會被 *tp_call* 使用，:c:member:`~PyTypeObject.tp_new` 和 :c:" -"member:`~PyTypeObject.tp_init` 也這樣傳遞引數。" - -#: ../../c-api/call.rst:29 -msgid "" -"To call an object, use :c:func:`PyObject_Call` or another :ref:`call API " -"`." -msgstr "" -"使用 :c:func:`PyObject_Call` 或其他\\ :ref:`呼叫 API ` 來呼叫一個" -"物件。" - -#: ../../c-api/call.rst:36 -msgid "The Vectorcall Protocol" -msgstr "Vectorcall 協定" - -#: ../../c-api/call.rst:40 -msgid "" -"The vectorcall protocol was introduced in :pep:`590` as an additional " -"protocol for making calls more efficient." -msgstr "" -"Vectorcall 協定是在 :pep:`590` 被引入的，它是使函式呼叫更加有效率的附加協定。" - -#: ../../c-api/call.rst:43 -msgid "" -"As rule of thumb, CPython will prefer the vectorcall for internal calls if " -"the callable supports it. However, this is not a hard rule. Additionally, " -"some third-party extensions use *tp_call* directly (rather than using :c:" -"func:`PyObject_Call`). Therefore, a class supporting vectorcall must also " -"implement :c:member:`~PyTypeObject.tp_call`. Moreover, the callable must " -"behave the same regardless of which protocol is used. The recommended way to " -"achieve this is by setting :c:member:`~PyTypeObject.tp_call` to :c:func:" -"`PyVectorcall_Call`. This bears repeating:" -msgstr "" -"經驗法則上，如果可呼叫物件有支援，CPython 於內部呼叫中會更傾向使用 " -"vectorcall。然而，這並不是一個硬性規定。此外，有些第三方擴充套件會直接使用 " -"*tp_call*\\ （而不是使用 :c:func:`PyObject_Call`）。因此，一個支援 " -"vectorcall 的類別也必須實作 :c:member:`~PyTypeObject.tp_call`。此外，無論使用" -"哪種協定，可呼叫物件的行為都必須是相同的。要達成這個目的的推薦做法是將 :c:" -"member:`~PyTypeObject.tp_call` 設定為 :c:func:`PyVectorcall_Call`。這值得一再" -"提醒：" - -#: ../../c-api/call.rst:57 -msgid "" -"A class supporting vectorcall **must** also implement :c:member:" -"`~PyTypeObject.tp_call` with the same semantics." -msgstr "" -"一個支援 vectorcall 的類別\\ **必須**\\ 也實作具有相同語義的 :c:member:" -"`~PyTypeObject.tp_call`。" - -#: ../../c-api/call.rst:62 -msgid "" -"The :c:macro:`Py_TPFLAGS_HAVE_VECTORCALL` flag is now removed from a class " -"when the class's :py:meth:`~object.__call__` method is reassigned. (This " -"internally sets :c:member:`~PyTypeObject.tp_call` only, and thus may make it " -"behave differently than the vectorcall function.) In earlier Python " -"versions, vectorcall should only be used with :c:macro:`immutable " -"` or static types." -msgstr "" -"當一個類別的 :py:meth:`~object.__call__` 方法被重新賦值時，:c:macro:" -"`Py_TPFLAGS_HAVE_VECTORCALL` 旗標現在會被移除。（這會在內部設定 :c:member:" -"`~PyTypeObject.tp_call`，因此可能會使它與 vectorcall 函式有不同的行為。）" -"在較早的 Python 版本中，vectorcall 應該只與 :c:macro:" -"`immutable ` 或靜態型別一起使用。" - -#: ../../c-api/call.rst:69 -msgid "" -"A class should not implement vectorcall if that would be slower than " -"*tp_call*. For example, if the callee needs to convert the arguments to an " -"args tuple and kwargs dict anyway, then there is no point in implementing " -"vectorcall." -msgstr "" -"如果一個類別的 vectorcall 比 *tp_call* 慢，就不應該實作 vectorcall。例如，如" -"果被呼叫者需要將引數轉換為 args tuple（引數元組）和 kwargs dict（關鍵字引數字" -"典），那麼實作 vectorcall 就沒有意義。" - -#: ../../c-api/call.rst:74 -msgid "" -"Classes can implement the vectorcall protocol by enabling the :c:macro:" -"`Py_TPFLAGS_HAVE_VECTORCALL` flag and setting :c:member:`~PyTypeObject." -"tp_vectorcall_offset` to the offset inside the object structure where a " -"*vectorcallfunc* appears. This is a pointer to a function with the following " -"signature:" -msgstr "" -"類別可以透過啟用 :c:macro:`Py_TPFLAGS_HAVE_VECTORCALL` 旗標並將 :c:member:" -"`~PyTypeObject.tp_vectorcall_offset` 設定為物件結構中有出現 *vectorcallfunc* " -"的 offset 來實作 vectorcall 協定。這是一個指向具有以下簽章之函式的指標：" - -#: ../../c-api/call.rst:82 -msgid "*callable* is the object being called." -msgstr "*callable* 是指被呼叫的物件。" - -#: ../../c-api/call.rst:83 -msgid "" -"*args* is a C array consisting of the positional arguments followed by the" -msgstr "*args* 是一個 C 語言陣列 (array)，包含位置引數與後面" - -#: ../../c-api/call.rst:84 -msgid "" -"values of the keyword arguments. This can be *NULL* if there are no " -"arguments." -msgstr "關鍵字引數的值。如果沒有引數，這個值可以是 *NULL*。" - -#: ../../c-api/call.rst:86 -msgid "*nargsf* is the number of positional arguments plus possibly the" -msgstr "*nargsf* 是位置引數的數量加上可能會有的" - -#: ../../c-api/call.rst:87 -msgid "" -":c:macro:`PY_VECTORCALL_ARGUMENTS_OFFSET` flag. To get the actual number of " -"positional arguments from *nargsf*, use :c:func:`PyVectorcall_NARGS`." -msgstr "" -":c:macro:`PY_VECTORCALL_ARGUMENTS_OFFSET` 旗標。如果要從 *nargsf* 獲得實際的" -"位置引數數量，請使用 :c:func:`PyVectorcall_NARGS`。" - -#: ../../c-api/call.rst:90 -msgid "*kwnames* is a tuple containing the names of the keyword arguments;" -msgstr "*kwnames* 是一個包含所有關鍵字引數名稱的 tuple；" - -#: ../../c-api/call.rst:91 -msgid "" -"in other words, the keys of the kwargs dict. These names must be strings " -"(instances of ``str`` or a subclass) and they must be unique. If there are " -"no keyword arguments, then *kwnames* can instead be *NULL*." -msgstr "" -"換句話說，就是 kwargs 字典的鍵。這些名字必須是字串（``str`` 或其子類別的實" -"例)，並且它們必須是不重複的。如果沒有關鍵字引數，那麼 *kwnames* 可以用 " -"*NULL* 代替。" - -#: ../../c-api/call.rst:98 -msgid "" -"If this flag is set in a vectorcall *nargsf* argument, the callee is allowed " -"to temporarily change ``args[-1]``. In other words, *args* points to " -"argument 1 (not 0) in the allocated vector. The callee must restore the " -"value of ``args[-1]`` before returning." -msgstr "" -"如果在 vectorcall 的 *nargsf* 引數中設定了此旗標，則允許被呼叫者臨時更改 " -"``args[-1]`` 的值。換句話說，*args* 指向向量中的引數 1（不是 0）。被呼叫方必" -"須在回傳之前還原 ``args[-1]`` 的值。" - -#: ../../c-api/call.rst:103 -msgid "" -"For :c:func:`PyObject_VectorcallMethod`, this flag means instead that " -"``args[0]`` may be changed." -msgstr "" -"對於 :c:func:`PyObject_VectorcallMethod`，這個旗標的改變意味著可能是 " -"``args[0]`` 被改變。" - -#: ../../c-api/call.rst:106 -msgid "" -"Whenever they can do so cheaply (without additional allocation), callers are " -"encouraged to use :c:macro:`PY_VECTORCALL_ARGUMENTS_OFFSET`. Doing so will " -"allow callables such as bound methods to make their onward calls (which " -"include a prepended *self* argument) very efficiently." -msgstr "" -"當可以以幾乎無代價的方式（無需佔據額外的記憶體）來達成，那麼會推薦呼叫者使" -"用 :c:macro:`PY_VECTORCALL_ARGUMENTS_OFFSET`。這樣做會讓如 bound method（繫結" -"方法）之類的可呼叫函式非常有效地繼續向前呼叫（這類函式包含一個在首位的 " -"*self* 引數）。" - -#: ../../c-api/call.rst:113 -msgid "" -"To call an object that implements vectorcall, use a :ref:`call API ` function as with any other callable. :c:func:`PyObject_Vectorcall` " -"will usually be most efficient." -msgstr "" -"要呼叫一個實作了 vectorcall 的物件，請就像其他可呼叫物件一樣使用\\ :ref:`呼" -"叫 API` 中的函式。:c:func:`PyObject_Vectorcall` 通常是最有效率的。" - -#: ../../c-api/call.rst:119 -msgid "Recursion Control" -msgstr "遞迴控制" - -#: ../../c-api/call.rst:121 -msgid "" -"When using *tp_call*, callees do not need to worry about :ref:`recursion " -"`: CPython uses :c:func:`Py_EnterRecursiveCall` and :c:func:" -"`Py_LeaveRecursiveCall` for calls made using *tp_call*." -msgstr "" -"在使用 *tp_call* 時，被呼叫者不必擔心\\ :ref:`遞迴 `：CPython 對於" -"使用 *tp_call* 的呼叫會使用 :c:func:`Py_EnterRecursiveCall` 和 :c:func:" -"`Py_LeaveRecursiveCall`。" - -#: ../../c-api/call.rst:126 -msgid "" -"For efficiency, this is not the case for calls done using vectorcall: the " -"callee should use *Py_EnterRecursiveCall* and *Py_LeaveRecursiveCall* if " -"needed." -msgstr "" -"為保證效率，這不適用於使用 vectorcall 的呼叫：被呼叫方在需要時應當使用 " -"*Py_EnterRecursiveCall* 和 *Py_LeaveRecursiveCall*。" - -#: ../../c-api/call.rst:132 -msgid "Vectorcall Support API" -msgstr "Vectorcall 支援 API" - -#: ../../c-api/call.rst:136 -msgid "" -"Given a vectorcall *nargsf* argument, return the actual number of arguments. " -"Currently equivalent to::" -msgstr "給定一個 vectorcall *nargsf* 引數，回傳引數的實際數量。目前等同於： ::" - -#: ../../c-api/call.rst:140 -msgid "(Py_ssize_t)(nargsf & ~PY_VECTORCALL_ARGUMENTS_OFFSET)" -msgstr "(Py_ssize_t)(nargsf & ~PY_VECTORCALL_ARGUMENTS_OFFSET)" - -#: ../../c-api/call.rst:142 -msgid "" -"However, the function ``PyVectorcall_NARGS`` should be used to allow for " -"future extensions." -msgstr "然而，應使用 ``PyVectorcall_NARGS`` 函式以便將來需要擴充。" - -#: ../../c-api/call.rst:149 -msgid "" -"If *op* does not support the vectorcall protocol (either because the type " -"does not or because the specific instance does not), return *NULL*. " -"Otherwise, return the vectorcall function pointer stored in *op*. This " -"function never raises an exception." -msgstr "" -"如果 *op* 不支援 vectorcall 協定（因為型別不支援或特定實例不支援），就回傳 " -"*NULL*。否則，回傳儲存在 *op* 中的 vectorcall 函式指標。這個函式不會引發例" -"外。" - -#: ../../c-api/call.rst:154 -msgid "" -"This is mostly useful to check whether or not *op* supports vectorcall, " -"which can be done by checking ``PyVectorcall_Function(op) != NULL``." -msgstr "" -"這大多在檢查 *op* 是否支援 vectorcall 時能派上用場，可以透過檢查 " -"``PyVectorcall_Function(op) != NULL`` 來達成。" - -#: ../../c-api/call.rst:161 -msgid "" -"Call *callable*'s :c:type:`vectorcallfunc` with positional and keyword " -"arguments given in a tuple and dict, respectively." -msgstr "" -"呼叫 *callable* 的 :c:type:`vectorcallfunc`，其位置引數和關鍵字引數分別以 " -"tuple 和 dict 格式給定。" - -#: ../../c-api/call.rst:164 -msgid "" -"This is a specialized function, intended to be put in the :c:member:" -"`~PyTypeObject.tp_call` slot or be used in an implementation of ``tp_call``. " -"It does not check the :c:macro:`Py_TPFLAGS_HAVE_VECTORCALL` flag and it does " -"not fall back to ``tp_call``." -msgstr "" -"這是一個專門函式，其目的是被放入 :c:member:`~PyTypeObject.tp_call` 擴充槽或是" -"用於 ``tp_call`` 的實作。它不會檢查 :c:macro:`Py_TPFLAGS_HAVE_VECTORCALL` 旗" -"標並且它不會退回 (fall back) 使用 ``tp_call``。" - -#: ../../c-api/call.rst:175 -msgid "Object Calling API" -msgstr "物件呼叫 API" - -#: ../../c-api/call.rst:177 -msgid "" -"Various functions are available for calling a Python object. Each converts " -"its arguments to a convention supported by the called object – either " -"*tp_call* or vectorcall. In order to do as little conversion as possible, " -"pick one that best fits the format of data you have available." -msgstr "" -"有多個函式可被用來呼叫 Python 物件。各個函式會將其引數轉換為被呼叫物件所支援" -"的慣用形式 – 可以是 *tp_call* 或 vectorcall。為了儘可能減少轉換的進行，請選擇" -"一個適合你所擁有資料格式的函式。" - -#: ../../c-api/call.rst:183 -msgid "" -"The following table summarizes the available functions; please see " -"individual documentation for details." -msgstr "下表總結了可用的函式；請參閱各個說明文件以瞭解詳情。" - -#: ../../c-api/call.rst:187 -msgid "Function" -msgstr "函式" - -#: ../../c-api/call.rst:187 -msgid "callable" -msgstr "callable" - -#: ../../c-api/call.rst:187 -msgid "args" -msgstr "args" - -#: ../../c-api/call.rst:187 -msgid "kwargs" -msgstr "kwargs" - -#: ../../c-api/call.rst:189 -msgid ":c:func:`PyObject_Call`" -msgstr ":c:func:`PyObject_Call`" - -#: ../../c-api/call.rst:189 ../../c-api/call.rst:191 ../../c-api/call.rst:193 -#: ../../c-api/call.rst:195 ../../c-api/call.rst:197 ../../c-api/call.rst:201 -#: ../../c-api/call.rst:209 ../../c-api/call.rst:211 -msgid "``PyObject *``" -msgstr "``PyObject *``" - -#: ../../c-api/call.rst:189 -msgid "tuple" -msgstr "tuple" - -#: ../../c-api/call.rst:189 ../../c-api/call.rst:211 -msgid "dict/``NULL``" -msgstr "dict/``NULL``" - -#: ../../c-api/call.rst:191 -msgid ":c:func:`PyObject_CallNoArgs`" -msgstr ":c:func:`PyObject_CallNoArgs`" - -#: ../../c-api/call.rst:191 ../../c-api/call.rst:193 ../../c-api/call.rst:195 -#: ../../c-api/call.rst:197 ../../c-api/call.rst:199 ../../c-api/call.rst:201 -#: ../../c-api/call.rst:203 ../../c-api/call.rst:205 ../../c-api/call.rst:207 -msgid "---" -msgstr "---" - -#: ../../c-api/call.rst:193 -msgid ":c:func:`PyObject_CallOneArg`" -msgstr ":c:func:`PyObject_CallOneArg`" - -#: ../../c-api/call.rst:193 ../../c-api/call.rst:207 -msgid "1 object" -msgstr "一個物件" - -#: ../../c-api/call.rst:195 -msgid ":c:func:`PyObject_CallObject`" -msgstr ":c:func:`PyObject_CallObject`" - -#: ../../c-api/call.rst:195 -msgid "tuple/``NULL``" -msgstr "tuple/``NULL``" - -#: ../../c-api/call.rst:197 -msgid ":c:func:`PyObject_CallFunction`" -msgstr ":c:func:`PyObject_CallFunction`" - -#: ../../c-api/call.rst:197 ../../c-api/call.rst:199 -msgid "format" -msgstr "format" - -#: ../../c-api/call.rst:199 -msgid ":c:func:`PyObject_CallMethod`" -msgstr ":c:func:`PyObject_CallMethod`" - -#: ../../c-api/call.rst:199 -msgid "obj + ``char*``" -msgstr "物件 + ``char*``" - -#: ../../c-api/call.rst:201 -msgid ":c:func:`PyObject_CallFunctionObjArgs`" -msgstr ":c:func:`PyObject_CallFunctionObjArgs`" - -#: ../../c-api/call.rst:201 ../../c-api/call.rst:203 -msgid "variadic" -msgstr "可變引數" - -#: ../../c-api/call.rst:203 -msgid ":c:func:`PyObject_CallMethodObjArgs`" -msgstr ":c:func:`PyObject_CallMethodObjArgs`" - -#: ../../c-api/call.rst:203 ../../c-api/call.rst:205 ../../c-api/call.rst:207 -msgid "obj + name" -msgstr "物件 + 名稱" - -#: ../../c-api/call.rst:205 -msgid ":c:func:`PyObject_CallMethodNoArgs`" -msgstr ":c:func:`PyObject_CallMethodNoArgs`" - -#: ../../c-api/call.rst:207 -msgid ":c:func:`PyObject_CallMethodOneArg`" -msgstr ":c:func:`PyObject_CallMethodOneArg`" - -#: ../../c-api/call.rst:209 -msgid ":c:func:`PyObject_Vectorcall`" -msgstr ":c:func:`PyObject_Vectorcall`" - -#: ../../c-api/call.rst:209 ../../c-api/call.rst:211 ../../c-api/call.rst:213 -msgid "vectorcall" -msgstr "vectorcall" - -#: ../../c-api/call.rst:211 -msgid ":c:func:`PyObject_VectorcallDict`" -msgstr ":c:func:`PyObject_VectorcallDict`" - -#: ../../c-api/call.rst:213 -msgid ":c:func:`PyObject_VectorcallMethod`" -msgstr ":c:func:`PyObject_VectorcallMethod`" - -#: ../../c-api/call.rst:213 -msgid "arg + name" -msgstr "引數 + 名稱" - -#: ../../c-api/call.rst:219 -msgid "" -"Call a callable Python object *callable*, with arguments given by the tuple " -"*args*, and named arguments given by the dictionary *kwargs*." -msgstr "" -"呼叫一個可呼叫的 Python 物件 *callable*，附帶由 tuple *args* 所給定的引數及由" -"字典 *kwargs* 所給定的關鍵字引數。" - -#: ../../c-api/call.rst:222 -msgid "" -"*args* must not be *NULL*; use an empty tuple if no arguments are needed. If " -"no named arguments are needed, *kwargs* can be *NULL*." -msgstr "" -"*args* 必須不為 *NULL*；如果不需要引數，請使用一個空 tuple。如果不需要關鍵字" -"引數，則 *kwargs* 可以為 *NULL*。" - -#: ../../c-api/call.rst:225 ../../c-api/call.rst:237 ../../c-api/call.rst:248 -#: ../../c-api/call.rst:259 ../../c-api/call.rst:271 ../../c-api/call.rst:291 -#: ../../c-api/call.rst:310 ../../c-api/call.rst:324 ../../c-api/call.rst:333 -#: ../../c-api/call.rst:345 ../../c-api/call.rst:358 ../../c-api/call.rst:392 -msgid "" -"Return the result of the call on success, or raise an exception and return " -"*NULL* on failure." -msgstr "成功時回傳結果，或在失敗時引發一個例外並回傳 *NULL*。" - -#: ../../c-api/call.rst:228 -msgid "" -"This is the equivalent of the Python expression: ``callable(*args, " -"**kwargs)``." -msgstr "這等價於 Python 運算式 ``callable(*args, **kwargs)``。" - -#: ../../c-api/call.rst:234 -msgid "" -"Call a callable Python object *callable* without any arguments. It is the " -"most efficient way to call a callable Python object without any argument." -msgstr "" -"呼叫一個可呼叫的 Python 物件 *callable* 並不附帶任何引數。這是不帶引數呼叫 " -"Python 可呼叫物件的最有效方式。" - -#: ../../c-api/call.rst:245 -msgid "" -"Call a callable Python object *callable* with exactly 1 positional argument " -"*arg* and no keyword arguments." -msgstr "" -"呼叫一個可呼叫的 Python 物件 *callable* 並附帶正好一個位置引數 *arg* 而沒有關" -"鍵字引數。" - -#: ../../c-api/call.rst:256 -msgid "" -"Call a callable Python object *callable*, with arguments given by the tuple " -"*args*. If no arguments are needed, then *args* can be *NULL*." -msgstr "" -"呼叫一個可呼叫的 Python 物件 *callable*，附帶由 tuple *args* 所給定的引數。如" -"果不需要傳入引數，則 *args* 可以為 *NULL*。" - -#: ../../c-api/call.rst:262 ../../c-api/call.rst:274 -msgid "This is the equivalent of the Python expression: ``callable(*args)``." -msgstr "這等價於 Python 運算式 ``callable(*args)``。" - -#: ../../c-api/call.rst:267 -msgid "" -"Call a callable Python object *callable*, with a variable number of C " -"arguments. The C arguments are described using a :c:func:`Py_BuildValue` " -"style format string. The format can be *NULL*, indicating that no arguments " -"are provided." -msgstr "" -"呼叫一個可呼叫的 Python 物件 *callable*，附帶數量可變的 C 引數。這些 C 引數使" -"用 :c:func:`Py_BuildValue` 風格的格式字串來描述。格式可以為 *NULL*，表示沒有" -"提供任何引數。" - -#: ../../c-api/call.rst:276 -msgid "" -"Note that if you only pass :c:expr:`PyObject *` args, :c:func:" -"`PyObject_CallFunctionObjArgs` is a faster alternative." -msgstr "" -"注意，如果你只傳入 :c:expr:`PyObject *` 引數，則 :c:func:" -"`PyObject_CallFunctionObjArgs` 是另一個更快速的選擇。" - -#: ../../c-api/call.rst:279 -msgid "The type of *format* was changed from ``char *``." -msgstr "這個 *format* 的型別已從 ``char *`` 更改。" - -#: ../../c-api/call.rst:285 -msgid "" -"Call the method named *name* of object *obj* with a variable number of C " -"arguments. The C arguments are described by a :c:func:`Py_BuildValue` " -"format string that should produce a tuple." -msgstr "" -"呼叫 *obj* 物件中名為 *name* 的 method 並附帶數量可變的 C 引數。這些 C 引數" -"由 :c:func:`Py_BuildValue` 格式字串來描述，並應當生成一個 tuple。" - -#: ../../c-api/call.rst:289 -msgid "The format can be *NULL*, indicating that no arguments are provided." -msgstr "格式可以為 *NULL*，表示沒有提供任何引數。" - -#: ../../c-api/call.rst:294 -msgid "" -"This is the equivalent of the Python expression: ``obj.name(arg1, " -"arg2, ...)``." -msgstr "這等價於 Python 運算式 ``obj.name(arg1, arg2, ...)``。" - -#: ../../c-api/call.rst:297 -msgid "" -"Note that if you only pass :c:expr:`PyObject *` args, :c:func:" -"`PyObject_CallMethodObjArgs` is a faster alternative." -msgstr "" -"注意，如果你只傳入 :c:expr:`PyObject *` 引數，則 :c:func:" -"`PyObject_CallMethodObjArgs` 是另一個更快速的選擇。" - -#: ../../c-api/call.rst:300 -msgid "The types of *name* and *format* were changed from ``char *``." -msgstr "*name* 和 *format* 的型別已從 ``char *`` 更改。" - -#: ../../c-api/call.rst:306 -msgid "" -"Call a callable Python object *callable*, with a variable number of :c:expr:" -"`PyObject *` arguments. The arguments are provided as a variable number of " -"parameters followed by *NULL*." -msgstr "" -"呼叫一個可呼叫的 Python 物件 *callable*，附帶數量可變的 :c:expr:`PyObject *` " -"引數。這些引數是以位置在 *NULL* 後面、數量可變的參數來提供。" - -#: ../../c-api/call.rst:313 -msgid "" -"This is the equivalent of the Python expression: ``callable(arg1, " -"arg2, ...)``." -msgstr "這等價於 Python 運算式 ``callable(arg1, arg2, ...)``。" - -#: ../../c-api/call.rst:319 -msgid "" -"Call a method of the Python object *obj*, where the name of the method is " -"given as a Python string object in *name*. It is called with a variable " -"number of :c:expr:`PyObject *` arguments. The arguments are provided as a " -"variable number of parameters followed by *NULL*." -msgstr "" -"呼叫 Python 物件 *obj* 中的一個 method，其中 method 名稱由 *name* 中的 " -"Python 字串物件給定。被呼叫時會附帶數量可變的 :c:expr:`PyObject *` 引數。這些" -"引數是以位置在 *NULL* 後面、且數量可變的參數來提供。" - -#: ../../c-api/call.rst:330 -msgid "" -"Call a method of the Python object *obj* without arguments, where the name " -"of the method is given as a Python string object in *name*." -msgstr "" -"不附帶任何引數地呼叫 Python 物件 *obj* 中的一個 method，其中 method 名稱由 " -"*name* 中的 Python 字串物件給定。" - -#: ../../c-api/call.rst:341 -msgid "" -"Call a method of the Python object *obj* with a single positional argument " -"*arg*, where the name of the method is given as a Python string object in " -"*name*." -msgstr "" -"附帶一個位置引數 *arg* 地呼叫 Python 物件 *obj* 中的一個 method，其中 method " -"名稱由 *name* 中的 Python 字串物件給定。" - -#: ../../c-api/call.rst:353 -msgid "" -"Call a callable Python object *callable*. The arguments are the same as for :" -"c:type:`vectorcallfunc`. If *callable* supports vectorcall_, this directly " -"calls the vectorcall function stored in *callable*." -msgstr "" -"呼叫一個可呼叫的 Python 物件 *callable*。附帶引數與 :c:type:`vectorcallfunc` " -"的相同。如果 *callable* 支援 vectorcall_，則它會直接呼叫存放在 *callable* 中" -"的 vectorcall 函式。" - -#: ../../c-api/call.rst:365 -msgid "" -"Call *callable* with positional arguments passed exactly as in the " -"vectorcall_ protocol, but with keyword arguments passed as a dictionary " -"*kwdict*. The *args* array contains only the positional arguments." -msgstr "" -"附帶與在 vectorcall_ 協定中傳入的相同位置引數來呼叫 *callable*，但會加上以字" -"典 *kwdict* 格式傳入的關鍵字引數。*args* 陣列將只包含位置引數。" - -#: ../../c-api/call.rst:369 -msgid "" -"Regardless of which protocol is used internally, a conversion of arguments " -"needs to be done. Therefore, this function should only be used if the caller " -"already has a dictionary ready to use for the keyword arguments, but not a " -"tuple for the positional arguments." -msgstr "" -"無論內部使用了哪一種協定，都會需要進行引數的轉換。因此，此函式應該只有在呼叫" -"方已經擁有一個要作為關鍵字引數的字典、但沒有作為位置引數的 tuple 時才被使用。" - -#: ../../c-api/call.rst:379 -msgid "" -"Call a method using the vectorcall calling convention. The name of the " -"method is given as a Python string *name*. The object whose method is called " -"is *args[0]*, and the *args* array starting at *args[1]* represents the " -"arguments of the call. There must be at least one positional argument. " -"*nargsf* is the number of positional arguments including *args[0]*, plus :c:" -"macro:`PY_VECTORCALL_ARGUMENTS_OFFSET` if the value of ``args[0]`` may " -"temporarily be changed. Keyword arguments can be passed just like in :c:func:" -"`PyObject_Vectorcall`." -msgstr "" -"使用 vectorcall 呼叫慣例來呼叫一個 method。method 的名稱以 Python 字串 " -"*name* 的格式給定。被呼叫 method 的物件為 *args[0]*，而 *args* 陣列從 " -"*args[1]* 開始的部分則代表呼叫的引數。必須傳入至少一個位置引數。*nargsf* 為包" -"括 *args[0]* 在內的位置引數的數量，如果 ``args[0]`` 的值可能被臨時改變則要再" -"加上 :c:macro:`PY_VECTORCALL_ARGUMENTS_OFFSET`。關鍵字引數可以像在 :c:func:" -"`PyObject_Vectorcall` 中一樣被傳入。" - -#: ../../c-api/call.rst:388 -msgid "" -"If the object has the :c:macro:`Py_TPFLAGS_METHOD_DESCRIPTOR` feature, this " -"will call the unbound method object with the full *args* vector as arguments." -msgstr "" -"如果物件具有 :c:macro:`Py_TPFLAGS_METHOD_DESCRIPTOR` 特性，這將以完整的 " -"*args* 向量作為引數來呼叫 unbound method（未繫結方法）物件。" - -#: ../../c-api/call.rst:399 -msgid "Call Support API" -msgstr "呼叫支援 API" - -#: ../../c-api/call.rst:403 -msgid "" -"Determine if the object *o* is callable. Return ``1`` if the object is " -"callable and ``0`` otherwise. This function always succeeds." -msgstr "" -"判定物件 *o* 是否為可呼叫的。如果物件是可呼叫物件則回傳 ``1``，其他情況回傳 " -"``0``。這個函式不會呼叫失敗。" - -#~ msgid "" -#~ "In CPython 3.8, the vectorcall API and related functions were available " -#~ "provisionally under names with a leading underscore: " -#~ "``_PyObject_Vectorcall``, ``_Py_TPFLAGS_HAVE_VECTORCALL``, " -#~ "``_PyObject_VectorcallMethod``, ``_PyVectorcall_Function``, " -#~ "``_PyObject_CallOneArg``, ``_PyObject_CallMethodNoArgs``, " -#~ "``_PyObject_CallMethodOneArg``. Additionally, ``PyObject_VectorcallDict`` " -#~ "was available as ``_PyObject_FastCallDict``. The old names are still " -#~ "defined as aliases of the new, non-underscored names." -#~ msgstr "" -#~ "在 CPython 3.8 中，vectorcall API 和相關函式暫定以帶開頭底線的名稱提供：" -#~ "``_PyObject_Vectorcall``、``_Py_TPFLAGS_HAVE_VECTORCALL``、" -#~ "``_PyObject_VectorcallMethod``、``_PyVectorcall_Function``、" -#~ "``_PyObject_CallOneArg``、``_PyObject_CallMethodNoArgs``、" -#~ "``_PyObject_CallMethodOneArg``。此外，``PyObject_VectorcallDict`` 也以 " -#~ "``_PyObject_FastCallDict`` 名稱提供。這些舊名稱仍有被定義，做為不帶底線的" -#~ "新名稱的別名。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Matt Wang , 2022 +# +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-09-23 07:52+0800\n" +"PO-Revision-Date: 2022-10-16 03:20+0800\n" +"Last-Translator: Matt Wang \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" +"X-Generator: Poedit 3.1.1\n" + +#: ../../c-api/call.rst:6 +msgid "Call Protocol" +msgstr "呼叫協定 (Call Protocol)" + +#: ../../c-api/call.rst:8 +msgid "" +"CPython supports two different calling protocols: *tp_call* and vectorcall." +msgstr "CPython 支援兩種不同的呼叫協定：*tp_call* 和 vectorcall（向量呼叫）。" + +#: ../../c-api/call.rst:12 +msgid "The *tp_call* Protocol" +msgstr "*tp_call* 協定" + +#: ../../c-api/call.rst:14 +msgid "" +"Instances of classes that set :c:member:`~PyTypeObject.tp_call` are " +"callable. The signature of the slot is::" +msgstr "" +"設定 :c:member:`~PyTypeObject.tp_call` 的類別之實例都是可呼叫的。該擴充槽 " +"(slot) 的簽章為： ::" + +#: ../../c-api/call.rst:17 +msgid "" +"PyObject *tp_call(PyObject *callable, PyObject *args, PyObject *kwargs);" +msgstr "" +"PyObject *tp_call(PyObject *callable, PyObject *args, PyObject *kwargs);" + +#: ../../c-api/call.rst:19 +msgid "" +"A call is made using a tuple for the positional arguments and a dict for the " +"keyword arguments, similarly to ``callable(*args, **kwargs)`` in Python " +"code. *args* must be non-NULL (use an empty tuple if there are no arguments) " +"but *kwargs* may be *NULL* if there are no keyword arguments." +msgstr "" +"要達成一個呼叫會使用一個 tuple（元組）表示位置引數、一個 dict 表示關鍵字引" +"數，類似於 Python 程式碼中的 ``callable(*args, **kwargs)``。*args* 必須不為 " +"NULL（如果沒有引數，會使用一個空 tuple），但如果沒有關鍵字引數，*kwargs* 可以" +"是 *NULL*。" + +#: ../../c-api/call.rst:25 +msgid "" +"This convention is not only used by *tp_call*: :c:member:`~PyTypeObject." +"tp_new` and :c:member:`~PyTypeObject.tp_init` also pass arguments this way." +msgstr "" +"這個慣例不僅會被 *tp_call* 使用，:c:member:`~PyTypeObject.tp_new` 和 :c:" +"member:`~PyTypeObject.tp_init` 也這樣傳遞引數。" + +#: ../../c-api/call.rst:29 +msgid "" +"To call an object, use :c:func:`PyObject_Call` or another :ref:`call API " +"`." +msgstr "" +"使用 :c:func:`PyObject_Call` 或其他\\ :ref:`呼叫 API ` 來呼叫一個" +"物件。" + +#: ../../c-api/call.rst:36 +msgid "The Vectorcall Protocol" +msgstr "Vectorcall 協定" + +#: ../../c-api/call.rst:40 +msgid "" +"The vectorcall protocol was introduced in :pep:`590` as an additional " +"protocol for making calls more efficient." +msgstr "" +"Vectorcall 協定是在 :pep:`590` 被引入的，它是使函式呼叫更加有效率的附加協定。" + +#: ../../c-api/call.rst:43 +msgid "" +"As rule of thumb, CPython will prefer the vectorcall for internal calls if " +"the callable supports it. However, this is not a hard rule. Additionally, " +"some third-party extensions use *tp_call* directly (rather than using :c:" +"func:`PyObject_Call`). Therefore, a class supporting vectorcall must also " +"implement :c:member:`~PyTypeObject.tp_call`. Moreover, the callable must " +"behave the same regardless of which protocol is used. The recommended way to " +"achieve this is by setting :c:member:`~PyTypeObject.tp_call` to :c:func:" +"`PyVectorcall_Call`. This bears repeating:" +msgstr "" +"經驗法則上，如果可呼叫物件有支援，CPython 於內部呼叫中會更傾向使用 " +"vectorcall。然而，這並不是一個硬性規定。此外，有些第三方擴充套件會直接使用 " +"*tp_call*\\ （而不是使用 :c:func:`PyObject_Call`）。因此，一個支援 " +"vectorcall 的類別也必須實作 :c:member:`~PyTypeObject.tp_call`。此外，無論使用" +"哪種協定，可呼叫物件的行為都必須是相同的。要達成這個目的的推薦做法是將 :c:" +"member:`~PyTypeObject.tp_call` 設定為 :c:func:`PyVectorcall_Call`。這值得一再" +"提醒：" + +#: ../../c-api/call.rst:57 +msgid "" +"A class supporting vectorcall **must** also implement :c:member:" +"`~PyTypeObject.tp_call` with the same semantics." +msgstr "" +"一個支援 vectorcall 的類別\\ **必須**\\ 也實作具有相同語義的 :c:member:" +"`~PyTypeObject.tp_call`。" + +#: ../../c-api/call.rst:62 +msgid "" +"The :c:macro:`Py_TPFLAGS_HAVE_VECTORCALL` flag is now removed from a class " +"when the class's :py:meth:`~object.__call__` method is reassigned. (This " +"internally sets :c:member:`~PyTypeObject.tp_call` only, and thus may make it " +"behave differently than the vectorcall function.) In earlier Python " +"versions, vectorcall should only be used with :c:macro:`immutable " +"` or static types." +msgstr "" +"當一個類別的 :py:meth:`~object.__call__` 方法被重新賦值時，:c:macro:" +"`Py_TPFLAGS_HAVE_VECTORCALL` 旗標現在會被移除。（這會在內部設定 :c:member:" +"`~PyTypeObject.tp_call`，因此可能會使它與 vectorcall 函式有不同的行為。）" +"在較早的 Python 版本中，vectorcall 應該只與 :c:macro:" +"`immutable ` 或靜態型別一起使用。" + +#: ../../c-api/call.rst:69 +msgid "" +"A class should not implement vectorcall if that would be slower than " +"*tp_call*. For example, if the callee needs to convert the arguments to an " +"args tuple and kwargs dict anyway, then there is no point in implementing " +"vectorcall." +msgstr "" +"如果一個類別的 vectorcall 比 *tp_call* 慢，就不應該實作 vectorcall。例如，如" +"果被呼叫者需要將引數轉換為 args tuple（引數元組）和 kwargs dict（關鍵字引數字" +"典），那麼實作 vectorcall 就沒有意義。" + +#: ../../c-api/call.rst:74 +msgid "" +"Classes can implement the vectorcall protocol by enabling the :c:macro:" +"`Py_TPFLAGS_HAVE_VECTORCALL` flag and setting :c:member:`~PyTypeObject." +"tp_vectorcall_offset` to the offset inside the object structure where a " +"*vectorcallfunc* appears. This is a pointer to a function with the following " +"signature:" +msgstr "" +"類別可以透過啟用 :c:macro:`Py_TPFLAGS_HAVE_VECTORCALL` 旗標並將 :c:member:" +"`~PyTypeObject.tp_vectorcall_offset` 設定為物件結構中有出現 *vectorcallfunc* " +"的 offset 來實作 vectorcall 協定。這是一個指向具有以下簽章之函式的指標：" + +#: ../../c-api/call.rst:82 +msgid "*callable* is the object being called." +msgstr "*callable* 是指被呼叫的物件。" + +#: ../../c-api/call.rst:83 +msgid "" +"*args* is a C array consisting of the positional arguments followed by the" +msgstr "*args* 是一個 C 語言陣列 (array)，包含位置引數與後面" + +#: ../../c-api/call.rst:84 +msgid "" +"values of the keyword arguments. This can be *NULL* if there are no " +"arguments." +msgstr "關鍵字引數的值。如果沒有引數，這個值可以是 *NULL*。" + +#: ../../c-api/call.rst:86 +msgid "*nargsf* is the number of positional arguments plus possibly the" +msgstr "*nargsf* 是位置引數的數量加上可能會有的" + +#: ../../c-api/call.rst:87 +msgid "" +":c:macro:`PY_VECTORCALL_ARGUMENTS_OFFSET` flag. To get the actual number of " +"positional arguments from *nargsf*, use :c:func:`PyVectorcall_NARGS`." +msgstr "" +":c:macro:`PY_VECTORCALL_ARGUMENTS_OFFSET` 旗標。如果要從 *nargsf* 獲得實際的" +"位置引數數量，請使用 :c:func:`PyVectorcall_NARGS`。" + +#: ../../c-api/call.rst:90 +msgid "*kwnames* is a tuple containing the names of the keyword arguments;" +msgstr "*kwnames* 是一個包含所有關鍵字引數名稱的 tuple；" + +#: ../../c-api/call.rst:91 +msgid "" +"in other words, the keys of the kwargs dict. These names must be strings " +"(instances of ``str`` or a subclass) and they must be unique. If there are " +"no keyword arguments, then *kwnames* can instead be *NULL*." +msgstr "" +"換句話說，就是 kwargs 字典的鍵。這些名字必須是字串（``str`` 或其子類別的實" +"例)，並且它們必須是不重複的。如果沒有關鍵字引數，那麼 *kwnames* 可以用 " +"*NULL* 代替。" + +#: ../../c-api/call.rst:98 +msgid "" +"If this flag is set in a vectorcall *nargsf* argument, the callee is allowed " +"to temporarily change ``args[-1]``. In other words, *args* points to " +"argument 1 (not 0) in the allocated vector. The callee must restore the " +"value of ``args[-1]`` before returning." +msgstr "" +"如果在 vectorcall 的 *nargsf* 引數中設定了此旗標，則允許被呼叫者臨時更改 " +"``args[-1]`` 的值。換句話說，*args* 指向向量中的引數 1（不是 0）。被呼叫方必" +"須在回傳之前還原 ``args[-1]`` 的值。" + +#: ../../c-api/call.rst:103 +msgid "" +"For :c:func:`PyObject_VectorcallMethod`, this flag means instead that " +"``args[0]`` may be changed." +msgstr "" +"對於 :c:func:`PyObject_VectorcallMethod`，這個旗標的改變意味著可能是 " +"``args[0]`` 被改變。" + +#: ../../c-api/call.rst:106 +msgid "" +"Whenever they can do so cheaply (without additional allocation), callers are " +"encouraged to use :c:macro:`PY_VECTORCALL_ARGUMENTS_OFFSET`. Doing so will " +"allow callables such as bound methods to make their onward calls (which " +"include a prepended *self* argument) very efficiently." +msgstr "" +"當可以以幾乎無代價的方式（無需佔據額外的記憶體）來達成，那麼會推薦呼叫者使" +"用 :c:macro:`PY_VECTORCALL_ARGUMENTS_OFFSET`。這樣做會讓如 bound method（繫結" +"方法）之類的可呼叫函式非常有效地繼續向前呼叫（這類函式包含一個在首位的 " +"*self* 引數）。" + +#: ../../c-api/call.rst:113 +msgid "" +"To call an object that implements vectorcall, use a :ref:`call API ` function as with any other callable. :c:func:`PyObject_Vectorcall` " +"will usually be most efficient." +msgstr "" +"要呼叫一個實作了 vectorcall 的物件，請就像其他可呼叫物件一樣使用\\ :ref:`呼" +"叫 API` 中的函式。:c:func:`PyObject_Vectorcall` 通常是最有效率的。" + +#: ../../c-api/call.rst:119 +msgid "Recursion Control" +msgstr "遞迴控制" + +#: ../../c-api/call.rst:121 +msgid "" +"When using *tp_call*, callees do not need to worry about :ref:`recursion " +"`: CPython uses :c:func:`Py_EnterRecursiveCall` and :c:func:" +"`Py_LeaveRecursiveCall` for calls made using *tp_call*." +msgstr "" +"在使用 *tp_call* 時，被呼叫者不必擔心\\ :ref:`遞迴 `：CPython 對於" +"使用 *tp_call* 的呼叫會使用 :c:func:`Py_EnterRecursiveCall` 和 :c:func:" +"`Py_LeaveRecursiveCall`。" + +#: ../../c-api/call.rst:126 +msgid "" +"For efficiency, this is not the case for calls done using vectorcall: the " +"callee should use *Py_EnterRecursiveCall* and *Py_LeaveRecursiveCall* if " +"needed." +msgstr "" +"為保證效率，這不適用於使用 vectorcall 的呼叫：被呼叫方在需要時應當使用 " +"*Py_EnterRecursiveCall* 和 *Py_LeaveRecursiveCall*。" + +#: ../../c-api/call.rst:132 +msgid "Vectorcall Support API" +msgstr "Vectorcall 支援 API" + +#: ../../c-api/call.rst:136 +msgid "" +"Given a vectorcall *nargsf* argument, return the actual number of arguments. " +"Currently equivalent to::" +msgstr "給定一個 vectorcall *nargsf* 引數，回傳引數的實際數量。目前等同於： ::" + +#: ../../c-api/call.rst:140 +msgid "(Py_ssize_t)(nargsf & ~PY_VECTORCALL_ARGUMENTS_OFFSET)" +msgstr "(Py_ssize_t)(nargsf & ~PY_VECTORCALL_ARGUMENTS_OFFSET)" + +#: ../../c-api/call.rst:142 +msgid "" +"However, the function ``PyVectorcall_NARGS`` should be used to allow for " +"future extensions." +msgstr "然而，應使用 ``PyVectorcall_NARGS`` 函式以便將來需要擴充。" + +#: ../../c-api/call.rst:149 +msgid "" +"If *op* does not support the vectorcall protocol (either because the type " +"does not or because the specific instance does not), return *NULL*. " +"Otherwise, return the vectorcall function pointer stored in *op*. This " +"function never raises an exception." +msgstr "" +"如果 *op* 不支援 vectorcall 協定（因為型別不支援或特定實例不支援），就回傳 " +"*NULL*。否則，回傳儲存在 *op* 中的 vectorcall 函式指標。這個函式不會引發例" +"外。" + +#: ../../c-api/call.rst:154 +msgid "" +"This is mostly useful to check whether or not *op* supports vectorcall, " +"which can be done by checking ``PyVectorcall_Function(op) != NULL``." +msgstr "" +"這大多在檢查 *op* 是否支援 vectorcall 時能派上用場，可以透過檢查 " +"``PyVectorcall_Function(op) != NULL`` 來達成。" + +#: ../../c-api/call.rst:161 +msgid "" +"Call *callable*'s :c:type:`vectorcallfunc` with positional and keyword " +"arguments given in a tuple and dict, respectively." +msgstr "" +"呼叫 *callable* 的 :c:type:`vectorcallfunc`，其位置引數和關鍵字引數分別以 " +"tuple 和 dict 格式給定。" + +#: ../../c-api/call.rst:164 +msgid "" +"This is a specialized function, intended to be put in the :c:member:" +"`~PyTypeObject.tp_call` slot or be used in an implementation of ``tp_call``. " +"It does not check the :c:macro:`Py_TPFLAGS_HAVE_VECTORCALL` flag and it does " +"not fall back to ``tp_call``." +msgstr "" +"這是一個專門函式，其目的是被放入 :c:member:`~PyTypeObject.tp_call` 擴充槽或是" +"用於 ``tp_call`` 的實作。它不會檢查 :c:macro:`Py_TPFLAGS_HAVE_VECTORCALL` 旗" +"標並且它不會退回 (fall back) 使用 ``tp_call``。" + +#: ../../c-api/call.rst:175 +msgid "Object Calling API" +msgstr "物件呼叫 API" + +#: ../../c-api/call.rst:177 +msgid "" +"Various functions are available for calling a Python object. Each converts " +"its arguments to a convention supported by the called object – either " +"*tp_call* or vectorcall. In order to do as little conversion as possible, " +"pick one that best fits the format of data you have available." +msgstr "" +"有多個函式可被用來呼叫 Python 物件。各個函式會將其引數轉換為被呼叫物件所支援" +"的慣用形式 – 可以是 *tp_call* 或 vectorcall。為了儘可能減少轉換的進行，請選擇" +"一個適合你所擁有資料格式的函式。" + +#: ../../c-api/call.rst:183 +msgid "" +"The following table summarizes the available functions; please see " +"individual documentation for details." +msgstr "下表總結了可用的函式；請參閱各個說明文件以瞭解詳情。" + +#: ../../c-api/call.rst:187 +msgid "Function" +msgstr "函式" + +#: ../../c-api/call.rst:187 +msgid "callable" +msgstr "callable" + +#: ../../c-api/call.rst:187 +msgid "args" +msgstr "args" + +#: ../../c-api/call.rst:187 +msgid "kwargs" +msgstr "kwargs" + +#: ../../c-api/call.rst:189 +msgid ":c:func:`PyObject_Call`" +msgstr ":c:func:`PyObject_Call`" + +#: ../../c-api/call.rst:189 ../../c-api/call.rst:191 ../../c-api/call.rst:193 +#: ../../c-api/call.rst:195 ../../c-api/call.rst:197 ../../c-api/call.rst:201 +#: ../../c-api/call.rst:209 ../../c-api/call.rst:211 +msgid "``PyObject *``" +msgstr "``PyObject *``" + +#: ../../c-api/call.rst:189 +msgid "tuple" +msgstr "tuple" + +#: ../../c-api/call.rst:189 ../../c-api/call.rst:211 +msgid "dict/``NULL``" +msgstr "dict/``NULL``" + +#: ../../c-api/call.rst:191 +msgid ":c:func:`PyObject_CallNoArgs`" +msgstr ":c:func:`PyObject_CallNoArgs`" + +#: ../../c-api/call.rst:191 ../../c-api/call.rst:193 ../../c-api/call.rst:195 +#: ../../c-api/call.rst:197 ../../c-api/call.rst:199 ../../c-api/call.rst:201 +#: ../../c-api/call.rst:203 ../../c-api/call.rst:205 ../../c-api/call.rst:207 +msgid "---" +msgstr "---" + +#: ../../c-api/call.rst:193 +msgid ":c:func:`PyObject_CallOneArg`" +msgstr ":c:func:`PyObject_CallOneArg`" + +#: ../../c-api/call.rst:193 ../../c-api/call.rst:207 +msgid "1 object" +msgstr "一個物件" + +#: ../../c-api/call.rst:195 +msgid ":c:func:`PyObject_CallObject`" +msgstr ":c:func:`PyObject_CallObject`" + +#: ../../c-api/call.rst:195 +msgid "tuple/``NULL``" +msgstr "tuple/``NULL``" + +#: ../../c-api/call.rst:197 +msgid ":c:func:`PyObject_CallFunction`" +msgstr ":c:func:`PyObject_CallFunction`" + +#: ../../c-api/call.rst:197 ../../c-api/call.rst:199 +msgid "format" +msgstr "format" + +#: ../../c-api/call.rst:199 +msgid ":c:func:`PyObject_CallMethod`" +msgstr ":c:func:`PyObject_CallMethod`" + +#: ../../c-api/call.rst:199 +msgid "obj + ``char*``" +msgstr "物件 + ``char*``" + +#: ../../c-api/call.rst:201 +msgid ":c:func:`PyObject_CallFunctionObjArgs`" +msgstr ":c:func:`PyObject_CallFunctionObjArgs`" + +#: ../../c-api/call.rst:201 ../../c-api/call.rst:203 +msgid "variadic" +msgstr "可變引數" + +#: ../../c-api/call.rst:203 +msgid ":c:func:`PyObject_CallMethodObjArgs`" +msgstr ":c:func:`PyObject_CallMethodObjArgs`" + +#: ../../c-api/call.rst:203 ../../c-api/call.rst:205 ../../c-api/call.rst:207 +msgid "obj + name" +msgstr "物件 + 名稱" + +#: ../../c-api/call.rst:205 +msgid ":c:func:`PyObject_CallMethodNoArgs`" +msgstr ":c:func:`PyObject_CallMethodNoArgs`" + +#: ../../c-api/call.rst:207 +msgid ":c:func:`PyObject_CallMethodOneArg`" +msgstr ":c:func:`PyObject_CallMethodOneArg`" + +#: ../../c-api/call.rst:209 +msgid ":c:func:`PyObject_Vectorcall`" +msgstr ":c:func:`PyObject_Vectorcall`" + +#: ../../c-api/call.rst:209 ../../c-api/call.rst:211 ../../c-api/call.rst:213 +msgid "vectorcall" +msgstr "vectorcall" + +#: ../../c-api/call.rst:211 +msgid ":c:func:`PyObject_VectorcallDict`" +msgstr ":c:func:`PyObject_VectorcallDict`" + +#: ../../c-api/call.rst:213 +msgid ":c:func:`PyObject_VectorcallMethod`" +msgstr ":c:func:`PyObject_VectorcallMethod`" + +#: ../../c-api/call.rst:213 +msgid "arg + name" +msgstr "引數 + 名稱" + +#: ../../c-api/call.rst:219 +msgid "" +"Call a callable Python object *callable*, with arguments given by the tuple " +"*args*, and named arguments given by the dictionary *kwargs*." +msgstr "" +"呼叫一個可呼叫的 Python 物件 *callable*，附帶由 tuple *args* 所給定的引數及由" +"字典 *kwargs* 所給定的關鍵字引數。" + +#: ../../c-api/call.rst:222 +msgid "" +"*args* must not be *NULL*; use an empty tuple if no arguments are needed. If " +"no named arguments are needed, *kwargs* can be *NULL*." +msgstr "" +"*args* 必須不為 *NULL*；如果不需要引數，請使用一個空 tuple。如果不需要關鍵字" +"引數，則 *kwargs* 可以為 *NULL*。" + +#: ../../c-api/call.rst:225 ../../c-api/call.rst:237 ../../c-api/call.rst:248 +#: ../../c-api/call.rst:259 ../../c-api/call.rst:271 ../../c-api/call.rst:291 +#: ../../c-api/call.rst:310 ../../c-api/call.rst:324 ../../c-api/call.rst:333 +#: ../../c-api/call.rst:345 ../../c-api/call.rst:358 ../../c-api/call.rst:392 +msgid "" +"Return the result of the call on success, or raise an exception and return " +"*NULL* on failure." +msgstr "成功時回傳結果，或在失敗時引發一個例外並回傳 *NULL*。" + +#: ../../c-api/call.rst:228 +msgid "" +"This is the equivalent of the Python expression: ``callable(*args, " +"**kwargs)``." +msgstr "這等價於 Python 運算式 ``callable(*args, **kwargs)``。" + +#: ../../c-api/call.rst:234 +msgid "" +"Call a callable Python object *callable* without any arguments. It is the " +"most efficient way to call a callable Python object without any argument." +msgstr "" +"呼叫一個可呼叫的 Python 物件 *callable* 並不附帶任何引數。這是不帶引數呼叫 " +"Python 可呼叫物件的最有效方式。" + +#: ../../c-api/call.rst:245 +msgid "" +"Call a callable Python object *callable* with exactly 1 positional argument " +"*arg* and no keyword arguments." +msgstr "" +"呼叫一個可呼叫的 Python 物件 *callable* 並附帶正好一個位置引數 *arg* 而沒有關" +"鍵字引數。" + +#: ../../c-api/call.rst:256 +msgid "" +"Call a callable Python object *callable*, with arguments given by the tuple " +"*args*. If no arguments are needed, then *args* can be *NULL*." +msgstr "" +"呼叫一個可呼叫的 Python 物件 *callable*，附帶由 tuple *args* 所給定的引數。如" +"果不需要傳入引數，則 *args* 可以為 *NULL*。" + +#: ../../c-api/call.rst:262 ../../c-api/call.rst:274 +msgid "This is the equivalent of the Python expression: ``callable(*args)``." +msgstr "這等價於 Python 運算式 ``callable(*args)``。" + +#: ../../c-api/call.rst:267 +msgid "" +"Call a callable Python object *callable*, with a variable number of C " +"arguments. The C arguments are described using a :c:func:`Py_BuildValue` " +"style format string. The format can be *NULL*, indicating that no arguments " +"are provided." +msgstr "" +"呼叫一個可呼叫的 Python 物件 *callable*，附帶數量可變的 C 引數。這些 C 引數使" +"用 :c:func:`Py_BuildValue` 風格的格式字串來描述。格式可以為 *NULL*，表示沒有" +"提供任何引數。" + +#: ../../c-api/call.rst:276 +msgid "" +"Note that if you only pass :c:expr:`PyObject *` args, :c:func:" +"`PyObject_CallFunctionObjArgs` is a faster alternative." +msgstr "" +"注意，如果你只傳入 :c:expr:`PyObject *` 引數，則 :c:func:" +"`PyObject_CallFunctionObjArgs` 是另一個更快速的選擇。" + +#: ../../c-api/call.rst:279 +msgid "The type of *format* was changed from ``char *``." +msgstr "這個 *format* 的型別已從 ``char *`` 更改。" + +#: ../../c-api/call.rst:285 +msgid "" +"Call the method named *name* of object *obj* with a variable number of C " +"arguments. The C arguments are described by a :c:func:`Py_BuildValue` " +"format string that should produce a tuple." +msgstr "" +"呼叫 *obj* 物件中名為 *name* 的 method 並附帶數量可變的 C 引數。這些 C 引數" +"由 :c:func:`Py_BuildValue` 格式字串來描述，並應當生成一個 tuple。" + +#: ../../c-api/call.rst:289 +msgid "The format can be *NULL*, indicating that no arguments are provided." +msgstr "格式可以為 *NULL*，表示沒有提供任何引數。" + +#: ../../c-api/call.rst:294 +msgid "" +"This is the equivalent of the Python expression: ``obj.name(arg1, " +"arg2, ...)``." +msgstr "這等價於 Python 運算式 ``obj.name(arg1, arg2, ...)``。" + +#: ../../c-api/call.rst:297 +msgid "" +"Note that if you only pass :c:expr:`PyObject *` args, :c:func:" +"`PyObject_CallMethodObjArgs` is a faster alternative." +msgstr "" +"注意，如果你只傳入 :c:expr:`PyObject *` 引數，則 :c:func:" +"`PyObject_CallMethodObjArgs` 是另一個更快速的選擇。" + +#: ../../c-api/call.rst:300 +msgid "The types of *name* and *format* were changed from ``char *``." +msgstr "*name* 和 *format* 的型別已從 ``char *`` 更改。" + +#: ../../c-api/call.rst:306 +msgid "" +"Call a callable Python object *callable*, with a variable number of :c:expr:" +"`PyObject *` arguments. The arguments are provided as a variable number of " +"parameters followed by *NULL*." +msgstr "" +"呼叫一個可呼叫的 Python 物件 *callable*，附帶數量可變的 :c:expr:`PyObject *` " +"引數。這些引數是以位置在 *NULL* 後面、數量可變的參數來提供。" + +#: ../../c-api/call.rst:313 +msgid "" +"This is the equivalent of the Python expression: ``callable(arg1, " +"arg2, ...)``." +msgstr "這等價於 Python 運算式 ``callable(arg1, arg2, ...)``。" + +#: ../../c-api/call.rst:319 +msgid "" +"Call a method of the Python object *obj*, where the name of the method is " +"given as a Python string object in *name*. It is called with a variable " +"number of :c:expr:`PyObject *` arguments. The arguments are provided as a " +"variable number of parameters followed by *NULL*." +msgstr "" +"呼叫 Python 物件 *obj* 中的一個 method，其中 method 名稱由 *name* 中的 " +"Python 字串物件給定。被呼叫時會附帶數量可變的 :c:expr:`PyObject *` 引數。這些" +"引數是以位置在 *NULL* 後面、且數量可變的參數來提供。" + +#: ../../c-api/call.rst:330 +msgid "" +"Call a method of the Python object *obj* without arguments, where the name " +"of the method is given as a Python string object in *name*." +msgstr "" +"不附帶任何引數地呼叫 Python 物件 *obj* 中的一個 method，其中 method 名稱由 " +"*name* 中的 Python 字串物件給定。" + +#: ../../c-api/call.rst:341 +msgid "" +"Call a method of the Python object *obj* with a single positional argument " +"*arg*, where the name of the method is given as a Python string object in " +"*name*." +msgstr "" +"附帶一個位置引數 *arg* 地呼叫 Python 物件 *obj* 中的一個 method，其中 method " +"名稱由 *name* 中的 Python 字串物件給定。" + +#: ../../c-api/call.rst:353 +msgid "" +"Call a callable Python object *callable*. The arguments are the same as for :" +"c:type:`vectorcallfunc`. If *callable* supports vectorcall_, this directly " +"calls the vectorcall function stored in *callable*." +msgstr "" +"呼叫一個可呼叫的 Python 物件 *callable*。附帶引數與 :c:type:`vectorcallfunc` " +"的相同。如果 *callable* 支援 vectorcall_，則它會直接呼叫存放在 *callable* 中" +"的 vectorcall 函式。" + +#: ../../c-api/call.rst:365 +msgid "" +"Call *callable* with positional arguments passed exactly as in the " +"vectorcall_ protocol, but with keyword arguments passed as a dictionary " +"*kwdict*. The *args* array contains only the positional arguments." +msgstr "" +"附帶與在 vectorcall_ 協定中傳入的相同位置引數來呼叫 *callable*，但會加上以字" +"典 *kwdict* 格式傳入的關鍵字引數。*args* 陣列將只包含位置引數。" + +#: ../../c-api/call.rst:369 +msgid "" +"Regardless of which protocol is used internally, a conversion of arguments " +"needs to be done. Therefore, this function should only be used if the caller " +"already has a dictionary ready to use for the keyword arguments, but not a " +"tuple for the positional arguments." +msgstr "" +"無論內部使用了哪一種協定，都會需要進行引數的轉換。因此，此函式應該只有在呼叫" +"方已經擁有一個要作為關鍵字引數的字典、但沒有作為位置引數的 tuple 時才被使用。" + +#: ../../c-api/call.rst:379 +msgid "" +"Call a method using the vectorcall calling convention. The name of the " +"method is given as a Python string *name*. The object whose method is called " +"is *args[0]*, and the *args* array starting at *args[1]* represents the " +"arguments of the call. There must be at least one positional argument. " +"*nargsf* is the number of positional arguments including *args[0]*, plus :c:" +"macro:`PY_VECTORCALL_ARGUMENTS_OFFSET` if the value of ``args[0]`` may " +"temporarily be changed. Keyword arguments can be passed just like in :c:func:" +"`PyObject_Vectorcall`." +msgstr "" +"使用 vectorcall 呼叫慣例來呼叫一個 method。method 的名稱以 Python 字串 " +"*name* 的格式給定。被呼叫 method 的物件為 *args[0]*，而 *args* 陣列從 " +"*args[1]* 開始的部分則代表呼叫的引數。必須傳入至少一個位置引數。*nargsf* 為包" +"括 *args[0]* 在內的位置引數的數量，如果 ``args[0]`` 的值可能被臨時改變則要再" +"加上 :c:macro:`PY_VECTORCALL_ARGUMENTS_OFFSET`。關鍵字引數可以像在 :c:func:" +"`PyObject_Vectorcall` 中一樣被傳入。" + +#: ../../c-api/call.rst:388 +msgid "" +"If the object has the :c:macro:`Py_TPFLAGS_METHOD_DESCRIPTOR` feature, this " +"will call the unbound method object with the full *args* vector as arguments." +msgstr "" +"如果物件具有 :c:macro:`Py_TPFLAGS_METHOD_DESCRIPTOR` 特性，這將以完整的 " +"*args* 向量作為引數來呼叫 unbound method（未繫結方法）物件。" + +#: ../../c-api/call.rst:399 +msgid "Call Support API" +msgstr "呼叫支援 API" + +#: ../../c-api/call.rst:403 +msgid "" +"Determine if the object *o* is callable. Return ``1`` if the object is " +"callable and ``0`` otherwise. This function always succeeds." +msgstr "" +"判定物件 *o* 是否為可呼叫的。如果物件是可呼叫物件則回傳 ``1``，其他情況回傳 " +"``0``。這個函式不會呼叫失敗。" + +#~ msgid "" +#~ "In CPython 3.8, the vectorcall API and related functions were available " +#~ "provisionally under names with a leading underscore: " +#~ "``_PyObject_Vectorcall``, ``_Py_TPFLAGS_HAVE_VECTORCALL``, " +#~ "``_PyObject_VectorcallMethod``, ``_PyVectorcall_Function``, " +#~ "``_PyObject_CallOneArg``, ``_PyObject_CallMethodNoArgs``, " +#~ "``_PyObject_CallMethodOneArg``. Additionally, ``PyObject_VectorcallDict`` " +#~ "was available as ``_PyObject_FastCallDict``. The old names are still " +#~ "defined as aliases of the new, non-underscored names." +#~ msgstr "" +#~ "在 CPython 3.8 中，vectorcall API 和相關函式暫定以帶開頭底線的名稱提供：" +#~ "``_PyObject_Vectorcall``、``_Py_TPFLAGS_HAVE_VECTORCALL``、" +#~ "``_PyObject_VectorcallMethod``、``_PyVectorcall_Function``、" +#~ "``_PyObject_CallOneArg``、``_PyObject_CallMethodNoArgs``、" +#~ "``_PyObject_CallMethodOneArg``。此外，``PyObject_VectorcallDict`` 也以 " +#~ "``_PyObject_FastCallDict`` 名稱提供。這些舊名稱仍有被定義，做為不帶底線的" +#~ "新名稱的別名。" diff --git a/c-api/capsule.po b/c-api/capsule.po index 0a50a92d86..ef3af2c1e9 100644 --- a/c-api/capsule.po +++ b/c-api/capsule.po @@ -1,235 +1,235 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-07 15:15+0000\n" -"PO-Revision-Date: 2018-05-23 14:30+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" - -#: ../../c-api/capsule.rst:6 -msgid "Capsules" -msgstr "" - -#: ../../c-api/capsule.rst:10 -msgid "" -"Refer to :ref:`using-capsules` for more information on using these objects." -msgstr "" - -#: ../../c-api/capsule.rst:17 -msgid "" -"This subtype of :c:type:`PyObject` represents an opaque value, useful for C " -"extension modules which need to pass an opaque value (as a :c:expr:`void*` " -"pointer) through Python code to other C code. It is often used to make a C " -"function pointer defined in one module available to other modules, so the " -"regular import mechanism can be used to access C APIs defined in dynamically " -"loaded modules." -msgstr "" - -#: ../../c-api/capsule.rst:27 -msgid "" -"The type object corresponding to capsule objects. This is the same object " -"as :class:`types.CapsuleType` in the Python layer." -msgstr "" - -#: ../../c-api/capsule.rst:33 -msgid "The type of a destructor callback for a capsule. Defined as::" -msgstr "" - -#: ../../c-api/capsule.rst:35 -msgid "typedef void (*PyCapsule_Destructor)(PyObject *);" -msgstr "typedef void (*PyCapsule_Destructor)(PyObject *);" - -#: ../../c-api/capsule.rst:37 -msgid "" -"See :c:func:`PyCapsule_New` for the semantics of PyCapsule_Destructor " -"callbacks." -msgstr "" - -#: ../../c-api/capsule.rst:43 -msgid "" -"Return true if its argument is a :c:type:`PyCapsule`. This function always " -"succeeds." -msgstr "" - -#: ../../c-api/capsule.rst:49 -msgid "" -"Create a :c:type:`PyCapsule` encapsulating the *pointer*. The *pointer* " -"argument may not be ``NULL``." -msgstr "" - -#: ../../c-api/capsule.rst:52 -msgid "On failure, set an exception and return ``NULL``." -msgstr "" - -#: ../../c-api/capsule.rst:54 -msgid "" -"The *name* string may either be ``NULL`` or a pointer to a valid C string. " -"If non-``NULL``, this string must outlive the capsule. (Though it is " -"permitted to free it inside the *destructor*.)" -msgstr "" - -#: ../../c-api/capsule.rst:58 -msgid "" -"If the *destructor* argument is not ``NULL``, it will be called with the " -"capsule as its argument when it is destroyed." -msgstr "" - -#: ../../c-api/capsule.rst:61 -msgid "" -"If this capsule will be stored as an attribute of a module, the *name* " -"should be specified as ``modulename.attributename``. This will enable other " -"modules to import the capsule using :c:func:`PyCapsule_Import`." -msgstr "" - -#: ../../c-api/capsule.rst:68 -msgid "" -"Retrieve the *pointer* stored in the capsule. On failure, set an exception " -"and return ``NULL``." -msgstr "" - -#: ../../c-api/capsule.rst:71 -msgid "" -"The *name* parameter must compare exactly to the name stored in the capsule. " -"If the name stored in the capsule is ``NULL``, the *name* passed in must " -"also be ``NULL``. Python uses the C function :c:func:`!strcmp` to compare " -"capsule names." -msgstr "" - -#: ../../c-api/capsule.rst:79 -msgid "" -"Return the current destructor stored in the capsule. On failure, set an " -"exception and return ``NULL``." -msgstr "" - -#: ../../c-api/capsule.rst:82 -msgid "" -"It is legal for a capsule to have a ``NULL`` destructor. This makes a " -"``NULL`` return code somewhat ambiguous; use :c:func:`PyCapsule_IsValid` or :" -"c:func:`PyErr_Occurred` to disambiguate." -msgstr "" - -#: ../../c-api/capsule.rst:89 -msgid "" -"Return the current context stored in the capsule. On failure, set an " -"exception and return ``NULL``." -msgstr "" - -#: ../../c-api/capsule.rst:92 -msgid "" -"It is legal for a capsule to have a ``NULL`` context. This makes a ``NULL`` " -"return code somewhat ambiguous; use :c:func:`PyCapsule_IsValid` or :c:func:" -"`PyErr_Occurred` to disambiguate." -msgstr "" - -#: ../../c-api/capsule.rst:99 -msgid "" -"Return the current name stored in the capsule. On failure, set an exception " -"and return ``NULL``." -msgstr "" - -#: ../../c-api/capsule.rst:102 -msgid "" -"It is legal for a capsule to have a ``NULL`` name. This makes a ``NULL`` " -"return code somewhat ambiguous; use :c:func:`PyCapsule_IsValid` or :c:func:" -"`PyErr_Occurred` to disambiguate." -msgstr "" - -#: ../../c-api/capsule.rst:109 -msgid "" -"Import a pointer to a C object from a capsule attribute in a module. The " -"*name* parameter should specify the full name to the attribute, as in " -"``module.attribute``. The *name* stored in the capsule must match this " -"string exactly." -msgstr "" - -#: ../../c-api/capsule.rst:114 -msgid "" -"This function splits *name* on the ``.`` character, and imports the first " -"element. It then processes further elements using attribute lookups." -msgstr "" - -#: ../../c-api/capsule.rst:117 -msgid "" -"Return the capsule's internal *pointer* on success. On failure, set an " -"exception and return ``NULL``." -msgstr "" - -#: ../../c-api/capsule.rst:122 -msgid "" -"If *name* points to an attribute of some submodule or subpackage, this " -"submodule or subpackage must be previously imported using other means (for " -"example, by using :c:func:`PyImport_ImportModule`) for the attribute lookups " -"to succeed." -msgstr "" - -#: ../../c-api/capsule.rst:127 -msgid "*no_block* has no effect anymore." -msgstr "" - -#: ../../c-api/capsule.rst:133 -msgid "" -"Determines whether or not *capsule* is a valid capsule. A valid capsule is " -"non-``NULL``, passes :c:func:`PyCapsule_CheckExact`, has a non-``NULL`` " -"pointer stored in it, and its internal name matches the *name* parameter. " -"(See :c:func:`PyCapsule_GetPointer` for information on how capsule names are " -"compared.)" -msgstr "" - -#: ../../c-api/capsule.rst:139 -msgid "" -"In other words, if :c:func:`PyCapsule_IsValid` returns a true value, calls " -"to any of the accessors (any function starting with ``PyCapsule_Get``) are " -"guaranteed to succeed." -msgstr "" - -#: ../../c-api/capsule.rst:143 -msgid "" -"Return a nonzero value if the object is valid and matches the name passed " -"in. Return ``0`` otherwise. This function will not fail." -msgstr "" - -#: ../../c-api/capsule.rst:149 -msgid "Set the context pointer inside *capsule* to *context*." -msgstr "" - -#: ../../c-api/capsule.rst:151 ../../c-api/capsule.rst:158 -#: ../../c-api/capsule.rst:167 ../../c-api/capsule.rst:175 -msgid "" -"Return ``0`` on success. Return nonzero and set an exception on failure." -msgstr "" - -#: ../../c-api/capsule.rst:156 -msgid "Set the destructor inside *capsule* to *destructor*." -msgstr "" - -#: ../../c-api/capsule.rst:163 -msgid "" -"Set the name inside *capsule* to *name*. If non-``NULL``, the name must " -"outlive the capsule. If the previous *name* stored in the capsule was not " -"``NULL``, no attempt is made to free it." -msgstr "" - -#: ../../c-api/capsule.rst:172 -msgid "" -"Set the void pointer inside *capsule* to *pointer*. The pointer may not be " -"``NULL``." -msgstr "" - -#: ../../c-api/capsule.rst:8 -msgid "object" -msgstr "object（物件）" - -#: ../../c-api/capsule.rst:8 -msgid "Capsule" -msgstr "Capsule" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-07 15:15+0000\n" +"PO-Revision-Date: 2018-05-23 14:30+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" + +#: ../../c-api/capsule.rst:6 +msgid "Capsules" +msgstr "" + +#: ../../c-api/capsule.rst:10 +msgid "" +"Refer to :ref:`using-capsules` for more information on using these objects." +msgstr "" + +#: ../../c-api/capsule.rst:17 +msgid "" +"This subtype of :c:type:`PyObject` represents an opaque value, useful for C " +"extension modules which need to pass an opaque value (as a :c:expr:`void*` " +"pointer) through Python code to other C code. It is often used to make a C " +"function pointer defined in one module available to other modules, so the " +"regular import mechanism can be used to access C APIs defined in dynamically " +"loaded modules." +msgstr "" + +#: ../../c-api/capsule.rst:27 +msgid "" +"The type object corresponding to capsule objects. This is the same object " +"as :class:`types.CapsuleType` in the Python layer." +msgstr "" + +#: ../../c-api/capsule.rst:33 +msgid "The type of a destructor callback for a capsule. Defined as::" +msgstr "" + +#: ../../c-api/capsule.rst:35 +msgid "typedef void (*PyCapsule_Destructor)(PyObject *);" +msgstr "typedef void (*PyCapsule_Destructor)(PyObject *);" + +#: ../../c-api/capsule.rst:37 +msgid "" +"See :c:func:`PyCapsule_New` for the semantics of PyCapsule_Destructor " +"callbacks." +msgstr "" + +#: ../../c-api/capsule.rst:43 +msgid "" +"Return true if its argument is a :c:type:`PyCapsule`. This function always " +"succeeds." +msgstr "" + +#: ../../c-api/capsule.rst:49 +msgid "" +"Create a :c:type:`PyCapsule` encapsulating the *pointer*. The *pointer* " +"argument may not be ``NULL``." +msgstr "" + +#: ../../c-api/capsule.rst:52 +msgid "On failure, set an exception and return ``NULL``." +msgstr "" + +#: ../../c-api/capsule.rst:54 +msgid "" +"The *name* string may either be ``NULL`` or a pointer to a valid C string. " +"If non-``NULL``, this string must outlive the capsule. (Though it is " +"permitted to free it inside the *destructor*.)" +msgstr "" + +#: ../../c-api/capsule.rst:58 +msgid "" +"If the *destructor* argument is not ``NULL``, it will be called with the " +"capsule as its argument when it is destroyed." +msgstr "" + +#: ../../c-api/capsule.rst:61 +msgid "" +"If this capsule will be stored as an attribute of a module, the *name* " +"should be specified as ``modulename.attributename``. This will enable other " +"modules to import the capsule using :c:func:`PyCapsule_Import`." +msgstr "" + +#: ../../c-api/capsule.rst:68 +msgid "" +"Retrieve the *pointer* stored in the capsule. On failure, set an exception " +"and return ``NULL``." +msgstr "" + +#: ../../c-api/capsule.rst:71 +msgid "" +"The *name* parameter must compare exactly to the name stored in the capsule. " +"If the name stored in the capsule is ``NULL``, the *name* passed in must " +"also be ``NULL``. Python uses the C function :c:func:`!strcmp` to compare " +"capsule names." +msgstr "" + +#: ../../c-api/capsule.rst:79 +msgid "" +"Return the current destructor stored in the capsule. On failure, set an " +"exception and return ``NULL``." +msgstr "" + +#: ../../c-api/capsule.rst:82 +msgid "" +"It is legal for a capsule to have a ``NULL`` destructor. This makes a " +"``NULL`` return code somewhat ambiguous; use :c:func:`PyCapsule_IsValid` or :" +"c:func:`PyErr_Occurred` to disambiguate." +msgstr "" + +#: ../../c-api/capsule.rst:89 +msgid "" +"Return the current context stored in the capsule. On failure, set an " +"exception and return ``NULL``." +msgstr "" + +#: ../../c-api/capsule.rst:92 +msgid "" +"It is legal for a capsule to have a ``NULL`` context. This makes a ``NULL`` " +"return code somewhat ambiguous; use :c:func:`PyCapsule_IsValid` or :c:func:" +"`PyErr_Occurred` to disambiguate." +msgstr "" + +#: ../../c-api/capsule.rst:99 +msgid "" +"Return the current name stored in the capsule. On failure, set an exception " +"and return ``NULL``." +msgstr "" + +#: ../../c-api/capsule.rst:102 +msgid "" +"It is legal for a capsule to have a ``NULL`` name. This makes a ``NULL`` " +"return code somewhat ambiguous; use :c:func:`PyCapsule_IsValid` or :c:func:" +"`PyErr_Occurred` to disambiguate." +msgstr "" + +#: ../../c-api/capsule.rst:109 +msgid "" +"Import a pointer to a C object from a capsule attribute in a module. The " +"*name* parameter should specify the full name to the attribute, as in " +"``module.attribute``. The *name* stored in the capsule must match this " +"string exactly." +msgstr "" + +#: ../../c-api/capsule.rst:114 +msgid "" +"This function splits *name* on the ``.`` character, and imports the first " +"element. It then processes further elements using attribute lookups." +msgstr "" + +#: ../../c-api/capsule.rst:117 +msgid "" +"Return the capsule's internal *pointer* on success. On failure, set an " +"exception and return ``NULL``." +msgstr "" + +#: ../../c-api/capsule.rst:122 +msgid "" +"If *name* points to an attribute of some submodule or subpackage, this " +"submodule or subpackage must be previously imported using other means (for " +"example, by using :c:func:`PyImport_ImportModule`) for the attribute lookups " +"to succeed." +msgstr "" + +#: ../../c-api/capsule.rst:127 +msgid "*no_block* has no effect anymore." +msgstr "" + +#: ../../c-api/capsule.rst:133 +msgid "" +"Determines whether or not *capsule* is a valid capsule. A valid capsule is " +"non-``NULL``, passes :c:func:`PyCapsule_CheckExact`, has a non-``NULL`` " +"pointer stored in it, and its internal name matches the *name* parameter. " +"(See :c:func:`PyCapsule_GetPointer` for information on how capsule names are " +"compared.)" +msgstr "" + +#: ../../c-api/capsule.rst:139 +msgid "" +"In other words, if :c:func:`PyCapsule_IsValid` returns a true value, calls " +"to any of the accessors (any function starting with ``PyCapsule_Get``) are " +"guaranteed to succeed." +msgstr "" + +#: ../../c-api/capsule.rst:143 +msgid "" +"Return a nonzero value if the object is valid and matches the name passed " +"in. Return ``0`` otherwise. This function will not fail." +msgstr "" + +#: ../../c-api/capsule.rst:149 +msgid "Set the context pointer inside *capsule* to *context*." +msgstr "" + +#: ../../c-api/capsule.rst:151 ../../c-api/capsule.rst:158 +#: ../../c-api/capsule.rst:167 ../../c-api/capsule.rst:175 +msgid "" +"Return ``0`` on success. Return nonzero and set an exception on failure." +msgstr "" + +#: ../../c-api/capsule.rst:156 +msgid "Set the destructor inside *capsule* to *destructor*." +msgstr "" + +#: ../../c-api/capsule.rst:163 +msgid "" +"Set the name inside *capsule* to *name*. If non-``NULL``, the name must " +"outlive the capsule. If the previous *name* stored in the capsule was not " +"``NULL``, no attempt is made to free it." +msgstr "" + +#: ../../c-api/capsule.rst:172 +msgid "" +"Set the void pointer inside *capsule* to *pointer*. The pointer may not be " +"``NULL``." +msgstr "" + +#: ../../c-api/capsule.rst:8 +msgid "object" +msgstr "object（物件）" + +#: ../../c-api/capsule.rst:8 +msgid "Capsule" +msgstr "Capsule" diff --git a/c-api/cell.po b/c-api/cell.po index 0f4a13c46c..35ad89924a 100644 --- a/c-api/cell.po +++ b/c-api/cell.po @@ -1,109 +1,109 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# aminzai , 2015 -# Liang-Bo Wang , 2015 -# Matt Wang , 2021 -# -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-05 00:16+0000\n" -"PO-Revision-Date: 2022-10-16 15:33+0800\n" -"Last-Translator: Matt Wang \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" -"X-Generator: Poedit 3.1.1\n" - -#: ../../c-api/cell.rst:6 -msgid "Cell Objects" -msgstr "Cell 物件" - -#: ../../c-api/cell.rst:8 -msgid "" -"\"Cell\" objects are used to implement variables referenced by multiple " -"scopes. For each such variable, a cell object is created to store the value; " -"the local variables of each stack frame that references the value contain a " -"reference to the cells from outer scopes which also use that variable. When " -"the value is accessed, the value contained in the cell is used instead of " -"the cell object itself. This de-referencing of the cell object requires " -"support from the generated byte-code; these are not automatically de-" -"referenced when accessed. Cell objects are not likely to be useful elsewhere." -msgstr "" -"\"Cell\" 物件用於實現被多個作用域所參照 (reference) 的變數。對於每個這樣的變" -"數，都會有個 cell 物件為了儲存該值而被建立；參照該值的每個 stack frame 中的區" -"域性變數包含外部作用域的 cell 參照，它同樣使用了該變數。存取該值時，將使用 " -"cell 中包含的值而不是 cell 物件本身。這種對 cell 物件的去除參照 (de-" -"reference) 需要生成的位元組碼 (byte-code) 有支援；存取時不會自動去除參照。" -"cell 物件在其他地方可能不太有用。" - -#: ../../c-api/cell.rst:20 -msgid "The C structure used for cell objects." -msgstr "Cell 物件所用之 C 結構。" - -#: ../../c-api/cell.rst:25 -msgid "The type object corresponding to cell objects." -msgstr "對應 cell 物件的物件型別。" - -#: ../../c-api/cell.rst:30 -msgid "" -"Return true if *ob* is a cell object; *ob* must not be ``NULL``. This " -"function always succeeds." -msgstr "" -"如果 *ob* 是一個 cell 物件則回傳真值；*ob* 必須不為 ``NULL``。此函式總是會成" -"功執行。" - -#: ../../c-api/cell.rst:36 -msgid "" -"Create and return a new cell object containing the value *ob*. The parameter " -"may be ``NULL``." -msgstr "建立並回傳一個包含 *ob* 的新 cell 物件。參數可以為 ``NULL``。" - -#: ../../c-api/cell.rst:42 -msgid "" -"Return the contents of the cell *cell*, which can be ``NULL``. If *cell* is " -"not a cell object, returns ``NULL`` with an exception set." -msgstr "" -"回傳 cell 物件 *cell* 的內容，其可能為 ``NULL``。如果 *cell* 不是一個 cell 物" -"件，則將回傳 ``NULL`` 並設定例外。" - -#: ../../c-api/cell.rst:48 -msgid "" -"Return the contents of the cell *cell*, but without checking that *cell* is " -"non-``NULL`` and a cell object." -msgstr "" -"回傳 cell 物件 *cell* 的內容，但是不檢查 *cell* 是否非 ``NULL`` 並且為一個 " -"cell 物件。" - -#: ../../c-api/cell.rst:54 -msgid "" -"Set the contents of the cell object *cell* to *value*. This releases the " -"reference to any current content of the cell. *value* may be ``NULL``. " -"*cell* must be non-``NULL``." -msgstr "" -"將 cell 物件 *cell* 的內容設為 *value*。這將釋放任何對 cell 物件目前內容的參" -"照。*value* 可以為 ``NULL``。*cell* 必須不為 ``NULL``。" - -#: ../../c-api/cell.rst:58 -msgid "" -"On success, return ``0``. If *cell* is not a cell object, set an exception " -"and return ``-1``." -msgstr "" -"在成功時回傳 ``0``。如果 *cell* 不是一個 cell 物件，則將設定例外並回傳 " -"``-1``。" - -#: ../../c-api/cell.rst:64 -msgid "" -"Sets the value of the cell object *cell* to *value*. No reference counts " -"are adjusted, and no checks are made for safety; *cell* must be non-``NULL`` " -"and must be a cell object." -msgstr "" -"將 cell 物件 *cell* 的值設為 *value*。不會調整參照計數，並且不會進行任何安全" -"檢查；*cell* 必須為非 ``NULL`` 並且為一個 cell 物件。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# aminzai , 2015 +# Liang-Bo Wang , 2015 +# Matt Wang , 2021 +# +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-05 00:16+0000\n" +"PO-Revision-Date: 2022-10-16 15:33+0800\n" +"Last-Translator: Matt Wang \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" +"X-Generator: Poedit 3.1.1\n" + +#: ../../c-api/cell.rst:6 +msgid "Cell Objects" +msgstr "Cell 物件" + +#: ../../c-api/cell.rst:8 +msgid "" +"\"Cell\" objects are used to implement variables referenced by multiple " +"scopes. For each such variable, a cell object is created to store the value; " +"the local variables of each stack frame that references the value contain a " +"reference to the cells from outer scopes which also use that variable. When " +"the value is accessed, the value contained in the cell is used instead of " +"the cell object itself. This de-referencing of the cell object requires " +"support from the generated byte-code; these are not automatically de-" +"referenced when accessed. Cell objects are not likely to be useful elsewhere." +msgstr "" +"\"Cell\" 物件用於實現被多個作用域所參照 (reference) 的變數。對於每個這樣的變" +"數，都會有個 cell 物件為了儲存該值而被建立；參照該值的每個 stack frame 中的區" +"域性變數包含外部作用域的 cell 參照，它同樣使用了該變數。存取該值時，將使用 " +"cell 中包含的值而不是 cell 物件本身。這種對 cell 物件的去除參照 (de-" +"reference) 需要生成的位元組碼 (byte-code) 有支援；存取時不會自動去除參照。" +"cell 物件在其他地方可能不太有用。" + +#: ../../c-api/cell.rst:20 +msgid "The C structure used for cell objects." +msgstr "Cell 物件所用之 C 結構。" + +#: ../../c-api/cell.rst:25 +msgid "The type object corresponding to cell objects." +msgstr "對應 cell 物件的物件型別。" + +#: ../../c-api/cell.rst:30 +msgid "" +"Return true if *ob* is a cell object; *ob* must not be ``NULL``. This " +"function always succeeds." +msgstr "" +"如果 *ob* 是一個 cell 物件則回傳真值；*ob* 必須不為 ``NULL``。此函式總是會成" +"功執行。" + +#: ../../c-api/cell.rst:36 +msgid "" +"Create and return a new cell object containing the value *ob*. The parameter " +"may be ``NULL``." +msgstr "建立並回傳一個包含 *ob* 的新 cell 物件。參數可以為 ``NULL``。" + +#: ../../c-api/cell.rst:42 +msgid "" +"Return the contents of the cell *cell*, which can be ``NULL``. If *cell* is " +"not a cell object, returns ``NULL`` with an exception set." +msgstr "" +"回傳 cell 物件 *cell* 的內容，其可能為 ``NULL``。如果 *cell* 不是一個 cell 物" +"件，則將回傳 ``NULL`` 並設定例外。" + +#: ../../c-api/cell.rst:48 +msgid "" +"Return the contents of the cell *cell*, but without checking that *cell* is " +"non-``NULL`` and a cell object." +msgstr "" +"回傳 cell 物件 *cell* 的內容，但是不檢查 *cell* 是否非 ``NULL`` 並且為一個 " +"cell 物件。" + +#: ../../c-api/cell.rst:54 +msgid "" +"Set the contents of the cell object *cell* to *value*. This releases the " +"reference to any current content of the cell. *value* may be ``NULL``. " +"*cell* must be non-``NULL``." +msgstr "" +"將 cell 物件 *cell* 的內容設為 *value*。這將釋放任何對 cell 物件目前內容的參" +"照。*value* 可以為 ``NULL``。*cell* 必須不為 ``NULL``。" + +#: ../../c-api/cell.rst:58 +msgid "" +"On success, return ``0``. If *cell* is not a cell object, set an exception " +"and return ``-1``." +msgstr "" +"在成功時回傳 ``0``。如果 *cell* 不是一個 cell 物件，則將設定例外並回傳 " +"``-1``。" + +#: ../../c-api/cell.rst:64 +msgid "" +"Sets the value of the cell object *cell* to *value*. No reference counts " +"are adjusted, and no checks are made for safety; *cell* must be non-``NULL`` " +"and must be a cell object." +msgstr "" +"將 cell 物件 *cell* 的值設為 *value*。不會調整參照計數，並且不會進行任何安全" +"檢查；*cell* 必須為非 ``NULL`` 並且為一個 cell 物件。" diff --git a/c-api/code.po b/c-api/code.po index 140c2ec564..257e109bd5 100644 --- a/c-api/code.po +++ b/c-api/code.po @@ -1,488 +1,488 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-13 23:16+0000\n" -"PO-Revision-Date: 2015-12-09 17:51+0000\n" -"Last-Translator: Liang-Bo Wang \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" - -#: ../../c-api/code.rst:8 -msgid "Code Objects" -msgstr "程式碼物件" - -#: ../../c-api/code.rst:12 -msgid "" -"Code objects are a low-level detail of the CPython implementation. Each one " -"represents a chunk of executable code that hasn't yet been bound into a " -"function." -msgstr "" - -#: ../../c-api/code.rst:18 -msgid "" -"The C structure of the objects used to describe code objects. The fields of " -"this type are subject to change at any time." -msgstr "" - -#: ../../c-api/code.rst:24 -msgid "" -"This is an instance of :c:type:`PyTypeObject` representing the Python :ref:" -"`code object `." -msgstr "" - -#: ../../c-api/code.rst:30 -msgid "" -"Return true if *co* is a :ref:`code object `. This function " -"always succeeds." -msgstr "" - -#: ../../c-api/code.rst:35 -msgid "" -"Return the number of :term:`free (closure) variables ` in " -"a code object." -msgstr "" - -#: ../../c-api/code.rst:40 -msgid "" -"Return the position of the first :term:`free (closure) variable ` in a code object." -msgstr "" - -#: ../../c-api/code.rst:45 -msgid "" -"Renamed from ``PyCode_GetFirstFree`` as part of :ref:`unstable-c-api`. The " -"old name is deprecated, but will remain available until the signature " -"changes again." -msgstr "" - -#: ../../c-api/code.rst:51 -msgid "" -"Return a new code object. If you need a dummy code object to create a " -"frame, use :c:func:`PyCode_NewEmpty` instead." -msgstr "" - -#: ../../c-api/code.rst:54 -msgid "" -"Since the definition of the bytecode changes often, calling :c:func:" -"`PyUnstable_Code_New` directly can bind you to a precise Python version." -msgstr "" - -#: ../../c-api/code.rst:57 -msgid "" -"The many arguments of this function are inter-dependent in complex ways, " -"meaning that subtle changes to values are likely to result in incorrect " -"execution or VM crashes. Use this function only with extreme care." -msgstr "" - -#: ../../c-api/code.rst:61 -msgid "Added ``qualname`` and ``exceptiontable`` parameters." -msgstr "新增 ``qualname`` 和 ``exceptiontable`` 參數。" - -#: ../../c-api/code.rst:68 -msgid "" -"Renamed from ``PyCode_New`` as part of :ref:`unstable-c-api`. The old name " -"is deprecated, but will remain available until the signature changes again." -msgstr "" - -#: ../../c-api/code.rst:74 -msgid "" -"Similar to :c:func:`PyUnstable_Code_New`, but with an extra " -"\"posonlyargcount\" for positional-only arguments. The same caveats that " -"apply to ``PyUnstable_Code_New`` also apply to this function." -msgstr "" - -#: ../../c-api/code.rst:79 -msgid "as ``PyCode_NewWithPosOnlyArgs``" -msgstr "" - -#: ../../c-api/code.rst:81 -msgid "Added ``qualname`` and ``exceptiontable`` parameters." -msgstr "新增 ``qualname`` 和 ``exceptiontable`` 參數。" - -#: ../../c-api/code.rst:86 -msgid "" -"Renamed to ``PyUnstable_Code_NewWithPosOnlyArgs``. The old name is " -"deprecated, but will remain available until the signature changes again." -msgstr "" - -#: ../../c-api/code.rst:92 -msgid "" -"Return a new empty code object with the specified filename, function name, " -"and first line number. The resulting code object will raise an ``Exception`` " -"if executed." -msgstr "" - -#: ../../c-api/code.rst:98 -msgid "" -"Return the line number of the instruction that occurs on or before " -"``byte_offset`` and ends after it. If you just need the line number of a " -"frame, use :c:func:`PyFrame_GetLineNumber` instead." -msgstr "" - -#: ../../c-api/code.rst:101 -msgid "" -"For efficiently iterating over the line numbers in a code object, use :pep:" -"`the API described in PEP 626 <0626#out-of-process-debuggers-and-profilers>`." -msgstr "" - -#: ../../c-api/code.rst:106 -msgid "" -"Sets the passed ``int`` pointers to the source code line and column numbers " -"for the instruction at ``byte_offset``. Sets the value to ``0`` when " -"information is not available for any particular element." -msgstr "" - -#: ../../c-api/code.rst:110 -msgid "Returns ``1`` if the function succeeds and 0 otherwise." -msgstr "如果函式成功則回傳 ``1``，否則回傳 ``0``。" - -#: ../../c-api/code.rst:116 -msgid "" -"Equivalent to the Python code ``getattr(co, 'co_code')``. Returns a strong " -"reference to a :c:type:`PyBytesObject` representing the bytecode in a code " -"object. On error, ``NULL`` is returned and an exception is raised." -msgstr "" - -#: ../../c-api/code.rst:121 -msgid "" -"This ``PyBytesObject`` may be created on-demand by the interpreter and does " -"not necessarily represent the bytecode actually executed by CPython. The " -"primary use case for this function is debuggers and profilers." -msgstr "" - -#: ../../c-api/code.rst:129 -msgid "" -"Equivalent to the Python code ``getattr(co, 'co_varnames')``. Returns a new " -"reference to a :c:type:`PyTupleObject` containing the names of the local " -"variables. On error, ``NULL`` is returned and an exception is raised." -msgstr "" - -#: ../../c-api/code.rst:138 -msgid "" -"Equivalent to the Python code ``getattr(co, 'co_cellvars')``. Returns a new " -"reference to a :c:type:`PyTupleObject` containing the names of the local " -"variables that are referenced by nested functions. On error, ``NULL`` is " -"returned and an exception is raised." -msgstr "" - -#: ../../c-api/code.rst:147 -msgid "" -"Equivalent to the Python code ``getattr(co, 'co_freevars')``. Returns a new " -"reference to a :c:type:`PyTupleObject` containing the names of the :term:" -"`free (closure) variables `. On error, ``NULL`` is " -"returned and an exception is raised." -msgstr "" - -#: ../../c-api/code.rst:156 -msgid "" -"Register *callback* as a code object watcher for the current interpreter. " -"Return an ID which may be passed to :c:func:`PyCode_ClearWatcher`. In case " -"of error (e.g. no more watcher IDs available), return ``-1`` and set an " -"exception." -msgstr "" - -#: ../../c-api/code.rst:165 -msgid "" -"Clear watcher identified by *watcher_id* previously returned from :c:func:" -"`PyCode_AddWatcher` for the current interpreter. Return ``0`` on success, or " -"``-1`` and set an exception on error (e.g. if the given *watcher_id* was " -"never registered.)" -msgstr "" - -#: ../../c-api/code.rst:174 -msgid "" -"Enumeration of possible code object watcher events: - " -"``PY_CODE_EVENT_CREATE`` - ``PY_CODE_EVENT_DESTROY``" -msgstr "" - -#: ../../c-api/code.rst:182 -msgid "Type of a code object watcher callback function." -msgstr "" - -#: ../../c-api/code.rst:184 -msgid "" -"If *event* is ``PY_CODE_EVENT_CREATE``, then the callback is invoked after " -"*co* has been fully initialized. Otherwise, the callback is invoked before " -"the destruction of *co* takes place, so the prior state of *co* can be " -"inspected." -msgstr "" - -#: ../../c-api/code.rst:189 -msgid "" -"If *event* is ``PY_CODE_EVENT_DESTROY``, taking a reference in the callback " -"to the about-to-be-destroyed code object will resurrect it and prevent it " -"from being freed at this time. When the resurrected object is destroyed " -"later, any watcher callbacks active at that time will be called again." -msgstr "" - -#: ../../c-api/code.rst:194 -msgid "" -"Users of this API should not rely on internal runtime implementation " -"details. Such details may include, but are not limited to, the exact order " -"and timing of creation and destruction of code objects. While changes in " -"these details may result in differences observable by watchers (including " -"whether a callback is invoked or not), it does not change the semantics of " -"the Python code being executed." -msgstr "" - -#: ../../c-api/code.rst:201 -msgid "" -"If the callback sets an exception, it must return ``-1``; this exception " -"will be printed as an unraisable exception using :c:func:" -"`PyErr_WriteUnraisable`. Otherwise it should return ``0``." -msgstr "" - -#: ../../c-api/code.rst:205 -msgid "" -"There may already be a pending exception set on entry to the callback. In " -"this case, the callback should return ``0`` with the same exception still " -"set. This means the callback may not call any other API that can set an " -"exception unless it saves and clears the exception state first, and restores " -"it before returning." -msgstr "" - -#: ../../c-api/code.rst:216 -msgid "This is a :term:`soft deprecated` function that does nothing." -msgstr "" - -#: ../../c-api/code.rst:218 -msgid "" -"Prior to Python 3.10, this function would perform basic optimizations to a " -"code object." -msgstr "" - -#: ../../c-api/code.rst:221 -msgid "This function now does nothing." -msgstr "" - -#: ../../c-api/code.rst:228 -msgid "Code Object Flags" -msgstr "程式碼物件旗標" - -#: ../../c-api/code.rst:230 -msgid "" -"Code objects contain a bit-field of flags, which can be retrieved as the :" -"attr:`~codeobject.co_flags` Python attribute (for example using :c:func:" -"`PyObject_GetAttrString`), and set using a *flags* argument to :c:func:" -"`PyUnstable_Code_New` and similar functions." -msgstr "" - -#: ../../c-api/code.rst:235 -msgid "" -"Flags whose names start with ``CO_FUTURE_`` correspond to features normally " -"selectable by :ref:`future statements `. These flags can be used in :" -"c:member:`PyCompilerFlags.cf_flags`. Note that many ``CO_FUTURE_`` flags are " -"mandatory in current versions of Python, and setting them has no effect." -msgstr "" - -#: ../../c-api/code.rst:241 -msgid "" -"The following flags are available. For their meaning, see the linked " -"documentation of their Python equivalents." -msgstr "" - -#: ../../c-api/code.rst:249 -msgid "Flag" -msgstr "旗標" - -#: ../../c-api/code.rst:250 -msgid "Meaning" -msgstr "意義" - -#: ../../c-api/code.rst:252 -msgid ":py:data:`inspect.CO_OPTIMIZED`" -msgstr ":py:data:`inspect.CO_OPTIMIZED`" - -#: ../../c-api/code.rst:254 -msgid ":py:data:`inspect.CO_NEWLOCALS`" -msgstr ":py:data:`inspect.CO_NEWLOCALS`" - -#: ../../c-api/code.rst:256 -msgid ":py:data:`inspect.CO_VARARGS`" -msgstr ":py:data:`inspect.CO_VARARGS`" - -#: ../../c-api/code.rst:258 -msgid ":py:data:`inspect.CO_VARKEYWORDS`" -msgstr ":py:data:`inspect.CO_VARKEYWORDS`" - -#: ../../c-api/code.rst:260 -msgid ":py:data:`inspect.CO_NESTED`" -msgstr ":py:data:`inspect.CO_NESTED`" - -#: ../../c-api/code.rst:262 -msgid ":py:data:`inspect.CO_GENERATOR`" -msgstr ":py:data:`inspect.CO_GENERATOR`" - -#: ../../c-api/code.rst:264 -msgid ":py:data:`inspect.CO_COROUTINE`" -msgstr ":py:data:`inspect.CO_COROUTINE`" - -#: ../../c-api/code.rst:266 -msgid ":py:data:`inspect.CO_ITERABLE_COROUTINE`" -msgstr ":py:data:`inspect.CO_ITERABLE_COROUTINE`" - -#: ../../c-api/code.rst:268 -msgid ":py:data:`inspect.CO_ASYNC_GENERATOR`" -msgstr ":py:data:`inspect.CO_ASYNC_GENERATOR`" - -#: ../../c-api/code.rst:270 -msgid ":py:data:`inspect.CO_HAS_DOCSTRING`" -msgstr ":py:data:`inspect.CO_HAS_DOCSTRING`" - -#: ../../c-api/code.rst:272 -msgid ":py:data:`inspect.CO_METHOD`" -msgstr ":py:data:`inspect.CO_METHOD`" - -#: ../../c-api/code.rst:275 -msgid "no effect (:py:data:`__future__.division`)" -msgstr "無效果（:py:data:`__future__.division`）" - -#: ../../c-api/code.rst:277 -msgid "no effect (:py:data:`__future__.absolute_import`)" -msgstr "無效果（:py:data:`__future__.absolute_import`）" - -#: ../../c-api/code.rst:279 -msgid "no effect (:py:data:`__future__.with_statement`)" -msgstr "無效果（:py:data:`__future__.with_statement`）" - -#: ../../c-api/code.rst:281 -msgid "no effect (:py:data:`__future__.print_function`)" -msgstr "無效果（:py:data:`__future__.print_function`）" - -#: ../../c-api/code.rst:283 -msgid "no effect (:py:data:`__future__.unicode_literals`)" -msgstr "無效果（:py:data:`__future__.unicode_literals`）" - -#: ../../c-api/code.rst:285 -msgid "no effect (:py:data:`__future__.generator_stop`)" -msgstr "無效果（:py:data:`__future__.generator_stop`）" - -#: ../../c-api/code.rst:287 -msgid ":py:data:`__future__.annotations`" -msgstr ":py:data:`__future__.annotations`" - -#: ../../c-api/code.rst:291 -msgid "Extra information" -msgstr "額外資訊" - -#: ../../c-api/code.rst:293 -msgid "" -"To support low-level extensions to frame evaluation, such as external just-" -"in-time compilers, it is possible to attach arbitrary extra data to code " -"objects." -msgstr "" - -#: ../../c-api/code.rst:297 -msgid "" -"These functions are part of the unstable C API tier: this functionality is a " -"CPython implementation detail, and the API may change without deprecation " -"warnings." -msgstr "" - -#: ../../c-api/code.rst:303 -msgid "Return a new opaque index value used to adding data to code objects." -msgstr "" - -#: ../../c-api/code.rst:305 -msgid "" -"You generally call this function once (per interpreter) and use the result " -"with ``PyCode_GetExtra`` and ``PyCode_SetExtra`` to manipulate data on " -"individual code objects." -msgstr "" - -#: ../../c-api/code.rst:309 -msgid "" -"If *free* is not ``NULL``: when a code object is deallocated, *free* will be " -"called on non-``NULL`` data stored under the new index. Use :c:func:" -"`Py_DecRef` when storing :c:type:`PyObject`." -msgstr "" - -#: ../../c-api/code.rst:315 -msgid "as ``_PyEval_RequestCodeExtraIndex``" -msgstr "" - -#: ../../c-api/code.rst:319 -msgid "" -"Renamed to ``PyUnstable_Eval_RequestCodeExtraIndex``. The old private name " -"is deprecated, but will be available until the API changes." -msgstr "" - -#: ../../c-api/code.rst:325 -msgid "" -"Set *extra* to the extra data stored under the given index. Return 0 on " -"success. Set an exception and return -1 on failure." -msgstr "" - -#: ../../c-api/code.rst:328 -msgid "" -"If no data was set under the index, set *extra* to ``NULL`` and return 0 " -"without setting an exception." -msgstr "" - -#: ../../c-api/code.rst:333 -msgid "as ``_PyCode_GetExtra``" -msgstr "" - -#: ../../c-api/code.rst:337 -msgid "" -"Renamed to ``PyUnstable_Code_GetExtra``. The old private name is deprecated, " -"but will be available until the API changes." -msgstr "" - -#: ../../c-api/code.rst:343 -msgid "" -"Set the extra data stored under the given index to *extra*. Return 0 on " -"success. Set an exception and return -1 on failure." -msgstr "" - -#: ../../c-api/code.rst:348 -msgid "as ``_PyCode_SetExtra``" -msgstr "" - -#: ../../c-api/code.rst:352 -msgid "" -"Renamed to ``PyUnstable_Code_SetExtra``. The old private name is deprecated, " -"but will be available until the API changes." -msgstr "" - -#: ../../c-api/code.rst:3 -msgid "object" -msgstr "object（物件）" - -#: ../../c-api/code.rst:3 -msgid "code" -msgstr "code（程式碼）" - -#: ../../c-api/code.rst:3 -msgid "code object" -msgstr "code object（程式碼物件）" - -#: ../../c-api/code.rst:64 -msgid "PyCode_New (C function)" -msgstr "PyCode_New（C 函式）" - -#: ../../c-api/code.rst:77 -msgid "PyCode_NewWithPosOnlyArgs (C function)" -msgstr "PyCode_NewWithPosOnlyArgs（C 函式）" - -#: ../../c-api/code.rst:313 -msgid "_PyEval_RequestCodeExtraIndex (C function)" -msgstr "_PyEval_RequestCodeExtraIndex（C 函式）" - -#: ../../c-api/code.rst:331 -msgid "_PyCode_GetExtra (C function)" -msgstr "_PyCode_GetExtra（C 函式）" - -#: ../../c-api/code.rst:346 -msgid "_PyCode_SetExtra (C function)" -msgstr "_PyCode_SetExtra（C 函式）" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-13 23:16+0000\n" +"PO-Revision-Date: 2015-12-09 17:51+0000\n" +"Last-Translator: Liang-Bo Wang \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" + +#: ../../c-api/code.rst:8 +msgid "Code Objects" +msgstr "程式碼物件" + +#: ../../c-api/code.rst:12 +msgid "" +"Code objects are a low-level detail of the CPython implementation. Each one " +"represents a chunk of executable code that hasn't yet been bound into a " +"function." +msgstr "" + +#: ../../c-api/code.rst:18 +msgid "" +"The C structure of the objects used to describe code objects. The fields of " +"this type are subject to change at any time." +msgstr "" + +#: ../../c-api/code.rst:24 +msgid "" +"This is an instance of :c:type:`PyTypeObject` representing the Python :ref:" +"`code object `." +msgstr "" + +#: ../../c-api/code.rst:30 +msgid "" +"Return true if *co* is a :ref:`code object `. This function " +"always succeeds." +msgstr "" + +#: ../../c-api/code.rst:35 +msgid "" +"Return the number of :term:`free (closure) variables ` in " +"a code object." +msgstr "" + +#: ../../c-api/code.rst:40 +msgid "" +"Return the position of the first :term:`free (closure) variable ` in a code object." +msgstr "" + +#: ../../c-api/code.rst:45 +msgid "" +"Renamed from ``PyCode_GetFirstFree`` as part of :ref:`unstable-c-api`. The " +"old name is deprecated, but will remain available until the signature " +"changes again." +msgstr "" + +#: ../../c-api/code.rst:51 +msgid "" +"Return a new code object. If you need a dummy code object to create a " +"frame, use :c:func:`PyCode_NewEmpty` instead." +msgstr "" + +#: ../../c-api/code.rst:54 +msgid "" +"Since the definition of the bytecode changes often, calling :c:func:" +"`PyUnstable_Code_New` directly can bind you to a precise Python version." +msgstr "" + +#: ../../c-api/code.rst:57 +msgid "" +"The many arguments of this function are inter-dependent in complex ways, " +"meaning that subtle changes to values are likely to result in incorrect " +"execution or VM crashes. Use this function only with extreme care." +msgstr "" + +#: ../../c-api/code.rst:61 +msgid "Added ``qualname`` and ``exceptiontable`` parameters." +msgstr "新增 ``qualname`` 和 ``exceptiontable`` 參數。" + +#: ../../c-api/code.rst:68 +msgid "" +"Renamed from ``PyCode_New`` as part of :ref:`unstable-c-api`. The old name " +"is deprecated, but will remain available until the signature changes again." +msgstr "" + +#: ../../c-api/code.rst:74 +msgid "" +"Similar to :c:func:`PyUnstable_Code_New`, but with an extra " +"\"posonlyargcount\" for positional-only arguments. The same caveats that " +"apply to ``PyUnstable_Code_New`` also apply to this function." +msgstr "" + +#: ../../c-api/code.rst:79 +msgid "as ``PyCode_NewWithPosOnlyArgs``" +msgstr "" + +#: ../../c-api/code.rst:81 +msgid "Added ``qualname`` and ``exceptiontable`` parameters." +msgstr "新增 ``qualname`` 和 ``exceptiontable`` 參數。" + +#: ../../c-api/code.rst:86 +msgid "" +"Renamed to ``PyUnstable_Code_NewWithPosOnlyArgs``. The old name is " +"deprecated, but will remain available until the signature changes again." +msgstr "" + +#: ../../c-api/code.rst:92 +msgid "" +"Return a new empty code object with the specified filename, function name, " +"and first line number. The resulting code object will raise an ``Exception`` " +"if executed." +msgstr "" + +#: ../../c-api/code.rst:98 +msgid "" +"Return the line number of the instruction that occurs on or before " +"``byte_offset`` and ends after it. If you just need the line number of a " +"frame, use :c:func:`PyFrame_GetLineNumber` instead." +msgstr "" + +#: ../../c-api/code.rst:101 +msgid "" +"For efficiently iterating over the line numbers in a code object, use :pep:" +"`the API described in PEP 626 <0626#out-of-process-debuggers-and-profilers>`." +msgstr "" + +#: ../../c-api/code.rst:106 +msgid "" +"Sets the passed ``int`` pointers to the source code line and column numbers " +"for the instruction at ``byte_offset``. Sets the value to ``0`` when " +"information is not available for any particular element." +msgstr "" + +#: ../../c-api/code.rst:110 +msgid "Returns ``1`` if the function succeeds and 0 otherwise." +msgstr "如果函式成功則回傳 ``1``，否則回傳 ``0``。" + +#: ../../c-api/code.rst:116 +msgid "" +"Equivalent to the Python code ``getattr(co, 'co_code')``. Returns a strong " +"reference to a :c:type:`PyBytesObject` representing the bytecode in a code " +"object. On error, ``NULL`` is returned and an exception is raised." +msgstr "" + +#: ../../c-api/code.rst:121 +msgid "" +"This ``PyBytesObject`` may be created on-demand by the interpreter and does " +"not necessarily represent the bytecode actually executed by CPython. The " +"primary use case for this function is debuggers and profilers." +msgstr "" + +#: ../../c-api/code.rst:129 +msgid "" +"Equivalent to the Python code ``getattr(co, 'co_varnames')``. Returns a new " +"reference to a :c:type:`PyTupleObject` containing the names of the local " +"variables. On error, ``NULL`` is returned and an exception is raised." +msgstr "" + +#: ../../c-api/code.rst:138 +msgid "" +"Equivalent to the Python code ``getattr(co, 'co_cellvars')``. Returns a new " +"reference to a :c:type:`PyTupleObject` containing the names of the local " +"variables that are referenced by nested functions. On error, ``NULL`` is " +"returned and an exception is raised." +msgstr "" + +#: ../../c-api/code.rst:147 +msgid "" +"Equivalent to the Python code ``getattr(co, 'co_freevars')``. Returns a new " +"reference to a :c:type:`PyTupleObject` containing the names of the :term:" +"`free (closure) variables `. On error, ``NULL`` is " +"returned and an exception is raised." +msgstr "" + +#: ../../c-api/code.rst:156 +msgid "" +"Register *callback* as a code object watcher for the current interpreter. " +"Return an ID which may be passed to :c:func:`PyCode_ClearWatcher`. In case " +"of error (e.g. no more watcher IDs available), return ``-1`` and set an " +"exception." +msgstr "" + +#: ../../c-api/code.rst:165 +msgid "" +"Clear watcher identified by *watcher_id* previously returned from :c:func:" +"`PyCode_AddWatcher` for the current interpreter. Return ``0`` on success, or " +"``-1`` and set an exception on error (e.g. if the given *watcher_id* was " +"never registered.)" +msgstr "" + +#: ../../c-api/code.rst:174 +msgid "" +"Enumeration of possible code object watcher events: - " +"``PY_CODE_EVENT_CREATE`` - ``PY_CODE_EVENT_DESTROY``" +msgstr "" + +#: ../../c-api/code.rst:182 +msgid "Type of a code object watcher callback function." +msgstr "" + +#: ../../c-api/code.rst:184 +msgid "" +"If *event* is ``PY_CODE_EVENT_CREATE``, then the callback is invoked after " +"*co* has been fully initialized. Otherwise, the callback is invoked before " +"the destruction of *co* takes place, so the prior state of *co* can be " +"inspected." +msgstr "" + +#: ../../c-api/code.rst:189 +msgid "" +"If *event* is ``PY_CODE_EVENT_DESTROY``, taking a reference in the callback " +"to the about-to-be-destroyed code object will resurrect it and prevent it " +"from being freed at this time. When the resurrected object is destroyed " +"later, any watcher callbacks active at that time will be called again." +msgstr "" + +#: ../../c-api/code.rst:194 +msgid "" +"Users of this API should not rely on internal runtime implementation " +"details. Such details may include, but are not limited to, the exact order " +"and timing of creation and destruction of code objects. While changes in " +"these details may result in differences observable by watchers (including " +"whether a callback is invoked or not), it does not change the semantics of " +"the Python code being executed." +msgstr "" + +#: ../../c-api/code.rst:201 +msgid "" +"If the callback sets an exception, it must return ``-1``; this exception " +"will be printed as an unraisable exception using :c:func:" +"`PyErr_WriteUnraisable`. Otherwise it should return ``0``." +msgstr "" + +#: ../../c-api/code.rst:205 +msgid "" +"There may already be a pending exception set on entry to the callback. In " +"this case, the callback should return ``0`` with the same exception still " +"set. This means the callback may not call any other API that can set an " +"exception unless it saves and clears the exception state first, and restores " +"it before returning." +msgstr "" + +#: ../../c-api/code.rst:216 +msgid "This is a :term:`soft deprecated` function that does nothing." +msgstr "" + +#: ../../c-api/code.rst:218 +msgid "" +"Prior to Python 3.10, this function would perform basic optimizations to a " +"code object." +msgstr "" + +#: ../../c-api/code.rst:221 +msgid "This function now does nothing." +msgstr "" + +#: ../../c-api/code.rst:228 +msgid "Code Object Flags" +msgstr "程式碼物件旗標" + +#: ../../c-api/code.rst:230 +msgid "" +"Code objects contain a bit-field of flags, which can be retrieved as the :" +"attr:`~codeobject.co_flags` Python attribute (for example using :c:func:" +"`PyObject_GetAttrString`), and set using a *flags* argument to :c:func:" +"`PyUnstable_Code_New` and similar functions." +msgstr "" + +#: ../../c-api/code.rst:235 +msgid "" +"Flags whose names start with ``CO_FUTURE_`` correspond to features normally " +"selectable by :ref:`future statements `. These flags can be used in :" +"c:member:`PyCompilerFlags.cf_flags`. Note that many ``CO_FUTURE_`` flags are " +"mandatory in current versions of Python, and setting them has no effect." +msgstr "" + +#: ../../c-api/code.rst:241 +msgid "" +"The following flags are available. For their meaning, see the linked " +"documentation of their Python equivalents." +msgstr "" + +#: ../../c-api/code.rst:249 +msgid "Flag" +msgstr "旗標" + +#: ../../c-api/code.rst:250 +msgid "Meaning" +msgstr "意義" + +#: ../../c-api/code.rst:252 +msgid ":py:data:`inspect.CO_OPTIMIZED`" +msgstr ":py:data:`inspect.CO_OPTIMIZED`" + +#: ../../c-api/code.rst:254 +msgid ":py:data:`inspect.CO_NEWLOCALS`" +msgstr ":py:data:`inspect.CO_NEWLOCALS`" + +#: ../../c-api/code.rst:256 +msgid ":py:data:`inspect.CO_VARARGS`" +msgstr ":py:data:`inspect.CO_VARARGS`" + +#: ../../c-api/code.rst:258 +msgid ":py:data:`inspect.CO_VARKEYWORDS`" +msgstr ":py:data:`inspect.CO_VARKEYWORDS`" + +#: ../../c-api/code.rst:260 +msgid ":py:data:`inspect.CO_NESTED`" +msgstr ":py:data:`inspect.CO_NESTED`" + +#: ../../c-api/code.rst:262 +msgid ":py:data:`inspect.CO_GENERATOR`" +msgstr ":py:data:`inspect.CO_GENERATOR`" + +#: ../../c-api/code.rst:264 +msgid ":py:data:`inspect.CO_COROUTINE`" +msgstr ":py:data:`inspect.CO_COROUTINE`" + +#: ../../c-api/code.rst:266 +msgid ":py:data:`inspect.CO_ITERABLE_COROUTINE`" +msgstr ":py:data:`inspect.CO_ITERABLE_COROUTINE`" + +#: ../../c-api/code.rst:268 +msgid ":py:data:`inspect.CO_ASYNC_GENERATOR`" +msgstr ":py:data:`inspect.CO_ASYNC_GENERATOR`" + +#: ../../c-api/code.rst:270 +msgid ":py:data:`inspect.CO_HAS_DOCSTRING`" +msgstr ":py:data:`inspect.CO_HAS_DOCSTRING`" + +#: ../../c-api/code.rst:272 +msgid ":py:data:`inspect.CO_METHOD`" +msgstr ":py:data:`inspect.CO_METHOD`" + +#: ../../c-api/code.rst:275 +msgid "no effect (:py:data:`__future__.division`)" +msgstr "無效果（:py:data:`__future__.division`）" + +#: ../../c-api/code.rst:277 +msgid "no effect (:py:data:`__future__.absolute_import`)" +msgstr "無效果（:py:data:`__future__.absolute_import`）" + +#: ../../c-api/code.rst:279 +msgid "no effect (:py:data:`__future__.with_statement`)" +msgstr "無效果（:py:data:`__future__.with_statement`）" + +#: ../../c-api/code.rst:281 +msgid "no effect (:py:data:`__future__.print_function`)" +msgstr "無效果（:py:data:`__future__.print_function`）" + +#: ../../c-api/code.rst:283 +msgid "no effect (:py:data:`__future__.unicode_literals`)" +msgstr "無效果（:py:data:`__future__.unicode_literals`）" + +#: ../../c-api/code.rst:285 +msgid "no effect (:py:data:`__future__.generator_stop`)" +msgstr "無效果（:py:data:`__future__.generator_stop`）" + +#: ../../c-api/code.rst:287 +msgid ":py:data:`__future__.annotations`" +msgstr ":py:data:`__future__.annotations`" + +#: ../../c-api/code.rst:291 +msgid "Extra information" +msgstr "額外資訊" + +#: ../../c-api/code.rst:293 +msgid "" +"To support low-level extensions to frame evaluation, such as external just-" +"in-time compilers, it is possible to attach arbitrary extra data to code " +"objects." +msgstr "" + +#: ../../c-api/code.rst:297 +msgid "" +"These functions are part of the unstable C API tier: this functionality is a " +"CPython implementation detail, and the API may change without deprecation " +"warnings." +msgstr "" + +#: ../../c-api/code.rst:303 +msgid "Return a new opaque index value used to adding data to code objects." +msgstr "" + +#: ../../c-api/code.rst:305 +msgid "" +"You generally call this function once (per interpreter) and use the result " +"with ``PyCode_GetExtra`` and ``PyCode_SetExtra`` to manipulate data on " +"individual code objects." +msgstr "" + +#: ../../c-api/code.rst:309 +msgid "" +"If *free* is not ``NULL``: when a code object is deallocated, *free* will be " +"called on non-``NULL`` data stored under the new index. Use :c:func:" +"`Py_DecRef` when storing :c:type:`PyObject`." +msgstr "" + +#: ../../c-api/code.rst:315 +msgid "as ``_PyEval_RequestCodeExtraIndex``" +msgstr "" + +#: ../../c-api/code.rst:319 +msgid "" +"Renamed to ``PyUnstable_Eval_RequestCodeExtraIndex``. The old private name " +"is deprecated, but will be available until the API changes." +msgstr "" + +#: ../../c-api/code.rst:325 +msgid "" +"Set *extra* to the extra data stored under the given index. Return 0 on " +"success. Set an exception and return -1 on failure." +msgstr "" + +#: ../../c-api/code.rst:328 +msgid "" +"If no data was set under the index, set *extra* to ``NULL`` and return 0 " +"without setting an exception." +msgstr "" + +#: ../../c-api/code.rst:333 +msgid "as ``_PyCode_GetExtra``" +msgstr "" + +#: ../../c-api/code.rst:337 +msgid "" +"Renamed to ``PyUnstable_Code_GetExtra``. The old private name is deprecated, " +"but will be available until the API changes." +msgstr "" + +#: ../../c-api/code.rst:343 +msgid "" +"Set the extra data stored under the given index to *extra*. Return 0 on " +"success. Set an exception and return -1 on failure." +msgstr "" + +#: ../../c-api/code.rst:348 +msgid "as ``_PyCode_SetExtra``" +msgstr "" + +#: ../../c-api/code.rst:352 +msgid "" +"Renamed to ``PyUnstable_Code_SetExtra``. The old private name is deprecated, " +"but will be available until the API changes." +msgstr "" + +#: ../../c-api/code.rst:3 +msgid "object" +msgstr "object（物件）" + +#: ../../c-api/code.rst:3 +msgid "code" +msgstr "code（程式碼）" + +#: ../../c-api/code.rst:3 +msgid "code object" +msgstr "code object（程式碼物件）" + +#: ../../c-api/code.rst:64 +msgid "PyCode_New (C function)" +msgstr "PyCode_New（C 函式）" + +#: ../../c-api/code.rst:77 +msgid "PyCode_NewWithPosOnlyArgs (C function)" +msgstr "PyCode_NewWithPosOnlyArgs（C 函式）" + +#: ../../c-api/code.rst:313 +msgid "_PyEval_RequestCodeExtraIndex (C function)" +msgstr "_PyEval_RequestCodeExtraIndex（C 函式）" + +#: ../../c-api/code.rst:331 +msgid "_PyCode_GetExtra (C function)" +msgstr "_PyCode_GetExtra（C 函式）" + +#: ../../c-api/code.rst:346 +msgid "_PyCode_SetExtra (C function)" +msgstr "_PyCode_SetExtra（C 函式）" diff --git a/c-api/codec.po b/c-api/codec.po index 9ca1d563d0..fa4f145ecd 100644 --- a/c-api/codec.po +++ b/c-api/codec.po @@ -1,211 +1,211 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Matt Wang , 2023 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-07 00:14+0000\n" -"PO-Revision-Date: 2023-07-24 17:51+0000\n" -"Last-Translator: Matt Wang \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" - -#: ../../c-api/codec.rst:4 -msgid "Codec registry and support functions" -msgstr "編解碼器註冊表和支援函式" - -#: ../../c-api/codec.rst:8 -msgid "Register a new codec search function." -msgstr "註冊一個新的編解碼器搜尋函式。" - -#: ../../c-api/codec.rst:10 -msgid "" -"As a side effect, this tries to load the :mod:`!encodings` package, if not " -"yet done, to make sure that it is always first in the list of search " -"functions." -msgstr "" -"作為副作用 (side effect)，這會嘗試載入 :mod:`!encodings`\\ （如果尚未完成），" -"以確保它始終位於搜尋函式列表中的第一個。" - -#: ../../c-api/codec.rst:15 -msgid "" -"Unregister a codec search function and clear the registry's cache. If the " -"search function is not registered, do nothing. Return 0 on success. Raise an " -"exception and return -1 on error." -msgstr "" -"取消註冊編解碼器搜尋函式並清除註冊表 (registry) 的快取。如果搜尋函式並未被註" -"冊，則不執行任何操作。成功回傳 0，發生錯誤時會引發例外並回傳 -1。" - -#: ../../c-api/codec.rst:23 -msgid "" -"Return ``1`` or ``0`` depending on whether there is a registered codec for " -"the given *encoding*. This function always succeeds." -msgstr "" -"回傳 ``1`` 或 ``0``，具體取決於是否有給定 *encoding* 的已註冊編解碼器。這個函" -"式總會成功。" - -#: ../../c-api/codec.rst:28 -msgid "Generic codec based encoding API." -msgstr "基於泛用編解碼器的編碼 API。" - -#: ../../c-api/codec.rst:30 -msgid "" -"*object* is passed through the encoder function found for the given " -"*encoding* using the error handling method defined by *errors*. *errors* " -"may be ``NULL`` to use the default method defined for the codec. Raises a :" -"exc:`LookupError` if no encoder can be found." -msgstr "" -"*object* 被傳遞給以給定 *encoding* 所查找到的編碼器函式，並使用以 *errors* 定" -"義的錯誤處理方法。*errors* 可以設為 ``NULL`` 來使用編解碼器定義的預設方法。如" -"果找不到編碼器，則引發 :exc:`LookupError`。" - -#: ../../c-api/codec.rst:37 -msgid "Generic codec based decoding API." -msgstr "基於泛用編解碼器的解碼 API。" - -#: ../../c-api/codec.rst:39 -msgid "" -"*object* is passed through the decoder function found for the given " -"*encoding* using the error handling method defined by *errors*. *errors* " -"may be ``NULL`` to use the default method defined for the codec. Raises a :" -"exc:`LookupError` if no decoder can be found." -msgstr "" -"*object* 被傳遞給以給定 *encoding* 所查找到的解碼器函式，並使用以 *errors* 定" -"義的錯誤處理方法。*errors* 可以設為 ``NULL`` 來使用編解碼器定義的預設方法。如" -"果找不到解碼器，則引發 :exc:`LookupError`。" - -#: ../../c-api/codec.rst:46 -msgid "Codec lookup API" -msgstr "編解碼器查找 API" - -#: ../../c-api/codec.rst:48 -msgid "" -"In the following functions, the *encoding* string is looked up converted to " -"all lower-case characters, which makes encodings looked up through this " -"mechanism effectively case-insensitive. If no codec is found, a :exc:" -"`KeyError` is set and ``NULL`` returned." -msgstr "" -"在以下函式中，查找的 *encoding* 字串的所有字元將轉換為小寫，這使得透過此機制" -"查找的編碼可以不區分大小寫而更有效率。如果未找到編解碼器，則會設定 :exc:" -"`KeyError` 並回傳 ``NULL``。" - -#: ../../c-api/codec.rst:55 -msgid "Get an encoder function for the given *encoding*." -msgstr "取得給定 *encoding* 的編碼器函式。" - -#: ../../c-api/codec.rst:59 -msgid "Get a decoder function for the given *encoding*." -msgstr "取得給定 *encoding* 的解碼器函式。" - -#: ../../c-api/codec.rst:63 -msgid "" -"Get an :class:`~codecs.IncrementalEncoder` object for the given *encoding*." -msgstr "取得給定 *encoding* 的 :class:`~codecs.IncrementalEncoder` 物件。" - -#: ../../c-api/codec.rst:67 -msgid "" -"Get an :class:`~codecs.IncrementalDecoder` object for the given *encoding*." -msgstr "取得給定 *encoding* 的 :class:`~codecs.IncrementalDecoder` 物件。" - -#: ../../c-api/codec.rst:71 -msgid "" -"Get a :class:`~codecs.StreamReader` factory function for the given " -"*encoding*." -msgstr "取得給定 *encoding* 的 :class:`~codecs.StreamReader` 工廠函式。" - -#: ../../c-api/codec.rst:75 -msgid "" -"Get a :class:`~codecs.StreamWriter` factory function for the given " -"*encoding*." -msgstr "取得給定 *encoding* 的 :class:`~codecs.StreamWriter` 工廠函式。" - -#: ../../c-api/codec.rst:79 -msgid "Registry API for Unicode encoding error handlers" -msgstr "用於 Unicode 編碼錯誤處理程式的註冊 API" - -#: ../../c-api/codec.rst:83 -msgid "" -"Register the error handling callback function *error* under the given " -"*name*. This callback function will be called by a codec when it encounters " -"unencodable characters/undecodable bytes and *name* is specified as the " -"error parameter in the call to the encode/decode function." -msgstr "" -"在給定的 *name* 下註冊錯誤處理回呼 (callback) 函式 *error*。當編解碼器遇到無" -"法編碼的字元/無法解碼的位元組並且 *name* 被指定為呼叫編碼/解碼函式時的錯誤參" -"數時，將呼叫此回呼函式。" - -#: ../../c-api/codec.rst:88 -msgid "" -"The callback gets a single argument, an instance of :exc:" -"`UnicodeEncodeError`, :exc:`UnicodeDecodeError` or :exc:" -"`UnicodeTranslateError` that holds information about the problematic " -"sequence of characters or bytes and their offset in the original string " -"(see :ref:`unicodeexceptions` for functions to extract this information). " -"The callback must either raise the given exception, or return a two-item " -"tuple containing the replacement for the problematic sequence, and an " -"integer giving the offset in the original string at which encoding/decoding " -"should be resumed." -msgstr "" -"回呼取得單個引數，即 :exc:`UnicodeEncodeError`、:exc:`UnicodeDecodeError` " -"或 :exc:`UnicodeTranslateError` 的實例，其中包含關於有問題的字元或位元組序列" -"及其在原始字串中偏移量的資訊（有關取得此資訊的函式，請參閱 :ref:" -"`unicodeexceptions`）。回呼必須引發給定的例外，或者回傳一個包含有問題序列的替" -"換的二元組 (two-item tuple)，以及一個代表原始字串中應該被恢復的編碼/解碼偏移" -"量的整數。" - -#: ../../c-api/codec.rst:98 -msgid "Return ``0`` on success, ``-1`` on error." -msgstr "成功時回傳 ``0``，錯誤時回傳 ``-1``。" - -#: ../../c-api/codec.rst:102 -msgid "" -"Lookup the error handling callback function registered under *name*. As a " -"special case ``NULL`` can be passed, in which case the error handling " -"callback for \"strict\" will be returned." -msgstr "" -"查找 *name* 下已註冊的錯誤處理回呼函式。作為一種特殊情況，可以傳遞 ``NULL``，" -"在這種情況下，將回傳 \"strict\" 的錯誤處理回呼。" - -#: ../../c-api/codec.rst:108 -msgid "Raise *exc* as an exception." -msgstr "引發 *exc* 作為例外。" - -#: ../../c-api/codec.rst:112 -msgid "Ignore the unicode error, skipping the faulty input." -msgstr "忽略 unicode 錯誤，跳過錯誤的輸入。" - -#: ../../c-api/codec.rst:116 -msgid "Replace the unicode encode error with ``?`` or ``U+FFFD``." -msgstr "將 unicode 編碼錯誤替換為 ``?`` 或 ``U+FFFD``。" - -#: ../../c-api/codec.rst:120 -msgid "Replace the unicode encode error with XML character references." -msgstr "將 unicode 編碼錯誤替換為 XML 字元參照。" - -#: ../../c-api/codec.rst:124 -msgid "" -"Replace the unicode encode error with backslash escapes (``\\x``, ``\\u`` " -"and ``\\U``)." -msgstr "將 unicode 編碼錯誤替換為反斜線跳脫（``\\x``、``\\u`` 和 ``\\U``）。" - -#: ../../c-api/codec.rst:129 -msgid "Replace the unicode encode error with ``\\N{...}`` escapes." -msgstr "將 unicode 編碼錯誤替換為 ``\\N{...}`` 跳脫。" - -#: ../../c-api/codec.rst:135 -msgid "Codec utility variables" -msgstr "" - -#: ../../c-api/codec.rst:139 -msgid "" -"A string constant containing the lowercase hexadecimal digits: " -"``\"0123456789abcdef\"``." -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Matt Wang , 2023 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-07 00:14+0000\n" +"PO-Revision-Date: 2023-07-24 17:51+0000\n" +"Last-Translator: Matt Wang \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" + +#: ../../c-api/codec.rst:4 +msgid "Codec registry and support functions" +msgstr "編解碼器註冊表和支援函式" + +#: ../../c-api/codec.rst:8 +msgid "Register a new codec search function." +msgstr "註冊一個新的編解碼器搜尋函式。" + +#: ../../c-api/codec.rst:10 +msgid "" +"As a side effect, this tries to load the :mod:`!encodings` package, if not " +"yet done, to make sure that it is always first in the list of search " +"functions." +msgstr "" +"作為副作用 (side effect)，這會嘗試載入 :mod:`!encodings`\\ （如果尚未完成），" +"以確保它始終位於搜尋函式列表中的第一個。" + +#: ../../c-api/codec.rst:15 +msgid "" +"Unregister a codec search function and clear the registry's cache. If the " +"search function is not registered, do nothing. Return 0 on success. Raise an " +"exception and return -1 on error." +msgstr "" +"取消註冊編解碼器搜尋函式並清除註冊表 (registry) 的快取。如果搜尋函式並未被註" +"冊，則不執行任何操作。成功回傳 0，發生錯誤時會引發例外並回傳 -1。" + +#: ../../c-api/codec.rst:23 +msgid "" +"Return ``1`` or ``0`` depending on whether there is a registered codec for " +"the given *encoding*. This function always succeeds." +msgstr "" +"回傳 ``1`` 或 ``0``，具體取決於是否有給定 *encoding* 的已註冊編解碼器。這個函" +"式總會成功。" + +#: ../../c-api/codec.rst:28 +msgid "Generic codec based encoding API." +msgstr "基於泛用編解碼器的編碼 API。" + +#: ../../c-api/codec.rst:30 +msgid "" +"*object* is passed through the encoder function found for the given " +"*encoding* using the error handling method defined by *errors*. *errors* " +"may be ``NULL`` to use the default method defined for the codec. Raises a :" +"exc:`LookupError` if no encoder can be found." +msgstr "" +"*object* 被傳遞給以給定 *encoding* 所查找到的編碼器函式，並使用以 *errors* 定" +"義的錯誤處理方法。*errors* 可以設為 ``NULL`` 來使用編解碼器定義的預設方法。如" +"果找不到編碼器，則引發 :exc:`LookupError`。" + +#: ../../c-api/codec.rst:37 +msgid "Generic codec based decoding API." +msgstr "基於泛用編解碼器的解碼 API。" + +#: ../../c-api/codec.rst:39 +msgid "" +"*object* is passed through the decoder function found for the given " +"*encoding* using the error handling method defined by *errors*. *errors* " +"may be ``NULL`` to use the default method defined for the codec. Raises a :" +"exc:`LookupError` if no decoder can be found." +msgstr "" +"*object* 被傳遞給以給定 *encoding* 所查找到的解碼器函式，並使用以 *errors* 定" +"義的錯誤處理方法。*errors* 可以設為 ``NULL`` 來使用編解碼器定義的預設方法。如" +"果找不到解碼器，則引發 :exc:`LookupError`。" + +#: ../../c-api/codec.rst:46 +msgid "Codec lookup API" +msgstr "編解碼器查找 API" + +#: ../../c-api/codec.rst:48 +msgid "" +"In the following functions, the *encoding* string is looked up converted to " +"all lower-case characters, which makes encodings looked up through this " +"mechanism effectively case-insensitive. If no codec is found, a :exc:" +"`KeyError` is set and ``NULL`` returned." +msgstr "" +"在以下函式中，查找的 *encoding* 字串的所有字元將轉換為小寫，這使得透過此機制" +"查找的編碼可以不區分大小寫而更有效率。如果未找到編解碼器，則會設定 :exc:" +"`KeyError` 並回傳 ``NULL``。" + +#: ../../c-api/codec.rst:55 +msgid "Get an encoder function for the given *encoding*." +msgstr "取得給定 *encoding* 的編碼器函式。" + +#: ../../c-api/codec.rst:59 +msgid "Get a decoder function for the given *encoding*." +msgstr "取得給定 *encoding* 的解碼器函式。" + +#: ../../c-api/codec.rst:63 +msgid "" +"Get an :class:`~codecs.IncrementalEncoder` object for the given *encoding*." +msgstr "取得給定 *encoding* 的 :class:`~codecs.IncrementalEncoder` 物件。" + +#: ../../c-api/codec.rst:67 +msgid "" +"Get an :class:`~codecs.IncrementalDecoder` object for the given *encoding*." +msgstr "取得給定 *encoding* 的 :class:`~codecs.IncrementalDecoder` 物件。" + +#: ../../c-api/codec.rst:71 +msgid "" +"Get a :class:`~codecs.StreamReader` factory function for the given " +"*encoding*." +msgstr "取得給定 *encoding* 的 :class:`~codecs.StreamReader` 工廠函式。" + +#: ../../c-api/codec.rst:75 +msgid "" +"Get a :class:`~codecs.StreamWriter` factory function for the given " +"*encoding*." +msgstr "取得給定 *encoding* 的 :class:`~codecs.StreamWriter` 工廠函式。" + +#: ../../c-api/codec.rst:79 +msgid "Registry API for Unicode encoding error handlers" +msgstr "用於 Unicode 編碼錯誤處理程式的註冊 API" + +#: ../../c-api/codec.rst:83 +msgid "" +"Register the error handling callback function *error* under the given " +"*name*. This callback function will be called by a codec when it encounters " +"unencodable characters/undecodable bytes and *name* is specified as the " +"error parameter in the call to the encode/decode function." +msgstr "" +"在給定的 *name* 下註冊錯誤處理回呼 (callback) 函式 *error*。當編解碼器遇到無" +"法編碼的字元/無法解碼的位元組並且 *name* 被指定為呼叫編碼/解碼函式時的錯誤參" +"數時，將呼叫此回呼函式。" + +#: ../../c-api/codec.rst:88 +msgid "" +"The callback gets a single argument, an instance of :exc:" +"`UnicodeEncodeError`, :exc:`UnicodeDecodeError` or :exc:" +"`UnicodeTranslateError` that holds information about the problematic " +"sequence of characters or bytes and their offset in the original string " +"(see :ref:`unicodeexceptions` for functions to extract this information). " +"The callback must either raise the given exception, or return a two-item " +"tuple containing the replacement for the problematic sequence, and an " +"integer giving the offset in the original string at which encoding/decoding " +"should be resumed." +msgstr "" +"回呼取得單個引數，即 :exc:`UnicodeEncodeError`、:exc:`UnicodeDecodeError` " +"或 :exc:`UnicodeTranslateError` 的實例，其中包含關於有問題的字元或位元組序列" +"及其在原始字串中偏移量的資訊（有關取得此資訊的函式，請參閱 :ref:" +"`unicodeexceptions`）。回呼必須引發給定的例外，或者回傳一個包含有問題序列的替" +"換的二元組 (two-item tuple)，以及一個代表原始字串中應該被恢復的編碼/解碼偏移" +"量的整數。" + +#: ../../c-api/codec.rst:98 +msgid "Return ``0`` on success, ``-1`` on error." +msgstr "成功時回傳 ``0``，錯誤時回傳 ``-1``。" + +#: ../../c-api/codec.rst:102 +msgid "" +"Lookup the error handling callback function registered under *name*. As a " +"special case ``NULL`` can be passed, in which case the error handling " +"callback for \"strict\" will be returned." +msgstr "" +"查找 *name* 下已註冊的錯誤處理回呼函式。作為一種特殊情況，可以傳遞 ``NULL``，" +"在這種情況下，將回傳 \"strict\" 的錯誤處理回呼。" + +#: ../../c-api/codec.rst:108 +msgid "Raise *exc* as an exception." +msgstr "引發 *exc* 作為例外。" + +#: ../../c-api/codec.rst:112 +msgid "Ignore the unicode error, skipping the faulty input." +msgstr "忽略 unicode 錯誤，跳過錯誤的輸入。" + +#: ../../c-api/codec.rst:116 +msgid "Replace the unicode encode error with ``?`` or ``U+FFFD``." +msgstr "將 unicode 編碼錯誤替換為 ``?`` 或 ``U+FFFD``。" + +#: ../../c-api/codec.rst:120 +msgid "Replace the unicode encode error with XML character references." +msgstr "將 unicode 編碼錯誤替換為 XML 字元參照。" + +#: ../../c-api/codec.rst:124 +msgid "" +"Replace the unicode encode error with backslash escapes (``\\x``, ``\\u`` " +"and ``\\U``)." +msgstr "將 unicode 編碼錯誤替換為反斜線跳脫（``\\x``、``\\u`` 和 ``\\U``）。" + +#: ../../c-api/codec.rst:129 +msgid "Replace the unicode encode error with ``\\N{...}`` escapes." +msgstr "將 unicode 編碼錯誤替換為 ``\\N{...}`` 跳脫。" + +#: ../../c-api/codec.rst:135 +msgid "Codec utility variables" +msgstr "" + +#: ../../c-api/codec.rst:139 +msgid "" +"A string constant containing the lowercase hexadecimal digits: " +"``\"0123456789abcdef\"``." +msgstr "" diff --git a/c-api/complex.po b/c-api/complex.po index 6246d71782..fc851fb6e2 100644 --- a/c-api/complex.po +++ b/c-api/complex.po @@ -1,263 +1,263 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Matt Wang , 2023 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: 2015-12-09 17:51+0000\n" -"Last-Translator: Matt Wang \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" - -#: ../../c-api/complex.rst:6 -msgid "Complex Number Objects" -msgstr "複數物件" - -#: ../../c-api/complex.rst:10 -msgid "" -"Python's complex number objects are implemented as two distinct types when " -"viewed from the C API: one is the Python object exposed to Python programs, " -"and the other is a C structure which represents the actual complex number " -"value. The API provides functions for working with both." -msgstr "" -"從 C API 來看，Python 的複數物件被實作為兩種不同的型別：一種是公開給 Python " -"程式的 Python 物件，另一種是表示實際複數值的 C 結構。API 提供了與兩者一起作用" -"的函式。" - -#: ../../c-api/complex.rst:17 -msgid "Complex Numbers as C Structures" -msgstr "作為 C 結構的複數" - -#: ../../c-api/complex.rst:19 -msgid "" -"Note that the functions which accept these structures as parameters and " -"return them as results do so *by value* rather than dereferencing them " -"through pointers. This is consistent throughout the API." -msgstr "" -"請注意，接受這些結構作為參數並將它們作為結果回傳的函式是\\ *按值 (by value)* " -"執行的，而不是透過指標取消參照 (dereference) 它們。這在整個 API 中都是一致" -"的。" - -#: ../../c-api/complex.rst:26 -msgid "" -"The C structure which corresponds to the value portion of a Python complex " -"number object. Most of the functions for dealing with complex number " -"objects use structures of this type as input or output values, as " -"appropriate." -msgstr "" -"相對於 Python 複數物件之數值部分的 C 結構。大多數處理複數物件的函式根據需求會" -"使用這種型別的結構作為輸入或輸出值。" - -#: ../../c-api/complex.rst:33 -msgid "The structure is defined as::" -msgstr "該結構被定義為： ::" - -#: ../../c-api/complex.rst:35 -msgid "" -"typedef struct {\n" -" double real;\n" -" double imag;\n" -"} Py_complex;" -msgstr "" -"typedef struct {\n" -" double real;\n" -" double imag;\n" -"} Py_complex;" - -#: ../../c-api/complex.rst:43 -msgid "" -"Return the sum of two complex numbers, using the C :c:type:`Py_complex` " -"representation." -msgstr "以 C 的 :c:type:`Py_complex` 表示形式來回傳兩個複數之和。" - -#: ../../c-api/complex.rst:49 -msgid "" -"Return the difference between two complex numbers, using the " -"C :c:type:`Py_complex` representation." -msgstr "以 C 的 :c:type:`Py_complex` 表示形式來回傳兩個複數間的差。" - -#: ../../c-api/complex.rst:55 -msgid "" -"Return the negation of the complex number *num*, using the " -"C :c:type:`Py_complex` representation." -msgstr "" -"以 C 的 :c:type:`Py_complex` 表示形式來回傳複數 *num* 的相反數 (negation)。" - -#: ../../c-api/complex.rst:61 -msgid "" -"Return the product of two complex numbers, using the C :c:type:`Py_complex` " -"representation." -msgstr "以 C 的 :c:type:`Py_complex` 表示形式來回傳兩個複數的乘積。" - -#: ../../c-api/complex.rst:67 -msgid "" -"Return the quotient of two complex numbers, using the C :c:type:`Py_complex` " -"representation." -msgstr "以 C 的 :c:type:`Py_complex` 表示形式來回傳兩個複數的商。" - -#: ../../c-api/complex.rst:70 -msgid "" -"If *divisor* is null, this method returns zero and sets :c:data:`errno` " -"to :c:macro:`!EDOM`." -msgstr "" -"如果 *divisor* 為 null，則此方法會回傳零並將 :c:data:`errno` 設定" -"為 :c:macro:`!EDOM`。" - -#: ../../c-api/complex.rst:76 -msgid "" -"Return the exponentiation of *num* by *exp*, using the " -"C :c:type:`Py_complex` representation." -msgstr "" -"以 C 的 :c:type:`Py_complex` 表示形式來回傳 *num* 的 *exp* 次方的結果。" - -#: ../../c-api/complex.rst:79 -msgid "" -"If *num* is null and *exp* is not a positive real number, this method " -"returns zero and sets :c:data:`errno` to :c:macro:`!EDOM`." -msgstr "" -"如果 *num* 為 null 且 *exp* 不是正實數，則此方法會回傳零並將 :c:data:`errno` " -"設定為 :c:macro:`!EDOM`。" - -#: ../../c-api/complex.rst:82 -msgid "Set :c:data:`errno` to :c:macro:`!ERANGE` on overflows." -msgstr "" - -#: ../../c-api/complex.rst:86 -msgid "Complex Numbers as Python Objects" -msgstr "作為 Python 物件的複數" - -#: ../../c-api/complex.rst:91 -msgid "" -"This subtype of :c:type:`PyObject` represents a Python complex number object." -msgstr "這個 :c:type:`PyObject` 的子型別代表一個 Python 複數物件。" - -#: ../../c-api/complex.rst:96 -msgid "" -"This instance of :c:type:`PyTypeObject` represents the Python complex number " -"type. It is the same object as :class:`complex` in the Python layer." -msgstr "" -"這個 :c:type:`PyTypeObject` 的實例代表 Python 複數型別。它與 Python 層中" -"的 :class:`complex` 是同一個物件。" - -#: ../../c-api/complex.rst:102 -msgid "" -"Return true if its argument is a :c:type:`PyComplexObject` or a subtype " -"of :c:type:`PyComplexObject`. This function always succeeds." -msgstr "" -"如果其引數是一個 :c:type:`PyComplexObject` 或者是 :c:type:`PyComplexObject` " -"的子型別，則會回傳 true。這個函式不會失敗。" - -#: ../../c-api/complex.rst:108 -msgid "" -"Return true if its argument is a :c:type:`PyComplexObject`, but not a " -"subtype of :c:type:`PyComplexObject`. This function always succeeds." -msgstr "" -"如果其引數是一個 :c:type:`PyComplexObject`，但不是 :c:type:`PyComplexObject` " -"的子型別，則會回傳 true。這個函式不會失敗。" - -#: ../../c-api/complex.rst:114 -msgid "" -"Create a new Python complex number object from a C :c:type:`Py_complex` " -"value. Return ``NULL`` with an exception set on error." -msgstr "" -"從 C 的 :c:type:`Py_complex` 值建立一個新的 Python 複數物件。在錯誤時回傳 " -"``NULL`` 並設定例外。" - -#: ../../c-api/complex.rst:120 -msgid "" -"Return a new :c:type:`PyComplexObject` object from *real* and *imag*. Return " -"``NULL`` with an exception set on error." -msgstr "" -"從 *real* 和 *imag* 回傳一個新的 :c:type:`PyComplexObject` 物件。在錯誤時回" -"傳 ``NULL`` 並設定例外。" - -#: ../../c-api/complex.rst:126 -msgid "Return the real part of *op* as a C :c:expr:`double`." -msgstr "以 C 的 :c:expr:`double` 形式回傳 *op* 的實部。" - -#: ../../c-api/complex.rst:128 -msgid "" -"If *op* is not a Python complex number object but has " -"a :meth:`~object.__complex__` method, this method will first be called to " -"convert *op* to a Python complex number object. If :meth:`!__complex__` is " -"not defined then it falls back to call :c:func:`PyFloat_AsDouble` and " -"returns its result." -msgstr "" -"如果 *op* 不是 Python 複數物件，但有一個 :meth:`~object.__complex__` 方法，則" -"首先會呼叫該方法將 *op* 轉換為 Python 複數物件。如果 :meth:`!__complex__` 並" -"未定義，那麼它會回退到呼叫 :c:func:`PyFloat_AsDouble` 並回傳其結果。" - -#: ../../c-api/complex.rst:134 ../../c-api/complex.rst:150 -msgid "" -"Upon failure, this method returns ``-1.0`` with an exception set, so one " -"should call :c:func:`PyErr_Occurred` to check for errors." -msgstr "" -"失敗時，此方法回傳 ``-1.0`` 並設定例外，因此應該呼" -"叫 :c:func:`PyErr_Occurred` 來檢查錯誤。" - -#: ../../c-api/complex.rst:137 ../../c-api/complex.rst:153 -msgid "Use :meth:`~object.__complex__` if available." -msgstr "如果可用則使用 :meth:`~object.__complex__`。" - -#: ../../c-api/complex.rst:142 -msgid "Return the imaginary part of *op* as a C :c:expr:`double`." -msgstr "將 *op* 的虛部作為 C 的 :c:expr:`double` 回傳。" - -#: ../../c-api/complex.rst:144 -msgid "" -"If *op* is not a Python complex number object but has " -"a :meth:`~object.__complex__` method, this method will first be called to " -"convert *op* to a Python complex number object. If :meth:`!__complex__` is " -"not defined then it falls back to call :c:func:`PyFloat_AsDouble` and " -"returns ``0.0`` on success." -msgstr "" -"如果 *op* 不是 Python 複數物件，但有一個 :meth:`~object.__complex__` 方法，則" -"首先會呼叫該方法將 *op* 轉換為 Python 複數物件。如果 :meth:`!__complex__` 並" -"未定義，那麼它會回退到呼叫 :c:func:`PyFloat_AsDouble` 並於成功時回傳 ``0.0``。" - -#: ../../c-api/complex.rst:158 -msgid "Return the :c:type:`Py_complex` value of the complex number *op*." -msgstr "回傳複數 *op* 的 :c:type:`Py_complex` 值。" - -#: ../../c-api/complex.rst:160 -msgid "" -"If *op* is not a Python complex number object but has " -"a :meth:`~object.__complex__` method, this method will first be called to " -"convert *op* to a Python complex number object. If :meth:`!__complex__` is " -"not defined then it falls back to :meth:`~object.__float__`. If :meth:`!" -"__float__` is not defined then it falls back to :meth:`~object.__index__`." -msgstr "" -"如果 *op* 不是 Python 複數物件，但有一個 :meth:`~object.__complex__` 方法，則" -"首先會呼叫該方法將 *op* 轉換為 Python 複數物件。如果 :meth:`!__complex__` 並" -"未定義，那麼它會回退到 :meth:`~object.__float__`。如果 :meth:`!__float__` 未" -"定義，則它將繼續回退為 :meth:`~object.__index__`。" - -#: ../../c-api/complex.rst:166 -msgid "" -"Upon failure, this method returns :c:type:`Py_complex` " -"with :c:member:`~Py_complex.real` set to ``-1.0`` and with an exception set, " -"so one should call :c:func:`PyErr_Occurred` to check for errors." -msgstr "" -"失敗時，此方法回傳 :c:type:`Py_complex` 並將 :c:member:`~Py_complex.real` 設" -"為 ``-1.0``，並設定例外，因此應該呼叫 :c:func:`PyErr_Occurred` 來檢查錯誤。" - -#: ../../c-api/complex.rst:170 -msgid "Use :meth:`~object.__index__` if available." -msgstr "如果可用則使用 :meth:`~object.__index__`。" - -#: ../../c-api/complex.rst:8 -msgid "object" -msgstr "object（物件）" - -#: ../../c-api/complex.rst:8 -msgid "complex number" -msgstr "complex number（複數）" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Matt Wang , 2023 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: 2015-12-09 17:51+0000\n" +"Last-Translator: Matt Wang \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" + +#: ../../c-api/complex.rst:6 +msgid "Complex Number Objects" +msgstr "複數物件" + +#: ../../c-api/complex.rst:10 +msgid "" +"Python's complex number objects are implemented as two distinct types when " +"viewed from the C API: one is the Python object exposed to Python programs, " +"and the other is a C structure which represents the actual complex number " +"value. The API provides functions for working with both." +msgstr "" +"從 C API 來看，Python 的複數物件被實作為兩種不同的型別：一種是公開給 Python " +"程式的 Python 物件，另一種是表示實際複數值的 C 結構。API 提供了與兩者一起作用" +"的函式。" + +#: ../../c-api/complex.rst:17 +msgid "Complex Numbers as C Structures" +msgstr "作為 C 結構的複數" + +#: ../../c-api/complex.rst:19 +msgid "" +"Note that the functions which accept these structures as parameters and " +"return them as results do so *by value* rather than dereferencing them " +"through pointers. This is consistent throughout the API." +msgstr "" +"請注意，接受這些結構作為參數並將它們作為結果回傳的函式是\\ *按值 (by value)* " +"執行的，而不是透過指標取消參照 (dereference) 它們。這在整個 API 中都是一致" +"的。" + +#: ../../c-api/complex.rst:26 +msgid "" +"The C structure which corresponds to the value portion of a Python complex " +"number object. Most of the functions for dealing with complex number " +"objects use structures of this type as input or output values, as " +"appropriate." +msgstr "" +"相對於 Python 複數物件之數值部分的 C 結構。大多數處理複數物件的函式根據需求會" +"使用這種型別的結構作為輸入或輸出值。" + +#: ../../c-api/complex.rst:33 +msgid "The structure is defined as::" +msgstr "該結構被定義為： ::" + +#: ../../c-api/complex.rst:35 +msgid "" +"typedef struct {\n" +" double real;\n" +" double imag;\n" +"} Py_complex;" +msgstr "" +"typedef struct {\n" +" double real;\n" +" double imag;\n" +"} Py_complex;" + +#: ../../c-api/complex.rst:43 +msgid "" +"Return the sum of two complex numbers, using the C :c:type:`Py_complex` " +"representation." +msgstr "以 C 的 :c:type:`Py_complex` 表示形式來回傳兩個複數之和。" + +#: ../../c-api/complex.rst:49 +msgid "" +"Return the difference between two complex numbers, using the " +"C :c:type:`Py_complex` representation." +msgstr "以 C 的 :c:type:`Py_complex` 表示形式來回傳兩個複數間的差。" + +#: ../../c-api/complex.rst:55 +msgid "" +"Return the negation of the complex number *num*, using the " +"C :c:type:`Py_complex` representation." +msgstr "" +"以 C 的 :c:type:`Py_complex` 表示形式來回傳複數 *num* 的相反數 (negation)。" + +#: ../../c-api/complex.rst:61 +msgid "" +"Return the product of two complex numbers, using the C :c:type:`Py_complex` " +"representation." +msgstr "以 C 的 :c:type:`Py_complex` 表示形式來回傳兩個複數的乘積。" + +#: ../../c-api/complex.rst:67 +msgid "" +"Return the quotient of two complex numbers, using the C :c:type:`Py_complex` " +"representation." +msgstr "以 C 的 :c:type:`Py_complex` 表示形式來回傳兩個複數的商。" + +#: ../../c-api/complex.rst:70 +msgid "" +"If *divisor* is null, this method returns zero and sets :c:data:`errno` " +"to :c:macro:`!EDOM`." +msgstr "" +"如果 *divisor* 為 null，則此方法會回傳零並將 :c:data:`errno` 設定" +"為 :c:macro:`!EDOM`。" + +#: ../../c-api/complex.rst:76 +msgid "" +"Return the exponentiation of *num* by *exp*, using the " +"C :c:type:`Py_complex` representation." +msgstr "" +"以 C 的 :c:type:`Py_complex` 表示形式來回傳 *num* 的 *exp* 次方的結果。" + +#: ../../c-api/complex.rst:79 +msgid "" +"If *num* is null and *exp* is not a positive real number, this method " +"returns zero and sets :c:data:`errno` to :c:macro:`!EDOM`." +msgstr "" +"如果 *num* 為 null 且 *exp* 不是正實數，則此方法會回傳零並將 :c:data:`errno` " +"設定為 :c:macro:`!EDOM`。" + +#: ../../c-api/complex.rst:82 +msgid "Set :c:data:`errno` to :c:macro:`!ERANGE` on overflows." +msgstr "" + +#: ../../c-api/complex.rst:86 +msgid "Complex Numbers as Python Objects" +msgstr "作為 Python 物件的複數" + +#: ../../c-api/complex.rst:91 +msgid "" +"This subtype of :c:type:`PyObject` represents a Python complex number object." +msgstr "這個 :c:type:`PyObject` 的子型別代表一個 Python 複數物件。" + +#: ../../c-api/complex.rst:96 +msgid "" +"This instance of :c:type:`PyTypeObject` represents the Python complex number " +"type. It is the same object as :class:`complex` in the Python layer." +msgstr "" +"這個 :c:type:`PyTypeObject` 的實例代表 Python 複數型別。它與 Python 層中" +"的 :class:`complex` 是同一個物件。" + +#: ../../c-api/complex.rst:102 +msgid "" +"Return true if its argument is a :c:type:`PyComplexObject` or a subtype " +"of :c:type:`PyComplexObject`. This function always succeeds." +msgstr "" +"如果其引數是一個 :c:type:`PyComplexObject` 或者是 :c:type:`PyComplexObject` " +"的子型別，則會回傳 true。這個函式不會失敗。" + +#: ../../c-api/complex.rst:108 +msgid "" +"Return true if its argument is a :c:type:`PyComplexObject`, but not a " +"subtype of :c:type:`PyComplexObject`. This function always succeeds." +msgstr "" +"如果其引數是一個 :c:type:`PyComplexObject`，但不是 :c:type:`PyComplexObject` " +"的子型別，則會回傳 true。這個函式不會失敗。" + +#: ../../c-api/complex.rst:114 +msgid "" +"Create a new Python complex number object from a C :c:type:`Py_complex` " +"value. Return ``NULL`` with an exception set on error." +msgstr "" +"從 C 的 :c:type:`Py_complex` 值建立一個新的 Python 複數物件。在錯誤時回傳 " +"``NULL`` 並設定例外。" + +#: ../../c-api/complex.rst:120 +msgid "" +"Return a new :c:type:`PyComplexObject` object from *real* and *imag*. Return " +"``NULL`` with an exception set on error." +msgstr "" +"從 *real* 和 *imag* 回傳一個新的 :c:type:`PyComplexObject` 物件。在錯誤時回" +"傳 ``NULL`` 並設定例外。" + +#: ../../c-api/complex.rst:126 +msgid "Return the real part of *op* as a C :c:expr:`double`." +msgstr "以 C 的 :c:expr:`double` 形式回傳 *op* 的實部。" + +#: ../../c-api/complex.rst:128 +msgid "" +"If *op* is not a Python complex number object but has " +"a :meth:`~object.__complex__` method, this method will first be called to " +"convert *op* to a Python complex number object. If :meth:`!__complex__` is " +"not defined then it falls back to call :c:func:`PyFloat_AsDouble` and " +"returns its result." +msgstr "" +"如果 *op* 不是 Python 複數物件，但有一個 :meth:`~object.__complex__` 方法，則" +"首先會呼叫該方法將 *op* 轉換為 Python 複數物件。如果 :meth:`!__complex__` 並" +"未定義，那麼它會回退到呼叫 :c:func:`PyFloat_AsDouble` 並回傳其結果。" + +#: ../../c-api/complex.rst:134 ../../c-api/complex.rst:150 +msgid "" +"Upon failure, this method returns ``-1.0`` with an exception set, so one " +"should call :c:func:`PyErr_Occurred` to check for errors." +msgstr "" +"失敗時，此方法回傳 ``-1.0`` 並設定例外，因此應該呼" +"叫 :c:func:`PyErr_Occurred` 來檢查錯誤。" + +#: ../../c-api/complex.rst:137 ../../c-api/complex.rst:153 +msgid "Use :meth:`~object.__complex__` if available." +msgstr "如果可用則使用 :meth:`~object.__complex__`。" + +#: ../../c-api/complex.rst:142 +msgid "Return the imaginary part of *op* as a C :c:expr:`double`." +msgstr "將 *op* 的虛部作為 C 的 :c:expr:`double` 回傳。" + +#: ../../c-api/complex.rst:144 +msgid "" +"If *op* is not a Python complex number object but has " +"a :meth:`~object.__complex__` method, this method will first be called to " +"convert *op* to a Python complex number object. If :meth:`!__complex__` is " +"not defined then it falls back to call :c:func:`PyFloat_AsDouble` and " +"returns ``0.0`` on success." +msgstr "" +"如果 *op* 不是 Python 複數物件，但有一個 :meth:`~object.__complex__` 方法，則" +"首先會呼叫該方法將 *op* 轉換為 Python 複數物件。如果 :meth:`!__complex__` 並" +"未定義，那麼它會回退到呼叫 :c:func:`PyFloat_AsDouble` 並於成功時回傳 ``0.0``。" + +#: ../../c-api/complex.rst:158 +msgid "Return the :c:type:`Py_complex` value of the complex number *op*." +msgstr "回傳複數 *op* 的 :c:type:`Py_complex` 值。" + +#: ../../c-api/complex.rst:160 +msgid "" +"If *op* is not a Python complex number object but has " +"a :meth:`~object.__complex__` method, this method will first be called to " +"convert *op* to a Python complex number object. If :meth:`!__complex__` is " +"not defined then it falls back to :meth:`~object.__float__`. If :meth:`!" +"__float__` is not defined then it falls back to :meth:`~object.__index__`." +msgstr "" +"如果 *op* 不是 Python 複數物件，但有一個 :meth:`~object.__complex__` 方法，則" +"首先會呼叫該方法將 *op* 轉換為 Python 複數物件。如果 :meth:`!__complex__` 並" +"未定義，那麼它會回退到 :meth:`~object.__float__`。如果 :meth:`!__float__` 未" +"定義，則它將繼續回退為 :meth:`~object.__index__`。" + +#: ../../c-api/complex.rst:166 +msgid "" +"Upon failure, this method returns :c:type:`Py_complex` " +"with :c:member:`~Py_complex.real` set to ``-1.0`` and with an exception set, " +"so one should call :c:func:`PyErr_Occurred` to check for errors." +msgstr "" +"失敗時，此方法回傳 :c:type:`Py_complex` 並將 :c:member:`~Py_complex.real` 設" +"為 ``-1.0``，並設定例外，因此應該呼叫 :c:func:`PyErr_Occurred` 來檢查錯誤。" + +#: ../../c-api/complex.rst:170 +msgid "Use :meth:`~object.__index__` if available." +msgstr "如果可用則使用 :meth:`~object.__index__`。" + +#: ../../c-api/complex.rst:8 +msgid "object" +msgstr "object（物件）" + +#: ../../c-api/complex.rst:8 +msgid "complex number" +msgstr "complex number（複數）" diff --git a/c-api/concrete.po b/c-api/concrete.po index cfa7d8a04e..e0ada80969 100644 --- a/c-api/concrete.po +++ b/c-api/concrete.po @@ -1,108 +1,108 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Matt Wang , 2022 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-17 00:14+0000\n" -"PO-Revision-Date: 2022-11-13 20:37+0800\n" -"Last-Translator: Matt Wang \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" -"X-Generator: Poedit 3.2\n" - -#: ../../c-api/concrete.rst:8 -msgid "Concrete Objects Layer" -msgstr "具體物件層" - -#: ../../c-api/concrete.rst:10 -msgid "" -"The functions in this chapter are specific to certain Python object types. " -"Passing them an object of the wrong type is not a good idea; if you receive " -"an object from a Python program and you are not sure that it has the right " -"type, you must perform a type check first; for example, to check that an " -"object is a dictionary, use :c:func:`PyDict_Check`. The chapter is " -"structured like the \"family tree\" of Python object types." -msgstr "" -"此章節列出的函式僅能接受某些特定的 Python 物件型別，將錯誤型別的物件傳遞給它" -"們並不是什麼好事，如果你從 Python 程式當中接收到一個不確定是否為正確型別的物" -"件，那麼請一定要先做型別檢查。例如使用 :c:func:`PyDict_Check` 來確認一個物件" -"是否為字典。本章結構類似於 Python 物件型別的\"族譜圖 (family tree)\"。" - -#: ../../c-api/concrete.rst:19 -msgid "" -"While the functions described in this chapter carefully check the type of " -"the objects which are passed in, many of them do not check for ``NULL`` " -"being passed instead of a valid object. Allowing ``NULL`` to be passed in " -"can cause memory access violations and immediate termination of the " -"interpreter." -msgstr "" -"雖然本章所述之函式仔細地檢查了傳入物件的型別，但大多並無檢查是否為 ``NULL``。" -"允許 ``NULL`` 的傳入可能造成記憶體的不合法存取和直譯器的立即中止。" - -#: ../../c-api/concrete.rst:28 -msgid "Fundamental Objects" -msgstr "基礎物件" - -#: ../../c-api/concrete.rst:30 -msgid "" -"This section describes Python type objects and the singleton object ``None``." -msgstr "此段落描述 Python 型別物件與單例 (singleton) 物件 ``None``。" - -#: ../../c-api/concrete.rst:41 -msgid "Numeric Objects" -msgstr "數值物件" - -#: ../../c-api/concrete.rst:56 -msgid "Sequence Objects" -msgstr "序列物件" - -#: ../../c-api/concrete.rst:60 -msgid "" -"Generic operations on sequence objects were discussed in the previous " -"chapter; this section deals with the specific kinds of sequence objects that " -"are intrinsic to the Python language." -msgstr "" -"序列物件的一般操作在前一章節討論過了；此段落將討論 Python 語言特有的特定型別" -"序列物件。" - -#: ../../c-api/concrete.rst:78 -msgid "Container Objects" -msgstr "容器物件" - -#: ../../c-api/concrete.rst:91 -msgid "Function Objects" -msgstr "函式物件" - -#: ../../c-api/concrete.rst:102 -msgid "Other Objects" -msgstr "其他物件" - -#: ../../c-api/concrete.rst:123 -msgid "C API for extension modules" -msgstr "擴充模組的 C API" - -#: ../../c-api/concrete.rst:43 ../../c-api/concrete.rst:58 -#: ../../c-api/concrete.rst:80 -msgid "object" -msgstr "object（物件）" - -#: ../../c-api/concrete.rst:43 -msgid "numeric" -msgstr "numeric（數值）" - -#: ../../c-api/concrete.rst:58 -msgid "sequence" -msgstr "sequence（序列）" - -#: ../../c-api/concrete.rst:80 -msgid "mapping" -msgstr "mapping（對映）" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Matt Wang , 2022 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-17 00:14+0000\n" +"PO-Revision-Date: 2022-11-13 20:37+0800\n" +"Last-Translator: Matt Wang \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" +"X-Generator: Poedit 3.2\n" + +#: ../../c-api/concrete.rst:8 +msgid "Concrete Objects Layer" +msgstr "具體物件層" + +#: ../../c-api/concrete.rst:10 +msgid "" +"The functions in this chapter are specific to certain Python object types. " +"Passing them an object of the wrong type is not a good idea; if you receive " +"an object from a Python program and you are not sure that it has the right " +"type, you must perform a type check first; for example, to check that an " +"object is a dictionary, use :c:func:`PyDict_Check`. The chapter is " +"structured like the \"family tree\" of Python object types." +msgstr "" +"此章節列出的函式僅能接受某些特定的 Python 物件型別，將錯誤型別的物件傳遞給它" +"們並不是什麼好事，如果你從 Python 程式當中接收到一個不確定是否為正確型別的物" +"件，那麼請一定要先做型別檢查。例如使用 :c:func:`PyDict_Check` 來確認一個物件" +"是否為字典。本章結構類似於 Python 物件型別的\"族譜圖 (family tree)\"。" + +#: ../../c-api/concrete.rst:19 +msgid "" +"While the functions described in this chapter carefully check the type of " +"the objects which are passed in, many of them do not check for ``NULL`` " +"being passed instead of a valid object. Allowing ``NULL`` to be passed in " +"can cause memory access violations and immediate termination of the " +"interpreter." +msgstr "" +"雖然本章所述之函式仔細地檢查了傳入物件的型別，但大多並無檢查是否為 ``NULL``。" +"允許 ``NULL`` 的傳入可能造成記憶體的不合法存取和直譯器的立即中止。" + +#: ../../c-api/concrete.rst:28 +msgid "Fundamental Objects" +msgstr "基礎物件" + +#: ../../c-api/concrete.rst:30 +msgid "" +"This section describes Python type objects and the singleton object ``None``." +msgstr "此段落描述 Python 型別物件與單例 (singleton) 物件 ``None``。" + +#: ../../c-api/concrete.rst:41 +msgid "Numeric Objects" +msgstr "數值物件" + +#: ../../c-api/concrete.rst:56 +msgid "Sequence Objects" +msgstr "序列物件" + +#: ../../c-api/concrete.rst:60 +msgid "" +"Generic operations on sequence objects were discussed in the previous " +"chapter; this section deals with the specific kinds of sequence objects that " +"are intrinsic to the Python language." +msgstr "" +"序列物件的一般操作在前一章節討論過了；此段落將討論 Python 語言特有的特定型別" +"序列物件。" + +#: ../../c-api/concrete.rst:78 +msgid "Container Objects" +msgstr "容器物件" + +#: ../../c-api/concrete.rst:91 +msgid "Function Objects" +msgstr "函式物件" + +#: ../../c-api/concrete.rst:102 +msgid "Other Objects" +msgstr "其他物件" + +#: ../../c-api/concrete.rst:123 +msgid "C API for extension modules" +msgstr "擴充模組的 C API" + +#: ../../c-api/concrete.rst:43 ../../c-api/concrete.rst:58 +#: ../../c-api/concrete.rst:80 +msgid "object" +msgstr "object（物件）" + +#: ../../c-api/concrete.rst:43 +msgid "numeric" +msgstr "numeric（數值）" + +#: ../../c-api/concrete.rst:58 +msgid "sequence" +msgstr "sequence（序列）" + +#: ../../c-api/concrete.rst:80 +msgid "mapping" +msgstr "mapping（對映）" diff --git a/c-api/contextvars.po b/c-api/contextvars.po index 35ec1c9bd0..a2c7548719 100644 --- a/c-api/contextvars.po +++ b/c-api/contextvars.po @@ -1,265 +1,265 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: 2025-06-27 00:11+0800\n" -"Last-Translator: \n" -"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" -"tw)\n" -"Language: zh_TW\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=UTF-8\n" -"Content-Transfer-Encoding: 8bit\n" -"X-Generator: Poedit 3.6\n" - -#: ../../c-api/contextvars.rst:6 -msgid "Context Variables Objects" -msgstr "情境變數物件（Context Variables Objects）" - -#: ../../c-api/contextvars.rst:15 -msgid "" -"In Python 3.7.1 the signatures of all context variables C APIs were " -"**changed** to use :c:type:`PyObject` pointers instead " -"of :c:type:`PyContext`, :c:type:`PyContextVar`, " -"and :c:type:`PyContextToken`, e.g.::" -msgstr "" -"在 Python 3.7.1 中所有情境變數 C API 的簽名都被\\ **改為**\\ 使" -"用 :c:type:`PyObject` 指標，而不" -"是 :c:type:`PyContext`、:c:type:`PyContextVar` 或 :c:type:`PyContextToken`，" -"例如：" - -#: ../../c-api/contextvars.rst:20 -msgid "" -"// in 3.7.0:\n" -"PyContext *PyContext_New(void);\n" -"\n" -"// in 3.7.1+:\n" -"PyObject *PyContext_New(void);" -msgstr "" -"// 在 3.7.0：\n" -"PyContext *PyContext_New(void);\n" -"\n" -"// 在 3.7.1+：\n" -"PyObject *PyContext_New(void);" - -#: ../../c-api/contextvars.rst:26 -msgid "See :issue:`34762` for more details." -msgstr "更多細節請見 :issue:`34762`。" - -#: ../../c-api/contextvars.rst:29 -msgid "" -"This section details the public C API for the :mod:`contextvars` module." -msgstr "本節詳述 :mod:`contextvars` 模組的公開 C API。" - -#: ../../c-api/contextvars.rst:33 -msgid "" -"The C structure used to represent a :class:`contextvars.Context` object." -msgstr "用來代表 :class:`contextvars.Context` 物件的 C 結構。" - -#: ../../c-api/contextvars.rst:38 -msgid "" -"The C structure used to represent a :class:`contextvars.ContextVar` object." -msgstr "用來代表 :class:`contextvars.ContextVar` 物件的 C 結構。" - -#: ../../c-api/contextvars.rst:43 -msgid "The C structure used to represent a :class:`contextvars.Token` object." -msgstr "用來代表 :class:`contextvars.Token` 物件的 C 結構。" - -#: ../../c-api/contextvars.rst:47 -msgid "The type object representing the *context* type." -msgstr "代表 *context* 型別的型別物件。" - -#: ../../c-api/contextvars.rst:51 -msgid "The type object representing the *context variable* type." -msgstr "代表 *情境變數* 型別的型別物件。" - -#: ../../c-api/contextvars.rst:55 -msgid "The type object representing the *context variable token* type." -msgstr "代表 *情境變數 token* 型別的型別物件。" - -#: ../../c-api/contextvars.rst:58 -msgid "Type-check macros:" -msgstr "型別檢查巨集：" - -#: ../../c-api/contextvars.rst:62 -msgid "" -"Return true if *o* is of type :c:data:`PyContext_Type`. *o* must not be " -"``NULL``. This function always succeeds." -msgstr "" -"如果 *o* 的型別為 :c:data:`PyContext_Type` 則回傳 true。*o* 不得為 ``NULL``。" -"此函式一定會成功回傳。" - -#: ../../c-api/contextvars.rst:67 -msgid "" -"Return true if *o* is of type :c:data:`PyContextVar_Type`. *o* must not be " -"``NULL``. This function always succeeds." -msgstr "" -"如果 *o* 的類型為 :c:data:`PyContextVar_Type` 則回傳 true。*o* 不得為 " -"``NULL``。此函式一定會成功回傳。" - -#: ../../c-api/contextvars.rst:72 -msgid "" -"Return true if *o* is of type :c:data:`PyContextToken_Type`. *o* must not be " -"``NULL``. This function always succeeds." -msgstr "" -"如果 *o* 的類型為 :c:data:`PyContextToken_Type` 則回傳 true。 *o* 不得為 " -"``NULL``。此函式一定會成功回傳。" - -#: ../../c-api/contextvars.rst:76 -msgid "Context object management functions:" -msgstr "情境物件管理函式：" - -#: ../../c-api/contextvars.rst:80 -msgid "" -"Create a new empty context object. Returns ``NULL`` if an error has " -"occurred." -msgstr "建立一個新的空的情境物件。 如果發生錯誤，則回傳 ``NULL``。" - -#: ../../c-api/contextvars.rst:85 -msgid "" -"Create a shallow copy of the passed *ctx* context object. Returns ``NULL`` " -"if an error has occurred." -msgstr "" -"建立傳入的 *ctx* 情境物件的淺層複製 (shallow copy)。如果發生錯誤，則回傳 " -"``NULL``。" - -#: ../../c-api/contextvars.rst:90 -msgid "" -"Create a shallow copy of the current thread context. Returns ``NULL`` if an " -"error has occurred." -msgstr "建立目前執行緒上的情境的淺層複製。如果發生錯誤，則回傳 ``NULL``。" - -#: ../../c-api/contextvars.rst:95 -msgid "" -"Set *ctx* as the current context for the current thread. Returns ``0`` on " -"success, and ``-1`` on error." -msgstr "" -"設定 *ctx* 為目前執行緒上的目前情境。成功時回傳 ``0``，錯誤時回傳 ``-1``。" - -#: ../../c-api/contextvars.rst:100 -msgid "" -"Deactivate the *ctx* context and restore the previous context as the current " -"context for the current thread. Returns ``0`` on success, and ``-1`` on " -"error." -msgstr "" -"關閉 *ctx* 情境，並將目前執行緒的目前情境設回之前的情境。 成功時回傳 ``0``，" -"錯誤時回傳 ``-1``。" - -#: ../../c-api/contextvars.rst:106 -msgid "" -"Register *callback* as a context object watcher for the current interpreter. " -"Return an ID which may be passed to :c:func:`PyContext_ClearWatcher`. In " -"case of error (e.g. no more watcher IDs available), return ``-1`` and set an " -"exception." -msgstr "" - -#: ../../c-api/contextvars.rst:115 -msgid "" -"Clear watcher identified by *watcher_id* previously returned " -"from :c:func:`PyContext_AddWatcher` for the current interpreter. Return " -"``0`` on success, or ``-1`` and set an exception on error (e.g. if the given " -"*watcher_id* was never registered.)" -msgstr "" - -#: ../../c-api/contextvars.rst:124 -msgid "Enumeration of possible context object watcher events:" -msgstr "" - -#: ../../c-api/contextvars.rst:126 -msgid "" -"``Py_CONTEXT_SWITCHED``: The :term:`current context` has switched to a " -"different context. The object passed to the watch callback is the now-" -"current :class:`contextvars.Context` object, or None if no context is " -"current." -msgstr "" - -#: ../../c-api/contextvars.rst:135 -msgid "" -"Context object watcher callback function. The object passed to the callback " -"is event-specific; see :c:type:`PyContextEvent` for details." -msgstr "" - -#: ../../c-api/contextvars.rst:138 -msgid "" -"If the callback returns with an exception set, it must return ``-1``; this " -"exception will be printed as an unraisable exception " -"using :c:func:`PyErr_FormatUnraisable`. Otherwise it should return ``0``." -msgstr "" - -#: ../../c-api/contextvars.rst:142 -msgid "" -"There may already be a pending exception set on entry to the callback. In " -"this case, the callback should return ``0`` with the same exception still " -"set. This means the callback may not call any other API that can set an " -"exception unless it saves and clears the exception state first, and restores " -"it before returning." -msgstr "" - -#: ../../c-api/contextvars.rst:151 -msgid "Context variable functions:" -msgstr "情境變數函式：" - -#: ../../c-api/contextvars.rst:155 -msgid "" -"Create a new ``ContextVar`` object. The *name* parameter is used for " -"introspection and debug purposes. The *def* parameter specifies a default " -"value for the context variable, or ``NULL`` for no default. If an error has " -"occurred, this function returns ``NULL``." -msgstr "" -"建立一個新的 ``ContextVar`` 物件。*name* 參數用於自我檢查（introspection）和" -"除錯目的。*def* 參數指定情境變數的預設值，亦可用 ``NULL`` 表示沒有預設值。 如" -"果發生錯誤，此函式會回傳 ``NULL``。" - -#: ../../c-api/contextvars.rst:162 -msgid "" -"Get the value of a context variable. Returns ``-1`` if an error has " -"occurred during lookup, and ``0`` if no error occurred, whether or not a " -"value was found." -msgstr "" -"取得情境變數的值。如果在查找過程中發生錯誤則回傳 ``-1``，如果沒有發生錯誤則無" -"論是否找到值都會回傳 ``0``。" - -#: ../../c-api/contextvars.rst:166 -msgid "" -"If the context variable was found, *value* will be a pointer to it. If the " -"context variable was *not* found, *value* will point to:" -msgstr "" -"如果找到情境變數，*value* 將會是指向它的指標。如果 *沒有* 找到情境變數，" -"*value* 將會指到：" - -#: ../../c-api/contextvars.rst:169 -msgid "*default_value*, if not ``NULL``;" -msgstr "*default_value* 預設值，但前提是預設值不是 ``NULL``；" - -#: ../../c-api/contextvars.rst:170 -msgid "the default value of *var*, if not ``NULL``;" -msgstr "*var* 的預設值，但前提是預設值不是 ``NULL``；" - -#: ../../c-api/contextvars.rst:171 -msgid "``NULL``" -msgstr "``NULL``" - -#: ../../c-api/contextvars.rst:173 -msgid "Except for ``NULL``, the function returns a new reference." -msgstr "除了 ``NULL`` 之外，此函式會回傳一個新的參照（reference）。" - -#: ../../c-api/contextvars.rst:177 -msgid "" -"Set the value of *var* to *value* in the current context. Returns a new " -"token object for this change, or ``NULL`` if an error has occurred." -msgstr "" -"在目前的情境中將 *var* 的值設為 *value*。會回傳一個用來代表此變更的新 token " -"物件，如果發生錯誤則回傳 ``NULL``。" - -#: ../../c-api/contextvars.rst:182 -msgid "" -"Reset the state of the *var* context variable to that it was in " -"before :c:func:`PyContextVar_Set` that returned the *token* was called. This " -"function returns ``0`` on success and ``-1`` on error." -msgstr "" -"將 *var* 情境變數的狀態設回之前的狀態，亦即上一次回傳 token " -"的 :c:func:`PyContextVar_Set` 被呼叫前的狀態。此函式在成功時回傳 ``0``，錯誤" -"時回傳 ``-1``。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: 2025-06-27 00:11+0800\n" +"Last-Translator: \n" +"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" +"tw)\n" +"Language: zh_TW\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"X-Generator: Poedit 3.6\n" + +#: ../../c-api/contextvars.rst:6 +msgid "Context Variables Objects" +msgstr "情境變數物件（Context Variables Objects）" + +#: ../../c-api/contextvars.rst:15 +msgid "" +"In Python 3.7.1 the signatures of all context variables C APIs were " +"**changed** to use :c:type:`PyObject` pointers instead " +"of :c:type:`PyContext`, :c:type:`PyContextVar`, " +"and :c:type:`PyContextToken`, e.g.::" +msgstr "" +"在 Python 3.7.1 中所有情境變數 C API 的簽名都被\\ **改為**\\ 使" +"用 :c:type:`PyObject` 指標，而不" +"是 :c:type:`PyContext`、:c:type:`PyContextVar` 或 :c:type:`PyContextToken`，" +"例如：" + +#: ../../c-api/contextvars.rst:20 +msgid "" +"// in 3.7.0:\n" +"PyContext *PyContext_New(void);\n" +"\n" +"// in 3.7.1+:\n" +"PyObject *PyContext_New(void);" +msgstr "" +"// 在 3.7.0：\n" +"PyContext *PyContext_New(void);\n" +"\n" +"// 在 3.7.1+：\n" +"PyObject *PyContext_New(void);" + +#: ../../c-api/contextvars.rst:26 +msgid "See :issue:`34762` for more details." +msgstr "更多細節請見 :issue:`34762`。" + +#: ../../c-api/contextvars.rst:29 +msgid "" +"This section details the public C API for the :mod:`contextvars` module." +msgstr "本節詳述 :mod:`contextvars` 模組的公開 C API。" + +#: ../../c-api/contextvars.rst:33 +msgid "" +"The C structure used to represent a :class:`contextvars.Context` object." +msgstr "用來代表 :class:`contextvars.Context` 物件的 C 結構。" + +#: ../../c-api/contextvars.rst:38 +msgid "" +"The C structure used to represent a :class:`contextvars.ContextVar` object." +msgstr "用來代表 :class:`contextvars.ContextVar` 物件的 C 結構。" + +#: ../../c-api/contextvars.rst:43 +msgid "The C structure used to represent a :class:`contextvars.Token` object." +msgstr "用來代表 :class:`contextvars.Token` 物件的 C 結構。" + +#: ../../c-api/contextvars.rst:47 +msgid "The type object representing the *context* type." +msgstr "代表 *context* 型別的型別物件。" + +#: ../../c-api/contextvars.rst:51 +msgid "The type object representing the *context variable* type." +msgstr "代表 *情境變數* 型別的型別物件。" + +#: ../../c-api/contextvars.rst:55 +msgid "The type object representing the *context variable token* type." +msgstr "代表 *情境變數 token* 型別的型別物件。" + +#: ../../c-api/contextvars.rst:58 +msgid "Type-check macros:" +msgstr "型別檢查巨集：" + +#: ../../c-api/contextvars.rst:62 +msgid "" +"Return true if *o* is of type :c:data:`PyContext_Type`. *o* must not be " +"``NULL``. This function always succeeds." +msgstr "" +"如果 *o* 的型別為 :c:data:`PyContext_Type` 則回傳 true。*o* 不得為 ``NULL``。" +"此函式一定會成功回傳。" + +#: ../../c-api/contextvars.rst:67 +msgid "" +"Return true if *o* is of type :c:data:`PyContextVar_Type`. *o* must not be " +"``NULL``. This function always succeeds." +msgstr "" +"如果 *o* 的類型為 :c:data:`PyContextVar_Type` 則回傳 true。*o* 不得為 " +"``NULL``。此函式一定會成功回傳。" + +#: ../../c-api/contextvars.rst:72 +msgid "" +"Return true if *o* is of type :c:data:`PyContextToken_Type`. *o* must not be " +"``NULL``. This function always succeeds." +msgstr "" +"如果 *o* 的類型為 :c:data:`PyContextToken_Type` 則回傳 true。 *o* 不得為 " +"``NULL``。此函式一定會成功回傳。" + +#: ../../c-api/contextvars.rst:76 +msgid "Context object management functions:" +msgstr "情境物件管理函式：" + +#: ../../c-api/contextvars.rst:80 +msgid "" +"Create a new empty context object. Returns ``NULL`` if an error has " +"occurred." +msgstr "建立一個新的空的情境物件。 如果發生錯誤，則回傳 ``NULL``。" + +#: ../../c-api/contextvars.rst:85 +msgid "" +"Create a shallow copy of the passed *ctx* context object. Returns ``NULL`` " +"if an error has occurred." +msgstr "" +"建立傳入的 *ctx* 情境物件的淺層複製 (shallow copy)。如果發生錯誤，則回傳 " +"``NULL``。" + +#: ../../c-api/contextvars.rst:90 +msgid "" +"Create a shallow copy of the current thread context. Returns ``NULL`` if an " +"error has occurred." +msgstr "建立目前執行緒上的情境的淺層複製。如果發生錯誤，則回傳 ``NULL``。" + +#: ../../c-api/contextvars.rst:95 +msgid "" +"Set *ctx* as the current context for the current thread. Returns ``0`` on " +"success, and ``-1`` on error." +msgstr "" +"設定 *ctx* 為目前執行緒上的目前情境。成功時回傳 ``0``，錯誤時回傳 ``-1``。" + +#: ../../c-api/contextvars.rst:100 +msgid "" +"Deactivate the *ctx* context and restore the previous context as the current " +"context for the current thread. Returns ``0`` on success, and ``-1`` on " +"error." +msgstr "" +"關閉 *ctx* 情境，並將目前執行緒的目前情境設回之前的情境。 成功時回傳 ``0``，" +"錯誤時回傳 ``-1``。" + +#: ../../c-api/contextvars.rst:106 +msgid "" +"Register *callback* as a context object watcher for the current interpreter. " +"Return an ID which may be passed to :c:func:`PyContext_ClearWatcher`. In " +"case of error (e.g. no more watcher IDs available), return ``-1`` and set an " +"exception." +msgstr "" + +#: ../../c-api/contextvars.rst:115 +msgid "" +"Clear watcher identified by *watcher_id* previously returned " +"from :c:func:`PyContext_AddWatcher` for the current interpreter. Return " +"``0`` on success, or ``-1`` and set an exception on error (e.g. if the given " +"*watcher_id* was never registered.)" +msgstr "" + +#: ../../c-api/contextvars.rst:124 +msgid "Enumeration of possible context object watcher events:" +msgstr "" + +#: ../../c-api/contextvars.rst:126 +msgid "" +"``Py_CONTEXT_SWITCHED``: The :term:`current context` has switched to a " +"different context. The object passed to the watch callback is the now-" +"current :class:`contextvars.Context` object, or None if no context is " +"current." +msgstr "" + +#: ../../c-api/contextvars.rst:135 +msgid "" +"Context object watcher callback function. The object passed to the callback " +"is event-specific; see :c:type:`PyContextEvent` for details." +msgstr "" + +#: ../../c-api/contextvars.rst:138 +msgid "" +"If the callback returns with an exception set, it must return ``-1``; this " +"exception will be printed as an unraisable exception " +"using :c:func:`PyErr_FormatUnraisable`. Otherwise it should return ``0``." +msgstr "" + +#: ../../c-api/contextvars.rst:142 +msgid "" +"There may already be a pending exception set on entry to the callback. In " +"this case, the callback should return ``0`` with the same exception still " +"set. This means the callback may not call any other API that can set an " +"exception unless it saves and clears the exception state first, and restores " +"it before returning." +msgstr "" + +#: ../../c-api/contextvars.rst:151 +msgid "Context variable functions:" +msgstr "情境變數函式：" + +#: ../../c-api/contextvars.rst:155 +msgid "" +"Create a new ``ContextVar`` object. The *name* parameter is used for " +"introspection and debug purposes. The *def* parameter specifies a default " +"value for the context variable, or ``NULL`` for no default. If an error has " +"occurred, this function returns ``NULL``." +msgstr "" +"建立一個新的 ``ContextVar`` 物件。*name* 參數用於自我檢查（introspection）和" +"除錯目的。*def* 參數指定情境變數的預設值，亦可用 ``NULL`` 表示沒有預設值。 如" +"果發生錯誤，此函式會回傳 ``NULL``。" + +#: ../../c-api/contextvars.rst:162 +msgid "" +"Get the value of a context variable. Returns ``-1`` if an error has " +"occurred during lookup, and ``0`` if no error occurred, whether or not a " +"value was found." +msgstr "" +"取得情境變數的值。如果在查找過程中發生錯誤則回傳 ``-1``，如果沒有發生錯誤則無" +"論是否找到值都會回傳 ``0``。" + +#: ../../c-api/contextvars.rst:166 +msgid "" +"If the context variable was found, *value* will be a pointer to it. If the " +"context variable was *not* found, *value* will point to:" +msgstr "" +"如果找到情境變數，*value* 將會是指向它的指標。如果 *沒有* 找到情境變數，" +"*value* 將會指到：" + +#: ../../c-api/contextvars.rst:169 +msgid "*default_value*, if not ``NULL``;" +msgstr "*default_value* 預設值，但前提是預設值不是 ``NULL``；" + +#: ../../c-api/contextvars.rst:170 +msgid "the default value of *var*, if not ``NULL``;" +msgstr "*var* 的預設值，但前提是預設值不是 ``NULL``；" + +#: ../../c-api/contextvars.rst:171 +msgid "``NULL``" +msgstr "``NULL``" + +#: ../../c-api/contextvars.rst:173 +msgid "Except for ``NULL``, the function returns a new reference." +msgstr "除了 ``NULL`` 之外，此函式會回傳一個新的參照（reference）。" + +#: ../../c-api/contextvars.rst:177 +msgid "" +"Set the value of *var* to *value* in the current context. Returns a new " +"token object for this change, or ``NULL`` if an error has occurred." +msgstr "" +"在目前的情境中將 *var* 的值設為 *value*。會回傳一個用來代表此變更的新 token " +"物件，如果發生錯誤則回傳 ``NULL``。" + +#: ../../c-api/contextvars.rst:182 +msgid "" +"Reset the state of the *var* context variable to that it was in " +"before :c:func:`PyContextVar_Set` that returned the *token* was called. This " +"function returns ``0`` on success and ``-1`` on error." +msgstr "" +"將 *var* 情境變數的狀態設回之前的狀態，亦即上一次回傳 token " +"的 :c:func:`PyContextVar_Set` 被呼叫前的狀態。此函式在成功時回傳 ``0``，錯誤" +"時回傳 ``-1``。" diff --git a/c-api/conversion.po b/c-api/conversion.po index 7cd313de67..9fbb7380bd 100644 --- a/c-api/conversion.po +++ b/c-api/conversion.po @@ -1,388 +1,388 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Ching-Lung Chuang, 2015 -# Leon H., 2017 -# Matt Wang , 2023 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-26 00:14+0000\n" -"PO-Revision-Date: 2023-12-11 18:26+0000\n" -"Last-Translator: Matt Wang \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" - -#: ../../c-api/conversion.rst:6 -msgid "String conversion and formatting" -msgstr "字串轉換與格式化" - -#: ../../c-api/conversion.rst:8 -msgid "Functions for number conversion and formatted string output." -msgstr "用於數字轉換和格式化字串輸出的函式。" - -#: ../../c-api/conversion.rst:13 -msgid "" -"Output not more than *size* bytes to *str* according to the format string " -"*format* and the extra arguments. See the Unix man page :manpage:" -"`snprintf(3)`." -msgstr "" -"根據格式字串 *format* 和額外引數，輸出不超過 *size* 位元組給 *str*。請參閱 " -"Unix 使用手冊 :manpage:`snprintf(3)`。" - -#: ../../c-api/conversion.rst:19 -msgid "" -"Output not more than *size* bytes to *str* according to the format string " -"*format* and the variable argument list *va*. Unix man page :manpage:" -"`vsnprintf(3)`." -msgstr "" -"根據格式字串 *format* 和變數引數串列 *va*，輸出不超過 *size* 位元組給 *str*。" -"Unix 使用手冊 :manpage:`vsnprintf(3)`。" - -#: ../../c-api/conversion.rst:23 -msgid "" -":c:func:`PyOS_snprintf` and :c:func:`PyOS_vsnprintf` wrap the Standard C " -"library functions :c:func:`snprintf` and :c:func:`vsnprintf`. Their purpose " -"is to guarantee consistent behavior in corner cases, which the Standard C " -"functions do not." -msgstr "" -":c:func:`PyOS_snprintf` 和 :c:func:`PyOS_vsnprintf` 包裝標準 C 函式庫函式 :c:" -"func:`snprintf` 和 :c:func:`vsnprintf`。它們的目的是確保邊角案例 (corner " -"case) 下的行為一致，而標準 C 函式則不然。" - -#: ../../c-api/conversion.rst:28 -msgid "" -"The wrappers ensure that ``str[size-1]`` is always ``'\\0'`` upon return. " -"They never write more than *size* bytes (including the trailing ``'\\0'``) " -"into str. Both functions require that ``str != NULL``, ``size > 0``, " -"``format != NULL`` and ``size < INT_MAX``. Note that this means there is no " -"equivalent to the C99 ``n = snprintf(NULL, 0, ...)`` which would determine " -"the necessary buffer size." -msgstr "" -"包裝器確保回傳時 ``str[size-1]`` 始終為 ``'\\0'``。他們永遠不會在 str 中寫入" -"超過 *size* 位元組（包括尾隨的 ``'\\0'``\\ ）。這兩個函式都要求 ``str != " -"NULL``、``size > 0``、``format != NULL`` 和 ``size < INT_MAX``。請注意，這表" -"示沒有與 C99 ``n = snprintf(NULL, 0, ...)`` 等效的函式來決定必要的緩衝區大" -"小。" - -#: ../../c-api/conversion.rst:34 -msgid "" -"The return value (*rv*) for these functions should be interpreted as follows:" -msgstr "這些函式的回傳值 (*rv*) 應如下被直譯：" - -#: ../../c-api/conversion.rst:36 -msgid "" -"When ``0 <= rv < size``, the output conversion was successful and *rv* " -"characters were written to *str* (excluding the trailing ``'\\0'`` byte at " -"``str[rv]``)." -msgstr "" -"當 ``0 <= rv < size`` 時，輸出轉換成功，*rv* 字元被寫入 *str*\\ （不包括 " -"``str[rv]`` 處的尾隨 ``'\\0'`` 位元組）。" - -#: ../../c-api/conversion.rst:40 -msgid "" -"When ``rv >= size``, the output conversion was truncated and a buffer with " -"``rv + 1`` bytes would have been needed to succeed. ``str[size-1]`` is " -"``'\\0'`` in this case." -msgstr "" -"當 ``rv >= size`` 時，輸出轉換被截斷，並且需要具有 ``rv + 1`` 位元組的緩衝區" -"才能成功。在這種情況下，``str[size-1]`` 是 ``'\\0'``。" - -#: ../../c-api/conversion.rst:44 -msgid "" -"When ``rv < 0``, the output conversion failed and ``str[size-1]`` is " -"``'\\0'`` in this case too, but the rest of *str* is undefined. The exact " -"cause of the error depends on the underlying platform." -msgstr "" -"當 ``rv < 0`` 時，代表輸出的轉換失敗，且在這種情況下 ``str[size-1]`` 也是 " -"``'\\0'``，但 *str* 的其餘部分未定義。錯誤的確切原因取決於底層平台。" - -#: ../../c-api/conversion.rst:49 -msgid "" -"The following functions provide locale-independent string to number " -"conversions." -msgstr "以下函式提供與區域設定無關 (locale-independent) 的字串到數字的轉換。" - -#: ../../c-api/conversion.rst:53 -msgid "" -"Convert the initial part of the string in ``str`` to an :c:expr:`unsigned " -"long` value according to the given ``base``, which must be between ``2`` and " -"``36`` inclusive, or be the special value ``0``." -msgstr "" -"將字串 ``str`` 的初始部分根據給定的 ``base`` 轉換為 :c:expr:`unsigned long` " -"值，底 (base) 必須介於 ``2`` 到 ``36``\\ （包含）之間，或為特殊值 ``0``。" - -#: ../../c-api/conversion.rst:57 -msgid "" -"Leading white space and case of characters are ignored. If ``base`` is zero " -"it looks for a leading ``0b``, ``0o`` or ``0x`` to tell which base. If " -"these are absent it defaults to ``10``. Base must be 0 or between 2 and 36 " -"(inclusive). If ``ptr`` is non-``NULL`` it will contain a pointer to the " -"end of the scan." -msgstr "" -"忽略前導空白和字元大小寫。如果 ``base`` 為零，則會尋找前導的 ``0b``、``0o`` " -"或 ``0x`` 來判斷使用哪個進位。如果這些前綴不存在，則預設為 ``10``。底必須為 " -"0 或介於 2 到 36（包含）之間。如果 ``ptr`` 為非 ``NULL``，它將包含指向掃描結" -"束處的指標。" - -#: ../../c-api/conversion.rst:63 -msgid "" -"If the converted value falls out of range of corresponding return type, " -"range error occurs (:c:data:`errno` is set to :c:macro:`!ERANGE`) and :c:" -"macro:`!ULONG_MAX` is returned. If no conversion can be performed, ``0`` is " -"returned." -msgstr "" -"如果轉換後的值超出對應回傳型別的範圍，則會發生範圍錯誤（:c:data:`errno` 會被" -"設定為 :c:macro:`!ERANGE`）並回傳 :c:macro:`!ULONG_MAX`。如果無法執行任何轉" -"換，則回傳 ``0``。" - -#: ../../c-api/conversion.rst:68 -msgid "See also the Unix man page :manpage:`strtoul(3)`." -msgstr "也請見 Unix 使用手冊 :manpage:`strtoul(3)`。" - -#: ../../c-api/conversion.rst:75 -msgid "" -"Convert the initial part of the string in ``str`` to an :c:expr:`long` value " -"according to the given ``base``, which must be between ``2`` and ``36`` " -"inclusive, or be the special value ``0``." -msgstr "" -"將字串 ``str`` 的初始部分根據給定的 ``base`` 轉換為 :c:expr:`long` 值，底 必" -"須介於 ``2`` 到 ``36`` \\ （包含）之間，或為特殊值 ``0``。" - -#: ../../c-api/conversion.rst:79 -msgid "" -"Same as :c:func:`PyOS_strtoul`, but return a :c:expr:`long` value instead " -"and :c:macro:`LONG_MAX` on overflows." -msgstr "" -"與 :c:func:`PyOS_strtoul` 相同，但回傳 :c:expr:`long` 值，並在溢位時回傳 :c:" -"macro:`LONG_MAX`。" - -#: ../../c-api/conversion.rst:82 -msgid "See also the Unix man page :manpage:`strtol(3)`." -msgstr "也請見 Unix 使用手冊 :manpage:`strtol(3)`。" - -#: ../../c-api/conversion.rst:89 -msgid "" -"Convert a string ``s`` to a :c:expr:`double`, raising a Python exception on " -"failure. The set of accepted strings corresponds to the set of strings " -"accepted by Python's :func:`float` constructor, except that ``s`` must not " -"have leading or trailing whitespace. The conversion is independent of the " -"current locale." -msgstr "" -"將字串 ``s`` 轉換為 :c:expr:`double`，失敗時引發 Python 例外。接受的字串集合" -"對應於 Python 的 :func:`float` 建構函式接受的字串集合，但 ``s`` 不得有前導或" -"尾隨的空格。轉換與目前區域設定無關。" - -#: ../../c-api/conversion.rst:95 -msgid "" -"If ``endptr`` is ``NULL``, convert the whole string. Raise :exc:" -"`ValueError` and return ``-1.0`` if the string is not a valid representation " -"of a floating-point number." -msgstr "" -"如果 ``endptr`` 為 ``NULL``，則轉換整個字串。如果字串不是浮點數的有效表示，則" -"引發 :exc:`ValueError` 並回傳 ``-1.0``。" - -#: ../../c-api/conversion.rst:99 -msgid "" -"If endptr is not ``NULL``, convert as much of the string as possible and set " -"``*endptr`` to point to the first unconverted character. If no initial " -"segment of the string is the valid representation of a floating-point " -"number, set ``*endptr`` to point to the beginning of the string, raise " -"ValueError, and return ``-1.0``." -msgstr "" -"如果 endptr 不是 ``NULL``，則盡可能轉換字串，並將 ``*endptr`` 設定為指向第一" -"個未轉換的字元。如果字串的初始片段都不是浮點數的有效表示，則設定 ``*endptr`` " -"指向字串的開頭，引發 ValueError 並回傳 ``-1.0``。" - -#: ../../c-api/conversion.rst:106 -msgid "" -"If ``s`` represents a value that is too large to store in a float (for " -"example, ``\"1e500\"`` is such a string on many platforms) then if " -"``overflow_exception`` is ``NULL`` return ``Py_INFINITY`` (with an " -"appropriate sign) and don't set any exception. Otherwise, " -"``overflow_exception`` must point to a Python exception object; raise that " -"exception and return ``-1.0``. In both cases, set ``*endptr`` to point to " -"the first character after the converted value." -msgstr "" -"如果 ``s`` 表示的值太大而無法儲存在浮點數中（例如 ``\"1e500\"`` 在許多平台上" -"都是這樣的字串），如果 ``overflow_exception`` 為 ``NULL`` 則回傳 " -"``Py_INFINITY``\\ （會帶有適當的符號）並且不設定任何例外。否則， " -"``overflow_exception`` 必須指向一個 Python 例外物件；引發該例外並回傳 " -"``-1.0``。在這兩種情況下，將 ``*endptr`` 設定為指向轉換後的值之後的第一個字" -"元。" - -#: ../../c-api/conversion.rst:114 -msgid "" -"If any other error occurs during the conversion (for example an out-of-" -"memory error), set the appropriate Python exception and return ``-1.0``." -msgstr "" -"如果轉換期間發生任何其他錯誤（例如記憶體不足的錯誤），請設定適當的 Python 例" -"外並回傳 ``-1.0``。" - -#: ../../c-api/conversion.rst:123 -msgid "" -"Convert a :c:expr:`double` *val* to a string using supplied *format_code*, " -"*precision*, and *flags*." -msgstr "" -"使用提供的 *format_code*、*precision* 和 *flags* 將 :c:expr:`double` *val* 轉" -"換為字串。" - -#: ../../c-api/conversion.rst:126 -msgid "" -"*format_code* must be one of ``'e'``, ``'E'``, ``'f'``, ``'F'``, ``'g'``, " -"``'G'`` or ``'r'``. For ``'r'``, the supplied *precision* must be 0 and is " -"ignored. The ``'r'`` format code specifies the standard :func:`repr` format." -msgstr "" -"*format_code* 必須是 ``'e'``、``'E'``、``'f'``、``'F'``、``'g'``、``'G'`` 或 " -"``'r'`` 其中之一。對於 ``'r'``，提供的 *precision* 必須為 0 並會被忽略。" -"``'r'`` 格式碼指定標準 :func:`repr` 格式。" - -#: ../../c-api/conversion.rst:131 -msgid "*flags* can be zero or more of the following values or-ed together:" -msgstr "*flags* 可以是零個或多個以下的值被聯集在一起：" - -#: ../../c-api/conversion.rst:135 -msgid "" -"Always precede the returned string with a sign character, even if *val* is " -"non-negative." -msgstr "" -"總是在回傳的字串前面加上正負號字元 (sign character)，即使 *val* 非負數。" - -#: ../../c-api/conversion.rst:140 -msgid "Ensure that the returned string will not look like an integer." -msgstr "確保回傳的字串看起來不會像整數。" - -#: ../../c-api/conversion.rst:144 -msgid "" -"Apply \"alternate\" formatting rules. See the documentation for the :c:func:" -"`PyOS_snprintf` ``'#'`` specifier for details." -msgstr "" -"套用「備用的 (alternate)」格式化規則。有關詳細資訊，請參閱 :c:func:" -"`PyOS_snprintf` ``'#'`` 的文件。" - -#: ../../c-api/conversion.rst:150 -msgid "Negative zero is converted to positive zero." -msgstr "負零會被轉換為正零。" - -#: ../../c-api/conversion.rst:154 -msgid "" -"If *ptype* is non-``NULL``, then the value it points to will be set to one " -"of ``Py_DTST_FINITE``, ``Py_DTST_INFINITE``, or ``Py_DTST_NAN``, signifying " -"that *val* is a finite number, an infinite number, or not a number, " -"respectively." -msgstr "" -"如果 *ptype* 是非 ``NULL``，那麼它指向的值將被設定為 ``Py_DTST_FINITE``、" -"``Py_DTST_INFINITE`` 或 ``Py_DTST_NAN`` 其中之一，分別代表 *val* 是有限數、無" -"限數或非數。" - -#: ../../c-api/conversion.rst:158 -msgid "" -"The return value is a pointer to *buffer* with the converted string or " -"``NULL`` if the conversion failed. The caller is responsible for freeing the " -"returned string by calling :c:func:`PyMem_Free`." -msgstr "" -"回傳值是指向 *buffer* 的指標，其中包含轉換後的字串，如果轉換失敗則回傳 " -"``NULL``。呼叫者負責透過呼叫 :c:func:`PyMem_Free` 來釋放回傳的字串。" - -#: ../../c-api/conversion.rst:168 -msgid "" -"Case insensitive comparison of strings. These functions work almost " -"identically to :c:func:`!strcmp` and :c:func:`!strncmp` (respectively), " -"except that they ignore the case of ASCII characters." -msgstr "" -"不區分大小寫的字串比較。函式的作用方式幾乎與 :c:func:`!strcmp` 和 :c:func:`!strncmp` " -"相同，只是它們忽略大小寫。" - -#: ../../c-api/conversion.rst:172 -msgid "" -"Return ``0`` if the strings are equal, a negative value if *str1* sorts " -"lexicographically before *str2*, or a positive value if it sorts after." -msgstr "" - -#: ../../c-api/conversion.rst:175 -msgid "" -"In the *str1* or *str2* arguments, a NUL byte marks the end of the string. " -"For :c:func:`!PyOS_mystrnicmp`, the *size* argument gives the maximum size " -"of the string, as if NUL was present at the index given by *size*." -msgstr "" - -#: ../../c-api/conversion.rst:179 -msgid "These functions do not use the locale." -msgstr "" - -#: ../../c-api/conversion.rst:185 -msgid "Case insensitive comparison of strings." -msgstr "不區分大小寫的字串比較。" - -#: ../../c-api/conversion.rst:187 -msgid "" -"On Windows, these are aliases of :c:func:`!stricmp` and :c:func:`!strnicmp`, " -"respectively." -msgstr "" - -#: ../../c-api/conversion.rst:190 -msgid "" -"On other platforms, they are aliases of :c:func:`PyOS_mystricmp` and :c:func:" -"`PyOS_mystrnicmp`, respectively." -msgstr "" - -#: ../../c-api/conversion.rst:195 -msgid "Character classification and conversion" -msgstr "" - -#: ../../c-api/conversion.rst:197 -msgid "" -"The following macros provide locale-independent (unlike the C standard " -"library ``ctype.h``) character classification and conversion. The argument " -"must be a signed or unsigned :c:expr:`char`." -msgstr "" - -#: ../../c-api/conversion.rst:204 -msgid "Return true if the character *c* is an alphanumeric character." -msgstr "" - -#: ../../c-api/conversion.rst:209 -msgid "" -"Return true if the character *c* is an alphabetic character (``a-z`` and ``A-" -"Z``)." -msgstr "" - -#: ../../c-api/conversion.rst:214 -msgid "Return true if the character *c* is a decimal digit (``0-9``)." -msgstr "" - -#: ../../c-api/conversion.rst:219 -msgid "Return true if the character *c* is a lowercase ASCII letter (``a-z``)." -msgstr "" - -#: ../../c-api/conversion.rst:224 -msgid "" -"Return true if the character *c* is an uppercase ASCII letter (``A-Z``)." -msgstr "" - -#: ../../c-api/conversion.rst:229 -msgid "" -"Return true if the character *c* is a whitespace character (space, tab, " -"carriage return, newline, vertical tab, or form feed)." -msgstr "" - -#: ../../c-api/conversion.rst:235 -msgid "" -"Return true if the character *c* is a hexadecimal digit (``0-9``, ``a-f``, " -"and ``A-F``)." -msgstr "" - -#: ../../c-api/conversion.rst:241 -msgid "Return the lowercase equivalent of the character *c*." -msgstr "" - -#: ../../c-api/conversion.rst:246 -msgid "Return the uppercase equivalent of the character *c*." -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Ching-Lung Chuang, 2015 +# Leon H., 2017 +# Matt Wang , 2023 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-26 00:14+0000\n" +"PO-Revision-Date: 2023-12-11 18:26+0000\n" +"Last-Translator: Matt Wang \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" + +#: ../../c-api/conversion.rst:6 +msgid "String conversion and formatting" +msgstr "字串轉換與格式化" + +#: ../../c-api/conversion.rst:8 +msgid "Functions for number conversion and formatted string output." +msgstr "用於數字轉換和格式化字串輸出的函式。" + +#: ../../c-api/conversion.rst:13 +msgid "" +"Output not more than *size* bytes to *str* according to the format string " +"*format* and the extra arguments. See the Unix man page :manpage:" +"`snprintf(3)`." +msgstr "" +"根據格式字串 *format* 和額外引數，輸出不超過 *size* 位元組給 *str*。請參閱 " +"Unix 使用手冊 :manpage:`snprintf(3)`。" + +#: ../../c-api/conversion.rst:19 +msgid "" +"Output not more than *size* bytes to *str* according to the format string " +"*format* and the variable argument list *va*. Unix man page :manpage:" +"`vsnprintf(3)`." +msgstr "" +"根據格式字串 *format* 和變數引數串列 *va*，輸出不超過 *size* 位元組給 *str*。" +"Unix 使用手冊 :manpage:`vsnprintf(3)`。" + +#: ../../c-api/conversion.rst:23 +msgid "" +":c:func:`PyOS_snprintf` and :c:func:`PyOS_vsnprintf` wrap the Standard C " +"library functions :c:func:`snprintf` and :c:func:`vsnprintf`. Their purpose " +"is to guarantee consistent behavior in corner cases, which the Standard C " +"functions do not." +msgstr "" +":c:func:`PyOS_snprintf` 和 :c:func:`PyOS_vsnprintf` 包裝標準 C 函式庫函式 :c:" +"func:`snprintf` 和 :c:func:`vsnprintf`。它們的目的是確保邊角案例 (corner " +"case) 下的行為一致，而標準 C 函式則不然。" + +#: ../../c-api/conversion.rst:28 +msgid "" +"The wrappers ensure that ``str[size-1]`` is always ``'\\0'`` upon return. " +"They never write more than *size* bytes (including the trailing ``'\\0'``) " +"into str. Both functions require that ``str != NULL``, ``size > 0``, " +"``format != NULL`` and ``size < INT_MAX``. Note that this means there is no " +"equivalent to the C99 ``n = snprintf(NULL, 0, ...)`` which would determine " +"the necessary buffer size." +msgstr "" +"包裝器確保回傳時 ``str[size-1]`` 始終為 ``'\\0'``。他們永遠不會在 str 中寫入" +"超過 *size* 位元組（包括尾隨的 ``'\\0'``\\ ）。這兩個函式都要求 ``str != " +"NULL``、``size > 0``、``format != NULL`` 和 ``size < INT_MAX``。請注意，這表" +"示沒有與 C99 ``n = snprintf(NULL, 0, ...)`` 等效的函式來決定必要的緩衝區大" +"小。" + +#: ../../c-api/conversion.rst:34 +msgid "" +"The return value (*rv*) for these functions should be interpreted as follows:" +msgstr "這些函式的回傳值 (*rv*) 應如下被直譯：" + +#: ../../c-api/conversion.rst:36 +msgid "" +"When ``0 <= rv < size``, the output conversion was successful and *rv* " +"characters were written to *str* (excluding the trailing ``'\\0'`` byte at " +"``str[rv]``)." +msgstr "" +"當 ``0 <= rv < size`` 時，輸出轉換成功，*rv* 字元被寫入 *str*\\ （不包括 " +"``str[rv]`` 處的尾隨 ``'\\0'`` 位元組）。" + +#: ../../c-api/conversion.rst:40 +msgid "" +"When ``rv >= size``, the output conversion was truncated and a buffer with " +"``rv + 1`` bytes would have been needed to succeed. ``str[size-1]`` is " +"``'\\0'`` in this case." +msgstr "" +"當 ``rv >= size`` 時，輸出轉換被截斷，並且需要具有 ``rv + 1`` 位元組的緩衝區" +"才能成功。在這種情況下，``str[size-1]`` 是 ``'\\0'``。" + +#: ../../c-api/conversion.rst:44 +msgid "" +"When ``rv < 0``, the output conversion failed and ``str[size-1]`` is " +"``'\\0'`` in this case too, but the rest of *str* is undefined. The exact " +"cause of the error depends on the underlying platform." +msgstr "" +"當 ``rv < 0`` 時，代表輸出的轉換失敗，且在這種情況下 ``str[size-1]`` 也是 " +"``'\\0'``，但 *str* 的其餘部分未定義。錯誤的確切原因取決於底層平台。" + +#: ../../c-api/conversion.rst:49 +msgid "" +"The following functions provide locale-independent string to number " +"conversions." +msgstr "以下函式提供與區域設定無關 (locale-independent) 的字串到數字的轉換。" + +#: ../../c-api/conversion.rst:53 +msgid "" +"Convert the initial part of the string in ``str`` to an :c:expr:`unsigned " +"long` value according to the given ``base``, which must be between ``2`` and " +"``36`` inclusive, or be the special value ``0``." +msgstr "" +"將字串 ``str`` 的初始部分根據給定的 ``base`` 轉換為 :c:expr:`unsigned long` " +"值，底 (base) 必須介於 ``2`` 到 ``36``\\ （包含）之間，或為特殊值 ``0``。" + +#: ../../c-api/conversion.rst:57 +msgid "" +"Leading white space and case of characters are ignored. If ``base`` is zero " +"it looks for a leading ``0b``, ``0o`` or ``0x`` to tell which base. If " +"these are absent it defaults to ``10``. Base must be 0 or between 2 and 36 " +"(inclusive). If ``ptr`` is non-``NULL`` it will contain a pointer to the " +"end of the scan." +msgstr "" +"忽略前導空白和字元大小寫。如果 ``base`` 為零，則會尋找前導的 ``0b``、``0o`` " +"或 ``0x`` 來判斷使用哪個進位。如果這些前綴不存在，則預設為 ``10``。底必須為 " +"0 或介於 2 到 36（包含）之間。如果 ``ptr`` 為非 ``NULL``，它將包含指向掃描結" +"束處的指標。" + +#: ../../c-api/conversion.rst:63 +msgid "" +"If the converted value falls out of range of corresponding return type, " +"range error occurs (:c:data:`errno` is set to :c:macro:`!ERANGE`) and :c:" +"macro:`!ULONG_MAX` is returned. If no conversion can be performed, ``0`` is " +"returned." +msgstr "" +"如果轉換後的值超出對應回傳型別的範圍，則會發生範圍錯誤（:c:data:`errno` 會被" +"設定為 :c:macro:`!ERANGE`）並回傳 :c:macro:`!ULONG_MAX`。如果無法執行任何轉" +"換，則回傳 ``0``。" + +#: ../../c-api/conversion.rst:68 +msgid "See also the Unix man page :manpage:`strtoul(3)`." +msgstr "也請見 Unix 使用手冊 :manpage:`strtoul(3)`。" + +#: ../../c-api/conversion.rst:75 +msgid "" +"Convert the initial part of the string in ``str`` to an :c:expr:`long` value " +"according to the given ``base``, which must be between ``2`` and ``36`` " +"inclusive, or be the special value ``0``." +msgstr "" +"將字串 ``str`` 的初始部分根據給定的 ``base`` 轉換為 :c:expr:`long` 值，底 必" +"須介於 ``2`` 到 ``36`` \\ （包含）之間，或為特殊值 ``0``。" + +#: ../../c-api/conversion.rst:79 +msgid "" +"Same as :c:func:`PyOS_strtoul`, but return a :c:expr:`long` value instead " +"and :c:macro:`LONG_MAX` on overflows." +msgstr "" +"與 :c:func:`PyOS_strtoul` 相同，但回傳 :c:expr:`long` 值，並在溢位時回傳 :c:" +"macro:`LONG_MAX`。" + +#: ../../c-api/conversion.rst:82 +msgid "See also the Unix man page :manpage:`strtol(3)`." +msgstr "也請見 Unix 使用手冊 :manpage:`strtol(3)`。" + +#: ../../c-api/conversion.rst:89 +msgid "" +"Convert a string ``s`` to a :c:expr:`double`, raising a Python exception on " +"failure. The set of accepted strings corresponds to the set of strings " +"accepted by Python's :func:`float` constructor, except that ``s`` must not " +"have leading or trailing whitespace. The conversion is independent of the " +"current locale." +msgstr "" +"將字串 ``s`` 轉換為 :c:expr:`double`，失敗時引發 Python 例外。接受的字串集合" +"對應於 Python 的 :func:`float` 建構函式接受的字串集合，但 ``s`` 不得有前導或" +"尾隨的空格。轉換與目前區域設定無關。" + +#: ../../c-api/conversion.rst:95 +msgid "" +"If ``endptr`` is ``NULL``, convert the whole string. Raise :exc:" +"`ValueError` and return ``-1.0`` if the string is not a valid representation " +"of a floating-point number." +msgstr "" +"如果 ``endptr`` 為 ``NULL``，則轉換整個字串。如果字串不是浮點數的有效表示，則" +"引發 :exc:`ValueError` 並回傳 ``-1.0``。" + +#: ../../c-api/conversion.rst:99 +msgid "" +"If endptr is not ``NULL``, convert as much of the string as possible and set " +"``*endptr`` to point to the first unconverted character. If no initial " +"segment of the string is the valid representation of a floating-point " +"number, set ``*endptr`` to point to the beginning of the string, raise " +"ValueError, and return ``-1.0``." +msgstr "" +"如果 endptr 不是 ``NULL``，則盡可能轉換字串，並將 ``*endptr`` 設定為指向第一" +"個未轉換的字元。如果字串的初始片段都不是浮點數的有效表示，則設定 ``*endptr`` " +"指向字串的開頭，引發 ValueError 並回傳 ``-1.0``。" + +#: ../../c-api/conversion.rst:106 +msgid "" +"If ``s`` represents a value that is too large to store in a float (for " +"example, ``\"1e500\"`` is such a string on many platforms) then if " +"``overflow_exception`` is ``NULL`` return ``Py_INFINITY`` (with an " +"appropriate sign) and don't set any exception. Otherwise, " +"``overflow_exception`` must point to a Python exception object; raise that " +"exception and return ``-1.0``. In both cases, set ``*endptr`` to point to " +"the first character after the converted value." +msgstr "" +"如果 ``s`` 表示的值太大而無法儲存在浮點數中（例如 ``\"1e500\"`` 在許多平台上" +"都是這樣的字串），如果 ``overflow_exception`` 為 ``NULL`` 則回傳 " +"``Py_INFINITY``\\ （會帶有適當的符號）並且不設定任何例外。否則， " +"``overflow_exception`` 必須指向一個 Python 例外物件；引發該例外並回傳 " +"``-1.0``。在這兩種情況下，將 ``*endptr`` 設定為指向轉換後的值之後的第一個字" +"元。" + +#: ../../c-api/conversion.rst:114 +msgid "" +"If any other error occurs during the conversion (for example an out-of-" +"memory error), set the appropriate Python exception and return ``-1.0``." +msgstr "" +"如果轉換期間發生任何其他錯誤（例如記憶體不足的錯誤），請設定適當的 Python 例" +"外並回傳 ``-1.0``。" + +#: ../../c-api/conversion.rst:123 +msgid "" +"Convert a :c:expr:`double` *val* to a string using supplied *format_code*, " +"*precision*, and *flags*." +msgstr "" +"使用提供的 *format_code*、*precision* 和 *flags* 將 :c:expr:`double` *val* 轉" +"換為字串。" + +#: ../../c-api/conversion.rst:126 +msgid "" +"*format_code* must be one of ``'e'``, ``'E'``, ``'f'``, ``'F'``, ``'g'``, " +"``'G'`` or ``'r'``. For ``'r'``, the supplied *precision* must be 0 and is " +"ignored. The ``'r'`` format code specifies the standard :func:`repr` format." +msgstr "" +"*format_code* 必須是 ``'e'``、``'E'``、``'f'``、``'F'``、``'g'``、``'G'`` 或 " +"``'r'`` 其中之一。對於 ``'r'``，提供的 *precision* 必須為 0 並會被忽略。" +"``'r'`` 格式碼指定標準 :func:`repr` 格式。" + +#: ../../c-api/conversion.rst:131 +msgid "*flags* can be zero or more of the following values or-ed together:" +msgstr "*flags* 可以是零個或多個以下的值被聯集在一起：" + +#: ../../c-api/conversion.rst:135 +msgid "" +"Always precede the returned string with a sign character, even if *val* is " +"non-negative." +msgstr "" +"總是在回傳的字串前面加上正負號字元 (sign character)，即使 *val* 非負數。" + +#: ../../c-api/conversion.rst:140 +msgid "Ensure that the returned string will not look like an integer." +msgstr "確保回傳的字串看起來不會像整數。" + +#: ../../c-api/conversion.rst:144 +msgid "" +"Apply \"alternate\" formatting rules. See the documentation for the :c:func:" +"`PyOS_snprintf` ``'#'`` specifier for details." +msgstr "" +"套用「備用的 (alternate)」格式化規則。有關詳細資訊，請參閱 :c:func:" +"`PyOS_snprintf` ``'#'`` 的文件。" + +#: ../../c-api/conversion.rst:150 +msgid "Negative zero is converted to positive zero." +msgstr "負零會被轉換為正零。" + +#: ../../c-api/conversion.rst:154 +msgid "" +"If *ptype* is non-``NULL``, then the value it points to will be set to one " +"of ``Py_DTST_FINITE``, ``Py_DTST_INFINITE``, or ``Py_DTST_NAN``, signifying " +"that *val* is a finite number, an infinite number, or not a number, " +"respectively." +msgstr "" +"如果 *ptype* 是非 ``NULL``，那麼它指向的值將被設定為 ``Py_DTST_FINITE``、" +"``Py_DTST_INFINITE`` 或 ``Py_DTST_NAN`` 其中之一，分別代表 *val* 是有限數、無" +"限數或非數。" + +#: ../../c-api/conversion.rst:158 +msgid "" +"The return value is a pointer to *buffer* with the converted string or " +"``NULL`` if the conversion failed. The caller is responsible for freeing the " +"returned string by calling :c:func:`PyMem_Free`." +msgstr "" +"回傳值是指向 *buffer* 的指標，其中包含轉換後的字串，如果轉換失敗則回傳 " +"``NULL``。呼叫者負責透過呼叫 :c:func:`PyMem_Free` 來釋放回傳的字串。" + +#: ../../c-api/conversion.rst:168 +msgid "" +"Case insensitive comparison of strings. These functions work almost " +"identically to :c:func:`!strcmp` and :c:func:`!strncmp` (respectively), " +"except that they ignore the case of ASCII characters." +msgstr "" +"不區分大小寫的字串比較。函式的作用方式幾乎與 :c:func:`!strcmp` 和 :c:func:`!strncmp` " +"相同，只是它們忽略大小寫。" + +#: ../../c-api/conversion.rst:172 +msgid "" +"Return ``0`` if the strings are equal, a negative value if *str1* sorts " +"lexicographically before *str2*, or a positive value if it sorts after." +msgstr "" + +#: ../../c-api/conversion.rst:175 +msgid "" +"In the *str1* or *str2* arguments, a NUL byte marks the end of the string. " +"For :c:func:`!PyOS_mystrnicmp`, the *size* argument gives the maximum size " +"of the string, as if NUL was present at the index given by *size*." +msgstr "" + +#: ../../c-api/conversion.rst:179 +msgid "These functions do not use the locale." +msgstr "" + +#: ../../c-api/conversion.rst:185 +msgid "Case insensitive comparison of strings." +msgstr "不區分大小寫的字串比較。" + +#: ../../c-api/conversion.rst:187 +msgid "" +"On Windows, these are aliases of :c:func:`!stricmp` and :c:func:`!strnicmp`, " +"respectively." +msgstr "" + +#: ../../c-api/conversion.rst:190 +msgid "" +"On other platforms, they are aliases of :c:func:`PyOS_mystricmp` and :c:func:" +"`PyOS_mystrnicmp`, respectively." +msgstr "" + +#: ../../c-api/conversion.rst:195 +msgid "Character classification and conversion" +msgstr "" + +#: ../../c-api/conversion.rst:197 +msgid "" +"The following macros provide locale-independent (unlike the C standard " +"library ``ctype.h``) character classification and conversion. The argument " +"must be a signed or unsigned :c:expr:`char`." +msgstr "" + +#: ../../c-api/conversion.rst:204 +msgid "Return true if the character *c* is an alphanumeric character." +msgstr "" + +#: ../../c-api/conversion.rst:209 +msgid "" +"Return true if the character *c* is an alphabetic character (``a-z`` and ``A-" +"Z``)." +msgstr "" + +#: ../../c-api/conversion.rst:214 +msgid "Return true if the character *c* is a decimal digit (``0-9``)." +msgstr "" + +#: ../../c-api/conversion.rst:219 +msgid "Return true if the character *c* is a lowercase ASCII letter (``a-z``)." +msgstr "" + +#: ../../c-api/conversion.rst:224 +msgid "" +"Return true if the character *c* is an uppercase ASCII letter (``A-Z``)." +msgstr "" + +#: ../../c-api/conversion.rst:229 +msgid "" +"Return true if the character *c* is a whitespace character (space, tab, " +"carriage return, newline, vertical tab, or form feed)." +msgstr "" + +#: ../../c-api/conversion.rst:235 +msgid "" +"Return true if the character *c* is a hexadecimal digit (``0-9``, ``a-f``, " +"and ``A-F``)." +msgstr "" + +#: ../../c-api/conversion.rst:241 +msgid "Return the lowercase equivalent of the character *c*." +msgstr "" + +#: ../../c-api/conversion.rst:246 +msgid "Return the uppercase equivalent of the character *c*." +msgstr "" diff --git a/c-api/coro.po b/c-api/coro.po index 5ee67a7822..753442c6e0 100644 --- a/c-api/coro.po +++ b/c-api/coro.po @@ -1,59 +1,59 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Liang-Bo Wang , 2015 -# Matt Wang , 2021 -# -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2021-09-13 00:11+0000\n" -"PO-Revision-Date: 2021-12-09 21:15+0800\n" -"Last-Translator: Matt Wang \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" -"X-Generator: Poedit 3.0\n" - -#: ../../c-api/coro.rst:6 -msgid "Coroutine Objects" -msgstr "Coroutine（協程）物件" - -#: ../../c-api/coro.rst:10 -msgid "" -"Coroutine objects are what functions declared with an ``async`` keyword " -"return." -msgstr "Coroutine 物件是那些以 ``async`` 關鍵字來宣告的函式所回傳的物件。" - -#: ../../c-api/coro.rst:16 -msgid "The C structure used for coroutine objects." -msgstr "用於 coroutine 物件的 C 結構。" - -#: ../../c-api/coro.rst:21 -msgid "The type object corresponding to coroutine objects." -msgstr "與 coroutine 物件對應的型別物件。" - -#: ../../c-api/coro.rst:26 -msgid "" -"Return true if *ob*'s type is :c:type:`PyCoro_Type`; *ob* must not be " -"``NULL``. This function always succeeds." -msgstr "" -"如果 *ob* 的型別是 :c:type:`PyCoro_Type` 則回傳真值；*ob* 必須不為 ``NULL``。" -"此函式總是會執行成功。" - -#: ../../c-api/coro.rst:32 -msgid "" -"Create and return a new coroutine object based on the *frame* object, with " -"``__name__`` and ``__qualname__`` set to *name* and *qualname*. A reference " -"to *frame* is stolen by this function. The *frame* argument must not be " -"``NULL``." -msgstr "" -"基於 *frame* 物件來建立並回傳一個新的 coroutine 物件，其中 ``__name__`` 和 " -"``__qualname__`` 被設為 *name* 和 *qualname*。此函式會取得一個對 *frame* 的參" -"照 (reference)。*frame* 引數必須不為 ``NULL``。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Liang-Bo Wang , 2015 +# Matt Wang , 2021 +# +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2021-09-13 00:11+0000\n" +"PO-Revision-Date: 2021-12-09 21:15+0800\n" +"Last-Translator: Matt Wang \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" +"X-Generator: Poedit 3.0\n" + +#: ../../c-api/coro.rst:6 +msgid "Coroutine Objects" +msgstr "Coroutine（協程）物件" + +#: ../../c-api/coro.rst:10 +msgid "" +"Coroutine objects are what functions declared with an ``async`` keyword " +"return." +msgstr "Coroutine 物件是那些以 ``async`` 關鍵字來宣告的函式所回傳的物件。" + +#: ../../c-api/coro.rst:16 +msgid "The C structure used for coroutine objects." +msgstr "用於 coroutine 物件的 C 結構。" + +#: ../../c-api/coro.rst:21 +msgid "The type object corresponding to coroutine objects." +msgstr "與 coroutine 物件對應的型別物件。" + +#: ../../c-api/coro.rst:26 +msgid "" +"Return true if *ob*'s type is :c:type:`PyCoro_Type`; *ob* must not be " +"``NULL``. This function always succeeds." +msgstr "" +"如果 *ob* 的型別是 :c:type:`PyCoro_Type` 則回傳真值；*ob* 必須不為 ``NULL``。" +"此函式總是會執行成功。" + +#: ../../c-api/coro.rst:32 +msgid "" +"Create and return a new coroutine object based on the *frame* object, with " +"``__name__`` and ``__qualname__`` set to *name* and *qualname*. A reference " +"to *frame* is stolen by this function. The *frame* argument must not be " +"``NULL``." +msgstr "" +"基於 *frame* 物件來建立並回傳一個新的 coroutine 物件，其中 ``__name__`` 和 " +"``__qualname__`` 被設為 *name* 和 *qualname*。此函式會取得一個對 *frame* 的參" +"照 (reference)。*frame* 引數必須不為 ``NULL``。" diff --git a/c-api/curses.po b/c-api/curses.po index f6f79465f3..3be0c8796d 100644 --- a/c-api/curses.po +++ b/c-api/curses.po @@ -1,213 +1,213 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# FIRST AUTHOR , YEAR. -# -#, fuzzy -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-09 17:02+0000\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language-Team: LANGUAGE \n" -"Language: zh_TW\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=UTF-8\n" -"Content-Transfer-Encoding: 8bit\n" - -#: ../../c-api/curses.rst:4 -msgid "Curses C API" -msgstr "Curses C API" - -#: ../../c-api/curses.rst:6 -msgid "" -":mod:`curses` exposes a small C interface for extension modules. Consumers " -"must include the header file :file:`py_curses.h` (which is not included by " -"default by :file:`Python.h`) and :c:func:`import_curses` must be invoked, " -"usually as part of the module initialisation function, to populate :c:var:" -"`PyCurses_API`." -msgstr "" -":mod:`curses` 為擴充模組公開了一個小型的 C 介面。使用者必須包含標頭檔 " -":file:`py_curses.h`\\ （此檔案不會由 :file:`Python.h` 預設包含），並且必須觸發 " -":c:func:`import_curses` 以填充 (populate) :c:var:`PyCurses_API`，通常是作為" -"模組初始化函式的一部分。" - -#: ../../c-api/curses.rst:14 -msgid "" -"Neither the C API nor the pure Python :mod:`curses` module are compatible " -"with subinterpreters." -msgstr "" - -#: ../../c-api/curses.rst:19 -msgid "" -"Import the curses C API. The macro does not need a semi-colon to be called." -msgstr "引入 curses C API。呼叫此巨集不需要寫分號。" - -#: ../../c-api/curses.rst:21 -msgid "On success, populate the :c:var:`PyCurses_API` pointer." -msgstr "" - -#: ../../c-api/curses.rst:23 -msgid "" -"On failure, set :c:var:`PyCurses_API` to NULL and set an exception. The " -"caller must check if an error occurred via :c:func:`PyErr_Occurred`:" -msgstr "" - -#: ../../c-api/curses.rst:26 -msgid "" -"import_curses(); // semi-colon is optional but recommended\n" -"if (PyErr_Occurred()) { /* cleanup */ }" -msgstr "" -"import_curses(); // 建議要寫分號但非必要\n" -"if (PyErr_Occurred()) { /* 清理 */ }" - -#: ../../c-api/curses.rst:34 -msgid "" -"Dynamically allocated object containing the curses C API. This variable is " -"only available once :c:macro:`import_curses` succeeds." -msgstr "" - -#: ../../c-api/curses.rst:37 -msgid "``PyCurses_API[0]`` corresponds to :c:data:`PyCursesWindow_Type`." -msgstr "" - -#: ../../c-api/curses.rst:39 -msgid "" -"``PyCurses_API[1]``, ``PyCurses_API[2]``, and ``PyCurses_API[3]`` are " -"pointers to predicate functions of type ``int (*)(void)``." -msgstr "" -"``PyCurses_API[1]``、``PyCurses_API[2]`` 和 ``PyCurses_API[3]`` 是指向 " -"型別為 ``int (*)(void)`` 的謂詞函式 (predicate functions) 的指標。" - -#: ../../c-api/curses.rst:42 -msgid "" -"When called, these predicates return whether :func:`curses.setupterm`, :func:" -"`curses.initscr`, and :func:`curses.start_color` have been called " -"respectively." -msgstr "" - -#: ../../c-api/curses.rst:46 -msgid "" -"See also the convenience macros :c:macro:`PyCursesSetupTermCalled`, :c:macro:" -"`PyCursesInitialised`, and :c:macro:`PyCursesInitialisedColor`." -msgstr "" - -#: ../../c-api/curses.rst:51 -msgid "" -"The number of entries in this structure is subject to changes. Consider " -"using :c:macro:`PyCurses_API_pointers` to check if new fields are available " -"or not." -msgstr "" - -#: ../../c-api/curses.rst:58 -msgid "" -"The number of accessible fields (``4``) in :c:var:`PyCurses_API`. This " -"number is incremented whenever new fields are added." -msgstr "" - -#: ../../c-api/curses.rst:64 -msgid "" -"The :ref:`heap type ` corresponding to :class:`curses.window`." -msgstr "" - -#: ../../c-api/curses.rst:69 -msgid "" -"Return true if *op* is a :class:`curses.window` instance, false otherwise." -msgstr "如果 *op* 是 :class:`curses.window` 實例則回傳 true，否則回傳 false。" - -#: ../../c-api/curses.rst:72 -msgid "" -"The following macros are convenience macros expanding into C statements. In " -"particular, they can only be used as ``macro;`` or ``macro``, but not " -"``macro()`` or ``macro();``." -msgstr "" - -#: ../../c-api/curses.rst:78 -msgid "Macro checking if :func:`curses.setupterm` has been called." -msgstr "如果已呼叫 :func:`curses.setupterm`，則為巨集檢查。" - -#: ../../c-api/curses.rst:80 ../../c-api/curses.rst:97 -#: ../../c-api/curses.rst:114 -msgid "The macro expansion is roughly equivalent to:" -msgstr "巨集展開大致相當於：" - -#: ../../c-api/curses.rst:82 -msgid "" -"{\n" -" typedef int (*predicate_t)(void);\n" -" predicate_t was_setupterm_called = (predicate_t)PyCurses_API[1];\n" -" if (!was_setupterm_called()) {\n" -" return NULL;\n" -" }\n" -"}" -msgstr "" -"{\n" -" typedef int (*predicate_t)(void);\n" -" predicate_t was_setupterm_called = (predicate_t)PyCurses_API[1];\n" -" if (!was_setupterm_called()) {\n" -" return NULL;\n" -" }\n" -"}" - -#: ../../c-api/curses.rst:95 -msgid "Macro checking if :func:`curses.initscr` has been called." -msgstr "如果已呼叫 :func:`curses.initscr`，則為巨集檢查。" - -#: ../../c-api/curses.rst:99 -msgid "" -"{\n" -" typedef int (*predicate_t)(void);\n" -" predicate_t was_initscr_called = (predicate_t)PyCurses_API[2];\n" -" if (!was_initscr_called()) {\n" -" return NULL;\n" -" }\n" -"}" -msgstr "" -"{\n" -" typedef int (*predicate_t)(void);\n" -" predicate_t was_initscr_called = (predicate_t)PyCurses_API[2];\n" -" if (!was_initscr_called()) {\n" -" return NULL;\n" -" }\n" -"}" - -#: ../../c-api/curses.rst:112 -msgid "Macro checking if :func:`curses.start_color` has been called." -msgstr "如果已呼叫 :func:`curses.start_color`，則為巨集檢查。" - -#: ../../c-api/curses.rst:116 -msgid "" -"{\n" -" typedef int (*predicate_t)(void);\n" -" predicate_t was_start_color_called = (predicate_t)PyCurses_API[3];\n" -" if (!was_start_color_called()) {\n" -" return NULL;\n" -" }\n" -"}" -msgstr "" -"{\n" -" typedef int (*predicate_t)(void);\n" -" predicate_t was_start_color_called = (predicate_t)PyCurses_API[3];\n" -" if (!was_start_color_called()) {\n" -" return NULL;\n" -" }\n" -"}" - -#: ../../c-api/curses.rst:128 -msgid "Internal data" -msgstr "內部資料" - -#: ../../c-api/curses.rst:130 -msgid "" -"The following objects are exposed by the C API but should be considered " -"internal-only." -msgstr "以下物件由 C API 所公開，但應視為僅供內部使用。" - -#: ../../c-api/curses.rst:135 -msgid "Name of the curses capsule to pass to :c:func:`PyCapsule_Import`." -msgstr "" - -#: ../../c-api/curses.rst:137 -msgid "Internal usage only. Use :c:macro:`import_curses` instead." -msgstr "僅供內部使用。請改用 :c:macro:`import_curses`。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-09 17:02+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"Language: zh_TW\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../c-api/curses.rst:4 +msgid "Curses C API" +msgstr "Curses C API" + +#: ../../c-api/curses.rst:6 +msgid "" +":mod:`curses` exposes a small C interface for extension modules. Consumers " +"must include the header file :file:`py_curses.h` (which is not included by " +"default by :file:`Python.h`) and :c:func:`import_curses` must be invoked, " +"usually as part of the module initialisation function, to populate :c:var:" +"`PyCurses_API`." +msgstr "" +":mod:`curses` 為擴充模組公開了一個小型的 C 介面。使用者必須包含標頭檔 " +":file:`py_curses.h`\\ （此檔案不會由 :file:`Python.h` 預設包含），並且必須觸發 " +":c:func:`import_curses` 以填充 (populate) :c:var:`PyCurses_API`，通常是作為" +"模組初始化函式的一部分。" + +#: ../../c-api/curses.rst:14 +msgid "" +"Neither the C API nor the pure Python :mod:`curses` module are compatible " +"with subinterpreters." +msgstr "" + +#: ../../c-api/curses.rst:19 +msgid "" +"Import the curses C API. The macro does not need a semi-colon to be called." +msgstr "引入 curses C API。呼叫此巨集不需要寫分號。" + +#: ../../c-api/curses.rst:21 +msgid "On success, populate the :c:var:`PyCurses_API` pointer." +msgstr "" + +#: ../../c-api/curses.rst:23 +msgid "" +"On failure, set :c:var:`PyCurses_API` to NULL and set an exception. The " +"caller must check if an error occurred via :c:func:`PyErr_Occurred`:" +msgstr "" + +#: ../../c-api/curses.rst:26 +msgid "" +"import_curses(); // semi-colon is optional but recommended\n" +"if (PyErr_Occurred()) { /* cleanup */ }" +msgstr "" +"import_curses(); // 建議要寫分號但非必要\n" +"if (PyErr_Occurred()) { /* 清理 */ }" + +#: ../../c-api/curses.rst:34 +msgid "" +"Dynamically allocated object containing the curses C API. This variable is " +"only available once :c:macro:`import_curses` succeeds." +msgstr "" + +#: ../../c-api/curses.rst:37 +msgid "``PyCurses_API[0]`` corresponds to :c:data:`PyCursesWindow_Type`." +msgstr "" + +#: ../../c-api/curses.rst:39 +msgid "" +"``PyCurses_API[1]``, ``PyCurses_API[2]``, and ``PyCurses_API[3]`` are " +"pointers to predicate functions of type ``int (*)(void)``." +msgstr "" +"``PyCurses_API[1]``、``PyCurses_API[2]`` 和 ``PyCurses_API[3]`` 是指向 " +"型別為 ``int (*)(void)`` 的謂詞函式 (predicate functions) 的指標。" + +#: ../../c-api/curses.rst:42 +msgid "" +"When called, these predicates return whether :func:`curses.setupterm`, :func:" +"`curses.initscr`, and :func:`curses.start_color` have been called " +"respectively." +msgstr "" + +#: ../../c-api/curses.rst:46 +msgid "" +"See also the convenience macros :c:macro:`PyCursesSetupTermCalled`, :c:macro:" +"`PyCursesInitialised`, and :c:macro:`PyCursesInitialisedColor`." +msgstr "" + +#: ../../c-api/curses.rst:51 +msgid "" +"The number of entries in this structure is subject to changes. Consider " +"using :c:macro:`PyCurses_API_pointers` to check if new fields are available " +"or not." +msgstr "" + +#: ../../c-api/curses.rst:58 +msgid "" +"The number of accessible fields (``4``) in :c:var:`PyCurses_API`. This " +"number is incremented whenever new fields are added." +msgstr "" + +#: ../../c-api/curses.rst:64 +msgid "" +"The :ref:`heap type ` corresponding to :class:`curses.window`." +msgstr "" + +#: ../../c-api/curses.rst:69 +msgid "" +"Return true if *op* is a :class:`curses.window` instance, false otherwise." +msgstr "如果 *op* 是 :class:`curses.window` 實例則回傳 true，否則回傳 false。" + +#: ../../c-api/curses.rst:72 +msgid "" +"The following macros are convenience macros expanding into C statements. In " +"particular, they can only be used as ``macro;`` or ``macro``, but not " +"``macro()`` or ``macro();``." +msgstr "" + +#: ../../c-api/curses.rst:78 +msgid "Macro checking if :func:`curses.setupterm` has been called." +msgstr "如果已呼叫 :func:`curses.setupterm`，則為巨集檢查。" + +#: ../../c-api/curses.rst:80 ../../c-api/curses.rst:97 +#: ../../c-api/curses.rst:114 +msgid "The macro expansion is roughly equivalent to:" +msgstr "巨集展開大致相當於：" + +#: ../../c-api/curses.rst:82 +msgid "" +"{\n" +" typedef int (*predicate_t)(void);\n" +" predicate_t was_setupterm_called = (predicate_t)PyCurses_API[1];\n" +" if (!was_setupterm_called()) {\n" +" return NULL;\n" +" }\n" +"}" +msgstr "" +"{\n" +" typedef int (*predicate_t)(void);\n" +" predicate_t was_setupterm_called = (predicate_t)PyCurses_API[1];\n" +" if (!was_setupterm_called()) {\n" +" return NULL;\n" +" }\n" +"}" + +#: ../../c-api/curses.rst:95 +msgid "Macro checking if :func:`curses.initscr` has been called." +msgstr "如果已呼叫 :func:`curses.initscr`，則為巨集檢查。" + +#: ../../c-api/curses.rst:99 +msgid "" +"{\n" +" typedef int (*predicate_t)(void);\n" +" predicate_t was_initscr_called = (predicate_t)PyCurses_API[2];\n" +" if (!was_initscr_called()) {\n" +" return NULL;\n" +" }\n" +"}" +msgstr "" +"{\n" +" typedef int (*predicate_t)(void);\n" +" predicate_t was_initscr_called = (predicate_t)PyCurses_API[2];\n" +" if (!was_initscr_called()) {\n" +" return NULL;\n" +" }\n" +"}" + +#: ../../c-api/curses.rst:112 +msgid "Macro checking if :func:`curses.start_color` has been called." +msgstr "如果已呼叫 :func:`curses.start_color`，則為巨集檢查。" + +#: ../../c-api/curses.rst:116 +msgid "" +"{\n" +" typedef int (*predicate_t)(void);\n" +" predicate_t was_start_color_called = (predicate_t)PyCurses_API[3];\n" +" if (!was_start_color_called()) {\n" +" return NULL;\n" +" }\n" +"}" +msgstr "" +"{\n" +" typedef int (*predicate_t)(void);\n" +" predicate_t was_start_color_called = (predicate_t)PyCurses_API[3];\n" +" if (!was_start_color_called()) {\n" +" return NULL;\n" +" }\n" +"}" + +#: ../../c-api/curses.rst:128 +msgid "Internal data" +msgstr "內部資料" + +#: ../../c-api/curses.rst:130 +msgid "" +"The following objects are exposed by the C API but should be considered " +"internal-only." +msgstr "以下物件由 C API 所公開，但應視為僅供內部使用。" + +#: ../../c-api/curses.rst:135 +msgid "Name of the curses capsule to pass to :c:func:`PyCapsule_Import`." +msgstr "" + +#: ../../c-api/curses.rst:137 +msgid "Internal usage only. Use :c:macro:`import_curses` instead." +msgstr "僅供內部使用。請改用 :c:macro:`import_curses`。" diff --git a/c-api/datetime.po b/c-api/datetime.po index 9a62a3dbf6..10014fdf64 100644 --- a/c-api/datetime.po +++ b/c-api/datetime.po @@ -1,444 +1,444 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Ching-Lung Chuang, 2015 -# Liang-Bo Wang , 2015 -# Matt Wang , 2023 -# Yorkxe , 2025 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-20 17:54+0000\n" -"PO-Revision-Date: 2025-10-14 20:39+0800\n" -"Last-Translator: Yorkxe \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" -"X-Generator: Poedit 3.3.1\n" - -#: ../../c-api/datetime.rst:6 -msgid "DateTime Objects" -msgstr "DateTime 物件" - -#: ../../c-api/datetime.rst:8 -msgid "" -"Various date and time objects are supplied by the :mod:`datetime` module. " -"Before using any of these functions, the header file :file:`datetime.h` must " -"be included in your source (note that this is not included by :file:`Python." -"h`), and the macro :c:macro:`PyDateTime_IMPORT` must be invoked, usually as " -"part of the module initialisation function. The macro puts a pointer to a C " -"structure into a static variable, :c:data:`PyDateTimeAPI`, that is used by " -"the following macros." -msgstr "" -":mod:`datetime` 模組提供各種日期和時間物件。在使用任何這些函式之前，必須將標" -"頭檔 :file:`datetime.h` 引入於原始碼中（請注意，:file:`Python.h` 並無引入該標" -"頭檔），且巨集 :c:macro:`PyDateTime_IMPORT` 必須被叫用，而這通常作為模組初始" -"化函式的一部分。該巨集將指向 C 結構的指標放入靜態變數 :c:data:`" -"PyDateTimeAPI` 中，該變數會被以下巨集使用。" - -#: ../../c-api/datetime.rst:18 -msgid "Import the datetime C API." -msgstr "引入 datetime C API。" - -#: ../../c-api/datetime.rst:20 -msgid "" -"On success, populate the :c:var:`PyDateTimeAPI` pointer. On failure, set :c:" -"var:`PyDateTimeAPI` to ``NULL`` and set an exception. The caller must check " -"if an error occurred via :c:func:`PyErr_Occurred`:" -msgstr "" -"成功時填充 (populate) :c:var:`PyDateTimeAPI` 指標。失敗時將 :c:var:`PyDateTimeAPI` 設為 " -"``NULL`` 並設定一個例外。呼叫者必須透過 :c:func:`PyErr_Occurred` 檢查是否發生錯" -"誤：" - -#: ../../c-api/datetime.rst:24 -msgid "" -"PyDateTime_IMPORT;\n" -"if (PyErr_Occurred()) { /* cleanup */ }" -msgstr "" -"PyDateTime_IMPORT;\n" -"if (PyErr_Occurred()) { /* cleanup */ }" - -#: ../../c-api/datetime.rst:31 -msgid "This is not compatible with subinterpreters." -msgstr "這和子直譯器 (subinterpreters) 不相容。" - -#: ../../c-api/datetime.rst:35 -msgid "Structure containing the fields for the datetime C API." -msgstr "包含 datetime C API 欄位的結構。" - -#: ../../c-api/datetime.rst:37 -msgid "The fields of this structure are private and subject to change." -msgstr "此結構的欄位為私有且可能會變動。" - -#: ../../c-api/datetime.rst:39 -msgid "Do not use this directly; prefer ``PyDateTime_*`` APIs instead." -msgstr "不要直接使用這個；請改用 ``PyDateTime_*`` API。" - -#: ../../c-api/datetime.rst:43 -msgid "Dynamically allocated object containing the datetime C API." -msgstr "動態配置的物件，包含 datetime C API。" - -#: ../../c-api/datetime.rst:45 -msgid "" -"This variable is only available once :c:macro:`PyDateTime_IMPORT` succeeds." -msgstr "此變數僅在 :c:macro:`PyDateTime_IMPORT` 成功後可用。" - -#: ../../c-api/datetime.rst:49 -msgid "This subtype of :c:type:`PyObject` represents a Python date object." -msgstr "此 :c:type:`PyObject` 子型別代表 Python date 物件" - -#: ../../c-api/datetime.rst:53 -msgid "This subtype of :c:type:`PyObject` represents a Python datetime object." -msgstr "此 :c:type:`PyObject` 子型別代表 Python datetime 物件" - -#: ../../c-api/datetime.rst:57 -msgid "This subtype of :c:type:`PyObject` represents a Python time object." -msgstr "此 :c:type:`PyObject` 子型別代表 Python time 物件" - -#: ../../c-api/datetime.rst:61 -msgid "" -"This subtype of :c:type:`PyObject` represents the difference between two " -"datetime values." -msgstr "此 :c:type:`PyObject` 子型別代表兩個 datetime 物件的差值" - -#: ../../c-api/datetime.rst:65 -msgid "" -"This instance of :c:type:`PyTypeObject` represents the Python date type; it " -"is the same object as :class:`datetime.date` in the Python layer." -msgstr "" -"此 :c:type:`PyTypeObject` 實例代表 Python date 型別，與 Python layer 中的 :" -"class:`datetime.date` 是同一物件" - -#: ../../c-api/datetime.rst:70 -msgid "" -"This instance of :c:type:`PyTypeObject` represents the Python datetime type; " -"it is the same object as :class:`datetime.datetime` in the Python layer." -msgstr "" -"此 :c:type:`PyTypeObject` 實例代表 Python datetime 型別，與 Python layer 中" -"的 :class:`datetime.datetime` 是同一物件" - -#: ../../c-api/datetime.rst:75 -msgid "" -"This instance of :c:type:`PyTypeObject` represents the Python time type; it " -"is the same object as :class:`datetime.time` in the Python layer." -msgstr "" -"此 :c:type:`PyTypeObject` 實例代表 Python time 型別，與 Python layer 中的 :" -"class:`datetime.time` 是同一物件" - -#: ../../c-api/datetime.rst:80 -msgid "" -"This instance of :c:type:`PyTypeObject` represents the Python type for the " -"difference between two datetime values; it is the same object as :class:" -"`datetime.timedelta` in the Python layer." -msgstr "" -"此 :c:type:`PyTypeObject` 實例代表 Python 兩個 datetime 物件的型別，與 " -"Python layer 中的 :class:`datetime.timedelta` 是同一物件" - -#: ../../c-api/datetime.rst:86 -msgid "" -"This instance of :c:type:`PyTypeObject` represents the Python time zone info " -"type; it is the same object as :class:`datetime.tzinfo` in the Python layer." -msgstr "" -"此 :c:type:`PyTypeObject` 實例代表 Python 時區資訊型別，與 Python layer 中" -"的 :class:`datetime.tzinfo` 是同一物件" - -#: ../../c-api/datetime.rst:90 -msgid "Macro for access to the UTC singleton:" -msgstr "用於存取 UTC 單例 (singleton) 的巨集：" - -#: ../../c-api/datetime.rst:94 -msgid "" -"Returns the time zone singleton representing UTC, the same object as :attr:" -"`datetime.timezone.utc`." -msgstr "" -"回傳表示 UTC 的時區單例，是與 :attr:`datetime.timezone.utc` 相同的物件。" - -#: ../../c-api/datetime.rst:100 -msgid "Type-check macros:" -msgstr "型別檢查巨集：" - -#: ../../c-api/datetime.rst:104 -msgid "" -"Return true if *ob* is of type :c:data:`PyDateTime_DateType` or a subtype " -"of :c:data:`!PyDateTime_DateType`. *ob* must not be ``NULL``. This " -"function always succeeds." -msgstr "" -"如果 *ob* 的型別為 :c:data:`PyDateTime_DateType` 或 :c:data:`!" -"PyDateTime_DateType` 的子型別，則回傳 true。 *ob* 不得為 ``NULL``。這個函式一" -"定會執行成功。" - -#: ../../c-api/datetime.rst:111 -msgid "" -"Return true if *ob* is of type :c:data:`PyDateTime_DateType`. *ob* must not " -"be ``NULL``. This function always succeeds." -msgstr "" -"如果 *ob* 的型別為 :c:data:`PyDateTime_DateType`，則回傳 true。 *ob* 不得為 " -"``NULL``。這個函式一定會執行成功。" - -#: ../../c-api/datetime.rst:117 -msgid "" -"Return true if *ob* is of type :c:data:`PyDateTime_DateTimeType` or a " -"subtype of :c:data:`!PyDateTime_DateTimeType`. *ob* must not be ``NULL``. " -"This function always succeeds." -msgstr "" -"如果 *ob* 的型別為 :c:data:`PyDateTime_DateTimeType` 或 :c:data:`!" -"PyDateTime_DateTimeType` 的子型別，則回傳 true。*ob* 不得為 ``NULL``。這個函" -"式一定會執行成功。" - -#: ../../c-api/datetime.rst:124 -msgid "" -"Return true if *ob* is of type :c:data:`PyDateTime_DateTimeType`. *ob* must " -"not be ``NULL``. This function always succeeds." -msgstr "" -"如果 *ob* 的型別為 :c:data:`PyDateTime_DateTimeType`，則回傳 true。*ob* 不得" -"為 ``NULL``。這個函式一定會執行成功。" - -#: ../../c-api/datetime.rst:130 -msgid "" -"Return true if *ob* is of type :c:data:`PyDateTime_TimeType` or a subtype " -"of :c:data:`!PyDateTime_TimeType`. *ob* must not be ``NULL``. This " -"function always succeeds." -msgstr "" -"如果 *ob* 的型別為 :c:data:`PyDateTime_TimeType` 或 :c:data:`!" -"PyDateTime_TimeType` 的子型別，則回傳 true。*ob* 不得為 ``NULL``。這個函式一" -"定會執行成功。" - -#: ../../c-api/datetime.rst:137 -msgid "" -"Return true if *ob* is of type :c:data:`PyDateTime_TimeType`. *ob* must not " -"be ``NULL``. This function always succeeds." -msgstr "" -"如果 *ob* 的型別為 :c:data:`PyDateTime_TimeType`，則回傳 true。*ob* 不得為 " -"``NULL``。這個函式一定會執行成功。" - -#: ../../c-api/datetime.rst:143 -msgid "" -"Return true if *ob* is of type :c:data:`PyDateTime_DeltaType` or a subtype " -"of :c:data:`!PyDateTime_DeltaType`. *ob* must not be ``NULL``. This " -"function always succeeds." -msgstr "" -"如果 *ob* 的型別為 :c:data:`PyDateTime_DeltaType` 或 :c:data:`!" -"PyDateTime_DeltaType` 的子型別，則回傳 true。*ob* 不得為 ``NULL``。這個函式一" -"定會執行成功。" - -#: ../../c-api/datetime.rst:150 -msgid "" -"Return true if *ob* is of type :c:data:`PyDateTime_DeltaType`. *ob* must not " -"be ``NULL``. This function always succeeds." -msgstr "" -"如果 *ob* 的型別為 :c:data:`PyDateTime_DeltaType`，則回傳 true。*ob* 不得為 " -"``NULL``。這個函式一定會執行成功。" - -#: ../../c-api/datetime.rst:156 -msgid "" -"Return true if *ob* is of type :c:data:`PyDateTime_TZInfoType` or a subtype " -"of :c:data:`!PyDateTime_TZInfoType`. *ob* must not be ``NULL``. This " -"function always succeeds." -msgstr "" -"如果 *ob* 的型別為 :c:data:`PyDateTime_TZInfoType` 或 :c:data:`!" -"PyDateTime_TZInfoType` 的子型別，則回傳 true。*ob* 不得為 ``NULL``。這個函式" -"一定會執行成功。" - -#: ../../c-api/datetime.rst:163 -msgid "" -"Return true if *ob* is of type :c:data:`PyDateTime_TZInfoType`. *ob* must " -"not be ``NULL``. This function always succeeds." -msgstr "" -"如果 *ob* 的型別為 :c:data:`PyDateTime_TZInfoType`，則回傳 true。 *ob* 不得" -"為 ``NULL``。這個函式一定會執行成功。" - -#: ../../c-api/datetime.rst:167 -msgid "Macros to create objects:" -msgstr "建立物件的巨集：" - -#: ../../c-api/datetime.rst:171 -msgid "" -"Return a :class:`datetime.date` object with the specified year, month and " -"day." -msgstr "回傳一個有特定年、月、日的物件 :class:`datetime.date`。" - -#: ../../c-api/datetime.rst:176 -msgid "" -"Return a :class:`datetime.datetime` object with the specified year, month, " -"day, hour, minute, second and microsecond." -msgstr "" -"回傳一個有特定年、月、日、時、分、秒、微秒的物件 :class:`datetime.datetime`。" - -#: ../../c-api/datetime.rst:182 -msgid "" -"Return a :class:`datetime.datetime` object with the specified year, month, " -"day, hour, minute, second, microsecond and fold." -msgstr "" -"回傳一個有特定年、月、日、時、分、秒、微秒與 fold（時間折疊）的物件 :class:" -"`datetime.datetime`。" - -#: ../../c-api/datetime.rst:190 -msgid "" -"Return a :class:`datetime.time` object with the specified hour, minute, " -"second and microsecond." -msgstr "回傳一個有特定時、分、秒、微秒的物件 :class:`datetime.time`。" - -#: ../../c-api/datetime.rst:196 -msgid "" -"Return a :class:`datetime.time` object with the specified hour, minute, " -"second, microsecond and fold." -msgstr "" -"回傳一個有特定時、分、秒、微秒與 fold（時間折疊）的物件 :class:`datetime." -"time`。" - -#: ../../c-api/datetime.rst:204 -msgid "" -"Return a :class:`datetime.timedelta` object representing the given number of " -"days, seconds and microseconds. Normalization is performed so that the " -"resulting number of microseconds and seconds lie in the ranges documented " -"for :class:`datetime.timedelta` objects." -msgstr "" -"回傳一個 :class:`datetime.timedelta` 物件，表示給定的天數、秒數和微秒數。執行" -"標準化 (normalization) 以便生成的微秒數和秒數位於 :class:`datetime." -"timedelta` 物件記錄的範圍內。" - -#: ../../c-api/datetime.rst:212 -msgid "" -"Return a :class:`datetime.timezone` object with an unnamed fixed offset " -"represented by the *offset* argument." -msgstr "" -"回傳一個 :class:`datetime.timezone` 物件，其未命名的固定偏移量由 *offset* 引" -"數表示。" - -#: ../../c-api/datetime.rst:220 -msgid "" -"Return a :class:`datetime.timezone` object with a fixed offset represented " -"by the *offset* argument and with tzname *name*." -msgstr "" -"回傳一個 :class:`datetime.timezone` 物件，其固定偏移量由 *offset* 引數表示，" -"並帶有 tzname *name*。" - -#: ../../c-api/datetime.rst:226 -msgid "" -"Macros to extract fields from date objects. The argument must be an " -"instance of :c:type:`PyDateTime_Date`, including subclasses (such as :c:type:" -"`PyDateTime_DateTime`). The argument must not be ``NULL``, and the type is " -"not checked:" -msgstr "" -"從 date 物件中提取欄位的巨集。引數必須是個 :c:type:`PyDateTime_Date` 的實例，" -"包括子類別（例如 :c:type:`PyDateTime_DateTime`）。引數不得為 ``NULL``，並且不" -"會檢查型別：" - -#: ../../c-api/datetime.rst:233 -msgid "Return the year, as a positive int." -msgstr "回傳年份，為正整數。" - -#: ../../c-api/datetime.rst:238 -msgid "Return the month, as an int from 1 through 12." -msgstr "回傳月份，為正整數，從 1 到 12。" - -#: ../../c-api/datetime.rst:243 -msgid "Return the day, as an int from 1 through 31." -msgstr "回傳日期，為正整數，從 1 到 31。" - -#: ../../c-api/datetime.rst:246 -msgid "" -"Macros to extract fields from datetime objects. The argument must be an " -"instance of :c:type:`PyDateTime_DateTime`, including subclasses. The " -"argument must not be ``NULL``, and the type is not checked:" -msgstr "" -"從 datetime 物件中提取欄位的巨集。引數必須是個 :c:type:`PyDateTime_DateTime` " -"的實例，包括子類別。引數不得為 ``NULL``，並且不會檢查型別：" - -#: ../../c-api/datetime.rst:252 ../../c-api/datetime.rst:290 -msgid "Return the hour, as an int from 0 through 23." -msgstr "回傳小時，為正整數，從 0 到 23。" - -#: ../../c-api/datetime.rst:257 ../../c-api/datetime.rst:295 -msgid "Return the minute, as an int from 0 through 59." -msgstr "回傳分鐘，為正整數，從 0 到 59。" - -#: ../../c-api/datetime.rst:262 ../../c-api/datetime.rst:300 -msgid "Return the second, as an int from 0 through 59." -msgstr "回傳秒，為正整數，從0 到59。" - -#: ../../c-api/datetime.rst:267 ../../c-api/datetime.rst:305 -msgid "Return the microsecond, as an int from 0 through 999999." -msgstr "回傳微秒，為正整數，從 0 到 999999。" - -#: ../../c-api/datetime.rst:272 ../../c-api/datetime.rst:310 -msgid "Return the fold, as an int from 0 through 1." -msgstr "回傳 fold，為 0 或 1 的正整數。" - -#: ../../c-api/datetime.rst:279 ../../c-api/datetime.rst:317 -msgid "Return the tzinfo (which may be ``None``)." -msgstr "回傳 tzinfo（可能是 ``None``）。" - -#: ../../c-api/datetime.rst:284 -msgid "" -"Macros to extract fields from time objects. The argument must be an " -"instance of :c:type:`PyDateTime_Time`, including subclasses. The argument " -"must not be ``NULL``, and the type is not checked:" -msgstr "" -"從 time 物件中提取欄位的巨集。引數必須是個 :c:type:`PyDateTime_Time` 的實例，" -"包括子類別。引數不得為 ``NULL``，並且不會檢查型別：" - -#: ../../c-api/datetime.rst:322 -msgid "" -"Macros to extract fields from time delta objects. The argument must be an " -"instance of :c:type:`PyDateTime_Delta`, including subclasses. The argument " -"must not be ``NULL``, and the type is not checked:" -msgstr "" -"從 time delta 物件中提取欄位的巨集。引數必須是個 :c:type:`PyDateTime_Delta` " -"的實例，包括子類別。引數不能為 ``NULL``，並且不會檢查型別：" - -#: ../../c-api/datetime.rst:328 -msgid "Return the number of days, as an int from -999999999 to 999999999." -msgstr "以 -999999999 到 999999999 之間的整數形式回傳天數。" - -#: ../../c-api/datetime.rst:335 -msgid "Return the number of seconds, as an int from 0 through 86399." -msgstr "以 0 到 86399 之間的整數形式回傳秒數。" - -#: ../../c-api/datetime.rst:342 -msgid "Return the number of microseconds, as an int from 0 through 999999." -msgstr "以 0 到 999999 之間的整數形式回傳微秒數。" - -#: ../../c-api/datetime.rst:347 -msgid "Macros for the convenience of modules implementing the DB API:" -msgstr "為了方便模組實作 DB API 的巨集：" - -#: ../../c-api/datetime.rst:351 -msgid "" -"Create and return a new :class:`datetime.datetime` object given an argument " -"tuple suitable for passing to :meth:`datetime.datetime.fromtimestamp`." -msgstr "" -"給定一個適合傳遞給 :meth:`datetime.datetime.fromtimestamp` 的引數元組，建立並" -"回傳一個新的 :class:`datetime.datetime` 物件。" - -#: ../../c-api/datetime.rst:357 -msgid "" -"Create and return a new :class:`datetime.date` object given an argument " -"tuple suitable for passing to :meth:`datetime.date.fromtimestamp`." -msgstr "" -"給定一個適合傳遞給 :meth:`datetime.date.fromtimestamp` 的引數元組，建立並回傳" -"一個新的 :class:`datetime.date` 物件。" - -#: ../../c-api/datetime.rst:362 -msgid "Internal data" -msgstr "內部資料" - -#: ../../c-api/datetime.rst:364 -msgid "" -"The following symbols are exposed by the C API but should be considered " -"internal-only." -msgstr "以下符號由 C API 公開，但應視為僅供內部使用。" - -#: ../../c-api/datetime.rst:369 -msgid "Name of the datetime capsule to pass to :c:func:`PyCapsule_Import`." -msgstr "傳遞給 :c:func:`PyCapsule_Import` 的 datetime capsule 名稱。" - -#: ../../c-api/datetime.rst:371 -msgid "Internal usage only. Use :c:macro:`PyDateTime_IMPORT` instead." -msgstr "僅供內部使用。請改用 :c:macro:`PyDateTime_IMPORT`。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Ching-Lung Chuang, 2015 +# Liang-Bo Wang , 2015 +# Matt Wang , 2023 +# Yorkxe , 2025 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-20 17:54+0000\n" +"PO-Revision-Date: 2025-10-14 20:39+0800\n" +"Last-Translator: Yorkxe \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" +"X-Generator: Poedit 3.3.1\n" + +#: ../../c-api/datetime.rst:6 +msgid "DateTime Objects" +msgstr "DateTime 物件" + +#: ../../c-api/datetime.rst:8 +msgid "" +"Various date and time objects are supplied by the :mod:`datetime` module. " +"Before using any of these functions, the header file :file:`datetime.h` must " +"be included in your source (note that this is not included by :file:`Python." +"h`), and the macro :c:macro:`PyDateTime_IMPORT` must be invoked, usually as " +"part of the module initialisation function. The macro puts a pointer to a C " +"structure into a static variable, :c:data:`PyDateTimeAPI`, that is used by " +"the following macros." +msgstr "" +":mod:`datetime` 模組提供各種日期和時間物件。在使用任何這些函式之前，必須將標" +"頭檔 :file:`datetime.h` 引入於原始碼中（請注意，:file:`Python.h` 並無引入該標" +"頭檔），且巨集 :c:macro:`PyDateTime_IMPORT` 必須被叫用，而這通常作為模組初始" +"化函式的一部分。該巨集將指向 C 結構的指標放入靜態變數 :c:data:`" +"PyDateTimeAPI` 中，該變數會被以下巨集使用。" + +#: ../../c-api/datetime.rst:18 +msgid "Import the datetime C API." +msgstr "引入 datetime C API。" + +#: ../../c-api/datetime.rst:20 +msgid "" +"On success, populate the :c:var:`PyDateTimeAPI` pointer. On failure, set :c:" +"var:`PyDateTimeAPI` to ``NULL`` and set an exception. The caller must check " +"if an error occurred via :c:func:`PyErr_Occurred`:" +msgstr "" +"成功時填充 (populate) :c:var:`PyDateTimeAPI` 指標。失敗時將 :c:var:`PyDateTimeAPI` 設為 " +"``NULL`` 並設定一個例外。呼叫者必須透過 :c:func:`PyErr_Occurred` 檢查是否發生錯" +"誤：" + +#: ../../c-api/datetime.rst:24 +msgid "" +"PyDateTime_IMPORT;\n" +"if (PyErr_Occurred()) { /* cleanup */ }" +msgstr "" +"PyDateTime_IMPORT;\n" +"if (PyErr_Occurred()) { /* cleanup */ }" + +#: ../../c-api/datetime.rst:31 +msgid "This is not compatible with subinterpreters." +msgstr "這和子直譯器 (subinterpreters) 不相容。" + +#: ../../c-api/datetime.rst:35 +msgid "Structure containing the fields for the datetime C API." +msgstr "包含 datetime C API 欄位的結構。" + +#: ../../c-api/datetime.rst:37 +msgid "The fields of this structure are private and subject to change." +msgstr "此結構的欄位為私有且可能會變動。" + +#: ../../c-api/datetime.rst:39 +msgid "Do not use this directly; prefer ``PyDateTime_*`` APIs instead." +msgstr "不要直接使用這個；請改用 ``PyDateTime_*`` API。" + +#: ../../c-api/datetime.rst:43 +msgid "Dynamically allocated object containing the datetime C API." +msgstr "動態配置的物件，包含 datetime C API。" + +#: ../../c-api/datetime.rst:45 +msgid "" +"This variable is only available once :c:macro:`PyDateTime_IMPORT` succeeds." +msgstr "此變數僅在 :c:macro:`PyDateTime_IMPORT` 成功後可用。" + +#: ../../c-api/datetime.rst:49 +msgid "This subtype of :c:type:`PyObject` represents a Python date object." +msgstr "此 :c:type:`PyObject` 子型別代表 Python date 物件" + +#: ../../c-api/datetime.rst:53 +msgid "This subtype of :c:type:`PyObject` represents a Python datetime object." +msgstr "此 :c:type:`PyObject` 子型別代表 Python datetime 物件" + +#: ../../c-api/datetime.rst:57 +msgid "This subtype of :c:type:`PyObject` represents a Python time object." +msgstr "此 :c:type:`PyObject` 子型別代表 Python time 物件" + +#: ../../c-api/datetime.rst:61 +msgid "" +"This subtype of :c:type:`PyObject` represents the difference between two " +"datetime values." +msgstr "此 :c:type:`PyObject` 子型別代表兩個 datetime 物件的差值" + +#: ../../c-api/datetime.rst:65 +msgid "" +"This instance of :c:type:`PyTypeObject` represents the Python date type; it " +"is the same object as :class:`datetime.date` in the Python layer." +msgstr "" +"此 :c:type:`PyTypeObject` 實例代表 Python date 型別，與 Python layer 中的 :" +"class:`datetime.date` 是同一物件" + +#: ../../c-api/datetime.rst:70 +msgid "" +"This instance of :c:type:`PyTypeObject` represents the Python datetime type; " +"it is the same object as :class:`datetime.datetime` in the Python layer." +msgstr "" +"此 :c:type:`PyTypeObject` 實例代表 Python datetime 型別，與 Python layer 中" +"的 :class:`datetime.datetime` 是同一物件" + +#: ../../c-api/datetime.rst:75 +msgid "" +"This instance of :c:type:`PyTypeObject` represents the Python time type; it " +"is the same object as :class:`datetime.time` in the Python layer." +msgstr "" +"此 :c:type:`PyTypeObject` 實例代表 Python time 型別，與 Python layer 中的 :" +"class:`datetime.time` 是同一物件" + +#: ../../c-api/datetime.rst:80 +msgid "" +"This instance of :c:type:`PyTypeObject` represents the Python type for the " +"difference between two datetime values; it is the same object as :class:" +"`datetime.timedelta` in the Python layer." +msgstr "" +"此 :c:type:`PyTypeObject` 實例代表 Python 兩個 datetime 物件的型別，與 " +"Python layer 中的 :class:`datetime.timedelta` 是同一物件" + +#: ../../c-api/datetime.rst:86 +msgid "" +"This instance of :c:type:`PyTypeObject` represents the Python time zone info " +"type; it is the same object as :class:`datetime.tzinfo` in the Python layer." +msgstr "" +"此 :c:type:`PyTypeObject` 實例代表 Python 時區資訊型別，與 Python layer 中" +"的 :class:`datetime.tzinfo` 是同一物件" + +#: ../../c-api/datetime.rst:90 +msgid "Macro for access to the UTC singleton:" +msgstr "用於存取 UTC 單例 (singleton) 的巨集：" + +#: ../../c-api/datetime.rst:94 +msgid "" +"Returns the time zone singleton representing UTC, the same object as :attr:" +"`datetime.timezone.utc`." +msgstr "" +"回傳表示 UTC 的時區單例，是與 :attr:`datetime.timezone.utc` 相同的物件。" + +#: ../../c-api/datetime.rst:100 +msgid "Type-check macros:" +msgstr "型別檢查巨集：" + +#: ../../c-api/datetime.rst:104 +msgid "" +"Return true if *ob* is of type :c:data:`PyDateTime_DateType` or a subtype " +"of :c:data:`!PyDateTime_DateType`. *ob* must not be ``NULL``. This " +"function always succeeds." +msgstr "" +"如果 *ob* 的型別為 :c:data:`PyDateTime_DateType` 或 :c:data:`!" +"PyDateTime_DateType` 的子型別，則回傳 true。 *ob* 不得為 ``NULL``。這個函式一" +"定會執行成功。" + +#: ../../c-api/datetime.rst:111 +msgid "" +"Return true if *ob* is of type :c:data:`PyDateTime_DateType`. *ob* must not " +"be ``NULL``. This function always succeeds." +msgstr "" +"如果 *ob* 的型別為 :c:data:`PyDateTime_DateType`，則回傳 true。 *ob* 不得為 " +"``NULL``。這個函式一定會執行成功。" + +#: ../../c-api/datetime.rst:117 +msgid "" +"Return true if *ob* is of type :c:data:`PyDateTime_DateTimeType` or a " +"subtype of :c:data:`!PyDateTime_DateTimeType`. *ob* must not be ``NULL``. " +"This function always succeeds." +msgstr "" +"如果 *ob* 的型別為 :c:data:`PyDateTime_DateTimeType` 或 :c:data:`!" +"PyDateTime_DateTimeType` 的子型別，則回傳 true。*ob* 不得為 ``NULL``。這個函" +"式一定會執行成功。" + +#: ../../c-api/datetime.rst:124 +msgid "" +"Return true if *ob* is of type :c:data:`PyDateTime_DateTimeType`. *ob* must " +"not be ``NULL``. This function always succeeds." +msgstr "" +"如果 *ob* 的型別為 :c:data:`PyDateTime_DateTimeType`，則回傳 true。*ob* 不得" +"為 ``NULL``。這個函式一定會執行成功。" + +#: ../../c-api/datetime.rst:130 +msgid "" +"Return true if *ob* is of type :c:data:`PyDateTime_TimeType` or a subtype " +"of :c:data:`!PyDateTime_TimeType`. *ob* must not be ``NULL``. This " +"function always succeeds." +msgstr "" +"如果 *ob* 的型別為 :c:data:`PyDateTime_TimeType` 或 :c:data:`!" +"PyDateTime_TimeType` 的子型別，則回傳 true。*ob* 不得為 ``NULL``。這個函式一" +"定會執行成功。" + +#: ../../c-api/datetime.rst:137 +msgid "" +"Return true if *ob* is of type :c:data:`PyDateTime_TimeType`. *ob* must not " +"be ``NULL``. This function always succeeds." +msgstr "" +"如果 *ob* 的型別為 :c:data:`PyDateTime_TimeType`，則回傳 true。*ob* 不得為 " +"``NULL``。這個函式一定會執行成功。" + +#: ../../c-api/datetime.rst:143 +msgid "" +"Return true if *ob* is of type :c:data:`PyDateTime_DeltaType` or a subtype " +"of :c:data:`!PyDateTime_DeltaType`. *ob* must not be ``NULL``. This " +"function always succeeds." +msgstr "" +"如果 *ob* 的型別為 :c:data:`PyDateTime_DeltaType` 或 :c:data:`!" +"PyDateTime_DeltaType` 的子型別，則回傳 true。*ob* 不得為 ``NULL``。這個函式一" +"定會執行成功。" + +#: ../../c-api/datetime.rst:150 +msgid "" +"Return true if *ob* is of type :c:data:`PyDateTime_DeltaType`. *ob* must not " +"be ``NULL``. This function always succeeds." +msgstr "" +"如果 *ob* 的型別為 :c:data:`PyDateTime_DeltaType`，則回傳 true。*ob* 不得為 " +"``NULL``。這個函式一定會執行成功。" + +#: ../../c-api/datetime.rst:156 +msgid "" +"Return true if *ob* is of type :c:data:`PyDateTime_TZInfoType` or a subtype " +"of :c:data:`!PyDateTime_TZInfoType`. *ob* must not be ``NULL``. This " +"function always succeeds." +msgstr "" +"如果 *ob* 的型別為 :c:data:`PyDateTime_TZInfoType` 或 :c:data:`!" +"PyDateTime_TZInfoType` 的子型別，則回傳 true。*ob* 不得為 ``NULL``。這個函式" +"一定會執行成功。" + +#: ../../c-api/datetime.rst:163 +msgid "" +"Return true if *ob* is of type :c:data:`PyDateTime_TZInfoType`. *ob* must " +"not be ``NULL``. This function always succeeds." +msgstr "" +"如果 *ob* 的型別為 :c:data:`PyDateTime_TZInfoType`，則回傳 true。 *ob* 不得" +"為 ``NULL``。這個函式一定會執行成功。" + +#: ../../c-api/datetime.rst:167 +msgid "Macros to create objects:" +msgstr "建立物件的巨集：" + +#: ../../c-api/datetime.rst:171 +msgid "" +"Return a :class:`datetime.date` object with the specified year, month and " +"day." +msgstr "回傳一個有特定年、月、日的物件 :class:`datetime.date`。" + +#: ../../c-api/datetime.rst:176 +msgid "" +"Return a :class:`datetime.datetime` object with the specified year, month, " +"day, hour, minute, second and microsecond." +msgstr "" +"回傳一個有特定年、月、日、時、分、秒、微秒的物件 :class:`datetime.datetime`。" + +#: ../../c-api/datetime.rst:182 +msgid "" +"Return a :class:`datetime.datetime` object with the specified year, month, " +"day, hour, minute, second, microsecond and fold." +msgstr "" +"回傳一個有特定年、月、日、時、分、秒、微秒與 fold（時間折疊）的物件 :class:" +"`datetime.datetime`。" + +#: ../../c-api/datetime.rst:190 +msgid "" +"Return a :class:`datetime.time` object with the specified hour, minute, " +"second and microsecond." +msgstr "回傳一個有特定時、分、秒、微秒的物件 :class:`datetime.time`。" + +#: ../../c-api/datetime.rst:196 +msgid "" +"Return a :class:`datetime.time` object with the specified hour, minute, " +"second, microsecond and fold." +msgstr "" +"回傳一個有特定時、分、秒、微秒與 fold（時間折疊）的物件 :class:`datetime." +"time`。" + +#: ../../c-api/datetime.rst:204 +msgid "" +"Return a :class:`datetime.timedelta` object representing the given number of " +"days, seconds and microseconds. Normalization is performed so that the " +"resulting number of microseconds and seconds lie in the ranges documented " +"for :class:`datetime.timedelta` objects." +msgstr "" +"回傳一個 :class:`datetime.timedelta` 物件，表示給定的天數、秒數和微秒數。執行" +"標準化 (normalization) 以便生成的微秒數和秒數位於 :class:`datetime." +"timedelta` 物件記錄的範圍內。" + +#: ../../c-api/datetime.rst:212 +msgid "" +"Return a :class:`datetime.timezone` object with an unnamed fixed offset " +"represented by the *offset* argument." +msgstr "" +"回傳一個 :class:`datetime.timezone` 物件，其未命名的固定偏移量由 *offset* 引" +"數表示。" + +#: ../../c-api/datetime.rst:220 +msgid "" +"Return a :class:`datetime.timezone` object with a fixed offset represented " +"by the *offset* argument and with tzname *name*." +msgstr "" +"回傳一個 :class:`datetime.timezone` 物件，其固定偏移量由 *offset* 引數表示，" +"並帶有 tzname *name*。" + +#: ../../c-api/datetime.rst:226 +msgid "" +"Macros to extract fields from date objects. The argument must be an " +"instance of :c:type:`PyDateTime_Date`, including subclasses (such as :c:type:" +"`PyDateTime_DateTime`). The argument must not be ``NULL``, and the type is " +"not checked:" +msgstr "" +"從 date 物件中提取欄位的巨集。引數必須是個 :c:type:`PyDateTime_Date` 的實例，" +"包括子類別（例如 :c:type:`PyDateTime_DateTime`）。引數不得為 ``NULL``，並且不" +"會檢查型別：" + +#: ../../c-api/datetime.rst:233 +msgid "Return the year, as a positive int." +msgstr "回傳年份，為正整數。" + +#: ../../c-api/datetime.rst:238 +msgid "Return the month, as an int from 1 through 12." +msgstr "回傳月份，為正整數，從 1 到 12。" + +#: ../../c-api/datetime.rst:243 +msgid "Return the day, as an int from 1 through 31." +msgstr "回傳日期，為正整數，從 1 到 31。" + +#: ../../c-api/datetime.rst:246 +msgid "" +"Macros to extract fields from datetime objects. The argument must be an " +"instance of :c:type:`PyDateTime_DateTime`, including subclasses. The " +"argument must not be ``NULL``, and the type is not checked:" +msgstr "" +"從 datetime 物件中提取欄位的巨集。引數必須是個 :c:type:`PyDateTime_DateTime` " +"的實例，包括子類別。引數不得為 ``NULL``，並且不會檢查型別：" + +#: ../../c-api/datetime.rst:252 ../../c-api/datetime.rst:290 +msgid "Return the hour, as an int from 0 through 23." +msgstr "回傳小時，為正整數，從 0 到 23。" + +#: ../../c-api/datetime.rst:257 ../../c-api/datetime.rst:295 +msgid "Return the minute, as an int from 0 through 59." +msgstr "回傳分鐘，為正整數，從 0 到 59。" + +#: ../../c-api/datetime.rst:262 ../../c-api/datetime.rst:300 +msgid "Return the second, as an int from 0 through 59." +msgstr "回傳秒，為正整數，從0 到59。" + +#: ../../c-api/datetime.rst:267 ../../c-api/datetime.rst:305 +msgid "Return the microsecond, as an int from 0 through 999999." +msgstr "回傳微秒，為正整數，從 0 到 999999。" + +#: ../../c-api/datetime.rst:272 ../../c-api/datetime.rst:310 +msgid "Return the fold, as an int from 0 through 1." +msgstr "回傳 fold，為 0 或 1 的正整數。" + +#: ../../c-api/datetime.rst:279 ../../c-api/datetime.rst:317 +msgid "Return the tzinfo (which may be ``None``)." +msgstr "回傳 tzinfo（可能是 ``None``）。" + +#: ../../c-api/datetime.rst:284 +msgid "" +"Macros to extract fields from time objects. The argument must be an " +"instance of :c:type:`PyDateTime_Time`, including subclasses. The argument " +"must not be ``NULL``, and the type is not checked:" +msgstr "" +"從 time 物件中提取欄位的巨集。引數必須是個 :c:type:`PyDateTime_Time` 的實例，" +"包括子類別。引數不得為 ``NULL``，並且不會檢查型別：" + +#: ../../c-api/datetime.rst:322 +msgid "" +"Macros to extract fields from time delta objects. The argument must be an " +"instance of :c:type:`PyDateTime_Delta`, including subclasses. The argument " +"must not be ``NULL``, and the type is not checked:" +msgstr "" +"從 time delta 物件中提取欄位的巨集。引數必須是個 :c:type:`PyDateTime_Delta` " +"的實例，包括子類別。引數不能為 ``NULL``，並且不會檢查型別：" + +#: ../../c-api/datetime.rst:328 +msgid "Return the number of days, as an int from -999999999 to 999999999." +msgstr "以 -999999999 到 999999999 之間的整數形式回傳天數。" + +#: ../../c-api/datetime.rst:335 +msgid "Return the number of seconds, as an int from 0 through 86399." +msgstr "以 0 到 86399 之間的整數形式回傳秒數。" + +#: ../../c-api/datetime.rst:342 +msgid "Return the number of microseconds, as an int from 0 through 999999." +msgstr "以 0 到 999999 之間的整數形式回傳微秒數。" + +#: ../../c-api/datetime.rst:347 +msgid "Macros for the convenience of modules implementing the DB API:" +msgstr "為了方便模組實作 DB API 的巨集：" + +#: ../../c-api/datetime.rst:351 +msgid "" +"Create and return a new :class:`datetime.datetime` object given an argument " +"tuple suitable for passing to :meth:`datetime.datetime.fromtimestamp`." +msgstr "" +"給定一個適合傳遞給 :meth:`datetime.datetime.fromtimestamp` 的引數元組，建立並" +"回傳一個新的 :class:`datetime.datetime` 物件。" + +#: ../../c-api/datetime.rst:357 +msgid "" +"Create and return a new :class:`datetime.date` object given an argument " +"tuple suitable for passing to :meth:`datetime.date.fromtimestamp`." +msgstr "" +"給定一個適合傳遞給 :meth:`datetime.date.fromtimestamp` 的引數元組，建立並回傳" +"一個新的 :class:`datetime.date` 物件。" + +#: ../../c-api/datetime.rst:362 +msgid "Internal data" +msgstr "內部資料" + +#: ../../c-api/datetime.rst:364 +msgid "" +"The following symbols are exposed by the C API but should be considered " +"internal-only." +msgstr "以下符號由 C API 公開，但應視為僅供內部使用。" + +#: ../../c-api/datetime.rst:369 +msgid "Name of the datetime capsule to pass to :c:func:`PyCapsule_Import`." +msgstr "傳遞給 :c:func:`PyCapsule_Import` 的 datetime capsule 名稱。" + +#: ../../c-api/datetime.rst:371 +msgid "Internal usage only. Use :c:macro:`PyDateTime_IMPORT` instead." +msgstr "僅供內部使用。請改用 :c:macro:`PyDateTime_IMPORT`。" diff --git a/c-api/descriptor.po b/c-api/descriptor.po index 0613dc5d61..f06e6b0ee9 100644 --- a/c-api/descriptor.po +++ b/c-api/descriptor.po @@ -1,135 +1,135 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Leon H., 2017 -# Matt Wang , 2021 -# -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-12-02 00:15+0000\n" -"PO-Revision-Date: 2021-12-09 20:56+0800\n" -"Last-Translator: Matt Wang \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" -"X-Generator: Poedit 3.0\n" - -#: ../../c-api/descriptor.rst:6 -msgid "Descriptor Objects" -msgstr "Descriptor（描述器）物件" - -#: ../../c-api/descriptor.rst:8 -msgid "" -"\"Descriptors\" are objects that describe some attribute of an object. They " -"are found in the dictionary of type objects." -msgstr "" -"\"Descriptor\" 是描述物件某些屬性的物件，它們存在於型別物件的 dictionary（字" -"典）中。" - -#: ../../c-api/descriptor.rst:15 -msgid "The type object for the built-in descriptor types." -msgstr "內建 descriptor 型別的型別物件。" - -#: ../../c-api/descriptor.rst:26 -msgid "" -"The type object for member descriptor objects created from :c:type:" -"`PyMemberDef` structures. These descriptors expose fields of a C struct as " -"attributes on a type, and correspond to :class:`types.MemberDescriptorType` " -"objects in Python." -msgstr "" - -#: ../../c-api/descriptor.rst:35 -msgid "" -"The type object for get/set descriptor objects created from :c:type:" -"`PyGetSetDef` structures. These descriptors implement attributes whose value " -"is computed by C getter and setter functions, and are used for many built-in " -"type attributes." -msgstr "" - -#: ../../c-api/descriptor.rst:46 -msgid "" -"The type object for method descriptor objects created from :c:type:" -"`PyMethodDef` structures. These descriptors expose C functions as methods on " -"a type, and correspond to :class:`types.MemberDescriptorType` objects in " -"Python." -msgstr "" - -#: ../../c-api/descriptor.rst:57 -msgid "" -"The type object for wrapper descriptor objects created by :c:func:" -"`PyDescr_NewWrapper` and :c:func:`PyWrapper_New`. Wrapper descriptors are " -"used internally to expose special methods implemented via wrapper " -"structures, and appear in Python as :class:`types.WrapperDescriptorType` " -"objects." -msgstr "" - -#: ../../c-api/descriptor.rst:69 -msgid "" -"Return non-zero if the descriptor object *descr* describes a data attribute, " -"or ``0`` if it describes a method. *descr* must be a descriptor object; " -"there is no error checking." -msgstr "" -"如果 descriptor 物件 *descr* 描述的是一個資料屬性則回傳非零值，或者如果它描述" -"的是一個方法則回傳 ``0``。*descr* 必須為一個 descriptor 物件；沒有錯誤檢查。" - -#: ../../c-api/descriptor.rst:78 -msgid "Built-in descriptors" -msgstr "內建描述器" - -#: ../../c-api/descriptor.rst:82 -msgid "" -"The type object for super objects. This is the same object as :class:`super` " -"in the Python layer." -msgstr "" - -#: ../../c-api/descriptor.rst:88 -msgid "" -"The type of class method objects. This is the same object as :class:" -"`classmethod` in the Python layer." -msgstr "" - -#: ../../c-api/descriptor.rst:94 -msgid "" -"The type object for C-level class method descriptor objects. This is the " -"type of the descriptors created for :func:`classmethod` defined in C " -"extension types, and is the same object as :class:`classmethod` in Python." -msgstr "" - -#: ../../c-api/descriptor.rst:102 -msgid "" -"Create a new :class:`classmethod` object wrapping *callable*. *callable* " -"must be a callable object and must not be ``NULL``." -msgstr "" - -#: ../../c-api/descriptor.rst:105 -msgid "" -"On success, this function returns a :term:`strong reference` to a new class " -"method descriptor. On failure, this function returns ``NULL`` with an " -"exception set." -msgstr "" - -#: ../../c-api/descriptor.rst:112 -msgid "" -"The type of static method objects. This is the same object as :class:" -"`staticmethod` in the Python layer." -msgstr "" - -#: ../../c-api/descriptor.rst:118 -msgid "" -"Create a new :class:`staticmethod` object wrapping *callable*. *callable* " -"must be a callable object and must not be ``NULL``." -msgstr "" - -#: ../../c-api/descriptor.rst:121 -msgid "" -"On success, this function returns a :term:`strong reference` to a new static " -"method descriptor. On failure, this function returns ``NULL`` with an " -"exception set." -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Leon H., 2017 +# Matt Wang , 2021 +# +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-12-02 00:15+0000\n" +"PO-Revision-Date: 2021-12-09 20:56+0800\n" +"Last-Translator: Matt Wang \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" +"X-Generator: Poedit 3.0\n" + +#: ../../c-api/descriptor.rst:6 +msgid "Descriptor Objects" +msgstr "Descriptor（描述器）物件" + +#: ../../c-api/descriptor.rst:8 +msgid "" +"\"Descriptors\" are objects that describe some attribute of an object. They " +"are found in the dictionary of type objects." +msgstr "" +"\"Descriptor\" 是描述物件某些屬性的物件，它們存在於型別物件的 dictionary（字" +"典）中。" + +#: ../../c-api/descriptor.rst:15 +msgid "The type object for the built-in descriptor types." +msgstr "內建 descriptor 型別的型別物件。" + +#: ../../c-api/descriptor.rst:26 +msgid "" +"The type object for member descriptor objects created from :c:type:" +"`PyMemberDef` structures. These descriptors expose fields of a C struct as " +"attributes on a type, and correspond to :class:`types.MemberDescriptorType` " +"objects in Python." +msgstr "" + +#: ../../c-api/descriptor.rst:35 +msgid "" +"The type object for get/set descriptor objects created from :c:type:" +"`PyGetSetDef` structures. These descriptors implement attributes whose value " +"is computed by C getter and setter functions, and are used for many built-in " +"type attributes." +msgstr "" + +#: ../../c-api/descriptor.rst:46 +msgid "" +"The type object for method descriptor objects created from :c:type:" +"`PyMethodDef` structures. These descriptors expose C functions as methods on " +"a type, and correspond to :class:`types.MemberDescriptorType` objects in " +"Python." +msgstr "" + +#: ../../c-api/descriptor.rst:57 +msgid "" +"The type object for wrapper descriptor objects created by :c:func:" +"`PyDescr_NewWrapper` and :c:func:`PyWrapper_New`. Wrapper descriptors are " +"used internally to expose special methods implemented via wrapper " +"structures, and appear in Python as :class:`types.WrapperDescriptorType` " +"objects." +msgstr "" + +#: ../../c-api/descriptor.rst:69 +msgid "" +"Return non-zero if the descriptor object *descr* describes a data attribute, " +"or ``0`` if it describes a method. *descr* must be a descriptor object; " +"there is no error checking." +msgstr "" +"如果 descriptor 物件 *descr* 描述的是一個資料屬性則回傳非零值，或者如果它描述" +"的是一個方法則回傳 ``0``。*descr* 必須為一個 descriptor 物件；沒有錯誤檢查。" + +#: ../../c-api/descriptor.rst:78 +msgid "Built-in descriptors" +msgstr "內建描述器" + +#: ../../c-api/descriptor.rst:82 +msgid "" +"The type object for super objects. This is the same object as :class:`super` " +"in the Python layer." +msgstr "" + +#: ../../c-api/descriptor.rst:88 +msgid "" +"The type of class method objects. This is the same object as :class:" +"`classmethod` in the Python layer." +msgstr "" + +#: ../../c-api/descriptor.rst:94 +msgid "" +"The type object for C-level class method descriptor objects. This is the " +"type of the descriptors created for :func:`classmethod` defined in C " +"extension types, and is the same object as :class:`classmethod` in Python." +msgstr "" + +#: ../../c-api/descriptor.rst:102 +msgid "" +"Create a new :class:`classmethod` object wrapping *callable*. *callable* " +"must be a callable object and must not be ``NULL``." +msgstr "" + +#: ../../c-api/descriptor.rst:105 +msgid "" +"On success, this function returns a :term:`strong reference` to a new class " +"method descriptor. On failure, this function returns ``NULL`` with an " +"exception set." +msgstr "" + +#: ../../c-api/descriptor.rst:112 +msgid "" +"The type of static method objects. This is the same object as :class:" +"`staticmethod` in the Python layer." +msgstr "" + +#: ../../c-api/descriptor.rst:118 +msgid "" +"Create a new :class:`staticmethod` object wrapping *callable*. *callable* " +"must be a callable object and must not be ``NULL``." +msgstr "" + +#: ../../c-api/descriptor.rst:121 +msgid "" +"On success, this function returns a :term:`strong reference` to a new static " +"method descriptor. On failure, this function returns ``NULL`` with an " +"exception set." +msgstr "" diff --git a/c-api/dict.po b/c-api/dict.po index e23ff15187..699e44f59d 100644 --- a/c-api/dict.po +++ b/c-api/dict.po @@ -1,713 +1,713 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# aminzai , 2015 -# Liang-Bo Wang , 2015 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-12-02 00:15+0000\n" -"PO-Revision-Date: 2017-09-22 18:26+0000\n" -"Last-Translator: Liang-Bo Wang \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" - -#: ../../c-api/dict.rst:6 -msgid "Dictionary Objects" -msgstr "字典物件" - -#: ../../c-api/dict.rst:13 -msgid "" -"This subtype of :c:type:`PyObject` represents a Python dictionary object." -msgstr ":c:type:`PyObject` 子型別代表一個 Python 字典物件。" - -#: ../../c-api/dict.rst:18 -msgid "" -"This instance of :c:type:`PyTypeObject` represents the Python dictionary " -"type. This is the same object as :class:`dict` in the Python layer." -msgstr "" -":c:type:`PyTypeObject` 實例代表一個 Python 字典型別。此與 Python 層中的 :" -"class:`dict` 為同一個物件。" - -#: ../../c-api/dict.rst:24 -msgid "" -"Return true if *p* is a dict object or an instance of a subtype of the dict " -"type. This function always succeeds." -msgstr "" -"若 *p* 是一個字典物件或字典的子型別實例則會回傳 true。此函式每次都會執行成" -"功。" - -#: ../../c-api/dict.rst:30 -msgid "" -"Return true if *p* is a dict object, but not an instance of a subtype of the " -"dict type. This function always succeeds." -msgstr "" -"若 *p* 是一個字典物件但並不是一個字典子型別的實例，則回傳 true。此函式每次都" -"會執行成功。" - -#: ../../c-api/dict.rst:36 -msgid "Return a new empty dictionary, or ``NULL`` on failure." -msgstr "回傳一個新的空字典，或在失敗時回傳 ``NULL``。" - -#: ../../c-api/dict.rst:41 -msgid "" -"Return a :class:`types.MappingProxyType` object for a mapping which enforces " -"read-only behavior. This is normally used to create a view to prevent " -"modification of the dictionary for non-dynamic class types." -msgstr "" - -#: ../../c-api/dict.rst:48 -msgid "" -"The type object for mapping proxy objects created by :c:func:" -"`PyDictProxy_New` and for the read-only ``__dict__`` attribute of many built-" -"in types. A :c:type:`PyDictProxy_Type` instance provides a dynamic, read-" -"only view of an underlying dictionary: changes to the underlying dictionary " -"are reflected in the proxy, but the proxy itself does not support mutation " -"operations. This corresponds to :class:`types.MappingProxyType` in Python." -msgstr "" - -#: ../../c-api/dict.rst:59 -msgid "Empty an existing dictionary of all key-value pairs." -msgstr "清空現有字典中的所有鍵值對。" - -#: ../../c-api/dict.rst:64 -msgid "" -"Determine if dictionary *p* contains *key*. If an item in *p* matches " -"*key*, return ``1``, otherwise return ``0``. On error, return ``-1``. This " -"is equivalent to the Python expression ``key in p``." -msgstr "" - -#: ../../c-api/dict.rst:71 -msgid "" -"This is the same as :c:func:`PyDict_Contains`, but *key* is specified as a :" -"c:expr:`const char*` UTF-8 encoded bytes string, rather than a :c:expr:" -"`PyObject*`." -msgstr "" - -#: ../../c-api/dict.rst:80 -msgid "Return a new dictionary that contains the same key-value pairs as *p*." -msgstr "回傳一個新的字典，包含與 *p* 相同的鍵值對。" - -#: ../../c-api/dict.rst:85 -msgid "" -"Insert *val* into the dictionary *p* with a key of *key*. *key* must be :" -"term:`hashable`; if it isn't, :exc:`TypeError` will be raised. Return ``0`` " -"on success or ``-1`` on failure. This function *does not* steal a reference " -"to *val*." -msgstr "" - -#: ../../c-api/dict.rst:93 -msgid "" -"This is the same as :c:func:`PyDict_SetItem`, but *key* is specified as a :c:" -"expr:`const char*` UTF-8 encoded bytes string, rather than a :c:expr:" -"`PyObject*`." -msgstr "" - -#: ../../c-api/dict.rst:100 -msgid "" -"Remove the entry in dictionary *p* with key *key*. *key* must be :term:" -"`hashable`; if it isn't, :exc:`TypeError` is raised. If *key* is not in the " -"dictionary, :exc:`KeyError` is raised. Return ``0`` on success or ``-1`` on " -"failure." -msgstr "" - -#: ../../c-api/dict.rst:108 -msgid "" -"This is the same as :c:func:`PyDict_DelItem`, but *key* is specified as a :c:" -"expr:`const char*` UTF-8 encoded bytes string, rather than a :c:expr:" -"`PyObject*`." -msgstr "" - -#: ../../c-api/dict.rst:115 -msgid "" -"Return a new :term:`strong reference` to the object from dictionary *p* " -"which has a key *key*:" -msgstr "" - -#: ../../c-api/dict.rst:118 -msgid "" -"If the key is present, set *\\*result* to a new :term:`strong reference` to " -"the value and return ``1``." -msgstr "" - -#: ../../c-api/dict.rst:120 -msgid "If the key is missing, set *\\*result* to ``NULL`` and return ``0``." -msgstr "如果鍵不存在，將 *\\*result* 設為 ``NULL`` 並回傳 ``0``。" - -#: ../../c-api/dict.rst:121 ../../c-api/dict.rst:218 -msgid "On error, raise an exception and return ``-1``." -msgstr "錯誤發生時，引發一個例外並回傳 ``-1``。" - -#: ../../c-api/dict.rst:125 -msgid "See also the :c:func:`PyObject_GetItem` function." -msgstr "另見 :c:func:`PyObject_GetItem` 函式。" - -#: ../../c-api/dict.rst:130 -msgid "" -"Return a :term:`borrowed reference` to the object from dictionary *p* which " -"has a key *key*. Return ``NULL`` if the key *key* is missing *without* " -"setting an exception." -msgstr "" - -#: ../../c-api/dict.rst:136 -msgid "" -"Exceptions that occur while this calls :meth:`~object.__hash__` and :meth:" -"`~object.__eq__` methods are silently ignored. Prefer the :c:func:" -"`PyDict_GetItemWithError` function instead." -msgstr "" - -#: ../../c-api/dict.rst:140 -msgid "" -"Calling this API without an :term:`attached thread state` had been allowed " -"for historical reason. It is no longer allowed." -msgstr "" - -#: ../../c-api/dict.rst:147 -msgid "" -"Variant of :c:func:`PyDict_GetItem` that does not suppress exceptions. " -"Return ``NULL`` **with** an exception set if an exception occurred. Return " -"``NULL`` **without** an exception set if the key wasn't present." -msgstr "" - -#: ../../c-api/dict.rst:155 -msgid "" -"This is the same as :c:func:`PyDict_GetItem`, but *key* is specified as a :c:" -"expr:`const char*` UTF-8 encoded bytes string, rather than a :c:expr:" -"`PyObject*`." -msgstr "" - -#: ../../c-api/dict.rst:161 -msgid "" -"Exceptions that occur while this calls :meth:`~object.__hash__` and :meth:" -"`~object.__eq__` methods or while creating the temporary :class:`str` object " -"are silently ignored. Prefer using the :c:func:`PyDict_GetItemWithError` " -"function with your own :c:func:`PyUnicode_FromString` *key* instead." -msgstr "" - -#: ../../c-api/dict.rst:170 -msgid "" -"Similar to :c:func:`PyDict_GetItemRef`, but *key* is specified as a :c:expr:" -"`const char*` UTF-8 encoded bytes string, rather than a :c:expr:`PyObject*`." -msgstr "" - -#: ../../c-api/dict.rst:179 -msgid "" -"This is the same as the Python-level :meth:`dict.setdefault`. If present, " -"it returns the value corresponding to *key* from the dictionary *p*. If the " -"key is not in the dict, it is inserted with value *defaultobj* and " -"*defaultobj* is returned. This function evaluates the hash function of " -"*key* only once, instead of evaluating it independently for the lookup and " -"the insertion." -msgstr "" - -#: ../../c-api/dict.rst:190 -msgid "" -"Inserts *default_value* into the dictionary *p* with a key of *key* if the " -"key is not already present in the dictionary. If *result* is not ``NULL``, " -"then *\\*result* is set to a :term:`strong reference` to either " -"*default_value*, if the key was not present, or the existing value, if *key* " -"was already present in the dictionary. Returns ``1`` if the key was present " -"and *default_value* was not inserted, or ``0`` if the key was not present " -"and *default_value* was inserted. On failure, returns ``-1``, sets an " -"exception, and sets ``*result`` to ``NULL``." -msgstr "" - -#: ../../c-api/dict.rst:200 -msgid "" -"For clarity: if you have a strong reference to *default_value* before " -"calling this function, then after it returns, you hold a strong reference to " -"both *default_value* and *\\*result* (if it's not ``NULL``). These may refer " -"to the same object: in that case you hold two separate references to it." -msgstr "" - -#: ../../c-api/dict.rst:211 -msgid "" -"Remove *key* from dictionary *p* and optionally return the removed value. Do " -"not raise :exc:`KeyError` if the key is missing." -msgstr "" - -#: ../../c-api/dict.rst:214 -msgid "" -"If the key is present, set *\\*result* to a new reference to the removed " -"value if *result* is not ``NULL``, and return ``1``." -msgstr "" - -#: ../../c-api/dict.rst:216 -msgid "" -"If the key is missing, set *\\*result* to ``NULL`` if *result* is not " -"``NULL``, and return ``0``." -msgstr "" - -#: ../../c-api/dict.rst:220 -msgid "" -"Similar to :meth:`dict.pop`, but without the default value and not raising :" -"exc:`KeyError` if the key is missing." -msgstr "" - -#: ../../c-api/dict.rst:228 -msgid "" -"Similar to :c:func:`PyDict_Pop`, but *key* is specified as a :c:expr:`const " -"char*` UTF-8 encoded bytes string, rather than a :c:expr:`PyObject*`." -msgstr "" - -#: ../../c-api/dict.rst:237 -msgid "" -"Return a :c:type:`PyListObject` containing all the items from the dictionary." -msgstr "回傳一個包含字典中所有項目的 :c:type:`PyListObject`。" - -#: ../../c-api/dict.rst:242 -msgid "" -"Return a :c:type:`PyListObject` containing all the keys from the dictionary." -msgstr "回傳一個包含字典中所有鍵的 :c:type:`PyListObject`。" - -#: ../../c-api/dict.rst:247 -msgid "" -"Return a :c:type:`PyListObject` containing all the values from the " -"dictionary *p*." -msgstr "回傳一個包含字典 *p* 中所有值的 :c:type:`PyListObject`。" - -#: ../../c-api/dict.rst:255 -msgid "" -"Return the number of items in the dictionary. This is equivalent to " -"``len(p)`` on a dictionary." -msgstr "回傳字典中項目的數量。此與於字典呼叫 ``len(p)`` 等效。" - -#: ../../c-api/dict.rst:261 -msgid "Similar to :c:func:`PyDict_Size`, but without error checking." -msgstr "和 :c:func:`PyDict_Size` 類似，但沒有錯誤檢查。" - -#: ../../c-api/dict.rst:266 -msgid "" -"Iterate over all key-value pairs in the dictionary *p*. The :c:type:" -"`Py_ssize_t` referred to by *ppos* must be initialized to ``0`` prior to the " -"first call to this function to start the iteration; the function returns " -"true for each pair in the dictionary, and false once all pairs have been " -"reported. The parameters *pkey* and *pvalue* should either point to :c:expr:" -"`PyObject*` variables that will be filled in with each key and value, " -"respectively, or may be ``NULL``. Any references returned through them are " -"borrowed. *ppos* should not be altered during iteration. Its value " -"represents offsets within the internal dictionary structure, and since the " -"structure is sparse, the offsets are not consecutive." -msgstr "" - -#: ../../c-api/dict.rst:277 -msgid "For example::" -msgstr "舉例來說： ::" - -#: ../../c-api/dict.rst:279 -msgid "" -"PyObject *key, *value;\n" -"Py_ssize_t pos = 0;\n" -"\n" -"while (PyDict_Next(self->dict, &pos, &key, &value)) {\n" -" /* do something interesting with the values... */\n" -" ...\n" -"}" -msgstr "" -"PyObject *key, *value;\n" -"Py_ssize_t pos = 0;\n" -"\n" -"while (PyDict_Next(self->dict, &pos, &key, &value)) {\n" -" /* 用值做一些有趣的事情... */\n" -" ...\n" -"}" - -#: ../../c-api/dict.rst:287 -msgid "" -"The dictionary *p* should not be mutated during iteration. It is safe to " -"modify the values of the keys as you iterate over the dictionary, but only " -"so long as the set of keys does not change. For example::" -msgstr "" - -#: ../../c-api/dict.rst:291 -msgid "" -"PyObject *key, *value;\n" -"Py_ssize_t pos = 0;\n" -"\n" -"while (PyDict_Next(self->dict, &pos, &key, &value)) {\n" -" long i = PyLong_AsLong(value);\n" -" if (i == -1 && PyErr_Occurred()) {\n" -" return -1;\n" -" }\n" -" PyObject *o = PyLong_FromLong(i + 1);\n" -" if (o == NULL)\n" -" return -1;\n" -" if (PyDict_SetItem(self->dict, key, o) < 0) {\n" -" Py_DECREF(o);\n" -" return -1;\n" -" }\n" -" Py_DECREF(o);\n" -"}" -msgstr "" -"PyObject *key, *value;\n" -"Py_ssize_t pos = 0;\n" -"\n" -"while (PyDict_Next(self->dict, &pos, &key, &value)) {\n" -" long i = PyLong_AsLong(value);\n" -" if (i == -1 && PyErr_Occurred()) {\n" -" return -1;\n" -" }\n" -" PyObject *o = PyLong_FromLong(i + 1);\n" -" if (o == NULL)\n" -" return -1;\n" -" if (PyDict_SetItem(self->dict, key, o) < 0) {\n" -" Py_DECREF(o);\n" -" return -1;\n" -" }\n" -" Py_DECREF(o);\n" -"}" - -#: ../../c-api/dict.rst:309 -msgid "" -"The function is not thread-safe in the :term:`free-threaded ` build without external synchronization. You can use :c:macro:" -"`Py_BEGIN_CRITICAL_SECTION` to lock the dictionary while iterating over it::" -msgstr "" - -#: ../../c-api/dict.rst:314 -msgid "" -"Py_BEGIN_CRITICAL_SECTION(self->dict);\n" -"while (PyDict_Next(self->dict, &pos, &key, &value)) {\n" -" ...\n" -"}\n" -"Py_END_CRITICAL_SECTION();" -msgstr "" -"Py_BEGIN_CRITICAL_SECTION(self->dict);\n" -"while (PyDict_Next(self->dict, &pos, &key, &value)) {\n" -" ...\n" -"}\n" -"Py_END_CRITICAL_SECTION();" - -#: ../../c-api/dict.rst:322 -msgid "" -"On the free-threaded build, this function can be used safely inside a " -"critical section. However, the references returned for *pkey* and *pvalue* " -"are :term:`borrowed ` and are only valid while the " -"critical section is held. If you need to use these objects outside the " -"critical section or when the critical section can be suspended, create a :" -"term:`strong reference ` (for example, using :c:func:" -"`Py_NewRef`)." -msgstr "" - -#: ../../c-api/dict.rst:332 -msgid "" -"Iterate over mapping object *b* adding key-value pairs to dictionary *a*. " -"*b* may be a dictionary, or any object supporting :c:func:`PyMapping_Keys` " -"and :c:func:`PyObject_GetItem`. If *override* is true, existing pairs in *a* " -"will be replaced if a matching key is found in *b*, otherwise pairs will " -"only be added if there is not a matching key in *a*. Return ``0`` on success " -"or ``-1`` if an exception was raised." -msgstr "" - -#: ../../c-api/dict.rst:342 -msgid "" -"This is the same as ``PyDict_Merge(a, b, 1)`` in C, and is similar to ``a." -"update(b)`` in Python except that :c:func:`PyDict_Update` doesn't fall back " -"to the iterating over a sequence of key value pairs if the second argument " -"has no \"keys\" attribute. Return ``0`` on success or ``-1`` if an " -"exception was raised." -msgstr "" - -#: ../../c-api/dict.rst:351 -msgid "" -"Update or merge into dictionary *a*, from the key-value pairs in *seq2*. " -"*seq2* must be an iterable object producing iterable objects of length 2, " -"viewed as key-value pairs. In case of duplicate keys, the last wins if " -"*override* is true, else the first wins. Return ``0`` on success or ``-1`` " -"if an exception was raised. Equivalent Python (except for the return value)::" -msgstr "" - -#: ../../c-api/dict.rst:358 -msgid "" -"def PyDict_MergeFromSeq2(a, seq2, override):\n" -" for key, value in seq2:\n" -" if override or key not in a:\n" -" a[key] = value" -msgstr "" -"def PyDict_MergeFromSeq2(a, seq2, override):\n" -" for key, value in seq2:\n" -" if override or key not in a:\n" -" a[key] = value" - -#: ../../c-api/dict.rst:365 -msgid "" -"Register *callback* as a dictionary watcher. Return a non-negative integer " -"id which must be passed to future calls to :c:func:`PyDict_Watch`. In case " -"of error (e.g. no more watcher IDs available), return ``-1`` and set an " -"exception." -msgstr "" - -#: ../../c-api/dict.rst:374 -msgid "" -"Clear watcher identified by *watcher_id* previously returned from :c:func:" -"`PyDict_AddWatcher`. Return ``0`` on success, ``-1`` on error (e.g. if the " -"given *watcher_id* was never registered.)" -msgstr "" - -#: ../../c-api/dict.rst:382 -msgid "" -"Mark dictionary *dict* as watched. The callback granted *watcher_id* by :c:" -"func:`PyDict_AddWatcher` will be called when *dict* is modified or " -"deallocated. Return ``0`` on success or ``-1`` on error." -msgstr "" - -#: ../../c-api/dict.rst:390 -msgid "" -"Mark dictionary *dict* as no longer watched. The callback granted " -"*watcher_id* by :c:func:`PyDict_AddWatcher` will no longer be called when " -"*dict* is modified or deallocated. The dict must previously have been " -"watched by this watcher. Return ``0`` on success or ``-1`` on error." -msgstr "" - -#: ../../c-api/dict.rst:399 -msgid "" -"Enumeration of possible dictionary watcher events: ``PyDict_EVENT_ADDED``, " -"``PyDict_EVENT_MODIFIED``, ``PyDict_EVENT_DELETED``, " -"``PyDict_EVENT_CLONED``, ``PyDict_EVENT_CLEARED``, or " -"``PyDict_EVENT_DEALLOCATED``." -msgstr "" - -#: ../../c-api/dict.rst:407 -msgid "Type of a dict watcher callback function." -msgstr "" - -#: ../../c-api/dict.rst:409 -msgid "" -"If *event* is ``PyDict_EVENT_CLEARED`` or ``PyDict_EVENT_DEALLOCATED``, both " -"*key* and *new_value* will be ``NULL``. If *event* is ``PyDict_EVENT_ADDED`` " -"or ``PyDict_EVENT_MODIFIED``, *new_value* will be the new value for *key*. " -"If *event* is ``PyDict_EVENT_DELETED``, *key* is being deleted from the " -"dictionary and *new_value* will be ``NULL``." -msgstr "" - -#: ../../c-api/dict.rst:415 -msgid "" -"``PyDict_EVENT_CLONED`` occurs when *dict* was previously empty and another " -"dict is merged into it. To maintain efficiency of this operation, per-key " -"``PyDict_EVENT_ADDED`` events are not issued in this case; instead a single " -"``PyDict_EVENT_CLONED`` is issued, and *key* will be the source dictionary." -msgstr "" - -#: ../../c-api/dict.rst:421 -msgid "" -"The callback may inspect but must not modify *dict*; doing so could have " -"unpredictable effects, including infinite recursion. Do not trigger Python " -"code execution in the callback, as it could modify the dict as a side effect." -msgstr "" - -#: ../../c-api/dict.rst:425 -msgid "" -"If *event* is ``PyDict_EVENT_DEALLOCATED``, taking a new reference in the " -"callback to the about-to-be-destroyed dictionary will resurrect it and " -"prevent it from being freed at this time. When the resurrected object is " -"destroyed later, any watcher callbacks active at that time will be called " -"again." -msgstr "" - -#: ../../c-api/dict.rst:431 -msgid "" -"Callbacks occur before the notified modification to *dict* takes place, so " -"the prior state of *dict* can be inspected." -msgstr "" - -#: ../../c-api/dict.rst:434 -msgid "" -"If the callback sets an exception, it must return ``-1``; this exception " -"will be printed as an unraisable exception using :c:func:" -"`PyErr_WriteUnraisable`. Otherwise it should return ``0``." -msgstr "" - -#: ../../c-api/dict.rst:438 -msgid "" -"There may already be a pending exception set on entry to the callback. In " -"this case, the callback should return ``0`` with the same exception still " -"set. This means the callback may not call any other API that can set an " -"exception unless it saves and clears the exception state first, and restores " -"it before returning." -msgstr "" - -#: ../../c-api/dict.rst:448 -msgid "Dictionary View Objects" -msgstr "字典視圖物件" - -#: ../../c-api/dict.rst:452 -msgid "" -"Return true if *op* is a view of a set inside a dictionary. This is " -"currently equivalent to :c:expr:`PyDictKeys_Check(op) || " -"PyDictItems_Check(op)`. This function always succeeds." -msgstr "" -"若 *op* 是一個字典中集合的視圖則會回傳 true。這目前等同於 :c:expr:" -"`PyDictKeys_Check(op) || PyDictItems_Check(op)`。此函式每次都會執行成功。" - -#: ../../c-api/dict.rst:459 -msgid "" -"Type object for a view of dictionary keys. In Python, this is the type of " -"the object returned by :meth:`dict.keys`." -msgstr "" - -#: ../../c-api/dict.rst:465 -msgid "" -"Return true if *op* is an instance of a dictionary keys view. This function " -"always succeeds." -msgstr "若 *op* 是一個字典鍵視圖的實例則會回傳 true。此函式每次都會執行成功。" - -#: ../../c-api/dict.rst:471 -msgid "" -"Type object for a view of dictionary values. In Python, this is the type of " -"the object returned by :meth:`dict.values`." -msgstr "" - -#: ../../c-api/dict.rst:477 -msgid "" -"Return true if *op* is an instance of a dictionary values view. This " -"function always succeeds." -msgstr "若 *op* 是一個字典值視圖的實例則會回傳 true。此函式每次都會執行成功。" - -#: ../../c-api/dict.rst:483 -msgid "" -"Type object for a view of dictionary items. In Python, this is the type of " -"the object returned by :meth:`dict.items`." -msgstr "" - -#: ../../c-api/dict.rst:489 -msgid "" -"Return true if *op* is an instance of a dictionary items view. This function " -"always succeeds." -msgstr "" -"若 *op* 是一個字典項目視圖的實例則會回傳 true。此函式每次都會執行成功。" - -#: ../../c-api/dict.rst:494 -msgid "Ordered Dictionaries" -msgstr "有序字典" - -#: ../../c-api/dict.rst:496 -msgid "" -"Python's C API provides interface for :class:`collections.OrderedDict` from " -"C. Since Python 3.7, dictionaries are ordered by default, so there is " -"usually little need for these functions; prefer ``PyDict*`` where possible." -msgstr "" - -#: ../../c-api/dict.rst:503 -msgid "" -"Type object for ordered dictionaries. This is the same object as :class:" -"`collections.OrderedDict` in the Python layer." -msgstr "" -"有序字典的型別物件。此與 Python 層中的 :class:`collections.OrderedDict` 為同" -"一個物件。" - -#: ../../c-api/dict.rst:509 -msgid "" -"Return true if *od* is an ordered dictionary object or an instance of a " -"subtype of the :class:`~collections.OrderedDict` type. This function always " -"succeeds." -msgstr "" -"若 *od* 是一個有序字典物件或 :class:`~collections.OrderedDict` 的子型別實例則" -"會回傳 true。此函式每次都會執行成功。" - -#: ../../c-api/dict.rst:516 -msgid "" -"Return true if *od* is an ordered dictionary object, but not an instance of " -"a subtype of the :class:`~collections.OrderedDict` type. This function " -"always succeeds." -msgstr "" -"若 *od* 是一個有序字典物件但並不是一個 :class:`~collections.OrderedDict` 子型" -"別的實例，則回傳 true。此函式每次都會執行成功。" - -#: ../../c-api/dict.rst:523 -msgid "Analogous to :c:type:`PyDictKeys_Type` for ordered dictionaries." -msgstr "" - -#: ../../c-api/dict.rst:528 -msgid "Analogous to :c:type:`PyDictValues_Type` for ordered dictionaries." -msgstr "" - -#: ../../c-api/dict.rst:533 -msgid "Analogous to :c:type:`PyDictItems_Type` for ordered dictionaries." -msgstr "" - -#: ../../c-api/dict.rst:538 -msgid "Return a new empty ordered dictionary, or ``NULL`` on failure." -msgstr "回傳一個新的空有序字典，或在失敗時回傳 ``NULL``。" - -#: ../../c-api/dict.rst:540 -msgid "This is analogous to :c:func:`PyDict_New`." -msgstr "這和 :c:func:`PyDict_New` 類似。" - -#: ../../c-api/dict.rst:545 -msgid "" -"Insert *value* into the ordered dictionary *od* with a key of *key*. Return " -"``0`` on success or ``-1`` with an exception set on failure." -msgstr "" - -#: ../../c-api/dict.rst:548 -msgid "This is analogous to :c:func:`PyDict_SetItem`." -msgstr "這和 :c:func:`PyDict_SetItem` 類似。" - -#: ../../c-api/dict.rst:553 -msgid "" -"Remove the entry in the ordered dictionary *od* with key *key*. Return ``0`` " -"on success or ``-1`` with an exception set on failure." -msgstr "" - -#: ../../c-api/dict.rst:556 -msgid "This is analogous to :c:func:`PyDict_DelItem`." -msgstr "這和 :c:func:`PyDict_DelItem` 類似。" - -#: ../../c-api/dict.rst:559 -msgid "These are :term:`soft deprecated` aliases to ``PyDict`` APIs:" -msgstr "" - -#: ../../c-api/dict.rst:566 -msgid "``PyODict``" -msgstr "``PyODict``" - -#: ../../c-api/dict.rst:567 -msgid "``PyDict``" -msgstr "``PyDict``" - -#: ../../c-api/dict.rst:569 -msgid ":c:func:`PyDict_GetItem`" -msgstr ":c:func:`PyDict_GetItem`" - -#: ../../c-api/dict.rst:571 -msgid ":c:func:`PyDict_GetItemWithError`" -msgstr ":c:func:`PyDict_GetItemWithError`" - -#: ../../c-api/dict.rst:573 -msgid ":c:func:`PyDict_GetItemString`" -msgstr ":c:func:`PyDict_GetItemString`" - -#: ../../c-api/dict.rst:575 -msgid ":c:func:`PyDict_Contains`" -msgstr ":c:func:`PyDict_Contains`" - -#: ../../c-api/dict.rst:577 -msgid ":c:func:`PyDict_Size`" -msgstr ":c:func:`PyDict_Size`" - -#: ../../c-api/dict.rst:579 -msgid ":c:func:`PyDict_GET_SIZE`" -msgstr ":c:func:`PyDict_GET_SIZE`" - -#: ../../c-api/dict.rst:8 -msgid "object" -msgstr "object（物件）" - -#: ../../c-api/dict.rst:8 -msgid "dictionary" -msgstr "dictionary（字典）" - -#: ../../c-api/dict.rst:253 -msgid "built-in function" -msgstr "built-in function（內建函式）" - -#: ../../c-api/dict.rst:253 -msgid "len" -msgstr "len" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# aminzai , 2015 +# Liang-Bo Wang , 2015 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-12-02 00:15+0000\n" +"PO-Revision-Date: 2017-09-22 18:26+0000\n" +"Last-Translator: Liang-Bo Wang \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" + +#: ../../c-api/dict.rst:6 +msgid "Dictionary Objects" +msgstr "字典物件" + +#: ../../c-api/dict.rst:13 +msgid "" +"This subtype of :c:type:`PyObject` represents a Python dictionary object." +msgstr ":c:type:`PyObject` 子型別代表一個 Python 字典物件。" + +#: ../../c-api/dict.rst:18 +msgid "" +"This instance of :c:type:`PyTypeObject` represents the Python dictionary " +"type. This is the same object as :class:`dict` in the Python layer." +msgstr "" +":c:type:`PyTypeObject` 實例代表一個 Python 字典型別。此與 Python 層中的 :" +"class:`dict` 為同一個物件。" + +#: ../../c-api/dict.rst:24 +msgid "" +"Return true if *p* is a dict object or an instance of a subtype of the dict " +"type. This function always succeeds." +msgstr "" +"若 *p* 是一個字典物件或字典的子型別實例則會回傳 true。此函式每次都會執行成" +"功。" + +#: ../../c-api/dict.rst:30 +msgid "" +"Return true if *p* is a dict object, but not an instance of a subtype of the " +"dict type. This function always succeeds." +msgstr "" +"若 *p* 是一個字典物件但並不是一個字典子型別的實例，則回傳 true。此函式每次都" +"會執行成功。" + +#: ../../c-api/dict.rst:36 +msgid "Return a new empty dictionary, or ``NULL`` on failure." +msgstr "回傳一個新的空字典，或在失敗時回傳 ``NULL``。" + +#: ../../c-api/dict.rst:41 +msgid "" +"Return a :class:`types.MappingProxyType` object for a mapping which enforces " +"read-only behavior. This is normally used to create a view to prevent " +"modification of the dictionary for non-dynamic class types." +msgstr "" + +#: ../../c-api/dict.rst:48 +msgid "" +"The type object for mapping proxy objects created by :c:func:" +"`PyDictProxy_New` and for the read-only ``__dict__`` attribute of many built-" +"in types. A :c:type:`PyDictProxy_Type` instance provides a dynamic, read-" +"only view of an underlying dictionary: changes to the underlying dictionary " +"are reflected in the proxy, but the proxy itself does not support mutation " +"operations. This corresponds to :class:`types.MappingProxyType` in Python." +msgstr "" + +#: ../../c-api/dict.rst:59 +msgid "Empty an existing dictionary of all key-value pairs." +msgstr "清空現有字典中的所有鍵值對。" + +#: ../../c-api/dict.rst:64 +msgid "" +"Determine if dictionary *p* contains *key*. If an item in *p* matches " +"*key*, return ``1``, otherwise return ``0``. On error, return ``-1``. This " +"is equivalent to the Python expression ``key in p``." +msgstr "" + +#: ../../c-api/dict.rst:71 +msgid "" +"This is the same as :c:func:`PyDict_Contains`, but *key* is specified as a :" +"c:expr:`const char*` UTF-8 encoded bytes string, rather than a :c:expr:" +"`PyObject*`." +msgstr "" + +#: ../../c-api/dict.rst:80 +msgid "Return a new dictionary that contains the same key-value pairs as *p*." +msgstr "回傳一個新的字典，包含與 *p* 相同的鍵值對。" + +#: ../../c-api/dict.rst:85 +msgid "" +"Insert *val* into the dictionary *p* with a key of *key*. *key* must be :" +"term:`hashable`; if it isn't, :exc:`TypeError` will be raised. Return ``0`` " +"on success or ``-1`` on failure. This function *does not* steal a reference " +"to *val*." +msgstr "" + +#: ../../c-api/dict.rst:93 +msgid "" +"This is the same as :c:func:`PyDict_SetItem`, but *key* is specified as a :c:" +"expr:`const char*` UTF-8 encoded bytes string, rather than a :c:expr:" +"`PyObject*`." +msgstr "" + +#: ../../c-api/dict.rst:100 +msgid "" +"Remove the entry in dictionary *p* with key *key*. *key* must be :term:" +"`hashable`; if it isn't, :exc:`TypeError` is raised. If *key* is not in the " +"dictionary, :exc:`KeyError` is raised. Return ``0`` on success or ``-1`` on " +"failure." +msgstr "" + +#: ../../c-api/dict.rst:108 +msgid "" +"This is the same as :c:func:`PyDict_DelItem`, but *key* is specified as a :c:" +"expr:`const char*` UTF-8 encoded bytes string, rather than a :c:expr:" +"`PyObject*`." +msgstr "" + +#: ../../c-api/dict.rst:115 +msgid "" +"Return a new :term:`strong reference` to the object from dictionary *p* " +"which has a key *key*:" +msgstr "" + +#: ../../c-api/dict.rst:118 +msgid "" +"If the key is present, set *\\*result* to a new :term:`strong reference` to " +"the value and return ``1``." +msgstr "" + +#: ../../c-api/dict.rst:120 +msgid "If the key is missing, set *\\*result* to ``NULL`` and return ``0``." +msgstr "如果鍵不存在，將 *\\*result* 設為 ``NULL`` 並回傳 ``0``。" + +#: ../../c-api/dict.rst:121 ../../c-api/dict.rst:218 +msgid "On error, raise an exception and return ``-1``." +msgstr "錯誤發生時，引發一個例外並回傳 ``-1``。" + +#: ../../c-api/dict.rst:125 +msgid "See also the :c:func:`PyObject_GetItem` function." +msgstr "另見 :c:func:`PyObject_GetItem` 函式。" + +#: ../../c-api/dict.rst:130 +msgid "" +"Return a :term:`borrowed reference` to the object from dictionary *p* which " +"has a key *key*. Return ``NULL`` if the key *key* is missing *without* " +"setting an exception." +msgstr "" + +#: ../../c-api/dict.rst:136 +msgid "" +"Exceptions that occur while this calls :meth:`~object.__hash__` and :meth:" +"`~object.__eq__` methods are silently ignored. Prefer the :c:func:" +"`PyDict_GetItemWithError` function instead." +msgstr "" + +#: ../../c-api/dict.rst:140 +msgid "" +"Calling this API without an :term:`attached thread state` had been allowed " +"for historical reason. It is no longer allowed." +msgstr "" + +#: ../../c-api/dict.rst:147 +msgid "" +"Variant of :c:func:`PyDict_GetItem` that does not suppress exceptions. " +"Return ``NULL`` **with** an exception set if an exception occurred. Return " +"``NULL`` **without** an exception set if the key wasn't present." +msgstr "" + +#: ../../c-api/dict.rst:155 +msgid "" +"This is the same as :c:func:`PyDict_GetItem`, but *key* is specified as a :c:" +"expr:`const char*` UTF-8 encoded bytes string, rather than a :c:expr:" +"`PyObject*`." +msgstr "" + +#: ../../c-api/dict.rst:161 +msgid "" +"Exceptions that occur while this calls :meth:`~object.__hash__` and :meth:" +"`~object.__eq__` methods or while creating the temporary :class:`str` object " +"are silently ignored. Prefer using the :c:func:`PyDict_GetItemWithError` " +"function with your own :c:func:`PyUnicode_FromString` *key* instead." +msgstr "" + +#: ../../c-api/dict.rst:170 +msgid "" +"Similar to :c:func:`PyDict_GetItemRef`, but *key* is specified as a :c:expr:" +"`const char*` UTF-8 encoded bytes string, rather than a :c:expr:`PyObject*`." +msgstr "" + +#: ../../c-api/dict.rst:179 +msgid "" +"This is the same as the Python-level :meth:`dict.setdefault`. If present, " +"it returns the value corresponding to *key* from the dictionary *p*. If the " +"key is not in the dict, it is inserted with value *defaultobj* and " +"*defaultobj* is returned. This function evaluates the hash function of " +"*key* only once, instead of evaluating it independently for the lookup and " +"the insertion." +msgstr "" + +#: ../../c-api/dict.rst:190 +msgid "" +"Inserts *default_value* into the dictionary *p* with a key of *key* if the " +"key is not already present in the dictionary. If *result* is not ``NULL``, " +"then *\\*result* is set to a :term:`strong reference` to either " +"*default_value*, if the key was not present, or the existing value, if *key* " +"was already present in the dictionary. Returns ``1`` if the key was present " +"and *default_value* was not inserted, or ``0`` if the key was not present " +"and *default_value* was inserted. On failure, returns ``-1``, sets an " +"exception, and sets ``*result`` to ``NULL``." +msgstr "" + +#: ../../c-api/dict.rst:200 +msgid "" +"For clarity: if you have a strong reference to *default_value* before " +"calling this function, then after it returns, you hold a strong reference to " +"both *default_value* and *\\*result* (if it's not ``NULL``). These may refer " +"to the same object: in that case you hold two separate references to it." +msgstr "" + +#: ../../c-api/dict.rst:211 +msgid "" +"Remove *key* from dictionary *p* and optionally return the removed value. Do " +"not raise :exc:`KeyError` if the key is missing." +msgstr "" + +#: ../../c-api/dict.rst:214 +msgid "" +"If the key is present, set *\\*result* to a new reference to the removed " +"value if *result* is not ``NULL``, and return ``1``." +msgstr "" + +#: ../../c-api/dict.rst:216 +msgid "" +"If the key is missing, set *\\*result* to ``NULL`` if *result* is not " +"``NULL``, and return ``0``." +msgstr "" + +#: ../../c-api/dict.rst:220 +msgid "" +"Similar to :meth:`dict.pop`, but without the default value and not raising :" +"exc:`KeyError` if the key is missing." +msgstr "" + +#: ../../c-api/dict.rst:228 +msgid "" +"Similar to :c:func:`PyDict_Pop`, but *key* is specified as a :c:expr:`const " +"char*` UTF-8 encoded bytes string, rather than a :c:expr:`PyObject*`." +msgstr "" + +#: ../../c-api/dict.rst:237 +msgid "" +"Return a :c:type:`PyListObject` containing all the items from the dictionary." +msgstr "回傳一個包含字典中所有項目的 :c:type:`PyListObject`。" + +#: ../../c-api/dict.rst:242 +msgid "" +"Return a :c:type:`PyListObject` containing all the keys from the dictionary." +msgstr "回傳一個包含字典中所有鍵的 :c:type:`PyListObject`。" + +#: ../../c-api/dict.rst:247 +msgid "" +"Return a :c:type:`PyListObject` containing all the values from the " +"dictionary *p*." +msgstr "回傳一個包含字典 *p* 中所有值的 :c:type:`PyListObject`。" + +#: ../../c-api/dict.rst:255 +msgid "" +"Return the number of items in the dictionary. This is equivalent to " +"``len(p)`` on a dictionary." +msgstr "回傳字典中項目的數量。此與於字典呼叫 ``len(p)`` 等效。" + +#: ../../c-api/dict.rst:261 +msgid "Similar to :c:func:`PyDict_Size`, but without error checking." +msgstr "和 :c:func:`PyDict_Size` 類似，但沒有錯誤檢查。" + +#: ../../c-api/dict.rst:266 +msgid "" +"Iterate over all key-value pairs in the dictionary *p*. The :c:type:" +"`Py_ssize_t` referred to by *ppos* must be initialized to ``0`` prior to the " +"first call to this function to start the iteration; the function returns " +"true for each pair in the dictionary, and false once all pairs have been " +"reported. The parameters *pkey* and *pvalue* should either point to :c:expr:" +"`PyObject*` variables that will be filled in with each key and value, " +"respectively, or may be ``NULL``. Any references returned through them are " +"borrowed. *ppos* should not be altered during iteration. Its value " +"represents offsets within the internal dictionary structure, and since the " +"structure is sparse, the offsets are not consecutive." +msgstr "" + +#: ../../c-api/dict.rst:277 +msgid "For example::" +msgstr "舉例來說： ::" + +#: ../../c-api/dict.rst:279 +msgid "" +"PyObject *key, *value;\n" +"Py_ssize_t pos = 0;\n" +"\n" +"while (PyDict_Next(self->dict, &pos, &key, &value)) {\n" +" /* do something interesting with the values... */\n" +" ...\n" +"}" +msgstr "" +"PyObject *key, *value;\n" +"Py_ssize_t pos = 0;\n" +"\n" +"while (PyDict_Next(self->dict, &pos, &key, &value)) {\n" +" /* 用值做一些有趣的事情... */\n" +" ...\n" +"}" + +#: ../../c-api/dict.rst:287 +msgid "" +"The dictionary *p* should not be mutated during iteration. It is safe to " +"modify the values of the keys as you iterate over the dictionary, but only " +"so long as the set of keys does not change. For example::" +msgstr "" + +#: ../../c-api/dict.rst:291 +msgid "" +"PyObject *key, *value;\n" +"Py_ssize_t pos = 0;\n" +"\n" +"while (PyDict_Next(self->dict, &pos, &key, &value)) {\n" +" long i = PyLong_AsLong(value);\n" +" if (i == -1 && PyErr_Occurred()) {\n" +" return -1;\n" +" }\n" +" PyObject *o = PyLong_FromLong(i + 1);\n" +" if (o == NULL)\n" +" return -1;\n" +" if (PyDict_SetItem(self->dict, key, o) < 0) {\n" +" Py_DECREF(o);\n" +" return -1;\n" +" }\n" +" Py_DECREF(o);\n" +"}" +msgstr "" +"PyObject *key, *value;\n" +"Py_ssize_t pos = 0;\n" +"\n" +"while (PyDict_Next(self->dict, &pos, &key, &value)) {\n" +" long i = PyLong_AsLong(value);\n" +" if (i == -1 && PyErr_Occurred()) {\n" +" return -1;\n" +" }\n" +" PyObject *o = PyLong_FromLong(i + 1);\n" +" if (o == NULL)\n" +" return -1;\n" +" if (PyDict_SetItem(self->dict, key, o) < 0) {\n" +" Py_DECREF(o);\n" +" return -1;\n" +" }\n" +" Py_DECREF(o);\n" +"}" + +#: ../../c-api/dict.rst:309 +msgid "" +"The function is not thread-safe in the :term:`free-threaded ` build without external synchronization. You can use :c:macro:" +"`Py_BEGIN_CRITICAL_SECTION` to lock the dictionary while iterating over it::" +msgstr "" + +#: ../../c-api/dict.rst:314 +msgid "" +"Py_BEGIN_CRITICAL_SECTION(self->dict);\n" +"while (PyDict_Next(self->dict, &pos, &key, &value)) {\n" +" ...\n" +"}\n" +"Py_END_CRITICAL_SECTION();" +msgstr "" +"Py_BEGIN_CRITICAL_SECTION(self->dict);\n" +"while (PyDict_Next(self->dict, &pos, &key, &value)) {\n" +" ...\n" +"}\n" +"Py_END_CRITICAL_SECTION();" + +#: ../../c-api/dict.rst:322 +msgid "" +"On the free-threaded build, this function can be used safely inside a " +"critical section. However, the references returned for *pkey* and *pvalue* " +"are :term:`borrowed ` and are only valid while the " +"critical section is held. If you need to use these objects outside the " +"critical section or when the critical section can be suspended, create a :" +"term:`strong reference ` (for example, using :c:func:" +"`Py_NewRef`)." +msgstr "" + +#: ../../c-api/dict.rst:332 +msgid "" +"Iterate over mapping object *b* adding key-value pairs to dictionary *a*. " +"*b* may be a dictionary, or any object supporting :c:func:`PyMapping_Keys` " +"and :c:func:`PyObject_GetItem`. If *override* is true, existing pairs in *a* " +"will be replaced if a matching key is found in *b*, otherwise pairs will " +"only be added if there is not a matching key in *a*. Return ``0`` on success " +"or ``-1`` if an exception was raised." +msgstr "" + +#: ../../c-api/dict.rst:342 +msgid "" +"This is the same as ``PyDict_Merge(a, b, 1)`` in C, and is similar to ``a." +"update(b)`` in Python except that :c:func:`PyDict_Update` doesn't fall back " +"to the iterating over a sequence of key value pairs if the second argument " +"has no \"keys\" attribute. Return ``0`` on success or ``-1`` if an " +"exception was raised." +msgstr "" + +#: ../../c-api/dict.rst:351 +msgid "" +"Update or merge into dictionary *a*, from the key-value pairs in *seq2*. " +"*seq2* must be an iterable object producing iterable objects of length 2, " +"viewed as key-value pairs. In case of duplicate keys, the last wins if " +"*override* is true, else the first wins. Return ``0`` on success or ``-1`` " +"if an exception was raised. Equivalent Python (except for the return value)::" +msgstr "" + +#: ../../c-api/dict.rst:358 +msgid "" +"def PyDict_MergeFromSeq2(a, seq2, override):\n" +" for key, value in seq2:\n" +" if override or key not in a:\n" +" a[key] = value" +msgstr "" +"def PyDict_MergeFromSeq2(a, seq2, override):\n" +" for key, value in seq2:\n" +" if override or key not in a:\n" +" a[key] = value" + +#: ../../c-api/dict.rst:365 +msgid "" +"Register *callback* as a dictionary watcher. Return a non-negative integer " +"id which must be passed to future calls to :c:func:`PyDict_Watch`. In case " +"of error (e.g. no more watcher IDs available), return ``-1`` and set an " +"exception." +msgstr "" + +#: ../../c-api/dict.rst:374 +msgid "" +"Clear watcher identified by *watcher_id* previously returned from :c:func:" +"`PyDict_AddWatcher`. Return ``0`` on success, ``-1`` on error (e.g. if the " +"given *watcher_id* was never registered.)" +msgstr "" + +#: ../../c-api/dict.rst:382 +msgid "" +"Mark dictionary *dict* as watched. The callback granted *watcher_id* by :c:" +"func:`PyDict_AddWatcher` will be called when *dict* is modified or " +"deallocated. Return ``0`` on success or ``-1`` on error." +msgstr "" + +#: ../../c-api/dict.rst:390 +msgid "" +"Mark dictionary *dict* as no longer watched. The callback granted " +"*watcher_id* by :c:func:`PyDict_AddWatcher` will no longer be called when " +"*dict* is modified or deallocated. The dict must previously have been " +"watched by this watcher. Return ``0`` on success or ``-1`` on error." +msgstr "" + +#: ../../c-api/dict.rst:399 +msgid "" +"Enumeration of possible dictionary watcher events: ``PyDict_EVENT_ADDED``, " +"``PyDict_EVENT_MODIFIED``, ``PyDict_EVENT_DELETED``, " +"``PyDict_EVENT_CLONED``, ``PyDict_EVENT_CLEARED``, or " +"``PyDict_EVENT_DEALLOCATED``." +msgstr "" + +#: ../../c-api/dict.rst:407 +msgid "Type of a dict watcher callback function." +msgstr "" + +#: ../../c-api/dict.rst:409 +msgid "" +"If *event* is ``PyDict_EVENT_CLEARED`` or ``PyDict_EVENT_DEALLOCATED``, both " +"*key* and *new_value* will be ``NULL``. If *event* is ``PyDict_EVENT_ADDED`` " +"or ``PyDict_EVENT_MODIFIED``, *new_value* will be the new value for *key*. " +"If *event* is ``PyDict_EVENT_DELETED``, *key* is being deleted from the " +"dictionary and *new_value* will be ``NULL``." +msgstr "" + +#: ../../c-api/dict.rst:415 +msgid "" +"``PyDict_EVENT_CLONED`` occurs when *dict* was previously empty and another " +"dict is merged into it. To maintain efficiency of this operation, per-key " +"``PyDict_EVENT_ADDED`` events are not issued in this case; instead a single " +"``PyDict_EVENT_CLONED`` is issued, and *key* will be the source dictionary." +msgstr "" + +#: ../../c-api/dict.rst:421 +msgid "" +"The callback may inspect but must not modify *dict*; doing so could have " +"unpredictable effects, including infinite recursion. Do not trigger Python " +"code execution in the callback, as it could modify the dict as a side effect." +msgstr "" + +#: ../../c-api/dict.rst:425 +msgid "" +"If *event* is ``PyDict_EVENT_DEALLOCATED``, taking a new reference in the " +"callback to the about-to-be-destroyed dictionary will resurrect it and " +"prevent it from being freed at this time. When the resurrected object is " +"destroyed later, any watcher callbacks active at that time will be called " +"again." +msgstr "" + +#: ../../c-api/dict.rst:431 +msgid "" +"Callbacks occur before the notified modification to *dict* takes place, so " +"the prior state of *dict* can be inspected." +msgstr "" + +#: ../../c-api/dict.rst:434 +msgid "" +"If the callback sets an exception, it must return ``-1``; this exception " +"will be printed as an unraisable exception using :c:func:" +"`PyErr_WriteUnraisable`. Otherwise it should return ``0``." +msgstr "" + +#: ../../c-api/dict.rst:438 +msgid "" +"There may already be a pending exception set on entry to the callback. In " +"this case, the callback should return ``0`` with the same exception still " +"set. This means the callback may not call any other API that can set an " +"exception unless it saves and clears the exception state first, and restores " +"it before returning." +msgstr "" + +#: ../../c-api/dict.rst:448 +msgid "Dictionary View Objects" +msgstr "字典視圖物件" + +#: ../../c-api/dict.rst:452 +msgid "" +"Return true if *op* is a view of a set inside a dictionary. This is " +"currently equivalent to :c:expr:`PyDictKeys_Check(op) || " +"PyDictItems_Check(op)`. This function always succeeds." +msgstr "" +"若 *op* 是一個字典中集合的視圖則會回傳 true。這目前等同於 :c:expr:" +"`PyDictKeys_Check(op) || PyDictItems_Check(op)`。此函式每次都會執行成功。" + +#: ../../c-api/dict.rst:459 +msgid "" +"Type object for a view of dictionary keys. In Python, this is the type of " +"the object returned by :meth:`dict.keys`." +msgstr "" + +#: ../../c-api/dict.rst:465 +msgid "" +"Return true if *op* is an instance of a dictionary keys view. This function " +"always succeeds." +msgstr "若 *op* 是一個字典鍵視圖的實例則會回傳 true。此函式每次都會執行成功。" + +#: ../../c-api/dict.rst:471 +msgid "" +"Type object for a view of dictionary values. In Python, this is the type of " +"the object returned by :meth:`dict.values`." +msgstr "" + +#: ../../c-api/dict.rst:477 +msgid "" +"Return true if *op* is an instance of a dictionary values view. This " +"function always succeeds." +msgstr "若 *op* 是一個字典值視圖的實例則會回傳 true。此函式每次都會執行成功。" + +#: ../../c-api/dict.rst:483 +msgid "" +"Type object for a view of dictionary items. In Python, this is the type of " +"the object returned by :meth:`dict.items`." +msgstr "" + +#: ../../c-api/dict.rst:489 +msgid "" +"Return true if *op* is an instance of a dictionary items view. This function " +"always succeeds." +msgstr "" +"若 *op* 是一個字典項目視圖的實例則會回傳 true。此函式每次都會執行成功。" + +#: ../../c-api/dict.rst:494 +msgid "Ordered Dictionaries" +msgstr "有序字典" + +#: ../../c-api/dict.rst:496 +msgid "" +"Python's C API provides interface for :class:`collections.OrderedDict` from " +"C. Since Python 3.7, dictionaries are ordered by default, so there is " +"usually little need for these functions; prefer ``PyDict*`` where possible." +msgstr "" + +#: ../../c-api/dict.rst:503 +msgid "" +"Type object for ordered dictionaries. This is the same object as :class:" +"`collections.OrderedDict` in the Python layer." +msgstr "" +"有序字典的型別物件。此與 Python 層中的 :class:`collections.OrderedDict` 為同" +"一個物件。" + +#: ../../c-api/dict.rst:509 +msgid "" +"Return true if *od* is an ordered dictionary object or an instance of a " +"subtype of the :class:`~collections.OrderedDict` type. This function always " +"succeeds." +msgstr "" +"若 *od* 是一個有序字典物件或 :class:`~collections.OrderedDict` 的子型別實例則" +"會回傳 true。此函式每次都會執行成功。" + +#: ../../c-api/dict.rst:516 +msgid "" +"Return true if *od* is an ordered dictionary object, but not an instance of " +"a subtype of the :class:`~collections.OrderedDict` type. This function " +"always succeeds." +msgstr "" +"若 *od* 是一個有序字典物件但並不是一個 :class:`~collections.OrderedDict` 子型" +"別的實例，則回傳 true。此函式每次都會執行成功。" + +#: ../../c-api/dict.rst:523 +msgid "Analogous to :c:type:`PyDictKeys_Type` for ordered dictionaries." +msgstr "" + +#: ../../c-api/dict.rst:528 +msgid "Analogous to :c:type:`PyDictValues_Type` for ordered dictionaries." +msgstr "" + +#: ../../c-api/dict.rst:533 +msgid "Analogous to :c:type:`PyDictItems_Type` for ordered dictionaries." +msgstr "" + +#: ../../c-api/dict.rst:538 +msgid "Return a new empty ordered dictionary, or ``NULL`` on failure." +msgstr "回傳一個新的空有序字典，或在失敗時回傳 ``NULL``。" + +#: ../../c-api/dict.rst:540 +msgid "This is analogous to :c:func:`PyDict_New`." +msgstr "這和 :c:func:`PyDict_New` 類似。" + +#: ../../c-api/dict.rst:545 +msgid "" +"Insert *value* into the ordered dictionary *od* with a key of *key*. Return " +"``0`` on success or ``-1`` with an exception set on failure." +msgstr "" + +#: ../../c-api/dict.rst:548 +msgid "This is analogous to :c:func:`PyDict_SetItem`." +msgstr "這和 :c:func:`PyDict_SetItem` 類似。" + +#: ../../c-api/dict.rst:553 +msgid "" +"Remove the entry in the ordered dictionary *od* with key *key*. Return ``0`` " +"on success or ``-1`` with an exception set on failure." +msgstr "" + +#: ../../c-api/dict.rst:556 +msgid "This is analogous to :c:func:`PyDict_DelItem`." +msgstr "這和 :c:func:`PyDict_DelItem` 類似。" + +#: ../../c-api/dict.rst:559 +msgid "These are :term:`soft deprecated` aliases to ``PyDict`` APIs:" +msgstr "" + +#: ../../c-api/dict.rst:566 +msgid "``PyODict``" +msgstr "``PyODict``" + +#: ../../c-api/dict.rst:567 +msgid "``PyDict``" +msgstr "``PyDict``" + +#: ../../c-api/dict.rst:569 +msgid ":c:func:`PyDict_GetItem`" +msgstr ":c:func:`PyDict_GetItem`" + +#: ../../c-api/dict.rst:571 +msgid ":c:func:`PyDict_GetItemWithError`" +msgstr ":c:func:`PyDict_GetItemWithError`" + +#: ../../c-api/dict.rst:573 +msgid ":c:func:`PyDict_GetItemString`" +msgstr ":c:func:`PyDict_GetItemString`" + +#: ../../c-api/dict.rst:575 +msgid ":c:func:`PyDict_Contains`" +msgstr ":c:func:`PyDict_Contains`" + +#: ../../c-api/dict.rst:577 +msgid ":c:func:`PyDict_Size`" +msgstr ":c:func:`PyDict_Size`" + +#: ../../c-api/dict.rst:579 +msgid ":c:func:`PyDict_GET_SIZE`" +msgstr ":c:func:`PyDict_GET_SIZE`" + +#: ../../c-api/dict.rst:8 +msgid "object" +msgstr "object（物件）" + +#: ../../c-api/dict.rst:8 +msgid "dictionary" +msgstr "dictionary（字典）" + +#: ../../c-api/dict.rst:253 +msgid "built-in function" +msgstr "built-in function（內建函式）" + +#: ../../c-api/dict.rst:253 +msgid "len" +msgstr "len" diff --git a/c-api/exceptions.po b/c-api/exceptions.po index 8a03c9821f..ebef8760f5 100644 --- a/c-api/exceptions.po +++ b/c-api/exceptions.po @@ -1,1575 +1,1575 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Ching-Lung Chuang, 2015 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-26 00:14+0000\n" -"PO-Revision-Date: 2018-05-23 14:05+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" - -#: ../../c-api/exceptions.rst:8 -msgid "Exception Handling" -msgstr "例外處理" - -#: ../../c-api/exceptions.rst:10 -msgid "" -"The functions described in this chapter will let you handle and raise Python " -"exceptions. It is important to understand some of the basics of Python " -"exception handling. It works somewhat like the POSIX :c:data:`errno` " -"variable: there is a global indicator (per thread) of the last error that " -"occurred. Most C API functions don't clear this on success, but will set it " -"to indicate the cause of the error on failure. Most C API functions also " -"return an error indicator, usually ``NULL`` if they are supposed to return a " -"pointer, or ``-1`` if they return an integer (exception: the ``PyArg_*`` " -"functions return ``1`` for success and ``0`` for failure)." -msgstr "" - -#: ../../c-api/exceptions.rst:20 -msgid "" -"Concretely, the error indicator consists of three object pointers: the " -"exception's type, the exception's value, and the traceback object. Any of " -"those pointers can be ``NULL`` if non-set (although some combinations are " -"forbidden, for example you can't have a non-``NULL`` traceback if the " -"exception type is ``NULL``)." -msgstr "" - -#: ../../c-api/exceptions.rst:26 -msgid "" -"When a function must fail because some function it called failed, it " -"generally doesn't set the error indicator; the function it called already " -"set it. It is responsible for either handling the error and clearing the " -"exception or returning after cleaning up any resources it holds (such as " -"object references or memory allocations); it should *not* continue normally " -"if it is not prepared to handle the error. If returning due to an error, it " -"is important to indicate to the caller that an error has been set. If the " -"error is not handled or carefully propagated, additional calls into the " -"Python/C API may not behave as intended and may fail in mysterious ways." -msgstr "" - -#: ../../c-api/exceptions.rst:37 -msgid "" -"The error indicator is **not** the result of :func:`sys.exc_info`. The " -"former corresponds to an exception that is not yet caught (and is therefore " -"still propagating), while the latter returns an exception after it is caught " -"(and has therefore stopped propagating)." -msgstr "" - -#: ../../c-api/exceptions.rst:44 -msgid "Printing and clearing" -msgstr "" - -#: ../../c-api/exceptions.rst:49 -msgid "" -"Clear the error indicator. If the error indicator is not set, there is no " -"effect." -msgstr "" - -#: ../../c-api/exceptions.rst:55 -msgid "" -"Print a standard traceback to ``sys.stderr`` and clear the error indicator. " -"**Unless** the error is a ``SystemExit``, in that case no traceback is " -"printed and the Python process will exit with the error code specified by " -"the ``SystemExit`` instance." -msgstr "" - -#: ../../c-api/exceptions.rst:60 -msgid "" -"Call this function **only** when the error indicator is set. Otherwise it " -"will cause a fatal error!" -msgstr "" - -#: ../../c-api/exceptions.rst:63 -msgid "" -"If *set_sys_last_vars* is nonzero, the variable :data:`sys.last_exc` is set " -"to the printed exception. For backwards compatibility, the deprecated " -"variables :data:`sys.last_type`, :data:`sys.last_value` and :data:`sys." -"last_traceback` are also set to the type, value and traceback of this " -"exception, respectively." -msgstr "" - -#: ../../c-api/exceptions.rst:69 -msgid "The setting of :data:`sys.last_exc` was added." -msgstr "新增 :data:`sys.last_exc` 設定。" - -#: ../../c-api/exceptions.rst:75 -msgid "Alias for ``PyErr_PrintEx(1)``." -msgstr "``PyErr_PrintEx(1)`` 的別名。" - -#: ../../c-api/exceptions.rst:80 -msgid "" -"Call :func:`sys.unraisablehook` using the current exception and *obj* " -"argument." -msgstr "" - -#: ../../c-api/exceptions.rst:83 -msgid "" -"This utility function prints a warning message to ``sys.stderr`` when an " -"exception has been set but it is impossible for the interpreter to actually " -"raise the exception. It is used, for example, when an exception occurs in " -"an :meth:`~object.__del__` method." -msgstr "" - -#: ../../c-api/exceptions.rst:88 -msgid "" -"The function is called with a single argument *obj* that identifies the " -"context in which the unraisable exception occurred. If possible, the repr of " -"*obj* will be printed in the warning message. If *obj* is ``NULL``, only the " -"traceback is printed." -msgstr "" - -#: ../../c-api/exceptions.rst:93 -msgid "An exception must be set when calling this function." -msgstr "" - -#: ../../c-api/exceptions.rst:95 -msgid "Print a traceback. Print only traceback if *obj* is ``NULL``." -msgstr "" - -#: ../../c-api/exceptions.rst:98 -msgid "Use :func:`sys.unraisablehook`." -msgstr "使用 :func:`sys.unraisablehook`。" - -#: ../../c-api/exceptions.rst:104 -msgid "" -"Similar to :c:func:`PyErr_WriteUnraisable`, but the *format* and subsequent " -"parameters help format the warning message; they have the same meaning and " -"values as in :c:func:`PyUnicode_FromFormat`. ``PyErr_WriteUnraisable(obj)`` " -"is roughly equivalent to ``PyErr_FormatUnraisable(\"Exception ignored in: " -"%R\", obj)``. If *format* is ``NULL``, only the traceback is printed." -msgstr "" - -#: ../../c-api/exceptions.rst:116 -msgid "" -"Print the standard traceback display of ``exc`` to ``sys.stderr``, including " -"chained exceptions and notes." -msgstr "" - -#: ../../c-api/exceptions.rst:123 -msgid "Raising exceptions" -msgstr "引發例外" - -#: ../../c-api/exceptions.rst:125 -msgid "" -"These functions help you set the current thread's error indicator. For " -"convenience, some of these functions will always return a ``NULL`` pointer " -"for use in a ``return`` statement." -msgstr "" - -#: ../../c-api/exceptions.rst:132 -msgid "" -"This is the most common way to set the error indicator. The first argument " -"specifies the exception type; it is normally one of the standard exceptions, " -"e.g. :c:data:`PyExc_RuntimeError`. You need not create a new :term:`strong " -"reference` to it (e.g. with :c:func:`Py_INCREF`). The second argument is an " -"error message; it is decoded from ``'utf-8'``." -msgstr "" - -#: ../../c-api/exceptions.rst:141 -msgid "" -"This function is similar to :c:func:`PyErr_SetString` but lets you specify " -"an arbitrary Python object for the \"value\" of the exception." -msgstr "" - -#: ../../c-api/exceptions.rst:147 -msgid "" -"This function sets the error indicator and returns ``NULL``. *exception* " -"should be a Python exception class. The *format* and subsequent parameters " -"help format the error message; they have the same meaning and values as in :" -"c:func:`PyUnicode_FromFormat`. *format* is an ASCII-encoded string." -msgstr "" - -#: ../../c-api/exceptions.rst:156 -msgid "" -"Same as :c:func:`PyErr_Format`, but taking a :c:type:`va_list` argument " -"rather than a variable number of arguments." -msgstr "" - -#: ../../c-api/exceptions.rst:164 -msgid "This is a shorthand for ``PyErr_SetObject(type, Py_None)``." -msgstr "" - -#: ../../c-api/exceptions.rst:169 -msgid "" -"This is a shorthand for ``PyErr_SetString(PyExc_TypeError, message)``, where " -"*message* indicates that a built-in operation was invoked with an illegal " -"argument. It is mostly for internal use." -msgstr "" - -#: ../../c-api/exceptions.rst:176 -msgid "" -"This is a shorthand for ``PyErr_SetNone(PyExc_MemoryError)``; it returns " -"``NULL`` so an object allocation function can write ``return " -"PyErr_NoMemory();`` when it runs out of memory." -msgstr "" - -#: ../../c-api/exceptions.rst:185 -msgid "" -"This is a convenience function to raise an exception when a C library " -"function has returned an error and set the C variable :c:data:`errno`. It " -"constructs a tuple object whose first item is the integer :c:data:`errno` " -"value and whose second item is the corresponding error message (gotten from :" -"c:func:`!strerror`), and then calls ``PyErr_SetObject(type, object)``. On " -"Unix, when the :c:data:`errno` value is :c:macro:`!EINTR`, indicating an " -"interrupted system call, this calls :c:func:`PyErr_CheckSignals`, and if " -"that set the error indicator, leaves it set to that. The function always " -"returns ``NULL``, so a wrapper function around a system call can write " -"``return PyErr_SetFromErrno(type);`` when the system call returns an error." -msgstr "" - -#: ../../c-api/exceptions.rst:199 -msgid "" -"Similar to :c:func:`PyErr_SetFromErrno`, with the additional behavior that " -"if *filenameObject* is not ``NULL``, it is passed to the constructor of " -"*type* as a third parameter. In the case of :exc:`OSError` exception, this " -"is used to define the :attr:`!filename` attribute of the exception instance." -msgstr "" - -#: ../../c-api/exceptions.rst:208 -msgid "" -"Similar to :c:func:`PyErr_SetFromErrnoWithFilenameObject`, but takes a " -"second filename object, for raising errors when a function that takes two " -"filenames fails." -msgstr "" - -#: ../../c-api/exceptions.rst:217 -msgid "" -"Similar to :c:func:`PyErr_SetFromErrnoWithFilenameObject`, but the filename " -"is given as a C string. *filename* is decoded from the :term:`filesystem " -"encoding and error handler`." -msgstr "" - -#: ../../c-api/exceptions.rst:224 -msgid "" -"This is a convenience function to raise :exc:`OSError`. If called with " -"*ierr* of ``0``, the error code returned by a call to :c:func:`!" -"GetLastError` is used instead. It calls the Win32 function :c:func:`!" -"FormatMessage` to retrieve the Windows description of error code given by " -"*ierr* or :c:func:`!GetLastError`, then it constructs a :exc:`OSError` " -"object with the :attr:`~OSError.winerror` attribute set to the error code, " -"the :attr:`~OSError.strerror` attribute set to the corresponding error " -"message (gotten from :c:func:`!FormatMessage`), and then calls " -"``PyErr_SetObject(PyExc_OSError, object)``. This function always returns " -"``NULL``." -msgstr "" - -#: ../../c-api/exceptions.rst:234 ../../c-api/exceptions.rst:242 -#: ../../c-api/exceptions.rst:253 ../../c-api/exceptions.rst:263 -#: ../../c-api/exceptions.rst:271 ../../c-api/exceptions.rst:281 -msgid "Availability" -msgstr "可用性" - -#: ../../c-api/exceptions.rst:239 -msgid "" -"Similar to :c:func:`PyErr_SetFromWindowsErr`, with an additional parameter " -"specifying the exception type to be raised." -msgstr "" - -#: ../../c-api/exceptions.rst:247 -msgid "" -"Similar to :c:func:`PyErr_SetFromWindowsErr`, with the additional behavior " -"that if *filename* is not ``NULL``, it is decoded from the filesystem " -"encoding (:func:`os.fsdecode`) and passed to the constructor of :exc:" -"`OSError` as a third parameter to be used to define the :attr:`!filename` " -"attribute of the exception instance." -msgstr "" - -#: ../../c-api/exceptions.rst:258 -msgid "" -"Similar to :c:func:`PyErr_SetExcFromWindowsErr`, with the additional " -"behavior that if *filename* is not ``NULL``, it is passed to the constructor " -"of :exc:`OSError` as a third parameter to be used to define the :attr:`!" -"filename` attribute of the exception instance." -msgstr "" - -#: ../../c-api/exceptions.rst:268 -msgid "" -"Similar to :c:func:`PyErr_SetExcFromWindowsErrWithFilenameObject`, but " -"accepts a second filename object." -msgstr "" - -#: ../../c-api/exceptions.rst:278 -msgid "" -"Similar to :c:func:`PyErr_SetFromWindowsErrWithFilename`, with an additional " -"parameter specifying the exception type to be raised." -msgstr "" - -#: ../../c-api/exceptions.rst:286 -msgid "" -"This is a convenience function to raise :exc:`ImportError`. *msg* will be " -"set as the exception's message string. *name* and *path*, both of which can " -"be ``NULL``, will be set as the :exc:`ImportError`'s respective ``name`` and " -"``path`` attributes." -msgstr "" - -#: ../../c-api/exceptions.rst:296 -msgid "" -"Much like :c:func:`PyErr_SetImportError` but this function allows for " -"specifying a subclass of :exc:`ImportError` to raise." -msgstr "" - -#: ../../c-api/exceptions.rst:304 -msgid "" -"Set file, line, and offset information for the current exception. If the " -"current exception is not a :exc:`SyntaxError`, then it sets additional " -"attributes, which make the exception printing subsystem think the exception " -"is a :exc:`SyntaxError`." -msgstr "" - -#: ../../c-api/exceptions.rst:314 -msgid "" -"Similar to :c:func:`PyErr_SyntaxLocationObject`, but also sets the " -"*end_lineno* and *end_col_offset* information for the current exception." -msgstr "" - -#: ../../c-api/exceptions.rst:322 -msgid "" -"Like :c:func:`PyErr_SyntaxLocationObject`, but *filename* is a byte string " -"decoded from the :term:`filesystem encoding and error handler`." -msgstr "" - -#: ../../c-api/exceptions.rst:330 -msgid "" -"Like :c:func:`PyErr_SyntaxLocationEx`, but the *col_offset* parameter is " -"omitted." -msgstr "" - -#: ../../c-api/exceptions.rst:336 -msgid "" -"This is a shorthand for ``PyErr_SetString(PyExc_SystemError, message)``, " -"where *message* indicates that an internal operation (e.g. a Python/C API " -"function) was invoked with an illegal argument. It is mostly for internal " -"use." -msgstr "" - -#: ../../c-api/exceptions.rst:344 -msgid "" -"Get the source line in *filename* at line *lineno*. *filename* should be a " -"Python :class:`str` object." -msgstr "" - -#: ../../c-api/exceptions.rst:347 -msgid "" -"On success, this function returns a Python string object with the found " -"line. On failure, this function returns ``NULL`` without an exception set." -msgstr "" - -#: ../../c-api/exceptions.rst:353 -msgid "" -"Similar to :c:func:`PyErr_ProgramTextObject`, but *filename* is a :c:expr:" -"`const char *`, which is decoded with the :term:`filesystem encoding and " -"error handler`, instead of a Python object reference." -msgstr "" - -#: ../../c-api/exceptions.rst:360 -msgid "Issuing warnings" -msgstr "發出警告" - -#: ../../c-api/exceptions.rst:362 -msgid "" -"Use these functions to issue warnings from C code. They mirror similar " -"functions exported by the Python :mod:`warnings` module. They normally " -"print a warning message to *sys.stderr*; however, it is also possible that " -"the user has specified that warnings are to be turned into errors, and in " -"that case they will raise an exception. It is also possible that the " -"functions raise an exception because of a problem with the warning " -"machinery. The return value is ``0`` if no exception is raised, or ``-1`` if " -"an exception is raised. (It is not possible to determine whether a warning " -"message is actually printed, nor what the reason is for the exception; this " -"is intentional.) If an exception is raised, the caller should do its normal " -"exception handling (for example, :c:func:`Py_DECREF` owned references and " -"return an error value)." -msgstr "" - -#: ../../c-api/exceptions.rst:377 -msgid "" -"Issue a warning message. The *category* argument is a warning category (see " -"below) or ``NULL``; the *message* argument is a UTF-8 encoded string. " -"*stack_level* is a positive number giving a number of stack frames; the " -"warning will be issued from the currently executing line of code in that " -"stack frame. A *stack_level* of 1 is the function calling :c:func:" -"`PyErr_WarnEx`, 2 is the function above that, and so forth." -msgstr "" - -#: ../../c-api/exceptions.rst:384 -msgid "" -"Warning categories must be subclasses of :c:data:`PyExc_Warning`; :c:data:" -"`PyExc_Warning` is a subclass of :c:data:`PyExc_Exception`; the default " -"warning category is :c:data:`PyExc_RuntimeWarning`. The standard Python " -"warning categories are available as global variables whose names are " -"enumerated at :ref:`standardwarningcategories`." -msgstr "" - -#: ../../c-api/exceptions.rst:390 -msgid "" -"For information about warning control, see the documentation for the :mod:" -"`warnings` module and the :option:`-W` option in the command line " -"documentation. There is no C API for warning control." -msgstr "" - -#: ../../c-api/exceptions.rst:397 -msgid "" -"Issue a warning message with explicit control over all warning attributes. " -"This is a straightforward wrapper around the Python function :func:`warnings." -"warn_explicit`; see there for more information. The *module* and *registry* " -"arguments may be set to ``NULL`` to get the default effect described there." -msgstr "" - -#: ../../c-api/exceptions.rst:408 -msgid "" -"Similar to :c:func:`PyErr_WarnExplicitObject` except that *message* and " -"*module* are UTF-8 encoded strings, and *filename* is decoded from the :term:" -"`filesystem encoding and error handler`." -msgstr "" - -#: ../../c-api/exceptions.rst:415 -msgid "" -"Function similar to :c:func:`PyErr_WarnEx`, but use :c:func:" -"`PyUnicode_FromFormat` to format the warning message. *format* is an ASCII-" -"encoded string." -msgstr "" - -#: ../../c-api/exceptions.rst:424 -msgid "" -"Similar to :c:func:`PyErr_WarnExplicit`, but uses :c:func:" -"`PyUnicode_FromFormat` to format the warning message. *format* is an ASCII-" -"encoded string." -msgstr "" - -#: ../../c-api/exceptions.rst:433 -msgid "" -"Function similar to :c:func:`PyErr_WarnFormat`, but *category* is :exc:" -"`ResourceWarning` and it passes *source* to :class:`!warnings." -"WarningMessage`." -msgstr "" - -#: ../../c-api/exceptions.rst:440 -msgid "Querying the error indicator" -msgstr "" - -#: ../../c-api/exceptions.rst:444 -msgid "" -"Test whether the error indicator is set. If set, return the exception " -"*type* (the first argument to the last call to one of the ``PyErr_Set*`` " -"functions or to :c:func:`PyErr_Restore`). If not set, return ``NULL``. You " -"do not own a reference to the return value, so you do not need to :c:func:" -"`Py_DECREF` it." -msgstr "" - -#: ../../c-api/exceptions.rst:450 -msgid "The caller must have an :term:`attached thread state`." -msgstr "" - -#: ../../c-api/exceptions.rst:454 -msgid "" -"Do not compare the return value to a specific exception; use :c:func:" -"`PyErr_ExceptionMatches` instead, shown below. (The comparison could easily " -"fail since the exception may be an instance instead of a class, in the case " -"of a class exception, or it may be a subclass of the expected exception.)" -msgstr "" - -#: ../../c-api/exceptions.rst:462 -msgid "" -"Equivalent to ``PyErr_GivenExceptionMatches(PyErr_Occurred(), exc)``. This " -"should only be called when an exception is actually set; a memory access " -"violation will occur if no exception has been raised." -msgstr "" - -#: ../../c-api/exceptions.rst:469 -msgid "" -"Return true if the *given* exception matches the exception type in *exc*. " -"If *exc* is a class object, this also returns true when *given* is an " -"instance of a subclass. If *exc* is a tuple, all exception types in the " -"tuple (and recursively in subtuples) are searched for a match." -msgstr "" - -#: ../../c-api/exceptions.rst:477 -msgid "" -"Return the exception currently being raised, clearing the error indicator at " -"the same time. Return ``NULL`` if the error indicator is not set." -msgstr "" - -#: ../../c-api/exceptions.rst:480 -msgid "" -"This function is used by code that needs to catch exceptions, or code that " -"needs to save and restore the error indicator temporarily." -msgstr "" - -#: ../../c-api/exceptions.rst:483 ../../c-api/exceptions.rst:527 -msgid "For example::" -msgstr "舉例來說： ::" - -#: ../../c-api/exceptions.rst:485 -msgid "" -"{\n" -" PyObject *exc = PyErr_GetRaisedException();\n" -"\n" -" /* ... code that might produce other errors ... */\n" -"\n" -" PyErr_SetRaisedException(exc);\n" -"}" -msgstr "" -"{\n" -" PyObject *exc = PyErr_GetRaisedException();\n" -"\n" -" /* ... 可能會產生其他錯誤的程式碼 ... */\n" -"\n" -" PyErr_SetRaisedException(exc);\n" -"}" - -#: ../../c-api/exceptions.rst:493 -msgid "" -":c:func:`PyErr_GetHandledException`, to save the exception currently being " -"handled." -msgstr "" - -#: ../../c-api/exceptions.rst:501 -msgid "" -"Set *exc* as the exception currently being raised, clearing the existing " -"exception if one is set." -msgstr "" - -#: ../../c-api/exceptions.rst:506 -msgid "This call steals a reference to *exc*, which must be a valid exception." -msgstr "" - -#: ../../c-api/exceptions.rst:515 -msgid "Use :c:func:`PyErr_GetRaisedException` instead." -msgstr "請改用 :c:func:`PyErr_GetRaisedException`。" - -#: ../../c-api/exceptions.rst:517 -msgid "" -"Retrieve the error indicator into three variables whose addresses are " -"passed. If the error indicator is not set, set all three variables to " -"``NULL``. If it is set, it will be cleared and you own a reference to each " -"object retrieved. The value and traceback object may be ``NULL`` even when " -"the type object is not." -msgstr "" - -#: ../../c-api/exceptions.rst:524 -msgid "" -"This function is normally only used by legacy code that needs to catch " -"exceptions or save and restore the error indicator temporarily." -msgstr "" - -#: ../../c-api/exceptions.rst:529 -msgid "" -"{\n" -" PyObject *type, *value, *traceback;\n" -" PyErr_Fetch(&type, &value, &traceback);\n" -"\n" -" /* ... code that might produce other errors ... */\n" -"\n" -" PyErr_Restore(type, value, traceback);\n" -"}" -msgstr "" -"{\n" -" PyObject *type, *value, *traceback;\n" -" PyErr_Fetch(&type, &value, &traceback);\n" -"\n" -" /* ... 可能會產生其他錯誤的程式碼 ... */\n" -"\n" -" PyErr_Restore(type, value, traceback);\n" -"}" - -#: ../../c-api/exceptions.rst:543 -msgid "Use :c:func:`PyErr_SetRaisedException` instead." -msgstr "請改用 :c:func:`PyErr_SetRaisedException`。" - -#: ../../c-api/exceptions.rst:545 -msgid "" -"Set the error indicator from the three objects, *type*, *value*, and " -"*traceback*, clearing the existing exception if one is set. If the objects " -"are ``NULL``, the error indicator is cleared. Do not pass a ``NULL`` type " -"and non-``NULL`` value or traceback. The exception type should be a class. " -"Do not pass an invalid exception type or value. (Violating these rules will " -"cause subtle problems later.) This call takes away a reference to each " -"object: you must own a reference to each object before the call and after " -"the call you no longer own these references. (If you don't understand this, " -"don't use this function. I warned you.)" -msgstr "" - -#: ../../c-api/exceptions.rst:559 -msgid "" -"This function is normally only used by legacy code that needs to save and " -"restore the error indicator temporarily. Use :c:func:`PyErr_Fetch` to save " -"the current error indicator." -msgstr "" - -#: ../../c-api/exceptions.rst:568 -msgid "" -"Use :c:func:`PyErr_GetRaisedException` instead, to avoid any possible de-" -"normalization." -msgstr "" - -#: ../../c-api/exceptions.rst:571 -msgid "" -"Under certain circumstances, the values returned by :c:func:`PyErr_Fetch` " -"below can be \"unnormalized\", meaning that ``*exc`` is a class object but " -"``*val`` is not an instance of the same class. This function can be used " -"to instantiate the class in that case. If the values are already " -"normalized, nothing happens. The delayed normalization is implemented to " -"improve performance." -msgstr "" - -#: ../../c-api/exceptions.rst:579 -msgid "" -"This function *does not* implicitly set the :attr:`~BaseException." -"__traceback__` attribute on the exception value. If setting the traceback " -"appropriately is desired, the following additional snippet is needed::" -msgstr "" - -#: ../../c-api/exceptions.rst:584 -msgid "" -"if (tb != NULL) {\n" -" PyException_SetTraceback(val, tb);\n" -"}" -msgstr "" -"if (tb != NULL) {\n" -" PyException_SetTraceback(val, tb);\n" -"}" - -#: ../../c-api/exceptions.rst:591 -msgid "" -"Retrieve the active exception instance, as would be returned by :func:`sys." -"exception`. This refers to an exception that was *already caught*, not to an " -"exception that was freshly raised. Returns a new reference to the exception " -"or ``NULL``. Does not modify the interpreter's exception state." -msgstr "" - -#: ../../c-api/exceptions.rst:598 -msgid "" -"This function is not normally used by code that wants to handle exceptions. " -"Rather, it can be used when code needs to save and restore the exception " -"state temporarily. Use :c:func:`PyErr_SetHandledException` to restore or " -"clear the exception state." -msgstr "" - -#: ../../c-api/exceptions.rst:607 -msgid "" -"Set the active exception, as known from ``sys.exception()``. This refers to " -"an exception that was *already caught*, not to an exception that was freshly " -"raised. To clear the exception state, pass ``NULL``." -msgstr "" - -#: ../../c-api/exceptions.rst:614 -msgid "" -"This function is not normally used by code that wants to handle exceptions. " -"Rather, it can be used when code needs to save and restore the exception " -"state temporarily. Use :c:func:`PyErr_GetHandledException` to get the " -"exception state." -msgstr "" - -#: ../../c-api/exceptions.rst:623 -msgid "" -"Retrieve the old-style representation of the exception info, as known from :" -"func:`sys.exc_info`. This refers to an exception that was *already caught*, " -"not to an exception that was freshly raised. Returns new references for the " -"three objects, any of which may be ``NULL``. Does not modify the exception " -"info state. This function is kept for backwards compatibility. Prefer " -"using :c:func:`PyErr_GetHandledException`." -msgstr "" - -#: ../../c-api/exceptions.rst:632 -msgid "" -"This function is not normally used by code that wants to handle exceptions. " -"Rather, it can be used when code needs to save and restore the exception " -"state temporarily. Use :c:func:`PyErr_SetExcInfo` to restore or clear the " -"exception state." -msgstr "" - -#: ../../c-api/exceptions.rst:642 -msgid "" -"Set the exception info, as known from ``sys.exc_info()``. This refers to an " -"exception that was *already caught*, not to an exception that was freshly " -"raised. This function steals the references of the arguments. To clear the " -"exception state, pass ``NULL`` for all three arguments. This function is " -"kept for backwards compatibility. Prefer using :c:func:" -"`PyErr_SetHandledException`." -msgstr "" - -#: ../../c-api/exceptions.rst:651 -msgid "" -"This function is not normally used by code that wants to handle exceptions. " -"Rather, it can be used when code needs to save and restore the exception " -"state temporarily. Use :c:func:`PyErr_GetExcInfo` to read the exception " -"state." -msgstr "" - -#: ../../c-api/exceptions.rst:658 -msgid "" -"The ``type`` and ``traceback`` arguments are no longer used and can be NULL. " -"The interpreter now derives them from the exception instance (the ``value`` " -"argument). The function still steals references of all three arguments." -msgstr "" - -#: ../../c-api/exceptions.rst:666 -msgid "Signal Handling" -msgstr "訊號處理" - -#: ../../c-api/exceptions.rst:676 -msgid "This function interacts with Python's signal handling." -msgstr "" - -#: ../../c-api/exceptions.rst:678 -msgid "" -"If the function is called from the main thread and under the main Python " -"interpreter, it checks whether a signal has been sent to the processes and " -"if so, invokes the corresponding signal handler. If the :mod:`signal` " -"module is supported, this can invoke a signal handler written in Python." -msgstr "" - -#: ../../c-api/exceptions.rst:683 -msgid "" -"The function attempts to handle all pending signals, and then returns ``0``. " -"However, if a Python signal handler raises an exception, the error indicator " -"is set and the function returns ``-1`` immediately (such that other pending " -"signals may not have been handled yet: they will be on the next :c:func:" -"`PyErr_CheckSignals()` invocation)." -msgstr "" - -#: ../../c-api/exceptions.rst:689 -msgid "" -"If the function is called from a non-main thread, or under a non-main Python " -"interpreter, it does nothing and returns ``0``." -msgstr "" - -#: ../../c-api/exceptions.rst:692 -msgid "" -"This function can be called by long-running C code that wants to be " -"interruptible by user requests (such as by pressing Ctrl-C)." -msgstr "" - -#: ../../c-api/exceptions.rst:696 -msgid "" -"The default Python signal handler for :c:macro:`!SIGINT` raises the :exc:" -"`KeyboardInterrupt` exception." -msgstr "" - -#: ../../c-api/exceptions.rst:707 -msgid "" -"Simulate the effect of a :c:macro:`!SIGINT` signal arriving. This is " -"equivalent to ``PyErr_SetInterruptEx(SIGINT)``." -msgstr "" - -#: ../../c-api/exceptions.rst:711 ../../c-api/exceptions.rst:738 -msgid "" -"This function is async-signal-safe. It can be called without an :term:" -"`attached thread state` and from a C signal handler." -msgstr "" - -#: ../../c-api/exceptions.rst:721 -msgid "" -"Simulate the effect of a signal arriving. The next time :c:func:" -"`PyErr_CheckSignals` is called, the Python signal handler for the given " -"signal number will be called." -msgstr "" - -#: ../../c-api/exceptions.rst:725 -msgid "" -"This function can be called by C code that sets up its own signal handling " -"and wants Python signal handlers to be invoked as expected when an " -"interruption is requested (for example when the user presses Ctrl-C to " -"interrupt an operation)." -msgstr "" - -#: ../../c-api/exceptions.rst:730 -msgid "" -"If the given signal isn't handled by Python (it was set to :py:const:`signal." -"SIG_DFL` or :py:const:`signal.SIG_IGN`), it will be ignored." -msgstr "" - -#: ../../c-api/exceptions.rst:733 -msgid "" -"If *signum* is outside of the allowed range of signal numbers, ``-1`` is " -"returned. Otherwise, ``0`` is returned. The error indicator is never " -"changed by this function." -msgstr "" - -#: ../../c-api/exceptions.rst:746 -msgid "" -"This utility function specifies a file descriptor to which the signal number " -"is written as a single byte whenever a signal is received. *fd* must be non-" -"blocking. It returns the previous such file descriptor." -msgstr "" - -#: ../../c-api/exceptions.rst:750 -msgid "" -"The value ``-1`` disables the feature; this is the initial state. This is " -"equivalent to :func:`signal.set_wakeup_fd` in Python, but without any error " -"checking. *fd* should be a valid file descriptor. The function should only " -"be called from the main thread." -msgstr "" - -#: ../../c-api/exceptions.rst:755 -msgid "On Windows, the function now also supports socket handles." -msgstr "" - -#: ../../c-api/exceptions.rst:760 -msgid "Exception Classes" -msgstr "例外類別" - -#: ../../c-api/exceptions.rst:764 -msgid "" -"This utility function creates and returns a new exception class. The *name* " -"argument must be the name of the new exception, a C string of the form " -"``module.classname``. The *base* and *dict* arguments are normally " -"``NULL``. This creates a class object derived from :exc:`Exception` " -"(accessible in C as :c:data:`PyExc_Exception`)." -msgstr "" - -#: ../../c-api/exceptions.rst:770 -msgid "" -"The :attr:`~type.__module__` attribute of the new class is set to the first " -"part (up to the last dot) of the *name* argument, and the class name is set " -"to the last part (after the last dot). The *base* argument can be used to " -"specify alternate base classes; it can either be only one class or a tuple " -"of classes. The *dict* argument can be used to specify a dictionary of class " -"variables and methods." -msgstr "" - -#: ../../c-api/exceptions.rst:779 -msgid "" -"Same as :c:func:`PyErr_NewException`, except that the new exception class " -"can easily be given a docstring: If *doc* is non-``NULL``, it will be used " -"as the docstring for the exception class." -msgstr "" - -#: ../../c-api/exceptions.rst:788 -msgid "" -"Return non-zero if *ob* is an exception class, zero otherwise. This function " -"always succeeds." -msgstr "" - -#: ../../c-api/exceptions.rst:793 -msgid "Return :c:member:`~PyTypeObject.tp_name` of the exception class *ob*." -msgstr "回傳例外類別 *ob* 的 :c:member:`~PyTypeObject.tp_name`。" - -#: ../../c-api/exceptions.rst:797 -msgid "Exception Objects" -msgstr "例外物件" - -#: ../../c-api/exceptions.rst:801 -msgid "" -"Return true if *op* is an instance of :class:`BaseException`, false " -"otherwise. This function always succeeds." -msgstr "" - -#: ../../c-api/exceptions.rst:807 -msgid "Equivalent to :c:func:`Py_TYPE(op) `." -msgstr "" - -#: ../../c-api/exceptions.rst:812 -msgid "" -"Return the traceback associated with the exception as a new reference, as " -"accessible from Python through the :attr:`~BaseException.__traceback__` " -"attribute. If there is no traceback associated, this returns ``NULL``." -msgstr "" - -#: ../../c-api/exceptions.rst:820 -msgid "" -"Set the traceback associated with the exception to *tb*. Use ``Py_None`` to " -"clear it." -msgstr "" - -#: ../../c-api/exceptions.rst:826 -msgid "" -"Return the context (another exception instance during whose handling *ex* " -"was raised) associated with the exception as a new reference, as accessible " -"from Python through the :attr:`~BaseException.__context__` attribute. If " -"there is no context associated, this returns ``NULL``." -msgstr "" - -#: ../../c-api/exceptions.rst:834 -msgid "" -"Set the context associated with the exception to *ctx*. Use ``NULL`` to " -"clear it. There is no type check to make sure that *ctx* is an exception " -"instance. This steals a reference to *ctx*." -msgstr "" - -#: ../../c-api/exceptions.rst:841 -msgid "" -"Return the cause (either an exception instance, or ``None``, set by " -"``raise ... from ...``) associated with the exception as a new reference, as " -"accessible from Python through the :attr:`~BaseException.__cause__` " -"attribute." -msgstr "" - -#: ../../c-api/exceptions.rst:849 -msgid "" -"Set the cause associated with the exception to *cause*. Use ``NULL`` to " -"clear it. There is no type check to make sure that *cause* is either an " -"exception instance or ``None``. This steals a reference to *cause*." -msgstr "" - -#: ../../c-api/exceptions.rst:853 -msgid "" -"The :attr:`~BaseException.__suppress_context__` attribute is implicitly set " -"to ``True`` by this function." -msgstr "" - -#: ../../c-api/exceptions.rst:859 -msgid "Return :attr:`~BaseException.args` of exception *ex*." -msgstr "回傳例外 *ex* 的 :attr:`~BaseException.args`。" - -#: ../../c-api/exceptions.rst:864 -msgid "Set :attr:`~BaseException.args` of exception *ex* to *args*." -msgstr "設定例外 *ex* 的 :attr:`~BaseException.args` 為 *args*。" - -#: ../../c-api/exceptions.rst:868 -msgid "" -"Implement part of the interpreter's implementation of :keyword:`!except*`. " -"*orig* is the original exception that was caught, and *excs* is the list of " -"the exceptions that need to be raised. This list contains the unhandled part " -"of *orig*, if any, as well as the exceptions that were raised from the :" -"keyword:`!except*` clauses (so they have a different traceback from *orig*) " -"and those that were reraised (and have the same traceback as *orig*). Return " -"the :exc:`ExceptionGroup` that needs to be reraised in the end, or ``None`` " -"if there is nothing to reraise." -msgstr "" - -#: ../../c-api/exceptions.rst:882 -msgid "Unicode Exception Objects" -msgstr "Unicode 例外物件" - -#: ../../c-api/exceptions.rst:884 -msgid "" -"The following functions are used to create and modify Unicode exceptions " -"from C." -msgstr "" - -#: ../../c-api/exceptions.rst:888 -msgid "" -"Create a :class:`UnicodeDecodeError` object with the attributes *encoding*, " -"*object*, *length*, *start*, *end* and *reason*. *encoding* and *reason* are " -"UTF-8 encoded strings." -msgstr "" - -#: ../../c-api/exceptions.rst:895 -msgid "Return the *encoding* attribute of the given exception object." -msgstr "" - -#: ../../c-api/exceptions.rst:901 -msgid "Return the *object* attribute of the given exception object." -msgstr "" - -#: ../../c-api/exceptions.rst:907 -msgid "" -"Get the *start* attribute of the given exception object and place it into " -"*\\*start*. *start* must not be ``NULL``. Return ``0`` on success, ``-1`` " -"on failure." -msgstr "" - -#: ../../c-api/exceptions.rst:911 -msgid "" -"If the :attr:`UnicodeError.object` is an empty sequence, the resulting " -"*start* is ``0``. Otherwise, it is clipped to ``[0, len(object) - 1]``." -msgstr "" - -#: ../../c-api/exceptions.rst:914 -msgid ":attr:`UnicodeError.start`" -msgstr ":attr:`UnicodeError.start`" - -#: ../../c-api/exceptions.rst:920 -msgid "" -"Set the *start* attribute of the given exception object to *start*. Return " -"``0`` on success, ``-1`` on failure." -msgstr "" - -#: ../../c-api/exceptions.rst:925 -msgid "" -"While passing a negative *start* does not raise an exception, the " -"corresponding getters will not consider it as a relative offset." -msgstr "" - -#: ../../c-api/exceptions.rst:933 -msgid "" -"Get the *end* attribute of the given exception object and place it into " -"*\\*end*. *end* must not be ``NULL``. Return ``0`` on success, ``-1`` on " -"failure." -msgstr "" - -#: ../../c-api/exceptions.rst:937 -msgid "" -"If the :attr:`UnicodeError.object` is an empty sequence, the resulting *end* " -"is ``0``. Otherwise, it is clipped to ``[1, len(object)]``." -msgstr "" - -#: ../../c-api/exceptions.rst:944 -msgid "" -"Set the *end* attribute of the given exception object to *end*. Return " -"``0`` on success, ``-1`` on failure." -msgstr "" - -#: ../../c-api/exceptions.rst:947 -msgid ":attr:`UnicodeError.end`" -msgstr ":attr:`UnicodeError.end`" - -#: ../../c-api/exceptions.rst:953 -msgid "Return the *reason* attribute of the given exception object." -msgstr "回傳給定例外物件的 *reason* 屬性。" - -#: ../../c-api/exceptions.rst:959 -msgid "" -"Set the *reason* attribute of the given exception object to *reason*. " -"Return ``0`` on success, ``-1`` on failure." -msgstr "" - -#: ../../c-api/exceptions.rst:966 -msgid "Recursion Control" -msgstr "遞迴控制" - -#: ../../c-api/exceptions.rst:968 -msgid "" -"These two functions provide a way to perform safe recursive calls at the C " -"level, both in the core and in extension modules. They are needed if the " -"recursive code does not necessarily invoke Python code (which tracks its " -"recursion depth automatically). They are also not needed for *tp_call* " -"implementations because the :ref:`call protocol ` takes care of " -"recursion handling." -msgstr "" - -#: ../../c-api/exceptions.rst:977 -msgid "Marks a point where a recursive C-level call is about to be performed." -msgstr "" - -#: ../../c-api/exceptions.rst:979 -msgid "" -"The function then checks if the stack limit is reached. If this is the " -"case, a :exc:`RecursionError` is set and a nonzero value is returned. " -"Otherwise, zero is returned." -msgstr "" - -#: ../../c-api/exceptions.rst:983 -msgid "" -"*where* should be a UTF-8 encoded string such as ``\" in instance check\"`` " -"to be concatenated to the :exc:`RecursionError` message caused by the " -"recursion depth limit." -msgstr "" - -#: ../../c-api/exceptions.rst:988 -msgid "The :c:func:`PyUnstable_ThreadState_SetStackProtection` function." -msgstr "" - -#: ../../c-api/exceptions.rst:990 ../../c-api/exceptions.rst:998 -msgid "" -"This function is now also available in the :ref:`limited API `." -msgstr "" - -#: ../../c-api/exceptions.rst:995 -msgid "" -"Ends a :c:func:`Py_EnterRecursiveCall`. Must be called once for each " -"*successful* invocation of :c:func:`Py_EnterRecursiveCall`." -msgstr "" - -#: ../../c-api/exceptions.rst:1001 -msgid "" -"Properly implementing :c:member:`~PyTypeObject.tp_repr` for container types " -"requires special recursion handling. In addition to protecting the stack, :" -"c:member:`~PyTypeObject.tp_repr` also needs to track objects to prevent " -"cycles. The following two functions facilitate this functionality. " -"Effectively, these are the C equivalent to :func:`reprlib.recursive_repr`." -msgstr "" - -#: ../../c-api/exceptions.rst:1009 -msgid "" -"Called at the beginning of the :c:member:`~PyTypeObject.tp_repr` " -"implementation to detect cycles." -msgstr "" - -#: ../../c-api/exceptions.rst:1012 -msgid "" -"If the object has already been processed, the function returns a positive " -"integer. In that case the :c:member:`~PyTypeObject.tp_repr` implementation " -"should return a string object indicating a cycle. As examples, :class:" -"`dict` objects return ``{...}`` and :class:`list` objects return ``[...]``." -msgstr "" - -#: ../../c-api/exceptions.rst:1018 -msgid "" -"The function will return a negative integer if the recursion limit is " -"reached. In that case the :c:member:`~PyTypeObject.tp_repr` implementation " -"should typically return ``NULL``." -msgstr "" - -#: ../../c-api/exceptions.rst:1022 -msgid "" -"Otherwise, the function returns zero and the :c:member:`~PyTypeObject." -"tp_repr` implementation can continue normally." -msgstr "" - -#: ../../c-api/exceptions.rst:1027 -msgid "" -"Ends a :c:func:`Py_ReprEnter`. Must be called once for each invocation of :" -"c:func:`Py_ReprEnter` that returns zero." -msgstr "" - -#: ../../c-api/exceptions.rst:1032 -msgid "" -"Get the recursion limit for the current interpreter. It can be set with :c:" -"func:`Py_SetRecursionLimit`. The recursion limit prevents the Python " -"interpreter stack from growing infinitely." -msgstr "" - -#: ../../c-api/exceptions.rst:1036 ../../c-api/exceptions.rst:1046 -msgid "" -"This function cannot fail, and the caller must hold an :term:`attached " -"thread state`." -msgstr "" - -#: ../../c-api/exceptions.rst:1040 -msgid ":py:func:`sys.getrecursionlimit`" -msgstr ":py:func:`sys.getrecursionlimit`" - -#: ../../c-api/exceptions.rst:1044 -msgid "Set the recursion limit for the current interpreter." -msgstr "" - -#: ../../c-api/exceptions.rst:1050 -msgid ":py:func:`sys.setrecursionlimit`" -msgstr ":py:func:`sys.setrecursionlimit`" - -#: ../../c-api/exceptions.rst:1055 -msgid "Exception and warning types" -msgstr "例外和警告型別" - -#: ../../c-api/exceptions.rst:1057 -msgid "" -"All standard Python exceptions and warning categories are available as " -"global variables whose names are ``PyExc_`` followed by the Python exception " -"name. These have the type :c:expr:`PyObject*`; they are all class objects." -msgstr "" - -#: ../../c-api/exceptions.rst:1061 -msgid "For completeness, here are all the variables:" -msgstr "" - -#: ../../c-api/exceptions.rst:1064 -msgid "Exception types" -msgstr "例外型別" - -#: ../../c-api/exceptions.rst:1071 ../../c-api/exceptions.rst:1217 -#: ../../c-api/exceptions.rst:1247 -msgid "C name" -msgstr "C 名稱" - -#: ../../c-api/exceptions.rst:1072 ../../c-api/exceptions.rst:1218 -#: ../../c-api/exceptions.rst:1248 -msgid "Python name" -msgstr "Python 名稱" - -#: ../../c-api/exceptions.rst:1074 -msgid ":exc:`BaseException`" -msgstr ":exc:`BaseException`" - -#: ../../c-api/exceptions.rst:1076 -msgid ":exc:`BaseExceptionGroup`" -msgstr ":exc:`BaseExceptionGroup`" - -#: ../../c-api/exceptions.rst:1078 -msgid ":exc:`Exception`" -msgstr ":exc:`Exception`" - -#: ../../c-api/exceptions.rst:1080 -msgid ":exc:`ArithmeticError`" -msgstr ":exc:`ArithmeticError`" - -#: ../../c-api/exceptions.rst:1082 -msgid ":exc:`AssertionError`" -msgstr ":exc:`AssertionError`" - -#: ../../c-api/exceptions.rst:1084 -msgid ":exc:`AttributeError`" -msgstr ":exc:`AttributeError`" - -#: ../../c-api/exceptions.rst:1086 -msgid ":exc:`BlockingIOError`" -msgstr ":exc:`BlockingIOError`" - -#: ../../c-api/exceptions.rst:1088 -msgid ":exc:`BrokenPipeError`" -msgstr ":exc:`BrokenPipeError`" - -#: ../../c-api/exceptions.rst:1090 -msgid ":exc:`BufferError`" -msgstr ":exc:`BufferError`" - -#: ../../c-api/exceptions.rst:1092 -msgid ":exc:`ChildProcessError`" -msgstr ":exc:`ChildProcessError`" - -#: ../../c-api/exceptions.rst:1094 -msgid ":exc:`ConnectionAbortedError`" -msgstr ":exc:`ConnectionAbortedError`" - -#: ../../c-api/exceptions.rst:1096 -msgid ":exc:`ConnectionError`" -msgstr ":exc:`ConnectionError`" - -#: ../../c-api/exceptions.rst:1098 -msgid ":exc:`ConnectionRefusedError`" -msgstr ":exc:`ConnectionRefusedError`" - -#: ../../c-api/exceptions.rst:1100 -msgid ":exc:`ConnectionResetError`" -msgstr ":exc:`ConnectionResetError`" - -#: ../../c-api/exceptions.rst:1102 -msgid ":exc:`EOFError`" -msgstr ":exc:`EOFError`" - -#: ../../c-api/exceptions.rst:1104 -msgid ":exc:`FileExistsError`" -msgstr ":exc:`FileExistsError`" - -#: ../../c-api/exceptions.rst:1106 -msgid ":exc:`FileNotFoundError`" -msgstr ":exc:`FileNotFoundError`" - -#: ../../c-api/exceptions.rst:1108 -msgid ":exc:`FloatingPointError`" -msgstr ":exc:`FloatingPointError`" - -#: ../../c-api/exceptions.rst:1110 -msgid ":exc:`GeneratorExit`" -msgstr ":exc:`GeneratorExit`" - -#: ../../c-api/exceptions.rst:1112 -msgid ":exc:`ImportError`" -msgstr ":exc:`ImportError`" - -#: ../../c-api/exceptions.rst:1114 -msgid ":exc:`IndentationError`" -msgstr ":exc:`IndentationError`" - -#: ../../c-api/exceptions.rst:1116 -msgid ":exc:`IndexError`" -msgstr ":exc:`IndexError`" - -#: ../../c-api/exceptions.rst:1118 -msgid ":exc:`InterruptedError`" -msgstr ":exc:`InterruptedError`" - -#: ../../c-api/exceptions.rst:1120 -msgid ":exc:`IsADirectoryError`" -msgstr ":exc:`IsADirectoryError`" - -#: ../../c-api/exceptions.rst:1122 -msgid ":exc:`KeyError`" -msgstr ":exc:`KeyError`" - -#: ../../c-api/exceptions.rst:1124 -msgid ":exc:`KeyboardInterrupt`" -msgstr ":exc:`KeyboardInterrupt`" - -#: ../../c-api/exceptions.rst:1126 -msgid ":exc:`LookupError`" -msgstr ":exc:`LookupError`" - -#: ../../c-api/exceptions.rst:1128 -msgid ":exc:`MemoryError`" -msgstr ":exc:`MemoryError`" - -#: ../../c-api/exceptions.rst:1130 -msgid ":exc:`ModuleNotFoundError`" -msgstr ":exc:`ModuleNotFoundError`" - -#: ../../c-api/exceptions.rst:1132 -msgid ":exc:`NameError`" -msgstr ":exc:`NameError`" - -#: ../../c-api/exceptions.rst:1134 -msgid ":exc:`NotADirectoryError`" -msgstr ":exc:`NotADirectoryError`" - -#: ../../c-api/exceptions.rst:1136 -msgid ":exc:`NotImplementedError`" -msgstr ":exc:`NotImplementedError`" - -#: ../../c-api/exceptions.rst:1138 ../../c-api/exceptions.rst:1221 -#: ../../c-api/exceptions.rst:1224 ../../c-api/exceptions.rst:1227 -msgid ":exc:`OSError`" -msgstr ":exc:`OSError`" - -#: ../../c-api/exceptions.rst:1140 -msgid ":exc:`OverflowError`" -msgstr ":exc:`OverflowError`" - -#: ../../c-api/exceptions.rst:1142 -msgid ":exc:`PermissionError`" -msgstr ":exc:`PermissionError`" - -#: ../../c-api/exceptions.rst:1144 -msgid ":exc:`ProcessLookupError`" -msgstr ":exc:`ProcessLookupError`" - -#: ../../c-api/exceptions.rst:1146 -msgid ":exc:`PythonFinalizationError`" -msgstr ":exc:`PythonFinalizationError`" - -#: ../../c-api/exceptions.rst:1148 -msgid ":exc:`RecursionError`" -msgstr ":exc:`RecursionError`" - -#: ../../c-api/exceptions.rst:1150 -msgid ":exc:`ReferenceError`" -msgstr ":exc:`ReferenceError`" - -#: ../../c-api/exceptions.rst:1152 -msgid ":exc:`RuntimeError`" -msgstr ":exc:`RuntimeError`" - -#: ../../c-api/exceptions.rst:1154 -msgid ":exc:`StopAsyncIteration`" -msgstr ":exc:`StopAsyncIteration`" - -#: ../../c-api/exceptions.rst:1156 -msgid ":exc:`StopIteration`" -msgstr ":exc:`StopIteration`" - -#: ../../c-api/exceptions.rst:1158 -msgid ":exc:`SyntaxError`" -msgstr ":exc:`SyntaxError`" - -#: ../../c-api/exceptions.rst:1160 -msgid ":exc:`SystemError`" -msgstr ":exc:`SystemError`" - -#: ../../c-api/exceptions.rst:1162 -msgid ":exc:`SystemExit`" -msgstr ":exc:`SystemExit`" - -#: ../../c-api/exceptions.rst:1164 -msgid ":exc:`TabError`" -msgstr ":exc:`TabError`" - -#: ../../c-api/exceptions.rst:1166 -msgid ":exc:`TimeoutError`" -msgstr ":exc:`TimeoutError`" - -#: ../../c-api/exceptions.rst:1168 -msgid ":exc:`TypeError`" -msgstr ":exc:`TypeError`" - -#: ../../c-api/exceptions.rst:1170 -msgid ":exc:`UnboundLocalError`" -msgstr ":exc:`UnboundLocalError`" - -#: ../../c-api/exceptions.rst:1172 -msgid ":exc:`UnicodeDecodeError`" -msgstr ":exc:`UnicodeDecodeError`" - -#: ../../c-api/exceptions.rst:1174 -msgid ":exc:`UnicodeEncodeError`" -msgstr ":exc:`UnicodeEncodeError`" - -#: ../../c-api/exceptions.rst:1176 -msgid ":exc:`UnicodeError`" -msgstr ":exc:`UnicodeError`" - -#: ../../c-api/exceptions.rst:1178 -msgid ":exc:`UnicodeTranslateError`" -msgstr ":exc:`UnicodeTranslateError`" - -#: ../../c-api/exceptions.rst:1180 -msgid ":exc:`ValueError`" -msgstr ":exc:`ValueError`" - -#: ../../c-api/exceptions.rst:1182 -msgid ":exc:`ZeroDivisionError`" -msgstr ":exc:`ZeroDivisionError`" - -#: ../../c-api/exceptions.rst:1184 -msgid "" -":c:data:`PyExc_BlockingIOError`, :c:data:`PyExc_BrokenPipeError`, :c:data:" -"`PyExc_ChildProcessError`, :c:data:`PyExc_ConnectionError`, :c:data:" -"`PyExc_ConnectionAbortedError`, :c:data:`PyExc_ConnectionRefusedError`, :c:" -"data:`PyExc_ConnectionResetError`, :c:data:`PyExc_FileExistsError`, :c:data:" -"`PyExc_FileNotFoundError`, :c:data:`PyExc_InterruptedError`, :c:data:" -"`PyExc_IsADirectoryError`, :c:data:`PyExc_NotADirectoryError`, :c:data:" -"`PyExc_PermissionError`, :c:data:`PyExc_ProcessLookupError` and :c:data:" -"`PyExc_TimeoutError` were introduced following :pep:`3151`." -msgstr "" -":c:data:`PyExc_BlockingIOError`, :c:data:`PyExc_BrokenPipeError`, :c:data:" -"`PyExc_ChildProcessError`, :c:data:`PyExc_ConnectionError`, :c:data:" -"`PyExc_ConnectionAbortedError`, :c:data:`PyExc_ConnectionRefusedError`, :c:" -"data:`PyExc_ConnectionResetError`, :c:data:`PyExc_FileExistsError`, :c:data:" -"`PyExc_FileNotFoundError`, :c:data:`PyExc_InterruptedError`, :c:data:" -"`PyExc_IsADirectoryError`, :c:data:`PyExc_NotADirectoryError`, :c:data:" -"`PyExc_PermissionError`, :c:data:`PyExc_ProcessLookupError` 和 :c:data:" -"`PyExc_TimeoutError` 是在 :pep:`3151` 被引入。" - -#: ../../c-api/exceptions.rst:1194 -msgid ":c:data:`PyExc_StopAsyncIteration` and :c:data:`PyExc_RecursionError`." -msgstr ":c:data:`PyExc_StopAsyncIteration` 和 :c:data:`PyExc_RecursionError`。" - -#: ../../c-api/exceptions.rst:1197 -msgid ":c:data:`PyExc_ModuleNotFoundError`." -msgstr ":c:data:`PyExc_ModuleNotFoundError`。" - -#: ../../c-api/exceptions.rst:1200 -msgid ":c:data:`PyExc_BaseExceptionGroup`." -msgstr ":c:data:`PyExc_BaseExceptionGroup`" - -#: ../../c-api/exceptions.rst:1205 -msgid "OSError aliases" -msgstr "OSError 別名" - -#: ../../c-api/exceptions.rst:1207 -msgid "The following are a compatibility aliases to :c:data:`PyExc_OSError`." -msgstr "" - -#: ../../c-api/exceptions.rst:1209 -msgid "These aliases used to be separate exception types." -msgstr "" - -#: ../../c-api/exceptions.rst:1219 -msgid "Notes" -msgstr "註解" - -#: ../../c-api/exceptions.rst:1228 -msgid "[win]_" -msgstr "[win]_" - -#: ../../c-api/exceptions.rst:1230 -msgid "Notes:" -msgstr "註解：" - -#: ../../c-api/exceptions.rst:1233 -msgid "" -":c:var:`!PyExc_WindowsError` is only defined on Windows; protect code that " -"uses this by testing that the preprocessor macro ``MS_WINDOWS`` is defined." -msgstr "" - -#: ../../c-api/exceptions.rst:1240 -msgid "Warning types" -msgstr "警告型別" - -#: ../../c-api/exceptions.rst:1250 -msgid ":exc:`Warning`" -msgstr ":exc:`Warning`" - -#: ../../c-api/exceptions.rst:1252 -msgid ":exc:`BytesWarning`" -msgstr ":exc:`BytesWarning`" - -#: ../../c-api/exceptions.rst:1254 -msgid ":exc:`DeprecationWarning`" -msgstr ":exc:`DeprecationWarning`" - -#: ../../c-api/exceptions.rst:1256 -msgid ":exc:`EncodingWarning`" -msgstr ":exc:`EncodingWarning`" - -#: ../../c-api/exceptions.rst:1258 -msgid ":exc:`FutureWarning`" -msgstr ":exc:`FutureWarning`" - -#: ../../c-api/exceptions.rst:1260 -msgid ":exc:`ImportWarning`" -msgstr ":exc:`ImportWarning`" - -#: ../../c-api/exceptions.rst:1262 -msgid ":exc:`PendingDeprecationWarning`" -msgstr ":exc:`PendingDeprecationWarning`" - -#: ../../c-api/exceptions.rst:1264 -msgid ":exc:`ResourceWarning`" -msgstr ":exc:`ResourceWarning`" - -#: ../../c-api/exceptions.rst:1266 -msgid ":exc:`RuntimeWarning`" -msgstr ":exc:`RuntimeWarning`" - -#: ../../c-api/exceptions.rst:1268 -msgid ":exc:`SyntaxWarning`" -msgstr ":exc:`SyntaxWarning`" - -#: ../../c-api/exceptions.rst:1270 -msgid ":exc:`UnicodeWarning`" -msgstr ":exc:`UnicodeWarning`" - -#: ../../c-api/exceptions.rst:1272 -msgid ":exc:`UserWarning`" -msgstr ":exc:`UserWarning`" - -#: ../../c-api/exceptions.rst:1274 -msgid ":c:data:`PyExc_ResourceWarning`." -msgstr ":c:data:`PyExc_ResourceWarning`。" - -#: ../../c-api/exceptions.rst:1277 -msgid ":c:data:`PyExc_EncodingWarning`." -msgstr ":c:data:`PyExc_EncodingWarning`。" - -#: ../../c-api/exceptions.rst:1282 -msgid "Tracebacks" -msgstr "" - -#: ../../c-api/exceptions.rst:1286 -msgid "" -"Type object for traceback objects. This is available as :class:`types." -"TracebackType` in the Python layer." -msgstr "" - -#: ../../c-api/exceptions.rst:1292 -msgid "" -"Return true if *op* is a traceback object, false otherwise. This function " -"does not account for subtypes." -msgstr "" - -#: ../../c-api/exceptions.rst:1298 -msgid "" -"Replace the :attr:`~BaseException.__traceback__` attribute on the current " -"exception with a new traceback prepending *f* to the existing chain." -msgstr "" - -#: ../../c-api/exceptions.rst:1301 -msgid "Calling this function without an exception set is undefined behavior." -msgstr "" - -#: ../../c-api/exceptions.rst:1303 ../../c-api/exceptions.rst:1311 -msgid "" -"This function returns ``0`` on success, and returns ``-1`` with an exception " -"set on failure." -msgstr "" - -#: ../../c-api/exceptions.rst:1309 -msgid "Write the traceback *tb* into the file *f*." -msgstr "" - -#: ../../c-api/exceptions.rst:183 -msgid "strerror (C function)" -msgstr "strerror（C 函式）" - -#: ../../c-api/exceptions.rst:671 ../../c-api/exceptions.rst:702 -#: ../../c-api/exceptions.rst:717 -msgid "module" -msgstr "module（模組）" - -#: ../../c-api/exceptions.rst:671 ../../c-api/exceptions.rst:702 -#: ../../c-api/exceptions.rst:717 -msgid "signal" -msgstr "signal（訊號）" - -#: ../../c-api/exceptions.rst:671 ../../c-api/exceptions.rst:702 -msgid "SIGINT (C macro)" -msgstr "SIGINT（C 巨集）" - -#: ../../c-api/exceptions.rst:671 ../../c-api/exceptions.rst:702 -#: ../../c-api/exceptions.rst:717 -msgid "KeyboardInterrupt (built-in exception)" -msgstr "KeyboardInterrupt（內建例外）" - -#~ msgid "The caller must hold the GIL." -#~ msgstr "呼叫者必須持有 GIL。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Ching-Lung Chuang, 2015 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-26 00:14+0000\n" +"PO-Revision-Date: 2018-05-23 14:05+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" + +#: ../../c-api/exceptions.rst:8 +msgid "Exception Handling" +msgstr "例外處理" + +#: ../../c-api/exceptions.rst:10 +msgid "" +"The functions described in this chapter will let you handle and raise Python " +"exceptions. It is important to understand some of the basics of Python " +"exception handling. It works somewhat like the POSIX :c:data:`errno` " +"variable: there is a global indicator (per thread) of the last error that " +"occurred. Most C API functions don't clear this on success, but will set it " +"to indicate the cause of the error on failure. Most C API functions also " +"return an error indicator, usually ``NULL`` if they are supposed to return a " +"pointer, or ``-1`` if they return an integer (exception: the ``PyArg_*`` " +"functions return ``1`` for success and ``0`` for failure)." +msgstr "" + +#: ../../c-api/exceptions.rst:20 +msgid "" +"Concretely, the error indicator consists of three object pointers: the " +"exception's type, the exception's value, and the traceback object. Any of " +"those pointers can be ``NULL`` if non-set (although some combinations are " +"forbidden, for example you can't have a non-``NULL`` traceback if the " +"exception type is ``NULL``)." +msgstr "" + +#: ../../c-api/exceptions.rst:26 +msgid "" +"When a function must fail because some function it called failed, it " +"generally doesn't set the error indicator; the function it called already " +"set it. It is responsible for either handling the error and clearing the " +"exception or returning after cleaning up any resources it holds (such as " +"object references or memory allocations); it should *not* continue normally " +"if it is not prepared to handle the error. If returning due to an error, it " +"is important to indicate to the caller that an error has been set. If the " +"error is not handled or carefully propagated, additional calls into the " +"Python/C API may not behave as intended and may fail in mysterious ways." +msgstr "" + +#: ../../c-api/exceptions.rst:37 +msgid "" +"The error indicator is **not** the result of :func:`sys.exc_info`. The " +"former corresponds to an exception that is not yet caught (and is therefore " +"still propagating), while the latter returns an exception after it is caught " +"(and has therefore stopped propagating)." +msgstr "" + +#: ../../c-api/exceptions.rst:44 +msgid "Printing and clearing" +msgstr "" + +#: ../../c-api/exceptions.rst:49 +msgid "" +"Clear the error indicator. If the error indicator is not set, there is no " +"effect." +msgstr "" + +#: ../../c-api/exceptions.rst:55 +msgid "" +"Print a standard traceback to ``sys.stderr`` and clear the error indicator. " +"**Unless** the error is a ``SystemExit``, in that case no traceback is " +"printed and the Python process will exit with the error code specified by " +"the ``SystemExit`` instance." +msgstr "" + +#: ../../c-api/exceptions.rst:60 +msgid "" +"Call this function **only** when the error indicator is set. Otherwise it " +"will cause a fatal error!" +msgstr "" + +#: ../../c-api/exceptions.rst:63 +msgid "" +"If *set_sys_last_vars* is nonzero, the variable :data:`sys.last_exc` is set " +"to the printed exception. For backwards compatibility, the deprecated " +"variables :data:`sys.last_type`, :data:`sys.last_value` and :data:`sys." +"last_traceback` are also set to the type, value and traceback of this " +"exception, respectively." +msgstr "" + +#: ../../c-api/exceptions.rst:69 +msgid "The setting of :data:`sys.last_exc` was added." +msgstr "新增 :data:`sys.last_exc` 設定。" + +#: ../../c-api/exceptions.rst:75 +msgid "Alias for ``PyErr_PrintEx(1)``." +msgstr "``PyErr_PrintEx(1)`` 的別名。" + +#: ../../c-api/exceptions.rst:80 +msgid "" +"Call :func:`sys.unraisablehook` using the current exception and *obj* " +"argument." +msgstr "" + +#: ../../c-api/exceptions.rst:83 +msgid "" +"This utility function prints a warning message to ``sys.stderr`` when an " +"exception has been set but it is impossible for the interpreter to actually " +"raise the exception. It is used, for example, when an exception occurs in " +"an :meth:`~object.__del__` method." +msgstr "" + +#: ../../c-api/exceptions.rst:88 +msgid "" +"The function is called with a single argument *obj* that identifies the " +"context in which the unraisable exception occurred. If possible, the repr of " +"*obj* will be printed in the warning message. If *obj* is ``NULL``, only the " +"traceback is printed." +msgstr "" + +#: ../../c-api/exceptions.rst:93 +msgid "An exception must be set when calling this function." +msgstr "" + +#: ../../c-api/exceptions.rst:95 +msgid "Print a traceback. Print only traceback if *obj* is ``NULL``." +msgstr "" + +#: ../../c-api/exceptions.rst:98 +msgid "Use :func:`sys.unraisablehook`." +msgstr "使用 :func:`sys.unraisablehook`。" + +#: ../../c-api/exceptions.rst:104 +msgid "" +"Similar to :c:func:`PyErr_WriteUnraisable`, but the *format* and subsequent " +"parameters help format the warning message; they have the same meaning and " +"values as in :c:func:`PyUnicode_FromFormat`. ``PyErr_WriteUnraisable(obj)`` " +"is roughly equivalent to ``PyErr_FormatUnraisable(\"Exception ignored in: " +"%R\", obj)``. If *format* is ``NULL``, only the traceback is printed." +msgstr "" + +#: ../../c-api/exceptions.rst:116 +msgid "" +"Print the standard traceback display of ``exc`` to ``sys.stderr``, including " +"chained exceptions and notes." +msgstr "" + +#: ../../c-api/exceptions.rst:123 +msgid "Raising exceptions" +msgstr "引發例外" + +#: ../../c-api/exceptions.rst:125 +msgid "" +"These functions help you set the current thread's error indicator. For " +"convenience, some of these functions will always return a ``NULL`` pointer " +"for use in a ``return`` statement." +msgstr "" + +#: ../../c-api/exceptions.rst:132 +msgid "" +"This is the most common way to set the error indicator. The first argument " +"specifies the exception type; it is normally one of the standard exceptions, " +"e.g. :c:data:`PyExc_RuntimeError`. You need not create a new :term:`strong " +"reference` to it (e.g. with :c:func:`Py_INCREF`). The second argument is an " +"error message; it is decoded from ``'utf-8'``." +msgstr "" + +#: ../../c-api/exceptions.rst:141 +msgid "" +"This function is similar to :c:func:`PyErr_SetString` but lets you specify " +"an arbitrary Python object for the \"value\" of the exception." +msgstr "" + +#: ../../c-api/exceptions.rst:147 +msgid "" +"This function sets the error indicator and returns ``NULL``. *exception* " +"should be a Python exception class. The *format* and subsequent parameters " +"help format the error message; they have the same meaning and values as in :" +"c:func:`PyUnicode_FromFormat`. *format* is an ASCII-encoded string." +msgstr "" + +#: ../../c-api/exceptions.rst:156 +msgid "" +"Same as :c:func:`PyErr_Format`, but taking a :c:type:`va_list` argument " +"rather than a variable number of arguments." +msgstr "" + +#: ../../c-api/exceptions.rst:164 +msgid "This is a shorthand for ``PyErr_SetObject(type, Py_None)``." +msgstr "" + +#: ../../c-api/exceptions.rst:169 +msgid "" +"This is a shorthand for ``PyErr_SetString(PyExc_TypeError, message)``, where " +"*message* indicates that a built-in operation was invoked with an illegal " +"argument. It is mostly for internal use." +msgstr "" + +#: ../../c-api/exceptions.rst:176 +msgid "" +"This is a shorthand for ``PyErr_SetNone(PyExc_MemoryError)``; it returns " +"``NULL`` so an object allocation function can write ``return " +"PyErr_NoMemory();`` when it runs out of memory." +msgstr "" + +#: ../../c-api/exceptions.rst:185 +msgid "" +"This is a convenience function to raise an exception when a C library " +"function has returned an error and set the C variable :c:data:`errno`. It " +"constructs a tuple object whose first item is the integer :c:data:`errno` " +"value and whose second item is the corresponding error message (gotten from :" +"c:func:`!strerror`), and then calls ``PyErr_SetObject(type, object)``. On " +"Unix, when the :c:data:`errno` value is :c:macro:`!EINTR`, indicating an " +"interrupted system call, this calls :c:func:`PyErr_CheckSignals`, and if " +"that set the error indicator, leaves it set to that. The function always " +"returns ``NULL``, so a wrapper function around a system call can write " +"``return PyErr_SetFromErrno(type);`` when the system call returns an error." +msgstr "" + +#: ../../c-api/exceptions.rst:199 +msgid "" +"Similar to :c:func:`PyErr_SetFromErrno`, with the additional behavior that " +"if *filenameObject* is not ``NULL``, it is passed to the constructor of " +"*type* as a third parameter. In the case of :exc:`OSError` exception, this " +"is used to define the :attr:`!filename` attribute of the exception instance." +msgstr "" + +#: ../../c-api/exceptions.rst:208 +msgid "" +"Similar to :c:func:`PyErr_SetFromErrnoWithFilenameObject`, but takes a " +"second filename object, for raising errors when a function that takes two " +"filenames fails." +msgstr "" + +#: ../../c-api/exceptions.rst:217 +msgid "" +"Similar to :c:func:`PyErr_SetFromErrnoWithFilenameObject`, but the filename " +"is given as a C string. *filename* is decoded from the :term:`filesystem " +"encoding and error handler`." +msgstr "" + +#: ../../c-api/exceptions.rst:224 +msgid "" +"This is a convenience function to raise :exc:`OSError`. If called with " +"*ierr* of ``0``, the error code returned by a call to :c:func:`!" +"GetLastError` is used instead. It calls the Win32 function :c:func:`!" +"FormatMessage` to retrieve the Windows description of error code given by " +"*ierr* or :c:func:`!GetLastError`, then it constructs a :exc:`OSError` " +"object with the :attr:`~OSError.winerror` attribute set to the error code, " +"the :attr:`~OSError.strerror` attribute set to the corresponding error " +"message (gotten from :c:func:`!FormatMessage`), and then calls " +"``PyErr_SetObject(PyExc_OSError, object)``. This function always returns " +"``NULL``." +msgstr "" + +#: ../../c-api/exceptions.rst:234 ../../c-api/exceptions.rst:242 +#: ../../c-api/exceptions.rst:253 ../../c-api/exceptions.rst:263 +#: ../../c-api/exceptions.rst:271 ../../c-api/exceptions.rst:281 +msgid "Availability" +msgstr "可用性" + +#: ../../c-api/exceptions.rst:239 +msgid "" +"Similar to :c:func:`PyErr_SetFromWindowsErr`, with an additional parameter " +"specifying the exception type to be raised." +msgstr "" + +#: ../../c-api/exceptions.rst:247 +msgid "" +"Similar to :c:func:`PyErr_SetFromWindowsErr`, with the additional behavior " +"that if *filename* is not ``NULL``, it is decoded from the filesystem " +"encoding (:func:`os.fsdecode`) and passed to the constructor of :exc:" +"`OSError` as a third parameter to be used to define the :attr:`!filename` " +"attribute of the exception instance." +msgstr "" + +#: ../../c-api/exceptions.rst:258 +msgid "" +"Similar to :c:func:`PyErr_SetExcFromWindowsErr`, with the additional " +"behavior that if *filename* is not ``NULL``, it is passed to the constructor " +"of :exc:`OSError` as a third parameter to be used to define the :attr:`!" +"filename` attribute of the exception instance." +msgstr "" + +#: ../../c-api/exceptions.rst:268 +msgid "" +"Similar to :c:func:`PyErr_SetExcFromWindowsErrWithFilenameObject`, but " +"accepts a second filename object." +msgstr "" + +#: ../../c-api/exceptions.rst:278 +msgid "" +"Similar to :c:func:`PyErr_SetFromWindowsErrWithFilename`, with an additional " +"parameter specifying the exception type to be raised." +msgstr "" + +#: ../../c-api/exceptions.rst:286 +msgid "" +"This is a convenience function to raise :exc:`ImportError`. *msg* will be " +"set as the exception's message string. *name* and *path*, both of which can " +"be ``NULL``, will be set as the :exc:`ImportError`'s respective ``name`` and " +"``path`` attributes." +msgstr "" + +#: ../../c-api/exceptions.rst:296 +msgid "" +"Much like :c:func:`PyErr_SetImportError` but this function allows for " +"specifying a subclass of :exc:`ImportError` to raise." +msgstr "" + +#: ../../c-api/exceptions.rst:304 +msgid "" +"Set file, line, and offset information for the current exception. If the " +"current exception is not a :exc:`SyntaxError`, then it sets additional " +"attributes, which make the exception printing subsystem think the exception " +"is a :exc:`SyntaxError`." +msgstr "" + +#: ../../c-api/exceptions.rst:314 +msgid "" +"Similar to :c:func:`PyErr_SyntaxLocationObject`, but also sets the " +"*end_lineno* and *end_col_offset* information for the current exception." +msgstr "" + +#: ../../c-api/exceptions.rst:322 +msgid "" +"Like :c:func:`PyErr_SyntaxLocationObject`, but *filename* is a byte string " +"decoded from the :term:`filesystem encoding and error handler`." +msgstr "" + +#: ../../c-api/exceptions.rst:330 +msgid "" +"Like :c:func:`PyErr_SyntaxLocationEx`, but the *col_offset* parameter is " +"omitted." +msgstr "" + +#: ../../c-api/exceptions.rst:336 +msgid "" +"This is a shorthand for ``PyErr_SetString(PyExc_SystemError, message)``, " +"where *message* indicates that an internal operation (e.g. a Python/C API " +"function) was invoked with an illegal argument. It is mostly for internal " +"use." +msgstr "" + +#: ../../c-api/exceptions.rst:344 +msgid "" +"Get the source line in *filename* at line *lineno*. *filename* should be a " +"Python :class:`str` object." +msgstr "" + +#: ../../c-api/exceptions.rst:347 +msgid "" +"On success, this function returns a Python string object with the found " +"line. On failure, this function returns ``NULL`` without an exception set." +msgstr "" + +#: ../../c-api/exceptions.rst:353 +msgid "" +"Similar to :c:func:`PyErr_ProgramTextObject`, but *filename* is a :c:expr:" +"`const char *`, which is decoded with the :term:`filesystem encoding and " +"error handler`, instead of a Python object reference." +msgstr "" + +#: ../../c-api/exceptions.rst:360 +msgid "Issuing warnings" +msgstr "發出警告" + +#: ../../c-api/exceptions.rst:362 +msgid "" +"Use these functions to issue warnings from C code. They mirror similar " +"functions exported by the Python :mod:`warnings` module. They normally " +"print a warning message to *sys.stderr*; however, it is also possible that " +"the user has specified that warnings are to be turned into errors, and in " +"that case they will raise an exception. It is also possible that the " +"functions raise an exception because of a problem with the warning " +"machinery. The return value is ``0`` if no exception is raised, or ``-1`` if " +"an exception is raised. (It is not possible to determine whether a warning " +"message is actually printed, nor what the reason is for the exception; this " +"is intentional.) If an exception is raised, the caller should do its normal " +"exception handling (for example, :c:func:`Py_DECREF` owned references and " +"return an error value)." +msgstr "" + +#: ../../c-api/exceptions.rst:377 +msgid "" +"Issue a warning message. The *category* argument is a warning category (see " +"below) or ``NULL``; the *message* argument is a UTF-8 encoded string. " +"*stack_level* is a positive number giving a number of stack frames; the " +"warning will be issued from the currently executing line of code in that " +"stack frame. A *stack_level* of 1 is the function calling :c:func:" +"`PyErr_WarnEx`, 2 is the function above that, and so forth." +msgstr "" + +#: ../../c-api/exceptions.rst:384 +msgid "" +"Warning categories must be subclasses of :c:data:`PyExc_Warning`; :c:data:" +"`PyExc_Warning` is a subclass of :c:data:`PyExc_Exception`; the default " +"warning category is :c:data:`PyExc_RuntimeWarning`. The standard Python " +"warning categories are available as global variables whose names are " +"enumerated at :ref:`standardwarningcategories`." +msgstr "" + +#: ../../c-api/exceptions.rst:390 +msgid "" +"For information about warning control, see the documentation for the :mod:" +"`warnings` module and the :option:`-W` option in the command line " +"documentation. There is no C API for warning control." +msgstr "" + +#: ../../c-api/exceptions.rst:397 +msgid "" +"Issue a warning message with explicit control over all warning attributes. " +"This is a straightforward wrapper around the Python function :func:`warnings." +"warn_explicit`; see there for more information. The *module* and *registry* " +"arguments may be set to ``NULL`` to get the default effect described there." +msgstr "" + +#: ../../c-api/exceptions.rst:408 +msgid "" +"Similar to :c:func:`PyErr_WarnExplicitObject` except that *message* and " +"*module* are UTF-8 encoded strings, and *filename* is decoded from the :term:" +"`filesystem encoding and error handler`." +msgstr "" + +#: ../../c-api/exceptions.rst:415 +msgid "" +"Function similar to :c:func:`PyErr_WarnEx`, but use :c:func:" +"`PyUnicode_FromFormat` to format the warning message. *format* is an ASCII-" +"encoded string." +msgstr "" + +#: ../../c-api/exceptions.rst:424 +msgid "" +"Similar to :c:func:`PyErr_WarnExplicit`, but uses :c:func:" +"`PyUnicode_FromFormat` to format the warning message. *format* is an ASCII-" +"encoded string." +msgstr "" + +#: ../../c-api/exceptions.rst:433 +msgid "" +"Function similar to :c:func:`PyErr_WarnFormat`, but *category* is :exc:" +"`ResourceWarning` and it passes *source* to :class:`!warnings." +"WarningMessage`." +msgstr "" + +#: ../../c-api/exceptions.rst:440 +msgid "Querying the error indicator" +msgstr "" + +#: ../../c-api/exceptions.rst:444 +msgid "" +"Test whether the error indicator is set. If set, return the exception " +"*type* (the first argument to the last call to one of the ``PyErr_Set*`` " +"functions or to :c:func:`PyErr_Restore`). If not set, return ``NULL``. You " +"do not own a reference to the return value, so you do not need to :c:func:" +"`Py_DECREF` it." +msgstr "" + +#: ../../c-api/exceptions.rst:450 +msgid "The caller must have an :term:`attached thread state`." +msgstr "" + +#: ../../c-api/exceptions.rst:454 +msgid "" +"Do not compare the return value to a specific exception; use :c:func:" +"`PyErr_ExceptionMatches` instead, shown below. (The comparison could easily " +"fail since the exception may be an instance instead of a class, in the case " +"of a class exception, or it may be a subclass of the expected exception.)" +msgstr "" + +#: ../../c-api/exceptions.rst:462 +msgid "" +"Equivalent to ``PyErr_GivenExceptionMatches(PyErr_Occurred(), exc)``. This " +"should only be called when an exception is actually set; a memory access " +"violation will occur if no exception has been raised." +msgstr "" + +#: ../../c-api/exceptions.rst:469 +msgid "" +"Return true if the *given* exception matches the exception type in *exc*. " +"If *exc* is a class object, this also returns true when *given* is an " +"instance of a subclass. If *exc* is a tuple, all exception types in the " +"tuple (and recursively in subtuples) are searched for a match." +msgstr "" + +#: ../../c-api/exceptions.rst:477 +msgid "" +"Return the exception currently being raised, clearing the error indicator at " +"the same time. Return ``NULL`` if the error indicator is not set." +msgstr "" + +#: ../../c-api/exceptions.rst:480 +msgid "" +"This function is used by code that needs to catch exceptions, or code that " +"needs to save and restore the error indicator temporarily." +msgstr "" + +#: ../../c-api/exceptions.rst:483 ../../c-api/exceptions.rst:527 +msgid "For example::" +msgstr "舉例來說： ::" + +#: ../../c-api/exceptions.rst:485 +msgid "" +"{\n" +" PyObject *exc = PyErr_GetRaisedException();\n" +"\n" +" /* ... code that might produce other errors ... */\n" +"\n" +" PyErr_SetRaisedException(exc);\n" +"}" +msgstr "" +"{\n" +" PyObject *exc = PyErr_GetRaisedException();\n" +"\n" +" /* ... 可能會產生其他錯誤的程式碼 ... */\n" +"\n" +" PyErr_SetRaisedException(exc);\n" +"}" + +#: ../../c-api/exceptions.rst:493 +msgid "" +":c:func:`PyErr_GetHandledException`, to save the exception currently being " +"handled." +msgstr "" + +#: ../../c-api/exceptions.rst:501 +msgid "" +"Set *exc* as the exception currently being raised, clearing the existing " +"exception if one is set." +msgstr "" + +#: ../../c-api/exceptions.rst:506 +msgid "This call steals a reference to *exc*, which must be a valid exception." +msgstr "" + +#: ../../c-api/exceptions.rst:515 +msgid "Use :c:func:`PyErr_GetRaisedException` instead." +msgstr "請改用 :c:func:`PyErr_GetRaisedException`。" + +#: ../../c-api/exceptions.rst:517 +msgid "" +"Retrieve the error indicator into three variables whose addresses are " +"passed. If the error indicator is not set, set all three variables to " +"``NULL``. If it is set, it will be cleared and you own a reference to each " +"object retrieved. The value and traceback object may be ``NULL`` even when " +"the type object is not." +msgstr "" + +#: ../../c-api/exceptions.rst:524 +msgid "" +"This function is normally only used by legacy code that needs to catch " +"exceptions or save and restore the error indicator temporarily." +msgstr "" + +#: ../../c-api/exceptions.rst:529 +msgid "" +"{\n" +" PyObject *type, *value, *traceback;\n" +" PyErr_Fetch(&type, &value, &traceback);\n" +"\n" +" /* ... code that might produce other errors ... */\n" +"\n" +" PyErr_Restore(type, value, traceback);\n" +"}" +msgstr "" +"{\n" +" PyObject *type, *value, *traceback;\n" +" PyErr_Fetch(&type, &value, &traceback);\n" +"\n" +" /* ... 可能會產生其他錯誤的程式碼 ... */\n" +"\n" +" PyErr_Restore(type, value, traceback);\n" +"}" + +#: ../../c-api/exceptions.rst:543 +msgid "Use :c:func:`PyErr_SetRaisedException` instead." +msgstr "請改用 :c:func:`PyErr_SetRaisedException`。" + +#: ../../c-api/exceptions.rst:545 +msgid "" +"Set the error indicator from the three objects, *type*, *value*, and " +"*traceback*, clearing the existing exception if one is set. If the objects " +"are ``NULL``, the error indicator is cleared. Do not pass a ``NULL`` type " +"and non-``NULL`` value or traceback. The exception type should be a class. " +"Do not pass an invalid exception type or value. (Violating these rules will " +"cause subtle problems later.) This call takes away a reference to each " +"object: you must own a reference to each object before the call and after " +"the call you no longer own these references. (If you don't understand this, " +"don't use this function. I warned you.)" +msgstr "" + +#: ../../c-api/exceptions.rst:559 +msgid "" +"This function is normally only used by legacy code that needs to save and " +"restore the error indicator temporarily. Use :c:func:`PyErr_Fetch` to save " +"the current error indicator." +msgstr "" + +#: ../../c-api/exceptions.rst:568 +msgid "" +"Use :c:func:`PyErr_GetRaisedException` instead, to avoid any possible de-" +"normalization." +msgstr "" + +#: ../../c-api/exceptions.rst:571 +msgid "" +"Under certain circumstances, the values returned by :c:func:`PyErr_Fetch` " +"below can be \"unnormalized\", meaning that ``*exc`` is a class object but " +"``*val`` is not an instance of the same class. This function can be used " +"to instantiate the class in that case. If the values are already " +"normalized, nothing happens. The delayed normalization is implemented to " +"improve performance." +msgstr "" + +#: ../../c-api/exceptions.rst:579 +msgid "" +"This function *does not* implicitly set the :attr:`~BaseException." +"__traceback__` attribute on the exception value. If setting the traceback " +"appropriately is desired, the following additional snippet is needed::" +msgstr "" + +#: ../../c-api/exceptions.rst:584 +msgid "" +"if (tb != NULL) {\n" +" PyException_SetTraceback(val, tb);\n" +"}" +msgstr "" +"if (tb != NULL) {\n" +" PyException_SetTraceback(val, tb);\n" +"}" + +#: ../../c-api/exceptions.rst:591 +msgid "" +"Retrieve the active exception instance, as would be returned by :func:`sys." +"exception`. This refers to an exception that was *already caught*, not to an " +"exception that was freshly raised. Returns a new reference to the exception " +"or ``NULL``. Does not modify the interpreter's exception state." +msgstr "" + +#: ../../c-api/exceptions.rst:598 +msgid "" +"This function is not normally used by code that wants to handle exceptions. " +"Rather, it can be used when code needs to save and restore the exception " +"state temporarily. Use :c:func:`PyErr_SetHandledException` to restore or " +"clear the exception state." +msgstr "" + +#: ../../c-api/exceptions.rst:607 +msgid "" +"Set the active exception, as known from ``sys.exception()``. This refers to " +"an exception that was *already caught*, not to an exception that was freshly " +"raised. To clear the exception state, pass ``NULL``." +msgstr "" + +#: ../../c-api/exceptions.rst:614 +msgid "" +"This function is not normally used by code that wants to handle exceptions. " +"Rather, it can be used when code needs to save and restore the exception " +"state temporarily. Use :c:func:`PyErr_GetHandledException` to get the " +"exception state." +msgstr "" + +#: ../../c-api/exceptions.rst:623 +msgid "" +"Retrieve the old-style representation of the exception info, as known from :" +"func:`sys.exc_info`. This refers to an exception that was *already caught*, " +"not to an exception that was freshly raised. Returns new references for the " +"three objects, any of which may be ``NULL``. Does not modify the exception " +"info state. This function is kept for backwards compatibility. Prefer " +"using :c:func:`PyErr_GetHandledException`." +msgstr "" + +#: ../../c-api/exceptions.rst:632 +msgid "" +"This function is not normally used by code that wants to handle exceptions. " +"Rather, it can be used when code needs to save and restore the exception " +"state temporarily. Use :c:func:`PyErr_SetExcInfo` to restore or clear the " +"exception state." +msgstr "" + +#: ../../c-api/exceptions.rst:642 +msgid "" +"Set the exception info, as known from ``sys.exc_info()``. This refers to an " +"exception that was *already caught*, not to an exception that was freshly " +"raised. This function steals the references of the arguments. To clear the " +"exception state, pass ``NULL`` for all three arguments. This function is " +"kept for backwards compatibility. Prefer using :c:func:" +"`PyErr_SetHandledException`." +msgstr "" + +#: ../../c-api/exceptions.rst:651 +msgid "" +"This function is not normally used by code that wants to handle exceptions. " +"Rather, it can be used when code needs to save and restore the exception " +"state temporarily. Use :c:func:`PyErr_GetExcInfo` to read the exception " +"state." +msgstr "" + +#: ../../c-api/exceptions.rst:658 +msgid "" +"The ``type`` and ``traceback`` arguments are no longer used and can be NULL. " +"The interpreter now derives them from the exception instance (the ``value`` " +"argument). The function still steals references of all three arguments." +msgstr "" + +#: ../../c-api/exceptions.rst:666 +msgid "Signal Handling" +msgstr "訊號處理" + +#: ../../c-api/exceptions.rst:676 +msgid "This function interacts with Python's signal handling." +msgstr "" + +#: ../../c-api/exceptions.rst:678 +msgid "" +"If the function is called from the main thread and under the main Python " +"interpreter, it checks whether a signal has been sent to the processes and " +"if so, invokes the corresponding signal handler. If the :mod:`signal` " +"module is supported, this can invoke a signal handler written in Python." +msgstr "" + +#: ../../c-api/exceptions.rst:683 +msgid "" +"The function attempts to handle all pending signals, and then returns ``0``. " +"However, if a Python signal handler raises an exception, the error indicator " +"is set and the function returns ``-1`` immediately (such that other pending " +"signals may not have been handled yet: they will be on the next :c:func:" +"`PyErr_CheckSignals()` invocation)." +msgstr "" + +#: ../../c-api/exceptions.rst:689 +msgid "" +"If the function is called from a non-main thread, or under a non-main Python " +"interpreter, it does nothing and returns ``0``." +msgstr "" + +#: ../../c-api/exceptions.rst:692 +msgid "" +"This function can be called by long-running C code that wants to be " +"interruptible by user requests (such as by pressing Ctrl-C)." +msgstr "" + +#: ../../c-api/exceptions.rst:696 +msgid "" +"The default Python signal handler for :c:macro:`!SIGINT` raises the :exc:" +"`KeyboardInterrupt` exception." +msgstr "" + +#: ../../c-api/exceptions.rst:707 +msgid "" +"Simulate the effect of a :c:macro:`!SIGINT` signal arriving. This is " +"equivalent to ``PyErr_SetInterruptEx(SIGINT)``." +msgstr "" + +#: ../../c-api/exceptions.rst:711 ../../c-api/exceptions.rst:738 +msgid "" +"This function is async-signal-safe. It can be called without an :term:" +"`attached thread state` and from a C signal handler." +msgstr "" + +#: ../../c-api/exceptions.rst:721 +msgid "" +"Simulate the effect of a signal arriving. The next time :c:func:" +"`PyErr_CheckSignals` is called, the Python signal handler for the given " +"signal number will be called." +msgstr "" + +#: ../../c-api/exceptions.rst:725 +msgid "" +"This function can be called by C code that sets up its own signal handling " +"and wants Python signal handlers to be invoked as expected when an " +"interruption is requested (for example when the user presses Ctrl-C to " +"interrupt an operation)." +msgstr "" + +#: ../../c-api/exceptions.rst:730 +msgid "" +"If the given signal isn't handled by Python (it was set to :py:const:`signal." +"SIG_DFL` or :py:const:`signal.SIG_IGN`), it will be ignored." +msgstr "" + +#: ../../c-api/exceptions.rst:733 +msgid "" +"If *signum* is outside of the allowed range of signal numbers, ``-1`` is " +"returned. Otherwise, ``0`` is returned. The error indicator is never " +"changed by this function." +msgstr "" + +#: ../../c-api/exceptions.rst:746 +msgid "" +"This utility function specifies a file descriptor to which the signal number " +"is written as a single byte whenever a signal is received. *fd* must be non-" +"blocking. It returns the previous such file descriptor." +msgstr "" + +#: ../../c-api/exceptions.rst:750 +msgid "" +"The value ``-1`` disables the feature; this is the initial state. This is " +"equivalent to :func:`signal.set_wakeup_fd` in Python, but without any error " +"checking. *fd* should be a valid file descriptor. The function should only " +"be called from the main thread." +msgstr "" + +#: ../../c-api/exceptions.rst:755 +msgid "On Windows, the function now also supports socket handles." +msgstr "" + +#: ../../c-api/exceptions.rst:760 +msgid "Exception Classes" +msgstr "例外類別" + +#: ../../c-api/exceptions.rst:764 +msgid "" +"This utility function creates and returns a new exception class. The *name* " +"argument must be the name of the new exception, a C string of the form " +"``module.classname``. The *base* and *dict* arguments are normally " +"``NULL``. This creates a class object derived from :exc:`Exception` " +"(accessible in C as :c:data:`PyExc_Exception`)." +msgstr "" + +#: ../../c-api/exceptions.rst:770 +msgid "" +"The :attr:`~type.__module__` attribute of the new class is set to the first " +"part (up to the last dot) of the *name* argument, and the class name is set " +"to the last part (after the last dot). The *base* argument can be used to " +"specify alternate base classes; it can either be only one class or a tuple " +"of classes. The *dict* argument can be used to specify a dictionary of class " +"variables and methods." +msgstr "" + +#: ../../c-api/exceptions.rst:779 +msgid "" +"Same as :c:func:`PyErr_NewException`, except that the new exception class " +"can easily be given a docstring: If *doc* is non-``NULL``, it will be used " +"as the docstring for the exception class." +msgstr "" + +#: ../../c-api/exceptions.rst:788 +msgid "" +"Return non-zero if *ob* is an exception class, zero otherwise. This function " +"always succeeds." +msgstr "" + +#: ../../c-api/exceptions.rst:793 +msgid "Return :c:member:`~PyTypeObject.tp_name` of the exception class *ob*." +msgstr "回傳例外類別 *ob* 的 :c:member:`~PyTypeObject.tp_name`。" + +#: ../../c-api/exceptions.rst:797 +msgid "Exception Objects" +msgstr "例外物件" + +#: ../../c-api/exceptions.rst:801 +msgid "" +"Return true if *op* is an instance of :class:`BaseException`, false " +"otherwise. This function always succeeds." +msgstr "" + +#: ../../c-api/exceptions.rst:807 +msgid "Equivalent to :c:func:`Py_TYPE(op) `." +msgstr "" + +#: ../../c-api/exceptions.rst:812 +msgid "" +"Return the traceback associated with the exception as a new reference, as " +"accessible from Python through the :attr:`~BaseException.__traceback__` " +"attribute. If there is no traceback associated, this returns ``NULL``." +msgstr "" + +#: ../../c-api/exceptions.rst:820 +msgid "" +"Set the traceback associated with the exception to *tb*. Use ``Py_None`` to " +"clear it." +msgstr "" + +#: ../../c-api/exceptions.rst:826 +msgid "" +"Return the context (another exception instance during whose handling *ex* " +"was raised) associated with the exception as a new reference, as accessible " +"from Python through the :attr:`~BaseException.__context__` attribute. If " +"there is no context associated, this returns ``NULL``." +msgstr "" + +#: ../../c-api/exceptions.rst:834 +msgid "" +"Set the context associated with the exception to *ctx*. Use ``NULL`` to " +"clear it. There is no type check to make sure that *ctx* is an exception " +"instance. This steals a reference to *ctx*." +msgstr "" + +#: ../../c-api/exceptions.rst:841 +msgid "" +"Return the cause (either an exception instance, or ``None``, set by " +"``raise ... from ...``) associated with the exception as a new reference, as " +"accessible from Python through the :attr:`~BaseException.__cause__` " +"attribute." +msgstr "" + +#: ../../c-api/exceptions.rst:849 +msgid "" +"Set the cause associated with the exception to *cause*. Use ``NULL`` to " +"clear it. There is no type check to make sure that *cause* is either an " +"exception instance or ``None``. This steals a reference to *cause*." +msgstr "" + +#: ../../c-api/exceptions.rst:853 +msgid "" +"The :attr:`~BaseException.__suppress_context__` attribute is implicitly set " +"to ``True`` by this function." +msgstr "" + +#: ../../c-api/exceptions.rst:859 +msgid "Return :attr:`~BaseException.args` of exception *ex*." +msgstr "回傳例外 *ex* 的 :attr:`~BaseException.args`。" + +#: ../../c-api/exceptions.rst:864 +msgid "Set :attr:`~BaseException.args` of exception *ex* to *args*." +msgstr "設定例外 *ex* 的 :attr:`~BaseException.args` 為 *args*。" + +#: ../../c-api/exceptions.rst:868 +msgid "" +"Implement part of the interpreter's implementation of :keyword:`!except*`. " +"*orig* is the original exception that was caught, and *excs* is the list of " +"the exceptions that need to be raised. This list contains the unhandled part " +"of *orig*, if any, as well as the exceptions that were raised from the :" +"keyword:`!except*` clauses (so they have a different traceback from *orig*) " +"and those that were reraised (and have the same traceback as *orig*). Return " +"the :exc:`ExceptionGroup` that needs to be reraised in the end, or ``None`` " +"if there is nothing to reraise." +msgstr "" + +#: ../../c-api/exceptions.rst:882 +msgid "Unicode Exception Objects" +msgstr "Unicode 例外物件" + +#: ../../c-api/exceptions.rst:884 +msgid "" +"The following functions are used to create and modify Unicode exceptions " +"from C." +msgstr "" + +#: ../../c-api/exceptions.rst:888 +msgid "" +"Create a :class:`UnicodeDecodeError` object with the attributes *encoding*, " +"*object*, *length*, *start*, *end* and *reason*. *encoding* and *reason* are " +"UTF-8 encoded strings." +msgstr "" + +#: ../../c-api/exceptions.rst:895 +msgid "Return the *encoding* attribute of the given exception object." +msgstr "" + +#: ../../c-api/exceptions.rst:901 +msgid "Return the *object* attribute of the given exception object." +msgstr "" + +#: ../../c-api/exceptions.rst:907 +msgid "" +"Get the *start* attribute of the given exception object and place it into " +"*\\*start*. *start* must not be ``NULL``. Return ``0`` on success, ``-1`` " +"on failure." +msgstr "" + +#: ../../c-api/exceptions.rst:911 +msgid "" +"If the :attr:`UnicodeError.object` is an empty sequence, the resulting " +"*start* is ``0``. Otherwise, it is clipped to ``[0, len(object) - 1]``." +msgstr "" + +#: ../../c-api/exceptions.rst:914 +msgid ":attr:`UnicodeError.start`" +msgstr ":attr:`UnicodeError.start`" + +#: ../../c-api/exceptions.rst:920 +msgid "" +"Set the *start* attribute of the given exception object to *start*. Return " +"``0`` on success, ``-1`` on failure." +msgstr "" + +#: ../../c-api/exceptions.rst:925 +msgid "" +"While passing a negative *start* does not raise an exception, the " +"corresponding getters will not consider it as a relative offset." +msgstr "" + +#: ../../c-api/exceptions.rst:933 +msgid "" +"Get the *end* attribute of the given exception object and place it into " +"*\\*end*. *end* must not be ``NULL``. Return ``0`` on success, ``-1`` on " +"failure." +msgstr "" + +#: ../../c-api/exceptions.rst:937 +msgid "" +"If the :attr:`UnicodeError.object` is an empty sequence, the resulting *end* " +"is ``0``. Otherwise, it is clipped to ``[1, len(object)]``." +msgstr "" + +#: ../../c-api/exceptions.rst:944 +msgid "" +"Set the *end* attribute of the given exception object to *end*. Return " +"``0`` on success, ``-1`` on failure." +msgstr "" + +#: ../../c-api/exceptions.rst:947 +msgid ":attr:`UnicodeError.end`" +msgstr ":attr:`UnicodeError.end`" + +#: ../../c-api/exceptions.rst:953 +msgid "Return the *reason* attribute of the given exception object." +msgstr "回傳給定例外物件的 *reason* 屬性。" + +#: ../../c-api/exceptions.rst:959 +msgid "" +"Set the *reason* attribute of the given exception object to *reason*. " +"Return ``0`` on success, ``-1`` on failure." +msgstr "" + +#: ../../c-api/exceptions.rst:966 +msgid "Recursion Control" +msgstr "遞迴控制" + +#: ../../c-api/exceptions.rst:968 +msgid "" +"These two functions provide a way to perform safe recursive calls at the C " +"level, both in the core and in extension modules. They are needed if the " +"recursive code does not necessarily invoke Python code (which tracks its " +"recursion depth automatically). They are also not needed for *tp_call* " +"implementations because the :ref:`call protocol ` takes care of " +"recursion handling." +msgstr "" + +#: ../../c-api/exceptions.rst:977 +msgid "Marks a point where a recursive C-level call is about to be performed." +msgstr "" + +#: ../../c-api/exceptions.rst:979 +msgid "" +"The function then checks if the stack limit is reached. If this is the " +"case, a :exc:`RecursionError` is set and a nonzero value is returned. " +"Otherwise, zero is returned." +msgstr "" + +#: ../../c-api/exceptions.rst:983 +msgid "" +"*where* should be a UTF-8 encoded string such as ``\" in instance check\"`` " +"to be concatenated to the :exc:`RecursionError` message caused by the " +"recursion depth limit." +msgstr "" + +#: ../../c-api/exceptions.rst:988 +msgid "The :c:func:`PyUnstable_ThreadState_SetStackProtection` function." +msgstr "" + +#: ../../c-api/exceptions.rst:990 ../../c-api/exceptions.rst:998 +msgid "" +"This function is now also available in the :ref:`limited API `." +msgstr "" + +#: ../../c-api/exceptions.rst:995 +msgid "" +"Ends a :c:func:`Py_EnterRecursiveCall`. Must be called once for each " +"*successful* invocation of :c:func:`Py_EnterRecursiveCall`." +msgstr "" + +#: ../../c-api/exceptions.rst:1001 +msgid "" +"Properly implementing :c:member:`~PyTypeObject.tp_repr` for container types " +"requires special recursion handling. In addition to protecting the stack, :" +"c:member:`~PyTypeObject.tp_repr` also needs to track objects to prevent " +"cycles. The following two functions facilitate this functionality. " +"Effectively, these are the C equivalent to :func:`reprlib.recursive_repr`." +msgstr "" + +#: ../../c-api/exceptions.rst:1009 +msgid "" +"Called at the beginning of the :c:member:`~PyTypeObject.tp_repr` " +"implementation to detect cycles." +msgstr "" + +#: ../../c-api/exceptions.rst:1012 +msgid "" +"If the object has already been processed, the function returns a positive " +"integer. In that case the :c:member:`~PyTypeObject.tp_repr` implementation " +"should return a string object indicating a cycle. As examples, :class:" +"`dict` objects return ``{...}`` and :class:`list` objects return ``[...]``." +msgstr "" + +#: ../../c-api/exceptions.rst:1018 +msgid "" +"The function will return a negative integer if the recursion limit is " +"reached. In that case the :c:member:`~PyTypeObject.tp_repr` implementation " +"should typically return ``NULL``." +msgstr "" + +#: ../../c-api/exceptions.rst:1022 +msgid "" +"Otherwise, the function returns zero and the :c:member:`~PyTypeObject." +"tp_repr` implementation can continue normally." +msgstr "" + +#: ../../c-api/exceptions.rst:1027 +msgid "" +"Ends a :c:func:`Py_ReprEnter`. Must be called once for each invocation of :" +"c:func:`Py_ReprEnter` that returns zero." +msgstr "" + +#: ../../c-api/exceptions.rst:1032 +msgid "" +"Get the recursion limit for the current interpreter. It can be set with :c:" +"func:`Py_SetRecursionLimit`. The recursion limit prevents the Python " +"interpreter stack from growing infinitely." +msgstr "" + +#: ../../c-api/exceptions.rst:1036 ../../c-api/exceptions.rst:1046 +msgid "" +"This function cannot fail, and the caller must hold an :term:`attached " +"thread state`." +msgstr "" + +#: ../../c-api/exceptions.rst:1040 +msgid ":py:func:`sys.getrecursionlimit`" +msgstr ":py:func:`sys.getrecursionlimit`" + +#: ../../c-api/exceptions.rst:1044 +msgid "Set the recursion limit for the current interpreter." +msgstr "" + +#: ../../c-api/exceptions.rst:1050 +msgid ":py:func:`sys.setrecursionlimit`" +msgstr ":py:func:`sys.setrecursionlimit`" + +#: ../../c-api/exceptions.rst:1055 +msgid "Exception and warning types" +msgstr "例外和警告型別" + +#: ../../c-api/exceptions.rst:1057 +msgid "" +"All standard Python exceptions and warning categories are available as " +"global variables whose names are ``PyExc_`` followed by the Python exception " +"name. These have the type :c:expr:`PyObject*`; they are all class objects." +msgstr "" + +#: ../../c-api/exceptions.rst:1061 +msgid "For completeness, here are all the variables:" +msgstr "" + +#: ../../c-api/exceptions.rst:1064 +msgid "Exception types" +msgstr "例外型別" + +#: ../../c-api/exceptions.rst:1071 ../../c-api/exceptions.rst:1217 +#: ../../c-api/exceptions.rst:1247 +msgid "C name" +msgstr "C 名稱" + +#: ../../c-api/exceptions.rst:1072 ../../c-api/exceptions.rst:1218 +#: ../../c-api/exceptions.rst:1248 +msgid "Python name" +msgstr "Python 名稱" + +#: ../../c-api/exceptions.rst:1074 +msgid ":exc:`BaseException`" +msgstr ":exc:`BaseException`" + +#: ../../c-api/exceptions.rst:1076 +msgid ":exc:`BaseExceptionGroup`" +msgstr ":exc:`BaseExceptionGroup`" + +#: ../../c-api/exceptions.rst:1078 +msgid ":exc:`Exception`" +msgstr ":exc:`Exception`" + +#: ../../c-api/exceptions.rst:1080 +msgid ":exc:`ArithmeticError`" +msgstr ":exc:`ArithmeticError`" + +#: ../../c-api/exceptions.rst:1082 +msgid ":exc:`AssertionError`" +msgstr ":exc:`AssertionError`" + +#: ../../c-api/exceptions.rst:1084 +msgid ":exc:`AttributeError`" +msgstr ":exc:`AttributeError`" + +#: ../../c-api/exceptions.rst:1086 +msgid ":exc:`BlockingIOError`" +msgstr ":exc:`BlockingIOError`" + +#: ../../c-api/exceptions.rst:1088 +msgid ":exc:`BrokenPipeError`" +msgstr ":exc:`BrokenPipeError`" + +#: ../../c-api/exceptions.rst:1090 +msgid ":exc:`BufferError`" +msgstr ":exc:`BufferError`" + +#: ../../c-api/exceptions.rst:1092 +msgid ":exc:`ChildProcessError`" +msgstr ":exc:`ChildProcessError`" + +#: ../../c-api/exceptions.rst:1094 +msgid ":exc:`ConnectionAbortedError`" +msgstr ":exc:`ConnectionAbortedError`" + +#: ../../c-api/exceptions.rst:1096 +msgid ":exc:`ConnectionError`" +msgstr ":exc:`ConnectionError`" + +#: ../../c-api/exceptions.rst:1098 +msgid ":exc:`ConnectionRefusedError`" +msgstr ":exc:`ConnectionRefusedError`" + +#: ../../c-api/exceptions.rst:1100 +msgid ":exc:`ConnectionResetError`" +msgstr ":exc:`ConnectionResetError`" + +#: ../../c-api/exceptions.rst:1102 +msgid ":exc:`EOFError`" +msgstr ":exc:`EOFError`" + +#: ../../c-api/exceptions.rst:1104 +msgid ":exc:`FileExistsError`" +msgstr ":exc:`FileExistsError`" + +#: ../../c-api/exceptions.rst:1106 +msgid ":exc:`FileNotFoundError`" +msgstr ":exc:`FileNotFoundError`" + +#: ../../c-api/exceptions.rst:1108 +msgid ":exc:`FloatingPointError`" +msgstr ":exc:`FloatingPointError`" + +#: ../../c-api/exceptions.rst:1110 +msgid ":exc:`GeneratorExit`" +msgstr ":exc:`GeneratorExit`" + +#: ../../c-api/exceptions.rst:1112 +msgid ":exc:`ImportError`" +msgstr ":exc:`ImportError`" + +#: ../../c-api/exceptions.rst:1114 +msgid ":exc:`IndentationError`" +msgstr ":exc:`IndentationError`" + +#: ../../c-api/exceptions.rst:1116 +msgid ":exc:`IndexError`" +msgstr ":exc:`IndexError`" + +#: ../../c-api/exceptions.rst:1118 +msgid ":exc:`InterruptedError`" +msgstr ":exc:`InterruptedError`" + +#: ../../c-api/exceptions.rst:1120 +msgid ":exc:`IsADirectoryError`" +msgstr ":exc:`IsADirectoryError`" + +#: ../../c-api/exceptions.rst:1122 +msgid ":exc:`KeyError`" +msgstr ":exc:`KeyError`" + +#: ../../c-api/exceptions.rst:1124 +msgid ":exc:`KeyboardInterrupt`" +msgstr ":exc:`KeyboardInterrupt`" + +#: ../../c-api/exceptions.rst:1126 +msgid ":exc:`LookupError`" +msgstr ":exc:`LookupError`" + +#: ../../c-api/exceptions.rst:1128 +msgid ":exc:`MemoryError`" +msgstr ":exc:`MemoryError`" + +#: ../../c-api/exceptions.rst:1130 +msgid ":exc:`ModuleNotFoundError`" +msgstr ":exc:`ModuleNotFoundError`" + +#: ../../c-api/exceptions.rst:1132 +msgid ":exc:`NameError`" +msgstr ":exc:`NameError`" + +#: ../../c-api/exceptions.rst:1134 +msgid ":exc:`NotADirectoryError`" +msgstr ":exc:`NotADirectoryError`" + +#: ../../c-api/exceptions.rst:1136 +msgid ":exc:`NotImplementedError`" +msgstr ":exc:`NotImplementedError`" + +#: ../../c-api/exceptions.rst:1138 ../../c-api/exceptions.rst:1221 +#: ../../c-api/exceptions.rst:1224 ../../c-api/exceptions.rst:1227 +msgid ":exc:`OSError`" +msgstr ":exc:`OSError`" + +#: ../../c-api/exceptions.rst:1140 +msgid ":exc:`OverflowError`" +msgstr ":exc:`OverflowError`" + +#: ../../c-api/exceptions.rst:1142 +msgid ":exc:`PermissionError`" +msgstr ":exc:`PermissionError`" + +#: ../../c-api/exceptions.rst:1144 +msgid ":exc:`ProcessLookupError`" +msgstr ":exc:`ProcessLookupError`" + +#: ../../c-api/exceptions.rst:1146 +msgid ":exc:`PythonFinalizationError`" +msgstr ":exc:`PythonFinalizationError`" + +#: ../../c-api/exceptions.rst:1148 +msgid ":exc:`RecursionError`" +msgstr ":exc:`RecursionError`" + +#: ../../c-api/exceptions.rst:1150 +msgid ":exc:`ReferenceError`" +msgstr ":exc:`ReferenceError`" + +#: ../../c-api/exceptions.rst:1152 +msgid ":exc:`RuntimeError`" +msgstr ":exc:`RuntimeError`" + +#: ../../c-api/exceptions.rst:1154 +msgid ":exc:`StopAsyncIteration`" +msgstr ":exc:`StopAsyncIteration`" + +#: ../../c-api/exceptions.rst:1156 +msgid ":exc:`StopIteration`" +msgstr ":exc:`StopIteration`" + +#: ../../c-api/exceptions.rst:1158 +msgid ":exc:`SyntaxError`" +msgstr ":exc:`SyntaxError`" + +#: ../../c-api/exceptions.rst:1160 +msgid ":exc:`SystemError`" +msgstr ":exc:`SystemError`" + +#: ../../c-api/exceptions.rst:1162 +msgid ":exc:`SystemExit`" +msgstr ":exc:`SystemExit`" + +#: ../../c-api/exceptions.rst:1164 +msgid ":exc:`TabError`" +msgstr ":exc:`TabError`" + +#: ../../c-api/exceptions.rst:1166 +msgid ":exc:`TimeoutError`" +msgstr ":exc:`TimeoutError`" + +#: ../../c-api/exceptions.rst:1168 +msgid ":exc:`TypeError`" +msgstr ":exc:`TypeError`" + +#: ../../c-api/exceptions.rst:1170 +msgid ":exc:`UnboundLocalError`" +msgstr ":exc:`UnboundLocalError`" + +#: ../../c-api/exceptions.rst:1172 +msgid ":exc:`UnicodeDecodeError`" +msgstr ":exc:`UnicodeDecodeError`" + +#: ../../c-api/exceptions.rst:1174 +msgid ":exc:`UnicodeEncodeError`" +msgstr ":exc:`UnicodeEncodeError`" + +#: ../../c-api/exceptions.rst:1176 +msgid ":exc:`UnicodeError`" +msgstr ":exc:`UnicodeError`" + +#: ../../c-api/exceptions.rst:1178 +msgid ":exc:`UnicodeTranslateError`" +msgstr ":exc:`UnicodeTranslateError`" + +#: ../../c-api/exceptions.rst:1180 +msgid ":exc:`ValueError`" +msgstr ":exc:`ValueError`" + +#: ../../c-api/exceptions.rst:1182 +msgid ":exc:`ZeroDivisionError`" +msgstr ":exc:`ZeroDivisionError`" + +#: ../../c-api/exceptions.rst:1184 +msgid "" +":c:data:`PyExc_BlockingIOError`, :c:data:`PyExc_BrokenPipeError`, :c:data:" +"`PyExc_ChildProcessError`, :c:data:`PyExc_ConnectionError`, :c:data:" +"`PyExc_ConnectionAbortedError`, :c:data:`PyExc_ConnectionRefusedError`, :c:" +"data:`PyExc_ConnectionResetError`, :c:data:`PyExc_FileExistsError`, :c:data:" +"`PyExc_FileNotFoundError`, :c:data:`PyExc_InterruptedError`, :c:data:" +"`PyExc_IsADirectoryError`, :c:data:`PyExc_NotADirectoryError`, :c:data:" +"`PyExc_PermissionError`, :c:data:`PyExc_ProcessLookupError` and :c:data:" +"`PyExc_TimeoutError` were introduced following :pep:`3151`." +msgstr "" +":c:data:`PyExc_BlockingIOError`, :c:data:`PyExc_BrokenPipeError`, :c:data:" +"`PyExc_ChildProcessError`, :c:data:`PyExc_ConnectionError`, :c:data:" +"`PyExc_ConnectionAbortedError`, :c:data:`PyExc_ConnectionRefusedError`, :c:" +"data:`PyExc_ConnectionResetError`, :c:data:`PyExc_FileExistsError`, :c:data:" +"`PyExc_FileNotFoundError`, :c:data:`PyExc_InterruptedError`, :c:data:" +"`PyExc_IsADirectoryError`, :c:data:`PyExc_NotADirectoryError`, :c:data:" +"`PyExc_PermissionError`, :c:data:`PyExc_ProcessLookupError` 和 :c:data:" +"`PyExc_TimeoutError` 是在 :pep:`3151` 被引入。" + +#: ../../c-api/exceptions.rst:1194 +msgid ":c:data:`PyExc_StopAsyncIteration` and :c:data:`PyExc_RecursionError`." +msgstr ":c:data:`PyExc_StopAsyncIteration` 和 :c:data:`PyExc_RecursionError`。" + +#: ../../c-api/exceptions.rst:1197 +msgid ":c:data:`PyExc_ModuleNotFoundError`." +msgstr ":c:data:`PyExc_ModuleNotFoundError`。" + +#: ../../c-api/exceptions.rst:1200 +msgid ":c:data:`PyExc_BaseExceptionGroup`." +msgstr ":c:data:`PyExc_BaseExceptionGroup`" + +#: ../../c-api/exceptions.rst:1205 +msgid "OSError aliases" +msgstr "OSError 別名" + +#: ../../c-api/exceptions.rst:1207 +msgid "The following are a compatibility aliases to :c:data:`PyExc_OSError`." +msgstr "" + +#: ../../c-api/exceptions.rst:1209 +msgid "These aliases used to be separate exception types." +msgstr "" + +#: ../../c-api/exceptions.rst:1219 +msgid "Notes" +msgstr "註解" + +#: ../../c-api/exceptions.rst:1228 +msgid "[win]_" +msgstr "[win]_" + +#: ../../c-api/exceptions.rst:1230 +msgid "Notes:" +msgstr "註解：" + +#: ../../c-api/exceptions.rst:1233 +msgid "" +":c:var:`!PyExc_WindowsError` is only defined on Windows; protect code that " +"uses this by testing that the preprocessor macro ``MS_WINDOWS`` is defined." +msgstr "" + +#: ../../c-api/exceptions.rst:1240 +msgid "Warning types" +msgstr "警告型別" + +#: ../../c-api/exceptions.rst:1250 +msgid ":exc:`Warning`" +msgstr ":exc:`Warning`" + +#: ../../c-api/exceptions.rst:1252 +msgid ":exc:`BytesWarning`" +msgstr ":exc:`BytesWarning`" + +#: ../../c-api/exceptions.rst:1254 +msgid ":exc:`DeprecationWarning`" +msgstr ":exc:`DeprecationWarning`" + +#: ../../c-api/exceptions.rst:1256 +msgid ":exc:`EncodingWarning`" +msgstr ":exc:`EncodingWarning`" + +#: ../../c-api/exceptions.rst:1258 +msgid ":exc:`FutureWarning`" +msgstr ":exc:`FutureWarning`" + +#: ../../c-api/exceptions.rst:1260 +msgid ":exc:`ImportWarning`" +msgstr ":exc:`ImportWarning`" + +#: ../../c-api/exceptions.rst:1262 +msgid ":exc:`PendingDeprecationWarning`" +msgstr ":exc:`PendingDeprecationWarning`" + +#: ../../c-api/exceptions.rst:1264 +msgid ":exc:`ResourceWarning`" +msgstr ":exc:`ResourceWarning`" + +#: ../../c-api/exceptions.rst:1266 +msgid ":exc:`RuntimeWarning`" +msgstr ":exc:`RuntimeWarning`" + +#: ../../c-api/exceptions.rst:1268 +msgid ":exc:`SyntaxWarning`" +msgstr ":exc:`SyntaxWarning`" + +#: ../../c-api/exceptions.rst:1270 +msgid ":exc:`UnicodeWarning`" +msgstr ":exc:`UnicodeWarning`" + +#: ../../c-api/exceptions.rst:1272 +msgid ":exc:`UserWarning`" +msgstr ":exc:`UserWarning`" + +#: ../../c-api/exceptions.rst:1274 +msgid ":c:data:`PyExc_ResourceWarning`." +msgstr ":c:data:`PyExc_ResourceWarning`。" + +#: ../../c-api/exceptions.rst:1277 +msgid ":c:data:`PyExc_EncodingWarning`." +msgstr ":c:data:`PyExc_EncodingWarning`。" + +#: ../../c-api/exceptions.rst:1282 +msgid "Tracebacks" +msgstr "" + +#: ../../c-api/exceptions.rst:1286 +msgid "" +"Type object for traceback objects. This is available as :class:`types." +"TracebackType` in the Python layer." +msgstr "" + +#: ../../c-api/exceptions.rst:1292 +msgid "" +"Return true if *op* is a traceback object, false otherwise. This function " +"does not account for subtypes." +msgstr "" + +#: ../../c-api/exceptions.rst:1298 +msgid "" +"Replace the :attr:`~BaseException.__traceback__` attribute on the current " +"exception with a new traceback prepending *f* to the existing chain." +msgstr "" + +#: ../../c-api/exceptions.rst:1301 +msgid "Calling this function without an exception set is undefined behavior." +msgstr "" + +#: ../../c-api/exceptions.rst:1303 ../../c-api/exceptions.rst:1311 +msgid "" +"This function returns ``0`` on success, and returns ``-1`` with an exception " +"set on failure." +msgstr "" + +#: ../../c-api/exceptions.rst:1309 +msgid "Write the traceback *tb* into the file *f*." +msgstr "" + +#: ../../c-api/exceptions.rst:183 +msgid "strerror (C function)" +msgstr "strerror（C 函式）" + +#: ../../c-api/exceptions.rst:671 ../../c-api/exceptions.rst:702 +#: ../../c-api/exceptions.rst:717 +msgid "module" +msgstr "module（模組）" + +#: ../../c-api/exceptions.rst:671 ../../c-api/exceptions.rst:702 +#: ../../c-api/exceptions.rst:717 +msgid "signal" +msgstr "signal（訊號）" + +#: ../../c-api/exceptions.rst:671 ../../c-api/exceptions.rst:702 +msgid "SIGINT (C macro)" +msgstr "SIGINT（C 巨集）" + +#: ../../c-api/exceptions.rst:671 ../../c-api/exceptions.rst:702 +#: ../../c-api/exceptions.rst:717 +msgid "KeyboardInterrupt (built-in exception)" +msgstr "KeyboardInterrupt（內建例外）" + +#~ msgid "The caller must hold the GIL." +#~ msgstr "呼叫者必須持有 GIL。" diff --git a/c-api/extension-modules.po b/c-api/extension-modules.po index b93feceed8..f5c4796450 100644 --- a/c-api/extension-modules.po +++ b/c-api/extension-modules.po @@ -1,384 +1,384 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# FIRST AUTHOR , YEAR. -# -#, fuzzy -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language-Team: LANGUAGE \n" -"Language: zh_TW\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=UTF-8\n" -"Content-Transfer-Encoding: 8bit\n" - -#: ../../c-api/extension-modules.rst:6 -msgid "Defining extension modules" -msgstr "" - -#: ../../c-api/extension-modules.rst:8 -msgid "" -"A C extension for CPython is a shared library (for example, a ``.so`` file " -"on Linux, ``.pyd`` DLL on Windows), which is loadable into the Python " -"process (for example, it is compiled with compatible compiler settings), and " -"which exports an :ref:`initialization function `." -msgstr "" - -#: ../../c-api/extension-modules.rst:13 -msgid "" -"To be importable by default (that is, " -"by :py:class:`importlib.machinery.ExtensionFileLoader`), the shared library " -"must be available on :py:attr:`sys.path`, and must be named after the module " -"name plus an extension listed " -"in :py:attr:`importlib.machinery.EXTENSION_SUFFIXES`." -msgstr "" - -#: ../../c-api/extension-modules.rst:21 -msgid "" -"Building, packaging and distributing extension modules is best done with " -"third-party tools, and is out of scope of this document. One suitable tool " -"is Setuptools, whose documentation can be found at https://" -"setuptools.pypa.io/en/latest/setuptools.html." -msgstr "" - -#: ../../c-api/extension-modules.rst:26 -msgid "" -"Normally, the initialization function returns a module definition " -"initialized using :c:func:`PyModuleDef_Init`. This allows splitting the " -"creation process into several phases:" -msgstr "" - -#: ../../c-api/extension-modules.rst:30 -msgid "" -"Before any substantial code is executed, Python can determine which " -"capabilities the module supports, and it can adjust the environment or " -"refuse loading an incompatible extension." -msgstr "" - -#: ../../c-api/extension-modules.rst:33 -msgid "" -"By default, Python itself creates the module object -- that is, it does the " -"equivalent of :py:meth:`object.__new__` for classes. It also sets initial " -"attributes like :attr:`~module.__package__` and :attr:`~module.__loader__`." -msgstr "" - -#: ../../c-api/extension-modules.rst:37 -msgid "" -"Afterwards, the module object is initialized using extension-specific code " -"-- the equivalent of :py:meth:`~object.__init__` on classes." -msgstr "" - -#: ../../c-api/extension-modules.rst:40 -msgid "" -"This is called *multi-phase initialization* to distinguish it from the " -"legacy (but still supported) *single-phase initialization* scheme, where the " -"initialization function returns a fully constructed module. See " -"the :ref:`single-phase-initialization section below ` for details." -msgstr "" - -#: ../../c-api/extension-modules.rst:48 -msgid "Added support for multi-phase initialization (:pep:`489`)." -msgstr "" - -#: ../../c-api/extension-modules.rst:52 -msgid "Multiple module instances" -msgstr "" - -#: ../../c-api/extension-modules.rst:54 -msgid "" -"By default, extension modules are not singletons. For example, if " -"the :py:attr:`sys.modules` entry is removed and the module is re-imported, a " -"new module object is created, and typically populated with fresh method and " -"type objects. The old module is subject to normal garbage collection. This " -"mirrors the behavior of pure-Python modules." -msgstr "" - -#: ../../c-api/extension-modules.rst:61 -msgid "" -"Additional module instances may be created in :ref:`sub-interpreters ` or after Python runtime reinitialization " -"(:c:func:`Py_Finalize` and :c:func:`Py_Initialize`). In these cases, sharing " -"Python objects between module instances would likely cause crashes or " -"undefined behavior." -msgstr "" - -#: ../../c-api/extension-modules.rst:68 -msgid "" -"To avoid such issues, each instance of an extension module should be " -"*isolated*: changes to one instance should not implicitly affect the others, " -"and all state owned by the module, including references to Python objects, " -"should be specific to a particular module instance. See :ref:`isolating-" -"extensions-howto` for more details and a practical guide." -msgstr "" - -#: ../../c-api/extension-modules.rst:74 -msgid "" -"A simpler way to avoid these issues is :ref:`raising an error on repeated " -"initialization `." -msgstr "" - -#: ../../c-api/extension-modules.rst:77 -msgid "" -"All modules are expected to support :ref:`sub-interpreters `, or otherwise explicitly signal a lack of support. This is usually " -"achieved by isolation or blocking repeated initialization, as above. A " -"module may also be limited to the main interpreter using " -"the :c:data:`Py_mod_multiple_interpreters` slot." -msgstr "" - -#: ../../c-api/extension-modules.rst:89 -msgid "Initialization function" -msgstr "" - -#: ../../c-api/extension-modules.rst:91 -msgid "" -"The initialization function defined by an extension module has the following " -"signature:" -msgstr "" - -#: ../../c-api/extension-modules.rst:96 -msgid "" -"Its name should be :samp:`PyInit_{}`, with ```` replaced by the " -"name of the module." -msgstr "" - -#: ../../c-api/extension-modules.rst:99 -msgid "" -"For modules with ASCII-only names, the function must instead be " -"named :samp:`PyInit_{}`, with ```` replaced by the name of the " -"module. When using :ref:`multi-phase-initialization`, non-ASCII module names " -"are allowed. In this case, the initialization function name " -"is :samp:`PyInitU_{}`, with ```` encoded using Python's " -"*punycode* encoding with hyphens replaced by underscores. In Python:" -msgstr "" - -#: ../../c-api/extension-modules.rst:106 -msgid "" -"def initfunc_name(name):\n" -" try:\n" -" suffix = b'_' + name.encode('ascii')\n" -" except UnicodeEncodeError:\n" -" suffix = b'U_' + name.encode('punycode').replace(b'-', b'_')\n" -" return b'PyInit' + suffix" -msgstr "" -"def initfunc_name(name):\n" -" try:\n" -" suffix = b'_' + name.encode('ascii')\n" -" except UnicodeEncodeError:\n" -" suffix = b'U_' + name.encode('punycode').replace(b'-', b'_')\n" -" return b'PyInit' + suffix" - -#: ../../c-api/extension-modules.rst:115 -msgid "" -"It is recommended to define the initialization function using a helper macro:" -msgstr "" - -#: ../../c-api/extension-modules.rst:119 -msgid "Declare an extension module initialization function. This macro:" -msgstr "" - -#: ../../c-api/extension-modules.rst:122 -msgid "specifies the :c:expr:`PyObject*` return type," -msgstr "" - -#: ../../c-api/extension-modules.rst:123 -msgid "adds any special linkage declarations required by the platform, and" -msgstr "" - -#: ../../c-api/extension-modules.rst:124 -msgid "for C++, declares the function as ``extern \"C\"``." -msgstr "" - -#: ../../c-api/extension-modules.rst:126 -msgid "For example, a module called ``spam`` would be defined like this::" -msgstr "" - -#: ../../c-api/extension-modules.rst:128 -msgid "" -"static struct PyModuleDef spam_module = {\n" -" .m_base = PyModuleDef_HEAD_INIT,\n" -" .m_name = \"spam\",\n" -" ...\n" -"};\n" -"\n" -"PyMODINIT_FUNC\n" -"PyInit_spam(void)\n" -"{\n" -" return PyModuleDef_Init(&spam_module);\n" -"}" -msgstr "" -"static struct PyModuleDef spam_module = {\n" -" .m_base = PyModuleDef_HEAD_INIT,\n" -" .m_name = \"spam\",\n" -" ...\n" -"};\n" -"\n" -"PyMODINIT_FUNC\n" -"PyInit_spam(void)\n" -"{\n" -" return PyModuleDef_Init(&spam_module);\n" -"}" - -#: ../../c-api/extension-modules.rst:140 -msgid "" -"It is possible to export multiple modules from a single shared library by " -"defining multiple initialization functions. However, importing them requires " -"using symbolic links or a custom importer, because by default only the " -"function corresponding to the filename is found. See the `Multiple modules " -"in one library `__ section in :pep:`489` for details." -msgstr "" - -#: ../../c-api/extension-modules.rst:147 -msgid "" -"The initialization function is typically the only non-\\ ``static`` item " -"defined in the module's C source." -msgstr "" - -#: ../../c-api/extension-modules.rst:154 -msgid "Multi-phase initialization" -msgstr "" - -#: ../../c-api/extension-modules.rst:156 -msgid "" -"Normally, the :ref:`initialization function ` " -"(``PyInit_modulename``) returns a :c:type:`PyModuleDef` instance with non-" -"``NULL`` :c:member:`~PyModuleDef.m_slots`. Before it is returned, the " -"``PyModuleDef`` instance must be initialized using the following function:" -msgstr "" - -#: ../../c-api/extension-modules.rst:165 -msgid "" -"Ensure a module definition is a properly initialized Python object that " -"correctly reports its type and a reference count." -msgstr "" - -#: ../../c-api/extension-modules.rst:168 -msgid "Return *def* cast to ``PyObject*``, or ``NULL`` if an error occurred." -msgstr "" - -#: ../../c-api/extension-modules.rst:170 -msgid "" -"Calling this function is required for :ref:`multi-phase-initialization`. It " -"should not be used in other contexts." -msgstr "" - -#: ../../c-api/extension-modules.rst:173 -msgid "" -"Note that Python assumes that ``PyModuleDef`` structures are statically " -"allocated. This function may return either a new reference or a borrowed " -"one; this reference must not be released." -msgstr "" - -#: ../../c-api/extension-modules.rst:184 -msgid "Legacy single-phase initialization" -msgstr "" - -#: ../../c-api/extension-modules.rst:187 -msgid "" -"Single-phase initialization is a legacy mechanism to initialize extension " -"modules, with known drawbacks and design flaws. Extension module authors are " -"encouraged to use multi-phase initialization instead." -msgstr "" - -#: ../../c-api/extension-modules.rst:191 -msgid "" -"In single-phase initialization, the :ref:`initialization function ` (``PyInit_modulename``) should create, populate and return a " -"module object. This is typically done using :c:func:`PyModule_Create` and " -"functions like :c:func:`PyModule_AddObjectRef`." -msgstr "" - -#: ../../c-api/extension-modules.rst:197 -msgid "" -"Single-phase initialization differs from the :ref:`default ` in the following ways:" -msgstr "" - -#: ../../c-api/extension-modules.rst:200 -msgid "Single-phase modules are, or rather *contain*, “singletons”." -msgstr "" - -#: ../../c-api/extension-modules.rst:202 -msgid "" -"When the module is first initialized, Python saves the contents of the " -"module's ``__dict__`` (that is, typically, the module's functions and types)." -msgstr "" - -#: ../../c-api/extension-modules.rst:206 -msgid "" -"For subsequent imports, Python does not call the initialization function " -"again. Instead, it creates a new module object with a new ``__dict__``, and " -"copies the saved contents to it. For example, given a single-phase module " -"``_testsinglephase`` [#testsinglephase]_ that defines a function ``sum`` and " -"an exception class ``error``:" -msgstr "" - -#: ../../c-api/extension-modules.rst:214 -msgid "" -">>> import sys\n" -">>> import _testsinglephase as one\n" -">>> del sys.modules['_testsinglephase']\n" -">>> import _testsinglephase as two\n" -">>> one is two\n" -"False\n" -">>> one.__dict__ is two.__dict__\n" -"False\n" -">>> one.sum is two.sum\n" -"True\n" -">>> one.error is two.error\n" -"True" -msgstr "" -">>> import sys\n" -">>> import _testsinglephase as one\n" -">>> del sys.modules['_testsinglephase']\n" -">>> import _testsinglephase as two\n" -">>> one is two\n" -"False\n" -">>> one.__dict__ is two.__dict__\n" -"False\n" -">>> one.sum is two.sum\n" -"True\n" -">>> one.error is two.error\n" -"True" - -#: ../../c-api/extension-modules.rst:229 -msgid "" -"The exact behavior should be considered a CPython implementation detail." -msgstr "" - -#: ../../c-api/extension-modules.rst:231 -msgid "" -"To work around the fact that ``PyInit_modulename`` does not take a *spec* " -"argument, some state of the import machinery is saved and applied to the " -"first suitable module created during the ``PyInit_modulename`` call. " -"Specifically, when a sub-module is imported, this mechanism prepends the " -"parent package name to the name of the module." -msgstr "" - -#: ../../c-api/extension-modules.rst:237 -msgid "" -"A single-phase ``PyInit_modulename`` function should create “its” module " -"object as soon as possible, before any other module objects can be created." -msgstr "" - -#: ../../c-api/extension-modules.rst:240 -msgid "Non-ASCII module names (``PyInitU_modulename``) are not supported." -msgstr "" - -#: ../../c-api/extension-modules.rst:242 -msgid "" -"Single-phase modules support module lookup functions " -"like :c:func:`PyState_FindModule`." -msgstr "" - -#: ../../c-api/extension-modules.rst:245 -msgid "" -"``_testsinglephase`` is an internal module used in CPython's self-test " -"suite; your installation may or may not include it." -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"Language: zh_TW\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../c-api/extension-modules.rst:6 +msgid "Defining extension modules" +msgstr "" + +#: ../../c-api/extension-modules.rst:8 +msgid "" +"A C extension for CPython is a shared library (for example, a ``.so`` file " +"on Linux, ``.pyd`` DLL on Windows), which is loadable into the Python " +"process (for example, it is compiled with compatible compiler settings), and " +"which exports an :ref:`initialization function `." +msgstr "" + +#: ../../c-api/extension-modules.rst:13 +msgid "" +"To be importable by default (that is, " +"by :py:class:`importlib.machinery.ExtensionFileLoader`), the shared library " +"must be available on :py:attr:`sys.path`, and must be named after the module " +"name plus an extension listed " +"in :py:attr:`importlib.machinery.EXTENSION_SUFFIXES`." +msgstr "" + +#: ../../c-api/extension-modules.rst:21 +msgid "" +"Building, packaging and distributing extension modules is best done with " +"third-party tools, and is out of scope of this document. One suitable tool " +"is Setuptools, whose documentation can be found at https://" +"setuptools.pypa.io/en/latest/setuptools.html." +msgstr "" + +#: ../../c-api/extension-modules.rst:26 +msgid "" +"Normally, the initialization function returns a module definition " +"initialized using :c:func:`PyModuleDef_Init`. This allows splitting the " +"creation process into several phases:" +msgstr "" + +#: ../../c-api/extension-modules.rst:30 +msgid "" +"Before any substantial code is executed, Python can determine which " +"capabilities the module supports, and it can adjust the environment or " +"refuse loading an incompatible extension." +msgstr "" + +#: ../../c-api/extension-modules.rst:33 +msgid "" +"By default, Python itself creates the module object -- that is, it does the " +"equivalent of :py:meth:`object.__new__` for classes. It also sets initial " +"attributes like :attr:`~module.__package__` and :attr:`~module.__loader__`." +msgstr "" + +#: ../../c-api/extension-modules.rst:37 +msgid "" +"Afterwards, the module object is initialized using extension-specific code " +"-- the equivalent of :py:meth:`~object.__init__` on classes." +msgstr "" + +#: ../../c-api/extension-modules.rst:40 +msgid "" +"This is called *multi-phase initialization* to distinguish it from the " +"legacy (but still supported) *single-phase initialization* scheme, where the " +"initialization function returns a fully constructed module. See " +"the :ref:`single-phase-initialization section below ` for details." +msgstr "" + +#: ../../c-api/extension-modules.rst:48 +msgid "Added support for multi-phase initialization (:pep:`489`)." +msgstr "" + +#: ../../c-api/extension-modules.rst:52 +msgid "Multiple module instances" +msgstr "" + +#: ../../c-api/extension-modules.rst:54 +msgid "" +"By default, extension modules are not singletons. For example, if " +"the :py:attr:`sys.modules` entry is removed and the module is re-imported, a " +"new module object is created, and typically populated with fresh method and " +"type objects. The old module is subject to normal garbage collection. This " +"mirrors the behavior of pure-Python modules." +msgstr "" + +#: ../../c-api/extension-modules.rst:61 +msgid "" +"Additional module instances may be created in :ref:`sub-interpreters ` or after Python runtime reinitialization " +"(:c:func:`Py_Finalize` and :c:func:`Py_Initialize`). In these cases, sharing " +"Python objects between module instances would likely cause crashes or " +"undefined behavior." +msgstr "" + +#: ../../c-api/extension-modules.rst:68 +msgid "" +"To avoid such issues, each instance of an extension module should be " +"*isolated*: changes to one instance should not implicitly affect the others, " +"and all state owned by the module, including references to Python objects, " +"should be specific to a particular module instance. See :ref:`isolating-" +"extensions-howto` for more details and a practical guide." +msgstr "" + +#: ../../c-api/extension-modules.rst:74 +msgid "" +"A simpler way to avoid these issues is :ref:`raising an error on repeated " +"initialization `." +msgstr "" + +#: ../../c-api/extension-modules.rst:77 +msgid "" +"All modules are expected to support :ref:`sub-interpreters `, or otherwise explicitly signal a lack of support. This is usually " +"achieved by isolation or blocking repeated initialization, as above. A " +"module may also be limited to the main interpreter using " +"the :c:data:`Py_mod_multiple_interpreters` slot." +msgstr "" + +#: ../../c-api/extension-modules.rst:89 +msgid "Initialization function" +msgstr "" + +#: ../../c-api/extension-modules.rst:91 +msgid "" +"The initialization function defined by an extension module has the following " +"signature:" +msgstr "" + +#: ../../c-api/extension-modules.rst:96 +msgid "" +"Its name should be :samp:`PyInit_{}`, with ```` replaced by the " +"name of the module." +msgstr "" + +#: ../../c-api/extension-modules.rst:99 +msgid "" +"For modules with ASCII-only names, the function must instead be " +"named :samp:`PyInit_{}`, with ```` replaced by the name of the " +"module. When using :ref:`multi-phase-initialization`, non-ASCII module names " +"are allowed. In this case, the initialization function name " +"is :samp:`PyInitU_{}`, with ```` encoded using Python's " +"*punycode* encoding with hyphens replaced by underscores. In Python:" +msgstr "" + +#: ../../c-api/extension-modules.rst:106 +msgid "" +"def initfunc_name(name):\n" +" try:\n" +" suffix = b'_' + name.encode('ascii')\n" +" except UnicodeEncodeError:\n" +" suffix = b'U_' + name.encode('punycode').replace(b'-', b'_')\n" +" return b'PyInit' + suffix" +msgstr "" +"def initfunc_name(name):\n" +" try:\n" +" suffix = b'_' + name.encode('ascii')\n" +" except UnicodeEncodeError:\n" +" suffix = b'U_' + name.encode('punycode').replace(b'-', b'_')\n" +" return b'PyInit' + suffix" + +#: ../../c-api/extension-modules.rst:115 +msgid "" +"It is recommended to define the initialization function using a helper macro:" +msgstr "" + +#: ../../c-api/extension-modules.rst:119 +msgid "Declare an extension module initialization function. This macro:" +msgstr "" + +#: ../../c-api/extension-modules.rst:122 +msgid "specifies the :c:expr:`PyObject*` return type," +msgstr "" + +#: ../../c-api/extension-modules.rst:123 +msgid "adds any special linkage declarations required by the platform, and" +msgstr "" + +#: ../../c-api/extension-modules.rst:124 +msgid "for C++, declares the function as ``extern \"C\"``." +msgstr "" + +#: ../../c-api/extension-modules.rst:126 +msgid "For example, a module called ``spam`` would be defined like this::" +msgstr "" + +#: ../../c-api/extension-modules.rst:128 +msgid "" +"static struct PyModuleDef spam_module = {\n" +" .m_base = PyModuleDef_HEAD_INIT,\n" +" .m_name = \"spam\",\n" +" ...\n" +"};\n" +"\n" +"PyMODINIT_FUNC\n" +"PyInit_spam(void)\n" +"{\n" +" return PyModuleDef_Init(&spam_module);\n" +"}" +msgstr "" +"static struct PyModuleDef spam_module = {\n" +" .m_base = PyModuleDef_HEAD_INIT,\n" +" .m_name = \"spam\",\n" +" ...\n" +"};\n" +"\n" +"PyMODINIT_FUNC\n" +"PyInit_spam(void)\n" +"{\n" +" return PyModuleDef_Init(&spam_module);\n" +"}" + +#: ../../c-api/extension-modules.rst:140 +msgid "" +"It is possible to export multiple modules from a single shared library by " +"defining multiple initialization functions. However, importing them requires " +"using symbolic links or a custom importer, because by default only the " +"function corresponding to the filename is found. See the `Multiple modules " +"in one library `__ section in :pep:`489` for details." +msgstr "" + +#: ../../c-api/extension-modules.rst:147 +msgid "" +"The initialization function is typically the only non-\\ ``static`` item " +"defined in the module's C source." +msgstr "" + +#: ../../c-api/extension-modules.rst:154 +msgid "Multi-phase initialization" +msgstr "" + +#: ../../c-api/extension-modules.rst:156 +msgid "" +"Normally, the :ref:`initialization function ` " +"(``PyInit_modulename``) returns a :c:type:`PyModuleDef` instance with non-" +"``NULL`` :c:member:`~PyModuleDef.m_slots`. Before it is returned, the " +"``PyModuleDef`` instance must be initialized using the following function:" +msgstr "" + +#: ../../c-api/extension-modules.rst:165 +msgid "" +"Ensure a module definition is a properly initialized Python object that " +"correctly reports its type and a reference count." +msgstr "" + +#: ../../c-api/extension-modules.rst:168 +msgid "Return *def* cast to ``PyObject*``, or ``NULL`` if an error occurred." +msgstr "" + +#: ../../c-api/extension-modules.rst:170 +msgid "" +"Calling this function is required for :ref:`multi-phase-initialization`. It " +"should not be used in other contexts." +msgstr "" + +#: ../../c-api/extension-modules.rst:173 +msgid "" +"Note that Python assumes that ``PyModuleDef`` structures are statically " +"allocated. This function may return either a new reference or a borrowed " +"one; this reference must not be released." +msgstr "" + +#: ../../c-api/extension-modules.rst:184 +msgid "Legacy single-phase initialization" +msgstr "" + +#: ../../c-api/extension-modules.rst:187 +msgid "" +"Single-phase initialization is a legacy mechanism to initialize extension " +"modules, with known drawbacks and design flaws. Extension module authors are " +"encouraged to use multi-phase initialization instead." +msgstr "" + +#: ../../c-api/extension-modules.rst:191 +msgid "" +"In single-phase initialization, the :ref:`initialization function ` (``PyInit_modulename``) should create, populate and return a " +"module object. This is typically done using :c:func:`PyModule_Create` and " +"functions like :c:func:`PyModule_AddObjectRef`." +msgstr "" + +#: ../../c-api/extension-modules.rst:197 +msgid "" +"Single-phase initialization differs from the :ref:`default ` in the following ways:" +msgstr "" + +#: ../../c-api/extension-modules.rst:200 +msgid "Single-phase modules are, or rather *contain*, “singletons”." +msgstr "" + +#: ../../c-api/extension-modules.rst:202 +msgid "" +"When the module is first initialized, Python saves the contents of the " +"module's ``__dict__`` (that is, typically, the module's functions and types)." +msgstr "" + +#: ../../c-api/extension-modules.rst:206 +msgid "" +"For subsequent imports, Python does not call the initialization function " +"again. Instead, it creates a new module object with a new ``__dict__``, and " +"copies the saved contents to it. For example, given a single-phase module " +"``_testsinglephase`` [#testsinglephase]_ that defines a function ``sum`` and " +"an exception class ``error``:" +msgstr "" + +#: ../../c-api/extension-modules.rst:214 +msgid "" +">>> import sys\n" +">>> import _testsinglephase as one\n" +">>> del sys.modules['_testsinglephase']\n" +">>> import _testsinglephase as two\n" +">>> one is two\n" +"False\n" +">>> one.__dict__ is two.__dict__\n" +"False\n" +">>> one.sum is two.sum\n" +"True\n" +">>> one.error is two.error\n" +"True" +msgstr "" +">>> import sys\n" +">>> import _testsinglephase as one\n" +">>> del sys.modules['_testsinglephase']\n" +">>> import _testsinglephase as two\n" +">>> one is two\n" +"False\n" +">>> one.__dict__ is two.__dict__\n" +"False\n" +">>> one.sum is two.sum\n" +"True\n" +">>> one.error is two.error\n" +"True" + +#: ../../c-api/extension-modules.rst:229 +msgid "" +"The exact behavior should be considered a CPython implementation detail." +msgstr "" + +#: ../../c-api/extension-modules.rst:231 +msgid "" +"To work around the fact that ``PyInit_modulename`` does not take a *spec* " +"argument, some state of the import machinery is saved and applied to the " +"first suitable module created during the ``PyInit_modulename`` call. " +"Specifically, when a sub-module is imported, this mechanism prepends the " +"parent package name to the name of the module." +msgstr "" + +#: ../../c-api/extension-modules.rst:237 +msgid "" +"A single-phase ``PyInit_modulename`` function should create “its” module " +"object as soon as possible, before any other module objects can be created." +msgstr "" + +#: ../../c-api/extension-modules.rst:240 +msgid "Non-ASCII module names (``PyInitU_modulename``) are not supported." +msgstr "" + +#: ../../c-api/extension-modules.rst:242 +msgid "" +"Single-phase modules support module lookup functions " +"like :c:func:`PyState_FindModule`." +msgstr "" + +#: ../../c-api/extension-modules.rst:245 +msgid "" +"``_testsinglephase`` is an internal module used in CPython's self-test " +"suite; your installation may or may not include it." +msgstr "" diff --git a/c-api/file.po b/c-api/file.po index 053ac91f7a..0adac6462d 100644 --- a/c-api/file.po +++ b/c-api/file.po @@ -1,224 +1,224 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Ching-Lung Chuang, 2015 -# Liang-Bo Wang , 2015 -# Matt Wang , 2022 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-12 00:16+0000\n" -"PO-Revision-Date: 2023-04-24 20:38+0800\n" -"Last-Translator: Matt Wang \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" -"X-Generator: Poedit 3.2.2\n" - -#: ../../c-api/file.rst:6 -msgid "File Objects" -msgstr "檔案物件 (File Objects)" - -#: ../../c-api/file.rst:10 -msgid "" -"These APIs are a minimal emulation of the Python 2 C API for built-in file " -"objects, which used to rely on the buffered I/O (:c:expr:`FILE*`) support " -"from the C standard library. In Python 3, files and streams use the new :" -"mod:`io` module, which defines several layers over the low-level unbuffered " -"I/O of the operating system. The functions described below are convenience " -"C wrappers over these new APIs, and meant mostly for internal error " -"reporting in the interpreter; third-party code is advised to access the :mod:" -"`io` APIs instead." -msgstr "" -"這些 API 是用於內建檔案物件的 Python 2 C API 的最小模擬 (minimal emulation)，" -"它過去依賴於 C 標準函式庫對於緩衝 I/O (:c:expr:`FILE*`) 的支援。在 Python 3 " -"中，檔案和串流使用新的 :mod:`io` 模組，它在作業系統的低階無緩衝 I/O 上定義了" -"多個層級。下面描述的函式是這些新 API 的便捷 C 包裝器，主要用於直譯器中的內部" -"錯誤報告；建議第三方程式碼改為存取 :mod:`io` API。" - -#: ../../c-api/file.rst:22 -msgid "" -"Create a Python file object from the file descriptor of an already opened " -"file *fd*. The arguments *name*, *encoding*, *errors* and *newline* can be " -"``NULL`` to use the defaults; *buffering* can be *-1* to use the default. " -"*name* is ignored and kept for backward compatibility. Return ``NULL`` on " -"failure. For a more comprehensive description of the arguments, please refer " -"to the :func:`io.open` function documentation." -msgstr "" -"從已打開檔案 *fd* 的檔案描述器建立一個 Python 檔案物件。引數 *name*、" -"*encoding*、*errors* 和 *newline* 可以為 ``NULL`` 以使用預設值； *buffering* " -"可以是 *-1* 以使用預設值。 *name* 被忽略並保留以實作向後相容性。失敗時回傳 " -"``NULL``。有關引數的更全面描述，請參閱 :func:`io.open` 函式文件。" - -#: ../../c-api/file.rst:31 -msgid "" -"Since Python streams have their own buffering layer, mixing them with OS-" -"level file descriptors can produce various issues (such as unexpected " -"ordering of data)." -msgstr "" -"由於 Python 串流有自己的緩衝層，將它們與作業系統層級檔案描述器混合使用會產生" -"各種問題（例如資料的排序不符合預期）。" - -#: ../../c-api/file.rst:35 -msgid "Ignore *name* attribute." -msgstr "忽略 *name* 屬性。" - -#: ../../c-api/file.rst:41 -msgid "" -"Return the file descriptor associated with *p* as an :c:expr:`int`. If the " -"object is an integer, its value is returned. If not, the object's :meth:" -"`~io.IOBase.fileno` method is called if it exists; the method must return an " -"integer, which is returned as the file descriptor value. Sets an exception " -"and returns ``-1`` on failure." -msgstr "" -"回傳與 *p* 關聯的檔案描述器作為 :c:expr:`int`。如果物件是整數，則回傳其值。如" -"果不是整數，則呼叫物件的 :meth:`~io.IOBase.fileno` 方法（如果存在）；該方法必" -"須回傳一個整數，它作為檔案描述器值回傳。設定例外並在失敗時回傳 ``-1``。" - -#: ../../c-api/file.rst:52 -msgid "" -"Equivalent to ``p.readline([n])``, this function reads one line from the " -"object *p*. *p* may be a file object or any object with a :meth:`~io.IOBase." -"readline` method. If *n* is ``0``, exactly one line is read, regardless of " -"the length of the line. If *n* is greater than ``0``, no more than *n* " -"bytes will be read from the file; a partial line can be returned. In both " -"cases, an empty string is returned if the end of the file is reached " -"immediately. If *n* is less than ``0``, however, one line is read " -"regardless of length, but :exc:`EOFError` is raised if the end of the file " -"is reached immediately." -msgstr "" -"相當於 ``p.readline([n])``，這個函式從物件 *p* 中讀取一行。 *p* 可以是檔案物" -"件或任何具有 :meth:`~io.IOBase.readline` 方法的物件。如果 *n* 為 ``0``，則不" -"管該行的長度都只會讀取一行。如果 *n* 大於 ``0``，則不會從檔案中讀取超過 *n* " -"個位元組；可以回傳該行的一部分。在這兩種情況下，如果立即到達檔案末尾，則回傳" -"一個空字串。但是，如果 *n* 小於 ``0``，無論長度如何，都會讀取一行，但如果立即" -"到達檔案末尾，則會引發 :exc:`EOFError`。" - -#: ../../c-api/file.rst:65 -msgid "" -"Overrides the normal behavior of :func:`io.open_code` to pass its parameter " -"through the provided handler." -msgstr "" -"覆蓋 :func:`io.open_code` 的正常行為以透過提供的處理程式 (handler) 傳遞其參" -"數。" - -#: ../../c-api/file.rst:68 -msgid "The *handler* is a function of type:" -msgstr "*handler* 是以下類型的函式：" - -#: ../../c-api/file.rst:73 -msgid "" -"Equivalent of :c:expr:`PyObject *(\\*)(PyObject *path, void *userData)`, " -"where *path* is guaranteed to be :c:type:`PyUnicodeObject`." -msgstr "" -"相當於 :c:expr:`PyObject *(\\*)(PyObject *path, void *userData)`，其中 " -"*path* 保證為 :c:type:`PyUnicodeObject`。" - -#: ../../c-api/file.rst:77 -msgid "" -"The *userData* pointer is passed into the hook function. Since hook " -"functions may be called from different runtimes, this pointer should not " -"refer directly to Python state." -msgstr "" -"*userData* 指標被傳遞到掛鉤函式 (hook function) 中。由於可能會從不同的執行環" -"境 (runtime) 呼叫掛鉤函式，因此該指標不應直接指向 Python 狀態。" - -#: ../../c-api/file.rst:81 -msgid "" -"As this hook is intentionally used during import, avoid importing new " -"modules during its execution unless they are known to be frozen or available " -"in ``sys.modules``." -msgstr "" -"由於此掛鉤函式是在導入期間有意使用的，因此請避免在其執行期間導入新模組，除非" -"它們已知有被凍結或在 ``sys.modules`` 中可用。" - -#: ../../c-api/file.rst:85 -msgid "" -"Once a hook has been set, it cannot be removed or replaced, and later calls " -"to :c:func:`PyFile_SetOpenCodeHook` will fail. On failure, the function " -"returns -1 and sets an exception if the interpreter has been initialized." -msgstr "" -"一旦設定了一個掛鉤函式，它就不能被刪除或替換，且後續對 :c:func:" -"`PyFile_SetOpenCodeHook` 的呼叫將會失敗。失敗時，函式回傳 -1 且若直譯器已初始" -"化便會設定例外。" - -#: ../../c-api/file.rst:89 -msgid "This function is safe to call before :c:func:`Py_Initialize`." -msgstr "在 :c:func:`Py_Initialize` 之前呼叫此函式是安全的。" - -#: ../../c-api/file.rst:91 -msgid "" -"Raises an :ref:`auditing event ` ``setopencodehook`` with no " -"arguments." -msgstr "" -"不帶引數地引發一個\\ :ref:`稽核事件 (auditing event) ` " -"``setopencodehook``。" - -#: ../../c-api/file.rst:98 -msgid "" -"Open *path* with the mode ``'rb'``. *path* must be a Python :class:`str` " -"object. The behavior of this function may be overridden by :c:func:" -"`PyFile_SetOpenCodeHook` to allow for some preprocessing of the text." -msgstr "" -"以模式 ``'rb'`` 開啟 *path*。*path* 必須是 Python :class:`str` 物件。此函式的" -"行為可能會被 :c:func:`PyFile_SetOpenCodeHook` 覆蓋，以允許對文字進行某些預處理。" - -#: ../../c-api/file.rst:103 -msgid "This is analogous to :func:`io.open_code` in Python." -msgstr "這類似於 Python 中的 :func:`io.open_code`。" - -#: ../../c-api/file.rst:105 -msgid "" -"On success, this function returns a :term:`strong reference` to a Python " -"file object. On failure, this function returns ``NULL`` with an exception " -"set." -msgstr "" -"成功時，此函式回傳對 Python 檔案物件的 :term:`strong reference`。失敗時，回傳 ``NULL`` 並設定例外。" - -#: ../../c-api/file.rst:114 -msgid "" -"Similar to :c:func:`PyFile_OpenCodeObject`, but *path* is a UTF-8 encoded :c:" -"expr:`const char*`." -msgstr "" -"類似於 :c:func:`PyFile_OpenCodeObject`，但 *path* 是 UTF-8 編碼的 :c:expr:`const char*`。" - -#: ../../c-api/file.rst:124 -msgid "" -"Write object *obj* to file object *p*. The only supported flag for *flags* " -"is :c:macro:`Py_PRINT_RAW`; if given, the :func:`str` of the object is " -"written instead of the :func:`repr`. Return ``0`` on success or ``-1`` on " -"failure; the appropriate exception will be set." -msgstr "" -"將物件 *obj* 寫入檔案物件 *p*。 *flags* 唯一支援的旗標是 :c:macro:" -"`Py_PRINT_RAW`；如果有給定，則寫入物件的 :func:`str` 而不是 :func:`repr`。在" -"成功回傳 ``0`` 或在失敗回傳 ``-1``；將設定適當的例外。" - -#: ../../c-api/file.rst:132 -msgid "" -"Write string *s* to file object *p*. Return ``0`` on success or ``-1`` on " -"failure; the appropriate exception will be set." -msgstr "" -"寫入字串 *s* 到 檔案物件 *p*。當成功時回傳 0，而當失敗時回傳 -1，並會設定合適" -"的例外狀況。" - -#: ../../c-api/file.rst:8 -msgid "object" -msgstr "object（物件）" - -#: ../../c-api/file.rst:8 -msgid "file" -msgstr "file（檔案）" - -#: ../../c-api/file.rst:50 -msgid "EOFError (built-in exception)" -msgstr "EOFError（內建例外）" - -#: ../../c-api/file.rst:122 -msgid "Py_PRINT_RAW (C macro)" -msgstr "Py_PRINT_RAW（C 巨集）" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Ching-Lung Chuang, 2015 +# Liang-Bo Wang , 2015 +# Matt Wang , 2022 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-12 00:16+0000\n" +"PO-Revision-Date: 2023-04-24 20:38+0800\n" +"Last-Translator: Matt Wang \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" +"X-Generator: Poedit 3.2.2\n" + +#: ../../c-api/file.rst:6 +msgid "File Objects" +msgstr "檔案物件 (File Objects)" + +#: ../../c-api/file.rst:10 +msgid "" +"These APIs are a minimal emulation of the Python 2 C API for built-in file " +"objects, which used to rely on the buffered I/O (:c:expr:`FILE*`) support " +"from the C standard library. In Python 3, files and streams use the new :" +"mod:`io` module, which defines several layers over the low-level unbuffered " +"I/O of the operating system. The functions described below are convenience " +"C wrappers over these new APIs, and meant mostly for internal error " +"reporting in the interpreter; third-party code is advised to access the :mod:" +"`io` APIs instead." +msgstr "" +"這些 API 是用於內建檔案物件的 Python 2 C API 的最小模擬 (minimal emulation)，" +"它過去依賴於 C 標準函式庫對於緩衝 I/O (:c:expr:`FILE*`) 的支援。在 Python 3 " +"中，檔案和串流使用新的 :mod:`io` 模組，它在作業系統的低階無緩衝 I/O 上定義了" +"多個層級。下面描述的函式是這些新 API 的便捷 C 包裝器，主要用於直譯器中的內部" +"錯誤報告；建議第三方程式碼改為存取 :mod:`io` API。" + +#: ../../c-api/file.rst:22 +msgid "" +"Create a Python file object from the file descriptor of an already opened " +"file *fd*. The arguments *name*, *encoding*, *errors* and *newline* can be " +"``NULL`` to use the defaults; *buffering* can be *-1* to use the default. " +"*name* is ignored and kept for backward compatibility. Return ``NULL`` on " +"failure. For a more comprehensive description of the arguments, please refer " +"to the :func:`io.open` function documentation." +msgstr "" +"從已打開檔案 *fd* 的檔案描述器建立一個 Python 檔案物件。引數 *name*、" +"*encoding*、*errors* 和 *newline* 可以為 ``NULL`` 以使用預設值； *buffering* " +"可以是 *-1* 以使用預設值。 *name* 被忽略並保留以實作向後相容性。失敗時回傳 " +"``NULL``。有關引數的更全面描述，請參閱 :func:`io.open` 函式文件。" + +#: ../../c-api/file.rst:31 +msgid "" +"Since Python streams have their own buffering layer, mixing them with OS-" +"level file descriptors can produce various issues (such as unexpected " +"ordering of data)." +msgstr "" +"由於 Python 串流有自己的緩衝層，將它們與作業系統層級檔案描述器混合使用會產生" +"各種問題（例如資料的排序不符合預期）。" + +#: ../../c-api/file.rst:35 +msgid "Ignore *name* attribute." +msgstr "忽略 *name* 屬性。" + +#: ../../c-api/file.rst:41 +msgid "" +"Return the file descriptor associated with *p* as an :c:expr:`int`. If the " +"object is an integer, its value is returned. If not, the object's :meth:" +"`~io.IOBase.fileno` method is called if it exists; the method must return an " +"integer, which is returned as the file descriptor value. Sets an exception " +"and returns ``-1`` on failure." +msgstr "" +"回傳與 *p* 關聯的檔案描述器作為 :c:expr:`int`。如果物件是整數，則回傳其值。如" +"果不是整數，則呼叫物件的 :meth:`~io.IOBase.fileno` 方法（如果存在）；該方法必" +"須回傳一個整數，它作為檔案描述器值回傳。設定例外並在失敗時回傳 ``-1``。" + +#: ../../c-api/file.rst:52 +msgid "" +"Equivalent to ``p.readline([n])``, this function reads one line from the " +"object *p*. *p* may be a file object or any object with a :meth:`~io.IOBase." +"readline` method. If *n* is ``0``, exactly one line is read, regardless of " +"the length of the line. If *n* is greater than ``0``, no more than *n* " +"bytes will be read from the file; a partial line can be returned. In both " +"cases, an empty string is returned if the end of the file is reached " +"immediately. If *n* is less than ``0``, however, one line is read " +"regardless of length, but :exc:`EOFError` is raised if the end of the file " +"is reached immediately." +msgstr "" +"相當於 ``p.readline([n])``，這個函式從物件 *p* 中讀取一行。 *p* 可以是檔案物" +"件或任何具有 :meth:`~io.IOBase.readline` 方法的物件。如果 *n* 為 ``0``，則不" +"管該行的長度都只會讀取一行。如果 *n* 大於 ``0``，則不會從檔案中讀取超過 *n* " +"個位元組；可以回傳該行的一部分。在這兩種情況下，如果立即到達檔案末尾，則回傳" +"一個空字串。但是，如果 *n* 小於 ``0``，無論長度如何，都會讀取一行，但如果立即" +"到達檔案末尾，則會引發 :exc:`EOFError`。" + +#: ../../c-api/file.rst:65 +msgid "" +"Overrides the normal behavior of :func:`io.open_code` to pass its parameter " +"through the provided handler." +msgstr "" +"覆蓋 :func:`io.open_code` 的正常行為以透過提供的處理程式 (handler) 傳遞其參" +"數。" + +#: ../../c-api/file.rst:68 +msgid "The *handler* is a function of type:" +msgstr "*handler* 是以下類型的函式：" + +#: ../../c-api/file.rst:73 +msgid "" +"Equivalent of :c:expr:`PyObject *(\\*)(PyObject *path, void *userData)`, " +"where *path* is guaranteed to be :c:type:`PyUnicodeObject`." +msgstr "" +"相當於 :c:expr:`PyObject *(\\*)(PyObject *path, void *userData)`，其中 " +"*path* 保證為 :c:type:`PyUnicodeObject`。" + +#: ../../c-api/file.rst:77 +msgid "" +"The *userData* pointer is passed into the hook function. Since hook " +"functions may be called from different runtimes, this pointer should not " +"refer directly to Python state." +msgstr "" +"*userData* 指標被傳遞到掛鉤函式 (hook function) 中。由於可能會從不同的執行環" +"境 (runtime) 呼叫掛鉤函式，因此該指標不應直接指向 Python 狀態。" + +#: ../../c-api/file.rst:81 +msgid "" +"As this hook is intentionally used during import, avoid importing new " +"modules during its execution unless they are known to be frozen or available " +"in ``sys.modules``." +msgstr "" +"由於此掛鉤函式是在導入期間有意使用的，因此請避免在其執行期間導入新模組，除非" +"它們已知有被凍結或在 ``sys.modules`` 中可用。" + +#: ../../c-api/file.rst:85 +msgid "" +"Once a hook has been set, it cannot be removed or replaced, and later calls " +"to :c:func:`PyFile_SetOpenCodeHook` will fail. On failure, the function " +"returns -1 and sets an exception if the interpreter has been initialized." +msgstr "" +"一旦設定了一個掛鉤函式，它就不能被刪除或替換，且後續對 :c:func:" +"`PyFile_SetOpenCodeHook` 的呼叫將會失敗。失敗時，函式回傳 -1 且若直譯器已初始" +"化便會設定例外。" + +#: ../../c-api/file.rst:89 +msgid "This function is safe to call before :c:func:`Py_Initialize`." +msgstr "在 :c:func:`Py_Initialize` 之前呼叫此函式是安全的。" + +#: ../../c-api/file.rst:91 +msgid "" +"Raises an :ref:`auditing event ` ``setopencodehook`` with no " +"arguments." +msgstr "" +"不帶引數地引發一個\\ :ref:`稽核事件 (auditing event) ` " +"``setopencodehook``。" + +#: ../../c-api/file.rst:98 +msgid "" +"Open *path* with the mode ``'rb'``. *path* must be a Python :class:`str` " +"object. The behavior of this function may be overridden by :c:func:" +"`PyFile_SetOpenCodeHook` to allow for some preprocessing of the text." +msgstr "" +"以模式 ``'rb'`` 開啟 *path*。*path* 必須是 Python :class:`str` 物件。此函式的" +"行為可能會被 :c:func:`PyFile_SetOpenCodeHook` 覆蓋，以允許對文字進行某些預處理。" + +#: ../../c-api/file.rst:103 +msgid "This is analogous to :func:`io.open_code` in Python." +msgstr "這類似於 Python 中的 :func:`io.open_code`。" + +#: ../../c-api/file.rst:105 +msgid "" +"On success, this function returns a :term:`strong reference` to a Python " +"file object. On failure, this function returns ``NULL`` with an exception " +"set." +msgstr "" +"成功時，此函式回傳對 Python 檔案物件的 :term:`strong reference`。失敗時，回傳 ``NULL`` 並設定例外。" + +#: ../../c-api/file.rst:114 +msgid "" +"Similar to :c:func:`PyFile_OpenCodeObject`, but *path* is a UTF-8 encoded :c:" +"expr:`const char*`." +msgstr "" +"類似於 :c:func:`PyFile_OpenCodeObject`，但 *path* 是 UTF-8 編碼的 :c:expr:`const char*`。" + +#: ../../c-api/file.rst:124 +msgid "" +"Write object *obj* to file object *p*. The only supported flag for *flags* " +"is :c:macro:`Py_PRINT_RAW`; if given, the :func:`str` of the object is " +"written instead of the :func:`repr`. Return ``0`` on success or ``-1`` on " +"failure; the appropriate exception will be set." +msgstr "" +"將物件 *obj* 寫入檔案物件 *p*。 *flags* 唯一支援的旗標是 :c:macro:" +"`Py_PRINT_RAW`；如果有給定，則寫入物件的 :func:`str` 而不是 :func:`repr`。在" +"成功回傳 ``0`` 或在失敗回傳 ``-1``；將設定適當的例外。" + +#: ../../c-api/file.rst:132 +msgid "" +"Write string *s* to file object *p*. Return ``0`` on success or ``-1`` on " +"failure; the appropriate exception will be set." +msgstr "" +"寫入字串 *s* 到 檔案物件 *p*。當成功時回傳 0，而當失敗時回傳 -1，並會設定合適" +"的例外狀況。" + +#: ../../c-api/file.rst:8 +msgid "object" +msgstr "object（物件）" + +#: ../../c-api/file.rst:8 +msgid "file" +msgstr "file（檔案）" + +#: ../../c-api/file.rst:50 +msgid "EOFError (built-in exception)" +msgstr "EOFError（內建例外）" + +#: ../../c-api/file.rst:122 +msgid "Py_PRINT_RAW (C macro)" +msgstr "Py_PRINT_RAW（C 巨集）" diff --git a/c-api/float.po b/c-api/float.po index d0f41f7aee..9de87801c3 100644 --- a/c-api/float.po +++ b/c-api/float.po @@ -1,397 +1,397 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Ching-Lung Chuang, 2015 -# Liang-Bo Wang , 2015 -# Matt Wang , 2025 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-19 00:14+0000\n" -"PO-Revision-Date: 2025-11-07 05:06+0000\n" -"Last-Translator: Matt Wang \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" - -#: ../../c-api/float.rst:6 -msgid "Floating-Point Objects" -msgstr "浮點數（Floating-Point）物件" - -#: ../../c-api/float.rst:13 -msgid "" -"This subtype of :c:type:`PyObject` represents a Python floating-point object." -msgstr "這個 :c:type:`PyObject` 的子型別代表一個 Python 浮點數物件。" - -#: ../../c-api/float.rst:18 -msgid "" -"This instance of :c:type:`PyTypeObject` represents the Python floating-point " -"type. This is the same object as :class:`float` in the Python layer." -msgstr "" -"這個 :c:type:`PyTypeObject` 的實例代表 Python 浮點數型別。這與 Python 層中" -"的 :class:`float` 物件相同。" - -#: ../../c-api/float.rst:24 -msgid "" -"Return true if its argument is a :c:type:`PyFloatObject` or a subtype of :c:" -"type:`PyFloatObject`. This function always succeeds." -msgstr "" -"如果其引數是 :c:type:`PyFloatObject` 或 :c:type:`PyFloatObject` 的子型別，則" -"回傳 true。這個函式不會失敗。" - -#: ../../c-api/float.rst:30 -msgid "" -"Return true if its argument is a :c:type:`PyFloatObject`, but not a subtype " -"of :c:type:`PyFloatObject`. This function always succeeds." -msgstr "" -"如果其引數是 :c:type:`PyFloatObject`，但不是 :c:type:`PyFloatObject` 的子型" -"別，則回傳 true。這個函式不會失敗。" - -#: ../../c-api/float.rst:36 -msgid "" -"Create a :c:type:`PyFloatObject` object based on the string value in *str*, " -"or ``NULL`` on failure." -msgstr "" -"建立一個基於字串值 *str* 的 :c:type:`PyFloatObject` 物件，失敗時回傳 " -"``NULL``。" - -#: ../../c-api/float.rst:42 -msgid "" -"Create a :c:type:`PyFloatObject` object from *v*, or ``NULL`` on failure." -msgstr "" -"建立一個來自 *v* 的 :c:type:`PyFloatObject` 物件，失敗時回傳 ``NULL``。" - -#: ../../c-api/float.rst:47 -msgid "" -"Return a C :c:expr:`double` representation of the contents of *pyfloat*. If " -"*pyfloat* is not a Python floating-point object but has a :meth:`~object." -"__float__` method, this method will first be called to convert *pyfloat* " -"into a float. If :meth:`!__float__` is not defined then it falls back to :" -"meth:`~object.__index__`. This method returns ``-1.0`` upon failure, so one " -"should call :c:func:`PyErr_Occurred` to check for errors." -msgstr "" -"回傳 *pyfloat* 內容的 C :c:expr:`double` 表示形式。如果 *pyfloat* 不是 " -"Python 浮點數物件，但具有 :meth:`~object.__float__` 方法，則會先呼叫此方法將 " -"*pyfloat* 轉換為浮點數。如果未定義 :meth:`!__float__`，則會用後備方法 :meth:" -"`~object.__index__`。此方法在失敗時回傳 ``-1.0``，因此應該呼叫 :c:func:" -"`PyErr_Occurred` 來檢查錯誤。" - -#: ../../c-api/float.rst:54 -msgid "Use :meth:`~object.__index__` if available." -msgstr "請使用 :meth:`~object.__index__`\\ （如果可用）。" - -#: ../../c-api/float.rst:60 -msgid "" -"Return a C :c:expr:`double` representation of the contents of *pyfloat*, but " -"without error checking." -msgstr "回傳 *pyfloat* 內容的 C :c:expr:`double` 表示形式，但不進行錯誤檢查。" - -#: ../../c-api/float.rst:66 -msgid "" -"Return a structseq instance which contains information about the precision, " -"minimum and maximum values of a float. It's a thin wrapper around the header " -"file :file:`float.h`." -msgstr "" -"回傳一個 structseq 實例，其中包含有關浮點數的精度、最小值和最大值的資訊。它是" -"對標頭檔 :file:`float.h` 的簡單封裝。" - -#: ../../c-api/float.rst:73 -msgid "" -"Return the maximum representable finite float *DBL_MAX* as C :c:expr:" -"`double`." -msgstr "將可表示的最大有限浮點數 *DBL_MAX* 作為 C :c:expr:`double` 回傳。" - -#: ../../c-api/float.rst:78 -msgid "" -"Return the minimum normalized positive float *DBL_MIN* as C :c:expr:`double`." -msgstr "將最小的正規化浮點數 *DBL_MIN* 作為 C :c:expr:`double` 回傳。" - -#: ../../c-api/float.rst:83 -msgid "" -"This macro expands a to constant expression of type :c:expr:`double`, that " -"represents the positive infinity." -msgstr "這個巨集會展開為一型別為 :c:expr:`double` 的常數運算式，表示正無窮大。" - -#: ../../c-api/float.rst:86 -msgid "" -"On most platforms, this is equivalent to the :c:macro:`!INFINITY` macro from " -"the C11 standard ```` header." -msgstr "" -"在大多數平台上，這相當於 C11 標準 ```` 標頭檔中的 :c:macro:`!" -"INFINITY` 巨集。" - -#: ../../c-api/float.rst:92 -msgid "" -"This macro expands a to constant expression of type :c:expr:`double`, that " -"represents a quiet not-a-number (qNaN) value." -msgstr "" -"這個巨集會展開為一型別為 :c:expr:`double` 的常數運算式，表示安靜型 NaN " -"(qNaN) 值。" - -#: ../../c-api/float.rst:95 -msgid "" -"On most platforms, this is equivalent to the :c:macro:`!NAN` macro from the " -"C11 standard ```` header." -msgstr "" -"在大多數平台上，這相當於 C11 標準 ```` 標頭檔中的 :c:macro:`!NAN` 巨" -"集。" - -#: ../../c-api/float.rst:101 -msgid "Equivalent to :c:macro:`!INFINITY`." -msgstr "與 :c:macro:`!INFINITY` 等價。" - -#: ../../c-api/float.rst:103 -msgid "The macro is :term:`soft deprecated`." -msgstr "這個巨集已被\\ :term:`軟性棄用 `。" - -#: ../../c-api/float.rst:109 -msgid "" -"The definition (accurate for a :c:expr:`double` type) of the :data:`math.e` " -"constant." -msgstr ":data:`math.e` 常數的定義（對 :c:expr:`double` 型別而言是準確的）。" - -#: ../../c-api/float.rst:114 -msgid "High precision (long double) definition of :data:`~math.e` constant." -msgstr "高精度（long double）定義的 :data:`~math.e` 常數。" - -#: ../../c-api/float.rst:119 -msgid "" -"The definition (accurate for a :c:expr:`double` type) of the :data:`math.pi` " -"constant." -msgstr ":data:`math.pi` 常數的定義（對 :c:expr:`double` 型別而言是準確的）。" - -#: ../../c-api/float.rst:124 -msgid "High precision (long double) definition of :data:`~math.pi` constant." -msgstr "高精度（long double）定義的 :data:`~math.pi` 常數。" - -#: ../../c-api/float.rst:129 -msgid "" -"The definition (accurate for a :c:expr:`double` type) of the :data:`math." -"tau` constant." -msgstr ":data:`math.tau` 常數的定義（對 :c:expr:`double` 型別而言是準確的）。" - -#: ../../c-api/float.rst:136 -msgid "Return :data:`math.nan` from a function." -msgstr "從函式回傳 :data:`math.nan`。" - -#: ../../c-api/float.rst:138 -msgid "" -"On most platforms, this is equivalent to ``return PyFloat_FromDouble(NAN)``." -msgstr "在大多數平台上，這相當於 ``return PyFloat_FromDouble(NAN)``。" - -#: ../../c-api/float.rst:143 -msgid "" -"Return :data:`math.inf` or :data:`-math.inf ` from a function, " -"depending on the sign of *sign*." -msgstr "" -"根據 *sign* 的正負號，從函式回傳 :data:`math.inf` 或 :data:`-math.inf `。" - -#: ../../c-api/float.rst:146 -msgid "On most platforms, this is equivalent to the following::" -msgstr "在大多數平台上，這相當於以下內容： ::" - -#: ../../c-api/float.rst:148 -msgid "return PyFloat_FromDouble(copysign(INFINITY, sign));" -msgstr "return PyFloat_FromDouble(copysign(INFINITY, sign));" - -#: ../../c-api/float.rst:153 -msgid "" -"Return ``1`` if the given floating-point number *X* is finite, that is, it " -"is normal, subnormal or zero, but not infinite or NaN. Return ``0`` " -"otherwise." -msgstr "" -"如果給定的浮點數 *X* 是有限的（即為正規數 (normal)、次正規數 (subnormal) 或零，但不是無窮大或 NaN），" -"則回傳 ``1``。否則回傳 ``0``。" - -#: ../../c-api/float.rst:157 -msgid "" -"The macro is :term:`soft deprecated`. Use :c:macro:`!isfinite` instead." -msgstr "此巨集已被\\ :term:`軟性棄用 `。請改用 :c:macro:`!isfinite`。" - -#: ../../c-api/float.rst:163 -msgid "" -"Return ``1`` if the given floating-point number *X* is positive or negative " -"infinity. Return ``0`` otherwise." -msgstr "" -"如果給定的浮點數 *X* 是正無窮大或負無窮大，則回傳 ``1``。否則回傳 ``0``。" - -#: ../../c-api/float.rst:166 -msgid "The macro is :term:`soft deprecated`. Use :c:macro:`!isinf` instead." -msgstr "此巨集已被\\ :term:`軟性棄用 `。請改用 :c:macro:`!isinf`。" - -#: ../../c-api/float.rst:172 -msgid "" -"Return ``1`` if the given floating-point number *X* is a not-a-number (NaN) " -"value. Return ``0`` otherwise." -msgstr "" -"如果給定的浮點數 *X* 是非數值 (NaN)，則回傳 ``1``。否則回傳 ``0``。" - -#: ../../c-api/float.rst:175 -msgid "The macro is :term:`soft deprecated`. Use :c:macro:`!isnan` instead." -msgstr "此巨集已被\\ :term:`軟性棄用 `。請改用 :c:macro:`!isnan`。" - -#: ../../c-api/float.rst:180 -msgid "Pack and Unpack functions" -msgstr "打包和解包函式" - -#: ../../c-api/float.rst:182 -msgid "" -"The pack and unpack functions provide an efficient platform-independent way " -"to store floating-point values as byte strings. The Pack routines produce a " -"bytes string from a C :c:expr:`double`, and the Unpack routines produce a C :" -"c:expr:`double` from such a bytes string. The suffix (2, 4 or 8) specifies " -"the number of bytes in the bytes string." -msgstr "" -"打包和解包函式提供了一種有效的跨平台方式，來將浮點數值儲存為位元組字串。打包" -"例程從 C :c:expr:`double` 產生位元組字串，而解包例程則從這樣的位元組字串產生 " -"C :c:expr:`double`。後綴（2、4 或 8）標示了位元組字串中的位元組數。" - -#: ../../c-api/float.rst:188 -msgid "" -"On platforms that appear to use IEEE 754 formats these functions work by " -"copying bits. On other platforms, the 2-byte format is identical to the IEEE " -"754 binary16 half-precision format, the 4-byte format (32-bit) is identical " -"to the IEEE 754 binary32 single precision format, and the 8-byte format to " -"the IEEE 754 binary64 double precision format, although the packing of INFs " -"and NaNs (if such things exist on the platform) isn't handled correctly, and " -"attempting to unpack a bytes string containing an IEEE INF or NaN will raise " -"an exception." -msgstr "" -"在看似使用 IEEE 754 格式的平台上，這些函式是透過複製位元來運作的。在其他平台" -"上，2 位元組格式與 IEEE 754 binary16 半精度格式相同，4 位元組格式（32 位元）" -"與 IEEE 754 binary32 單精度格式相同，8 位元組格式與 IEEE 754 binary64 雙精度" -"格式相同。儘管如此，INF 和 NaN（如果這些東西在平台上存在）的打包並未正確處" -"理，並且嘗試解包包含 IEEE INF 或 NaN 的位元組字串將引發例外。" - -#: ../../c-api/float.rst:197 -msgid "" -"Note that NaNs type may not be preserved on IEEE platforms (signaling NaN " -"become quiet NaN), for example on x86 systems in 32-bit mode." -msgstr "" -"請注意，在 IEEE 平台上可能無法保留 NaN 型別（「訊號型 NaN (signaling NaN)」會" -"變成「安靜型 NaN (quiet NaN)」），例如在 32 位元模式的 x86 系統上。" - -#: ../../c-api/float.rst:200 -msgid "" -"On non-IEEE platforms with more precision, or larger dynamic range, than " -"IEEE 754 supports, not all values can be packed; on non-IEEE platforms with " -"less precision, or smaller dynamic range, not all values can be unpacked. " -"What happens in such cases is partly accidental (alas)." -msgstr "" -"在非 IEEE 平台上，如果精度更高或動態範圍比 IEEE 754 支援的更大，則無法打包所" -"有值；在非 IEEE 平台上，如果精度較低或動態範圍較小，則無法解包所有值。在這種" -"案例下發生的情況在某種程度上是偶然的（唉）。" - -#: ../../c-api/float.rst:208 -msgid "Pack functions" -msgstr "打包函式" - -#: ../../c-api/float.rst:210 -msgid "" -"The pack routines write 2, 4 or 8 bytes, starting at *p*. *le* is an :c:expr:" -"`int` argument, non-zero if you want the bytes string in little-endian " -"format (exponent last, at ``p+1``, ``p+3``, or ``p+6`` ``p+7``), zero if you " -"want big-endian format (exponent first, at *p*). The :c:macro:" -"`PY_BIG_ENDIAN` constant can be used to use the native endian: it is equal " -"to ``1`` on big endian processor, or ``0`` on little endian processor." -msgstr "" -"打包例程會從 *p* 開始寫入 2、4 或 8 位元組。*le* 是一個 :c:expr:`int` 引數，" -"如果你想要位元組字串為小端序格式（指數在最後，位於 ``p+1``、``p+3``、``p+6`` " -"或 ``p+7``），則用非零值；如果你想要大端序格式（指數在最前，位於 *p*），則用" -"零。可以使用 :c:macro:`PY_BIG_ENDIAN` 常數來使用原生端序：在大端序處理器上它" -"等於 ``1``，在小端序處理器上它等於 ``0``。" - -#: ../../c-api/float.rst:217 -msgid "" -"Return value: ``0`` if all is OK, ``-1`` if error (and an exception is set, " -"most likely :exc:`OverflowError`)." -msgstr "" -"回傳值：如果一切正常則為 ``0``，如果發生錯誤則為 ``-1``\\ （並且會設定一個例" -"外，最有可能是 :exc:`OverflowError`）。" - -#: ../../c-api/float.rst:220 -msgid "There are two problems on non-IEEE platforms:" -msgstr "在非 IEEE 平台上有兩個問題：" - -#: ../../c-api/float.rst:222 -msgid "What this does is undefined if *x* is a NaN or infinity." -msgstr "如果 *x* 是 NaN 或無窮大，則這樣做是未定義的。" - -#: ../../c-api/float.rst:223 -msgid "``-0.0`` and ``+0.0`` produce the same bytes string." -msgstr "``-0.0`` 和 ``+0.0`` 會產生同樣的位元組字串。" - -#: ../../c-api/float.rst:227 -msgid "Pack a C double as the IEEE 754 binary16 half-precision format." -msgstr "將 C double 打包為 IEEE 754 binary16 半精度格式。" - -#: ../../c-api/float.rst:231 -msgid "Pack a C double as the IEEE 754 binary32 single precision format." -msgstr "將 C double 打包為 IEEE 754 binary32 單精度格式。" - -#: ../../c-api/float.rst:235 -msgid "Pack a C double as the IEEE 754 binary64 double precision format." -msgstr "將 C double 打包為 IEEE 754 binary64 雙精度格式。" - -#: ../../c-api/float.rst:239 -msgid "Unpack functions" -msgstr "解包函式" - -#: ../../c-api/float.rst:241 -msgid "" -"The unpack routines read 2, 4 or 8 bytes, starting at *p*. *le* is an :c:" -"expr:`int` argument, non-zero if the bytes string is in little-endian format " -"(exponent last, at ``p+1``, ``p+3`` or ``p+6`` and ``p+7``), zero if big-" -"endian (exponent first, at *p*). The :c:macro:`PY_BIG_ENDIAN` constant can " -"be used to use the native endian: it is equal to ``1`` on big endian " -"processor, or ``0`` on little endian processor." -msgstr "" -"解包例程會從 *p* 開始讀取 2、4 或 8 位元組。*le* 是一個 :c:expr:`int` 引數，" -"如果位元組字串為小端序格式（指數在最後，位於 ``p+1``、``p+3``、``p+6`` 或 " -"``p+7``），則用非零值；如果為大端序格式（指數在最前，位於 *p*），則用零。可以" -"使用 :c:macro:`PY_BIG_ENDIAN` 常數來使用原生端序：在大端序處理器上它等於 " -"``1``，在小端序處理器上它等於 ``0``。" - -#: ../../c-api/float.rst:248 -msgid "" -"Return value: The unpacked double. On error, this is ``-1.0`` and :c:func:" -"`PyErr_Occurred` is true (and an exception is set, most likely :exc:" -"`OverflowError`)." -msgstr "" -"回傳值：解包後的 double。發生錯誤時，這是 ``-1.0`` 且 :c:func:" -"`PyErr_Occurred` 為 true（並且會設置一個例外，最有可能是 :exc:" -"`OverflowError`）。" - -#: ../../c-api/float.rst:252 -msgid "" -"Note that on a non-IEEE platform this will refuse to unpack a bytes string " -"that represents a NaN or infinity." -msgstr "" -"請注意，在非 IEEE 平台上，這將拒絕解包會表示為 NaN 或無窮大的位元組字串。" - -#: ../../c-api/float.rst:257 -msgid "Unpack the IEEE 754 binary16 half-precision format as a C double." -msgstr "將 IEEE 754 binary16 半精度格式解包為 C double。" - -#: ../../c-api/float.rst:261 -msgid "Unpack the IEEE 754 binary32 single precision format as a C double." -msgstr "將 IEEE 754 binary32 單精度格式解包為 C double。" - -#: ../../c-api/float.rst:265 -msgid "Unpack the IEEE 754 binary64 double precision format as a C double." -msgstr "將 IEEE 754 binary64 雙精度格式解包為 C double。" - -#: ../../c-api/float.rst:8 -msgid "object" -msgstr "object（物件）" - -#: ../../c-api/float.rst:8 -msgid "floating-point" -msgstr "floating-point（浮點）" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Ching-Lung Chuang, 2015 +# Liang-Bo Wang , 2015 +# Matt Wang , 2025 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-19 00:14+0000\n" +"PO-Revision-Date: 2025-11-07 05:06+0000\n" +"Last-Translator: Matt Wang \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" + +#: ../../c-api/float.rst:6 +msgid "Floating-Point Objects" +msgstr "浮點數（Floating-Point）物件" + +#: ../../c-api/float.rst:13 +msgid "" +"This subtype of :c:type:`PyObject` represents a Python floating-point object." +msgstr "這個 :c:type:`PyObject` 的子型別代表一個 Python 浮點數物件。" + +#: ../../c-api/float.rst:18 +msgid "" +"This instance of :c:type:`PyTypeObject` represents the Python floating-point " +"type. This is the same object as :class:`float` in the Python layer." +msgstr "" +"這個 :c:type:`PyTypeObject` 的實例代表 Python 浮點數型別。這與 Python 層中" +"的 :class:`float` 物件相同。" + +#: ../../c-api/float.rst:24 +msgid "" +"Return true if its argument is a :c:type:`PyFloatObject` or a subtype of :c:" +"type:`PyFloatObject`. This function always succeeds." +msgstr "" +"如果其引數是 :c:type:`PyFloatObject` 或 :c:type:`PyFloatObject` 的子型別，則" +"回傳 true。這個函式不會失敗。" + +#: ../../c-api/float.rst:30 +msgid "" +"Return true if its argument is a :c:type:`PyFloatObject`, but not a subtype " +"of :c:type:`PyFloatObject`. This function always succeeds." +msgstr "" +"如果其引數是 :c:type:`PyFloatObject`，但不是 :c:type:`PyFloatObject` 的子型" +"別，則回傳 true。這個函式不會失敗。" + +#: ../../c-api/float.rst:36 +msgid "" +"Create a :c:type:`PyFloatObject` object based on the string value in *str*, " +"or ``NULL`` on failure." +msgstr "" +"建立一個基於字串值 *str* 的 :c:type:`PyFloatObject` 物件，失敗時回傳 " +"``NULL``。" + +#: ../../c-api/float.rst:42 +msgid "" +"Create a :c:type:`PyFloatObject` object from *v*, or ``NULL`` on failure." +msgstr "" +"建立一個來自 *v* 的 :c:type:`PyFloatObject` 物件，失敗時回傳 ``NULL``。" + +#: ../../c-api/float.rst:47 +msgid "" +"Return a C :c:expr:`double` representation of the contents of *pyfloat*. If " +"*pyfloat* is not a Python floating-point object but has a :meth:`~object." +"__float__` method, this method will first be called to convert *pyfloat* " +"into a float. If :meth:`!__float__` is not defined then it falls back to :" +"meth:`~object.__index__`. This method returns ``-1.0`` upon failure, so one " +"should call :c:func:`PyErr_Occurred` to check for errors." +msgstr "" +"回傳 *pyfloat* 內容的 C :c:expr:`double` 表示形式。如果 *pyfloat* 不是 " +"Python 浮點數物件，但具有 :meth:`~object.__float__` 方法，則會先呼叫此方法將 " +"*pyfloat* 轉換為浮點數。如果未定義 :meth:`!__float__`，則會用後備方法 :meth:" +"`~object.__index__`。此方法在失敗時回傳 ``-1.0``，因此應該呼叫 :c:func:" +"`PyErr_Occurred` 來檢查錯誤。" + +#: ../../c-api/float.rst:54 +msgid "Use :meth:`~object.__index__` if available." +msgstr "請使用 :meth:`~object.__index__`\\ （如果可用）。" + +#: ../../c-api/float.rst:60 +msgid "" +"Return a C :c:expr:`double` representation of the contents of *pyfloat*, but " +"without error checking." +msgstr "回傳 *pyfloat* 內容的 C :c:expr:`double` 表示形式，但不進行錯誤檢查。" + +#: ../../c-api/float.rst:66 +msgid "" +"Return a structseq instance which contains information about the precision, " +"minimum and maximum values of a float. It's a thin wrapper around the header " +"file :file:`float.h`." +msgstr "" +"回傳一個 structseq 實例，其中包含有關浮點數的精度、最小值和最大值的資訊。它是" +"對標頭檔 :file:`float.h` 的簡單封裝。" + +#: ../../c-api/float.rst:73 +msgid "" +"Return the maximum representable finite float *DBL_MAX* as C :c:expr:" +"`double`." +msgstr "將可表示的最大有限浮點數 *DBL_MAX* 作為 C :c:expr:`double` 回傳。" + +#: ../../c-api/float.rst:78 +msgid "" +"Return the minimum normalized positive float *DBL_MIN* as C :c:expr:`double`." +msgstr "將最小的正規化浮點數 *DBL_MIN* 作為 C :c:expr:`double` 回傳。" + +#: ../../c-api/float.rst:83 +msgid "" +"This macro expands a to constant expression of type :c:expr:`double`, that " +"represents the positive infinity." +msgstr "這個巨集會展開為一型別為 :c:expr:`double` 的常數運算式，表示正無窮大。" + +#: ../../c-api/float.rst:86 +msgid "" +"On most platforms, this is equivalent to the :c:macro:`!INFINITY` macro from " +"the C11 standard ```` header." +msgstr "" +"在大多數平台上，這相當於 C11 標準 ```` 標頭檔中的 :c:macro:`!" +"INFINITY` 巨集。" + +#: ../../c-api/float.rst:92 +msgid "" +"This macro expands a to constant expression of type :c:expr:`double`, that " +"represents a quiet not-a-number (qNaN) value." +msgstr "" +"這個巨集會展開為一型別為 :c:expr:`double` 的常數運算式，表示安靜型 NaN " +"(qNaN) 值。" + +#: ../../c-api/float.rst:95 +msgid "" +"On most platforms, this is equivalent to the :c:macro:`!NAN` macro from the " +"C11 standard ```` header." +msgstr "" +"在大多數平台上，這相當於 C11 標準 ```` 標頭檔中的 :c:macro:`!NAN` 巨" +"集。" + +#: ../../c-api/float.rst:101 +msgid "Equivalent to :c:macro:`!INFINITY`." +msgstr "與 :c:macro:`!INFINITY` 等價。" + +#: ../../c-api/float.rst:103 +msgid "The macro is :term:`soft deprecated`." +msgstr "這個巨集已被\\ :term:`軟性棄用 `。" + +#: ../../c-api/float.rst:109 +msgid "" +"The definition (accurate for a :c:expr:`double` type) of the :data:`math.e` " +"constant." +msgstr ":data:`math.e` 常數的定義（對 :c:expr:`double` 型別而言是準確的）。" + +#: ../../c-api/float.rst:114 +msgid "High precision (long double) definition of :data:`~math.e` constant." +msgstr "高精度（long double）定義的 :data:`~math.e` 常數。" + +#: ../../c-api/float.rst:119 +msgid "" +"The definition (accurate for a :c:expr:`double` type) of the :data:`math.pi` " +"constant." +msgstr ":data:`math.pi` 常數的定義（對 :c:expr:`double` 型別而言是準確的）。" + +#: ../../c-api/float.rst:124 +msgid "High precision (long double) definition of :data:`~math.pi` constant." +msgstr "高精度（long double）定義的 :data:`~math.pi` 常數。" + +#: ../../c-api/float.rst:129 +msgid "" +"The definition (accurate for a :c:expr:`double` type) of the :data:`math." +"tau` constant." +msgstr ":data:`math.tau` 常數的定義（對 :c:expr:`double` 型別而言是準確的）。" + +#: ../../c-api/float.rst:136 +msgid "Return :data:`math.nan` from a function." +msgstr "從函式回傳 :data:`math.nan`。" + +#: ../../c-api/float.rst:138 +msgid "" +"On most platforms, this is equivalent to ``return PyFloat_FromDouble(NAN)``." +msgstr "在大多數平台上，這相當於 ``return PyFloat_FromDouble(NAN)``。" + +#: ../../c-api/float.rst:143 +msgid "" +"Return :data:`math.inf` or :data:`-math.inf ` from a function, " +"depending on the sign of *sign*." +msgstr "" +"根據 *sign* 的正負號，從函式回傳 :data:`math.inf` 或 :data:`-math.inf `。" + +#: ../../c-api/float.rst:146 +msgid "On most platforms, this is equivalent to the following::" +msgstr "在大多數平台上，這相當於以下內容： ::" + +#: ../../c-api/float.rst:148 +msgid "return PyFloat_FromDouble(copysign(INFINITY, sign));" +msgstr "return PyFloat_FromDouble(copysign(INFINITY, sign));" + +#: ../../c-api/float.rst:153 +msgid "" +"Return ``1`` if the given floating-point number *X* is finite, that is, it " +"is normal, subnormal or zero, but not infinite or NaN. Return ``0`` " +"otherwise." +msgstr "" +"如果給定的浮點數 *X* 是有限的（即為正規數 (normal)、次正規數 (subnormal) 或零，但不是無窮大或 NaN），" +"則回傳 ``1``。否則回傳 ``0``。" + +#: ../../c-api/float.rst:157 +msgid "" +"The macro is :term:`soft deprecated`. Use :c:macro:`!isfinite` instead." +msgstr "此巨集已被\\ :term:`軟性棄用 `。請改用 :c:macro:`!isfinite`。" + +#: ../../c-api/float.rst:163 +msgid "" +"Return ``1`` if the given floating-point number *X* is positive or negative " +"infinity. Return ``0`` otherwise." +msgstr "" +"如果給定的浮點數 *X* 是正無窮大或負無窮大，則回傳 ``1``。否則回傳 ``0``。" + +#: ../../c-api/float.rst:166 +msgid "The macro is :term:`soft deprecated`. Use :c:macro:`!isinf` instead." +msgstr "此巨集已被\\ :term:`軟性棄用 `。請改用 :c:macro:`!isinf`。" + +#: ../../c-api/float.rst:172 +msgid "" +"Return ``1`` if the given floating-point number *X* is a not-a-number (NaN) " +"value. Return ``0`` otherwise." +msgstr "" +"如果給定的浮點數 *X* 是非數值 (NaN)，則回傳 ``1``。否則回傳 ``0``。" + +#: ../../c-api/float.rst:175 +msgid "The macro is :term:`soft deprecated`. Use :c:macro:`!isnan` instead." +msgstr "此巨集已被\\ :term:`軟性棄用 `。請改用 :c:macro:`!isnan`。" + +#: ../../c-api/float.rst:180 +msgid "Pack and Unpack functions" +msgstr "打包和解包函式" + +#: ../../c-api/float.rst:182 +msgid "" +"The pack and unpack functions provide an efficient platform-independent way " +"to store floating-point values as byte strings. The Pack routines produce a " +"bytes string from a C :c:expr:`double`, and the Unpack routines produce a C :" +"c:expr:`double` from such a bytes string. The suffix (2, 4 or 8) specifies " +"the number of bytes in the bytes string." +msgstr "" +"打包和解包函式提供了一種有效的跨平台方式，來將浮點數值儲存為位元組字串。打包" +"例程從 C :c:expr:`double` 產生位元組字串，而解包例程則從這樣的位元組字串產生 " +"C :c:expr:`double`。後綴（2、4 或 8）標示了位元組字串中的位元組數。" + +#: ../../c-api/float.rst:188 +msgid "" +"On platforms that appear to use IEEE 754 formats these functions work by " +"copying bits. On other platforms, the 2-byte format is identical to the IEEE " +"754 binary16 half-precision format, the 4-byte format (32-bit) is identical " +"to the IEEE 754 binary32 single precision format, and the 8-byte format to " +"the IEEE 754 binary64 double precision format, although the packing of INFs " +"and NaNs (if such things exist on the platform) isn't handled correctly, and " +"attempting to unpack a bytes string containing an IEEE INF or NaN will raise " +"an exception." +msgstr "" +"在看似使用 IEEE 754 格式的平台上，這些函式是透過複製位元來運作的。在其他平台" +"上，2 位元組格式與 IEEE 754 binary16 半精度格式相同，4 位元組格式（32 位元）" +"與 IEEE 754 binary32 單精度格式相同，8 位元組格式與 IEEE 754 binary64 雙精度" +"格式相同。儘管如此，INF 和 NaN（如果這些東西在平台上存在）的打包並未正確處" +"理，並且嘗試解包包含 IEEE INF 或 NaN 的位元組字串將引發例外。" + +#: ../../c-api/float.rst:197 +msgid "" +"Note that NaNs type may not be preserved on IEEE platforms (signaling NaN " +"become quiet NaN), for example on x86 systems in 32-bit mode." +msgstr "" +"請注意，在 IEEE 平台上可能無法保留 NaN 型別（「訊號型 NaN (signaling NaN)」會" +"變成「安靜型 NaN (quiet NaN)」），例如在 32 位元模式的 x86 系統上。" + +#: ../../c-api/float.rst:200 +msgid "" +"On non-IEEE platforms with more precision, or larger dynamic range, than " +"IEEE 754 supports, not all values can be packed; on non-IEEE platforms with " +"less precision, or smaller dynamic range, not all values can be unpacked. " +"What happens in such cases is partly accidental (alas)." +msgstr "" +"在非 IEEE 平台上，如果精度更高或動態範圍比 IEEE 754 支援的更大，則無法打包所" +"有值；在非 IEEE 平台上，如果精度較低或動態範圍較小，則無法解包所有值。在這種" +"案例下發生的情況在某種程度上是偶然的（唉）。" + +#: ../../c-api/float.rst:208 +msgid "Pack functions" +msgstr "打包函式" + +#: ../../c-api/float.rst:210 +msgid "" +"The pack routines write 2, 4 or 8 bytes, starting at *p*. *le* is an :c:expr:" +"`int` argument, non-zero if you want the bytes string in little-endian " +"format (exponent last, at ``p+1``, ``p+3``, or ``p+6`` ``p+7``), zero if you " +"want big-endian format (exponent first, at *p*). The :c:macro:" +"`PY_BIG_ENDIAN` constant can be used to use the native endian: it is equal " +"to ``1`` on big endian processor, or ``0`` on little endian processor." +msgstr "" +"打包例程會從 *p* 開始寫入 2、4 或 8 位元組。*le* 是一個 :c:expr:`int` 引數，" +"如果你想要位元組字串為小端序格式（指數在最後，位於 ``p+1``、``p+3``、``p+6`` " +"或 ``p+7``），則用非零值；如果你想要大端序格式（指數在最前，位於 *p*），則用" +"零。可以使用 :c:macro:`PY_BIG_ENDIAN` 常數來使用原生端序：在大端序處理器上它" +"等於 ``1``，在小端序處理器上它等於 ``0``。" + +#: ../../c-api/float.rst:217 +msgid "" +"Return value: ``0`` if all is OK, ``-1`` if error (and an exception is set, " +"most likely :exc:`OverflowError`)." +msgstr "" +"回傳值：如果一切正常則為 ``0``，如果發生錯誤則為 ``-1``\\ （並且會設定一個例" +"外，最有可能是 :exc:`OverflowError`）。" + +#: ../../c-api/float.rst:220 +msgid "There are two problems on non-IEEE platforms:" +msgstr "在非 IEEE 平台上有兩個問題：" + +#: ../../c-api/float.rst:222 +msgid "What this does is undefined if *x* is a NaN or infinity." +msgstr "如果 *x* 是 NaN 或無窮大，則這樣做是未定義的。" + +#: ../../c-api/float.rst:223 +msgid "``-0.0`` and ``+0.0`` produce the same bytes string." +msgstr "``-0.0`` 和 ``+0.0`` 會產生同樣的位元組字串。" + +#: ../../c-api/float.rst:227 +msgid "Pack a C double as the IEEE 754 binary16 half-precision format." +msgstr "將 C double 打包為 IEEE 754 binary16 半精度格式。" + +#: ../../c-api/float.rst:231 +msgid "Pack a C double as the IEEE 754 binary32 single precision format." +msgstr "將 C double 打包為 IEEE 754 binary32 單精度格式。" + +#: ../../c-api/float.rst:235 +msgid "Pack a C double as the IEEE 754 binary64 double precision format." +msgstr "將 C double 打包為 IEEE 754 binary64 雙精度格式。" + +#: ../../c-api/float.rst:239 +msgid "Unpack functions" +msgstr "解包函式" + +#: ../../c-api/float.rst:241 +msgid "" +"The unpack routines read 2, 4 or 8 bytes, starting at *p*. *le* is an :c:" +"expr:`int` argument, non-zero if the bytes string is in little-endian format " +"(exponent last, at ``p+1``, ``p+3`` or ``p+6`` and ``p+7``), zero if big-" +"endian (exponent first, at *p*). The :c:macro:`PY_BIG_ENDIAN` constant can " +"be used to use the native endian: it is equal to ``1`` on big endian " +"processor, or ``0`` on little endian processor." +msgstr "" +"解包例程會從 *p* 開始讀取 2、4 或 8 位元組。*le* 是一個 :c:expr:`int` 引數，" +"如果位元組字串為小端序格式（指數在最後，位於 ``p+1``、``p+3``、``p+6`` 或 " +"``p+7``），則用非零值；如果為大端序格式（指數在最前，位於 *p*），則用零。可以" +"使用 :c:macro:`PY_BIG_ENDIAN` 常數來使用原生端序：在大端序處理器上它等於 " +"``1``，在小端序處理器上它等於 ``0``。" + +#: ../../c-api/float.rst:248 +msgid "" +"Return value: The unpacked double. On error, this is ``-1.0`` and :c:func:" +"`PyErr_Occurred` is true (and an exception is set, most likely :exc:" +"`OverflowError`)." +msgstr "" +"回傳值：解包後的 double。發生錯誤時，這是 ``-1.0`` 且 :c:func:" +"`PyErr_Occurred` 為 true（並且會設置一個例外，最有可能是 :exc:" +"`OverflowError`）。" + +#: ../../c-api/float.rst:252 +msgid "" +"Note that on a non-IEEE platform this will refuse to unpack a bytes string " +"that represents a NaN or infinity." +msgstr "" +"請注意，在非 IEEE 平台上，這將拒絕解包會表示為 NaN 或無窮大的位元組字串。" + +#: ../../c-api/float.rst:257 +msgid "Unpack the IEEE 754 binary16 half-precision format as a C double." +msgstr "將 IEEE 754 binary16 半精度格式解包為 C double。" + +#: ../../c-api/float.rst:261 +msgid "Unpack the IEEE 754 binary32 single precision format as a C double." +msgstr "將 IEEE 754 binary32 單精度格式解包為 C double。" + +#: ../../c-api/float.rst:265 +msgid "Unpack the IEEE 754 binary64 double precision format as a C double." +msgstr "將 IEEE 754 binary64 雙精度格式解包為 C double。" + +#: ../../c-api/float.rst:8 +msgid "object" +msgstr "object（物件）" + +#: ../../c-api/float.rst:8 +msgid "floating-point" +msgstr "floating-point（浮點）" diff --git a/c-api/frame.po b/c-api/frame.po index c4bda1df95..1f280a9bd5 100644 --- a/c-api/frame.po +++ b/c-api/frame.po @@ -1,268 +1,268 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-11 00:15+0000\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \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" - -#: ../../c-api/frame.rst:4 -msgid "Frame Objects" -msgstr "Frame 物件" - -#: ../../c-api/frame.rst:8 -msgid "The C structure of the objects used to describe frame objects." -msgstr "用來描述 frame 物件的 C 結構。" - -#: ../../c-api/frame.rst:10 -msgid "There are no public members in this structure." -msgstr "在這個結構中沒有公開的成員。" - -#: ../../c-api/frame.rst:12 -msgid "" -"The members of this structure were removed from the public C API. Refer to " -"the :ref:`What's New entry ` for details." -msgstr "" - -#: ../../c-api/frame.rst:17 -msgid "" -"The :c:func:`PyEval_GetFrame` and :c:func:`PyThreadState_GetFrame` functions " -"can be used to get a frame object." -msgstr "" - -#: ../../c-api/frame.rst:20 -msgid "See also :ref:`Reflection `." -msgstr "另請參閱 :ref:`Reflection `。" - -#: ../../c-api/frame.rst:24 -msgid "" -"The type of frame objects. It is the same object as :py:class:`types." -"FrameType` in the Python layer." -msgstr "" - -#: ../../c-api/frame.rst:29 -msgid "" -"Previously, this type was only available after including ````." -msgstr "" - -#: ../../c-api/frame.rst:34 -msgid "" -"Create a new frame object. This function returns a :term:`strong reference` " -"to the new frame object on success, and returns ``NULL`` with an exception " -"set on failure." -msgstr "" - -#: ../../c-api/frame.rst:40 -msgid "Return non-zero if *obj* is a frame object." -msgstr "" - -#: ../../c-api/frame.rst:44 -msgid "" -"Previously, this function was only available after including ````." -msgstr "" - -#: ../../c-api/frame.rst:49 -msgid "Get the *frame* next outer frame." -msgstr "" - -#: ../../c-api/frame.rst:51 -msgid "" -"Return a :term:`strong reference`, or ``NULL`` if *frame* has no outer frame." -msgstr "" - -#: ../../c-api/frame.rst:59 -msgid "Get the *frame*'s :attr:`~frame.f_builtins` attribute." -msgstr "取得 *frame* 的 :attr:`~frame.f_builtins` 屬性。" - -#: ../../c-api/frame.rst:61 ../../c-api/frame.rst:92 -msgid "Return a :term:`strong reference`. The result cannot be ``NULL``." -msgstr "回傳 :term:`strong reference`。結果不能為 ``NULL``。" - -#: ../../c-api/frame.rst:68 -msgid "Get the *frame* code." -msgstr "" - -#: ../../c-api/frame.rst:70 ../../c-api/frame.rst:136 -msgid "Return a :term:`strong reference`." -msgstr "回傳 :term:`strong reference`。" - -#: ../../c-api/frame.rst:72 -msgid "The result (frame code) cannot be ``NULL``." -msgstr "" - -#: ../../c-api/frame.rst:79 -msgid "" -"Get the generator, coroutine, or async generator that owns this frame, or " -"``NULL`` if this frame is not owned by a generator. Does not raise an " -"exception, even if the return value is ``NULL``." -msgstr "" - -#: ../../c-api/frame.rst:83 -msgid "Return a :term:`strong reference`, or ``NULL``." -msgstr "回傳 :term:`strong reference` 或 ``NULL``。" - -#: ../../c-api/frame.rst:90 -msgid "Get the *frame*'s :attr:`~frame.f_globals` attribute." -msgstr "取得 *frame* 的 :attr:`~frame.f_globals` 屬性。" - -#: ../../c-api/frame.rst:99 -msgid "Get the *frame*'s :attr:`~frame.f_lasti` attribute." -msgstr "取得 *frame* 的 :attr:`~frame.f_lasti` 屬性。" - -#: ../../c-api/frame.rst:101 -msgid "Returns -1 if ``frame.f_lasti`` is ``None``." -msgstr "如果 ``frame.f_lasti`` 是 ``None`` 則回傳 -1。" - -#: ../../c-api/frame.rst:108 -msgid "Get the variable *name* of *frame*." -msgstr "取得 *frame* 的變數 *name*。" - -#: ../../c-api/frame.rst:110 -msgid "Return a :term:`strong reference` to the variable value on success." -msgstr "在成功時回傳變數值的 :term:`strong reference`。" - -#: ../../c-api/frame.rst:111 -msgid "" -"Raise :exc:`NameError` and return ``NULL`` if the variable does not exist." -msgstr "如果變數不存在，則引發 :exc:`NameError` 並回傳 ``NULL``。" - -#: ../../c-api/frame.rst:112 -msgid "Raise an exception and return ``NULL`` on error." -msgstr "在錯誤時引發例外並回傳 ``NULL``。" - -#: ../../c-api/frame.rst:114 -msgid "*name* type must be a :class:`str`." -msgstr "*name* 的型別必須是 :class:`str`。" - -#: ../../c-api/frame.rst:121 -msgid "" -"Similar to :c:func:`PyFrame_GetVar`, but the variable name is a C string " -"encoded in UTF-8." -msgstr "" - -#: ../../c-api/frame.rst:129 -msgid "" -"Get the *frame*'s :attr:`~frame.f_locals` attribute. If the frame refers to " -"an :term:`optimized scope`, this returns a write-through proxy object that " -"allows modifying the locals. In all other cases (classes, modules, :func:" -"`exec`, :func:`eval`) it returns the mapping representing the frame locals " -"directly (as described for :func:`locals`)." -msgstr "" - -#: ../../c-api/frame.rst:140 -msgid "" -"As part of :pep:`667`, return an instance of :c:var:" -"`PyFrameLocalsProxy_Type`." -msgstr "" - -#: ../../c-api/frame.rst:146 -msgid "Return the line number that *frame* is currently executing." -msgstr "" - -#: ../../c-api/frame.rst:150 -msgid "Frame Locals Proxies" -msgstr "" - -#: ../../c-api/frame.rst:154 -msgid "" -"The :attr:`~frame.f_locals` attribute on a :ref:`frame object ` is an instance of a \"frame-locals proxy\". The proxy object " -"exposes a write-through view of the underlying locals dictionary for the " -"frame. This ensures that the variables exposed by ``f_locals`` are always up " -"to date with the live local variables in the frame itself." -msgstr "" - -#: ../../c-api/frame.rst:160 -msgid "See :pep:`667` for more information." -msgstr "更多資訊請參閱 :pep:`667`。" - -#: ../../c-api/frame.rst:164 -msgid "The type of frame :func:`locals` proxy objects." -msgstr "" - -#: ../../c-api/frame.rst:168 -msgid "Return non-zero if *obj* is a frame :func:`locals` proxy." -msgstr "" - -#: ../../c-api/frame.rst:172 -msgid "Legacy Local Variable APIs" -msgstr "" - -#: ../../c-api/frame.rst:174 -msgid "" -"These APIs are :term:`soft deprecated`. As of Python 3.13, they do nothing. " -"They exist solely for backwards compatibility." -msgstr "" - -#: ../../c-api/frame.rst:180 ../../c-api/frame.rst:194 -#: ../../c-api/frame.rst:207 -msgid "This function is :term:`soft deprecated` and does nothing." -msgstr "" - -#: ../../c-api/frame.rst:182 -msgid "" -"Prior to Python 3.13, this function would copy the :attr:`~frame.f_locals` " -"attribute of *f* to the internal \"fast\" array of local variables, allowing " -"changes in frame objects to be visible to the interpreter. If *clear* was " -"true, this function would process variables that were unset in the locals " -"dictionary." -msgstr "" - -#: ../../c-api/frame.rst:188 ../../c-api/frame.rst:201 -#: ../../c-api/frame.rst:213 -msgid "This function now does nothing." -msgstr "" - -#: ../../c-api/frame.rst:196 -msgid "" -"Prior to Python 3.13, this function would copy the internal \"fast\" array " -"of local variables (which is used by the interpreter) to the :attr:`~frame." -"f_locals` attribute of *f*, allowing changes in local variables to be " -"visible to frame objects." -msgstr "" - -#: ../../c-api/frame.rst:209 -msgid "" -"Prior to Python 3.13, this function was similar to :c:func:" -"`PyFrame_FastToLocals`, but would return ``0`` on success, and ``-1`` with " -"an exception set on failure." -msgstr "" - -#: ../../c-api/frame.rst:218 -msgid ":pep:`667`" -msgstr "" - -#: ../../c-api/frame.rst:222 -msgid "Internal Frames" -msgstr "" - -#: ../../c-api/frame.rst:224 -msgid "Unless using :pep:`523`, you will not need this." -msgstr "" - -#: ../../c-api/frame.rst:228 -msgid "The interpreter's internal frame representation." -msgstr "" - -#: ../../c-api/frame.rst:234 -msgid "Return a :term:`strong reference` to the code object for the frame." -msgstr "" - -#: ../../c-api/frame.rst:241 -msgid "Return the byte offset into the last executed instruction." -msgstr "" - -#: ../../c-api/frame.rst:248 -msgid "" -"Return the currently executing line number, or -1 if there is no line number." -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-11 00:15+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \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" + +#: ../../c-api/frame.rst:4 +msgid "Frame Objects" +msgstr "Frame 物件" + +#: ../../c-api/frame.rst:8 +msgid "The C structure of the objects used to describe frame objects." +msgstr "用來描述 frame 物件的 C 結構。" + +#: ../../c-api/frame.rst:10 +msgid "There are no public members in this structure." +msgstr "在這個結構中沒有公開的成員。" + +#: ../../c-api/frame.rst:12 +msgid "" +"The members of this structure were removed from the public C API. Refer to " +"the :ref:`What's New entry ` for details." +msgstr "" + +#: ../../c-api/frame.rst:17 +msgid "" +"The :c:func:`PyEval_GetFrame` and :c:func:`PyThreadState_GetFrame` functions " +"can be used to get a frame object." +msgstr "" + +#: ../../c-api/frame.rst:20 +msgid "See also :ref:`Reflection `." +msgstr "另請參閱 :ref:`Reflection `。" + +#: ../../c-api/frame.rst:24 +msgid "" +"The type of frame objects. It is the same object as :py:class:`types." +"FrameType` in the Python layer." +msgstr "" + +#: ../../c-api/frame.rst:29 +msgid "" +"Previously, this type was only available after including ````." +msgstr "" + +#: ../../c-api/frame.rst:34 +msgid "" +"Create a new frame object. This function returns a :term:`strong reference` " +"to the new frame object on success, and returns ``NULL`` with an exception " +"set on failure." +msgstr "" + +#: ../../c-api/frame.rst:40 +msgid "Return non-zero if *obj* is a frame object." +msgstr "" + +#: ../../c-api/frame.rst:44 +msgid "" +"Previously, this function was only available after including ````." +msgstr "" + +#: ../../c-api/frame.rst:49 +msgid "Get the *frame* next outer frame." +msgstr "" + +#: ../../c-api/frame.rst:51 +msgid "" +"Return a :term:`strong reference`, or ``NULL`` if *frame* has no outer frame." +msgstr "" + +#: ../../c-api/frame.rst:59 +msgid "Get the *frame*'s :attr:`~frame.f_builtins` attribute." +msgstr "取得 *frame* 的 :attr:`~frame.f_builtins` 屬性。" + +#: ../../c-api/frame.rst:61 ../../c-api/frame.rst:92 +msgid "Return a :term:`strong reference`. The result cannot be ``NULL``." +msgstr "回傳 :term:`strong reference`。結果不能為 ``NULL``。" + +#: ../../c-api/frame.rst:68 +msgid "Get the *frame* code." +msgstr "" + +#: ../../c-api/frame.rst:70 ../../c-api/frame.rst:136 +msgid "Return a :term:`strong reference`." +msgstr "回傳 :term:`strong reference`。" + +#: ../../c-api/frame.rst:72 +msgid "The result (frame code) cannot be ``NULL``." +msgstr "" + +#: ../../c-api/frame.rst:79 +msgid "" +"Get the generator, coroutine, or async generator that owns this frame, or " +"``NULL`` if this frame is not owned by a generator. Does not raise an " +"exception, even if the return value is ``NULL``." +msgstr "" + +#: ../../c-api/frame.rst:83 +msgid "Return a :term:`strong reference`, or ``NULL``." +msgstr "回傳 :term:`strong reference` 或 ``NULL``。" + +#: ../../c-api/frame.rst:90 +msgid "Get the *frame*'s :attr:`~frame.f_globals` attribute." +msgstr "取得 *frame* 的 :attr:`~frame.f_globals` 屬性。" + +#: ../../c-api/frame.rst:99 +msgid "Get the *frame*'s :attr:`~frame.f_lasti` attribute." +msgstr "取得 *frame* 的 :attr:`~frame.f_lasti` 屬性。" + +#: ../../c-api/frame.rst:101 +msgid "Returns -1 if ``frame.f_lasti`` is ``None``." +msgstr "如果 ``frame.f_lasti`` 是 ``None`` 則回傳 -1。" + +#: ../../c-api/frame.rst:108 +msgid "Get the variable *name* of *frame*." +msgstr "取得 *frame* 的變數 *name*。" + +#: ../../c-api/frame.rst:110 +msgid "Return a :term:`strong reference` to the variable value on success." +msgstr "在成功時回傳變數值的 :term:`strong reference`。" + +#: ../../c-api/frame.rst:111 +msgid "" +"Raise :exc:`NameError` and return ``NULL`` if the variable does not exist." +msgstr "如果變數不存在，則引發 :exc:`NameError` 並回傳 ``NULL``。" + +#: ../../c-api/frame.rst:112 +msgid "Raise an exception and return ``NULL`` on error." +msgstr "在錯誤時引發例外並回傳 ``NULL``。" + +#: ../../c-api/frame.rst:114 +msgid "*name* type must be a :class:`str`." +msgstr "*name* 的型別必須是 :class:`str`。" + +#: ../../c-api/frame.rst:121 +msgid "" +"Similar to :c:func:`PyFrame_GetVar`, but the variable name is a C string " +"encoded in UTF-8." +msgstr "" + +#: ../../c-api/frame.rst:129 +msgid "" +"Get the *frame*'s :attr:`~frame.f_locals` attribute. If the frame refers to " +"an :term:`optimized scope`, this returns a write-through proxy object that " +"allows modifying the locals. In all other cases (classes, modules, :func:" +"`exec`, :func:`eval`) it returns the mapping representing the frame locals " +"directly (as described for :func:`locals`)." +msgstr "" + +#: ../../c-api/frame.rst:140 +msgid "" +"As part of :pep:`667`, return an instance of :c:var:" +"`PyFrameLocalsProxy_Type`." +msgstr "" + +#: ../../c-api/frame.rst:146 +msgid "Return the line number that *frame* is currently executing." +msgstr "" + +#: ../../c-api/frame.rst:150 +msgid "Frame Locals Proxies" +msgstr "" + +#: ../../c-api/frame.rst:154 +msgid "" +"The :attr:`~frame.f_locals` attribute on a :ref:`frame object ` is an instance of a \"frame-locals proxy\". The proxy object " +"exposes a write-through view of the underlying locals dictionary for the " +"frame. This ensures that the variables exposed by ``f_locals`` are always up " +"to date with the live local variables in the frame itself." +msgstr "" + +#: ../../c-api/frame.rst:160 +msgid "See :pep:`667` for more information." +msgstr "更多資訊請參閱 :pep:`667`。" + +#: ../../c-api/frame.rst:164 +msgid "The type of frame :func:`locals` proxy objects." +msgstr "" + +#: ../../c-api/frame.rst:168 +msgid "Return non-zero if *obj* is a frame :func:`locals` proxy." +msgstr "" + +#: ../../c-api/frame.rst:172 +msgid "Legacy Local Variable APIs" +msgstr "" + +#: ../../c-api/frame.rst:174 +msgid "" +"These APIs are :term:`soft deprecated`. As of Python 3.13, they do nothing. " +"They exist solely for backwards compatibility." +msgstr "" + +#: ../../c-api/frame.rst:180 ../../c-api/frame.rst:194 +#: ../../c-api/frame.rst:207 +msgid "This function is :term:`soft deprecated` and does nothing." +msgstr "" + +#: ../../c-api/frame.rst:182 +msgid "" +"Prior to Python 3.13, this function would copy the :attr:`~frame.f_locals` " +"attribute of *f* to the internal \"fast\" array of local variables, allowing " +"changes in frame objects to be visible to the interpreter. If *clear* was " +"true, this function would process variables that were unset in the locals " +"dictionary." +msgstr "" + +#: ../../c-api/frame.rst:188 ../../c-api/frame.rst:201 +#: ../../c-api/frame.rst:213 +msgid "This function now does nothing." +msgstr "" + +#: ../../c-api/frame.rst:196 +msgid "" +"Prior to Python 3.13, this function would copy the internal \"fast\" array " +"of local variables (which is used by the interpreter) to the :attr:`~frame." +"f_locals` attribute of *f*, allowing changes in local variables to be " +"visible to frame objects." +msgstr "" + +#: ../../c-api/frame.rst:209 +msgid "" +"Prior to Python 3.13, this function was similar to :c:func:" +"`PyFrame_FastToLocals`, but would return ``0`` on success, and ``-1`` with " +"an exception set on failure." +msgstr "" + +#: ../../c-api/frame.rst:218 +msgid ":pep:`667`" +msgstr "" + +#: ../../c-api/frame.rst:222 +msgid "Internal Frames" +msgstr "" + +#: ../../c-api/frame.rst:224 +msgid "Unless using :pep:`523`, you will not need this." +msgstr "" + +#: ../../c-api/frame.rst:228 +msgid "The interpreter's internal frame representation." +msgstr "" + +#: ../../c-api/frame.rst:234 +msgid "Return a :term:`strong reference` to the code object for the frame." +msgstr "" + +#: ../../c-api/frame.rst:241 +msgid "Return the byte offset into the last executed instruction." +msgstr "" + +#: ../../c-api/frame.rst:248 +msgid "" +"Return the currently executing line number, or -1 if there is no line number." +msgstr "" diff --git a/c-api/function.po b/c-api/function.po index 61b434d12a..e9dd765303 100644 --- a/c-api/function.po +++ b/c-api/function.po @@ -1,305 +1,305 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Ching-Lung Chuang, 2015 -# Liang-Bo Wang , 2015 -# Matt Wang , 2022 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-10 00:16+0000\n" -"PO-Revision-Date: 2022-11-12 15:45+0800\n" -"Last-Translator: Matt Wang \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" -"X-Generator: Poedit 3.2\n" - -#: ../../c-api/function.rst:6 -msgid "Function Objects" -msgstr "函式物件 (Function Objects)" - -#: ../../c-api/function.rst:10 -msgid "There are a few functions specific to Python functions." -msgstr "這有一些特用於 Python 函式的函式。" - -#: ../../c-api/function.rst:15 -msgid "The C structure used for functions." -msgstr "用於函式的 C 結構。" - -#: ../../c-api/function.rst:22 -msgid "" -"This is an instance of :c:type:`PyTypeObject` and represents the Python " -"function type. It is exposed to Python programmers as ``types." -"FunctionType``." -msgstr "" -"這是個 :c:type:`PyTypeObject` 的實例，且代表了 Python 函式型別，Python 程式設" -"計者可透過 ``types.FunctionType`` 使用它。" - -#: ../../c-api/function.rst:28 -msgid "" -"Return true if *o* is a function object (has type :c:data:" -"`PyFunction_Type`). The parameter must not be ``NULL``. This function " -"always succeeds." -msgstr "" -"如果 *o* 是個函式物件（擁有 :c:data:`PyFunction_Type` 的型別）則回傳 true。參" -"數必須不為 ``NULL``。此函式必能成功執行。" - -#: ../../c-api/function.rst:34 -msgid "" -"Return a new function object associated with the code object *code*. " -"*globals* must be a dictionary with the global variables accessible to the " -"function." -msgstr "" -"回傳一個與程式碼物件 *code* 相關聯的函式物件。*globals* 必須是一個帶有函式能" -"夠存取的全域變數的字典。" - -#: ../../c-api/function.rst:37 -msgid "" -"The function's docstring and name are retrieved from the code object. :attr:" -"`~function.__module__` is retrieved from *globals*. The argument defaults, " -"annotations and closure are set to ``NULL``. :attr:`~function.__qualname__` " -"is set to the same value as the code object's :attr:`~codeobject." -"co_qualname` field." -msgstr "" -"函式的文件字串 (docstring) 和名稱是從程式碼物件所取得，:attr:`~function." -"__module__` 是自 *globals* 所取得。引數預設值、標註 (annotation) 和閉包 " -"(closure) 被設為 ``NULL``，:attr:`~function.__qualname__` 被設為和程式碼物" -"件 :attr:`~codeobject.co_qualname` 欄位相同的值。" - -#: ../../c-api/function.rst:46 -msgid "" -"As :c:func:`PyFunction_New`, but also allows setting the function object's :" -"attr:`~function.__qualname__` attribute. *qualname* should be a unicode " -"object or ``NULL``; if ``NULL``, the :attr:`!__qualname__` attribute is set " -"to the same value as the code object's :attr:`~codeobject.co_qualname` field." -msgstr "" -"和 :c:func:`PyFunction_New` 相似，但也允許函式物件 :attr:`~function." -"__qualname__` 屬性的設定，*qualname* 應為一個 unicode 物件或是 ``NULL``；如" -"為 ``NULL``，:attr:`!__qualname__` 屬性會被設為與程式碼物件 :attr:" -"`~codeobject.co_qualname` 欄位相同的值。" - -#: ../../c-api/function.rst:57 -msgid "Return the code object associated with the function object *op*." -msgstr "回傳與程式碼物件相關的函式物件 *op*。" - -#: ../../c-api/function.rst:62 -msgid "Return the globals dictionary associated with the function object *op*." -msgstr "回傳與全域函式字典相關的函式物件 *op*。" - -#: ../../c-api/function.rst:67 -msgid "" -"Return a :term:`borrowed reference` to the :attr:`~function.__module__` " -"attribute of the :ref:`function object ` *op*. It can be " -"*NULL*." -msgstr "" -"回傳一個\\ :ref:`函式物件 ` *op* 之 :attr:`~function." -"__module__` 屬性的 :term:`borrowed reference`，它可以是 *NULL*。" - -#: ../../c-api/function.rst:71 -msgid "" -"This is normally a :class:`string ` containing the module name, but can " -"be set to any other object by Python code." -msgstr "" -"這通常是個包含模組名稱的\\ :class:`字串 `，但可以被 Python 程式設為任何" -"其他物件。" - -#: ../../c-api/function.rst:77 -msgid "" -"Return the argument default values of the function object *op*. This can be " -"a tuple of arguments or ``NULL``." -msgstr "" -"回傳函式物件 *op* 的引數預設值，這可以是一個含有多個引數的 tuple（元組）或 " -"``NULL``。" - -#: ../../c-api/function.rst:83 -msgid "" -"Set the argument default values for the function object *op*. *defaults* " -"must be ``Py_None`` or a tuple." -msgstr "" -"設定函式物件 *op* 的引數預設值。*defaults* 必須是 ``Py_None`` 或一個 tuple。" - -#: ../../c-api/function.rst:86 ../../c-api/function.rst:125 -#: ../../c-api/function.rst:139 -msgid "Raises :exc:`SystemError` and returns ``-1`` on failure." -msgstr "引發 :exc:`SystemError` 且在失敗時回傳 ``-1``。" - -#: ../../c-api/function.rst:91 -msgid "Set the vectorcall field of a given function object *func*." -msgstr "為一個給定的函式物件 *func* 設定 vectorcall 欄位。" - -#: ../../c-api/function.rst:93 -msgid "" -"Warning: extensions using this API must preserve the behavior of the " -"unaltered (default) vectorcall function!" -msgstr "" -"警告：使用此 API 的擴充套件必須保留未更改（預設）vectorcall 函式的行為！" - -#: ../../c-api/function.rst:101 -msgid "" -"Return the keyword-only argument default values of the function object *op*. " -"This can be a dictionary of arguments or ``NULL``." -msgstr "" -"回傳函式物件 *op* 的僅限關鍵字引數預設值，這可以是一個含有多個引數的字典或 " -"``NULL``。" - -#: ../../c-api/function.rst:107 -msgid "" -"Set the keyword-only argument default values of the function object *op*. " -"*defaults* must be a dictionary of keyword-only arguments or ``Py_None``." -msgstr "" -"設定函式物件 *op* 的僅限關鍵字引數預設值。*defaults* 必須是僅限關鍵字引數的字典或 ``Py_None``。" - -#: ../../c-api/function.rst:110 -msgid "" -"This function returns ``0`` on success, and returns ``-1`` with an exception " -"set on failure." -msgstr "此函式在成功時回傳 ``0``，在失敗時回傳 ``-1`` 且設定一個例外。" - -#: ../../c-api/function.rst:116 -msgid "" -"Return the closure associated with the function object *op*. This can be " -"``NULL`` or a tuple of cell objects." -msgstr "" -"回傳與函式物件 *op* 相關聯的閉包，這可以是個 ``NULL`` 或是一個包含 cell 物件" -"的 tuple。" - -#: ../../c-api/function.rst:122 -msgid "" -"Set the closure associated with the function object *op*. *closure* must be " -"``Py_None`` or a tuple of cell objects." -msgstr "" -"設定與函式物件 *op* 相關聯的閉包，*closure* 必須是 ``Py_None`` 或是一個包含 " -"cell 物件的 tuple。" - -#: ../../c-api/function.rst:130 -msgid "" -"Return the annotations of the function object *op*. This can be a mutable " -"dictionary or ``NULL``." -msgstr "" -"回傳函式物件 *op* 的標註，這可以是一個可變動的 (mutable) 字典或 ``NULL``。" - -#: ../../c-api/function.rst:136 -msgid "" -"Set the annotations for the function object *op*. *annotations* must be a " -"dictionary or ``Py_None``." -msgstr "設定函式物件 *op* 的標註，*annotations* 必須是一個字典或 ``Py_None``。" - -#: ../../c-api/function.rst:150 -msgid "" -"These functions are similar to their ``PyFunction_Get*`` counterparts, but " -"do not do type checking. Passing anything other than an instance of :c:data:" -"`PyFunction_Type` is undefined behavior." -msgstr "" - -#: ../../c-api/function.rst:157 -msgid "" -"Register *callback* as a function watcher for the current interpreter. " -"Return an ID which may be passed to :c:func:`PyFunction_ClearWatcher`. In " -"case of error (e.g. no more watcher IDs available), return ``-1`` and set an " -"exception." -msgstr "" - -#: ../../c-api/function.rst:167 -msgid "" -"Clear watcher identified by *watcher_id* previously returned from :c:func:" -"`PyFunction_AddWatcher` for the current interpreter. Return ``0`` on " -"success, or ``-1`` and set an exception on error (e.g. if the given " -"*watcher_id* was never registered.)" -msgstr "" - -#: ../../c-api/function.rst:177 -msgid "Enumeration of possible function watcher events:" -msgstr "" - -#: ../../c-api/function.rst:179 -msgid "``PyFunction_EVENT_CREATE``" -msgstr "``PyFunction_EVENT_CREATE``" - -#: ../../c-api/function.rst:180 -msgid "``PyFunction_EVENT_DESTROY``" -msgstr "``PyFunction_EVENT_DESTROY``" - -#: ../../c-api/function.rst:181 -msgid "``PyFunction_EVENT_MODIFY_CODE``" -msgstr "``PyFunction_EVENT_MODIFY_CODE``" - -#: ../../c-api/function.rst:182 -msgid "``PyFunction_EVENT_MODIFY_DEFAULTS``" -msgstr "``PyFunction_EVENT_MODIFY_DEFAULTS``" - -#: ../../c-api/function.rst:183 -msgid "``PyFunction_EVENT_MODIFY_KWDEFAULTS``" -msgstr "``PyFunction_EVENT_MODIFY_KWDEFAULTS``" - -#: ../../c-api/function.rst:190 -msgid "Type of a function watcher callback function." -msgstr "" - -#: ../../c-api/function.rst:192 -msgid "" -"If *event* is ``PyFunction_EVENT_CREATE`` or ``PyFunction_EVENT_DESTROY`` " -"then *new_value* will be ``NULL``. Otherwise, *new_value* will hold a :term:" -"`borrowed reference` to the new value that is about to be stored in *func* " -"for the attribute that is being modified." -msgstr "" - -#: ../../c-api/function.rst:197 -msgid "" -"The callback may inspect but must not modify *func*; doing so could have " -"unpredictable effects, including infinite recursion." -msgstr "" - -#: ../../c-api/function.rst:200 -msgid "" -"If *event* is ``PyFunction_EVENT_CREATE``, then the callback is invoked " -"after *func* has been fully initialized. Otherwise, the callback is invoked " -"before the modification to *func* takes place, so the prior state of *func* " -"can be inspected. The runtime is permitted to optimize away the creation of " -"function objects when possible. In such cases no event will be emitted. " -"Although this creates the possibility of an observable difference of runtime " -"behavior depending on optimization decisions, it does not change the " -"semantics of the Python code being executed." -msgstr "" - -#: ../../c-api/function.rst:209 -msgid "" -"If *event* is ``PyFunction_EVENT_DESTROY``, Taking a reference in the " -"callback to the about-to-be-destroyed function will resurrect it, preventing " -"it from being freed at this time. When the resurrected object is destroyed " -"later, any watcher callbacks active at that time will be called again." -msgstr "" - -#: ../../c-api/function.rst:214 -msgid "" -"If the callback sets an exception, it must return ``-1``; this exception " -"will be printed as an unraisable exception using :c:func:" -"`PyErr_WriteUnraisable`. Otherwise it should return ``0``." -msgstr "" - -#: ../../c-api/function.rst:218 -msgid "" -"There may already be a pending exception set on entry to the callback. In " -"this case, the callback should return ``0`` with the same exception still " -"set. This means the callback may not call any other API that can set an " -"exception unless it saves and clears the exception state first, and restores " -"it before returning." -msgstr "" - -#: ../../c-api/function.rst:8 -msgid "object" -msgstr "object（物件）" - -#: ../../c-api/function.rst:8 -msgid "function" -msgstr "function（函式）" - -#: ../../c-api/function.rst:20 -msgid "MethodType (in module types)" -msgstr "MethodType（types 模組中）" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Ching-Lung Chuang, 2015 +# Liang-Bo Wang , 2015 +# Matt Wang , 2022 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-10 00:16+0000\n" +"PO-Revision-Date: 2022-11-12 15:45+0800\n" +"Last-Translator: Matt Wang \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" +"X-Generator: Poedit 3.2\n" + +#: ../../c-api/function.rst:6 +msgid "Function Objects" +msgstr "函式物件 (Function Objects)" + +#: ../../c-api/function.rst:10 +msgid "There are a few functions specific to Python functions." +msgstr "這有一些特用於 Python 函式的函式。" + +#: ../../c-api/function.rst:15 +msgid "The C structure used for functions." +msgstr "用於函式的 C 結構。" + +#: ../../c-api/function.rst:22 +msgid "" +"This is an instance of :c:type:`PyTypeObject` and represents the Python " +"function type. It is exposed to Python programmers as ``types." +"FunctionType``." +msgstr "" +"這是個 :c:type:`PyTypeObject` 的實例，且代表了 Python 函式型別，Python 程式設" +"計者可透過 ``types.FunctionType`` 使用它。" + +#: ../../c-api/function.rst:28 +msgid "" +"Return true if *o* is a function object (has type :c:data:" +"`PyFunction_Type`). The parameter must not be ``NULL``. This function " +"always succeeds." +msgstr "" +"如果 *o* 是個函式物件（擁有 :c:data:`PyFunction_Type` 的型別）則回傳 true。參" +"數必須不為 ``NULL``。此函式必能成功執行。" + +#: ../../c-api/function.rst:34 +msgid "" +"Return a new function object associated with the code object *code*. " +"*globals* must be a dictionary with the global variables accessible to the " +"function." +msgstr "" +"回傳一個與程式碼物件 *code* 相關聯的函式物件。*globals* 必須是一個帶有函式能" +"夠存取的全域變數的字典。" + +#: ../../c-api/function.rst:37 +msgid "" +"The function's docstring and name are retrieved from the code object. :attr:" +"`~function.__module__` is retrieved from *globals*. The argument defaults, " +"annotations and closure are set to ``NULL``. :attr:`~function.__qualname__` " +"is set to the same value as the code object's :attr:`~codeobject." +"co_qualname` field." +msgstr "" +"函式的文件字串 (docstring) 和名稱是從程式碼物件所取得，:attr:`~function." +"__module__` 是自 *globals* 所取得。引數預設值、標註 (annotation) 和閉包 " +"(closure) 被設為 ``NULL``，:attr:`~function.__qualname__` 被設為和程式碼物" +"件 :attr:`~codeobject.co_qualname` 欄位相同的值。" + +#: ../../c-api/function.rst:46 +msgid "" +"As :c:func:`PyFunction_New`, but also allows setting the function object's :" +"attr:`~function.__qualname__` attribute. *qualname* should be a unicode " +"object or ``NULL``; if ``NULL``, the :attr:`!__qualname__` attribute is set " +"to the same value as the code object's :attr:`~codeobject.co_qualname` field." +msgstr "" +"和 :c:func:`PyFunction_New` 相似，但也允許函式物件 :attr:`~function." +"__qualname__` 屬性的設定，*qualname* 應為一個 unicode 物件或是 ``NULL``；如" +"為 ``NULL``，:attr:`!__qualname__` 屬性會被設為與程式碼物件 :attr:" +"`~codeobject.co_qualname` 欄位相同的值。" + +#: ../../c-api/function.rst:57 +msgid "Return the code object associated with the function object *op*." +msgstr "回傳與程式碼物件相關的函式物件 *op*。" + +#: ../../c-api/function.rst:62 +msgid "Return the globals dictionary associated with the function object *op*." +msgstr "回傳與全域函式字典相關的函式物件 *op*。" + +#: ../../c-api/function.rst:67 +msgid "" +"Return a :term:`borrowed reference` to the :attr:`~function.__module__` " +"attribute of the :ref:`function object ` *op*. It can be " +"*NULL*." +msgstr "" +"回傳一個\\ :ref:`函式物件 ` *op* 之 :attr:`~function." +"__module__` 屬性的 :term:`borrowed reference`，它可以是 *NULL*。" + +#: ../../c-api/function.rst:71 +msgid "" +"This is normally a :class:`string ` containing the module name, but can " +"be set to any other object by Python code." +msgstr "" +"這通常是個包含模組名稱的\\ :class:`字串 `，但可以被 Python 程式設為任何" +"其他物件。" + +#: ../../c-api/function.rst:77 +msgid "" +"Return the argument default values of the function object *op*. This can be " +"a tuple of arguments or ``NULL``." +msgstr "" +"回傳函式物件 *op* 的引數預設值，這可以是一個含有多個引數的 tuple（元組）或 " +"``NULL``。" + +#: ../../c-api/function.rst:83 +msgid "" +"Set the argument default values for the function object *op*. *defaults* " +"must be ``Py_None`` or a tuple." +msgstr "" +"設定函式物件 *op* 的引數預設值。*defaults* 必須是 ``Py_None`` 或一個 tuple。" + +#: ../../c-api/function.rst:86 ../../c-api/function.rst:125 +#: ../../c-api/function.rst:139 +msgid "Raises :exc:`SystemError` and returns ``-1`` on failure." +msgstr "引發 :exc:`SystemError` 且在失敗時回傳 ``-1``。" + +#: ../../c-api/function.rst:91 +msgid "Set the vectorcall field of a given function object *func*." +msgstr "為一個給定的函式物件 *func* 設定 vectorcall 欄位。" + +#: ../../c-api/function.rst:93 +msgid "" +"Warning: extensions using this API must preserve the behavior of the " +"unaltered (default) vectorcall function!" +msgstr "" +"警告：使用此 API 的擴充套件必須保留未更改（預設）vectorcall 函式的行為！" + +#: ../../c-api/function.rst:101 +msgid "" +"Return the keyword-only argument default values of the function object *op*. " +"This can be a dictionary of arguments or ``NULL``." +msgstr "" +"回傳函式物件 *op* 的僅限關鍵字引數預設值，這可以是一個含有多個引數的字典或 " +"``NULL``。" + +#: ../../c-api/function.rst:107 +msgid "" +"Set the keyword-only argument default values of the function object *op*. " +"*defaults* must be a dictionary of keyword-only arguments or ``Py_None``." +msgstr "" +"設定函式物件 *op* 的僅限關鍵字引數預設值。*defaults* 必須是僅限關鍵字引數的字典或 ``Py_None``。" + +#: ../../c-api/function.rst:110 +msgid "" +"This function returns ``0`` on success, and returns ``-1`` with an exception " +"set on failure." +msgstr "此函式在成功時回傳 ``0``，在失敗時回傳 ``-1`` 且設定一個例外。" + +#: ../../c-api/function.rst:116 +msgid "" +"Return the closure associated with the function object *op*. This can be " +"``NULL`` or a tuple of cell objects." +msgstr "" +"回傳與函式物件 *op* 相關聯的閉包，這可以是個 ``NULL`` 或是一個包含 cell 物件" +"的 tuple。" + +#: ../../c-api/function.rst:122 +msgid "" +"Set the closure associated with the function object *op*. *closure* must be " +"``Py_None`` or a tuple of cell objects." +msgstr "" +"設定與函式物件 *op* 相關聯的閉包，*closure* 必須是 ``Py_None`` 或是一個包含 " +"cell 物件的 tuple。" + +#: ../../c-api/function.rst:130 +msgid "" +"Return the annotations of the function object *op*. This can be a mutable " +"dictionary or ``NULL``." +msgstr "" +"回傳函式物件 *op* 的標註，這可以是一個可變動的 (mutable) 字典或 ``NULL``。" + +#: ../../c-api/function.rst:136 +msgid "" +"Set the annotations for the function object *op*. *annotations* must be a " +"dictionary or ``Py_None``." +msgstr "設定函式物件 *op* 的標註，*annotations* 必須是一個字典或 ``Py_None``。" + +#: ../../c-api/function.rst:150 +msgid "" +"These functions are similar to their ``PyFunction_Get*`` counterparts, but " +"do not do type checking. Passing anything other than an instance of :c:data:" +"`PyFunction_Type` is undefined behavior." +msgstr "" + +#: ../../c-api/function.rst:157 +msgid "" +"Register *callback* as a function watcher for the current interpreter. " +"Return an ID which may be passed to :c:func:`PyFunction_ClearWatcher`. In " +"case of error (e.g. no more watcher IDs available), return ``-1`` and set an " +"exception." +msgstr "" + +#: ../../c-api/function.rst:167 +msgid "" +"Clear watcher identified by *watcher_id* previously returned from :c:func:" +"`PyFunction_AddWatcher` for the current interpreter. Return ``0`` on " +"success, or ``-1`` and set an exception on error (e.g. if the given " +"*watcher_id* was never registered.)" +msgstr "" + +#: ../../c-api/function.rst:177 +msgid "Enumeration of possible function watcher events:" +msgstr "" + +#: ../../c-api/function.rst:179 +msgid "``PyFunction_EVENT_CREATE``" +msgstr "``PyFunction_EVENT_CREATE``" + +#: ../../c-api/function.rst:180 +msgid "``PyFunction_EVENT_DESTROY``" +msgstr "``PyFunction_EVENT_DESTROY``" + +#: ../../c-api/function.rst:181 +msgid "``PyFunction_EVENT_MODIFY_CODE``" +msgstr "``PyFunction_EVENT_MODIFY_CODE``" + +#: ../../c-api/function.rst:182 +msgid "``PyFunction_EVENT_MODIFY_DEFAULTS``" +msgstr "``PyFunction_EVENT_MODIFY_DEFAULTS``" + +#: ../../c-api/function.rst:183 +msgid "``PyFunction_EVENT_MODIFY_KWDEFAULTS``" +msgstr "``PyFunction_EVENT_MODIFY_KWDEFAULTS``" + +#: ../../c-api/function.rst:190 +msgid "Type of a function watcher callback function." +msgstr "" + +#: ../../c-api/function.rst:192 +msgid "" +"If *event* is ``PyFunction_EVENT_CREATE`` or ``PyFunction_EVENT_DESTROY`` " +"then *new_value* will be ``NULL``. Otherwise, *new_value* will hold a :term:" +"`borrowed reference` to the new value that is about to be stored in *func* " +"for the attribute that is being modified." +msgstr "" + +#: ../../c-api/function.rst:197 +msgid "" +"The callback may inspect but must not modify *func*; doing so could have " +"unpredictable effects, including infinite recursion." +msgstr "" + +#: ../../c-api/function.rst:200 +msgid "" +"If *event* is ``PyFunction_EVENT_CREATE``, then the callback is invoked " +"after *func* has been fully initialized. Otherwise, the callback is invoked " +"before the modification to *func* takes place, so the prior state of *func* " +"can be inspected. The runtime is permitted to optimize away the creation of " +"function objects when possible. In such cases no event will be emitted. " +"Although this creates the possibility of an observable difference of runtime " +"behavior depending on optimization decisions, it does not change the " +"semantics of the Python code being executed." +msgstr "" + +#: ../../c-api/function.rst:209 +msgid "" +"If *event* is ``PyFunction_EVENT_DESTROY``, Taking a reference in the " +"callback to the about-to-be-destroyed function will resurrect it, preventing " +"it from being freed at this time. When the resurrected object is destroyed " +"later, any watcher callbacks active at that time will be called again." +msgstr "" + +#: ../../c-api/function.rst:214 +msgid "" +"If the callback sets an exception, it must return ``-1``; this exception " +"will be printed as an unraisable exception using :c:func:" +"`PyErr_WriteUnraisable`. Otherwise it should return ``0``." +msgstr "" + +#: ../../c-api/function.rst:218 +msgid "" +"There may already be a pending exception set on entry to the callback. In " +"this case, the callback should return ``0`` with the same exception still " +"set. This means the callback may not call any other API that can set an " +"exception unless it saves and clears the exception state first, and restores " +"it before returning." +msgstr "" + +#: ../../c-api/function.rst:8 +msgid "object" +msgstr "object（物件）" + +#: ../../c-api/function.rst:8 +msgid "function" +msgstr "function（函式）" + +#: ../../c-api/function.rst:20 +msgid "MethodType (in module types)" +msgstr "MethodType（types 模組中）" diff --git a/c-api/gcsupport.po b/c-api/gcsupport.po index a95dd47f00..b4196db5a3 100644 --- a/c-api/gcsupport.po +++ b/c-api/gcsupport.po @@ -1,458 +1,458 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-12-09 00:14+0000\n" -"PO-Revision-Date: 2018-05-23 14:31+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" - -#: ../../c-api/gcsupport.rst:6 -msgid "Supporting Cyclic Garbage Collection" -msgstr "循環垃圾回收的支援" - -#: ../../c-api/gcsupport.rst:8 -msgid "" -"Python's support for detecting and collecting garbage which involves " -"circular references requires support from object types which are " -"\"containers\" for other objects which may also be containers. Types which " -"do not store references to other objects, or which only store references to " -"atomic types (such as numbers or strings), do not need to provide any " -"explicit support for garbage collection." -msgstr "" - -#: ../../c-api/gcsupport.rst:15 -msgid "" -"To create a container type, the :c:member:`~PyTypeObject.tp_flags` field of " -"the type object must include the :c:macro:`Py_TPFLAGS_HAVE_GC` and provide " -"an implementation of the :c:member:`~PyTypeObject.tp_traverse` handler. If " -"instances of the type are mutable, a :c:member:`~PyTypeObject.tp_clear` " -"implementation must also be provided." -msgstr "" - -#: ../../c-api/gcsupport.rst:21 -msgid ":c:macro:`Py_TPFLAGS_HAVE_GC`" -msgstr ":c:macro:`Py_TPFLAGS_HAVE_GC`" - -#: ../../c-api/gcsupport.rst:22 -msgid "" -"Objects with a type with this flag set must conform with the rules " -"documented here. For convenience these objects will be referred to as " -"container objects." -msgstr "" - -#: ../../c-api/gcsupport.rst:26 -msgid "Constructors for container types must conform to two rules:" -msgstr "" - -#: ../../c-api/gcsupport.rst:28 -msgid "" -"The memory for the object must be allocated using :c:macro:`PyObject_GC_New` " -"or :c:macro:`PyObject_GC_NewVar`." -msgstr "" - -#: ../../c-api/gcsupport.rst:31 -msgid "" -"Once all the fields which may contain references to other containers are " -"initialized, it must call :c:func:`PyObject_GC_Track`." -msgstr "" - -#: ../../c-api/gcsupport.rst:34 -msgid "" -"Similarly, the deallocator for the object must conform to a similar pair of " -"rules:" -msgstr "" - -#: ../../c-api/gcsupport.rst:37 -msgid "" -"Before fields which refer to other containers are invalidated, :c:func:" -"`PyObject_GC_UnTrack` must be called." -msgstr "" - -#: ../../c-api/gcsupport.rst:40 -msgid "" -"The object's memory must be deallocated using :c:func:`PyObject_GC_Del`." -msgstr "" - -#: ../../c-api/gcsupport.rst:43 -msgid "" -"If a type adds the Py_TPFLAGS_HAVE_GC, then it *must* implement at least a :" -"c:member:`~PyTypeObject.tp_traverse` handler or explicitly use one from its " -"subclass or subclasses." -msgstr "" - -#: ../../c-api/gcsupport.rst:47 -msgid "" -"When calling :c:func:`PyType_Ready` or some of the APIs that indirectly call " -"it like :c:func:`PyType_FromSpecWithBases` or :c:func:`PyType_FromSpec` the " -"interpreter will automatically populate the :c:member:`~PyTypeObject." -"tp_flags`, :c:member:`~PyTypeObject.tp_traverse` and :c:member:" -"`~PyTypeObject.tp_clear` fields if the type inherits from a class that " -"implements the garbage collector protocol and the child class does *not* " -"include the :c:macro:`Py_TPFLAGS_HAVE_GC` flag." -msgstr "" - -#: ../../c-api/gcsupport.rst:57 -msgid "" -"Analogous to :c:macro:`PyObject_New` but for container objects with the :c:" -"macro:`Py_TPFLAGS_HAVE_GC` flag set." -msgstr "" - -#: ../../c-api/gcsupport.rst:60 ../../c-api/gcsupport.rst:84 -msgid "" -"Do not call this directly to allocate memory for an object; call the type's :" -"c:member:`~PyTypeObject.tp_alloc` slot instead." -msgstr "" - -#: ../../c-api/gcsupport.rst:63 ../../c-api/gcsupport.rst:87 -msgid "" -"When populating a type's :c:member:`~PyTypeObject.tp_alloc` slot, :c:func:" -"`PyType_GenericAlloc` is preferred over a custom function that simply calls " -"this macro." -msgstr "" - -#: ../../c-api/gcsupport.rst:67 ../../c-api/gcsupport.rst:91 -msgid "" -"Memory allocated by this macro must be freed with :c:func:`PyObject_GC_Del` " -"(usually called via the object's :c:member:`~PyTypeObject.tp_free` slot)." -msgstr "" - -#: ../../c-api/gcsupport.rst:73 ../../c-api/gcsupport.rst:97 -msgid ":c:func:`PyObject_GC_Del`" -msgstr ":c:func:`PyObject_GC_Del`" - -#: ../../c-api/gcsupport.rst:74 -msgid ":c:macro:`PyObject_New`" -msgstr ":c:macro:`PyObject_New`" - -#: ../../c-api/gcsupport.rst:75 ../../c-api/gcsupport.rst:99 -#: ../../c-api/gcsupport.rst:193 -msgid ":c:func:`PyType_GenericAlloc`" -msgstr ":c:func:`PyType_GenericAlloc`" - -#: ../../c-api/gcsupport.rst:76 ../../c-api/gcsupport.rst:100 -msgid ":c:member:`~PyTypeObject.tp_alloc`" -msgstr ":c:member:`~PyTypeObject.tp_alloc`" - -#: ../../c-api/gcsupport.rst:81 -msgid "" -"Analogous to :c:macro:`PyObject_NewVar` but for container objects with the :" -"c:macro:`Py_TPFLAGS_HAVE_GC` flag set." -msgstr "" - -#: ../../c-api/gcsupport.rst:98 -msgid ":c:macro:`PyObject_NewVar`" -msgstr ":c:macro:`PyObject_NewVar`" - -#: ../../c-api/gcsupport.rst:105 -msgid "" -"Analogous to :c:macro:`PyObject_GC_New` but allocates *extra_size* bytes at " -"the end of the object (at offset :c:member:`~PyTypeObject.tp_basicsize`). " -"The allocated memory is initialized to zeros, except for the :c:type:`Python " -"object header `." -msgstr "" - -#: ../../c-api/gcsupport.rst:111 -msgid "" -"The extra data will be deallocated with the object, but otherwise it is not " -"managed by Python." -msgstr "" - -#: ../../c-api/gcsupport.rst:114 -msgid "" -"Memory allocated by this function must be freed with :c:func:" -"`PyObject_GC_Del` (usually called via the object's :c:member:`~PyTypeObject." -"tp_free` slot)." -msgstr "" - -#: ../../c-api/gcsupport.rst:119 -msgid "" -"The function is marked as unstable because the final mechanism for reserving " -"extra data after an instance is not yet decided. For allocating a variable " -"number of fields, prefer using :c:type:`PyVarObject` and :c:member:" -"`~PyTypeObject.tp_itemsize` instead." -msgstr "" - -#: ../../c-api/gcsupport.rst:130 -msgid "" -"Resize an object allocated by :c:macro:`PyObject_NewVar`. Returns the " -"resized object of type ``TYPE*`` (refers to any C type) or ``NULL`` on " -"failure." -msgstr "" - -#: ../../c-api/gcsupport.rst:134 -msgid "" -"*op* must be of type :c:expr:`PyVarObject *` and must not be tracked by the " -"collector yet. *newsize* must be of type :c:type:`Py_ssize_t`." -msgstr "" - -#: ../../c-api/gcsupport.rst:141 -msgid "" -"Adds the object *op* to the set of container objects tracked by the " -"collector. The collector can run at unexpected times so objects must be " -"valid while being tracked. This should be called once all the fields " -"followed by the :c:member:`~PyTypeObject.tp_traverse` handler become valid, " -"usually near the end of the constructor." -msgstr "" - -#: ../../c-api/gcsupport.rst:150 -msgid "" -"Returns non-zero if the object implements the garbage collector protocol, " -"otherwise returns 0." -msgstr "" - -#: ../../c-api/gcsupport.rst:153 -msgid "" -"The object cannot be tracked by the garbage collector if this function " -"returns 0." -msgstr "" - -#: ../../c-api/gcsupport.rst:158 -msgid "" -"Returns 1 if the object type of *op* implements the GC protocol and *op* is " -"being currently tracked by the garbage collector and 0 otherwise." -msgstr "" - -#: ../../c-api/gcsupport.rst:161 -msgid "This is analogous to the Python function :func:`gc.is_tracked`." -msgstr "" - -#: ../../c-api/gcsupport.rst:168 -msgid "" -"Returns 1 if the object type of *op* implements the GC protocol and *op* has " -"been already finalized by the garbage collector and 0 otherwise." -msgstr "" - -#: ../../c-api/gcsupport.rst:171 -msgid "This is analogous to the Python function :func:`gc.is_finalized`." -msgstr "" - -#: ../../c-api/gcsupport.rst:178 -msgid "" -"Releases memory allocated to an object using :c:macro:`PyObject_GC_New` or :" -"c:macro:`PyObject_GC_NewVar`." -msgstr "" - -#: ../../c-api/gcsupport.rst:181 -msgid "" -"Do not call this directly to free an object's memory; call the type's :c:" -"member:`~PyTypeObject.tp_free` slot instead." -msgstr "" - -#: ../../c-api/gcsupport.rst:184 -msgid "" -"Do not use this for memory allocated by :c:macro:`PyObject_New`, :c:macro:" -"`PyObject_NewVar`, or related allocation functions; use :c:func:" -"`PyObject_Free` instead." -msgstr "" - -#: ../../c-api/gcsupport.rst:190 -msgid ":c:func:`PyObject_Free` is the non-GC equivalent of this function." -msgstr "" - -#: ../../c-api/gcsupport.rst:191 -msgid ":c:macro:`PyObject_GC_New`" -msgstr ":c:macro:`PyObject_GC_New`" - -#: ../../c-api/gcsupport.rst:192 -msgid ":c:macro:`PyObject_GC_NewVar`" -msgstr ":c:macro:`PyObject_GC_NewVar`" - -#: ../../c-api/gcsupport.rst:194 -msgid ":c:member:`~PyTypeObject.tp_free`" -msgstr ":c:member:`~PyTypeObject.tp_free`" - -#: ../../c-api/gcsupport.rst:199 -msgid "" -"Remove the object *op* from the set of container objects tracked by the " -"collector. Note that :c:func:`PyObject_GC_Track` can be called again on " -"this object to add it back to the set of tracked objects. The deallocator (:" -"c:member:`~PyTypeObject.tp_dealloc` handler) should call this for the object " -"before any of the fields used by the :c:member:`~PyTypeObject.tp_traverse` " -"handler become invalid." -msgstr "" - -#: ../../c-api/gcsupport.rst:208 -msgid "" -"The :c:func:`!_PyObject_GC_TRACK` and :c:func:`!_PyObject_GC_UNTRACK` macros " -"have been removed from the public C API." -msgstr "" - -#: ../../c-api/gcsupport.rst:211 -msgid "" -"The :c:member:`~PyTypeObject.tp_traverse` handler accepts a function " -"parameter of this type:" -msgstr "" - -#: ../../c-api/gcsupport.rst:216 -msgid "" -"Type of the visitor function passed to the :c:member:`~PyTypeObject." -"tp_traverse` handler. The function should be called with an object to " -"traverse as *object* and the third parameter to the :c:member:`~PyTypeObject." -"tp_traverse` handler as *arg*. The Python core uses several visitor " -"functions to implement cyclic garbage detection; it's not expected that " -"users will need to write their own visitor functions." -msgstr "" - -#: ../../c-api/gcsupport.rst:223 -msgid "" -"The :c:member:`~PyTypeObject.tp_traverse` handler must have the following " -"type:" -msgstr "" - -#: ../../c-api/gcsupport.rst:228 -msgid "" -"Traversal function for a container object. Implementations must call the " -"*visit* function for each object directly contained by *self*, with the " -"parameters to *visit* being the contained object and the *arg* value passed " -"to the handler. The *visit* function must not be called with a ``NULL`` " -"object argument. If *visit* returns a non-zero value that value should be " -"returned immediately." -msgstr "" - -#: ../../c-api/gcsupport.rst:235 -msgid "" -"The traversal function must not have any side effects. Implementations may " -"not modify the reference counts of any Python objects nor create or destroy " -"any Python objects." -msgstr "" - -#: ../../c-api/gcsupport.rst:239 -msgid "" -"To simplify writing :c:member:`~PyTypeObject.tp_traverse` handlers, a :c:" -"func:`Py_VISIT` macro is provided. In order to use this macro, the :c:" -"member:`~PyTypeObject.tp_traverse` implementation must name its arguments " -"exactly *visit* and *arg*:" -msgstr "" - -#: ../../c-api/gcsupport.rst:246 -msgid "" -"If the :c:expr:`PyObject *` *o* is not ``NULL``, call the *visit* callback, " -"with arguments *o* and *arg*. If *visit* returns a non-zero value, then " -"return it. Using this macro, :c:member:`~PyTypeObject.tp_traverse` handlers " -"look like::" -msgstr "" - -#: ../../c-api/gcsupport.rst:251 -msgid "" -"static int\n" -"my_traverse(Noddy *self, visitproc visit, void *arg)\n" -"{\n" -" Py_VISIT(self->foo);\n" -" Py_VISIT(self->bar);\n" -" return 0;\n" -"}" -msgstr "" -"static int\n" -"my_traverse(Noddy *self, visitproc visit, void *arg)\n" -"{\n" -" Py_VISIT(self->foo);\n" -" Py_VISIT(self->bar);\n" -" return 0;\n" -"}" - -#: ../../c-api/gcsupport.rst:259 -msgid "" -"The :c:member:`~PyTypeObject.tp_clear` handler must be of the :c:type:" -"`inquiry` type, or ``NULL`` if the object is immutable." -msgstr "" - -#: ../../c-api/gcsupport.rst:265 -msgid "" -"Drop references that may have created reference cycles. Immutable objects " -"do not have to define this method since they can never directly create " -"reference cycles. Note that the object must still be valid after calling " -"this method (don't just call :c:func:`Py_DECREF` on a reference). The " -"collector will call this method if it detects that this object is involved " -"in a reference cycle." -msgstr "" - -#: ../../c-api/gcsupport.rst:274 -msgid "Controlling the Garbage Collector State" -msgstr "" - -#: ../../c-api/gcsupport.rst:276 -msgid "" -"The C-API provides the following functions for controlling garbage " -"collection runs." -msgstr "" - -#: ../../c-api/gcsupport.rst:281 -msgid "" -"Perform a full garbage collection, if the garbage collector is enabled. " -"(Note that :func:`gc.collect` runs it unconditionally.)" -msgstr "" - -#: ../../c-api/gcsupport.rst:284 -msgid "" -"Returns the number of collected + unreachable objects which cannot be " -"collected. If the garbage collector is disabled or already collecting, " -"returns ``0`` immediately. Errors during garbage collection are passed to :" -"data:`sys.unraisablehook`. This function does not raise exceptions." -msgstr "" - -#: ../../c-api/gcsupport.rst:294 -msgid "" -"Enable the garbage collector: similar to :func:`gc.enable`. Returns the " -"previous state, 0 for disabled and 1 for enabled." -msgstr "" - -#: ../../c-api/gcsupport.rst:302 -msgid "" -"Disable the garbage collector: similar to :func:`gc.disable`. Returns the " -"previous state, 0 for disabled and 1 for enabled." -msgstr "" - -#: ../../c-api/gcsupport.rst:310 -msgid "" -"Query the state of the garbage collector: similar to :func:`gc.isenabled`. " -"Returns the current state, 0 for disabled and 1 for enabled." -msgstr "" - -#: ../../c-api/gcsupport.rst:317 -msgid "Querying Garbage Collector State" -msgstr "" - -#: ../../c-api/gcsupport.rst:319 -msgid "" -"The C-API provides the following interface for querying information about " -"the garbage collector." -msgstr "" - -#: ../../c-api/gcsupport.rst:324 -msgid "" -"Run supplied *callback* on all live GC-capable objects. *arg* is passed " -"through to all invocations of *callback*." -msgstr "" - -#: ../../c-api/gcsupport.rst:328 -msgid "" -"If new objects are (de)allocated by the callback it is undefined if they " -"will be visited." -msgstr "" - -#: ../../c-api/gcsupport.rst:331 -msgid "" -"Garbage collection is disabled during operation. Explicitly running a " -"collection in the callback may lead to undefined behaviour e.g. visiting the " -"same objects multiple times or not at all." -msgstr "" - -#: ../../c-api/gcsupport.rst:339 -msgid "" -"Type of the visitor function to be passed to :c:func:" -"`PyUnstable_GC_VisitObjects`. *arg* is the same as the *arg* passed to " -"``PyUnstable_GC_VisitObjects``. Return ``1`` to continue iteration, return " -"``0`` to stop iteration. Other return values are reserved for now so " -"behavior on returning anything else is undefined." -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-12-09 00:14+0000\n" +"PO-Revision-Date: 2018-05-23 14:31+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" + +#: ../../c-api/gcsupport.rst:6 +msgid "Supporting Cyclic Garbage Collection" +msgstr "循環垃圾回收的支援" + +#: ../../c-api/gcsupport.rst:8 +msgid "" +"Python's support for detecting and collecting garbage which involves " +"circular references requires support from object types which are " +"\"containers\" for other objects which may also be containers. Types which " +"do not store references to other objects, or which only store references to " +"atomic types (such as numbers or strings), do not need to provide any " +"explicit support for garbage collection." +msgstr "" + +#: ../../c-api/gcsupport.rst:15 +msgid "" +"To create a container type, the :c:member:`~PyTypeObject.tp_flags` field of " +"the type object must include the :c:macro:`Py_TPFLAGS_HAVE_GC` and provide " +"an implementation of the :c:member:`~PyTypeObject.tp_traverse` handler. If " +"instances of the type are mutable, a :c:member:`~PyTypeObject.tp_clear` " +"implementation must also be provided." +msgstr "" + +#: ../../c-api/gcsupport.rst:21 +msgid ":c:macro:`Py_TPFLAGS_HAVE_GC`" +msgstr ":c:macro:`Py_TPFLAGS_HAVE_GC`" + +#: ../../c-api/gcsupport.rst:22 +msgid "" +"Objects with a type with this flag set must conform with the rules " +"documented here. For convenience these objects will be referred to as " +"container objects." +msgstr "" + +#: ../../c-api/gcsupport.rst:26 +msgid "Constructors for container types must conform to two rules:" +msgstr "" + +#: ../../c-api/gcsupport.rst:28 +msgid "" +"The memory for the object must be allocated using :c:macro:`PyObject_GC_New` " +"or :c:macro:`PyObject_GC_NewVar`." +msgstr "" + +#: ../../c-api/gcsupport.rst:31 +msgid "" +"Once all the fields which may contain references to other containers are " +"initialized, it must call :c:func:`PyObject_GC_Track`." +msgstr "" + +#: ../../c-api/gcsupport.rst:34 +msgid "" +"Similarly, the deallocator for the object must conform to a similar pair of " +"rules:" +msgstr "" + +#: ../../c-api/gcsupport.rst:37 +msgid "" +"Before fields which refer to other containers are invalidated, :c:func:" +"`PyObject_GC_UnTrack` must be called." +msgstr "" + +#: ../../c-api/gcsupport.rst:40 +msgid "" +"The object's memory must be deallocated using :c:func:`PyObject_GC_Del`." +msgstr "" + +#: ../../c-api/gcsupport.rst:43 +msgid "" +"If a type adds the Py_TPFLAGS_HAVE_GC, then it *must* implement at least a :" +"c:member:`~PyTypeObject.tp_traverse` handler or explicitly use one from its " +"subclass or subclasses." +msgstr "" + +#: ../../c-api/gcsupport.rst:47 +msgid "" +"When calling :c:func:`PyType_Ready` or some of the APIs that indirectly call " +"it like :c:func:`PyType_FromSpecWithBases` or :c:func:`PyType_FromSpec` the " +"interpreter will automatically populate the :c:member:`~PyTypeObject." +"tp_flags`, :c:member:`~PyTypeObject.tp_traverse` and :c:member:" +"`~PyTypeObject.tp_clear` fields if the type inherits from a class that " +"implements the garbage collector protocol and the child class does *not* " +"include the :c:macro:`Py_TPFLAGS_HAVE_GC` flag." +msgstr "" + +#: ../../c-api/gcsupport.rst:57 +msgid "" +"Analogous to :c:macro:`PyObject_New` but for container objects with the :c:" +"macro:`Py_TPFLAGS_HAVE_GC` flag set." +msgstr "" + +#: ../../c-api/gcsupport.rst:60 ../../c-api/gcsupport.rst:84 +msgid "" +"Do not call this directly to allocate memory for an object; call the type's :" +"c:member:`~PyTypeObject.tp_alloc` slot instead." +msgstr "" + +#: ../../c-api/gcsupport.rst:63 ../../c-api/gcsupport.rst:87 +msgid "" +"When populating a type's :c:member:`~PyTypeObject.tp_alloc` slot, :c:func:" +"`PyType_GenericAlloc` is preferred over a custom function that simply calls " +"this macro." +msgstr "" + +#: ../../c-api/gcsupport.rst:67 ../../c-api/gcsupport.rst:91 +msgid "" +"Memory allocated by this macro must be freed with :c:func:`PyObject_GC_Del` " +"(usually called via the object's :c:member:`~PyTypeObject.tp_free` slot)." +msgstr "" + +#: ../../c-api/gcsupport.rst:73 ../../c-api/gcsupport.rst:97 +msgid ":c:func:`PyObject_GC_Del`" +msgstr ":c:func:`PyObject_GC_Del`" + +#: ../../c-api/gcsupport.rst:74 +msgid ":c:macro:`PyObject_New`" +msgstr ":c:macro:`PyObject_New`" + +#: ../../c-api/gcsupport.rst:75 ../../c-api/gcsupport.rst:99 +#: ../../c-api/gcsupport.rst:193 +msgid ":c:func:`PyType_GenericAlloc`" +msgstr ":c:func:`PyType_GenericAlloc`" + +#: ../../c-api/gcsupport.rst:76 ../../c-api/gcsupport.rst:100 +msgid ":c:member:`~PyTypeObject.tp_alloc`" +msgstr ":c:member:`~PyTypeObject.tp_alloc`" + +#: ../../c-api/gcsupport.rst:81 +msgid "" +"Analogous to :c:macro:`PyObject_NewVar` but for container objects with the :" +"c:macro:`Py_TPFLAGS_HAVE_GC` flag set." +msgstr "" + +#: ../../c-api/gcsupport.rst:98 +msgid ":c:macro:`PyObject_NewVar`" +msgstr ":c:macro:`PyObject_NewVar`" + +#: ../../c-api/gcsupport.rst:105 +msgid "" +"Analogous to :c:macro:`PyObject_GC_New` but allocates *extra_size* bytes at " +"the end of the object (at offset :c:member:`~PyTypeObject.tp_basicsize`). " +"The allocated memory is initialized to zeros, except for the :c:type:`Python " +"object header `." +msgstr "" + +#: ../../c-api/gcsupport.rst:111 +msgid "" +"The extra data will be deallocated with the object, but otherwise it is not " +"managed by Python." +msgstr "" + +#: ../../c-api/gcsupport.rst:114 +msgid "" +"Memory allocated by this function must be freed with :c:func:" +"`PyObject_GC_Del` (usually called via the object's :c:member:`~PyTypeObject." +"tp_free` slot)." +msgstr "" + +#: ../../c-api/gcsupport.rst:119 +msgid "" +"The function is marked as unstable because the final mechanism for reserving " +"extra data after an instance is not yet decided. For allocating a variable " +"number of fields, prefer using :c:type:`PyVarObject` and :c:member:" +"`~PyTypeObject.tp_itemsize` instead." +msgstr "" + +#: ../../c-api/gcsupport.rst:130 +msgid "" +"Resize an object allocated by :c:macro:`PyObject_NewVar`. Returns the " +"resized object of type ``TYPE*`` (refers to any C type) or ``NULL`` on " +"failure." +msgstr "" + +#: ../../c-api/gcsupport.rst:134 +msgid "" +"*op* must be of type :c:expr:`PyVarObject *` and must not be tracked by the " +"collector yet. *newsize* must be of type :c:type:`Py_ssize_t`." +msgstr "" + +#: ../../c-api/gcsupport.rst:141 +msgid "" +"Adds the object *op* to the set of container objects tracked by the " +"collector. The collector can run at unexpected times so objects must be " +"valid while being tracked. This should be called once all the fields " +"followed by the :c:member:`~PyTypeObject.tp_traverse` handler become valid, " +"usually near the end of the constructor." +msgstr "" + +#: ../../c-api/gcsupport.rst:150 +msgid "" +"Returns non-zero if the object implements the garbage collector protocol, " +"otherwise returns 0." +msgstr "" + +#: ../../c-api/gcsupport.rst:153 +msgid "" +"The object cannot be tracked by the garbage collector if this function " +"returns 0." +msgstr "" + +#: ../../c-api/gcsupport.rst:158 +msgid "" +"Returns 1 if the object type of *op* implements the GC protocol and *op* is " +"being currently tracked by the garbage collector and 0 otherwise." +msgstr "" + +#: ../../c-api/gcsupport.rst:161 +msgid "This is analogous to the Python function :func:`gc.is_tracked`." +msgstr "" + +#: ../../c-api/gcsupport.rst:168 +msgid "" +"Returns 1 if the object type of *op* implements the GC protocol and *op* has " +"been already finalized by the garbage collector and 0 otherwise." +msgstr "" + +#: ../../c-api/gcsupport.rst:171 +msgid "This is analogous to the Python function :func:`gc.is_finalized`." +msgstr "" + +#: ../../c-api/gcsupport.rst:178 +msgid "" +"Releases memory allocated to an object using :c:macro:`PyObject_GC_New` or :" +"c:macro:`PyObject_GC_NewVar`." +msgstr "" + +#: ../../c-api/gcsupport.rst:181 +msgid "" +"Do not call this directly to free an object's memory; call the type's :c:" +"member:`~PyTypeObject.tp_free` slot instead." +msgstr "" + +#: ../../c-api/gcsupport.rst:184 +msgid "" +"Do not use this for memory allocated by :c:macro:`PyObject_New`, :c:macro:" +"`PyObject_NewVar`, or related allocation functions; use :c:func:" +"`PyObject_Free` instead." +msgstr "" + +#: ../../c-api/gcsupport.rst:190 +msgid ":c:func:`PyObject_Free` is the non-GC equivalent of this function." +msgstr "" + +#: ../../c-api/gcsupport.rst:191 +msgid ":c:macro:`PyObject_GC_New`" +msgstr ":c:macro:`PyObject_GC_New`" + +#: ../../c-api/gcsupport.rst:192 +msgid ":c:macro:`PyObject_GC_NewVar`" +msgstr ":c:macro:`PyObject_GC_NewVar`" + +#: ../../c-api/gcsupport.rst:194 +msgid ":c:member:`~PyTypeObject.tp_free`" +msgstr ":c:member:`~PyTypeObject.tp_free`" + +#: ../../c-api/gcsupport.rst:199 +msgid "" +"Remove the object *op* from the set of container objects tracked by the " +"collector. Note that :c:func:`PyObject_GC_Track` can be called again on " +"this object to add it back to the set of tracked objects. The deallocator (:" +"c:member:`~PyTypeObject.tp_dealloc` handler) should call this for the object " +"before any of the fields used by the :c:member:`~PyTypeObject.tp_traverse` " +"handler become invalid." +msgstr "" + +#: ../../c-api/gcsupport.rst:208 +msgid "" +"The :c:func:`!_PyObject_GC_TRACK` and :c:func:`!_PyObject_GC_UNTRACK` macros " +"have been removed from the public C API." +msgstr "" + +#: ../../c-api/gcsupport.rst:211 +msgid "" +"The :c:member:`~PyTypeObject.tp_traverse` handler accepts a function " +"parameter of this type:" +msgstr "" + +#: ../../c-api/gcsupport.rst:216 +msgid "" +"Type of the visitor function passed to the :c:member:`~PyTypeObject." +"tp_traverse` handler. The function should be called with an object to " +"traverse as *object* and the third parameter to the :c:member:`~PyTypeObject." +"tp_traverse` handler as *arg*. The Python core uses several visitor " +"functions to implement cyclic garbage detection; it's not expected that " +"users will need to write their own visitor functions." +msgstr "" + +#: ../../c-api/gcsupport.rst:223 +msgid "" +"The :c:member:`~PyTypeObject.tp_traverse` handler must have the following " +"type:" +msgstr "" + +#: ../../c-api/gcsupport.rst:228 +msgid "" +"Traversal function for a container object. Implementations must call the " +"*visit* function for each object directly contained by *self*, with the " +"parameters to *visit* being the contained object and the *arg* value passed " +"to the handler. The *visit* function must not be called with a ``NULL`` " +"object argument. If *visit* returns a non-zero value that value should be " +"returned immediately." +msgstr "" + +#: ../../c-api/gcsupport.rst:235 +msgid "" +"The traversal function must not have any side effects. Implementations may " +"not modify the reference counts of any Python objects nor create or destroy " +"any Python objects." +msgstr "" + +#: ../../c-api/gcsupport.rst:239 +msgid "" +"To simplify writing :c:member:`~PyTypeObject.tp_traverse` handlers, a :c:" +"func:`Py_VISIT` macro is provided. In order to use this macro, the :c:" +"member:`~PyTypeObject.tp_traverse` implementation must name its arguments " +"exactly *visit* and *arg*:" +msgstr "" + +#: ../../c-api/gcsupport.rst:246 +msgid "" +"If the :c:expr:`PyObject *` *o* is not ``NULL``, call the *visit* callback, " +"with arguments *o* and *arg*. If *visit* returns a non-zero value, then " +"return it. Using this macro, :c:member:`~PyTypeObject.tp_traverse` handlers " +"look like::" +msgstr "" + +#: ../../c-api/gcsupport.rst:251 +msgid "" +"static int\n" +"my_traverse(Noddy *self, visitproc visit, void *arg)\n" +"{\n" +" Py_VISIT(self->foo);\n" +" Py_VISIT(self->bar);\n" +" return 0;\n" +"}" +msgstr "" +"static int\n" +"my_traverse(Noddy *self, visitproc visit, void *arg)\n" +"{\n" +" Py_VISIT(self->foo);\n" +" Py_VISIT(self->bar);\n" +" return 0;\n" +"}" + +#: ../../c-api/gcsupport.rst:259 +msgid "" +"The :c:member:`~PyTypeObject.tp_clear` handler must be of the :c:type:" +"`inquiry` type, or ``NULL`` if the object is immutable." +msgstr "" + +#: ../../c-api/gcsupport.rst:265 +msgid "" +"Drop references that may have created reference cycles. Immutable objects " +"do not have to define this method since they can never directly create " +"reference cycles. Note that the object must still be valid after calling " +"this method (don't just call :c:func:`Py_DECREF` on a reference). The " +"collector will call this method if it detects that this object is involved " +"in a reference cycle." +msgstr "" + +#: ../../c-api/gcsupport.rst:274 +msgid "Controlling the Garbage Collector State" +msgstr "" + +#: ../../c-api/gcsupport.rst:276 +msgid "" +"The C-API provides the following functions for controlling garbage " +"collection runs." +msgstr "" + +#: ../../c-api/gcsupport.rst:281 +msgid "" +"Perform a full garbage collection, if the garbage collector is enabled. " +"(Note that :func:`gc.collect` runs it unconditionally.)" +msgstr "" + +#: ../../c-api/gcsupport.rst:284 +msgid "" +"Returns the number of collected + unreachable objects which cannot be " +"collected. If the garbage collector is disabled or already collecting, " +"returns ``0`` immediately. Errors during garbage collection are passed to :" +"data:`sys.unraisablehook`. This function does not raise exceptions." +msgstr "" + +#: ../../c-api/gcsupport.rst:294 +msgid "" +"Enable the garbage collector: similar to :func:`gc.enable`. Returns the " +"previous state, 0 for disabled and 1 for enabled." +msgstr "" + +#: ../../c-api/gcsupport.rst:302 +msgid "" +"Disable the garbage collector: similar to :func:`gc.disable`. Returns the " +"previous state, 0 for disabled and 1 for enabled." +msgstr "" + +#: ../../c-api/gcsupport.rst:310 +msgid "" +"Query the state of the garbage collector: similar to :func:`gc.isenabled`. " +"Returns the current state, 0 for disabled and 1 for enabled." +msgstr "" + +#: ../../c-api/gcsupport.rst:317 +msgid "Querying Garbage Collector State" +msgstr "" + +#: ../../c-api/gcsupport.rst:319 +msgid "" +"The C-API provides the following interface for querying information about " +"the garbage collector." +msgstr "" + +#: ../../c-api/gcsupport.rst:324 +msgid "" +"Run supplied *callback* on all live GC-capable objects. *arg* is passed " +"through to all invocations of *callback*." +msgstr "" + +#: ../../c-api/gcsupport.rst:328 +msgid "" +"If new objects are (de)allocated by the callback it is undefined if they " +"will be visited." +msgstr "" + +#: ../../c-api/gcsupport.rst:331 +msgid "" +"Garbage collection is disabled during operation. Explicitly running a " +"collection in the callback may lead to undefined behaviour e.g. visiting the " +"same objects multiple times or not at all." +msgstr "" + +#: ../../c-api/gcsupport.rst:339 +msgid "" +"Type of the visitor function to be passed to :c:func:" +"`PyUnstable_GC_VisitObjects`. *arg* is the same as the *arg* passed to " +"``PyUnstable_GC_VisitObjects``. Return ``1`` to continue iteration, return " +"``0`` to stop iteration. Other return values are reserved for now so " +"behavior on returning anything else is undefined." +msgstr "" diff --git a/c-api/gen.po b/c-api/gen.po index d3c409ea04..38b0873ba0 100644 --- a/c-api/gen.po +++ b/c-api/gen.po @@ -1,130 +1,130 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Leon H., 2017 -# Matt Wang , 2021 -# -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-20 17:54+0000\n" -"PO-Revision-Date: 2022-10-16 15:33+0800\n" -"Last-Translator: Matt Wang \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" -"X-Generator: Poedit 3.1.1\n" - -#: ../../c-api/gen.rst:6 -msgid "Generator Objects" -msgstr "產生器 (Generator) 物件" - -#: ../../c-api/gen.rst:8 -msgid "" -"Generator objects are what Python uses to implement generator iterators. " -"They are normally created by iterating over a function that yields values, " -"rather than explicitly calling :c:func:`PyGen_New` or :c:func:" -"`PyGen_NewWithQualName`." -msgstr "" -"產生器物件是 Python 用來實現產生器疊代器 (generator iterator) 的物件。它們通" -"常透過疊代會產生值的函式來建立，而不是顯式呼叫 :c:func:`PyGen_New` 或 :c:" -"func:`PyGen_NewWithQualName`。" - -#: ../../c-api/gen.rst:15 -msgid "The C structure used for generator objects." -msgstr "用於產生器物件的 C 結構。" - -#: ../../c-api/gen.rst:20 -msgid "The type object corresponding to generator objects." -msgstr "與產生器物件對應的型別物件。" - -#: ../../c-api/gen.rst:25 -msgid "" -"Return true if *ob* is a generator object; *ob* must not be ``NULL``. This " -"function always succeeds." -msgstr "" -"如果 *ob* 是一個產生器 (generator) 物件則回傳真值；*ob* 必須不為 ``NULL``。此" -"函式總是會成功執行。" - -#: ../../c-api/gen.rst:31 -msgid "" -"Return true if *ob*'s type is :c:type:`PyGen_Type`; *ob* must not be " -"``NULL``. This function always succeeds." -msgstr "" -"如果 *ob* 的型別是 :c:type:`PyGen_Type` 則回傳真值；*ob* 必須不為 ``NULL``。" -"此函式總是會成功執行。" - -#: ../../c-api/gen.rst:37 -msgid "" -"Create and return a new generator object based on the *frame* object. A " -"reference to *frame* is stolen by this function. The argument must not be " -"``NULL``." -msgstr "" -"基於 *frame* 物件建立並回傳一個新的產生器物件。此函式會取走一個對 *frame* 的" -"參照 (reference)。引數必須不為 ``NULL``。" - -#: ../../c-api/gen.rst:43 -msgid "" -"Create and return a new generator object based on the *frame* object, with " -"``__name__`` and ``__qualname__`` set to *name* and *qualname*. A reference " -"to *frame* is stolen by this function. The *frame* argument must not be " -"``NULL``." -msgstr "" -"基於 *frame* 物件建立並回傳一個新的產生器物件，其中 ``__name__`` 和 " -"``__qualname__`` 設為 *name* 和 *qualname*。此函式會取走一個對 *frame* 的參" -"照。*frame* 引數必須不為 ``NULL``。" - -#: ../../c-api/gen.rst:50 -msgid "" -"Return a new :term:`strong reference` to the code object wrapped by *gen*. " -"This function always succeeds." -msgstr "" -"回傳一個對 *gen* 所包裝的程式碼物件的新\\ :term:`強參照 `。" -"此函式總是會成功執行。" - -#: ../../c-api/gen.rst:55 -msgid "Asynchronous Generator Objects" -msgstr "非同步產生器 (Asynchronous Generator) 物件" - -#: ../../c-api/gen.rst:58 -msgid ":pep:`525`" -msgstr ":pep:`525`" - -#: ../../c-api/gen.rst:62 -msgid "" -"The type object corresponding to asynchronous generator objects. This is " -"available as :class:`types.AsyncGeneratorType` in the Python layer." -msgstr "" -"與非同步產生器物件對應的型別物件。在 Python 層中可以 :class:`types." -"AsyncGeneratorType` 使用。" - -#: ../../c-api/gen.rst:69 -msgid "" -"Create a new asynchronous generator wrapping *frame*, with ``__name__`` and " -"``__qualname__`` set to *name* and *qualname*. *frame* is stolen by this " -"function and must not be ``NULL``." -msgstr "" -"建立一個包裝 *frame* 的非同步產生器，並將 ``__name__`` 和 ``__qualname__`` 設為 " -"*name* 和 *qualname*。*frame* 會被此函式取走，且不得為 ``NULL``。" - -#: ../../c-api/gen.rst:73 -msgid "" -"On success, this function returns a :term:`strong reference` to the new " -"asynchronous generator. On failure, this function returns ``NULL`` with an " -"exception set." -msgstr "" -"成功時此函式回傳對新的非同步產生器的\\ :term:`強參照 `。失敗" -"時此函式回傳 ``NULL`` 並設定一個例外。" - -#: ../../c-api/gen.rst:81 -msgid "" -"Return true if *op* is an asynchronous generator object, false otherwise. " -"This function always succeeds." -msgstr "" -"如果 *op* 是一個非同步產生器物件則回傳 true，否則回傳 false。此函式總是會成功執行。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Leon H., 2017 +# Matt Wang , 2021 +# +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-20 17:54+0000\n" +"PO-Revision-Date: 2022-10-16 15:33+0800\n" +"Last-Translator: Matt Wang \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" +"X-Generator: Poedit 3.1.1\n" + +#: ../../c-api/gen.rst:6 +msgid "Generator Objects" +msgstr "產生器 (Generator) 物件" + +#: ../../c-api/gen.rst:8 +msgid "" +"Generator objects are what Python uses to implement generator iterators. " +"They are normally created by iterating over a function that yields values, " +"rather than explicitly calling :c:func:`PyGen_New` or :c:func:" +"`PyGen_NewWithQualName`." +msgstr "" +"產生器物件是 Python 用來實現產生器疊代器 (generator iterator) 的物件。它們通" +"常透過疊代會產生值的函式來建立，而不是顯式呼叫 :c:func:`PyGen_New` 或 :c:" +"func:`PyGen_NewWithQualName`。" + +#: ../../c-api/gen.rst:15 +msgid "The C structure used for generator objects." +msgstr "用於產生器物件的 C 結構。" + +#: ../../c-api/gen.rst:20 +msgid "The type object corresponding to generator objects." +msgstr "與產生器物件對應的型別物件。" + +#: ../../c-api/gen.rst:25 +msgid "" +"Return true if *ob* is a generator object; *ob* must not be ``NULL``. This " +"function always succeeds." +msgstr "" +"如果 *ob* 是一個產生器 (generator) 物件則回傳真值；*ob* 必須不為 ``NULL``。此" +"函式總是會成功執行。" + +#: ../../c-api/gen.rst:31 +msgid "" +"Return true if *ob*'s type is :c:type:`PyGen_Type`; *ob* must not be " +"``NULL``. This function always succeeds." +msgstr "" +"如果 *ob* 的型別是 :c:type:`PyGen_Type` 則回傳真值；*ob* 必須不為 ``NULL``。" +"此函式總是會成功執行。" + +#: ../../c-api/gen.rst:37 +msgid "" +"Create and return a new generator object based on the *frame* object. A " +"reference to *frame* is stolen by this function. The argument must not be " +"``NULL``." +msgstr "" +"基於 *frame* 物件建立並回傳一個新的產生器物件。此函式會取走一個對 *frame* 的" +"參照 (reference)。引數必須不為 ``NULL``。" + +#: ../../c-api/gen.rst:43 +msgid "" +"Create and return a new generator object based on the *frame* object, with " +"``__name__`` and ``__qualname__`` set to *name* and *qualname*. A reference " +"to *frame* is stolen by this function. The *frame* argument must not be " +"``NULL``." +msgstr "" +"基於 *frame* 物件建立並回傳一個新的產生器物件，其中 ``__name__`` 和 " +"``__qualname__`` 設為 *name* 和 *qualname*。此函式會取走一個對 *frame* 的參" +"照。*frame* 引數必須不為 ``NULL``。" + +#: ../../c-api/gen.rst:50 +msgid "" +"Return a new :term:`strong reference` to the code object wrapped by *gen*. " +"This function always succeeds." +msgstr "" +"回傳一個對 *gen* 所包裝的程式碼物件的新\\ :term:`強參照 `。" +"此函式總是會成功執行。" + +#: ../../c-api/gen.rst:55 +msgid "Asynchronous Generator Objects" +msgstr "非同步產生器 (Asynchronous Generator) 物件" + +#: ../../c-api/gen.rst:58 +msgid ":pep:`525`" +msgstr ":pep:`525`" + +#: ../../c-api/gen.rst:62 +msgid "" +"The type object corresponding to asynchronous generator objects. This is " +"available as :class:`types.AsyncGeneratorType` in the Python layer." +msgstr "" +"與非同步產生器物件對應的型別物件。在 Python 層中可以 :class:`types." +"AsyncGeneratorType` 使用。" + +#: ../../c-api/gen.rst:69 +msgid "" +"Create a new asynchronous generator wrapping *frame*, with ``__name__`` and " +"``__qualname__`` set to *name* and *qualname*. *frame* is stolen by this " +"function and must not be ``NULL``." +msgstr "" +"建立一個包裝 *frame* 的非同步產生器，並將 ``__name__`` 和 ``__qualname__`` 設為 " +"*name* 和 *qualname*。*frame* 會被此函式取走，且不得為 ``NULL``。" + +#: ../../c-api/gen.rst:73 +msgid "" +"On success, this function returns a :term:`strong reference` to the new " +"asynchronous generator. On failure, this function returns ``NULL`` with an " +"exception set." +msgstr "" +"成功時此函式回傳對新的非同步產生器的\\ :term:`強參照 `。失敗" +"時此函式回傳 ``NULL`` 並設定一個例外。" + +#: ../../c-api/gen.rst:81 +msgid "" +"Return true if *op* is an asynchronous generator object, false otherwise. " +"This function always succeeds." +msgstr "" +"如果 *op* 是一個非同步產生器物件則回傳 true，否則回傳 false。此函式總是會成功執行。" diff --git a/c-api/hash.po b/c-api/hash.po index 7ec708bf84..f8fef77548 100644 --- a/c-api/hash.po +++ b/c-api/hash.po @@ -1,210 +1,210 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Matt Wang , 2024 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-09 00:17+0000\n" -"PO-Revision-Date: 2024-04-30 00:20+0800\n" -"Last-Translator: Matt Wang \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" - -#: ../../c-api/hash.rst:4 -msgid "PyHash API" -msgstr "PyHash API" - -#: ../../c-api/hash.rst:6 -msgid "" -"See also the :c:member:`PyTypeObject.tp_hash` member and :ref:`numeric-hash`." -msgstr "另請參閱 :c:member:`PyTypeObject.tp_hash` 成員和 :ref:`numeric-hash`。" - -#: ../../c-api/hash.rst:10 -msgid "Hash value type: signed integer." -msgstr "雜湊值型別：有符號整數。" - -#: ../../c-api/hash.rst:17 -msgid "Hash value type: unsigned integer." -msgstr "雜湊值型別：無符號整數。" - -#: ../../c-api/hash.rst:24 -msgid "" -"A numerical value indicating the algorithm for hashing of :class:`str`, :" -"class:`bytes`, and :class:`memoryview`." -msgstr "" - -#: ../../c-api/hash.rst:27 -msgid "The algorithm name is exposed by :data:`sys.hash_info.algorithm`." -msgstr "演算式名稱由 :data:`sys.hash_info.algorithm` 公開。" - -#: ../../c-api/hash.rst:36 -msgid "" -"Numerical values to compare to :c:macro:`Py_HASH_ALGORITHM` to determine " -"which algorithm is used for hashing. The hash algorithm can be configured " -"via the configure :option:`--with-hash-algorithm` option." -msgstr "" - -#: ../../c-api/hash.rst:40 -msgid "Add :c:macro:`!Py_HASH_FNV` and :c:macro:`!Py_HASH_SIPHASH24`." -msgstr "新增 :c:macro:`!Py_HASH_FNV` 和 :c:macro:`!Py_HASH_SIPHASH24`。" - -#: ../../c-api/hash.rst:43 -msgid "Add :c:macro:`!Py_HASH_SIPHASH13`." -msgstr "新增 :c:macro:`!Py_HASH_SIPHASH13`。" - -#: ../../c-api/hash.rst:49 -msgid "" -"Buffers of length in range ``[1, Py_HASH_CUTOFF)`` are hashed using DJBX33A " -"instead of the algorithm described by :c:macro:`Py_HASH_ALGORITHM`." -msgstr "" - -#: ../../c-api/hash.rst:52 -msgid "A :c:macro:`!Py_HASH_CUTOFF` of 0 disables the optimization." -msgstr "將 :c:macro:`!Py_HASH_CUTOFF` 設為 0 可停用此最佳化。" - -#: ../../c-api/hash.rst:53 -msgid "" -":c:macro:`!Py_HASH_CUTOFF` must be non-negative and less or equal than 7." -msgstr ":c:macro:`!Py_HASH_CUTOFF` 必須為非負且小於或等於 7。" - -#: ../../c-api/hash.rst:55 -msgid "" -"32-bit platforms should use a cutoff smaller than 64-bit platforms because " -"it is easier to create colliding strings. A cutoff of 7 on 64-bit platforms " -"and 5 on 32-bit platforms should provide a decent safety margin." -msgstr "" - -#: ../../c-api/hash.rst:59 -msgid "This corresponds to the :data:`sys.hash_info.cutoff` constant." -msgstr "這對應到 :data:`sys.hash_info.cutoff` 常數。" - -#: ../../c-api/hash.rst:66 -msgid "" -"The `Mersenne prime `_ ``P = " -"2**n -1``, used for numeric hash scheme." -msgstr "" -"用於數值雜湊方案的\\ `梅森質數 (Mersenne prime) `_ ``P = 2**n -1``。" - -#: ../../c-api/hash.rst:69 -msgid "This corresponds to the :data:`sys.hash_info.modulus` constant." -msgstr "這對應到 :data:`sys.hash_info.modulus` 常數。" - -#: ../../c-api/hash.rst:76 -msgid "The exponent ``n`` of ``P`` in :c:macro:`PyHASH_MODULUS`." -msgstr ":c:macro:`PyHASH_MODULUS` 中 ``P`` 的指數 ``n``。" - -#: ../../c-api/hash.rst:83 -msgid "Prime multiplier used in string and various other hashes." -msgstr "用於字串和其他各種雜湊的質數乘數 (prime multiplier)。" - -#: ../../c-api/hash.rst:90 -msgid "The hash value returned for a positive infinity." -msgstr "正無窮大回傳的雜湊值。" - -#: ../../c-api/hash.rst:92 -msgid "This corresponds to the :data:`sys.hash_info.inf` constant." -msgstr "這對應到 :data:`sys.hash_info.inf` 常數。" - -#: ../../c-api/hash.rst:99 -msgid "The multiplier used for the imaginary part of a complex number." -msgstr "用於複數虛數部分的乘數。" - -#: ../../c-api/hash.rst:101 -msgid "This corresponds to the :data:`sys.hash_info.imag` constant." -msgstr "這對應到 :data:`sys.hash_info.imag` 常數。" - -#: ../../c-api/hash.rst:108 -msgid "Hash function definition used by :c:func:`PyHash_GetFuncDef`." -msgstr ":c:func:`PyHash_GetFuncDef` 所使用的雜湊函式定義。" - -#: ../../c-api/hash.rst:112 -msgid "Hash function." -msgstr "雜湊函式。" - -#: ../../c-api/hash.rst:116 -msgid "Hash function name (UTF-8 encoded string)." -msgstr "雜湊函式名稱（UTF-8 編碼字串）。" - -#: ../../c-api/hash.rst:118 -msgid "This corresponds to the :data:`sys.hash_info.algorithm` constant." -msgstr "這對應到 :data:`sys.hash_info.algorithm` 常數。" - -#: ../../c-api/hash.rst:122 -msgid "Internal size of the hash value in bits." -msgstr "雜湊值的內部大小（以位元為單位）。" - -#: ../../c-api/hash.rst:124 -msgid "This corresponds to the :data:`sys.hash_info.hash_bits` constant." -msgstr "這對應到 :data:`sys.hash_info.hash_bits` 常數。" - -#: ../../c-api/hash.rst:128 -msgid "Size of seed input in bits." -msgstr "Seed 輸入的大小（以位元為單位）。" - -#: ../../c-api/hash.rst:130 -msgid "This corresponds to the :data:`sys.hash_info.seed_bits` constant." -msgstr "這對應到 :data:`sys.hash_info.seed_bits` 常數。" - -#: ../../c-api/hash.rst:137 -msgid "Get the hash function definition." -msgstr "取得雜湊函式定義。" - -#: ../../c-api/hash.rst:140 -msgid ":pep:`456` \"Secure and interchangeable hash algorithm\"." -msgstr "" -":pep:`456`\\ 「安全且可交替使用的雜湊演算法 (Secure and interchangeable hash " -"algorithm)」。" - -#: ../../c-api/hash.rst:147 -msgid "" -"Hash a pointer value: process the pointer value as an integer (cast it to " -"``uintptr_t`` internally). The pointer is not dereferenced." -msgstr "" -"雜湊指標值：將指標值作為整數處理（在內部轉型為 ``uintptr_t``）。指標不會被取" -"值 (dereference)。" - -#: ../../c-api/hash.rst:150 -msgid "The function cannot fail: it cannot return ``-1``." -msgstr "此函式不會失敗：它不會回傳 ``-1``。" - -#: ../../c-api/hash.rst:157 -msgid "" -"Compute and return the hash value of a buffer of *len* bytes starting at " -"address *ptr*. The hash is guaranteed to match that of :class:`bytes`, :" -"class:`memoryview`, and other built-in objects that implement the :ref:" -"`buffer protocol `." -msgstr "" - -#: ../../c-api/hash.rst:162 -msgid "" -"Use this function to implement hashing for immutable objects whose :c:member:" -"`~PyTypeObject.tp_richcompare` function compares to another object's buffer." -msgstr "" - -#: ../../c-api/hash.rst:166 -msgid "*len* must be greater than or equal to ``0``." -msgstr "*len* 必須大於或等於 ``0``。" - -#: ../../c-api/hash.rst:168 -msgid "This function always succeeds." -msgstr "此函式總是會成功執行。" - -#: ../../c-api/hash.rst:175 -msgid "" -"Generic hashing function that is meant to be put into a type object's " -"``tp_hash`` slot. Its result only depends on the object's identity." -msgstr "" -"泛用雜湊函式，旨在放入型別物件的 ``tp_hash`` 插槽中。其結果僅取決於物件的識別" -"性。" - -#: ../../c-api/hash.rst:180 -msgid "In CPython, it is equivalent to :c:func:`Py_HashPointer`." -msgstr "在 CPython 中，它等價於 :c:func:`Py_HashPointer`。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Matt Wang , 2024 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-09 00:17+0000\n" +"PO-Revision-Date: 2024-04-30 00:20+0800\n" +"Last-Translator: Matt Wang \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" + +#: ../../c-api/hash.rst:4 +msgid "PyHash API" +msgstr "PyHash API" + +#: ../../c-api/hash.rst:6 +msgid "" +"See also the :c:member:`PyTypeObject.tp_hash` member and :ref:`numeric-hash`." +msgstr "另請參閱 :c:member:`PyTypeObject.tp_hash` 成員和 :ref:`numeric-hash`。" + +#: ../../c-api/hash.rst:10 +msgid "Hash value type: signed integer." +msgstr "雜湊值型別：有符號整數。" + +#: ../../c-api/hash.rst:17 +msgid "Hash value type: unsigned integer." +msgstr "雜湊值型別：無符號整數。" + +#: ../../c-api/hash.rst:24 +msgid "" +"A numerical value indicating the algorithm for hashing of :class:`str`, :" +"class:`bytes`, and :class:`memoryview`." +msgstr "" + +#: ../../c-api/hash.rst:27 +msgid "The algorithm name is exposed by :data:`sys.hash_info.algorithm`." +msgstr "演算式名稱由 :data:`sys.hash_info.algorithm` 公開。" + +#: ../../c-api/hash.rst:36 +msgid "" +"Numerical values to compare to :c:macro:`Py_HASH_ALGORITHM` to determine " +"which algorithm is used for hashing. The hash algorithm can be configured " +"via the configure :option:`--with-hash-algorithm` option." +msgstr "" + +#: ../../c-api/hash.rst:40 +msgid "Add :c:macro:`!Py_HASH_FNV` and :c:macro:`!Py_HASH_SIPHASH24`." +msgstr "新增 :c:macro:`!Py_HASH_FNV` 和 :c:macro:`!Py_HASH_SIPHASH24`。" + +#: ../../c-api/hash.rst:43 +msgid "Add :c:macro:`!Py_HASH_SIPHASH13`." +msgstr "新增 :c:macro:`!Py_HASH_SIPHASH13`。" + +#: ../../c-api/hash.rst:49 +msgid "" +"Buffers of length in range ``[1, Py_HASH_CUTOFF)`` are hashed using DJBX33A " +"instead of the algorithm described by :c:macro:`Py_HASH_ALGORITHM`." +msgstr "" + +#: ../../c-api/hash.rst:52 +msgid "A :c:macro:`!Py_HASH_CUTOFF` of 0 disables the optimization." +msgstr "將 :c:macro:`!Py_HASH_CUTOFF` 設為 0 可停用此最佳化。" + +#: ../../c-api/hash.rst:53 +msgid "" +":c:macro:`!Py_HASH_CUTOFF` must be non-negative and less or equal than 7." +msgstr ":c:macro:`!Py_HASH_CUTOFF` 必須為非負且小於或等於 7。" + +#: ../../c-api/hash.rst:55 +msgid "" +"32-bit platforms should use a cutoff smaller than 64-bit platforms because " +"it is easier to create colliding strings. A cutoff of 7 on 64-bit platforms " +"and 5 on 32-bit platforms should provide a decent safety margin." +msgstr "" + +#: ../../c-api/hash.rst:59 +msgid "This corresponds to the :data:`sys.hash_info.cutoff` constant." +msgstr "這對應到 :data:`sys.hash_info.cutoff` 常數。" + +#: ../../c-api/hash.rst:66 +msgid "" +"The `Mersenne prime `_ ``P = " +"2**n -1``, used for numeric hash scheme." +msgstr "" +"用於數值雜湊方案的\\ `梅森質數 (Mersenne prime) `_ ``P = 2**n -1``。" + +#: ../../c-api/hash.rst:69 +msgid "This corresponds to the :data:`sys.hash_info.modulus` constant." +msgstr "這對應到 :data:`sys.hash_info.modulus` 常數。" + +#: ../../c-api/hash.rst:76 +msgid "The exponent ``n`` of ``P`` in :c:macro:`PyHASH_MODULUS`." +msgstr ":c:macro:`PyHASH_MODULUS` 中 ``P`` 的指數 ``n``。" + +#: ../../c-api/hash.rst:83 +msgid "Prime multiplier used in string and various other hashes." +msgstr "用於字串和其他各種雜湊的質數乘數 (prime multiplier)。" + +#: ../../c-api/hash.rst:90 +msgid "The hash value returned for a positive infinity." +msgstr "正無窮大回傳的雜湊值。" + +#: ../../c-api/hash.rst:92 +msgid "This corresponds to the :data:`sys.hash_info.inf` constant." +msgstr "這對應到 :data:`sys.hash_info.inf` 常數。" + +#: ../../c-api/hash.rst:99 +msgid "The multiplier used for the imaginary part of a complex number." +msgstr "用於複數虛數部分的乘數。" + +#: ../../c-api/hash.rst:101 +msgid "This corresponds to the :data:`sys.hash_info.imag` constant." +msgstr "這對應到 :data:`sys.hash_info.imag` 常數。" + +#: ../../c-api/hash.rst:108 +msgid "Hash function definition used by :c:func:`PyHash_GetFuncDef`." +msgstr ":c:func:`PyHash_GetFuncDef` 所使用的雜湊函式定義。" + +#: ../../c-api/hash.rst:112 +msgid "Hash function." +msgstr "雜湊函式。" + +#: ../../c-api/hash.rst:116 +msgid "Hash function name (UTF-8 encoded string)." +msgstr "雜湊函式名稱（UTF-8 編碼字串）。" + +#: ../../c-api/hash.rst:118 +msgid "This corresponds to the :data:`sys.hash_info.algorithm` constant." +msgstr "這對應到 :data:`sys.hash_info.algorithm` 常數。" + +#: ../../c-api/hash.rst:122 +msgid "Internal size of the hash value in bits." +msgstr "雜湊值的內部大小（以位元為單位）。" + +#: ../../c-api/hash.rst:124 +msgid "This corresponds to the :data:`sys.hash_info.hash_bits` constant." +msgstr "這對應到 :data:`sys.hash_info.hash_bits` 常數。" + +#: ../../c-api/hash.rst:128 +msgid "Size of seed input in bits." +msgstr "Seed 輸入的大小（以位元為單位）。" + +#: ../../c-api/hash.rst:130 +msgid "This corresponds to the :data:`sys.hash_info.seed_bits` constant." +msgstr "這對應到 :data:`sys.hash_info.seed_bits` 常數。" + +#: ../../c-api/hash.rst:137 +msgid "Get the hash function definition." +msgstr "取得雜湊函式定義。" + +#: ../../c-api/hash.rst:140 +msgid ":pep:`456` \"Secure and interchangeable hash algorithm\"." +msgstr "" +":pep:`456`\\ 「安全且可交替使用的雜湊演算法 (Secure and interchangeable hash " +"algorithm)」。" + +#: ../../c-api/hash.rst:147 +msgid "" +"Hash a pointer value: process the pointer value as an integer (cast it to " +"``uintptr_t`` internally). The pointer is not dereferenced." +msgstr "" +"雜湊指標值：將指標值作為整數處理（在內部轉型為 ``uintptr_t``）。指標不會被取" +"值 (dereference)。" + +#: ../../c-api/hash.rst:150 +msgid "The function cannot fail: it cannot return ``-1``." +msgstr "此函式不會失敗：它不會回傳 ``-1``。" + +#: ../../c-api/hash.rst:157 +msgid "" +"Compute and return the hash value of a buffer of *len* bytes starting at " +"address *ptr*. The hash is guaranteed to match that of :class:`bytes`, :" +"class:`memoryview`, and other built-in objects that implement the :ref:" +"`buffer protocol `." +msgstr "" + +#: ../../c-api/hash.rst:162 +msgid "" +"Use this function to implement hashing for immutable objects whose :c:member:" +"`~PyTypeObject.tp_richcompare` function compares to another object's buffer." +msgstr "" + +#: ../../c-api/hash.rst:166 +msgid "*len* must be greater than or equal to ``0``." +msgstr "*len* 必須大於或等於 ``0``。" + +#: ../../c-api/hash.rst:168 +msgid "This function always succeeds." +msgstr "此函式總是會成功執行。" + +#: ../../c-api/hash.rst:175 +msgid "" +"Generic hashing function that is meant to be put into a type object's " +"``tp_hash`` slot. Its result only depends on the object's identity." +msgstr "" +"泛用雜湊函式，旨在放入型別物件的 ``tp_hash`` 插槽中。其結果僅取決於物件的識別" +"性。" + +#: ../../c-api/hash.rst:180 +msgid "In CPython, it is equivalent to :c:func:`Py_HashPointer`." +msgstr "在 CPython 中，它等價於 :c:func:`Py_HashPointer`。" diff --git a/c-api/import.po b/c-api/import.po index fa6dd95b73..d518df077b 100644 --- a/c-api/import.po +++ b/c-api/import.po @@ -1,558 +1,558 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Ching-Lung Chuang, 2015 -# Matt Wang , 2025 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-25 00:13+0000\n" -"PO-Revision-Date: 2025-11-11 14:06+0000\n" -"Last-Translator: mattwang44@gmail.com\n" -"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" -"tw)\n" -"Language: zh_TW\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=UTF-8\n" -"Content-Transfer-Encoding: 8bit\n" -"Plural-Forms: nplurals=1; plural=0;\n" - -#: ../../c-api/import.rst:6 -msgid "Importing Modules" -msgstr "引入模組" - -#: ../../c-api/import.rst:16 -msgid "" -"This is a wrapper around :c:func:`PyImport_Import()` which takes a :c:expr:" -"`const char *` as an argument instead of a :c:expr:`PyObject *`." -msgstr "" -"這是 :c:func:`PyImport_Import()` 的包裝器 (wrapper)，它使用 :c:expr:`const " -"char *` 作為引數，而不是 :c:expr:`PyObject *`。" - -#: ../../c-api/import.rst:21 -msgid "This function is a deprecated alias of :c:func:`PyImport_ImportModule`." -msgstr "這個函式是 :c:func:`PyImport_ImportModule` 的已棄用別名。" - -#: ../../c-api/import.rst:23 -msgid "" -"This function used to fail immediately when the import lock was held by " -"another thread. In Python 3.3 though, the locking scheme switched to per-" -"module locks for most purposes, so this function's special behaviour isn't " -"needed anymore." -msgstr "" -"當引入鎖被其他執行緒持有時，這個函式過去會立即失敗。但在 Python 3.3 中，鎖機" -"制轉換成針對每個模組的鎖 (per-module lock) 來達到大多數目的，所以這個函式的特" -"殊行為就不再需要了。" - -#: ../../c-api/import.rst:29 -msgid "Use :c:func:`PyImport_ImportModule` instead." -msgstr "請改用 :c:func:`PyImport_ImportModule`。" - -#: ../../c-api/import.rst:37 -msgid "" -"Import a module. This is best described by referring to the built-in Python " -"function :func:`__import__`." -msgstr "" -"引入一個模組。這最好透過參考 Python 內建函式 :func:`__import__` 來說明。" - -#: ../../c-api/import.rst:40 ../../c-api/import.rst:56 -msgid "" -"The return value is a new reference to the imported module or top-level " -"package, or ``NULL`` with an exception set on failure. Like for :func:" -"`__import__`, the return value when a submodule of a package was requested " -"is normally the top-level package, unless a non-empty *fromlist* was given." -msgstr "" -"回傳值是對引入的模組或頂層套件的新參照，或者是 ``NULL``，失敗時會設定例外。就" -"像 :func:`__import__` 一樣，當要求一個套件的子模組時，回傳值通常是頂層套件，" -"除非給定一個非空的 *fromlist*。" - -#: ../../c-api/import.rst:46 -msgid "" -"Failing imports remove incomplete module objects, like with :c:func:" -"`PyImport_ImportModule`." -msgstr "" -"失敗的引入會移除不完整的模組物件，就像 :c:func:`PyImport_ImportModule` 一樣。" - -#: ../../c-api/import.rst:52 -msgid "" -"Import a module. This is best described by referring to the built-in Python " -"function :func:`__import__`, as the standard :func:`__import__` function " -"calls this function directly." -msgstr "" -"引入一個模組。這最好透過參考內建的 Python 函式 :func:`__import__` 來說明，因" -"為標準的 :func:`__import__` 函式會直接呼叫這個函式。" - -#: ../../c-api/import.rst:66 -msgid "" -"Similar to :c:func:`PyImport_ImportModuleLevelObject`, but the name is a " -"UTF-8 encoded string instead of a Unicode object." -msgstr "" -"類似於 :c:func:`PyImport_ImportModuleLevelObject`，但名稱是 UTF-8 編碼字串，" -"而不是 Unicode 物件。" - -#: ../../c-api/import.rst:69 -msgid "Negative values for *level* are no longer accepted." -msgstr "不再接受負的 *level* 值。" - -#: ../../c-api/import.rst:74 -msgid "" -"This is a higher-level interface that calls the current \"import hook " -"function\" (with an explicit *level* of 0, meaning absolute import). It " -"invokes the :func:`__import__` function from the ``__builtins__`` of the " -"current globals. This means that the import is done using whatever import " -"hooks are installed in the current environment." -msgstr "" -"這是一個較高階的介面，用來呼叫目前的「引入掛勾函式 (import hook function)」" -"（明確的 *level* 為 0，表示絕對引入 (absolute import)）。它從目前全域變數的 " -"``__builtins__`` 中呼叫 :func:`__import__` 函式。這表示引入是使用目前環境所安" -"裝的引入掛勾來完成的。" - -#: ../../c-api/import.rst:80 -msgid "This function always uses absolute imports." -msgstr "此函式總是使用絕對引入。" - -#: ../../c-api/import.rst:85 -msgid "" -"Reload a module. Return a new reference to the reloaded module, or ``NULL`` " -"with an exception set on failure (the module still exists in this case)." -msgstr "" -"重新載入一個模組。回傳重新載入模組的新參照，或在失敗時回傳 ``NULL`` 並設定例" -"外（在這種情況下模組仍然存在）。" - -#: ../../c-api/import.rst:91 -msgid "Return the module object corresponding to a module name." -msgstr "回傳與模組名稱對應的模組物件。" - -#: ../../c-api/import.rst:93 -msgid "" -"The *name* argument may be of the form ``package.module``. First check the " -"modules dictionary if there's one there, and if not, create a new one and " -"insert it in the modules dictionary." -msgstr "" -"*name* 引數的形式可以是 ``package.module``。首先檢查模組字典中是否有，如果沒" -"有，則建立新的模組並插入模組字典中。" - -#: ../../c-api/import.rst:97 -msgid "" -"Return a :term:`strong reference` to the module on success. Return ``NULL`` " -"with an exception set on failure." -msgstr "" -"成功時回傳模組的\\ :term:`強參照 `。失敗時回傳 ``NULL`` 並" -"設定例外。" - -#: ../../c-api/import.rst:100 -msgid "The module name *name* is decoded from UTF-8." -msgstr "模組名稱 *name* 是以 UTF-8 解碼。" - -#: ../../c-api/import.rst:102 -msgid "" -"This function does not load or import the module; if the module wasn't " -"already loaded, you will get an empty module object. Use :c:func:" -"`PyImport_ImportModule` or one of its variants to import a module. Package " -"structures implied by a dotted name for *name* are not created if not " -"already present." -msgstr "" -"這個函式不會載入或引入模組；如果模組尚未載入，你將會得到一個空的模組物件。使" -"用 :c:func:`PyImport_ImportModule` 或其變體來引入一個模組。如果尚未存在，則不" -"會建立由 *name* 的點名稱 (dotted name) 所隱含的套件結構。" - -#: ../../c-api/import.rst:113 -msgid "" -"Similar to :c:func:`PyImport_AddModuleRef`, but return a :term:`borrowed " -"reference` and *name* is a Python :class:`str` object." -msgstr "" -"類似於 :c:func:`PyImport_AddModuleRef`，但是會回傳一個\\ :term:`借用參照 " -"`\\ 且 *name* 為 Python 的 :class:`str` 物件。" - -#: ../../c-api/import.rst:121 -msgid "" -"Similar to :c:func:`PyImport_AddModuleRef`, but return a :term:`borrowed " -"reference`." -msgstr "" -"類似於 :c:func:`PyImport_AddModuleRef`，但是會回傳一個\\ :term:`借用參照 " -"`。" - -#: ../../c-api/import.rst:129 -msgid "" -"Given a module name (possibly of the form ``package.module``) and a code " -"object read from a Python bytecode file or obtained from the built-in " -"function :func:`compile`, load the module. Return a new reference to the " -"module object, or ``NULL`` with an exception set if an error occurred. " -"*name* is removed from :data:`sys.modules` in error cases, even if *name* " -"was already in :data:`sys.modules` on entry to :c:func:" -"`PyImport_ExecCodeModule`. Leaving incompletely initialized modules in :" -"data:`sys.modules` is dangerous, as imports of such modules have no way to " -"know that the module object is an unknown (and probably damaged with respect " -"to the module author's intents) state." -msgstr "" -"給定一個模組名稱（可能為 ``package.module`` 的形式），以及一個從 Python 位元" -"組碼檔讀取或從內建函式 :func:`compile` 取得的程式碼物件，載入模組。回傳模組物" -"件的新參照，如果發生錯誤，則回傳 ``NULL`` 並設定例外。在出錯的情況下，*name* " -"會從 :data:`sys.modules` 中移除，即使 *name* 在進入 :c:func:" -"`PyImport_ExecCodeModule` 時已經在 :data:`sys.modules` 中。在 :data:`sys." -"modules` 中留下未完全初始化的模組是很危險的，因為這種模組的引入無法知道模組物" -"件處於未知狀態（且相對於模組作者的意圖，很可能已經損壞）。" - -#: ../../c-api/import.rst:139 -msgid "" -"The module's :attr:`~module.__spec__` and :attr:`~module.__loader__` will be " -"set, if not set already, with the appropriate values. The spec's loader " -"will be set to the module's :attr:`!__loader__` (if set) and to an instance " -"of :class:`~importlib.machinery.SourceFileLoader` otherwise." -msgstr "" -"如果尚未設定，模組的 :attr:`~module.__spec__` 和 :attr:`~module.__loader__` " -"將會被設定為適當的值。規格的載入器將被設定為模組的 :attr:`!__loader__`\\ （如" -"果有設定），否則將被設定為 :class:`~importlib.machinery.SourceFileLoader` 的" -"實例。" - -#: ../../c-api/import.rst:144 -msgid "" -"The module's :attr:`~module.__file__` attribute will be set to the code " -"object's :attr:`~codeobject.co_filename`. If applicable, :attr:`~module." -"__cached__` will also be set." -msgstr "" -"模組的 :attr:`~module.__file__` 屬性將會設定為程式碼物件的 :attr:" -"`~codeobject.co_filename`。如果適用，:attr:`~module.__cached__` 也會被設定。" - -#: ../../c-api/import.rst:148 -msgid "" -"This function will reload the module if it was already imported. See :c:" -"func:`PyImport_ReloadModule` for the intended way to reload a module." -msgstr "" -"如果模組已經被引入，這個函式會重新載入模組。請參閱 :c:func:" -"`PyImport_ReloadModule` 以取得重新載入模組的預期方法。" - -#: ../../c-api/import.rst:151 -msgid "" -"If *name* points to a dotted name of the form ``package.module``, any " -"package structures not already created will still not be created." -msgstr "" -"如果 *name* 指向形式為 ``package.module`` 的點名稱，則任何尚未建立的套件結構" -"仍不會被建立。" - -#: ../../c-api/import.rst:154 -msgid "" -"See also :c:func:`PyImport_ExecCodeModuleEx` and :c:func:" -"`PyImport_ExecCodeModuleWithPathnames`." -msgstr "" -"另請參閱 :c:func:`PyImport_ExecCodeModuleEx` 及 :c:func:" -"`PyImport_ExecCodeModuleWithPathnames`。" - -#: ../../c-api/import.rst:157 -msgid "" -"The setting of :attr:`~module.__cached__` and :attr:`~module.__loader__` is " -"deprecated. See :class:`~importlib.machinery.ModuleSpec` for alternatives." -msgstr "" -":attr:`~module.__cached__` 和 :attr:`~module.__loader__` 的設定已被棄用。請參" -"閱 :class:`~importlib.machinery.ModuleSpec` 以取得替代方案。" - -#: ../../c-api/import.rst:165 -msgid "" -"Like :c:func:`PyImport_ExecCodeModule`, but the :attr:`~module.__file__` " -"attribute of the module object is set to *pathname* if it is non-``NULL``." -msgstr "" -"類似於 :c:func:`PyImport_ExecCodeModule`，但是如果 *pathname* 不是 ``NULL``，" -"模組物件的 :attr:`~module.__file__` 屬性會被設定為 *pathname*。" - -#: ../../c-api/import.rst:168 -msgid "See also :c:func:`PyImport_ExecCodeModuleWithPathnames`." -msgstr "另請參閱 :c:func:`PyImport_ExecCodeModuleWithPathnames`。" - -#: ../../c-api/import.rst:173 -msgid "" -"Like :c:func:`PyImport_ExecCodeModuleEx`, but the :attr:`~module.__cached__` " -"attribute of the module object is set to *cpathname* if it is non-``NULL``. " -"Of the three functions, this is the preferred one to use." -msgstr "" -"類似於 :c:func:`PyImport_ExecCodeModuleEx`，但是如果 *cpathname* 不是 " -"``NULL``，模組物件的 :attr:`~module.__cached__` 屬性會被設定為 *cpathname*。" -"在這三個函式中，這是首選的函式。" - -#: ../../c-api/import.rst:179 -msgid "" -"Setting :attr:`~module.__cached__` is deprecated. See :class:`~importlib." -"machinery.ModuleSpec` for alternatives." -msgstr "" -"設定 :attr:`~module.__cached__` 已被棄用。請參閱 :class:`~importlib." -"machinery.ModuleSpec` 以取得替代方案。" - -#: ../../c-api/import.rst:186 -msgid "" -"Like :c:func:`PyImport_ExecCodeModuleObject`, but *name*, *pathname* and " -"*cpathname* are UTF-8 encoded strings. Attempts are also made to figure out " -"what the value for *pathname* should be from *cpathname* if the former is " -"set to ``NULL``." -msgstr "" -"類似於 :c:func:`PyImport_ExecCodeModuleObject`，但是 *name*、*pathname* 和 " -"*cpathname* 是 UTF-8 編碼的字串。如果 *pathname* 被設定為 ``NULL``，也會嘗試" -"從 *cpathname* 中找出 *pathname* 的值應該是什麼。" - -#: ../../c-api/import.rst:192 -msgid "" -"Uses :func:`!imp.source_from_cache` in calculating the source path if only " -"the bytecode path is provided." -msgstr "" -"如果只提供了位元組碼路徑，則在計算原始碼路徑時使用 :func:`!imp." -"source_from_cache`。" - -#: ../../c-api/import.rst:195 -msgid "No longer uses the removed :mod:`!imp` module." -msgstr "不再使用已被移除的 :mod:`!imp` 模組。" - -#: ../../c-api/import.rst:201 -msgid "" -"Return the magic number for Python bytecode files (a.k.a. :file:`.pyc` " -"file). The magic number should be present in the first four bytes of the " -"bytecode file, in little-endian byte order. Returns ``-1`` on error." -msgstr "" -"回傳 Python 位元組碼檔案（也稱為 :file:`.pyc` 檔案）的魔術數字（magic " -"number）。魔術數字應該出現在位元組碼檔案的前四個位元組，以小端序（little-" -"endian）位元組順序排列。錯誤時會回傳 ``-1``。" - -#: ../../c-api/import.rst:205 -msgid "Return value of ``-1`` upon failure." -msgstr "當失敗時回傳 ``-1``。" - -#: ../../c-api/import.rst:211 -msgid "" -"Return the magic tag string for :pep:`3147` format Python bytecode file " -"names. Keep in mind that the value at ``sys.implementation.cache_tag`` is " -"authoritative and should be used instead of this function." -msgstr "" -"回傳 :pep:`3147` 格式 Python 位元組碼檔名的魔術標籤字串。請記住，``sys." -"implementation.cache_tag`` 的值是權威的，應該使用它來取代這個函式。" - -#: ../../c-api/import.rst:219 -msgid "" -"Return the dictionary used for the module administration (a.k.a. ``sys." -"modules``). Note that this is a per-interpreter variable." -msgstr "" -"回傳用於模組管理的字典（也稱為 ``sys.modules``）。請注意，這是一個針對每個直" -"譯器的變數 (per-interpreter variable)。" - -#: ../../c-api/import.rst:224 -msgid "" -"Return the already imported module with the given name. If the module has " -"not been imported yet then returns ``NULL`` but does not set an error. " -"Returns ``NULL`` and sets an error if the lookup failed." -msgstr "" -"回傳已以給定名稱引入的模組。如果模組尚未引入，則會回傳 ``NULL`` 但不會設定錯" -"誤。如果查找失敗，則回傳 ``NULL`` 並設定錯誤。" - -#: ../../c-api/import.rst:232 -msgid "" -"Return a finder object for a :data:`sys.path`/:attr:`!pkg.__path__` item " -"*path*, possibly by fetching it from the :data:`sys.path_importer_cache` " -"dict. If it wasn't yet cached, traverse :data:`sys.path_hooks` until a hook " -"is found that can handle the path item. Return ``None`` if no hook could; " -"this tells our caller that the :term:`path based finder` could not find a " -"finder for this path item. Cache the result in :data:`sys." -"path_importer_cache`. Return a new reference to the finder object." -msgstr "" -"回傳 :data:`sys.path`/:attr:`!pkg.__path__` 項 *path* 的查找器物件 (finder " -"object)，可能的方式是從 :data:`sys.path_importer_cache` 字典取得。如果它還沒" -"有被快取，就遍歷 :data:`sys.path_hooks` 直到找到可以處理路徑項的掛勾。如果沒" -"有掛勾可以處理，則回傳 ``None``；這會告訴我們的呼叫者 :term:`path based " -"finder` 找不到這個路徑項的查找器。將結果快取到 :data:`sys." -"path_importer_cache`。回傳查找器物件的新參照。" - -#: ../../c-api/import.rst:243 -msgid "" -"Load a frozen module named *name*. Return ``1`` for success, ``0`` if the " -"module is not found, and ``-1`` with an exception set if the initialization " -"failed. To access the imported module on a successful load, use :c:func:" -"`PyImport_ImportModule`. (Note the misnomer --- this function would reload " -"the module if it was already imported.)" -msgstr "" -"載入一個名為 *name* 的凍結模組。成功則回傳 ``1``，找不到模組則回傳 ``0``，初" -"始化失敗則回傳 ``-1`` 並設定例外。要在成功載入時存取引入的模組，請使用 :c:" -"func:`PyImport_ImportModule`。（請注意這個名稱並不恰當 --- 如果模組已經被引" -"入，這個函式會重新載入模組）。" - -#: ../../c-api/import.rst:251 -msgid "The ``__file__`` attribute is no longer set on the module." -msgstr "不會再於模組設定 ``__file__`` 屬性。" - -#: ../../c-api/import.rst:257 -msgid "" -"Similar to :c:func:`PyImport_ImportFrozenModuleObject`, but the name is a " -"UTF-8 encoded string instead of a Unicode object." -msgstr "" -"類似於 :c:func:`PyImport_ImportFrozenModuleObject`，但名稱是 UTF-8 編碼字串，" -"而不是 Unicode 物件。" - -#: ../../c-api/import.rst:265 -msgid "" -"This is the structure type definition for frozen module descriptors, as " -"generated by the :program:`freeze` utility (see :file:`Tools/freeze/` in the " -"Python source distribution). Its definition, found in :file:`Include/import." -"h`, is::" -msgstr "" -"這是由 :program:`freeze` 工具程式產生的凍結模組描述器的結構型別定義（請參閱 " -"Python 原始碼發行版中的 :file:`Tools/freeze/`）。它的定義在 :file:`Include/" -"import.h` 中，為： ::" - -#: ../../c-api/import.rst:270 -msgid "" -"struct _frozen {\n" -" const char *name;\n" -" const unsigned char *code;\n" -" int size;\n" -" bool is_package;\n" -"};" -msgstr "" -"struct _frozen {\n" -" const char *name;\n" -" const unsigned char *code;\n" -" int size;\n" -" bool is_package;\n" -"};" - -#: ../../c-api/import.rst:277 -msgid "" -"The new ``is_package`` field indicates whether the module is a package or " -"not. This replaces setting the ``size`` field to a negative value." -msgstr "" -"新的 ``is_package`` 欄位指出模組是否為套件。這取代了將 ``size`` 欄位設定為負" -"值的方式。" - -#: ../../c-api/import.rst:283 -msgid "" -"This pointer is initialized to point to an array of :c:struct:`_frozen` " -"records, terminated by one whose members are all ``NULL`` or zero. When a " -"frozen module is imported, it is searched in this table. Third-party code " -"could play tricks with this to provide a dynamically created collection of " -"frozen modules." -msgstr "" -"這個指標會被初始化為指向一個 :c:struct:`_frozen` 記錄的陣列，以一個其成員都" -"是 ``NULL`` 或 0 的記錄為結尾。當一個凍結的模組被引入時，它會在這個表格中被搜" -"尋。第三方程式碼可以利用這一點來提供一個動態建立的凍結模組集合。" - -#: ../../c-api/import.rst:291 -msgid "" -"Add a single module to the existing table of built-in modules. This is a " -"convenience wrapper around :c:func:`PyImport_ExtendInittab`, returning " -"``-1`` if the table could not be extended. The new module can be imported " -"by the name *name*, and uses the function *initfunc* as the initialization " -"function called on the first attempted import. This should be called " -"before :c:func:`Py_Initialize`." -msgstr "" -"新增單一模組到現有的內建模組表格。這是 :c:func:`PyImport_ExtendInittab` 的便" -"利包裝器，如果表格無法擴充會回傳 ``-1``。新的模組可以用 *name* 的名稱引入，並" -"使用函式 *initfunc* 作為第一次嘗試引入時呼叫的初始化函式。這應該在 :c:func:" -"`Py_Initialize` 之前呼叫。" - -#: ../../c-api/import.rst:301 -msgid "" -"Structure describing a single entry in the list of built-in modules. " -"Programs which embed Python may use an array of these structures in " -"conjunction with :c:func:`PyImport_ExtendInittab` to provide additional " -"built-in modules. The structure consists of two members:" -msgstr "" -"描述內建模組列表中單一項目的結構。嵌入 Python 的程式可以使用這些結構的陣列" -"與 :c:func:`PyImport_ExtendInittab` 結合來提供額外的內建模組。這個結構包含兩" -"個成員：" - -#: ../../c-api/import.rst:309 -msgid "The module name, as an ASCII encoded string." -msgstr "模組名稱，為 ASCII 編碼的字串。" - -#: ../../c-api/import.rst:313 -msgid "Initialization function for a module built into the interpreter." -msgstr "內建於直譯器中的模組的初始化函式。" - -#: ../../c-api/import.rst:318 -msgid "" -"Add a collection of modules to the table of built-in modules. The *newtab* " -"array must end with a sentinel entry which contains ``NULL`` for the :c:" -"member:`~_inittab.name` field; failure to provide the sentinel value can " -"result in a memory fault. Returns ``0`` on success or ``-1`` if insufficient " -"memory could be allocated to extend the internal table. In the event of " -"failure, no modules are added to the internal table. This must be called " -"before :c:func:`Py_Initialize`." -msgstr "" -"新增一個模組集合到內建模組表格。*newtab* 陣列必須以包含 ``NULL`` 的 :c:" -"member:`~_inittab.name` 欄位的哨兵項目（sentinel entry）結尾；如果沒有提供哨" -"兵值，可能會導致記憶體錯誤。成功時會回傳 ``0``，如果沒有足夠的記憶體可以分配" -"來擴充內部表格則回傳 ``-1``。在失敗的情況下，沒有模組會被加入內部表格。這個函" -"式必須在 :c:func:`Py_Initialize` 之前呼叫。" - -#: ../../c-api/import.rst:325 -msgid "" -"If Python is initialized multiple times, :c:func:`PyImport_AppendInittab` " -"or :c:func:`PyImport_ExtendInittab` must be called before each Python " -"initialization." -msgstr "" -"如果 Python 被多次初始化，:c:func:`PyImport_AppendInittab` 或 :c:func:" -"`PyImport_ExtendInittab` 必須在每次 Python 初始化之前被呼叫。" - -#: ../../c-api/import.rst:332 -msgid "" -"The table of built-in modules used by Python initialization. Do not use this " -"directly; use :c:func:`PyImport_AppendInittab` and :c:func:" -"`PyImport_ExtendInittab` instead." -msgstr "" -"Python 初始化所使用的內建模組表格。請勿直接使用它，" -"請改用 :c:func:`PyImport_AppendInittab` 與 :c:func:" -"`PyImport_ExtendInittab`。" - -#: ../../c-api/import.rst:339 -msgid "Import the module *mod_name* and get its attribute *attr_name*." -msgstr "引入模組 *mod_name* 並取得其屬性 *attr_name*。" - -#: ../../c-api/import.rst:341 -msgid "Names must be Python :class:`str` objects." -msgstr "名稱必須是 Python :class:`str` 物件。" - -#: ../../c-api/import.rst:343 -msgid "" -"Helper function combining :c:func:`PyImport_Import` and :c:func:" -"`PyObject_GetAttr`. For example, it can raise :exc:`ImportError` if the " -"module is not found, and :exc:`AttributeError` if the attribute doesn't " -"exist." -msgstr "" -"結合 :c:func:`PyImport_Import` 和 :c:func:`PyObject_GetAttr` 的輔助函式。例" -"如，如果找不到模組，它會引發 :exc:`ImportError`，如果屬性不存在，則會引發 :" -"exc:`AttributeError`。" - -#: ../../c-api/import.rst:352 -msgid "" -"Similar to :c:func:`PyImport_ImportModuleAttr`, but names are UTF-8 encoded " -"strings instead of Python :class:`str` objects." -msgstr "" -"類似於 :c:func:`PyImport_ImportModuleAttr`，但名稱是 UTF-8 編碼字串，而不是 " -"Python :class:`str` 物件。" - -#: ../../c-api/import.rst:11 -msgid "package variable" -msgstr "package variable（套件變數）" - -#: ../../c-api/import.rst:11 -msgid "__all__" -msgstr "__all__" - -#: ../../c-api/import.rst:11 -msgid "__all__ (package variable)" -msgstr "__all__（套件變數）" - -#: ../../c-api/import.rst:11 -msgid "modules (in module sys)" -msgstr "modules（sys 模組中）" - -#: ../../c-api/import.rst:35 ../../c-api/import.rst:127 -msgid "built-in function" -msgstr "built-in function（內建函式）" - -#: ../../c-api/import.rst:35 -msgid "__import__" -msgstr "__import__" - -#: ../../c-api/import.rst:127 -msgid "compile" -msgstr "compile（編譯）" - -#: ../../c-api/import.rst:263 -msgid "freeze utility" -msgstr "freeze utility（凍結工具程式）" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Ching-Lung Chuang, 2015 +# Matt Wang , 2025 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-25 00:13+0000\n" +"PO-Revision-Date: 2025-11-11 14:06+0000\n" +"Last-Translator: mattwang44@gmail.com\n" +"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" +"tw)\n" +"Language: zh_TW\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=1; plural=0;\n" + +#: ../../c-api/import.rst:6 +msgid "Importing Modules" +msgstr "引入模組" + +#: ../../c-api/import.rst:16 +msgid "" +"This is a wrapper around :c:func:`PyImport_Import()` which takes a :c:expr:" +"`const char *` as an argument instead of a :c:expr:`PyObject *`." +msgstr "" +"這是 :c:func:`PyImport_Import()` 的包裝器 (wrapper)，它使用 :c:expr:`const " +"char *` 作為引數，而不是 :c:expr:`PyObject *`。" + +#: ../../c-api/import.rst:21 +msgid "This function is a deprecated alias of :c:func:`PyImport_ImportModule`." +msgstr "這個函式是 :c:func:`PyImport_ImportModule` 的已棄用別名。" + +#: ../../c-api/import.rst:23 +msgid "" +"This function used to fail immediately when the import lock was held by " +"another thread. In Python 3.3 though, the locking scheme switched to per-" +"module locks for most purposes, so this function's special behaviour isn't " +"needed anymore." +msgstr "" +"當引入鎖被其他執行緒持有時，這個函式過去會立即失敗。但在 Python 3.3 中，鎖機" +"制轉換成針對每個模組的鎖 (per-module lock) 來達到大多數目的，所以這個函式的特" +"殊行為就不再需要了。" + +#: ../../c-api/import.rst:29 +msgid "Use :c:func:`PyImport_ImportModule` instead." +msgstr "請改用 :c:func:`PyImport_ImportModule`。" + +#: ../../c-api/import.rst:37 +msgid "" +"Import a module. This is best described by referring to the built-in Python " +"function :func:`__import__`." +msgstr "" +"引入一個模組。這最好透過參考 Python 內建函式 :func:`__import__` 來說明。" + +#: ../../c-api/import.rst:40 ../../c-api/import.rst:56 +msgid "" +"The return value is a new reference to the imported module or top-level " +"package, or ``NULL`` with an exception set on failure. Like for :func:" +"`__import__`, the return value when a submodule of a package was requested " +"is normally the top-level package, unless a non-empty *fromlist* was given." +msgstr "" +"回傳值是對引入的模組或頂層套件的新參照，或者是 ``NULL``，失敗時會設定例外。就" +"像 :func:`__import__` 一樣，當要求一個套件的子模組時，回傳值通常是頂層套件，" +"除非給定一個非空的 *fromlist*。" + +#: ../../c-api/import.rst:46 +msgid "" +"Failing imports remove incomplete module objects, like with :c:func:" +"`PyImport_ImportModule`." +msgstr "" +"失敗的引入會移除不完整的模組物件，就像 :c:func:`PyImport_ImportModule` 一樣。" + +#: ../../c-api/import.rst:52 +msgid "" +"Import a module. This is best described by referring to the built-in Python " +"function :func:`__import__`, as the standard :func:`__import__` function " +"calls this function directly." +msgstr "" +"引入一個模組。這最好透過參考內建的 Python 函式 :func:`__import__` 來說明，因" +"為標準的 :func:`__import__` 函式會直接呼叫這個函式。" + +#: ../../c-api/import.rst:66 +msgid "" +"Similar to :c:func:`PyImport_ImportModuleLevelObject`, but the name is a " +"UTF-8 encoded string instead of a Unicode object." +msgstr "" +"類似於 :c:func:`PyImport_ImportModuleLevelObject`，但名稱是 UTF-8 編碼字串，" +"而不是 Unicode 物件。" + +#: ../../c-api/import.rst:69 +msgid "Negative values for *level* are no longer accepted." +msgstr "不再接受負的 *level* 值。" + +#: ../../c-api/import.rst:74 +msgid "" +"This is a higher-level interface that calls the current \"import hook " +"function\" (with an explicit *level* of 0, meaning absolute import). It " +"invokes the :func:`__import__` function from the ``__builtins__`` of the " +"current globals. This means that the import is done using whatever import " +"hooks are installed in the current environment." +msgstr "" +"這是一個較高階的介面，用來呼叫目前的「引入掛勾函式 (import hook function)」" +"（明確的 *level* 為 0，表示絕對引入 (absolute import)）。它從目前全域變數的 " +"``__builtins__`` 中呼叫 :func:`__import__` 函式。這表示引入是使用目前環境所安" +"裝的引入掛勾來完成的。" + +#: ../../c-api/import.rst:80 +msgid "This function always uses absolute imports." +msgstr "此函式總是使用絕對引入。" + +#: ../../c-api/import.rst:85 +msgid "" +"Reload a module. Return a new reference to the reloaded module, or ``NULL`` " +"with an exception set on failure (the module still exists in this case)." +msgstr "" +"重新載入一個模組。回傳重新載入模組的新參照，或在失敗時回傳 ``NULL`` 並設定例" +"外（在這種情況下模組仍然存在）。" + +#: ../../c-api/import.rst:91 +msgid "Return the module object corresponding to a module name." +msgstr "回傳與模組名稱對應的模組物件。" + +#: ../../c-api/import.rst:93 +msgid "" +"The *name* argument may be of the form ``package.module``. First check the " +"modules dictionary if there's one there, and if not, create a new one and " +"insert it in the modules dictionary." +msgstr "" +"*name* 引數的形式可以是 ``package.module``。首先檢查模組字典中是否有，如果沒" +"有，則建立新的模組並插入模組字典中。" + +#: ../../c-api/import.rst:97 +msgid "" +"Return a :term:`strong reference` to the module on success. Return ``NULL`` " +"with an exception set on failure." +msgstr "" +"成功時回傳模組的\\ :term:`強參照 `。失敗時回傳 ``NULL`` 並" +"設定例外。" + +#: ../../c-api/import.rst:100 +msgid "The module name *name* is decoded from UTF-8." +msgstr "模組名稱 *name* 是以 UTF-8 解碼。" + +#: ../../c-api/import.rst:102 +msgid "" +"This function does not load or import the module; if the module wasn't " +"already loaded, you will get an empty module object. Use :c:func:" +"`PyImport_ImportModule` or one of its variants to import a module. Package " +"structures implied by a dotted name for *name* are not created if not " +"already present." +msgstr "" +"這個函式不會載入或引入模組；如果模組尚未載入，你將會得到一個空的模組物件。使" +"用 :c:func:`PyImport_ImportModule` 或其變體來引入一個模組。如果尚未存在，則不" +"會建立由 *name* 的點名稱 (dotted name) 所隱含的套件結構。" + +#: ../../c-api/import.rst:113 +msgid "" +"Similar to :c:func:`PyImport_AddModuleRef`, but return a :term:`borrowed " +"reference` and *name* is a Python :class:`str` object." +msgstr "" +"類似於 :c:func:`PyImport_AddModuleRef`，但是會回傳一個\\ :term:`借用參照 " +"`\\ 且 *name* 為 Python 的 :class:`str` 物件。" + +#: ../../c-api/import.rst:121 +msgid "" +"Similar to :c:func:`PyImport_AddModuleRef`, but return a :term:`borrowed " +"reference`." +msgstr "" +"類似於 :c:func:`PyImport_AddModuleRef`，但是會回傳一個\\ :term:`借用參照 " +"`。" + +#: ../../c-api/import.rst:129 +msgid "" +"Given a module name (possibly of the form ``package.module``) and a code " +"object read from a Python bytecode file or obtained from the built-in " +"function :func:`compile`, load the module. Return a new reference to the " +"module object, or ``NULL`` with an exception set if an error occurred. " +"*name* is removed from :data:`sys.modules` in error cases, even if *name* " +"was already in :data:`sys.modules` on entry to :c:func:" +"`PyImport_ExecCodeModule`. Leaving incompletely initialized modules in :" +"data:`sys.modules` is dangerous, as imports of such modules have no way to " +"know that the module object is an unknown (and probably damaged with respect " +"to the module author's intents) state." +msgstr "" +"給定一個模組名稱（可能為 ``package.module`` 的形式），以及一個從 Python 位元" +"組碼檔讀取或從內建函式 :func:`compile` 取得的程式碼物件，載入模組。回傳模組物" +"件的新參照，如果發生錯誤，則回傳 ``NULL`` 並設定例外。在出錯的情況下，*name* " +"會從 :data:`sys.modules` 中移除，即使 *name* 在進入 :c:func:" +"`PyImport_ExecCodeModule` 時已經在 :data:`sys.modules` 中。在 :data:`sys." +"modules` 中留下未完全初始化的模組是很危險的，因為這種模組的引入無法知道模組物" +"件處於未知狀態（且相對於模組作者的意圖，很可能已經損壞）。" + +#: ../../c-api/import.rst:139 +msgid "" +"The module's :attr:`~module.__spec__` and :attr:`~module.__loader__` will be " +"set, if not set already, with the appropriate values. The spec's loader " +"will be set to the module's :attr:`!__loader__` (if set) and to an instance " +"of :class:`~importlib.machinery.SourceFileLoader` otherwise." +msgstr "" +"如果尚未設定，模組的 :attr:`~module.__spec__` 和 :attr:`~module.__loader__` " +"將會被設定為適當的值。規格的載入器將被設定為模組的 :attr:`!__loader__`\\ （如" +"果有設定），否則將被設定為 :class:`~importlib.machinery.SourceFileLoader` 的" +"實例。" + +#: ../../c-api/import.rst:144 +msgid "" +"The module's :attr:`~module.__file__` attribute will be set to the code " +"object's :attr:`~codeobject.co_filename`. If applicable, :attr:`~module." +"__cached__` will also be set." +msgstr "" +"模組的 :attr:`~module.__file__` 屬性將會設定為程式碼物件的 :attr:" +"`~codeobject.co_filename`。如果適用，:attr:`~module.__cached__` 也會被設定。" + +#: ../../c-api/import.rst:148 +msgid "" +"This function will reload the module if it was already imported. See :c:" +"func:`PyImport_ReloadModule` for the intended way to reload a module." +msgstr "" +"如果模組已經被引入，這個函式會重新載入模組。請參閱 :c:func:" +"`PyImport_ReloadModule` 以取得重新載入模組的預期方法。" + +#: ../../c-api/import.rst:151 +msgid "" +"If *name* points to a dotted name of the form ``package.module``, any " +"package structures not already created will still not be created." +msgstr "" +"如果 *name* 指向形式為 ``package.module`` 的點名稱，則任何尚未建立的套件結構" +"仍不會被建立。" + +#: ../../c-api/import.rst:154 +msgid "" +"See also :c:func:`PyImport_ExecCodeModuleEx` and :c:func:" +"`PyImport_ExecCodeModuleWithPathnames`." +msgstr "" +"另請參閱 :c:func:`PyImport_ExecCodeModuleEx` 及 :c:func:" +"`PyImport_ExecCodeModuleWithPathnames`。" + +#: ../../c-api/import.rst:157 +msgid "" +"The setting of :attr:`~module.__cached__` and :attr:`~module.__loader__` is " +"deprecated. See :class:`~importlib.machinery.ModuleSpec` for alternatives." +msgstr "" +":attr:`~module.__cached__` 和 :attr:`~module.__loader__` 的設定已被棄用。請參" +"閱 :class:`~importlib.machinery.ModuleSpec` 以取得替代方案。" + +#: ../../c-api/import.rst:165 +msgid "" +"Like :c:func:`PyImport_ExecCodeModule`, but the :attr:`~module.__file__` " +"attribute of the module object is set to *pathname* if it is non-``NULL``." +msgstr "" +"類似於 :c:func:`PyImport_ExecCodeModule`，但是如果 *pathname* 不是 ``NULL``，" +"模組物件的 :attr:`~module.__file__` 屬性會被設定為 *pathname*。" + +#: ../../c-api/import.rst:168 +msgid "See also :c:func:`PyImport_ExecCodeModuleWithPathnames`." +msgstr "另請參閱 :c:func:`PyImport_ExecCodeModuleWithPathnames`。" + +#: ../../c-api/import.rst:173 +msgid "" +"Like :c:func:`PyImport_ExecCodeModuleEx`, but the :attr:`~module.__cached__` " +"attribute of the module object is set to *cpathname* if it is non-``NULL``. " +"Of the three functions, this is the preferred one to use." +msgstr "" +"類似於 :c:func:`PyImport_ExecCodeModuleEx`，但是如果 *cpathname* 不是 " +"``NULL``，模組物件的 :attr:`~module.__cached__` 屬性會被設定為 *cpathname*。" +"在這三個函式中，這是首選的函式。" + +#: ../../c-api/import.rst:179 +msgid "" +"Setting :attr:`~module.__cached__` is deprecated. See :class:`~importlib." +"machinery.ModuleSpec` for alternatives." +msgstr "" +"設定 :attr:`~module.__cached__` 已被棄用。請參閱 :class:`~importlib." +"machinery.ModuleSpec` 以取得替代方案。" + +#: ../../c-api/import.rst:186 +msgid "" +"Like :c:func:`PyImport_ExecCodeModuleObject`, but *name*, *pathname* and " +"*cpathname* are UTF-8 encoded strings. Attempts are also made to figure out " +"what the value for *pathname* should be from *cpathname* if the former is " +"set to ``NULL``." +msgstr "" +"類似於 :c:func:`PyImport_ExecCodeModuleObject`，但是 *name*、*pathname* 和 " +"*cpathname* 是 UTF-8 編碼的字串。如果 *pathname* 被設定為 ``NULL``，也會嘗試" +"從 *cpathname* 中找出 *pathname* 的值應該是什麼。" + +#: ../../c-api/import.rst:192 +msgid "" +"Uses :func:`!imp.source_from_cache` in calculating the source path if only " +"the bytecode path is provided." +msgstr "" +"如果只提供了位元組碼路徑，則在計算原始碼路徑時使用 :func:`!imp." +"source_from_cache`。" + +#: ../../c-api/import.rst:195 +msgid "No longer uses the removed :mod:`!imp` module." +msgstr "不再使用已被移除的 :mod:`!imp` 模組。" + +#: ../../c-api/import.rst:201 +msgid "" +"Return the magic number for Python bytecode files (a.k.a. :file:`.pyc` " +"file). The magic number should be present in the first four bytes of the " +"bytecode file, in little-endian byte order. Returns ``-1`` on error." +msgstr "" +"回傳 Python 位元組碼檔案（也稱為 :file:`.pyc` 檔案）的魔術數字（magic " +"number）。魔術數字應該出現在位元組碼檔案的前四個位元組，以小端序（little-" +"endian）位元組順序排列。錯誤時會回傳 ``-1``。" + +#: ../../c-api/import.rst:205 +msgid "Return value of ``-1`` upon failure." +msgstr "當失敗時回傳 ``-1``。" + +#: ../../c-api/import.rst:211 +msgid "" +"Return the magic tag string for :pep:`3147` format Python bytecode file " +"names. Keep in mind that the value at ``sys.implementation.cache_tag`` is " +"authoritative and should be used instead of this function." +msgstr "" +"回傳 :pep:`3147` 格式 Python 位元組碼檔名的魔術標籤字串。請記住，``sys." +"implementation.cache_tag`` 的值是權威的，應該使用它來取代這個函式。" + +#: ../../c-api/import.rst:219 +msgid "" +"Return the dictionary used for the module administration (a.k.a. ``sys." +"modules``). Note that this is a per-interpreter variable." +msgstr "" +"回傳用於模組管理的字典（也稱為 ``sys.modules``）。請注意，這是一個針對每個直" +"譯器的變數 (per-interpreter variable)。" + +#: ../../c-api/import.rst:224 +msgid "" +"Return the already imported module with the given name. If the module has " +"not been imported yet then returns ``NULL`` but does not set an error. " +"Returns ``NULL`` and sets an error if the lookup failed." +msgstr "" +"回傳已以給定名稱引入的模組。如果模組尚未引入，則會回傳 ``NULL`` 但不會設定錯" +"誤。如果查找失敗，則回傳 ``NULL`` 並設定錯誤。" + +#: ../../c-api/import.rst:232 +msgid "" +"Return a finder object for a :data:`sys.path`/:attr:`!pkg.__path__` item " +"*path*, possibly by fetching it from the :data:`sys.path_importer_cache` " +"dict. If it wasn't yet cached, traverse :data:`sys.path_hooks` until a hook " +"is found that can handle the path item. Return ``None`` if no hook could; " +"this tells our caller that the :term:`path based finder` could not find a " +"finder for this path item. Cache the result in :data:`sys." +"path_importer_cache`. Return a new reference to the finder object." +msgstr "" +"回傳 :data:`sys.path`/:attr:`!pkg.__path__` 項 *path* 的查找器物件 (finder " +"object)，可能的方式是從 :data:`sys.path_importer_cache` 字典取得。如果它還沒" +"有被快取，就遍歷 :data:`sys.path_hooks` 直到找到可以處理路徑項的掛勾。如果沒" +"有掛勾可以處理，則回傳 ``None``；這會告訴我們的呼叫者 :term:`path based " +"finder` 找不到這個路徑項的查找器。將結果快取到 :data:`sys." +"path_importer_cache`。回傳查找器物件的新參照。" + +#: ../../c-api/import.rst:243 +msgid "" +"Load a frozen module named *name*. Return ``1`` for success, ``0`` if the " +"module is not found, and ``-1`` with an exception set if the initialization " +"failed. To access the imported module on a successful load, use :c:func:" +"`PyImport_ImportModule`. (Note the misnomer --- this function would reload " +"the module if it was already imported.)" +msgstr "" +"載入一個名為 *name* 的凍結模組。成功則回傳 ``1``，找不到模組則回傳 ``0``，初" +"始化失敗則回傳 ``-1`` 並設定例外。要在成功載入時存取引入的模組，請使用 :c:" +"func:`PyImport_ImportModule`。（請注意這個名稱並不恰當 --- 如果模組已經被引" +"入，這個函式會重新載入模組）。" + +#: ../../c-api/import.rst:251 +msgid "The ``__file__`` attribute is no longer set on the module." +msgstr "不會再於模組設定 ``__file__`` 屬性。" + +#: ../../c-api/import.rst:257 +msgid "" +"Similar to :c:func:`PyImport_ImportFrozenModuleObject`, but the name is a " +"UTF-8 encoded string instead of a Unicode object." +msgstr "" +"類似於 :c:func:`PyImport_ImportFrozenModuleObject`，但名稱是 UTF-8 編碼字串，" +"而不是 Unicode 物件。" + +#: ../../c-api/import.rst:265 +msgid "" +"This is the structure type definition for frozen module descriptors, as " +"generated by the :program:`freeze` utility (see :file:`Tools/freeze/` in the " +"Python source distribution). Its definition, found in :file:`Include/import." +"h`, is::" +msgstr "" +"這是由 :program:`freeze` 工具程式產生的凍結模組描述器的結構型別定義（請參閱 " +"Python 原始碼發行版中的 :file:`Tools/freeze/`）。它的定義在 :file:`Include/" +"import.h` 中，為： ::" + +#: ../../c-api/import.rst:270 +msgid "" +"struct _frozen {\n" +" const char *name;\n" +" const unsigned char *code;\n" +" int size;\n" +" bool is_package;\n" +"};" +msgstr "" +"struct _frozen {\n" +" const char *name;\n" +" const unsigned char *code;\n" +" int size;\n" +" bool is_package;\n" +"};" + +#: ../../c-api/import.rst:277 +msgid "" +"The new ``is_package`` field indicates whether the module is a package or " +"not. This replaces setting the ``size`` field to a negative value." +msgstr "" +"新的 ``is_package`` 欄位指出模組是否為套件。這取代了將 ``size`` 欄位設定為負" +"值的方式。" + +#: ../../c-api/import.rst:283 +msgid "" +"This pointer is initialized to point to an array of :c:struct:`_frozen` " +"records, terminated by one whose members are all ``NULL`` or zero. When a " +"frozen module is imported, it is searched in this table. Third-party code " +"could play tricks with this to provide a dynamically created collection of " +"frozen modules." +msgstr "" +"這個指標會被初始化為指向一個 :c:struct:`_frozen` 記錄的陣列，以一個其成員都" +"是 ``NULL`` 或 0 的記錄為結尾。當一個凍結的模組被引入時，它會在這個表格中被搜" +"尋。第三方程式碼可以利用這一點來提供一個動態建立的凍結模組集合。" + +#: ../../c-api/import.rst:291 +msgid "" +"Add a single module to the existing table of built-in modules. This is a " +"convenience wrapper around :c:func:`PyImport_ExtendInittab`, returning " +"``-1`` if the table could not be extended. The new module can be imported " +"by the name *name*, and uses the function *initfunc* as the initialization " +"function called on the first attempted import. This should be called " +"before :c:func:`Py_Initialize`." +msgstr "" +"新增單一模組到現有的內建模組表格。這是 :c:func:`PyImport_ExtendInittab` 的便" +"利包裝器，如果表格無法擴充會回傳 ``-1``。新的模組可以用 *name* 的名稱引入，並" +"使用函式 *initfunc* 作為第一次嘗試引入時呼叫的初始化函式。這應該在 :c:func:" +"`Py_Initialize` 之前呼叫。" + +#: ../../c-api/import.rst:301 +msgid "" +"Structure describing a single entry in the list of built-in modules. " +"Programs which embed Python may use an array of these structures in " +"conjunction with :c:func:`PyImport_ExtendInittab` to provide additional " +"built-in modules. The structure consists of two members:" +msgstr "" +"描述內建模組列表中單一項目的結構。嵌入 Python 的程式可以使用這些結構的陣列" +"與 :c:func:`PyImport_ExtendInittab` 結合來提供額外的內建模組。這個結構包含兩" +"個成員：" + +#: ../../c-api/import.rst:309 +msgid "The module name, as an ASCII encoded string." +msgstr "模組名稱，為 ASCII 編碼的字串。" + +#: ../../c-api/import.rst:313 +msgid "Initialization function for a module built into the interpreter." +msgstr "內建於直譯器中的模組的初始化函式。" + +#: ../../c-api/import.rst:318 +msgid "" +"Add a collection of modules to the table of built-in modules. The *newtab* " +"array must end with a sentinel entry which contains ``NULL`` for the :c:" +"member:`~_inittab.name` field; failure to provide the sentinel value can " +"result in a memory fault. Returns ``0`` on success or ``-1`` if insufficient " +"memory could be allocated to extend the internal table. In the event of " +"failure, no modules are added to the internal table. This must be called " +"before :c:func:`Py_Initialize`." +msgstr "" +"新增一個模組集合到內建模組表格。*newtab* 陣列必須以包含 ``NULL`` 的 :c:" +"member:`~_inittab.name` 欄位的哨兵項目（sentinel entry）結尾；如果沒有提供哨" +"兵值，可能會導致記憶體錯誤。成功時會回傳 ``0``，如果沒有足夠的記憶體可以分配" +"來擴充內部表格則回傳 ``-1``。在失敗的情況下，沒有模組會被加入內部表格。這個函" +"式必須在 :c:func:`Py_Initialize` 之前呼叫。" + +#: ../../c-api/import.rst:325 +msgid "" +"If Python is initialized multiple times, :c:func:`PyImport_AppendInittab` " +"or :c:func:`PyImport_ExtendInittab` must be called before each Python " +"initialization." +msgstr "" +"如果 Python 被多次初始化，:c:func:`PyImport_AppendInittab` 或 :c:func:" +"`PyImport_ExtendInittab` 必須在每次 Python 初始化之前被呼叫。" + +#: ../../c-api/import.rst:332 +msgid "" +"The table of built-in modules used by Python initialization. Do not use this " +"directly; use :c:func:`PyImport_AppendInittab` and :c:func:" +"`PyImport_ExtendInittab` instead." +msgstr "" +"Python 初始化所使用的內建模組表格。請勿直接使用它，" +"請改用 :c:func:`PyImport_AppendInittab` 與 :c:func:" +"`PyImport_ExtendInittab`。" + +#: ../../c-api/import.rst:339 +msgid "Import the module *mod_name* and get its attribute *attr_name*." +msgstr "引入模組 *mod_name* 並取得其屬性 *attr_name*。" + +#: ../../c-api/import.rst:341 +msgid "Names must be Python :class:`str` objects." +msgstr "名稱必須是 Python :class:`str` 物件。" + +#: ../../c-api/import.rst:343 +msgid "" +"Helper function combining :c:func:`PyImport_Import` and :c:func:" +"`PyObject_GetAttr`. For example, it can raise :exc:`ImportError` if the " +"module is not found, and :exc:`AttributeError` if the attribute doesn't " +"exist." +msgstr "" +"結合 :c:func:`PyImport_Import` 和 :c:func:`PyObject_GetAttr` 的輔助函式。例" +"如，如果找不到模組，它會引發 :exc:`ImportError`，如果屬性不存在，則會引發 :" +"exc:`AttributeError`。" + +#: ../../c-api/import.rst:352 +msgid "" +"Similar to :c:func:`PyImport_ImportModuleAttr`, but names are UTF-8 encoded " +"strings instead of Python :class:`str` objects." +msgstr "" +"類似於 :c:func:`PyImport_ImportModuleAttr`，但名稱是 UTF-8 編碼字串，而不是 " +"Python :class:`str` 物件。" + +#: ../../c-api/import.rst:11 +msgid "package variable" +msgstr "package variable（套件變數）" + +#: ../../c-api/import.rst:11 +msgid "__all__" +msgstr "__all__" + +#: ../../c-api/import.rst:11 +msgid "__all__ (package variable)" +msgstr "__all__（套件變數）" + +#: ../../c-api/import.rst:11 +msgid "modules (in module sys)" +msgstr "modules（sys 模組中）" + +#: ../../c-api/import.rst:35 ../../c-api/import.rst:127 +msgid "built-in function" +msgstr "built-in function（內建函式）" + +#: ../../c-api/import.rst:35 +msgid "__import__" +msgstr "__import__" + +#: ../../c-api/import.rst:127 +msgid "compile" +msgstr "compile（編譯）" + +#: ../../c-api/import.rst:263 +msgid "freeze utility" +msgstr "freeze utility（凍結工具程式）" diff --git a/c-api/index.po b/c-api/index.po index 024b9747ea..667219063a 100644 --- a/c-api/index.po +++ b/c-api/index.po @@ -1,37 +1,37 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Leon H., 2017 -# 豆豆 (Tommy Lin) , 2017 -# Steven Hsu , 2021 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2018-06-26 18:54+0800\n" -"PO-Revision-Date: 2021-07-05 21:11+0800\n" -"Last-Translator: 豆豆 (Tommy Lin) \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" -"X-Generator: Poedit 2.4.3\n" - -#: ../../c-api/index.rst:5 -msgid "Python/C API Reference Manual" -msgstr "Python/C API 參考手冊" - -#: ../../c-api/index.rst:7 -msgid "" -"This manual documents the API used by C and C++ programmers who want to " -"write extension modules or embed Python. It is a companion to :ref:" -"`extending-index`, which describes the general principles of extension " -"writing but does not document the API functions in detail." -msgstr "" -"對於想要編寫擴充模組或是嵌入 Python 的 C 和 C++ 程式設計師們，這份手冊記錄了" -"可使用的 API（應用程式介面）。在\\ :ref:`extending-index`\\ 中也有相關的內" -"容，它描述了編寫擴充的一般原則，但並沒有詳細說明 API 函式。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Leon H., 2017 +# 豆豆 (Tommy Lin) , 2017 +# Steven Hsu , 2021 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2018-06-26 18:54+0800\n" +"PO-Revision-Date: 2021-07-05 21:11+0800\n" +"Last-Translator: 豆豆 (Tommy Lin) \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" +"X-Generator: Poedit 2.4.3\n" + +#: ../../c-api/index.rst:5 +msgid "Python/C API Reference Manual" +msgstr "Python/C API 參考手冊" + +#: ../../c-api/index.rst:7 +msgid "" +"This manual documents the API used by C and C++ programmers who want to " +"write extension modules or embed Python. It is a companion to :ref:" +"`extending-index`, which describes the general principles of extension " +"writing but does not document the API functions in detail." +msgstr "" +"對於想要編寫擴充模組或是嵌入 Python 的 C 和 C++ 程式設計師們，這份手冊記錄了" +"可使用的 API（應用程式介面）。在\\ :ref:`extending-index`\\ 中也有相關的內" +"容，它描述了編寫擴充的一般原則，但並沒有詳細說明 API 函式。" diff --git a/c-api/init.po b/c-api/init.po index 2932196ad1..37cfb8ca73 100644 --- a/c-api/init.po +++ b/c-api/init.po @@ -1,3727 +1,3727 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Adrian Liaw , 2018 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-26 00:14+0000\n" -"PO-Revision-Date: 2023-04-24 20:49+0800\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" -"X-Generator: Poedit 3.2.2\n" - -#: ../../c-api/init.rst:8 -msgid "Initialization, Finalization, and Threads" -msgstr "初始化、終結化與執行緒" - -#: ../../c-api/init.rst:10 -msgid "" -"See :ref:`Python Initialization Configuration ` for details on " -"how to configure the interpreter prior to initialization." -msgstr "" -"關於如何在初始化之前設定直譯器的細節，請參見 :ref:`Python 初始化設定 `。" - -#: ../../c-api/init.rst:16 -msgid "Before Python Initialization" -msgstr "Python 初始化之前" - -#: ../../c-api/init.rst:18 -msgid "" -"In an application embedding Python, the :c:func:`Py_Initialize` function " -"must be called before using any other Python/C API functions; with the " -"exception of a few functions and the :ref:`global configuration variables " -"`." -msgstr "" - -#: ../../c-api/init.rst:23 -msgid "" -"The following functions can be safely called before Python is initialized:" -msgstr "" - -#: ../../c-api/init.rst:25 -msgid "Functions that initialize the interpreter:" -msgstr "" - -#: ../../c-api/init.rst:27 -msgid ":c:func:`Py_Initialize`" -msgstr ":c:func:`Py_Initialize`" - -#: ../../c-api/init.rst:28 -msgid ":c:func:`Py_InitializeEx`" -msgstr ":c:func:`Py_InitializeEx`" - -#: ../../c-api/init.rst:29 -msgid ":c:func:`Py_InitializeFromConfig`" -msgstr ":c:func:`Py_InitializeFromConfig`" - -#: ../../c-api/init.rst:30 -msgid ":c:func:`Py_BytesMain`" -msgstr ":c:func:`Py_BytesMain`" - -#: ../../c-api/init.rst:31 -msgid ":c:func:`Py_Main`" -msgstr ":c:func:`Py_Main`" - -#: ../../c-api/init.rst:32 -msgid "the runtime pre-initialization functions covered in :ref:`init-config`" -msgstr "" - -#: ../../c-api/init.rst:34 -msgid "Configuration functions:" -msgstr "" - -#: ../../c-api/init.rst:36 -msgid ":c:func:`PyImport_AppendInittab`" -msgstr ":c:func:`PyImport_AppendInittab`" - -#: ../../c-api/init.rst:37 -msgid ":c:func:`PyImport_ExtendInittab`" -msgstr ":c:func:`PyImport_ExtendInittab`" - -#: ../../c-api/init.rst:38 -msgid ":c:func:`!PyInitFrozenExtensions`" -msgstr ":c:func:`!PyInitFrozenExtensions`" - -#: ../../c-api/init.rst:39 -msgid ":c:func:`PyMem_SetAllocator`" -msgstr ":c:func:`PyMem_SetAllocator`" - -#: ../../c-api/init.rst:40 -msgid ":c:func:`PyMem_SetupDebugHooks`" -msgstr ":c:func:`PyMem_SetupDebugHooks`" - -#: ../../c-api/init.rst:41 -msgid ":c:func:`PyObject_SetArenaAllocator`" -msgstr ":c:func:`PyObject_SetArenaAllocator`" - -#: ../../c-api/init.rst:42 -msgid ":c:func:`Py_SetProgramName`" -msgstr ":c:func:`Py_SetProgramName`" - -#: ../../c-api/init.rst:43 -msgid ":c:func:`Py_SetPythonHome`" -msgstr ":c:func:`Py_SetPythonHome`" - -#: ../../c-api/init.rst:44 -msgid ":c:func:`PySys_ResetWarnOptions`" -msgstr ":c:func:`PySys_ResetWarnOptions`" - -#: ../../c-api/init.rst:45 -msgid "the configuration functions covered in :ref:`init-config`" -msgstr "" - -#: ../../c-api/init.rst:47 -msgid "Informative functions:" -msgstr "" - -#: ../../c-api/init.rst:49 ../../c-api/init.rst:57 -msgid ":c:func:`Py_IsInitialized`" -msgstr ":c:func:`Py_IsInitialized`" - -#: ../../c-api/init.rst:50 -msgid ":c:func:`PyMem_GetAllocator`" -msgstr ":c:func:`PyMem_GetAllocator`" - -#: ../../c-api/init.rst:51 -msgid ":c:func:`PyObject_GetArenaAllocator`" -msgstr ":c:func:`PyObject_GetArenaAllocator`" - -#: ../../c-api/init.rst:52 -msgid ":c:func:`Py_GetBuildInfo`" -msgstr ":c:func:`Py_GetBuildInfo`" - -#: ../../c-api/init.rst:53 -msgid ":c:func:`Py_GetCompiler`" -msgstr ":c:func:`Py_GetCompiler`" - -#: ../../c-api/init.rst:54 -msgid ":c:func:`Py_GetCopyright`" -msgstr ":c:func:`Py_GetCopyright`" - -#: ../../c-api/init.rst:55 -msgid ":c:func:`Py_GetPlatform`" -msgstr ":c:func:`Py_GetPlatform`" - -#: ../../c-api/init.rst:56 -msgid ":c:func:`Py_GetVersion`" -msgstr ":c:func:`Py_GetVersion`" - -#: ../../c-api/init.rst:59 -msgid "Utilities:" -msgstr "" - -#: ../../c-api/init.rst:61 -msgid ":c:func:`Py_DecodeLocale`" -msgstr ":c:func:`Py_DecodeLocale`" - -#: ../../c-api/init.rst:62 -msgid "" -"the status reporting and utility functions covered in :ref:`init-config`" -msgstr "" - -#: ../../c-api/init.rst:64 -msgid "Memory allocators:" -msgstr "" - -#: ../../c-api/init.rst:66 -msgid ":c:func:`PyMem_RawMalloc`" -msgstr ":c:func:`PyMem_RawMalloc`" - -#: ../../c-api/init.rst:67 -msgid ":c:func:`PyMem_RawRealloc`" -msgstr ":c:func:`PyMem_RawRealloc`" - -#: ../../c-api/init.rst:68 -msgid ":c:func:`PyMem_RawCalloc`" -msgstr ":c:func:`PyMem_RawCalloc`" - -#: ../../c-api/init.rst:69 -msgid ":c:func:`PyMem_RawFree`" -msgstr ":c:func:`PyMem_RawFree`" - -#: ../../c-api/init.rst:71 -msgid "Synchronization:" -msgstr "" - -#: ../../c-api/init.rst:73 -msgid ":c:func:`PyMutex_Lock`" -msgstr ":c:func:`PyMutex_Lock`" - -#: ../../c-api/init.rst:74 -msgid ":c:func:`PyMutex_Unlock`" -msgstr ":c:func:`PyMutex_Unlock`" - -#: ../../c-api/init.rst:78 -msgid "" -"Despite their apparent similarity to some of the functions listed above, the " -"following functions **should not be called** before the interpreter has been " -"initialized: :c:func:`Py_EncodeLocale`, :c:func:`Py_GetPath`, :c:func:" -"`Py_GetPrefix`, :c:func:`Py_GetExecPrefix`, :c:func:" -"`Py_GetProgramFullPath`, :c:func:`Py_GetPythonHome`, :c:func:" -"`Py_GetProgramName`, :c:func:`PyEval_InitThreads`, and :c:func:`Py_RunMain`." -msgstr "" - -#: ../../c-api/init.rst:90 -msgid "Global configuration variables" -msgstr "" - -#: ../../c-api/init.rst:92 -msgid "" -"Python has variables for the global configuration to control different " -"features and options. By default, these flags are controlled by :ref:" -"`command line options `." -msgstr "" - -#: ../../c-api/init.rst:96 -msgid "" -"When a flag is set by an option, the value of the flag is the number of " -"times that the option was set. For example, ``-b`` sets :c:data:" -"`Py_BytesWarningFlag` to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to " -"2." -msgstr "" - -#: ../../c-api/init.rst:102 -msgid "" -"This API is kept for backward compatibility: setting :c:member:`PyConfig." -"bytes_warning` should be used instead, see :ref:`Python Initialization " -"Configuration `." -msgstr "" - -#: ../../c-api/init.rst:106 -msgid "" -"Issue a warning when comparing :class:`bytes` or :class:`bytearray` with :" -"class:`str` or :class:`bytes` with :class:`int`. Issue an error if greater " -"or equal to ``2``." -msgstr "" - -#: ../../c-api/init.rst:110 -msgid "Set by the :option:`-b` option." -msgstr "由 :option:`-b` 選項設定。" - -#: ../../c-api/init.rst:116 -msgid "" -"This API is kept for backward compatibility: setting :c:member:`PyConfig." -"parser_debug` should be used instead, see :ref:`Python Initialization " -"Configuration `." -msgstr "" - -#: ../../c-api/init.rst:120 -msgid "" -"Turn on parser debugging output (for expert only, depending on compilation " -"options)." -msgstr "" - -#: ../../c-api/init.rst:123 -msgid "" -"Set by the :option:`-d` option and the :envvar:`PYTHONDEBUG` environment " -"variable." -msgstr "由 :option:`-d` 選項與 :envvar:`PYTHONDEBUG` 環境變數設定。" - -#: ../../c-api/init.rst:130 -msgid "" -"This API is kept for backward compatibility: setting :c:member:`PyConfig." -"write_bytecode` should be used instead, see :ref:`Python Initialization " -"Configuration `." -msgstr "" - -#: ../../c-api/init.rst:134 -msgid "" -"If set to non-zero, Python won't try to write ``.pyc`` files on the import " -"of source modules." -msgstr "" - -#: ../../c-api/init.rst:137 -msgid "" -"Set by the :option:`-B` option and the :envvar:`PYTHONDONTWRITEBYTECODE` " -"environment variable." -msgstr "" -"由 :option:`-B` 選項與 :envvar:`PYTHONDONTWRITEBYTECODE` 環境變數設定。" - -#: ../../c-api/init.rst:144 -msgid "" -"This API is kept for backward compatibility: setting :c:member:`PyConfig." -"pathconfig_warnings` should be used instead, see :ref:`Python Initialization " -"Configuration `." -msgstr "" - -#: ../../c-api/init.rst:148 -msgid "" -"Suppress error messages when calculating the module search path in :c:func:" -"`Py_GetPath`." -msgstr "" - -#: ../../c-api/init.rst:151 -msgid "Private flag used by ``_freeze_module`` and ``frozenmain`` programs." -msgstr "" - -#: ../../c-api/init.rst:157 -msgid "" -"This API is kept for backward compatibility: setting :c:member:`PyConfig." -"hash_seed` and :c:member:`PyConfig.use_hash_seed` should be used instead, " -"see :ref:`Python Initialization Configuration `." -msgstr "" - -#: ../../c-api/init.rst:162 -msgid "" -"Set to ``1`` if the :envvar:`PYTHONHASHSEED` environment variable is set to " -"a non-empty string." -msgstr "" -"如果環境變數 :envvar:`PYTHONHASHSEED` 被設定為一個非空字串則設為 ``1``。" - -#: ../../c-api/init.rst:165 -msgid "" -"If the flag is non-zero, read the :envvar:`PYTHONHASHSEED` environment " -"variable to initialize the secret hash seed." -msgstr "" - -#: ../../c-api/init.rst:172 -msgid "" -"This API is kept for backward compatibility: setting :c:member:`PyConfig." -"use_environment` should be used instead, see :ref:`Python Initialization " -"Configuration `." -msgstr "" - -#: ../../c-api/init.rst:176 -msgid "" -"Ignore all :envvar:`!PYTHON*` environment variables, e.g. :envvar:" -"`PYTHONPATH` and :envvar:`PYTHONHOME`, that might be set." -msgstr "" -"忽略所有可能被設定的 :envvar:`!PYTHON*` 環境變數，例如 :envvar:`PYTHONPATH` " -"與 :envvar:`PYTHONHOME`。" - -#: ../../c-api/init.rst:179 -msgid "Set by the :option:`-E` and :option:`-I` options." -msgstr "由 :option:`-E` 與 :option:`-I` 選項設定。" - -#: ../../c-api/init.rst:185 -msgid "" -"This API is kept for backward compatibility: setting :c:member:`PyConfig." -"inspect` should be used instead, see :ref:`Python Initialization " -"Configuration `." -msgstr "" - -#: ../../c-api/init.rst:189 -msgid "" -"When a script is passed as first argument or the :option:`-c` option is " -"used, enter interactive mode after executing the script or the command, even " -"when :data:`sys.stdin` does not appear to be a terminal." -msgstr "" - -#: ../../c-api/init.rst:193 -msgid "" -"Set by the :option:`-i` option and the :envvar:`PYTHONINSPECT` environment " -"variable." -msgstr "由 :option:`-i` 選項與 :envvar:`PYTHONINSPECT` 環境變數設定。" - -#: ../../c-api/init.rst:200 -msgid "" -"This API is kept for backward compatibility: setting :c:member:`PyConfig." -"interactive` should be used instead, see :ref:`Python Initialization " -"Configuration `." -msgstr "" - -#: ../../c-api/init.rst:204 -msgid "Set by the :option:`-i` option." -msgstr "由 :option:`-i` 選項設定。" - -#: ../../c-api/init.rst:210 -msgid "" -"This API is kept for backward compatibility: setting :c:member:`PyConfig." -"isolated` should be used instead, see :ref:`Python Initialization " -"Configuration `." -msgstr "" - -#: ../../c-api/init.rst:214 -msgid "" -"Run Python in isolated mode. In isolated mode :data:`sys.path` contains " -"neither the script's directory nor the user's site-packages directory." -msgstr "" - -#: ../../c-api/init.rst:217 -msgid "Set by the :option:`-I` option." -msgstr "由 :option:`-I` 選項設定。" - -#: ../../c-api/init.rst:225 -msgid "" -"This API is kept for backward compatibility: setting :c:member:`PyPreConfig." -"legacy_windows_fs_encoding` should be used instead, see :ref:`Python " -"Initialization Configuration `." -msgstr "" - -#: ../../c-api/init.rst:229 -msgid "" -"If the flag is non-zero, use the ``mbcs`` encoding with ``replace`` error " -"handler, instead of the UTF-8 encoding with ``surrogatepass`` error handler, " -"for the :term:`filesystem encoding and error handler`." -msgstr "" - -#: ../../c-api/init.rst:233 -msgid "" -"Set to ``1`` if the :envvar:`PYTHONLEGACYWINDOWSFSENCODING` environment " -"variable is set to a non-empty string." -msgstr "" -"如果環境變數 :envvar:`PYTHONLEGACYWINDOWSFSENCODING` 被設定為一個非空字串則設" -"為 ``1``。" - -#: ../../c-api/init.rst:236 -msgid "See :pep:`529` for more details." -msgstr "更多詳情請見 :pep:`529`。" - -#: ../../c-api/init.rst:238 ../../c-api/init.rst:256 -msgid "Availability" -msgstr "可用性" - -#: ../../c-api/init.rst:244 -msgid "" -"This API is kept for backward compatibility: setting :c:member:`PyConfig." -"legacy_windows_stdio` should be used instead, see :ref:`Python " -"Initialization Configuration `." -msgstr "" - -#: ../../c-api/init.rst:248 -msgid "" -"If the flag is non-zero, use :class:`io.FileIO` instead of :class:`!io." -"_WindowsConsoleIO` for :mod:`sys` standard streams." -msgstr "" - -#: ../../c-api/init.rst:251 -msgid "" -"Set to ``1`` if the :envvar:`PYTHONLEGACYWINDOWSSTDIO` environment variable " -"is set to a non-empty string." -msgstr "" - -#: ../../c-api/init.rst:254 -msgid "See :pep:`528` for more details." -msgstr "更多詳情請見 :pep:`528`。" - -#: ../../c-api/init.rst:262 -msgid "" -"This API is kept for backward compatibility: setting :c:member:`PyConfig." -"site_import` should be used instead, see :ref:`Python Initialization " -"Configuration `." -msgstr "" - -#: ../../c-api/init.rst:266 -msgid "" -"Disable the import of the module :mod:`site` and the site-dependent " -"manipulations of :data:`sys.path` that it entails. Also disable these " -"manipulations if :mod:`site` is explicitly imported later (call :func:`site." -"main` if you want them to be triggered)." -msgstr "" - -#: ../../c-api/init.rst:271 -msgid "Set by the :option:`-S` option." -msgstr "由 :option:`-S` 選項設定。" - -#: ../../c-api/init.rst:277 -msgid "" -"This API is kept for backward compatibility: setting :c:member:`PyConfig." -"user_site_directory` should be used instead, see :ref:`Python Initialization " -"Configuration `." -msgstr "" - -#: ../../c-api/init.rst:281 -msgid "" -"Don't add the :data:`user site-packages directory ` to :data:" -"`sys.path`." -msgstr "" - -#: ../../c-api/init.rst:284 -msgid "" -"Set by the :option:`-s` and :option:`-I` options, and the :envvar:" -"`PYTHONNOUSERSITE` environment variable." -msgstr "" -"由 :option:`-s` 選項、:option:`-I` 選項與 :envvar:`PYTHONNOUSERSITE` 環境變數" -"設定。" - -#: ../../c-api/init.rst:291 -msgid "" -"This API is kept for backward compatibility: setting :c:member:`PyConfig." -"optimization_level` should be used instead, see :ref:`Python Initialization " -"Configuration `." -msgstr "" - -#: ../../c-api/init.rst:295 -msgid "" -"Set by the :option:`-O` option and the :envvar:`PYTHONOPTIMIZE` environment " -"variable." -msgstr "由 :option:`-O` 選項與 :envvar:`PYTHONOPTIMIZE` 環境變數設定。" - -#: ../../c-api/init.rst:302 -msgid "" -"This API is kept for backward compatibility: setting :c:member:`PyConfig." -"quiet` should be used instead, see :ref:`Python Initialization Configuration " -"`." -msgstr "" - -#: ../../c-api/init.rst:306 -msgid "" -"Don't display the copyright and version messages even in interactive mode." -msgstr "" - -#: ../../c-api/init.rst:308 -msgid "Set by the :option:`-q` option." -msgstr "由 :option:`-q` 選項設定。" - -#: ../../c-api/init.rst:316 -msgid "" -"This API is kept for backward compatibility: setting :c:member:`PyConfig." -"buffered_stdio` should be used instead, see :ref:`Python Initialization " -"Configuration `." -msgstr "" - -#: ../../c-api/init.rst:320 -msgid "Force the stdout and stderr streams to be unbuffered." -msgstr "" - -#: ../../c-api/init.rst:322 -msgid "" -"Set by the :option:`-u` option and the :envvar:`PYTHONUNBUFFERED` " -"environment variable." -msgstr "由 :option:`-u` 選項與 :envvar:`PYTHONUNBUFFERED` 環境變數設定。" - -#: ../../c-api/init.rst:329 -msgid "" -"This API is kept for backward compatibility: setting :c:member:`PyConfig." -"verbose` should be used instead, see :ref:`Python Initialization " -"Configuration `." -msgstr "" - -#: ../../c-api/init.rst:333 -msgid "" -"Print a message each time a module is initialized, showing the place " -"(filename or built-in module) from which it is loaded. If greater or equal " -"to ``2``, print a message for each file that is checked for when searching " -"for a module. Also provides information on module cleanup at exit." -msgstr "" - -#: ../../c-api/init.rst:338 -msgid "" -"Set by the :option:`-v` option and the :envvar:`PYTHONVERBOSE` environment " -"variable." -msgstr "由 :option:`-v` 選項與 :envvar:`PYTHONVERBOSE` 環境變數設定。" - -#: ../../c-api/init.rst:345 -msgid "Initializing and finalizing the interpreter" -msgstr "" - -#: ../../c-api/init.rst:360 -msgid "" -"Initialize the Python interpreter. In an application embedding Python, " -"this should be called before using any other Python/C API functions; see :" -"ref:`Before Python Initialization ` for the few exceptions." -msgstr "" - -#: ../../c-api/init.rst:364 -msgid "" -"This initializes the table of loaded modules (``sys.modules``), and creates " -"the fundamental modules :mod:`builtins`, :mod:`__main__` and :mod:`sys`. It " -"also initializes the module search path (``sys.path``). It does not set " -"``sys.argv``; use the :ref:`Python Initialization Configuration ` API for that. This is a no-op when called for a second time " -"(without calling :c:func:`Py_FinalizeEx` first). There is no return value; " -"it is a fatal error if the initialization fails." -msgstr "" - -#: ../../c-api/init.rst:372 ../../c-api/init.rst:386 -msgid "" -"Use :c:func:`Py_InitializeFromConfig` to customize the :ref:`Python " -"Initialization Configuration `." -msgstr "" - -#: ../../c-api/init.rst:376 -msgid "" -"On Windows, changes the console mode from ``O_TEXT`` to ``O_BINARY``, which " -"will also affect non-Python uses of the console using the C Runtime." -msgstr "" - -#: ../../c-api/init.rst:382 -msgid "" -"This function works like :c:func:`Py_Initialize` if *initsigs* is ``1``. If " -"*initsigs* is ``0``, it skips initialization registration of signal " -"handlers, which may be useful when CPython is embedded as part of a larger " -"application." -msgstr "" - -#: ../../c-api/init.rst:392 -msgid "" -"Initialize Python from *config* configuration, as described in :ref:`init-" -"from-config`." -msgstr "" - -#: ../../c-api/init.rst:395 -msgid "" -"See the :ref:`init-config` section for details on pre-initializing the " -"interpreter, populating the runtime configuration structure, and querying " -"the returned status structure." -msgstr "" - -#: ../../c-api/init.rst:402 -msgid "" -"Return true (nonzero) when the Python interpreter has been initialized, " -"false (zero) if not. After :c:func:`Py_FinalizeEx` is called, this returns " -"false until :c:func:`Py_Initialize` is called again." -msgstr "" - -#: ../../c-api/init.rst:409 -msgid "" -"Return true (non-zero) if the main Python interpreter is :term:`shutting " -"down `. Return false (zero) otherwise." -msgstr "" - -#: ../../c-api/init.rst:417 -msgid "" -"Undo all initializations made by :c:func:`Py_Initialize` and subsequent use " -"of Python/C API functions, and destroy all sub-interpreters (see :c:func:" -"`Py_NewInterpreter` below) that were created and not yet destroyed since the " -"last call to :c:func:`Py_Initialize`. This is a no-op when called for a " -"second time (without calling :c:func:`Py_Initialize` again first)." -msgstr "" - -#: ../../c-api/init.rst:423 -msgid "" -"Since this is the reverse of :c:func:`Py_Initialize`, it should be called in " -"the same thread with the same interpreter active. That means the main " -"thread and the main interpreter. This should never be called while :c:func:" -"`Py_RunMain` is running." -msgstr "" - -#: ../../c-api/init.rst:428 -msgid "" -"Normally the return value is ``0``. If there were errors during finalization " -"(flushing buffered data), ``-1`` is returned." -msgstr "" - -#: ../../c-api/init.rst:432 -msgid "" -"Note that Python will do a best effort at freeing all memory allocated by " -"the Python interpreter. Therefore, any C-Extension should make sure to " -"correctly clean up all of the preveiously allocated PyObjects before using " -"them in subsequent calls to :c:func:`Py_Initialize`. Otherwise it could " -"introduce vulnerabilities and incorrect behavior." -msgstr "" - -#: ../../c-api/init.rst:438 -msgid "" -"This function is provided for a number of reasons. An embedding application " -"might want to restart Python without having to restart the application " -"itself. An application that has loaded the Python interpreter from a " -"dynamically loadable library (or DLL) might want to free all memory " -"allocated by Python before unloading the DLL. During a hunt for memory leaks " -"in an application a developer might want to free all memory allocated by " -"Python before exiting from the application." -msgstr "" - -#: ../../c-api/init.rst:446 -msgid "" -"**Bugs and caveats:** The destruction of modules and objects in modules is " -"done in random order; this may cause destructors (:meth:`~object.__del__` " -"methods) to fail when they depend on other objects (even functions) or " -"modules. Dynamically loaded extension modules loaded by Python are not " -"unloaded. Small amounts of memory allocated by the Python interpreter may " -"not be freed (if you find a leak, please report it). Memory tied up in " -"circular references between objects is not freed. Interned strings will all " -"be deallocated regardless of their reference count. Some memory allocated by " -"extension modules may not be freed. Some extensions may not work properly " -"if their initialization routine is called more than once; this can happen if " -"an application calls :c:func:`Py_Initialize` and :c:func:`Py_FinalizeEx` " -"more than once. :c:func:`Py_FinalizeEx` must not be called recursively from " -"within itself. Therefore, it must not be called by any code that may be run " -"as part of the interpreter shutdown process, such as :py:mod:`atexit` " -"handlers, object finalizers, or any code that may be run while flushing the " -"stdout and stderr files." -msgstr "" - -#: ../../c-api/init.rst:462 -msgid "" -"Raises an :ref:`auditing event ` ``cpython." -"_PySys_ClearAuditHooks`` with no arguments." -msgstr "" -"引發一個不附帶引數的\\ :ref:`稽核事件 ` ``cpython." -"_PySys_ClearAuditHooks``。" - -#: ../../c-api/init.rst:469 -msgid "" -"This is a backwards-compatible version of :c:func:`Py_FinalizeEx` that " -"disregards the return value." -msgstr "" - -#: ../../c-api/init.rst:475 -msgid "" -"Similar to :c:func:`Py_Main` but *argv* is an array of bytes strings, " -"allowing the calling application to delegate the text decoding step to the " -"CPython runtime." -msgstr "" - -#: ../../c-api/init.rst:484 -msgid "" -"The main program for the standard interpreter, encapsulating a full " -"initialization/finalization cycle, as well as additional behaviour to " -"implement reading configurations settings from the environment and command " -"line, and then executing ``__main__`` in accordance with :ref:`using-on-" -"cmdline`." -msgstr "" - -#: ../../c-api/init.rst:490 -msgid "" -"This is made available for programs which wish to support the full CPython " -"command line interface, rather than just embedding a Python runtime in a " -"larger application." -msgstr "" - -#: ../../c-api/init.rst:494 -msgid "" -"The *argc* and *argv* parameters are similar to those which are passed to a " -"C program's :c:func:`main` function, except that the *argv* entries are " -"first converted to ``wchar_t`` using :c:func:`Py_DecodeLocale`. It is also " -"important to note that the argument list entries may be modified to point to " -"strings other than those passed in (however, the contents of the strings " -"pointed to by the argument list are not modified)." -msgstr "" - -#: ../../c-api/init.rst:501 -msgid "" -"The return value is ``2`` if the argument list does not represent a valid " -"Python command line, and otherwise the same as :c:func:`Py_RunMain`." -msgstr "" - -#: ../../c-api/init.rst:504 -msgid "" -"In terms of the CPython runtime configuration APIs documented in the :ref:" -"`runtime configuration ` section (and without accounting for " -"error handling), ``Py_Main`` is approximately equivalent to::" -msgstr "" - -#: ../../c-api/init.rst:508 -msgid "" -"PyConfig config;\n" -"PyConfig_InitPythonConfig(&config);\n" -"PyConfig_SetArgv(&config, argc, argv);\n" -"Py_InitializeFromConfig(&config);\n" -"PyConfig_Clear(&config);\n" -"\n" -"Py_RunMain();" -msgstr "" - -#: ../../c-api/init.rst:516 -msgid "" -"In normal usage, an embedding application will call this function *instead* " -"of calling :c:func:`Py_Initialize`, :c:func:`Py_InitializeEx` or :c:func:" -"`Py_InitializeFromConfig` directly, and all settings will be applied as " -"described elsewhere in this documentation. If this function is instead " -"called *after* a preceding runtime initialization API call, then exactly " -"which environmental and command line configuration settings will be updated " -"is version dependent (as it depends on which settings correctly support " -"being modified after they have already been set once when the runtime was " -"first initialized)." -msgstr "" - -#: ../../c-api/init.rst:529 -msgid "Executes the main module in a fully configured CPython runtime." -msgstr "" - -#: ../../c-api/init.rst:531 -msgid "" -"Executes the command (:c:member:`PyConfig.run_command`), the script (:c:" -"member:`PyConfig.run_filename`) or the module (:c:member:`PyConfig." -"run_module`) specified on the command line or in the configuration. If none " -"of these values are set, runs the interactive Python prompt (REPL) using the " -"``__main__`` module's global namespace." -msgstr "" - -#: ../../c-api/init.rst:537 -msgid "" -"If :c:member:`PyConfig.inspect` is not set (the default), the return value " -"will be ``0`` if the interpreter exits normally (that is, without raising an " -"exception), the exit status of an unhandled :exc:`SystemExit`, or ``1`` for " -"any other unhandled exception." -msgstr "" - -#: ../../c-api/init.rst:542 -msgid "" -"If :c:member:`PyConfig.inspect` is set (such as when the :option:`-i` option " -"is used), rather than returning when the interpreter exits, execution will " -"instead resume in an interactive Python prompt (REPL) using the ``__main__`` " -"module's global namespace. If the interpreter exited with an exception, it " -"is immediately raised in the REPL session. The function return value is then " -"determined by the way the *REPL session* terminates: ``0``, ``1``, or the " -"status of a :exc:`SystemExit`, as specified above." -msgstr "" - -#: ../../c-api/init.rst:550 -msgid "" -"This function always finalizes the Python interpreter before it returns." -msgstr "" - -#: ../../c-api/init.rst:552 -msgid "" -"See :ref:`Python Configuration ` for an example of a " -"customized Python that always runs in isolated mode using :c:func:" -"`Py_RunMain`." -msgstr "" - -#: ../../c-api/init.rst:558 -msgid "" -"Register an :mod:`atexit` callback for the target interpreter *interp*. This " -"is similar to :c:func:`Py_AtExit`, but takes an explicit interpreter and " -"data pointer for the callback." -msgstr "" - -#: ../../c-api/init.rst:562 -msgid "There must be an :term:`attached thread state` for *interp*." -msgstr "" - -#: ../../c-api/init.rst:567 -msgid "Process-wide parameters" -msgstr "" - -#: ../../c-api/init.rst:577 -msgid "" -"This API is kept for backward compatibility: setting :c:member:`PyConfig." -"program_name` should be used instead, see :ref:`Python Initialization " -"Configuration `." -msgstr "" - -#: ../../c-api/init.rst:581 -msgid "" -"This function should be called before :c:func:`Py_Initialize` is called for " -"the first time, if it is called at all. It tells the interpreter the value " -"of the ``argv[0]`` argument to the :c:func:`main` function of the program " -"(converted to wide characters). This is used by :c:func:`Py_GetPath` and " -"some other functions below to find the Python run-time libraries relative to " -"the interpreter executable. The default value is ``'python'``. The " -"argument should point to a zero-terminated wide character string in static " -"storage whose contents will not change for the duration of the program's " -"execution. No code in the Python interpreter will change the contents of " -"this storage." -msgstr "" - -#: ../../c-api/init.rst:592 ../../c-api/init.rst:840 ../../c-api/init.rst:876 -#: ../../c-api/init.rst:902 -msgid "" -"Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a :c:expr:" -"`wchar_t*` string." -msgstr "" - -#: ../../c-api/init.rst:600 -msgid "" -"Return the program name set with :c:member:`PyConfig.program_name`, or the " -"default. The returned string points into static storage; the caller should " -"not modify its value." -msgstr "" - -#: ../../c-api/init.rst:604 ../../c-api/init.rst:627 ../../c-api/init.rst:675 -#: ../../c-api/init.rst:699 ../../c-api/init.rst:726 ../../c-api/init.rst:914 -msgid "" -"This function should not be called before :c:func:`Py_Initialize`, otherwise " -"it returns ``NULL``." -msgstr "此函式不應該在 :c:func:`Py_Initialize` 之前呼叫，否則會回傳 ``NULL``。" - -#: ../../c-api/init.rst:607 ../../c-api/init.rst:630 ../../c-api/init.rst:678 -#: ../../c-api/init.rst:702 ../../c-api/init.rst:731 ../../c-api/init.rst:917 -msgid "It now returns ``NULL`` if called before :c:func:`Py_Initialize`." -msgstr "如果在 :c:func:`Py_Initialize` 之前呼叫，現在會回傳 ``NULL``。" - -#: ../../c-api/init.rst:610 ../../c-api/init.rst:705 -msgid "" -"Use :c:func:`PyConfig_Get(\"executable\") ` (:data:`sys." -"executable`) instead." -msgstr "" - -#: ../../c-api/init.rst:617 -msgid "" -"Return the *prefix* for installed platform-independent files. This is " -"derived through a number of complicated rules from the program name set " -"with :c:member:`PyConfig.program_name` and some environment variables; for " -"example, if the program name is ``'/usr/local/bin/python'``, the prefix is " -"``'/usr/local'``. The returned string points into static storage; the caller " -"should not modify its value. This corresponds to the :makevar:`prefix` " -"variable in the top-level :file:`Makefile` and the :option:`--prefix` " -"argument to the :program:`configure` script at build time. The value is " -"available to Python code as ``sys.base_prefix``. It is only useful on Unix. " -"See also the next function." -msgstr "" - -#: ../../c-api/init.rst:633 -msgid "" -"Use :c:func:`PyConfig_Get(\"base_prefix\") ` (:data:`sys." -"base_prefix`) instead. Use :c:func:`PyConfig_Get(\"prefix\") ` " -"(:data:`sys.prefix`) if :ref:`virtual environments ` need to be " -"handled." -msgstr "" - -#: ../../c-api/init.rst:642 -msgid "" -"Return the *exec-prefix* for installed platform-*dependent* files. This is " -"derived through a number of complicated rules from the program name set " -"with :c:member:`PyConfig.program_name` and some environment variables; for " -"example, if the program name is ``'/usr/local/bin/python'``, the exec-prefix " -"is ``'/usr/local'``. The returned string points into static storage; the " -"caller should not modify its value. This corresponds to the :makevar:" -"`exec_prefix` variable in the top-level :file:`Makefile` and the ``--exec-" -"prefix`` argument to the :program:`configure` script at build time. The " -"value is available to Python code as ``sys.base_exec_prefix``. It is only " -"useful on Unix." -msgstr "" - -#: ../../c-api/init.rst:653 -msgid "" -"Background: The exec-prefix differs from the prefix when platform dependent " -"files (such as executables and shared libraries) are installed in a " -"different directory tree. In a typical installation, platform dependent " -"files may be installed in the :file:`/usr/local/plat` subtree while platform " -"independent may be installed in :file:`/usr/local`." -msgstr "" - -#: ../../c-api/init.rst:659 -msgid "" -"Generally speaking, a platform is a combination of hardware and software " -"families, e.g. Sparc machines running the Solaris 2.x operating system are " -"considered the same platform, but Intel machines running Solaris 2.x are " -"another platform, and Intel machines running Linux are yet another " -"platform. Different major revisions of the same operating system generally " -"also form different platforms. Non-Unix operating systems are a different " -"story; the installation strategies on those systems are so different that " -"the prefix and exec-prefix are meaningless, and set to the empty string. " -"Note that compiled Python bytecode files are platform independent (but not " -"independent from the Python version by which they were compiled!)." -msgstr "" - -#: ../../c-api/init.rst:670 -msgid "" -"System administrators will know how to configure the :program:`mount` or :" -"program:`automount` programs to share :file:`/usr/local` between platforms " -"while having :file:`/usr/local/plat` be a different filesystem for each " -"platform." -msgstr "" - -#: ../../c-api/init.rst:681 -msgid "" -"Use :c:func:`PyConfig_Get(\"base_exec_prefix\") ` (:data:`sys." -"base_exec_prefix`) instead. Use :c:func:`PyConfig_Get(\"exec_prefix\") " -"` (:data:`sys.exec_prefix`) if :ref:`virtual environments " -"` need to be handled." -msgstr "" - -#: ../../c-api/init.rst:693 -msgid "" -"Return the full program name of the Python executable; this is computed as " -"a side-effect of deriving the default module search path from the program " -"name (set by :c:member:`PyConfig.program_name`). The returned string points " -"into static storage; the caller should not modify its value. The value is " -"available to Python code as ``sys.executable``." -msgstr "" - -#: ../../c-api/init.rst:716 -msgid "" -"Return the default module search path; this is computed from the program " -"name (set by :c:member:`PyConfig.program_name`) and some environment " -"variables. The returned string consists of a series of directory names " -"separated by a platform dependent delimiter character. The delimiter " -"character is ``':'`` on Unix and macOS, ``';'`` on Windows. The returned " -"string points into static storage; the caller should not modify its value. " -"The list :data:`sys.path` is initialized with this value on interpreter " -"startup; it can be (and usually is) modified later to change the search path " -"for loading modules." -msgstr "" - -#: ../../c-api/init.rst:734 -msgid "" -"Use :c:func:`PyConfig_Get(\"module_search_paths\") ` (:data:" -"`sys.path`) instead." -msgstr "" - -#: ../../c-api/init.rst:740 -msgid "" -"Return the version of this Python interpreter. This is a string that looks " -"something like ::" -msgstr "" - -#: ../../c-api/init.rst:743 -msgid "\"3.0a5+ (py3k:63103M, May 12 2008, 00:53:55) \\n[GCC 4.2.3]\"" -msgstr "\"3.0a5+ (py3k:63103M, May 12 2008, 00:53:55) \\n[GCC 4.2.3]\"" - -#: ../../c-api/init.rst:747 -msgid "" -"The first word (up to the first space character) is the current Python " -"version; the first characters are the major and minor version separated by a " -"period. The returned string points into static storage; the caller should " -"not modify its value. The value is available to Python code as :data:`sys." -"version`." -msgstr "" - -#: ../../c-api/init.rst:752 -msgid "See also the :c:var:`Py_Version` constant." -msgstr "另請參閱 :c:var:`Py_Version` 常數。" - -#: ../../c-api/init.rst:759 -msgid "" -"Return the platform identifier for the current platform. On Unix, this is " -"formed from the \"official\" name of the operating system, converted to " -"lower case, followed by the major revision number; e.g., for Solaris 2.x, " -"which is also known as SunOS 5.x, the value is ``'sunos5'``. On macOS, it " -"is ``'darwin'``. On Windows, it is ``'win'``. The returned string points " -"into static storage; the caller should not modify its value. The value is " -"available to Python code as ``sys.platform``." -msgstr "" - -#: ../../c-api/init.rst:770 -msgid "" -"Return the official copyright string for the current Python version, for " -"example" -msgstr "" - -#: ../../c-api/init.rst:772 -msgid "``'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam'``" -msgstr "``'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam'``" - -#: ../../c-api/init.rst:776 -msgid "" -"The returned string points into static storage; the caller should not modify " -"its value. The value is available to Python code as ``sys.copyright``." -msgstr "" - -#: ../../c-api/init.rst:782 -msgid "" -"Return an indication of the compiler used to build the current Python " -"version, in square brackets, for example::" -msgstr "" - -#: ../../c-api/init.rst:785 -msgid "\"[GCC 2.7.2.2]\"" -msgstr "\"[GCC 2.7.2.2]\"" - -#: ../../c-api/init.rst:789 ../../c-api/init.rst:803 -msgid "" -"The returned string points into static storage; the caller should not modify " -"its value. The value is available to Python code as part of the variable " -"``sys.version``." -msgstr "" - -#: ../../c-api/init.rst:796 -msgid "" -"Return information about the sequence number and build date and time of the " -"current Python interpreter instance, for example ::" -msgstr "" - -#: ../../c-api/init.rst:799 -msgid "\"#67, Aug 1 1997, 22:34:28\"" -msgstr "\"#67, Aug 1 1997, 22:34:28\"" - -#: ../../c-api/init.rst:815 -msgid "" -"This API is kept for backward compatibility: setting :c:member:`PyConfig." -"argv`, :c:member:`PyConfig.parse_argv` and :c:member:`PyConfig.safe_path` " -"should be used instead, see :ref:`Python Initialization Configuration `." -msgstr "" - -#: ../../c-api/init.rst:820 -msgid "" -"Set :data:`sys.argv` based on *argc* and *argv*. These parameters are " -"similar to those passed to the program's :c:func:`main` function with the " -"difference that the first entry should refer to the script file to be " -"executed rather than the executable hosting the Python interpreter. If " -"there isn't a script that will be run, the first entry in *argv* can be an " -"empty string. If this function fails to initialize :data:`sys.argv`, a " -"fatal condition is signalled using :c:func:`Py_FatalError`." -msgstr "" - -#: ../../c-api/init.rst:828 -msgid "" -"If *updatepath* is zero, this is all the function does. If *updatepath* is " -"non-zero, the function also modifies :data:`sys.path` according to the " -"following algorithm:" -msgstr "" - -#: ../../c-api/init.rst:832 -msgid "" -"If the name of an existing script is passed in ``argv[0]``, the absolute " -"path of the directory where the script is located is prepended to :data:`sys." -"path`." -msgstr "" - -#: ../../c-api/init.rst:835 -msgid "" -"Otherwise (that is, if *argc* is ``0`` or ``argv[0]`` doesn't point to an " -"existing file name), an empty string is prepended to :data:`sys.path`, which " -"is the same as prepending the current working directory (``\".\"``)." -msgstr "" - -#: ../../c-api/init.rst:843 ../../c-api/init.rst:879 -msgid "" -"See also :c:member:`PyConfig.orig_argv` and :c:member:`PyConfig.argv` " -"members of the :ref:`Python Initialization Configuration `." -msgstr "" - -#: ../../c-api/init.rst:847 -msgid "" -"It is recommended that applications embedding the Python interpreter for " -"purposes other than executing a single script pass ``0`` as *updatepath*, " -"and update :data:`sys.path` themselves if desired. See :cve:`2008-5983`." -msgstr "" - -#: ../../c-api/init.rst:852 -msgid "" -"On versions before 3.1.3, you can achieve the same effect by manually " -"popping the first :data:`sys.path` element after having called :c:func:" -"`PySys_SetArgv`, for example using::" -msgstr "" - -#: ../../c-api/init.rst:856 -msgid "PyRun_SimpleString(\"import sys; sys.path.pop(0)\\n\");" -msgstr "PyRun_SimpleString(\"import sys; sys.path.pop(0)\\n\");" - -#: ../../c-api/init.rst:868 -msgid "" -"This API is kept for backward compatibility: setting :c:member:`PyConfig." -"argv` and :c:member:`PyConfig.parse_argv` should be used instead, see :ref:" -"`Python Initialization Configuration `." -msgstr "" - -#: ../../c-api/init.rst:872 -msgid "" -"This function works like :c:func:`PySys_SetArgvEx` with *updatepath* set to " -"``1`` unless the :program:`python` interpreter was started with the :option:" -"`-I`." -msgstr "" - -#: ../../c-api/init.rst:882 -msgid "The *updatepath* value depends on :option:`-I`." -msgstr "" - -#: ../../c-api/init.rst:889 -msgid "" -"This API is kept for backward compatibility: setting :c:member:`PyConfig." -"home` should be used instead, see :ref:`Python Initialization Configuration " -"`." -msgstr "" - -#: ../../c-api/init.rst:893 -msgid "" -"Set the default \"home\" directory, that is, the location of the standard " -"Python libraries. See :envvar:`PYTHONHOME` for the meaning of the argument " -"string." -msgstr "" - -#: ../../c-api/init.rst:897 -msgid "" -"The argument should point to a zero-terminated character string in static " -"storage whose contents will not change for the duration of the program's " -"execution. No code in the Python interpreter will change the contents of " -"this storage." -msgstr "" - -#: ../../c-api/init.rst:910 -msgid "" -"Return the default \"home\", that is, the value set by :c:member:`PyConfig." -"home`, or the value of the :envvar:`PYTHONHOME` environment variable if it " -"is set." -msgstr "" - -#: ../../c-api/init.rst:920 -msgid "" -"Use :c:func:`PyConfig_Get(\"home\") ` or the :envvar:" -"`PYTHONHOME` environment variable instead." -msgstr "" -"改為使用 :c:func:`PyConfig_Get(\"home\") ` 或 :envvar:" -"`PYTHONHOME` 環境變數。" - -#: ../../c-api/init.rst:928 -msgid "Thread State and the Global Interpreter Lock" -msgstr "" - -#: ../../c-api/init.rst:935 -msgid "" -"Unless on a :term:`free-threaded ` build of :term:`CPython`, " -"the Python interpreter is not fully thread-safe. In order to support multi-" -"threaded Python programs, there's a global lock, called the :term:`global " -"interpreter lock` or :term:`GIL`, that must be held by the current thread " -"before it can safely access Python objects. Without the lock, even the " -"simplest operations could cause problems in a multi-threaded program: for " -"example, when two threads simultaneously increment the reference count of " -"the same object, the reference count could end up being incremented only " -"once instead of twice." -msgstr "" - -#: ../../c-api/init.rst:946 -msgid "" -"Therefore, the rule exists that only the thread that has acquired the :term:" -"`GIL` may operate on Python objects or call Python/C API functions. In order " -"to emulate concurrency of execution, the interpreter regularly tries to " -"switch threads (see :func:`sys.setswitchinterval`). The lock is also " -"released around potentially blocking I/O operations like reading or writing " -"a file, so that other Python threads can run in the meantime." -msgstr "" - -#: ../../c-api/init.rst:956 -msgid "" -"The Python interpreter keeps some thread-specific bookkeeping information " -"inside a data structure called :c:type:`PyThreadState`, known as a :term:" -"`thread state`. Each OS thread has a thread-local pointer to a :c:type:" -"`PyThreadState`; a thread state referenced by this pointer is considered to " -"be :term:`attached `." -msgstr "" - -#: ../../c-api/init.rst:961 -msgid "" -"A thread can only have one :term:`attached thread state` at a time. An " -"attached thread state is typically analogous with holding the :term:`GIL`, " -"except on :term:`free-threaded ` builds. On builds with " -"the :term:`GIL` enabled, :term:`attaching ` a thread " -"state will block until the :term:`GIL` can be acquired. However, even on " -"builds with the :term:`GIL` disabled, it is still required to have an " -"attached thread state to call most of the C API." -msgstr "" - -#: ../../c-api/init.rst:968 -msgid "" -"In general, there will always be an :term:`attached thread state` when using " -"Python's C API. Only in some specific cases (such as in a :c:macro:" -"`Py_BEGIN_ALLOW_THREADS` block) will the thread not have an attached thread " -"state. If uncertain, check if :c:func:`PyThreadState_GetUnchecked` returns " -"``NULL``." -msgstr "" - -#: ../../c-api/init.rst:974 -msgid "Detaching the thread state from extension code" -msgstr "" - -#: ../../c-api/init.rst:976 -msgid "" -"Most extension code manipulating the :term:`thread state` has the following " -"simple structure::" -msgstr "" - -#: ../../c-api/init.rst:979 -msgid "" -"Save the thread state in a local variable.\n" -"... Do some blocking I/O operation ...\n" -"Restore the thread state from the local variable." -msgstr "" - -#: ../../c-api/init.rst:983 -msgid "This is so common that a pair of macros exists to simplify it::" -msgstr "" - -#: ../../c-api/init.rst:985 -msgid "" -"Py_BEGIN_ALLOW_THREADS\n" -"... Do some blocking I/O operation ...\n" -"Py_END_ALLOW_THREADS" -msgstr "" - -#: ../../c-api/init.rst:993 -msgid "" -"The :c:macro:`Py_BEGIN_ALLOW_THREADS` macro opens a new block and declares a " -"hidden local variable; the :c:macro:`Py_END_ALLOW_THREADS` macro closes the " -"block." -msgstr "" - -#: ../../c-api/init.rst:997 -msgid "The block above expands to the following code::" -msgstr "" - -#: ../../c-api/init.rst:999 -msgid "" -"PyThreadState *_save;\n" -"\n" -"_save = PyEval_SaveThread();\n" -"... Do some blocking I/O operation ...\n" -"PyEval_RestoreThread(_save);" -msgstr "" - -#: ../../c-api/init.rst:1009 -msgid "Here is how these functions work:" -msgstr "" - -#: ../../c-api/init.rst:1011 -msgid "" -"The :term:`attached thread state` holds the :term:`GIL` for the entire " -"interpreter. When detaching the :term:`attached thread state`, the :term:" -"`GIL` is released, allowing other threads to attach a thread state to their " -"own thread, thus getting the :term:`GIL` and can start executing. The " -"pointer to the prior :term:`attached thread state` is stored as a local " -"variable. Upon reaching :c:macro:`Py_END_ALLOW_THREADS`, the thread state " -"that was previously :term:`attached ` is passed to :c:" -"func:`PyEval_RestoreThread`. This function will block until another releases " -"its :term:`thread state `, thus allowing the old :" -"term:`thread state ` to get re-attached and the C API " -"can be called again." -msgstr "" - -#: ../../c-api/init.rst:1021 -msgid "" -"For :term:`free-threaded ` builds, the :term:`GIL` is " -"normally out of the question, but detaching the :term:`thread state " -"` is still required for blocking I/O and long " -"operations. The difference is that threads don't have to wait for the :term:" -"`GIL` to be released to attach their thread state, allowing true multi-core " -"parallelism." -msgstr "" - -#: ../../c-api/init.rst:1027 -msgid "" -"Calling system I/O functions is the most common use case for detaching the :" -"term:`thread state `, but it can also be useful " -"before calling long-running computations which don't need access to Python " -"objects, such as compression or cryptographic functions operating over " -"memory buffers. For example, the standard :mod:`zlib` and :mod:`hashlib` " -"modules detach the :term:`thread state ` when " -"compressing or hashing data." -msgstr "" - -#: ../../c-api/init.rst:1038 -msgid "Non-Python created threads" -msgstr "" - -#: ../../c-api/init.rst:1040 -msgid "" -"When threads are created using the dedicated Python APIs (such as the :mod:" -"`threading` module), a thread state is automatically associated to them and " -"the code showed above is therefore correct. However, when threads are " -"created from C (for example by a third-party library with its own thread " -"management), they don't hold the :term:`GIL`, because they don't have an :" -"term:`attached thread state`." -msgstr "" - -#: ../../c-api/init.rst:1047 -msgid "" -"If you need to call Python code from these threads (often this will be part " -"of a callback API provided by the aforementioned third-party library), you " -"must first register these threads with the interpreter by creating an :term:" -"`attached thread state` before you can start using the Python/C API. When " -"you are done, you should detach the :term:`thread state `, and finally free it." -msgstr "" - -#: ../../c-api/init.rst:1054 -msgid "" -"The :c:func:`PyGILState_Ensure` and :c:func:`PyGILState_Release` functions " -"do all of the above automatically. The typical idiom for calling into " -"Python from a C thread is::" -msgstr "" - -#: ../../c-api/init.rst:1058 -msgid "" -"PyGILState_STATE gstate;\n" -"gstate = PyGILState_Ensure();\n" -"\n" -"/* Perform Python actions here. */\n" -"result = CallSomeFunction();\n" -"/* evaluate result or handle exception */\n" -"\n" -"/* Release the thread. No Python API allowed beyond this point. */\n" -"PyGILState_Release(gstate);" -msgstr "" - -#: ../../c-api/init.rst:1068 -msgid "" -"Note that the ``PyGILState_*`` functions assume there is only one global " -"interpreter (created automatically by :c:func:`Py_Initialize`). Python " -"supports the creation of additional interpreters (using :c:func:" -"`Py_NewInterpreter`), but mixing multiple interpreters and the " -"``PyGILState_*`` API is unsupported. This is because :c:func:" -"`PyGILState_Ensure` and similar functions default to :term:`attaching " -"` a :term:`thread state` for the main interpreter, " -"meaning that the thread can't safely interact with the calling " -"subinterpreter." -msgstr "" - -#: ../../c-api/init.rst:1078 -msgid "Supporting subinterpreters in non-Python threads" -msgstr "" - -#: ../../c-api/init.rst:1080 -msgid "" -"If you would like to support subinterpreters with non-Python created " -"threads, you must use the ``PyThreadState_*`` API instead of the traditional " -"``PyGILState_*`` API." -msgstr "" - -#: ../../c-api/init.rst:1084 -msgid "" -"In particular, you must store the interpreter state from the calling " -"function and pass it to :c:func:`PyThreadState_New`, which will ensure that " -"the :term:`thread state` is targeting the correct interpreter::" -msgstr "" - -#: ../../c-api/init.rst:1088 -msgid "" -"/* The return value of PyInterpreterState_Get() from the\n" -" function that created this thread. */\n" -"PyInterpreterState *interp = ThreadData->interp;\n" -"PyThreadState *tstate = PyThreadState_New(interp);\n" -"PyThreadState_Swap(tstate);\n" -"\n" -"/* GIL of the subinterpreter is now held.\n" -" Perform Python actions here. */\n" -"result = CallSomeFunction();\n" -"/* evaluate result or handle exception */\n" -"\n" -"/* Destroy the thread state. No Python API allowed beyond this point. */\n" -"PyThreadState_Clear(tstate);\n" -"PyThreadState_DeleteCurrent();" -msgstr "" - -#: ../../c-api/init.rst:1106 -msgid "Cautions about fork()" -msgstr "" - -#: ../../c-api/init.rst:1108 -msgid "" -"Another important thing to note about threads is their behaviour in the face " -"of the C :c:func:`fork` call. On most systems with :c:func:`fork`, after a " -"process forks only the thread that issued the fork will exist. This has a " -"concrete impact both on how locks must be handled and on all stored state in " -"CPython's runtime." -msgstr "" - -#: ../../c-api/init.rst:1114 -msgid "" -"The fact that only the \"current\" thread remains means any locks held by " -"other threads will never be released. Python solves this for :func:`os.fork` " -"by acquiring the locks it uses internally before the fork, and releasing " -"them afterwards. In addition, it resets any :ref:`lock-objects` in the " -"child. When extending or embedding Python, there is no way to inform Python " -"of additional (non-Python) locks that need to be acquired before or reset " -"after a fork. OS facilities such as :c:func:`!pthread_atfork` would need to " -"be used to accomplish the same thing. Additionally, when extending or " -"embedding Python, calling :c:func:`fork` directly rather than through :func:" -"`os.fork` (and returning to or calling into Python) may result in a deadlock " -"by one of Python's internal locks being held by a thread that is defunct " -"after the fork. :c:func:`PyOS_AfterFork_Child` tries to reset the necessary " -"locks, but is not always able to." -msgstr "" - -#: ../../c-api/init.rst:1129 -msgid "" -"The fact that all other threads go away also means that CPython's runtime " -"state there must be cleaned up properly, which :func:`os.fork` does. This " -"means finalizing all other :c:type:`PyThreadState` objects belonging to the " -"current interpreter and all other :c:type:`PyInterpreterState` objects. Due " -"to this and the special nature of the :ref:`\"main\" interpreter `, :c:func:`fork` should only be called in that " -"interpreter's \"main\" thread, where the CPython global runtime was " -"originally initialized. The only exception is if :c:func:`exec` will be " -"called immediately after." -msgstr "" - -#: ../../c-api/init.rst:1143 -msgid "Cautions regarding runtime finalization" -msgstr "" - -#: ../../c-api/init.rst:1145 -msgid "" -"In the late stage of :term:`interpreter shutdown`, after attempting to wait " -"for non-daemon threads to exit (though this can be interrupted by :class:" -"`KeyboardInterrupt`) and running the :mod:`atexit` functions, the runtime is " -"marked as *finalizing*: :c:func:`Py_IsFinalizing` and :func:`sys." -"is_finalizing` return true. At this point, only the *finalization thread* " -"that initiated finalization (typically the main thread) is allowed to " -"acquire the :term:`GIL`." -msgstr "" - -#: ../../c-api/init.rst:1153 -msgid "" -"If any thread, other than the finalization thread, attempts to attach a :" -"term:`thread state` during finalization, either explicitly or implicitly, " -"the thread enters **a permanently blocked state** where it remains until the " -"program exits. In most cases this is harmless, but this can result in " -"deadlock if a later stage of finalization attempts to acquire a lock owned " -"by the blocked thread, or otherwise waits on the blocked thread." -msgstr "" - -#: ../../c-api/init.rst:1160 -msgid "" -"Gross? Yes. This prevents random crashes and/or unexpectedly skipped C++ " -"finalizations further up the call stack when such threads were forcibly " -"exited here in CPython 3.13 and earlier. The CPython runtime :term:`thread " -"state` C APIs have never had any error reporting or handling expectations " -"at :term:`thread state` attachment time that would've allowed for graceful " -"exit from this situation. Changing that would require new stable C APIs and " -"rewriting the majority of C code in the CPython ecosystem to use those with " -"error handling." -msgstr "" - -#: ../../c-api/init.rst:1170 -msgid "High-level API" -msgstr "高階 API" - -#: ../../c-api/init.rst:1172 -msgid "" -"These are the most commonly used types and functions when writing C " -"extension code, or when embedding the Python interpreter:" -msgstr "" - -#: ../../c-api/init.rst:1177 -msgid "" -"This data structure represents the state shared by a number of cooperating " -"threads. Threads belonging to the same interpreter share their module " -"administration and a few other internal items. There are no public members " -"in this structure." -msgstr "" - -#: ../../c-api/init.rst:1182 -msgid "" -"Threads belonging to different interpreters initially share nothing, except " -"process state like available memory, open file descriptors and such. The " -"global interpreter lock is also shared by all threads, regardless of to " -"which interpreter they belong." -msgstr "" - -#: ../../c-api/init.rst:1189 -msgid "" -":pep:`684` introduced the possibility of a :ref:`per-interpreter GIL `. See :c:func:`Py_NewInterpreterFromConfig`." -msgstr "" - -#: ../../c-api/init.rst:1196 -msgid "" -"This data structure represents the state of a single thread. The only " -"public data member is:" -msgstr "" - -#: ../../c-api/init.rst:1201 -msgid "This thread's interpreter state." -msgstr "" - -#: ../../c-api/init.rst:1212 -msgid "Deprecated function which does nothing." -msgstr "" - -#: ../../c-api/init.rst:1214 -msgid "" -"In Python 3.6 and older, this function created the GIL if it didn't exist." -msgstr "" - -#: ../../c-api/init.rst:1216 -msgid "The function now does nothing." -msgstr "此函式現在不會做任何事情。" - -#: ../../c-api/init.rst:1219 -msgid "" -"This function is now called by :c:func:`Py_Initialize()`, so you don't have " -"to call it yourself anymore." -msgstr "" - -#: ../../c-api/init.rst:1223 -msgid "" -"This function cannot be called before :c:func:`Py_Initialize()` anymore." -msgstr "" - -#: ../../c-api/init.rst:1233 -msgid "" -"Detach the :term:`attached thread state` and return it. The thread will have " -"no :term:`thread state` upon returning." -msgstr "" - -#: ../../c-api/init.rst:1239 -msgid "" -"Set the :term:`attached thread state` to *tstate*. The passed :term:`thread " -"state` **should not** be :term:`attached `, otherwise " -"deadlock ensues. *tstate* will be attached upon returning." -msgstr "" - -#: ../../c-api/init.rst:1244 ../../c-api/init.rst:1688 -msgid "" -"Calling this function from a thread when the runtime is finalizing will hang " -"the thread until the program exits, even if the thread was not created by " -"Python. Refer to :ref:`cautions-regarding-runtime-finalization` for more " -"details." -msgstr "" - -#: ../../c-api/init.rst:1249 ../../c-api/init.rst:1333 -#: ../../c-api/init.rst:1698 -msgid "" -"Hangs the current thread, rather than terminating it, if called while the " -"interpreter is finalizing." -msgstr "" - -#: ../../c-api/init.rst:1255 -msgid "" -"Return the :term:`attached thread state`. If the thread has no attached " -"thread state, (such as when inside of :c:macro:`Py_BEGIN_ALLOW_THREADS` " -"block), then this issues a fatal error (so that the caller needn't check for " -"``NULL``)." -msgstr "" - -#: ../../c-api/init.rst:1260 -msgid "See also :c:func:`PyThreadState_GetUnchecked`." -msgstr "也請見 :c:func:`PyThreadState_GetUnchecked`。" - -#: ../../c-api/init.rst:1264 -msgid "" -"Similar to :c:func:`PyThreadState_Get`, but don't kill the process with a " -"fatal error if it is NULL. The caller is responsible to check if the result " -"is NULL." -msgstr "" - -#: ../../c-api/init.rst:1268 -msgid "" -"In Python 3.5 to 3.12, the function was private and known as " -"``_PyThreadState_UncheckedGet()``." -msgstr "" - -#: ../../c-api/init.rst:1275 -msgid "" -"Set the :term:`attached thread state` to *tstate*, and return the :term:" -"`thread state` that was attached prior to calling." -msgstr "" - -#: ../../c-api/init.rst:1278 -msgid "" -"This function is safe to call without an :term:`attached thread state`; it " -"will simply return ``NULL`` indicating that there was no prior thread state." -msgstr "" - -#: ../../c-api/init.rst:1282 -msgid ":c:func:`PyEval_ReleaseThread`" -msgstr ":c:func:`PyEval_ReleaseThread`" - -#: ../../c-api/init.rst:1285 -msgid "" -"Similar to :c:func:`PyGILState_Ensure`, this function will hang the thread " -"if the runtime is finalizing." -msgstr "" - -#: ../../c-api/init.rst:1289 -msgid "" -"The following functions use thread-local storage, and are not compatible " -"with sub-interpreters:" -msgstr "" - -#: ../../c-api/init.rst:1294 -msgid "" -"The type of the value returned by :c:func:`PyGILState_Ensure` and passed to :" -"c:func:`PyGILState_Release`." -msgstr "" - -#: ../../c-api/init.rst:1299 -msgid "The GIL was already held when :c:func:`PyGILState_Ensure` was called." -msgstr "" - -#: ../../c-api/init.rst:1303 -msgid "The GIL was not held when :c:func:`PyGILState_Ensure` was called." -msgstr "" - -#: ../../c-api/init.rst:1307 -msgid "" -"Ensure that the current thread is ready to call the Python C API regardless " -"of the current state of Python, or of the :term:`attached thread state`. " -"This may be called as many times as desired by a thread as long as each call " -"is matched with a call to :c:func:`PyGILState_Release`. In general, other " -"thread-related APIs may be used between :c:func:`PyGILState_Ensure` and :c:" -"func:`PyGILState_Release` calls as long as the thread state is restored to " -"its previous state before the Release(). For example, normal usage of the :" -"c:macro:`Py_BEGIN_ALLOW_THREADS` and :c:macro:`Py_END_ALLOW_THREADS` macros " -"is acceptable." -msgstr "" - -#: ../../c-api/init.rst:1317 -msgid "" -"The return value is an opaque \"handle\" to the :term:`attached thread " -"state` when :c:func:`PyGILState_Ensure` was called, and must be passed to :c:" -"func:`PyGILState_Release` to ensure Python is left in the same state. Even " -"though recursive calls are allowed, these handles *cannot* be shared - each " -"unique call to :c:func:`PyGILState_Ensure` must save the handle for its call " -"to :c:func:`PyGILState_Release`." -msgstr "" - -#: ../../c-api/init.rst:1324 -msgid "" -"When the function returns, there will be an :term:`attached thread state` " -"and the thread will be able to call arbitrary Python code. Failure is a " -"fatal error." -msgstr "" - -#: ../../c-api/init.rst:1328 -msgid "" -"Calling this function when the runtime is finalizing is unsafe. Doing so " -"will either hang the thread until the program ends, or fully crash the " -"interpreter in rare cases. Refer to :ref:`cautions-regarding-runtime-" -"finalization` for more details." -msgstr "" - -#: ../../c-api/init.rst:1339 -msgid "" -"Release any resources previously acquired. After this call, Python's state " -"will be the same as it was prior to the corresponding :c:func:" -"`PyGILState_Ensure` call (but generally this state will be unknown to the " -"caller, hence the use of the GILState API)." -msgstr "" - -#: ../../c-api/init.rst:1344 -msgid "" -"Every call to :c:func:`PyGILState_Ensure` must be matched by a call to :c:" -"func:`PyGILState_Release` on the same thread." -msgstr "" - -#: ../../c-api/init.rst:1349 -msgid "" -"Get the :term:`attached thread state` for this thread. May return ``NULL`` " -"if no GILState API has been used on the current thread. Note that the main " -"thread always has such a thread-state, even if no auto-thread-state call has " -"been made on the main thread. This is mainly a helper/diagnostic function." -msgstr "" - -#: ../../c-api/init.rst:1355 -msgid "" -"This function may return non-``NULL`` even when the :term:`thread state` is " -"detached. Prefer :c:func:`PyThreadState_Get` or :c:func:" -"`PyThreadState_GetUnchecked` for most cases." -msgstr "" - -#: ../../c-api/init.rst:1360 -msgid ":c:func:`PyThreadState_Get`" -msgstr ":c:func:`PyThreadState_Get`" - -#: ../../c-api/init.rst:1364 -msgid "" -"Return ``1`` if the current thread is holding the :term:`GIL` and ``0`` " -"otherwise. This function can be called from any thread at any time. Only if " -"it has had its :term:`thread state ` initialized via :" -"c:func:`PyGILState_Ensure` will it return ``1``. This is mainly a helper/" -"diagnostic function. It can be useful for example in callback contexts or " -"memory allocation functions when knowing that the :term:`GIL` is locked can " -"allow the caller to perform sensitive actions or otherwise behave " -"differently." -msgstr "" - -#: ../../c-api/init.rst:1374 -msgid "" -"If the current Python process has ever created a subinterpreter, this " -"function will *always* return ``1``. Prefer :c:func:" -"`PyThreadState_GetUnchecked` for most cases." -msgstr "" - -#: ../../c-api/init.rst:1381 -msgid "" -"The following macros are normally used without a trailing semicolon; look " -"for example usage in the Python source distribution." -msgstr "" - -#: ../../c-api/init.rst:1387 -msgid "" -"This macro expands to ``{ PyThreadState *_save; _save = PyEval_SaveThread();" -"``. Note that it contains an opening brace; it must be matched with a " -"following :c:macro:`Py_END_ALLOW_THREADS` macro. See above for further " -"discussion of this macro." -msgstr "" - -#: ../../c-api/init.rst:1395 -msgid "" -"This macro expands to ``PyEval_RestoreThread(_save); }``. Note that it " -"contains a closing brace; it must be matched with an earlier :c:macro:" -"`Py_BEGIN_ALLOW_THREADS` macro. See above for further discussion of this " -"macro." -msgstr "" - -#: ../../c-api/init.rst:1403 -msgid "" -"This macro expands to ``PyEval_RestoreThread(_save);``: it is equivalent to :" -"c:macro:`Py_END_ALLOW_THREADS` without the closing brace." -msgstr "" - -#: ../../c-api/init.rst:1409 -msgid "" -"This macro expands to ``_save = PyEval_SaveThread();``: it is equivalent to :" -"c:macro:`Py_BEGIN_ALLOW_THREADS` without the opening brace and variable " -"declaration." -msgstr "" - -#: ../../c-api/init.rst:1415 -msgid "Low-level API" -msgstr "低階 API" - -#: ../../c-api/init.rst:1417 -msgid "" -"All of the following functions must be called after :c:func:`Py_Initialize`." -msgstr "" - -#: ../../c-api/init.rst:1419 -msgid "" -":c:func:`Py_Initialize()` now initializes the :term:`GIL` and sets an :term:" -"`attached thread state`." -msgstr "" - -#: ../../c-api/init.rst:1426 -msgid "" -"Create a new interpreter state object. An :term:`attached thread state` is " -"not needed, but may optionally exist if it is necessary to serialize calls " -"to this function." -msgstr "" - -#: ../../c-api/init.rst:1430 -msgid "" -"Raises an :ref:`auditing event ` ``cpython." -"PyInterpreterState_New`` with no arguments." -msgstr "" -"引發一個不附帶引數的\\ :ref:`稽核事件 ` ``cpython." -"PyInterpreterState_New``。" - -#: ../../c-api/init.rst:1435 -msgid "" -"Reset all information in an interpreter state object. There must be an :" -"term:`attached thread state` for the interpreter." -msgstr "" - -#: ../../c-api/init.rst:1438 -msgid "" -"Raises an :ref:`auditing event ` ``cpython." -"PyInterpreterState_Clear`` with no arguments." -msgstr "" -"引發一個不附帶引數的\\ :ref:`稽核事件 ` ``cpython." -"PyInterpreterState_Clear``。" - -#: ../../c-api/init.rst:1443 -msgid "" -"Destroy an interpreter state object. There **should not** be an :term:" -"`attached thread state` for the target interpreter. The interpreter state " -"must have been reset with a previous call to :c:func:" -"`PyInterpreterState_Clear`." -msgstr "" - -#: ../../c-api/init.rst:1450 -msgid "" -"Create a new thread state object belonging to the given interpreter object. " -"An :term:`attached thread state` is not needed." -msgstr "" - -#: ../../c-api/init.rst:1455 -msgid "" -"Reset all information in a :term:`thread state` object. *tstate* must be :" -"term:`attached `" -msgstr "" - -#: ../../c-api/init.rst:1458 -msgid "" -"This function now calls the :c:member:`!PyThreadState.on_delete` callback. " -"Previously, that happened in :c:func:`PyThreadState_Delete`." -msgstr "" - -#: ../../c-api/init.rst:1462 -msgid "The :c:member:`!PyThreadState.on_delete` callback was removed." -msgstr ":c:member:`!PyThreadState.on_delete` 回呼已被移除。" - -#: ../../c-api/init.rst:1468 -msgid "" -"Destroy a :term:`thread state` object. *tstate* should not be :term:" -"`attached ` to any thread. *tstate* must have been " -"reset with a previous call to :c:func:`PyThreadState_Clear`." -msgstr "" - -#: ../../c-api/init.rst:1476 -msgid "" -"Detach the :term:`attached thread state` (which must have been reset with a " -"previous call to :c:func:`PyThreadState_Clear`) and then destroy it." -msgstr "" - -#: ../../c-api/init.rst:1479 -msgid "" -"No :term:`thread state` will be :term:`attached ` " -"upon returning." -msgstr "" - -#: ../../c-api/init.rst:1484 -msgid "Get the current frame of the Python thread state *tstate*." -msgstr "" - -#: ../../c-api/init.rst:1486 -msgid "" -"Return a :term:`strong reference`. Return ``NULL`` if no frame is currently " -"executing." -msgstr "" - -#: ../../c-api/init.rst:1489 -msgid "See also :c:func:`PyEval_GetFrame`." -msgstr "也請見 :c:func:`PyEval_GetFrame`。" - -#: ../../c-api/init.rst:1491 ../../c-api/init.rst:1500 -#: ../../c-api/init.rst:1509 -msgid "" -"*tstate* must not be ``NULL``, and must be :term:`attached `." -msgstr "" - -#: ../../c-api/init.rst:1498 -msgid "" -"Get the unique :term:`thread state` identifier of the Python thread state " -"*tstate*." -msgstr "" - -#: ../../c-api/init.rst:1507 -msgid "Get the interpreter of the Python thread state *tstate*." -msgstr "" - -#: ../../c-api/init.rst:1516 -msgid "Suspend tracing and profiling in the Python thread state *tstate*." -msgstr "" - -#: ../../c-api/init.rst:1518 -msgid "Resume them using the :c:func:`PyThreadState_LeaveTracing` function." -msgstr "" - -#: ../../c-api/init.rst:1525 -msgid "" -"Resume tracing and profiling in the Python thread state *tstate* suspended " -"by the :c:func:`PyThreadState_EnterTracing` function." -msgstr "" - -#: ../../c-api/init.rst:1528 -msgid "" -"See also :c:func:`PyEval_SetTrace` and :c:func:`PyEval_SetProfile` functions." -msgstr "" - -#: ../../c-api/init.rst:1536 -msgid "" -"Set the stack protection start address and stack protection size of a Python " -"thread state." -msgstr "" - -#: ../../c-api/init.rst:1539 -msgid "" -"On success, return ``0``. On failure, set an exception and return ``-1``." -msgstr "" - -#: ../../c-api/init.rst:1542 -msgid "" -"CPython implements :ref:`recursion control ` for C code by " -"raising :py:exc:`RecursionError` when it notices that the machine execution " -"stack is close to overflow. See for example the :c:func:" -"`Py_EnterRecursiveCall` function. For this, it needs to know the location of " -"the current thread's stack, which it normally gets from the operating " -"system. When the stack is changed, for example using context switching " -"techniques like the Boost library's ``boost::context``, you must call :c:" -"func:`~PyUnstable_ThreadState_SetStackProtection` to inform CPython of the " -"change." -msgstr "" - -#: ../../c-api/init.rst:1551 -msgid "" -"Call :c:func:`~PyUnstable_ThreadState_SetStackProtection` either before or " -"after changing the stack. Do not call any other Python C API between the " -"call and the stack change." -msgstr "" - -#: ../../c-api/init.rst:1556 -msgid "" -"See :c:func:`PyUnstable_ThreadState_ResetStackProtection` for undoing this " -"operation." -msgstr "" - -#: ../../c-api/init.rst:1562 ../../c-api/init.rst:1582 -msgid "" -"This function was added in a bugfix release, and extensions that use it will " -"be incompatible with Python 3.14.0. Most packaging tools for Python are not " -"able to handle this incompatibility automatically, and will need explicit " -"configuration. When using PyPA standards (wheels and source distributions), " -"specify ``Requires-Python: != 3.14.0.*`` in `core metadata `_." -msgstr "" - -#: ../../c-api/init.rst:1573 -msgid "" -"Reset the stack protection start address and stack protection size of a " -"Python thread state to the operating system defaults." -msgstr "" - -#: ../../c-api/init.rst:1576 -msgid "" -"See :c:func:`PyUnstable_ThreadState_SetStackProtection` for an explanation." -msgstr "" - -#: ../../c-api/init.rst:1593 -msgid "Get the current interpreter." -msgstr "" - -#: ../../c-api/init.rst:1595 -msgid "" -"Issue a fatal error if there no :term:`attached thread state`. It cannot " -"return NULL." -msgstr "" - -#: ../../c-api/init.rst:1603 -msgid "" -"Return the interpreter's unique ID. If there was any error in doing so then " -"``-1`` is returned and an error is set." -msgstr "" - -#: ../../c-api/init.rst:1606 ../../c-api/init.rst:2221 -#: ../../c-api/init.rst:2228 ../../c-api/init.rst:2247 -#: ../../c-api/init.rst:2254 -msgid "The caller must have an :term:`attached thread state`." -msgstr "呼叫者必須擁有一個 :term:`attached thread state`。" - -#: ../../c-api/init.rst:1613 -msgid "" -"Return a dictionary in which interpreter-specific data may be stored. If " -"this function returns ``NULL`` then no exception has been raised and the " -"caller should assume no interpreter-specific dict is available." -msgstr "" - -#: ../../c-api/init.rst:1617 -msgid "" -"This is not a replacement for :c:func:`PyModule_GetState()`, which " -"extensions should use to store interpreter-specific state information." -msgstr "" - -#: ../../c-api/init.rst:1620 -msgid "" -"The returned dictionary is borrowed from the interpreter and is valid until " -"interpreter shutdown." -msgstr "" - -#: ../../c-api/init.rst:1628 -msgid "Type of a frame evaluation function." -msgstr "" - -#: ../../c-api/init.rst:1630 -msgid "" -"The *throwflag* parameter is used by the ``throw()`` method of generators: " -"if non-zero, handle the current exception." -msgstr "" - -#: ../../c-api/init.rst:1633 -msgid "The function now takes a *tstate* parameter." -msgstr "" - -#: ../../c-api/init.rst:1636 -msgid "" -"The *frame* parameter changed from ``PyFrameObject*`` to " -"``_PyInterpreterFrame*``." -msgstr "" - -#: ../../c-api/init.rst:1641 -msgid "Get the frame evaluation function." -msgstr "" - -#: ../../c-api/init.rst:1643 ../../c-api/init.rst:1651 -msgid "See the :pep:`523` \"Adding a frame evaluation API to CPython\"." -msgstr "" - -#: ../../c-api/init.rst:1649 -msgid "Set the frame evaluation function." -msgstr "" - -#: ../../c-api/init.rst:1658 -msgid "" -"Return a dictionary in which extensions can store thread-specific state " -"information. Each extension should use a unique key to use to store state " -"in the dictionary. It is okay to call this function when no :term:`thread " -"state` is :term:`attached `. If this function returns " -"``NULL``, no exception has been raised and the caller should assume no " -"thread state is attached." -msgstr "" - -#: ../../c-api/init.rst:1668 -msgid "" -"Asynchronously raise an exception in a thread. The *id* argument is the " -"thread id of the target thread; *exc* is the exception object to be raised. " -"This function does not steal any references to *exc*. To prevent naive " -"misuse, you must write your own C extension to call this. Must be called " -"with an :term:`attached thread state`. Returns the number of thread states " -"modified; this is normally one, but will be zero if the thread id isn't " -"found. If *exc* is ``NULL``, the pending exception (if any) for the thread " -"is cleared. This raises no exceptions." -msgstr "" - -#: ../../c-api/init.rst:1676 -msgid "" -"The type of the *id* parameter changed from :c:expr:`long` to :c:expr:" -"`unsigned long`." -msgstr "" - -#: ../../c-api/init.rst:1682 -msgid "" -":term:`Attach ` *tstate* to the current thread, which " -"must not be ``NULL`` or already :term:`attached `." -msgstr "" - -#: ../../c-api/init.rst:1685 -msgid "" -"The calling thread must not already have an :term:`attached thread state`." -msgstr "" - -#: ../../c-api/init.rst:1693 -msgid "" -"Updated to be consistent with :c:func:`PyEval_RestoreThread`, :c:func:" -"`Py_END_ALLOW_THREADS`, and :c:func:`PyGILState_Ensure`, and terminate the " -"current thread if called while the interpreter is finalizing." -msgstr "" - -#: ../../c-api/init.rst:1702 -msgid "" -":c:func:`PyEval_RestoreThread` is a higher-level function which is always " -"available (even when threads have not been initialized)." -msgstr "" - -#: ../../c-api/init.rst:1708 -msgid "" -"Detach the :term:`attached thread state`. The *tstate* argument, which must " -"not be ``NULL``, is only used to check that it represents the :term:" -"`attached thread state` --- if it isn't, a fatal error is reported." -msgstr "" - -#: ../../c-api/init.rst:1713 -msgid "" -":c:func:`PyEval_SaveThread` is a higher-level function which is always " -"available (even when threads have not been initialized)." -msgstr "" - -#: ../../c-api/init.rst:1720 -msgid "Sub-interpreter support" -msgstr "" - -#: ../../c-api/init.rst:1722 -msgid "" -"While in most uses, you will only embed a single Python interpreter, there " -"are cases where you need to create several independent interpreters in the " -"same process and perhaps even in the same thread. Sub-interpreters allow you " -"to do that." -msgstr "" - -#: ../../c-api/init.rst:1727 -msgid "" -"The \"main\" interpreter is the first one created when the runtime " -"initializes. It is usually the only Python interpreter in a process. Unlike " -"sub-interpreters, the main interpreter has unique process-global " -"responsibilities like signal handling. It is also responsible for execution " -"during runtime initialization and is usually the active interpreter during " -"runtime finalization. The :c:func:`PyInterpreterState_Main` function " -"returns a pointer to its state." -msgstr "" - -#: ../../c-api/init.rst:1734 -msgid "" -"You can switch between sub-interpreters using the :c:func:" -"`PyThreadState_Swap` function. You can create and destroy them using the " -"following functions:" -msgstr "" - -#: ../../c-api/init.rst:1740 -msgid "" -"Structure containing most parameters to configure a sub-interpreter. Its " -"values are used only in :c:func:`Py_NewInterpreterFromConfig` and never " -"modified by the runtime." -msgstr "" - -#: ../../c-api/init.rst:1746 -msgid "Structure fields:" -msgstr "" - -#: ../../c-api/init.rst:1750 -msgid "" -"If this is ``0`` then the sub-interpreter will use its own \"object\" " -"allocator state. Otherwise it will use (share) the main interpreter's." -msgstr "" - -#: ../../c-api/init.rst:1754 -msgid "" -"If this is ``0`` then :c:member:`~PyInterpreterConfig." -"check_multi_interp_extensions` must be ``1`` (non-zero). If this is ``1`` " -"then :c:member:`~PyInterpreterConfig.gil` must not be :c:macro:" -"`PyInterpreterConfig_OWN_GIL`." -msgstr "" - -#: ../../c-api/init.rst:1762 -msgid "" -"If this is ``0`` then the runtime will not support forking the process in " -"any thread where the sub-interpreter is currently active. Otherwise fork is " -"unrestricted." -msgstr "" - -#: ../../c-api/init.rst:1766 -msgid "" -"Note that the :mod:`subprocess` module still works when fork is disallowed." -msgstr "" - -#: ../../c-api/init.rst:1771 -msgid "" -"If this is ``0`` then the runtime will not support replacing the current " -"process via exec (e.g. :func:`os.execv`) in any thread where the sub-" -"interpreter is currently active. Otherwise exec is unrestricted." -msgstr "" - -#: ../../c-api/init.rst:1776 -msgid "" -"Note that the :mod:`subprocess` module still works when exec is disallowed." -msgstr "" - -#: ../../c-api/init.rst:1781 -msgid "" -"If this is ``0`` then the sub-interpreter's :mod:`threading` module won't " -"create threads. Otherwise threads are allowed." -msgstr "" - -#: ../../c-api/init.rst:1787 -msgid "" -"If this is ``0`` then the sub-interpreter's :mod:`threading` module won't " -"create daemon threads. Otherwise daemon threads are allowed (as long as :c:" -"member:`~PyInterpreterConfig.allow_threads` is non-zero)." -msgstr "" - -#: ../../c-api/init.rst:1794 -msgid "" -"If this is ``0`` then all extension modules may be imported, including " -"legacy (single-phase init) modules, in any thread where the sub-interpreter " -"is currently active. Otherwise only multi-phase init extension modules (see :" -"pep:`489`) may be imported. (Also see :c:macro:" -"`Py_mod_multiple_interpreters`.)" -msgstr "" - -#: ../../c-api/init.rst:1801 -msgid "" -"This must be ``1`` (non-zero) if :c:member:`~PyInterpreterConfig." -"use_main_obmalloc` is ``0``." -msgstr "" - -#: ../../c-api/init.rst:1806 -msgid "" -"This determines the operation of the GIL for the sub-interpreter. It may be " -"one of the following:" -msgstr "" - -#: ../../c-api/init.rst:1813 -msgid "Use the default selection (:c:macro:`PyInterpreterConfig_SHARED_GIL`)." -msgstr "" - -#: ../../c-api/init.rst:1817 -msgid "Use (share) the main interpreter's GIL." -msgstr "" - -#: ../../c-api/init.rst:1821 -msgid "Use the sub-interpreter's own GIL." -msgstr "" - -#: ../../c-api/init.rst:1823 -msgid "" -"If this is :c:macro:`PyInterpreterConfig_OWN_GIL` then :c:member:" -"`PyInterpreterConfig.use_main_obmalloc` must be ``0``." -msgstr "" - -#: ../../c-api/init.rst:1837 -msgid "" -"Create a new sub-interpreter. This is an (almost) totally separate " -"environment for the execution of Python code. In particular, the new " -"interpreter has separate, independent versions of all imported modules, " -"including the fundamental modules :mod:`builtins`, :mod:`__main__` and :mod:" -"`sys`. The table of loaded modules (``sys.modules``) and the module search " -"path (``sys.path``) are also separate. The new environment has no ``sys." -"argv`` variable. It has new standard I/O stream file objects ``sys.stdin``, " -"``sys.stdout`` and ``sys.stderr`` (however these refer to the same " -"underlying file descriptors)." -msgstr "" - -#: ../../c-api/init.rst:1847 -msgid "" -"The given *config* controls the options with which the interpreter is " -"initialized." -msgstr "" - -#: ../../c-api/init.rst:1850 -msgid "" -"Upon success, *tstate_p* will be set to the first :term:`thread state` " -"created in the new sub-interpreter. This thread state is :term:`attached " -"`. Note that no actual thread is created; see the " -"discussion of thread states below. If creation of the new interpreter is " -"unsuccessful, *tstate_p* is set to ``NULL``; no exception is set since the " -"exception state is stored in the :term:`attached thread state`, which might " -"not exist." -msgstr "" - -#: ../../c-api/init.rst:1859 -msgid "" -"Like all other Python/C API functions, an :term:`attached thread state` must " -"be present before calling this function, but it might be detached upon " -"returning. On success, the returned thread state will be :term:`attached " -"`. If the sub-interpreter is created with its own :" -"term:`GIL` then the :term:`attached thread state` of the calling interpreter " -"will be detached. When the function returns, the new interpreter's :term:" -"`thread state` will be :term:`attached ` to the " -"current thread and the previous interpreter's :term:`attached thread state` " -"will remain detached." -msgstr "" - -#: ../../c-api/init.rst:1870 -msgid "" -"Sub-interpreters are most effective when isolated from each other, with " -"certain functionality restricted::" -msgstr "" - -#: ../../c-api/init.rst:1873 -msgid "" -"PyInterpreterConfig config = {\n" -" .use_main_obmalloc = 0,\n" -" .allow_fork = 0,\n" -" .allow_exec = 0,\n" -" .allow_threads = 1,\n" -" .allow_daemon_threads = 0,\n" -" .check_multi_interp_extensions = 1,\n" -" .gil = PyInterpreterConfig_OWN_GIL,\n" -"};\n" -"PyThreadState *tstate = NULL;\n" -"PyStatus status = Py_NewInterpreterFromConfig(&tstate, &config);\n" -"if (PyStatus_Exception(status)) {\n" -" Py_ExitStatusException(status);\n" -"}" -msgstr "" -"PyInterpreterConfig config = {\n" -" .use_main_obmalloc = 0,\n" -" .allow_fork = 0,\n" -" .allow_exec = 0,\n" -" .allow_threads = 1,\n" -" .allow_daemon_threads = 0,\n" -" .check_multi_interp_extensions = 1,\n" -" .gil = PyInterpreterConfig_OWN_GIL,\n" -"};\n" -"PyThreadState *tstate = NULL;\n" -"PyStatus status = Py_NewInterpreterFromConfig(&tstate, &config);\n" -"if (PyStatus_Exception(status)) {\n" -" Py_ExitStatusException(status);\n" -"}" - -#: ../../c-api/init.rst:1888 -msgid "" -"Note that the config is used only briefly and does not get modified. During " -"initialization the config's values are converted into various :c:type:" -"`PyInterpreterState` values. A read-only copy of the config may be stored " -"internally on the :c:type:`PyInterpreterState`." -msgstr "" - -#: ../../c-api/init.rst:1897 -msgid "Extension modules are shared between (sub-)interpreters as follows:" -msgstr "" - -#: ../../c-api/init.rst:1899 -msgid "" -"For modules using multi-phase initialization, e.g. :c:func:" -"`PyModule_FromDefAndSpec`, a separate module object is created and " -"initialized for each interpreter. Only C-level static and global variables " -"are shared between these module objects." -msgstr "" - -#: ../../c-api/init.rst:1905 -msgid "" -"For modules using single-phase initialization, e.g. :c:func:" -"`PyModule_Create`, the first time a particular extension is imported, it is " -"initialized normally, and a (shallow) copy of its module's dictionary is " -"squirreled away. When the same extension is imported by another " -"(sub-)interpreter, a new module is initialized and filled with the contents " -"of this copy; the extension's ``init`` function is not called. Objects in " -"the module's dictionary thus end up shared across (sub-)interpreters, which " -"might cause unwanted behavior (see `Bugs and caveats`_ below)." -msgstr "" - -#: ../../c-api/init.rst:1916 -msgid "" -"Note that this is different from what happens when an extension is imported " -"after the interpreter has been completely re-initialized by calling :c:func:" -"`Py_FinalizeEx` and :c:func:`Py_Initialize`; in that case, the extension's " -"``initmodule`` function *is* called again. As with multi-phase " -"initialization, this means that only C-level static and global variables are " -"shared between these modules." -msgstr "" - -#: ../../c-api/init.rst:1936 -msgid "" -"Create a new sub-interpreter. This is essentially just a wrapper around :c:" -"func:`Py_NewInterpreterFromConfig` with a config that preserves the existing " -"behavior. The result is an unisolated sub-interpreter that shares the main " -"interpreter's GIL, allows fork/exec, allows daemon threads, and allows " -"single-phase init modules." -msgstr "" - -#: ../../c-api/init.rst:1948 -msgid "" -"Destroy the (sub-)interpreter represented by the given :term:`thread state`. " -"The given thread state must be :term:`attached `. " -"When the call returns, there will be no :term:`attached thread state`. All " -"thread states associated with this interpreter are destroyed." -msgstr "" - -#: ../../c-api/init.rst:1953 -msgid "" -":c:func:`Py_FinalizeEx` will destroy all sub-interpreters that haven't been " -"explicitly destroyed at that point." -msgstr "" - -#: ../../c-api/init.rst:1960 -msgid "A Per-Interpreter GIL" -msgstr "直譯器各別持有的 GIL" - -#: ../../c-api/init.rst:1962 -msgid "" -"Using :c:func:`Py_NewInterpreterFromConfig` you can create a sub-interpreter " -"that is completely isolated from other interpreters, including having its " -"own GIL. The most important benefit of this isolation is that such an " -"interpreter can execute Python code without being blocked by other " -"interpreters or blocking any others. Thus a single Python process can truly " -"take advantage of multiple CPU cores when running Python code. The " -"isolation also encourages a different approach to concurrency than that of " -"just using threads. (See :pep:`554` and :pep:`684`.)" -msgstr "" - -#: ../../c-api/init.rst:1972 -msgid "" -"Using an isolated interpreter requires vigilance in preserving that " -"isolation. That especially means not sharing any objects or mutable state " -"without guarantees about thread-safety. Even objects that are otherwise " -"immutable (e.g. ``None``, ``(1, 5)``) can't normally be shared because of " -"the refcount. One simple but less-efficient approach around this is to use " -"a global lock around all use of some state (or object). Alternately, " -"effectively immutable objects (like integers or strings) can be made safe in " -"spite of their refcounts by making them :term:`immortal`. In fact, this has " -"been done for the builtin singletons, small integers, and a number of other " -"builtin objects." -msgstr "" - -#: ../../c-api/init.rst:1983 -msgid "" -"If you preserve isolation then you will have access to proper multi-core " -"computing without the complications that come with free-threading. Failure " -"to preserve isolation will expose you to the full consequences of free-" -"threading, including races and hard-to-debug crashes." -msgstr "" - -#: ../../c-api/init.rst:1988 -msgid "" -"Aside from that, one of the main challenges of using multiple isolated " -"interpreters is how to communicate between them safely (not break isolation) " -"and efficiently. The runtime and stdlib do not provide any standard " -"approach to this yet. A future stdlib module would help mitigate the effort " -"of preserving isolation and expose effective tools for communicating (and " -"sharing) data between interpreters." -msgstr "" - -#: ../../c-api/init.rst:1999 -msgid "Bugs and caveats" -msgstr "" - -#: ../../c-api/init.rst:2001 -msgid "" -"Because sub-interpreters (and the main interpreter) are part of the same " -"process, the insulation between them isn't perfect --- for example, using " -"low-level file operations like :func:`os.close` they can (accidentally or " -"maliciously) affect each other's open files. Because of the way extensions " -"are shared between (sub-)interpreters, some extensions may not work " -"properly; this is especially likely when using single-phase initialization " -"or (static) global variables. It is possible to insert objects created in " -"one sub-interpreter into a namespace of another (sub-)interpreter; this " -"should be avoided if possible." -msgstr "" - -#: ../../c-api/init.rst:2011 -msgid "" -"Special care should be taken to avoid sharing user-defined functions, " -"methods, instances or classes between sub-interpreters, since import " -"operations executed by such objects may affect the wrong (sub-)interpreter's " -"dictionary of loaded modules. It is equally important to avoid sharing " -"objects from which the above are reachable." -msgstr "" - -#: ../../c-api/init.rst:2017 -msgid "" -"Also note that combining this functionality with ``PyGILState_*`` APIs is " -"delicate, because these APIs assume a bijection between Python thread states " -"and OS-level threads, an assumption broken by the presence of sub-" -"interpreters. It is highly recommended that you don't switch sub-" -"interpreters between a pair of matching :c:func:`PyGILState_Ensure` and :c:" -"func:`PyGILState_Release` calls. Furthermore, extensions (such as :mod:" -"`ctypes`) using these APIs to allow calling of Python code from non-Python " -"created threads will probably be broken when using sub-interpreters." -msgstr "" - -#: ../../c-api/init.rst:2028 -msgid "Asynchronous Notifications" -msgstr "" - -#: ../../c-api/init.rst:2030 -msgid "" -"A mechanism is provided to make asynchronous notifications to the main " -"interpreter thread. These notifications take the form of a function pointer " -"and a void pointer argument." -msgstr "" - -#: ../../c-api/init.rst:2037 -msgid "" -"Schedule a function to be called from the main interpreter thread. On " -"success, ``0`` is returned and *func* is queued for being called in the main " -"thread. On failure, ``-1`` is returned without setting any exception." -msgstr "" - -#: ../../c-api/init.rst:2041 -msgid "" -"When successfully queued, *func* will be *eventually* called from the main " -"interpreter thread with the argument *arg*. It will be called " -"asynchronously with respect to normally running Python code, but with both " -"these conditions met:" -msgstr "" - -#: ../../c-api/init.rst:2046 -msgid "on a :term:`bytecode` boundary;" -msgstr "" - -#: ../../c-api/init.rst:2047 -msgid "" -"with the main thread holding an :term:`attached thread state` (*func* can " -"therefore use the full C API)." -msgstr "" - -#: ../../c-api/init.rst:2050 -msgid "" -"*func* must return ``0`` on success, or ``-1`` on failure with an exception " -"set. *func* won't be interrupted to perform another asynchronous " -"notification recursively, but it can still be interrupted to switch threads " -"if the :term:`thread state ` is detached." -msgstr "" - -#: ../../c-api/init.rst:2055 -msgid "" -"This function doesn't need an :term:`attached thread state`. However, to " -"call this function in a subinterpreter, the caller must have an :term:" -"`attached thread state`. Otherwise, the function *func* can be scheduled to " -"be called from the wrong interpreter." -msgstr "" - -#: ../../c-api/init.rst:2060 -msgid "" -"This is a low-level function, only useful for very special cases. There is " -"no guarantee that *func* will be called as quick as possible. If the main " -"thread is busy executing a system call, *func* won't be called before the " -"system call returns. This function is generally **not** suitable for " -"calling Python code from arbitrary C threads. Instead, use the :ref:" -"`PyGILState API`." -msgstr "" - -#: ../../c-api/init.rst:2069 -msgid "" -"If this function is called in a subinterpreter, the function *func* is now " -"scheduled to be called from the subinterpreter, rather than being called " -"from the main interpreter. Each subinterpreter now has its own list of " -"scheduled calls." -msgstr "" - -#: ../../c-api/init.rst:2075 -msgid "" -"This function now always schedules *func* to be run in the main interpreter." -msgstr "" - -#: ../../c-api/init.rst:2082 -msgid "" -"Execute all pending calls. This is usually executed automatically by the " -"interpreter." -msgstr "" - -#: ../../c-api/init.rst:2085 -msgid "" -"This function returns ``0`` on success, and returns ``-1`` with an exception " -"set on failure." -msgstr "" - -#: ../../c-api/init.rst:2088 -msgid "" -"If this is not called in the main thread of the main interpreter, this " -"function does nothing and returns ``0``. The caller must hold an :term:" -"`attached thread state`." -msgstr "" - -#: ../../c-api/init.rst:2094 -msgid "This function only runs pending calls in the main interpreter." -msgstr "" - -#: ../../c-api/init.rst:2101 -msgid "Profiling and Tracing" -msgstr "" - -#: ../../c-api/init.rst:2106 -msgid "" -"The Python interpreter provides some low-level support for attaching " -"profiling and execution tracing facilities. These are used for profiling, " -"debugging, and coverage analysis tools." -msgstr "" - -#: ../../c-api/init.rst:2110 -msgid "" -"This C interface allows the profiling or tracing code to avoid the overhead " -"of calling through Python-level callable objects, making a direct C function " -"call instead. The essential attributes of the facility have not changed; " -"the interface allows trace functions to be installed per-thread, and the " -"basic events reported to the trace function are the same as had been " -"reported to the Python-level trace functions in previous versions." -msgstr "" - -#: ../../c-api/init.rst:2120 -msgid "" -"The type of the trace function registered using :c:func:`PyEval_SetProfile` " -"and :c:func:`PyEval_SetTrace`. The first parameter is the object passed to " -"the registration function as *obj*, *frame* is the frame object to which the " -"event pertains, *what* is one of the constants :c:data:`PyTrace_CALL`, :c:" -"data:`PyTrace_EXCEPTION`, :c:data:`PyTrace_LINE`, :c:data:`PyTrace_RETURN`, :" -"c:data:`PyTrace_C_CALL`, :c:data:`PyTrace_C_EXCEPTION`, :c:data:" -"`PyTrace_C_RETURN`, or :c:data:`PyTrace_OPCODE`, and *arg* depends on the " -"value of *what*:" -msgstr "" - -#: ../../c-api/init.rst:2129 -msgid "Value of *what*" -msgstr "*what* 的值" - -#: ../../c-api/init.rst:2129 -msgid "Meaning of *arg*" -msgstr "*arg* 的含義" - -#: ../../c-api/init.rst:2131 -msgid ":c:data:`PyTrace_CALL`" -msgstr ":c:data:`PyTrace_CALL`" - -#: ../../c-api/init.rst:2131 ../../c-api/init.rst:2136 -#: ../../c-api/init.rst:2147 -msgid "Always :c:data:`Py_None`." -msgstr "" - -#: ../../c-api/init.rst:2133 -msgid ":c:data:`PyTrace_EXCEPTION`" -msgstr ":c:data:`PyTrace_EXCEPTION`" - -#: ../../c-api/init.rst:2133 -msgid "Exception information as returned by :func:`sys.exc_info`." -msgstr "" - -#: ../../c-api/init.rst:2136 -msgid ":c:data:`PyTrace_LINE`" -msgstr ":c:data:`PyTrace_LINE`" - -#: ../../c-api/init.rst:2138 -msgid ":c:data:`PyTrace_RETURN`" -msgstr ":c:data:`PyTrace_RETURN`" - -#: ../../c-api/init.rst:2138 -msgid "" -"Value being returned to the caller, or ``NULL`` if caused by an exception." -msgstr "" - -#: ../../c-api/init.rst:2141 -msgid ":c:data:`PyTrace_C_CALL`" -msgstr ":c:data:`PyTrace_C_CALL`" - -#: ../../c-api/init.rst:2141 ../../c-api/init.rst:2143 -#: ../../c-api/init.rst:2145 -msgid "Function object being called." -msgstr "被呼叫的函式物件。" - -#: ../../c-api/init.rst:2143 -msgid ":c:data:`PyTrace_C_EXCEPTION`" -msgstr ":c:data:`PyTrace_C_EXCEPTION`" - -#: ../../c-api/init.rst:2145 -msgid ":c:data:`PyTrace_C_RETURN`" -msgstr ":c:data:`PyTrace_C_RETURN`" - -#: ../../c-api/init.rst:2147 -msgid ":c:data:`PyTrace_OPCODE`" -msgstr ":c:data:`PyTrace_OPCODE`" - -#: ../../c-api/init.rst:2152 -msgid "" -"The value of the *what* parameter to a :c:type:`Py_tracefunc` function when " -"a new call to a function or method is being reported, or a new entry into a " -"generator. Note that the creation of the iterator for a generator function " -"is not reported as there is no control transfer to the Python bytecode in " -"the corresponding frame." -msgstr "" - -#: ../../c-api/init.rst:2161 -msgid "" -"The value of the *what* parameter to a :c:type:`Py_tracefunc` function when " -"an exception has been raised. The callback function is called with this " -"value for *what* when after any bytecode is processed after which the " -"exception becomes set within the frame being executed. The effect of this " -"is that as exception propagation causes the Python stack to unwind, the " -"callback is called upon return to each frame as the exception propagates. " -"Only trace functions receives these events; they are not needed by the " -"profiler." -msgstr "" - -#: ../../c-api/init.rst:2172 -msgid "" -"The value passed as the *what* parameter to a :c:type:`Py_tracefunc` " -"function (but not a profiling function) when a line-number event is being " -"reported. It may be disabled for a frame by setting :attr:`~frame." -"f_trace_lines` to *0* on that frame." -msgstr "" - -#: ../../c-api/init.rst:2180 -msgid "" -"The value for the *what* parameter to :c:type:`Py_tracefunc` functions when " -"a call is about to return." -msgstr "" - -#: ../../c-api/init.rst:2186 -msgid "" -"The value for the *what* parameter to :c:type:`Py_tracefunc` functions when " -"a C function is about to be called." -msgstr "" - -#: ../../c-api/init.rst:2192 -msgid "" -"The value for the *what* parameter to :c:type:`Py_tracefunc` functions when " -"a C function has raised an exception." -msgstr "" - -#: ../../c-api/init.rst:2198 -msgid "" -"The value for the *what* parameter to :c:type:`Py_tracefunc` functions when " -"a C function has returned." -msgstr "" - -#: ../../c-api/init.rst:2204 -msgid "" -"The value for the *what* parameter to :c:type:`Py_tracefunc` functions (but " -"not profiling functions) when a new opcode is about to be executed. This " -"event is not emitted by default: it must be explicitly requested by setting :" -"attr:`~frame.f_trace_opcodes` to *1* on the frame." -msgstr "" - -#: ../../c-api/init.rst:2212 -msgid "" -"Set the profiler function to *func*. The *obj* parameter is passed to the " -"function as its first parameter, and may be any Python object, or ``NULL``. " -"If the profile function needs to maintain state, using a different value for " -"*obj* for each thread provides a convenient and thread-safe place to store " -"it. The profile function is called for all monitored events except :c:data:" -"`PyTrace_LINE` :c:data:`PyTrace_OPCODE` and :c:data:`PyTrace_EXCEPTION`." -msgstr "" - -#: ../../c-api/init.rst:2219 -msgid "See also the :func:`sys.setprofile` function." -msgstr "另請參閱 :func:`sys.setprofile` 函式。" - -#: ../../c-api/init.rst:2225 -msgid "" -"Like :c:func:`PyEval_SetProfile` but sets the profile function in all " -"running threads belonging to the current interpreter instead of the setting " -"it only on the current thread." -msgstr "" - -#: ../../c-api/init.rst:2230 -msgid "" -"As :c:func:`PyEval_SetProfile`, this function ignores any exceptions raised " -"while setting the profile functions in all threads." -msgstr "" - -#: ../../c-api/init.rst:2238 -msgid "" -"Set the tracing function to *func*. This is similar to :c:func:" -"`PyEval_SetProfile`, except the tracing function does receive line-number " -"events and per-opcode events, but does not receive any event related to C " -"function objects being called. Any trace function registered using :c:func:" -"`PyEval_SetTrace` will not receive :c:data:`PyTrace_C_CALL`, :c:data:" -"`PyTrace_C_EXCEPTION` or :c:data:`PyTrace_C_RETURN` as a value for the " -"*what* parameter." -msgstr "" - -#: ../../c-api/init.rst:2245 -msgid "See also the :func:`sys.settrace` function." -msgstr "也請見 :func:`sys.settrace` 函式。" - -#: ../../c-api/init.rst:2251 -msgid "" -"Like :c:func:`PyEval_SetTrace` but sets the tracing function in all running " -"threads belonging to the current interpreter instead of the setting it only " -"on the current thread." -msgstr "" - -#: ../../c-api/init.rst:2256 -msgid "" -"As :c:func:`PyEval_SetTrace`, this function ignores any exceptions raised " -"while setting the trace functions in all threads." -msgstr "" - -#: ../../c-api/init.rst:2262 -msgid "Reference tracing" -msgstr "" - -#: ../../c-api/init.rst:2268 -msgid "" -"The type of the trace function registered using :c:func:" -"`PyRefTracer_SetTracer`. The first parameter is a Python object that has " -"been just created (when **event** is set to :c:data:`PyRefTracer_CREATE`) or " -"about to be destroyed (when **event** is set to :c:data:" -"`PyRefTracer_DESTROY`). The **data** argument is the opaque pointer that was " -"provided when :c:func:`PyRefTracer_SetTracer` was called." -msgstr "" - -#: ../../c-api/init.rst:2278 -msgid "" -"The value for the *event* parameter to :c:type:`PyRefTracer` functions when " -"a Python object has been created." -msgstr "" - -#: ../../c-api/init.rst:2283 -msgid "" -"The value for the *event* parameter to :c:type:`PyRefTracer` functions when " -"a Python object has been destroyed." -msgstr "" - -#: ../../c-api/init.rst:2288 -msgid "" -"Register a reference tracer function. The function will be called when a new " -"Python has been created or when an object is going to be destroyed. If " -"**data** is provided it must be an opaque pointer that will be provided when " -"the tracer function is called. Return ``0`` on success. Set an exception and " -"return ``-1`` on error." -msgstr "" - -#: ../../c-api/init.rst:2294 -msgid "" -"Not that tracer functions **must not** create Python objects inside or " -"otherwise the call will be re-entrant. The tracer also **must not** clear " -"any existing exception or set an exception. A :term:`thread state` will be " -"active every time the tracer function is called." -msgstr "" - -#: ../../c-api/init.rst:2299 ../../c-api/init.rst:2310 -msgid "" -"There must be an :term:`attached thread state` when calling this function." -msgstr "" - -#: ../../c-api/init.rst:2305 -msgid "" -"Get the registered reference tracer function and the value of the opaque " -"data pointer that was registered when :c:func:`PyRefTracer_SetTracer` was " -"called. If no tracer was registered this function will return NULL and will " -"set the **data** pointer to NULL." -msgstr "" - -#: ../../c-api/init.rst:2317 -msgid "Advanced Debugger Support" -msgstr "" - -#: ../../c-api/init.rst:2322 -msgid "" -"These functions are only intended to be used by advanced debugging tools." -msgstr "" - -#: ../../c-api/init.rst:2327 -msgid "" -"Return the interpreter state object at the head of the list of all such " -"objects." -msgstr "" - -#: ../../c-api/init.rst:2332 -msgid "Return the main interpreter state object." -msgstr "" - -#: ../../c-api/init.rst:2337 -msgid "" -"Return the next interpreter state object after *interp* from the list of all " -"such objects." -msgstr "" - -#: ../../c-api/init.rst:2343 -msgid "" -"Return the pointer to the first :c:type:`PyThreadState` object in the list " -"of threads associated with the interpreter *interp*." -msgstr "" - -#: ../../c-api/init.rst:2349 -msgid "" -"Return the next thread state object after *tstate* from the list of all such " -"objects belonging to the same :c:type:`PyInterpreterState` object." -msgstr "" - -#: ../../c-api/init.rst:2356 -msgid "Thread Local Storage Support" -msgstr "" - -#: ../../c-api/init.rst:2360 -msgid "" -"The Python interpreter provides low-level support for thread-local storage " -"(TLS) which wraps the underlying native TLS implementation to support the " -"Python-level thread local storage API (:class:`threading.local`). The " -"CPython C level APIs are similar to those offered by pthreads and Windows: " -"use a thread key and functions to associate a :c:expr:`void*` value per " -"thread." -msgstr "" - -#: ../../c-api/init.rst:2367 -msgid "" -"A :term:`thread state` does *not* need to be :term:`attached ` when calling these functions; they suppl their own locking." -msgstr "" - -#: ../../c-api/init.rst:2370 -msgid "" -"Note that :file:`Python.h` does not include the declaration of the TLS APIs, " -"you need to include :file:`pythread.h` to use thread-local storage." -msgstr "" - -#: ../../c-api/init.rst:2374 -msgid "" -"None of these API functions handle memory management on behalf of the :c:" -"expr:`void*` values. You need to allocate and deallocate them yourself. If " -"the :c:expr:`void*` values happen to be :c:expr:`PyObject*`, these functions " -"don't do refcount operations on them either." -msgstr "" - -#: ../../c-api/init.rst:2382 -msgid "Thread Specific Storage (TSS) API" -msgstr "" - -#: ../../c-api/init.rst:2384 -msgid "" -"TSS API is introduced to supersede the use of the existing TLS API within " -"the CPython interpreter. This API uses a new type :c:type:`Py_tss_t` " -"instead of :c:expr:`int` to represent thread keys." -msgstr "" - -#: ../../c-api/init.rst:2390 -msgid "\"A New C-API for Thread-Local Storage in CPython\" (:pep:`539`)" -msgstr "" - -#: ../../c-api/init.rst:2395 -msgid "" -"This data structure represents the state of a thread key, the definition of " -"which may depend on the underlying TLS implementation, and it has an " -"internal field representing the key's initialization state. There are no " -"public members in this structure." -msgstr "" - -#: ../../c-api/init.rst:2400 -msgid "" -"When :ref:`Py_LIMITED_API ` is not defined, static allocation of " -"this type by :c:macro:`Py_tss_NEEDS_INIT` is allowed." -msgstr "" - -#: ../../c-api/init.rst:2406 -msgid "" -"This macro expands to the initializer for :c:type:`Py_tss_t` variables. Note " -"that this macro won't be defined with :ref:`Py_LIMITED_API `." -msgstr "" - -#: ../../c-api/init.rst:2411 -msgid "Dynamic Allocation" -msgstr "" - -#: ../../c-api/init.rst:2413 -msgid "" -"Dynamic allocation of the :c:type:`Py_tss_t`, required in extension modules " -"built with :ref:`Py_LIMITED_API `, where static allocation of this " -"type is not possible due to its implementation being opaque at build time." -msgstr "" - -#: ../../c-api/init.rst:2420 -msgid "" -"Return a value which is the same state as a value initialized with :c:macro:" -"`Py_tss_NEEDS_INIT`, or ``NULL`` in the case of dynamic allocation failure." -msgstr "" - -#: ../../c-api/init.rst:2427 -msgid "" -"Free the given *key* allocated by :c:func:`PyThread_tss_alloc`, after first " -"calling :c:func:`PyThread_tss_delete` to ensure any associated thread locals " -"have been unassigned. This is a no-op if the *key* argument is ``NULL``." -msgstr "" - -#: ../../c-api/init.rst:2433 -msgid "" -"A freed key becomes a dangling pointer. You should reset the key to ``NULL``." -msgstr "" - -#: ../../c-api/init.rst:2438 -msgid "Methods" -msgstr "方法" - -#: ../../c-api/init.rst:2440 -msgid "" -"The parameter *key* of these functions must not be ``NULL``. Moreover, the " -"behaviors of :c:func:`PyThread_tss_set` and :c:func:`PyThread_tss_get` are " -"undefined if the given :c:type:`Py_tss_t` has not been initialized by :c:" -"func:`PyThread_tss_create`." -msgstr "" - -#: ../../c-api/init.rst:2448 -msgid "" -"Return a non-zero value if the given :c:type:`Py_tss_t` has been initialized " -"by :c:func:`PyThread_tss_create`." -msgstr "" - -#: ../../c-api/init.rst:2454 -msgid "" -"Return a zero value on successful initialization of a TSS key. The behavior " -"is undefined if the value pointed to by the *key* argument is not " -"initialized by :c:macro:`Py_tss_NEEDS_INIT`. This function can be called " -"repeatedly on the same key -- calling it on an already initialized key is a " -"no-op and immediately returns success." -msgstr "" - -#: ../../c-api/init.rst:2463 -msgid "" -"Destroy a TSS key to forget the values associated with the key across all " -"threads, and change the key's initialization state to uninitialized. A " -"destroyed key is able to be initialized again by :c:func:" -"`PyThread_tss_create`. This function can be called repeatedly on the same " -"key -- calling it on an already destroyed key is a no-op." -msgstr "" - -#: ../../c-api/init.rst:2472 -msgid "" -"Return a zero value to indicate successfully associating a :c:expr:`void*` " -"value with a TSS key in the current thread. Each thread has a distinct " -"mapping of the key to a :c:expr:`void*` value." -msgstr "" - -#: ../../c-api/init.rst:2479 -msgid "" -"Return the :c:expr:`void*` value associated with a TSS key in the current " -"thread. This returns ``NULL`` if no value is associated with the key in the " -"current thread." -msgstr "" - -#: ../../c-api/init.rst:2487 -msgid "Thread Local Storage (TLS) API" -msgstr "執行緒局部儲存 (Thread Local Storage, TLS) API：" - -#: ../../c-api/init.rst:2489 -msgid "" -"This API is superseded by :ref:`Thread Specific Storage (TSS) API `." -msgstr "" - -#: ../../c-api/init.rst:2494 -msgid "" -"This version of the API does not support platforms where the native TLS key " -"is defined in a way that cannot be safely cast to ``int``. On such " -"platforms, :c:func:`PyThread_create_key` will return immediately with a " -"failure status, and the other TLS functions will all be no-ops on such " -"platforms." -msgstr "" - -#: ../../c-api/init.rst:2499 -msgid "" -"Due to the compatibility problem noted above, this version of the API should " -"not be used in new code." -msgstr "" - -#: ../../c-api/init.rst:2510 -msgid "Synchronization Primitives" -msgstr "" - -#: ../../c-api/init.rst:2512 -msgid "The C-API provides a basic mutual exclusion lock." -msgstr "" - -#: ../../c-api/init.rst:2516 -msgid "" -"A mutual exclusion lock. The :c:type:`!PyMutex` should be initialized to " -"zero to represent the unlocked state. For example::" -msgstr "" - -#: ../../c-api/init.rst:2519 -msgid "PyMutex mutex = {0};" -msgstr "PyMutex mutex = {0};" - -#: ../../c-api/init.rst:2521 -msgid "" -"Instances of :c:type:`!PyMutex` should not be copied or moved. Both the " -"contents and address of a :c:type:`!PyMutex` are meaningful, and it must " -"remain at a fixed, writable location in memory." -msgstr "" - -#: ../../c-api/init.rst:2527 -msgid "" -"A :c:type:`!PyMutex` currently occupies one byte, but the size should be " -"considered unstable. The size may change in future Python releases without " -"a deprecation period." -msgstr "" - -#: ../../c-api/init.rst:2535 -msgid "" -"Lock mutex *m*. If another thread has already locked it, the calling thread " -"will block until the mutex is unlocked. While blocked, the thread will " -"temporarily detach the :term:`thread state ` if one " -"exists." -msgstr "" - -#: ../../c-api/init.rst:2543 -msgid "" -"Unlock mutex *m*. The mutex must be locked --- otherwise, the function will " -"issue a fatal error." -msgstr "" - -#: ../../c-api/init.rst:2550 -msgid "Returns non-zero if the mutex *m* is currently locked, zero otherwise." -msgstr "" - -#: ../../c-api/init.rst:2554 -msgid "" -"This function is intended for use in assertions and debugging only and " -"should not be used to make concurrency control decisions, as the lock state " -"may change immediately after the check." -msgstr "" - -#: ../../c-api/init.rst:2563 -msgid "Python Critical Section API" -msgstr "" - -#: ../../c-api/init.rst:2565 -msgid "" -"The critical section API provides a deadlock avoidance layer on top of per-" -"object locks for :term:`free-threaded ` CPython. They are " -"intended to replace reliance on the :term:`global interpreter lock`, and are " -"no-ops in versions of Python with the global interpreter lock." -msgstr "" - -#: ../../c-api/init.rst:2570 -msgid "" -"Critical sections are intended to be used for custom types implemented in C-" -"API extensions. They should generally not be used with built-in types like :" -"class:`list` and :class:`dict` because their public C-APIs already use " -"critical sections internally, with the notable exception of :c:func:" -"`PyDict_Next`, which requires critical section to be acquired externally." -msgstr "" - -#: ../../c-api/init.rst:2577 -msgid "" -"Critical sections avoid deadlocks by implicitly suspending active critical " -"sections, hence, they do not provide exclusive access such as provided by " -"traditional locks like :c:type:`PyMutex`. When a critical section is " -"started, the per-object lock for the object is acquired. If the code " -"executed inside the critical section calls C-API functions then it can " -"suspend the critical section thereby releasing the per-object lock, so other " -"threads can acquire the per-object lock for the same object." -msgstr "" - -#: ../../c-api/init.rst:2585 -msgid "" -"Variants that accept :c:type:`PyMutex` pointers rather than Python objects " -"are also available. Use these variants to start a critical section in a " -"situation where there is no :c:type:`PyObject` -- for example, when working " -"with a C type that does not extend or wrap :c:type:`PyObject` but still " -"needs to call into the C API in a manner that might lead to deadlocks." -msgstr "" - -#: ../../c-api/init.rst:2591 -msgid "" -"The functions and structs used by the macros are exposed for cases where C " -"macros are not available. They should only be used as in the given macro " -"expansions. Note that the sizes and contents of the structures may change in " -"future Python versions." -msgstr "" - -#: ../../c-api/init.rst:2598 -msgid "" -"Operations that need to lock two objects at once must use :c:macro:" -"`Py_BEGIN_CRITICAL_SECTION2`. You *cannot* use nested critical sections to " -"lock more than one object at once, because the inner critical section may " -"suspend the outer critical sections. This API does not provide a way to " -"lock more than two objects at once." -msgstr "" - -#: ../../c-api/init.rst:2604 -msgid "Example usage::" -msgstr "範例用法： ::" - -#: ../../c-api/init.rst:2606 -msgid "" -"static PyObject *\n" -"set_field(MyObject *self, PyObject *value)\n" -"{\n" -" Py_BEGIN_CRITICAL_SECTION(self);\n" -" Py_SETREF(self->field, Py_XNewRef(value));\n" -" Py_END_CRITICAL_SECTION();\n" -" Py_RETURN_NONE;\n" -"}" -msgstr "" -"static PyObject *\n" -"set_field(MyObject *self, PyObject *value)\n" -"{\n" -" Py_BEGIN_CRITICAL_SECTION(self);\n" -" Py_SETREF(self->field, Py_XNewRef(value));\n" -" Py_END_CRITICAL_SECTION();\n" -" Py_RETURN_NONE;\n" -"}" - -#: ../../c-api/init.rst:2615 -msgid "" -"In the above example, :c:macro:`Py_SETREF` calls :c:macro:`Py_DECREF`, which " -"can call arbitrary code through an object's deallocation function. The " -"critical section API avoids potential deadlocks due to reentrancy and lock " -"ordering by allowing the runtime to temporarily suspend the critical section " -"if the code triggered by the finalizer blocks and calls :c:func:" -"`PyEval_SaveThread`." -msgstr "" - -#: ../../c-api/init.rst:2623 -msgid "" -"Acquires the per-object lock for the object *op* and begins a critical " -"section." -msgstr "" - -#: ../../c-api/init.rst:2626 ../../c-api/init.rst:2640 -#: ../../c-api/init.rst:2657 ../../c-api/init.rst:2672 -#: ../../c-api/init.rst:2686 ../../c-api/init.rst:2703 -msgid "In the free-threaded build, this macro expands to::" -msgstr "" - -#: ../../c-api/init.rst:2628 -msgid "" -"{\n" -" PyCriticalSection _py_cs;\n" -" PyCriticalSection_Begin(&_py_cs, (PyObject*)(op))" -msgstr "" -"{\n" -" PyCriticalSection _py_cs;\n" -" PyCriticalSection_Begin(&_py_cs, (PyObject*)(op))" - -#: ../../c-api/init.rst:2632 ../../c-api/init.rst:2678 -msgid "In the default build, this macro expands to ``{``." -msgstr "" - -#: ../../c-api/init.rst:2638 -msgid "Locks the mutex *m* and begins a critical section." -msgstr "" - -#: ../../c-api/init.rst:2642 -msgid "" -"{\n" -" PyCriticalSection _py_cs;\n" -" PyCriticalSection_BeginMutex(&_py_cs, m)" -msgstr "" -"{\n" -" PyCriticalSection _py_cs;\n" -" PyCriticalSection_BeginMutex(&_py_cs, m)" - -#: ../../c-api/init.rst:2646 -msgid "" -"Note that unlike :c:macro:`Py_BEGIN_CRITICAL_SECTION`, there is no cast for " -"the argument of the macro - it must be a :c:type:`PyMutex` pointer." -msgstr "" - -#: ../../c-api/init.rst:2649 ../../c-api/init.rst:2695 -msgid "On the default build, this macro expands to ``{``." -msgstr "" - -#: ../../c-api/init.rst:2655 -msgid "Ends the critical section and releases the per-object lock." -msgstr "" - -#: ../../c-api/init.rst:2659 -msgid "" -" PyCriticalSection_End(&_py_cs);\n" -"}" -msgstr "" -" PyCriticalSection_End(&_py_cs);\n" -"}" - -#: ../../c-api/init.rst:2662 ../../c-api/init.rst:2708 -msgid "In the default build, this macro expands to ``}``." -msgstr "" - -#: ../../c-api/init.rst:2668 -msgid "" -"Acquires the per-objects locks for the objects *a* and *b* and begins a " -"critical section. The locks are acquired in a consistent order (lowest " -"address first) to avoid lock ordering deadlocks." -msgstr "" - -#: ../../c-api/init.rst:2674 -msgid "" -"{\n" -" PyCriticalSection2 _py_cs2;\n" -" PyCriticalSection2_Begin(&_py_cs2, (PyObject*)(a), (PyObject*)(b))" -msgstr "" -"{\n" -" PyCriticalSection2 _py_cs2;\n" -" PyCriticalSection2_Begin(&_py_cs2, (PyObject*)(a), (PyObject*)(b))" - -#: ../../c-api/init.rst:2684 -msgid "Locks the mutexes *m1* and *m2* and begins a critical section." -msgstr "" - -#: ../../c-api/init.rst:2688 -msgid "" -"{\n" -" PyCriticalSection2 _py_cs2;\n" -" PyCriticalSection2_BeginMutex(&_py_cs2, m1, m2)" -msgstr "" -"{\n" -" PyCriticalSection2 _py_cs2;\n" -" PyCriticalSection2_BeginMutex(&_py_cs2, m1, m2)" - -#: ../../c-api/init.rst:2692 -msgid "" -"Note that unlike :c:macro:`Py_BEGIN_CRITICAL_SECTION2`, there is no cast for " -"the arguments of the macro - they must be :c:type:`PyMutex` pointers." -msgstr "" - -#: ../../c-api/init.rst:2701 -msgid "Ends the critical section and releases the per-object locks." -msgstr "" - -#: ../../c-api/init.rst:2705 -msgid "" -" PyCriticalSection2_End(&_py_cs2);\n" -"}" -msgstr "" -" PyCriticalSection2_End(&_py_cs2);\n" -"}" - -#: ../../c-api/init.rst:2714 -msgid "Legacy Locking APIs" -msgstr "" - -#: ../../c-api/init.rst:2716 -msgid "" -"These APIs are obsolete since Python 3.13 with the introduction of :c:type:" -"`PyMutex`." -msgstr "" - -#: ../../c-api/init.rst:2719 -msgid "These APIs are now a simple wrapper around ``PyMutex``." -msgstr "" - -#: ../../c-api/init.rst:2725 -msgid "A pointer to a mutual exclusion lock." -msgstr "" - -#: ../../c-api/init.rst:2730 -msgid "The result of acquiring a lock with a timeout." -msgstr "" - -#: ../../c-api/init.rst:2736 -msgid "Failed to acquire the lock." -msgstr "" - -#: ../../c-api/init.rst:2740 -msgid "The lock was successfully acquired." -msgstr "" - -#: ../../c-api/init.rst:2744 -msgid "The lock was interrupted by a signal." -msgstr "" - -#: ../../c-api/init.rst:2749 -msgid "Allocate a new lock." -msgstr "" - -#: ../../c-api/init.rst:2751 -msgid "" -"On success, this function returns a lock; on failure, this function returns " -"``0`` without an exception set." -msgstr "" - -#: ../../c-api/init.rst:2754 ../../c-api/init.rst:2766 -#: ../../c-api/init.rst:2786 ../../c-api/init.rst:2804 -#: ../../c-api/init.rst:2812 ../../c-api/init.rst:2835 -#: ../../c-api/init.rst:2919 ../../c-api/init.rst:2927 -msgid "The caller does not need to hold an :term:`attached thread state`." -msgstr "呼叫者不需擁有一個 :term:`attached thread state`。" - -#: ../../c-api/init.rst:2756 -msgid "" -"This function now always uses :c:type:`PyMutex`. In prior versions, this " -"would use a lock provided by the operating system." -msgstr "" - -#: ../../c-api/init.rst:2763 -msgid "" -"Destroy *lock*. The lock should not be held by any thread when calling this." -msgstr "" - -#: ../../c-api/init.rst:2771 -msgid "Acquire *lock* with a timeout." -msgstr "" - -#: ../../c-api/init.rst:2773 -msgid "" -"This will wait for *microseconds* microseconds to acquire the lock. If the " -"timeout expires, this function returns :c:enumerator:`PY_LOCK_FAILURE`. If " -"*microseconds* is ``-1``, this will wait indefinitely until the lock has " -"been released." -msgstr "" - -#: ../../c-api/init.rst:2778 -msgid "" -"If *intr_flag* is ``1``, acquiring the lock may be interrupted by a signal, " -"in which case this function returns :c:enumerator:`PY_LOCK_INTR`. Upon " -"interruption, it's generally expected that the caller makes a call to :c:" -"func:`Py_MakePendingCalls` to propagate an exception to Python code." -msgstr "" - -#: ../../c-api/init.rst:2783 -msgid "" -"If the lock is successfully acquired, this function returns :c:enumerator:" -"`PY_LOCK_ACQUIRED`." -msgstr "" - -#: ../../c-api/init.rst:2791 -msgid "Acquire *lock*." -msgstr "" - -#: ../../c-api/init.rst:2793 -msgid "" -"If *waitflag* is ``1`` and another thread currently holds the lock, this " -"function will wait until the lock can be acquired and will always return " -"``1``." -msgstr "" - -#: ../../c-api/init.rst:2797 -msgid "" -"If *waitflag* is ``0`` and another thread holds the lock, this function will " -"not wait and instead return ``0``. If the lock is not held by any other " -"thread, then this function will acquire it and return ``1``." -msgstr "" - -#: ../../c-api/init.rst:2801 -msgid "" -"Unlike :c:func:`PyThread_acquire_lock_timed`, acquiring the lock cannot be " -"interrupted by a signal." -msgstr "" - -#: ../../c-api/init.rst:2809 -msgid "" -"Release *lock*. If *lock* is not held, then this function issues a fatal " -"error." -msgstr "" - -#: ../../c-api/init.rst:2816 -msgid "Operating System Thread APIs" -msgstr "" - -#: ../../c-api/init.rst:2820 -msgid "Sentinel value for an invalid thread ID." -msgstr "" - -#: ../../c-api/init.rst:2822 -msgid "This is currently equivalent to ``(unsigned long)-1``." -msgstr "" - -#: ../../c-api/init.rst:2827 -msgid "" -"Start function *func* in a new thread with argument *arg*. The resulting " -"thread is not intended to be joined." -msgstr "" - -#: ../../c-api/init.rst:2830 -msgid "*func* must not be ``NULL``, but *arg* may be ``NULL``." -msgstr "" - -#: ../../c-api/init.rst:2832 -msgid "" -"On success, this function returns the identifier of the new thread; on " -"failure, this returns :c:macro:`PYTHREAD_INVALID_THREAD_ID`." -msgstr "" - -#: ../../c-api/init.rst:2840 -msgid "Return the identifier of the current thread, which will never be zero." -msgstr "" - -#: ../../c-api/init.rst:2842 ../../c-api/init.rst:2874 -msgid "" -"This function cannot fail, and the caller does not need to hold an :term:" -"`attached thread state`." -msgstr "" - -#: ../../c-api/init.rst:2846 -msgid ":py:func:`threading.get_ident`" -msgstr ":py:func:`threading.get_ident`" - -#: ../../c-api/init.rst:2851 -msgid "" -"Get general information about the current thread in the form of a :ref:" -"`struct sequence ` object. This information is " -"accessible as :py:attr:`sys.thread_info` in Python." -msgstr "" - -#: ../../c-api/init.rst:2855 -msgid "" -"On success, this returns a new :term:`strong reference` to the thread " -"information; on failure, this returns ``NULL`` with an exception set." -msgstr "" - -#: ../../c-api/init.rst:2858 -msgid "The caller must hold an :term:`attached thread state`." -msgstr "呼叫者必須擁有一個 :term:`attached thread state`。" - -#: ../../c-api/init.rst:2863 -msgid "This macro is defined when the system supports native thread IDs." -msgstr "" - -#: ../../c-api/init.rst:2868 -msgid "" -"Get the native identifier of the current thread as it was assigned by the " -"operating system's kernel, which will never be less than zero." -msgstr "" - -#: ../../c-api/init.rst:2871 -msgid "" -"This function is only available when :c:macro:`PY_HAVE_THREAD_NATIVE_ID` is " -"defined." -msgstr "" - -#: ../../c-api/init.rst:2878 -msgid ":py:func:`threading.get_native_id`" -msgstr ":py:func:`threading.get_native_id`" - -#: ../../c-api/init.rst:2883 -msgid "" -"Terminate the current thread. This function is generally considered unsafe " -"and should be avoided. It is kept solely for backwards compatibility." -msgstr "" - -#: ../../c-api/init.rst:2886 -msgid "" -"This function is only safe to call if all functions in the full call stack " -"are written to safely allow it." -msgstr "" - -#: ../../c-api/init.rst:2891 -msgid "" -"If the current system uses POSIX threads (also known as \"pthreads\"), this " -"calls :manpage:`pthread_exit(3)`, which attempts to unwind the stack and " -"call C++ destructors on some libc implementations. However, if a " -"``noexcept`` function is reached, it may terminate the process. Other " -"systems, such as macOS, do unwinding." -msgstr "" - -#: ../../c-api/init.rst:2897 -msgid "" -"On Windows, this function calls ``_endthreadex()``, which kills the thread " -"without calling C++ destructors." -msgstr "" - -#: ../../c-api/init.rst:2900 -msgid "In any case, there is a risk of corruption on the thread's stack." -msgstr "" - -#: ../../c-api/init.rst:2907 -msgid "" -"Initialize ``PyThread*`` APIs. Python executes this function automatically, " -"so there's little need to call it from an extension module." -msgstr "" - -#: ../../c-api/init.rst:2913 -msgid "Set the stack size of the current thread to *size* bytes." -msgstr "" - -#: ../../c-api/init.rst:2915 -msgid "" -"This function returns ``0`` on success, ``-1`` if *size* is invalid, or " -"``-2`` if the system does not support changing the stack size. This function " -"does not set exceptions." -msgstr "" - -#: ../../c-api/init.rst:2924 -msgid "" -"Return the stack size of the current thread in bytes, or ``0`` if the " -"system's default stack size is in use." -msgstr "" - -#: ../../c-api/init.rst:350 -msgid "PyEval_InitThreads()" -msgstr "PyEval_InitThreads()" - -#: ../../c-api/init.rst:350 -msgid "modules (in module sys)" -msgstr "modules（sys 模組中）" - -#: ../../c-api/init.rst:350 ../../c-api/init.rst:712 -msgid "path (in module sys)" -msgstr "path（sys 模組中）" - -#: ../../c-api/init.rst:350 ../../c-api/init.rst:712 ../../c-api/init.rst:1228 -#: ../../c-api/init.rst:1829 ../../c-api/init.rst:1928 -msgid "module" -msgstr "模組" - -#: ../../c-api/init.rst:350 ../../c-api/init.rst:1829 ../../c-api/init.rst:1928 -msgid "builtins" -msgstr "builtins（內建）" - -#: ../../c-api/init.rst:350 ../../c-api/init.rst:1829 ../../c-api/init.rst:1928 -msgid "__main__" -msgstr "__main__" - -#: ../../c-api/init.rst:350 ../../c-api/init.rst:1829 ../../c-api/init.rst:1928 -msgid "sys" -msgstr "sys" - -#: ../../c-api/init.rst:350 ../../c-api/init.rst:712 -msgid "search" -msgstr "search（搜尋）" - -#: ../../c-api/init.rst:350 ../../c-api/init.rst:712 -msgid "path" -msgstr "path（路徑）" - -#: ../../c-api/init.rst:350 ../../c-api/init.rst:1893 ../../c-api/init.rst:1946 -msgid "Py_FinalizeEx (C function)" -msgstr "Py_FinalizeEx（C 函式）" - -#: ../../c-api/init.rst:572 -msgid "Py_Initialize()" -msgstr "Py_Initialize()" - -#: ../../c-api/init.rst:572 ../../c-api/init.rst:810 -msgid "main()" -msgstr "main()" - -#: ../../c-api/init.rst:572 -msgid "Py_GetPath()" -msgstr "Py_GetPath()" - -#: ../../c-api/init.rst:690 -msgid "executable (in module sys)" -msgstr "executable（sys 模組中）" - -#: ../../c-api/init.rst:745 ../../c-api/init.rst:787 ../../c-api/init.rst:801 -msgid "version (in module sys)" -msgstr "version（sys 模組中）" - -#: ../../c-api/init.rst:757 -msgid "platform (in module sys)" -msgstr "platform（sys 模組中）" - -#: ../../c-api/init.rst:774 -msgid "copyright (in module sys)" -msgstr "copyright（sys 模組中）" - -#: ../../c-api/init.rst:810 -msgid "Py_FatalError()" -msgstr "Py_FatalError()" - -#: ../../c-api/init.rst:810 -msgid "argv (in module sys)" -msgstr "argv（sys 模組中）" - -#: ../../c-api/init.rst:930 -msgid "global interpreter lock" -msgstr "global interpreter lock（全域直譯器鎖）" - -#: ../../c-api/init.rst:930 -msgid "interpreter lock" -msgstr "interpreter lock（直譯器鎖）" - -#: ../../c-api/init.rst:930 -msgid "lock, interpreter" -msgstr "lock, interpreter（鎖、直譯器）" - -#: ../../c-api/init.rst:944 -msgid "setswitchinterval (in module sys)" -msgstr "setswitchinterval （sys 模組中）" - -#: ../../c-api/init.rst:953 -msgid "PyThreadState (C type)" -msgstr "PyThreadState（C 型別）" - -#: ../../c-api/init.rst:989 -msgid "Py_BEGIN_ALLOW_THREADS (C macro)" -msgstr "Py_BEGIN_ALLOW_THREADS（C 巨集）" - -#: ../../c-api/init.rst:989 -msgid "Py_END_ALLOW_THREADS (C macro)" -msgstr "Py_END_ALLOW_THREADS（C 巨集）" - -#: ../../c-api/init.rst:1005 -msgid "PyEval_RestoreThread (C function)" -msgstr "PyEval_RestoreThread（C 函式）" - -#: ../../c-api/init.rst:1005 -msgid "PyEval_SaveThread (C function)" -msgstr "PyEval_SaveThread（C 函式）" - -#: ../../c-api/init.rst:1206 -msgid "PyEval_AcquireThread()" -msgstr "PyEval_AcquireThread()" - -#: ../../c-api/init.rst:1206 -msgid "PyEval_ReleaseThread()" -msgstr "PyEval_ReleaseThread()" - -#: ../../c-api/init.rst:1206 -msgid "PyEval_SaveThread()" -msgstr "PyEval_SaveThread()" - -#: ../../c-api/init.rst:1206 -msgid "PyEval_RestoreThread()" -msgstr "PyEval_RestoreThread()" - -#: ../../c-api/init.rst:1228 -msgid "_thread" -msgstr "_thread" - -#: ../../c-api/init.rst:1829 ../../c-api/init.rst:1928 -msgid "stdout (in module sys)" -msgstr "stdout（sys 模組中）" - -#: ../../c-api/init.rst:1829 ../../c-api/init.rst:1928 -msgid "stderr (in module sys)" -msgstr "stderr（sys 模組中）" - -#: ../../c-api/init.rst:1829 ../../c-api/init.rst:1928 -msgid "stdin (in module sys)" -msgstr "stdin（sys 模組中）" - -#: ../../c-api/init.rst:1893 -msgid "Py_Initialize (C function)" -msgstr "Py_Initialize（C 函式）" - -#: ../../c-api/init.rst:1923 -msgid "close (in module os)" -msgstr "close（os 模組中）" - -#~ msgid "*tstate* must not be ``NULL``." -#~ msgstr "*tstate* 不可為 ``NULL``。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Adrian Liaw , 2018 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-26 00:14+0000\n" +"PO-Revision-Date: 2023-04-24 20:49+0800\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" +"X-Generator: Poedit 3.2.2\n" + +#: ../../c-api/init.rst:8 +msgid "Initialization, Finalization, and Threads" +msgstr "初始化、終結化與執行緒" + +#: ../../c-api/init.rst:10 +msgid "" +"See :ref:`Python Initialization Configuration ` for details on " +"how to configure the interpreter prior to initialization." +msgstr "" +"關於如何在初始化之前設定直譯器的細節，請參見 :ref:`Python 初始化設定 `。" + +#: ../../c-api/init.rst:16 +msgid "Before Python Initialization" +msgstr "Python 初始化之前" + +#: ../../c-api/init.rst:18 +msgid "" +"In an application embedding Python, the :c:func:`Py_Initialize` function " +"must be called before using any other Python/C API functions; with the " +"exception of a few functions and the :ref:`global configuration variables " +"`." +msgstr "" + +#: ../../c-api/init.rst:23 +msgid "" +"The following functions can be safely called before Python is initialized:" +msgstr "" + +#: ../../c-api/init.rst:25 +msgid "Functions that initialize the interpreter:" +msgstr "" + +#: ../../c-api/init.rst:27 +msgid ":c:func:`Py_Initialize`" +msgstr ":c:func:`Py_Initialize`" + +#: ../../c-api/init.rst:28 +msgid ":c:func:`Py_InitializeEx`" +msgstr ":c:func:`Py_InitializeEx`" + +#: ../../c-api/init.rst:29 +msgid ":c:func:`Py_InitializeFromConfig`" +msgstr ":c:func:`Py_InitializeFromConfig`" + +#: ../../c-api/init.rst:30 +msgid ":c:func:`Py_BytesMain`" +msgstr ":c:func:`Py_BytesMain`" + +#: ../../c-api/init.rst:31 +msgid ":c:func:`Py_Main`" +msgstr ":c:func:`Py_Main`" + +#: ../../c-api/init.rst:32 +msgid "the runtime pre-initialization functions covered in :ref:`init-config`" +msgstr "" + +#: ../../c-api/init.rst:34 +msgid "Configuration functions:" +msgstr "" + +#: ../../c-api/init.rst:36 +msgid ":c:func:`PyImport_AppendInittab`" +msgstr ":c:func:`PyImport_AppendInittab`" + +#: ../../c-api/init.rst:37 +msgid ":c:func:`PyImport_ExtendInittab`" +msgstr ":c:func:`PyImport_ExtendInittab`" + +#: ../../c-api/init.rst:38 +msgid ":c:func:`!PyInitFrozenExtensions`" +msgstr ":c:func:`!PyInitFrozenExtensions`" + +#: ../../c-api/init.rst:39 +msgid ":c:func:`PyMem_SetAllocator`" +msgstr ":c:func:`PyMem_SetAllocator`" + +#: ../../c-api/init.rst:40 +msgid ":c:func:`PyMem_SetupDebugHooks`" +msgstr ":c:func:`PyMem_SetupDebugHooks`" + +#: ../../c-api/init.rst:41 +msgid ":c:func:`PyObject_SetArenaAllocator`" +msgstr ":c:func:`PyObject_SetArenaAllocator`" + +#: ../../c-api/init.rst:42 +msgid ":c:func:`Py_SetProgramName`" +msgstr ":c:func:`Py_SetProgramName`" + +#: ../../c-api/init.rst:43 +msgid ":c:func:`Py_SetPythonHome`" +msgstr ":c:func:`Py_SetPythonHome`" + +#: ../../c-api/init.rst:44 +msgid ":c:func:`PySys_ResetWarnOptions`" +msgstr ":c:func:`PySys_ResetWarnOptions`" + +#: ../../c-api/init.rst:45 +msgid "the configuration functions covered in :ref:`init-config`" +msgstr "" + +#: ../../c-api/init.rst:47 +msgid "Informative functions:" +msgstr "" + +#: ../../c-api/init.rst:49 ../../c-api/init.rst:57 +msgid ":c:func:`Py_IsInitialized`" +msgstr ":c:func:`Py_IsInitialized`" + +#: ../../c-api/init.rst:50 +msgid ":c:func:`PyMem_GetAllocator`" +msgstr ":c:func:`PyMem_GetAllocator`" + +#: ../../c-api/init.rst:51 +msgid ":c:func:`PyObject_GetArenaAllocator`" +msgstr ":c:func:`PyObject_GetArenaAllocator`" + +#: ../../c-api/init.rst:52 +msgid ":c:func:`Py_GetBuildInfo`" +msgstr ":c:func:`Py_GetBuildInfo`" + +#: ../../c-api/init.rst:53 +msgid ":c:func:`Py_GetCompiler`" +msgstr ":c:func:`Py_GetCompiler`" + +#: ../../c-api/init.rst:54 +msgid ":c:func:`Py_GetCopyright`" +msgstr ":c:func:`Py_GetCopyright`" + +#: ../../c-api/init.rst:55 +msgid ":c:func:`Py_GetPlatform`" +msgstr ":c:func:`Py_GetPlatform`" + +#: ../../c-api/init.rst:56 +msgid ":c:func:`Py_GetVersion`" +msgstr ":c:func:`Py_GetVersion`" + +#: ../../c-api/init.rst:59 +msgid "Utilities:" +msgstr "" + +#: ../../c-api/init.rst:61 +msgid ":c:func:`Py_DecodeLocale`" +msgstr ":c:func:`Py_DecodeLocale`" + +#: ../../c-api/init.rst:62 +msgid "" +"the status reporting and utility functions covered in :ref:`init-config`" +msgstr "" + +#: ../../c-api/init.rst:64 +msgid "Memory allocators:" +msgstr "" + +#: ../../c-api/init.rst:66 +msgid ":c:func:`PyMem_RawMalloc`" +msgstr ":c:func:`PyMem_RawMalloc`" + +#: ../../c-api/init.rst:67 +msgid ":c:func:`PyMem_RawRealloc`" +msgstr ":c:func:`PyMem_RawRealloc`" + +#: ../../c-api/init.rst:68 +msgid ":c:func:`PyMem_RawCalloc`" +msgstr ":c:func:`PyMem_RawCalloc`" + +#: ../../c-api/init.rst:69 +msgid ":c:func:`PyMem_RawFree`" +msgstr ":c:func:`PyMem_RawFree`" + +#: ../../c-api/init.rst:71 +msgid "Synchronization:" +msgstr "" + +#: ../../c-api/init.rst:73 +msgid ":c:func:`PyMutex_Lock`" +msgstr ":c:func:`PyMutex_Lock`" + +#: ../../c-api/init.rst:74 +msgid ":c:func:`PyMutex_Unlock`" +msgstr ":c:func:`PyMutex_Unlock`" + +#: ../../c-api/init.rst:78 +msgid "" +"Despite their apparent similarity to some of the functions listed above, the " +"following functions **should not be called** before the interpreter has been " +"initialized: :c:func:`Py_EncodeLocale`, :c:func:`Py_GetPath`, :c:func:" +"`Py_GetPrefix`, :c:func:`Py_GetExecPrefix`, :c:func:" +"`Py_GetProgramFullPath`, :c:func:`Py_GetPythonHome`, :c:func:" +"`Py_GetProgramName`, :c:func:`PyEval_InitThreads`, and :c:func:`Py_RunMain`." +msgstr "" + +#: ../../c-api/init.rst:90 +msgid "Global configuration variables" +msgstr "" + +#: ../../c-api/init.rst:92 +msgid "" +"Python has variables for the global configuration to control different " +"features and options. By default, these flags are controlled by :ref:" +"`command line options `." +msgstr "" + +#: ../../c-api/init.rst:96 +msgid "" +"When a flag is set by an option, the value of the flag is the number of " +"times that the option was set. For example, ``-b`` sets :c:data:" +"`Py_BytesWarningFlag` to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to " +"2." +msgstr "" + +#: ../../c-api/init.rst:102 +msgid "" +"This API is kept for backward compatibility: setting :c:member:`PyConfig." +"bytes_warning` should be used instead, see :ref:`Python Initialization " +"Configuration `." +msgstr "" + +#: ../../c-api/init.rst:106 +msgid "" +"Issue a warning when comparing :class:`bytes` or :class:`bytearray` with :" +"class:`str` or :class:`bytes` with :class:`int`. Issue an error if greater " +"or equal to ``2``." +msgstr "" + +#: ../../c-api/init.rst:110 +msgid "Set by the :option:`-b` option." +msgstr "由 :option:`-b` 選項設定。" + +#: ../../c-api/init.rst:116 +msgid "" +"This API is kept for backward compatibility: setting :c:member:`PyConfig." +"parser_debug` should be used instead, see :ref:`Python Initialization " +"Configuration `." +msgstr "" + +#: ../../c-api/init.rst:120 +msgid "" +"Turn on parser debugging output (for expert only, depending on compilation " +"options)." +msgstr "" + +#: ../../c-api/init.rst:123 +msgid "" +"Set by the :option:`-d` option and the :envvar:`PYTHONDEBUG` environment " +"variable." +msgstr "由 :option:`-d` 選項與 :envvar:`PYTHONDEBUG` 環境變數設定。" + +#: ../../c-api/init.rst:130 +msgid "" +"This API is kept for backward compatibility: setting :c:member:`PyConfig." +"write_bytecode` should be used instead, see :ref:`Python Initialization " +"Configuration `." +msgstr "" + +#: ../../c-api/init.rst:134 +msgid "" +"If set to non-zero, Python won't try to write ``.pyc`` files on the import " +"of source modules." +msgstr "" + +#: ../../c-api/init.rst:137 +msgid "" +"Set by the :option:`-B` option and the :envvar:`PYTHONDONTWRITEBYTECODE` " +"environment variable." +msgstr "" +"由 :option:`-B` 選項與 :envvar:`PYTHONDONTWRITEBYTECODE` 環境變數設定。" + +#: ../../c-api/init.rst:144 +msgid "" +"This API is kept for backward compatibility: setting :c:member:`PyConfig." +"pathconfig_warnings` should be used instead, see :ref:`Python Initialization " +"Configuration `." +msgstr "" + +#: ../../c-api/init.rst:148 +msgid "" +"Suppress error messages when calculating the module search path in :c:func:" +"`Py_GetPath`." +msgstr "" + +#: ../../c-api/init.rst:151 +msgid "Private flag used by ``_freeze_module`` and ``frozenmain`` programs." +msgstr "" + +#: ../../c-api/init.rst:157 +msgid "" +"This API is kept for backward compatibility: setting :c:member:`PyConfig." +"hash_seed` and :c:member:`PyConfig.use_hash_seed` should be used instead, " +"see :ref:`Python Initialization Configuration `." +msgstr "" + +#: ../../c-api/init.rst:162 +msgid "" +"Set to ``1`` if the :envvar:`PYTHONHASHSEED` environment variable is set to " +"a non-empty string." +msgstr "" +"如果環境變數 :envvar:`PYTHONHASHSEED` 被設定為一個非空字串則設為 ``1``。" + +#: ../../c-api/init.rst:165 +msgid "" +"If the flag is non-zero, read the :envvar:`PYTHONHASHSEED` environment " +"variable to initialize the secret hash seed." +msgstr "" + +#: ../../c-api/init.rst:172 +msgid "" +"This API is kept for backward compatibility: setting :c:member:`PyConfig." +"use_environment` should be used instead, see :ref:`Python Initialization " +"Configuration `." +msgstr "" + +#: ../../c-api/init.rst:176 +msgid "" +"Ignore all :envvar:`!PYTHON*` environment variables, e.g. :envvar:" +"`PYTHONPATH` and :envvar:`PYTHONHOME`, that might be set." +msgstr "" +"忽略所有可能被設定的 :envvar:`!PYTHON*` 環境變數，例如 :envvar:`PYTHONPATH` " +"與 :envvar:`PYTHONHOME`。" + +#: ../../c-api/init.rst:179 +msgid "Set by the :option:`-E` and :option:`-I` options." +msgstr "由 :option:`-E` 與 :option:`-I` 選項設定。" + +#: ../../c-api/init.rst:185 +msgid "" +"This API is kept for backward compatibility: setting :c:member:`PyConfig." +"inspect` should be used instead, see :ref:`Python Initialization " +"Configuration `." +msgstr "" + +#: ../../c-api/init.rst:189 +msgid "" +"When a script is passed as first argument or the :option:`-c` option is " +"used, enter interactive mode after executing the script or the command, even " +"when :data:`sys.stdin` does not appear to be a terminal." +msgstr "" + +#: ../../c-api/init.rst:193 +msgid "" +"Set by the :option:`-i` option and the :envvar:`PYTHONINSPECT` environment " +"variable." +msgstr "由 :option:`-i` 選項與 :envvar:`PYTHONINSPECT` 環境變數設定。" + +#: ../../c-api/init.rst:200 +msgid "" +"This API is kept for backward compatibility: setting :c:member:`PyConfig." +"interactive` should be used instead, see :ref:`Python Initialization " +"Configuration `." +msgstr "" + +#: ../../c-api/init.rst:204 +msgid "Set by the :option:`-i` option." +msgstr "由 :option:`-i` 選項設定。" + +#: ../../c-api/init.rst:210 +msgid "" +"This API is kept for backward compatibility: setting :c:member:`PyConfig." +"isolated` should be used instead, see :ref:`Python Initialization " +"Configuration `." +msgstr "" + +#: ../../c-api/init.rst:214 +msgid "" +"Run Python in isolated mode. In isolated mode :data:`sys.path` contains " +"neither the script's directory nor the user's site-packages directory." +msgstr "" + +#: ../../c-api/init.rst:217 +msgid "Set by the :option:`-I` option." +msgstr "由 :option:`-I` 選項設定。" + +#: ../../c-api/init.rst:225 +msgid "" +"This API is kept for backward compatibility: setting :c:member:`PyPreConfig." +"legacy_windows_fs_encoding` should be used instead, see :ref:`Python " +"Initialization Configuration `." +msgstr "" + +#: ../../c-api/init.rst:229 +msgid "" +"If the flag is non-zero, use the ``mbcs`` encoding with ``replace`` error " +"handler, instead of the UTF-8 encoding with ``surrogatepass`` error handler, " +"for the :term:`filesystem encoding and error handler`." +msgstr "" + +#: ../../c-api/init.rst:233 +msgid "" +"Set to ``1`` if the :envvar:`PYTHONLEGACYWINDOWSFSENCODING` environment " +"variable is set to a non-empty string." +msgstr "" +"如果環境變數 :envvar:`PYTHONLEGACYWINDOWSFSENCODING` 被設定為一個非空字串則設" +"為 ``1``。" + +#: ../../c-api/init.rst:236 +msgid "See :pep:`529` for more details." +msgstr "更多詳情請見 :pep:`529`。" + +#: ../../c-api/init.rst:238 ../../c-api/init.rst:256 +msgid "Availability" +msgstr "可用性" + +#: ../../c-api/init.rst:244 +msgid "" +"This API is kept for backward compatibility: setting :c:member:`PyConfig." +"legacy_windows_stdio` should be used instead, see :ref:`Python " +"Initialization Configuration `." +msgstr "" + +#: ../../c-api/init.rst:248 +msgid "" +"If the flag is non-zero, use :class:`io.FileIO` instead of :class:`!io." +"_WindowsConsoleIO` for :mod:`sys` standard streams." +msgstr "" + +#: ../../c-api/init.rst:251 +msgid "" +"Set to ``1`` if the :envvar:`PYTHONLEGACYWINDOWSSTDIO` environment variable " +"is set to a non-empty string." +msgstr "" + +#: ../../c-api/init.rst:254 +msgid "See :pep:`528` for more details." +msgstr "更多詳情請見 :pep:`528`。" + +#: ../../c-api/init.rst:262 +msgid "" +"This API is kept for backward compatibility: setting :c:member:`PyConfig." +"site_import` should be used instead, see :ref:`Python Initialization " +"Configuration `." +msgstr "" + +#: ../../c-api/init.rst:266 +msgid "" +"Disable the import of the module :mod:`site` and the site-dependent " +"manipulations of :data:`sys.path` that it entails. Also disable these " +"manipulations if :mod:`site` is explicitly imported later (call :func:`site." +"main` if you want them to be triggered)." +msgstr "" + +#: ../../c-api/init.rst:271 +msgid "Set by the :option:`-S` option." +msgstr "由 :option:`-S` 選項設定。" + +#: ../../c-api/init.rst:277 +msgid "" +"This API is kept for backward compatibility: setting :c:member:`PyConfig." +"user_site_directory` should be used instead, see :ref:`Python Initialization " +"Configuration `." +msgstr "" + +#: ../../c-api/init.rst:281 +msgid "" +"Don't add the :data:`user site-packages directory ` to :data:" +"`sys.path`." +msgstr "" + +#: ../../c-api/init.rst:284 +msgid "" +"Set by the :option:`-s` and :option:`-I` options, and the :envvar:" +"`PYTHONNOUSERSITE` environment variable." +msgstr "" +"由 :option:`-s` 選項、:option:`-I` 選項與 :envvar:`PYTHONNOUSERSITE` 環境變數" +"設定。" + +#: ../../c-api/init.rst:291 +msgid "" +"This API is kept for backward compatibility: setting :c:member:`PyConfig." +"optimization_level` should be used instead, see :ref:`Python Initialization " +"Configuration `." +msgstr "" + +#: ../../c-api/init.rst:295 +msgid "" +"Set by the :option:`-O` option and the :envvar:`PYTHONOPTIMIZE` environment " +"variable." +msgstr "由 :option:`-O` 選項與 :envvar:`PYTHONOPTIMIZE` 環境變數設定。" + +#: ../../c-api/init.rst:302 +msgid "" +"This API is kept for backward compatibility: setting :c:member:`PyConfig." +"quiet` should be used instead, see :ref:`Python Initialization Configuration " +"`." +msgstr "" + +#: ../../c-api/init.rst:306 +msgid "" +"Don't display the copyright and version messages even in interactive mode." +msgstr "" + +#: ../../c-api/init.rst:308 +msgid "Set by the :option:`-q` option." +msgstr "由 :option:`-q` 選項設定。" + +#: ../../c-api/init.rst:316 +msgid "" +"This API is kept for backward compatibility: setting :c:member:`PyConfig." +"buffered_stdio` should be used instead, see :ref:`Python Initialization " +"Configuration `." +msgstr "" + +#: ../../c-api/init.rst:320 +msgid "Force the stdout and stderr streams to be unbuffered." +msgstr "" + +#: ../../c-api/init.rst:322 +msgid "" +"Set by the :option:`-u` option and the :envvar:`PYTHONUNBUFFERED` " +"environment variable." +msgstr "由 :option:`-u` 選項與 :envvar:`PYTHONUNBUFFERED` 環境變數設定。" + +#: ../../c-api/init.rst:329 +msgid "" +"This API is kept for backward compatibility: setting :c:member:`PyConfig." +"verbose` should be used instead, see :ref:`Python Initialization " +"Configuration `." +msgstr "" + +#: ../../c-api/init.rst:333 +msgid "" +"Print a message each time a module is initialized, showing the place " +"(filename or built-in module) from which it is loaded. If greater or equal " +"to ``2``, print a message for each file that is checked for when searching " +"for a module. Also provides information on module cleanup at exit." +msgstr "" + +#: ../../c-api/init.rst:338 +msgid "" +"Set by the :option:`-v` option and the :envvar:`PYTHONVERBOSE` environment " +"variable." +msgstr "由 :option:`-v` 選項與 :envvar:`PYTHONVERBOSE` 環境變數設定。" + +#: ../../c-api/init.rst:345 +msgid "Initializing and finalizing the interpreter" +msgstr "" + +#: ../../c-api/init.rst:360 +msgid "" +"Initialize the Python interpreter. In an application embedding Python, " +"this should be called before using any other Python/C API functions; see :" +"ref:`Before Python Initialization ` for the few exceptions." +msgstr "" + +#: ../../c-api/init.rst:364 +msgid "" +"This initializes the table of loaded modules (``sys.modules``), and creates " +"the fundamental modules :mod:`builtins`, :mod:`__main__` and :mod:`sys`. It " +"also initializes the module search path (``sys.path``). It does not set " +"``sys.argv``; use the :ref:`Python Initialization Configuration ` API for that. This is a no-op when called for a second time " +"(without calling :c:func:`Py_FinalizeEx` first). There is no return value; " +"it is a fatal error if the initialization fails." +msgstr "" + +#: ../../c-api/init.rst:372 ../../c-api/init.rst:386 +msgid "" +"Use :c:func:`Py_InitializeFromConfig` to customize the :ref:`Python " +"Initialization Configuration `." +msgstr "" + +#: ../../c-api/init.rst:376 +msgid "" +"On Windows, changes the console mode from ``O_TEXT`` to ``O_BINARY``, which " +"will also affect non-Python uses of the console using the C Runtime." +msgstr "" + +#: ../../c-api/init.rst:382 +msgid "" +"This function works like :c:func:`Py_Initialize` if *initsigs* is ``1``. If " +"*initsigs* is ``0``, it skips initialization registration of signal " +"handlers, which may be useful when CPython is embedded as part of a larger " +"application." +msgstr "" + +#: ../../c-api/init.rst:392 +msgid "" +"Initialize Python from *config* configuration, as described in :ref:`init-" +"from-config`." +msgstr "" + +#: ../../c-api/init.rst:395 +msgid "" +"See the :ref:`init-config` section for details on pre-initializing the " +"interpreter, populating the runtime configuration structure, and querying " +"the returned status structure." +msgstr "" + +#: ../../c-api/init.rst:402 +msgid "" +"Return true (nonzero) when the Python interpreter has been initialized, " +"false (zero) if not. After :c:func:`Py_FinalizeEx` is called, this returns " +"false until :c:func:`Py_Initialize` is called again." +msgstr "" + +#: ../../c-api/init.rst:409 +msgid "" +"Return true (non-zero) if the main Python interpreter is :term:`shutting " +"down `. Return false (zero) otherwise." +msgstr "" + +#: ../../c-api/init.rst:417 +msgid "" +"Undo all initializations made by :c:func:`Py_Initialize` and subsequent use " +"of Python/C API functions, and destroy all sub-interpreters (see :c:func:" +"`Py_NewInterpreter` below) that were created and not yet destroyed since the " +"last call to :c:func:`Py_Initialize`. This is a no-op when called for a " +"second time (without calling :c:func:`Py_Initialize` again first)." +msgstr "" + +#: ../../c-api/init.rst:423 +msgid "" +"Since this is the reverse of :c:func:`Py_Initialize`, it should be called in " +"the same thread with the same interpreter active. That means the main " +"thread and the main interpreter. This should never be called while :c:func:" +"`Py_RunMain` is running." +msgstr "" + +#: ../../c-api/init.rst:428 +msgid "" +"Normally the return value is ``0``. If there were errors during finalization " +"(flushing buffered data), ``-1`` is returned." +msgstr "" + +#: ../../c-api/init.rst:432 +msgid "" +"Note that Python will do a best effort at freeing all memory allocated by " +"the Python interpreter. Therefore, any C-Extension should make sure to " +"correctly clean up all of the preveiously allocated PyObjects before using " +"them in subsequent calls to :c:func:`Py_Initialize`. Otherwise it could " +"introduce vulnerabilities and incorrect behavior." +msgstr "" + +#: ../../c-api/init.rst:438 +msgid "" +"This function is provided for a number of reasons. An embedding application " +"might want to restart Python without having to restart the application " +"itself. An application that has loaded the Python interpreter from a " +"dynamically loadable library (or DLL) might want to free all memory " +"allocated by Python before unloading the DLL. During a hunt for memory leaks " +"in an application a developer might want to free all memory allocated by " +"Python before exiting from the application." +msgstr "" + +#: ../../c-api/init.rst:446 +msgid "" +"**Bugs and caveats:** The destruction of modules and objects in modules is " +"done in random order; this may cause destructors (:meth:`~object.__del__` " +"methods) to fail when they depend on other objects (even functions) or " +"modules. Dynamically loaded extension modules loaded by Python are not " +"unloaded. Small amounts of memory allocated by the Python interpreter may " +"not be freed (if you find a leak, please report it). Memory tied up in " +"circular references between objects is not freed. Interned strings will all " +"be deallocated regardless of their reference count. Some memory allocated by " +"extension modules may not be freed. Some extensions may not work properly " +"if their initialization routine is called more than once; this can happen if " +"an application calls :c:func:`Py_Initialize` and :c:func:`Py_FinalizeEx` " +"more than once. :c:func:`Py_FinalizeEx` must not be called recursively from " +"within itself. Therefore, it must not be called by any code that may be run " +"as part of the interpreter shutdown process, such as :py:mod:`atexit` " +"handlers, object finalizers, or any code that may be run while flushing the " +"stdout and stderr files." +msgstr "" + +#: ../../c-api/init.rst:462 +msgid "" +"Raises an :ref:`auditing event ` ``cpython." +"_PySys_ClearAuditHooks`` with no arguments." +msgstr "" +"引發一個不附帶引數的\\ :ref:`稽核事件 ` ``cpython." +"_PySys_ClearAuditHooks``。" + +#: ../../c-api/init.rst:469 +msgid "" +"This is a backwards-compatible version of :c:func:`Py_FinalizeEx` that " +"disregards the return value." +msgstr "" + +#: ../../c-api/init.rst:475 +msgid "" +"Similar to :c:func:`Py_Main` but *argv* is an array of bytes strings, " +"allowing the calling application to delegate the text decoding step to the " +"CPython runtime." +msgstr "" + +#: ../../c-api/init.rst:484 +msgid "" +"The main program for the standard interpreter, encapsulating a full " +"initialization/finalization cycle, as well as additional behaviour to " +"implement reading configurations settings from the environment and command " +"line, and then executing ``__main__`` in accordance with :ref:`using-on-" +"cmdline`." +msgstr "" + +#: ../../c-api/init.rst:490 +msgid "" +"This is made available for programs which wish to support the full CPython " +"command line interface, rather than just embedding a Python runtime in a " +"larger application." +msgstr "" + +#: ../../c-api/init.rst:494 +msgid "" +"The *argc* and *argv* parameters are similar to those which are passed to a " +"C program's :c:func:`main` function, except that the *argv* entries are " +"first converted to ``wchar_t`` using :c:func:`Py_DecodeLocale`. It is also " +"important to note that the argument list entries may be modified to point to " +"strings other than those passed in (however, the contents of the strings " +"pointed to by the argument list are not modified)." +msgstr "" + +#: ../../c-api/init.rst:501 +msgid "" +"The return value is ``2`` if the argument list does not represent a valid " +"Python command line, and otherwise the same as :c:func:`Py_RunMain`." +msgstr "" + +#: ../../c-api/init.rst:504 +msgid "" +"In terms of the CPython runtime configuration APIs documented in the :ref:" +"`runtime configuration ` section (and without accounting for " +"error handling), ``Py_Main`` is approximately equivalent to::" +msgstr "" + +#: ../../c-api/init.rst:508 +msgid "" +"PyConfig config;\n" +"PyConfig_InitPythonConfig(&config);\n" +"PyConfig_SetArgv(&config, argc, argv);\n" +"Py_InitializeFromConfig(&config);\n" +"PyConfig_Clear(&config);\n" +"\n" +"Py_RunMain();" +msgstr "" + +#: ../../c-api/init.rst:516 +msgid "" +"In normal usage, an embedding application will call this function *instead* " +"of calling :c:func:`Py_Initialize`, :c:func:`Py_InitializeEx` or :c:func:" +"`Py_InitializeFromConfig` directly, and all settings will be applied as " +"described elsewhere in this documentation. If this function is instead " +"called *after* a preceding runtime initialization API call, then exactly " +"which environmental and command line configuration settings will be updated " +"is version dependent (as it depends on which settings correctly support " +"being modified after they have already been set once when the runtime was " +"first initialized)." +msgstr "" + +#: ../../c-api/init.rst:529 +msgid "Executes the main module in a fully configured CPython runtime." +msgstr "" + +#: ../../c-api/init.rst:531 +msgid "" +"Executes the command (:c:member:`PyConfig.run_command`), the script (:c:" +"member:`PyConfig.run_filename`) or the module (:c:member:`PyConfig." +"run_module`) specified on the command line or in the configuration. If none " +"of these values are set, runs the interactive Python prompt (REPL) using the " +"``__main__`` module's global namespace." +msgstr "" + +#: ../../c-api/init.rst:537 +msgid "" +"If :c:member:`PyConfig.inspect` is not set (the default), the return value " +"will be ``0`` if the interpreter exits normally (that is, without raising an " +"exception), the exit status of an unhandled :exc:`SystemExit`, or ``1`` for " +"any other unhandled exception." +msgstr "" + +#: ../../c-api/init.rst:542 +msgid "" +"If :c:member:`PyConfig.inspect` is set (such as when the :option:`-i` option " +"is used), rather than returning when the interpreter exits, execution will " +"instead resume in an interactive Python prompt (REPL) using the ``__main__`` " +"module's global namespace. If the interpreter exited with an exception, it " +"is immediately raised in the REPL session. The function return value is then " +"determined by the way the *REPL session* terminates: ``0``, ``1``, or the " +"status of a :exc:`SystemExit`, as specified above." +msgstr "" + +#: ../../c-api/init.rst:550 +msgid "" +"This function always finalizes the Python interpreter before it returns." +msgstr "" + +#: ../../c-api/init.rst:552 +msgid "" +"See :ref:`Python Configuration ` for an example of a " +"customized Python that always runs in isolated mode using :c:func:" +"`Py_RunMain`." +msgstr "" + +#: ../../c-api/init.rst:558 +msgid "" +"Register an :mod:`atexit` callback for the target interpreter *interp*. This " +"is similar to :c:func:`Py_AtExit`, but takes an explicit interpreter and " +"data pointer for the callback." +msgstr "" + +#: ../../c-api/init.rst:562 +msgid "There must be an :term:`attached thread state` for *interp*." +msgstr "" + +#: ../../c-api/init.rst:567 +msgid "Process-wide parameters" +msgstr "" + +#: ../../c-api/init.rst:577 +msgid "" +"This API is kept for backward compatibility: setting :c:member:`PyConfig." +"program_name` should be used instead, see :ref:`Python Initialization " +"Configuration `." +msgstr "" + +#: ../../c-api/init.rst:581 +msgid "" +"This function should be called before :c:func:`Py_Initialize` is called for " +"the first time, if it is called at all. It tells the interpreter the value " +"of the ``argv[0]`` argument to the :c:func:`main` function of the program " +"(converted to wide characters). This is used by :c:func:`Py_GetPath` and " +"some other functions below to find the Python run-time libraries relative to " +"the interpreter executable. The default value is ``'python'``. The " +"argument should point to a zero-terminated wide character string in static " +"storage whose contents will not change for the duration of the program's " +"execution. No code in the Python interpreter will change the contents of " +"this storage." +msgstr "" + +#: ../../c-api/init.rst:592 ../../c-api/init.rst:840 ../../c-api/init.rst:876 +#: ../../c-api/init.rst:902 +msgid "" +"Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a :c:expr:" +"`wchar_t*` string." +msgstr "" + +#: ../../c-api/init.rst:600 +msgid "" +"Return the program name set with :c:member:`PyConfig.program_name`, or the " +"default. The returned string points into static storage; the caller should " +"not modify its value." +msgstr "" + +#: ../../c-api/init.rst:604 ../../c-api/init.rst:627 ../../c-api/init.rst:675 +#: ../../c-api/init.rst:699 ../../c-api/init.rst:726 ../../c-api/init.rst:914 +msgid "" +"This function should not be called before :c:func:`Py_Initialize`, otherwise " +"it returns ``NULL``." +msgstr "此函式不應該在 :c:func:`Py_Initialize` 之前呼叫，否則會回傳 ``NULL``。" + +#: ../../c-api/init.rst:607 ../../c-api/init.rst:630 ../../c-api/init.rst:678 +#: ../../c-api/init.rst:702 ../../c-api/init.rst:731 ../../c-api/init.rst:917 +msgid "It now returns ``NULL`` if called before :c:func:`Py_Initialize`." +msgstr "如果在 :c:func:`Py_Initialize` 之前呼叫，現在會回傳 ``NULL``。" + +#: ../../c-api/init.rst:610 ../../c-api/init.rst:705 +msgid "" +"Use :c:func:`PyConfig_Get(\"executable\") ` (:data:`sys." +"executable`) instead." +msgstr "" + +#: ../../c-api/init.rst:617 +msgid "" +"Return the *prefix* for installed platform-independent files. This is " +"derived through a number of complicated rules from the program name set " +"with :c:member:`PyConfig.program_name` and some environment variables; for " +"example, if the program name is ``'/usr/local/bin/python'``, the prefix is " +"``'/usr/local'``. The returned string points into static storage; the caller " +"should not modify its value. This corresponds to the :makevar:`prefix` " +"variable in the top-level :file:`Makefile` and the :option:`--prefix` " +"argument to the :program:`configure` script at build time. The value is " +"available to Python code as ``sys.base_prefix``. It is only useful on Unix. " +"See also the next function." +msgstr "" + +#: ../../c-api/init.rst:633 +msgid "" +"Use :c:func:`PyConfig_Get(\"base_prefix\") ` (:data:`sys." +"base_prefix`) instead. Use :c:func:`PyConfig_Get(\"prefix\") ` " +"(:data:`sys.prefix`) if :ref:`virtual environments ` need to be " +"handled." +msgstr "" + +#: ../../c-api/init.rst:642 +msgid "" +"Return the *exec-prefix* for installed platform-*dependent* files. This is " +"derived through a number of complicated rules from the program name set " +"with :c:member:`PyConfig.program_name` and some environment variables; for " +"example, if the program name is ``'/usr/local/bin/python'``, the exec-prefix " +"is ``'/usr/local'``. The returned string points into static storage; the " +"caller should not modify its value. This corresponds to the :makevar:" +"`exec_prefix` variable in the top-level :file:`Makefile` and the ``--exec-" +"prefix`` argument to the :program:`configure` script at build time. The " +"value is available to Python code as ``sys.base_exec_prefix``. It is only " +"useful on Unix." +msgstr "" + +#: ../../c-api/init.rst:653 +msgid "" +"Background: The exec-prefix differs from the prefix when platform dependent " +"files (such as executables and shared libraries) are installed in a " +"different directory tree. In a typical installation, platform dependent " +"files may be installed in the :file:`/usr/local/plat` subtree while platform " +"independent may be installed in :file:`/usr/local`." +msgstr "" + +#: ../../c-api/init.rst:659 +msgid "" +"Generally speaking, a platform is a combination of hardware and software " +"families, e.g. Sparc machines running the Solaris 2.x operating system are " +"considered the same platform, but Intel machines running Solaris 2.x are " +"another platform, and Intel machines running Linux are yet another " +"platform. Different major revisions of the same operating system generally " +"also form different platforms. Non-Unix operating systems are a different " +"story; the installation strategies on those systems are so different that " +"the prefix and exec-prefix are meaningless, and set to the empty string. " +"Note that compiled Python bytecode files are platform independent (but not " +"independent from the Python version by which they were compiled!)." +msgstr "" + +#: ../../c-api/init.rst:670 +msgid "" +"System administrators will know how to configure the :program:`mount` or :" +"program:`automount` programs to share :file:`/usr/local` between platforms " +"while having :file:`/usr/local/plat` be a different filesystem for each " +"platform." +msgstr "" + +#: ../../c-api/init.rst:681 +msgid "" +"Use :c:func:`PyConfig_Get(\"base_exec_prefix\") ` (:data:`sys." +"base_exec_prefix`) instead. Use :c:func:`PyConfig_Get(\"exec_prefix\") " +"` (:data:`sys.exec_prefix`) if :ref:`virtual environments " +"` need to be handled." +msgstr "" + +#: ../../c-api/init.rst:693 +msgid "" +"Return the full program name of the Python executable; this is computed as " +"a side-effect of deriving the default module search path from the program " +"name (set by :c:member:`PyConfig.program_name`). The returned string points " +"into static storage; the caller should not modify its value. The value is " +"available to Python code as ``sys.executable``." +msgstr "" + +#: ../../c-api/init.rst:716 +msgid "" +"Return the default module search path; this is computed from the program " +"name (set by :c:member:`PyConfig.program_name`) and some environment " +"variables. The returned string consists of a series of directory names " +"separated by a platform dependent delimiter character. The delimiter " +"character is ``':'`` on Unix and macOS, ``';'`` on Windows. The returned " +"string points into static storage; the caller should not modify its value. " +"The list :data:`sys.path` is initialized with this value on interpreter " +"startup; it can be (and usually is) modified later to change the search path " +"for loading modules." +msgstr "" + +#: ../../c-api/init.rst:734 +msgid "" +"Use :c:func:`PyConfig_Get(\"module_search_paths\") ` (:data:" +"`sys.path`) instead." +msgstr "" + +#: ../../c-api/init.rst:740 +msgid "" +"Return the version of this Python interpreter. This is a string that looks " +"something like ::" +msgstr "" + +#: ../../c-api/init.rst:743 +msgid "\"3.0a5+ (py3k:63103M, May 12 2008, 00:53:55) \\n[GCC 4.2.3]\"" +msgstr "\"3.0a5+ (py3k:63103M, May 12 2008, 00:53:55) \\n[GCC 4.2.3]\"" + +#: ../../c-api/init.rst:747 +msgid "" +"The first word (up to the first space character) is the current Python " +"version; the first characters are the major and minor version separated by a " +"period. The returned string points into static storage; the caller should " +"not modify its value. The value is available to Python code as :data:`sys." +"version`." +msgstr "" + +#: ../../c-api/init.rst:752 +msgid "See also the :c:var:`Py_Version` constant." +msgstr "另請參閱 :c:var:`Py_Version` 常數。" + +#: ../../c-api/init.rst:759 +msgid "" +"Return the platform identifier for the current platform. On Unix, this is " +"formed from the \"official\" name of the operating system, converted to " +"lower case, followed by the major revision number; e.g., for Solaris 2.x, " +"which is also known as SunOS 5.x, the value is ``'sunos5'``. On macOS, it " +"is ``'darwin'``. On Windows, it is ``'win'``. The returned string points " +"into static storage; the caller should not modify its value. The value is " +"available to Python code as ``sys.platform``." +msgstr "" + +#: ../../c-api/init.rst:770 +msgid "" +"Return the official copyright string for the current Python version, for " +"example" +msgstr "" + +#: ../../c-api/init.rst:772 +msgid "``'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam'``" +msgstr "``'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam'``" + +#: ../../c-api/init.rst:776 +msgid "" +"The returned string points into static storage; the caller should not modify " +"its value. The value is available to Python code as ``sys.copyright``." +msgstr "" + +#: ../../c-api/init.rst:782 +msgid "" +"Return an indication of the compiler used to build the current Python " +"version, in square brackets, for example::" +msgstr "" + +#: ../../c-api/init.rst:785 +msgid "\"[GCC 2.7.2.2]\"" +msgstr "\"[GCC 2.7.2.2]\"" + +#: ../../c-api/init.rst:789 ../../c-api/init.rst:803 +msgid "" +"The returned string points into static storage; the caller should not modify " +"its value. The value is available to Python code as part of the variable " +"``sys.version``." +msgstr "" + +#: ../../c-api/init.rst:796 +msgid "" +"Return information about the sequence number and build date and time of the " +"current Python interpreter instance, for example ::" +msgstr "" + +#: ../../c-api/init.rst:799 +msgid "\"#67, Aug 1 1997, 22:34:28\"" +msgstr "\"#67, Aug 1 1997, 22:34:28\"" + +#: ../../c-api/init.rst:815 +msgid "" +"This API is kept for backward compatibility: setting :c:member:`PyConfig." +"argv`, :c:member:`PyConfig.parse_argv` and :c:member:`PyConfig.safe_path` " +"should be used instead, see :ref:`Python Initialization Configuration `." +msgstr "" + +#: ../../c-api/init.rst:820 +msgid "" +"Set :data:`sys.argv` based on *argc* and *argv*. These parameters are " +"similar to those passed to the program's :c:func:`main` function with the " +"difference that the first entry should refer to the script file to be " +"executed rather than the executable hosting the Python interpreter. If " +"there isn't a script that will be run, the first entry in *argv* can be an " +"empty string. If this function fails to initialize :data:`sys.argv`, a " +"fatal condition is signalled using :c:func:`Py_FatalError`." +msgstr "" + +#: ../../c-api/init.rst:828 +msgid "" +"If *updatepath* is zero, this is all the function does. If *updatepath* is " +"non-zero, the function also modifies :data:`sys.path` according to the " +"following algorithm:" +msgstr "" + +#: ../../c-api/init.rst:832 +msgid "" +"If the name of an existing script is passed in ``argv[0]``, the absolute " +"path of the directory where the script is located is prepended to :data:`sys." +"path`." +msgstr "" + +#: ../../c-api/init.rst:835 +msgid "" +"Otherwise (that is, if *argc* is ``0`` or ``argv[0]`` doesn't point to an " +"existing file name), an empty string is prepended to :data:`sys.path`, which " +"is the same as prepending the current working directory (``\".\"``)." +msgstr "" + +#: ../../c-api/init.rst:843 ../../c-api/init.rst:879 +msgid "" +"See also :c:member:`PyConfig.orig_argv` and :c:member:`PyConfig.argv` " +"members of the :ref:`Python Initialization Configuration `." +msgstr "" + +#: ../../c-api/init.rst:847 +msgid "" +"It is recommended that applications embedding the Python interpreter for " +"purposes other than executing a single script pass ``0`` as *updatepath*, " +"and update :data:`sys.path` themselves if desired. See :cve:`2008-5983`." +msgstr "" + +#: ../../c-api/init.rst:852 +msgid "" +"On versions before 3.1.3, you can achieve the same effect by manually " +"popping the first :data:`sys.path` element after having called :c:func:" +"`PySys_SetArgv`, for example using::" +msgstr "" + +#: ../../c-api/init.rst:856 +msgid "PyRun_SimpleString(\"import sys; sys.path.pop(0)\\n\");" +msgstr "PyRun_SimpleString(\"import sys; sys.path.pop(0)\\n\");" + +#: ../../c-api/init.rst:868 +msgid "" +"This API is kept for backward compatibility: setting :c:member:`PyConfig." +"argv` and :c:member:`PyConfig.parse_argv` should be used instead, see :ref:" +"`Python Initialization Configuration `." +msgstr "" + +#: ../../c-api/init.rst:872 +msgid "" +"This function works like :c:func:`PySys_SetArgvEx` with *updatepath* set to " +"``1`` unless the :program:`python` interpreter was started with the :option:" +"`-I`." +msgstr "" + +#: ../../c-api/init.rst:882 +msgid "The *updatepath* value depends on :option:`-I`." +msgstr "" + +#: ../../c-api/init.rst:889 +msgid "" +"This API is kept for backward compatibility: setting :c:member:`PyConfig." +"home` should be used instead, see :ref:`Python Initialization Configuration " +"`." +msgstr "" + +#: ../../c-api/init.rst:893 +msgid "" +"Set the default \"home\" directory, that is, the location of the standard " +"Python libraries. See :envvar:`PYTHONHOME` for the meaning of the argument " +"string." +msgstr "" + +#: ../../c-api/init.rst:897 +msgid "" +"The argument should point to a zero-terminated character string in static " +"storage whose contents will not change for the duration of the program's " +"execution. No code in the Python interpreter will change the contents of " +"this storage." +msgstr "" + +#: ../../c-api/init.rst:910 +msgid "" +"Return the default \"home\", that is, the value set by :c:member:`PyConfig." +"home`, or the value of the :envvar:`PYTHONHOME` environment variable if it " +"is set." +msgstr "" + +#: ../../c-api/init.rst:920 +msgid "" +"Use :c:func:`PyConfig_Get(\"home\") ` or the :envvar:" +"`PYTHONHOME` environment variable instead." +msgstr "" +"改為使用 :c:func:`PyConfig_Get(\"home\") ` 或 :envvar:" +"`PYTHONHOME` 環境變數。" + +#: ../../c-api/init.rst:928 +msgid "Thread State and the Global Interpreter Lock" +msgstr "" + +#: ../../c-api/init.rst:935 +msgid "" +"Unless on a :term:`free-threaded ` build of :term:`CPython`, " +"the Python interpreter is not fully thread-safe. In order to support multi-" +"threaded Python programs, there's a global lock, called the :term:`global " +"interpreter lock` or :term:`GIL`, that must be held by the current thread " +"before it can safely access Python objects. Without the lock, even the " +"simplest operations could cause problems in a multi-threaded program: for " +"example, when two threads simultaneously increment the reference count of " +"the same object, the reference count could end up being incremented only " +"once instead of twice." +msgstr "" + +#: ../../c-api/init.rst:946 +msgid "" +"Therefore, the rule exists that only the thread that has acquired the :term:" +"`GIL` may operate on Python objects or call Python/C API functions. In order " +"to emulate concurrency of execution, the interpreter regularly tries to " +"switch threads (see :func:`sys.setswitchinterval`). The lock is also " +"released around potentially blocking I/O operations like reading or writing " +"a file, so that other Python threads can run in the meantime." +msgstr "" + +#: ../../c-api/init.rst:956 +msgid "" +"The Python interpreter keeps some thread-specific bookkeeping information " +"inside a data structure called :c:type:`PyThreadState`, known as a :term:" +"`thread state`. Each OS thread has a thread-local pointer to a :c:type:" +"`PyThreadState`; a thread state referenced by this pointer is considered to " +"be :term:`attached `." +msgstr "" + +#: ../../c-api/init.rst:961 +msgid "" +"A thread can only have one :term:`attached thread state` at a time. An " +"attached thread state is typically analogous with holding the :term:`GIL`, " +"except on :term:`free-threaded ` builds. On builds with " +"the :term:`GIL` enabled, :term:`attaching ` a thread " +"state will block until the :term:`GIL` can be acquired. However, even on " +"builds with the :term:`GIL` disabled, it is still required to have an " +"attached thread state to call most of the C API." +msgstr "" + +#: ../../c-api/init.rst:968 +msgid "" +"In general, there will always be an :term:`attached thread state` when using " +"Python's C API. Only in some specific cases (such as in a :c:macro:" +"`Py_BEGIN_ALLOW_THREADS` block) will the thread not have an attached thread " +"state. If uncertain, check if :c:func:`PyThreadState_GetUnchecked` returns " +"``NULL``." +msgstr "" + +#: ../../c-api/init.rst:974 +msgid "Detaching the thread state from extension code" +msgstr "" + +#: ../../c-api/init.rst:976 +msgid "" +"Most extension code manipulating the :term:`thread state` has the following " +"simple structure::" +msgstr "" + +#: ../../c-api/init.rst:979 +msgid "" +"Save the thread state in a local variable.\n" +"... Do some blocking I/O operation ...\n" +"Restore the thread state from the local variable." +msgstr "" + +#: ../../c-api/init.rst:983 +msgid "This is so common that a pair of macros exists to simplify it::" +msgstr "" + +#: ../../c-api/init.rst:985 +msgid "" +"Py_BEGIN_ALLOW_THREADS\n" +"... Do some blocking I/O operation ...\n" +"Py_END_ALLOW_THREADS" +msgstr "" + +#: ../../c-api/init.rst:993 +msgid "" +"The :c:macro:`Py_BEGIN_ALLOW_THREADS` macro opens a new block and declares a " +"hidden local variable; the :c:macro:`Py_END_ALLOW_THREADS` macro closes the " +"block." +msgstr "" + +#: ../../c-api/init.rst:997 +msgid "The block above expands to the following code::" +msgstr "" + +#: ../../c-api/init.rst:999 +msgid "" +"PyThreadState *_save;\n" +"\n" +"_save = PyEval_SaveThread();\n" +"... Do some blocking I/O operation ...\n" +"PyEval_RestoreThread(_save);" +msgstr "" + +#: ../../c-api/init.rst:1009 +msgid "Here is how these functions work:" +msgstr "" + +#: ../../c-api/init.rst:1011 +msgid "" +"The :term:`attached thread state` holds the :term:`GIL` for the entire " +"interpreter. When detaching the :term:`attached thread state`, the :term:" +"`GIL` is released, allowing other threads to attach a thread state to their " +"own thread, thus getting the :term:`GIL` and can start executing. The " +"pointer to the prior :term:`attached thread state` is stored as a local " +"variable. Upon reaching :c:macro:`Py_END_ALLOW_THREADS`, the thread state " +"that was previously :term:`attached ` is passed to :c:" +"func:`PyEval_RestoreThread`. This function will block until another releases " +"its :term:`thread state `, thus allowing the old :" +"term:`thread state ` to get re-attached and the C API " +"can be called again." +msgstr "" + +#: ../../c-api/init.rst:1021 +msgid "" +"For :term:`free-threaded ` builds, the :term:`GIL` is " +"normally out of the question, but detaching the :term:`thread state " +"` is still required for blocking I/O and long " +"operations. The difference is that threads don't have to wait for the :term:" +"`GIL` to be released to attach their thread state, allowing true multi-core " +"parallelism." +msgstr "" + +#: ../../c-api/init.rst:1027 +msgid "" +"Calling system I/O functions is the most common use case for detaching the :" +"term:`thread state `, but it can also be useful " +"before calling long-running computations which don't need access to Python " +"objects, such as compression or cryptographic functions operating over " +"memory buffers. For example, the standard :mod:`zlib` and :mod:`hashlib` " +"modules detach the :term:`thread state ` when " +"compressing or hashing data." +msgstr "" + +#: ../../c-api/init.rst:1038 +msgid "Non-Python created threads" +msgstr "" + +#: ../../c-api/init.rst:1040 +msgid "" +"When threads are created using the dedicated Python APIs (such as the :mod:" +"`threading` module), a thread state is automatically associated to them and " +"the code showed above is therefore correct. However, when threads are " +"created from C (for example by a third-party library with its own thread " +"management), they don't hold the :term:`GIL`, because they don't have an :" +"term:`attached thread state`." +msgstr "" + +#: ../../c-api/init.rst:1047 +msgid "" +"If you need to call Python code from these threads (often this will be part " +"of a callback API provided by the aforementioned third-party library), you " +"must first register these threads with the interpreter by creating an :term:" +"`attached thread state` before you can start using the Python/C API. When " +"you are done, you should detach the :term:`thread state `, and finally free it." +msgstr "" + +#: ../../c-api/init.rst:1054 +msgid "" +"The :c:func:`PyGILState_Ensure` and :c:func:`PyGILState_Release` functions " +"do all of the above automatically. The typical idiom for calling into " +"Python from a C thread is::" +msgstr "" + +#: ../../c-api/init.rst:1058 +msgid "" +"PyGILState_STATE gstate;\n" +"gstate = PyGILState_Ensure();\n" +"\n" +"/* Perform Python actions here. */\n" +"result = CallSomeFunction();\n" +"/* evaluate result or handle exception */\n" +"\n" +"/* Release the thread. No Python API allowed beyond this point. */\n" +"PyGILState_Release(gstate);" +msgstr "" + +#: ../../c-api/init.rst:1068 +msgid "" +"Note that the ``PyGILState_*`` functions assume there is only one global " +"interpreter (created automatically by :c:func:`Py_Initialize`). Python " +"supports the creation of additional interpreters (using :c:func:" +"`Py_NewInterpreter`), but mixing multiple interpreters and the " +"``PyGILState_*`` API is unsupported. This is because :c:func:" +"`PyGILState_Ensure` and similar functions default to :term:`attaching " +"` a :term:`thread state` for the main interpreter, " +"meaning that the thread can't safely interact with the calling " +"subinterpreter." +msgstr "" + +#: ../../c-api/init.rst:1078 +msgid "Supporting subinterpreters in non-Python threads" +msgstr "" + +#: ../../c-api/init.rst:1080 +msgid "" +"If you would like to support subinterpreters with non-Python created " +"threads, you must use the ``PyThreadState_*`` API instead of the traditional " +"``PyGILState_*`` API." +msgstr "" + +#: ../../c-api/init.rst:1084 +msgid "" +"In particular, you must store the interpreter state from the calling " +"function and pass it to :c:func:`PyThreadState_New`, which will ensure that " +"the :term:`thread state` is targeting the correct interpreter::" +msgstr "" + +#: ../../c-api/init.rst:1088 +msgid "" +"/* The return value of PyInterpreterState_Get() from the\n" +" function that created this thread. */\n" +"PyInterpreterState *interp = ThreadData->interp;\n" +"PyThreadState *tstate = PyThreadState_New(interp);\n" +"PyThreadState_Swap(tstate);\n" +"\n" +"/* GIL of the subinterpreter is now held.\n" +" Perform Python actions here. */\n" +"result = CallSomeFunction();\n" +"/* evaluate result or handle exception */\n" +"\n" +"/* Destroy the thread state. No Python API allowed beyond this point. */\n" +"PyThreadState_Clear(tstate);\n" +"PyThreadState_DeleteCurrent();" +msgstr "" + +#: ../../c-api/init.rst:1106 +msgid "Cautions about fork()" +msgstr "" + +#: ../../c-api/init.rst:1108 +msgid "" +"Another important thing to note about threads is their behaviour in the face " +"of the C :c:func:`fork` call. On most systems with :c:func:`fork`, after a " +"process forks only the thread that issued the fork will exist. This has a " +"concrete impact both on how locks must be handled and on all stored state in " +"CPython's runtime." +msgstr "" + +#: ../../c-api/init.rst:1114 +msgid "" +"The fact that only the \"current\" thread remains means any locks held by " +"other threads will never be released. Python solves this for :func:`os.fork` " +"by acquiring the locks it uses internally before the fork, and releasing " +"them afterwards. In addition, it resets any :ref:`lock-objects` in the " +"child. When extending or embedding Python, there is no way to inform Python " +"of additional (non-Python) locks that need to be acquired before or reset " +"after a fork. OS facilities such as :c:func:`!pthread_atfork` would need to " +"be used to accomplish the same thing. Additionally, when extending or " +"embedding Python, calling :c:func:`fork` directly rather than through :func:" +"`os.fork` (and returning to or calling into Python) may result in a deadlock " +"by one of Python's internal locks being held by a thread that is defunct " +"after the fork. :c:func:`PyOS_AfterFork_Child` tries to reset the necessary " +"locks, but is not always able to." +msgstr "" + +#: ../../c-api/init.rst:1129 +msgid "" +"The fact that all other threads go away also means that CPython's runtime " +"state there must be cleaned up properly, which :func:`os.fork` does. This " +"means finalizing all other :c:type:`PyThreadState` objects belonging to the " +"current interpreter and all other :c:type:`PyInterpreterState` objects. Due " +"to this and the special nature of the :ref:`\"main\" interpreter `, :c:func:`fork` should only be called in that " +"interpreter's \"main\" thread, where the CPython global runtime was " +"originally initialized. The only exception is if :c:func:`exec` will be " +"called immediately after." +msgstr "" + +#: ../../c-api/init.rst:1143 +msgid "Cautions regarding runtime finalization" +msgstr "" + +#: ../../c-api/init.rst:1145 +msgid "" +"In the late stage of :term:`interpreter shutdown`, after attempting to wait " +"for non-daemon threads to exit (though this can be interrupted by :class:" +"`KeyboardInterrupt`) and running the :mod:`atexit` functions, the runtime is " +"marked as *finalizing*: :c:func:`Py_IsFinalizing` and :func:`sys." +"is_finalizing` return true. At this point, only the *finalization thread* " +"that initiated finalization (typically the main thread) is allowed to " +"acquire the :term:`GIL`." +msgstr "" + +#: ../../c-api/init.rst:1153 +msgid "" +"If any thread, other than the finalization thread, attempts to attach a :" +"term:`thread state` during finalization, either explicitly or implicitly, " +"the thread enters **a permanently blocked state** where it remains until the " +"program exits. In most cases this is harmless, but this can result in " +"deadlock if a later stage of finalization attempts to acquire a lock owned " +"by the blocked thread, or otherwise waits on the blocked thread." +msgstr "" + +#: ../../c-api/init.rst:1160 +msgid "" +"Gross? Yes. This prevents random crashes and/or unexpectedly skipped C++ " +"finalizations further up the call stack when such threads were forcibly " +"exited here in CPython 3.13 and earlier. The CPython runtime :term:`thread " +"state` C APIs have never had any error reporting or handling expectations " +"at :term:`thread state` attachment time that would've allowed for graceful " +"exit from this situation. Changing that would require new stable C APIs and " +"rewriting the majority of C code in the CPython ecosystem to use those with " +"error handling." +msgstr "" + +#: ../../c-api/init.rst:1170 +msgid "High-level API" +msgstr "高階 API" + +#: ../../c-api/init.rst:1172 +msgid "" +"These are the most commonly used types and functions when writing C " +"extension code, or when embedding the Python interpreter:" +msgstr "" + +#: ../../c-api/init.rst:1177 +msgid "" +"This data structure represents the state shared by a number of cooperating " +"threads. Threads belonging to the same interpreter share their module " +"administration and a few other internal items. There are no public members " +"in this structure." +msgstr "" + +#: ../../c-api/init.rst:1182 +msgid "" +"Threads belonging to different interpreters initially share nothing, except " +"process state like available memory, open file descriptors and such. The " +"global interpreter lock is also shared by all threads, regardless of to " +"which interpreter they belong." +msgstr "" + +#: ../../c-api/init.rst:1189 +msgid "" +":pep:`684` introduced the possibility of a :ref:`per-interpreter GIL `. See :c:func:`Py_NewInterpreterFromConfig`." +msgstr "" + +#: ../../c-api/init.rst:1196 +msgid "" +"This data structure represents the state of a single thread. The only " +"public data member is:" +msgstr "" + +#: ../../c-api/init.rst:1201 +msgid "This thread's interpreter state." +msgstr "" + +#: ../../c-api/init.rst:1212 +msgid "Deprecated function which does nothing." +msgstr "" + +#: ../../c-api/init.rst:1214 +msgid "" +"In Python 3.6 and older, this function created the GIL if it didn't exist." +msgstr "" + +#: ../../c-api/init.rst:1216 +msgid "The function now does nothing." +msgstr "此函式現在不會做任何事情。" + +#: ../../c-api/init.rst:1219 +msgid "" +"This function is now called by :c:func:`Py_Initialize()`, so you don't have " +"to call it yourself anymore." +msgstr "" + +#: ../../c-api/init.rst:1223 +msgid "" +"This function cannot be called before :c:func:`Py_Initialize()` anymore." +msgstr "" + +#: ../../c-api/init.rst:1233 +msgid "" +"Detach the :term:`attached thread state` and return it. The thread will have " +"no :term:`thread state` upon returning." +msgstr "" + +#: ../../c-api/init.rst:1239 +msgid "" +"Set the :term:`attached thread state` to *tstate*. The passed :term:`thread " +"state` **should not** be :term:`attached `, otherwise " +"deadlock ensues. *tstate* will be attached upon returning." +msgstr "" + +#: ../../c-api/init.rst:1244 ../../c-api/init.rst:1688 +msgid "" +"Calling this function from a thread when the runtime is finalizing will hang " +"the thread until the program exits, even if the thread was not created by " +"Python. Refer to :ref:`cautions-regarding-runtime-finalization` for more " +"details." +msgstr "" + +#: ../../c-api/init.rst:1249 ../../c-api/init.rst:1333 +#: ../../c-api/init.rst:1698 +msgid "" +"Hangs the current thread, rather than terminating it, if called while the " +"interpreter is finalizing." +msgstr "" + +#: ../../c-api/init.rst:1255 +msgid "" +"Return the :term:`attached thread state`. If the thread has no attached " +"thread state, (such as when inside of :c:macro:`Py_BEGIN_ALLOW_THREADS` " +"block), then this issues a fatal error (so that the caller needn't check for " +"``NULL``)." +msgstr "" + +#: ../../c-api/init.rst:1260 +msgid "See also :c:func:`PyThreadState_GetUnchecked`." +msgstr "也請見 :c:func:`PyThreadState_GetUnchecked`。" + +#: ../../c-api/init.rst:1264 +msgid "" +"Similar to :c:func:`PyThreadState_Get`, but don't kill the process with a " +"fatal error if it is NULL. The caller is responsible to check if the result " +"is NULL." +msgstr "" + +#: ../../c-api/init.rst:1268 +msgid "" +"In Python 3.5 to 3.12, the function was private and known as " +"``_PyThreadState_UncheckedGet()``." +msgstr "" + +#: ../../c-api/init.rst:1275 +msgid "" +"Set the :term:`attached thread state` to *tstate*, and return the :term:" +"`thread state` that was attached prior to calling." +msgstr "" + +#: ../../c-api/init.rst:1278 +msgid "" +"This function is safe to call without an :term:`attached thread state`; it " +"will simply return ``NULL`` indicating that there was no prior thread state." +msgstr "" + +#: ../../c-api/init.rst:1282 +msgid ":c:func:`PyEval_ReleaseThread`" +msgstr ":c:func:`PyEval_ReleaseThread`" + +#: ../../c-api/init.rst:1285 +msgid "" +"Similar to :c:func:`PyGILState_Ensure`, this function will hang the thread " +"if the runtime is finalizing." +msgstr "" + +#: ../../c-api/init.rst:1289 +msgid "" +"The following functions use thread-local storage, and are not compatible " +"with sub-interpreters:" +msgstr "" + +#: ../../c-api/init.rst:1294 +msgid "" +"The type of the value returned by :c:func:`PyGILState_Ensure` and passed to :" +"c:func:`PyGILState_Release`." +msgstr "" + +#: ../../c-api/init.rst:1299 +msgid "The GIL was already held when :c:func:`PyGILState_Ensure` was called." +msgstr "" + +#: ../../c-api/init.rst:1303 +msgid "The GIL was not held when :c:func:`PyGILState_Ensure` was called." +msgstr "" + +#: ../../c-api/init.rst:1307 +msgid "" +"Ensure that the current thread is ready to call the Python C API regardless " +"of the current state of Python, or of the :term:`attached thread state`. " +"This may be called as many times as desired by a thread as long as each call " +"is matched with a call to :c:func:`PyGILState_Release`. In general, other " +"thread-related APIs may be used between :c:func:`PyGILState_Ensure` and :c:" +"func:`PyGILState_Release` calls as long as the thread state is restored to " +"its previous state before the Release(). For example, normal usage of the :" +"c:macro:`Py_BEGIN_ALLOW_THREADS` and :c:macro:`Py_END_ALLOW_THREADS` macros " +"is acceptable." +msgstr "" + +#: ../../c-api/init.rst:1317 +msgid "" +"The return value is an opaque \"handle\" to the :term:`attached thread " +"state` when :c:func:`PyGILState_Ensure` was called, and must be passed to :c:" +"func:`PyGILState_Release` to ensure Python is left in the same state. Even " +"though recursive calls are allowed, these handles *cannot* be shared - each " +"unique call to :c:func:`PyGILState_Ensure` must save the handle for its call " +"to :c:func:`PyGILState_Release`." +msgstr "" + +#: ../../c-api/init.rst:1324 +msgid "" +"When the function returns, there will be an :term:`attached thread state` " +"and the thread will be able to call arbitrary Python code. Failure is a " +"fatal error." +msgstr "" + +#: ../../c-api/init.rst:1328 +msgid "" +"Calling this function when the runtime is finalizing is unsafe. Doing so " +"will either hang the thread until the program ends, or fully crash the " +"interpreter in rare cases. Refer to :ref:`cautions-regarding-runtime-" +"finalization` for more details." +msgstr "" + +#: ../../c-api/init.rst:1339 +msgid "" +"Release any resources previously acquired. After this call, Python's state " +"will be the same as it was prior to the corresponding :c:func:" +"`PyGILState_Ensure` call (but generally this state will be unknown to the " +"caller, hence the use of the GILState API)." +msgstr "" + +#: ../../c-api/init.rst:1344 +msgid "" +"Every call to :c:func:`PyGILState_Ensure` must be matched by a call to :c:" +"func:`PyGILState_Release` on the same thread." +msgstr "" + +#: ../../c-api/init.rst:1349 +msgid "" +"Get the :term:`attached thread state` for this thread. May return ``NULL`` " +"if no GILState API has been used on the current thread. Note that the main " +"thread always has such a thread-state, even if no auto-thread-state call has " +"been made on the main thread. This is mainly a helper/diagnostic function." +msgstr "" + +#: ../../c-api/init.rst:1355 +msgid "" +"This function may return non-``NULL`` even when the :term:`thread state` is " +"detached. Prefer :c:func:`PyThreadState_Get` or :c:func:" +"`PyThreadState_GetUnchecked` for most cases." +msgstr "" + +#: ../../c-api/init.rst:1360 +msgid ":c:func:`PyThreadState_Get`" +msgstr ":c:func:`PyThreadState_Get`" + +#: ../../c-api/init.rst:1364 +msgid "" +"Return ``1`` if the current thread is holding the :term:`GIL` and ``0`` " +"otherwise. This function can be called from any thread at any time. Only if " +"it has had its :term:`thread state ` initialized via :" +"c:func:`PyGILState_Ensure` will it return ``1``. This is mainly a helper/" +"diagnostic function. It can be useful for example in callback contexts or " +"memory allocation functions when knowing that the :term:`GIL` is locked can " +"allow the caller to perform sensitive actions or otherwise behave " +"differently." +msgstr "" + +#: ../../c-api/init.rst:1374 +msgid "" +"If the current Python process has ever created a subinterpreter, this " +"function will *always* return ``1``. Prefer :c:func:" +"`PyThreadState_GetUnchecked` for most cases." +msgstr "" + +#: ../../c-api/init.rst:1381 +msgid "" +"The following macros are normally used without a trailing semicolon; look " +"for example usage in the Python source distribution." +msgstr "" + +#: ../../c-api/init.rst:1387 +msgid "" +"This macro expands to ``{ PyThreadState *_save; _save = PyEval_SaveThread();" +"``. Note that it contains an opening brace; it must be matched with a " +"following :c:macro:`Py_END_ALLOW_THREADS` macro. See above for further " +"discussion of this macro." +msgstr "" + +#: ../../c-api/init.rst:1395 +msgid "" +"This macro expands to ``PyEval_RestoreThread(_save); }``. Note that it " +"contains a closing brace; it must be matched with an earlier :c:macro:" +"`Py_BEGIN_ALLOW_THREADS` macro. See above for further discussion of this " +"macro." +msgstr "" + +#: ../../c-api/init.rst:1403 +msgid "" +"This macro expands to ``PyEval_RestoreThread(_save);``: it is equivalent to :" +"c:macro:`Py_END_ALLOW_THREADS` without the closing brace." +msgstr "" + +#: ../../c-api/init.rst:1409 +msgid "" +"This macro expands to ``_save = PyEval_SaveThread();``: it is equivalent to :" +"c:macro:`Py_BEGIN_ALLOW_THREADS` without the opening brace and variable " +"declaration." +msgstr "" + +#: ../../c-api/init.rst:1415 +msgid "Low-level API" +msgstr "低階 API" + +#: ../../c-api/init.rst:1417 +msgid "" +"All of the following functions must be called after :c:func:`Py_Initialize`." +msgstr "" + +#: ../../c-api/init.rst:1419 +msgid "" +":c:func:`Py_Initialize()` now initializes the :term:`GIL` and sets an :term:" +"`attached thread state`." +msgstr "" + +#: ../../c-api/init.rst:1426 +msgid "" +"Create a new interpreter state object. An :term:`attached thread state` is " +"not needed, but may optionally exist if it is necessary to serialize calls " +"to this function." +msgstr "" + +#: ../../c-api/init.rst:1430 +msgid "" +"Raises an :ref:`auditing event ` ``cpython." +"PyInterpreterState_New`` with no arguments." +msgstr "" +"引發一個不附帶引數的\\ :ref:`稽核事件 ` ``cpython." +"PyInterpreterState_New``。" + +#: ../../c-api/init.rst:1435 +msgid "" +"Reset all information in an interpreter state object. There must be an :" +"term:`attached thread state` for the interpreter." +msgstr "" + +#: ../../c-api/init.rst:1438 +msgid "" +"Raises an :ref:`auditing event ` ``cpython." +"PyInterpreterState_Clear`` with no arguments." +msgstr "" +"引發一個不附帶引數的\\ :ref:`稽核事件 ` ``cpython." +"PyInterpreterState_Clear``。" + +#: ../../c-api/init.rst:1443 +msgid "" +"Destroy an interpreter state object. There **should not** be an :term:" +"`attached thread state` for the target interpreter. The interpreter state " +"must have been reset with a previous call to :c:func:" +"`PyInterpreterState_Clear`." +msgstr "" + +#: ../../c-api/init.rst:1450 +msgid "" +"Create a new thread state object belonging to the given interpreter object. " +"An :term:`attached thread state` is not needed." +msgstr "" + +#: ../../c-api/init.rst:1455 +msgid "" +"Reset all information in a :term:`thread state` object. *tstate* must be :" +"term:`attached `" +msgstr "" + +#: ../../c-api/init.rst:1458 +msgid "" +"This function now calls the :c:member:`!PyThreadState.on_delete` callback. " +"Previously, that happened in :c:func:`PyThreadState_Delete`." +msgstr "" + +#: ../../c-api/init.rst:1462 +msgid "The :c:member:`!PyThreadState.on_delete` callback was removed." +msgstr ":c:member:`!PyThreadState.on_delete` 回呼已被移除。" + +#: ../../c-api/init.rst:1468 +msgid "" +"Destroy a :term:`thread state` object. *tstate* should not be :term:" +"`attached ` to any thread. *tstate* must have been " +"reset with a previous call to :c:func:`PyThreadState_Clear`." +msgstr "" + +#: ../../c-api/init.rst:1476 +msgid "" +"Detach the :term:`attached thread state` (which must have been reset with a " +"previous call to :c:func:`PyThreadState_Clear`) and then destroy it." +msgstr "" + +#: ../../c-api/init.rst:1479 +msgid "" +"No :term:`thread state` will be :term:`attached ` " +"upon returning." +msgstr "" + +#: ../../c-api/init.rst:1484 +msgid "Get the current frame of the Python thread state *tstate*." +msgstr "" + +#: ../../c-api/init.rst:1486 +msgid "" +"Return a :term:`strong reference`. Return ``NULL`` if no frame is currently " +"executing." +msgstr "" + +#: ../../c-api/init.rst:1489 +msgid "See also :c:func:`PyEval_GetFrame`." +msgstr "也請見 :c:func:`PyEval_GetFrame`。" + +#: ../../c-api/init.rst:1491 ../../c-api/init.rst:1500 +#: ../../c-api/init.rst:1509 +msgid "" +"*tstate* must not be ``NULL``, and must be :term:`attached `." +msgstr "" + +#: ../../c-api/init.rst:1498 +msgid "" +"Get the unique :term:`thread state` identifier of the Python thread state " +"*tstate*." +msgstr "" + +#: ../../c-api/init.rst:1507 +msgid "Get the interpreter of the Python thread state *tstate*." +msgstr "" + +#: ../../c-api/init.rst:1516 +msgid "Suspend tracing and profiling in the Python thread state *tstate*." +msgstr "" + +#: ../../c-api/init.rst:1518 +msgid "Resume them using the :c:func:`PyThreadState_LeaveTracing` function." +msgstr "" + +#: ../../c-api/init.rst:1525 +msgid "" +"Resume tracing and profiling in the Python thread state *tstate* suspended " +"by the :c:func:`PyThreadState_EnterTracing` function." +msgstr "" + +#: ../../c-api/init.rst:1528 +msgid "" +"See also :c:func:`PyEval_SetTrace` and :c:func:`PyEval_SetProfile` functions." +msgstr "" + +#: ../../c-api/init.rst:1536 +msgid "" +"Set the stack protection start address and stack protection size of a Python " +"thread state." +msgstr "" + +#: ../../c-api/init.rst:1539 +msgid "" +"On success, return ``0``. On failure, set an exception and return ``-1``." +msgstr "" + +#: ../../c-api/init.rst:1542 +msgid "" +"CPython implements :ref:`recursion control ` for C code by " +"raising :py:exc:`RecursionError` when it notices that the machine execution " +"stack is close to overflow. See for example the :c:func:" +"`Py_EnterRecursiveCall` function. For this, it needs to know the location of " +"the current thread's stack, which it normally gets from the operating " +"system. When the stack is changed, for example using context switching " +"techniques like the Boost library's ``boost::context``, you must call :c:" +"func:`~PyUnstable_ThreadState_SetStackProtection` to inform CPython of the " +"change." +msgstr "" + +#: ../../c-api/init.rst:1551 +msgid "" +"Call :c:func:`~PyUnstable_ThreadState_SetStackProtection` either before or " +"after changing the stack. Do not call any other Python C API between the " +"call and the stack change." +msgstr "" + +#: ../../c-api/init.rst:1556 +msgid "" +"See :c:func:`PyUnstable_ThreadState_ResetStackProtection` for undoing this " +"operation." +msgstr "" + +#: ../../c-api/init.rst:1562 ../../c-api/init.rst:1582 +msgid "" +"This function was added in a bugfix release, and extensions that use it will " +"be incompatible with Python 3.14.0. Most packaging tools for Python are not " +"able to handle this incompatibility automatically, and will need explicit " +"configuration. When using PyPA standards (wheels and source distributions), " +"specify ``Requires-Python: != 3.14.0.*`` in `core metadata `_." +msgstr "" + +#: ../../c-api/init.rst:1573 +msgid "" +"Reset the stack protection start address and stack protection size of a " +"Python thread state to the operating system defaults." +msgstr "" + +#: ../../c-api/init.rst:1576 +msgid "" +"See :c:func:`PyUnstable_ThreadState_SetStackProtection` for an explanation." +msgstr "" + +#: ../../c-api/init.rst:1593 +msgid "Get the current interpreter." +msgstr "" + +#: ../../c-api/init.rst:1595 +msgid "" +"Issue a fatal error if there no :term:`attached thread state`. It cannot " +"return NULL." +msgstr "" + +#: ../../c-api/init.rst:1603 +msgid "" +"Return the interpreter's unique ID. If there was any error in doing so then " +"``-1`` is returned and an error is set." +msgstr "" + +#: ../../c-api/init.rst:1606 ../../c-api/init.rst:2221 +#: ../../c-api/init.rst:2228 ../../c-api/init.rst:2247 +#: ../../c-api/init.rst:2254 +msgid "The caller must have an :term:`attached thread state`." +msgstr "呼叫者必須擁有一個 :term:`attached thread state`。" + +#: ../../c-api/init.rst:1613 +msgid "" +"Return a dictionary in which interpreter-specific data may be stored. If " +"this function returns ``NULL`` then no exception has been raised and the " +"caller should assume no interpreter-specific dict is available." +msgstr "" + +#: ../../c-api/init.rst:1617 +msgid "" +"This is not a replacement for :c:func:`PyModule_GetState()`, which " +"extensions should use to store interpreter-specific state information." +msgstr "" + +#: ../../c-api/init.rst:1620 +msgid "" +"The returned dictionary is borrowed from the interpreter and is valid until " +"interpreter shutdown." +msgstr "" + +#: ../../c-api/init.rst:1628 +msgid "Type of a frame evaluation function." +msgstr "" + +#: ../../c-api/init.rst:1630 +msgid "" +"The *throwflag* parameter is used by the ``throw()`` method of generators: " +"if non-zero, handle the current exception." +msgstr "" + +#: ../../c-api/init.rst:1633 +msgid "The function now takes a *tstate* parameter." +msgstr "" + +#: ../../c-api/init.rst:1636 +msgid "" +"The *frame* parameter changed from ``PyFrameObject*`` to " +"``_PyInterpreterFrame*``." +msgstr "" + +#: ../../c-api/init.rst:1641 +msgid "Get the frame evaluation function." +msgstr "" + +#: ../../c-api/init.rst:1643 ../../c-api/init.rst:1651 +msgid "See the :pep:`523` \"Adding a frame evaluation API to CPython\"." +msgstr "" + +#: ../../c-api/init.rst:1649 +msgid "Set the frame evaluation function." +msgstr "" + +#: ../../c-api/init.rst:1658 +msgid "" +"Return a dictionary in which extensions can store thread-specific state " +"information. Each extension should use a unique key to use to store state " +"in the dictionary. It is okay to call this function when no :term:`thread " +"state` is :term:`attached `. If this function returns " +"``NULL``, no exception has been raised and the caller should assume no " +"thread state is attached." +msgstr "" + +#: ../../c-api/init.rst:1668 +msgid "" +"Asynchronously raise an exception in a thread. The *id* argument is the " +"thread id of the target thread; *exc* is the exception object to be raised. " +"This function does not steal any references to *exc*. To prevent naive " +"misuse, you must write your own C extension to call this. Must be called " +"with an :term:`attached thread state`. Returns the number of thread states " +"modified; this is normally one, but will be zero if the thread id isn't " +"found. If *exc* is ``NULL``, the pending exception (if any) for the thread " +"is cleared. This raises no exceptions." +msgstr "" + +#: ../../c-api/init.rst:1676 +msgid "" +"The type of the *id* parameter changed from :c:expr:`long` to :c:expr:" +"`unsigned long`." +msgstr "" + +#: ../../c-api/init.rst:1682 +msgid "" +":term:`Attach ` *tstate* to the current thread, which " +"must not be ``NULL`` or already :term:`attached `." +msgstr "" + +#: ../../c-api/init.rst:1685 +msgid "" +"The calling thread must not already have an :term:`attached thread state`." +msgstr "" + +#: ../../c-api/init.rst:1693 +msgid "" +"Updated to be consistent with :c:func:`PyEval_RestoreThread`, :c:func:" +"`Py_END_ALLOW_THREADS`, and :c:func:`PyGILState_Ensure`, and terminate the " +"current thread if called while the interpreter is finalizing." +msgstr "" + +#: ../../c-api/init.rst:1702 +msgid "" +":c:func:`PyEval_RestoreThread` is a higher-level function which is always " +"available (even when threads have not been initialized)." +msgstr "" + +#: ../../c-api/init.rst:1708 +msgid "" +"Detach the :term:`attached thread state`. The *tstate* argument, which must " +"not be ``NULL``, is only used to check that it represents the :term:" +"`attached thread state` --- if it isn't, a fatal error is reported." +msgstr "" + +#: ../../c-api/init.rst:1713 +msgid "" +":c:func:`PyEval_SaveThread` is a higher-level function which is always " +"available (even when threads have not been initialized)." +msgstr "" + +#: ../../c-api/init.rst:1720 +msgid "Sub-interpreter support" +msgstr "" + +#: ../../c-api/init.rst:1722 +msgid "" +"While in most uses, you will only embed a single Python interpreter, there " +"are cases where you need to create several independent interpreters in the " +"same process and perhaps even in the same thread. Sub-interpreters allow you " +"to do that." +msgstr "" + +#: ../../c-api/init.rst:1727 +msgid "" +"The \"main\" interpreter is the first one created when the runtime " +"initializes. It is usually the only Python interpreter in a process. Unlike " +"sub-interpreters, the main interpreter has unique process-global " +"responsibilities like signal handling. It is also responsible for execution " +"during runtime initialization and is usually the active interpreter during " +"runtime finalization. The :c:func:`PyInterpreterState_Main` function " +"returns a pointer to its state." +msgstr "" + +#: ../../c-api/init.rst:1734 +msgid "" +"You can switch between sub-interpreters using the :c:func:" +"`PyThreadState_Swap` function. You can create and destroy them using the " +"following functions:" +msgstr "" + +#: ../../c-api/init.rst:1740 +msgid "" +"Structure containing most parameters to configure a sub-interpreter. Its " +"values are used only in :c:func:`Py_NewInterpreterFromConfig` and never " +"modified by the runtime." +msgstr "" + +#: ../../c-api/init.rst:1746 +msgid "Structure fields:" +msgstr "" + +#: ../../c-api/init.rst:1750 +msgid "" +"If this is ``0`` then the sub-interpreter will use its own \"object\" " +"allocator state. Otherwise it will use (share) the main interpreter's." +msgstr "" + +#: ../../c-api/init.rst:1754 +msgid "" +"If this is ``0`` then :c:member:`~PyInterpreterConfig." +"check_multi_interp_extensions` must be ``1`` (non-zero). If this is ``1`` " +"then :c:member:`~PyInterpreterConfig.gil` must not be :c:macro:" +"`PyInterpreterConfig_OWN_GIL`." +msgstr "" + +#: ../../c-api/init.rst:1762 +msgid "" +"If this is ``0`` then the runtime will not support forking the process in " +"any thread where the sub-interpreter is currently active. Otherwise fork is " +"unrestricted." +msgstr "" + +#: ../../c-api/init.rst:1766 +msgid "" +"Note that the :mod:`subprocess` module still works when fork is disallowed." +msgstr "" + +#: ../../c-api/init.rst:1771 +msgid "" +"If this is ``0`` then the runtime will not support replacing the current " +"process via exec (e.g. :func:`os.execv`) in any thread where the sub-" +"interpreter is currently active. Otherwise exec is unrestricted." +msgstr "" + +#: ../../c-api/init.rst:1776 +msgid "" +"Note that the :mod:`subprocess` module still works when exec is disallowed." +msgstr "" + +#: ../../c-api/init.rst:1781 +msgid "" +"If this is ``0`` then the sub-interpreter's :mod:`threading` module won't " +"create threads. Otherwise threads are allowed." +msgstr "" + +#: ../../c-api/init.rst:1787 +msgid "" +"If this is ``0`` then the sub-interpreter's :mod:`threading` module won't " +"create daemon threads. Otherwise daemon threads are allowed (as long as :c:" +"member:`~PyInterpreterConfig.allow_threads` is non-zero)." +msgstr "" + +#: ../../c-api/init.rst:1794 +msgid "" +"If this is ``0`` then all extension modules may be imported, including " +"legacy (single-phase init) modules, in any thread where the sub-interpreter " +"is currently active. Otherwise only multi-phase init extension modules (see :" +"pep:`489`) may be imported. (Also see :c:macro:" +"`Py_mod_multiple_interpreters`.)" +msgstr "" + +#: ../../c-api/init.rst:1801 +msgid "" +"This must be ``1`` (non-zero) if :c:member:`~PyInterpreterConfig." +"use_main_obmalloc` is ``0``." +msgstr "" + +#: ../../c-api/init.rst:1806 +msgid "" +"This determines the operation of the GIL for the sub-interpreter. It may be " +"one of the following:" +msgstr "" + +#: ../../c-api/init.rst:1813 +msgid "Use the default selection (:c:macro:`PyInterpreterConfig_SHARED_GIL`)." +msgstr "" + +#: ../../c-api/init.rst:1817 +msgid "Use (share) the main interpreter's GIL." +msgstr "" + +#: ../../c-api/init.rst:1821 +msgid "Use the sub-interpreter's own GIL." +msgstr "" + +#: ../../c-api/init.rst:1823 +msgid "" +"If this is :c:macro:`PyInterpreterConfig_OWN_GIL` then :c:member:" +"`PyInterpreterConfig.use_main_obmalloc` must be ``0``." +msgstr "" + +#: ../../c-api/init.rst:1837 +msgid "" +"Create a new sub-interpreter. This is an (almost) totally separate " +"environment for the execution of Python code. In particular, the new " +"interpreter has separate, independent versions of all imported modules, " +"including the fundamental modules :mod:`builtins`, :mod:`__main__` and :mod:" +"`sys`. The table of loaded modules (``sys.modules``) and the module search " +"path (``sys.path``) are also separate. The new environment has no ``sys." +"argv`` variable. It has new standard I/O stream file objects ``sys.stdin``, " +"``sys.stdout`` and ``sys.stderr`` (however these refer to the same " +"underlying file descriptors)." +msgstr "" + +#: ../../c-api/init.rst:1847 +msgid "" +"The given *config* controls the options with which the interpreter is " +"initialized." +msgstr "" + +#: ../../c-api/init.rst:1850 +msgid "" +"Upon success, *tstate_p* will be set to the first :term:`thread state` " +"created in the new sub-interpreter. This thread state is :term:`attached " +"`. Note that no actual thread is created; see the " +"discussion of thread states below. If creation of the new interpreter is " +"unsuccessful, *tstate_p* is set to ``NULL``; no exception is set since the " +"exception state is stored in the :term:`attached thread state`, which might " +"not exist." +msgstr "" + +#: ../../c-api/init.rst:1859 +msgid "" +"Like all other Python/C API functions, an :term:`attached thread state` must " +"be present before calling this function, but it might be detached upon " +"returning. On success, the returned thread state will be :term:`attached " +"`. If the sub-interpreter is created with its own :" +"term:`GIL` then the :term:`attached thread state` of the calling interpreter " +"will be detached. When the function returns, the new interpreter's :term:" +"`thread state` will be :term:`attached ` to the " +"current thread and the previous interpreter's :term:`attached thread state` " +"will remain detached." +msgstr "" + +#: ../../c-api/init.rst:1870 +msgid "" +"Sub-interpreters are most effective when isolated from each other, with " +"certain functionality restricted::" +msgstr "" + +#: ../../c-api/init.rst:1873 +msgid "" +"PyInterpreterConfig config = {\n" +" .use_main_obmalloc = 0,\n" +" .allow_fork = 0,\n" +" .allow_exec = 0,\n" +" .allow_threads = 1,\n" +" .allow_daemon_threads = 0,\n" +" .check_multi_interp_extensions = 1,\n" +" .gil = PyInterpreterConfig_OWN_GIL,\n" +"};\n" +"PyThreadState *tstate = NULL;\n" +"PyStatus status = Py_NewInterpreterFromConfig(&tstate, &config);\n" +"if (PyStatus_Exception(status)) {\n" +" Py_ExitStatusException(status);\n" +"}" +msgstr "" +"PyInterpreterConfig config = {\n" +" .use_main_obmalloc = 0,\n" +" .allow_fork = 0,\n" +" .allow_exec = 0,\n" +" .allow_threads = 1,\n" +" .allow_daemon_threads = 0,\n" +" .check_multi_interp_extensions = 1,\n" +" .gil = PyInterpreterConfig_OWN_GIL,\n" +"};\n" +"PyThreadState *tstate = NULL;\n" +"PyStatus status = Py_NewInterpreterFromConfig(&tstate, &config);\n" +"if (PyStatus_Exception(status)) {\n" +" Py_ExitStatusException(status);\n" +"}" + +#: ../../c-api/init.rst:1888 +msgid "" +"Note that the config is used only briefly and does not get modified. During " +"initialization the config's values are converted into various :c:type:" +"`PyInterpreterState` values. A read-only copy of the config may be stored " +"internally on the :c:type:`PyInterpreterState`." +msgstr "" + +#: ../../c-api/init.rst:1897 +msgid "Extension modules are shared between (sub-)interpreters as follows:" +msgstr "" + +#: ../../c-api/init.rst:1899 +msgid "" +"For modules using multi-phase initialization, e.g. :c:func:" +"`PyModule_FromDefAndSpec`, a separate module object is created and " +"initialized for each interpreter. Only C-level static and global variables " +"are shared between these module objects." +msgstr "" + +#: ../../c-api/init.rst:1905 +msgid "" +"For modules using single-phase initialization, e.g. :c:func:" +"`PyModule_Create`, the first time a particular extension is imported, it is " +"initialized normally, and a (shallow) copy of its module's dictionary is " +"squirreled away. When the same extension is imported by another " +"(sub-)interpreter, a new module is initialized and filled with the contents " +"of this copy; the extension's ``init`` function is not called. Objects in " +"the module's dictionary thus end up shared across (sub-)interpreters, which " +"might cause unwanted behavior (see `Bugs and caveats`_ below)." +msgstr "" + +#: ../../c-api/init.rst:1916 +msgid "" +"Note that this is different from what happens when an extension is imported " +"after the interpreter has been completely re-initialized by calling :c:func:" +"`Py_FinalizeEx` and :c:func:`Py_Initialize`; in that case, the extension's " +"``initmodule`` function *is* called again. As with multi-phase " +"initialization, this means that only C-level static and global variables are " +"shared between these modules." +msgstr "" + +#: ../../c-api/init.rst:1936 +msgid "" +"Create a new sub-interpreter. This is essentially just a wrapper around :c:" +"func:`Py_NewInterpreterFromConfig` with a config that preserves the existing " +"behavior. The result is an unisolated sub-interpreter that shares the main " +"interpreter's GIL, allows fork/exec, allows daemon threads, and allows " +"single-phase init modules." +msgstr "" + +#: ../../c-api/init.rst:1948 +msgid "" +"Destroy the (sub-)interpreter represented by the given :term:`thread state`. " +"The given thread state must be :term:`attached `. " +"When the call returns, there will be no :term:`attached thread state`. All " +"thread states associated with this interpreter are destroyed." +msgstr "" + +#: ../../c-api/init.rst:1953 +msgid "" +":c:func:`Py_FinalizeEx` will destroy all sub-interpreters that haven't been " +"explicitly destroyed at that point." +msgstr "" + +#: ../../c-api/init.rst:1960 +msgid "A Per-Interpreter GIL" +msgstr "直譯器各別持有的 GIL" + +#: ../../c-api/init.rst:1962 +msgid "" +"Using :c:func:`Py_NewInterpreterFromConfig` you can create a sub-interpreter " +"that is completely isolated from other interpreters, including having its " +"own GIL. The most important benefit of this isolation is that such an " +"interpreter can execute Python code without being blocked by other " +"interpreters or blocking any others. Thus a single Python process can truly " +"take advantage of multiple CPU cores when running Python code. The " +"isolation also encourages a different approach to concurrency than that of " +"just using threads. (See :pep:`554` and :pep:`684`.)" +msgstr "" + +#: ../../c-api/init.rst:1972 +msgid "" +"Using an isolated interpreter requires vigilance in preserving that " +"isolation. That especially means not sharing any objects or mutable state " +"without guarantees about thread-safety. Even objects that are otherwise " +"immutable (e.g. ``None``, ``(1, 5)``) can't normally be shared because of " +"the refcount. One simple but less-efficient approach around this is to use " +"a global lock around all use of some state (or object). Alternately, " +"effectively immutable objects (like integers or strings) can be made safe in " +"spite of their refcounts by making them :term:`immortal`. In fact, this has " +"been done for the builtin singletons, small integers, and a number of other " +"builtin objects." +msgstr "" + +#: ../../c-api/init.rst:1983 +msgid "" +"If you preserve isolation then you will have access to proper multi-core " +"computing without the complications that come with free-threading. Failure " +"to preserve isolation will expose you to the full consequences of free-" +"threading, including races and hard-to-debug crashes." +msgstr "" + +#: ../../c-api/init.rst:1988 +msgid "" +"Aside from that, one of the main challenges of using multiple isolated " +"interpreters is how to communicate between them safely (not break isolation) " +"and efficiently. The runtime and stdlib do not provide any standard " +"approach to this yet. A future stdlib module would help mitigate the effort " +"of preserving isolation and expose effective tools for communicating (and " +"sharing) data between interpreters." +msgstr "" + +#: ../../c-api/init.rst:1999 +msgid "Bugs and caveats" +msgstr "" + +#: ../../c-api/init.rst:2001 +msgid "" +"Because sub-interpreters (and the main interpreter) are part of the same " +"process, the insulation between them isn't perfect --- for example, using " +"low-level file operations like :func:`os.close` they can (accidentally or " +"maliciously) affect each other's open files. Because of the way extensions " +"are shared between (sub-)interpreters, some extensions may not work " +"properly; this is especially likely when using single-phase initialization " +"or (static) global variables. It is possible to insert objects created in " +"one sub-interpreter into a namespace of another (sub-)interpreter; this " +"should be avoided if possible." +msgstr "" + +#: ../../c-api/init.rst:2011 +msgid "" +"Special care should be taken to avoid sharing user-defined functions, " +"methods, instances or classes between sub-interpreters, since import " +"operations executed by such objects may affect the wrong (sub-)interpreter's " +"dictionary of loaded modules. It is equally important to avoid sharing " +"objects from which the above are reachable." +msgstr "" + +#: ../../c-api/init.rst:2017 +msgid "" +"Also note that combining this functionality with ``PyGILState_*`` APIs is " +"delicate, because these APIs assume a bijection between Python thread states " +"and OS-level threads, an assumption broken by the presence of sub-" +"interpreters. It is highly recommended that you don't switch sub-" +"interpreters between a pair of matching :c:func:`PyGILState_Ensure` and :c:" +"func:`PyGILState_Release` calls. Furthermore, extensions (such as :mod:" +"`ctypes`) using these APIs to allow calling of Python code from non-Python " +"created threads will probably be broken when using sub-interpreters." +msgstr "" + +#: ../../c-api/init.rst:2028 +msgid "Asynchronous Notifications" +msgstr "" + +#: ../../c-api/init.rst:2030 +msgid "" +"A mechanism is provided to make asynchronous notifications to the main " +"interpreter thread. These notifications take the form of a function pointer " +"and a void pointer argument." +msgstr "" + +#: ../../c-api/init.rst:2037 +msgid "" +"Schedule a function to be called from the main interpreter thread. On " +"success, ``0`` is returned and *func* is queued for being called in the main " +"thread. On failure, ``-1`` is returned without setting any exception." +msgstr "" + +#: ../../c-api/init.rst:2041 +msgid "" +"When successfully queued, *func* will be *eventually* called from the main " +"interpreter thread with the argument *arg*. It will be called " +"asynchronously with respect to normally running Python code, but with both " +"these conditions met:" +msgstr "" + +#: ../../c-api/init.rst:2046 +msgid "on a :term:`bytecode` boundary;" +msgstr "" + +#: ../../c-api/init.rst:2047 +msgid "" +"with the main thread holding an :term:`attached thread state` (*func* can " +"therefore use the full C API)." +msgstr "" + +#: ../../c-api/init.rst:2050 +msgid "" +"*func* must return ``0`` on success, or ``-1`` on failure with an exception " +"set. *func* won't be interrupted to perform another asynchronous " +"notification recursively, but it can still be interrupted to switch threads " +"if the :term:`thread state ` is detached." +msgstr "" + +#: ../../c-api/init.rst:2055 +msgid "" +"This function doesn't need an :term:`attached thread state`. However, to " +"call this function in a subinterpreter, the caller must have an :term:" +"`attached thread state`. Otherwise, the function *func* can be scheduled to " +"be called from the wrong interpreter." +msgstr "" + +#: ../../c-api/init.rst:2060 +msgid "" +"This is a low-level function, only useful for very special cases. There is " +"no guarantee that *func* will be called as quick as possible. If the main " +"thread is busy executing a system call, *func* won't be called before the " +"system call returns. This function is generally **not** suitable for " +"calling Python code from arbitrary C threads. Instead, use the :ref:" +"`PyGILState API`." +msgstr "" + +#: ../../c-api/init.rst:2069 +msgid "" +"If this function is called in a subinterpreter, the function *func* is now " +"scheduled to be called from the subinterpreter, rather than being called " +"from the main interpreter. Each subinterpreter now has its own list of " +"scheduled calls." +msgstr "" + +#: ../../c-api/init.rst:2075 +msgid "" +"This function now always schedules *func* to be run in the main interpreter." +msgstr "" + +#: ../../c-api/init.rst:2082 +msgid "" +"Execute all pending calls. This is usually executed automatically by the " +"interpreter." +msgstr "" + +#: ../../c-api/init.rst:2085 +msgid "" +"This function returns ``0`` on success, and returns ``-1`` with an exception " +"set on failure." +msgstr "" + +#: ../../c-api/init.rst:2088 +msgid "" +"If this is not called in the main thread of the main interpreter, this " +"function does nothing and returns ``0``. The caller must hold an :term:" +"`attached thread state`." +msgstr "" + +#: ../../c-api/init.rst:2094 +msgid "This function only runs pending calls in the main interpreter." +msgstr "" + +#: ../../c-api/init.rst:2101 +msgid "Profiling and Tracing" +msgstr "" + +#: ../../c-api/init.rst:2106 +msgid "" +"The Python interpreter provides some low-level support for attaching " +"profiling and execution tracing facilities. These are used for profiling, " +"debugging, and coverage analysis tools." +msgstr "" + +#: ../../c-api/init.rst:2110 +msgid "" +"This C interface allows the profiling or tracing code to avoid the overhead " +"of calling through Python-level callable objects, making a direct C function " +"call instead. The essential attributes of the facility have not changed; " +"the interface allows trace functions to be installed per-thread, and the " +"basic events reported to the trace function are the same as had been " +"reported to the Python-level trace functions in previous versions." +msgstr "" + +#: ../../c-api/init.rst:2120 +msgid "" +"The type of the trace function registered using :c:func:`PyEval_SetProfile` " +"and :c:func:`PyEval_SetTrace`. The first parameter is the object passed to " +"the registration function as *obj*, *frame* is the frame object to which the " +"event pertains, *what* is one of the constants :c:data:`PyTrace_CALL`, :c:" +"data:`PyTrace_EXCEPTION`, :c:data:`PyTrace_LINE`, :c:data:`PyTrace_RETURN`, :" +"c:data:`PyTrace_C_CALL`, :c:data:`PyTrace_C_EXCEPTION`, :c:data:" +"`PyTrace_C_RETURN`, or :c:data:`PyTrace_OPCODE`, and *arg* depends on the " +"value of *what*:" +msgstr "" + +#: ../../c-api/init.rst:2129 +msgid "Value of *what*" +msgstr "*what* 的值" + +#: ../../c-api/init.rst:2129 +msgid "Meaning of *arg*" +msgstr "*arg* 的含義" + +#: ../../c-api/init.rst:2131 +msgid ":c:data:`PyTrace_CALL`" +msgstr ":c:data:`PyTrace_CALL`" + +#: ../../c-api/init.rst:2131 ../../c-api/init.rst:2136 +#: ../../c-api/init.rst:2147 +msgid "Always :c:data:`Py_None`." +msgstr "" + +#: ../../c-api/init.rst:2133 +msgid ":c:data:`PyTrace_EXCEPTION`" +msgstr ":c:data:`PyTrace_EXCEPTION`" + +#: ../../c-api/init.rst:2133 +msgid "Exception information as returned by :func:`sys.exc_info`." +msgstr "" + +#: ../../c-api/init.rst:2136 +msgid ":c:data:`PyTrace_LINE`" +msgstr ":c:data:`PyTrace_LINE`" + +#: ../../c-api/init.rst:2138 +msgid ":c:data:`PyTrace_RETURN`" +msgstr ":c:data:`PyTrace_RETURN`" + +#: ../../c-api/init.rst:2138 +msgid "" +"Value being returned to the caller, or ``NULL`` if caused by an exception." +msgstr "" + +#: ../../c-api/init.rst:2141 +msgid ":c:data:`PyTrace_C_CALL`" +msgstr ":c:data:`PyTrace_C_CALL`" + +#: ../../c-api/init.rst:2141 ../../c-api/init.rst:2143 +#: ../../c-api/init.rst:2145 +msgid "Function object being called." +msgstr "被呼叫的函式物件。" + +#: ../../c-api/init.rst:2143 +msgid ":c:data:`PyTrace_C_EXCEPTION`" +msgstr ":c:data:`PyTrace_C_EXCEPTION`" + +#: ../../c-api/init.rst:2145 +msgid ":c:data:`PyTrace_C_RETURN`" +msgstr ":c:data:`PyTrace_C_RETURN`" + +#: ../../c-api/init.rst:2147 +msgid ":c:data:`PyTrace_OPCODE`" +msgstr ":c:data:`PyTrace_OPCODE`" + +#: ../../c-api/init.rst:2152 +msgid "" +"The value of the *what* parameter to a :c:type:`Py_tracefunc` function when " +"a new call to a function or method is being reported, or a new entry into a " +"generator. Note that the creation of the iterator for a generator function " +"is not reported as there is no control transfer to the Python bytecode in " +"the corresponding frame." +msgstr "" + +#: ../../c-api/init.rst:2161 +msgid "" +"The value of the *what* parameter to a :c:type:`Py_tracefunc` function when " +"an exception has been raised. The callback function is called with this " +"value for *what* when after any bytecode is processed after which the " +"exception becomes set within the frame being executed. The effect of this " +"is that as exception propagation causes the Python stack to unwind, the " +"callback is called upon return to each frame as the exception propagates. " +"Only trace functions receives these events; they are not needed by the " +"profiler." +msgstr "" + +#: ../../c-api/init.rst:2172 +msgid "" +"The value passed as the *what* parameter to a :c:type:`Py_tracefunc` " +"function (but not a profiling function) when a line-number event is being " +"reported. It may be disabled for a frame by setting :attr:`~frame." +"f_trace_lines` to *0* on that frame." +msgstr "" + +#: ../../c-api/init.rst:2180 +msgid "" +"The value for the *what* parameter to :c:type:`Py_tracefunc` functions when " +"a call is about to return." +msgstr "" + +#: ../../c-api/init.rst:2186 +msgid "" +"The value for the *what* parameter to :c:type:`Py_tracefunc` functions when " +"a C function is about to be called." +msgstr "" + +#: ../../c-api/init.rst:2192 +msgid "" +"The value for the *what* parameter to :c:type:`Py_tracefunc` functions when " +"a C function has raised an exception." +msgstr "" + +#: ../../c-api/init.rst:2198 +msgid "" +"The value for the *what* parameter to :c:type:`Py_tracefunc` functions when " +"a C function has returned." +msgstr "" + +#: ../../c-api/init.rst:2204 +msgid "" +"The value for the *what* parameter to :c:type:`Py_tracefunc` functions (but " +"not profiling functions) when a new opcode is about to be executed. This " +"event is not emitted by default: it must be explicitly requested by setting :" +"attr:`~frame.f_trace_opcodes` to *1* on the frame." +msgstr "" + +#: ../../c-api/init.rst:2212 +msgid "" +"Set the profiler function to *func*. The *obj* parameter is passed to the " +"function as its first parameter, and may be any Python object, or ``NULL``. " +"If the profile function needs to maintain state, using a different value for " +"*obj* for each thread provides a convenient and thread-safe place to store " +"it. The profile function is called for all monitored events except :c:data:" +"`PyTrace_LINE` :c:data:`PyTrace_OPCODE` and :c:data:`PyTrace_EXCEPTION`." +msgstr "" + +#: ../../c-api/init.rst:2219 +msgid "See also the :func:`sys.setprofile` function." +msgstr "另請參閱 :func:`sys.setprofile` 函式。" + +#: ../../c-api/init.rst:2225 +msgid "" +"Like :c:func:`PyEval_SetProfile` but sets the profile function in all " +"running threads belonging to the current interpreter instead of the setting " +"it only on the current thread." +msgstr "" + +#: ../../c-api/init.rst:2230 +msgid "" +"As :c:func:`PyEval_SetProfile`, this function ignores any exceptions raised " +"while setting the profile functions in all threads." +msgstr "" + +#: ../../c-api/init.rst:2238 +msgid "" +"Set the tracing function to *func*. This is similar to :c:func:" +"`PyEval_SetProfile`, except the tracing function does receive line-number " +"events and per-opcode events, but does not receive any event related to C " +"function objects being called. Any trace function registered using :c:func:" +"`PyEval_SetTrace` will not receive :c:data:`PyTrace_C_CALL`, :c:data:" +"`PyTrace_C_EXCEPTION` or :c:data:`PyTrace_C_RETURN` as a value for the " +"*what* parameter." +msgstr "" + +#: ../../c-api/init.rst:2245 +msgid "See also the :func:`sys.settrace` function." +msgstr "也請見 :func:`sys.settrace` 函式。" + +#: ../../c-api/init.rst:2251 +msgid "" +"Like :c:func:`PyEval_SetTrace` but sets the tracing function in all running " +"threads belonging to the current interpreter instead of the setting it only " +"on the current thread." +msgstr "" + +#: ../../c-api/init.rst:2256 +msgid "" +"As :c:func:`PyEval_SetTrace`, this function ignores any exceptions raised " +"while setting the trace functions in all threads." +msgstr "" + +#: ../../c-api/init.rst:2262 +msgid "Reference tracing" +msgstr "" + +#: ../../c-api/init.rst:2268 +msgid "" +"The type of the trace function registered using :c:func:" +"`PyRefTracer_SetTracer`. The first parameter is a Python object that has " +"been just created (when **event** is set to :c:data:`PyRefTracer_CREATE`) or " +"about to be destroyed (when **event** is set to :c:data:" +"`PyRefTracer_DESTROY`). The **data** argument is the opaque pointer that was " +"provided when :c:func:`PyRefTracer_SetTracer` was called." +msgstr "" + +#: ../../c-api/init.rst:2278 +msgid "" +"The value for the *event* parameter to :c:type:`PyRefTracer` functions when " +"a Python object has been created." +msgstr "" + +#: ../../c-api/init.rst:2283 +msgid "" +"The value for the *event* parameter to :c:type:`PyRefTracer` functions when " +"a Python object has been destroyed." +msgstr "" + +#: ../../c-api/init.rst:2288 +msgid "" +"Register a reference tracer function. The function will be called when a new " +"Python has been created or when an object is going to be destroyed. If " +"**data** is provided it must be an opaque pointer that will be provided when " +"the tracer function is called. Return ``0`` on success. Set an exception and " +"return ``-1`` on error." +msgstr "" + +#: ../../c-api/init.rst:2294 +msgid "" +"Not that tracer functions **must not** create Python objects inside or " +"otherwise the call will be re-entrant. The tracer also **must not** clear " +"any existing exception or set an exception. A :term:`thread state` will be " +"active every time the tracer function is called." +msgstr "" + +#: ../../c-api/init.rst:2299 ../../c-api/init.rst:2310 +msgid "" +"There must be an :term:`attached thread state` when calling this function." +msgstr "" + +#: ../../c-api/init.rst:2305 +msgid "" +"Get the registered reference tracer function and the value of the opaque " +"data pointer that was registered when :c:func:`PyRefTracer_SetTracer` was " +"called. If no tracer was registered this function will return NULL and will " +"set the **data** pointer to NULL." +msgstr "" + +#: ../../c-api/init.rst:2317 +msgid "Advanced Debugger Support" +msgstr "" + +#: ../../c-api/init.rst:2322 +msgid "" +"These functions are only intended to be used by advanced debugging tools." +msgstr "" + +#: ../../c-api/init.rst:2327 +msgid "" +"Return the interpreter state object at the head of the list of all such " +"objects." +msgstr "" + +#: ../../c-api/init.rst:2332 +msgid "Return the main interpreter state object." +msgstr "" + +#: ../../c-api/init.rst:2337 +msgid "" +"Return the next interpreter state object after *interp* from the list of all " +"such objects." +msgstr "" + +#: ../../c-api/init.rst:2343 +msgid "" +"Return the pointer to the first :c:type:`PyThreadState` object in the list " +"of threads associated with the interpreter *interp*." +msgstr "" + +#: ../../c-api/init.rst:2349 +msgid "" +"Return the next thread state object after *tstate* from the list of all such " +"objects belonging to the same :c:type:`PyInterpreterState` object." +msgstr "" + +#: ../../c-api/init.rst:2356 +msgid "Thread Local Storage Support" +msgstr "" + +#: ../../c-api/init.rst:2360 +msgid "" +"The Python interpreter provides low-level support for thread-local storage " +"(TLS) which wraps the underlying native TLS implementation to support the " +"Python-level thread local storage API (:class:`threading.local`). The " +"CPython C level APIs are similar to those offered by pthreads and Windows: " +"use a thread key and functions to associate a :c:expr:`void*` value per " +"thread." +msgstr "" + +#: ../../c-api/init.rst:2367 +msgid "" +"A :term:`thread state` does *not* need to be :term:`attached ` when calling these functions; they suppl their own locking." +msgstr "" + +#: ../../c-api/init.rst:2370 +msgid "" +"Note that :file:`Python.h` does not include the declaration of the TLS APIs, " +"you need to include :file:`pythread.h` to use thread-local storage." +msgstr "" + +#: ../../c-api/init.rst:2374 +msgid "" +"None of these API functions handle memory management on behalf of the :c:" +"expr:`void*` values. You need to allocate and deallocate them yourself. If " +"the :c:expr:`void*` values happen to be :c:expr:`PyObject*`, these functions " +"don't do refcount operations on them either." +msgstr "" + +#: ../../c-api/init.rst:2382 +msgid "Thread Specific Storage (TSS) API" +msgstr "" + +#: ../../c-api/init.rst:2384 +msgid "" +"TSS API is introduced to supersede the use of the existing TLS API within " +"the CPython interpreter. This API uses a new type :c:type:`Py_tss_t` " +"instead of :c:expr:`int` to represent thread keys." +msgstr "" + +#: ../../c-api/init.rst:2390 +msgid "\"A New C-API for Thread-Local Storage in CPython\" (:pep:`539`)" +msgstr "" + +#: ../../c-api/init.rst:2395 +msgid "" +"This data structure represents the state of a thread key, the definition of " +"which may depend on the underlying TLS implementation, and it has an " +"internal field representing the key's initialization state. There are no " +"public members in this structure." +msgstr "" + +#: ../../c-api/init.rst:2400 +msgid "" +"When :ref:`Py_LIMITED_API ` is not defined, static allocation of " +"this type by :c:macro:`Py_tss_NEEDS_INIT` is allowed." +msgstr "" + +#: ../../c-api/init.rst:2406 +msgid "" +"This macro expands to the initializer for :c:type:`Py_tss_t` variables. Note " +"that this macro won't be defined with :ref:`Py_LIMITED_API `." +msgstr "" + +#: ../../c-api/init.rst:2411 +msgid "Dynamic Allocation" +msgstr "" + +#: ../../c-api/init.rst:2413 +msgid "" +"Dynamic allocation of the :c:type:`Py_tss_t`, required in extension modules " +"built with :ref:`Py_LIMITED_API `, where static allocation of this " +"type is not possible due to its implementation being opaque at build time." +msgstr "" + +#: ../../c-api/init.rst:2420 +msgid "" +"Return a value which is the same state as a value initialized with :c:macro:" +"`Py_tss_NEEDS_INIT`, or ``NULL`` in the case of dynamic allocation failure." +msgstr "" + +#: ../../c-api/init.rst:2427 +msgid "" +"Free the given *key* allocated by :c:func:`PyThread_tss_alloc`, after first " +"calling :c:func:`PyThread_tss_delete` to ensure any associated thread locals " +"have been unassigned. This is a no-op if the *key* argument is ``NULL``." +msgstr "" + +#: ../../c-api/init.rst:2433 +msgid "" +"A freed key becomes a dangling pointer. You should reset the key to ``NULL``." +msgstr "" + +#: ../../c-api/init.rst:2438 +msgid "Methods" +msgstr "方法" + +#: ../../c-api/init.rst:2440 +msgid "" +"The parameter *key* of these functions must not be ``NULL``. Moreover, the " +"behaviors of :c:func:`PyThread_tss_set` and :c:func:`PyThread_tss_get` are " +"undefined if the given :c:type:`Py_tss_t` has not been initialized by :c:" +"func:`PyThread_tss_create`." +msgstr "" + +#: ../../c-api/init.rst:2448 +msgid "" +"Return a non-zero value if the given :c:type:`Py_tss_t` has been initialized " +"by :c:func:`PyThread_tss_create`." +msgstr "" + +#: ../../c-api/init.rst:2454 +msgid "" +"Return a zero value on successful initialization of a TSS key. The behavior " +"is undefined if the value pointed to by the *key* argument is not " +"initialized by :c:macro:`Py_tss_NEEDS_INIT`. This function can be called " +"repeatedly on the same key -- calling it on an already initialized key is a " +"no-op and immediately returns success." +msgstr "" + +#: ../../c-api/init.rst:2463 +msgid "" +"Destroy a TSS key to forget the values associated with the key across all " +"threads, and change the key's initialization state to uninitialized. A " +"destroyed key is able to be initialized again by :c:func:" +"`PyThread_tss_create`. This function can be called repeatedly on the same " +"key -- calling it on an already destroyed key is a no-op." +msgstr "" + +#: ../../c-api/init.rst:2472 +msgid "" +"Return a zero value to indicate successfully associating a :c:expr:`void*` " +"value with a TSS key in the current thread. Each thread has a distinct " +"mapping of the key to a :c:expr:`void*` value." +msgstr "" + +#: ../../c-api/init.rst:2479 +msgid "" +"Return the :c:expr:`void*` value associated with a TSS key in the current " +"thread. This returns ``NULL`` if no value is associated with the key in the " +"current thread." +msgstr "" + +#: ../../c-api/init.rst:2487 +msgid "Thread Local Storage (TLS) API" +msgstr "執行緒局部儲存 (Thread Local Storage, TLS) API：" + +#: ../../c-api/init.rst:2489 +msgid "" +"This API is superseded by :ref:`Thread Specific Storage (TSS) API `." +msgstr "" + +#: ../../c-api/init.rst:2494 +msgid "" +"This version of the API does not support platforms where the native TLS key " +"is defined in a way that cannot be safely cast to ``int``. On such " +"platforms, :c:func:`PyThread_create_key` will return immediately with a " +"failure status, and the other TLS functions will all be no-ops on such " +"platforms." +msgstr "" + +#: ../../c-api/init.rst:2499 +msgid "" +"Due to the compatibility problem noted above, this version of the API should " +"not be used in new code." +msgstr "" + +#: ../../c-api/init.rst:2510 +msgid "Synchronization Primitives" +msgstr "" + +#: ../../c-api/init.rst:2512 +msgid "The C-API provides a basic mutual exclusion lock." +msgstr "" + +#: ../../c-api/init.rst:2516 +msgid "" +"A mutual exclusion lock. The :c:type:`!PyMutex` should be initialized to " +"zero to represent the unlocked state. For example::" +msgstr "" + +#: ../../c-api/init.rst:2519 +msgid "PyMutex mutex = {0};" +msgstr "PyMutex mutex = {0};" + +#: ../../c-api/init.rst:2521 +msgid "" +"Instances of :c:type:`!PyMutex` should not be copied or moved. Both the " +"contents and address of a :c:type:`!PyMutex` are meaningful, and it must " +"remain at a fixed, writable location in memory." +msgstr "" + +#: ../../c-api/init.rst:2527 +msgid "" +"A :c:type:`!PyMutex` currently occupies one byte, but the size should be " +"considered unstable. The size may change in future Python releases without " +"a deprecation period." +msgstr "" + +#: ../../c-api/init.rst:2535 +msgid "" +"Lock mutex *m*. If another thread has already locked it, the calling thread " +"will block until the mutex is unlocked. While blocked, the thread will " +"temporarily detach the :term:`thread state ` if one " +"exists." +msgstr "" + +#: ../../c-api/init.rst:2543 +msgid "" +"Unlock mutex *m*. The mutex must be locked --- otherwise, the function will " +"issue a fatal error." +msgstr "" + +#: ../../c-api/init.rst:2550 +msgid "Returns non-zero if the mutex *m* is currently locked, zero otherwise." +msgstr "" + +#: ../../c-api/init.rst:2554 +msgid "" +"This function is intended for use in assertions and debugging only and " +"should not be used to make concurrency control decisions, as the lock state " +"may change immediately after the check." +msgstr "" + +#: ../../c-api/init.rst:2563 +msgid "Python Critical Section API" +msgstr "" + +#: ../../c-api/init.rst:2565 +msgid "" +"The critical section API provides a deadlock avoidance layer on top of per-" +"object locks for :term:`free-threaded ` CPython. They are " +"intended to replace reliance on the :term:`global interpreter lock`, and are " +"no-ops in versions of Python with the global interpreter lock." +msgstr "" + +#: ../../c-api/init.rst:2570 +msgid "" +"Critical sections are intended to be used for custom types implemented in C-" +"API extensions. They should generally not be used with built-in types like :" +"class:`list` and :class:`dict` because their public C-APIs already use " +"critical sections internally, with the notable exception of :c:func:" +"`PyDict_Next`, which requires critical section to be acquired externally." +msgstr "" + +#: ../../c-api/init.rst:2577 +msgid "" +"Critical sections avoid deadlocks by implicitly suspending active critical " +"sections, hence, they do not provide exclusive access such as provided by " +"traditional locks like :c:type:`PyMutex`. When a critical section is " +"started, the per-object lock for the object is acquired. If the code " +"executed inside the critical section calls C-API functions then it can " +"suspend the critical section thereby releasing the per-object lock, so other " +"threads can acquire the per-object lock for the same object." +msgstr "" + +#: ../../c-api/init.rst:2585 +msgid "" +"Variants that accept :c:type:`PyMutex` pointers rather than Python objects " +"are also available. Use these variants to start a critical section in a " +"situation where there is no :c:type:`PyObject` -- for example, when working " +"with a C type that does not extend or wrap :c:type:`PyObject` but still " +"needs to call into the C API in a manner that might lead to deadlocks." +msgstr "" + +#: ../../c-api/init.rst:2591 +msgid "" +"The functions and structs used by the macros are exposed for cases where C " +"macros are not available. They should only be used as in the given macro " +"expansions. Note that the sizes and contents of the structures may change in " +"future Python versions." +msgstr "" + +#: ../../c-api/init.rst:2598 +msgid "" +"Operations that need to lock two objects at once must use :c:macro:" +"`Py_BEGIN_CRITICAL_SECTION2`. You *cannot* use nested critical sections to " +"lock more than one object at once, because the inner critical section may " +"suspend the outer critical sections. This API does not provide a way to " +"lock more than two objects at once." +msgstr "" + +#: ../../c-api/init.rst:2604 +msgid "Example usage::" +msgstr "範例用法： ::" + +#: ../../c-api/init.rst:2606 +msgid "" +"static PyObject *\n" +"set_field(MyObject *self, PyObject *value)\n" +"{\n" +" Py_BEGIN_CRITICAL_SECTION(self);\n" +" Py_SETREF(self->field, Py_XNewRef(value));\n" +" Py_END_CRITICAL_SECTION();\n" +" Py_RETURN_NONE;\n" +"}" +msgstr "" +"static PyObject *\n" +"set_field(MyObject *self, PyObject *value)\n" +"{\n" +" Py_BEGIN_CRITICAL_SECTION(self);\n" +" Py_SETREF(self->field, Py_XNewRef(value));\n" +" Py_END_CRITICAL_SECTION();\n" +" Py_RETURN_NONE;\n" +"}" + +#: ../../c-api/init.rst:2615 +msgid "" +"In the above example, :c:macro:`Py_SETREF` calls :c:macro:`Py_DECREF`, which " +"can call arbitrary code through an object's deallocation function. The " +"critical section API avoids potential deadlocks due to reentrancy and lock " +"ordering by allowing the runtime to temporarily suspend the critical section " +"if the code triggered by the finalizer blocks and calls :c:func:" +"`PyEval_SaveThread`." +msgstr "" + +#: ../../c-api/init.rst:2623 +msgid "" +"Acquires the per-object lock for the object *op* and begins a critical " +"section." +msgstr "" + +#: ../../c-api/init.rst:2626 ../../c-api/init.rst:2640 +#: ../../c-api/init.rst:2657 ../../c-api/init.rst:2672 +#: ../../c-api/init.rst:2686 ../../c-api/init.rst:2703 +msgid "In the free-threaded build, this macro expands to::" +msgstr "" + +#: ../../c-api/init.rst:2628 +msgid "" +"{\n" +" PyCriticalSection _py_cs;\n" +" PyCriticalSection_Begin(&_py_cs, (PyObject*)(op))" +msgstr "" +"{\n" +" PyCriticalSection _py_cs;\n" +" PyCriticalSection_Begin(&_py_cs, (PyObject*)(op))" + +#: ../../c-api/init.rst:2632 ../../c-api/init.rst:2678 +msgid "In the default build, this macro expands to ``{``." +msgstr "" + +#: ../../c-api/init.rst:2638 +msgid "Locks the mutex *m* and begins a critical section." +msgstr "" + +#: ../../c-api/init.rst:2642 +msgid "" +"{\n" +" PyCriticalSection _py_cs;\n" +" PyCriticalSection_BeginMutex(&_py_cs, m)" +msgstr "" +"{\n" +" PyCriticalSection _py_cs;\n" +" PyCriticalSection_BeginMutex(&_py_cs, m)" + +#: ../../c-api/init.rst:2646 +msgid "" +"Note that unlike :c:macro:`Py_BEGIN_CRITICAL_SECTION`, there is no cast for " +"the argument of the macro - it must be a :c:type:`PyMutex` pointer." +msgstr "" + +#: ../../c-api/init.rst:2649 ../../c-api/init.rst:2695 +msgid "On the default build, this macro expands to ``{``." +msgstr "" + +#: ../../c-api/init.rst:2655 +msgid "Ends the critical section and releases the per-object lock." +msgstr "" + +#: ../../c-api/init.rst:2659 +msgid "" +" PyCriticalSection_End(&_py_cs);\n" +"}" +msgstr "" +" PyCriticalSection_End(&_py_cs);\n" +"}" + +#: ../../c-api/init.rst:2662 ../../c-api/init.rst:2708 +msgid "In the default build, this macro expands to ``}``." +msgstr "" + +#: ../../c-api/init.rst:2668 +msgid "" +"Acquires the per-objects locks for the objects *a* and *b* and begins a " +"critical section. The locks are acquired in a consistent order (lowest " +"address first) to avoid lock ordering deadlocks." +msgstr "" + +#: ../../c-api/init.rst:2674 +msgid "" +"{\n" +" PyCriticalSection2 _py_cs2;\n" +" PyCriticalSection2_Begin(&_py_cs2, (PyObject*)(a), (PyObject*)(b))" +msgstr "" +"{\n" +" PyCriticalSection2 _py_cs2;\n" +" PyCriticalSection2_Begin(&_py_cs2, (PyObject*)(a), (PyObject*)(b))" + +#: ../../c-api/init.rst:2684 +msgid "Locks the mutexes *m1* and *m2* and begins a critical section." +msgstr "" + +#: ../../c-api/init.rst:2688 +msgid "" +"{\n" +" PyCriticalSection2 _py_cs2;\n" +" PyCriticalSection2_BeginMutex(&_py_cs2, m1, m2)" +msgstr "" +"{\n" +" PyCriticalSection2 _py_cs2;\n" +" PyCriticalSection2_BeginMutex(&_py_cs2, m1, m2)" + +#: ../../c-api/init.rst:2692 +msgid "" +"Note that unlike :c:macro:`Py_BEGIN_CRITICAL_SECTION2`, there is no cast for " +"the arguments of the macro - they must be :c:type:`PyMutex` pointers." +msgstr "" + +#: ../../c-api/init.rst:2701 +msgid "Ends the critical section and releases the per-object locks." +msgstr "" + +#: ../../c-api/init.rst:2705 +msgid "" +" PyCriticalSection2_End(&_py_cs2);\n" +"}" +msgstr "" +" PyCriticalSection2_End(&_py_cs2);\n" +"}" + +#: ../../c-api/init.rst:2714 +msgid "Legacy Locking APIs" +msgstr "" + +#: ../../c-api/init.rst:2716 +msgid "" +"These APIs are obsolete since Python 3.13 with the introduction of :c:type:" +"`PyMutex`." +msgstr "" + +#: ../../c-api/init.rst:2719 +msgid "These APIs are now a simple wrapper around ``PyMutex``." +msgstr "" + +#: ../../c-api/init.rst:2725 +msgid "A pointer to a mutual exclusion lock." +msgstr "" + +#: ../../c-api/init.rst:2730 +msgid "The result of acquiring a lock with a timeout." +msgstr "" + +#: ../../c-api/init.rst:2736 +msgid "Failed to acquire the lock." +msgstr "" + +#: ../../c-api/init.rst:2740 +msgid "The lock was successfully acquired." +msgstr "" + +#: ../../c-api/init.rst:2744 +msgid "The lock was interrupted by a signal." +msgstr "" + +#: ../../c-api/init.rst:2749 +msgid "Allocate a new lock." +msgstr "" + +#: ../../c-api/init.rst:2751 +msgid "" +"On success, this function returns a lock; on failure, this function returns " +"``0`` without an exception set." +msgstr "" + +#: ../../c-api/init.rst:2754 ../../c-api/init.rst:2766 +#: ../../c-api/init.rst:2786 ../../c-api/init.rst:2804 +#: ../../c-api/init.rst:2812 ../../c-api/init.rst:2835 +#: ../../c-api/init.rst:2919 ../../c-api/init.rst:2927 +msgid "The caller does not need to hold an :term:`attached thread state`." +msgstr "呼叫者不需擁有一個 :term:`attached thread state`。" + +#: ../../c-api/init.rst:2756 +msgid "" +"This function now always uses :c:type:`PyMutex`. In prior versions, this " +"would use a lock provided by the operating system." +msgstr "" + +#: ../../c-api/init.rst:2763 +msgid "" +"Destroy *lock*. The lock should not be held by any thread when calling this." +msgstr "" + +#: ../../c-api/init.rst:2771 +msgid "Acquire *lock* with a timeout." +msgstr "" + +#: ../../c-api/init.rst:2773 +msgid "" +"This will wait for *microseconds* microseconds to acquire the lock. If the " +"timeout expires, this function returns :c:enumerator:`PY_LOCK_FAILURE`. If " +"*microseconds* is ``-1``, this will wait indefinitely until the lock has " +"been released." +msgstr "" + +#: ../../c-api/init.rst:2778 +msgid "" +"If *intr_flag* is ``1``, acquiring the lock may be interrupted by a signal, " +"in which case this function returns :c:enumerator:`PY_LOCK_INTR`. Upon " +"interruption, it's generally expected that the caller makes a call to :c:" +"func:`Py_MakePendingCalls` to propagate an exception to Python code." +msgstr "" + +#: ../../c-api/init.rst:2783 +msgid "" +"If the lock is successfully acquired, this function returns :c:enumerator:" +"`PY_LOCK_ACQUIRED`." +msgstr "" + +#: ../../c-api/init.rst:2791 +msgid "Acquire *lock*." +msgstr "" + +#: ../../c-api/init.rst:2793 +msgid "" +"If *waitflag* is ``1`` and another thread currently holds the lock, this " +"function will wait until the lock can be acquired and will always return " +"``1``." +msgstr "" + +#: ../../c-api/init.rst:2797 +msgid "" +"If *waitflag* is ``0`` and another thread holds the lock, this function will " +"not wait and instead return ``0``. If the lock is not held by any other " +"thread, then this function will acquire it and return ``1``." +msgstr "" + +#: ../../c-api/init.rst:2801 +msgid "" +"Unlike :c:func:`PyThread_acquire_lock_timed`, acquiring the lock cannot be " +"interrupted by a signal." +msgstr "" + +#: ../../c-api/init.rst:2809 +msgid "" +"Release *lock*. If *lock* is not held, then this function issues a fatal " +"error." +msgstr "" + +#: ../../c-api/init.rst:2816 +msgid "Operating System Thread APIs" +msgstr "" + +#: ../../c-api/init.rst:2820 +msgid "Sentinel value for an invalid thread ID." +msgstr "" + +#: ../../c-api/init.rst:2822 +msgid "This is currently equivalent to ``(unsigned long)-1``." +msgstr "" + +#: ../../c-api/init.rst:2827 +msgid "" +"Start function *func* in a new thread with argument *arg*. The resulting " +"thread is not intended to be joined." +msgstr "" + +#: ../../c-api/init.rst:2830 +msgid "*func* must not be ``NULL``, but *arg* may be ``NULL``." +msgstr "" + +#: ../../c-api/init.rst:2832 +msgid "" +"On success, this function returns the identifier of the new thread; on " +"failure, this returns :c:macro:`PYTHREAD_INVALID_THREAD_ID`." +msgstr "" + +#: ../../c-api/init.rst:2840 +msgid "Return the identifier of the current thread, which will never be zero." +msgstr "" + +#: ../../c-api/init.rst:2842 ../../c-api/init.rst:2874 +msgid "" +"This function cannot fail, and the caller does not need to hold an :term:" +"`attached thread state`." +msgstr "" + +#: ../../c-api/init.rst:2846 +msgid ":py:func:`threading.get_ident`" +msgstr ":py:func:`threading.get_ident`" + +#: ../../c-api/init.rst:2851 +msgid "" +"Get general information about the current thread in the form of a :ref:" +"`struct sequence ` object. This information is " +"accessible as :py:attr:`sys.thread_info` in Python." +msgstr "" + +#: ../../c-api/init.rst:2855 +msgid "" +"On success, this returns a new :term:`strong reference` to the thread " +"information; on failure, this returns ``NULL`` with an exception set." +msgstr "" + +#: ../../c-api/init.rst:2858 +msgid "The caller must hold an :term:`attached thread state`." +msgstr "呼叫者必須擁有一個 :term:`attached thread state`。" + +#: ../../c-api/init.rst:2863 +msgid "This macro is defined when the system supports native thread IDs." +msgstr "" + +#: ../../c-api/init.rst:2868 +msgid "" +"Get the native identifier of the current thread as it was assigned by the " +"operating system's kernel, which will never be less than zero." +msgstr "" + +#: ../../c-api/init.rst:2871 +msgid "" +"This function is only available when :c:macro:`PY_HAVE_THREAD_NATIVE_ID` is " +"defined." +msgstr "" + +#: ../../c-api/init.rst:2878 +msgid ":py:func:`threading.get_native_id`" +msgstr ":py:func:`threading.get_native_id`" + +#: ../../c-api/init.rst:2883 +msgid "" +"Terminate the current thread. This function is generally considered unsafe " +"and should be avoided. It is kept solely for backwards compatibility." +msgstr "" + +#: ../../c-api/init.rst:2886 +msgid "" +"This function is only safe to call if all functions in the full call stack " +"are written to safely allow it." +msgstr "" + +#: ../../c-api/init.rst:2891 +msgid "" +"If the current system uses POSIX threads (also known as \"pthreads\"), this " +"calls :manpage:`pthread_exit(3)`, which attempts to unwind the stack and " +"call C++ destructors on some libc implementations. However, if a " +"``noexcept`` function is reached, it may terminate the process. Other " +"systems, such as macOS, do unwinding." +msgstr "" + +#: ../../c-api/init.rst:2897 +msgid "" +"On Windows, this function calls ``_endthreadex()``, which kills the thread " +"without calling C++ destructors." +msgstr "" + +#: ../../c-api/init.rst:2900 +msgid "In any case, there is a risk of corruption on the thread's stack." +msgstr "" + +#: ../../c-api/init.rst:2907 +msgid "" +"Initialize ``PyThread*`` APIs. Python executes this function automatically, " +"so there's little need to call it from an extension module." +msgstr "" + +#: ../../c-api/init.rst:2913 +msgid "Set the stack size of the current thread to *size* bytes." +msgstr "" + +#: ../../c-api/init.rst:2915 +msgid "" +"This function returns ``0`` on success, ``-1`` if *size* is invalid, or " +"``-2`` if the system does not support changing the stack size. This function " +"does not set exceptions." +msgstr "" + +#: ../../c-api/init.rst:2924 +msgid "" +"Return the stack size of the current thread in bytes, or ``0`` if the " +"system's default stack size is in use." +msgstr "" + +#: ../../c-api/init.rst:350 +msgid "PyEval_InitThreads()" +msgstr "PyEval_InitThreads()" + +#: ../../c-api/init.rst:350 +msgid "modules (in module sys)" +msgstr "modules（sys 模組中）" + +#: ../../c-api/init.rst:350 ../../c-api/init.rst:712 +msgid "path (in module sys)" +msgstr "path（sys 模組中）" + +#: ../../c-api/init.rst:350 ../../c-api/init.rst:712 ../../c-api/init.rst:1228 +#: ../../c-api/init.rst:1829 ../../c-api/init.rst:1928 +msgid "module" +msgstr "模組" + +#: ../../c-api/init.rst:350 ../../c-api/init.rst:1829 ../../c-api/init.rst:1928 +msgid "builtins" +msgstr "builtins（內建）" + +#: ../../c-api/init.rst:350 ../../c-api/init.rst:1829 ../../c-api/init.rst:1928 +msgid "__main__" +msgstr "__main__" + +#: ../../c-api/init.rst:350 ../../c-api/init.rst:1829 ../../c-api/init.rst:1928 +msgid "sys" +msgstr "sys" + +#: ../../c-api/init.rst:350 ../../c-api/init.rst:712 +msgid "search" +msgstr "search（搜尋）" + +#: ../../c-api/init.rst:350 ../../c-api/init.rst:712 +msgid "path" +msgstr "path（路徑）" + +#: ../../c-api/init.rst:350 ../../c-api/init.rst:1893 ../../c-api/init.rst:1946 +msgid "Py_FinalizeEx (C function)" +msgstr "Py_FinalizeEx（C 函式）" + +#: ../../c-api/init.rst:572 +msgid "Py_Initialize()" +msgstr "Py_Initialize()" + +#: ../../c-api/init.rst:572 ../../c-api/init.rst:810 +msgid "main()" +msgstr "main()" + +#: ../../c-api/init.rst:572 +msgid "Py_GetPath()" +msgstr "Py_GetPath()" + +#: ../../c-api/init.rst:690 +msgid "executable (in module sys)" +msgstr "executable（sys 模組中）" + +#: ../../c-api/init.rst:745 ../../c-api/init.rst:787 ../../c-api/init.rst:801 +msgid "version (in module sys)" +msgstr "version（sys 模組中）" + +#: ../../c-api/init.rst:757 +msgid "platform (in module sys)" +msgstr "platform（sys 模組中）" + +#: ../../c-api/init.rst:774 +msgid "copyright (in module sys)" +msgstr "copyright（sys 模組中）" + +#: ../../c-api/init.rst:810 +msgid "Py_FatalError()" +msgstr "Py_FatalError()" + +#: ../../c-api/init.rst:810 +msgid "argv (in module sys)" +msgstr "argv（sys 模組中）" + +#: ../../c-api/init.rst:930 +msgid "global interpreter lock" +msgstr "global interpreter lock（全域直譯器鎖）" + +#: ../../c-api/init.rst:930 +msgid "interpreter lock" +msgstr "interpreter lock（直譯器鎖）" + +#: ../../c-api/init.rst:930 +msgid "lock, interpreter" +msgstr "lock, interpreter（鎖、直譯器）" + +#: ../../c-api/init.rst:944 +msgid "setswitchinterval (in module sys)" +msgstr "setswitchinterval （sys 模組中）" + +#: ../../c-api/init.rst:953 +msgid "PyThreadState (C type)" +msgstr "PyThreadState（C 型別）" + +#: ../../c-api/init.rst:989 +msgid "Py_BEGIN_ALLOW_THREADS (C macro)" +msgstr "Py_BEGIN_ALLOW_THREADS（C 巨集）" + +#: ../../c-api/init.rst:989 +msgid "Py_END_ALLOW_THREADS (C macro)" +msgstr "Py_END_ALLOW_THREADS（C 巨集）" + +#: ../../c-api/init.rst:1005 +msgid "PyEval_RestoreThread (C function)" +msgstr "PyEval_RestoreThread（C 函式）" + +#: ../../c-api/init.rst:1005 +msgid "PyEval_SaveThread (C function)" +msgstr "PyEval_SaveThread（C 函式）" + +#: ../../c-api/init.rst:1206 +msgid "PyEval_AcquireThread()" +msgstr "PyEval_AcquireThread()" + +#: ../../c-api/init.rst:1206 +msgid "PyEval_ReleaseThread()" +msgstr "PyEval_ReleaseThread()" + +#: ../../c-api/init.rst:1206 +msgid "PyEval_SaveThread()" +msgstr "PyEval_SaveThread()" + +#: ../../c-api/init.rst:1206 +msgid "PyEval_RestoreThread()" +msgstr "PyEval_RestoreThread()" + +#: ../../c-api/init.rst:1228 +msgid "_thread" +msgstr "_thread" + +#: ../../c-api/init.rst:1829 ../../c-api/init.rst:1928 +msgid "stdout (in module sys)" +msgstr "stdout（sys 模組中）" + +#: ../../c-api/init.rst:1829 ../../c-api/init.rst:1928 +msgid "stderr (in module sys)" +msgstr "stderr（sys 模組中）" + +#: ../../c-api/init.rst:1829 ../../c-api/init.rst:1928 +msgid "stdin (in module sys)" +msgstr "stdin（sys 模組中）" + +#: ../../c-api/init.rst:1893 +msgid "Py_Initialize (C function)" +msgstr "Py_Initialize（C 函式）" + +#: ../../c-api/init.rst:1923 +msgid "close (in module os)" +msgstr "close（os 模組中）" + +#~ msgid "*tstate* must not be ``NULL``." +#~ msgstr "*tstate* 不可為 ``NULL``。" diff --git a/c-api/init_config.po b/c-api/init_config.po index 91e5b4ea80..4d9ffaa4b0 100644 --- a/c-api/init_config.po +++ b/c-api/init_config.po @@ -1,3422 +1,3422 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# FIRST AUTHOR , YEAR. -# -#, fuzzy -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-05 00:16+0000\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \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" - -#: ../../c-api/init_config.rst:7 -msgid "Python Initialization Configuration" -msgstr "Python 初始化設定" - -#: ../../c-api/init_config.rst:13 -msgid "PyInitConfig C API" -msgstr "PyInitConfig C API" - -#: ../../c-api/init_config.rst:17 -msgid "Python can be initialized with :c:func:`Py_InitializeFromInitConfig`." -msgstr "Python 可以使用 :c:func:`Py_InitializeFromInitConfig` 來初始化。" - -#: ../../c-api/init_config.rst:19 ../../c-api/init_config.rst:650 -msgid "" -"The :c:func:`Py_RunMain` function can be used to write a customized Python " -"program." -msgstr "" - -#: ../../c-api/init_config.rst:22 ../../c-api/init_config.rst:653 -msgid "" -"See also :ref:`Initialization, Finalization, and Threads `." -msgstr "" - -#: ../../c-api/init_config.rst:25 -msgid ":pep:`741` \"Python Configuration C API\"." -msgstr "" - -#: ../../c-api/init_config.rst:29 ../../c-api/init_config.rst:660 -msgid "Example" -msgstr "範例" - -#: ../../c-api/init_config.rst:31 -msgid "" -"Example of customized Python always running with the :ref:`Python " -"Development Mode ` enabled; return ``-1`` on error:" -msgstr "" - -#: ../../c-api/init_config.rst:34 -msgid "" -"int init_python(void)\n" -"{\n" -" PyInitConfig *config = PyInitConfig_Create();\n" -" if (config == NULL) {\n" -" printf(\"PYTHON INIT ERROR: memory allocation failed\\n\");\n" -" return -1;\n" -" }\n" -"\n" -" // Enable the Python Development Mode\n" -" if (PyInitConfig_SetInt(config, \"dev_mode\", 1) < 0) {\n" -" goto error;\n" -" }\n" -"\n" -" // Initialize Python with the configuration\n" -" if (Py_InitializeFromInitConfig(config) < 0) {\n" -" goto error;\n" -" }\n" -" PyInitConfig_Free(config);\n" -" return 0;\n" -"\n" -"error:\n" -" {\n" -" // Display the error message.\n" -" //\n" -" // This uncommon braces style is used, because you cannot make\n" -" // goto targets point to variable declarations.\n" -" const char *err_msg;\n" -" (void)PyInitConfig_GetError(config, &err_msg);\n" -" printf(\"PYTHON INIT ERROR: %s\\n\", err_msg);\n" -" PyInitConfig_Free(config);\n" -" return -1;\n" -" }\n" -"}" -msgstr "" - -#: ../../c-api/init_config.rst:71 -msgid "Create Config" -msgstr "建立設定" - -#: ../../c-api/init_config.rst:75 -msgid "Opaque structure to configure the Python initialization." -msgstr "" - -#: ../../c-api/init_config.rst:80 -msgid "" -"Create a new initialization configuration using :ref:`Isolated Configuration " -"` default values." -msgstr "" - -#: ../../c-api/init_config.rst:83 -msgid "It must be freed by :c:func:`PyInitConfig_Free`." -msgstr "必須由 :c:func:`PyInitConfig_Free` 來釋放。" - -#: ../../c-api/init_config.rst:85 -msgid "Return ``NULL`` on memory allocation failure." -msgstr "在記憶體配置失敗時回傳 ``NULL``。" - -#: ../../c-api/init_config.rst:90 -msgid "Free memory of the initialization configuration *config*." -msgstr "釋放初始化配置 *config* 的記憶體。" - -#: ../../c-api/init_config.rst:92 -msgid "If *config* is ``NULL``, no operation is performed." -msgstr "如果 *config* 是 ``NULL``，則不執行任何操作。" - -#: ../../c-api/init_config.rst:96 -msgid "Error Handling" -msgstr "錯誤處理" - -#: ../../c-api/init_config.rst:100 -msgid "Get the *config* error message." -msgstr "取得 *config* 錯誤訊息。" - -#: ../../c-api/init_config.rst:102 -msgid "Set *\\*err_msg* and return ``1`` if an error is set." -msgstr "如果設定了錯誤，則設置 *\\*err_msg* 並回傳 ``1``。" - -#: ../../c-api/init_config.rst:103 -msgid "Set *\\*err_msg* to ``NULL`` and return ``0`` otherwise." -msgstr "如果沒有設定錯誤，則設定 *\\*err_msg* 為 ``NULL`` 並回傳 ``0``。" - -#: ../../c-api/init_config.rst:105 -msgid "An error message is a UTF-8 encoded string." -msgstr "錯誤訊息是 UTF-8 編碼的字串。" - -#: ../../c-api/init_config.rst:107 -msgid "If *config* has an exit code, format the exit code as an error message." -msgstr "" - -#: ../../c-api/init_config.rst:110 -msgid "" -"The error message remains valid until another ``PyInitConfig`` function is " -"called with *config*. The caller doesn't have to free the error message." -msgstr "" - -#: ../../c-api/init_config.rst:117 -msgid "Get the *config* exit code." -msgstr "" - -#: ../../c-api/init_config.rst:119 -msgid "Set *\\*exitcode* and return ``1`` if *config* has an exit code set." -msgstr "" - -#: ../../c-api/init_config.rst:120 -msgid "Return ``0`` if *config* has no exit code set." -msgstr "" - -#: ../../c-api/init_config.rst:122 -msgid "" -"Only the ``Py_InitializeFromInitConfig()`` function can set an exit code if " -"the ``parse_argv`` option is non-zero." -msgstr "" - -#: ../../c-api/init_config.rst:125 -msgid "" -"An exit code can be set when parsing the command line failed (exit code " -"``2``) or when a command line option asks to display the command line help " -"(exit code ``0``)." -msgstr "" - -#: ../../c-api/init_config.rst:131 -msgid "Get Options" -msgstr "" - -#: ../../c-api/init_config.rst:133 ../../c-api/init_config.rst:187 -#: ../../c-api/init_config.rst:559 -msgid "" -"The configuration option *name* parameter must be a non-NULL null-terminated " -"UTF-8 encoded string. See :ref:`Configuration Options `." -msgstr "" - -#: ../../c-api/init_config.rst:138 -msgid "Test if the configuration has an option called *name*." -msgstr "測試配置是否有名為 *name* 的選項。" - -#: ../../c-api/init_config.rst:140 -msgid "Return ``1`` if the option exists, or return ``0`` otherwise." -msgstr "如果選項存在則回傳 ``1``，否則回傳 ``0``。" - -#: ../../c-api/init_config.rst:145 -msgid "Get an integer configuration option." -msgstr "" - -#: ../../c-api/init_config.rst:147 ../../c-api/init_config.rst:156 -msgid "Set *\\*value*, and return ``0`` on success." -msgstr "" - -#: ../../c-api/init_config.rst:148 ../../c-api/init_config.rst:157 -#: ../../c-api/init_config.rst:172 ../../c-api/init_config.rst:200 -#: ../../c-api/init_config.rst:209 ../../c-api/init_config.rst:218 -#: ../../c-api/init_config.rst:233 ../../c-api/init_config.rst:249 -msgid "Set an error in *config* and return ``-1`` on error." -msgstr "" - -#: ../../c-api/init_config.rst:153 -msgid "" -"Get a string configuration option as a null-terminated UTF-8 encoded string." -msgstr "" - -#: ../../c-api/init_config.rst:159 -msgid "" -"*\\*value* can be set to ``NULL`` if the option is an optional string and " -"the option is unset." -msgstr "" - -#: ../../c-api/init_config.rst:162 -msgid "" -"On success, the string must be released with ``free(value)`` if it's not " -"``NULL``." -msgstr "" - -#: ../../c-api/init_config.rst:168 -msgid "" -"Get a string list configuration option as an array of null-terminated UTF-8 " -"encoded strings." -msgstr "" - -#: ../../c-api/init_config.rst:171 -msgid "Set *\\*length* and *\\*value*, and return ``0`` on success." -msgstr "" - -#: ../../c-api/init_config.rst:174 -msgid "" -"On success, the string list must be released with " -"``PyInitConfig_FreeStrList(length, items)``." -msgstr "" - -#: ../../c-api/init_config.rst:180 -msgid "Free memory of a string list created by ``PyInitConfig_GetStrList()``." -msgstr "" - -#: ../../c-api/init_config.rst:185 -msgid "Set Options" -msgstr "" - -#: ../../c-api/init_config.rst:190 -msgid "" -"Some configuration options have side effects on other options. This logic is " -"only implemented when ``Py_InitializeFromInitConfig()`` is called, not by " -"the \"Set\" functions below. For example, setting ``dev_mode`` to ``1`` does " -"not set ``faulthandler`` to ``1``." -msgstr "" - -#: ../../c-api/init_config.rst:197 -msgid "Set an integer configuration option." -msgstr "" - -#: ../../c-api/init_config.rst:199 ../../c-api/init_config.rst:208 -#: ../../c-api/init_config.rst:217 ../../c-api/init_config.rst:232 -#: ../../c-api/init_config.rst:248 ../../c-api/init_config.rst:591 -msgid "Return ``0`` on success." -msgstr "成功時回傳 ``0``。" - -#: ../../c-api/init_config.rst:205 -msgid "" -"Set a string configuration option from a null-terminated UTF-8 encoded " -"string. The string is copied." -msgstr "" - -#: ../../c-api/init_config.rst:214 -msgid "" -"Set a string list configuration option from an array of null-terminated " -"UTF-8 encoded strings. The string list is copied." -msgstr "" - -#: ../../c-api/init_config.rst:222 -msgid "Module" -msgstr "模組" - -#: ../../c-api/init_config.rst:226 -msgid "Add a built-in extension module to the table of built-in modules." -msgstr "" - -#: ../../c-api/init_config.rst:228 -msgid "" -"The new module can be imported by the name *name*, and uses the function " -"*initfunc* as the initialization function called on the first attempted " -"import." -msgstr "" - -#: ../../c-api/init_config.rst:235 -msgid "" -"If Python is initialized multiple times, ``PyInitConfig_AddModule()`` must " -"be called at each Python initialization." -msgstr "" - -#: ../../c-api/init_config.rst:238 -msgid "Similar to the :c:func:`PyImport_AppendInittab` function." -msgstr "和 :c:func:`PyImport_AppendInittab` 函式類似。" - -#: ../../c-api/init_config.rst:242 -msgid "Initialize Python" -msgstr "初始化 Python" - -#: ../../c-api/init_config.rst:246 -msgid "Initialize Python from the initialization configuration." -msgstr "" - -#: ../../c-api/init_config.rst:250 -msgid "Set an exit code in *config* and return ``-1`` if Python wants to exit." -msgstr "" - -#: ../../c-api/init_config.rst:253 -msgid "See ``PyInitConfig_GetExitcode()`` for the exit code case." -msgstr "" - -#: ../../c-api/init_config.rst:259 -msgid "Configuration Options" -msgstr "" - -#: ../../c-api/init_config.rst:264 -msgid "Option" -msgstr "選項" - -#: ../../c-api/init_config.rst:265 -msgid "PyConfig/PyPreConfig member" -msgstr "PyConfig/PyPreConfig 成員" - -#: ../../c-api/init_config.rst:266 -msgid "Type" -msgstr "" - -#: ../../c-api/init_config.rst:267 -msgid "Visibility" -msgstr "" - -#: ../../c-api/init_config.rst:268 -msgid "``\"allocator\"``" -msgstr "``\"allocator\"``" - -#: ../../c-api/init_config.rst:269 -msgid ":c:member:`allocator `" -msgstr ":c:member:`allocator `" - -#: ../../c-api/init_config.rst:270 ../../c-api/init_config.rst:294 -#: ../../c-api/init_config.rst:322 ../../c-api/init_config.rst:358 -#: ../../c-api/init_config.rst:366 ../../c-api/init_config.rst:378 -#: ../../c-api/init_config.rst:406 ../../c-api/init_config.rst:494 -#: ../../c-api/init_config.rst:522 ../../c-api/init_config.rst:576 -msgid "``int``" -msgstr "``int``" - -#: ../../c-api/init_config.rst:271 ../../c-api/init_config.rst:291 -#: ../../c-api/init_config.rst:299 ../../c-api/init_config.rst:303 -#: ../../c-api/init_config.rst:307 ../../c-api/init_config.rst:311 -#: ../../c-api/init_config.rst:315 ../../c-api/init_config.rst:319 -#: ../../c-api/init_config.rst:327 ../../c-api/init_config.rst:331 -#: ../../c-api/init_config.rst:335 ../../c-api/init_config.rst:347 -#: ../../c-api/init_config.rst:351 ../../c-api/init_config.rst:355 -#: ../../c-api/init_config.rst:359 ../../c-api/init_config.rst:363 -#: ../../c-api/init_config.rst:367 ../../c-api/init_config.rst:375 -#: ../../c-api/init_config.rst:387 ../../c-api/init_config.rst:391 -#: ../../c-api/init_config.rst:395 ../../c-api/init_config.rst:399 -#: ../../c-api/init_config.rst:411 ../../c-api/init_config.rst:415 -#: ../../c-api/init_config.rst:423 ../../c-api/init_config.rst:427 -#: ../../c-api/init_config.rst:439 ../../c-api/init_config.rst:451 -#: ../../c-api/init_config.rst:455 ../../c-api/init_config.rst:459 -#: ../../c-api/init_config.rst:463 ../../c-api/init_config.rst:467 -#: ../../c-api/init_config.rst:471 ../../c-api/init_config.rst:475 -#: ../../c-api/init_config.rst:479 ../../c-api/init_config.rst:483 -#: ../../c-api/init_config.rst:487 ../../c-api/init_config.rst:495 -#: ../../c-api/init_config.rst:503 ../../c-api/init_config.rst:507 -#: ../../c-api/init_config.rst:511 ../../c-api/init_config.rst:515 -#: ../../c-api/init_config.rst:519 ../../c-api/init_config.rst:527 -#: ../../c-api/init_config.rst:543 -msgid "Read-only" -msgstr "唯讀" - -#: ../../c-api/init_config.rst:272 -msgid "``\"argv\"``" -msgstr "``\"argv\"``" - -#: ../../c-api/init_config.rst:273 -msgid ":c:member:`argv `" -msgstr ":c:member:`argv `" - -#: ../../c-api/init_config.rst:274 ../../c-api/init_config.rst:402 -#: ../../c-api/init_config.rst:410 ../../c-api/init_config.rst:530 -#: ../../c-api/init_config.rst:578 -msgid "``list[str]``" -msgstr "``list[str]``" - -#: ../../c-api/init_config.rst:275 ../../c-api/init_config.rst:279 -#: ../../c-api/init_config.rst:283 ../../c-api/init_config.rst:287 -#: ../../c-api/init_config.rst:295 ../../c-api/init_config.rst:323 -#: ../../c-api/init_config.rst:339 ../../c-api/init_config.rst:343 -#: ../../c-api/init_config.rst:371 ../../c-api/init_config.rst:379 -#: ../../c-api/init_config.rst:383 ../../c-api/init_config.rst:403 -#: ../../c-api/init_config.rst:407 ../../c-api/init_config.rst:419 -#: ../../c-api/init_config.rst:431 ../../c-api/init_config.rst:435 -#: ../../c-api/init_config.rst:443 ../../c-api/init_config.rst:447 -#: ../../c-api/init_config.rst:491 ../../c-api/init_config.rst:499 -#: ../../c-api/init_config.rst:523 ../../c-api/init_config.rst:531 -#: ../../c-api/init_config.rst:535 ../../c-api/init_config.rst:539 -msgid "Public" -msgstr "公開" - -#: ../../c-api/init_config.rst:276 -msgid "``\"base_exec_prefix\"``" -msgstr "``\"base_exec_prefix\"``" - -#: ../../c-api/init_config.rst:277 -msgid ":c:member:`base_exec_prefix `" -msgstr ":c:member:`base_exec_prefix `" - -#: ../../c-api/init_config.rst:278 ../../c-api/init_config.rst:282 -#: ../../c-api/init_config.rst:286 ../../c-api/init_config.rst:298 -#: ../../c-api/init_config.rst:334 ../../c-api/init_config.rst:338 -#: ../../c-api/init_config.rst:342 ../../c-api/init_config.rst:350 -#: ../../c-api/init_config.rst:354 ../../c-api/init_config.rst:362 -#: ../../c-api/init_config.rst:430 ../../c-api/init_config.rst:434 -#: ../../c-api/init_config.rst:438 ../../c-api/init_config.rst:442 -#: ../../c-api/init_config.rst:450 ../../c-api/init_config.rst:454 -#: ../../c-api/init_config.rst:458 ../../c-api/init_config.rst:462 -#: ../../c-api/init_config.rst:482 ../../c-api/init_config.rst:486 -#: ../../c-api/init_config.rst:490 ../../c-api/init_config.rst:577 -msgid "``str``" -msgstr "``str``" - -#: ../../c-api/init_config.rst:280 -msgid "``\"base_executable\"``" -msgstr "``\"base_executable\"``" - -#: ../../c-api/init_config.rst:281 -msgid ":c:member:`base_executable `" -msgstr ":c:member:`base_executable `" - -#: ../../c-api/init_config.rst:284 -msgid "``\"base_prefix\"``" -msgstr "``\"base_prefix\"``" - -#: ../../c-api/init_config.rst:285 -msgid ":c:member:`base_prefix `" -msgstr ":c:member:`base_prefix `" - -#: ../../c-api/init_config.rst:288 -msgid "``\"buffered_stdio\"``" -msgstr "``\"buffered_stdio\"``" - -#: ../../c-api/init_config.rst:289 -msgid ":c:member:`buffered_stdio `" -msgstr ":c:member:`buffered_stdio `" - -#: ../../c-api/init_config.rst:290 ../../c-api/init_config.rst:302 -#: ../../c-api/init_config.rst:306 ../../c-api/init_config.rst:310 -#: ../../c-api/init_config.rst:314 ../../c-api/init_config.rst:318 -#: ../../c-api/init_config.rst:326 ../../c-api/init_config.rst:330 -#: ../../c-api/init_config.rst:346 ../../c-api/init_config.rst:370 -#: ../../c-api/init_config.rst:374 ../../c-api/init_config.rst:382 -#: ../../c-api/init_config.rst:386 ../../c-api/init_config.rst:390 -#: ../../c-api/init_config.rst:394 ../../c-api/init_config.rst:398 -#: ../../c-api/init_config.rst:414 ../../c-api/init_config.rst:418 -#: ../../c-api/init_config.rst:422 ../../c-api/init_config.rst:426 -#: ../../c-api/init_config.rst:446 ../../c-api/init_config.rst:466 -#: ../../c-api/init_config.rst:470 ../../c-api/init_config.rst:474 -#: ../../c-api/init_config.rst:478 ../../c-api/init_config.rst:498 -#: ../../c-api/init_config.rst:502 ../../c-api/init_config.rst:506 -#: ../../c-api/init_config.rst:510 ../../c-api/init_config.rst:514 -#: ../../c-api/init_config.rst:518 ../../c-api/init_config.rst:526 -#: ../../c-api/init_config.rst:534 ../../c-api/init_config.rst:542 -#: ../../c-api/init_config.rst:575 -msgid "``bool``" -msgstr "``bool``" - -#: ../../c-api/init_config.rst:292 -msgid "``\"bytes_warning\"``" -msgstr "``\"bytes_warning\"``" - -#: ../../c-api/init_config.rst:293 -msgid ":c:member:`bytes_warning `" -msgstr ":c:member:`bytes_warning `" - -#: ../../c-api/init_config.rst:296 -msgid "``\"check_hash_pycs_mode\"``" -msgstr "``\"check_hash_pycs_mode\"``" - -#: ../../c-api/init_config.rst:297 -msgid ":c:member:`check_hash_pycs_mode `" -msgstr ":c:member:`check_hash_pycs_mode `" - -#: ../../c-api/init_config.rst:300 -msgid "``\"code_debug_ranges\"``" -msgstr "``\"code_debug_ranges\"``" - -#: ../../c-api/init_config.rst:301 -msgid ":c:member:`code_debug_ranges `" -msgstr ":c:member:`code_debug_ranges `" - -#: ../../c-api/init_config.rst:304 -msgid "``\"coerce_c_locale\"``" -msgstr "``\"coerce_c_locale\"``" - -#: ../../c-api/init_config.rst:305 -msgid ":c:member:`coerce_c_locale `" -msgstr ":c:member:`coerce_c_locale `" - -#: ../../c-api/init_config.rst:308 -msgid "``\"coerce_c_locale_warn\"``" -msgstr "``\"coerce_c_locale_warn\"``" - -#: ../../c-api/init_config.rst:309 -msgid ":c:member:`coerce_c_locale_warn `" -msgstr ":c:member:`coerce_c_locale_warn `" - -#: ../../c-api/init_config.rst:312 -msgid "``\"configure_c_stdio\"``" -msgstr "``\"configure_c_stdio\"``" - -#: ../../c-api/init_config.rst:313 -msgid ":c:member:`configure_c_stdio `" -msgstr ":c:member:`configure_c_stdio `" - -#: ../../c-api/init_config.rst:316 -msgid "``\"configure_locale\"``" -msgstr "``\"configure_locale\"``" - -#: ../../c-api/init_config.rst:317 -msgid ":c:member:`configure_locale `" -msgstr ":c:member:`configure_locale `" - -#: ../../c-api/init_config.rst:320 -msgid "``\"cpu_count\"``" -msgstr "``\"cpu_count\"``" - -#: ../../c-api/init_config.rst:321 -msgid ":c:member:`cpu_count `" -msgstr ":c:member:`cpu_count `" - -#: ../../c-api/init_config.rst:324 -msgid "``\"dev_mode\"``" -msgstr "``\"dev_mode\"``" - -#: ../../c-api/init_config.rst:325 -msgid ":c:member:`dev_mode `" -msgstr ":c:member:`dev_mode `" - -#: ../../c-api/init_config.rst:328 -msgid "``\"dump_refs\"``" -msgstr "``\"dump_refs\"``" - -#: ../../c-api/init_config.rst:329 -msgid ":c:member:`dump_refs `" -msgstr ":c:member:`dump_refs `" - -#: ../../c-api/init_config.rst:332 -msgid "``\"dump_refs_file\"``" -msgstr "``\"dump_refs_file\"``" - -#: ../../c-api/init_config.rst:333 -msgid ":c:member:`dump_refs_file `" -msgstr ":c:member:`dump_refs_file `" - -#: ../../c-api/init_config.rst:336 -msgid "``\"exec_prefix\"``" -msgstr "``\"exec_prefix\"``" - -#: ../../c-api/init_config.rst:337 -msgid ":c:member:`exec_prefix `" -msgstr ":c:member:`exec_prefix `" - -#: ../../c-api/init_config.rst:340 -msgid "``\"executable\"``" -msgstr "``\"executable\"``" - -#: ../../c-api/init_config.rst:341 -msgid ":c:member:`executable `" -msgstr ":c:member:`executable `" - -#: ../../c-api/init_config.rst:344 -msgid "``\"faulthandler\"``" -msgstr "``\"faulthandler\"``" - -#: ../../c-api/init_config.rst:345 -msgid ":c:member:`faulthandler `" -msgstr ":c:member:`faulthandler `" - -#: ../../c-api/init_config.rst:348 -msgid "``\"filesystem_encoding\"``" -msgstr "``\"filesystem_encoding\"``" - -#: ../../c-api/init_config.rst:349 -msgid ":c:member:`filesystem_encoding `" -msgstr ":c:member:`filesystem_encoding `" - -#: ../../c-api/init_config.rst:352 -msgid "``\"filesystem_errors\"``" -msgstr "``\"filesystem_errors\"``" - -#: ../../c-api/init_config.rst:353 -msgid ":c:member:`filesystem_errors `" -msgstr ":c:member:`filesystem_errors `" - -#: ../../c-api/init_config.rst:356 -msgid "``\"hash_seed\"``" -msgstr "``\"hash_seed\"``" - -#: ../../c-api/init_config.rst:357 -msgid ":c:member:`hash_seed `" -msgstr ":c:member:`hash_seed `" - -#: ../../c-api/init_config.rst:360 -msgid "``\"home\"``" -msgstr "``\"home\"``" - -#: ../../c-api/init_config.rst:361 -msgid ":c:member:`home `" -msgstr ":c:member:`home `" - -#: ../../c-api/init_config.rst:364 -msgid "``\"import_time\"``" -msgstr "``\"import_time\"``" - -#: ../../c-api/init_config.rst:365 -msgid ":c:member:`import_time `" -msgstr ":c:member:`import_time `" - -#: ../../c-api/init_config.rst:368 -msgid "``\"inspect\"``" -msgstr "``\"inspect\"``" - -#: ../../c-api/init_config.rst:369 -msgid ":c:member:`inspect `" -msgstr ":c:member:`inspect `" - -#: ../../c-api/init_config.rst:372 -msgid "``\"install_signal_handlers\"``" -msgstr "``\"install_signal_handlers\"``" - -#: ../../c-api/init_config.rst:373 -msgid ":c:member:`install_signal_handlers `" -msgstr ":c:member:`install_signal_handlers `" - -#: ../../c-api/init_config.rst:376 -msgid "``\"int_max_str_digits\"``" -msgstr "``\"int_max_str_digits\"``" - -#: ../../c-api/init_config.rst:377 -msgid ":c:member:`int_max_str_digits `" -msgstr ":c:member:`int_max_str_digits `" - -#: ../../c-api/init_config.rst:380 -msgid "``\"interactive\"``" -msgstr "``\"interactive\"``" - -#: ../../c-api/init_config.rst:381 -msgid ":c:member:`interactive `" -msgstr ":c:member:`interactive `" - -#: ../../c-api/init_config.rst:384 -msgid "``\"isolated\"``" -msgstr "``\"isolated\"``" - -#: ../../c-api/init_config.rst:385 -msgid ":c:member:`isolated `" -msgstr ":c:member:`isolated `" - -#: ../../c-api/init_config.rst:388 -msgid "``\"legacy_windows_fs_encoding\"``" -msgstr "``\"legacy_windows_fs_encoding\"``" - -#: ../../c-api/init_config.rst:389 -msgid "" -":c:member:`legacy_windows_fs_encoding `" -msgstr "" -":c:member:`legacy_windows_fs_encoding `" - -#: ../../c-api/init_config.rst:392 -msgid "``\"legacy_windows_stdio\"``" -msgstr "``\"legacy_windows_stdio\"``" - -#: ../../c-api/init_config.rst:393 -msgid ":c:member:`legacy_windows_stdio `" -msgstr ":c:member:`legacy_windows_stdio `" - -#: ../../c-api/init_config.rst:396 -msgid "``\"malloc_stats\"``" -msgstr "``\"malloc_stats\"``" - -#: ../../c-api/init_config.rst:397 -msgid ":c:member:`malloc_stats `" -msgstr ":c:member:`malloc_stats `" - -#: ../../c-api/init_config.rst:400 -msgid "``\"module_search_paths\"``" -msgstr "``\"module_search_paths\"``" - -#: ../../c-api/init_config.rst:401 -msgid ":c:member:`module_search_paths `" -msgstr ":c:member:`module_search_paths `" - -#: ../../c-api/init_config.rst:404 -msgid "``\"optimization_level\"``" -msgstr "``\"optimization_level\"``" - -#: ../../c-api/init_config.rst:405 -msgid ":c:member:`optimization_level `" -msgstr ":c:member:`optimization_level `" - -#: ../../c-api/init_config.rst:408 -msgid "``\"orig_argv\"``" -msgstr "``\"orig_argv\"``" - -#: ../../c-api/init_config.rst:409 -msgid ":c:member:`orig_argv `" -msgstr ":c:member:`orig_argv `" - -#: ../../c-api/init_config.rst:412 -msgid "``\"parse_argv\"``" -msgstr "``\"parse_argv\"``" - -#: ../../c-api/init_config.rst:413 -msgid ":c:member:`parse_argv `" -msgstr ":c:member:`parse_argv `" - -#: ../../c-api/init_config.rst:416 -msgid "``\"parser_debug\"``" -msgstr "``\"parser_debug\"``" - -#: ../../c-api/init_config.rst:417 -msgid ":c:member:`parser_debug `" -msgstr ":c:member:`parser_debug `" - -#: ../../c-api/init_config.rst:420 -msgid "``\"pathconfig_warnings\"``" -msgstr "``\"pathconfig_warnings\"``" - -#: ../../c-api/init_config.rst:421 -msgid ":c:member:`pathconfig_warnings `" -msgstr ":c:member:`pathconfig_warnings `" - -#: ../../c-api/init_config.rst:424 -msgid "``\"perf_profiling\"``" -msgstr "``\"perf_profiling\"``" - -#: ../../c-api/init_config.rst:425 -msgid ":c:member:`perf_profiling `" -msgstr ":c:member:`perf_profiling `" - -#: ../../c-api/init_config.rst:428 -msgid "``\"platlibdir\"``" -msgstr "``\"platlibdir\"``" - -#: ../../c-api/init_config.rst:429 -msgid ":c:member:`platlibdir `" -msgstr ":c:member:`platlibdir `" - -#: ../../c-api/init_config.rst:432 -msgid "``\"prefix\"``" -msgstr "``\"prefix\"``" - -#: ../../c-api/init_config.rst:433 -msgid ":c:member:`prefix `" -msgstr ":c:member:`prefix `" - -#: ../../c-api/init_config.rst:436 -msgid "``\"program_name\"``" -msgstr "``\"surrogateescape\"``" - -#: ../../c-api/init_config.rst:437 -msgid ":c:member:`program_name `" -msgstr ":c:member:`program_name `" - -#: ../../c-api/init_config.rst:440 -msgid "``\"pycache_prefix\"``" -msgstr "``\"pycache_prefix\"``" - -#: ../../c-api/init_config.rst:441 -msgid ":c:member:`pycache_prefix `" -msgstr ":c:member:`pycache_prefix `" - -#: ../../c-api/init_config.rst:444 -msgid "``\"quiet\"``" -msgstr "``\"quiet\"``" - -#: ../../c-api/init_config.rst:445 -msgid ":c:member:`quiet `" -msgstr ":c:member:`quiet `" - -#: ../../c-api/init_config.rst:448 -msgid "``\"run_command\"``" -msgstr "``\"run_command\"``" - -#: ../../c-api/init_config.rst:449 -msgid ":c:member:`run_command `" -msgstr ":c:member:`run_command `" - -#: ../../c-api/init_config.rst:452 -msgid "``\"run_filename\"``" -msgstr "``\"run_filename\"``" - -#: ../../c-api/init_config.rst:453 -msgid ":c:member:`run_filename `" -msgstr ":c:member:`run_filename `" - -#: ../../c-api/init_config.rst:456 -msgid "``\"run_module\"``" -msgstr "``\"run_module\"``" - -#: ../../c-api/init_config.rst:457 -msgid ":c:member:`run_module `" -msgstr ":c:member:`run_module `" - -#: ../../c-api/init_config.rst:460 -msgid "``\"run_presite\"``" -msgstr "``\"run_presite\"``" - -#: ../../c-api/init_config.rst:461 -msgid ":c:member:`run_presite `" -msgstr ":c:member:`run_presite `" - -#: ../../c-api/init_config.rst:464 -msgid "``\"safe_path\"``" -msgstr "``\"safe_path\"``" - -#: ../../c-api/init_config.rst:465 -msgid ":c:member:`safe_path `" -msgstr ":c:member:`safe_path `" - -#: ../../c-api/init_config.rst:468 -msgid "``\"show_ref_count\"``" -msgstr "``\"show_ref_count\"``" - -#: ../../c-api/init_config.rst:469 -msgid ":c:member:`show_ref_count `" -msgstr ":c:member:`show_ref_count `" - -#: ../../c-api/init_config.rst:472 -msgid "``\"site_import\"``" -msgstr "``\"site_import\"``" - -#: ../../c-api/init_config.rst:473 -msgid ":c:member:`site_import `" -msgstr ":c:member:`site_import `" - -#: ../../c-api/init_config.rst:476 -msgid "``\"skip_source_first_line\"``" -msgstr "``\"skip_source_first_line\"``" - -#: ../../c-api/init_config.rst:477 -msgid ":c:member:`skip_source_first_line `" -msgstr ":c:member:`skip_source_first_line `" - -#: ../../c-api/init_config.rst:480 -msgid "``\"stdio_encoding\"``" -msgstr "``\"stdio_encoding\"``" - -#: ../../c-api/init_config.rst:481 -msgid ":c:member:`stdio_encoding `" -msgstr ":c:member:`stdio_encoding `" - -#: ../../c-api/init_config.rst:484 -msgid "``\"stdio_errors\"``" -msgstr "``\"stdio_errors\"``" - -#: ../../c-api/init_config.rst:485 -msgid ":c:member:`stdio_errors `" -msgstr ":c:member:`stdio_errors `" - -#: ../../c-api/init_config.rst:488 -msgid "``\"stdlib_dir\"``" -msgstr "``\"stdlib_dir\"``" - -#: ../../c-api/init_config.rst:489 -msgid ":c:member:`stdlib_dir `" -msgstr ":c:member:`stdlib_dir `" - -#: ../../c-api/init_config.rst:492 -msgid "``\"tracemalloc\"``" -msgstr "``\"tracemalloc\"``" - -#: ../../c-api/init_config.rst:493 -msgid ":c:member:`tracemalloc `" -msgstr ":c:member:`tracemalloc `" - -#: ../../c-api/init_config.rst:496 -msgid "``\"use_environment\"``" -msgstr "``\"use_environment\"``" - -#: ../../c-api/init_config.rst:497 -msgid ":c:member:`use_environment `" -msgstr ":c:member:`use_environment `" - -#: ../../c-api/init_config.rst:500 -msgid "``\"use_frozen_modules\"``" -msgstr "``\"use_frozen_modules\"``" - -#: ../../c-api/init_config.rst:501 -msgid ":c:member:`use_frozen_modules `" -msgstr ":c:member:`use_frozen_modules `" - -#: ../../c-api/init_config.rst:504 -msgid "``\"use_hash_seed\"``" -msgstr "``\"use_hash_seed\"``" - -#: ../../c-api/init_config.rst:505 -msgid ":c:member:`use_hash_seed `" -msgstr ":c:member:`use_hash_seed `" - -#: ../../c-api/init_config.rst:508 -msgid "``\"use_system_logger\"``" -msgstr "``\"use_system_logger\"``" - -#: ../../c-api/init_config.rst:509 -msgid ":c:member:`use_system_logger `" -msgstr ":c:member:`use_system_logger `" - -#: ../../c-api/init_config.rst:512 -msgid "``\"user_site_directory\"``" -msgstr "``\"user_site_directory\"``" - -#: ../../c-api/init_config.rst:513 -msgid ":c:member:`user_site_directory `" -msgstr ":c:member:`user_site_directory `" - -#: ../../c-api/init_config.rst:516 -msgid "``\"utf8_mode\"``" -msgstr "``\"utf8_mode\"``" - -#: ../../c-api/init_config.rst:517 -msgid ":c:member:`utf8_mode `" -msgstr ":c:member:`utf8_mode `" - -#: ../../c-api/init_config.rst:520 -msgid "``\"verbose\"``" -msgstr "``\"verbose\"``" - -#: ../../c-api/init_config.rst:521 -msgid ":c:member:`verbose `" -msgstr ":c:member:`verbose `" - -#: ../../c-api/init_config.rst:524 -msgid "``\"warn_default_encoding\"``" -msgstr "``\"warn_default_encoding\"``" - -#: ../../c-api/init_config.rst:525 -msgid ":c:member:`warn_default_encoding `" -msgstr ":c:member:`warn_default_encoding `" - -#: ../../c-api/init_config.rst:528 -msgid "``\"warnoptions\"``" -msgstr "``\"warnoptions\"``" - -#: ../../c-api/init_config.rst:529 -msgid ":c:member:`warnoptions `" -msgstr ":c:member:`warnoptions `" - -#: ../../c-api/init_config.rst:532 -msgid "``\"write_bytecode\"``" -msgstr "``\"write_bytecode\"``" - -#: ../../c-api/init_config.rst:533 -msgid ":c:member:`write_bytecode `" -msgstr ":c:member:`write_bytecode `" - -#: ../../c-api/init_config.rst:536 -msgid "``\"xoptions\"``" -msgstr "``\"xoptions\"``" - -#: ../../c-api/init_config.rst:537 -msgid ":c:member:`xoptions `" -msgstr ":c:member:`xoptions `" - -#: ../../c-api/init_config.rst:538 ../../c-api/init_config.rst:579 -msgid "``dict[str, str]``" -msgstr "``dict[str, str]``" - -#: ../../c-api/init_config.rst:540 -msgid "``\"_pystats\"``" -msgstr "``\"_pystats\"``" - -#: ../../c-api/init_config.rst:541 -msgid ":c:member:`_pystats `" -msgstr ":c:member:`_pystats `" - -#: ../../c-api/init_config.rst:545 -msgid "Visibility:" -msgstr "" - -#: ../../c-api/init_config.rst:547 -msgid "" -"Public: Can by get by :c:func:`PyConfig_Get` and set by :c:func:" -"`PyConfig_Set`." -msgstr "" - -#: ../../c-api/init_config.rst:549 -msgid "" -"Read-only: Can by get by :c:func:`PyConfig_Get`, but cannot be set by :c:" -"func:`PyConfig_Set`." -msgstr "" - -#: ../../c-api/init_config.rst:554 -msgid "Runtime Python configuration API" -msgstr "" - -#: ../../c-api/init_config.rst:556 -msgid "" -"At runtime, it's possible to get and set configuration options using :c:func:" -"`PyConfig_Get` and :c:func:`PyConfig_Set` functions." -msgstr "" - -#: ../../c-api/init_config.rst:562 -msgid "" -"Some options are read from the :mod:`sys` attributes. For example, the " -"option ``\"argv\"`` is read from :data:`sys.argv`." -msgstr "" - -#: ../../c-api/init_config.rst:568 -msgid "" -"Get the current runtime value of a configuration option as a Python object." -msgstr "" - -#: ../../c-api/init_config.rst:570 ../../c-api/init_config.rst:601 -msgid "Return a new reference on success." -msgstr "" - -#: ../../c-api/init_config.rst:571 ../../c-api/init_config.rst:602 -msgid "Set an exception and return ``NULL`` on error." -msgstr "" - -#: ../../c-api/init_config.rst:573 -msgid "The object type depends on the configuration option. It can be:" -msgstr "" - -#: ../../c-api/init_config.rst:581 ../../c-api/init_config.rst:604 -#: ../../c-api/init_config.rst:619 -msgid "" -"The caller must have an :term:`attached thread state`. The function cannot " -"be called before Python initialization nor after Python finalization." -msgstr "" - -#: ../../c-api/init_config.rst:589 -msgid "Similar to :c:func:`PyConfig_Get`, but get the value as a C int." -msgstr "" - -#: ../../c-api/init_config.rst:592 -msgid "Set an exception and return ``-1`` on error." -msgstr "" - -#: ../../c-api/init_config.rst:599 -msgid "Get all configuration option names as a ``frozenset``." -msgstr "" - -#: ../../c-api/init_config.rst:612 -msgid "Set the current runtime value of a configuration option." -msgstr "" - -#: ../../c-api/init_config.rst:614 -msgid "Raise a :exc:`ValueError` if there is no option *name*." -msgstr "如果沒有選項 *name*，則引發 :exc:`ValueError`。" - -#: ../../c-api/init_config.rst:615 -msgid "Raise a :exc:`ValueError` if *value* is an invalid value." -msgstr "如果 *value* 是無效值，則引發 :exc:`ValueError`。" - -#: ../../c-api/init_config.rst:616 -msgid "Raise a :exc:`ValueError` if the option is read-only (cannot be set)." -msgstr "如果選項是唯讀的（無法設定），則引發 :exc:`ValueError`。" - -#: ../../c-api/init_config.rst:617 -msgid "Raise a :exc:`TypeError` if *value* has not the proper type." -msgstr "" - -#: ../../c-api/init_config.rst:622 -msgid "" -"Raises an :ref:`auditing event ` ``cpython.PyConfig_Set`` with " -"arguments ``name``, ``value``." -msgstr "" - -#: ../../c-api/init_config.rst:630 -msgid "PyConfig C API" -msgstr "PyConfig C API" - -#: ../../c-api/init_config.rst:634 -msgid "" -"Python can be initialized with :c:func:`Py_InitializeFromConfig` and the :c:" -"type:`PyConfig` structure. It can be preinitialized with :c:func:" -"`Py_PreInitialize` and the :c:type:`PyPreConfig` structure." -msgstr "" - -#: ../../c-api/init_config.rst:638 -msgid "There are two kinds of configuration:" -msgstr "" - -#: ../../c-api/init_config.rst:640 -msgid "" -"The :ref:`Python Configuration ` can be used to build a " -"customized Python which behaves as the regular Python. For example, " -"environment variables and command line arguments are used to configure " -"Python." -msgstr "" - -#: ../../c-api/init_config.rst:645 -msgid "" -"The :ref:`Isolated Configuration ` can be used to embed " -"Python into an application. It isolates Python from the system. For example, " -"environment variables are ignored, the LC_CTYPE locale is left unchanged and " -"no signal handler is registered." -msgstr "" - -#: ../../c-api/init_config.rst:656 -msgid ":pep:`587` \"Python Initialization Configuration\"." -msgstr "" - -#: ../../c-api/init_config.rst:662 -msgid "Example of customized Python always running in isolated mode::" -msgstr "" - -#: ../../c-api/init_config.rst:664 -msgid "" -"int main(int argc, char **argv)\n" -"{\n" -" PyStatus status;\n" -"\n" -" PyConfig config;\n" -" PyConfig_InitPythonConfig(&config);\n" -" config.isolated = 1;\n" -"\n" -" /* Decode command line arguments.\n" -" Implicitly preinitialize Python (in isolated mode). */\n" -" status = PyConfig_SetBytesArgv(&config, argc, argv);\n" -" if (PyStatus_Exception(status)) {\n" -" goto exception;\n" -" }\n" -"\n" -" status = Py_InitializeFromConfig(&config);\n" -" if (PyStatus_Exception(status)) {\n" -" goto exception;\n" -" }\n" -" PyConfig_Clear(&config);\n" -"\n" -" return Py_RunMain();\n" -"\n" -"exception:\n" -" PyConfig_Clear(&config);\n" -" if (PyStatus_IsExit(status)) {\n" -" return status.exitcode;\n" -" }\n" -" /* Display the error message and exit the process with\n" -" non-zero exit code */\n" -" Py_ExitStatusException(status);\n" -"}" -msgstr "" - -#: ../../c-api/init_config.rst:699 -msgid "PyWideStringList" -msgstr "PyWideStringList" - -#: ../../c-api/init_config.rst:703 -msgid "List of ``wchar_t*`` strings." -msgstr "``wchar_t*`` 字串串列。" - -#: ../../c-api/init_config.rst:705 -msgid "" -"If *length* is non-zero, *items* must be non-``NULL`` and all strings must " -"be non-``NULL``." -msgstr "" - -#: ../../c-api/init_config.rst:710 -msgid "Methods:" -msgstr "方法：" - -#: ../../c-api/init_config.rst:714 -msgid "Append *item* to *list*." -msgstr "" - -#: ../../c-api/init_config.rst:716 ../../c-api/init_config.rst:727 -msgid "Python must be preinitialized to call this function." -msgstr "" - -#: ../../c-api/init_config.rst:720 -msgid "Insert *item* into *list* at *index*." -msgstr "" - -#: ../../c-api/init_config.rst:722 -msgid "" -"If *index* is greater than or equal to *list* length, append *item* to " -"*list*." -msgstr "" - -#: ../../c-api/init_config.rst:725 -msgid "*index* must be greater than or equal to ``0``." -msgstr "" - -#: ../../c-api/init_config.rst:731 ../../c-api/init_config.rst:751 -#: ../../c-api/init_config.rst:858 ../../c-api/init_config.rst:1177 -msgid "Structure fields:" -msgstr "" - -#: ../../c-api/init_config.rst:735 -msgid "List length." -msgstr "串列長度。" - -#: ../../c-api/init_config.rst:739 -msgid "List items." -msgstr "" - -#: ../../c-api/init_config.rst:742 -msgid "PyStatus" -msgstr "PyStatus" - -#: ../../c-api/init_config.rst:746 -msgid "" -"Structure to store an initialization function status: success, error or exit." -msgstr "" - -#: ../../c-api/init_config.rst:749 -msgid "For an error, it can store the C function name which created the error." -msgstr "" - -#: ../../c-api/init_config.rst:755 -msgid "Exit code. Argument passed to ``exit()``." -msgstr "" - -#: ../../c-api/init_config.rst:759 -msgid "Error message." -msgstr "錯誤訊息。" - -#: ../../c-api/init_config.rst:763 -msgid "Name of the function which created an error, can be ``NULL``." -msgstr "" - -#: ../../c-api/init_config.rst:767 -msgid "Functions to create a status:" -msgstr "建立狀態的函式：" - -#: ../../c-api/init_config.rst:771 -msgid "Success." -msgstr "成功。" - -#: ../../c-api/init_config.rst:775 -msgid "Initialization error with a message." -msgstr "附帶訊息的初始化錯誤。" - -#: ../../c-api/init_config.rst:777 -msgid "*err_msg* must not be ``NULL``." -msgstr "*err_msg* 不可為 ``NULL``。" - -#: ../../c-api/init_config.rst:781 -msgid "Memory allocation failure (out of memory)." -msgstr "" - -#: ../../c-api/init_config.rst:785 -msgid "Exit Python with the specified exit code." -msgstr "以指定的退出代號退出 Python。" - -#: ../../c-api/init_config.rst:787 -msgid "Functions to handle a status:" -msgstr "處理狀態的函式：" - -#: ../../c-api/init_config.rst:791 -msgid "" -"Is the status an error or an exit? If true, the exception must be handled; " -"by calling :c:func:`Py_ExitStatusException` for example." -msgstr "" - -#: ../../c-api/init_config.rst:796 -msgid "Is the result an error?" -msgstr "" - -#: ../../c-api/init_config.rst:800 -msgid "Is the result an exit?" -msgstr "" - -#: ../../c-api/init_config.rst:804 -msgid "" -"Call ``exit(exitcode)`` if *status* is an exit. Print the error message and " -"exit with a non-zero exit code if *status* is an error. Must only be called " -"if ``PyStatus_Exception(status)`` is non-zero." -msgstr "" - -#: ../../c-api/init_config.rst:809 -msgid "" -"Internally, Python uses macros which set ``PyStatus.func``, whereas " -"functions to create a status set ``func`` to ``NULL``." -msgstr "" - -#: ../../c-api/init_config.rst:812 -msgid "Example::" -msgstr "範例： ::" - -#: ../../c-api/init_config.rst:814 -msgid "" -"PyStatus alloc(void **ptr, size_t size)\n" -"{\n" -" *ptr = PyMem_RawMalloc(size);\n" -" if (*ptr == NULL) {\n" -" return PyStatus_NoMemory();\n" -" }\n" -" return PyStatus_Ok();\n" -"}\n" -"\n" -"int main(int argc, char **argv)\n" -"{\n" -" void *ptr;\n" -" PyStatus status = alloc(&ptr, 16);\n" -" if (PyStatus_Exception(status)) {\n" -" Py_ExitStatusException(status);\n" -" }\n" -" PyMem_Free(ptr);\n" -" return 0;\n" -"}" -msgstr "" -"PyStatus alloc(void **ptr, size_t size)\n" -"{\n" -" *ptr = PyMem_RawMalloc(size);\n" -" if (*ptr == NULL) {\n" -" return PyStatus_NoMemory();\n" -" }\n" -" return PyStatus_Ok();\n" -"}\n" -"\n" -"int main(int argc, char **argv)\n" -"{\n" -" void *ptr;\n" -" PyStatus status = alloc(&ptr, 16);\n" -" if (PyStatus_Exception(status)) {\n" -" Py_ExitStatusException(status);\n" -" }\n" -" PyMem_Free(ptr);\n" -" return 0;\n" -"}" - -#: ../../c-api/init_config.rst:836 -msgid "PyPreConfig" -msgstr "PyPreConfig" - -#: ../../c-api/init_config.rst:840 -msgid "Structure used to preinitialize Python." -msgstr "" - -#: ../../c-api/init_config.rst:844 -msgid "Function to initialize a preconfiguration:" -msgstr "" - -#: ../../c-api/init_config.rst:848 -msgid "" -"Initialize the preconfiguration with :ref:`Python Configuration `." -msgstr "" - -#: ../../c-api/init_config.rst:853 -msgid "" -"Initialize the preconfiguration with :ref:`Isolated Configuration `." -msgstr "" - -#: ../../c-api/init_config.rst:862 -msgid "Name of the Python memory allocators:" -msgstr "" - -#: ../../c-api/init_config.rst:864 -msgid "" -"``PYMEM_ALLOCATOR_NOT_SET`` (``0``): don't change memory allocators (use " -"defaults)." -msgstr "" - -#: ../../c-api/init_config.rst:866 -msgid "" -"``PYMEM_ALLOCATOR_DEFAULT`` (``1``): :ref:`default memory allocators " -"`." -msgstr "" - -#: ../../c-api/init_config.rst:868 -msgid "" -"``PYMEM_ALLOCATOR_DEBUG`` (``2``): :ref:`default memory allocators ` with :ref:`debug hooks `." -msgstr "" - -#: ../../c-api/init_config.rst:871 -msgid "``PYMEM_ALLOCATOR_MALLOC`` (``3``): use ``malloc()`` of the C library." -msgstr "" - -#: ../../c-api/init_config.rst:872 -msgid "" -"``PYMEM_ALLOCATOR_MALLOC_DEBUG`` (``4``): force usage of ``malloc()`` with :" -"ref:`debug hooks `." -msgstr "" - -#: ../../c-api/init_config.rst:874 -msgid "" -"``PYMEM_ALLOCATOR_PYMALLOC`` (``5``): :ref:`Python pymalloc memory allocator " -"`." -msgstr "" - -#: ../../c-api/init_config.rst:876 -msgid "" -"``PYMEM_ALLOCATOR_PYMALLOC_DEBUG`` (``6``): :ref:`Python pymalloc memory " -"allocator ` with :ref:`debug hooks `." -msgstr "" - -#: ../../c-api/init_config.rst:879 -msgid "" -"``PYMEM_ALLOCATOR_MIMALLOC`` (``6``): use ``mimalloc``, a fast malloc " -"replacement." -msgstr "" - -#: ../../c-api/init_config.rst:881 -msgid "" -"``PYMEM_ALLOCATOR_MIMALLOC_DEBUG`` (``7``): use ``mimalloc``, a fast malloc " -"replacement with :ref:`debug hooks `." -msgstr "" - -#: ../../c-api/init_config.rst:885 -msgid "" -"``PYMEM_ALLOCATOR_PYMALLOC`` and ``PYMEM_ALLOCATOR_PYMALLOC_DEBUG`` are not " -"supported if Python is :option:`configured using --without-pymalloc <--" -"without-pymalloc>`." -msgstr "" - -#: ../../c-api/init_config.rst:889 -msgid "" -"``PYMEM_ALLOCATOR_MIMALLOC`` and ``PYMEM_ALLOCATOR_MIMALLOC_DEBUG`` are not " -"supported if Python is :option:`configured using --without-mimalloc <--" -"without-mimalloc>` or if the underlying atomic support isn't available." -msgstr "" - -#: ../../c-api/init_config.rst:894 -msgid "See :ref:`Memory Management `." -msgstr "請見\\ :ref:`記憶體管理 `。" - -#: ../../c-api/init_config.rst:896 -msgid "Default: ``PYMEM_ALLOCATOR_NOT_SET``." -msgstr "預設：``PYMEM_ALLOCATOR_NOT_SET``。" - -#: ../../c-api/init_config.rst:900 -msgid "Set the LC_CTYPE locale to the user preferred locale." -msgstr "" - -#: ../../c-api/init_config.rst:902 -msgid "" -"If equals to ``0``, set :c:member:`~PyPreConfig.coerce_c_locale` and :c:" -"member:`~PyPreConfig.coerce_c_locale_warn` members to ``0``." -msgstr "" - -#: ../../c-api/init_config.rst:905 ../../c-api/init_config.rst:916 -msgid "See the :term:`locale encoding`." -msgstr "請見 :term:`locale encoding`。" - -#: ../../c-api/init_config.rst:907 ../../c-api/init_config.rst:962 -#: ../../c-api/init_config.rst:1333 -msgid "Default: ``1`` in Python config, ``0`` in isolated config." -msgstr "" - -#: ../../c-api/init_config.rst:911 -msgid "If equals to ``2``, coerce the C locale." -msgstr "" - -#: ../../c-api/init_config.rst:913 -msgid "" -"If equals to ``1``, read the LC_CTYPE locale to decide if it should be " -"coerced." -msgstr "" - -#: ../../c-api/init_config.rst:918 ../../c-api/init_config.rst:924 -msgid "Default: ``-1`` in Python config, ``0`` in isolated config." -msgstr "" - -#: ../../c-api/init_config.rst:922 -msgid "If non-zero, emit a warning if the C locale is coerced." -msgstr "" - -#: ../../c-api/init_config.rst:928 -msgid "" -":ref:`Python Development Mode `: see :c:member:`PyConfig.dev_mode`." -msgstr "" - -#: ../../c-api/init_config.rst:931 ../../c-api/init_config.rst:1342 -#: ../../c-api/init_config.rst:1398 ../../c-api/init_config.rst:1892 -msgid "Default: ``-1`` in Python mode, ``0`` in isolated mode." -msgstr "" - -#: ../../c-api/init_config.rst:935 -msgid "Isolated mode: see :c:member:`PyConfig.isolated`." -msgstr "" - -#: ../../c-api/init_config.rst:937 ../../c-api/init_config.rst:1569 -msgid "Default: ``0`` in Python mode, ``1`` in isolated mode." -msgstr "" - -#: ../../c-api/init_config.rst:941 -msgid "If non-zero:" -msgstr "如果不為 0：" - -#: ../../c-api/init_config.rst:943 -msgid "Set :c:member:`PyPreConfig.utf8_mode` to ``0``," -msgstr "將 :c:member:`PyPreConfig.utf8_mode` 設為 ``0``、" - -#: ../../c-api/init_config.rst:944 -msgid "Set :c:member:`PyConfig.filesystem_encoding` to ``\"mbcs\"``," -msgstr "將 :c:member:`PyConfig.filesystem_encoding` 設為 ``\"mbcs\"``、" - -#: ../../c-api/init_config.rst:945 -msgid "Set :c:member:`PyConfig.filesystem_errors` to ``\"replace\"``." -msgstr "將 :c:member:`PyConfig.filesystem_errors` 設為 ``\"replace\"``。" - -#: ../../c-api/init_config.rst:947 -msgid "" -"Initialized from the :envvar:`PYTHONLEGACYWINDOWSFSENCODING` environment " -"variable value." -msgstr "" - -#: ../../c-api/init_config.rst:950 ../../c-api/init_config.rst:1583 -msgid "" -"Only available on Windows. ``#ifdef MS_WINDOWS`` macro can be used for " -"Windows specific code." -msgstr "" - -#: ../../c-api/init_config.rst:953 ../../c-api/init_config.rst:1281 -#: ../../c-api/init_config.rst:1288 ../../c-api/init_config.rst:1355 -#: ../../c-api/init_config.rst:1487 ../../c-api/init_config.rst:1505 -#: ../../c-api/init_config.rst:1519 ../../c-api/init_config.rst:1586 -#: ../../c-api/init_config.rst:1600 ../../c-api/init_config.rst:1660 -#: ../../c-api/init_config.rst:1712 ../../c-api/init_config.rst:1774 -#: ../../c-api/init_config.rst:1828 ../../c-api/init_config.rst:1857 -#: ../../c-api/init_config.rst:1971 ../../c-api/init_config.rst:2018 -msgid "Default: ``0``." -msgstr "預設：``0``。" - -#: ../../c-api/init_config.rst:957 -msgid "" -"If non-zero, :c:func:`Py_PreInitializeFromArgs` and :c:func:" -"`Py_PreInitializeFromBytesArgs` parse their ``argv`` argument the same way " -"the regular Python parses command line arguments: see :ref:`Command Line " -"Arguments `." -msgstr "" - -#: ../../c-api/init_config.rst:966 -msgid "" -"Use :ref:`environment variables `? See :c:member:`PyConfig." -"use_environment`." -msgstr "" - -#: ../../c-api/init_config.rst:969 ../../c-api/init_config.rst:1933 -msgid "Default: ``1`` in Python config and ``0`` in isolated config." -msgstr "" - -#: ../../c-api/init_config.rst:973 -msgid "If non-zero, enable the :ref:`Python UTF-8 Mode `." -msgstr "" - -#: ../../c-api/init_config.rst:975 -msgid "" -"Set to ``0`` or ``1`` by the :option:`-X utf8 <-X>` command line option and " -"the :envvar:`PYTHONUTF8` environment variable." -msgstr "" - -#: ../../c-api/init_config.rst:978 -msgid "Also set to ``1`` if the ``LC_CTYPE`` locale is ``C`` or ``POSIX``." -msgstr "" - -#: ../../c-api/init_config.rst:980 -msgid "Default: ``-1`` in Python config and ``0`` in isolated config." -msgstr "" - -#: ../../c-api/init_config.rst:986 -msgid "Preinitialize Python with PyPreConfig" -msgstr "" - -#: ../../c-api/init_config.rst:988 -msgid "The preinitialization of Python:" -msgstr "" - -#: ../../c-api/init_config.rst:990 -msgid "Set the Python memory allocators (:c:member:`PyPreConfig.allocator`)" -msgstr "" - -#: ../../c-api/init_config.rst:991 -msgid "Configure the LC_CTYPE locale (:term:`locale encoding`)" -msgstr "" - -#: ../../c-api/init_config.rst:992 -msgid "" -"Set the :ref:`Python UTF-8 Mode ` (:c:member:`PyPreConfig." -"utf8_mode`)" -msgstr "" - -#: ../../c-api/init_config.rst:995 -msgid "" -"The current preconfiguration (``PyPreConfig`` type) is stored in " -"``_PyRuntime.preconfig``." -msgstr "" - -#: ../../c-api/init_config.rst:998 -msgid "Functions to preinitialize Python:" -msgstr "" - -#: ../../c-api/init_config.rst:1002 ../../c-api/init_config.rst:1008 -#: ../../c-api/init_config.rst:1017 -msgid "Preinitialize Python from *preconfig* preconfiguration." -msgstr "" - -#: ../../c-api/init_config.rst:1004 ../../c-api/init_config.rst:1013 -#: ../../c-api/init_config.rst:1022 -msgid "*preconfig* must not be ``NULL``." -msgstr "*preconfig* 不可為 ``NULL``。" - -#: ../../c-api/init_config.rst:1010 -msgid "" -"Parse *argv* command line arguments (bytes strings) if :c:member:" -"`~PyPreConfig.parse_argv` of *preconfig* is non-zero." -msgstr "" - -#: ../../c-api/init_config.rst:1019 -msgid "" -"Parse *argv* command line arguments (wide strings) if :c:member:" -"`~PyPreConfig.parse_argv` of *preconfig* is non-zero." -msgstr "" - -#: ../../c-api/init_config.rst:1024 ../../c-api/init_config.rst:2041 -msgid "" -"The caller is responsible to handle exceptions (error or exit) using :c:func:" -"`PyStatus_Exception` and :c:func:`Py_ExitStatusException`." -msgstr "" - -#: ../../c-api/init_config.rst:1027 -msgid "" -"For :ref:`Python Configuration ` (:c:func:" -"`PyPreConfig_InitPythonConfig`), if Python is initialized with command line " -"arguments, the command line arguments must also be passed to preinitialize " -"Python, since they have an effect on the pre-configuration like encodings. " -"For example, the :option:`-X utf8 <-X>` command line option enables the :ref:" -"`Python UTF-8 Mode `." -msgstr "" - -#: ../../c-api/init_config.rst:1034 -msgid "" -"``PyMem_SetAllocator()`` can be called after :c:func:`Py_PreInitialize` and " -"before :c:func:`Py_InitializeFromConfig` to install a custom memory " -"allocator. It can be called before :c:func:`Py_PreInitialize` if :c:member:" -"`PyPreConfig.allocator` is set to ``PYMEM_ALLOCATOR_NOT_SET``." -msgstr "" - -#: ../../c-api/init_config.rst:1039 -msgid "" -"Python memory allocation functions like :c:func:`PyMem_RawMalloc` must not " -"be used before the Python preinitialization, whereas calling directly " -"``malloc()`` and ``free()`` is always safe. :c:func:`Py_DecodeLocale` must " -"not be called before the Python preinitialization." -msgstr "" - -#: ../../c-api/init_config.rst:1044 -msgid "" -"Example using the preinitialization to enable the :ref:`Python UTF-8 Mode " -"`::" -msgstr "" - -#: ../../c-api/init_config.rst:1047 -msgid "" -"PyStatus status;\n" -"PyPreConfig preconfig;\n" -"PyPreConfig_InitPythonConfig(&preconfig);\n" -"\n" -"preconfig.utf8_mode = 1;\n" -"\n" -"status = Py_PreInitialize(&preconfig);\n" -"if (PyStatus_Exception(status)) {\n" -" Py_ExitStatusException(status);\n" -"}\n" -"\n" -"/* at this point, Python speaks UTF-8 */\n" -"\n" -"Py_Initialize();\n" -"/* ... use Python API here ... */\n" -"Py_Finalize();" -msgstr "" - -#: ../../c-api/init_config.rst:1066 -msgid "PyConfig" -msgstr "PyConfig" - -#: ../../c-api/init_config.rst:1070 -msgid "Structure containing most parameters to configure Python." -msgstr "" - -#: ../../c-api/init_config.rst:1072 -msgid "" -"When done, the :c:func:`PyConfig_Clear` function must be used to release the " -"configuration memory." -msgstr "" - -#: ../../c-api/init_config.rst:1077 -msgid "Structure methods:" -msgstr "" - -#: ../../c-api/init_config.rst:1081 -msgid "" -"Initialize configuration with the :ref:`Python Configuration `." -msgstr "" - -#: ../../c-api/init_config.rst:1086 -msgid "" -"Initialize configuration with the :ref:`Isolated Configuration `." -msgstr "" - -#: ../../c-api/init_config.rst:1091 -msgid "Copy the wide character string *str* into ``*config_str``." -msgstr "" - -#: ../../c-api/init_config.rst:1093 ../../c-api/init_config.rst:1100 -#: ../../c-api/init_config.rst:1107 ../../c-api/init_config.rst:1115 -#: ../../c-api/init_config.rst:1121 ../../c-api/init_config.rst:1138 -msgid ":ref:`Preinitialize Python ` if needed." -msgstr "" - -#: ../../c-api/init_config.rst:1097 -msgid "" -"Decode *str* using :c:func:`Py_DecodeLocale` and set the result into " -"``*config_str``." -msgstr "" - -#: ../../c-api/init_config.rst:1104 -msgid "" -"Set command line arguments (:c:member:`~PyConfig.argv` member of *config*) " -"from the *argv* list of wide character strings." -msgstr "" - -#: ../../c-api/init_config.rst:1111 -msgid "" -"Set command line arguments (:c:member:`~PyConfig.argv` member of *config*) " -"from the *argv* list of bytes strings. Decode bytes using :c:func:" -"`Py_DecodeLocale`." -msgstr "" - -#: ../../c-api/init_config.rst:1119 -msgid "Set the list of wide strings *list* to *length* and *items*." -msgstr "" - -#: ../../c-api/init_config.rst:1125 -msgid "Read all Python configuration." -msgstr "讀取所有 Python 配置。" - -#: ../../c-api/init_config.rst:1127 -msgid "Fields which are already initialized are left unchanged." -msgstr "已經初始化的欄位將保持不變。" - -#: ../../c-api/init_config.rst:1129 -msgid "" -"Fields for :ref:`path configuration ` are no longer " -"calculated or modified when calling this function, as of Python 3.11." -msgstr "" - -#: ../../c-api/init_config.rst:1132 ../../c-api/init_config.rst:1689 -msgid "" -"The :c:func:`PyConfig_Read` function only parses :c:member:`PyConfig.argv` " -"arguments once: :c:member:`PyConfig.parse_argv` is set to ``2`` after " -"arguments are parsed. Since Python arguments are stripped from :c:member:" -"`PyConfig.argv`, parsing arguments twice would parse the application options " -"as Python options." -msgstr "" - -#: ../../c-api/init_config.rst:1140 -msgid "" -"The :c:member:`PyConfig.argv` arguments are now only parsed once, :c:member:" -"`PyConfig.parse_argv` is set to ``2`` after arguments are parsed, and " -"arguments are only parsed if :c:member:`PyConfig.parse_argv` equals ``1``." -msgstr "" - -#: ../../c-api/init_config.rst:1146 -msgid "" -":c:func:`PyConfig_Read` no longer calculates all paths, and so fields listed " -"under :ref:`Python Path Configuration ` may no longer be " -"updated until :c:func:`Py_InitializeFromConfig` is called." -msgstr "" - -#: ../../c-api/init_config.rst:1154 -msgid "Release configuration memory." -msgstr "" - -#: ../../c-api/init_config.rst:1156 -msgid "" -"Most ``PyConfig`` methods :ref:`preinitialize Python ` if needed. " -"In that case, the Python preinitialization configuration (:c:type:" -"`PyPreConfig`) in based on the :c:type:`PyConfig`. If configuration fields " -"which are in common with :c:type:`PyPreConfig` are tuned, they must be set " -"before calling a :c:type:`PyConfig` method:" -msgstr "" - -#: ../../c-api/init_config.rst:1162 -msgid ":c:member:`PyConfig.dev_mode`" -msgstr ":c:member:`PyConfig.dev_mode`" - -#: ../../c-api/init_config.rst:1163 -msgid ":c:member:`PyConfig.isolated`" -msgstr ":c:member:`PyConfig.isolated`" - -#: ../../c-api/init_config.rst:1164 -msgid ":c:member:`PyConfig.parse_argv`" -msgstr ":c:member:`PyConfig.parse_argv`" - -#: ../../c-api/init_config.rst:1165 -msgid ":c:member:`PyConfig.use_environment`" -msgstr ":c:member:`PyConfig.use_environment`" - -#: ../../c-api/init_config.rst:1167 -msgid "" -"Moreover, if :c:func:`PyConfig_SetArgv` or :c:func:`PyConfig_SetBytesArgv` " -"is used, this method must be called before other methods, since the " -"preinitialization configuration depends on command line arguments (if :c:" -"member:`~PyConfig.parse_argv` is non-zero)." -msgstr "" - -#: ../../c-api/init_config.rst:1172 -msgid "" -"The caller of these methods is responsible to handle exceptions (error or " -"exit) using ``PyStatus_Exception()`` and ``Py_ExitStatusException()``." -msgstr "" - -#: ../../c-api/init_config.rst:1185 -msgid "" -"Set :data:`sys.argv` command line arguments based on :c:member:`~PyConfig." -"argv`. These parameters are similar to those passed to the program's :c:" -"func:`main` function with the difference that the first entry should refer " -"to the script file to be executed rather than the executable hosting the " -"Python interpreter. If there isn't a script that will be run, the first " -"entry in :c:member:`~PyConfig.argv` can be an empty string." -msgstr "" - -#: ../../c-api/init_config.rst:1193 -msgid "" -"Set :c:member:`~PyConfig.parse_argv` to ``1`` to parse :c:member:`~PyConfig." -"argv` the same way the regular Python parses Python command line arguments " -"and then to strip Python arguments from :c:member:`~PyConfig.argv`." -msgstr "" - -#: ../../c-api/init_config.rst:1198 -msgid "" -"If :c:member:`~PyConfig.argv` is empty, an empty string is added to ensure " -"that :data:`sys.argv` always exists and is never empty." -msgstr "" - -#: ../../c-api/init_config.rst:1201 ../../c-api/init_config.rst:1228 -#: ../../c-api/init_config.rst:1242 ../../c-api/init_config.rst:1252 -#: ../../c-api/init_config.rst:1363 ../../c-api/init_config.rst:1372 -#: ../../c-api/init_config.rst:1383 ../../c-api/init_config.rst:1474 -#: ../../c-api/init_config.rst:1630 ../../c-api/init_config.rst:1731 -#: ../../c-api/init_config.rst:1750 ../../c-api/init_config.rst:1765 -#: ../../c-api/init_config.rst:1782 ../../c-api/init_config.rst:1795 -#: ../../c-api/init_config.rst:1803 ../../c-api/init_config.rst:1817 -#: ../../c-api/init_config.rst:1920 -msgid "Default: ``NULL``." -msgstr "預設值：``NULL``。" - -#: ../../c-api/init_config.rst:1203 -msgid "See also the :c:member:`~PyConfig.orig_argv` member." -msgstr "另請參閱 :c:member:`~PyConfig.orig_argv` 成員。" - -#: ../../c-api/init_config.rst:1207 -msgid "" -"If equals to zero, ``Py_RunMain()`` prepends a potentially unsafe path to :" -"data:`sys.path` at startup:" -msgstr "" - -#: ../../c-api/init_config.rst:1210 -msgid "" -"If :c:member:`argv[0] ` is equal to ``L\"-m\"`` (``python -m " -"module``), prepend the current working directory." -msgstr "" - -#: ../../c-api/init_config.rst:1212 -msgid "" -"If running a script (``python script.py``), prepend the script's directory. " -"If it's a symbolic link, resolve symbolic links." -msgstr "" - -#: ../../c-api/init_config.rst:1214 -msgid "" -"Otherwise (``python -c code`` and ``python``), prepend an empty string, " -"which means the current working directory." -msgstr "" - -#: ../../c-api/init_config.rst:1217 -msgid "" -"Set to ``1`` by the :option:`-P` command line option and the :envvar:" -"`PYTHONSAFEPATH` environment variable." -msgstr "" - -#: ../../c-api/init_config.rst:1220 -msgid "Default: ``0`` in Python config, ``1`` in isolated config." -msgstr "" - -#: ../../c-api/init_config.rst:1226 -msgid ":data:`sys.base_exec_prefix`." -msgstr ":data:`sys.base_exec_prefix`。" - -#: ../../c-api/init_config.rst:1230 ../../c-api/init_config.rst:1244 -#: ../../c-api/init_config.rst:1254 ../../c-api/init_config.rst:1374 -#: ../../c-api/init_config.rst:1385 ../../c-api/init_config.rst:1647 -#: ../../c-api/init_config.rst:1733 -msgid "Part of the :ref:`Python Path Configuration ` output." -msgstr "" - -#: ../../c-api/init_config.rst:1232 -msgid "See also :c:member:`PyConfig.exec_prefix`." -msgstr "也請見 :c:member:`PyConfig.exec_prefix`" - -#: ../../c-api/init_config.rst:1236 -msgid "Python base executable: :data:`sys._base_executable`." -msgstr "" - -#: ../../c-api/init_config.rst:1238 -msgid "Set by the :envvar:`__PYVENV_LAUNCHER__` environment variable." -msgstr "由 :envvar:`__PYVENV_LAUNCHER__` 環境變數設定。" - -#: ../../c-api/init_config.rst:1240 -msgid "Set from :c:member:`PyConfig.executable` if ``NULL``." -msgstr "如果為 ``NULL``，則從 :c:member:`PyConfig.executable` 設定。" - -#: ../../c-api/init_config.rst:1246 -msgid "See also :c:member:`PyConfig.executable`." -msgstr "也請見 :c:member:`PyConfig.executable`" - -#: ../../c-api/init_config.rst:1250 -msgid ":data:`sys.base_prefix`." -msgstr ":data:`sys.base_prefix`。" - -#: ../../c-api/init_config.rst:1256 -msgid "See also :c:member:`PyConfig.prefix`." -msgstr "也請見 :c:member:`PyConfig.prefix`" - -#: ../../c-api/init_config.rst:1260 -msgid "" -"If equals to ``0`` and :c:member:`~PyConfig.configure_c_stdio` is non-zero, " -"disable buffering on the C streams stdout and stderr." -msgstr "" - -#: ../../c-api/init_config.rst:1263 -msgid "" -"Set to ``0`` by the :option:`-u` command line option and the :envvar:" -"`PYTHONUNBUFFERED` environment variable." -msgstr "" - -#: ../../c-api/init_config.rst:1266 -msgid "stdin is always opened in buffered mode." -msgstr "" - -#: ../../c-api/init_config.rst:1268 ../../c-api/init_config.rst:1301 -#: ../../c-api/init_config.rst:1845 ../../c-api/init_config.rst:2003 -msgid "Default: ``1``." -msgstr "預設值：``1``。" - -#: ../../c-api/init_config.rst:1272 -msgid "" -"If equals to ``1``, issue a warning when comparing :class:`bytes` or :class:" -"`bytearray` with :class:`str`, or comparing :class:`bytes` with :class:`int`." -msgstr "" - -#: ../../c-api/init_config.rst:1276 -msgid "" -"If equal or greater to ``2``, raise a :exc:`BytesWarning` exception in these " -"cases." -msgstr "" - -#: ../../c-api/init_config.rst:1279 -msgid "Incremented by the :option:`-b` command line option." -msgstr "" - -#: ../../c-api/init_config.rst:1285 -msgid "" -"If non-zero, emit a :exc:`EncodingWarning` warning when :class:`io." -"TextIOWrapper` uses its default encoding. See :ref:`io-encoding-warning` for " -"details." -msgstr "" - -#: ../../c-api/init_config.rst:1294 -msgid "" -"If equals to ``0``, disables the inclusion of the end line and column " -"mappings in code objects. Also disables traceback printing carets to " -"specific error locations." -msgstr "" - -#: ../../c-api/init_config.rst:1298 -msgid "" -"Set to ``0`` by the :envvar:`PYTHONNODEBUGRANGES` environment variable and " -"by the :option:`-X no_debug_ranges <-X>` command line option." -msgstr "" - -#: ../../c-api/init_config.rst:1307 -msgid "" -"Control the validation behavior of hash-based ``.pyc`` files: value of the :" -"option:`--check-hash-based-pycs` command line option." -msgstr "" - -#: ../../c-api/init_config.rst:1310 -msgid "Valid values:" -msgstr "有效值：" - -#: ../../c-api/init_config.rst:1312 -msgid "" -"``L\"always\"``: Hash the source file for invalidation regardless of value " -"of the 'check_source' flag." -msgstr "" - -#: ../../c-api/init_config.rst:1314 -msgid "``L\"never\"``: Assume that hash-based pycs always are valid." -msgstr "" - -#: ../../c-api/init_config.rst:1315 -msgid "" -"``L\"default\"``: The 'check_source' flag in hash-based pycs determines " -"invalidation." -msgstr "" - -#: ../../c-api/init_config.rst:1318 -msgid "Default: ``L\"default\"``." -msgstr "預設：``L\"default\"``。" - -#: ../../c-api/init_config.rst:1320 -msgid "See also :pep:`552` \"Deterministic pycs\"." -msgstr "" - -#: ../../c-api/init_config.rst:1324 -msgid "If non-zero, configure C standard streams:" -msgstr "" - -#: ../../c-api/init_config.rst:1326 -msgid "" -"On Windows, set the binary mode (``O_BINARY``) on stdin, stdout and stderr." -msgstr "" - -#: ../../c-api/init_config.rst:1328 -msgid "" -"If :c:member:`~PyConfig.buffered_stdio` equals zero, disable buffering of " -"stdin, stdout and stderr streams." -msgstr "" - -#: ../../c-api/init_config.rst:1330 -msgid "" -"If :c:member:`~PyConfig.interactive` is non-zero, enable stream buffering on " -"stdin and stdout (only stdout on Windows)." -msgstr "" - -#: ../../c-api/init_config.rst:1337 -msgid "If non-zero, enable the :ref:`Python Development Mode `." -msgstr "" - -#: ../../c-api/init_config.rst:1339 -msgid "" -"Set to ``1`` by the :option:`-X dev <-X>` option and the :envvar:" -"`PYTHONDEVMODE` environment variable." -msgstr "" - -#: ../../c-api/init_config.rst:1346 -msgid "Dump Python references?" -msgstr "" - -#: ../../c-api/init_config.rst:1348 -msgid "If non-zero, dump all objects which are still alive at exit." -msgstr "" - -#: ../../c-api/init_config.rst:1350 -msgid "Set to ``1`` by the :envvar:`PYTHONDUMPREFS` environment variable." -msgstr "" - -#: ../../c-api/init_config.rst:1352 -msgid "" -"Needs a special build of Python with the ``Py_TRACE_REFS`` macro defined: " -"see the :option:`configure --with-trace-refs option <--with-trace-refs>`." -msgstr "" - -#: ../../c-api/init_config.rst:1359 -msgid "Filename where to dump Python references." -msgstr "" - -#: ../../c-api/init_config.rst:1361 -msgid "Set by the :envvar:`PYTHONDUMPREFSFILE` environment variable." -msgstr "由 :envvar:`PYTHONDUMPREFSFILE` 環境變數設定。" - -#: ../../c-api/init_config.rst:1369 -msgid "" -"The site-specific directory prefix where the platform-dependent Python files " -"are installed: :data:`sys.exec_prefix`." -msgstr "" - -#: ../../c-api/init_config.rst:1376 -msgid "See also :c:member:`PyConfig.base_exec_prefix`." -msgstr "也請見 :c:member:`PyConfig.base_exec_prefix`" - -#: ../../c-api/init_config.rst:1380 -msgid "" -"The absolute path of the executable binary for the Python interpreter: :data:" -"`sys.executable`." -msgstr "" - -#: ../../c-api/init_config.rst:1387 -msgid "See also :c:member:`PyConfig.base_executable`." -msgstr "也請見 :c:member:`PyConfig.base_executable`" - -#: ../../c-api/init_config.rst:1391 -msgid "Enable faulthandler?" -msgstr "啟用 faulthandler？" - -#: ../../c-api/init_config.rst:1393 -msgid "If non-zero, call :func:`faulthandler.enable` at startup." -msgstr "如果非零，則在啟動時呼叫 :func:`faulthandler.enable`。" - -#: ../../c-api/init_config.rst:1395 -msgid "" -"Set to ``1`` by :option:`-X faulthandler <-X>` and the :envvar:" -"`PYTHONFAULTHANDLER` environment variable." -msgstr "" - -#: ../../c-api/init_config.rst:1402 -msgid "" -":term:`Filesystem encoding `: :func:" -"`sys.getfilesystemencoding`." -msgstr "" - -#: ../../c-api/init_config.rst:1405 -msgid "On macOS, Android and VxWorks: use ``\"utf-8\"`` by default." -msgstr "" - -#: ../../c-api/init_config.rst:1407 -msgid "" -"On Windows: use ``\"utf-8\"`` by default, or ``\"mbcs\"`` if :c:member:" -"`~PyPreConfig.legacy_windows_fs_encoding` of :c:type:`PyPreConfig` is non-" -"zero." -msgstr "" - -#: ../../c-api/init_config.rst:1411 -msgid "Default encoding on other platforms:" -msgstr "其他平台的預設編碼：" - -#: ../../c-api/init_config.rst:1413 -msgid "``\"utf-8\"`` if :c:member:`PyPreConfig.utf8_mode` is non-zero." -msgstr "如果 :c:member:`PyPreConfig.utf8_mode` 非零，則為 ``\"utf-8\"``。" - -#: ../../c-api/init_config.rst:1414 -msgid "" -"``\"ascii\"`` if Python detects that ``nl_langinfo(CODESET)`` announces the " -"ASCII encoding, whereas the ``mbstowcs()`` function decodes from a different " -"encoding (usually Latin1)." -msgstr "" - -#: ../../c-api/init_config.rst:1417 -msgid "``\"utf-8\"`` if ``nl_langinfo(CODESET)`` returns an empty string." -msgstr "" - -#: ../../c-api/init_config.rst:1418 -msgid "" -"Otherwise, use the :term:`locale encoding`: ``nl_langinfo(CODESET)`` result." -msgstr "" - -#: ../../c-api/init_config.rst:1421 -msgid "" -"At Python startup, the encoding name is normalized to the Python codec name. " -"For example, ``\"ANSI_X3.4-1968\"`` is replaced with ``\"ascii\"``." -msgstr "" - -#: ../../c-api/init_config.rst:1424 -msgid "See also the :c:member:`~PyConfig.filesystem_errors` member." -msgstr "另請參閱 :c:member:`~PyConfig.filesystem_errors` 成員。" - -#: ../../c-api/init_config.rst:1428 -msgid "" -":term:`Filesystem error handler `: :" -"func:`sys.getfilesystemencodeerrors`." -msgstr "" - -#: ../../c-api/init_config.rst:1431 -msgid "" -"On Windows: use ``\"surrogatepass\"`` by default, or ``\"replace\"`` if :c:" -"member:`~PyPreConfig.legacy_windows_fs_encoding` of :c:type:`PyPreConfig` is " -"non-zero." -msgstr "" - -#: ../../c-api/init_config.rst:1435 -msgid "On other platforms: use ``\"surrogateescape\"`` by default." -msgstr "其他平台：預設使用 ``\"surrogateescape\"``。" - -#: ../../c-api/init_config.rst:1437 -msgid "Supported error handlers:" -msgstr "支援的錯誤處理器：" - -#: ../../c-api/init_config.rst:1439 -msgid "``\"strict\"``" -msgstr "``\"strict\"``" - -#: ../../c-api/init_config.rst:1440 -msgid "``\"surrogateescape\"``" -msgstr "``\"surrogateescape\"``" - -#: ../../c-api/init_config.rst:1441 -msgid "``\"surrogatepass\"`` (only supported with the UTF-8 encoding)" -msgstr "``\"surrogatepass\"``\\ （僅支援 UTF-8 編碼）" - -#: ../../c-api/init_config.rst:1443 -msgid "See also the :c:member:`~PyConfig.filesystem_encoding` member." -msgstr "另請參閱 :c:member:`~PyConfig.filesystem_encoding` 成員。" - -#: ../../c-api/init_config.rst:1447 -msgid "If non-zero, use frozen modules." -msgstr "如果非零，則使用凍結模組。" - -#: ../../c-api/init_config.rst:1449 -msgid "Set by the :envvar:`PYTHON_FROZEN_MODULES` environment variable." -msgstr "由 :envvar:`PYTHON_FROZEN_MODULES` 環境變數設定。" - -#: ../../c-api/init_config.rst:1451 -msgid "" -"Default: ``1`` in a release build, or ``0`` in a :ref:`debug build `." -msgstr "" - -#: ../../c-api/init_config.rst:1457 -msgid "Randomized hash function seed." -msgstr "" - -#: ../../c-api/init_config.rst:1459 -msgid "" -"If :c:member:`~PyConfig.use_hash_seed` is zero, a seed is chosen randomly at " -"Python startup, and :c:member:`~PyConfig.hash_seed` is ignored." -msgstr "" - -#: ../../c-api/init_config.rst:1462 -msgid "Set by the :envvar:`PYTHONHASHSEED` environment variable." -msgstr "由 :envvar:`PYTHONHASHSEED` 環境變數設定。" - -#: ../../c-api/init_config.rst:1464 -msgid "" -"Default *use_hash_seed* value: ``-1`` in Python mode, ``0`` in isolated mode." -msgstr "" - -#: ../../c-api/init_config.rst:1469 -msgid "" -"Set the default Python \"home\" directory, that is, the location of the " -"standard Python libraries (see :envvar:`PYTHONHOME`)." -msgstr "" - -#: ../../c-api/init_config.rst:1472 -msgid "Set by the :envvar:`PYTHONHOME` environment variable." -msgstr "由 :envvar:`PYTHONHOME` 環境變數設定。" - -#: ../../c-api/init_config.rst:1476 ../../c-api/init_config.rst:1612 -#: ../../c-api/init_config.rst:1632 ../../c-api/init_config.rst:1721 -#: ../../c-api/init_config.rst:1752 -msgid "Part of the :ref:`Python Path Configuration ` input." -msgstr "" - -#: ../../c-api/init_config.rst:1480 -msgid "" -"If ``1``, profile import time. If ``2``, include additional output that " -"indicates when an imported module has already been loaded." -msgstr "" - -#: ../../c-api/init_config.rst:1484 -msgid "" -"Set by the :option:`-X importtime <-X>` option and the :envvar:" -"`PYTHONPROFILEIMPORTTIME` environment variable." -msgstr "" -"由 :option:`-X importtime <-X>` 選項與 :envvar:`PYTHONPROFILEIMPORTTIME` 環境" -"變數設定。" - -#: ../../c-api/init_config.rst:1491 -msgid "Added support for ``import_time = 2``" -msgstr "新增對 ``import_time = 2`` 的支援" - -#: ../../c-api/init_config.rst:1495 -msgid "Enter interactive mode after executing a script or a command." -msgstr "在執行腳本或命令後進入互動模式。" - -#: ../../c-api/init_config.rst:1497 -msgid "" -"If greater than ``0``, enable inspect: when a script is passed as first " -"argument or the -c option is used, enter interactive mode after executing " -"the script or the command, even when :data:`sys.stdin` does not appear to be " -"a terminal." -msgstr "" - -#: ../../c-api/init_config.rst:1502 -msgid "" -"Incremented by the :option:`-i` command line option. Set to ``1`` if the :" -"envvar:`PYTHONINSPECT` environment variable is non-empty." -msgstr "" - -#: ../../c-api/init_config.rst:1509 -msgid "Install Python signal handlers?" -msgstr "" - -#: ../../c-api/init_config.rst:1511 ../../c-api/init_config.rst:1695 -#: ../../c-api/init_config.rst:1719 ../../c-api/init_config.rst:1955 -msgid "Default: ``1`` in Python mode, ``0`` in isolated mode." -msgstr "" - -#: ../../c-api/init_config.rst:1515 -msgid "If greater than ``0``, enable the interactive mode (REPL)." -msgstr "" - -#: ../../c-api/init_config.rst:1517 -msgid "Incremented by the :option:`-i` command line option." -msgstr "" - -#: ../../c-api/init_config.rst:1523 -msgid "" -"Configures the :ref:`integer string conversion length limitation " -"`. An initial value of ``-1`` means the value will be " -"taken from the command line or environment or otherwise default to 4300 (:" -"data:`sys.int_info.default_max_str_digits`). A value of ``0`` disables the " -"limitation. Values greater than zero but less than 640 (:data:`sys.int_info." -"str_digits_check_threshold`) are unsupported and will produce an error." -msgstr "" - -#: ../../c-api/init_config.rst:1531 -msgid "" -"Configured by the :option:`-X int_max_str_digits <-X>` command line flag or " -"the :envvar:`PYTHONINTMAXSTRDIGITS` environment variable." -msgstr "" - -#: ../../c-api/init_config.rst:1534 -msgid "" -"Default: ``-1`` in Python mode. 4300 (:data:`sys.int_info." -"default_max_str_digits`) in isolated mode." -msgstr "" - -#: ../../c-api/init_config.rst:1541 -msgid "" -"If the value of :c:member:`~PyConfig.cpu_count` is not ``-1`` then it will " -"override the return values of :func:`os.cpu_count`, :func:`os." -"process_cpu_count`, and :func:`multiprocessing.cpu_count`." -msgstr "" - -#: ../../c-api/init_config.rst:1545 -msgid "" -"Configured by the :samp:`-X cpu_count={n|default}` command line flag or the :" -"envvar:`PYTHON_CPU_COUNT` environment variable." -msgstr "" - -#: ../../c-api/init_config.rst:1548 ../../c-api/init_config.rst:1909 -msgid "Default: ``-1``." -msgstr "預設值：``1``。" - -#: ../../c-api/init_config.rst:1554 -msgid "If greater than ``0``, enable isolated mode:" -msgstr "" - -#: ../../c-api/init_config.rst:1556 -msgid "" -"Set :c:member:`~PyConfig.safe_path` to ``1``: don't prepend a potentially " -"unsafe path to :data:`sys.path` at Python startup, such as the current " -"directory, the script's directory or an empty string." -msgstr "" - -#: ../../c-api/init_config.rst:1560 -msgid "" -"Set :c:member:`~PyConfig.use_environment` to ``0``: ignore ``PYTHON`` " -"environment variables." -msgstr "" -"將 :c:member:`~PyConfig.use_environment` 設定為 ``0``：忽略 ``PYTHON`` 環境變" -"數。" - -#: ../../c-api/init_config.rst:1562 -msgid "" -"Set :c:member:`~PyConfig.user_site_directory` to ``0``: don't add the user " -"site directory to :data:`sys.path`." -msgstr "" - -#: ../../c-api/init_config.rst:1564 -msgid "" -"Python REPL doesn't import :mod:`readline` nor enable default readline " -"configuration on interactive prompts." -msgstr "" - -#: ../../c-api/init_config.rst:1567 -msgid "Set to ``1`` by the :option:`-I` command line option." -msgstr "" - -#: ../../c-api/init_config.rst:1571 -msgid "" -"See also the :ref:`Isolated Configuration ` and :c:" -"member:`PyPreConfig.isolated`." -msgstr "" - -#: ../../c-api/init_config.rst:1576 -msgid "" -"If non-zero, use :class:`io.FileIO` instead of :class:`!io." -"_WindowsConsoleIO` for :data:`sys.stdin`, :data:`sys.stdout` and :data:`sys." -"stderr`." -msgstr "" - -#: ../../c-api/init_config.rst:1580 -msgid "" -"Set to ``1`` if the :envvar:`PYTHONLEGACYWINDOWSSTDIO` environment variable " -"is set to a non-empty string." -msgstr "" - -#: ../../c-api/init_config.rst:1588 -msgid "See also the :pep:`528` (Change Windows console encoding to UTF-8)." -msgstr "" - -#: ../../c-api/init_config.rst:1592 -msgid "" -"If non-zero, dump statistics on :ref:`Python pymalloc memory allocator " -"` at exit." -msgstr "" - -#: ../../c-api/init_config.rst:1595 -msgid "Set to ``1`` by the :envvar:`PYTHONMALLOCSTATS` environment variable." -msgstr "" - -#: ../../c-api/init_config.rst:1597 -msgid "" -"The option is ignored if Python is :option:`configured using the --without-" -"pymalloc option <--without-pymalloc>`." -msgstr "" - -#: ../../c-api/init_config.rst:1604 -msgid "Platform library directory name: :data:`sys.platlibdir`." -msgstr "" - -#: ../../c-api/init_config.rst:1606 -msgid "Set by the :envvar:`PYTHONPLATLIBDIR` environment variable." -msgstr "" - -#: ../../c-api/init_config.rst:1608 -msgid "" -"Default: value of the ``PLATLIBDIR`` macro which is set by the :option:" -"`configure --with-platlibdir option <--with-platlibdir>` (default: " -"``\"lib\"``, or ``\"DLLs\"`` on Windows)." -msgstr "" - -#: ../../c-api/init_config.rst:1616 -msgid "" -"This macro is now used on Windows to locate the standard library extension " -"modules, typically under ``DLLs``. However, for compatibility, note that " -"this value is ignored for any non-standard layouts, including in-tree builds " -"and virtual environments." -msgstr "" - -#: ../../c-api/init_config.rst:1625 -msgid "" -"Module search paths (:data:`sys.path`) as a string separated by ``DELIM`` (:" -"data:`os.pathsep`)." -msgstr "" - -#: ../../c-api/init_config.rst:1628 -msgid "Set by the :envvar:`PYTHONPATH` environment variable." -msgstr "" - -#: ../../c-api/init_config.rst:1637 -msgid "Module search paths: :data:`sys.path`." -msgstr "" - -#: ../../c-api/init_config.rst:1639 -msgid "" -"If :c:member:`~PyConfig.module_search_paths_set` is equal to ``0``, :c:func:" -"`Py_InitializeFromConfig` will replace :c:member:`~PyConfig." -"module_search_paths` and sets :c:member:`~PyConfig.module_search_paths_set` " -"to ``1``." -msgstr "" - -#: ../../c-api/init_config.rst:1644 -msgid "" -"Default: empty list (``module_search_paths``) and ``0`` " -"(``module_search_paths_set``)." -msgstr "" - -#: ../../c-api/init_config.rst:1651 -msgid "Compilation optimization level:" -msgstr "" - -#: ../../c-api/init_config.rst:1653 -msgid "``0``: Peephole optimizer, set ``__debug__`` to ``True``." -msgstr "" - -#: ../../c-api/init_config.rst:1654 -msgid "``1``: Level 0, remove assertions, set ``__debug__`` to ``False``." -msgstr "" - -#: ../../c-api/init_config.rst:1655 -msgid "``2``: Level 1, strip docstrings." -msgstr "" - -#: ../../c-api/init_config.rst:1657 -msgid "" -"Incremented by the :option:`-O` command line option. Set to the :envvar:" -"`PYTHONOPTIMIZE` environment variable value." -msgstr "" - -#: ../../c-api/init_config.rst:1664 -msgid "" -"The list of the original command line arguments passed to the Python " -"executable: :data:`sys.orig_argv`." -msgstr "" - -#: ../../c-api/init_config.rst:1667 -msgid "" -"If :c:member:`~PyConfig.orig_argv` list is empty and :c:member:`~PyConfig." -"argv` is not a list only containing an empty string, :c:func:`PyConfig_Read` " -"copies :c:member:`~PyConfig.argv` into :c:member:`~PyConfig.orig_argv` " -"before modifying :c:member:`~PyConfig.argv` (if :c:member:`~PyConfig." -"parse_argv` is non-zero)." -msgstr "" - -#: ../../c-api/init_config.rst:1674 -msgid "" -"See also the :c:member:`~PyConfig.argv` member and the :c:func:" -"`Py_GetArgcArgv` function." -msgstr "" - -#: ../../c-api/init_config.rst:1677 ../../c-api/init_config.rst:1990 -#: ../../c-api/init_config.rst:2009 -msgid "Default: empty list." -msgstr "" - -#: ../../c-api/init_config.rst:1683 -msgid "Parse command line arguments?" -msgstr "" - -#: ../../c-api/init_config.rst:1685 -msgid "" -"If equals to ``1``, parse :c:member:`~PyConfig.argv` the same way the " -"regular Python parses :ref:`command line arguments `, and " -"strip Python arguments from :c:member:`~PyConfig.argv`." -msgstr "" - -#: ../../c-api/init_config.rst:1697 -msgid "" -"The :c:member:`PyConfig.argv` arguments are now only parsed if :c:member:" -"`PyConfig.parse_argv` equals to ``1``." -msgstr "" - -#: ../../c-api/init_config.rst:1703 -msgid "" -"Parser debug mode. If greater than ``0``, turn on parser debugging output " -"(for expert only, depending on compilation options)." -msgstr "" - -#: ../../c-api/init_config.rst:1706 -msgid "" -"Incremented by the :option:`-d` command line option. Set to the :envvar:" -"`PYTHONDEBUG` environment variable value." -msgstr "" - -#: ../../c-api/init_config.rst:1709 ../../c-api/init_config.rst:1814 -msgid "" -"Needs a :ref:`debug build of Python ` (the ``Py_DEBUG`` macro " -"must be defined)." -msgstr "" - -#: ../../c-api/init_config.rst:1716 -msgid "" -"If non-zero, calculation of path configuration is allowed to log warnings " -"into ``stderr``. If equals to ``0``, suppress these warnings." -msgstr "" - -#: ../../c-api/init_config.rst:1723 -msgid "Now also applies on Windows." -msgstr "現在也適用於 Windows。" - -#: ../../c-api/init_config.rst:1728 -msgid "" -"The site-specific directory prefix where the platform independent Python " -"files are installed: :data:`sys.prefix`." -msgstr "" - -#: ../../c-api/init_config.rst:1735 -msgid "See also :c:member:`PyConfig.base_prefix`." -msgstr "也請見 :c:member:`PyConfig.base_prefix`" - -#: ../../c-api/init_config.rst:1739 -msgid "" -"Program name used to initialize :c:member:`~PyConfig.executable` and in " -"early error messages during Python initialization." -msgstr "" - -#: ../../c-api/init_config.rst:1742 -msgid "On macOS, use :envvar:`PYTHONEXECUTABLE` environment variable if set." -msgstr "" - -#: ../../c-api/init_config.rst:1743 -msgid "" -"If the ``WITH_NEXT_FRAMEWORK`` macro is defined, use :envvar:" -"`__PYVENV_LAUNCHER__` environment variable if set." -msgstr "" - -#: ../../c-api/init_config.rst:1745 -msgid "" -"Use ``argv[0]`` of :c:member:`~PyConfig.argv` if available and non-empty." -msgstr "" - -#: ../../c-api/init_config.rst:1747 -msgid "" -"Otherwise, use ``L\"python\"`` on Windows, or ``L\"python3\"`` on other " -"platforms." -msgstr "" - -#: ../../c-api/init_config.rst:1756 -msgid "" -"Directory where cached ``.pyc`` files are written: :data:`sys." -"pycache_prefix`." -msgstr "" - -#: ../../c-api/init_config.rst:1759 -msgid "" -"Set by the :option:`-X pycache_prefix=PATH <-X>` command line option and " -"the :envvar:`PYTHONPYCACHEPREFIX` environment variable. The command-line " -"option takes precedence." -msgstr "" - -#: ../../c-api/init_config.rst:1763 -msgid "If ``NULL``, :data:`sys.pycache_prefix` is set to ``None``." -msgstr "" - -#: ../../c-api/init_config.rst:1769 -msgid "" -"Quiet mode. If greater than ``0``, don't display the copyright and version " -"at Python startup in interactive mode." -msgstr "" - -#: ../../c-api/init_config.rst:1772 -msgid "Incremented by the :option:`-q` command line option." -msgstr "" - -#: ../../c-api/init_config.rst:1778 -msgid "Value of the :option:`-c` command line option." -msgstr "" - -#: ../../c-api/init_config.rst:1780 ../../c-api/init_config.rst:1801 -msgid "Used by :c:func:`Py_RunMain`." -msgstr "被 :c:func:`Py_RunMain` 使用。" - -#: ../../c-api/init_config.rst:1786 -msgid "" -"Filename passed on the command line: trailing command line argument without :" -"option:`-c` or :option:`-m`. It is used by the :c:func:`Py_RunMain` function." -msgstr "" - -#: ../../c-api/init_config.rst:1790 -msgid "" -"For example, it is set to ``script.py`` by the ``python3 script.py arg`` " -"command line." -msgstr "" - -#: ../../c-api/init_config.rst:1793 -msgid "See also the :c:member:`PyConfig.skip_source_first_line` option." -msgstr "也請見 :c:member:`PyConfig.skip_source_first_line` 選項。" - -#: ../../c-api/init_config.rst:1799 -msgid "Value of the :option:`-m` command line option." -msgstr "" - -#: ../../c-api/init_config.rst:1807 -msgid "" -"``package.module`` path to module that should be imported before ``site.py`` " -"is run." -msgstr "" - -#: ../../c-api/init_config.rst:1810 -msgid "" -"Set by the :option:`-X presite=package.module <-X>` command-line option and " -"the :envvar:`PYTHON_PRESITE` environment variable. The command-line option " -"takes precedence." -msgstr "" - -#: ../../c-api/init_config.rst:1821 -msgid "" -"Show total reference count at exit (excluding :term:`immortal` objects)?" -msgstr "" - -#: ../../c-api/init_config.rst:1823 -msgid "Set to ``1`` by :option:`-X showrefcount <-X>` command line option." -msgstr "" - -#: ../../c-api/init_config.rst:1825 -msgid "" -"Needs a :ref:`debug build of Python ` (the ``Py_REF_DEBUG`` " -"macro must be defined)." -msgstr "" - -#: ../../c-api/init_config.rst:1832 -msgid "Import the :mod:`site` module at startup?" -msgstr "" - -#: ../../c-api/init_config.rst:1834 -msgid "" -"If equal to zero, disable the import of the module site and the site-" -"dependent manipulations of :data:`sys.path` that it entails." -msgstr "" - -#: ../../c-api/init_config.rst:1837 -msgid "" -"Also disable these manipulations if the :mod:`site` module is explicitly " -"imported later (call :func:`site.main` if you want them to be triggered)." -msgstr "" - -#: ../../c-api/init_config.rst:1840 -msgid "Set to ``0`` by the :option:`-S` command line option." -msgstr "" - -#: ../../c-api/init_config.rst:1842 -msgid "" -":data:`sys.flags.no_site ` is set to the inverted value of :c:" -"member:`~PyConfig.site_import`." -msgstr "" - -#: ../../c-api/init_config.rst:1849 -msgid "" -"If non-zero, skip the first line of the :c:member:`PyConfig.run_filename` " -"source." -msgstr "" - -#: ../../c-api/init_config.rst:1852 -msgid "" -"It allows the usage of non-Unix forms of ``#!cmd``. This is intended for a " -"DOS specific hack only." -msgstr "" - -#: ../../c-api/init_config.rst:1855 -msgid "Set to ``1`` by the :option:`-x` command line option." -msgstr "" - -#: ../../c-api/init_config.rst:1862 -msgid "" -"Encoding and encoding errors of :data:`sys.stdin`, :data:`sys.stdout` and :" -"data:`sys.stderr` (but :data:`sys.stderr` always uses " -"``\"backslashreplace\"`` error handler)." -msgstr "" - -#: ../../c-api/init_config.rst:1866 -msgid "" -"Use the :envvar:`PYTHONIOENCODING` environment variable if it is non-empty." -msgstr "" - -#: ../../c-api/init_config.rst:1869 -msgid "Default encoding:" -msgstr "預設編碼：" - -#: ../../c-api/init_config.rst:1871 -msgid "``\"UTF-8\"`` if :c:member:`PyPreConfig.utf8_mode` is non-zero." -msgstr "如果 :c:member:`PyPreConfig.utf8_mode` 非零，則為 ``\"UTF-8\"``。" - -#: ../../c-api/init_config.rst:1872 -msgid "Otherwise, use the :term:`locale encoding`." -msgstr "否則使用 :term:`locale encoding`。" - -#: ../../c-api/init_config.rst:1874 -msgid "Default error handler:" -msgstr "" - -#: ../../c-api/init_config.rst:1876 -msgid "On Windows: use ``\"surrogateescape\"``." -msgstr "在 Windows 上：使用 ``\"surrogateescape\"``。" - -#: ../../c-api/init_config.rst:1877 -msgid "" -"``\"surrogateescape\"`` if :c:member:`PyPreConfig.utf8_mode` is non-zero, or " -"if the LC_CTYPE locale is \"C\" or \"POSIX\"." -msgstr "" - -#: ../../c-api/init_config.rst:1879 -msgid "``\"strict\"`` otherwise." -msgstr "" - -#: ../../c-api/init_config.rst:1881 -msgid "See also :c:member:`PyConfig.legacy_windows_stdio`." -msgstr "也請見 :c:member:`PyConfig.legacy_windows_stdio`。" - -#: ../../c-api/init_config.rst:1885 -msgid "Enable tracemalloc?" -msgstr "" - -#: ../../c-api/init_config.rst:1887 -msgid "If non-zero, call :func:`tracemalloc.start` at startup." -msgstr "" - -#: ../../c-api/init_config.rst:1889 -msgid "" -"Set by :option:`-X tracemalloc=N <-X>` command line option and by the :" -"envvar:`PYTHONTRACEMALLOC` environment variable." -msgstr "" - -#: ../../c-api/init_config.rst:1896 -msgid "Enable the Linux ``perf`` profiler support?" -msgstr "要啟用 Linux ``perf`` 分析器支援嗎？" - -#: ../../c-api/init_config.rst:1898 -msgid "If equals to ``1``, enable support for the Linux ``perf`` profiler." -msgstr "如果等於 ``1``，則啟用對 Linux ``perf`` 分析器的支援。" - -#: ../../c-api/init_config.rst:1900 -msgid "" -"If equals to ``2``, enable support for the Linux ``perf`` profiler with " -"DWARF JIT support." -msgstr "" -"如果等於 ``2``，則啟用有 DWARF JIT 支援的 Linux ``perf`` 分析器的支援。" - -#: ../../c-api/init_config.rst:1903 -msgid "" -"Set to ``1`` by :option:`-X perf <-X>` command-line option and the :envvar:" -"`PYTHONPERFSUPPORT` environment variable." -msgstr "" - -#: ../../c-api/init_config.rst:1906 -msgid "" -"Set to ``2`` by the :option:`-X perf_jit <-X>` command-line option and the :" -"envvar:`PYTHON_PERF_JIT_SUPPORT` environment variable." -msgstr "" - -#: ../../c-api/init_config.rst:1912 -msgid "See :ref:`perf_profiling` for more information." -msgstr "更多資訊請參見 :ref:`perf_profiling`。" - -#: ../../c-api/init_config.rst:1918 -msgid "Directory of the Python standard library." -msgstr "" - -#: ../../c-api/init_config.rst:1926 -msgid "Use :ref:`environment variables `?" -msgstr "" - -#: ../../c-api/init_config.rst:1928 -msgid "" -"If equals to zero, ignore the :ref:`environment variables `." -msgstr "" - -#: ../../c-api/init_config.rst:1931 -msgid "Set to ``0`` by the :option:`-E` environment variable." -msgstr "" - -#: ../../c-api/init_config.rst:1937 -msgid "" -"If non-zero, ``stdout`` and ``stderr`` will be redirected to the system log." -msgstr "" - -#: ../../c-api/init_config.rst:1940 -msgid "Only available on macOS 10.12 and later, and on iOS." -msgstr "" - -#: ../../c-api/init_config.rst:1942 -msgid "" -"Default: ``0`` (don't use the system log) on macOS; ``1`` on iOS (use the " -"system log)." -msgstr "" - -#: ../../c-api/init_config.rst:1949 -msgid "If non-zero, add the user site directory to :data:`sys.path`." -msgstr "" - -#: ../../c-api/init_config.rst:1951 -msgid "Set to ``0`` by the :option:`-s` and :option:`-I` command line options." -msgstr "" - -#: ../../c-api/init_config.rst:1953 -msgid "Set to ``0`` by the :envvar:`PYTHONNOUSERSITE` environment variable." -msgstr "" - -#: ../../c-api/init_config.rst:1959 -msgid "" -"Verbose mode. If greater than ``0``, print a message each time a module is " -"imported, showing the place (filename or built-in module) from which it is " -"loaded." -msgstr "" - -#: ../../c-api/init_config.rst:1963 -msgid "" -"If greater than or equal to ``2``, print a message for each file that is " -"checked for when searching for a module. Also provides information on module " -"cleanup at exit." -msgstr "" - -#: ../../c-api/init_config.rst:1967 -msgid "Incremented by the :option:`-v` command line option." -msgstr "" - -#: ../../c-api/init_config.rst:1969 -msgid "Set by the :envvar:`PYTHONVERBOSE` environment variable value." -msgstr "" - -#: ../../c-api/init_config.rst:1975 -msgid "" -"Options of the :mod:`warnings` module to build warnings filters, lowest to " -"highest priority: :data:`sys.warnoptions`." -msgstr "" - -#: ../../c-api/init_config.rst:1978 -msgid "" -"The :mod:`warnings` module adds :data:`sys.warnoptions` in the reverse " -"order: the last :c:member:`PyConfig.warnoptions` item becomes the first item " -"of :data:`warnings.filters` which is checked first (highest priority)." -msgstr "" - -#: ../../c-api/init_config.rst:1983 -msgid "" -"The :option:`-W` command line options adds its value to :c:member:`~PyConfig." -"warnoptions`, it can be used multiple times." -msgstr "" - -#: ../../c-api/init_config.rst:1986 -msgid "" -"The :envvar:`PYTHONWARNINGS` environment variable can also be used to add " -"warning options. Multiple options can be specified, separated by commas (``," -"``)." -msgstr "" - -#: ../../c-api/init_config.rst:1994 -msgid "" -"If equal to ``0``, Python won't try to write ``.pyc`` files on the import of " -"source modules." -msgstr "" - -#: ../../c-api/init_config.rst:1997 -msgid "" -"Set to ``0`` by the :option:`-B` command line option and the :envvar:" -"`PYTHONDONTWRITEBYTECODE` environment variable." -msgstr "" - -#: ../../c-api/init_config.rst:2000 -msgid "" -":data:`sys.dont_write_bytecode` is initialized to the inverted value of :c:" -"member:`~PyConfig.write_bytecode`." -msgstr "" - -#: ../../c-api/init_config.rst:2007 -msgid "Values of the :option:`-X` command line options: :data:`sys._xoptions`." -msgstr "" - -#: ../../c-api/init_config.rst:2013 -msgid "If non-zero, write performance statistics at Python exit." -msgstr "" - -#: ../../c-api/init_config.rst:2015 -msgid "" -"Need a special build with the ``Py_STATS`` macro: see :option:`--enable-" -"pystats`." -msgstr "" - -#: ../../c-api/init_config.rst:2020 -msgid "" -"If :c:member:`~PyConfig.parse_argv` is non-zero, :c:member:`~PyConfig.argv` " -"arguments are parsed the same way the regular Python parses :ref:`command " -"line arguments `, and Python arguments are stripped from :" -"c:member:`~PyConfig.argv`." -msgstr "" - -#: ../../c-api/init_config.rst:2025 -msgid "" -"The :c:member:`~PyConfig.xoptions` options are parsed to set other options: " -"see the :option:`-X` command line option." -msgstr "" - -#: ../../c-api/init_config.rst:2030 -msgid "The ``show_alloc_count`` field has been removed." -msgstr "" - -#: ../../c-api/init_config.rst:2036 -msgid "Initialization with PyConfig" -msgstr "" - -#: ../../c-api/init_config.rst:2038 -msgid "" -"Initializing the interpreter from a populated configuration struct is " -"handled by calling :c:func:`Py_InitializeFromConfig`." -msgstr "" - -#: ../../c-api/init_config.rst:2044 -msgid "" -"If :c:func:`PyImport_FrozenModules`, :c:func:`PyImport_AppendInittab` or :c:" -"func:`PyImport_ExtendInittab` are used, they must be set or called after " -"Python preinitialization and before the Python initialization. If Python is " -"initialized multiple times, :c:func:`PyImport_AppendInittab` or :c:func:" -"`PyImport_ExtendInittab` must be called before each Python initialization." -msgstr "" - -#: ../../c-api/init_config.rst:2051 -msgid "" -"The current configuration (``PyConfig`` type) is stored in " -"``PyInterpreterState.config``." -msgstr "" - -#: ../../c-api/init_config.rst:2054 -msgid "Example setting the program name::" -msgstr "" - -#: ../../c-api/init_config.rst:2056 -msgid "" -"void init_python(void)\n" -"{\n" -" PyStatus status;\n" -"\n" -" PyConfig config;\n" -" PyConfig_InitPythonConfig(&config);\n" -"\n" -" /* Set the program name. Implicitly preinitialize Python. */\n" -" status = PyConfig_SetString(&config, &config.program_name,\n" -" L\"/path/to/my_program\");\n" -" if (PyStatus_Exception(status)) {\n" -" goto exception;\n" -" }\n" -"\n" -" status = Py_InitializeFromConfig(&config);\n" -" if (PyStatus_Exception(status)) {\n" -" goto exception;\n" -" }\n" -" PyConfig_Clear(&config);\n" -" return;\n" -"\n" -"exception:\n" -" PyConfig_Clear(&config);\n" -" Py_ExitStatusException(status);\n" -"}" -msgstr "" -"void init_python(void)\n" -"{\n" -" PyStatus status;\n" -"\n" -" PyConfig config;\n" -" PyConfig_InitPythonConfig(&config);\n" -"\n" -" /* Set the program name. Implicitly preinitialize Python. */\n" -" status = PyConfig_SetString(&config, &config.program_name,\n" -" L\"/path/to/my_program\");\n" -" if (PyStatus_Exception(status)) {\n" -" goto exception;\n" -" }\n" -"\n" -" status = Py_InitializeFromConfig(&config);\n" -" if (PyStatus_Exception(status)) {\n" -" goto exception;\n" -" }\n" -" PyConfig_Clear(&config);\n" -" return;\n" -"\n" -"exception:\n" -" PyConfig_Clear(&config);\n" -" Py_ExitStatusException(status);\n" -"}" - -#: ../../c-api/init_config.rst:2082 -msgid "" -"More complete example modifying the default configuration, read the " -"configuration, and then override some parameters. Note that since 3.11, many " -"parameters are not calculated until initialization, and so values cannot be " -"read from the configuration structure. Any values set before initialize is " -"called will be left unchanged by initialization::" -msgstr "" - -#: ../../c-api/init_config.rst:2089 -msgid "" -"PyStatus init_python(const char *program_name)\n" -"{\n" -" PyStatus status;\n" -"\n" -" PyConfig config;\n" -" PyConfig_InitPythonConfig(&config);\n" -"\n" -" /* Set the program name before reading the configuration\n" -" (decode byte string from the locale encoding).\n" -"\n" -" Implicitly preinitialize Python. */\n" -" status = PyConfig_SetBytesString(&config, &config.program_name,\n" -" program_name);\n" -" if (PyStatus_Exception(status)) {\n" -" goto done;\n" -" }\n" -"\n" -" /* Read all configuration at once */\n" -" status = PyConfig_Read(&config);\n" -" if (PyStatus_Exception(status)) {\n" -" goto done;\n" -" }\n" -"\n" -" /* Specify sys.path explicitly */\n" -" /* If you want to modify the default set of paths, finish\n" -" initialization first and then use PySys_GetObject(\"path\") */\n" -" config.module_search_paths_set = 1;\n" -" status = PyWideStringList_Append(&config.module_search_paths,\n" -" L\"/path/to/stdlib\");\n" -" if (PyStatus_Exception(status)) {\n" -" goto done;\n" -" }\n" -" status = PyWideStringList_Append(&config.module_search_paths,\n" -" L\"/path/to/more/modules\");\n" -" if (PyStatus_Exception(status)) {\n" -" goto done;\n" -" }\n" -"\n" -" /* Override executable computed by PyConfig_Read() */\n" -" status = PyConfig_SetString(&config, &config.executable,\n" -" L\"/path/to/my_executable\");\n" -" if (PyStatus_Exception(status)) {\n" -" goto done;\n" -" }\n" -"\n" -" status = Py_InitializeFromConfig(&config);\n" -"\n" -"done:\n" -" PyConfig_Clear(&config);\n" -" return status;\n" -"}" -msgstr "" - -#: ../../c-api/init_config.rst:2145 -msgid "Isolated Configuration" -msgstr "" - -#: ../../c-api/init_config.rst:2147 -msgid "" -":c:func:`PyPreConfig_InitIsolatedConfig` and :c:func:" -"`PyConfig_InitIsolatedConfig` functions create a configuration to isolate " -"Python from the system. For example, to embed Python into an application." -msgstr "" - -#: ../../c-api/init_config.rst:2152 -msgid "" -"This configuration ignores global configuration variables, environment " -"variables, command line arguments (:c:member:`PyConfig.argv` is not parsed) " -"and user site directory. The C standard streams (ex: ``stdout``) and the " -"LC_CTYPE locale are left unchanged. Signal handlers are not installed." -msgstr "" - -#: ../../c-api/init_config.rst:2157 -msgid "" -"Configuration files are still used with this configuration to determine " -"paths that are unspecified. Ensure :c:member:`PyConfig.home` is specified to " -"avoid computing the default path configuration." -msgstr "" - -#: ../../c-api/init_config.rst:2165 -msgid "Python Configuration" -msgstr "" - -#: ../../c-api/init_config.rst:2167 -msgid "" -":c:func:`PyPreConfig_InitPythonConfig` and :c:func:" -"`PyConfig_InitPythonConfig` functions create a configuration to build a " -"customized Python which behaves as the regular Python." -msgstr "" - -#: ../../c-api/init_config.rst:2171 -msgid "" -"Environments variables and command line arguments are used to configure " -"Python, whereas global configuration variables are ignored." -msgstr "" - -#: ../../c-api/init_config.rst:2174 -msgid "" -"This function enables C locale coercion (:pep:`538`) and :ref:`Python UTF-8 " -"Mode ` (:pep:`540`) depending on the LC_CTYPE locale, :envvar:" -"`PYTHONUTF8` and :envvar:`PYTHONCOERCECLOCALE` environment variables." -msgstr "" - -#: ../../c-api/init_config.rst:2183 -msgid "Python Path Configuration" -msgstr "Python 路徑配置" - -#: ../../c-api/init_config.rst:2185 -msgid ":c:type:`PyConfig` contains multiple fields for the path configuration:" -msgstr "" - -#: ../../c-api/init_config.rst:2187 -msgid "Path configuration inputs:" -msgstr "" - -#: ../../c-api/init_config.rst:2189 -msgid ":c:member:`PyConfig.home`" -msgstr ":c:member:`PyConfig.home`" - -#: ../../c-api/init_config.rst:2190 -msgid ":c:member:`PyConfig.platlibdir`" -msgstr ":c:member:`PyConfig.platlibdir`" - -#: ../../c-api/init_config.rst:2191 -msgid ":c:member:`PyConfig.pathconfig_warnings`" -msgstr ":c:member:`PyConfig.pathconfig_warnings`" - -#: ../../c-api/init_config.rst:2192 -msgid ":c:member:`PyConfig.program_name`" -msgstr ":c:member:`PyConfig.program_name`" - -#: ../../c-api/init_config.rst:2193 -msgid ":c:member:`PyConfig.pythonpath_env`" -msgstr ":c:member:`PyConfig.pythonpath_env`" - -#: ../../c-api/init_config.rst:2194 -msgid "current working directory: to get absolute paths" -msgstr "" - -#: ../../c-api/init_config.rst:2195 -msgid "" -"``PATH`` environment variable to get the program full path (from :c:member:" -"`PyConfig.program_name`)" -msgstr "" - -#: ../../c-api/init_config.rst:2197 -msgid "``__PYVENV_LAUNCHER__`` environment variable" -msgstr "``__PYVENV_LAUNCHER__`` 環境變數" - -#: ../../c-api/init_config.rst:2198 -msgid "" -"(Windows only) Application paths in the registry under " -"\"Software\\Python\\PythonCore\\X.Y\\PythonPath\" of HKEY_CURRENT_USER and " -"HKEY_LOCAL_MACHINE (where X.Y is the Python version)." -msgstr "" - -#: ../../c-api/init_config.rst:2202 -msgid "Path configuration output fields:" -msgstr "" - -#: ../../c-api/init_config.rst:2204 -msgid ":c:member:`PyConfig.base_exec_prefix`" -msgstr ":c:member:`PyConfig.base_exec_prefix`" - -#: ../../c-api/init_config.rst:2205 -msgid ":c:member:`PyConfig.base_executable`" -msgstr ":c:member:`PyConfig.base_executable`" - -#: ../../c-api/init_config.rst:2206 -msgid ":c:member:`PyConfig.base_prefix`" -msgstr ":c:member:`PyConfig.base_prefix`" - -#: ../../c-api/init_config.rst:2207 -msgid ":c:member:`PyConfig.exec_prefix`" -msgstr ":c:member:`PyConfig.exec_prefix`" - -#: ../../c-api/init_config.rst:2208 -msgid ":c:member:`PyConfig.executable`" -msgstr ":c:member:`PyConfig.executable`" - -#: ../../c-api/init_config.rst:2209 -msgid "" -":c:member:`PyConfig.module_search_paths_set`, :c:member:`PyConfig." -"module_search_paths`" -msgstr "" -":c:member:`PyConfig.module_search_paths_set`, :c:member:`PyConfig." -"module_search_paths`" - -#: ../../c-api/init_config.rst:2211 -msgid ":c:member:`PyConfig.prefix`" -msgstr ":c:member:`PyConfig.prefix`" - -#: ../../c-api/init_config.rst:2213 -msgid "" -"If at least one \"output field\" is not set, Python calculates the path " -"configuration to fill unset fields. If :c:member:`~PyConfig." -"module_search_paths_set` is equal to ``0``, :c:member:`~PyConfig." -"module_search_paths` is overridden and :c:member:`~PyConfig." -"module_search_paths_set` is set to ``1``." -msgstr "" - -#: ../../c-api/init_config.rst:2219 -msgid "" -"It is possible to completely ignore the function calculating the default " -"path configuration by setting explicitly all path configuration output " -"fields listed above. A string is considered as set even if it is non-empty. " -"``module_search_paths`` is considered as set if ``module_search_paths_set`` " -"is set to ``1``. In this case, ``module_search_paths`` will be used without " -"modification." -msgstr "" - -#: ../../c-api/init_config.rst:2226 -msgid "" -"Set :c:member:`~PyConfig.pathconfig_warnings` to ``0`` to suppress warnings " -"when calculating the path configuration (Unix only, Windows does not log any " -"warning)." -msgstr "" - -#: ../../c-api/init_config.rst:2229 -msgid "" -"If :c:member:`~PyConfig.base_prefix` or :c:member:`~PyConfig." -"base_exec_prefix` fields are not set, they inherit their value from :c:" -"member:`~PyConfig.prefix` and :c:member:`~PyConfig.exec_prefix` respectively." -msgstr "" - -#: ../../c-api/init_config.rst:2233 -msgid ":c:func:`Py_RunMain` and :c:func:`Py_Main` modify :data:`sys.path`:" -msgstr ":c:func:`Py_RunMain` 和 :c:func:`Py_Main` 會修改 :data:`sys.path`：" - -#: ../../c-api/init_config.rst:2235 -msgid "" -"If :c:member:`~PyConfig.run_filename` is set and is a directory which " -"contains a ``__main__.py`` script, prepend :c:member:`~PyConfig." -"run_filename` to :data:`sys.path`." -msgstr "" - -#: ../../c-api/init_config.rst:2238 -msgid "If :c:member:`~PyConfig.isolated` is zero:" -msgstr "如果 :c:member:`~PyConfig.isolated` 為零：" - -#: ../../c-api/init_config.rst:2240 -msgid "" -"If :c:member:`~PyConfig.run_module` is set, prepend the current directory " -"to :data:`sys.path`. Do nothing if the current directory cannot be read." -msgstr "" - -#: ../../c-api/init_config.rst:2242 -msgid "" -"If :c:member:`~PyConfig.run_filename` is set, prepend the directory of the " -"filename to :data:`sys.path`." -msgstr "" - -#: ../../c-api/init_config.rst:2244 -msgid "Otherwise, prepend an empty string to :data:`sys.path`." -msgstr "" - -#: ../../c-api/init_config.rst:2246 -msgid "" -"If :c:member:`~PyConfig.site_import` is non-zero, :data:`sys.path` can be " -"modified by the :mod:`site` module. If :c:member:`~PyConfig." -"user_site_directory` is non-zero and the user's site-package directory " -"exists, the :mod:`site` module appends the user's site-package directory to :" -"data:`sys.path`." -msgstr "" - -#: ../../c-api/init_config.rst:2252 -msgid "The following configuration files are used by the path configuration:" -msgstr "" - -#: ../../c-api/init_config.rst:2254 -msgid "``pyvenv.cfg``" -msgstr "``pyvenv.cfg``" - -#: ../../c-api/init_config.rst:2255 -msgid "``._pth`` file (ex: ``python._pth``)" -msgstr "" - -#: ../../c-api/init_config.rst:2256 -msgid "``pybuilddir.txt`` (Unix only)" -msgstr "``pybuilddir.txt``\\ （僅限 Unix）" - -#: ../../c-api/init_config.rst:2258 -msgid "If a ``._pth`` file is present:" -msgstr "" - -#: ../../c-api/init_config.rst:2260 -msgid "Set :c:member:`~PyConfig.isolated` to ``1``." -msgstr "將 :c:member:`~PyConfig.isolated` 設定為 ``1``。" - -#: ../../c-api/init_config.rst:2261 -msgid "Set :c:member:`~PyConfig.use_environment` to ``0``." -msgstr "將 :c:member:`~PyConfig.use_environment` 設定為 ``0``。" - -#: ../../c-api/init_config.rst:2262 -msgid "Set :c:member:`~PyConfig.site_import` to ``0``." -msgstr "將 :c:member:`~PyConfig.site_import` 設定為 ``0``。" - -#: ../../c-api/init_config.rst:2263 -msgid "Set :c:member:`~PyConfig.safe_path` to ``1``." -msgstr "將 :c:member:`~PyConfig.safe_path` 設定為 ``1``。" - -#: ../../c-api/init_config.rst:2265 -msgid "" -"If :c:member:`~PyConfig.home` is not set and a ``pyvenv.cfg`` file is " -"present in the same directory as :c:member:`~PyConfig.executable`, or its " -"parent, :c:member:`~PyConfig.prefix` and :c:member:`~PyConfig.exec_prefix` " -"are set that location. When this happens, :c:member:`~PyConfig.base_prefix` " -"and :c:member:`~PyConfig.base_exec_prefix` still keep their value, pointing " -"to the base installation. See :ref:`sys-path-init-virtual-environments` for " -"more information." -msgstr "" - -#: ../../c-api/init_config.rst:2273 -msgid "" -"The ``__PYVENV_LAUNCHER__`` environment variable is used to set :c:member:" -"`PyConfig.base_executable`." -msgstr "" - -#: ../../c-api/init_config.rst:2278 -msgid "" -":c:member:`~PyConfig.prefix`, and :c:member:`~PyConfig.exec_prefix`, are now " -"set to the ``pyvenv.cfg`` directory. This was previously done by :mod:" -"`site`, therefore affected by :option:`-S`." -msgstr "" - -#: ../../c-api/init_config.rst:2284 -msgid "Py_GetArgcArgv()" -msgstr "Py_GetArgcArgv()" - -#: ../../c-api/init_config.rst:2288 -msgid "Get the original command line arguments, before Python modified them." -msgstr "" - -#: ../../c-api/init_config.rst:2290 -msgid "See also :c:member:`PyConfig.orig_argv` member." -msgstr "也請參與 :c:member:`PyConfig.orig_argv` 成員。" - -#: ../../c-api/init_config.rst:2293 -msgid "Delaying main module execution" -msgstr "" - -#: ../../c-api/init_config.rst:2295 -msgid "" -"In some embedding use cases, it may be desirable to separate interpreter " -"initialization from the execution of the main module." -msgstr "" - -#: ../../c-api/init_config.rst:2298 -msgid "" -"This separation can be achieved by setting ``PyConfig.run_command`` to the " -"empty string during initialization (to prevent the interpreter from dropping " -"into the interactive prompt), and then subsequently executing the desired " -"main module code using ``__main__.__dict__`` as the global namespace." -msgstr "" - -#: ../../c-api/init_config.rst:1181 -msgid "main()" -msgstr "main()" - -#: ../../c-api/init_config.rst:1181 -msgid "argv (in module sys)" -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-05 00:16+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \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" + +#: ../../c-api/init_config.rst:7 +msgid "Python Initialization Configuration" +msgstr "Python 初始化設定" + +#: ../../c-api/init_config.rst:13 +msgid "PyInitConfig C API" +msgstr "PyInitConfig C API" + +#: ../../c-api/init_config.rst:17 +msgid "Python can be initialized with :c:func:`Py_InitializeFromInitConfig`." +msgstr "Python 可以使用 :c:func:`Py_InitializeFromInitConfig` 來初始化。" + +#: ../../c-api/init_config.rst:19 ../../c-api/init_config.rst:650 +msgid "" +"The :c:func:`Py_RunMain` function can be used to write a customized Python " +"program." +msgstr "" + +#: ../../c-api/init_config.rst:22 ../../c-api/init_config.rst:653 +msgid "" +"See also :ref:`Initialization, Finalization, and Threads `." +msgstr "" + +#: ../../c-api/init_config.rst:25 +msgid ":pep:`741` \"Python Configuration C API\"." +msgstr "" + +#: ../../c-api/init_config.rst:29 ../../c-api/init_config.rst:660 +msgid "Example" +msgstr "範例" + +#: ../../c-api/init_config.rst:31 +msgid "" +"Example of customized Python always running with the :ref:`Python " +"Development Mode ` enabled; return ``-1`` on error:" +msgstr "" + +#: ../../c-api/init_config.rst:34 +msgid "" +"int init_python(void)\n" +"{\n" +" PyInitConfig *config = PyInitConfig_Create();\n" +" if (config == NULL) {\n" +" printf(\"PYTHON INIT ERROR: memory allocation failed\\n\");\n" +" return -1;\n" +" }\n" +"\n" +" // Enable the Python Development Mode\n" +" if (PyInitConfig_SetInt(config, \"dev_mode\", 1) < 0) {\n" +" goto error;\n" +" }\n" +"\n" +" // Initialize Python with the configuration\n" +" if (Py_InitializeFromInitConfig(config) < 0) {\n" +" goto error;\n" +" }\n" +" PyInitConfig_Free(config);\n" +" return 0;\n" +"\n" +"error:\n" +" {\n" +" // Display the error message.\n" +" //\n" +" // This uncommon braces style is used, because you cannot make\n" +" // goto targets point to variable declarations.\n" +" const char *err_msg;\n" +" (void)PyInitConfig_GetError(config, &err_msg);\n" +" printf(\"PYTHON INIT ERROR: %s\\n\", err_msg);\n" +" PyInitConfig_Free(config);\n" +" return -1;\n" +" }\n" +"}" +msgstr "" + +#: ../../c-api/init_config.rst:71 +msgid "Create Config" +msgstr "建立設定" + +#: ../../c-api/init_config.rst:75 +msgid "Opaque structure to configure the Python initialization." +msgstr "" + +#: ../../c-api/init_config.rst:80 +msgid "" +"Create a new initialization configuration using :ref:`Isolated Configuration " +"` default values." +msgstr "" + +#: ../../c-api/init_config.rst:83 +msgid "It must be freed by :c:func:`PyInitConfig_Free`." +msgstr "必須由 :c:func:`PyInitConfig_Free` 來釋放。" + +#: ../../c-api/init_config.rst:85 +msgid "Return ``NULL`` on memory allocation failure." +msgstr "在記憶體配置失敗時回傳 ``NULL``。" + +#: ../../c-api/init_config.rst:90 +msgid "Free memory of the initialization configuration *config*." +msgstr "釋放初始化配置 *config* 的記憶體。" + +#: ../../c-api/init_config.rst:92 +msgid "If *config* is ``NULL``, no operation is performed." +msgstr "如果 *config* 是 ``NULL``，則不執行任何操作。" + +#: ../../c-api/init_config.rst:96 +msgid "Error Handling" +msgstr "錯誤處理" + +#: ../../c-api/init_config.rst:100 +msgid "Get the *config* error message." +msgstr "取得 *config* 錯誤訊息。" + +#: ../../c-api/init_config.rst:102 +msgid "Set *\\*err_msg* and return ``1`` if an error is set." +msgstr "如果設定了錯誤，則設置 *\\*err_msg* 並回傳 ``1``。" + +#: ../../c-api/init_config.rst:103 +msgid "Set *\\*err_msg* to ``NULL`` and return ``0`` otherwise." +msgstr "如果沒有設定錯誤，則設定 *\\*err_msg* 為 ``NULL`` 並回傳 ``0``。" + +#: ../../c-api/init_config.rst:105 +msgid "An error message is a UTF-8 encoded string." +msgstr "錯誤訊息是 UTF-8 編碼的字串。" + +#: ../../c-api/init_config.rst:107 +msgid "If *config* has an exit code, format the exit code as an error message." +msgstr "" + +#: ../../c-api/init_config.rst:110 +msgid "" +"The error message remains valid until another ``PyInitConfig`` function is " +"called with *config*. The caller doesn't have to free the error message." +msgstr "" + +#: ../../c-api/init_config.rst:117 +msgid "Get the *config* exit code." +msgstr "" + +#: ../../c-api/init_config.rst:119 +msgid "Set *\\*exitcode* and return ``1`` if *config* has an exit code set." +msgstr "" + +#: ../../c-api/init_config.rst:120 +msgid "Return ``0`` if *config* has no exit code set." +msgstr "" + +#: ../../c-api/init_config.rst:122 +msgid "" +"Only the ``Py_InitializeFromInitConfig()`` function can set an exit code if " +"the ``parse_argv`` option is non-zero." +msgstr "" + +#: ../../c-api/init_config.rst:125 +msgid "" +"An exit code can be set when parsing the command line failed (exit code " +"``2``) or when a command line option asks to display the command line help " +"(exit code ``0``)." +msgstr "" + +#: ../../c-api/init_config.rst:131 +msgid "Get Options" +msgstr "" + +#: ../../c-api/init_config.rst:133 ../../c-api/init_config.rst:187 +#: ../../c-api/init_config.rst:559 +msgid "" +"The configuration option *name* parameter must be a non-NULL null-terminated " +"UTF-8 encoded string. See :ref:`Configuration Options `." +msgstr "" + +#: ../../c-api/init_config.rst:138 +msgid "Test if the configuration has an option called *name*." +msgstr "測試配置是否有名為 *name* 的選項。" + +#: ../../c-api/init_config.rst:140 +msgid "Return ``1`` if the option exists, or return ``0`` otherwise." +msgstr "如果選項存在則回傳 ``1``，否則回傳 ``0``。" + +#: ../../c-api/init_config.rst:145 +msgid "Get an integer configuration option." +msgstr "" + +#: ../../c-api/init_config.rst:147 ../../c-api/init_config.rst:156 +msgid "Set *\\*value*, and return ``0`` on success." +msgstr "" + +#: ../../c-api/init_config.rst:148 ../../c-api/init_config.rst:157 +#: ../../c-api/init_config.rst:172 ../../c-api/init_config.rst:200 +#: ../../c-api/init_config.rst:209 ../../c-api/init_config.rst:218 +#: ../../c-api/init_config.rst:233 ../../c-api/init_config.rst:249 +msgid "Set an error in *config* and return ``-1`` on error." +msgstr "" + +#: ../../c-api/init_config.rst:153 +msgid "" +"Get a string configuration option as a null-terminated UTF-8 encoded string." +msgstr "" + +#: ../../c-api/init_config.rst:159 +msgid "" +"*\\*value* can be set to ``NULL`` if the option is an optional string and " +"the option is unset." +msgstr "" + +#: ../../c-api/init_config.rst:162 +msgid "" +"On success, the string must be released with ``free(value)`` if it's not " +"``NULL``." +msgstr "" + +#: ../../c-api/init_config.rst:168 +msgid "" +"Get a string list configuration option as an array of null-terminated UTF-8 " +"encoded strings." +msgstr "" + +#: ../../c-api/init_config.rst:171 +msgid "Set *\\*length* and *\\*value*, and return ``0`` on success." +msgstr "" + +#: ../../c-api/init_config.rst:174 +msgid "" +"On success, the string list must be released with " +"``PyInitConfig_FreeStrList(length, items)``." +msgstr "" + +#: ../../c-api/init_config.rst:180 +msgid "Free memory of a string list created by ``PyInitConfig_GetStrList()``." +msgstr "" + +#: ../../c-api/init_config.rst:185 +msgid "Set Options" +msgstr "" + +#: ../../c-api/init_config.rst:190 +msgid "" +"Some configuration options have side effects on other options. This logic is " +"only implemented when ``Py_InitializeFromInitConfig()`` is called, not by " +"the \"Set\" functions below. For example, setting ``dev_mode`` to ``1`` does " +"not set ``faulthandler`` to ``1``." +msgstr "" + +#: ../../c-api/init_config.rst:197 +msgid "Set an integer configuration option." +msgstr "" + +#: ../../c-api/init_config.rst:199 ../../c-api/init_config.rst:208 +#: ../../c-api/init_config.rst:217 ../../c-api/init_config.rst:232 +#: ../../c-api/init_config.rst:248 ../../c-api/init_config.rst:591 +msgid "Return ``0`` on success." +msgstr "成功時回傳 ``0``。" + +#: ../../c-api/init_config.rst:205 +msgid "" +"Set a string configuration option from a null-terminated UTF-8 encoded " +"string. The string is copied." +msgstr "" + +#: ../../c-api/init_config.rst:214 +msgid "" +"Set a string list configuration option from an array of null-terminated " +"UTF-8 encoded strings. The string list is copied." +msgstr "" + +#: ../../c-api/init_config.rst:222 +msgid "Module" +msgstr "模組" + +#: ../../c-api/init_config.rst:226 +msgid "Add a built-in extension module to the table of built-in modules." +msgstr "" + +#: ../../c-api/init_config.rst:228 +msgid "" +"The new module can be imported by the name *name*, and uses the function " +"*initfunc* as the initialization function called on the first attempted " +"import." +msgstr "" + +#: ../../c-api/init_config.rst:235 +msgid "" +"If Python is initialized multiple times, ``PyInitConfig_AddModule()`` must " +"be called at each Python initialization." +msgstr "" + +#: ../../c-api/init_config.rst:238 +msgid "Similar to the :c:func:`PyImport_AppendInittab` function." +msgstr "和 :c:func:`PyImport_AppendInittab` 函式類似。" + +#: ../../c-api/init_config.rst:242 +msgid "Initialize Python" +msgstr "初始化 Python" + +#: ../../c-api/init_config.rst:246 +msgid "Initialize Python from the initialization configuration." +msgstr "" + +#: ../../c-api/init_config.rst:250 +msgid "Set an exit code in *config* and return ``-1`` if Python wants to exit." +msgstr "" + +#: ../../c-api/init_config.rst:253 +msgid "See ``PyInitConfig_GetExitcode()`` for the exit code case." +msgstr "" + +#: ../../c-api/init_config.rst:259 +msgid "Configuration Options" +msgstr "" + +#: ../../c-api/init_config.rst:264 +msgid "Option" +msgstr "選項" + +#: ../../c-api/init_config.rst:265 +msgid "PyConfig/PyPreConfig member" +msgstr "PyConfig/PyPreConfig 成員" + +#: ../../c-api/init_config.rst:266 +msgid "Type" +msgstr "" + +#: ../../c-api/init_config.rst:267 +msgid "Visibility" +msgstr "" + +#: ../../c-api/init_config.rst:268 +msgid "``\"allocator\"``" +msgstr "``\"allocator\"``" + +#: ../../c-api/init_config.rst:269 +msgid ":c:member:`allocator `" +msgstr ":c:member:`allocator `" + +#: ../../c-api/init_config.rst:270 ../../c-api/init_config.rst:294 +#: ../../c-api/init_config.rst:322 ../../c-api/init_config.rst:358 +#: ../../c-api/init_config.rst:366 ../../c-api/init_config.rst:378 +#: ../../c-api/init_config.rst:406 ../../c-api/init_config.rst:494 +#: ../../c-api/init_config.rst:522 ../../c-api/init_config.rst:576 +msgid "``int``" +msgstr "``int``" + +#: ../../c-api/init_config.rst:271 ../../c-api/init_config.rst:291 +#: ../../c-api/init_config.rst:299 ../../c-api/init_config.rst:303 +#: ../../c-api/init_config.rst:307 ../../c-api/init_config.rst:311 +#: ../../c-api/init_config.rst:315 ../../c-api/init_config.rst:319 +#: ../../c-api/init_config.rst:327 ../../c-api/init_config.rst:331 +#: ../../c-api/init_config.rst:335 ../../c-api/init_config.rst:347 +#: ../../c-api/init_config.rst:351 ../../c-api/init_config.rst:355 +#: ../../c-api/init_config.rst:359 ../../c-api/init_config.rst:363 +#: ../../c-api/init_config.rst:367 ../../c-api/init_config.rst:375 +#: ../../c-api/init_config.rst:387 ../../c-api/init_config.rst:391 +#: ../../c-api/init_config.rst:395 ../../c-api/init_config.rst:399 +#: ../../c-api/init_config.rst:411 ../../c-api/init_config.rst:415 +#: ../../c-api/init_config.rst:423 ../../c-api/init_config.rst:427 +#: ../../c-api/init_config.rst:439 ../../c-api/init_config.rst:451 +#: ../../c-api/init_config.rst:455 ../../c-api/init_config.rst:459 +#: ../../c-api/init_config.rst:463 ../../c-api/init_config.rst:467 +#: ../../c-api/init_config.rst:471 ../../c-api/init_config.rst:475 +#: ../../c-api/init_config.rst:479 ../../c-api/init_config.rst:483 +#: ../../c-api/init_config.rst:487 ../../c-api/init_config.rst:495 +#: ../../c-api/init_config.rst:503 ../../c-api/init_config.rst:507 +#: ../../c-api/init_config.rst:511 ../../c-api/init_config.rst:515 +#: ../../c-api/init_config.rst:519 ../../c-api/init_config.rst:527 +#: ../../c-api/init_config.rst:543 +msgid "Read-only" +msgstr "唯讀" + +#: ../../c-api/init_config.rst:272 +msgid "``\"argv\"``" +msgstr "``\"argv\"``" + +#: ../../c-api/init_config.rst:273 +msgid ":c:member:`argv `" +msgstr ":c:member:`argv `" + +#: ../../c-api/init_config.rst:274 ../../c-api/init_config.rst:402 +#: ../../c-api/init_config.rst:410 ../../c-api/init_config.rst:530 +#: ../../c-api/init_config.rst:578 +msgid "``list[str]``" +msgstr "``list[str]``" + +#: ../../c-api/init_config.rst:275 ../../c-api/init_config.rst:279 +#: ../../c-api/init_config.rst:283 ../../c-api/init_config.rst:287 +#: ../../c-api/init_config.rst:295 ../../c-api/init_config.rst:323 +#: ../../c-api/init_config.rst:339 ../../c-api/init_config.rst:343 +#: ../../c-api/init_config.rst:371 ../../c-api/init_config.rst:379 +#: ../../c-api/init_config.rst:383 ../../c-api/init_config.rst:403 +#: ../../c-api/init_config.rst:407 ../../c-api/init_config.rst:419 +#: ../../c-api/init_config.rst:431 ../../c-api/init_config.rst:435 +#: ../../c-api/init_config.rst:443 ../../c-api/init_config.rst:447 +#: ../../c-api/init_config.rst:491 ../../c-api/init_config.rst:499 +#: ../../c-api/init_config.rst:523 ../../c-api/init_config.rst:531 +#: ../../c-api/init_config.rst:535 ../../c-api/init_config.rst:539 +msgid "Public" +msgstr "公開" + +#: ../../c-api/init_config.rst:276 +msgid "``\"base_exec_prefix\"``" +msgstr "``\"base_exec_prefix\"``" + +#: ../../c-api/init_config.rst:277 +msgid ":c:member:`base_exec_prefix `" +msgstr ":c:member:`base_exec_prefix `" + +#: ../../c-api/init_config.rst:278 ../../c-api/init_config.rst:282 +#: ../../c-api/init_config.rst:286 ../../c-api/init_config.rst:298 +#: ../../c-api/init_config.rst:334 ../../c-api/init_config.rst:338 +#: ../../c-api/init_config.rst:342 ../../c-api/init_config.rst:350 +#: ../../c-api/init_config.rst:354 ../../c-api/init_config.rst:362 +#: ../../c-api/init_config.rst:430 ../../c-api/init_config.rst:434 +#: ../../c-api/init_config.rst:438 ../../c-api/init_config.rst:442 +#: ../../c-api/init_config.rst:450 ../../c-api/init_config.rst:454 +#: ../../c-api/init_config.rst:458 ../../c-api/init_config.rst:462 +#: ../../c-api/init_config.rst:482 ../../c-api/init_config.rst:486 +#: ../../c-api/init_config.rst:490 ../../c-api/init_config.rst:577 +msgid "``str``" +msgstr "``str``" + +#: ../../c-api/init_config.rst:280 +msgid "``\"base_executable\"``" +msgstr "``\"base_executable\"``" + +#: ../../c-api/init_config.rst:281 +msgid ":c:member:`base_executable `" +msgstr ":c:member:`base_executable `" + +#: ../../c-api/init_config.rst:284 +msgid "``\"base_prefix\"``" +msgstr "``\"base_prefix\"``" + +#: ../../c-api/init_config.rst:285 +msgid ":c:member:`base_prefix `" +msgstr ":c:member:`base_prefix `" + +#: ../../c-api/init_config.rst:288 +msgid "``\"buffered_stdio\"``" +msgstr "``\"buffered_stdio\"``" + +#: ../../c-api/init_config.rst:289 +msgid ":c:member:`buffered_stdio `" +msgstr ":c:member:`buffered_stdio `" + +#: ../../c-api/init_config.rst:290 ../../c-api/init_config.rst:302 +#: ../../c-api/init_config.rst:306 ../../c-api/init_config.rst:310 +#: ../../c-api/init_config.rst:314 ../../c-api/init_config.rst:318 +#: ../../c-api/init_config.rst:326 ../../c-api/init_config.rst:330 +#: ../../c-api/init_config.rst:346 ../../c-api/init_config.rst:370 +#: ../../c-api/init_config.rst:374 ../../c-api/init_config.rst:382 +#: ../../c-api/init_config.rst:386 ../../c-api/init_config.rst:390 +#: ../../c-api/init_config.rst:394 ../../c-api/init_config.rst:398 +#: ../../c-api/init_config.rst:414 ../../c-api/init_config.rst:418 +#: ../../c-api/init_config.rst:422 ../../c-api/init_config.rst:426 +#: ../../c-api/init_config.rst:446 ../../c-api/init_config.rst:466 +#: ../../c-api/init_config.rst:470 ../../c-api/init_config.rst:474 +#: ../../c-api/init_config.rst:478 ../../c-api/init_config.rst:498 +#: ../../c-api/init_config.rst:502 ../../c-api/init_config.rst:506 +#: ../../c-api/init_config.rst:510 ../../c-api/init_config.rst:514 +#: ../../c-api/init_config.rst:518 ../../c-api/init_config.rst:526 +#: ../../c-api/init_config.rst:534 ../../c-api/init_config.rst:542 +#: ../../c-api/init_config.rst:575 +msgid "``bool``" +msgstr "``bool``" + +#: ../../c-api/init_config.rst:292 +msgid "``\"bytes_warning\"``" +msgstr "``\"bytes_warning\"``" + +#: ../../c-api/init_config.rst:293 +msgid ":c:member:`bytes_warning `" +msgstr ":c:member:`bytes_warning `" + +#: ../../c-api/init_config.rst:296 +msgid "``\"check_hash_pycs_mode\"``" +msgstr "``\"check_hash_pycs_mode\"``" + +#: ../../c-api/init_config.rst:297 +msgid ":c:member:`check_hash_pycs_mode `" +msgstr ":c:member:`check_hash_pycs_mode `" + +#: ../../c-api/init_config.rst:300 +msgid "``\"code_debug_ranges\"``" +msgstr "``\"code_debug_ranges\"``" + +#: ../../c-api/init_config.rst:301 +msgid ":c:member:`code_debug_ranges `" +msgstr ":c:member:`code_debug_ranges `" + +#: ../../c-api/init_config.rst:304 +msgid "``\"coerce_c_locale\"``" +msgstr "``\"coerce_c_locale\"``" + +#: ../../c-api/init_config.rst:305 +msgid ":c:member:`coerce_c_locale `" +msgstr ":c:member:`coerce_c_locale `" + +#: ../../c-api/init_config.rst:308 +msgid "``\"coerce_c_locale_warn\"``" +msgstr "``\"coerce_c_locale_warn\"``" + +#: ../../c-api/init_config.rst:309 +msgid ":c:member:`coerce_c_locale_warn `" +msgstr ":c:member:`coerce_c_locale_warn `" + +#: ../../c-api/init_config.rst:312 +msgid "``\"configure_c_stdio\"``" +msgstr "``\"configure_c_stdio\"``" + +#: ../../c-api/init_config.rst:313 +msgid ":c:member:`configure_c_stdio `" +msgstr ":c:member:`configure_c_stdio `" + +#: ../../c-api/init_config.rst:316 +msgid "``\"configure_locale\"``" +msgstr "``\"configure_locale\"``" + +#: ../../c-api/init_config.rst:317 +msgid ":c:member:`configure_locale `" +msgstr ":c:member:`configure_locale `" + +#: ../../c-api/init_config.rst:320 +msgid "``\"cpu_count\"``" +msgstr "``\"cpu_count\"``" + +#: ../../c-api/init_config.rst:321 +msgid ":c:member:`cpu_count `" +msgstr ":c:member:`cpu_count `" + +#: ../../c-api/init_config.rst:324 +msgid "``\"dev_mode\"``" +msgstr "``\"dev_mode\"``" + +#: ../../c-api/init_config.rst:325 +msgid ":c:member:`dev_mode `" +msgstr ":c:member:`dev_mode `" + +#: ../../c-api/init_config.rst:328 +msgid "``\"dump_refs\"``" +msgstr "``\"dump_refs\"``" + +#: ../../c-api/init_config.rst:329 +msgid ":c:member:`dump_refs `" +msgstr ":c:member:`dump_refs `" + +#: ../../c-api/init_config.rst:332 +msgid "``\"dump_refs_file\"``" +msgstr "``\"dump_refs_file\"``" + +#: ../../c-api/init_config.rst:333 +msgid ":c:member:`dump_refs_file `" +msgstr ":c:member:`dump_refs_file `" + +#: ../../c-api/init_config.rst:336 +msgid "``\"exec_prefix\"``" +msgstr "``\"exec_prefix\"``" + +#: ../../c-api/init_config.rst:337 +msgid ":c:member:`exec_prefix `" +msgstr ":c:member:`exec_prefix `" + +#: ../../c-api/init_config.rst:340 +msgid "``\"executable\"``" +msgstr "``\"executable\"``" + +#: ../../c-api/init_config.rst:341 +msgid ":c:member:`executable `" +msgstr ":c:member:`executable `" + +#: ../../c-api/init_config.rst:344 +msgid "``\"faulthandler\"``" +msgstr "``\"faulthandler\"``" + +#: ../../c-api/init_config.rst:345 +msgid ":c:member:`faulthandler `" +msgstr ":c:member:`faulthandler `" + +#: ../../c-api/init_config.rst:348 +msgid "``\"filesystem_encoding\"``" +msgstr "``\"filesystem_encoding\"``" + +#: ../../c-api/init_config.rst:349 +msgid ":c:member:`filesystem_encoding `" +msgstr ":c:member:`filesystem_encoding `" + +#: ../../c-api/init_config.rst:352 +msgid "``\"filesystem_errors\"``" +msgstr "``\"filesystem_errors\"``" + +#: ../../c-api/init_config.rst:353 +msgid ":c:member:`filesystem_errors `" +msgstr ":c:member:`filesystem_errors `" + +#: ../../c-api/init_config.rst:356 +msgid "``\"hash_seed\"``" +msgstr "``\"hash_seed\"``" + +#: ../../c-api/init_config.rst:357 +msgid ":c:member:`hash_seed `" +msgstr ":c:member:`hash_seed `" + +#: ../../c-api/init_config.rst:360 +msgid "``\"home\"``" +msgstr "``\"home\"``" + +#: ../../c-api/init_config.rst:361 +msgid ":c:member:`home `" +msgstr ":c:member:`home `" + +#: ../../c-api/init_config.rst:364 +msgid "``\"import_time\"``" +msgstr "``\"import_time\"``" + +#: ../../c-api/init_config.rst:365 +msgid ":c:member:`import_time `" +msgstr ":c:member:`import_time `" + +#: ../../c-api/init_config.rst:368 +msgid "``\"inspect\"``" +msgstr "``\"inspect\"``" + +#: ../../c-api/init_config.rst:369 +msgid ":c:member:`inspect `" +msgstr ":c:member:`inspect `" + +#: ../../c-api/init_config.rst:372 +msgid "``\"install_signal_handlers\"``" +msgstr "``\"install_signal_handlers\"``" + +#: ../../c-api/init_config.rst:373 +msgid ":c:member:`install_signal_handlers `" +msgstr ":c:member:`install_signal_handlers `" + +#: ../../c-api/init_config.rst:376 +msgid "``\"int_max_str_digits\"``" +msgstr "``\"int_max_str_digits\"``" + +#: ../../c-api/init_config.rst:377 +msgid ":c:member:`int_max_str_digits `" +msgstr ":c:member:`int_max_str_digits `" + +#: ../../c-api/init_config.rst:380 +msgid "``\"interactive\"``" +msgstr "``\"interactive\"``" + +#: ../../c-api/init_config.rst:381 +msgid ":c:member:`interactive `" +msgstr ":c:member:`interactive `" + +#: ../../c-api/init_config.rst:384 +msgid "``\"isolated\"``" +msgstr "``\"isolated\"``" + +#: ../../c-api/init_config.rst:385 +msgid ":c:member:`isolated `" +msgstr ":c:member:`isolated `" + +#: ../../c-api/init_config.rst:388 +msgid "``\"legacy_windows_fs_encoding\"``" +msgstr "``\"legacy_windows_fs_encoding\"``" + +#: ../../c-api/init_config.rst:389 +msgid "" +":c:member:`legacy_windows_fs_encoding `" +msgstr "" +":c:member:`legacy_windows_fs_encoding `" + +#: ../../c-api/init_config.rst:392 +msgid "``\"legacy_windows_stdio\"``" +msgstr "``\"legacy_windows_stdio\"``" + +#: ../../c-api/init_config.rst:393 +msgid ":c:member:`legacy_windows_stdio `" +msgstr ":c:member:`legacy_windows_stdio `" + +#: ../../c-api/init_config.rst:396 +msgid "``\"malloc_stats\"``" +msgstr "``\"malloc_stats\"``" + +#: ../../c-api/init_config.rst:397 +msgid ":c:member:`malloc_stats `" +msgstr ":c:member:`malloc_stats `" + +#: ../../c-api/init_config.rst:400 +msgid "``\"module_search_paths\"``" +msgstr "``\"module_search_paths\"``" + +#: ../../c-api/init_config.rst:401 +msgid ":c:member:`module_search_paths `" +msgstr ":c:member:`module_search_paths `" + +#: ../../c-api/init_config.rst:404 +msgid "``\"optimization_level\"``" +msgstr "``\"optimization_level\"``" + +#: ../../c-api/init_config.rst:405 +msgid ":c:member:`optimization_level `" +msgstr ":c:member:`optimization_level `" + +#: ../../c-api/init_config.rst:408 +msgid "``\"orig_argv\"``" +msgstr "``\"orig_argv\"``" + +#: ../../c-api/init_config.rst:409 +msgid ":c:member:`orig_argv `" +msgstr ":c:member:`orig_argv `" + +#: ../../c-api/init_config.rst:412 +msgid "``\"parse_argv\"``" +msgstr "``\"parse_argv\"``" + +#: ../../c-api/init_config.rst:413 +msgid ":c:member:`parse_argv `" +msgstr ":c:member:`parse_argv `" + +#: ../../c-api/init_config.rst:416 +msgid "``\"parser_debug\"``" +msgstr "``\"parser_debug\"``" + +#: ../../c-api/init_config.rst:417 +msgid ":c:member:`parser_debug `" +msgstr ":c:member:`parser_debug `" + +#: ../../c-api/init_config.rst:420 +msgid "``\"pathconfig_warnings\"``" +msgstr "``\"pathconfig_warnings\"``" + +#: ../../c-api/init_config.rst:421 +msgid ":c:member:`pathconfig_warnings `" +msgstr ":c:member:`pathconfig_warnings `" + +#: ../../c-api/init_config.rst:424 +msgid "``\"perf_profiling\"``" +msgstr "``\"perf_profiling\"``" + +#: ../../c-api/init_config.rst:425 +msgid ":c:member:`perf_profiling `" +msgstr ":c:member:`perf_profiling `" + +#: ../../c-api/init_config.rst:428 +msgid "``\"platlibdir\"``" +msgstr "``\"platlibdir\"``" + +#: ../../c-api/init_config.rst:429 +msgid ":c:member:`platlibdir `" +msgstr ":c:member:`platlibdir `" + +#: ../../c-api/init_config.rst:432 +msgid "``\"prefix\"``" +msgstr "``\"prefix\"``" + +#: ../../c-api/init_config.rst:433 +msgid ":c:member:`prefix `" +msgstr ":c:member:`prefix `" + +#: ../../c-api/init_config.rst:436 +msgid "``\"program_name\"``" +msgstr "``\"surrogateescape\"``" + +#: ../../c-api/init_config.rst:437 +msgid ":c:member:`program_name `" +msgstr ":c:member:`program_name `" + +#: ../../c-api/init_config.rst:440 +msgid "``\"pycache_prefix\"``" +msgstr "``\"pycache_prefix\"``" + +#: ../../c-api/init_config.rst:441 +msgid ":c:member:`pycache_prefix `" +msgstr ":c:member:`pycache_prefix `" + +#: ../../c-api/init_config.rst:444 +msgid "``\"quiet\"``" +msgstr "``\"quiet\"``" + +#: ../../c-api/init_config.rst:445 +msgid ":c:member:`quiet `" +msgstr ":c:member:`quiet `" + +#: ../../c-api/init_config.rst:448 +msgid "``\"run_command\"``" +msgstr "``\"run_command\"``" + +#: ../../c-api/init_config.rst:449 +msgid ":c:member:`run_command `" +msgstr ":c:member:`run_command `" + +#: ../../c-api/init_config.rst:452 +msgid "``\"run_filename\"``" +msgstr "``\"run_filename\"``" + +#: ../../c-api/init_config.rst:453 +msgid ":c:member:`run_filename `" +msgstr ":c:member:`run_filename `" + +#: ../../c-api/init_config.rst:456 +msgid "``\"run_module\"``" +msgstr "``\"run_module\"``" + +#: ../../c-api/init_config.rst:457 +msgid ":c:member:`run_module `" +msgstr ":c:member:`run_module `" + +#: ../../c-api/init_config.rst:460 +msgid "``\"run_presite\"``" +msgstr "``\"run_presite\"``" + +#: ../../c-api/init_config.rst:461 +msgid ":c:member:`run_presite `" +msgstr ":c:member:`run_presite `" + +#: ../../c-api/init_config.rst:464 +msgid "``\"safe_path\"``" +msgstr "``\"safe_path\"``" + +#: ../../c-api/init_config.rst:465 +msgid ":c:member:`safe_path `" +msgstr ":c:member:`safe_path `" + +#: ../../c-api/init_config.rst:468 +msgid "``\"show_ref_count\"``" +msgstr "``\"show_ref_count\"``" + +#: ../../c-api/init_config.rst:469 +msgid ":c:member:`show_ref_count `" +msgstr ":c:member:`show_ref_count `" + +#: ../../c-api/init_config.rst:472 +msgid "``\"site_import\"``" +msgstr "``\"site_import\"``" + +#: ../../c-api/init_config.rst:473 +msgid ":c:member:`site_import `" +msgstr ":c:member:`site_import `" + +#: ../../c-api/init_config.rst:476 +msgid "``\"skip_source_first_line\"``" +msgstr "``\"skip_source_first_line\"``" + +#: ../../c-api/init_config.rst:477 +msgid ":c:member:`skip_source_first_line `" +msgstr ":c:member:`skip_source_first_line `" + +#: ../../c-api/init_config.rst:480 +msgid "``\"stdio_encoding\"``" +msgstr "``\"stdio_encoding\"``" + +#: ../../c-api/init_config.rst:481 +msgid ":c:member:`stdio_encoding `" +msgstr ":c:member:`stdio_encoding `" + +#: ../../c-api/init_config.rst:484 +msgid "``\"stdio_errors\"``" +msgstr "``\"stdio_errors\"``" + +#: ../../c-api/init_config.rst:485 +msgid ":c:member:`stdio_errors `" +msgstr ":c:member:`stdio_errors `" + +#: ../../c-api/init_config.rst:488 +msgid "``\"stdlib_dir\"``" +msgstr "``\"stdlib_dir\"``" + +#: ../../c-api/init_config.rst:489 +msgid ":c:member:`stdlib_dir `" +msgstr ":c:member:`stdlib_dir `" + +#: ../../c-api/init_config.rst:492 +msgid "``\"tracemalloc\"``" +msgstr "``\"tracemalloc\"``" + +#: ../../c-api/init_config.rst:493 +msgid ":c:member:`tracemalloc `" +msgstr ":c:member:`tracemalloc `" + +#: ../../c-api/init_config.rst:496 +msgid "``\"use_environment\"``" +msgstr "``\"use_environment\"``" + +#: ../../c-api/init_config.rst:497 +msgid ":c:member:`use_environment `" +msgstr ":c:member:`use_environment `" + +#: ../../c-api/init_config.rst:500 +msgid "``\"use_frozen_modules\"``" +msgstr "``\"use_frozen_modules\"``" + +#: ../../c-api/init_config.rst:501 +msgid ":c:member:`use_frozen_modules `" +msgstr ":c:member:`use_frozen_modules `" + +#: ../../c-api/init_config.rst:504 +msgid "``\"use_hash_seed\"``" +msgstr "``\"use_hash_seed\"``" + +#: ../../c-api/init_config.rst:505 +msgid ":c:member:`use_hash_seed `" +msgstr ":c:member:`use_hash_seed `" + +#: ../../c-api/init_config.rst:508 +msgid "``\"use_system_logger\"``" +msgstr "``\"use_system_logger\"``" + +#: ../../c-api/init_config.rst:509 +msgid ":c:member:`use_system_logger `" +msgstr ":c:member:`use_system_logger `" + +#: ../../c-api/init_config.rst:512 +msgid "``\"user_site_directory\"``" +msgstr "``\"user_site_directory\"``" + +#: ../../c-api/init_config.rst:513 +msgid ":c:member:`user_site_directory `" +msgstr ":c:member:`user_site_directory `" + +#: ../../c-api/init_config.rst:516 +msgid "``\"utf8_mode\"``" +msgstr "``\"utf8_mode\"``" + +#: ../../c-api/init_config.rst:517 +msgid ":c:member:`utf8_mode `" +msgstr ":c:member:`utf8_mode `" + +#: ../../c-api/init_config.rst:520 +msgid "``\"verbose\"``" +msgstr "``\"verbose\"``" + +#: ../../c-api/init_config.rst:521 +msgid ":c:member:`verbose `" +msgstr ":c:member:`verbose `" + +#: ../../c-api/init_config.rst:524 +msgid "``\"warn_default_encoding\"``" +msgstr "``\"warn_default_encoding\"``" + +#: ../../c-api/init_config.rst:525 +msgid ":c:member:`warn_default_encoding `" +msgstr ":c:member:`warn_default_encoding `" + +#: ../../c-api/init_config.rst:528 +msgid "``\"warnoptions\"``" +msgstr "``\"warnoptions\"``" + +#: ../../c-api/init_config.rst:529 +msgid ":c:member:`warnoptions `" +msgstr ":c:member:`warnoptions `" + +#: ../../c-api/init_config.rst:532 +msgid "``\"write_bytecode\"``" +msgstr "``\"write_bytecode\"``" + +#: ../../c-api/init_config.rst:533 +msgid ":c:member:`write_bytecode `" +msgstr ":c:member:`write_bytecode `" + +#: ../../c-api/init_config.rst:536 +msgid "``\"xoptions\"``" +msgstr "``\"xoptions\"``" + +#: ../../c-api/init_config.rst:537 +msgid ":c:member:`xoptions `" +msgstr ":c:member:`xoptions `" + +#: ../../c-api/init_config.rst:538 ../../c-api/init_config.rst:579 +msgid "``dict[str, str]``" +msgstr "``dict[str, str]``" + +#: ../../c-api/init_config.rst:540 +msgid "``\"_pystats\"``" +msgstr "``\"_pystats\"``" + +#: ../../c-api/init_config.rst:541 +msgid ":c:member:`_pystats `" +msgstr ":c:member:`_pystats `" + +#: ../../c-api/init_config.rst:545 +msgid "Visibility:" +msgstr "" + +#: ../../c-api/init_config.rst:547 +msgid "" +"Public: Can by get by :c:func:`PyConfig_Get` and set by :c:func:" +"`PyConfig_Set`." +msgstr "" + +#: ../../c-api/init_config.rst:549 +msgid "" +"Read-only: Can by get by :c:func:`PyConfig_Get`, but cannot be set by :c:" +"func:`PyConfig_Set`." +msgstr "" + +#: ../../c-api/init_config.rst:554 +msgid "Runtime Python configuration API" +msgstr "" + +#: ../../c-api/init_config.rst:556 +msgid "" +"At runtime, it's possible to get and set configuration options using :c:func:" +"`PyConfig_Get` and :c:func:`PyConfig_Set` functions." +msgstr "" + +#: ../../c-api/init_config.rst:562 +msgid "" +"Some options are read from the :mod:`sys` attributes. For example, the " +"option ``\"argv\"`` is read from :data:`sys.argv`." +msgstr "" + +#: ../../c-api/init_config.rst:568 +msgid "" +"Get the current runtime value of a configuration option as a Python object." +msgstr "" + +#: ../../c-api/init_config.rst:570 ../../c-api/init_config.rst:601 +msgid "Return a new reference on success." +msgstr "" + +#: ../../c-api/init_config.rst:571 ../../c-api/init_config.rst:602 +msgid "Set an exception and return ``NULL`` on error." +msgstr "" + +#: ../../c-api/init_config.rst:573 +msgid "The object type depends on the configuration option. It can be:" +msgstr "" + +#: ../../c-api/init_config.rst:581 ../../c-api/init_config.rst:604 +#: ../../c-api/init_config.rst:619 +msgid "" +"The caller must have an :term:`attached thread state`. The function cannot " +"be called before Python initialization nor after Python finalization." +msgstr "" + +#: ../../c-api/init_config.rst:589 +msgid "Similar to :c:func:`PyConfig_Get`, but get the value as a C int." +msgstr "" + +#: ../../c-api/init_config.rst:592 +msgid "Set an exception and return ``-1`` on error." +msgstr "" + +#: ../../c-api/init_config.rst:599 +msgid "Get all configuration option names as a ``frozenset``." +msgstr "" + +#: ../../c-api/init_config.rst:612 +msgid "Set the current runtime value of a configuration option." +msgstr "" + +#: ../../c-api/init_config.rst:614 +msgid "Raise a :exc:`ValueError` if there is no option *name*." +msgstr "如果沒有選項 *name*，則引發 :exc:`ValueError`。" + +#: ../../c-api/init_config.rst:615 +msgid "Raise a :exc:`ValueError` if *value* is an invalid value." +msgstr "如果 *value* 是無效值，則引發 :exc:`ValueError`。" + +#: ../../c-api/init_config.rst:616 +msgid "Raise a :exc:`ValueError` if the option is read-only (cannot be set)." +msgstr "如果選項是唯讀的（無法設定），則引發 :exc:`ValueError`。" + +#: ../../c-api/init_config.rst:617 +msgid "Raise a :exc:`TypeError` if *value* has not the proper type." +msgstr "" + +#: ../../c-api/init_config.rst:622 +msgid "" +"Raises an :ref:`auditing event ` ``cpython.PyConfig_Set`` with " +"arguments ``name``, ``value``." +msgstr "" + +#: ../../c-api/init_config.rst:630 +msgid "PyConfig C API" +msgstr "PyConfig C API" + +#: ../../c-api/init_config.rst:634 +msgid "" +"Python can be initialized with :c:func:`Py_InitializeFromConfig` and the :c:" +"type:`PyConfig` structure. It can be preinitialized with :c:func:" +"`Py_PreInitialize` and the :c:type:`PyPreConfig` structure." +msgstr "" + +#: ../../c-api/init_config.rst:638 +msgid "There are two kinds of configuration:" +msgstr "" + +#: ../../c-api/init_config.rst:640 +msgid "" +"The :ref:`Python Configuration ` can be used to build a " +"customized Python which behaves as the regular Python. For example, " +"environment variables and command line arguments are used to configure " +"Python." +msgstr "" + +#: ../../c-api/init_config.rst:645 +msgid "" +"The :ref:`Isolated Configuration ` can be used to embed " +"Python into an application. It isolates Python from the system. For example, " +"environment variables are ignored, the LC_CTYPE locale is left unchanged and " +"no signal handler is registered." +msgstr "" + +#: ../../c-api/init_config.rst:656 +msgid ":pep:`587` \"Python Initialization Configuration\"." +msgstr "" + +#: ../../c-api/init_config.rst:662 +msgid "Example of customized Python always running in isolated mode::" +msgstr "" + +#: ../../c-api/init_config.rst:664 +msgid "" +"int main(int argc, char **argv)\n" +"{\n" +" PyStatus status;\n" +"\n" +" PyConfig config;\n" +" PyConfig_InitPythonConfig(&config);\n" +" config.isolated = 1;\n" +"\n" +" /* Decode command line arguments.\n" +" Implicitly preinitialize Python (in isolated mode). */\n" +" status = PyConfig_SetBytesArgv(&config, argc, argv);\n" +" if (PyStatus_Exception(status)) {\n" +" goto exception;\n" +" }\n" +"\n" +" status = Py_InitializeFromConfig(&config);\n" +" if (PyStatus_Exception(status)) {\n" +" goto exception;\n" +" }\n" +" PyConfig_Clear(&config);\n" +"\n" +" return Py_RunMain();\n" +"\n" +"exception:\n" +" PyConfig_Clear(&config);\n" +" if (PyStatus_IsExit(status)) {\n" +" return status.exitcode;\n" +" }\n" +" /* Display the error message and exit the process with\n" +" non-zero exit code */\n" +" Py_ExitStatusException(status);\n" +"}" +msgstr "" + +#: ../../c-api/init_config.rst:699 +msgid "PyWideStringList" +msgstr "PyWideStringList" + +#: ../../c-api/init_config.rst:703 +msgid "List of ``wchar_t*`` strings." +msgstr "``wchar_t*`` 字串串列。" + +#: ../../c-api/init_config.rst:705 +msgid "" +"If *length* is non-zero, *items* must be non-``NULL`` and all strings must " +"be non-``NULL``." +msgstr "" + +#: ../../c-api/init_config.rst:710 +msgid "Methods:" +msgstr "方法：" + +#: ../../c-api/init_config.rst:714 +msgid "Append *item* to *list*." +msgstr "" + +#: ../../c-api/init_config.rst:716 ../../c-api/init_config.rst:727 +msgid "Python must be preinitialized to call this function." +msgstr "" + +#: ../../c-api/init_config.rst:720 +msgid "Insert *item* into *list* at *index*." +msgstr "" + +#: ../../c-api/init_config.rst:722 +msgid "" +"If *index* is greater than or equal to *list* length, append *item* to " +"*list*." +msgstr "" + +#: ../../c-api/init_config.rst:725 +msgid "*index* must be greater than or equal to ``0``." +msgstr "" + +#: ../../c-api/init_config.rst:731 ../../c-api/init_config.rst:751 +#: ../../c-api/init_config.rst:858 ../../c-api/init_config.rst:1177 +msgid "Structure fields:" +msgstr "" + +#: ../../c-api/init_config.rst:735 +msgid "List length." +msgstr "串列長度。" + +#: ../../c-api/init_config.rst:739 +msgid "List items." +msgstr "" + +#: ../../c-api/init_config.rst:742 +msgid "PyStatus" +msgstr "PyStatus" + +#: ../../c-api/init_config.rst:746 +msgid "" +"Structure to store an initialization function status: success, error or exit." +msgstr "" + +#: ../../c-api/init_config.rst:749 +msgid "For an error, it can store the C function name which created the error." +msgstr "" + +#: ../../c-api/init_config.rst:755 +msgid "Exit code. Argument passed to ``exit()``." +msgstr "" + +#: ../../c-api/init_config.rst:759 +msgid "Error message." +msgstr "錯誤訊息。" + +#: ../../c-api/init_config.rst:763 +msgid "Name of the function which created an error, can be ``NULL``." +msgstr "" + +#: ../../c-api/init_config.rst:767 +msgid "Functions to create a status:" +msgstr "建立狀態的函式：" + +#: ../../c-api/init_config.rst:771 +msgid "Success." +msgstr "成功。" + +#: ../../c-api/init_config.rst:775 +msgid "Initialization error with a message." +msgstr "附帶訊息的初始化錯誤。" + +#: ../../c-api/init_config.rst:777 +msgid "*err_msg* must not be ``NULL``." +msgstr "*err_msg* 不可為 ``NULL``。" + +#: ../../c-api/init_config.rst:781 +msgid "Memory allocation failure (out of memory)." +msgstr "" + +#: ../../c-api/init_config.rst:785 +msgid "Exit Python with the specified exit code." +msgstr "以指定的退出代號退出 Python。" + +#: ../../c-api/init_config.rst:787 +msgid "Functions to handle a status:" +msgstr "處理狀態的函式：" + +#: ../../c-api/init_config.rst:791 +msgid "" +"Is the status an error or an exit? If true, the exception must be handled; " +"by calling :c:func:`Py_ExitStatusException` for example." +msgstr "" + +#: ../../c-api/init_config.rst:796 +msgid "Is the result an error?" +msgstr "" + +#: ../../c-api/init_config.rst:800 +msgid "Is the result an exit?" +msgstr "" + +#: ../../c-api/init_config.rst:804 +msgid "" +"Call ``exit(exitcode)`` if *status* is an exit. Print the error message and " +"exit with a non-zero exit code if *status* is an error. Must only be called " +"if ``PyStatus_Exception(status)`` is non-zero." +msgstr "" + +#: ../../c-api/init_config.rst:809 +msgid "" +"Internally, Python uses macros which set ``PyStatus.func``, whereas " +"functions to create a status set ``func`` to ``NULL``." +msgstr "" + +#: ../../c-api/init_config.rst:812 +msgid "Example::" +msgstr "範例： ::" + +#: ../../c-api/init_config.rst:814 +msgid "" +"PyStatus alloc(void **ptr, size_t size)\n" +"{\n" +" *ptr = PyMem_RawMalloc(size);\n" +" if (*ptr == NULL) {\n" +" return PyStatus_NoMemory();\n" +" }\n" +" return PyStatus_Ok();\n" +"}\n" +"\n" +"int main(int argc, char **argv)\n" +"{\n" +" void *ptr;\n" +" PyStatus status = alloc(&ptr, 16);\n" +" if (PyStatus_Exception(status)) {\n" +" Py_ExitStatusException(status);\n" +" }\n" +" PyMem_Free(ptr);\n" +" return 0;\n" +"}" +msgstr "" +"PyStatus alloc(void **ptr, size_t size)\n" +"{\n" +" *ptr = PyMem_RawMalloc(size);\n" +" if (*ptr == NULL) {\n" +" return PyStatus_NoMemory();\n" +" }\n" +" return PyStatus_Ok();\n" +"}\n" +"\n" +"int main(int argc, char **argv)\n" +"{\n" +" void *ptr;\n" +" PyStatus status = alloc(&ptr, 16);\n" +" if (PyStatus_Exception(status)) {\n" +" Py_ExitStatusException(status);\n" +" }\n" +" PyMem_Free(ptr);\n" +" return 0;\n" +"}" + +#: ../../c-api/init_config.rst:836 +msgid "PyPreConfig" +msgstr "PyPreConfig" + +#: ../../c-api/init_config.rst:840 +msgid "Structure used to preinitialize Python." +msgstr "" + +#: ../../c-api/init_config.rst:844 +msgid "Function to initialize a preconfiguration:" +msgstr "" + +#: ../../c-api/init_config.rst:848 +msgid "" +"Initialize the preconfiguration with :ref:`Python Configuration `." +msgstr "" + +#: ../../c-api/init_config.rst:853 +msgid "" +"Initialize the preconfiguration with :ref:`Isolated Configuration `." +msgstr "" + +#: ../../c-api/init_config.rst:862 +msgid "Name of the Python memory allocators:" +msgstr "" + +#: ../../c-api/init_config.rst:864 +msgid "" +"``PYMEM_ALLOCATOR_NOT_SET`` (``0``): don't change memory allocators (use " +"defaults)." +msgstr "" + +#: ../../c-api/init_config.rst:866 +msgid "" +"``PYMEM_ALLOCATOR_DEFAULT`` (``1``): :ref:`default memory allocators " +"`." +msgstr "" + +#: ../../c-api/init_config.rst:868 +msgid "" +"``PYMEM_ALLOCATOR_DEBUG`` (``2``): :ref:`default memory allocators ` with :ref:`debug hooks `." +msgstr "" + +#: ../../c-api/init_config.rst:871 +msgid "``PYMEM_ALLOCATOR_MALLOC`` (``3``): use ``malloc()`` of the C library." +msgstr "" + +#: ../../c-api/init_config.rst:872 +msgid "" +"``PYMEM_ALLOCATOR_MALLOC_DEBUG`` (``4``): force usage of ``malloc()`` with :" +"ref:`debug hooks `." +msgstr "" + +#: ../../c-api/init_config.rst:874 +msgid "" +"``PYMEM_ALLOCATOR_PYMALLOC`` (``5``): :ref:`Python pymalloc memory allocator " +"`." +msgstr "" + +#: ../../c-api/init_config.rst:876 +msgid "" +"``PYMEM_ALLOCATOR_PYMALLOC_DEBUG`` (``6``): :ref:`Python pymalloc memory " +"allocator ` with :ref:`debug hooks `." +msgstr "" + +#: ../../c-api/init_config.rst:879 +msgid "" +"``PYMEM_ALLOCATOR_MIMALLOC`` (``6``): use ``mimalloc``, a fast malloc " +"replacement." +msgstr "" + +#: ../../c-api/init_config.rst:881 +msgid "" +"``PYMEM_ALLOCATOR_MIMALLOC_DEBUG`` (``7``): use ``mimalloc``, a fast malloc " +"replacement with :ref:`debug hooks `." +msgstr "" + +#: ../../c-api/init_config.rst:885 +msgid "" +"``PYMEM_ALLOCATOR_PYMALLOC`` and ``PYMEM_ALLOCATOR_PYMALLOC_DEBUG`` are not " +"supported if Python is :option:`configured using --without-pymalloc <--" +"without-pymalloc>`." +msgstr "" + +#: ../../c-api/init_config.rst:889 +msgid "" +"``PYMEM_ALLOCATOR_MIMALLOC`` and ``PYMEM_ALLOCATOR_MIMALLOC_DEBUG`` are not " +"supported if Python is :option:`configured using --without-mimalloc <--" +"without-mimalloc>` or if the underlying atomic support isn't available." +msgstr "" + +#: ../../c-api/init_config.rst:894 +msgid "See :ref:`Memory Management `." +msgstr "請見\\ :ref:`記憶體管理 `。" + +#: ../../c-api/init_config.rst:896 +msgid "Default: ``PYMEM_ALLOCATOR_NOT_SET``." +msgstr "預設：``PYMEM_ALLOCATOR_NOT_SET``。" + +#: ../../c-api/init_config.rst:900 +msgid "Set the LC_CTYPE locale to the user preferred locale." +msgstr "" + +#: ../../c-api/init_config.rst:902 +msgid "" +"If equals to ``0``, set :c:member:`~PyPreConfig.coerce_c_locale` and :c:" +"member:`~PyPreConfig.coerce_c_locale_warn` members to ``0``." +msgstr "" + +#: ../../c-api/init_config.rst:905 ../../c-api/init_config.rst:916 +msgid "See the :term:`locale encoding`." +msgstr "請見 :term:`locale encoding`。" + +#: ../../c-api/init_config.rst:907 ../../c-api/init_config.rst:962 +#: ../../c-api/init_config.rst:1333 +msgid "Default: ``1`` in Python config, ``0`` in isolated config." +msgstr "" + +#: ../../c-api/init_config.rst:911 +msgid "If equals to ``2``, coerce the C locale." +msgstr "" + +#: ../../c-api/init_config.rst:913 +msgid "" +"If equals to ``1``, read the LC_CTYPE locale to decide if it should be " +"coerced." +msgstr "" + +#: ../../c-api/init_config.rst:918 ../../c-api/init_config.rst:924 +msgid "Default: ``-1`` in Python config, ``0`` in isolated config." +msgstr "" + +#: ../../c-api/init_config.rst:922 +msgid "If non-zero, emit a warning if the C locale is coerced." +msgstr "" + +#: ../../c-api/init_config.rst:928 +msgid "" +":ref:`Python Development Mode `: see :c:member:`PyConfig.dev_mode`." +msgstr "" + +#: ../../c-api/init_config.rst:931 ../../c-api/init_config.rst:1342 +#: ../../c-api/init_config.rst:1398 ../../c-api/init_config.rst:1892 +msgid "Default: ``-1`` in Python mode, ``0`` in isolated mode." +msgstr "" + +#: ../../c-api/init_config.rst:935 +msgid "Isolated mode: see :c:member:`PyConfig.isolated`." +msgstr "" + +#: ../../c-api/init_config.rst:937 ../../c-api/init_config.rst:1569 +msgid "Default: ``0`` in Python mode, ``1`` in isolated mode." +msgstr "" + +#: ../../c-api/init_config.rst:941 +msgid "If non-zero:" +msgstr "如果不為 0：" + +#: ../../c-api/init_config.rst:943 +msgid "Set :c:member:`PyPreConfig.utf8_mode` to ``0``," +msgstr "將 :c:member:`PyPreConfig.utf8_mode` 設為 ``0``、" + +#: ../../c-api/init_config.rst:944 +msgid "Set :c:member:`PyConfig.filesystem_encoding` to ``\"mbcs\"``," +msgstr "將 :c:member:`PyConfig.filesystem_encoding` 設為 ``\"mbcs\"``、" + +#: ../../c-api/init_config.rst:945 +msgid "Set :c:member:`PyConfig.filesystem_errors` to ``\"replace\"``." +msgstr "將 :c:member:`PyConfig.filesystem_errors` 設為 ``\"replace\"``。" + +#: ../../c-api/init_config.rst:947 +msgid "" +"Initialized from the :envvar:`PYTHONLEGACYWINDOWSFSENCODING` environment " +"variable value." +msgstr "" + +#: ../../c-api/init_config.rst:950 ../../c-api/init_config.rst:1583 +msgid "" +"Only available on Windows. ``#ifdef MS_WINDOWS`` macro can be used for " +"Windows specific code." +msgstr "" + +#: ../../c-api/init_config.rst:953 ../../c-api/init_config.rst:1281 +#: ../../c-api/init_config.rst:1288 ../../c-api/init_config.rst:1355 +#: ../../c-api/init_config.rst:1487 ../../c-api/init_config.rst:1505 +#: ../../c-api/init_config.rst:1519 ../../c-api/init_config.rst:1586 +#: ../../c-api/init_config.rst:1600 ../../c-api/init_config.rst:1660 +#: ../../c-api/init_config.rst:1712 ../../c-api/init_config.rst:1774 +#: ../../c-api/init_config.rst:1828 ../../c-api/init_config.rst:1857 +#: ../../c-api/init_config.rst:1971 ../../c-api/init_config.rst:2018 +msgid "Default: ``0``." +msgstr "預設：``0``。" + +#: ../../c-api/init_config.rst:957 +msgid "" +"If non-zero, :c:func:`Py_PreInitializeFromArgs` and :c:func:" +"`Py_PreInitializeFromBytesArgs` parse their ``argv`` argument the same way " +"the regular Python parses command line arguments: see :ref:`Command Line " +"Arguments `." +msgstr "" + +#: ../../c-api/init_config.rst:966 +msgid "" +"Use :ref:`environment variables `? See :c:member:`PyConfig." +"use_environment`." +msgstr "" + +#: ../../c-api/init_config.rst:969 ../../c-api/init_config.rst:1933 +msgid "Default: ``1`` in Python config and ``0`` in isolated config." +msgstr "" + +#: ../../c-api/init_config.rst:973 +msgid "If non-zero, enable the :ref:`Python UTF-8 Mode `." +msgstr "" + +#: ../../c-api/init_config.rst:975 +msgid "" +"Set to ``0`` or ``1`` by the :option:`-X utf8 <-X>` command line option and " +"the :envvar:`PYTHONUTF8` environment variable." +msgstr "" + +#: ../../c-api/init_config.rst:978 +msgid "Also set to ``1`` if the ``LC_CTYPE`` locale is ``C`` or ``POSIX``." +msgstr "" + +#: ../../c-api/init_config.rst:980 +msgid "Default: ``-1`` in Python config and ``0`` in isolated config." +msgstr "" + +#: ../../c-api/init_config.rst:986 +msgid "Preinitialize Python with PyPreConfig" +msgstr "" + +#: ../../c-api/init_config.rst:988 +msgid "The preinitialization of Python:" +msgstr "" + +#: ../../c-api/init_config.rst:990 +msgid "Set the Python memory allocators (:c:member:`PyPreConfig.allocator`)" +msgstr "" + +#: ../../c-api/init_config.rst:991 +msgid "Configure the LC_CTYPE locale (:term:`locale encoding`)" +msgstr "" + +#: ../../c-api/init_config.rst:992 +msgid "" +"Set the :ref:`Python UTF-8 Mode ` (:c:member:`PyPreConfig." +"utf8_mode`)" +msgstr "" + +#: ../../c-api/init_config.rst:995 +msgid "" +"The current preconfiguration (``PyPreConfig`` type) is stored in " +"``_PyRuntime.preconfig``." +msgstr "" + +#: ../../c-api/init_config.rst:998 +msgid "Functions to preinitialize Python:" +msgstr "" + +#: ../../c-api/init_config.rst:1002 ../../c-api/init_config.rst:1008 +#: ../../c-api/init_config.rst:1017 +msgid "Preinitialize Python from *preconfig* preconfiguration." +msgstr "" + +#: ../../c-api/init_config.rst:1004 ../../c-api/init_config.rst:1013 +#: ../../c-api/init_config.rst:1022 +msgid "*preconfig* must not be ``NULL``." +msgstr "*preconfig* 不可為 ``NULL``。" + +#: ../../c-api/init_config.rst:1010 +msgid "" +"Parse *argv* command line arguments (bytes strings) if :c:member:" +"`~PyPreConfig.parse_argv` of *preconfig* is non-zero." +msgstr "" + +#: ../../c-api/init_config.rst:1019 +msgid "" +"Parse *argv* command line arguments (wide strings) if :c:member:" +"`~PyPreConfig.parse_argv` of *preconfig* is non-zero." +msgstr "" + +#: ../../c-api/init_config.rst:1024 ../../c-api/init_config.rst:2041 +msgid "" +"The caller is responsible to handle exceptions (error or exit) using :c:func:" +"`PyStatus_Exception` and :c:func:`Py_ExitStatusException`." +msgstr "" + +#: ../../c-api/init_config.rst:1027 +msgid "" +"For :ref:`Python Configuration ` (:c:func:" +"`PyPreConfig_InitPythonConfig`), if Python is initialized with command line " +"arguments, the command line arguments must also be passed to preinitialize " +"Python, since they have an effect on the pre-configuration like encodings. " +"For example, the :option:`-X utf8 <-X>` command line option enables the :ref:" +"`Python UTF-8 Mode `." +msgstr "" + +#: ../../c-api/init_config.rst:1034 +msgid "" +"``PyMem_SetAllocator()`` can be called after :c:func:`Py_PreInitialize` and " +"before :c:func:`Py_InitializeFromConfig` to install a custom memory " +"allocator. It can be called before :c:func:`Py_PreInitialize` if :c:member:" +"`PyPreConfig.allocator` is set to ``PYMEM_ALLOCATOR_NOT_SET``." +msgstr "" + +#: ../../c-api/init_config.rst:1039 +msgid "" +"Python memory allocation functions like :c:func:`PyMem_RawMalloc` must not " +"be used before the Python preinitialization, whereas calling directly " +"``malloc()`` and ``free()`` is always safe. :c:func:`Py_DecodeLocale` must " +"not be called before the Python preinitialization." +msgstr "" + +#: ../../c-api/init_config.rst:1044 +msgid "" +"Example using the preinitialization to enable the :ref:`Python UTF-8 Mode " +"`::" +msgstr "" + +#: ../../c-api/init_config.rst:1047 +msgid "" +"PyStatus status;\n" +"PyPreConfig preconfig;\n" +"PyPreConfig_InitPythonConfig(&preconfig);\n" +"\n" +"preconfig.utf8_mode = 1;\n" +"\n" +"status = Py_PreInitialize(&preconfig);\n" +"if (PyStatus_Exception(status)) {\n" +" Py_ExitStatusException(status);\n" +"}\n" +"\n" +"/* at this point, Python speaks UTF-8 */\n" +"\n" +"Py_Initialize();\n" +"/* ... use Python API here ... */\n" +"Py_Finalize();" +msgstr "" + +#: ../../c-api/init_config.rst:1066 +msgid "PyConfig" +msgstr "PyConfig" + +#: ../../c-api/init_config.rst:1070 +msgid "Structure containing most parameters to configure Python." +msgstr "" + +#: ../../c-api/init_config.rst:1072 +msgid "" +"When done, the :c:func:`PyConfig_Clear` function must be used to release the " +"configuration memory." +msgstr "" + +#: ../../c-api/init_config.rst:1077 +msgid "Structure methods:" +msgstr "" + +#: ../../c-api/init_config.rst:1081 +msgid "" +"Initialize configuration with the :ref:`Python Configuration `." +msgstr "" + +#: ../../c-api/init_config.rst:1086 +msgid "" +"Initialize configuration with the :ref:`Isolated Configuration `." +msgstr "" + +#: ../../c-api/init_config.rst:1091 +msgid "Copy the wide character string *str* into ``*config_str``." +msgstr "" + +#: ../../c-api/init_config.rst:1093 ../../c-api/init_config.rst:1100 +#: ../../c-api/init_config.rst:1107 ../../c-api/init_config.rst:1115 +#: ../../c-api/init_config.rst:1121 ../../c-api/init_config.rst:1138 +msgid ":ref:`Preinitialize Python ` if needed." +msgstr "" + +#: ../../c-api/init_config.rst:1097 +msgid "" +"Decode *str* using :c:func:`Py_DecodeLocale` and set the result into " +"``*config_str``." +msgstr "" + +#: ../../c-api/init_config.rst:1104 +msgid "" +"Set command line arguments (:c:member:`~PyConfig.argv` member of *config*) " +"from the *argv* list of wide character strings." +msgstr "" + +#: ../../c-api/init_config.rst:1111 +msgid "" +"Set command line arguments (:c:member:`~PyConfig.argv` member of *config*) " +"from the *argv* list of bytes strings. Decode bytes using :c:func:" +"`Py_DecodeLocale`." +msgstr "" + +#: ../../c-api/init_config.rst:1119 +msgid "Set the list of wide strings *list* to *length* and *items*." +msgstr "" + +#: ../../c-api/init_config.rst:1125 +msgid "Read all Python configuration." +msgstr "讀取所有 Python 配置。" + +#: ../../c-api/init_config.rst:1127 +msgid "Fields which are already initialized are left unchanged." +msgstr "已經初始化的欄位將保持不變。" + +#: ../../c-api/init_config.rst:1129 +msgid "" +"Fields for :ref:`path configuration ` are no longer " +"calculated or modified when calling this function, as of Python 3.11." +msgstr "" + +#: ../../c-api/init_config.rst:1132 ../../c-api/init_config.rst:1689 +msgid "" +"The :c:func:`PyConfig_Read` function only parses :c:member:`PyConfig.argv` " +"arguments once: :c:member:`PyConfig.parse_argv` is set to ``2`` after " +"arguments are parsed. Since Python arguments are stripped from :c:member:" +"`PyConfig.argv`, parsing arguments twice would parse the application options " +"as Python options." +msgstr "" + +#: ../../c-api/init_config.rst:1140 +msgid "" +"The :c:member:`PyConfig.argv` arguments are now only parsed once, :c:member:" +"`PyConfig.parse_argv` is set to ``2`` after arguments are parsed, and " +"arguments are only parsed if :c:member:`PyConfig.parse_argv` equals ``1``." +msgstr "" + +#: ../../c-api/init_config.rst:1146 +msgid "" +":c:func:`PyConfig_Read` no longer calculates all paths, and so fields listed " +"under :ref:`Python Path Configuration ` may no longer be " +"updated until :c:func:`Py_InitializeFromConfig` is called." +msgstr "" + +#: ../../c-api/init_config.rst:1154 +msgid "Release configuration memory." +msgstr "" + +#: ../../c-api/init_config.rst:1156 +msgid "" +"Most ``PyConfig`` methods :ref:`preinitialize Python ` if needed. " +"In that case, the Python preinitialization configuration (:c:type:" +"`PyPreConfig`) in based on the :c:type:`PyConfig`. If configuration fields " +"which are in common with :c:type:`PyPreConfig` are tuned, they must be set " +"before calling a :c:type:`PyConfig` method:" +msgstr "" + +#: ../../c-api/init_config.rst:1162 +msgid ":c:member:`PyConfig.dev_mode`" +msgstr ":c:member:`PyConfig.dev_mode`" + +#: ../../c-api/init_config.rst:1163 +msgid ":c:member:`PyConfig.isolated`" +msgstr ":c:member:`PyConfig.isolated`" + +#: ../../c-api/init_config.rst:1164 +msgid ":c:member:`PyConfig.parse_argv`" +msgstr ":c:member:`PyConfig.parse_argv`" + +#: ../../c-api/init_config.rst:1165 +msgid ":c:member:`PyConfig.use_environment`" +msgstr ":c:member:`PyConfig.use_environment`" + +#: ../../c-api/init_config.rst:1167 +msgid "" +"Moreover, if :c:func:`PyConfig_SetArgv` or :c:func:`PyConfig_SetBytesArgv` " +"is used, this method must be called before other methods, since the " +"preinitialization configuration depends on command line arguments (if :c:" +"member:`~PyConfig.parse_argv` is non-zero)." +msgstr "" + +#: ../../c-api/init_config.rst:1172 +msgid "" +"The caller of these methods is responsible to handle exceptions (error or " +"exit) using ``PyStatus_Exception()`` and ``Py_ExitStatusException()``." +msgstr "" + +#: ../../c-api/init_config.rst:1185 +msgid "" +"Set :data:`sys.argv` command line arguments based on :c:member:`~PyConfig." +"argv`. These parameters are similar to those passed to the program's :c:" +"func:`main` function with the difference that the first entry should refer " +"to the script file to be executed rather than the executable hosting the " +"Python interpreter. If there isn't a script that will be run, the first " +"entry in :c:member:`~PyConfig.argv` can be an empty string." +msgstr "" + +#: ../../c-api/init_config.rst:1193 +msgid "" +"Set :c:member:`~PyConfig.parse_argv` to ``1`` to parse :c:member:`~PyConfig." +"argv` the same way the regular Python parses Python command line arguments " +"and then to strip Python arguments from :c:member:`~PyConfig.argv`." +msgstr "" + +#: ../../c-api/init_config.rst:1198 +msgid "" +"If :c:member:`~PyConfig.argv` is empty, an empty string is added to ensure " +"that :data:`sys.argv` always exists and is never empty." +msgstr "" + +#: ../../c-api/init_config.rst:1201 ../../c-api/init_config.rst:1228 +#: ../../c-api/init_config.rst:1242 ../../c-api/init_config.rst:1252 +#: ../../c-api/init_config.rst:1363 ../../c-api/init_config.rst:1372 +#: ../../c-api/init_config.rst:1383 ../../c-api/init_config.rst:1474 +#: ../../c-api/init_config.rst:1630 ../../c-api/init_config.rst:1731 +#: ../../c-api/init_config.rst:1750 ../../c-api/init_config.rst:1765 +#: ../../c-api/init_config.rst:1782 ../../c-api/init_config.rst:1795 +#: ../../c-api/init_config.rst:1803 ../../c-api/init_config.rst:1817 +#: ../../c-api/init_config.rst:1920 +msgid "Default: ``NULL``." +msgstr "預設值：``NULL``。" + +#: ../../c-api/init_config.rst:1203 +msgid "See also the :c:member:`~PyConfig.orig_argv` member." +msgstr "另請參閱 :c:member:`~PyConfig.orig_argv` 成員。" + +#: ../../c-api/init_config.rst:1207 +msgid "" +"If equals to zero, ``Py_RunMain()`` prepends a potentially unsafe path to :" +"data:`sys.path` at startup:" +msgstr "" + +#: ../../c-api/init_config.rst:1210 +msgid "" +"If :c:member:`argv[0] ` is equal to ``L\"-m\"`` (``python -m " +"module``), prepend the current working directory." +msgstr "" + +#: ../../c-api/init_config.rst:1212 +msgid "" +"If running a script (``python script.py``), prepend the script's directory. " +"If it's a symbolic link, resolve symbolic links." +msgstr "" + +#: ../../c-api/init_config.rst:1214 +msgid "" +"Otherwise (``python -c code`` and ``python``), prepend an empty string, " +"which means the current working directory." +msgstr "" + +#: ../../c-api/init_config.rst:1217 +msgid "" +"Set to ``1`` by the :option:`-P` command line option and the :envvar:" +"`PYTHONSAFEPATH` environment variable." +msgstr "" + +#: ../../c-api/init_config.rst:1220 +msgid "Default: ``0`` in Python config, ``1`` in isolated config." +msgstr "" + +#: ../../c-api/init_config.rst:1226 +msgid ":data:`sys.base_exec_prefix`." +msgstr ":data:`sys.base_exec_prefix`。" + +#: ../../c-api/init_config.rst:1230 ../../c-api/init_config.rst:1244 +#: ../../c-api/init_config.rst:1254 ../../c-api/init_config.rst:1374 +#: ../../c-api/init_config.rst:1385 ../../c-api/init_config.rst:1647 +#: ../../c-api/init_config.rst:1733 +msgid "Part of the :ref:`Python Path Configuration ` output." +msgstr "" + +#: ../../c-api/init_config.rst:1232 +msgid "See also :c:member:`PyConfig.exec_prefix`." +msgstr "也請見 :c:member:`PyConfig.exec_prefix`" + +#: ../../c-api/init_config.rst:1236 +msgid "Python base executable: :data:`sys._base_executable`." +msgstr "" + +#: ../../c-api/init_config.rst:1238 +msgid "Set by the :envvar:`__PYVENV_LAUNCHER__` environment variable." +msgstr "由 :envvar:`__PYVENV_LAUNCHER__` 環境變數設定。" + +#: ../../c-api/init_config.rst:1240 +msgid "Set from :c:member:`PyConfig.executable` if ``NULL``." +msgstr "如果為 ``NULL``，則從 :c:member:`PyConfig.executable` 設定。" + +#: ../../c-api/init_config.rst:1246 +msgid "See also :c:member:`PyConfig.executable`." +msgstr "也請見 :c:member:`PyConfig.executable`" + +#: ../../c-api/init_config.rst:1250 +msgid ":data:`sys.base_prefix`." +msgstr ":data:`sys.base_prefix`。" + +#: ../../c-api/init_config.rst:1256 +msgid "See also :c:member:`PyConfig.prefix`." +msgstr "也請見 :c:member:`PyConfig.prefix`" + +#: ../../c-api/init_config.rst:1260 +msgid "" +"If equals to ``0`` and :c:member:`~PyConfig.configure_c_stdio` is non-zero, " +"disable buffering on the C streams stdout and stderr." +msgstr "" + +#: ../../c-api/init_config.rst:1263 +msgid "" +"Set to ``0`` by the :option:`-u` command line option and the :envvar:" +"`PYTHONUNBUFFERED` environment variable." +msgstr "" + +#: ../../c-api/init_config.rst:1266 +msgid "stdin is always opened in buffered mode." +msgstr "" + +#: ../../c-api/init_config.rst:1268 ../../c-api/init_config.rst:1301 +#: ../../c-api/init_config.rst:1845 ../../c-api/init_config.rst:2003 +msgid "Default: ``1``." +msgstr "預設值：``1``。" + +#: ../../c-api/init_config.rst:1272 +msgid "" +"If equals to ``1``, issue a warning when comparing :class:`bytes` or :class:" +"`bytearray` with :class:`str`, or comparing :class:`bytes` with :class:`int`." +msgstr "" + +#: ../../c-api/init_config.rst:1276 +msgid "" +"If equal or greater to ``2``, raise a :exc:`BytesWarning` exception in these " +"cases." +msgstr "" + +#: ../../c-api/init_config.rst:1279 +msgid "Incremented by the :option:`-b` command line option." +msgstr "" + +#: ../../c-api/init_config.rst:1285 +msgid "" +"If non-zero, emit a :exc:`EncodingWarning` warning when :class:`io." +"TextIOWrapper` uses its default encoding. See :ref:`io-encoding-warning` for " +"details." +msgstr "" + +#: ../../c-api/init_config.rst:1294 +msgid "" +"If equals to ``0``, disables the inclusion of the end line and column " +"mappings in code objects. Also disables traceback printing carets to " +"specific error locations." +msgstr "" + +#: ../../c-api/init_config.rst:1298 +msgid "" +"Set to ``0`` by the :envvar:`PYTHONNODEBUGRANGES` environment variable and " +"by the :option:`-X no_debug_ranges <-X>` command line option." +msgstr "" + +#: ../../c-api/init_config.rst:1307 +msgid "" +"Control the validation behavior of hash-based ``.pyc`` files: value of the :" +"option:`--check-hash-based-pycs` command line option." +msgstr "" + +#: ../../c-api/init_config.rst:1310 +msgid "Valid values:" +msgstr "有效值：" + +#: ../../c-api/init_config.rst:1312 +msgid "" +"``L\"always\"``: Hash the source file for invalidation regardless of value " +"of the 'check_source' flag." +msgstr "" + +#: ../../c-api/init_config.rst:1314 +msgid "``L\"never\"``: Assume that hash-based pycs always are valid." +msgstr "" + +#: ../../c-api/init_config.rst:1315 +msgid "" +"``L\"default\"``: The 'check_source' flag in hash-based pycs determines " +"invalidation." +msgstr "" + +#: ../../c-api/init_config.rst:1318 +msgid "Default: ``L\"default\"``." +msgstr "預設：``L\"default\"``。" + +#: ../../c-api/init_config.rst:1320 +msgid "See also :pep:`552` \"Deterministic pycs\"." +msgstr "" + +#: ../../c-api/init_config.rst:1324 +msgid "If non-zero, configure C standard streams:" +msgstr "" + +#: ../../c-api/init_config.rst:1326 +msgid "" +"On Windows, set the binary mode (``O_BINARY``) on stdin, stdout and stderr." +msgstr "" + +#: ../../c-api/init_config.rst:1328 +msgid "" +"If :c:member:`~PyConfig.buffered_stdio` equals zero, disable buffering of " +"stdin, stdout and stderr streams." +msgstr "" + +#: ../../c-api/init_config.rst:1330 +msgid "" +"If :c:member:`~PyConfig.interactive` is non-zero, enable stream buffering on " +"stdin and stdout (only stdout on Windows)." +msgstr "" + +#: ../../c-api/init_config.rst:1337 +msgid "If non-zero, enable the :ref:`Python Development Mode `." +msgstr "" + +#: ../../c-api/init_config.rst:1339 +msgid "" +"Set to ``1`` by the :option:`-X dev <-X>` option and the :envvar:" +"`PYTHONDEVMODE` environment variable." +msgstr "" + +#: ../../c-api/init_config.rst:1346 +msgid "Dump Python references?" +msgstr "" + +#: ../../c-api/init_config.rst:1348 +msgid "If non-zero, dump all objects which are still alive at exit." +msgstr "" + +#: ../../c-api/init_config.rst:1350 +msgid "Set to ``1`` by the :envvar:`PYTHONDUMPREFS` environment variable." +msgstr "" + +#: ../../c-api/init_config.rst:1352 +msgid "" +"Needs a special build of Python with the ``Py_TRACE_REFS`` macro defined: " +"see the :option:`configure --with-trace-refs option <--with-trace-refs>`." +msgstr "" + +#: ../../c-api/init_config.rst:1359 +msgid "Filename where to dump Python references." +msgstr "" + +#: ../../c-api/init_config.rst:1361 +msgid "Set by the :envvar:`PYTHONDUMPREFSFILE` environment variable." +msgstr "由 :envvar:`PYTHONDUMPREFSFILE` 環境變數設定。" + +#: ../../c-api/init_config.rst:1369 +msgid "" +"The site-specific directory prefix where the platform-dependent Python files " +"are installed: :data:`sys.exec_prefix`." +msgstr "" + +#: ../../c-api/init_config.rst:1376 +msgid "See also :c:member:`PyConfig.base_exec_prefix`." +msgstr "也請見 :c:member:`PyConfig.base_exec_prefix`" + +#: ../../c-api/init_config.rst:1380 +msgid "" +"The absolute path of the executable binary for the Python interpreter: :data:" +"`sys.executable`." +msgstr "" + +#: ../../c-api/init_config.rst:1387 +msgid "See also :c:member:`PyConfig.base_executable`." +msgstr "也請見 :c:member:`PyConfig.base_executable`" + +#: ../../c-api/init_config.rst:1391 +msgid "Enable faulthandler?" +msgstr "啟用 faulthandler？" + +#: ../../c-api/init_config.rst:1393 +msgid "If non-zero, call :func:`faulthandler.enable` at startup." +msgstr "如果非零，則在啟動時呼叫 :func:`faulthandler.enable`。" + +#: ../../c-api/init_config.rst:1395 +msgid "" +"Set to ``1`` by :option:`-X faulthandler <-X>` and the :envvar:" +"`PYTHONFAULTHANDLER` environment variable." +msgstr "" + +#: ../../c-api/init_config.rst:1402 +msgid "" +":term:`Filesystem encoding `: :func:" +"`sys.getfilesystemencoding`." +msgstr "" + +#: ../../c-api/init_config.rst:1405 +msgid "On macOS, Android and VxWorks: use ``\"utf-8\"`` by default." +msgstr "" + +#: ../../c-api/init_config.rst:1407 +msgid "" +"On Windows: use ``\"utf-8\"`` by default, or ``\"mbcs\"`` if :c:member:" +"`~PyPreConfig.legacy_windows_fs_encoding` of :c:type:`PyPreConfig` is non-" +"zero." +msgstr "" + +#: ../../c-api/init_config.rst:1411 +msgid "Default encoding on other platforms:" +msgstr "其他平台的預設編碼：" + +#: ../../c-api/init_config.rst:1413 +msgid "``\"utf-8\"`` if :c:member:`PyPreConfig.utf8_mode` is non-zero." +msgstr "如果 :c:member:`PyPreConfig.utf8_mode` 非零，則為 ``\"utf-8\"``。" + +#: ../../c-api/init_config.rst:1414 +msgid "" +"``\"ascii\"`` if Python detects that ``nl_langinfo(CODESET)`` announces the " +"ASCII encoding, whereas the ``mbstowcs()`` function decodes from a different " +"encoding (usually Latin1)." +msgstr "" + +#: ../../c-api/init_config.rst:1417 +msgid "``\"utf-8\"`` if ``nl_langinfo(CODESET)`` returns an empty string." +msgstr "" + +#: ../../c-api/init_config.rst:1418 +msgid "" +"Otherwise, use the :term:`locale encoding`: ``nl_langinfo(CODESET)`` result." +msgstr "" + +#: ../../c-api/init_config.rst:1421 +msgid "" +"At Python startup, the encoding name is normalized to the Python codec name. " +"For example, ``\"ANSI_X3.4-1968\"`` is replaced with ``\"ascii\"``." +msgstr "" + +#: ../../c-api/init_config.rst:1424 +msgid "See also the :c:member:`~PyConfig.filesystem_errors` member." +msgstr "另請參閱 :c:member:`~PyConfig.filesystem_errors` 成員。" + +#: ../../c-api/init_config.rst:1428 +msgid "" +":term:`Filesystem error handler `: :" +"func:`sys.getfilesystemencodeerrors`." +msgstr "" + +#: ../../c-api/init_config.rst:1431 +msgid "" +"On Windows: use ``\"surrogatepass\"`` by default, or ``\"replace\"`` if :c:" +"member:`~PyPreConfig.legacy_windows_fs_encoding` of :c:type:`PyPreConfig` is " +"non-zero." +msgstr "" + +#: ../../c-api/init_config.rst:1435 +msgid "On other platforms: use ``\"surrogateescape\"`` by default." +msgstr "其他平台：預設使用 ``\"surrogateescape\"``。" + +#: ../../c-api/init_config.rst:1437 +msgid "Supported error handlers:" +msgstr "支援的錯誤處理器：" + +#: ../../c-api/init_config.rst:1439 +msgid "``\"strict\"``" +msgstr "``\"strict\"``" + +#: ../../c-api/init_config.rst:1440 +msgid "``\"surrogateescape\"``" +msgstr "``\"surrogateescape\"``" + +#: ../../c-api/init_config.rst:1441 +msgid "``\"surrogatepass\"`` (only supported with the UTF-8 encoding)" +msgstr "``\"surrogatepass\"``\\ （僅支援 UTF-8 編碼）" + +#: ../../c-api/init_config.rst:1443 +msgid "See also the :c:member:`~PyConfig.filesystem_encoding` member." +msgstr "另請參閱 :c:member:`~PyConfig.filesystem_encoding` 成員。" + +#: ../../c-api/init_config.rst:1447 +msgid "If non-zero, use frozen modules." +msgstr "如果非零，則使用凍結模組。" + +#: ../../c-api/init_config.rst:1449 +msgid "Set by the :envvar:`PYTHON_FROZEN_MODULES` environment variable." +msgstr "由 :envvar:`PYTHON_FROZEN_MODULES` 環境變數設定。" + +#: ../../c-api/init_config.rst:1451 +msgid "" +"Default: ``1`` in a release build, or ``0`` in a :ref:`debug build `." +msgstr "" + +#: ../../c-api/init_config.rst:1457 +msgid "Randomized hash function seed." +msgstr "" + +#: ../../c-api/init_config.rst:1459 +msgid "" +"If :c:member:`~PyConfig.use_hash_seed` is zero, a seed is chosen randomly at " +"Python startup, and :c:member:`~PyConfig.hash_seed` is ignored." +msgstr "" + +#: ../../c-api/init_config.rst:1462 +msgid "Set by the :envvar:`PYTHONHASHSEED` environment variable." +msgstr "由 :envvar:`PYTHONHASHSEED` 環境變數設定。" + +#: ../../c-api/init_config.rst:1464 +msgid "" +"Default *use_hash_seed* value: ``-1`` in Python mode, ``0`` in isolated mode." +msgstr "" + +#: ../../c-api/init_config.rst:1469 +msgid "" +"Set the default Python \"home\" directory, that is, the location of the " +"standard Python libraries (see :envvar:`PYTHONHOME`)." +msgstr "" + +#: ../../c-api/init_config.rst:1472 +msgid "Set by the :envvar:`PYTHONHOME` environment variable." +msgstr "由 :envvar:`PYTHONHOME` 環境變數設定。" + +#: ../../c-api/init_config.rst:1476 ../../c-api/init_config.rst:1612 +#: ../../c-api/init_config.rst:1632 ../../c-api/init_config.rst:1721 +#: ../../c-api/init_config.rst:1752 +msgid "Part of the :ref:`Python Path Configuration ` input." +msgstr "" + +#: ../../c-api/init_config.rst:1480 +msgid "" +"If ``1``, profile import time. If ``2``, include additional output that " +"indicates when an imported module has already been loaded." +msgstr "" + +#: ../../c-api/init_config.rst:1484 +msgid "" +"Set by the :option:`-X importtime <-X>` option and the :envvar:" +"`PYTHONPROFILEIMPORTTIME` environment variable." +msgstr "" +"由 :option:`-X importtime <-X>` 選項與 :envvar:`PYTHONPROFILEIMPORTTIME` 環境" +"變數設定。" + +#: ../../c-api/init_config.rst:1491 +msgid "Added support for ``import_time = 2``" +msgstr "新增對 ``import_time = 2`` 的支援" + +#: ../../c-api/init_config.rst:1495 +msgid "Enter interactive mode after executing a script or a command." +msgstr "在執行腳本或命令後進入互動模式。" + +#: ../../c-api/init_config.rst:1497 +msgid "" +"If greater than ``0``, enable inspect: when a script is passed as first " +"argument or the -c option is used, enter interactive mode after executing " +"the script or the command, even when :data:`sys.stdin` does not appear to be " +"a terminal." +msgstr "" + +#: ../../c-api/init_config.rst:1502 +msgid "" +"Incremented by the :option:`-i` command line option. Set to ``1`` if the :" +"envvar:`PYTHONINSPECT` environment variable is non-empty." +msgstr "" + +#: ../../c-api/init_config.rst:1509 +msgid "Install Python signal handlers?" +msgstr "" + +#: ../../c-api/init_config.rst:1511 ../../c-api/init_config.rst:1695 +#: ../../c-api/init_config.rst:1719 ../../c-api/init_config.rst:1955 +msgid "Default: ``1`` in Python mode, ``0`` in isolated mode." +msgstr "" + +#: ../../c-api/init_config.rst:1515 +msgid "If greater than ``0``, enable the interactive mode (REPL)." +msgstr "" + +#: ../../c-api/init_config.rst:1517 +msgid "Incremented by the :option:`-i` command line option." +msgstr "" + +#: ../../c-api/init_config.rst:1523 +msgid "" +"Configures the :ref:`integer string conversion length limitation " +"`. An initial value of ``-1`` means the value will be " +"taken from the command line or environment or otherwise default to 4300 (:" +"data:`sys.int_info.default_max_str_digits`). A value of ``0`` disables the " +"limitation. Values greater than zero but less than 640 (:data:`sys.int_info." +"str_digits_check_threshold`) are unsupported and will produce an error." +msgstr "" + +#: ../../c-api/init_config.rst:1531 +msgid "" +"Configured by the :option:`-X int_max_str_digits <-X>` command line flag or " +"the :envvar:`PYTHONINTMAXSTRDIGITS` environment variable." +msgstr "" + +#: ../../c-api/init_config.rst:1534 +msgid "" +"Default: ``-1`` in Python mode. 4300 (:data:`sys.int_info." +"default_max_str_digits`) in isolated mode." +msgstr "" + +#: ../../c-api/init_config.rst:1541 +msgid "" +"If the value of :c:member:`~PyConfig.cpu_count` is not ``-1`` then it will " +"override the return values of :func:`os.cpu_count`, :func:`os." +"process_cpu_count`, and :func:`multiprocessing.cpu_count`." +msgstr "" + +#: ../../c-api/init_config.rst:1545 +msgid "" +"Configured by the :samp:`-X cpu_count={n|default}` command line flag or the :" +"envvar:`PYTHON_CPU_COUNT` environment variable." +msgstr "" + +#: ../../c-api/init_config.rst:1548 ../../c-api/init_config.rst:1909 +msgid "Default: ``-1``." +msgstr "預設值：``1``。" + +#: ../../c-api/init_config.rst:1554 +msgid "If greater than ``0``, enable isolated mode:" +msgstr "" + +#: ../../c-api/init_config.rst:1556 +msgid "" +"Set :c:member:`~PyConfig.safe_path` to ``1``: don't prepend a potentially " +"unsafe path to :data:`sys.path` at Python startup, such as the current " +"directory, the script's directory or an empty string." +msgstr "" + +#: ../../c-api/init_config.rst:1560 +msgid "" +"Set :c:member:`~PyConfig.use_environment` to ``0``: ignore ``PYTHON`` " +"environment variables." +msgstr "" +"將 :c:member:`~PyConfig.use_environment` 設定為 ``0``：忽略 ``PYTHON`` 環境變" +"數。" + +#: ../../c-api/init_config.rst:1562 +msgid "" +"Set :c:member:`~PyConfig.user_site_directory` to ``0``: don't add the user " +"site directory to :data:`sys.path`." +msgstr "" + +#: ../../c-api/init_config.rst:1564 +msgid "" +"Python REPL doesn't import :mod:`readline` nor enable default readline " +"configuration on interactive prompts." +msgstr "" + +#: ../../c-api/init_config.rst:1567 +msgid "Set to ``1`` by the :option:`-I` command line option." +msgstr "" + +#: ../../c-api/init_config.rst:1571 +msgid "" +"See also the :ref:`Isolated Configuration ` and :c:" +"member:`PyPreConfig.isolated`." +msgstr "" + +#: ../../c-api/init_config.rst:1576 +msgid "" +"If non-zero, use :class:`io.FileIO` instead of :class:`!io." +"_WindowsConsoleIO` for :data:`sys.stdin`, :data:`sys.stdout` and :data:`sys." +"stderr`." +msgstr "" + +#: ../../c-api/init_config.rst:1580 +msgid "" +"Set to ``1`` if the :envvar:`PYTHONLEGACYWINDOWSSTDIO` environment variable " +"is set to a non-empty string." +msgstr "" + +#: ../../c-api/init_config.rst:1588 +msgid "See also the :pep:`528` (Change Windows console encoding to UTF-8)." +msgstr "" + +#: ../../c-api/init_config.rst:1592 +msgid "" +"If non-zero, dump statistics on :ref:`Python pymalloc memory allocator " +"` at exit." +msgstr "" + +#: ../../c-api/init_config.rst:1595 +msgid "Set to ``1`` by the :envvar:`PYTHONMALLOCSTATS` environment variable." +msgstr "" + +#: ../../c-api/init_config.rst:1597 +msgid "" +"The option is ignored if Python is :option:`configured using the --without-" +"pymalloc option <--without-pymalloc>`." +msgstr "" + +#: ../../c-api/init_config.rst:1604 +msgid "Platform library directory name: :data:`sys.platlibdir`." +msgstr "" + +#: ../../c-api/init_config.rst:1606 +msgid "Set by the :envvar:`PYTHONPLATLIBDIR` environment variable." +msgstr "" + +#: ../../c-api/init_config.rst:1608 +msgid "" +"Default: value of the ``PLATLIBDIR`` macro which is set by the :option:" +"`configure --with-platlibdir option <--with-platlibdir>` (default: " +"``\"lib\"``, or ``\"DLLs\"`` on Windows)." +msgstr "" + +#: ../../c-api/init_config.rst:1616 +msgid "" +"This macro is now used on Windows to locate the standard library extension " +"modules, typically under ``DLLs``. However, for compatibility, note that " +"this value is ignored for any non-standard layouts, including in-tree builds " +"and virtual environments." +msgstr "" + +#: ../../c-api/init_config.rst:1625 +msgid "" +"Module search paths (:data:`sys.path`) as a string separated by ``DELIM`` (:" +"data:`os.pathsep`)." +msgstr "" + +#: ../../c-api/init_config.rst:1628 +msgid "Set by the :envvar:`PYTHONPATH` environment variable." +msgstr "" + +#: ../../c-api/init_config.rst:1637 +msgid "Module search paths: :data:`sys.path`." +msgstr "" + +#: ../../c-api/init_config.rst:1639 +msgid "" +"If :c:member:`~PyConfig.module_search_paths_set` is equal to ``0``, :c:func:" +"`Py_InitializeFromConfig` will replace :c:member:`~PyConfig." +"module_search_paths` and sets :c:member:`~PyConfig.module_search_paths_set` " +"to ``1``." +msgstr "" + +#: ../../c-api/init_config.rst:1644 +msgid "" +"Default: empty list (``module_search_paths``) and ``0`` " +"(``module_search_paths_set``)." +msgstr "" + +#: ../../c-api/init_config.rst:1651 +msgid "Compilation optimization level:" +msgstr "" + +#: ../../c-api/init_config.rst:1653 +msgid "``0``: Peephole optimizer, set ``__debug__`` to ``True``." +msgstr "" + +#: ../../c-api/init_config.rst:1654 +msgid "``1``: Level 0, remove assertions, set ``__debug__`` to ``False``." +msgstr "" + +#: ../../c-api/init_config.rst:1655 +msgid "``2``: Level 1, strip docstrings." +msgstr "" + +#: ../../c-api/init_config.rst:1657 +msgid "" +"Incremented by the :option:`-O` command line option. Set to the :envvar:" +"`PYTHONOPTIMIZE` environment variable value." +msgstr "" + +#: ../../c-api/init_config.rst:1664 +msgid "" +"The list of the original command line arguments passed to the Python " +"executable: :data:`sys.orig_argv`." +msgstr "" + +#: ../../c-api/init_config.rst:1667 +msgid "" +"If :c:member:`~PyConfig.orig_argv` list is empty and :c:member:`~PyConfig." +"argv` is not a list only containing an empty string, :c:func:`PyConfig_Read` " +"copies :c:member:`~PyConfig.argv` into :c:member:`~PyConfig.orig_argv` " +"before modifying :c:member:`~PyConfig.argv` (if :c:member:`~PyConfig." +"parse_argv` is non-zero)." +msgstr "" + +#: ../../c-api/init_config.rst:1674 +msgid "" +"See also the :c:member:`~PyConfig.argv` member and the :c:func:" +"`Py_GetArgcArgv` function." +msgstr "" + +#: ../../c-api/init_config.rst:1677 ../../c-api/init_config.rst:1990 +#: ../../c-api/init_config.rst:2009 +msgid "Default: empty list." +msgstr "" + +#: ../../c-api/init_config.rst:1683 +msgid "Parse command line arguments?" +msgstr "" + +#: ../../c-api/init_config.rst:1685 +msgid "" +"If equals to ``1``, parse :c:member:`~PyConfig.argv` the same way the " +"regular Python parses :ref:`command line arguments `, and " +"strip Python arguments from :c:member:`~PyConfig.argv`." +msgstr "" + +#: ../../c-api/init_config.rst:1697 +msgid "" +"The :c:member:`PyConfig.argv` arguments are now only parsed if :c:member:" +"`PyConfig.parse_argv` equals to ``1``." +msgstr "" + +#: ../../c-api/init_config.rst:1703 +msgid "" +"Parser debug mode. If greater than ``0``, turn on parser debugging output " +"(for expert only, depending on compilation options)." +msgstr "" + +#: ../../c-api/init_config.rst:1706 +msgid "" +"Incremented by the :option:`-d` command line option. Set to the :envvar:" +"`PYTHONDEBUG` environment variable value." +msgstr "" + +#: ../../c-api/init_config.rst:1709 ../../c-api/init_config.rst:1814 +msgid "" +"Needs a :ref:`debug build of Python ` (the ``Py_DEBUG`` macro " +"must be defined)." +msgstr "" + +#: ../../c-api/init_config.rst:1716 +msgid "" +"If non-zero, calculation of path configuration is allowed to log warnings " +"into ``stderr``. If equals to ``0``, suppress these warnings." +msgstr "" + +#: ../../c-api/init_config.rst:1723 +msgid "Now also applies on Windows." +msgstr "現在也適用於 Windows。" + +#: ../../c-api/init_config.rst:1728 +msgid "" +"The site-specific directory prefix where the platform independent Python " +"files are installed: :data:`sys.prefix`." +msgstr "" + +#: ../../c-api/init_config.rst:1735 +msgid "See also :c:member:`PyConfig.base_prefix`." +msgstr "也請見 :c:member:`PyConfig.base_prefix`" + +#: ../../c-api/init_config.rst:1739 +msgid "" +"Program name used to initialize :c:member:`~PyConfig.executable` and in " +"early error messages during Python initialization." +msgstr "" + +#: ../../c-api/init_config.rst:1742 +msgid "On macOS, use :envvar:`PYTHONEXECUTABLE` environment variable if set." +msgstr "" + +#: ../../c-api/init_config.rst:1743 +msgid "" +"If the ``WITH_NEXT_FRAMEWORK`` macro is defined, use :envvar:" +"`__PYVENV_LAUNCHER__` environment variable if set." +msgstr "" + +#: ../../c-api/init_config.rst:1745 +msgid "" +"Use ``argv[0]`` of :c:member:`~PyConfig.argv` if available and non-empty." +msgstr "" + +#: ../../c-api/init_config.rst:1747 +msgid "" +"Otherwise, use ``L\"python\"`` on Windows, or ``L\"python3\"`` on other " +"platforms." +msgstr "" + +#: ../../c-api/init_config.rst:1756 +msgid "" +"Directory where cached ``.pyc`` files are written: :data:`sys." +"pycache_prefix`." +msgstr "" + +#: ../../c-api/init_config.rst:1759 +msgid "" +"Set by the :option:`-X pycache_prefix=PATH <-X>` command line option and " +"the :envvar:`PYTHONPYCACHEPREFIX` environment variable. The command-line " +"option takes precedence." +msgstr "" + +#: ../../c-api/init_config.rst:1763 +msgid "If ``NULL``, :data:`sys.pycache_prefix` is set to ``None``." +msgstr "" + +#: ../../c-api/init_config.rst:1769 +msgid "" +"Quiet mode. If greater than ``0``, don't display the copyright and version " +"at Python startup in interactive mode." +msgstr "" + +#: ../../c-api/init_config.rst:1772 +msgid "Incremented by the :option:`-q` command line option." +msgstr "" + +#: ../../c-api/init_config.rst:1778 +msgid "Value of the :option:`-c` command line option." +msgstr "" + +#: ../../c-api/init_config.rst:1780 ../../c-api/init_config.rst:1801 +msgid "Used by :c:func:`Py_RunMain`." +msgstr "被 :c:func:`Py_RunMain` 使用。" + +#: ../../c-api/init_config.rst:1786 +msgid "" +"Filename passed on the command line: trailing command line argument without :" +"option:`-c` or :option:`-m`. It is used by the :c:func:`Py_RunMain` function." +msgstr "" + +#: ../../c-api/init_config.rst:1790 +msgid "" +"For example, it is set to ``script.py`` by the ``python3 script.py arg`` " +"command line." +msgstr "" + +#: ../../c-api/init_config.rst:1793 +msgid "See also the :c:member:`PyConfig.skip_source_first_line` option." +msgstr "也請見 :c:member:`PyConfig.skip_source_first_line` 選項。" + +#: ../../c-api/init_config.rst:1799 +msgid "Value of the :option:`-m` command line option." +msgstr "" + +#: ../../c-api/init_config.rst:1807 +msgid "" +"``package.module`` path to module that should be imported before ``site.py`` " +"is run." +msgstr "" + +#: ../../c-api/init_config.rst:1810 +msgid "" +"Set by the :option:`-X presite=package.module <-X>` command-line option and " +"the :envvar:`PYTHON_PRESITE` environment variable. The command-line option " +"takes precedence." +msgstr "" + +#: ../../c-api/init_config.rst:1821 +msgid "" +"Show total reference count at exit (excluding :term:`immortal` objects)?" +msgstr "" + +#: ../../c-api/init_config.rst:1823 +msgid "Set to ``1`` by :option:`-X showrefcount <-X>` command line option." +msgstr "" + +#: ../../c-api/init_config.rst:1825 +msgid "" +"Needs a :ref:`debug build of Python ` (the ``Py_REF_DEBUG`` " +"macro must be defined)." +msgstr "" + +#: ../../c-api/init_config.rst:1832 +msgid "Import the :mod:`site` module at startup?" +msgstr "" + +#: ../../c-api/init_config.rst:1834 +msgid "" +"If equal to zero, disable the import of the module site and the site-" +"dependent manipulations of :data:`sys.path` that it entails." +msgstr "" + +#: ../../c-api/init_config.rst:1837 +msgid "" +"Also disable these manipulations if the :mod:`site` module is explicitly " +"imported later (call :func:`site.main` if you want them to be triggered)." +msgstr "" + +#: ../../c-api/init_config.rst:1840 +msgid "Set to ``0`` by the :option:`-S` command line option." +msgstr "" + +#: ../../c-api/init_config.rst:1842 +msgid "" +":data:`sys.flags.no_site ` is set to the inverted value of :c:" +"member:`~PyConfig.site_import`." +msgstr "" + +#: ../../c-api/init_config.rst:1849 +msgid "" +"If non-zero, skip the first line of the :c:member:`PyConfig.run_filename` " +"source." +msgstr "" + +#: ../../c-api/init_config.rst:1852 +msgid "" +"It allows the usage of non-Unix forms of ``#!cmd``. This is intended for a " +"DOS specific hack only." +msgstr "" + +#: ../../c-api/init_config.rst:1855 +msgid "Set to ``1`` by the :option:`-x` command line option." +msgstr "" + +#: ../../c-api/init_config.rst:1862 +msgid "" +"Encoding and encoding errors of :data:`sys.stdin`, :data:`sys.stdout` and :" +"data:`sys.stderr` (but :data:`sys.stderr` always uses " +"``\"backslashreplace\"`` error handler)." +msgstr "" + +#: ../../c-api/init_config.rst:1866 +msgid "" +"Use the :envvar:`PYTHONIOENCODING` environment variable if it is non-empty." +msgstr "" + +#: ../../c-api/init_config.rst:1869 +msgid "Default encoding:" +msgstr "預設編碼：" + +#: ../../c-api/init_config.rst:1871 +msgid "``\"UTF-8\"`` if :c:member:`PyPreConfig.utf8_mode` is non-zero." +msgstr "如果 :c:member:`PyPreConfig.utf8_mode` 非零，則為 ``\"UTF-8\"``。" + +#: ../../c-api/init_config.rst:1872 +msgid "Otherwise, use the :term:`locale encoding`." +msgstr "否則使用 :term:`locale encoding`。" + +#: ../../c-api/init_config.rst:1874 +msgid "Default error handler:" +msgstr "" + +#: ../../c-api/init_config.rst:1876 +msgid "On Windows: use ``\"surrogateescape\"``." +msgstr "在 Windows 上：使用 ``\"surrogateescape\"``。" + +#: ../../c-api/init_config.rst:1877 +msgid "" +"``\"surrogateescape\"`` if :c:member:`PyPreConfig.utf8_mode` is non-zero, or " +"if the LC_CTYPE locale is \"C\" or \"POSIX\"." +msgstr "" + +#: ../../c-api/init_config.rst:1879 +msgid "``\"strict\"`` otherwise." +msgstr "" + +#: ../../c-api/init_config.rst:1881 +msgid "See also :c:member:`PyConfig.legacy_windows_stdio`." +msgstr "也請見 :c:member:`PyConfig.legacy_windows_stdio`。" + +#: ../../c-api/init_config.rst:1885 +msgid "Enable tracemalloc?" +msgstr "" + +#: ../../c-api/init_config.rst:1887 +msgid "If non-zero, call :func:`tracemalloc.start` at startup." +msgstr "" + +#: ../../c-api/init_config.rst:1889 +msgid "" +"Set by :option:`-X tracemalloc=N <-X>` command line option and by the :" +"envvar:`PYTHONTRACEMALLOC` environment variable." +msgstr "" + +#: ../../c-api/init_config.rst:1896 +msgid "Enable the Linux ``perf`` profiler support?" +msgstr "要啟用 Linux ``perf`` 分析器支援嗎？" + +#: ../../c-api/init_config.rst:1898 +msgid "If equals to ``1``, enable support for the Linux ``perf`` profiler." +msgstr "如果等於 ``1``，則啟用對 Linux ``perf`` 分析器的支援。" + +#: ../../c-api/init_config.rst:1900 +msgid "" +"If equals to ``2``, enable support for the Linux ``perf`` profiler with " +"DWARF JIT support." +msgstr "" +"如果等於 ``2``，則啟用有 DWARF JIT 支援的 Linux ``perf`` 分析器的支援。" + +#: ../../c-api/init_config.rst:1903 +msgid "" +"Set to ``1`` by :option:`-X perf <-X>` command-line option and the :envvar:" +"`PYTHONPERFSUPPORT` environment variable." +msgstr "" + +#: ../../c-api/init_config.rst:1906 +msgid "" +"Set to ``2`` by the :option:`-X perf_jit <-X>` command-line option and the :" +"envvar:`PYTHON_PERF_JIT_SUPPORT` environment variable." +msgstr "" + +#: ../../c-api/init_config.rst:1912 +msgid "See :ref:`perf_profiling` for more information." +msgstr "更多資訊請參見 :ref:`perf_profiling`。" + +#: ../../c-api/init_config.rst:1918 +msgid "Directory of the Python standard library." +msgstr "" + +#: ../../c-api/init_config.rst:1926 +msgid "Use :ref:`environment variables `?" +msgstr "" + +#: ../../c-api/init_config.rst:1928 +msgid "" +"If equals to zero, ignore the :ref:`environment variables `." +msgstr "" + +#: ../../c-api/init_config.rst:1931 +msgid "Set to ``0`` by the :option:`-E` environment variable." +msgstr "" + +#: ../../c-api/init_config.rst:1937 +msgid "" +"If non-zero, ``stdout`` and ``stderr`` will be redirected to the system log." +msgstr "" + +#: ../../c-api/init_config.rst:1940 +msgid "Only available on macOS 10.12 and later, and on iOS." +msgstr "" + +#: ../../c-api/init_config.rst:1942 +msgid "" +"Default: ``0`` (don't use the system log) on macOS; ``1`` on iOS (use the " +"system log)." +msgstr "" + +#: ../../c-api/init_config.rst:1949 +msgid "If non-zero, add the user site directory to :data:`sys.path`." +msgstr "" + +#: ../../c-api/init_config.rst:1951 +msgid "Set to ``0`` by the :option:`-s` and :option:`-I` command line options." +msgstr "" + +#: ../../c-api/init_config.rst:1953 +msgid "Set to ``0`` by the :envvar:`PYTHONNOUSERSITE` environment variable." +msgstr "" + +#: ../../c-api/init_config.rst:1959 +msgid "" +"Verbose mode. If greater than ``0``, print a message each time a module is " +"imported, showing the place (filename or built-in module) from which it is " +"loaded." +msgstr "" + +#: ../../c-api/init_config.rst:1963 +msgid "" +"If greater than or equal to ``2``, print a message for each file that is " +"checked for when searching for a module. Also provides information on module " +"cleanup at exit." +msgstr "" + +#: ../../c-api/init_config.rst:1967 +msgid "Incremented by the :option:`-v` command line option." +msgstr "" + +#: ../../c-api/init_config.rst:1969 +msgid "Set by the :envvar:`PYTHONVERBOSE` environment variable value." +msgstr "" + +#: ../../c-api/init_config.rst:1975 +msgid "" +"Options of the :mod:`warnings` module to build warnings filters, lowest to " +"highest priority: :data:`sys.warnoptions`." +msgstr "" + +#: ../../c-api/init_config.rst:1978 +msgid "" +"The :mod:`warnings` module adds :data:`sys.warnoptions` in the reverse " +"order: the last :c:member:`PyConfig.warnoptions` item becomes the first item " +"of :data:`warnings.filters` which is checked first (highest priority)." +msgstr "" + +#: ../../c-api/init_config.rst:1983 +msgid "" +"The :option:`-W` command line options adds its value to :c:member:`~PyConfig." +"warnoptions`, it can be used multiple times." +msgstr "" + +#: ../../c-api/init_config.rst:1986 +msgid "" +"The :envvar:`PYTHONWARNINGS` environment variable can also be used to add " +"warning options. Multiple options can be specified, separated by commas (``," +"``)." +msgstr "" + +#: ../../c-api/init_config.rst:1994 +msgid "" +"If equal to ``0``, Python won't try to write ``.pyc`` files on the import of " +"source modules." +msgstr "" + +#: ../../c-api/init_config.rst:1997 +msgid "" +"Set to ``0`` by the :option:`-B` command line option and the :envvar:" +"`PYTHONDONTWRITEBYTECODE` environment variable." +msgstr "" + +#: ../../c-api/init_config.rst:2000 +msgid "" +":data:`sys.dont_write_bytecode` is initialized to the inverted value of :c:" +"member:`~PyConfig.write_bytecode`." +msgstr "" + +#: ../../c-api/init_config.rst:2007 +msgid "Values of the :option:`-X` command line options: :data:`sys._xoptions`." +msgstr "" + +#: ../../c-api/init_config.rst:2013 +msgid "If non-zero, write performance statistics at Python exit." +msgstr "" + +#: ../../c-api/init_config.rst:2015 +msgid "" +"Need a special build with the ``Py_STATS`` macro: see :option:`--enable-" +"pystats`." +msgstr "" + +#: ../../c-api/init_config.rst:2020 +msgid "" +"If :c:member:`~PyConfig.parse_argv` is non-zero, :c:member:`~PyConfig.argv` " +"arguments are parsed the same way the regular Python parses :ref:`command " +"line arguments `, and Python arguments are stripped from :" +"c:member:`~PyConfig.argv`." +msgstr "" + +#: ../../c-api/init_config.rst:2025 +msgid "" +"The :c:member:`~PyConfig.xoptions` options are parsed to set other options: " +"see the :option:`-X` command line option." +msgstr "" + +#: ../../c-api/init_config.rst:2030 +msgid "The ``show_alloc_count`` field has been removed." +msgstr "" + +#: ../../c-api/init_config.rst:2036 +msgid "Initialization with PyConfig" +msgstr "" + +#: ../../c-api/init_config.rst:2038 +msgid "" +"Initializing the interpreter from a populated configuration struct is " +"handled by calling :c:func:`Py_InitializeFromConfig`." +msgstr "" + +#: ../../c-api/init_config.rst:2044 +msgid "" +"If :c:func:`PyImport_FrozenModules`, :c:func:`PyImport_AppendInittab` or :c:" +"func:`PyImport_ExtendInittab` are used, they must be set or called after " +"Python preinitialization and before the Python initialization. If Python is " +"initialized multiple times, :c:func:`PyImport_AppendInittab` or :c:func:" +"`PyImport_ExtendInittab` must be called before each Python initialization." +msgstr "" + +#: ../../c-api/init_config.rst:2051 +msgid "" +"The current configuration (``PyConfig`` type) is stored in " +"``PyInterpreterState.config``." +msgstr "" + +#: ../../c-api/init_config.rst:2054 +msgid "Example setting the program name::" +msgstr "" + +#: ../../c-api/init_config.rst:2056 +msgid "" +"void init_python(void)\n" +"{\n" +" PyStatus status;\n" +"\n" +" PyConfig config;\n" +" PyConfig_InitPythonConfig(&config);\n" +"\n" +" /* Set the program name. Implicitly preinitialize Python. */\n" +" status = PyConfig_SetString(&config, &config.program_name,\n" +" L\"/path/to/my_program\");\n" +" if (PyStatus_Exception(status)) {\n" +" goto exception;\n" +" }\n" +"\n" +" status = Py_InitializeFromConfig(&config);\n" +" if (PyStatus_Exception(status)) {\n" +" goto exception;\n" +" }\n" +" PyConfig_Clear(&config);\n" +" return;\n" +"\n" +"exception:\n" +" PyConfig_Clear(&config);\n" +" Py_ExitStatusException(status);\n" +"}" +msgstr "" +"void init_python(void)\n" +"{\n" +" PyStatus status;\n" +"\n" +" PyConfig config;\n" +" PyConfig_InitPythonConfig(&config);\n" +"\n" +" /* Set the program name. Implicitly preinitialize Python. */\n" +" status = PyConfig_SetString(&config, &config.program_name,\n" +" L\"/path/to/my_program\");\n" +" if (PyStatus_Exception(status)) {\n" +" goto exception;\n" +" }\n" +"\n" +" status = Py_InitializeFromConfig(&config);\n" +" if (PyStatus_Exception(status)) {\n" +" goto exception;\n" +" }\n" +" PyConfig_Clear(&config);\n" +" return;\n" +"\n" +"exception:\n" +" PyConfig_Clear(&config);\n" +" Py_ExitStatusException(status);\n" +"}" + +#: ../../c-api/init_config.rst:2082 +msgid "" +"More complete example modifying the default configuration, read the " +"configuration, and then override some parameters. Note that since 3.11, many " +"parameters are not calculated until initialization, and so values cannot be " +"read from the configuration structure. Any values set before initialize is " +"called will be left unchanged by initialization::" +msgstr "" + +#: ../../c-api/init_config.rst:2089 +msgid "" +"PyStatus init_python(const char *program_name)\n" +"{\n" +" PyStatus status;\n" +"\n" +" PyConfig config;\n" +" PyConfig_InitPythonConfig(&config);\n" +"\n" +" /* Set the program name before reading the configuration\n" +" (decode byte string from the locale encoding).\n" +"\n" +" Implicitly preinitialize Python. */\n" +" status = PyConfig_SetBytesString(&config, &config.program_name,\n" +" program_name);\n" +" if (PyStatus_Exception(status)) {\n" +" goto done;\n" +" }\n" +"\n" +" /* Read all configuration at once */\n" +" status = PyConfig_Read(&config);\n" +" if (PyStatus_Exception(status)) {\n" +" goto done;\n" +" }\n" +"\n" +" /* Specify sys.path explicitly */\n" +" /* If you want to modify the default set of paths, finish\n" +" initialization first and then use PySys_GetObject(\"path\") */\n" +" config.module_search_paths_set = 1;\n" +" status = PyWideStringList_Append(&config.module_search_paths,\n" +" L\"/path/to/stdlib\");\n" +" if (PyStatus_Exception(status)) {\n" +" goto done;\n" +" }\n" +" status = PyWideStringList_Append(&config.module_search_paths,\n" +" L\"/path/to/more/modules\");\n" +" if (PyStatus_Exception(status)) {\n" +" goto done;\n" +" }\n" +"\n" +" /* Override executable computed by PyConfig_Read() */\n" +" status = PyConfig_SetString(&config, &config.executable,\n" +" L\"/path/to/my_executable\");\n" +" if (PyStatus_Exception(status)) {\n" +" goto done;\n" +" }\n" +"\n" +" status = Py_InitializeFromConfig(&config);\n" +"\n" +"done:\n" +" PyConfig_Clear(&config);\n" +" return status;\n" +"}" +msgstr "" + +#: ../../c-api/init_config.rst:2145 +msgid "Isolated Configuration" +msgstr "" + +#: ../../c-api/init_config.rst:2147 +msgid "" +":c:func:`PyPreConfig_InitIsolatedConfig` and :c:func:" +"`PyConfig_InitIsolatedConfig` functions create a configuration to isolate " +"Python from the system. For example, to embed Python into an application." +msgstr "" + +#: ../../c-api/init_config.rst:2152 +msgid "" +"This configuration ignores global configuration variables, environment " +"variables, command line arguments (:c:member:`PyConfig.argv` is not parsed) " +"and user site directory. The C standard streams (ex: ``stdout``) and the " +"LC_CTYPE locale are left unchanged. Signal handlers are not installed." +msgstr "" + +#: ../../c-api/init_config.rst:2157 +msgid "" +"Configuration files are still used with this configuration to determine " +"paths that are unspecified. Ensure :c:member:`PyConfig.home` is specified to " +"avoid computing the default path configuration." +msgstr "" + +#: ../../c-api/init_config.rst:2165 +msgid "Python Configuration" +msgstr "" + +#: ../../c-api/init_config.rst:2167 +msgid "" +":c:func:`PyPreConfig_InitPythonConfig` and :c:func:" +"`PyConfig_InitPythonConfig` functions create a configuration to build a " +"customized Python which behaves as the regular Python." +msgstr "" + +#: ../../c-api/init_config.rst:2171 +msgid "" +"Environments variables and command line arguments are used to configure " +"Python, whereas global configuration variables are ignored." +msgstr "" + +#: ../../c-api/init_config.rst:2174 +msgid "" +"This function enables C locale coercion (:pep:`538`) and :ref:`Python UTF-8 " +"Mode ` (:pep:`540`) depending on the LC_CTYPE locale, :envvar:" +"`PYTHONUTF8` and :envvar:`PYTHONCOERCECLOCALE` environment variables." +msgstr "" + +#: ../../c-api/init_config.rst:2183 +msgid "Python Path Configuration" +msgstr "Python 路徑配置" + +#: ../../c-api/init_config.rst:2185 +msgid ":c:type:`PyConfig` contains multiple fields for the path configuration:" +msgstr "" + +#: ../../c-api/init_config.rst:2187 +msgid "Path configuration inputs:" +msgstr "" + +#: ../../c-api/init_config.rst:2189 +msgid ":c:member:`PyConfig.home`" +msgstr ":c:member:`PyConfig.home`" + +#: ../../c-api/init_config.rst:2190 +msgid ":c:member:`PyConfig.platlibdir`" +msgstr ":c:member:`PyConfig.platlibdir`" + +#: ../../c-api/init_config.rst:2191 +msgid ":c:member:`PyConfig.pathconfig_warnings`" +msgstr ":c:member:`PyConfig.pathconfig_warnings`" + +#: ../../c-api/init_config.rst:2192 +msgid ":c:member:`PyConfig.program_name`" +msgstr ":c:member:`PyConfig.program_name`" + +#: ../../c-api/init_config.rst:2193 +msgid ":c:member:`PyConfig.pythonpath_env`" +msgstr ":c:member:`PyConfig.pythonpath_env`" + +#: ../../c-api/init_config.rst:2194 +msgid "current working directory: to get absolute paths" +msgstr "" + +#: ../../c-api/init_config.rst:2195 +msgid "" +"``PATH`` environment variable to get the program full path (from :c:member:" +"`PyConfig.program_name`)" +msgstr "" + +#: ../../c-api/init_config.rst:2197 +msgid "``__PYVENV_LAUNCHER__`` environment variable" +msgstr "``__PYVENV_LAUNCHER__`` 環境變數" + +#: ../../c-api/init_config.rst:2198 +msgid "" +"(Windows only) Application paths in the registry under " +"\"Software\\Python\\PythonCore\\X.Y\\PythonPath\" of HKEY_CURRENT_USER and " +"HKEY_LOCAL_MACHINE (where X.Y is the Python version)." +msgstr "" + +#: ../../c-api/init_config.rst:2202 +msgid "Path configuration output fields:" +msgstr "" + +#: ../../c-api/init_config.rst:2204 +msgid ":c:member:`PyConfig.base_exec_prefix`" +msgstr ":c:member:`PyConfig.base_exec_prefix`" + +#: ../../c-api/init_config.rst:2205 +msgid ":c:member:`PyConfig.base_executable`" +msgstr ":c:member:`PyConfig.base_executable`" + +#: ../../c-api/init_config.rst:2206 +msgid ":c:member:`PyConfig.base_prefix`" +msgstr ":c:member:`PyConfig.base_prefix`" + +#: ../../c-api/init_config.rst:2207 +msgid ":c:member:`PyConfig.exec_prefix`" +msgstr ":c:member:`PyConfig.exec_prefix`" + +#: ../../c-api/init_config.rst:2208 +msgid ":c:member:`PyConfig.executable`" +msgstr ":c:member:`PyConfig.executable`" + +#: ../../c-api/init_config.rst:2209 +msgid "" +":c:member:`PyConfig.module_search_paths_set`, :c:member:`PyConfig." +"module_search_paths`" +msgstr "" +":c:member:`PyConfig.module_search_paths_set`, :c:member:`PyConfig." +"module_search_paths`" + +#: ../../c-api/init_config.rst:2211 +msgid ":c:member:`PyConfig.prefix`" +msgstr ":c:member:`PyConfig.prefix`" + +#: ../../c-api/init_config.rst:2213 +msgid "" +"If at least one \"output field\" is not set, Python calculates the path " +"configuration to fill unset fields. If :c:member:`~PyConfig." +"module_search_paths_set` is equal to ``0``, :c:member:`~PyConfig." +"module_search_paths` is overridden and :c:member:`~PyConfig." +"module_search_paths_set` is set to ``1``." +msgstr "" + +#: ../../c-api/init_config.rst:2219 +msgid "" +"It is possible to completely ignore the function calculating the default " +"path configuration by setting explicitly all path configuration output " +"fields listed above. A string is considered as set even if it is non-empty. " +"``module_search_paths`` is considered as set if ``module_search_paths_set`` " +"is set to ``1``. In this case, ``module_search_paths`` will be used without " +"modification." +msgstr "" + +#: ../../c-api/init_config.rst:2226 +msgid "" +"Set :c:member:`~PyConfig.pathconfig_warnings` to ``0`` to suppress warnings " +"when calculating the path configuration (Unix only, Windows does not log any " +"warning)." +msgstr "" + +#: ../../c-api/init_config.rst:2229 +msgid "" +"If :c:member:`~PyConfig.base_prefix` or :c:member:`~PyConfig." +"base_exec_prefix` fields are not set, they inherit their value from :c:" +"member:`~PyConfig.prefix` and :c:member:`~PyConfig.exec_prefix` respectively." +msgstr "" + +#: ../../c-api/init_config.rst:2233 +msgid ":c:func:`Py_RunMain` and :c:func:`Py_Main` modify :data:`sys.path`:" +msgstr ":c:func:`Py_RunMain` 和 :c:func:`Py_Main` 會修改 :data:`sys.path`：" + +#: ../../c-api/init_config.rst:2235 +msgid "" +"If :c:member:`~PyConfig.run_filename` is set and is a directory which " +"contains a ``__main__.py`` script, prepend :c:member:`~PyConfig." +"run_filename` to :data:`sys.path`." +msgstr "" + +#: ../../c-api/init_config.rst:2238 +msgid "If :c:member:`~PyConfig.isolated` is zero:" +msgstr "如果 :c:member:`~PyConfig.isolated` 為零：" + +#: ../../c-api/init_config.rst:2240 +msgid "" +"If :c:member:`~PyConfig.run_module` is set, prepend the current directory " +"to :data:`sys.path`. Do nothing if the current directory cannot be read." +msgstr "" + +#: ../../c-api/init_config.rst:2242 +msgid "" +"If :c:member:`~PyConfig.run_filename` is set, prepend the directory of the " +"filename to :data:`sys.path`." +msgstr "" + +#: ../../c-api/init_config.rst:2244 +msgid "Otherwise, prepend an empty string to :data:`sys.path`." +msgstr "" + +#: ../../c-api/init_config.rst:2246 +msgid "" +"If :c:member:`~PyConfig.site_import` is non-zero, :data:`sys.path` can be " +"modified by the :mod:`site` module. If :c:member:`~PyConfig." +"user_site_directory` is non-zero and the user's site-package directory " +"exists, the :mod:`site` module appends the user's site-package directory to :" +"data:`sys.path`." +msgstr "" + +#: ../../c-api/init_config.rst:2252 +msgid "The following configuration files are used by the path configuration:" +msgstr "" + +#: ../../c-api/init_config.rst:2254 +msgid "``pyvenv.cfg``" +msgstr "``pyvenv.cfg``" + +#: ../../c-api/init_config.rst:2255 +msgid "``._pth`` file (ex: ``python._pth``)" +msgstr "" + +#: ../../c-api/init_config.rst:2256 +msgid "``pybuilddir.txt`` (Unix only)" +msgstr "``pybuilddir.txt``\\ （僅限 Unix）" + +#: ../../c-api/init_config.rst:2258 +msgid "If a ``._pth`` file is present:" +msgstr "" + +#: ../../c-api/init_config.rst:2260 +msgid "Set :c:member:`~PyConfig.isolated` to ``1``." +msgstr "將 :c:member:`~PyConfig.isolated` 設定為 ``1``。" + +#: ../../c-api/init_config.rst:2261 +msgid "Set :c:member:`~PyConfig.use_environment` to ``0``." +msgstr "將 :c:member:`~PyConfig.use_environment` 設定為 ``0``。" + +#: ../../c-api/init_config.rst:2262 +msgid "Set :c:member:`~PyConfig.site_import` to ``0``." +msgstr "將 :c:member:`~PyConfig.site_import` 設定為 ``0``。" + +#: ../../c-api/init_config.rst:2263 +msgid "Set :c:member:`~PyConfig.safe_path` to ``1``." +msgstr "將 :c:member:`~PyConfig.safe_path` 設定為 ``1``。" + +#: ../../c-api/init_config.rst:2265 +msgid "" +"If :c:member:`~PyConfig.home` is not set and a ``pyvenv.cfg`` file is " +"present in the same directory as :c:member:`~PyConfig.executable`, or its " +"parent, :c:member:`~PyConfig.prefix` and :c:member:`~PyConfig.exec_prefix` " +"are set that location. When this happens, :c:member:`~PyConfig.base_prefix` " +"and :c:member:`~PyConfig.base_exec_prefix` still keep their value, pointing " +"to the base installation. See :ref:`sys-path-init-virtual-environments` for " +"more information." +msgstr "" + +#: ../../c-api/init_config.rst:2273 +msgid "" +"The ``__PYVENV_LAUNCHER__`` environment variable is used to set :c:member:" +"`PyConfig.base_executable`." +msgstr "" + +#: ../../c-api/init_config.rst:2278 +msgid "" +":c:member:`~PyConfig.prefix`, and :c:member:`~PyConfig.exec_prefix`, are now " +"set to the ``pyvenv.cfg`` directory. This was previously done by :mod:" +"`site`, therefore affected by :option:`-S`." +msgstr "" + +#: ../../c-api/init_config.rst:2284 +msgid "Py_GetArgcArgv()" +msgstr "Py_GetArgcArgv()" + +#: ../../c-api/init_config.rst:2288 +msgid "Get the original command line arguments, before Python modified them." +msgstr "" + +#: ../../c-api/init_config.rst:2290 +msgid "See also :c:member:`PyConfig.orig_argv` member." +msgstr "也請參與 :c:member:`PyConfig.orig_argv` 成員。" + +#: ../../c-api/init_config.rst:2293 +msgid "Delaying main module execution" +msgstr "" + +#: ../../c-api/init_config.rst:2295 +msgid "" +"In some embedding use cases, it may be desirable to separate interpreter " +"initialization from the execution of the main module." +msgstr "" + +#: ../../c-api/init_config.rst:2298 +msgid "" +"This separation can be achieved by setting ``PyConfig.run_command`` to the " +"empty string during initialization (to prevent the interpreter from dropping " +"into the interactive prompt), and then subsequently executing the desired " +"main module code using ``__main__.__dict__`` as the global namespace." +msgstr "" + +#: ../../c-api/init_config.rst:1181 +msgid "main()" +msgstr "main()" + +#: ../../c-api/init_config.rst:1181 +msgid "argv (in module sys)" +msgstr "" diff --git a/c-api/intro.po b/c-api/intro.po index 1e160f1bda..19ba0730d0 100644 --- a/c-api/intro.po +++ b/c-api/intro.po @@ -1,1659 +1,1659 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Matt Wang , 2023 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-25 00:13+0000\n" -"PO-Revision-Date: 2023-04-25 18:01+0800\n" -"Last-Translator: Matt Wang \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" -"X-Generator: Poedit 3.2.2\n" - -#: ../../c-api/intro.rst:8 -msgid "Introduction" -msgstr "簡介" - -#: ../../c-api/intro.rst:10 -msgid "" -"The Application Programmer's Interface to Python gives C and C++ programmers " -"access to the Python interpreter at a variety of levels. The API is equally " -"usable from C++, but for brevity it is generally referred to as the Python/C " -"API. There are two fundamentally different reasons for using the Python/C " -"API. The first reason is to write *extension modules* for specific purposes; " -"these are C modules that extend the Python interpreter. This is probably " -"the most common use. The second reason is to use Python as a component in a " -"larger application; this technique is generally referred to as :dfn:" -"`embedding` Python in an application." -msgstr "" -"對於 Python 的應用程式開發介面使得 C 和 C++ 開發者能夠在各種層級存取 Python " -"直譯器。該 API 同樣可用於 C++，但為簡潔起見，通常將其稱為 Python/C API。使用 " -"Python/C API 有兩個不同的原因，第一個是為特定目的來編寫\\ *擴充模組*；這些是" -"擴充 Python 直譯器的 C 模組，這可能是最常見的用法。第二個原因是在更大的應用程" -"式中將 Python 作為零件使用；這種技術通常在應用程式中稱為 :dfn:`embedding`\\ " -"（嵌入式）Python。" - -#: ../../c-api/intro.rst:20 -msgid "" -"Writing an extension module is a relatively well-understood process, where a " -"\"cookbook\" approach works well. There are several tools that automate the " -"process to some extent. While people have embedded Python in other " -"applications since its early existence, the process of embedding Python is " -"less straightforward than writing an extension." -msgstr "" -"編寫擴充模組是一個相對容易理解的過程，其中「食譜 (cookbook)」方法很有效。有幾" -"種工具可以在一定程度上自動化該過程，儘管人們從早期就將 Python 嵌入到其他應用" -"程式中，但嵌入 Python 的過程並不像編寫擴充那樣簡單。" - -#: ../../c-api/intro.rst:26 -msgid "" -"Many API functions are useful independent of whether you're embedding or " -"extending Python; moreover, most applications that embed Python will need " -"to provide a custom extension as well, so it's probably a good idea to " -"become familiar with writing an extension before attempting to embed Python " -"in a real application." -msgstr "" -"不論你是嵌入還是擴充 Python，許多 API 函式都是很有用的；此外，大多數嵌入 " -"Python 的應用程式也需要提供自訂擴充模組，因此在嘗試將 Python 嵌入實際應用程" -"式之前熟悉編寫擴充可能是個好主意。" - -#: ../../c-api/intro.rst:34 -msgid "Language version compatibility" -msgstr "語言版本相容性" - -#: ../../c-api/intro.rst:36 -msgid "Python's C API is compatible with C11 and C++11 versions of C and C++." -msgstr "Python 的 C API 與 C11 和 C++11 版本的 C 和 C++ 相容。" - -#: ../../c-api/intro.rst:38 -msgid "" -"This is a lower limit: the C API does not require features from later C/C++ " -"versions. You do *not* need to enable your compiler's \"c11 mode\"." -msgstr "" - -#: ../../c-api/intro.rst:44 -msgid "Coding standards" -msgstr "編寫標準" - -#: ../../c-api/intro.rst:46 -msgid "" -"If you're writing C code for inclusion in CPython, you **must** follow the " -"guidelines and standards defined in :PEP:`7`. These guidelines apply " -"regardless of the version of Python you are contributing to. Following " -"these conventions is not necessary for your own third party extension " -"modules, unless you eventually expect to contribute them to Python." -msgstr "" -"如果你正在編寫要引入於 CPython 中的 C 程式碼，你\\ **必須**\\ 遵循 :PEP:`7` " -"中定義的指南和標準。無論你貢獻的 Python 版本如何，這些指南都適用。對於你自己" -"的第三方擴充模組，則不必遵循這些約定，除非你希望最終將它們貢獻給 Python。" - -#: ../../c-api/intro.rst:56 -msgid "Include Files" -msgstr "引入檔案 (include files)" - -#: ../../c-api/intro.rst:58 -msgid "" -"All function, type and macro definitions needed to use the Python/C API are " -"included in your code by the following line::" -msgstr "" -"使用 Python/C API 所需的所有函式、型別和巨集的定義都透過以下這幾行來在你的程" -"式碼中引入：" - -#: ../../c-api/intro.rst:61 -msgid "" -"#define PY_SSIZE_T_CLEAN\n" -"#include " -msgstr "" -"#define PY_SSIZE_T_CLEAN\n" -"#include " - -#: ../../c-api/intro.rst:64 -msgid "" -"This implies inclusion of the following standard headers: ````, " -"````, ````, ````, ```` and ```` (if available)." -msgstr "" -"這意味著會引入以下標準標頭：````、````、````、" -"````、```` 和 ````\\ （如果可用）。" - -#: ../../c-api/intro.rst:70 -msgid "" -"Since Python may define some pre-processor definitions which affect the " -"standard headers on some systems, you *must* include :file:`Python.h` before " -"any standard headers are included." -msgstr "" -"由於 Python 可能會定義一些會影響某些系統上標準標頭檔的預處理器 (pre-" -"processor)，因此你\\ *必須*\\ 在引入任何標準標頭檔之前引入 :file:`Python.h`。" - -#: ../../c-api/intro.rst:74 -msgid "" -"It is recommended to always define ``PY_SSIZE_T_CLEAN`` before including " -"``Python.h``. See :ref:`arg-parsing` for a description of this macro." -msgstr "" -"建議在引入 ``Python.h`` 之前都要定義 ``PY_SSIZE_T_CLEAN``。有關此巨集的說明，" -"請參閱\\ :ref:`arg-parsing`。" - -#: ../../c-api/intro.rst:77 -msgid "" -"All user visible names defined by Python.h (except those defined by the " -"included standard headers) have one of the prefixes ``Py`` or ``_Py``. " -"Names beginning with ``_Py`` are for internal use by the Python " -"implementation and should not be used by extension writers. Structure member " -"names do not have a reserved prefix." -msgstr "" -"所有定義於 Python.h 中且使用者可見的名稱（另外透過標準標頭檔引入的除外）都具" -"有 ``Py`` 或 ``_Py`` 前綴。以 ``_Py`` 開頭的名稱供 Python 實作內部使用，擴充" -"編寫者不應使用。結構成員名稱沒有保留前綴。" - -#: ../../c-api/intro.rst:84 -msgid "" -"User code should never define names that begin with ``Py`` or ``_Py``. This " -"confuses the reader, and jeopardizes the portability of the user code to " -"future Python versions, which may define additional names beginning with one " -"of these prefixes." -msgstr "" -"使用者程式碼不應定義任何以 ``Py`` 或 ``_Py`` 開頭的名稱。這會讓讀者感到困惑，" -"並危及使用者程式碼在未來 Python 版本上的可移植性，這些版本可能會定義以這些前" -"綴之一開頭的其他名稱。" - -#: ../../c-api/intro.rst:89 -msgid "" -"The header files are typically installed with Python. On Unix, these are " -"located in the directories :file:`{prefix}/include/pythonversion/` and :file:" -"`{exec_prefix}/include/pythonversion/`, where :option:`prefix <--prefix>` " -"and :option:`exec_prefix <--exec-prefix>` are defined by the corresponding " -"parameters to Python's :program:`configure` script and *version* is ``'%d." -"%d' % sys.version_info[:2]``. On Windows, the headers are installed in :" -"file:`{prefix}/include`, where ``prefix`` is the installation directory " -"specified to the installer." -msgstr "" -"標頭檔通常隨 Python 一起安裝。在 Unix 上它們位於目錄 :file:`{prefix}/include/" -"pythonversion/` 和 :file:`{exec_prefix}/include/pythonversion/`，其中 :" -"option:`prefix <--prefix>` 和 :option:`exec_prefix <--exec-prefix>` 由 " -"Python 的 :program:`configure` 腳本的相應參數定義，*version* 是 ``'%d.%d' % " -"sys.version_info[:2]``。在 Windows 上，標頭安裝在 :file:`{prefix}/include` " -"中，其中 ``prefix`` 是指定給安裝程式 (installer) 用的安裝目錄。" - -#: ../../c-api/intro.rst:98 -msgid "" -"To include the headers, place both directories (if different) on your " -"compiler's search path for includes. Do *not* place the parent directories " -"on the search path and then use ``#include ``; this will " -"break on multi-platform builds since the platform independent headers under :" -"option:`prefix <--prefix>` include the platform specific headers from :" -"option:`exec_prefix <--exec-prefix>`." -msgstr "" -"要引入標頭，請將兩個（如果不同）目錄放在編譯器的引入搜尋路徑 (search path) " -"中。*不要*\\ 將父目錄放在搜尋路徑上，然後使用 ``#include ``；這會在多平台建置上壞掉，因為 :option:`prefix <--prefix>` 下獨立於平台的" -"標頭包括來自 :option:`exec_prefix <--exec-prefix>` 的平台特定標頭。" - -#: ../../c-api/intro.rst:105 -msgid "" -"C++ users should note that although the API is defined entirely using C, the " -"header files properly declare the entry points to be ``extern \"C\"``. As a " -"result, there is no need to do anything special to use the API from C++." -msgstr "" -"C++ 使用者應注意，儘管 API 完全使用 C 來定義，但標頭檔適當地將入口點聲明為 " -"``extern \"C\"``。因此，無需執行任何特殊操作即可使用 C++ 中的 API。" - -#: ../../c-api/intro.rst:111 -msgid "Useful macros" -msgstr "有用的巨集" - -#: ../../c-api/intro.rst:113 -msgid "" -"Several useful macros are defined in the Python header files. Many are " -"defined closer to where they are useful (for example, :c:macro:" -"`Py_RETURN_NONE`, :c:macro:`PyMODINIT_FUNC`). Others of a more general " -"utility are defined here. This is not necessarily a complete listing." -msgstr "" -"Python 標頭檔中定義了幾個有用的巨集，大多被定義在它們有用的地方附近（例如 :c:" -"macro:`Py_RETURN_NONE`、:c:macro:`PyMODINIT_FUNC`），其他是更通用的工具程式。" -"以下並不一定是完整的列表。" - -#: ../../c-api/intro.rst:122 -msgid "Return the absolute value of ``x``." -msgstr "回傳 ``x`` 的絕對值。" - -#: ../../c-api/intro.rst:124 -msgid "" -"If the result cannot be represented (for example, if ``x`` has :c:macro:`!" -"INT_MIN` value for :c:expr:`int` type), the behavior is undefined." -msgstr "" - -#: ../../c-api/intro.rst:132 -msgid "" -"Ask the compiler to always inline a static inline function. The compiler can " -"ignore it and decide to not inline the function." -msgstr "" -"要求編譯器總是嵌入靜態行內函式 (static inline function)，編譯器可以忽略它並決" -"定不嵌入該函式。" - -#: ../../c-api/intro.rst:135 -msgid "" -"It can be used to inline performance critical static inline functions when " -"building Python in debug mode with function inlining disabled. For example, " -"MSC disables function inlining when building in debug mode." -msgstr "" -"在禁用函式嵌入的除錯模式下建置 Python 時，它可用於嵌入有性能要求的靜態行內函" -"式。例如，MSC 在除錯模式下建置時禁用函式嵌入。" - -#: ../../c-api/intro.rst:139 -msgid "" -"Marking blindly a static inline function with Py_ALWAYS_INLINE can result in " -"worse performances (due to increased code size for example). The compiler is " -"usually smarter than the developer for the cost/benefit analysis." -msgstr "" -"盲目地使用 Py_ALWAYS_INLINE 標記靜態行內函式可能會導致更差的性能（例如程式碼" -"大小增加）。在成本/收益分析方面，編譯器通常比開發人員更聰明。" - -#: ../../c-api/intro.rst:143 -msgid "" -"If Python is :ref:`built in debug mode ` (if the :c:macro:" -"`Py_DEBUG` macro is defined), the :c:macro:`Py_ALWAYS_INLINE` macro does " -"nothing." -msgstr "" -"如果 Python 是\\ :ref:`在除錯模式下建置 `\\ （如果 :c:macro:" -"`Py_DEBUG` 巨集有被定義），:c:macro:`Py_ALWAYS_INLINE` 巨集就什麼都不會做。" - -#: ../../c-api/intro.rst:146 -msgid "It must be specified before the function return type. Usage::" -msgstr "它必須在函式回傳型別之前被指定。用法： ::" - -#: ../../c-api/intro.rst:148 -msgid "static inline Py_ALWAYS_INLINE int random(void) { return 4; }" -msgstr "static inline Py_ALWAYS_INLINE int random(void) { return 4; }" - -#: ../../c-api/intro.rst:154 -msgid "" -"Argument must be a character or an integer in the range [-128, 127] or [0, " -"255]. This macro returns ``c`` cast to an ``unsigned char``." -msgstr "" -"引數必須是 [-128, 127] 或 [0, 255] 範圍內的字元或整數。這個巨集會將 ``c`` 轉" -"換為 ``unsigned char`` 並回傳。" - -#: ../../c-api/intro.rst:159 -msgid "" -"Use this for deprecated declarations. The macro must be placed before the " -"symbol name." -msgstr "將其用於已棄用的聲明。巨集必須放在符號名稱之前。" - -#: ../../c-api/intro.rst:162 ../../c-api/intro.rst:290 -#: ../../c-api/intro.rst:308 -msgid "Example::" -msgstr "範例： ::" - -#: ../../c-api/intro.rst:164 -msgid "Py_DEPRECATED(3.8) PyAPI_FUNC(int) Py_OldFunction(void);" -msgstr "Py_DEPRECATED(3.8) PyAPI_FUNC(int) Py_OldFunction(void);" - -#: ../../c-api/intro.rst:166 -msgid "MSVC support was added." -msgstr "新增了 MSVC 支援。" - -#: ../../c-api/intro.rst:171 -msgid "" -"Like ``getenv(s)``, but returns ``NULL`` if :option:`-E` was passed on the " -"command line (see :c:member:`PyConfig.use_environment`)." -msgstr "" -"類似於 ``getenv(s)``，但如果在命令列上傳遞了 :option:`-E` 則回傳 ``NULL`` " -"（請見 :c:member:`PyConfig.use_environment`）。" - -#: ../../c-api/intro.rst:176 -msgid "" -"Declare a function returning the specified *type* using a fast-calling " -"qualifier for functions that are local to the current file. Semantically, " -"this is equivalent to ``static type``." -msgstr "" - -#: ../../c-api/intro.rst:182 -msgid "" -"Equivalent to :c:macro:`Py_LOCAL` but additionally requests the function be " -"inlined." -msgstr "" - -#: ../../c-api/intro.rst:187 -msgid "Return the maximum value between ``x`` and ``y``." -msgstr "回傳 ``x`` 和 ``y`` 之間的最大值。" - -#: ../../c-api/intro.rst:193 -msgid "Return the size of a structure (``type``) ``member`` in bytes." -msgstr "以位元組為單位回傳結構 (``type``) ``member`` 的大小。" - -#: ../../c-api/intro.rst:199 -msgid "" -"This is a :term:`soft deprecated` alias to :c:func:`!memcpy`. Use :c:func:`!" -"memcpy` directly instead." -msgstr "" -"這是 :c:func:`!memcpy` 的已\\ :term:`軟性棄用 `\\ 別名。請直" -"接使用 :c:func:`!memcpy`。" - -#: ../../c-api/intro.rst:202 -msgid "The macro is :term:`soft deprecated`." -msgstr "這個巨集已被\\ :term:`軟性棄用 `。" - -#: ../../c-api/intro.rst:207 -msgid "Return the minimum value between ``x`` and ``y``." -msgstr "回傳 ``x`` 和 ``y`` 之間的最小值。" - -#: ../../c-api/intro.rst:213 -msgid "" -"Disable inlining on a function. For example, it reduces the C stack " -"consumption: useful on LTO+PGO builds which heavily inline code (see :issue:" -"`33720`)." -msgstr "" -"禁用函式的嵌入。例如，它減少了 C 堆疊的消耗：對大量嵌入程式碼的 LTO+PGO 建置" -"很有用（請參閱 :issue:`33720`）。" - -#: ../../c-api/intro.rst:217 -msgid "Usage::" -msgstr "用法： ::" - -#: ../../c-api/intro.rst:219 -msgid "Py_NO_INLINE static int random(void) { return 4; }" -msgstr "Py_NO_INLINE static int random(void) { return 4; }" - -#: ../../c-api/intro.rst:225 -msgid "" -"Convert ``x`` to a C string. E.g. ``Py_STRINGIFY(123)`` returns ``\"123\"``." -msgstr "" -"將 ``x`` 轉換為 C 字串。例如 ``Py_STRINGIFY(123)`` 會回傳 ``\"123\"``。" - -#: ../../c-api/intro.rst:232 -msgid "" -"Use this when you have a code path that cannot be reached by design. For " -"example, in the ``default:`` clause in a ``switch`` statement for which all " -"possible values are covered in ``case`` statements. Use this in places " -"where you might be tempted to put an ``assert(0)`` or ``abort()`` call." -msgstr "" -"當你的設計中有無法達到的程式碼路徑時，請使用此選項。例如在 ``case`` 語句已涵" -"蓋了所有可能值的 ``switch`` 陳述式中的 ``default:`` 子句。在你可能想要呼叫 " -"``assert(0)`` 或 ``abort()`` 的地方使用它。" - -#: ../../c-api/intro.rst:237 -msgid "" -"In release mode, the macro helps the compiler to optimize the code, and " -"avoids a warning about unreachable code. For example, the macro is " -"implemented with ``__builtin_unreachable()`` on GCC in release mode." -msgstr "" -"在發布模式 (release mode) 下，巨集幫助編譯器最佳化程式碼，並避免有關無法存取" -"程式碼的警告。例如該巨集是在發布模式下於 GCC 使用 " -"``__builtin_unreachable()`` 來實作。" - -#: ../../c-api/intro.rst:241 -msgid "" -"A use for ``Py_UNREACHABLE()`` is following a call a function that never " -"returns but that is not declared :c:macro:`_Py_NO_RETURN`." -msgstr "" -"``Py_UNREACHABLE()`` 的一個用途是，在對一個永不回傳但並未聲明為 :c:macro:" -"`_Py_NO_RETURN` 的函式之呼叫後使用。" - -#: ../../c-api/intro.rst:244 -msgid "" -"If a code path is very unlikely code but can be reached under exceptional " -"case, this macro must not be used. For example, under low memory condition " -"or if a system call returns a value out of the expected range. In this " -"case, it's better to report the error to the caller. If the error cannot be " -"reported to caller, :c:func:`Py_FatalError` can be used." -msgstr "" -"如果程式碼路徑是極不可能但在特殊情況下可以到達，則不得使用此巨集。例如在低記" -"憶體條件下或系統呼叫回傳了超出預期範圍的值。在這種情況下，最好將錯誤回報給呼" -"叫者。如果無法回報錯誤則可以使用 :c:func:`Py_FatalError`。" - -#: ../../c-api/intro.rst:254 -msgid "" -"Use this for unused arguments in a function definition to silence compiler " -"warnings. Example: ``int func(int a, int Py_UNUSED(b)) { return a; }``." -msgstr "" -"將此用於函式定義中未使用的參數以消除編譯器警告。例如：``int func(int a, int " -"Py_UNUSED(b)) { return a; }``。" - -#: ../../c-api/intro.rst:261 -msgid "" -"Asserts a compile-time condition *cond*, as a statement. The build will fail " -"if the condition is false or cannot be evaluated at compile time." -msgstr "" - -#: ../../c-api/intro.rst:264 ../../c-api/intro.rst:275 -#: ../../c-api/intro.rst:320 -msgid "For example::" -msgstr "範例： ::" - -#: ../../c-api/intro.rst:266 -msgid "Py_BUILD_ASSERT(sizeof(PyTime_t) == sizeof(int64_t));" -msgstr "Py_BUILD_ASSERT(sizeof(PyTime_t) == sizeof(int64_t));" - -#: ../../c-api/intro.rst:272 -msgid "" -"Asserts a compile-time condition *cond*, as an expression that evaluates to " -"``0``. The build will fail if the condition is false or cannot be evaluated " -"at compile time." -msgstr "" - -#: ../../c-api/intro.rst:277 -msgid "" -"#define foo_to_char(foo) \\\n" -" ((char *)(foo) + Py_BUILD_ASSERT_EXPR(offsetof(struct foo, string) == 0))" -msgstr "" -"#define foo_to_char(foo) \\\n" -" ((char *)(foo) + Py_BUILD_ASSERT_EXPR(offsetof(struct foo, string) == 0))" - -#: ../../c-api/intro.rst:284 -msgid "" -"Creates a variable with name *name* that can be used in docstrings. If " -"Python is built without docstrings, the value will be empty." -msgstr "" -"建立一個名為 *name* 的變數，可以在文件字串中使用。如果 Python 是在沒有文件字" -"串的情況下建置，則該值將為空。" - -#: ../../c-api/intro.rst:287 -msgid "" -"Use :c:macro:`PyDoc_STRVAR` for docstrings to support building Python " -"without docstrings, as specified in :pep:`7`." -msgstr "" -"如 :pep:`7` 中所指明，使用 :c:macro:`PyDoc_STRVAR` 作為文件字串可以支援在沒有" -"文件字串的情況下建置 Python。" - -#: ../../c-api/intro.rst:292 -msgid "" -"PyDoc_STRVAR(pop_doc, \"Remove and return the rightmost element.\");\n" -"\n" -"static PyMethodDef deque_methods[] = {\n" -" // ...\n" -" {\"pop\", (PyCFunction)deque_pop, METH_NOARGS, pop_doc},\n" -" // ...\n" -"}" -msgstr "" -"PyDoc_STRVAR(pop_doc, \"Remove and return the rightmost element.\");\n" -"\n" -"static PyMethodDef deque_methods[] = {\n" -" // ...\n" -" {\"pop\", (PyCFunction)deque_pop, METH_NOARGS, pop_doc},\n" -" // ...\n" -"}" - -#: ../../c-api/intro.rst:302 -msgid "" -"Creates a docstring for the given input string or an empty string if " -"docstrings are disabled." -msgstr "為給定的輸入字串建立一個文件字串，如果文件字串被禁用則建立空字串。" - -#: ../../c-api/intro.rst:305 -msgid "" -"Use :c:macro:`PyDoc_STR` in specifying docstrings to support building Python " -"without docstrings, as specified in :pep:`7`." -msgstr "" -"如 :pep:`7` 中所指明，使用 :c:macro:`PyDoc_STR` 指定文件字串以支援在沒有文件" -"字串下建置 Python。" - -#: ../../c-api/intro.rst:310 -msgid "" -"static PyMethodDef pysqlite_row_methods[] = {\n" -" {\"keys\", (PyCFunction)pysqlite_row_keys, METH_NOARGS,\n" -" PyDoc_STR(\"Returns the keys of the row.\")},\n" -" {NULL, NULL}\n" -"};" -msgstr "" -"static PyMethodDef pysqlite_row_methods[] = {\n" -" {\"keys\", (PyCFunction)pysqlite_row_keys, METH_NOARGS,\n" -" PyDoc_STR(\"Returns the keys of the row.\")},\n" -" {NULL, NULL}\n" -"};" - -#: ../../c-api/intro.rst:318 -msgid "Declares a static character array variable with the given name *name*." -msgstr "" - -#: ../../c-api/intro.rst:322 -msgid "" -"PyDoc_VAR(python_doc) = PyDoc_STR(\"A genus of constricting snakes in the " -"Pythonidae family native \"\n" -" \"to the tropics and subtropics of the " -"Eastern Hemisphere.\");" -msgstr "" -"PyDoc_VAR(python_doc) = PyDoc_STR(\"A genus of constricting snakes in the " -"Pythonidae family native \"\n" -" \"to the tropics and subtropics of the " -"Eastern Hemisphere.\");" - -#: ../../c-api/intro.rst:327 -msgid "Compute the length of a statically allocated C array at compile time." -msgstr "" - -#: ../../c-api/intro.rst:329 -msgid "" -"The *array* argument must be a C array with a size known at compile time. " -"Passing an array with an unknown size, such as a heap-allocated array, will " -"result in a compilation error on some compilers, or otherwise produce " -"incorrect results." -msgstr "" - -#: ../../c-api/intro.rst:334 -msgid "This is roughly equivalent to::" -msgstr "" - -#: ../../c-api/intro.rst:336 -msgid "sizeof(array) / sizeof((array)[0])" -msgstr "" - -#: ../../c-api/intro.rst:342 -msgid "Objects, Types and Reference Counts" -msgstr "物件、型別和參照計數" - -#: ../../c-api/intro.rst:346 -msgid "" -"Most Python/C API functions have one or more arguments as well as a return " -"value of type :c:expr:`PyObject*`. This type is a pointer to an opaque data " -"type representing an arbitrary Python object. Since all Python object types " -"are treated the same way by the Python language in most situations (e.g., " -"assignments, scope rules, and argument passing), it is only fitting that " -"they should be represented by a single C type. Almost all Python objects " -"live on the heap: you never declare an automatic or static variable of type :" -"c:type:`PyObject`, only pointer variables of type :c:expr:`PyObject*` can " -"be declared. The sole exception are the type objects; since these must " -"never be deallocated, they are typically static :c:type:`PyTypeObject` " -"objects." -msgstr "" -"大多數 Python/C API 函式都有一個或多個引數以及一個型別為 :c:expr:`PyObject*` " -"的回傳值，此型別是一個指標，指向一個表示任意 Python 物件的晦暗 (opaque) 資料" -"型別。由於在大多數情況下，Python 語言以相同的方式處理所有 Python 物件型別（例" -"如賦值、作用域規則和引數傳遞），因此它們應該由單個 C 型別來表示。幾乎所有的 " -"Python 物件都存在於堆積 (heap) 中：你永遠不會聲明 :c:type:`PyObject` 型別的自" -"動變數或靜態變數，只能聲明 :c:expr:`PyObject*` 型別的指標變數。唯一的例外是型" -"別物件；由於它們絕不能被釋放，因此它們通常是靜態 :c:type:`PyTypeObject` 物" -"件。" - -#: ../../c-api/intro.rst:357 -msgid "" -"All Python objects (even Python integers) have a :dfn:`type` and a :dfn:" -"`reference count`. An object's type determines what kind of object it is (e." -"g., an integer, a list, or a user-defined function; there are many more as " -"explained in :ref:`types`). For each of the well-known types there is a " -"macro to check whether an object is of that type; for instance, " -"``PyList_Check(a)`` is true if (and only if) the object pointed to by *a* is " -"a Python list." -msgstr "" -"所有 Python 物件（甚至是 Python 整數）都有一個型別 (:dfn:`type`) 和一個參照計" -"數 (:dfn:`reference count`)。一個物件的型別決定了它是什麼種類的物件（例如一個" -"整數、一個 list 或一個使用者定義的函式；還有更多型別，請見\\ :ref:" -"`types`\\ ）。對於每個眾所周知的型別，都有一個巨集來檢查物件是否屬於該型別；" -"例如，若（且唯若）*a* 指向的物件是 Python list 時，``PyList_Check(a)`` 為真。" - -#: ../../c-api/intro.rst:368 -msgid "Reference Counts" -msgstr "參照計數" - -#: ../../c-api/intro.rst:370 -msgid "" -"The reference count is important because today's computers have a finite " -"(and often severely limited) memory size; it counts how many different " -"places there are that have a :term:`strong reference` to an object. Such a " -"place could be another object, or a global (or static) C variable, or a " -"local variable in some C function. When the last :term:`strong reference` to " -"an object is released (i.e. its reference count becomes zero), the object is " -"deallocated. If it contains references to other objects, those references " -"are released. Those other objects may be deallocated in turn, if there are " -"no more references to them, and so on. (There's an obvious problem with " -"objects that reference each other here; for now, the solution is \"don't do " -"that.\")" -msgstr "" -"參照計數很重要，因為現今的電腦記憶體大小是有限的（而且通常是非常有限的）；它" -"計算有多少個不同的地方用有了一個物件的\\ :term:`強參照 `。" -"這樣的地方可以是另一個物件，或者全域（或靜態）C 變數，或者某個 C 函式中的本地" -"變數。當一個物件的最後一個\\ :term:`強參照 `\\ 被釋放時（即" -"其的參照計數變為零），該物件將被解除配置 (deallocated)。如果它包含對其他物件" -"的參照，則它們的參照會被釋放。如果這樣的釋放使得再也沒有任何對於它們的參照，" -"則可以依次為那些其他物件解除配置，依此類推。（此處相互參照物件的存在是個明顯" -"的問題；目前，解決方案是「就不要那樣做」。）" - -#: ../../c-api/intro.rst:387 -msgid "" -"Reference counts are always manipulated explicitly. The normal way is to " -"use the macro :c:func:`Py_INCREF` to take a new reference to an object (i.e. " -"increment its reference count by one), and :c:func:`Py_DECREF` to release " -"that reference (i.e. decrement the reference count by one). The :c:func:" -"`Py_DECREF` macro is considerably more complex than the incref one, since it " -"must check whether the reference count becomes zero and then cause the " -"object's deallocator to be called. The deallocator is a function pointer " -"contained in the object's type structure. The type-specific deallocator " -"takes care of releasing references for other objects contained in the object " -"if this is a compound object type, such as a list, as well as performing any " -"additional finalization that's needed. There's no chance that the reference " -"count can overflow; at least as many bits are used to hold the reference " -"count as there are distinct memory locations in virtual memory (assuming " -"``sizeof(Py_ssize_t) >= sizeof(void*)``). Thus, the reference count " -"increment is a simple operation." -msgstr "" -"參照計數總是被明確地操作。正常的方法是使用巨集 :c:func:`Py_INCREF` 來取得對於" -"物件的參照（即參照計數加一），並使用巨集 :c:func:`Py_DECREF` 來釋放參照（即將" -"參照計數減一）。:c:func:`Py_DECREF` 巨集比 incref 巨集複雜得多，因為它必須檢" -"查參照計數是否變為零，然後呼叫物件的釋放器 (deallocator)。釋放器是包含在物件" -"型別結構中的函式指標。特定型別的釋放器，在如果是一個複合物件型別（例如 list）" -"時負責釋放物件中包含的其他物件的參照，並執行任何需要的額外完結步驟。參照計數" -"不可能溢出；至少與虛擬記憶體中用來保存參照計數的不同記憶體位置數量一樣多的位" -"元會被使用（假設 ``sizeof(Py_ssize_t) >= sizeof(void*)``）。因此參照計數增加" -"是一個簡單的操作。" - -#: ../../c-api/intro.rst:403 -msgid "" -"It is not necessary to hold a :term:`strong reference` (i.e. increment the " -"reference count) for every local variable that contains a pointer to an " -"object. In theory, the object's reference count goes up by one when the " -"variable is made to point to it and it goes down by one when the variable " -"goes out of scope. However, these two cancel each other out, so at the end " -"the reference count hasn't changed. The only real reason to use the " -"reference count is to prevent the object from being deallocated as long as " -"our variable is pointing to it. If we know that there is at least one " -"other reference to the object that lives at least as long as our variable, " -"there is no need to take a new :term:`strong reference` (i.e. increment the " -"reference count) temporarily. An important situation where this arises is in " -"objects that are passed as arguments to C functions in an extension module " -"that are called from Python; the call mechanism guarantees to hold a " -"reference to every argument for the duration of the call." -msgstr "" -"沒有必要為每個包含物件指標的本地變數物件都持有一個\\ :term:`強參照 `\\ （即增加參照計數）。理論上，當變數指向它時，物件的參照計數會增" -"加 1，而當變數離開作用域時就會減少 1。然而這兩者會相互抵消，所以最後參照計數" -"沒有改變。使用參照計數的唯一真正原因是防止物件還有變數指向它時被解除配置。如" -"果我們知道至少有一個物件的其他參照生存了至少與我們的變數一樣久，就不需要臨時" -"增加建立新的\\ :term:`強參照 `\\ （即增加參照計數）。出現這" -"種情況的一個重要情況是在從 Python 呼叫的擴充模組中作為引數傳遞給 C 函式的物" -"件；呼叫機制保證在呼叫期間保持對每個參數的參照。" - -#: ../../c-api/intro.rst:419 -msgid "" -"However, a common pitfall is to extract an object from a list and hold on to " -"it for a while without taking a new reference. Some other operation might " -"conceivably remove the object from the list, releasing that reference, and " -"possibly deallocating it. The real danger is that innocent-looking " -"operations may invoke arbitrary Python code which could do this; there is a " -"code path which allows control to flow back to the user from a :c:func:" -"`Py_DECREF`, so almost any operation is potentially dangerous." -msgstr "" -"然而，一個常見的陷阱是從一個 list 中提取一個物件並保留它一段時間而不取得其參" -"照。某些其他操作可能會從列表中刪除該物件，減少其參照計數並可能取消分配它。真" -"正的危險是看似無害的操作可能會叫用可以執行此操作的任意 Python 程式碼；有一個" -"程式碼路徑允許控制權從 :c:func:`Py_DECREF` 回歸使用者，因此幾乎任何操作都有潛" -"在危險。" - -#: ../../c-api/intro.rst:427 -msgid "" -"A safe approach is to always use the generic operations (functions whose " -"name begins with ``PyObject_``, ``PyNumber_``, ``PySequence_`` or " -"``PyMapping_``). These operations always create a new :term:`strong " -"reference` (i.e. increment the reference count) of the object they return. " -"This leaves the caller with the responsibility to call :c:func:`Py_DECREF` " -"when they are done with the result; this soon becomes second nature." -msgstr "" -"一種安全的方法是都使用通用 (generics) 操作（名稱以 ``PyObject_``、" -"``PyNumber_``、``PySequence_`` 或 ``PyMapping_`` 開頭的函式）。這些操作總是建" -"立新的對於它們回傳物件的\\ :term:`強參照 `\\ （即增加其參照" -"計數）。這讓呼叫者有責任在處理完結果後呼叫 :c:func:`Py_DECREF`；這就成為第二" -"本質。" - -#: ../../c-api/intro.rst:438 -msgid "Reference Count Details" -msgstr "參照計數詳細資訊" - -#: ../../c-api/intro.rst:440 -msgid "" -"The reference count behavior of functions in the Python/C API is best " -"explained in terms of *ownership of references*. Ownership pertains to " -"references, never to objects (objects are not owned: they are always " -"shared). \"Owning a reference\" means being responsible for calling " -"Py_DECREF on it when the reference is no longer needed. Ownership can also " -"be transferred, meaning that the code that receives ownership of the " -"reference then becomes responsible for eventually releasing it by calling :c:" -"func:`Py_DECREF` or :c:func:`Py_XDECREF` when it's no longer needed---or " -"passing on this responsibility (usually to its caller). When a function " -"passes ownership of a reference on to its caller, the caller is said to " -"receive a *new* reference. When no ownership is transferred, the caller is " -"said to *borrow* the reference. Nothing needs to be done for a :term:" -"`borrowed reference`." -msgstr "" -"Python/C API 中函式的參照計數行為最好用\\ *參照的所有權*\\ 來解釋。所有權附屬" -"於參照而非物件（物件並非被擁有，它們總是共享的）。「擁有參照」意味著當不再需" -"要該參照時，負責在其上呼叫 Py_DECREF。所有權也可以轉移，這意味著接收參照所有" -"權的程式碼最終會負責在不需要參照時透過呼叫 :c:func:`Py_DECREF` 或 :c:func:" -"`Py_XDECREF` 釋放參照 --- 或者將這個責任再傳遞出去（通常是給它的呼叫者）。當" -"一個函式將參照的所有權傳遞給它的呼叫者時，呼叫者被稱為接收到一個\\ *新*\\ 參" -"照。當沒有所有權轉移時，呼叫者被稱為\\ *借用*\\ 參照。如果是\\ :term:`借用參" -"照 `\\ 就不需要做任何事情。" - -#: ../../c-api/intro.rst:453 -msgid "" -"Conversely, when a calling function passes in a reference to an object, " -"there are two possibilities: the function *steals* a reference to the " -"object, or it does not. *Stealing a reference* means that when you pass a " -"reference to a function, that function assumes that it now owns that " -"reference, and you are not responsible for it any longer." -msgstr "" -"相反地，當呼叫的函式傳入物件的參照時，有兩種可能性：函式有\\ *竊取 (steal)* " -"物件的參照，或者沒有。 *竊取參照*\\ 意味著當你將參照傳遞給函式時，該函式假定" -"它現在擁有該參照，並且你不再對它負責。" - -#: ../../c-api/intro.rst:463 -msgid "" -"Few functions steal references; the two notable exceptions are :c:func:" -"`PyList_SetItem` and :c:func:`PyTuple_SetItem`, which steal a reference to " -"the item (but not to the tuple or list into which the item is put!). These " -"functions were designed to steal a reference because of a common idiom for " -"populating a tuple or list with newly created objects; for example, the code " -"to create the tuple ``(1, 2, \"three\")`` could look like this (forgetting " -"about error handling for the moment; a better way to code this is shown " -"below)::" -msgstr "" -"很少有函式會竊取參照；兩個值得注意的例外是 :c:func:`PyList_SetItem` 和 :c:" -"func:`PyTuple_SetItem`，它們竊取了對項目的參照（但不是對項目所在的 tuple 或 " -"list 的參照！）。因為有著使用新建立的物件來增加 (populate) tuple 或 list 的習" -"慣，這些函式旨在竊取參照；例如，建立 tuple ``(1, 2, \"three\")`` 的程式碼可以" -"如下所示（先暫時忘記錯誤處理；更好的編寫方式如下所示）：" - -#: ../../c-api/intro.rst:471 -msgid "" -"PyObject *t;\n" -"\n" -"t = PyTuple_New(3);\n" -"PyTuple_SetItem(t, 0, PyLong_FromLong(1L));\n" -"PyTuple_SetItem(t, 1, PyLong_FromLong(2L));\n" -"PyTuple_SetItem(t, 2, PyUnicode_FromString(\"three\"));" -msgstr "" -"PyObject *t;\n" -"\n" -"t = PyTuple_New(3);\n" -"PyTuple_SetItem(t, 0, PyLong_FromLong(1L));\n" -"PyTuple_SetItem(t, 1, PyLong_FromLong(2L));\n" -"PyTuple_SetItem(t, 2, PyUnicode_FromString(\"three\"));" - -#: ../../c-api/intro.rst:478 -msgid "" -"Here, :c:func:`PyLong_FromLong` returns a new reference which is immediately " -"stolen by :c:func:`PyTuple_SetItem`. When you want to keep using an object " -"although the reference to it will be stolen, use :c:func:`Py_INCREF` to grab " -"another reference before calling the reference-stealing function." -msgstr "" -"這裡 :c:func:`PyLong_FromLong` 會回傳一個新的參照，它立即被 :c:func:" -"`PyTuple_SetItem` 竊取。如果你想繼續使用一個物件，儘管對它的參照將被竊取，請" -"在呼叫參照竊取函式之前使用 :c:func:`Py_INCREF` 來取得另一個參照。" - -#: ../../c-api/intro.rst:483 -msgid "" -"Incidentally, :c:func:`PyTuple_SetItem` is the *only* way to set tuple " -"items; :c:func:`PySequence_SetItem` and :c:func:`PyObject_SetItem` refuse to " -"do this since tuples are an immutable data type. You should only use :c:" -"func:`PyTuple_SetItem` for tuples that you are creating yourself." -msgstr "" -"附帶地說，:c:func:`PyTuple_SetItem` 是設定 tuple 項目的\\ *唯一*\\ 方法； :c:" -"func:`PySequence_SetItem` 和 :c:func:`PyObject_SetItem` 拒絕這樣做，因為 " -"tuple 是一種不可變 (immutable) 的資料型別。你應該只對你自己建立的 tuple 使" -"用 :c:func:`PyTuple_SetItem`。" - -#: ../../c-api/intro.rst:488 -msgid "" -"Equivalent code for populating a list can be written using :c:func:" -"`PyList_New` and :c:func:`PyList_SetItem`." -msgstr "" -"可以使用 :c:func:`PyList_New` 和 :c:func:`PyList_SetItem` 編寫用於填充列表的" -"等效程式碼。" - -#: ../../c-api/intro.rst:491 -msgid "" -"However, in practice, you will rarely use these ways of creating and " -"populating a tuple or list. There's a generic function, :c:func:" -"`Py_BuildValue`, that can create most common objects from C values, directed " -"by a :dfn:`format string`. For example, the above two blocks of code could " -"be replaced by the following (which also takes care of the error checking)::" -msgstr "" -"但是在實際操作中你很少會使用這些方法來建立和增加 tuple 和 list。有一個通用函" -"式 :c:func:`Py_BuildValue` 可以從 C 值建立最常見的物件，由 :dfn:`format " -"string` 引導。例如上面的兩個程式碼可以用以下程式碼替換（它還負責了錯誤檢" -"查）： ::" - -#: ../../c-api/intro.rst:497 -msgid "" -"PyObject *tuple, *list;\n" -"\n" -"tuple = Py_BuildValue(\"(iis)\", 1, 2, \"three\");\n" -"list = Py_BuildValue(\"[iis]\", 1, 2, \"three\");" -msgstr "" -"PyObject *tuple, *list;\n" -"\n" -"tuple = Py_BuildValue(\"(iis)\", 1, 2, \"three\");\n" -"list = Py_BuildValue(\"[iis]\", 1, 2, \"three\");" - -#: ../../c-api/intro.rst:502 -msgid "" -"It is much more common to use :c:func:`PyObject_SetItem` and friends with " -"items whose references you are only borrowing, like arguments that were " -"passed in to the function you are writing. In that case, their behaviour " -"regarding references is much saner, since you don't have to take a new " -"reference just so you can give that reference away (\"have it be stolen\"). " -"For example, this function sets all items of a list (actually, any mutable " -"sequence) to a given item::" -msgstr "" -"更常見的是以那些借用參照的項目來使用 :c:func:`PyObject_SetItem` 及其系列函" -"式，比如傳遞給你正在編寫的函式的引數。在那種情況下，他們關於參照的行為會比較" -"穩健，因為你不取得新的一個參照就可以放棄參照（「讓它被竊取」）。例如，此函式" -"將 list（實際上是任何可變序列）的所有項目設定於給定項目：" - -#: ../../c-api/intro.rst:509 -msgid "" -"int\n" -"set_all(PyObject *target, PyObject *item)\n" -"{\n" -" Py_ssize_t i, n;\n" -"\n" -" n = PyObject_Length(target);\n" -" if (n < 0)\n" -" return -1;\n" -" for (i = 0; i < n; i++) {\n" -" PyObject *index = PyLong_FromSsize_t(i);\n" -" if (!index)\n" -" return -1;\n" -" if (PyObject_SetItem(target, index, item) < 0) {\n" -" Py_DECREF(index);\n" -" return -1;\n" -" }\n" -" Py_DECREF(index);\n" -" }\n" -" return 0;\n" -"}" -msgstr "" -"int\n" -"set_all(PyObject *target, PyObject *item)\n" -"{\n" -" Py_ssize_t i, n;\n" -"\n" -" n = PyObject_Length(target);\n" -" if (n < 0)\n" -" return -1;\n" -" for (i = 0; i < n; i++) {\n" -" PyObject *index = PyLong_FromSsize_t(i);\n" -" if (!index)\n" -" return -1;\n" -" if (PyObject_SetItem(target, index, item) < 0) {\n" -" Py_DECREF(index);\n" -" return -1;\n" -" }\n" -" Py_DECREF(index);\n" -" }\n" -" return 0;\n" -"}" - -#: ../../c-api/intro.rst:532 -msgid "" -"The situation is slightly different for function return values. While " -"passing a reference to most functions does not change your ownership " -"responsibilities for that reference, many functions that return a reference " -"to an object give you ownership of the reference. The reason is simple: in " -"many cases, the returned object is created on the fly, and the reference " -"you get is the only reference to the object. Therefore, the generic " -"functions that return object references, like :c:func:`PyObject_GetItem` " -"and :c:func:`PySequence_GetItem`, always return a new reference (the caller " -"becomes the owner of the reference)." -msgstr "" -"函式回傳值的情況略有不同。雖然傳遞對大多數函式的參照不會改變你對該參照的所有" -"權責任，但許多回傳物件參照的函式會給你該參照的所有權。原因很簡單：在很多情況" -"下，回傳的物件是即時建立的，你獲得的參照是對該物件的唯一參照。因此回傳物件參" -"照的通用函式，如 :c:func:`PyObject_GetItem` 和 :c:func:`PySequence_GetItem`，" -"總是回傳一個新的參照（呼叫者成為參照的所有者）。" - -#: ../../c-api/intro.rst:541 -msgid "" -"It is important to realize that whether you own a reference returned by a " -"function depends on which function you call only --- *the plumage* (the type " -"of the object passed as an argument to the function) *doesn't enter into it!" -"* Thus, if you extract an item from a list using :c:func:`PyList_GetItem`, " -"you don't own the reference --- but if you obtain the same item from the " -"same list using :c:func:`PySequence_GetItem` (which happens to take exactly " -"the same arguments), you do own a reference to the returned object." -msgstr "" -"重要的是要意識到你是否擁有一個函式回傳的參照只取決於你呼叫哪個函式 --- *羽毛 " -"(plumage)*\\ （作為引數傳遞給函式的物件之型別）\\ *不會進入它！*\\ 因此，如果" -"你使用 :c:func:`PyList_GetItem` 從 list 中提取一個項目，你不會擁有其參照 --- " -"但如果你使用 :c:func:`PySequence_GetItem` 從同一 list 中取得相同的項目（且恰" -"好使用完全相同的引數），你確實會擁有對回傳物件的參照。" - -#: ../../c-api/intro.rst:553 -msgid "" -"Here is an example of how you could write a function that computes the sum " -"of the items in a list of integers; once using :c:func:`PyList_GetItem`, " -"and once using :c:func:`PySequence_GetItem`. ::" -msgstr "" -"以下是一個範例，說明如何編寫函式來計算一個整數 list 中項目的總和；一次使用 :" -"c:func:`PyList_GetItem`，一次使用 :c:func:`PySequence_GetItem`： ::" - -#: ../../c-api/intro.rst:557 -msgid "" -"long\n" -"sum_list(PyObject *list)\n" -"{\n" -" Py_ssize_t i, n;\n" -" long total = 0, value;\n" -" PyObject *item;\n" -"\n" -" n = PyList_Size(list);\n" -" if (n < 0)\n" -" return -1; /* Not a list */\n" -" for (i = 0; i < n; i++) {\n" -" item = PyList_GetItem(list, i); /* Can't fail */\n" -" if (!PyLong_Check(item)) continue; /* Skip non-integers */\n" -" value = PyLong_AsLong(item);\n" -" if (value == -1 && PyErr_Occurred())\n" -" /* Integer too big to fit in a C long, bail out */\n" -" return -1;\n" -" total += value;\n" -" }\n" -" return total;\n" -"}" -msgstr "" -"long\n" -"sum_list(PyObject *list)\n" -"{\n" -" Py_ssize_t i, n;\n" -" long total = 0, value;\n" -" PyObject *item;\n" -"\n" -" n = PyList_Size(list);\n" -" if (n < 0)\n" -" return -1; /* 不是 list */\n" -" for (i = 0; i < n; i++) {\n" -" item = PyList_GetItem(list, i); /* 不會失敗 */\n" -" if (!PyLong_Check(item)) continue; /* 跳過非整數 */\n" -" value = PyLong_AsLong(item);\n" -" if (value == -1 && PyErr_Occurred())\n" -" /* 整數太大，無法放入 C long，退出 */\n" -" return -1;\n" -" total += value;\n" -" }\n" -" return total;\n" -"}" - -#: ../../c-api/intro.rst:583 -msgid "" -"long\n" -"sum_sequence(PyObject *sequence)\n" -"{\n" -" Py_ssize_t i, n;\n" -" long total = 0, value;\n" -" PyObject *item;\n" -" n = PySequence_Length(sequence);\n" -" if (n < 0)\n" -" return -1; /* Has no length */\n" -" for (i = 0; i < n; i++) {\n" -" item = PySequence_GetItem(sequence, i);\n" -" if (item == NULL)\n" -" return -1; /* Not a sequence, or other failure */\n" -" if (PyLong_Check(item)) {\n" -" value = PyLong_AsLong(item);\n" -" Py_DECREF(item);\n" -" if (value == -1 && PyErr_Occurred())\n" -" /* Integer too big to fit in a C long, bail out */\n" -" return -1;\n" -" total += value;\n" -" }\n" -" else {\n" -" Py_DECREF(item); /* Discard reference ownership */\n" -" }\n" -" }\n" -" return total;\n" -"}" -msgstr "" -"long\n" -"sum_sequence(PyObject *sequence)\n" -"{\n" -" Py_ssize_t i, n;\n" -" long total = 0, value;\n" -" PyObject *item;\n" -" n = PySequence_Length(sequence);\n" -" if (n < 0)\n" -" return -1; /* 沒有長度 */\n" -" for (i = 0; i < n; i++) {\n" -" item = PySequence_GetItem(sequence, i);\n" -" if (item == NULL)\n" -" return -1; /* 不是序列或其他錯誤 */\n" -" if (PyLong_Check(item)) {\n" -" value = PyLong_AsLong(item);\n" -" Py_DECREF(item);\n" -" if (value == -1 && PyErr_Occurred())\n" -" /* 整數太大，無法放入 C long，退出 */\n" -" return -1;\n" -" total += value;\n" -" }\n" -" else {\n" -" Py_DECREF(item); /* 丟棄參照所有權 */\n" -" }\n" -" }\n" -" return total;\n" -"}" - -#: ../../c-api/intro.rst:617 -msgid "Types" -msgstr "型別" - -#: ../../c-api/intro.rst:619 -msgid "" -"There are few other data types that play a significant role in the Python/C " -"API; most are simple C types such as :c:expr:`int`, :c:expr:`long`, :c:expr:" -"`double` and :c:expr:`char*`. A few structure types are used to describe " -"static tables used to list the functions exported by a module or the data " -"attributes of a new object type, and another is used to describe the value " -"of a complex number. These will be discussed together with the functions " -"that use them." -msgstr "" -"有少數幾個其他的資料型別在 Python/C API 中發揮重要作用；大多數是簡單的 C 型" -"別，例如 :c:expr:`int`、:c:expr:`long`、:c:expr:`double` 和 :c:expr:`char*`。" -"一些結構型別被用於描述用於列出模組所匯出的函式或新物件型別的資料屬性的靜態" -"表，其他則用於描述複數的值。這些將與使用它們的函式一起討論。" - -#: ../../c-api/intro.rst:629 -msgid "" -"A signed integral type such that ``sizeof(Py_ssize_t) == sizeof(size_t)``. " -"C99 doesn't define such a thing directly (size_t is an unsigned integral " -"type). See :pep:`353` for details. ``PY_SSIZE_T_MAX`` is the largest " -"positive value of type :c:type:`Py_ssize_t`." -msgstr "" -"一個帶符號的整數型別，使得 ``sizeof(Py_ssize_t) == sizeof(size_t)``。 C99 沒" -"有直接定義這樣的東西（size_t 是無符號整數型別）。有關詳細資訊，請參閱 :pep:" -"`353`。 ``PY_SSIZE_T_MAX`` 是 :c:type:`Py_ssize_t` 型別的最大正值。" - -#: ../../c-api/intro.rst:638 -msgid "Exceptions" -msgstr "例外" - -#: ../../c-api/intro.rst:640 -msgid "" -"The Python programmer only needs to deal with exceptions if specific error " -"handling is required; unhandled exceptions are automatically propagated to " -"the caller, then to the caller's caller, and so on, until they reach the top-" -"level interpreter, where they are reported to the user accompanied by a " -"stack traceback." -msgstr "" -"如果需要特定的錯誤處理，Python 開發者就只需要處理例外；未處理的例外會自動傳遞" -"給呼叫者，然後傳遞給呼叫者的呼叫者，依此類推，直到它們到達頂層直譯器，在那裡" -"它們透過堆疊回溯 (stack trace) 回報給使用者。" - -#: ../../c-api/intro.rst:648 -msgid "" -"For C programmers, however, error checking always has to be explicit. All " -"functions in the Python/C API can raise exceptions, unless an explicit claim " -"is made otherwise in a function's documentation. In general, when a " -"function encounters an error, it sets an exception, discards any object " -"references that it owns, and returns an error indicator. If not documented " -"otherwise, this indicator is either ``NULL`` or ``-1``, depending on the " -"function's return type. A few functions return a Boolean true/false result, " -"with false indicating an error. Very few functions return no explicit error " -"indicator or have an ambiguous return value, and require explicit testing " -"for errors with :c:func:`PyErr_Occurred`. These exceptions are always " -"explicitly documented." -msgstr "" -"然而，對於 C 開發者來說，錯誤檢查總是必須是顯式的。除非在函式的文件中另有明確" -"聲明，否則 Python/C API 中的所有函式都可以引發例外。通常當一個函式遇到錯誤" -"時，它會設定一個例外，丟棄它擁有的任何物件參照，並回傳一個錯誤指示器。如果沒" -"有另外文件記錄，這個指示器要麼是 ``NULL`` 不然就是 ``-1``，取決於函式的回傳型" -"別。有些函式會回傳布林值 true/false 結果，false 表示錯誤。很少有函式不回傳明" -"確的錯誤指示器或者有不明確的回傳值，而需要使用 :c:func:`PyErr_Occurred` 明確" -"測試錯誤。這些例外都會被明確地記錄於文件。" - -#: ../../c-api/intro.rst:663 -msgid "" -"Exception state is maintained in per-thread storage (this is equivalent to " -"using global storage in an unthreaded application). A thread can be in one " -"of two states: an exception has occurred, or not. The function :c:func:" -"`PyErr_Occurred` can be used to check for this: it returns a borrowed " -"reference to the exception type object when an exception has occurred, and " -"``NULL`` otherwise. There are a number of functions to set the exception " -"state: :c:func:`PyErr_SetString` is the most common (though not the most " -"general) function to set the exception state, and :c:func:`PyErr_Clear` " -"clears the exception state." -msgstr "" -"例外的狀態會在個別執行緒的儲存空間 (per-thread storage) 中維護（這相當於在非" -"執行緒應用程式中使用全域儲存空間）。執行緒可以處於兩種狀態之一：發生例外或未" -"發生例外。函式 :c:func:`PyErr_Occurred` 可用於檢查這一點：當例外發生時，它回" -"傳對例外型別物件的借用參照，否則回傳 ``NULL``。設定例外狀態的函式有很多：:c:" -"func:`PyErr_SetString` 是最常見的（儘管不是最通用的）設定例外狀態的函式，而 :" -"c:func:`PyErr_Clear` 是用來清除例外狀態。" - -#: ../../c-api/intro.rst:673 -msgid "" -"The full exception state consists of three objects (all of which can be " -"``NULL``): the exception type, the corresponding exception value, and the " -"traceback. These have the same meanings as the Python result of ``sys." -"exc_info()``; however, they are not the same: the Python objects represent " -"the last exception being handled by a Python :keyword:`try` ... :keyword:" -"`except` statement, while the C level exception state only exists while an " -"exception is being passed on between C functions until it reaches the Python " -"bytecode interpreter's main loop, which takes care of transferring it to " -"``sys.exc_info()`` and friends." -msgstr "" -"完整的例外狀態由三個（都可以為 ``NULL`` 的）物件組成：例外型別、對應的例外值" -"和回溯。這些與 ``sys.exc_info()`` 的 Python 結果具有相同的含義；但是它們並不" -"相同：Python 物件表示由 Python :keyword:`try` ... :keyword:`except` 陳述式處" -"理的最後一個例外，而 C 層級的例外狀態僅在例外在 C 函式間傳遞時存在，直到它到" -"達 Python 位元組碼直譯器的主迴圈，該迴圈負責將它傳遞給 ``sys.exc_info()`` 和" -"其系列函式。" - -#: ../../c-api/intro.rst:685 -msgid "" -"Note that starting with Python 1.5, the preferred, thread-safe way to access " -"the exception state from Python code is to call the function :func:`sys." -"exc_info`, which returns the per-thread exception state for Python code. " -"Also, the semantics of both ways to access the exception state have changed " -"so that a function which catches an exception will save and restore its " -"thread's exception state so as to preserve the exception state of its " -"caller. This prevents common bugs in exception handling code caused by an " -"innocent-looking function overwriting the exception being handled; it also " -"reduces the often unwanted lifetime extension for objects that are " -"referenced by the stack frames in the traceback." -msgstr "" -"請注意，從 Python 1.5 開始，從 Python 程式碼存取例外狀態的首選且支援執行緒安" -"全的方法是呼叫 :func:`sys.exc_info` 函式，它回傳 Python 程式碼的個別執行緒例" -"外狀態。此外，兩種存取例外狀態方法的語義都發生了變化，因此捕獲例外的函式將保" -"存和恢復其執行緒的例外狀態，從而保留其呼叫者的例外狀態。這可以防止例外處理程" -"式碼中的常見錯誤，這些錯誤是由看似無辜的函式覆蓋了正在處理的例外而引起的；它" -"還替回溯中被堆疊框 (stack frame) 參照的物件減少了通常不需要的生命週期延長。" - -#: ../../c-api/intro.rst:696 -msgid "" -"As a general principle, a function that calls another function to perform " -"some task should check whether the called function raised an exception, and " -"if so, pass the exception state on to its caller. It should discard any " -"object references that it owns, and return an error indicator, but it " -"should *not* set another exception --- that would overwrite the exception " -"that was just raised, and lose important information about the exact cause " -"of the error." -msgstr "" -"作為一般原則，呼叫另一個函式來執行某些任務的函式應該檢查被呼叫函式是否引發了" -"例外，如果是，則將例外狀態傳遞給它的呼叫者。它應該丟棄它擁有的任何物件參照，" -"並回傳一個錯誤指示符，但它\\ *不應該*\\ 設定另一個例外 --- 這將覆蓋剛剛引發的" -"例外，並丟失關於錯誤確切原因的重要資訊。" - -#: ../../c-api/intro.rst:705 -msgid "" -"A simple example of detecting exceptions and passing them on is shown in " -"the :c:func:`!sum_sequence` example above. It so happens that this example " -"doesn't need to clean up any owned references when it detects an error. The " -"following example function shows some error cleanup. First, to remind you " -"why you like Python, we show the equivalent Python code::" -msgstr "" -"上面的 :c:func:`!sum_sequence` 範例展示了一個檢測例外並將其繼續傳遞的例子。碰" -"巧這個例子在檢測到錯誤時不需要清理任何擁有的參照。以下範例函式展示了一些錯誤" -"清理。首先，為了提醒你為什麼喜歡 Python，我們展示了等效的 Python 程式碼： ::" - -#: ../../c-api/intro.rst:711 -msgid "" -"def incr_item(dict, key):\n" -" try:\n" -" item = dict[key]\n" -" except KeyError:\n" -" item = 0\n" -" dict[key] = item + 1" -msgstr "" -"def incr_item(dict, key):\n" -" try:\n" -" item = dict[key]\n" -" except KeyError:\n" -" item = 0\n" -" dict[key] = item + 1" - -#: ../../c-api/intro.rst:720 -msgid "Here is the corresponding C code, in all its glory::" -msgstr "這是相應的 C 程式碼：" - -#: ../../c-api/intro.rst:722 -msgid "" -"int\n" -"incr_item(PyObject *dict, PyObject *key)\n" -"{\n" -" /* Objects all initialized to NULL for Py_XDECREF */\n" -" PyObject *item = NULL, *const_one = NULL, *incremented_item = NULL;\n" -" int rv = -1; /* Return value initialized to -1 (failure) */\n" -"\n" -" item = PyObject_GetItem(dict, key);\n" -" if (item == NULL) {\n" -" /* Handle KeyError only: */\n" -" if (!PyErr_ExceptionMatches(PyExc_KeyError))\n" -" goto error;\n" -"\n" -" /* Clear the error and use zero: */\n" -" PyErr_Clear();\n" -" item = PyLong_FromLong(0L);\n" -" if (item == NULL)\n" -" goto error;\n" -" }\n" -" const_one = PyLong_FromLong(1L);\n" -" if (const_one == NULL)\n" -" goto error;\n" -"\n" -" incremented_item = PyNumber_Add(item, const_one);\n" -" if (incremented_item == NULL)\n" -" goto error;\n" -"\n" -" if (PyObject_SetItem(dict, key, incremented_item) < 0)\n" -" goto error;\n" -" rv = 0; /* Success */\n" -" /* Continue with cleanup code */\n" -"\n" -" error:\n" -" /* Cleanup code, shared by success and failure path */\n" -"\n" -" /* Use Py_XDECREF() to ignore NULL references */\n" -" Py_XDECREF(item);\n" -" Py_XDECREF(const_one);\n" -" Py_XDECREF(incremented_item);\n" -"\n" -" return rv; /* -1 for error, 0 for success */\n" -"}" -msgstr "" - -#: ../../c-api/intro.rst:772 -msgid "" -"This example represents an endorsed use of the ``goto`` statement in C! It " -"illustrates the use of :c:func:`PyErr_ExceptionMatches` and :c:func:" -"`PyErr_Clear` to handle specific exceptions, and the use of :c:func:" -"`Py_XDECREF` to dispose of owned references that may be ``NULL`` (note the " -"``'X'`` in the name; :c:func:`Py_DECREF` would crash when confronted with a " -"``NULL`` reference). It is important that the variables used to hold owned " -"references are initialized to ``NULL`` for this to work; likewise, the " -"proposed return value is initialized to ``-1`` (failure) and only set to " -"success after the final call made is successful." -msgstr "" -"這個例子代表了在 C 語言中對使用 ``goto`` 陳述句的認同！它闡述了以 :c:func:" -"`PyErr_ExceptionMatches` 和 :c:func:`PyErr_Clear` 來處理特定的例外，以及以 :" -"c:func:`Py_XDECREF` 來配置其所擁有且可能為 ``NULL`` 的參照（注意名稱中的 " -"``'X'``\\ ；:c:func:`Py_DECREF` 在遇到 ``NULL`` 參照時會崩潰）。重要的是，用" -"於保存擁有的參照的變數被初始化為 ``NULL`` 以使其能夠順利作用；同樣地，回傳值" -"被初始化為 ``-1``\\ （失敗），並且僅在最後一次呼叫成功後才設定為成功。" - -#: ../../c-api/intro.rst:786 -msgid "Embedding Python" -msgstr "嵌入式Python" - -#: ../../c-api/intro.rst:788 -msgid "" -"The one important task that only embedders (as opposed to extension writers) " -"of the Python interpreter have to worry about is the initialization, and " -"possibly the finalization, of the Python interpreter. Most functionality of " -"the interpreter can only be used after the interpreter has been initialized." -msgstr "" -"只有 Python 直譯器的嵌入者（而不是擴充編寫者）需要擔心的一項重要任務是 " -"Python 直譯器的初始化與完成階段。直譯器的大部分功能只能在直譯器初始化後使用。" - -#: ../../c-api/intro.rst:801 -msgid "" -"The basic initialization function is :c:func:`Py_Initialize`. This " -"initializes the table of loaded modules, and creates the fundamental " -"modules :mod:`builtins`, :mod:`__main__`, and :mod:`sys`. It also " -"initializes the module search path (``sys.path``)." -msgstr "" -"基本的初始化函式是 :c:func:`Py_Initialize`。這會初始化帶有載入模組的表，並建" -"立基礎模組 :mod:`builtins`、:mod:`__main__` 和 :mod:`sys`。它還會初始化模組搜" -"索路徑 (``sys.path``)。" - -#: ../../c-api/intro.rst:806 -msgid "" -":c:func:`Py_Initialize` does not set the \"script argument list\" (``sys." -"argv``). If this variable is needed by Python code that will be executed " -"later, setting :c:member:`PyConfig.argv` and :c:member:`PyConfig.parse_argv` " -"must be set: see :ref:`Python Initialization Configuration `." -msgstr "" -":c:func:`Py_Initialize` 不設定「腳本引數列表 (script argument list)」 (``sys." -"argv``)。如果稍後將要執行的 Python 程式碼需要此變數，則必須設定 :c:member:" -"`PyConfig.argv` 和 :c:member:`PyConfig.parse_argv`，請見 :ref:`Python 初始化" -"配置 `。" - -#: ../../c-api/intro.rst:811 -msgid "" -"On most systems (in particular, on Unix and Windows, although the details " -"are slightly different), :c:func:`Py_Initialize` calculates the module " -"search path based upon its best guess for the location of the standard " -"Python interpreter executable, assuming that the Python library is found in " -"a fixed location relative to the Python interpreter executable. In " -"particular, it looks for a directory named :file:`lib/python{X.Y}` relative " -"to the parent directory where the executable named :file:`python` is found " -"on the shell command search path (the environment variable :envvar:`PATH`)." -msgstr "" -"在大多數系統上（特別是在 Unix 和 Windows 上，儘管細節略有不同），:c:func:" -"`Py_Initialize` 會假設Python 函式庫相對於 Python 直譯器可執行檔案的位置固定，" -"並根據其對標準 Python 直譯器可執行檔案位置的最佳猜測來計算模組搜尋路徑。或者" -"更詳細地說，它會在 shell 命令搜尋路徑（環境變數 :envvar:`PATH`）中找到名為 :" -"file:`python` 的可執行檔案，並在其父目錄中查找一個名為 :file:`lib/python{X.Y}" -"` 的目錄的相對位置。" - -#: ../../c-api/intro.rst:820 -msgid "" -"For instance, if the Python executable is found in :file:`/usr/local/bin/" -"python`, it will assume that the libraries are in :file:`/usr/local/lib/" -"python{X.Y}`. (In fact, this particular path is also the \"fallback\" " -"location, used when no executable file named :file:`python` is found along :" -"envvar:`PATH`.) The user can override this behavior by setting the " -"environment variable :envvar:`PYTHONHOME`, or insert additional directories " -"in front of the standard path by setting :envvar:`PYTHONPATH`." -msgstr "" -"例如，如果在 :file:`/usr/local/bin/python` 中找到 Python 可執行檔案，它將假定" -"函式庫位於 :file:`/usr/local/lib/python{X.Y}` 中。（事實上這個特定的路徑也是" -"「後備 (fallback)」位置，當在 :envvar:`PATH` 中找不到名為 :file:`python` 的可" -"執行檔案時使用。）使用者可以透過設定環境變數來覆蓋此行為 :envvar:" -"`PYTHONHOME`，或者透過設定 :envvar:`PYTHONPATH` 在標準路徑前面插入額外的目" -"錄。" - -#: ../../c-api/intro.rst:834 -msgid "" -"The embedding application can steer the search by setting :c:member:" -"`PyConfig.program_name` *before* calling :c:func:`Py_InitializeFromConfig`. " -"Note that :envvar:`PYTHONHOME` still overrides this and :envvar:`PYTHONPATH` " -"is still inserted in front of the standard path. An application that " -"requires total control has to provide its own implementation of :c:func:" -"`Py_GetPath`, :c:func:`Py_GetPrefix`, :c:func:`Py_GetExecPrefix`, and :c:" -"func:`Py_GetProgramFullPath` (all defined in :file:`Modules/getpath.c`)." -msgstr "" -"嵌入的應用程式可以透過在呼叫 :c:func:`Py_InitializeFromConfig` *之前*\\ 設" -"定 :c:member:`PyConfig.program_name` 來引導搜尋。請注意 :envvar:`PYTHONHOME` " -"仍然覆蓋它並且 :envvar:`PYTHONPATH` 仍然插入在標準路徑的前面。需要完全控制權" -"的應用程式必須實作自己的 :c:func:`Py_GetPath`、:c:func:`Py_GetPrefix`、:c:" -"func:`Py_GetExecPrefix` 和 :c:func:`Py_GetProgramFullPath`\\（全部定義在 :" -"file:`Modules/getpath.c`)。" - -#: ../../c-api/intro.rst:845 -msgid "" -"Sometimes, it is desirable to \"uninitialize\" Python. For instance, the " -"application may want to start over (make another call to :c:func:" -"`Py_Initialize`) or the application is simply done with its use of Python " -"and wants to free memory allocated by Python. This can be accomplished by " -"calling :c:func:`Py_FinalizeEx`. The function :c:func:`Py_IsInitialized` " -"returns true if Python is currently in the initialized state. More " -"information about these functions is given in a later chapter. Notice that :" -"c:func:`Py_FinalizeEx` does *not* free all memory allocated by the Python " -"interpreter, e.g. memory allocated by extension modules currently cannot be " -"released." -msgstr "" -"有時會希望能夠「取消初始化 (uninitialize)」Python。例如，應用程式可能想要重新" -"開始（再次呼叫 :c:func:`Py_Initialize`）或者應用程式簡單地完成了對 Python 的" -"使用並想要釋放 Python 分配的記憶體。這可以透過呼叫 :c:func:`Py_FinalizeEx` 來" -"完成。如果 Python 目前處於初始化狀態，函式 :c:func:`Py_IsInitialized` 會回傳 " -"true。有關這些功能的更多資訊將在後面的章節中給出。請注意 :c:func:" -"`Py_FinalizeEx` *不會*\\ 釋放由 Python 直譯器分配的所有記憶體，例如目前無法釋" -"放被擴充模組所分配的記憶體。" - -#: ../../c-api/intro.rst:859 -msgid "Debugging Builds" -msgstr "除錯建置" - -#: ../../c-api/intro.rst:861 -msgid "" -"Python can be built with several macros to enable extra checks of the " -"interpreter and extension modules. These checks tend to add a large amount " -"of overhead to the runtime so they are not enabled by default." -msgstr "" -"Python 可以在建置時使用多個巨集來啟用對直譯器和擴充模組的額外檢查，這些檢查往" -"往會在執行環境 (runtime) 增加大量開銷 (overhead)，因此預設情況下不啟用它們。" - -#: ../../c-api/intro.rst:865 -msgid "" -"A full list of the various types of debugging builds is in the file :file:" -"`Misc/SpecialBuilds.txt` in the Python source distribution. Builds are " -"available that support tracing of reference counts, debugging the memory " -"allocator, or low-level profiling of the main interpreter loop. Only the " -"most frequently used builds will be described in the remainder of this " -"section." -msgstr "" -"Python 原始碼發佈版本中的 :file:`Misc/SpecialBuilds.txt` 檔案有一份包含多種除" -"錯構置的完整列表，為支援追蹤參照計數、為記憶體分配器除錯或對主直譯器迴圈進行" -"低階分析的建置。本節的其餘部分將僅描述最常用的建置。" - -#: ../../c-api/intro.rst:873 -msgid "" -"Compiling the interpreter with the :c:macro:`!Py_DEBUG` macro defined " -"produces what is generally meant by :ref:`a debug build of Python `. :c:macro:`!Py_DEBUG` is enabled in the Unix build by adding :option:" -"`--with-pydebug` to the :file:`./configure` command. It is also implied by " -"the presence of the not-Python-specific :c:macro:`!_DEBUG` macro. When :c:" -"macro:`!Py_DEBUG` is enabled in the Unix build, compiler optimization is " -"disabled." -msgstr "" -"使用定義的 :c:macro:`!Py_DEBUG` 巨集編譯直譯器會生成 :ref:`Python 的除錯建置 " -"`。 :c:macro:`!Py_DEBUG` 在 Unix 建置中要透過在 :file:`./" -"configure` 命令中加入 :option:`--with-pydebug` 來啟用。非 Python 限定的 :c:" -"macro:`!_DEBUG` 巨集的存在也暗示了這一點。當 :c:macro:`!Py_DEBUG` 在 Unix 建" -"置中啟用時，編譯器最佳化會被禁用。" - -#: ../../c-api/intro.rst:881 -msgid "" -"In addition to the reference count debugging described below, extra checks " -"are performed, see :ref:`Python Debug Build `." -msgstr "" -"除了下面描述的參照計數除錯之外，還會執行額外的檢查，請參閱 :ref:`Python 除錯" -"建置 `。" - -#: ../../c-api/intro.rst:884 -msgid "" -"Defining :c:macro:`Py_TRACE_REFS` enables reference tracing (see the :option:" -"`configure --with-trace-refs option <--with-trace-refs>`). When defined, a " -"circular doubly linked list of active objects is maintained by adding two " -"extra fields to every :c:type:`PyObject`. Total allocations are tracked as " -"well. Upon exit, all existing references are printed. (In interactive mode " -"this happens after every statement run by the interpreter.)" -msgstr "" -"定義 :c:macro:`Py_TRACE_REFS` 來啟用參照追蹤（參見\\ :option:`設定 --with-" -"trace-refs 選項 <--with-trace-refs>`）。當有定義時，透過向每個 :c:type:" -"`PyObject` 新增兩個額外欄位來維護有效物件的循環雙向鍊表 (circular doubly " -"linked list)。全體分配也有被追蹤。退出時將印出所有現行參照。（在交互模式下，" -"這發生在直譯器運行的每個陳述句之後。）" - -#: ../../c-api/intro.rst:891 -msgid "" -"Please refer to :file:`Misc/SpecialBuilds.txt` in the Python source " -"distribution for more detailed information." -msgstr "" -"有關更多詳細資訊，請參閱 Python 原始碼發布版中的 :file:`Misc/SpecialBuilds." -"txt`。" - -#: ../../c-api/intro.rst:898 -msgid "Recommended third party tools" -msgstr "建議的第三方工具" - -#: ../../c-api/intro.rst:900 -msgid "" -"The following third party tools offer both simpler and more sophisticated " -"approaches to creating C, C++ and Rust extensions for Python:" -msgstr "" -"以下第三方工具提供了更簡單且更細緻的方法來為 Python 建立 C、C++ 和 Rust 擴充" -"模組：" - -#: ../../c-api/intro.rst:903 -msgid "`Cython `_" -msgstr "`Cython `_" - -#: ../../c-api/intro.rst:904 -msgid "`cffi `_" -msgstr "`cffi `_" - -#: ../../c-api/intro.rst:905 -msgid "`HPy `_" -msgstr "`HPy `_" - -#: ../../c-api/intro.rst:906 -msgid "`nanobind `_ (C++)" -msgstr "`nanobind `_ (C++)" - -#: ../../c-api/intro.rst:907 -msgid "`Numba `_" -msgstr "`Numba `_" - -#: ../../c-api/intro.rst:908 -msgid "`pybind11 `_ (C++)" -msgstr "`pybind11 `_ (C++)" - -#: ../../c-api/intro.rst:909 -msgid "`PyO3 `_ (Rust)" -msgstr "`PyO3 `_ (Rust)" - -#: ../../c-api/intro.rst:910 -msgid "`SWIG `_" -msgstr "`SWIG `_" - -#: ../../c-api/intro.rst:912 -msgid "" -"Using tools such as these can help avoid writing code that is tightly bound " -"to a particular version of CPython, avoid reference counting errors, and " -"focus more on your own code than on using the CPython API. In general, new " -"versions of Python can be supported by updating the tool, and your code will " -"often use newer and more efficient APIs automatically. Some tools also " -"support compiling for other implementations of Python from a single set of " -"sources." -msgstr "" - -#: ../../c-api/intro.rst:919 -msgid "" -"These projects are not supported by the same people who maintain Python, and " -"issues need to be raised with the projects directly. Remember to check that " -"the project is still maintained and supported, as the list above may become " -"outdated." -msgstr "" - -#: ../../c-api/intro.rst:926 -msgid "" -"`Python Packaging User Guide: Binary Extensions `_" -msgstr "" - -#: ../../c-api/intro.rst:927 -msgid "" -"The Python Packaging User Guide not only covers several available tools that " -"simplify the creation of binary extensions, but also discusses the various " -"reasons why creating an extension module may be desirable in the first place." -msgstr "" - -#: ../../c-api/intro.rst:344 -msgid "object" -msgstr "object（物件）" - -#: ../../c-api/intro.rst:344 -msgid "type" -msgstr "type（型別）" - -#: ../../c-api/intro.rst:383 -msgid "Py_INCREF (C function)" -msgstr "Py_INCREF（C 函式）" - -#: ../../c-api/intro.rst:383 -msgid "Py_DECREF (C function)" -msgstr "Py_DECREF（C 函式）" - -#: ../../c-api/intro.rst:459 -msgid "PyList_SetItem (C function)" -msgstr "PyList_SetItem（C 函式）" - -#: ../../c-api/intro.rst:459 -msgid "PyTuple_SetItem (C function)" -msgstr "PyTuple_SetItem（C 函式）" - -#: ../../c-api/intro.rst:530 -msgid "set_all()" -msgstr "set_all()" - -#: ../../c-api/intro.rst:549 -msgid "PyList_GetItem (C function)" -msgstr "PyList_GetItem（C 函式）" - -#: ../../c-api/intro.rst:549 -msgid "PySequence_GetItem (C function)" -msgstr "PySequence_GetItem（C 函式）" - -#: ../../c-api/intro.rst:579 -msgid "sum_list()" -msgstr "sum_list()" - -#: ../../c-api/intro.rst:611 ../../c-api/intro.rst:703 -msgid "sum_sequence()" -msgstr "sum_sequence()" - -#: ../../c-api/intro.rst:646 -msgid "PyErr_Occurred (C function)" -msgstr "PyErr_Occurred（C 函式）" - -#: ../../c-api/intro.rst:659 -msgid "PyErr_SetString (C function)" -msgstr "PyErr_SetString（C 函式）" - -#: ../../c-api/intro.rst:659 ../../c-api/intro.rst:767 -msgid "PyErr_Clear (C function)" -msgstr "PyErr_Clear（C 函式）" - -#: ../../c-api/intro.rst:683 -msgid "exc_info (in module sys)" -msgstr "exc_info （sys 模組中）" - -#: ../../c-api/intro.rst:718 ../../c-api/intro.rst:765 -msgid "incr_item()" -msgstr "incr_item()" - -#: ../../c-api/intro.rst:767 -msgid "PyErr_ExceptionMatches (C function)" -msgstr "PyErr_ExceptionMatches（C 函式）" - -#: ../../c-api/intro.rst:767 -msgid "Py_XDECREF (C function)" -msgstr "Py_XDECREF（C 函式）" - -#: ../../c-api/intro.rst:793 -msgid "Py_Initialize (C function)" -msgstr "Py_Initialize（C 函式）" - -#: ../../c-api/intro.rst:793 -msgid "module" -msgstr "module（模組）" - -#: ../../c-api/intro.rst:793 -msgid "builtins" -msgstr "builtins（內建）" - -#: ../../c-api/intro.rst:793 -msgid "__main__" -msgstr "__main__" - -#: ../../c-api/intro.rst:793 -msgid "sys" -msgstr "sys" - -#: ../../c-api/intro.rst:793 -msgid "search" -msgstr "search（搜尋）" - -#: ../../c-api/intro.rst:793 -msgid "path" -msgstr "path（路徑）" - -#: ../../c-api/intro.rst:793 -msgid "path (in module sys)" -msgstr "path（sys 模組中）" - -#: ../../c-api/intro.rst:828 -msgid "Py_GetPath (C function)" -msgstr "Py_GetPath（C 函式）" - -#: ../../c-api/intro.rst:828 -msgid "Py_GetPrefix (C function)" -msgstr "Py_GetPrefix（C 函式）" - -#: ../../c-api/intro.rst:828 -msgid "Py_GetExecPrefix (C function)" -msgstr "Py_GetExecPrefix（C 函式）" - -#: ../../c-api/intro.rst:828 -msgid "Py_GetProgramFullPath (C function)" -msgstr "Py_GetProgramFullPath（C 函式）" - -#: ../../c-api/intro.rst:843 -msgid "Py_IsInitialized (C function)" -msgstr "Py_IsInitialized（C 函式）" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Matt Wang , 2023 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-25 00:13+0000\n" +"PO-Revision-Date: 2023-04-25 18:01+0800\n" +"Last-Translator: Matt Wang \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" +"X-Generator: Poedit 3.2.2\n" + +#: ../../c-api/intro.rst:8 +msgid "Introduction" +msgstr "簡介" + +#: ../../c-api/intro.rst:10 +msgid "" +"The Application Programmer's Interface to Python gives C and C++ programmers " +"access to the Python interpreter at a variety of levels. The API is equally " +"usable from C++, but for brevity it is generally referred to as the Python/C " +"API. There are two fundamentally different reasons for using the Python/C " +"API. The first reason is to write *extension modules* for specific purposes; " +"these are C modules that extend the Python interpreter. This is probably " +"the most common use. The second reason is to use Python as a component in a " +"larger application; this technique is generally referred to as :dfn:" +"`embedding` Python in an application." +msgstr "" +"對於 Python 的應用程式開發介面使得 C 和 C++ 開發者能夠在各種層級存取 Python " +"直譯器。該 API 同樣可用於 C++，但為簡潔起見，通常將其稱為 Python/C API。使用 " +"Python/C API 有兩個不同的原因，第一個是為特定目的來編寫\\ *擴充模組*；這些是" +"擴充 Python 直譯器的 C 模組，這可能是最常見的用法。第二個原因是在更大的應用程" +"式中將 Python 作為零件使用；這種技術通常在應用程式中稱為 :dfn:`embedding`\\ " +"（嵌入式）Python。" + +#: ../../c-api/intro.rst:20 +msgid "" +"Writing an extension module is a relatively well-understood process, where a " +"\"cookbook\" approach works well. There are several tools that automate the " +"process to some extent. While people have embedded Python in other " +"applications since its early existence, the process of embedding Python is " +"less straightforward than writing an extension." +msgstr "" +"編寫擴充模組是一個相對容易理解的過程，其中「食譜 (cookbook)」方法很有效。有幾" +"種工具可以在一定程度上自動化該過程，儘管人們從早期就將 Python 嵌入到其他應用" +"程式中，但嵌入 Python 的過程並不像編寫擴充那樣簡單。" + +#: ../../c-api/intro.rst:26 +msgid "" +"Many API functions are useful independent of whether you're embedding or " +"extending Python; moreover, most applications that embed Python will need " +"to provide a custom extension as well, so it's probably a good idea to " +"become familiar with writing an extension before attempting to embed Python " +"in a real application." +msgstr "" +"不論你是嵌入還是擴充 Python，許多 API 函式都是很有用的；此外，大多數嵌入 " +"Python 的應用程式也需要提供自訂擴充模組，因此在嘗試將 Python 嵌入實際應用程" +"式之前熟悉編寫擴充可能是個好主意。" + +#: ../../c-api/intro.rst:34 +msgid "Language version compatibility" +msgstr "語言版本相容性" + +#: ../../c-api/intro.rst:36 +msgid "Python's C API is compatible with C11 and C++11 versions of C and C++." +msgstr "Python 的 C API 與 C11 和 C++11 版本的 C 和 C++ 相容。" + +#: ../../c-api/intro.rst:38 +msgid "" +"This is a lower limit: the C API does not require features from later C/C++ " +"versions. You do *not* need to enable your compiler's \"c11 mode\"." +msgstr "" + +#: ../../c-api/intro.rst:44 +msgid "Coding standards" +msgstr "編寫標準" + +#: ../../c-api/intro.rst:46 +msgid "" +"If you're writing C code for inclusion in CPython, you **must** follow the " +"guidelines and standards defined in :PEP:`7`. These guidelines apply " +"regardless of the version of Python you are contributing to. Following " +"these conventions is not necessary for your own third party extension " +"modules, unless you eventually expect to contribute them to Python." +msgstr "" +"如果你正在編寫要引入於 CPython 中的 C 程式碼，你\\ **必須**\\ 遵循 :PEP:`7` " +"中定義的指南和標準。無論你貢獻的 Python 版本如何，這些指南都適用。對於你自己" +"的第三方擴充模組，則不必遵循這些約定，除非你希望最終將它們貢獻給 Python。" + +#: ../../c-api/intro.rst:56 +msgid "Include Files" +msgstr "引入檔案 (include files)" + +#: ../../c-api/intro.rst:58 +msgid "" +"All function, type and macro definitions needed to use the Python/C API are " +"included in your code by the following line::" +msgstr "" +"使用 Python/C API 所需的所有函式、型別和巨集的定義都透過以下這幾行來在你的程" +"式碼中引入：" + +#: ../../c-api/intro.rst:61 +msgid "" +"#define PY_SSIZE_T_CLEAN\n" +"#include " +msgstr "" +"#define PY_SSIZE_T_CLEAN\n" +"#include " + +#: ../../c-api/intro.rst:64 +msgid "" +"This implies inclusion of the following standard headers: ````, " +"````, ````, ````, ```` and ```` (if available)." +msgstr "" +"這意味著會引入以下標準標頭：````、````、````、" +"````、```` 和 ````\\ （如果可用）。" + +#: ../../c-api/intro.rst:70 +msgid "" +"Since Python may define some pre-processor definitions which affect the " +"standard headers on some systems, you *must* include :file:`Python.h` before " +"any standard headers are included." +msgstr "" +"由於 Python 可能會定義一些會影響某些系統上標準標頭檔的預處理器 (pre-" +"processor)，因此你\\ *必須*\\ 在引入任何標準標頭檔之前引入 :file:`Python.h`。" + +#: ../../c-api/intro.rst:74 +msgid "" +"It is recommended to always define ``PY_SSIZE_T_CLEAN`` before including " +"``Python.h``. See :ref:`arg-parsing` for a description of this macro." +msgstr "" +"建議在引入 ``Python.h`` 之前都要定義 ``PY_SSIZE_T_CLEAN``。有關此巨集的說明，" +"請參閱\\ :ref:`arg-parsing`。" + +#: ../../c-api/intro.rst:77 +msgid "" +"All user visible names defined by Python.h (except those defined by the " +"included standard headers) have one of the prefixes ``Py`` or ``_Py``. " +"Names beginning with ``_Py`` are for internal use by the Python " +"implementation and should not be used by extension writers. Structure member " +"names do not have a reserved prefix." +msgstr "" +"所有定義於 Python.h 中且使用者可見的名稱（另外透過標準標頭檔引入的除外）都具" +"有 ``Py`` 或 ``_Py`` 前綴。以 ``_Py`` 開頭的名稱供 Python 實作內部使用，擴充" +"編寫者不應使用。結構成員名稱沒有保留前綴。" + +#: ../../c-api/intro.rst:84 +msgid "" +"User code should never define names that begin with ``Py`` or ``_Py``. This " +"confuses the reader, and jeopardizes the portability of the user code to " +"future Python versions, which may define additional names beginning with one " +"of these prefixes." +msgstr "" +"使用者程式碼不應定義任何以 ``Py`` 或 ``_Py`` 開頭的名稱。這會讓讀者感到困惑，" +"並危及使用者程式碼在未來 Python 版本上的可移植性，這些版本可能會定義以這些前" +"綴之一開頭的其他名稱。" + +#: ../../c-api/intro.rst:89 +msgid "" +"The header files are typically installed with Python. On Unix, these are " +"located in the directories :file:`{prefix}/include/pythonversion/` and :file:" +"`{exec_prefix}/include/pythonversion/`, where :option:`prefix <--prefix>` " +"and :option:`exec_prefix <--exec-prefix>` are defined by the corresponding " +"parameters to Python's :program:`configure` script and *version* is ``'%d." +"%d' % sys.version_info[:2]``. On Windows, the headers are installed in :" +"file:`{prefix}/include`, where ``prefix`` is the installation directory " +"specified to the installer." +msgstr "" +"標頭檔通常隨 Python 一起安裝。在 Unix 上它們位於目錄 :file:`{prefix}/include/" +"pythonversion/` 和 :file:`{exec_prefix}/include/pythonversion/`，其中 :" +"option:`prefix <--prefix>` 和 :option:`exec_prefix <--exec-prefix>` 由 " +"Python 的 :program:`configure` 腳本的相應參數定義，*version* 是 ``'%d.%d' % " +"sys.version_info[:2]``。在 Windows 上，標頭安裝在 :file:`{prefix}/include` " +"中，其中 ``prefix`` 是指定給安裝程式 (installer) 用的安裝目錄。" + +#: ../../c-api/intro.rst:98 +msgid "" +"To include the headers, place both directories (if different) on your " +"compiler's search path for includes. Do *not* place the parent directories " +"on the search path and then use ``#include ``; this will " +"break on multi-platform builds since the platform independent headers under :" +"option:`prefix <--prefix>` include the platform specific headers from :" +"option:`exec_prefix <--exec-prefix>`." +msgstr "" +"要引入標頭，請將兩個（如果不同）目錄放在編譯器的引入搜尋路徑 (search path) " +"中。*不要*\\ 將父目錄放在搜尋路徑上，然後使用 ``#include ``；這會在多平台建置上壞掉，因為 :option:`prefix <--prefix>` 下獨立於平台的" +"標頭包括來自 :option:`exec_prefix <--exec-prefix>` 的平台特定標頭。" + +#: ../../c-api/intro.rst:105 +msgid "" +"C++ users should note that although the API is defined entirely using C, the " +"header files properly declare the entry points to be ``extern \"C\"``. As a " +"result, there is no need to do anything special to use the API from C++." +msgstr "" +"C++ 使用者應注意，儘管 API 完全使用 C 來定義，但標頭檔適當地將入口點聲明為 " +"``extern \"C\"``。因此，無需執行任何特殊操作即可使用 C++ 中的 API。" + +#: ../../c-api/intro.rst:111 +msgid "Useful macros" +msgstr "有用的巨集" + +#: ../../c-api/intro.rst:113 +msgid "" +"Several useful macros are defined in the Python header files. Many are " +"defined closer to where they are useful (for example, :c:macro:" +"`Py_RETURN_NONE`, :c:macro:`PyMODINIT_FUNC`). Others of a more general " +"utility are defined here. This is not necessarily a complete listing." +msgstr "" +"Python 標頭檔中定義了幾個有用的巨集，大多被定義在它們有用的地方附近（例如 :c:" +"macro:`Py_RETURN_NONE`、:c:macro:`PyMODINIT_FUNC`），其他是更通用的工具程式。" +"以下並不一定是完整的列表。" + +#: ../../c-api/intro.rst:122 +msgid "Return the absolute value of ``x``." +msgstr "回傳 ``x`` 的絕對值。" + +#: ../../c-api/intro.rst:124 +msgid "" +"If the result cannot be represented (for example, if ``x`` has :c:macro:`!" +"INT_MIN` value for :c:expr:`int` type), the behavior is undefined." +msgstr "" + +#: ../../c-api/intro.rst:132 +msgid "" +"Ask the compiler to always inline a static inline function. The compiler can " +"ignore it and decide to not inline the function." +msgstr "" +"要求編譯器總是嵌入靜態行內函式 (static inline function)，編譯器可以忽略它並決" +"定不嵌入該函式。" + +#: ../../c-api/intro.rst:135 +msgid "" +"It can be used to inline performance critical static inline functions when " +"building Python in debug mode with function inlining disabled. For example, " +"MSC disables function inlining when building in debug mode." +msgstr "" +"在禁用函式嵌入的除錯模式下建置 Python 時，它可用於嵌入有性能要求的靜態行內函" +"式。例如，MSC 在除錯模式下建置時禁用函式嵌入。" + +#: ../../c-api/intro.rst:139 +msgid "" +"Marking blindly a static inline function with Py_ALWAYS_INLINE can result in " +"worse performances (due to increased code size for example). The compiler is " +"usually smarter than the developer for the cost/benefit analysis." +msgstr "" +"盲目地使用 Py_ALWAYS_INLINE 標記靜態行內函式可能會導致更差的性能（例如程式碼" +"大小增加）。在成本/收益分析方面，編譯器通常比開發人員更聰明。" + +#: ../../c-api/intro.rst:143 +msgid "" +"If Python is :ref:`built in debug mode ` (if the :c:macro:" +"`Py_DEBUG` macro is defined), the :c:macro:`Py_ALWAYS_INLINE` macro does " +"nothing." +msgstr "" +"如果 Python 是\\ :ref:`在除錯模式下建置 `\\ （如果 :c:macro:" +"`Py_DEBUG` 巨集有被定義），:c:macro:`Py_ALWAYS_INLINE` 巨集就什麼都不會做。" + +#: ../../c-api/intro.rst:146 +msgid "It must be specified before the function return type. Usage::" +msgstr "它必須在函式回傳型別之前被指定。用法： ::" + +#: ../../c-api/intro.rst:148 +msgid "static inline Py_ALWAYS_INLINE int random(void) { return 4; }" +msgstr "static inline Py_ALWAYS_INLINE int random(void) { return 4; }" + +#: ../../c-api/intro.rst:154 +msgid "" +"Argument must be a character or an integer in the range [-128, 127] or [0, " +"255]. This macro returns ``c`` cast to an ``unsigned char``." +msgstr "" +"引數必須是 [-128, 127] 或 [0, 255] 範圍內的字元或整數。這個巨集會將 ``c`` 轉" +"換為 ``unsigned char`` 並回傳。" + +#: ../../c-api/intro.rst:159 +msgid "" +"Use this for deprecated declarations. The macro must be placed before the " +"symbol name." +msgstr "將其用於已棄用的聲明。巨集必須放在符號名稱之前。" + +#: ../../c-api/intro.rst:162 ../../c-api/intro.rst:290 +#: ../../c-api/intro.rst:308 +msgid "Example::" +msgstr "範例： ::" + +#: ../../c-api/intro.rst:164 +msgid "Py_DEPRECATED(3.8) PyAPI_FUNC(int) Py_OldFunction(void);" +msgstr "Py_DEPRECATED(3.8) PyAPI_FUNC(int) Py_OldFunction(void);" + +#: ../../c-api/intro.rst:166 +msgid "MSVC support was added." +msgstr "新增了 MSVC 支援。" + +#: ../../c-api/intro.rst:171 +msgid "" +"Like ``getenv(s)``, but returns ``NULL`` if :option:`-E` was passed on the " +"command line (see :c:member:`PyConfig.use_environment`)." +msgstr "" +"類似於 ``getenv(s)``，但如果在命令列上傳遞了 :option:`-E` 則回傳 ``NULL`` " +"（請見 :c:member:`PyConfig.use_environment`）。" + +#: ../../c-api/intro.rst:176 +msgid "" +"Declare a function returning the specified *type* using a fast-calling " +"qualifier for functions that are local to the current file. Semantically, " +"this is equivalent to ``static type``." +msgstr "" + +#: ../../c-api/intro.rst:182 +msgid "" +"Equivalent to :c:macro:`Py_LOCAL` but additionally requests the function be " +"inlined." +msgstr "" + +#: ../../c-api/intro.rst:187 +msgid "Return the maximum value between ``x`` and ``y``." +msgstr "回傳 ``x`` 和 ``y`` 之間的最大值。" + +#: ../../c-api/intro.rst:193 +msgid "Return the size of a structure (``type``) ``member`` in bytes." +msgstr "以位元組為單位回傳結構 (``type``) ``member`` 的大小。" + +#: ../../c-api/intro.rst:199 +msgid "" +"This is a :term:`soft deprecated` alias to :c:func:`!memcpy`. Use :c:func:`!" +"memcpy` directly instead." +msgstr "" +"這是 :c:func:`!memcpy` 的已\\ :term:`軟性棄用 `\\ 別名。請直" +"接使用 :c:func:`!memcpy`。" + +#: ../../c-api/intro.rst:202 +msgid "The macro is :term:`soft deprecated`." +msgstr "這個巨集已被\\ :term:`軟性棄用 `。" + +#: ../../c-api/intro.rst:207 +msgid "Return the minimum value between ``x`` and ``y``." +msgstr "回傳 ``x`` 和 ``y`` 之間的最小值。" + +#: ../../c-api/intro.rst:213 +msgid "" +"Disable inlining on a function. For example, it reduces the C stack " +"consumption: useful on LTO+PGO builds which heavily inline code (see :issue:" +"`33720`)." +msgstr "" +"禁用函式的嵌入。例如，它減少了 C 堆疊的消耗：對大量嵌入程式碼的 LTO+PGO 建置" +"很有用（請參閱 :issue:`33720`）。" + +#: ../../c-api/intro.rst:217 +msgid "Usage::" +msgstr "用法： ::" + +#: ../../c-api/intro.rst:219 +msgid "Py_NO_INLINE static int random(void) { return 4; }" +msgstr "Py_NO_INLINE static int random(void) { return 4; }" + +#: ../../c-api/intro.rst:225 +msgid "" +"Convert ``x`` to a C string. E.g. ``Py_STRINGIFY(123)`` returns ``\"123\"``." +msgstr "" +"將 ``x`` 轉換為 C 字串。例如 ``Py_STRINGIFY(123)`` 會回傳 ``\"123\"``。" + +#: ../../c-api/intro.rst:232 +msgid "" +"Use this when you have a code path that cannot be reached by design. For " +"example, in the ``default:`` clause in a ``switch`` statement for which all " +"possible values are covered in ``case`` statements. Use this in places " +"where you might be tempted to put an ``assert(0)`` or ``abort()`` call." +msgstr "" +"當你的設計中有無法達到的程式碼路徑時，請使用此選項。例如在 ``case`` 語句已涵" +"蓋了所有可能值的 ``switch`` 陳述式中的 ``default:`` 子句。在你可能想要呼叫 " +"``assert(0)`` 或 ``abort()`` 的地方使用它。" + +#: ../../c-api/intro.rst:237 +msgid "" +"In release mode, the macro helps the compiler to optimize the code, and " +"avoids a warning about unreachable code. For example, the macro is " +"implemented with ``__builtin_unreachable()`` on GCC in release mode." +msgstr "" +"在發布模式 (release mode) 下，巨集幫助編譯器最佳化程式碼，並避免有關無法存取" +"程式碼的警告。例如該巨集是在發布模式下於 GCC 使用 " +"``__builtin_unreachable()`` 來實作。" + +#: ../../c-api/intro.rst:241 +msgid "" +"A use for ``Py_UNREACHABLE()`` is following a call a function that never " +"returns but that is not declared :c:macro:`_Py_NO_RETURN`." +msgstr "" +"``Py_UNREACHABLE()`` 的一個用途是，在對一個永不回傳但並未聲明為 :c:macro:" +"`_Py_NO_RETURN` 的函式之呼叫後使用。" + +#: ../../c-api/intro.rst:244 +msgid "" +"If a code path is very unlikely code but can be reached under exceptional " +"case, this macro must not be used. For example, under low memory condition " +"or if a system call returns a value out of the expected range. In this " +"case, it's better to report the error to the caller. If the error cannot be " +"reported to caller, :c:func:`Py_FatalError` can be used." +msgstr "" +"如果程式碼路徑是極不可能但在特殊情況下可以到達，則不得使用此巨集。例如在低記" +"憶體條件下或系統呼叫回傳了超出預期範圍的值。在這種情況下，最好將錯誤回報給呼" +"叫者。如果無法回報錯誤則可以使用 :c:func:`Py_FatalError`。" + +#: ../../c-api/intro.rst:254 +msgid "" +"Use this for unused arguments in a function definition to silence compiler " +"warnings. Example: ``int func(int a, int Py_UNUSED(b)) { return a; }``." +msgstr "" +"將此用於函式定義中未使用的參數以消除編譯器警告。例如：``int func(int a, int " +"Py_UNUSED(b)) { return a; }``。" + +#: ../../c-api/intro.rst:261 +msgid "" +"Asserts a compile-time condition *cond*, as a statement. The build will fail " +"if the condition is false or cannot be evaluated at compile time." +msgstr "" + +#: ../../c-api/intro.rst:264 ../../c-api/intro.rst:275 +#: ../../c-api/intro.rst:320 +msgid "For example::" +msgstr "範例： ::" + +#: ../../c-api/intro.rst:266 +msgid "Py_BUILD_ASSERT(sizeof(PyTime_t) == sizeof(int64_t));" +msgstr "Py_BUILD_ASSERT(sizeof(PyTime_t) == sizeof(int64_t));" + +#: ../../c-api/intro.rst:272 +msgid "" +"Asserts a compile-time condition *cond*, as an expression that evaluates to " +"``0``. The build will fail if the condition is false or cannot be evaluated " +"at compile time." +msgstr "" + +#: ../../c-api/intro.rst:277 +msgid "" +"#define foo_to_char(foo) \\\n" +" ((char *)(foo) + Py_BUILD_ASSERT_EXPR(offsetof(struct foo, string) == 0))" +msgstr "" +"#define foo_to_char(foo) \\\n" +" ((char *)(foo) + Py_BUILD_ASSERT_EXPR(offsetof(struct foo, string) == 0))" + +#: ../../c-api/intro.rst:284 +msgid "" +"Creates a variable with name *name* that can be used in docstrings. If " +"Python is built without docstrings, the value will be empty." +msgstr "" +"建立一個名為 *name* 的變數，可以在文件字串中使用。如果 Python 是在沒有文件字" +"串的情況下建置，則該值將為空。" + +#: ../../c-api/intro.rst:287 +msgid "" +"Use :c:macro:`PyDoc_STRVAR` for docstrings to support building Python " +"without docstrings, as specified in :pep:`7`." +msgstr "" +"如 :pep:`7` 中所指明，使用 :c:macro:`PyDoc_STRVAR` 作為文件字串可以支援在沒有" +"文件字串的情況下建置 Python。" + +#: ../../c-api/intro.rst:292 +msgid "" +"PyDoc_STRVAR(pop_doc, \"Remove and return the rightmost element.\");\n" +"\n" +"static PyMethodDef deque_methods[] = {\n" +" // ...\n" +" {\"pop\", (PyCFunction)deque_pop, METH_NOARGS, pop_doc},\n" +" // ...\n" +"}" +msgstr "" +"PyDoc_STRVAR(pop_doc, \"Remove and return the rightmost element.\");\n" +"\n" +"static PyMethodDef deque_methods[] = {\n" +" // ...\n" +" {\"pop\", (PyCFunction)deque_pop, METH_NOARGS, pop_doc},\n" +" // ...\n" +"}" + +#: ../../c-api/intro.rst:302 +msgid "" +"Creates a docstring for the given input string or an empty string if " +"docstrings are disabled." +msgstr "為給定的輸入字串建立一個文件字串，如果文件字串被禁用則建立空字串。" + +#: ../../c-api/intro.rst:305 +msgid "" +"Use :c:macro:`PyDoc_STR` in specifying docstrings to support building Python " +"without docstrings, as specified in :pep:`7`." +msgstr "" +"如 :pep:`7` 中所指明，使用 :c:macro:`PyDoc_STR` 指定文件字串以支援在沒有文件" +"字串下建置 Python。" + +#: ../../c-api/intro.rst:310 +msgid "" +"static PyMethodDef pysqlite_row_methods[] = {\n" +" {\"keys\", (PyCFunction)pysqlite_row_keys, METH_NOARGS,\n" +" PyDoc_STR(\"Returns the keys of the row.\")},\n" +" {NULL, NULL}\n" +"};" +msgstr "" +"static PyMethodDef pysqlite_row_methods[] = {\n" +" {\"keys\", (PyCFunction)pysqlite_row_keys, METH_NOARGS,\n" +" PyDoc_STR(\"Returns the keys of the row.\")},\n" +" {NULL, NULL}\n" +"};" + +#: ../../c-api/intro.rst:318 +msgid "Declares a static character array variable with the given name *name*." +msgstr "" + +#: ../../c-api/intro.rst:322 +msgid "" +"PyDoc_VAR(python_doc) = PyDoc_STR(\"A genus of constricting snakes in the " +"Pythonidae family native \"\n" +" \"to the tropics and subtropics of the " +"Eastern Hemisphere.\");" +msgstr "" +"PyDoc_VAR(python_doc) = PyDoc_STR(\"A genus of constricting snakes in the " +"Pythonidae family native \"\n" +" \"to the tropics and subtropics of the " +"Eastern Hemisphere.\");" + +#: ../../c-api/intro.rst:327 +msgid "Compute the length of a statically allocated C array at compile time." +msgstr "" + +#: ../../c-api/intro.rst:329 +msgid "" +"The *array* argument must be a C array with a size known at compile time. " +"Passing an array with an unknown size, such as a heap-allocated array, will " +"result in a compilation error on some compilers, or otherwise produce " +"incorrect results." +msgstr "" + +#: ../../c-api/intro.rst:334 +msgid "This is roughly equivalent to::" +msgstr "" + +#: ../../c-api/intro.rst:336 +msgid "sizeof(array) / sizeof((array)[0])" +msgstr "" + +#: ../../c-api/intro.rst:342 +msgid "Objects, Types and Reference Counts" +msgstr "物件、型別和參照計數" + +#: ../../c-api/intro.rst:346 +msgid "" +"Most Python/C API functions have one or more arguments as well as a return " +"value of type :c:expr:`PyObject*`. This type is a pointer to an opaque data " +"type representing an arbitrary Python object. Since all Python object types " +"are treated the same way by the Python language in most situations (e.g., " +"assignments, scope rules, and argument passing), it is only fitting that " +"they should be represented by a single C type. Almost all Python objects " +"live on the heap: you never declare an automatic or static variable of type :" +"c:type:`PyObject`, only pointer variables of type :c:expr:`PyObject*` can " +"be declared. The sole exception are the type objects; since these must " +"never be deallocated, they are typically static :c:type:`PyTypeObject` " +"objects." +msgstr "" +"大多數 Python/C API 函式都有一個或多個引數以及一個型別為 :c:expr:`PyObject*` " +"的回傳值，此型別是一個指標，指向一個表示任意 Python 物件的晦暗 (opaque) 資料" +"型別。由於在大多數情況下，Python 語言以相同的方式處理所有 Python 物件型別（例" +"如賦值、作用域規則和引數傳遞），因此它們應該由單個 C 型別來表示。幾乎所有的 " +"Python 物件都存在於堆積 (heap) 中：你永遠不會聲明 :c:type:`PyObject` 型別的自" +"動變數或靜態變數，只能聲明 :c:expr:`PyObject*` 型別的指標變數。唯一的例外是型" +"別物件；由於它們絕不能被釋放，因此它們通常是靜態 :c:type:`PyTypeObject` 物" +"件。" + +#: ../../c-api/intro.rst:357 +msgid "" +"All Python objects (even Python integers) have a :dfn:`type` and a :dfn:" +"`reference count`. An object's type determines what kind of object it is (e." +"g., an integer, a list, or a user-defined function; there are many more as " +"explained in :ref:`types`). For each of the well-known types there is a " +"macro to check whether an object is of that type; for instance, " +"``PyList_Check(a)`` is true if (and only if) the object pointed to by *a* is " +"a Python list." +msgstr "" +"所有 Python 物件（甚至是 Python 整數）都有一個型別 (:dfn:`type`) 和一個參照計" +"數 (:dfn:`reference count`)。一個物件的型別決定了它是什麼種類的物件（例如一個" +"整數、一個 list 或一個使用者定義的函式；還有更多型別，請見\\ :ref:" +"`types`\\ ）。對於每個眾所周知的型別，都有一個巨集來檢查物件是否屬於該型別；" +"例如，若（且唯若）*a* 指向的物件是 Python list 時，``PyList_Check(a)`` 為真。" + +#: ../../c-api/intro.rst:368 +msgid "Reference Counts" +msgstr "參照計數" + +#: ../../c-api/intro.rst:370 +msgid "" +"The reference count is important because today's computers have a finite " +"(and often severely limited) memory size; it counts how many different " +"places there are that have a :term:`strong reference` to an object. Such a " +"place could be another object, or a global (or static) C variable, or a " +"local variable in some C function. When the last :term:`strong reference` to " +"an object is released (i.e. its reference count becomes zero), the object is " +"deallocated. If it contains references to other objects, those references " +"are released. Those other objects may be deallocated in turn, if there are " +"no more references to them, and so on. (There's an obvious problem with " +"objects that reference each other here; for now, the solution is \"don't do " +"that.\")" +msgstr "" +"參照計數很重要，因為現今的電腦記憶體大小是有限的（而且通常是非常有限的）；它" +"計算有多少個不同的地方用有了一個物件的\\ :term:`強參照 `。" +"這樣的地方可以是另一個物件，或者全域（或靜態）C 變數，或者某個 C 函式中的本地" +"變數。當一個物件的最後一個\\ :term:`強參照 `\\ 被釋放時（即" +"其的參照計數變為零），該物件將被解除配置 (deallocated)。如果它包含對其他物件" +"的參照，則它們的參照會被釋放。如果這樣的釋放使得再也沒有任何對於它們的參照，" +"則可以依次為那些其他物件解除配置，依此類推。（此處相互參照物件的存在是個明顯" +"的問題；目前，解決方案是「就不要那樣做」。）" + +#: ../../c-api/intro.rst:387 +msgid "" +"Reference counts are always manipulated explicitly. The normal way is to " +"use the macro :c:func:`Py_INCREF` to take a new reference to an object (i.e. " +"increment its reference count by one), and :c:func:`Py_DECREF` to release " +"that reference (i.e. decrement the reference count by one). The :c:func:" +"`Py_DECREF` macro is considerably more complex than the incref one, since it " +"must check whether the reference count becomes zero and then cause the " +"object's deallocator to be called. The deallocator is a function pointer " +"contained in the object's type structure. The type-specific deallocator " +"takes care of releasing references for other objects contained in the object " +"if this is a compound object type, such as a list, as well as performing any " +"additional finalization that's needed. There's no chance that the reference " +"count can overflow; at least as many bits are used to hold the reference " +"count as there are distinct memory locations in virtual memory (assuming " +"``sizeof(Py_ssize_t) >= sizeof(void*)``). Thus, the reference count " +"increment is a simple operation." +msgstr "" +"參照計數總是被明確地操作。正常的方法是使用巨集 :c:func:`Py_INCREF` 來取得對於" +"物件的參照（即參照計數加一），並使用巨集 :c:func:`Py_DECREF` 來釋放參照（即將" +"參照計數減一）。:c:func:`Py_DECREF` 巨集比 incref 巨集複雜得多，因為它必須檢" +"查參照計數是否變為零，然後呼叫物件的釋放器 (deallocator)。釋放器是包含在物件" +"型別結構中的函式指標。特定型別的釋放器，在如果是一個複合物件型別（例如 list）" +"時負責釋放物件中包含的其他物件的參照，並執行任何需要的額外完結步驟。參照計數" +"不可能溢出；至少與虛擬記憶體中用來保存參照計數的不同記憶體位置數量一樣多的位" +"元會被使用（假設 ``sizeof(Py_ssize_t) >= sizeof(void*)``）。因此參照計數增加" +"是一個簡單的操作。" + +#: ../../c-api/intro.rst:403 +msgid "" +"It is not necessary to hold a :term:`strong reference` (i.e. increment the " +"reference count) for every local variable that contains a pointer to an " +"object. In theory, the object's reference count goes up by one when the " +"variable is made to point to it and it goes down by one when the variable " +"goes out of scope. However, these two cancel each other out, so at the end " +"the reference count hasn't changed. The only real reason to use the " +"reference count is to prevent the object from being deallocated as long as " +"our variable is pointing to it. If we know that there is at least one " +"other reference to the object that lives at least as long as our variable, " +"there is no need to take a new :term:`strong reference` (i.e. increment the " +"reference count) temporarily. An important situation where this arises is in " +"objects that are passed as arguments to C functions in an extension module " +"that are called from Python; the call mechanism guarantees to hold a " +"reference to every argument for the duration of the call." +msgstr "" +"沒有必要為每個包含物件指標的本地變數物件都持有一個\\ :term:`強參照 `\\ （即增加參照計數）。理論上，當變數指向它時，物件的參照計數會增" +"加 1，而當變數離開作用域時就會減少 1。然而這兩者會相互抵消，所以最後參照計數" +"沒有改變。使用參照計數的唯一真正原因是防止物件還有變數指向它時被解除配置。如" +"果我們知道至少有一個物件的其他參照生存了至少與我們的變數一樣久，就不需要臨時" +"增加建立新的\\ :term:`強參照 `\\ （即增加參照計數）。出現這" +"種情況的一個重要情況是在從 Python 呼叫的擴充模組中作為引數傳遞給 C 函式的物" +"件；呼叫機制保證在呼叫期間保持對每個參數的參照。" + +#: ../../c-api/intro.rst:419 +msgid "" +"However, a common pitfall is to extract an object from a list and hold on to " +"it for a while without taking a new reference. Some other operation might " +"conceivably remove the object from the list, releasing that reference, and " +"possibly deallocating it. The real danger is that innocent-looking " +"operations may invoke arbitrary Python code which could do this; there is a " +"code path which allows control to flow back to the user from a :c:func:" +"`Py_DECREF`, so almost any operation is potentially dangerous." +msgstr "" +"然而，一個常見的陷阱是從一個 list 中提取一個物件並保留它一段時間而不取得其參" +"照。某些其他操作可能會從列表中刪除該物件，減少其參照計數並可能取消分配它。真" +"正的危險是看似無害的操作可能會叫用可以執行此操作的任意 Python 程式碼；有一個" +"程式碼路徑允許控制權從 :c:func:`Py_DECREF` 回歸使用者，因此幾乎任何操作都有潛" +"在危險。" + +#: ../../c-api/intro.rst:427 +msgid "" +"A safe approach is to always use the generic operations (functions whose " +"name begins with ``PyObject_``, ``PyNumber_``, ``PySequence_`` or " +"``PyMapping_``). These operations always create a new :term:`strong " +"reference` (i.e. increment the reference count) of the object they return. " +"This leaves the caller with the responsibility to call :c:func:`Py_DECREF` " +"when they are done with the result; this soon becomes second nature." +msgstr "" +"一種安全的方法是都使用通用 (generics) 操作（名稱以 ``PyObject_``、" +"``PyNumber_``、``PySequence_`` 或 ``PyMapping_`` 開頭的函式）。這些操作總是建" +"立新的對於它們回傳物件的\\ :term:`強參照 `\\ （即增加其參照" +"計數）。這讓呼叫者有責任在處理完結果後呼叫 :c:func:`Py_DECREF`；這就成為第二" +"本質。" + +#: ../../c-api/intro.rst:438 +msgid "Reference Count Details" +msgstr "參照計數詳細資訊" + +#: ../../c-api/intro.rst:440 +msgid "" +"The reference count behavior of functions in the Python/C API is best " +"explained in terms of *ownership of references*. Ownership pertains to " +"references, never to objects (objects are not owned: they are always " +"shared). \"Owning a reference\" means being responsible for calling " +"Py_DECREF on it when the reference is no longer needed. Ownership can also " +"be transferred, meaning that the code that receives ownership of the " +"reference then becomes responsible for eventually releasing it by calling :c:" +"func:`Py_DECREF` or :c:func:`Py_XDECREF` when it's no longer needed---or " +"passing on this responsibility (usually to its caller). When a function " +"passes ownership of a reference on to its caller, the caller is said to " +"receive a *new* reference. When no ownership is transferred, the caller is " +"said to *borrow* the reference. Nothing needs to be done for a :term:" +"`borrowed reference`." +msgstr "" +"Python/C API 中函式的參照計數行為最好用\\ *參照的所有權*\\ 來解釋。所有權附屬" +"於參照而非物件（物件並非被擁有，它們總是共享的）。「擁有參照」意味著當不再需" +"要該參照時，負責在其上呼叫 Py_DECREF。所有權也可以轉移，這意味著接收參照所有" +"權的程式碼最終會負責在不需要參照時透過呼叫 :c:func:`Py_DECREF` 或 :c:func:" +"`Py_XDECREF` 釋放參照 --- 或者將這個責任再傳遞出去（通常是給它的呼叫者）。當" +"一個函式將參照的所有權傳遞給它的呼叫者時，呼叫者被稱為接收到一個\\ *新*\\ 參" +"照。當沒有所有權轉移時，呼叫者被稱為\\ *借用*\\ 參照。如果是\\ :term:`借用參" +"照 `\\ 就不需要做任何事情。" + +#: ../../c-api/intro.rst:453 +msgid "" +"Conversely, when a calling function passes in a reference to an object, " +"there are two possibilities: the function *steals* a reference to the " +"object, or it does not. *Stealing a reference* means that when you pass a " +"reference to a function, that function assumes that it now owns that " +"reference, and you are not responsible for it any longer." +msgstr "" +"相反地，當呼叫的函式傳入物件的參照時，有兩種可能性：函式有\\ *竊取 (steal)* " +"物件的參照，或者沒有。 *竊取參照*\\ 意味著當你將參照傳遞給函式時，該函式假定" +"它現在擁有該參照，並且你不再對它負責。" + +#: ../../c-api/intro.rst:463 +msgid "" +"Few functions steal references; the two notable exceptions are :c:func:" +"`PyList_SetItem` and :c:func:`PyTuple_SetItem`, which steal a reference to " +"the item (but not to the tuple or list into which the item is put!). These " +"functions were designed to steal a reference because of a common idiom for " +"populating a tuple or list with newly created objects; for example, the code " +"to create the tuple ``(1, 2, \"three\")`` could look like this (forgetting " +"about error handling for the moment; a better way to code this is shown " +"below)::" +msgstr "" +"很少有函式會竊取參照；兩個值得注意的例外是 :c:func:`PyList_SetItem` 和 :c:" +"func:`PyTuple_SetItem`，它們竊取了對項目的參照（但不是對項目所在的 tuple 或 " +"list 的參照！）。因為有著使用新建立的物件來增加 (populate) tuple 或 list 的習" +"慣，這些函式旨在竊取參照；例如，建立 tuple ``(1, 2, \"three\")`` 的程式碼可以" +"如下所示（先暫時忘記錯誤處理；更好的編寫方式如下所示）：" + +#: ../../c-api/intro.rst:471 +msgid "" +"PyObject *t;\n" +"\n" +"t = PyTuple_New(3);\n" +"PyTuple_SetItem(t, 0, PyLong_FromLong(1L));\n" +"PyTuple_SetItem(t, 1, PyLong_FromLong(2L));\n" +"PyTuple_SetItem(t, 2, PyUnicode_FromString(\"three\"));" +msgstr "" +"PyObject *t;\n" +"\n" +"t = PyTuple_New(3);\n" +"PyTuple_SetItem(t, 0, PyLong_FromLong(1L));\n" +"PyTuple_SetItem(t, 1, PyLong_FromLong(2L));\n" +"PyTuple_SetItem(t, 2, PyUnicode_FromString(\"three\"));" + +#: ../../c-api/intro.rst:478 +msgid "" +"Here, :c:func:`PyLong_FromLong` returns a new reference which is immediately " +"stolen by :c:func:`PyTuple_SetItem`. When you want to keep using an object " +"although the reference to it will be stolen, use :c:func:`Py_INCREF` to grab " +"another reference before calling the reference-stealing function." +msgstr "" +"這裡 :c:func:`PyLong_FromLong` 會回傳一個新的參照，它立即被 :c:func:" +"`PyTuple_SetItem` 竊取。如果你想繼續使用一個物件，儘管對它的參照將被竊取，請" +"在呼叫參照竊取函式之前使用 :c:func:`Py_INCREF` 來取得另一個參照。" + +#: ../../c-api/intro.rst:483 +msgid "" +"Incidentally, :c:func:`PyTuple_SetItem` is the *only* way to set tuple " +"items; :c:func:`PySequence_SetItem` and :c:func:`PyObject_SetItem` refuse to " +"do this since tuples are an immutable data type. You should only use :c:" +"func:`PyTuple_SetItem` for tuples that you are creating yourself." +msgstr "" +"附帶地說，:c:func:`PyTuple_SetItem` 是設定 tuple 項目的\\ *唯一*\\ 方法； :c:" +"func:`PySequence_SetItem` 和 :c:func:`PyObject_SetItem` 拒絕這樣做，因為 " +"tuple 是一種不可變 (immutable) 的資料型別。你應該只對你自己建立的 tuple 使" +"用 :c:func:`PyTuple_SetItem`。" + +#: ../../c-api/intro.rst:488 +msgid "" +"Equivalent code for populating a list can be written using :c:func:" +"`PyList_New` and :c:func:`PyList_SetItem`." +msgstr "" +"可以使用 :c:func:`PyList_New` 和 :c:func:`PyList_SetItem` 編寫用於填充列表的" +"等效程式碼。" + +#: ../../c-api/intro.rst:491 +msgid "" +"However, in practice, you will rarely use these ways of creating and " +"populating a tuple or list. There's a generic function, :c:func:" +"`Py_BuildValue`, that can create most common objects from C values, directed " +"by a :dfn:`format string`. For example, the above two blocks of code could " +"be replaced by the following (which also takes care of the error checking)::" +msgstr "" +"但是在實際操作中你很少會使用這些方法來建立和增加 tuple 和 list。有一個通用函" +"式 :c:func:`Py_BuildValue` 可以從 C 值建立最常見的物件，由 :dfn:`format " +"string` 引導。例如上面的兩個程式碼可以用以下程式碼替換（它還負責了錯誤檢" +"查）： ::" + +#: ../../c-api/intro.rst:497 +msgid "" +"PyObject *tuple, *list;\n" +"\n" +"tuple = Py_BuildValue(\"(iis)\", 1, 2, \"three\");\n" +"list = Py_BuildValue(\"[iis]\", 1, 2, \"three\");" +msgstr "" +"PyObject *tuple, *list;\n" +"\n" +"tuple = Py_BuildValue(\"(iis)\", 1, 2, \"three\");\n" +"list = Py_BuildValue(\"[iis]\", 1, 2, \"three\");" + +#: ../../c-api/intro.rst:502 +msgid "" +"It is much more common to use :c:func:`PyObject_SetItem` and friends with " +"items whose references you are only borrowing, like arguments that were " +"passed in to the function you are writing. In that case, their behaviour " +"regarding references is much saner, since you don't have to take a new " +"reference just so you can give that reference away (\"have it be stolen\"). " +"For example, this function sets all items of a list (actually, any mutable " +"sequence) to a given item::" +msgstr "" +"更常見的是以那些借用參照的項目來使用 :c:func:`PyObject_SetItem` 及其系列函" +"式，比如傳遞給你正在編寫的函式的引數。在那種情況下，他們關於參照的行為會比較" +"穩健，因為你不取得新的一個參照就可以放棄參照（「讓它被竊取」）。例如，此函式" +"將 list（實際上是任何可變序列）的所有項目設定於給定項目：" + +#: ../../c-api/intro.rst:509 +msgid "" +"int\n" +"set_all(PyObject *target, PyObject *item)\n" +"{\n" +" Py_ssize_t i, n;\n" +"\n" +" n = PyObject_Length(target);\n" +" if (n < 0)\n" +" return -1;\n" +" for (i = 0; i < n; i++) {\n" +" PyObject *index = PyLong_FromSsize_t(i);\n" +" if (!index)\n" +" return -1;\n" +" if (PyObject_SetItem(target, index, item) < 0) {\n" +" Py_DECREF(index);\n" +" return -1;\n" +" }\n" +" Py_DECREF(index);\n" +" }\n" +" return 0;\n" +"}" +msgstr "" +"int\n" +"set_all(PyObject *target, PyObject *item)\n" +"{\n" +" Py_ssize_t i, n;\n" +"\n" +" n = PyObject_Length(target);\n" +" if (n < 0)\n" +" return -1;\n" +" for (i = 0; i < n; i++) {\n" +" PyObject *index = PyLong_FromSsize_t(i);\n" +" if (!index)\n" +" return -1;\n" +" if (PyObject_SetItem(target, index, item) < 0) {\n" +" Py_DECREF(index);\n" +" return -1;\n" +" }\n" +" Py_DECREF(index);\n" +" }\n" +" return 0;\n" +"}" + +#: ../../c-api/intro.rst:532 +msgid "" +"The situation is slightly different for function return values. While " +"passing a reference to most functions does not change your ownership " +"responsibilities for that reference, many functions that return a reference " +"to an object give you ownership of the reference. The reason is simple: in " +"many cases, the returned object is created on the fly, and the reference " +"you get is the only reference to the object. Therefore, the generic " +"functions that return object references, like :c:func:`PyObject_GetItem` " +"and :c:func:`PySequence_GetItem`, always return a new reference (the caller " +"becomes the owner of the reference)." +msgstr "" +"函式回傳值的情況略有不同。雖然傳遞對大多數函式的參照不會改變你對該參照的所有" +"權責任，但許多回傳物件參照的函式會給你該參照的所有權。原因很簡單：在很多情況" +"下，回傳的物件是即時建立的，你獲得的參照是對該物件的唯一參照。因此回傳物件參" +"照的通用函式，如 :c:func:`PyObject_GetItem` 和 :c:func:`PySequence_GetItem`，" +"總是回傳一個新的參照（呼叫者成為參照的所有者）。" + +#: ../../c-api/intro.rst:541 +msgid "" +"It is important to realize that whether you own a reference returned by a " +"function depends on which function you call only --- *the plumage* (the type " +"of the object passed as an argument to the function) *doesn't enter into it!" +"* Thus, if you extract an item from a list using :c:func:`PyList_GetItem`, " +"you don't own the reference --- but if you obtain the same item from the " +"same list using :c:func:`PySequence_GetItem` (which happens to take exactly " +"the same arguments), you do own a reference to the returned object." +msgstr "" +"重要的是要意識到你是否擁有一個函式回傳的參照只取決於你呼叫哪個函式 --- *羽毛 " +"(plumage)*\\ （作為引數傳遞給函式的物件之型別）\\ *不會進入它！*\\ 因此，如果" +"你使用 :c:func:`PyList_GetItem` 從 list 中提取一個項目，你不會擁有其參照 --- " +"但如果你使用 :c:func:`PySequence_GetItem` 從同一 list 中取得相同的項目（且恰" +"好使用完全相同的引數），你確實會擁有對回傳物件的參照。" + +#: ../../c-api/intro.rst:553 +msgid "" +"Here is an example of how you could write a function that computes the sum " +"of the items in a list of integers; once using :c:func:`PyList_GetItem`, " +"and once using :c:func:`PySequence_GetItem`. ::" +msgstr "" +"以下是一個範例，說明如何編寫函式來計算一個整數 list 中項目的總和；一次使用 :" +"c:func:`PyList_GetItem`，一次使用 :c:func:`PySequence_GetItem`： ::" + +#: ../../c-api/intro.rst:557 +msgid "" +"long\n" +"sum_list(PyObject *list)\n" +"{\n" +" Py_ssize_t i, n;\n" +" long total = 0, value;\n" +" PyObject *item;\n" +"\n" +" n = PyList_Size(list);\n" +" if (n < 0)\n" +" return -1; /* Not a list */\n" +" for (i = 0; i < n; i++) {\n" +" item = PyList_GetItem(list, i); /* Can't fail */\n" +" if (!PyLong_Check(item)) continue; /* Skip non-integers */\n" +" value = PyLong_AsLong(item);\n" +" if (value == -1 && PyErr_Occurred())\n" +" /* Integer too big to fit in a C long, bail out */\n" +" return -1;\n" +" total += value;\n" +" }\n" +" return total;\n" +"}" +msgstr "" +"long\n" +"sum_list(PyObject *list)\n" +"{\n" +" Py_ssize_t i, n;\n" +" long total = 0, value;\n" +" PyObject *item;\n" +"\n" +" n = PyList_Size(list);\n" +" if (n < 0)\n" +" return -1; /* 不是 list */\n" +" for (i = 0; i < n; i++) {\n" +" item = PyList_GetItem(list, i); /* 不會失敗 */\n" +" if (!PyLong_Check(item)) continue; /* 跳過非整數 */\n" +" value = PyLong_AsLong(item);\n" +" if (value == -1 && PyErr_Occurred())\n" +" /* 整數太大，無法放入 C long，退出 */\n" +" return -1;\n" +" total += value;\n" +" }\n" +" return total;\n" +"}" + +#: ../../c-api/intro.rst:583 +msgid "" +"long\n" +"sum_sequence(PyObject *sequence)\n" +"{\n" +" Py_ssize_t i, n;\n" +" long total = 0, value;\n" +" PyObject *item;\n" +" n = PySequence_Length(sequence);\n" +" if (n < 0)\n" +" return -1; /* Has no length */\n" +" for (i = 0; i < n; i++) {\n" +" item = PySequence_GetItem(sequence, i);\n" +" if (item == NULL)\n" +" return -1; /* Not a sequence, or other failure */\n" +" if (PyLong_Check(item)) {\n" +" value = PyLong_AsLong(item);\n" +" Py_DECREF(item);\n" +" if (value == -1 && PyErr_Occurred())\n" +" /* Integer too big to fit in a C long, bail out */\n" +" return -1;\n" +" total += value;\n" +" }\n" +" else {\n" +" Py_DECREF(item); /* Discard reference ownership */\n" +" }\n" +" }\n" +" return total;\n" +"}" +msgstr "" +"long\n" +"sum_sequence(PyObject *sequence)\n" +"{\n" +" Py_ssize_t i, n;\n" +" long total = 0, value;\n" +" PyObject *item;\n" +" n = PySequence_Length(sequence);\n" +" if (n < 0)\n" +" return -1; /* 沒有長度 */\n" +" for (i = 0; i < n; i++) {\n" +" item = PySequence_GetItem(sequence, i);\n" +" if (item == NULL)\n" +" return -1; /* 不是序列或其他錯誤 */\n" +" if (PyLong_Check(item)) {\n" +" value = PyLong_AsLong(item);\n" +" Py_DECREF(item);\n" +" if (value == -1 && PyErr_Occurred())\n" +" /* 整數太大，無法放入 C long，退出 */\n" +" return -1;\n" +" total += value;\n" +" }\n" +" else {\n" +" Py_DECREF(item); /* 丟棄參照所有權 */\n" +" }\n" +" }\n" +" return total;\n" +"}" + +#: ../../c-api/intro.rst:617 +msgid "Types" +msgstr "型別" + +#: ../../c-api/intro.rst:619 +msgid "" +"There are few other data types that play a significant role in the Python/C " +"API; most are simple C types such as :c:expr:`int`, :c:expr:`long`, :c:expr:" +"`double` and :c:expr:`char*`. A few structure types are used to describe " +"static tables used to list the functions exported by a module or the data " +"attributes of a new object type, and another is used to describe the value " +"of a complex number. These will be discussed together with the functions " +"that use them." +msgstr "" +"有少數幾個其他的資料型別在 Python/C API 中發揮重要作用；大多數是簡單的 C 型" +"別，例如 :c:expr:`int`、:c:expr:`long`、:c:expr:`double` 和 :c:expr:`char*`。" +"一些結構型別被用於描述用於列出模組所匯出的函式或新物件型別的資料屬性的靜態" +"表，其他則用於描述複數的值。這些將與使用它們的函式一起討論。" + +#: ../../c-api/intro.rst:629 +msgid "" +"A signed integral type such that ``sizeof(Py_ssize_t) == sizeof(size_t)``. " +"C99 doesn't define such a thing directly (size_t is an unsigned integral " +"type). See :pep:`353` for details. ``PY_SSIZE_T_MAX`` is the largest " +"positive value of type :c:type:`Py_ssize_t`." +msgstr "" +"一個帶符號的整數型別，使得 ``sizeof(Py_ssize_t) == sizeof(size_t)``。 C99 沒" +"有直接定義這樣的東西（size_t 是無符號整數型別）。有關詳細資訊，請參閱 :pep:" +"`353`。 ``PY_SSIZE_T_MAX`` 是 :c:type:`Py_ssize_t` 型別的最大正值。" + +#: ../../c-api/intro.rst:638 +msgid "Exceptions" +msgstr "例外" + +#: ../../c-api/intro.rst:640 +msgid "" +"The Python programmer only needs to deal with exceptions if specific error " +"handling is required; unhandled exceptions are automatically propagated to " +"the caller, then to the caller's caller, and so on, until they reach the top-" +"level interpreter, where they are reported to the user accompanied by a " +"stack traceback." +msgstr "" +"如果需要特定的錯誤處理，Python 開發者就只需要處理例外；未處理的例外會自動傳遞" +"給呼叫者，然後傳遞給呼叫者的呼叫者，依此類推，直到它們到達頂層直譯器，在那裡" +"它們透過堆疊回溯 (stack trace) 回報給使用者。" + +#: ../../c-api/intro.rst:648 +msgid "" +"For C programmers, however, error checking always has to be explicit. All " +"functions in the Python/C API can raise exceptions, unless an explicit claim " +"is made otherwise in a function's documentation. In general, when a " +"function encounters an error, it sets an exception, discards any object " +"references that it owns, and returns an error indicator. If not documented " +"otherwise, this indicator is either ``NULL`` or ``-1``, depending on the " +"function's return type. A few functions return a Boolean true/false result, " +"with false indicating an error. Very few functions return no explicit error " +"indicator or have an ambiguous return value, and require explicit testing " +"for errors with :c:func:`PyErr_Occurred`. These exceptions are always " +"explicitly documented." +msgstr "" +"然而，對於 C 開發者來說，錯誤檢查總是必須是顯式的。除非在函式的文件中另有明確" +"聲明，否則 Python/C API 中的所有函式都可以引發例外。通常當一個函式遇到錯誤" +"時，它會設定一個例外，丟棄它擁有的任何物件參照，並回傳一個錯誤指示器。如果沒" +"有另外文件記錄，這個指示器要麼是 ``NULL`` 不然就是 ``-1``，取決於函式的回傳型" +"別。有些函式會回傳布林值 true/false 結果，false 表示錯誤。很少有函式不回傳明" +"確的錯誤指示器或者有不明確的回傳值，而需要使用 :c:func:`PyErr_Occurred` 明確" +"測試錯誤。這些例外都會被明確地記錄於文件。" + +#: ../../c-api/intro.rst:663 +msgid "" +"Exception state is maintained in per-thread storage (this is equivalent to " +"using global storage in an unthreaded application). A thread can be in one " +"of two states: an exception has occurred, or not. The function :c:func:" +"`PyErr_Occurred` can be used to check for this: it returns a borrowed " +"reference to the exception type object when an exception has occurred, and " +"``NULL`` otherwise. There are a number of functions to set the exception " +"state: :c:func:`PyErr_SetString` is the most common (though not the most " +"general) function to set the exception state, and :c:func:`PyErr_Clear` " +"clears the exception state." +msgstr "" +"例外的狀態會在個別執行緒的儲存空間 (per-thread storage) 中維護（這相當於在非" +"執行緒應用程式中使用全域儲存空間）。執行緒可以處於兩種狀態之一：發生例外或未" +"發生例外。函式 :c:func:`PyErr_Occurred` 可用於檢查這一點：當例外發生時，它回" +"傳對例外型別物件的借用參照，否則回傳 ``NULL``。設定例外狀態的函式有很多：:c:" +"func:`PyErr_SetString` 是最常見的（儘管不是最通用的）設定例外狀態的函式，而 :" +"c:func:`PyErr_Clear` 是用來清除例外狀態。" + +#: ../../c-api/intro.rst:673 +msgid "" +"The full exception state consists of three objects (all of which can be " +"``NULL``): the exception type, the corresponding exception value, and the " +"traceback. These have the same meanings as the Python result of ``sys." +"exc_info()``; however, they are not the same: the Python objects represent " +"the last exception being handled by a Python :keyword:`try` ... :keyword:" +"`except` statement, while the C level exception state only exists while an " +"exception is being passed on between C functions until it reaches the Python " +"bytecode interpreter's main loop, which takes care of transferring it to " +"``sys.exc_info()`` and friends." +msgstr "" +"完整的例外狀態由三個（都可以為 ``NULL`` 的）物件組成：例外型別、對應的例外值" +"和回溯。這些與 ``sys.exc_info()`` 的 Python 結果具有相同的含義；但是它們並不" +"相同：Python 物件表示由 Python :keyword:`try` ... :keyword:`except` 陳述式處" +"理的最後一個例外，而 C 層級的例外狀態僅在例外在 C 函式間傳遞時存在，直到它到" +"達 Python 位元組碼直譯器的主迴圈，該迴圈負責將它傳遞給 ``sys.exc_info()`` 和" +"其系列函式。" + +#: ../../c-api/intro.rst:685 +msgid "" +"Note that starting with Python 1.5, the preferred, thread-safe way to access " +"the exception state from Python code is to call the function :func:`sys." +"exc_info`, which returns the per-thread exception state for Python code. " +"Also, the semantics of both ways to access the exception state have changed " +"so that a function which catches an exception will save and restore its " +"thread's exception state so as to preserve the exception state of its " +"caller. This prevents common bugs in exception handling code caused by an " +"innocent-looking function overwriting the exception being handled; it also " +"reduces the often unwanted lifetime extension for objects that are " +"referenced by the stack frames in the traceback." +msgstr "" +"請注意，從 Python 1.5 開始，從 Python 程式碼存取例外狀態的首選且支援執行緒安" +"全的方法是呼叫 :func:`sys.exc_info` 函式，它回傳 Python 程式碼的個別執行緒例" +"外狀態。此外，兩種存取例外狀態方法的語義都發生了變化，因此捕獲例外的函式將保" +"存和恢復其執行緒的例外狀態，從而保留其呼叫者的例外狀態。這可以防止例外處理程" +"式碼中的常見錯誤，這些錯誤是由看似無辜的函式覆蓋了正在處理的例外而引起的；它" +"還替回溯中被堆疊框 (stack frame) 參照的物件減少了通常不需要的生命週期延長。" + +#: ../../c-api/intro.rst:696 +msgid "" +"As a general principle, a function that calls another function to perform " +"some task should check whether the called function raised an exception, and " +"if so, pass the exception state on to its caller. It should discard any " +"object references that it owns, and return an error indicator, but it " +"should *not* set another exception --- that would overwrite the exception " +"that was just raised, and lose important information about the exact cause " +"of the error." +msgstr "" +"作為一般原則，呼叫另一個函式來執行某些任務的函式應該檢查被呼叫函式是否引發了" +"例外，如果是，則將例外狀態傳遞給它的呼叫者。它應該丟棄它擁有的任何物件參照，" +"並回傳一個錯誤指示符，但它\\ *不應該*\\ 設定另一個例外 --- 這將覆蓋剛剛引發的" +"例外，並丟失關於錯誤確切原因的重要資訊。" + +#: ../../c-api/intro.rst:705 +msgid "" +"A simple example of detecting exceptions and passing them on is shown in " +"the :c:func:`!sum_sequence` example above. It so happens that this example " +"doesn't need to clean up any owned references when it detects an error. The " +"following example function shows some error cleanup. First, to remind you " +"why you like Python, we show the equivalent Python code::" +msgstr "" +"上面的 :c:func:`!sum_sequence` 範例展示了一個檢測例外並將其繼續傳遞的例子。碰" +"巧這個例子在檢測到錯誤時不需要清理任何擁有的參照。以下範例函式展示了一些錯誤" +"清理。首先，為了提醒你為什麼喜歡 Python，我們展示了等效的 Python 程式碼： ::" + +#: ../../c-api/intro.rst:711 +msgid "" +"def incr_item(dict, key):\n" +" try:\n" +" item = dict[key]\n" +" except KeyError:\n" +" item = 0\n" +" dict[key] = item + 1" +msgstr "" +"def incr_item(dict, key):\n" +" try:\n" +" item = dict[key]\n" +" except KeyError:\n" +" item = 0\n" +" dict[key] = item + 1" + +#: ../../c-api/intro.rst:720 +msgid "Here is the corresponding C code, in all its glory::" +msgstr "這是相應的 C 程式碼：" + +#: ../../c-api/intro.rst:722 +msgid "" +"int\n" +"incr_item(PyObject *dict, PyObject *key)\n" +"{\n" +" /* Objects all initialized to NULL for Py_XDECREF */\n" +" PyObject *item = NULL, *const_one = NULL, *incremented_item = NULL;\n" +" int rv = -1; /* Return value initialized to -1 (failure) */\n" +"\n" +" item = PyObject_GetItem(dict, key);\n" +" if (item == NULL) {\n" +" /* Handle KeyError only: */\n" +" if (!PyErr_ExceptionMatches(PyExc_KeyError))\n" +" goto error;\n" +"\n" +" /* Clear the error and use zero: */\n" +" PyErr_Clear();\n" +" item = PyLong_FromLong(0L);\n" +" if (item == NULL)\n" +" goto error;\n" +" }\n" +" const_one = PyLong_FromLong(1L);\n" +" if (const_one == NULL)\n" +" goto error;\n" +"\n" +" incremented_item = PyNumber_Add(item, const_one);\n" +" if (incremented_item == NULL)\n" +" goto error;\n" +"\n" +" if (PyObject_SetItem(dict, key, incremented_item) < 0)\n" +" goto error;\n" +" rv = 0; /* Success */\n" +" /* Continue with cleanup code */\n" +"\n" +" error:\n" +" /* Cleanup code, shared by success and failure path */\n" +"\n" +" /* Use Py_XDECREF() to ignore NULL references */\n" +" Py_XDECREF(item);\n" +" Py_XDECREF(const_one);\n" +" Py_XDECREF(incremented_item);\n" +"\n" +" return rv; /* -1 for error, 0 for success */\n" +"}" +msgstr "" + +#: ../../c-api/intro.rst:772 +msgid "" +"This example represents an endorsed use of the ``goto`` statement in C! It " +"illustrates the use of :c:func:`PyErr_ExceptionMatches` and :c:func:" +"`PyErr_Clear` to handle specific exceptions, and the use of :c:func:" +"`Py_XDECREF` to dispose of owned references that may be ``NULL`` (note the " +"``'X'`` in the name; :c:func:`Py_DECREF` would crash when confronted with a " +"``NULL`` reference). It is important that the variables used to hold owned " +"references are initialized to ``NULL`` for this to work; likewise, the " +"proposed return value is initialized to ``-1`` (failure) and only set to " +"success after the final call made is successful." +msgstr "" +"這個例子代表了在 C 語言中對使用 ``goto`` 陳述句的認同！它闡述了以 :c:func:" +"`PyErr_ExceptionMatches` 和 :c:func:`PyErr_Clear` 來處理特定的例外，以及以 :" +"c:func:`Py_XDECREF` 來配置其所擁有且可能為 ``NULL`` 的參照（注意名稱中的 " +"``'X'``\\ ；:c:func:`Py_DECREF` 在遇到 ``NULL`` 參照時會崩潰）。重要的是，用" +"於保存擁有的參照的變數被初始化為 ``NULL`` 以使其能夠順利作用；同樣地，回傳值" +"被初始化為 ``-1``\\ （失敗），並且僅在最後一次呼叫成功後才設定為成功。" + +#: ../../c-api/intro.rst:786 +msgid "Embedding Python" +msgstr "嵌入式Python" + +#: ../../c-api/intro.rst:788 +msgid "" +"The one important task that only embedders (as opposed to extension writers) " +"of the Python interpreter have to worry about is the initialization, and " +"possibly the finalization, of the Python interpreter. Most functionality of " +"the interpreter can only be used after the interpreter has been initialized." +msgstr "" +"只有 Python 直譯器的嵌入者（而不是擴充編寫者）需要擔心的一項重要任務是 " +"Python 直譯器的初始化與完成階段。直譯器的大部分功能只能在直譯器初始化後使用。" + +#: ../../c-api/intro.rst:801 +msgid "" +"The basic initialization function is :c:func:`Py_Initialize`. This " +"initializes the table of loaded modules, and creates the fundamental " +"modules :mod:`builtins`, :mod:`__main__`, and :mod:`sys`. It also " +"initializes the module search path (``sys.path``)." +msgstr "" +"基本的初始化函式是 :c:func:`Py_Initialize`。這會初始化帶有載入模組的表，並建" +"立基礎模組 :mod:`builtins`、:mod:`__main__` 和 :mod:`sys`。它還會初始化模組搜" +"索路徑 (``sys.path``)。" + +#: ../../c-api/intro.rst:806 +msgid "" +":c:func:`Py_Initialize` does not set the \"script argument list\" (``sys." +"argv``). If this variable is needed by Python code that will be executed " +"later, setting :c:member:`PyConfig.argv` and :c:member:`PyConfig.parse_argv` " +"must be set: see :ref:`Python Initialization Configuration `." +msgstr "" +":c:func:`Py_Initialize` 不設定「腳本引數列表 (script argument list)」 (``sys." +"argv``)。如果稍後將要執行的 Python 程式碼需要此變數，則必須設定 :c:member:" +"`PyConfig.argv` 和 :c:member:`PyConfig.parse_argv`，請見 :ref:`Python 初始化" +"配置 `。" + +#: ../../c-api/intro.rst:811 +msgid "" +"On most systems (in particular, on Unix and Windows, although the details " +"are slightly different), :c:func:`Py_Initialize` calculates the module " +"search path based upon its best guess for the location of the standard " +"Python interpreter executable, assuming that the Python library is found in " +"a fixed location relative to the Python interpreter executable. In " +"particular, it looks for a directory named :file:`lib/python{X.Y}` relative " +"to the parent directory where the executable named :file:`python` is found " +"on the shell command search path (the environment variable :envvar:`PATH`)." +msgstr "" +"在大多數系統上（特別是在 Unix 和 Windows 上，儘管細節略有不同），:c:func:" +"`Py_Initialize` 會假設Python 函式庫相對於 Python 直譯器可執行檔案的位置固定，" +"並根據其對標準 Python 直譯器可執行檔案位置的最佳猜測來計算模組搜尋路徑。或者" +"更詳細地說，它會在 shell 命令搜尋路徑（環境變數 :envvar:`PATH`）中找到名為 :" +"file:`python` 的可執行檔案，並在其父目錄中查找一個名為 :file:`lib/python{X.Y}" +"` 的目錄的相對位置。" + +#: ../../c-api/intro.rst:820 +msgid "" +"For instance, if the Python executable is found in :file:`/usr/local/bin/" +"python`, it will assume that the libraries are in :file:`/usr/local/lib/" +"python{X.Y}`. (In fact, this particular path is also the \"fallback\" " +"location, used when no executable file named :file:`python` is found along :" +"envvar:`PATH`.) The user can override this behavior by setting the " +"environment variable :envvar:`PYTHONHOME`, or insert additional directories " +"in front of the standard path by setting :envvar:`PYTHONPATH`." +msgstr "" +"例如，如果在 :file:`/usr/local/bin/python` 中找到 Python 可執行檔案，它將假定" +"函式庫位於 :file:`/usr/local/lib/python{X.Y}` 中。（事實上這個特定的路徑也是" +"「後備 (fallback)」位置，當在 :envvar:`PATH` 中找不到名為 :file:`python` 的可" +"執行檔案時使用。）使用者可以透過設定環境變數來覆蓋此行為 :envvar:" +"`PYTHONHOME`，或者透過設定 :envvar:`PYTHONPATH` 在標準路徑前面插入額外的目" +"錄。" + +#: ../../c-api/intro.rst:834 +msgid "" +"The embedding application can steer the search by setting :c:member:" +"`PyConfig.program_name` *before* calling :c:func:`Py_InitializeFromConfig`. " +"Note that :envvar:`PYTHONHOME` still overrides this and :envvar:`PYTHONPATH` " +"is still inserted in front of the standard path. An application that " +"requires total control has to provide its own implementation of :c:func:" +"`Py_GetPath`, :c:func:`Py_GetPrefix`, :c:func:`Py_GetExecPrefix`, and :c:" +"func:`Py_GetProgramFullPath` (all defined in :file:`Modules/getpath.c`)." +msgstr "" +"嵌入的應用程式可以透過在呼叫 :c:func:`Py_InitializeFromConfig` *之前*\\ 設" +"定 :c:member:`PyConfig.program_name` 來引導搜尋。請注意 :envvar:`PYTHONHOME` " +"仍然覆蓋它並且 :envvar:`PYTHONPATH` 仍然插入在標準路徑的前面。需要完全控制權" +"的應用程式必須實作自己的 :c:func:`Py_GetPath`、:c:func:`Py_GetPrefix`、:c:" +"func:`Py_GetExecPrefix` 和 :c:func:`Py_GetProgramFullPath`\\（全部定義在 :" +"file:`Modules/getpath.c`)。" + +#: ../../c-api/intro.rst:845 +msgid "" +"Sometimes, it is desirable to \"uninitialize\" Python. For instance, the " +"application may want to start over (make another call to :c:func:" +"`Py_Initialize`) or the application is simply done with its use of Python " +"and wants to free memory allocated by Python. This can be accomplished by " +"calling :c:func:`Py_FinalizeEx`. The function :c:func:`Py_IsInitialized` " +"returns true if Python is currently in the initialized state. More " +"information about these functions is given in a later chapter. Notice that :" +"c:func:`Py_FinalizeEx` does *not* free all memory allocated by the Python " +"interpreter, e.g. memory allocated by extension modules currently cannot be " +"released." +msgstr "" +"有時會希望能夠「取消初始化 (uninitialize)」Python。例如，應用程式可能想要重新" +"開始（再次呼叫 :c:func:`Py_Initialize`）或者應用程式簡單地完成了對 Python 的" +"使用並想要釋放 Python 分配的記憶體。這可以透過呼叫 :c:func:`Py_FinalizeEx` 來" +"完成。如果 Python 目前處於初始化狀態，函式 :c:func:`Py_IsInitialized` 會回傳 " +"true。有關這些功能的更多資訊將在後面的章節中給出。請注意 :c:func:" +"`Py_FinalizeEx` *不會*\\ 釋放由 Python 直譯器分配的所有記憶體，例如目前無法釋" +"放被擴充模組所分配的記憶體。" + +#: ../../c-api/intro.rst:859 +msgid "Debugging Builds" +msgstr "除錯建置" + +#: ../../c-api/intro.rst:861 +msgid "" +"Python can be built with several macros to enable extra checks of the " +"interpreter and extension modules. These checks tend to add a large amount " +"of overhead to the runtime so they are not enabled by default." +msgstr "" +"Python 可以在建置時使用多個巨集來啟用對直譯器和擴充模組的額外檢查，這些檢查往" +"往會在執行環境 (runtime) 增加大量開銷 (overhead)，因此預設情況下不啟用它們。" + +#: ../../c-api/intro.rst:865 +msgid "" +"A full list of the various types of debugging builds is in the file :file:" +"`Misc/SpecialBuilds.txt` in the Python source distribution. Builds are " +"available that support tracing of reference counts, debugging the memory " +"allocator, or low-level profiling of the main interpreter loop. Only the " +"most frequently used builds will be described in the remainder of this " +"section." +msgstr "" +"Python 原始碼發佈版本中的 :file:`Misc/SpecialBuilds.txt` 檔案有一份包含多種除" +"錯構置的完整列表，為支援追蹤參照計數、為記憶體分配器除錯或對主直譯器迴圈進行" +"低階分析的建置。本節的其餘部分將僅描述最常用的建置。" + +#: ../../c-api/intro.rst:873 +msgid "" +"Compiling the interpreter with the :c:macro:`!Py_DEBUG` macro defined " +"produces what is generally meant by :ref:`a debug build of Python `. :c:macro:`!Py_DEBUG` is enabled in the Unix build by adding :option:" +"`--with-pydebug` to the :file:`./configure` command. It is also implied by " +"the presence of the not-Python-specific :c:macro:`!_DEBUG` macro. When :c:" +"macro:`!Py_DEBUG` is enabled in the Unix build, compiler optimization is " +"disabled." +msgstr "" +"使用定義的 :c:macro:`!Py_DEBUG` 巨集編譯直譯器會生成 :ref:`Python 的除錯建置 " +"`。 :c:macro:`!Py_DEBUG` 在 Unix 建置中要透過在 :file:`./" +"configure` 命令中加入 :option:`--with-pydebug` 來啟用。非 Python 限定的 :c:" +"macro:`!_DEBUG` 巨集的存在也暗示了這一點。當 :c:macro:`!Py_DEBUG` 在 Unix 建" +"置中啟用時，編譯器最佳化會被禁用。" + +#: ../../c-api/intro.rst:881 +msgid "" +"In addition to the reference count debugging described below, extra checks " +"are performed, see :ref:`Python Debug Build `." +msgstr "" +"除了下面描述的參照計數除錯之外，還會執行額外的檢查，請參閱 :ref:`Python 除錯" +"建置 `。" + +#: ../../c-api/intro.rst:884 +msgid "" +"Defining :c:macro:`Py_TRACE_REFS` enables reference tracing (see the :option:" +"`configure --with-trace-refs option <--with-trace-refs>`). When defined, a " +"circular doubly linked list of active objects is maintained by adding two " +"extra fields to every :c:type:`PyObject`. Total allocations are tracked as " +"well. Upon exit, all existing references are printed. (In interactive mode " +"this happens after every statement run by the interpreter.)" +msgstr "" +"定義 :c:macro:`Py_TRACE_REFS` 來啟用參照追蹤（參見\\ :option:`設定 --with-" +"trace-refs 選項 <--with-trace-refs>`）。當有定義時，透過向每個 :c:type:" +"`PyObject` 新增兩個額外欄位來維護有效物件的循環雙向鍊表 (circular doubly " +"linked list)。全體分配也有被追蹤。退出時將印出所有現行參照。（在交互模式下，" +"這發生在直譯器運行的每個陳述句之後。）" + +#: ../../c-api/intro.rst:891 +msgid "" +"Please refer to :file:`Misc/SpecialBuilds.txt` in the Python source " +"distribution for more detailed information." +msgstr "" +"有關更多詳細資訊，請參閱 Python 原始碼發布版中的 :file:`Misc/SpecialBuilds." +"txt`。" + +#: ../../c-api/intro.rst:898 +msgid "Recommended third party tools" +msgstr "建議的第三方工具" + +#: ../../c-api/intro.rst:900 +msgid "" +"The following third party tools offer both simpler and more sophisticated " +"approaches to creating C, C++ and Rust extensions for Python:" +msgstr "" +"以下第三方工具提供了更簡單且更細緻的方法來為 Python 建立 C、C++ 和 Rust 擴充" +"模組：" + +#: ../../c-api/intro.rst:903 +msgid "`Cython `_" +msgstr "`Cython `_" + +#: ../../c-api/intro.rst:904 +msgid "`cffi `_" +msgstr "`cffi `_" + +#: ../../c-api/intro.rst:905 +msgid "`HPy `_" +msgstr "`HPy `_" + +#: ../../c-api/intro.rst:906 +msgid "`nanobind `_ (C++)" +msgstr "`nanobind `_ (C++)" + +#: ../../c-api/intro.rst:907 +msgid "`Numba `_" +msgstr "`Numba `_" + +#: ../../c-api/intro.rst:908 +msgid "`pybind11 `_ (C++)" +msgstr "`pybind11 `_ (C++)" + +#: ../../c-api/intro.rst:909 +msgid "`PyO3 `_ (Rust)" +msgstr "`PyO3 `_ (Rust)" + +#: ../../c-api/intro.rst:910 +msgid "`SWIG `_" +msgstr "`SWIG `_" + +#: ../../c-api/intro.rst:912 +msgid "" +"Using tools such as these can help avoid writing code that is tightly bound " +"to a particular version of CPython, avoid reference counting errors, and " +"focus more on your own code than on using the CPython API. In general, new " +"versions of Python can be supported by updating the tool, and your code will " +"often use newer and more efficient APIs automatically. Some tools also " +"support compiling for other implementations of Python from a single set of " +"sources." +msgstr "" + +#: ../../c-api/intro.rst:919 +msgid "" +"These projects are not supported by the same people who maintain Python, and " +"issues need to be raised with the projects directly. Remember to check that " +"the project is still maintained and supported, as the list above may become " +"outdated." +msgstr "" + +#: ../../c-api/intro.rst:926 +msgid "" +"`Python Packaging User Guide: Binary Extensions `_" +msgstr "" + +#: ../../c-api/intro.rst:927 +msgid "" +"The Python Packaging User Guide not only covers several available tools that " +"simplify the creation of binary extensions, but also discusses the various " +"reasons why creating an extension module may be desirable in the first place." +msgstr "" + +#: ../../c-api/intro.rst:344 +msgid "object" +msgstr "object（物件）" + +#: ../../c-api/intro.rst:344 +msgid "type" +msgstr "type（型別）" + +#: ../../c-api/intro.rst:383 +msgid "Py_INCREF (C function)" +msgstr "Py_INCREF（C 函式）" + +#: ../../c-api/intro.rst:383 +msgid "Py_DECREF (C function)" +msgstr "Py_DECREF（C 函式）" + +#: ../../c-api/intro.rst:459 +msgid "PyList_SetItem (C function)" +msgstr "PyList_SetItem（C 函式）" + +#: ../../c-api/intro.rst:459 +msgid "PyTuple_SetItem (C function)" +msgstr "PyTuple_SetItem（C 函式）" + +#: ../../c-api/intro.rst:530 +msgid "set_all()" +msgstr "set_all()" + +#: ../../c-api/intro.rst:549 +msgid "PyList_GetItem (C function)" +msgstr "PyList_GetItem（C 函式）" + +#: ../../c-api/intro.rst:549 +msgid "PySequence_GetItem (C function)" +msgstr "PySequence_GetItem（C 函式）" + +#: ../../c-api/intro.rst:579 +msgid "sum_list()" +msgstr "sum_list()" + +#: ../../c-api/intro.rst:611 ../../c-api/intro.rst:703 +msgid "sum_sequence()" +msgstr "sum_sequence()" + +#: ../../c-api/intro.rst:646 +msgid "PyErr_Occurred (C function)" +msgstr "PyErr_Occurred（C 函式）" + +#: ../../c-api/intro.rst:659 +msgid "PyErr_SetString (C function)" +msgstr "PyErr_SetString（C 函式）" + +#: ../../c-api/intro.rst:659 ../../c-api/intro.rst:767 +msgid "PyErr_Clear (C function)" +msgstr "PyErr_Clear（C 函式）" + +#: ../../c-api/intro.rst:683 +msgid "exc_info (in module sys)" +msgstr "exc_info （sys 模組中）" + +#: ../../c-api/intro.rst:718 ../../c-api/intro.rst:765 +msgid "incr_item()" +msgstr "incr_item()" + +#: ../../c-api/intro.rst:767 +msgid "PyErr_ExceptionMatches (C function)" +msgstr "PyErr_ExceptionMatches（C 函式）" + +#: ../../c-api/intro.rst:767 +msgid "Py_XDECREF (C function)" +msgstr "Py_XDECREF（C 函式）" + +#: ../../c-api/intro.rst:793 +msgid "Py_Initialize (C function)" +msgstr "Py_Initialize（C 函式）" + +#: ../../c-api/intro.rst:793 +msgid "module" +msgstr "module（模組）" + +#: ../../c-api/intro.rst:793 +msgid "builtins" +msgstr "builtins（內建）" + +#: ../../c-api/intro.rst:793 +msgid "__main__" +msgstr "__main__" + +#: ../../c-api/intro.rst:793 +msgid "sys" +msgstr "sys" + +#: ../../c-api/intro.rst:793 +msgid "search" +msgstr "search（搜尋）" + +#: ../../c-api/intro.rst:793 +msgid "path" +msgstr "path（路徑）" + +#: ../../c-api/intro.rst:793 +msgid "path (in module sys)" +msgstr "path（sys 模組中）" + +#: ../../c-api/intro.rst:828 +msgid "Py_GetPath (C function)" +msgstr "Py_GetPath（C 函式）" + +#: ../../c-api/intro.rst:828 +msgid "Py_GetPrefix (C function)" +msgstr "Py_GetPrefix（C 函式）" + +#: ../../c-api/intro.rst:828 +msgid "Py_GetExecPrefix (C function)" +msgstr "Py_GetExecPrefix（C 函式）" + +#: ../../c-api/intro.rst:828 +msgid "Py_GetProgramFullPath (C function)" +msgstr "Py_GetProgramFullPath（C 函式）" + +#: ../../c-api/intro.rst:843 +msgid "Py_IsInitialized (C function)" +msgstr "Py_IsInitialized（C 函式）" diff --git a/c-api/iter.po b/c-api/iter.po index 37c2a713c7..22291f45c8 100644 --- a/c-api/iter.po +++ b/c-api/iter.po @@ -1,99 +1,99 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Liang-Bo Wang , 2015 -# Matt Wang , 2023 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: 2023-07-01 03:44+0800\n" -"Last-Translator: Matt Wang \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" -"X-Generator: Poedit 3.2.2\n" - -#: ../../c-api/iter.rst:6 -msgid "Iterator Protocol" -msgstr "疊代器協定" - -#: ../../c-api/iter.rst:8 -msgid "There are two functions specifically for working with iterators." -msgstr "有兩個專門用於疊代器的函式。" - -#: ../../c-api/iter.rst:12 -msgid "" -"Return non-zero if the object *o* can be safely passed " -"to :c:func:`PyIter_NextItem` and ``0`` otherwise. This function always " -"succeeds." -msgstr "" -"如果物件 *o* 可以安全地傳遞給 :c:func:`PyIter_NextItem` 則回傳非零 (non-zero)，否" -"則回傳 0。這個函式一定會執行成功。" - -#: ../../c-api/iter.rst:18 -msgid "" -"Return non-zero if the object *o* provides the :class:`AsyncIterator` " -"protocol, and ``0`` otherwise. This function always succeeds." -msgstr "" -"如果物件 *o* 有提供 :class:`AsyncIterator` 協定，則回傳非零，否則回傳 0。這個" -"函式一定會執行成功。" - -#: ../../c-api/iter.rst:25 -msgid "" -"Return ``1`` and set *item* to a :term:`strong reference` of the next value " -"of the iterator *iter* on success. Return ``0`` and set *item* to ``NULL`` " -"if there are no remaining values. Return ``-1``, set *item* to ``NULL`` and " -"set an exception on error." -msgstr "" - -#: ../../c-api/iter.rst:34 -msgid "" -"This is an older version of :c:func:`!PyIter_NextItem`, which is retained " -"for backwards compatibility. Prefer :c:func:`PyIter_NextItem`." -msgstr "" -"這是 :c:func:`!PyIter_NextItem` 的舊版本，為了向後相容而保留。請優先使用 :c:func:`PyIter_NextItem`。" - -#: ../../c-api/iter.rst:38 -msgid "" -"Return the next value from the iterator *o*. The object must be an iterator " -"according to :c:func:`PyIter_Check` (it is up to the caller to check this). " -"If there are no remaining values, returns ``NULL`` with no exception set. If " -"an error occurs while retrieving the item, returns ``NULL`` and passes along " -"the exception." -msgstr "" -"回傳疊代器 *o* 的下一個值。根據 :c:func:`PyIter_Check`，該物件必須是一個疊代" -"器（由呼叫者檢查）。如果沒有剩餘值，則回傳 ``NULL`` 且不設定例外。如果檢索項" -"目時發生錯誤，則回傳 ``NULL`` 並傳遞例外。" - -#: ../../c-api/iter.rst:46 -msgid "" -"The enum value used to represent different results of :c:func:`PyIter_Send`." -msgstr "用於表示 :c:func:`PyIter_Send` 不同結果的列舉 (enum) 值。" - -#: ../../c-api/iter.rst:53 -msgid "Sends the *arg* value into the iterator *iter*. Returns:" -msgstr "將 *arg* 值發送到疊代器 *iter* 中。回傳：" - -#: ../../c-api/iter.rst:55 -msgid "" -"``PYGEN_RETURN`` if iterator returns. Return value is returned via *presult*." -msgstr "如果疊代器有回傳則為 ``PYGEN_RETURN``。回傳值透過 *presult* 回傳。" - -#: ../../c-api/iter.rst:56 -msgid "" -"``PYGEN_NEXT`` if iterator yields. Yielded value is returned via *presult*." -msgstr "" -"如果疊代器有產生 (yield) 則為 ``PYGEN_NEXT``。產生值透過 *presult* 回傳。" - -#: ../../c-api/iter.rst:57 -msgid "" -"``PYGEN_ERROR`` if iterator has raised and exception. *presult* is set to " -"``NULL``." -msgstr "如果疊代器引發例外則為 ``PYGEN_ERROR``。 *presult* 被設定為 ``NULL``。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Liang-Bo Wang , 2015 +# Matt Wang , 2023 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: 2023-07-01 03:44+0800\n" +"Last-Translator: Matt Wang \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" +"X-Generator: Poedit 3.2.2\n" + +#: ../../c-api/iter.rst:6 +msgid "Iterator Protocol" +msgstr "疊代器協定" + +#: ../../c-api/iter.rst:8 +msgid "There are two functions specifically for working with iterators." +msgstr "有兩個專門用於疊代器的函式。" + +#: ../../c-api/iter.rst:12 +msgid "" +"Return non-zero if the object *o* can be safely passed " +"to :c:func:`PyIter_NextItem` and ``0`` otherwise. This function always " +"succeeds." +msgstr "" +"如果物件 *o* 可以安全地傳遞給 :c:func:`PyIter_NextItem` 則回傳非零 (non-zero)，否" +"則回傳 0。這個函式一定會執行成功。" + +#: ../../c-api/iter.rst:18 +msgid "" +"Return non-zero if the object *o* provides the :class:`AsyncIterator` " +"protocol, and ``0`` otherwise. This function always succeeds." +msgstr "" +"如果物件 *o* 有提供 :class:`AsyncIterator` 協定，則回傳非零，否則回傳 0。這個" +"函式一定會執行成功。" + +#: ../../c-api/iter.rst:25 +msgid "" +"Return ``1`` and set *item* to a :term:`strong reference` of the next value " +"of the iterator *iter* on success. Return ``0`` and set *item* to ``NULL`` " +"if there are no remaining values. Return ``-1``, set *item* to ``NULL`` and " +"set an exception on error." +msgstr "" + +#: ../../c-api/iter.rst:34 +msgid "" +"This is an older version of :c:func:`!PyIter_NextItem`, which is retained " +"for backwards compatibility. Prefer :c:func:`PyIter_NextItem`." +msgstr "" +"這是 :c:func:`!PyIter_NextItem` 的舊版本，為了向後相容而保留。請優先使用 :c:func:`PyIter_NextItem`。" + +#: ../../c-api/iter.rst:38 +msgid "" +"Return the next value from the iterator *o*. The object must be an iterator " +"according to :c:func:`PyIter_Check` (it is up to the caller to check this). " +"If there are no remaining values, returns ``NULL`` with no exception set. If " +"an error occurs while retrieving the item, returns ``NULL`` and passes along " +"the exception." +msgstr "" +"回傳疊代器 *o* 的下一個值。根據 :c:func:`PyIter_Check`，該物件必須是一個疊代" +"器（由呼叫者檢查）。如果沒有剩餘值，則回傳 ``NULL`` 且不設定例外。如果檢索項" +"目時發生錯誤，則回傳 ``NULL`` 並傳遞例外。" + +#: ../../c-api/iter.rst:46 +msgid "" +"The enum value used to represent different results of :c:func:`PyIter_Send`." +msgstr "用於表示 :c:func:`PyIter_Send` 不同結果的列舉 (enum) 值。" + +#: ../../c-api/iter.rst:53 +msgid "Sends the *arg* value into the iterator *iter*. Returns:" +msgstr "將 *arg* 值發送到疊代器 *iter* 中。回傳：" + +#: ../../c-api/iter.rst:55 +msgid "" +"``PYGEN_RETURN`` if iterator returns. Return value is returned via *presult*." +msgstr "如果疊代器有回傳則為 ``PYGEN_RETURN``。回傳值透過 *presult* 回傳。" + +#: ../../c-api/iter.rst:56 +msgid "" +"``PYGEN_NEXT`` if iterator yields. Yielded value is returned via *presult*." +msgstr "" +"如果疊代器有產生 (yield) 則為 ``PYGEN_NEXT``。產生值透過 *presult* 回傳。" + +#: ../../c-api/iter.rst:57 +msgid "" +"``PYGEN_ERROR`` if iterator has raised and exception. *presult* is set to " +"``NULL``." +msgstr "如果疊代器引發例外則為 ``PYGEN_ERROR``。 *presult* 被設定為 ``NULL``。" diff --git a/c-api/iterator.po b/c-api/iterator.po index 6ada4984c0..151e26e039 100644 --- a/c-api/iterator.po +++ b/c-api/iterator.po @@ -1,152 +1,152 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Leon H., 2017 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-18 00:15+0000\n" -"PO-Revision-Date: 2017-09-22 18:26+0000\n" -"Last-Translator: Leon H.\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" - -#: ../../c-api/iterator.rst:6 -msgid "Iterator Objects" -msgstr "疊代器（Iterator）物件" - -#: ../../c-api/iterator.rst:8 -msgid "" -"Python provides two general-purpose iterator objects. The first, a sequence " -"iterator, works with an arbitrary sequence supporting the :meth:`~object." -"__getitem__` method. The second works with a callable object and a sentinel " -"value, calling the callable for each item in the sequence, and ending the " -"iteration when the sentinel value is returned." -msgstr "" -"Python 提供了兩種通用的疊代器 (iterator) 物件，第一種是序列疊代器 (sequence " -"iterator)，適用於支援 :meth:`~object.__getitem__` 方法的任意序列，第二種是與" -"可呼叫 (callable) 物件和哨兵值 (sentinel value) 一起使用，會呼叫序列中的每個" -"可呼叫物件，當回傳哨兵值時就結束疊代。" - -#: ../../c-api/iterator.rst:17 -msgid "" -"Type object for iterator objects returned by :c:func:`PySeqIter_New` and the " -"one-argument form of the :func:`iter` built-in function for built-in " -"sequence types." -msgstr "" -"此型別物件用於由 :c:func:`PySeqIter_New` 所回傳的疊代器物件以及用於內建序列型" -"別的內建函式 :func:`iter` 的單引數形式。" - -#: ../../c-api/iterator.rst:24 -msgid "" -"Return true if the type of *op* is :c:data:`PySeqIter_Type`. This function " -"always succeeds." -msgstr "" - -#: ../../c-api/iterator.rst:30 -msgid "" -"Return an iterator that works with a general sequence object, *seq*. The " -"iteration ends when the sequence raises :exc:`IndexError` for the " -"subscripting operation." -msgstr "" - -#: ../../c-api/iterator.rst:37 -msgid "" -"Type object for iterator objects returned by :c:func:`PyCallIter_New` and " -"the two-argument form of the :func:`iter` built-in function." -msgstr "" - -#: ../../c-api/iterator.rst:43 -msgid "" -"Return true if the type of *op* is :c:data:`PyCallIter_Type`. This function " -"always succeeds." -msgstr "" - -#: ../../c-api/iterator.rst:49 -msgid "" -"Return a new iterator. The first parameter, *callable*, can be any Python " -"callable object that can be called with no parameters; each call to it " -"should return the next item in the iteration. When *callable* returns a " -"value equal to *sentinel*, the iteration will be terminated." -msgstr "" - -#: ../../c-api/iterator.rst:56 -msgid "Range Objects" -msgstr "Range 物件" - -#: ../../c-api/iterator.rst:60 -msgid "The type object for :class:`range` objects." -msgstr ":class:`range` 物件的型別物件。" - -#: ../../c-api/iterator.rst:65 -msgid "" -"Return true if the object *o* is an instance of a :class:`range` object. " -"This function always succeeds." -msgstr "" - -#: ../../c-api/iterator.rst:70 -msgid "Builtin Iterator Types" -msgstr "內建疊代器型別" - -#: ../../c-api/iterator.rst:72 -msgid "" -"These are built-in iteration types that are included in Python's C API, but " -"provide no additional functions. They are here for completeness." -msgstr "" - -#: ../../c-api/iterator.rst:80 -msgid "C type" -msgstr "C 型別" - -#: ../../c-api/iterator.rst:81 -msgid "Python type" -msgstr "Python 型別" - -#: ../../c-api/iterator.rst:83 -msgid ":py:class:`enumerate`" -msgstr ":py:class:`enumerate`" - -#: ../../c-api/iterator.rst:85 -msgid ":py:class:`filter`" -msgstr ":py:class:`filter`" - -#: ../../c-api/iterator.rst:87 -msgid ":py:class:`map`" -msgstr ":py:class:`map`" - -#: ../../c-api/iterator.rst:89 -msgid ":py:class:`reversed`" -msgstr ":py:class:`reversed`" - -#: ../../c-api/iterator.rst:91 -msgid ":py:class:`zip`" -msgstr ":py:class:`zip`" - -#: ../../c-api/iterator.rst:95 -msgid "Other Iterator Objects" -msgstr "其他疊代器物件" - -#: ../../c-api/iterator.rst:113 -msgid "Type objects for iterators of various built-in objects." -msgstr "各種內建物件的疊代器型別物件。" - -#: ../../c-api/iterator.rst:115 -msgid "" -"Do not create instances of these directly; prefer calling :c:func:" -"`PyObject_GetIter` instead." -msgstr "" - -#: ../../c-api/iterator.rst:118 -msgid "" -"Note that there is no guarantee that a given built-in type uses a given " -"iterator type. For example, iterating over :class:`range` will use one of " -"two iterator types depending on the size of the range. Other types may start " -"using a similar scheme in the future, without warning." -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Leon H., 2017 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-18 00:15+0000\n" +"PO-Revision-Date: 2017-09-22 18:26+0000\n" +"Last-Translator: Leon H.\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" + +#: ../../c-api/iterator.rst:6 +msgid "Iterator Objects" +msgstr "疊代器（Iterator）物件" + +#: ../../c-api/iterator.rst:8 +msgid "" +"Python provides two general-purpose iterator objects. The first, a sequence " +"iterator, works with an arbitrary sequence supporting the :meth:`~object." +"__getitem__` method. The second works with a callable object and a sentinel " +"value, calling the callable for each item in the sequence, and ending the " +"iteration when the sentinel value is returned." +msgstr "" +"Python 提供了兩種通用的疊代器 (iterator) 物件，第一種是序列疊代器 (sequence " +"iterator)，適用於支援 :meth:`~object.__getitem__` 方法的任意序列，第二種是與" +"可呼叫 (callable) 物件和哨兵值 (sentinel value) 一起使用，會呼叫序列中的每個" +"可呼叫物件，當回傳哨兵值時就結束疊代。" + +#: ../../c-api/iterator.rst:17 +msgid "" +"Type object for iterator objects returned by :c:func:`PySeqIter_New` and the " +"one-argument form of the :func:`iter` built-in function for built-in " +"sequence types." +msgstr "" +"此型別物件用於由 :c:func:`PySeqIter_New` 所回傳的疊代器物件以及用於內建序列型" +"別的內建函式 :func:`iter` 的單引數形式。" + +#: ../../c-api/iterator.rst:24 +msgid "" +"Return true if the type of *op* is :c:data:`PySeqIter_Type`. This function " +"always succeeds." +msgstr "" + +#: ../../c-api/iterator.rst:30 +msgid "" +"Return an iterator that works with a general sequence object, *seq*. The " +"iteration ends when the sequence raises :exc:`IndexError` for the " +"subscripting operation." +msgstr "" + +#: ../../c-api/iterator.rst:37 +msgid "" +"Type object for iterator objects returned by :c:func:`PyCallIter_New` and " +"the two-argument form of the :func:`iter` built-in function." +msgstr "" + +#: ../../c-api/iterator.rst:43 +msgid "" +"Return true if the type of *op* is :c:data:`PyCallIter_Type`. This function " +"always succeeds." +msgstr "" + +#: ../../c-api/iterator.rst:49 +msgid "" +"Return a new iterator. The first parameter, *callable*, can be any Python " +"callable object that can be called with no parameters; each call to it " +"should return the next item in the iteration. When *callable* returns a " +"value equal to *sentinel*, the iteration will be terminated." +msgstr "" + +#: ../../c-api/iterator.rst:56 +msgid "Range Objects" +msgstr "Range 物件" + +#: ../../c-api/iterator.rst:60 +msgid "The type object for :class:`range` objects." +msgstr ":class:`range` 物件的型別物件。" + +#: ../../c-api/iterator.rst:65 +msgid "" +"Return true if the object *o* is an instance of a :class:`range` object. " +"This function always succeeds." +msgstr "" + +#: ../../c-api/iterator.rst:70 +msgid "Builtin Iterator Types" +msgstr "內建疊代器型別" + +#: ../../c-api/iterator.rst:72 +msgid "" +"These are built-in iteration types that are included in Python's C API, but " +"provide no additional functions. They are here for completeness." +msgstr "" + +#: ../../c-api/iterator.rst:80 +msgid "C type" +msgstr "C 型別" + +#: ../../c-api/iterator.rst:81 +msgid "Python type" +msgstr "Python 型別" + +#: ../../c-api/iterator.rst:83 +msgid ":py:class:`enumerate`" +msgstr ":py:class:`enumerate`" + +#: ../../c-api/iterator.rst:85 +msgid ":py:class:`filter`" +msgstr ":py:class:`filter`" + +#: ../../c-api/iterator.rst:87 +msgid ":py:class:`map`" +msgstr ":py:class:`map`" + +#: ../../c-api/iterator.rst:89 +msgid ":py:class:`reversed`" +msgstr ":py:class:`reversed`" + +#: ../../c-api/iterator.rst:91 +msgid ":py:class:`zip`" +msgstr ":py:class:`zip`" + +#: ../../c-api/iterator.rst:95 +msgid "Other Iterator Objects" +msgstr "其他疊代器物件" + +#: ../../c-api/iterator.rst:113 +msgid "Type objects for iterators of various built-in objects." +msgstr "各種內建物件的疊代器型別物件。" + +#: ../../c-api/iterator.rst:115 +msgid "" +"Do not create instances of these directly; prefer calling :c:func:" +"`PyObject_GetIter` instead." +msgstr "" + +#: ../../c-api/iterator.rst:118 +msgid "" +"Note that there is no guarantee that a given built-in type uses a given " +"iterator type. For example, iterating over :class:`range` will use one of " +"two iterator types depending on the size of the range. Other types may start " +"using a similar scheme in the future, without warning." +msgstr "" diff --git a/c-api/lifecycle.po b/c-api/lifecycle.po index 1a3bb772c4..1934fc011f 100644 --- a/c-api/lifecycle.po +++ b/c-api/lifecycle.po @@ -1,364 +1,364 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# FIRST AUTHOR , YEAR. -# -#, fuzzy -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language-Team: LANGUAGE \n" -"Language: zh_TW\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=UTF-8\n" -"Content-Transfer-Encoding: 8bit\n" - -#: ../../c-api/lifecycle.rst:6 -msgid "Object Life Cycle" -msgstr "物件生命週期" - -#: ../../c-api/lifecycle.rst:8 -msgid "" -"This section explains how a type's slots relate to each other throughout the " -"life of an object. It is not intended to be a complete canonical reference " -"for the slots; instead, refer to the slot-specific documentation " -"in :ref:`type-structs` for details about a particular slot." -msgstr "" - -#: ../../c-api/lifecycle.rst:15 -msgid "Life Events" -msgstr "生命事件" - -#: ../../c-api/lifecycle.rst:17 -msgid "" -"The figure below illustrates the order of events that can occur throughout " -"an object's life. An arrow from *A* to *B* indicates that event *B* can " -"occur after event *A* has occurred, with the arrow's label indicating the " -"condition that must be true for *B* to occur after *A*." -msgstr "" - -#: ../../c-api/lifecycle.rst:55 ../../c-api/lifecycle.rst:62 -msgid "Diagram showing events in an object's life. Explained in detail below." -msgstr "" - -#: ../../c-api/lifecycle.rst:70 -msgid "Explanation:" -msgstr "說明：" - -#: ../../c-api/lifecycle.rst:72 -msgid "When a new object is constructed by calling its type:" -msgstr "當一個新物件透過其型別來建構時：" - -#: ../../c-api/lifecycle.rst:74 -msgid ":c:member:`~PyTypeObject.tp_new` is called to create a new object." -msgstr ":c:member:`~PyTypeObject.tp_new` 會被呼叫來建立一個新物件。" - -#: ../../c-api/lifecycle.rst:75 -msgid "" -":c:member:`~PyTypeObject.tp_alloc` is directly called " -"by :c:member:`~PyTypeObject.tp_new` to allocate the memory for the new " -"object." -msgstr "" - -#: ../../c-api/lifecycle.rst:78 -msgid "" -":c:member:`~PyTypeObject.tp_init` initializes the newly created " -"object. :c:member:`!tp_init` can be called again to re-initialize an object, " -"if desired. The :c:member:`!tp_init` call can also be skipped entirely, for " -"example by Python code calling :py:meth:`~object.__new__`." -msgstr "" - -#: ../../c-api/lifecycle.rst:83 -msgid "After :c:member:`!tp_init` completes, the object is ready to use." -msgstr "在 :c:member:`!tp_init` 完成後，該物件即可使用。" - -#: ../../c-api/lifecycle.rst:84 -msgid "Some time after the last reference to an object is removed:" -msgstr "在最後一個對物件的參照被移除一段時間後：" - -#: ../../c-api/lifecycle.rst:86 -msgid "" -"If an object is not marked as *finalized*, it might be finalized by marking " -"it as *finalized* and calling its :c:member:`~PyTypeObject.tp_finalize` " -"function. Python does *not* finalize an object when the last reference to " -"it is deleted; use :c:func:`PyObject_CallFinalizerFromDealloc` to ensure " -"that :c:member:`~PyTypeObject.tp_finalize` is always called." -msgstr "" - -#: ../../c-api/lifecycle.rst:92 -msgid "" -"If the object is marked as finalized, :c:member:`~PyTypeObject.tp_clear` " -"might be called by the garbage collector to clear references held by the " -"object. It is *not* called when the object's reference count reaches zero." -msgstr "" - -#: ../../c-api/lifecycle.rst:96 -msgid "" -":c:member:`~PyTypeObject.tp_dealloc` is called to destroy the object. To " -"avoid code duplication, :c:member:`~PyTypeObject.tp_dealloc` typically calls " -"into :c:member:`~PyTypeObject.tp_clear` to free up the object's references." -msgstr "" - -#: ../../c-api/lifecycle.rst:100 -msgid "" -"When :c:member:`~PyTypeObject.tp_dealloc` finishes object destruction, it " -"directly calls :c:member:`~PyTypeObject.tp_free` (usually set " -"to :c:func:`PyObject_Free` or :c:func:`PyObject_GC_Del` automatically as " -"appropriate for the type) to deallocate the memory." -msgstr "" - -#: ../../c-api/lifecycle.rst:105 -msgid "" -"The :c:member:`~PyTypeObject.tp_finalize` function is permitted to add a " -"reference to the object if desired. If it does, the object is " -"*resurrected*, preventing its pending destruction. (Only :c:member:`!" -"tp_finalize` is allowed to resurrect an " -"object; :c:member:`~PyTypeObject.tp_clear` " -"and :c:member:`~PyTypeObject.tp_dealloc` cannot without calling " -"into :c:member:`!tp_finalize`.) Resurrecting an object may or may not cause " -"the object's *finalized* mark to be removed. Currently, Python does not " -"remove the *finalized* mark from a resurrected object if it supports garbage " -"collection (i.e., the :c:macro:`Py_TPFLAGS_HAVE_GC` flag is set) but does " -"remove the mark if the object does not support garbage collection; either or " -"both of these behaviors may change in the future." -msgstr "" - -#: ../../c-api/lifecycle.rst:118 -msgid "" -":c:member:`~PyTypeObject.tp_dealloc` can optionally " -"call :c:member:`~PyTypeObject.tp_finalize` " -"via :c:func:`PyObject_CallFinalizerFromDealloc` if it wishes to reuse that " -"code to help with object destruction. This is recommended because it " -"guarantees that :c:member:`!tp_finalize` is always called before " -"destruction. See the :c:member:`~PyTypeObject.tp_dealloc` documentation for " -"example code." -msgstr "" - -#: ../../c-api/lifecycle.rst:125 -msgid "" -"If the object is a member of a :term:`cyclic isolate` and " -"either :c:member:`~PyTypeObject.tp_clear` fails to break the reference cycle " -"or the cyclic isolate is not detected (perhaps :func:`gc.disable` was " -"called, or the :c:macro:`Py_TPFLAGS_HAVE_GC` flag was erroneously omitted in " -"one of the involved types), the objects remain indefinitely uncollectable " -"(they \"leak\"). See :data:`gc.garbage`." -msgstr "" - -#: ../../c-api/lifecycle.rst:132 -msgid "" -"If the object is marked as supporting garbage collection " -"(the :c:macro:`Py_TPFLAGS_HAVE_GC` flag is set " -"in :c:member:`~PyTypeObject.tp_flags`), the following events are also " -"possible:" -msgstr "" - -#: ../../c-api/lifecycle.rst:136 -msgid "" -"The garbage collector occasionally " -"calls :c:member:`~PyTypeObject.tp_traverse` to identify :term:`cyclic " -"isolates `." -msgstr "" - -#: ../../c-api/lifecycle.rst:139 -msgid "" -"When the garbage collector discovers a :term:`cyclic isolate`, it finalizes " -"one of the objects in the group by marking it as *finalized* and calling " -"its :c:member:`~PyTypeObject.tp_finalize` function, if it has one. This " -"repeats until the cyclic isolate doesn't exist or all of the objects have " -"been finalized." -msgstr "" - -#: ../../c-api/lifecycle.rst:144 -msgid "" -":c:member:`~PyTypeObject.tp_finalize` is permitted to resurrect the object " -"by adding a reference from outside the :term:`cyclic isolate`. The new " -"reference causes the group of objects to no longer form a cyclic isolate " -"(the reference cycle may still exist, but if it does the objects are no " -"longer isolated)." -msgstr "" - -#: ../../c-api/lifecycle.rst:149 -msgid "" -"When the garbage collector discovers a :term:`cyclic isolate` and all of the " -"objects in the group have already been marked as *finalized*, the garbage " -"collector clears one or more of the uncleared objects in the group (possibly " -"concurrently) by calling each's :c:member:`~PyTypeObject.tp_clear` " -"function. This repeats as long as the cyclic isolate still exists and not " -"all of the objects have been cleared." -msgstr "" - -#: ../../c-api/lifecycle.rst:158 -msgid "Cyclic Isolate Destruction" -msgstr "" - -#: ../../c-api/lifecycle.rst:160 -msgid "" -"Listed below are the stages of life of a hypothetical :term:`cyclic isolate` " -"that continues to exist after each member object is finalized or cleared. " -"It is a memory leak if a cyclic isolate progresses through all of these " -"stages; it should vanish once all objects are cleared, if not sooner. A " -"cyclic isolate can vanish either because the reference cycle is broken or " -"because the objects are no longer isolated due to finalizer resurrection " -"(see :c:member:`~PyTypeObject.tp_finalize`)." -msgstr "" - -#: ../../c-api/lifecycle.rst:168 -msgid "" -"**Reachable** (not yet a cyclic isolate): All objects are in their normal, " -"reachable state. A reference cycle could exist, but an external reference " -"means the objects are not yet isolated." -msgstr "" - -#: ../../c-api/lifecycle.rst:171 -msgid "" -"**Unreachable but consistent:** The final reference from outside the cyclic " -"group of objects has been removed, causing the objects to become isolated " -"(thus a cyclic isolate is born). None of the group's objects have been " -"finalized or cleared yet. The cyclic isolate remains at this stage until " -"some future run of the garbage collector (not necessarily the next run " -"because the next run might not scan every object)." -msgstr "" - -#: ../../c-api/lifecycle.rst:177 -msgid "" -"**Mix of finalized and not finalized:** Objects in a cyclic isolate are " -"finalized one at a time, which means that there is a period of time when the " -"cyclic isolate is composed of a mix of finalized and non-finalized objects. " -"Finalization order is unspecified, so it can appear random. A finalized " -"object must behave in a sane manner when non-finalized objects interact with " -"it, and a non-finalized object must be able to tolerate the finalization of " -"an arbitrary subset of its referents." -msgstr "" - -#: ../../c-api/lifecycle.rst:184 -msgid "" -"**All finalized:** All objects in a cyclic isolate are finalized before any " -"of them are cleared." -msgstr "" - -#: ../../c-api/lifecycle.rst:186 -msgid "" -"**Mix of finalized and cleared:** The objects can be cleared serially or " -"concurrently (but with the :term:`GIL` held); either way, some will finish " -"before others. A finalized object must be able to tolerate the clearing of " -"a subset of its referents. :pep:`442` calls this stage \"cyclic trash\"." -msgstr "" - -#: ../../c-api/lifecycle.rst:190 -msgid "" -"**Leaked:** If a cyclic isolate still exists after all objects in the group " -"have been finalized and cleared, then the objects remain indefinitely " -"uncollectable (see :data:`gc.garbage`). It is a bug if a cyclic isolate " -"reaches this stage---it means the :c:member:`~PyTypeObject.tp_clear` methods " -"of the participating objects have failed to break the reference cycle as " -"required." -msgstr "" - -#: ../../c-api/lifecycle.rst:197 -msgid "" -"If :c:member:`~PyTypeObject.tp_clear` did not exist, then Python would have " -"no way to safely break a reference cycle. Simply destroying an object in a " -"cyclic isolate would result in a dangling pointer, triggering undefined " -"behavior when an object referencing the destroyed object is itself " -"destroyed. The clearing step makes object destruction a two-phase process: " -"first :c:member:`~PyTypeObject.tp_clear` is called to partially destroy the " -"objects enough to detangle them from each other, " -"then :c:member:`~PyTypeObject.tp_dealloc` is called to complete the " -"destruction." -msgstr "" - -#: ../../c-api/lifecycle.rst:206 -msgid "" -"Unlike clearing, finalization is not a phase of destruction. A finalized " -"object must still behave properly by continuing to fulfill its design " -"contracts. An object's finalizer is allowed to execute arbitrary Python " -"code, and is even allowed to prevent the impending destruction by adding a " -"reference. The finalizer is only related to destruction by call order---if " -"it runs, it runs before destruction, which starts " -"with :c:member:`~PyTypeObject.tp_clear` (if called) and concludes " -"with :c:member:`~PyTypeObject.tp_dealloc`." -msgstr "" - -#: ../../c-api/lifecycle.rst:214 -msgid "" -"The finalization step is not necessary to safely reclaim the objects in a " -"cyclic isolate, but its existence makes it easier to design types that " -"behave in a sane manner when objects are cleared. Clearing an object might " -"necessarily leave it in a broken, partially destroyed state---it might be " -"unsafe to call any of the cleared object's methods or access any of its " -"attributes. With finalization, only finalized objects can possibly interact " -"with cleared objects; non-finalized objects are guaranteed to interact with " -"only non-cleared (but potentially finalized) objects." -msgstr "" - -#: ../../c-api/lifecycle.rst:223 -msgid "To summarize the possible interactions:" -msgstr "" - -#: ../../c-api/lifecycle.rst:225 -msgid "" -"A non-finalized object might have references to or from non-finalized and " -"finalized objects, but not to or from cleared objects." -msgstr "" - -#: ../../c-api/lifecycle.rst:227 -msgid "" -"A finalized object might have references to or from non-finalized, " -"finalized, and cleared objects." -msgstr "" - -#: ../../c-api/lifecycle.rst:229 -msgid "" -"A cleared object might have references to or from finalized and cleared " -"objects, but not to or from non-finalized objects." -msgstr "" - -#: ../../c-api/lifecycle.rst:232 -msgid "" -"Without any reference cycles, an object can be simply destroyed once its " -"last reference is deleted; the finalization and clearing steps are not " -"necessary to safely reclaim unused objects. However, it can be useful to " -"automatically call :c:member:`~PyTypeObject.tp_finalize` " -"and :c:member:`~PyTypeObject.tp_clear` before destruction anyway because " -"type design is simplified when all objects always experience the same series " -"of events regardless of whether they participated in a cyclic isolate. " -"Python currently only calls :c:member:`~PyTypeObject.tp_finalize` " -"and :c:member:`~PyTypeObject.tp_clear` as needed to destroy a cyclic " -"isolate; this may change in a future version." -msgstr "" - -#: ../../c-api/lifecycle.rst:244 -msgid "Functions" -msgstr "函式" - -#: ../../c-api/lifecycle.rst:246 -msgid "To allocate and free memory, see :ref:`allocating-objects`." -msgstr "要分配和釋放記憶體，請參見 :ref:`allocating-objects`。" - -#: ../../c-api/lifecycle.rst:251 -msgid "" -"Finalizes the object as described in :c:member:`~PyTypeObject.tp_finalize`. " -"Call this function (or :c:func:`PyObject_CallFinalizerFromDealloc`) instead " -"of calling :c:member:`~PyTypeObject.tp_finalize` directly because this " -"function may deduplicate multiple calls to :c:member:`!tp_finalize`. " -"Currently, calls are only deduplicated if the type supports garbage " -"collection (i.e., the :c:macro:`Py_TPFLAGS_HAVE_GC` flag is set); this may " -"change in the future." -msgstr "" - -#: ../../c-api/lifecycle.rst:262 -msgid "" -"Same as :c:func:`PyObject_CallFinalizer` but meant to be called at the " -"beginning of the object's destructor (:c:member:`~PyTypeObject.tp_dealloc`). " -"There must not be any references to the object. If the object's finalizer " -"resurrects the object, this function returns -1; no further destruction " -"should happen. Otherwise, this function returns 0 and destruction can " -"continue normally." -msgstr "" - -#: ../../c-api/lifecycle.rst:271 -msgid ":c:member:`~PyTypeObject.tp_dealloc` for example code." -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"Language: zh_TW\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../c-api/lifecycle.rst:6 +msgid "Object Life Cycle" +msgstr "物件生命週期" + +#: ../../c-api/lifecycle.rst:8 +msgid "" +"This section explains how a type's slots relate to each other throughout the " +"life of an object. It is not intended to be a complete canonical reference " +"for the slots; instead, refer to the slot-specific documentation " +"in :ref:`type-structs` for details about a particular slot." +msgstr "" + +#: ../../c-api/lifecycle.rst:15 +msgid "Life Events" +msgstr "生命事件" + +#: ../../c-api/lifecycle.rst:17 +msgid "" +"The figure below illustrates the order of events that can occur throughout " +"an object's life. An arrow from *A* to *B* indicates that event *B* can " +"occur after event *A* has occurred, with the arrow's label indicating the " +"condition that must be true for *B* to occur after *A*." +msgstr "" + +#: ../../c-api/lifecycle.rst:55 ../../c-api/lifecycle.rst:62 +msgid "Diagram showing events in an object's life. Explained in detail below." +msgstr "" + +#: ../../c-api/lifecycle.rst:70 +msgid "Explanation:" +msgstr "說明：" + +#: ../../c-api/lifecycle.rst:72 +msgid "When a new object is constructed by calling its type:" +msgstr "當一個新物件透過其型別來建構時：" + +#: ../../c-api/lifecycle.rst:74 +msgid ":c:member:`~PyTypeObject.tp_new` is called to create a new object." +msgstr ":c:member:`~PyTypeObject.tp_new` 會被呼叫來建立一個新物件。" + +#: ../../c-api/lifecycle.rst:75 +msgid "" +":c:member:`~PyTypeObject.tp_alloc` is directly called " +"by :c:member:`~PyTypeObject.tp_new` to allocate the memory for the new " +"object." +msgstr "" + +#: ../../c-api/lifecycle.rst:78 +msgid "" +":c:member:`~PyTypeObject.tp_init` initializes the newly created " +"object. :c:member:`!tp_init` can be called again to re-initialize an object, " +"if desired. The :c:member:`!tp_init` call can also be skipped entirely, for " +"example by Python code calling :py:meth:`~object.__new__`." +msgstr "" + +#: ../../c-api/lifecycle.rst:83 +msgid "After :c:member:`!tp_init` completes, the object is ready to use." +msgstr "在 :c:member:`!tp_init` 完成後，該物件即可使用。" + +#: ../../c-api/lifecycle.rst:84 +msgid "Some time after the last reference to an object is removed:" +msgstr "在最後一個對物件的參照被移除一段時間後：" + +#: ../../c-api/lifecycle.rst:86 +msgid "" +"If an object is not marked as *finalized*, it might be finalized by marking " +"it as *finalized* and calling its :c:member:`~PyTypeObject.tp_finalize` " +"function. Python does *not* finalize an object when the last reference to " +"it is deleted; use :c:func:`PyObject_CallFinalizerFromDealloc` to ensure " +"that :c:member:`~PyTypeObject.tp_finalize` is always called." +msgstr "" + +#: ../../c-api/lifecycle.rst:92 +msgid "" +"If the object is marked as finalized, :c:member:`~PyTypeObject.tp_clear` " +"might be called by the garbage collector to clear references held by the " +"object. It is *not* called when the object's reference count reaches zero." +msgstr "" + +#: ../../c-api/lifecycle.rst:96 +msgid "" +":c:member:`~PyTypeObject.tp_dealloc` is called to destroy the object. To " +"avoid code duplication, :c:member:`~PyTypeObject.tp_dealloc` typically calls " +"into :c:member:`~PyTypeObject.tp_clear` to free up the object's references." +msgstr "" + +#: ../../c-api/lifecycle.rst:100 +msgid "" +"When :c:member:`~PyTypeObject.tp_dealloc` finishes object destruction, it " +"directly calls :c:member:`~PyTypeObject.tp_free` (usually set " +"to :c:func:`PyObject_Free` or :c:func:`PyObject_GC_Del` automatically as " +"appropriate for the type) to deallocate the memory." +msgstr "" + +#: ../../c-api/lifecycle.rst:105 +msgid "" +"The :c:member:`~PyTypeObject.tp_finalize` function is permitted to add a " +"reference to the object if desired. If it does, the object is " +"*resurrected*, preventing its pending destruction. (Only :c:member:`!" +"tp_finalize` is allowed to resurrect an " +"object; :c:member:`~PyTypeObject.tp_clear` " +"and :c:member:`~PyTypeObject.tp_dealloc` cannot without calling " +"into :c:member:`!tp_finalize`.) Resurrecting an object may or may not cause " +"the object's *finalized* mark to be removed. Currently, Python does not " +"remove the *finalized* mark from a resurrected object if it supports garbage " +"collection (i.e., the :c:macro:`Py_TPFLAGS_HAVE_GC` flag is set) but does " +"remove the mark if the object does not support garbage collection; either or " +"both of these behaviors may change in the future." +msgstr "" + +#: ../../c-api/lifecycle.rst:118 +msgid "" +":c:member:`~PyTypeObject.tp_dealloc` can optionally " +"call :c:member:`~PyTypeObject.tp_finalize` " +"via :c:func:`PyObject_CallFinalizerFromDealloc` if it wishes to reuse that " +"code to help with object destruction. This is recommended because it " +"guarantees that :c:member:`!tp_finalize` is always called before " +"destruction. See the :c:member:`~PyTypeObject.tp_dealloc` documentation for " +"example code." +msgstr "" + +#: ../../c-api/lifecycle.rst:125 +msgid "" +"If the object is a member of a :term:`cyclic isolate` and " +"either :c:member:`~PyTypeObject.tp_clear` fails to break the reference cycle " +"or the cyclic isolate is not detected (perhaps :func:`gc.disable` was " +"called, or the :c:macro:`Py_TPFLAGS_HAVE_GC` flag was erroneously omitted in " +"one of the involved types), the objects remain indefinitely uncollectable " +"(they \"leak\"). See :data:`gc.garbage`." +msgstr "" + +#: ../../c-api/lifecycle.rst:132 +msgid "" +"If the object is marked as supporting garbage collection " +"(the :c:macro:`Py_TPFLAGS_HAVE_GC` flag is set " +"in :c:member:`~PyTypeObject.tp_flags`), the following events are also " +"possible:" +msgstr "" + +#: ../../c-api/lifecycle.rst:136 +msgid "" +"The garbage collector occasionally " +"calls :c:member:`~PyTypeObject.tp_traverse` to identify :term:`cyclic " +"isolates `." +msgstr "" + +#: ../../c-api/lifecycle.rst:139 +msgid "" +"When the garbage collector discovers a :term:`cyclic isolate`, it finalizes " +"one of the objects in the group by marking it as *finalized* and calling " +"its :c:member:`~PyTypeObject.tp_finalize` function, if it has one. This " +"repeats until the cyclic isolate doesn't exist or all of the objects have " +"been finalized." +msgstr "" + +#: ../../c-api/lifecycle.rst:144 +msgid "" +":c:member:`~PyTypeObject.tp_finalize` is permitted to resurrect the object " +"by adding a reference from outside the :term:`cyclic isolate`. The new " +"reference causes the group of objects to no longer form a cyclic isolate " +"(the reference cycle may still exist, but if it does the objects are no " +"longer isolated)." +msgstr "" + +#: ../../c-api/lifecycle.rst:149 +msgid "" +"When the garbage collector discovers a :term:`cyclic isolate` and all of the " +"objects in the group have already been marked as *finalized*, the garbage " +"collector clears one or more of the uncleared objects in the group (possibly " +"concurrently) by calling each's :c:member:`~PyTypeObject.tp_clear` " +"function. This repeats as long as the cyclic isolate still exists and not " +"all of the objects have been cleared." +msgstr "" + +#: ../../c-api/lifecycle.rst:158 +msgid "Cyclic Isolate Destruction" +msgstr "" + +#: ../../c-api/lifecycle.rst:160 +msgid "" +"Listed below are the stages of life of a hypothetical :term:`cyclic isolate` " +"that continues to exist after each member object is finalized or cleared. " +"It is a memory leak if a cyclic isolate progresses through all of these " +"stages; it should vanish once all objects are cleared, if not sooner. A " +"cyclic isolate can vanish either because the reference cycle is broken or " +"because the objects are no longer isolated due to finalizer resurrection " +"(see :c:member:`~PyTypeObject.tp_finalize`)." +msgstr "" + +#: ../../c-api/lifecycle.rst:168 +msgid "" +"**Reachable** (not yet a cyclic isolate): All objects are in their normal, " +"reachable state. A reference cycle could exist, but an external reference " +"means the objects are not yet isolated." +msgstr "" + +#: ../../c-api/lifecycle.rst:171 +msgid "" +"**Unreachable but consistent:** The final reference from outside the cyclic " +"group of objects has been removed, causing the objects to become isolated " +"(thus a cyclic isolate is born). None of the group's objects have been " +"finalized or cleared yet. The cyclic isolate remains at this stage until " +"some future run of the garbage collector (not necessarily the next run " +"because the next run might not scan every object)." +msgstr "" + +#: ../../c-api/lifecycle.rst:177 +msgid "" +"**Mix of finalized and not finalized:** Objects in a cyclic isolate are " +"finalized one at a time, which means that there is a period of time when the " +"cyclic isolate is composed of a mix of finalized and non-finalized objects. " +"Finalization order is unspecified, so it can appear random. A finalized " +"object must behave in a sane manner when non-finalized objects interact with " +"it, and a non-finalized object must be able to tolerate the finalization of " +"an arbitrary subset of its referents." +msgstr "" + +#: ../../c-api/lifecycle.rst:184 +msgid "" +"**All finalized:** All objects in a cyclic isolate are finalized before any " +"of them are cleared." +msgstr "" + +#: ../../c-api/lifecycle.rst:186 +msgid "" +"**Mix of finalized and cleared:** The objects can be cleared serially or " +"concurrently (but with the :term:`GIL` held); either way, some will finish " +"before others. A finalized object must be able to tolerate the clearing of " +"a subset of its referents. :pep:`442` calls this stage \"cyclic trash\"." +msgstr "" + +#: ../../c-api/lifecycle.rst:190 +msgid "" +"**Leaked:** If a cyclic isolate still exists after all objects in the group " +"have been finalized and cleared, then the objects remain indefinitely " +"uncollectable (see :data:`gc.garbage`). It is a bug if a cyclic isolate " +"reaches this stage---it means the :c:member:`~PyTypeObject.tp_clear` methods " +"of the participating objects have failed to break the reference cycle as " +"required." +msgstr "" + +#: ../../c-api/lifecycle.rst:197 +msgid "" +"If :c:member:`~PyTypeObject.tp_clear` did not exist, then Python would have " +"no way to safely break a reference cycle. Simply destroying an object in a " +"cyclic isolate would result in a dangling pointer, triggering undefined " +"behavior when an object referencing the destroyed object is itself " +"destroyed. The clearing step makes object destruction a two-phase process: " +"first :c:member:`~PyTypeObject.tp_clear` is called to partially destroy the " +"objects enough to detangle them from each other, " +"then :c:member:`~PyTypeObject.tp_dealloc` is called to complete the " +"destruction." +msgstr "" + +#: ../../c-api/lifecycle.rst:206 +msgid "" +"Unlike clearing, finalization is not a phase of destruction. A finalized " +"object must still behave properly by continuing to fulfill its design " +"contracts. An object's finalizer is allowed to execute arbitrary Python " +"code, and is even allowed to prevent the impending destruction by adding a " +"reference. The finalizer is only related to destruction by call order---if " +"it runs, it runs before destruction, which starts " +"with :c:member:`~PyTypeObject.tp_clear` (if called) and concludes " +"with :c:member:`~PyTypeObject.tp_dealloc`." +msgstr "" + +#: ../../c-api/lifecycle.rst:214 +msgid "" +"The finalization step is not necessary to safely reclaim the objects in a " +"cyclic isolate, but its existence makes it easier to design types that " +"behave in a sane manner when objects are cleared. Clearing an object might " +"necessarily leave it in a broken, partially destroyed state---it might be " +"unsafe to call any of the cleared object's methods or access any of its " +"attributes. With finalization, only finalized objects can possibly interact " +"with cleared objects; non-finalized objects are guaranteed to interact with " +"only non-cleared (but potentially finalized) objects." +msgstr "" + +#: ../../c-api/lifecycle.rst:223 +msgid "To summarize the possible interactions:" +msgstr "" + +#: ../../c-api/lifecycle.rst:225 +msgid "" +"A non-finalized object might have references to or from non-finalized and " +"finalized objects, but not to or from cleared objects." +msgstr "" + +#: ../../c-api/lifecycle.rst:227 +msgid "" +"A finalized object might have references to or from non-finalized, " +"finalized, and cleared objects." +msgstr "" + +#: ../../c-api/lifecycle.rst:229 +msgid "" +"A cleared object might have references to or from finalized and cleared " +"objects, but not to or from non-finalized objects." +msgstr "" + +#: ../../c-api/lifecycle.rst:232 +msgid "" +"Without any reference cycles, an object can be simply destroyed once its " +"last reference is deleted; the finalization and clearing steps are not " +"necessary to safely reclaim unused objects. However, it can be useful to " +"automatically call :c:member:`~PyTypeObject.tp_finalize` " +"and :c:member:`~PyTypeObject.tp_clear` before destruction anyway because " +"type design is simplified when all objects always experience the same series " +"of events regardless of whether they participated in a cyclic isolate. " +"Python currently only calls :c:member:`~PyTypeObject.tp_finalize` " +"and :c:member:`~PyTypeObject.tp_clear` as needed to destroy a cyclic " +"isolate; this may change in a future version." +msgstr "" + +#: ../../c-api/lifecycle.rst:244 +msgid "Functions" +msgstr "函式" + +#: ../../c-api/lifecycle.rst:246 +msgid "To allocate and free memory, see :ref:`allocating-objects`." +msgstr "要分配和釋放記憶體，請參見 :ref:`allocating-objects`。" + +#: ../../c-api/lifecycle.rst:251 +msgid "" +"Finalizes the object as described in :c:member:`~PyTypeObject.tp_finalize`. " +"Call this function (or :c:func:`PyObject_CallFinalizerFromDealloc`) instead " +"of calling :c:member:`~PyTypeObject.tp_finalize` directly because this " +"function may deduplicate multiple calls to :c:member:`!tp_finalize`. " +"Currently, calls are only deduplicated if the type supports garbage " +"collection (i.e., the :c:macro:`Py_TPFLAGS_HAVE_GC` flag is set); this may " +"change in the future." +msgstr "" + +#: ../../c-api/lifecycle.rst:262 +msgid "" +"Same as :c:func:`PyObject_CallFinalizer` but meant to be called at the " +"beginning of the object's destructor (:c:member:`~PyTypeObject.tp_dealloc`). " +"There must not be any references to the object. If the object's finalizer " +"resurrects the object, this function returns -1; no further destruction " +"should happen. Otherwise, this function returns 0 and destruction can " +"continue normally." +msgstr "" + +#: ../../c-api/lifecycle.rst:271 +msgid ":c:member:`~PyTypeObject.tp_dealloc` for example code." +msgstr "" diff --git a/c-api/list.po b/c-api/list.po index f9671f5700..10e9d3a82b 100644 --- a/c-api/list.po +++ b/c-api/list.po @@ -1,271 +1,271 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Nkeys Syu , 2016 -# Matt Wang , 2023 -# Yorkxe , 2025 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-09-23 07:52+0800\n" -"PO-Revision-Date: 2025-11-25 22:16+0800\n" -"Last-Translator: Yorkxe \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" -"X-Generator: Poedit 3.2.2\n" - -#: ../../c-api/list.rst:6 -msgid "List Objects" -msgstr "List（串列）物件" - -#: ../../c-api/list.rst:13 -msgid "This subtype of :c:type:`PyObject` represents a Python list object." -msgstr ":c:type:`PyObject` 的這個子型別表示 Python 的 list（串列）物件。" - -#: ../../c-api/list.rst:18 -msgid "" -"This instance of :c:type:`PyTypeObject` represents the Python list type. " -"This is the same object as :class:`list` in the Python layer." -msgstr "" -"此 :c:type:`PyTypeObject` 實例表示 Python 的 list 型別。這與 Python 層中" -"的 :class:`list` 是同一個物件。" - -#: ../../c-api/list.rst:24 -msgid "" -"Return true if *p* is a list object or an instance of a subtype of the list " -"type. This function always succeeds." -msgstr "" -"如果 *p* 是一個 list 物件或者是 list 型別之子型別的實例，就回傳 true。這個函" -"式永遠會成功執行。" - -#: ../../c-api/list.rst:30 -msgid "" -"Return true if *p* is a list object, but not an instance of a subtype of the " -"list type. This function always succeeds." -msgstr "" -"如果 *p* 是一個 list 物件但不是 list 型別的子型別的實例，就回傳 true。這個函" -"式永遠會成功執行。" - -#: ../../c-api/list.rst:36 -msgid "Return a new list of length *len* on success, or ``NULL`` on failure." -msgstr "成功時回傳長度為 *len* 的新串列，失敗時回傳 ``NULL``。" - -#: ../../c-api/list.rst:40 -msgid "" -"If *len* is greater than zero, the returned list object's items are set to " -"``NULL``. Thus you cannot use abstract API functions such " -"as :c:func:`PySequence_SetItem` or expose the object to Python code before " -"setting all items to a real object with :c:func:`PyList_SetItem` " -"or :c:func:`PyList_SET_ITEM()`. The following APIs are safe APIs before the " -"list is fully initialized: :c:func:`PyList_SetItem()` " -"and :c:func:`PyList_SET_ITEM()`." -msgstr "" -"如果 *len* 大於零，則回傳的串列物件之項目將被設定為 ``NULL``。因此，在使" -"用 :c:func:`PyList_SetItem` 或 :c:func:`PyList_SET_ITEM()` 來將所有項目設定為" -"一個真實物件前，你無法使用像是 :c:func:`PySequence_SetItem` 的抽象 API 函式，" -"也不能將物件暴露 (expose) 給 Python 程式碼。以下 API 在串列完全初始化之前是安" -"全的：:c:func:`PyList_SetItem()` 和 :c:func:`PyList_SET_ITEM()`。" - -#: ../../c-api/list.rst:53 -msgid "" -"Return the length of the list object in *list*; this is equivalent to " -"``len(list)`` on a list object." -msgstr "回傳 *list* 串列物件的長度；這相當於串列物件的 ``len(list)``。" - -#: ../../c-api/list.rst:59 -msgid "Similar to :c:func:`PyList_Size`, but without error checking." -msgstr "與 :c:func:`PyList_Size` 類似，但沒有錯誤檢查。" - -#: ../../c-api/list.rst:64 -msgid "" -"Return the object at position *index* in the list pointed to by *list*. The " -"position must be non-negative; indexing from the end of the list is not " -"supported. If *index* is out of bounds (:code:`<0 or >=len(list)`), return " -"``NULL`` and set an :exc:`IndexError` exception." -msgstr "" -"回傳 *list* 指向的串列中位於 *index* 位置的物件。該位置不可為負數；並不支援從" -"串列尾末開始索引。如果 *index* 超出邊界範圍 (:code:`<0 or >=len(list)`) 則回" -"傳 ``NULL`` 並設定 :exc:`IndexError` 例外。" - -#: ../../c-api/list.rst:74 -msgid "" -"Like :c:func:`PyList_GetItemRef`, but returns a :term:`borrowed reference` " -"instead of a :term:`strong reference`." -msgstr "" -"與 :c:func:`PyList_GetItemRef` 類似，但回傳一個 :term:`borrowed reference` " -"而非一個 :term:`strong reference`。" - -#: ../../c-api/list.rst:80 -msgid "Similar to :c:func:`PyList_GetItem`, but without error checking." -msgstr "與 :c:func:`PyList_GetItem` 類似，但沒有錯誤檢查。" - -#: ../../c-api/list.rst:85 -msgid "" -"Set the item at index *index* in list to *item*. Return ``0`` on success. " -"If *index* is out of bounds, return ``-1`` and set an :exc:`IndexError` " -"exception." -msgstr "" -"將串列中索引 *index* 處的項目設定為 *item*。成功時回傳 ``0``。如果 *index* 超" -"出邊界範圍則回傳 ``-1`` 並設定一個 :exc:`IndexError` 例外。" - -#: ../../c-api/list.rst:91 -msgid "" -"This function \"steals\" a reference to *item* and discards a reference to " -"an item already in the list at the affected position." -msgstr "此函式「竊取」對 *item* 的參照，並丟棄對串列中受影響位置上已存在項目的參照。" - -#: ../../c-api/list.rst:97 -msgid "" -"Macro form of :c:func:`PyList_SetItem` without error checking. This is " -"normally only used to fill in new lists where there is no previous content." -msgstr "" -":c:func:`PyList_SetItem` 的巨集形式，沒有錯誤檢查。這通常僅用於填充沒有已存在" -"內容的新串列。" - -#: ../../c-api/list.rst:100 -msgid "" -"Bounds checking is performed as an assertion if Python is built " -"in :ref:`debug mode ` or :option:`with assertions <--with-" -"assertions>`." -msgstr "" -"如果 Python 是以\\ :ref:`偵錯模式 `\\ 或 " -":option:`with assertions <--with-assertions>` 建置，則會進行作為" -"斷言（asserting）的邊界檢查。" - -#: ../../c-api/list.rst:106 -msgid "" -"This macro \"steals\" a reference to *item*, and, " -"unlike :c:func:`PyList_SetItem`, does *not* discard a reference to any item " -"that is being replaced; any reference in *list* at position *i* will be " -"leaked." -msgstr "" -"該巨集「竊取」對 *item* 的參照，並且與 :c:func:`PyList_SetItem` 不同的是，它" -"\\ *不會*\\ 丟棄對任意被替換項目的參照；*list* 中位置 *i* 的任何參照都將被洩" -"漏 (leak)。" - -#: ../../c-api/list.rst:114 -msgid "" -"Insert the item *item* into list *list* in front of index *index*. Return " -"``0`` if successful; return ``-1`` and set an exception if unsuccessful. " -"Analogous to ``list.insert(index, item)``." -msgstr "" -"將項目 *item* 插入串列 *list* 中索引 *index* 的位置之前。如果成功則回傳 " -"``0``；如果失敗則回傳 ``-1`` 並設定例外。類似於 ``list.insert(index, " -"item)``。" - -#: ../../c-api/list.rst:121 -msgid "" -"Append the object *item* at the end of list *list*. Return ``0`` if " -"successful; return ``-1`` and set an exception if unsuccessful. Analogous " -"to ``list.append(item)``." -msgstr "" -"將物件 *item* 附加到串列 *list* 的最後面。如果成功則回傳 ``0``；如果不成功，" -"則回傳 ``-1`` 並設定例外。類似於 ``list.append(item)``。" - -#: ../../c-api/list.rst:128 -msgid "" -"Return a list of the objects in *list* containing the objects *between* " -"*low* and *high*. Return ``NULL`` and set an exception if unsuccessful. " -"Analogous to ``list[low:high]``. Indexing from the end of the list is not " -"supported." -msgstr "" -"回傳 *list* 中的物件串列，其中包含 *low* 和 *high* *之間*\\ 的物件。如果沒有" -"成功則回傳 ``NULL`` 並設定例外。類似於 ``list[low:high]``。不支援從串列尾末開" -"始索引。" - -#: ../../c-api/list.rst:135 -msgid "" -"Set the slice of *list* between *low* and *high* to the contents of " -"*itemlist*. Analogous to ``list[low:high] = itemlist``. The *itemlist* may " -"be ``NULL``, indicating the assignment of an empty list (slice deletion). " -"Return ``0`` on success, ``-1`` on failure. Indexing from the end of the " -"list is not supported." -msgstr "" -"將 *low* 和 *high* 之間的 *list* 切片設定為 *itemlist* 的內容。類似於 " -"``list[low:high] = itemlist``。*itemlist* 可能為 ``NULL``，表示分配一個空串列" -"（切片刪除）。成功時回傳 ``0``，失敗時則回傳 ``-1``。不支援從串列尾末開始索" -"引。" - -#: ../../c-api/list.rst:144 -msgid "" -"Extend *list* with the contents of *iterable*. This is the same as " -"``PyList_SetSlice(list, PY_SSIZE_T_MAX, PY_SSIZE_T_MAX, iterable)`` and " -"analogous to ``list.extend(iterable)`` or ``list += iterable``." -msgstr "" -"以 *iterable* 中的內容擴展 *list*。這與 ``PyList_SetSlice(list, " -"PY_SSIZE_T_MAX, PY_SSIZE_T_MAX, iterable)`` 相同，類似於 " -"``list.extend(iterable)`` 或 ``list += iterable``。" - -#: ../../c-api/list.rst:148 -msgid "" -"Raise an exception and return ``-1`` if *list* is not a :class:`list` " -"object. Return 0 on success." -msgstr "" -"引發一個例外並回傳 ``-1`` 如果 *list* 不是一個 :class:`list` 物件。如果成功回" -"傳 0。" - -#: ../../c-api/list.rst:156 -msgid "" -"Remove all items from *list*. This is the same as ``PyList_SetSlice(list, " -"0, PY_SSIZE_T_MAX, NULL)`` and analogous to ``list.clear()`` or ``del " -"list[:]``." -msgstr "移除 *list* 中的所有項目。這與 ``PyList_SetSlice(list, 0, PY_SSIZE_T_MAX, " -"NULL)`` 相同，類似於 ``list.clear()`` 或 ``del list[:]``。" - -#: ../../c-api/list.rst:160 -msgid "" -"Raise an exception and return ``-1`` if *list* is not a :class:`list` " -"object. Return 0 on success." -msgstr "引發一個例外並回傳 ``-1`` 如果 *list* 不是一個 :class:`list` 物件。" -"如果成功回傳 0。" - -#: ../../c-api/list.rst:168 -msgid "" -"Sort the items of *list* in place. Return ``0`` on success, ``-1`` on " -"failure. This is equivalent to ``list.sort()``." -msgstr "" -"對 *list* 的項目進行原地 (in place) 排序。成功時回傳 ``0``，失敗時回傳 " -"``-1``。這相當於 ``list.sort()``。" - -#: ../../c-api/list.rst:174 -msgid "" -"Reverse the items of *list* in place. Return ``0`` on success, ``-1`` on " -"failure. This is the equivalent of ``list.reverse()``." -msgstr "" -"原地反轉 *list* 的項目。成功時回傳 ``0``，失敗時回傳 ``-1``。這相當於 " -"``list.reverse()``。" - -#: ../../c-api/list.rst:182 -msgid "" -"Return a new tuple object containing the contents of *list*; equivalent to " -"``tuple(list)``." -msgstr "" -"回傳一個新的 tuple（元組）物件，其中包含 *list* 的內容；相當於 " -"``tuple(list)``。" - -#: ../../c-api/list.rst:8 -msgid "object" -msgstr "object（物件）" - -#: ../../c-api/list.rst:8 -msgid "list" -msgstr "list（串列）" - -#: ../../c-api/list.rst:51 ../../c-api/list.rst:180 -msgid "built-in function" -msgstr "built-in function（內建函式）" - -#: ../../c-api/list.rst:51 -msgid "len" -msgstr "len" - -#: ../../c-api/list.rst:180 -msgid "tuple" -msgstr "tuple（元組）" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Nkeys Syu , 2016 +# Matt Wang , 2023 +# Yorkxe , 2025 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-09-23 07:52+0800\n" +"PO-Revision-Date: 2025-11-25 22:16+0800\n" +"Last-Translator: Yorkxe \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" +"X-Generator: Poedit 3.2.2\n" + +#: ../../c-api/list.rst:6 +msgid "List Objects" +msgstr "List（串列）物件" + +#: ../../c-api/list.rst:13 +msgid "This subtype of :c:type:`PyObject` represents a Python list object." +msgstr ":c:type:`PyObject` 的這個子型別表示 Python 的 list（串列）物件。" + +#: ../../c-api/list.rst:18 +msgid "" +"This instance of :c:type:`PyTypeObject` represents the Python list type. " +"This is the same object as :class:`list` in the Python layer." +msgstr "" +"此 :c:type:`PyTypeObject` 實例表示 Python 的 list 型別。這與 Python 層中" +"的 :class:`list` 是同一個物件。" + +#: ../../c-api/list.rst:24 +msgid "" +"Return true if *p* is a list object or an instance of a subtype of the list " +"type. This function always succeeds." +msgstr "" +"如果 *p* 是一個 list 物件或者是 list 型別之子型別的實例，就回傳 true。這個函" +"式永遠會成功執行。" + +#: ../../c-api/list.rst:30 +msgid "" +"Return true if *p* is a list object, but not an instance of a subtype of the " +"list type. This function always succeeds." +msgstr "" +"如果 *p* 是一個 list 物件但不是 list 型別的子型別的實例，就回傳 true。這個函" +"式永遠會成功執行。" + +#: ../../c-api/list.rst:36 +msgid "Return a new list of length *len* on success, or ``NULL`` on failure." +msgstr "成功時回傳長度為 *len* 的新串列，失敗時回傳 ``NULL``。" + +#: ../../c-api/list.rst:40 +msgid "" +"If *len* is greater than zero, the returned list object's items are set to " +"``NULL``. Thus you cannot use abstract API functions such " +"as :c:func:`PySequence_SetItem` or expose the object to Python code before " +"setting all items to a real object with :c:func:`PyList_SetItem` " +"or :c:func:`PyList_SET_ITEM()`. The following APIs are safe APIs before the " +"list is fully initialized: :c:func:`PyList_SetItem()` " +"and :c:func:`PyList_SET_ITEM()`." +msgstr "" +"如果 *len* 大於零，則回傳的串列物件之項目將被設定為 ``NULL``。因此，在使" +"用 :c:func:`PyList_SetItem` 或 :c:func:`PyList_SET_ITEM()` 來將所有項目設定為" +"一個真實物件前，你無法使用像是 :c:func:`PySequence_SetItem` 的抽象 API 函式，" +"也不能將物件暴露 (expose) 給 Python 程式碼。以下 API 在串列完全初始化之前是安" +"全的：:c:func:`PyList_SetItem()` 和 :c:func:`PyList_SET_ITEM()`。" + +#: ../../c-api/list.rst:53 +msgid "" +"Return the length of the list object in *list*; this is equivalent to " +"``len(list)`` on a list object." +msgstr "回傳 *list* 串列物件的長度；這相當於串列物件的 ``len(list)``。" + +#: ../../c-api/list.rst:59 +msgid "Similar to :c:func:`PyList_Size`, but without error checking." +msgstr "與 :c:func:`PyList_Size` 類似，但沒有錯誤檢查。" + +#: ../../c-api/list.rst:64 +msgid "" +"Return the object at position *index* in the list pointed to by *list*. The " +"position must be non-negative; indexing from the end of the list is not " +"supported. If *index* is out of bounds (:code:`<0 or >=len(list)`), return " +"``NULL`` and set an :exc:`IndexError` exception." +msgstr "" +"回傳 *list* 指向的串列中位於 *index* 位置的物件。該位置不可為負數；並不支援從" +"串列尾末開始索引。如果 *index* 超出邊界範圍 (:code:`<0 or >=len(list)`) 則回" +"傳 ``NULL`` 並設定 :exc:`IndexError` 例外。" + +#: ../../c-api/list.rst:74 +msgid "" +"Like :c:func:`PyList_GetItemRef`, but returns a :term:`borrowed reference` " +"instead of a :term:`strong reference`." +msgstr "" +"與 :c:func:`PyList_GetItemRef` 類似，但回傳一個 :term:`borrowed reference` " +"而非一個 :term:`strong reference`。" + +#: ../../c-api/list.rst:80 +msgid "Similar to :c:func:`PyList_GetItem`, but without error checking." +msgstr "與 :c:func:`PyList_GetItem` 類似，但沒有錯誤檢查。" + +#: ../../c-api/list.rst:85 +msgid "" +"Set the item at index *index* in list to *item*. Return ``0`` on success. " +"If *index* is out of bounds, return ``-1`` and set an :exc:`IndexError` " +"exception." +msgstr "" +"將串列中索引 *index* 處的項目設定為 *item*。成功時回傳 ``0``。如果 *index* 超" +"出邊界範圍則回傳 ``-1`` 並設定一個 :exc:`IndexError` 例外。" + +#: ../../c-api/list.rst:91 +msgid "" +"This function \"steals\" a reference to *item* and discards a reference to " +"an item already in the list at the affected position." +msgstr "此函式「竊取」對 *item* 的參照，並丟棄對串列中受影響位置上已存在項目的參照。" + +#: ../../c-api/list.rst:97 +msgid "" +"Macro form of :c:func:`PyList_SetItem` without error checking. This is " +"normally only used to fill in new lists where there is no previous content." +msgstr "" +":c:func:`PyList_SetItem` 的巨集形式，沒有錯誤檢查。這通常僅用於填充沒有已存在" +"內容的新串列。" + +#: ../../c-api/list.rst:100 +msgid "" +"Bounds checking is performed as an assertion if Python is built " +"in :ref:`debug mode ` or :option:`with assertions <--with-" +"assertions>`." +msgstr "" +"如果 Python 是以\\ :ref:`偵錯模式 `\\ 或 " +":option:`with assertions <--with-assertions>` 建置，則會進行作為" +"斷言（asserting）的邊界檢查。" + +#: ../../c-api/list.rst:106 +msgid "" +"This macro \"steals\" a reference to *item*, and, " +"unlike :c:func:`PyList_SetItem`, does *not* discard a reference to any item " +"that is being replaced; any reference in *list* at position *i* will be " +"leaked." +msgstr "" +"該巨集「竊取」對 *item* 的參照，並且與 :c:func:`PyList_SetItem` 不同的是，它" +"\\ *不會*\\ 丟棄對任意被替換項目的參照；*list* 中位置 *i* 的任何參照都將被洩" +"漏 (leak)。" + +#: ../../c-api/list.rst:114 +msgid "" +"Insert the item *item* into list *list* in front of index *index*. Return " +"``0`` if successful; return ``-1`` and set an exception if unsuccessful. " +"Analogous to ``list.insert(index, item)``." +msgstr "" +"將項目 *item* 插入串列 *list* 中索引 *index* 的位置之前。如果成功則回傳 " +"``0``；如果失敗則回傳 ``-1`` 並設定例外。類似於 ``list.insert(index, " +"item)``。" + +#: ../../c-api/list.rst:121 +msgid "" +"Append the object *item* at the end of list *list*. Return ``0`` if " +"successful; return ``-1`` and set an exception if unsuccessful. Analogous " +"to ``list.append(item)``." +msgstr "" +"將物件 *item* 附加到串列 *list* 的最後面。如果成功則回傳 ``0``；如果不成功，" +"則回傳 ``-1`` 並設定例外。類似於 ``list.append(item)``。" + +#: ../../c-api/list.rst:128 +msgid "" +"Return a list of the objects in *list* containing the objects *between* " +"*low* and *high*. Return ``NULL`` and set an exception if unsuccessful. " +"Analogous to ``list[low:high]``. Indexing from the end of the list is not " +"supported." +msgstr "" +"回傳 *list* 中的物件串列，其中包含 *low* 和 *high* *之間*\\ 的物件。如果沒有" +"成功則回傳 ``NULL`` 並設定例外。類似於 ``list[low:high]``。不支援從串列尾末開" +"始索引。" + +#: ../../c-api/list.rst:135 +msgid "" +"Set the slice of *list* between *low* and *high* to the contents of " +"*itemlist*. Analogous to ``list[low:high] = itemlist``. The *itemlist* may " +"be ``NULL``, indicating the assignment of an empty list (slice deletion). " +"Return ``0`` on success, ``-1`` on failure. Indexing from the end of the " +"list is not supported." +msgstr "" +"將 *low* 和 *high* 之間的 *list* 切片設定為 *itemlist* 的內容。類似於 " +"``list[low:high] = itemlist``。*itemlist* 可能為 ``NULL``，表示分配一個空串列" +"（切片刪除）。成功時回傳 ``0``，失敗時則回傳 ``-1``。不支援從串列尾末開始索" +"引。" + +#: ../../c-api/list.rst:144 +msgid "" +"Extend *list* with the contents of *iterable*. This is the same as " +"``PyList_SetSlice(list, PY_SSIZE_T_MAX, PY_SSIZE_T_MAX, iterable)`` and " +"analogous to ``list.extend(iterable)`` or ``list += iterable``." +msgstr "" +"以 *iterable* 中的內容擴展 *list*。這與 ``PyList_SetSlice(list, " +"PY_SSIZE_T_MAX, PY_SSIZE_T_MAX, iterable)`` 相同，類似於 " +"``list.extend(iterable)`` 或 ``list += iterable``。" + +#: ../../c-api/list.rst:148 +msgid "" +"Raise an exception and return ``-1`` if *list* is not a :class:`list` " +"object. Return 0 on success." +msgstr "" +"引發一個例外並回傳 ``-1`` 如果 *list* 不是一個 :class:`list` 物件。如果成功回" +"傳 0。" + +#: ../../c-api/list.rst:156 +msgid "" +"Remove all items from *list*. This is the same as ``PyList_SetSlice(list, " +"0, PY_SSIZE_T_MAX, NULL)`` and analogous to ``list.clear()`` or ``del " +"list[:]``." +msgstr "移除 *list* 中的所有項目。這與 ``PyList_SetSlice(list, 0, PY_SSIZE_T_MAX, " +"NULL)`` 相同，類似於 ``list.clear()`` 或 ``del list[:]``。" + +#: ../../c-api/list.rst:160 +msgid "" +"Raise an exception and return ``-1`` if *list* is not a :class:`list` " +"object. Return 0 on success." +msgstr "引發一個例外並回傳 ``-1`` 如果 *list* 不是一個 :class:`list` 物件。" +"如果成功回傳 0。" + +#: ../../c-api/list.rst:168 +msgid "" +"Sort the items of *list* in place. Return ``0`` on success, ``-1`` on " +"failure. This is equivalent to ``list.sort()``." +msgstr "" +"對 *list* 的項目進行原地 (in place) 排序。成功時回傳 ``0``，失敗時回傳 " +"``-1``。這相當於 ``list.sort()``。" + +#: ../../c-api/list.rst:174 +msgid "" +"Reverse the items of *list* in place. Return ``0`` on success, ``-1`` on " +"failure. This is the equivalent of ``list.reverse()``." +msgstr "" +"原地反轉 *list* 的項目。成功時回傳 ``0``，失敗時回傳 ``-1``。這相當於 " +"``list.reverse()``。" + +#: ../../c-api/list.rst:182 +msgid "" +"Return a new tuple object containing the contents of *list*; equivalent to " +"``tuple(list)``." +msgstr "" +"回傳一個新的 tuple（元組）物件，其中包含 *list* 的內容；相當於 " +"``tuple(list)``。" + +#: ../../c-api/list.rst:8 +msgid "object" +msgstr "object（物件）" + +#: ../../c-api/list.rst:8 +msgid "list" +msgstr "list（串列）" + +#: ../../c-api/list.rst:51 ../../c-api/list.rst:180 +msgid "built-in function" +msgstr "built-in function（內建函式）" + +#: ../../c-api/list.rst:51 +msgid "len" +msgstr "len" + +#: ../../c-api/list.rst:180 +msgid "tuple" +msgstr "tuple（元組）" diff --git a/c-api/long.po b/c-api/long.po index d5b97df804..6b358e5809 100644 --- a/c-api/long.po +++ b/c-api/long.po @@ -1,1034 +1,1034 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Leon H., 2017 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-07 00:14+0000\n" -"PO-Revision-Date: 2018-05-23 14:06+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" - -#: ../../c-api/long.rst:6 -msgid "Integer Objects" -msgstr "整數物件" - -#: ../../c-api/long.rst:11 -msgid "" -"All integers are implemented as \"long\" integer objects of arbitrary size." -msgstr "" - -#: ../../c-api/long.rst:13 -msgid "" -"On error, most ``PyLong_As*`` APIs return ``(return type)-1`` which cannot " -"be distinguished from a number. Use :c:func:`PyErr_Occurred` to " -"disambiguate." -msgstr "" - -#: ../../c-api/long.rst:18 -msgid "This subtype of :c:type:`PyObject` represents a Python integer object." -msgstr "" - -#: ../../c-api/long.rst:23 -msgid "" -"This instance of :c:type:`PyTypeObject` represents the Python integer type. " -"This is the same object as :class:`int` in the Python layer." -msgstr "" - -#: ../../c-api/long.rst:29 -msgid "" -"Return true if its argument is a :c:type:`PyLongObject` or a subtype of :c:" -"type:`PyLongObject`. This function always succeeds." -msgstr "" - -#: ../../c-api/long.rst:35 -msgid "" -"Return true if its argument is a :c:type:`PyLongObject`, but not a subtype " -"of :c:type:`PyLongObject`. This function always succeeds." -msgstr "" - -#: ../../c-api/long.rst:41 -msgid "" -"Return a new :c:type:`PyLongObject` object from *v*, or ``NULL`` on failure." -msgstr "" - -#: ../../c-api/long.rst:45 -msgid "" -"CPython keeps an array of integer objects for all integers between ``-5`` " -"and ``256``. When you create an int in that range you actually just get " -"back a reference to the existing object." -msgstr "" - -#: ../../c-api/long.rst:52 -msgid "" -"Return a new :c:type:`PyLongObject` object from a C :c:expr:`unsigned long`, " -"or ``NULL`` on failure." -msgstr "" - -#: ../../c-api/long.rst:58 -msgid "" -"Return a new :c:type:`PyLongObject` object from a C :c:type:`Py_ssize_t`, or " -"``NULL`` on failure." -msgstr "" - -#: ../../c-api/long.rst:64 -msgid "" -"Return a new :c:type:`PyLongObject` object from a C :c:type:`size_t`, or " -"``NULL`` on failure." -msgstr "" - -#: ../../c-api/long.rst:70 -msgid "" -"Return a new :c:type:`PyLongObject` object from a C :c:expr:`long long`, or " -"``NULL`` on failure." -msgstr "" - -#: ../../c-api/long.rst:77 -msgid "" -"Return a new :c:type:`PyLongObject` object from a signed C :c:expr:`int32_t` " -"or :c:expr:`int64_t`, or ``NULL`` with an exception set on failure." -msgstr "" - -#: ../../c-api/long.rst:86 -msgid "" -"Return a new :c:type:`PyLongObject` object from a C :c:expr:`unsigned long " -"long`, or ``NULL`` on failure." -msgstr "" - -#: ../../c-api/long.rst:93 -msgid "" -"Return a new :c:type:`PyLongObject` object from an unsigned C :c:expr:" -"`uint32_t` or :c:expr:`uint64_t`, or ``NULL`` with an exception set on " -"failure." -msgstr "" - -#: ../../c-api/long.rst:102 -msgid "" -"Return a new :c:type:`PyLongObject` object from the integer part of *v*, or " -"``NULL`` on failure." -msgstr "" - -#: ../../c-api/long.rst:108 -msgid "" -"Return a new :c:type:`PyLongObject` based on the string value in *str*, " -"which is interpreted according to the radix in *base*, or ``NULL`` on " -"failure. If *pend* is non-``NULL``, *\\*pend* will point to the end of " -"*str* on success or to the first character that could not be processed on " -"error. If *base* is ``0``, *str* is interpreted using the :ref:`integers` " -"definition; in this case, leading zeros in a non-zero decimal number raises " -"a :exc:`ValueError`. If *base* is not ``0``, it must be between ``2`` and " -"``36``, inclusive. Leading and trailing whitespace and single underscores " -"after a base specifier and between digits are ignored. If there are no " -"digits or *str* is not NULL-terminated following the digits and trailing " -"whitespace, :exc:`ValueError` will be raised." -msgstr "" - -#: ../../c-api/long.rst:119 -msgid "" -":c:func:`PyLong_AsNativeBytes()` and :c:func:`PyLong_FromNativeBytes()` " -"functions can be used to convert a :c:type:`PyLongObject` to/from an array " -"of bytes in base ``256``." -msgstr "" - -#: ../../c-api/long.rst:126 -msgid "" -"Convert a sequence of Unicode digits in the string *u* to a Python integer " -"value." -msgstr "" - -#: ../../c-api/long.rst:134 -msgid "" -"Create a Python integer from the pointer *p*. The pointer value can be " -"retrieved from the resulting value using :c:func:`PyLong_AsVoidPtr`." -msgstr "" - -#: ../../c-api/long.rst:140 -msgid "" -"Create a Python integer from the value contained in the first *n_bytes* of " -"*buffer*, interpreted as a two's-complement signed number." -msgstr "" - -#: ../../c-api/long.rst:143 -msgid "" -"*flags* are as for :c:func:`PyLong_AsNativeBytes`. Passing ``-1`` will " -"select the native endian that CPython was compiled with and assume that the " -"most-significant bit is a sign bit. Passing " -"``Py_ASNATIVEBYTES_UNSIGNED_BUFFER`` will produce the same result as " -"calling :c:func:`PyLong_FromUnsignedNativeBytes`. Other flags are ignored." -msgstr "" - -#: ../../c-api/long.rst:154 -msgid "" -"Create a Python integer from the value contained in the first *n_bytes* of " -"*buffer*, interpreted as an unsigned number." -msgstr "" - -#: ../../c-api/long.rst:157 -msgid "" -"*flags* are as for :c:func:`PyLong_AsNativeBytes`. Passing ``-1`` will " -"select the native endian that CPython was compiled with and assume that the " -"most-significant bit is not a sign bit. Flags other than endian are ignored." -msgstr "" - -#: ../../c-api/long.rst:166 -msgid "Macro for creating a Python integer from a process identifier." -msgstr "" - -#: ../../c-api/long.rst:168 -msgid "" -"This can be defined as an alias to :c:func:`PyLong_FromLong` or :c:func:" -"`PyLong_FromLongLong`, depending on the size of the system's PID type." -msgstr "" - -#: ../../c-api/long.rst:181 ../../c-api/long.rst:217 -msgid "" -"Return a C :c:expr:`long` representation of *obj*. If *obj* is not an " -"instance of :c:type:`PyLongObject`, first call its :meth:`~object.__index__` " -"method (if present) to convert it to a :c:type:`PyLongObject`." -msgstr "" - -#: ../../c-api/long.rst:185 -msgid "" -"Raise :exc:`OverflowError` if the value of *obj* is out of range for a :c:" -"expr:`long`." -msgstr "" - -#: ../../c-api/long.rst:188 ../../c-api/long.rst:226 ../../c-api/long.rst:247 -#: ../../c-api/long.rst:267 ../../c-api/long.rst:290 -msgid "Returns ``-1`` on error. Use :c:func:`PyErr_Occurred` to disambiguate." -msgstr "" - -#: ../../c-api/long.rst:190 ../../c-api/long.rst:228 ../../c-api/long.rst:249 -#: ../../c-api/long.rst:271 ../../c-api/long.rst:355 ../../c-api/long.rst:375 -msgid "Use :meth:`~object.__index__` if available." -msgstr "" - -#: ../../c-api/long.rst:193 ../../c-api/long.rst:231 ../../c-api/long.rst:252 -#: ../../c-api/long.rst:274 ../../c-api/long.rst:358 ../../c-api/long.rst:378 -msgid "This function will no longer use :meth:`~object.__int__`." -msgstr "" - -#: ../../c-api/long.rst:200 -msgid "" -"A :term:`soft deprecated` alias. Exactly equivalent to the preferred " -"``PyLong_AsLong``. In particular, it can fail with :exc:`OverflowError` or " -"another exception." -msgstr "" - -#: ../../c-api/long.rst:204 -msgid "The function is soft deprecated." -msgstr "" - -#: ../../c-api/long.rst:209 -msgid "" -"Similar to :c:func:`PyLong_AsLong`, but store the result in a C :c:expr:" -"`int` instead of a C :c:expr:`long`." -msgstr "" - -#: ../../c-api/long.rst:221 -msgid "" -"If the value of *obj* is greater than :c:macro:`LONG_MAX` or less than :c:" -"macro:`LONG_MIN`, set *\\*overflow* to ``1`` or ``-1``, respectively, and " -"return ``-1``; otherwise, set *\\*overflow* to ``0``. If any other " -"exception occurs set *\\*overflow* to ``0`` and return ``-1`` as usual." -msgstr "" - -#: ../../c-api/long.rst:240 ../../c-api/long.rst:258 -msgid "" -"Return a C :c:expr:`long long` representation of *obj*. If *obj* is not an " -"instance of :c:type:`PyLongObject`, first call its :meth:`~object.__index__` " -"method (if present) to convert it to a :c:type:`PyLongObject`." -msgstr "" - -#: ../../c-api/long.rst:244 -msgid "" -"Raise :exc:`OverflowError` if the value of *obj* is out of range for a :c:" -"expr:`long long`." -msgstr "" - -#: ../../c-api/long.rst:262 -msgid "" -"If the value of *obj* is greater than :c:macro:`LLONG_MAX` or less than :c:" -"macro:`LLONG_MIN`, set *\\*overflow* to ``1`` or ``-1``, respectively, and " -"return ``-1``; otherwise, set *\\*overflow* to ``0``. If any other " -"exception occurs set *\\*overflow* to ``0`` and return ``-1`` as usual." -msgstr "" - -#: ../../c-api/long.rst:284 -msgid "" -"Return a C :c:type:`Py_ssize_t` representation of *pylong*. *pylong* must " -"be an instance of :c:type:`PyLongObject`." -msgstr "" - -#: ../../c-api/long.rst:287 -msgid "" -"Raise :exc:`OverflowError` if the value of *pylong* is out of range for a :c:" -"type:`Py_ssize_t`." -msgstr "" - -#: ../../c-api/long.rst:299 -msgid "" -"Return a C :c:expr:`unsigned long` representation of *pylong*. *pylong* " -"must be an instance of :c:type:`PyLongObject`." -msgstr "" - -#: ../../c-api/long.rst:302 -msgid "" -"Raise :exc:`OverflowError` if the value of *pylong* is out of range for a :c:" -"expr:`unsigned long`." -msgstr "" - -#: ../../c-api/long.rst:305 -msgid "" -"Returns ``(unsigned long)-1`` on error. Use :c:func:`PyErr_Occurred` to " -"disambiguate." -msgstr "" - -#: ../../c-api/long.rst:315 -msgid "" -"Return a C :c:type:`size_t` representation of *pylong*. *pylong* must be an " -"instance of :c:type:`PyLongObject`." -msgstr "" - -#: ../../c-api/long.rst:318 -msgid "" -"Raise :exc:`OverflowError` if the value of *pylong* is out of range for a :c:" -"type:`size_t`." -msgstr "" - -#: ../../c-api/long.rst:321 -msgid "" -"Returns ``(size_t)-1`` on error. Use :c:func:`PyErr_Occurred` to " -"disambiguate." -msgstr "" - -#: ../../c-api/long.rst:330 -msgid "" -"Return a C :c:expr:`unsigned long long` representation of *pylong*. " -"*pylong* must be an instance of :c:type:`PyLongObject`." -msgstr "" - -#: ../../c-api/long.rst:333 -msgid "" -"Raise :exc:`OverflowError` if the value of *pylong* is out of range for an :" -"c:expr:`unsigned long long`." -msgstr "" - -#: ../../c-api/long.rst:336 -msgid "" -"Returns ``(unsigned long long)-1`` on error. Use :c:func:`PyErr_Occurred` to " -"disambiguate." -msgstr "" - -#: ../../c-api/long.rst:339 -msgid "" -"A negative *pylong* now raises :exc:`OverflowError`, not :exc:`TypeError`." -msgstr "" - -#: ../../c-api/long.rst:345 -msgid "" -"Return a C :c:expr:`unsigned long` representation of *obj*. If *obj* is not " -"an instance of :c:type:`PyLongObject`, first call its :meth:`~object." -"__index__` method (if present) to convert it to a :c:type:`PyLongObject`." -msgstr "" - -#: ../../c-api/long.rst:349 -msgid "" -"If the value of *obj* is out of range for an :c:expr:`unsigned long`, return " -"the reduction of that value modulo ``ULONG_MAX + 1``." -msgstr "" - -#: ../../c-api/long.rst:352 -msgid "" -"Returns ``(unsigned long)-1`` on error. Use :c:func:`PyErr_Occurred` to " -"disambiguate." -msgstr "" - -#: ../../c-api/long.rst:364 -msgid "" -"Return a C :c:expr:`unsigned long long` representation of *obj*. If *obj* " -"is not an instance of :c:type:`PyLongObject`, first call its :meth:`~object." -"__index__` method (if present) to convert it to a :c:type:`PyLongObject`." -msgstr "" - -#: ../../c-api/long.rst:369 -msgid "" -"If the value of *obj* is out of range for an :c:expr:`unsigned long long`, " -"return the reduction of that value modulo ``ULLONG_MAX + 1``." -msgstr "" - -#: ../../c-api/long.rst:372 -msgid "" -"Returns ``(unsigned long long)-1`` on error. Use :c:func:`PyErr_Occurred` " -"to disambiguate." -msgstr "" - -#: ../../c-api/long.rst:385 -msgid "" -"Set *\\*value* to a signed C :c:expr:`int32_t` or :c:expr:`int64_t` " -"representation of *obj*." -msgstr "" - -#: ../../c-api/long.rst:388 ../../c-api/long.rst:408 -msgid "" -"If *obj* is not an instance of :c:type:`PyLongObject`, first call its :meth:" -"`~object.__index__` method (if present) to convert it to a :c:type:" -"`PyLongObject`." -msgstr "" - -#: ../../c-api/long.rst:392 ../../c-api/long.rst:413 -msgid "If the *obj* value is out of range, raise an :exc:`OverflowError`." -msgstr "" - -#: ../../c-api/long.rst:394 ../../c-api/long.rst:415 -msgid "" -"Set *\\*value* and return ``0`` on success. Set an exception and return " -"``-1`` on error." -msgstr "" - -#: ../../c-api/long.rst:397 ../../c-api/long.rst:418 -msgid "*value* must not be ``NULL``." -msgstr "" - -#: ../../c-api/long.rst:405 -msgid "" -"Set *\\*value* to an unsigned C :c:expr:`uint32_t` or :c:expr:`uint64_t` " -"representation of *obj*." -msgstr "" - -#: ../../c-api/long.rst:412 -msgid "If *obj* is negative, raise a :exc:`ValueError`." -msgstr "" - -#: ../../c-api/long.rst:425 -msgid "" -"Return a C :c:expr:`double` representation of *pylong*. *pylong* must be an " -"instance of :c:type:`PyLongObject`." -msgstr "" - -#: ../../c-api/long.rst:428 -msgid "" -"Raise :exc:`OverflowError` if the value of *pylong* is out of range for a :c:" -"expr:`double`." -msgstr "" - -#: ../../c-api/long.rst:431 -msgid "" -"Returns ``-1.0`` on error. Use :c:func:`PyErr_Occurred` to disambiguate." -msgstr "" - -#: ../../c-api/long.rst:436 -msgid "" -"Convert a Python integer *pylong* to a C :c:expr:`void` pointer. If *pylong* " -"cannot be converted, an :exc:`OverflowError` will be raised. This is only " -"assured to produce a usable :c:expr:`void` pointer for values created with :" -"c:func:`PyLong_FromVoidPtr`." -msgstr "" - -#: ../../c-api/long.rst:441 -msgid "" -"Returns ``NULL`` on error. Use :c:func:`PyErr_Occurred` to disambiguate." -msgstr "" - -#: ../../c-api/long.rst:446 -msgid "" -"Copy the Python integer value *pylong* to a native *buffer* of size " -"*n_bytes*. The *flags* can be set to ``-1`` to behave similarly to a C cast, " -"or to values documented below to control the behavior." -msgstr "" - -#: ../../c-api/long.rst:450 -msgid "" -"Returns ``-1`` with an exception raised on error. This may happen if " -"*pylong* cannot be interpreted as an integer, or if *pylong* was negative " -"and the ``Py_ASNATIVEBYTES_REJECT_NEGATIVE`` flag was set." -msgstr "" - -#: ../../c-api/long.rst:454 -msgid "" -"Otherwise, returns the number of bytes required to store the value. If this " -"is equal to or less than *n_bytes*, the entire value was copied. All " -"*n_bytes* of the buffer are written: large buffers are padded with zeroes." -msgstr "" - -#: ../../c-api/long.rst:459 -msgid "" -"If the returned value is greater than *n_bytes*, the value was truncated: as " -"many of the lowest bits of the value as could fit are written, and the " -"higher bits are ignored. This matches the typical behavior of a C-style " -"downcast." -msgstr "" - -#: ../../c-api/long.rst:466 -msgid "" -"Overflow is not considered an error. If the returned value is larger than " -"*n_bytes*, most significant bits were discarded." -msgstr "" - -#: ../../c-api/long.rst:469 -msgid "``0`` will never be returned." -msgstr "``0`` 將永不被回傳。" - -#: ../../c-api/long.rst:471 -msgid "Values are always copied as two's-complement." -msgstr "" - -#: ../../c-api/long.rst:473 -msgid "Usage example::" -msgstr "使用範例： ::" - -#: ../../c-api/long.rst:475 -msgid "" -"int32_t value;\n" -"Py_ssize_t bytes = PyLong_AsNativeBytes(pylong, &value, sizeof(value), -1);\n" -"if (bytes < 0) {\n" -" // Failed. A Python exception was set with the reason.\n" -" return NULL;\n" -"}\n" -"else if (bytes <= (Py_ssize_t)sizeof(value)) {\n" -" // Success!\n" -"}\n" -"else {\n" -" // Overflow occurred, but 'value' contains the truncated\n" -" // lowest bits of pylong.\n" -"}" -msgstr "" - -#: ../../c-api/long.rst:489 -msgid "" -"Passing zero to *n_bytes* will return the size of a buffer that would be " -"large enough to hold the value. This may be larger than technically " -"necessary, but not unreasonably so. If *n_bytes=0*, *buffer* may be ``NULL``." -msgstr "" - -#: ../../c-api/long.rst:496 -msgid "" -"Passing *n_bytes=0* to this function is not an accurate way to determine the " -"bit length of the value." -msgstr "" - -#: ../../c-api/long.rst:499 -msgid "" -"To get at the entire Python value of an unknown size, the function can be " -"called twice: first to determine the buffer size, then to fill it::" -msgstr "" - -#: ../../c-api/long.rst:502 -msgid "" -"// Ask how much space we need.\n" -"Py_ssize_t expected = PyLong_AsNativeBytes(pylong, NULL, 0, -1);\n" -"if (expected < 0) {\n" -" // Failed. A Python exception was set with the reason.\n" -" return NULL;\n" -"}\n" -"assert(expected != 0); // Impossible per the API definition.\n" -"uint8_t *bignum = malloc(expected);\n" -"if (!bignum) {\n" -" PyErr_SetString(PyExc_MemoryError, \"bignum malloc failed.\");\n" -" return NULL;\n" -"}\n" -"// Safely get the entire value.\n" -"Py_ssize_t bytes = PyLong_AsNativeBytes(pylong, bignum, expected, -1);\n" -"if (bytes < 0) { // Exception has been set.\n" -" free(bignum);\n" -" return NULL;\n" -"}\n" -"else if (bytes > expected) { // This should not be possible.\n" -" PyErr_SetString(PyExc_RuntimeError,\n" -" \"Unexpected bignum truncation after a size check.\");\n" -" free(bignum);\n" -" return NULL;\n" -"}\n" -"// The expected success given the above pre-check.\n" -"// ... use bignum ...\n" -"free(bignum);" -msgstr "" - -#: ../../c-api/long.rst:530 -msgid "" -"*flags* is either ``-1`` (``Py_ASNATIVEBYTES_DEFAULTS``) to select defaults " -"that behave most like a C cast, or a combination of the other flags in the " -"table below. Note that ``-1`` cannot be combined with other flags." -msgstr "" - -#: ../../c-api/long.rst:535 -msgid "" -"Currently, ``-1`` corresponds to ``Py_ASNATIVEBYTES_NATIVE_ENDIAN | " -"Py_ASNATIVEBYTES_UNSIGNED_BUFFER``." -msgstr "" - -#: ../../c-api/long.rst:541 -msgid "Flag" -msgstr "旗標" - -#: ../../c-api/long.rst:541 -msgid "Value" -msgstr "數值" - -#: ../../c-api/long.rst:543 -msgid "``-1``" -msgstr "``-1``" - -#: ../../c-api/long.rst:544 -msgid "``0``" -msgstr "``0``" - -#: ../../c-api/long.rst:545 -msgid "``1``" -msgstr "``1``" - -#: ../../c-api/long.rst:546 -msgid "``3``" -msgstr "``3``" - -#: ../../c-api/long.rst:547 -msgid "``4``" -msgstr "``4``" - -#: ../../c-api/long.rst:548 -msgid "``8``" -msgstr "``8``" - -#: ../../c-api/long.rst:549 -msgid "``16``" -msgstr "``16``" - -#: ../../c-api/long.rst:552 -msgid "" -"Specifying ``Py_ASNATIVEBYTES_NATIVE_ENDIAN`` will override any other endian " -"flags. Passing ``2`` is reserved." -msgstr "" - -#: ../../c-api/long.rst:555 -msgid "" -"By default, sufficient buffer will be requested to include a sign bit. For " -"example, when converting 128 with *n_bytes=1*, the function will return 2 " -"(or more) in order to store a zero sign bit." -msgstr "" - -#: ../../c-api/long.rst:559 -msgid "" -"If ``Py_ASNATIVEBYTES_UNSIGNED_BUFFER`` is specified, a zero sign bit will " -"be omitted from size calculations. This allows, for example, 128 to fit in a " -"single-byte buffer. If the destination buffer is later treated as signed, a " -"positive input value may become negative. Note that the flag does not affect " -"handling of negative values: for those, space for a sign bit is always " -"requested." -msgstr "" - -#: ../../c-api/long.rst:566 -msgid "" -"Specifying ``Py_ASNATIVEBYTES_REJECT_NEGATIVE`` causes an exception to be " -"set if *pylong* is negative. Without this flag, negative values will be " -"copied provided there is enough space for at least one sign bit, regardless " -"of whether ``Py_ASNATIVEBYTES_UNSIGNED_BUFFER`` was specified." -msgstr "" - -#: ../../c-api/long.rst:571 -msgid "" -"If ``Py_ASNATIVEBYTES_ALLOW_INDEX`` is specified and a non-integer value is " -"passed, its :meth:`~object.__index__` method will be called first. This may " -"result in Python code executing and other threads being allowed to run, " -"which could cause changes to other objects or values in use. When *flags* is " -"``-1``, this option is not set, and non-integer values will raise :exc:" -"`TypeError`." -msgstr "" - -#: ../../c-api/long.rst:580 -msgid "" -"With the default *flags* (``-1``, or *UNSIGNED_BUFFER* without " -"*REJECT_NEGATIVE*), multiple Python integers can map to a single value " -"without overflow. For example, both ``255`` and ``-1`` fit a single-byte " -"buffer and set all its bits. This matches typical C cast behavior." -msgstr "" - -#: ../../c-api/long.rst:591 -msgid "Macro for converting a Python integer into a process identifier." -msgstr "" - -#: ../../c-api/long.rst:593 -msgid "" -"This can be defined as an alias to :c:func:`PyLong_AsLong`, :c:func:" -"`PyLong_FromLongLong`, or :c:func:`PyLong_AsInt`, depending on the size of " -"the system's PID type." -msgstr "" - -#: ../../c-api/long.rst:602 -msgid "Get the sign of the integer object *obj*." -msgstr "" - -#: ../../c-api/long.rst:604 -msgid "" -"On success, set *\\*sign* to the integer sign (0, -1 or +1 for zero, " -"negative or positive integer, respectively) and return 0." -msgstr "" - -#: ../../c-api/long.rst:607 -msgid "" -"On failure, return -1 with an exception set. This function always succeeds " -"if *obj* is a :c:type:`PyLongObject` or its subtype." -msgstr "" - -#: ../../c-api/long.rst:615 -msgid "Check if the integer object *obj* is positive (``obj > 0``)." -msgstr "" - -#: ../../c-api/long.rst:617 -msgid "" -"If *obj* is an instance of :c:type:`PyLongObject` or its subtype, return " -"``1`` when it's positive and ``0`` otherwise. Else set an exception and " -"return ``-1``." -msgstr "" - -#: ../../c-api/long.rst:626 -msgid "Check if the integer object *obj* is negative (``obj < 0``)." -msgstr "" - -#: ../../c-api/long.rst:628 -msgid "" -"If *obj* is an instance of :c:type:`PyLongObject` or its subtype, return " -"``1`` when it's negative and ``0`` otherwise. Else set an exception and " -"return ``-1``." -msgstr "" - -#: ../../c-api/long.rst:637 -msgid "Check if the integer object *obj* is zero." -msgstr "" - -#: ../../c-api/long.rst:639 -msgid "" -"If *obj* is an instance of :c:type:`PyLongObject` or its subtype, return " -"``1`` when it's zero and ``0`` otherwise. Else set an exception and return " -"``-1``." -msgstr "" - -#: ../../c-api/long.rst:648 -msgid "" -"On success, return a read only :term:`named tuple`, that holds information " -"about Python's internal representation of integers. See :data:`sys.int_info` " -"for description of individual fields." -msgstr "" - -#: ../../c-api/long.rst:652 -msgid "On failure, return ``NULL`` with an exception set." -msgstr "在失敗時，會回傳 ``NULL`` 並設定例外。" - -#: ../../c-api/long.rst:659 -msgid "Return 1 if *op* is compact, 0 otherwise." -msgstr "" - -#: ../../c-api/long.rst:661 -msgid "" -"This function makes it possible for performance-critical code to implement a " -"“fast path” for small integers. For compact values use :c:func:" -"`PyUnstable_Long_CompactValue`; for others fall back to a :c:func:" -"`PyLong_As* ` function or :c:func:`PyLong_AsNativeBytes`." -msgstr "" - -#: ../../c-api/long.rst:667 -msgid "The speedup is expected to be negligible for most users." -msgstr "" - -#: ../../c-api/long.rst:669 -msgid "" -"Exactly what values are considered compact is an implementation detail and " -"is subject to change." -msgstr "" - -#: ../../c-api/long.rst:677 -msgid "" -"If *op* is compact, as determined by :c:func:`PyUnstable_Long_IsCompact`, " -"return its value." -msgstr "" - -#: ../../c-api/long.rst:680 -msgid "Otherwise, the return value is undefined." -msgstr "" - -#: ../../c-api/long.rst:686 -msgid "Export API" -msgstr "" - -#: ../../c-api/long.rst:692 -msgid "" -"Layout of an array of \"digits\" (\"limbs\" in the GMP terminology), used to " -"represent absolute value for arbitrary precision integers." -msgstr "" - -#: ../../c-api/long.rst:695 -msgid "" -"Use :c:func:`PyLong_GetNativeLayout` to get the native layout of Python :" -"class:`int` objects, used internally for integers with \"big enough\" " -"absolute value." -msgstr "" - -#: ../../c-api/long.rst:699 -msgid "" -"See also :data:`sys.int_info` which exposes similar information in Python." -msgstr "" - -#: ../../c-api/long.rst:703 -msgid "" -"Bits per digit. For example, a 15 bit digit means that bits 0-14 contain " -"meaningful information." -msgstr "" - -#: ../../c-api/long.rst:708 -msgid "" -"Digit size in bytes. For example, a 15 bit digit will require at least 2 " -"bytes." -msgstr "" - -#: ../../c-api/long.rst:713 -msgid "Digits order:" -msgstr "" - -#: ../../c-api/long.rst:715 -msgid "``1`` for most significant digit first" -msgstr "" - -#: ../../c-api/long.rst:716 -msgid "``-1`` for least significant digit first" -msgstr "" - -#: ../../c-api/long.rst:720 -msgid "Digit endianness:" -msgstr "" - -#: ../../c-api/long.rst:722 -msgid "``1`` for most significant byte first (big endian)" -msgstr "" - -#: ../../c-api/long.rst:723 -msgid "``-1`` for least significant byte first (little endian)" -msgstr "" - -#: ../../c-api/long.rst:728 -msgid "Get the native layout of Python :class:`int` objects." -msgstr "" - -#: ../../c-api/long.rst:730 -msgid "See the :c:struct:`PyLongLayout` structure." -msgstr "請見 :c:struct:`PyLongLayout` 結構。" - -#: ../../c-api/long.rst:732 -msgid "" -"The function must not be called before Python initialization nor after " -"Python finalization. The returned layout is valid until Python is finalized. " -"The layout is the same for all Python sub-interpreters in a process, and so " -"it can be cached." -msgstr "" - -#: ../../c-api/long.rst:740 -msgid "Export of a Python :class:`int` object." -msgstr "" - -#: ../../c-api/long.rst:742 -msgid "There are two cases:" -msgstr "" - -#: ../../c-api/long.rst:744 -msgid "" -"If :c:member:`digits` is ``NULL``, only use the :c:member:`value` member." -msgstr "" - -#: ../../c-api/long.rst:745 -msgid "" -"If :c:member:`digits` is not ``NULL``, use :c:member:`negative`, :c:member:" -"`ndigits` and :c:member:`digits` members." -msgstr "" - -#: ../../c-api/long.rst:750 -msgid "" -"The native integer value of the exported :class:`int` object. Only valid if :" -"c:member:`digits` is ``NULL``." -msgstr "" - -#: ../../c-api/long.rst:755 -msgid "" -"``1`` if the number is negative, ``0`` otherwise. Only valid if :c:member:" -"`digits` is not ``NULL``." -msgstr "" - -#: ../../c-api/long.rst:760 -msgid "" -"Number of digits in :c:member:`digits` array. Only valid if :c:member:" -"`digits` is not ``NULL``." -msgstr "" - -#: ../../c-api/long.rst:765 -msgid "Read-only array of unsigned digits. Can be ``NULL``." -msgstr "" - -#: ../../c-api/long.rst:770 -msgid "Export a Python :class:`int` object." -msgstr "" - -#: ../../c-api/long.rst:772 -msgid "" -"*export_long* must point to a :c:struct:`PyLongExport` structure allocated " -"by the caller. It must not be ``NULL``." -msgstr "" - -#: ../../c-api/long.rst:775 -msgid "" -"On success, fill in *\\*export_long* and return ``0``. On error, set an " -"exception and return ``-1``." -msgstr "" - -#: ../../c-api/long.rst:778 -msgid "" -":c:func:`PyLong_FreeExport` must be called when the export is no longer " -"needed." -msgstr "" - -#: ../../c-api/long.rst:782 -msgid "" -"This function always succeeds if *obj* is a Python :class:`int` object or a " -"subclass." -msgstr "" - -#: ../../c-api/long.rst:788 -msgid "Release the export *export_long* created by :c:func:`PyLong_Export`." -msgstr "" - -#: ../../c-api/long.rst:791 -msgid "" -"Calling :c:func:`PyLong_FreeExport` is optional if *export_long->digits* is " -"``NULL``." -msgstr "" - -#: ../../c-api/long.rst:796 -msgid "PyLongWriter API" -msgstr "" - -#: ../../c-api/long.rst:798 -msgid "The :c:type:`PyLongWriter` API can be used to import an integer." -msgstr "" - -#: ../../c-api/long.rst:804 -msgid "A Python :class:`int` writer instance." -msgstr "" - -#: ../../c-api/long.rst:806 -msgid "" -"The instance must be destroyed by :c:func:`PyLongWriter_Finish` or :c:func:" -"`PyLongWriter_Discard`." -msgstr "" - -#: ../../c-api/long.rst:812 -msgid "Create a :c:type:`PyLongWriter`." -msgstr "" - -#: ../../c-api/long.rst:814 -msgid "" -"On success, allocate *\\*digits* and return a writer. On error, set an " -"exception and return ``NULL``." -msgstr "" - -#: ../../c-api/long.rst:817 -msgid "*negative* is ``1`` if the number is negative, or ``0`` otherwise." -msgstr "" - -#: ../../c-api/long.rst:819 -msgid "" -"*ndigits* is the number of digits in the *digits* array. It must be greater " -"than 0." -msgstr "" - -#: ../../c-api/long.rst:822 -msgid "*digits* must not be NULL." -msgstr "" - -#: ../../c-api/long.rst:824 -msgid "" -"After a successful call to this function, the caller should fill in the " -"array of digits *digits* and then call :c:func:`PyLongWriter_Finish` to get " -"a Python :class:`int`. The layout of *digits* is described by :c:func:" -"`PyLong_GetNativeLayout`." -msgstr "" - -#: ../../c-api/long.rst:829 -msgid "" -"Digits must be in the range [``0``; ``(1 << bits_per_digit) - 1``] (where " -"the :c:struct:`~PyLongLayout.bits_per_digit` is the number of bits per " -"digit). Any unused most significant digits must be set to ``0``." -msgstr "" - -#: ../../c-api/long.rst:834 -msgid "" -"Alternately, call :c:func:`PyLongWriter_Discard` to destroy the writer " -"instance without creating an :class:`~int` object." -msgstr "" - -#: ../../c-api/long.rst:840 -msgid "" -"Finish a :c:type:`PyLongWriter` created by :c:func:`PyLongWriter_Create`." -msgstr "" - -#: ../../c-api/long.rst:842 -msgid "" -"On success, return a Python :class:`int` object. On error, set an exception " -"and return ``NULL``." -msgstr "" - -#: ../../c-api/long.rst:845 -msgid "" -"The function takes care of normalizing the digits and converts the object to " -"a compact integer if needed." -msgstr "" - -#: ../../c-api/long.rst:848 ../../c-api/long.rst:857 -msgid "The writer instance and the *digits* array are invalid after the call." -msgstr "" - -#: ../../c-api/long.rst:853 -msgid "" -"Discard a :c:type:`PyLongWriter` created by :c:func:`PyLongWriter_Create`." -msgstr "" - -#: ../../c-api/long.rst:855 -msgid "If *writer* is ``NULL``, no operation is performed." -msgstr "" - -#: ../../c-api/long.rst:8 -msgid "object" -msgstr "object（物件）" - -#: ../../c-api/long.rst:8 -msgid "long integer" -msgstr "long integer（長整數）" - -#: ../../c-api/long.rst:8 -msgid "integer" -msgstr "integer（整數）" - -#: ../../c-api/long.rst:177 -msgid "LONG_MAX (C macro)" -msgstr "LONG_MAX（C 巨集）" - -#: ../../c-api/long.rst:177 ../../c-api/long.rst:237 ../../c-api/long.rst:280 -#: ../../c-api/long.rst:295 ../../c-api/long.rst:311 ../../c-api/long.rst:327 -msgid "OverflowError (built-in exception)" -msgstr "OverflowError（內建例外）" - -#: ../../c-api/long.rst:280 -msgid "PY_SSIZE_T_MAX (C macro)" -msgstr "PY_SSIZE_T_MAX（C 巨集）" - -#: ../../c-api/long.rst:295 -msgid "ULONG_MAX (C macro)" -msgstr "ULONG_MAX（C 巨集）" - -#: ../../c-api/long.rst:311 -msgid "SIZE_MAX (C macro)" -msgstr "SIZE_MAX（C 巨集）" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Leon H., 2017 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-07 00:14+0000\n" +"PO-Revision-Date: 2018-05-23 14:06+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" + +#: ../../c-api/long.rst:6 +msgid "Integer Objects" +msgstr "整數物件" + +#: ../../c-api/long.rst:11 +msgid "" +"All integers are implemented as \"long\" integer objects of arbitrary size." +msgstr "" + +#: ../../c-api/long.rst:13 +msgid "" +"On error, most ``PyLong_As*`` APIs return ``(return type)-1`` which cannot " +"be distinguished from a number. Use :c:func:`PyErr_Occurred` to " +"disambiguate." +msgstr "" + +#: ../../c-api/long.rst:18 +msgid "This subtype of :c:type:`PyObject` represents a Python integer object." +msgstr "" + +#: ../../c-api/long.rst:23 +msgid "" +"This instance of :c:type:`PyTypeObject` represents the Python integer type. " +"This is the same object as :class:`int` in the Python layer." +msgstr "" + +#: ../../c-api/long.rst:29 +msgid "" +"Return true if its argument is a :c:type:`PyLongObject` or a subtype of :c:" +"type:`PyLongObject`. This function always succeeds." +msgstr "" + +#: ../../c-api/long.rst:35 +msgid "" +"Return true if its argument is a :c:type:`PyLongObject`, but not a subtype " +"of :c:type:`PyLongObject`. This function always succeeds." +msgstr "" + +#: ../../c-api/long.rst:41 +msgid "" +"Return a new :c:type:`PyLongObject` object from *v*, or ``NULL`` on failure." +msgstr "" + +#: ../../c-api/long.rst:45 +msgid "" +"CPython keeps an array of integer objects for all integers between ``-5`` " +"and ``256``. When you create an int in that range you actually just get " +"back a reference to the existing object." +msgstr "" + +#: ../../c-api/long.rst:52 +msgid "" +"Return a new :c:type:`PyLongObject` object from a C :c:expr:`unsigned long`, " +"or ``NULL`` on failure." +msgstr "" + +#: ../../c-api/long.rst:58 +msgid "" +"Return a new :c:type:`PyLongObject` object from a C :c:type:`Py_ssize_t`, or " +"``NULL`` on failure." +msgstr "" + +#: ../../c-api/long.rst:64 +msgid "" +"Return a new :c:type:`PyLongObject` object from a C :c:type:`size_t`, or " +"``NULL`` on failure." +msgstr "" + +#: ../../c-api/long.rst:70 +msgid "" +"Return a new :c:type:`PyLongObject` object from a C :c:expr:`long long`, or " +"``NULL`` on failure." +msgstr "" + +#: ../../c-api/long.rst:77 +msgid "" +"Return a new :c:type:`PyLongObject` object from a signed C :c:expr:`int32_t` " +"or :c:expr:`int64_t`, or ``NULL`` with an exception set on failure." +msgstr "" + +#: ../../c-api/long.rst:86 +msgid "" +"Return a new :c:type:`PyLongObject` object from a C :c:expr:`unsigned long " +"long`, or ``NULL`` on failure." +msgstr "" + +#: ../../c-api/long.rst:93 +msgid "" +"Return a new :c:type:`PyLongObject` object from an unsigned C :c:expr:" +"`uint32_t` or :c:expr:`uint64_t`, or ``NULL`` with an exception set on " +"failure." +msgstr "" + +#: ../../c-api/long.rst:102 +msgid "" +"Return a new :c:type:`PyLongObject` object from the integer part of *v*, or " +"``NULL`` on failure." +msgstr "" + +#: ../../c-api/long.rst:108 +msgid "" +"Return a new :c:type:`PyLongObject` based on the string value in *str*, " +"which is interpreted according to the radix in *base*, or ``NULL`` on " +"failure. If *pend* is non-``NULL``, *\\*pend* will point to the end of " +"*str* on success or to the first character that could not be processed on " +"error. If *base* is ``0``, *str* is interpreted using the :ref:`integers` " +"definition; in this case, leading zeros in a non-zero decimal number raises " +"a :exc:`ValueError`. If *base* is not ``0``, it must be between ``2`` and " +"``36``, inclusive. Leading and trailing whitespace and single underscores " +"after a base specifier and between digits are ignored. If there are no " +"digits or *str* is not NULL-terminated following the digits and trailing " +"whitespace, :exc:`ValueError` will be raised." +msgstr "" + +#: ../../c-api/long.rst:119 +msgid "" +":c:func:`PyLong_AsNativeBytes()` and :c:func:`PyLong_FromNativeBytes()` " +"functions can be used to convert a :c:type:`PyLongObject` to/from an array " +"of bytes in base ``256``." +msgstr "" + +#: ../../c-api/long.rst:126 +msgid "" +"Convert a sequence of Unicode digits in the string *u* to a Python integer " +"value." +msgstr "" + +#: ../../c-api/long.rst:134 +msgid "" +"Create a Python integer from the pointer *p*. The pointer value can be " +"retrieved from the resulting value using :c:func:`PyLong_AsVoidPtr`." +msgstr "" + +#: ../../c-api/long.rst:140 +msgid "" +"Create a Python integer from the value contained in the first *n_bytes* of " +"*buffer*, interpreted as a two's-complement signed number." +msgstr "" + +#: ../../c-api/long.rst:143 +msgid "" +"*flags* are as for :c:func:`PyLong_AsNativeBytes`. Passing ``-1`` will " +"select the native endian that CPython was compiled with and assume that the " +"most-significant bit is a sign bit. Passing " +"``Py_ASNATIVEBYTES_UNSIGNED_BUFFER`` will produce the same result as " +"calling :c:func:`PyLong_FromUnsignedNativeBytes`. Other flags are ignored." +msgstr "" + +#: ../../c-api/long.rst:154 +msgid "" +"Create a Python integer from the value contained in the first *n_bytes* of " +"*buffer*, interpreted as an unsigned number." +msgstr "" + +#: ../../c-api/long.rst:157 +msgid "" +"*flags* are as for :c:func:`PyLong_AsNativeBytes`. Passing ``-1`` will " +"select the native endian that CPython was compiled with and assume that the " +"most-significant bit is not a sign bit. Flags other than endian are ignored." +msgstr "" + +#: ../../c-api/long.rst:166 +msgid "Macro for creating a Python integer from a process identifier." +msgstr "" + +#: ../../c-api/long.rst:168 +msgid "" +"This can be defined as an alias to :c:func:`PyLong_FromLong` or :c:func:" +"`PyLong_FromLongLong`, depending on the size of the system's PID type." +msgstr "" + +#: ../../c-api/long.rst:181 ../../c-api/long.rst:217 +msgid "" +"Return a C :c:expr:`long` representation of *obj*. If *obj* is not an " +"instance of :c:type:`PyLongObject`, first call its :meth:`~object.__index__` " +"method (if present) to convert it to a :c:type:`PyLongObject`." +msgstr "" + +#: ../../c-api/long.rst:185 +msgid "" +"Raise :exc:`OverflowError` if the value of *obj* is out of range for a :c:" +"expr:`long`." +msgstr "" + +#: ../../c-api/long.rst:188 ../../c-api/long.rst:226 ../../c-api/long.rst:247 +#: ../../c-api/long.rst:267 ../../c-api/long.rst:290 +msgid "Returns ``-1`` on error. Use :c:func:`PyErr_Occurred` to disambiguate." +msgstr "" + +#: ../../c-api/long.rst:190 ../../c-api/long.rst:228 ../../c-api/long.rst:249 +#: ../../c-api/long.rst:271 ../../c-api/long.rst:355 ../../c-api/long.rst:375 +msgid "Use :meth:`~object.__index__` if available." +msgstr "" + +#: ../../c-api/long.rst:193 ../../c-api/long.rst:231 ../../c-api/long.rst:252 +#: ../../c-api/long.rst:274 ../../c-api/long.rst:358 ../../c-api/long.rst:378 +msgid "This function will no longer use :meth:`~object.__int__`." +msgstr "" + +#: ../../c-api/long.rst:200 +msgid "" +"A :term:`soft deprecated` alias. Exactly equivalent to the preferred " +"``PyLong_AsLong``. In particular, it can fail with :exc:`OverflowError` or " +"another exception." +msgstr "" + +#: ../../c-api/long.rst:204 +msgid "The function is soft deprecated." +msgstr "" + +#: ../../c-api/long.rst:209 +msgid "" +"Similar to :c:func:`PyLong_AsLong`, but store the result in a C :c:expr:" +"`int` instead of a C :c:expr:`long`." +msgstr "" + +#: ../../c-api/long.rst:221 +msgid "" +"If the value of *obj* is greater than :c:macro:`LONG_MAX` or less than :c:" +"macro:`LONG_MIN`, set *\\*overflow* to ``1`` or ``-1``, respectively, and " +"return ``-1``; otherwise, set *\\*overflow* to ``0``. If any other " +"exception occurs set *\\*overflow* to ``0`` and return ``-1`` as usual." +msgstr "" + +#: ../../c-api/long.rst:240 ../../c-api/long.rst:258 +msgid "" +"Return a C :c:expr:`long long` representation of *obj*. If *obj* is not an " +"instance of :c:type:`PyLongObject`, first call its :meth:`~object.__index__` " +"method (if present) to convert it to a :c:type:`PyLongObject`." +msgstr "" + +#: ../../c-api/long.rst:244 +msgid "" +"Raise :exc:`OverflowError` if the value of *obj* is out of range for a :c:" +"expr:`long long`." +msgstr "" + +#: ../../c-api/long.rst:262 +msgid "" +"If the value of *obj* is greater than :c:macro:`LLONG_MAX` or less than :c:" +"macro:`LLONG_MIN`, set *\\*overflow* to ``1`` or ``-1``, respectively, and " +"return ``-1``; otherwise, set *\\*overflow* to ``0``. If any other " +"exception occurs set *\\*overflow* to ``0`` and return ``-1`` as usual." +msgstr "" + +#: ../../c-api/long.rst:284 +msgid "" +"Return a C :c:type:`Py_ssize_t` representation of *pylong*. *pylong* must " +"be an instance of :c:type:`PyLongObject`." +msgstr "" + +#: ../../c-api/long.rst:287 +msgid "" +"Raise :exc:`OverflowError` if the value of *pylong* is out of range for a :c:" +"type:`Py_ssize_t`." +msgstr "" + +#: ../../c-api/long.rst:299 +msgid "" +"Return a C :c:expr:`unsigned long` representation of *pylong*. *pylong* " +"must be an instance of :c:type:`PyLongObject`." +msgstr "" + +#: ../../c-api/long.rst:302 +msgid "" +"Raise :exc:`OverflowError` if the value of *pylong* is out of range for a :c:" +"expr:`unsigned long`." +msgstr "" + +#: ../../c-api/long.rst:305 +msgid "" +"Returns ``(unsigned long)-1`` on error. Use :c:func:`PyErr_Occurred` to " +"disambiguate." +msgstr "" + +#: ../../c-api/long.rst:315 +msgid "" +"Return a C :c:type:`size_t` representation of *pylong*. *pylong* must be an " +"instance of :c:type:`PyLongObject`." +msgstr "" + +#: ../../c-api/long.rst:318 +msgid "" +"Raise :exc:`OverflowError` if the value of *pylong* is out of range for a :c:" +"type:`size_t`." +msgstr "" + +#: ../../c-api/long.rst:321 +msgid "" +"Returns ``(size_t)-1`` on error. Use :c:func:`PyErr_Occurred` to " +"disambiguate." +msgstr "" + +#: ../../c-api/long.rst:330 +msgid "" +"Return a C :c:expr:`unsigned long long` representation of *pylong*. " +"*pylong* must be an instance of :c:type:`PyLongObject`." +msgstr "" + +#: ../../c-api/long.rst:333 +msgid "" +"Raise :exc:`OverflowError` if the value of *pylong* is out of range for an :" +"c:expr:`unsigned long long`." +msgstr "" + +#: ../../c-api/long.rst:336 +msgid "" +"Returns ``(unsigned long long)-1`` on error. Use :c:func:`PyErr_Occurred` to " +"disambiguate." +msgstr "" + +#: ../../c-api/long.rst:339 +msgid "" +"A negative *pylong* now raises :exc:`OverflowError`, not :exc:`TypeError`." +msgstr "" + +#: ../../c-api/long.rst:345 +msgid "" +"Return a C :c:expr:`unsigned long` representation of *obj*. If *obj* is not " +"an instance of :c:type:`PyLongObject`, first call its :meth:`~object." +"__index__` method (if present) to convert it to a :c:type:`PyLongObject`." +msgstr "" + +#: ../../c-api/long.rst:349 +msgid "" +"If the value of *obj* is out of range for an :c:expr:`unsigned long`, return " +"the reduction of that value modulo ``ULONG_MAX + 1``." +msgstr "" + +#: ../../c-api/long.rst:352 +msgid "" +"Returns ``(unsigned long)-1`` on error. Use :c:func:`PyErr_Occurred` to " +"disambiguate." +msgstr "" + +#: ../../c-api/long.rst:364 +msgid "" +"Return a C :c:expr:`unsigned long long` representation of *obj*. If *obj* " +"is not an instance of :c:type:`PyLongObject`, first call its :meth:`~object." +"__index__` method (if present) to convert it to a :c:type:`PyLongObject`." +msgstr "" + +#: ../../c-api/long.rst:369 +msgid "" +"If the value of *obj* is out of range for an :c:expr:`unsigned long long`, " +"return the reduction of that value modulo ``ULLONG_MAX + 1``." +msgstr "" + +#: ../../c-api/long.rst:372 +msgid "" +"Returns ``(unsigned long long)-1`` on error. Use :c:func:`PyErr_Occurred` " +"to disambiguate." +msgstr "" + +#: ../../c-api/long.rst:385 +msgid "" +"Set *\\*value* to a signed C :c:expr:`int32_t` or :c:expr:`int64_t` " +"representation of *obj*." +msgstr "" + +#: ../../c-api/long.rst:388 ../../c-api/long.rst:408 +msgid "" +"If *obj* is not an instance of :c:type:`PyLongObject`, first call its :meth:" +"`~object.__index__` method (if present) to convert it to a :c:type:" +"`PyLongObject`." +msgstr "" + +#: ../../c-api/long.rst:392 ../../c-api/long.rst:413 +msgid "If the *obj* value is out of range, raise an :exc:`OverflowError`." +msgstr "" + +#: ../../c-api/long.rst:394 ../../c-api/long.rst:415 +msgid "" +"Set *\\*value* and return ``0`` on success. Set an exception and return " +"``-1`` on error." +msgstr "" + +#: ../../c-api/long.rst:397 ../../c-api/long.rst:418 +msgid "*value* must not be ``NULL``." +msgstr "" + +#: ../../c-api/long.rst:405 +msgid "" +"Set *\\*value* to an unsigned C :c:expr:`uint32_t` or :c:expr:`uint64_t` " +"representation of *obj*." +msgstr "" + +#: ../../c-api/long.rst:412 +msgid "If *obj* is negative, raise a :exc:`ValueError`." +msgstr "" + +#: ../../c-api/long.rst:425 +msgid "" +"Return a C :c:expr:`double` representation of *pylong*. *pylong* must be an " +"instance of :c:type:`PyLongObject`." +msgstr "" + +#: ../../c-api/long.rst:428 +msgid "" +"Raise :exc:`OverflowError` if the value of *pylong* is out of range for a :c:" +"expr:`double`." +msgstr "" + +#: ../../c-api/long.rst:431 +msgid "" +"Returns ``-1.0`` on error. Use :c:func:`PyErr_Occurred` to disambiguate." +msgstr "" + +#: ../../c-api/long.rst:436 +msgid "" +"Convert a Python integer *pylong* to a C :c:expr:`void` pointer. If *pylong* " +"cannot be converted, an :exc:`OverflowError` will be raised. This is only " +"assured to produce a usable :c:expr:`void` pointer for values created with :" +"c:func:`PyLong_FromVoidPtr`." +msgstr "" + +#: ../../c-api/long.rst:441 +msgid "" +"Returns ``NULL`` on error. Use :c:func:`PyErr_Occurred` to disambiguate." +msgstr "" + +#: ../../c-api/long.rst:446 +msgid "" +"Copy the Python integer value *pylong* to a native *buffer* of size " +"*n_bytes*. The *flags* can be set to ``-1`` to behave similarly to a C cast, " +"or to values documented below to control the behavior." +msgstr "" + +#: ../../c-api/long.rst:450 +msgid "" +"Returns ``-1`` with an exception raised on error. This may happen if " +"*pylong* cannot be interpreted as an integer, or if *pylong* was negative " +"and the ``Py_ASNATIVEBYTES_REJECT_NEGATIVE`` flag was set." +msgstr "" + +#: ../../c-api/long.rst:454 +msgid "" +"Otherwise, returns the number of bytes required to store the value. If this " +"is equal to or less than *n_bytes*, the entire value was copied. All " +"*n_bytes* of the buffer are written: large buffers are padded with zeroes." +msgstr "" + +#: ../../c-api/long.rst:459 +msgid "" +"If the returned value is greater than *n_bytes*, the value was truncated: as " +"many of the lowest bits of the value as could fit are written, and the " +"higher bits are ignored. This matches the typical behavior of a C-style " +"downcast." +msgstr "" + +#: ../../c-api/long.rst:466 +msgid "" +"Overflow is not considered an error. If the returned value is larger than " +"*n_bytes*, most significant bits were discarded." +msgstr "" + +#: ../../c-api/long.rst:469 +msgid "``0`` will never be returned." +msgstr "``0`` 將永不被回傳。" + +#: ../../c-api/long.rst:471 +msgid "Values are always copied as two's-complement." +msgstr "" + +#: ../../c-api/long.rst:473 +msgid "Usage example::" +msgstr "使用範例： ::" + +#: ../../c-api/long.rst:475 +msgid "" +"int32_t value;\n" +"Py_ssize_t bytes = PyLong_AsNativeBytes(pylong, &value, sizeof(value), -1);\n" +"if (bytes < 0) {\n" +" // Failed. A Python exception was set with the reason.\n" +" return NULL;\n" +"}\n" +"else if (bytes <= (Py_ssize_t)sizeof(value)) {\n" +" // Success!\n" +"}\n" +"else {\n" +" // Overflow occurred, but 'value' contains the truncated\n" +" // lowest bits of pylong.\n" +"}" +msgstr "" + +#: ../../c-api/long.rst:489 +msgid "" +"Passing zero to *n_bytes* will return the size of a buffer that would be " +"large enough to hold the value. This may be larger than technically " +"necessary, but not unreasonably so. If *n_bytes=0*, *buffer* may be ``NULL``." +msgstr "" + +#: ../../c-api/long.rst:496 +msgid "" +"Passing *n_bytes=0* to this function is not an accurate way to determine the " +"bit length of the value." +msgstr "" + +#: ../../c-api/long.rst:499 +msgid "" +"To get at the entire Python value of an unknown size, the function can be " +"called twice: first to determine the buffer size, then to fill it::" +msgstr "" + +#: ../../c-api/long.rst:502 +msgid "" +"// Ask how much space we need.\n" +"Py_ssize_t expected = PyLong_AsNativeBytes(pylong, NULL, 0, -1);\n" +"if (expected < 0) {\n" +" // Failed. A Python exception was set with the reason.\n" +" return NULL;\n" +"}\n" +"assert(expected != 0); // Impossible per the API definition.\n" +"uint8_t *bignum = malloc(expected);\n" +"if (!bignum) {\n" +" PyErr_SetString(PyExc_MemoryError, \"bignum malloc failed.\");\n" +" return NULL;\n" +"}\n" +"// Safely get the entire value.\n" +"Py_ssize_t bytes = PyLong_AsNativeBytes(pylong, bignum, expected, -1);\n" +"if (bytes < 0) { // Exception has been set.\n" +" free(bignum);\n" +" return NULL;\n" +"}\n" +"else if (bytes > expected) { // This should not be possible.\n" +" PyErr_SetString(PyExc_RuntimeError,\n" +" \"Unexpected bignum truncation after a size check.\");\n" +" free(bignum);\n" +" return NULL;\n" +"}\n" +"// The expected success given the above pre-check.\n" +"// ... use bignum ...\n" +"free(bignum);" +msgstr "" + +#: ../../c-api/long.rst:530 +msgid "" +"*flags* is either ``-1`` (``Py_ASNATIVEBYTES_DEFAULTS``) to select defaults " +"that behave most like a C cast, or a combination of the other flags in the " +"table below. Note that ``-1`` cannot be combined with other flags." +msgstr "" + +#: ../../c-api/long.rst:535 +msgid "" +"Currently, ``-1`` corresponds to ``Py_ASNATIVEBYTES_NATIVE_ENDIAN | " +"Py_ASNATIVEBYTES_UNSIGNED_BUFFER``." +msgstr "" + +#: ../../c-api/long.rst:541 +msgid "Flag" +msgstr "旗標" + +#: ../../c-api/long.rst:541 +msgid "Value" +msgstr "數值" + +#: ../../c-api/long.rst:543 +msgid "``-1``" +msgstr "``-1``" + +#: ../../c-api/long.rst:544 +msgid "``0``" +msgstr "``0``" + +#: ../../c-api/long.rst:545 +msgid "``1``" +msgstr "``1``" + +#: ../../c-api/long.rst:546 +msgid "``3``" +msgstr "``3``" + +#: ../../c-api/long.rst:547 +msgid "``4``" +msgstr "``4``" + +#: ../../c-api/long.rst:548 +msgid "``8``" +msgstr "``8``" + +#: ../../c-api/long.rst:549 +msgid "``16``" +msgstr "``16``" + +#: ../../c-api/long.rst:552 +msgid "" +"Specifying ``Py_ASNATIVEBYTES_NATIVE_ENDIAN`` will override any other endian " +"flags. Passing ``2`` is reserved." +msgstr "" + +#: ../../c-api/long.rst:555 +msgid "" +"By default, sufficient buffer will be requested to include a sign bit. For " +"example, when converting 128 with *n_bytes=1*, the function will return 2 " +"(or more) in order to store a zero sign bit." +msgstr "" + +#: ../../c-api/long.rst:559 +msgid "" +"If ``Py_ASNATIVEBYTES_UNSIGNED_BUFFER`` is specified, a zero sign bit will " +"be omitted from size calculations. This allows, for example, 128 to fit in a " +"single-byte buffer. If the destination buffer is later treated as signed, a " +"positive input value may become negative. Note that the flag does not affect " +"handling of negative values: for those, space for a sign bit is always " +"requested." +msgstr "" + +#: ../../c-api/long.rst:566 +msgid "" +"Specifying ``Py_ASNATIVEBYTES_REJECT_NEGATIVE`` causes an exception to be " +"set if *pylong* is negative. Without this flag, negative values will be " +"copied provided there is enough space for at least one sign bit, regardless " +"of whether ``Py_ASNATIVEBYTES_UNSIGNED_BUFFER`` was specified." +msgstr "" + +#: ../../c-api/long.rst:571 +msgid "" +"If ``Py_ASNATIVEBYTES_ALLOW_INDEX`` is specified and a non-integer value is " +"passed, its :meth:`~object.__index__` method will be called first. This may " +"result in Python code executing and other threads being allowed to run, " +"which could cause changes to other objects or values in use. When *flags* is " +"``-1``, this option is not set, and non-integer values will raise :exc:" +"`TypeError`." +msgstr "" + +#: ../../c-api/long.rst:580 +msgid "" +"With the default *flags* (``-1``, or *UNSIGNED_BUFFER* without " +"*REJECT_NEGATIVE*), multiple Python integers can map to a single value " +"without overflow. For example, both ``255`` and ``-1`` fit a single-byte " +"buffer and set all its bits. This matches typical C cast behavior." +msgstr "" + +#: ../../c-api/long.rst:591 +msgid "Macro for converting a Python integer into a process identifier." +msgstr "" + +#: ../../c-api/long.rst:593 +msgid "" +"This can be defined as an alias to :c:func:`PyLong_AsLong`, :c:func:" +"`PyLong_FromLongLong`, or :c:func:`PyLong_AsInt`, depending on the size of " +"the system's PID type." +msgstr "" + +#: ../../c-api/long.rst:602 +msgid "Get the sign of the integer object *obj*." +msgstr "" + +#: ../../c-api/long.rst:604 +msgid "" +"On success, set *\\*sign* to the integer sign (0, -1 or +1 for zero, " +"negative or positive integer, respectively) and return 0." +msgstr "" + +#: ../../c-api/long.rst:607 +msgid "" +"On failure, return -1 with an exception set. This function always succeeds " +"if *obj* is a :c:type:`PyLongObject` or its subtype." +msgstr "" + +#: ../../c-api/long.rst:615 +msgid "Check if the integer object *obj* is positive (``obj > 0``)." +msgstr "" + +#: ../../c-api/long.rst:617 +msgid "" +"If *obj* is an instance of :c:type:`PyLongObject` or its subtype, return " +"``1`` when it's positive and ``0`` otherwise. Else set an exception and " +"return ``-1``." +msgstr "" + +#: ../../c-api/long.rst:626 +msgid "Check if the integer object *obj* is negative (``obj < 0``)." +msgstr "" + +#: ../../c-api/long.rst:628 +msgid "" +"If *obj* is an instance of :c:type:`PyLongObject` or its subtype, return " +"``1`` when it's negative and ``0`` otherwise. Else set an exception and " +"return ``-1``." +msgstr "" + +#: ../../c-api/long.rst:637 +msgid "Check if the integer object *obj* is zero." +msgstr "" + +#: ../../c-api/long.rst:639 +msgid "" +"If *obj* is an instance of :c:type:`PyLongObject` or its subtype, return " +"``1`` when it's zero and ``0`` otherwise. Else set an exception and return " +"``-1``." +msgstr "" + +#: ../../c-api/long.rst:648 +msgid "" +"On success, return a read only :term:`named tuple`, that holds information " +"about Python's internal representation of integers. See :data:`sys.int_info` " +"for description of individual fields." +msgstr "" + +#: ../../c-api/long.rst:652 +msgid "On failure, return ``NULL`` with an exception set." +msgstr "在失敗時，會回傳 ``NULL`` 並設定例外。" + +#: ../../c-api/long.rst:659 +msgid "Return 1 if *op* is compact, 0 otherwise." +msgstr "" + +#: ../../c-api/long.rst:661 +msgid "" +"This function makes it possible for performance-critical code to implement a " +"“fast path” for small integers. For compact values use :c:func:" +"`PyUnstable_Long_CompactValue`; for others fall back to a :c:func:" +"`PyLong_As* ` function or :c:func:`PyLong_AsNativeBytes`." +msgstr "" + +#: ../../c-api/long.rst:667 +msgid "The speedup is expected to be negligible for most users." +msgstr "" + +#: ../../c-api/long.rst:669 +msgid "" +"Exactly what values are considered compact is an implementation detail and " +"is subject to change." +msgstr "" + +#: ../../c-api/long.rst:677 +msgid "" +"If *op* is compact, as determined by :c:func:`PyUnstable_Long_IsCompact`, " +"return its value." +msgstr "" + +#: ../../c-api/long.rst:680 +msgid "Otherwise, the return value is undefined." +msgstr "" + +#: ../../c-api/long.rst:686 +msgid "Export API" +msgstr "" + +#: ../../c-api/long.rst:692 +msgid "" +"Layout of an array of \"digits\" (\"limbs\" in the GMP terminology), used to " +"represent absolute value for arbitrary precision integers." +msgstr "" + +#: ../../c-api/long.rst:695 +msgid "" +"Use :c:func:`PyLong_GetNativeLayout` to get the native layout of Python :" +"class:`int` objects, used internally for integers with \"big enough\" " +"absolute value." +msgstr "" + +#: ../../c-api/long.rst:699 +msgid "" +"See also :data:`sys.int_info` which exposes similar information in Python." +msgstr "" + +#: ../../c-api/long.rst:703 +msgid "" +"Bits per digit. For example, a 15 bit digit means that bits 0-14 contain " +"meaningful information." +msgstr "" + +#: ../../c-api/long.rst:708 +msgid "" +"Digit size in bytes. For example, a 15 bit digit will require at least 2 " +"bytes." +msgstr "" + +#: ../../c-api/long.rst:713 +msgid "Digits order:" +msgstr "" + +#: ../../c-api/long.rst:715 +msgid "``1`` for most significant digit first" +msgstr "" + +#: ../../c-api/long.rst:716 +msgid "``-1`` for least significant digit first" +msgstr "" + +#: ../../c-api/long.rst:720 +msgid "Digit endianness:" +msgstr "" + +#: ../../c-api/long.rst:722 +msgid "``1`` for most significant byte first (big endian)" +msgstr "" + +#: ../../c-api/long.rst:723 +msgid "``-1`` for least significant byte first (little endian)" +msgstr "" + +#: ../../c-api/long.rst:728 +msgid "Get the native layout of Python :class:`int` objects." +msgstr "" + +#: ../../c-api/long.rst:730 +msgid "See the :c:struct:`PyLongLayout` structure." +msgstr "請見 :c:struct:`PyLongLayout` 結構。" + +#: ../../c-api/long.rst:732 +msgid "" +"The function must not be called before Python initialization nor after " +"Python finalization. The returned layout is valid until Python is finalized. " +"The layout is the same for all Python sub-interpreters in a process, and so " +"it can be cached." +msgstr "" + +#: ../../c-api/long.rst:740 +msgid "Export of a Python :class:`int` object." +msgstr "" + +#: ../../c-api/long.rst:742 +msgid "There are two cases:" +msgstr "" + +#: ../../c-api/long.rst:744 +msgid "" +"If :c:member:`digits` is ``NULL``, only use the :c:member:`value` member." +msgstr "" + +#: ../../c-api/long.rst:745 +msgid "" +"If :c:member:`digits` is not ``NULL``, use :c:member:`negative`, :c:member:" +"`ndigits` and :c:member:`digits` members." +msgstr "" + +#: ../../c-api/long.rst:750 +msgid "" +"The native integer value of the exported :class:`int` object. Only valid if :" +"c:member:`digits` is ``NULL``." +msgstr "" + +#: ../../c-api/long.rst:755 +msgid "" +"``1`` if the number is negative, ``0`` otherwise. Only valid if :c:member:" +"`digits` is not ``NULL``." +msgstr "" + +#: ../../c-api/long.rst:760 +msgid "" +"Number of digits in :c:member:`digits` array. Only valid if :c:member:" +"`digits` is not ``NULL``." +msgstr "" + +#: ../../c-api/long.rst:765 +msgid "Read-only array of unsigned digits. Can be ``NULL``." +msgstr "" + +#: ../../c-api/long.rst:770 +msgid "Export a Python :class:`int` object." +msgstr "" + +#: ../../c-api/long.rst:772 +msgid "" +"*export_long* must point to a :c:struct:`PyLongExport` structure allocated " +"by the caller. It must not be ``NULL``." +msgstr "" + +#: ../../c-api/long.rst:775 +msgid "" +"On success, fill in *\\*export_long* and return ``0``. On error, set an " +"exception and return ``-1``." +msgstr "" + +#: ../../c-api/long.rst:778 +msgid "" +":c:func:`PyLong_FreeExport` must be called when the export is no longer " +"needed." +msgstr "" + +#: ../../c-api/long.rst:782 +msgid "" +"This function always succeeds if *obj* is a Python :class:`int` object or a " +"subclass." +msgstr "" + +#: ../../c-api/long.rst:788 +msgid "Release the export *export_long* created by :c:func:`PyLong_Export`." +msgstr "" + +#: ../../c-api/long.rst:791 +msgid "" +"Calling :c:func:`PyLong_FreeExport` is optional if *export_long->digits* is " +"``NULL``." +msgstr "" + +#: ../../c-api/long.rst:796 +msgid "PyLongWriter API" +msgstr "" + +#: ../../c-api/long.rst:798 +msgid "The :c:type:`PyLongWriter` API can be used to import an integer." +msgstr "" + +#: ../../c-api/long.rst:804 +msgid "A Python :class:`int` writer instance." +msgstr "" + +#: ../../c-api/long.rst:806 +msgid "" +"The instance must be destroyed by :c:func:`PyLongWriter_Finish` or :c:func:" +"`PyLongWriter_Discard`." +msgstr "" + +#: ../../c-api/long.rst:812 +msgid "Create a :c:type:`PyLongWriter`." +msgstr "" + +#: ../../c-api/long.rst:814 +msgid "" +"On success, allocate *\\*digits* and return a writer. On error, set an " +"exception and return ``NULL``." +msgstr "" + +#: ../../c-api/long.rst:817 +msgid "*negative* is ``1`` if the number is negative, or ``0`` otherwise." +msgstr "" + +#: ../../c-api/long.rst:819 +msgid "" +"*ndigits* is the number of digits in the *digits* array. It must be greater " +"than 0." +msgstr "" + +#: ../../c-api/long.rst:822 +msgid "*digits* must not be NULL." +msgstr "" + +#: ../../c-api/long.rst:824 +msgid "" +"After a successful call to this function, the caller should fill in the " +"array of digits *digits* and then call :c:func:`PyLongWriter_Finish` to get " +"a Python :class:`int`. The layout of *digits* is described by :c:func:" +"`PyLong_GetNativeLayout`." +msgstr "" + +#: ../../c-api/long.rst:829 +msgid "" +"Digits must be in the range [``0``; ``(1 << bits_per_digit) - 1``] (where " +"the :c:struct:`~PyLongLayout.bits_per_digit` is the number of bits per " +"digit). Any unused most significant digits must be set to ``0``." +msgstr "" + +#: ../../c-api/long.rst:834 +msgid "" +"Alternately, call :c:func:`PyLongWriter_Discard` to destroy the writer " +"instance without creating an :class:`~int` object." +msgstr "" + +#: ../../c-api/long.rst:840 +msgid "" +"Finish a :c:type:`PyLongWriter` created by :c:func:`PyLongWriter_Create`." +msgstr "" + +#: ../../c-api/long.rst:842 +msgid "" +"On success, return a Python :class:`int` object. On error, set an exception " +"and return ``NULL``." +msgstr "" + +#: ../../c-api/long.rst:845 +msgid "" +"The function takes care of normalizing the digits and converts the object to " +"a compact integer if needed." +msgstr "" + +#: ../../c-api/long.rst:848 ../../c-api/long.rst:857 +msgid "The writer instance and the *digits* array are invalid after the call." +msgstr "" + +#: ../../c-api/long.rst:853 +msgid "" +"Discard a :c:type:`PyLongWriter` created by :c:func:`PyLongWriter_Create`." +msgstr "" + +#: ../../c-api/long.rst:855 +msgid "If *writer* is ``NULL``, no operation is performed." +msgstr "" + +#: ../../c-api/long.rst:8 +msgid "object" +msgstr "object（物件）" + +#: ../../c-api/long.rst:8 +msgid "long integer" +msgstr "long integer（長整數）" + +#: ../../c-api/long.rst:8 +msgid "integer" +msgstr "integer（整數）" + +#: ../../c-api/long.rst:177 +msgid "LONG_MAX (C macro)" +msgstr "LONG_MAX（C 巨集）" + +#: ../../c-api/long.rst:177 ../../c-api/long.rst:237 ../../c-api/long.rst:280 +#: ../../c-api/long.rst:295 ../../c-api/long.rst:311 ../../c-api/long.rst:327 +msgid "OverflowError (built-in exception)" +msgstr "OverflowError（內建例外）" + +#: ../../c-api/long.rst:280 +msgid "PY_SSIZE_T_MAX (C macro)" +msgstr "PY_SSIZE_T_MAX（C 巨集）" + +#: ../../c-api/long.rst:295 +msgid "ULONG_MAX (C macro)" +msgstr "ULONG_MAX（C 巨集）" + +#: ../../c-api/long.rst:311 +msgid "SIZE_MAX (C macro)" +msgstr "SIZE_MAX（C 巨集）" diff --git a/c-api/mapping.po b/c-api/mapping.po index 1be66dc2c0..31a774b6ad 100644 --- a/c-api/mapping.po +++ b/c-api/mapping.po @@ -1,199 +1,199 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Matt Wang , 2024 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-05 00:16+0000\n" -"PO-Revision-Date: 2024-05-11 14:32+0800\n" -"Last-Translator: Matt Wang \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" - -#: ../../c-api/mapping.rst:6 -msgid "Mapping Protocol" -msgstr "對映協定" - -#: ../../c-api/mapping.rst:8 -msgid "" -"See also :c:func:`PyObject_GetItem`, :c:func:`PyObject_SetItem` and :c:func:" -"`PyObject_DelItem`." -msgstr "" -"另請參閱 :c:func:`PyObject_GetItem`、:c:func:`PyObject_SetItem` 和 :c:func:" -"`PyObject_DelItem`。" - -#: ../../c-api/mapping.rst:14 -msgid "" -"Return ``1`` if the object provides the mapping protocol or supports " -"slicing, and ``0`` otherwise. Note that it returns ``1`` for Python classes " -"with a :meth:`~object.__getitem__` method, since in general it is impossible " -"to determine what type of keys the class supports. This function always " -"succeeds." -msgstr "" -"如果物件有提供對映協定或支援切片 (slicing) 則回傳 ``1``，否則回傳 ``0``。請注" -"意，對於具有 :meth:`~object.__getitem__` 方法的 Python 類別，它會回傳 ``1``，" -"因為通常無法確定該類別支援什麼類型的鍵。這個函式總會是成功的。" - -#: ../../c-api/mapping.rst:25 -msgid "" -"Returns the number of keys in object *o* on success, and ``-1`` on failure. " -"This is equivalent to the Python expression ``len(o)``." -msgstr "" -"成功時回傳物件 *o* 中的鍵數，失敗時回傳 ``-1``。這相當於 Python 運算式 " -"``len(o)``。" - -#: ../../c-api/mapping.rst:31 -msgid "" -"This is the same as :c:func:`PyObject_GetItem`, but *key* is specified as a :" -"c:expr:`const char*` UTF-8 encoded bytes string, rather than a :c:expr:" -"`PyObject*`." -msgstr "" -"這與 :c:func:`PyObject_GetItem` 相同，但 *key* 被指定為 :c:expr:`const " -"char*` UTF-8 編碼位元組字串，而不是 :c:expr:`PyObject*`。" - -#: ../../c-api/mapping.rst:38 -msgid "" -"Variant of :c:func:`PyObject_GetItem` which doesn't raise :exc:`KeyError` if " -"the key is not found." -msgstr "" - -#: ../../c-api/mapping.rst:41 -msgid "" -"If the key is found, return ``1`` and set *\\*result* to a new :term:`strong " -"reference` to the corresponding value. If the key is not found, return ``0`` " -"and set *\\*result* to ``NULL``; the :exc:`KeyError` is silenced. If an " -"error other than :exc:`KeyError` is raised, return ``-1`` and set " -"*\\*result* to ``NULL``." -msgstr "" - -#: ../../c-api/mapping.rst:53 -msgid "" -"This is the same as :c:func:`PyMapping_GetOptionalItem`, but *key* is " -"specified as a :c:expr:`const char*` UTF-8 encoded bytes string, rather than " -"a :c:expr:`PyObject*`." -msgstr "" -"這與 :c:func:`PyMapping_GetOptionalItem` 相同，但 *key* 被指定為 :c:expr:" -"`const char*` UTF-8 編碼位元組字串，而不是 :c:expr:`PyObject*`。" - -#: ../../c-api/mapping.rst:62 -msgid "" -"This is the same as :c:func:`PyObject_SetItem`, but *key* is specified as a :" -"c:expr:`const char*` UTF-8 encoded bytes string, rather than a :c:expr:" -"`PyObject*`." -msgstr "" -"這與 :c:func:`PyObject_SetItem` 相同，但 *key* 被指定為 :c:expr:`const " -"char*` UTF-8 編碼位元組字串，而不是 :c:expr:`PyObject*`。" - -#: ../../c-api/mapping.rst:69 -msgid "This is an alias of :c:func:`PyObject_DelItem`." -msgstr "這是 :c:func:`PyObject_DelItem` 的別名。" - -#: ../../c-api/mapping.rst:74 -msgid "" -"This is the same as :c:func:`PyObject_DelItem`, but *key* is specified as a :" -"c:expr:`const char*` UTF-8 encoded bytes string, rather than a :c:expr:" -"`PyObject*`." -msgstr "" -"這與 :c:func:`PyObject_DelItem` 相同，但 *key* 被指定為 :c:expr:`const " -"char*` UTF-8 編碼位元組字串，而不是 :c:expr:`PyObject*`。" - -#: ../../c-api/mapping.rst:81 -msgid "" -"Return ``1`` if the mapping object has the key *key* and ``0`` otherwise. " -"This is equivalent to the Python expression ``key in o``. On failure, return " -"``-1``." -msgstr "" -"如果對映物件具有鍵 *key* 則回傳 ``1``，否則回傳 ``0``。這相當於 Python 運算" -"式 ``key in o``。失敗時回傳 ``-1``。" - -#: ../../c-api/mapping.rst:90 -msgid "" -"This is the same as :c:func:`PyMapping_HasKeyWithError`, but *key* is " -"specified as a :c:expr:`const char*` UTF-8 encoded bytes string, rather than " -"a :c:expr:`PyObject*`." -msgstr "" -"這與 :c:func:`PyMapping_HasKeyWithError` 相同，但 *key* 被指定為 :c:expr:" -"`const char*` UTF-8 編碼位元組字串，而不是 :c:expr:`PyObject*`。" - -#: ../../c-api/mapping.rst:99 -msgid "" -"Return ``1`` if the mapping object has the key *key* and ``0`` otherwise. " -"This is equivalent to the Python expression ``key in o``. This function " -"always succeeds." -msgstr "" -"如果對映物件具有鍵 *key* 則回傳 ``1``，否則回傳 ``0``。這相當於 Python 運算" -"式 ``key in o``。這個函式總會是成功的。" - -#: ../../c-api/mapping.rst:105 -msgid "" -"Exceptions which occur when this calls the :meth:`~object.__getitem__` " -"method are silently ignored. For proper error handling, use :c:func:" -"`PyMapping_HasKeyWithError`, :c:func:`PyMapping_GetOptionalItem` or :c:func:" -"`PyObject_GetItem()` instead." -msgstr "" -"當它呼叫 :meth:`~object.__getitem__` 方法時發生的例外將被默默忽略。為了適當地" -"處理錯誤，請改用 :c:func:`PyMapping_HasKeyWithError`、:c:func:" -"`PyMapping_GetOptionalItem` 或 :c:func:`PyObject_GetItem()`。" - -#: ../../c-api/mapping.rst:113 -msgid "" -"This is the same as :c:func:`PyMapping_HasKey`, but *key* is specified as a :" -"c:expr:`const char*` UTF-8 encoded bytes string, rather than a :c:expr:" -"`PyObject*`." -msgstr "" -"這與 :c:func:`PyMapping_HasKey` 相同，但 *key* 被指定為 :c:expr:`const " -"char*` UTF-8 編碼位元組字串，而不是 :c:expr:`PyObject*`。" - -#: ../../c-api/mapping.rst:119 -msgid "" -"Exceptions that occur when this calls the :meth:`~object.__getitem__` method " -"or while creating the temporary :class:`str` object are silently ignored. " -"For proper error handling, use :c:func:`PyMapping_HasKeyStringWithError`, :c:" -"func:`PyMapping_GetOptionalItemString` or :c:func:`PyMapping_GetItemString` " -"instead." -msgstr "" -"當它呼叫 :meth:`~object.__getitem__` 方法或建立臨時 :class:`str` 物件時發生的" -"例外將被默默忽略。為了適當地處理錯誤，請改用 :c:func:" -"`PyMapping_HasKeyStringWithError`、:c:func:`PyMapping_GetOptionalItemString` " -"或 :c:func:`PyMapping_GetItemString`。" - -#: ../../c-api/mapping.rst:129 -msgid "" -"On success, return a list of the keys in object *o*. On failure, return " -"``NULL``." -msgstr "成功時回傳一個物件 *o* 內之鍵的串列，失敗時回傳 ``NULL``。" - -#: ../../c-api/mapping.rst:132 ../../c-api/mapping.rst:141 -#: ../../c-api/mapping.rst:150 -msgid "Previously, the function returned a list or a tuple." -msgstr "在以前，該函式會回傳串列或元組。" - -#: ../../c-api/mapping.rst:138 -msgid "" -"On success, return a list of the values in object *o*. On failure, return " -"``NULL``." -msgstr "成功時回傳物件 *o* 中值的串列。失敗時回傳 ``NULL``。" - -#: ../../c-api/mapping.rst:147 -msgid "" -"On success, return a list of the items in object *o*, where each item is a " -"tuple containing a key-value pair. On failure, return ``NULL``." -msgstr "" -"成功時回傳物件 *o* 內之項目的串列，其中每個項目都是包含鍵值對的元組。失敗時回" -"傳 ``NULL``。" - -#: ../../c-api/mapping.rst:23 -msgid "built-in function" -msgstr "built-in function（內建函式）" - -#: ../../c-api/mapping.rst:23 -msgid "len" -msgstr "len" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Matt Wang , 2024 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-05 00:16+0000\n" +"PO-Revision-Date: 2024-05-11 14:32+0800\n" +"Last-Translator: Matt Wang \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" + +#: ../../c-api/mapping.rst:6 +msgid "Mapping Protocol" +msgstr "對映協定" + +#: ../../c-api/mapping.rst:8 +msgid "" +"See also :c:func:`PyObject_GetItem`, :c:func:`PyObject_SetItem` and :c:func:" +"`PyObject_DelItem`." +msgstr "" +"另請參閱 :c:func:`PyObject_GetItem`、:c:func:`PyObject_SetItem` 和 :c:func:" +"`PyObject_DelItem`。" + +#: ../../c-api/mapping.rst:14 +msgid "" +"Return ``1`` if the object provides the mapping protocol or supports " +"slicing, and ``0`` otherwise. Note that it returns ``1`` for Python classes " +"with a :meth:`~object.__getitem__` method, since in general it is impossible " +"to determine what type of keys the class supports. This function always " +"succeeds." +msgstr "" +"如果物件有提供對映協定或支援切片 (slicing) 則回傳 ``1``，否則回傳 ``0``。請注" +"意，對於具有 :meth:`~object.__getitem__` 方法的 Python 類別，它會回傳 ``1``，" +"因為通常無法確定該類別支援什麼類型的鍵。這個函式總會是成功的。" + +#: ../../c-api/mapping.rst:25 +msgid "" +"Returns the number of keys in object *o* on success, and ``-1`` on failure. " +"This is equivalent to the Python expression ``len(o)``." +msgstr "" +"成功時回傳物件 *o* 中的鍵數，失敗時回傳 ``-1``。這相當於 Python 運算式 " +"``len(o)``。" + +#: ../../c-api/mapping.rst:31 +msgid "" +"This is the same as :c:func:`PyObject_GetItem`, but *key* is specified as a :" +"c:expr:`const char*` UTF-8 encoded bytes string, rather than a :c:expr:" +"`PyObject*`." +msgstr "" +"這與 :c:func:`PyObject_GetItem` 相同，但 *key* 被指定為 :c:expr:`const " +"char*` UTF-8 編碼位元組字串，而不是 :c:expr:`PyObject*`。" + +#: ../../c-api/mapping.rst:38 +msgid "" +"Variant of :c:func:`PyObject_GetItem` which doesn't raise :exc:`KeyError` if " +"the key is not found." +msgstr "" + +#: ../../c-api/mapping.rst:41 +msgid "" +"If the key is found, return ``1`` and set *\\*result* to a new :term:`strong " +"reference` to the corresponding value. If the key is not found, return ``0`` " +"and set *\\*result* to ``NULL``; the :exc:`KeyError` is silenced. If an " +"error other than :exc:`KeyError` is raised, return ``-1`` and set " +"*\\*result* to ``NULL``." +msgstr "" + +#: ../../c-api/mapping.rst:53 +msgid "" +"This is the same as :c:func:`PyMapping_GetOptionalItem`, but *key* is " +"specified as a :c:expr:`const char*` UTF-8 encoded bytes string, rather than " +"a :c:expr:`PyObject*`." +msgstr "" +"這與 :c:func:`PyMapping_GetOptionalItem` 相同，但 *key* 被指定為 :c:expr:" +"`const char*` UTF-8 編碼位元組字串，而不是 :c:expr:`PyObject*`。" + +#: ../../c-api/mapping.rst:62 +msgid "" +"This is the same as :c:func:`PyObject_SetItem`, but *key* is specified as a :" +"c:expr:`const char*` UTF-8 encoded bytes string, rather than a :c:expr:" +"`PyObject*`." +msgstr "" +"這與 :c:func:`PyObject_SetItem` 相同，但 *key* 被指定為 :c:expr:`const " +"char*` UTF-8 編碼位元組字串，而不是 :c:expr:`PyObject*`。" + +#: ../../c-api/mapping.rst:69 +msgid "This is an alias of :c:func:`PyObject_DelItem`." +msgstr "這是 :c:func:`PyObject_DelItem` 的別名。" + +#: ../../c-api/mapping.rst:74 +msgid "" +"This is the same as :c:func:`PyObject_DelItem`, but *key* is specified as a :" +"c:expr:`const char*` UTF-8 encoded bytes string, rather than a :c:expr:" +"`PyObject*`." +msgstr "" +"這與 :c:func:`PyObject_DelItem` 相同，但 *key* 被指定為 :c:expr:`const " +"char*` UTF-8 編碼位元組字串，而不是 :c:expr:`PyObject*`。" + +#: ../../c-api/mapping.rst:81 +msgid "" +"Return ``1`` if the mapping object has the key *key* and ``0`` otherwise. " +"This is equivalent to the Python expression ``key in o``. On failure, return " +"``-1``." +msgstr "" +"如果對映物件具有鍵 *key* 則回傳 ``1``，否則回傳 ``0``。這相當於 Python 運算" +"式 ``key in o``。失敗時回傳 ``-1``。" + +#: ../../c-api/mapping.rst:90 +msgid "" +"This is the same as :c:func:`PyMapping_HasKeyWithError`, but *key* is " +"specified as a :c:expr:`const char*` UTF-8 encoded bytes string, rather than " +"a :c:expr:`PyObject*`." +msgstr "" +"這與 :c:func:`PyMapping_HasKeyWithError` 相同，但 *key* 被指定為 :c:expr:" +"`const char*` UTF-8 編碼位元組字串，而不是 :c:expr:`PyObject*`。" + +#: ../../c-api/mapping.rst:99 +msgid "" +"Return ``1`` if the mapping object has the key *key* and ``0`` otherwise. " +"This is equivalent to the Python expression ``key in o``. This function " +"always succeeds." +msgstr "" +"如果對映物件具有鍵 *key* 則回傳 ``1``，否則回傳 ``0``。這相當於 Python 運算" +"式 ``key in o``。這個函式總會是成功的。" + +#: ../../c-api/mapping.rst:105 +msgid "" +"Exceptions which occur when this calls the :meth:`~object.__getitem__` " +"method are silently ignored. For proper error handling, use :c:func:" +"`PyMapping_HasKeyWithError`, :c:func:`PyMapping_GetOptionalItem` or :c:func:" +"`PyObject_GetItem()` instead." +msgstr "" +"當它呼叫 :meth:`~object.__getitem__` 方法時發生的例外將被默默忽略。為了適當地" +"處理錯誤，請改用 :c:func:`PyMapping_HasKeyWithError`、:c:func:" +"`PyMapping_GetOptionalItem` 或 :c:func:`PyObject_GetItem()`。" + +#: ../../c-api/mapping.rst:113 +msgid "" +"This is the same as :c:func:`PyMapping_HasKey`, but *key* is specified as a :" +"c:expr:`const char*` UTF-8 encoded bytes string, rather than a :c:expr:" +"`PyObject*`." +msgstr "" +"這與 :c:func:`PyMapping_HasKey` 相同，但 *key* 被指定為 :c:expr:`const " +"char*` UTF-8 編碼位元組字串，而不是 :c:expr:`PyObject*`。" + +#: ../../c-api/mapping.rst:119 +msgid "" +"Exceptions that occur when this calls the :meth:`~object.__getitem__` method " +"or while creating the temporary :class:`str` object are silently ignored. " +"For proper error handling, use :c:func:`PyMapping_HasKeyStringWithError`, :c:" +"func:`PyMapping_GetOptionalItemString` or :c:func:`PyMapping_GetItemString` " +"instead." +msgstr "" +"當它呼叫 :meth:`~object.__getitem__` 方法或建立臨時 :class:`str` 物件時發生的" +"例外將被默默忽略。為了適當地處理錯誤，請改用 :c:func:" +"`PyMapping_HasKeyStringWithError`、:c:func:`PyMapping_GetOptionalItemString` " +"或 :c:func:`PyMapping_GetItemString`。" + +#: ../../c-api/mapping.rst:129 +msgid "" +"On success, return a list of the keys in object *o*. On failure, return " +"``NULL``." +msgstr "成功時回傳一個物件 *o* 內之鍵的串列，失敗時回傳 ``NULL``。" + +#: ../../c-api/mapping.rst:132 ../../c-api/mapping.rst:141 +#: ../../c-api/mapping.rst:150 +msgid "Previously, the function returned a list or a tuple." +msgstr "在以前，該函式會回傳串列或元組。" + +#: ../../c-api/mapping.rst:138 +msgid "" +"On success, return a list of the values in object *o*. On failure, return " +"``NULL``." +msgstr "成功時回傳物件 *o* 中值的串列。失敗時回傳 ``NULL``。" + +#: ../../c-api/mapping.rst:147 +msgid "" +"On success, return a list of the items in object *o*, where each item is a " +"tuple containing a key-value pair. On failure, return ``NULL``." +msgstr "" +"成功時回傳物件 *o* 內之項目的串列，其中每個項目都是包含鍵值對的元組。失敗時回" +"傳 ``NULL``。" + +#: ../../c-api/mapping.rst:23 +msgid "built-in function" +msgstr "built-in function（內建函式）" + +#: ../../c-api/mapping.rst:23 +msgid "len" +msgstr "len" diff --git a/c-api/marshal.po b/c-api/marshal.po index 41698940f0..4b61d3a03c 100644 --- a/c-api/marshal.po +++ b/c-api/marshal.po @@ -1,162 +1,162 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Adrian Liaw , 2018 -# Matt Wang , 2025 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-05 00:16+0000\n" -"PO-Revision-Date: 2025-06-28 02:44+0800\n" -"Last-Translator: Matt Wang \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" -"X-Generator: Poedit 3.6\n" - -#: ../../c-api/marshal.rst:6 -msgid "Data marshalling support" -msgstr "資料 marshal 操作的支援" - -#: ../../c-api/marshal.rst:8 -msgid "" -"These routines allow C code to work with serialized objects using the same " -"data format as the :mod:`marshal` module. There are functions to write data " -"into the serialization format, and additional functions that can be used to " -"read the data back. Files used to store marshalled data must be opened in " -"binary mode." -msgstr "" -"這些例程允許 C 程式碼使用與 :mod:`marshal` 模組相同的資料格式來處理序列化物" -"件。有函式可以將資料寫入序列化格式，還有其他函式可以用來讀取回資料。用來儲存 " -"marshal 過的資料的檔案必須以二進位模式開啟。" - -#: ../../c-api/marshal.rst:14 -msgid "Numeric values are stored with the least significant byte first." -msgstr "數值會以最低有效位元組 (the least significant byte) 優先的方式儲存。" - -#: ../../c-api/marshal.rst:16 -msgid "" -"The module supports several versions of the data format; see the :py:mod:" -"`Python module documentation ` for details." -msgstr "" - -#: ../../c-api/marshal.rst:21 -msgid "The current format version. See :py:data:`marshal.version`." -msgstr "" - -#: ../../c-api/marshal.rst:25 -msgid "" -"Marshal a :c:expr:`long` integer, *value*, to *file*. This will only write " -"the least-significant 32 bits of *value*; regardless of the size of the " -"native :c:expr:`long` type. *version* indicates the file format." -msgstr "" -"將一個 :c:expr:`long` 整數 *value* marshal 為 *file*。這只會寫入 *value* 的最" -"低有效 32 位元；無論原生 :c:expr:`long` 型別的大小如何。*version* 表示檔案的" -"格式。" - -#: ../../c-api/marshal.rst:29 ../../c-api/marshal.rst:37 -msgid "" -"This function can fail, in which case it sets the error indicator. Use :c:" -"func:`PyErr_Occurred` to check for that." -msgstr "" -"這個函式可能會失敗，這時會設定錯誤指示器。使用 :c:func:`PyErr_Occurred` 來檢" -"查是否發生錯誤。" - -#: ../../c-api/marshal.rst:34 -msgid "" -"Marshal a Python object, *value*, to *file*. *version* indicates the file " -"format." -msgstr "" -"將一個 Python 物件 *value* marshal 為 *file*。*version* 表示檔案的格式。" - -#: ../../c-api/marshal.rst:42 -msgid "" -"Return a bytes object containing the marshalled representation of *value*. " -"*version* indicates the file format." -msgstr "" -"回傳一個位元組物件，包含 *value* 的 marshal 表示。*version* 為檔案的格式。" - -#: ../../c-api/marshal.rst:46 -msgid "The following functions allow marshalled values to be read back in." -msgstr "以下函式允許將 marshal 過後的值讀取回來。" - -#: ../../c-api/marshal.rst:51 -msgid "" -"Return a C :c:expr:`long` from the data stream in a :c:expr:`FILE*` opened " -"for reading. Only a 32-bit value can be read in using this function, " -"regardless of the native size of :c:expr:`long`." -msgstr "" -"從一個為讀取而開啟的 :c:expr:`FILE*` 中的資料串流回傳一個 C :c:expr:`long`。" -"無論 :c:expr:`long` 的原生大小如何，這個函式只能讀取 32 位元的值。" - -#: ../../c-api/marshal.rst:55 ../../c-api/marshal.rst:65 -msgid "" -"On error, sets the appropriate exception (:exc:`EOFError`) and returns " -"``-1``." -msgstr "在錯誤發生時，會設定合適的例外（:exc:`EOFError`）並回傳 ``-1``。" - -#: ../../c-api/marshal.rst:61 -msgid "" -"Return a C :c:expr:`short` from the data stream in a :c:expr:`FILE*` opened " -"for reading. Only a 16-bit value can be read in using this function, " -"regardless of the native size of :c:expr:`short`." -msgstr "" -"從一個為讀取而開啟的 :c:expr:`FILE*` 中的資料串流回傳一個 C :c:expr:`short`。" -"無論 :c:expr:`short` 的原生大小如何，這個函式只能讀取 16 位元的值。" - -#: ../../c-api/marshal.rst:71 -msgid "" -"Return a Python object from the data stream in a :c:expr:`FILE*` opened for " -"reading." -msgstr "" -"從一個為讀取而開啟的 :c:expr:`FILE*` 中的資料串流回傳一個 Python 物件。" - -#: ../../c-api/marshal.rst:74 ../../c-api/marshal.rst:88 -#: ../../c-api/marshal.rst:97 -msgid "" -"On error, sets the appropriate exception (:exc:`EOFError`, :exc:`ValueError` " -"or :exc:`TypeError`) and returns ``NULL``." -msgstr "" -"在錯誤發生時，會設定合適的例外（:exc:`EOFError`、:exc:`ValueError` 或 :exc:" -"`TypeError`）並回傳 ``NULL``。" - -#: ../../c-api/marshal.rst:80 -msgid "" -"Return a Python object from the data stream in a :c:expr:`FILE*` opened for " -"reading. Unlike :c:func:`PyMarshal_ReadObjectFromFile`, this function " -"assumes that no further objects will be read from the file, allowing it to " -"aggressively load file data into memory so that the de-serialization can " -"operate from data in memory rather than reading a byte at a time from the " -"file. Only use this variant if you are certain that you won't be reading " -"anything else from the file." -msgstr "" -"從一個為讀取而開啟的 :c:expr:`FILE*` 中的資料串流回傳一個 Python 物件。與 :c:" -"func:`PyMarshal_ReadObjectFromFile` 不同，這個函式假設不會從檔案中讀取其他物" -"件，允許它積極地將檔案資料載入記憶體，以便反序列化可以從記憶體中的資料操作，" -"而不是從檔案中逐位元組讀取。只有在確定不會從檔案中讀取其他內容時，才使用這個" -"變體。" - -#: ../../c-api/marshal.rst:94 -msgid "" -"Return a Python object from the data stream in a byte buffer containing " -"*len* bytes pointed to by *data*." -msgstr "" -"從一個包含 *len* 位元組、被 *data* 指向的位元組緩衝區中的資料串流回傳一個 " -"Python 物件。" - -#~ msgid "" -#~ "The module supports two versions of the data format: version 0 is the " -#~ "historical version, version 1 shares interned strings in the file, and " -#~ "upon unmarshalling. Version 2 uses a binary format for floating-point " -#~ "numbers. ``Py_MARSHAL_VERSION`` indicates the current file format " -#~ "(currently 2)." -#~ msgstr "" -#~ "這個模組支援兩個版本的資料格式：版本 0 是歷史版本，版本 1 在檔案中共享駐留" -#~ "字串 (interned strings)，並在 unmarshal 時使用。版本 2 使用二進位格式來儲" -#~ "存浮點數。``Py_MARSHAL_VERSION`` 表示目前的檔案格式（目前為 2）。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Adrian Liaw , 2018 +# Matt Wang , 2025 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-05 00:16+0000\n" +"PO-Revision-Date: 2025-06-28 02:44+0800\n" +"Last-Translator: Matt Wang \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" +"X-Generator: Poedit 3.6\n" + +#: ../../c-api/marshal.rst:6 +msgid "Data marshalling support" +msgstr "資料 marshal 操作的支援" + +#: ../../c-api/marshal.rst:8 +msgid "" +"These routines allow C code to work with serialized objects using the same " +"data format as the :mod:`marshal` module. There are functions to write data " +"into the serialization format, and additional functions that can be used to " +"read the data back. Files used to store marshalled data must be opened in " +"binary mode." +msgstr "" +"這些例程允許 C 程式碼使用與 :mod:`marshal` 模組相同的資料格式來處理序列化物" +"件。有函式可以將資料寫入序列化格式，還有其他函式可以用來讀取回資料。用來儲存 " +"marshal 過的資料的檔案必須以二進位模式開啟。" + +#: ../../c-api/marshal.rst:14 +msgid "Numeric values are stored with the least significant byte first." +msgstr "數值會以最低有效位元組 (the least significant byte) 優先的方式儲存。" + +#: ../../c-api/marshal.rst:16 +msgid "" +"The module supports several versions of the data format; see the :py:mod:" +"`Python module documentation ` for details." +msgstr "" + +#: ../../c-api/marshal.rst:21 +msgid "The current format version. See :py:data:`marshal.version`." +msgstr "" + +#: ../../c-api/marshal.rst:25 +msgid "" +"Marshal a :c:expr:`long` integer, *value*, to *file*. This will only write " +"the least-significant 32 bits of *value*; regardless of the size of the " +"native :c:expr:`long` type. *version* indicates the file format." +msgstr "" +"將一個 :c:expr:`long` 整數 *value* marshal 為 *file*。這只會寫入 *value* 的最" +"低有效 32 位元；無論原生 :c:expr:`long` 型別的大小如何。*version* 表示檔案的" +"格式。" + +#: ../../c-api/marshal.rst:29 ../../c-api/marshal.rst:37 +msgid "" +"This function can fail, in which case it sets the error indicator. Use :c:" +"func:`PyErr_Occurred` to check for that." +msgstr "" +"這個函式可能會失敗，這時會設定錯誤指示器。使用 :c:func:`PyErr_Occurred` 來檢" +"查是否發生錯誤。" + +#: ../../c-api/marshal.rst:34 +msgid "" +"Marshal a Python object, *value*, to *file*. *version* indicates the file " +"format." +msgstr "" +"將一個 Python 物件 *value* marshal 為 *file*。*version* 表示檔案的格式。" + +#: ../../c-api/marshal.rst:42 +msgid "" +"Return a bytes object containing the marshalled representation of *value*. " +"*version* indicates the file format." +msgstr "" +"回傳一個位元組物件，包含 *value* 的 marshal 表示。*version* 為檔案的格式。" + +#: ../../c-api/marshal.rst:46 +msgid "The following functions allow marshalled values to be read back in." +msgstr "以下函式允許將 marshal 過後的值讀取回來。" + +#: ../../c-api/marshal.rst:51 +msgid "" +"Return a C :c:expr:`long` from the data stream in a :c:expr:`FILE*` opened " +"for reading. Only a 32-bit value can be read in using this function, " +"regardless of the native size of :c:expr:`long`." +msgstr "" +"從一個為讀取而開啟的 :c:expr:`FILE*` 中的資料串流回傳一個 C :c:expr:`long`。" +"無論 :c:expr:`long` 的原生大小如何，這個函式只能讀取 32 位元的值。" + +#: ../../c-api/marshal.rst:55 ../../c-api/marshal.rst:65 +msgid "" +"On error, sets the appropriate exception (:exc:`EOFError`) and returns " +"``-1``." +msgstr "在錯誤發生時，會設定合適的例外（:exc:`EOFError`）並回傳 ``-1``。" + +#: ../../c-api/marshal.rst:61 +msgid "" +"Return a C :c:expr:`short` from the data stream in a :c:expr:`FILE*` opened " +"for reading. Only a 16-bit value can be read in using this function, " +"regardless of the native size of :c:expr:`short`." +msgstr "" +"從一個為讀取而開啟的 :c:expr:`FILE*` 中的資料串流回傳一個 C :c:expr:`short`。" +"無論 :c:expr:`short` 的原生大小如何，這個函式只能讀取 16 位元的值。" + +#: ../../c-api/marshal.rst:71 +msgid "" +"Return a Python object from the data stream in a :c:expr:`FILE*` opened for " +"reading." +msgstr "" +"從一個為讀取而開啟的 :c:expr:`FILE*` 中的資料串流回傳一個 Python 物件。" + +#: ../../c-api/marshal.rst:74 ../../c-api/marshal.rst:88 +#: ../../c-api/marshal.rst:97 +msgid "" +"On error, sets the appropriate exception (:exc:`EOFError`, :exc:`ValueError` " +"or :exc:`TypeError`) and returns ``NULL``." +msgstr "" +"在錯誤發生時，會設定合適的例外（:exc:`EOFError`、:exc:`ValueError` 或 :exc:" +"`TypeError`）並回傳 ``NULL``。" + +#: ../../c-api/marshal.rst:80 +msgid "" +"Return a Python object from the data stream in a :c:expr:`FILE*` opened for " +"reading. Unlike :c:func:`PyMarshal_ReadObjectFromFile`, this function " +"assumes that no further objects will be read from the file, allowing it to " +"aggressively load file data into memory so that the de-serialization can " +"operate from data in memory rather than reading a byte at a time from the " +"file. Only use this variant if you are certain that you won't be reading " +"anything else from the file." +msgstr "" +"從一個為讀取而開啟的 :c:expr:`FILE*` 中的資料串流回傳一個 Python 物件。與 :c:" +"func:`PyMarshal_ReadObjectFromFile` 不同，這個函式假設不會從檔案中讀取其他物" +"件，允許它積極地將檔案資料載入記憶體，以便反序列化可以從記憶體中的資料操作，" +"而不是從檔案中逐位元組讀取。只有在確定不會從檔案中讀取其他內容時，才使用這個" +"變體。" + +#: ../../c-api/marshal.rst:94 +msgid "" +"Return a Python object from the data stream in a byte buffer containing " +"*len* bytes pointed to by *data*." +msgstr "" +"從一個包含 *len* 位元組、被 *data* 指向的位元組緩衝區中的資料串流回傳一個 " +"Python 物件。" + +#~ msgid "" +#~ "The module supports two versions of the data format: version 0 is the " +#~ "historical version, version 1 shares interned strings in the file, and " +#~ "upon unmarshalling. Version 2 uses a binary format for floating-point " +#~ "numbers. ``Py_MARSHAL_VERSION`` indicates the current file format " +#~ "(currently 2)." +#~ msgstr "" +#~ "這個模組支援兩個版本的資料格式：版本 0 是歷史版本，版本 1 在檔案中共享駐留" +#~ "字串 (interned strings)，並在 unmarshal 時使用。版本 2 使用二進位格式來儲" +#~ "存浮點數。``Py_MARSHAL_VERSION`` 表示目前的檔案格式（目前為 2）。" diff --git a/c-api/memory.po b/c-api/memory.po index a5631a2f0c..6ff3bb39a3 100644 --- a/c-api/memory.po +++ b/c-api/memory.po @@ -1,1209 +1,1209 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Ching-Lung Chuang, 2015 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-05 00:16+0000\n" -"PO-Revision-Date: 2018-05-23 14:06+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" - -#: ../../c-api/memory.rst:8 -msgid "Memory Management" -msgstr "記憶體管理" - -#: ../../c-api/memory.rst:17 -msgid "Overview" -msgstr "總覽" - -#: ../../c-api/memory.rst:19 -msgid "" -"Memory management in Python involves a private heap containing all Python " -"objects and data structures. The management of this private heap is ensured " -"internally by the *Python memory manager*. The Python memory manager has " -"different components which deal with various dynamic storage management " -"aspects, like sharing, segmentation, preallocation or caching." -msgstr "" - -#: ../../c-api/memory.rst:25 -msgid "" -"At the lowest level, a raw memory allocator ensures that there is enough " -"room in the private heap for storing all Python-related data by interacting " -"with the memory manager of the operating system. On top of the raw memory " -"allocator, several object-specific allocators operate on the same heap and " -"implement distinct memory management policies adapted to the peculiarities " -"of every object type. For example, integer objects are managed differently " -"within the heap than strings, tuples or dictionaries because integers imply " -"different storage requirements and speed/space tradeoffs. The Python memory " -"manager thus delegates some of the work to the object-specific allocators, " -"but ensures that the latter operate within the bounds of the private heap." -msgstr "" - -#: ../../c-api/memory.rst:36 -msgid "" -"It is important to understand that the management of the Python heap is " -"performed by the interpreter itself and that the user has no control over " -"it, even if they regularly manipulate object pointers to memory blocks " -"inside that heap. The allocation of heap space for Python objects and other " -"internal buffers is performed on demand by the Python memory manager through " -"the Python/C API functions listed in this document." -msgstr "" - -#: ../../c-api/memory.rst:49 -msgid "" -"To avoid memory corruption, extension writers should never try to operate on " -"Python objects with the functions exported by the C library: :c:func:" -"`malloc`, :c:func:`calloc`, :c:func:`realloc` and :c:func:`free`. This will " -"result in mixed calls between the C allocator and the Python memory manager " -"with fatal consequences, because they implement different algorithms and " -"operate on different heaps. However, one may safely allocate and release " -"memory blocks with the C library allocator for individual purposes, as shown " -"in the following example::" -msgstr "" - -#: ../../c-api/memory.rst:58 -msgid "" -"PyObject *res;\n" -"char *buf = (char *) malloc(BUFSIZ); /* for I/O */\n" -"\n" -"if (buf == NULL)\n" -" return PyErr_NoMemory();\n" -"...Do some I/O operation involving buf...\n" -"res = PyBytes_FromString(buf);\n" -"free(buf); /* malloc'ed */\n" -"return res;" -msgstr "" - -#: ../../c-api/memory.rst:68 -msgid "" -"In this example, the memory request for the I/O buffer is handled by the C " -"library allocator. The Python memory manager is involved only in the " -"allocation of the bytes object returned as a result." -msgstr "" - -#: ../../c-api/memory.rst:72 -msgid "" -"In most situations, however, it is recommended to allocate memory from the " -"Python heap specifically because the latter is under control of the Python " -"memory manager. For example, this is required when the interpreter is " -"extended with new object types written in C. Another reason for using the " -"Python heap is the desire to *inform* the Python memory manager about the " -"memory needs of the extension module. Even when the requested memory is used " -"exclusively for internal, highly specific purposes, delegating all memory " -"requests to the Python memory manager causes the interpreter to have a more " -"accurate image of its memory footprint as a whole. Consequently, under " -"certain circumstances, the Python memory manager may or may not trigger " -"appropriate actions, like garbage collection, memory compaction or other " -"preventive procedures. Note that by using the C library allocator as shown " -"in the previous example, the allocated memory for the I/O buffer escapes " -"completely the Python memory manager." -msgstr "" - -#: ../../c-api/memory.rst:88 -msgid "" -"The :envvar:`PYTHONMALLOC` environment variable can be used to configure the " -"memory allocators used by Python." -msgstr "" - -#: ../../c-api/memory.rst:91 -msgid "" -"The :envvar:`PYTHONMALLOCSTATS` environment variable can be used to print " -"statistics of the :ref:`pymalloc memory allocator ` every time a " -"new pymalloc object arena is created, and on shutdown." -msgstr "" - -#: ../../c-api/memory.rst:96 -msgid "Allocator Domains" -msgstr "" - -#: ../../c-api/memory.rst:100 -msgid "" -"All allocating functions belong to one of three different \"domains\" (see " -"also :c:type:`PyMemAllocatorDomain`). These domains represent different " -"allocation strategies and are optimized for different purposes. The specific " -"details on how every domain allocates memory or what internal functions each " -"domain calls is considered an implementation detail, but for debugging " -"purposes a simplified table can be found at :ref:`default-memory-" -"allocators`. The APIs used to allocate and free a block of memory must be " -"from the same domain. For example, :c:func:`PyMem_Free` must be used to free " -"memory allocated using :c:func:`PyMem_Malloc`." -msgstr "" - -#: ../../c-api/memory.rst:109 -msgid "The three allocation domains are:" -msgstr "" - -#: ../../c-api/memory.rst:111 -msgid "" -"Raw domain: intended for allocating memory for general-purpose memory " -"buffers where the allocation *must* go to the system allocator or where the " -"allocator can operate without an :term:`attached thread state`. The memory " -"is requested directly from the system. See :ref:`Raw Memory Interface `." -msgstr "" - -#: ../../c-api/memory.rst:116 -msgid "" -"\"Mem\" domain: intended for allocating memory for Python buffers and " -"general-purpose memory buffers where the allocation must be performed with " -"an :term:`attached thread state`. The memory is taken from the Python " -"private heap. See :ref:`Memory Interface `." -msgstr "" - -#: ../../c-api/memory.rst:121 -msgid "" -"Object domain: intended for allocating memory for Python objects. The memory " -"is taken from the Python private heap. See :ref:`Object allocators " -"`." -msgstr "" - -#: ../../c-api/memory.rst:126 -msgid "" -"The :term:`free-threaded ` build requires that only Python " -"objects are allocated using the \"object\" domain and that all Python " -"objects are allocated using that domain. This differs from the prior Python " -"versions, where this was only a best practice and not a hard requirement." -msgstr "" - -#: ../../c-api/memory.rst:130 -msgid "" -"For example, buffers (non-Python objects) should be allocated using :c:func:" -"`PyMem_Malloc`, :c:func:`PyMem_RawMalloc`, or :c:func:`malloc`, but not :c:" -"func:`PyObject_Malloc`." -msgstr "" - -#: ../../c-api/memory.rst:133 -msgid "See :ref:`Memory Allocation APIs `." -msgstr "" - -#: ../../c-api/memory.rst:139 -msgid "Raw Memory Interface" -msgstr "" - -#: ../../c-api/memory.rst:141 -msgid "" -"The following function sets are wrappers to the system allocator. These " -"functions are thread-safe, so a :term:`thread state` does not need to be :" -"term:`attached `." -msgstr "" - -#: ../../c-api/memory.rst:145 -msgid "" -"The :ref:`default raw memory allocator ` uses the " -"following functions: :c:func:`malloc`, :c:func:`calloc`, :c:func:`realloc` " -"and :c:func:`!free`; call ``malloc(1)`` (or ``calloc(1, 1)``) when " -"requesting zero bytes." -msgstr "" - -#: ../../c-api/memory.rst:154 ../../c-api/memory.rst:224 -#: ../../c-api/memory.rst:333 -msgid "" -"Allocates *n* bytes and returns a pointer of type :c:expr:`void*` to the " -"allocated memory, or ``NULL`` if the request fails." -msgstr "" - -#: ../../c-api/memory.rst:157 -msgid "" -"Requesting zero bytes returns a distinct non-``NULL`` pointer if possible, " -"as if ``PyMem_RawMalloc(1)`` had been called instead. The memory will not " -"have been initialized in any way." -msgstr "" - -#: ../../c-api/memory.rst:164 ../../c-api/memory.rst:234 -#: ../../c-api/memory.rst:343 -msgid "" -"Allocates *nelem* elements each whose size in bytes is *elsize* and returns " -"a pointer of type :c:expr:`void*` to the allocated memory, or ``NULL`` if " -"the request fails. The memory is initialized to zeros." -msgstr "" - -#: ../../c-api/memory.rst:168 -msgid "" -"Requesting zero elements or elements of size zero bytes returns a distinct " -"non-``NULL`` pointer if possible, as if ``PyMem_RawCalloc(1, 1)`` had been " -"called instead." -msgstr "" - -#: ../../c-api/memory.rst:177 ../../c-api/memory.rst:247 -#: ../../c-api/memory.rst:356 -msgid "" -"Resizes the memory block pointed to by *p* to *n* bytes. The contents will " -"be unchanged to the minimum of the old and the new sizes." -msgstr "" - -#: ../../c-api/memory.rst:180 -msgid "" -"If *p* is ``NULL``, the call is equivalent to ``PyMem_RawMalloc(n)``; else " -"if *n* is equal to zero, the memory block is resized but is not freed, and " -"the returned pointer is non-``NULL``." -msgstr "" - -#: ../../c-api/memory.rst:184 -msgid "" -"Unless *p* is ``NULL``, it must have been returned by a previous call to :c:" -"func:`PyMem_RawMalloc`, :c:func:`PyMem_RawRealloc` or :c:func:" -"`PyMem_RawCalloc`." -msgstr "" - -#: ../../c-api/memory.rst:188 -msgid "" -"If the request fails, :c:func:`PyMem_RawRealloc` returns ``NULL`` and *p* " -"remains a valid pointer to the previous memory area." -msgstr "" - -#: ../../c-api/memory.rst:194 -msgid "" -"Frees the memory block pointed to by *p*, which must have been returned by a " -"previous call to :c:func:`PyMem_RawMalloc`, :c:func:`PyMem_RawRealloc` or :c:" -"func:`PyMem_RawCalloc`. Otherwise, or if ``PyMem_RawFree(p)`` has been " -"called before, undefined behavior occurs." -msgstr "" - -#: ../../c-api/memory.rst:199 ../../c-api/memory.rst:268 -#: ../../c-api/memory.rst:377 -msgid "If *p* is ``NULL``, no operation is performed." -msgstr "" - -#: ../../c-api/memory.rst:205 -msgid "Memory Interface" -msgstr "記憶體介面" - -#: ../../c-api/memory.rst:207 ../../c-api/memory.rst:314 -msgid "" -"The following function sets, modeled after the ANSI C standard, but " -"specifying behavior when requesting zero bytes, are available for allocating " -"and releasing memory from the Python heap." -msgstr "" - -#: ../../c-api/memory.rst:211 -msgid "" -"The :ref:`default memory allocator ` uses the :" -"ref:`pymalloc memory allocator `." -msgstr "" - -#: ../../c-api/memory.rst:216 ../../c-api/memory.rst:329 -msgid "" -"There must be an :term:`attached thread state` when using these functions." -msgstr "" - -#: ../../c-api/memory.rst:220 -msgid "" -"The default allocator is now pymalloc instead of system :c:func:`malloc`." -msgstr "" - -#: ../../c-api/memory.rst:227 -msgid "" -"Requesting zero bytes returns a distinct non-``NULL`` pointer if possible, " -"as if ``PyMem_Malloc(1)`` had been called instead. The memory will not have " -"been initialized in any way." -msgstr "" - -#: ../../c-api/memory.rst:238 -msgid "" -"Requesting zero elements or elements of size zero bytes returns a distinct " -"non-``NULL`` pointer if possible, as if ``PyMem_Calloc(1, 1)`` had been " -"called instead." -msgstr "" - -#: ../../c-api/memory.rst:250 -msgid "" -"If *p* is ``NULL``, the call is equivalent to ``PyMem_Malloc(n)``; else if " -"*n* is equal to zero, the memory block is resized but is not freed, and the " -"returned pointer is non-``NULL``." -msgstr "" - -#: ../../c-api/memory.rst:254 -msgid "" -"Unless *p* is ``NULL``, it must have been returned by a previous call to :c:" -"func:`PyMem_Malloc`, :c:func:`PyMem_Realloc` or :c:func:`PyMem_Calloc`." -msgstr "" - -#: ../../c-api/memory.rst:257 -msgid "" -"If the request fails, :c:func:`PyMem_Realloc` returns ``NULL`` and *p* " -"remains a valid pointer to the previous memory area." -msgstr "" - -#: ../../c-api/memory.rst:263 -msgid "" -"Frees the memory block pointed to by *p*, which must have been returned by a " -"previous call to :c:func:`PyMem_Malloc`, :c:func:`PyMem_Realloc` or :c:func:" -"`PyMem_Calloc`. Otherwise, or if ``PyMem_Free(p)`` has been called before, " -"undefined behavior occurs." -msgstr "" - -#: ../../c-api/memory.rst:270 -msgid "" -"The following type-oriented macros are provided for convenience. Note that " -"*TYPE* refers to any C type." -msgstr "" - -#: ../../c-api/memory.rst:276 -msgid "" -"Same as :c:func:`PyMem_Malloc`, but allocates ``(n * sizeof(TYPE))`` bytes " -"of memory. Returns a pointer cast to ``TYPE*``. The memory will not have " -"been initialized in any way." -msgstr "" - -#: ../../c-api/memory.rst:283 -msgid "" -"Same as :c:func:`PyMem_Realloc`, but the memory block is resized to ``(n * " -"sizeof(TYPE))`` bytes. Returns a pointer cast to ``TYPE*``. On return, *p* " -"will be a pointer to the new memory area, or ``NULL`` in the event of " -"failure." -msgstr "" - -#: ../../c-api/memory.rst:288 -msgid "" -"This is a C preprocessor macro; *p* is always reassigned. Save the original " -"value of *p* to avoid losing memory when handling errors." -msgstr "" - -#: ../../c-api/memory.rst:294 -msgid "Same as :c:func:`PyMem_Free`." -msgstr "和 :c:func:`PyMem_Free` 相同。" - -#: ../../c-api/memory.rst:296 -msgid "" -"In addition, the following macro sets are provided for calling the Python " -"memory allocator directly, without involving the C API functions listed " -"above. However, note that their use does not preserve binary compatibility " -"across Python versions and is therefore deprecated in extension modules." -msgstr "" - -#: ../../c-api/memory.rst:301 -msgid "``PyMem_MALLOC(size)``" -msgstr "``PyMem_MALLOC(size)``" - -#: ../../c-api/memory.rst:302 -msgid "``PyMem_NEW(type, size)``" -msgstr "``PyMem_NEW(type, size)``" - -#: ../../c-api/memory.rst:303 -msgid "``PyMem_REALLOC(ptr, size)``" -msgstr "``PyMem_REALLOC(ptr, size)``" - -#: ../../c-api/memory.rst:304 -msgid "``PyMem_RESIZE(ptr, type, size)``" -msgstr "``PyMem_RESIZE(ptr, type, size)``" - -#: ../../c-api/memory.rst:305 -msgid "``PyMem_FREE(ptr)``" -msgstr "``PyMem_FREE(ptr)``" - -#: ../../c-api/memory.rst:306 -msgid "``PyMem_DEL(ptr)``" -msgstr "``PyMem_DEL(ptr)``" - -#: ../../c-api/memory.rst:312 -msgid "Object allocators" -msgstr "" - -#: ../../c-api/memory.rst:319 -msgid "" -"There is no guarantee that the memory returned by these allocators can be " -"successfully cast to a Python object when intercepting the allocating " -"functions in this domain by the methods described in the :ref:`Customize " -"Memory Allocators ` section." -msgstr "" - -#: ../../c-api/memory.rst:324 -msgid "" -"The :ref:`default object allocator ` uses the :" -"ref:`pymalloc memory allocator `." -msgstr "" - -#: ../../c-api/memory.rst:336 -msgid "" -"Requesting zero bytes returns a distinct non-``NULL`` pointer if possible, " -"as if ``PyObject_Malloc(1)`` had been called instead. The memory will not " -"have been initialized in any way." -msgstr "" - -#: ../../c-api/memory.rst:347 -msgid "" -"Requesting zero elements or elements of size zero bytes returns a distinct " -"non-``NULL`` pointer if possible, as if ``PyObject_Calloc(1, 1)`` had been " -"called instead." -msgstr "" - -#: ../../c-api/memory.rst:359 -msgid "" -"If *p* is ``NULL``, the call is equivalent to ``PyObject_Malloc(n)``; else " -"if *n* is equal to zero, the memory block is resized but is not freed, and " -"the returned pointer is non-``NULL``." -msgstr "" - -#: ../../c-api/memory.rst:363 -msgid "" -"Unless *p* is ``NULL``, it must have been returned by a previous call to :c:" -"func:`PyObject_Malloc`, :c:func:`PyObject_Realloc` or :c:func:" -"`PyObject_Calloc`." -msgstr "" - -#: ../../c-api/memory.rst:366 -msgid "" -"If the request fails, :c:func:`PyObject_Realloc` returns ``NULL`` and *p* " -"remains a valid pointer to the previous memory area." -msgstr "" - -#: ../../c-api/memory.rst:372 -msgid "" -"Frees the memory block pointed to by *p*, which must have been returned by a " -"previous call to :c:func:`PyObject_Malloc`, :c:func:`PyObject_Realloc` or :c:" -"func:`PyObject_Calloc`. Otherwise, or if ``PyObject_Free(p)`` has been " -"called before, undefined behavior occurs." -msgstr "" - -#: ../../c-api/memory.rst:379 -msgid "" -"Do not call this directly to free an object's memory; call the type's :c:" -"member:`~PyTypeObject.tp_free` slot instead." -msgstr "" - -#: ../../c-api/memory.rst:382 -msgid "" -"Do not use this for memory allocated by :c:macro:`PyObject_GC_New` or :c:" -"macro:`PyObject_GC_NewVar`; use :c:func:`PyObject_GC_Del` instead." -msgstr "" - -#: ../../c-api/memory.rst:387 -msgid "" -":c:func:`PyObject_GC_Del` is the equivalent of this function for memory " -"allocated by types that support garbage collection." -msgstr "" - -#: ../../c-api/memory.rst:389 ../../c-api/memory.rst:486 -msgid ":c:func:`PyObject_Malloc`" -msgstr ":c:func:`PyObject_Malloc`" - -#: ../../c-api/memory.rst:390 ../../c-api/memory.rst:487 -msgid ":c:func:`PyObject_Realloc`" -msgstr ":c:func:`PyObject_Realloc`" - -#: ../../c-api/memory.rst:391 ../../c-api/memory.rst:488 -msgid ":c:func:`PyObject_Calloc`" -msgstr ":c:func:`PyObject_Calloc`" - -#: ../../c-api/memory.rst:392 -msgid ":c:macro:`PyObject_New`" -msgstr ":c:macro:`PyObject_New`" - -#: ../../c-api/memory.rst:393 -msgid ":c:macro:`PyObject_NewVar`" -msgstr ":c:macro:`PyObject_NewVar`" - -#: ../../c-api/memory.rst:394 -msgid ":c:func:`PyType_GenericAlloc`" -msgstr ":c:func:`PyType_GenericAlloc`" - -#: ../../c-api/memory.rst:395 -msgid ":c:member:`~PyTypeObject.tp_free`" -msgstr ":c:member:`~PyTypeObject.tp_free`" - -#: ../../c-api/memory.rst:401 -msgid "Default Memory Allocators" -msgstr "" - -#: ../../c-api/memory.rst:403 -msgid "Default memory allocators:" -msgstr "" - -#: ../../c-api/memory.rst:406 -msgid "Configuration" -msgstr "配置" - -#: ../../c-api/memory.rst:406 -msgid "Name" -msgstr "名稱" - -#: ../../c-api/memory.rst:406 -msgid "PyMem_RawMalloc" -msgstr "PyMem_RawMalloc" - -#: ../../c-api/memory.rst:406 -msgid "PyMem_Malloc" -msgstr "PyMem_Malloc" - -#: ../../c-api/memory.rst:406 -msgid "PyObject_Malloc" -msgstr "PyObject_Malloc" - -#: ../../c-api/memory.rst:408 -msgid "Release build" -msgstr "" - -#: ../../c-api/memory.rst:408 -msgid "``\"pymalloc\"``" -msgstr "``\"pymalloc\"``" - -#: ../../c-api/memory.rst:408 ../../c-api/memory.rst:410 -msgid "``malloc``" -msgstr "``malloc``" - -#: ../../c-api/memory.rst:408 -msgid "``pymalloc``" -msgstr "``pymalloc``" - -#: ../../c-api/memory.rst:409 -msgid "Debug build" -msgstr "" - -#: ../../c-api/memory.rst:409 -msgid "``\"pymalloc_debug\"``" -msgstr "``\"pymalloc_debug\"``" - -#: ../../c-api/memory.rst:409 ../../c-api/memory.rst:411 -msgid "``malloc`` + debug" -msgstr "" - -#: ../../c-api/memory.rst:409 -msgid "``pymalloc`` + debug" -msgstr "" - -#: ../../c-api/memory.rst:410 -msgid "Release build, without pymalloc" -msgstr "" - -#: ../../c-api/memory.rst:410 -msgid "``\"malloc\"``" -msgstr "``\"malloc\"``" - -#: ../../c-api/memory.rst:411 -msgid "Debug build, without pymalloc" -msgstr "" - -#: ../../c-api/memory.rst:411 -msgid "``\"malloc_debug\"``" -msgstr "``\"malloc_debug\"``" - -#: ../../c-api/memory.rst:414 -msgid "Legend:" -msgstr "" - -#: ../../c-api/memory.rst:416 -msgid "Name: value for :envvar:`PYTHONMALLOC` environment variable." -msgstr "" - -#: ../../c-api/memory.rst:417 -msgid "" -"``malloc``: system allocators from the standard C library, C functions: :c:" -"func:`malloc`, :c:func:`calloc`, :c:func:`realloc` and :c:func:`free`." -msgstr "" - -#: ../../c-api/memory.rst:419 -msgid "``pymalloc``: :ref:`pymalloc memory allocator `." -msgstr "" - -#: ../../c-api/memory.rst:420 -msgid "" -"``mimalloc``: :ref:`mimalloc memory allocator `. The pymalloc " -"allocator will be used if mimalloc support isn't available." -msgstr "" - -#: ../../c-api/memory.rst:422 -msgid "" -"\"+ debug\": with :ref:`debug hooks on the Python memory allocators `." -msgstr "" - -#: ../../c-api/memory.rst:424 -msgid "\"Debug build\": :ref:`Python build in debug mode `." -msgstr "" - -#: ../../c-api/memory.rst:429 -msgid "Customize Memory Allocators" -msgstr "" - -#: ../../c-api/memory.rst:435 -msgid "" -"Structure used to describe a memory block allocator. The structure has the " -"following fields:" -msgstr "" - -#: ../../c-api/memory.rst:439 ../../c-api/memory.rst:690 -msgid "Field" -msgstr "欄位" - -#: ../../c-api/memory.rst:439 ../../c-api/memory.rst:690 -msgid "Meaning" -msgstr "意義" - -#: ../../c-api/memory.rst:441 ../../c-api/memory.rst:692 -msgid "``void *ctx``" -msgstr "``void *ctx``" - -#: ../../c-api/memory.rst:441 ../../c-api/memory.rst:692 -msgid "user context passed as first argument" -msgstr "" - -#: ../../c-api/memory.rst:443 -msgid "``void* malloc(void *ctx, size_t size)``" -msgstr "``void* malloc(void *ctx, size_t size)``" - -#: ../../c-api/memory.rst:443 -msgid "allocate a memory block" -msgstr "" - -#: ../../c-api/memory.rst:445 -msgid "``void* calloc(void *ctx, size_t nelem, size_t elsize)``" -msgstr "``void* calloc(void *ctx, size_t nelem, size_t elsize)``" - -#: ../../c-api/memory.rst:445 -msgid "allocate a memory block initialized with zeros" -msgstr "" - -#: ../../c-api/memory.rst:448 -msgid "``void* realloc(void *ctx, void *ptr, size_t new_size)``" -msgstr "``void* realloc(void *ctx, void *ptr, size_t new_size)``" - -#: ../../c-api/memory.rst:448 -msgid "allocate or resize a memory block" -msgstr "" - -#: ../../c-api/memory.rst:450 -msgid "``void free(void *ctx, void *ptr)``" -msgstr "``void free(void *ctx, void *ptr)``" - -#: ../../c-api/memory.rst:450 -msgid "free a memory block" -msgstr "" - -#: ../../c-api/memory.rst:453 -msgid "" -"The :c:type:`!PyMemAllocator` structure was renamed to :c:type:" -"`PyMemAllocatorEx` and a new ``calloc`` field was added." -msgstr "" - -#: ../../c-api/memory.rst:460 -msgid "Enum used to identify an allocator domain. Domains:" -msgstr "" - -#: ../../c-api/memory.rst:466 ../../c-api/memory.rst:475 -#: ../../c-api/memory.rst:484 -msgid "Functions:" -msgstr "函式：" - -#: ../../c-api/memory.rst:468 -msgid ":c:func:`PyMem_RawMalloc`" -msgstr ":c:func:`PyMem_RawMalloc`" - -#: ../../c-api/memory.rst:469 -msgid ":c:func:`PyMem_RawRealloc`" -msgstr ":c:func:`PyMem_RawRealloc`" - -#: ../../c-api/memory.rst:470 -msgid ":c:func:`PyMem_RawCalloc`" -msgstr ":c:func:`PyMem_RawCalloc`" - -#: ../../c-api/memory.rst:471 -msgid ":c:func:`PyMem_RawFree`" -msgstr ":c:func:`PyMem_RawFree`" - -#: ../../c-api/memory.rst:477 -msgid ":c:func:`PyMem_Malloc`," -msgstr ":c:func:`PyMem_Malloc`," - -#: ../../c-api/memory.rst:478 -msgid ":c:func:`PyMem_Realloc`" -msgstr ":c:func:`PyMem_Realloc`" - -#: ../../c-api/memory.rst:479 -msgid ":c:func:`PyMem_Calloc`" -msgstr ":c:func:`PyMem_Calloc`" - -#: ../../c-api/memory.rst:480 -msgid ":c:func:`PyMem_Free`" -msgstr ":c:func:`PyMem_Free`" - -#: ../../c-api/memory.rst:489 -msgid ":c:func:`PyObject_Free`" -msgstr ":c:func:`PyObject_Free`" - -#: ../../c-api/memory.rst:493 -msgid "Get the memory block allocator of the specified domain." -msgstr "" - -#: ../../c-api/memory.rst:498 -msgid "Set the memory block allocator of the specified domain." -msgstr "" - -#: ../../c-api/memory.rst:500 -msgid "" -"The new allocator must return a distinct non-``NULL`` pointer when " -"requesting zero bytes." -msgstr "" - -#: ../../c-api/memory.rst:503 -msgid "" -"For the :c:macro:`PYMEM_DOMAIN_RAW` domain, the allocator must be thread-" -"safe: a :term:`thread state` is not :term:`attached ` " -"when the allocator is called." -msgstr "" - -#: ../../c-api/memory.rst:507 -msgid "" -"For the remaining domains, the allocator must also be thread-safe: the " -"allocator may be called in different interpreters that do not share a :term:" -"`GIL`." -msgstr "" - -#: ../../c-api/memory.rst:511 -msgid "" -"If the new allocator is not a hook (does not call the previous allocator), " -"the :c:func:`PyMem_SetupDebugHooks` function must be called to reinstall the " -"debug hooks on top on the new allocator." -msgstr "" - -#: ../../c-api/memory.rst:515 -msgid "" -"See also :c:member:`PyPreConfig.allocator` and :ref:`Preinitialize Python " -"with PyPreConfig `." -msgstr "" - -#: ../../c-api/memory.rst:520 -msgid ":c:func:`PyMem_SetAllocator` does have the following contract:" -msgstr "" - -#: ../../c-api/memory.rst:522 -msgid "" -"It can be called after :c:func:`Py_PreInitialize` and before :c:func:" -"`Py_InitializeFromConfig` to install a custom memory allocator. There are no " -"restrictions over the installed allocator other than the ones imposed by the " -"domain (for instance, the Raw Domain allows the allocator to be called " -"without an :term:`attached thread state`). See :ref:`the section on " -"allocator domains ` for more information." -msgstr "" - -#: ../../c-api/memory.rst:530 -msgid "" -"If called after Python has finish initializing (after :c:func:" -"`Py_InitializeFromConfig` has been called) the allocator **must** wrap the " -"existing allocator. Substituting the current allocator for some other " -"arbitrary one is **not supported**." -msgstr "" - -#: ../../c-api/memory.rst:535 -msgid "All allocators must be thread-safe." -msgstr "" - -#: ../../c-api/memory.rst:541 -msgid "" -"Setup :ref:`debug hooks in the Python memory allocators ` " -"to detect memory errors." -msgstr "" - -#: ../../c-api/memory.rst:548 -msgid "Debug hooks on the Python memory allocators" -msgstr "" - -#: ../../c-api/memory.rst:550 -msgid "" -"When :ref:`Python is built in debug mode `, the :c:func:" -"`PyMem_SetupDebugHooks` function is called at the :ref:`Python " -"preinitialization ` to setup debug hooks on Python memory " -"allocators to detect memory errors." -msgstr "" - -#: ../../c-api/memory.rst:555 -msgid "" -"The :envvar:`PYTHONMALLOC` environment variable can be used to install debug " -"hooks on a Python compiled in release mode (ex: ``PYTHONMALLOC=debug``)." -msgstr "" - -#: ../../c-api/memory.rst:558 -msgid "" -"The :c:func:`PyMem_SetupDebugHooks` function can be used to set debug hooks " -"after calling :c:func:`PyMem_SetAllocator`." -msgstr "" - -#: ../../c-api/memory.rst:561 -msgid "" -"These debug hooks fill dynamically allocated memory blocks with special, " -"recognizable bit patterns. Newly allocated memory is filled with the byte " -"``0xCD`` (``PYMEM_CLEANBYTE``), freed memory is filled with the byte " -"``0xDD`` (``PYMEM_DEADBYTE``). Memory blocks are surrounded by \"forbidden " -"bytes\" filled with the byte ``0xFD`` (``PYMEM_FORBIDDENBYTE``). Strings of " -"these bytes are unlikely to be valid addresses, floats, or ASCII strings." -msgstr "" - -#: ../../c-api/memory.rst:568 -msgid "Runtime checks:" -msgstr "Runtime 檢查：" - -#: ../../c-api/memory.rst:570 -msgid "" -"Detect API violations. For example, detect if :c:func:`PyObject_Free` is " -"called on a memory block allocated by :c:func:`PyMem_Malloc`." -msgstr "" - -#: ../../c-api/memory.rst:572 -msgid "Detect write before the start of the buffer (buffer underflow)." -msgstr "" - -#: ../../c-api/memory.rst:573 -msgid "Detect write after the end of the buffer (buffer overflow)." -msgstr "" - -#: ../../c-api/memory.rst:574 -msgid "" -"Check that there is an :term:`attached thread state` when allocator " -"functions of :c:macro:`PYMEM_DOMAIN_OBJ` (ex: :c:func:`PyObject_Malloc`) " -"and :c:macro:`PYMEM_DOMAIN_MEM` (ex: :c:func:`PyMem_Malloc`) domains are " -"called." -msgstr "" - -#: ../../c-api/memory.rst:579 -msgid "" -"On error, the debug hooks use the :mod:`tracemalloc` module to get the " -"traceback where a memory block was allocated. The traceback is only " -"displayed if :mod:`tracemalloc` is tracing Python memory allocations and the " -"memory block was traced." -msgstr "" - -#: ../../c-api/memory.rst:584 -msgid "" -"Let *S* = ``sizeof(size_t)``. ``2*S`` bytes are added at each end of each " -"block of *N* bytes requested. The memory layout is like so, where p " -"represents the address returned by a malloc-like or realloc-like function " -"(``p[i:j]`` means the slice of bytes from ``*(p+i)`` inclusive up to " -"``*(p+j)`` exclusive; note that the treatment of negative indices differs " -"from a Python slice):" -msgstr "" - -#: ../../c-api/memory.rst:590 -msgid "``p[-2*S:-S]``" -msgstr "``p[-2*S:-S]``" - -#: ../../c-api/memory.rst:591 -msgid "" -"Number of bytes originally asked for. This is a size_t, big-endian (easier " -"to read in a memory dump)." -msgstr "" - -#: ../../c-api/memory.rst:593 -msgid "``p[-S]``" -msgstr "``p[-S]``" - -#: ../../c-api/memory.rst:594 -msgid "API identifier (ASCII character):" -msgstr "" - -#: ../../c-api/memory.rst:596 -msgid "``'r'`` for :c:macro:`PYMEM_DOMAIN_RAW`." -msgstr "" - -#: ../../c-api/memory.rst:597 -msgid "``'m'`` for :c:macro:`PYMEM_DOMAIN_MEM`." -msgstr "" - -#: ../../c-api/memory.rst:598 -msgid "``'o'`` for :c:macro:`PYMEM_DOMAIN_OBJ`." -msgstr "" - -#: ../../c-api/memory.rst:600 -msgid "``p[-S+1:0]``" -msgstr "``p[-S+1:0]``" - -#: ../../c-api/memory.rst:601 -msgid "Copies of PYMEM_FORBIDDENBYTE. Used to catch under- writes and reads." -msgstr "" - -#: ../../c-api/memory.rst:603 -msgid "``p[0:N]``" -msgstr "``p[0:N]``" - -#: ../../c-api/memory.rst:604 -msgid "" -"The requested memory, filled with copies of PYMEM_CLEANBYTE, used to catch " -"reference to uninitialized memory. When a realloc-like function is called " -"requesting a larger memory block, the new excess bytes are also filled with " -"PYMEM_CLEANBYTE. When a free-like function is called, these are overwritten " -"with PYMEM_DEADBYTE, to catch reference to freed memory. When a realloc- " -"like function is called requesting a smaller memory block, the excess old " -"bytes are also filled with PYMEM_DEADBYTE." -msgstr "" - -#: ../../c-api/memory.rst:612 -msgid "``p[N:N+S]``" -msgstr "``p[N:N+S]``" - -#: ../../c-api/memory.rst:613 -msgid "Copies of PYMEM_FORBIDDENBYTE. Used to catch over- writes and reads." -msgstr "" - -#: ../../c-api/memory.rst:615 -msgid "``p[N+S:N+2*S]``" -msgstr "``p[N+S:N+2*S]``" - -#: ../../c-api/memory.rst:616 -msgid "" -"Only used if the ``PYMEM_DEBUG_SERIALNO`` macro is defined (not defined by " -"default)." -msgstr "" - -#: ../../c-api/memory.rst:619 -msgid "" -"A serial number, incremented by 1 on each call to a malloc-like or realloc-" -"like function. Big-endian :c:type:`size_t`. If \"bad memory\" is detected " -"later, the serial number gives an excellent way to set a breakpoint on the " -"next run, to capture the instant at which this block was passed out. The " -"static function bumpserialno() in obmalloc.c is the only place the serial " -"number is incremented, and exists so you can set such a breakpoint easily." -msgstr "" - -#: ../../c-api/memory.rst:626 -msgid "" -"A realloc-like or free-like function first checks that the " -"PYMEM_FORBIDDENBYTE bytes at each end are intact. If they've been altered, " -"diagnostic output is written to stderr, and the program is aborted via " -"Py_FatalError(). The other main failure mode is provoking a memory error " -"when a program reads up one of the special bit patterns and tries to use it " -"as an address. If you get in a debugger then and look at the object, you're " -"likely to see that it's entirely filled with PYMEM_DEADBYTE (meaning freed " -"memory is getting used) or PYMEM_CLEANBYTE (meaning uninitialized memory is " -"getting used)." -msgstr "" - -#: ../../c-api/memory.rst:635 -msgid "" -"The :c:func:`PyMem_SetupDebugHooks` function now also works on Python " -"compiled in release mode. On error, the debug hooks now use :mod:" -"`tracemalloc` to get the traceback where a memory block was allocated. The " -"debug hooks now also check if there is an :term:`attached thread state` when " -"functions of :c:macro:`PYMEM_DOMAIN_OBJ` and :c:macro:`PYMEM_DOMAIN_MEM` " -"domains are called." -msgstr "" - -#: ../../c-api/memory.rst:643 -msgid "" -"Byte patterns ``0xCB`` (``PYMEM_CLEANBYTE``), ``0xDB`` (``PYMEM_DEADBYTE``) " -"and ``0xFB`` (``PYMEM_FORBIDDENBYTE``) have been replaced with ``0xCD``, " -"``0xDD`` and ``0xFD`` to use the same values than Windows CRT debug " -"``malloc()`` and ``free()``." -msgstr "" - -#: ../../c-api/memory.rst:653 -msgid "The pymalloc allocator" -msgstr "" - -#: ../../c-api/memory.rst:655 -msgid "" -"Python has a *pymalloc* allocator optimized for small objects (smaller or " -"equal to 512 bytes) with a short lifetime. It uses memory mappings called " -"\"arenas\" with a fixed size of either 256 KiB on 32-bit platforms or 1 MiB " -"on 64-bit platforms. It falls back to :c:func:`PyMem_RawMalloc` and :c:func:" -"`PyMem_RawRealloc` for allocations larger than 512 bytes." -msgstr "" - -#: ../../c-api/memory.rst:661 -msgid "" -"*pymalloc* is the :ref:`default allocator ` of " -"the :c:macro:`PYMEM_DOMAIN_MEM` (ex: :c:func:`PyMem_Malloc`) and :c:macro:" -"`PYMEM_DOMAIN_OBJ` (ex: :c:func:`PyObject_Malloc`) domains." -msgstr "" - -#: ../../c-api/memory.rst:665 -msgid "The arena allocator uses the following functions:" -msgstr "" - -#: ../../c-api/memory.rst:667 -msgid ":c:func:`!VirtualAlloc` and :c:func:`!VirtualFree` on Windows," -msgstr "Windows 上的 :c:func:`!VirtualAlloc` 和 :c:func:`!VirtualFree`，" - -#: ../../c-api/memory.rst:668 -msgid ":c:func:`!mmap` and :c:func:`!munmap` if available," -msgstr "如果可用，則使用 :c:func:`!mmap` 和 :c:func:`!munmap`，" - -#: ../../c-api/memory.rst:669 -msgid ":c:func:`malloc` and :c:func:`free` otherwise." -msgstr "否則使用 :c:func:`malloc` 和 :c:func:`free`。" - -#: ../../c-api/memory.rst:671 -msgid "" -"This allocator is disabled if Python is configured with the :option:`--" -"without-pymalloc` option. It can also be disabled at runtime using the :" -"envvar:`PYTHONMALLOC` environment variable (ex: ``PYTHONMALLOC=malloc``)." -msgstr "" - -#: ../../c-api/memory.rst:675 -msgid "" -"Typically, it makes sense to disable the pymalloc allocator when building " -"Python with AddressSanitizer (:option:`--with-address-sanitizer`) which " -"helps uncover low level bugs within the C code." -msgstr "" - -#: ../../c-api/memory.rst:680 -msgid "Customize pymalloc Arena Allocator" -msgstr "" - -#: ../../c-api/memory.rst:686 -msgid "" -"Structure used to describe an arena allocator. The structure has three " -"fields:" -msgstr "" - -#: ../../c-api/memory.rst:694 -msgid "``void* alloc(void *ctx, size_t size)``" -msgstr "``void* alloc(void *ctx, size_t size)``" - -#: ../../c-api/memory.rst:694 -msgid "allocate an arena of size bytes" -msgstr "" - -#: ../../c-api/memory.rst:696 -msgid "``void free(void *ctx, void *ptr, size_t size)``" -msgstr "``void free(void *ctx, void *ptr, size_t size)``" - -#: ../../c-api/memory.rst:696 -msgid "free an arena" -msgstr "" - -#: ../../c-api/memory.rst:701 -msgid "Get the arena allocator." -msgstr "" - -#: ../../c-api/memory.rst:705 -msgid "Set the arena allocator." -msgstr "" - -#: ../../c-api/memory.rst:710 -msgid "The mimalloc allocator" -msgstr "" - -#: ../../c-api/memory.rst:714 -msgid "" -"Python supports the mimalloc allocator when the underlying platform support " -"is available. mimalloc \"is a general purpose allocator with excellent " -"performance characteristics. Initially developed by Daan Leijen for the " -"runtime systems of the Koka and Lean languages.\"" -msgstr "" - -#: ../../c-api/memory.rst:719 -msgid "tracemalloc C API" -msgstr "" - -#: ../../c-api/memory.rst:725 -msgid "Track an allocated memory block in the :mod:`tracemalloc` module." -msgstr "" - -#: ../../c-api/memory.rst:727 -msgid "" -"Return ``0`` on success, return ``-1`` on error (failed to allocate memory " -"to store the trace). Return ``-2`` if tracemalloc is disabled." -msgstr "" - -#: ../../c-api/memory.rst:730 -msgid "If memory block is already tracked, update the existing trace." -msgstr "" - -#: ../../c-api/memory.rst:734 -msgid "" -"Untrack an allocated memory block in the :mod:`tracemalloc` module. Do " -"nothing if the block was not tracked." -msgstr "" - -#: ../../c-api/memory.rst:737 -msgid "Return ``-2`` if tracemalloc is disabled, otherwise return ``0``." -msgstr "" - -#: ../../c-api/memory.rst:743 -msgid "Examples" -msgstr "範例" - -#: ../../c-api/memory.rst:745 -msgid "" -"Here is the example from section :ref:`memoryoverview`, rewritten so that " -"the I/O buffer is allocated from the Python heap by using the first function " -"set::" -msgstr "" - -#: ../../c-api/memory.rst:748 -msgid "" -"PyObject *res;\n" -"char *buf = (char *) PyMem_Malloc(BUFSIZ); /* for I/O */\n" -"\n" -"if (buf == NULL)\n" -" return PyErr_NoMemory();\n" -"/* ...Do some I/O operation involving buf... */\n" -"res = PyBytes_FromString(buf);\n" -"PyMem_Free(buf); /* allocated with PyMem_Malloc */\n" -"return res;" -msgstr "" - -#: ../../c-api/memory.rst:758 -msgid "The same code using the type-oriented function set::" -msgstr "" - -#: ../../c-api/memory.rst:760 -msgid "" -"PyObject *res;\n" -"char *buf = PyMem_New(char, BUFSIZ); /* for I/O */\n" -"\n" -"if (buf == NULL)\n" -" return PyErr_NoMemory();\n" -"/* ...Do some I/O operation involving buf... */\n" -"res = PyBytes_FromString(buf);\n" -"PyMem_Free(buf); /* allocated with PyMem_New */\n" -"return res;" -msgstr "" - -#: ../../c-api/memory.rst:770 -msgid "" -"Note that in the two examples above, the buffer is always manipulated via " -"functions belonging to the same set. Indeed, it is required to use the same " -"memory API family for a given memory block, so that the risk of mixing " -"different allocators is reduced to a minimum. The following code sequence " -"contains two errors, one of which is labeled as *fatal* because it mixes two " -"different allocators operating on different heaps. ::" -msgstr "" - -#: ../../c-api/memory.rst:777 -msgid "" -"char *buf1 = PyMem_New(char, BUFSIZ);\n" -"char *buf2 = (char *) malloc(BUFSIZ);\n" -"char *buf3 = (char *) PyMem_Malloc(BUFSIZ);\n" -"...\n" -"PyMem_Del(buf3); /* Wrong -- should be PyMem_Free() */\n" -"free(buf2); /* Right -- allocated via malloc() */\n" -"free(buf1); /* Fatal -- should be PyMem_Free() */" -msgstr "" - -#: ../../c-api/memory.rst:785 -msgid "" -"In addition to the functions aimed at handling raw memory blocks from the " -"Python heap, objects in Python are allocated and released with :c:macro:" -"`PyObject_New`, :c:macro:`PyObject_NewVar` and :c:func:`PyObject_Free`." -msgstr "" - -#: ../../c-api/memory.rst:789 -msgid "" -"These will be explained in the next chapter on defining and implementing new " -"object types in C." -msgstr "" - -#: ../../c-api/memory.rst:43 -msgid "malloc (C function)" -msgstr "malloc（C 函式）" - -#: ../../c-api/memory.rst:43 -msgid "calloc (C function)" -msgstr "calloc（C 函式）" - -#: ../../c-api/memory.rst:43 -msgid "realloc (C function)" -msgstr "realloc（C 函式）" - -#: ../../c-api/memory.rst:43 -msgid "free (C function)" -msgstr "free（C 函式）" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Ching-Lung Chuang, 2015 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-05 00:16+0000\n" +"PO-Revision-Date: 2018-05-23 14:06+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" + +#: ../../c-api/memory.rst:8 +msgid "Memory Management" +msgstr "記憶體管理" + +#: ../../c-api/memory.rst:17 +msgid "Overview" +msgstr "總覽" + +#: ../../c-api/memory.rst:19 +msgid "" +"Memory management in Python involves a private heap containing all Python " +"objects and data structures. The management of this private heap is ensured " +"internally by the *Python memory manager*. The Python memory manager has " +"different components which deal with various dynamic storage management " +"aspects, like sharing, segmentation, preallocation or caching." +msgstr "" + +#: ../../c-api/memory.rst:25 +msgid "" +"At the lowest level, a raw memory allocator ensures that there is enough " +"room in the private heap for storing all Python-related data by interacting " +"with the memory manager of the operating system. On top of the raw memory " +"allocator, several object-specific allocators operate on the same heap and " +"implement distinct memory management policies adapted to the peculiarities " +"of every object type. For example, integer objects are managed differently " +"within the heap than strings, tuples or dictionaries because integers imply " +"different storage requirements and speed/space tradeoffs. The Python memory " +"manager thus delegates some of the work to the object-specific allocators, " +"but ensures that the latter operate within the bounds of the private heap." +msgstr "" + +#: ../../c-api/memory.rst:36 +msgid "" +"It is important to understand that the management of the Python heap is " +"performed by the interpreter itself and that the user has no control over " +"it, even if they regularly manipulate object pointers to memory blocks " +"inside that heap. The allocation of heap space for Python objects and other " +"internal buffers is performed on demand by the Python memory manager through " +"the Python/C API functions listed in this document." +msgstr "" + +#: ../../c-api/memory.rst:49 +msgid "" +"To avoid memory corruption, extension writers should never try to operate on " +"Python objects with the functions exported by the C library: :c:func:" +"`malloc`, :c:func:`calloc`, :c:func:`realloc` and :c:func:`free`. This will " +"result in mixed calls between the C allocator and the Python memory manager " +"with fatal consequences, because they implement different algorithms and " +"operate on different heaps. However, one may safely allocate and release " +"memory blocks with the C library allocator for individual purposes, as shown " +"in the following example::" +msgstr "" + +#: ../../c-api/memory.rst:58 +msgid "" +"PyObject *res;\n" +"char *buf = (char *) malloc(BUFSIZ); /* for I/O */\n" +"\n" +"if (buf == NULL)\n" +" return PyErr_NoMemory();\n" +"...Do some I/O operation involving buf...\n" +"res = PyBytes_FromString(buf);\n" +"free(buf); /* malloc'ed */\n" +"return res;" +msgstr "" + +#: ../../c-api/memory.rst:68 +msgid "" +"In this example, the memory request for the I/O buffer is handled by the C " +"library allocator. The Python memory manager is involved only in the " +"allocation of the bytes object returned as a result." +msgstr "" + +#: ../../c-api/memory.rst:72 +msgid "" +"In most situations, however, it is recommended to allocate memory from the " +"Python heap specifically because the latter is under control of the Python " +"memory manager. For example, this is required when the interpreter is " +"extended with new object types written in C. Another reason for using the " +"Python heap is the desire to *inform* the Python memory manager about the " +"memory needs of the extension module. Even when the requested memory is used " +"exclusively for internal, highly specific purposes, delegating all memory " +"requests to the Python memory manager causes the interpreter to have a more " +"accurate image of its memory footprint as a whole. Consequently, under " +"certain circumstances, the Python memory manager may or may not trigger " +"appropriate actions, like garbage collection, memory compaction or other " +"preventive procedures. Note that by using the C library allocator as shown " +"in the previous example, the allocated memory for the I/O buffer escapes " +"completely the Python memory manager." +msgstr "" + +#: ../../c-api/memory.rst:88 +msgid "" +"The :envvar:`PYTHONMALLOC` environment variable can be used to configure the " +"memory allocators used by Python." +msgstr "" + +#: ../../c-api/memory.rst:91 +msgid "" +"The :envvar:`PYTHONMALLOCSTATS` environment variable can be used to print " +"statistics of the :ref:`pymalloc memory allocator ` every time a " +"new pymalloc object arena is created, and on shutdown." +msgstr "" + +#: ../../c-api/memory.rst:96 +msgid "Allocator Domains" +msgstr "" + +#: ../../c-api/memory.rst:100 +msgid "" +"All allocating functions belong to one of three different \"domains\" (see " +"also :c:type:`PyMemAllocatorDomain`). These domains represent different " +"allocation strategies and are optimized for different purposes. The specific " +"details on how every domain allocates memory or what internal functions each " +"domain calls is considered an implementation detail, but for debugging " +"purposes a simplified table can be found at :ref:`default-memory-" +"allocators`. The APIs used to allocate and free a block of memory must be " +"from the same domain. For example, :c:func:`PyMem_Free` must be used to free " +"memory allocated using :c:func:`PyMem_Malloc`." +msgstr "" + +#: ../../c-api/memory.rst:109 +msgid "The three allocation domains are:" +msgstr "" + +#: ../../c-api/memory.rst:111 +msgid "" +"Raw domain: intended for allocating memory for general-purpose memory " +"buffers where the allocation *must* go to the system allocator or where the " +"allocator can operate without an :term:`attached thread state`. The memory " +"is requested directly from the system. See :ref:`Raw Memory Interface `." +msgstr "" + +#: ../../c-api/memory.rst:116 +msgid "" +"\"Mem\" domain: intended for allocating memory for Python buffers and " +"general-purpose memory buffers where the allocation must be performed with " +"an :term:`attached thread state`. The memory is taken from the Python " +"private heap. See :ref:`Memory Interface `." +msgstr "" + +#: ../../c-api/memory.rst:121 +msgid "" +"Object domain: intended for allocating memory for Python objects. The memory " +"is taken from the Python private heap. See :ref:`Object allocators " +"`." +msgstr "" + +#: ../../c-api/memory.rst:126 +msgid "" +"The :term:`free-threaded ` build requires that only Python " +"objects are allocated using the \"object\" domain and that all Python " +"objects are allocated using that domain. This differs from the prior Python " +"versions, where this was only a best practice and not a hard requirement." +msgstr "" + +#: ../../c-api/memory.rst:130 +msgid "" +"For example, buffers (non-Python objects) should be allocated using :c:func:" +"`PyMem_Malloc`, :c:func:`PyMem_RawMalloc`, or :c:func:`malloc`, but not :c:" +"func:`PyObject_Malloc`." +msgstr "" + +#: ../../c-api/memory.rst:133 +msgid "See :ref:`Memory Allocation APIs `." +msgstr "" + +#: ../../c-api/memory.rst:139 +msgid "Raw Memory Interface" +msgstr "" + +#: ../../c-api/memory.rst:141 +msgid "" +"The following function sets are wrappers to the system allocator. These " +"functions are thread-safe, so a :term:`thread state` does not need to be :" +"term:`attached `." +msgstr "" + +#: ../../c-api/memory.rst:145 +msgid "" +"The :ref:`default raw memory allocator ` uses the " +"following functions: :c:func:`malloc`, :c:func:`calloc`, :c:func:`realloc` " +"and :c:func:`!free`; call ``malloc(1)`` (or ``calloc(1, 1)``) when " +"requesting zero bytes." +msgstr "" + +#: ../../c-api/memory.rst:154 ../../c-api/memory.rst:224 +#: ../../c-api/memory.rst:333 +msgid "" +"Allocates *n* bytes and returns a pointer of type :c:expr:`void*` to the " +"allocated memory, or ``NULL`` if the request fails." +msgstr "" + +#: ../../c-api/memory.rst:157 +msgid "" +"Requesting zero bytes returns a distinct non-``NULL`` pointer if possible, " +"as if ``PyMem_RawMalloc(1)`` had been called instead. The memory will not " +"have been initialized in any way." +msgstr "" + +#: ../../c-api/memory.rst:164 ../../c-api/memory.rst:234 +#: ../../c-api/memory.rst:343 +msgid "" +"Allocates *nelem* elements each whose size in bytes is *elsize* and returns " +"a pointer of type :c:expr:`void*` to the allocated memory, or ``NULL`` if " +"the request fails. The memory is initialized to zeros." +msgstr "" + +#: ../../c-api/memory.rst:168 +msgid "" +"Requesting zero elements or elements of size zero bytes returns a distinct " +"non-``NULL`` pointer if possible, as if ``PyMem_RawCalloc(1, 1)`` had been " +"called instead." +msgstr "" + +#: ../../c-api/memory.rst:177 ../../c-api/memory.rst:247 +#: ../../c-api/memory.rst:356 +msgid "" +"Resizes the memory block pointed to by *p* to *n* bytes. The contents will " +"be unchanged to the minimum of the old and the new sizes." +msgstr "" + +#: ../../c-api/memory.rst:180 +msgid "" +"If *p* is ``NULL``, the call is equivalent to ``PyMem_RawMalloc(n)``; else " +"if *n* is equal to zero, the memory block is resized but is not freed, and " +"the returned pointer is non-``NULL``." +msgstr "" + +#: ../../c-api/memory.rst:184 +msgid "" +"Unless *p* is ``NULL``, it must have been returned by a previous call to :c:" +"func:`PyMem_RawMalloc`, :c:func:`PyMem_RawRealloc` or :c:func:" +"`PyMem_RawCalloc`." +msgstr "" + +#: ../../c-api/memory.rst:188 +msgid "" +"If the request fails, :c:func:`PyMem_RawRealloc` returns ``NULL`` and *p* " +"remains a valid pointer to the previous memory area." +msgstr "" + +#: ../../c-api/memory.rst:194 +msgid "" +"Frees the memory block pointed to by *p*, which must have been returned by a " +"previous call to :c:func:`PyMem_RawMalloc`, :c:func:`PyMem_RawRealloc` or :c:" +"func:`PyMem_RawCalloc`. Otherwise, or if ``PyMem_RawFree(p)`` has been " +"called before, undefined behavior occurs." +msgstr "" + +#: ../../c-api/memory.rst:199 ../../c-api/memory.rst:268 +#: ../../c-api/memory.rst:377 +msgid "If *p* is ``NULL``, no operation is performed." +msgstr "" + +#: ../../c-api/memory.rst:205 +msgid "Memory Interface" +msgstr "記憶體介面" + +#: ../../c-api/memory.rst:207 ../../c-api/memory.rst:314 +msgid "" +"The following function sets, modeled after the ANSI C standard, but " +"specifying behavior when requesting zero bytes, are available for allocating " +"and releasing memory from the Python heap." +msgstr "" + +#: ../../c-api/memory.rst:211 +msgid "" +"The :ref:`default memory allocator ` uses the :" +"ref:`pymalloc memory allocator `." +msgstr "" + +#: ../../c-api/memory.rst:216 ../../c-api/memory.rst:329 +msgid "" +"There must be an :term:`attached thread state` when using these functions." +msgstr "" + +#: ../../c-api/memory.rst:220 +msgid "" +"The default allocator is now pymalloc instead of system :c:func:`malloc`." +msgstr "" + +#: ../../c-api/memory.rst:227 +msgid "" +"Requesting zero bytes returns a distinct non-``NULL`` pointer if possible, " +"as if ``PyMem_Malloc(1)`` had been called instead. The memory will not have " +"been initialized in any way." +msgstr "" + +#: ../../c-api/memory.rst:238 +msgid "" +"Requesting zero elements or elements of size zero bytes returns a distinct " +"non-``NULL`` pointer if possible, as if ``PyMem_Calloc(1, 1)`` had been " +"called instead." +msgstr "" + +#: ../../c-api/memory.rst:250 +msgid "" +"If *p* is ``NULL``, the call is equivalent to ``PyMem_Malloc(n)``; else if " +"*n* is equal to zero, the memory block is resized but is not freed, and the " +"returned pointer is non-``NULL``." +msgstr "" + +#: ../../c-api/memory.rst:254 +msgid "" +"Unless *p* is ``NULL``, it must have been returned by a previous call to :c:" +"func:`PyMem_Malloc`, :c:func:`PyMem_Realloc` or :c:func:`PyMem_Calloc`." +msgstr "" + +#: ../../c-api/memory.rst:257 +msgid "" +"If the request fails, :c:func:`PyMem_Realloc` returns ``NULL`` and *p* " +"remains a valid pointer to the previous memory area." +msgstr "" + +#: ../../c-api/memory.rst:263 +msgid "" +"Frees the memory block pointed to by *p*, which must have been returned by a " +"previous call to :c:func:`PyMem_Malloc`, :c:func:`PyMem_Realloc` or :c:func:" +"`PyMem_Calloc`. Otherwise, or if ``PyMem_Free(p)`` has been called before, " +"undefined behavior occurs." +msgstr "" + +#: ../../c-api/memory.rst:270 +msgid "" +"The following type-oriented macros are provided for convenience. Note that " +"*TYPE* refers to any C type." +msgstr "" + +#: ../../c-api/memory.rst:276 +msgid "" +"Same as :c:func:`PyMem_Malloc`, but allocates ``(n * sizeof(TYPE))`` bytes " +"of memory. Returns a pointer cast to ``TYPE*``. The memory will not have " +"been initialized in any way." +msgstr "" + +#: ../../c-api/memory.rst:283 +msgid "" +"Same as :c:func:`PyMem_Realloc`, but the memory block is resized to ``(n * " +"sizeof(TYPE))`` bytes. Returns a pointer cast to ``TYPE*``. On return, *p* " +"will be a pointer to the new memory area, or ``NULL`` in the event of " +"failure." +msgstr "" + +#: ../../c-api/memory.rst:288 +msgid "" +"This is a C preprocessor macro; *p* is always reassigned. Save the original " +"value of *p* to avoid losing memory when handling errors." +msgstr "" + +#: ../../c-api/memory.rst:294 +msgid "Same as :c:func:`PyMem_Free`." +msgstr "和 :c:func:`PyMem_Free` 相同。" + +#: ../../c-api/memory.rst:296 +msgid "" +"In addition, the following macro sets are provided for calling the Python " +"memory allocator directly, without involving the C API functions listed " +"above. However, note that their use does not preserve binary compatibility " +"across Python versions and is therefore deprecated in extension modules." +msgstr "" + +#: ../../c-api/memory.rst:301 +msgid "``PyMem_MALLOC(size)``" +msgstr "``PyMem_MALLOC(size)``" + +#: ../../c-api/memory.rst:302 +msgid "``PyMem_NEW(type, size)``" +msgstr "``PyMem_NEW(type, size)``" + +#: ../../c-api/memory.rst:303 +msgid "``PyMem_REALLOC(ptr, size)``" +msgstr "``PyMem_REALLOC(ptr, size)``" + +#: ../../c-api/memory.rst:304 +msgid "``PyMem_RESIZE(ptr, type, size)``" +msgstr "``PyMem_RESIZE(ptr, type, size)``" + +#: ../../c-api/memory.rst:305 +msgid "``PyMem_FREE(ptr)``" +msgstr "``PyMem_FREE(ptr)``" + +#: ../../c-api/memory.rst:306 +msgid "``PyMem_DEL(ptr)``" +msgstr "``PyMem_DEL(ptr)``" + +#: ../../c-api/memory.rst:312 +msgid "Object allocators" +msgstr "" + +#: ../../c-api/memory.rst:319 +msgid "" +"There is no guarantee that the memory returned by these allocators can be " +"successfully cast to a Python object when intercepting the allocating " +"functions in this domain by the methods described in the :ref:`Customize " +"Memory Allocators ` section." +msgstr "" + +#: ../../c-api/memory.rst:324 +msgid "" +"The :ref:`default object allocator ` uses the :" +"ref:`pymalloc memory allocator `." +msgstr "" + +#: ../../c-api/memory.rst:336 +msgid "" +"Requesting zero bytes returns a distinct non-``NULL`` pointer if possible, " +"as if ``PyObject_Malloc(1)`` had been called instead. The memory will not " +"have been initialized in any way." +msgstr "" + +#: ../../c-api/memory.rst:347 +msgid "" +"Requesting zero elements or elements of size zero bytes returns a distinct " +"non-``NULL`` pointer if possible, as if ``PyObject_Calloc(1, 1)`` had been " +"called instead." +msgstr "" + +#: ../../c-api/memory.rst:359 +msgid "" +"If *p* is ``NULL``, the call is equivalent to ``PyObject_Malloc(n)``; else " +"if *n* is equal to zero, the memory block is resized but is not freed, and " +"the returned pointer is non-``NULL``." +msgstr "" + +#: ../../c-api/memory.rst:363 +msgid "" +"Unless *p* is ``NULL``, it must have been returned by a previous call to :c:" +"func:`PyObject_Malloc`, :c:func:`PyObject_Realloc` or :c:func:" +"`PyObject_Calloc`." +msgstr "" + +#: ../../c-api/memory.rst:366 +msgid "" +"If the request fails, :c:func:`PyObject_Realloc` returns ``NULL`` and *p* " +"remains a valid pointer to the previous memory area." +msgstr "" + +#: ../../c-api/memory.rst:372 +msgid "" +"Frees the memory block pointed to by *p*, which must have been returned by a " +"previous call to :c:func:`PyObject_Malloc`, :c:func:`PyObject_Realloc` or :c:" +"func:`PyObject_Calloc`. Otherwise, or if ``PyObject_Free(p)`` has been " +"called before, undefined behavior occurs." +msgstr "" + +#: ../../c-api/memory.rst:379 +msgid "" +"Do not call this directly to free an object's memory; call the type's :c:" +"member:`~PyTypeObject.tp_free` slot instead." +msgstr "" + +#: ../../c-api/memory.rst:382 +msgid "" +"Do not use this for memory allocated by :c:macro:`PyObject_GC_New` or :c:" +"macro:`PyObject_GC_NewVar`; use :c:func:`PyObject_GC_Del` instead." +msgstr "" + +#: ../../c-api/memory.rst:387 +msgid "" +":c:func:`PyObject_GC_Del` is the equivalent of this function for memory " +"allocated by types that support garbage collection." +msgstr "" + +#: ../../c-api/memory.rst:389 ../../c-api/memory.rst:486 +msgid ":c:func:`PyObject_Malloc`" +msgstr ":c:func:`PyObject_Malloc`" + +#: ../../c-api/memory.rst:390 ../../c-api/memory.rst:487 +msgid ":c:func:`PyObject_Realloc`" +msgstr ":c:func:`PyObject_Realloc`" + +#: ../../c-api/memory.rst:391 ../../c-api/memory.rst:488 +msgid ":c:func:`PyObject_Calloc`" +msgstr ":c:func:`PyObject_Calloc`" + +#: ../../c-api/memory.rst:392 +msgid ":c:macro:`PyObject_New`" +msgstr ":c:macro:`PyObject_New`" + +#: ../../c-api/memory.rst:393 +msgid ":c:macro:`PyObject_NewVar`" +msgstr ":c:macro:`PyObject_NewVar`" + +#: ../../c-api/memory.rst:394 +msgid ":c:func:`PyType_GenericAlloc`" +msgstr ":c:func:`PyType_GenericAlloc`" + +#: ../../c-api/memory.rst:395 +msgid ":c:member:`~PyTypeObject.tp_free`" +msgstr ":c:member:`~PyTypeObject.tp_free`" + +#: ../../c-api/memory.rst:401 +msgid "Default Memory Allocators" +msgstr "" + +#: ../../c-api/memory.rst:403 +msgid "Default memory allocators:" +msgstr "" + +#: ../../c-api/memory.rst:406 +msgid "Configuration" +msgstr "配置" + +#: ../../c-api/memory.rst:406 +msgid "Name" +msgstr "名稱" + +#: ../../c-api/memory.rst:406 +msgid "PyMem_RawMalloc" +msgstr "PyMem_RawMalloc" + +#: ../../c-api/memory.rst:406 +msgid "PyMem_Malloc" +msgstr "PyMem_Malloc" + +#: ../../c-api/memory.rst:406 +msgid "PyObject_Malloc" +msgstr "PyObject_Malloc" + +#: ../../c-api/memory.rst:408 +msgid "Release build" +msgstr "" + +#: ../../c-api/memory.rst:408 +msgid "``\"pymalloc\"``" +msgstr "``\"pymalloc\"``" + +#: ../../c-api/memory.rst:408 ../../c-api/memory.rst:410 +msgid "``malloc``" +msgstr "``malloc``" + +#: ../../c-api/memory.rst:408 +msgid "``pymalloc``" +msgstr "``pymalloc``" + +#: ../../c-api/memory.rst:409 +msgid "Debug build" +msgstr "" + +#: ../../c-api/memory.rst:409 +msgid "``\"pymalloc_debug\"``" +msgstr "``\"pymalloc_debug\"``" + +#: ../../c-api/memory.rst:409 ../../c-api/memory.rst:411 +msgid "``malloc`` + debug" +msgstr "" + +#: ../../c-api/memory.rst:409 +msgid "``pymalloc`` + debug" +msgstr "" + +#: ../../c-api/memory.rst:410 +msgid "Release build, without pymalloc" +msgstr "" + +#: ../../c-api/memory.rst:410 +msgid "``\"malloc\"``" +msgstr "``\"malloc\"``" + +#: ../../c-api/memory.rst:411 +msgid "Debug build, without pymalloc" +msgstr "" + +#: ../../c-api/memory.rst:411 +msgid "``\"malloc_debug\"``" +msgstr "``\"malloc_debug\"``" + +#: ../../c-api/memory.rst:414 +msgid "Legend:" +msgstr "" + +#: ../../c-api/memory.rst:416 +msgid "Name: value for :envvar:`PYTHONMALLOC` environment variable." +msgstr "" + +#: ../../c-api/memory.rst:417 +msgid "" +"``malloc``: system allocators from the standard C library, C functions: :c:" +"func:`malloc`, :c:func:`calloc`, :c:func:`realloc` and :c:func:`free`." +msgstr "" + +#: ../../c-api/memory.rst:419 +msgid "``pymalloc``: :ref:`pymalloc memory allocator `." +msgstr "" + +#: ../../c-api/memory.rst:420 +msgid "" +"``mimalloc``: :ref:`mimalloc memory allocator `. The pymalloc " +"allocator will be used if mimalloc support isn't available." +msgstr "" + +#: ../../c-api/memory.rst:422 +msgid "" +"\"+ debug\": with :ref:`debug hooks on the Python memory allocators `." +msgstr "" + +#: ../../c-api/memory.rst:424 +msgid "\"Debug build\": :ref:`Python build in debug mode `." +msgstr "" + +#: ../../c-api/memory.rst:429 +msgid "Customize Memory Allocators" +msgstr "" + +#: ../../c-api/memory.rst:435 +msgid "" +"Structure used to describe a memory block allocator. The structure has the " +"following fields:" +msgstr "" + +#: ../../c-api/memory.rst:439 ../../c-api/memory.rst:690 +msgid "Field" +msgstr "欄位" + +#: ../../c-api/memory.rst:439 ../../c-api/memory.rst:690 +msgid "Meaning" +msgstr "意義" + +#: ../../c-api/memory.rst:441 ../../c-api/memory.rst:692 +msgid "``void *ctx``" +msgstr "``void *ctx``" + +#: ../../c-api/memory.rst:441 ../../c-api/memory.rst:692 +msgid "user context passed as first argument" +msgstr "" + +#: ../../c-api/memory.rst:443 +msgid "``void* malloc(void *ctx, size_t size)``" +msgstr "``void* malloc(void *ctx, size_t size)``" + +#: ../../c-api/memory.rst:443 +msgid "allocate a memory block" +msgstr "" + +#: ../../c-api/memory.rst:445 +msgid "``void* calloc(void *ctx, size_t nelem, size_t elsize)``" +msgstr "``void* calloc(void *ctx, size_t nelem, size_t elsize)``" + +#: ../../c-api/memory.rst:445 +msgid "allocate a memory block initialized with zeros" +msgstr "" + +#: ../../c-api/memory.rst:448 +msgid "``void* realloc(void *ctx, void *ptr, size_t new_size)``" +msgstr "``void* realloc(void *ctx, void *ptr, size_t new_size)``" + +#: ../../c-api/memory.rst:448 +msgid "allocate or resize a memory block" +msgstr "" + +#: ../../c-api/memory.rst:450 +msgid "``void free(void *ctx, void *ptr)``" +msgstr "``void free(void *ctx, void *ptr)``" + +#: ../../c-api/memory.rst:450 +msgid "free a memory block" +msgstr "" + +#: ../../c-api/memory.rst:453 +msgid "" +"The :c:type:`!PyMemAllocator` structure was renamed to :c:type:" +"`PyMemAllocatorEx` and a new ``calloc`` field was added." +msgstr "" + +#: ../../c-api/memory.rst:460 +msgid "Enum used to identify an allocator domain. Domains:" +msgstr "" + +#: ../../c-api/memory.rst:466 ../../c-api/memory.rst:475 +#: ../../c-api/memory.rst:484 +msgid "Functions:" +msgstr "函式：" + +#: ../../c-api/memory.rst:468 +msgid ":c:func:`PyMem_RawMalloc`" +msgstr ":c:func:`PyMem_RawMalloc`" + +#: ../../c-api/memory.rst:469 +msgid ":c:func:`PyMem_RawRealloc`" +msgstr ":c:func:`PyMem_RawRealloc`" + +#: ../../c-api/memory.rst:470 +msgid ":c:func:`PyMem_RawCalloc`" +msgstr ":c:func:`PyMem_RawCalloc`" + +#: ../../c-api/memory.rst:471 +msgid ":c:func:`PyMem_RawFree`" +msgstr ":c:func:`PyMem_RawFree`" + +#: ../../c-api/memory.rst:477 +msgid ":c:func:`PyMem_Malloc`," +msgstr ":c:func:`PyMem_Malloc`," + +#: ../../c-api/memory.rst:478 +msgid ":c:func:`PyMem_Realloc`" +msgstr ":c:func:`PyMem_Realloc`" + +#: ../../c-api/memory.rst:479 +msgid ":c:func:`PyMem_Calloc`" +msgstr ":c:func:`PyMem_Calloc`" + +#: ../../c-api/memory.rst:480 +msgid ":c:func:`PyMem_Free`" +msgstr ":c:func:`PyMem_Free`" + +#: ../../c-api/memory.rst:489 +msgid ":c:func:`PyObject_Free`" +msgstr ":c:func:`PyObject_Free`" + +#: ../../c-api/memory.rst:493 +msgid "Get the memory block allocator of the specified domain." +msgstr "" + +#: ../../c-api/memory.rst:498 +msgid "Set the memory block allocator of the specified domain." +msgstr "" + +#: ../../c-api/memory.rst:500 +msgid "" +"The new allocator must return a distinct non-``NULL`` pointer when " +"requesting zero bytes." +msgstr "" + +#: ../../c-api/memory.rst:503 +msgid "" +"For the :c:macro:`PYMEM_DOMAIN_RAW` domain, the allocator must be thread-" +"safe: a :term:`thread state` is not :term:`attached ` " +"when the allocator is called." +msgstr "" + +#: ../../c-api/memory.rst:507 +msgid "" +"For the remaining domains, the allocator must also be thread-safe: the " +"allocator may be called in different interpreters that do not share a :term:" +"`GIL`." +msgstr "" + +#: ../../c-api/memory.rst:511 +msgid "" +"If the new allocator is not a hook (does not call the previous allocator), " +"the :c:func:`PyMem_SetupDebugHooks` function must be called to reinstall the " +"debug hooks on top on the new allocator." +msgstr "" + +#: ../../c-api/memory.rst:515 +msgid "" +"See also :c:member:`PyPreConfig.allocator` and :ref:`Preinitialize Python " +"with PyPreConfig `." +msgstr "" + +#: ../../c-api/memory.rst:520 +msgid ":c:func:`PyMem_SetAllocator` does have the following contract:" +msgstr "" + +#: ../../c-api/memory.rst:522 +msgid "" +"It can be called after :c:func:`Py_PreInitialize` and before :c:func:" +"`Py_InitializeFromConfig` to install a custom memory allocator. There are no " +"restrictions over the installed allocator other than the ones imposed by the " +"domain (for instance, the Raw Domain allows the allocator to be called " +"without an :term:`attached thread state`). See :ref:`the section on " +"allocator domains ` for more information." +msgstr "" + +#: ../../c-api/memory.rst:530 +msgid "" +"If called after Python has finish initializing (after :c:func:" +"`Py_InitializeFromConfig` has been called) the allocator **must** wrap the " +"existing allocator. Substituting the current allocator for some other " +"arbitrary one is **not supported**." +msgstr "" + +#: ../../c-api/memory.rst:535 +msgid "All allocators must be thread-safe." +msgstr "" + +#: ../../c-api/memory.rst:541 +msgid "" +"Setup :ref:`debug hooks in the Python memory allocators ` " +"to detect memory errors." +msgstr "" + +#: ../../c-api/memory.rst:548 +msgid "Debug hooks on the Python memory allocators" +msgstr "" + +#: ../../c-api/memory.rst:550 +msgid "" +"When :ref:`Python is built in debug mode `, the :c:func:" +"`PyMem_SetupDebugHooks` function is called at the :ref:`Python " +"preinitialization ` to setup debug hooks on Python memory " +"allocators to detect memory errors." +msgstr "" + +#: ../../c-api/memory.rst:555 +msgid "" +"The :envvar:`PYTHONMALLOC` environment variable can be used to install debug " +"hooks on a Python compiled in release mode (ex: ``PYTHONMALLOC=debug``)." +msgstr "" + +#: ../../c-api/memory.rst:558 +msgid "" +"The :c:func:`PyMem_SetupDebugHooks` function can be used to set debug hooks " +"after calling :c:func:`PyMem_SetAllocator`." +msgstr "" + +#: ../../c-api/memory.rst:561 +msgid "" +"These debug hooks fill dynamically allocated memory blocks with special, " +"recognizable bit patterns. Newly allocated memory is filled with the byte " +"``0xCD`` (``PYMEM_CLEANBYTE``), freed memory is filled with the byte " +"``0xDD`` (``PYMEM_DEADBYTE``). Memory blocks are surrounded by \"forbidden " +"bytes\" filled with the byte ``0xFD`` (``PYMEM_FORBIDDENBYTE``). Strings of " +"these bytes are unlikely to be valid addresses, floats, or ASCII strings." +msgstr "" + +#: ../../c-api/memory.rst:568 +msgid "Runtime checks:" +msgstr "Runtime 檢查：" + +#: ../../c-api/memory.rst:570 +msgid "" +"Detect API violations. For example, detect if :c:func:`PyObject_Free` is " +"called on a memory block allocated by :c:func:`PyMem_Malloc`." +msgstr "" + +#: ../../c-api/memory.rst:572 +msgid "Detect write before the start of the buffer (buffer underflow)." +msgstr "" + +#: ../../c-api/memory.rst:573 +msgid "Detect write after the end of the buffer (buffer overflow)." +msgstr "" + +#: ../../c-api/memory.rst:574 +msgid "" +"Check that there is an :term:`attached thread state` when allocator " +"functions of :c:macro:`PYMEM_DOMAIN_OBJ` (ex: :c:func:`PyObject_Malloc`) " +"and :c:macro:`PYMEM_DOMAIN_MEM` (ex: :c:func:`PyMem_Malloc`) domains are " +"called." +msgstr "" + +#: ../../c-api/memory.rst:579 +msgid "" +"On error, the debug hooks use the :mod:`tracemalloc` module to get the " +"traceback where a memory block was allocated. The traceback is only " +"displayed if :mod:`tracemalloc` is tracing Python memory allocations and the " +"memory block was traced." +msgstr "" + +#: ../../c-api/memory.rst:584 +msgid "" +"Let *S* = ``sizeof(size_t)``. ``2*S`` bytes are added at each end of each " +"block of *N* bytes requested. The memory layout is like so, where p " +"represents the address returned by a malloc-like or realloc-like function " +"(``p[i:j]`` means the slice of bytes from ``*(p+i)`` inclusive up to " +"``*(p+j)`` exclusive; note that the treatment of negative indices differs " +"from a Python slice):" +msgstr "" + +#: ../../c-api/memory.rst:590 +msgid "``p[-2*S:-S]``" +msgstr "``p[-2*S:-S]``" + +#: ../../c-api/memory.rst:591 +msgid "" +"Number of bytes originally asked for. This is a size_t, big-endian (easier " +"to read in a memory dump)." +msgstr "" + +#: ../../c-api/memory.rst:593 +msgid "``p[-S]``" +msgstr "``p[-S]``" + +#: ../../c-api/memory.rst:594 +msgid "API identifier (ASCII character):" +msgstr "" + +#: ../../c-api/memory.rst:596 +msgid "``'r'`` for :c:macro:`PYMEM_DOMAIN_RAW`." +msgstr "" + +#: ../../c-api/memory.rst:597 +msgid "``'m'`` for :c:macro:`PYMEM_DOMAIN_MEM`." +msgstr "" + +#: ../../c-api/memory.rst:598 +msgid "``'o'`` for :c:macro:`PYMEM_DOMAIN_OBJ`." +msgstr "" + +#: ../../c-api/memory.rst:600 +msgid "``p[-S+1:0]``" +msgstr "``p[-S+1:0]``" + +#: ../../c-api/memory.rst:601 +msgid "Copies of PYMEM_FORBIDDENBYTE. Used to catch under- writes and reads." +msgstr "" + +#: ../../c-api/memory.rst:603 +msgid "``p[0:N]``" +msgstr "``p[0:N]``" + +#: ../../c-api/memory.rst:604 +msgid "" +"The requested memory, filled with copies of PYMEM_CLEANBYTE, used to catch " +"reference to uninitialized memory. When a realloc-like function is called " +"requesting a larger memory block, the new excess bytes are also filled with " +"PYMEM_CLEANBYTE. When a free-like function is called, these are overwritten " +"with PYMEM_DEADBYTE, to catch reference to freed memory. When a realloc- " +"like function is called requesting a smaller memory block, the excess old " +"bytes are also filled with PYMEM_DEADBYTE." +msgstr "" + +#: ../../c-api/memory.rst:612 +msgid "``p[N:N+S]``" +msgstr "``p[N:N+S]``" + +#: ../../c-api/memory.rst:613 +msgid "Copies of PYMEM_FORBIDDENBYTE. Used to catch over- writes and reads." +msgstr "" + +#: ../../c-api/memory.rst:615 +msgid "``p[N+S:N+2*S]``" +msgstr "``p[N+S:N+2*S]``" + +#: ../../c-api/memory.rst:616 +msgid "" +"Only used if the ``PYMEM_DEBUG_SERIALNO`` macro is defined (not defined by " +"default)." +msgstr "" + +#: ../../c-api/memory.rst:619 +msgid "" +"A serial number, incremented by 1 on each call to a malloc-like or realloc-" +"like function. Big-endian :c:type:`size_t`. If \"bad memory\" is detected " +"later, the serial number gives an excellent way to set a breakpoint on the " +"next run, to capture the instant at which this block was passed out. The " +"static function bumpserialno() in obmalloc.c is the only place the serial " +"number is incremented, and exists so you can set such a breakpoint easily." +msgstr "" + +#: ../../c-api/memory.rst:626 +msgid "" +"A realloc-like or free-like function first checks that the " +"PYMEM_FORBIDDENBYTE bytes at each end are intact. If they've been altered, " +"diagnostic output is written to stderr, and the program is aborted via " +"Py_FatalError(). The other main failure mode is provoking a memory error " +"when a program reads up one of the special bit patterns and tries to use it " +"as an address. If you get in a debugger then and look at the object, you're " +"likely to see that it's entirely filled with PYMEM_DEADBYTE (meaning freed " +"memory is getting used) or PYMEM_CLEANBYTE (meaning uninitialized memory is " +"getting used)." +msgstr "" + +#: ../../c-api/memory.rst:635 +msgid "" +"The :c:func:`PyMem_SetupDebugHooks` function now also works on Python " +"compiled in release mode. On error, the debug hooks now use :mod:" +"`tracemalloc` to get the traceback where a memory block was allocated. The " +"debug hooks now also check if there is an :term:`attached thread state` when " +"functions of :c:macro:`PYMEM_DOMAIN_OBJ` and :c:macro:`PYMEM_DOMAIN_MEM` " +"domains are called." +msgstr "" + +#: ../../c-api/memory.rst:643 +msgid "" +"Byte patterns ``0xCB`` (``PYMEM_CLEANBYTE``), ``0xDB`` (``PYMEM_DEADBYTE``) " +"and ``0xFB`` (``PYMEM_FORBIDDENBYTE``) have been replaced with ``0xCD``, " +"``0xDD`` and ``0xFD`` to use the same values than Windows CRT debug " +"``malloc()`` and ``free()``." +msgstr "" + +#: ../../c-api/memory.rst:653 +msgid "The pymalloc allocator" +msgstr "" + +#: ../../c-api/memory.rst:655 +msgid "" +"Python has a *pymalloc* allocator optimized for small objects (smaller or " +"equal to 512 bytes) with a short lifetime. It uses memory mappings called " +"\"arenas\" with a fixed size of either 256 KiB on 32-bit platforms or 1 MiB " +"on 64-bit platforms. It falls back to :c:func:`PyMem_RawMalloc` and :c:func:" +"`PyMem_RawRealloc` for allocations larger than 512 bytes." +msgstr "" + +#: ../../c-api/memory.rst:661 +msgid "" +"*pymalloc* is the :ref:`default allocator ` of " +"the :c:macro:`PYMEM_DOMAIN_MEM` (ex: :c:func:`PyMem_Malloc`) and :c:macro:" +"`PYMEM_DOMAIN_OBJ` (ex: :c:func:`PyObject_Malloc`) domains." +msgstr "" + +#: ../../c-api/memory.rst:665 +msgid "The arena allocator uses the following functions:" +msgstr "" + +#: ../../c-api/memory.rst:667 +msgid ":c:func:`!VirtualAlloc` and :c:func:`!VirtualFree` on Windows," +msgstr "Windows 上的 :c:func:`!VirtualAlloc` 和 :c:func:`!VirtualFree`，" + +#: ../../c-api/memory.rst:668 +msgid ":c:func:`!mmap` and :c:func:`!munmap` if available," +msgstr "如果可用，則使用 :c:func:`!mmap` 和 :c:func:`!munmap`，" + +#: ../../c-api/memory.rst:669 +msgid ":c:func:`malloc` and :c:func:`free` otherwise." +msgstr "否則使用 :c:func:`malloc` 和 :c:func:`free`。" + +#: ../../c-api/memory.rst:671 +msgid "" +"This allocator is disabled if Python is configured with the :option:`--" +"without-pymalloc` option. It can also be disabled at runtime using the :" +"envvar:`PYTHONMALLOC` environment variable (ex: ``PYTHONMALLOC=malloc``)." +msgstr "" + +#: ../../c-api/memory.rst:675 +msgid "" +"Typically, it makes sense to disable the pymalloc allocator when building " +"Python with AddressSanitizer (:option:`--with-address-sanitizer`) which " +"helps uncover low level bugs within the C code." +msgstr "" + +#: ../../c-api/memory.rst:680 +msgid "Customize pymalloc Arena Allocator" +msgstr "" + +#: ../../c-api/memory.rst:686 +msgid "" +"Structure used to describe an arena allocator. The structure has three " +"fields:" +msgstr "" + +#: ../../c-api/memory.rst:694 +msgid "``void* alloc(void *ctx, size_t size)``" +msgstr "``void* alloc(void *ctx, size_t size)``" + +#: ../../c-api/memory.rst:694 +msgid "allocate an arena of size bytes" +msgstr "" + +#: ../../c-api/memory.rst:696 +msgid "``void free(void *ctx, void *ptr, size_t size)``" +msgstr "``void free(void *ctx, void *ptr, size_t size)``" + +#: ../../c-api/memory.rst:696 +msgid "free an arena" +msgstr "" + +#: ../../c-api/memory.rst:701 +msgid "Get the arena allocator." +msgstr "" + +#: ../../c-api/memory.rst:705 +msgid "Set the arena allocator." +msgstr "" + +#: ../../c-api/memory.rst:710 +msgid "The mimalloc allocator" +msgstr "" + +#: ../../c-api/memory.rst:714 +msgid "" +"Python supports the mimalloc allocator when the underlying platform support " +"is available. mimalloc \"is a general purpose allocator with excellent " +"performance characteristics. Initially developed by Daan Leijen for the " +"runtime systems of the Koka and Lean languages.\"" +msgstr "" + +#: ../../c-api/memory.rst:719 +msgid "tracemalloc C API" +msgstr "" + +#: ../../c-api/memory.rst:725 +msgid "Track an allocated memory block in the :mod:`tracemalloc` module." +msgstr "" + +#: ../../c-api/memory.rst:727 +msgid "" +"Return ``0`` on success, return ``-1`` on error (failed to allocate memory " +"to store the trace). Return ``-2`` if tracemalloc is disabled." +msgstr "" + +#: ../../c-api/memory.rst:730 +msgid "If memory block is already tracked, update the existing trace." +msgstr "" + +#: ../../c-api/memory.rst:734 +msgid "" +"Untrack an allocated memory block in the :mod:`tracemalloc` module. Do " +"nothing if the block was not tracked." +msgstr "" + +#: ../../c-api/memory.rst:737 +msgid "Return ``-2`` if tracemalloc is disabled, otherwise return ``0``." +msgstr "" + +#: ../../c-api/memory.rst:743 +msgid "Examples" +msgstr "範例" + +#: ../../c-api/memory.rst:745 +msgid "" +"Here is the example from section :ref:`memoryoverview`, rewritten so that " +"the I/O buffer is allocated from the Python heap by using the first function " +"set::" +msgstr "" + +#: ../../c-api/memory.rst:748 +msgid "" +"PyObject *res;\n" +"char *buf = (char *) PyMem_Malloc(BUFSIZ); /* for I/O */\n" +"\n" +"if (buf == NULL)\n" +" return PyErr_NoMemory();\n" +"/* ...Do some I/O operation involving buf... */\n" +"res = PyBytes_FromString(buf);\n" +"PyMem_Free(buf); /* allocated with PyMem_Malloc */\n" +"return res;" +msgstr "" + +#: ../../c-api/memory.rst:758 +msgid "The same code using the type-oriented function set::" +msgstr "" + +#: ../../c-api/memory.rst:760 +msgid "" +"PyObject *res;\n" +"char *buf = PyMem_New(char, BUFSIZ); /* for I/O */\n" +"\n" +"if (buf == NULL)\n" +" return PyErr_NoMemory();\n" +"/* ...Do some I/O operation involving buf... */\n" +"res = PyBytes_FromString(buf);\n" +"PyMem_Free(buf); /* allocated with PyMem_New */\n" +"return res;" +msgstr "" + +#: ../../c-api/memory.rst:770 +msgid "" +"Note that in the two examples above, the buffer is always manipulated via " +"functions belonging to the same set. Indeed, it is required to use the same " +"memory API family for a given memory block, so that the risk of mixing " +"different allocators is reduced to a minimum. The following code sequence " +"contains two errors, one of which is labeled as *fatal* because it mixes two " +"different allocators operating on different heaps. ::" +msgstr "" + +#: ../../c-api/memory.rst:777 +msgid "" +"char *buf1 = PyMem_New(char, BUFSIZ);\n" +"char *buf2 = (char *) malloc(BUFSIZ);\n" +"char *buf3 = (char *) PyMem_Malloc(BUFSIZ);\n" +"...\n" +"PyMem_Del(buf3); /* Wrong -- should be PyMem_Free() */\n" +"free(buf2); /* Right -- allocated via malloc() */\n" +"free(buf1); /* Fatal -- should be PyMem_Free() */" +msgstr "" + +#: ../../c-api/memory.rst:785 +msgid "" +"In addition to the functions aimed at handling raw memory blocks from the " +"Python heap, objects in Python are allocated and released with :c:macro:" +"`PyObject_New`, :c:macro:`PyObject_NewVar` and :c:func:`PyObject_Free`." +msgstr "" + +#: ../../c-api/memory.rst:789 +msgid "" +"These will be explained in the next chapter on defining and implementing new " +"object types in C." +msgstr "" + +#: ../../c-api/memory.rst:43 +msgid "malloc (C function)" +msgstr "malloc（C 函式）" + +#: ../../c-api/memory.rst:43 +msgid "calloc (C function)" +msgstr "calloc（C 函式）" + +#: ../../c-api/memory.rst:43 +msgid "realloc (C function)" +msgstr "realloc（C 函式）" + +#: ../../c-api/memory.rst:43 +msgid "free (C function)" +msgstr "free（C 函式）" diff --git a/c-api/memoryview.po b/c-api/memoryview.po index fd622b22e9..ef12773b1f 100644 --- a/c-api/memoryview.po +++ b/c-api/memoryview.po @@ -1,108 +1,108 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-06 00:14+0000\n" -"PO-Revision-Date: 2015-12-09 17:51+0000\n" -"Last-Translator: Liang-Bo Wang \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" - -#: ../../c-api/memoryview.rst:9 -msgid "MemoryView objects" -msgstr "MemoryView 物件" - -#: ../../c-api/memoryview.rst:11 -msgid "" -"A :class:`memoryview` object exposes the C level :ref:`buffer interface " -"` as a Python object which can then be passed around like any " -"other object." -msgstr "" - -#: ../../c-api/memoryview.rst:18 -msgid "" -"This instance of :c:type:`PyTypeObject` represents the Python memoryview " -"type. This is the same object as :class:`memoryview` in the Python layer." -msgstr "" - -#: ../../c-api/memoryview.rst:24 -msgid "" -"Create a memoryview object from an object that provides the buffer " -"interface. If *obj* supports writable buffer exports, the memoryview object " -"will be read/write, otherwise it may be either read-only or read/write at " -"the discretion of the exporter." -msgstr "" - -#: ../../c-api/memoryview.rst:32 -msgid "Flag to request a readonly buffer." -msgstr "" - -#: ../../c-api/memoryview.rst:37 -msgid "Flag to request a writable buffer." -msgstr "" - -#: ../../c-api/memoryview.rst:42 -msgid "" -"Create a memoryview object using *mem* as the underlying buffer. *flags* can " -"be one of :c:macro:`PyBUF_READ` or :c:macro:`PyBUF_WRITE`." -msgstr "" - -#: ../../c-api/memoryview.rst:49 -msgid "" -"Create a memoryview object wrapping the given buffer structure *view*. For " -"simple byte buffers, :c:func:`PyMemoryView_FromMemory` is the preferred " -"function." -msgstr "" - -#: ../../c-api/memoryview.rst:55 -msgid "" -"Create a memoryview object to a :term:`contiguous` chunk of memory (in " -"either 'C' or 'F'ortran *order*) from an object that defines the buffer " -"interface. If memory is contiguous, the memoryview object points to the " -"original memory. Otherwise, a copy is made and the memoryview points to a " -"new bytes object." -msgstr "" - -#: ../../c-api/memoryview.rst:61 -msgid "" -"*buffertype* can be one of :c:macro:`PyBUF_READ` or :c:macro:`PyBUF_WRITE`." -msgstr "" - -#: ../../c-api/memoryview.rst:66 -msgid "" -"Return true if the object *obj* is a memoryview object. It is not currently " -"allowed to create subclasses of :class:`memoryview`. This function always " -"succeeds." -msgstr "" - -#: ../../c-api/memoryview.rst:73 -msgid "" -"Return a pointer to the memoryview's private copy of the exporter's buffer. " -"*mview* **must** be a memoryview instance; this macro doesn't check its " -"type, you must do it yourself or you will risk crashes." -msgstr "" - -#: ../../c-api/memoryview.rst:79 -msgid "" -"Return either a pointer to the exporting object that the memoryview is based " -"on or ``NULL`` if the memoryview has been created by one of the functions :c:" -"func:`PyMemoryView_FromMemory` or :c:func:`PyMemoryView_FromBuffer`. *mview* " -"**must** be a memoryview instance." -msgstr "" - -#: ../../c-api/memoryview.rst:5 -msgid "object" -msgstr "object（物件）" - -#: ../../c-api/memoryview.rst:5 -msgid "memoryview" -msgstr "memoryview（記憶體視圖）" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-06 00:14+0000\n" +"PO-Revision-Date: 2015-12-09 17:51+0000\n" +"Last-Translator: Liang-Bo Wang \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" + +#: ../../c-api/memoryview.rst:9 +msgid "MemoryView objects" +msgstr "MemoryView 物件" + +#: ../../c-api/memoryview.rst:11 +msgid "" +"A :class:`memoryview` object exposes the C level :ref:`buffer interface " +"` as a Python object which can then be passed around like any " +"other object." +msgstr "" + +#: ../../c-api/memoryview.rst:18 +msgid "" +"This instance of :c:type:`PyTypeObject` represents the Python memoryview " +"type. This is the same object as :class:`memoryview` in the Python layer." +msgstr "" + +#: ../../c-api/memoryview.rst:24 +msgid "" +"Create a memoryview object from an object that provides the buffer " +"interface. If *obj* supports writable buffer exports, the memoryview object " +"will be read/write, otherwise it may be either read-only or read/write at " +"the discretion of the exporter." +msgstr "" + +#: ../../c-api/memoryview.rst:32 +msgid "Flag to request a readonly buffer." +msgstr "" + +#: ../../c-api/memoryview.rst:37 +msgid "Flag to request a writable buffer." +msgstr "" + +#: ../../c-api/memoryview.rst:42 +msgid "" +"Create a memoryview object using *mem* as the underlying buffer. *flags* can " +"be one of :c:macro:`PyBUF_READ` or :c:macro:`PyBUF_WRITE`." +msgstr "" + +#: ../../c-api/memoryview.rst:49 +msgid "" +"Create a memoryview object wrapping the given buffer structure *view*. For " +"simple byte buffers, :c:func:`PyMemoryView_FromMemory` is the preferred " +"function." +msgstr "" + +#: ../../c-api/memoryview.rst:55 +msgid "" +"Create a memoryview object to a :term:`contiguous` chunk of memory (in " +"either 'C' or 'F'ortran *order*) from an object that defines the buffer " +"interface. If memory is contiguous, the memoryview object points to the " +"original memory. Otherwise, a copy is made and the memoryview points to a " +"new bytes object." +msgstr "" + +#: ../../c-api/memoryview.rst:61 +msgid "" +"*buffertype* can be one of :c:macro:`PyBUF_READ` or :c:macro:`PyBUF_WRITE`." +msgstr "" + +#: ../../c-api/memoryview.rst:66 +msgid "" +"Return true if the object *obj* is a memoryview object. It is not currently " +"allowed to create subclasses of :class:`memoryview`. This function always " +"succeeds." +msgstr "" + +#: ../../c-api/memoryview.rst:73 +msgid "" +"Return a pointer to the memoryview's private copy of the exporter's buffer. " +"*mview* **must** be a memoryview instance; this macro doesn't check its " +"type, you must do it yourself or you will risk crashes." +msgstr "" + +#: ../../c-api/memoryview.rst:79 +msgid "" +"Return either a pointer to the exporting object that the memoryview is based " +"on or ``NULL`` if the memoryview has been created by one of the functions :c:" +"func:`PyMemoryView_FromMemory` or :c:func:`PyMemoryView_FromBuffer`. *mview* " +"**must** be a memoryview instance." +msgstr "" + +#: ../../c-api/memoryview.rst:5 +msgid "object" +msgstr "object（物件）" + +#: ../../c-api/memoryview.rst:5 +msgid "memoryview" +msgstr "memoryview（記憶體視圖）" diff --git a/c-api/method.po b/c-api/method.po index 8a650771d5..ac13a9c2b6 100644 --- a/c-api/method.po +++ b/c-api/method.po @@ -1,143 +1,143 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Leon H., 2017 -# Matt Wang , 2022 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2023-07-24 00:03+0000\n" -"PO-Revision-Date: 2022-01-24 22:22+0800\n" -"Last-Translator: Matt Wang \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" -"X-Generator: Poedit 3.0.1\n" - -#: ../../c-api/method.rst:6 -msgid "Instance Method Objects" -msgstr "實例方法物件 (Instance Method Objects)" - -#: ../../c-api/method.rst:10 -msgid "" -"An instance method is a wrapper for a :c:type:`PyCFunction` and the new way " -"to bind a :c:type:`PyCFunction` to a class object. It replaces the former " -"call ``PyMethod_New(func, NULL, class)``." -msgstr "" -"實例方法是 :c:type:`PyCFunction` 的包裝器 (wrapper)，也是將 :c:type:" -"`PyCFunction` 繫結 (bind) 到類別物件的一種新方式。它替代了原先對 " -"``PyMethod_New(func, NULL, class)`` 的呼叫。" - -#: ../../c-api/method.rst:17 -msgid "" -"This instance of :c:type:`PyTypeObject` represents the Python instance " -"method type. It is not exposed to Python programs." -msgstr "" -":c:type:`PyTypeObject` 的實例代表 Python 實例方法型別。它不會公開 (expose) " -"給 Python 程式。" - -#: ../../c-api/method.rst:23 -msgid "" -"Return true if *o* is an instance method object (has type :c:data:" -"`PyInstanceMethod_Type`). The parameter must not be ``NULL``. This function " -"always succeeds." -msgstr "" -"如果 *o* 是一個實例方法物件（型別為 :c:data:`PyInstanceMethod_Type`）則回傳 " -"true。參數必須不為 ``NULL``。此函式總是會成功執行。" - -#: ../../c-api/method.rst:30 -msgid "" -"Return a new instance method object, with *func* being any callable object. " -"*func* is the function that will be called when the instance method is " -"called." -msgstr "" -"回傳一個新的實例方法物件，*func* 為任意可呼叫物件，在實例方法被呼叫時 *func* " -"函式也會被呼叫。" - -#: ../../c-api/method.rst:37 -msgid "Return the function object associated with the instance method *im*." -msgstr "回傳關聯到實例方法 *im* 的函式物件。" - -#: ../../c-api/method.rst:42 -msgid "" -"Macro version of :c:func:`PyInstanceMethod_Function` which avoids error " -"checking." -msgstr "" -"巨集 (macro) 版本的 :c:func:`PyInstanceMethod_Function`，忽略了錯誤檢查。" - -#: ../../c-api/method.rst:48 -msgid "Method Objects" -msgstr "方法物件 (Method Objects)" - -#: ../../c-api/method.rst:52 -msgid "" -"Methods are bound function objects. Methods are always bound to an instance " -"of a user-defined class. Unbound methods (methods bound to a class object) " -"are no longer available." -msgstr "" -"方法為繫結函式 (bound function) 物件。方法總是會被繫結到一個使用者定義類別的" -"實例。未繫結方法（繫結到一個類別的方法）已不可用。" - -#: ../../c-api/method.rst:61 -msgid "" -"This instance of :c:type:`PyTypeObject` represents the Python method type. " -"This is exposed to Python programs as ``types.MethodType``." -msgstr "" -"這個 :c:type:`PyTypeObject` 實例代表 Python 方法型別。它作為 ``types." -"MethodType`` 公開給 Python 程式。" - -#: ../../c-api/method.rst:67 -msgid "" -"Return true if *o* is a method object (has type :c:data:`PyMethod_Type`). " -"The parameter must not be ``NULL``. This function always succeeds." -msgstr "" -"如果 *o* 是一個方法物件（型別為 :c:data:`PyMethod_Type`）則回傳 true。參數必" -"須不為 ``NULL``。此函式總是會成功執行。" - -#: ../../c-api/method.rst:73 -msgid "" -"Return a new method object, with *func* being any callable object and *self* " -"the instance the method should be bound. *func* is the function that will be " -"called when the method is called. *self* must not be ``NULL``." -msgstr "" -"回傳一個新的方法物件，*func* 應為任意可呼叫物件，*self* 為該方法應繫結的實" -"例。在方法被呼叫時，*func* 函式也會被呼叫。*self* 必須不為 ``NULL``。" - -#: ../../c-api/method.rst:80 -msgid "Return the function object associated with the method *meth*." -msgstr "回傳關聯到方法 *meth* 的函式物件。" - -#: ../../c-api/method.rst:85 -msgid "" -"Macro version of :c:func:`PyMethod_Function` which avoids error checking." -msgstr "巨集版本的 :c:func:`PyMethod_Function`，忽略了錯誤檢查。" - -#: ../../c-api/method.rst:90 -msgid "Return the instance associated with the method *meth*." -msgstr "回傳關聯到方法 *meth* 的實例。" - -#: ../../c-api/method.rst:95 -msgid "Macro version of :c:func:`PyMethod_Self` which avoids error checking." -msgstr "巨集版本的 :c:func:`PyMethod_Self`，忽略了錯誤檢查。" - -#: ../../c-api/method.rst:8 ../../c-api/method.rst:50 -msgid "object" -msgstr "object（物件）" - -#: ../../c-api/method.rst:8 -msgid "instancemethod" -msgstr "instancemethod" - -#: ../../c-api/method.rst:50 -msgid "method" -msgstr "method（方法）" - -#: ../../c-api/method.rst:59 -msgid "MethodType (in module types)" -msgstr "MethodType（types 模組中）" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Leon H., 2017 +# Matt Wang , 2022 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-07-24 00:03+0000\n" +"PO-Revision-Date: 2022-01-24 22:22+0800\n" +"Last-Translator: Matt Wang \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" +"X-Generator: Poedit 3.0.1\n" + +#: ../../c-api/method.rst:6 +msgid "Instance Method Objects" +msgstr "實例方法物件 (Instance Method Objects)" + +#: ../../c-api/method.rst:10 +msgid "" +"An instance method is a wrapper for a :c:type:`PyCFunction` and the new way " +"to bind a :c:type:`PyCFunction` to a class object. It replaces the former " +"call ``PyMethod_New(func, NULL, class)``." +msgstr "" +"實例方法是 :c:type:`PyCFunction` 的包裝器 (wrapper)，也是將 :c:type:" +"`PyCFunction` 繫結 (bind) 到類別物件的一種新方式。它替代了原先對 " +"``PyMethod_New(func, NULL, class)`` 的呼叫。" + +#: ../../c-api/method.rst:17 +msgid "" +"This instance of :c:type:`PyTypeObject` represents the Python instance " +"method type. It is not exposed to Python programs." +msgstr "" +":c:type:`PyTypeObject` 的實例代表 Python 實例方法型別。它不會公開 (expose) " +"給 Python 程式。" + +#: ../../c-api/method.rst:23 +msgid "" +"Return true if *o* is an instance method object (has type :c:data:" +"`PyInstanceMethod_Type`). The parameter must not be ``NULL``. This function " +"always succeeds." +msgstr "" +"如果 *o* 是一個實例方法物件（型別為 :c:data:`PyInstanceMethod_Type`）則回傳 " +"true。參數必須不為 ``NULL``。此函式總是會成功執行。" + +#: ../../c-api/method.rst:30 +msgid "" +"Return a new instance method object, with *func* being any callable object. " +"*func* is the function that will be called when the instance method is " +"called." +msgstr "" +"回傳一個新的實例方法物件，*func* 為任意可呼叫物件，在實例方法被呼叫時 *func* " +"函式也會被呼叫。" + +#: ../../c-api/method.rst:37 +msgid "Return the function object associated with the instance method *im*." +msgstr "回傳關聯到實例方法 *im* 的函式物件。" + +#: ../../c-api/method.rst:42 +msgid "" +"Macro version of :c:func:`PyInstanceMethod_Function` which avoids error " +"checking." +msgstr "" +"巨集 (macro) 版本的 :c:func:`PyInstanceMethod_Function`，忽略了錯誤檢查。" + +#: ../../c-api/method.rst:48 +msgid "Method Objects" +msgstr "方法物件 (Method Objects)" + +#: ../../c-api/method.rst:52 +msgid "" +"Methods are bound function objects. Methods are always bound to an instance " +"of a user-defined class. Unbound methods (methods bound to a class object) " +"are no longer available." +msgstr "" +"方法為繫結函式 (bound function) 物件。方法總是會被繫結到一個使用者定義類別的" +"實例。未繫結方法（繫結到一個類別的方法）已不可用。" + +#: ../../c-api/method.rst:61 +msgid "" +"This instance of :c:type:`PyTypeObject` represents the Python method type. " +"This is exposed to Python programs as ``types.MethodType``." +msgstr "" +"這個 :c:type:`PyTypeObject` 實例代表 Python 方法型別。它作為 ``types." +"MethodType`` 公開給 Python 程式。" + +#: ../../c-api/method.rst:67 +msgid "" +"Return true if *o* is a method object (has type :c:data:`PyMethod_Type`). " +"The parameter must not be ``NULL``. This function always succeeds." +msgstr "" +"如果 *o* 是一個方法物件（型別為 :c:data:`PyMethod_Type`）則回傳 true。參數必" +"須不為 ``NULL``。此函式總是會成功執行。" + +#: ../../c-api/method.rst:73 +msgid "" +"Return a new method object, with *func* being any callable object and *self* " +"the instance the method should be bound. *func* is the function that will be " +"called when the method is called. *self* must not be ``NULL``." +msgstr "" +"回傳一個新的方法物件，*func* 應為任意可呼叫物件，*self* 為該方法應繫結的實" +"例。在方法被呼叫時，*func* 函式也會被呼叫。*self* 必須不為 ``NULL``。" + +#: ../../c-api/method.rst:80 +msgid "Return the function object associated with the method *meth*." +msgstr "回傳關聯到方法 *meth* 的函式物件。" + +#: ../../c-api/method.rst:85 +msgid "" +"Macro version of :c:func:`PyMethod_Function` which avoids error checking." +msgstr "巨集版本的 :c:func:`PyMethod_Function`，忽略了錯誤檢查。" + +#: ../../c-api/method.rst:90 +msgid "Return the instance associated with the method *meth*." +msgstr "回傳關聯到方法 *meth* 的實例。" + +#: ../../c-api/method.rst:95 +msgid "Macro version of :c:func:`PyMethod_Self` which avoids error checking." +msgstr "巨集版本的 :c:func:`PyMethod_Self`，忽略了錯誤檢查。" + +#: ../../c-api/method.rst:8 ../../c-api/method.rst:50 +msgid "object" +msgstr "object（物件）" + +#: ../../c-api/method.rst:8 +msgid "instancemethod" +msgstr "instancemethod" + +#: ../../c-api/method.rst:50 +msgid "method" +msgstr "method（方法）" + +#: ../../c-api/method.rst:59 +msgid "MethodType (in module types)" +msgstr "MethodType（types 模組中）" diff --git a/c-api/module.po b/c-api/module.po index 71f6d4b155..3a7ec871d8 100644 --- a/c-api/module.po +++ b/c-api/module.po @@ -1,908 +1,908 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Leon H., 2017 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-27 00:14+0000\n" -"PO-Revision-Date: 2018-05-23 14:32+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" - -#: ../../c-api/module.rst:6 -msgid "Module Objects" -msgstr "模組物件" - -#: ../../c-api/module.rst:15 -msgid "" -"This instance of :c:type:`PyTypeObject` represents the Python module type. " -"This is exposed to Python programs as :py:class:`types.ModuleType`." -msgstr "" - -#: ../../c-api/module.rst:21 -msgid "" -"Return true if *p* is a module object, or a subtype of a module object. This " -"function always succeeds." -msgstr "" - -#: ../../c-api/module.rst:27 -msgid "" -"Return true if *p* is a module object, but not a subtype of :c:data:" -"`PyModule_Type`. This function always succeeds." -msgstr "" - -#: ../../c-api/module.rst:40 -msgid "" -"Return a new module object with :attr:`module.__name__` set to *name*. The " -"module's :attr:`!__name__`, :attr:`~module.__doc__`, :attr:`~module." -"__package__` and :attr:`~module.__loader__` attributes are filled in (all " -"but :attr:`!__name__` are set to ``None``). The caller is responsible for " -"setting a :attr:`~module.__file__` attribute." -msgstr "" - -#: ../../c-api/module.rst:46 ../../c-api/module.rst:434 -#: ../../c-api/module.rst:461 -msgid "Return ``NULL`` with an exception set on error." -msgstr "在失敗時回傳 ``NULL`` 並設定例外。" - -#: ../../c-api/module.rst:50 -msgid "" -":attr:`~module.__package__` and :attr:`~module.__loader__` are now set to " -"``None``." -msgstr "" -":attr:`~module.__package__` 和 :attr:`~module.__loader__` 現在被設為 " -"``None``。" - -#: ../../c-api/module.rst:57 -msgid "" -"Similar to :c:func:`PyModule_NewObject`, but the name is a UTF-8 encoded " -"string instead of a Unicode object." -msgstr "" -"類似於 :c:func:`PyModule_NewObject`，但名稱是以 UTF-8 編碼的字串，而非 " -"Unicode 物件。" - -#: ../../c-api/module.rst:65 -msgid "" -"Return the dictionary object that implements *module*'s namespace; this " -"object is the same as the :attr:`~object.__dict__` attribute of the module " -"object. If *module* is not a module object (or a subtype of a module " -"object), :exc:`SystemError` is raised and ``NULL`` is returned." -msgstr "" - -#: ../../c-api/module.rst:70 -msgid "" -"It is recommended extensions use other ``PyModule_*`` and ``PyObject_*`` " -"functions rather than directly manipulate a module's :attr:`~object." -"__dict__`." -msgstr "" - -#: ../../c-api/module.rst:74 -msgid "" -"The returned reference is borrowed from the module; it is valid until the " -"module is destroyed." -msgstr "" - -#: ../../c-api/module.rst:84 -msgid "" -"Return *module*'s :attr:`~module.__name__` value. If the module does not " -"provide one, or if it is not a string, :exc:`SystemError` is raised and " -"``NULL`` is returned." -msgstr "" - -#: ../../c-api/module.rst:93 -msgid "" -"Similar to :c:func:`PyModule_GetNameObject` but return the name encoded to " -"``'utf-8'``." -msgstr "" -"類似於 :c:func:`PyModule_GetNameObject`，但回傳以 ``'utf-8'`` 編碼的名稱。" - -#: ../../c-api/module.rst:96 -msgid "" -"The returned buffer is only valid until the module is renamed or destroyed. " -"Note that Python code may rename a module by setting its :py:attr:`~module." -"__name__` attribute." -msgstr "" - -#: ../../c-api/module.rst:102 -msgid "" -"Return the \"state\" of the module, that is, a pointer to the block of " -"memory allocated at module creation time, or ``NULL``. See :c:member:" -"`PyModuleDef.m_size`." -msgstr "" - -#: ../../c-api/module.rst:109 -msgid "" -"Return a pointer to the :c:type:`PyModuleDef` struct from which the module " -"was created, or ``NULL`` if the module wasn't created from a definition." -msgstr "" - -#: ../../c-api/module.rst:112 -msgid "" -"On error, return ``NULL`` with an exception set. Use :c:func:" -"`PyErr_Occurred` to tell this case apart from a missing :c:type:`!" -"PyModuleDef`." -msgstr "" - -#: ../../c-api/module.rst:123 -msgid "" -"Return the name of the file from which *module* was loaded using *module*'s :" -"attr:`~module.__file__` attribute. If this is not defined, or if it is not " -"a string, raise :exc:`SystemError` and return ``NULL``; otherwise return a " -"reference to a Unicode object." -msgstr "" - -#: ../../c-api/module.rst:133 -msgid "" -"Similar to :c:func:`PyModule_GetFilenameObject` but return the filename " -"encoded to 'utf-8'." -msgstr "" -"類似於 :c:func:`PyModule_GetFilenameObject`，但回傳以 'utf-8' 編碼的檔案名" -"稱。" - -#: ../../c-api/module.rst:136 -msgid "" -"The returned buffer is only valid until the module's :py:attr:`~module." -"__file__` attribute is reassigned or the module is destroyed." -msgstr "" - -#: ../../c-api/module.rst:139 -msgid "" -":c:func:`PyModule_GetFilename` raises :exc:`UnicodeEncodeError` on " -"unencodable filenames, use :c:func:`PyModule_GetFilenameObject` instead." -msgstr "" - -#: ../../c-api/module.rst:147 -msgid "Module definitions" -msgstr "模組定義" - -#: ../../c-api/module.rst:149 -msgid "" -"The functions in the previous section work on any module object, including " -"modules imported from Python code." -msgstr "" - -#: ../../c-api/module.rst:152 -msgid "" -"Modules defined using the C API typically use a *module definition*, :c:type:" -"`PyModuleDef` -- a statically allocated, constant “description\" of how a " -"module should be created." -msgstr "" - -#: ../../c-api/module.rst:156 -msgid "" -"The definition is usually used to define an extension's “main” module object " -"(see :ref:`extension-modules` for details). It is also used to :ref:`create " -"extension modules dynamically `." -msgstr "" - -#: ../../c-api/module.rst:161 -msgid "" -"Unlike :c:func:`PyModule_New`, the definition allows management of *module " -"state* -- a piece of memory that is allocated and cleared together with the " -"module object. Unlike the module's Python attributes, Python code cannot " -"replace or delete data stored in module state." -msgstr "" - -#: ../../c-api/module.rst:169 -msgid "" -"The module definition struct, which holds all information needed to create a " -"module object. This structure must be statically allocated (or be otherwise " -"guaranteed to be valid while any modules created from it exist). Usually, " -"there is only one variable of this type for each extension module." -msgstr "" - -#: ../../c-api/module.rst:177 -msgid "Always initialize this member to :c:macro:`PyModuleDef_HEAD_INIT`." -msgstr "" - -#: ../../c-api/module.rst:181 -msgid "Name for the new module." -msgstr "" - -#: ../../c-api/module.rst:185 -msgid "" -"Docstring for the module; usually a docstring variable created with :c:macro:" -"`PyDoc_STRVAR` is used." -msgstr "" - -#: ../../c-api/module.rst:190 -msgid "" -"Module state may be kept in a per-module memory area that can be retrieved " -"with :c:func:`PyModule_GetState`, rather than in static globals. This makes " -"modules safe for use in multiple sub-interpreters." -msgstr "" - -#: ../../c-api/module.rst:194 -msgid "" -"This memory area is allocated based on *m_size* on module creation, and " -"freed when the module object is deallocated, after the :c:member:" -"`~PyModuleDef.m_free` function has been called, if present." -msgstr "" - -#: ../../c-api/module.rst:198 -msgid "" -"Setting it to a non-negative value means that the module can be re-" -"initialized and specifies the additional amount of memory it requires for " -"its state." -msgstr "" - -#: ../../c-api/module.rst:202 -msgid "" -"Setting ``m_size`` to ``-1`` means that the module does not support sub-" -"interpreters, because it has global state. Negative ``m_size`` is only " -"allowed when using :ref:`legacy single-phase initialization ` or when :ref:`creating modules dynamically `." -msgstr "" - -#: ../../c-api/module.rst:208 -msgid "See :PEP:`3121` for more details." -msgstr "更多詳情請見 :pep:`3121`。" - -#: ../../c-api/module.rst:212 -msgid "" -"A pointer to a table of module-level functions, described by :c:type:" -"`PyMethodDef` values. Can be ``NULL`` if no functions are present." -msgstr "" - -#: ../../c-api/module.rst:217 -msgid "" -"An array of slot definitions for multi-phase initialization, terminated by a " -"``{0, NULL}`` entry. When using legacy single-phase initialization, " -"*m_slots* must be ``NULL``." -msgstr "" - -#: ../../c-api/module.rst:223 -msgid "" -"Prior to version 3.5, this member was always set to ``NULL``, and was " -"defined as:" -msgstr "在 3.5 版本之前，這個成員總是被設為 ``NULL``，並被定義為：" - -#: ../../c-api/module.rst:230 -msgid "" -"A traversal function to call during GC traversal of the module object, or " -"``NULL`` if not needed." -msgstr "" - -#: ../../c-api/module.rst:233 ../../c-api/module.rst:248 -#: ../../c-api/module.rst:269 -msgid "" -"This function is not called if the module state was requested but is not " -"allocated yet. This is the case immediately after the module is created and " -"before the module is executed (:c:data:`Py_mod_exec` function). More " -"precisely, this function is not called if :c:member:`~PyModuleDef.m_size` is " -"greater than 0 and the module state (as returned by :c:func:" -"`PyModule_GetState`) is ``NULL``." -msgstr "" - -#: ../../c-api/module.rst:240 ../../c-api/module.rst:261 -#: ../../c-api/module.rst:276 -msgid "No longer called before the module state is allocated." -msgstr "" - -#: ../../c-api/module.rst:245 -msgid "" -"A clear function to call during GC clearing of the module object, or " -"``NULL`` if not needed." -msgstr "" - -#: ../../c-api/module.rst:255 -msgid "" -"Like :c:member:`PyTypeObject.tp_clear`, this function is not *always* called " -"before a module is deallocated. For example, when reference counting is " -"enough to determine that an object is no longer used, the cyclic garbage " -"collector is not involved and :c:member:`~PyModuleDef.m_free` is called " -"directly." -msgstr "" - -#: ../../c-api/module.rst:266 -msgid "" -"A function to call during deallocation of the module object, or ``NULL`` if " -"not needed." -msgstr "" - -#: ../../c-api/module.rst:281 -msgid "Module slots" -msgstr "模組槽 (Module slots)" - -#: ../../c-api/module.rst:287 -msgid "A slot ID, chosen from the available values explained below." -msgstr "" - -#: ../../c-api/module.rst:291 -msgid "Value of the slot, whose meaning depends on the slot ID." -msgstr "" - -#: ../../c-api/module.rst:295 -msgid "The available slot types are:" -msgstr "" - -#: ../../c-api/module.rst:299 -msgid "" -"Specifies a function that is called to create the module object itself. The " -"*value* pointer of this slot must point to a function of the signature:" -msgstr "" - -#: ../../c-api/module.rst:306 -msgid "" -"The function receives a :py:class:`~importlib.machinery.ModuleSpec` " -"instance, as defined in :PEP:`451`, and the module definition. It should " -"return a new module object, or set an error and return ``NULL``." -msgstr "" - -#: ../../c-api/module.rst:311 -msgid "" -"This function should be kept minimal. In particular, it should not call " -"arbitrary Python code, as trying to import the same module again may result " -"in an infinite loop." -msgstr "" - -#: ../../c-api/module.rst:315 -msgid "" -"Multiple ``Py_mod_create`` slots may not be specified in one module " -"definition." -msgstr "" - -#: ../../c-api/module.rst:318 -msgid "" -"If ``Py_mod_create`` is not specified, the import machinery will create a " -"normal module object using :c:func:`PyModule_New`. The name is taken from " -"*spec*, not the definition, to allow extension modules to dynamically adjust " -"to their place in the module hierarchy and be imported under different names " -"through symlinks, all while sharing a single module definition." -msgstr "" - -#: ../../c-api/module.rst:324 -msgid "" -"There is no requirement for the returned object to be an instance of :c:type:" -"`PyModule_Type`. Any type can be used, as long as it supports setting and " -"getting import-related attributes. However, only ``PyModule_Type`` instances " -"may be returned if the ``PyModuleDef`` has non-``NULL`` ``m_traverse``, " -"``m_clear``, ``m_free``; non-zero ``m_size``; or slots other than " -"``Py_mod_create``." -msgstr "" - -#: ../../c-api/module.rst:335 -msgid "" -"Specifies a function that is called to *execute* the module. This is " -"equivalent to executing the code of a Python module: typically, this " -"function adds classes and constants to the module. The signature of the " -"function is:" -msgstr "" - -#: ../../c-api/module.rst:344 -msgid "" -"If multiple ``Py_mod_exec`` slots are specified, they are processed in the " -"order they appear in the *m_slots* array." -msgstr "" - -#: ../../c-api/module.rst:351 ../../c-api/module.rst:384 -msgid "Specifies one of the following values:" -msgstr "" - -#: ../../c-api/module.rst:357 -msgid "The module does not support being imported in subinterpreters." -msgstr "" - -#: ../../c-api/module.rst:361 -msgid "" -"The module supports being imported in subinterpreters, but only when they " -"share the main interpreter's GIL. (See :ref:`isolating-extensions-howto`.)" -msgstr "" - -#: ../../c-api/module.rst:367 -msgid "" -"The module supports being imported in subinterpreters, even when they have " -"their own GIL. (See :ref:`isolating-extensions-howto`.)" -msgstr "" - -#: ../../c-api/module.rst:371 -msgid "" -"This slot determines whether or not importing this module in a " -"subinterpreter will fail." -msgstr "" - -#: ../../c-api/module.rst:374 -msgid "" -"Multiple ``Py_mod_multiple_interpreters`` slots may not be specified in one " -"module definition." -msgstr "" - -#: ../../c-api/module.rst:377 -msgid "" -"If ``Py_mod_multiple_interpreters`` is not specified, the import machinery " -"defaults to ``Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED``." -msgstr "" - -#: ../../c-api/module.rst:390 -msgid "" -"The module depends on the presence of the global interpreter lock (GIL), and " -"may access global state without synchronization." -msgstr "" - -#: ../../c-api/module.rst:395 -msgid "The module is safe to run without an active GIL." -msgstr "" - -#: ../../c-api/module.rst:397 -msgid "" -"This slot is ignored by Python builds not configured with :option:`--disable-" -"gil`. Otherwise, it determines whether or not importing this module will " -"cause the GIL to be automatically enabled. See :ref:`whatsnew313-free-" -"threaded-cpython` for more detail." -msgstr "" - -#: ../../c-api/module.rst:402 -msgid "" -"Multiple ``Py_mod_gil`` slots may not be specified in one module definition." -msgstr "" - -#: ../../c-api/module.rst:404 -msgid "" -"If ``Py_mod_gil`` is not specified, the import machinery defaults to " -"``Py_MOD_GIL_USED``." -msgstr "" - -#: ../../c-api/module.rst:413 -msgid "Creating extension modules dynamically" -msgstr "" - -#: ../../c-api/module.rst:415 -msgid "" -"The following functions may be used to create a module outside of an " -"extension's :ref:`initialization function `. They are " -"also used in :ref:`single-phase initialization `." -msgstr "" - -#: ../../c-api/module.rst:422 -msgid "" -"Create a new module object, given the definition in *def*. This is a macro " -"that calls :c:func:`PyModule_Create2` with *module_api_version* set to :c:" -"macro:`PYTHON_API_VERSION`, or to :c:macro:`PYTHON_ABI_VERSION` if using " -"the :ref:`limited API `." -msgstr "" - -#: ../../c-api/module.rst:430 -msgid "" -"Create a new module object, given the definition in *def*, assuming the API " -"version *module_api_version*. If that version does not match the version of " -"the running interpreter, a :exc:`RuntimeWarning` is emitted." -msgstr "" - -#: ../../c-api/module.rst:436 -msgid "" -"This function does not support slots. The :c:member:`~PyModuleDef.m_slots` " -"member of *def* must be ``NULL``." -msgstr "" - -#: ../../c-api/module.rst:442 -msgid "" -"Most uses of this function should be using :c:func:`PyModule_Create` " -"instead; only use this if you are sure you need it." -msgstr "" - -#: ../../c-api/module.rst:447 -msgid "" -"This macro calls :c:func:`PyModule_FromDefAndSpec2` with " -"*module_api_version* set to :c:macro:`PYTHON_API_VERSION`, or to :c:macro:" -"`PYTHON_ABI_VERSION` if using the :ref:`limited API `." -msgstr "" - -#: ../../c-api/module.rst:456 -msgid "" -"Create a new module object, given the definition in *def* and the ModuleSpec " -"*spec*, assuming the API version *module_api_version*. If that version does " -"not match the version of the running interpreter, a :exc:`RuntimeWarning` is " -"emitted." -msgstr "" - -#: ../../c-api/module.rst:463 -msgid "" -"Note that this does not process execution slots (:c:data:`Py_mod_exec`). " -"Both ``PyModule_FromDefAndSpec`` and ``PyModule_ExecDef`` must be called to " -"fully initialize a module." -msgstr "" - -#: ../../c-api/module.rst:469 -msgid "" -"Most uses of this function should be using :c:func:`PyModule_FromDefAndSpec` " -"instead; only use this if you are sure you need it." -msgstr "" - -#: ../../c-api/module.rst:476 -msgid "Process any execution slots (:c:data:`Py_mod_exec`) given in *def*." -msgstr "" - -#: ../../c-api/module.rst:482 -msgid "The C API version. Defined for backwards compatibility." -msgstr "" - -#: ../../c-api/module.rst:484 ../../c-api/module.rst:491 -msgid "" -"Currently, this constant is not updated in new Python versions, and is not " -"useful for versioning. This may change in the future." -msgstr "" - -#: ../../c-api/module.rst:489 -msgid "Defined as ``3`` for backwards compatibility." -msgstr "" - -#: ../../c-api/module.rst:496 -msgid "Support functions" -msgstr "支援的函式" - -#: ../../c-api/module.rst:498 -msgid "" -"The following functions are provided to help initialize a module state. They " -"are intended for a module's execution slots (:c:data:`Py_mod_exec`), the " -"initialization function for legacy :ref:`single-phase initialization `, or code that creates modules dynamically." -msgstr "" - -#: ../../c-api/module.rst:506 -msgid "" -"Add an object to *module* as *name*. This is a convenience function which " -"can be used from the module's initialization function." -msgstr "" - -#: ../../c-api/module.rst:509 -msgid "" -"On success, return ``0``. On error, raise an exception and return ``-1``." -msgstr "" - -#: ../../c-api/module.rst:511 ../../c-api/module.rst:562 -#: ../../c-api/module.rst:589 -msgid "Example usage::" -msgstr "用法範例： ::" - -#: ../../c-api/module.rst:513 -msgid "" -"static int\n" -"add_spam(PyObject *module, int value)\n" -"{\n" -" PyObject *obj = PyLong_FromLong(value);\n" -" if (obj == NULL) {\n" -" return -1;\n" -" }\n" -" int res = PyModule_AddObjectRef(module, \"spam\", obj);\n" -" Py_DECREF(obj);\n" -" return res;\n" -" }" -msgstr "" -"static int\n" -"add_spam(PyObject *module, int value)\n" -"{\n" -" PyObject *obj = PyLong_FromLong(value);\n" -" if (obj == NULL) {\n" -" return -1;\n" -" }\n" -" int res = PyModule_AddObjectRef(module, \"spam\", obj);\n" -" Py_DECREF(obj);\n" -" return res;\n" -" }" - -#: ../../c-api/module.rst:525 -msgid "" -"To be convenient, the function accepts ``NULL`` *value* with an exception " -"set. In this case, return ``-1`` and just leave the raised exception " -"unchanged." -msgstr "" - -#: ../../c-api/module.rst:529 -msgid "" -"The example can also be written without checking explicitly if *obj* is " -"``NULL``::" -msgstr "" - -#: ../../c-api/module.rst:532 -msgid "" -"static int\n" -"add_spam(PyObject *module, int value)\n" -"{\n" -" PyObject *obj = PyLong_FromLong(value);\n" -" int res = PyModule_AddObjectRef(module, \"spam\", obj);\n" -" Py_XDECREF(obj);\n" -" return res;\n" -" }" -msgstr "" -"static int\n" -"add_spam(PyObject *module, int value)\n" -"{\n" -" PyObject *obj = PyLong_FromLong(value);\n" -" int res = PyModule_AddObjectRef(module, \"spam\", obj);\n" -" Py_XDECREF(obj);\n" -" return res;\n" -" }" - -#: ../../c-api/module.rst:541 -msgid "" -"Note that ``Py_XDECREF()`` should be used instead of ``Py_DECREF()`` in this " -"case, since *obj* can be ``NULL``." -msgstr "" - -#: ../../c-api/module.rst:544 -msgid "" -"The number of different *name* strings passed to this function should be " -"kept small, usually by only using statically allocated strings as *name*. " -"For names that aren't known at compile time, prefer calling :c:func:" -"`PyUnicode_FromString` and :c:func:`PyObject_SetAttr` directly. For more " -"details, see :c:func:`PyUnicode_InternFromString`, which may be used " -"internally to create a key object." -msgstr "" - -#: ../../c-api/module.rst:557 -msgid "" -"Similar to :c:func:`PyModule_AddObjectRef`, but \"steals\" a reference to " -"*value*. It can be called with a result of function that returns a new " -"reference without bothering to check its result or even saving it to a " -"variable." -msgstr "" - -#: ../../c-api/module.rst:564 -msgid "" -"if (PyModule_Add(module, \"spam\", PyBytes_FromString(value)) < 0) {\n" -" goto error;\n" -"}" -msgstr "" -"if (PyModule_Add(module, \"spam\", PyBytes_FromString(value)) < 0) {\n" -" goto error;\n" -"}" - -#: ../../c-api/module.rst:573 -msgid "" -"Similar to :c:func:`PyModule_AddObjectRef`, but steals a reference to " -"*value* on success (if it returns ``0``)." -msgstr "" -"類似於 :c:func:`PyModule_AddObjectRef`，但在成功時（如果回傳 ``0``）會偷走對 " -"*value* 的參照。" - -#: ../../c-api/module.rst:576 -msgid "" -"The new :c:func:`PyModule_Add` or :c:func:`PyModule_AddObjectRef` functions " -"are recommended, since it is easy to introduce reference leaks by misusing " -"the :c:func:`PyModule_AddObject` function." -msgstr "" - -#: ../../c-api/module.rst:583 -msgid "" -"Unlike other functions that steal references, ``PyModule_AddObject()`` only " -"releases the reference to *value* **on success**." -msgstr "" - -#: ../../c-api/module.rst:586 -msgid "" -"This means that its return value must be checked, and calling code must :c:" -"func:`Py_XDECREF` *value* manually on error." -msgstr "" - -#: ../../c-api/module.rst:591 -msgid "" -"PyObject *obj = PyBytes_FromString(value);\n" -"if (PyModule_AddObject(module, \"spam\", obj) < 0) {\n" -" // If 'obj' is not NULL and PyModule_AddObject() failed,\n" -" // 'obj' strong reference must be deleted with Py_XDECREF().\n" -" // If 'obj' is NULL, Py_XDECREF() does nothing.\n" -" Py_XDECREF(obj);\n" -" goto error;\n" -"}\n" -"// PyModule_AddObject() stole a reference to obj:\n" -"// Py_XDECREF(obj) is not needed here." -msgstr "" - -#: ../../c-api/module.rst:604 -msgid ":c:func:`PyModule_AddObject` is :term:`soft deprecated`." -msgstr "" -":c:func:`PyModule_AddObject` 已被\\ :term:`軟性棄用 `。" - -#: ../../c-api/module.rst:609 -msgid "" -"Add an integer constant to *module* as *name*. This convenience function " -"can be used from the module's initialization function. Return ``-1`` with an " -"exception set on error, ``0`` on success." -msgstr "" - -#: ../../c-api/module.rst:613 -msgid "" -"This is a convenience function that calls :c:func:`PyLong_FromLong` and :c:" -"func:`PyModule_AddObjectRef`; see their documentation for details." -msgstr "" - -#: ../../c-api/module.rst:619 -msgid "" -"Add a string constant to *module* as *name*. This convenience function can " -"be used from the module's initialization function. The string *value* must " -"be ``NULL``-terminated. Return ``-1`` with an exception set on error, ``0`` " -"on success." -msgstr "" - -#: ../../c-api/module.rst:624 -msgid "" -"This is a convenience function that calls :c:func:" -"`PyUnicode_InternFromString` and :c:func:`PyModule_AddObjectRef`; see their " -"documentation for details." -msgstr "" - -#: ../../c-api/module.rst:631 -msgid "" -"Add an int constant to *module*. The name and the value are taken from " -"*macro*. For example ``PyModule_AddIntMacro(module, AF_INET)`` adds the int " -"constant *AF_INET* with the value of *AF_INET* to *module*. Return ``-1`` " -"with an exception set on error, ``0`` on success." -msgstr "" - -#: ../../c-api/module.rst:639 -msgid "Add a string constant to *module*." -msgstr "將字串常數加入到 *module* 中。" - -#: ../../c-api/module.rst:643 -msgid "" -"Add a type object to *module*. The type object is finalized by calling " -"internally :c:func:`PyType_Ready`. The name of the type object is taken from " -"the last component of :c:member:`~PyTypeObject.tp_name` after dot. Return " -"``-1`` with an exception set on error, ``0`` on success." -msgstr "" - -#: ../../c-api/module.rst:653 -msgid "" -"Add the functions from the ``NULL`` terminated *functions* array to " -"*module*. Refer to the :c:type:`PyMethodDef` documentation for details on " -"individual entries (due to the lack of a shared module namespace, module " -"level \"functions\" implemented in C typically receive the module as their " -"first parameter, making them similar to instance methods on Python classes)." -msgstr "" - -#: ../../c-api/module.rst:659 -msgid "" -"This function is called automatically when creating a module from " -"``PyModuleDef`` (such as when using :ref:`multi-phase-initialization`, " -"``PyModule_Create``, or ``PyModule_FromDefAndSpec``). Some module authors " -"may prefer defining functions in multiple :c:type:`PyMethodDef` arrays; in " -"that case they should call this function directly." -msgstr "" - -#: ../../c-api/module.rst:666 -msgid "" -"The *functions* array must be statically allocated (or otherwise guaranteed " -"to outlive the module object)." -msgstr "" - -#: ../../c-api/module.rst:673 -msgid "" -"Set the docstring for *module* to *docstring*. This function is called " -"automatically when creating a module from ``PyModuleDef`` (such as when " -"using :ref:`multi-phase-initialization`, ``PyModule_Create``, or " -"``PyModule_FromDefAndSpec``)." -msgstr "" - -#: ../../c-api/module.rst:682 -msgid "" -"Indicate that *module* does or does not support running without the global " -"interpreter lock (GIL), using one of the values from :c:macro:`Py_mod_gil`. " -"It must be called during *module*'s initialization function when using :ref:" -"`single-phase-initialization`. If this function is not called during module " -"initialization, the import machinery assumes the module does not support " -"running without the GIL. This function is only available in Python builds " -"configured with :option:`--disable-gil`. Return ``-1`` with an exception set " -"on error, ``0`` on success." -msgstr "" - -#: ../../c-api/module.rst:696 -msgid "Module lookup (single-phase initialization)" -msgstr "" - -#: ../../c-api/module.rst:698 -msgid "" -"The legacy :ref:`single-phase initialization ` " -"initialization scheme creates singleton modules that can be looked up in the " -"context of the current interpreter. This allows the module object to be " -"retrieved later with only a reference to the module definition." -msgstr "" - -#: ../../c-api/module.rst:703 -msgid "" -"These functions will not work on modules created using multi-phase " -"initialization, since multiple such modules can be created from a single " -"definition." -msgstr "" - -#: ../../c-api/module.rst:708 -msgid "" -"Returns the module object that was created from *def* for the current " -"interpreter. This method requires that the module object has been attached " -"to the interpreter state with :c:func:`PyState_AddModule` beforehand. In " -"case the corresponding module object is not found or has not been attached " -"to the interpreter state yet, it returns ``NULL``." -msgstr "" - -#: ../../c-api/module.rst:715 -msgid "" -"Attaches the module object passed to the function to the interpreter state. " -"This allows the module object to be accessible via :c:func:" -"`PyState_FindModule`." -msgstr "" - -#: ../../c-api/module.rst:718 -msgid "Only effective on modules created using single-phase initialization." -msgstr "" - -#: ../../c-api/module.rst:720 -msgid "" -"Python calls ``PyState_AddModule`` automatically after importing a module " -"that uses :ref:`single-phase initialization `, " -"so it is unnecessary (but harmless) to call it from module initialization " -"code. An explicit call is needed only if the module's own init code " -"subsequently calls ``PyState_FindModule``. The function is mainly intended " -"for implementing alternative import mechanisms (either by calling it " -"directly, or by referring to its implementation for details of the required " -"state updates)." -msgstr "" - -#: ../../c-api/module.rst:729 -msgid "" -"If a module was attached previously using the same *def*, it is replaced by " -"the new *module*." -msgstr "" - -#: ../../c-api/module.rst:732 ../../c-api/module.rst:743 -msgid "The caller must have an :term:`attached thread state`." -msgstr "" - -#: ../../c-api/module.rst:734 -msgid "Return ``-1`` with an exception set on error, ``0`` on success." -msgstr "成功時回傳 ``0``，在失敗時回傳 ``-1`` 並設定例外。" - -#: ../../c-api/module.rst:740 -msgid "" -"Removes the module object created from *def* from the interpreter state. " -"Return ``-1`` with an exception set on error, ``0`` on success." -msgstr "" - -#: ../../c-api/module.rst:8 -msgid "object" -msgstr "object（模組）" - -#: ../../c-api/module.rst:8 -msgid "module" -msgstr "module（模組）" - -#: ../../c-api/module.rst:13 -msgid "ModuleType (in module types)" -msgstr "MethodType（types 模組中）" - -#: ../../c-api/module.rst:33 ../../c-api/module.rst:80 -msgid "__name__ (module attribute)" -msgstr "__name__（模組屬性）" - -#: ../../c-api/module.rst:33 -msgid "__doc__ (module attribute)" -msgstr "__doc__（模組屬性）" - -#: ../../c-api/module.rst:33 ../../c-api/module.rst:119 -msgid "__file__ (module attribute)" -msgstr "__file__（模組屬性）" - -#: ../../c-api/module.rst:33 -msgid "__package__ (module attribute)" -msgstr "__package__（模組屬性）" - -#: ../../c-api/module.rst:33 -msgid "__loader__ (module attribute)" -msgstr "__loader__（模組屬性）" - -#: ../../c-api/module.rst:63 -msgid "__dict__ (module attribute)" -msgstr "__dict__（模組屬性）" - -#: ../../c-api/module.rst:80 ../../c-api/module.rst:119 -msgid "SystemError (built-in exception)" -msgstr "SystemError（內建例外）" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Leon H., 2017 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-27 00:14+0000\n" +"PO-Revision-Date: 2018-05-23 14:32+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" + +#: ../../c-api/module.rst:6 +msgid "Module Objects" +msgstr "模組物件" + +#: ../../c-api/module.rst:15 +msgid "" +"This instance of :c:type:`PyTypeObject` represents the Python module type. " +"This is exposed to Python programs as :py:class:`types.ModuleType`." +msgstr "" + +#: ../../c-api/module.rst:21 +msgid "" +"Return true if *p* is a module object, or a subtype of a module object. This " +"function always succeeds." +msgstr "" + +#: ../../c-api/module.rst:27 +msgid "" +"Return true if *p* is a module object, but not a subtype of :c:data:" +"`PyModule_Type`. This function always succeeds." +msgstr "" + +#: ../../c-api/module.rst:40 +msgid "" +"Return a new module object with :attr:`module.__name__` set to *name*. The " +"module's :attr:`!__name__`, :attr:`~module.__doc__`, :attr:`~module." +"__package__` and :attr:`~module.__loader__` attributes are filled in (all " +"but :attr:`!__name__` are set to ``None``). The caller is responsible for " +"setting a :attr:`~module.__file__` attribute." +msgstr "" + +#: ../../c-api/module.rst:46 ../../c-api/module.rst:434 +#: ../../c-api/module.rst:461 +msgid "Return ``NULL`` with an exception set on error." +msgstr "在失敗時回傳 ``NULL`` 並設定例外。" + +#: ../../c-api/module.rst:50 +msgid "" +":attr:`~module.__package__` and :attr:`~module.__loader__` are now set to " +"``None``." +msgstr "" +":attr:`~module.__package__` 和 :attr:`~module.__loader__` 現在被設為 " +"``None``。" + +#: ../../c-api/module.rst:57 +msgid "" +"Similar to :c:func:`PyModule_NewObject`, but the name is a UTF-8 encoded " +"string instead of a Unicode object." +msgstr "" +"類似於 :c:func:`PyModule_NewObject`，但名稱是以 UTF-8 編碼的字串，而非 " +"Unicode 物件。" + +#: ../../c-api/module.rst:65 +msgid "" +"Return the dictionary object that implements *module*'s namespace; this " +"object is the same as the :attr:`~object.__dict__` attribute of the module " +"object. If *module* is not a module object (or a subtype of a module " +"object), :exc:`SystemError` is raised and ``NULL`` is returned." +msgstr "" + +#: ../../c-api/module.rst:70 +msgid "" +"It is recommended extensions use other ``PyModule_*`` and ``PyObject_*`` " +"functions rather than directly manipulate a module's :attr:`~object." +"__dict__`." +msgstr "" + +#: ../../c-api/module.rst:74 +msgid "" +"The returned reference is borrowed from the module; it is valid until the " +"module is destroyed." +msgstr "" + +#: ../../c-api/module.rst:84 +msgid "" +"Return *module*'s :attr:`~module.__name__` value. If the module does not " +"provide one, or if it is not a string, :exc:`SystemError` is raised and " +"``NULL`` is returned." +msgstr "" + +#: ../../c-api/module.rst:93 +msgid "" +"Similar to :c:func:`PyModule_GetNameObject` but return the name encoded to " +"``'utf-8'``." +msgstr "" +"類似於 :c:func:`PyModule_GetNameObject`，但回傳以 ``'utf-8'`` 編碼的名稱。" + +#: ../../c-api/module.rst:96 +msgid "" +"The returned buffer is only valid until the module is renamed or destroyed. " +"Note that Python code may rename a module by setting its :py:attr:`~module." +"__name__` attribute." +msgstr "" + +#: ../../c-api/module.rst:102 +msgid "" +"Return the \"state\" of the module, that is, a pointer to the block of " +"memory allocated at module creation time, or ``NULL``. See :c:member:" +"`PyModuleDef.m_size`." +msgstr "" + +#: ../../c-api/module.rst:109 +msgid "" +"Return a pointer to the :c:type:`PyModuleDef` struct from which the module " +"was created, or ``NULL`` if the module wasn't created from a definition." +msgstr "" + +#: ../../c-api/module.rst:112 +msgid "" +"On error, return ``NULL`` with an exception set. Use :c:func:" +"`PyErr_Occurred` to tell this case apart from a missing :c:type:`!" +"PyModuleDef`." +msgstr "" + +#: ../../c-api/module.rst:123 +msgid "" +"Return the name of the file from which *module* was loaded using *module*'s :" +"attr:`~module.__file__` attribute. If this is not defined, or if it is not " +"a string, raise :exc:`SystemError` and return ``NULL``; otherwise return a " +"reference to a Unicode object." +msgstr "" + +#: ../../c-api/module.rst:133 +msgid "" +"Similar to :c:func:`PyModule_GetFilenameObject` but return the filename " +"encoded to 'utf-8'." +msgstr "" +"類似於 :c:func:`PyModule_GetFilenameObject`，但回傳以 'utf-8' 編碼的檔案名" +"稱。" + +#: ../../c-api/module.rst:136 +msgid "" +"The returned buffer is only valid until the module's :py:attr:`~module." +"__file__` attribute is reassigned or the module is destroyed." +msgstr "" + +#: ../../c-api/module.rst:139 +msgid "" +":c:func:`PyModule_GetFilename` raises :exc:`UnicodeEncodeError` on " +"unencodable filenames, use :c:func:`PyModule_GetFilenameObject` instead." +msgstr "" + +#: ../../c-api/module.rst:147 +msgid "Module definitions" +msgstr "模組定義" + +#: ../../c-api/module.rst:149 +msgid "" +"The functions in the previous section work on any module object, including " +"modules imported from Python code." +msgstr "" + +#: ../../c-api/module.rst:152 +msgid "" +"Modules defined using the C API typically use a *module definition*, :c:type:" +"`PyModuleDef` -- a statically allocated, constant “description\" of how a " +"module should be created." +msgstr "" + +#: ../../c-api/module.rst:156 +msgid "" +"The definition is usually used to define an extension's “main” module object " +"(see :ref:`extension-modules` for details). It is also used to :ref:`create " +"extension modules dynamically `." +msgstr "" + +#: ../../c-api/module.rst:161 +msgid "" +"Unlike :c:func:`PyModule_New`, the definition allows management of *module " +"state* -- a piece of memory that is allocated and cleared together with the " +"module object. Unlike the module's Python attributes, Python code cannot " +"replace or delete data stored in module state." +msgstr "" + +#: ../../c-api/module.rst:169 +msgid "" +"The module definition struct, which holds all information needed to create a " +"module object. This structure must be statically allocated (or be otherwise " +"guaranteed to be valid while any modules created from it exist). Usually, " +"there is only one variable of this type for each extension module." +msgstr "" + +#: ../../c-api/module.rst:177 +msgid "Always initialize this member to :c:macro:`PyModuleDef_HEAD_INIT`." +msgstr "" + +#: ../../c-api/module.rst:181 +msgid "Name for the new module." +msgstr "" + +#: ../../c-api/module.rst:185 +msgid "" +"Docstring for the module; usually a docstring variable created with :c:macro:" +"`PyDoc_STRVAR` is used." +msgstr "" + +#: ../../c-api/module.rst:190 +msgid "" +"Module state may be kept in a per-module memory area that can be retrieved " +"with :c:func:`PyModule_GetState`, rather than in static globals. This makes " +"modules safe for use in multiple sub-interpreters." +msgstr "" + +#: ../../c-api/module.rst:194 +msgid "" +"This memory area is allocated based on *m_size* on module creation, and " +"freed when the module object is deallocated, after the :c:member:" +"`~PyModuleDef.m_free` function has been called, if present." +msgstr "" + +#: ../../c-api/module.rst:198 +msgid "" +"Setting it to a non-negative value means that the module can be re-" +"initialized and specifies the additional amount of memory it requires for " +"its state." +msgstr "" + +#: ../../c-api/module.rst:202 +msgid "" +"Setting ``m_size`` to ``-1`` means that the module does not support sub-" +"interpreters, because it has global state. Negative ``m_size`` is only " +"allowed when using :ref:`legacy single-phase initialization ` or when :ref:`creating modules dynamically `." +msgstr "" + +#: ../../c-api/module.rst:208 +msgid "See :PEP:`3121` for more details." +msgstr "更多詳情請見 :pep:`3121`。" + +#: ../../c-api/module.rst:212 +msgid "" +"A pointer to a table of module-level functions, described by :c:type:" +"`PyMethodDef` values. Can be ``NULL`` if no functions are present." +msgstr "" + +#: ../../c-api/module.rst:217 +msgid "" +"An array of slot definitions for multi-phase initialization, terminated by a " +"``{0, NULL}`` entry. When using legacy single-phase initialization, " +"*m_slots* must be ``NULL``." +msgstr "" + +#: ../../c-api/module.rst:223 +msgid "" +"Prior to version 3.5, this member was always set to ``NULL``, and was " +"defined as:" +msgstr "在 3.5 版本之前，這個成員總是被設為 ``NULL``，並被定義為：" + +#: ../../c-api/module.rst:230 +msgid "" +"A traversal function to call during GC traversal of the module object, or " +"``NULL`` if not needed." +msgstr "" + +#: ../../c-api/module.rst:233 ../../c-api/module.rst:248 +#: ../../c-api/module.rst:269 +msgid "" +"This function is not called if the module state was requested but is not " +"allocated yet. This is the case immediately after the module is created and " +"before the module is executed (:c:data:`Py_mod_exec` function). More " +"precisely, this function is not called if :c:member:`~PyModuleDef.m_size` is " +"greater than 0 and the module state (as returned by :c:func:" +"`PyModule_GetState`) is ``NULL``." +msgstr "" + +#: ../../c-api/module.rst:240 ../../c-api/module.rst:261 +#: ../../c-api/module.rst:276 +msgid "No longer called before the module state is allocated." +msgstr "" + +#: ../../c-api/module.rst:245 +msgid "" +"A clear function to call during GC clearing of the module object, or " +"``NULL`` if not needed." +msgstr "" + +#: ../../c-api/module.rst:255 +msgid "" +"Like :c:member:`PyTypeObject.tp_clear`, this function is not *always* called " +"before a module is deallocated. For example, when reference counting is " +"enough to determine that an object is no longer used, the cyclic garbage " +"collector is not involved and :c:member:`~PyModuleDef.m_free` is called " +"directly." +msgstr "" + +#: ../../c-api/module.rst:266 +msgid "" +"A function to call during deallocation of the module object, or ``NULL`` if " +"not needed." +msgstr "" + +#: ../../c-api/module.rst:281 +msgid "Module slots" +msgstr "模組槽 (Module slots)" + +#: ../../c-api/module.rst:287 +msgid "A slot ID, chosen from the available values explained below." +msgstr "" + +#: ../../c-api/module.rst:291 +msgid "Value of the slot, whose meaning depends on the slot ID." +msgstr "" + +#: ../../c-api/module.rst:295 +msgid "The available slot types are:" +msgstr "" + +#: ../../c-api/module.rst:299 +msgid "" +"Specifies a function that is called to create the module object itself. The " +"*value* pointer of this slot must point to a function of the signature:" +msgstr "" + +#: ../../c-api/module.rst:306 +msgid "" +"The function receives a :py:class:`~importlib.machinery.ModuleSpec` " +"instance, as defined in :PEP:`451`, and the module definition. It should " +"return a new module object, or set an error and return ``NULL``." +msgstr "" + +#: ../../c-api/module.rst:311 +msgid "" +"This function should be kept minimal. In particular, it should not call " +"arbitrary Python code, as trying to import the same module again may result " +"in an infinite loop." +msgstr "" + +#: ../../c-api/module.rst:315 +msgid "" +"Multiple ``Py_mod_create`` slots may not be specified in one module " +"definition." +msgstr "" + +#: ../../c-api/module.rst:318 +msgid "" +"If ``Py_mod_create`` is not specified, the import machinery will create a " +"normal module object using :c:func:`PyModule_New`. The name is taken from " +"*spec*, not the definition, to allow extension modules to dynamically adjust " +"to their place in the module hierarchy and be imported under different names " +"through symlinks, all while sharing a single module definition." +msgstr "" + +#: ../../c-api/module.rst:324 +msgid "" +"There is no requirement for the returned object to be an instance of :c:type:" +"`PyModule_Type`. Any type can be used, as long as it supports setting and " +"getting import-related attributes. However, only ``PyModule_Type`` instances " +"may be returned if the ``PyModuleDef`` has non-``NULL`` ``m_traverse``, " +"``m_clear``, ``m_free``; non-zero ``m_size``; or slots other than " +"``Py_mod_create``." +msgstr "" + +#: ../../c-api/module.rst:335 +msgid "" +"Specifies a function that is called to *execute* the module. This is " +"equivalent to executing the code of a Python module: typically, this " +"function adds classes and constants to the module. The signature of the " +"function is:" +msgstr "" + +#: ../../c-api/module.rst:344 +msgid "" +"If multiple ``Py_mod_exec`` slots are specified, they are processed in the " +"order they appear in the *m_slots* array." +msgstr "" + +#: ../../c-api/module.rst:351 ../../c-api/module.rst:384 +msgid "Specifies one of the following values:" +msgstr "" + +#: ../../c-api/module.rst:357 +msgid "The module does not support being imported in subinterpreters." +msgstr "" + +#: ../../c-api/module.rst:361 +msgid "" +"The module supports being imported in subinterpreters, but only when they " +"share the main interpreter's GIL. (See :ref:`isolating-extensions-howto`.)" +msgstr "" + +#: ../../c-api/module.rst:367 +msgid "" +"The module supports being imported in subinterpreters, even when they have " +"their own GIL. (See :ref:`isolating-extensions-howto`.)" +msgstr "" + +#: ../../c-api/module.rst:371 +msgid "" +"This slot determines whether or not importing this module in a " +"subinterpreter will fail." +msgstr "" + +#: ../../c-api/module.rst:374 +msgid "" +"Multiple ``Py_mod_multiple_interpreters`` slots may not be specified in one " +"module definition." +msgstr "" + +#: ../../c-api/module.rst:377 +msgid "" +"If ``Py_mod_multiple_interpreters`` is not specified, the import machinery " +"defaults to ``Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED``." +msgstr "" + +#: ../../c-api/module.rst:390 +msgid "" +"The module depends on the presence of the global interpreter lock (GIL), and " +"may access global state without synchronization." +msgstr "" + +#: ../../c-api/module.rst:395 +msgid "The module is safe to run without an active GIL." +msgstr "" + +#: ../../c-api/module.rst:397 +msgid "" +"This slot is ignored by Python builds not configured with :option:`--disable-" +"gil`. Otherwise, it determines whether or not importing this module will " +"cause the GIL to be automatically enabled. See :ref:`whatsnew313-free-" +"threaded-cpython` for more detail." +msgstr "" + +#: ../../c-api/module.rst:402 +msgid "" +"Multiple ``Py_mod_gil`` slots may not be specified in one module definition." +msgstr "" + +#: ../../c-api/module.rst:404 +msgid "" +"If ``Py_mod_gil`` is not specified, the import machinery defaults to " +"``Py_MOD_GIL_USED``." +msgstr "" + +#: ../../c-api/module.rst:413 +msgid "Creating extension modules dynamically" +msgstr "" + +#: ../../c-api/module.rst:415 +msgid "" +"The following functions may be used to create a module outside of an " +"extension's :ref:`initialization function `. They are " +"also used in :ref:`single-phase initialization `." +msgstr "" + +#: ../../c-api/module.rst:422 +msgid "" +"Create a new module object, given the definition in *def*. This is a macro " +"that calls :c:func:`PyModule_Create2` with *module_api_version* set to :c:" +"macro:`PYTHON_API_VERSION`, or to :c:macro:`PYTHON_ABI_VERSION` if using " +"the :ref:`limited API `." +msgstr "" + +#: ../../c-api/module.rst:430 +msgid "" +"Create a new module object, given the definition in *def*, assuming the API " +"version *module_api_version*. If that version does not match the version of " +"the running interpreter, a :exc:`RuntimeWarning` is emitted." +msgstr "" + +#: ../../c-api/module.rst:436 +msgid "" +"This function does not support slots. The :c:member:`~PyModuleDef.m_slots` " +"member of *def* must be ``NULL``." +msgstr "" + +#: ../../c-api/module.rst:442 +msgid "" +"Most uses of this function should be using :c:func:`PyModule_Create` " +"instead; only use this if you are sure you need it." +msgstr "" + +#: ../../c-api/module.rst:447 +msgid "" +"This macro calls :c:func:`PyModule_FromDefAndSpec2` with " +"*module_api_version* set to :c:macro:`PYTHON_API_VERSION`, or to :c:macro:" +"`PYTHON_ABI_VERSION` if using the :ref:`limited API `." +msgstr "" + +#: ../../c-api/module.rst:456 +msgid "" +"Create a new module object, given the definition in *def* and the ModuleSpec " +"*spec*, assuming the API version *module_api_version*. If that version does " +"not match the version of the running interpreter, a :exc:`RuntimeWarning` is " +"emitted." +msgstr "" + +#: ../../c-api/module.rst:463 +msgid "" +"Note that this does not process execution slots (:c:data:`Py_mod_exec`). " +"Both ``PyModule_FromDefAndSpec`` and ``PyModule_ExecDef`` must be called to " +"fully initialize a module." +msgstr "" + +#: ../../c-api/module.rst:469 +msgid "" +"Most uses of this function should be using :c:func:`PyModule_FromDefAndSpec` " +"instead; only use this if you are sure you need it." +msgstr "" + +#: ../../c-api/module.rst:476 +msgid "Process any execution slots (:c:data:`Py_mod_exec`) given in *def*." +msgstr "" + +#: ../../c-api/module.rst:482 +msgid "The C API version. Defined for backwards compatibility." +msgstr "" + +#: ../../c-api/module.rst:484 ../../c-api/module.rst:491 +msgid "" +"Currently, this constant is not updated in new Python versions, and is not " +"useful for versioning. This may change in the future." +msgstr "" + +#: ../../c-api/module.rst:489 +msgid "Defined as ``3`` for backwards compatibility." +msgstr "" + +#: ../../c-api/module.rst:496 +msgid "Support functions" +msgstr "支援的函式" + +#: ../../c-api/module.rst:498 +msgid "" +"The following functions are provided to help initialize a module state. They " +"are intended for a module's execution slots (:c:data:`Py_mod_exec`), the " +"initialization function for legacy :ref:`single-phase initialization `, or code that creates modules dynamically." +msgstr "" + +#: ../../c-api/module.rst:506 +msgid "" +"Add an object to *module* as *name*. This is a convenience function which " +"can be used from the module's initialization function." +msgstr "" + +#: ../../c-api/module.rst:509 +msgid "" +"On success, return ``0``. On error, raise an exception and return ``-1``." +msgstr "" + +#: ../../c-api/module.rst:511 ../../c-api/module.rst:562 +#: ../../c-api/module.rst:589 +msgid "Example usage::" +msgstr "用法範例： ::" + +#: ../../c-api/module.rst:513 +msgid "" +"static int\n" +"add_spam(PyObject *module, int value)\n" +"{\n" +" PyObject *obj = PyLong_FromLong(value);\n" +" if (obj == NULL) {\n" +" return -1;\n" +" }\n" +" int res = PyModule_AddObjectRef(module, \"spam\", obj);\n" +" Py_DECREF(obj);\n" +" return res;\n" +" }" +msgstr "" +"static int\n" +"add_spam(PyObject *module, int value)\n" +"{\n" +" PyObject *obj = PyLong_FromLong(value);\n" +" if (obj == NULL) {\n" +" return -1;\n" +" }\n" +" int res = PyModule_AddObjectRef(module, \"spam\", obj);\n" +" Py_DECREF(obj);\n" +" return res;\n" +" }" + +#: ../../c-api/module.rst:525 +msgid "" +"To be convenient, the function accepts ``NULL`` *value* with an exception " +"set. In this case, return ``-1`` and just leave the raised exception " +"unchanged." +msgstr "" + +#: ../../c-api/module.rst:529 +msgid "" +"The example can also be written without checking explicitly if *obj* is " +"``NULL``::" +msgstr "" + +#: ../../c-api/module.rst:532 +msgid "" +"static int\n" +"add_spam(PyObject *module, int value)\n" +"{\n" +" PyObject *obj = PyLong_FromLong(value);\n" +" int res = PyModule_AddObjectRef(module, \"spam\", obj);\n" +" Py_XDECREF(obj);\n" +" return res;\n" +" }" +msgstr "" +"static int\n" +"add_spam(PyObject *module, int value)\n" +"{\n" +" PyObject *obj = PyLong_FromLong(value);\n" +" int res = PyModule_AddObjectRef(module, \"spam\", obj);\n" +" Py_XDECREF(obj);\n" +" return res;\n" +" }" + +#: ../../c-api/module.rst:541 +msgid "" +"Note that ``Py_XDECREF()`` should be used instead of ``Py_DECREF()`` in this " +"case, since *obj* can be ``NULL``." +msgstr "" + +#: ../../c-api/module.rst:544 +msgid "" +"The number of different *name* strings passed to this function should be " +"kept small, usually by only using statically allocated strings as *name*. " +"For names that aren't known at compile time, prefer calling :c:func:" +"`PyUnicode_FromString` and :c:func:`PyObject_SetAttr` directly. For more " +"details, see :c:func:`PyUnicode_InternFromString`, which may be used " +"internally to create a key object." +msgstr "" + +#: ../../c-api/module.rst:557 +msgid "" +"Similar to :c:func:`PyModule_AddObjectRef`, but \"steals\" a reference to " +"*value*. It can be called with a result of function that returns a new " +"reference without bothering to check its result or even saving it to a " +"variable." +msgstr "" + +#: ../../c-api/module.rst:564 +msgid "" +"if (PyModule_Add(module, \"spam\", PyBytes_FromString(value)) < 0) {\n" +" goto error;\n" +"}" +msgstr "" +"if (PyModule_Add(module, \"spam\", PyBytes_FromString(value)) < 0) {\n" +" goto error;\n" +"}" + +#: ../../c-api/module.rst:573 +msgid "" +"Similar to :c:func:`PyModule_AddObjectRef`, but steals a reference to " +"*value* on success (if it returns ``0``)." +msgstr "" +"類似於 :c:func:`PyModule_AddObjectRef`，但在成功時（如果回傳 ``0``）會偷走對 " +"*value* 的參照。" + +#: ../../c-api/module.rst:576 +msgid "" +"The new :c:func:`PyModule_Add` or :c:func:`PyModule_AddObjectRef` functions " +"are recommended, since it is easy to introduce reference leaks by misusing " +"the :c:func:`PyModule_AddObject` function." +msgstr "" + +#: ../../c-api/module.rst:583 +msgid "" +"Unlike other functions that steal references, ``PyModule_AddObject()`` only " +"releases the reference to *value* **on success**." +msgstr "" + +#: ../../c-api/module.rst:586 +msgid "" +"This means that its return value must be checked, and calling code must :c:" +"func:`Py_XDECREF` *value* manually on error." +msgstr "" + +#: ../../c-api/module.rst:591 +msgid "" +"PyObject *obj = PyBytes_FromString(value);\n" +"if (PyModule_AddObject(module, \"spam\", obj) < 0) {\n" +" // If 'obj' is not NULL and PyModule_AddObject() failed,\n" +" // 'obj' strong reference must be deleted with Py_XDECREF().\n" +" // If 'obj' is NULL, Py_XDECREF() does nothing.\n" +" Py_XDECREF(obj);\n" +" goto error;\n" +"}\n" +"// PyModule_AddObject() stole a reference to obj:\n" +"// Py_XDECREF(obj) is not needed here." +msgstr "" + +#: ../../c-api/module.rst:604 +msgid ":c:func:`PyModule_AddObject` is :term:`soft deprecated`." +msgstr "" +":c:func:`PyModule_AddObject` 已被\\ :term:`軟性棄用 `。" + +#: ../../c-api/module.rst:609 +msgid "" +"Add an integer constant to *module* as *name*. This convenience function " +"can be used from the module's initialization function. Return ``-1`` with an " +"exception set on error, ``0`` on success." +msgstr "" + +#: ../../c-api/module.rst:613 +msgid "" +"This is a convenience function that calls :c:func:`PyLong_FromLong` and :c:" +"func:`PyModule_AddObjectRef`; see their documentation for details." +msgstr "" + +#: ../../c-api/module.rst:619 +msgid "" +"Add a string constant to *module* as *name*. This convenience function can " +"be used from the module's initialization function. The string *value* must " +"be ``NULL``-terminated. Return ``-1`` with an exception set on error, ``0`` " +"on success." +msgstr "" + +#: ../../c-api/module.rst:624 +msgid "" +"This is a convenience function that calls :c:func:" +"`PyUnicode_InternFromString` and :c:func:`PyModule_AddObjectRef`; see their " +"documentation for details." +msgstr "" + +#: ../../c-api/module.rst:631 +msgid "" +"Add an int constant to *module*. The name and the value are taken from " +"*macro*. For example ``PyModule_AddIntMacro(module, AF_INET)`` adds the int " +"constant *AF_INET* with the value of *AF_INET* to *module*. Return ``-1`` " +"with an exception set on error, ``0`` on success." +msgstr "" + +#: ../../c-api/module.rst:639 +msgid "Add a string constant to *module*." +msgstr "將字串常數加入到 *module* 中。" + +#: ../../c-api/module.rst:643 +msgid "" +"Add a type object to *module*. The type object is finalized by calling " +"internally :c:func:`PyType_Ready`. The name of the type object is taken from " +"the last component of :c:member:`~PyTypeObject.tp_name` after dot. Return " +"``-1`` with an exception set on error, ``0`` on success." +msgstr "" + +#: ../../c-api/module.rst:653 +msgid "" +"Add the functions from the ``NULL`` terminated *functions* array to " +"*module*. Refer to the :c:type:`PyMethodDef` documentation for details on " +"individual entries (due to the lack of a shared module namespace, module " +"level \"functions\" implemented in C typically receive the module as their " +"first parameter, making them similar to instance methods on Python classes)." +msgstr "" + +#: ../../c-api/module.rst:659 +msgid "" +"This function is called automatically when creating a module from " +"``PyModuleDef`` (such as when using :ref:`multi-phase-initialization`, " +"``PyModule_Create``, or ``PyModule_FromDefAndSpec``). Some module authors " +"may prefer defining functions in multiple :c:type:`PyMethodDef` arrays; in " +"that case they should call this function directly." +msgstr "" + +#: ../../c-api/module.rst:666 +msgid "" +"The *functions* array must be statically allocated (or otherwise guaranteed " +"to outlive the module object)." +msgstr "" + +#: ../../c-api/module.rst:673 +msgid "" +"Set the docstring for *module* to *docstring*. This function is called " +"automatically when creating a module from ``PyModuleDef`` (such as when " +"using :ref:`multi-phase-initialization`, ``PyModule_Create``, or " +"``PyModule_FromDefAndSpec``)." +msgstr "" + +#: ../../c-api/module.rst:682 +msgid "" +"Indicate that *module* does or does not support running without the global " +"interpreter lock (GIL), using one of the values from :c:macro:`Py_mod_gil`. " +"It must be called during *module*'s initialization function when using :ref:" +"`single-phase-initialization`. If this function is not called during module " +"initialization, the import machinery assumes the module does not support " +"running without the GIL. This function is only available in Python builds " +"configured with :option:`--disable-gil`. Return ``-1`` with an exception set " +"on error, ``0`` on success." +msgstr "" + +#: ../../c-api/module.rst:696 +msgid "Module lookup (single-phase initialization)" +msgstr "" + +#: ../../c-api/module.rst:698 +msgid "" +"The legacy :ref:`single-phase initialization ` " +"initialization scheme creates singleton modules that can be looked up in the " +"context of the current interpreter. This allows the module object to be " +"retrieved later with only a reference to the module definition." +msgstr "" + +#: ../../c-api/module.rst:703 +msgid "" +"These functions will not work on modules created using multi-phase " +"initialization, since multiple such modules can be created from a single " +"definition." +msgstr "" + +#: ../../c-api/module.rst:708 +msgid "" +"Returns the module object that was created from *def* for the current " +"interpreter. This method requires that the module object has been attached " +"to the interpreter state with :c:func:`PyState_AddModule` beforehand. In " +"case the corresponding module object is not found or has not been attached " +"to the interpreter state yet, it returns ``NULL``." +msgstr "" + +#: ../../c-api/module.rst:715 +msgid "" +"Attaches the module object passed to the function to the interpreter state. " +"This allows the module object to be accessible via :c:func:" +"`PyState_FindModule`." +msgstr "" + +#: ../../c-api/module.rst:718 +msgid "Only effective on modules created using single-phase initialization." +msgstr "" + +#: ../../c-api/module.rst:720 +msgid "" +"Python calls ``PyState_AddModule`` automatically after importing a module " +"that uses :ref:`single-phase initialization `, " +"so it is unnecessary (but harmless) to call it from module initialization " +"code. An explicit call is needed only if the module's own init code " +"subsequently calls ``PyState_FindModule``. The function is mainly intended " +"for implementing alternative import mechanisms (either by calling it " +"directly, or by referring to its implementation for details of the required " +"state updates)." +msgstr "" + +#: ../../c-api/module.rst:729 +msgid "" +"If a module was attached previously using the same *def*, it is replaced by " +"the new *module*." +msgstr "" + +#: ../../c-api/module.rst:732 ../../c-api/module.rst:743 +msgid "The caller must have an :term:`attached thread state`." +msgstr "" + +#: ../../c-api/module.rst:734 +msgid "Return ``-1`` with an exception set on error, ``0`` on success." +msgstr "成功時回傳 ``0``，在失敗時回傳 ``-1`` 並設定例外。" + +#: ../../c-api/module.rst:740 +msgid "" +"Removes the module object created from *def* from the interpreter state. " +"Return ``-1`` with an exception set on error, ``0`` on success." +msgstr "" + +#: ../../c-api/module.rst:8 +msgid "object" +msgstr "object（模組）" + +#: ../../c-api/module.rst:8 +msgid "module" +msgstr "module（模組）" + +#: ../../c-api/module.rst:13 +msgid "ModuleType (in module types)" +msgstr "MethodType（types 模組中）" + +#: ../../c-api/module.rst:33 ../../c-api/module.rst:80 +msgid "__name__ (module attribute)" +msgstr "__name__（模組屬性）" + +#: ../../c-api/module.rst:33 +msgid "__doc__ (module attribute)" +msgstr "__doc__（模組屬性）" + +#: ../../c-api/module.rst:33 ../../c-api/module.rst:119 +msgid "__file__ (module attribute)" +msgstr "__file__（模組屬性）" + +#: ../../c-api/module.rst:33 +msgid "__package__ (module attribute)" +msgstr "__package__（模組屬性）" + +#: ../../c-api/module.rst:33 +msgid "__loader__ (module attribute)" +msgstr "__loader__（模組屬性）" + +#: ../../c-api/module.rst:63 +msgid "__dict__ (module attribute)" +msgstr "__dict__（模組屬性）" + +#: ../../c-api/module.rst:80 ../../c-api/module.rst:119 +msgid "SystemError (built-in exception)" +msgstr "SystemError（內建例外）" diff --git a/c-api/monitoring.po b/c-api/monitoring.po index 8c2bc0c80c..0890bbb591 100644 --- a/c-api/monitoring.po +++ b/c-api/monitoring.po @@ -1,302 +1,302 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -#, fuzzy -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-05 00:16+0000\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \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" - -#: ../../c-api/monitoring.rst:6 -msgid "Monitoring C API" -msgstr "監控 C API" - -#: ../../c-api/monitoring.rst:8 -msgid "Added in version 3.13." -msgstr "於 3.13 版本中新增。" - -#: ../../c-api/monitoring.rst:10 -msgid "" -"An extension may need to interact with the event monitoring system. " -"Subscribing to events and registering callbacks can be done via the Python " -"API exposed in :mod:`sys.monitoring`." -msgstr "" - -#: ../../c-api/monitoring.rst:15 -msgid "Generating Execution Events" -msgstr "" - -#: ../../c-api/monitoring.rst:17 -msgid "" -"The functions below make it possible for an extension to fire monitoring " -"events as it emulates the execution of Python code. Each of these functions " -"accepts a ``PyMonitoringState`` struct which contains concise information " -"about the activation state of events, as well as the event arguments, which " -"include a ``PyObject*`` representing the code object, the instruction offset " -"and sometimes additional, event-specific arguments (see :mod:`sys." -"monitoring` for details about the signatures of the different event " -"callbacks). The ``codelike`` argument should be an instance of :class:`types." -"CodeType` or of a type that emulates it." -msgstr "" - -#: ../../c-api/monitoring.rst:27 -msgid "" -"The VM disables tracing when firing an event, so there is no need for user " -"code to do that." -msgstr "" - -#: ../../c-api/monitoring.rst:30 -msgid "" -"Monitoring functions should not be called with an exception set, except " -"those listed below as working with the current exception." -msgstr "" - -#: ../../c-api/monitoring.rst:35 -msgid "" -"Representation of the state of an event type. It is allocated by the user " -"while its contents are maintained by the monitoring API functions described " -"below." -msgstr "" - -#: ../../c-api/monitoring.rst:39 -msgid "" -"All of the functions below return 0 on success and -1 (with an exception " -"set) on error." -msgstr "" - -#: ../../c-api/monitoring.rst:41 -msgid "See :mod:`sys.monitoring` for descriptions of the events." -msgstr "關於事件的敘述請見 :mod:`sys.monitoring`。" - -#: ../../c-api/monitoring.rst:45 -msgid "Fire a ``PY_START`` event." -msgstr "發出一個 ``PY_START`` 事件。" - -#: ../../c-api/monitoring.rst:50 -msgid "Fire a ``PY_RESUME`` event." -msgstr "發出一個 ``PY_RESUME`` 事件。" - -#: ../../c-api/monitoring.rst:55 -msgid "Fire a ``PY_RETURN`` event." -msgstr "發出一個 ``PY_RETURN`` 事件。" - -#: ../../c-api/monitoring.rst:60 -msgid "Fire a ``PY_YIELD`` event." -msgstr "發出一個 ``PY_YIELD`` 事件。" - -#: ../../c-api/monitoring.rst:65 -msgid "Fire a ``CALL`` event." -msgstr "發出一個 ``CALL`` 事件。" - -#: ../../c-api/monitoring.rst:70 -msgid "Fire a ``LINE`` event." -msgstr "發出一個 ``LINE`` 事件。" - -#: ../../c-api/monitoring.rst:75 -msgid "Fire a ``JUMP`` event." -msgstr "發出一個 ``JUMP`` 事件。" - -#: ../../c-api/monitoring.rst:80 -msgid "Fire a ``BRANCH_LEFT`` event." -msgstr "發出一個 ``BRANCH_LEFT`` 事件。" - -#: ../../c-api/monitoring.rst:85 -msgid "Fire a ``BRANCH_RIGHT`` event." -msgstr "發出一個 ``BRANCH_RIGHT`` 事件。" - -#: ../../c-api/monitoring.rst:90 -msgid "Fire a ``C_RETURN`` event." -msgstr "發出一個 ``C_RETURN`` 事件。" - -#: ../../c-api/monitoring.rst:95 -msgid "" -"Fire a ``PY_THROW`` event with the current exception (as returned by :c:func:" -"`PyErr_GetRaisedException`)." -msgstr "" - -#: ../../c-api/monitoring.rst:101 -msgid "" -"Fire a ``RAISE`` event with the current exception (as returned by :c:func:" -"`PyErr_GetRaisedException`)." -msgstr "" - -#: ../../c-api/monitoring.rst:107 -msgid "" -"Fire a ``C_RAISE`` event with the current exception (as returned by :c:func:" -"`PyErr_GetRaisedException`)." -msgstr "" - -#: ../../c-api/monitoring.rst:113 -msgid "" -"Fire a ``RERAISE`` event with the current exception (as returned by :c:func:" -"`PyErr_GetRaisedException`)." -msgstr "" - -#: ../../c-api/monitoring.rst:119 -msgid "" -"Fire an ``EXCEPTION_HANDLED`` event with the current exception (as returned " -"by :c:func:`PyErr_GetRaisedException`)." -msgstr "" - -#: ../../c-api/monitoring.rst:125 -msgid "" -"Fire a ``PY_UNWIND`` event with the current exception (as returned by :c:" -"func:`PyErr_GetRaisedException`)." -msgstr "" - -#: ../../c-api/monitoring.rst:131 -msgid "" -"Fire a ``STOP_ITERATION`` event. If ``value`` is an instance of :exc:" -"`StopIteration`, it is used. Otherwise, a new :exc:`StopIteration` instance " -"is created with ``value`` as its argument." -msgstr "" - -#: ../../c-api/monitoring.rst:136 -msgid "Managing the Monitoring State" -msgstr "" - -#: ../../c-api/monitoring.rst:138 -msgid "" -"Monitoring states can be managed with the help of monitoring scopes. A scope " -"would typically correspond to a Python function." -msgstr "" - -#: ../../c-api/monitoring.rst:143 -msgid "" -"Enter a monitored scope. ``event_types`` is an array of the event IDs for " -"events that may be fired from the scope. For example, the ID of a " -"``PY_START`` event is the value ``PY_MONITORING_EVENT_PY_START``, which is " -"numerically equal to the base-2 logarithm of ``sys.monitoring.events." -"PY_START``. ``state_array`` is an array with a monitoring state entry for " -"each event in ``event_types``, it is allocated by the user but populated by :" -"c:func:`!PyMonitoring_EnterScope` with information about the activation " -"state of the event. The size of ``event_types`` (and hence also of " -"``state_array``) is given in ``length``." -msgstr "" - -#: ../../c-api/monitoring.rst:153 -msgid "" -"The ``version`` argument is a pointer to a value which should be allocated " -"by the user together with ``state_array`` and initialized to 0, and then set " -"only by :c:func:`!PyMonitoring_EnterScope` itself. It allows this function " -"to determine whether event states have changed since the previous call, and " -"to return quickly if they have not." -msgstr "" - -#: ../../c-api/monitoring.rst:159 -msgid "" -"The scopes referred to here are lexical scopes: a function, class or " -"method. :c:func:`!PyMonitoring_EnterScope` should be called whenever the " -"lexical scope is entered. Scopes can be reentered, reusing the same " -"*state_array* and *version*, in situations like when emulating a recursive " -"Python function. When a code-like's execution is paused, such as when " -"emulating a generator, the scope needs to be exited and re-entered." -msgstr "" - -#: ../../c-api/monitoring.rst:166 -msgid "The macros for *event_types* are:" -msgstr "*event_types* 的巨集有：" - -#: ../../c-api/monitoring.rst:174 -msgid "Macro" -msgstr "巨集" - -#: ../../c-api/monitoring.rst:174 -msgid "Event" -msgstr "事件" - -#: ../../c-api/monitoring.rst:176 -msgid ":monitoring-event:`BRANCH_LEFT`" -msgstr ":monitoring-event:`BRANCH_LEFT`" - -#: ../../c-api/monitoring.rst:177 -msgid ":monitoring-event:`BRANCH_RIGHT`" -msgstr ":monitoring-event:`BRANCH_RIGHT`" - -#: ../../c-api/monitoring.rst:178 -msgid ":monitoring-event:`CALL`" -msgstr ":monitoring-event:`CALL`" - -#: ../../c-api/monitoring.rst:179 -msgid ":monitoring-event:`C_RAISE`" -msgstr ":monitoring-event:`C_RAISE`" - -#: ../../c-api/monitoring.rst:180 -msgid ":monitoring-event:`C_RETURN`" -msgstr ":monitoring-event:`C_RETURN`" - -#: ../../c-api/monitoring.rst:181 -msgid ":monitoring-event:`EXCEPTION_HANDLED`" -msgstr ":monitoring-event:`EXCEPTION_HANDLED`" - -#: ../../c-api/monitoring.rst:182 -msgid ":monitoring-event:`INSTRUCTION`" -msgstr ":monitoring-event:`INSTRUCTION`" - -#: ../../c-api/monitoring.rst:183 -msgid ":monitoring-event:`JUMP`" -msgstr ":monitoring-event:`JUMP`" - -#: ../../c-api/monitoring.rst:184 -msgid ":monitoring-event:`LINE`" -msgstr ":monitoring-event:`LINE`" - -#: ../../c-api/monitoring.rst:185 -msgid ":monitoring-event:`PY_RESUME`" -msgstr ":monitoring-event:`PY_RESUME`" - -#: ../../c-api/monitoring.rst:186 -msgid ":monitoring-event:`PY_RETURN`" -msgstr ":monitoring-event:`PY_RETURN`" - -#: ../../c-api/monitoring.rst:187 -msgid ":monitoring-event:`PY_START`" -msgstr ":monitoring-event:`PY_START`" - -#: ../../c-api/monitoring.rst:188 -msgid ":monitoring-event:`PY_THROW`" -msgstr ":monitoring-event:`PY_THROW`" - -#: ../../c-api/monitoring.rst:189 -msgid ":monitoring-event:`PY_UNWIND`" -msgstr ":monitoring-event:`PY_UNWIND`" - -#: ../../c-api/monitoring.rst:190 -msgid ":monitoring-event:`PY_YIELD`" -msgstr ":monitoring-event:`PY_YIELD`" - -#: ../../c-api/monitoring.rst:191 -msgid ":monitoring-event:`RAISE`" -msgstr ":monitoring-event:`RAISE`" - -#: ../../c-api/monitoring.rst:192 -msgid ":monitoring-event:`RERAISE`" -msgstr ":monitoring-event:`RERAISE`" - -#: ../../c-api/monitoring.rst:193 -msgid ":monitoring-event:`STOP_ITERATION`" -msgstr ":monitoring-event:`STOP_ITERATION`" - -#: ../../c-api/monitoring.rst:198 -msgid "" -"Exit the last scope that was entered with :c:func:`!PyMonitoring_EnterScope`." -msgstr "" - -#: ../../c-api/monitoring.rst:203 -msgid "" -"Return true if the event corresponding to the event ID *ev* is a :ref:`local " -"event `." -msgstr "" - -#: ../../c-api/monitoring.rst:210 -msgid "This function is :term:`soft deprecated`." -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-05 00:16+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \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" + +#: ../../c-api/monitoring.rst:6 +msgid "Monitoring C API" +msgstr "監控 C API" + +#: ../../c-api/monitoring.rst:8 +msgid "Added in version 3.13." +msgstr "於 3.13 版本中新增。" + +#: ../../c-api/monitoring.rst:10 +msgid "" +"An extension may need to interact with the event monitoring system. " +"Subscribing to events and registering callbacks can be done via the Python " +"API exposed in :mod:`sys.monitoring`." +msgstr "" + +#: ../../c-api/monitoring.rst:15 +msgid "Generating Execution Events" +msgstr "" + +#: ../../c-api/monitoring.rst:17 +msgid "" +"The functions below make it possible for an extension to fire monitoring " +"events as it emulates the execution of Python code. Each of these functions " +"accepts a ``PyMonitoringState`` struct which contains concise information " +"about the activation state of events, as well as the event arguments, which " +"include a ``PyObject*`` representing the code object, the instruction offset " +"and sometimes additional, event-specific arguments (see :mod:`sys." +"monitoring` for details about the signatures of the different event " +"callbacks). The ``codelike`` argument should be an instance of :class:`types." +"CodeType` or of a type that emulates it." +msgstr "" + +#: ../../c-api/monitoring.rst:27 +msgid "" +"The VM disables tracing when firing an event, so there is no need for user " +"code to do that." +msgstr "" + +#: ../../c-api/monitoring.rst:30 +msgid "" +"Monitoring functions should not be called with an exception set, except " +"those listed below as working with the current exception." +msgstr "" + +#: ../../c-api/monitoring.rst:35 +msgid "" +"Representation of the state of an event type. It is allocated by the user " +"while its contents are maintained by the monitoring API functions described " +"below." +msgstr "" + +#: ../../c-api/monitoring.rst:39 +msgid "" +"All of the functions below return 0 on success and -1 (with an exception " +"set) on error." +msgstr "" + +#: ../../c-api/monitoring.rst:41 +msgid "See :mod:`sys.monitoring` for descriptions of the events." +msgstr "關於事件的敘述請見 :mod:`sys.monitoring`。" + +#: ../../c-api/monitoring.rst:45 +msgid "Fire a ``PY_START`` event." +msgstr "發出一個 ``PY_START`` 事件。" + +#: ../../c-api/monitoring.rst:50 +msgid "Fire a ``PY_RESUME`` event." +msgstr "發出一個 ``PY_RESUME`` 事件。" + +#: ../../c-api/monitoring.rst:55 +msgid "Fire a ``PY_RETURN`` event." +msgstr "發出一個 ``PY_RETURN`` 事件。" + +#: ../../c-api/monitoring.rst:60 +msgid "Fire a ``PY_YIELD`` event." +msgstr "發出一個 ``PY_YIELD`` 事件。" + +#: ../../c-api/monitoring.rst:65 +msgid "Fire a ``CALL`` event." +msgstr "發出一個 ``CALL`` 事件。" + +#: ../../c-api/monitoring.rst:70 +msgid "Fire a ``LINE`` event." +msgstr "發出一個 ``LINE`` 事件。" + +#: ../../c-api/monitoring.rst:75 +msgid "Fire a ``JUMP`` event." +msgstr "發出一個 ``JUMP`` 事件。" + +#: ../../c-api/monitoring.rst:80 +msgid "Fire a ``BRANCH_LEFT`` event." +msgstr "發出一個 ``BRANCH_LEFT`` 事件。" + +#: ../../c-api/monitoring.rst:85 +msgid "Fire a ``BRANCH_RIGHT`` event." +msgstr "發出一個 ``BRANCH_RIGHT`` 事件。" + +#: ../../c-api/monitoring.rst:90 +msgid "Fire a ``C_RETURN`` event." +msgstr "發出一個 ``C_RETURN`` 事件。" + +#: ../../c-api/monitoring.rst:95 +msgid "" +"Fire a ``PY_THROW`` event with the current exception (as returned by :c:func:" +"`PyErr_GetRaisedException`)." +msgstr "" + +#: ../../c-api/monitoring.rst:101 +msgid "" +"Fire a ``RAISE`` event with the current exception (as returned by :c:func:" +"`PyErr_GetRaisedException`)." +msgstr "" + +#: ../../c-api/monitoring.rst:107 +msgid "" +"Fire a ``C_RAISE`` event with the current exception (as returned by :c:func:" +"`PyErr_GetRaisedException`)." +msgstr "" + +#: ../../c-api/monitoring.rst:113 +msgid "" +"Fire a ``RERAISE`` event with the current exception (as returned by :c:func:" +"`PyErr_GetRaisedException`)." +msgstr "" + +#: ../../c-api/monitoring.rst:119 +msgid "" +"Fire an ``EXCEPTION_HANDLED`` event with the current exception (as returned " +"by :c:func:`PyErr_GetRaisedException`)." +msgstr "" + +#: ../../c-api/monitoring.rst:125 +msgid "" +"Fire a ``PY_UNWIND`` event with the current exception (as returned by :c:" +"func:`PyErr_GetRaisedException`)." +msgstr "" + +#: ../../c-api/monitoring.rst:131 +msgid "" +"Fire a ``STOP_ITERATION`` event. If ``value`` is an instance of :exc:" +"`StopIteration`, it is used. Otherwise, a new :exc:`StopIteration` instance " +"is created with ``value`` as its argument." +msgstr "" + +#: ../../c-api/monitoring.rst:136 +msgid "Managing the Monitoring State" +msgstr "" + +#: ../../c-api/monitoring.rst:138 +msgid "" +"Monitoring states can be managed with the help of monitoring scopes. A scope " +"would typically correspond to a Python function." +msgstr "" + +#: ../../c-api/monitoring.rst:143 +msgid "" +"Enter a monitored scope. ``event_types`` is an array of the event IDs for " +"events that may be fired from the scope. For example, the ID of a " +"``PY_START`` event is the value ``PY_MONITORING_EVENT_PY_START``, which is " +"numerically equal to the base-2 logarithm of ``sys.monitoring.events." +"PY_START``. ``state_array`` is an array with a monitoring state entry for " +"each event in ``event_types``, it is allocated by the user but populated by :" +"c:func:`!PyMonitoring_EnterScope` with information about the activation " +"state of the event. The size of ``event_types`` (and hence also of " +"``state_array``) is given in ``length``." +msgstr "" + +#: ../../c-api/monitoring.rst:153 +msgid "" +"The ``version`` argument is a pointer to a value which should be allocated " +"by the user together with ``state_array`` and initialized to 0, and then set " +"only by :c:func:`!PyMonitoring_EnterScope` itself. It allows this function " +"to determine whether event states have changed since the previous call, and " +"to return quickly if they have not." +msgstr "" + +#: ../../c-api/monitoring.rst:159 +msgid "" +"The scopes referred to here are lexical scopes: a function, class or " +"method. :c:func:`!PyMonitoring_EnterScope` should be called whenever the " +"lexical scope is entered. Scopes can be reentered, reusing the same " +"*state_array* and *version*, in situations like when emulating a recursive " +"Python function. When a code-like's execution is paused, such as when " +"emulating a generator, the scope needs to be exited and re-entered." +msgstr "" + +#: ../../c-api/monitoring.rst:166 +msgid "The macros for *event_types* are:" +msgstr "*event_types* 的巨集有：" + +#: ../../c-api/monitoring.rst:174 +msgid "Macro" +msgstr "巨集" + +#: ../../c-api/monitoring.rst:174 +msgid "Event" +msgstr "事件" + +#: ../../c-api/monitoring.rst:176 +msgid ":monitoring-event:`BRANCH_LEFT`" +msgstr ":monitoring-event:`BRANCH_LEFT`" + +#: ../../c-api/monitoring.rst:177 +msgid ":monitoring-event:`BRANCH_RIGHT`" +msgstr ":monitoring-event:`BRANCH_RIGHT`" + +#: ../../c-api/monitoring.rst:178 +msgid ":monitoring-event:`CALL`" +msgstr ":monitoring-event:`CALL`" + +#: ../../c-api/monitoring.rst:179 +msgid ":monitoring-event:`C_RAISE`" +msgstr ":monitoring-event:`C_RAISE`" + +#: ../../c-api/monitoring.rst:180 +msgid ":monitoring-event:`C_RETURN`" +msgstr ":monitoring-event:`C_RETURN`" + +#: ../../c-api/monitoring.rst:181 +msgid ":monitoring-event:`EXCEPTION_HANDLED`" +msgstr ":monitoring-event:`EXCEPTION_HANDLED`" + +#: ../../c-api/monitoring.rst:182 +msgid ":monitoring-event:`INSTRUCTION`" +msgstr ":monitoring-event:`INSTRUCTION`" + +#: ../../c-api/monitoring.rst:183 +msgid ":monitoring-event:`JUMP`" +msgstr ":monitoring-event:`JUMP`" + +#: ../../c-api/monitoring.rst:184 +msgid ":monitoring-event:`LINE`" +msgstr ":monitoring-event:`LINE`" + +#: ../../c-api/monitoring.rst:185 +msgid ":monitoring-event:`PY_RESUME`" +msgstr ":monitoring-event:`PY_RESUME`" + +#: ../../c-api/monitoring.rst:186 +msgid ":monitoring-event:`PY_RETURN`" +msgstr ":monitoring-event:`PY_RETURN`" + +#: ../../c-api/monitoring.rst:187 +msgid ":monitoring-event:`PY_START`" +msgstr ":monitoring-event:`PY_START`" + +#: ../../c-api/monitoring.rst:188 +msgid ":monitoring-event:`PY_THROW`" +msgstr ":monitoring-event:`PY_THROW`" + +#: ../../c-api/monitoring.rst:189 +msgid ":monitoring-event:`PY_UNWIND`" +msgstr ":monitoring-event:`PY_UNWIND`" + +#: ../../c-api/monitoring.rst:190 +msgid ":monitoring-event:`PY_YIELD`" +msgstr ":monitoring-event:`PY_YIELD`" + +#: ../../c-api/monitoring.rst:191 +msgid ":monitoring-event:`RAISE`" +msgstr ":monitoring-event:`RAISE`" + +#: ../../c-api/monitoring.rst:192 +msgid ":monitoring-event:`RERAISE`" +msgstr ":monitoring-event:`RERAISE`" + +#: ../../c-api/monitoring.rst:193 +msgid ":monitoring-event:`STOP_ITERATION`" +msgstr ":monitoring-event:`STOP_ITERATION`" + +#: ../../c-api/monitoring.rst:198 +msgid "" +"Exit the last scope that was entered with :c:func:`!PyMonitoring_EnterScope`." +msgstr "" + +#: ../../c-api/monitoring.rst:203 +msgid "" +"Return true if the event corresponding to the event ID *ev* is a :ref:`local " +"event `." +msgstr "" + +#: ../../c-api/monitoring.rst:210 +msgid "This function is :term:`soft deprecated`." +msgstr "" diff --git a/c-api/none.po b/c-api/none.po index 675650b020..f34c163c68 100644 --- a/c-api/none.po +++ b/c-api/none.po @@ -1,53 +1,53 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Leon H., 2017 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-09-23 07:52+0800\n" -"PO-Revision-Date: 2018-05-23 14: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" - -#: ../../c-api/none.rst:6 -msgid "The ``None`` Object" -msgstr "``None`` 物件" - -#: ../../c-api/none.rst:10 -msgid "" -"Note that the :c:type:`PyTypeObject` for ``None`` is not directly exposed in " -"the Python/C API. Since ``None`` is a singleton, testing for object " -"identity (using ``==`` in C) is sufficient. There is no :c:func:`!" -"PyNone_Check` function for the same reason." -msgstr "" - -#: ../../c-api/none.rst:18 -msgid "" -"The Python ``None`` object, denoting lack of value. This object has no " -"methods and is :term:`immortal`." -msgstr "" - -#: ../../c-api/none.rst:21 -msgid ":c:data:`Py_None` is :term:`immortal`." -msgstr ":c:data:`Py_None` 為\\ :term:`不滅的 (immortal) `。" - -#: ../../c-api/none.rst:26 -msgid "Return :c:data:`Py_None` from a function." -msgstr "" - -#: ../../c-api/none.rst:8 -msgid "object" -msgstr "object（物件）" - -#: ../../c-api/none.rst:8 -msgid "None" -msgstr "None" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Leon H., 2017 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-09-23 07:52+0800\n" +"PO-Revision-Date: 2018-05-23 14: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" + +#: ../../c-api/none.rst:6 +msgid "The ``None`` Object" +msgstr "``None`` 物件" + +#: ../../c-api/none.rst:10 +msgid "" +"Note that the :c:type:`PyTypeObject` for ``None`` is not directly exposed in " +"the Python/C API. Since ``None`` is a singleton, testing for object " +"identity (using ``==`` in C) is sufficient. There is no :c:func:`!" +"PyNone_Check` function for the same reason." +msgstr "" + +#: ../../c-api/none.rst:18 +msgid "" +"The Python ``None`` object, denoting lack of value. This object has no " +"methods and is :term:`immortal`." +msgstr "" + +#: ../../c-api/none.rst:21 +msgid ":c:data:`Py_None` is :term:`immortal`." +msgstr ":c:data:`Py_None` 為\\ :term:`不滅的 (immortal) `。" + +#: ../../c-api/none.rst:26 +msgid "Return :c:data:`Py_None` from a function." +msgstr "" + +#: ../../c-api/none.rst:8 +msgid "object" +msgstr "object（物件）" + +#: ../../c-api/none.rst:8 +msgid "None" +msgstr "None" diff --git a/c-api/number.po b/c-api/number.po index 66d782afb5..1111e55e7c 100644 --- a/c-api/number.po +++ b/c-api/number.po @@ -1,327 +1,327 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-07-20 00:03+0000\n" -"PO-Revision-Date: 2018-05-23 14: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" - -#: ../../c-api/number.rst:6 -msgid "Number Protocol" -msgstr "數字協定" - -#: ../../c-api/number.rst:11 -msgid "" -"Returns ``1`` if the object *o* provides numeric protocols, and false " -"otherwise. This function always succeeds." -msgstr "" - -#: ../../c-api/number.rst:14 -msgid "Returns ``1`` if *o* is an index integer." -msgstr "" - -#: ../../c-api/number.rst:20 -msgid "" -"Returns the result of adding *o1* and *o2*, or ``NULL`` on failure. This is " -"the equivalent of the Python expression ``o1 + o2``." -msgstr "" - -#: ../../c-api/number.rst:26 -msgid "" -"Returns the result of subtracting *o2* from *o1*, or ``NULL`` on failure. " -"This is the equivalent of the Python expression ``o1 - o2``." -msgstr "" - -#: ../../c-api/number.rst:32 -msgid "" -"Returns the result of multiplying *o1* and *o2*, or ``NULL`` on failure. " -"This is the equivalent of the Python expression ``o1 * o2``." -msgstr "" - -#: ../../c-api/number.rst:38 -msgid "" -"Returns the result of matrix multiplication on *o1* and *o2*, or ``NULL`` on " -"failure. This is the equivalent of the Python expression ``o1 @ o2``." -msgstr "" - -#: ../../c-api/number.rst:46 -msgid "" -"Return the floor of *o1* divided by *o2*, or ``NULL`` on failure. This is " -"the equivalent of the Python expression ``o1 // o2``." -msgstr "" - -#: ../../c-api/number.rst:52 -msgid "" -"Return a reasonable approximation for the mathematical value of *o1* divided " -"by *o2*, or ``NULL`` on failure. The return value is \"approximate\" " -"because binary floating-point numbers are approximate; it is not possible to " -"represent all real numbers in base two. This function can return a floating-" -"point value when passed two integers. This is the equivalent of the Python " -"expression ``o1 / o2``." -msgstr "" - -#: ../../c-api/number.rst:61 -msgid "" -"Returns the remainder of dividing *o1* by *o2*, or ``NULL`` on failure. " -"This is the equivalent of the Python expression ``o1 % o2``." -msgstr "" - -#: ../../c-api/number.rst:69 -msgid "" -"See the built-in function :func:`divmod`. Returns ``NULL`` on failure. This " -"is the equivalent of the Python expression ``divmod(o1, o2)``." -msgstr "" - -#: ../../c-api/number.rst:77 -msgid "" -"See the built-in function :func:`pow`. Returns ``NULL`` on failure. This is " -"the equivalent of the Python expression ``pow(o1, o2, o3)``, where *o3* is " -"optional. If *o3* is to be ignored, pass :c:data:`Py_None` in its place " -"(passing ``NULL`` for *o3* would cause an illegal memory access)." -msgstr "" - -#: ../../c-api/number.rst:85 -msgid "" -"Returns the negation of *o* on success, or ``NULL`` on failure. This is the " -"equivalent of the Python expression ``-o``." -msgstr "" - -#: ../../c-api/number.rst:91 -msgid "" -"Returns *o* on success, or ``NULL`` on failure. This is the equivalent of " -"the Python expression ``+o``." -msgstr "" - -#: ../../c-api/number.rst:99 -msgid "" -"Returns the absolute value of *o*, or ``NULL`` on failure. This is the " -"equivalent of the Python expression ``abs(o)``." -msgstr "" - -#: ../../c-api/number.rst:105 -msgid "" -"Returns the bitwise negation of *o* on success, or ``NULL`` on failure. " -"This is the equivalent of the Python expression ``~o``." -msgstr "" - -#: ../../c-api/number.rst:111 -msgid "" -"Returns the result of left shifting *o1* by *o2* on success, or ``NULL`` on " -"failure. This is the equivalent of the Python expression ``o1 << o2``." -msgstr "" - -#: ../../c-api/number.rst:117 -msgid "" -"Returns the result of right shifting *o1* by *o2* on success, or ``NULL`` on " -"failure. This is the equivalent of the Python expression ``o1 >> o2``." -msgstr "" - -#: ../../c-api/number.rst:123 -msgid "" -"Returns the \"bitwise and\" of *o1* and *o2* on success and ``NULL`` on " -"failure. This is the equivalent of the Python expression ``o1 & o2``." -msgstr "" - -#: ../../c-api/number.rst:129 -msgid "" -"Returns the \"bitwise exclusive or\" of *o1* by *o2* on success, or ``NULL`` " -"on failure. This is the equivalent of the Python expression ``o1 ^ o2``." -msgstr "" - -#: ../../c-api/number.rst:135 -msgid "" -"Returns the \"bitwise or\" of *o1* and *o2* on success, or ``NULL`` on " -"failure. This is the equivalent of the Python expression ``o1 | o2``." -msgstr "" - -#: ../../c-api/number.rst:141 -msgid "" -"Returns the result of adding *o1* and *o2*, or ``NULL`` on failure. The " -"operation is done *in-place* when *o1* supports it. This is the equivalent " -"of the Python statement ``o1 += o2``." -msgstr "" - -#: ../../c-api/number.rst:148 -msgid "" -"Returns the result of subtracting *o2* from *o1*, or ``NULL`` on failure. " -"The operation is done *in-place* when *o1* supports it. This is the " -"equivalent of the Python statement ``o1 -= o2``." -msgstr "" - -#: ../../c-api/number.rst:155 -msgid "" -"Returns the result of multiplying *o1* and *o2*, or ``NULL`` on failure. " -"The operation is done *in-place* when *o1* supports it. This is the " -"equivalent of the Python statement ``o1 *= o2``." -msgstr "" - -#: ../../c-api/number.rst:162 -msgid "" -"Returns the result of matrix multiplication on *o1* and *o2*, or ``NULL`` on " -"failure. The operation is done *in-place* when *o1* supports it. This is " -"the equivalent of the Python statement ``o1 @= o2``." -msgstr "" - -#: ../../c-api/number.rst:171 -msgid "" -"Returns the mathematical floor of dividing *o1* by *o2*, or ``NULL`` on " -"failure. The operation is done *in-place* when *o1* supports it. This is " -"the equivalent of the Python statement ``o1 //= o2``." -msgstr "" - -#: ../../c-api/number.rst:178 -msgid "" -"Return a reasonable approximation for the mathematical value of *o1* divided " -"by *o2*, or ``NULL`` on failure. The return value is \"approximate\" " -"because binary floating-point numbers are approximate; it is not possible to " -"represent all real numbers in base two. This function can return a floating-" -"point value when passed two integers. The operation is done *in-place* when " -"*o1* supports it. This is the equivalent of the Python statement ``o1 /= " -"o2``." -msgstr "" - -#: ../../c-api/number.rst:188 -msgid "" -"Returns the remainder of dividing *o1* by *o2*, or ``NULL`` on failure. The " -"operation is done *in-place* when *o1* supports it. This is the equivalent " -"of the Python statement ``o1 %= o2``." -msgstr "" - -#: ../../c-api/number.rst:197 -msgid "" -"See the built-in function :func:`pow`. Returns ``NULL`` on failure. The " -"operation is done *in-place* when *o1* supports it. This is the equivalent " -"of the Python statement ``o1 **= o2`` when o3 is :c:data:`Py_None`, or an in-" -"place variant of ``pow(o1, o2, o3)`` otherwise. If *o3* is to be ignored, " -"pass :c:data:`Py_None` in its place (passing ``NULL`` for *o3* would cause " -"an illegal memory access)." -msgstr "" - -#: ../../c-api/number.rst:206 -msgid "" -"Returns the result of left shifting *o1* by *o2* on success, or ``NULL`` on " -"failure. The operation is done *in-place* when *o1* supports it. This is " -"the equivalent of the Python statement ``o1 <<= o2``." -msgstr "" - -#: ../../c-api/number.rst:213 -msgid "" -"Returns the result of right shifting *o1* by *o2* on success, or ``NULL`` on " -"failure. The operation is done *in-place* when *o1* supports it. This is " -"the equivalent of the Python statement ``o1 >>= o2``." -msgstr "" - -#: ../../c-api/number.rst:220 -msgid "" -"Returns the \"bitwise and\" of *o1* and *o2* on success and ``NULL`` on " -"failure. The operation is done *in-place* when *o1* supports it. This is " -"the equivalent of the Python statement ``o1 &= o2``." -msgstr "" - -#: ../../c-api/number.rst:227 -msgid "" -"Returns the \"bitwise exclusive or\" of *o1* by *o2* on success, or ``NULL`` " -"on failure. The operation is done *in-place* when *o1* supports it. This " -"is the equivalent of the Python statement ``o1 ^= o2``." -msgstr "" - -#: ../../c-api/number.rst:234 -msgid "" -"Returns the \"bitwise or\" of *o1* and *o2* on success, or ``NULL`` on " -"failure. The operation is done *in-place* when *o1* supports it. This is " -"the equivalent of the Python statement ``o1 |= o2``." -msgstr "" - -#: ../../c-api/number.rst:243 -msgid "" -"Returns the *o* converted to an integer object on success, or ``NULL`` on " -"failure. This is the equivalent of the Python expression ``int(o)``." -msgstr "" - -#: ../../c-api/number.rst:251 -msgid "" -"Returns the *o* converted to a float object on success, or ``NULL`` on " -"failure. This is the equivalent of the Python expression ``float(o)``." -msgstr "" - -#: ../../c-api/number.rst:257 -msgid "" -"Returns the *o* converted to a Python int on success or ``NULL`` with a :exc:" -"`TypeError` exception raised on failure." -msgstr "" - -#: ../../c-api/number.rst:260 -msgid "" -"The result always has exact type :class:`int`. Previously, the result could " -"have been an instance of a subclass of ``int``." -msgstr "" - -#: ../../c-api/number.rst:267 -msgid "" -"Returns the integer *n* converted to base *base* as a string. The *base* " -"argument must be one of 2, 8, 10, or 16. For base 2, 8, or 16, the returned " -"string is prefixed with a base marker of ``'0b'``, ``'0o'``, or ``'0x'``, " -"respectively. If *n* is not a Python int, it is converted with :c:func:" -"`PyNumber_Index` first." -msgstr "" - -#: ../../c-api/number.rst:276 -msgid "" -"Returns *o* converted to a :c:type:`Py_ssize_t` value if *o* can be " -"interpreted as an integer. If the call fails, an exception is raised and " -"``-1`` is returned." -msgstr "" - -#: ../../c-api/number.rst:279 -msgid "" -"If *o* can be converted to a Python int but the attempt to convert to a :c:" -"type:`Py_ssize_t` value would raise an :exc:`OverflowError`, then the *exc* " -"argument is the type of exception that will be raised (usually :exc:" -"`IndexError` or :exc:`OverflowError`). If *exc* is ``NULL``, then the " -"exception is cleared and the value is clipped to ``PY_SSIZE_T_MIN`` for a " -"negative integer or ``PY_SSIZE_T_MAX`` for a positive integer." -msgstr "" - -#: ../../c-api/number.rst:289 -msgid "" -"Returns ``1`` if *o* is an index integer (has the ``nb_index`` slot of the " -"``tp_as_number`` structure filled in), and ``0`` otherwise. This function " -"always succeeds." -msgstr "" - -#: ../../c-api/number.rst:67 ../../c-api/number.rst:75 -#: ../../c-api/number.rst:97 ../../c-api/number.rst:195 -#: ../../c-api/number.rst:241 ../../c-api/number.rst:249 -msgid "built-in function" -msgstr "built-in function（內建函式）" - -#: ../../c-api/number.rst:67 -msgid "divmod" -msgstr "divmod" - -#: ../../c-api/number.rst:75 ../../c-api/number.rst:195 -msgid "pow" -msgstr "pow" - -#: ../../c-api/number.rst:97 -msgid "abs" -msgstr "abs" - -#: ../../c-api/number.rst:241 -msgid "int" -msgstr "int" - -#: ../../c-api/number.rst:249 -msgid "float" -msgstr "float" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-07-20 00:03+0000\n" +"PO-Revision-Date: 2018-05-23 14: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" + +#: ../../c-api/number.rst:6 +msgid "Number Protocol" +msgstr "數字協定" + +#: ../../c-api/number.rst:11 +msgid "" +"Returns ``1`` if the object *o* provides numeric protocols, and false " +"otherwise. This function always succeeds." +msgstr "" + +#: ../../c-api/number.rst:14 +msgid "Returns ``1`` if *o* is an index integer." +msgstr "" + +#: ../../c-api/number.rst:20 +msgid "" +"Returns the result of adding *o1* and *o2*, or ``NULL`` on failure. This is " +"the equivalent of the Python expression ``o1 + o2``." +msgstr "" + +#: ../../c-api/number.rst:26 +msgid "" +"Returns the result of subtracting *o2* from *o1*, or ``NULL`` on failure. " +"This is the equivalent of the Python expression ``o1 - o2``." +msgstr "" + +#: ../../c-api/number.rst:32 +msgid "" +"Returns the result of multiplying *o1* and *o2*, or ``NULL`` on failure. " +"This is the equivalent of the Python expression ``o1 * o2``." +msgstr "" + +#: ../../c-api/number.rst:38 +msgid "" +"Returns the result of matrix multiplication on *o1* and *o2*, or ``NULL`` on " +"failure. This is the equivalent of the Python expression ``o1 @ o2``." +msgstr "" + +#: ../../c-api/number.rst:46 +msgid "" +"Return the floor of *o1* divided by *o2*, or ``NULL`` on failure. This is " +"the equivalent of the Python expression ``o1 // o2``." +msgstr "" + +#: ../../c-api/number.rst:52 +msgid "" +"Return a reasonable approximation for the mathematical value of *o1* divided " +"by *o2*, or ``NULL`` on failure. The return value is \"approximate\" " +"because binary floating-point numbers are approximate; it is not possible to " +"represent all real numbers in base two. This function can return a floating-" +"point value when passed two integers. This is the equivalent of the Python " +"expression ``o1 / o2``." +msgstr "" + +#: ../../c-api/number.rst:61 +msgid "" +"Returns the remainder of dividing *o1* by *o2*, or ``NULL`` on failure. " +"This is the equivalent of the Python expression ``o1 % o2``." +msgstr "" + +#: ../../c-api/number.rst:69 +msgid "" +"See the built-in function :func:`divmod`. Returns ``NULL`` on failure. This " +"is the equivalent of the Python expression ``divmod(o1, o2)``." +msgstr "" + +#: ../../c-api/number.rst:77 +msgid "" +"See the built-in function :func:`pow`. Returns ``NULL`` on failure. This is " +"the equivalent of the Python expression ``pow(o1, o2, o3)``, where *o3* is " +"optional. If *o3* is to be ignored, pass :c:data:`Py_None` in its place " +"(passing ``NULL`` for *o3* would cause an illegal memory access)." +msgstr "" + +#: ../../c-api/number.rst:85 +msgid "" +"Returns the negation of *o* on success, or ``NULL`` on failure. This is the " +"equivalent of the Python expression ``-o``." +msgstr "" + +#: ../../c-api/number.rst:91 +msgid "" +"Returns *o* on success, or ``NULL`` on failure. This is the equivalent of " +"the Python expression ``+o``." +msgstr "" + +#: ../../c-api/number.rst:99 +msgid "" +"Returns the absolute value of *o*, or ``NULL`` on failure. This is the " +"equivalent of the Python expression ``abs(o)``." +msgstr "" + +#: ../../c-api/number.rst:105 +msgid "" +"Returns the bitwise negation of *o* on success, or ``NULL`` on failure. " +"This is the equivalent of the Python expression ``~o``." +msgstr "" + +#: ../../c-api/number.rst:111 +msgid "" +"Returns the result of left shifting *o1* by *o2* on success, or ``NULL`` on " +"failure. This is the equivalent of the Python expression ``o1 << o2``." +msgstr "" + +#: ../../c-api/number.rst:117 +msgid "" +"Returns the result of right shifting *o1* by *o2* on success, or ``NULL`` on " +"failure. This is the equivalent of the Python expression ``o1 >> o2``." +msgstr "" + +#: ../../c-api/number.rst:123 +msgid "" +"Returns the \"bitwise and\" of *o1* and *o2* on success and ``NULL`` on " +"failure. This is the equivalent of the Python expression ``o1 & o2``." +msgstr "" + +#: ../../c-api/number.rst:129 +msgid "" +"Returns the \"bitwise exclusive or\" of *o1* by *o2* on success, or ``NULL`` " +"on failure. This is the equivalent of the Python expression ``o1 ^ o2``." +msgstr "" + +#: ../../c-api/number.rst:135 +msgid "" +"Returns the \"bitwise or\" of *o1* and *o2* on success, or ``NULL`` on " +"failure. This is the equivalent of the Python expression ``o1 | o2``." +msgstr "" + +#: ../../c-api/number.rst:141 +msgid "" +"Returns the result of adding *o1* and *o2*, or ``NULL`` on failure. The " +"operation is done *in-place* when *o1* supports it. This is the equivalent " +"of the Python statement ``o1 += o2``." +msgstr "" + +#: ../../c-api/number.rst:148 +msgid "" +"Returns the result of subtracting *o2* from *o1*, or ``NULL`` on failure. " +"The operation is done *in-place* when *o1* supports it. This is the " +"equivalent of the Python statement ``o1 -= o2``." +msgstr "" + +#: ../../c-api/number.rst:155 +msgid "" +"Returns the result of multiplying *o1* and *o2*, or ``NULL`` on failure. " +"The operation is done *in-place* when *o1* supports it. This is the " +"equivalent of the Python statement ``o1 *= o2``." +msgstr "" + +#: ../../c-api/number.rst:162 +msgid "" +"Returns the result of matrix multiplication on *o1* and *o2*, or ``NULL`` on " +"failure. The operation is done *in-place* when *o1* supports it. This is " +"the equivalent of the Python statement ``o1 @= o2``." +msgstr "" + +#: ../../c-api/number.rst:171 +msgid "" +"Returns the mathematical floor of dividing *o1* by *o2*, or ``NULL`` on " +"failure. The operation is done *in-place* when *o1* supports it. This is " +"the equivalent of the Python statement ``o1 //= o2``." +msgstr "" + +#: ../../c-api/number.rst:178 +msgid "" +"Return a reasonable approximation for the mathematical value of *o1* divided " +"by *o2*, or ``NULL`` on failure. The return value is \"approximate\" " +"because binary floating-point numbers are approximate; it is not possible to " +"represent all real numbers in base two. This function can return a floating-" +"point value when passed two integers. The operation is done *in-place* when " +"*o1* supports it. This is the equivalent of the Python statement ``o1 /= " +"o2``." +msgstr "" + +#: ../../c-api/number.rst:188 +msgid "" +"Returns the remainder of dividing *o1* by *o2*, or ``NULL`` on failure. The " +"operation is done *in-place* when *o1* supports it. This is the equivalent " +"of the Python statement ``o1 %= o2``." +msgstr "" + +#: ../../c-api/number.rst:197 +msgid "" +"See the built-in function :func:`pow`. Returns ``NULL`` on failure. The " +"operation is done *in-place* when *o1* supports it. This is the equivalent " +"of the Python statement ``o1 **= o2`` when o3 is :c:data:`Py_None`, or an in-" +"place variant of ``pow(o1, o2, o3)`` otherwise. If *o3* is to be ignored, " +"pass :c:data:`Py_None` in its place (passing ``NULL`` for *o3* would cause " +"an illegal memory access)." +msgstr "" + +#: ../../c-api/number.rst:206 +msgid "" +"Returns the result of left shifting *o1* by *o2* on success, or ``NULL`` on " +"failure. The operation is done *in-place* when *o1* supports it. This is " +"the equivalent of the Python statement ``o1 <<= o2``." +msgstr "" + +#: ../../c-api/number.rst:213 +msgid "" +"Returns the result of right shifting *o1* by *o2* on success, or ``NULL`` on " +"failure. The operation is done *in-place* when *o1* supports it. This is " +"the equivalent of the Python statement ``o1 >>= o2``." +msgstr "" + +#: ../../c-api/number.rst:220 +msgid "" +"Returns the \"bitwise and\" of *o1* and *o2* on success and ``NULL`` on " +"failure. The operation is done *in-place* when *o1* supports it. This is " +"the equivalent of the Python statement ``o1 &= o2``." +msgstr "" + +#: ../../c-api/number.rst:227 +msgid "" +"Returns the \"bitwise exclusive or\" of *o1* by *o2* on success, or ``NULL`` " +"on failure. The operation is done *in-place* when *o1* supports it. This " +"is the equivalent of the Python statement ``o1 ^= o2``." +msgstr "" + +#: ../../c-api/number.rst:234 +msgid "" +"Returns the \"bitwise or\" of *o1* and *o2* on success, or ``NULL`` on " +"failure. The operation is done *in-place* when *o1* supports it. This is " +"the equivalent of the Python statement ``o1 |= o2``." +msgstr "" + +#: ../../c-api/number.rst:243 +msgid "" +"Returns the *o* converted to an integer object on success, or ``NULL`` on " +"failure. This is the equivalent of the Python expression ``int(o)``." +msgstr "" + +#: ../../c-api/number.rst:251 +msgid "" +"Returns the *o* converted to a float object on success, or ``NULL`` on " +"failure. This is the equivalent of the Python expression ``float(o)``." +msgstr "" + +#: ../../c-api/number.rst:257 +msgid "" +"Returns the *o* converted to a Python int on success or ``NULL`` with a :exc:" +"`TypeError` exception raised on failure." +msgstr "" + +#: ../../c-api/number.rst:260 +msgid "" +"The result always has exact type :class:`int`. Previously, the result could " +"have been an instance of a subclass of ``int``." +msgstr "" + +#: ../../c-api/number.rst:267 +msgid "" +"Returns the integer *n* converted to base *base* as a string. The *base* " +"argument must be one of 2, 8, 10, or 16. For base 2, 8, or 16, the returned " +"string is prefixed with a base marker of ``'0b'``, ``'0o'``, or ``'0x'``, " +"respectively. If *n* is not a Python int, it is converted with :c:func:" +"`PyNumber_Index` first." +msgstr "" + +#: ../../c-api/number.rst:276 +msgid "" +"Returns *o* converted to a :c:type:`Py_ssize_t` value if *o* can be " +"interpreted as an integer. If the call fails, an exception is raised and " +"``-1`` is returned." +msgstr "" + +#: ../../c-api/number.rst:279 +msgid "" +"If *o* can be converted to a Python int but the attempt to convert to a :c:" +"type:`Py_ssize_t` value would raise an :exc:`OverflowError`, then the *exc* " +"argument is the type of exception that will be raised (usually :exc:" +"`IndexError` or :exc:`OverflowError`). If *exc* is ``NULL``, then the " +"exception is cleared and the value is clipped to ``PY_SSIZE_T_MIN`` for a " +"negative integer or ``PY_SSIZE_T_MAX`` for a positive integer." +msgstr "" + +#: ../../c-api/number.rst:289 +msgid "" +"Returns ``1`` if *o* is an index integer (has the ``nb_index`` slot of the " +"``tp_as_number`` structure filled in), and ``0`` otherwise. This function " +"always succeeds." +msgstr "" + +#: ../../c-api/number.rst:67 ../../c-api/number.rst:75 +#: ../../c-api/number.rst:97 ../../c-api/number.rst:195 +#: ../../c-api/number.rst:241 ../../c-api/number.rst:249 +msgid "built-in function" +msgstr "built-in function（內建函式）" + +#: ../../c-api/number.rst:67 +msgid "divmod" +msgstr "divmod" + +#: ../../c-api/number.rst:75 ../../c-api/number.rst:195 +msgid "pow" +msgstr "pow" + +#: ../../c-api/number.rst:97 +msgid "abs" +msgstr "abs" + +#: ../../c-api/number.rst:241 +msgid "int" +msgstr "int" + +#: ../../c-api/number.rst:249 +msgid "float" +msgstr "float" diff --git a/c-api/object.po b/c-api/object.po index 5cdde8ebd5..4cc687fc12 100644 --- a/c-api/object.po +++ b/c-api/object.po @@ -1,974 +1,974 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-05 00:16+0000\n" -"PO-Revision-Date: 2018-05-23 14:32+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" - -#: ../../c-api/object.rst:6 -msgid "Object Protocol" -msgstr "物件協定" - -#: ../../c-api/object.rst:11 -msgid "Get a :term:`strong reference` to a constant." -msgstr "" - -#: ../../c-api/object.rst:13 -msgid "Set an exception and return ``NULL`` if *constant_id* is invalid." -msgstr "如果 *constant_id* 無效，則設定一個例外並回傳 ``NULL``。" - -#: ../../c-api/object.rst:15 -msgid "*constant_id* must be one of these constant identifiers:" -msgstr "*constant_id* 必須是這些常數識別字之一：" - -#: ../../c-api/object.rst:20 -msgid "Constant Identifier" -msgstr "常數識別字" - -#: ../../c-api/object.rst:20 -msgid "Value" -msgstr "數值" - -#: ../../c-api/object.rst:20 -msgid "Returned object" -msgstr "回傳物件" - -#: ../../c-api/object.rst:22 ../../c-api/object.rst:27 -msgid "``0``" -msgstr "``0``" - -#: ../../c-api/object.rst:22 -msgid ":py:data:`None`" -msgstr ":py:data:`None`" - -#: ../../c-api/object.rst:23 ../../c-api/object.rst:28 -msgid "``1``" -msgstr "``1``" - -#: ../../c-api/object.rst:23 -msgid ":py:data:`False`" -msgstr ":py:data:`False`" - -#: ../../c-api/object.rst:24 -msgid "``2``" -msgstr "``2``" - -#: ../../c-api/object.rst:24 -msgid ":py:data:`True`" -msgstr ":py:data:`True`" - -#: ../../c-api/object.rst:25 -msgid "``3``" -msgstr "``3``" - -#: ../../c-api/object.rst:25 -msgid ":py:data:`Ellipsis`" -msgstr ":py:data:`Ellipsis`" - -#: ../../c-api/object.rst:26 -msgid "``4``" -msgstr "``4``" - -#: ../../c-api/object.rst:26 -msgid ":py:data:`NotImplemented`" -msgstr ":py:data:`NotImplemented`" - -#: ../../c-api/object.rst:27 -msgid "``5``" -msgstr "``5``" - -#: ../../c-api/object.rst:28 -msgid "``6``" -msgstr "``6``" - -#: ../../c-api/object.rst:29 -msgid "``7``" -msgstr "``7``" - -#: ../../c-api/object.rst:29 -msgid "``''``" -msgstr "``''``" - -#: ../../c-api/object.rst:30 -msgid "``8``" -msgstr "``8``" - -#: ../../c-api/object.rst:30 -msgid "``b''``" -msgstr "``b''``" - -#: ../../c-api/object.rst:31 -msgid "``9``" -msgstr "``9``" - -#: ../../c-api/object.rst:31 -msgid "``()``" -msgstr "``()``" - -#: ../../c-api/object.rst:34 -msgid "" -"Numeric values are only given for projects which cannot use the constant " -"identifiers." -msgstr "" - -#: ../../c-api/object.rst:42 -msgid "In CPython, all of these constants are :term:`immortal`." -msgstr "在 CPython 中，所有這些常數都是\\ :term:`不滅 `\\ 的。" - -#: ../../c-api/object.rst:47 -msgid "" -"Similar to :c:func:`Py_GetConstant`, but return a :term:`borrowed reference`." -msgstr "" - -#: ../../c-api/object.rst:50 -msgid "" -"This function is primarily intended for backwards compatibility: using :c:" -"func:`Py_GetConstant` is recommended for new code." -msgstr "" - -#: ../../c-api/object.rst:53 -msgid "" -"The reference is borrowed from the interpreter, and is valid until the " -"interpreter finalization." -msgstr "" - -#: ../../c-api/object.rst:61 -msgid "" -"The ``NotImplemented`` singleton, used to signal that an operation is not " -"implemented for the given type combination." -msgstr "" - -#: ../../c-api/object.rst:67 -msgid "" -"Properly handle returning :c:data:`Py_NotImplemented` from within a C " -"function (that is, create a new :term:`strong reference` to :const:" -"`NotImplemented` and return it)." -msgstr "" - -#: ../../c-api/object.rst:74 -msgid "" -"Flag to be used with multiple functions that print the object (like :c:func:" -"`PyObject_Print` and :c:func:`PyFile_WriteObject`). If passed, these " -"functions use the :func:`str` of the object instead of the :func:`repr`." -msgstr "" - -#: ../../c-api/object.rst:82 -msgid "" -"Print an object *o*, on file *fp*. Returns ``-1`` on error. The flags " -"argument is used to enable certain printing options. The only option " -"currently supported is :c:macro:`Py_PRINT_RAW`; if given, the :func:`str` of " -"the object is written instead of the :func:`repr`." -msgstr "" - -#: ../../c-api/object.rst:90 -msgid "" -"Returns ``1`` if *o* has the attribute *attr_name*, and ``0`` otherwise. " -"This is equivalent to the Python expression ``hasattr(o, attr_name)``. On " -"failure, return ``-1``." -msgstr "" - -#: ../../c-api/object.rst:99 -msgid "" -"This is the same as :c:func:`PyObject_HasAttrWithError`, but *attr_name* is " -"specified as a :c:expr:`const char*` UTF-8 encoded bytes string, rather than " -"a :c:expr:`PyObject*`." -msgstr "" - -#: ../../c-api/object.rst:108 -msgid "" -"Returns ``1`` if *o* has the attribute *attr_name*, and ``0`` otherwise. " -"This function always succeeds." -msgstr "" - -#: ../../c-api/object.rst:113 -msgid "" -"Exceptions that occur when this calls :meth:`~object.__getattr__` and :meth:" -"`~object.__getattribute__` methods aren't propagated, but instead given to :" -"func:`sys.unraisablehook`. For proper error handling, use :c:func:" -"`PyObject_HasAttrWithError`, :c:func:`PyObject_GetOptionalAttr` or :c:func:" -"`PyObject_GetAttr` instead." -msgstr "" - -#: ../../c-api/object.rst:122 -msgid "" -"This is the same as :c:func:`PyObject_HasAttr`, but *attr_name* is specified " -"as a :c:expr:`const char*` UTF-8 encoded bytes string, rather than a :c:expr:" -"`PyObject*`." -msgstr "" - -#: ../../c-api/object.rst:128 -msgid "" -"Exceptions that occur when this calls :meth:`~object.__getattr__` and :meth:" -"`~object.__getattribute__` methods or while creating the temporary :class:" -"`str` object are silently ignored. For proper error handling, use :c:func:" -"`PyObject_HasAttrStringWithError`, :c:func:`PyObject_GetOptionalAttrString` " -"or :c:func:`PyObject_GetAttrString` instead." -msgstr "" - -#: ../../c-api/object.rst:138 -msgid "" -"Retrieve an attribute named *attr_name* from object *o*. Returns the " -"attribute value on success, or ``NULL`` on failure. This is the equivalent " -"of the Python expression ``o.attr_name``." -msgstr "" - -#: ../../c-api/object.rst:142 -msgid "" -"If the missing attribute should not be treated as a failure, you can use :c:" -"func:`PyObject_GetOptionalAttr` instead." -msgstr "" - -#: ../../c-api/object.rst:148 -msgid "" -"This is the same as :c:func:`PyObject_GetAttr`, but *attr_name* is specified " -"as a :c:expr:`const char*` UTF-8 encoded bytes string, rather than a :c:expr:" -"`PyObject*`." -msgstr "" - -#: ../../c-api/object.rst:152 -msgid "" -"If the missing attribute should not be treated as a failure, you can use :c:" -"func:`PyObject_GetOptionalAttrString` instead." -msgstr "" - -#: ../../c-api/object.rst:158 -msgid "" -"Variant of :c:func:`PyObject_GetAttr` which doesn't raise :exc:" -"`AttributeError` if the attribute is not found." -msgstr "" - -#: ../../c-api/object.rst:161 -msgid "" -"If the attribute is found, return ``1`` and set *\\*result* to a new :term:" -"`strong reference` to the attribute. If the attribute is not found, return " -"``0`` and set *\\*result* to ``NULL``; the :exc:`AttributeError` is " -"silenced. If an error other than :exc:`AttributeError` is raised, return " -"``-1`` and set *\\*result* to ``NULL``." -msgstr "" - -#: ../../c-api/object.rst:173 -msgid "" -"This is the same as :c:func:`PyObject_GetOptionalAttr`, but *attr_name* is " -"specified as a :c:expr:`const char*` UTF-8 encoded bytes string, rather than " -"a :c:expr:`PyObject*`." -msgstr "" - -#: ../../c-api/object.rst:181 -msgid "" -"Generic attribute getter function that is meant to be put into a type " -"object's ``tp_getattro`` slot. It looks for a descriptor in the dictionary " -"of classes in the object's MRO as well as an attribute in the object's :attr:" -"`~object.__dict__` (if present). As outlined in :ref:`descriptors`, data " -"descriptors take preference over instance attributes, while non-data " -"descriptors don't. Otherwise, an :exc:`AttributeError` is raised." -msgstr "" - -#: ../../c-api/object.rst:191 -msgid "" -"Set the value of the attribute named *attr_name*, for object *o*, to the " -"value *v*. Raise an exception and return ``-1`` on failure; return ``0`` on " -"success. This is the equivalent of the Python statement ``o.attr_name = v``." -msgstr "" - -#: ../../c-api/object.rst:196 -msgid "" -"If *v* is ``NULL``, the attribute is deleted. This behaviour is deprecated " -"in favour of using :c:func:`PyObject_DelAttr`, but there are currently no " -"plans to remove it." -msgstr "" - -#: ../../c-api/object.rst:203 -msgid "" -"This is the same as :c:func:`PyObject_SetAttr`, but *attr_name* is specified " -"as a :c:expr:`const char*` UTF-8 encoded bytes string, rather than a :c:expr:" -"`PyObject*`." -msgstr "" - -#: ../../c-api/object.rst:207 -msgid "" -"If *v* is ``NULL``, the attribute is deleted, but this feature is deprecated " -"in favour of using :c:func:`PyObject_DelAttrString`." -msgstr "" - -#: ../../c-api/object.rst:210 -msgid "" -"The number of different attribute names passed to this function should be " -"kept small, usually by using a statically allocated string as *attr_name*. " -"For attribute names that aren't known at compile time, prefer calling :c:" -"func:`PyUnicode_FromString` and :c:func:`PyObject_SetAttr` directly. For " -"more details, see :c:func:`PyUnicode_InternFromString`, which may be used " -"internally to create a key object." -msgstr "" - -#: ../../c-api/object.rst:220 -msgid "" -"Generic attribute setter and deleter function that is meant to be put into a " -"type object's :c:member:`~PyTypeObject.tp_setattro` slot. It looks for a " -"data descriptor in the dictionary of classes in the object's MRO, and if " -"found it takes preference over setting or deleting the attribute in the " -"instance dictionary. Otherwise, the attribute is set or deleted in the " -"object's :attr:`~object.__dict__` (if present). On success, ``0`` is " -"returned, otherwise an :exc:`AttributeError` is raised and ``-1`` is " -"returned." -msgstr "" - -#: ../../c-api/object.rst:232 -msgid "" -"Delete attribute named *attr_name*, for object *o*. Returns ``-1`` on " -"failure. This is the equivalent of the Python statement ``del o.attr_name``." -msgstr "" - -#: ../../c-api/object.rst:238 -msgid "" -"This is the same as :c:func:`PyObject_DelAttr`, but *attr_name* is specified " -"as a :c:expr:`const char*` UTF-8 encoded bytes string, rather than a :c:expr:" -"`PyObject*`." -msgstr "" - -#: ../../c-api/object.rst:242 -msgid "" -"The number of different attribute names passed to this function should be " -"kept small, usually by using a statically allocated string as *attr_name*. " -"For attribute names that aren't known at compile time, prefer calling :c:" -"func:`PyUnicode_FromString` and :c:func:`PyObject_DelAttr` directly. For " -"more details, see :c:func:`PyUnicode_InternFromString`, which may be used " -"internally to create a key object for lookup." -msgstr "" - -#: ../../c-api/object.rst:253 -msgid "" -"A generic implementation for the getter of a ``__dict__`` descriptor. It " -"creates the dictionary if necessary." -msgstr "" - -#: ../../c-api/object.rst:256 -msgid "" -"This function may also be called to get the :py:attr:`~object.__dict__` of " -"the object *o*. Pass ``NULL`` for *context* when calling it. Since this " -"function may need to allocate memory for the dictionary, it may be more " -"efficient to call :c:func:`PyObject_GetAttr` when accessing an attribute on " -"the object." -msgstr "" - -#: ../../c-api/object.rst:262 -msgid "On failure, returns ``NULL`` with an exception set." -msgstr "在失敗時，會回傳 ``NULL`` 並設定例外。" - -#: ../../c-api/object.rst:269 -msgid "" -"A generic implementation for the setter of a ``__dict__`` descriptor. This " -"implementation does not allow the dictionary to be deleted." -msgstr "" - -#: ../../c-api/object.rst:277 -msgid "" -"Return a pointer to :py:attr:`~object.__dict__` of the object *obj*. If " -"there is no ``__dict__``, return ``NULL`` without setting an exception." -msgstr "" - -#: ../../c-api/object.rst:280 -msgid "" -"This function may need to allocate memory for the dictionary, so it may be " -"more efficient to call :c:func:`PyObject_GetAttr` when accessing an " -"attribute on the object." -msgstr "" - -#: ../../c-api/object.rst:287 -msgid "" -"Compare the values of *o1* and *o2* using the operation specified by *opid*, " -"which must be one of :c:macro:`Py_LT`, :c:macro:`Py_LE`, :c:macro:`Py_EQ`, :" -"c:macro:`Py_NE`, :c:macro:`Py_GT`, or :c:macro:`Py_GE`, corresponding to " -"``<``, ``<=``, ``==``, ``!=``, ``>``, or ``>=`` respectively. This is the " -"equivalent of the Python expression ``o1 op o2``, where ``op`` is the " -"operator corresponding to *opid*. Returns the value of the comparison on " -"success, or ``NULL`` on failure." -msgstr "" - -#: ../../c-api/object.rst:297 -msgid "" -"Compare the values of *o1* and *o2* using the operation specified by *opid*, " -"like :c:func:`PyObject_RichCompare`, but returns ``-1`` on error, ``0`` if " -"the result is false, ``1`` otherwise." -msgstr "" - -#: ../../c-api/object.rst:302 -msgid "" -"If *o1* and *o2* are the same object, :c:func:`PyObject_RichCompareBool` " -"will always return ``1`` for :c:macro:`Py_EQ` and ``0`` for :c:macro:`Py_NE`." -msgstr "" - -#: ../../c-api/object.rst:307 -msgid "" -"Format *obj* using *format_spec*. This is equivalent to the Python " -"expression ``format(obj, format_spec)``." -msgstr "" - -#: ../../c-api/object.rst:310 -msgid "" -"*format_spec* may be ``NULL``. In this case the call is equivalent to " -"``format(obj)``. Returns the formatted string on success, ``NULL`` on " -"failure." -msgstr "" - -#: ../../c-api/object.rst:318 -msgid "" -"Compute a string representation of object *o*. Returns the string " -"representation on success, ``NULL`` on failure. This is the equivalent of " -"the Python expression ``repr(o)``. Called by the :func:`repr` built-in " -"function." -msgstr "" - -#: ../../c-api/object.rst:322 ../../c-api/object.rst:346 -msgid "" -"This function now includes a debug assertion to help ensure that it does not " -"silently discard an active exception." -msgstr "" - -#: ../../c-api/object.rst:330 -msgid "" -"As :c:func:`PyObject_Repr`, compute a string representation of object *o*, " -"but escape the non-ASCII characters in the string returned by :c:func:" -"`PyObject_Repr` with ``\\x``, ``\\u`` or ``\\U`` escapes. This generates a " -"string similar to that returned by :c:func:`PyObject_Repr` in Python 2. " -"Called by the :func:`ascii` built-in function." -msgstr "" - -#: ../../c-api/object.rst:341 -msgid "" -"Compute a string representation of object *o*. Returns the string " -"representation on success, ``NULL`` on failure. This is the equivalent of " -"the Python expression ``str(o)``. Called by the :func:`str` built-in " -"function and, therefore, by the :func:`print` function." -msgstr "" - -#: ../../c-api/object.rst:355 -msgid "" -"Compute a bytes representation of object *o*. ``NULL`` is returned on " -"failure and a bytes object on success. This is equivalent to the Python " -"expression ``bytes(o)``, when *o* is not an integer. Unlike ``bytes(o)``, a " -"TypeError is raised when *o* is an integer instead of a zero-initialized " -"bytes object." -msgstr "" - -#: ../../c-api/object.rst:364 -msgid "" -"Return ``1`` if the class *derived* is identical to or derived from the " -"class *cls*, otherwise return ``0``. In case of an error, return ``-1``." -msgstr "" - -#: ../../c-api/object.rst:367 ../../c-api/object.rst:386 -msgid "" -"If *cls* is a tuple, the check will be done against every entry in *cls*. " -"The result will be ``1`` when at least one of the checks returns ``1``, " -"otherwise it will be ``0``." -msgstr "" - -#: ../../c-api/object.rst:371 -msgid "" -"If *cls* has a :meth:`~type.__subclasscheck__` method, it will be called to " -"determine the subclass status as described in :pep:`3119`. Otherwise, " -"*derived* is a subclass of *cls* if it is a direct or indirect subclass, i." -"e. contained in :attr:`cls.__mro__ `." -msgstr "" - -#: ../../c-api/object.rst:376 -msgid "" -"Normally only class objects, i.e. instances of :class:`type` or a derived " -"class, are considered classes. However, objects can override this by having " -"a :attr:`~type.__bases__` attribute (which must be a tuple of base classes)." -msgstr "" - -#: ../../c-api/object.rst:383 -msgid "" -"Return ``1`` if *inst* is an instance of the class *cls* or a subclass of " -"*cls*, or ``0`` if not. On error, returns ``-1`` and sets an exception." -msgstr "" - -#: ../../c-api/object.rst:390 -msgid "" -"If *cls* has a :meth:`~type.__instancecheck__` method, it will be called to " -"determine the subclass status as described in :pep:`3119`. Otherwise, " -"*inst* is an instance of *cls* if its class is a subclass of *cls*." -msgstr "" - -#: ../../c-api/object.rst:394 -msgid "" -"An instance *inst* can override what is considered its class by having a :" -"attr:`~object.__class__` attribute." -msgstr "" - -#: ../../c-api/object.rst:397 -msgid "" -"An object *cls* can override if it is considered a class, and what its base " -"classes are, by having a :attr:`~type.__bases__` attribute (which must be a " -"tuple of base classes)." -msgstr "" - -#: ../../c-api/object.rst:406 -msgid "" -"Compute and return the hash value of an object *o*. On failure, return " -"``-1``. This is the equivalent of the Python expression ``hash(o)``." -msgstr "" - -#: ../../c-api/object.rst:409 -msgid "" -"The return type is now Py_hash_t. This is a signed integer the same size " -"as :c:type:`Py_ssize_t`." -msgstr "" - -#: ../../c-api/object.rst:416 -msgid "" -"Set a :exc:`TypeError` indicating that ``type(o)`` is not :term:`hashable` " -"and return ``-1``. This function receives special treatment when stored in a " -"``tp_hash`` slot, allowing a type to explicitly indicate to the interpreter " -"that it is not hashable." -msgstr "" - -#: ../../c-api/object.rst:424 -msgid "" -"Returns ``1`` if the object *o* is considered to be true, and ``0`` " -"otherwise. This is equivalent to the Python expression ``not not o``. On " -"failure, return ``-1``." -msgstr "" - -#: ../../c-api/object.rst:431 -msgid "" -"Returns ``0`` if the object *o* is considered to be true, and ``1`` " -"otherwise. This is equivalent to the Python expression ``not o``. On " -"failure, return ``-1``." -msgstr "" - -#: ../../c-api/object.rst:440 -msgid "" -"When *o* is non-``NULL``, returns a type object corresponding to the object " -"type of object *o*. On failure, raises :exc:`SystemError` and returns " -"``NULL``. This is equivalent to the Python expression ``type(o)``. This " -"function creates a new :term:`strong reference` to the return value. There's " -"really no reason to use this function instead of the :c:func:`Py_TYPE()` " -"function, which returns a pointer of type :c:expr:`PyTypeObject*`, except " -"when a new :term:`strong reference` is needed." -msgstr "" - -#: ../../c-api/object.rst:452 -msgid "" -"Return non-zero if the object *o* is of type *type* or a subtype of *type*, " -"and ``0`` otherwise. Both parameters must be non-``NULL``." -msgstr "" - -#: ../../c-api/object.rst:461 -msgid "" -"Return the length of object *o*. If the object *o* provides either the " -"sequence and mapping protocols, the sequence length is returned. On error, " -"``-1`` is returned. This is the equivalent to the Python expression " -"``len(o)``." -msgstr "" - -#: ../../c-api/object.rst:468 -msgid "" -"Return an estimated length for the object *o*. First try to return its " -"actual length, then an estimate using :meth:`~object.__length_hint__`, and " -"finally return the default value. On error return ``-1``. This is the " -"equivalent to the Python expression ``operator.length_hint(o, " -"defaultvalue)``." -msgstr "" - -#: ../../c-api/object.rst:478 -msgid "" -"Return element of *o* corresponding to the object *key* or ``NULL`` on " -"failure. This is the equivalent of the Python expression ``o[key]``." -msgstr "" - -#: ../../c-api/object.rst:484 -msgid "" -"Map the object *key* to the value *v*. Raise an exception and return ``-1`` " -"on failure; return ``0`` on success. This is the equivalent of the Python " -"statement ``o[key] = v``. This function *does not* steal a reference to *v*." -msgstr "" - -#: ../../c-api/object.rst:492 -msgid "" -"Remove the mapping for the object *key* from the object *o*. Return ``-1`` " -"on failure. This is equivalent to the Python statement ``del o[key]``." -msgstr "" - -#: ../../c-api/object.rst:498 -msgid "" -"This is the same as :c:func:`PyObject_DelItem`, but *key* is specified as a :" -"c:expr:`const char*` UTF-8 encoded bytes string, rather than a :c:expr:" -"`PyObject*`." -msgstr "" - -#: ../../c-api/object.rst:505 -msgid "" -"This is equivalent to the Python expression ``dir(o)``, returning a " -"(possibly empty) list of strings appropriate for the object argument, or " -"``NULL`` if there was an error. If the argument is ``NULL``, this is like " -"the Python ``dir()``, returning the names of the current locals; in this " -"case, if no execution frame is active then ``NULL`` is returned but :c:func:" -"`PyErr_Occurred` will return false." -msgstr "" - -#: ../../c-api/object.rst:514 -msgid "" -"This is equivalent to the Python expression ``iter(o)``. It returns a new " -"iterator for the object argument, or the object itself if the object is " -"already an iterator. Raises :exc:`TypeError` and returns ``NULL`` if the " -"object cannot be iterated." -msgstr "" - -#: ../../c-api/object.rst:522 -msgid "" -"This is equivalent to the Python ``__iter__(self): return self`` method. It " -"is intended for :term:`iterator` types, to be used in the :c:member:" -"`PyTypeObject.tp_iter` slot." -msgstr "" - -#: ../../c-api/object.rst:528 -msgid "" -"This is the equivalent to the Python expression ``aiter(o)``. Takes an :" -"class:`AsyncIterable` object and returns an :class:`AsyncIterator` for it. " -"This is typically a new iterator but if the argument is an :class:" -"`AsyncIterator`, this returns itself. Raises :exc:`TypeError` and returns " -"``NULL`` if the object cannot be iterated." -msgstr "" - -#: ../../c-api/object.rst:538 -msgid "Get a pointer to subclass-specific data reserved for *cls*." -msgstr "" - -#: ../../c-api/object.rst:540 -msgid "" -"The object *o* must be an instance of *cls*, and *cls* must have been " -"created using negative :c:member:`PyType_Spec.basicsize`. Python does not " -"check this." -msgstr "" - -#: ../../c-api/object.rst:544 -msgid "On error, set an exception and return ``NULL``." -msgstr "錯誤時設定一個例外並回傳 ``NULL``。" - -#: ../../c-api/object.rst:550 -msgid "" -"Return the size of the instance memory space reserved for *cls*, i.e. the " -"size of the memory :c:func:`PyObject_GetTypeData` returns." -msgstr "" - -#: ../../c-api/object.rst:553 -msgid "" -"This may be larger than requested using :c:member:`-PyType_Spec.basicsize " -"`; it is safe to use this larger size (e.g. with :c:" -"func:`!memset`)." -msgstr "" - -#: ../../c-api/object.rst:556 -msgid "" -"The type *cls* **must** have been created using negative :c:member:" -"`PyType_Spec.basicsize`. Python does not check this." -msgstr "" - -#: ../../c-api/object.rst:560 -msgid "On error, set an exception and return a negative value." -msgstr "錯誤時設定一個例外並回傳一個負值。" - -#: ../../c-api/object.rst:566 -msgid "" -"Get a pointer to per-item data for a class with :c:macro:" -"`Py_TPFLAGS_ITEMS_AT_END`." -msgstr "" - -#: ../../c-api/object.rst:569 -msgid "" -"On error, set an exception and return ``NULL``. :py:exc:`TypeError` is " -"raised if *o* does not have :c:macro:`Py_TPFLAGS_ITEMS_AT_END` set." -msgstr "" -"錯誤時設定一個例外並回傳 ``NULL``。如果 *o* 沒有設定 :c:macro:" -"`Py_TPFLAGS_ITEMS_AT_END`，則會引發 :py:exc:`TypeError`。" - -#: ../../c-api/object.rst:577 -msgid "Visit the managed dictionary of *obj*." -msgstr "" - -#: ../../c-api/object.rst:579 -msgid "" -"This function must only be called in a traverse function of the type which " -"has the :c:macro:`Py_TPFLAGS_MANAGED_DICT` flag set." -msgstr "" - -#: ../../c-api/object.rst:586 -msgid "Clear the managed dictionary of *obj*." -msgstr "" - -#: ../../c-api/object.rst:588 -msgid "" -"This function must only be called in a clear function of the type which has " -"the :c:macro:`Py_TPFLAGS_MANAGED_DICT` flag set." -msgstr "" - -#: ../../c-api/object.rst:595 -msgid "" -"Enable `deferred reference counting `_ on *obj*, if supported by the runtime. In " -"the :term:`free-threaded ` build, this allows the " -"interpreter to avoid reference count adjustments to *obj*, which may improve " -"multi-threaded performance. The tradeoff is that *obj* will only be " -"deallocated by the tracing garbage collector, and not when the interpreter " -"no longer has any references to it." -msgstr "" - -#: ../../c-api/object.rst:602 -msgid "" -"This function returns ``1`` if deferred reference counting is enabled on " -"*obj*, and ``0`` if deferred reference counting is not supported or if the " -"hint was ignored by the interpreter, such as when deferred reference " -"counting is already enabled on *obj*. This function is thread-safe, and " -"cannot fail." -msgstr "" - -#: ../../c-api/object.rst:607 -msgid "" -"This function does nothing on builds with the :term:`GIL` enabled, which do " -"not support deferred reference counting. This also does nothing if *obj* is " -"not an object tracked by the garbage collector (see :func:`gc.is_tracked` " -"and :c:func:`PyObject_GC_IsTracked`)." -msgstr "" - -#: ../../c-api/object.rst:612 -msgid "" -"This function is intended to be used soon after *obj* is created, by the " -"code that creates it, such as in the object's :c:member:`~PyTypeObject." -"tp_new` slot." -msgstr "" - -#: ../../c-api/object.rst:620 -msgid "" -"Check if *obj* is a unique temporary object. Returns ``1`` if *obj* is known " -"to be a unique temporary object, and ``0`` otherwise. This function cannot " -"fail, but the check is conservative, and may return ``0`` in some cases even " -"if *obj* is a unique temporary object." -msgstr "" - -#: ../../c-api/object.rst:626 -msgid "" -"If an object is a unique temporary, it is guaranteed that the current code " -"has the only reference to the object. For arguments to C functions, this " -"should be used instead of checking if the reference count is ``1``. Starting " -"with Python 3.14, the interpreter internally avoids some reference count " -"modifications when loading objects onto the operands stack by :term:" -"`borrowing ` references when possible, which means that " -"a reference count of ``1`` by itself does not guarantee that a function " -"argument uniquely referenced." -msgstr "" - -#: ../../c-api/object.rst:635 -msgid "" -"In the example below, ``my_func`` is called with a unique temporary object " -"as its argument::" -msgstr "" - -#: ../../c-api/object.rst:638 -msgid "my_func([1, 2, 3])" -msgstr "my_func([1, 2, 3])" - -#: ../../c-api/object.rst:640 -msgid "" -"In the example below, ``my_func`` is **not** called with a unique temporary " -"object as its argument, even if its refcount is ``1``::" -msgstr "" - -#: ../../c-api/object.rst:643 -msgid "" -"my_list = [1, 2, 3]\n" -"my_func(my_list)" -msgstr "" -"my_list = [1, 2, 3]\n" -"my_func(my_list)" - -#: ../../c-api/object.rst:646 -msgid "See also the function :c:func:`Py_REFCNT`." -msgstr "另請參閱 :c:func:`Py_REFCNT` 函式。" - -#: ../../c-api/object.rst:652 -msgid "" -"This function returns non-zero if *obj* is :term:`immortal`, and zero " -"otherwise. This function cannot fail." -msgstr "" - -#: ../../c-api/object.rst:657 -msgid "" -"Objects that are immortal in one CPython version are not guaranteed to be " -"immortal in another." -msgstr "" - -#: ../../c-api/object.rst:664 -msgid "" -"Increments the reference count of *obj* if it is not zero. Returns ``1`` if " -"the object's reference count was successfully incremented. Otherwise, this " -"function returns ``0``." -msgstr "" - -#: ../../c-api/object.rst:668 -msgid "" -":c:func:`PyUnstable_EnableTryIncRef` must have been called earlier on *obj* " -"or this function may spuriously return ``0`` in the :term:`free threading` " -"build." -msgstr "" - -#: ../../c-api/object.rst:672 -msgid "" -"This function is logically equivalent to the following C code, except that " -"it behaves atomically in the :term:`free threading` build::" -msgstr "" - -#: ../../c-api/object.rst:675 -msgid "" -"if (Py_REFCNT(op) > 0) {\n" -" Py_INCREF(op);\n" -" return 1;\n" -"}\n" -"return 0;" -msgstr "" -"if (Py_REFCNT(op) > 0) {\n" -" Py_INCREF(op);\n" -" return 1;\n" -"}\n" -"return 0;" - -#: ../../c-api/object.rst:681 -msgid "" -"This is intended as a building block for managing weak references without " -"the overhead of a Python :ref:`weak reference object `." -msgstr "" - -#: ../../c-api/object.rst:684 -msgid "" -"Typically, correct use of this function requires support from *obj*'s " -"deallocator (:c:member:`~PyTypeObject.tp_dealloc`). For example, the " -"following sketch could be adapted to implement a \"weakmap\" that works like " -"a :py:class:`~weakref.WeakValueDictionary` for a specific type:" -msgstr "" - -#: ../../c-api/object.rst:690 -msgid "" -"PyMutex mutex;\n" -"\n" -"PyObject *\n" -"add_entry(weakmap_key_type *key, PyObject *value)\n" -"{\n" -" PyUnstable_EnableTryIncRef(value);\n" -" weakmap_type weakmap = ...;\n" -" PyMutex_Lock(&mutex);\n" -" weakmap_add_entry(weakmap, key, value);\n" -" PyMutex_Unlock(&mutex);\n" -" Py_RETURN_NONE;\n" -"}\n" -"\n" -"PyObject *\n" -"get_value(weakmap_key_type *key)\n" -"{\n" -" weakmap_type weakmap = ...;\n" -" PyMutex_Lock(&mutex);\n" -" PyObject *result = weakmap_find(weakmap, key);\n" -" if (PyUnstable_TryIncRef(result)) {\n" -" // `result` is safe to use\n" -" PyMutex_Unlock(&mutex);\n" -" return result;\n" -" }\n" -" // if we get here, `result` is starting to be garbage-collected,\n" -" // but has not been removed from the weakmap yet\n" -" PyMutex_Unlock(&mutex);\n" -" return NULL;\n" -"}\n" -"\n" -"// tp_dealloc function for weakmap values\n" -"void\n" -"value_dealloc(PyObject *value)\n" -"{\n" -" weakmap_type weakmap = ...;\n" -" PyMutex_Lock(&mutex);\n" -" weakmap_remove_value(weakmap, value);\n" -"\n" -" ...\n" -" PyMutex_Unlock(&mutex);\n" -"}" -msgstr "" - -#: ../../c-api/object.rst:738 -msgid "" -"Enables subsequent uses of :c:func:`PyUnstable_TryIncRef` on *obj*. The " -"caller must hold a :term:`strong reference` to *obj* when calling this." -msgstr "" - -#: ../../c-api/object.rst:745 -msgid "Determine if *op* only has one reference." -msgstr "" - -#: ../../c-api/object.rst:747 -msgid "" -"On GIL-enabled builds, this function is equivalent to :c:expr:`Py_REFCNT(op) " -"== 1`." -msgstr "" - -#: ../../c-api/object.rst:750 -msgid "" -"On a :term:`free threaded ` build, this checks if *op*'s :" -"term:`reference count` is equal to one and additionally checks if *op* is " -"only used by this thread. :c:expr:`Py_REFCNT(op) == 1` is **not** thread-" -"safe on free threaded builds; prefer this function." -msgstr "" - -#: ../../c-api/object.rst:755 -msgid "" -"The caller must hold an :term:`attached thread state`, despite the fact that " -"this function doesn't call into the Python interpreter. This function cannot " -"fail." -msgstr "" - -#: ../../c-api/object.rst:316 ../../c-api/object.rst:328 -#: ../../c-api/object.rst:353 ../../c-api/object.rst:404 -#: ../../c-api/object.rst:438 ../../c-api/object.rst:459 -msgid "built-in function" -msgstr "bulit-in function（內建函式）" - -#: ../../c-api/object.rst:316 -msgid "repr" -msgstr "repr" - -#: ../../c-api/object.rst:328 -msgid "ascii" -msgstr "ascii" - -#: ../../c-api/object.rst:336 -msgid "string" -msgstr "string（字串）" - -#: ../../c-api/object.rst:336 -msgid "PyObject_Str (C function)" -msgstr "PyObject_Str（C 函式）" - -#: ../../c-api/object.rst:353 -msgid "bytes" -msgstr "bytes（位元組）" - -#: ../../c-api/object.rst:404 -msgid "hash" -msgstr "hash（雜湊）" - -#: ../../c-api/object.rst:438 -msgid "type" -msgstr "type（型別）" - -#: ../../c-api/object.rst:459 -msgid "len" -msgstr "len" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-05 00:16+0000\n" +"PO-Revision-Date: 2018-05-23 14:32+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" + +#: ../../c-api/object.rst:6 +msgid "Object Protocol" +msgstr "物件協定" + +#: ../../c-api/object.rst:11 +msgid "Get a :term:`strong reference` to a constant." +msgstr "" + +#: ../../c-api/object.rst:13 +msgid "Set an exception and return ``NULL`` if *constant_id* is invalid." +msgstr "如果 *constant_id* 無效，則設定一個例外並回傳 ``NULL``。" + +#: ../../c-api/object.rst:15 +msgid "*constant_id* must be one of these constant identifiers:" +msgstr "*constant_id* 必須是這些常數識別字之一：" + +#: ../../c-api/object.rst:20 +msgid "Constant Identifier" +msgstr "常數識別字" + +#: ../../c-api/object.rst:20 +msgid "Value" +msgstr "數值" + +#: ../../c-api/object.rst:20 +msgid "Returned object" +msgstr "回傳物件" + +#: ../../c-api/object.rst:22 ../../c-api/object.rst:27 +msgid "``0``" +msgstr "``0``" + +#: ../../c-api/object.rst:22 +msgid ":py:data:`None`" +msgstr ":py:data:`None`" + +#: ../../c-api/object.rst:23 ../../c-api/object.rst:28 +msgid "``1``" +msgstr "``1``" + +#: ../../c-api/object.rst:23 +msgid ":py:data:`False`" +msgstr ":py:data:`False`" + +#: ../../c-api/object.rst:24 +msgid "``2``" +msgstr "``2``" + +#: ../../c-api/object.rst:24 +msgid ":py:data:`True`" +msgstr ":py:data:`True`" + +#: ../../c-api/object.rst:25 +msgid "``3``" +msgstr "``3``" + +#: ../../c-api/object.rst:25 +msgid ":py:data:`Ellipsis`" +msgstr ":py:data:`Ellipsis`" + +#: ../../c-api/object.rst:26 +msgid "``4``" +msgstr "``4``" + +#: ../../c-api/object.rst:26 +msgid ":py:data:`NotImplemented`" +msgstr ":py:data:`NotImplemented`" + +#: ../../c-api/object.rst:27 +msgid "``5``" +msgstr "``5``" + +#: ../../c-api/object.rst:28 +msgid "``6``" +msgstr "``6``" + +#: ../../c-api/object.rst:29 +msgid "``7``" +msgstr "``7``" + +#: ../../c-api/object.rst:29 +msgid "``''``" +msgstr "``''``" + +#: ../../c-api/object.rst:30 +msgid "``8``" +msgstr "``8``" + +#: ../../c-api/object.rst:30 +msgid "``b''``" +msgstr "``b''``" + +#: ../../c-api/object.rst:31 +msgid "``9``" +msgstr "``9``" + +#: ../../c-api/object.rst:31 +msgid "``()``" +msgstr "``()``" + +#: ../../c-api/object.rst:34 +msgid "" +"Numeric values are only given for projects which cannot use the constant " +"identifiers." +msgstr "" + +#: ../../c-api/object.rst:42 +msgid "In CPython, all of these constants are :term:`immortal`." +msgstr "在 CPython 中，所有這些常數都是\\ :term:`不滅 `\\ 的。" + +#: ../../c-api/object.rst:47 +msgid "" +"Similar to :c:func:`Py_GetConstant`, but return a :term:`borrowed reference`." +msgstr "" + +#: ../../c-api/object.rst:50 +msgid "" +"This function is primarily intended for backwards compatibility: using :c:" +"func:`Py_GetConstant` is recommended for new code." +msgstr "" + +#: ../../c-api/object.rst:53 +msgid "" +"The reference is borrowed from the interpreter, and is valid until the " +"interpreter finalization." +msgstr "" + +#: ../../c-api/object.rst:61 +msgid "" +"The ``NotImplemented`` singleton, used to signal that an operation is not " +"implemented for the given type combination." +msgstr "" + +#: ../../c-api/object.rst:67 +msgid "" +"Properly handle returning :c:data:`Py_NotImplemented` from within a C " +"function (that is, create a new :term:`strong reference` to :const:" +"`NotImplemented` and return it)." +msgstr "" + +#: ../../c-api/object.rst:74 +msgid "" +"Flag to be used with multiple functions that print the object (like :c:func:" +"`PyObject_Print` and :c:func:`PyFile_WriteObject`). If passed, these " +"functions use the :func:`str` of the object instead of the :func:`repr`." +msgstr "" + +#: ../../c-api/object.rst:82 +msgid "" +"Print an object *o*, on file *fp*. Returns ``-1`` on error. The flags " +"argument is used to enable certain printing options. The only option " +"currently supported is :c:macro:`Py_PRINT_RAW`; if given, the :func:`str` of " +"the object is written instead of the :func:`repr`." +msgstr "" + +#: ../../c-api/object.rst:90 +msgid "" +"Returns ``1`` if *o* has the attribute *attr_name*, and ``0`` otherwise. " +"This is equivalent to the Python expression ``hasattr(o, attr_name)``. On " +"failure, return ``-1``." +msgstr "" + +#: ../../c-api/object.rst:99 +msgid "" +"This is the same as :c:func:`PyObject_HasAttrWithError`, but *attr_name* is " +"specified as a :c:expr:`const char*` UTF-8 encoded bytes string, rather than " +"a :c:expr:`PyObject*`." +msgstr "" + +#: ../../c-api/object.rst:108 +msgid "" +"Returns ``1`` if *o* has the attribute *attr_name*, and ``0`` otherwise. " +"This function always succeeds." +msgstr "" + +#: ../../c-api/object.rst:113 +msgid "" +"Exceptions that occur when this calls :meth:`~object.__getattr__` and :meth:" +"`~object.__getattribute__` methods aren't propagated, but instead given to :" +"func:`sys.unraisablehook`. For proper error handling, use :c:func:" +"`PyObject_HasAttrWithError`, :c:func:`PyObject_GetOptionalAttr` or :c:func:" +"`PyObject_GetAttr` instead." +msgstr "" + +#: ../../c-api/object.rst:122 +msgid "" +"This is the same as :c:func:`PyObject_HasAttr`, but *attr_name* is specified " +"as a :c:expr:`const char*` UTF-8 encoded bytes string, rather than a :c:expr:" +"`PyObject*`." +msgstr "" + +#: ../../c-api/object.rst:128 +msgid "" +"Exceptions that occur when this calls :meth:`~object.__getattr__` and :meth:" +"`~object.__getattribute__` methods or while creating the temporary :class:" +"`str` object are silently ignored. For proper error handling, use :c:func:" +"`PyObject_HasAttrStringWithError`, :c:func:`PyObject_GetOptionalAttrString` " +"or :c:func:`PyObject_GetAttrString` instead." +msgstr "" + +#: ../../c-api/object.rst:138 +msgid "" +"Retrieve an attribute named *attr_name* from object *o*. Returns the " +"attribute value on success, or ``NULL`` on failure. This is the equivalent " +"of the Python expression ``o.attr_name``." +msgstr "" + +#: ../../c-api/object.rst:142 +msgid "" +"If the missing attribute should not be treated as a failure, you can use :c:" +"func:`PyObject_GetOptionalAttr` instead." +msgstr "" + +#: ../../c-api/object.rst:148 +msgid "" +"This is the same as :c:func:`PyObject_GetAttr`, but *attr_name* is specified " +"as a :c:expr:`const char*` UTF-8 encoded bytes string, rather than a :c:expr:" +"`PyObject*`." +msgstr "" + +#: ../../c-api/object.rst:152 +msgid "" +"If the missing attribute should not be treated as a failure, you can use :c:" +"func:`PyObject_GetOptionalAttrString` instead." +msgstr "" + +#: ../../c-api/object.rst:158 +msgid "" +"Variant of :c:func:`PyObject_GetAttr` which doesn't raise :exc:" +"`AttributeError` if the attribute is not found." +msgstr "" + +#: ../../c-api/object.rst:161 +msgid "" +"If the attribute is found, return ``1`` and set *\\*result* to a new :term:" +"`strong reference` to the attribute. If the attribute is not found, return " +"``0`` and set *\\*result* to ``NULL``; the :exc:`AttributeError` is " +"silenced. If an error other than :exc:`AttributeError` is raised, return " +"``-1`` and set *\\*result* to ``NULL``." +msgstr "" + +#: ../../c-api/object.rst:173 +msgid "" +"This is the same as :c:func:`PyObject_GetOptionalAttr`, but *attr_name* is " +"specified as a :c:expr:`const char*` UTF-8 encoded bytes string, rather than " +"a :c:expr:`PyObject*`." +msgstr "" + +#: ../../c-api/object.rst:181 +msgid "" +"Generic attribute getter function that is meant to be put into a type " +"object's ``tp_getattro`` slot. It looks for a descriptor in the dictionary " +"of classes in the object's MRO as well as an attribute in the object's :attr:" +"`~object.__dict__` (if present). As outlined in :ref:`descriptors`, data " +"descriptors take preference over instance attributes, while non-data " +"descriptors don't. Otherwise, an :exc:`AttributeError` is raised." +msgstr "" + +#: ../../c-api/object.rst:191 +msgid "" +"Set the value of the attribute named *attr_name*, for object *o*, to the " +"value *v*. Raise an exception and return ``-1`` on failure; return ``0`` on " +"success. This is the equivalent of the Python statement ``o.attr_name = v``." +msgstr "" + +#: ../../c-api/object.rst:196 +msgid "" +"If *v* is ``NULL``, the attribute is deleted. This behaviour is deprecated " +"in favour of using :c:func:`PyObject_DelAttr`, but there are currently no " +"plans to remove it." +msgstr "" + +#: ../../c-api/object.rst:203 +msgid "" +"This is the same as :c:func:`PyObject_SetAttr`, but *attr_name* is specified " +"as a :c:expr:`const char*` UTF-8 encoded bytes string, rather than a :c:expr:" +"`PyObject*`." +msgstr "" + +#: ../../c-api/object.rst:207 +msgid "" +"If *v* is ``NULL``, the attribute is deleted, but this feature is deprecated " +"in favour of using :c:func:`PyObject_DelAttrString`." +msgstr "" + +#: ../../c-api/object.rst:210 +msgid "" +"The number of different attribute names passed to this function should be " +"kept small, usually by using a statically allocated string as *attr_name*. " +"For attribute names that aren't known at compile time, prefer calling :c:" +"func:`PyUnicode_FromString` and :c:func:`PyObject_SetAttr` directly. For " +"more details, see :c:func:`PyUnicode_InternFromString`, which may be used " +"internally to create a key object." +msgstr "" + +#: ../../c-api/object.rst:220 +msgid "" +"Generic attribute setter and deleter function that is meant to be put into a " +"type object's :c:member:`~PyTypeObject.tp_setattro` slot. It looks for a " +"data descriptor in the dictionary of classes in the object's MRO, and if " +"found it takes preference over setting or deleting the attribute in the " +"instance dictionary. Otherwise, the attribute is set or deleted in the " +"object's :attr:`~object.__dict__` (if present). On success, ``0`` is " +"returned, otherwise an :exc:`AttributeError` is raised and ``-1`` is " +"returned." +msgstr "" + +#: ../../c-api/object.rst:232 +msgid "" +"Delete attribute named *attr_name*, for object *o*. Returns ``-1`` on " +"failure. This is the equivalent of the Python statement ``del o.attr_name``." +msgstr "" + +#: ../../c-api/object.rst:238 +msgid "" +"This is the same as :c:func:`PyObject_DelAttr`, but *attr_name* is specified " +"as a :c:expr:`const char*` UTF-8 encoded bytes string, rather than a :c:expr:" +"`PyObject*`." +msgstr "" + +#: ../../c-api/object.rst:242 +msgid "" +"The number of different attribute names passed to this function should be " +"kept small, usually by using a statically allocated string as *attr_name*. " +"For attribute names that aren't known at compile time, prefer calling :c:" +"func:`PyUnicode_FromString` and :c:func:`PyObject_DelAttr` directly. For " +"more details, see :c:func:`PyUnicode_InternFromString`, which may be used " +"internally to create a key object for lookup." +msgstr "" + +#: ../../c-api/object.rst:253 +msgid "" +"A generic implementation for the getter of a ``__dict__`` descriptor. It " +"creates the dictionary if necessary." +msgstr "" + +#: ../../c-api/object.rst:256 +msgid "" +"This function may also be called to get the :py:attr:`~object.__dict__` of " +"the object *o*. Pass ``NULL`` for *context* when calling it. Since this " +"function may need to allocate memory for the dictionary, it may be more " +"efficient to call :c:func:`PyObject_GetAttr` when accessing an attribute on " +"the object." +msgstr "" + +#: ../../c-api/object.rst:262 +msgid "On failure, returns ``NULL`` with an exception set." +msgstr "在失敗時，會回傳 ``NULL`` 並設定例外。" + +#: ../../c-api/object.rst:269 +msgid "" +"A generic implementation for the setter of a ``__dict__`` descriptor. This " +"implementation does not allow the dictionary to be deleted." +msgstr "" + +#: ../../c-api/object.rst:277 +msgid "" +"Return a pointer to :py:attr:`~object.__dict__` of the object *obj*. If " +"there is no ``__dict__``, return ``NULL`` without setting an exception." +msgstr "" + +#: ../../c-api/object.rst:280 +msgid "" +"This function may need to allocate memory for the dictionary, so it may be " +"more efficient to call :c:func:`PyObject_GetAttr` when accessing an " +"attribute on the object." +msgstr "" + +#: ../../c-api/object.rst:287 +msgid "" +"Compare the values of *o1* and *o2* using the operation specified by *opid*, " +"which must be one of :c:macro:`Py_LT`, :c:macro:`Py_LE`, :c:macro:`Py_EQ`, :" +"c:macro:`Py_NE`, :c:macro:`Py_GT`, or :c:macro:`Py_GE`, corresponding to " +"``<``, ``<=``, ``==``, ``!=``, ``>``, or ``>=`` respectively. This is the " +"equivalent of the Python expression ``o1 op o2``, where ``op`` is the " +"operator corresponding to *opid*. Returns the value of the comparison on " +"success, or ``NULL`` on failure." +msgstr "" + +#: ../../c-api/object.rst:297 +msgid "" +"Compare the values of *o1* and *o2* using the operation specified by *opid*, " +"like :c:func:`PyObject_RichCompare`, but returns ``-1`` on error, ``0`` if " +"the result is false, ``1`` otherwise." +msgstr "" + +#: ../../c-api/object.rst:302 +msgid "" +"If *o1* and *o2* are the same object, :c:func:`PyObject_RichCompareBool` " +"will always return ``1`` for :c:macro:`Py_EQ` and ``0`` for :c:macro:`Py_NE`." +msgstr "" + +#: ../../c-api/object.rst:307 +msgid "" +"Format *obj* using *format_spec*. This is equivalent to the Python " +"expression ``format(obj, format_spec)``." +msgstr "" + +#: ../../c-api/object.rst:310 +msgid "" +"*format_spec* may be ``NULL``. In this case the call is equivalent to " +"``format(obj)``. Returns the formatted string on success, ``NULL`` on " +"failure." +msgstr "" + +#: ../../c-api/object.rst:318 +msgid "" +"Compute a string representation of object *o*. Returns the string " +"representation on success, ``NULL`` on failure. This is the equivalent of " +"the Python expression ``repr(o)``. Called by the :func:`repr` built-in " +"function." +msgstr "" + +#: ../../c-api/object.rst:322 ../../c-api/object.rst:346 +msgid "" +"This function now includes a debug assertion to help ensure that it does not " +"silently discard an active exception." +msgstr "" + +#: ../../c-api/object.rst:330 +msgid "" +"As :c:func:`PyObject_Repr`, compute a string representation of object *o*, " +"but escape the non-ASCII characters in the string returned by :c:func:" +"`PyObject_Repr` with ``\\x``, ``\\u`` or ``\\U`` escapes. This generates a " +"string similar to that returned by :c:func:`PyObject_Repr` in Python 2. " +"Called by the :func:`ascii` built-in function." +msgstr "" + +#: ../../c-api/object.rst:341 +msgid "" +"Compute a string representation of object *o*. Returns the string " +"representation on success, ``NULL`` on failure. This is the equivalent of " +"the Python expression ``str(o)``. Called by the :func:`str` built-in " +"function and, therefore, by the :func:`print` function." +msgstr "" + +#: ../../c-api/object.rst:355 +msgid "" +"Compute a bytes representation of object *o*. ``NULL`` is returned on " +"failure and a bytes object on success. This is equivalent to the Python " +"expression ``bytes(o)``, when *o* is not an integer. Unlike ``bytes(o)``, a " +"TypeError is raised when *o* is an integer instead of a zero-initialized " +"bytes object." +msgstr "" + +#: ../../c-api/object.rst:364 +msgid "" +"Return ``1`` if the class *derived* is identical to or derived from the " +"class *cls*, otherwise return ``0``. In case of an error, return ``-1``." +msgstr "" + +#: ../../c-api/object.rst:367 ../../c-api/object.rst:386 +msgid "" +"If *cls* is a tuple, the check will be done against every entry in *cls*. " +"The result will be ``1`` when at least one of the checks returns ``1``, " +"otherwise it will be ``0``." +msgstr "" + +#: ../../c-api/object.rst:371 +msgid "" +"If *cls* has a :meth:`~type.__subclasscheck__` method, it will be called to " +"determine the subclass status as described in :pep:`3119`. Otherwise, " +"*derived* is a subclass of *cls* if it is a direct or indirect subclass, i." +"e. contained in :attr:`cls.__mro__ `." +msgstr "" + +#: ../../c-api/object.rst:376 +msgid "" +"Normally only class objects, i.e. instances of :class:`type` or a derived " +"class, are considered classes. However, objects can override this by having " +"a :attr:`~type.__bases__` attribute (which must be a tuple of base classes)." +msgstr "" + +#: ../../c-api/object.rst:383 +msgid "" +"Return ``1`` if *inst* is an instance of the class *cls* or a subclass of " +"*cls*, or ``0`` if not. On error, returns ``-1`` and sets an exception." +msgstr "" + +#: ../../c-api/object.rst:390 +msgid "" +"If *cls* has a :meth:`~type.__instancecheck__` method, it will be called to " +"determine the subclass status as described in :pep:`3119`. Otherwise, " +"*inst* is an instance of *cls* if its class is a subclass of *cls*." +msgstr "" + +#: ../../c-api/object.rst:394 +msgid "" +"An instance *inst* can override what is considered its class by having a :" +"attr:`~object.__class__` attribute." +msgstr "" + +#: ../../c-api/object.rst:397 +msgid "" +"An object *cls* can override if it is considered a class, and what its base " +"classes are, by having a :attr:`~type.__bases__` attribute (which must be a " +"tuple of base classes)." +msgstr "" + +#: ../../c-api/object.rst:406 +msgid "" +"Compute and return the hash value of an object *o*. On failure, return " +"``-1``. This is the equivalent of the Python expression ``hash(o)``." +msgstr "" + +#: ../../c-api/object.rst:409 +msgid "" +"The return type is now Py_hash_t. This is a signed integer the same size " +"as :c:type:`Py_ssize_t`." +msgstr "" + +#: ../../c-api/object.rst:416 +msgid "" +"Set a :exc:`TypeError` indicating that ``type(o)`` is not :term:`hashable` " +"and return ``-1``. This function receives special treatment when stored in a " +"``tp_hash`` slot, allowing a type to explicitly indicate to the interpreter " +"that it is not hashable." +msgstr "" + +#: ../../c-api/object.rst:424 +msgid "" +"Returns ``1`` if the object *o* is considered to be true, and ``0`` " +"otherwise. This is equivalent to the Python expression ``not not o``. On " +"failure, return ``-1``." +msgstr "" + +#: ../../c-api/object.rst:431 +msgid "" +"Returns ``0`` if the object *o* is considered to be true, and ``1`` " +"otherwise. This is equivalent to the Python expression ``not o``. On " +"failure, return ``-1``." +msgstr "" + +#: ../../c-api/object.rst:440 +msgid "" +"When *o* is non-``NULL``, returns a type object corresponding to the object " +"type of object *o*. On failure, raises :exc:`SystemError` and returns " +"``NULL``. This is equivalent to the Python expression ``type(o)``. This " +"function creates a new :term:`strong reference` to the return value. There's " +"really no reason to use this function instead of the :c:func:`Py_TYPE()` " +"function, which returns a pointer of type :c:expr:`PyTypeObject*`, except " +"when a new :term:`strong reference` is needed." +msgstr "" + +#: ../../c-api/object.rst:452 +msgid "" +"Return non-zero if the object *o* is of type *type* or a subtype of *type*, " +"and ``0`` otherwise. Both parameters must be non-``NULL``." +msgstr "" + +#: ../../c-api/object.rst:461 +msgid "" +"Return the length of object *o*. If the object *o* provides either the " +"sequence and mapping protocols, the sequence length is returned. On error, " +"``-1`` is returned. This is the equivalent to the Python expression " +"``len(o)``." +msgstr "" + +#: ../../c-api/object.rst:468 +msgid "" +"Return an estimated length for the object *o*. First try to return its " +"actual length, then an estimate using :meth:`~object.__length_hint__`, and " +"finally return the default value. On error return ``-1``. This is the " +"equivalent to the Python expression ``operator.length_hint(o, " +"defaultvalue)``." +msgstr "" + +#: ../../c-api/object.rst:478 +msgid "" +"Return element of *o* corresponding to the object *key* or ``NULL`` on " +"failure. This is the equivalent of the Python expression ``o[key]``." +msgstr "" + +#: ../../c-api/object.rst:484 +msgid "" +"Map the object *key* to the value *v*. Raise an exception and return ``-1`` " +"on failure; return ``0`` on success. This is the equivalent of the Python " +"statement ``o[key] = v``. This function *does not* steal a reference to *v*." +msgstr "" + +#: ../../c-api/object.rst:492 +msgid "" +"Remove the mapping for the object *key* from the object *o*. Return ``-1`` " +"on failure. This is equivalent to the Python statement ``del o[key]``." +msgstr "" + +#: ../../c-api/object.rst:498 +msgid "" +"This is the same as :c:func:`PyObject_DelItem`, but *key* is specified as a :" +"c:expr:`const char*` UTF-8 encoded bytes string, rather than a :c:expr:" +"`PyObject*`." +msgstr "" + +#: ../../c-api/object.rst:505 +msgid "" +"This is equivalent to the Python expression ``dir(o)``, returning a " +"(possibly empty) list of strings appropriate for the object argument, or " +"``NULL`` if there was an error. If the argument is ``NULL``, this is like " +"the Python ``dir()``, returning the names of the current locals; in this " +"case, if no execution frame is active then ``NULL`` is returned but :c:func:" +"`PyErr_Occurred` will return false." +msgstr "" + +#: ../../c-api/object.rst:514 +msgid "" +"This is equivalent to the Python expression ``iter(o)``. It returns a new " +"iterator for the object argument, or the object itself if the object is " +"already an iterator. Raises :exc:`TypeError` and returns ``NULL`` if the " +"object cannot be iterated." +msgstr "" + +#: ../../c-api/object.rst:522 +msgid "" +"This is equivalent to the Python ``__iter__(self): return self`` method. It " +"is intended for :term:`iterator` types, to be used in the :c:member:" +"`PyTypeObject.tp_iter` slot." +msgstr "" + +#: ../../c-api/object.rst:528 +msgid "" +"This is the equivalent to the Python expression ``aiter(o)``. Takes an :" +"class:`AsyncIterable` object and returns an :class:`AsyncIterator` for it. " +"This is typically a new iterator but if the argument is an :class:" +"`AsyncIterator`, this returns itself. Raises :exc:`TypeError` and returns " +"``NULL`` if the object cannot be iterated." +msgstr "" + +#: ../../c-api/object.rst:538 +msgid "Get a pointer to subclass-specific data reserved for *cls*." +msgstr "" + +#: ../../c-api/object.rst:540 +msgid "" +"The object *o* must be an instance of *cls*, and *cls* must have been " +"created using negative :c:member:`PyType_Spec.basicsize`. Python does not " +"check this." +msgstr "" + +#: ../../c-api/object.rst:544 +msgid "On error, set an exception and return ``NULL``." +msgstr "錯誤時設定一個例外並回傳 ``NULL``。" + +#: ../../c-api/object.rst:550 +msgid "" +"Return the size of the instance memory space reserved for *cls*, i.e. the " +"size of the memory :c:func:`PyObject_GetTypeData` returns." +msgstr "" + +#: ../../c-api/object.rst:553 +msgid "" +"This may be larger than requested using :c:member:`-PyType_Spec.basicsize " +"`; it is safe to use this larger size (e.g. with :c:" +"func:`!memset`)." +msgstr "" + +#: ../../c-api/object.rst:556 +msgid "" +"The type *cls* **must** have been created using negative :c:member:" +"`PyType_Spec.basicsize`. Python does not check this." +msgstr "" + +#: ../../c-api/object.rst:560 +msgid "On error, set an exception and return a negative value." +msgstr "錯誤時設定一個例外並回傳一個負值。" + +#: ../../c-api/object.rst:566 +msgid "" +"Get a pointer to per-item data for a class with :c:macro:" +"`Py_TPFLAGS_ITEMS_AT_END`." +msgstr "" + +#: ../../c-api/object.rst:569 +msgid "" +"On error, set an exception and return ``NULL``. :py:exc:`TypeError` is " +"raised if *o* does not have :c:macro:`Py_TPFLAGS_ITEMS_AT_END` set." +msgstr "" +"錯誤時設定一個例外並回傳 ``NULL``。如果 *o* 沒有設定 :c:macro:" +"`Py_TPFLAGS_ITEMS_AT_END`，則會引發 :py:exc:`TypeError`。" + +#: ../../c-api/object.rst:577 +msgid "Visit the managed dictionary of *obj*." +msgstr "" + +#: ../../c-api/object.rst:579 +msgid "" +"This function must only be called in a traverse function of the type which " +"has the :c:macro:`Py_TPFLAGS_MANAGED_DICT` flag set." +msgstr "" + +#: ../../c-api/object.rst:586 +msgid "Clear the managed dictionary of *obj*." +msgstr "" + +#: ../../c-api/object.rst:588 +msgid "" +"This function must only be called in a clear function of the type which has " +"the :c:macro:`Py_TPFLAGS_MANAGED_DICT` flag set." +msgstr "" + +#: ../../c-api/object.rst:595 +msgid "" +"Enable `deferred reference counting `_ on *obj*, if supported by the runtime. In " +"the :term:`free-threaded ` build, this allows the " +"interpreter to avoid reference count adjustments to *obj*, which may improve " +"multi-threaded performance. The tradeoff is that *obj* will only be " +"deallocated by the tracing garbage collector, and not when the interpreter " +"no longer has any references to it." +msgstr "" + +#: ../../c-api/object.rst:602 +msgid "" +"This function returns ``1`` if deferred reference counting is enabled on " +"*obj*, and ``0`` if deferred reference counting is not supported or if the " +"hint was ignored by the interpreter, such as when deferred reference " +"counting is already enabled on *obj*. This function is thread-safe, and " +"cannot fail." +msgstr "" + +#: ../../c-api/object.rst:607 +msgid "" +"This function does nothing on builds with the :term:`GIL` enabled, which do " +"not support deferred reference counting. This also does nothing if *obj* is " +"not an object tracked by the garbage collector (see :func:`gc.is_tracked` " +"and :c:func:`PyObject_GC_IsTracked`)." +msgstr "" + +#: ../../c-api/object.rst:612 +msgid "" +"This function is intended to be used soon after *obj* is created, by the " +"code that creates it, such as in the object's :c:member:`~PyTypeObject." +"tp_new` slot." +msgstr "" + +#: ../../c-api/object.rst:620 +msgid "" +"Check if *obj* is a unique temporary object. Returns ``1`` if *obj* is known " +"to be a unique temporary object, and ``0`` otherwise. This function cannot " +"fail, but the check is conservative, and may return ``0`` in some cases even " +"if *obj* is a unique temporary object." +msgstr "" + +#: ../../c-api/object.rst:626 +msgid "" +"If an object is a unique temporary, it is guaranteed that the current code " +"has the only reference to the object. For arguments to C functions, this " +"should be used instead of checking if the reference count is ``1``. Starting " +"with Python 3.14, the interpreter internally avoids some reference count " +"modifications when loading objects onto the operands stack by :term:" +"`borrowing ` references when possible, which means that " +"a reference count of ``1`` by itself does not guarantee that a function " +"argument uniquely referenced." +msgstr "" + +#: ../../c-api/object.rst:635 +msgid "" +"In the example below, ``my_func`` is called with a unique temporary object " +"as its argument::" +msgstr "" + +#: ../../c-api/object.rst:638 +msgid "my_func([1, 2, 3])" +msgstr "my_func([1, 2, 3])" + +#: ../../c-api/object.rst:640 +msgid "" +"In the example below, ``my_func`` is **not** called with a unique temporary " +"object as its argument, even if its refcount is ``1``::" +msgstr "" + +#: ../../c-api/object.rst:643 +msgid "" +"my_list = [1, 2, 3]\n" +"my_func(my_list)" +msgstr "" +"my_list = [1, 2, 3]\n" +"my_func(my_list)" + +#: ../../c-api/object.rst:646 +msgid "See also the function :c:func:`Py_REFCNT`." +msgstr "另請參閱 :c:func:`Py_REFCNT` 函式。" + +#: ../../c-api/object.rst:652 +msgid "" +"This function returns non-zero if *obj* is :term:`immortal`, and zero " +"otherwise. This function cannot fail." +msgstr "" + +#: ../../c-api/object.rst:657 +msgid "" +"Objects that are immortal in one CPython version are not guaranteed to be " +"immortal in another." +msgstr "" + +#: ../../c-api/object.rst:664 +msgid "" +"Increments the reference count of *obj* if it is not zero. Returns ``1`` if " +"the object's reference count was successfully incremented. Otherwise, this " +"function returns ``0``." +msgstr "" + +#: ../../c-api/object.rst:668 +msgid "" +":c:func:`PyUnstable_EnableTryIncRef` must have been called earlier on *obj* " +"or this function may spuriously return ``0`` in the :term:`free threading` " +"build." +msgstr "" + +#: ../../c-api/object.rst:672 +msgid "" +"This function is logically equivalent to the following C code, except that " +"it behaves atomically in the :term:`free threading` build::" +msgstr "" + +#: ../../c-api/object.rst:675 +msgid "" +"if (Py_REFCNT(op) > 0) {\n" +" Py_INCREF(op);\n" +" return 1;\n" +"}\n" +"return 0;" +msgstr "" +"if (Py_REFCNT(op) > 0) {\n" +" Py_INCREF(op);\n" +" return 1;\n" +"}\n" +"return 0;" + +#: ../../c-api/object.rst:681 +msgid "" +"This is intended as a building block for managing weak references without " +"the overhead of a Python :ref:`weak reference object `." +msgstr "" + +#: ../../c-api/object.rst:684 +msgid "" +"Typically, correct use of this function requires support from *obj*'s " +"deallocator (:c:member:`~PyTypeObject.tp_dealloc`). For example, the " +"following sketch could be adapted to implement a \"weakmap\" that works like " +"a :py:class:`~weakref.WeakValueDictionary` for a specific type:" +msgstr "" + +#: ../../c-api/object.rst:690 +msgid "" +"PyMutex mutex;\n" +"\n" +"PyObject *\n" +"add_entry(weakmap_key_type *key, PyObject *value)\n" +"{\n" +" PyUnstable_EnableTryIncRef(value);\n" +" weakmap_type weakmap = ...;\n" +" PyMutex_Lock(&mutex);\n" +" weakmap_add_entry(weakmap, key, value);\n" +" PyMutex_Unlock(&mutex);\n" +" Py_RETURN_NONE;\n" +"}\n" +"\n" +"PyObject *\n" +"get_value(weakmap_key_type *key)\n" +"{\n" +" weakmap_type weakmap = ...;\n" +" PyMutex_Lock(&mutex);\n" +" PyObject *result = weakmap_find(weakmap, key);\n" +" if (PyUnstable_TryIncRef(result)) {\n" +" // `result` is safe to use\n" +" PyMutex_Unlock(&mutex);\n" +" return result;\n" +" }\n" +" // if we get here, `result` is starting to be garbage-collected,\n" +" // but has not been removed from the weakmap yet\n" +" PyMutex_Unlock(&mutex);\n" +" return NULL;\n" +"}\n" +"\n" +"// tp_dealloc function for weakmap values\n" +"void\n" +"value_dealloc(PyObject *value)\n" +"{\n" +" weakmap_type weakmap = ...;\n" +" PyMutex_Lock(&mutex);\n" +" weakmap_remove_value(weakmap, value);\n" +"\n" +" ...\n" +" PyMutex_Unlock(&mutex);\n" +"}" +msgstr "" + +#: ../../c-api/object.rst:738 +msgid "" +"Enables subsequent uses of :c:func:`PyUnstable_TryIncRef` on *obj*. The " +"caller must hold a :term:`strong reference` to *obj* when calling this." +msgstr "" + +#: ../../c-api/object.rst:745 +msgid "Determine if *op* only has one reference." +msgstr "" + +#: ../../c-api/object.rst:747 +msgid "" +"On GIL-enabled builds, this function is equivalent to :c:expr:`Py_REFCNT(op) " +"== 1`." +msgstr "" + +#: ../../c-api/object.rst:750 +msgid "" +"On a :term:`free threaded ` build, this checks if *op*'s :" +"term:`reference count` is equal to one and additionally checks if *op* is " +"only used by this thread. :c:expr:`Py_REFCNT(op) == 1` is **not** thread-" +"safe on free threaded builds; prefer this function." +msgstr "" + +#: ../../c-api/object.rst:755 +msgid "" +"The caller must hold an :term:`attached thread state`, despite the fact that " +"this function doesn't call into the Python interpreter. This function cannot " +"fail." +msgstr "" + +#: ../../c-api/object.rst:316 ../../c-api/object.rst:328 +#: ../../c-api/object.rst:353 ../../c-api/object.rst:404 +#: ../../c-api/object.rst:438 ../../c-api/object.rst:459 +msgid "built-in function" +msgstr "bulit-in function（內建函式）" + +#: ../../c-api/object.rst:316 +msgid "repr" +msgstr "repr" + +#: ../../c-api/object.rst:328 +msgid "ascii" +msgstr "ascii" + +#: ../../c-api/object.rst:336 +msgid "string" +msgstr "string（字串）" + +#: ../../c-api/object.rst:336 +msgid "PyObject_Str (C function)" +msgstr "PyObject_Str（C 函式）" + +#: ../../c-api/object.rst:353 +msgid "bytes" +msgstr "bytes（位元組）" + +#: ../../c-api/object.rst:404 +msgid "hash" +msgstr "hash（雜湊）" + +#: ../../c-api/object.rst:438 +msgid "type" +msgstr "type（型別）" + +#: ../../c-api/object.rst:459 +msgid "len" +msgstr "len" diff --git a/c-api/objimpl.po b/c-api/objimpl.po index e01909fd1f..9fc43ef105 100644 --- a/c-api/objimpl.po +++ b/c-api/objimpl.po @@ -1,28 +1,28 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2018-06-26 18:54+0800\n" -"PO-Revision-Date: 2025-07-14 02:51+0000\n" -"Last-Translator: AI Assistant\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" - -#: ../../c-api/objimpl.rst:7 -msgid "Object Implementation Support" -msgstr "物件實作支援" - -#: ../../c-api/objimpl.rst:9 -msgid "" -"This chapter describes the functions, types, and macros used when defining " -"new object types." -msgstr "本章節說明在定義新的物件型別時所使用的函式、型別和巨集。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2018-06-26 18:54+0800\n" +"PO-Revision-Date: 2025-07-14 02:51+0000\n" +"Last-Translator: AI Assistant\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" + +#: ../../c-api/objimpl.rst:7 +msgid "Object Implementation Support" +msgstr "物件實作支援" + +#: ../../c-api/objimpl.rst:9 +msgid "" +"This chapter describes the functions, types, and macros used when defining " +"new object types." +msgstr "本章節說明在定義新的物件型別時所使用的函式、型別和巨集。" diff --git a/c-api/perfmaps.po b/c-api/perfmaps.po index 026a9131c8..e06badd7ee 100644 --- a/c-api/perfmaps.po +++ b/c-api/perfmaps.po @@ -1,116 +1,116 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Matt Wang , 2024 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: 2024-05-11 14:42+0800\n" -"Last-Translator: Matt Wang \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" - -#: ../../c-api/perfmaps.rst:6 -msgid "Support for Perf Maps" -msgstr "對 Perf Map 的支援" - -#: ../../c-api/perfmaps.rst:8 -msgid "" -"On supported platforms (as of this writing, only Linux), the runtime can " -"take advantage of *perf map files* to make Python functions visible to an " -"external profiling tool (such as `perf `_). A running process may create a file in the ``/tmp`` " -"directory, which contains entries that can map a section of executable code " -"to a name. This interface is described in the `documentation of the Linux " -"Perf tool `_." -msgstr "" -"在支援的平台上（截至撰寫本文時，僅限 Linux），runtime 可以利用 *perf map 檔案" -"*\\ 使得外部分析工具（例如 `perf `_）可以見到 Python 函式。正在運行的行程可能會在 ``/tmp`` 目錄中建" -"立一個檔案，其中包含可以將一段可執行程式碼對映到名稱的各個條目。此介面在 " -"`Linux Perf 工具的文件 `_\\ 中有" -"被描述。" - -#: ../../c-api/perfmaps.rst:16 -msgid "" -"In Python, these helper APIs can be used by libraries and features that rely " -"on generating machine code on the fly." -msgstr "" -"在 Python 中，這些輔助 API 可以被依賴於運行期間 (on the fly) 產生機器碼的函式" -"庫和功能所使用。" - -#: ../../c-api/perfmaps.rst:19 -msgid "" -"Note that holding an :term:`attached thread state` is not required for these " -"APIs." -msgstr "請注意，這些 API 不需要持有 :term:`attached thread state`。" - -#: ../../c-api/perfmaps.rst:23 -msgid "" -"Open the ``/tmp/perf-$pid.map`` file, unless it's already opened, and create " -"a lock to ensure thread-safe writes to the file (provided the writes are " -"done through :c:func:`PyUnstable_WritePerfMapEntry`). Normally, there's no " -"need to call this explicitly; just " -"use :c:func:`PyUnstable_WritePerfMapEntry` and it will initialize the state " -"on first call." -msgstr "" -"打開 ``/tmp/perf-$pid.map`` 檔案，除非它已經打開，並建立一個鎖以確保執行緒安" -"全地 (thread-safe) 寫入該檔案（前提是寫入是透" -"過 :c:func:`PyUnstable_WritePerfMapEntry` 完成的）。通常不需要明確地呼叫它；" -"只需使用 :c:func:`PyUnstable_WritePerfMapEntry` 它就會在首次呼叫時初始化狀" -"態。" - -#: ../../c-api/perfmaps.rst:29 -msgid "" -"Returns ``0`` on success, ``-1`` on failure to create/open the perf map " -"file, or ``-2`` on failure to create a lock. Check ``errno`` for more " -"information about the cause of a failure." -msgstr "" -"建立/打開 perf map 檔案成功時回傳 ``0``，失敗時回傳 ``-1``，建立鎖時失敗則回" -"傳 ``-2``。檢查 ``errno`` 以取得更多造成失敗的資訊。" - -#: ../../c-api/perfmaps.rst:35 -msgid "" -"Write one single entry to the ``/tmp/perf-$pid.map`` file. This function is " -"thread safe. Here is what an example entry looks like::" -msgstr "" -"將單一條目寫入 ``/tmp/perf-$pid.map`` 檔案。此函式是執行緒安全的。以下是一個" -"條目的範例：" - -#: ../../c-api/perfmaps.rst:38 -msgid "" -"# address size name\n" -"7f3529fcf759 b py::bar:/run/t.py" -msgstr "" -"# 位址 大小 名稱\n" -"7f3529fcf759 b py::bar:/run/t.py" - -#: ../../c-api/perfmaps.rst:41 -msgid "" -"Will call :c:func:`PyUnstable_PerfMapState_Init` before writing the entry, " -"if the perf map file is not already opened. Returns ``0`` on success, or the " -"same error codes as :c:func:`PyUnstable_PerfMapState_Init` on failure." -msgstr "" -"如果尚未開啟 perf map 檔案，將在寫入條目之前呼" -"叫 :c:func:`PyUnstable_PerfMapState_Init`。成功時回傳 ``0``，失敗時回傳" -"與 :c:func:`PyUnstable_PerfMapState_Init` 失敗時相同的錯誤碼。" - -#: ../../c-api/perfmaps.rst:47 -msgid "" -"Close the perf map file opened by :c:func:`PyUnstable_PerfMapState_Init`. " -"This is called by the runtime itself during interpreter shut-down. In " -"general, there shouldn't be a reason to explicitly call this, except to " -"handle specific scenarios such as forking." -msgstr "" -"關閉由 :c:func:`PyUnstable_PerfMapState_Init` 開啟的 perf map 檔案，這是在直" -"譯器關閉期間由 runtime 本身呼叫的。一般來說，除了處理 forking 等特定場景外，" -"不應該明確地呼叫它。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Matt Wang , 2024 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: 2024-05-11 14:42+0800\n" +"Last-Translator: Matt Wang \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" + +#: ../../c-api/perfmaps.rst:6 +msgid "Support for Perf Maps" +msgstr "對 Perf Map 的支援" + +#: ../../c-api/perfmaps.rst:8 +msgid "" +"On supported platforms (as of this writing, only Linux), the runtime can " +"take advantage of *perf map files* to make Python functions visible to an " +"external profiling tool (such as `perf `_). A running process may create a file in the ``/tmp`` " +"directory, which contains entries that can map a section of executable code " +"to a name. This interface is described in the `documentation of the Linux " +"Perf tool `_." +msgstr "" +"在支援的平台上（截至撰寫本文時，僅限 Linux），runtime 可以利用 *perf map 檔案" +"*\\ 使得外部分析工具（例如 `perf `_）可以見到 Python 函式。正在運行的行程可能會在 ``/tmp`` 目錄中建" +"立一個檔案，其中包含可以將一段可執行程式碼對映到名稱的各個條目。此介面在 " +"`Linux Perf 工具的文件 `_\\ 中有" +"被描述。" + +#: ../../c-api/perfmaps.rst:16 +msgid "" +"In Python, these helper APIs can be used by libraries and features that rely " +"on generating machine code on the fly." +msgstr "" +"在 Python 中，這些輔助 API 可以被依賴於運行期間 (on the fly) 產生機器碼的函式" +"庫和功能所使用。" + +#: ../../c-api/perfmaps.rst:19 +msgid "" +"Note that holding an :term:`attached thread state` is not required for these " +"APIs." +msgstr "請注意，這些 API 不需要持有 :term:`attached thread state`。" + +#: ../../c-api/perfmaps.rst:23 +msgid "" +"Open the ``/tmp/perf-$pid.map`` file, unless it's already opened, and create " +"a lock to ensure thread-safe writes to the file (provided the writes are " +"done through :c:func:`PyUnstable_WritePerfMapEntry`). Normally, there's no " +"need to call this explicitly; just " +"use :c:func:`PyUnstable_WritePerfMapEntry` and it will initialize the state " +"on first call." +msgstr "" +"打開 ``/tmp/perf-$pid.map`` 檔案，除非它已經打開，並建立一個鎖以確保執行緒安" +"全地 (thread-safe) 寫入該檔案（前提是寫入是透" +"過 :c:func:`PyUnstable_WritePerfMapEntry` 完成的）。通常不需要明確地呼叫它；" +"只需使用 :c:func:`PyUnstable_WritePerfMapEntry` 它就會在首次呼叫時初始化狀" +"態。" + +#: ../../c-api/perfmaps.rst:29 +msgid "" +"Returns ``0`` on success, ``-1`` on failure to create/open the perf map " +"file, or ``-2`` on failure to create a lock. Check ``errno`` for more " +"information about the cause of a failure." +msgstr "" +"建立/打開 perf map 檔案成功時回傳 ``0``，失敗時回傳 ``-1``，建立鎖時失敗則回" +"傳 ``-2``。檢查 ``errno`` 以取得更多造成失敗的資訊。" + +#: ../../c-api/perfmaps.rst:35 +msgid "" +"Write one single entry to the ``/tmp/perf-$pid.map`` file. This function is " +"thread safe. Here is what an example entry looks like::" +msgstr "" +"將單一條目寫入 ``/tmp/perf-$pid.map`` 檔案。此函式是執行緒安全的。以下是一個" +"條目的範例：" + +#: ../../c-api/perfmaps.rst:38 +msgid "" +"# address size name\n" +"7f3529fcf759 b py::bar:/run/t.py" +msgstr "" +"# 位址 大小 名稱\n" +"7f3529fcf759 b py::bar:/run/t.py" + +#: ../../c-api/perfmaps.rst:41 +msgid "" +"Will call :c:func:`PyUnstable_PerfMapState_Init` before writing the entry, " +"if the perf map file is not already opened. Returns ``0`` on success, or the " +"same error codes as :c:func:`PyUnstable_PerfMapState_Init` on failure." +msgstr "" +"如果尚未開啟 perf map 檔案，將在寫入條目之前呼" +"叫 :c:func:`PyUnstable_PerfMapState_Init`。成功時回傳 ``0``，失敗時回傳" +"與 :c:func:`PyUnstable_PerfMapState_Init` 失敗時相同的錯誤碼。" + +#: ../../c-api/perfmaps.rst:47 +msgid "" +"Close the perf map file opened by :c:func:`PyUnstable_PerfMapState_Init`. " +"This is called by the runtime itself during interpreter shut-down. In " +"general, there shouldn't be a reason to explicitly call this, except to " +"handle specific scenarios such as forking." +msgstr "" +"關閉由 :c:func:`PyUnstable_PerfMapState_Init` 開啟的 perf map 檔案，這是在直" +"譯器關閉期間由 runtime 本身呼叫的。一般來說，除了處理 forking 等特定場景外，" +"不應該明確地呼叫它。" diff --git a/c-api/picklebuffer.po b/c-api/picklebuffer.po index 1e73246ba7..a62a6036b8 100644 --- a/c-api/picklebuffer.po +++ b/c-api/picklebuffer.po @@ -1,101 +1,101 @@ -# SOME DESCRIPTIVE TITLE. -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# FIRST AUTHOR , YEAR. -# -#, fuzzy -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-17 00:14+0000\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language-Team: LANGUAGE \n" -"Language: zh_TW\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=UTF-8\n" -"Content-Transfer-Encoding: 8bit\n" - -#: ../../c-api/picklebuffer.rst:9 -msgid "Pickle buffer objects" -msgstr "" - -#: ../../c-api/picklebuffer.rst:13 -msgid "" -"A :class:`pickle.PickleBuffer` object wraps a :ref:`buffer-providing object " -"` for out-of-band data transfer with the :mod:`pickle` module." -msgstr "" - -#: ../../c-api/picklebuffer.rst:19 -msgid "" -"This instance of :c:type:`PyTypeObject` represents the Python pickle buffer " -"type. This is the same object as :class:`pickle.PickleBuffer` in the Python " -"layer." -msgstr "" - -#: ../../c-api/picklebuffer.rst:25 -msgid "" -"Return true if *op* is a pickle buffer instance. This function always " -"succeeds." -msgstr "" - -#: ../../c-api/picklebuffer.rst:31 -msgid "Create a pickle buffer from the object *obj*." -msgstr "" - -#: ../../c-api/picklebuffer.rst:33 -msgid "" -"This function will fail if *obj* doesn't support the :ref:`buffer protocol " -"`." -msgstr "" - -#: ../../c-api/picklebuffer.rst:35 -msgid "" -"On success, return a new pickle buffer instance. On failure, set an " -"exception and return ``NULL``." -msgstr "" - -#: ../../c-api/picklebuffer.rst:38 -msgid "Analogous to calling :class:`pickle.PickleBuffer` with *obj* in Python." -msgstr "" - -#: ../../c-api/picklebuffer.rst:43 -msgid "" -"Get a pointer to the underlying :c:type:`Py_buffer` that the pickle buffer " -"wraps." -msgstr "" - -#: ../../c-api/picklebuffer.rst:45 -msgid "" -"The returned pointer is valid as long as *picklebuf* is alive and has not " -"been released. The caller must not modify or free the returned :c:type:" -"`Py_buffer`. If the pickle buffer has been released, raise :exc:`ValueError`." -msgstr "" - -#: ../../c-api/picklebuffer.rst:49 -msgid "" -"On success, return a pointer to the buffer view. On failure, set an " -"exception and return ``NULL``." -msgstr "" - -#: ../../c-api/picklebuffer.rst:55 -msgid "Release the underlying buffer held by the pickle buffer." -msgstr "" - -#: ../../c-api/picklebuffer.rst:57 -msgid "" -"Return ``0`` on success. On failure, set an exception and return ``-1``." -msgstr "" - -#: ../../c-api/picklebuffer.rst:59 -msgid "Analogous to calling :meth:`pickle.PickleBuffer.release` in Python." -msgstr "" - -#: ../../c-api/picklebuffer.rst:5 -msgid "object" -msgstr "" - -#: ../../c-api/picklebuffer.rst:5 -msgid "PickleBuffer" -msgstr "" +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-17 00:14+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"Language: zh_TW\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../c-api/picklebuffer.rst:9 +msgid "Pickle buffer objects" +msgstr "" + +#: ../../c-api/picklebuffer.rst:13 +msgid "" +"A :class:`pickle.PickleBuffer` object wraps a :ref:`buffer-providing object " +"` for out-of-band data transfer with the :mod:`pickle` module." +msgstr "" + +#: ../../c-api/picklebuffer.rst:19 +msgid "" +"This instance of :c:type:`PyTypeObject` represents the Python pickle buffer " +"type. This is the same object as :class:`pickle.PickleBuffer` in the Python " +"layer." +msgstr "" + +#: ../../c-api/picklebuffer.rst:25 +msgid "" +"Return true if *op* is a pickle buffer instance. This function always " +"succeeds." +msgstr "" + +#: ../../c-api/picklebuffer.rst:31 +msgid "Create a pickle buffer from the object *obj*." +msgstr "" + +#: ../../c-api/picklebuffer.rst:33 +msgid "" +"This function will fail if *obj* doesn't support the :ref:`buffer protocol " +"`." +msgstr "" + +#: ../../c-api/picklebuffer.rst:35 +msgid "" +"On success, return a new pickle buffer instance. On failure, set an " +"exception and return ``NULL``." +msgstr "" + +#: ../../c-api/picklebuffer.rst:38 +msgid "Analogous to calling :class:`pickle.PickleBuffer` with *obj* in Python." +msgstr "" + +#: ../../c-api/picklebuffer.rst:43 +msgid "" +"Get a pointer to the underlying :c:type:`Py_buffer` that the pickle buffer " +"wraps." +msgstr "" + +#: ../../c-api/picklebuffer.rst:45 +msgid "" +"The returned pointer is valid as long as *picklebuf* is alive and has not " +"been released. The caller must not modify or free the returned :c:type:" +"`Py_buffer`. If the pickle buffer has been released, raise :exc:`ValueError`." +msgstr "" + +#: ../../c-api/picklebuffer.rst:49 +msgid "" +"On success, return a pointer to the buffer view. On failure, set an " +"exception and return ``NULL``." +msgstr "" + +#: ../../c-api/picklebuffer.rst:55 +msgid "Release the underlying buffer held by the pickle buffer." +msgstr "" + +#: ../../c-api/picklebuffer.rst:57 +msgid "" +"Return ``0`` on success. On failure, set an exception and return ``-1``." +msgstr "" + +#: ../../c-api/picklebuffer.rst:59 +msgid "Analogous to calling :meth:`pickle.PickleBuffer.release` in Python." +msgstr "" + +#: ../../c-api/picklebuffer.rst:5 +msgid "object" +msgstr "" + +#: ../../c-api/picklebuffer.rst:5 +msgid "PickleBuffer" +msgstr "" diff --git a/c-api/refcounting.po b/c-api/refcounting.po index 3ad5095d4d..f313003ec6 100644 --- a/c-api/refcounting.po +++ b/c-api/refcounting.po @@ -1,373 +1,373 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Leon H., 2017 -# Matt Wang , 2023 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: 2023-08-06 14:19+0800\n" -"Last-Translator: Matt Wang \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" -"X-Generator: Poedit 3.3.2\n" - -#: ../../c-api/refcounting.rst:8 -msgid "Reference Counting" -msgstr "參照計數" - -#: ../../c-api/refcounting.rst:10 -msgid "" -"The functions and macros in this section are used for managing reference " -"counts of Python objects." -msgstr "本節中的函式與巨集用於管理 Python 物件的參照計數。" - -#: ../../c-api/refcounting.rst:16 -msgid "Get the reference count of the Python object *o*." -msgstr "取得物件 *o* 的參照計數。" - -#: ../../c-api/refcounting.rst:18 -msgid "" -"Note that the returned value may not actually reflect how many references to " -"the object are actually held. For example, some objects " -"are :term:`immortal` and have a very high refcount that does not reflect the " -"actual number of references. Consequently, do not rely on the returned " -"value to be accurate, other than a value of 0 or 1." -msgstr "" -"請注意，回傳的值可能實際上並不反映實際保存了多少對該物件的參照。例如，某些物" -"件是「:term:`不滅的 (immortal) `」，並且具有非常高的參照計數，不能" -"反映實際的參照數量。因此，除了 0 或 1 以外，不要依賴回傳值的準確性。" - -#: ../../c-api/refcounting.rst:24 -msgid "" -"Use the :c:func:`Py_SET_REFCNT()` function to set an object reference count." -msgstr "使用 :c:func:`Py_SET_REFCNT()` 函式設定物件參照計數。" - -#: ../../c-api/refcounting.rst:28 -msgid "" -"On :term:`free threaded ` builds of Python, returning 1 " -"isn't sufficient to determine if it's safe to treat *o* as having no access " -"by other threads. Use :c:func:`PyUnstable_Object_IsUniquelyReferenced` for " -"that instead." -msgstr "" - -#: ../../c-api/refcounting.rst:33 -msgid "" -"See also the " -"function :c:func:`PyUnstable_Object_IsUniqueReferencedTemporary()`." -msgstr "" - -#: ../../c-api/refcounting.rst:35 -msgid ":c:func:`Py_REFCNT()` is changed to the inline static function." -msgstr ":c:func:`Py_REFCNT()` 更改為行內靜態函式 (inline static function)。" - -#: ../../c-api/refcounting.rst:38 -msgid "The parameter type is no longer :c:expr:`const PyObject*`." -msgstr "參數型別不再是 :c:expr:`const PyObject*`。" - -#: ../../c-api/refcounting.rst:44 -msgid "Set the object *o* reference counter to *refcnt*." -msgstr "設定物件 *o* 的參照計數。" - -#: ../../c-api/refcounting.rst:46 -msgid "" -"On :ref:`Python build with Free Threading `, if " -"*refcnt* is larger than ``UINT32_MAX``, the object is made :term:`immortal`." -msgstr "" -"在\\ :ref:`啟用自由執行緒的 Python 建置 `\\ 中，如果 " -"*refcnt* 大於 ``UINT32_MAX``，則該物件會被設為\\ :term:`不滅的 (immortal) " -"`。" - -#: ../../c-api/refcounting.rst:49 ../../c-api/refcounting.rst:62 -#: ../../c-api/refcounting.rst:128 -msgid "This function has no effect on :term:`immortal` objects." -msgstr "請注意，此函式對\\ :term:`不滅的 `\\ 物件沒有影響。" - -#: ../../c-api/refcounting.rst:53 ../../c-api/refcounting.rst:77 -#: ../../c-api/refcounting.rst:156 -msgid "Immortal objects are not modified." -msgstr "不滅的物件不會被修改。" - -#: ../../c-api/refcounting.rst:59 -msgid "" -"Indicate taking a new :term:`strong reference` to object *o*, indicating it " -"is in use and should not be destroyed." -msgstr "" -"代表取得對於物件 *o* 的新\\ :term:`強參照 `，即它正在使用且" -"不應被銷毀。" - -#: ../../c-api/refcounting.rst:64 -msgid "" -"This function is usually used to convert a :term:`borrowed reference` to " -"a :term:`strong reference` in-place. The :c:func:`Py_NewRef` function can be " -"used to create a new :term:`strong reference`." -msgstr "" -"此函式通常用於將\\ :term:`借用參照 `\\ 原地 (in-place) 轉" -"換為\\ :term:`強參照 `。:c:func:`Py_NewRef` 函式可用於建立" -"新的\\ :term:`強參照 `。" - -#: ../../c-api/refcounting.rst:68 -msgid "When done using the object, release is by calling :c:func:`Py_DECREF`." -msgstr "使用完該物件後，透過呼叫 :c:func:`Py_DECREF` 來釋放它。" - -#: ../../c-api/refcounting.rst:70 -msgid "" -"The object must not be ``NULL``; if you aren't sure that it isn't ``NULL``, " -"use :c:func:`Py_XINCREF`." -msgstr "" -"該物件不能為 ``NULL``；如果你不確定它不是 ``NULL``，請使" -"用 :c:func:`Py_XINCREF`。" - -#: ../../c-api/refcounting.rst:73 -msgid "" -"Do not expect this function to actually modify *o* in any way. For at " -"least :pep:`some objects <0683>`, this function has no effect." -msgstr "" -"不要期望此函式會以任何方式實際修改 *o*，至少對於\\ :pep:`某些物件 <0683>`\\ " -"來說，此函式沒有任何效果。" - -#: ../../c-api/refcounting.rst:83 -msgid "" -"Similar to :c:func:`Py_INCREF`, but the object *o* can be ``NULL``, in which " -"case this has no effect." -msgstr "" -"與 :c:func:`Py_INCREF` 類似，但物件 *o* 可以為 ``NULL``，在這種情況下這就不會" -"有任何效果。" - -#: ../../c-api/refcounting.rst:86 -msgid "See also :c:func:`Py_XNewRef`." -msgstr "另請見 :c:func:`Py_XNewRef`。" - -#: ../../c-api/refcounting.rst:91 -msgid "" -"Create a new :term:`strong reference` to an object: call :c:func:`Py_INCREF` " -"on *o* and return the object *o*." -msgstr "" -"建立對物件的新\\ :term:`強參照 `：於 *o* 呼" -"叫 :c:func:`Py_INCREF` 並回傳物件 *o*。" - -#: ../../c-api/refcounting.rst:94 -msgid "" -"When the :term:`strong reference` is no longer needed, :c:func:`Py_DECREF` " -"should be called on it to release the reference." -msgstr "" -"當不再需要\\ :term:`強參照 `\\ 時，應對其呼" -"叫 :c:func:`Py_DECREF` 以釋放該參照。" - -#: ../../c-api/refcounting.rst:97 -msgid "" -"The object *o* must not be ``NULL``; use :c:func:`Py_XNewRef` if *o* can be " -"``NULL``." -msgstr "" -"物件 *o* 不能為 ``NULL``；如果 *o* 可以為 ``NULL``，則使" -"用 :c:func:`Py_XNewRef`。" - -#: ../../c-api/refcounting.rst:100 -msgid "For example::" -msgstr "舉例來說： ::" - -#: ../../c-api/refcounting.rst:102 -msgid "" -"Py_INCREF(obj);\n" -"self->attr = obj;" -msgstr "" -"Py_INCREF(obj);\n" -"self->attr = obj;" - -#: ../../c-api/refcounting.rst:105 -msgid "can be written as::" -msgstr "可以寫成： ::" - -#: ../../c-api/refcounting.rst:107 -msgid "self->attr = Py_NewRef(obj);" -msgstr "self->attr = Py_NewRef(obj);" - -#: ../../c-api/refcounting.rst:109 -msgid "See also :c:func:`Py_INCREF`." -msgstr "另請參閱 :c:func:`Py_INCREF`。" - -#: ../../c-api/refcounting.rst:116 -msgid "Similar to :c:func:`Py_NewRef`, but the object *o* can be NULL." -msgstr "與 :c:func:`Py_NewRef` 類似，但物件 *o* 可以為 NULL。" - -#: ../../c-api/refcounting.rst:118 -msgid "If the object *o* is ``NULL``, the function just returns ``NULL``." -msgstr "如果物件 *o* 為 ``NULL``，則該函式僅回傳 ``NULL``。" - -#: ../../c-api/refcounting.rst:125 -msgid "" -"Release a :term:`strong reference` to object *o*, indicating the reference " -"is no longer used." -msgstr "" -"釋放一個對物件 *o* 的\\ :term:`強參照 `，代表該參照不會再被" -"使用。" - -#: ../../c-api/refcounting.rst:130 -msgid "" -"Once the last :term:`strong reference` is released (i.e. the object's " -"reference count reaches 0), the object's type's deallocation function (which " -"must not be ``NULL``) is invoked." -msgstr "" -"如果最後一個\\ :term:`強參照 `\\ 被釋放（即物件的參照計數達" -"到零），則觸發物件之型別的釋放函式 (deallocation function)（不得為 " -"``NULL``\\ ）。" - -#: ../../c-api/refcounting.rst:135 -msgid "" -"This function is usually used to delete a :term:`strong reference` before " -"exiting its scope." -msgstr "" -"此函式通常用於在退出作用域之前刪除\\ :term:`強參照 `。" - -#: ../../c-api/refcounting.rst:138 -msgid "" -"The object must not be ``NULL``; if you aren't sure that it isn't ``NULL``, " -"use :c:func:`Py_XDECREF`." -msgstr "" -"該物件不能為 ``NULL``；如果你不確定它不是 ``NULL``，請改" -"用 :c:func:`Py_XDECREF`。" - -#: ../../c-api/refcounting.rst:141 -msgid "" -"Do not expect this function to actually modify *o* in any way. For at " -"least :pep:`some objects <683>`, this function has no effect." -msgstr "" -"不要期望此函式會以任何方式實際修改 *o*，至少對於\\ :pep:`某些物件 <683>`\\ 來" -"說，此函式沒有任何效果。" - -#: ../../c-api/refcounting.rst:147 -msgid "" -"The deallocation function can cause arbitrary Python code to be invoked " -"(e.g. when a class instance with a :meth:`~object.__del__` method is " -"deallocated). While exceptions in such code are not propagated, the " -"executed code has free access to all Python global variables. This means " -"that any object that is reachable from a global variable should be in a " -"consistent state before :c:func:`Py_DECREF` is invoked. For example, code " -"to delete an object from a list should copy a reference to the deleted " -"object in a temporary variable, update the list data structure, and then " -"call :c:func:`Py_DECREF` for the temporary variable." -msgstr "" -"釋放函式可以導致任意 Python 程式碼被叫用（例如，當釋放具" -"有 :meth:`~object.__del__` 方法的類別實例時）。雖然此類程式碼中的例外不會被傳" -"遞出來，但​​執行的程式碼可以自由存取所有 Python 全域變數。這意味著在叫" -"用 :c:func:`Py_DECREF` 之前，可從全域變數存取的任何物件都應處於一致狀態。例" -"如，從 list 中刪除物件的程式碼應將已刪除物件的參照複製到臨時變數中，更新 " -"list 資料結構，然後為臨時變數呼叫 :c:func:`Py_DECREF`。" - -#: ../../c-api/refcounting.rst:162 -msgid "" -"Similar to :c:func:`Py_DECREF`, but the object *o* can be ``NULL``, in which " -"case this has no effect. The same warning from :c:func:`Py_DECREF` applies " -"here as well." -msgstr "" -"和 :c:func:`Py_DECREF` 類似，但該物件可以是 ``NULL``，在這種情況下巨集不起作" -"用。在這裡也會出現與 :c:func:`Py_DECREF` 相同的警告。" - -#: ../../c-api/refcounting.rst:169 -msgid "" -"Release a :term:`strong reference` for object *o*. The object may be " -"``NULL``, in which case the macro has no effect; otherwise the effect is the " -"same as for :c:func:`Py_DECREF`, except that the argument is also set to " -"``NULL``. The warning for :c:func:`Py_DECREF` does not apply with respect " -"to the object passed because the macro carefully uses a temporary variable " -"and sets the argument to ``NULL`` before releasing the reference." -msgstr "" -"釋放對於物件 *o* 的\\ :term:`強參照 `。該物件可能是 " -"``NULL``，在這種情況下巨集不起作用；否則，效果與 :c:func:`Py_DECREF` 相同，除" -"非引數也設定為 ``NULL``。:c:func:`Py_DECREF` 的警告不適用於傳遞的物件，因為巨" -"集在釋放其參照之前小心地使用臨時變數並將引數設定為 ``NULL``。" - -#: ../../c-api/refcounting.rst:177 -msgid "" -"It is a good idea to use this macro whenever releasing a reference to an " -"object that might be traversed during garbage collection." -msgstr "" -"每當要釋放垃圾回收 (garbage collection) 期間可能被遍歷到之對於物件的參照時，" -"使用此巨集是個好主意。" - -#: ../../c-api/refcounting.rst:180 -msgid "" -"The macro argument is now only evaluated once. If the argument has side " -"effects, these are no longer duplicated." -msgstr "" -"巨集引數現在僅會被求值 (evaluate) 一次。如果引數有其他副作用，則不再重複作" -"用。" - -#: ../../c-api/refcounting.rst:187 -msgid "" -"Indicate taking a new :term:`strong reference` to object *o*. A function " -"version of :c:func:`Py_XINCREF`. It can be used for runtime dynamic " -"embedding of Python." -msgstr "" -"代表取得對於物件 *o* 的\\ :term:`強參照 `。:c:func:`Py_XINCREF` 的函式版本。它可用於 Python 的 runtime 動態" -"嵌入。" - -#: ../../c-api/refcounting.rst:194 -msgid "" -"Release a :term:`strong reference` to object *o*. A function version " -"of :c:func:`Py_XDECREF`. It can be used for runtime dynamic embedding of " -"Python." -msgstr "" -"釋放對物件 *o* 的\\ :term:`強參照 `。:c:func:`Py_XDECREF` " -"的函式版本。它可用於 Python 的 runtime 動態嵌入。" - -#: ../../c-api/refcounting.rst:201 -msgid "" -"Macro safely releasing a :term:`strong reference` to object *dst* and " -"setting *dst* to *src*." -msgstr "" -"巨集安全地釋放對於物件 *dst* 的\\ :term:`強參照 `\\ 並將 " -"*dst* 設定為 *src*。" - -#: ../../c-api/refcounting.rst:204 -msgid "As in case of :c:func:`Py_CLEAR`, \"the obvious\" code can be deadly::" -msgstr "與 :c:func:`Py_CLEAR` 的情況一樣，「明顯的」程式碼可能是致命的： ::" - -#: ../../c-api/refcounting.rst:206 -msgid "" -"Py_DECREF(dst);\n" -"dst = src;" -msgstr "" -"Py_DECREF(dst);\n" -"dst = src;" - -#: ../../c-api/refcounting.rst:209 -msgid "The safe way is::" -msgstr "安全的方法是： ::" - -#: ../../c-api/refcounting.rst:211 -msgid "Py_SETREF(dst, src);" -msgstr "Py_SETREF(dst, src);" - -#: ../../c-api/refcounting.rst:213 -msgid "" -"That arranges to set *dst* to *src* *before* releasing the reference to the " -"old value of *dst*, so that any code triggered as a side-effect of *dst* " -"getting torn down no longer believes *dst* points to a valid object." -msgstr "" -"這會在釋放對 *dst* 舊值的參照\\ *之前*\\ 將 *dst* 設定為 *src*，使得因 *dst* " -"被拆除而觸發的任何副作用 (side-effect) 之程式碼不會相信 *dst* 是指向一個有效" -"物件。" - -#: ../../c-api/refcounting.rst:220 ../../c-api/refcounting.rst:232 -msgid "" -"The macro arguments are now only evaluated once. If an argument has side " -"effects, these are no longer duplicated." -msgstr "巨集引數現在僅會被求值一次。如果引數有其他副作用，則不再重複作用。" - -#: ../../c-api/refcounting.rst:227 -msgid "" -"Variant of :c:macro:`Py_SETREF` macro that uses :c:func:`Py_XDECREF` instead " -"of :c:func:`Py_DECREF`." -msgstr "" -":c:macro:`Py_SETREF` 巨集的變體，請改用 :c:func:`Py_XDECREF` 而" -"非 :c:func:`Py_DECREF`。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Leon H., 2017 +# Matt Wang , 2023 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: 2023-08-06 14:19+0800\n" +"Last-Translator: Matt Wang \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" +"X-Generator: Poedit 3.3.2\n" + +#: ../../c-api/refcounting.rst:8 +msgid "Reference Counting" +msgstr "參照計數" + +#: ../../c-api/refcounting.rst:10 +msgid "" +"The functions and macros in this section are used for managing reference " +"counts of Python objects." +msgstr "本節中的函式與巨集用於管理 Python 物件的參照計數。" + +#: ../../c-api/refcounting.rst:16 +msgid "Get the reference count of the Python object *o*." +msgstr "取得物件 *o* 的參照計數。" + +#: ../../c-api/refcounting.rst:18 +msgid "" +"Note that the returned value may not actually reflect how many references to " +"the object are actually held. For example, some objects " +"are :term:`immortal` and have a very high refcount that does not reflect the " +"actual number of references. Consequently, do not rely on the returned " +"value to be accurate, other than a value of 0 or 1." +msgstr "" +"請注意，回傳的值可能實際上並不反映實際保存了多少對該物件的參照。例如，某些物" +"件是「:term:`不滅的 (immortal) `」，並且具有非常高的參照計數，不能" +"反映實際的參照數量。因此，除了 0 或 1 以外，不要依賴回傳值的準確性。" + +#: ../../c-api/refcounting.rst:24 +msgid "" +"Use the :c:func:`Py_SET_REFCNT()` function to set an object reference count." +msgstr "使用 :c:func:`Py_SET_REFCNT()` 函式設定物件參照計數。" + +#: ../../c-api/refcounting.rst:28 +msgid "" +"On :term:`free threaded ` builds of Python, returning 1 " +"isn't sufficient to determine if it's safe to treat *o* as having no access " +"by other threads. Use :c:func:`PyUnstable_Object_IsUniquelyReferenced` for " +"that instead." +msgstr "" + +#: ../../c-api/refcounting.rst:33 +msgid "" +"See also the " +"function :c:func:`PyUnstable_Object_IsUniqueReferencedTemporary()`." +msgstr "" + +#: ../../c-api/refcounting.rst:35 +msgid ":c:func:`Py_REFCNT()` is changed to the inline static function." +msgstr ":c:func:`Py_REFCNT()` 更改為行內靜態函式 (inline static function)。" + +#: ../../c-api/refcounting.rst:38 +msgid "The parameter type is no longer :c:expr:`const PyObject*`." +msgstr "參數型別不再是 :c:expr:`const PyObject*`。" + +#: ../../c-api/refcounting.rst:44 +msgid "Set the object *o* reference counter to *refcnt*." +msgstr "設定物件 *o* 的參照計數。" + +#: ../../c-api/refcounting.rst:46 +msgid "" +"On :ref:`Python build with Free Threading `, if " +"*refcnt* is larger than ``UINT32_MAX``, the object is made :term:`immortal`." +msgstr "" +"在\\ :ref:`啟用自由執行緒的 Python 建置 `\\ 中，如果 " +"*refcnt* 大於 ``UINT32_MAX``，則該物件會被設為\\ :term:`不滅的 (immortal) " +"`。" + +#: ../../c-api/refcounting.rst:49 ../../c-api/refcounting.rst:62 +#: ../../c-api/refcounting.rst:128 +msgid "This function has no effect on :term:`immortal` objects." +msgstr "請注意，此函式對\\ :term:`不滅的 `\\ 物件沒有影響。" + +#: ../../c-api/refcounting.rst:53 ../../c-api/refcounting.rst:77 +#: ../../c-api/refcounting.rst:156 +msgid "Immortal objects are not modified." +msgstr "不滅的物件不會被修改。" + +#: ../../c-api/refcounting.rst:59 +msgid "" +"Indicate taking a new :term:`strong reference` to object *o*, indicating it " +"is in use and should not be destroyed." +msgstr "" +"代表取得對於物件 *o* 的新\\ :term:`強參照 `，即它正在使用且" +"不應被銷毀。" + +#: ../../c-api/refcounting.rst:64 +msgid "" +"This function is usually used to convert a :term:`borrowed reference` to " +"a :term:`strong reference` in-place. The :c:func:`Py_NewRef` function can be " +"used to create a new :term:`strong reference`." +msgstr "" +"此函式通常用於將\\ :term:`借用參照 `\\ 原地 (in-place) 轉" +"換為\\ :term:`強參照 `。:c:func:`Py_NewRef` 函式可用於建立" +"新的\\ :term:`強參照 `。" + +#: ../../c-api/refcounting.rst:68 +msgid "When done using the object, release is by calling :c:func:`Py_DECREF`." +msgstr "使用完該物件後，透過呼叫 :c:func:`Py_DECREF` 來釋放它。" + +#: ../../c-api/refcounting.rst:70 +msgid "" +"The object must not be ``NULL``; if you aren't sure that it isn't ``NULL``, " +"use :c:func:`Py_XINCREF`." +msgstr "" +"該物件不能為 ``NULL``；如果你不確定它不是 ``NULL``，請使" +"用 :c:func:`Py_XINCREF`。" + +#: ../../c-api/refcounting.rst:73 +msgid "" +"Do not expect this function to actually modify *o* in any way. For at " +"least :pep:`some objects <0683>`, this function has no effect." +msgstr "" +"不要期望此函式會以任何方式實際修改 *o*，至少對於\\ :pep:`某些物件 <0683>`\\ " +"來說，此函式沒有任何效果。" + +#: ../../c-api/refcounting.rst:83 +msgid "" +"Similar to :c:func:`Py_INCREF`, but the object *o* can be ``NULL``, in which " +"case this has no effect." +msgstr "" +"與 :c:func:`Py_INCREF` 類似，但物件 *o* 可以為 ``NULL``，在這種情況下這就不會" +"有任何效果。" + +#: ../../c-api/refcounting.rst:86 +msgid "See also :c:func:`Py_XNewRef`." +msgstr "另請見 :c:func:`Py_XNewRef`。" + +#: ../../c-api/refcounting.rst:91 +msgid "" +"Create a new :term:`strong reference` to an object: call :c:func:`Py_INCREF` " +"on *o* and return the object *o*." +msgstr "" +"建立對物件的新\\ :term:`強參照 `：於 *o* 呼" +"叫 :c:func:`Py_INCREF` 並回傳物件 *o*。" + +#: ../../c-api/refcounting.rst:94 +msgid "" +"When the :term:`strong reference` is no longer needed, :c:func:`Py_DECREF` " +"should be called on it to release the reference." +msgstr "" +"當不再需要\\ :term:`強參照 `\\ 時，應對其呼" +"叫 :c:func:`Py_DECREF` 以釋放該參照。" + +#: ../../c-api/refcounting.rst:97 +msgid "" +"The object *o* must not be ``NULL``; use :c:func:`Py_XNewRef` if *o* can be " +"``NULL``." +msgstr "" +"物件 *o* 不能為 ``NULL``；如果 *o* 可以為 ``NULL``，則使" +"用 :c:func:`Py_XNewRef`。" + +#: ../../c-api/refcounting.rst:100 +msgid "For example::" +msgstr "舉例來說： ::" + +#: ../../c-api/refcounting.rst:102 +msgid "" +"Py_INCREF(obj);\n" +"self->attr = obj;" +msgstr "" +"Py_INCREF(obj);\n" +"self->attr = obj;" + +#: ../../c-api/refcounting.rst:105 +msgid "can be written as::" +msgstr "可以寫成： ::" + +#: ../../c-api/refcounting.rst:107 +msgid "self->attr = Py_NewRef(obj);" +msgstr "self->attr = Py_NewRef(obj);" + +#: ../../c-api/refcounting.rst:109 +msgid "See also :c:func:`Py_INCREF`." +msgstr "另請參閱 :c:func:`Py_INCREF`。" + +#: ../../c-api/refcounting.rst:116 +msgid "Similar to :c:func:`Py_NewRef`, but the object *o* can be NULL." +msgstr "與 :c:func:`Py_NewRef` 類似，但物件 *o* 可以為 NULL。" + +#: ../../c-api/refcounting.rst:118 +msgid "If the object *o* is ``NULL``, the function just returns ``NULL``." +msgstr "如果物件 *o* 為 ``NULL``，則該函式僅回傳 ``NULL``。" + +#: ../../c-api/refcounting.rst:125 +msgid "" +"Release a :term:`strong reference` to object *o*, indicating the reference " +"is no longer used." +msgstr "" +"釋放一個對物件 *o* 的\\ :term:`強參照 `，代表該參照不會再被" +"使用。" + +#: ../../c-api/refcounting.rst:130 +msgid "" +"Once the last :term:`strong reference` is released (i.e. the object's " +"reference count reaches 0), the object's type's deallocation function (which " +"must not be ``NULL``) is invoked." +msgstr "" +"如果最後一個\\ :term:`強參照 `\\ 被釋放（即物件的參照計數達" +"到零），則觸發物件之型別的釋放函式 (deallocation function)（不得為 " +"``NULL``\\ ）。" + +#: ../../c-api/refcounting.rst:135 +msgid "" +"This function is usually used to delete a :term:`strong reference` before " +"exiting its scope." +msgstr "" +"此函式通常用於在退出作用域之前刪除\\ :term:`強參照 `。" + +#: ../../c-api/refcounting.rst:138 +msgid "" +"The object must not be ``NULL``; if you aren't sure that it isn't ``NULL``, " +"use :c:func:`Py_XDECREF`." +msgstr "" +"該物件不能為 ``NULL``；如果你不確定它不是 ``NULL``，請改" +"用 :c:func:`Py_XDECREF`。" + +#: ../../c-api/refcounting.rst:141 +msgid "" +"Do not expect this function to actually modify *o* in any way. For at " +"least :pep:`some objects <683>`, this function has no effect." +msgstr "" +"不要期望此函式會以任何方式實際修改 *o*，至少對於\\ :pep:`某些物件 <683>`\\ 來" +"說，此函式沒有任何效果。" + +#: ../../c-api/refcounting.rst:147 +msgid "" +"The deallocation function can cause arbitrary Python code to be invoked " +"(e.g. when a class instance with a :meth:`~object.__del__` method is " +"deallocated). While exceptions in such code are not propagated, the " +"executed code has free access to all Python global variables. This means " +"that any object that is reachable from a global variable should be in a " +"consistent state before :c:func:`Py_DECREF` is invoked. For example, code " +"to delete an object from a list should copy a reference to the deleted " +"object in a temporary variable, update the list data structure, and then " +"call :c:func:`Py_DECREF` for the temporary variable." +msgstr "" +"釋放函式可以導致任意 Python 程式碼被叫用（例如，當釋放具" +"有 :meth:`~object.__del__` 方法的類別實例時）。雖然此類程式碼中的例外不會被傳" +"遞出來，但​​執行的程式碼可以自由存取所有 Python 全域變數。這意味著在叫" +"用 :c:func:`Py_DECREF` 之前，可從全域變數存取的任何物件都應處於一致狀態。例" +"如，從 list 中刪除物件的程式碼應將已刪除物件的參照複製到臨時變數中，更新 " +"list 資料結構，然後為臨時變數呼叫 :c:func:`Py_DECREF`。" + +#: ../../c-api/refcounting.rst:162 +msgid "" +"Similar to :c:func:`Py_DECREF`, but the object *o* can be ``NULL``, in which " +"case this has no effect. The same warning from :c:func:`Py_DECREF` applies " +"here as well." +msgstr "" +"和 :c:func:`Py_DECREF` 類似，但該物件可以是 ``NULL``，在這種情況下巨集不起作" +"用。在這裡也會出現與 :c:func:`Py_DECREF` 相同的警告。" + +#: ../../c-api/refcounting.rst:169 +msgid "" +"Release a :term:`strong reference` for object *o*. The object may be " +"``NULL``, in which case the macro has no effect; otherwise the effect is the " +"same as for :c:func:`Py_DECREF`, except that the argument is also set to " +"``NULL``. The warning for :c:func:`Py_DECREF` does not apply with respect " +"to the object passed because the macro carefully uses a temporary variable " +"and sets the argument to ``NULL`` before releasing the reference." +msgstr "" +"釋放對於物件 *o* 的\\ :term:`強參照 `。該物件可能是 " +"``NULL``，在這種情況下巨集不起作用；否則，效果與 :c:func:`Py_DECREF` 相同，除" +"非引數也設定為 ``NULL``。:c:func:`Py_DECREF` 的警告不適用於傳遞的物件，因為巨" +"集在釋放其參照之前小心地使用臨時變數並將引數設定為 ``NULL``。" + +#: ../../c-api/refcounting.rst:177 +msgid "" +"It is a good idea to use this macro whenever releasing a reference to an " +"object that might be traversed during garbage collection." +msgstr "" +"每當要釋放垃圾回收 (garbage collection) 期間可能被遍歷到之對於物件的參照時，" +"使用此巨集是個好主意。" + +#: ../../c-api/refcounting.rst:180 +msgid "" +"The macro argument is now only evaluated once. If the argument has side " +"effects, these are no longer duplicated." +msgstr "" +"巨集引數現在僅會被求值 (evaluate) 一次。如果引數有其他副作用，則不再重複作" +"用。" + +#: ../../c-api/refcounting.rst:187 +msgid "" +"Indicate taking a new :term:`strong reference` to object *o*. A function " +"version of :c:func:`Py_XINCREF`. It can be used for runtime dynamic " +"embedding of Python." +msgstr "" +"代表取得對於物件 *o* 的\\ :term:`強參照 `。:c:func:`Py_XINCREF` 的函式版本。它可用於 Python 的 runtime 動態" +"嵌入。" + +#: ../../c-api/refcounting.rst:194 +msgid "" +"Release a :term:`strong reference` to object *o*. A function version " +"of :c:func:`Py_XDECREF`. It can be used for runtime dynamic embedding of " +"Python." +msgstr "" +"釋放對物件 *o* 的\\ :term:`強參照 `。:c:func:`Py_XDECREF` " +"的函式版本。它可用於 Python 的 runtime 動態嵌入。" + +#: ../../c-api/refcounting.rst:201 +msgid "" +"Macro safely releasing a :term:`strong reference` to object *dst* and " +"setting *dst* to *src*." +msgstr "" +"巨集安全地釋放對於物件 *dst* 的\\ :term:`強參照 `\\ 並將 " +"*dst* 設定為 *src*。" + +#: ../../c-api/refcounting.rst:204 +msgid "As in case of :c:func:`Py_CLEAR`, \"the obvious\" code can be deadly::" +msgstr "與 :c:func:`Py_CLEAR` 的情況一樣，「明顯的」程式碼可能是致命的： ::" + +#: ../../c-api/refcounting.rst:206 +msgid "" +"Py_DECREF(dst);\n" +"dst = src;" +msgstr "" +"Py_DECREF(dst);\n" +"dst = src;" + +#: ../../c-api/refcounting.rst:209 +msgid "The safe way is::" +msgstr "安全的方法是： ::" + +#: ../../c-api/refcounting.rst:211 +msgid "Py_SETREF(dst, src);" +msgstr "Py_SETREF(dst, src);" + +#: ../../c-api/refcounting.rst:213 +msgid "" +"That arranges to set *dst* to *src* *before* releasing the reference to the " +"old value of *dst*, so that any code triggered as a side-effect of *dst* " +"getting torn down no longer believes *dst* points to a valid object." +msgstr "" +"這會在釋放對 *dst* 舊值的參照\\ *之前*\\ 將 *dst* 設定為 *src*，使得因 *dst* " +"被拆除而觸發的任何副作用 (side-effect) 之程式碼不會相信 *dst* 是指向一個有效" +"物件。" + +#: ../../c-api/refcounting.rst:220 ../../c-api/refcounting.rst:232 +msgid "" +"The macro arguments are now only evaluated once. If an argument has side " +"effects, these are no longer duplicated." +msgstr "巨集引數現在僅會被求值一次。如果引數有其他副作用，則不再重複作用。" + +#: ../../c-api/refcounting.rst:227 +msgid "" +"Variant of :c:macro:`Py_SETREF` macro that uses :c:func:`Py_XDECREF` instead " +"of :c:func:`Py_DECREF`." +msgstr "" +":c:macro:`Py_SETREF` 巨集的變體，請改用 :c:func:`Py_XDECREF` 而" +"非 :c:func:`Py_DECREF`。" diff --git a/c-api/reflection.po b/c-api/reflection.po index ceb70a288b..7bfdc6799f 100644 --- a/c-api/reflection.po +++ b/c-api/reflection.po @@ -1,130 +1,130 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: 2015-12-09 17:51+0000\n" -"Last-Translator: Liang-Bo Wang \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" - -#: ../../c-api/reflection.rst:6 -msgid "Reflection" -msgstr "" - -#: ../../c-api/reflection.rst:12 -msgid "Use :c:func:`PyEval_GetFrameBuiltins` instead." -msgstr "" - -#: ../../c-api/reflection.rst:14 ../../c-api/reflection.rst:66 -msgid "" -"Return a dictionary of the builtins in the current execution frame, or the " -"interpreter of the thread state if no frame is currently executing." -msgstr "" - -#: ../../c-api/reflection.rst:22 -msgid "" -"Use either :c:func:`PyEval_GetFrameLocals` to obtain the same behaviour as " -"calling :func:`locals` in Python code, or else " -"call :c:func:`PyFrame_GetLocals` on the result of :c:func:`PyEval_GetFrame` " -"to access the :attr:`~frame.f_locals` attribute of the currently executing " -"frame." -msgstr "" - -#: ../../c-api/reflection.rst:27 -msgid "" -"Return a mapping providing access to the local variables in the current " -"execution frame, or ``NULL`` if no frame is currently executing." -msgstr "" - -#: ../../c-api/reflection.rst:30 -msgid "" -"Refer to :func:`locals` for details of the mapping returned at different " -"scopes." -msgstr "" - -#: ../../c-api/reflection.rst:32 -msgid "" -"As this function returns a :term:`borrowed reference`, the dictionary " -"returned for :term:`optimized scopes ` is cached on the " -"frame object and will remain alive as long as the frame object does. " -"Unlike :c:func:`PyEval_GetFrameLocals` and :func:`locals`, subsequent calls " -"to this function in the same frame will update the contents of the cached " -"dictionary to reflect changes in the state of the local variables rather " -"than returning a new snapshot." -msgstr "" - -#: ../../c-api/reflection.rst:39 -msgid "" -"As part of :pep:`667`, :c:func:`PyFrame_GetLocals`, :func:`locals`, " -"and :attr:`FrameType.f_locals ` no longer make use of the " -"shared cache dictionary. Refer to the :ref:`What's New entry ` for additional details." -msgstr "" - -#: ../../c-api/reflection.rst:50 -msgid "Use :c:func:`PyEval_GetFrameGlobals` instead." -msgstr "" - -#: ../../c-api/reflection.rst:52 -msgid "" -"Return a dictionary of the global variables in the current execution frame, " -"or ``NULL`` if no frame is currently executing." -msgstr "" - -#: ../../c-api/reflection.rst:58 -msgid "" -"Return the :term:`attached thread state`'s frame, which is ``NULL`` if no " -"frame is currently executing." -msgstr "" - -#: ../../c-api/reflection.rst:61 -msgid "See also :c:func:`PyThreadState_GetFrame`." -msgstr "另請見 :c:func:`PyThreadState_GetFrame`。" - -#: ../../c-api/reflection.rst:74 -msgid "" -"Return a dictionary of the local variables in the current execution frame, " -"or ``NULL`` if no frame is currently executing. Equivalent to " -"calling :func:`locals` in Python code." -msgstr "" - -#: ../../c-api/reflection.rst:78 -msgid "" -"To access :attr:`~frame.f_locals` on the current frame without making an " -"independent snapshot in :term:`optimized scopes `, " -"call :c:func:`PyFrame_GetLocals` on the result of :c:func:`PyEval_GetFrame`." -msgstr "" - -#: ../../c-api/reflection.rst:87 -msgid "" -"Return a dictionary of the global variables in the current execution frame, " -"or ``NULL`` if no frame is currently executing. Equivalent to " -"calling :func:`globals` in Python code." -msgstr "" - -#: ../../c-api/reflection.rst:96 -msgid "" -"Return the name of *func* if it is a function, class or instance object, " -"else the name of *func*\\s type." -msgstr "" - -#: ../../c-api/reflection.rst:102 -msgid "" -"Return a description string, depending on the type of *func*. Return values " -"include \"()\" for functions and methods, \" constructor\", \" instance\", " -"and \" object\". Concatenated with the result " -"of :c:func:`PyEval_GetFuncName`, the result will be a description of *func*." -msgstr "" - -#~ msgid "*frame* must not be ``NULL``." -#~ msgstr "*frame* 不可為 ``NULL``。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: 2015-12-09 17:51+0000\n" +"Last-Translator: Liang-Bo Wang \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" + +#: ../../c-api/reflection.rst:6 +msgid "Reflection" +msgstr "" + +#: ../../c-api/reflection.rst:12 +msgid "Use :c:func:`PyEval_GetFrameBuiltins` instead." +msgstr "" + +#: ../../c-api/reflection.rst:14 ../../c-api/reflection.rst:66 +msgid "" +"Return a dictionary of the builtins in the current execution frame, or the " +"interpreter of the thread state if no frame is currently executing." +msgstr "" + +#: ../../c-api/reflection.rst:22 +msgid "" +"Use either :c:func:`PyEval_GetFrameLocals` to obtain the same behaviour as " +"calling :func:`locals` in Python code, or else " +"call :c:func:`PyFrame_GetLocals` on the result of :c:func:`PyEval_GetFrame` " +"to access the :attr:`~frame.f_locals` attribute of the currently executing " +"frame." +msgstr "" + +#: ../../c-api/reflection.rst:27 +msgid "" +"Return a mapping providing access to the local variables in the current " +"execution frame, or ``NULL`` if no frame is currently executing." +msgstr "" + +#: ../../c-api/reflection.rst:30 +msgid "" +"Refer to :func:`locals` for details of the mapping returned at different " +"scopes." +msgstr "" + +#: ../../c-api/reflection.rst:32 +msgid "" +"As this function returns a :term:`borrowed reference`, the dictionary " +"returned for :term:`optimized scopes ` is cached on the " +"frame object and will remain alive as long as the frame object does. " +"Unlike :c:func:`PyEval_GetFrameLocals` and :func:`locals`, subsequent calls " +"to this function in the same frame will update the contents of the cached " +"dictionary to reflect changes in the state of the local variables rather " +"than returning a new snapshot." +msgstr "" + +#: ../../c-api/reflection.rst:39 +msgid "" +"As part of :pep:`667`, :c:func:`PyFrame_GetLocals`, :func:`locals`, " +"and :attr:`FrameType.f_locals ` no longer make use of the " +"shared cache dictionary. Refer to the :ref:`What's New entry ` for additional details." +msgstr "" + +#: ../../c-api/reflection.rst:50 +msgid "Use :c:func:`PyEval_GetFrameGlobals` instead." +msgstr "" + +#: ../../c-api/reflection.rst:52 +msgid "" +"Return a dictionary of the global variables in the current execution frame, " +"or ``NULL`` if no frame is currently executing." +msgstr "" + +#: ../../c-api/reflection.rst:58 +msgid "" +"Return the :term:`attached thread state`'s frame, which is ``NULL`` if no " +"frame is currently executing." +msgstr "" + +#: ../../c-api/reflection.rst:61 +msgid "See also :c:func:`PyThreadState_GetFrame`." +msgstr "另請見 :c:func:`PyThreadState_GetFrame`。" + +#: ../../c-api/reflection.rst:74 +msgid "" +"Return a dictionary of the local variables in the current execution frame, " +"or ``NULL`` if no frame is currently executing. Equivalent to " +"calling :func:`locals` in Python code." +msgstr "" + +#: ../../c-api/reflection.rst:78 +msgid "" +"To access :attr:`~frame.f_locals` on the current frame without making an " +"independent snapshot in :term:`optimized scopes `, " +"call :c:func:`PyFrame_GetLocals` on the result of :c:func:`PyEval_GetFrame`." +msgstr "" + +#: ../../c-api/reflection.rst:87 +msgid "" +"Return a dictionary of the global variables in the current execution frame, " +"or ``NULL`` if no frame is currently executing. Equivalent to " +"calling :func:`globals` in Python code." +msgstr "" + +#: ../../c-api/reflection.rst:96 +msgid "" +"Return the name of *func* if it is a function, class or instance object, " +"else the name of *func*\\s type." +msgstr "" + +#: ../../c-api/reflection.rst:102 +msgid "" +"Return a description string, depending on the type of *func*. Return values " +"include \"()\" for functions and methods, \" constructor\", \" instance\", " +"and \" object\". Concatenated with the result " +"of :c:func:`PyEval_GetFuncName`, the result will be a description of *func*." +msgstr "" + +#~ msgid "*frame* must not be ``NULL``." +#~ msgstr "*frame* 不可為 ``NULL``。" diff --git a/c-api/sequence.po b/c-api/sequence.po index 912fea56bf..a9148e667c 100644 --- a/c-api/sequence.po +++ b/c-api/sequence.po @@ -1,223 +1,223 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: 2018-05-23 14:32+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" - -#: ../../c-api/sequence.rst:6 -msgid "Sequence Protocol" -msgstr "序列協定" - -#: ../../c-api/sequence.rst:11 -msgid "" -"Return ``1`` if the object provides the sequence protocol, and ``0`` " -"otherwise. Note that it returns ``1`` for Python classes with " -"a :meth:`~object.__getitem__` method, unless they are :class:`dict` " -"subclasses, since in general it is impossible to determine what type of keys " -"the class supports. This function always succeeds." -msgstr "" - -#: ../../c-api/sequence.rst:23 -msgid "" -"Returns the number of objects in sequence *o* on success, and ``-1`` on " -"failure. This is equivalent to the Python expression ``len(o)``." -msgstr "" - -#: ../../c-api/sequence.rst:29 -msgid "" -"Return the concatenation of *o1* and *o2* on success, and ``NULL`` on " -"failure. This is the equivalent of the Python expression ``o1 + o2``." -msgstr "" - -#: ../../c-api/sequence.rst:35 -msgid "" -"Return the result of repeating sequence object *o* *count* times, or " -"``NULL`` on failure. This is the equivalent of the Python expression ``o * " -"count``." -msgstr "" - -#: ../../c-api/sequence.rst:41 -msgid "" -"Return the concatenation of *o1* and *o2* on success, and ``NULL`` on " -"failure. The operation is done *in-place* when *o1* supports it. This is " -"the equivalent of the Python expression ``o1 += o2``." -msgstr "" - -#: ../../c-api/sequence.rst:48 -msgid "" -"Return the result of repeating sequence object *o* *count* times, or " -"``NULL`` on failure. The operation is done *in-place* when *o* supports " -"it. This is the equivalent of the Python expression ``o *= count``." -msgstr "" - -#: ../../c-api/sequence.rst:55 -msgid "" -"Return the *i*\\ th element of *o*, or ``NULL`` on failure. This is the " -"equivalent of the Python expression ``o[i]``." -msgstr "" - -#: ../../c-api/sequence.rst:61 -msgid "" -"Return the slice of sequence object *o* between *i1* and *i2*, or ``NULL`` " -"on failure. This is the equivalent of the Python expression ``o[i1:i2]``." -msgstr "" - -#: ../../c-api/sequence.rst:67 -msgid "" -"Assign object *v* to the *i*\\ th element of *o*. Raise an exception and " -"return ``-1`` on failure; return ``0`` on success. This is the equivalent " -"of the Python statement ``o[i] = v``. This function *does not* steal a " -"reference to *v*." -msgstr "" - -#: ../../c-api/sequence.rst:72 -msgid "" -"If *v* is ``NULL``, the element is deleted, but this feature is deprecated " -"in favour of using :c:func:`PySequence_DelItem`." -msgstr "" - -#: ../../c-api/sequence.rst:78 -msgid "" -"Delete the *i*\\ th element of object *o*. Returns ``-1`` on failure. This " -"is the equivalent of the Python statement ``del o[i]``." -msgstr "" - -#: ../../c-api/sequence.rst:84 -msgid "" -"Assign the sequence object *v* to the slice in sequence object *o* from *i1* " -"to *i2*. This is the equivalent of the Python statement ``o[i1:i2] = v``." -msgstr "" - -#: ../../c-api/sequence.rst:90 -msgid "" -"Delete the slice in sequence object *o* from *i1* to *i2*. Returns ``-1`` " -"on failure. This is the equivalent of the Python statement ``del o[i1:i2]``." -msgstr "" - -#: ../../c-api/sequence.rst:96 -msgid "" -"Return the number of occurrences of *value* in *o*, that is, return the " -"number of keys for which ``o[key] == value``. On failure, return ``-1``. " -"This is equivalent to the Python expression ``o.count(value)``." -msgstr "" - -#: ../../c-api/sequence.rst:103 -msgid "" -"Determine if *o* contains *value*. If an item in *o* is equal to *value*, " -"return ``1``, otherwise return ``0``. On error, return ``-1``. This is " -"equivalent to the Python expression ``value in o``." -msgstr "" - -#: ../../c-api/sequence.rst:110 -msgid "Alias for :c:func:`PySequence_Contains`." -msgstr ":c:func:`PySequence_Contains` 的別名。" - -#: ../../c-api/sequence.rst:112 -msgid "" -"The function is :term:`soft deprecated` and should no longer be used to " -"write new code." -msgstr "" - -#: ../../c-api/sequence.rst:119 -msgid "" -"Return the first index *i* for which ``o[i] == value``. On error, return " -"``-1``. This is equivalent to the Python expression ``o.index(value)``." -msgstr "" - -#: ../../c-api/sequence.rst:125 -msgid "" -"Return a list object with the same contents as the sequence or iterable *o*, " -"or ``NULL`` on failure. The returned list is guaranteed to be new. This is " -"equivalent to the Python expression ``list(o)``." -msgstr "" - -#: ../../c-api/sequence.rst:134 -msgid "" -"Return a tuple object with the same contents as the sequence or iterable " -"*o*, or ``NULL`` on failure. If *o* is a tuple, a new reference will be " -"returned, otherwise a tuple will be constructed with the appropriate " -"contents. This is equivalent to the Python expression ``tuple(o)``." -msgstr "" - -#: ../../c-api/sequence.rst:142 -msgid "" -"Return the sequence or iterable *o* as an object usable by the other " -"``PySequence_Fast*`` family of functions. If the object is not a sequence or " -"iterable, raises :exc:`TypeError` with *m* as the message text. Returns " -"``NULL`` on failure." -msgstr "" - -#: ../../c-api/sequence.rst:147 -msgid "" -"The ``PySequence_Fast*`` functions are thus named because they assume *o* is " -"a :c:type:`PyTupleObject` or a :c:type:`PyListObject` and access the data " -"fields of *o* directly." -msgstr "" - -#: ../../c-api/sequence.rst:151 -msgid "" -"As a CPython implementation detail, if *o* is already a sequence or list, it " -"will be returned." -msgstr "" - -#: ../../c-api/sequence.rst:157 -msgid "" -"Returns the length of *o*, assuming that *o* was returned " -"by :c:func:`PySequence_Fast` and that *o* is not ``NULL``. The size can " -"also be retrieved by calling :c:func:`PySequence_Size` on *o*, " -"but :c:func:`PySequence_Fast_GET_SIZE` is faster because it can assume *o* " -"is a list or tuple." -msgstr "" - -#: ../../c-api/sequence.rst:166 -msgid "" -"Return the *i*\\ th element of *o*, assuming that *o* was returned " -"by :c:func:`PySequence_Fast`, *o* is not ``NULL``, and that *i* is within " -"bounds." -msgstr "" - -#: ../../c-api/sequence.rst:172 -msgid "" -"Return the underlying array of PyObject pointers. Assumes that *o* was " -"returned by :c:func:`PySequence_Fast` and *o* is not ``NULL``." -msgstr "" - -#: ../../c-api/sequence.rst:175 -msgid "" -"Note, if a list gets resized, the reallocation may relocate the items array. " -"So, only use the underlying array pointer in contexts where the sequence " -"cannot change." -msgstr "" - -#: ../../c-api/sequence.rst:182 -msgid "" -"Return the *i*\\ th element of *o* or ``NULL`` on failure. Faster form " -"of :c:func:`PySequence_GetItem` but without checking " -"that :c:func:`PySequence_Check` on *o* is true and without adjustment for " -"negative indices." -msgstr "" - -#: ../../c-api/sequence.rst:21 ../../c-api/sequence.rst:132 -msgid "built-in function" -msgstr "built-in function（內建函式）" - -#: ../../c-api/sequence.rst:21 -msgid "len" -msgstr "len" - -#: ../../c-api/sequence.rst:132 -msgid "tuple" -msgstr "tuple（元組）" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: 2018-05-23 14:32+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" + +#: ../../c-api/sequence.rst:6 +msgid "Sequence Protocol" +msgstr "序列協定" + +#: ../../c-api/sequence.rst:11 +msgid "" +"Return ``1`` if the object provides the sequence protocol, and ``0`` " +"otherwise. Note that it returns ``1`` for Python classes with " +"a :meth:`~object.__getitem__` method, unless they are :class:`dict` " +"subclasses, since in general it is impossible to determine what type of keys " +"the class supports. This function always succeeds." +msgstr "" + +#: ../../c-api/sequence.rst:23 +msgid "" +"Returns the number of objects in sequence *o* on success, and ``-1`` on " +"failure. This is equivalent to the Python expression ``len(o)``." +msgstr "" + +#: ../../c-api/sequence.rst:29 +msgid "" +"Return the concatenation of *o1* and *o2* on success, and ``NULL`` on " +"failure. This is the equivalent of the Python expression ``o1 + o2``." +msgstr "" + +#: ../../c-api/sequence.rst:35 +msgid "" +"Return the result of repeating sequence object *o* *count* times, or " +"``NULL`` on failure. This is the equivalent of the Python expression ``o * " +"count``." +msgstr "" + +#: ../../c-api/sequence.rst:41 +msgid "" +"Return the concatenation of *o1* and *o2* on success, and ``NULL`` on " +"failure. The operation is done *in-place* when *o1* supports it. This is " +"the equivalent of the Python expression ``o1 += o2``." +msgstr "" + +#: ../../c-api/sequence.rst:48 +msgid "" +"Return the result of repeating sequence object *o* *count* times, or " +"``NULL`` on failure. The operation is done *in-place* when *o* supports " +"it. This is the equivalent of the Python expression ``o *= count``." +msgstr "" + +#: ../../c-api/sequence.rst:55 +msgid "" +"Return the *i*\\ th element of *o*, or ``NULL`` on failure. This is the " +"equivalent of the Python expression ``o[i]``." +msgstr "" + +#: ../../c-api/sequence.rst:61 +msgid "" +"Return the slice of sequence object *o* between *i1* and *i2*, or ``NULL`` " +"on failure. This is the equivalent of the Python expression ``o[i1:i2]``." +msgstr "" + +#: ../../c-api/sequence.rst:67 +msgid "" +"Assign object *v* to the *i*\\ th element of *o*. Raise an exception and " +"return ``-1`` on failure; return ``0`` on success. This is the equivalent " +"of the Python statement ``o[i] = v``. This function *does not* steal a " +"reference to *v*." +msgstr "" + +#: ../../c-api/sequence.rst:72 +msgid "" +"If *v* is ``NULL``, the element is deleted, but this feature is deprecated " +"in favour of using :c:func:`PySequence_DelItem`." +msgstr "" + +#: ../../c-api/sequence.rst:78 +msgid "" +"Delete the *i*\\ th element of object *o*. Returns ``-1`` on failure. This " +"is the equivalent of the Python statement ``del o[i]``." +msgstr "" + +#: ../../c-api/sequence.rst:84 +msgid "" +"Assign the sequence object *v* to the slice in sequence object *o* from *i1* " +"to *i2*. This is the equivalent of the Python statement ``o[i1:i2] = v``." +msgstr "" + +#: ../../c-api/sequence.rst:90 +msgid "" +"Delete the slice in sequence object *o* from *i1* to *i2*. Returns ``-1`` " +"on failure. This is the equivalent of the Python statement ``del o[i1:i2]``." +msgstr "" + +#: ../../c-api/sequence.rst:96 +msgid "" +"Return the number of occurrences of *value* in *o*, that is, return the " +"number of keys for which ``o[key] == value``. On failure, return ``-1``. " +"This is equivalent to the Python expression ``o.count(value)``." +msgstr "" + +#: ../../c-api/sequence.rst:103 +msgid "" +"Determine if *o* contains *value*. If an item in *o* is equal to *value*, " +"return ``1``, otherwise return ``0``. On error, return ``-1``. This is " +"equivalent to the Python expression ``value in o``." +msgstr "" + +#: ../../c-api/sequence.rst:110 +msgid "Alias for :c:func:`PySequence_Contains`." +msgstr ":c:func:`PySequence_Contains` 的別名。" + +#: ../../c-api/sequence.rst:112 +msgid "" +"The function is :term:`soft deprecated` and should no longer be used to " +"write new code." +msgstr "" + +#: ../../c-api/sequence.rst:119 +msgid "" +"Return the first index *i* for which ``o[i] == value``. On error, return " +"``-1``. This is equivalent to the Python expression ``o.index(value)``." +msgstr "" + +#: ../../c-api/sequence.rst:125 +msgid "" +"Return a list object with the same contents as the sequence or iterable *o*, " +"or ``NULL`` on failure. The returned list is guaranteed to be new. This is " +"equivalent to the Python expression ``list(o)``." +msgstr "" + +#: ../../c-api/sequence.rst:134 +msgid "" +"Return a tuple object with the same contents as the sequence or iterable " +"*o*, or ``NULL`` on failure. If *o* is a tuple, a new reference will be " +"returned, otherwise a tuple will be constructed with the appropriate " +"contents. This is equivalent to the Python expression ``tuple(o)``." +msgstr "" + +#: ../../c-api/sequence.rst:142 +msgid "" +"Return the sequence or iterable *o* as an object usable by the other " +"``PySequence_Fast*`` family of functions. If the object is not a sequence or " +"iterable, raises :exc:`TypeError` with *m* as the message text. Returns " +"``NULL`` on failure." +msgstr "" + +#: ../../c-api/sequence.rst:147 +msgid "" +"The ``PySequence_Fast*`` functions are thus named because they assume *o* is " +"a :c:type:`PyTupleObject` or a :c:type:`PyListObject` and access the data " +"fields of *o* directly." +msgstr "" + +#: ../../c-api/sequence.rst:151 +msgid "" +"As a CPython implementation detail, if *o* is already a sequence or list, it " +"will be returned." +msgstr "" + +#: ../../c-api/sequence.rst:157 +msgid "" +"Returns the length of *o*, assuming that *o* was returned " +"by :c:func:`PySequence_Fast` and that *o* is not ``NULL``. The size can " +"also be retrieved by calling :c:func:`PySequence_Size` on *o*, " +"but :c:func:`PySequence_Fast_GET_SIZE` is faster because it can assume *o* " +"is a list or tuple." +msgstr "" + +#: ../../c-api/sequence.rst:166 +msgid "" +"Return the *i*\\ th element of *o*, assuming that *o* was returned " +"by :c:func:`PySequence_Fast`, *o* is not ``NULL``, and that *i* is within " +"bounds." +msgstr "" + +#: ../../c-api/sequence.rst:172 +msgid "" +"Return the underlying array of PyObject pointers. Assumes that *o* was " +"returned by :c:func:`PySequence_Fast` and *o* is not ``NULL``." +msgstr "" + +#: ../../c-api/sequence.rst:175 +msgid "" +"Note, if a list gets resized, the reallocation may relocate the items array. " +"So, only use the underlying array pointer in contexts where the sequence " +"cannot change." +msgstr "" + +#: ../../c-api/sequence.rst:182 +msgid "" +"Return the *i*\\ th element of *o* or ``NULL`` on failure. Faster form " +"of :c:func:`PySequence_GetItem` but without checking " +"that :c:func:`PySequence_Check` on *o* is true and without adjustment for " +"negative indices." +msgstr "" + +#: ../../c-api/sequence.rst:21 ../../c-api/sequence.rst:132 +msgid "built-in function" +msgstr "built-in function（內建函式）" + +#: ../../c-api/sequence.rst:21 +msgid "len" +msgstr "len" + +#: ../../c-api/sequence.rst:132 +msgid "tuple" +msgstr "tuple（元組）" diff --git a/c-api/set.po b/c-api/set.po index 2fbd3280b8..b975997af9 100644 --- a/c-api/set.po +++ b/c-api/set.po @@ -1,208 +1,208 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-12-08 07:22+0000\n" -"PO-Revision-Date: 2018-05-23 14: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" - -#: ../../c-api/set.rst:6 -msgid "Set Objects" -msgstr "集合物件" - -#: ../../c-api/set.rst:15 -msgid "" -"This section details the public API for :class:`set` and :class:`frozenset` " -"objects. Any functionality not listed below is best accessed using either " -"the abstract object protocol (including :c:func:`PyObject_CallMethod`, :c:" -"func:`PyObject_RichCompareBool`, :c:func:`PyObject_Hash`, :c:func:" -"`PyObject_Repr`, :c:func:`PyObject_IsTrue`, :c:func:`PyObject_Print`, and :c:" -"func:`PyObject_GetIter`) or the abstract number protocol (including :c:func:" -"`PyNumber_And`, :c:func:`PyNumber_Subtract`, :c:func:`PyNumber_Or`, :c:func:" -"`PyNumber_Xor`, :c:func:`PyNumber_InPlaceAnd`, :c:func:" -"`PyNumber_InPlaceSubtract`, :c:func:`PyNumber_InPlaceOr`, and :c:func:" -"`PyNumber_InPlaceXor`)." -msgstr "" - -#: ../../c-api/set.rst:29 -msgid "" -"This subtype of :c:type:`PyObject` is used to hold the internal data for " -"both :class:`set` and :class:`frozenset` objects. It is like a :c:type:" -"`PyDictObject` in that it is a fixed size for small sets (much like tuple " -"storage) and will point to a separate, variable sized block of memory for " -"medium and large sized sets (much like list storage). None of the fields of " -"this structure should be considered public and all are subject to change. " -"All access should be done through the documented API rather than by " -"manipulating the values in the structure." -msgstr "" - -#: ../../c-api/set.rst:40 -msgid "" -"This is an instance of :c:type:`PyTypeObject` representing the Python :class:" -"`set` type." -msgstr "" - -#: ../../c-api/set.rst:46 -msgid "" -"This is an instance of :c:type:`PyTypeObject` representing the Python :class:" -"`frozenset` type." -msgstr "" - -#: ../../c-api/set.rst:49 -msgid "" -"The following type check macros work on pointers to any Python object. " -"Likewise, the constructor functions work with any iterable Python object." -msgstr "" - -#: ../../c-api/set.rst:55 -msgid "" -"Return true if *p* is a :class:`set` object or an instance of a subtype. " -"This function always succeeds." -msgstr "" - -#: ../../c-api/set.rst:60 -msgid "" -"Return true if *p* is a :class:`frozenset` object or an instance of a " -"subtype. This function always succeeds." -msgstr "" - -#: ../../c-api/set.rst:65 -msgid "" -"Return true if *p* is a :class:`set` object, a :class:`frozenset` object, or " -"an instance of a subtype. This function always succeeds." -msgstr "" - -#: ../../c-api/set.rst:70 -msgid "" -"Return true if *p* is a :class:`set` object but not an instance of a " -"subtype. This function always succeeds." -msgstr "" - -#: ../../c-api/set.rst:77 -msgid "" -"Return true if *p* is a :class:`set` object or a :class:`frozenset` object " -"but not an instance of a subtype. This function always succeeds." -msgstr "" - -#: ../../c-api/set.rst:83 -msgid "" -"Return true if *p* is a :class:`frozenset` object but not an instance of a " -"subtype. This function always succeeds." -msgstr "" - -#: ../../c-api/set.rst:89 -msgid "" -"Return a new :class:`set` containing objects returned by the *iterable*. " -"The *iterable* may be ``NULL`` to create a new empty set. Return the new " -"set on success or ``NULL`` on failure. Raise :exc:`TypeError` if *iterable* " -"is not actually iterable. The constructor is also useful for copying a set " -"(``c=set(s)``)." -msgstr "" - -#: ../../c-api/set.rst:98 -msgid "" -"Return a new :class:`frozenset` containing objects returned by the " -"*iterable*. The *iterable* may be ``NULL`` to create a new empty frozenset. " -"Return the new set on success or ``NULL`` on failure. Raise :exc:" -"`TypeError` if *iterable* is not actually iterable." -msgstr "" - -#: ../../c-api/set.rst:104 -msgid "" -"The following functions and macros are available for instances of :class:" -"`set` or :class:`frozenset` or instances of their subtypes." -msgstr "" - -#: ../../c-api/set.rst:112 -msgid "" -"Return the length of a :class:`set` or :class:`frozenset` object. Equivalent " -"to ``len(anyset)``. Raises a :exc:`SystemError` if *anyset* is not a :class:" -"`set`, :class:`frozenset`, or an instance of a subtype." -msgstr "" - -#: ../../c-api/set.rst:119 -msgid "Macro form of :c:func:`PySet_Size` without error checking." -msgstr "" - -#: ../../c-api/set.rst:124 -msgid "" -"Return ``1`` if found, ``0`` if not found, and ``-1`` if an error is " -"encountered. Unlike the Python :meth:`~object.__contains__` method, this " -"function does not automatically convert unhashable sets into temporary " -"frozensets. Raise a :exc:`TypeError` if the *key* is unhashable. Raise :exc:" -"`SystemError` if *anyset* is not a :class:`set`, :class:`frozenset`, or an " -"instance of a subtype." -msgstr "" - -#: ../../c-api/set.rst:133 -msgid "" -"Add *key* to a :class:`set` instance. Also works with :class:`frozenset` " -"instances (like :c:func:`PyTuple_SetItem` it can be used to fill in the " -"values of brand new frozensets before they are exposed to other code). " -"Return ``0`` on success or ``-1`` on failure. Raise a :exc:`TypeError` if " -"the *key* is unhashable. Raise a :exc:`MemoryError` if there is no room to " -"grow. Raise a :exc:`SystemError` if *set* is not an instance of :class:" -"`set` or its subtype." -msgstr "" - -#: ../../c-api/set.rst:142 -msgid "" -"The following functions are available for instances of :class:`set` or its " -"subtypes but not for instances of :class:`frozenset` or its subtypes." -msgstr "" - -#: ../../c-api/set.rst:148 -msgid "" -"Return ``1`` if found and removed, ``0`` if not found (no action taken), and " -"``-1`` if an error is encountered. Does not raise :exc:`KeyError` for " -"missing keys. Raise a :exc:`TypeError` if the *key* is unhashable. Unlike " -"the Python :meth:`~set.discard` method, this function does not automatically " -"convert unhashable sets into temporary frozensets. Raise :exc:`SystemError` " -"if *set* is not an instance of :class:`set` or its subtype." -msgstr "" - -#: ../../c-api/set.rst:158 -msgid "" -"Return a new reference to an arbitrary object in the *set*, and removes the " -"object from the *set*. Return ``NULL`` on failure. Raise :exc:`KeyError` " -"if the set is empty. Raise a :exc:`SystemError` if *set* is not an instance " -"of :class:`set` or its subtype." -msgstr "" - -#: ../../c-api/set.rst:166 -msgid "" -"Empty an existing set of all elements. Return ``0`` on success. Return " -"``-1`` and raise :exc:`SystemError` if *set* is not an instance of :class:" -"`set` or its subtype." -msgstr "" - -#: ../../c-api/set.rst:11 -msgid "object" -msgstr "object（物件）" - -#: ../../c-api/set.rst:11 -msgid "set" -msgstr "set（集合）" - -#: ../../c-api/set.rst:11 -msgid "frozenset" -msgstr "frozenset（凍結集合）" - -#: ../../c-api/set.rst:110 -msgid "built-in function" -msgstr "built-in function（內建函式）" - -#: ../../c-api/set.rst:110 -msgid "len" -msgstr "len" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-12-08 07:22+0000\n" +"PO-Revision-Date: 2018-05-23 14: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" + +#: ../../c-api/set.rst:6 +msgid "Set Objects" +msgstr "集合物件" + +#: ../../c-api/set.rst:15 +msgid "" +"This section details the public API for :class:`set` and :class:`frozenset` " +"objects. Any functionality not listed below is best accessed using either " +"the abstract object protocol (including :c:func:`PyObject_CallMethod`, :c:" +"func:`PyObject_RichCompareBool`, :c:func:`PyObject_Hash`, :c:func:" +"`PyObject_Repr`, :c:func:`PyObject_IsTrue`, :c:func:`PyObject_Print`, and :c:" +"func:`PyObject_GetIter`) or the abstract number protocol (including :c:func:" +"`PyNumber_And`, :c:func:`PyNumber_Subtract`, :c:func:`PyNumber_Or`, :c:func:" +"`PyNumber_Xor`, :c:func:`PyNumber_InPlaceAnd`, :c:func:" +"`PyNumber_InPlaceSubtract`, :c:func:`PyNumber_InPlaceOr`, and :c:func:" +"`PyNumber_InPlaceXor`)." +msgstr "" + +#: ../../c-api/set.rst:29 +msgid "" +"This subtype of :c:type:`PyObject` is used to hold the internal data for " +"both :class:`set` and :class:`frozenset` objects. It is like a :c:type:" +"`PyDictObject` in that it is a fixed size for small sets (much like tuple " +"storage) and will point to a separate, variable sized block of memory for " +"medium and large sized sets (much like list storage). None of the fields of " +"this structure should be considered public and all are subject to change. " +"All access should be done through the documented API rather than by " +"manipulating the values in the structure." +msgstr "" + +#: ../../c-api/set.rst:40 +msgid "" +"This is an instance of :c:type:`PyTypeObject` representing the Python :class:" +"`set` type." +msgstr "" + +#: ../../c-api/set.rst:46 +msgid "" +"This is an instance of :c:type:`PyTypeObject` representing the Python :class:" +"`frozenset` type." +msgstr "" + +#: ../../c-api/set.rst:49 +msgid "" +"The following type check macros work on pointers to any Python object. " +"Likewise, the constructor functions work with any iterable Python object." +msgstr "" + +#: ../../c-api/set.rst:55 +msgid "" +"Return true if *p* is a :class:`set` object or an instance of a subtype. " +"This function always succeeds." +msgstr "" + +#: ../../c-api/set.rst:60 +msgid "" +"Return true if *p* is a :class:`frozenset` object or an instance of a " +"subtype. This function always succeeds." +msgstr "" + +#: ../../c-api/set.rst:65 +msgid "" +"Return true if *p* is a :class:`set` object, a :class:`frozenset` object, or " +"an instance of a subtype. This function always succeeds." +msgstr "" + +#: ../../c-api/set.rst:70 +msgid "" +"Return true if *p* is a :class:`set` object but not an instance of a " +"subtype. This function always succeeds." +msgstr "" + +#: ../../c-api/set.rst:77 +msgid "" +"Return true if *p* is a :class:`set` object or a :class:`frozenset` object " +"but not an instance of a subtype. This function always succeeds." +msgstr "" + +#: ../../c-api/set.rst:83 +msgid "" +"Return true if *p* is a :class:`frozenset` object but not an instance of a " +"subtype. This function always succeeds." +msgstr "" + +#: ../../c-api/set.rst:89 +msgid "" +"Return a new :class:`set` containing objects returned by the *iterable*. " +"The *iterable* may be ``NULL`` to create a new empty set. Return the new " +"set on success or ``NULL`` on failure. Raise :exc:`TypeError` if *iterable* " +"is not actually iterable. The constructor is also useful for copying a set " +"(``c=set(s)``)." +msgstr "" + +#: ../../c-api/set.rst:98 +msgid "" +"Return a new :class:`frozenset` containing objects returned by the " +"*iterable*. The *iterable* may be ``NULL`` to create a new empty frozenset. " +"Return the new set on success or ``NULL`` on failure. Raise :exc:" +"`TypeError` if *iterable* is not actually iterable." +msgstr "" + +#: ../../c-api/set.rst:104 +msgid "" +"The following functions and macros are available for instances of :class:" +"`set` or :class:`frozenset` or instances of their subtypes." +msgstr "" + +#: ../../c-api/set.rst:112 +msgid "" +"Return the length of a :class:`set` or :class:`frozenset` object. Equivalent " +"to ``len(anyset)``. Raises a :exc:`SystemError` if *anyset* is not a :class:" +"`set`, :class:`frozenset`, or an instance of a subtype." +msgstr "" + +#: ../../c-api/set.rst:119 +msgid "Macro form of :c:func:`PySet_Size` without error checking." +msgstr "" + +#: ../../c-api/set.rst:124 +msgid "" +"Return ``1`` if found, ``0`` if not found, and ``-1`` if an error is " +"encountered. Unlike the Python :meth:`~object.__contains__` method, this " +"function does not automatically convert unhashable sets into temporary " +"frozensets. Raise a :exc:`TypeError` if the *key* is unhashable. Raise :exc:" +"`SystemError` if *anyset* is not a :class:`set`, :class:`frozenset`, or an " +"instance of a subtype." +msgstr "" + +#: ../../c-api/set.rst:133 +msgid "" +"Add *key* to a :class:`set` instance. Also works with :class:`frozenset` " +"instances (like :c:func:`PyTuple_SetItem` it can be used to fill in the " +"values of brand new frozensets before they are exposed to other code). " +"Return ``0`` on success or ``-1`` on failure. Raise a :exc:`TypeError` if " +"the *key* is unhashable. Raise a :exc:`MemoryError` if there is no room to " +"grow. Raise a :exc:`SystemError` if *set* is not an instance of :class:" +"`set` or its subtype." +msgstr "" + +#: ../../c-api/set.rst:142 +msgid "" +"The following functions are available for instances of :class:`set` or its " +"subtypes but not for instances of :class:`frozenset` or its subtypes." +msgstr "" + +#: ../../c-api/set.rst:148 +msgid "" +"Return ``1`` if found and removed, ``0`` if not found (no action taken), and " +"``-1`` if an error is encountered. Does not raise :exc:`KeyError` for " +"missing keys. Raise a :exc:`TypeError` if the *key* is unhashable. Unlike " +"the Python :meth:`~set.discard` method, this function does not automatically " +"convert unhashable sets into temporary frozensets. Raise :exc:`SystemError` " +"if *set* is not an instance of :class:`set` or its subtype." +msgstr "" + +#: ../../c-api/set.rst:158 +msgid "" +"Return a new reference to an arbitrary object in the *set*, and removes the " +"object from the *set*. Return ``NULL`` on failure. Raise :exc:`KeyError` " +"if the set is empty. Raise a :exc:`SystemError` if *set* is not an instance " +"of :class:`set` or its subtype." +msgstr "" + +#: ../../c-api/set.rst:166 +msgid "" +"Empty an existing set of all elements. Return ``0`` on success. Return " +"``-1`` and raise :exc:`SystemError` if *set* is not an instance of :class:" +"`set` or its subtype." +msgstr "" + +#: ../../c-api/set.rst:11 +msgid "object" +msgstr "object（物件）" + +#: ../../c-api/set.rst:11 +msgid "set" +msgstr "set（集合）" + +#: ../../c-api/set.rst:11 +msgid "frozenset" +msgstr "frozenset（凍結集合）" + +#: ../../c-api/set.rst:110 +msgid "built-in function" +msgstr "built-in function（內建函式）" + +#: ../../c-api/set.rst:110 +msgid "len" +msgstr "len" diff --git a/c-api/slice.po b/c-api/slice.po index 7cbae1a4ee..e071c2ffcb 100644 --- a/c-api/slice.po +++ b/c-api/slice.po @@ -1,215 +1,215 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Leon H., 2017 -# Weilin Du, 2025 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-02-18 00:13+0000\n" -"PO-Revision-Date: 2025-10-08 21:36+0800\n" -"Last-Translator: Weilin Du <1372449351@qq.com>\n" -"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" -"tw)\n" -"Language: zh_TW\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=UTF-8\n" -"Content-Transfer-Encoding: 8bit\n" -"Plural-Forms: nplurals=1; plural=0;\n" -"X-Generator: Poedit 3.6\n" - -#: ../../c-api/slice.rst:6 -msgid "Slice Objects" -msgstr "切片物件" - -#: ../../c-api/slice.rst:11 -msgid "" -"The type object for slice objects. This is the same as :class:`slice` in " -"the Python layer." -msgstr "slice 物件的型別物件。這與 Python 層中的 :class:`slice` 相同。" - -#: ../../c-api/slice.rst:17 -msgid "" -"Return true if *ob* is a slice object; *ob* must not be ``NULL``. This " -"function always succeeds." -msgstr "" -"如果 *ob* 是 slice 物件，則回傳 true；*ob* 不能是 ``NULL`` 。此函式永遠成功。" - -#: ../../c-api/slice.rst:23 -msgid "" -"Return a new slice object with the given values. The *start*, *stop*, and " -"*step* parameters are used as the values of the slice object attributes of " -"the same names. Any of the values may be ``NULL``, in which case the " -"``None`` will be used for the corresponding attribute." -msgstr "" -"以指定的值回傳一個新的切片物件。*start*、*stop* 及 *step* 參數會被用為同名的 " -"slice 物件屬性值。任何值都可能是 ``NULL``，在這種情況下，``None`` 將用於相對" -"應的屬性。" - -#: ../../c-api/slice.rst:28 -msgid "" -"Return ``NULL`` with an exception set if the new object could not be " -"allocated." -msgstr "如果無法分配新物件，則回傳 ``NULL`` 並設定例外。" - -#: ../../c-api/slice.rst:34 -msgid "" -"Retrieve the start, stop and step indices from the slice object *slice*, " -"assuming a sequence of length *length*. Treats indices greater than *length* " -"as errors." -msgstr "" -"從 slice 物件 *slice* 讀取開始、停止和步進索引，假設序列長度為 *length*。將大" -"於 *length* 的索引視為錯誤。" - -#: ../../c-api/slice.rst:38 -msgid "" -"Returns ``0`` on success and ``-1`` on error with no exception set (unless " -"one of the indices was not ``None`` and failed to be converted to an " -"integer, in which case ``-1`` is returned with an exception set)." -msgstr "" -"成功時回傳 ``0``，錯誤時回傳 ``-1``，並無例外設定（除非其中一個索引不是 " -"``None`` 並且未能轉換成整數，在這種情況下會回傳 ``-1`` ，並有設定例外）。" - -#: ../../c-api/slice.rst:42 -msgid "You probably do not want to use this function." -msgstr "你可能不想使用此功能。" - -#: ../../c-api/slice.rst:44 ../../c-api/slice.rst:75 -msgid "" -"The parameter type for the *slice* parameter was ``PySliceObject*`` before." -msgstr "之前 *slice* 的參數型別是 ``PySliceObject*`` 。" - -#: ../../c-api/slice.rst:51 -msgid "" -"Usable replacement for :c:func:`PySlice_GetIndices`. Retrieve the start, " -"stop, and step indices from the slice object *slice* assuming a sequence of " -"length *length*, and store the length of the slice in *slicelength*. Out of " -"bounds indices are clipped in a manner consistent with the handling of " -"normal slices." -msgstr "" -"可用來取代 :c:func:`PySlice_GetIndices`。從假設序列長度為 *length* 的 slice " -"物件 *slice* 擷取開始、停止和步長索引，並將 slice 的長度存入 *slicelength*。" -"超出範圍的索引會被剪切，剪切方式與一般切片的處理方式一致。" - -#: ../../c-api/slice.rst:57 -msgid "Return ``0`` on success and ``-1`` on error with an exception set." -msgstr "成功時回傳 ``0`` ，在失敗時回傳 ``-1`` 並設定例外。" - -#: ../../c-api/slice.rst:60 -msgid "" -"This function is considered not safe for resizable sequences. Its invocation " -"should be replaced by a combination of :c:func:`PySlice_Unpack` " -"and :c:func:`PySlice_AdjustIndices` where ::" -msgstr "" -"這個函式對於可調整大小的序列並不安全。它的呼叫應該" -"被 :c:func:`PySlice_Unpack` 和 :c:func:`PySlice_AdjustIndices` 的組合取代，其" -"中： ::" - -#: ../../c-api/slice.rst:64 -msgid "" -"if (PySlice_GetIndicesEx(slice, length, &start, &stop, &step, &slicelength) " -"< 0) {\n" -" // return error\n" -"}" -msgstr "" -"if (PySlice_GetIndicesEx(slice, length, &start, &stop, &step, &slicelength) " -"< 0) {\n" -" // return error\n" -"}" - -#: ../../c-api/slice.rst:68 -msgid "is replaced by ::" -msgstr "被更換為： ::" - -#: ../../c-api/slice.rst:70 -msgid "" -"if (PySlice_Unpack(slice, &start, &stop, &step) < 0) {\n" -" // return error\n" -"}\n" -"slicelength = PySlice_AdjustIndices(length, &start, &stop, step);" -msgstr "" -"if (PySlice_Unpack(slice, &start, &stop, &step) < 0) {\n" -" // return error\n" -"}\n" -"slicelength = PySlice_AdjustIndices(length, &start, &stop, step);" - -#: ../../c-api/slice.rst:79 -msgid "" -"If ``Py_LIMITED_API`` is not set or set to the value between ``0x03050400`` " -"and ``0x03060000`` (not including) or ``0x03060100`` or higher :c:func:`!" -"PySlice_GetIndicesEx` is implemented as a macro using :c:func:`!" -"PySlice_Unpack` and :c:func:`!PySlice_AdjustIndices`. Arguments *start*, " -"*stop* and *step* are evaluated more than once." -msgstr "" -"如果 ``Py_LIMITED_API`` 沒有設定或設定為 ``0x03050400`` 和 ``0x03060000`` (不" -"包括) 或 ``0x03060100`` 或更高的值 :c:func:`!PySlice_GetIndicesEx` 是使" -"用 :c:func:`!PySlice_Unpack` 和 :c:func:`!PySlice_AdjustIndices` 來實作一個巨集" -"。引數 *start*、*stop* 和 *step* 會被計算多次。" - -#: ../../c-api/slice.rst:86 -msgid "" -"If ``Py_LIMITED_API`` is set to the value less than ``0x03050400`` or " -"between ``0x03060000`` and ``0x03060100`` (not including) :c:func:`!" -"PySlice_GetIndicesEx` is a deprecated function." -msgstr "" -"如果 ``Py_LIMITED_API`` 設定為小於 ``0x03050400`` 或介於 ``0x03060000`` 和 " -"``0x03060100`` 之間 (不包括邊界值) :c:func:`!PySlice_GetIndicesEx` 是一個" -"已廢棄的函式。" - -#: ../../c-api/slice.rst:94 -msgid "" -"Extract the start, stop and step data members from a slice object as C " -"integers. Silently reduce values larger than ``PY_SSIZE_T_MAX`` to " -"``PY_SSIZE_T_MAX``, silently boost the start and stop values less than " -"``PY_SSIZE_T_MIN`` to ``PY_SSIZE_T_MIN``, and silently boost the step values " -"less than ``-PY_SSIZE_T_MAX`` to ``-PY_SSIZE_T_MAX``." -msgstr "" -"以 C 整數的形式從 slice 物件中抽取 start、stop 及 step 資料成員。將大於 " -"``PY_SSIZE_T_MAX`` 的值靜默減少為 ``PY_SSIZE_T_MAX``，將小於 ``PY_SSIZE_T_MIN`` " -"的 start 和 stop 值靜默提升為 ``PY_SSIZE_T_MIN``，將小於 ``-PY_SSIZE_T_MAX`` " -"的 step 值靜默提升為 ``-PY_SSIZE_T_MAX``。" - -#: ../../c-api/slice.rst:100 -msgid "Return ``-1`` with an exception set on error, ``0`` on success." -msgstr "成功時回傳 ``0``，在失敗時回傳 ``-1`` 並設定例外。" - -#: ../../c-api/slice.rst:107 -msgid "" -"Adjust start/end slice indices assuming a sequence of the specified length. " -"Out of bounds indices are clipped in a manner consistent with the handling " -"of normal slices." -msgstr "" -"假設序列長度為指定長度，調整開始/結束切片索引。超出範圍的索引會以與處理正常切" -"片一致的方式切除。" - -#: ../../c-api/slice.rst:111 -msgid "" -"Return the length of the slice. Always successful. Doesn't call Python " -"code." -msgstr "回傳切片的長度。永遠成功。不呼叫 Python 程式碼。" - -#: ../../c-api/slice.rst:118 -msgid "Ellipsis Object" -msgstr "Ellipsis 物件" - -#: ../../c-api/slice.rst:123 -msgid "" -"The type of Python :const:`Ellipsis` object. Same " -"as :class:`types.EllipsisType` in the Python layer." -msgstr "" -"Python :const:`Ellipsis` 物件的型別。與 Python 層中" -"的 :class:`types.EllipsisType` 相同。" - -#: ../../c-api/slice.rst:129 -msgid "" -"The Python ``Ellipsis`` object. This object has no methods. " -"Like :c:data:`Py_None`, it is an :term:`immortal` singleton object." -msgstr "" -"Python ``Ellipsis`` 物件。這個物件沒有方法。就像 :c:data:`Py_None` 一樣，它是" -"一個 :term:`immortal` 單一物件。" - -#: ../../c-api/slice.rst:132 -msgid ":c:data:`Py_Ellipsis` is immortal." -msgstr ":c:data:`Py_Ellipsis` 為不滅的 (immortal)。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Leon H., 2017 +# Weilin Du, 2025 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-02-18 00:13+0000\n" +"PO-Revision-Date: 2025-10-08 21:36+0800\n" +"Last-Translator: Weilin Du <1372449351@qq.com>\n" +"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" +"tw)\n" +"Language: zh_TW\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=1; plural=0;\n" +"X-Generator: Poedit 3.6\n" + +#: ../../c-api/slice.rst:6 +msgid "Slice Objects" +msgstr "切片物件" + +#: ../../c-api/slice.rst:11 +msgid "" +"The type object for slice objects. This is the same as :class:`slice` in " +"the Python layer." +msgstr "slice 物件的型別物件。這與 Python 層中的 :class:`slice` 相同。" + +#: ../../c-api/slice.rst:17 +msgid "" +"Return true if *ob* is a slice object; *ob* must not be ``NULL``. This " +"function always succeeds." +msgstr "" +"如果 *ob* 是 slice 物件，則回傳 true；*ob* 不能是 ``NULL`` 。此函式永遠成功。" + +#: ../../c-api/slice.rst:23 +msgid "" +"Return a new slice object with the given values. The *start*, *stop*, and " +"*step* parameters are used as the values of the slice object attributes of " +"the same names. Any of the values may be ``NULL``, in which case the " +"``None`` will be used for the corresponding attribute." +msgstr "" +"以指定的值回傳一個新的切片物件。*start*、*stop* 及 *step* 參數會被用為同名的 " +"slice 物件屬性值。任何值都可能是 ``NULL``，在這種情況下，``None`` 將用於相對" +"應的屬性。" + +#: ../../c-api/slice.rst:28 +msgid "" +"Return ``NULL`` with an exception set if the new object could not be " +"allocated." +msgstr "如果無法分配新物件，則回傳 ``NULL`` 並設定例外。" + +#: ../../c-api/slice.rst:34 +msgid "" +"Retrieve the start, stop and step indices from the slice object *slice*, " +"assuming a sequence of length *length*. Treats indices greater than *length* " +"as errors." +msgstr "" +"從 slice 物件 *slice* 讀取開始、停止和步進索引，假設序列長度為 *length*。將大" +"於 *length* 的索引視為錯誤。" + +#: ../../c-api/slice.rst:38 +msgid "" +"Returns ``0`` on success and ``-1`` on error with no exception set (unless " +"one of the indices was not ``None`` and failed to be converted to an " +"integer, in which case ``-1`` is returned with an exception set)." +msgstr "" +"成功時回傳 ``0``，錯誤時回傳 ``-1``，並無例外設定（除非其中一個索引不是 " +"``None`` 並且未能轉換成整數，在這種情況下會回傳 ``-1`` ，並有設定例外）。" + +#: ../../c-api/slice.rst:42 +msgid "You probably do not want to use this function." +msgstr "你可能不想使用此功能。" + +#: ../../c-api/slice.rst:44 ../../c-api/slice.rst:75 +msgid "" +"The parameter type for the *slice* parameter was ``PySliceObject*`` before." +msgstr "之前 *slice* 的參數型別是 ``PySliceObject*`` 。" + +#: ../../c-api/slice.rst:51 +msgid "" +"Usable replacement for :c:func:`PySlice_GetIndices`. Retrieve the start, " +"stop, and step indices from the slice object *slice* assuming a sequence of " +"length *length*, and store the length of the slice in *slicelength*. Out of " +"bounds indices are clipped in a manner consistent with the handling of " +"normal slices." +msgstr "" +"可用來取代 :c:func:`PySlice_GetIndices`。從假設序列長度為 *length* 的 slice " +"物件 *slice* 擷取開始、停止和步長索引，並將 slice 的長度存入 *slicelength*。" +"超出範圍的索引會被剪切，剪切方式與一般切片的處理方式一致。" + +#: ../../c-api/slice.rst:57 +msgid "Return ``0`` on success and ``-1`` on error with an exception set." +msgstr "成功時回傳 ``0`` ，在失敗時回傳 ``-1`` 並設定例外。" + +#: ../../c-api/slice.rst:60 +msgid "" +"This function is considered not safe for resizable sequences. Its invocation " +"should be replaced by a combination of :c:func:`PySlice_Unpack` " +"and :c:func:`PySlice_AdjustIndices` where ::" +msgstr "" +"這個函式對於可調整大小的序列並不安全。它的呼叫應該" +"被 :c:func:`PySlice_Unpack` 和 :c:func:`PySlice_AdjustIndices` 的組合取代，其" +"中： ::" + +#: ../../c-api/slice.rst:64 +msgid "" +"if (PySlice_GetIndicesEx(slice, length, &start, &stop, &step, &slicelength) " +"< 0) {\n" +" // return error\n" +"}" +msgstr "" +"if (PySlice_GetIndicesEx(slice, length, &start, &stop, &step, &slicelength) " +"< 0) {\n" +" // return error\n" +"}" + +#: ../../c-api/slice.rst:68 +msgid "is replaced by ::" +msgstr "被更換為： ::" + +#: ../../c-api/slice.rst:70 +msgid "" +"if (PySlice_Unpack(slice, &start, &stop, &step) < 0) {\n" +" // return error\n" +"}\n" +"slicelength = PySlice_AdjustIndices(length, &start, &stop, step);" +msgstr "" +"if (PySlice_Unpack(slice, &start, &stop, &step) < 0) {\n" +" // return error\n" +"}\n" +"slicelength = PySlice_AdjustIndices(length, &start, &stop, step);" + +#: ../../c-api/slice.rst:79 +msgid "" +"If ``Py_LIMITED_API`` is not set or set to the value between ``0x03050400`` " +"and ``0x03060000`` (not including) or ``0x03060100`` or higher :c:func:`!" +"PySlice_GetIndicesEx` is implemented as a macro using :c:func:`!" +"PySlice_Unpack` and :c:func:`!PySlice_AdjustIndices`. Arguments *start*, " +"*stop* and *step* are evaluated more than once." +msgstr "" +"如果 ``Py_LIMITED_API`` 沒有設定或設定為 ``0x03050400`` 和 ``0x03060000`` (不" +"包括) 或 ``0x03060100`` 或更高的值 :c:func:`!PySlice_GetIndicesEx` 是使" +"用 :c:func:`!PySlice_Unpack` 和 :c:func:`!PySlice_AdjustIndices` 來實作一個巨集" +"。引數 *start*、*stop* 和 *step* 會被計算多次。" + +#: ../../c-api/slice.rst:86 +msgid "" +"If ``Py_LIMITED_API`` is set to the value less than ``0x03050400`` or " +"between ``0x03060000`` and ``0x03060100`` (not including) :c:func:`!" +"PySlice_GetIndicesEx` is a deprecated function." +msgstr "" +"如果 ``Py_LIMITED_API`` 設定為小於 ``0x03050400`` 或介於 ``0x03060000`` 和 " +"``0x03060100`` 之間 (不包括邊界值) :c:func:`!PySlice_GetIndicesEx` 是一個" +"已廢棄的函式。" + +#: ../../c-api/slice.rst:94 +msgid "" +"Extract the start, stop and step data members from a slice object as C " +"integers. Silently reduce values larger than ``PY_SSIZE_T_MAX`` to " +"``PY_SSIZE_T_MAX``, silently boost the start and stop values less than " +"``PY_SSIZE_T_MIN`` to ``PY_SSIZE_T_MIN``, and silently boost the step values " +"less than ``-PY_SSIZE_T_MAX`` to ``-PY_SSIZE_T_MAX``." +msgstr "" +"以 C 整數的形式從 slice 物件中抽取 start、stop 及 step 資料成員。將大於 " +"``PY_SSIZE_T_MAX`` 的值靜默減少為 ``PY_SSIZE_T_MAX``，將小於 ``PY_SSIZE_T_MIN`` " +"的 start 和 stop 值靜默提升為 ``PY_SSIZE_T_MIN``，將小於 ``-PY_SSIZE_T_MAX`` " +"的 step 值靜默提升為 ``-PY_SSIZE_T_MAX``。" + +#: ../../c-api/slice.rst:100 +msgid "Return ``-1`` with an exception set on error, ``0`` on success." +msgstr "成功時回傳 ``0``，在失敗時回傳 ``-1`` 並設定例外。" + +#: ../../c-api/slice.rst:107 +msgid "" +"Adjust start/end slice indices assuming a sequence of the specified length. " +"Out of bounds indices are clipped in a manner consistent with the handling " +"of normal slices." +msgstr "" +"假設序列長度為指定長度，調整開始/結束切片索引。超出範圍的索引會以與處理正常切" +"片一致的方式切除。" + +#: ../../c-api/slice.rst:111 +msgid "" +"Return the length of the slice. Always successful. Doesn't call Python " +"code." +msgstr "回傳切片的長度。永遠成功。不呼叫 Python 程式碼。" + +#: ../../c-api/slice.rst:118 +msgid "Ellipsis Object" +msgstr "Ellipsis 物件" + +#: ../../c-api/slice.rst:123 +msgid "" +"The type of Python :const:`Ellipsis` object. Same " +"as :class:`types.EllipsisType` in the Python layer." +msgstr "" +"Python :const:`Ellipsis` 物件的型別。與 Python 層中" +"的 :class:`types.EllipsisType` 相同。" + +#: ../../c-api/slice.rst:129 +msgid "" +"The Python ``Ellipsis`` object. This object has no methods. " +"Like :c:data:`Py_None`, it is an :term:`immortal` singleton object." +msgstr "" +"Python ``Ellipsis`` 物件。這個物件沒有方法。就像 :c:data:`Py_None` 一樣，它是" +"一個 :term:`immortal` 單一物件。" + +#: ../../c-api/slice.rst:132 +msgid ":c:data:`Py_Ellipsis` is immortal." +msgstr ":c:data:`Py_Ellipsis` 為不滅的 (immortal)。" diff --git a/c-api/stable.po b/c-api/stable.po index 805c537ea6..a107b5f20a 100644 --- a/c-api/stable.po +++ b/c-api/stable.po @@ -1,399 +1,399 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Matt Wang , 2023 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: 2023-01-24 21:07+0800\n" -"Last-Translator: Matt Wang \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" -"X-Generator: Poedit 3.2.2\n" - -#: ../../c-api/stable.rst:7 -msgid "C API Stability" -msgstr "C API 穩定性" - -#: ../../c-api/stable.rst:9 -msgid "" -"Unless documented otherwise, Python's C API is covered by the Backwards " -"Compatibility Policy, :pep:`387`. Most changes to it are source-compatible " -"(typically by only adding new API). Changing existing API or removing API is " -"only done after a deprecation period or to fix serious issues." -msgstr "" -"除非有另外記錄於文件，Python 的 C API 被包含在向後相容性策略 :pep:`387` 中。" -"大多數改動都是相容於原始碼的（通常只會增加新的 API）。更改現有 API 或刪除 " -"API 僅在棄用期後或修復嚴重問題時進行。" - -#: ../../c-api/stable.rst:15 -msgid "" -"CPython's Application Binary Interface (ABI) is forward- and backwards-" -"compatible across a minor release (if these are compiled the same way; " -"see :ref:`stable-abi-platform` below). So, code compiled for Python 3.10.0 " -"will work on 3.10.8 and vice versa, but will need to be compiled separately " -"for 3.9.x and 3.11.x." -msgstr "" -"CPython 的應用程式二進位介面 (Application Binary Interface, ABI) 在次要版本中" -"是向前和向後相容的（如果它們以相同的方式編譯；請參閱下面的\\ :ref:`stable-" -"abi-platform`\\）。因此，為 Python 3.10.0 編譯的程式碼將能夠在 3.10.8 上運" -"行，反之亦然，但 3.9.x 和 3.11.x 就需要分別編譯。" - -#: ../../c-api/stable.rst:21 -msgid "There are two tiers of C API with different stability expectations:" -msgstr "C API 有兩層級，有不同的穩定性期望：" - -#: ../../c-api/stable.rst:23 -msgid "" -":ref:`Unstable API `, may change in minor versions without a " -"deprecation period. It is marked by the ``PyUnstable`` prefix in names." -msgstr "" -":ref:`不穩定 API `，可能會在次要版本中發生變化，而沒有棄用階" -"段。會在名稱中以 ``PyUnstable`` 前綴來標記。" - -#: ../../c-api/stable.rst:25 -msgid "" -":ref:`Limited API `, is compatible across several minor " -"releases. When :c:macro:`Py_LIMITED_API` is defined, only this subset is " -"exposed from ``Python.h``." -msgstr "" -":ref:`受限 API `，在多個次要版本之間相容。當有定" -"義 :c:macro:`Py_LIMITED_API` 時，只有這個子集會從 ``Python.h`` 公開。" - -#: ../../c-api/stable.rst:29 -msgid "These are discussed in more detail below." -msgstr "下面將更詳細地討論這些內容。" - -#: ../../c-api/stable.rst:31 -msgid "" -"Names prefixed by an underscore, such as ``_Py_InternalState``, are private " -"API that can change without notice even in patch releases. If you need to " -"use this API, consider reaching out to `CPython developers `_ to discuss adding public API for " -"your use case." -msgstr "" -"帶有底線前綴的名稱是私有 API (private API)，像是 ``_Py_InternalState``，即使" -"在補丁版本 (patch release) 中也可能被更改，不會另行通知。如果你需要使用這個 " -"API，可以聯繫 `CPython 開發者 `_ 並針對你的使用方法來討論是否新增公開的 API。" - -#: ../../c-api/stable.rst:40 -msgid "Unstable C API" -msgstr "不穩定的 C API" - -#: ../../c-api/stable.rst:44 -msgid "" -"Any API named with the ``PyUnstable`` prefix exposes CPython implementation " -"details, and may change in every minor release (e.g. from 3.9 to 3.10) " -"without any deprecation warnings. However, it will not change in a bugfix " -"release (e.g. from 3.10.0 to 3.10.1)." -msgstr "" -"任何以 ``PyUnstable`` 前綴命名的 API 都會公開 CPython 實作細節，並可能在每個" -"次要版本中進行更改（例如從 3.9 到 3.10），而不會出現任何棄用警告。但是它不會" -"在錯誤修復發布版本中發生變化（例如從 3.10.0 到 3.10.1）。" - -#: ../../c-api/stable.rst:49 -msgid "" -"It is generally intended for specialized, low-level tools like debuggers." -msgstr "它通常用於專門的低階工具，例如偵錯器。" - -#: ../../c-api/stable.rst:51 -msgid "" -"Projects that use this API are expected to follow CPython development and " -"spend extra effort adjusting to changes." -msgstr "" -"使用此 API 的專案應該要遵循 CPython 開發細節，並花費額外的力氣來針對這些變動" -"來做調整。" - -#: ../../c-api/stable.rst:57 -msgid "Stable Application Binary Interface" -msgstr "穩定的應用程式二進位介面" - -#: ../../c-api/stable.rst:59 -msgid "" -"For simplicity, this document talks about *extensions*, but the Limited API " -"and Stable ABI work the same way for all uses of the API – for example, " -"embedding Python." -msgstr "" -"為簡單起見，本文件討論\\ *擴充 (extension)*，但受限 API 和穩定 ABI 在所有 " -"API 使用方式中都以相同的方式運作 -- 例如在嵌入式 Python (embedding Python) " -"中。" - -#: ../../c-api/stable.rst:66 -msgid "Limited C API" -msgstr "受限 C API" - -#: ../../c-api/stable.rst:68 -msgid "" -"Python 3.2 introduced the *Limited API*, a subset of Python's C API. " -"Extensions that only use the Limited API can be compiled once and be loaded " -"on multiple versions of Python. Contents of the Limited API are :ref:`listed " -"below `." -msgstr "" -"Python 3.2 引入了\\ *受限 API (Limited API)*，它是 Python C API 的一個子集。" -"僅使用受限 API 的擴充可以只編譯一次就被載入於多個版本的 Python。受限 API 的內" -"容\\ :ref:`列在下方 `。" - -#: ../../c-api/stable.rst:75 -msgid "" -"Define this macro before including ``Python.h`` to opt in to only use the " -"Limited API, and to select the Limited API version." -msgstr "" -"在包含 ``Python.h`` 之前定義此巨集以選擇只使用受限 API，並挑選受限 API 版本。" - -#: ../../c-api/stable.rst:78 -msgid "" -"Define ``Py_LIMITED_API`` to the value of :c:macro:`PY_VERSION_HEX` " -"corresponding to the lowest Python version your extension supports. The " -"extension will be ABI-compatible with all Python 3 releases from the " -"specified one onward, and can use Limited API introduced up to that version." -msgstr "" -"將 ``Py_LIMITED_API`` 定義為對應於你的擴充有支援的最低 Python 版本" -"的 :c:macro:`PY_VERSION_HEX` 值。該擴充與從指定版本開始的所有 Python 3 版本" -"之 ABI 相容，並且可以使用過去版本有引入的受限 API。" - -#: ../../c-api/stable.rst:84 -msgid "" -"Rather than using the ``PY_VERSION_HEX`` macro directly, hardcode a minimum " -"minor version (e.g. ``0x030A0000`` for Python 3.10) for stability when " -"compiling with future Python versions." -msgstr "" -"與其直接使用 ``PY_VERSION_HEX`` 巨集，不如寫死 (hardcode) 最小次要版本（例如" -"代表 Python 3.10 的 ``0x030A0000``\\ ），以便在使用未來的 Python 版本進行編譯" -"時仍保持穩定性。" - -#: ../../c-api/stable.rst:88 -msgid "" -"You can also define ``Py_LIMITED_API`` to ``3``. This works the same as " -"``0x03020000`` (Python 3.2, the version that introduced Limited API)." -msgstr "" -"你還可以將 ``Py_LIMITED_API`` 定義為 ``3``，這與 ``0x03020000``\\ （Python " -"3.2，引入了受限 API 的版本）相同。" - -#: ../../c-api/stable.rst:95 -msgid "Stable ABI" -msgstr "穩定 ABI" - -#: ../../c-api/stable.rst:97 -msgid "" -"To enable this, Python provides a *Stable ABI*: a set of symbols that will " -"remain ABI-compatible across Python 3.x versions." -msgstr "" -"為了實現它，Python 提供了一個\\ *穩定 ABI (Stable ABI)*：一組將在各個 Python " -"3.x 版本之間保持 ABI 相容的符號。" - -#: ../../c-api/stable.rst:102 -msgid "" -"The Stable ABI prevents ABI issues, like linker errors due to missing " -"symbols or data corruption due to changes in structure layouts or function " -"signatures. However, other changes in Python can change the *behavior* of " -"extensions. See Python's Backwards Compatibility Policy (:pep:`387`) for " -"details." -msgstr "" -"穩定 ABI 可以防止 ABI 問題，例如由於結構布局或函式簽名變化導致缺少符號或數據" -"損壞的鏈接器 (linker) 錯誤。然而，Python 的其他變化可能會改變 *行為* 的擴充。" -"有關詳細資訊，請參閱 Python 的向後相容性政策 (:pep:`387`)。" - -#: ../../c-api/stable.rst:108 -msgid "" -"The Stable ABI contains symbols exposed in the :ref:`Limited API `, but also other ones – for example, functions necessary to support " -"older versions of the Limited API." -msgstr "" -"穩定 ABI 被包含在\\ :ref:`受限 API ` 中開放的符號，但也包含其" -"他符號 - 例如，支援舊版受限 API 所必需的函式。" - -#: ../../c-api/stable.rst:112 -msgid "" -"On Windows, extensions that use the Stable ABI should be linked against " -"``python3.dll`` rather than a version-specific library such as " -"``python39.dll``." -msgstr "" -"在 Windows 上，使用穩定 ABI 的擴充應該連接到 ``python3.dll`` 而不是特定版本的" -"函式庫，例如 ``python39.dll``。" - -#: ../../c-api/stable.rst:116 -msgid "" -"On some platforms, Python will look for and load shared library files named " -"with the ``abi3`` tag (e.g. ``mymodule.abi3.so``). It does not check if such " -"extensions conform to a Stable ABI. The user (or their packaging tools) need " -"to ensure that, for example, extensions built with the 3.10+ Limited API are " -"not installed for lower versions of Python." -msgstr "" -"在某些平台上，Python 將查找並加載以 ``abi3`` 標籤命名的共享函式庫檔案（例如 " -"``mymodule.abi3.so``\\ ）。它不檢查此類擴充是否符合穩定的 ABI。確保的責任在使" -"用者（或者打包工具）身上，例如使用 3.10+ 受限 API 建置的擴充不會為較低版本的 " -"Python 所安裝。" - -#: ../../c-api/stable.rst:123 -msgid "" -"All functions in the Stable ABI are present as functions in Python's shared " -"library, not solely as macros. This makes them usable from languages that " -"don't use the C preprocessor." -msgstr "" -"穩定 ABI 中的所有函式都作為函式存在於 Python 的共享函式庫中，而不僅是作為巨" -"集。這使得它們可被用於不使用 C 預處理器 (preprocessor) 的語言。" - -#: ../../c-api/stable.rst:129 -msgid "Limited API Scope and Performance" -msgstr "受限 API 範圍和性能" - -#: ../../c-api/stable.rst:131 -msgid "" -"The goal for the Limited API is to allow everything that is possible with " -"the full C API, but possibly with a performance penalty." -msgstr "" -"受限 API 的目標是允許使用完整的 C API 進行所有可能的操作，但可能會降低性能。" - -#: ../../c-api/stable.rst:134 -msgid "" -"For example, while :c:func:`PyList_GetItem` is available, its “unsafe” macro " -"variant :c:func:`PyList_GET_ITEM` is not. The macro can be faster because it " -"can rely on version-specific implementation details of the list object." -msgstr "" -"例如，雖然 :c:func:`PyList_GetItem` 可用，但它的「不安全」巨集變" -"體 :c:func:`PyList_GET_ITEM` 為不可用。巨集運行可以更快，因為它可以依賴 list " -"物件的特定版本實作細節。" - -#: ../../c-api/stable.rst:139 -msgid "" -"Without ``Py_LIMITED_API`` defined, some C API functions are inlined or " -"replaced by macros. Defining ``Py_LIMITED_API`` disables this inlining, " -"allowing stability as Python's data structures are improved, but possibly " -"reducing performance." -msgstr "" -"如果沒有定義 ``Py_LIMITED_API``，一些 C API 函式將被嵌入或被替換為巨集。定義 " -"``Py_LIMITED_API`` 會禁用嵌入，從而隨著 Python 資料結構的改進而提高穩定性，但" -"可能會降低性能。" - -#: ../../c-api/stable.rst:144 -msgid "" -"By leaving out the ``Py_LIMITED_API`` definition, it is possible to compile " -"a Limited API extension with a version-specific ABI. This can improve " -"performance for that Python version, but will limit compatibility. Compiling " -"with ``Py_LIMITED_API`` will then yield an extension that can be distributed " -"where a version-specific one is not available – for example, for prereleases " -"of an upcoming Python version." -msgstr "" -"透過省略 ``Py_LIMITED_API`` 定義，可以使用特定版本的 ABI 編譯受限 API 擴充。" -"這可以提高該 Python 版本的性能，但會限制相容性。使用 ``Py_LIMITED_API`` 編譯" -"將產生一個擴充，可以在特定版本的擴充不可用的地方發布 — 例如，用於即將發布的 " -"Python 版本的預發布版本 (prerelease)。" - -#: ../../c-api/stable.rst:153 -msgid "Limited API Caveats" -msgstr "受限 API 注意事項" - -#: ../../c-api/stable.rst:155 -msgid "" -"Note that compiling with ``Py_LIMITED_API`` is *not* a complete guarantee " -"that code conforms to the :ref:`Limited API ` or " -"the :ref:`Stable ABI `. ``Py_LIMITED_API`` only covers " -"definitions, but an API also includes other issues, such as expected " -"semantics." -msgstr "" -"請注意，使用 ``Py_LIMITED_API`` 進行編譯\\ *不*\\ 完全保證程式碼符合\\ :ref:`" -"受限 API ` 或\\ :ref:`穩定 ABI `。" -"``Py_LIMITED_API`` 僅涵蓋定義，但 API 還包括其他議題，例如預期的語義 " -"(semantic)。" - -#: ../../c-api/stable.rst:160 -msgid "" -"One issue that ``Py_LIMITED_API`` does not guard against is calling a " -"function with arguments that are invalid in a lower Python version. For " -"example, consider a function that starts accepting ``NULL`` for an argument. " -"In Python 3.9, ``NULL`` now selects a default behavior, but in Python 3.8, " -"the argument will be used directly, causing a ``NULL`` dereference and " -"crash. A similar argument works for fields of structs." -msgstr "" -"``Py_LIMITED_API`` 無法防範的一個問題是使用在較低 Python 版本中無效的引數來呼" -"叫函式。例如一個開始接受 ``NULL`` 作為引數的函式。在 Python 3.9 中，``NULL`` " -"現在代表選擇預設行為，但在 Python 3.8 中，引數將被直接使用，導致 ``NULL`` 取" -"消參照 (dereference) 且崩潰 (crash)。類似的引數適用於結構 (struct) 的欄位。" - -#: ../../c-api/stable.rst:167 -msgid "" -"Another issue is that some struct fields are currently not hidden when " -"``Py_LIMITED_API`` is defined, even though they're part of the Limited API." -msgstr "" -"另一個問題是，當有定義 ``Py_LIMITED_API`` 時，一些結構欄位目前不會被隱藏，即" -"使它們是受限 API 的一部分。" - -#: ../../c-api/stable.rst:170 -msgid "" -"For these reasons, we recommend testing an extension with *all* minor Python " -"versions it supports, and preferably to build with the *lowest* such version." -msgstr "" -"出於這些原因，我們建議要以它支援的\\ *所有*\\ 次要 Python 版本來測試擴充，並" -"且最好使用\\ *最低*\\ 版本進行建置。" - -#: ../../c-api/stable.rst:173 -msgid "" -"We also recommend reviewing documentation of all used API to check if it is " -"explicitly part of the Limited API. Even with ``Py_LIMITED_API`` defined, a " -"few private declarations are exposed for technical reasons (or even " -"unintentionally, as bugs)." -msgstr "" -"我們也建議要查看所有使用過的 API 的文件，檢查它是否明確屬於受限 API。即使有定" -"義 ``Py_LIMITED_API``，一些私有聲明也會因為技術原因（或者甚至是無意地，例如臭" -"蟲）而被公開出來。" - -#: ../../c-api/stable.rst:178 -msgid "" -"Also note that the Limited API is not necessarily stable: compiling with " -"``Py_LIMITED_API`` with Python 3.8 means that the extension will run with " -"Python 3.12, but it will not necessarily *compile* with Python 3.12. In " -"particular, parts of the Limited API may be deprecated and removed, provided " -"that the Stable ABI stays stable." -msgstr "" -"另請注意，受限 API 不一定是穩定的：在 Python 3.8 中使用 ``Py_LIMITED_API`` 進" -"行編譯意味著擴充將能以 Python 3.12 運行，但不一定能以 Python 3.12 *編譯*。特" -"別是如果穩定 ABI 保持穩定，部分受限 API 可能會被棄用和刪除。" - -#: ../../c-api/stable.rst:188 -msgid "Platform Considerations" -msgstr "平台注意事項" - -#: ../../c-api/stable.rst:190 -msgid "" -"ABI stability depends not only on Python, but also on the compiler used, " -"lower-level libraries and compiler options. For the purposes of " -"the :ref:`Stable ABI `, these details define a “platform”. They " -"usually depend on the OS type and processor architecture" -msgstr "" -"ABI 穩定性不僅取決於 Python，還取決於使用的編譯器、低階函式庫和編譯器選項。出" -"於\\ :ref:`穩定 ABI ` 的目的，這些細節定義了一個「平台」。它們通" -"常取決於作業系統種類和處理器架構" - -#: ../../c-api/stable.rst:195 -msgid "" -"It is the responsibility of each particular distributor of Python to ensure " -"that all Python versions on a particular platform are built in a way that " -"does not break the Stable ABI. This is the case with Windows and macOS " -"releases from ``python.org`` and many third-party distributors." -msgstr "" -"每個特定的 Python 發布者都有責任確保特定平台上的所有 Python 版本都以不破壞穩" -"定 ABI 的方式建置。``python.org`` 和許多第三方發布者發布的 Windows 和 macOS " -"版本就是這種情況。" - -#: ../../c-api/stable.rst:205 -msgid "Contents of Limited API" -msgstr "受限 API 的內容" - -#: ../../c-api/stable.rst:208 -msgid "" -"Currently, the :ref:`Limited API ` includes the following " -"items:" -msgstr "目前，:ref:`受限 API ` 包括以下項目：" - -#: ../../c-api/stable.rst:42 -msgid "PyUnstable" -msgstr "PyUnstable" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Matt Wang , 2023 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: 2023-01-24 21:07+0800\n" +"Last-Translator: Matt Wang \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" +"X-Generator: Poedit 3.2.2\n" + +#: ../../c-api/stable.rst:7 +msgid "C API Stability" +msgstr "C API 穩定性" + +#: ../../c-api/stable.rst:9 +msgid "" +"Unless documented otherwise, Python's C API is covered by the Backwards " +"Compatibility Policy, :pep:`387`. Most changes to it are source-compatible " +"(typically by only adding new API). Changing existing API or removing API is " +"only done after a deprecation period or to fix serious issues." +msgstr "" +"除非有另外記錄於文件，Python 的 C API 被包含在向後相容性策略 :pep:`387` 中。" +"大多數改動都是相容於原始碼的（通常只會增加新的 API）。更改現有 API 或刪除 " +"API 僅在棄用期後或修復嚴重問題時進行。" + +#: ../../c-api/stable.rst:15 +msgid "" +"CPython's Application Binary Interface (ABI) is forward- and backwards-" +"compatible across a minor release (if these are compiled the same way; " +"see :ref:`stable-abi-platform` below). So, code compiled for Python 3.10.0 " +"will work on 3.10.8 and vice versa, but will need to be compiled separately " +"for 3.9.x and 3.11.x." +msgstr "" +"CPython 的應用程式二進位介面 (Application Binary Interface, ABI) 在次要版本中" +"是向前和向後相容的（如果它們以相同的方式編譯；請參閱下面的\\ :ref:`stable-" +"abi-platform`\\）。因此，為 Python 3.10.0 編譯的程式碼將能夠在 3.10.8 上運" +"行，反之亦然，但 3.9.x 和 3.11.x 就需要分別編譯。" + +#: ../../c-api/stable.rst:21 +msgid "There are two tiers of C API with different stability expectations:" +msgstr "C API 有兩層級，有不同的穩定性期望：" + +#: ../../c-api/stable.rst:23 +msgid "" +":ref:`Unstable API `, may change in minor versions without a " +"deprecation period. It is marked by the ``PyUnstable`` prefix in names." +msgstr "" +":ref:`不穩定 API `，可能會在次要版本中發生變化，而沒有棄用階" +"段。會在名稱中以 ``PyUnstable`` 前綴來標記。" + +#: ../../c-api/stable.rst:25 +msgid "" +":ref:`Limited API `, is compatible across several minor " +"releases. When :c:macro:`Py_LIMITED_API` is defined, only this subset is " +"exposed from ``Python.h``." +msgstr "" +":ref:`受限 API `，在多個次要版本之間相容。當有定" +"義 :c:macro:`Py_LIMITED_API` 時，只有這個子集會從 ``Python.h`` 公開。" + +#: ../../c-api/stable.rst:29 +msgid "These are discussed in more detail below." +msgstr "下面將更詳細地討論這些內容。" + +#: ../../c-api/stable.rst:31 +msgid "" +"Names prefixed by an underscore, such as ``_Py_InternalState``, are private " +"API that can change without notice even in patch releases. If you need to " +"use this API, consider reaching out to `CPython developers `_ to discuss adding public API for " +"your use case." +msgstr "" +"帶有底線前綴的名稱是私有 API (private API)，像是 ``_Py_InternalState``，即使" +"在補丁版本 (patch release) 中也可能被更改，不會另行通知。如果你需要使用這個 " +"API，可以聯繫 `CPython 開發者 `_ 並針對你的使用方法來討論是否新增公開的 API。" + +#: ../../c-api/stable.rst:40 +msgid "Unstable C API" +msgstr "不穩定的 C API" + +#: ../../c-api/stable.rst:44 +msgid "" +"Any API named with the ``PyUnstable`` prefix exposes CPython implementation " +"details, and may change in every minor release (e.g. from 3.9 to 3.10) " +"without any deprecation warnings. However, it will not change in a bugfix " +"release (e.g. from 3.10.0 to 3.10.1)." +msgstr "" +"任何以 ``PyUnstable`` 前綴命名的 API 都會公開 CPython 實作細節，並可能在每個" +"次要版本中進行更改（例如從 3.9 到 3.10），而不會出現任何棄用警告。但是它不會" +"在錯誤修復發布版本中發生變化（例如從 3.10.0 到 3.10.1）。" + +#: ../../c-api/stable.rst:49 +msgid "" +"It is generally intended for specialized, low-level tools like debuggers." +msgstr "它通常用於專門的低階工具，例如偵錯器。" + +#: ../../c-api/stable.rst:51 +msgid "" +"Projects that use this API are expected to follow CPython development and " +"spend extra effort adjusting to changes." +msgstr "" +"使用此 API 的專案應該要遵循 CPython 開發細節，並花費額外的力氣來針對這些變動" +"來做調整。" + +#: ../../c-api/stable.rst:57 +msgid "Stable Application Binary Interface" +msgstr "穩定的應用程式二進位介面" + +#: ../../c-api/stable.rst:59 +msgid "" +"For simplicity, this document talks about *extensions*, but the Limited API " +"and Stable ABI work the same way for all uses of the API – for example, " +"embedding Python." +msgstr "" +"為簡單起見，本文件討論\\ *擴充 (extension)*，但受限 API 和穩定 ABI 在所有 " +"API 使用方式中都以相同的方式運作 -- 例如在嵌入式 Python (embedding Python) " +"中。" + +#: ../../c-api/stable.rst:66 +msgid "Limited C API" +msgstr "受限 C API" + +#: ../../c-api/stable.rst:68 +msgid "" +"Python 3.2 introduced the *Limited API*, a subset of Python's C API. " +"Extensions that only use the Limited API can be compiled once and be loaded " +"on multiple versions of Python. Contents of the Limited API are :ref:`listed " +"below `." +msgstr "" +"Python 3.2 引入了\\ *受限 API (Limited API)*，它是 Python C API 的一個子集。" +"僅使用受限 API 的擴充可以只編譯一次就被載入於多個版本的 Python。受限 API 的內" +"容\\ :ref:`列在下方 `。" + +#: ../../c-api/stable.rst:75 +msgid "" +"Define this macro before including ``Python.h`` to opt in to only use the " +"Limited API, and to select the Limited API version." +msgstr "" +"在包含 ``Python.h`` 之前定義此巨集以選擇只使用受限 API，並挑選受限 API 版本。" + +#: ../../c-api/stable.rst:78 +msgid "" +"Define ``Py_LIMITED_API`` to the value of :c:macro:`PY_VERSION_HEX` " +"corresponding to the lowest Python version your extension supports. The " +"extension will be ABI-compatible with all Python 3 releases from the " +"specified one onward, and can use Limited API introduced up to that version." +msgstr "" +"將 ``Py_LIMITED_API`` 定義為對應於你的擴充有支援的最低 Python 版本" +"的 :c:macro:`PY_VERSION_HEX` 值。該擴充與從指定版本開始的所有 Python 3 版本" +"之 ABI 相容，並且可以使用過去版本有引入的受限 API。" + +#: ../../c-api/stable.rst:84 +msgid "" +"Rather than using the ``PY_VERSION_HEX`` macro directly, hardcode a minimum " +"minor version (e.g. ``0x030A0000`` for Python 3.10) for stability when " +"compiling with future Python versions." +msgstr "" +"與其直接使用 ``PY_VERSION_HEX`` 巨集，不如寫死 (hardcode) 最小次要版本（例如" +"代表 Python 3.10 的 ``0x030A0000``\\ ），以便在使用未來的 Python 版本進行編譯" +"時仍保持穩定性。" + +#: ../../c-api/stable.rst:88 +msgid "" +"You can also define ``Py_LIMITED_API`` to ``3``. This works the same as " +"``0x03020000`` (Python 3.2, the version that introduced Limited API)." +msgstr "" +"你還可以將 ``Py_LIMITED_API`` 定義為 ``3``，這與 ``0x03020000``\\ （Python " +"3.2，引入了受限 API 的版本）相同。" + +#: ../../c-api/stable.rst:95 +msgid "Stable ABI" +msgstr "穩定 ABI" + +#: ../../c-api/stable.rst:97 +msgid "" +"To enable this, Python provides a *Stable ABI*: a set of symbols that will " +"remain ABI-compatible across Python 3.x versions." +msgstr "" +"為了實現它，Python 提供了一個\\ *穩定 ABI (Stable ABI)*：一組將在各個 Python " +"3.x 版本之間保持 ABI 相容的符號。" + +#: ../../c-api/stable.rst:102 +msgid "" +"The Stable ABI prevents ABI issues, like linker errors due to missing " +"symbols or data corruption due to changes in structure layouts or function " +"signatures. However, other changes in Python can change the *behavior* of " +"extensions. See Python's Backwards Compatibility Policy (:pep:`387`) for " +"details." +msgstr "" +"穩定 ABI 可以防止 ABI 問題，例如由於結構布局或函式簽名變化導致缺少符號或數據" +"損壞的鏈接器 (linker) 錯誤。然而，Python 的其他變化可能會改變 *行為* 的擴充。" +"有關詳細資訊，請參閱 Python 的向後相容性政策 (:pep:`387`)。" + +#: ../../c-api/stable.rst:108 +msgid "" +"The Stable ABI contains symbols exposed in the :ref:`Limited API `, but also other ones – for example, functions necessary to support " +"older versions of the Limited API." +msgstr "" +"穩定 ABI 被包含在\\ :ref:`受限 API ` 中開放的符號，但也包含其" +"他符號 - 例如，支援舊版受限 API 所必需的函式。" + +#: ../../c-api/stable.rst:112 +msgid "" +"On Windows, extensions that use the Stable ABI should be linked against " +"``python3.dll`` rather than a version-specific library such as " +"``python39.dll``." +msgstr "" +"在 Windows 上，使用穩定 ABI 的擴充應該連接到 ``python3.dll`` 而不是特定版本的" +"函式庫，例如 ``python39.dll``。" + +#: ../../c-api/stable.rst:116 +msgid "" +"On some platforms, Python will look for and load shared library files named " +"with the ``abi3`` tag (e.g. ``mymodule.abi3.so``). It does not check if such " +"extensions conform to a Stable ABI. The user (or their packaging tools) need " +"to ensure that, for example, extensions built with the 3.10+ Limited API are " +"not installed for lower versions of Python." +msgstr "" +"在某些平台上，Python 將查找並加載以 ``abi3`` 標籤命名的共享函式庫檔案（例如 " +"``mymodule.abi3.so``\\ ）。它不檢查此類擴充是否符合穩定的 ABI。確保的責任在使" +"用者（或者打包工具）身上，例如使用 3.10+ 受限 API 建置的擴充不會為較低版本的 " +"Python 所安裝。" + +#: ../../c-api/stable.rst:123 +msgid "" +"All functions in the Stable ABI are present as functions in Python's shared " +"library, not solely as macros. This makes them usable from languages that " +"don't use the C preprocessor." +msgstr "" +"穩定 ABI 中的所有函式都作為函式存在於 Python 的共享函式庫中，而不僅是作為巨" +"集。這使得它們可被用於不使用 C 預處理器 (preprocessor) 的語言。" + +#: ../../c-api/stable.rst:129 +msgid "Limited API Scope and Performance" +msgstr "受限 API 範圍和性能" + +#: ../../c-api/stable.rst:131 +msgid "" +"The goal for the Limited API is to allow everything that is possible with " +"the full C API, but possibly with a performance penalty." +msgstr "" +"受限 API 的目標是允許使用完整的 C API 進行所有可能的操作，但可能會降低性能。" + +#: ../../c-api/stable.rst:134 +msgid "" +"For example, while :c:func:`PyList_GetItem` is available, its “unsafe” macro " +"variant :c:func:`PyList_GET_ITEM` is not. The macro can be faster because it " +"can rely on version-specific implementation details of the list object." +msgstr "" +"例如，雖然 :c:func:`PyList_GetItem` 可用，但它的「不安全」巨集變" +"體 :c:func:`PyList_GET_ITEM` 為不可用。巨集運行可以更快，因為它可以依賴 list " +"物件的特定版本實作細節。" + +#: ../../c-api/stable.rst:139 +msgid "" +"Without ``Py_LIMITED_API`` defined, some C API functions are inlined or " +"replaced by macros. Defining ``Py_LIMITED_API`` disables this inlining, " +"allowing stability as Python's data structures are improved, but possibly " +"reducing performance." +msgstr "" +"如果沒有定義 ``Py_LIMITED_API``，一些 C API 函式將被嵌入或被替換為巨集。定義 " +"``Py_LIMITED_API`` 會禁用嵌入，從而隨著 Python 資料結構的改進而提高穩定性，但" +"可能會降低性能。" + +#: ../../c-api/stable.rst:144 +msgid "" +"By leaving out the ``Py_LIMITED_API`` definition, it is possible to compile " +"a Limited API extension with a version-specific ABI. This can improve " +"performance for that Python version, but will limit compatibility. Compiling " +"with ``Py_LIMITED_API`` will then yield an extension that can be distributed " +"where a version-specific one is not available – for example, for prereleases " +"of an upcoming Python version." +msgstr "" +"透過省略 ``Py_LIMITED_API`` 定義，可以使用特定版本的 ABI 編譯受限 API 擴充。" +"這可以提高該 Python 版本的性能，但會限制相容性。使用 ``Py_LIMITED_API`` 編譯" +"將產生一個擴充，可以在特定版本的擴充不可用的地方發布 — 例如，用於即將發布的 " +"Python 版本的預發布版本 (prerelease)。" + +#: ../../c-api/stable.rst:153 +msgid "Limited API Caveats" +msgstr "受限 API 注意事項" + +#: ../../c-api/stable.rst:155 +msgid "" +"Note that compiling with ``Py_LIMITED_API`` is *not* a complete guarantee " +"that code conforms to the :ref:`Limited API ` or " +"the :ref:`Stable ABI `. ``Py_LIMITED_API`` only covers " +"definitions, but an API also includes other issues, such as expected " +"semantics." +msgstr "" +"請注意，使用 ``Py_LIMITED_API`` 進行編譯\\ *不*\\ 完全保證程式碼符合\\ :ref:`" +"受限 API ` 或\\ :ref:`穩定 ABI `。" +"``Py_LIMITED_API`` 僅涵蓋定義，但 API 還包括其他議題，例如預期的語義 " +"(semantic)。" + +#: ../../c-api/stable.rst:160 +msgid "" +"One issue that ``Py_LIMITED_API`` does not guard against is calling a " +"function with arguments that are invalid in a lower Python version. For " +"example, consider a function that starts accepting ``NULL`` for an argument. " +"In Python 3.9, ``NULL`` now selects a default behavior, but in Python 3.8, " +"the argument will be used directly, causing a ``NULL`` dereference and " +"crash. A similar argument works for fields of structs." +msgstr "" +"``Py_LIMITED_API`` 無法防範的一個問題是使用在較低 Python 版本中無效的引數來呼" +"叫函式。例如一個開始接受 ``NULL`` 作為引數的函式。在 Python 3.9 中，``NULL`` " +"現在代表選擇預設行為，但在 Python 3.8 中，引數將被直接使用，導致 ``NULL`` 取" +"消參照 (dereference) 且崩潰 (crash)。類似的引數適用於結構 (struct) 的欄位。" + +#: ../../c-api/stable.rst:167 +msgid "" +"Another issue is that some struct fields are currently not hidden when " +"``Py_LIMITED_API`` is defined, even though they're part of the Limited API." +msgstr "" +"另一個問題是，當有定義 ``Py_LIMITED_API`` 時，一些結構欄位目前不會被隱藏，即" +"使它們是受限 API 的一部分。" + +#: ../../c-api/stable.rst:170 +msgid "" +"For these reasons, we recommend testing an extension with *all* minor Python " +"versions it supports, and preferably to build with the *lowest* such version." +msgstr "" +"出於這些原因，我們建議要以它支援的\\ *所有*\\ 次要 Python 版本來測試擴充，並" +"且最好使用\\ *最低*\\ 版本進行建置。" + +#: ../../c-api/stable.rst:173 +msgid "" +"We also recommend reviewing documentation of all used API to check if it is " +"explicitly part of the Limited API. Even with ``Py_LIMITED_API`` defined, a " +"few private declarations are exposed for technical reasons (or even " +"unintentionally, as bugs)." +msgstr "" +"我們也建議要查看所有使用過的 API 的文件，檢查它是否明確屬於受限 API。即使有定" +"義 ``Py_LIMITED_API``，一些私有聲明也會因為技術原因（或者甚至是無意地，例如臭" +"蟲）而被公開出來。" + +#: ../../c-api/stable.rst:178 +msgid "" +"Also note that the Limited API is not necessarily stable: compiling with " +"``Py_LIMITED_API`` with Python 3.8 means that the extension will run with " +"Python 3.12, but it will not necessarily *compile* with Python 3.12. In " +"particular, parts of the Limited API may be deprecated and removed, provided " +"that the Stable ABI stays stable." +msgstr "" +"另請注意，受限 API 不一定是穩定的：在 Python 3.8 中使用 ``Py_LIMITED_API`` 進" +"行編譯意味著擴充將能以 Python 3.12 運行，但不一定能以 Python 3.12 *編譯*。特" +"別是如果穩定 ABI 保持穩定，部分受限 API 可能會被棄用和刪除。" + +#: ../../c-api/stable.rst:188 +msgid "Platform Considerations" +msgstr "平台注意事項" + +#: ../../c-api/stable.rst:190 +msgid "" +"ABI stability depends not only on Python, but also on the compiler used, " +"lower-level libraries and compiler options. For the purposes of " +"the :ref:`Stable ABI `, these details define a “platform”. They " +"usually depend on the OS type and processor architecture" +msgstr "" +"ABI 穩定性不僅取決於 Python，還取決於使用的編譯器、低階函式庫和編譯器選項。出" +"於\\ :ref:`穩定 ABI ` 的目的，這些細節定義了一個「平台」。它們通" +"常取決於作業系統種類和處理器架構" + +#: ../../c-api/stable.rst:195 +msgid "" +"It is the responsibility of each particular distributor of Python to ensure " +"that all Python versions on a particular platform are built in a way that " +"does not break the Stable ABI. This is the case with Windows and macOS " +"releases from ``python.org`` and many third-party distributors." +msgstr "" +"每個特定的 Python 發布者都有責任確保特定平台上的所有 Python 版本都以不破壞穩" +"定 ABI 的方式建置。``python.org`` 和許多第三方發布者發布的 Windows 和 macOS " +"版本就是這種情況。" + +#: ../../c-api/stable.rst:205 +msgid "Contents of Limited API" +msgstr "受限 API 的內容" + +#: ../../c-api/stable.rst:208 +msgid "" +"Currently, the :ref:`Limited API ` includes the following " +"items:" +msgstr "目前，:ref:`受限 API ` 包括以下項目：" + +#: ../../c-api/stable.rst:42 +msgid "PyUnstable" +msgstr "PyUnstable" diff --git a/c-api/structures.po b/c-api/structures.po index 9085983507..4288b54605 100644 --- a/c-api/structures.po +++ b/c-api/structures.po @@ -1,1221 +1,1221 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Leon H., 2017 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-20 00:14+0000\n" -"PO-Revision-Date: 2018-05-23 14: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" - -#: ../../c-api/structures.rst:6 -msgid "Common Object Structures" -msgstr "通用物件結構" - -#: ../../c-api/structures.rst:8 -msgid "" -"There are a large number of structures which are used in the definition of " -"object types for Python. This section describes these structures and how " -"they are used." -msgstr "" - -#: ../../c-api/structures.rst:14 -msgid "Base object types and macros" -msgstr "" - -#: ../../c-api/structures.rst:16 -msgid "" -"All Python objects ultimately share a small number of fields at the " -"beginning of the object's representation in memory. These are represented " -"by the :c:type:`PyObject` and :c:type:`PyVarObject` types, which are " -"defined, in turn, by the expansions of some macros also used, whether " -"directly or indirectly, in the definition of all other Python objects. " -"Additional macros can be found under :ref:`reference counting " -"`." -msgstr "" - -#: ../../c-api/structures.rst:26 -msgid "" -"All object types are extensions of this type. This is a type which contains " -"the information Python needs to treat a pointer to an object as an object. " -"In a normal \"release\" build, it contains only the object's reference count " -"and a pointer to the corresponding type object. Nothing is actually declared " -"to be a :c:type:`PyObject`, but every pointer to a Python object can be cast " -"to a :c:expr:`PyObject*`." -msgstr "" - -#: ../../c-api/structures.rst:33 -msgid "" -"The members must not be accessed directly; instead use macros such as :c:" -"macro:`Py_REFCNT` and :c:macro:`Py_TYPE`." -msgstr "" - -#: ../../c-api/structures.rst:38 -msgid "" -"The object's reference count, as returned by :c:macro:`Py_REFCNT`. Do not " -"use this field directly; instead use functions and macros such as :c:macro:`!" -"Py_REFCNT`, :c:func:`Py_INCREF` and :c:func:`Py_DecRef`." -msgstr "" - -#: ../../c-api/structures.rst:42 -msgid "" -"The field type may be different from ``Py_ssize_t``, depending on build " -"configuration and platform." -msgstr "" - -#: ../../c-api/structures.rst:47 -msgid "" -"The object's type. Do not use this field directly; use :c:macro:`Py_TYPE` " -"and :c:func:`Py_SET_TYPE` instead." -msgstr "" - -#: ../../c-api/structures.rst:54 -msgid "" -"An extension of :c:type:`PyObject` that adds the :c:member:`~PyVarObject." -"ob_size` field. This is intended for objects that have some notion of " -"*length*." -msgstr "" - -#: ../../c-api/structures.rst:58 -msgid "" -"As with :c:type:`!PyObject`, the members must not be accessed directly; " -"instead use macros such as :c:macro:`Py_SIZE`, :c:macro:`Py_REFCNT` and :c:" -"macro:`Py_TYPE`." -msgstr "" - -#: ../../c-api/structures.rst:64 -msgid "" -"A size field, whose contents should be considered an object's internal " -"implementation detail." -msgstr "" - -#: ../../c-api/structures.rst:67 -msgid "Do not use this field directly; use :c:macro:`Py_SIZE` instead." -msgstr "" - -#: ../../c-api/structures.rst:69 -msgid "" -"Object creation functions such as :c:func:`PyObject_NewVar` will generally " -"set this field to the requested size (number of items). After creation, " -"arbitrary values can be stored in :c:member:`!ob_size` using :c:macro:" -"`Py_SET_SIZE`." -msgstr "" - -#: ../../c-api/structures.rst:74 -msgid "" -"To get an object's publicly exposed length, as returned by the Python " -"function :py:func:`len`, use :c:func:`PyObject_Length` instead." -msgstr "" - -#: ../../c-api/structures.rst:81 -msgid "" -"This is a macro used when declaring new types which represent objects " -"without a varying length. The PyObject_HEAD macro expands to::" -msgstr "" - -#: ../../c-api/structures.rst:84 -msgid "PyObject ob_base;" -msgstr "PyObject ob_base;" - -#: ../../c-api/structures.rst:86 -msgid "See documentation of :c:type:`PyObject` above." -msgstr "請見上面 :c:type:`PyObject` 的文件。" - -#: ../../c-api/structures.rst:91 -msgid "" -"This is a macro used when declaring new types which represent objects with a " -"length that varies from instance to instance. The PyObject_VAR_HEAD macro " -"expands to::" -msgstr "" - -#: ../../c-api/structures.rst:95 -msgid "PyVarObject ob_base;" -msgstr "PyVarObject ob_base;" - -#: ../../c-api/structures.rst:97 -msgid "See documentation of :c:type:`PyVarObject` above." -msgstr "請見上面 :c:type:`PyVarObject` 的文件。" - -#: ../../c-api/structures.rst:102 -msgid "" -"The base class of all other objects, the same as :class:`object` in Python." -msgstr "" - -#: ../../c-api/structures.rst:107 -msgid "" -"Test if the *x* object is the *y* object, the same as ``x is y`` in Python." -msgstr "" - -#: ../../c-api/structures.rst:114 -msgid "" -"Test if an object is the ``None`` singleton, the same as ``x is None`` in " -"Python." -msgstr "" - -#: ../../c-api/structures.rst:122 -msgid "" -"Test if an object is the ``True`` singleton, the same as ``x is True`` in " -"Python." -msgstr "" - -#: ../../c-api/structures.rst:130 -msgid "" -"Test if an object is the ``False`` singleton, the same as ``x is False`` in " -"Python." -msgstr "" - -#: ../../c-api/structures.rst:138 -msgid "Get the type of the Python object *o*." -msgstr "" - -#: ../../c-api/structures.rst:140 -msgid "" -"The returned reference is :term:`borrowed ` from *o*. Do " -"not release it with :c:func:`Py_DECREF` or similar." -msgstr "" - -#: ../../c-api/structures.rst:143 -msgid "" -":c:func:`Py_TYPE()` is changed to an inline static function. The parameter " -"type is no longer :c:expr:`const PyObject*`." -msgstr "" - -#: ../../c-api/structures.rst:150 -msgid "" -"Return non-zero if the object *o* type is *type*. Return zero otherwise. " -"Equivalent to: ``Py_TYPE(o) == type``." -msgstr "" - -#: ../../c-api/structures.rst:158 -msgid "" -"Set the type of object *o* to *type*, without any checking or reference " -"counting." -msgstr "" - -#: ../../c-api/structures.rst:161 -msgid "" -"This is a very low-level operation. Consider instead setting the Python " -"attribute :attr:`~object.__class__` using :c:func:`PyObject_SetAttrString` " -"or similar." -msgstr "" - -#: ../../c-api/structures.rst:165 -msgid "" -"Note that assigning an incompatible type can lead to undefined behavior." -msgstr "" - -#: ../../c-api/structures.rst:167 -msgid "" -"If *type* is a :ref:`heap type `, the caller must create a new " -"reference to it. Similarly, if the old type of *o* is a heap type, the " -"caller must release a reference to that type." -msgstr "" - -#: ../../c-api/structures.rst:177 -msgid "Get the :c:member:`~PyVarObject.ob_size` field of *o*." -msgstr "" - -#: ../../c-api/structures.rst:179 -msgid "" -":c:func:`Py_SIZE()` is changed to an inline static function. The parameter " -"type is no longer :c:expr:`const PyVarObject*`." -msgstr "" - -#: ../../c-api/structures.rst:186 -msgid "Set the :c:member:`~PyVarObject.ob_size` field of *o* to *size*." -msgstr "" - -#: ../../c-api/structures.rst:193 -msgid "" -"This is a macro which expands to initialization values for a new :c:type:" -"`PyObject` type. This macro expands to::" -msgstr "" - -#: ../../c-api/structures.rst:196 -msgid "" -"_PyObject_EXTRA_INIT\n" -"1, type," -msgstr "" -"_PyObject_EXTRA_INIT\n" -"1, type," - -#: ../../c-api/structures.rst:202 -msgid "" -"This is a macro which expands to initialization values for a new :c:type:" -"`PyVarObject` type, including the :c:member:`~PyVarObject.ob_size` field. " -"This macro expands to::" -msgstr "" - -#: ../../c-api/structures.rst:206 -msgid "" -"_PyObject_EXTRA_INIT\n" -"1, type, size," -msgstr "" -"_PyObject_EXTRA_INIT\n" -"1, type, size," - -#: ../../c-api/structures.rst:211 -msgid "Implementing functions and methods" -msgstr "實作函式與方法" - -#: ../../c-api/structures.rst:215 -msgid "" -"Type of the functions used to implement most Python callables in C. " -"Functions of this type take two :c:expr:`PyObject*` parameters and return " -"one such value. If the return value is ``NULL``, an exception shall have " -"been set. If not ``NULL``, the return value is interpreted as the return " -"value of the function as exposed in Python. The function must return a new " -"reference." -msgstr "" - -#: ../../c-api/structures.rst:222 -msgid "The function signature is::" -msgstr "" - -#: ../../c-api/structures.rst:224 -msgid "" -"PyObject *PyCFunction(PyObject *self,\n" -" PyObject *args);" -msgstr "" -"PyObject *PyCFunction(PyObject *self,\n" -" PyObject *args);" - -#: ../../c-api/structures.rst:229 -msgid "" -"Type of the functions used to implement Python callables in C with " -"signature :ref:`METH_VARARGS | METH_KEYWORDS `. " -"The function signature is::" -msgstr "" - -#: ../../c-api/structures.rst:233 -msgid "" -"PyObject *PyCFunctionWithKeywords(PyObject *self,\n" -" PyObject *args,\n" -" PyObject *kwargs);" -msgstr "" -"PyObject *PyCFunctionWithKeywords(PyObject *self,\n" -" PyObject *args,\n" -" PyObject *kwargs);" - -#: ../../c-api/structures.rst:240 -msgid "" -"Type of the functions used to implement Python callables in C with " -"signature :c:macro:`METH_FASTCALL`. The function signature is::" -msgstr "" - -#: ../../c-api/structures.rst:244 -msgid "" -"PyObject *PyCFunctionFast(PyObject *self,\n" -" PyObject *const *args,\n" -" Py_ssize_t nargs);" -msgstr "" -"PyObject *PyCFunctionFast(PyObject *self,\n" -" PyObject *const *args,\n" -" Py_ssize_t nargs);" - -#: ../../c-api/structures.rst:250 -msgid "" -"Type of the functions used to implement Python callables in C with " -"signature :ref:`METH_FASTCALL | METH_KEYWORDS `. The function signature is::" -msgstr "" - -#: ../../c-api/structures.rst:254 -msgid "" -"PyObject *PyCFunctionFastWithKeywords(PyObject *self,\n" -" PyObject *const *args,\n" -" Py_ssize_t nargs,\n" -" PyObject *kwnames);" -msgstr "" -"PyObject *PyCFunctionFastWithKeywords(PyObject *self,\n" -" PyObject *const *args,\n" -" Py_ssize_t nargs,\n" -" PyObject *kwnames);" - -#: ../../c-api/structures.rst:261 -msgid "" -"Type of the functions used to implement Python callables in C with " -"signature :ref:`METH_METHOD | METH_FASTCALL | METH_KEYWORDS `. The function signature is::" -msgstr "" - -#: ../../c-api/structures.rst:265 -msgid "" -"PyObject *PyCMethod(PyObject *self,\n" -" PyTypeObject *defining_class,\n" -" PyObject *const *args,\n" -" Py_ssize_t nargs,\n" -" PyObject *kwnames)" -msgstr "" -"PyObject *PyCMethod(PyObject *self,\n" -" PyTypeObject *defining_class,\n" -" PyObject *const *args,\n" -" Py_ssize_t nargs,\n" -" PyObject *kwnames)" - -#: ../../c-api/structures.rst:276 -msgid "" -"Structure used to describe a method of an extension type. This structure " -"has four fields:" -msgstr "" - -#: ../../c-api/structures.rst:281 -msgid "Name of the method." -msgstr "" - -#: ../../c-api/structures.rst:285 -msgid "Pointer to the C implementation." -msgstr "" - -#: ../../c-api/structures.rst:289 -msgid "Flags bits indicating how the call should be constructed." -msgstr "" - -#: ../../c-api/structures.rst:293 -msgid "Points to the contents of the docstring." -msgstr "" - -#: ../../c-api/structures.rst:295 -msgid "" -"The :c:member:`~PyMethodDef.ml_meth` is a C function pointer. The functions " -"may be of different types, but they always return :c:expr:`PyObject*`. If " -"the function is not of the :c:type:`PyCFunction`, the compiler will require " -"a cast in the method table. Even though :c:type:`PyCFunction` defines the " -"first parameter as :c:expr:`PyObject*`, it is common that the method " -"implementation uses the specific C type of the *self* object." -msgstr "" - -#: ../../c-api/structures.rst:303 -msgid "" -"The :c:member:`~PyMethodDef.ml_flags` field is a bitfield which can include " -"the following flags. The individual flags indicate either a calling " -"convention or a binding convention." -msgstr "" - -#: ../../c-api/structures.rst:308 -msgid "There are these calling conventions:" -msgstr "" - -#: ../../c-api/structures.rst:312 -msgid "" -"This is the typical calling convention, where the methods have the type :c:" -"type:`PyCFunction`. The function expects two :c:expr:`PyObject*` values. The " -"first one is the *self* object for methods; for module functions, it is the " -"module object. The second parameter (often called *args*) is a tuple object " -"representing all arguments. This parameter is typically processed using :c:" -"func:`PyArg_ParseTuple` or :c:func:`PyArg_UnpackTuple`." -msgstr "" - -#: ../../c-api/structures.rst:322 -msgid "" -"Can only be used in certain combinations with other flags: :ref:" -"`METH_VARARGS | METH_KEYWORDS `, :ref:" -"`METH_FASTCALL | METH_KEYWORDS ` and :ref:" -"`METH_METHOD | METH_FASTCALL | METH_KEYWORDS `." -msgstr "" - -#: ../../c-api/structures.rst:330 -msgid ":c:expr:`METH_VARARGS | METH_KEYWORDS`" -msgstr ":c:expr:`METH_VARARGS | METH_KEYWORDS`" - -#: ../../c-api/structures.rst:331 -msgid "" -"Methods with these flags must be of type :c:type:`PyCFunctionWithKeywords`. " -"The function expects three parameters: *self*, *args*, *kwargs* where " -"*kwargs* is a dictionary of all the keyword arguments or possibly ``NULL`` " -"if there are no keyword arguments. The parameters are typically processed " -"using :c:func:`PyArg_ParseTupleAndKeywords`." -msgstr "" - -#: ../../c-api/structures.rst:340 -msgid "" -"Fast calling convention supporting only positional arguments. The methods " -"have the type :c:type:`PyCFunctionFast`. The first parameter is *self*, the " -"second parameter is a C array of :c:expr:`PyObject*` values indicating the " -"arguments and the third parameter is the number of arguments (the length of " -"the array)." -msgstr "" - -#: ../../c-api/structures.rst:350 -msgid "``METH_FASTCALL`` is now part of the :ref:`stable ABI `." -msgstr "" - -#: ../../c-api/structures.rst:355 -msgid ":c:expr:`METH_FASTCALL | METH_KEYWORDS`" -msgstr ":c:expr:`METH_FASTCALL | METH_KEYWORDS`" - -#: ../../c-api/structures.rst:356 -msgid "" -"Extension of :c:macro:`METH_FASTCALL` supporting also keyword arguments, " -"with methods of type :c:type:`PyCFunctionFastWithKeywords`. Keyword " -"arguments are passed the same way as in the :ref:`vectorcall protocol " -"`: there is an additional fourth :c:expr:`PyObject*` parameter " -"which is a tuple representing the names of the keyword arguments (which are " -"guaranteed to be strings) or possibly ``NULL`` if there are no keywords. " -"The values of the keyword arguments are stored in the *args* array, after " -"the positional arguments." -msgstr "" - -#: ../../c-api/structures.rst:371 -msgid "" -"Can only be used in the combination with other flags: :ref:`METH_METHOD | " -"METH_FASTCALL | METH_KEYWORDS `." -msgstr "" - -#: ../../c-api/structures.rst:377 -msgid ":c:expr:`METH_METHOD | METH_FASTCALL | METH_KEYWORDS`" -msgstr ":c:expr:`METH_METHOD | METH_FASTCALL | METH_KEYWORDS`" - -#: ../../c-api/structures.rst:378 -msgid "" -"Extension of :ref:`METH_FASTCALL | METH_KEYWORDS ` supporting the *defining class*, that is, the class that " -"contains the method in question. The defining class might be a superclass of " -"``Py_TYPE(self)``." -msgstr "" - -#: ../../c-api/structures.rst:383 -msgid "" -"The method needs to be of type :c:type:`PyCMethod`, the same as for " -"``METH_FASTCALL | METH_KEYWORDS`` with ``defining_class`` argument added " -"after ``self``." -msgstr "" - -#: ../../c-api/structures.rst:392 -msgid "" -"Methods without parameters don't need to check whether arguments are given " -"if they are listed with the :c:macro:`METH_NOARGS` flag. They need to be of " -"type :c:type:`PyCFunction`. The first parameter is typically named *self* " -"and will hold a reference to the module or object instance. In all cases " -"the second parameter will be ``NULL``." -msgstr "" - -#: ../../c-api/structures.rst:398 -msgid "" -"The function must have 2 parameters. Since the second parameter is unused, :" -"c:macro:`Py_UNUSED` can be used to prevent a compiler warning." -msgstr "" - -#: ../../c-api/structures.rst:404 -msgid "" -"Methods with a single object argument can be listed with the :c:macro:" -"`METH_O` flag, instead of invoking :c:func:`PyArg_ParseTuple` with a " -"``\"O\"`` argument. They have the type :c:type:`PyCFunction`, with the " -"*self* parameter, and a :c:expr:`PyObject*` parameter representing the " -"single argument." -msgstr "" - -#: ../../c-api/structures.rst:410 -msgid "" -"These two constants are not used to indicate the calling convention but the " -"binding when use with methods of classes. These may not be used for " -"functions defined for modules. At most one of these flags may be set for " -"any given method." -msgstr "" - -#: ../../c-api/structures.rst:420 -msgid "" -"The method will be passed the type object as the first parameter rather than " -"an instance of the type. This is used to create *class methods*, similar to " -"what is created when using the :func:`classmethod` built-in function." -msgstr "" - -#: ../../c-api/structures.rst:430 -msgid "" -"The method will be passed ``NULL`` as the first parameter rather than an " -"instance of the type. This is used to create *static methods*, similar to " -"what is created when using the :func:`staticmethod` built-in function." -msgstr "" - -#: ../../c-api/structures.rst:434 -msgid "" -"One other constant controls whether a method is loaded in place of another " -"definition with the same method name." -msgstr "" - -#: ../../c-api/structures.rst:440 -msgid "" -"The method will be loaded in place of existing definitions. Without " -"*METH_COEXIST*, the default is to skip repeated definitions. Since slot " -"wrappers are loaded before the method table, the existence of a " -"*sq_contains* slot, for example, would generate a wrapped method named :meth:" -"`~object.__contains__` and preclude the loading of a corresponding " -"PyCFunction with the same name. With the flag defined, the PyCFunction will " -"be loaded in place of the wrapper object and will co-exist with the slot. " -"This is helpful because calls to PyCFunctions are optimized more than " -"wrapper object calls." -msgstr "" - -#: ../../c-api/structures.rst:453 -msgid "" -"The type object corresponding to Python C method objects. This is available " -"as :class:`types.BuiltinMethodType` in the Python layer." -msgstr "" - -#: ../../c-api/structures.rst:459 -msgid "" -"Return true if *op* is an instance of the :c:type:`PyCMethod_Type` type or a " -"subtype of it. This function always succeeds." -msgstr "" - -#: ../../c-api/structures.rst:465 -msgid "" -"This is the same as :c:func:`PyCMethod_Check`, but does not account for " -"subtypes." -msgstr "" - -#: ../../c-api/structures.rst:471 -msgid "" -"Turn *ml* into a Python :term:`callable` object. The caller must ensure that " -"*ml* outlives the :term:`callable`. Typically, *ml* is defined as a static " -"variable." -msgstr "" - -#: ../../c-api/structures.rst:475 -msgid "" -"The *self* parameter will be passed as the *self* argument to the C function " -"in ``ml->ml_meth`` when invoked. *self* can be ``NULL``." -msgstr "" - -#: ../../c-api/structures.rst:479 -msgid "" -"The :term:`callable` object's ``__module__`` attribute can be set from the " -"given *module* argument. *module* should be a Python string, which will be " -"used as name of the module the function is defined in. If unavailable, it " -"can be set to :const:`None` or ``NULL``." -msgstr "" - -#: ../../c-api/structures.rst:485 -msgid ":attr:`function.__module__`" -msgstr ":attr:`function.__module__`" - -#: ../../c-api/structures.rst:487 -msgid "" -"The *cls* parameter will be passed as the *defining_class* argument to the C " -"function. Must be set if :c:macro:`METH_METHOD` is set on ``ml->ml_flags``." -msgstr "" - -#: ../../c-api/structures.rst:496 -msgid "" -"The type object corresponding to Python C function objects. This is " -"available as :class:`types.BuiltinFunctionType` in the Python layer." -msgstr "" - -#: ../../c-api/structures.rst:502 -msgid "" -"Return true if *op* is an instance of the :c:type:`PyCFunction_Type` type or " -"a subtype of it. This function always succeeds." -msgstr "" - -#: ../../c-api/structures.rst:508 -msgid "" -"This is the same as :c:func:`PyCFunction_Check`, but does not account for " -"subtypes." -msgstr "" - -#: ../../c-api/structures.rst:514 -msgid "Equivalent to ``PyCMethod_New(ml, self, module, NULL)``." -msgstr "等價於 ``PyCMethod_New(ml, self, module, NULL)``。" - -#: ../../c-api/structures.rst:519 -msgid "Equivalent to ``PyCMethod_New(ml, self, NULL, NULL)``." -msgstr "等價於 ``PyCMethod_New(ml, self, NULL, NULL)``。" - -#: ../../c-api/structures.rst:524 -msgid "" -"Get the function's flags on *func* as they were passed to :c:member:" -"`~PyMethodDef.ml_flags`." -msgstr "" - -#: ../../c-api/structures.rst:527 ../../c-api/structures.rst:545 -#: ../../c-api/structures.rst:565 -msgid "" -"If *func* is not a C function object, this fails with an exception. *func* " -"must not be ``NULL``." -msgstr "" - -#: ../../c-api/structures.rst:530 -msgid "" -"This function returns the function's flags on success, and ``-1`` with an " -"exception set on failure." -msgstr "" - -#: ../../c-api/structures.rst:536 -msgid "" -"This is the same as :c:func:`PyCFunction_GetFlags`, but without error or " -"type checking." -msgstr "" - -#: ../../c-api/structures.rst:542 -msgid "" -"Get the function pointer on *func* as it was passed to :c:member:" -"`~PyMethodDef.ml_meth`." -msgstr "" - -#: ../../c-api/structures.rst:548 -msgid "" -"This function returns the function pointer on success, and ``NULL`` with an " -"exception set on failure." -msgstr "" - -#: ../../c-api/structures.rst:554 -msgid "" -"This is the same as :c:func:`PyCFunction_GetFunction`, but without error or " -"type checking." -msgstr "" - -#: ../../c-api/structures.rst:560 -msgid "" -"Get the \"self\" object on *func*. This is the object that would be passed " -"to the first argument of a :c:type:`PyCFunction`. For C function objects " -"created through a :c:type:`PyMethodDef` on a :c:type:`PyModuleDef`, this is " -"the resulting module object." -msgstr "" - -#: ../../c-api/structures.rst:568 -msgid "" -"This function returns a :term:`borrowed reference` to the \"self\" object on " -"success, and ``NULL`` with an exception set on failure." -msgstr "" - -#: ../../c-api/structures.rst:574 -msgid "" -"This is the same as :c:func:`PyCFunction_GetSelf`, but without error or type " -"checking." -msgstr "" - -#: ../../c-api/structures.rst:579 -msgid "Accessing attributes of extension types" -msgstr "" - -#: ../../c-api/structures.rst:583 -msgid "" -"Structure which describes an attribute of a type which corresponds to a C " -"struct member. When defining a class, put a NULL-terminated array of these " -"structures in the :c:member:`~PyTypeObject.tp_members` slot." -msgstr "" - -#: ../../c-api/structures.rst:588 -msgid "Its fields are, in order:" -msgstr "" - -#: ../../c-api/structures.rst:592 -msgid "" -"Name of the member. A NULL value marks the end of a ``PyMemberDef[]`` array." -msgstr "" - -#: ../../c-api/structures.rst:595 -msgid "The string should be static, no copy is made of it." -msgstr "" - -#: ../../c-api/structures.rst:599 -msgid "" -"The type of the member in the C struct. See :ref:`PyMemberDef-types` for the " -"possible values." -msgstr "" - -#: ../../c-api/structures.rst:604 -msgid "" -"The offset in bytes that the member is located on the type’s object struct." -msgstr "" - -#: ../../c-api/structures.rst:608 -msgid "" -"Zero or more of the :ref:`PyMemberDef-flags`, combined using bitwise OR." -msgstr "" - -#: ../../c-api/structures.rst:612 -msgid "" -"The docstring, or NULL. The string should be static, no copy is made of it. " -"Typically, it is defined using :c:macro:`PyDoc_STR`." -msgstr "" - -#: ../../c-api/structures.rst:616 -msgid "" -"By default (when :c:member:`~PyMemberDef.flags` is ``0``), members allow " -"both read and write access. Use the :c:macro:`Py_READONLY` flag for read-" -"only access. Certain types, like :c:macro:`Py_T_STRING`, imply :c:macro:" -"`Py_READONLY`. Only :c:macro:`Py_T_OBJECT_EX` (and legacy :c:macro:" -"`T_OBJECT`) members can be deleted." -msgstr "" - -#: ../../c-api/structures.rst:625 -msgid "" -"For heap-allocated types (created using :c:func:`PyType_FromSpec` or " -"similar), ``PyMemberDef`` may contain a definition for the special member " -"``\"__vectorcalloffset__\"``, corresponding to :c:member:`~PyTypeObject." -"tp_vectorcall_offset` in type objects. This member must be defined with " -"``Py_T_PYSSIZET``, and either ``Py_READONLY`` or ``Py_READONLY | " -"Py_RELATIVE_OFFSET``. For example::" -msgstr "" - -#: ../../c-api/structures.rst:632 -msgid "" -"static PyMemberDef spam_type_members[] = {\n" -" {\"__vectorcalloffset__\", Py_T_PYSSIZET,\n" -" offsetof(Spam_object, vectorcall), Py_READONLY},\n" -" {NULL} /* Sentinel */\n" -"};" -msgstr "" -"static PyMemberDef spam_type_members[] = {\n" -" {\"__vectorcalloffset__\", Py_T_PYSSIZET,\n" -" offsetof(Spam_object, vectorcall), Py_READONLY},\n" -" {NULL} /* Sentinel */\n" -"};" - -#: ../../c-api/structures.rst:638 -msgid "(You may need to ``#include `` for :c:func:`!offsetof`.)" -msgstr "" - -#: ../../c-api/structures.rst:640 -msgid "" -"The legacy offsets :c:member:`~PyTypeObject.tp_dictoffset` and :c:member:" -"`~PyTypeObject.tp_weaklistoffset` can be defined similarly using " -"``\"__dictoffset__\"`` and ``\"__weaklistoffset__\"`` members, but " -"extensions are strongly encouraged to use :c:macro:`Py_TPFLAGS_MANAGED_DICT` " -"and :c:macro:`Py_TPFLAGS_MANAGED_WEAKREF` instead." -msgstr "" - -#: ../../c-api/structures.rst:648 -msgid "" -"``PyMemberDef`` is always available. Previously, it required including " -"``\"structmember.h\"``." -msgstr "" - -#: ../../c-api/structures.rst:653 -msgid "" -":c:macro:`Py_RELATIVE_OFFSET` is now allowed for " -"``\"__vectorcalloffset__\"``, ``\"__dictoffset__\"`` and " -"``\"__weaklistoffset__\"``." -msgstr "" - -#: ../../c-api/structures.rst:659 -msgid "" -"Get an attribute belonging to the object at address *obj_addr*. The " -"attribute is described by ``PyMemberDef`` *m*. Returns ``NULL`` on error." -msgstr "" - -#: ../../c-api/structures.rst:665 -msgid "" -"``PyMember_GetOne`` is always available. Previously, it required including " -"``\"structmember.h\"``." -msgstr "" - -#: ../../c-api/structures.rst:670 -msgid "" -"Set an attribute belonging to the object at address *obj_addr* to object " -"*o*. The attribute to set is described by ``PyMemberDef`` *m*. Returns " -"``0`` if successful and a negative value on failure." -msgstr "" - -#: ../../c-api/structures.rst:676 -msgid "" -"``PyMember_SetOne`` is always available. Previously, it required including " -"``\"structmember.h\"``." -msgstr "" - -#: ../../c-api/structures.rst:682 -msgid "Member flags" -msgstr "" - -#: ../../c-api/structures.rst:684 -msgid "The following flags can be used with :c:member:`PyMemberDef.flags`:" -msgstr "" - -#: ../../c-api/structures.rst:688 -msgid "Not writable." -msgstr "不可寫入。" - -#: ../../c-api/structures.rst:692 -msgid "" -"Emit an ``object.__getattr__`` :ref:`audit event ` before " -"reading." -msgstr "" - -#: ../../c-api/structures.rst:697 -msgid "" -"Indicates that the :c:member:`~PyMemberDef.offset` of this ``PyMemberDef`` " -"entry indicates an offset from the subclass-specific data, rather than from " -"``PyObject``." -msgstr "" - -#: ../../c-api/structures.rst:701 -msgid "" -"Can only be used as part of the :c:data:`Py_tp_members` :c:type:`slot " -"` when creating a class using negative :c:member:`~PyType_Spec." -"basicsize`. It is mandatory in that case. When setting :c:member:" -"`~PyTypeObject.tp_members` from the slot during class creation, Python " -"clears the flag and sets :c:member:`PyMemberDef.offset` to the offset from " -"the ``PyObject`` struct." -msgstr "" - -#: ../../c-api/structures.rst:716 -msgid "" -"The :c:macro:`!RESTRICTED`, :c:macro:`!READ_RESTRICTED` and :c:macro:`!" -"WRITE_RESTRICTED` macros available with ``#include \"structmember.h\"`` are " -"deprecated. :c:macro:`!READ_RESTRICTED` and :c:macro:`!RESTRICTED` are " -"equivalent to :c:macro:`Py_AUDIT_READ`; :c:macro:`!WRITE_RESTRICTED` does " -"nothing." -msgstr "" - -#: ../../c-api/structures.rst:727 -msgid "" -"The :c:macro:`!READONLY` macro was renamed to :c:macro:`Py_READONLY`. The :c:" -"macro:`!PY_AUDIT_READ` macro was renamed with the ``Py_`` prefix. The new " -"names are now always available. Previously, these required ``#include " -"\"structmember.h\"``. The header is still available and it provides the old " -"names." -msgstr "" - -#: ../../c-api/structures.rst:736 -msgid "Member types" -msgstr "" - -#: ../../c-api/structures.rst:738 -msgid "" -":c:member:`PyMemberDef.type` can be one of the following macros " -"corresponding to various C types. When the member is accessed in Python, it " -"will be converted to the equivalent Python type. When it is set from Python, " -"it will be converted back to the C type. If that is not possible, an " -"exception such as :exc:`TypeError` or :exc:`ValueError` is raised." -msgstr "" - -#: ../../c-api/structures.rst:746 -msgid "" -"Unless marked (D), attributes defined this way cannot be deleted using e.g. :" -"keyword:`del` or :py:func:`delattr`." -msgstr "" - -#: ../../c-api/structures.rst:750 -msgid "Macro name" -msgstr "巨集名稱" - -#: ../../c-api/structures.rst:750 -msgid "C type" -msgstr "" - -#: ../../c-api/structures.rst:750 -msgid "Python type" -msgstr "" - -#: ../../c-api/structures.rst:752 -msgid ":c:expr:`char`" -msgstr ":c:expr:`char`" - -#: ../../c-api/structures.rst:752 ../../c-api/structures.rst:753 -#: ../../c-api/structures.rst:754 ../../c-api/structures.rst:755 -#: ../../c-api/structures.rst:756 ../../c-api/structures.rst:757 -#: ../../c-api/structures.rst:758 ../../c-api/structures.rst:759 -#: ../../c-api/structures.rst:760 ../../c-api/structures.rst:761 -#: ../../c-api/structures.rst:762 -msgid ":py:class:`int`" -msgstr ":py:class:`int`" - -#: ../../c-api/structures.rst:753 -msgid ":c:expr:`short`" -msgstr ":c:expr:`short`" - -#: ../../c-api/structures.rst:754 -msgid ":c:expr:`int`" -msgstr ":c:expr:`int`" - -#: ../../c-api/structures.rst:755 -msgid ":c:expr:`long`" -msgstr ":c:expr:`long`" - -#: ../../c-api/structures.rst:756 -msgid ":c:expr:`long long`" -msgstr ":c:expr:`long long`" - -#: ../../c-api/structures.rst:757 -msgid ":c:expr:`unsigned char`" -msgstr ":c:expr:`unsigned char`" - -#: ../../c-api/structures.rst:758 -msgid ":c:expr:`unsigned int`" -msgstr ":c:expr:`unsigned int`" - -#: ../../c-api/structures.rst:759 -msgid ":c:expr:`unsigned short`" -msgstr ":c:expr:`unsigned short`" - -#: ../../c-api/structures.rst:760 -msgid ":c:expr:`unsigned long`" -msgstr ":c:expr:`unsigned long`" - -#: ../../c-api/structures.rst:761 -msgid ":c:expr:`unsigned long long`" -msgstr ":c:expr:`unsigned long long`" - -#: ../../c-api/structures.rst:762 -msgid ":c:expr:`Py_ssize_t`" -msgstr ":c:expr:`Py_ssize_t`" - -#: ../../c-api/structures.rst:763 -msgid ":c:expr:`float`" -msgstr ":c:expr:`float`" - -#: ../../c-api/structures.rst:763 ../../c-api/structures.rst:764 -msgid ":py:class:`float`" -msgstr ":py:class:`float`" - -#: ../../c-api/structures.rst:764 -msgid ":c:expr:`double`" -msgstr ":c:expr:`double`" - -#: ../../c-api/structures.rst:765 -msgid ":c:expr:`char` (written as 0 or 1)" -msgstr ":c:expr:`char` （寫成 0 或 1）" - -#: ../../c-api/structures.rst:765 -msgid ":py:class:`bool`" -msgstr ":py:class:`bool`" - -#: ../../c-api/structures.rst:767 -msgid ":c:expr:`const char *` (*)" -msgstr ":c:expr:`const char *` (*)" - -#: ../../c-api/structures.rst:767 ../../c-api/structures.rst:768 -msgid ":py:class:`str` (RO)" -msgstr ":py:class:`str` (RO)" - -#: ../../c-api/structures.rst:768 -msgid ":c:expr:`const char[]` (*)" -msgstr ":c:expr:`const char[]` (*)" - -#: ../../c-api/structures.rst:769 -msgid ":c:expr:`char` (0-127)" -msgstr ":c:expr:`char` (0-127)" - -#: ../../c-api/structures.rst:769 -msgid ":py:class:`str` (**)" -msgstr ":py:class:`str` (**)" - -#: ../../c-api/structures.rst:770 -msgid ":c:expr:`PyObject *`" -msgstr ":c:expr:`PyObject *`" - -#: ../../c-api/structures.rst:770 -msgid ":py:class:`object` (D)" -msgstr ":py:class:`object` (D)" - -#: ../../c-api/structures.rst:773 -msgid "" -"(*): Zero-terminated, UTF8-encoded C string. With :c:macro:`!Py_T_STRING` " -"the C representation is a pointer; with :c:macro:`!Py_T_STRING_INPLACE` the " -"string is stored directly in the structure." -msgstr "" - -#: ../../c-api/structures.rst:778 -msgid "(**): String of length 1. Only ASCII is accepted." -msgstr "" - -#: ../../c-api/structures.rst:780 -msgid "(RO): Implies :c:macro:`Py_READONLY`." -msgstr "" - -#: ../../c-api/structures.rst:782 -msgid "" -"(D): Can be deleted, in which case the pointer is set to ``NULL``. Reading a " -"``NULL`` pointer raises :py:exc:`AttributeError`." -msgstr "" - -#: ../../c-api/structures.rst:808 -msgid "" -"In previous versions, the macros were only available with ``#include " -"\"structmember.h\"`` and were named without the ``Py_`` prefix (e.g. as " -"``T_INT``). The header is still available and contains the old names, along " -"with the following deprecated types:" -msgstr "" - -#: ../../c-api/structures.rst:816 -msgid "" -"Like ``Py_T_OBJECT_EX``, but ``NULL`` is converted to ``None``. This results " -"in surprising behavior in Python: deleting the attribute effectively sets it " -"to ``None``." -msgstr "" - -#: ../../c-api/structures.rst:822 -msgid "Always ``None``. Must be used with :c:macro:`Py_READONLY`." -msgstr "" - -#: ../../c-api/structures.rst:825 -msgid "Defining Getters and Setters" -msgstr "" - -#: ../../c-api/structures.rst:829 -msgid "" -"Structure to define property-like access for a type. See also description of " -"the :c:member:`PyTypeObject.tp_getset` slot." -msgstr "" - -#: ../../c-api/structures.rst:834 -msgid "attribute name" -msgstr "屬性名稱" - -#: ../../c-api/structures.rst:838 -msgid "C function to get the attribute." -msgstr "" - -#: ../../c-api/structures.rst:842 -msgid "" -"Optional C function to set or delete the attribute. If ``NULL``, the " -"attribute is read-only." -msgstr "" - -#: ../../c-api/structures.rst:847 -msgid "optional docstring" -msgstr "可選的文件字串" - -#: ../../c-api/structures.rst:851 -msgid "" -"Optional user data pointer, providing additional data for getter and setter." -msgstr "" - -#: ../../c-api/structures.rst:855 -msgid "" -"The ``get`` function takes one :c:expr:`PyObject*` parameter (the instance) " -"and a user data pointer (the associated ``closure``):" -msgstr "" - -#: ../../c-api/structures.rst:858 -msgid "" -"It should return a new reference on success or ``NULL`` with a set exception " -"on failure." -msgstr "" - -#: ../../c-api/structures.rst:863 -msgid "" -"``set`` functions take two :c:expr:`PyObject*` parameters (the instance and " -"the value to be set) and a user data pointer (the associated ``closure``):" -msgstr "" - -#: ../../c-api/structures.rst:866 -msgid "" -"In case the attribute should be deleted the second parameter is ``NULL``. " -"Should return ``0`` on success or ``-1`` with a set exception on failure." -msgstr "" - -#: ../../c-api/structures.rst:418 ../../c-api/structures.rst:428 -msgid "built-in function" -msgstr "built-in function（內建函式）" - -#: ../../c-api/structures.rst:418 -msgid "classmethod" -msgstr "classmethod" - -#: ../../c-api/structures.rst:428 -msgid "staticmethod" -msgstr "staticmethod" - -#: ../../c-api/structures.rst:709 -msgid "READ_RESTRICTED (C macro)" -msgstr "READ_RESTRICTED（C 巨集）" - -#: ../../c-api/structures.rst:709 -msgid "WRITE_RESTRICTED (C macro)" -msgstr "WRITE_RESTRICTED（C 巨集）" - -#: ../../c-api/structures.rst:709 -msgid "RESTRICTED (C macro)" -msgstr "RESTRICTED（C 巨集）" - -#: ../../c-api/structures.rst:722 -msgid "READONLY (C macro)" -msgstr "READONLY（C 巨集）" - -#: ../../c-api/structures.rst:785 -msgid "T_BYTE (C macro)" -msgstr "T_BYTE（C 巨集）" - -#: ../../c-api/structures.rst:785 -msgid "T_SHORT (C macro)" -msgstr "T_SHORT（C 巨集）" - -#: ../../c-api/structures.rst:785 -msgid "T_INT (C macro)" -msgstr "T_INT（C 巨集）" - -#: ../../c-api/structures.rst:785 -msgid "T_LONG (C macro)" -msgstr "T_LONG（C 巨集）" - -#: ../../c-api/structures.rst:785 -msgid "T_LONGLONG (C macro)" -msgstr "T_LONGLONG（C 巨集）" - -#: ../../c-api/structures.rst:785 -msgid "T_UBYTE (C macro)" -msgstr "T_UBYTE（C 巨集）" - -#: ../../c-api/structures.rst:785 -msgid "T_USHORT (C macro)" -msgstr "T_USHORT（C 巨集）" - -#: ../../c-api/structures.rst:785 -msgid "T_UINT (C macro)" -msgstr "T_UINT（C 巨集）" - -#: ../../c-api/structures.rst:785 -msgid "T_ULONG (C macro)" -msgstr "T_ULONG（C 巨集）" - -#: ../../c-api/structures.rst:785 -msgid "T_ULONGULONG (C macro)" -msgstr "T_ULONGULONG（C 巨集）" - -#: ../../c-api/structures.rst:785 -msgid "T_PYSSIZET (C macro)" -msgstr "T_PYSSIZET（C 巨集）" - -#: ../../c-api/structures.rst:785 -msgid "T_FLOAT (C macro)" -msgstr "T_FLOAT（C 巨集）" - -#: ../../c-api/structures.rst:785 -msgid "T_DOUBLE (C macro)" -msgstr "T_DOUBLE（C 巨集）" - -#: ../../c-api/structures.rst:785 -msgid "T_BOOL (C macro)" -msgstr "T_BOOL（C 巨集）" - -#: ../../c-api/structures.rst:785 -msgid "T_CHAR (C macro)" -msgstr "T_CHAR（C 巨集）" - -#: ../../c-api/structures.rst:785 -msgid "T_STRING (C macro)" -msgstr "T_STRING（C 巨集）" - -#: ../../c-api/structures.rst:785 -msgid "T_STRING_INPLACE (C macro)" -msgstr "T_STRING_INPLACE（C 巨集）" - -#: ../../c-api/structures.rst:785 -msgid "T_OBJECT_EX (C macro)" -msgstr "T_OBJECT_EX（C 巨集）" - -#: ../../c-api/structures.rst:785 -msgid "structmember.h" -msgstr "structmember.h" - -#~ msgid "Set the object *o* type to *type*." -#~ msgstr "將物件 *o* 的型別設為 *type*。" - -#~ msgid "Get the size of the Python object *o*." -#~ msgstr "取得 Python 物件 *o* 的大小。" - -#~ msgid "Set the object *o* size to *size*." -#~ msgstr "將物件 *o* 的大小設為 *size*。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Leon H., 2017 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-20 00:14+0000\n" +"PO-Revision-Date: 2018-05-23 14: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" + +#: ../../c-api/structures.rst:6 +msgid "Common Object Structures" +msgstr "通用物件結構" + +#: ../../c-api/structures.rst:8 +msgid "" +"There are a large number of structures which are used in the definition of " +"object types for Python. This section describes these structures and how " +"they are used." +msgstr "" + +#: ../../c-api/structures.rst:14 +msgid "Base object types and macros" +msgstr "" + +#: ../../c-api/structures.rst:16 +msgid "" +"All Python objects ultimately share a small number of fields at the " +"beginning of the object's representation in memory. These are represented " +"by the :c:type:`PyObject` and :c:type:`PyVarObject` types, which are " +"defined, in turn, by the expansions of some macros also used, whether " +"directly or indirectly, in the definition of all other Python objects. " +"Additional macros can be found under :ref:`reference counting " +"`." +msgstr "" + +#: ../../c-api/structures.rst:26 +msgid "" +"All object types are extensions of this type. This is a type which contains " +"the information Python needs to treat a pointer to an object as an object. " +"In a normal \"release\" build, it contains only the object's reference count " +"and a pointer to the corresponding type object. Nothing is actually declared " +"to be a :c:type:`PyObject`, but every pointer to a Python object can be cast " +"to a :c:expr:`PyObject*`." +msgstr "" + +#: ../../c-api/structures.rst:33 +msgid "" +"The members must not be accessed directly; instead use macros such as :c:" +"macro:`Py_REFCNT` and :c:macro:`Py_TYPE`." +msgstr "" + +#: ../../c-api/structures.rst:38 +msgid "" +"The object's reference count, as returned by :c:macro:`Py_REFCNT`. Do not " +"use this field directly; instead use functions and macros such as :c:macro:`!" +"Py_REFCNT`, :c:func:`Py_INCREF` and :c:func:`Py_DecRef`." +msgstr "" + +#: ../../c-api/structures.rst:42 +msgid "" +"The field type may be different from ``Py_ssize_t``, depending on build " +"configuration and platform." +msgstr "" + +#: ../../c-api/structures.rst:47 +msgid "" +"The object's type. Do not use this field directly; use :c:macro:`Py_TYPE` " +"and :c:func:`Py_SET_TYPE` instead." +msgstr "" + +#: ../../c-api/structures.rst:54 +msgid "" +"An extension of :c:type:`PyObject` that adds the :c:member:`~PyVarObject." +"ob_size` field. This is intended for objects that have some notion of " +"*length*." +msgstr "" + +#: ../../c-api/structures.rst:58 +msgid "" +"As with :c:type:`!PyObject`, the members must not be accessed directly; " +"instead use macros such as :c:macro:`Py_SIZE`, :c:macro:`Py_REFCNT` and :c:" +"macro:`Py_TYPE`." +msgstr "" + +#: ../../c-api/structures.rst:64 +msgid "" +"A size field, whose contents should be considered an object's internal " +"implementation detail." +msgstr "" + +#: ../../c-api/structures.rst:67 +msgid "Do not use this field directly; use :c:macro:`Py_SIZE` instead." +msgstr "" + +#: ../../c-api/structures.rst:69 +msgid "" +"Object creation functions such as :c:func:`PyObject_NewVar` will generally " +"set this field to the requested size (number of items). After creation, " +"arbitrary values can be stored in :c:member:`!ob_size` using :c:macro:" +"`Py_SET_SIZE`." +msgstr "" + +#: ../../c-api/structures.rst:74 +msgid "" +"To get an object's publicly exposed length, as returned by the Python " +"function :py:func:`len`, use :c:func:`PyObject_Length` instead." +msgstr "" + +#: ../../c-api/structures.rst:81 +msgid "" +"This is a macro used when declaring new types which represent objects " +"without a varying length. The PyObject_HEAD macro expands to::" +msgstr "" + +#: ../../c-api/structures.rst:84 +msgid "PyObject ob_base;" +msgstr "PyObject ob_base;" + +#: ../../c-api/structures.rst:86 +msgid "See documentation of :c:type:`PyObject` above." +msgstr "請見上面 :c:type:`PyObject` 的文件。" + +#: ../../c-api/structures.rst:91 +msgid "" +"This is a macro used when declaring new types which represent objects with a " +"length that varies from instance to instance. The PyObject_VAR_HEAD macro " +"expands to::" +msgstr "" + +#: ../../c-api/structures.rst:95 +msgid "PyVarObject ob_base;" +msgstr "PyVarObject ob_base;" + +#: ../../c-api/structures.rst:97 +msgid "See documentation of :c:type:`PyVarObject` above." +msgstr "請見上面 :c:type:`PyVarObject` 的文件。" + +#: ../../c-api/structures.rst:102 +msgid "" +"The base class of all other objects, the same as :class:`object` in Python." +msgstr "" + +#: ../../c-api/structures.rst:107 +msgid "" +"Test if the *x* object is the *y* object, the same as ``x is y`` in Python." +msgstr "" + +#: ../../c-api/structures.rst:114 +msgid "" +"Test if an object is the ``None`` singleton, the same as ``x is None`` in " +"Python." +msgstr "" + +#: ../../c-api/structures.rst:122 +msgid "" +"Test if an object is the ``True`` singleton, the same as ``x is True`` in " +"Python." +msgstr "" + +#: ../../c-api/structures.rst:130 +msgid "" +"Test if an object is the ``False`` singleton, the same as ``x is False`` in " +"Python." +msgstr "" + +#: ../../c-api/structures.rst:138 +msgid "Get the type of the Python object *o*." +msgstr "" + +#: ../../c-api/structures.rst:140 +msgid "" +"The returned reference is :term:`borrowed ` from *o*. Do " +"not release it with :c:func:`Py_DECREF` or similar." +msgstr "" + +#: ../../c-api/structures.rst:143 +msgid "" +":c:func:`Py_TYPE()` is changed to an inline static function. The parameter " +"type is no longer :c:expr:`const PyObject*`." +msgstr "" + +#: ../../c-api/structures.rst:150 +msgid "" +"Return non-zero if the object *o* type is *type*. Return zero otherwise. " +"Equivalent to: ``Py_TYPE(o) == type``." +msgstr "" + +#: ../../c-api/structures.rst:158 +msgid "" +"Set the type of object *o* to *type*, without any checking or reference " +"counting." +msgstr "" + +#: ../../c-api/structures.rst:161 +msgid "" +"This is a very low-level operation. Consider instead setting the Python " +"attribute :attr:`~object.__class__` using :c:func:`PyObject_SetAttrString` " +"or similar." +msgstr "" + +#: ../../c-api/structures.rst:165 +msgid "" +"Note that assigning an incompatible type can lead to undefined behavior." +msgstr "" + +#: ../../c-api/structures.rst:167 +msgid "" +"If *type* is a :ref:`heap type `, the caller must create a new " +"reference to it. Similarly, if the old type of *o* is a heap type, the " +"caller must release a reference to that type." +msgstr "" + +#: ../../c-api/structures.rst:177 +msgid "Get the :c:member:`~PyVarObject.ob_size` field of *o*." +msgstr "" + +#: ../../c-api/structures.rst:179 +msgid "" +":c:func:`Py_SIZE()` is changed to an inline static function. The parameter " +"type is no longer :c:expr:`const PyVarObject*`." +msgstr "" + +#: ../../c-api/structures.rst:186 +msgid "Set the :c:member:`~PyVarObject.ob_size` field of *o* to *size*." +msgstr "" + +#: ../../c-api/structures.rst:193 +msgid "" +"This is a macro which expands to initialization values for a new :c:type:" +"`PyObject` type. This macro expands to::" +msgstr "" + +#: ../../c-api/structures.rst:196 +msgid "" +"_PyObject_EXTRA_INIT\n" +"1, type," +msgstr "" +"_PyObject_EXTRA_INIT\n" +"1, type," + +#: ../../c-api/structures.rst:202 +msgid "" +"This is a macro which expands to initialization values for a new :c:type:" +"`PyVarObject` type, including the :c:member:`~PyVarObject.ob_size` field. " +"This macro expands to::" +msgstr "" + +#: ../../c-api/structures.rst:206 +msgid "" +"_PyObject_EXTRA_INIT\n" +"1, type, size," +msgstr "" +"_PyObject_EXTRA_INIT\n" +"1, type, size," + +#: ../../c-api/structures.rst:211 +msgid "Implementing functions and methods" +msgstr "實作函式與方法" + +#: ../../c-api/structures.rst:215 +msgid "" +"Type of the functions used to implement most Python callables in C. " +"Functions of this type take two :c:expr:`PyObject*` parameters and return " +"one such value. If the return value is ``NULL``, an exception shall have " +"been set. If not ``NULL``, the return value is interpreted as the return " +"value of the function as exposed in Python. The function must return a new " +"reference." +msgstr "" + +#: ../../c-api/structures.rst:222 +msgid "The function signature is::" +msgstr "" + +#: ../../c-api/structures.rst:224 +msgid "" +"PyObject *PyCFunction(PyObject *self,\n" +" PyObject *args);" +msgstr "" +"PyObject *PyCFunction(PyObject *self,\n" +" PyObject *args);" + +#: ../../c-api/structures.rst:229 +msgid "" +"Type of the functions used to implement Python callables in C with " +"signature :ref:`METH_VARARGS | METH_KEYWORDS `. " +"The function signature is::" +msgstr "" + +#: ../../c-api/structures.rst:233 +msgid "" +"PyObject *PyCFunctionWithKeywords(PyObject *self,\n" +" PyObject *args,\n" +" PyObject *kwargs);" +msgstr "" +"PyObject *PyCFunctionWithKeywords(PyObject *self,\n" +" PyObject *args,\n" +" PyObject *kwargs);" + +#: ../../c-api/structures.rst:240 +msgid "" +"Type of the functions used to implement Python callables in C with " +"signature :c:macro:`METH_FASTCALL`. The function signature is::" +msgstr "" + +#: ../../c-api/structures.rst:244 +msgid "" +"PyObject *PyCFunctionFast(PyObject *self,\n" +" PyObject *const *args,\n" +" Py_ssize_t nargs);" +msgstr "" +"PyObject *PyCFunctionFast(PyObject *self,\n" +" PyObject *const *args,\n" +" Py_ssize_t nargs);" + +#: ../../c-api/structures.rst:250 +msgid "" +"Type of the functions used to implement Python callables in C with " +"signature :ref:`METH_FASTCALL | METH_KEYWORDS `. The function signature is::" +msgstr "" + +#: ../../c-api/structures.rst:254 +msgid "" +"PyObject *PyCFunctionFastWithKeywords(PyObject *self,\n" +" PyObject *const *args,\n" +" Py_ssize_t nargs,\n" +" PyObject *kwnames);" +msgstr "" +"PyObject *PyCFunctionFastWithKeywords(PyObject *self,\n" +" PyObject *const *args,\n" +" Py_ssize_t nargs,\n" +" PyObject *kwnames);" + +#: ../../c-api/structures.rst:261 +msgid "" +"Type of the functions used to implement Python callables in C with " +"signature :ref:`METH_METHOD | METH_FASTCALL | METH_KEYWORDS `. The function signature is::" +msgstr "" + +#: ../../c-api/structures.rst:265 +msgid "" +"PyObject *PyCMethod(PyObject *self,\n" +" PyTypeObject *defining_class,\n" +" PyObject *const *args,\n" +" Py_ssize_t nargs,\n" +" PyObject *kwnames)" +msgstr "" +"PyObject *PyCMethod(PyObject *self,\n" +" PyTypeObject *defining_class,\n" +" PyObject *const *args,\n" +" Py_ssize_t nargs,\n" +" PyObject *kwnames)" + +#: ../../c-api/structures.rst:276 +msgid "" +"Structure used to describe a method of an extension type. This structure " +"has four fields:" +msgstr "" + +#: ../../c-api/structures.rst:281 +msgid "Name of the method." +msgstr "" + +#: ../../c-api/structures.rst:285 +msgid "Pointer to the C implementation." +msgstr "" + +#: ../../c-api/structures.rst:289 +msgid "Flags bits indicating how the call should be constructed." +msgstr "" + +#: ../../c-api/structures.rst:293 +msgid "Points to the contents of the docstring." +msgstr "" + +#: ../../c-api/structures.rst:295 +msgid "" +"The :c:member:`~PyMethodDef.ml_meth` is a C function pointer. The functions " +"may be of different types, but they always return :c:expr:`PyObject*`. If " +"the function is not of the :c:type:`PyCFunction`, the compiler will require " +"a cast in the method table. Even though :c:type:`PyCFunction` defines the " +"first parameter as :c:expr:`PyObject*`, it is common that the method " +"implementation uses the specific C type of the *self* object." +msgstr "" + +#: ../../c-api/structures.rst:303 +msgid "" +"The :c:member:`~PyMethodDef.ml_flags` field is a bitfield which can include " +"the following flags. The individual flags indicate either a calling " +"convention or a binding convention." +msgstr "" + +#: ../../c-api/structures.rst:308 +msgid "There are these calling conventions:" +msgstr "" + +#: ../../c-api/structures.rst:312 +msgid "" +"This is the typical calling convention, where the methods have the type :c:" +"type:`PyCFunction`. The function expects two :c:expr:`PyObject*` values. The " +"first one is the *self* object for methods; for module functions, it is the " +"module object. The second parameter (often called *args*) is a tuple object " +"representing all arguments. This parameter is typically processed using :c:" +"func:`PyArg_ParseTuple` or :c:func:`PyArg_UnpackTuple`." +msgstr "" + +#: ../../c-api/structures.rst:322 +msgid "" +"Can only be used in certain combinations with other flags: :ref:" +"`METH_VARARGS | METH_KEYWORDS `, :ref:" +"`METH_FASTCALL | METH_KEYWORDS ` and :ref:" +"`METH_METHOD | METH_FASTCALL | METH_KEYWORDS `." +msgstr "" + +#: ../../c-api/structures.rst:330 +msgid ":c:expr:`METH_VARARGS | METH_KEYWORDS`" +msgstr ":c:expr:`METH_VARARGS | METH_KEYWORDS`" + +#: ../../c-api/structures.rst:331 +msgid "" +"Methods with these flags must be of type :c:type:`PyCFunctionWithKeywords`. " +"The function expects three parameters: *self*, *args*, *kwargs* where " +"*kwargs* is a dictionary of all the keyword arguments or possibly ``NULL`` " +"if there are no keyword arguments. The parameters are typically processed " +"using :c:func:`PyArg_ParseTupleAndKeywords`." +msgstr "" + +#: ../../c-api/structures.rst:340 +msgid "" +"Fast calling convention supporting only positional arguments. The methods " +"have the type :c:type:`PyCFunctionFast`. The first parameter is *self*, the " +"second parameter is a C array of :c:expr:`PyObject*` values indicating the " +"arguments and the third parameter is the number of arguments (the length of " +"the array)." +msgstr "" + +#: ../../c-api/structures.rst:350 +msgid "``METH_FASTCALL`` is now part of the :ref:`stable ABI `." +msgstr "" + +#: ../../c-api/structures.rst:355 +msgid ":c:expr:`METH_FASTCALL | METH_KEYWORDS`" +msgstr ":c:expr:`METH_FASTCALL | METH_KEYWORDS`" + +#: ../../c-api/structures.rst:356 +msgid "" +"Extension of :c:macro:`METH_FASTCALL` supporting also keyword arguments, " +"with methods of type :c:type:`PyCFunctionFastWithKeywords`. Keyword " +"arguments are passed the same way as in the :ref:`vectorcall protocol " +"`: there is an additional fourth :c:expr:`PyObject*` parameter " +"which is a tuple representing the names of the keyword arguments (which are " +"guaranteed to be strings) or possibly ``NULL`` if there are no keywords. " +"The values of the keyword arguments are stored in the *args* array, after " +"the positional arguments." +msgstr "" + +#: ../../c-api/structures.rst:371 +msgid "" +"Can only be used in the combination with other flags: :ref:`METH_METHOD | " +"METH_FASTCALL | METH_KEYWORDS `." +msgstr "" + +#: ../../c-api/structures.rst:377 +msgid ":c:expr:`METH_METHOD | METH_FASTCALL | METH_KEYWORDS`" +msgstr ":c:expr:`METH_METHOD | METH_FASTCALL | METH_KEYWORDS`" + +#: ../../c-api/structures.rst:378 +msgid "" +"Extension of :ref:`METH_FASTCALL | METH_KEYWORDS ` supporting the *defining class*, that is, the class that " +"contains the method in question. The defining class might be a superclass of " +"``Py_TYPE(self)``." +msgstr "" + +#: ../../c-api/structures.rst:383 +msgid "" +"The method needs to be of type :c:type:`PyCMethod`, the same as for " +"``METH_FASTCALL | METH_KEYWORDS`` with ``defining_class`` argument added " +"after ``self``." +msgstr "" + +#: ../../c-api/structures.rst:392 +msgid "" +"Methods without parameters don't need to check whether arguments are given " +"if they are listed with the :c:macro:`METH_NOARGS` flag. They need to be of " +"type :c:type:`PyCFunction`. The first parameter is typically named *self* " +"and will hold a reference to the module or object instance. In all cases " +"the second parameter will be ``NULL``." +msgstr "" + +#: ../../c-api/structures.rst:398 +msgid "" +"The function must have 2 parameters. Since the second parameter is unused, :" +"c:macro:`Py_UNUSED` can be used to prevent a compiler warning." +msgstr "" + +#: ../../c-api/structures.rst:404 +msgid "" +"Methods with a single object argument can be listed with the :c:macro:" +"`METH_O` flag, instead of invoking :c:func:`PyArg_ParseTuple` with a " +"``\"O\"`` argument. They have the type :c:type:`PyCFunction`, with the " +"*self* parameter, and a :c:expr:`PyObject*` parameter representing the " +"single argument." +msgstr "" + +#: ../../c-api/structures.rst:410 +msgid "" +"These two constants are not used to indicate the calling convention but the " +"binding when use with methods of classes. These may not be used for " +"functions defined for modules. At most one of these flags may be set for " +"any given method." +msgstr "" + +#: ../../c-api/structures.rst:420 +msgid "" +"The method will be passed the type object as the first parameter rather than " +"an instance of the type. This is used to create *class methods*, similar to " +"what is created when using the :func:`classmethod` built-in function." +msgstr "" + +#: ../../c-api/structures.rst:430 +msgid "" +"The method will be passed ``NULL`` as the first parameter rather than an " +"instance of the type. This is used to create *static methods*, similar to " +"what is created when using the :func:`staticmethod` built-in function." +msgstr "" + +#: ../../c-api/structures.rst:434 +msgid "" +"One other constant controls whether a method is loaded in place of another " +"definition with the same method name." +msgstr "" + +#: ../../c-api/structures.rst:440 +msgid "" +"The method will be loaded in place of existing definitions. Without " +"*METH_COEXIST*, the default is to skip repeated definitions. Since slot " +"wrappers are loaded before the method table, the existence of a " +"*sq_contains* slot, for example, would generate a wrapped method named :meth:" +"`~object.__contains__` and preclude the loading of a corresponding " +"PyCFunction with the same name. With the flag defined, the PyCFunction will " +"be loaded in place of the wrapper object and will co-exist with the slot. " +"This is helpful because calls to PyCFunctions are optimized more than " +"wrapper object calls." +msgstr "" + +#: ../../c-api/structures.rst:453 +msgid "" +"The type object corresponding to Python C method objects. This is available " +"as :class:`types.BuiltinMethodType` in the Python layer." +msgstr "" + +#: ../../c-api/structures.rst:459 +msgid "" +"Return true if *op* is an instance of the :c:type:`PyCMethod_Type` type or a " +"subtype of it. This function always succeeds." +msgstr "" + +#: ../../c-api/structures.rst:465 +msgid "" +"This is the same as :c:func:`PyCMethod_Check`, but does not account for " +"subtypes." +msgstr "" + +#: ../../c-api/structures.rst:471 +msgid "" +"Turn *ml* into a Python :term:`callable` object. The caller must ensure that " +"*ml* outlives the :term:`callable`. Typically, *ml* is defined as a static " +"variable." +msgstr "" + +#: ../../c-api/structures.rst:475 +msgid "" +"The *self* parameter will be passed as the *self* argument to the C function " +"in ``ml->ml_meth`` when invoked. *self* can be ``NULL``." +msgstr "" + +#: ../../c-api/structures.rst:479 +msgid "" +"The :term:`callable` object's ``__module__`` attribute can be set from the " +"given *module* argument. *module* should be a Python string, which will be " +"used as name of the module the function is defined in. If unavailable, it " +"can be set to :const:`None` or ``NULL``." +msgstr "" + +#: ../../c-api/structures.rst:485 +msgid ":attr:`function.__module__`" +msgstr ":attr:`function.__module__`" + +#: ../../c-api/structures.rst:487 +msgid "" +"The *cls* parameter will be passed as the *defining_class* argument to the C " +"function. Must be set if :c:macro:`METH_METHOD` is set on ``ml->ml_flags``." +msgstr "" + +#: ../../c-api/structures.rst:496 +msgid "" +"The type object corresponding to Python C function objects. This is " +"available as :class:`types.BuiltinFunctionType` in the Python layer." +msgstr "" + +#: ../../c-api/structures.rst:502 +msgid "" +"Return true if *op* is an instance of the :c:type:`PyCFunction_Type` type or " +"a subtype of it. This function always succeeds." +msgstr "" + +#: ../../c-api/structures.rst:508 +msgid "" +"This is the same as :c:func:`PyCFunction_Check`, but does not account for " +"subtypes." +msgstr "" + +#: ../../c-api/structures.rst:514 +msgid "Equivalent to ``PyCMethod_New(ml, self, module, NULL)``." +msgstr "等價於 ``PyCMethod_New(ml, self, module, NULL)``。" + +#: ../../c-api/structures.rst:519 +msgid "Equivalent to ``PyCMethod_New(ml, self, NULL, NULL)``." +msgstr "等價於 ``PyCMethod_New(ml, self, NULL, NULL)``。" + +#: ../../c-api/structures.rst:524 +msgid "" +"Get the function's flags on *func* as they were passed to :c:member:" +"`~PyMethodDef.ml_flags`." +msgstr "" + +#: ../../c-api/structures.rst:527 ../../c-api/structures.rst:545 +#: ../../c-api/structures.rst:565 +msgid "" +"If *func* is not a C function object, this fails with an exception. *func* " +"must not be ``NULL``." +msgstr "" + +#: ../../c-api/structures.rst:530 +msgid "" +"This function returns the function's flags on success, and ``-1`` with an " +"exception set on failure." +msgstr "" + +#: ../../c-api/structures.rst:536 +msgid "" +"This is the same as :c:func:`PyCFunction_GetFlags`, but without error or " +"type checking." +msgstr "" + +#: ../../c-api/structures.rst:542 +msgid "" +"Get the function pointer on *func* as it was passed to :c:member:" +"`~PyMethodDef.ml_meth`." +msgstr "" + +#: ../../c-api/structures.rst:548 +msgid "" +"This function returns the function pointer on success, and ``NULL`` with an " +"exception set on failure." +msgstr "" + +#: ../../c-api/structures.rst:554 +msgid "" +"This is the same as :c:func:`PyCFunction_GetFunction`, but without error or " +"type checking." +msgstr "" + +#: ../../c-api/structures.rst:560 +msgid "" +"Get the \"self\" object on *func*. This is the object that would be passed " +"to the first argument of a :c:type:`PyCFunction`. For C function objects " +"created through a :c:type:`PyMethodDef` on a :c:type:`PyModuleDef`, this is " +"the resulting module object." +msgstr "" + +#: ../../c-api/structures.rst:568 +msgid "" +"This function returns a :term:`borrowed reference` to the \"self\" object on " +"success, and ``NULL`` with an exception set on failure." +msgstr "" + +#: ../../c-api/structures.rst:574 +msgid "" +"This is the same as :c:func:`PyCFunction_GetSelf`, but without error or type " +"checking." +msgstr "" + +#: ../../c-api/structures.rst:579 +msgid "Accessing attributes of extension types" +msgstr "" + +#: ../../c-api/structures.rst:583 +msgid "" +"Structure which describes an attribute of a type which corresponds to a C " +"struct member. When defining a class, put a NULL-terminated array of these " +"structures in the :c:member:`~PyTypeObject.tp_members` slot." +msgstr "" + +#: ../../c-api/structures.rst:588 +msgid "Its fields are, in order:" +msgstr "" + +#: ../../c-api/structures.rst:592 +msgid "" +"Name of the member. A NULL value marks the end of a ``PyMemberDef[]`` array." +msgstr "" + +#: ../../c-api/structures.rst:595 +msgid "The string should be static, no copy is made of it." +msgstr "" + +#: ../../c-api/structures.rst:599 +msgid "" +"The type of the member in the C struct. See :ref:`PyMemberDef-types` for the " +"possible values." +msgstr "" + +#: ../../c-api/structures.rst:604 +msgid "" +"The offset in bytes that the member is located on the type’s object struct." +msgstr "" + +#: ../../c-api/structures.rst:608 +msgid "" +"Zero or more of the :ref:`PyMemberDef-flags`, combined using bitwise OR." +msgstr "" + +#: ../../c-api/structures.rst:612 +msgid "" +"The docstring, or NULL. The string should be static, no copy is made of it. " +"Typically, it is defined using :c:macro:`PyDoc_STR`." +msgstr "" + +#: ../../c-api/structures.rst:616 +msgid "" +"By default (when :c:member:`~PyMemberDef.flags` is ``0``), members allow " +"both read and write access. Use the :c:macro:`Py_READONLY` flag for read-" +"only access. Certain types, like :c:macro:`Py_T_STRING`, imply :c:macro:" +"`Py_READONLY`. Only :c:macro:`Py_T_OBJECT_EX` (and legacy :c:macro:" +"`T_OBJECT`) members can be deleted." +msgstr "" + +#: ../../c-api/structures.rst:625 +msgid "" +"For heap-allocated types (created using :c:func:`PyType_FromSpec` or " +"similar), ``PyMemberDef`` may contain a definition for the special member " +"``\"__vectorcalloffset__\"``, corresponding to :c:member:`~PyTypeObject." +"tp_vectorcall_offset` in type objects. This member must be defined with " +"``Py_T_PYSSIZET``, and either ``Py_READONLY`` or ``Py_READONLY | " +"Py_RELATIVE_OFFSET``. For example::" +msgstr "" + +#: ../../c-api/structures.rst:632 +msgid "" +"static PyMemberDef spam_type_members[] = {\n" +" {\"__vectorcalloffset__\", Py_T_PYSSIZET,\n" +" offsetof(Spam_object, vectorcall), Py_READONLY},\n" +" {NULL} /* Sentinel */\n" +"};" +msgstr "" +"static PyMemberDef spam_type_members[] = {\n" +" {\"__vectorcalloffset__\", Py_T_PYSSIZET,\n" +" offsetof(Spam_object, vectorcall), Py_READONLY},\n" +" {NULL} /* Sentinel */\n" +"};" + +#: ../../c-api/structures.rst:638 +msgid "(You may need to ``#include `` for :c:func:`!offsetof`.)" +msgstr "" + +#: ../../c-api/structures.rst:640 +msgid "" +"The legacy offsets :c:member:`~PyTypeObject.tp_dictoffset` and :c:member:" +"`~PyTypeObject.tp_weaklistoffset` can be defined similarly using " +"``\"__dictoffset__\"`` and ``\"__weaklistoffset__\"`` members, but " +"extensions are strongly encouraged to use :c:macro:`Py_TPFLAGS_MANAGED_DICT` " +"and :c:macro:`Py_TPFLAGS_MANAGED_WEAKREF` instead." +msgstr "" + +#: ../../c-api/structures.rst:648 +msgid "" +"``PyMemberDef`` is always available. Previously, it required including " +"``\"structmember.h\"``." +msgstr "" + +#: ../../c-api/structures.rst:653 +msgid "" +":c:macro:`Py_RELATIVE_OFFSET` is now allowed for " +"``\"__vectorcalloffset__\"``, ``\"__dictoffset__\"`` and " +"``\"__weaklistoffset__\"``." +msgstr "" + +#: ../../c-api/structures.rst:659 +msgid "" +"Get an attribute belonging to the object at address *obj_addr*. The " +"attribute is described by ``PyMemberDef`` *m*. Returns ``NULL`` on error." +msgstr "" + +#: ../../c-api/structures.rst:665 +msgid "" +"``PyMember_GetOne`` is always available. Previously, it required including " +"``\"structmember.h\"``." +msgstr "" + +#: ../../c-api/structures.rst:670 +msgid "" +"Set an attribute belonging to the object at address *obj_addr* to object " +"*o*. The attribute to set is described by ``PyMemberDef`` *m*. Returns " +"``0`` if successful and a negative value on failure." +msgstr "" + +#: ../../c-api/structures.rst:676 +msgid "" +"``PyMember_SetOne`` is always available. Previously, it required including " +"``\"structmember.h\"``." +msgstr "" + +#: ../../c-api/structures.rst:682 +msgid "Member flags" +msgstr "" + +#: ../../c-api/structures.rst:684 +msgid "The following flags can be used with :c:member:`PyMemberDef.flags`:" +msgstr "" + +#: ../../c-api/structures.rst:688 +msgid "Not writable." +msgstr "不可寫入。" + +#: ../../c-api/structures.rst:692 +msgid "" +"Emit an ``object.__getattr__`` :ref:`audit event ` before " +"reading." +msgstr "" + +#: ../../c-api/structures.rst:697 +msgid "" +"Indicates that the :c:member:`~PyMemberDef.offset` of this ``PyMemberDef`` " +"entry indicates an offset from the subclass-specific data, rather than from " +"``PyObject``." +msgstr "" + +#: ../../c-api/structures.rst:701 +msgid "" +"Can only be used as part of the :c:data:`Py_tp_members` :c:type:`slot " +"` when creating a class using negative :c:member:`~PyType_Spec." +"basicsize`. It is mandatory in that case. When setting :c:member:" +"`~PyTypeObject.tp_members` from the slot during class creation, Python " +"clears the flag and sets :c:member:`PyMemberDef.offset` to the offset from " +"the ``PyObject`` struct." +msgstr "" + +#: ../../c-api/structures.rst:716 +msgid "" +"The :c:macro:`!RESTRICTED`, :c:macro:`!READ_RESTRICTED` and :c:macro:`!" +"WRITE_RESTRICTED` macros available with ``#include \"structmember.h\"`` are " +"deprecated. :c:macro:`!READ_RESTRICTED` and :c:macro:`!RESTRICTED` are " +"equivalent to :c:macro:`Py_AUDIT_READ`; :c:macro:`!WRITE_RESTRICTED` does " +"nothing." +msgstr "" + +#: ../../c-api/structures.rst:727 +msgid "" +"The :c:macro:`!READONLY` macro was renamed to :c:macro:`Py_READONLY`. The :c:" +"macro:`!PY_AUDIT_READ` macro was renamed with the ``Py_`` prefix. The new " +"names are now always available. Previously, these required ``#include " +"\"structmember.h\"``. The header is still available and it provides the old " +"names." +msgstr "" + +#: ../../c-api/structures.rst:736 +msgid "Member types" +msgstr "" + +#: ../../c-api/structures.rst:738 +msgid "" +":c:member:`PyMemberDef.type` can be one of the following macros " +"corresponding to various C types. When the member is accessed in Python, it " +"will be converted to the equivalent Python type. When it is set from Python, " +"it will be converted back to the C type. If that is not possible, an " +"exception such as :exc:`TypeError` or :exc:`ValueError` is raised." +msgstr "" + +#: ../../c-api/structures.rst:746 +msgid "" +"Unless marked (D), attributes defined this way cannot be deleted using e.g. :" +"keyword:`del` or :py:func:`delattr`." +msgstr "" + +#: ../../c-api/structures.rst:750 +msgid "Macro name" +msgstr "巨集名稱" + +#: ../../c-api/structures.rst:750 +msgid "C type" +msgstr "" + +#: ../../c-api/structures.rst:750 +msgid "Python type" +msgstr "" + +#: ../../c-api/structures.rst:752 +msgid ":c:expr:`char`" +msgstr ":c:expr:`char`" + +#: ../../c-api/structures.rst:752 ../../c-api/structures.rst:753 +#: ../../c-api/structures.rst:754 ../../c-api/structures.rst:755 +#: ../../c-api/structures.rst:756 ../../c-api/structures.rst:757 +#: ../../c-api/structures.rst:758 ../../c-api/structures.rst:759 +#: ../../c-api/structures.rst:760 ../../c-api/structures.rst:761 +#: ../../c-api/structures.rst:762 +msgid ":py:class:`int`" +msgstr ":py:class:`int`" + +#: ../../c-api/structures.rst:753 +msgid ":c:expr:`short`" +msgstr ":c:expr:`short`" + +#: ../../c-api/structures.rst:754 +msgid ":c:expr:`int`" +msgstr ":c:expr:`int`" + +#: ../../c-api/structures.rst:755 +msgid ":c:expr:`long`" +msgstr ":c:expr:`long`" + +#: ../../c-api/structures.rst:756 +msgid ":c:expr:`long long`" +msgstr ":c:expr:`long long`" + +#: ../../c-api/structures.rst:757 +msgid ":c:expr:`unsigned char`" +msgstr ":c:expr:`unsigned char`" + +#: ../../c-api/structures.rst:758 +msgid ":c:expr:`unsigned int`" +msgstr ":c:expr:`unsigned int`" + +#: ../../c-api/structures.rst:759 +msgid ":c:expr:`unsigned short`" +msgstr ":c:expr:`unsigned short`" + +#: ../../c-api/structures.rst:760 +msgid ":c:expr:`unsigned long`" +msgstr ":c:expr:`unsigned long`" + +#: ../../c-api/structures.rst:761 +msgid ":c:expr:`unsigned long long`" +msgstr ":c:expr:`unsigned long long`" + +#: ../../c-api/structures.rst:762 +msgid ":c:expr:`Py_ssize_t`" +msgstr ":c:expr:`Py_ssize_t`" + +#: ../../c-api/structures.rst:763 +msgid ":c:expr:`float`" +msgstr ":c:expr:`float`" + +#: ../../c-api/structures.rst:763 ../../c-api/structures.rst:764 +msgid ":py:class:`float`" +msgstr ":py:class:`float`" + +#: ../../c-api/structures.rst:764 +msgid ":c:expr:`double`" +msgstr ":c:expr:`double`" + +#: ../../c-api/structures.rst:765 +msgid ":c:expr:`char` (written as 0 or 1)" +msgstr ":c:expr:`char` （寫成 0 或 1）" + +#: ../../c-api/structures.rst:765 +msgid ":py:class:`bool`" +msgstr ":py:class:`bool`" + +#: ../../c-api/structures.rst:767 +msgid ":c:expr:`const char *` (*)" +msgstr ":c:expr:`const char *` (*)" + +#: ../../c-api/structures.rst:767 ../../c-api/structures.rst:768 +msgid ":py:class:`str` (RO)" +msgstr ":py:class:`str` (RO)" + +#: ../../c-api/structures.rst:768 +msgid ":c:expr:`const char[]` (*)" +msgstr ":c:expr:`const char[]` (*)" + +#: ../../c-api/structures.rst:769 +msgid ":c:expr:`char` (0-127)" +msgstr ":c:expr:`char` (0-127)" + +#: ../../c-api/structures.rst:769 +msgid ":py:class:`str` (**)" +msgstr ":py:class:`str` (**)" + +#: ../../c-api/structures.rst:770 +msgid ":c:expr:`PyObject *`" +msgstr ":c:expr:`PyObject *`" + +#: ../../c-api/structures.rst:770 +msgid ":py:class:`object` (D)" +msgstr ":py:class:`object` (D)" + +#: ../../c-api/structures.rst:773 +msgid "" +"(*): Zero-terminated, UTF8-encoded C string. With :c:macro:`!Py_T_STRING` " +"the C representation is a pointer; with :c:macro:`!Py_T_STRING_INPLACE` the " +"string is stored directly in the structure." +msgstr "" + +#: ../../c-api/structures.rst:778 +msgid "(**): String of length 1. Only ASCII is accepted." +msgstr "" + +#: ../../c-api/structures.rst:780 +msgid "(RO): Implies :c:macro:`Py_READONLY`." +msgstr "" + +#: ../../c-api/structures.rst:782 +msgid "" +"(D): Can be deleted, in which case the pointer is set to ``NULL``. Reading a " +"``NULL`` pointer raises :py:exc:`AttributeError`." +msgstr "" + +#: ../../c-api/structures.rst:808 +msgid "" +"In previous versions, the macros were only available with ``#include " +"\"structmember.h\"`` and were named without the ``Py_`` prefix (e.g. as " +"``T_INT``). The header is still available and contains the old names, along " +"with the following deprecated types:" +msgstr "" + +#: ../../c-api/structures.rst:816 +msgid "" +"Like ``Py_T_OBJECT_EX``, but ``NULL`` is converted to ``None``. This results " +"in surprising behavior in Python: deleting the attribute effectively sets it " +"to ``None``." +msgstr "" + +#: ../../c-api/structures.rst:822 +msgid "Always ``None``. Must be used with :c:macro:`Py_READONLY`." +msgstr "" + +#: ../../c-api/structures.rst:825 +msgid "Defining Getters and Setters" +msgstr "" + +#: ../../c-api/structures.rst:829 +msgid "" +"Structure to define property-like access for a type. See also description of " +"the :c:member:`PyTypeObject.tp_getset` slot." +msgstr "" + +#: ../../c-api/structures.rst:834 +msgid "attribute name" +msgstr "屬性名稱" + +#: ../../c-api/structures.rst:838 +msgid "C function to get the attribute." +msgstr "" + +#: ../../c-api/structures.rst:842 +msgid "" +"Optional C function to set or delete the attribute. If ``NULL``, the " +"attribute is read-only." +msgstr "" + +#: ../../c-api/structures.rst:847 +msgid "optional docstring" +msgstr "可選的文件字串" + +#: ../../c-api/structures.rst:851 +msgid "" +"Optional user data pointer, providing additional data for getter and setter." +msgstr "" + +#: ../../c-api/structures.rst:855 +msgid "" +"The ``get`` function takes one :c:expr:`PyObject*` parameter (the instance) " +"and a user data pointer (the associated ``closure``):" +msgstr "" + +#: ../../c-api/structures.rst:858 +msgid "" +"It should return a new reference on success or ``NULL`` with a set exception " +"on failure." +msgstr "" + +#: ../../c-api/structures.rst:863 +msgid "" +"``set`` functions take two :c:expr:`PyObject*` parameters (the instance and " +"the value to be set) and a user data pointer (the associated ``closure``):" +msgstr "" + +#: ../../c-api/structures.rst:866 +msgid "" +"In case the attribute should be deleted the second parameter is ``NULL``. " +"Should return ``0`` on success or ``-1`` with a set exception on failure." +msgstr "" + +#: ../../c-api/structures.rst:418 ../../c-api/structures.rst:428 +msgid "built-in function" +msgstr "built-in function（內建函式）" + +#: ../../c-api/structures.rst:418 +msgid "classmethod" +msgstr "classmethod" + +#: ../../c-api/structures.rst:428 +msgid "staticmethod" +msgstr "staticmethod" + +#: ../../c-api/structures.rst:709 +msgid "READ_RESTRICTED (C macro)" +msgstr "READ_RESTRICTED（C 巨集）" + +#: ../../c-api/structures.rst:709 +msgid "WRITE_RESTRICTED (C macro)" +msgstr "WRITE_RESTRICTED（C 巨集）" + +#: ../../c-api/structures.rst:709 +msgid "RESTRICTED (C macro)" +msgstr "RESTRICTED（C 巨集）" + +#: ../../c-api/structures.rst:722 +msgid "READONLY (C macro)" +msgstr "READONLY（C 巨集）" + +#: ../../c-api/structures.rst:785 +msgid "T_BYTE (C macro)" +msgstr "T_BYTE（C 巨集）" + +#: ../../c-api/structures.rst:785 +msgid "T_SHORT (C macro)" +msgstr "T_SHORT（C 巨集）" + +#: ../../c-api/structures.rst:785 +msgid "T_INT (C macro)" +msgstr "T_INT（C 巨集）" + +#: ../../c-api/structures.rst:785 +msgid "T_LONG (C macro)" +msgstr "T_LONG（C 巨集）" + +#: ../../c-api/structures.rst:785 +msgid "T_LONGLONG (C macro)" +msgstr "T_LONGLONG（C 巨集）" + +#: ../../c-api/structures.rst:785 +msgid "T_UBYTE (C macro)" +msgstr "T_UBYTE（C 巨集）" + +#: ../../c-api/structures.rst:785 +msgid "T_USHORT (C macro)" +msgstr "T_USHORT（C 巨集）" + +#: ../../c-api/structures.rst:785 +msgid "T_UINT (C macro)" +msgstr "T_UINT（C 巨集）" + +#: ../../c-api/structures.rst:785 +msgid "T_ULONG (C macro)" +msgstr "T_ULONG（C 巨集）" + +#: ../../c-api/structures.rst:785 +msgid "T_ULONGULONG (C macro)" +msgstr "T_ULONGULONG（C 巨集）" + +#: ../../c-api/structures.rst:785 +msgid "T_PYSSIZET (C macro)" +msgstr "T_PYSSIZET（C 巨集）" + +#: ../../c-api/structures.rst:785 +msgid "T_FLOAT (C macro)" +msgstr "T_FLOAT（C 巨集）" + +#: ../../c-api/structures.rst:785 +msgid "T_DOUBLE (C macro)" +msgstr "T_DOUBLE（C 巨集）" + +#: ../../c-api/structures.rst:785 +msgid "T_BOOL (C macro)" +msgstr "T_BOOL（C 巨集）" + +#: ../../c-api/structures.rst:785 +msgid "T_CHAR (C macro)" +msgstr "T_CHAR（C 巨集）" + +#: ../../c-api/structures.rst:785 +msgid "T_STRING (C macro)" +msgstr "T_STRING（C 巨集）" + +#: ../../c-api/structures.rst:785 +msgid "T_STRING_INPLACE (C macro)" +msgstr "T_STRING_INPLACE（C 巨集）" + +#: ../../c-api/structures.rst:785 +msgid "T_OBJECT_EX (C macro)" +msgstr "T_OBJECT_EX（C 巨集）" + +#: ../../c-api/structures.rst:785 +msgid "structmember.h" +msgstr "structmember.h" + +#~ msgid "Set the object *o* type to *type*." +#~ msgstr "將物件 *o* 的型別設為 *type*。" + +#~ msgid "Get the size of the Python object *o*." +#~ msgstr "取得 Python 物件 *o* 的大小。" + +#~ msgid "Set the object *o* size to *size*." +#~ msgstr "將物件 *o* 的大小設為 *size*。" diff --git a/c-api/sys.po b/c-api/sys.po index 40e4b155f5..a23c9ac3c3 100644 --- a/c-api/sys.po +++ b/c-api/sys.po @@ -1,578 +1,578 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Ching-Lung Chuang, 2015 -# Leon H., 2017 -# Liang-Bo Wang , 2015 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-14 19:37+0000\n" -"PO-Revision-Date: 2018-05-23 14: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" - -#: ../../c-api/sys.rst:6 -msgid "Operating System Utilities" -msgstr "作業系統工具" - -#: ../../c-api/sys.rst:11 -msgid "" -"Return the file system representation for *path*. If the object is a :class:" -"`str` or :class:`bytes` object, then a new :term:`strong reference` is " -"returned. If the object implements the :class:`os.PathLike` interface, then :" -"meth:`~os.PathLike.__fspath__` is returned as long as it is a :class:`str` " -"or :class:`bytes` object. Otherwise :exc:`TypeError` is raised and ``NULL`` " -"is returned." -msgstr "" - -#: ../../c-api/sys.rst:24 -msgid "" -"Return true (nonzero) if the standard I/O file *fp* with name *filename* is " -"deemed interactive. This is the case for files for which " -"``isatty(fileno(fp))`` is true. If the :c:member:`PyConfig.interactive` is " -"non-zero, this function also returns true if the *filename* pointer is " -"``NULL`` or if the name is equal to one of the strings ``''`` or " -"``'???'``." -msgstr "" - -#: ../../c-api/sys.rst:30 -msgid "This function must not be called before Python is initialized." -msgstr "" - -#: ../../c-api/sys.rst:35 -msgid "" -"Function to prepare some internal state before a process fork. This should " -"be called before calling :c:func:`fork` or any similar function that clones " -"the current process. Only available on systems where :c:func:`fork` is " -"defined." -msgstr "" - -#: ../../c-api/sys.rst:41 -msgid "" -"The C :c:func:`fork` call should only be made from the :ref:`\"main\" thread " -"` (of the :ref:`\"main\" interpreter `). The same is true for ``PyOS_BeforeFork()``." -msgstr "" - -#: ../../c-api/sys.rst:51 -msgid "" -"Function to update some internal state after a process fork. This should be " -"called from the parent process after calling :c:func:`fork` or any similar " -"function that clones the current process, regardless of whether process " -"cloning was successful. Only available on systems where :c:func:`fork` is " -"defined." -msgstr "" - -#: ../../c-api/sys.rst:58 -msgid "" -"The C :c:func:`fork` call should only be made from the :ref:`\"main\" thread " -"` (of the :ref:`\"main\" interpreter `). The same is true for ``PyOS_AfterFork_Parent()``." -msgstr "" - -#: ../../c-api/sys.rst:68 -msgid "" -"Function to update internal interpreter state after a process fork. This " -"must be called from the child process after calling :c:func:`fork`, or any " -"similar function that clones the current process, if there is any chance the " -"process will call back into the Python interpreter. Only available on " -"systems where :c:func:`fork` is defined." -msgstr "" - -#: ../../c-api/sys.rst:75 -msgid "" -"The C :c:func:`fork` call should only be made from the :ref:`\"main\" thread " -"` (of the :ref:`\"main\" interpreter `). The same is true for ``PyOS_AfterFork_Child()``." -msgstr "" - -#: ../../c-api/sys.rst:83 -msgid "" -":func:`os.register_at_fork` allows registering custom Python functions to be " -"called by :c:func:`PyOS_BeforeFork()`, :c:func:`PyOS_AfterFork_Parent` and :" -"c:func:`PyOS_AfterFork_Child`." -msgstr "" - -#: ../../c-api/sys.rst:90 -msgid "" -"Function to update some internal state after a process fork; this should be " -"called in the new process if the Python interpreter will continue to be " -"used. If a new executable is loaded into the new process, this function does " -"not need to be called." -msgstr "" - -#: ../../c-api/sys.rst:95 -msgid "This function is superseded by :c:func:`PyOS_AfterFork_Child()`." -msgstr "" - -#: ../../c-api/sys.rst:103 -msgid "" -"Return true when the interpreter runs out of stack space. This is a " -"reliable check, but is only available when :c:macro:`!USE_STACKCHECK` is " -"defined (currently on certain versions of Windows using the Microsoft Visual " -"C++ compiler). :c:macro:`!USE_STACKCHECK` will be defined automatically; you " -"should never change the definition in your own code." -msgstr "" - -#: ../../c-api/sys.rst:115 -msgid "" -"Return the current signal handler for signal *i*. This is a thin wrapper " -"around either :c:func:`!sigaction` or :c:func:`!signal`. Do not call those " -"functions directly!" -msgstr "" - -#: ../../c-api/sys.rst:122 -msgid "" -"Set the signal handler for signal *i* to be *h*; return the old signal " -"handler. This is a thin wrapper around either :c:func:`!sigaction` or :c:" -"func:`!signal`. Do not call those functions directly!" -msgstr "" - -#: ../../c-api/sys.rst:129 -msgid "Check if a :c:macro:`!SIGINT` signal has been received." -msgstr "" - -#: ../../c-api/sys.rst:131 -msgid "" -"Returns ``1`` if a :c:macro:`!SIGINT` has occurred and clears the signal " -"flag, or ``0`` otherwise." -msgstr "" - -#: ../../c-api/sys.rst:134 -msgid "" -"In most cases, you should prefer :c:func:`PyErr_CheckSignals` over this " -"function. :c:func:`!PyErr_CheckSignals` invokes the appropriate signal " -"handlers for all pending signals, allowing Python code to handle the signal " -"properly. This function only detects :c:macro:`!SIGINT` and does not invoke " -"any Python signal handlers." -msgstr "" - -#: ../../c-api/sys.rst:140 -msgid "" -"This function is async-signal-safe and this function cannot fail. The caller " -"must hold an :term:`attached thread state`." -msgstr "" - -#: ../../c-api/sys.rst:147 -msgid "" -"This function should not be called directly: use the :c:type:`PyConfig` API " -"with the :c:func:`PyConfig_SetBytesString` function which ensures that :ref:" -"`Python is preinitialized `." -msgstr "" - -#: ../../c-api/sys.rst:151 ../../c-api/sys.rst:218 -msgid "" -"This function must not be called before :ref:`Python is preinitialized ` and so that the LC_CTYPE locale is properly configured: see the :c:" -"func:`Py_PreInitialize` function." -msgstr "" - -#: ../../c-api/sys.rst:155 -msgid "" -"Decode a byte string from the :term:`filesystem encoding and error handler`. " -"If the error handler is :ref:`surrogateescape error handler " -"`, undecodable bytes are decoded as characters in range " -"U+DC80..U+DCFF; and if a byte sequence can be decoded as a surrogate " -"character, the bytes are escaped using the surrogateescape error handler " -"instead of decoding them." -msgstr "" - -#: ../../c-api/sys.rst:162 -msgid "" -"Return a pointer to a newly allocated wide character string, use :c:func:" -"`PyMem_RawFree` to free the memory. If size is not ``NULL``, write the " -"number of wide characters excluding the null character into ``*size``" -msgstr "" - -#: ../../c-api/sys.rst:166 -msgid "" -"Return ``NULL`` on decoding error or memory allocation error. If *size* is " -"not ``NULL``, ``*size`` is set to ``(size_t)-1`` on memory error or set to " -"``(size_t)-2`` on decoding error." -msgstr "" - -#: ../../c-api/sys.rst:170 ../../c-api/sys.rst:210 -msgid "" -"The :term:`filesystem encoding and error handler` are selected by :c:func:" -"`PyConfig_Read`: see :c:member:`~PyConfig.filesystem_encoding` and :c:member:" -"`~PyConfig.filesystem_errors` members of :c:type:`PyConfig`." -msgstr "" - -#: ../../c-api/sys.rst:174 -msgid "" -"Decoding errors should never happen, unless there is a bug in the C library." -msgstr "" - -#: ../../c-api/sys.rst:177 -msgid "" -"Use the :c:func:`Py_EncodeLocale` function to encode the character string " -"back to a byte string." -msgstr "" - -#: ../../c-api/sys.rst:182 -msgid "" -"The :c:func:`PyUnicode_DecodeFSDefaultAndSize` and :c:func:" -"`PyUnicode_DecodeLocaleAndSize` functions." -msgstr "" - -#: ../../c-api/sys.rst:187 ../../c-api/sys.rst:229 -msgid "" -"The function now uses the UTF-8 encoding in the :ref:`Python UTF-8 Mode " -"`." -msgstr "" - -#: ../../c-api/sys.rst:191 -msgid "" -"The function now uses the UTF-8 encoding on Windows if :c:member:" -"`PyPreConfig.legacy_windows_fs_encoding` is zero;" -msgstr "" - -#: ../../c-api/sys.rst:198 -msgid "" -"Encode a wide character string to the :term:`filesystem encoding and error " -"handler`. If the error handler is :ref:`surrogateescape error handler " -"`, surrogate characters in the range U+DC80..U+DCFF are " -"converted to bytes 0x80..0xFF." -msgstr "" - -#: ../../c-api/sys.rst:203 -msgid "" -"Return a pointer to a newly allocated byte string, use :c:func:`PyMem_Free` " -"to free the memory. Return ``NULL`` on encoding error or memory allocation " -"error." -msgstr "" - -#: ../../c-api/sys.rst:207 -msgid "" -"If error_pos is not ``NULL``, ``*error_pos`` is set to ``(size_t)-1`` on " -"success, or set to the index of the invalid character on encoding error." -msgstr "" - -#: ../../c-api/sys.rst:214 -msgid "" -"Use the :c:func:`Py_DecodeLocale` function to decode the bytes string back " -"to a wide character string." -msgstr "" - -#: ../../c-api/sys.rst:224 -msgid "" -"The :c:func:`PyUnicode_EncodeFSDefault` and :c:func:`PyUnicode_EncodeLocale` " -"functions." -msgstr "" - -#: ../../c-api/sys.rst:233 -msgid "" -"The function now uses the UTF-8 encoding on Windows if :c:member:" -"`PyPreConfig.legacy_windows_fs_encoding` is zero." -msgstr "" - -#: ../../c-api/sys.rst:239 -msgid "" -"Similar to :c:func:`!fopen`, but *path* is a Python object and an exception " -"is set on error." -msgstr "" - -#: ../../c-api/sys.rst:242 -msgid "" -"*path* must be a :class:`str` object, a :class:`bytes` object, or a :term:" -"`path-like object`." -msgstr "" - -#: ../../c-api/sys.rst:245 -msgid "" -"On success, return the new file pointer. On error, set an exception and " -"return ``NULL``." -msgstr "" - -#: ../../c-api/sys.rst:248 -msgid "" -"The file must be closed by :c:func:`Py_fclose` rather than calling directly :" -"c:func:`!fclose`." -msgstr "" - -#: ../../c-api/sys.rst:251 -msgid "The file descriptor is created non-inheritable (:pep:`446`)." -msgstr "" - -#: ../../c-api/sys.rst:253 -msgid "The caller must have an :term:`attached thread state`." -msgstr "" - -#: ../../c-api/sys.rst:260 -msgid "Close a file that was opened by :c:func:`Py_fopen`." -msgstr "" - -#: ../../c-api/sys.rst:262 -msgid "" -"On success, return ``0``. On error, return ``EOF`` and ``errno`` is set to " -"indicate the error. In either case, any further access (including another " -"call to :c:func:`Py_fclose`) to the stream results in undefined behavior." -msgstr "" - -#: ../../c-api/sys.rst:273 -msgid "System Functions" -msgstr "系統函式" - -#: ../../c-api/sys.rst:275 -msgid "" -"These are utility functions that make functionality from the :mod:`sys` " -"module accessible to C code. They all work with the current interpreter " -"thread's :mod:`sys` module's dict, which is contained in the internal thread " -"state structure." -msgstr "" - -#: ../../c-api/sys.rst:281 -msgid "" -"Return the object *name* from the :mod:`sys` module or ``NULL`` if it does " -"not exist, without setting an exception." -msgstr "" - -#: ../../c-api/sys.rst:286 -msgid "" -"Set *name* in the :mod:`sys` module to *v* unless *v* is ``NULL``, in which " -"case *name* is deleted from the sys module. Returns ``0`` on success, ``-1`` " -"on error." -msgstr "" - -#: ../../c-api/sys.rst:292 -msgid "" -"Reset :data:`sys.warnoptions` to an empty list. This function may be called " -"prior to :c:func:`Py_Initialize`." -msgstr "" - -#: ../../c-api/sys.rst:295 -msgid "Clear :data:`sys.warnoptions` and :data:`!warnings.filters` instead." -msgstr "" - -#: ../../c-api/sys.rst:300 -msgid "" -"Write the output string described by *format* to :data:`sys.stdout`. No " -"exceptions are raised, even if truncation occurs (see below)." -msgstr "" - -#: ../../c-api/sys.rst:303 -msgid "" -"*format* should limit the total size of the formatted output string to 1000 " -"bytes or less -- after 1000 bytes, the output string is truncated. In " -"particular, this means that no unrestricted \"%s\" formats should occur; " -"these should be limited using \"%.s\" where is a decimal number " -"calculated so that plus the maximum size of other formatted text does " -"not exceed 1000 bytes. Also watch out for \"%f\", which can print hundreds " -"of digits for very large numbers." -msgstr "" - -#: ../../c-api/sys.rst:311 -msgid "" -"If a problem occurs, or :data:`sys.stdout` is unset, the formatted message " -"is written to the real (C level) *stdout*." -msgstr "" - -#: ../../c-api/sys.rst:316 -msgid "" -"As :c:func:`PySys_WriteStdout`, but write to :data:`sys.stderr` or *stderr* " -"instead." -msgstr "" - -#: ../../c-api/sys.rst:321 -msgid "" -"Function similar to PySys_WriteStdout() but format the message using :c:func:" -"`PyUnicode_FromFormatV` and don't truncate the message to an arbitrary " -"length." -msgstr "" - -#: ../../c-api/sys.rst:329 -msgid "" -"As :c:func:`PySys_FormatStdout`, but write to :data:`sys.stderr` or *stderr* " -"instead." -msgstr "" - -#: ../../c-api/sys.rst:336 -msgid "" -"Return the current dictionary of :option:`-X` options, similarly to :data:" -"`sys._xoptions`. On error, ``NULL`` is returned and an exception is set." -msgstr "" - -#: ../../c-api/sys.rst:345 -msgid "" -"Raise an auditing event with any active hooks. Return zero for success and " -"non-zero with an exception set on failure." -msgstr "" - -#: ../../c-api/sys.rst:348 -msgid "The *event* string argument must not be *NULL*." -msgstr "" - -#: ../../c-api/sys.rst:350 -msgid "" -"If any hooks have been added, *format* and other arguments will be used to " -"construct a tuple to pass. Apart from ``N``, the same format characters as " -"used in :c:func:`Py_BuildValue` are available. If the built value is not a " -"tuple, it will be added into a single-element tuple." -msgstr "" - -#: ../../c-api/sys.rst:355 -msgid "" -"The ``N`` format option must not be used. It consumes a reference, but since " -"there is no way to know whether arguments to this function will be consumed, " -"using it may cause reference leaks." -msgstr "" - -#: ../../c-api/sys.rst:359 -msgid "" -"Note that ``#`` format characters should always be treated as :c:type:" -"`Py_ssize_t`, regardless of whether ``PY_SSIZE_T_CLEAN`` was defined." -msgstr "" - -#: ../../c-api/sys.rst:362 -msgid ":func:`sys.audit` performs the same function from Python code." -msgstr "" - -#: ../../c-api/sys.rst:364 -msgid "See also :c:func:`PySys_AuditTuple`." -msgstr "請參閱 :c:func:`PySys_AuditTuple`。" - -#: ../../c-api/sys.rst:370 -msgid "" -"Require :c:type:`Py_ssize_t` for ``#`` format characters. Previously, an " -"unavoidable deprecation warning was raised." -msgstr "" - -#: ../../c-api/sys.rst:376 -msgid "" -"Similar to :c:func:`PySys_Audit`, but pass arguments as a Python object. " -"*args* must be a :class:`tuple`. To pass no arguments, *args* can be *NULL*." -msgstr "" - -#: ../../c-api/sys.rst:384 -msgid "" -"Append the callable *hook* to the list of active auditing hooks. Return zero " -"on success and non-zero on failure. If the runtime has been initialized, " -"also set an error on failure. Hooks added through this API are called for " -"all interpreters created by the runtime." -msgstr "" - -#: ../../c-api/sys.rst:390 -msgid "" -"The *userData* pointer is passed into the hook function. Since hook " -"functions may be called from different runtimes, this pointer should not " -"refer directly to Python state." -msgstr "" - -#: ../../c-api/sys.rst:394 -msgid "" -"This function is safe to call before :c:func:`Py_Initialize`. When called " -"after runtime initialization, existing audit hooks are notified and may " -"silently abort the operation by raising an error subclassed from :class:" -"`Exception` (other errors will not be silenced)." -msgstr "" - -#: ../../c-api/sys.rst:399 -msgid "" -"The hook function is always called with an :term:`attached thread state` by " -"the Python interpreter that raised the event." -msgstr "" - -#: ../../c-api/sys.rst:402 -msgid "" -"See :pep:`578` for a detailed description of auditing. Functions in the " -"runtime and standard library that raise events are listed in the :ref:`audit " -"events table `. Details are in each function's documentation." -msgstr "" - -#: ../../c-api/sys.rst:407 ../../c-api/sys.rst:409 -msgid "" -"If the interpreter is initialized, this function raises an auditing event " -"``sys.addaudithook`` with no arguments. If any existing hooks raise an " -"exception derived from :class:`Exception`, the new hook will not be added " -"and the exception is cleared. As a result, callers cannot assume that their " -"hook has been added unless they control all existing hooks." -msgstr "" - -#: ../../c-api/sys.rst:418 -msgid "" -"The type of the hook function. *event* is the C string event argument passed " -"to :c:func:`PySys_Audit` or :c:func:`PySys_AuditTuple`. *args* is guaranteed " -"to be a :c:type:`PyTupleObject`. *userData* is the argument passed to " -"PySys_AddAuditHook()." -msgstr "" - -#: ../../c-api/sys.rst:430 -msgid "Process Control" -msgstr "行程控制" - -#: ../../c-api/sys.rst:437 -msgid "" -"Print a fatal error message and kill the process. No cleanup is performed. " -"This function should only be invoked when a condition is detected that would " -"make it dangerous to continue using the Python interpreter; e.g., when the " -"object administration appears to be corrupted. On Unix, the standard C " -"library function :c:func:`!abort` is called which will attempt to produce a :" -"file:`core` file." -msgstr "" - -#: ../../c-api/sys.rst:444 -msgid "" -"The ``Py_FatalError()`` function is replaced with a macro which logs " -"automatically the name of the current function, unless the " -"``Py_LIMITED_API`` macro is defined." -msgstr "" - -#: ../../c-api/sys.rst:448 -msgid "Log the function name automatically." -msgstr "" - -#: ../../c-api/sys.rst:458 -msgid "" -"Exit the current process. This calls :c:func:`Py_FinalizeEx` and then calls " -"the standard C library function ``exit(status)``. If :c:func:" -"`Py_FinalizeEx` indicates an error, the exit status is set to 120." -msgstr "" - -#: ../../c-api/sys.rst:462 -msgid "Errors from finalization no longer ignored." -msgstr "" - -#: ../../c-api/sys.rst:472 -msgid "" -"Register a cleanup function to be called by :c:func:`Py_FinalizeEx`. The " -"cleanup function will be called with no arguments and should return no " -"value. At most 32 cleanup functions can be registered. When the " -"registration is successful, :c:func:`Py_AtExit` returns ``0``; on failure, " -"it returns ``-1``. The cleanup function registered last is called first. " -"Each cleanup function will be called at most once. Since Python's internal " -"finalization will have completed before the cleanup function, no Python APIs " -"should be called by *func*." -msgstr "" - -#: ../../c-api/sys.rst:482 -msgid ":c:func:`PyUnstable_AtExit` for passing a ``void *data`` argument." -msgstr "" - -#: ../../c-api/sys.rst:101 -msgid "USE_STACKCHECK (C macro)" -msgstr "USE_STACKCHECK（C 巨集）" - -#: ../../c-api/sys.rst:435 -msgid "abort (C function)" -msgstr "abort（C 函式）" - -#: ../../c-api/sys.rst:454 ../../c-api/sys.rst:468 -msgid "Py_FinalizeEx (C function)" -msgstr "Py_FinalizeEx（C 函式）" - -#: ../../c-api/sys.rst:454 -msgid "exit (C function)" -msgstr "exit（C 函式）" - -#: ../../c-api/sys.rst:468 -msgid "cleanup functions" -msgstr "cleanup functions（清理函式）" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Ching-Lung Chuang, 2015 +# Leon H., 2017 +# Liang-Bo Wang , 2015 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-14 19:37+0000\n" +"PO-Revision-Date: 2018-05-23 14: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" + +#: ../../c-api/sys.rst:6 +msgid "Operating System Utilities" +msgstr "作業系統工具" + +#: ../../c-api/sys.rst:11 +msgid "" +"Return the file system representation for *path*. If the object is a :class:" +"`str` or :class:`bytes` object, then a new :term:`strong reference` is " +"returned. If the object implements the :class:`os.PathLike` interface, then :" +"meth:`~os.PathLike.__fspath__` is returned as long as it is a :class:`str` " +"or :class:`bytes` object. Otherwise :exc:`TypeError` is raised and ``NULL`` " +"is returned." +msgstr "" + +#: ../../c-api/sys.rst:24 +msgid "" +"Return true (nonzero) if the standard I/O file *fp* with name *filename* is " +"deemed interactive. This is the case for files for which " +"``isatty(fileno(fp))`` is true. If the :c:member:`PyConfig.interactive` is " +"non-zero, this function also returns true if the *filename* pointer is " +"``NULL`` or if the name is equal to one of the strings ``''`` or " +"``'???'``." +msgstr "" + +#: ../../c-api/sys.rst:30 +msgid "This function must not be called before Python is initialized." +msgstr "" + +#: ../../c-api/sys.rst:35 +msgid "" +"Function to prepare some internal state before a process fork. This should " +"be called before calling :c:func:`fork` or any similar function that clones " +"the current process. Only available on systems where :c:func:`fork` is " +"defined." +msgstr "" + +#: ../../c-api/sys.rst:41 +msgid "" +"The C :c:func:`fork` call should only be made from the :ref:`\"main\" thread " +"` (of the :ref:`\"main\" interpreter `). The same is true for ``PyOS_BeforeFork()``." +msgstr "" + +#: ../../c-api/sys.rst:51 +msgid "" +"Function to update some internal state after a process fork. This should be " +"called from the parent process after calling :c:func:`fork` or any similar " +"function that clones the current process, regardless of whether process " +"cloning was successful. Only available on systems where :c:func:`fork` is " +"defined." +msgstr "" + +#: ../../c-api/sys.rst:58 +msgid "" +"The C :c:func:`fork` call should only be made from the :ref:`\"main\" thread " +"` (of the :ref:`\"main\" interpreter `). The same is true for ``PyOS_AfterFork_Parent()``." +msgstr "" + +#: ../../c-api/sys.rst:68 +msgid "" +"Function to update internal interpreter state after a process fork. This " +"must be called from the child process after calling :c:func:`fork`, or any " +"similar function that clones the current process, if there is any chance the " +"process will call back into the Python interpreter. Only available on " +"systems where :c:func:`fork` is defined." +msgstr "" + +#: ../../c-api/sys.rst:75 +msgid "" +"The C :c:func:`fork` call should only be made from the :ref:`\"main\" thread " +"` (of the :ref:`\"main\" interpreter `). The same is true for ``PyOS_AfterFork_Child()``." +msgstr "" + +#: ../../c-api/sys.rst:83 +msgid "" +":func:`os.register_at_fork` allows registering custom Python functions to be " +"called by :c:func:`PyOS_BeforeFork()`, :c:func:`PyOS_AfterFork_Parent` and :" +"c:func:`PyOS_AfterFork_Child`." +msgstr "" + +#: ../../c-api/sys.rst:90 +msgid "" +"Function to update some internal state after a process fork; this should be " +"called in the new process if the Python interpreter will continue to be " +"used. If a new executable is loaded into the new process, this function does " +"not need to be called." +msgstr "" + +#: ../../c-api/sys.rst:95 +msgid "This function is superseded by :c:func:`PyOS_AfterFork_Child()`." +msgstr "" + +#: ../../c-api/sys.rst:103 +msgid "" +"Return true when the interpreter runs out of stack space. This is a " +"reliable check, but is only available when :c:macro:`!USE_STACKCHECK` is " +"defined (currently on certain versions of Windows using the Microsoft Visual " +"C++ compiler). :c:macro:`!USE_STACKCHECK` will be defined automatically; you " +"should never change the definition in your own code." +msgstr "" + +#: ../../c-api/sys.rst:115 +msgid "" +"Return the current signal handler for signal *i*. This is a thin wrapper " +"around either :c:func:`!sigaction` or :c:func:`!signal`. Do not call those " +"functions directly!" +msgstr "" + +#: ../../c-api/sys.rst:122 +msgid "" +"Set the signal handler for signal *i* to be *h*; return the old signal " +"handler. This is a thin wrapper around either :c:func:`!sigaction` or :c:" +"func:`!signal`. Do not call those functions directly!" +msgstr "" + +#: ../../c-api/sys.rst:129 +msgid "Check if a :c:macro:`!SIGINT` signal has been received." +msgstr "" + +#: ../../c-api/sys.rst:131 +msgid "" +"Returns ``1`` if a :c:macro:`!SIGINT` has occurred and clears the signal " +"flag, or ``0`` otherwise." +msgstr "" + +#: ../../c-api/sys.rst:134 +msgid "" +"In most cases, you should prefer :c:func:`PyErr_CheckSignals` over this " +"function. :c:func:`!PyErr_CheckSignals` invokes the appropriate signal " +"handlers for all pending signals, allowing Python code to handle the signal " +"properly. This function only detects :c:macro:`!SIGINT` and does not invoke " +"any Python signal handlers." +msgstr "" + +#: ../../c-api/sys.rst:140 +msgid "" +"This function is async-signal-safe and this function cannot fail. The caller " +"must hold an :term:`attached thread state`." +msgstr "" + +#: ../../c-api/sys.rst:147 +msgid "" +"This function should not be called directly: use the :c:type:`PyConfig` API " +"with the :c:func:`PyConfig_SetBytesString` function which ensures that :ref:" +"`Python is preinitialized `." +msgstr "" + +#: ../../c-api/sys.rst:151 ../../c-api/sys.rst:218 +msgid "" +"This function must not be called before :ref:`Python is preinitialized ` and so that the LC_CTYPE locale is properly configured: see the :c:" +"func:`Py_PreInitialize` function." +msgstr "" + +#: ../../c-api/sys.rst:155 +msgid "" +"Decode a byte string from the :term:`filesystem encoding and error handler`. " +"If the error handler is :ref:`surrogateescape error handler " +"`, undecodable bytes are decoded as characters in range " +"U+DC80..U+DCFF; and if a byte sequence can be decoded as a surrogate " +"character, the bytes are escaped using the surrogateescape error handler " +"instead of decoding them." +msgstr "" + +#: ../../c-api/sys.rst:162 +msgid "" +"Return a pointer to a newly allocated wide character string, use :c:func:" +"`PyMem_RawFree` to free the memory. If size is not ``NULL``, write the " +"number of wide characters excluding the null character into ``*size``" +msgstr "" + +#: ../../c-api/sys.rst:166 +msgid "" +"Return ``NULL`` on decoding error or memory allocation error. If *size* is " +"not ``NULL``, ``*size`` is set to ``(size_t)-1`` on memory error or set to " +"``(size_t)-2`` on decoding error." +msgstr "" + +#: ../../c-api/sys.rst:170 ../../c-api/sys.rst:210 +msgid "" +"The :term:`filesystem encoding and error handler` are selected by :c:func:" +"`PyConfig_Read`: see :c:member:`~PyConfig.filesystem_encoding` and :c:member:" +"`~PyConfig.filesystem_errors` members of :c:type:`PyConfig`." +msgstr "" + +#: ../../c-api/sys.rst:174 +msgid "" +"Decoding errors should never happen, unless there is a bug in the C library." +msgstr "" + +#: ../../c-api/sys.rst:177 +msgid "" +"Use the :c:func:`Py_EncodeLocale` function to encode the character string " +"back to a byte string." +msgstr "" + +#: ../../c-api/sys.rst:182 +msgid "" +"The :c:func:`PyUnicode_DecodeFSDefaultAndSize` and :c:func:" +"`PyUnicode_DecodeLocaleAndSize` functions." +msgstr "" + +#: ../../c-api/sys.rst:187 ../../c-api/sys.rst:229 +msgid "" +"The function now uses the UTF-8 encoding in the :ref:`Python UTF-8 Mode " +"`." +msgstr "" + +#: ../../c-api/sys.rst:191 +msgid "" +"The function now uses the UTF-8 encoding on Windows if :c:member:" +"`PyPreConfig.legacy_windows_fs_encoding` is zero;" +msgstr "" + +#: ../../c-api/sys.rst:198 +msgid "" +"Encode a wide character string to the :term:`filesystem encoding and error " +"handler`. If the error handler is :ref:`surrogateescape error handler " +"`, surrogate characters in the range U+DC80..U+DCFF are " +"converted to bytes 0x80..0xFF." +msgstr "" + +#: ../../c-api/sys.rst:203 +msgid "" +"Return a pointer to a newly allocated byte string, use :c:func:`PyMem_Free` " +"to free the memory. Return ``NULL`` on encoding error or memory allocation " +"error." +msgstr "" + +#: ../../c-api/sys.rst:207 +msgid "" +"If error_pos is not ``NULL``, ``*error_pos`` is set to ``(size_t)-1`` on " +"success, or set to the index of the invalid character on encoding error." +msgstr "" + +#: ../../c-api/sys.rst:214 +msgid "" +"Use the :c:func:`Py_DecodeLocale` function to decode the bytes string back " +"to a wide character string." +msgstr "" + +#: ../../c-api/sys.rst:224 +msgid "" +"The :c:func:`PyUnicode_EncodeFSDefault` and :c:func:`PyUnicode_EncodeLocale` " +"functions." +msgstr "" + +#: ../../c-api/sys.rst:233 +msgid "" +"The function now uses the UTF-8 encoding on Windows if :c:member:" +"`PyPreConfig.legacy_windows_fs_encoding` is zero." +msgstr "" + +#: ../../c-api/sys.rst:239 +msgid "" +"Similar to :c:func:`!fopen`, but *path* is a Python object and an exception " +"is set on error." +msgstr "" + +#: ../../c-api/sys.rst:242 +msgid "" +"*path* must be a :class:`str` object, a :class:`bytes` object, or a :term:" +"`path-like object`." +msgstr "" + +#: ../../c-api/sys.rst:245 +msgid "" +"On success, return the new file pointer. On error, set an exception and " +"return ``NULL``." +msgstr "" + +#: ../../c-api/sys.rst:248 +msgid "" +"The file must be closed by :c:func:`Py_fclose` rather than calling directly :" +"c:func:`!fclose`." +msgstr "" + +#: ../../c-api/sys.rst:251 +msgid "The file descriptor is created non-inheritable (:pep:`446`)." +msgstr "" + +#: ../../c-api/sys.rst:253 +msgid "The caller must have an :term:`attached thread state`." +msgstr "" + +#: ../../c-api/sys.rst:260 +msgid "Close a file that was opened by :c:func:`Py_fopen`." +msgstr "" + +#: ../../c-api/sys.rst:262 +msgid "" +"On success, return ``0``. On error, return ``EOF`` and ``errno`` is set to " +"indicate the error. In either case, any further access (including another " +"call to :c:func:`Py_fclose`) to the stream results in undefined behavior." +msgstr "" + +#: ../../c-api/sys.rst:273 +msgid "System Functions" +msgstr "系統函式" + +#: ../../c-api/sys.rst:275 +msgid "" +"These are utility functions that make functionality from the :mod:`sys` " +"module accessible to C code. They all work with the current interpreter " +"thread's :mod:`sys` module's dict, which is contained in the internal thread " +"state structure." +msgstr "" + +#: ../../c-api/sys.rst:281 +msgid "" +"Return the object *name* from the :mod:`sys` module or ``NULL`` if it does " +"not exist, without setting an exception." +msgstr "" + +#: ../../c-api/sys.rst:286 +msgid "" +"Set *name* in the :mod:`sys` module to *v* unless *v* is ``NULL``, in which " +"case *name* is deleted from the sys module. Returns ``0`` on success, ``-1`` " +"on error." +msgstr "" + +#: ../../c-api/sys.rst:292 +msgid "" +"Reset :data:`sys.warnoptions` to an empty list. This function may be called " +"prior to :c:func:`Py_Initialize`." +msgstr "" + +#: ../../c-api/sys.rst:295 +msgid "Clear :data:`sys.warnoptions` and :data:`!warnings.filters` instead." +msgstr "" + +#: ../../c-api/sys.rst:300 +msgid "" +"Write the output string described by *format* to :data:`sys.stdout`. No " +"exceptions are raised, even if truncation occurs (see below)." +msgstr "" + +#: ../../c-api/sys.rst:303 +msgid "" +"*format* should limit the total size of the formatted output string to 1000 " +"bytes or less -- after 1000 bytes, the output string is truncated. In " +"particular, this means that no unrestricted \"%s\" formats should occur; " +"these should be limited using \"%.s\" where is a decimal number " +"calculated so that plus the maximum size of other formatted text does " +"not exceed 1000 bytes. Also watch out for \"%f\", which can print hundreds " +"of digits for very large numbers." +msgstr "" + +#: ../../c-api/sys.rst:311 +msgid "" +"If a problem occurs, or :data:`sys.stdout` is unset, the formatted message " +"is written to the real (C level) *stdout*." +msgstr "" + +#: ../../c-api/sys.rst:316 +msgid "" +"As :c:func:`PySys_WriteStdout`, but write to :data:`sys.stderr` or *stderr* " +"instead." +msgstr "" + +#: ../../c-api/sys.rst:321 +msgid "" +"Function similar to PySys_WriteStdout() but format the message using :c:func:" +"`PyUnicode_FromFormatV` and don't truncate the message to an arbitrary " +"length." +msgstr "" + +#: ../../c-api/sys.rst:329 +msgid "" +"As :c:func:`PySys_FormatStdout`, but write to :data:`sys.stderr` or *stderr* " +"instead." +msgstr "" + +#: ../../c-api/sys.rst:336 +msgid "" +"Return the current dictionary of :option:`-X` options, similarly to :data:" +"`sys._xoptions`. On error, ``NULL`` is returned and an exception is set." +msgstr "" + +#: ../../c-api/sys.rst:345 +msgid "" +"Raise an auditing event with any active hooks. Return zero for success and " +"non-zero with an exception set on failure." +msgstr "" + +#: ../../c-api/sys.rst:348 +msgid "The *event* string argument must not be *NULL*." +msgstr "" + +#: ../../c-api/sys.rst:350 +msgid "" +"If any hooks have been added, *format* and other arguments will be used to " +"construct a tuple to pass. Apart from ``N``, the same format characters as " +"used in :c:func:`Py_BuildValue` are available. If the built value is not a " +"tuple, it will be added into a single-element tuple." +msgstr "" + +#: ../../c-api/sys.rst:355 +msgid "" +"The ``N`` format option must not be used. It consumes a reference, but since " +"there is no way to know whether arguments to this function will be consumed, " +"using it may cause reference leaks." +msgstr "" + +#: ../../c-api/sys.rst:359 +msgid "" +"Note that ``#`` format characters should always be treated as :c:type:" +"`Py_ssize_t`, regardless of whether ``PY_SSIZE_T_CLEAN`` was defined." +msgstr "" + +#: ../../c-api/sys.rst:362 +msgid ":func:`sys.audit` performs the same function from Python code." +msgstr "" + +#: ../../c-api/sys.rst:364 +msgid "See also :c:func:`PySys_AuditTuple`." +msgstr "請參閱 :c:func:`PySys_AuditTuple`。" + +#: ../../c-api/sys.rst:370 +msgid "" +"Require :c:type:`Py_ssize_t` for ``#`` format characters. Previously, an " +"unavoidable deprecation warning was raised." +msgstr "" + +#: ../../c-api/sys.rst:376 +msgid "" +"Similar to :c:func:`PySys_Audit`, but pass arguments as a Python object. " +"*args* must be a :class:`tuple`. To pass no arguments, *args* can be *NULL*." +msgstr "" + +#: ../../c-api/sys.rst:384 +msgid "" +"Append the callable *hook* to the list of active auditing hooks. Return zero " +"on success and non-zero on failure. If the runtime has been initialized, " +"also set an error on failure. Hooks added through this API are called for " +"all interpreters created by the runtime." +msgstr "" + +#: ../../c-api/sys.rst:390 +msgid "" +"The *userData* pointer is passed into the hook function. Since hook " +"functions may be called from different runtimes, this pointer should not " +"refer directly to Python state." +msgstr "" + +#: ../../c-api/sys.rst:394 +msgid "" +"This function is safe to call before :c:func:`Py_Initialize`. When called " +"after runtime initialization, existing audit hooks are notified and may " +"silently abort the operation by raising an error subclassed from :class:" +"`Exception` (other errors will not be silenced)." +msgstr "" + +#: ../../c-api/sys.rst:399 +msgid "" +"The hook function is always called with an :term:`attached thread state` by " +"the Python interpreter that raised the event." +msgstr "" + +#: ../../c-api/sys.rst:402 +msgid "" +"See :pep:`578` for a detailed description of auditing. Functions in the " +"runtime and standard library that raise events are listed in the :ref:`audit " +"events table `. Details are in each function's documentation." +msgstr "" + +#: ../../c-api/sys.rst:407 ../../c-api/sys.rst:409 +msgid "" +"If the interpreter is initialized, this function raises an auditing event " +"``sys.addaudithook`` with no arguments. If any existing hooks raise an " +"exception derived from :class:`Exception`, the new hook will not be added " +"and the exception is cleared. As a result, callers cannot assume that their " +"hook has been added unless they control all existing hooks." +msgstr "" + +#: ../../c-api/sys.rst:418 +msgid "" +"The type of the hook function. *event* is the C string event argument passed " +"to :c:func:`PySys_Audit` or :c:func:`PySys_AuditTuple`. *args* is guaranteed " +"to be a :c:type:`PyTupleObject`. *userData* is the argument passed to " +"PySys_AddAuditHook()." +msgstr "" + +#: ../../c-api/sys.rst:430 +msgid "Process Control" +msgstr "行程控制" + +#: ../../c-api/sys.rst:437 +msgid "" +"Print a fatal error message and kill the process. No cleanup is performed. " +"This function should only be invoked when a condition is detected that would " +"make it dangerous to continue using the Python interpreter; e.g., when the " +"object administration appears to be corrupted. On Unix, the standard C " +"library function :c:func:`!abort` is called which will attempt to produce a :" +"file:`core` file." +msgstr "" + +#: ../../c-api/sys.rst:444 +msgid "" +"The ``Py_FatalError()`` function is replaced with a macro which logs " +"automatically the name of the current function, unless the " +"``Py_LIMITED_API`` macro is defined." +msgstr "" + +#: ../../c-api/sys.rst:448 +msgid "Log the function name automatically." +msgstr "" + +#: ../../c-api/sys.rst:458 +msgid "" +"Exit the current process. This calls :c:func:`Py_FinalizeEx` and then calls " +"the standard C library function ``exit(status)``. If :c:func:" +"`Py_FinalizeEx` indicates an error, the exit status is set to 120." +msgstr "" + +#: ../../c-api/sys.rst:462 +msgid "Errors from finalization no longer ignored." +msgstr "" + +#: ../../c-api/sys.rst:472 +msgid "" +"Register a cleanup function to be called by :c:func:`Py_FinalizeEx`. The " +"cleanup function will be called with no arguments and should return no " +"value. At most 32 cleanup functions can be registered. When the " +"registration is successful, :c:func:`Py_AtExit` returns ``0``; on failure, " +"it returns ``-1``. The cleanup function registered last is called first. " +"Each cleanup function will be called at most once. Since Python's internal " +"finalization will have completed before the cleanup function, no Python APIs " +"should be called by *func*." +msgstr "" + +#: ../../c-api/sys.rst:482 +msgid ":c:func:`PyUnstable_AtExit` for passing a ``void *data`` argument." +msgstr "" + +#: ../../c-api/sys.rst:101 +msgid "USE_STACKCHECK (C macro)" +msgstr "USE_STACKCHECK（C 巨集）" + +#: ../../c-api/sys.rst:435 +msgid "abort (C function)" +msgstr "abort（C 函式）" + +#: ../../c-api/sys.rst:454 ../../c-api/sys.rst:468 +msgid "Py_FinalizeEx (C function)" +msgstr "Py_FinalizeEx（C 函式）" + +#: ../../c-api/sys.rst:454 +msgid "exit (C function)" +msgstr "exit（C 函式）" + +#: ../../c-api/sys.rst:468 +msgid "cleanup functions" +msgstr "cleanup functions（清理函式）" diff --git a/c-api/time.po b/c-api/time.po index 4ec1712864..7a9edc68cb 100644 --- a/c-api/time.po +++ b/c-api/time.po @@ -1,189 +1,189 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Matt Wang , 2025 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: 2025-05-25 04:26+0800\n" -"Last-Translator: Matt Wang \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" - -#: ../../c-api/time.rst:6 -msgid "PyTime C API" -msgstr "PyTime C API" - -#: ../../c-api/time.rst:10 -msgid "" -"The clock C API provides access to system clocks. It is similar to the " -"Python :mod:`time` module." -msgstr "時鐘 C API 提供對系統時鐘的存取。它類似於 Python 的 :mod:`time` 模組。" - -#: ../../c-api/time.rst:13 -msgid "" -"For C API related to the :mod:`datetime` module, see :ref:`datetimeobjects`." -msgstr "" -"對於與 :mod:`datetime` 模組相關的 C API，請參閱 :ref:`datetimeobjects`。" - -#: ../../c-api/time.rst:17 -msgid "Types" -msgstr "型別" - -#: ../../c-api/time.rst:21 -msgid "" -"A timestamp or duration in nanoseconds, represented as a signed 64-bit " -"integer." -msgstr "以奈秒為單位的時間戳記或持續時長，以有符號的 64 位元整數表示。" - -#: ../../c-api/time.rst:24 -msgid "" -"The reference point for timestamps depends on the clock used. For " -"example, :c:func:`PyTime_Time` returns timestamps relative to the UNIX epoch." -msgstr "" -"時間戳記的參照點取決於所使用的時鐘。例如 :c:func:`PyTime_Time` 回傳相對於 " -"UNIX 紀元 (UNIX epoch) 的時間戳記。" - -#: ../../c-api/time.rst:27 -msgid "" -"The supported range is around [-292.3 years; +292.3 years]. Using the Unix " -"epoch (January 1st, 1970) as reference, the supported date range is around " -"[1677-09-21; 2262-04-11]. The exact limits are exposed as constants:" -msgstr "" -"支援的範圍約為 [-292.3 年；+292.3 年]。以 Unix 紀元 (1970 年 1 月 1 日) 為參" -"照，支援的日期範圍約為 [1677-09-21; 2262-04-11]。確切的限制是以常數的形式公開" -"出來：" - -#: ../../c-api/time.rst:34 -msgid "Minimum value of :c:type:`PyTime_t`." -msgstr ":c:type:`PyTime_t` 的最小值。" - -#: ../../c-api/time.rst:38 -msgid "Maximum value of :c:type:`PyTime_t`." -msgstr ":c:type:`PyTime_t` 的最大值。" - -#: ../../c-api/time.rst:42 -msgid "Clock Functions" -msgstr "時鐘函式" - -#: ../../c-api/time.rst:44 -msgid "" -"The following functions take a pointer to a :c:expr:`PyTime_t` that they set " -"to the value of a particular clock. Details of each clock are given in the " -"documentation of the corresponding Python function." -msgstr "" -"以下的函式接受一個指向 :c:expr:`PyTime_t` 的指標，並將其設定為特定時鐘的值。" -"每個時鐘的詳細資訊紀錄在相對應的 Python 函式說明文件中。" - -#: ../../c-api/time.rst:49 -msgid "" -"The functions return ``0`` on success, or ``-1`` (with an exception set) on " -"failure." -msgstr "函式成功時會回傳 ``0`` 或在失敗時回傳 ``-1``\\ （並設定一個例外）。" - -#: ../../c-api/time.rst:52 -msgid "" -"On integer overflow, they set the :c:data:`PyExc_OverflowError` exception " -"and set ``*result`` to the value clamped to the ``[PyTime_MIN; PyTime_MAX]`` " -"range. (On current systems, integer overflows are likely caused by " -"misconfigured system time.)" -msgstr "" -"在整數溢位時，它們會設定 :c:data:`PyExc_OverflowError` 例外，並將 " -"``*result`` 設定為夾在 ``[PyTime_MIN; PyTime_MAX]`` 範圍內的值。（在目前的系" -"統上，整數溢位很可能是由於錯誤設定的系統時間所造成。）" - -#: ../../c-api/time.rst:58 -msgid "" -"As any other C API (unless otherwise specified), the functions must be " -"called with an :term:`attached thread state`." -msgstr "" -"如同任何其他 C API（除非另有指定），必須在具有 :term:`attached thread state` 的情況下呼叫函式。" - -#: ../../c-api/time.rst:63 -msgid "" -"Read the monotonic clock. See :func:`time.monotonic` for important details " -"on this clock." -msgstr "讀取單調時鐘。請參閱 :func:`time.monotonic` 取得此時鐘的重要詳細資訊。" - -#: ../../c-api/time.rst:68 -msgid "" -"Read the performance counter. See :func:`time.perf_counter` for important " -"details on this clock." -msgstr "" -"讀取效能計數器。請參閱 :func:`time.perf_counter` 以取得此時鐘的重要詳細資訊。" - -#: ../../c-api/time.rst:73 -msgid "" -"Read the “wall clock” time. See :func:`time.time` for details important on " -"this clock." -msgstr "" -"讀取「牆上時鐘 (wall clock)」的時間。請參閱 :func:`time.time` 以取得詳細資" -"訊。" - -#: ../../c-api/time.rst:78 -msgid "Raw Clock Functions" -msgstr "原始時鐘函式" - -#: ../../c-api/time.rst:80 -msgid "" -"Similar to clock functions, but don't set an exception on error and don't " -"require the caller to have an :term:`attached thread state`." -msgstr "類似於時鐘函式，但不會在出錯時設定例外，也不需要呼叫者擁有 :term:`attached thread state`。" - -#: ../../c-api/time.rst:83 -msgid "On success, the functions return ``0``." -msgstr "成功時函式會回傳 ``0``。" - -#: ../../c-api/time.rst:85 -msgid "" -"On failure, they set ``*result`` to ``0`` and return ``-1``, *without* " -"setting an exception. To get the cause of the error, :term:`attach ` a :term:`thread state`, and call the regular (non-``Raw``) " -"function. Note that the regular function may succeed after the ``Raw`` one " -"failed." -msgstr "" -"失敗時，它們會將 ``*result`` 設為 ``0`` 並回傳 ``-1``, 而\\ *不*\\ 設定例外。" -"要取得錯誤原因，請\\ :term:`附加 `\\ 一個 :term:`thread state`，" -"並呼叫常規（非 ``Raw``）函式。請注意，常規函式可能會在 ``Raw`` 的函式失敗後成功。" - -#: ../../c-api/time.rst:92 -msgid "" -"Similar to :c:func:`PyTime_Monotonic`, but don't set an exception on error " -"and don't require an :term:`attached thread state`." -msgstr "" -"類似於 :c:func:`PyTime_Monotonic`，但不會在錯誤時設定例外，也不需要擁有 :term:`attached thread state`。" - -#: ../../c-api/time.rst:97 -msgid "" -"Similar to :c:func:`PyTime_PerfCounter`, but don't set an exception on error " -"and don't require an :term:`attached thread state`." -msgstr "" -"類似於 :c:func:`PyTime_PerfCounter`，但不會在錯誤時設定例外，也不需要擁有 :term:`attached thread state`。" - -#: ../../c-api/time.rst:102 -msgid "" -"Similar to :c:func:`PyTime_Time`, but don't set an exception on error and " -"don't require an :term:`attached thread state`." -msgstr "" -"類似於 :c:func:`PyTime_Time`，但不會在錯誤時設定例外，也不需要擁有 :term:`attached thread state`。" - -#: ../../c-api/time.rst:107 -msgid "Conversion functions" -msgstr "轉換函式" - -#: ../../c-api/time.rst:111 -msgid "Convert a timestamp to a number of seconds as a C :c:expr:`double`." -msgstr "將時間戳記轉換為 C :c:expr:`double` 的秒數。" - -#: ../../c-api/time.rst:113 -msgid "" -"The function cannot fail, but note that :c:expr:`double` has limited " -"accuracy for large values." -msgstr "此函式不會失敗，但請注意 :c:expr:`double` 對於大數值的精確度有限。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Matt Wang , 2025 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: 2025-05-25 04:26+0800\n" +"Last-Translator: Matt Wang \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" + +#: ../../c-api/time.rst:6 +msgid "PyTime C API" +msgstr "PyTime C API" + +#: ../../c-api/time.rst:10 +msgid "" +"The clock C API provides access to system clocks. It is similar to the " +"Python :mod:`time` module." +msgstr "時鐘 C API 提供對系統時鐘的存取。它類似於 Python 的 :mod:`time` 模組。" + +#: ../../c-api/time.rst:13 +msgid "" +"For C API related to the :mod:`datetime` module, see :ref:`datetimeobjects`." +msgstr "" +"對於與 :mod:`datetime` 模組相關的 C API，請參閱 :ref:`datetimeobjects`。" + +#: ../../c-api/time.rst:17 +msgid "Types" +msgstr "型別" + +#: ../../c-api/time.rst:21 +msgid "" +"A timestamp or duration in nanoseconds, represented as a signed 64-bit " +"integer." +msgstr "以奈秒為單位的時間戳記或持續時長，以有符號的 64 位元整數表示。" + +#: ../../c-api/time.rst:24 +msgid "" +"The reference point for timestamps depends on the clock used. For " +"example, :c:func:`PyTime_Time` returns timestamps relative to the UNIX epoch." +msgstr "" +"時間戳記的參照點取決於所使用的時鐘。例如 :c:func:`PyTime_Time` 回傳相對於 " +"UNIX 紀元 (UNIX epoch) 的時間戳記。" + +#: ../../c-api/time.rst:27 +msgid "" +"The supported range is around [-292.3 years; +292.3 years]. Using the Unix " +"epoch (January 1st, 1970) as reference, the supported date range is around " +"[1677-09-21; 2262-04-11]. The exact limits are exposed as constants:" +msgstr "" +"支援的範圍約為 [-292.3 年；+292.3 年]。以 Unix 紀元 (1970 年 1 月 1 日) 為參" +"照，支援的日期範圍約為 [1677-09-21; 2262-04-11]。確切的限制是以常數的形式公開" +"出來：" + +#: ../../c-api/time.rst:34 +msgid "Minimum value of :c:type:`PyTime_t`." +msgstr ":c:type:`PyTime_t` 的最小值。" + +#: ../../c-api/time.rst:38 +msgid "Maximum value of :c:type:`PyTime_t`." +msgstr ":c:type:`PyTime_t` 的最大值。" + +#: ../../c-api/time.rst:42 +msgid "Clock Functions" +msgstr "時鐘函式" + +#: ../../c-api/time.rst:44 +msgid "" +"The following functions take a pointer to a :c:expr:`PyTime_t` that they set " +"to the value of a particular clock. Details of each clock are given in the " +"documentation of the corresponding Python function." +msgstr "" +"以下的函式接受一個指向 :c:expr:`PyTime_t` 的指標，並將其設定為特定時鐘的值。" +"每個時鐘的詳細資訊紀錄在相對應的 Python 函式說明文件中。" + +#: ../../c-api/time.rst:49 +msgid "" +"The functions return ``0`` on success, or ``-1`` (with an exception set) on " +"failure." +msgstr "函式成功時會回傳 ``0`` 或在失敗時回傳 ``-1``\\ （並設定一個例外）。" + +#: ../../c-api/time.rst:52 +msgid "" +"On integer overflow, they set the :c:data:`PyExc_OverflowError` exception " +"and set ``*result`` to the value clamped to the ``[PyTime_MIN; PyTime_MAX]`` " +"range. (On current systems, integer overflows are likely caused by " +"misconfigured system time.)" +msgstr "" +"在整數溢位時，它們會設定 :c:data:`PyExc_OverflowError` 例外，並將 " +"``*result`` 設定為夾在 ``[PyTime_MIN; PyTime_MAX]`` 範圍內的值。（在目前的系" +"統上，整數溢位很可能是由於錯誤設定的系統時間所造成。）" + +#: ../../c-api/time.rst:58 +msgid "" +"As any other C API (unless otherwise specified), the functions must be " +"called with an :term:`attached thread state`." +msgstr "" +"如同任何其他 C API（除非另有指定），必須在具有 :term:`attached thread state` 的情況下呼叫函式。" + +#: ../../c-api/time.rst:63 +msgid "" +"Read the monotonic clock. See :func:`time.monotonic` for important details " +"on this clock." +msgstr "讀取單調時鐘。請參閱 :func:`time.monotonic` 取得此時鐘的重要詳細資訊。" + +#: ../../c-api/time.rst:68 +msgid "" +"Read the performance counter. See :func:`time.perf_counter` for important " +"details on this clock." +msgstr "" +"讀取效能計數器。請參閱 :func:`time.perf_counter` 以取得此時鐘的重要詳細資訊。" + +#: ../../c-api/time.rst:73 +msgid "" +"Read the “wall clock” time. See :func:`time.time` for details important on " +"this clock." +msgstr "" +"讀取「牆上時鐘 (wall clock)」的時間。請參閱 :func:`time.time` 以取得詳細資" +"訊。" + +#: ../../c-api/time.rst:78 +msgid "Raw Clock Functions" +msgstr "原始時鐘函式" + +#: ../../c-api/time.rst:80 +msgid "" +"Similar to clock functions, but don't set an exception on error and don't " +"require the caller to have an :term:`attached thread state`." +msgstr "類似於時鐘函式，但不會在出錯時設定例外，也不需要呼叫者擁有 :term:`attached thread state`。" + +#: ../../c-api/time.rst:83 +msgid "On success, the functions return ``0``." +msgstr "成功時函式會回傳 ``0``。" + +#: ../../c-api/time.rst:85 +msgid "" +"On failure, they set ``*result`` to ``0`` and return ``-1``, *without* " +"setting an exception. To get the cause of the error, :term:`attach ` a :term:`thread state`, and call the regular (non-``Raw``) " +"function. Note that the regular function may succeed after the ``Raw`` one " +"failed." +msgstr "" +"失敗時，它們會將 ``*result`` 設為 ``0`` 並回傳 ``-1``, 而\\ *不*\\ 設定例外。" +"要取得錯誤原因，請\\ :term:`附加 `\\ 一個 :term:`thread state`，" +"並呼叫常規（非 ``Raw``）函式。請注意，常規函式可能會在 ``Raw`` 的函式失敗後成功。" + +#: ../../c-api/time.rst:92 +msgid "" +"Similar to :c:func:`PyTime_Monotonic`, but don't set an exception on error " +"and don't require an :term:`attached thread state`." +msgstr "" +"類似於 :c:func:`PyTime_Monotonic`，但不會在錯誤時設定例外，也不需要擁有 :term:`attached thread state`。" + +#: ../../c-api/time.rst:97 +msgid "" +"Similar to :c:func:`PyTime_PerfCounter`, but don't set an exception on error " +"and don't require an :term:`attached thread state`." +msgstr "" +"類似於 :c:func:`PyTime_PerfCounter`，但不會在錯誤時設定例外，也不需要擁有 :term:`attached thread state`。" + +#: ../../c-api/time.rst:102 +msgid "" +"Similar to :c:func:`PyTime_Time`, but don't set an exception on error and " +"don't require an :term:`attached thread state`." +msgstr "" +"類似於 :c:func:`PyTime_Time`，但不會在錯誤時設定例外，也不需要擁有 :term:`attached thread state`。" + +#: ../../c-api/time.rst:107 +msgid "Conversion functions" +msgstr "轉換函式" + +#: ../../c-api/time.rst:111 +msgid "Convert a timestamp to a number of seconds as a C :c:expr:`double`." +msgstr "將時間戳記轉換為 C :c:expr:`double` 的秒數。" + +#: ../../c-api/time.rst:113 +msgid "" +"The function cannot fail, but note that :c:expr:`double` has limited " +"accuracy for large values." +msgstr "此函式不會失敗，但請注意 :c:expr:`double` 對於大數值的精確度有限。" diff --git a/c-api/tuple.po b/c-api/tuple.po index 3116a764a7..a04fe0cc82 100644 --- a/c-api/tuple.po +++ b/c-api/tuple.po @@ -1,336 +1,336 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Leon H., 2017 -# Yorkxe , 2025 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-05 00:16+0000\n" -"PO-Revision-Date: 2025-11-13 21:53+0000\n" -"Last-Translator: Yorkxe \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" - -#: ../../c-api/tuple.rst:6 -msgid "Tuple Objects" -msgstr "Tuple（元組）物件" - -#: ../../c-api/tuple.rst:13 -msgid "This subtype of :c:type:`PyObject` represents a Python tuple object." -msgstr "此 :c:type:`PyObject` 子型別代表 Python 元組物件" - -#: ../../c-api/tuple.rst:18 -msgid "" -"This instance of :c:type:`PyTypeObject` represents the Python tuple type; it " -"is the same object as :class:`tuple` in the Python layer." -msgstr "" -"此 :c:type:`PyTypeObject` 實例代表 Python 元組型別，與 Python 層中的 :class:" -"`tuple` 是同一物件" - -#: ../../c-api/tuple.rst:24 -msgid "" -"Return true if *p* is a tuple object or an instance of a subtype of the " -"tuple type. This function always succeeds." -msgstr "" -"如果 *p* 為一元組物件或是元組型別的子型別實例時回傳 true。此函式總會執行成功" - -#: ../../c-api/tuple.rst:30 -msgid "" -"Return true if *p* is a tuple object, but not an instance of a subtype of " -"the tuple type. This function always succeeds." -msgstr "" -"如果 *p* 為一元組物件但不是元組型別的子型別實例時回傳 true。此函式總會執行成" -"功" - -#: ../../c-api/tuple.rst:36 -msgid "" -"Return a new tuple object of size *len*, or ``NULL`` with an exception set " -"on failure." -msgstr "回傳一個長度為 *len* 的新元組物件，失敗會時回傳 ``NULL`` 並設定例外。" - -#: ../../c-api/tuple.rst:42 -msgid "" -"Return a new tuple object of size *n*, or ``NULL`` with an exception set on " -"failure. The tuple values are initialized to the subsequent *n* C arguments " -"pointing to Python objects. ``PyTuple_Pack(2, a, b)`` is equivalent to " -"``Py_BuildValue(\"(OO)\", a, b)``." -msgstr "" -"回傳一個長度為 *n* 的新元組物件，失敗時會回傳 ``NULL`` 並設定例外。元組值被初" -"始化為指向 Python 物件的接續 *n* 個 C 引數。``PyTuple_Pack(2, a, b)`` 等價於 " -"``Py_BuildValue(\"(OO)\", a, b)``。" - -#: ../../c-api/tuple.rst:50 -msgid "" -"Take a pointer to a tuple object, and return the size of that tuple. On " -"error, return ``-1`` with an exception set." -msgstr "" -"拿取一個元組物件的指標，然後回傳此元組的大小。錯誤發生時，回傳 ``-1`` 並設定" -"例外。" - -#: ../../c-api/tuple.rst:56 -msgid "Like :c:func:`PyTuple_Size`, but without error checking." -msgstr "就像 :c:func:`PyTuple_Size` 但沒有錯誤檢查。" - -#: ../../c-api/tuple.rst:61 -msgid "" -"Return the object at position *pos* in the tuple pointed to by *p*. If " -"*pos* is negative or out of bounds, return ``NULL`` and set an :exc:" -"`IndexError` exception." -msgstr "" -"回傳 *p* 指向的元組中位置 *pos* 處的物件。如果 *pos* 為負數或超出範圍，回傳 " -"``NULL`` 並設定 :exc:`IndexError` 例外。" - -#: ../../c-api/tuple.rst:64 -msgid "" -"The returned reference is borrowed from the tuple *p* (that is: it is only " -"valid as long as you hold a reference to *p*). To get a :term:`strong " -"reference`, use :c:func:`Py_NewRef(PyTuple_GetItem(...)) ` or :c:" -"func:`PySequence_GetItem`." -msgstr "" -"回傳的參照借自元組 *p*\\ （也就是說：它僅在你持有 *p* 的參照時有效）。若要取" -"得一個 :term:`strong reference`，請使用 :c:func:" -"`Py_NewRef(PyTuple_GetItem(...)) ` 或 :c:func:" -"`PySequence_GetItem`。" - -#: ../../c-api/tuple.rst:73 -msgid "Like :c:func:`PyTuple_GetItem`, but does no checking of its arguments." -msgstr "與 :c:func:`PyTuple_GetItem` 相似，但不檢查其引數。" - -#: ../../c-api/tuple.rst:78 -msgid "" -"Return the slice of the tuple pointed to by *p* between *low* and *high*, or " -"``NULL`` with an exception set on failure." -msgstr "" -"回傳由 *p* 指向的元組中介於 *low* 和 *high* 之間的切片或在錯誤時回傳 " -"``NULL`` 並設定例外。" - -#: ../../c-api/tuple.rst:81 -msgid "" -"This is the equivalent of the Python expression ``p[low:high]``. Indexing " -"from the end of the tuple is not supported." -msgstr "這與 Python ``p[low:high]`` 運算式等價。但不支援從元組末端開始索引。" - -#: ../../c-api/tuple.rst:87 -msgid "" -"Insert a reference to object *o* at position *pos* of the tuple pointed to " -"by *p*. Return ``0`` on success. If *pos* is out of bounds, return ``-1`` " -"and set an :exc:`IndexError` exception." -msgstr "" -"於 *p* 指向的元組 *pos* 位置處插入對物件 *o* 的參照。成功時回傳 ``0``，如果 " -"*pos* 超出邊界則回傳 ``-1``，並設定 :exc:`IndexError` 例外。" - -#: ../../c-api/tuple.rst:93 -msgid "" -"This function \"steals\" a reference to *o* and discards a reference to an " -"item already in the tuple at the affected position." -msgstr "此函式 \"竊取\" 對 *o* 的參照，並丟棄對元組中受影響位置的項目的參照。" - -#: ../../c-api/tuple.rst:99 -msgid "" -"Like :c:func:`PyTuple_SetItem`, but does no error checking, and should " -"*only* be used to fill in brand new tuples." -msgstr "" -"與 :c:func:`PyTuple_SetItem` 相似，但不進行錯誤檢查，且應 *只* 用於填充全新的" -"元組。" - -#: ../../c-api/tuple.rst:102 ../../c-api/tuple.rst:224 -#: ../../c-api/tuple.rst:242 -msgid "" -"Bounds checking is performed as an assertion if Python is built in :ref:" -"`debug mode ` or :option:`with assertions <--with-assertions>`." -msgstr "" -"若 Python 以 :ref:`debug mode ` 或 :option:`with assertions <--" -"with-assertions>` 建置，則會進行作為斷言（asserting）的邊界檢查。" - -#: ../../c-api/tuple.rst:107 -msgid "" -"This function \"steals\" a reference to *o*, and, unlike :c:func:" -"`PyTuple_SetItem`, does *not* discard a reference to any item that is being " -"replaced; any reference in the tuple at position *pos* will be leaked." -msgstr "" -"此函式 \"竊取\" 對 *o* 的參照，且與 :c:func:`PyTuple_SetItem` 不同的是，此函" -"式並 *不* 丟棄任何被替代項目的參照；元組中 *pos* 位置的所有參照皆會被洩漏。" - -#: ../../c-api/tuple.rst:114 -msgid "" -"This macro should *only* be used on tuples that are newly created. Using " -"this macro on a tuple that is already in use (or in other words, has a " -"refcount > 1) could lead to undefined behavior." -msgstr "" -"此巨集應 *僅* 用於新建立的元組。在正被使用中的元組（或換句話說，參照計數大於 " -"1 的元組）上使用此巨集可能會導致未定義行為。" - -#: ../../c-api/tuple.rst:121 -msgid "" -"Can be used to resize a tuple. *newsize* will be the new length of the " -"tuple. Because tuples are *supposed* to be immutable, this should only be " -"used if there is only one reference to the object. Do *not* use this if the " -"tuple may already be known to some other part of the code. The tuple will " -"always grow or shrink at the end. Think of this as destroying the old tuple " -"and creating a new one, only more efficiently. Returns ``0`` on success. " -"Client code should never assume that the resulting value of ``*p`` will be " -"the same as before calling this function. If the object referenced by ``*p`` " -"is replaced, the original ``*p`` is destroyed. On failure, returns ``-1`` " -"and sets ``*p`` to ``NULL``, and raises :exc:`MemoryError` or :exc:" -"`SystemError`." -msgstr "" -"可用於調整元組的大小。*newsize* 將是元組的新長度。由於元組 *應該* 是不可變" -"的，因此僅當物件只有一個參照時才應使用此方法。如果程式碼的其他部分已經知道該" -"元組，則 *不要* 使用此方法。最終元組總會變大或縮小。可以將其理解為銷毀舊元組" -"並建立一個新元組，只是有著更高的效率。成功時回傳 ``0``。用戶端程式碼絕不應假" -"設 ``*p`` 的結果值與呼叫此函式之前的值相同。如果 ``*p`` 參照的物件被替換，則" -"原始的 ``*p`` 將被銷毀。失敗時，回傳 ``-1``，並將 ``*p`` 設定為 ``NULL``，並" -"引發 :exc:`MemoryError` 或 :exc:`SystemError` 例外。" - -#: ../../c-api/tuple.rst:136 -msgid "Struct Sequence Objects" -msgstr "結構序列物件" - -#: ../../c-api/tuple.rst:138 -msgid "" -"Struct sequence objects are the C equivalent of :func:`~collections." -"namedtuple` objects, i.e. a sequence whose items can also be accessed " -"through attributes. To create a struct sequence, you first have to create a " -"specific struct sequence type." -msgstr "" -"結構序列物件是 :func:`~collections.namedtuple` 物件在 C 語言中的等價，換言" -"之，一個序列的元素也可以透過屬性存取。要建立結構序列，首先需要建立特定的結構" -"序列型別。" - -#: ../../c-api/tuple.rst:145 -msgid "" -"Create a new struct sequence type from the data in *desc*, described below. " -"Instances of the resulting type can be created with :c:func:" -"`PyStructSequence_New`." -msgstr "" -"從 *desc* 中的資料建立一個新的結構序列型別，如下所述。可以使用 :c:func:" -"`PyStructSequence_New` 以建立產生結構序列型別的實例。" - -#: ../../c-api/tuple.rst:148 ../../c-api/tuple.rst:217 -msgid "Return ``NULL`` with an exception set on failure." -msgstr "失敗時回傳 ``NULL`` 並設定例外。" - -#: ../../c-api/tuple.rst:153 -msgid "Initializes a struct sequence type *type* from *desc* in place." -msgstr "從 *desc* 原地（in place）初始化結構序列型別 *type*。" - -#: ../../c-api/tuple.rst:158 -msgid "" -"Like :c:func:`PyStructSequence_InitType`, but returns ``0`` on success and " -"``-1`` with an exception set on failure." -msgstr "" -"與 :c:func:`PyStructSequence_InitType` 相似，但運行成功時回傳 ``0``，運行失敗" -"時回傳 ``-1`` 並設定例外。" - -#: ../../c-api/tuple.rst:166 -msgid "Contains the meta information of a struct sequence type to create." -msgstr "包含要建立的結構序列化型別的中介資訊（meta information）。" - -#: ../../c-api/tuple.rst:170 -msgid "" -"Fully qualified name of the type; null-terminated UTF-8 encoded. The name " -"must contain the module name." -msgstr "" -"型別的完整限定名稱（Fully qualified name）；以 UTF-8 編碼並以空字元結尾。名稱" -"必須包含完整的模組名稱。" - -#: ../../c-api/tuple.rst:175 -msgid "Pointer to docstring for the type or ``NULL`` to omit." -msgstr "指向型別說明文件（docstring）的指標或使用 ``NULL`` 表示忽略。" - -#: ../../c-api/tuple.rst:179 -msgid "Pointer to ``NULL``-terminated array with field names of the new type." -msgstr "指向一個以 ``NULL`` 結尾的陣列指標，其包含新型別的欄位名稱。" - -#: ../../c-api/tuple.rst:183 -msgid "Number of fields visible to the Python side (if used as tuple)." -msgstr "Python 端可以看到欄位的數目（如果作為元組使用）。" - -#: ../../c-api/tuple.rst:188 -msgid "" -"Describes a field of a struct sequence. As a struct sequence is modeled as a " -"tuple, all fields are typed as :c:expr:`PyObject*`. The index in the :c:" -"member:`~PyStructSequence_Desc.fields` array of the :c:type:" -"`PyStructSequence_Desc` determines which field of the struct sequence is " -"described." -msgstr "" -"描述結構序列的一個欄位。由於結構序列以元組作為原型，所有欄位的型別均為 :c:" -"expr:`PyObject*`。:c:type:`PyStructSequence_Desc` 在 :c:member:" -"`~PyStructSequence_Desc.fields` 陣列中的索引決定了描述的是結構序列的哪個欄" -"位。" - -#: ../../c-api/tuple.rst:196 -msgid "" -"Name for the field or ``NULL`` to end the list of named fields, set to :c:" -"data:`PyStructSequence_UnnamedField` to leave unnamed." -msgstr "" -"欄位名稱，或 ``NULL`` 表示命名欄位串列結束，設定為 :c:data:" -"`PyStructSequence_UnnamedField` 表示該欄位不命名。" - -#: ../../c-api/tuple.rst:201 -msgid "Field docstring or ``NULL`` to omit." -msgstr "欄位說明字串或為 ``NULL`` 表示忽略。" - -#: ../../c-api/tuple.rst:206 -msgid "Special value for a field name to leave it unnamed." -msgstr "給定欄位名稱一個特別值，表示該欄位不命名。" - -#: ../../c-api/tuple.rst:208 -msgid "The type was changed from ``char *``." -msgstr "型別原本是 ``char *``，現已被修改。" - -#: ../../c-api/tuple.rst:214 -msgid "" -"Creates an instance of *type*, which must have been created with :c:func:" -"`PyStructSequence_NewType`." -msgstr "建立 *type* 的實例，必須以 :c:func:`PyStructSequence_NewType` 建立。" - -#: ../../c-api/tuple.rst:222 -msgid "" -"Return the object at position *pos* in the struct sequence pointed to by *p*." -msgstr "回傳結構序列中由 *p* 指向 *pos* 處的物件。" - -#: ../../c-api/tuple.rst:230 -msgid "Alias to :c:func:`PyStructSequence_GetItem`." -msgstr ":c:func:`PyStructSequence_GetItem` 的別名。" - -#: ../../c-api/tuple.rst:232 -msgid "Now implemented as an alias to :c:func:`PyStructSequence_GetItem`." -msgstr "現在是被實作為 :c:func:`PyStructSequence_GetItem` 的一個別名。" - -#: ../../c-api/tuple.rst:238 -msgid "" -"Sets the field at index *pos* of the struct sequence *p* to value *o*. " -"Like :c:func:`PyTuple_SET_ITEM`, this should only be used to fill in brand " -"new instances." -msgstr "" -"將結構序列 *p* 中索引 *pos* 處的欄位值設為 *o*。與 :c:func:" -"`PyTuple_SET_ITEM` 類似，此函式僅套用於填充全新實例。" - -#: ../../c-api/tuple.rst:247 -msgid "This function \"steals\" a reference to *o*." -msgstr "此函式 \"竊取\" *o* 的參照。" - -#: ../../c-api/tuple.rst:252 -msgid "Alias to :c:func:`PyStructSequence_SetItem`." -msgstr ":c:func:`PyStructSequence_SetItem` 的別名。" - -#: ../../c-api/tuple.rst:254 -msgid "Now implemented as an alias to :c:func:`PyStructSequence_SetItem`." -msgstr "現在是被實作為 :c:func:`PyStructSequence_SetItem` 的一個別名。" - -#: ../../c-api/tuple.rst:8 -msgid "object" -msgstr "object（物件）" - -#: ../../c-api/tuple.rst:8 -msgid "tuple" -msgstr "tuple（元組）" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Leon H., 2017 +# Yorkxe , 2025 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-05 00:16+0000\n" +"PO-Revision-Date: 2025-11-13 21:53+0000\n" +"Last-Translator: Yorkxe \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" + +#: ../../c-api/tuple.rst:6 +msgid "Tuple Objects" +msgstr "Tuple（元組）物件" + +#: ../../c-api/tuple.rst:13 +msgid "This subtype of :c:type:`PyObject` represents a Python tuple object." +msgstr "此 :c:type:`PyObject` 子型別代表 Python 元組物件" + +#: ../../c-api/tuple.rst:18 +msgid "" +"This instance of :c:type:`PyTypeObject` represents the Python tuple type; it " +"is the same object as :class:`tuple` in the Python layer." +msgstr "" +"此 :c:type:`PyTypeObject` 實例代表 Python 元組型別，與 Python 層中的 :class:" +"`tuple` 是同一物件" + +#: ../../c-api/tuple.rst:24 +msgid "" +"Return true if *p* is a tuple object or an instance of a subtype of the " +"tuple type. This function always succeeds." +msgstr "" +"如果 *p* 為一元組物件或是元組型別的子型別實例時回傳 true。此函式總會執行成功" + +#: ../../c-api/tuple.rst:30 +msgid "" +"Return true if *p* is a tuple object, but not an instance of a subtype of " +"the tuple type. This function always succeeds." +msgstr "" +"如果 *p* 為一元組物件但不是元組型別的子型別實例時回傳 true。此函式總會執行成" +"功" + +#: ../../c-api/tuple.rst:36 +msgid "" +"Return a new tuple object of size *len*, or ``NULL`` with an exception set " +"on failure." +msgstr "回傳一個長度為 *len* 的新元組物件，失敗會時回傳 ``NULL`` 並設定例外。" + +#: ../../c-api/tuple.rst:42 +msgid "" +"Return a new tuple object of size *n*, or ``NULL`` with an exception set on " +"failure. The tuple values are initialized to the subsequent *n* C arguments " +"pointing to Python objects. ``PyTuple_Pack(2, a, b)`` is equivalent to " +"``Py_BuildValue(\"(OO)\", a, b)``." +msgstr "" +"回傳一個長度為 *n* 的新元組物件，失敗時會回傳 ``NULL`` 並設定例外。元組值被初" +"始化為指向 Python 物件的接續 *n* 個 C 引數。``PyTuple_Pack(2, a, b)`` 等價於 " +"``Py_BuildValue(\"(OO)\", a, b)``。" + +#: ../../c-api/tuple.rst:50 +msgid "" +"Take a pointer to a tuple object, and return the size of that tuple. On " +"error, return ``-1`` with an exception set." +msgstr "" +"拿取一個元組物件的指標，然後回傳此元組的大小。錯誤發生時，回傳 ``-1`` 並設定" +"例外。" + +#: ../../c-api/tuple.rst:56 +msgid "Like :c:func:`PyTuple_Size`, but without error checking." +msgstr "就像 :c:func:`PyTuple_Size` 但沒有錯誤檢查。" + +#: ../../c-api/tuple.rst:61 +msgid "" +"Return the object at position *pos* in the tuple pointed to by *p*. If " +"*pos* is negative or out of bounds, return ``NULL`` and set an :exc:" +"`IndexError` exception." +msgstr "" +"回傳 *p* 指向的元組中位置 *pos* 處的物件。如果 *pos* 為負數或超出範圍，回傳 " +"``NULL`` 並設定 :exc:`IndexError` 例外。" + +#: ../../c-api/tuple.rst:64 +msgid "" +"The returned reference is borrowed from the tuple *p* (that is: it is only " +"valid as long as you hold a reference to *p*). To get a :term:`strong " +"reference`, use :c:func:`Py_NewRef(PyTuple_GetItem(...)) ` or :c:" +"func:`PySequence_GetItem`." +msgstr "" +"回傳的參照借自元組 *p*\\ （也就是說：它僅在你持有 *p* 的參照時有效）。若要取" +"得一個 :term:`strong reference`，請使用 :c:func:" +"`Py_NewRef(PyTuple_GetItem(...)) ` 或 :c:func:" +"`PySequence_GetItem`。" + +#: ../../c-api/tuple.rst:73 +msgid "Like :c:func:`PyTuple_GetItem`, but does no checking of its arguments." +msgstr "與 :c:func:`PyTuple_GetItem` 相似，但不檢查其引數。" + +#: ../../c-api/tuple.rst:78 +msgid "" +"Return the slice of the tuple pointed to by *p* between *low* and *high*, or " +"``NULL`` with an exception set on failure." +msgstr "" +"回傳由 *p* 指向的元組中介於 *low* 和 *high* 之間的切片或在錯誤時回傳 " +"``NULL`` 並設定例外。" + +#: ../../c-api/tuple.rst:81 +msgid "" +"This is the equivalent of the Python expression ``p[low:high]``. Indexing " +"from the end of the tuple is not supported." +msgstr "這與 Python ``p[low:high]`` 運算式等價。但不支援從元組末端開始索引。" + +#: ../../c-api/tuple.rst:87 +msgid "" +"Insert a reference to object *o* at position *pos* of the tuple pointed to " +"by *p*. Return ``0`` on success. If *pos* is out of bounds, return ``-1`` " +"and set an :exc:`IndexError` exception." +msgstr "" +"於 *p* 指向的元組 *pos* 位置處插入對物件 *o* 的參照。成功時回傳 ``0``，如果 " +"*pos* 超出邊界則回傳 ``-1``，並設定 :exc:`IndexError` 例外。" + +#: ../../c-api/tuple.rst:93 +msgid "" +"This function \"steals\" a reference to *o* and discards a reference to an " +"item already in the tuple at the affected position." +msgstr "此函式 \"竊取\" 對 *o* 的參照，並丟棄對元組中受影響位置的項目的參照。" + +#: ../../c-api/tuple.rst:99 +msgid "" +"Like :c:func:`PyTuple_SetItem`, but does no error checking, and should " +"*only* be used to fill in brand new tuples." +msgstr "" +"與 :c:func:`PyTuple_SetItem` 相似，但不進行錯誤檢查，且應 *只* 用於填充全新的" +"元組。" + +#: ../../c-api/tuple.rst:102 ../../c-api/tuple.rst:224 +#: ../../c-api/tuple.rst:242 +msgid "" +"Bounds checking is performed as an assertion if Python is built in :ref:" +"`debug mode ` or :option:`with assertions <--with-assertions>`." +msgstr "" +"若 Python 以 :ref:`debug mode ` 或 :option:`with assertions <--" +"with-assertions>` 建置，則會進行作為斷言（asserting）的邊界檢查。" + +#: ../../c-api/tuple.rst:107 +msgid "" +"This function \"steals\" a reference to *o*, and, unlike :c:func:" +"`PyTuple_SetItem`, does *not* discard a reference to any item that is being " +"replaced; any reference in the tuple at position *pos* will be leaked." +msgstr "" +"此函式 \"竊取\" 對 *o* 的參照，且與 :c:func:`PyTuple_SetItem` 不同的是，此函" +"式並 *不* 丟棄任何被替代項目的參照；元組中 *pos* 位置的所有參照皆會被洩漏。" + +#: ../../c-api/tuple.rst:114 +msgid "" +"This macro should *only* be used on tuples that are newly created. Using " +"this macro on a tuple that is already in use (or in other words, has a " +"refcount > 1) could lead to undefined behavior." +msgstr "" +"此巨集應 *僅* 用於新建立的元組。在正被使用中的元組（或換句話說，參照計數大於 " +"1 的元組）上使用此巨集可能會導致未定義行為。" + +#: ../../c-api/tuple.rst:121 +msgid "" +"Can be used to resize a tuple. *newsize* will be the new length of the " +"tuple. Because tuples are *supposed* to be immutable, this should only be " +"used if there is only one reference to the object. Do *not* use this if the " +"tuple may already be known to some other part of the code. The tuple will " +"always grow or shrink at the end. Think of this as destroying the old tuple " +"and creating a new one, only more efficiently. Returns ``0`` on success. " +"Client code should never assume that the resulting value of ``*p`` will be " +"the same as before calling this function. If the object referenced by ``*p`` " +"is replaced, the original ``*p`` is destroyed. On failure, returns ``-1`` " +"and sets ``*p`` to ``NULL``, and raises :exc:`MemoryError` or :exc:" +"`SystemError`." +msgstr "" +"可用於調整元組的大小。*newsize* 將是元組的新長度。由於元組 *應該* 是不可變" +"的，因此僅當物件只有一個參照時才應使用此方法。如果程式碼的其他部分已經知道該" +"元組，則 *不要* 使用此方法。最終元組總會變大或縮小。可以將其理解為銷毀舊元組" +"並建立一個新元組，只是有著更高的效率。成功時回傳 ``0``。用戶端程式碼絕不應假" +"設 ``*p`` 的結果值與呼叫此函式之前的值相同。如果 ``*p`` 參照的物件被替換，則" +"原始的 ``*p`` 將被銷毀。失敗時，回傳 ``-1``，並將 ``*p`` 設定為 ``NULL``，並" +"引發 :exc:`MemoryError` 或 :exc:`SystemError` 例外。" + +#: ../../c-api/tuple.rst:136 +msgid "Struct Sequence Objects" +msgstr "結構序列物件" + +#: ../../c-api/tuple.rst:138 +msgid "" +"Struct sequence objects are the C equivalent of :func:`~collections." +"namedtuple` objects, i.e. a sequence whose items can also be accessed " +"through attributes. To create a struct sequence, you first have to create a " +"specific struct sequence type." +msgstr "" +"結構序列物件是 :func:`~collections.namedtuple` 物件在 C 語言中的等價，換言" +"之，一個序列的元素也可以透過屬性存取。要建立結構序列，首先需要建立特定的結構" +"序列型別。" + +#: ../../c-api/tuple.rst:145 +msgid "" +"Create a new struct sequence type from the data in *desc*, described below. " +"Instances of the resulting type can be created with :c:func:" +"`PyStructSequence_New`." +msgstr "" +"從 *desc* 中的資料建立一個新的結構序列型別，如下所述。可以使用 :c:func:" +"`PyStructSequence_New` 以建立產生結構序列型別的實例。" + +#: ../../c-api/tuple.rst:148 ../../c-api/tuple.rst:217 +msgid "Return ``NULL`` with an exception set on failure." +msgstr "失敗時回傳 ``NULL`` 並設定例外。" + +#: ../../c-api/tuple.rst:153 +msgid "Initializes a struct sequence type *type* from *desc* in place." +msgstr "從 *desc* 原地（in place）初始化結構序列型別 *type*。" + +#: ../../c-api/tuple.rst:158 +msgid "" +"Like :c:func:`PyStructSequence_InitType`, but returns ``0`` on success and " +"``-1`` with an exception set on failure." +msgstr "" +"與 :c:func:`PyStructSequence_InitType` 相似，但運行成功時回傳 ``0``，運行失敗" +"時回傳 ``-1`` 並設定例外。" + +#: ../../c-api/tuple.rst:166 +msgid "Contains the meta information of a struct sequence type to create." +msgstr "包含要建立的結構序列化型別的中介資訊（meta information）。" + +#: ../../c-api/tuple.rst:170 +msgid "" +"Fully qualified name of the type; null-terminated UTF-8 encoded. The name " +"must contain the module name." +msgstr "" +"型別的完整限定名稱（Fully qualified name）；以 UTF-8 編碼並以空字元結尾。名稱" +"必須包含完整的模組名稱。" + +#: ../../c-api/tuple.rst:175 +msgid "Pointer to docstring for the type or ``NULL`` to omit." +msgstr "指向型別說明文件（docstring）的指標或使用 ``NULL`` 表示忽略。" + +#: ../../c-api/tuple.rst:179 +msgid "Pointer to ``NULL``-terminated array with field names of the new type." +msgstr "指向一個以 ``NULL`` 結尾的陣列指標，其包含新型別的欄位名稱。" + +#: ../../c-api/tuple.rst:183 +msgid "Number of fields visible to the Python side (if used as tuple)." +msgstr "Python 端可以看到欄位的數目（如果作為元組使用）。" + +#: ../../c-api/tuple.rst:188 +msgid "" +"Describes a field of a struct sequence. As a struct sequence is modeled as a " +"tuple, all fields are typed as :c:expr:`PyObject*`. The index in the :c:" +"member:`~PyStructSequence_Desc.fields` array of the :c:type:" +"`PyStructSequence_Desc` determines which field of the struct sequence is " +"described." +msgstr "" +"描述結構序列的一個欄位。由於結構序列以元組作為原型，所有欄位的型別均為 :c:" +"expr:`PyObject*`。:c:type:`PyStructSequence_Desc` 在 :c:member:" +"`~PyStructSequence_Desc.fields` 陣列中的索引決定了描述的是結構序列的哪個欄" +"位。" + +#: ../../c-api/tuple.rst:196 +msgid "" +"Name for the field or ``NULL`` to end the list of named fields, set to :c:" +"data:`PyStructSequence_UnnamedField` to leave unnamed." +msgstr "" +"欄位名稱，或 ``NULL`` 表示命名欄位串列結束，設定為 :c:data:" +"`PyStructSequence_UnnamedField` 表示該欄位不命名。" + +#: ../../c-api/tuple.rst:201 +msgid "Field docstring or ``NULL`` to omit." +msgstr "欄位說明字串或為 ``NULL`` 表示忽略。" + +#: ../../c-api/tuple.rst:206 +msgid "Special value for a field name to leave it unnamed." +msgstr "給定欄位名稱一個特別值，表示該欄位不命名。" + +#: ../../c-api/tuple.rst:208 +msgid "The type was changed from ``char *``." +msgstr "型別原本是 ``char *``，現已被修改。" + +#: ../../c-api/tuple.rst:214 +msgid "" +"Creates an instance of *type*, which must have been created with :c:func:" +"`PyStructSequence_NewType`." +msgstr "建立 *type* 的實例，必須以 :c:func:`PyStructSequence_NewType` 建立。" + +#: ../../c-api/tuple.rst:222 +msgid "" +"Return the object at position *pos* in the struct sequence pointed to by *p*." +msgstr "回傳結構序列中由 *p* 指向 *pos* 處的物件。" + +#: ../../c-api/tuple.rst:230 +msgid "Alias to :c:func:`PyStructSequence_GetItem`." +msgstr ":c:func:`PyStructSequence_GetItem` 的別名。" + +#: ../../c-api/tuple.rst:232 +msgid "Now implemented as an alias to :c:func:`PyStructSequence_GetItem`." +msgstr "現在是被實作為 :c:func:`PyStructSequence_GetItem` 的一個別名。" + +#: ../../c-api/tuple.rst:238 +msgid "" +"Sets the field at index *pos* of the struct sequence *p* to value *o*. " +"Like :c:func:`PyTuple_SET_ITEM`, this should only be used to fill in brand " +"new instances." +msgstr "" +"將結構序列 *p* 中索引 *pos* 處的欄位值設為 *o*。與 :c:func:" +"`PyTuple_SET_ITEM` 類似，此函式僅套用於填充全新實例。" + +#: ../../c-api/tuple.rst:247 +msgid "This function \"steals\" a reference to *o*." +msgstr "此函式 \"竊取\" *o* 的參照。" + +#: ../../c-api/tuple.rst:252 +msgid "Alias to :c:func:`PyStructSequence_SetItem`." +msgstr ":c:func:`PyStructSequence_SetItem` 的別名。" + +#: ../../c-api/tuple.rst:254 +msgid "Now implemented as an alias to :c:func:`PyStructSequence_SetItem`." +msgstr "現在是被實作為 :c:func:`PyStructSequence_SetItem` 的一個別名。" + +#: ../../c-api/tuple.rst:8 +msgid "object" +msgstr "object（物件）" + +#: ../../c-api/tuple.rst:8 +msgid "tuple" +msgstr "tuple（元組）" diff --git a/c-api/type.po b/c-api/type.po index f5ecca5936..b518f8ff41 100644 --- a/c-api/type.po +++ b/c-api/type.po @@ -1,849 +1,849 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-22 00:14+0000\n" -"PO-Revision-Date: 2015-12-09 17:51+0000\n" -"Last-Translator: Liang-Bo Wang \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" - -#: ../../c-api/type.rst:6 -msgid "Type Objects" -msgstr "型別物件" - -#: ../../c-api/type.rst:13 -msgid "The C structure of the objects used to describe built-in types." -msgstr "" - -#: ../../c-api/type.rst:18 -msgid "" -"This is the type object for type objects; it is the same object as :class:" -"`type` in the Python layer." -msgstr "" - -#: ../../c-api/type.rst:24 -msgid "" -"Return non-zero if the object *o* is a type object, including instances of " -"types derived from the standard type object. Return 0 in all other cases. " -"This function always succeeds." -msgstr "" - -#: ../../c-api/type.rst:31 -msgid "" -"Return non-zero if the object *o* is a type object, but not a subtype of the " -"standard type object. Return 0 in all other cases. This function always " -"succeeds." -msgstr "" - -#: ../../c-api/type.rst:38 -msgid "Clear the internal lookup cache. Return the current version tag." -msgstr "" - -#: ../../c-api/type.rst:42 -msgid "" -"Return the :c:member:`~PyTypeObject.tp_flags` member of *type*. This " -"function is primarily meant for use with ``Py_LIMITED_API``; the individual " -"flag bits are guaranteed to be stable across Python releases, but access to :" -"c:member:`~PyTypeObject.tp_flags` itself is not part of the :ref:`limited " -"API `." -msgstr "" - -#: ../../c-api/type.rst:49 -msgid "The return type is now ``unsigned long`` rather than ``long``." -msgstr "" - -#: ../../c-api/type.rst:55 -msgid "" -"Return the type object's internal namespace, which is otherwise only exposed " -"via a read-only proxy (:attr:`cls.__dict__ `). This is a " -"replacement for accessing :c:member:`~PyTypeObject.tp_dict` directly. The " -"returned dictionary must be treated as read-only." -msgstr "" - -#: ../../c-api/type.rst:61 -msgid "" -"This function is meant for specific embedding and language-binding cases, " -"where direct access to the dict is necessary and indirect access (e.g. via " -"the proxy or :c:func:`PyObject_GetAttr`) isn't adequate." -msgstr "" - -#: ../../c-api/type.rst:65 -msgid "" -"Extension modules should continue to use ``tp_dict``, directly or " -"indirectly, when setting up their own types." -msgstr "" - -#: ../../c-api/type.rst:73 -msgid "" -"Invalidate the internal lookup cache for the type and all of its subtypes. " -"This function must be called after any manual modification of the attributes " -"or base classes of the type." -msgstr "" - -#: ../../c-api/type.rst:80 -msgid "" -"Register *callback* as a type watcher. Return a non-negative integer ID " -"which must be passed to future calls to :c:func:`PyType_Watch`. In case of " -"error (e.g. no more watcher IDs available), return ``-1`` and set an " -"exception." -msgstr "" - -#: ../../c-api/type.rst:85 -msgid "" -"In free-threaded builds, :c:func:`PyType_AddWatcher` is not thread-safe, so " -"it must be called at start up (before spawning the first thread)." -msgstr "" - -#: ../../c-api/type.rst:93 -msgid "" -"Clear watcher identified by *watcher_id* (previously returned from :c:func:" -"`PyType_AddWatcher`). Return ``0`` on success, ``-1`` on error (e.g. if " -"*watcher_id* was never registered.)" -msgstr "" - -#: ../../c-api/type.rst:97 -msgid "" -"An extension should never call ``PyType_ClearWatcher`` with a *watcher_id* " -"that was not returned to it by a previous call to :c:func:" -"`PyType_AddWatcher`." -msgstr "" - -#: ../../c-api/type.rst:106 -msgid "" -"Mark *type* as watched. The callback granted *watcher_id* by :c:func:" -"`PyType_AddWatcher` will be called whenever :c:func:`PyType_Modified` " -"reports a change to *type*. (The callback may be called only once for a " -"series of consecutive modifications to *type*, if :c:func:`!_PyType_Lookup` " -"is not called on *type* between the modifications; this is an implementation " -"detail and subject to change.)" -msgstr "" - -#: ../../c-api/type.rst:113 -msgid "" -"An extension should never call ``PyType_Watch`` with a *watcher_id* that was " -"not returned to it by a previous call to :c:func:`PyType_AddWatcher`." -msgstr "" - -#: ../../c-api/type.rst:121 -msgid "" -"Mark *type* as not watched. This undoes a previous call to :c:func:" -"`PyType_Watch`. *type* must not be ``NULL``." -msgstr "" - -#: ../../c-api/type.rst:124 -msgid "" -"An extension should never call this function with a *watcher_id* that was " -"not returned to it by a previous call to :c:func:`PyType_AddWatcher`." -msgstr "" - -#: ../../c-api/type.rst:127 -msgid "" -"On success, this function returns ``0``. On failure, this function returns " -"``-1`` with an exception set." -msgstr "成功時此函式會回傳 ``0``。失敗時此函式回傳 ``-1`` 並設定例外。" - -#: ../../c-api/type.rst:135 -msgid "Type of a type-watcher callback function." -msgstr "" - -#: ../../c-api/type.rst:137 -msgid "" -"The callback must not modify *type* or cause :c:func:`PyType_Modified` to be " -"called on *type* or any type in its MRO; violating this rule could cause " -"infinite recursion." -msgstr "" - -#: ../../c-api/type.rst:146 -msgid "" -"Return non-zero if the type object *o* sets the feature *feature*. Type " -"features are denoted by single bit flags." -msgstr "" - -#: ../../c-api/type.rst:152 -msgid "" -"Return non-zero if the type object *type* sets the subclass flag *flag*. " -"Subclass flags are denoted by :c:macro:`Py_TPFLAGS_*_SUBCLASS " -"`. This function is used by many ``_Check`` " -"functions for common types." -msgstr "" - -#: ../../c-api/type.rst:158 -msgid "" -":c:func:`PyObject_TypeCheck`, which is used as a slower alternative in " -"``_Check`` functions for types that don't come with subclass flags." -msgstr "" - -#: ../../c-api/type.rst:164 -msgid "" -"Return true if the type object includes support for the cycle detector; this " -"tests the type flag :c:macro:`Py_TPFLAGS_HAVE_GC`." -msgstr "" - -#: ../../c-api/type.rst:170 -msgid "Return true if *a* is a subtype of *b*." -msgstr "如果 *a* 是 *b* 的子類別則回傳 true。" - -#: ../../c-api/type.rst:172 -msgid "" -"This function only checks for actual subtypes, which means that :meth:`~type." -"__subclasscheck__` is not called on *b*. Call :c:func:`PyObject_IsSubclass` " -"to do the same check that :func:`issubclass` would do." -msgstr "" - -#: ../../c-api/type.rst:180 -msgid "" -"Generic handler for the :c:member:`~PyTypeObject.tp_alloc` slot of a type " -"object. Uses Python's default memory allocation mechanism to allocate " -"memory for a new instance, zeros the memory, then initializes the memory as " -"if by calling :c:func:`PyObject_Init` or :c:func:`PyObject_InitVar`." -msgstr "" - -#: ../../c-api/type.rst:185 -msgid "" -"Do not call this directly to allocate memory for an object; call the type's :" -"c:member:`~PyTypeObject.tp_alloc` slot instead." -msgstr "" - -#: ../../c-api/type.rst:188 -msgid "" -"For types that support garbage collection (i.e., the :c:macro:" -"`Py_TPFLAGS_HAVE_GC` flag is set), this function behaves like :c:macro:" -"`PyObject_GC_New` or :c:macro:`PyObject_GC_NewVar` (except the memory is " -"guaranteed to be zeroed before initialization), and should be paired with :c:" -"func:`PyObject_GC_Del` in :c:member:`~PyTypeObject.tp_free`. Otherwise, it " -"behaves like :c:macro:`PyObject_New` or :c:macro:`PyObject_NewVar` (except " -"the memory is guaranteed to be zeroed before initialization) and should be " -"paired with :c:func:`PyObject_Free` in :c:member:`~PyTypeObject.tp_free`." -msgstr "" - -#: ../../c-api/type.rst:201 -msgid "" -"Generic handler for the :c:member:`~PyTypeObject.tp_new` slot of a type " -"object. Creates a new instance using the type's :c:member:`~PyTypeObject." -"tp_alloc` slot and returns the resulting object." -msgstr "" - -#: ../../c-api/type.rst:208 -msgid "" -"Finalize a type object. This should be called on all type objects to finish " -"their initialization. This function is responsible for adding inherited " -"slots from a type's base class. Return ``0`` on success, or return ``-1`` " -"and sets an exception on error." -msgstr "" - -#: ../../c-api/type.rst:214 -msgid "" -"If some of the base classes implements the GC protocol and the provided type " -"does not include the :c:macro:`Py_TPFLAGS_HAVE_GC` in its flags, then the GC " -"protocol will be automatically implemented from its parents. On the " -"contrary, if the type being created does include :c:macro:" -"`Py_TPFLAGS_HAVE_GC` in its flags then it **must** implement the GC protocol " -"itself by at least implementing the :c:member:`~PyTypeObject.tp_traverse` " -"handle." -msgstr "" - -#: ../../c-api/type.rst:225 -msgid "" -"Return the type's name. Equivalent to getting the type's :attr:`~type." -"__name__` attribute." -msgstr "" - -#: ../../c-api/type.rst:233 -msgid "" -"Return the type's qualified name. Equivalent to getting the type's :attr:" -"`~type.__qualname__` attribute." -msgstr "" - -#: ../../c-api/type.rst:240 -msgid "" -"Return the type's fully qualified name. Equivalent to ``f\"{type.__module__}." -"{type.__qualname__}\"``, or :attr:`type.__qualname__` if :attr:`type." -"__module__` is not a string or is equal to ``\"builtins\"``." -msgstr "" - -#: ../../c-api/type.rst:249 -msgid "" -"Return the type's module name. Equivalent to getting the :attr:`type." -"__module__` attribute." -msgstr "" - -#: ../../c-api/type.rst:257 -msgid "" -"Return the function pointer stored in the given slot. If the result is " -"``NULL``, this indicates that either the slot is ``NULL``, or that the " -"function was called with invalid parameters. Callers will typically cast the " -"result pointer into the appropriate function type." -msgstr "" - -#: ../../c-api/type.rst:263 -msgid "" -"See :c:member:`PyType_Slot.slot` for possible values of the *slot* argument." -msgstr "" - -#: ../../c-api/type.rst:267 -msgid "" -":c:func:`PyType_GetSlot` can now accept all types. Previously, it was " -"limited to :ref:`heap types `." -msgstr "" - -#: ../../c-api/type.rst:274 -msgid "" -"Return the module object associated with the given type when the type was " -"created using :c:func:`PyType_FromModuleAndSpec`." -msgstr "" - -#: ../../c-api/type.rst:277 ../../c-api/type.rst:298 -msgid "" -"If no module is associated with the given type, sets :py:class:`TypeError` " -"and returns ``NULL``." -msgstr "" - -#: ../../c-api/type.rst:280 -msgid "" -"This function is usually used to get the module in which a method is " -"defined. Note that in such a method, ``PyType_GetModule(Py_TYPE(self))`` may " -"not return the intended result. ``Py_TYPE(self)`` may be a *subclass* of the " -"intended class, and subclasses are not necessarily defined in the same " -"module as their superclass. See :c:type:`PyCMethod` to get the class that " -"defines the method. See :c:func:`PyType_GetModuleByDef` for cases when :c:" -"type:`!PyCMethod` cannot be used." -msgstr "" - -#: ../../c-api/type.rst:294 -msgid "" -"Return the state of the module object associated with the given type. This " -"is a shortcut for calling :c:func:`PyModule_GetState()` on the result of :c:" -"func:`PyType_GetModule`." -msgstr "" - -#: ../../c-api/type.rst:301 -msgid "" -"If the *type* has an associated module but its state is ``NULL``, returns " -"``NULL`` without setting an exception." -msgstr "" - -#: ../../c-api/type.rst:309 -msgid "" -"Find the first superclass whose module was created from the given :c:type:" -"`PyModuleDef` *def*, and return that module." -msgstr "" - -#: ../../c-api/type.rst:312 -msgid "" -"If no module is found, raises a :py:class:`TypeError` and returns ``NULL``." -msgstr "" - -#: ../../c-api/type.rst:314 -msgid "" -"This function is intended to be used together with :c:func:" -"`PyModule_GetState()` to get module state from slot methods (such as :c:" -"member:`~PyTypeObject.tp_init` or :c:member:`~PyNumberMethods.nb_add`) and " -"other places where a method's defining class cannot be passed using the :c:" -"type:`PyCMethod` calling convention." -msgstr "" - -#: ../../c-api/type.rst:320 -msgid "" -"The returned reference is :term:`borrowed ` from *type*, " -"and will be valid as long as you hold a reference to *type*. Do not release " -"it with :c:func:`Py_DECREF` or similar." -msgstr "" - -#: ../../c-api/type.rst:329 -msgid "" -"Find the first superclass in *type*'s :term:`method resolution order` whose :" -"c:macro:`Py_tp_token` token is equal to the given one." -msgstr "" - -#: ../../c-api/type.rst:332 -msgid "" -"If found, set *\\*result* to a new :term:`strong reference` to it and return " -"``1``." -msgstr "" - -#: ../../c-api/type.rst:334 -msgid "If not found, set *\\*result* to ``NULL`` and return ``0``." -msgstr "如果沒找到，則將 *\\*result* 設為 ``NULL`` 並回傳 ``0``。" - -#: ../../c-api/type.rst:335 -msgid "" -"On error, set *\\*result* to ``NULL`` and return ``-1`` with an exception " -"set." -msgstr "" -"在發生錯誤時，將 *\\*result* 設為 ``NULL`` 並回傳 ``-1``，同時設定例外。" - -#: ../../c-api/type.rst:338 -msgid "" -"The *result* argument may be ``NULL``, in which case *\\*result* is not set. " -"Use this if you need only the return value." -msgstr "" -"如果 *result* 引數為 ``NULL``，則不會設定 *\\*result*。如果你只需要回傳值，請" -"使用此選項。" - -#: ../../c-api/type.rst:341 -msgid "The *token* argument may not be ``NULL``." -msgstr "*token* 引數不可為 ``NULL``。" - -#: ../../c-api/type.rst:348 -msgid "Attempt to assign a version tag to the given type." -msgstr "" - -#: ../../c-api/type.rst:350 -msgid "" -"Returns 1 if the type already had a valid version tag or a new one was " -"assigned, or 0 if a new tag could not be assigned." -msgstr "" - -#: ../../c-api/type.rst:358 -msgid "" -"Return true if instances of *type* support creating weak references, false " -"otherwise. This function always succeeds. *type* must not be ``NULL``." -msgstr "" - -#: ../../c-api/type.rst:362 -msgid ":ref:`weakrefobjects`" -msgstr ":ref:`weakrefobjects`" - -#: ../../c-api/type.rst:363 -msgid ":py:mod:`weakref`" -msgstr ":py:mod:`weakref`" - -#: ../../c-api/type.rst:367 -msgid "Creating Heap-Allocated Types" -msgstr "" - -#: ../../c-api/type.rst:369 -msgid "" -"The following functions and structs are used to create :ref:`heap types " -"`." -msgstr "" - -#: ../../c-api/type.rst:374 -msgid "" -"Create and return a :ref:`heap type ` from the *spec* (see :c:" -"macro:`Py_TPFLAGS_HEAPTYPE`)." -msgstr "" - -#: ../../c-api/type.rst:377 -msgid "" -"The metaclass *metaclass* is used to construct the resulting type object. " -"When *metaclass* is ``NULL``, the metaclass is derived from *bases* (or " -"*Py_tp_base[s]* slots if *bases* is ``NULL``, see below)." -msgstr "" - -#: ../../c-api/type.rst:381 -msgid "" -"Metaclasses that override :c:member:`~PyTypeObject.tp_new` are not " -"supported, except if ``tp_new`` is ``NULL``." -msgstr "" - -#: ../../c-api/type.rst:384 -msgid "" -"The *bases* argument can be used to specify base classes; it can either be " -"only one class or a tuple of classes. If *bases* is ``NULL``, the :c:data:" -"`Py_tp_bases` slot is used instead. If that also is ``NULL``, the :c:data:" -"`Py_tp_base` slot is used instead. If that also is ``NULL``, the new type " -"derives from :class:`object`." -msgstr "" - -#: ../../c-api/type.rst:390 -msgid "" -"The *module* argument can be used to record the module in which the new " -"class is defined. It must be a module object or ``NULL``. If not ``NULL``, " -"the module is associated with the new type and can later be retrieved with :" -"c:func:`PyType_GetModule`. The associated module is not inherited by " -"subclasses; it must be specified for each class individually." -msgstr "" - -#: ../../c-api/type.rst:397 -msgid "This function calls :c:func:`PyType_Ready` on the new type." -msgstr "" - -#: ../../c-api/type.rst:399 -msgid "" -"Note that this function does *not* fully match the behavior of calling :py:" -"class:`type() ` or using the :keyword:`class` statement. With user-" -"provided base types or metaclasses, prefer :ref:`calling ` :py:" -"class:`type` (or the metaclass) over ``PyType_From*`` functions. " -"Specifically:" -msgstr "" - -#: ../../c-api/type.rst:406 -msgid "" -":py:meth:`~object.__new__` is not called on the new class (and it must be " -"set to ``type.__new__``)." -msgstr "" -":py:meth:`~object.__new__` 不會在新類別上被呼叫（且它必須被設為 ``type." -"__new__``）。" - -#: ../../c-api/type.rst:408 -msgid ":py:meth:`~object.__init__` is not called on the new class." -msgstr ":py:meth:`~object.__init__` 不會在新類別上被呼叫。" - -#: ../../c-api/type.rst:409 -msgid ":py:meth:`~object.__init_subclass__` is not called on any bases." -msgstr ":py:meth:`~object.__init_subclass__` 不會在任何基底上被呼叫。" - -#: ../../c-api/type.rst:410 -msgid ":py:meth:`~object.__set_name__` is not called on new descriptors." -msgstr ":py:meth:`~object.__set_name__` 不會在新的描述器上被呼叫。" - -#: ../../c-api/type.rst:417 -msgid "Equivalent to ``PyType_FromMetaclass(NULL, module, spec, bases)``." -msgstr "等價於 ``PyType_FromMetaclass(NULL, module, spec, bases)``。" - -#: ../../c-api/type.rst:423 -msgid "" -"The function now accepts a single class as the *bases* argument and ``NULL`` " -"as the ``tp_doc`` slot." -msgstr "" - -#: ../../c-api/type.rst:428 ../../c-api/type.rst:450 -msgid "" -"The function now finds and uses a metaclass corresponding to the provided " -"base classes. Previously, only :class:`type` instances were returned." -msgstr "" - -#: ../../c-api/type.rst:431 ../../c-api/type.rst:453 ../../c-api/type.rst:474 -msgid "" -"The :c:member:`~PyTypeObject.tp_new` of the metaclass is *ignored*. which " -"may result in incomplete initialization. Creating classes whose metaclass " -"overrides :c:member:`~PyTypeObject.tp_new` is deprecated." -msgstr "" - -#: ../../c-api/type.rst:438 ../../c-api/type.rst:460 ../../c-api/type.rst:481 -msgid "" -"Creating classes whose metaclass overrides :c:member:`~PyTypeObject.tp_new` " -"is no longer allowed." -msgstr "" - -#: ../../c-api/type.rst:444 -msgid "Equivalent to ``PyType_FromMetaclass(NULL, NULL, spec, bases)``." -msgstr "等價於 ``PyType_FromMetaclass(NULL, NULL, spec, bases)``。" - -#: ../../c-api/type.rst:466 -msgid "Equivalent to ``PyType_FromMetaclass(NULL, NULL, spec, NULL)``." -msgstr "等價於 ``PyType_FromMetaclass(NULL, NULL, spec, NULL)``。" - -#: ../../c-api/type.rst:470 -msgid "" -"The function now finds and uses a metaclass corresponding to the base " -"classes provided in *Py_tp_base[s]* slots. Previously, only :class:`type` " -"instances were returned." -msgstr "" - -#: ../../c-api/type.rst:487 -msgid "" -"Make a type immutable: set the :c:macro:`Py_TPFLAGS_IMMUTABLETYPE` flag." -msgstr "" - -#: ../../c-api/type.rst:489 -msgid "All base classes of *type* must be immutable." -msgstr "所有 *type* 的基底類別都必須是不可變的。" - -#: ../../c-api/type.rst:491 -msgid "On success, return ``0``. On error, set an exception and return ``-1``." -msgstr "" - -#: ../../c-api/type.rst:494 -msgid "" -"The type must not be used before it's made immutable. For example, type " -"instances must not be created before the type is made immutable." -msgstr "" - -#: ../../c-api/type.rst:510 -msgid "Structure defining a type's behavior." -msgstr "" - -#: ../../c-api/type.rst:514 -msgid "Name of the type, used to set :c:member:`PyTypeObject.tp_name`." -msgstr "" - -#: ../../c-api/type.rst:518 -msgid "" -"If positive, specifies the size of the instance in bytes. It is used to set :" -"c:member:`PyTypeObject.tp_basicsize`." -msgstr "" - -#: ../../c-api/type.rst:521 -msgid "" -"If zero, specifies that :c:member:`~PyTypeObject.tp_basicsize` should be " -"inherited." -msgstr "" - -#: ../../c-api/type.rst:524 -msgid "" -"If negative, the absolute value specifies how much space instances of the " -"class need *in addition* to the superclass. Use :c:func:" -"`PyObject_GetTypeData` to get a pointer to subclass-specific memory reserved " -"this way. For negative :c:member:`!basicsize`, Python will insert padding " -"when needed to meet :c:member:`~PyTypeObject.tp_basicsize`'s alignment " -"requirements." -msgstr "" - -#: ../../c-api/type.rst:534 -msgid "Previously, this field could not be negative." -msgstr "在過去此欄位不可為負值。" - -#: ../../c-api/type.rst:538 -msgid "" -"Size of one element of a variable-size type, in bytes. Used to set :c:member:" -"`PyTypeObject.tp_itemsize`. See ``tp_itemsize`` documentation for caveats." -msgstr "" - -#: ../../c-api/type.rst:542 -msgid "" -"If zero, :c:member:`~PyTypeObject.tp_itemsize` is inherited. Extending " -"arbitrary variable-sized classes is dangerous, since some types use a fixed " -"offset for variable-sized memory, which can then overlap fixed-sized memory " -"used by a subclass. To help prevent mistakes, inheriting ``itemsize`` is " -"only possible in the following situations:" -msgstr "" - -#: ../../c-api/type.rst:549 -msgid "" -"The base is not variable-sized (its :c:member:`~PyTypeObject.tp_itemsize`)." -msgstr "" - -#: ../../c-api/type.rst:551 -msgid "" -"The requested :c:member:`PyType_Spec.basicsize` is positive, suggesting that " -"the memory layout of the base class is known." -msgstr "" - -#: ../../c-api/type.rst:553 -msgid "" -"The requested :c:member:`PyType_Spec.basicsize` is zero, suggesting that the " -"subclass does not access the instance's memory directly." -msgstr "" - -#: ../../c-api/type.rst:556 -msgid "With the :c:macro:`Py_TPFLAGS_ITEMS_AT_END` flag." -msgstr "" - -#: ../../c-api/type.rst:560 -msgid "Type flags, used to set :c:member:`PyTypeObject.tp_flags`." -msgstr "" - -#: ../../c-api/type.rst:562 -msgid "" -"If the ``Py_TPFLAGS_HEAPTYPE`` flag is not set, :c:func:" -"`PyType_FromSpecWithBases` sets it automatically." -msgstr "" -"如果未設定 ``Py_TPFLAGS_HEAPTYPE`` 旗標，則 :c:func:" -"`PyType_FromSpecWithBases` 會自動設定它。" - -#: ../../c-api/type.rst:567 -msgid "" -"Array of :c:type:`PyType_Slot` structures. Terminated by the special slot " -"value ``{0, NULL}``." -msgstr "" - -#: ../../c-api/type.rst:570 -msgid "Each slot ID should be specified at most once." -msgstr "" - -#: ../../c-api/type.rst:580 -msgid "" -"Structure defining optional functionality of a type, containing a slot ID " -"and a value pointer." -msgstr "" - -#: ../../c-api/type.rst:585 -msgid "A slot ID." -msgstr "" - -#: ../../c-api/type.rst:587 -msgid "" -"Slot IDs are named like the field names of the structures :c:type:" -"`PyTypeObject`, :c:type:`PyNumberMethods`, :c:type:`PySequenceMethods`, :c:" -"type:`PyMappingMethods` and :c:type:`PyAsyncMethods` with an added ``Py_`` " -"prefix. For example, use:" -msgstr "" - -#: ../../c-api/type.rst:593 -msgid ":c:data:`Py_tp_dealloc` to set :c:member:`PyTypeObject.tp_dealloc`" -msgstr ":c:data:`Py_tp_dealloc` 以設定 :c:member:`PyTypeObject.tp_dealloc`" - -#: ../../c-api/type.rst:594 -msgid ":c:data:`Py_nb_add` to set :c:member:`PyNumberMethods.nb_add`" -msgstr ":c:data:`Py_nb_add` 以設定 :c:member:`PyNumberMethods.nb_add`" - -#: ../../c-api/type.rst:595 -msgid ":c:data:`Py_sq_length` to set :c:member:`PySequenceMethods.sq_length`" -msgstr ":c:data:`Py_sq_length` 以設定 :c:member:`PySequenceMethods.sq_length`" - -#: ../../c-api/type.rst:597 -msgid "" -"An additional slot is supported that does not correspond to a :c:type:`!" -"PyTypeObject` struct field:" -msgstr "" - -#: ../../c-api/type.rst:600 -msgid ":c:data:`Py_tp_token`" -msgstr ":c:data:`Py_tp_token`" - -#: ../../c-api/type.rst:602 -msgid "" -"The following “offset” fields cannot be set using :c:type:`PyType_Slot`:" -msgstr "" - -#: ../../c-api/type.rst:604 -msgid "" -":c:member:`~PyTypeObject.tp_weaklistoffset` (use :c:macro:" -"`Py_TPFLAGS_MANAGED_WEAKREF` instead if possible)" -msgstr "" -":c:member:`~PyTypeObject.tp_weaklistoffset`\\ （如果可能，請改用 :c:macro:" -"`Py_TPFLAGS_MANAGED_WEAKREF`）" - -#: ../../c-api/type.rst:606 -msgid "" -":c:member:`~PyTypeObject.tp_dictoffset` (use :c:macro:" -"`Py_TPFLAGS_MANAGED_DICT` instead if possible)" -msgstr "" -":c:member:`~PyTypeObject.tp_dictoffset`\\ （如果可能，請改用 :c:macro:" -"`Py_TPFLAGS_MANAGED_DICT`）" - -#: ../../c-api/type.rst:608 -msgid "" -":c:member:`~PyTypeObject.tp_vectorcall_offset` (use " -"``\"__vectorcalloffset__\"`` in :ref:`PyMemberDef `)" -msgstr "" -":c:member:`~PyTypeObject.tp_vectorcall_offset`\\ （請用 :ref:`PyMemberDef " -"` 中的 ``\"__vectorcalloffset__\"``）" - -#: ../../c-api/type.rst:612 -msgid "" -"If it is not possible to switch to a ``MANAGED`` flag (for example, for " -"vectorcall or to support Python older than 3.12), specify the offset in :c:" -"data:`Py_tp_members`. See :ref:`PyMemberDef documentation ` for details." -msgstr "" - -#: ../../c-api/type.rst:618 -msgid "" -"The following internal fields cannot be set at all when creating a heap type:" -msgstr "" - -#: ../../c-api/type.rst:621 -msgid "" -":c:member:`~PyTypeObject.tp_dict`, :c:member:`~PyTypeObject.tp_mro`, :c:" -"member:`~PyTypeObject.tp_cache`, :c:member:`~PyTypeObject.tp_subclasses`, " -"and :c:member:`~PyTypeObject.tp_weaklist`." -msgstr "" - -#: ../../c-api/type.rst:627 -msgid "" -"Setting :c:data:`Py_tp_bases` or :c:data:`Py_tp_base` may be problematic on " -"some platforms. To avoid issues, use the *bases* argument of :c:func:" -"`PyType_FromSpecWithBases` instead." -msgstr "" - -#: ../../c-api/type.rst:632 -msgid "Slots in :c:type:`PyBufferProcs` may be set in the unlimited API." -msgstr "" - -#: ../../c-api/type.rst:635 -msgid "" -":c:member:`~PyBufferProcs.bf_getbuffer` and :c:member:`~PyBufferProcs." -"bf_releasebuffer` are now available under the :ref:`limited API `." -msgstr "" - -#: ../../c-api/type.rst:640 -msgid "" -"The field :c:member:`~PyTypeObject.tp_vectorcall` can now be set using :c:" -"data:`Py_tp_vectorcall`. See the field's documentation for details." -msgstr "" - -#: ../../c-api/type.rst:647 -msgid "" -"The desired value of the slot. In most cases, this is a pointer to a " -"function." -msgstr "" - -#: ../../c-api/type.rst:650 -msgid "*pfunc* values may not be ``NULL``, except for the following slots:" -msgstr "" - -#: ../../c-api/type.rst:652 -msgid ":c:data:`Py_tp_doc`" -msgstr ":c:data:`Py_tp_doc`" - -#: ../../c-api/type.rst:653 -msgid "" -":c:data:`Py_tp_token` (for clarity, prefer :c:data:`Py_TP_USE_SPEC` rather " -"than ``NULL``)" -msgstr "" - -#: ../../c-api/type.rst:659 -msgid "" -"A :c:member:`~PyType_Slot.slot` that records a static memory layout ID for a " -"class." -msgstr "" - -#: ../../c-api/type.rst:662 -msgid "" -"If the :c:type:`PyType_Spec` of the class is statically allocated, the token " -"can be set to the spec using the special value :c:data:`Py_TP_USE_SPEC`:" -msgstr "" - -#: ../../c-api/type.rst:666 -msgid "" -"static PyType_Slot foo_slots[] = {\n" -" {Py_tp_token, Py_TP_USE_SPEC}," -msgstr "" -"static PyType_Slot foo_slots[] = {\n" -" {Py_tp_token, Py_TP_USE_SPEC}," - -#: ../../c-api/type.rst:671 -msgid "It can also be set to an arbitrary pointer, but you must ensure that:" -msgstr "" - -#: ../../c-api/type.rst:673 -msgid "" -"The pointer outlives the class, so it's not reused for something else while " -"the class exists." -msgstr "" - -#: ../../c-api/type.rst:675 -msgid "" -"It \"belongs\" to the extension module where the class lives, so it will not " -"clash with other extensions." -msgstr "" - -#: ../../c-api/type.rst:678 -msgid "" -"Use :c:func:`PyType_GetBaseByToken` to check if a class's superclass has a " -"given token -- that is, check whether the memory layout is compatible." -msgstr "" - -#: ../../c-api/type.rst:681 -msgid "" -"To get the token for a given class (without considering superclasses), use :" -"c:func:`PyType_GetSlot` with ``Py_tp_token``." -msgstr "" - -#: ../../c-api/type.rst:690 -msgid "" -"Used as a value with :c:data:`Py_tp_token` to set the token to the class's :" -"c:type:`PyType_Spec`. Expands to ``NULL``." -msgstr "" - -#: ../../c-api/type.rst:8 -msgid "object" -msgstr "object（物件）" - -#: ../../c-api/type.rst:8 -msgid "type" -msgstr "type（型別）" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-22 00:14+0000\n" +"PO-Revision-Date: 2015-12-09 17:51+0000\n" +"Last-Translator: Liang-Bo Wang \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" + +#: ../../c-api/type.rst:6 +msgid "Type Objects" +msgstr "型別物件" + +#: ../../c-api/type.rst:13 +msgid "The C structure of the objects used to describe built-in types." +msgstr "" + +#: ../../c-api/type.rst:18 +msgid "" +"This is the type object for type objects; it is the same object as :class:" +"`type` in the Python layer." +msgstr "" + +#: ../../c-api/type.rst:24 +msgid "" +"Return non-zero if the object *o* is a type object, including instances of " +"types derived from the standard type object. Return 0 in all other cases. " +"This function always succeeds." +msgstr "" + +#: ../../c-api/type.rst:31 +msgid "" +"Return non-zero if the object *o* is a type object, but not a subtype of the " +"standard type object. Return 0 in all other cases. This function always " +"succeeds." +msgstr "" + +#: ../../c-api/type.rst:38 +msgid "Clear the internal lookup cache. Return the current version tag." +msgstr "" + +#: ../../c-api/type.rst:42 +msgid "" +"Return the :c:member:`~PyTypeObject.tp_flags` member of *type*. This " +"function is primarily meant for use with ``Py_LIMITED_API``; the individual " +"flag bits are guaranteed to be stable across Python releases, but access to :" +"c:member:`~PyTypeObject.tp_flags` itself is not part of the :ref:`limited " +"API `." +msgstr "" + +#: ../../c-api/type.rst:49 +msgid "The return type is now ``unsigned long`` rather than ``long``." +msgstr "" + +#: ../../c-api/type.rst:55 +msgid "" +"Return the type object's internal namespace, which is otherwise only exposed " +"via a read-only proxy (:attr:`cls.__dict__ `). This is a " +"replacement for accessing :c:member:`~PyTypeObject.tp_dict` directly. The " +"returned dictionary must be treated as read-only." +msgstr "" + +#: ../../c-api/type.rst:61 +msgid "" +"This function is meant for specific embedding and language-binding cases, " +"where direct access to the dict is necessary and indirect access (e.g. via " +"the proxy or :c:func:`PyObject_GetAttr`) isn't adequate." +msgstr "" + +#: ../../c-api/type.rst:65 +msgid "" +"Extension modules should continue to use ``tp_dict``, directly or " +"indirectly, when setting up their own types." +msgstr "" + +#: ../../c-api/type.rst:73 +msgid "" +"Invalidate the internal lookup cache for the type and all of its subtypes. " +"This function must be called after any manual modification of the attributes " +"or base classes of the type." +msgstr "" + +#: ../../c-api/type.rst:80 +msgid "" +"Register *callback* as a type watcher. Return a non-negative integer ID " +"which must be passed to future calls to :c:func:`PyType_Watch`. In case of " +"error (e.g. no more watcher IDs available), return ``-1`` and set an " +"exception." +msgstr "" + +#: ../../c-api/type.rst:85 +msgid "" +"In free-threaded builds, :c:func:`PyType_AddWatcher` is not thread-safe, so " +"it must be called at start up (before spawning the first thread)." +msgstr "" + +#: ../../c-api/type.rst:93 +msgid "" +"Clear watcher identified by *watcher_id* (previously returned from :c:func:" +"`PyType_AddWatcher`). Return ``0`` on success, ``-1`` on error (e.g. if " +"*watcher_id* was never registered.)" +msgstr "" + +#: ../../c-api/type.rst:97 +msgid "" +"An extension should never call ``PyType_ClearWatcher`` with a *watcher_id* " +"that was not returned to it by a previous call to :c:func:" +"`PyType_AddWatcher`." +msgstr "" + +#: ../../c-api/type.rst:106 +msgid "" +"Mark *type* as watched. The callback granted *watcher_id* by :c:func:" +"`PyType_AddWatcher` will be called whenever :c:func:`PyType_Modified` " +"reports a change to *type*. (The callback may be called only once for a " +"series of consecutive modifications to *type*, if :c:func:`!_PyType_Lookup` " +"is not called on *type* between the modifications; this is an implementation " +"detail and subject to change.)" +msgstr "" + +#: ../../c-api/type.rst:113 +msgid "" +"An extension should never call ``PyType_Watch`` with a *watcher_id* that was " +"not returned to it by a previous call to :c:func:`PyType_AddWatcher`." +msgstr "" + +#: ../../c-api/type.rst:121 +msgid "" +"Mark *type* as not watched. This undoes a previous call to :c:func:" +"`PyType_Watch`. *type* must not be ``NULL``." +msgstr "" + +#: ../../c-api/type.rst:124 +msgid "" +"An extension should never call this function with a *watcher_id* that was " +"not returned to it by a previous call to :c:func:`PyType_AddWatcher`." +msgstr "" + +#: ../../c-api/type.rst:127 +msgid "" +"On success, this function returns ``0``. On failure, this function returns " +"``-1`` with an exception set." +msgstr "成功時此函式會回傳 ``0``。失敗時此函式回傳 ``-1`` 並設定例外。" + +#: ../../c-api/type.rst:135 +msgid "Type of a type-watcher callback function." +msgstr "" + +#: ../../c-api/type.rst:137 +msgid "" +"The callback must not modify *type* or cause :c:func:`PyType_Modified` to be " +"called on *type* or any type in its MRO; violating this rule could cause " +"infinite recursion." +msgstr "" + +#: ../../c-api/type.rst:146 +msgid "" +"Return non-zero if the type object *o* sets the feature *feature*. Type " +"features are denoted by single bit flags." +msgstr "" + +#: ../../c-api/type.rst:152 +msgid "" +"Return non-zero if the type object *type* sets the subclass flag *flag*. " +"Subclass flags are denoted by :c:macro:`Py_TPFLAGS_*_SUBCLASS " +"`. This function is used by many ``_Check`` " +"functions for common types." +msgstr "" + +#: ../../c-api/type.rst:158 +msgid "" +":c:func:`PyObject_TypeCheck`, which is used as a slower alternative in " +"``_Check`` functions for types that don't come with subclass flags." +msgstr "" + +#: ../../c-api/type.rst:164 +msgid "" +"Return true if the type object includes support for the cycle detector; this " +"tests the type flag :c:macro:`Py_TPFLAGS_HAVE_GC`." +msgstr "" + +#: ../../c-api/type.rst:170 +msgid "Return true if *a* is a subtype of *b*." +msgstr "如果 *a* 是 *b* 的子類別則回傳 true。" + +#: ../../c-api/type.rst:172 +msgid "" +"This function only checks for actual subtypes, which means that :meth:`~type." +"__subclasscheck__` is not called on *b*. Call :c:func:`PyObject_IsSubclass` " +"to do the same check that :func:`issubclass` would do." +msgstr "" + +#: ../../c-api/type.rst:180 +msgid "" +"Generic handler for the :c:member:`~PyTypeObject.tp_alloc` slot of a type " +"object. Uses Python's default memory allocation mechanism to allocate " +"memory for a new instance, zeros the memory, then initializes the memory as " +"if by calling :c:func:`PyObject_Init` or :c:func:`PyObject_InitVar`." +msgstr "" + +#: ../../c-api/type.rst:185 +msgid "" +"Do not call this directly to allocate memory for an object; call the type's :" +"c:member:`~PyTypeObject.tp_alloc` slot instead." +msgstr "" + +#: ../../c-api/type.rst:188 +msgid "" +"For types that support garbage collection (i.e., the :c:macro:" +"`Py_TPFLAGS_HAVE_GC` flag is set), this function behaves like :c:macro:" +"`PyObject_GC_New` or :c:macro:`PyObject_GC_NewVar` (except the memory is " +"guaranteed to be zeroed before initialization), and should be paired with :c:" +"func:`PyObject_GC_Del` in :c:member:`~PyTypeObject.tp_free`. Otherwise, it " +"behaves like :c:macro:`PyObject_New` or :c:macro:`PyObject_NewVar` (except " +"the memory is guaranteed to be zeroed before initialization) and should be " +"paired with :c:func:`PyObject_Free` in :c:member:`~PyTypeObject.tp_free`." +msgstr "" + +#: ../../c-api/type.rst:201 +msgid "" +"Generic handler for the :c:member:`~PyTypeObject.tp_new` slot of a type " +"object. Creates a new instance using the type's :c:member:`~PyTypeObject." +"tp_alloc` slot and returns the resulting object." +msgstr "" + +#: ../../c-api/type.rst:208 +msgid "" +"Finalize a type object. This should be called on all type objects to finish " +"their initialization. This function is responsible for adding inherited " +"slots from a type's base class. Return ``0`` on success, or return ``-1`` " +"and sets an exception on error." +msgstr "" + +#: ../../c-api/type.rst:214 +msgid "" +"If some of the base classes implements the GC protocol and the provided type " +"does not include the :c:macro:`Py_TPFLAGS_HAVE_GC` in its flags, then the GC " +"protocol will be automatically implemented from its parents. On the " +"contrary, if the type being created does include :c:macro:" +"`Py_TPFLAGS_HAVE_GC` in its flags then it **must** implement the GC protocol " +"itself by at least implementing the :c:member:`~PyTypeObject.tp_traverse` " +"handle." +msgstr "" + +#: ../../c-api/type.rst:225 +msgid "" +"Return the type's name. Equivalent to getting the type's :attr:`~type." +"__name__` attribute." +msgstr "" + +#: ../../c-api/type.rst:233 +msgid "" +"Return the type's qualified name. Equivalent to getting the type's :attr:" +"`~type.__qualname__` attribute." +msgstr "" + +#: ../../c-api/type.rst:240 +msgid "" +"Return the type's fully qualified name. Equivalent to ``f\"{type.__module__}." +"{type.__qualname__}\"``, or :attr:`type.__qualname__` if :attr:`type." +"__module__` is not a string or is equal to ``\"builtins\"``." +msgstr "" + +#: ../../c-api/type.rst:249 +msgid "" +"Return the type's module name. Equivalent to getting the :attr:`type." +"__module__` attribute." +msgstr "" + +#: ../../c-api/type.rst:257 +msgid "" +"Return the function pointer stored in the given slot. If the result is " +"``NULL``, this indicates that either the slot is ``NULL``, or that the " +"function was called with invalid parameters. Callers will typically cast the " +"result pointer into the appropriate function type." +msgstr "" + +#: ../../c-api/type.rst:263 +msgid "" +"See :c:member:`PyType_Slot.slot` for possible values of the *slot* argument." +msgstr "" + +#: ../../c-api/type.rst:267 +msgid "" +":c:func:`PyType_GetSlot` can now accept all types. Previously, it was " +"limited to :ref:`heap types `." +msgstr "" + +#: ../../c-api/type.rst:274 +msgid "" +"Return the module object associated with the given type when the type was " +"created using :c:func:`PyType_FromModuleAndSpec`." +msgstr "" + +#: ../../c-api/type.rst:277 ../../c-api/type.rst:298 +msgid "" +"If no module is associated with the given type, sets :py:class:`TypeError` " +"and returns ``NULL``." +msgstr "" + +#: ../../c-api/type.rst:280 +msgid "" +"This function is usually used to get the module in which a method is " +"defined. Note that in such a method, ``PyType_GetModule(Py_TYPE(self))`` may " +"not return the intended result. ``Py_TYPE(self)`` may be a *subclass* of the " +"intended class, and subclasses are not necessarily defined in the same " +"module as their superclass. See :c:type:`PyCMethod` to get the class that " +"defines the method. See :c:func:`PyType_GetModuleByDef` for cases when :c:" +"type:`!PyCMethod` cannot be used." +msgstr "" + +#: ../../c-api/type.rst:294 +msgid "" +"Return the state of the module object associated with the given type. This " +"is a shortcut for calling :c:func:`PyModule_GetState()` on the result of :c:" +"func:`PyType_GetModule`." +msgstr "" + +#: ../../c-api/type.rst:301 +msgid "" +"If the *type* has an associated module but its state is ``NULL``, returns " +"``NULL`` without setting an exception." +msgstr "" + +#: ../../c-api/type.rst:309 +msgid "" +"Find the first superclass whose module was created from the given :c:type:" +"`PyModuleDef` *def*, and return that module." +msgstr "" + +#: ../../c-api/type.rst:312 +msgid "" +"If no module is found, raises a :py:class:`TypeError` and returns ``NULL``." +msgstr "" + +#: ../../c-api/type.rst:314 +msgid "" +"This function is intended to be used together with :c:func:" +"`PyModule_GetState()` to get module state from slot methods (such as :c:" +"member:`~PyTypeObject.tp_init` or :c:member:`~PyNumberMethods.nb_add`) and " +"other places where a method's defining class cannot be passed using the :c:" +"type:`PyCMethod` calling convention." +msgstr "" + +#: ../../c-api/type.rst:320 +msgid "" +"The returned reference is :term:`borrowed ` from *type*, " +"and will be valid as long as you hold a reference to *type*. Do not release " +"it with :c:func:`Py_DECREF` or similar." +msgstr "" + +#: ../../c-api/type.rst:329 +msgid "" +"Find the first superclass in *type*'s :term:`method resolution order` whose :" +"c:macro:`Py_tp_token` token is equal to the given one." +msgstr "" + +#: ../../c-api/type.rst:332 +msgid "" +"If found, set *\\*result* to a new :term:`strong reference` to it and return " +"``1``." +msgstr "" + +#: ../../c-api/type.rst:334 +msgid "If not found, set *\\*result* to ``NULL`` and return ``0``." +msgstr "如果沒找到，則將 *\\*result* 設為 ``NULL`` 並回傳 ``0``。" + +#: ../../c-api/type.rst:335 +msgid "" +"On error, set *\\*result* to ``NULL`` and return ``-1`` with an exception " +"set." +msgstr "" +"在發生錯誤時，將 *\\*result* 設為 ``NULL`` 並回傳 ``-1``，同時設定例外。" + +#: ../../c-api/type.rst:338 +msgid "" +"The *result* argument may be ``NULL``, in which case *\\*result* is not set. " +"Use this if you need only the return value." +msgstr "" +"如果 *result* 引數為 ``NULL``，則不會設定 *\\*result*。如果你只需要回傳值，請" +"使用此選項。" + +#: ../../c-api/type.rst:341 +msgid "The *token* argument may not be ``NULL``." +msgstr "*token* 引數不可為 ``NULL``。" + +#: ../../c-api/type.rst:348 +msgid "Attempt to assign a version tag to the given type." +msgstr "" + +#: ../../c-api/type.rst:350 +msgid "" +"Returns 1 if the type already had a valid version tag or a new one was " +"assigned, or 0 if a new tag could not be assigned." +msgstr "" + +#: ../../c-api/type.rst:358 +msgid "" +"Return true if instances of *type* support creating weak references, false " +"otherwise. This function always succeeds. *type* must not be ``NULL``." +msgstr "" + +#: ../../c-api/type.rst:362 +msgid ":ref:`weakrefobjects`" +msgstr ":ref:`weakrefobjects`" + +#: ../../c-api/type.rst:363 +msgid ":py:mod:`weakref`" +msgstr ":py:mod:`weakref`" + +#: ../../c-api/type.rst:367 +msgid "Creating Heap-Allocated Types" +msgstr "" + +#: ../../c-api/type.rst:369 +msgid "" +"The following functions and structs are used to create :ref:`heap types " +"`." +msgstr "" + +#: ../../c-api/type.rst:374 +msgid "" +"Create and return a :ref:`heap type ` from the *spec* (see :c:" +"macro:`Py_TPFLAGS_HEAPTYPE`)." +msgstr "" + +#: ../../c-api/type.rst:377 +msgid "" +"The metaclass *metaclass* is used to construct the resulting type object. " +"When *metaclass* is ``NULL``, the metaclass is derived from *bases* (or " +"*Py_tp_base[s]* slots if *bases* is ``NULL``, see below)." +msgstr "" + +#: ../../c-api/type.rst:381 +msgid "" +"Metaclasses that override :c:member:`~PyTypeObject.tp_new` are not " +"supported, except if ``tp_new`` is ``NULL``." +msgstr "" + +#: ../../c-api/type.rst:384 +msgid "" +"The *bases* argument can be used to specify base classes; it can either be " +"only one class or a tuple of classes. If *bases* is ``NULL``, the :c:data:" +"`Py_tp_bases` slot is used instead. If that also is ``NULL``, the :c:data:" +"`Py_tp_base` slot is used instead. If that also is ``NULL``, the new type " +"derives from :class:`object`." +msgstr "" + +#: ../../c-api/type.rst:390 +msgid "" +"The *module* argument can be used to record the module in which the new " +"class is defined. It must be a module object or ``NULL``. If not ``NULL``, " +"the module is associated with the new type and can later be retrieved with :" +"c:func:`PyType_GetModule`. The associated module is not inherited by " +"subclasses; it must be specified for each class individually." +msgstr "" + +#: ../../c-api/type.rst:397 +msgid "This function calls :c:func:`PyType_Ready` on the new type." +msgstr "" + +#: ../../c-api/type.rst:399 +msgid "" +"Note that this function does *not* fully match the behavior of calling :py:" +"class:`type() ` or using the :keyword:`class` statement. With user-" +"provided base types or metaclasses, prefer :ref:`calling ` :py:" +"class:`type` (or the metaclass) over ``PyType_From*`` functions. " +"Specifically:" +msgstr "" + +#: ../../c-api/type.rst:406 +msgid "" +":py:meth:`~object.__new__` is not called on the new class (and it must be " +"set to ``type.__new__``)." +msgstr "" +":py:meth:`~object.__new__` 不會在新類別上被呼叫（且它必須被設為 ``type." +"__new__``）。" + +#: ../../c-api/type.rst:408 +msgid ":py:meth:`~object.__init__` is not called on the new class." +msgstr ":py:meth:`~object.__init__` 不會在新類別上被呼叫。" + +#: ../../c-api/type.rst:409 +msgid ":py:meth:`~object.__init_subclass__` is not called on any bases." +msgstr ":py:meth:`~object.__init_subclass__` 不會在任何基底上被呼叫。" + +#: ../../c-api/type.rst:410 +msgid ":py:meth:`~object.__set_name__` is not called on new descriptors." +msgstr ":py:meth:`~object.__set_name__` 不會在新的描述器上被呼叫。" + +#: ../../c-api/type.rst:417 +msgid "Equivalent to ``PyType_FromMetaclass(NULL, module, spec, bases)``." +msgstr "等價於 ``PyType_FromMetaclass(NULL, module, spec, bases)``。" + +#: ../../c-api/type.rst:423 +msgid "" +"The function now accepts a single class as the *bases* argument and ``NULL`` " +"as the ``tp_doc`` slot." +msgstr "" + +#: ../../c-api/type.rst:428 ../../c-api/type.rst:450 +msgid "" +"The function now finds and uses a metaclass corresponding to the provided " +"base classes. Previously, only :class:`type` instances were returned." +msgstr "" + +#: ../../c-api/type.rst:431 ../../c-api/type.rst:453 ../../c-api/type.rst:474 +msgid "" +"The :c:member:`~PyTypeObject.tp_new` of the metaclass is *ignored*. which " +"may result in incomplete initialization. Creating classes whose metaclass " +"overrides :c:member:`~PyTypeObject.tp_new` is deprecated." +msgstr "" + +#: ../../c-api/type.rst:438 ../../c-api/type.rst:460 ../../c-api/type.rst:481 +msgid "" +"Creating classes whose metaclass overrides :c:member:`~PyTypeObject.tp_new` " +"is no longer allowed." +msgstr "" + +#: ../../c-api/type.rst:444 +msgid "Equivalent to ``PyType_FromMetaclass(NULL, NULL, spec, bases)``." +msgstr "等價於 ``PyType_FromMetaclass(NULL, NULL, spec, bases)``。" + +#: ../../c-api/type.rst:466 +msgid "Equivalent to ``PyType_FromMetaclass(NULL, NULL, spec, NULL)``." +msgstr "等價於 ``PyType_FromMetaclass(NULL, NULL, spec, NULL)``。" + +#: ../../c-api/type.rst:470 +msgid "" +"The function now finds and uses a metaclass corresponding to the base " +"classes provided in *Py_tp_base[s]* slots. Previously, only :class:`type` " +"instances were returned." +msgstr "" + +#: ../../c-api/type.rst:487 +msgid "" +"Make a type immutable: set the :c:macro:`Py_TPFLAGS_IMMUTABLETYPE` flag." +msgstr "" + +#: ../../c-api/type.rst:489 +msgid "All base classes of *type* must be immutable." +msgstr "所有 *type* 的基底類別都必須是不可變的。" + +#: ../../c-api/type.rst:491 +msgid "On success, return ``0``. On error, set an exception and return ``-1``." +msgstr "" + +#: ../../c-api/type.rst:494 +msgid "" +"The type must not be used before it's made immutable. For example, type " +"instances must not be created before the type is made immutable." +msgstr "" + +#: ../../c-api/type.rst:510 +msgid "Structure defining a type's behavior." +msgstr "" + +#: ../../c-api/type.rst:514 +msgid "Name of the type, used to set :c:member:`PyTypeObject.tp_name`." +msgstr "" + +#: ../../c-api/type.rst:518 +msgid "" +"If positive, specifies the size of the instance in bytes. It is used to set :" +"c:member:`PyTypeObject.tp_basicsize`." +msgstr "" + +#: ../../c-api/type.rst:521 +msgid "" +"If zero, specifies that :c:member:`~PyTypeObject.tp_basicsize` should be " +"inherited." +msgstr "" + +#: ../../c-api/type.rst:524 +msgid "" +"If negative, the absolute value specifies how much space instances of the " +"class need *in addition* to the superclass. Use :c:func:" +"`PyObject_GetTypeData` to get a pointer to subclass-specific memory reserved " +"this way. For negative :c:member:`!basicsize`, Python will insert padding " +"when needed to meet :c:member:`~PyTypeObject.tp_basicsize`'s alignment " +"requirements." +msgstr "" + +#: ../../c-api/type.rst:534 +msgid "Previously, this field could not be negative." +msgstr "在過去此欄位不可為負值。" + +#: ../../c-api/type.rst:538 +msgid "" +"Size of one element of a variable-size type, in bytes. Used to set :c:member:" +"`PyTypeObject.tp_itemsize`. See ``tp_itemsize`` documentation for caveats." +msgstr "" + +#: ../../c-api/type.rst:542 +msgid "" +"If zero, :c:member:`~PyTypeObject.tp_itemsize` is inherited. Extending " +"arbitrary variable-sized classes is dangerous, since some types use a fixed " +"offset for variable-sized memory, which can then overlap fixed-sized memory " +"used by a subclass. To help prevent mistakes, inheriting ``itemsize`` is " +"only possible in the following situations:" +msgstr "" + +#: ../../c-api/type.rst:549 +msgid "" +"The base is not variable-sized (its :c:member:`~PyTypeObject.tp_itemsize`)." +msgstr "" + +#: ../../c-api/type.rst:551 +msgid "" +"The requested :c:member:`PyType_Spec.basicsize` is positive, suggesting that " +"the memory layout of the base class is known." +msgstr "" + +#: ../../c-api/type.rst:553 +msgid "" +"The requested :c:member:`PyType_Spec.basicsize` is zero, suggesting that the " +"subclass does not access the instance's memory directly." +msgstr "" + +#: ../../c-api/type.rst:556 +msgid "With the :c:macro:`Py_TPFLAGS_ITEMS_AT_END` flag." +msgstr "" + +#: ../../c-api/type.rst:560 +msgid "Type flags, used to set :c:member:`PyTypeObject.tp_flags`." +msgstr "" + +#: ../../c-api/type.rst:562 +msgid "" +"If the ``Py_TPFLAGS_HEAPTYPE`` flag is not set, :c:func:" +"`PyType_FromSpecWithBases` sets it automatically." +msgstr "" +"如果未設定 ``Py_TPFLAGS_HEAPTYPE`` 旗標，則 :c:func:" +"`PyType_FromSpecWithBases` 會自動設定它。" + +#: ../../c-api/type.rst:567 +msgid "" +"Array of :c:type:`PyType_Slot` structures. Terminated by the special slot " +"value ``{0, NULL}``." +msgstr "" + +#: ../../c-api/type.rst:570 +msgid "Each slot ID should be specified at most once." +msgstr "" + +#: ../../c-api/type.rst:580 +msgid "" +"Structure defining optional functionality of a type, containing a slot ID " +"and a value pointer." +msgstr "" + +#: ../../c-api/type.rst:585 +msgid "A slot ID." +msgstr "" + +#: ../../c-api/type.rst:587 +msgid "" +"Slot IDs are named like the field names of the structures :c:type:" +"`PyTypeObject`, :c:type:`PyNumberMethods`, :c:type:`PySequenceMethods`, :c:" +"type:`PyMappingMethods` and :c:type:`PyAsyncMethods` with an added ``Py_`` " +"prefix. For example, use:" +msgstr "" + +#: ../../c-api/type.rst:593 +msgid ":c:data:`Py_tp_dealloc` to set :c:member:`PyTypeObject.tp_dealloc`" +msgstr ":c:data:`Py_tp_dealloc` 以設定 :c:member:`PyTypeObject.tp_dealloc`" + +#: ../../c-api/type.rst:594 +msgid ":c:data:`Py_nb_add` to set :c:member:`PyNumberMethods.nb_add`" +msgstr ":c:data:`Py_nb_add` 以設定 :c:member:`PyNumberMethods.nb_add`" + +#: ../../c-api/type.rst:595 +msgid ":c:data:`Py_sq_length` to set :c:member:`PySequenceMethods.sq_length`" +msgstr ":c:data:`Py_sq_length` 以設定 :c:member:`PySequenceMethods.sq_length`" + +#: ../../c-api/type.rst:597 +msgid "" +"An additional slot is supported that does not correspond to a :c:type:`!" +"PyTypeObject` struct field:" +msgstr "" + +#: ../../c-api/type.rst:600 +msgid ":c:data:`Py_tp_token`" +msgstr ":c:data:`Py_tp_token`" + +#: ../../c-api/type.rst:602 +msgid "" +"The following “offset” fields cannot be set using :c:type:`PyType_Slot`:" +msgstr "" + +#: ../../c-api/type.rst:604 +msgid "" +":c:member:`~PyTypeObject.tp_weaklistoffset` (use :c:macro:" +"`Py_TPFLAGS_MANAGED_WEAKREF` instead if possible)" +msgstr "" +":c:member:`~PyTypeObject.tp_weaklistoffset`\\ （如果可能，請改用 :c:macro:" +"`Py_TPFLAGS_MANAGED_WEAKREF`）" + +#: ../../c-api/type.rst:606 +msgid "" +":c:member:`~PyTypeObject.tp_dictoffset` (use :c:macro:" +"`Py_TPFLAGS_MANAGED_DICT` instead if possible)" +msgstr "" +":c:member:`~PyTypeObject.tp_dictoffset`\\ （如果可能，請改用 :c:macro:" +"`Py_TPFLAGS_MANAGED_DICT`）" + +#: ../../c-api/type.rst:608 +msgid "" +":c:member:`~PyTypeObject.tp_vectorcall_offset` (use " +"``\"__vectorcalloffset__\"`` in :ref:`PyMemberDef `)" +msgstr "" +":c:member:`~PyTypeObject.tp_vectorcall_offset`\\ （請用 :ref:`PyMemberDef " +"` 中的 ``\"__vectorcalloffset__\"``）" + +#: ../../c-api/type.rst:612 +msgid "" +"If it is not possible to switch to a ``MANAGED`` flag (for example, for " +"vectorcall or to support Python older than 3.12), specify the offset in :c:" +"data:`Py_tp_members`. See :ref:`PyMemberDef documentation ` for details." +msgstr "" + +#: ../../c-api/type.rst:618 +msgid "" +"The following internal fields cannot be set at all when creating a heap type:" +msgstr "" + +#: ../../c-api/type.rst:621 +msgid "" +":c:member:`~PyTypeObject.tp_dict`, :c:member:`~PyTypeObject.tp_mro`, :c:" +"member:`~PyTypeObject.tp_cache`, :c:member:`~PyTypeObject.tp_subclasses`, " +"and :c:member:`~PyTypeObject.tp_weaklist`." +msgstr "" + +#: ../../c-api/type.rst:627 +msgid "" +"Setting :c:data:`Py_tp_bases` or :c:data:`Py_tp_base` may be problematic on " +"some platforms. To avoid issues, use the *bases* argument of :c:func:" +"`PyType_FromSpecWithBases` instead." +msgstr "" + +#: ../../c-api/type.rst:632 +msgid "Slots in :c:type:`PyBufferProcs` may be set in the unlimited API." +msgstr "" + +#: ../../c-api/type.rst:635 +msgid "" +":c:member:`~PyBufferProcs.bf_getbuffer` and :c:member:`~PyBufferProcs." +"bf_releasebuffer` are now available under the :ref:`limited API `." +msgstr "" + +#: ../../c-api/type.rst:640 +msgid "" +"The field :c:member:`~PyTypeObject.tp_vectorcall` can now be set using :c:" +"data:`Py_tp_vectorcall`. See the field's documentation for details." +msgstr "" + +#: ../../c-api/type.rst:647 +msgid "" +"The desired value of the slot. In most cases, this is a pointer to a " +"function." +msgstr "" + +#: ../../c-api/type.rst:650 +msgid "*pfunc* values may not be ``NULL``, except for the following slots:" +msgstr "" + +#: ../../c-api/type.rst:652 +msgid ":c:data:`Py_tp_doc`" +msgstr ":c:data:`Py_tp_doc`" + +#: ../../c-api/type.rst:653 +msgid "" +":c:data:`Py_tp_token` (for clarity, prefer :c:data:`Py_TP_USE_SPEC` rather " +"than ``NULL``)" +msgstr "" + +#: ../../c-api/type.rst:659 +msgid "" +"A :c:member:`~PyType_Slot.slot` that records a static memory layout ID for a " +"class." +msgstr "" + +#: ../../c-api/type.rst:662 +msgid "" +"If the :c:type:`PyType_Spec` of the class is statically allocated, the token " +"can be set to the spec using the special value :c:data:`Py_TP_USE_SPEC`:" +msgstr "" + +#: ../../c-api/type.rst:666 +msgid "" +"static PyType_Slot foo_slots[] = {\n" +" {Py_tp_token, Py_TP_USE_SPEC}," +msgstr "" +"static PyType_Slot foo_slots[] = {\n" +" {Py_tp_token, Py_TP_USE_SPEC}," + +#: ../../c-api/type.rst:671 +msgid "It can also be set to an arbitrary pointer, but you must ensure that:" +msgstr "" + +#: ../../c-api/type.rst:673 +msgid "" +"The pointer outlives the class, so it's not reused for something else while " +"the class exists." +msgstr "" + +#: ../../c-api/type.rst:675 +msgid "" +"It \"belongs\" to the extension module where the class lives, so it will not " +"clash with other extensions." +msgstr "" + +#: ../../c-api/type.rst:678 +msgid "" +"Use :c:func:`PyType_GetBaseByToken` to check if a class's superclass has a " +"given token -- that is, check whether the memory layout is compatible." +msgstr "" + +#: ../../c-api/type.rst:681 +msgid "" +"To get the token for a given class (without considering superclasses), use :" +"c:func:`PyType_GetSlot` with ``Py_tp_token``." +msgstr "" + +#: ../../c-api/type.rst:690 +msgid "" +"Used as a value with :c:data:`Py_tp_token` to set the token to the class's :" +"c:type:`PyType_Spec`. Expands to ``NULL``." +msgstr "" + +#: ../../c-api/type.rst:8 +msgid "object" +msgstr "object（物件）" + +#: ../../c-api/type.rst:8 +msgid "type" +msgstr "type（型別）" diff --git a/c-api/typehints.po b/c-api/typehints.po index 113e15ecbc..74b92e97c8 100644 --- a/c-api/typehints.po +++ b/c-api/typehints.po @@ -1,94 +1,94 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Matt Wang , 2022 -# -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-09-01 22:24+0800\n" -"PO-Revision-Date: 2022-10-16 16:16+0800\n" -"Last-Translator: Matt Wang \n" -"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" -"tw)\n" -"Language: zh_TW\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=UTF-8\n" -"Content-Transfer-Encoding: 8bit\n" -"X-Generator: Poedit 3.1.1\n" - -#: ../../c-api/typehints.rst:6 -msgid "Objects for Type Hinting" -msgstr "型別提示物件" - -#: ../../c-api/typehints.rst:8 -msgid "" -"Various built-in types for type hinting are provided. Currently, two types " -"exist -- :ref:`GenericAlias ` and :ref:`Union `. Only ``GenericAlias`` is exposed to C." -msgstr "" -"提供了數個用於型別提示的內建型別。目前有兩種 -- :ref:`GenericAlias ` 和 :ref:`Union `。只有 ``GenericAlias`` 有公開 " -"(expose) 給 C。" - -#: ../../c-api/typehints.rst:14 -msgid "" -"Create a :ref:`GenericAlias ` object. Equivalent to " -"calling the Python class :class:`types.GenericAlias`. The *origin* and " -"*args* arguments set the ``GenericAlias``\\ 's ``__origin__`` and " -"``__args__`` attributes respectively. *origin* should be a :c:expr:" -"`PyTypeObject*`, and *args* can be a :c:expr:`PyTupleObject*` or any " -"``PyObject*``. If *args* passed is not a tuple, a 1-tuple is automatically " -"constructed and ``__args__`` is set to ``(args,)``. Minimal checking is done " -"for the arguments, so the function will succeed even if *origin* is not a " -"type. The ``GenericAlias``\\ 's ``__parameters__`` attribute is constructed " -"lazily from ``__args__``. On failure, an exception is raised and ``NULL`` " -"is returned." -msgstr "" -"建立一個 :ref:`GenericAlias ` 物件，等同於呼叫 Python " -"的 :class:`types.GenericAlias` class。 *origin* 和 *args* 引數分別設定了 " -"``GenericAlias`` 的 ``__origin__`` 與 ``__args__`` 屬性。*origin* 應該要是" -"個 :c:expr:`PyTypeObject*` 且 *args* 可以是個 :c:expr:`PyTupleObject*` 或任" -"意 ``PyObject*``。如果傳入的 *args* 不是個 tuple（元組），則會自動建立一個長" -"度為 1 的 tuple 且 ``__args__`` 會被設為 ``(args,)``。只會進行最少的引數檢" -"查，所以即便 *origin* 不是個型別，函式也會不會失敗。 ``GenericAlias`` 的 " -"``__parameters__`` 屬性會自 ``__args__`` 惰性地建立 (constructed lazily)。當" -"失敗時，會引發一個例外並回傳 ``NULL``。" - -#: ../../c-api/typehints.rst:28 -msgid "Here's an example of how to make an extension type generic::" -msgstr "以下是個讓一個擴充型別泛用化 (generic) 的例子： ::" - -#: ../../c-api/typehints.rst:30 -msgid "" -"...\n" -"static PyMethodDef my_obj_methods[] = {\n" -" // Other methods.\n" -" ...\n" -" {\"__class_getitem__\", Py_GenericAlias, METH_O|METH_CLASS, \"See PEP " -"585\"}\n" -" ...\n" -"}" -msgstr "" -"...\n" -"static PyMethodDef my_obj_methods[] = {\n" -" // 其他方法。\n" -" ...\n" -" {\"__class_getitem__\", Py_GenericAlias, METH_O|METH_CLASS, \"See PEP " -"585\"}\n" -" ...\n" -"}" - -#: ../../c-api/typehints.rst:38 -msgid "The data model method :meth:`~object.__class_getitem__`." -msgstr "資料模型方法 :meth:`~object.__class_getitem__`。" - -#: ../../c-api/typehints.rst:44 -msgid "" -"The C type of the object returned by :c:func:`Py_GenericAlias`. Equivalent " -"to :class:`types.GenericAlias` in Python." -msgstr "" -":c:func:`Py_GenericAlias` 所回傳該物件的 C 型別。等價於 Python 中的 :class:" -"`types.GenericAlias`。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Matt Wang , 2022 +# +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-09-01 22:24+0800\n" +"PO-Revision-Date: 2022-10-16 16:16+0800\n" +"Last-Translator: Matt Wang \n" +"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" +"tw)\n" +"Language: zh_TW\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"X-Generator: Poedit 3.1.1\n" + +#: ../../c-api/typehints.rst:6 +msgid "Objects for Type Hinting" +msgstr "型別提示物件" + +#: ../../c-api/typehints.rst:8 +msgid "" +"Various built-in types for type hinting are provided. Currently, two types " +"exist -- :ref:`GenericAlias ` and :ref:`Union `. Only ``GenericAlias`` is exposed to C." +msgstr "" +"提供了數個用於型別提示的內建型別。目前有兩種 -- :ref:`GenericAlias ` 和 :ref:`Union `。只有 ``GenericAlias`` 有公開 " +"(expose) 給 C。" + +#: ../../c-api/typehints.rst:14 +msgid "" +"Create a :ref:`GenericAlias ` object. Equivalent to " +"calling the Python class :class:`types.GenericAlias`. The *origin* and " +"*args* arguments set the ``GenericAlias``\\ 's ``__origin__`` and " +"``__args__`` attributes respectively. *origin* should be a :c:expr:" +"`PyTypeObject*`, and *args* can be a :c:expr:`PyTupleObject*` or any " +"``PyObject*``. If *args* passed is not a tuple, a 1-tuple is automatically " +"constructed and ``__args__`` is set to ``(args,)``. Minimal checking is done " +"for the arguments, so the function will succeed even if *origin* is not a " +"type. The ``GenericAlias``\\ 's ``__parameters__`` attribute is constructed " +"lazily from ``__args__``. On failure, an exception is raised and ``NULL`` " +"is returned." +msgstr "" +"建立一個 :ref:`GenericAlias ` 物件，等同於呼叫 Python " +"的 :class:`types.GenericAlias` class。 *origin* 和 *args* 引數分別設定了 " +"``GenericAlias`` 的 ``__origin__`` 與 ``__args__`` 屬性。*origin* 應該要是" +"個 :c:expr:`PyTypeObject*` 且 *args* 可以是個 :c:expr:`PyTupleObject*` 或任" +"意 ``PyObject*``。如果傳入的 *args* 不是個 tuple（元組），則會自動建立一個長" +"度為 1 的 tuple 且 ``__args__`` 會被設為 ``(args,)``。只會進行最少的引數檢" +"查，所以即便 *origin* 不是個型別，函式也會不會失敗。 ``GenericAlias`` 的 " +"``__parameters__`` 屬性會自 ``__args__`` 惰性地建立 (constructed lazily)。當" +"失敗時，會引發一個例外並回傳 ``NULL``。" + +#: ../../c-api/typehints.rst:28 +msgid "Here's an example of how to make an extension type generic::" +msgstr "以下是個讓一個擴充型別泛用化 (generic) 的例子： ::" + +#: ../../c-api/typehints.rst:30 +msgid "" +"...\n" +"static PyMethodDef my_obj_methods[] = {\n" +" // Other methods.\n" +" ...\n" +" {\"__class_getitem__\", Py_GenericAlias, METH_O|METH_CLASS, \"See PEP " +"585\"}\n" +" ...\n" +"}" +msgstr "" +"...\n" +"static PyMethodDef my_obj_methods[] = {\n" +" // 其他方法。\n" +" ...\n" +" {\"__class_getitem__\", Py_GenericAlias, METH_O|METH_CLASS, \"See PEP " +"585\"}\n" +" ...\n" +"}" + +#: ../../c-api/typehints.rst:38 +msgid "The data model method :meth:`~object.__class_getitem__`." +msgstr "資料模型方法 :meth:`~object.__class_getitem__`。" + +#: ../../c-api/typehints.rst:44 +msgid "" +"The C type of the object returned by :c:func:`Py_GenericAlias`. Equivalent " +"to :class:`types.GenericAlias` in Python." +msgstr "" +":c:func:`Py_GenericAlias` 所回傳該物件的 C 型別。等價於 Python 中的 :class:" +"`types.GenericAlias`。" diff --git a/c-api/typeobj.po b/c-api/typeobj.po index 51e5ca4e1e..26a2975cf9 100644 --- a/c-api/typeobj.po +++ b/c-api/typeobj.po @@ -1,4784 +1,4784 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-12-09 00:14+0000\n" -"PO-Revision-Date: 2018-05-23 14:33+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" - -#: ../../c-api/typeobj.rst:6 -msgid "Type Object Structures" -msgstr "型別物件結構" - -#: ../../c-api/typeobj.rst:8 -msgid "" -"Perhaps one of the most important structures of the Python object system is " -"the structure that defines a new type: the :c:type:`PyTypeObject` " -"structure. Type objects can be handled using any of the ``PyObject_*`` or " -"``PyType_*`` functions, but do not offer much that's interesting to most " -"Python applications. These objects are fundamental to how objects behave, so " -"they are very important to the interpreter itself and to any extension " -"module that implements new types." -msgstr "" - -#: ../../c-api/typeobj.rst:16 -msgid "" -"Type objects are fairly large compared to most of the standard types. The " -"reason for the size is that each type object stores a large number of " -"values, mostly C function pointers, each of which implements a small part of " -"the type's functionality. The fields of the type object are examined in " -"detail in this section. The fields will be described in the order in which " -"they occur in the structure." -msgstr "" - -#: ../../c-api/typeobj.rst:23 -msgid "" -"In addition to the following quick reference, the :ref:`typedef-examples` " -"section provides at-a-glance insight into the meaning and use of :c:type:" -"`PyTypeObject`." -msgstr "" - -#: ../../c-api/typeobj.rst:29 -msgid "Quick Reference" -msgstr "" - -#: ../../c-api/typeobj.rst:34 -msgid "\"tp slots\"" -msgstr "\"tp slots\"" - -#: ../../c-api/typeobj.rst:40 -msgid "PyTypeObject Slot [#slots]_" -msgstr "" - -#: ../../c-api/typeobj.rst:40 ../../c-api/typeobj.rst:201 -msgid ":ref:`Type `" -msgstr ":ref:`Type `" - -#: ../../c-api/typeobj.rst:40 -msgid "special methods/attrs" -msgstr "" - -#: ../../c-api/typeobj.rst:40 -msgid "Info [#cols]_" -msgstr "" - -#: ../../c-api/typeobj.rst:42 -msgid "O" -msgstr "O" - -#: ../../c-api/typeobj.rst:42 -msgid "T" -msgstr "T" - -#: ../../c-api/typeobj.rst:42 -msgid "D" -msgstr "D" - -#: ../../c-api/typeobj.rst:42 -msgid "I" -msgstr "I" - -#: ../../c-api/typeobj.rst:44 -msgid " :c:member:`~PyTypeObject.tp_name`" -msgstr " :c:member:`~PyTypeObject.tp_name`" - -#: ../../c-api/typeobj.rst:44 ../../c-api/typeobj.rst:86 -#: ../../c-api/typeobj.rst:372 ../../c-api/typeobj.rst:377 -msgid "const char *" -msgstr "const char *" - -#: ../../c-api/typeobj.rst:44 -msgid "__name__" -msgstr "__name__" - -#: ../../c-api/typeobj.rst:44 ../../c-api/typeobj.rst:46 -#: ../../c-api/typeobj.rst:48 ../../c-api/typeobj.rst:50 -#: ../../c-api/typeobj.rst:52 ../../c-api/typeobj.rst:62 -#: ../../c-api/typeobj.rst:70 ../../c-api/typeobj.rst:72 -#: ../../c-api/typeobj.rst:74 ../../c-api/typeobj.rst:76 -#: ../../c-api/typeobj.rst:79 ../../c-api/typeobj.rst:84 -#: ../../c-api/typeobj.rst:86 ../../c-api/typeobj.rst:88 -#: ../../c-api/typeobj.rst:90 ../../c-api/typeobj.rst:92 -#: ../../c-api/typeobj.rst:99 ../../c-api/typeobj.rst:101 -#: ../../c-api/typeobj.rst:103 ../../c-api/typeobj.rst:105 -#: ../../c-api/typeobj.rst:107 ../../c-api/typeobj.rst:109 -#: ../../c-api/typeobj.rst:111 ../../c-api/typeobj.rst:115 -#: ../../c-api/typeobj.rst:117 ../../c-api/typeobj.rst:120 -#: ../../c-api/typeobj.rst:122 ../../c-api/typeobj.rst:124 -#: ../../c-api/typeobj.rst:126 ../../c-api/typeobj.rst:128 -#: ../../c-api/typeobj.rst:130 ../../c-api/typeobj.rst:146 -msgid "X" -msgstr "X" - -#: ../../c-api/typeobj.rst:46 -msgid ":c:member:`~PyTypeObject.tp_basicsize`" -msgstr ":c:member:`~PyTypeObject.tp_basicsize`" - -#: ../../c-api/typeobj.rst:46 ../../c-api/typeobj.rst:48 -#: ../../c-api/typeobj.rst:52 ../../c-api/typeobj.rst:99 -#: ../../c-api/typeobj.rst:120 ../../c-api/typeobj.rst:343 -#: ../../c-api/typeobj.rst:417 ../../c-api/typeobj.rst:448 -#: ../../c-api/typeobj.rst:453 -msgid ":c:type:`Py_ssize_t`" -msgstr ":c:type:`Py_ssize_t`" - -#: ../../c-api/typeobj.rst:48 -msgid ":c:member:`~PyTypeObject.tp_itemsize`" -msgstr ":c:member:`~PyTypeObject.tp_itemsize`" - -#: ../../c-api/typeobj.rst:50 -msgid ":c:member:`~PyTypeObject.tp_dealloc`" -msgstr ":c:member:`~PyTypeObject.tp_dealloc`" - -#: ../../c-api/typeobj.rst:50 ../../c-api/typeobj.rst:142 -#: ../../c-api/typeobj.rst:146 ../../c-api/typeobj.rst:347 -msgid ":c:type:`destructor`" -msgstr ":c:type:`destructor`" - -#: ../../c-api/typeobj.rst:52 -msgid ":c:member:`~PyTypeObject.tp_vectorcall_offset`" -msgstr ":c:member:`~PyTypeObject.tp_vectorcall_offset`" - -#: ../../c-api/typeobj.rst:54 -msgid "(:c:member:`~PyTypeObject.tp_getattr`)" -msgstr "(:c:member:`~PyTypeObject.tp_getattr`)" - -#: ../../c-api/typeobj.rst:54 ../../c-api/typeobj.rst:371 -msgid ":c:type:`getattrfunc`" -msgstr ":c:type:`getattrfunc`" - -#: ../../c-api/typeobj.rst:54 ../../c-api/typeobj.rst:76 -msgid "__getattribute__, __getattr__" -msgstr "__getattribute__, __getattr__" - -#: ../../c-api/typeobj.rst:54 ../../c-api/typeobj.rst:57 -#: ../../c-api/typeobj.rst:70 ../../c-api/typeobj.rst:76 -#: ../../c-api/typeobj.rst:79 ../../c-api/typeobj.rst:88 -#: ../../c-api/typeobj.rst:90 ../../c-api/typeobj.rst:92 -msgid "G" -msgstr "G" - -#: ../../c-api/typeobj.rst:57 -msgid "(:c:member:`~PyTypeObject.tp_setattr`)" -msgstr "(:c:member:`~PyTypeObject.tp_setattr`)" - -#: ../../c-api/typeobj.rst:57 ../../c-api/typeobj.rst:376 -msgid ":c:type:`setattrfunc`" -msgstr ":c:type:`setattrfunc`" - -#: ../../c-api/typeobj.rst:57 ../../c-api/typeobj.rst:79 -msgid "__setattr__, __delattr__" -msgstr "__setattr__, __delattr__" - -#: ../../c-api/typeobj.rst:60 -msgid ":c:member:`~PyTypeObject.tp_as_async`" -msgstr ":c:member:`~PyTypeObject.tp_as_async`" - -#: ../../c-api/typeobj.rst:60 -msgid ":c:type:`PyAsyncMethods` *" -msgstr ":c:type:`PyAsyncMethods` *" - -#: ../../c-api/typeobj.rst:60 ../../c-api/typeobj.rst:64 -#: ../../c-api/typeobj.rst:66 ../../c-api/typeobj.rst:68 -#: ../../c-api/typeobj.rst:82 -msgid ":ref:`sub-slots`" -msgstr ":ref:`sub-slots`" - -#: ../../c-api/typeobj.rst:60 ../../c-api/typeobj.rst:64 -#: ../../c-api/typeobj.rst:66 ../../c-api/typeobj.rst:68 -#: ../../c-api/typeobj.rst:82 -msgid "%" -msgstr "%" - -#: ../../c-api/typeobj.rst:62 -msgid ":c:member:`~PyTypeObject.tp_repr`" -msgstr ":c:member:`~PyTypeObject.tp_repr`" - -#: ../../c-api/typeobj.rst:62 ../../c-api/typeobj.rst:74 -#: ../../c-api/typeobj.rst:369 -msgid ":c:type:`reprfunc`" -msgstr ":c:type:`reprfunc`" - -#: ../../c-api/typeobj.rst:62 -msgid "__repr__" -msgstr "__repr__" - -#: ../../c-api/typeobj.rst:64 -msgid ":c:member:`~PyTypeObject.tp_as_number`" -msgstr ":c:member:`~PyTypeObject.tp_as_number`" - -#: ../../c-api/typeobj.rst:64 -msgid ":c:type:`PyNumberMethods` *" -msgstr ":c:type:`PyNumberMethods` *" - -#: ../../c-api/typeobj.rst:66 -msgid ":c:member:`~PyTypeObject.tp_as_sequence`" -msgstr ":c:member:`~PyTypeObject.tp_as_sequence`" - -#: ../../c-api/typeobj.rst:66 -msgid ":c:type:`PySequenceMethods` *" -msgstr ":c:type:`PySequenceMethods` *" - -#: ../../c-api/typeobj.rst:68 -msgid ":c:member:`~PyTypeObject.tp_as_mapping`" -msgstr ":c:member:`~PyTypeObject.tp_as_mapping`" - -#: ../../c-api/typeobj.rst:68 -msgid ":c:type:`PyMappingMethods` *" -msgstr ":c:type:`PyMappingMethods` *" - -#: ../../c-api/typeobj.rst:70 -msgid ":c:member:`~PyTypeObject.tp_hash`" -msgstr ":c:member:`~PyTypeObject.tp_hash`" - -#: ../../c-api/typeobj.rst:70 ../../c-api/typeobj.rst:405 -msgid ":c:type:`hashfunc`" -msgstr ":c:type:`hashfunc`" - -#: ../../c-api/typeobj.rst:70 -msgid "__hash__" -msgstr "__hash__" - -#: ../../c-api/typeobj.rst:72 -msgid ":c:member:`~PyTypeObject.tp_call`" -msgstr ":c:member:`~PyTypeObject.tp_call`" - -#: ../../c-api/typeobj.rst:72 ../../c-api/typeobj.rst:237 -#: ../../c-api/typeobj.rst:240 ../../c-api/typeobj.rst:441 -msgid ":c:type:`ternaryfunc`" -msgstr ":c:type:`ternaryfunc`" - -#: ../../c-api/typeobj.rst:72 -msgid "__call__" -msgstr "__call__" - -#: ../../c-api/typeobj.rst:74 -msgid ":c:member:`~PyTypeObject.tp_str`" -msgstr ":c:member:`~PyTypeObject.tp_str`" - -#: ../../c-api/typeobj.rst:74 -msgid "__str__" -msgstr "__str__" - -#: ../../c-api/typeobj.rst:76 -msgid ":c:member:`~PyTypeObject.tp_getattro`" -msgstr ":c:member:`~PyTypeObject.tp_getattro`" - -#: ../../c-api/typeobj.rst:76 ../../c-api/typeobj.rst:382 -msgid ":c:type:`getattrofunc`" -msgstr ":c:type:`getattrofunc`" - -#: ../../c-api/typeobj.rst:79 -msgid ":c:member:`~PyTypeObject.tp_setattro`" -msgstr ":c:member:`~PyTypeObject.tp_setattro`" - -#: ../../c-api/typeobj.rst:79 ../../c-api/typeobj.rst:387 -msgid ":c:type:`setattrofunc`" -msgstr ":c:type:`setattrofunc`" - -#: ../../c-api/typeobj.rst:82 -msgid ":c:member:`~PyTypeObject.tp_as_buffer`" -msgstr ":c:member:`~PyTypeObject.tp_as_buffer`" - -#: ../../c-api/typeobj.rst:82 -msgid ":c:type:`PyBufferProcs` *" -msgstr ":c:type:`PyBufferProcs` *" - -#: ../../c-api/typeobj.rst:84 -msgid ":c:member:`~PyTypeObject.tp_flags`" -msgstr ":c:member:`~PyTypeObject.tp_flags`" - -#: ../../c-api/typeobj.rst:84 -msgid "unsigned long" -msgstr "unsigned long" - -#: ../../c-api/typeobj.rst:84 ../../c-api/typeobj.rst:99 -#: ../../c-api/typeobj.rst:113 ../../c-api/typeobj.rst:120 -#: ../../c-api/typeobj.rst:124 ../../c-api/typeobj.rst:126 -#: ../../c-api/typeobj.rst:128 -msgid "?" -msgstr "?" - -#: ../../c-api/typeobj.rst:86 -msgid ":c:member:`~PyTypeObject.tp_doc`" -msgstr ":c:member:`~PyTypeObject.tp_doc`" - -#: ../../c-api/typeobj.rst:86 -msgid "__doc__" -msgstr "__doc__" - -#: ../../c-api/typeobj.rst:88 -msgid ":c:member:`~PyTypeObject.tp_traverse`" -msgstr ":c:member:`~PyTypeObject.tp_traverse`" - -#: ../../c-api/typeobj.rst:88 ../../c-api/typeobj.rst:351 -msgid ":c:type:`traverseproc`" -msgstr ":c:type:`traverseproc`" - -#: ../../c-api/typeobj.rst:90 -msgid ":c:member:`~PyTypeObject.tp_clear`" -msgstr ":c:member:`~PyTypeObject.tp_clear`" - -#: ../../c-api/typeobj.rst:90 ../../c-api/typeobj.rst:130 -#: ../../c-api/typeobj.rst:248 ../../c-api/typeobj.rst:430 -msgid ":c:type:`inquiry`" -msgstr ":c:type:`inquiry`" - -#: ../../c-api/typeobj.rst:92 -msgid ":c:member:`~PyTypeObject.tp_richcompare`" -msgstr ":c:member:`~PyTypeObject.tp_richcompare`" - -#: ../../c-api/typeobj.rst:92 ../../c-api/typeobj.rst:407 -msgid ":c:type:`richcmpfunc`" -msgstr ":c:type:`richcmpfunc`" - -#: ../../c-api/typeobj.rst:92 -msgid "__lt__, __le__, __eq__, __ne__, __gt__, __ge__" -msgstr "__lt__, __le__, __eq__, __ne__, __gt__, __ge__" - -#: ../../c-api/typeobj.rst:99 -msgid "(:c:member:`~PyTypeObject.tp_weaklistoffset`)" -msgstr "(:c:member:`~PyTypeObject.tp_weaklistoffset`)" - -#: ../../c-api/typeobj.rst:101 -msgid ":c:member:`~PyTypeObject.tp_iter`" -msgstr ":c:member:`~PyTypeObject.tp_iter`" - -#: ../../c-api/typeobj.rst:101 ../../c-api/typeobj.rst:413 -msgid ":c:type:`getiterfunc`" -msgstr ":c:type:`getiterfunc`" - -#: ../../c-api/typeobj.rst:101 -msgid "__iter__" -msgstr "__iter__" - -#: ../../c-api/typeobj.rst:103 -msgid ":c:member:`~PyTypeObject.tp_iternext`" -msgstr ":c:member:`~PyTypeObject.tp_iternext`" - -#: ../../c-api/typeobj.rst:103 ../../c-api/typeobj.rst:415 -msgid ":c:type:`iternextfunc`" -msgstr ":c:type:`iternextfunc`" - -#: ../../c-api/typeobj.rst:103 -msgid "__next__" -msgstr "__next__" - -#: ../../c-api/typeobj.rst:105 -msgid ":c:member:`~PyTypeObject.tp_methods`" -msgstr ":c:member:`~PyTypeObject.tp_methods`" - -#: ../../c-api/typeobj.rst:105 -msgid ":c:type:`PyMethodDef` []" -msgstr ":c:type:`PyMethodDef` []" - -#: ../../c-api/typeobj.rst:107 -msgid ":c:member:`~PyTypeObject.tp_members`" -msgstr ":c:member:`~PyTypeObject.tp_members`" - -#: ../../c-api/typeobj.rst:107 -msgid ":c:type:`PyMemberDef` []" -msgstr ":c:type:`PyMemberDef` []" - -#: ../../c-api/typeobj.rst:109 -msgid ":c:member:`~PyTypeObject.tp_getset`" -msgstr ":c:member:`~PyTypeObject.tp_getset`" - -#: ../../c-api/typeobj.rst:109 -msgid ":c:type:`PyGetSetDef` []" -msgstr ":c:type:`PyGetSetDef` []" - -#: ../../c-api/typeobj.rst:111 -msgid ":c:member:`~PyTypeObject.tp_base`" -msgstr ":c:member:`~PyTypeObject.tp_base`" - -#: ../../c-api/typeobj.rst:111 ../../c-api/typeobj.rst:342 -#: ../../c-api/typeobj.rst:357 -msgid ":c:type:`PyTypeObject` *" -msgstr ":c:type:`PyTypeObject` *" - -#: ../../c-api/typeobj.rst:111 -msgid "__base__" -msgstr "__base__" - -#: ../../c-api/typeobj.rst:113 -msgid ":c:member:`~PyTypeObject.tp_dict`" -msgstr ":c:member:`~PyTypeObject.tp_dict`" - -#: ../../c-api/typeobj.rst:113 ../../c-api/typeobj.rst:132 -#: ../../c-api/typeobj.rst:134 ../../c-api/typeobj.rst:136 -#: ../../c-api/typeobj.rst:140 ../../c-api/typeobj.rst:342 -#: ../../c-api/typeobj.rst:347 ../../c-api/typeobj.rst:351 -#: ../../c-api/typeobj.rst:357 ../../c-api/typeobj.rst:358 -#: ../../c-api/typeobj.rst:359 ../../c-api/typeobj.rst:363 -#: ../../c-api/typeobj.rst:364 ../../c-api/typeobj.rst:365 -#: ../../c-api/typeobj.rst:369 ../../c-api/typeobj.rst:371 -#: ../../c-api/typeobj.rst:376 ../../c-api/typeobj.rst:378 -#: ../../c-api/typeobj.rst:382 ../../c-api/typeobj.rst:383 -#: ../../c-api/typeobj.rst:387 ../../c-api/typeobj.rst:388 -#: ../../c-api/typeobj.rst:389 ../../c-api/typeobj.rst:393 -#: ../../c-api/typeobj.rst:394 ../../c-api/typeobj.rst:395 -#: ../../c-api/typeobj.rst:399 ../../c-api/typeobj.rst:400 -#: ../../c-api/typeobj.rst:401 ../../c-api/typeobj.rst:405 -#: ../../c-api/typeobj.rst:407 ../../c-api/typeobj.rst:408 -#: ../../c-api/typeobj.rst:413 ../../c-api/typeobj.rst:415 -#: ../../c-api/typeobj.rst:417 ../../c-api/typeobj.rst:419 -#: ../../c-api/typeobj.rst:425 ../../c-api/typeobj.rst:430 -#: ../../c-api/typeobj.rst:432 ../../c-api/typeobj.rst:436 -#: ../../c-api/typeobj.rst:437 ../../c-api/typeobj.rst:441 -#: ../../c-api/typeobj.rst:442 ../../c-api/typeobj.rst:443 -#: ../../c-api/typeobj.rst:447 ../../c-api/typeobj.rst:452 -#: ../../c-api/typeobj.rst:454 ../../c-api/typeobj.rst:458 -#: ../../c-api/typeobj.rst:459 ../../c-api/typeobj.rst:463 -#: ../../c-api/typeobj.rst:464 ../../c-api/typeobj.rst:465 -msgid ":c:type:`PyObject` *" -msgstr ":c:type:`PyObject` *" - -#: ../../c-api/typeobj.rst:113 -msgid "__dict__" -msgstr "__dict__" - -#: ../../c-api/typeobj.rst:115 -msgid ":c:member:`~PyTypeObject.tp_descr_get`" -msgstr ":c:member:`~PyTypeObject.tp_descr_get`" - -#: ../../c-api/typeobj.rst:115 ../../c-api/typeobj.rst:393 -msgid ":c:type:`descrgetfunc`" -msgstr ":c:type:`descrgetfunc`" - -#: ../../c-api/typeobj.rst:115 -msgid "__get__" -msgstr "__get__" - -#: ../../c-api/typeobj.rst:117 -msgid ":c:member:`~PyTypeObject.tp_descr_set`" -msgstr ":c:member:`~PyTypeObject.tp_descr_set`" - -#: ../../c-api/typeobj.rst:117 ../../c-api/typeobj.rst:399 -msgid ":c:type:`descrsetfunc`" -msgstr ":c:type:`descrsetfunc`" - -#: ../../c-api/typeobj.rst:117 -msgid "__set__, __delete__" -msgstr "__set__, __delete__" - -#: ../../c-api/typeobj.rst:120 -msgid "(:c:member:`~PyTypeObject.tp_dictoffset`)" -msgstr "(:c:member:`~PyTypeObject.tp_dictoffset`)" - -#: ../../c-api/typeobj.rst:122 -msgid ":c:member:`~PyTypeObject.tp_init`" -msgstr ":c:member:`~PyTypeObject.tp_init`" - -#: ../../c-api/typeobj.rst:122 ../../c-api/typeobj.rst:363 -msgid ":c:type:`initproc`" -msgstr ":c:type:`initproc`" - -#: ../../c-api/typeobj.rst:122 -msgid "__init__" -msgstr "__init__" - -#: ../../c-api/typeobj.rst:124 -msgid ":c:member:`~PyTypeObject.tp_alloc`" -msgstr ":c:member:`~PyTypeObject.tp_alloc`" - -#: ../../c-api/typeobj.rst:124 ../../c-api/typeobj.rst:342 -msgid ":c:type:`allocfunc`" -msgstr ":c:type:`allocfunc`" - -#: ../../c-api/typeobj.rst:126 -msgid ":c:member:`~PyTypeObject.tp_new`" -msgstr ":c:member:`~PyTypeObject.tp_new`" - -#: ../../c-api/typeobj.rst:126 ../../c-api/typeobj.rst:357 -msgid ":c:type:`newfunc`" -msgstr ":c:type:`newfunc`" - -#: ../../c-api/typeobj.rst:126 -msgid "__new__" -msgstr "__new__" - -#: ../../c-api/typeobj.rst:128 -msgid ":c:member:`~PyTypeObject.tp_free`" -msgstr ":c:member:`~PyTypeObject.tp_free`" - -#: ../../c-api/typeobj.rst:128 ../../c-api/typeobj.rst:349 -msgid ":c:type:`freefunc`" -msgstr ":c:type:`freefunc`" - -#: ../../c-api/typeobj.rst:130 -msgid ":c:member:`~PyTypeObject.tp_is_gc`" -msgstr ":c:member:`~PyTypeObject.tp_is_gc`" - -#: ../../c-api/typeobj.rst:132 -msgid "<:c:member:`~PyTypeObject.tp_bases`>" -msgstr "<:c:member:`~PyTypeObject.tp_bases`>" - -#: ../../c-api/typeobj.rst:132 -msgid "__bases__" -msgstr "__bases__" - -#: ../../c-api/typeobj.rst:132 ../../c-api/typeobj.rst:134 -msgid "~" -msgstr "~" - -#: ../../c-api/typeobj.rst:134 -msgid "<:c:member:`~PyTypeObject.tp_mro`>" -msgstr "<:c:member:`~PyTypeObject.tp_mro`>" - -#: ../../c-api/typeobj.rst:134 -msgid "__mro__" -msgstr "__mro__" - -#: ../../c-api/typeobj.rst:136 -msgid "[:c:member:`~PyTypeObject.tp_cache`]" -msgstr "[:c:member:`~PyTypeObject.tp_cache`]" - -#: ../../c-api/typeobj.rst:138 -msgid "[:c:member:`~PyTypeObject.tp_subclasses`]" -msgstr "[:c:member:`~PyTypeObject.tp_subclasses`]" - -#: ../../c-api/typeobj.rst:138 ../../c-api/typeobj.rst:279 -#: ../../c-api/typeobj.rst:349 ../../c-api/typeobj.rst:353 -msgid "void *" -msgstr "void *" - -#: ../../c-api/typeobj.rst:138 -msgid "__subclasses__" -msgstr "__subclasses__" - -#: ../../c-api/typeobj.rst:140 -msgid "[:c:member:`~PyTypeObject.tp_weaklist`]" -msgstr "[:c:member:`~PyTypeObject.tp_weaklist`]" - -#: ../../c-api/typeobj.rst:142 -msgid "(:c:member:`~PyTypeObject.tp_del`)" -msgstr "(:c:member:`~PyTypeObject.tp_del`)" - -#: ../../c-api/typeobj.rst:144 -msgid "[:c:member:`~PyTypeObject.tp_version_tag`]" -msgstr "[:c:member:`~PyTypeObject.tp_version_tag`]" - -#: ../../c-api/typeobj.rst:144 -msgid "unsigned int" -msgstr "unsigned int" - -#: ../../c-api/typeobj.rst:146 -msgid ":c:member:`~PyTypeObject.tp_finalize`" -msgstr ":c:member:`~PyTypeObject.tp_finalize`" - -#: ../../c-api/typeobj.rst:146 -msgid "__del__" -msgstr "__del__" - -#: ../../c-api/typeobj.rst:148 -msgid ":c:member:`~PyTypeObject.tp_vectorcall`" -msgstr ":c:member:`~PyTypeObject.tp_vectorcall`" - -#: ../../c-api/typeobj.rst:148 -msgid ":c:type:`vectorcallfunc`" -msgstr ":c:type:`vectorcallfunc`" - -#: ../../c-api/typeobj.rst:150 -msgid "[:c:member:`~PyTypeObject.tp_watched`]" -msgstr "[:c:member:`~PyTypeObject.tp_watched`]" - -#: ../../c-api/typeobj.rst:150 -msgid "unsigned char" -msgstr "unsigned char" - -#: ../../c-api/typeobj.rst:155 -msgid "" -"**()**: A slot name in parentheses indicates it is (effectively) deprecated." -msgstr "" - -#: ../../c-api/typeobj.rst:157 -msgid "" -"**<>**: Names in angle brackets should be initially set to ``NULL`` and " -"treated as read-only." -msgstr "" - -#: ../../c-api/typeobj.rst:160 -msgid "**[]**: Names in square brackets are for internal use only." -msgstr "" - -#: ../../c-api/typeobj.rst:162 -msgid "" -"**** (as a prefix) means the field is required (must be non-``NULL``)." -msgstr "" - -#: ../../c-api/typeobj.rst:164 -msgid "Columns:" -msgstr "" - -#: ../../c-api/typeobj.rst:166 -msgid "**\"O\"**: set on :c:data:`PyBaseObject_Type`" -msgstr "" - -#: ../../c-api/typeobj.rst:168 -msgid "**\"T\"**: set on :c:data:`PyType_Type`" -msgstr "" - -#: ../../c-api/typeobj.rst:170 -msgid "**\"D\"**: default (if slot is set to ``NULL``)" -msgstr "" - -#: ../../c-api/typeobj.rst:172 -msgid "" -"X - PyType_Ready sets this value if it is NULL\n" -"~ - PyType_Ready always sets this value (it should be NULL)\n" -"? - PyType_Ready may set this value depending on other slots\n" -"\n" -"Also see the inheritance column (\"I\")." -msgstr "" - -#: ../../c-api/typeobj.rst:180 -msgid "**\"I\"**: inheritance" -msgstr "" - -#: ../../c-api/typeobj.rst:182 -msgid "" -"X - type slot is inherited via *PyType_Ready* if defined with a *NULL* " -"value\n" -"% - the slots of the sub-struct are inherited individually\n" -"G - inherited, but only in combination with other slots; see the slot's " -"description\n" -"? - it's complicated; see the slot's description" -msgstr "" - -#: ../../c-api/typeobj.rst:189 -msgid "" -"Note that some slots are effectively inherited through the normal attribute " -"lookup chain." -msgstr "" - -#: ../../c-api/typeobj.rst:195 -msgid "sub-slots" -msgstr "" - -#: ../../c-api/typeobj.rst:201 -msgid "Slot" -msgstr "" - -#: ../../c-api/typeobj.rst:201 -msgid "special methods" -msgstr "" - -#: ../../c-api/typeobj.rst:204 -msgid ":c:member:`~PyAsyncMethods.am_await`" -msgstr ":c:member:`~PyAsyncMethods.am_await`" - -#: ../../c-api/typeobj.rst:204 ../../c-api/typeobj.rst:206 -#: ../../c-api/typeobj.rst:208 ../../c-api/typeobj.rst:242 -#: ../../c-api/typeobj.rst:244 ../../c-api/typeobj.rst:246 -#: ../../c-api/typeobj.rst:250 ../../c-api/typeobj.rst:277 -#: ../../c-api/typeobj.rst:281 ../../c-api/typeobj.rst:291 -#: ../../c-api/typeobj.rst:432 -msgid ":c:type:`unaryfunc`" -msgstr ":c:type:`unaryfunc`" - -#: ../../c-api/typeobj.rst:204 -msgid "__await__" -msgstr "__await__" - -#: ../../c-api/typeobj.rst:206 -msgid ":c:member:`~PyAsyncMethods.am_aiter`" -msgstr ":c:member:`~PyAsyncMethods.am_aiter`" - -#: ../../c-api/typeobj.rst:206 -msgid "__aiter__" -msgstr "__aiter__" - -#: ../../c-api/typeobj.rst:208 -msgid ":c:member:`~PyAsyncMethods.am_anext`" -msgstr ":c:member:`~PyAsyncMethods.am_anext`" - -#: ../../c-api/typeobj.rst:208 -msgid "__anext__" -msgstr "__anext__" - -#: ../../c-api/typeobj.rst:210 -msgid ":c:member:`~PyAsyncMethods.am_send`" -msgstr ":c:member:`~PyAsyncMethods.am_send`" - -#: ../../c-api/typeobj.rst:210 -msgid ":c:type:`sendfunc`" -msgstr ":c:type:`sendfunc`" - -#: ../../c-api/typeobj.rst:214 -msgid ":c:member:`~PyNumberMethods.nb_add`" -msgstr ":c:member:`~PyNumberMethods.nb_add`" - -#: ../../c-api/typeobj.rst:214 ../../c-api/typeobj.rst:217 -#: ../../c-api/typeobj.rst:219 ../../c-api/typeobj.rst:222 -#: ../../c-api/typeobj.rst:224 ../../c-api/typeobj.rst:227 -#: ../../c-api/typeobj.rst:229 ../../c-api/typeobj.rst:232 -#: ../../c-api/typeobj.rst:234 ../../c-api/typeobj.rst:252 -#: ../../c-api/typeobj.rst:255 ../../c-api/typeobj.rst:257 -#: ../../c-api/typeobj.rst:260 ../../c-api/typeobj.rst:262 -#: ../../c-api/typeobj.rst:265 ../../c-api/typeobj.rst:267 -#: ../../c-api/typeobj.rst:270 ../../c-api/typeobj.rst:272 -#: ../../c-api/typeobj.rst:275 ../../c-api/typeobj.rst:283 -#: ../../c-api/typeobj.rst:285 ../../c-api/typeobj.rst:287 -#: ../../c-api/typeobj.rst:289 ../../c-api/typeobj.rst:293 -#: ../../c-api/typeobj.rst:296 ../../c-api/typeobj.rst:302 -#: ../../c-api/typeobj.rst:311 ../../c-api/typeobj.rst:322 -#: ../../c-api/typeobj.rst:436 -msgid ":c:type:`binaryfunc`" -msgstr ":c:type:`binaryfunc`" - -#: ../../c-api/typeobj.rst:214 -msgid "__add__ __radd__" -msgstr "__add__ __radd__" - -#: ../../c-api/typeobj.rst:217 -msgid ":c:member:`~PyNumberMethods.nb_inplace_add`" -msgstr ":c:member:`~PyNumberMethods.nb_inplace_add`" - -#: ../../c-api/typeobj.rst:217 ../../c-api/typeobj.rst:322 -msgid "__iadd__" -msgstr "__iadd__" - -#: ../../c-api/typeobj.rst:219 -msgid ":c:member:`~PyNumberMethods.nb_subtract`" -msgstr ":c:member:`~PyNumberMethods.nb_subtract`" - -#: ../../c-api/typeobj.rst:219 -msgid "__sub__ __rsub__" -msgstr "__sub__ __rsub__" - -#: ../../c-api/typeobj.rst:222 -msgid ":c:member:`~PyNumberMethods.nb_inplace_subtract`" -msgstr ":c:member:`~PyNumberMethods.nb_inplace_subtract`" - -#: ../../c-api/typeobj.rst:222 -msgid "__isub__" -msgstr "__isub__" - -#: ../../c-api/typeobj.rst:224 -msgid ":c:member:`~PyNumberMethods.nb_multiply`" -msgstr ":c:member:`~PyNumberMethods.nb_multiply`" - -#: ../../c-api/typeobj.rst:224 -msgid "__mul__ __rmul__" -msgstr "__mul__ __rmul__" - -#: ../../c-api/typeobj.rst:227 -msgid ":c:member:`~PyNumberMethods.nb_inplace_multiply`" -msgstr ":c:member:`~PyNumberMethods.nb_inplace_multiply`" - -#: ../../c-api/typeobj.rst:227 ../../c-api/typeobj.rst:324 -msgid "__imul__" -msgstr "__imul__" - -#: ../../c-api/typeobj.rst:229 -msgid ":c:member:`~PyNumberMethods.nb_remainder`" -msgstr ":c:member:`~PyNumberMethods.nb_remainder`" - -#: ../../c-api/typeobj.rst:229 -msgid "__mod__ __rmod__" -msgstr "__mod__ __rmod__" - -#: ../../c-api/typeobj.rst:232 -msgid ":c:member:`~PyNumberMethods.nb_inplace_remainder`" -msgstr ":c:member:`~PyNumberMethods.nb_inplace_remainder`" - -#: ../../c-api/typeobj.rst:232 -msgid "__imod__" -msgstr "__imod__" - -#: ../../c-api/typeobj.rst:234 -msgid ":c:member:`~PyNumberMethods.nb_divmod`" -msgstr ":c:member:`~PyNumberMethods.nb_divmod`" - -#: ../../c-api/typeobj.rst:234 -msgid "__divmod__ __rdivmod__" -msgstr "__divmod__ __rdivmod__" - -#: ../../c-api/typeobj.rst:237 -msgid ":c:member:`~PyNumberMethods.nb_power`" -msgstr ":c:member:`~PyNumberMethods.nb_power`" - -#: ../../c-api/typeobj.rst:237 -msgid "__pow__ __rpow__" -msgstr "__pow__ __rpow__" - -#: ../../c-api/typeobj.rst:240 -msgid ":c:member:`~PyNumberMethods.nb_inplace_power`" -msgstr ":c:member:`~PyNumberMethods.nb_inplace_power`" - -#: ../../c-api/typeobj.rst:240 -msgid "__ipow__" -msgstr "__ipow__" - -#: ../../c-api/typeobj.rst:242 -msgid ":c:member:`~PyNumberMethods.nb_negative`" -msgstr ":c:member:`~PyNumberMethods.nb_negative`" - -#: ../../c-api/typeobj.rst:242 -msgid "__neg__" -msgstr "__neg__" - -#: ../../c-api/typeobj.rst:244 -msgid ":c:member:`~PyNumberMethods.nb_positive`" -msgstr ":c:member:`~PyNumberMethods.nb_positive`" - -#: ../../c-api/typeobj.rst:244 -msgid "__pos__" -msgstr "__pos__" - -#: ../../c-api/typeobj.rst:246 -msgid ":c:member:`~PyNumberMethods.nb_absolute`" -msgstr ":c:member:`~PyNumberMethods.nb_absolute`" - -#: ../../c-api/typeobj.rst:246 -msgid "__abs__" -msgstr "__abs__" - -#: ../../c-api/typeobj.rst:248 -msgid ":c:member:`~PyNumberMethods.nb_bool`" -msgstr ":c:member:`~PyNumberMethods.nb_bool`" - -#: ../../c-api/typeobj.rst:248 -msgid "__bool__" -msgstr "__bool__" - -#: ../../c-api/typeobj.rst:250 -msgid ":c:member:`~PyNumberMethods.nb_invert`" -msgstr ":c:member:`~PyNumberMethods.nb_invert`" - -#: ../../c-api/typeobj.rst:250 -msgid "__invert__" -msgstr "__invert__" - -#: ../../c-api/typeobj.rst:252 -msgid ":c:member:`~PyNumberMethods.nb_lshift`" -msgstr ":c:member:`~PyNumberMethods.nb_lshift`" - -#: ../../c-api/typeobj.rst:252 -msgid "__lshift__ __rlshift__" -msgstr "__lshift__ __rlshift__" - -#: ../../c-api/typeobj.rst:255 -msgid ":c:member:`~PyNumberMethods.nb_inplace_lshift`" -msgstr ":c:member:`~PyNumberMethods.nb_inplace_lshift`" - -#: ../../c-api/typeobj.rst:255 -msgid "__ilshift__" -msgstr "__ilshift__" - -#: ../../c-api/typeobj.rst:257 -msgid ":c:member:`~PyNumberMethods.nb_rshift`" -msgstr ":c:member:`~PyNumberMethods.nb_rshift`" - -#: ../../c-api/typeobj.rst:257 -msgid "__rshift__ __rrshift__" -msgstr "__rshift__ __rrshift__" - -#: ../../c-api/typeobj.rst:260 -msgid ":c:member:`~PyNumberMethods.nb_inplace_rshift`" -msgstr ":c:member:`~PyNumberMethods.nb_inplace_rshift`" - -#: ../../c-api/typeobj.rst:260 -msgid "__irshift__" -msgstr "__irshift__" - -#: ../../c-api/typeobj.rst:262 -msgid ":c:member:`~PyNumberMethods.nb_and`" -msgstr ":c:member:`~PyNumberMethods.nb_and`" - -#: ../../c-api/typeobj.rst:262 -msgid "__and__ __rand__" -msgstr "__and__ __rand__" - -#: ../../c-api/typeobj.rst:265 -msgid ":c:member:`~PyNumberMethods.nb_inplace_and`" -msgstr ":c:member:`~PyNumberMethods.nb_inplace_and`" - -#: ../../c-api/typeobj.rst:265 -msgid "__iand__" -msgstr "__iand__" - -#: ../../c-api/typeobj.rst:267 -msgid ":c:member:`~PyNumberMethods.nb_xor`" -msgstr ":c:member:`~PyNumberMethods.nb_xor`" - -#: ../../c-api/typeobj.rst:267 -msgid "__xor__ __rxor__" -msgstr "__xor__ __rxor__" - -#: ../../c-api/typeobj.rst:270 -msgid ":c:member:`~PyNumberMethods.nb_inplace_xor`" -msgstr ":c:member:`~PyNumberMethods.nb_inplace_xor`" - -#: ../../c-api/typeobj.rst:270 -msgid "__ixor__" -msgstr "__ixor__" - -#: ../../c-api/typeobj.rst:272 -msgid ":c:member:`~PyNumberMethods.nb_or`" -msgstr ":c:member:`~PyNumberMethods.nb_or`" - -#: ../../c-api/typeobj.rst:272 -msgid "__or__ __ror__" -msgstr "__or__ __ror__" - -#: ../../c-api/typeobj.rst:275 -msgid ":c:member:`~PyNumberMethods.nb_inplace_or`" -msgstr ":c:member:`~PyNumberMethods.nb_inplace_or`" - -#: ../../c-api/typeobj.rst:275 -msgid "__ior__" -msgstr "__ior__" - -#: ../../c-api/typeobj.rst:277 -msgid ":c:member:`~PyNumberMethods.nb_int`" -msgstr ":c:member:`~PyNumberMethods.nb_int`" - -#: ../../c-api/typeobj.rst:277 -msgid "__int__" -msgstr "__int__" - -#: ../../c-api/typeobj.rst:279 -msgid ":c:member:`~PyNumberMethods.nb_reserved`" -msgstr ":c:member:`~PyNumberMethods.nb_reserved`" - -#: ../../c-api/typeobj.rst:281 -msgid ":c:member:`~PyNumberMethods.nb_float`" -msgstr ":c:member:`~PyNumberMethods.nb_float`" - -#: ../../c-api/typeobj.rst:281 -msgid "__float__" -msgstr "__float__" - -#: ../../c-api/typeobj.rst:283 -msgid ":c:member:`~PyNumberMethods.nb_floor_divide`" -msgstr ":c:member:`~PyNumberMethods.nb_floor_divide`" - -#: ../../c-api/typeobj.rst:283 -msgid "__floordiv__" -msgstr "__floordiv__" - -#: ../../c-api/typeobj.rst:285 -msgid ":c:member:`~PyNumberMethods.nb_inplace_floor_divide`" -msgstr ":c:member:`~PyNumberMethods.nb_inplace_floor_divide`" - -#: ../../c-api/typeobj.rst:285 -msgid "__ifloordiv__" -msgstr "__ifloordiv__" - -#: ../../c-api/typeobj.rst:287 -msgid ":c:member:`~PyNumberMethods.nb_true_divide`" -msgstr ":c:member:`~PyNumberMethods.nb_true_divide`" - -#: ../../c-api/typeobj.rst:287 -msgid "__truediv__" -msgstr "__truediv__" - -#: ../../c-api/typeobj.rst:289 -msgid ":c:member:`~PyNumberMethods.nb_inplace_true_divide`" -msgstr ":c:member:`~PyNumberMethods.nb_inplace_true_divide`" - -#: ../../c-api/typeobj.rst:289 -msgid "__itruediv__" -msgstr "__itruediv__" - -#: ../../c-api/typeobj.rst:291 -msgid ":c:member:`~PyNumberMethods.nb_index`" -msgstr ":c:member:`~PyNumberMethods.nb_index`" - -#: ../../c-api/typeobj.rst:291 -msgid "__index__" -msgstr "__index__" - -#: ../../c-api/typeobj.rst:293 -msgid ":c:member:`~PyNumberMethods.nb_matrix_multiply`" -msgstr ":c:member:`~PyNumberMethods.nb_matrix_multiply`" - -#: ../../c-api/typeobj.rst:293 -msgid "__matmul__ __rmatmul__" -msgstr "__matmul__ __rmatmul__" - -#: ../../c-api/typeobj.rst:296 -msgid ":c:member:`~PyNumberMethods.nb_inplace_matrix_multiply`" -msgstr ":c:member:`~PyNumberMethods.nb_inplace_matrix_multiply`" - -#: ../../c-api/typeobj.rst:296 -msgid "__imatmul__" -msgstr "__imatmul__" - -#: ../../c-api/typeobj.rst:300 -msgid ":c:member:`~PyMappingMethods.mp_length`" -msgstr ":c:member:`~PyMappingMethods.mp_length`" - -#: ../../c-api/typeobj.rst:300 ../../c-api/typeobj.rst:309 -#: ../../c-api/typeobj.rst:417 -msgid ":c:type:`lenfunc`" -msgstr ":c:type:`lenfunc`" - -#: ../../c-api/typeobj.rst:300 ../../c-api/typeobj.rst:309 -msgid "__len__" -msgstr "__len__" - -#: ../../c-api/typeobj.rst:302 -msgid ":c:member:`~PyMappingMethods.mp_subscript`" -msgstr ":c:member:`~PyMappingMethods.mp_subscript`" - -#: ../../c-api/typeobj.rst:302 ../../c-api/typeobj.rst:315 -msgid "__getitem__" -msgstr "__getitem__" - -#: ../../c-api/typeobj.rst:304 -msgid ":c:member:`~PyMappingMethods.mp_ass_subscript`" -msgstr ":c:member:`~PyMappingMethods.mp_ass_subscript`" - -#: ../../c-api/typeobj.rst:304 ../../c-api/typeobj.rst:463 -msgid ":c:type:`objobjargproc`" -msgstr ":c:type:`objobjargproc`" - -#: ../../c-api/typeobj.rst:304 -msgid "__setitem__, __delitem__" -msgstr "__setitem__, __delitem__" - -#: ../../c-api/typeobj.rst:309 -msgid ":c:member:`~PySequenceMethods.sq_length`" -msgstr ":c:member:`~PySequenceMethods.sq_length`" - -#: ../../c-api/typeobj.rst:311 -msgid ":c:member:`~PySequenceMethods.sq_concat`" -msgstr ":c:member:`~PySequenceMethods.sq_concat`" - -#: ../../c-api/typeobj.rst:311 -msgid "__add__" -msgstr "__add__" - -#: ../../c-api/typeobj.rst:313 -msgid ":c:member:`~PySequenceMethods.sq_repeat`" -msgstr ":c:member:`~PySequenceMethods.sq_repeat`" - -#: ../../c-api/typeobj.rst:313 ../../c-api/typeobj.rst:315 -#: ../../c-api/typeobj.rst:324 ../../c-api/typeobj.rst:447 -msgid ":c:type:`ssizeargfunc`" -msgstr ":c:type:`ssizeargfunc`" - -#: ../../c-api/typeobj.rst:313 -msgid "__mul__" -msgstr "__mul__" - -#: ../../c-api/typeobj.rst:315 -msgid ":c:member:`~PySequenceMethods.sq_item`" -msgstr ":c:member:`~PySequenceMethods.sq_item`" - -#: ../../c-api/typeobj.rst:317 -msgid ":c:member:`~PySequenceMethods.sq_ass_item`" -msgstr ":c:member:`~PySequenceMethods.sq_ass_item`" - -#: ../../c-api/typeobj.rst:317 ../../c-api/typeobj.rst:452 -msgid ":c:type:`ssizeobjargproc`" -msgstr ":c:type:`ssizeobjargproc`" - -#: ../../c-api/typeobj.rst:317 -msgid "__setitem__ __delitem__" -msgstr "__setitem__ __delitem__" - -#: ../../c-api/typeobj.rst:320 -msgid ":c:member:`~PySequenceMethods.sq_contains`" -msgstr ":c:member:`~PySequenceMethods.sq_contains`" - -#: ../../c-api/typeobj.rst:320 ../../c-api/typeobj.rst:458 -msgid ":c:type:`objobjproc`" -msgstr ":c:type:`objobjproc`" - -#: ../../c-api/typeobj.rst:320 -msgid "__contains__" -msgstr "__contains__" - -#: ../../c-api/typeobj.rst:322 -msgid ":c:member:`~PySequenceMethods.sq_inplace_concat`" -msgstr ":c:member:`~PySequenceMethods.sq_inplace_concat`" - -#: ../../c-api/typeobj.rst:324 -msgid ":c:member:`~PySequenceMethods.sq_inplace_repeat`" -msgstr ":c:member:`~PySequenceMethods.sq_inplace_repeat`" - -#: ../../c-api/typeobj.rst:328 -msgid ":c:member:`~PyBufferProcs.bf_getbuffer`" -msgstr ":c:member:`~PyBufferProcs.bf_getbuffer`" - -#: ../../c-api/typeobj.rst:328 -msgid ":c:func:`getbufferproc`" -msgstr ":c:func:`getbufferproc`" - -#: ../../c-api/typeobj.rst:328 -msgid "__buffer__" -msgstr "__buffer__" - -#: ../../c-api/typeobj.rst:330 -msgid ":c:member:`~PyBufferProcs.bf_releasebuffer`" -msgstr ":c:member:`~PyBufferProcs.bf_releasebuffer`" - -#: ../../c-api/typeobj.rst:330 -msgid ":c:func:`releasebufferproc`" -msgstr ":c:func:`releasebufferproc`" - -#: ../../c-api/typeobj.rst:330 -msgid "__release_ buffer\\__" -msgstr "__release_ buffer\\__" - -#: ../../c-api/typeobj.rst:337 -msgid "slot typedefs" -msgstr "" - -#: ../../c-api/typeobj.rst:340 -msgid "typedef" -msgstr "typedef" - -#: ../../c-api/typeobj.rst:340 -msgid "Parameter Types" -msgstr "" - -#: ../../c-api/typeobj.rst:340 -msgid "Return Type" -msgstr "" - -#: ../../c-api/typeobj.rst:347 ../../c-api/typeobj.rst:349 -#: ../../c-api/typeobj.rst:425 -msgid "void" -msgstr "void" - -#: ../../c-api/typeobj.rst:352 -msgid ":c:type:`visitproc`" -msgstr ":c:type:`visitproc`" - -#: ../../c-api/typeobj.rst:351 ../../c-api/typeobj.rst:363 -#: ../../c-api/typeobj.rst:376 ../../c-api/typeobj.rst:387 -#: ../../c-api/typeobj.rst:399 ../../c-api/typeobj.rst:409 -#: ../../c-api/typeobj.rst:419 ../../c-api/typeobj.rst:421 -#: ../../c-api/typeobj.rst:430 ../../c-api/typeobj.rst:452 -#: ../../c-api/typeobj.rst:458 ../../c-api/typeobj.rst:463 -msgid "int" -msgstr "int" - -#: ../../c-api/typeobj.rst:405 -msgid "Py_hash_t" -msgstr "Py_hash_t" - -#: ../../c-api/typeobj.rst:419 -msgid ":c:type:`getbufferproc`" -msgstr ":c:type:`getbufferproc`" - -#: ../../c-api/typeobj.rst:420 ../../c-api/typeobj.rst:426 -msgid ":c:type:`Py_buffer` *" -msgstr ":c:type:`Py_buffer` *" - -#: ../../c-api/typeobj.rst:425 -msgid ":c:type:`releasebufferproc`" -msgstr ":c:type:`releasebufferproc`" - -#: ../../c-api/typeobj.rst:470 -msgid "See :ref:`slot-typedefs` below for more detail." -msgstr "更多細節請見下方的 :ref:`slot-typedefs`。" - -#: ../../c-api/typeobj.rst:474 -msgid "PyTypeObject Definition" -msgstr "" - -#: ../../c-api/typeobj.rst:476 -msgid "" -"The structure definition for :c:type:`PyTypeObject` can be found in :file:" -"`Include/cpython/object.h`. For convenience of reference, this repeats the " -"definition found there:" -msgstr "" - -#: ../../c-api/typeobj.rst:482 -msgid "" -"typedef struct _typeobject {\n" -" PyObject_VAR_HEAD\n" -" const char *tp_name; /* For printing, in format \".\" */\n" -" Py_ssize_t tp_basicsize, tp_itemsize; /* For allocation */\n" -"\n" -" /* Methods to implement standard operations */\n" -"\n" -" destructor tp_dealloc;\n" -" Py_ssize_t tp_vectorcall_offset;\n" -" getattrfunc tp_getattr;\n" -" setattrfunc tp_setattr;\n" -" PyAsyncMethods *tp_as_async; /* formerly known as tp_compare (Python 2)\n" -" or tp_reserved (Python 3) */\n" -" reprfunc tp_repr;\n" -"\n" -" /* Method suites for standard classes */\n" -"\n" -" PyNumberMethods *tp_as_number;\n" -" PySequenceMethods *tp_as_sequence;\n" -" PyMappingMethods *tp_as_mapping;\n" -"\n" -" /* More standard operations (here for binary compatibility) */\n" -"\n" -" hashfunc tp_hash;\n" -" ternaryfunc tp_call;\n" -" reprfunc tp_str;\n" -" getattrofunc tp_getattro;\n" -" setattrofunc tp_setattro;\n" -"\n" -" /* Functions to access object as input/output buffer */\n" -" PyBufferProcs *tp_as_buffer;\n" -"\n" -" /* Flags to define presence of optional/expanded features */\n" -" unsigned long tp_flags;\n" -"\n" -" const char *tp_doc; /* Documentation string */\n" -"\n" -" /* Assigned meaning in release 2.0 */\n" -" /* call function for all accessible objects */\n" -" traverseproc tp_traverse;\n" -"\n" -" /* delete references to contained objects */\n" -" inquiry tp_clear;\n" -"\n" -" /* Assigned meaning in release 2.1 */\n" -" /* rich comparisons */\n" -" richcmpfunc tp_richcompare;\n" -"\n" -" /* weak reference enabler */\n" -" Py_ssize_t tp_weaklistoffset;\n" -"\n" -" /* Iterators */\n" -" getiterfunc tp_iter;\n" -" iternextfunc tp_iternext;\n" -"\n" -" /* Attribute descriptor and subclassing stuff */\n" -" PyMethodDef *tp_methods;\n" -" PyMemberDef *tp_members;\n" -" PyGetSetDef *tp_getset;\n" -" // Strong reference on a heap type, borrowed reference on a static type\n" -" PyTypeObject *tp_base;\n" -" PyObject *tp_dict;\n" -" descrgetfunc tp_descr_get;\n" -" descrsetfunc tp_descr_set;\n" -" Py_ssize_t tp_dictoffset;\n" -" initproc tp_init;\n" -" allocfunc tp_alloc;\n" -" newfunc tp_new;\n" -" freefunc tp_free; /* Low-level free-memory routine */\n" -" inquiry tp_is_gc; /* For PyObject_IS_GC */\n" -" PyObject *tp_bases;\n" -" PyObject *tp_mro; /* method resolution order */\n" -" PyObject *tp_cache; /* no longer used */\n" -" void *tp_subclasses; /* for static builtin types this is an index */\n" -" PyObject *tp_weaklist; /* not used for static builtin types */\n" -" destructor tp_del;\n" -"\n" -" /* Type attribute cache version tag. Added in version 2.6.\n" -" * If zero, the cache is invalid and must be initialized.\n" -" */\n" -" unsigned int tp_version_tag;\n" -"\n" -" destructor tp_finalize;\n" -" vectorcallfunc tp_vectorcall;\n" -"\n" -" /* bitset of which type-watchers care about this type */\n" -" unsigned char tp_watched;\n" -"\n" -" /* Number of tp_version_tag values used.\n" -" * Set to _Py_ATTR_CACHE_UNUSED if the attribute cache is\n" -" * disabled for this type (e.g. due to custom MRO entries).\n" -" * Otherwise, limited to MAX_VERSIONS_PER_CLASS (defined elsewhere).\n" -" */\n" -" uint16_t tp_versions_used;\n" -"} PyTypeObject;\n" -msgstr "" - -#: ../../c-api/typeobj.rst:486 -msgid "PyObject Slots" -msgstr "" - -#: ../../c-api/typeobj.rst:488 -msgid "" -"The type object structure extends the :c:type:`PyVarObject` structure. The :" -"c:member:`~PyVarObject.ob_size` field is used for dynamic types (created by :" -"c:func:`!type_new`, usually called from a class statement). Note that :c:" -"data:`PyType_Type` (the metatype) initializes :c:member:`~PyTypeObject." -"tp_itemsize`, which means that its instances (i.e. type objects) *must* have " -"the :c:member:`~PyVarObject.ob_size` field." -msgstr "" - -#: ../../c-api/typeobj.rst:495 -msgid ":c:member:`PyObject.ob_refcnt`" -msgstr ":c:member:`PyObject.ob_refcnt`" - -#: ../../c-api/typeobj.rst:497 -msgid "" -"The type object's reference count is initialized to ``1`` by the " -"``PyObject_HEAD_INIT`` macro. Note that for :ref:`statically allocated type " -"objects `, the type's instances (objects whose :c:member:" -"`~PyObject.ob_type` points back to the type) do *not* count as references. " -"But for :ref:`dynamically allocated type objects `, the " -"instances *do* count as references." -msgstr "" - -#: ../../c-api/typeobj.rst:504 ../../c-api/typeobj.rst:527 -#: ../../c-api/typeobj.rst:543 ../../c-api/typeobj.rst:587 -#: ../../c-api/typeobj.rst:665 ../../c-api/typeobj.rst:809 -#: ../../c-api/typeobj.rst:854 ../../c-api/typeobj.rst:873 -#: ../../c-api/typeobj.rst:892 ../../c-api/typeobj.rst:910 -#: ../../c-api/typeobj.rst:936 ../../c-api/typeobj.rst:953 -#: ../../c-api/typeobj.rst:965 ../../c-api/typeobj.rst:977 -#: ../../c-api/typeobj.rst:1012 ../../c-api/typeobj.rst:1036 -#: ../../c-api/typeobj.rst:1058 ../../c-api/typeobj.rst:1081 -#: ../../c-api/typeobj.rst:1109 ../../c-api/typeobj.rst:1128 -#: ../../c-api/typeobj.rst:1144 ../../c-api/typeobj.rst:1184 -#: ../../c-api/typeobj.rst:1195 ../../c-api/typeobj.rst:1205 -#: ../../c-api/typeobj.rst:1215 ../../c-api/typeobj.rst:1229 -#: ../../c-api/typeobj.rst:1247 ../../c-api/typeobj.rst:1270 -#: ../../c-api/typeobj.rst:1288 ../../c-api/typeobj.rst:1301 -#: ../../c-api/typeobj.rst:1323 ../../c-api/typeobj.rst:1367 -#: ../../c-api/typeobj.rst:1388 ../../c-api/typeobj.rst:1407 -#: ../../c-api/typeobj.rst:1437 ../../c-api/typeobj.rst:1459 -#: ../../c-api/typeobj.rst:1487 ../../c-api/typeobj.rst:1585 -#: ../../c-api/typeobj.rst:1731 ../../c-api/typeobj.rst:1798 -#: ../../c-api/typeobj.rst:1834 ../../c-api/typeobj.rst:1861 -#: ../../c-api/typeobj.rst:1886 ../../c-api/typeobj.rst:1901 -#: ../../c-api/typeobj.rst:1918 ../../c-api/typeobj.rst:1934 -#: ../../c-api/typeobj.rst:1966 ../../c-api/typeobj.rst:1998 -#: ../../c-api/typeobj.rst:2026 ../../c-api/typeobj.rst:2046 -#: ../../c-api/typeobj.rst:2075 ../../c-api/typeobj.rst:2121 -#: ../../c-api/typeobj.rst:2140 ../../c-api/typeobj.rst:2182 -#: ../../c-api/typeobj.rst:2207 ../../c-api/typeobj.rst:2247 -#: ../../c-api/typeobj.rst:2277 ../../c-api/typeobj.rst:2290 -#: ../../c-api/typeobj.rst:2300 ../../c-api/typeobj.rst:2317 -#: ../../c-api/typeobj.rst:2334 ../../c-api/typeobj.rst:2350 -#: ../../c-api/typeobj.rst:2494 ../../c-api/typeobj.rst:2554 -msgid "**Inheritance:**" -msgstr "" - -#: ../../c-api/typeobj.rst:506 ../../c-api/typeobj.rst:545 -#: ../../c-api/typeobj.rst:589 -msgid "This field is not inherited by subtypes." -msgstr "" - -#: ../../c-api/typeobj.rst:509 -msgid ":c:member:`PyObject.ob_type`" -msgstr ":c:member:`PyObject.ob_type`" - -#: ../../c-api/typeobj.rst:511 -msgid "" -"This is the type's type, in other words its metatype. It is initialized by " -"the argument to the ``PyObject_HEAD_INIT`` macro, and its value should " -"normally be ``&PyType_Type``. However, for dynamically loadable extension " -"modules that must be usable on Windows (at least), the compiler complains " -"that this is not a valid initializer. Therefore, the convention is to pass " -"``NULL`` to the ``PyObject_HEAD_INIT`` macro and to initialize this field " -"explicitly at the start of the module's initialization function, before " -"doing anything else. This is typically done like this::" -msgstr "" - -#: ../../c-api/typeobj.rst:520 -msgid "Foo_Type.ob_type = &PyType_Type;" -msgstr "Foo_Type.ob_type = &PyType_Type;" - -#: ../../c-api/typeobj.rst:522 -msgid "" -"This should be done before any instances of the type are created. :c:func:" -"`PyType_Ready` checks if :c:member:`~PyObject.ob_type` is ``NULL``, and if " -"so, initializes it to the :c:member:`~PyObject.ob_type` field of the base " -"class. :c:func:`PyType_Ready` will not change this field if it is non-zero." -msgstr "" - -#: ../../c-api/typeobj.rst:529 ../../c-api/typeobj.rst:811 -#: ../../c-api/typeobj.rst:938 ../../c-api/typeobj.rst:1038 -#: ../../c-api/typeobj.rst:1060 ../../c-api/typeobj.rst:1863 -#: ../../c-api/typeobj.rst:1888 ../../c-api/typeobj.rst:2028 -#: ../../c-api/typeobj.rst:2048 ../../c-api/typeobj.rst:2123 -#: ../../c-api/typeobj.rst:2249 ../../c-api/typeobj.rst:2496 -msgid "This field is inherited by subtypes." -msgstr "" - -#: ../../c-api/typeobj.rst:533 -msgid "PyVarObject Slots" -msgstr "" - -#: ../../c-api/typeobj.rst:535 -msgid ":c:member:`PyVarObject.ob_size`" -msgstr ":c:member:`PyVarObject.ob_size`" - -#: ../../c-api/typeobj.rst:537 -msgid "" -"For :ref:`statically allocated type objects `, this should be " -"initialized to zero. For :ref:`dynamically allocated type objects `, this field has a special internal meaning." -msgstr "" - -#: ../../c-api/typeobj.rst:541 -msgid "This field should be accessed using the :c:func:`Py_SIZE()` macro." -msgstr "" - -#: ../../c-api/typeobj.rst:549 -msgid "PyTypeObject Slots" -msgstr "" - -#: ../../c-api/typeobj.rst:551 -msgid "" -"Each slot has a section describing inheritance. If :c:func:`PyType_Ready` " -"may set a value when the field is set to ``NULL`` then there will also be a " -"\"Default\" section. (Note that many fields set on :c:data:" -"`PyBaseObject_Type` and :c:data:`PyType_Type` effectively act as defaults.)" -msgstr "" - -#: ../../c-api/typeobj.rst:558 -msgid "" -"Pointer to a NUL-terminated string containing the name of the type. For " -"types that are accessible as module globals, the string should be the full " -"module name, followed by a dot, followed by the type name; for built-in " -"types, it should be just the type name. If the module is a submodule of a " -"package, the full package name is part of the full module name. For " -"example, a type named :class:`!T` defined in module :mod:`!M` in subpackage :" -"mod:`!Q` in package :mod:`!P` should have the :c:member:`~PyTypeObject." -"tp_name` initializer ``\"P.Q.M.T\"``." -msgstr "" - -#: ../../c-api/typeobj.rst:566 -msgid "" -"For :ref:`dynamically allocated type objects `, this should just " -"be the type name, and the module name explicitly stored in the type dict as " -"the value for key ``'__module__'``." -msgstr "" - -#: ../../c-api/typeobj.rst:571 -msgid "" -"For :ref:`statically allocated type objects `, the *tp_name* " -"field should contain a dot. Everything before the last dot is made " -"accessible as the :attr:`~type.__module__` attribute, and everything after " -"the last dot is made accessible as the :attr:`~type.__name__` attribute." -msgstr "" - -#: ../../c-api/typeobj.rst:577 -msgid "" -"If no dot is present, the entire :c:member:`~PyTypeObject.tp_name` field is " -"made accessible as the :attr:`~type.__name__` attribute, and the :attr:" -"`~type.__module__` attribute is undefined (unless explicitly set in the " -"dictionary, as explained above). This means your type will be impossible to " -"pickle. Additionally, it will not be listed in module documentations " -"created with pydoc." -msgstr "" - -#: ../../c-api/typeobj.rst:583 -msgid "" -"This field must not be ``NULL``. It is the only required field in :c:func:" -"`PyTypeObject` (other than potentially :c:member:`~PyTypeObject." -"tp_itemsize`)." -msgstr "" - -#: ../../c-api/typeobj.rst:595 -msgid "" -"These fields allow calculating the size in bytes of instances of the type." -msgstr "" - -#: ../../c-api/typeobj.rst:597 -msgid "" -"There are two kinds of types: types with fixed-length instances have a zero :" -"c:member:`!tp_itemsize` field, types with variable-length instances have a " -"non-zero :c:member:`!tp_itemsize` field. For a type with fixed-length " -"instances, all instances have the same size, given in :c:member:`!" -"tp_basicsize`. (Exceptions to this rule can be made using :c:func:" -"`PyUnstable_Object_GC_NewWithExtraData`.)" -msgstr "" - -#: ../../c-api/typeobj.rst:604 -msgid "" -"For a type with variable-length instances, the instances must have an :c:" -"member:`~PyVarObject.ob_size` field, and the instance size is :c:member:`!" -"tp_basicsize` plus N times :c:member:`!tp_itemsize`, where N is the " -"\"length\" of the object." -msgstr "" - -#: ../../c-api/typeobj.rst:609 -msgid "" -"Functions like :c:func:`PyObject_NewVar` will take the value of N as an " -"argument, and store in the instance's :c:member:`~PyVarObject.ob_size` " -"field. Note that the :c:member:`~PyVarObject.ob_size` field may later be " -"used for other purposes. For example, :py:type:`int` instances use the bits " -"of :c:member:`~PyVarObject.ob_size` in an implementation-defined way; the " -"underlying storage and its size should be accessed using :c:func:" -"`PyLong_Export`." -msgstr "" - -#: ../../c-api/typeobj.rst:619 -msgid "" -"The :c:member:`~PyVarObject.ob_size` field should be accessed using the :c:" -"func:`Py_SIZE()` and :c:func:`Py_SET_SIZE()` macros." -msgstr "" - -#: ../../c-api/typeobj.rst:622 -msgid "" -"Also, the presence of an :c:member:`~PyVarObject.ob_size` field in the " -"instance layout doesn't mean that the instance structure is variable-length. " -"For example, the :py:type:`list` type has fixed-length instances, yet those " -"instances have a :c:member:`~PyVarObject.ob_size` field. (As with :py:type:" -"`int`, avoid reading lists' :c:member:`!ob_size` directly. Call :c:func:" -"`PyList_Size` instead.)" -msgstr "" - -#: ../../c-api/typeobj.rst:629 -msgid "" -"The :c:member:`!tp_basicsize` includes size needed for data of the type's :c:" -"member:`~PyTypeObject.tp_base`, plus any extra data needed by each instance." -msgstr "" - -#: ../../c-api/typeobj.rst:633 -msgid "" -"The correct way to set :c:member:`!tp_basicsize` is to use the ``sizeof`` " -"operator on the struct used to declare the instance layout. This struct must " -"include the struct used to declare the base type. In other words, :c:member:" -"`!tp_basicsize` must be greater than or equal to the base's :c:member:`!" -"tp_basicsize`." -msgstr "" - -#: ../../c-api/typeobj.rst:639 -msgid "" -"Since every type is a subtype of :py:type:`object`, this struct must " -"include :c:type:`PyObject` or :c:type:`PyVarObject` (depending on whether :c:" -"member:`~PyVarObject.ob_size` should be included). These are usually defined " -"by the macro :c:macro:`PyObject_HEAD` or :c:macro:`PyObject_VAR_HEAD`, " -"respectively." -msgstr "" - -#: ../../c-api/typeobj.rst:645 -msgid "" -"The basic size does not include the GC header size, as that header is not " -"part of :c:macro:`PyObject_HEAD`." -msgstr "" - -#: ../../c-api/typeobj.rst:648 -msgid "" -"For cases where struct used to declare the base type is unknown, see :c:" -"member:`PyType_Spec.basicsize` and :c:func:`PyType_FromMetaclass`." -msgstr "" - -#: ../../c-api/typeobj.rst:651 -msgid "Notes about alignment:" -msgstr "" - -#: ../../c-api/typeobj.rst:653 -msgid "" -":c:member:`!tp_basicsize` must be a multiple of ``_Alignof(PyObject)``. When " -"using ``sizeof`` on a ``struct`` that includes :c:macro:`PyObject_HEAD`, as " -"recommended, the compiler ensures this. When not using a C ``struct``, or " -"when using compiler extensions like ``__attribute__((packed))``, it is up to " -"you." -msgstr "" - -#: ../../c-api/typeobj.rst:658 -msgid "" -"If the variable items require a particular alignment, :c:member:`!" -"tp_basicsize` and :c:member:`!tp_itemsize` must each be a multiple of that " -"alignment. For example, if a type's variable part stores a ``double``, it is " -"your responsibility that both fields are a multiple of ``_Alignof(double)``." -msgstr "" - -#: ../../c-api/typeobj.rst:667 -msgid "" -"These fields are inherited separately by subtypes. (That is, if the field is " -"set to zero, :c:func:`PyType_Ready` will copy the value from the base type, " -"indicating that the instances do not need additional storage.)" -msgstr "" - -#: ../../c-api/typeobj.rst:672 -msgid "" -"If the base type has a non-zero :c:member:`~PyTypeObject.tp_itemsize`, it is " -"generally not safe to set :c:member:`~PyTypeObject.tp_itemsize` to a " -"different non-zero value in a subtype (though this depends on the " -"implementation of the base type)." -msgstr "" - -#: ../../c-api/typeobj.rst:681 -msgid "" -"A pointer to the instance destructor function. The function signature is::" -msgstr "" - -#: ../../c-api/typeobj.rst:683 -msgid "void tp_dealloc(PyObject *self);" -msgstr "void tp_dealloc(PyObject *self);" - -#: ../../c-api/typeobj.rst:685 -msgid "" -"The destructor function should remove all references which the instance owns " -"(e.g., call :c:func:`Py_CLEAR`), free all memory buffers owned by the " -"instance, and call the type's :c:member:`~PyTypeObject.tp_free` function to " -"free the object itself." -msgstr "" - -#: ../../c-api/typeobj.rst:690 -msgid "" -"If you may call functions that may set the error indicator, you must use :c:" -"func:`PyErr_GetRaisedException` and :c:func:`PyErr_SetRaisedException` to " -"ensure you don't clobber a preexisting error indicator (the deallocation " -"could have occurred while processing a different error):" -msgstr "" - -#: ../../c-api/typeobj.rst:695 -msgid "" -"static void\n" -"foo_dealloc(foo_object *self)\n" -"{\n" -" PyObject *et, *ev, *etb;\n" -" PyObject *exc = PyErr_GetRaisedException();\n" -" ...\n" -" PyErr_SetRaisedException(exc);\n" -"}" -msgstr "" - -#: ../../c-api/typeobj.rst:706 -msgid "" -"The dealloc handler itself must not raise an exception; if it hits an error " -"case it should call :c:func:`PyErr_FormatUnraisable` to log (and clear) an " -"unraisable exception." -msgstr "" - -#: ../../c-api/typeobj.rst:710 -msgid "No guarantees are made about when an object is destroyed, except:" -msgstr "" - -#: ../../c-api/typeobj.rst:712 -msgid "" -"Python will destroy an object immediately or some time after the final " -"reference to the object is deleted, unless its finalizer (:c:member:" -"`~PyTypeObject.tp_finalize`) subsequently resurrects the object." -msgstr "" - -#: ../../c-api/typeobj.rst:716 -msgid "" -"An object will not be destroyed while it is being automatically finalized (:" -"c:member:`~PyTypeObject.tp_finalize`) or automatically cleared (:c:member:" -"`~PyTypeObject.tp_clear`)." -msgstr "" - -#: ../../c-api/typeobj.rst:720 -msgid "" -"CPython currently destroys an object immediately from :c:func:`Py_DECREF` " -"when the new reference count is zero, but this may change in a future " -"version." -msgstr "" - -#: ../../c-api/typeobj.rst:724 -msgid "" -"It is recommended to call :c:func:`PyObject_CallFinalizerFromDealloc` at the " -"beginning of :c:member:`!tp_dealloc` to guarantee that the object is always " -"finalized before destruction." -msgstr "" - -#: ../../c-api/typeobj.rst:728 -msgid "" -"If the type supports garbage collection (the :c:macro:`Py_TPFLAGS_HAVE_GC` " -"flag is set), the destructor should call :c:func:`PyObject_GC_UnTrack` " -"before clearing any member fields." -msgstr "" - -#: ../../c-api/typeobj.rst:732 -msgid "" -"It is permissible to call :c:member:`~PyTypeObject.tp_clear` from :c:member:" -"`!tp_dealloc` to reduce code duplication and to guarantee that the object is " -"always cleared before destruction. Beware that :c:member:`!tp_clear` might " -"have already been called." -msgstr "" - -#: ../../c-api/typeobj.rst:737 -msgid "" -"If the type is heap allocated (:c:macro:`Py_TPFLAGS_HEAPTYPE`), the " -"deallocator should release the owned reference to its type object (via :c:" -"func:`Py_DECREF`) after calling the type deallocator. See the example code " -"below.::" -msgstr "" - -#: ../../c-api/typeobj.rst:742 -msgid "" -"static void\n" -"foo_dealloc(PyObject *op)\n" -"{\n" -" foo_object *self = (foo_object *) op;\n" -" PyObject_GC_UnTrack(self);\n" -" Py_CLEAR(self->ref);\n" -" Py_TYPE(self)->tp_free(self);\n" -"}" -msgstr "" -"static void\n" -"foo_dealloc(PyObject *op)\n" -"{\n" -" foo_object *self = (foo_object *) op;\n" -" PyObject_GC_UnTrack(self);\n" -" Py_CLEAR(self->ref);\n" -" Py_TYPE(self)->tp_free(self);\n" -"}" - -#: ../../c-api/typeobj.rst:751 -msgid "" -":c:member:`!tp_dealloc` must leave the exception status unchanged. If it " -"needs to call something that might raise an exception, the exception state " -"must be backed up first and restored later (after logging any exceptions " -"with :c:func:`PyErr_WriteUnraisable`)." -msgstr "" - -#: ../../c-api/typeobj.rst:756 -msgid "Example::" -msgstr "範例： ::" - -#: ../../c-api/typeobj.rst:758 -msgid "" -"static void\n" -"foo_dealloc(PyObject *self)\n" -"{\n" -" PyObject *exc = PyErr_GetRaisedException();\n" -"\n" -" if (PyObject_CallFinalizerFromDealloc(self) < 0) {\n" -" // self was resurrected.\n" -" goto done;\n" -" }\n" -"\n" -" PyTypeObject *tp = Py_TYPE(self);\n" -"\n" -" if (tp->tp_flags & Py_TPFLAGS_HAVE_GC) {\n" -" PyObject_GC_UnTrack(self);\n" -" }\n" -"\n" -" // Optional, but convenient to avoid code duplication.\n" -" if (tp->tp_clear && tp->tp_clear(self) < 0) {\n" -" PyErr_WriteUnraisable(self);\n" -" }\n" -"\n" -" // Any additional destruction goes here.\n" -"\n" -" tp->tp_free(self);\n" -" self = NULL; // In case PyErr_WriteUnraisable() is called below.\n" -"\n" -" if (tp->tp_flags & Py_TPFLAGS_HEAPTYPE) {\n" -" Py_CLEAR(tp);\n" -" }\n" -"\n" -"done:\n" -" // Optional, if something was called that might have raised an\n" -" // exception.\n" -" if (PyErr_Occurred()) {\n" -" PyErr_WriteUnraisable(self);\n" -" }\n" -" PyErr_SetRaisedException(exc);\n" -"}" -msgstr "" - -#: ../../c-api/typeobj.rst:797 -msgid "" -":c:member:`!tp_dealloc` may be called from any Python thread, not just the " -"thread which created the object (if the object becomes part of a refcount " -"cycle, that cycle might be collected by a garbage collection on any " -"thread). This is not a problem for Python API calls, since the thread on " -"which :c:member:`!tp_dealloc` is called with an :term:`attached thread " -"state`. However, if the object being destroyed in turn destroys objects " -"from some other C library, care should be taken to ensure that destroying " -"those objects on the thread which called :c:member:`!tp_dealloc` will not " -"violate any assumptions of the library." -msgstr "" - -#: ../../c-api/typeobj.rst:815 ../../c-api/typeobj.rst:1742 -#: ../../c-api/typeobj.rst:2509 -msgid "" -":ref:`life-cycle` for details about how this slot relates to other slots." -msgstr "" - -#: ../../c-api/typeobj.rst:820 -msgid "" -"An optional offset to a per-instance function that implements calling the " -"object using the :ref:`vectorcall protocol `, a more efficient " -"alternative of the simpler :c:member:`~PyTypeObject.tp_call`." -msgstr "" - -#: ../../c-api/typeobj.rst:825 -msgid "" -"This field is only used if the flag :c:macro:`Py_TPFLAGS_HAVE_VECTORCALL` is " -"set. If so, this must be a positive integer containing the offset in the " -"instance of a :c:type:`vectorcallfunc` pointer." -msgstr "" - -#: ../../c-api/typeobj.rst:829 -msgid "" -"The *vectorcallfunc* pointer may be ``NULL``, in which case the instance " -"behaves as if :c:macro:`Py_TPFLAGS_HAVE_VECTORCALL` was not set: calling the " -"instance falls back to :c:member:`~PyTypeObject.tp_call`." -msgstr "" - -#: ../../c-api/typeobj.rst:833 -msgid "" -"Any class that sets ``Py_TPFLAGS_HAVE_VECTORCALL`` must also set :c:member:" -"`~PyTypeObject.tp_call` and make sure its behaviour is consistent with the " -"*vectorcallfunc* function. This can be done by setting *tp_call* to :c:func:" -"`PyVectorcall_Call`." -msgstr "" - -#: ../../c-api/typeobj.rst:840 -msgid "" -"Before version 3.8, this slot was named ``tp_print``. In Python 2.x, it was " -"used for printing to a file. In Python 3.0 to 3.7, it was unused." -msgstr "" - -#: ../../c-api/typeobj.rst:846 -msgid "" -"Before version 3.12, it was not recommended for :ref:`mutable heap types " -"` to implement the vectorcall protocol. When a user sets :attr:" -"`~object.__call__` in Python code, only *tp_call* is updated, likely making " -"it inconsistent with the vectorcall function. Since 3.12, setting " -"``__call__`` will disable vectorcall optimization by clearing the :c:macro:" -"`Py_TPFLAGS_HAVE_VECTORCALL` flag." -msgstr "" - -#: ../../c-api/typeobj.rst:856 -msgid "" -"This field is always inherited. However, the :c:macro:" -"`Py_TPFLAGS_HAVE_VECTORCALL` flag is not always inherited. If it's not set, " -"then the subclass won't use :ref:`vectorcall `, except when :c:" -"func:`PyVectorcall_Call` is explicitly called." -msgstr "" - -#: ../../c-api/typeobj.rst:867 -msgid "An optional pointer to the get-attribute-string function." -msgstr "" - -#: ../../c-api/typeobj.rst:869 -msgid "" -"This field is deprecated. When it is defined, it should point to a function " -"that acts the same as the :c:member:`~PyTypeObject.tp_getattro` function, " -"but taking a C string instead of a Python string object to give the " -"attribute name." -msgstr "" -"此欄位已被棄用。當它被定義時，它應該指向一個與 :c:member:`~PyTypeObject." -"tp_getattro` 行為相同但使用 C 字串而非 Python 字串物件來提供屬性名稱的函式。" - -#: ../../c-api/typeobj.rst:875 ../../c-api/typeobj.rst:1083 -msgid "" -"Group: :c:member:`~PyTypeObject.tp_getattr`, :c:member:`~PyTypeObject." -"tp_getattro`" -msgstr "" -"群組：:c:member:`~PyTypeObject.tp_getattr`、:c:member:`~PyTypeObject." -"tp_getattro`" - -#: ../../c-api/typeobj.rst:877 -msgid "" -"This field is inherited by subtypes together with :c:member:`~PyTypeObject." -"tp_getattro`: a subtype inherits both :c:member:`~PyTypeObject.tp_getattr` " -"and :c:member:`~PyTypeObject.tp_getattro` from its base type when the " -"subtype's :c:member:`~PyTypeObject.tp_getattr` and :c:member:`~PyTypeObject." -"tp_getattro` are both ``NULL``." -msgstr "" - -#: ../../c-api/typeobj.rst:886 ../../c-api/typeobj.rst:1098 -msgid "" -"An optional pointer to the function for setting and deleting attributes." -msgstr "" - -#: ../../c-api/typeobj.rst:888 -msgid "" -"This field is deprecated. When it is defined, it should point to a function " -"that acts the same as the :c:member:`~PyTypeObject.tp_setattro` function, " -"but taking a C string instead of a Python string object to give the " -"attribute name." -msgstr "" -"此欄位已被棄用。當它被定義時，它應該指向一個與 :c:member:`~PyTypeObject." -"tp_setattro` 行為相同但使用 C 字串而非 Python 字串物件來提供屬性名稱的函式。" - -#: ../../c-api/typeobj.rst:894 ../../c-api/typeobj.rst:1111 -msgid "" -"Group: :c:member:`~PyTypeObject.tp_setattr`, :c:member:`~PyTypeObject." -"tp_setattro`" -msgstr "" -"群組：:c:member:`~PyTypeObject.tp_setattr`、:c:member:`~PyTypeObject." -"tp_setattro`" - -#: ../../c-api/typeobj.rst:896 -msgid "" -"This field is inherited by subtypes together with :c:member:`~PyTypeObject." -"tp_setattro`: a subtype inherits both :c:member:`~PyTypeObject.tp_setattr` " -"and :c:member:`~PyTypeObject.tp_setattro` from its base type when the " -"subtype's :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject." -"tp_setattro` are both ``NULL``." -msgstr "" - -#: ../../c-api/typeobj.rst:903 -msgid "" -"Pointer to an additional structure that contains fields relevant only to " -"objects which implement :term:`awaitable` and :term:`asynchronous iterator` " -"protocols at the C-level. See :ref:`async-structs` for details." -msgstr "" - -#: ../../c-api/typeobj.rst:907 -msgid "Formerly known as ``tp_compare`` and ``tp_reserved``." -msgstr "以前稱為 ``tp_compare`` 和 ``tp_reserved``。" - -#: ../../c-api/typeobj.rst:912 -msgid "" -"The :c:member:`~PyTypeObject.tp_as_async` field is not inherited, but the " -"contained fields are inherited individually." -msgstr "" - -#: ../../c-api/typeobj.rst:922 -msgid "" -"An optional pointer to a function that implements the built-in function :" -"func:`repr`." -msgstr "" - -#: ../../c-api/typeobj.rst:925 -msgid "The signature is the same as for :c:func:`PyObject_Repr`::" -msgstr "函式簽名與 :c:func:`PyObject_Repr` 相同： ::" - -#: ../../c-api/typeobj.rst:927 -msgid "PyObject *tp_repr(PyObject *self);" -msgstr "PyObject *tp_repr(PyObject *self);" - -#: ../../c-api/typeobj.rst:929 -msgid "" -"The function must return a string or a Unicode object. Ideally, this " -"function should return a string that, when passed to :func:`eval`, given a " -"suitable environment, returns an object with the same value. If this is not " -"feasible, it should return a string starting with ``'<'`` and ending with " -"``'>'`` from which both the type and the value of the object can be deduced." -msgstr "" - -#: ../../c-api/typeobj.rst:940 ../../c-api/typeobj.rst:1021 -#: ../../c-api/typeobj.rst:1062 ../../c-api/typeobj.rst:1089 -#: ../../c-api/typeobj.rst:1117 ../../c-api/typeobj.rst:1159 -#: ../../c-api/typeobj.rst:1807 ../../c-api/typeobj.rst:1841 -#: ../../c-api/typeobj.rst:1970 ../../c-api/typeobj.rst:2003 -#: ../../c-api/typeobj.rst:2082 ../../c-api/typeobj.rst:2125 -#: ../../c-api/typeobj.rst:2147 ../../c-api/typeobj.rst:2188 -#: ../../c-api/typeobj.rst:2218 ../../c-api/typeobj.rst:2251 -msgid "**Default:**" -msgstr "**預設：**" - -#: ../../c-api/typeobj.rst:942 -msgid "" -"When this field is not set, a string of the form ``<%s object at %p>`` is " -"returned, where ``%s`` is replaced by the type name, and ``%p`` by the " -"object's memory address." -msgstr "" - -#: ../../c-api/typeobj.rst:949 -msgid "" -"Pointer to an additional structure that contains fields relevant only to " -"objects which implement the number protocol. These fields are documented " -"in :ref:`number-structs`." -msgstr "" - -#: ../../c-api/typeobj.rst:955 -msgid "" -"The :c:member:`~PyTypeObject.tp_as_number` field is not inherited, but the " -"contained fields are inherited individually." -msgstr "" - -#: ../../c-api/typeobj.rst:961 -msgid "" -"Pointer to an additional structure that contains fields relevant only to " -"objects which implement the sequence protocol. These fields are documented " -"in :ref:`sequence-structs`." -msgstr "" - -#: ../../c-api/typeobj.rst:967 -msgid "" -"The :c:member:`~PyTypeObject.tp_as_sequence` field is not inherited, but the " -"contained fields are inherited individually." -msgstr "" - -#: ../../c-api/typeobj.rst:973 -msgid "" -"Pointer to an additional structure that contains fields relevant only to " -"objects which implement the mapping protocol. These fields are documented " -"in :ref:`mapping-structs`." -msgstr "" - -#: ../../c-api/typeobj.rst:979 -msgid "" -"The :c:member:`~PyTypeObject.tp_as_mapping` field is not inherited, but the " -"contained fields are inherited individually." -msgstr "" - -#: ../../c-api/typeobj.rst:989 -msgid "" -"An optional pointer to a function that implements the built-in function :" -"func:`hash`." -msgstr "" - -#: ../../c-api/typeobj.rst:992 -msgid "The signature is the same as for :c:func:`PyObject_Hash`::" -msgstr "函式簽名與 :c:func:`PyObject_Hash` 相同： ::" - -#: ../../c-api/typeobj.rst:994 -msgid "Py_hash_t tp_hash(PyObject *);" -msgstr "Py_hash_t tp_hash(PyObject *);" - -#: ../../c-api/typeobj.rst:996 -msgid "" -"The value ``-1`` should not be returned as a normal return value; when an " -"error occurs during the computation of the hash value, the function should " -"set an exception and return ``-1``." -msgstr "" - -#: ../../c-api/typeobj.rst:1000 -msgid "" -"When this field is not set (*and* :c:member:`~PyTypeObject.tp_richcompare` " -"is not set), an attempt to take the hash of the object raises :exc:" -"`TypeError`. This is the same as setting it to :c:func:" -"`PyObject_HashNotImplemented`." -msgstr "" - -#: ../../c-api/typeobj.rst:1004 -msgid "" -"This field can be set explicitly to :c:func:`PyObject_HashNotImplemented` to " -"block inheritance of the hash method from a parent type. This is interpreted " -"as the equivalent of ``__hash__ = None`` at the Python level, causing " -"``isinstance(o, collections.Hashable)`` to correctly return ``False``. Note " -"that the converse is also true - setting ``__hash__ = None`` on a class at " -"the Python level will result in the ``tp_hash`` slot being set to :c:func:" -"`PyObject_HashNotImplemented`." -msgstr "" - -#: ../../c-api/typeobj.rst:1014 ../../c-api/typeobj.rst:1800 -msgid "" -"Group: :c:member:`~PyTypeObject.tp_hash`, :c:member:`~PyTypeObject." -"tp_richcompare`" -msgstr "" -"群組：:c:member:`~PyTypeObject.tp_hash`、:c:member:`~PyTypeObject." -"tp_richcompare`" - -#: ../../c-api/typeobj.rst:1016 -msgid "" -"This field is inherited by subtypes together with :c:member:`~PyTypeObject." -"tp_richcompare`: a subtype inherits both of :c:member:`~PyTypeObject." -"tp_richcompare` and :c:member:`~PyTypeObject.tp_hash`, when the subtype's :c:" -"member:`~PyTypeObject.tp_richcompare` and :c:member:`~PyTypeObject.tp_hash` " -"are both ``NULL``." -msgstr "" - -#: ../../c-api/typeobj.rst:1023 -msgid ":c:data:`PyBaseObject_Type` uses :c:func:`PyObject_GenericHash`." -msgstr ":c:data:`PyBaseObject_Type` 會使用 :c:func:`PyObject_GenericHash`。" - -#: ../../c-api/typeobj.rst:1030 -msgid "" -"An optional pointer to a function that implements calling the object. This " -"should be ``NULL`` if the object is not callable. The signature is the same " -"as for :c:func:`PyObject_Call`::" -msgstr "" - -#: ../../c-api/typeobj.rst:1034 -msgid "PyObject *tp_call(PyObject *self, PyObject *args, PyObject *kwargs);" -msgstr "PyObject *tp_call(PyObject *self, PyObject *args, PyObject *kwargs);" - -#: ../../c-api/typeobj.rst:1045 -msgid "" -"An optional pointer to a function that implements the built-in operation :" -"func:`str`. (Note that :class:`str` is a type now, and :func:`str` calls " -"the constructor for that type. This constructor calls :c:func:" -"`PyObject_Str` to do the actual work, and :c:func:`PyObject_Str` will call " -"this handler.)" -msgstr "" - -#: ../../c-api/typeobj.rst:1050 -msgid "The signature is the same as for :c:func:`PyObject_Str`::" -msgstr "函式簽名與 :c:func:`PyObject_Str` 相同： ::" - -#: ../../c-api/typeobj.rst:1052 -msgid "PyObject *tp_str(PyObject *self);" -msgstr "PyObject *tp_str(PyObject *self);" - -#: ../../c-api/typeobj.rst:1054 -msgid "" -"The function must return a string or a Unicode object. It should be a " -"\"friendly\" string representation of the object, as this is the " -"representation that will be used, among other things, by the :func:`print` " -"function." -msgstr "" - -#: ../../c-api/typeobj.rst:1064 -msgid "" -"When this field is not set, :c:func:`PyObject_Repr` is called to return a " -"string representation." -msgstr "" - -#: ../../c-api/typeobj.rst:1072 -msgid "An optional pointer to the get-attribute function." -msgstr "" - -#: ../../c-api/typeobj.rst:1074 -msgid "The signature is the same as for :c:func:`PyObject_GetAttr`::" -msgstr "函式簽名與 :c:func:`PyObject_GetAttr` 相同： ::" - -#: ../../c-api/typeobj.rst:1076 -msgid "PyObject *tp_getattro(PyObject *self, PyObject *attr);" -msgstr "PyObject *tp_getattro(PyObject *self, PyObject *attr);" - -#: ../../c-api/typeobj.rst:1078 -msgid "" -"It is usually convenient to set this field to :c:func:" -"`PyObject_GenericGetAttr`, which implements the normal way of looking for " -"object attributes." -msgstr "" - -#: ../../c-api/typeobj.rst:1085 -msgid "" -"This field is inherited by subtypes together with :c:member:`~PyTypeObject." -"tp_getattr`: a subtype inherits both :c:member:`~PyTypeObject.tp_getattr` " -"and :c:member:`~PyTypeObject.tp_getattro` from its base type when the " -"subtype's :c:member:`~PyTypeObject.tp_getattr` and :c:member:`~PyTypeObject." -"tp_getattro` are both ``NULL``." -msgstr "" - -#: ../../c-api/typeobj.rst:1091 -msgid ":c:data:`PyBaseObject_Type` uses :c:func:`PyObject_GenericGetAttr`." -msgstr ":c:data:`PyBaseObject_Type` 會使用 :c:func:`PyObject_GenericGetAttr`。" - -#: ../../c-api/typeobj.rst:1100 -msgid "The signature is the same as for :c:func:`PyObject_SetAttr`::" -msgstr "函式簽名與 :c:func:`PyObject_SetAttr` 相同： ::" - -#: ../../c-api/typeobj.rst:1102 -msgid "int tp_setattro(PyObject *self, PyObject *attr, PyObject *value);" -msgstr "int tp_setattro(PyObject *self, PyObject *attr, PyObject *value);" - -#: ../../c-api/typeobj.rst:1104 -msgid "" -"In addition, setting *value* to ``NULL`` to delete an attribute must be " -"supported. It is usually convenient to set this field to :c:func:" -"`PyObject_GenericSetAttr`, which implements the normal way of setting object " -"attributes." -msgstr "" - -#: ../../c-api/typeobj.rst:1113 -msgid "" -"This field is inherited by subtypes together with :c:member:`~PyTypeObject." -"tp_setattr`: a subtype inherits both :c:member:`~PyTypeObject.tp_setattr` " -"and :c:member:`~PyTypeObject.tp_setattro` from its base type when the " -"subtype's :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject." -"tp_setattro` are both ``NULL``." -msgstr "" - -#: ../../c-api/typeobj.rst:1119 -msgid ":c:data:`PyBaseObject_Type` uses :c:func:`PyObject_GenericSetAttr`." -msgstr "" - -#: ../../c-api/typeobj.rst:1124 -msgid "" -"Pointer to an additional structure that contains fields relevant only to " -"objects which implement the buffer interface. These fields are documented " -"in :ref:`buffer-structs`." -msgstr "" - -#: ../../c-api/typeobj.rst:1130 -msgid "" -"The :c:member:`~PyTypeObject.tp_as_buffer` field is not inherited, but the " -"contained fields are inherited individually." -msgstr "" - -#: ../../c-api/typeobj.rst:1136 -msgid "" -"This field is a bit mask of various flags. Some flags indicate variant " -"semantics for certain situations; others are used to indicate that certain " -"fields in the type object (or in the extension structures referenced via :c:" -"member:`~PyTypeObject.tp_as_number`, :c:member:`~PyTypeObject." -"tp_as_sequence`, :c:member:`~PyTypeObject.tp_as_mapping`, and :c:member:" -"`~PyTypeObject.tp_as_buffer`) that were historically not always present are " -"valid; if such a flag bit is clear, the type fields it guards must not be " -"accessed and must be considered to have a zero or ``NULL`` value instead." -msgstr "" - -#: ../../c-api/typeobj.rst:1146 -msgid "" -"Inheritance of this field is complicated. Most flag bits are inherited " -"individually, i.e. if the base type has a flag bit set, the subtype inherits " -"this flag bit. The flag bits that pertain to extension structures are " -"strictly inherited if the extension structure is inherited, i.e. the base " -"type's value of the flag bit is copied into the subtype together with a " -"pointer to the extension structure. The :c:macro:`Py_TPFLAGS_HAVE_GC` flag " -"bit is inherited together with the :c:member:`~PyTypeObject.tp_traverse` " -"and :c:member:`~PyTypeObject.tp_clear` fields, i.e. if the :c:macro:" -"`Py_TPFLAGS_HAVE_GC` flag bit is clear in the subtype and the :c:member:" -"`~PyTypeObject.tp_traverse` and :c:member:`~PyTypeObject.tp_clear` fields in " -"the subtype exist and have ``NULL`` values." -msgstr "" - -#: ../../c-api/typeobj.rst:1161 -msgid "" -":c:data:`PyBaseObject_Type` uses ``Py_TPFLAGS_DEFAULT | " -"Py_TPFLAGS_BASETYPE``." -msgstr "" -":c:data:`PyBaseObject_Type` 使用 ``Py_TPFLAGS_DEFAULT | " -"Py_TPFLAGS_BASETYPE``。" - -#: ../../c-api/typeobj.rst:1164 -msgid "**Bit Masks:**" -msgstr "" - -#: ../../c-api/typeobj.rst:1168 -msgid "" -"The following bit masks are currently defined; these can be ORed together " -"using the ``|`` operator to form the value of the :c:member:`~PyTypeObject." -"tp_flags` field. The macro :c:func:`PyType_HasFeature` takes a type and a " -"flags value, *tp* and *f*, and checks whether ``tp->tp_flags & f`` is non-" -"zero." -msgstr "" - -#: ../../c-api/typeobj.rst:1175 -msgid "" -"This bit is set when the type object itself is allocated on the heap, for " -"example, types created dynamically using :c:func:`PyType_FromSpec`. In this " -"case, the :c:member:`~PyObject.ob_type` field of its instances is considered " -"a reference to the type, and the type object is INCREF'ed when a new " -"instance is created, and DECREF'ed when an instance is destroyed (this does " -"not apply to instances of subtypes; only the type referenced by the " -"instance's ob_type gets INCREF'ed or DECREF'ed). Heap types should also :ref:" -"`support garbage collection ` as they can form a " -"reference cycle with their own module object." -msgstr "" - -#: ../../c-api/typeobj.rst:1186 ../../c-api/typeobj.rst:1197 -#: ../../c-api/typeobj.rst:1207 ../../c-api/typeobj.rst:1217 -#: ../../c-api/typeobj.rst:1249 -msgid "???" -msgstr "???" - -#: ../../c-api/typeobj.rst:1191 -msgid "" -"This bit is set when the type can be used as the base type of another type. " -"If this bit is clear, the type cannot be subtyped (similar to a \"final\" " -"class in Java)." -msgstr "" - -#: ../../c-api/typeobj.rst:1202 -msgid "" -"This bit is set when the type object has been fully initialized by :c:func:" -"`PyType_Ready`." -msgstr "" - -#: ../../c-api/typeobj.rst:1212 -msgid "" -"This bit is set while :c:func:`PyType_Ready` is in the process of " -"initializing the type object." -msgstr "" - -#: ../../c-api/typeobj.rst:1222 -msgid "" -"This bit is set when the object supports garbage collection. If this bit is " -"set, memory for new instances (see :c:member:`~PyTypeObject.tp_alloc`) must " -"be allocated using :c:macro:`PyObject_GC_New` or :c:func:" -"`PyType_GenericAlloc` and deallocated (see :c:member:`~PyTypeObject." -"tp_free`) using :c:func:`PyObject_GC_Del`. More information in section :ref:" -"`supporting-cycle-detection`." -msgstr "" - -#: ../../c-api/typeobj.rst:1231 ../../c-api/typeobj.rst:1587 -#: ../../c-api/typeobj.rst:1733 -msgid "" -"Group: :c:macro:`Py_TPFLAGS_HAVE_GC`, :c:member:`~PyTypeObject." -"tp_traverse`, :c:member:`~PyTypeObject.tp_clear`" -msgstr "" - -#: ../../c-api/typeobj.rst:1233 -msgid "" -"The :c:macro:`Py_TPFLAGS_HAVE_GC` flag bit is inherited together with the :c:" -"member:`~PyTypeObject.tp_traverse` and :c:member:`~PyTypeObject.tp_clear` " -"fields, i.e. if the :c:macro:`Py_TPFLAGS_HAVE_GC` flag bit is clear in the " -"subtype and the :c:member:`~PyTypeObject.tp_traverse` and :c:member:" -"`~PyTypeObject.tp_clear` fields in the subtype exist and have ``NULL`` " -"values." -msgstr "" - -#: ../../c-api/typeobj.rst:1243 -msgid "" -"This is a bitmask of all the bits that pertain to the existence of certain " -"fields in the type object and its extension structures. Currently, it " -"includes the following bits: :c:macro:`Py_TPFLAGS_HAVE_STACKLESS_EXTENSION`." -msgstr "" - -#: ../../c-api/typeobj.rst:1254 -msgid "This bit indicates that objects behave like unbound methods." -msgstr "" - -#: ../../c-api/typeobj.rst:1256 -msgid "If this flag is set for ``type(meth)``, then:" -msgstr "如果此旗標為 ``type(meth)`` 所設定，則：" - -#: ../../c-api/typeobj.rst:1258 -msgid "" -"``meth.__get__(obj, cls)(*args, **kwds)`` (with ``obj`` not None) must be " -"equivalent to ``meth(obj, *args, **kwds)``." -msgstr "" -"``meth.__get__(obj, cls)(*args, **kwds)``\\（其中 ``obj`` 並非 None）必須等價" -"於 ``meth(obj, *args, **kwds)``。" - -#: ../../c-api/typeobj.rst:1261 -msgid "" -"``meth.__get__(None, cls)(*args, **kwds)`` must be equivalent to " -"``meth(*args, **kwds)``." -msgstr "" -"``meth.__get__(None, cls)(*args, **kwds)`` 必須等價於 ``meth(*args, " -"**kwds)``。" - -#: ../../c-api/typeobj.rst:1264 -msgid "" -"This flag enables an optimization for typical method calls like ``obj." -"meth()``: it avoids creating a temporary \"bound method\" object for ``obj." -"meth``." -msgstr "" - -#: ../../c-api/typeobj.rst:1272 -msgid "" -"This flag is never inherited by types without the :c:macro:" -"`Py_TPFLAGS_IMMUTABLETYPE` flag set. For extension types, it is inherited " -"whenever :c:member:`~PyTypeObject.tp_descr_get` is inherited." -msgstr "" - -#: ../../c-api/typeobj.rst:1278 -msgid "" -"This bit indicates that instances of the class have a :attr:`~object." -"__dict__` attribute, and that the space for the dictionary is managed by the " -"VM." -msgstr "" - -#: ../../c-api/typeobj.rst:1281 -msgid "If this flag is set, :c:macro:`Py_TPFLAGS_HAVE_GC` should also be set." -msgstr "如果有設定此旗標，則也應該設定 :c:macro:`Py_TPFLAGS_HAVE_GC`。" - -#: ../../c-api/typeobj.rst:1283 -msgid "" -"The type traverse function must call :c:func:`PyObject_VisitManagedDict` and " -"its clear function must call :c:func:`PyObject_ClearManagedDict`." -msgstr "" - -#: ../../c-api/typeobj.rst:1290 -msgid "" -"This flag is inherited unless the :c:member:`~PyTypeObject.tp_dictoffset` " -"field is set in a superclass." -msgstr "" - -#: ../../c-api/typeobj.rst:1296 -msgid "" -"This bit indicates that instances of the class should be weakly " -"referenceable." -msgstr "" - -#: ../../c-api/typeobj.rst:1303 -msgid "" -"This flag is inherited unless the :c:member:`~PyTypeObject." -"tp_weaklistoffset` field is set in a superclass." -msgstr "" - -#: ../../c-api/typeobj.rst:1309 -msgid "" -"Only usable with variable-size types, i.e. ones with non-zero :c:member:" -"`~PyTypeObject.tp_itemsize`." -msgstr "" - -#: ../../c-api/typeobj.rst:1312 -msgid "" -"Indicates that the variable-sized portion of an instance of this type is at " -"the end of the instance's memory area, at an offset of ``Py_TYPE(obj)-" -">tp_basicsize`` (which may be different in each subclass)." -msgstr "" - -#: ../../c-api/typeobj.rst:1317 -msgid "" -"When setting this flag, be sure that all superclasses either use this memory " -"layout, or are not variable-sized. Python does not check this." -msgstr "" - -#: ../../c-api/typeobj.rst:1325 -msgid "This flag is inherited." -msgstr "" - -#: ../../c-api/typeobj.rst:1339 -msgid "" -"Functions such as :c:func:`PyLong_Check` will call :c:func:" -"`PyType_FastSubclass` with one of these flags to quickly determine if a type " -"is a subclass of a built-in type; such specific checks are faster than a " -"generic check, like :c:func:`PyObject_IsInstance`. Custom types that inherit " -"from built-ins should have their :c:member:`~PyTypeObject.tp_flags` set " -"appropriately, or the code that interacts with such types will behave " -"differently depending on what kind of check is used." -msgstr "" - -#: ../../c-api/typeobj.rst:1350 -msgid "" -"This bit is set when the :c:member:`~PyTypeObject.tp_finalize` slot is " -"present in the type structure." -msgstr "" - -#: ../../c-api/typeobj.rst:1355 -msgid "" -"This flag isn't necessary anymore, as the interpreter assumes the :c:member:" -"`~PyTypeObject.tp_finalize` slot is always present in the type structure." -msgstr "" - -#: ../../c-api/typeobj.rst:1363 -msgid "" -"This bit is set when the class implements the :ref:`vectorcall protocol " -"`. See :c:member:`~PyTypeObject.tp_vectorcall_offset` for " -"details." -msgstr "" - -#: ../../c-api/typeobj.rst:1369 -msgid "" -"This bit is inherited if :c:member:`~PyTypeObject.tp_call` is also inherited." -msgstr "" - -#: ../../c-api/typeobj.rst:1376 -msgid "" -"This flag is now removed from a class when the class's :py:meth:`~object." -"__call__` method is reassigned." -msgstr "" - -#: ../../c-api/typeobj.rst:1379 -msgid "This flag can now be inherited by mutable classes." -msgstr "" - -#: ../../c-api/typeobj.rst:1383 -msgid "" -"This bit is set for type objects that are immutable: type attributes cannot " -"be set nor deleted." -msgstr "" - -#: ../../c-api/typeobj.rst:1385 -msgid "" -":c:func:`PyType_Ready` automatically applies this flag to :ref:`static types " -"`." -msgstr "" - -#: ../../c-api/typeobj.rst:1390 -msgid "This flag is not inherited." -msgstr "" - -#: ../../c-api/typeobj.rst:1396 -msgid "" -"Disallow creating instances of the type: set :c:member:`~PyTypeObject." -"tp_new` to NULL and don't create the ``__new__`` key in the type dictionary." -msgstr "" - -#: ../../c-api/typeobj.rst:1400 -msgid "" -"The flag must be set before creating the type, not after. For example, it " -"must be set before :c:func:`PyType_Ready` is called on the type." -msgstr "" - -#: ../../c-api/typeobj.rst:1403 -msgid "" -"The flag is set automatically on :ref:`static types ` if :c:" -"member:`~PyTypeObject.tp_base` is NULL or ``&PyBaseObject_Type`` and :c:" -"member:`~PyTypeObject.tp_new` is NULL." -msgstr "" - -#: ../../c-api/typeobj.rst:1409 -msgid "" -"This flag is not inherited. However, subclasses will not be instantiable " -"unless they provide a non-NULL :c:member:`~PyTypeObject.tp_new` (which is " -"only possible via the C API)." -msgstr "" - -#: ../../c-api/typeobj.rst:1416 -msgid "" -"To disallow instantiating a class directly but allow instantiating its " -"subclasses (e.g. for an :term:`abstract base class`), do not use this flag. " -"Instead, make :c:member:`~PyTypeObject.tp_new` only succeed for subclasses." -msgstr "" - -#: ../../c-api/typeobj.rst:1427 -msgid "" -"This bit indicates that instances of the class may match mapping patterns " -"when used as the subject of a :keyword:`match` block. It is automatically " -"set when registering or subclassing :class:`collections.abc.Mapping`, and " -"unset when registering :class:`collections.abc.Sequence`." -msgstr "" - -#: ../../c-api/typeobj.rst:1434 ../../c-api/typeobj.rst:1456 -msgid "" -":c:macro:`Py_TPFLAGS_MAPPING` and :c:macro:`Py_TPFLAGS_SEQUENCE` are " -"mutually exclusive; it is an error to enable both flags simultaneously." -msgstr "" - -#: ../../c-api/typeobj.rst:1439 -msgid "" -"This flag is inherited by types that do not already set :c:macro:" -"`Py_TPFLAGS_SEQUENCE`." -msgstr "" - -#: ../../c-api/typeobj.rst:1442 ../../c-api/typeobj.rst:1464 -msgid ":pep:`634` -- Structural Pattern Matching: Specification" -msgstr "" - -#: ../../c-api/typeobj.rst:1449 -msgid "" -"This bit indicates that instances of the class may match sequence patterns " -"when used as the subject of a :keyword:`match` block. It is automatically " -"set when registering or subclassing :class:`collections.abc.Sequence`, and " -"unset when registering :class:`collections.abc.Mapping`." -msgstr "" - -#: ../../c-api/typeobj.rst:1461 -msgid "" -"This flag is inherited by types that do not already set :c:macro:" -"`Py_TPFLAGS_MAPPING`." -msgstr "" - -#: ../../c-api/typeobj.rst:1471 -msgid "" -"Internal. Do not set or unset this flag. To indicate that a class has " -"changed call :c:func:`PyType_Modified`" -msgstr "" - -#: ../../c-api/typeobj.rst:1475 -msgid "" -"This flag is present in header files, but is not be used. It will be removed " -"in a future version of CPython" -msgstr "" - -#: ../../c-api/typeobj.rst:1483 -msgid "" -"An optional pointer to a NUL-terminated C string giving the docstring for " -"this type object. This is exposed as the :attr:`~type.__doc__` attribute on " -"the type and instances of the type." -msgstr "" - -#: ../../c-api/typeobj.rst:1489 -msgid "This field is *not* inherited by subtypes." -msgstr "此欄位不會被子型別繼承。" - -#: ../../c-api/typeobj.rst:1496 -msgid "" -"An optional pointer to a traversal function for the garbage collector. This " -"is only used if the :c:macro:`Py_TPFLAGS_HAVE_GC` flag bit is set. The " -"signature is::" -msgstr "" - -#: ../../c-api/typeobj.rst:1499 -msgid "int tp_traverse(PyObject *self, visitproc visit, void *arg);" -msgstr "int tp_traverse(PyObject *self, visitproc visit, void *arg);" - -#: ../../c-api/typeobj.rst:1501 ../../c-api/typeobj.rst:1728 -msgid "" -"More information about Python's garbage collection scheme can be found in " -"section :ref:`supporting-cycle-detection`." -msgstr "" - -#: ../../c-api/typeobj.rst:1504 -msgid "" -"The :c:member:`~PyTypeObject.tp_traverse` pointer is used by the garbage " -"collector to detect reference cycles. A typical implementation of a :c:" -"member:`~PyTypeObject.tp_traverse` function simply calls :c:func:`Py_VISIT` " -"on each of the instance's members that are Python objects that the instance " -"owns. For example, this is function :c:func:`!local_traverse` from the :mod:" -"`!_thread` extension module::" -msgstr "" - -#: ../../c-api/typeobj.rst:1510 -msgid "" -"static int\n" -"local_traverse(PyObject *op, visitproc visit, void *arg)\n" -"{\n" -" localobject *self = (localobject *) op;\n" -" Py_VISIT(self->args);\n" -" Py_VISIT(self->kw);\n" -" Py_VISIT(self->dict);\n" -" return 0;\n" -"}" -msgstr "" -"static int\n" -"local_traverse(PyObject *op, visitproc visit, void *arg)\n" -"{\n" -" localobject *self = (localobject *) op;\n" -" Py_VISIT(self->args);\n" -" Py_VISIT(self->kw);\n" -" Py_VISIT(self->dict);\n" -" return 0;\n" -"}" - -#: ../../c-api/typeobj.rst:1520 -msgid "" -"Note that :c:func:`Py_VISIT` is called only on those members that can " -"participate in reference cycles. Although there is also a ``self->key`` " -"member, it can only be ``NULL`` or a Python string and therefore cannot be " -"part of a reference cycle." -msgstr "" - -#: ../../c-api/typeobj.rst:1524 -msgid "" -"On the other hand, even if you know a member can never be part of a cycle, " -"as a debugging aid you may want to visit it anyway just so the :mod:`gc` " -"module's :func:`~gc.get_referents` function will include it." -msgstr "" - -#: ../../c-api/typeobj.rst:1528 -msgid "" -"Heap types (:c:macro:`Py_TPFLAGS_HEAPTYPE`) must visit their type with::" -msgstr "" - -#: ../../c-api/typeobj.rst:1530 -msgid "Py_VISIT(Py_TYPE(self));" -msgstr "Py_VISIT(Py_TYPE(self));" - -#: ../../c-api/typeobj.rst:1532 -msgid "" -"It is only needed since Python 3.9. To support Python 3.8 and older, this " -"line must be conditional::" -msgstr "" - -#: ../../c-api/typeobj.rst:1535 -msgid "" -"#if PY_VERSION_HEX >= 0x03090000\n" -" Py_VISIT(Py_TYPE(self));\n" -"#endif" -msgstr "" -"#if PY_VERSION_HEX >= 0x03090000\n" -" Py_VISIT(Py_TYPE(self));\n" -"#endif" - -#: ../../c-api/typeobj.rst:1539 -msgid "" -"If the :c:macro:`Py_TPFLAGS_MANAGED_DICT` bit is set in the :c:member:" -"`~PyTypeObject.tp_flags` field, the traverse function must call :c:func:" -"`PyObject_VisitManagedDict` like this::" -msgstr "" - -#: ../../c-api/typeobj.rst:1543 -msgid "PyObject_VisitManagedDict((PyObject*)self, visit, arg);" -msgstr "PyObject_VisitManagedDict((PyObject*)self, visit, arg);" - -#: ../../c-api/typeobj.rst:1546 -msgid "" -"When implementing :c:member:`~PyTypeObject.tp_traverse`, only the members " -"that the instance *owns* (by having :term:`strong references ` to them) must be visited. For instance, if an object supports " -"weak references via the :c:member:`~PyTypeObject.tp_weaklist` slot, the " -"pointer supporting the linked list (what *tp_weaklist* points to) must " -"**not** be visited as the instance does not directly own the weak references " -"to itself (the weakreference list is there to support the weak reference " -"machinery, but the instance has no strong reference to the elements inside " -"it, as they are allowed to be removed even if the instance is still alive)." -msgstr "" - -#: ../../c-api/typeobj.rst:1558 -msgid "" -"The traversal function must not have any side effects. It must not modify " -"the reference counts of any Python objects nor create or destroy any Python " -"objects." -msgstr "" - -#: ../../c-api/typeobj.rst:1562 -msgid "" -"Note that :c:func:`Py_VISIT` requires the *visit* and *arg* parameters to :c:" -"func:`!local_traverse` to have these specific names; don't name them just " -"anything." -msgstr "" - -#: ../../c-api/typeobj.rst:1566 -msgid "" -"Instances of :ref:`heap-allocated types ` hold a reference to " -"their type. Their traversal function must therefore either visit :c:func:" -"`Py_TYPE(self) `, or delegate this responsibility by calling " -"``tp_traverse`` of another heap-allocated type (such as a heap-allocated " -"superclass). If they do not, the type object may not be garbage-collected." -msgstr "" - -#: ../../c-api/typeobj.rst:1575 -msgid "" -"The :c:member:`~PyTypeObject.tp_traverse` function can be called from any " -"thread." -msgstr ":c:member:`~PyTypeObject.tp_traverse` 函式可以從任何執行緒呼叫。" - -#: ../../c-api/typeobj.rst:1580 -msgid "" -"Heap-allocated types are expected to visit ``Py_TYPE(self)`` in " -"``tp_traverse``. In earlier versions of Python, due to `bug 40217 `_, doing this may lead to crashes in subclasses." -msgstr "" - -#: ../../c-api/typeobj.rst:1589 -msgid "" -"This field is inherited by subtypes together with :c:member:`~PyTypeObject." -"tp_clear` and the :c:macro:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :c:" -"member:`~PyTypeObject.tp_traverse`, and :c:member:`~PyTypeObject.tp_clear` " -"are all inherited from the base type if they are all zero in the subtype." -msgstr "" - -#: ../../c-api/typeobj.rst:1599 -msgid "An optional pointer to a clear function. The signature is::" -msgstr "" - -#: ../../c-api/typeobj.rst:1601 -msgid "int tp_clear(PyObject *);" -msgstr "int tp_clear(PyObject *);" - -#: ../../c-api/typeobj.rst:1603 -msgid "" -"The purpose of this function is to break reference cycles that are causing " -"a :term:`cyclic isolate` so that the objects can be safely destroyed. A " -"cleared object is a partially destroyed object; the object is not obligated " -"to satisfy design invariants held during normal use." -msgstr "" - -#: ../../c-api/typeobj.rst:1608 -msgid "" -":c:member:`!tp_clear` does not need to delete references to objects that " -"can't participate in reference cycles, such as Python strings or Python " -"integers. However, it may be convenient to clear all references, and write " -"the type's :c:member:`~PyTypeObject.tp_dealloc` function to invoke :c:member:" -"`!tp_clear` to avoid code duplication. (Beware that :c:member:`!tp_clear` " -"might have already been called. Prefer calling idempotent functions like :c:" -"func:`Py_CLEAR`.)" -msgstr "" - -#: ../../c-api/typeobj.rst:1616 -msgid "" -"Any non-trivial cleanup should be performed in :c:member:`~PyTypeObject." -"tp_finalize` instead of :c:member:`!tp_clear`." -msgstr "" - -#: ../../c-api/typeobj.rst:1621 -msgid "" -"If :c:member:`!tp_clear` fails to break a reference cycle then the objects " -"in the :term:`cyclic isolate` may remain indefinitely uncollectable " -"(\"leak\"). See :data:`gc.garbage`." -msgstr "" - -#: ../../c-api/typeobj.rst:1627 -msgid "" -"Referents (direct and indirect) might have already been cleared; they are " -"not guaranteed to be in a consistent state." -msgstr "" - -#: ../../c-api/typeobj.rst:1632 -msgid "" -"The :c:member:`~PyTypeObject.tp_clear` function can be called from any " -"thread." -msgstr ":c:member:`~PyTypeObject.tp_clear` 函式可以從任何執行緒呼叫。" - -#: ../../c-api/typeobj.rst:1637 -msgid "" -"An object is not guaranteed to be automatically cleared before its " -"destructor (:c:member:`~PyTypeObject.tp_dealloc`) is called." -msgstr "" - -#: ../../c-api/typeobj.rst:1640 -msgid "" -"This function differs from the destructor (:c:member:`~PyTypeObject." -"tp_dealloc`) in the following ways:" -msgstr "" - -#: ../../c-api/typeobj.rst:1643 -msgid "" -"The purpose of clearing an object is to remove references to other objects " -"that might participate in a reference cycle. The purpose of the destructor, " -"on the other hand, is a superset: it must release *all* resources it owns, " -"including references to objects that cannot participate in a reference cycle " -"(e.g., integers) as well as the object's own memory (by calling :c:member:" -"`~PyTypeObject.tp_free`)." -msgstr "" - -#: ../../c-api/typeobj.rst:1649 -msgid "" -"When :c:member:`!tp_clear` is called, other objects might still hold " -"references to the object being cleared. Because of this, :c:member:`!" -"tp_clear` must not deallocate the object's own memory (:c:member:" -"`~PyTypeObject.tp_free`). The destructor, on the other hand, is only called " -"when no (strong) references exist, and as such, must safely destroy the " -"object itself by deallocating it." -msgstr "" - -#: ../../c-api/typeobj.rst:1655 -msgid "" -":c:member:`!tp_clear` might never be automatically called. An object's " -"destructor, on the other hand, will be automatically called some time after " -"the object becomes unreachable (i.e., either there are no references to the " -"object or the object is a member of a :term:`cyclic isolate`)." -msgstr "" - -#: ../../c-api/typeobj.rst:1660 -msgid "" -"No guarantees are made about when, if, or how often Python automatically " -"clears an object, except:" -msgstr "" - -#: ../../c-api/typeobj.rst:1663 -msgid "" -"Python will not automatically clear an object if it is reachable, i.e., " -"there is a reference to it and it is not a member of a :term:`cyclic " -"isolate`." -msgstr "" - -#: ../../c-api/typeobj.rst:1666 -msgid "" -"Python will not automatically clear an object if it has not been " -"automatically finalized (see :c:member:`~PyTypeObject.tp_finalize`). (If " -"the finalizer resurrected the object, the object may or may not be " -"automatically finalized again before it is cleared.)" -msgstr "" - -#: ../../c-api/typeobj.rst:1670 -msgid "" -"If an object is a member of a :term:`cyclic isolate`, Python will not " -"automatically clear it if any member of the cyclic isolate has not yet been " -"automatically finalized (:c:member:`~PyTypeObject.tp_finalize`)." -msgstr "" - -#: ../../c-api/typeobj.rst:1673 -msgid "" -"Python will not destroy an object until after any automatic calls to its :c:" -"member:`!tp_clear` function have returned. This ensures that the act of " -"breaking a reference cycle does not invalidate the ``self`` pointer while :c:" -"member:`!tp_clear` is still executing." -msgstr "" - -#: ../../c-api/typeobj.rst:1677 -msgid "" -"Python will not automatically call :c:member:`!tp_clear` multiple times " -"concurrently." -msgstr "" - -#: ../../c-api/typeobj.rst:1680 -msgid "" -"CPython currently only automatically clears objects as needed to break " -"reference cycles in a :term:`cyclic isolate`, but future versions might " -"clear objects regularly before their destruction." -msgstr "" - -#: ../../c-api/typeobj.rst:1684 -msgid "" -"Taken together, all :c:member:`~PyTypeObject.tp_clear` functions in the " -"system must combine to break all reference cycles. This is subtle, and if " -"in any doubt supply a :c:member:`~PyTypeObject.tp_clear` function. For " -"example, the tuple type does not implement a :c:member:`~PyTypeObject." -"tp_clear` function, because it's possible to prove that no reference cycle " -"can be composed entirely of tuples. Therefore the :c:member:`~PyTypeObject." -"tp_clear` functions of other types are responsible for breaking any cycle " -"containing a tuple. This isn't immediately obvious, and there's rarely a " -"good reason to avoid implementing :c:member:`~PyTypeObject.tp_clear`." -msgstr "" - -#: ../../c-api/typeobj.rst:1695 -msgid "" -"Implementations of :c:member:`~PyTypeObject.tp_clear` should drop the " -"instance's references to those of its members that may be Python objects, " -"and set its pointers to those members to ``NULL``, as in the following " -"example::" -msgstr "" - -#: ../../c-api/typeobj.rst:1699 -msgid "" -"static int\n" -"local_clear(PyObject *op)\n" -"{\n" -" localobject *self = (localobject *) op;\n" -" Py_CLEAR(self->key);\n" -" Py_CLEAR(self->args);\n" -" Py_CLEAR(self->kw);\n" -" Py_CLEAR(self->dict);\n" -" return 0;\n" -"}" -msgstr "" -"static int\n" -"local_clear(PyObject *op)\n" -"{\n" -" localobject *self = (localobject *) op;\n" -" Py_CLEAR(self->key);\n" -" Py_CLEAR(self->args);\n" -" Py_CLEAR(self->kw);\n" -" Py_CLEAR(self->dict);\n" -" return 0;\n" -"}" - -#: ../../c-api/typeobj.rst:1710 -msgid "" -"The :c:func:`Py_CLEAR` macro should be used, because clearing references is " -"delicate: the reference to the contained object must not be released (via :" -"c:func:`Py_DECREF`) until after the pointer to the contained object is set " -"to ``NULL``. This is because releasing the reference may cause the " -"contained object to become trash, triggering a chain of reclamation activity " -"that may include invoking arbitrary Python code (due to finalizers, or " -"weakref callbacks, associated with the contained object). If it's possible " -"for such code to reference *self* again, it's important that the pointer to " -"the contained object be ``NULL`` at that time, so that *self* knows the " -"contained object can no longer be used. The :c:func:`Py_CLEAR` macro " -"performs the operations in a safe order." -msgstr "" - -#: ../../c-api/typeobj.rst:1722 -msgid "" -"If the :c:macro:`Py_TPFLAGS_MANAGED_DICT` bit is set in the :c:member:" -"`~PyTypeObject.tp_flags` field, the clear function must call :c:func:" -"`PyObject_ClearManagedDict` like this::" -msgstr "" - -#: ../../c-api/typeobj.rst:1726 -msgid "PyObject_ClearManagedDict((PyObject*)self);" -msgstr "PyObject_ClearManagedDict((PyObject*)self);" - -#: ../../c-api/typeobj.rst:1735 -msgid "" -"This field is inherited by subtypes together with :c:member:`~PyTypeObject." -"tp_traverse` and the :c:macro:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :" -"c:member:`~PyTypeObject.tp_traverse`, and :c:member:`~PyTypeObject.tp_clear` " -"are all inherited from the base type if they are all zero in the subtype." -msgstr "" - -#: ../../c-api/typeobj.rst:1749 -msgid "" -"An optional pointer to the rich comparison function, whose signature is::" -msgstr "" - -#: ../../c-api/typeobj.rst:1751 -msgid "PyObject *tp_richcompare(PyObject *self, PyObject *other, int op);" -msgstr "PyObject *tp_richcompare(PyObject *self, PyObject *other, int op);" - -#: ../../c-api/typeobj.rst:1753 -msgid "" -"The first parameter is guaranteed to be an instance of the type that is " -"defined by :c:type:`PyTypeObject`." -msgstr "" - -#: ../../c-api/typeobj.rst:1756 -msgid "" -"The function should return the result of the comparison (usually ``Py_True`` " -"or ``Py_False``). If the comparison is undefined, it must return " -"``Py_NotImplemented``, if another error occurred it must return ``NULL`` and " -"set an exception condition." -msgstr "" - -#: ../../c-api/typeobj.rst:1761 -msgid "" -"The following constants are defined to be used as the third argument for :c:" -"member:`~PyTypeObject.tp_richcompare` and for :c:func:`PyObject_RichCompare`:" -msgstr "" - -#: ../../c-api/typeobj.rst:1767 -msgid "Constant" -msgstr "常數" - -#: ../../c-api/typeobj.rst:1767 -msgid "Comparison" -msgstr "" - -#: ../../c-api/typeobj.rst:1769 -msgid "``<``" -msgstr "``<``" - -#: ../../c-api/typeobj.rst:1771 -msgid "``<=``" -msgstr "``<=``" - -#: ../../c-api/typeobj.rst:1773 -msgid "``==``" -msgstr "``==``" - -#: ../../c-api/typeobj.rst:1775 -msgid "``!=``" -msgstr "``!=``" - -#: ../../c-api/typeobj.rst:1777 -msgid "``>``" -msgstr "``>``" - -#: ../../c-api/typeobj.rst:1779 -msgid "``>=``" -msgstr "``>=``" - -#: ../../c-api/typeobj.rst:1782 -msgid "" -"The following macro is defined to ease writing rich comparison functions:" -msgstr "" - -#: ../../c-api/typeobj.rst:1786 -msgid "" -"Return ``Py_True`` or ``Py_False`` from the function, depending on the " -"result of a comparison. VAL_A and VAL_B must be orderable by C comparison " -"operators (for example, they may be C ints or floats). The third argument " -"specifies the requested operation, as for :c:func:`PyObject_RichCompare`." -msgstr "" - -#: ../../c-api/typeobj.rst:1792 -msgid "The returned value is a new :term:`strong reference`." -msgstr "" - -#: ../../c-api/typeobj.rst:1794 -msgid "On error, sets an exception and returns ``NULL`` from the function." -msgstr "" - -#: ../../c-api/typeobj.rst:1802 -msgid "" -"This field is inherited by subtypes together with :c:member:`~PyTypeObject." -"tp_hash`: a subtype inherits :c:member:`~PyTypeObject.tp_richcompare` and :c:" -"member:`~PyTypeObject.tp_hash` when the subtype's :c:member:`~PyTypeObject." -"tp_richcompare` and :c:member:`~PyTypeObject.tp_hash` are both ``NULL``." -msgstr "" - -#: ../../c-api/typeobj.rst:1809 -msgid "" -":c:data:`PyBaseObject_Type` provides a :c:member:`~PyTypeObject." -"tp_richcompare` implementation, which may be inherited. However, if only :c:" -"member:`~PyTypeObject.tp_hash` is defined, not even the inherited function " -"is used and instances of the type will not be able to participate in any " -"comparisons." -msgstr "" - -#: ../../c-api/typeobj.rst:1818 -msgid "" -"While this field is still supported, :c:macro:`Py_TPFLAGS_MANAGED_WEAKREF` " -"should be used instead, if at all possible." -msgstr "" - -#: ../../c-api/typeobj.rst:1821 -msgid "" -"If the instances of this type are weakly referenceable, this field is " -"greater than zero and contains the offset in the instance structure of the " -"weak reference list head (ignoring the GC header, if present); this offset " -"is used by :c:func:`PyObject_ClearWeakRefs` and the ``PyWeakref_*`` " -"functions. The instance structure needs to include a field of type :c:expr:" -"`PyObject*` which is initialized to ``NULL``." -msgstr "" - -#: ../../c-api/typeobj.rst:1828 -msgid "" -"Do not confuse this field with :c:member:`~PyTypeObject.tp_weaklist`; that " -"is the list head for weak references to the type object itself." -msgstr "" - -#: ../../c-api/typeobj.rst:1831 -msgid "" -"It is an error to set both the :c:macro:`Py_TPFLAGS_MANAGED_WEAKREF` bit " -"and :c:member:`~PyTypeObject.tp_weaklistoffset`." -msgstr "" - -#: ../../c-api/typeobj.rst:1836 -msgid "" -"This field is inherited by subtypes, but see the rules listed below. A " -"subtype may override this offset; this means that the subtype uses a " -"different weak reference list head than the base type. Since the list head " -"is always found via :c:member:`~PyTypeObject.tp_weaklistoffset`, this should " -"not be a problem." -msgstr "" - -#: ../../c-api/typeobj.rst:1843 -msgid "" -"If the :c:macro:`Py_TPFLAGS_MANAGED_WEAKREF` bit is set in the :c:member:" -"`~PyTypeObject.tp_flags` field, then :c:member:`~PyTypeObject." -"tp_weaklistoffset` will be set to a negative value, to indicate that it is " -"unsafe to use this field." -msgstr "" - -#: ../../c-api/typeobj.rst:1853 -msgid "" -"An optional pointer to a function that returns an :term:`iterator` for the " -"object. Its presence normally signals that the instances of this type are :" -"term:`iterable` (although sequences may be iterable without this function)." -msgstr "" - -#: ../../c-api/typeobj.rst:1857 -msgid "This function has the same signature as :c:func:`PyObject_GetIter`::" -msgstr "" - -#: ../../c-api/typeobj.rst:1859 -msgid "PyObject *tp_iter(PyObject *self);" -msgstr "PyObject *tp_iter(PyObject *self);" - -#: ../../c-api/typeobj.rst:1870 -msgid "" -"An optional pointer to a function that returns the next item in an :term:" -"`iterator`. The signature is::" -msgstr "" - -#: ../../c-api/typeobj.rst:1873 -msgid "PyObject *tp_iternext(PyObject *self);" -msgstr "PyObject *tp_iternext(PyObject *self);" - -#: ../../c-api/typeobj.rst:1875 -msgid "" -"When the iterator is exhausted, it must return ``NULL``; a :exc:" -"`StopIteration` exception may or may not be set. When another error occurs, " -"it must return ``NULL`` too. Its presence signals that the instances of " -"this type are iterators." -msgstr "" - -#: ../../c-api/typeobj.rst:1880 -msgid "" -"Iterator types should also define the :c:member:`~PyTypeObject.tp_iter` " -"function, and that function should return the iterator instance itself (not " -"a new iterator instance)." -msgstr "" - -#: ../../c-api/typeobj.rst:1884 -msgid "This function has the same signature as :c:func:`PyIter_Next`." -msgstr "" - -#: ../../c-api/typeobj.rst:1895 -msgid "" -"An optional pointer to a static ``NULL``-terminated array of :c:type:" -"`PyMethodDef` structures, declaring regular methods of this type." -msgstr "" - -#: ../../c-api/typeobj.rst:1898 -msgid "" -"For each entry in the array, an entry is added to the type's dictionary " -"(see :c:member:`~PyTypeObject.tp_dict` below) containing a method descriptor." -msgstr "" - -#: ../../c-api/typeobj.rst:1903 -msgid "" -"This field is not inherited by subtypes (methods are inherited through a " -"different mechanism)." -msgstr "" - -#: ../../c-api/typeobj.rst:1911 -msgid "" -"An optional pointer to a static ``NULL``-terminated array of :c:type:" -"`PyMemberDef` structures, declaring regular data members (fields or slots) " -"of instances of this type." -msgstr "" - -#: ../../c-api/typeobj.rst:1915 -msgid "" -"For each entry in the array, an entry is added to the type's dictionary " -"(see :c:member:`~PyTypeObject.tp_dict` below) containing a member descriptor." -msgstr "" - -#: ../../c-api/typeobj.rst:1920 -msgid "" -"This field is not inherited by subtypes (members are inherited through a " -"different mechanism)." -msgstr "" - -#: ../../c-api/typeobj.rst:1928 -msgid "" -"An optional pointer to a static ``NULL``-terminated array of :c:type:" -"`PyGetSetDef` structures, declaring computed attributes of instances of this " -"type." -msgstr "" - -#: ../../c-api/typeobj.rst:1931 -msgid "" -"For each entry in the array, an entry is added to the type's dictionary " -"(see :c:member:`~PyTypeObject.tp_dict` below) containing a getset descriptor." -msgstr "" - -#: ../../c-api/typeobj.rst:1936 -msgid "" -"This field is not inherited by subtypes (computed attributes are inherited " -"through a different mechanism)." -msgstr "" - -#: ../../c-api/typeobj.rst:1944 -msgid "" -"An optional pointer to a base type from which type properties are " -"inherited. At this level, only single inheritance is supported; multiple " -"inheritance require dynamically creating a type object by calling the " -"metatype." -msgstr "" - -#: ../../c-api/typeobj.rst:1952 -msgid "" -"Slot initialization is subject to the rules of initializing globals. C99 " -"requires the initializers to be \"address constants\". Function designators " -"like :c:func:`PyType_GenericNew`, with implicit conversion to a pointer, are " -"valid C99 address constants." -msgstr "" - -#: ../../c-api/typeobj.rst:1957 -msgid "" -"However, the unary '&' operator applied to a non-static variable like :c:" -"data:`PyBaseObject_Type` is not required to produce an address constant. " -"Compilers may support this (gcc does), MSVC does not. Both compilers are " -"strictly standard conforming in this particular behavior." -msgstr "" - -#: ../../c-api/typeobj.rst:1963 -msgid "" -"Consequently, :c:member:`~PyTypeObject.tp_base` should be set in the " -"extension module's init function." -msgstr "" - -#: ../../c-api/typeobj.rst:1968 -msgid "This field is not inherited by subtypes (obviously)." -msgstr "" - -#: ../../c-api/typeobj.rst:1972 -msgid "" -"This field defaults to ``&PyBaseObject_Type`` (which to Python programmers " -"is known as the type :class:`object`)." -msgstr "" - -#: ../../c-api/typeobj.rst:1978 -msgid "The type's dictionary is stored here by :c:func:`PyType_Ready`." -msgstr "" - -#: ../../c-api/typeobj.rst:1980 -msgid "" -"This field should normally be initialized to ``NULL`` before PyType_Ready is " -"called; it may also be initialized to a dictionary containing initial " -"attributes for the type. Once :c:func:`PyType_Ready` has initialized the " -"type, extra attributes for the type may be added to this dictionary only if " -"they don't correspond to overloaded operations (like :meth:`~object." -"__add__`). Once initialization for the type has finished, this field should " -"be treated as read-only." -msgstr "" - -#: ../../c-api/typeobj.rst:1988 -msgid "" -"Some types may not store their dictionary in this slot. Use :c:func:" -"`PyType_GetDict` to retrieve the dictionary for an arbitrary type." -msgstr "" - -#: ../../c-api/typeobj.rst:1994 -msgid "" -"Internals detail: For static builtin types, this is always ``NULL``. " -"Instead, the dict for such types is stored on ``PyInterpreterState``. Use :c:" -"func:`PyType_GetDict` to get the dict for an arbitrary type." -msgstr "" - -#: ../../c-api/typeobj.rst:2000 -msgid "" -"This field is not inherited by subtypes (though the attributes defined in " -"here are inherited through a different mechanism)." -msgstr "" - -#: ../../c-api/typeobj.rst:2005 -msgid "" -"If this field is ``NULL``, :c:func:`PyType_Ready` will assign a new " -"dictionary to it." -msgstr "" - -#: ../../c-api/typeobj.rst:2010 -msgid "" -"It is not safe to use :c:func:`PyDict_SetItem` on or otherwise modify :c:" -"member:`~PyTypeObject.tp_dict` with the dictionary C-API." -msgstr "" - -#: ../../c-api/typeobj.rst:2018 -msgid "An optional pointer to a \"descriptor get\" function." -msgstr "" - -#: ../../c-api/typeobj.rst:2020 ../../c-api/typeobj.rst:2038 -#: ../../c-api/typeobj.rst:2104 ../../c-api/typeobj.rst:2136 -#: ../../c-api/typeobj.rst:2161 -msgid "The function signature is::" -msgstr "" - -#: ../../c-api/typeobj.rst:2022 -msgid "PyObject * tp_descr_get(PyObject *self, PyObject *obj, PyObject *type);" -msgstr "" -"PyObject * tp_descr_get(PyObject *self, PyObject *obj, PyObject *type);" - -#: ../../c-api/typeobj.rst:2035 -msgid "" -"An optional pointer to a function for setting and deleting a descriptor's " -"value." -msgstr "" - -#: ../../c-api/typeobj.rst:2040 -msgid "int tp_descr_set(PyObject *self, PyObject *obj, PyObject *value);" -msgstr "int tp_descr_set(PyObject *self, PyObject *obj, PyObject *value);" - -#: ../../c-api/typeobj.rst:2042 -msgid "The *value* argument is set to ``NULL`` to delete the value." -msgstr "" - -#: ../../c-api/typeobj.rst:2053 -msgid "" -"While this field is still supported, :c:macro:`Py_TPFLAGS_MANAGED_DICT` " -"should be used instead, if at all possible." -msgstr "" - -#: ../../c-api/typeobj.rst:2056 -msgid "" -"If the instances of this type have a dictionary containing instance " -"variables, this field is non-zero and contains the offset in the instances " -"of the type of the instance variable dictionary; this offset is used by :c:" -"func:`PyObject_GenericGetAttr`." -msgstr "" - -#: ../../c-api/typeobj.rst:2061 -msgid "" -"Do not confuse this field with :c:member:`~PyTypeObject.tp_dict`; that is " -"the dictionary for attributes of the type object itself." -msgstr "" - -#: ../../c-api/typeobj.rst:2064 -msgid "" -"The value specifies the offset of the dictionary from the start of the " -"instance structure." -msgstr "" - -#: ../../c-api/typeobj.rst:2066 -msgid "" -"The :c:member:`~PyTypeObject.tp_dictoffset` should be regarded as write-" -"only. To get the pointer to the dictionary call :c:func:" -"`PyObject_GenericGetDict`. Calling :c:func:`PyObject_GenericGetDict` may " -"need to allocate memory for the dictionary, so it is may be more efficient " -"to call :c:func:`PyObject_GetAttr` when accessing an attribute on the object." -msgstr "" - -#: ../../c-api/typeobj.rst:2072 -msgid "" -"It is an error to set both the :c:macro:`Py_TPFLAGS_MANAGED_DICT` bit and :c:" -"member:`~PyTypeObject.tp_dictoffset`." -msgstr "" - -#: ../../c-api/typeobj.rst:2077 -msgid "" -"This field is inherited by subtypes. A subtype should not override this " -"offset; doing so could be unsafe, if C code tries to access the dictionary " -"at the previous offset. To properly support inheritance, use :c:macro:" -"`Py_TPFLAGS_MANAGED_DICT`." -msgstr "" - -#: ../../c-api/typeobj.rst:2084 -msgid "" -"This slot has no default. For :ref:`static types `, if the " -"field is ``NULL`` then no :attr:`~object.__dict__` gets created for " -"instances." -msgstr "" - -#: ../../c-api/typeobj.rst:2087 -msgid "" -"If the :c:macro:`Py_TPFLAGS_MANAGED_DICT` bit is set in the :c:member:" -"`~PyTypeObject.tp_flags` field, then :c:member:`~PyTypeObject.tp_dictoffset` " -"will be set to ``-1``, to indicate that it is unsafe to use this field." -msgstr "" - -#: ../../c-api/typeobj.rst:2097 -msgid "An optional pointer to an instance initialization function." -msgstr "" - -#: ../../c-api/typeobj.rst:2099 -msgid "" -"This function corresponds to the :meth:`~object.__init__` method of " -"classes. Like :meth:`!__init__`, it is possible to create an instance " -"without calling :meth:`!__init__`, and it is possible to reinitialize an " -"instance by calling its :meth:`!__init__` method again." -msgstr "" - -#: ../../c-api/typeobj.rst:2106 -msgid "int tp_init(PyObject *self, PyObject *args, PyObject *kwds);" -msgstr "int tp_init(PyObject *self, PyObject *args, PyObject *kwds);" - -#: ../../c-api/typeobj.rst:2108 -msgid "" -"The self argument is the instance to be initialized; the *args* and *kwds* " -"arguments represent positional and keyword arguments of the call to :meth:" -"`~object.__init__`." -msgstr "" - -#: ../../c-api/typeobj.rst:2112 -msgid "" -"The :c:member:`~PyTypeObject.tp_init` function, if not ``NULL``, is called " -"when an instance is created normally by calling its type, after the type's :" -"c:member:`~PyTypeObject.tp_new` function has returned an instance of the " -"type. If the :c:member:`~PyTypeObject.tp_new` function returns an instance " -"of some other type that is not a subtype of the original type, no :c:member:" -"`~PyTypeObject.tp_init` function is called; if :c:member:`~PyTypeObject." -"tp_new` returns an instance of a subtype of the original type, the " -"subtype's :c:member:`~PyTypeObject.tp_init` is called." -msgstr "" - -#: ../../c-api/typeobj.rst:2119 -msgid "Returns ``0`` on success, ``-1`` and sets an exception on error." -msgstr "" - -#: ../../c-api/typeobj.rst:2127 -msgid "" -"For :ref:`static types ` this field does not have a default." -msgstr "" - -#: ../../c-api/typeobj.rst:2134 -msgid "An optional pointer to an instance allocation function." -msgstr "" - -#: ../../c-api/typeobj.rst:2138 -msgid "PyObject *tp_alloc(PyTypeObject *self, Py_ssize_t nitems);" -msgstr "PyObject *tp_alloc(PyTypeObject *self, Py_ssize_t nitems);" - -#: ../../c-api/typeobj.rst:2142 -msgid "" -"Static subtypes inherit this slot, which will be :c:func:" -"`PyType_GenericAlloc` if inherited from :class:`object`." -msgstr "" - -#: ../../c-api/typeobj.rst:2145 ../../c-api/typeobj.rst:2216 -msgid ":ref:`Heap subtypes ` do not inherit this slot." -msgstr "" - -#: ../../c-api/typeobj.rst:2149 -msgid "" -"For heap subtypes, this field is always set to :c:func:`PyType_GenericAlloc`." -msgstr "" - -#: ../../c-api/typeobj.rst:2152 ../../c-api/typeobj.rst:2224 -msgid "For static subtypes, this slot is inherited (see above)." -msgstr "" - -#: ../../c-api/typeobj.rst:2159 -msgid "An optional pointer to an instance creation function." -msgstr "" - -#: ../../c-api/typeobj.rst:2163 -msgid "" -"PyObject *tp_new(PyTypeObject *subtype, PyObject *args, PyObject *kwds);" -msgstr "" -"PyObject *tp_new(PyTypeObject *subtype, PyObject *args, PyObject *kwds);" - -#: ../../c-api/typeobj.rst:2165 -msgid "" -"The *subtype* argument is the type of the object being created; the *args* " -"and *kwds* arguments represent positional and keyword arguments of the call " -"to the type. Note that *subtype* doesn't have to equal the type whose :c:" -"member:`~PyTypeObject.tp_new` function is called; it may be a subtype of " -"that type (but not an unrelated type)." -msgstr "" - -#: ../../c-api/typeobj.rst:2171 -msgid "" -"The :c:member:`~PyTypeObject.tp_new` function should call ``subtype-" -">tp_alloc(subtype, nitems)`` to allocate space for the object, and then do " -"only as much further initialization as is absolutely necessary. " -"Initialization that can safely be ignored or repeated should be placed in " -"the :c:member:`~PyTypeObject.tp_init` handler. A good rule of thumb is that " -"for immutable types, all initialization should take place in :c:member:" -"`~PyTypeObject.tp_new`, while for mutable types, most initialization should " -"be deferred to :c:member:`~PyTypeObject.tp_init`." -msgstr "" - -#: ../../c-api/typeobj.rst:2179 -msgid "" -"Set the :c:macro:`Py_TPFLAGS_DISALLOW_INSTANTIATION` flag to disallow " -"creating instances of the type in Python." -msgstr "" - -#: ../../c-api/typeobj.rst:2184 -msgid "" -"This field is inherited by subtypes, except it is not inherited by :ref:" -"`static types ` whose :c:member:`~PyTypeObject.tp_base` is " -"``NULL`` or ``&PyBaseObject_Type``." -msgstr "" - -#: ../../c-api/typeobj.rst:2190 -msgid "" -"For :ref:`static types ` this field has no default. This means " -"if the slot is defined as ``NULL``, the type cannot be called to create new " -"instances; presumably there is some other way to create instances, like a " -"factory function." -msgstr "" - -#: ../../c-api/typeobj.rst:2200 -msgid "" -"An optional pointer to an instance deallocation function. Its signature is::" -msgstr "" - -#: ../../c-api/typeobj.rst:2202 -msgid "void tp_free(void *self);" -msgstr "void tp_free(void *self);" - -#: ../../c-api/typeobj.rst:2204 -msgid "" -"This function must free the memory allocated by :c:member:`~PyTypeObject." -"tp_alloc`." -msgstr "" - -#: ../../c-api/typeobj.rst:2209 -msgid "" -"Static subtypes inherit this slot, which will be :c:func:`PyObject_Free` if " -"inherited from :class:`object`. Exception: If the type supports garbage " -"collection (i.e., the :c:macro:`Py_TPFLAGS_HAVE_GC` flag is set in :c:member:" -"`~PyTypeObject.tp_flags`) and it would inherit :c:func:`PyObject_Free`, then " -"this slot is not inherited but instead defaults to :c:func:`PyObject_GC_Del`." -msgstr "" - -#: ../../c-api/typeobj.rst:2220 -msgid "" -"For :ref:`heap subtypes `, this slot defaults to a deallocator " -"suitable to match :c:func:`PyType_GenericAlloc` and the value of the :c:" -"macro:`Py_TPFLAGS_HAVE_GC` flag." -msgstr "" - -#: ../../c-api/typeobj.rst:2231 -msgid "An optional pointer to a function called by the garbage collector." -msgstr "" - -#: ../../c-api/typeobj.rst:2233 -msgid "" -"The garbage collector needs to know whether a particular object is " -"collectible or not. Normally, it is sufficient to look at the object's " -"type's :c:member:`~PyTypeObject.tp_flags` field, and check the :c:macro:" -"`Py_TPFLAGS_HAVE_GC` flag bit. But some types have a mixture of statically " -"and dynamically allocated instances, and the statically allocated instances " -"are not collectible. Such types should define this function; it should " -"return ``1`` for a collectible instance, and ``0`` for a non-collectible " -"instance. The signature is::" -msgstr "" - -#: ../../c-api/typeobj.rst:2241 -msgid "int tp_is_gc(PyObject *self);" -msgstr "int tp_is_gc(PyObject *self);" - -#: ../../c-api/typeobj.rst:2243 -msgid "" -"(The only example of this are types themselves. The metatype, :c:data:" -"`PyType_Type`, defines this function to distinguish between statically and :" -"ref:`dynamically allocated types `.)" -msgstr "" - -#: ../../c-api/typeobj.rst:2253 -msgid "" -"This slot has no default. If this field is ``NULL``, :c:macro:" -"`Py_TPFLAGS_HAVE_GC` is used as the functional equivalent." -msgstr "" - -#: ../../c-api/typeobj.rst:2261 -msgid "Tuple of base types." -msgstr "" - -#: ../../c-api/typeobj.rst:2263 ../../c-api/typeobj.rst:2287 -msgid "" -"This field should be set to ``NULL`` and treated as read-only. Python will " -"fill it in when the type is :c:func:`initialized `." -msgstr "" - -#: ../../c-api/typeobj.rst:2266 -msgid "" -"For dynamically created classes, the :c:data:`Py_tp_bases` :c:type:`slot " -"` can be used instead of the *bases* argument of :c:func:" -"`PyType_FromSpecWithBases`. The argument form is preferred." -msgstr "" - -#: ../../c-api/typeobj.rst:2273 -msgid "" -"Multiple inheritance does not work well for statically defined types. If you " -"set ``tp_bases`` to a tuple, Python will not raise an error, but some slots " -"will only be inherited from the first base." -msgstr "" - -#: ../../c-api/typeobj.rst:2279 ../../c-api/typeobj.rst:2302 -#: ../../c-api/typeobj.rst:2319 ../../c-api/typeobj.rst:2336 -#: ../../c-api/typeobj.rst:2352 -msgid "This field is not inherited." -msgstr "" - -#: ../../c-api/typeobj.rst:2284 -msgid "" -"Tuple containing the expanded set of base types, starting with the type " -"itself and ending with :class:`object`, in Method Resolution Order." -msgstr "" - -#: ../../c-api/typeobj.rst:2292 -msgid "" -"This field is not inherited; it is calculated fresh by :c:func:" -"`PyType_Ready`." -msgstr "" - -#: ../../c-api/typeobj.rst:2298 -msgid "Unused. Internal use only." -msgstr "" - -#: ../../c-api/typeobj.rst:2307 -msgid "" -"A collection of subclasses. Internal use only. May be an invalid pointer." -msgstr "" - -#: ../../c-api/typeobj.rst:2309 -msgid "" -"To get a list of subclasses, call the Python method :py:meth:`~type." -"__subclasses__`." -msgstr "" - -#: ../../c-api/typeobj.rst:2314 -msgid "" -"For some types, this field does not hold a valid :c:expr:`PyObject*`. The " -"type was changed to :c:expr:`void*` to indicate this." -msgstr "" - -#: ../../c-api/typeobj.rst:2324 -msgid "" -"Weak reference list head, for weak references to this type object. Not " -"inherited. Internal use only." -msgstr "" - -#: ../../c-api/typeobj.rst:2329 -msgid "" -"Internals detail: For the static builtin types this is always ``NULL``, even " -"if weakrefs are added. Instead, the weakrefs for each are stored on " -"``PyInterpreterState``. Use the public C-API or the internal " -"``_PyObject_GET_WEAKREFS_LISTPTR()`` macro to avoid the distinction." -msgstr "" - -#: ../../c-api/typeobj.rst:2343 -msgid "" -"This field is deprecated. Use :c:member:`~PyTypeObject.tp_finalize` instead." -msgstr "此欄位已被棄用。請改用 :c:member:`~PyTypeObject.tp_finalize`。" - -#: ../../c-api/typeobj.rst:2348 -msgid "Used to index into the method cache. Internal use only." -msgstr "" - -#: ../../c-api/typeobj.rst:2359 -msgid "" -"An optional pointer to an instance finalization function. This is the C " -"implementation of the :meth:`~object.__del__` special method. Its signature " -"is::" -msgstr "" - -#: ../../c-api/typeobj.rst:2363 -msgid "void tp_finalize(PyObject *self);" -msgstr "void tp_finalize(PyObject *self);" - -#: ../../c-api/typeobj.rst:2365 -msgid "" -"The primary purpose of finalization is to perform any non-trivial cleanup " -"that must be performed before the object is destroyed, while the object and " -"any other objects it directly or indirectly references are still in a " -"consistent state. The finalizer is allowed to execute arbitrary Python code." -msgstr "" - -#: ../../c-api/typeobj.rst:2371 -msgid "" -"Before Python automatically finalizes an object, some of the object's direct " -"or indirect referents might have themselves been automatically finalized. " -"However, none of the referents will have been automatically cleared (:c:" -"member:`~PyTypeObject.tp_clear`) yet." -msgstr "" - -#: ../../c-api/typeobj.rst:2376 -msgid "" -"Other non-finalized objects might still be using a finalized object, so the " -"finalizer must leave the object in a sane state (e.g., invariants are still " -"met)." -msgstr "" - -#: ../../c-api/typeobj.rst:2382 -msgid "" -"After Python automatically finalizes an object, Python might start " -"automatically clearing (:c:member:`~PyTypeObject.tp_clear`) the object and " -"its referents (direct and indirect). Cleared objects are not guaranteed to " -"be in a consistent state; a finalized object must be able to tolerate " -"cleared referents." -msgstr "" - -#: ../../c-api/typeobj.rst:2390 -msgid "" -"An object is not guaranteed to be automatically finalized before its " -"destructor (:c:member:`~PyTypeObject.tp_dealloc`) is called. It is " -"recommended to call :c:func:`PyObject_CallFinalizerFromDealloc` at the " -"beginning of :c:member:`!tp_dealloc` to guarantee that the object is always " -"finalized before destruction." -msgstr "" - -#: ../../c-api/typeobj.rst:2398 -msgid "" -"The :c:member:`~PyTypeObject.tp_finalize` function can be called from any " -"thread, although the :term:`GIL` will be held." -msgstr "" - -#: ../../c-api/typeobj.rst:2403 -msgid "" -"The :c:member:`!tp_finalize` function can be called during shutdown, after " -"some global variables have been deleted. See the documentation of the :meth:" -"`~object.__del__` method for details." -msgstr "" - -#: ../../c-api/typeobj.rst:2407 -msgid "" -"When Python finalizes an object, it behaves like the following algorithm:" -msgstr "" - -#: ../../c-api/typeobj.rst:2409 -msgid "" -"Python might mark the object as *finalized*. Currently, Python always marks " -"objects whose type supports garbage collection (i.e., the :c:macro:" -"`Py_TPFLAGS_HAVE_GC` flag is set in :c:member:`~PyTypeObject.tp_flags`) and " -"never marks other types of objects; this might change in a future version." -msgstr "" - -#: ../../c-api/typeobj.rst:2414 -msgid "" -"If the object is not marked as *finalized* and its :c:member:`!tp_finalize` " -"finalizer function is non-``NULL``, the finalizer function is called." -msgstr "" - -#: ../../c-api/typeobj.rst:2417 -msgid "" -"If the finalizer function was called and the finalizer made the object " -"reachable (i.e., there is a reference to the object and it is not a member " -"of a :term:`cyclic isolate`), then the finalizer is said to have " -"*resurrected* the object. It is unspecified whether the finalizer can also " -"resurrect the object by adding a new reference to the object that does not " -"make it reachable, i.e., the object is (still) a member of a cyclic isolate." -msgstr "" - -#: ../../c-api/typeobj.rst:2424 -msgid "" -"If the finalizer resurrected the object, the object's pending destruction is " -"canceled and the object's *finalized* mark might be removed if present. " -"Currently, Python never removes the *finalized* mark; this might change in a " -"future version." -msgstr "" - -#: ../../c-api/typeobj.rst:2429 -msgid "" -"*Automatic finalization* refers to any finalization performed by Python " -"except via calls to :c:func:`PyObject_CallFinalizer` or :c:func:" -"`PyObject_CallFinalizerFromDealloc`. No guarantees are made about when, if, " -"or how often an object is automatically finalized, except:" -msgstr "" - -#: ../../c-api/typeobj.rst:2434 -msgid "" -"Python will not automatically finalize an object if it is reachable, i.e., " -"there is a reference to it and it is not a member of a :term:`cyclic " -"isolate`." -msgstr "" - -#: ../../c-api/typeobj.rst:2437 -msgid "" -"Python will not automatically finalize an object if finalizing it would not " -"mark the object as *finalized*. Currently, this applies to objects whose " -"type does not support garbage collection, i.e., the :c:macro:" -"`Py_TPFLAGS_HAVE_GC` flag is not set. Such objects can still be manually " -"finalized by calling :c:func:`PyObject_CallFinalizer` or :c:func:" -"`PyObject_CallFinalizerFromDealloc`." -msgstr "" - -#: ../../c-api/typeobj.rst:2443 -msgid "" -"Python will not automatically finalize any two members of a :term:`cyclic " -"isolate` concurrently." -msgstr "" - -#: ../../c-api/typeobj.rst:2445 -msgid "" -"Python will not automatically finalize an object after it has automatically " -"cleared (:c:member:`~PyTypeObject.tp_clear`) the object." -msgstr "" - -#: ../../c-api/typeobj.rst:2447 -msgid "" -"If an object is a member of a :term:`cyclic isolate`, Python will not " -"automatically finalize it after automatically clearing (see :c:member:" -"`~PyTypeObject.tp_clear`) any other member." -msgstr "" - -#: ../../c-api/typeobj.rst:2450 -msgid "" -"Python will automatically finalize every member of a :term:`cyclic isolate` " -"before it automatically clears (see :c:member:`~PyTypeObject.tp_clear`) any " -"of them." -msgstr "" - -#: ../../c-api/typeobj.rst:2453 -msgid "" -"If Python is going to automatically clear an object (:c:member:" -"`~PyTypeObject.tp_clear`), it will automatically finalize the object first." -msgstr "" - -#: ../../c-api/typeobj.rst:2457 -msgid "" -"Python currently only automatically finalizes objects that are members of a :" -"term:`cyclic isolate`, but future versions might finalize objects regularly " -"before their destruction." -msgstr "" - -#: ../../c-api/typeobj.rst:2461 -msgid "" -"To manually finalize an object, do not call this function directly; call :c:" -"func:`PyObject_CallFinalizer` or :c:func:`PyObject_CallFinalizerFromDealloc` " -"instead." -msgstr "" - -#: ../../c-api/typeobj.rst:2465 -msgid "" -":c:member:`~PyTypeObject.tp_finalize` should leave the current exception " -"status unchanged. The recommended way to write a non-trivial finalizer is " -"to back up the exception at the beginning by calling :c:func:" -"`PyErr_GetRaisedException` and restore the exception at the end by calling :" -"c:func:`PyErr_SetRaisedException`. If an exception is encountered in the " -"middle of the finalizer, log and clear it with :c:func:" -"`PyErr_WriteUnraisable` or :c:func:`PyErr_FormatUnraisable`. For example::" -msgstr "" - -#: ../../c-api/typeobj.rst:2474 -msgid "" -"static void\n" -"foo_finalize(PyObject *self)\n" -"{\n" -" // Save the current exception, if any.\n" -" PyObject *exc = PyErr_GetRaisedException();\n" -"\n" -" // ...\n" -"\n" -" if (do_something_that_might_raise() != success_indicator) {\n" -" PyErr_WriteUnraisable(self);\n" -" goto done;\n" -" }\n" -"\n" -"done:\n" -" // Restore the saved exception. This silently discards any exception\n" -" // raised above, so be sure to call PyErr_WriteUnraisable first if\n" -" // necessary.\n" -" PyErr_SetRaisedException(exc);\n" -"}" -msgstr "" - -#: ../../c-api/typeobj.rst:2502 -msgid "" -"Before version 3.8 it was necessary to set the :c:macro:" -"`Py_TPFLAGS_HAVE_FINALIZE` flags bit in order for this field to be used. " -"This is no longer required." -msgstr "" - -#: ../../c-api/typeobj.rst:2508 -msgid ":pep:`442`: \"Safe object finalization\"" -msgstr "" - -#: ../../c-api/typeobj.rst:2511 -msgid ":c:func:`PyObject_CallFinalizer`" -msgstr ":c:func:`PyObject_CallFinalizer`" - -#: ../../c-api/typeobj.rst:2512 -msgid ":c:func:`PyObject_CallFinalizerFromDealloc`" -msgstr ":c:func:`PyObject_CallFinalizerFromDealloc`" - -#: ../../c-api/typeobj.rst:2519 -msgid "" -"A :ref:`vectorcall function ` to use for calls of this type " -"object (rather than instances). In other words, ``tp_vectorcall`` can be " -"used to optimize ``type.__call__``, which typically returns a new instance " -"of *type*." -msgstr "" - -#: ../../c-api/typeobj.rst:2524 -msgid "" -"As with any vectorcall function, if ``tp_vectorcall`` is ``NULL``, the " -"*tp_call* protocol (``Py_TYPE(type)->tp_call``) is used instead." -msgstr "" - -#: ../../c-api/typeobj.rst:2529 -msgid "" -"The :ref:`vectorcall protocol ` requires that the vectorcall " -"function has the same behavior as the corresponding ``tp_call``. This means " -"that ``type->tp_vectorcall`` must match the behavior of ``Py_TYPE(type)-" -">tp_call``." -msgstr "" - -#: ../../c-api/typeobj.rst:2534 -msgid "" -"Specifically, if *type* uses the default metaclass, ``type->tp_vectorcall`` " -"must behave the same as :c:expr:`PyType_Type->tp_call`, which:" -msgstr "" - -#: ../../c-api/typeobj.rst:2538 -msgid "calls ``type->tp_new``," -msgstr "呼叫 ``type->tp_new``，" - -#: ../../c-api/typeobj.rst:2540 -msgid "" -"if the result is a subclass of *type*, calls ``type->tp_init`` on the result " -"of ``tp_new``, and" -msgstr "" - -#: ../../c-api/typeobj.rst:2543 -msgid "returns the result of ``tp_new``." -msgstr "回傳 ``tp_new`` 的結果。" - -#: ../../c-api/typeobj.rst:2545 -msgid "" -"Typically, ``tp_vectorcall`` is overridden to optimize this process for " -"specific :c:member:`~PyTypeObject.tp_new` and :c:member:`~PyTypeObject." -"tp_init`. When doing this for user-subclassable types, note that both can be " -"overridden (using :py:func:`~object.__new__` and :py:func:`~object." -"__init__`, respectively)." -msgstr "" - -#: ../../c-api/typeobj.rst:2556 -msgid "This field is never inherited." -msgstr "" - -#: ../../c-api/typeobj.rst:2558 -msgid "(the field exists since 3.8 but it's only used since 3.9)" -msgstr "" - -#: ../../c-api/typeobj.rst:2563 -msgid "Internal. Do not use." -msgstr "" - -#: ../../c-api/typeobj.rst:2571 -msgid "Static Types" -msgstr "靜態型別" - -#: ../../c-api/typeobj.rst:2573 -msgid "" -"Traditionally, types defined in C code are *static*, that is, a static :c:" -"type:`PyTypeObject` structure is defined directly in code and initialized " -"using :c:func:`PyType_Ready`." -msgstr "" - -#: ../../c-api/typeobj.rst:2577 -msgid "" -"This results in types that are limited relative to types defined in Python:" -msgstr "" - -#: ../../c-api/typeobj.rst:2579 -msgid "" -"Static types are limited to one base, i.e. they cannot use multiple " -"inheritance." -msgstr "" - -#: ../../c-api/typeobj.rst:2581 -msgid "" -"Static type objects (but not necessarily their instances) are immutable. It " -"is not possible to add or modify the type object's attributes from Python." -msgstr "" - -#: ../../c-api/typeobj.rst:2583 -msgid "" -"Static type objects are shared across :ref:`sub-interpreters `, so they should not include any subinterpreter-" -"specific state." -msgstr "" - -#: ../../c-api/typeobj.rst:2587 -msgid "" -"Also, since :c:type:`PyTypeObject` is only part of the :ref:`Limited API " -"` as an opaque struct, any extension modules using static " -"types must be compiled for a specific Python minor version." -msgstr "" - -#: ../../c-api/typeobj.rst:2595 -msgid "Heap Types" -msgstr "堆積型別" - -#: ../../c-api/typeobj.rst:2597 -msgid "" -"An alternative to :ref:`static types ` is *heap-allocated " -"types*, or *heap types* for short, which correspond closely to classes " -"created by Python's ``class`` statement. Heap types have the :c:macro:" -"`Py_TPFLAGS_HEAPTYPE` flag set." -msgstr "" - -#: ../../c-api/typeobj.rst:2602 -msgid "" -"This is done by filling a :c:type:`PyType_Spec` structure and calling :c:" -"func:`PyType_FromSpec`, :c:func:`PyType_FromSpecWithBases`, :c:func:" -"`PyType_FromModuleAndSpec`, or :c:func:`PyType_FromMetaclass`." -msgstr "" - -#: ../../c-api/typeobj.rst:2610 -msgid "Number Object Structures" -msgstr "" - -#: ../../c-api/typeobj.rst:2617 -msgid "" -"This structure holds pointers to the functions which an object uses to " -"implement the number protocol. Each function is used by the function of " -"similar name documented in the :ref:`number` section." -msgstr "" - -#: ../../c-api/typeobj.rst:2623 ../../c-api/typeobj.rst:3079 -msgid "Here is the structure definition::" -msgstr "" - -#: ../../c-api/typeobj.rst:2625 -msgid "" -"typedef struct {\n" -" binaryfunc nb_add;\n" -" binaryfunc nb_subtract;\n" -" binaryfunc nb_multiply;\n" -" binaryfunc nb_remainder;\n" -" binaryfunc nb_divmod;\n" -" ternaryfunc nb_power;\n" -" unaryfunc nb_negative;\n" -" unaryfunc nb_positive;\n" -" unaryfunc nb_absolute;\n" -" inquiry nb_bool;\n" -" unaryfunc nb_invert;\n" -" binaryfunc nb_lshift;\n" -" binaryfunc nb_rshift;\n" -" binaryfunc nb_and;\n" -" binaryfunc nb_xor;\n" -" binaryfunc nb_or;\n" -" unaryfunc nb_int;\n" -" void *nb_reserved;\n" -" unaryfunc nb_float;\n" -"\n" -" binaryfunc nb_inplace_add;\n" -" binaryfunc nb_inplace_subtract;\n" -" binaryfunc nb_inplace_multiply;\n" -" binaryfunc nb_inplace_remainder;\n" -" ternaryfunc nb_inplace_power;\n" -" binaryfunc nb_inplace_lshift;\n" -" binaryfunc nb_inplace_rshift;\n" -" binaryfunc nb_inplace_and;\n" -" binaryfunc nb_inplace_xor;\n" -" binaryfunc nb_inplace_or;\n" -"\n" -" binaryfunc nb_floor_divide;\n" -" binaryfunc nb_true_divide;\n" -" binaryfunc nb_inplace_floor_divide;\n" -" binaryfunc nb_inplace_true_divide;\n" -"\n" -" unaryfunc nb_index;\n" -"\n" -" binaryfunc nb_matrix_multiply;\n" -" binaryfunc nb_inplace_matrix_multiply;\n" -"} PyNumberMethods;" -msgstr "" -"typedef struct {\n" -" binaryfunc nb_add;\n" -" binaryfunc nb_subtract;\n" -" binaryfunc nb_multiply;\n" -" binaryfunc nb_remainder;\n" -" binaryfunc nb_divmod;\n" -" ternaryfunc nb_power;\n" -" unaryfunc nb_negative;\n" -" unaryfunc nb_positive;\n" -" unaryfunc nb_absolute;\n" -" inquiry nb_bool;\n" -" unaryfunc nb_invert;\n" -" binaryfunc nb_lshift;\n" -" binaryfunc nb_rshift;\n" -" binaryfunc nb_and;\n" -" binaryfunc nb_xor;\n" -" binaryfunc nb_or;\n" -" unaryfunc nb_int;\n" -" void *nb_reserved;\n" -" unaryfunc nb_float;\n" -"\n" -" binaryfunc nb_inplace_add;\n" -" binaryfunc nb_inplace_subtract;\n" -" binaryfunc nb_inplace_multiply;\n" -" binaryfunc nb_inplace_remainder;\n" -" ternaryfunc nb_inplace_power;\n" -" binaryfunc nb_inplace_lshift;\n" -" binaryfunc nb_inplace_rshift;\n" -" binaryfunc nb_inplace_and;\n" -" binaryfunc nb_inplace_xor;\n" -" binaryfunc nb_inplace_or;\n" -"\n" -" binaryfunc nb_floor_divide;\n" -" binaryfunc nb_true_divide;\n" -" binaryfunc nb_inplace_floor_divide;\n" -" binaryfunc nb_inplace_true_divide;\n" -"\n" -" unaryfunc nb_index;\n" -"\n" -" binaryfunc nb_matrix_multiply;\n" -" binaryfunc nb_inplace_matrix_multiply;\n" -"} PyNumberMethods;" - -#: ../../c-api/typeobj.rst:2670 -msgid "" -"Binary and ternary functions must check the type of all their operands, and " -"implement the necessary conversions (at least one of the operands is an " -"instance of the defined type). If the operation is not defined for the " -"given operands, binary and ternary functions must return " -"``Py_NotImplemented``, if another error occurred they must return ``NULL`` " -"and set an exception." -msgstr "" - -#: ../../c-api/typeobj.rst:2679 -msgid "" -"The :c:member:`~PyNumberMethods.nb_reserved` field should always be " -"``NULL``. It was previously called :c:member:`!nb_long`, and was renamed in " -"Python 3.0.1." -msgstr "" - -#: ../../c-api/typeobj.rst:2830 -msgid "Mapping Object Structures" -msgstr "對映物件結構" - -#: ../../c-api/typeobj.rst:2837 -msgid "" -"This structure holds pointers to the functions which an object uses to " -"implement the mapping protocol. It has three members:" -msgstr "" - -#: ../../c-api/typeobj.rst:2844 -msgid "" -"This function is used by :c:func:`PyMapping_Size` and :c:func:" -"`PyObject_Size`, and has the same signature. This slot may be set to " -"``NULL`` if the object has no defined length." -msgstr "" - -#: ../../c-api/typeobj.rst:2852 -msgid "" -"This function is used by :c:func:`PyObject_GetItem` and :c:func:" -"`PySequence_GetSlice`, and has the same signature as :c:func:`!" -"PyObject_GetItem`. This slot must be filled for the :c:func:" -"`PyMapping_Check` function to return ``1``, it can be ``NULL`` otherwise." -msgstr "" - -#: ../../c-api/typeobj.rst:2862 -msgid "" -"This function is used by :c:func:`PyObject_SetItem`, :c:func:" -"`PyObject_DelItem`, :c:func:`PySequence_SetSlice` and :c:func:" -"`PySequence_DelSlice`. It has the same signature as :c:func:`!" -"PyObject_SetItem`, but *v* can also be set to ``NULL`` to delete an item. " -"If this slot is ``NULL``, the object does not support item assignment and " -"deletion." -msgstr "" - -#: ../../c-api/typeobj.rst:2873 -msgid "Sequence Object Structures" -msgstr "序列物件結構" - -#: ../../c-api/typeobj.rst:2880 -msgid "" -"This structure holds pointers to the functions which an object uses to " -"implement the sequence protocol." -msgstr "" - -#: ../../c-api/typeobj.rst:2887 -msgid "" -"This function is used by :c:func:`PySequence_Size` and :c:func:" -"`PyObject_Size`, and has the same signature. It is also used for handling " -"negative indices via the :c:member:`~PySequenceMethods.sq_item` and the :c:" -"member:`~PySequenceMethods.sq_ass_item` slots." -msgstr "" - -#: ../../c-api/typeobj.rst:2896 -msgid "" -"This function is used by :c:func:`PySequence_Concat` and has the same " -"signature. It is also used by the ``+`` operator, after trying the numeric " -"addition via the :c:member:`~PyNumberMethods.nb_add` slot." -msgstr "" - -#: ../../c-api/typeobj.rst:2904 -msgid "" -"This function is used by :c:func:`PySequence_Repeat` and has the same " -"signature. It is also used by the ``*`` operator, after trying numeric " -"multiplication via the :c:member:`~PyNumberMethods.nb_multiply` slot." -msgstr "" - -#: ../../c-api/typeobj.rst:2912 -msgid "" -"This function is used by :c:func:`PySequence_GetItem` and has the same " -"signature. It is also used by :c:func:`PyObject_GetItem`, after trying the " -"subscription via the :c:member:`~PyMappingMethods.mp_subscript` slot. This " -"slot must be filled for the :c:func:`PySequence_Check` function to return " -"``1``, it can be ``NULL`` otherwise." -msgstr "" - -#: ../../c-api/typeobj.rst:2918 -msgid "" -"Negative indexes are handled as follows: if the :c:member:" -"`~PySequenceMethods.sq_length` slot is filled, it is called and the sequence " -"length is used to compute a positive index which is passed to :c:member:" -"`~PySequenceMethods.sq_item`. If :c:member:`!sq_length` is ``NULL``, the " -"index is passed as is to the function." -msgstr "" - -#: ../../c-api/typeobj.rst:2927 -msgid "" -"This function is used by :c:func:`PySequence_SetItem` and has the same " -"signature. It is also used by :c:func:`PyObject_SetItem` and :c:func:" -"`PyObject_DelItem`, after trying the item assignment and deletion via the :c:" -"member:`~PyMappingMethods.mp_ass_subscript` slot. This slot may be left to " -"``NULL`` if the object does not support item assignment and deletion." -msgstr "" - -#: ../../c-api/typeobj.rst:2938 -msgid "" -"This function may be used by :c:func:`PySequence_Contains` and has the same " -"signature. This slot may be left to ``NULL``, in this case :c:func:`!" -"PySequence_Contains` simply traverses the sequence until it finds a match." -msgstr "" - -#: ../../c-api/typeobj.rst:2947 -msgid "" -"This function is used by :c:func:`PySequence_InPlaceConcat` and has the same " -"signature. It should modify its first operand, and return it. This slot " -"may be left to ``NULL``, in this case :c:func:`!PySequence_InPlaceConcat` " -"will fall back to :c:func:`PySequence_Concat`. It is also used by the " -"augmented assignment ``+=``, after trying numeric in-place addition via the :" -"c:member:`~PyNumberMethods.nb_inplace_add` slot." -msgstr "" - -#: ../../c-api/typeobj.rst:2958 -msgid "" -"This function is used by :c:func:`PySequence_InPlaceRepeat` and has the same " -"signature. It should modify its first operand, and return it. This slot " -"may be left to ``NULL``, in this case :c:func:`!PySequence_InPlaceRepeat` " -"will fall back to :c:func:`PySequence_Repeat`. It is also used by the " -"augmented assignment ``*=``, after trying numeric in-place multiplication " -"via the :c:member:`~PyNumberMethods.nb_inplace_multiply` slot." -msgstr "" - -#: ../../c-api/typeobj.rst:2969 -msgid "Buffer Object Structures" -msgstr "緩衝區物件結構" - -#: ../../c-api/typeobj.rst:2977 -msgid "" -"This structure holds pointers to the functions required by the :ref:`Buffer " -"protocol `. The protocol defines how an exporter object can " -"expose its internal data to consumer objects." -msgstr "" - -#: ../../c-api/typeobj.rst:2985 ../../c-api/typeobj.rst:3036 -#: ../../c-api/typeobj.rst:3092 ../../c-api/typeobj.rst:3105 -#: ../../c-api/typeobj.rst:3119 ../../c-api/typeobj.rst:3131 -msgid "The signature of this function is::" -msgstr "函式的簽名為： ::" - -#: ../../c-api/typeobj.rst:2987 -msgid "int (PyObject *exporter, Py_buffer *view, int flags);" -msgstr "int (PyObject *exporter, Py_buffer *view, int flags);" - -#: ../../c-api/typeobj.rst:2989 -msgid "" -"Handle a request to *exporter* to fill in *view* as specified by *flags*. " -"Except for point (3), an implementation of this function MUST take these " -"steps:" -msgstr "" - -#: ../../c-api/typeobj.rst:2993 -msgid "" -"Check if the request can be met. If not, raise :exc:`BufferError`, set :c:" -"expr:`view->obj` to ``NULL`` and return ``-1``." -msgstr "" - -#: ../../c-api/typeobj.rst:2996 -msgid "Fill in the requested fields." -msgstr "" - -#: ../../c-api/typeobj.rst:2998 -msgid "Increment an internal counter for the number of exports." -msgstr "" - -#: ../../c-api/typeobj.rst:3000 -msgid "" -"Set :c:expr:`view->obj` to *exporter* and increment :c:expr:`view->obj`." -msgstr "" - -#: ../../c-api/typeobj.rst:3002 -msgid "Return ``0``." -msgstr "回傳 ``0``。" - -#: ../../c-api/typeobj.rst:3004 -msgid "" -"If *exporter* is part of a chain or tree of buffer providers, two main " -"schemes can be used:" -msgstr "" - -#: ../../c-api/typeobj.rst:3007 -msgid "" -"Re-export: Each member of the tree acts as the exporting object and sets :c:" -"expr:`view->obj` to a new reference to itself." -msgstr "" - -#: ../../c-api/typeobj.rst:3010 -msgid "" -"Redirect: The buffer request is redirected to the root object of the tree. " -"Here, :c:expr:`view->obj` will be a new reference to the root object." -msgstr "" - -#: ../../c-api/typeobj.rst:3014 -msgid "" -"The individual fields of *view* are described in section :ref:`Buffer " -"structure `, the rules how an exporter must react to " -"specific requests are in section :ref:`Buffer request types `." -msgstr "" - -#: ../../c-api/typeobj.rst:3019 -msgid "" -"All memory pointed to in the :c:type:`Py_buffer` structure belongs to the " -"exporter and must remain valid until there are no consumers left. :c:member:" -"`~Py_buffer.format`, :c:member:`~Py_buffer.shape`, :c:member:`~Py_buffer." -"strides`, :c:member:`~Py_buffer.suboffsets` and :c:member:`~Py_buffer." -"internal` are read-only for the consumer." -msgstr "" - -#: ../../c-api/typeobj.rst:3026 -msgid "" -":c:func:`PyBuffer_FillInfo` provides an easy way of exposing a simple bytes " -"buffer while dealing correctly with all request types." -msgstr "" - -#: ../../c-api/typeobj.rst:3029 -msgid "" -":c:func:`PyObject_GetBuffer` is the interface for the consumer that wraps " -"this function." -msgstr "" - -#: ../../c-api/typeobj.rst:3038 -msgid "void (PyObject *exporter, Py_buffer *view);" -msgstr "void (PyObject *exporter, Py_buffer *view);" - -#: ../../c-api/typeobj.rst:3040 -msgid "" -"Handle a request to release the resources of the buffer. If no resources " -"need to be released, :c:member:`PyBufferProcs.bf_releasebuffer` may be " -"``NULL``. Otherwise, a standard implementation of this function will take " -"these optional steps:" -msgstr "" - -#: ../../c-api/typeobj.rst:3045 -msgid "Decrement an internal counter for the number of exports." -msgstr "" - -#: ../../c-api/typeobj.rst:3047 -msgid "If the counter is ``0``, free all memory associated with *view*." -msgstr "" - -#: ../../c-api/typeobj.rst:3049 -msgid "" -"The exporter MUST use the :c:member:`~Py_buffer.internal` field to keep " -"track of buffer-specific resources. This field is guaranteed to remain " -"constant, while a consumer MAY pass a copy of the original buffer as the " -"*view* argument." -msgstr "" - -#: ../../c-api/typeobj.rst:3055 -msgid "" -"This function MUST NOT decrement :c:expr:`view->obj`, since that is done " -"automatically in :c:func:`PyBuffer_Release` (this scheme is useful for " -"breaking reference cycles)." -msgstr "" - -#: ../../c-api/typeobj.rst:3060 -msgid "" -":c:func:`PyBuffer_Release` is the interface for the consumer that wraps this " -"function." -msgstr "" - -#: ../../c-api/typeobj.rst:3068 -msgid "Async Object Structures" -msgstr "非同步物件結構" - -#: ../../c-api/typeobj.rst:3076 -msgid "" -"This structure holds pointers to the functions required to implement :term:" -"`awaitable` and :term:`asynchronous iterator` objects." -msgstr "" - -#: ../../c-api/typeobj.rst:3081 -msgid "" -"typedef struct {\n" -" unaryfunc am_await;\n" -" unaryfunc am_aiter;\n" -" unaryfunc am_anext;\n" -" sendfunc am_send;\n" -"} PyAsyncMethods;" -msgstr "" -"typedef struct {\n" -" unaryfunc am_await;\n" -" unaryfunc am_aiter;\n" -" unaryfunc am_anext;\n" -" sendfunc am_send;\n" -"} PyAsyncMethods;" - -#: ../../c-api/typeobj.rst:3094 -msgid "PyObject *am_await(PyObject *self);" -msgstr "PyObject *am_await(PyObject *self);" - -#: ../../c-api/typeobj.rst:3096 -msgid "" -"The returned object must be an :term:`iterator`, i.e. :c:func:`PyIter_Check` " -"must return ``1`` for it." -msgstr "" - -#: ../../c-api/typeobj.rst:3099 -msgid "" -"This slot may be set to ``NULL`` if an object is not an :term:`awaitable`." -msgstr "" - -#: ../../c-api/typeobj.rst:3107 -msgid "PyObject *am_aiter(PyObject *self);" -msgstr "PyObject *am_aiter(PyObject *self);" - -#: ../../c-api/typeobj.rst:3109 -msgid "" -"Must return an :term:`asynchronous iterator` object. See :meth:`~object." -"__anext__` for details." -msgstr "" - -#: ../../c-api/typeobj.rst:3112 -msgid "" -"This slot may be set to ``NULL`` if an object does not implement " -"asynchronous iteration protocol." -msgstr "" - -#: ../../c-api/typeobj.rst:3121 -msgid "PyObject *am_anext(PyObject *self);" -msgstr "PyObject *am_anext(PyObject *self);" - -#: ../../c-api/typeobj.rst:3123 -msgid "" -"Must return an :term:`awaitable` object. See :meth:`~object.__anext__` for " -"details. This slot may be set to ``NULL``." -msgstr "" - -#: ../../c-api/typeobj.rst:3133 -msgid "PySendResult am_send(PyObject *self, PyObject *arg, PyObject **result);" -msgstr "" -"PySendResult am_send(PyObject *self, PyObject *arg, PyObject **result);" - -#: ../../c-api/typeobj.rst:3135 -msgid "" -"See :c:func:`PyIter_Send` for details. This slot may be set to ``NULL``." -msgstr "" - -#: ../../c-api/typeobj.rst:3144 -msgid "Slot Type typedefs" -msgstr "" - -#: ../../c-api/typeobj.rst:3148 -msgid "" -"The purpose of this function is to separate memory allocation from memory " -"initialization. It should return a pointer to a block of memory of adequate " -"length for the instance, suitably aligned, and initialized to zeros, but " -"with :c:member:`~PyObject.ob_refcnt` set to ``1`` and :c:member:`~PyObject." -"ob_type` set to the type argument. If the type's :c:member:`~PyTypeObject." -"tp_itemsize` is non-zero, the object's :c:member:`~PyVarObject.ob_size` " -"field should be initialized to *nitems* and the length of the allocated " -"memory block should be ``tp_basicsize + nitems*tp_itemsize``, rounded up to " -"a multiple of ``sizeof(void*)``; otherwise, *nitems* is not used and the " -"length of the block should be :c:member:`~PyTypeObject.tp_basicsize`." -msgstr "" - -#: ../../c-api/typeobj.rst:3158 -msgid "" -"This function should not do any other instance initialization, not even to " -"allocate additional memory; that should be done by :c:member:`~PyTypeObject." -"tp_new`." -msgstr "" - -#: ../../c-api/typeobj.rst:3165 -msgid "See :c:member:`~PyTypeObject.tp_free`." -msgstr "請見 :c:member:`~PyTypeObject.tp_free`。" - -#: ../../c-api/typeobj.rst:3169 -msgid "See :c:member:`~PyTypeObject.tp_new`." -msgstr "請見 :c:member:`~PyTypeObject.tp_new`。" - -#: ../../c-api/typeobj.rst:3173 -msgid "See :c:member:`~PyTypeObject.tp_init`." -msgstr "請見 :c:member:`~PyTypeObject.tp_init`。" - -#: ../../c-api/typeobj.rst:3177 -msgid "See :c:member:`~PyTypeObject.tp_repr`." -msgstr "請見 :c:member:`~PyTypeObject.tp_repr`。" - -#: ../../c-api/typeobj.rst:3181 ../../c-api/typeobj.rst:3190 -msgid "Return the value of the named attribute for the object." -msgstr "" - -#: ../../c-api/typeobj.rst:3185 ../../c-api/typeobj.rst:3196 -msgid "" -"Set the value of the named attribute for the object. The value argument is " -"set to ``NULL`` to delete the attribute." -msgstr "" - -#: ../../c-api/typeobj.rst:3192 -msgid "See :c:member:`~PyTypeObject.tp_getattro`." -msgstr "請見 :c:member:`~PyTypeObject.tp_getattro`。" - -#: ../../c-api/typeobj.rst:3199 -msgid "See :c:member:`~PyTypeObject.tp_setattro`." -msgstr "請見 :c:member:`~PyTypeObject.tp_setattro`。" - -#: ../../c-api/typeobj.rst:3203 -msgid "See :c:member:`~PyTypeObject.tp_descr_get`." -msgstr "請見 :c:member:`~PyTypeObject.tp_descr_get`。" - -#: ../../c-api/typeobj.rst:3207 -msgid "See :c:member:`~PyTypeObject.tp_descr_set`." -msgstr "請見 :c:member:`~PyTypeObject.tp_descr_set`。" - -#: ../../c-api/typeobj.rst:3211 -msgid "See :c:member:`~PyTypeObject.tp_hash`." -msgstr "請見 :c:member:`~PyTypeObject.tp_hash`。" - -#: ../../c-api/typeobj.rst:3215 -msgid "See :c:member:`~PyTypeObject.tp_richcompare`." -msgstr "請見 :c:member:`~PyTypeObject.tp_richcompare`。" - -#: ../../c-api/typeobj.rst:3219 -msgid "See :c:member:`~PyTypeObject.tp_iter`." -msgstr "請見 :c:member:`~PyTypeObject.tp_iter`。" - -#: ../../c-api/typeobj.rst:3223 -msgid "See :c:member:`~PyTypeObject.tp_iternext`." -msgstr "請見 :c:member:`~PyTypeObject.tp_iternext`。" - -#: ../../c-api/typeobj.rst:3237 -msgid "See :c:member:`~PyAsyncMethods.am_send`." -msgstr "請見 :c:member:`~PyAsyncMethods.am_send`。" - -#: ../../c-api/typeobj.rst:3253 -msgid "Examples" -msgstr "範例" - -#: ../../c-api/typeobj.rst:3255 -msgid "" -"The following are simple examples of Python type definitions. They include " -"common usage you may encounter. Some demonstrate tricky corner cases. For " -"more examples, practical info, and a tutorial, see :ref:`defining-new-types` " -"and :ref:`new-types-topics`." -msgstr "" - -#: ../../c-api/typeobj.rst:3260 -msgid "A basic :ref:`static type `::" -msgstr "" - -#: ../../c-api/typeobj.rst:3262 -msgid "" -"typedef struct {\n" -" PyObject_HEAD\n" -" const char *data;\n" -"} MyObject;\n" -"\n" -"static PyTypeObject MyObject_Type = {\n" -" PyVarObject_HEAD_INIT(NULL, 0)\n" -" .tp_name = \"mymod.MyObject\",\n" -" .tp_basicsize = sizeof(MyObject),\n" -" .tp_doc = PyDoc_STR(\"My objects\"),\n" -" .tp_new = myobj_new,\n" -" .tp_dealloc = (destructor)myobj_dealloc,\n" -" .tp_repr = (reprfunc)myobj_repr,\n" -"};" -msgstr "" -"typedef struct {\n" -" PyObject_HEAD\n" -" const char *data;\n" -"} MyObject;\n" -"\n" -"static PyTypeObject MyObject_Type = {\n" -" PyVarObject_HEAD_INIT(NULL, 0)\n" -" .tp_name = \"mymod.MyObject\",\n" -" .tp_basicsize = sizeof(MyObject),\n" -" .tp_doc = PyDoc_STR(\"My objects\"),\n" -" .tp_new = myobj_new,\n" -" .tp_dealloc = (destructor)myobj_dealloc,\n" -" .tp_repr = (reprfunc)myobj_repr,\n" -"};" - -#: ../../c-api/typeobj.rst:3277 -msgid "" -"You may also find older code (especially in the CPython code base) with a " -"more verbose initializer::" -msgstr "" - -#: ../../c-api/typeobj.rst:3280 -msgid "" -"static PyTypeObject MyObject_Type = {\n" -" PyVarObject_HEAD_INIT(NULL, 0)\n" -" \"mymod.MyObject\", /* tp_name */\n" -" sizeof(MyObject), /* tp_basicsize */\n" -" 0, /* tp_itemsize */\n" -" (destructor)myobj_dealloc, /* tp_dealloc */\n" -" 0, /* tp_vectorcall_offset */\n" -" 0, /* tp_getattr */\n" -" 0, /* tp_setattr */\n" -" 0, /* tp_as_async */\n" -" (reprfunc)myobj_repr, /* tp_repr */\n" -" 0, /* tp_as_number */\n" -" 0, /* tp_as_sequence */\n" -" 0, /* tp_as_mapping */\n" -" 0, /* tp_hash */\n" -" 0, /* tp_call */\n" -" 0, /* tp_str */\n" -" 0, /* tp_getattro */\n" -" 0, /* tp_setattro */\n" -" 0, /* tp_as_buffer */\n" -" 0, /* tp_flags */\n" -" PyDoc_STR(\"My objects\"), /* tp_doc */\n" -" 0, /* tp_traverse */\n" -" 0, /* tp_clear */\n" -" 0, /* tp_richcompare */\n" -" 0, /* tp_weaklistoffset */\n" -" 0, /* tp_iter */\n" -" 0, /* tp_iternext */\n" -" 0, /* tp_methods */\n" -" 0, /* tp_members */\n" -" 0, /* tp_getset */\n" -" 0, /* tp_base */\n" -" 0, /* tp_dict */\n" -" 0, /* tp_descr_get */\n" -" 0, /* tp_descr_set */\n" -" 0, /* tp_dictoffset */\n" -" 0, /* tp_init */\n" -" 0, /* tp_alloc */\n" -" myobj_new, /* tp_new */\n" -"};" -msgstr "" -"static PyTypeObject MyObject_Type = {\n" -" PyVarObject_HEAD_INIT(NULL, 0)\n" -" \"mymod.MyObject\", /* tp_name */\n" -" sizeof(MyObject), /* tp_basicsize */\n" -" 0, /* tp_itemsize */\n" -" (destructor)myobj_dealloc, /* tp_dealloc */\n" -" 0, /* tp_vectorcall_offset */\n" -" 0, /* tp_getattr */\n" -" 0, /* tp_setattr */\n" -" 0, /* tp_as_async */\n" -" (reprfunc)myobj_repr, /* tp_repr */\n" -" 0, /* tp_as_number */\n" -" 0, /* tp_as_sequence */\n" -" 0, /* tp_as_mapping */\n" -" 0, /* tp_hash */\n" -" 0, /* tp_call */\n" -" 0, /* tp_str */\n" -" 0, /* tp_getattro */\n" -" 0, /* tp_setattro */\n" -" 0, /* tp_as_buffer */\n" -" 0, /* tp_flags */\n" -" PyDoc_STR(\"My objects\"), /* tp_doc */\n" -" 0, /* tp_traverse */\n" -" 0, /* tp_clear */\n" -" 0, /* tp_richcompare */\n" -" 0, /* tp_weaklistoffset */\n" -" 0, /* tp_iter */\n" -" 0, /* tp_iternext */\n" -" 0, /* tp_methods */\n" -" 0, /* tp_members */\n" -" 0, /* tp_getset */\n" -" 0, /* tp_base */\n" -" 0, /* tp_dict */\n" -" 0, /* tp_descr_get */\n" -" 0, /* tp_descr_set */\n" -" 0, /* tp_dictoffset */\n" -" 0, /* tp_init */\n" -" 0, /* tp_alloc */\n" -" myobj_new, /* tp_new */\n" -"};" - -#: ../../c-api/typeobj.rst:3321 -msgid "A type that supports weakrefs, instance dicts, and hashing::" -msgstr "" - -#: ../../c-api/typeobj.rst:3323 -msgid "" -"typedef struct {\n" -" PyObject_HEAD\n" -" const char *data;\n" -"} MyObject;\n" -"\n" -"static PyTypeObject MyObject_Type = {\n" -" PyVarObject_HEAD_INIT(NULL, 0)\n" -" .tp_name = \"mymod.MyObject\",\n" -" .tp_basicsize = sizeof(MyObject),\n" -" .tp_doc = PyDoc_STR(\"My objects\"),\n" -" .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE |\n" -" Py_TPFLAGS_HAVE_GC | Py_TPFLAGS_MANAGED_DICT |\n" -" Py_TPFLAGS_MANAGED_WEAKREF,\n" -" .tp_new = myobj_new,\n" -" .tp_traverse = (traverseproc)myobj_traverse,\n" -" .tp_clear = (inquiry)myobj_clear,\n" -" .tp_alloc = PyType_GenericNew,\n" -" .tp_dealloc = (destructor)myobj_dealloc,\n" -" .tp_repr = (reprfunc)myobj_repr,\n" -" .tp_hash = (hashfunc)myobj_hash,\n" -" .tp_richcompare = PyBaseObject_Type.tp_richcompare,\n" -"};" -msgstr "" - -#: ../../c-api/typeobj.rst:3346 -msgid "" -"A str subclass that cannot be subclassed and cannot be called to create " -"instances (e.g. uses a separate factory func) using :c:macro:" -"`Py_TPFLAGS_DISALLOW_INSTANTIATION` flag::" -msgstr "" - -#: ../../c-api/typeobj.rst:3350 -msgid "" -"typedef struct {\n" -" PyUnicodeObject raw;\n" -" char *extra;\n" -"} MyStr;\n" -"\n" -"static PyTypeObject MyStr_Type = {\n" -" PyVarObject_HEAD_INIT(NULL, 0)\n" -" .tp_name = \"mymod.MyStr\",\n" -" .tp_basicsize = sizeof(MyStr),\n" -" .tp_base = NULL, // set to &PyUnicode_Type in module init\n" -" .tp_doc = PyDoc_STR(\"my custom str\"),\n" -" .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_DISALLOW_INSTANTIATION,\n" -" .tp_repr = (reprfunc)myobj_repr,\n" -"};" -msgstr "" - -#: ../../c-api/typeobj.rst:3365 -msgid "" -"The simplest :ref:`static type ` with fixed-length instances::" -msgstr "" - -#: ../../c-api/typeobj.rst:3367 -msgid "" -"typedef struct {\n" -" PyObject_HEAD\n" -"} MyObject;\n" -"\n" -"static PyTypeObject MyObject_Type = {\n" -" PyVarObject_HEAD_INIT(NULL, 0)\n" -" .tp_name = \"mymod.MyObject\",\n" -"};" -msgstr "" -"typedef struct {\n" -" PyObject_HEAD\n" -"} MyObject;\n" -"\n" -"static PyTypeObject MyObject_Type = {\n" -" PyVarObject_HEAD_INIT(NULL, 0)\n" -" .tp_name = \"mymod.MyObject\",\n" -"};" - -#: ../../c-api/typeobj.rst:3376 -msgid "" -"The simplest :ref:`static type ` with variable-length " -"instances::" -msgstr "" - -#: ../../c-api/typeobj.rst:3378 -msgid "" -"typedef struct {\n" -" PyObject_VAR_HEAD\n" -" const char *data[1];\n" -"} MyObject;\n" -"\n" -"static PyTypeObject MyObject_Type = {\n" -" PyVarObject_HEAD_INIT(NULL, 0)\n" -" .tp_name = \"mymod.MyObject\",\n" -" .tp_basicsize = sizeof(MyObject) - sizeof(char *),\n" -" .tp_itemsize = sizeof(char *),\n" -"};" -msgstr "" -"typedef struct {\n" -" PyObject_VAR_HEAD\n" -" const char *data[1];\n" -"} MyObject;\n" -"\n" -"static PyTypeObject MyObject_Type = {\n" -" PyVarObject_HEAD_INIT(NULL, 0)\n" -" .tp_name = \"mymod.MyObject\",\n" -" .tp_basicsize = sizeof(MyObject) - sizeof(char *),\n" -" .tp_itemsize = sizeof(char *),\n" -"};" - -#: ../../c-api/typeobj.rst:920 ../../c-api/typeobj.rst:987 -msgid "built-in function" -msgstr "built-in function（內建函式）" - -#: ../../c-api/typeobj.rst:920 -msgid "repr" -msgstr "repr" - -#: ../../c-api/typeobj.rst:987 -msgid "hash" -msgstr "hash（雜湊）" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-12-09 00:14+0000\n" +"PO-Revision-Date: 2018-05-23 14:33+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" + +#: ../../c-api/typeobj.rst:6 +msgid "Type Object Structures" +msgstr "型別物件結構" + +#: ../../c-api/typeobj.rst:8 +msgid "" +"Perhaps one of the most important structures of the Python object system is " +"the structure that defines a new type: the :c:type:`PyTypeObject` " +"structure. Type objects can be handled using any of the ``PyObject_*`` or " +"``PyType_*`` functions, but do not offer much that's interesting to most " +"Python applications. These objects are fundamental to how objects behave, so " +"they are very important to the interpreter itself and to any extension " +"module that implements new types." +msgstr "" + +#: ../../c-api/typeobj.rst:16 +msgid "" +"Type objects are fairly large compared to most of the standard types. The " +"reason for the size is that each type object stores a large number of " +"values, mostly C function pointers, each of which implements a small part of " +"the type's functionality. The fields of the type object are examined in " +"detail in this section. The fields will be described in the order in which " +"they occur in the structure." +msgstr "" + +#: ../../c-api/typeobj.rst:23 +msgid "" +"In addition to the following quick reference, the :ref:`typedef-examples` " +"section provides at-a-glance insight into the meaning and use of :c:type:" +"`PyTypeObject`." +msgstr "" + +#: ../../c-api/typeobj.rst:29 +msgid "Quick Reference" +msgstr "" + +#: ../../c-api/typeobj.rst:34 +msgid "\"tp slots\"" +msgstr "\"tp slots\"" + +#: ../../c-api/typeobj.rst:40 +msgid "PyTypeObject Slot [#slots]_" +msgstr "" + +#: ../../c-api/typeobj.rst:40 ../../c-api/typeobj.rst:201 +msgid ":ref:`Type `" +msgstr ":ref:`Type `" + +#: ../../c-api/typeobj.rst:40 +msgid "special methods/attrs" +msgstr "" + +#: ../../c-api/typeobj.rst:40 +msgid "Info [#cols]_" +msgstr "" + +#: ../../c-api/typeobj.rst:42 +msgid "O" +msgstr "O" + +#: ../../c-api/typeobj.rst:42 +msgid "T" +msgstr "T" + +#: ../../c-api/typeobj.rst:42 +msgid "D" +msgstr "D" + +#: ../../c-api/typeobj.rst:42 +msgid "I" +msgstr "I" + +#: ../../c-api/typeobj.rst:44 +msgid " :c:member:`~PyTypeObject.tp_name`" +msgstr " :c:member:`~PyTypeObject.tp_name`" + +#: ../../c-api/typeobj.rst:44 ../../c-api/typeobj.rst:86 +#: ../../c-api/typeobj.rst:372 ../../c-api/typeobj.rst:377 +msgid "const char *" +msgstr "const char *" + +#: ../../c-api/typeobj.rst:44 +msgid "__name__" +msgstr "__name__" + +#: ../../c-api/typeobj.rst:44 ../../c-api/typeobj.rst:46 +#: ../../c-api/typeobj.rst:48 ../../c-api/typeobj.rst:50 +#: ../../c-api/typeobj.rst:52 ../../c-api/typeobj.rst:62 +#: ../../c-api/typeobj.rst:70 ../../c-api/typeobj.rst:72 +#: ../../c-api/typeobj.rst:74 ../../c-api/typeobj.rst:76 +#: ../../c-api/typeobj.rst:79 ../../c-api/typeobj.rst:84 +#: ../../c-api/typeobj.rst:86 ../../c-api/typeobj.rst:88 +#: ../../c-api/typeobj.rst:90 ../../c-api/typeobj.rst:92 +#: ../../c-api/typeobj.rst:99 ../../c-api/typeobj.rst:101 +#: ../../c-api/typeobj.rst:103 ../../c-api/typeobj.rst:105 +#: ../../c-api/typeobj.rst:107 ../../c-api/typeobj.rst:109 +#: ../../c-api/typeobj.rst:111 ../../c-api/typeobj.rst:115 +#: ../../c-api/typeobj.rst:117 ../../c-api/typeobj.rst:120 +#: ../../c-api/typeobj.rst:122 ../../c-api/typeobj.rst:124 +#: ../../c-api/typeobj.rst:126 ../../c-api/typeobj.rst:128 +#: ../../c-api/typeobj.rst:130 ../../c-api/typeobj.rst:146 +msgid "X" +msgstr "X" + +#: ../../c-api/typeobj.rst:46 +msgid ":c:member:`~PyTypeObject.tp_basicsize`" +msgstr ":c:member:`~PyTypeObject.tp_basicsize`" + +#: ../../c-api/typeobj.rst:46 ../../c-api/typeobj.rst:48 +#: ../../c-api/typeobj.rst:52 ../../c-api/typeobj.rst:99 +#: ../../c-api/typeobj.rst:120 ../../c-api/typeobj.rst:343 +#: ../../c-api/typeobj.rst:417 ../../c-api/typeobj.rst:448 +#: ../../c-api/typeobj.rst:453 +msgid ":c:type:`Py_ssize_t`" +msgstr ":c:type:`Py_ssize_t`" + +#: ../../c-api/typeobj.rst:48 +msgid ":c:member:`~PyTypeObject.tp_itemsize`" +msgstr ":c:member:`~PyTypeObject.tp_itemsize`" + +#: ../../c-api/typeobj.rst:50 +msgid ":c:member:`~PyTypeObject.tp_dealloc`" +msgstr ":c:member:`~PyTypeObject.tp_dealloc`" + +#: ../../c-api/typeobj.rst:50 ../../c-api/typeobj.rst:142 +#: ../../c-api/typeobj.rst:146 ../../c-api/typeobj.rst:347 +msgid ":c:type:`destructor`" +msgstr ":c:type:`destructor`" + +#: ../../c-api/typeobj.rst:52 +msgid ":c:member:`~PyTypeObject.tp_vectorcall_offset`" +msgstr ":c:member:`~PyTypeObject.tp_vectorcall_offset`" + +#: ../../c-api/typeobj.rst:54 +msgid "(:c:member:`~PyTypeObject.tp_getattr`)" +msgstr "(:c:member:`~PyTypeObject.tp_getattr`)" + +#: ../../c-api/typeobj.rst:54 ../../c-api/typeobj.rst:371 +msgid ":c:type:`getattrfunc`" +msgstr ":c:type:`getattrfunc`" + +#: ../../c-api/typeobj.rst:54 ../../c-api/typeobj.rst:76 +msgid "__getattribute__, __getattr__" +msgstr "__getattribute__, __getattr__" + +#: ../../c-api/typeobj.rst:54 ../../c-api/typeobj.rst:57 +#: ../../c-api/typeobj.rst:70 ../../c-api/typeobj.rst:76 +#: ../../c-api/typeobj.rst:79 ../../c-api/typeobj.rst:88 +#: ../../c-api/typeobj.rst:90 ../../c-api/typeobj.rst:92 +msgid "G" +msgstr "G" + +#: ../../c-api/typeobj.rst:57 +msgid "(:c:member:`~PyTypeObject.tp_setattr`)" +msgstr "(:c:member:`~PyTypeObject.tp_setattr`)" + +#: ../../c-api/typeobj.rst:57 ../../c-api/typeobj.rst:376 +msgid ":c:type:`setattrfunc`" +msgstr ":c:type:`setattrfunc`" + +#: ../../c-api/typeobj.rst:57 ../../c-api/typeobj.rst:79 +msgid "__setattr__, __delattr__" +msgstr "__setattr__, __delattr__" + +#: ../../c-api/typeobj.rst:60 +msgid ":c:member:`~PyTypeObject.tp_as_async`" +msgstr ":c:member:`~PyTypeObject.tp_as_async`" + +#: ../../c-api/typeobj.rst:60 +msgid ":c:type:`PyAsyncMethods` *" +msgstr ":c:type:`PyAsyncMethods` *" + +#: ../../c-api/typeobj.rst:60 ../../c-api/typeobj.rst:64 +#: ../../c-api/typeobj.rst:66 ../../c-api/typeobj.rst:68 +#: ../../c-api/typeobj.rst:82 +msgid ":ref:`sub-slots`" +msgstr ":ref:`sub-slots`" + +#: ../../c-api/typeobj.rst:60 ../../c-api/typeobj.rst:64 +#: ../../c-api/typeobj.rst:66 ../../c-api/typeobj.rst:68 +#: ../../c-api/typeobj.rst:82 +msgid "%" +msgstr "%" + +#: ../../c-api/typeobj.rst:62 +msgid ":c:member:`~PyTypeObject.tp_repr`" +msgstr ":c:member:`~PyTypeObject.tp_repr`" + +#: ../../c-api/typeobj.rst:62 ../../c-api/typeobj.rst:74 +#: ../../c-api/typeobj.rst:369 +msgid ":c:type:`reprfunc`" +msgstr ":c:type:`reprfunc`" + +#: ../../c-api/typeobj.rst:62 +msgid "__repr__" +msgstr "__repr__" + +#: ../../c-api/typeobj.rst:64 +msgid ":c:member:`~PyTypeObject.tp_as_number`" +msgstr ":c:member:`~PyTypeObject.tp_as_number`" + +#: ../../c-api/typeobj.rst:64 +msgid ":c:type:`PyNumberMethods` *" +msgstr ":c:type:`PyNumberMethods` *" + +#: ../../c-api/typeobj.rst:66 +msgid ":c:member:`~PyTypeObject.tp_as_sequence`" +msgstr ":c:member:`~PyTypeObject.tp_as_sequence`" + +#: ../../c-api/typeobj.rst:66 +msgid ":c:type:`PySequenceMethods` *" +msgstr ":c:type:`PySequenceMethods` *" + +#: ../../c-api/typeobj.rst:68 +msgid ":c:member:`~PyTypeObject.tp_as_mapping`" +msgstr ":c:member:`~PyTypeObject.tp_as_mapping`" + +#: ../../c-api/typeobj.rst:68 +msgid ":c:type:`PyMappingMethods` *" +msgstr ":c:type:`PyMappingMethods` *" + +#: ../../c-api/typeobj.rst:70 +msgid ":c:member:`~PyTypeObject.tp_hash`" +msgstr ":c:member:`~PyTypeObject.tp_hash`" + +#: ../../c-api/typeobj.rst:70 ../../c-api/typeobj.rst:405 +msgid ":c:type:`hashfunc`" +msgstr ":c:type:`hashfunc`" + +#: ../../c-api/typeobj.rst:70 +msgid "__hash__" +msgstr "__hash__" + +#: ../../c-api/typeobj.rst:72 +msgid ":c:member:`~PyTypeObject.tp_call`" +msgstr ":c:member:`~PyTypeObject.tp_call`" + +#: ../../c-api/typeobj.rst:72 ../../c-api/typeobj.rst:237 +#: ../../c-api/typeobj.rst:240 ../../c-api/typeobj.rst:441 +msgid ":c:type:`ternaryfunc`" +msgstr ":c:type:`ternaryfunc`" + +#: ../../c-api/typeobj.rst:72 +msgid "__call__" +msgstr "__call__" + +#: ../../c-api/typeobj.rst:74 +msgid ":c:member:`~PyTypeObject.tp_str`" +msgstr ":c:member:`~PyTypeObject.tp_str`" + +#: ../../c-api/typeobj.rst:74 +msgid "__str__" +msgstr "__str__" + +#: ../../c-api/typeobj.rst:76 +msgid ":c:member:`~PyTypeObject.tp_getattro`" +msgstr ":c:member:`~PyTypeObject.tp_getattro`" + +#: ../../c-api/typeobj.rst:76 ../../c-api/typeobj.rst:382 +msgid ":c:type:`getattrofunc`" +msgstr ":c:type:`getattrofunc`" + +#: ../../c-api/typeobj.rst:79 +msgid ":c:member:`~PyTypeObject.tp_setattro`" +msgstr ":c:member:`~PyTypeObject.tp_setattro`" + +#: ../../c-api/typeobj.rst:79 ../../c-api/typeobj.rst:387 +msgid ":c:type:`setattrofunc`" +msgstr ":c:type:`setattrofunc`" + +#: ../../c-api/typeobj.rst:82 +msgid ":c:member:`~PyTypeObject.tp_as_buffer`" +msgstr ":c:member:`~PyTypeObject.tp_as_buffer`" + +#: ../../c-api/typeobj.rst:82 +msgid ":c:type:`PyBufferProcs` *" +msgstr ":c:type:`PyBufferProcs` *" + +#: ../../c-api/typeobj.rst:84 +msgid ":c:member:`~PyTypeObject.tp_flags`" +msgstr ":c:member:`~PyTypeObject.tp_flags`" + +#: ../../c-api/typeobj.rst:84 +msgid "unsigned long" +msgstr "unsigned long" + +#: ../../c-api/typeobj.rst:84 ../../c-api/typeobj.rst:99 +#: ../../c-api/typeobj.rst:113 ../../c-api/typeobj.rst:120 +#: ../../c-api/typeobj.rst:124 ../../c-api/typeobj.rst:126 +#: ../../c-api/typeobj.rst:128 +msgid "?" +msgstr "?" + +#: ../../c-api/typeobj.rst:86 +msgid ":c:member:`~PyTypeObject.tp_doc`" +msgstr ":c:member:`~PyTypeObject.tp_doc`" + +#: ../../c-api/typeobj.rst:86 +msgid "__doc__" +msgstr "__doc__" + +#: ../../c-api/typeobj.rst:88 +msgid ":c:member:`~PyTypeObject.tp_traverse`" +msgstr ":c:member:`~PyTypeObject.tp_traverse`" + +#: ../../c-api/typeobj.rst:88 ../../c-api/typeobj.rst:351 +msgid ":c:type:`traverseproc`" +msgstr ":c:type:`traverseproc`" + +#: ../../c-api/typeobj.rst:90 +msgid ":c:member:`~PyTypeObject.tp_clear`" +msgstr ":c:member:`~PyTypeObject.tp_clear`" + +#: ../../c-api/typeobj.rst:90 ../../c-api/typeobj.rst:130 +#: ../../c-api/typeobj.rst:248 ../../c-api/typeobj.rst:430 +msgid ":c:type:`inquiry`" +msgstr ":c:type:`inquiry`" + +#: ../../c-api/typeobj.rst:92 +msgid ":c:member:`~PyTypeObject.tp_richcompare`" +msgstr ":c:member:`~PyTypeObject.tp_richcompare`" + +#: ../../c-api/typeobj.rst:92 ../../c-api/typeobj.rst:407 +msgid ":c:type:`richcmpfunc`" +msgstr ":c:type:`richcmpfunc`" + +#: ../../c-api/typeobj.rst:92 +msgid "__lt__, __le__, __eq__, __ne__, __gt__, __ge__" +msgstr "__lt__, __le__, __eq__, __ne__, __gt__, __ge__" + +#: ../../c-api/typeobj.rst:99 +msgid "(:c:member:`~PyTypeObject.tp_weaklistoffset`)" +msgstr "(:c:member:`~PyTypeObject.tp_weaklistoffset`)" + +#: ../../c-api/typeobj.rst:101 +msgid ":c:member:`~PyTypeObject.tp_iter`" +msgstr ":c:member:`~PyTypeObject.tp_iter`" + +#: ../../c-api/typeobj.rst:101 ../../c-api/typeobj.rst:413 +msgid ":c:type:`getiterfunc`" +msgstr ":c:type:`getiterfunc`" + +#: ../../c-api/typeobj.rst:101 +msgid "__iter__" +msgstr "__iter__" + +#: ../../c-api/typeobj.rst:103 +msgid ":c:member:`~PyTypeObject.tp_iternext`" +msgstr ":c:member:`~PyTypeObject.tp_iternext`" + +#: ../../c-api/typeobj.rst:103 ../../c-api/typeobj.rst:415 +msgid ":c:type:`iternextfunc`" +msgstr ":c:type:`iternextfunc`" + +#: ../../c-api/typeobj.rst:103 +msgid "__next__" +msgstr "__next__" + +#: ../../c-api/typeobj.rst:105 +msgid ":c:member:`~PyTypeObject.tp_methods`" +msgstr ":c:member:`~PyTypeObject.tp_methods`" + +#: ../../c-api/typeobj.rst:105 +msgid ":c:type:`PyMethodDef` []" +msgstr ":c:type:`PyMethodDef` []" + +#: ../../c-api/typeobj.rst:107 +msgid ":c:member:`~PyTypeObject.tp_members`" +msgstr ":c:member:`~PyTypeObject.tp_members`" + +#: ../../c-api/typeobj.rst:107 +msgid ":c:type:`PyMemberDef` []" +msgstr ":c:type:`PyMemberDef` []" + +#: ../../c-api/typeobj.rst:109 +msgid ":c:member:`~PyTypeObject.tp_getset`" +msgstr ":c:member:`~PyTypeObject.tp_getset`" + +#: ../../c-api/typeobj.rst:109 +msgid ":c:type:`PyGetSetDef` []" +msgstr ":c:type:`PyGetSetDef` []" + +#: ../../c-api/typeobj.rst:111 +msgid ":c:member:`~PyTypeObject.tp_base`" +msgstr ":c:member:`~PyTypeObject.tp_base`" + +#: ../../c-api/typeobj.rst:111 ../../c-api/typeobj.rst:342 +#: ../../c-api/typeobj.rst:357 +msgid ":c:type:`PyTypeObject` *" +msgstr ":c:type:`PyTypeObject` *" + +#: ../../c-api/typeobj.rst:111 +msgid "__base__" +msgstr "__base__" + +#: ../../c-api/typeobj.rst:113 +msgid ":c:member:`~PyTypeObject.tp_dict`" +msgstr ":c:member:`~PyTypeObject.tp_dict`" + +#: ../../c-api/typeobj.rst:113 ../../c-api/typeobj.rst:132 +#: ../../c-api/typeobj.rst:134 ../../c-api/typeobj.rst:136 +#: ../../c-api/typeobj.rst:140 ../../c-api/typeobj.rst:342 +#: ../../c-api/typeobj.rst:347 ../../c-api/typeobj.rst:351 +#: ../../c-api/typeobj.rst:357 ../../c-api/typeobj.rst:358 +#: ../../c-api/typeobj.rst:359 ../../c-api/typeobj.rst:363 +#: ../../c-api/typeobj.rst:364 ../../c-api/typeobj.rst:365 +#: ../../c-api/typeobj.rst:369 ../../c-api/typeobj.rst:371 +#: ../../c-api/typeobj.rst:376 ../../c-api/typeobj.rst:378 +#: ../../c-api/typeobj.rst:382 ../../c-api/typeobj.rst:383 +#: ../../c-api/typeobj.rst:387 ../../c-api/typeobj.rst:388 +#: ../../c-api/typeobj.rst:389 ../../c-api/typeobj.rst:393 +#: ../../c-api/typeobj.rst:394 ../../c-api/typeobj.rst:395 +#: ../../c-api/typeobj.rst:399 ../../c-api/typeobj.rst:400 +#: ../../c-api/typeobj.rst:401 ../../c-api/typeobj.rst:405 +#: ../../c-api/typeobj.rst:407 ../../c-api/typeobj.rst:408 +#: ../../c-api/typeobj.rst:413 ../../c-api/typeobj.rst:415 +#: ../../c-api/typeobj.rst:417 ../../c-api/typeobj.rst:419 +#: ../../c-api/typeobj.rst:425 ../../c-api/typeobj.rst:430 +#: ../../c-api/typeobj.rst:432 ../../c-api/typeobj.rst:436 +#: ../../c-api/typeobj.rst:437 ../../c-api/typeobj.rst:441 +#: ../../c-api/typeobj.rst:442 ../../c-api/typeobj.rst:443 +#: ../../c-api/typeobj.rst:447 ../../c-api/typeobj.rst:452 +#: ../../c-api/typeobj.rst:454 ../../c-api/typeobj.rst:458 +#: ../../c-api/typeobj.rst:459 ../../c-api/typeobj.rst:463 +#: ../../c-api/typeobj.rst:464 ../../c-api/typeobj.rst:465 +msgid ":c:type:`PyObject` *" +msgstr ":c:type:`PyObject` *" + +#: ../../c-api/typeobj.rst:113 +msgid "__dict__" +msgstr "__dict__" + +#: ../../c-api/typeobj.rst:115 +msgid ":c:member:`~PyTypeObject.tp_descr_get`" +msgstr ":c:member:`~PyTypeObject.tp_descr_get`" + +#: ../../c-api/typeobj.rst:115 ../../c-api/typeobj.rst:393 +msgid ":c:type:`descrgetfunc`" +msgstr ":c:type:`descrgetfunc`" + +#: ../../c-api/typeobj.rst:115 +msgid "__get__" +msgstr "__get__" + +#: ../../c-api/typeobj.rst:117 +msgid ":c:member:`~PyTypeObject.tp_descr_set`" +msgstr ":c:member:`~PyTypeObject.tp_descr_set`" + +#: ../../c-api/typeobj.rst:117 ../../c-api/typeobj.rst:399 +msgid ":c:type:`descrsetfunc`" +msgstr ":c:type:`descrsetfunc`" + +#: ../../c-api/typeobj.rst:117 +msgid "__set__, __delete__" +msgstr "__set__, __delete__" + +#: ../../c-api/typeobj.rst:120 +msgid "(:c:member:`~PyTypeObject.tp_dictoffset`)" +msgstr "(:c:member:`~PyTypeObject.tp_dictoffset`)" + +#: ../../c-api/typeobj.rst:122 +msgid ":c:member:`~PyTypeObject.tp_init`" +msgstr ":c:member:`~PyTypeObject.tp_init`" + +#: ../../c-api/typeobj.rst:122 ../../c-api/typeobj.rst:363 +msgid ":c:type:`initproc`" +msgstr ":c:type:`initproc`" + +#: ../../c-api/typeobj.rst:122 +msgid "__init__" +msgstr "__init__" + +#: ../../c-api/typeobj.rst:124 +msgid ":c:member:`~PyTypeObject.tp_alloc`" +msgstr ":c:member:`~PyTypeObject.tp_alloc`" + +#: ../../c-api/typeobj.rst:124 ../../c-api/typeobj.rst:342 +msgid ":c:type:`allocfunc`" +msgstr ":c:type:`allocfunc`" + +#: ../../c-api/typeobj.rst:126 +msgid ":c:member:`~PyTypeObject.tp_new`" +msgstr ":c:member:`~PyTypeObject.tp_new`" + +#: ../../c-api/typeobj.rst:126 ../../c-api/typeobj.rst:357 +msgid ":c:type:`newfunc`" +msgstr ":c:type:`newfunc`" + +#: ../../c-api/typeobj.rst:126 +msgid "__new__" +msgstr "__new__" + +#: ../../c-api/typeobj.rst:128 +msgid ":c:member:`~PyTypeObject.tp_free`" +msgstr ":c:member:`~PyTypeObject.tp_free`" + +#: ../../c-api/typeobj.rst:128 ../../c-api/typeobj.rst:349 +msgid ":c:type:`freefunc`" +msgstr ":c:type:`freefunc`" + +#: ../../c-api/typeobj.rst:130 +msgid ":c:member:`~PyTypeObject.tp_is_gc`" +msgstr ":c:member:`~PyTypeObject.tp_is_gc`" + +#: ../../c-api/typeobj.rst:132 +msgid "<:c:member:`~PyTypeObject.tp_bases`>" +msgstr "<:c:member:`~PyTypeObject.tp_bases`>" + +#: ../../c-api/typeobj.rst:132 +msgid "__bases__" +msgstr "__bases__" + +#: ../../c-api/typeobj.rst:132 ../../c-api/typeobj.rst:134 +msgid "~" +msgstr "~" + +#: ../../c-api/typeobj.rst:134 +msgid "<:c:member:`~PyTypeObject.tp_mro`>" +msgstr "<:c:member:`~PyTypeObject.tp_mro`>" + +#: ../../c-api/typeobj.rst:134 +msgid "__mro__" +msgstr "__mro__" + +#: ../../c-api/typeobj.rst:136 +msgid "[:c:member:`~PyTypeObject.tp_cache`]" +msgstr "[:c:member:`~PyTypeObject.tp_cache`]" + +#: ../../c-api/typeobj.rst:138 +msgid "[:c:member:`~PyTypeObject.tp_subclasses`]" +msgstr "[:c:member:`~PyTypeObject.tp_subclasses`]" + +#: ../../c-api/typeobj.rst:138 ../../c-api/typeobj.rst:279 +#: ../../c-api/typeobj.rst:349 ../../c-api/typeobj.rst:353 +msgid "void *" +msgstr "void *" + +#: ../../c-api/typeobj.rst:138 +msgid "__subclasses__" +msgstr "__subclasses__" + +#: ../../c-api/typeobj.rst:140 +msgid "[:c:member:`~PyTypeObject.tp_weaklist`]" +msgstr "[:c:member:`~PyTypeObject.tp_weaklist`]" + +#: ../../c-api/typeobj.rst:142 +msgid "(:c:member:`~PyTypeObject.tp_del`)" +msgstr "(:c:member:`~PyTypeObject.tp_del`)" + +#: ../../c-api/typeobj.rst:144 +msgid "[:c:member:`~PyTypeObject.tp_version_tag`]" +msgstr "[:c:member:`~PyTypeObject.tp_version_tag`]" + +#: ../../c-api/typeobj.rst:144 +msgid "unsigned int" +msgstr "unsigned int" + +#: ../../c-api/typeobj.rst:146 +msgid ":c:member:`~PyTypeObject.tp_finalize`" +msgstr ":c:member:`~PyTypeObject.tp_finalize`" + +#: ../../c-api/typeobj.rst:146 +msgid "__del__" +msgstr "__del__" + +#: ../../c-api/typeobj.rst:148 +msgid ":c:member:`~PyTypeObject.tp_vectorcall`" +msgstr ":c:member:`~PyTypeObject.tp_vectorcall`" + +#: ../../c-api/typeobj.rst:148 +msgid ":c:type:`vectorcallfunc`" +msgstr ":c:type:`vectorcallfunc`" + +#: ../../c-api/typeobj.rst:150 +msgid "[:c:member:`~PyTypeObject.tp_watched`]" +msgstr "[:c:member:`~PyTypeObject.tp_watched`]" + +#: ../../c-api/typeobj.rst:150 +msgid "unsigned char" +msgstr "unsigned char" + +#: ../../c-api/typeobj.rst:155 +msgid "" +"**()**: A slot name in parentheses indicates it is (effectively) deprecated." +msgstr "" + +#: ../../c-api/typeobj.rst:157 +msgid "" +"**<>**: Names in angle brackets should be initially set to ``NULL`` and " +"treated as read-only." +msgstr "" + +#: ../../c-api/typeobj.rst:160 +msgid "**[]**: Names in square brackets are for internal use only." +msgstr "" + +#: ../../c-api/typeobj.rst:162 +msgid "" +"**** (as a prefix) means the field is required (must be non-``NULL``)." +msgstr "" + +#: ../../c-api/typeobj.rst:164 +msgid "Columns:" +msgstr "" + +#: ../../c-api/typeobj.rst:166 +msgid "**\"O\"**: set on :c:data:`PyBaseObject_Type`" +msgstr "" + +#: ../../c-api/typeobj.rst:168 +msgid "**\"T\"**: set on :c:data:`PyType_Type`" +msgstr "" + +#: ../../c-api/typeobj.rst:170 +msgid "**\"D\"**: default (if slot is set to ``NULL``)" +msgstr "" + +#: ../../c-api/typeobj.rst:172 +msgid "" +"X - PyType_Ready sets this value if it is NULL\n" +"~ - PyType_Ready always sets this value (it should be NULL)\n" +"? - PyType_Ready may set this value depending on other slots\n" +"\n" +"Also see the inheritance column (\"I\")." +msgstr "" + +#: ../../c-api/typeobj.rst:180 +msgid "**\"I\"**: inheritance" +msgstr "" + +#: ../../c-api/typeobj.rst:182 +msgid "" +"X - type slot is inherited via *PyType_Ready* if defined with a *NULL* " +"value\n" +"% - the slots of the sub-struct are inherited individually\n" +"G - inherited, but only in combination with other slots; see the slot's " +"description\n" +"? - it's complicated; see the slot's description" +msgstr "" + +#: ../../c-api/typeobj.rst:189 +msgid "" +"Note that some slots are effectively inherited through the normal attribute " +"lookup chain." +msgstr "" + +#: ../../c-api/typeobj.rst:195 +msgid "sub-slots" +msgstr "" + +#: ../../c-api/typeobj.rst:201 +msgid "Slot" +msgstr "" + +#: ../../c-api/typeobj.rst:201 +msgid "special methods" +msgstr "" + +#: ../../c-api/typeobj.rst:204 +msgid ":c:member:`~PyAsyncMethods.am_await`" +msgstr ":c:member:`~PyAsyncMethods.am_await`" + +#: ../../c-api/typeobj.rst:204 ../../c-api/typeobj.rst:206 +#: ../../c-api/typeobj.rst:208 ../../c-api/typeobj.rst:242 +#: ../../c-api/typeobj.rst:244 ../../c-api/typeobj.rst:246 +#: ../../c-api/typeobj.rst:250 ../../c-api/typeobj.rst:277 +#: ../../c-api/typeobj.rst:281 ../../c-api/typeobj.rst:291 +#: ../../c-api/typeobj.rst:432 +msgid ":c:type:`unaryfunc`" +msgstr ":c:type:`unaryfunc`" + +#: ../../c-api/typeobj.rst:204 +msgid "__await__" +msgstr "__await__" + +#: ../../c-api/typeobj.rst:206 +msgid ":c:member:`~PyAsyncMethods.am_aiter`" +msgstr ":c:member:`~PyAsyncMethods.am_aiter`" + +#: ../../c-api/typeobj.rst:206 +msgid "__aiter__" +msgstr "__aiter__" + +#: ../../c-api/typeobj.rst:208 +msgid ":c:member:`~PyAsyncMethods.am_anext`" +msgstr ":c:member:`~PyAsyncMethods.am_anext`" + +#: ../../c-api/typeobj.rst:208 +msgid "__anext__" +msgstr "__anext__" + +#: ../../c-api/typeobj.rst:210 +msgid ":c:member:`~PyAsyncMethods.am_send`" +msgstr ":c:member:`~PyAsyncMethods.am_send`" + +#: ../../c-api/typeobj.rst:210 +msgid ":c:type:`sendfunc`" +msgstr ":c:type:`sendfunc`" + +#: ../../c-api/typeobj.rst:214 +msgid ":c:member:`~PyNumberMethods.nb_add`" +msgstr ":c:member:`~PyNumberMethods.nb_add`" + +#: ../../c-api/typeobj.rst:214 ../../c-api/typeobj.rst:217 +#: ../../c-api/typeobj.rst:219 ../../c-api/typeobj.rst:222 +#: ../../c-api/typeobj.rst:224 ../../c-api/typeobj.rst:227 +#: ../../c-api/typeobj.rst:229 ../../c-api/typeobj.rst:232 +#: ../../c-api/typeobj.rst:234 ../../c-api/typeobj.rst:252 +#: ../../c-api/typeobj.rst:255 ../../c-api/typeobj.rst:257 +#: ../../c-api/typeobj.rst:260 ../../c-api/typeobj.rst:262 +#: ../../c-api/typeobj.rst:265 ../../c-api/typeobj.rst:267 +#: ../../c-api/typeobj.rst:270 ../../c-api/typeobj.rst:272 +#: ../../c-api/typeobj.rst:275 ../../c-api/typeobj.rst:283 +#: ../../c-api/typeobj.rst:285 ../../c-api/typeobj.rst:287 +#: ../../c-api/typeobj.rst:289 ../../c-api/typeobj.rst:293 +#: ../../c-api/typeobj.rst:296 ../../c-api/typeobj.rst:302 +#: ../../c-api/typeobj.rst:311 ../../c-api/typeobj.rst:322 +#: ../../c-api/typeobj.rst:436 +msgid ":c:type:`binaryfunc`" +msgstr ":c:type:`binaryfunc`" + +#: ../../c-api/typeobj.rst:214 +msgid "__add__ __radd__" +msgstr "__add__ __radd__" + +#: ../../c-api/typeobj.rst:217 +msgid ":c:member:`~PyNumberMethods.nb_inplace_add`" +msgstr ":c:member:`~PyNumberMethods.nb_inplace_add`" + +#: ../../c-api/typeobj.rst:217 ../../c-api/typeobj.rst:322 +msgid "__iadd__" +msgstr "__iadd__" + +#: ../../c-api/typeobj.rst:219 +msgid ":c:member:`~PyNumberMethods.nb_subtract`" +msgstr ":c:member:`~PyNumberMethods.nb_subtract`" + +#: ../../c-api/typeobj.rst:219 +msgid "__sub__ __rsub__" +msgstr "__sub__ __rsub__" + +#: ../../c-api/typeobj.rst:222 +msgid ":c:member:`~PyNumberMethods.nb_inplace_subtract`" +msgstr ":c:member:`~PyNumberMethods.nb_inplace_subtract`" + +#: ../../c-api/typeobj.rst:222 +msgid "__isub__" +msgstr "__isub__" + +#: ../../c-api/typeobj.rst:224 +msgid ":c:member:`~PyNumberMethods.nb_multiply`" +msgstr ":c:member:`~PyNumberMethods.nb_multiply`" + +#: ../../c-api/typeobj.rst:224 +msgid "__mul__ __rmul__" +msgstr "__mul__ __rmul__" + +#: ../../c-api/typeobj.rst:227 +msgid ":c:member:`~PyNumberMethods.nb_inplace_multiply`" +msgstr ":c:member:`~PyNumberMethods.nb_inplace_multiply`" + +#: ../../c-api/typeobj.rst:227 ../../c-api/typeobj.rst:324 +msgid "__imul__" +msgstr "__imul__" + +#: ../../c-api/typeobj.rst:229 +msgid ":c:member:`~PyNumberMethods.nb_remainder`" +msgstr ":c:member:`~PyNumberMethods.nb_remainder`" + +#: ../../c-api/typeobj.rst:229 +msgid "__mod__ __rmod__" +msgstr "__mod__ __rmod__" + +#: ../../c-api/typeobj.rst:232 +msgid ":c:member:`~PyNumberMethods.nb_inplace_remainder`" +msgstr ":c:member:`~PyNumberMethods.nb_inplace_remainder`" + +#: ../../c-api/typeobj.rst:232 +msgid "__imod__" +msgstr "__imod__" + +#: ../../c-api/typeobj.rst:234 +msgid ":c:member:`~PyNumberMethods.nb_divmod`" +msgstr ":c:member:`~PyNumberMethods.nb_divmod`" + +#: ../../c-api/typeobj.rst:234 +msgid "__divmod__ __rdivmod__" +msgstr "__divmod__ __rdivmod__" + +#: ../../c-api/typeobj.rst:237 +msgid ":c:member:`~PyNumberMethods.nb_power`" +msgstr ":c:member:`~PyNumberMethods.nb_power`" + +#: ../../c-api/typeobj.rst:237 +msgid "__pow__ __rpow__" +msgstr "__pow__ __rpow__" + +#: ../../c-api/typeobj.rst:240 +msgid ":c:member:`~PyNumberMethods.nb_inplace_power`" +msgstr ":c:member:`~PyNumberMethods.nb_inplace_power`" + +#: ../../c-api/typeobj.rst:240 +msgid "__ipow__" +msgstr "__ipow__" + +#: ../../c-api/typeobj.rst:242 +msgid ":c:member:`~PyNumberMethods.nb_negative`" +msgstr ":c:member:`~PyNumberMethods.nb_negative`" + +#: ../../c-api/typeobj.rst:242 +msgid "__neg__" +msgstr "__neg__" + +#: ../../c-api/typeobj.rst:244 +msgid ":c:member:`~PyNumberMethods.nb_positive`" +msgstr ":c:member:`~PyNumberMethods.nb_positive`" + +#: ../../c-api/typeobj.rst:244 +msgid "__pos__" +msgstr "__pos__" + +#: ../../c-api/typeobj.rst:246 +msgid ":c:member:`~PyNumberMethods.nb_absolute`" +msgstr ":c:member:`~PyNumberMethods.nb_absolute`" + +#: ../../c-api/typeobj.rst:246 +msgid "__abs__" +msgstr "__abs__" + +#: ../../c-api/typeobj.rst:248 +msgid ":c:member:`~PyNumberMethods.nb_bool`" +msgstr ":c:member:`~PyNumberMethods.nb_bool`" + +#: ../../c-api/typeobj.rst:248 +msgid "__bool__" +msgstr "__bool__" + +#: ../../c-api/typeobj.rst:250 +msgid ":c:member:`~PyNumberMethods.nb_invert`" +msgstr ":c:member:`~PyNumberMethods.nb_invert`" + +#: ../../c-api/typeobj.rst:250 +msgid "__invert__" +msgstr "__invert__" + +#: ../../c-api/typeobj.rst:252 +msgid ":c:member:`~PyNumberMethods.nb_lshift`" +msgstr ":c:member:`~PyNumberMethods.nb_lshift`" + +#: ../../c-api/typeobj.rst:252 +msgid "__lshift__ __rlshift__" +msgstr "__lshift__ __rlshift__" + +#: ../../c-api/typeobj.rst:255 +msgid ":c:member:`~PyNumberMethods.nb_inplace_lshift`" +msgstr ":c:member:`~PyNumberMethods.nb_inplace_lshift`" + +#: ../../c-api/typeobj.rst:255 +msgid "__ilshift__" +msgstr "__ilshift__" + +#: ../../c-api/typeobj.rst:257 +msgid ":c:member:`~PyNumberMethods.nb_rshift`" +msgstr ":c:member:`~PyNumberMethods.nb_rshift`" + +#: ../../c-api/typeobj.rst:257 +msgid "__rshift__ __rrshift__" +msgstr "__rshift__ __rrshift__" + +#: ../../c-api/typeobj.rst:260 +msgid ":c:member:`~PyNumberMethods.nb_inplace_rshift`" +msgstr ":c:member:`~PyNumberMethods.nb_inplace_rshift`" + +#: ../../c-api/typeobj.rst:260 +msgid "__irshift__" +msgstr "__irshift__" + +#: ../../c-api/typeobj.rst:262 +msgid ":c:member:`~PyNumberMethods.nb_and`" +msgstr ":c:member:`~PyNumberMethods.nb_and`" + +#: ../../c-api/typeobj.rst:262 +msgid "__and__ __rand__" +msgstr "__and__ __rand__" + +#: ../../c-api/typeobj.rst:265 +msgid ":c:member:`~PyNumberMethods.nb_inplace_and`" +msgstr ":c:member:`~PyNumberMethods.nb_inplace_and`" + +#: ../../c-api/typeobj.rst:265 +msgid "__iand__" +msgstr "__iand__" + +#: ../../c-api/typeobj.rst:267 +msgid ":c:member:`~PyNumberMethods.nb_xor`" +msgstr ":c:member:`~PyNumberMethods.nb_xor`" + +#: ../../c-api/typeobj.rst:267 +msgid "__xor__ __rxor__" +msgstr "__xor__ __rxor__" + +#: ../../c-api/typeobj.rst:270 +msgid ":c:member:`~PyNumberMethods.nb_inplace_xor`" +msgstr ":c:member:`~PyNumberMethods.nb_inplace_xor`" + +#: ../../c-api/typeobj.rst:270 +msgid "__ixor__" +msgstr "__ixor__" + +#: ../../c-api/typeobj.rst:272 +msgid ":c:member:`~PyNumberMethods.nb_or`" +msgstr ":c:member:`~PyNumberMethods.nb_or`" + +#: ../../c-api/typeobj.rst:272 +msgid "__or__ __ror__" +msgstr "__or__ __ror__" + +#: ../../c-api/typeobj.rst:275 +msgid ":c:member:`~PyNumberMethods.nb_inplace_or`" +msgstr ":c:member:`~PyNumberMethods.nb_inplace_or`" + +#: ../../c-api/typeobj.rst:275 +msgid "__ior__" +msgstr "__ior__" + +#: ../../c-api/typeobj.rst:277 +msgid ":c:member:`~PyNumberMethods.nb_int`" +msgstr ":c:member:`~PyNumberMethods.nb_int`" + +#: ../../c-api/typeobj.rst:277 +msgid "__int__" +msgstr "__int__" + +#: ../../c-api/typeobj.rst:279 +msgid ":c:member:`~PyNumberMethods.nb_reserved`" +msgstr ":c:member:`~PyNumberMethods.nb_reserved`" + +#: ../../c-api/typeobj.rst:281 +msgid ":c:member:`~PyNumberMethods.nb_float`" +msgstr ":c:member:`~PyNumberMethods.nb_float`" + +#: ../../c-api/typeobj.rst:281 +msgid "__float__" +msgstr "__float__" + +#: ../../c-api/typeobj.rst:283 +msgid ":c:member:`~PyNumberMethods.nb_floor_divide`" +msgstr ":c:member:`~PyNumberMethods.nb_floor_divide`" + +#: ../../c-api/typeobj.rst:283 +msgid "__floordiv__" +msgstr "__floordiv__" + +#: ../../c-api/typeobj.rst:285 +msgid ":c:member:`~PyNumberMethods.nb_inplace_floor_divide`" +msgstr ":c:member:`~PyNumberMethods.nb_inplace_floor_divide`" + +#: ../../c-api/typeobj.rst:285 +msgid "__ifloordiv__" +msgstr "__ifloordiv__" + +#: ../../c-api/typeobj.rst:287 +msgid ":c:member:`~PyNumberMethods.nb_true_divide`" +msgstr ":c:member:`~PyNumberMethods.nb_true_divide`" + +#: ../../c-api/typeobj.rst:287 +msgid "__truediv__" +msgstr "__truediv__" + +#: ../../c-api/typeobj.rst:289 +msgid ":c:member:`~PyNumberMethods.nb_inplace_true_divide`" +msgstr ":c:member:`~PyNumberMethods.nb_inplace_true_divide`" + +#: ../../c-api/typeobj.rst:289 +msgid "__itruediv__" +msgstr "__itruediv__" + +#: ../../c-api/typeobj.rst:291 +msgid ":c:member:`~PyNumberMethods.nb_index`" +msgstr ":c:member:`~PyNumberMethods.nb_index`" + +#: ../../c-api/typeobj.rst:291 +msgid "__index__" +msgstr "__index__" + +#: ../../c-api/typeobj.rst:293 +msgid ":c:member:`~PyNumberMethods.nb_matrix_multiply`" +msgstr ":c:member:`~PyNumberMethods.nb_matrix_multiply`" + +#: ../../c-api/typeobj.rst:293 +msgid "__matmul__ __rmatmul__" +msgstr "__matmul__ __rmatmul__" + +#: ../../c-api/typeobj.rst:296 +msgid ":c:member:`~PyNumberMethods.nb_inplace_matrix_multiply`" +msgstr ":c:member:`~PyNumberMethods.nb_inplace_matrix_multiply`" + +#: ../../c-api/typeobj.rst:296 +msgid "__imatmul__" +msgstr "__imatmul__" + +#: ../../c-api/typeobj.rst:300 +msgid ":c:member:`~PyMappingMethods.mp_length`" +msgstr ":c:member:`~PyMappingMethods.mp_length`" + +#: ../../c-api/typeobj.rst:300 ../../c-api/typeobj.rst:309 +#: ../../c-api/typeobj.rst:417 +msgid ":c:type:`lenfunc`" +msgstr ":c:type:`lenfunc`" + +#: ../../c-api/typeobj.rst:300 ../../c-api/typeobj.rst:309 +msgid "__len__" +msgstr "__len__" + +#: ../../c-api/typeobj.rst:302 +msgid ":c:member:`~PyMappingMethods.mp_subscript`" +msgstr ":c:member:`~PyMappingMethods.mp_subscript`" + +#: ../../c-api/typeobj.rst:302 ../../c-api/typeobj.rst:315 +msgid "__getitem__" +msgstr "__getitem__" + +#: ../../c-api/typeobj.rst:304 +msgid ":c:member:`~PyMappingMethods.mp_ass_subscript`" +msgstr ":c:member:`~PyMappingMethods.mp_ass_subscript`" + +#: ../../c-api/typeobj.rst:304 ../../c-api/typeobj.rst:463 +msgid ":c:type:`objobjargproc`" +msgstr ":c:type:`objobjargproc`" + +#: ../../c-api/typeobj.rst:304 +msgid "__setitem__, __delitem__" +msgstr "__setitem__, __delitem__" + +#: ../../c-api/typeobj.rst:309 +msgid ":c:member:`~PySequenceMethods.sq_length`" +msgstr ":c:member:`~PySequenceMethods.sq_length`" + +#: ../../c-api/typeobj.rst:311 +msgid ":c:member:`~PySequenceMethods.sq_concat`" +msgstr ":c:member:`~PySequenceMethods.sq_concat`" + +#: ../../c-api/typeobj.rst:311 +msgid "__add__" +msgstr "__add__" + +#: ../../c-api/typeobj.rst:313 +msgid ":c:member:`~PySequenceMethods.sq_repeat`" +msgstr ":c:member:`~PySequenceMethods.sq_repeat`" + +#: ../../c-api/typeobj.rst:313 ../../c-api/typeobj.rst:315 +#: ../../c-api/typeobj.rst:324 ../../c-api/typeobj.rst:447 +msgid ":c:type:`ssizeargfunc`" +msgstr ":c:type:`ssizeargfunc`" + +#: ../../c-api/typeobj.rst:313 +msgid "__mul__" +msgstr "__mul__" + +#: ../../c-api/typeobj.rst:315 +msgid ":c:member:`~PySequenceMethods.sq_item`" +msgstr ":c:member:`~PySequenceMethods.sq_item`" + +#: ../../c-api/typeobj.rst:317 +msgid ":c:member:`~PySequenceMethods.sq_ass_item`" +msgstr ":c:member:`~PySequenceMethods.sq_ass_item`" + +#: ../../c-api/typeobj.rst:317 ../../c-api/typeobj.rst:452 +msgid ":c:type:`ssizeobjargproc`" +msgstr ":c:type:`ssizeobjargproc`" + +#: ../../c-api/typeobj.rst:317 +msgid "__setitem__ __delitem__" +msgstr "__setitem__ __delitem__" + +#: ../../c-api/typeobj.rst:320 +msgid ":c:member:`~PySequenceMethods.sq_contains`" +msgstr ":c:member:`~PySequenceMethods.sq_contains`" + +#: ../../c-api/typeobj.rst:320 ../../c-api/typeobj.rst:458 +msgid ":c:type:`objobjproc`" +msgstr ":c:type:`objobjproc`" + +#: ../../c-api/typeobj.rst:320 +msgid "__contains__" +msgstr "__contains__" + +#: ../../c-api/typeobj.rst:322 +msgid ":c:member:`~PySequenceMethods.sq_inplace_concat`" +msgstr ":c:member:`~PySequenceMethods.sq_inplace_concat`" + +#: ../../c-api/typeobj.rst:324 +msgid ":c:member:`~PySequenceMethods.sq_inplace_repeat`" +msgstr ":c:member:`~PySequenceMethods.sq_inplace_repeat`" + +#: ../../c-api/typeobj.rst:328 +msgid ":c:member:`~PyBufferProcs.bf_getbuffer`" +msgstr ":c:member:`~PyBufferProcs.bf_getbuffer`" + +#: ../../c-api/typeobj.rst:328 +msgid ":c:func:`getbufferproc`" +msgstr ":c:func:`getbufferproc`" + +#: ../../c-api/typeobj.rst:328 +msgid "__buffer__" +msgstr "__buffer__" + +#: ../../c-api/typeobj.rst:330 +msgid ":c:member:`~PyBufferProcs.bf_releasebuffer`" +msgstr ":c:member:`~PyBufferProcs.bf_releasebuffer`" + +#: ../../c-api/typeobj.rst:330 +msgid ":c:func:`releasebufferproc`" +msgstr ":c:func:`releasebufferproc`" + +#: ../../c-api/typeobj.rst:330 +msgid "__release_ buffer\\__" +msgstr "__release_ buffer\\__" + +#: ../../c-api/typeobj.rst:337 +msgid "slot typedefs" +msgstr "" + +#: ../../c-api/typeobj.rst:340 +msgid "typedef" +msgstr "typedef" + +#: ../../c-api/typeobj.rst:340 +msgid "Parameter Types" +msgstr "" + +#: ../../c-api/typeobj.rst:340 +msgid "Return Type" +msgstr "" + +#: ../../c-api/typeobj.rst:347 ../../c-api/typeobj.rst:349 +#: ../../c-api/typeobj.rst:425 +msgid "void" +msgstr "void" + +#: ../../c-api/typeobj.rst:352 +msgid ":c:type:`visitproc`" +msgstr ":c:type:`visitproc`" + +#: ../../c-api/typeobj.rst:351 ../../c-api/typeobj.rst:363 +#: ../../c-api/typeobj.rst:376 ../../c-api/typeobj.rst:387 +#: ../../c-api/typeobj.rst:399 ../../c-api/typeobj.rst:409 +#: ../../c-api/typeobj.rst:419 ../../c-api/typeobj.rst:421 +#: ../../c-api/typeobj.rst:430 ../../c-api/typeobj.rst:452 +#: ../../c-api/typeobj.rst:458 ../../c-api/typeobj.rst:463 +msgid "int" +msgstr "int" + +#: ../../c-api/typeobj.rst:405 +msgid "Py_hash_t" +msgstr "Py_hash_t" + +#: ../../c-api/typeobj.rst:419 +msgid ":c:type:`getbufferproc`" +msgstr ":c:type:`getbufferproc`" + +#: ../../c-api/typeobj.rst:420 ../../c-api/typeobj.rst:426 +msgid ":c:type:`Py_buffer` *" +msgstr ":c:type:`Py_buffer` *" + +#: ../../c-api/typeobj.rst:425 +msgid ":c:type:`releasebufferproc`" +msgstr ":c:type:`releasebufferproc`" + +#: ../../c-api/typeobj.rst:470 +msgid "See :ref:`slot-typedefs` below for more detail." +msgstr "更多細節請見下方的 :ref:`slot-typedefs`。" + +#: ../../c-api/typeobj.rst:474 +msgid "PyTypeObject Definition" +msgstr "" + +#: ../../c-api/typeobj.rst:476 +msgid "" +"The structure definition for :c:type:`PyTypeObject` can be found in :file:" +"`Include/cpython/object.h`. For convenience of reference, this repeats the " +"definition found there:" +msgstr "" + +#: ../../c-api/typeobj.rst:482 +msgid "" +"typedef struct _typeobject {\n" +" PyObject_VAR_HEAD\n" +" const char *tp_name; /* For printing, in format \".\" */\n" +" Py_ssize_t tp_basicsize, tp_itemsize; /* For allocation */\n" +"\n" +" /* Methods to implement standard operations */\n" +"\n" +" destructor tp_dealloc;\n" +" Py_ssize_t tp_vectorcall_offset;\n" +" getattrfunc tp_getattr;\n" +" setattrfunc tp_setattr;\n" +" PyAsyncMethods *tp_as_async; /* formerly known as tp_compare (Python 2)\n" +" or tp_reserved (Python 3) */\n" +" reprfunc tp_repr;\n" +"\n" +" /* Method suites for standard classes */\n" +"\n" +" PyNumberMethods *tp_as_number;\n" +" PySequenceMethods *tp_as_sequence;\n" +" PyMappingMethods *tp_as_mapping;\n" +"\n" +" /* More standard operations (here for binary compatibility) */\n" +"\n" +" hashfunc tp_hash;\n" +" ternaryfunc tp_call;\n" +" reprfunc tp_str;\n" +" getattrofunc tp_getattro;\n" +" setattrofunc tp_setattro;\n" +"\n" +" /* Functions to access object as input/output buffer */\n" +" PyBufferProcs *tp_as_buffer;\n" +"\n" +" /* Flags to define presence of optional/expanded features */\n" +" unsigned long tp_flags;\n" +"\n" +" const char *tp_doc; /* Documentation string */\n" +"\n" +" /* Assigned meaning in release 2.0 */\n" +" /* call function for all accessible objects */\n" +" traverseproc tp_traverse;\n" +"\n" +" /* delete references to contained objects */\n" +" inquiry tp_clear;\n" +"\n" +" /* Assigned meaning in release 2.1 */\n" +" /* rich comparisons */\n" +" richcmpfunc tp_richcompare;\n" +"\n" +" /* weak reference enabler */\n" +" Py_ssize_t tp_weaklistoffset;\n" +"\n" +" /* Iterators */\n" +" getiterfunc tp_iter;\n" +" iternextfunc tp_iternext;\n" +"\n" +" /* Attribute descriptor and subclassing stuff */\n" +" PyMethodDef *tp_methods;\n" +" PyMemberDef *tp_members;\n" +" PyGetSetDef *tp_getset;\n" +" // Strong reference on a heap type, borrowed reference on a static type\n" +" PyTypeObject *tp_base;\n" +" PyObject *tp_dict;\n" +" descrgetfunc tp_descr_get;\n" +" descrsetfunc tp_descr_set;\n" +" Py_ssize_t tp_dictoffset;\n" +" initproc tp_init;\n" +" allocfunc tp_alloc;\n" +" newfunc tp_new;\n" +" freefunc tp_free; /* Low-level free-memory routine */\n" +" inquiry tp_is_gc; /* For PyObject_IS_GC */\n" +" PyObject *tp_bases;\n" +" PyObject *tp_mro; /* method resolution order */\n" +" PyObject *tp_cache; /* no longer used */\n" +" void *tp_subclasses; /* for static builtin types this is an index */\n" +" PyObject *tp_weaklist; /* not used for static builtin types */\n" +" destructor tp_del;\n" +"\n" +" /* Type attribute cache version tag. Added in version 2.6.\n" +" * If zero, the cache is invalid and must be initialized.\n" +" */\n" +" unsigned int tp_version_tag;\n" +"\n" +" destructor tp_finalize;\n" +" vectorcallfunc tp_vectorcall;\n" +"\n" +" /* bitset of which type-watchers care about this type */\n" +" unsigned char tp_watched;\n" +"\n" +" /* Number of tp_version_tag values used.\n" +" * Set to _Py_ATTR_CACHE_UNUSED if the attribute cache is\n" +" * disabled for this type (e.g. due to custom MRO entries).\n" +" * Otherwise, limited to MAX_VERSIONS_PER_CLASS (defined elsewhere).\n" +" */\n" +" uint16_t tp_versions_used;\n" +"} PyTypeObject;\n" +msgstr "" + +#: ../../c-api/typeobj.rst:486 +msgid "PyObject Slots" +msgstr "" + +#: ../../c-api/typeobj.rst:488 +msgid "" +"The type object structure extends the :c:type:`PyVarObject` structure. The :" +"c:member:`~PyVarObject.ob_size` field is used for dynamic types (created by :" +"c:func:`!type_new`, usually called from a class statement). Note that :c:" +"data:`PyType_Type` (the metatype) initializes :c:member:`~PyTypeObject." +"tp_itemsize`, which means that its instances (i.e. type objects) *must* have " +"the :c:member:`~PyVarObject.ob_size` field." +msgstr "" + +#: ../../c-api/typeobj.rst:495 +msgid ":c:member:`PyObject.ob_refcnt`" +msgstr ":c:member:`PyObject.ob_refcnt`" + +#: ../../c-api/typeobj.rst:497 +msgid "" +"The type object's reference count is initialized to ``1`` by the " +"``PyObject_HEAD_INIT`` macro. Note that for :ref:`statically allocated type " +"objects `, the type's instances (objects whose :c:member:" +"`~PyObject.ob_type` points back to the type) do *not* count as references. " +"But for :ref:`dynamically allocated type objects `, the " +"instances *do* count as references." +msgstr "" + +#: ../../c-api/typeobj.rst:504 ../../c-api/typeobj.rst:527 +#: ../../c-api/typeobj.rst:543 ../../c-api/typeobj.rst:587 +#: ../../c-api/typeobj.rst:665 ../../c-api/typeobj.rst:809 +#: ../../c-api/typeobj.rst:854 ../../c-api/typeobj.rst:873 +#: ../../c-api/typeobj.rst:892 ../../c-api/typeobj.rst:910 +#: ../../c-api/typeobj.rst:936 ../../c-api/typeobj.rst:953 +#: ../../c-api/typeobj.rst:965 ../../c-api/typeobj.rst:977 +#: ../../c-api/typeobj.rst:1012 ../../c-api/typeobj.rst:1036 +#: ../../c-api/typeobj.rst:1058 ../../c-api/typeobj.rst:1081 +#: ../../c-api/typeobj.rst:1109 ../../c-api/typeobj.rst:1128 +#: ../../c-api/typeobj.rst:1144 ../../c-api/typeobj.rst:1184 +#: ../../c-api/typeobj.rst:1195 ../../c-api/typeobj.rst:1205 +#: ../../c-api/typeobj.rst:1215 ../../c-api/typeobj.rst:1229 +#: ../../c-api/typeobj.rst:1247 ../../c-api/typeobj.rst:1270 +#: ../../c-api/typeobj.rst:1288 ../../c-api/typeobj.rst:1301 +#: ../../c-api/typeobj.rst:1323 ../../c-api/typeobj.rst:1367 +#: ../../c-api/typeobj.rst:1388 ../../c-api/typeobj.rst:1407 +#: ../../c-api/typeobj.rst:1437 ../../c-api/typeobj.rst:1459 +#: ../../c-api/typeobj.rst:1487 ../../c-api/typeobj.rst:1585 +#: ../../c-api/typeobj.rst:1731 ../../c-api/typeobj.rst:1798 +#: ../../c-api/typeobj.rst:1834 ../../c-api/typeobj.rst:1861 +#: ../../c-api/typeobj.rst:1886 ../../c-api/typeobj.rst:1901 +#: ../../c-api/typeobj.rst:1918 ../../c-api/typeobj.rst:1934 +#: ../../c-api/typeobj.rst:1966 ../../c-api/typeobj.rst:1998 +#: ../../c-api/typeobj.rst:2026 ../../c-api/typeobj.rst:2046 +#: ../../c-api/typeobj.rst:2075 ../../c-api/typeobj.rst:2121 +#: ../../c-api/typeobj.rst:2140 ../../c-api/typeobj.rst:2182 +#: ../../c-api/typeobj.rst:2207 ../../c-api/typeobj.rst:2247 +#: ../../c-api/typeobj.rst:2277 ../../c-api/typeobj.rst:2290 +#: ../../c-api/typeobj.rst:2300 ../../c-api/typeobj.rst:2317 +#: ../../c-api/typeobj.rst:2334 ../../c-api/typeobj.rst:2350 +#: ../../c-api/typeobj.rst:2494 ../../c-api/typeobj.rst:2554 +msgid "**Inheritance:**" +msgstr "" + +#: ../../c-api/typeobj.rst:506 ../../c-api/typeobj.rst:545 +#: ../../c-api/typeobj.rst:589 +msgid "This field is not inherited by subtypes." +msgstr "" + +#: ../../c-api/typeobj.rst:509 +msgid ":c:member:`PyObject.ob_type`" +msgstr ":c:member:`PyObject.ob_type`" + +#: ../../c-api/typeobj.rst:511 +msgid "" +"This is the type's type, in other words its metatype. It is initialized by " +"the argument to the ``PyObject_HEAD_INIT`` macro, and its value should " +"normally be ``&PyType_Type``. However, for dynamically loadable extension " +"modules that must be usable on Windows (at least), the compiler complains " +"that this is not a valid initializer. Therefore, the convention is to pass " +"``NULL`` to the ``PyObject_HEAD_INIT`` macro and to initialize this field " +"explicitly at the start of the module's initialization function, before " +"doing anything else. This is typically done like this::" +msgstr "" + +#: ../../c-api/typeobj.rst:520 +msgid "Foo_Type.ob_type = &PyType_Type;" +msgstr "Foo_Type.ob_type = &PyType_Type;" + +#: ../../c-api/typeobj.rst:522 +msgid "" +"This should be done before any instances of the type are created. :c:func:" +"`PyType_Ready` checks if :c:member:`~PyObject.ob_type` is ``NULL``, and if " +"so, initializes it to the :c:member:`~PyObject.ob_type` field of the base " +"class. :c:func:`PyType_Ready` will not change this field if it is non-zero." +msgstr "" + +#: ../../c-api/typeobj.rst:529 ../../c-api/typeobj.rst:811 +#: ../../c-api/typeobj.rst:938 ../../c-api/typeobj.rst:1038 +#: ../../c-api/typeobj.rst:1060 ../../c-api/typeobj.rst:1863 +#: ../../c-api/typeobj.rst:1888 ../../c-api/typeobj.rst:2028 +#: ../../c-api/typeobj.rst:2048 ../../c-api/typeobj.rst:2123 +#: ../../c-api/typeobj.rst:2249 ../../c-api/typeobj.rst:2496 +msgid "This field is inherited by subtypes." +msgstr "" + +#: ../../c-api/typeobj.rst:533 +msgid "PyVarObject Slots" +msgstr "" + +#: ../../c-api/typeobj.rst:535 +msgid ":c:member:`PyVarObject.ob_size`" +msgstr ":c:member:`PyVarObject.ob_size`" + +#: ../../c-api/typeobj.rst:537 +msgid "" +"For :ref:`statically allocated type objects `, this should be " +"initialized to zero. For :ref:`dynamically allocated type objects `, this field has a special internal meaning." +msgstr "" + +#: ../../c-api/typeobj.rst:541 +msgid "This field should be accessed using the :c:func:`Py_SIZE()` macro." +msgstr "" + +#: ../../c-api/typeobj.rst:549 +msgid "PyTypeObject Slots" +msgstr "" + +#: ../../c-api/typeobj.rst:551 +msgid "" +"Each slot has a section describing inheritance. If :c:func:`PyType_Ready` " +"may set a value when the field is set to ``NULL`` then there will also be a " +"\"Default\" section. (Note that many fields set on :c:data:" +"`PyBaseObject_Type` and :c:data:`PyType_Type` effectively act as defaults.)" +msgstr "" + +#: ../../c-api/typeobj.rst:558 +msgid "" +"Pointer to a NUL-terminated string containing the name of the type. For " +"types that are accessible as module globals, the string should be the full " +"module name, followed by a dot, followed by the type name; for built-in " +"types, it should be just the type name. If the module is a submodule of a " +"package, the full package name is part of the full module name. For " +"example, a type named :class:`!T` defined in module :mod:`!M` in subpackage :" +"mod:`!Q` in package :mod:`!P` should have the :c:member:`~PyTypeObject." +"tp_name` initializer ``\"P.Q.M.T\"``." +msgstr "" + +#: ../../c-api/typeobj.rst:566 +msgid "" +"For :ref:`dynamically allocated type objects `, this should just " +"be the type name, and the module name explicitly stored in the type dict as " +"the value for key ``'__module__'``." +msgstr "" + +#: ../../c-api/typeobj.rst:571 +msgid "" +"For :ref:`statically allocated type objects `, the *tp_name* " +"field should contain a dot. Everything before the last dot is made " +"accessible as the :attr:`~type.__module__` attribute, and everything after " +"the last dot is made accessible as the :attr:`~type.__name__` attribute." +msgstr "" + +#: ../../c-api/typeobj.rst:577 +msgid "" +"If no dot is present, the entire :c:member:`~PyTypeObject.tp_name` field is " +"made accessible as the :attr:`~type.__name__` attribute, and the :attr:" +"`~type.__module__` attribute is undefined (unless explicitly set in the " +"dictionary, as explained above). This means your type will be impossible to " +"pickle. Additionally, it will not be listed in module documentations " +"created with pydoc." +msgstr "" + +#: ../../c-api/typeobj.rst:583 +msgid "" +"This field must not be ``NULL``. It is the only required field in :c:func:" +"`PyTypeObject` (other than potentially :c:member:`~PyTypeObject." +"tp_itemsize`)." +msgstr "" + +#: ../../c-api/typeobj.rst:595 +msgid "" +"These fields allow calculating the size in bytes of instances of the type." +msgstr "" + +#: ../../c-api/typeobj.rst:597 +msgid "" +"There are two kinds of types: types with fixed-length instances have a zero :" +"c:member:`!tp_itemsize` field, types with variable-length instances have a " +"non-zero :c:member:`!tp_itemsize` field. For a type with fixed-length " +"instances, all instances have the same size, given in :c:member:`!" +"tp_basicsize`. (Exceptions to this rule can be made using :c:func:" +"`PyUnstable_Object_GC_NewWithExtraData`.)" +msgstr "" + +#: ../../c-api/typeobj.rst:604 +msgid "" +"For a type with variable-length instances, the instances must have an :c:" +"member:`~PyVarObject.ob_size` field, and the instance size is :c:member:`!" +"tp_basicsize` plus N times :c:member:`!tp_itemsize`, where N is the " +"\"length\" of the object." +msgstr "" + +#: ../../c-api/typeobj.rst:609 +msgid "" +"Functions like :c:func:`PyObject_NewVar` will take the value of N as an " +"argument, and store in the instance's :c:member:`~PyVarObject.ob_size` " +"field. Note that the :c:member:`~PyVarObject.ob_size` field may later be " +"used for other purposes. For example, :py:type:`int` instances use the bits " +"of :c:member:`~PyVarObject.ob_size` in an implementation-defined way; the " +"underlying storage and its size should be accessed using :c:func:" +"`PyLong_Export`." +msgstr "" + +#: ../../c-api/typeobj.rst:619 +msgid "" +"The :c:member:`~PyVarObject.ob_size` field should be accessed using the :c:" +"func:`Py_SIZE()` and :c:func:`Py_SET_SIZE()` macros." +msgstr "" + +#: ../../c-api/typeobj.rst:622 +msgid "" +"Also, the presence of an :c:member:`~PyVarObject.ob_size` field in the " +"instance layout doesn't mean that the instance structure is variable-length. " +"For example, the :py:type:`list` type has fixed-length instances, yet those " +"instances have a :c:member:`~PyVarObject.ob_size` field. (As with :py:type:" +"`int`, avoid reading lists' :c:member:`!ob_size` directly. Call :c:func:" +"`PyList_Size` instead.)" +msgstr "" + +#: ../../c-api/typeobj.rst:629 +msgid "" +"The :c:member:`!tp_basicsize` includes size needed for data of the type's :c:" +"member:`~PyTypeObject.tp_base`, plus any extra data needed by each instance." +msgstr "" + +#: ../../c-api/typeobj.rst:633 +msgid "" +"The correct way to set :c:member:`!tp_basicsize` is to use the ``sizeof`` " +"operator on the struct used to declare the instance layout. This struct must " +"include the struct used to declare the base type. In other words, :c:member:" +"`!tp_basicsize` must be greater than or equal to the base's :c:member:`!" +"tp_basicsize`." +msgstr "" + +#: ../../c-api/typeobj.rst:639 +msgid "" +"Since every type is a subtype of :py:type:`object`, this struct must " +"include :c:type:`PyObject` or :c:type:`PyVarObject` (depending on whether :c:" +"member:`~PyVarObject.ob_size` should be included). These are usually defined " +"by the macro :c:macro:`PyObject_HEAD` or :c:macro:`PyObject_VAR_HEAD`, " +"respectively." +msgstr "" + +#: ../../c-api/typeobj.rst:645 +msgid "" +"The basic size does not include the GC header size, as that header is not " +"part of :c:macro:`PyObject_HEAD`." +msgstr "" + +#: ../../c-api/typeobj.rst:648 +msgid "" +"For cases where struct used to declare the base type is unknown, see :c:" +"member:`PyType_Spec.basicsize` and :c:func:`PyType_FromMetaclass`." +msgstr "" + +#: ../../c-api/typeobj.rst:651 +msgid "Notes about alignment:" +msgstr "" + +#: ../../c-api/typeobj.rst:653 +msgid "" +":c:member:`!tp_basicsize` must be a multiple of ``_Alignof(PyObject)``. When " +"using ``sizeof`` on a ``struct`` that includes :c:macro:`PyObject_HEAD`, as " +"recommended, the compiler ensures this. When not using a C ``struct``, or " +"when using compiler extensions like ``__attribute__((packed))``, it is up to " +"you." +msgstr "" + +#: ../../c-api/typeobj.rst:658 +msgid "" +"If the variable items require a particular alignment, :c:member:`!" +"tp_basicsize` and :c:member:`!tp_itemsize` must each be a multiple of that " +"alignment. For example, if a type's variable part stores a ``double``, it is " +"your responsibility that both fields are a multiple of ``_Alignof(double)``." +msgstr "" + +#: ../../c-api/typeobj.rst:667 +msgid "" +"These fields are inherited separately by subtypes. (That is, if the field is " +"set to zero, :c:func:`PyType_Ready` will copy the value from the base type, " +"indicating that the instances do not need additional storage.)" +msgstr "" + +#: ../../c-api/typeobj.rst:672 +msgid "" +"If the base type has a non-zero :c:member:`~PyTypeObject.tp_itemsize`, it is " +"generally not safe to set :c:member:`~PyTypeObject.tp_itemsize` to a " +"different non-zero value in a subtype (though this depends on the " +"implementation of the base type)." +msgstr "" + +#: ../../c-api/typeobj.rst:681 +msgid "" +"A pointer to the instance destructor function. The function signature is::" +msgstr "" + +#: ../../c-api/typeobj.rst:683 +msgid "void tp_dealloc(PyObject *self);" +msgstr "void tp_dealloc(PyObject *self);" + +#: ../../c-api/typeobj.rst:685 +msgid "" +"The destructor function should remove all references which the instance owns " +"(e.g., call :c:func:`Py_CLEAR`), free all memory buffers owned by the " +"instance, and call the type's :c:member:`~PyTypeObject.tp_free` function to " +"free the object itself." +msgstr "" + +#: ../../c-api/typeobj.rst:690 +msgid "" +"If you may call functions that may set the error indicator, you must use :c:" +"func:`PyErr_GetRaisedException` and :c:func:`PyErr_SetRaisedException` to " +"ensure you don't clobber a preexisting error indicator (the deallocation " +"could have occurred while processing a different error):" +msgstr "" + +#: ../../c-api/typeobj.rst:695 +msgid "" +"static void\n" +"foo_dealloc(foo_object *self)\n" +"{\n" +" PyObject *et, *ev, *etb;\n" +" PyObject *exc = PyErr_GetRaisedException();\n" +" ...\n" +" PyErr_SetRaisedException(exc);\n" +"}" +msgstr "" + +#: ../../c-api/typeobj.rst:706 +msgid "" +"The dealloc handler itself must not raise an exception; if it hits an error " +"case it should call :c:func:`PyErr_FormatUnraisable` to log (and clear) an " +"unraisable exception." +msgstr "" + +#: ../../c-api/typeobj.rst:710 +msgid "No guarantees are made about when an object is destroyed, except:" +msgstr "" + +#: ../../c-api/typeobj.rst:712 +msgid "" +"Python will destroy an object immediately or some time after the final " +"reference to the object is deleted, unless its finalizer (:c:member:" +"`~PyTypeObject.tp_finalize`) subsequently resurrects the object." +msgstr "" + +#: ../../c-api/typeobj.rst:716 +msgid "" +"An object will not be destroyed while it is being automatically finalized (:" +"c:member:`~PyTypeObject.tp_finalize`) or automatically cleared (:c:member:" +"`~PyTypeObject.tp_clear`)." +msgstr "" + +#: ../../c-api/typeobj.rst:720 +msgid "" +"CPython currently destroys an object immediately from :c:func:`Py_DECREF` " +"when the new reference count is zero, but this may change in a future " +"version." +msgstr "" + +#: ../../c-api/typeobj.rst:724 +msgid "" +"It is recommended to call :c:func:`PyObject_CallFinalizerFromDealloc` at the " +"beginning of :c:member:`!tp_dealloc` to guarantee that the object is always " +"finalized before destruction." +msgstr "" + +#: ../../c-api/typeobj.rst:728 +msgid "" +"If the type supports garbage collection (the :c:macro:`Py_TPFLAGS_HAVE_GC` " +"flag is set), the destructor should call :c:func:`PyObject_GC_UnTrack` " +"before clearing any member fields." +msgstr "" + +#: ../../c-api/typeobj.rst:732 +msgid "" +"It is permissible to call :c:member:`~PyTypeObject.tp_clear` from :c:member:" +"`!tp_dealloc` to reduce code duplication and to guarantee that the object is " +"always cleared before destruction. Beware that :c:member:`!tp_clear` might " +"have already been called." +msgstr "" + +#: ../../c-api/typeobj.rst:737 +msgid "" +"If the type is heap allocated (:c:macro:`Py_TPFLAGS_HEAPTYPE`), the " +"deallocator should release the owned reference to its type object (via :c:" +"func:`Py_DECREF`) after calling the type deallocator. See the example code " +"below.::" +msgstr "" + +#: ../../c-api/typeobj.rst:742 +msgid "" +"static void\n" +"foo_dealloc(PyObject *op)\n" +"{\n" +" foo_object *self = (foo_object *) op;\n" +" PyObject_GC_UnTrack(self);\n" +" Py_CLEAR(self->ref);\n" +" Py_TYPE(self)->tp_free(self);\n" +"}" +msgstr "" +"static void\n" +"foo_dealloc(PyObject *op)\n" +"{\n" +" foo_object *self = (foo_object *) op;\n" +" PyObject_GC_UnTrack(self);\n" +" Py_CLEAR(self->ref);\n" +" Py_TYPE(self)->tp_free(self);\n" +"}" + +#: ../../c-api/typeobj.rst:751 +msgid "" +":c:member:`!tp_dealloc` must leave the exception status unchanged. If it " +"needs to call something that might raise an exception, the exception state " +"must be backed up first and restored later (after logging any exceptions " +"with :c:func:`PyErr_WriteUnraisable`)." +msgstr "" + +#: ../../c-api/typeobj.rst:756 +msgid "Example::" +msgstr "範例： ::" + +#: ../../c-api/typeobj.rst:758 +msgid "" +"static void\n" +"foo_dealloc(PyObject *self)\n" +"{\n" +" PyObject *exc = PyErr_GetRaisedException();\n" +"\n" +" if (PyObject_CallFinalizerFromDealloc(self) < 0) {\n" +" // self was resurrected.\n" +" goto done;\n" +" }\n" +"\n" +" PyTypeObject *tp = Py_TYPE(self);\n" +"\n" +" if (tp->tp_flags & Py_TPFLAGS_HAVE_GC) {\n" +" PyObject_GC_UnTrack(self);\n" +" }\n" +"\n" +" // Optional, but convenient to avoid code duplication.\n" +" if (tp->tp_clear && tp->tp_clear(self) < 0) {\n" +" PyErr_WriteUnraisable(self);\n" +" }\n" +"\n" +" // Any additional destruction goes here.\n" +"\n" +" tp->tp_free(self);\n" +" self = NULL; // In case PyErr_WriteUnraisable() is called below.\n" +"\n" +" if (tp->tp_flags & Py_TPFLAGS_HEAPTYPE) {\n" +" Py_CLEAR(tp);\n" +" }\n" +"\n" +"done:\n" +" // Optional, if something was called that might have raised an\n" +" // exception.\n" +" if (PyErr_Occurred()) {\n" +" PyErr_WriteUnraisable(self);\n" +" }\n" +" PyErr_SetRaisedException(exc);\n" +"}" +msgstr "" + +#: ../../c-api/typeobj.rst:797 +msgid "" +":c:member:`!tp_dealloc` may be called from any Python thread, not just the " +"thread which created the object (if the object becomes part of a refcount " +"cycle, that cycle might be collected by a garbage collection on any " +"thread). This is not a problem for Python API calls, since the thread on " +"which :c:member:`!tp_dealloc` is called with an :term:`attached thread " +"state`. However, if the object being destroyed in turn destroys objects " +"from some other C library, care should be taken to ensure that destroying " +"those objects on the thread which called :c:member:`!tp_dealloc` will not " +"violate any assumptions of the library." +msgstr "" + +#: ../../c-api/typeobj.rst:815 ../../c-api/typeobj.rst:1742 +#: ../../c-api/typeobj.rst:2509 +msgid "" +":ref:`life-cycle` for details about how this slot relates to other slots." +msgstr "" + +#: ../../c-api/typeobj.rst:820 +msgid "" +"An optional offset to a per-instance function that implements calling the " +"object using the :ref:`vectorcall protocol `, a more efficient " +"alternative of the simpler :c:member:`~PyTypeObject.tp_call`." +msgstr "" + +#: ../../c-api/typeobj.rst:825 +msgid "" +"This field is only used if the flag :c:macro:`Py_TPFLAGS_HAVE_VECTORCALL` is " +"set. If so, this must be a positive integer containing the offset in the " +"instance of a :c:type:`vectorcallfunc` pointer." +msgstr "" + +#: ../../c-api/typeobj.rst:829 +msgid "" +"The *vectorcallfunc* pointer may be ``NULL``, in which case the instance " +"behaves as if :c:macro:`Py_TPFLAGS_HAVE_VECTORCALL` was not set: calling the " +"instance falls back to :c:member:`~PyTypeObject.tp_call`." +msgstr "" + +#: ../../c-api/typeobj.rst:833 +msgid "" +"Any class that sets ``Py_TPFLAGS_HAVE_VECTORCALL`` must also set :c:member:" +"`~PyTypeObject.tp_call` and make sure its behaviour is consistent with the " +"*vectorcallfunc* function. This can be done by setting *tp_call* to :c:func:" +"`PyVectorcall_Call`." +msgstr "" + +#: ../../c-api/typeobj.rst:840 +msgid "" +"Before version 3.8, this slot was named ``tp_print``. In Python 2.x, it was " +"used for printing to a file. In Python 3.0 to 3.7, it was unused." +msgstr "" + +#: ../../c-api/typeobj.rst:846 +msgid "" +"Before version 3.12, it was not recommended for :ref:`mutable heap types " +"` to implement the vectorcall protocol. When a user sets :attr:" +"`~object.__call__` in Python code, only *tp_call* is updated, likely making " +"it inconsistent with the vectorcall function. Since 3.12, setting " +"``__call__`` will disable vectorcall optimization by clearing the :c:macro:" +"`Py_TPFLAGS_HAVE_VECTORCALL` flag." +msgstr "" + +#: ../../c-api/typeobj.rst:856 +msgid "" +"This field is always inherited. However, the :c:macro:" +"`Py_TPFLAGS_HAVE_VECTORCALL` flag is not always inherited. If it's not set, " +"then the subclass won't use :ref:`vectorcall `, except when :c:" +"func:`PyVectorcall_Call` is explicitly called." +msgstr "" + +#: ../../c-api/typeobj.rst:867 +msgid "An optional pointer to the get-attribute-string function." +msgstr "" + +#: ../../c-api/typeobj.rst:869 +msgid "" +"This field is deprecated. When it is defined, it should point to a function " +"that acts the same as the :c:member:`~PyTypeObject.tp_getattro` function, " +"but taking a C string instead of a Python string object to give the " +"attribute name." +msgstr "" +"此欄位已被棄用。當它被定義時，它應該指向一個與 :c:member:`~PyTypeObject." +"tp_getattro` 行為相同但使用 C 字串而非 Python 字串物件來提供屬性名稱的函式。" + +#: ../../c-api/typeobj.rst:875 ../../c-api/typeobj.rst:1083 +msgid "" +"Group: :c:member:`~PyTypeObject.tp_getattr`, :c:member:`~PyTypeObject." +"tp_getattro`" +msgstr "" +"群組：:c:member:`~PyTypeObject.tp_getattr`、:c:member:`~PyTypeObject." +"tp_getattro`" + +#: ../../c-api/typeobj.rst:877 +msgid "" +"This field is inherited by subtypes together with :c:member:`~PyTypeObject." +"tp_getattro`: a subtype inherits both :c:member:`~PyTypeObject.tp_getattr` " +"and :c:member:`~PyTypeObject.tp_getattro` from its base type when the " +"subtype's :c:member:`~PyTypeObject.tp_getattr` and :c:member:`~PyTypeObject." +"tp_getattro` are both ``NULL``." +msgstr "" + +#: ../../c-api/typeobj.rst:886 ../../c-api/typeobj.rst:1098 +msgid "" +"An optional pointer to the function for setting and deleting attributes." +msgstr "" + +#: ../../c-api/typeobj.rst:888 +msgid "" +"This field is deprecated. When it is defined, it should point to a function " +"that acts the same as the :c:member:`~PyTypeObject.tp_setattro` function, " +"but taking a C string instead of a Python string object to give the " +"attribute name." +msgstr "" +"此欄位已被棄用。當它被定義時，它應該指向一個與 :c:member:`~PyTypeObject." +"tp_setattro` 行為相同但使用 C 字串而非 Python 字串物件來提供屬性名稱的函式。" + +#: ../../c-api/typeobj.rst:894 ../../c-api/typeobj.rst:1111 +msgid "" +"Group: :c:member:`~PyTypeObject.tp_setattr`, :c:member:`~PyTypeObject." +"tp_setattro`" +msgstr "" +"群組：:c:member:`~PyTypeObject.tp_setattr`、:c:member:`~PyTypeObject." +"tp_setattro`" + +#: ../../c-api/typeobj.rst:896 +msgid "" +"This field is inherited by subtypes together with :c:member:`~PyTypeObject." +"tp_setattro`: a subtype inherits both :c:member:`~PyTypeObject.tp_setattr` " +"and :c:member:`~PyTypeObject.tp_setattro` from its base type when the " +"subtype's :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject." +"tp_setattro` are both ``NULL``." +msgstr "" + +#: ../../c-api/typeobj.rst:903 +msgid "" +"Pointer to an additional structure that contains fields relevant only to " +"objects which implement :term:`awaitable` and :term:`asynchronous iterator` " +"protocols at the C-level. See :ref:`async-structs` for details." +msgstr "" + +#: ../../c-api/typeobj.rst:907 +msgid "Formerly known as ``tp_compare`` and ``tp_reserved``." +msgstr "以前稱為 ``tp_compare`` 和 ``tp_reserved``。" + +#: ../../c-api/typeobj.rst:912 +msgid "" +"The :c:member:`~PyTypeObject.tp_as_async` field is not inherited, but the " +"contained fields are inherited individually." +msgstr "" + +#: ../../c-api/typeobj.rst:922 +msgid "" +"An optional pointer to a function that implements the built-in function :" +"func:`repr`." +msgstr "" + +#: ../../c-api/typeobj.rst:925 +msgid "The signature is the same as for :c:func:`PyObject_Repr`::" +msgstr "函式簽名與 :c:func:`PyObject_Repr` 相同： ::" + +#: ../../c-api/typeobj.rst:927 +msgid "PyObject *tp_repr(PyObject *self);" +msgstr "PyObject *tp_repr(PyObject *self);" + +#: ../../c-api/typeobj.rst:929 +msgid "" +"The function must return a string or a Unicode object. Ideally, this " +"function should return a string that, when passed to :func:`eval`, given a " +"suitable environment, returns an object with the same value. If this is not " +"feasible, it should return a string starting with ``'<'`` and ending with " +"``'>'`` from which both the type and the value of the object can be deduced." +msgstr "" + +#: ../../c-api/typeobj.rst:940 ../../c-api/typeobj.rst:1021 +#: ../../c-api/typeobj.rst:1062 ../../c-api/typeobj.rst:1089 +#: ../../c-api/typeobj.rst:1117 ../../c-api/typeobj.rst:1159 +#: ../../c-api/typeobj.rst:1807 ../../c-api/typeobj.rst:1841 +#: ../../c-api/typeobj.rst:1970 ../../c-api/typeobj.rst:2003 +#: ../../c-api/typeobj.rst:2082 ../../c-api/typeobj.rst:2125 +#: ../../c-api/typeobj.rst:2147 ../../c-api/typeobj.rst:2188 +#: ../../c-api/typeobj.rst:2218 ../../c-api/typeobj.rst:2251 +msgid "**Default:**" +msgstr "**預設：**" + +#: ../../c-api/typeobj.rst:942 +msgid "" +"When this field is not set, a string of the form ``<%s object at %p>`` is " +"returned, where ``%s`` is replaced by the type name, and ``%p`` by the " +"object's memory address." +msgstr "" + +#: ../../c-api/typeobj.rst:949 +msgid "" +"Pointer to an additional structure that contains fields relevant only to " +"objects which implement the number protocol. These fields are documented " +"in :ref:`number-structs`." +msgstr "" + +#: ../../c-api/typeobj.rst:955 +msgid "" +"The :c:member:`~PyTypeObject.tp_as_number` field is not inherited, but the " +"contained fields are inherited individually." +msgstr "" + +#: ../../c-api/typeobj.rst:961 +msgid "" +"Pointer to an additional structure that contains fields relevant only to " +"objects which implement the sequence protocol. These fields are documented " +"in :ref:`sequence-structs`." +msgstr "" + +#: ../../c-api/typeobj.rst:967 +msgid "" +"The :c:member:`~PyTypeObject.tp_as_sequence` field is not inherited, but the " +"contained fields are inherited individually." +msgstr "" + +#: ../../c-api/typeobj.rst:973 +msgid "" +"Pointer to an additional structure that contains fields relevant only to " +"objects which implement the mapping protocol. These fields are documented " +"in :ref:`mapping-structs`." +msgstr "" + +#: ../../c-api/typeobj.rst:979 +msgid "" +"The :c:member:`~PyTypeObject.tp_as_mapping` field is not inherited, but the " +"contained fields are inherited individually." +msgstr "" + +#: ../../c-api/typeobj.rst:989 +msgid "" +"An optional pointer to a function that implements the built-in function :" +"func:`hash`." +msgstr "" + +#: ../../c-api/typeobj.rst:992 +msgid "The signature is the same as for :c:func:`PyObject_Hash`::" +msgstr "函式簽名與 :c:func:`PyObject_Hash` 相同： ::" + +#: ../../c-api/typeobj.rst:994 +msgid "Py_hash_t tp_hash(PyObject *);" +msgstr "Py_hash_t tp_hash(PyObject *);" + +#: ../../c-api/typeobj.rst:996 +msgid "" +"The value ``-1`` should not be returned as a normal return value; when an " +"error occurs during the computation of the hash value, the function should " +"set an exception and return ``-1``." +msgstr "" + +#: ../../c-api/typeobj.rst:1000 +msgid "" +"When this field is not set (*and* :c:member:`~PyTypeObject.tp_richcompare` " +"is not set), an attempt to take the hash of the object raises :exc:" +"`TypeError`. This is the same as setting it to :c:func:" +"`PyObject_HashNotImplemented`." +msgstr "" + +#: ../../c-api/typeobj.rst:1004 +msgid "" +"This field can be set explicitly to :c:func:`PyObject_HashNotImplemented` to " +"block inheritance of the hash method from a parent type. This is interpreted " +"as the equivalent of ``__hash__ = None`` at the Python level, causing " +"``isinstance(o, collections.Hashable)`` to correctly return ``False``. Note " +"that the converse is also true - setting ``__hash__ = None`` on a class at " +"the Python level will result in the ``tp_hash`` slot being set to :c:func:" +"`PyObject_HashNotImplemented`." +msgstr "" + +#: ../../c-api/typeobj.rst:1014 ../../c-api/typeobj.rst:1800 +msgid "" +"Group: :c:member:`~PyTypeObject.tp_hash`, :c:member:`~PyTypeObject." +"tp_richcompare`" +msgstr "" +"群組：:c:member:`~PyTypeObject.tp_hash`、:c:member:`~PyTypeObject." +"tp_richcompare`" + +#: ../../c-api/typeobj.rst:1016 +msgid "" +"This field is inherited by subtypes together with :c:member:`~PyTypeObject." +"tp_richcompare`: a subtype inherits both of :c:member:`~PyTypeObject." +"tp_richcompare` and :c:member:`~PyTypeObject.tp_hash`, when the subtype's :c:" +"member:`~PyTypeObject.tp_richcompare` and :c:member:`~PyTypeObject.tp_hash` " +"are both ``NULL``." +msgstr "" + +#: ../../c-api/typeobj.rst:1023 +msgid ":c:data:`PyBaseObject_Type` uses :c:func:`PyObject_GenericHash`." +msgstr ":c:data:`PyBaseObject_Type` 會使用 :c:func:`PyObject_GenericHash`。" + +#: ../../c-api/typeobj.rst:1030 +msgid "" +"An optional pointer to a function that implements calling the object. This " +"should be ``NULL`` if the object is not callable. The signature is the same " +"as for :c:func:`PyObject_Call`::" +msgstr "" + +#: ../../c-api/typeobj.rst:1034 +msgid "PyObject *tp_call(PyObject *self, PyObject *args, PyObject *kwargs);" +msgstr "PyObject *tp_call(PyObject *self, PyObject *args, PyObject *kwargs);" + +#: ../../c-api/typeobj.rst:1045 +msgid "" +"An optional pointer to a function that implements the built-in operation :" +"func:`str`. (Note that :class:`str` is a type now, and :func:`str` calls " +"the constructor for that type. This constructor calls :c:func:" +"`PyObject_Str` to do the actual work, and :c:func:`PyObject_Str` will call " +"this handler.)" +msgstr "" + +#: ../../c-api/typeobj.rst:1050 +msgid "The signature is the same as for :c:func:`PyObject_Str`::" +msgstr "函式簽名與 :c:func:`PyObject_Str` 相同： ::" + +#: ../../c-api/typeobj.rst:1052 +msgid "PyObject *tp_str(PyObject *self);" +msgstr "PyObject *tp_str(PyObject *self);" + +#: ../../c-api/typeobj.rst:1054 +msgid "" +"The function must return a string or a Unicode object. It should be a " +"\"friendly\" string representation of the object, as this is the " +"representation that will be used, among other things, by the :func:`print` " +"function." +msgstr "" + +#: ../../c-api/typeobj.rst:1064 +msgid "" +"When this field is not set, :c:func:`PyObject_Repr` is called to return a " +"string representation." +msgstr "" + +#: ../../c-api/typeobj.rst:1072 +msgid "An optional pointer to the get-attribute function." +msgstr "" + +#: ../../c-api/typeobj.rst:1074 +msgid "The signature is the same as for :c:func:`PyObject_GetAttr`::" +msgstr "函式簽名與 :c:func:`PyObject_GetAttr` 相同： ::" + +#: ../../c-api/typeobj.rst:1076 +msgid "PyObject *tp_getattro(PyObject *self, PyObject *attr);" +msgstr "PyObject *tp_getattro(PyObject *self, PyObject *attr);" + +#: ../../c-api/typeobj.rst:1078 +msgid "" +"It is usually convenient to set this field to :c:func:" +"`PyObject_GenericGetAttr`, which implements the normal way of looking for " +"object attributes." +msgstr "" + +#: ../../c-api/typeobj.rst:1085 +msgid "" +"This field is inherited by subtypes together with :c:member:`~PyTypeObject." +"tp_getattr`: a subtype inherits both :c:member:`~PyTypeObject.tp_getattr` " +"and :c:member:`~PyTypeObject.tp_getattro` from its base type when the " +"subtype's :c:member:`~PyTypeObject.tp_getattr` and :c:member:`~PyTypeObject." +"tp_getattro` are both ``NULL``." +msgstr "" + +#: ../../c-api/typeobj.rst:1091 +msgid ":c:data:`PyBaseObject_Type` uses :c:func:`PyObject_GenericGetAttr`." +msgstr ":c:data:`PyBaseObject_Type` 會使用 :c:func:`PyObject_GenericGetAttr`。" + +#: ../../c-api/typeobj.rst:1100 +msgid "The signature is the same as for :c:func:`PyObject_SetAttr`::" +msgstr "函式簽名與 :c:func:`PyObject_SetAttr` 相同： ::" + +#: ../../c-api/typeobj.rst:1102 +msgid "int tp_setattro(PyObject *self, PyObject *attr, PyObject *value);" +msgstr "int tp_setattro(PyObject *self, PyObject *attr, PyObject *value);" + +#: ../../c-api/typeobj.rst:1104 +msgid "" +"In addition, setting *value* to ``NULL`` to delete an attribute must be " +"supported. It is usually convenient to set this field to :c:func:" +"`PyObject_GenericSetAttr`, which implements the normal way of setting object " +"attributes." +msgstr "" + +#: ../../c-api/typeobj.rst:1113 +msgid "" +"This field is inherited by subtypes together with :c:member:`~PyTypeObject." +"tp_setattr`: a subtype inherits both :c:member:`~PyTypeObject.tp_setattr` " +"and :c:member:`~PyTypeObject.tp_setattro` from its base type when the " +"subtype's :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject." +"tp_setattro` are both ``NULL``." +msgstr "" + +#: ../../c-api/typeobj.rst:1119 +msgid ":c:data:`PyBaseObject_Type` uses :c:func:`PyObject_GenericSetAttr`." +msgstr "" + +#: ../../c-api/typeobj.rst:1124 +msgid "" +"Pointer to an additional structure that contains fields relevant only to " +"objects which implement the buffer interface. These fields are documented " +"in :ref:`buffer-structs`." +msgstr "" + +#: ../../c-api/typeobj.rst:1130 +msgid "" +"The :c:member:`~PyTypeObject.tp_as_buffer` field is not inherited, but the " +"contained fields are inherited individually." +msgstr "" + +#: ../../c-api/typeobj.rst:1136 +msgid "" +"This field is a bit mask of various flags. Some flags indicate variant " +"semantics for certain situations; others are used to indicate that certain " +"fields in the type object (or in the extension structures referenced via :c:" +"member:`~PyTypeObject.tp_as_number`, :c:member:`~PyTypeObject." +"tp_as_sequence`, :c:member:`~PyTypeObject.tp_as_mapping`, and :c:member:" +"`~PyTypeObject.tp_as_buffer`) that were historically not always present are " +"valid; if such a flag bit is clear, the type fields it guards must not be " +"accessed and must be considered to have a zero or ``NULL`` value instead." +msgstr "" + +#: ../../c-api/typeobj.rst:1146 +msgid "" +"Inheritance of this field is complicated. Most flag bits are inherited " +"individually, i.e. if the base type has a flag bit set, the subtype inherits " +"this flag bit. The flag bits that pertain to extension structures are " +"strictly inherited if the extension structure is inherited, i.e. the base " +"type's value of the flag bit is copied into the subtype together with a " +"pointer to the extension structure. The :c:macro:`Py_TPFLAGS_HAVE_GC` flag " +"bit is inherited together with the :c:member:`~PyTypeObject.tp_traverse` " +"and :c:member:`~PyTypeObject.tp_clear` fields, i.e. if the :c:macro:" +"`Py_TPFLAGS_HAVE_GC` flag bit is clear in the subtype and the :c:member:" +"`~PyTypeObject.tp_traverse` and :c:member:`~PyTypeObject.tp_clear` fields in " +"the subtype exist and have ``NULL`` values." +msgstr "" + +#: ../../c-api/typeobj.rst:1161 +msgid "" +":c:data:`PyBaseObject_Type` uses ``Py_TPFLAGS_DEFAULT | " +"Py_TPFLAGS_BASETYPE``." +msgstr "" +":c:data:`PyBaseObject_Type` 使用 ``Py_TPFLAGS_DEFAULT | " +"Py_TPFLAGS_BASETYPE``。" + +#: ../../c-api/typeobj.rst:1164 +msgid "**Bit Masks:**" +msgstr "" + +#: ../../c-api/typeobj.rst:1168 +msgid "" +"The following bit masks are currently defined; these can be ORed together " +"using the ``|`` operator to form the value of the :c:member:`~PyTypeObject." +"tp_flags` field. The macro :c:func:`PyType_HasFeature` takes a type and a " +"flags value, *tp* and *f*, and checks whether ``tp->tp_flags & f`` is non-" +"zero." +msgstr "" + +#: ../../c-api/typeobj.rst:1175 +msgid "" +"This bit is set when the type object itself is allocated on the heap, for " +"example, types created dynamically using :c:func:`PyType_FromSpec`. In this " +"case, the :c:member:`~PyObject.ob_type` field of its instances is considered " +"a reference to the type, and the type object is INCREF'ed when a new " +"instance is created, and DECREF'ed when an instance is destroyed (this does " +"not apply to instances of subtypes; only the type referenced by the " +"instance's ob_type gets INCREF'ed or DECREF'ed). Heap types should also :ref:" +"`support garbage collection ` as they can form a " +"reference cycle with their own module object." +msgstr "" + +#: ../../c-api/typeobj.rst:1186 ../../c-api/typeobj.rst:1197 +#: ../../c-api/typeobj.rst:1207 ../../c-api/typeobj.rst:1217 +#: ../../c-api/typeobj.rst:1249 +msgid "???" +msgstr "???" + +#: ../../c-api/typeobj.rst:1191 +msgid "" +"This bit is set when the type can be used as the base type of another type. " +"If this bit is clear, the type cannot be subtyped (similar to a \"final\" " +"class in Java)." +msgstr "" + +#: ../../c-api/typeobj.rst:1202 +msgid "" +"This bit is set when the type object has been fully initialized by :c:func:" +"`PyType_Ready`." +msgstr "" + +#: ../../c-api/typeobj.rst:1212 +msgid "" +"This bit is set while :c:func:`PyType_Ready` is in the process of " +"initializing the type object." +msgstr "" + +#: ../../c-api/typeobj.rst:1222 +msgid "" +"This bit is set when the object supports garbage collection. If this bit is " +"set, memory for new instances (see :c:member:`~PyTypeObject.tp_alloc`) must " +"be allocated using :c:macro:`PyObject_GC_New` or :c:func:" +"`PyType_GenericAlloc` and deallocated (see :c:member:`~PyTypeObject." +"tp_free`) using :c:func:`PyObject_GC_Del`. More information in section :ref:" +"`supporting-cycle-detection`." +msgstr "" + +#: ../../c-api/typeobj.rst:1231 ../../c-api/typeobj.rst:1587 +#: ../../c-api/typeobj.rst:1733 +msgid "" +"Group: :c:macro:`Py_TPFLAGS_HAVE_GC`, :c:member:`~PyTypeObject." +"tp_traverse`, :c:member:`~PyTypeObject.tp_clear`" +msgstr "" + +#: ../../c-api/typeobj.rst:1233 +msgid "" +"The :c:macro:`Py_TPFLAGS_HAVE_GC` flag bit is inherited together with the :c:" +"member:`~PyTypeObject.tp_traverse` and :c:member:`~PyTypeObject.tp_clear` " +"fields, i.e. if the :c:macro:`Py_TPFLAGS_HAVE_GC` flag bit is clear in the " +"subtype and the :c:member:`~PyTypeObject.tp_traverse` and :c:member:" +"`~PyTypeObject.tp_clear` fields in the subtype exist and have ``NULL`` " +"values." +msgstr "" + +#: ../../c-api/typeobj.rst:1243 +msgid "" +"This is a bitmask of all the bits that pertain to the existence of certain " +"fields in the type object and its extension structures. Currently, it " +"includes the following bits: :c:macro:`Py_TPFLAGS_HAVE_STACKLESS_EXTENSION`." +msgstr "" + +#: ../../c-api/typeobj.rst:1254 +msgid "This bit indicates that objects behave like unbound methods." +msgstr "" + +#: ../../c-api/typeobj.rst:1256 +msgid "If this flag is set for ``type(meth)``, then:" +msgstr "如果此旗標為 ``type(meth)`` 所設定，則：" + +#: ../../c-api/typeobj.rst:1258 +msgid "" +"``meth.__get__(obj, cls)(*args, **kwds)`` (with ``obj`` not None) must be " +"equivalent to ``meth(obj, *args, **kwds)``." +msgstr "" +"``meth.__get__(obj, cls)(*args, **kwds)``\\（其中 ``obj`` 並非 None）必須等價" +"於 ``meth(obj, *args, **kwds)``。" + +#: ../../c-api/typeobj.rst:1261 +msgid "" +"``meth.__get__(None, cls)(*args, **kwds)`` must be equivalent to " +"``meth(*args, **kwds)``." +msgstr "" +"``meth.__get__(None, cls)(*args, **kwds)`` 必須等價於 ``meth(*args, " +"**kwds)``。" + +#: ../../c-api/typeobj.rst:1264 +msgid "" +"This flag enables an optimization for typical method calls like ``obj." +"meth()``: it avoids creating a temporary \"bound method\" object for ``obj." +"meth``." +msgstr "" + +#: ../../c-api/typeobj.rst:1272 +msgid "" +"This flag is never inherited by types without the :c:macro:" +"`Py_TPFLAGS_IMMUTABLETYPE` flag set. For extension types, it is inherited " +"whenever :c:member:`~PyTypeObject.tp_descr_get` is inherited." +msgstr "" + +#: ../../c-api/typeobj.rst:1278 +msgid "" +"This bit indicates that instances of the class have a :attr:`~object." +"__dict__` attribute, and that the space for the dictionary is managed by the " +"VM." +msgstr "" + +#: ../../c-api/typeobj.rst:1281 +msgid "If this flag is set, :c:macro:`Py_TPFLAGS_HAVE_GC` should also be set." +msgstr "如果有設定此旗標，則也應該設定 :c:macro:`Py_TPFLAGS_HAVE_GC`。" + +#: ../../c-api/typeobj.rst:1283 +msgid "" +"The type traverse function must call :c:func:`PyObject_VisitManagedDict` and " +"its clear function must call :c:func:`PyObject_ClearManagedDict`." +msgstr "" + +#: ../../c-api/typeobj.rst:1290 +msgid "" +"This flag is inherited unless the :c:member:`~PyTypeObject.tp_dictoffset` " +"field is set in a superclass." +msgstr "" + +#: ../../c-api/typeobj.rst:1296 +msgid "" +"This bit indicates that instances of the class should be weakly " +"referenceable." +msgstr "" + +#: ../../c-api/typeobj.rst:1303 +msgid "" +"This flag is inherited unless the :c:member:`~PyTypeObject." +"tp_weaklistoffset` field is set in a superclass." +msgstr "" + +#: ../../c-api/typeobj.rst:1309 +msgid "" +"Only usable with variable-size types, i.e. ones with non-zero :c:member:" +"`~PyTypeObject.tp_itemsize`." +msgstr "" + +#: ../../c-api/typeobj.rst:1312 +msgid "" +"Indicates that the variable-sized portion of an instance of this type is at " +"the end of the instance's memory area, at an offset of ``Py_TYPE(obj)-" +">tp_basicsize`` (which may be different in each subclass)." +msgstr "" + +#: ../../c-api/typeobj.rst:1317 +msgid "" +"When setting this flag, be sure that all superclasses either use this memory " +"layout, or are not variable-sized. Python does not check this." +msgstr "" + +#: ../../c-api/typeobj.rst:1325 +msgid "This flag is inherited." +msgstr "" + +#: ../../c-api/typeobj.rst:1339 +msgid "" +"Functions such as :c:func:`PyLong_Check` will call :c:func:" +"`PyType_FastSubclass` with one of these flags to quickly determine if a type " +"is a subclass of a built-in type; such specific checks are faster than a " +"generic check, like :c:func:`PyObject_IsInstance`. Custom types that inherit " +"from built-ins should have their :c:member:`~PyTypeObject.tp_flags` set " +"appropriately, or the code that interacts with such types will behave " +"differently depending on what kind of check is used." +msgstr "" + +#: ../../c-api/typeobj.rst:1350 +msgid "" +"This bit is set when the :c:member:`~PyTypeObject.tp_finalize` slot is " +"present in the type structure." +msgstr "" + +#: ../../c-api/typeobj.rst:1355 +msgid "" +"This flag isn't necessary anymore, as the interpreter assumes the :c:member:" +"`~PyTypeObject.tp_finalize` slot is always present in the type structure." +msgstr "" + +#: ../../c-api/typeobj.rst:1363 +msgid "" +"This bit is set when the class implements the :ref:`vectorcall protocol " +"`. See :c:member:`~PyTypeObject.tp_vectorcall_offset` for " +"details." +msgstr "" + +#: ../../c-api/typeobj.rst:1369 +msgid "" +"This bit is inherited if :c:member:`~PyTypeObject.tp_call` is also inherited." +msgstr "" + +#: ../../c-api/typeobj.rst:1376 +msgid "" +"This flag is now removed from a class when the class's :py:meth:`~object." +"__call__` method is reassigned." +msgstr "" + +#: ../../c-api/typeobj.rst:1379 +msgid "This flag can now be inherited by mutable classes." +msgstr "" + +#: ../../c-api/typeobj.rst:1383 +msgid "" +"This bit is set for type objects that are immutable: type attributes cannot " +"be set nor deleted." +msgstr "" + +#: ../../c-api/typeobj.rst:1385 +msgid "" +":c:func:`PyType_Ready` automatically applies this flag to :ref:`static types " +"`." +msgstr "" + +#: ../../c-api/typeobj.rst:1390 +msgid "This flag is not inherited." +msgstr "" + +#: ../../c-api/typeobj.rst:1396 +msgid "" +"Disallow creating instances of the type: set :c:member:`~PyTypeObject." +"tp_new` to NULL and don't create the ``__new__`` key in the type dictionary." +msgstr "" + +#: ../../c-api/typeobj.rst:1400 +msgid "" +"The flag must be set before creating the type, not after. For example, it " +"must be set before :c:func:`PyType_Ready` is called on the type." +msgstr "" + +#: ../../c-api/typeobj.rst:1403 +msgid "" +"The flag is set automatically on :ref:`static types ` if :c:" +"member:`~PyTypeObject.tp_base` is NULL or ``&PyBaseObject_Type`` and :c:" +"member:`~PyTypeObject.tp_new` is NULL." +msgstr "" + +#: ../../c-api/typeobj.rst:1409 +msgid "" +"This flag is not inherited. However, subclasses will not be instantiable " +"unless they provide a non-NULL :c:member:`~PyTypeObject.tp_new` (which is " +"only possible via the C API)." +msgstr "" + +#: ../../c-api/typeobj.rst:1416 +msgid "" +"To disallow instantiating a class directly but allow instantiating its " +"subclasses (e.g. for an :term:`abstract base class`), do not use this flag. " +"Instead, make :c:member:`~PyTypeObject.tp_new` only succeed for subclasses." +msgstr "" + +#: ../../c-api/typeobj.rst:1427 +msgid "" +"This bit indicates that instances of the class may match mapping patterns " +"when used as the subject of a :keyword:`match` block. It is automatically " +"set when registering or subclassing :class:`collections.abc.Mapping`, and " +"unset when registering :class:`collections.abc.Sequence`." +msgstr "" + +#: ../../c-api/typeobj.rst:1434 ../../c-api/typeobj.rst:1456 +msgid "" +":c:macro:`Py_TPFLAGS_MAPPING` and :c:macro:`Py_TPFLAGS_SEQUENCE` are " +"mutually exclusive; it is an error to enable both flags simultaneously." +msgstr "" + +#: ../../c-api/typeobj.rst:1439 +msgid "" +"This flag is inherited by types that do not already set :c:macro:" +"`Py_TPFLAGS_SEQUENCE`." +msgstr "" + +#: ../../c-api/typeobj.rst:1442 ../../c-api/typeobj.rst:1464 +msgid ":pep:`634` -- Structural Pattern Matching: Specification" +msgstr "" + +#: ../../c-api/typeobj.rst:1449 +msgid "" +"This bit indicates that instances of the class may match sequence patterns " +"when used as the subject of a :keyword:`match` block. It is automatically " +"set when registering or subclassing :class:`collections.abc.Sequence`, and " +"unset when registering :class:`collections.abc.Mapping`." +msgstr "" + +#: ../../c-api/typeobj.rst:1461 +msgid "" +"This flag is inherited by types that do not already set :c:macro:" +"`Py_TPFLAGS_MAPPING`." +msgstr "" + +#: ../../c-api/typeobj.rst:1471 +msgid "" +"Internal. Do not set or unset this flag. To indicate that a class has " +"changed call :c:func:`PyType_Modified`" +msgstr "" + +#: ../../c-api/typeobj.rst:1475 +msgid "" +"This flag is present in header files, but is not be used. It will be removed " +"in a future version of CPython" +msgstr "" + +#: ../../c-api/typeobj.rst:1483 +msgid "" +"An optional pointer to a NUL-terminated C string giving the docstring for " +"this type object. This is exposed as the :attr:`~type.__doc__` attribute on " +"the type and instances of the type." +msgstr "" + +#: ../../c-api/typeobj.rst:1489 +msgid "This field is *not* inherited by subtypes." +msgstr "此欄位不會被子型別繼承。" + +#: ../../c-api/typeobj.rst:1496 +msgid "" +"An optional pointer to a traversal function for the garbage collector. This " +"is only used if the :c:macro:`Py_TPFLAGS_HAVE_GC` flag bit is set. The " +"signature is::" +msgstr "" + +#: ../../c-api/typeobj.rst:1499 +msgid "int tp_traverse(PyObject *self, visitproc visit, void *arg);" +msgstr "int tp_traverse(PyObject *self, visitproc visit, void *arg);" + +#: ../../c-api/typeobj.rst:1501 ../../c-api/typeobj.rst:1728 +msgid "" +"More information about Python's garbage collection scheme can be found in " +"section :ref:`supporting-cycle-detection`." +msgstr "" + +#: ../../c-api/typeobj.rst:1504 +msgid "" +"The :c:member:`~PyTypeObject.tp_traverse` pointer is used by the garbage " +"collector to detect reference cycles. A typical implementation of a :c:" +"member:`~PyTypeObject.tp_traverse` function simply calls :c:func:`Py_VISIT` " +"on each of the instance's members that are Python objects that the instance " +"owns. For example, this is function :c:func:`!local_traverse` from the :mod:" +"`!_thread` extension module::" +msgstr "" + +#: ../../c-api/typeobj.rst:1510 +msgid "" +"static int\n" +"local_traverse(PyObject *op, visitproc visit, void *arg)\n" +"{\n" +" localobject *self = (localobject *) op;\n" +" Py_VISIT(self->args);\n" +" Py_VISIT(self->kw);\n" +" Py_VISIT(self->dict);\n" +" return 0;\n" +"}" +msgstr "" +"static int\n" +"local_traverse(PyObject *op, visitproc visit, void *arg)\n" +"{\n" +" localobject *self = (localobject *) op;\n" +" Py_VISIT(self->args);\n" +" Py_VISIT(self->kw);\n" +" Py_VISIT(self->dict);\n" +" return 0;\n" +"}" + +#: ../../c-api/typeobj.rst:1520 +msgid "" +"Note that :c:func:`Py_VISIT` is called only on those members that can " +"participate in reference cycles. Although there is also a ``self->key`` " +"member, it can only be ``NULL`` or a Python string and therefore cannot be " +"part of a reference cycle." +msgstr "" + +#: ../../c-api/typeobj.rst:1524 +msgid "" +"On the other hand, even if you know a member can never be part of a cycle, " +"as a debugging aid you may want to visit it anyway just so the :mod:`gc` " +"module's :func:`~gc.get_referents` function will include it." +msgstr "" + +#: ../../c-api/typeobj.rst:1528 +msgid "" +"Heap types (:c:macro:`Py_TPFLAGS_HEAPTYPE`) must visit their type with::" +msgstr "" + +#: ../../c-api/typeobj.rst:1530 +msgid "Py_VISIT(Py_TYPE(self));" +msgstr "Py_VISIT(Py_TYPE(self));" + +#: ../../c-api/typeobj.rst:1532 +msgid "" +"It is only needed since Python 3.9. To support Python 3.8 and older, this " +"line must be conditional::" +msgstr "" + +#: ../../c-api/typeobj.rst:1535 +msgid "" +"#if PY_VERSION_HEX >= 0x03090000\n" +" Py_VISIT(Py_TYPE(self));\n" +"#endif" +msgstr "" +"#if PY_VERSION_HEX >= 0x03090000\n" +" Py_VISIT(Py_TYPE(self));\n" +"#endif" + +#: ../../c-api/typeobj.rst:1539 +msgid "" +"If the :c:macro:`Py_TPFLAGS_MANAGED_DICT` bit is set in the :c:member:" +"`~PyTypeObject.tp_flags` field, the traverse function must call :c:func:" +"`PyObject_VisitManagedDict` like this::" +msgstr "" + +#: ../../c-api/typeobj.rst:1543 +msgid "PyObject_VisitManagedDict((PyObject*)self, visit, arg);" +msgstr "PyObject_VisitManagedDict((PyObject*)self, visit, arg);" + +#: ../../c-api/typeobj.rst:1546 +msgid "" +"When implementing :c:member:`~PyTypeObject.tp_traverse`, only the members " +"that the instance *owns* (by having :term:`strong references ` to them) must be visited. For instance, if an object supports " +"weak references via the :c:member:`~PyTypeObject.tp_weaklist` slot, the " +"pointer supporting the linked list (what *tp_weaklist* points to) must " +"**not** be visited as the instance does not directly own the weak references " +"to itself (the weakreference list is there to support the weak reference " +"machinery, but the instance has no strong reference to the elements inside " +"it, as they are allowed to be removed even if the instance is still alive)." +msgstr "" + +#: ../../c-api/typeobj.rst:1558 +msgid "" +"The traversal function must not have any side effects. It must not modify " +"the reference counts of any Python objects nor create or destroy any Python " +"objects." +msgstr "" + +#: ../../c-api/typeobj.rst:1562 +msgid "" +"Note that :c:func:`Py_VISIT` requires the *visit* and *arg* parameters to :c:" +"func:`!local_traverse` to have these specific names; don't name them just " +"anything." +msgstr "" + +#: ../../c-api/typeobj.rst:1566 +msgid "" +"Instances of :ref:`heap-allocated types ` hold a reference to " +"their type. Their traversal function must therefore either visit :c:func:" +"`Py_TYPE(self) `, or delegate this responsibility by calling " +"``tp_traverse`` of another heap-allocated type (such as a heap-allocated " +"superclass). If they do not, the type object may not be garbage-collected." +msgstr "" + +#: ../../c-api/typeobj.rst:1575 +msgid "" +"The :c:member:`~PyTypeObject.tp_traverse` function can be called from any " +"thread." +msgstr ":c:member:`~PyTypeObject.tp_traverse` 函式可以從任何執行緒呼叫。" + +#: ../../c-api/typeobj.rst:1580 +msgid "" +"Heap-allocated types are expected to visit ``Py_TYPE(self)`` in " +"``tp_traverse``. In earlier versions of Python, due to `bug 40217 `_, doing this may lead to crashes in subclasses." +msgstr "" + +#: ../../c-api/typeobj.rst:1589 +msgid "" +"This field is inherited by subtypes together with :c:member:`~PyTypeObject." +"tp_clear` and the :c:macro:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :c:" +"member:`~PyTypeObject.tp_traverse`, and :c:member:`~PyTypeObject.tp_clear` " +"are all inherited from the base type if they are all zero in the subtype." +msgstr "" + +#: ../../c-api/typeobj.rst:1599 +msgid "An optional pointer to a clear function. The signature is::" +msgstr "" + +#: ../../c-api/typeobj.rst:1601 +msgid "int tp_clear(PyObject *);" +msgstr "int tp_clear(PyObject *);" + +#: ../../c-api/typeobj.rst:1603 +msgid "" +"The purpose of this function is to break reference cycles that are causing " +"a :term:`cyclic isolate` so that the objects can be safely destroyed. A " +"cleared object is a partially destroyed object; the object is not obligated " +"to satisfy design invariants held during normal use." +msgstr "" + +#: ../../c-api/typeobj.rst:1608 +msgid "" +":c:member:`!tp_clear` does not need to delete references to objects that " +"can't participate in reference cycles, such as Python strings or Python " +"integers. However, it may be convenient to clear all references, and write " +"the type's :c:member:`~PyTypeObject.tp_dealloc` function to invoke :c:member:" +"`!tp_clear` to avoid code duplication. (Beware that :c:member:`!tp_clear` " +"might have already been called. Prefer calling idempotent functions like :c:" +"func:`Py_CLEAR`.)" +msgstr "" + +#: ../../c-api/typeobj.rst:1616 +msgid "" +"Any non-trivial cleanup should be performed in :c:member:`~PyTypeObject." +"tp_finalize` instead of :c:member:`!tp_clear`." +msgstr "" + +#: ../../c-api/typeobj.rst:1621 +msgid "" +"If :c:member:`!tp_clear` fails to break a reference cycle then the objects " +"in the :term:`cyclic isolate` may remain indefinitely uncollectable " +"(\"leak\"). See :data:`gc.garbage`." +msgstr "" + +#: ../../c-api/typeobj.rst:1627 +msgid "" +"Referents (direct and indirect) might have already been cleared; they are " +"not guaranteed to be in a consistent state." +msgstr "" + +#: ../../c-api/typeobj.rst:1632 +msgid "" +"The :c:member:`~PyTypeObject.tp_clear` function can be called from any " +"thread." +msgstr ":c:member:`~PyTypeObject.tp_clear` 函式可以從任何執行緒呼叫。" + +#: ../../c-api/typeobj.rst:1637 +msgid "" +"An object is not guaranteed to be automatically cleared before its " +"destructor (:c:member:`~PyTypeObject.tp_dealloc`) is called." +msgstr "" + +#: ../../c-api/typeobj.rst:1640 +msgid "" +"This function differs from the destructor (:c:member:`~PyTypeObject." +"tp_dealloc`) in the following ways:" +msgstr "" + +#: ../../c-api/typeobj.rst:1643 +msgid "" +"The purpose of clearing an object is to remove references to other objects " +"that might participate in a reference cycle. The purpose of the destructor, " +"on the other hand, is a superset: it must release *all* resources it owns, " +"including references to objects that cannot participate in a reference cycle " +"(e.g., integers) as well as the object's own memory (by calling :c:member:" +"`~PyTypeObject.tp_free`)." +msgstr "" + +#: ../../c-api/typeobj.rst:1649 +msgid "" +"When :c:member:`!tp_clear` is called, other objects might still hold " +"references to the object being cleared. Because of this, :c:member:`!" +"tp_clear` must not deallocate the object's own memory (:c:member:" +"`~PyTypeObject.tp_free`). The destructor, on the other hand, is only called " +"when no (strong) references exist, and as such, must safely destroy the " +"object itself by deallocating it." +msgstr "" + +#: ../../c-api/typeobj.rst:1655 +msgid "" +":c:member:`!tp_clear` might never be automatically called. An object's " +"destructor, on the other hand, will be automatically called some time after " +"the object becomes unreachable (i.e., either there are no references to the " +"object or the object is a member of a :term:`cyclic isolate`)." +msgstr "" + +#: ../../c-api/typeobj.rst:1660 +msgid "" +"No guarantees are made about when, if, or how often Python automatically " +"clears an object, except:" +msgstr "" + +#: ../../c-api/typeobj.rst:1663 +msgid "" +"Python will not automatically clear an object if it is reachable, i.e., " +"there is a reference to it and it is not a member of a :term:`cyclic " +"isolate`." +msgstr "" + +#: ../../c-api/typeobj.rst:1666 +msgid "" +"Python will not automatically clear an object if it has not been " +"automatically finalized (see :c:member:`~PyTypeObject.tp_finalize`). (If " +"the finalizer resurrected the object, the object may or may not be " +"automatically finalized again before it is cleared.)" +msgstr "" + +#: ../../c-api/typeobj.rst:1670 +msgid "" +"If an object is a member of a :term:`cyclic isolate`, Python will not " +"automatically clear it if any member of the cyclic isolate has not yet been " +"automatically finalized (:c:member:`~PyTypeObject.tp_finalize`)." +msgstr "" + +#: ../../c-api/typeobj.rst:1673 +msgid "" +"Python will not destroy an object until after any automatic calls to its :c:" +"member:`!tp_clear` function have returned. This ensures that the act of " +"breaking a reference cycle does not invalidate the ``self`` pointer while :c:" +"member:`!tp_clear` is still executing." +msgstr "" + +#: ../../c-api/typeobj.rst:1677 +msgid "" +"Python will not automatically call :c:member:`!tp_clear` multiple times " +"concurrently." +msgstr "" + +#: ../../c-api/typeobj.rst:1680 +msgid "" +"CPython currently only automatically clears objects as needed to break " +"reference cycles in a :term:`cyclic isolate`, but future versions might " +"clear objects regularly before their destruction." +msgstr "" + +#: ../../c-api/typeobj.rst:1684 +msgid "" +"Taken together, all :c:member:`~PyTypeObject.tp_clear` functions in the " +"system must combine to break all reference cycles. This is subtle, and if " +"in any doubt supply a :c:member:`~PyTypeObject.tp_clear` function. For " +"example, the tuple type does not implement a :c:member:`~PyTypeObject." +"tp_clear` function, because it's possible to prove that no reference cycle " +"can be composed entirely of tuples. Therefore the :c:member:`~PyTypeObject." +"tp_clear` functions of other types are responsible for breaking any cycle " +"containing a tuple. This isn't immediately obvious, and there's rarely a " +"good reason to avoid implementing :c:member:`~PyTypeObject.tp_clear`." +msgstr "" + +#: ../../c-api/typeobj.rst:1695 +msgid "" +"Implementations of :c:member:`~PyTypeObject.tp_clear` should drop the " +"instance's references to those of its members that may be Python objects, " +"and set its pointers to those members to ``NULL``, as in the following " +"example::" +msgstr "" + +#: ../../c-api/typeobj.rst:1699 +msgid "" +"static int\n" +"local_clear(PyObject *op)\n" +"{\n" +" localobject *self = (localobject *) op;\n" +" Py_CLEAR(self->key);\n" +" Py_CLEAR(self->args);\n" +" Py_CLEAR(self->kw);\n" +" Py_CLEAR(self->dict);\n" +" return 0;\n" +"}" +msgstr "" +"static int\n" +"local_clear(PyObject *op)\n" +"{\n" +" localobject *self = (localobject *) op;\n" +" Py_CLEAR(self->key);\n" +" Py_CLEAR(self->args);\n" +" Py_CLEAR(self->kw);\n" +" Py_CLEAR(self->dict);\n" +" return 0;\n" +"}" + +#: ../../c-api/typeobj.rst:1710 +msgid "" +"The :c:func:`Py_CLEAR` macro should be used, because clearing references is " +"delicate: the reference to the contained object must not be released (via :" +"c:func:`Py_DECREF`) until after the pointer to the contained object is set " +"to ``NULL``. This is because releasing the reference may cause the " +"contained object to become trash, triggering a chain of reclamation activity " +"that may include invoking arbitrary Python code (due to finalizers, or " +"weakref callbacks, associated with the contained object). If it's possible " +"for such code to reference *self* again, it's important that the pointer to " +"the contained object be ``NULL`` at that time, so that *self* knows the " +"contained object can no longer be used. The :c:func:`Py_CLEAR` macro " +"performs the operations in a safe order." +msgstr "" + +#: ../../c-api/typeobj.rst:1722 +msgid "" +"If the :c:macro:`Py_TPFLAGS_MANAGED_DICT` bit is set in the :c:member:" +"`~PyTypeObject.tp_flags` field, the clear function must call :c:func:" +"`PyObject_ClearManagedDict` like this::" +msgstr "" + +#: ../../c-api/typeobj.rst:1726 +msgid "PyObject_ClearManagedDict((PyObject*)self);" +msgstr "PyObject_ClearManagedDict((PyObject*)self);" + +#: ../../c-api/typeobj.rst:1735 +msgid "" +"This field is inherited by subtypes together with :c:member:`~PyTypeObject." +"tp_traverse` and the :c:macro:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :" +"c:member:`~PyTypeObject.tp_traverse`, and :c:member:`~PyTypeObject.tp_clear` " +"are all inherited from the base type if they are all zero in the subtype." +msgstr "" + +#: ../../c-api/typeobj.rst:1749 +msgid "" +"An optional pointer to the rich comparison function, whose signature is::" +msgstr "" + +#: ../../c-api/typeobj.rst:1751 +msgid "PyObject *tp_richcompare(PyObject *self, PyObject *other, int op);" +msgstr "PyObject *tp_richcompare(PyObject *self, PyObject *other, int op);" + +#: ../../c-api/typeobj.rst:1753 +msgid "" +"The first parameter is guaranteed to be an instance of the type that is " +"defined by :c:type:`PyTypeObject`." +msgstr "" + +#: ../../c-api/typeobj.rst:1756 +msgid "" +"The function should return the result of the comparison (usually ``Py_True`` " +"or ``Py_False``). If the comparison is undefined, it must return " +"``Py_NotImplemented``, if another error occurred it must return ``NULL`` and " +"set an exception condition." +msgstr "" + +#: ../../c-api/typeobj.rst:1761 +msgid "" +"The following constants are defined to be used as the third argument for :c:" +"member:`~PyTypeObject.tp_richcompare` and for :c:func:`PyObject_RichCompare`:" +msgstr "" + +#: ../../c-api/typeobj.rst:1767 +msgid "Constant" +msgstr "常數" + +#: ../../c-api/typeobj.rst:1767 +msgid "Comparison" +msgstr "" + +#: ../../c-api/typeobj.rst:1769 +msgid "``<``" +msgstr "``<``" + +#: ../../c-api/typeobj.rst:1771 +msgid "``<=``" +msgstr "``<=``" + +#: ../../c-api/typeobj.rst:1773 +msgid "``==``" +msgstr "``==``" + +#: ../../c-api/typeobj.rst:1775 +msgid "``!=``" +msgstr "``!=``" + +#: ../../c-api/typeobj.rst:1777 +msgid "``>``" +msgstr "``>``" + +#: ../../c-api/typeobj.rst:1779 +msgid "``>=``" +msgstr "``>=``" + +#: ../../c-api/typeobj.rst:1782 +msgid "" +"The following macro is defined to ease writing rich comparison functions:" +msgstr "" + +#: ../../c-api/typeobj.rst:1786 +msgid "" +"Return ``Py_True`` or ``Py_False`` from the function, depending on the " +"result of a comparison. VAL_A and VAL_B must be orderable by C comparison " +"operators (for example, they may be C ints or floats). The third argument " +"specifies the requested operation, as for :c:func:`PyObject_RichCompare`." +msgstr "" + +#: ../../c-api/typeobj.rst:1792 +msgid "The returned value is a new :term:`strong reference`." +msgstr "" + +#: ../../c-api/typeobj.rst:1794 +msgid "On error, sets an exception and returns ``NULL`` from the function." +msgstr "" + +#: ../../c-api/typeobj.rst:1802 +msgid "" +"This field is inherited by subtypes together with :c:member:`~PyTypeObject." +"tp_hash`: a subtype inherits :c:member:`~PyTypeObject.tp_richcompare` and :c:" +"member:`~PyTypeObject.tp_hash` when the subtype's :c:member:`~PyTypeObject." +"tp_richcompare` and :c:member:`~PyTypeObject.tp_hash` are both ``NULL``." +msgstr "" + +#: ../../c-api/typeobj.rst:1809 +msgid "" +":c:data:`PyBaseObject_Type` provides a :c:member:`~PyTypeObject." +"tp_richcompare` implementation, which may be inherited. However, if only :c:" +"member:`~PyTypeObject.tp_hash` is defined, not even the inherited function " +"is used and instances of the type will not be able to participate in any " +"comparisons." +msgstr "" + +#: ../../c-api/typeobj.rst:1818 +msgid "" +"While this field is still supported, :c:macro:`Py_TPFLAGS_MANAGED_WEAKREF` " +"should be used instead, if at all possible." +msgstr "" + +#: ../../c-api/typeobj.rst:1821 +msgid "" +"If the instances of this type are weakly referenceable, this field is " +"greater than zero and contains the offset in the instance structure of the " +"weak reference list head (ignoring the GC header, if present); this offset " +"is used by :c:func:`PyObject_ClearWeakRefs` and the ``PyWeakref_*`` " +"functions. The instance structure needs to include a field of type :c:expr:" +"`PyObject*` which is initialized to ``NULL``." +msgstr "" + +#: ../../c-api/typeobj.rst:1828 +msgid "" +"Do not confuse this field with :c:member:`~PyTypeObject.tp_weaklist`; that " +"is the list head for weak references to the type object itself." +msgstr "" + +#: ../../c-api/typeobj.rst:1831 +msgid "" +"It is an error to set both the :c:macro:`Py_TPFLAGS_MANAGED_WEAKREF` bit " +"and :c:member:`~PyTypeObject.tp_weaklistoffset`." +msgstr "" + +#: ../../c-api/typeobj.rst:1836 +msgid "" +"This field is inherited by subtypes, but see the rules listed below. A " +"subtype may override this offset; this means that the subtype uses a " +"different weak reference list head than the base type. Since the list head " +"is always found via :c:member:`~PyTypeObject.tp_weaklistoffset`, this should " +"not be a problem." +msgstr "" + +#: ../../c-api/typeobj.rst:1843 +msgid "" +"If the :c:macro:`Py_TPFLAGS_MANAGED_WEAKREF` bit is set in the :c:member:" +"`~PyTypeObject.tp_flags` field, then :c:member:`~PyTypeObject." +"tp_weaklistoffset` will be set to a negative value, to indicate that it is " +"unsafe to use this field." +msgstr "" + +#: ../../c-api/typeobj.rst:1853 +msgid "" +"An optional pointer to a function that returns an :term:`iterator` for the " +"object. Its presence normally signals that the instances of this type are :" +"term:`iterable` (although sequences may be iterable without this function)." +msgstr "" + +#: ../../c-api/typeobj.rst:1857 +msgid "This function has the same signature as :c:func:`PyObject_GetIter`::" +msgstr "" + +#: ../../c-api/typeobj.rst:1859 +msgid "PyObject *tp_iter(PyObject *self);" +msgstr "PyObject *tp_iter(PyObject *self);" + +#: ../../c-api/typeobj.rst:1870 +msgid "" +"An optional pointer to a function that returns the next item in an :term:" +"`iterator`. The signature is::" +msgstr "" + +#: ../../c-api/typeobj.rst:1873 +msgid "PyObject *tp_iternext(PyObject *self);" +msgstr "PyObject *tp_iternext(PyObject *self);" + +#: ../../c-api/typeobj.rst:1875 +msgid "" +"When the iterator is exhausted, it must return ``NULL``; a :exc:" +"`StopIteration` exception may or may not be set. When another error occurs, " +"it must return ``NULL`` too. Its presence signals that the instances of " +"this type are iterators." +msgstr "" + +#: ../../c-api/typeobj.rst:1880 +msgid "" +"Iterator types should also define the :c:member:`~PyTypeObject.tp_iter` " +"function, and that function should return the iterator instance itself (not " +"a new iterator instance)." +msgstr "" + +#: ../../c-api/typeobj.rst:1884 +msgid "This function has the same signature as :c:func:`PyIter_Next`." +msgstr "" + +#: ../../c-api/typeobj.rst:1895 +msgid "" +"An optional pointer to a static ``NULL``-terminated array of :c:type:" +"`PyMethodDef` structures, declaring regular methods of this type." +msgstr "" + +#: ../../c-api/typeobj.rst:1898 +msgid "" +"For each entry in the array, an entry is added to the type's dictionary " +"(see :c:member:`~PyTypeObject.tp_dict` below) containing a method descriptor." +msgstr "" + +#: ../../c-api/typeobj.rst:1903 +msgid "" +"This field is not inherited by subtypes (methods are inherited through a " +"different mechanism)." +msgstr "" + +#: ../../c-api/typeobj.rst:1911 +msgid "" +"An optional pointer to a static ``NULL``-terminated array of :c:type:" +"`PyMemberDef` structures, declaring regular data members (fields or slots) " +"of instances of this type." +msgstr "" + +#: ../../c-api/typeobj.rst:1915 +msgid "" +"For each entry in the array, an entry is added to the type's dictionary " +"(see :c:member:`~PyTypeObject.tp_dict` below) containing a member descriptor." +msgstr "" + +#: ../../c-api/typeobj.rst:1920 +msgid "" +"This field is not inherited by subtypes (members are inherited through a " +"different mechanism)." +msgstr "" + +#: ../../c-api/typeobj.rst:1928 +msgid "" +"An optional pointer to a static ``NULL``-terminated array of :c:type:" +"`PyGetSetDef` structures, declaring computed attributes of instances of this " +"type." +msgstr "" + +#: ../../c-api/typeobj.rst:1931 +msgid "" +"For each entry in the array, an entry is added to the type's dictionary " +"(see :c:member:`~PyTypeObject.tp_dict` below) containing a getset descriptor." +msgstr "" + +#: ../../c-api/typeobj.rst:1936 +msgid "" +"This field is not inherited by subtypes (computed attributes are inherited " +"through a different mechanism)." +msgstr "" + +#: ../../c-api/typeobj.rst:1944 +msgid "" +"An optional pointer to a base type from which type properties are " +"inherited. At this level, only single inheritance is supported; multiple " +"inheritance require dynamically creating a type object by calling the " +"metatype." +msgstr "" + +#: ../../c-api/typeobj.rst:1952 +msgid "" +"Slot initialization is subject to the rules of initializing globals. C99 " +"requires the initializers to be \"address constants\". Function designators " +"like :c:func:`PyType_GenericNew`, with implicit conversion to a pointer, are " +"valid C99 address constants." +msgstr "" + +#: ../../c-api/typeobj.rst:1957 +msgid "" +"However, the unary '&' operator applied to a non-static variable like :c:" +"data:`PyBaseObject_Type` is not required to produce an address constant. " +"Compilers may support this (gcc does), MSVC does not. Both compilers are " +"strictly standard conforming in this particular behavior." +msgstr "" + +#: ../../c-api/typeobj.rst:1963 +msgid "" +"Consequently, :c:member:`~PyTypeObject.tp_base` should be set in the " +"extension module's init function." +msgstr "" + +#: ../../c-api/typeobj.rst:1968 +msgid "This field is not inherited by subtypes (obviously)." +msgstr "" + +#: ../../c-api/typeobj.rst:1972 +msgid "" +"This field defaults to ``&PyBaseObject_Type`` (which to Python programmers " +"is known as the type :class:`object`)." +msgstr "" + +#: ../../c-api/typeobj.rst:1978 +msgid "The type's dictionary is stored here by :c:func:`PyType_Ready`." +msgstr "" + +#: ../../c-api/typeobj.rst:1980 +msgid "" +"This field should normally be initialized to ``NULL`` before PyType_Ready is " +"called; it may also be initialized to a dictionary containing initial " +"attributes for the type. Once :c:func:`PyType_Ready` has initialized the " +"type, extra attributes for the type may be added to this dictionary only if " +"they don't correspond to overloaded operations (like :meth:`~object." +"__add__`). Once initialization for the type has finished, this field should " +"be treated as read-only." +msgstr "" + +#: ../../c-api/typeobj.rst:1988 +msgid "" +"Some types may not store their dictionary in this slot. Use :c:func:" +"`PyType_GetDict` to retrieve the dictionary for an arbitrary type." +msgstr "" + +#: ../../c-api/typeobj.rst:1994 +msgid "" +"Internals detail: For static builtin types, this is always ``NULL``. " +"Instead, the dict for such types is stored on ``PyInterpreterState``. Use :c:" +"func:`PyType_GetDict` to get the dict for an arbitrary type." +msgstr "" + +#: ../../c-api/typeobj.rst:2000 +msgid "" +"This field is not inherited by subtypes (though the attributes defined in " +"here are inherited through a different mechanism)." +msgstr "" + +#: ../../c-api/typeobj.rst:2005 +msgid "" +"If this field is ``NULL``, :c:func:`PyType_Ready` will assign a new " +"dictionary to it." +msgstr "" + +#: ../../c-api/typeobj.rst:2010 +msgid "" +"It is not safe to use :c:func:`PyDict_SetItem` on or otherwise modify :c:" +"member:`~PyTypeObject.tp_dict` with the dictionary C-API." +msgstr "" + +#: ../../c-api/typeobj.rst:2018 +msgid "An optional pointer to a \"descriptor get\" function." +msgstr "" + +#: ../../c-api/typeobj.rst:2020 ../../c-api/typeobj.rst:2038 +#: ../../c-api/typeobj.rst:2104 ../../c-api/typeobj.rst:2136 +#: ../../c-api/typeobj.rst:2161 +msgid "The function signature is::" +msgstr "" + +#: ../../c-api/typeobj.rst:2022 +msgid "PyObject * tp_descr_get(PyObject *self, PyObject *obj, PyObject *type);" +msgstr "" +"PyObject * tp_descr_get(PyObject *self, PyObject *obj, PyObject *type);" + +#: ../../c-api/typeobj.rst:2035 +msgid "" +"An optional pointer to a function for setting and deleting a descriptor's " +"value." +msgstr "" + +#: ../../c-api/typeobj.rst:2040 +msgid "int tp_descr_set(PyObject *self, PyObject *obj, PyObject *value);" +msgstr "int tp_descr_set(PyObject *self, PyObject *obj, PyObject *value);" + +#: ../../c-api/typeobj.rst:2042 +msgid "The *value* argument is set to ``NULL`` to delete the value." +msgstr "" + +#: ../../c-api/typeobj.rst:2053 +msgid "" +"While this field is still supported, :c:macro:`Py_TPFLAGS_MANAGED_DICT` " +"should be used instead, if at all possible." +msgstr "" + +#: ../../c-api/typeobj.rst:2056 +msgid "" +"If the instances of this type have a dictionary containing instance " +"variables, this field is non-zero and contains the offset in the instances " +"of the type of the instance variable dictionary; this offset is used by :c:" +"func:`PyObject_GenericGetAttr`." +msgstr "" + +#: ../../c-api/typeobj.rst:2061 +msgid "" +"Do not confuse this field with :c:member:`~PyTypeObject.tp_dict`; that is " +"the dictionary for attributes of the type object itself." +msgstr "" + +#: ../../c-api/typeobj.rst:2064 +msgid "" +"The value specifies the offset of the dictionary from the start of the " +"instance structure." +msgstr "" + +#: ../../c-api/typeobj.rst:2066 +msgid "" +"The :c:member:`~PyTypeObject.tp_dictoffset` should be regarded as write-" +"only. To get the pointer to the dictionary call :c:func:" +"`PyObject_GenericGetDict`. Calling :c:func:`PyObject_GenericGetDict` may " +"need to allocate memory for the dictionary, so it is may be more efficient " +"to call :c:func:`PyObject_GetAttr` when accessing an attribute on the object." +msgstr "" + +#: ../../c-api/typeobj.rst:2072 +msgid "" +"It is an error to set both the :c:macro:`Py_TPFLAGS_MANAGED_DICT` bit and :c:" +"member:`~PyTypeObject.tp_dictoffset`." +msgstr "" + +#: ../../c-api/typeobj.rst:2077 +msgid "" +"This field is inherited by subtypes. A subtype should not override this " +"offset; doing so could be unsafe, if C code tries to access the dictionary " +"at the previous offset. To properly support inheritance, use :c:macro:" +"`Py_TPFLAGS_MANAGED_DICT`." +msgstr "" + +#: ../../c-api/typeobj.rst:2084 +msgid "" +"This slot has no default. For :ref:`static types `, if the " +"field is ``NULL`` then no :attr:`~object.__dict__` gets created for " +"instances." +msgstr "" + +#: ../../c-api/typeobj.rst:2087 +msgid "" +"If the :c:macro:`Py_TPFLAGS_MANAGED_DICT` bit is set in the :c:member:" +"`~PyTypeObject.tp_flags` field, then :c:member:`~PyTypeObject.tp_dictoffset` " +"will be set to ``-1``, to indicate that it is unsafe to use this field." +msgstr "" + +#: ../../c-api/typeobj.rst:2097 +msgid "An optional pointer to an instance initialization function." +msgstr "" + +#: ../../c-api/typeobj.rst:2099 +msgid "" +"This function corresponds to the :meth:`~object.__init__` method of " +"classes. Like :meth:`!__init__`, it is possible to create an instance " +"without calling :meth:`!__init__`, and it is possible to reinitialize an " +"instance by calling its :meth:`!__init__` method again." +msgstr "" + +#: ../../c-api/typeobj.rst:2106 +msgid "int tp_init(PyObject *self, PyObject *args, PyObject *kwds);" +msgstr "int tp_init(PyObject *self, PyObject *args, PyObject *kwds);" + +#: ../../c-api/typeobj.rst:2108 +msgid "" +"The self argument is the instance to be initialized; the *args* and *kwds* " +"arguments represent positional and keyword arguments of the call to :meth:" +"`~object.__init__`." +msgstr "" + +#: ../../c-api/typeobj.rst:2112 +msgid "" +"The :c:member:`~PyTypeObject.tp_init` function, if not ``NULL``, is called " +"when an instance is created normally by calling its type, after the type's :" +"c:member:`~PyTypeObject.tp_new` function has returned an instance of the " +"type. If the :c:member:`~PyTypeObject.tp_new` function returns an instance " +"of some other type that is not a subtype of the original type, no :c:member:" +"`~PyTypeObject.tp_init` function is called; if :c:member:`~PyTypeObject." +"tp_new` returns an instance of a subtype of the original type, the " +"subtype's :c:member:`~PyTypeObject.tp_init` is called." +msgstr "" + +#: ../../c-api/typeobj.rst:2119 +msgid "Returns ``0`` on success, ``-1`` and sets an exception on error." +msgstr "" + +#: ../../c-api/typeobj.rst:2127 +msgid "" +"For :ref:`static types ` this field does not have a default." +msgstr "" + +#: ../../c-api/typeobj.rst:2134 +msgid "An optional pointer to an instance allocation function." +msgstr "" + +#: ../../c-api/typeobj.rst:2138 +msgid "PyObject *tp_alloc(PyTypeObject *self, Py_ssize_t nitems);" +msgstr "PyObject *tp_alloc(PyTypeObject *self, Py_ssize_t nitems);" + +#: ../../c-api/typeobj.rst:2142 +msgid "" +"Static subtypes inherit this slot, which will be :c:func:" +"`PyType_GenericAlloc` if inherited from :class:`object`." +msgstr "" + +#: ../../c-api/typeobj.rst:2145 ../../c-api/typeobj.rst:2216 +msgid ":ref:`Heap subtypes ` do not inherit this slot." +msgstr "" + +#: ../../c-api/typeobj.rst:2149 +msgid "" +"For heap subtypes, this field is always set to :c:func:`PyType_GenericAlloc`." +msgstr "" + +#: ../../c-api/typeobj.rst:2152 ../../c-api/typeobj.rst:2224 +msgid "For static subtypes, this slot is inherited (see above)." +msgstr "" + +#: ../../c-api/typeobj.rst:2159 +msgid "An optional pointer to an instance creation function." +msgstr "" + +#: ../../c-api/typeobj.rst:2163 +msgid "" +"PyObject *tp_new(PyTypeObject *subtype, PyObject *args, PyObject *kwds);" +msgstr "" +"PyObject *tp_new(PyTypeObject *subtype, PyObject *args, PyObject *kwds);" + +#: ../../c-api/typeobj.rst:2165 +msgid "" +"The *subtype* argument is the type of the object being created; the *args* " +"and *kwds* arguments represent positional and keyword arguments of the call " +"to the type. Note that *subtype* doesn't have to equal the type whose :c:" +"member:`~PyTypeObject.tp_new` function is called; it may be a subtype of " +"that type (but not an unrelated type)." +msgstr "" + +#: ../../c-api/typeobj.rst:2171 +msgid "" +"The :c:member:`~PyTypeObject.tp_new` function should call ``subtype-" +">tp_alloc(subtype, nitems)`` to allocate space for the object, and then do " +"only as much further initialization as is absolutely necessary. " +"Initialization that can safely be ignored or repeated should be placed in " +"the :c:member:`~PyTypeObject.tp_init` handler. A good rule of thumb is that " +"for immutable types, all initialization should take place in :c:member:" +"`~PyTypeObject.tp_new`, while for mutable types, most initialization should " +"be deferred to :c:member:`~PyTypeObject.tp_init`." +msgstr "" + +#: ../../c-api/typeobj.rst:2179 +msgid "" +"Set the :c:macro:`Py_TPFLAGS_DISALLOW_INSTANTIATION` flag to disallow " +"creating instances of the type in Python." +msgstr "" + +#: ../../c-api/typeobj.rst:2184 +msgid "" +"This field is inherited by subtypes, except it is not inherited by :ref:" +"`static types ` whose :c:member:`~PyTypeObject.tp_base` is " +"``NULL`` or ``&PyBaseObject_Type``." +msgstr "" + +#: ../../c-api/typeobj.rst:2190 +msgid "" +"For :ref:`static types ` this field has no default. This means " +"if the slot is defined as ``NULL``, the type cannot be called to create new " +"instances; presumably there is some other way to create instances, like a " +"factory function." +msgstr "" + +#: ../../c-api/typeobj.rst:2200 +msgid "" +"An optional pointer to an instance deallocation function. Its signature is::" +msgstr "" + +#: ../../c-api/typeobj.rst:2202 +msgid "void tp_free(void *self);" +msgstr "void tp_free(void *self);" + +#: ../../c-api/typeobj.rst:2204 +msgid "" +"This function must free the memory allocated by :c:member:`~PyTypeObject." +"tp_alloc`." +msgstr "" + +#: ../../c-api/typeobj.rst:2209 +msgid "" +"Static subtypes inherit this slot, which will be :c:func:`PyObject_Free` if " +"inherited from :class:`object`. Exception: If the type supports garbage " +"collection (i.e., the :c:macro:`Py_TPFLAGS_HAVE_GC` flag is set in :c:member:" +"`~PyTypeObject.tp_flags`) and it would inherit :c:func:`PyObject_Free`, then " +"this slot is not inherited but instead defaults to :c:func:`PyObject_GC_Del`." +msgstr "" + +#: ../../c-api/typeobj.rst:2220 +msgid "" +"For :ref:`heap subtypes `, this slot defaults to a deallocator " +"suitable to match :c:func:`PyType_GenericAlloc` and the value of the :c:" +"macro:`Py_TPFLAGS_HAVE_GC` flag." +msgstr "" + +#: ../../c-api/typeobj.rst:2231 +msgid "An optional pointer to a function called by the garbage collector." +msgstr "" + +#: ../../c-api/typeobj.rst:2233 +msgid "" +"The garbage collector needs to know whether a particular object is " +"collectible or not. Normally, it is sufficient to look at the object's " +"type's :c:member:`~PyTypeObject.tp_flags` field, and check the :c:macro:" +"`Py_TPFLAGS_HAVE_GC` flag bit. But some types have a mixture of statically " +"and dynamically allocated instances, and the statically allocated instances " +"are not collectible. Such types should define this function; it should " +"return ``1`` for a collectible instance, and ``0`` for a non-collectible " +"instance. The signature is::" +msgstr "" + +#: ../../c-api/typeobj.rst:2241 +msgid "int tp_is_gc(PyObject *self);" +msgstr "int tp_is_gc(PyObject *self);" + +#: ../../c-api/typeobj.rst:2243 +msgid "" +"(The only example of this are types themselves. The metatype, :c:data:" +"`PyType_Type`, defines this function to distinguish between statically and :" +"ref:`dynamically allocated types `.)" +msgstr "" + +#: ../../c-api/typeobj.rst:2253 +msgid "" +"This slot has no default. If this field is ``NULL``, :c:macro:" +"`Py_TPFLAGS_HAVE_GC` is used as the functional equivalent." +msgstr "" + +#: ../../c-api/typeobj.rst:2261 +msgid "Tuple of base types." +msgstr "" + +#: ../../c-api/typeobj.rst:2263 ../../c-api/typeobj.rst:2287 +msgid "" +"This field should be set to ``NULL`` and treated as read-only. Python will " +"fill it in when the type is :c:func:`initialized `." +msgstr "" + +#: ../../c-api/typeobj.rst:2266 +msgid "" +"For dynamically created classes, the :c:data:`Py_tp_bases` :c:type:`slot " +"` can be used instead of the *bases* argument of :c:func:" +"`PyType_FromSpecWithBases`. The argument form is preferred." +msgstr "" + +#: ../../c-api/typeobj.rst:2273 +msgid "" +"Multiple inheritance does not work well for statically defined types. If you " +"set ``tp_bases`` to a tuple, Python will not raise an error, but some slots " +"will only be inherited from the first base." +msgstr "" + +#: ../../c-api/typeobj.rst:2279 ../../c-api/typeobj.rst:2302 +#: ../../c-api/typeobj.rst:2319 ../../c-api/typeobj.rst:2336 +#: ../../c-api/typeobj.rst:2352 +msgid "This field is not inherited." +msgstr "" + +#: ../../c-api/typeobj.rst:2284 +msgid "" +"Tuple containing the expanded set of base types, starting with the type " +"itself and ending with :class:`object`, in Method Resolution Order." +msgstr "" + +#: ../../c-api/typeobj.rst:2292 +msgid "" +"This field is not inherited; it is calculated fresh by :c:func:" +"`PyType_Ready`." +msgstr "" + +#: ../../c-api/typeobj.rst:2298 +msgid "Unused. Internal use only." +msgstr "" + +#: ../../c-api/typeobj.rst:2307 +msgid "" +"A collection of subclasses. Internal use only. May be an invalid pointer." +msgstr "" + +#: ../../c-api/typeobj.rst:2309 +msgid "" +"To get a list of subclasses, call the Python method :py:meth:`~type." +"__subclasses__`." +msgstr "" + +#: ../../c-api/typeobj.rst:2314 +msgid "" +"For some types, this field does not hold a valid :c:expr:`PyObject*`. The " +"type was changed to :c:expr:`void*` to indicate this." +msgstr "" + +#: ../../c-api/typeobj.rst:2324 +msgid "" +"Weak reference list head, for weak references to this type object. Not " +"inherited. Internal use only." +msgstr "" + +#: ../../c-api/typeobj.rst:2329 +msgid "" +"Internals detail: For the static builtin types this is always ``NULL``, even " +"if weakrefs are added. Instead, the weakrefs for each are stored on " +"``PyInterpreterState``. Use the public C-API or the internal " +"``_PyObject_GET_WEAKREFS_LISTPTR()`` macro to avoid the distinction." +msgstr "" + +#: ../../c-api/typeobj.rst:2343 +msgid "" +"This field is deprecated. Use :c:member:`~PyTypeObject.tp_finalize` instead." +msgstr "此欄位已被棄用。請改用 :c:member:`~PyTypeObject.tp_finalize`。" + +#: ../../c-api/typeobj.rst:2348 +msgid "Used to index into the method cache. Internal use only." +msgstr "" + +#: ../../c-api/typeobj.rst:2359 +msgid "" +"An optional pointer to an instance finalization function. This is the C " +"implementation of the :meth:`~object.__del__` special method. Its signature " +"is::" +msgstr "" + +#: ../../c-api/typeobj.rst:2363 +msgid "void tp_finalize(PyObject *self);" +msgstr "void tp_finalize(PyObject *self);" + +#: ../../c-api/typeobj.rst:2365 +msgid "" +"The primary purpose of finalization is to perform any non-trivial cleanup " +"that must be performed before the object is destroyed, while the object and " +"any other objects it directly or indirectly references are still in a " +"consistent state. The finalizer is allowed to execute arbitrary Python code." +msgstr "" + +#: ../../c-api/typeobj.rst:2371 +msgid "" +"Before Python automatically finalizes an object, some of the object's direct " +"or indirect referents might have themselves been automatically finalized. " +"However, none of the referents will have been automatically cleared (:c:" +"member:`~PyTypeObject.tp_clear`) yet." +msgstr "" + +#: ../../c-api/typeobj.rst:2376 +msgid "" +"Other non-finalized objects might still be using a finalized object, so the " +"finalizer must leave the object in a sane state (e.g., invariants are still " +"met)." +msgstr "" + +#: ../../c-api/typeobj.rst:2382 +msgid "" +"After Python automatically finalizes an object, Python might start " +"automatically clearing (:c:member:`~PyTypeObject.tp_clear`) the object and " +"its referents (direct and indirect). Cleared objects are not guaranteed to " +"be in a consistent state; a finalized object must be able to tolerate " +"cleared referents." +msgstr "" + +#: ../../c-api/typeobj.rst:2390 +msgid "" +"An object is not guaranteed to be automatically finalized before its " +"destructor (:c:member:`~PyTypeObject.tp_dealloc`) is called. It is " +"recommended to call :c:func:`PyObject_CallFinalizerFromDealloc` at the " +"beginning of :c:member:`!tp_dealloc` to guarantee that the object is always " +"finalized before destruction." +msgstr "" + +#: ../../c-api/typeobj.rst:2398 +msgid "" +"The :c:member:`~PyTypeObject.tp_finalize` function can be called from any " +"thread, although the :term:`GIL` will be held." +msgstr "" + +#: ../../c-api/typeobj.rst:2403 +msgid "" +"The :c:member:`!tp_finalize` function can be called during shutdown, after " +"some global variables have been deleted. See the documentation of the :meth:" +"`~object.__del__` method for details." +msgstr "" + +#: ../../c-api/typeobj.rst:2407 +msgid "" +"When Python finalizes an object, it behaves like the following algorithm:" +msgstr "" + +#: ../../c-api/typeobj.rst:2409 +msgid "" +"Python might mark the object as *finalized*. Currently, Python always marks " +"objects whose type supports garbage collection (i.e., the :c:macro:" +"`Py_TPFLAGS_HAVE_GC` flag is set in :c:member:`~PyTypeObject.tp_flags`) and " +"never marks other types of objects; this might change in a future version." +msgstr "" + +#: ../../c-api/typeobj.rst:2414 +msgid "" +"If the object is not marked as *finalized* and its :c:member:`!tp_finalize` " +"finalizer function is non-``NULL``, the finalizer function is called." +msgstr "" + +#: ../../c-api/typeobj.rst:2417 +msgid "" +"If the finalizer function was called and the finalizer made the object " +"reachable (i.e., there is a reference to the object and it is not a member " +"of a :term:`cyclic isolate`), then the finalizer is said to have " +"*resurrected* the object. It is unspecified whether the finalizer can also " +"resurrect the object by adding a new reference to the object that does not " +"make it reachable, i.e., the object is (still) a member of a cyclic isolate." +msgstr "" + +#: ../../c-api/typeobj.rst:2424 +msgid "" +"If the finalizer resurrected the object, the object's pending destruction is " +"canceled and the object's *finalized* mark might be removed if present. " +"Currently, Python never removes the *finalized* mark; this might change in a " +"future version." +msgstr "" + +#: ../../c-api/typeobj.rst:2429 +msgid "" +"*Automatic finalization* refers to any finalization performed by Python " +"except via calls to :c:func:`PyObject_CallFinalizer` or :c:func:" +"`PyObject_CallFinalizerFromDealloc`. No guarantees are made about when, if, " +"or how often an object is automatically finalized, except:" +msgstr "" + +#: ../../c-api/typeobj.rst:2434 +msgid "" +"Python will not automatically finalize an object if it is reachable, i.e., " +"there is a reference to it and it is not a member of a :term:`cyclic " +"isolate`." +msgstr "" + +#: ../../c-api/typeobj.rst:2437 +msgid "" +"Python will not automatically finalize an object if finalizing it would not " +"mark the object as *finalized*. Currently, this applies to objects whose " +"type does not support garbage collection, i.e., the :c:macro:" +"`Py_TPFLAGS_HAVE_GC` flag is not set. Such objects can still be manually " +"finalized by calling :c:func:`PyObject_CallFinalizer` or :c:func:" +"`PyObject_CallFinalizerFromDealloc`." +msgstr "" + +#: ../../c-api/typeobj.rst:2443 +msgid "" +"Python will not automatically finalize any two members of a :term:`cyclic " +"isolate` concurrently." +msgstr "" + +#: ../../c-api/typeobj.rst:2445 +msgid "" +"Python will not automatically finalize an object after it has automatically " +"cleared (:c:member:`~PyTypeObject.tp_clear`) the object." +msgstr "" + +#: ../../c-api/typeobj.rst:2447 +msgid "" +"If an object is a member of a :term:`cyclic isolate`, Python will not " +"automatically finalize it after automatically clearing (see :c:member:" +"`~PyTypeObject.tp_clear`) any other member." +msgstr "" + +#: ../../c-api/typeobj.rst:2450 +msgid "" +"Python will automatically finalize every member of a :term:`cyclic isolate` " +"before it automatically clears (see :c:member:`~PyTypeObject.tp_clear`) any " +"of them." +msgstr "" + +#: ../../c-api/typeobj.rst:2453 +msgid "" +"If Python is going to automatically clear an object (:c:member:" +"`~PyTypeObject.tp_clear`), it will automatically finalize the object first." +msgstr "" + +#: ../../c-api/typeobj.rst:2457 +msgid "" +"Python currently only automatically finalizes objects that are members of a :" +"term:`cyclic isolate`, but future versions might finalize objects regularly " +"before their destruction." +msgstr "" + +#: ../../c-api/typeobj.rst:2461 +msgid "" +"To manually finalize an object, do not call this function directly; call :c:" +"func:`PyObject_CallFinalizer` or :c:func:`PyObject_CallFinalizerFromDealloc` " +"instead." +msgstr "" + +#: ../../c-api/typeobj.rst:2465 +msgid "" +":c:member:`~PyTypeObject.tp_finalize` should leave the current exception " +"status unchanged. The recommended way to write a non-trivial finalizer is " +"to back up the exception at the beginning by calling :c:func:" +"`PyErr_GetRaisedException` and restore the exception at the end by calling :" +"c:func:`PyErr_SetRaisedException`. If an exception is encountered in the " +"middle of the finalizer, log and clear it with :c:func:" +"`PyErr_WriteUnraisable` or :c:func:`PyErr_FormatUnraisable`. For example::" +msgstr "" + +#: ../../c-api/typeobj.rst:2474 +msgid "" +"static void\n" +"foo_finalize(PyObject *self)\n" +"{\n" +" // Save the current exception, if any.\n" +" PyObject *exc = PyErr_GetRaisedException();\n" +"\n" +" // ...\n" +"\n" +" if (do_something_that_might_raise() != success_indicator) {\n" +" PyErr_WriteUnraisable(self);\n" +" goto done;\n" +" }\n" +"\n" +"done:\n" +" // Restore the saved exception. This silently discards any exception\n" +" // raised above, so be sure to call PyErr_WriteUnraisable first if\n" +" // necessary.\n" +" PyErr_SetRaisedException(exc);\n" +"}" +msgstr "" + +#: ../../c-api/typeobj.rst:2502 +msgid "" +"Before version 3.8 it was necessary to set the :c:macro:" +"`Py_TPFLAGS_HAVE_FINALIZE` flags bit in order for this field to be used. " +"This is no longer required." +msgstr "" + +#: ../../c-api/typeobj.rst:2508 +msgid ":pep:`442`: \"Safe object finalization\"" +msgstr "" + +#: ../../c-api/typeobj.rst:2511 +msgid ":c:func:`PyObject_CallFinalizer`" +msgstr ":c:func:`PyObject_CallFinalizer`" + +#: ../../c-api/typeobj.rst:2512 +msgid ":c:func:`PyObject_CallFinalizerFromDealloc`" +msgstr ":c:func:`PyObject_CallFinalizerFromDealloc`" + +#: ../../c-api/typeobj.rst:2519 +msgid "" +"A :ref:`vectorcall function ` to use for calls of this type " +"object (rather than instances). In other words, ``tp_vectorcall`` can be " +"used to optimize ``type.__call__``, which typically returns a new instance " +"of *type*." +msgstr "" + +#: ../../c-api/typeobj.rst:2524 +msgid "" +"As with any vectorcall function, if ``tp_vectorcall`` is ``NULL``, the " +"*tp_call* protocol (``Py_TYPE(type)->tp_call``) is used instead." +msgstr "" + +#: ../../c-api/typeobj.rst:2529 +msgid "" +"The :ref:`vectorcall protocol ` requires that the vectorcall " +"function has the same behavior as the corresponding ``tp_call``. This means " +"that ``type->tp_vectorcall`` must match the behavior of ``Py_TYPE(type)-" +">tp_call``." +msgstr "" + +#: ../../c-api/typeobj.rst:2534 +msgid "" +"Specifically, if *type* uses the default metaclass, ``type->tp_vectorcall`` " +"must behave the same as :c:expr:`PyType_Type->tp_call`, which:" +msgstr "" + +#: ../../c-api/typeobj.rst:2538 +msgid "calls ``type->tp_new``," +msgstr "呼叫 ``type->tp_new``，" + +#: ../../c-api/typeobj.rst:2540 +msgid "" +"if the result is a subclass of *type*, calls ``type->tp_init`` on the result " +"of ``tp_new``, and" +msgstr "" + +#: ../../c-api/typeobj.rst:2543 +msgid "returns the result of ``tp_new``." +msgstr "回傳 ``tp_new`` 的結果。" + +#: ../../c-api/typeobj.rst:2545 +msgid "" +"Typically, ``tp_vectorcall`` is overridden to optimize this process for " +"specific :c:member:`~PyTypeObject.tp_new` and :c:member:`~PyTypeObject." +"tp_init`. When doing this for user-subclassable types, note that both can be " +"overridden (using :py:func:`~object.__new__` and :py:func:`~object." +"__init__`, respectively)." +msgstr "" + +#: ../../c-api/typeobj.rst:2556 +msgid "This field is never inherited." +msgstr "" + +#: ../../c-api/typeobj.rst:2558 +msgid "(the field exists since 3.8 but it's only used since 3.9)" +msgstr "" + +#: ../../c-api/typeobj.rst:2563 +msgid "Internal. Do not use." +msgstr "" + +#: ../../c-api/typeobj.rst:2571 +msgid "Static Types" +msgstr "靜態型別" + +#: ../../c-api/typeobj.rst:2573 +msgid "" +"Traditionally, types defined in C code are *static*, that is, a static :c:" +"type:`PyTypeObject` structure is defined directly in code and initialized " +"using :c:func:`PyType_Ready`." +msgstr "" + +#: ../../c-api/typeobj.rst:2577 +msgid "" +"This results in types that are limited relative to types defined in Python:" +msgstr "" + +#: ../../c-api/typeobj.rst:2579 +msgid "" +"Static types are limited to one base, i.e. they cannot use multiple " +"inheritance." +msgstr "" + +#: ../../c-api/typeobj.rst:2581 +msgid "" +"Static type objects (but not necessarily their instances) are immutable. It " +"is not possible to add or modify the type object's attributes from Python." +msgstr "" + +#: ../../c-api/typeobj.rst:2583 +msgid "" +"Static type objects are shared across :ref:`sub-interpreters `, so they should not include any subinterpreter-" +"specific state." +msgstr "" + +#: ../../c-api/typeobj.rst:2587 +msgid "" +"Also, since :c:type:`PyTypeObject` is only part of the :ref:`Limited API " +"` as an opaque struct, any extension modules using static " +"types must be compiled for a specific Python minor version." +msgstr "" + +#: ../../c-api/typeobj.rst:2595 +msgid "Heap Types" +msgstr "堆積型別" + +#: ../../c-api/typeobj.rst:2597 +msgid "" +"An alternative to :ref:`static types ` is *heap-allocated " +"types*, or *heap types* for short, which correspond closely to classes " +"created by Python's ``class`` statement. Heap types have the :c:macro:" +"`Py_TPFLAGS_HEAPTYPE` flag set." +msgstr "" + +#: ../../c-api/typeobj.rst:2602 +msgid "" +"This is done by filling a :c:type:`PyType_Spec` structure and calling :c:" +"func:`PyType_FromSpec`, :c:func:`PyType_FromSpecWithBases`, :c:func:" +"`PyType_FromModuleAndSpec`, or :c:func:`PyType_FromMetaclass`." +msgstr "" + +#: ../../c-api/typeobj.rst:2610 +msgid "Number Object Structures" +msgstr "" + +#: ../../c-api/typeobj.rst:2617 +msgid "" +"This structure holds pointers to the functions which an object uses to " +"implement the number protocol. Each function is used by the function of " +"similar name documented in the :ref:`number` section." +msgstr "" + +#: ../../c-api/typeobj.rst:2623 ../../c-api/typeobj.rst:3079 +msgid "Here is the structure definition::" +msgstr "" + +#: ../../c-api/typeobj.rst:2625 +msgid "" +"typedef struct {\n" +" binaryfunc nb_add;\n" +" binaryfunc nb_subtract;\n" +" binaryfunc nb_multiply;\n" +" binaryfunc nb_remainder;\n" +" binaryfunc nb_divmod;\n" +" ternaryfunc nb_power;\n" +" unaryfunc nb_negative;\n" +" unaryfunc nb_positive;\n" +" unaryfunc nb_absolute;\n" +" inquiry nb_bool;\n" +" unaryfunc nb_invert;\n" +" binaryfunc nb_lshift;\n" +" binaryfunc nb_rshift;\n" +" binaryfunc nb_and;\n" +" binaryfunc nb_xor;\n" +" binaryfunc nb_or;\n" +" unaryfunc nb_int;\n" +" void *nb_reserved;\n" +" unaryfunc nb_float;\n" +"\n" +" binaryfunc nb_inplace_add;\n" +" binaryfunc nb_inplace_subtract;\n" +" binaryfunc nb_inplace_multiply;\n" +" binaryfunc nb_inplace_remainder;\n" +" ternaryfunc nb_inplace_power;\n" +" binaryfunc nb_inplace_lshift;\n" +" binaryfunc nb_inplace_rshift;\n" +" binaryfunc nb_inplace_and;\n" +" binaryfunc nb_inplace_xor;\n" +" binaryfunc nb_inplace_or;\n" +"\n" +" binaryfunc nb_floor_divide;\n" +" binaryfunc nb_true_divide;\n" +" binaryfunc nb_inplace_floor_divide;\n" +" binaryfunc nb_inplace_true_divide;\n" +"\n" +" unaryfunc nb_index;\n" +"\n" +" binaryfunc nb_matrix_multiply;\n" +" binaryfunc nb_inplace_matrix_multiply;\n" +"} PyNumberMethods;" +msgstr "" +"typedef struct {\n" +" binaryfunc nb_add;\n" +" binaryfunc nb_subtract;\n" +" binaryfunc nb_multiply;\n" +" binaryfunc nb_remainder;\n" +" binaryfunc nb_divmod;\n" +" ternaryfunc nb_power;\n" +" unaryfunc nb_negative;\n" +" unaryfunc nb_positive;\n" +" unaryfunc nb_absolute;\n" +" inquiry nb_bool;\n" +" unaryfunc nb_invert;\n" +" binaryfunc nb_lshift;\n" +" binaryfunc nb_rshift;\n" +" binaryfunc nb_and;\n" +" binaryfunc nb_xor;\n" +" binaryfunc nb_or;\n" +" unaryfunc nb_int;\n" +" void *nb_reserved;\n" +" unaryfunc nb_float;\n" +"\n" +" binaryfunc nb_inplace_add;\n" +" binaryfunc nb_inplace_subtract;\n" +" binaryfunc nb_inplace_multiply;\n" +" binaryfunc nb_inplace_remainder;\n" +" ternaryfunc nb_inplace_power;\n" +" binaryfunc nb_inplace_lshift;\n" +" binaryfunc nb_inplace_rshift;\n" +" binaryfunc nb_inplace_and;\n" +" binaryfunc nb_inplace_xor;\n" +" binaryfunc nb_inplace_or;\n" +"\n" +" binaryfunc nb_floor_divide;\n" +" binaryfunc nb_true_divide;\n" +" binaryfunc nb_inplace_floor_divide;\n" +" binaryfunc nb_inplace_true_divide;\n" +"\n" +" unaryfunc nb_index;\n" +"\n" +" binaryfunc nb_matrix_multiply;\n" +" binaryfunc nb_inplace_matrix_multiply;\n" +"} PyNumberMethods;" + +#: ../../c-api/typeobj.rst:2670 +msgid "" +"Binary and ternary functions must check the type of all their operands, and " +"implement the necessary conversions (at least one of the operands is an " +"instance of the defined type). If the operation is not defined for the " +"given operands, binary and ternary functions must return " +"``Py_NotImplemented``, if another error occurred they must return ``NULL`` " +"and set an exception." +msgstr "" + +#: ../../c-api/typeobj.rst:2679 +msgid "" +"The :c:member:`~PyNumberMethods.nb_reserved` field should always be " +"``NULL``. It was previously called :c:member:`!nb_long`, and was renamed in " +"Python 3.0.1." +msgstr "" + +#: ../../c-api/typeobj.rst:2830 +msgid "Mapping Object Structures" +msgstr "對映物件結構" + +#: ../../c-api/typeobj.rst:2837 +msgid "" +"This structure holds pointers to the functions which an object uses to " +"implement the mapping protocol. It has three members:" +msgstr "" + +#: ../../c-api/typeobj.rst:2844 +msgid "" +"This function is used by :c:func:`PyMapping_Size` and :c:func:" +"`PyObject_Size`, and has the same signature. This slot may be set to " +"``NULL`` if the object has no defined length." +msgstr "" + +#: ../../c-api/typeobj.rst:2852 +msgid "" +"This function is used by :c:func:`PyObject_GetItem` and :c:func:" +"`PySequence_GetSlice`, and has the same signature as :c:func:`!" +"PyObject_GetItem`. This slot must be filled for the :c:func:" +"`PyMapping_Check` function to return ``1``, it can be ``NULL`` otherwise." +msgstr "" + +#: ../../c-api/typeobj.rst:2862 +msgid "" +"This function is used by :c:func:`PyObject_SetItem`, :c:func:" +"`PyObject_DelItem`, :c:func:`PySequence_SetSlice` and :c:func:" +"`PySequence_DelSlice`. It has the same signature as :c:func:`!" +"PyObject_SetItem`, but *v* can also be set to ``NULL`` to delete an item. " +"If this slot is ``NULL``, the object does not support item assignment and " +"deletion." +msgstr "" + +#: ../../c-api/typeobj.rst:2873 +msgid "Sequence Object Structures" +msgstr "序列物件結構" + +#: ../../c-api/typeobj.rst:2880 +msgid "" +"This structure holds pointers to the functions which an object uses to " +"implement the sequence protocol." +msgstr "" + +#: ../../c-api/typeobj.rst:2887 +msgid "" +"This function is used by :c:func:`PySequence_Size` and :c:func:" +"`PyObject_Size`, and has the same signature. It is also used for handling " +"negative indices via the :c:member:`~PySequenceMethods.sq_item` and the :c:" +"member:`~PySequenceMethods.sq_ass_item` slots." +msgstr "" + +#: ../../c-api/typeobj.rst:2896 +msgid "" +"This function is used by :c:func:`PySequence_Concat` and has the same " +"signature. It is also used by the ``+`` operator, after trying the numeric " +"addition via the :c:member:`~PyNumberMethods.nb_add` slot." +msgstr "" + +#: ../../c-api/typeobj.rst:2904 +msgid "" +"This function is used by :c:func:`PySequence_Repeat` and has the same " +"signature. It is also used by the ``*`` operator, after trying numeric " +"multiplication via the :c:member:`~PyNumberMethods.nb_multiply` slot." +msgstr "" + +#: ../../c-api/typeobj.rst:2912 +msgid "" +"This function is used by :c:func:`PySequence_GetItem` and has the same " +"signature. It is also used by :c:func:`PyObject_GetItem`, after trying the " +"subscription via the :c:member:`~PyMappingMethods.mp_subscript` slot. This " +"slot must be filled for the :c:func:`PySequence_Check` function to return " +"``1``, it can be ``NULL`` otherwise." +msgstr "" + +#: ../../c-api/typeobj.rst:2918 +msgid "" +"Negative indexes are handled as follows: if the :c:member:" +"`~PySequenceMethods.sq_length` slot is filled, it is called and the sequence " +"length is used to compute a positive index which is passed to :c:member:" +"`~PySequenceMethods.sq_item`. If :c:member:`!sq_length` is ``NULL``, the " +"index is passed as is to the function." +msgstr "" + +#: ../../c-api/typeobj.rst:2927 +msgid "" +"This function is used by :c:func:`PySequence_SetItem` and has the same " +"signature. It is also used by :c:func:`PyObject_SetItem` and :c:func:" +"`PyObject_DelItem`, after trying the item assignment and deletion via the :c:" +"member:`~PyMappingMethods.mp_ass_subscript` slot. This slot may be left to " +"``NULL`` if the object does not support item assignment and deletion." +msgstr "" + +#: ../../c-api/typeobj.rst:2938 +msgid "" +"This function may be used by :c:func:`PySequence_Contains` and has the same " +"signature. This slot may be left to ``NULL``, in this case :c:func:`!" +"PySequence_Contains` simply traverses the sequence until it finds a match." +msgstr "" + +#: ../../c-api/typeobj.rst:2947 +msgid "" +"This function is used by :c:func:`PySequence_InPlaceConcat` and has the same " +"signature. It should modify its first operand, and return it. This slot " +"may be left to ``NULL``, in this case :c:func:`!PySequence_InPlaceConcat` " +"will fall back to :c:func:`PySequence_Concat`. It is also used by the " +"augmented assignment ``+=``, after trying numeric in-place addition via the :" +"c:member:`~PyNumberMethods.nb_inplace_add` slot." +msgstr "" + +#: ../../c-api/typeobj.rst:2958 +msgid "" +"This function is used by :c:func:`PySequence_InPlaceRepeat` and has the same " +"signature. It should modify its first operand, and return it. This slot " +"may be left to ``NULL``, in this case :c:func:`!PySequence_InPlaceRepeat` " +"will fall back to :c:func:`PySequence_Repeat`. It is also used by the " +"augmented assignment ``*=``, after trying numeric in-place multiplication " +"via the :c:member:`~PyNumberMethods.nb_inplace_multiply` slot." +msgstr "" + +#: ../../c-api/typeobj.rst:2969 +msgid "Buffer Object Structures" +msgstr "緩衝區物件結構" + +#: ../../c-api/typeobj.rst:2977 +msgid "" +"This structure holds pointers to the functions required by the :ref:`Buffer " +"protocol `. The protocol defines how an exporter object can " +"expose its internal data to consumer objects." +msgstr "" + +#: ../../c-api/typeobj.rst:2985 ../../c-api/typeobj.rst:3036 +#: ../../c-api/typeobj.rst:3092 ../../c-api/typeobj.rst:3105 +#: ../../c-api/typeobj.rst:3119 ../../c-api/typeobj.rst:3131 +msgid "The signature of this function is::" +msgstr "函式的簽名為： ::" + +#: ../../c-api/typeobj.rst:2987 +msgid "int (PyObject *exporter, Py_buffer *view, int flags);" +msgstr "int (PyObject *exporter, Py_buffer *view, int flags);" + +#: ../../c-api/typeobj.rst:2989 +msgid "" +"Handle a request to *exporter* to fill in *view* as specified by *flags*. " +"Except for point (3), an implementation of this function MUST take these " +"steps:" +msgstr "" + +#: ../../c-api/typeobj.rst:2993 +msgid "" +"Check if the request can be met. If not, raise :exc:`BufferError`, set :c:" +"expr:`view->obj` to ``NULL`` and return ``-1``." +msgstr "" + +#: ../../c-api/typeobj.rst:2996 +msgid "Fill in the requested fields." +msgstr "" + +#: ../../c-api/typeobj.rst:2998 +msgid "Increment an internal counter for the number of exports." +msgstr "" + +#: ../../c-api/typeobj.rst:3000 +msgid "" +"Set :c:expr:`view->obj` to *exporter* and increment :c:expr:`view->obj`." +msgstr "" + +#: ../../c-api/typeobj.rst:3002 +msgid "Return ``0``." +msgstr "回傳 ``0``。" + +#: ../../c-api/typeobj.rst:3004 +msgid "" +"If *exporter* is part of a chain or tree of buffer providers, two main " +"schemes can be used:" +msgstr "" + +#: ../../c-api/typeobj.rst:3007 +msgid "" +"Re-export: Each member of the tree acts as the exporting object and sets :c:" +"expr:`view->obj` to a new reference to itself." +msgstr "" + +#: ../../c-api/typeobj.rst:3010 +msgid "" +"Redirect: The buffer request is redirected to the root object of the tree. " +"Here, :c:expr:`view->obj` will be a new reference to the root object." +msgstr "" + +#: ../../c-api/typeobj.rst:3014 +msgid "" +"The individual fields of *view* are described in section :ref:`Buffer " +"structure `, the rules how an exporter must react to " +"specific requests are in section :ref:`Buffer request types `." +msgstr "" + +#: ../../c-api/typeobj.rst:3019 +msgid "" +"All memory pointed to in the :c:type:`Py_buffer` structure belongs to the " +"exporter and must remain valid until there are no consumers left. :c:member:" +"`~Py_buffer.format`, :c:member:`~Py_buffer.shape`, :c:member:`~Py_buffer." +"strides`, :c:member:`~Py_buffer.suboffsets` and :c:member:`~Py_buffer." +"internal` are read-only for the consumer." +msgstr "" + +#: ../../c-api/typeobj.rst:3026 +msgid "" +":c:func:`PyBuffer_FillInfo` provides an easy way of exposing a simple bytes " +"buffer while dealing correctly with all request types." +msgstr "" + +#: ../../c-api/typeobj.rst:3029 +msgid "" +":c:func:`PyObject_GetBuffer` is the interface for the consumer that wraps " +"this function." +msgstr "" + +#: ../../c-api/typeobj.rst:3038 +msgid "void (PyObject *exporter, Py_buffer *view);" +msgstr "void (PyObject *exporter, Py_buffer *view);" + +#: ../../c-api/typeobj.rst:3040 +msgid "" +"Handle a request to release the resources of the buffer. If no resources " +"need to be released, :c:member:`PyBufferProcs.bf_releasebuffer` may be " +"``NULL``. Otherwise, a standard implementation of this function will take " +"these optional steps:" +msgstr "" + +#: ../../c-api/typeobj.rst:3045 +msgid "Decrement an internal counter for the number of exports." +msgstr "" + +#: ../../c-api/typeobj.rst:3047 +msgid "If the counter is ``0``, free all memory associated with *view*." +msgstr "" + +#: ../../c-api/typeobj.rst:3049 +msgid "" +"The exporter MUST use the :c:member:`~Py_buffer.internal` field to keep " +"track of buffer-specific resources. This field is guaranteed to remain " +"constant, while a consumer MAY pass a copy of the original buffer as the " +"*view* argument." +msgstr "" + +#: ../../c-api/typeobj.rst:3055 +msgid "" +"This function MUST NOT decrement :c:expr:`view->obj`, since that is done " +"automatically in :c:func:`PyBuffer_Release` (this scheme is useful for " +"breaking reference cycles)." +msgstr "" + +#: ../../c-api/typeobj.rst:3060 +msgid "" +":c:func:`PyBuffer_Release` is the interface for the consumer that wraps this " +"function." +msgstr "" + +#: ../../c-api/typeobj.rst:3068 +msgid "Async Object Structures" +msgstr "非同步物件結構" + +#: ../../c-api/typeobj.rst:3076 +msgid "" +"This structure holds pointers to the functions required to implement :term:" +"`awaitable` and :term:`asynchronous iterator` objects." +msgstr "" + +#: ../../c-api/typeobj.rst:3081 +msgid "" +"typedef struct {\n" +" unaryfunc am_await;\n" +" unaryfunc am_aiter;\n" +" unaryfunc am_anext;\n" +" sendfunc am_send;\n" +"} PyAsyncMethods;" +msgstr "" +"typedef struct {\n" +" unaryfunc am_await;\n" +" unaryfunc am_aiter;\n" +" unaryfunc am_anext;\n" +" sendfunc am_send;\n" +"} PyAsyncMethods;" + +#: ../../c-api/typeobj.rst:3094 +msgid "PyObject *am_await(PyObject *self);" +msgstr "PyObject *am_await(PyObject *self);" + +#: ../../c-api/typeobj.rst:3096 +msgid "" +"The returned object must be an :term:`iterator`, i.e. :c:func:`PyIter_Check` " +"must return ``1`` for it." +msgstr "" + +#: ../../c-api/typeobj.rst:3099 +msgid "" +"This slot may be set to ``NULL`` if an object is not an :term:`awaitable`." +msgstr "" + +#: ../../c-api/typeobj.rst:3107 +msgid "PyObject *am_aiter(PyObject *self);" +msgstr "PyObject *am_aiter(PyObject *self);" + +#: ../../c-api/typeobj.rst:3109 +msgid "" +"Must return an :term:`asynchronous iterator` object. See :meth:`~object." +"__anext__` for details." +msgstr "" + +#: ../../c-api/typeobj.rst:3112 +msgid "" +"This slot may be set to ``NULL`` if an object does not implement " +"asynchronous iteration protocol." +msgstr "" + +#: ../../c-api/typeobj.rst:3121 +msgid "PyObject *am_anext(PyObject *self);" +msgstr "PyObject *am_anext(PyObject *self);" + +#: ../../c-api/typeobj.rst:3123 +msgid "" +"Must return an :term:`awaitable` object. See :meth:`~object.__anext__` for " +"details. This slot may be set to ``NULL``." +msgstr "" + +#: ../../c-api/typeobj.rst:3133 +msgid "PySendResult am_send(PyObject *self, PyObject *arg, PyObject **result);" +msgstr "" +"PySendResult am_send(PyObject *self, PyObject *arg, PyObject **result);" + +#: ../../c-api/typeobj.rst:3135 +msgid "" +"See :c:func:`PyIter_Send` for details. This slot may be set to ``NULL``." +msgstr "" + +#: ../../c-api/typeobj.rst:3144 +msgid "Slot Type typedefs" +msgstr "" + +#: ../../c-api/typeobj.rst:3148 +msgid "" +"The purpose of this function is to separate memory allocation from memory " +"initialization. It should return a pointer to a block of memory of adequate " +"length for the instance, suitably aligned, and initialized to zeros, but " +"with :c:member:`~PyObject.ob_refcnt` set to ``1`` and :c:member:`~PyObject." +"ob_type` set to the type argument. If the type's :c:member:`~PyTypeObject." +"tp_itemsize` is non-zero, the object's :c:member:`~PyVarObject.ob_size` " +"field should be initialized to *nitems* and the length of the allocated " +"memory block should be ``tp_basicsize + nitems*tp_itemsize``, rounded up to " +"a multiple of ``sizeof(void*)``; otherwise, *nitems* is not used and the " +"length of the block should be :c:member:`~PyTypeObject.tp_basicsize`." +msgstr "" + +#: ../../c-api/typeobj.rst:3158 +msgid "" +"This function should not do any other instance initialization, not even to " +"allocate additional memory; that should be done by :c:member:`~PyTypeObject." +"tp_new`." +msgstr "" + +#: ../../c-api/typeobj.rst:3165 +msgid "See :c:member:`~PyTypeObject.tp_free`." +msgstr "請見 :c:member:`~PyTypeObject.tp_free`。" + +#: ../../c-api/typeobj.rst:3169 +msgid "See :c:member:`~PyTypeObject.tp_new`." +msgstr "請見 :c:member:`~PyTypeObject.tp_new`。" + +#: ../../c-api/typeobj.rst:3173 +msgid "See :c:member:`~PyTypeObject.tp_init`." +msgstr "請見 :c:member:`~PyTypeObject.tp_init`。" + +#: ../../c-api/typeobj.rst:3177 +msgid "See :c:member:`~PyTypeObject.tp_repr`." +msgstr "請見 :c:member:`~PyTypeObject.tp_repr`。" + +#: ../../c-api/typeobj.rst:3181 ../../c-api/typeobj.rst:3190 +msgid "Return the value of the named attribute for the object." +msgstr "" + +#: ../../c-api/typeobj.rst:3185 ../../c-api/typeobj.rst:3196 +msgid "" +"Set the value of the named attribute for the object. The value argument is " +"set to ``NULL`` to delete the attribute." +msgstr "" + +#: ../../c-api/typeobj.rst:3192 +msgid "See :c:member:`~PyTypeObject.tp_getattro`." +msgstr "請見 :c:member:`~PyTypeObject.tp_getattro`。" + +#: ../../c-api/typeobj.rst:3199 +msgid "See :c:member:`~PyTypeObject.tp_setattro`." +msgstr "請見 :c:member:`~PyTypeObject.tp_setattro`。" + +#: ../../c-api/typeobj.rst:3203 +msgid "See :c:member:`~PyTypeObject.tp_descr_get`." +msgstr "請見 :c:member:`~PyTypeObject.tp_descr_get`。" + +#: ../../c-api/typeobj.rst:3207 +msgid "See :c:member:`~PyTypeObject.tp_descr_set`." +msgstr "請見 :c:member:`~PyTypeObject.tp_descr_set`。" + +#: ../../c-api/typeobj.rst:3211 +msgid "See :c:member:`~PyTypeObject.tp_hash`." +msgstr "請見 :c:member:`~PyTypeObject.tp_hash`。" + +#: ../../c-api/typeobj.rst:3215 +msgid "See :c:member:`~PyTypeObject.tp_richcompare`." +msgstr "請見 :c:member:`~PyTypeObject.tp_richcompare`。" + +#: ../../c-api/typeobj.rst:3219 +msgid "See :c:member:`~PyTypeObject.tp_iter`." +msgstr "請見 :c:member:`~PyTypeObject.tp_iter`。" + +#: ../../c-api/typeobj.rst:3223 +msgid "See :c:member:`~PyTypeObject.tp_iternext`." +msgstr "請見 :c:member:`~PyTypeObject.tp_iternext`。" + +#: ../../c-api/typeobj.rst:3237 +msgid "See :c:member:`~PyAsyncMethods.am_send`." +msgstr "請見 :c:member:`~PyAsyncMethods.am_send`。" + +#: ../../c-api/typeobj.rst:3253 +msgid "Examples" +msgstr "範例" + +#: ../../c-api/typeobj.rst:3255 +msgid "" +"The following are simple examples of Python type definitions. They include " +"common usage you may encounter. Some demonstrate tricky corner cases. For " +"more examples, practical info, and a tutorial, see :ref:`defining-new-types` " +"and :ref:`new-types-topics`." +msgstr "" + +#: ../../c-api/typeobj.rst:3260 +msgid "A basic :ref:`static type `::" +msgstr "" + +#: ../../c-api/typeobj.rst:3262 +msgid "" +"typedef struct {\n" +" PyObject_HEAD\n" +" const char *data;\n" +"} MyObject;\n" +"\n" +"static PyTypeObject MyObject_Type = {\n" +" PyVarObject_HEAD_INIT(NULL, 0)\n" +" .tp_name = \"mymod.MyObject\",\n" +" .tp_basicsize = sizeof(MyObject),\n" +" .tp_doc = PyDoc_STR(\"My objects\"),\n" +" .tp_new = myobj_new,\n" +" .tp_dealloc = (destructor)myobj_dealloc,\n" +" .tp_repr = (reprfunc)myobj_repr,\n" +"};" +msgstr "" +"typedef struct {\n" +" PyObject_HEAD\n" +" const char *data;\n" +"} MyObject;\n" +"\n" +"static PyTypeObject MyObject_Type = {\n" +" PyVarObject_HEAD_INIT(NULL, 0)\n" +" .tp_name = \"mymod.MyObject\",\n" +" .tp_basicsize = sizeof(MyObject),\n" +" .tp_doc = PyDoc_STR(\"My objects\"),\n" +" .tp_new = myobj_new,\n" +" .tp_dealloc = (destructor)myobj_dealloc,\n" +" .tp_repr = (reprfunc)myobj_repr,\n" +"};" + +#: ../../c-api/typeobj.rst:3277 +msgid "" +"You may also find older code (especially in the CPython code base) with a " +"more verbose initializer::" +msgstr "" + +#: ../../c-api/typeobj.rst:3280 +msgid "" +"static PyTypeObject MyObject_Type = {\n" +" PyVarObject_HEAD_INIT(NULL, 0)\n" +" \"mymod.MyObject\", /* tp_name */\n" +" sizeof(MyObject), /* tp_basicsize */\n" +" 0, /* tp_itemsize */\n" +" (destructor)myobj_dealloc, /* tp_dealloc */\n" +" 0, /* tp_vectorcall_offset */\n" +" 0, /* tp_getattr */\n" +" 0, /* tp_setattr */\n" +" 0, /* tp_as_async */\n" +" (reprfunc)myobj_repr, /* tp_repr */\n" +" 0, /* tp_as_number */\n" +" 0, /* tp_as_sequence */\n" +" 0, /* tp_as_mapping */\n" +" 0, /* tp_hash */\n" +" 0, /* tp_call */\n" +" 0, /* tp_str */\n" +" 0, /* tp_getattro */\n" +" 0, /* tp_setattro */\n" +" 0, /* tp_as_buffer */\n" +" 0, /* tp_flags */\n" +" PyDoc_STR(\"My objects\"), /* tp_doc */\n" +" 0, /* tp_traverse */\n" +" 0, /* tp_clear */\n" +" 0, /* tp_richcompare */\n" +" 0, /* tp_weaklistoffset */\n" +" 0, /* tp_iter */\n" +" 0, /* tp_iternext */\n" +" 0, /* tp_methods */\n" +" 0, /* tp_members */\n" +" 0, /* tp_getset */\n" +" 0, /* tp_base */\n" +" 0, /* tp_dict */\n" +" 0, /* tp_descr_get */\n" +" 0, /* tp_descr_set */\n" +" 0, /* tp_dictoffset */\n" +" 0, /* tp_init */\n" +" 0, /* tp_alloc */\n" +" myobj_new, /* tp_new */\n" +"};" +msgstr "" +"static PyTypeObject MyObject_Type = {\n" +" PyVarObject_HEAD_INIT(NULL, 0)\n" +" \"mymod.MyObject\", /* tp_name */\n" +" sizeof(MyObject), /* tp_basicsize */\n" +" 0, /* tp_itemsize */\n" +" (destructor)myobj_dealloc, /* tp_dealloc */\n" +" 0, /* tp_vectorcall_offset */\n" +" 0, /* tp_getattr */\n" +" 0, /* tp_setattr */\n" +" 0, /* tp_as_async */\n" +" (reprfunc)myobj_repr, /* tp_repr */\n" +" 0, /* tp_as_number */\n" +" 0, /* tp_as_sequence */\n" +" 0, /* tp_as_mapping */\n" +" 0, /* tp_hash */\n" +" 0, /* tp_call */\n" +" 0, /* tp_str */\n" +" 0, /* tp_getattro */\n" +" 0, /* tp_setattro */\n" +" 0, /* tp_as_buffer */\n" +" 0, /* tp_flags */\n" +" PyDoc_STR(\"My objects\"), /* tp_doc */\n" +" 0, /* tp_traverse */\n" +" 0, /* tp_clear */\n" +" 0, /* tp_richcompare */\n" +" 0, /* tp_weaklistoffset */\n" +" 0, /* tp_iter */\n" +" 0, /* tp_iternext */\n" +" 0, /* tp_methods */\n" +" 0, /* tp_members */\n" +" 0, /* tp_getset */\n" +" 0, /* tp_base */\n" +" 0, /* tp_dict */\n" +" 0, /* tp_descr_get */\n" +" 0, /* tp_descr_set */\n" +" 0, /* tp_dictoffset */\n" +" 0, /* tp_init */\n" +" 0, /* tp_alloc */\n" +" myobj_new, /* tp_new */\n" +"};" + +#: ../../c-api/typeobj.rst:3321 +msgid "A type that supports weakrefs, instance dicts, and hashing::" +msgstr "" + +#: ../../c-api/typeobj.rst:3323 +msgid "" +"typedef struct {\n" +" PyObject_HEAD\n" +" const char *data;\n" +"} MyObject;\n" +"\n" +"static PyTypeObject MyObject_Type = {\n" +" PyVarObject_HEAD_INIT(NULL, 0)\n" +" .tp_name = \"mymod.MyObject\",\n" +" .tp_basicsize = sizeof(MyObject),\n" +" .tp_doc = PyDoc_STR(\"My objects\"),\n" +" .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE |\n" +" Py_TPFLAGS_HAVE_GC | Py_TPFLAGS_MANAGED_DICT |\n" +" Py_TPFLAGS_MANAGED_WEAKREF,\n" +" .tp_new = myobj_new,\n" +" .tp_traverse = (traverseproc)myobj_traverse,\n" +" .tp_clear = (inquiry)myobj_clear,\n" +" .tp_alloc = PyType_GenericNew,\n" +" .tp_dealloc = (destructor)myobj_dealloc,\n" +" .tp_repr = (reprfunc)myobj_repr,\n" +" .tp_hash = (hashfunc)myobj_hash,\n" +" .tp_richcompare = PyBaseObject_Type.tp_richcompare,\n" +"};" +msgstr "" + +#: ../../c-api/typeobj.rst:3346 +msgid "" +"A str subclass that cannot be subclassed and cannot be called to create " +"instances (e.g. uses a separate factory func) using :c:macro:" +"`Py_TPFLAGS_DISALLOW_INSTANTIATION` flag::" +msgstr "" + +#: ../../c-api/typeobj.rst:3350 +msgid "" +"typedef struct {\n" +" PyUnicodeObject raw;\n" +" char *extra;\n" +"} MyStr;\n" +"\n" +"static PyTypeObject MyStr_Type = {\n" +" PyVarObject_HEAD_INIT(NULL, 0)\n" +" .tp_name = \"mymod.MyStr\",\n" +" .tp_basicsize = sizeof(MyStr),\n" +" .tp_base = NULL, // set to &PyUnicode_Type in module init\n" +" .tp_doc = PyDoc_STR(\"my custom str\"),\n" +" .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_DISALLOW_INSTANTIATION,\n" +" .tp_repr = (reprfunc)myobj_repr,\n" +"};" +msgstr "" + +#: ../../c-api/typeobj.rst:3365 +msgid "" +"The simplest :ref:`static type ` with fixed-length instances::" +msgstr "" + +#: ../../c-api/typeobj.rst:3367 +msgid "" +"typedef struct {\n" +" PyObject_HEAD\n" +"} MyObject;\n" +"\n" +"static PyTypeObject MyObject_Type = {\n" +" PyVarObject_HEAD_INIT(NULL, 0)\n" +" .tp_name = \"mymod.MyObject\",\n" +"};" +msgstr "" +"typedef struct {\n" +" PyObject_HEAD\n" +"} MyObject;\n" +"\n" +"static PyTypeObject MyObject_Type = {\n" +" PyVarObject_HEAD_INIT(NULL, 0)\n" +" .tp_name = \"mymod.MyObject\",\n" +"};" + +#: ../../c-api/typeobj.rst:3376 +msgid "" +"The simplest :ref:`static type ` with variable-length " +"instances::" +msgstr "" + +#: ../../c-api/typeobj.rst:3378 +msgid "" +"typedef struct {\n" +" PyObject_VAR_HEAD\n" +" const char *data[1];\n" +"} MyObject;\n" +"\n" +"static PyTypeObject MyObject_Type = {\n" +" PyVarObject_HEAD_INIT(NULL, 0)\n" +" .tp_name = \"mymod.MyObject\",\n" +" .tp_basicsize = sizeof(MyObject) - sizeof(char *),\n" +" .tp_itemsize = sizeof(char *),\n" +"};" +msgstr "" +"typedef struct {\n" +" PyObject_VAR_HEAD\n" +" const char *data[1];\n" +"} MyObject;\n" +"\n" +"static PyTypeObject MyObject_Type = {\n" +" PyVarObject_HEAD_INIT(NULL, 0)\n" +" .tp_name = \"mymod.MyObject\",\n" +" .tp_basicsize = sizeof(MyObject) - sizeof(char *),\n" +" .tp_itemsize = sizeof(char *),\n" +"};" + +#: ../../c-api/typeobj.rst:920 ../../c-api/typeobj.rst:987 +msgid "built-in function" +msgstr "built-in function（內建函式）" + +#: ../../c-api/typeobj.rst:920 +msgid "repr" +msgstr "repr" + +#: ../../c-api/typeobj.rst:987 +msgid "hash" +msgstr "hash（雜湊）" diff --git a/c-api/unicode.po b/c-api/unicode.po index 7d9e21a667..b894478b58 100644 --- a/c-api/unicode.po +++ b/c-api/unicode.po @@ -1,2354 +1,2354 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Leon H., 2017 -# Liang-Bo Wang , 2016 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-05 00:16+0000\n" -"PO-Revision-Date: 2018-05-23 14:08+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" - -#: ../../c-api/unicode.rst:6 -msgid "Unicode Objects and Codecs" -msgstr "Unicode 物件與編解碼器" - -#: ../../c-api/unicode.rst:12 -msgid "Unicode Objects" -msgstr "Unicode 物件" - -#: ../../c-api/unicode.rst:14 -msgid "" -"Since the implementation of :pep:`393` in Python 3.3, Unicode objects " -"internally use a variety of representations, in order to allow handling the " -"complete range of Unicode characters while staying memory efficient. There " -"are special cases for strings where all code points are below 128, 256, or " -"65536; otherwise, code points must be below 1114112 (which is the full " -"Unicode range)." -msgstr "" - -#: ../../c-api/unicode.rst:20 -msgid "" -"UTF-8 representation is created on demand and cached in the Unicode object." -msgstr "UTF-8 表示法會在需要時建立並快取在 Unicode 物件中。" - -#: ../../c-api/unicode.rst:23 -msgid "" -"The :c:type:`Py_UNICODE` representation has been removed since Python 3.12 " -"with deprecated APIs. See :pep:`623` for more information." -msgstr "" -"自 Python 3.12 起，已移除 :c:type:`Py_UNICODE` 表示法，並標示為已棄用的 API。" -"更多資訊請參閱 :pep:`623`。" - -#: ../../c-api/unicode.rst:29 -msgid "Unicode Type" -msgstr "Unicode 型別" - -#: ../../c-api/unicode.rst:31 -msgid "" -"These are the basic Unicode object types used for the Unicode implementation " -"in Python:" -msgstr "這些是 Python 中用於 Unicode 實作的基本 Unicode 物件型別：" - -#: ../../c-api/unicode.rst:36 -msgid "" -"This instance of :c:type:`PyTypeObject` represents the Python Unicode type. " -"It is exposed to Python code as :py:class:`str`." -msgstr "" - -#: ../../c-api/unicode.rst:42 -msgid "" -"This instance of :c:type:`PyTypeObject` represents the Python Unicode " -"iterator type. It is used to iterate over Unicode string objects." -msgstr "" - -#: ../../c-api/unicode.rst:50 -msgid "" -"These types are typedefs for unsigned integer types wide enough to contain " -"characters of 32 bits, 16 bits and 8 bits, respectively. When dealing with " -"single Unicode characters, use :c:type:`Py_UCS4`." -msgstr "" - -#: ../../c-api/unicode.rst:61 -msgid "" -"These subtypes of :c:type:`PyObject` represent a Python Unicode object. In " -"almost all cases, they shouldn't be used directly, since all API functions " -"that deal with Unicode objects take and return :c:type:`PyObject` pointers." -msgstr "" - -#: ../../c-api/unicode.rst:68 -msgid "" -"The following APIs are C macros and static inlined functions for fast checks " -"and access to internal read-only data of Unicode objects:" -msgstr "" - -#: ../../c-api/unicode.rst:73 -msgid "" -"Return true if the object *obj* is a Unicode object or an instance of a " -"Unicode subtype. This function always succeeds." -msgstr "" - -#: ../../c-api/unicode.rst:79 -msgid "" -"Return true if the object *obj* is a Unicode object, but not an instance of " -"a subtype. This function always succeeds." -msgstr "" - -#: ../../c-api/unicode.rst:85 -msgid "" -"Return the length of the Unicode string, in code points. *unicode* has to " -"be a Unicode object in the \"canonical\" representation (not checked)." -msgstr "" - -#: ../../c-api/unicode.rst:95 -msgid "" -"Return a pointer to the canonical representation cast to UCS1, UCS2 or UCS4 " -"integer types for direct character access. No checks are performed if the " -"canonical representation has the correct character size; use :c:func:" -"`PyUnicode_KIND` to select the right function." -msgstr "" - -#: ../../c-api/unicode.rst:107 -msgid "Return values of the :c:func:`PyUnicode_KIND` macro." -msgstr "" - -#: ../../c-api/unicode.rst:111 -msgid "``PyUnicode_WCHAR_KIND`` has been removed." -msgstr "``PyUnicode_WCHAR_KIND`` 已被移除。" - -#: ../../c-api/unicode.rst:117 -msgid "" -"Return one of the PyUnicode kind constants (see above) that indicate how " -"many bytes per character this Unicode object uses to store its data. " -"*unicode* has to be a Unicode object in the \"canonical\" representation " -"(not checked)." -msgstr "" - -#: ../../c-api/unicode.rst:126 -msgid "" -"Return a void pointer to the raw Unicode buffer. *unicode* has to be a " -"Unicode object in the \"canonical\" representation (not checked)." -msgstr "" - -#: ../../c-api/unicode.rst:135 -msgid "" -"Write the code point *value* to the given zero-based *index* in a string." -msgstr "" - -#: ../../c-api/unicode.rst:137 -msgid "" -"The *kind* value and *data* pointer must have been obtained from a string " -"using :c:func:`PyUnicode_KIND` and :c:func:`PyUnicode_DATA` respectively. " -"You must hold a reference to that string while calling :c:func:`!" -"PyUnicode_WRITE`. All requirements of :c:func:`PyUnicode_WriteChar` also " -"apply." -msgstr "" - -#: ../../c-api/unicode.rst:143 -msgid "" -"The function performs no checks for any of its requirements, and is intended " -"for usage in loops." -msgstr "" - -#: ../../c-api/unicode.rst:152 -msgid "" -"Read a code point from a canonical representation *data* (as obtained with :" -"c:func:`PyUnicode_DATA`). No checks or ready calls are performed." -msgstr "" - -#: ../../c-api/unicode.rst:160 -msgid "" -"Read a character from a Unicode object *unicode*, which must be in the " -"\"canonical\" representation. This is less efficient than :c:func:" -"`PyUnicode_READ` if you do multiple consecutive reads." -msgstr "" - -#: ../../c-api/unicode.rst:169 -msgid "" -"Return the maximum code point that is suitable for creating another string " -"based on *unicode*, which must be in the \"canonical\" representation. This " -"is always an approximation but more efficient than iterating over the string." -msgstr "" - -#: ../../c-api/unicode.rst:178 -msgid "" -"Return ``1`` if the string is a valid identifier according to the language " -"definition, section :ref:`identifiers`. Return ``0`` otherwise." -msgstr "" - -#: ../../c-api/unicode.rst:181 -msgid "" -"The function does not call :c:func:`Py_FatalError` anymore if the string is " -"not ready." -msgstr "" - -#: ../../c-api/unicode.rst:188 -msgid "" -"Return true if the string only contains ASCII characters. Equivalent to :py:" -"meth:`str.isascii`." -msgstr "" - -#: ../../c-api/unicode.rst:195 -msgid "Unicode Character Properties" -msgstr "" - -#: ../../c-api/unicode.rst:197 -msgid "" -"Unicode provides many different character properties. The most often needed " -"ones are available through these macros which are mapped to C functions " -"depending on the Python configuration." -msgstr "" - -#: ../../c-api/unicode.rst:204 -msgid "" -"Return ``1`` or ``0`` depending on whether *ch* is a whitespace character." -msgstr "根據 *ch* 是否為空白字元來回傳 ``1`` 或 ``0``。" - -#: ../../c-api/unicode.rst:209 -msgid "" -"Return ``1`` or ``0`` depending on whether *ch* is a lowercase character." -msgstr "根據 *ch* 是否為小寫字元來回傳 ``1`` 或 ``0``。" - -#: ../../c-api/unicode.rst:214 -msgid "" -"Return ``1`` or ``0`` depending on whether *ch* is an uppercase character." -msgstr "根據 *ch* 是否為大寫字元來回傳 ``1`` 或 ``0``。" - -#: ../../c-api/unicode.rst:219 -msgid "" -"Return ``1`` or ``0`` depending on whether *ch* is a titlecase character." -msgstr "根據 *ch* 是否為首字大寫字元來回傳 ``1`` 或 ``0``。" - -#: ../../c-api/unicode.rst:224 -msgid "" -"Return ``1`` or ``0`` depending on whether *ch* is a linebreak character." -msgstr "根據 *ch* 是否為換行字元來回傳 ``1`` 或 ``0``。" - -#: ../../c-api/unicode.rst:229 -msgid "Return ``1`` or ``0`` depending on whether *ch* is a decimal character." -msgstr "根據 *ch* 是否為十進位字元來回傳 ``1`` 或 ``0``。" - -#: ../../c-api/unicode.rst:234 -msgid "Return ``1`` or ``0`` depending on whether *ch* is a digit character." -msgstr "根據 *ch* 是否為數字 (digit) 字元來回傳 ``1`` 或 ``0``。" - -#: ../../c-api/unicode.rst:239 -msgid "Return ``1`` or ``0`` depending on whether *ch* is a numeric character." -msgstr "根據 *ch* 是否為數值 (numeric) 字元來回傳 ``1`` 或 ``0``。" - -#: ../../c-api/unicode.rst:244 -msgid "" -"Return ``1`` or ``0`` depending on whether *ch* is an alphabetic character." -msgstr "根據 *ch* 是否為字母字元來回傳 ``1`` 或 ``0``。" - -#: ../../c-api/unicode.rst:249 -msgid "" -"Return ``1`` or ``0`` depending on whether *ch* is an alphanumeric character." -msgstr "根據 *ch* 是否為字母數字 (alphanumeric) 字元來回傳 ``1`` 或 ``0``。" - -#: ../../c-api/unicode.rst:254 -msgid "" -"Return ``1`` or ``0`` depending on whether *ch* is a printable character, in " -"the sense of :meth:`str.isprintable`." -msgstr "" -"根據 *ch* 是否為可列印字元（如 :meth:`str.isprintable` 所定義）來回傳 ``1`` " -"或 ``0``。" - -#: ../../c-api/unicode.rst:258 -msgid "These APIs can be used for fast direct character conversions:" -msgstr "這些 API 可用於快速直接字元轉換：" - -#: ../../c-api/unicode.rst:263 -msgid "Return the character *ch* converted to lower case." -msgstr "回傳轉換為小寫的 *ch* 字元。" - -#: ../../c-api/unicode.rst:268 -msgid "Return the character *ch* converted to upper case." -msgstr "回傳轉換為大寫的 *ch* 字元。" - -#: ../../c-api/unicode.rst:273 -msgid "Return the character *ch* converted to title case." -msgstr "回傳轉換為首字大寫的 *ch* 字元。" - -#: ../../c-api/unicode.rst:278 -msgid "" -"Return the character *ch* converted to a decimal positive integer. Return " -"``-1`` if this is not possible. This function does not raise exceptions." -msgstr "" -"回傳轉換為十進位正整數的 *ch* 字元，若無法轉換則回傳 ``-1``。此函式不會引發例" -"外。" - -#: ../../c-api/unicode.rst:284 -msgid "" -"Return the character *ch* converted to a single digit integer. Return ``-1`` " -"if this is not possible. This function does not raise exceptions." -msgstr "" -"回傳轉換為單一數字整數的 *ch* 字元，若無法轉換則回傳 ``-1``。此函式不會引發例" -"外。" - -#: ../../c-api/unicode.rst:290 -msgid "" -"Return the character *ch* converted to a double. Return ``-1.0`` if this is " -"not possible. This function does not raise exceptions." -msgstr "" -"回傳轉換為雙精度浮點數 (double) 的 *ch* 字元，若無法轉換則回傳 ``-1.0``。此函" -"式不會引發例外。" - -#: ../../c-api/unicode.rst:294 -msgid "These APIs can be used to work with surrogates:" -msgstr "這些 API 可用於處理代理字元：" - -#: ../../c-api/unicode.rst:298 -msgid "Check if *ch* is a surrogate (``0xD800 <= ch <= 0xDFFF``)." -msgstr "檢查 *ch* 是否為代理字元 (surrogate, ``0xD800 <= ch <= 0xDFFF``)。" - -#: ../../c-api/unicode.rst:302 -msgid "Check if *ch* is a high surrogate (``0xD800 <= ch <= 0xDBFF``)." -msgstr "" -"檢查 *ch* 是否為高代理字元 (high surrogate, ``0xD800 <= ch <= 0xDBFF``)。" - -#: ../../c-api/unicode.rst:306 -msgid "Check if *ch* is a low surrogate (``0xDC00 <= ch <= 0xDFFF``)." -msgstr "" -"檢查 *ch* 是否為低代理字元 (low surrogate, ``0xDC00 <= ch <= 0xDFFF``)。" - -#: ../../c-api/unicode.rst:310 -msgid "" -"Return the high UTF-16 surrogate (``0xD800`` to ``0xDBFF``) for a Unicode " -"code point in the range ``[0x10000; 0x10FFFF]``." -msgstr "" - -#: ../../c-api/unicode.rst:315 -msgid "" -"Return the low UTF-16 surrogate (``0xDC00`` to ``0xDFFF``) for a Unicode " -"code point in the range ``[0x10000; 0x10FFFF]``." -msgstr "" - -#: ../../c-api/unicode.rst:320 -msgid "" -"Join two surrogate code points and return a single :c:type:`Py_UCS4` value. " -"*high* and *low* are respectively the leading and trailing surrogates in a " -"surrogate pair. *high* must be in the range ``[0xD800; 0xDBFF]`` and *low* " -"must be in the range ``[0xDC00; 0xDFFF]``." -msgstr "" - -#: ../../c-api/unicode.rst:327 -msgid "Creating and accessing Unicode strings" -msgstr "" - -#: ../../c-api/unicode.rst:329 -msgid "" -"To create Unicode objects and access their basic sequence properties, use " -"these APIs:" -msgstr "" - -#: ../../c-api/unicode.rst:334 -msgid "" -"Create a new Unicode object. *maxchar* should be the true maximum code " -"point to be placed in the string. As an approximation, it can be rounded up " -"to the nearest value in the sequence 127, 255, 65535, 1114111." -msgstr "" - -#: ../../c-api/unicode.rst:338 -msgid "On error, set an exception and return ``NULL``." -msgstr "" - -#: ../../c-api/unicode.rst:340 -msgid "" -"After creation, the string can be filled by :c:func:`PyUnicode_WriteChar`, :" -"c:func:`PyUnicode_CopyCharacters`, :c:func:`PyUnicode_Fill`, :c:func:" -"`PyUnicode_WRITE` or similar. Since strings are supposed to be immutable, " -"take care to not “use” the result while it is being modified. In particular, " -"before it's filled with its final contents, a string:" -msgstr "" - -#: ../../c-api/unicode.rst:347 -msgid "must not be hashed," -msgstr "" - -#: ../../c-api/unicode.rst:348 -msgid "" -"must not be :c:func:`converted to UTF-8 `, or " -"another non-\"canonical\" representation," -msgstr "" - -#: ../../c-api/unicode.rst:350 -msgid "must not have its reference count changed," -msgstr "" - -#: ../../c-api/unicode.rst:351 -msgid "must not be shared with code that might do one of the above." -msgstr "" - -#: ../../c-api/unicode.rst:353 -msgid "" -"This list is not exhaustive. Avoiding these uses is your responsibility; " -"Python does not always check these requirements." -msgstr "" - -#: ../../c-api/unicode.rst:356 -msgid "" -"To avoid accidentally exposing a partially-written string object, prefer " -"using the :c:type:`PyUnicodeWriter` API, or one of the ``PyUnicode_From*`` " -"functions below." -msgstr "" - -#: ../../c-api/unicode.rst:367 -msgid "" -"Create a new Unicode object with the given *kind* (possible values are :c:" -"macro:`PyUnicode_1BYTE_KIND` etc., as returned by :c:func:" -"`PyUnicode_KIND`). The *buffer* must point to an array of *size* units of " -"1, 2 or 4 bytes per character, as given by the kind." -msgstr "" - -#: ../../c-api/unicode.rst:372 -msgid "" -"If necessary, the input *buffer* is copied and transformed into the " -"canonical representation. For example, if the *buffer* is a UCS4 string (:c:" -"macro:`PyUnicode_4BYTE_KIND`) and it consists only of codepoints in the UCS1 " -"range, it will be transformed into UCS1 (:c:macro:`PyUnicode_1BYTE_KIND`)." -msgstr "" - -#: ../../c-api/unicode.rst:383 -msgid "" -"Create a Unicode object from the char buffer *str*. The bytes will be " -"interpreted as being UTF-8 encoded. The buffer is copied into the new " -"object. The return value might be a shared object, i.e. modification of the " -"data is not allowed." -msgstr "" - -#: ../../c-api/unicode.rst:389 -msgid "This function raises :exc:`SystemError` when:" -msgstr "此函式在以下情況下會引發 :exc:`SystemError`：" - -#: ../../c-api/unicode.rst:391 -msgid "*size* < 0," -msgstr "*size* < 0，" - -#: ../../c-api/unicode.rst:392 -msgid "*str* is ``NULL`` and *size* > 0" -msgstr "*str* 為 ``NULL`` 且 *size* > 0" - -#: ../../c-api/unicode.rst:394 -msgid "*str* == ``NULL`` with *size* > 0 is not allowed anymore." -msgstr "*str* == ``NULL`` 且 *size* > 0 不再被允許。" - -#: ../../c-api/unicode.rst:400 -msgid "" -"Create a Unicode object from a UTF-8 encoded null-terminated char buffer " -"*str*." -msgstr "" - -#: ../../c-api/unicode.rst:406 -msgid "" -"Take a C :c:func:`printf`\\ -style *format* string and a variable number of " -"arguments, calculate the size of the resulting Python Unicode string and " -"return a string with the values formatted into it. The variable arguments " -"must be C types and must correspond exactly to the format characters in the " -"*format* ASCII-encoded string." -msgstr "" - -#: ../../c-api/unicode.rst:412 -msgid "" -"A conversion specifier contains two or more characters and has the following " -"components, which must occur in this order:" -msgstr "" - -#: ../../c-api/unicode.rst:415 -msgid "The ``'%'`` character, which marks the start of the specifier." -msgstr "" - -#: ../../c-api/unicode.rst:417 -msgid "" -"Conversion flags (optional), which affect the result of some conversion " -"types." -msgstr "" - -#: ../../c-api/unicode.rst:420 -msgid "" -"Minimum field width (optional). If specified as an ``'*'`` (asterisk), the " -"actual width is given in the next argument, which must be of type :c:expr:" -"`int`, and the object to convert comes after the minimum field width and " -"optional precision." -msgstr "" - -#: ../../c-api/unicode.rst:425 -msgid "" -"Precision (optional), given as a ``'.'`` (dot) followed by the precision. If " -"specified as ``'*'`` (an asterisk), the actual precision is given in the " -"next argument, which must be of type :c:expr:`int`, and the value to convert " -"comes after the precision." -msgstr "" - -#: ../../c-api/unicode.rst:430 -msgid "Length modifier (optional)." -msgstr "" - -#: ../../c-api/unicode.rst:432 -msgid "Conversion type." -msgstr "" - -#: ../../c-api/unicode.rst:434 -msgid "The conversion flag characters are:" -msgstr "" - -#: ../../c-api/unicode.rst:439 -msgid "Flag" -msgstr "旗標" - -#: ../../c-api/unicode.rst:439 -msgid "Meaning" -msgstr "含義" - -#: ../../c-api/unicode.rst:441 -msgid "``0``" -msgstr "``0``" - -#: ../../c-api/unicode.rst:441 -msgid "The conversion will be zero padded for numeric values." -msgstr "" - -#: ../../c-api/unicode.rst:443 -msgid "``-``" -msgstr "``-``" - -#: ../../c-api/unicode.rst:443 -msgid "" -"The converted value is left adjusted (overrides the ``0`` flag if both are " -"given)." -msgstr "" - -#: ../../c-api/unicode.rst:447 -msgid "" -"The length modifiers for following integer conversions (``d``, ``i``, ``o``, " -"``u``, ``x``, or ``X``) specify the type of the argument (:c:expr:`int` by " -"default):" -msgstr "" - -#: ../../c-api/unicode.rst:454 -msgid "Modifier" -msgstr "" - -#: ../../c-api/unicode.rst:454 -msgid "Types" -msgstr "" - -#: ../../c-api/unicode.rst:456 -msgid "``l``" -msgstr "``l``" - -#: ../../c-api/unicode.rst:456 -msgid ":c:expr:`long` or :c:expr:`unsigned long`" -msgstr ":c:expr:`long` 或 :c:expr:`unsigned long`" - -#: ../../c-api/unicode.rst:458 -msgid "``ll``" -msgstr "``ll``" - -#: ../../c-api/unicode.rst:458 -msgid ":c:expr:`long long` or :c:expr:`unsigned long long`" -msgstr ":c:expr:`long long` 或 :c:expr:`unsigned long long`" - -#: ../../c-api/unicode.rst:460 -msgid "``j``" -msgstr "``j``" - -#: ../../c-api/unicode.rst:460 -msgid ":c:type:`intmax_t` or :c:type:`uintmax_t`" -msgstr ":c:type:`intmax_t` 或 :c:type:`uintmax_t`" - -#: ../../c-api/unicode.rst:462 -msgid "``z``" -msgstr "``z``" - -#: ../../c-api/unicode.rst:462 -msgid ":c:type:`size_t` or :c:type:`ssize_t`" -msgstr ":c:type:`size_t` 或 :c:type:`ssize_t`" - -#: ../../c-api/unicode.rst:464 -msgid "``t``" -msgstr "``t``" - -#: ../../c-api/unicode.rst:464 -msgid ":c:type:`ptrdiff_t`" -msgstr ":c:type:`ptrdiff_t`" - -#: ../../c-api/unicode.rst:467 -msgid "" -"The length modifier ``l`` for following conversions ``s`` or ``V`` specify " -"that the type of the argument is :c:expr:`const wchar_t*`." -msgstr "" - -#: ../../c-api/unicode.rst:470 -msgid "The conversion specifiers are:" -msgstr "" - -#: ../../c-api/unicode.rst:476 -msgid "Conversion Specifier" -msgstr "" - -#: ../../c-api/unicode.rst:477 -msgid "Type" -msgstr "" - -#: ../../c-api/unicode.rst:478 -msgid "Comment" -msgstr "" - -#: ../../c-api/unicode.rst:480 -msgid "``%``" -msgstr "``%``" - -#: ../../c-api/unicode.rst:481 -msgid "*n/a*" -msgstr "*n/a*" - -#: ../../c-api/unicode.rst:482 -msgid "The literal ``%`` character." -msgstr "字面 ``%`` 字元。" - -#: ../../c-api/unicode.rst:484 -msgid "``d``, ``i``" -msgstr "``d``, ``i``" - -#: ../../c-api/unicode.rst:485 ../../c-api/unicode.rst:489 -#: ../../c-api/unicode.rst:493 ../../c-api/unicode.rst:497 -#: ../../c-api/unicode.rst:501 -msgid "Specified by the length modifier" -msgstr "" - -#: ../../c-api/unicode.rst:486 -msgid "The decimal representation of a signed C integer." -msgstr "一個有符號 C 整數的十進位表示法。" - -#: ../../c-api/unicode.rst:488 -msgid "``u``" -msgstr "``u``" - -#: ../../c-api/unicode.rst:490 -msgid "The decimal representation of an unsigned C integer." -msgstr "一個無符號 C 整數的十進位表示法。" - -#: ../../c-api/unicode.rst:492 -msgid "``o``" -msgstr "``o``" - -#: ../../c-api/unicode.rst:494 -msgid "The octal representation of an unsigned C integer." -msgstr "一個無符號 C 整數的八進位表示法。" - -#: ../../c-api/unicode.rst:496 -msgid "``x``" -msgstr "``x``" - -#: ../../c-api/unicode.rst:498 -msgid "The hexadecimal representation of an unsigned C integer (lowercase)." -msgstr "一個無符號 C 整數的十六進位表示法（小寫）。" - -#: ../../c-api/unicode.rst:500 -msgid "``X``" -msgstr "``X``" - -#: ../../c-api/unicode.rst:502 -msgid "The hexadecimal representation of an unsigned C integer (uppercase)." -msgstr "一個無符號 C 整數的十六進位表示法（大寫）。" - -#: ../../c-api/unicode.rst:504 -msgid "``c``" -msgstr "``c``" - -#: ../../c-api/unicode.rst:505 -msgid ":c:expr:`int`" -msgstr ":c:expr:`int`" - -#: ../../c-api/unicode.rst:506 -msgid "A single character." -msgstr "一個單一字元。" - -#: ../../c-api/unicode.rst:508 -msgid "``s``" -msgstr "``s``" - -#: ../../c-api/unicode.rst:509 -msgid ":c:expr:`const char*` or :c:expr:`const wchar_t*`" -msgstr ":c:expr:`const char*` 或 :c:expr:`const wchar_t*`" - -#: ../../c-api/unicode.rst:510 -msgid "A null-terminated C character array." -msgstr "一個以 null 結尾的 C 字元陣列。" - -#: ../../c-api/unicode.rst:512 -msgid "``p``" -msgstr "``p``" - -#: ../../c-api/unicode.rst:513 -msgid ":c:expr:`const void*`" -msgstr ":c:expr:`const void*`" - -#: ../../c-api/unicode.rst:514 -msgid "" -"The hex representation of a C pointer. Mostly equivalent to " -"``printf(\"%p\")`` except that it is guaranteed to start with the literal " -"``0x`` regardless of what the platform's ``printf`` yields." -msgstr "" - -#: ../../c-api/unicode.rst:519 -msgid "``A``" -msgstr "``A``" - -#: ../../c-api/unicode.rst:520 ../../c-api/unicode.rst:524 -#: ../../c-api/unicode.rst:534 ../../c-api/unicode.rst:538 -#: ../../c-api/unicode.rst:542 ../../c-api/unicode.rst:547 -msgid ":c:expr:`PyObject*`" -msgstr ":c:expr:`PyObject*`" - -#: ../../c-api/unicode.rst:521 -msgid "The result of calling :func:`ascii`." -msgstr "呼叫 :func:`ascii` 的結果。" - -#: ../../c-api/unicode.rst:523 -msgid "``U``" -msgstr "``U``" - -#: ../../c-api/unicode.rst:525 -msgid "A Unicode object." -msgstr "一個 Unicode 物件。" - -#: ../../c-api/unicode.rst:527 -msgid "``V``" -msgstr "``V``" - -#: ../../c-api/unicode.rst:528 -msgid ":c:expr:`PyObject*`, :c:expr:`const char*` or :c:expr:`const wchar_t*`" -msgstr ":c:expr:`PyObject*`、:c:expr:`const char*` 或 :c:expr:`const wchar_t*`" - -#: ../../c-api/unicode.rst:529 -msgid "" -"A Unicode object (which may be ``NULL``) and a null-terminated C character " -"array as a second parameter (which will be used, if the first parameter is " -"``NULL``)." -msgstr "" - -#: ../../c-api/unicode.rst:533 -msgid "``S``" -msgstr "``S``" - -#: ../../c-api/unicode.rst:535 -msgid "The result of calling :c:func:`PyObject_Str`." -msgstr "呼叫 :c:func:`PyObject_Str` 的結果。" - -#: ../../c-api/unicode.rst:537 -msgid "``R``" -msgstr "``R``" - -#: ../../c-api/unicode.rst:539 -msgid "The result of calling :c:func:`PyObject_Repr`." -msgstr "呼叫 :c:func:`PyObject_Repr` 的結果。" - -#: ../../c-api/unicode.rst:541 -msgid "``T``" -msgstr "``T``" - -#: ../../c-api/unicode.rst:543 -msgid "" -"Get the fully qualified name of an object type; call :c:func:" -"`PyType_GetFullyQualifiedName`." -msgstr "" - -#: ../../c-api/unicode.rst:546 -msgid "``#T``" -msgstr "``#T``" - -#: ../../c-api/unicode.rst:548 -msgid "" -"Similar to ``T`` format, but use a colon (``:``) as separator between the " -"module name and the qualified name." -msgstr "" - -#: ../../c-api/unicode.rst:551 -msgid "``N``" -msgstr "``N``" - -#: ../../c-api/unicode.rst:552 ../../c-api/unicode.rst:557 -msgid ":c:expr:`PyTypeObject*`" -msgstr ":c:expr:`PyTypeObject*`" - -#: ../../c-api/unicode.rst:553 -msgid "" -"Get the fully qualified name of a type; call :c:func:" -"`PyType_GetFullyQualifiedName`." -msgstr "" - -#: ../../c-api/unicode.rst:556 -msgid "``#N``" -msgstr "``#N``" - -#: ../../c-api/unicode.rst:558 -msgid "" -"Similar to ``N`` format, but use a colon (``:``) as separator between the " -"module name and the qualified name." -msgstr "" - -#: ../../c-api/unicode.rst:562 -msgid "" -"The width formatter unit is number of characters rather than bytes. The " -"precision formatter unit is number of bytes or :c:type:`wchar_t` items (if " -"the length modifier ``l`` is used) for ``\"%s\"`` and ``\"%V\"`` (if the " -"``PyObject*`` argument is ``NULL``), and a number of characters for " -"``\"%A\"``, ``\"%U\"``, ``\"%S\"``, ``\"%R\"`` and ``\"%V\"`` (if the " -"``PyObject*`` argument is not ``NULL``)." -msgstr "" - -#: ../../c-api/unicode.rst:570 -msgid "" -"Unlike to C :c:func:`printf` the ``0`` flag has effect even when a precision " -"is given for integer conversions (``d``, ``i``, ``u``, ``o``, ``x``, or " -"``X``)." -msgstr "" - -#: ../../c-api/unicode.rst:574 -msgid "Support for ``\"%lld\"`` and ``\"%llu\"`` added." -msgstr "新增對 ``\"%lld\"`` 和 ``\"%llu\"`` 的支援。" - -#: ../../c-api/unicode.rst:577 -msgid "Support for ``\"%li\"``, ``\"%lli\"`` and ``\"%zi\"`` added." -msgstr "新增對 ``\"%li\"``、``\"%lli\"`` 和 ``\"%zi\"`` 的支援。" - -#: ../../c-api/unicode.rst:580 -msgid "" -"Support width and precision formatter for ``\"%s\"``, ``\"%A\"``, " -"``\"%U\"``, ``\"%V\"``, ``\"%S\"``, ``\"%R\"`` added." -msgstr "" -"新增對 ``\"%s\"``、``\"%A\"``、``\"%U\"``、``\"%V\"``、``\"%S\"``、" -"``\"%R\"`` 的寬度和精確度格式化支援。" - -#: ../../c-api/unicode.rst:584 -msgid "" -"Support for conversion specifiers ``o`` and ``X``. Support for length " -"modifiers ``j`` and ``t``. Length modifiers are now applied to all integer " -"conversions. Length modifier ``l`` is now applied to conversion specifiers " -"``s`` and ``V``. Support for variable width and precision ``*``. Support for " -"flag ``-``." -msgstr "" - -#: ../../c-api/unicode.rst:592 -msgid "" -"An unrecognized format character now sets a :exc:`SystemError`. In previous " -"versions it caused all the rest of the format string to be copied as-is to " -"the result string, and any extra arguments discarded." -msgstr "" - -#: ../../c-api/unicode.rst:596 -msgid "Support for ``%T``, ``%#T``, ``%N`` and ``%#N`` formats added." -msgstr "新增對 ``%T``、``%#T``、``%N`` 和 ``%#N`` 格式的支援。" - -#: ../../c-api/unicode.rst:602 -msgid "" -"Identical to :c:func:`PyUnicode_FromFormat` except that it takes exactly two " -"arguments." -msgstr "" - -#: ../../c-api/unicode.rst:608 -msgid "" -"Copy an instance of a Unicode subtype to a new true Unicode object if " -"necessary. If *obj* is already a true Unicode object (not a subtype), return " -"a new :term:`strong reference` to the object." -msgstr "" - -#: ../../c-api/unicode.rst:612 -msgid "" -"Objects other than Unicode or its subtypes will cause a :exc:`TypeError`." -msgstr "" - -#: ../../c-api/unicode.rst:617 -msgid "Create a Unicode Object from the given Unicode code point *ordinal*." -msgstr "" - -#: ../../c-api/unicode.rst:619 -msgid "" -"The ordinal must be in ``range(0x110000)``. A :exc:`ValueError` is raised in " -"the case it is not." -msgstr "" - -#: ../../c-api/unicode.rst:626 -msgid "Decode an encoded object *obj* to a Unicode object." -msgstr "" - -#: ../../c-api/unicode.rst:628 -msgid "" -":class:`bytes`, :class:`bytearray` and other :term:`bytes-like objects " -"` are decoded according to the given *encoding* and using " -"the error handling defined by *errors*. Both can be ``NULL`` to have the " -"interface use the default values (see :ref:`builtincodecs` for details)." -msgstr "" - -#: ../../c-api/unicode.rst:634 -msgid "" -"All other objects, including Unicode objects, cause a :exc:`TypeError` to be " -"set." -msgstr "" - -#: ../../c-api/unicode.rst:637 -msgid "" -"The API returns ``NULL`` if there was an error. The caller is responsible " -"for decref'ing the returned objects." -msgstr "" - -#: ../../c-api/unicode.rst:643 -msgid "" -"Append the string *right* to the end of *p_left*. *p_left* must point to a :" -"term:`strong reference` to a Unicode object; :c:func:`!PyUnicode_Append` " -"releases (\"steals\") this reference." -msgstr "" - -#: ../../c-api/unicode.rst:647 -msgid "On error, set *\\*p_left* to ``NULL`` and set an exception." -msgstr "於錯誤發生時，將 *\\*p_left* 設為 ``NULL`` 並設定例外。" - -#: ../../c-api/unicode.rst:649 -msgid "On success, set *\\*p_left* to a new strong reference to the result." -msgstr "" - -#: ../../c-api/unicode.rst:654 -msgid "" -"The function is similar to :c:func:`PyUnicode_Append`, with the only " -"difference being that it decrements the reference count of *right* by one." -msgstr "" - -#: ../../c-api/unicode.rst:660 -msgid "" -"Return a mapping suitable for decoding a custom single-byte encoding. Given " -"a Unicode string *string* of up to 256 characters representing an encoding " -"table, returns either a compact internal mapping object or a dictionary " -"mapping character ordinals to byte values. Raises a :exc:`TypeError` and " -"return ``NULL`` on invalid input." -msgstr "" - -#: ../../c-api/unicode.rst:671 -msgid "" -"Return the name of the default string encoding, ``\"utf-8\"``. See :func:" -"`sys.getdefaultencoding`." -msgstr "" - -#: ../../c-api/unicode.rst:674 -msgid "" -"The returned string does not need to be freed, and is valid until " -"interpreter shutdown." -msgstr "" - -#: ../../c-api/unicode.rst:680 -msgid "Return the length of the Unicode object, in code points." -msgstr "" - -#: ../../c-api/unicode.rst:682 -msgid "On error, set an exception and return ``-1``." -msgstr "發生錯誤時，設定例外並回傳 ``-1``。" - -#: ../../c-api/unicode.rst:693 -msgid "" -"Copy characters from one Unicode object into another. This function " -"performs character conversion when necessary and falls back to :c:func:`!" -"memcpy` if possible. Returns ``-1`` and sets an exception on error, " -"otherwise returns the number of copied characters." -msgstr "" - -#: ../../c-api/unicode.rst:698 ../../c-api/unicode.rst:728 -#: ../../c-api/unicode.rst:748 -msgid "" -"The string must not have been “used” yet. See :c:func:`PyUnicode_New` for " -"details." -msgstr "" - -#: ../../c-api/unicode.rst:706 -msgid "" -"Resize a Unicode object *\\*unicode* to the new *length* in code points." -msgstr "" - -#: ../../c-api/unicode.rst:708 -msgid "" -"Try to resize the string in place (which is usually faster than allocating a " -"new string and copying characters), or create a new string." -msgstr "" - -#: ../../c-api/unicode.rst:711 -msgid "" -"*\\*unicode* is modified to point to the new (resized) object and ``0`` is " -"returned on success. Otherwise, ``-1`` is returned and an exception is set, " -"and *\\*unicode* is left untouched." -msgstr "" - -#: ../../c-api/unicode.rst:715 -msgid "" -"The function doesn't check string content, the result may not be a string in " -"canonical representation." -msgstr "" - -#: ../../c-api/unicode.rst:722 -msgid "" -"Fill a string with a character: write *fill_char* into ``unicode[start:" -"start+length]``." -msgstr "" - -#: ../../c-api/unicode.rst:725 -msgid "" -"Fail if *fill_char* is bigger than the string maximum character, or if the " -"string has more than 1 reference." -msgstr "" - -#: ../../c-api/unicode.rst:731 -msgid "" -"Return the number of written character, or return ``-1`` and raise an " -"exception on error." -msgstr "" - -#: ../../c-api/unicode.rst:740 -msgid "" -"Write a *character* to the string *unicode* at the zero-based *index*. " -"Return ``0`` on success, ``-1`` on error with an exception set." -msgstr "" - -#: ../../c-api/unicode.rst:743 -msgid "" -"This function checks that *unicode* is a Unicode object, that the index is " -"not out of bounds, and that the object's reference count is one. See :c:func:" -"`PyUnicode_WRITE` for a version that skips these checks, making them your " -"responsibility." -msgstr "" - -#: ../../c-api/unicode.rst:756 -msgid "" -"Read a character from a string. This function checks that *unicode* is a " -"Unicode object and the index is not out of bounds, in contrast to :c:func:" -"`PyUnicode_READ_CHAR`, which performs no error checking." -msgstr "" - -#: ../../c-api/unicode.rst:760 -msgid "Return character on success, ``-1`` on error with an exception set." -msgstr "成功時回傳字元，發生錯誤時設定例外並回傳 ``-1``。" - -#: ../../c-api/unicode.rst:768 -msgid "" -"Return a substring of *unicode*, from character index *start* (included) to " -"character index *end* (excluded). Negative indices are not supported. On " -"error, set an exception and return ``NULL``." -msgstr "" - -#: ../../c-api/unicode.rst:778 -msgid "" -"Copy the string *unicode* into a UCS4 buffer, including a null character, if " -"*copy_null* is set. Returns ``NULL`` and sets an exception on error (in " -"particular, a :exc:`SystemError` if *buflen* is smaller than the length of " -"*unicode*). *buffer* is returned on success." -msgstr "" - -#: ../../c-api/unicode.rst:788 -msgid "" -"Copy the string *unicode* into a new UCS4 buffer that is allocated using :c:" -"func:`PyMem_Malloc`. If this fails, ``NULL`` is returned with a :exc:" -"`MemoryError` set. The returned buffer always has an extra null code point " -"appended." -msgstr "" - -#: ../../c-api/unicode.rst:797 -msgid "Locale Encoding" -msgstr "" - -#: ../../c-api/unicode.rst:799 -msgid "" -"The current locale encoding can be used to decode text from the operating " -"system." -msgstr "" - -#: ../../c-api/unicode.rst:806 -msgid "" -"Decode a string from UTF-8 on Android and VxWorks, or from the current " -"locale encoding on other platforms. The supported error handlers are " -"``\"strict\"`` and ``\"surrogateescape\"`` (:pep:`383`). The decoder uses " -"``\"strict\"`` error handler if *errors* is ``NULL``. *str* must end with a " -"null character but cannot contain embedded null characters." -msgstr "" - -#: ../../c-api/unicode.rst:813 -msgid "" -"Use :c:func:`PyUnicode_DecodeFSDefaultAndSize` to decode a string from the :" -"term:`filesystem encoding and error handler`." -msgstr "" - -#: ../../c-api/unicode.rst:816 ../../c-api/unicode.rst:851 -msgid "This function ignores the :ref:`Python UTF-8 Mode `." -msgstr "此函式會忽略 :ref:`Python UTF-8 模式 `。" - -#: ../../c-api/unicode.rst:820 ../../c-api/unicode.rst:936 -msgid "The :c:func:`Py_DecodeLocale` function." -msgstr ":c:func:`Py_DecodeLocale` 函式。" - -#: ../../c-api/unicode.rst:824 -msgid "" -"The function now also uses the current locale encoding for the " -"``surrogateescape`` error handler, except on Android. Previously, :c:func:" -"`Py_DecodeLocale` was used for the ``surrogateescape``, and the current " -"locale encoding was used for ``strict``." -msgstr "" - -#: ../../c-api/unicode.rst:833 -msgid "" -"Similar to :c:func:`PyUnicode_DecodeLocaleAndSize`, but compute the string " -"length using :c:func:`!strlen`." -msgstr "" -"類似於 :c:func:`PyUnicode_DecodeLocaleAndSize`，但使用 :c:func:`!strlen` 計算" -"字串長度。" - -#: ../../c-api/unicode.rst:841 -msgid "" -"Encode a Unicode object to UTF-8 on Android and VxWorks, or to the current " -"locale encoding on other platforms. The supported error handlers are " -"``\"strict\"`` and ``\"surrogateescape\"`` (:pep:`383`). The encoder uses " -"``\"strict\"`` error handler if *errors* is ``NULL``. Return a :class:" -"`bytes` object. *unicode* cannot contain embedded null characters." -msgstr "" - -#: ../../c-api/unicode.rst:848 -msgid "" -"Use :c:func:`PyUnicode_EncodeFSDefault` to encode a string to the :term:" -"`filesystem encoding and error handler`." -msgstr "" - -#: ../../c-api/unicode.rst:855 ../../c-api/unicode.rst:967 -msgid "The :c:func:`Py_EncodeLocale` function." -msgstr ":c:func:`Py_EncodeLocale` 函式。" - -#: ../../c-api/unicode.rst:859 -msgid "" -"The function now also uses the current locale encoding for the " -"``surrogateescape`` error handler, except on Android. Previously, :c:func:" -"`Py_EncodeLocale` was used for the ``surrogateescape``, and the current " -"locale encoding was used for ``strict``." -msgstr "" - -#: ../../c-api/unicode.rst:868 -msgid "File System Encoding" -msgstr "檔案系統編碼" - -#: ../../c-api/unicode.rst:870 -msgid "" -"Functions encoding to and decoding from the :term:`filesystem encoding and " -"error handler` (:pep:`383` and :pep:`529`)." -msgstr "" - -#: ../../c-api/unicode.rst:873 -msgid "" -"To encode file names to :class:`bytes` during argument parsing, the " -"``\"O&\"`` converter should be used, passing :c:func:`!" -"PyUnicode_FSConverter` as the conversion function:" -msgstr "" - -#: ../../c-api/unicode.rst:879 -msgid "" -":ref:`PyArg_Parse\\* converter `: encode :class:`str` objects " -"-- obtained directly or through the :class:`os.PathLike` interface -- to :" -"class:`bytes` using :c:func:`PyUnicode_EncodeFSDefault`; :class:`bytes` " -"objects are output as-is. *result* must be an address of a C variable of " -"type :c:expr:`PyObject*` (or :c:expr:`PyBytesObject*`). On success, set the " -"variable to a new :term:`strong reference` to a :ref:`bytes object " -"` which must be released when it is no longer used and return " -"a non-zero value (:c:macro:`Py_CLEANUP_SUPPORTED`). Embedded null bytes are " -"not allowed in the result. On failure, return ``0`` with an exception set." -msgstr "" - -#: ../../c-api/unicode.rst:891 -msgid "" -"If *obj* is ``NULL``, the function releases a strong reference stored in the " -"variable referred by *result* and returns ``1``." -msgstr "" - -#: ../../c-api/unicode.rst:896 ../../c-api/unicode.rst:923 -msgid "Accepts a :term:`path-like object`." -msgstr "接受一個 :term:`path-like object`。" - -#: ../../c-api/unicode.rst:899 -msgid "" -"To decode file names to :class:`str` during argument parsing, the ``\"O&\"`` " -"converter should be used, passing :c:func:`!PyUnicode_FSDecoder` as the " -"conversion function:" -msgstr "" - -#: ../../c-api/unicode.rst:905 -msgid "" -":ref:`PyArg_Parse\\* converter `: decode :class:`bytes` objects " -"-- obtained either directly or indirectly through the :class:`os.PathLike` " -"interface -- to :class:`str` using :c:func:" -"`PyUnicode_DecodeFSDefaultAndSize`; :class:`str` objects are output as-is. " -"*result* must be an address of a C variable of type :c:expr:`PyObject*` (or :" -"c:expr:`PyUnicodeObject*`). On success, set the variable to a new :term:" -"`strong reference` to a :ref:`Unicode object ` which must be " -"released when it is no longer used and return a non-zero value (:c:macro:" -"`Py_CLEANUP_SUPPORTED`). Embedded null characters are not allowed in the " -"result. On failure, return ``0`` with an exception set." -msgstr "" - -#: ../../c-api/unicode.rst:918 -msgid "" -"If *obj* is ``NULL``, release the strong reference to the object referred to " -"by *result* and return ``1``." -msgstr "" - -#: ../../c-api/unicode.rst:929 -msgid "Decode a string from the :term:`filesystem encoding and error handler`." -msgstr "" - -#: ../../c-api/unicode.rst:931 -msgid "" -"If you need to decode a string from the current locale encoding, use :c:func:" -"`PyUnicode_DecodeLocaleAndSize`." -msgstr "" - -#: ../../c-api/unicode.rst:938 ../../c-api/unicode.rst:951 -#: ../../c-api/unicode.rst:971 -msgid "" -"The :term:`filesystem error handler ` " -"is now used." -msgstr "" - -#: ../../c-api/unicode.rst:945 -msgid "" -"Decode a null-terminated string from the :term:`filesystem encoding and " -"error handler`." -msgstr "" - -#: ../../c-api/unicode.rst:948 -msgid "" -"If the string length is known, use :c:func:" -"`PyUnicode_DecodeFSDefaultAndSize`." -msgstr "如果字串長度已知，請使用 :c:func:`PyUnicode_DecodeFSDefaultAndSize`。" - -#: ../../c-api/unicode.rst:958 -msgid "" -"Encode a Unicode object to the :term:`filesystem encoding and error " -"handler`, and return :class:`bytes`. Note that the resulting :class:`bytes` " -"object can contain null bytes." -msgstr "" - -#: ../../c-api/unicode.rst:962 -msgid "" -"If you need to encode a string to the current locale encoding, use :c:func:" -"`PyUnicode_EncodeLocale`." -msgstr "" - -#: ../../c-api/unicode.rst:976 -msgid "wchar_t Support" -msgstr "wchar_t 支援" - -#: ../../c-api/unicode.rst:978 -msgid ":c:type:`wchar_t` support for platforms which support it:" -msgstr "對支援 :c:type:`wchar_t` 的平台提供支援：" - -#: ../../c-api/unicode.rst:982 -msgid "" -"Create a Unicode object from the :c:type:`wchar_t` buffer *wstr* of the " -"given *size*. Passing ``-1`` as the *size* indicates that the function must " -"itself compute the length, using :c:func:`!wcslen`. Return ``NULL`` on " -"failure." -msgstr "" - -#: ../../c-api/unicode.rst:990 -msgid "" -"Copy the Unicode object contents into the :c:type:`wchar_t` buffer *wstr*. " -"At most *size* :c:type:`wchar_t` characters are copied (excluding a possibly " -"trailing null termination character). Return the number of :c:type:" -"`wchar_t` characters copied or ``-1`` in case of an error." -msgstr "" - -#: ../../c-api/unicode.rst:995 -msgid "" -"When *wstr* is ``NULL``, instead return the *size* that would be required to " -"store all of *unicode* including a terminating null." -msgstr "" - -#: ../../c-api/unicode.rst:998 -msgid "" -"Note that the resulting :c:expr:`wchar_t*` string may or may not be null-" -"terminated. It is the responsibility of the caller to make sure that the :c:" -"expr:`wchar_t*` string is null-terminated in case this is required by the " -"application. Also, note that the :c:expr:`wchar_t*` string might contain " -"null characters, which would cause the string to be truncated when used with " -"most C functions." -msgstr "" - -#: ../../c-api/unicode.rst:1008 -msgid "" -"Convert the Unicode object to a wide character string. The output string " -"always ends with a null character. If *size* is not ``NULL``, write the " -"number of wide characters (excluding the trailing null termination " -"character) into *\\*size*. Note that the resulting :c:type:`wchar_t` string " -"might contain null characters, which would cause the string to be truncated " -"when used with most C functions. If *size* is ``NULL`` and the :c:expr:" -"`wchar_t*` string contains null characters a :exc:`ValueError` is raised." -msgstr "" - -#: ../../c-api/unicode.rst:1016 -msgid "" -"Returns a buffer allocated by :c:macro:`PyMem_New` (use :c:func:`PyMem_Free` " -"to free it) on success. On error, returns ``NULL`` and *\\*size* is " -"undefined. Raises a :exc:`MemoryError` if memory allocation is failed." -msgstr "" - -#: ../../c-api/unicode.rst:1023 -msgid "" -"Raises a :exc:`ValueError` if *size* is ``NULL`` and the :c:expr:`wchar_t*` " -"string contains null characters." -msgstr "" - -#: ../../c-api/unicode.rst:1031 -msgid "Built-in Codecs" -msgstr "內建編解碼器" - -#: ../../c-api/unicode.rst:1033 -msgid "" -"Python provides a set of built-in codecs which are written in C for speed. " -"All of these codecs are directly usable via the following functions." -msgstr "" - -#: ../../c-api/unicode.rst:1036 -msgid "" -"Many of the following APIs take two arguments encoding and errors, and they " -"have the same semantics as the ones of the built-in :func:`str` string " -"object constructor." -msgstr "" - -#: ../../c-api/unicode.rst:1040 -msgid "" -"Setting encoding to ``NULL`` causes the default encoding to be used which is " -"UTF-8. The file system calls should use :c:func:`PyUnicode_FSConverter` for " -"encoding file names. This uses the :term:`filesystem encoding and error " -"handler` internally." -msgstr "" - -#: ../../c-api/unicode.rst:1045 -msgid "" -"Error handling is set by errors which may also be set to ``NULL`` meaning to " -"use the default handling defined for the codec. Default error handling for " -"all built-in codecs is \"strict\" (:exc:`ValueError` is raised)." -msgstr "" - -#: ../../c-api/unicode.rst:1049 -msgid "" -"The codecs all use a similar interface. Only deviations from the following " -"generic ones are documented for simplicity." -msgstr "" - -#: ../../c-api/unicode.rst:1054 -msgid "Generic Codecs" -msgstr "泛用編解碼器" - -#: ../../c-api/unicode.rst:1056 -msgid "The following macro is provided:" -msgstr "" - -#: ../../c-api/unicode.rst:1061 -msgid "The Unicode code point ``U+FFFD`` (replacement character)." -msgstr "" - -#: ../../c-api/unicode.rst:1063 -msgid "" -"This Unicode character is used as the replacement character during decoding " -"if the *errors* argument is set to \"replace\"." -msgstr "" - -#: ../../c-api/unicode.rst:1067 -msgid "These are the generic codec APIs:" -msgstr "這些是泛用編解碼器的 API：" - -#: ../../c-api/unicode.rst:1073 -msgid "" -"Create a Unicode object by decoding *size* bytes of the encoded string " -"*str*. *encoding* and *errors* have the same meaning as the parameters of " -"the same name in the :func:`str` built-in function. The codec to be used is " -"looked up using the Python codec registry. Return ``NULL`` if an exception " -"was raised by the codec." -msgstr "" - -#: ../../c-api/unicode.rst:1083 -msgid "" -"Encode a Unicode object and return the result as Python bytes object. " -"*encoding* and *errors* have the same meaning as the parameters of the same " -"name in the Unicode :meth:`~str.encode` method. The codec to be used is " -"looked up using the Python codec registry. Return ``NULL`` if an exception " -"was raised by the codec." -msgstr "" - -#: ../../c-api/unicode.rst:1091 -msgid "UTF-8 Codecs" -msgstr "UTF-8 編解碼器" - -#: ../../c-api/unicode.rst:1093 -msgid "These are the UTF-8 codec APIs:" -msgstr "這些是 UTF-8 編解碼器的 API：" - -#: ../../c-api/unicode.rst:1098 -msgid "" -"Create a Unicode object by decoding *size* bytes of the UTF-8 encoded string " -"*str*. Return ``NULL`` if an exception was raised by the codec." -msgstr "" - -#: ../../c-api/unicode.rst:1105 -msgid "" -"If *consumed* is ``NULL``, behave like :c:func:`PyUnicode_DecodeUTF8`. If " -"*consumed* is not ``NULL``, trailing incomplete UTF-8 byte sequences will " -"not be treated as an error. Those bytes will not be decoded and the number " -"of bytes that have been decoded will be stored in *consumed*." -msgstr "" - -#: ../../c-api/unicode.rst:1113 -msgid "" -"Encode a Unicode object using UTF-8 and return the result as Python bytes " -"object. Error handling is \"strict\". Return ``NULL`` if an exception was " -"raised by the codec." -msgstr "" - -#: ../../c-api/unicode.rst:1117 ../../c-api/unicode.rst:1132 -msgid "" -"The function fails if the string contains surrogate code points (``U+D800`` " -"- ``U+DFFF``)." -msgstr "" - -#: ../../c-api/unicode.rst:1123 -msgid "" -"Return a pointer to the UTF-8 encoding of the Unicode object, and store the " -"size of the encoded representation (in bytes) in *size*. The *size* " -"argument can be ``NULL``; in this case no size will be stored. The returned " -"buffer always has an extra null byte appended (not included in *size*), " -"regardless of whether there are any other null code points." -msgstr "" - -#: ../../c-api/unicode.rst:1129 -msgid "" -"On error, set an exception, set *size* to ``-1`` (if it's not NULL) and " -"return ``NULL``." -msgstr "" -"發生錯誤時，設定例外並將 *size* 設為 ``-1``\\ （如果不是 NULL），並回傳 " -"``NULL``。" - -#: ../../c-api/unicode.rst:1135 -msgid "" -"This caches the UTF-8 representation of the string in the Unicode object, " -"and subsequent calls will return a pointer to the same buffer. The caller " -"is not responsible for deallocating the buffer. The buffer is deallocated " -"and pointers to it become invalid when the Unicode object is garbage " -"collected." -msgstr "" - -#: ../../c-api/unicode.rst:1142 ../../c-api/unicode.rst:1164 -msgid "The return type is now ``const char *`` rather of ``char *``." -msgstr "回傳型別現在是 ``const char *`` 而不是 ``char *``。" - -#: ../../c-api/unicode.rst:1145 -msgid "This function is a part of the :ref:`limited API `." -msgstr "" - -#: ../../c-api/unicode.rst:1151 -msgid "As :c:func:`PyUnicode_AsUTF8AndSize`, but does not store the size." -msgstr "與 :c:func:`PyUnicode_AsUTF8AndSize` 類似，但不儲存大小。" - -#: ../../c-api/unicode.rst:1155 -msgid "" -"This function does not have any special behavior for `null characters " -"`_ embedded within *unicode*. " -"As a result, strings containing null characters will remain in the returned " -"string, which some C functions might interpret as the end of the string, " -"leading to truncation. If truncation is an issue, it is recommended to use :" -"c:func:`PyUnicode_AsUTF8AndSize` instead." -msgstr "" - -#: ../../c-api/unicode.rst:1169 -msgid "UTF-32 Codecs" -msgstr "UTF-32 編解碼器" - -#: ../../c-api/unicode.rst:1171 -msgid "These are the UTF-32 codec APIs:" -msgstr "這些是 UTF-32 編解碼器的 API：" - -#: ../../c-api/unicode.rst:1177 -msgid "" -"Decode *size* bytes from a UTF-32 encoded buffer string and return the " -"corresponding Unicode object. *errors* (if non-``NULL``) defines the error " -"handling. It defaults to \"strict\"." -msgstr "" - -#: ../../c-api/unicode.rst:1181 ../../c-api/unicode.rst:1231 -msgid "" -"If *byteorder* is non-``NULL``, the decoder starts decoding using the given " -"byte order::" -msgstr "" - -#: ../../c-api/unicode.rst:1184 ../../c-api/unicode.rst:1234 -msgid "" -"*byteorder == -1: little endian\n" -"*byteorder == 0: native order\n" -"*byteorder == 1: big endian" -msgstr "" - -#: ../../c-api/unicode.rst:1188 -msgid "" -"If ``*byteorder`` is zero, and the first four bytes of the input data are a " -"byte order mark (BOM), the decoder switches to this byte order and the BOM " -"is not copied into the resulting Unicode string. If ``*byteorder`` is " -"``-1`` or ``1``, any byte order mark is copied to the output." -msgstr "" - -#: ../../c-api/unicode.rst:1193 -msgid "" -"After completion, *\\*byteorder* is set to the current byte order at the end " -"of input data." -msgstr "" - -#: ../../c-api/unicode.rst:1196 ../../c-api/unicode.rst:1247 -msgid "If *byteorder* is ``NULL``, the codec starts in native order mode." -msgstr "" - -#: ../../c-api/unicode.rst:1198 ../../c-api/unicode.rst:1249 -msgid "Return ``NULL`` if an exception was raised by the codec." -msgstr "如果編解碼器引發例外則回傳 ``NULL``。" - -#: ../../c-api/unicode.rst:1204 -msgid "" -"If *consumed* is ``NULL``, behave like :c:func:`PyUnicode_DecodeUTF32`. If " -"*consumed* is not ``NULL``, :c:func:`PyUnicode_DecodeUTF32Stateful` will not " -"treat trailing incomplete UTF-32 byte sequences (such as a number of bytes " -"not divisible by four) as an error. Those bytes will not be decoded and the " -"number of bytes that have been decoded will be stored in *consumed*." -msgstr "" - -#: ../../c-api/unicode.rst:1213 -msgid "" -"Return a Python byte string using the UTF-32 encoding in native byte order. " -"The string always starts with a BOM mark. Error handling is \"strict\". " -"Return ``NULL`` if an exception was raised by the codec." -msgstr "" - -#: ../../c-api/unicode.rst:1219 -msgid "UTF-16 Codecs" -msgstr "UTF-16 編解碼器" - -#: ../../c-api/unicode.rst:1221 -msgid "These are the UTF-16 codec APIs:" -msgstr "這些是 UTF-16 編解碼器的 API：" - -#: ../../c-api/unicode.rst:1227 -msgid "" -"Decode *size* bytes from a UTF-16 encoded buffer string and return the " -"corresponding Unicode object. *errors* (if non-``NULL``) defines the error " -"handling. It defaults to \"strict\"." -msgstr "" - -#: ../../c-api/unicode.rst:1238 -msgid "" -"If ``*byteorder`` is zero, and the first two bytes of the input data are a " -"byte order mark (BOM), the decoder switches to this byte order and the BOM " -"is not copied into the resulting Unicode string. If ``*byteorder`` is " -"``-1`` or ``1``, any byte order mark is copied to the output (where it will " -"result in either a ``\\ufeff`` or a ``\\ufffe`` character)." -msgstr "" - -#: ../../c-api/unicode.rst:1244 -msgid "" -"After completion, ``*byteorder`` is set to the current byte order at the end " -"of input data." -msgstr "" - -#: ../../c-api/unicode.rst:1255 -msgid "" -"If *consumed* is ``NULL``, behave like :c:func:`PyUnicode_DecodeUTF16`. If " -"*consumed* is not ``NULL``, :c:func:`PyUnicode_DecodeUTF16Stateful` will not " -"treat trailing incomplete UTF-16 byte sequences (such as an odd number of " -"bytes or a split surrogate pair) as an error. Those bytes will not be " -"decoded and the number of bytes that have been decoded will be stored in " -"*consumed*." -msgstr "" - -#: ../../c-api/unicode.rst:1264 -msgid "" -"Return a Python byte string using the UTF-16 encoding in native byte order. " -"The string always starts with a BOM mark. Error handling is \"strict\". " -"Return ``NULL`` if an exception was raised by the codec." -msgstr "" - -#: ../../c-api/unicode.rst:1270 -msgid "UTF-7 Codecs" -msgstr "UTF-7 編解碼器" - -#: ../../c-api/unicode.rst:1272 -msgid "These are the UTF-7 codec APIs:" -msgstr "這些是 UTF-7 編解碼器的 API：" - -#: ../../c-api/unicode.rst:1277 -msgid "" -"Create a Unicode object by decoding *size* bytes of the UTF-7 encoded string " -"*str*. Return ``NULL`` if an exception was raised by the codec." -msgstr "" - -#: ../../c-api/unicode.rst:1284 -msgid "" -"If *consumed* is ``NULL``, behave like :c:func:`PyUnicode_DecodeUTF7`. If " -"*consumed* is not ``NULL``, trailing incomplete UTF-7 base-64 sections will " -"not be treated as an error. Those bytes will not be decoded and the number " -"of bytes that have been decoded will be stored in *consumed*." -msgstr "" - -#: ../../c-api/unicode.rst:1291 -msgid "Unicode-Escape Codecs" -msgstr "" - -#: ../../c-api/unicode.rst:1293 -msgid "These are the \"Unicode Escape\" codec APIs:" -msgstr "" - -#: ../../c-api/unicode.rst:1299 -msgid "" -"Create a Unicode object by decoding *size* bytes of the Unicode-Escape " -"encoded string *str*. Return ``NULL`` if an exception was raised by the " -"codec." -msgstr "" - -#: ../../c-api/unicode.rst:1305 -msgid "" -"Encode a Unicode object using Unicode-Escape and return the result as a " -"bytes object. Error handling is \"strict\". Return ``NULL`` if an " -"exception was raised by the codec." -msgstr "" - -#: ../../c-api/unicode.rst:1311 -msgid "Raw-Unicode-Escape Codecs" -msgstr "" - -#: ../../c-api/unicode.rst:1313 -msgid "These are the \"Raw Unicode Escape\" codec APIs:" -msgstr "" - -#: ../../c-api/unicode.rst:1319 -msgid "" -"Create a Unicode object by decoding *size* bytes of the Raw-Unicode-Escape " -"encoded string *str*. Return ``NULL`` if an exception was raised by the " -"codec." -msgstr "" - -#: ../../c-api/unicode.rst:1325 -msgid "" -"Encode a Unicode object using Raw-Unicode-Escape and return the result as a " -"bytes object. Error handling is \"strict\". Return ``NULL`` if an " -"exception was raised by the codec." -msgstr "" - -#: ../../c-api/unicode.rst:1331 -msgid "Latin-1 Codecs" -msgstr "Latin-1 編解碼器" - -#: ../../c-api/unicode.rst:1333 -msgid "" -"These are the Latin-1 codec APIs: Latin-1 corresponds to the first 256 " -"Unicode ordinals and only these are accepted by the codecs during encoding." -msgstr "" - -#: ../../c-api/unicode.rst:1339 -msgid "" -"Create a Unicode object by decoding *size* bytes of the Latin-1 encoded " -"string *str*. Return ``NULL`` if an exception was raised by the codec." -msgstr "" - -#: ../../c-api/unicode.rst:1345 -msgid "" -"Encode a Unicode object using Latin-1 and return the result as Python bytes " -"object. Error handling is \"strict\". Return ``NULL`` if an exception was " -"raised by the codec." -msgstr "" - -#: ../../c-api/unicode.rst:1351 -msgid "ASCII Codecs" -msgstr "ASCII 編解碼器" - -#: ../../c-api/unicode.rst:1353 -msgid "" -"These are the ASCII codec APIs. Only 7-bit ASCII data is accepted. All " -"other codes generate errors." -msgstr "" - -#: ../../c-api/unicode.rst:1359 -msgid "" -"Create a Unicode object by decoding *size* bytes of the ASCII encoded string " -"*str*. Return ``NULL`` if an exception was raised by the codec." -msgstr "" - -#: ../../c-api/unicode.rst:1365 -msgid "" -"Encode a Unicode object using ASCII and return the result as Python bytes " -"object. Error handling is \"strict\". Return ``NULL`` if an exception was " -"raised by the codec." -msgstr "" - -#: ../../c-api/unicode.rst:1371 -msgid "Character Map Codecs" -msgstr "" - -#: ../../c-api/unicode.rst:1373 -msgid "" -"This codec is special in that it can be used to implement many different " -"codecs (and this is in fact what was done to obtain most of the standard " -"codecs included in the :mod:`!encodings` package). The codec uses mappings " -"to encode and decode characters. The mapping objects provided must support " -"the :meth:`~object.__getitem__` mapping interface; dictionaries and " -"sequences work well." -msgstr "" - -#: ../../c-api/unicode.rst:1379 -msgid "These are the mapping codec APIs:" -msgstr "這些是對映編解碼器的 API：" - -#: ../../c-api/unicode.rst:1384 -msgid "" -"Create a Unicode object by decoding *size* bytes of the encoded string *str* " -"using the given *mapping* object. Return ``NULL`` if an exception was " -"raised by the codec." -msgstr "" - -#: ../../c-api/unicode.rst:1388 -msgid "" -"If *mapping* is ``NULL``, Latin-1 decoding will be applied. Else *mapping* " -"must map bytes ordinals (integers in the range from 0 to 255) to Unicode " -"strings, integers (which are then interpreted as Unicode ordinals) or " -"``None``. Unmapped data bytes -- ones which cause a :exc:`LookupError`, as " -"well as ones which get mapped to ``None``, ``0xFFFE`` or ``'\\ufffe'``, are " -"treated as undefined mappings and cause an error." -msgstr "" - -#: ../../c-api/unicode.rst:1399 -msgid "" -"Encode a Unicode object using the given *mapping* object and return the " -"result as a bytes object. Error handling is \"strict\". Return ``NULL`` if " -"an exception was raised by the codec." -msgstr "" - -#: ../../c-api/unicode.rst:1403 -msgid "" -"The *mapping* object must map Unicode ordinal integers to bytes objects, " -"integers in the range from 0 to 255 or ``None``. Unmapped character " -"ordinals (ones which cause a :exc:`LookupError`) as well as mapped to " -"``None`` are treated as \"undefined mapping\" and cause an error." -msgstr "" - -#: ../../c-api/unicode.rst:1409 -msgid "The following codec API is special in that maps Unicode to Unicode." -msgstr "" - -#: ../../c-api/unicode.rst:1413 -msgid "" -"Translate a string by applying a character mapping table to it and return " -"the resulting Unicode object. Return ``NULL`` if an exception was raised by " -"the codec." -msgstr "" - -#: ../../c-api/unicode.rst:1417 -msgid "" -"The mapping table must map Unicode ordinal integers to Unicode ordinal " -"integers or ``None`` (causing deletion of the character)." -msgstr "" - -#: ../../c-api/unicode.rst:1420 -msgid "" -"Mapping tables need only provide the :meth:`~object.__getitem__` interface; " -"dictionaries and sequences work well. Unmapped character ordinals (ones " -"which cause a :exc:`LookupError`) are left untouched and are copied as-is." -msgstr "" - -#: ../../c-api/unicode.rst:1424 -msgid "" -"*errors* has the usual meaning for codecs. It may be ``NULL`` which " -"indicates to use the default error handling." -msgstr "" - -#: ../../c-api/unicode.rst:1429 -msgid "MBCS codecs for Windows" -msgstr "Windows 的 MBCS 編解碼器" - -#: ../../c-api/unicode.rst:1431 -msgid "" -"These are the MBCS codec APIs. They are currently only available on Windows " -"and use the Win32 MBCS converters to implement the conversions. Note that " -"MBCS (or DBCS) is a class of encodings, not just one. The target encoding " -"is defined by the user settings on the machine running the codec." -msgstr "" - -#: ../../c-api/unicode.rst:1438 -msgid "" -"Create a Unicode object by decoding *size* bytes of the MBCS encoded string " -"*str*. Return ``NULL`` if an exception was raised by the codec." -msgstr "" - -#: ../../c-api/unicode.rst:1445 -msgid "" -"If *consumed* is ``NULL``, behave like :c:func:`PyUnicode_DecodeMBCS`. If " -"*consumed* is not ``NULL``, :c:func:`PyUnicode_DecodeMBCSStateful` will not " -"decode trailing lead byte and the number of bytes that have been decoded " -"will be stored in *consumed*." -msgstr "" - -#: ../../c-api/unicode.rst:1454 -msgid "" -"Similar to :c:func:`PyUnicode_DecodeMBCSStateful`, except uses the code page " -"specified by *code_page*." -msgstr "" - -#: ../../c-api/unicode.rst:1460 -msgid "" -"Encode a Unicode object using MBCS and return the result as Python bytes " -"object. Error handling is \"strict\". Return ``NULL`` if an exception was " -"raised by the codec." -msgstr "" - -#: ../../c-api/unicode.rst:1467 -msgid "" -"Encode the Unicode object using the specified code page and return a Python " -"bytes object. Return ``NULL`` if an exception was raised by the codec. Use :" -"c:macro:`!CP_ACP` code page to get the MBCS encoder." -msgstr "" - -#: ../../c-api/unicode.rst:1477 -msgid "Methods and Slot Functions" -msgstr "" - -#: ../../c-api/unicode.rst:1479 -msgid "" -"The following APIs are capable of handling Unicode objects and strings on " -"input (we refer to them as strings in the descriptions) and return Unicode " -"objects or integers as appropriate." -msgstr "" - -#: ../../c-api/unicode.rst:1483 -msgid "They all return ``NULL`` or ``-1`` if an exception occurs." -msgstr "如果發生例外，則回傳 ``NULL`` 或 ``-1``。" - -#: ../../c-api/unicode.rst:1488 -msgid "Concat two strings giving a new Unicode string." -msgstr "" - -#: ../../c-api/unicode.rst:1493 -msgid "" -"Split a string giving a list of Unicode strings. If *sep* is ``NULL``, " -"splitting will be done at all whitespace substrings. Otherwise, splits " -"occur at the given separator. At most *maxsplit* splits will be done. If " -"negative, no limit is set. Separators are not included in the resulting " -"list." -msgstr "" - -#: ../../c-api/unicode.rst:1498 ../../c-api/unicode.rst:1508 -#: ../../c-api/unicode.rst:1529 ../../c-api/unicode.rst:1542 -msgid "On error, return ``NULL`` with an exception set." -msgstr "於錯誤發生時回傳 ``NULL`` 並設定例外。" - -#: ../../c-api/unicode.rst:1500 -msgid "Equivalent to :py:meth:`str.split`." -msgstr "等價於 :py:meth:`str.split`。" - -#: ../../c-api/unicode.rst:1505 -msgid "" -"Similar to :c:func:`PyUnicode_Split`, but splitting will be done beginning " -"at the end of the string." -msgstr "" - -#: ../../c-api/unicode.rst:1510 -msgid "Equivalent to :py:meth:`str.rsplit`." -msgstr "等價於 :py:meth:`str.rsplit`。" - -#: ../../c-api/unicode.rst:1515 -msgid "" -"Split a Unicode string at line breaks, returning a list of Unicode strings. " -"CRLF is considered to be one line break. If *keepends* is ``0``, the Line " -"break characters are not included in the resulting strings." -msgstr "" - -#: ../../c-api/unicode.rst:1522 -msgid "" -"Split a Unicode string at the first occurrence of *sep*, and return a 3-" -"tuple containing the part before the separator, the separator itself, and " -"the part after the separator. If the separator is not found, return a 3-" -"tuple containing the string itself, followed by two empty strings." -msgstr "" - -#: ../../c-api/unicode.rst:1527 ../../c-api/unicode.rst:1540 -msgid "*sep* must not be empty." -msgstr "*sep* 不得為空。" - -#: ../../c-api/unicode.rst:1531 -msgid "Equivalent to :py:meth:`str.partition`." -msgstr "等價於 :py:meth:`str.partition`。" - -#: ../../c-api/unicode.rst:1536 -msgid "" -"Similar to :c:func:`PyUnicode_Partition`, but split a Unicode string at the " -"last occurrence of *sep*. If the separator is not found, return a 3-tuple " -"containing two empty strings, followed by the string itself." -msgstr "" - -#: ../../c-api/unicode.rst:1544 -msgid "Equivalent to :py:meth:`str.rpartition`." -msgstr "等價於 :py:meth:`str.rpartition`。" - -#: ../../c-api/unicode.rst:1549 -msgid "" -"Join a sequence of strings using the given *separator* and return the " -"resulting Unicode string." -msgstr "" - -#: ../../c-api/unicode.rst:1556 -msgid "" -"Return ``1`` if *substr* matches ``unicode[start:end]`` at the given tail " -"end (*direction* == ``-1`` means to do a prefix match, *direction* == ``1`` " -"a suffix match), ``0`` otherwise. Return ``-1`` if an error occurred." -msgstr "" - -#: ../../c-api/unicode.rst:1564 -msgid "" -"Return the first position of *substr* in ``unicode[start:end]`` using the " -"given *direction* (*direction* == ``1`` means to do a forward search, " -"*direction* == ``-1`` a backward search). The return value is the index of " -"the first match; a value of ``-1`` indicates that no match was found, and " -"``-2`` indicates that an error occurred and an exception has been set." -msgstr "" - -#: ../../c-api/unicode.rst:1574 -msgid "" -"Return the first position of the character *ch* in ``unicode[start:end]`` " -"using the given *direction* (*direction* == ``1`` means to do a forward " -"search, *direction* == ``-1`` a backward search). The return value is the " -"index of the first match; a value of ``-1`` indicates that no match was " -"found, and ``-2`` indicates that an error occurred and an exception has been " -"set." -msgstr "" - -#: ../../c-api/unicode.rst:1582 -msgid "" -"*start* and *end* are now adjusted to behave like ``unicode[start:end]``." -msgstr "" - -#: ../../c-api/unicode.rst:1589 -msgid "" -"Return the number of non-overlapping occurrences of *substr* in " -"``unicode[start:end]``. Return ``-1`` if an error occurred." -msgstr "" - -#: ../../c-api/unicode.rst:1596 -msgid "" -"Replace at most *maxcount* occurrences of *substr* in *unicode* with " -"*replstr* and return the resulting Unicode object. *maxcount* == ``-1`` " -"means replace all occurrences." -msgstr "" - -#: ../../c-api/unicode.rst:1603 -msgid "" -"Compare two strings and return ``-1``, ``0``, ``1`` for less than, equal, " -"and greater than, respectively." -msgstr "" - -#: ../../c-api/unicode.rst:1606 -msgid "" -"This function returns ``-1`` upon failure, so one should call :c:func:" -"`PyErr_Occurred` to check for errors." -msgstr "" - -#: ../../c-api/unicode.rst:1611 -msgid "The :c:func:`PyUnicode_Equal` function." -msgstr ":c:func:`PyUnicode_Equal` 函式。" - -#: ../../c-api/unicode.rst:1616 -msgid "Test if two strings are equal:" -msgstr "測試兩個字串是否相等：" - -#: ../../c-api/unicode.rst:1618 -msgid "Return ``1`` if *a* is equal to *b*." -msgstr "如果 *a* 等於 *b*，則回傳 ``1``。" - -#: ../../c-api/unicode.rst:1619 -msgid "Return ``0`` if *a* is not equal to *b*." -msgstr "如果 *a* 不等於 *b*，則回傳 ``0``。" - -#: ../../c-api/unicode.rst:1620 -msgid "" -"Set a :exc:`TypeError` exception and return ``-1`` if *a* or *b* is not a :" -"class:`str` object." -msgstr "" - -#: ../../c-api/unicode.rst:1623 -msgid "The function always succeeds if *a* and *b* are :class:`str` objects." -msgstr "" - -#: ../../c-api/unicode.rst:1625 -msgid "" -"The function works for :class:`str` subclasses, but does not honor custom " -"``__eq__()`` method." -msgstr "" - -#: ../../c-api/unicode.rst:1630 -msgid "The :c:func:`PyUnicode_Compare` function." -msgstr ":c:func:`PyUnicode_Compare` 函式。" - -#: ../../c-api/unicode.rst:1637 -msgid "" -"Compare a Unicode object with a char buffer which is interpreted as being " -"UTF-8 or ASCII encoded and return true (``1``) if they are equal, or false " -"(``0``) otherwise. If the Unicode object contains surrogate code points " -"(``U+D800`` - ``U+DFFF``) or the C string is not valid UTF-8, false (``0``) " -"is returned." -msgstr "" - -#: ../../c-api/unicode.rst:1644 ../../c-api/unicode.rst:1665 -msgid "This function does not raise exceptions." -msgstr "此函式不會引發例外。" - -#: ../../c-api/unicode.rst:1651 -msgid "" -"Similar to :c:func:`PyUnicode_EqualToUTF8AndSize`, but compute *string* " -"length using :c:func:`!strlen`. If the Unicode object contains null " -"characters, false (``0``) is returned." -msgstr "" - -#: ../../c-api/unicode.rst:1660 -msgid "" -"Compare a Unicode object, *unicode*, with *string* and return ``-1``, ``0``, " -"``1`` for less than, equal, and greater than, respectively. It is best to " -"pass only ASCII-encoded strings, but the function interprets the input " -"string as ISO-8859-1 if it contains non-ASCII characters." -msgstr "" - -#: ../../c-api/unicode.rst:1670 -msgid "Rich compare two Unicode strings and return one of the following:" -msgstr "" - -#: ../../c-api/unicode.rst:1672 -msgid "``NULL`` in case an exception was raised" -msgstr "" - -#: ../../c-api/unicode.rst:1673 -msgid ":c:data:`Py_True` or :c:data:`Py_False` for successful comparisons" -msgstr "" - -#: ../../c-api/unicode.rst:1674 -msgid ":c:data:`Py_NotImplemented` in case the type combination is unknown" -msgstr "" - -#: ../../c-api/unicode.rst:1676 -msgid "" -"Possible values for *op* are :c:macro:`Py_GT`, :c:macro:`Py_GE`, :c:macro:" -"`Py_EQ`, :c:macro:`Py_NE`, :c:macro:`Py_LT`, and :c:macro:`Py_LE`." -msgstr "" - -#: ../../c-api/unicode.rst:1682 -msgid "" -"Return a new string object from *format* and *args*; this is analogous to " -"``format % args``." -msgstr "" - -#: ../../c-api/unicode.rst:1688 -msgid "" -"Check whether *substr* is contained in *unicode* and return true or false " -"accordingly." -msgstr "" - -#: ../../c-api/unicode.rst:1691 -msgid "" -"*substr* has to coerce to a one element Unicode string. ``-1`` is returned " -"if there was an error." -msgstr "" - -#: ../../c-api/unicode.rst:1697 -msgid "" -"Intern the argument :c:expr:`*p_unicode` in place. The argument must be the " -"address of a pointer variable pointing to a Python Unicode string object. " -"If there is an existing interned string that is the same as :c:expr:" -"`*p_unicode`, it sets :c:expr:`*p_unicode` to it (releasing the reference to " -"the old string object and creating a new :term:`strong reference` to the " -"interned string object), otherwise it leaves :c:expr:`*p_unicode` alone and " -"interns it." -msgstr "" - -#: ../../c-api/unicode.rst:1704 -msgid "" -"(Clarification: even though there is a lot of talk about references, think " -"of this function as reference-neutral. You must own the object you pass in; " -"after the call you no longer own the passed-in reference, but you newly own " -"the result.)" -msgstr "" - -#: ../../c-api/unicode.rst:1709 -msgid "" -"This function never raises an exception. On error, it leaves its argument " -"unchanged without interning it." -msgstr "" - -#: ../../c-api/unicode.rst:1712 -msgid "" -"Instances of subclasses of :py:class:`str` may not be interned, that is, :c:" -"expr:`PyUnicode_CheckExact(*p_unicode)` must be true. If it is not, then -- " -"as with any other error -- the argument is left unchanged." -msgstr "" - -#: ../../c-api/unicode.rst:1716 -msgid "" -"Note that interned strings are not “immortal”. You must keep a reference to " -"the result to benefit from interning." -msgstr "" - -#: ../../c-api/unicode.rst:1722 -msgid "" -"A combination of :c:func:`PyUnicode_FromString` and :c:func:" -"`PyUnicode_InternInPlace`, meant for statically allocated strings." -msgstr "" - -#: ../../c-api/unicode.rst:1725 -msgid "" -"Return a new (\"owned\") reference to either a new Unicode string object " -"that has been interned, or an earlier interned string object with the same " -"value." -msgstr "" - -#: ../../c-api/unicode.rst:1729 -msgid "" -"Python may keep a reference to the result, or make it :term:`immortal`, " -"preventing it from being garbage-collected promptly. For interning an " -"unbounded number of different strings, such as ones coming from user input, " -"prefer calling :c:func:`PyUnicode_FromString` and :c:func:" -"`PyUnicode_InternInPlace` directly." -msgstr "" - -#: ../../c-api/unicode.rst:1738 -msgid "" -"Return a non-zero value if *str* is interned, zero if not. The *str* " -"argument must be a string; this is not checked. This function always " -"succeeds." -msgstr "" - -#: ../../c-api/unicode.rst:1744 -msgid "" -"A non-zero return value may carry additional information about *how* the " -"string is interned. The meaning of such non-zero values, as well as each " -"specific string's intern-related details, may change between CPython " -"versions." -msgstr "" - -#: ../../c-api/unicode.rst:1751 -msgid "PyUnicodeWriter" -msgstr "PyUnicodeWriter" - -#: ../../c-api/unicode.rst:1753 -msgid "" -"The :c:type:`PyUnicodeWriter` API can be used to create a Python :class:" -"`str` object." -msgstr "" - -#: ../../c-api/unicode.rst:1760 -msgid "A Unicode writer instance." -msgstr "一個 Unicode 寫入器實例。" - -#: ../../c-api/unicode.rst:1762 -msgid "" -"The instance must be destroyed by :c:func:`PyUnicodeWriter_Finish` on " -"success, or :c:func:`PyUnicodeWriter_Discard` on error." -msgstr "" - -#: ../../c-api/unicode.rst:1767 -msgid "Create a Unicode writer instance." -msgstr "" - -#: ../../c-api/unicode.rst:1769 -msgid "*length* must be greater than or equal to ``0``." -msgstr "" - -#: ../../c-api/unicode.rst:1771 -msgid "" -"If *length* is greater than ``0``, preallocate an internal buffer of " -"*length* characters." -msgstr "" - -#: ../../c-api/unicode.rst:1774 ../../c-api/unicode.rst:1780 -msgid "Set an exception and return ``NULL`` on error." -msgstr "發生錯誤時，設定例外並回傳 ``NULL``。" - -#: ../../c-api/unicode.rst:1778 -msgid "" -"Return the final Python :class:`str` object and destroy the writer instance." -msgstr "" - -#: ../../c-api/unicode.rst:1782 ../../c-api/unicode.rst:1790 -msgid "The writer instance is invalid after this call." -msgstr "" - -#: ../../c-api/unicode.rst:1786 -msgid "Discard the internal Unicode buffer and destroy the writer instance." -msgstr "" - -#: ../../c-api/unicode.rst:1788 -msgid "If *writer* is ``NULL``, no operation is performed." -msgstr "" - -#: ../../c-api/unicode.rst:1794 -msgid "Write the single Unicode character *ch* into *writer*." -msgstr "" - -#: ../../c-api/unicode.rst:1796 ../../c-api/unicode.rst:1806 -#: ../../c-api/unicode.rst:1821 ../../c-api/unicode.rst:1833 -#: ../../c-api/unicode.rst:1842 ../../c-api/unicode.rst:1849 -#: ../../c-api/unicode.rst:1856 ../../c-api/unicode.rst:1867 -#: ../../c-api/unicode.rst:1874 ../../c-api/unicode.rst:1893 -msgid "" -"On success, return ``0``. On error, set an exception, leave the writer " -"unchanged, and return ``-1``." -msgstr "成功時回傳 ``0``，發生錯誤時設定例外、保持寫入器不變，並回傳 ``-1``。" - -#: ../../c-api/unicode.rst:1801 -msgid "" -"Decode the string *str* from UTF-8 in strict mode and write the output into " -"*writer*." -msgstr "" - -#: ../../c-api/unicode.rst:1803 ../../c-api/unicode.rst:1815 -#: ../../c-api/unicode.rst:1882 -msgid "" -"*size* is the string length in bytes. If *size* is equal to ``-1``, call " -"``strlen(str)`` to get the string length." -msgstr "" - -#: ../../c-api/unicode.rst:1809 -msgid "See also :c:func:`PyUnicodeWriter_DecodeUTF8Stateful`." -msgstr "另請參閱 :c:func:`PyUnicodeWriter_DecodeUTF8Stateful`。" - -#: ../../c-api/unicode.rst:1813 -msgid "Write the ASCII string *str* into *writer*." -msgstr "" - -#: ../../c-api/unicode.rst:1818 -msgid "" -"*str* must only contain ASCII characters. The behavior is undefined if *str* " -"contains non-ASCII characters." -msgstr "" - -#: ../../c-api/unicode.rst:1828 -msgid "Write the wide string *str* into *writer*." -msgstr "" - -#: ../../c-api/unicode.rst:1830 -msgid "" -"*size* is a number of wide characters. If *size* is equal to ``-1``, call " -"``wcslen(str)`` to get the string length." -msgstr "" - -#: ../../c-api/unicode.rst:1838 -msgid "Writer the UCS4 string *str* into *writer*." -msgstr "" - -#: ../../c-api/unicode.rst:1840 -msgid "*size* is a number of UCS4 characters." -msgstr "" - -#: ../../c-api/unicode.rst:1847 -msgid "" -"Call :c:func:`PyObject_Str` on *obj* and write the output into *writer*." -msgstr "" - -#: ../../c-api/unicode.rst:1854 -msgid "" -"Call :c:func:`PyObject_Repr` on *obj* and write the output into *writer*." -msgstr "" - -#: ../../c-api/unicode.rst:1861 -msgid "Write the substring ``str[start:end]`` into *writer*." -msgstr "" - -#: ../../c-api/unicode.rst:1863 -msgid "" -"*str* must be Python :class:`str` object. *start* must be greater than or " -"equal to 0, and less than or equal to *end*. *end* must be less than or " -"equal to *str* length." -msgstr "" - -#: ../../c-api/unicode.rst:1872 -msgid "" -"Similar to :c:func:`PyUnicode_FromFormat`, but write the output directly " -"into *writer*." -msgstr "類似於 :c:func:`PyUnicode_FromFormat`，但是直接將輸出寫入 *writer*。" - -#: ../../c-api/unicode.rst:1879 -msgid "" -"Decode the string *str* from UTF-8 with *errors* error handler and write the " -"output into *writer*." -msgstr "" - -#: ../../c-api/unicode.rst:1885 -msgid "" -"*errors* is an :ref:`error handler ` name, such as " -"``\"replace\"``. If *errors* is ``NULL``, use the strict error handler." -msgstr "" - -#: ../../c-api/unicode.rst:1888 -msgid "" -"If *consumed* is not ``NULL``, set *\\*consumed* to the number of decoded " -"bytes on success. If *consumed* is ``NULL``, treat trailing incomplete UTF-8 " -"byte sequences as an error." -msgstr "" - -#: ../../c-api/unicode.rst:1896 -msgid "See also :c:func:`PyUnicodeWriter_WriteUTF8`." -msgstr "另請參閱 :c:func:`PyUnicodeWriter_WriteUTF8`。" - -#: ../../c-api/unicode.rst:1899 -msgid "Deprecated API" -msgstr "已棄用的 API" - -#: ../../c-api/unicode.rst:1901 -msgid "The following API is deprecated." -msgstr "以下 API 已棄用。" - -#: ../../c-api/unicode.rst:1905 -msgid "" -"This is a typedef of :c:type:`wchar_t`, which is a 16-bit type or 32-bit " -"type depending on the platform. Please use :c:type:`wchar_t` directly " -"instead." -msgstr "" - -#: ../../c-api/unicode.rst:1909 -msgid "" -"In previous versions, this was a 16-bit type or a 32-bit type depending on " -"whether you selected a \"narrow\" or \"wide\" Unicode version of Python at " -"build time." -msgstr "" - -#: ../../c-api/unicode.rst:1919 -msgid "" -"Do nothing and return ``0``. This API is kept only for backward " -"compatibility, but there are no plans to remove it." -msgstr "" - -#: ../../c-api/unicode.rst:1925 -msgid "" -"This API does nothing since Python 3.12. Previously, this needed to be " -"called for each string created using the old API (:c:func:`!" -"PyUnicode_FromUnicode` or similar)." -msgstr "" - -#: ../../c-api/unicode.rst:1933 -msgid "" -"Do nothing and return ``1``. This API is kept only for backward " -"compatibility, but there are no plans to remove it." -msgstr "" - -#: ../../c-api/unicode.rst:1939 -msgid "" -"This API does nothing since Python 3.12. Previously, this could be called to " -"check if :c:func:`PyUnicode_READY` is necessary." -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Leon H., 2017 +# Liang-Bo Wang , 2016 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-05 00:16+0000\n" +"PO-Revision-Date: 2018-05-23 14:08+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" + +#: ../../c-api/unicode.rst:6 +msgid "Unicode Objects and Codecs" +msgstr "Unicode 物件與編解碼器" + +#: ../../c-api/unicode.rst:12 +msgid "Unicode Objects" +msgstr "Unicode 物件" + +#: ../../c-api/unicode.rst:14 +msgid "" +"Since the implementation of :pep:`393` in Python 3.3, Unicode objects " +"internally use a variety of representations, in order to allow handling the " +"complete range of Unicode characters while staying memory efficient. There " +"are special cases for strings where all code points are below 128, 256, or " +"65536; otherwise, code points must be below 1114112 (which is the full " +"Unicode range)." +msgstr "" + +#: ../../c-api/unicode.rst:20 +msgid "" +"UTF-8 representation is created on demand and cached in the Unicode object." +msgstr "UTF-8 表示法會在需要時建立並快取在 Unicode 物件中。" + +#: ../../c-api/unicode.rst:23 +msgid "" +"The :c:type:`Py_UNICODE` representation has been removed since Python 3.12 " +"with deprecated APIs. See :pep:`623` for more information." +msgstr "" +"自 Python 3.12 起，已移除 :c:type:`Py_UNICODE` 表示法，並標示為已棄用的 API。" +"更多資訊請參閱 :pep:`623`。" + +#: ../../c-api/unicode.rst:29 +msgid "Unicode Type" +msgstr "Unicode 型別" + +#: ../../c-api/unicode.rst:31 +msgid "" +"These are the basic Unicode object types used for the Unicode implementation " +"in Python:" +msgstr "這些是 Python 中用於 Unicode 實作的基本 Unicode 物件型別：" + +#: ../../c-api/unicode.rst:36 +msgid "" +"This instance of :c:type:`PyTypeObject` represents the Python Unicode type. " +"It is exposed to Python code as :py:class:`str`." +msgstr "" + +#: ../../c-api/unicode.rst:42 +msgid "" +"This instance of :c:type:`PyTypeObject` represents the Python Unicode " +"iterator type. It is used to iterate over Unicode string objects." +msgstr "" + +#: ../../c-api/unicode.rst:50 +msgid "" +"These types are typedefs for unsigned integer types wide enough to contain " +"characters of 32 bits, 16 bits and 8 bits, respectively. When dealing with " +"single Unicode characters, use :c:type:`Py_UCS4`." +msgstr "" + +#: ../../c-api/unicode.rst:61 +msgid "" +"These subtypes of :c:type:`PyObject` represent a Python Unicode object. In " +"almost all cases, they shouldn't be used directly, since all API functions " +"that deal with Unicode objects take and return :c:type:`PyObject` pointers." +msgstr "" + +#: ../../c-api/unicode.rst:68 +msgid "" +"The following APIs are C macros and static inlined functions for fast checks " +"and access to internal read-only data of Unicode objects:" +msgstr "" + +#: ../../c-api/unicode.rst:73 +msgid "" +"Return true if the object *obj* is a Unicode object or an instance of a " +"Unicode subtype. This function always succeeds." +msgstr "" + +#: ../../c-api/unicode.rst:79 +msgid "" +"Return true if the object *obj* is a Unicode object, but not an instance of " +"a subtype. This function always succeeds." +msgstr "" + +#: ../../c-api/unicode.rst:85 +msgid "" +"Return the length of the Unicode string, in code points. *unicode* has to " +"be a Unicode object in the \"canonical\" representation (not checked)." +msgstr "" + +#: ../../c-api/unicode.rst:95 +msgid "" +"Return a pointer to the canonical representation cast to UCS1, UCS2 or UCS4 " +"integer types for direct character access. No checks are performed if the " +"canonical representation has the correct character size; use :c:func:" +"`PyUnicode_KIND` to select the right function." +msgstr "" + +#: ../../c-api/unicode.rst:107 +msgid "Return values of the :c:func:`PyUnicode_KIND` macro." +msgstr "" + +#: ../../c-api/unicode.rst:111 +msgid "``PyUnicode_WCHAR_KIND`` has been removed." +msgstr "``PyUnicode_WCHAR_KIND`` 已被移除。" + +#: ../../c-api/unicode.rst:117 +msgid "" +"Return one of the PyUnicode kind constants (see above) that indicate how " +"many bytes per character this Unicode object uses to store its data. " +"*unicode* has to be a Unicode object in the \"canonical\" representation " +"(not checked)." +msgstr "" + +#: ../../c-api/unicode.rst:126 +msgid "" +"Return a void pointer to the raw Unicode buffer. *unicode* has to be a " +"Unicode object in the \"canonical\" representation (not checked)." +msgstr "" + +#: ../../c-api/unicode.rst:135 +msgid "" +"Write the code point *value* to the given zero-based *index* in a string." +msgstr "" + +#: ../../c-api/unicode.rst:137 +msgid "" +"The *kind* value and *data* pointer must have been obtained from a string " +"using :c:func:`PyUnicode_KIND` and :c:func:`PyUnicode_DATA` respectively. " +"You must hold a reference to that string while calling :c:func:`!" +"PyUnicode_WRITE`. All requirements of :c:func:`PyUnicode_WriteChar` also " +"apply." +msgstr "" + +#: ../../c-api/unicode.rst:143 +msgid "" +"The function performs no checks for any of its requirements, and is intended " +"for usage in loops." +msgstr "" + +#: ../../c-api/unicode.rst:152 +msgid "" +"Read a code point from a canonical representation *data* (as obtained with :" +"c:func:`PyUnicode_DATA`). No checks or ready calls are performed." +msgstr "" + +#: ../../c-api/unicode.rst:160 +msgid "" +"Read a character from a Unicode object *unicode*, which must be in the " +"\"canonical\" representation. This is less efficient than :c:func:" +"`PyUnicode_READ` if you do multiple consecutive reads." +msgstr "" + +#: ../../c-api/unicode.rst:169 +msgid "" +"Return the maximum code point that is suitable for creating another string " +"based on *unicode*, which must be in the \"canonical\" representation. This " +"is always an approximation but more efficient than iterating over the string." +msgstr "" + +#: ../../c-api/unicode.rst:178 +msgid "" +"Return ``1`` if the string is a valid identifier according to the language " +"definition, section :ref:`identifiers`. Return ``0`` otherwise." +msgstr "" + +#: ../../c-api/unicode.rst:181 +msgid "" +"The function does not call :c:func:`Py_FatalError` anymore if the string is " +"not ready." +msgstr "" + +#: ../../c-api/unicode.rst:188 +msgid "" +"Return true if the string only contains ASCII characters. Equivalent to :py:" +"meth:`str.isascii`." +msgstr "" + +#: ../../c-api/unicode.rst:195 +msgid "Unicode Character Properties" +msgstr "" + +#: ../../c-api/unicode.rst:197 +msgid "" +"Unicode provides many different character properties. The most often needed " +"ones are available through these macros which are mapped to C functions " +"depending on the Python configuration." +msgstr "" + +#: ../../c-api/unicode.rst:204 +msgid "" +"Return ``1`` or ``0`` depending on whether *ch* is a whitespace character." +msgstr "根據 *ch* 是否為空白字元來回傳 ``1`` 或 ``0``。" + +#: ../../c-api/unicode.rst:209 +msgid "" +"Return ``1`` or ``0`` depending on whether *ch* is a lowercase character." +msgstr "根據 *ch* 是否為小寫字元來回傳 ``1`` 或 ``0``。" + +#: ../../c-api/unicode.rst:214 +msgid "" +"Return ``1`` or ``0`` depending on whether *ch* is an uppercase character." +msgstr "根據 *ch* 是否為大寫字元來回傳 ``1`` 或 ``0``。" + +#: ../../c-api/unicode.rst:219 +msgid "" +"Return ``1`` or ``0`` depending on whether *ch* is a titlecase character." +msgstr "根據 *ch* 是否為首字大寫字元來回傳 ``1`` 或 ``0``。" + +#: ../../c-api/unicode.rst:224 +msgid "" +"Return ``1`` or ``0`` depending on whether *ch* is a linebreak character." +msgstr "根據 *ch* 是否為換行字元來回傳 ``1`` 或 ``0``。" + +#: ../../c-api/unicode.rst:229 +msgid "Return ``1`` or ``0`` depending on whether *ch* is a decimal character." +msgstr "根據 *ch* 是否為十進位字元來回傳 ``1`` 或 ``0``。" + +#: ../../c-api/unicode.rst:234 +msgid "Return ``1`` or ``0`` depending on whether *ch* is a digit character." +msgstr "根據 *ch* 是否為數字 (digit) 字元來回傳 ``1`` 或 ``0``。" + +#: ../../c-api/unicode.rst:239 +msgid "Return ``1`` or ``0`` depending on whether *ch* is a numeric character." +msgstr "根據 *ch* 是否為數值 (numeric) 字元來回傳 ``1`` 或 ``0``。" + +#: ../../c-api/unicode.rst:244 +msgid "" +"Return ``1`` or ``0`` depending on whether *ch* is an alphabetic character." +msgstr "根據 *ch* 是否為字母字元來回傳 ``1`` 或 ``0``。" + +#: ../../c-api/unicode.rst:249 +msgid "" +"Return ``1`` or ``0`` depending on whether *ch* is an alphanumeric character." +msgstr "根據 *ch* 是否為字母數字 (alphanumeric) 字元來回傳 ``1`` 或 ``0``。" + +#: ../../c-api/unicode.rst:254 +msgid "" +"Return ``1`` or ``0`` depending on whether *ch* is a printable character, in " +"the sense of :meth:`str.isprintable`." +msgstr "" +"根據 *ch* 是否為可列印字元（如 :meth:`str.isprintable` 所定義）來回傳 ``1`` " +"或 ``0``。" + +#: ../../c-api/unicode.rst:258 +msgid "These APIs can be used for fast direct character conversions:" +msgstr "這些 API 可用於快速直接字元轉換：" + +#: ../../c-api/unicode.rst:263 +msgid "Return the character *ch* converted to lower case." +msgstr "回傳轉換為小寫的 *ch* 字元。" + +#: ../../c-api/unicode.rst:268 +msgid "Return the character *ch* converted to upper case." +msgstr "回傳轉換為大寫的 *ch* 字元。" + +#: ../../c-api/unicode.rst:273 +msgid "Return the character *ch* converted to title case." +msgstr "回傳轉換為首字大寫的 *ch* 字元。" + +#: ../../c-api/unicode.rst:278 +msgid "" +"Return the character *ch* converted to a decimal positive integer. Return " +"``-1`` if this is not possible. This function does not raise exceptions." +msgstr "" +"回傳轉換為十進位正整數的 *ch* 字元，若無法轉換則回傳 ``-1``。此函式不會引發例" +"外。" + +#: ../../c-api/unicode.rst:284 +msgid "" +"Return the character *ch* converted to a single digit integer. Return ``-1`` " +"if this is not possible. This function does not raise exceptions." +msgstr "" +"回傳轉換為單一數字整數的 *ch* 字元，若無法轉換則回傳 ``-1``。此函式不會引發例" +"外。" + +#: ../../c-api/unicode.rst:290 +msgid "" +"Return the character *ch* converted to a double. Return ``-1.0`` if this is " +"not possible. This function does not raise exceptions." +msgstr "" +"回傳轉換為雙精度浮點數 (double) 的 *ch* 字元，若無法轉換則回傳 ``-1.0``。此函" +"式不會引發例外。" + +#: ../../c-api/unicode.rst:294 +msgid "These APIs can be used to work with surrogates:" +msgstr "這些 API 可用於處理代理字元：" + +#: ../../c-api/unicode.rst:298 +msgid "Check if *ch* is a surrogate (``0xD800 <= ch <= 0xDFFF``)." +msgstr "檢查 *ch* 是否為代理字元 (surrogate, ``0xD800 <= ch <= 0xDFFF``)。" + +#: ../../c-api/unicode.rst:302 +msgid "Check if *ch* is a high surrogate (``0xD800 <= ch <= 0xDBFF``)." +msgstr "" +"檢查 *ch* 是否為高代理字元 (high surrogate, ``0xD800 <= ch <= 0xDBFF``)。" + +#: ../../c-api/unicode.rst:306 +msgid "Check if *ch* is a low surrogate (``0xDC00 <= ch <= 0xDFFF``)." +msgstr "" +"檢查 *ch* 是否為低代理字元 (low surrogate, ``0xDC00 <= ch <= 0xDFFF``)。" + +#: ../../c-api/unicode.rst:310 +msgid "" +"Return the high UTF-16 surrogate (``0xD800`` to ``0xDBFF``) for a Unicode " +"code point in the range ``[0x10000; 0x10FFFF]``." +msgstr "" + +#: ../../c-api/unicode.rst:315 +msgid "" +"Return the low UTF-16 surrogate (``0xDC00`` to ``0xDFFF``) for a Unicode " +"code point in the range ``[0x10000; 0x10FFFF]``." +msgstr "" + +#: ../../c-api/unicode.rst:320 +msgid "" +"Join two surrogate code points and return a single :c:type:`Py_UCS4` value. " +"*high* and *low* are respectively the leading and trailing surrogates in a " +"surrogate pair. *high* must be in the range ``[0xD800; 0xDBFF]`` and *low* " +"must be in the range ``[0xDC00; 0xDFFF]``." +msgstr "" + +#: ../../c-api/unicode.rst:327 +msgid "Creating and accessing Unicode strings" +msgstr "" + +#: ../../c-api/unicode.rst:329 +msgid "" +"To create Unicode objects and access their basic sequence properties, use " +"these APIs:" +msgstr "" + +#: ../../c-api/unicode.rst:334 +msgid "" +"Create a new Unicode object. *maxchar* should be the true maximum code " +"point to be placed in the string. As an approximation, it can be rounded up " +"to the nearest value in the sequence 127, 255, 65535, 1114111." +msgstr "" + +#: ../../c-api/unicode.rst:338 +msgid "On error, set an exception and return ``NULL``." +msgstr "" + +#: ../../c-api/unicode.rst:340 +msgid "" +"After creation, the string can be filled by :c:func:`PyUnicode_WriteChar`, :" +"c:func:`PyUnicode_CopyCharacters`, :c:func:`PyUnicode_Fill`, :c:func:" +"`PyUnicode_WRITE` or similar. Since strings are supposed to be immutable, " +"take care to not “use” the result while it is being modified. In particular, " +"before it's filled with its final contents, a string:" +msgstr "" + +#: ../../c-api/unicode.rst:347 +msgid "must not be hashed," +msgstr "" + +#: ../../c-api/unicode.rst:348 +msgid "" +"must not be :c:func:`converted to UTF-8 `, or " +"another non-\"canonical\" representation," +msgstr "" + +#: ../../c-api/unicode.rst:350 +msgid "must not have its reference count changed," +msgstr "" + +#: ../../c-api/unicode.rst:351 +msgid "must not be shared with code that might do one of the above." +msgstr "" + +#: ../../c-api/unicode.rst:353 +msgid "" +"This list is not exhaustive. Avoiding these uses is your responsibility; " +"Python does not always check these requirements." +msgstr "" + +#: ../../c-api/unicode.rst:356 +msgid "" +"To avoid accidentally exposing a partially-written string object, prefer " +"using the :c:type:`PyUnicodeWriter` API, or one of the ``PyUnicode_From*`` " +"functions below." +msgstr "" + +#: ../../c-api/unicode.rst:367 +msgid "" +"Create a new Unicode object with the given *kind* (possible values are :c:" +"macro:`PyUnicode_1BYTE_KIND` etc., as returned by :c:func:" +"`PyUnicode_KIND`). The *buffer* must point to an array of *size* units of " +"1, 2 or 4 bytes per character, as given by the kind." +msgstr "" + +#: ../../c-api/unicode.rst:372 +msgid "" +"If necessary, the input *buffer* is copied and transformed into the " +"canonical representation. For example, if the *buffer* is a UCS4 string (:c:" +"macro:`PyUnicode_4BYTE_KIND`) and it consists only of codepoints in the UCS1 " +"range, it will be transformed into UCS1 (:c:macro:`PyUnicode_1BYTE_KIND`)." +msgstr "" + +#: ../../c-api/unicode.rst:383 +msgid "" +"Create a Unicode object from the char buffer *str*. The bytes will be " +"interpreted as being UTF-8 encoded. The buffer is copied into the new " +"object. The return value might be a shared object, i.e. modification of the " +"data is not allowed." +msgstr "" + +#: ../../c-api/unicode.rst:389 +msgid "This function raises :exc:`SystemError` when:" +msgstr "此函式在以下情況下會引發 :exc:`SystemError`：" + +#: ../../c-api/unicode.rst:391 +msgid "*size* < 0," +msgstr "*size* < 0，" + +#: ../../c-api/unicode.rst:392 +msgid "*str* is ``NULL`` and *size* > 0" +msgstr "*str* 為 ``NULL`` 且 *size* > 0" + +#: ../../c-api/unicode.rst:394 +msgid "*str* == ``NULL`` with *size* > 0 is not allowed anymore." +msgstr "*str* == ``NULL`` 且 *size* > 0 不再被允許。" + +#: ../../c-api/unicode.rst:400 +msgid "" +"Create a Unicode object from a UTF-8 encoded null-terminated char buffer " +"*str*." +msgstr "" + +#: ../../c-api/unicode.rst:406 +msgid "" +"Take a C :c:func:`printf`\\ -style *format* string and a variable number of " +"arguments, calculate the size of the resulting Python Unicode string and " +"return a string with the values formatted into it. The variable arguments " +"must be C types and must correspond exactly to the format characters in the " +"*format* ASCII-encoded string." +msgstr "" + +#: ../../c-api/unicode.rst:412 +msgid "" +"A conversion specifier contains two or more characters and has the following " +"components, which must occur in this order:" +msgstr "" + +#: ../../c-api/unicode.rst:415 +msgid "The ``'%'`` character, which marks the start of the specifier." +msgstr "" + +#: ../../c-api/unicode.rst:417 +msgid "" +"Conversion flags (optional), which affect the result of some conversion " +"types." +msgstr "" + +#: ../../c-api/unicode.rst:420 +msgid "" +"Minimum field width (optional). If specified as an ``'*'`` (asterisk), the " +"actual width is given in the next argument, which must be of type :c:expr:" +"`int`, and the object to convert comes after the minimum field width and " +"optional precision." +msgstr "" + +#: ../../c-api/unicode.rst:425 +msgid "" +"Precision (optional), given as a ``'.'`` (dot) followed by the precision. If " +"specified as ``'*'`` (an asterisk), the actual precision is given in the " +"next argument, which must be of type :c:expr:`int`, and the value to convert " +"comes after the precision." +msgstr "" + +#: ../../c-api/unicode.rst:430 +msgid "Length modifier (optional)." +msgstr "" + +#: ../../c-api/unicode.rst:432 +msgid "Conversion type." +msgstr "" + +#: ../../c-api/unicode.rst:434 +msgid "The conversion flag characters are:" +msgstr "" + +#: ../../c-api/unicode.rst:439 +msgid "Flag" +msgstr "旗標" + +#: ../../c-api/unicode.rst:439 +msgid "Meaning" +msgstr "含義" + +#: ../../c-api/unicode.rst:441 +msgid "``0``" +msgstr "``0``" + +#: ../../c-api/unicode.rst:441 +msgid "The conversion will be zero padded for numeric values." +msgstr "" + +#: ../../c-api/unicode.rst:443 +msgid "``-``" +msgstr "``-``" + +#: ../../c-api/unicode.rst:443 +msgid "" +"The converted value is left adjusted (overrides the ``0`` flag if both are " +"given)." +msgstr "" + +#: ../../c-api/unicode.rst:447 +msgid "" +"The length modifiers for following integer conversions (``d``, ``i``, ``o``, " +"``u``, ``x``, or ``X``) specify the type of the argument (:c:expr:`int` by " +"default):" +msgstr "" + +#: ../../c-api/unicode.rst:454 +msgid "Modifier" +msgstr "" + +#: ../../c-api/unicode.rst:454 +msgid "Types" +msgstr "" + +#: ../../c-api/unicode.rst:456 +msgid "``l``" +msgstr "``l``" + +#: ../../c-api/unicode.rst:456 +msgid ":c:expr:`long` or :c:expr:`unsigned long`" +msgstr ":c:expr:`long` 或 :c:expr:`unsigned long`" + +#: ../../c-api/unicode.rst:458 +msgid "``ll``" +msgstr "``ll``" + +#: ../../c-api/unicode.rst:458 +msgid ":c:expr:`long long` or :c:expr:`unsigned long long`" +msgstr ":c:expr:`long long` 或 :c:expr:`unsigned long long`" + +#: ../../c-api/unicode.rst:460 +msgid "``j``" +msgstr "``j``" + +#: ../../c-api/unicode.rst:460 +msgid ":c:type:`intmax_t` or :c:type:`uintmax_t`" +msgstr ":c:type:`intmax_t` 或 :c:type:`uintmax_t`" + +#: ../../c-api/unicode.rst:462 +msgid "``z``" +msgstr "``z``" + +#: ../../c-api/unicode.rst:462 +msgid ":c:type:`size_t` or :c:type:`ssize_t`" +msgstr ":c:type:`size_t` 或 :c:type:`ssize_t`" + +#: ../../c-api/unicode.rst:464 +msgid "``t``" +msgstr "``t``" + +#: ../../c-api/unicode.rst:464 +msgid ":c:type:`ptrdiff_t`" +msgstr ":c:type:`ptrdiff_t`" + +#: ../../c-api/unicode.rst:467 +msgid "" +"The length modifier ``l`` for following conversions ``s`` or ``V`` specify " +"that the type of the argument is :c:expr:`const wchar_t*`." +msgstr "" + +#: ../../c-api/unicode.rst:470 +msgid "The conversion specifiers are:" +msgstr "" + +#: ../../c-api/unicode.rst:476 +msgid "Conversion Specifier" +msgstr "" + +#: ../../c-api/unicode.rst:477 +msgid "Type" +msgstr "" + +#: ../../c-api/unicode.rst:478 +msgid "Comment" +msgstr "" + +#: ../../c-api/unicode.rst:480 +msgid "``%``" +msgstr "``%``" + +#: ../../c-api/unicode.rst:481 +msgid "*n/a*" +msgstr "*n/a*" + +#: ../../c-api/unicode.rst:482 +msgid "The literal ``%`` character." +msgstr "字面 ``%`` 字元。" + +#: ../../c-api/unicode.rst:484 +msgid "``d``, ``i``" +msgstr "``d``, ``i``" + +#: ../../c-api/unicode.rst:485 ../../c-api/unicode.rst:489 +#: ../../c-api/unicode.rst:493 ../../c-api/unicode.rst:497 +#: ../../c-api/unicode.rst:501 +msgid "Specified by the length modifier" +msgstr "" + +#: ../../c-api/unicode.rst:486 +msgid "The decimal representation of a signed C integer." +msgstr "一個有符號 C 整數的十進位表示法。" + +#: ../../c-api/unicode.rst:488 +msgid "``u``" +msgstr "``u``" + +#: ../../c-api/unicode.rst:490 +msgid "The decimal representation of an unsigned C integer." +msgstr "一個無符號 C 整數的十進位表示法。" + +#: ../../c-api/unicode.rst:492 +msgid "``o``" +msgstr "``o``" + +#: ../../c-api/unicode.rst:494 +msgid "The octal representation of an unsigned C integer." +msgstr "一個無符號 C 整數的八進位表示法。" + +#: ../../c-api/unicode.rst:496 +msgid "``x``" +msgstr "``x``" + +#: ../../c-api/unicode.rst:498 +msgid "The hexadecimal representation of an unsigned C integer (lowercase)." +msgstr "一個無符號 C 整數的十六進位表示法（小寫）。" + +#: ../../c-api/unicode.rst:500 +msgid "``X``" +msgstr "``X``" + +#: ../../c-api/unicode.rst:502 +msgid "The hexadecimal representation of an unsigned C integer (uppercase)." +msgstr "一個無符號 C 整數的十六進位表示法（大寫）。" + +#: ../../c-api/unicode.rst:504 +msgid "``c``" +msgstr "``c``" + +#: ../../c-api/unicode.rst:505 +msgid ":c:expr:`int`" +msgstr ":c:expr:`int`" + +#: ../../c-api/unicode.rst:506 +msgid "A single character." +msgstr "一個單一字元。" + +#: ../../c-api/unicode.rst:508 +msgid "``s``" +msgstr "``s``" + +#: ../../c-api/unicode.rst:509 +msgid ":c:expr:`const char*` or :c:expr:`const wchar_t*`" +msgstr ":c:expr:`const char*` 或 :c:expr:`const wchar_t*`" + +#: ../../c-api/unicode.rst:510 +msgid "A null-terminated C character array." +msgstr "一個以 null 結尾的 C 字元陣列。" + +#: ../../c-api/unicode.rst:512 +msgid "``p``" +msgstr "``p``" + +#: ../../c-api/unicode.rst:513 +msgid ":c:expr:`const void*`" +msgstr ":c:expr:`const void*`" + +#: ../../c-api/unicode.rst:514 +msgid "" +"The hex representation of a C pointer. Mostly equivalent to " +"``printf(\"%p\")`` except that it is guaranteed to start with the literal " +"``0x`` regardless of what the platform's ``printf`` yields." +msgstr "" + +#: ../../c-api/unicode.rst:519 +msgid "``A``" +msgstr "``A``" + +#: ../../c-api/unicode.rst:520 ../../c-api/unicode.rst:524 +#: ../../c-api/unicode.rst:534 ../../c-api/unicode.rst:538 +#: ../../c-api/unicode.rst:542 ../../c-api/unicode.rst:547 +msgid ":c:expr:`PyObject*`" +msgstr ":c:expr:`PyObject*`" + +#: ../../c-api/unicode.rst:521 +msgid "The result of calling :func:`ascii`." +msgstr "呼叫 :func:`ascii` 的結果。" + +#: ../../c-api/unicode.rst:523 +msgid "``U``" +msgstr "``U``" + +#: ../../c-api/unicode.rst:525 +msgid "A Unicode object." +msgstr "一個 Unicode 物件。" + +#: ../../c-api/unicode.rst:527 +msgid "``V``" +msgstr "``V``" + +#: ../../c-api/unicode.rst:528 +msgid ":c:expr:`PyObject*`, :c:expr:`const char*` or :c:expr:`const wchar_t*`" +msgstr ":c:expr:`PyObject*`、:c:expr:`const char*` 或 :c:expr:`const wchar_t*`" + +#: ../../c-api/unicode.rst:529 +msgid "" +"A Unicode object (which may be ``NULL``) and a null-terminated C character " +"array as a second parameter (which will be used, if the first parameter is " +"``NULL``)." +msgstr "" + +#: ../../c-api/unicode.rst:533 +msgid "``S``" +msgstr "``S``" + +#: ../../c-api/unicode.rst:535 +msgid "The result of calling :c:func:`PyObject_Str`." +msgstr "呼叫 :c:func:`PyObject_Str` 的結果。" + +#: ../../c-api/unicode.rst:537 +msgid "``R``" +msgstr "``R``" + +#: ../../c-api/unicode.rst:539 +msgid "The result of calling :c:func:`PyObject_Repr`." +msgstr "呼叫 :c:func:`PyObject_Repr` 的結果。" + +#: ../../c-api/unicode.rst:541 +msgid "``T``" +msgstr "``T``" + +#: ../../c-api/unicode.rst:543 +msgid "" +"Get the fully qualified name of an object type; call :c:func:" +"`PyType_GetFullyQualifiedName`." +msgstr "" + +#: ../../c-api/unicode.rst:546 +msgid "``#T``" +msgstr "``#T``" + +#: ../../c-api/unicode.rst:548 +msgid "" +"Similar to ``T`` format, but use a colon (``:``) as separator between the " +"module name and the qualified name." +msgstr "" + +#: ../../c-api/unicode.rst:551 +msgid "``N``" +msgstr "``N``" + +#: ../../c-api/unicode.rst:552 ../../c-api/unicode.rst:557 +msgid ":c:expr:`PyTypeObject*`" +msgstr ":c:expr:`PyTypeObject*`" + +#: ../../c-api/unicode.rst:553 +msgid "" +"Get the fully qualified name of a type; call :c:func:" +"`PyType_GetFullyQualifiedName`." +msgstr "" + +#: ../../c-api/unicode.rst:556 +msgid "``#N``" +msgstr "``#N``" + +#: ../../c-api/unicode.rst:558 +msgid "" +"Similar to ``N`` format, but use a colon (``:``) as separator between the " +"module name and the qualified name." +msgstr "" + +#: ../../c-api/unicode.rst:562 +msgid "" +"The width formatter unit is number of characters rather than bytes. The " +"precision formatter unit is number of bytes or :c:type:`wchar_t` items (if " +"the length modifier ``l`` is used) for ``\"%s\"`` and ``\"%V\"`` (if the " +"``PyObject*`` argument is ``NULL``), and a number of characters for " +"``\"%A\"``, ``\"%U\"``, ``\"%S\"``, ``\"%R\"`` and ``\"%V\"`` (if the " +"``PyObject*`` argument is not ``NULL``)." +msgstr "" + +#: ../../c-api/unicode.rst:570 +msgid "" +"Unlike to C :c:func:`printf` the ``0`` flag has effect even when a precision " +"is given for integer conversions (``d``, ``i``, ``u``, ``o``, ``x``, or " +"``X``)." +msgstr "" + +#: ../../c-api/unicode.rst:574 +msgid "Support for ``\"%lld\"`` and ``\"%llu\"`` added." +msgstr "新增對 ``\"%lld\"`` 和 ``\"%llu\"`` 的支援。" + +#: ../../c-api/unicode.rst:577 +msgid "Support for ``\"%li\"``, ``\"%lli\"`` and ``\"%zi\"`` added." +msgstr "新增對 ``\"%li\"``、``\"%lli\"`` 和 ``\"%zi\"`` 的支援。" + +#: ../../c-api/unicode.rst:580 +msgid "" +"Support width and precision formatter for ``\"%s\"``, ``\"%A\"``, " +"``\"%U\"``, ``\"%V\"``, ``\"%S\"``, ``\"%R\"`` added." +msgstr "" +"新增對 ``\"%s\"``、``\"%A\"``、``\"%U\"``、``\"%V\"``、``\"%S\"``、" +"``\"%R\"`` 的寬度和精確度格式化支援。" + +#: ../../c-api/unicode.rst:584 +msgid "" +"Support for conversion specifiers ``o`` and ``X``. Support for length " +"modifiers ``j`` and ``t``. Length modifiers are now applied to all integer " +"conversions. Length modifier ``l`` is now applied to conversion specifiers " +"``s`` and ``V``. Support for variable width and precision ``*``. Support for " +"flag ``-``." +msgstr "" + +#: ../../c-api/unicode.rst:592 +msgid "" +"An unrecognized format character now sets a :exc:`SystemError`. In previous " +"versions it caused all the rest of the format string to be copied as-is to " +"the result string, and any extra arguments discarded." +msgstr "" + +#: ../../c-api/unicode.rst:596 +msgid "Support for ``%T``, ``%#T``, ``%N`` and ``%#N`` formats added." +msgstr "新增對 ``%T``、``%#T``、``%N`` 和 ``%#N`` 格式的支援。" + +#: ../../c-api/unicode.rst:602 +msgid "" +"Identical to :c:func:`PyUnicode_FromFormat` except that it takes exactly two " +"arguments." +msgstr "" + +#: ../../c-api/unicode.rst:608 +msgid "" +"Copy an instance of a Unicode subtype to a new true Unicode object if " +"necessary. If *obj* is already a true Unicode object (not a subtype), return " +"a new :term:`strong reference` to the object." +msgstr "" + +#: ../../c-api/unicode.rst:612 +msgid "" +"Objects other than Unicode or its subtypes will cause a :exc:`TypeError`." +msgstr "" + +#: ../../c-api/unicode.rst:617 +msgid "Create a Unicode Object from the given Unicode code point *ordinal*." +msgstr "" + +#: ../../c-api/unicode.rst:619 +msgid "" +"The ordinal must be in ``range(0x110000)``. A :exc:`ValueError` is raised in " +"the case it is not." +msgstr "" + +#: ../../c-api/unicode.rst:626 +msgid "Decode an encoded object *obj* to a Unicode object." +msgstr "" + +#: ../../c-api/unicode.rst:628 +msgid "" +":class:`bytes`, :class:`bytearray` and other :term:`bytes-like objects " +"` are decoded according to the given *encoding* and using " +"the error handling defined by *errors*. Both can be ``NULL`` to have the " +"interface use the default values (see :ref:`builtincodecs` for details)." +msgstr "" + +#: ../../c-api/unicode.rst:634 +msgid "" +"All other objects, including Unicode objects, cause a :exc:`TypeError` to be " +"set." +msgstr "" + +#: ../../c-api/unicode.rst:637 +msgid "" +"The API returns ``NULL`` if there was an error. The caller is responsible " +"for decref'ing the returned objects." +msgstr "" + +#: ../../c-api/unicode.rst:643 +msgid "" +"Append the string *right* to the end of *p_left*. *p_left* must point to a :" +"term:`strong reference` to a Unicode object; :c:func:`!PyUnicode_Append` " +"releases (\"steals\") this reference." +msgstr "" + +#: ../../c-api/unicode.rst:647 +msgid "On error, set *\\*p_left* to ``NULL`` and set an exception." +msgstr "於錯誤發生時，將 *\\*p_left* 設為 ``NULL`` 並設定例外。" + +#: ../../c-api/unicode.rst:649 +msgid "On success, set *\\*p_left* to a new strong reference to the result." +msgstr "" + +#: ../../c-api/unicode.rst:654 +msgid "" +"The function is similar to :c:func:`PyUnicode_Append`, with the only " +"difference being that it decrements the reference count of *right* by one." +msgstr "" + +#: ../../c-api/unicode.rst:660 +msgid "" +"Return a mapping suitable for decoding a custom single-byte encoding. Given " +"a Unicode string *string* of up to 256 characters representing an encoding " +"table, returns either a compact internal mapping object or a dictionary " +"mapping character ordinals to byte values. Raises a :exc:`TypeError` and " +"return ``NULL`` on invalid input." +msgstr "" + +#: ../../c-api/unicode.rst:671 +msgid "" +"Return the name of the default string encoding, ``\"utf-8\"``. See :func:" +"`sys.getdefaultencoding`." +msgstr "" + +#: ../../c-api/unicode.rst:674 +msgid "" +"The returned string does not need to be freed, and is valid until " +"interpreter shutdown." +msgstr "" + +#: ../../c-api/unicode.rst:680 +msgid "Return the length of the Unicode object, in code points." +msgstr "" + +#: ../../c-api/unicode.rst:682 +msgid "On error, set an exception and return ``-1``." +msgstr "發生錯誤時，設定例外並回傳 ``-1``。" + +#: ../../c-api/unicode.rst:693 +msgid "" +"Copy characters from one Unicode object into another. This function " +"performs character conversion when necessary and falls back to :c:func:`!" +"memcpy` if possible. Returns ``-1`` and sets an exception on error, " +"otherwise returns the number of copied characters." +msgstr "" + +#: ../../c-api/unicode.rst:698 ../../c-api/unicode.rst:728 +#: ../../c-api/unicode.rst:748 +msgid "" +"The string must not have been “used” yet. See :c:func:`PyUnicode_New` for " +"details." +msgstr "" + +#: ../../c-api/unicode.rst:706 +msgid "" +"Resize a Unicode object *\\*unicode* to the new *length* in code points." +msgstr "" + +#: ../../c-api/unicode.rst:708 +msgid "" +"Try to resize the string in place (which is usually faster than allocating a " +"new string and copying characters), or create a new string." +msgstr "" + +#: ../../c-api/unicode.rst:711 +msgid "" +"*\\*unicode* is modified to point to the new (resized) object and ``0`` is " +"returned on success. Otherwise, ``-1`` is returned and an exception is set, " +"and *\\*unicode* is left untouched." +msgstr "" + +#: ../../c-api/unicode.rst:715 +msgid "" +"The function doesn't check string content, the result may not be a string in " +"canonical representation." +msgstr "" + +#: ../../c-api/unicode.rst:722 +msgid "" +"Fill a string with a character: write *fill_char* into ``unicode[start:" +"start+length]``." +msgstr "" + +#: ../../c-api/unicode.rst:725 +msgid "" +"Fail if *fill_char* is bigger than the string maximum character, or if the " +"string has more than 1 reference." +msgstr "" + +#: ../../c-api/unicode.rst:731 +msgid "" +"Return the number of written character, or return ``-1`` and raise an " +"exception on error." +msgstr "" + +#: ../../c-api/unicode.rst:740 +msgid "" +"Write a *character* to the string *unicode* at the zero-based *index*. " +"Return ``0`` on success, ``-1`` on error with an exception set." +msgstr "" + +#: ../../c-api/unicode.rst:743 +msgid "" +"This function checks that *unicode* is a Unicode object, that the index is " +"not out of bounds, and that the object's reference count is one. See :c:func:" +"`PyUnicode_WRITE` for a version that skips these checks, making them your " +"responsibility." +msgstr "" + +#: ../../c-api/unicode.rst:756 +msgid "" +"Read a character from a string. This function checks that *unicode* is a " +"Unicode object and the index is not out of bounds, in contrast to :c:func:" +"`PyUnicode_READ_CHAR`, which performs no error checking." +msgstr "" + +#: ../../c-api/unicode.rst:760 +msgid "Return character on success, ``-1`` on error with an exception set." +msgstr "成功時回傳字元，發生錯誤時設定例外並回傳 ``-1``。" + +#: ../../c-api/unicode.rst:768 +msgid "" +"Return a substring of *unicode*, from character index *start* (included) to " +"character index *end* (excluded). Negative indices are not supported. On " +"error, set an exception and return ``NULL``." +msgstr "" + +#: ../../c-api/unicode.rst:778 +msgid "" +"Copy the string *unicode* into a UCS4 buffer, including a null character, if " +"*copy_null* is set. Returns ``NULL`` and sets an exception on error (in " +"particular, a :exc:`SystemError` if *buflen* is smaller than the length of " +"*unicode*). *buffer* is returned on success." +msgstr "" + +#: ../../c-api/unicode.rst:788 +msgid "" +"Copy the string *unicode* into a new UCS4 buffer that is allocated using :c:" +"func:`PyMem_Malloc`. If this fails, ``NULL`` is returned with a :exc:" +"`MemoryError` set. The returned buffer always has an extra null code point " +"appended." +msgstr "" + +#: ../../c-api/unicode.rst:797 +msgid "Locale Encoding" +msgstr "" + +#: ../../c-api/unicode.rst:799 +msgid "" +"The current locale encoding can be used to decode text from the operating " +"system." +msgstr "" + +#: ../../c-api/unicode.rst:806 +msgid "" +"Decode a string from UTF-8 on Android and VxWorks, or from the current " +"locale encoding on other platforms. The supported error handlers are " +"``\"strict\"`` and ``\"surrogateescape\"`` (:pep:`383`). The decoder uses " +"``\"strict\"`` error handler if *errors* is ``NULL``. *str* must end with a " +"null character but cannot contain embedded null characters." +msgstr "" + +#: ../../c-api/unicode.rst:813 +msgid "" +"Use :c:func:`PyUnicode_DecodeFSDefaultAndSize` to decode a string from the :" +"term:`filesystem encoding and error handler`." +msgstr "" + +#: ../../c-api/unicode.rst:816 ../../c-api/unicode.rst:851 +msgid "This function ignores the :ref:`Python UTF-8 Mode `." +msgstr "此函式會忽略 :ref:`Python UTF-8 模式 `。" + +#: ../../c-api/unicode.rst:820 ../../c-api/unicode.rst:936 +msgid "The :c:func:`Py_DecodeLocale` function." +msgstr ":c:func:`Py_DecodeLocale` 函式。" + +#: ../../c-api/unicode.rst:824 +msgid "" +"The function now also uses the current locale encoding for the " +"``surrogateescape`` error handler, except on Android. Previously, :c:func:" +"`Py_DecodeLocale` was used for the ``surrogateescape``, and the current " +"locale encoding was used for ``strict``." +msgstr "" + +#: ../../c-api/unicode.rst:833 +msgid "" +"Similar to :c:func:`PyUnicode_DecodeLocaleAndSize`, but compute the string " +"length using :c:func:`!strlen`." +msgstr "" +"類似於 :c:func:`PyUnicode_DecodeLocaleAndSize`，但使用 :c:func:`!strlen` 計算" +"字串長度。" + +#: ../../c-api/unicode.rst:841 +msgid "" +"Encode a Unicode object to UTF-8 on Android and VxWorks, or to the current " +"locale encoding on other platforms. The supported error handlers are " +"``\"strict\"`` and ``\"surrogateescape\"`` (:pep:`383`). The encoder uses " +"``\"strict\"`` error handler if *errors* is ``NULL``. Return a :class:" +"`bytes` object. *unicode* cannot contain embedded null characters." +msgstr "" + +#: ../../c-api/unicode.rst:848 +msgid "" +"Use :c:func:`PyUnicode_EncodeFSDefault` to encode a string to the :term:" +"`filesystem encoding and error handler`." +msgstr "" + +#: ../../c-api/unicode.rst:855 ../../c-api/unicode.rst:967 +msgid "The :c:func:`Py_EncodeLocale` function." +msgstr ":c:func:`Py_EncodeLocale` 函式。" + +#: ../../c-api/unicode.rst:859 +msgid "" +"The function now also uses the current locale encoding for the " +"``surrogateescape`` error handler, except on Android. Previously, :c:func:" +"`Py_EncodeLocale` was used for the ``surrogateescape``, and the current " +"locale encoding was used for ``strict``." +msgstr "" + +#: ../../c-api/unicode.rst:868 +msgid "File System Encoding" +msgstr "檔案系統編碼" + +#: ../../c-api/unicode.rst:870 +msgid "" +"Functions encoding to and decoding from the :term:`filesystem encoding and " +"error handler` (:pep:`383` and :pep:`529`)." +msgstr "" + +#: ../../c-api/unicode.rst:873 +msgid "" +"To encode file names to :class:`bytes` during argument parsing, the " +"``\"O&\"`` converter should be used, passing :c:func:`!" +"PyUnicode_FSConverter` as the conversion function:" +msgstr "" + +#: ../../c-api/unicode.rst:879 +msgid "" +":ref:`PyArg_Parse\\* converter `: encode :class:`str` objects " +"-- obtained directly or through the :class:`os.PathLike` interface -- to :" +"class:`bytes` using :c:func:`PyUnicode_EncodeFSDefault`; :class:`bytes` " +"objects are output as-is. *result* must be an address of a C variable of " +"type :c:expr:`PyObject*` (or :c:expr:`PyBytesObject*`). On success, set the " +"variable to a new :term:`strong reference` to a :ref:`bytes object " +"` which must be released when it is no longer used and return " +"a non-zero value (:c:macro:`Py_CLEANUP_SUPPORTED`). Embedded null bytes are " +"not allowed in the result. On failure, return ``0`` with an exception set." +msgstr "" + +#: ../../c-api/unicode.rst:891 +msgid "" +"If *obj* is ``NULL``, the function releases a strong reference stored in the " +"variable referred by *result* and returns ``1``." +msgstr "" + +#: ../../c-api/unicode.rst:896 ../../c-api/unicode.rst:923 +msgid "Accepts a :term:`path-like object`." +msgstr "接受一個 :term:`path-like object`。" + +#: ../../c-api/unicode.rst:899 +msgid "" +"To decode file names to :class:`str` during argument parsing, the ``\"O&\"`` " +"converter should be used, passing :c:func:`!PyUnicode_FSDecoder` as the " +"conversion function:" +msgstr "" + +#: ../../c-api/unicode.rst:905 +msgid "" +":ref:`PyArg_Parse\\* converter `: decode :class:`bytes` objects " +"-- obtained either directly or indirectly through the :class:`os.PathLike` " +"interface -- to :class:`str` using :c:func:" +"`PyUnicode_DecodeFSDefaultAndSize`; :class:`str` objects are output as-is. " +"*result* must be an address of a C variable of type :c:expr:`PyObject*` (or :" +"c:expr:`PyUnicodeObject*`). On success, set the variable to a new :term:" +"`strong reference` to a :ref:`Unicode object ` which must be " +"released when it is no longer used and return a non-zero value (:c:macro:" +"`Py_CLEANUP_SUPPORTED`). Embedded null characters are not allowed in the " +"result. On failure, return ``0`` with an exception set." +msgstr "" + +#: ../../c-api/unicode.rst:918 +msgid "" +"If *obj* is ``NULL``, release the strong reference to the object referred to " +"by *result* and return ``1``." +msgstr "" + +#: ../../c-api/unicode.rst:929 +msgid "Decode a string from the :term:`filesystem encoding and error handler`." +msgstr "" + +#: ../../c-api/unicode.rst:931 +msgid "" +"If you need to decode a string from the current locale encoding, use :c:func:" +"`PyUnicode_DecodeLocaleAndSize`." +msgstr "" + +#: ../../c-api/unicode.rst:938 ../../c-api/unicode.rst:951 +#: ../../c-api/unicode.rst:971 +msgid "" +"The :term:`filesystem error handler ` " +"is now used." +msgstr "" + +#: ../../c-api/unicode.rst:945 +msgid "" +"Decode a null-terminated string from the :term:`filesystem encoding and " +"error handler`." +msgstr "" + +#: ../../c-api/unicode.rst:948 +msgid "" +"If the string length is known, use :c:func:" +"`PyUnicode_DecodeFSDefaultAndSize`." +msgstr "如果字串長度已知，請使用 :c:func:`PyUnicode_DecodeFSDefaultAndSize`。" + +#: ../../c-api/unicode.rst:958 +msgid "" +"Encode a Unicode object to the :term:`filesystem encoding and error " +"handler`, and return :class:`bytes`. Note that the resulting :class:`bytes` " +"object can contain null bytes." +msgstr "" + +#: ../../c-api/unicode.rst:962 +msgid "" +"If you need to encode a string to the current locale encoding, use :c:func:" +"`PyUnicode_EncodeLocale`." +msgstr "" + +#: ../../c-api/unicode.rst:976 +msgid "wchar_t Support" +msgstr "wchar_t 支援" + +#: ../../c-api/unicode.rst:978 +msgid ":c:type:`wchar_t` support for platforms which support it:" +msgstr "對支援 :c:type:`wchar_t` 的平台提供支援：" + +#: ../../c-api/unicode.rst:982 +msgid "" +"Create a Unicode object from the :c:type:`wchar_t` buffer *wstr* of the " +"given *size*. Passing ``-1`` as the *size* indicates that the function must " +"itself compute the length, using :c:func:`!wcslen`. Return ``NULL`` on " +"failure." +msgstr "" + +#: ../../c-api/unicode.rst:990 +msgid "" +"Copy the Unicode object contents into the :c:type:`wchar_t` buffer *wstr*. " +"At most *size* :c:type:`wchar_t` characters are copied (excluding a possibly " +"trailing null termination character). Return the number of :c:type:" +"`wchar_t` characters copied or ``-1`` in case of an error." +msgstr "" + +#: ../../c-api/unicode.rst:995 +msgid "" +"When *wstr* is ``NULL``, instead return the *size* that would be required to " +"store all of *unicode* including a terminating null." +msgstr "" + +#: ../../c-api/unicode.rst:998 +msgid "" +"Note that the resulting :c:expr:`wchar_t*` string may or may not be null-" +"terminated. It is the responsibility of the caller to make sure that the :c:" +"expr:`wchar_t*` string is null-terminated in case this is required by the " +"application. Also, note that the :c:expr:`wchar_t*` string might contain " +"null characters, which would cause the string to be truncated when used with " +"most C functions." +msgstr "" + +#: ../../c-api/unicode.rst:1008 +msgid "" +"Convert the Unicode object to a wide character string. The output string " +"always ends with a null character. If *size* is not ``NULL``, write the " +"number of wide characters (excluding the trailing null termination " +"character) into *\\*size*. Note that the resulting :c:type:`wchar_t` string " +"might contain null characters, which would cause the string to be truncated " +"when used with most C functions. If *size* is ``NULL`` and the :c:expr:" +"`wchar_t*` string contains null characters a :exc:`ValueError` is raised." +msgstr "" + +#: ../../c-api/unicode.rst:1016 +msgid "" +"Returns a buffer allocated by :c:macro:`PyMem_New` (use :c:func:`PyMem_Free` " +"to free it) on success. On error, returns ``NULL`` and *\\*size* is " +"undefined. Raises a :exc:`MemoryError` if memory allocation is failed." +msgstr "" + +#: ../../c-api/unicode.rst:1023 +msgid "" +"Raises a :exc:`ValueError` if *size* is ``NULL`` and the :c:expr:`wchar_t*` " +"string contains null characters." +msgstr "" + +#: ../../c-api/unicode.rst:1031 +msgid "Built-in Codecs" +msgstr "內建編解碼器" + +#: ../../c-api/unicode.rst:1033 +msgid "" +"Python provides a set of built-in codecs which are written in C for speed. " +"All of these codecs are directly usable via the following functions." +msgstr "" + +#: ../../c-api/unicode.rst:1036 +msgid "" +"Many of the following APIs take two arguments encoding and errors, and they " +"have the same semantics as the ones of the built-in :func:`str` string " +"object constructor." +msgstr "" + +#: ../../c-api/unicode.rst:1040 +msgid "" +"Setting encoding to ``NULL`` causes the default encoding to be used which is " +"UTF-8. The file system calls should use :c:func:`PyUnicode_FSConverter` for " +"encoding file names. This uses the :term:`filesystem encoding and error " +"handler` internally." +msgstr "" + +#: ../../c-api/unicode.rst:1045 +msgid "" +"Error handling is set by errors which may also be set to ``NULL`` meaning to " +"use the default handling defined for the codec. Default error handling for " +"all built-in codecs is \"strict\" (:exc:`ValueError` is raised)." +msgstr "" + +#: ../../c-api/unicode.rst:1049 +msgid "" +"The codecs all use a similar interface. Only deviations from the following " +"generic ones are documented for simplicity." +msgstr "" + +#: ../../c-api/unicode.rst:1054 +msgid "Generic Codecs" +msgstr "泛用編解碼器" + +#: ../../c-api/unicode.rst:1056 +msgid "The following macro is provided:" +msgstr "" + +#: ../../c-api/unicode.rst:1061 +msgid "The Unicode code point ``U+FFFD`` (replacement character)." +msgstr "" + +#: ../../c-api/unicode.rst:1063 +msgid "" +"This Unicode character is used as the replacement character during decoding " +"if the *errors* argument is set to \"replace\"." +msgstr "" + +#: ../../c-api/unicode.rst:1067 +msgid "These are the generic codec APIs:" +msgstr "這些是泛用編解碼器的 API：" + +#: ../../c-api/unicode.rst:1073 +msgid "" +"Create a Unicode object by decoding *size* bytes of the encoded string " +"*str*. *encoding* and *errors* have the same meaning as the parameters of " +"the same name in the :func:`str` built-in function. The codec to be used is " +"looked up using the Python codec registry. Return ``NULL`` if an exception " +"was raised by the codec." +msgstr "" + +#: ../../c-api/unicode.rst:1083 +msgid "" +"Encode a Unicode object and return the result as Python bytes object. " +"*encoding* and *errors* have the same meaning as the parameters of the same " +"name in the Unicode :meth:`~str.encode` method. The codec to be used is " +"looked up using the Python codec registry. Return ``NULL`` if an exception " +"was raised by the codec." +msgstr "" + +#: ../../c-api/unicode.rst:1091 +msgid "UTF-8 Codecs" +msgstr "UTF-8 編解碼器" + +#: ../../c-api/unicode.rst:1093 +msgid "These are the UTF-8 codec APIs:" +msgstr "這些是 UTF-8 編解碼器的 API：" + +#: ../../c-api/unicode.rst:1098 +msgid "" +"Create a Unicode object by decoding *size* bytes of the UTF-8 encoded string " +"*str*. Return ``NULL`` if an exception was raised by the codec." +msgstr "" + +#: ../../c-api/unicode.rst:1105 +msgid "" +"If *consumed* is ``NULL``, behave like :c:func:`PyUnicode_DecodeUTF8`. If " +"*consumed* is not ``NULL``, trailing incomplete UTF-8 byte sequences will " +"not be treated as an error. Those bytes will not be decoded and the number " +"of bytes that have been decoded will be stored in *consumed*." +msgstr "" + +#: ../../c-api/unicode.rst:1113 +msgid "" +"Encode a Unicode object using UTF-8 and return the result as Python bytes " +"object. Error handling is \"strict\". Return ``NULL`` if an exception was " +"raised by the codec." +msgstr "" + +#: ../../c-api/unicode.rst:1117 ../../c-api/unicode.rst:1132 +msgid "" +"The function fails if the string contains surrogate code points (``U+D800`` " +"- ``U+DFFF``)." +msgstr "" + +#: ../../c-api/unicode.rst:1123 +msgid "" +"Return a pointer to the UTF-8 encoding of the Unicode object, and store the " +"size of the encoded representation (in bytes) in *size*. The *size* " +"argument can be ``NULL``; in this case no size will be stored. The returned " +"buffer always has an extra null byte appended (not included in *size*), " +"regardless of whether there are any other null code points." +msgstr "" + +#: ../../c-api/unicode.rst:1129 +msgid "" +"On error, set an exception, set *size* to ``-1`` (if it's not NULL) and " +"return ``NULL``." +msgstr "" +"發生錯誤時，設定例外並將 *size* 設為 ``-1``\\ （如果不是 NULL），並回傳 " +"``NULL``。" + +#: ../../c-api/unicode.rst:1135 +msgid "" +"This caches the UTF-8 representation of the string in the Unicode object, " +"and subsequent calls will return a pointer to the same buffer. The caller " +"is not responsible for deallocating the buffer. The buffer is deallocated " +"and pointers to it become invalid when the Unicode object is garbage " +"collected." +msgstr "" + +#: ../../c-api/unicode.rst:1142 ../../c-api/unicode.rst:1164 +msgid "The return type is now ``const char *`` rather of ``char *``." +msgstr "回傳型別現在是 ``const char *`` 而不是 ``char *``。" + +#: ../../c-api/unicode.rst:1145 +msgid "This function is a part of the :ref:`limited API `." +msgstr "" + +#: ../../c-api/unicode.rst:1151 +msgid "As :c:func:`PyUnicode_AsUTF8AndSize`, but does not store the size." +msgstr "與 :c:func:`PyUnicode_AsUTF8AndSize` 類似，但不儲存大小。" + +#: ../../c-api/unicode.rst:1155 +msgid "" +"This function does not have any special behavior for `null characters " +"`_ embedded within *unicode*. " +"As a result, strings containing null characters will remain in the returned " +"string, which some C functions might interpret as the end of the string, " +"leading to truncation. If truncation is an issue, it is recommended to use :" +"c:func:`PyUnicode_AsUTF8AndSize` instead." +msgstr "" + +#: ../../c-api/unicode.rst:1169 +msgid "UTF-32 Codecs" +msgstr "UTF-32 編解碼器" + +#: ../../c-api/unicode.rst:1171 +msgid "These are the UTF-32 codec APIs:" +msgstr "這些是 UTF-32 編解碼器的 API：" + +#: ../../c-api/unicode.rst:1177 +msgid "" +"Decode *size* bytes from a UTF-32 encoded buffer string and return the " +"corresponding Unicode object. *errors* (if non-``NULL``) defines the error " +"handling. It defaults to \"strict\"." +msgstr "" + +#: ../../c-api/unicode.rst:1181 ../../c-api/unicode.rst:1231 +msgid "" +"If *byteorder* is non-``NULL``, the decoder starts decoding using the given " +"byte order::" +msgstr "" + +#: ../../c-api/unicode.rst:1184 ../../c-api/unicode.rst:1234 +msgid "" +"*byteorder == -1: little endian\n" +"*byteorder == 0: native order\n" +"*byteorder == 1: big endian" +msgstr "" + +#: ../../c-api/unicode.rst:1188 +msgid "" +"If ``*byteorder`` is zero, and the first four bytes of the input data are a " +"byte order mark (BOM), the decoder switches to this byte order and the BOM " +"is not copied into the resulting Unicode string. If ``*byteorder`` is " +"``-1`` or ``1``, any byte order mark is copied to the output." +msgstr "" + +#: ../../c-api/unicode.rst:1193 +msgid "" +"After completion, *\\*byteorder* is set to the current byte order at the end " +"of input data." +msgstr "" + +#: ../../c-api/unicode.rst:1196 ../../c-api/unicode.rst:1247 +msgid "If *byteorder* is ``NULL``, the codec starts in native order mode." +msgstr "" + +#: ../../c-api/unicode.rst:1198 ../../c-api/unicode.rst:1249 +msgid "Return ``NULL`` if an exception was raised by the codec." +msgstr "如果編解碼器引發例外則回傳 ``NULL``。" + +#: ../../c-api/unicode.rst:1204 +msgid "" +"If *consumed* is ``NULL``, behave like :c:func:`PyUnicode_DecodeUTF32`. If " +"*consumed* is not ``NULL``, :c:func:`PyUnicode_DecodeUTF32Stateful` will not " +"treat trailing incomplete UTF-32 byte sequences (such as a number of bytes " +"not divisible by four) as an error. Those bytes will not be decoded and the " +"number of bytes that have been decoded will be stored in *consumed*." +msgstr "" + +#: ../../c-api/unicode.rst:1213 +msgid "" +"Return a Python byte string using the UTF-32 encoding in native byte order. " +"The string always starts with a BOM mark. Error handling is \"strict\". " +"Return ``NULL`` if an exception was raised by the codec." +msgstr "" + +#: ../../c-api/unicode.rst:1219 +msgid "UTF-16 Codecs" +msgstr "UTF-16 編解碼器" + +#: ../../c-api/unicode.rst:1221 +msgid "These are the UTF-16 codec APIs:" +msgstr "這些是 UTF-16 編解碼器的 API：" + +#: ../../c-api/unicode.rst:1227 +msgid "" +"Decode *size* bytes from a UTF-16 encoded buffer string and return the " +"corresponding Unicode object. *errors* (if non-``NULL``) defines the error " +"handling. It defaults to \"strict\"." +msgstr "" + +#: ../../c-api/unicode.rst:1238 +msgid "" +"If ``*byteorder`` is zero, and the first two bytes of the input data are a " +"byte order mark (BOM), the decoder switches to this byte order and the BOM " +"is not copied into the resulting Unicode string. If ``*byteorder`` is " +"``-1`` or ``1``, any byte order mark is copied to the output (where it will " +"result in either a ``\\ufeff`` or a ``\\ufffe`` character)." +msgstr "" + +#: ../../c-api/unicode.rst:1244 +msgid "" +"After completion, ``*byteorder`` is set to the current byte order at the end " +"of input data." +msgstr "" + +#: ../../c-api/unicode.rst:1255 +msgid "" +"If *consumed* is ``NULL``, behave like :c:func:`PyUnicode_DecodeUTF16`. If " +"*consumed* is not ``NULL``, :c:func:`PyUnicode_DecodeUTF16Stateful` will not " +"treat trailing incomplete UTF-16 byte sequences (such as an odd number of " +"bytes or a split surrogate pair) as an error. Those bytes will not be " +"decoded and the number of bytes that have been decoded will be stored in " +"*consumed*." +msgstr "" + +#: ../../c-api/unicode.rst:1264 +msgid "" +"Return a Python byte string using the UTF-16 encoding in native byte order. " +"The string always starts with a BOM mark. Error handling is \"strict\". " +"Return ``NULL`` if an exception was raised by the codec." +msgstr "" + +#: ../../c-api/unicode.rst:1270 +msgid "UTF-7 Codecs" +msgstr "UTF-7 編解碼器" + +#: ../../c-api/unicode.rst:1272 +msgid "These are the UTF-7 codec APIs:" +msgstr "這些是 UTF-7 編解碼器的 API：" + +#: ../../c-api/unicode.rst:1277 +msgid "" +"Create a Unicode object by decoding *size* bytes of the UTF-7 encoded string " +"*str*. Return ``NULL`` if an exception was raised by the codec." +msgstr "" + +#: ../../c-api/unicode.rst:1284 +msgid "" +"If *consumed* is ``NULL``, behave like :c:func:`PyUnicode_DecodeUTF7`. If " +"*consumed* is not ``NULL``, trailing incomplete UTF-7 base-64 sections will " +"not be treated as an error. Those bytes will not be decoded and the number " +"of bytes that have been decoded will be stored in *consumed*." +msgstr "" + +#: ../../c-api/unicode.rst:1291 +msgid "Unicode-Escape Codecs" +msgstr "" + +#: ../../c-api/unicode.rst:1293 +msgid "These are the \"Unicode Escape\" codec APIs:" +msgstr "" + +#: ../../c-api/unicode.rst:1299 +msgid "" +"Create a Unicode object by decoding *size* bytes of the Unicode-Escape " +"encoded string *str*. Return ``NULL`` if an exception was raised by the " +"codec." +msgstr "" + +#: ../../c-api/unicode.rst:1305 +msgid "" +"Encode a Unicode object using Unicode-Escape and return the result as a " +"bytes object. Error handling is \"strict\". Return ``NULL`` if an " +"exception was raised by the codec." +msgstr "" + +#: ../../c-api/unicode.rst:1311 +msgid "Raw-Unicode-Escape Codecs" +msgstr "" + +#: ../../c-api/unicode.rst:1313 +msgid "These are the \"Raw Unicode Escape\" codec APIs:" +msgstr "" + +#: ../../c-api/unicode.rst:1319 +msgid "" +"Create a Unicode object by decoding *size* bytes of the Raw-Unicode-Escape " +"encoded string *str*. Return ``NULL`` if an exception was raised by the " +"codec." +msgstr "" + +#: ../../c-api/unicode.rst:1325 +msgid "" +"Encode a Unicode object using Raw-Unicode-Escape and return the result as a " +"bytes object. Error handling is \"strict\". Return ``NULL`` if an " +"exception was raised by the codec." +msgstr "" + +#: ../../c-api/unicode.rst:1331 +msgid "Latin-1 Codecs" +msgstr "Latin-1 編解碼器" + +#: ../../c-api/unicode.rst:1333 +msgid "" +"These are the Latin-1 codec APIs: Latin-1 corresponds to the first 256 " +"Unicode ordinals and only these are accepted by the codecs during encoding." +msgstr "" + +#: ../../c-api/unicode.rst:1339 +msgid "" +"Create a Unicode object by decoding *size* bytes of the Latin-1 encoded " +"string *str*. Return ``NULL`` if an exception was raised by the codec." +msgstr "" + +#: ../../c-api/unicode.rst:1345 +msgid "" +"Encode a Unicode object using Latin-1 and return the result as Python bytes " +"object. Error handling is \"strict\". Return ``NULL`` if an exception was " +"raised by the codec." +msgstr "" + +#: ../../c-api/unicode.rst:1351 +msgid "ASCII Codecs" +msgstr "ASCII 編解碼器" + +#: ../../c-api/unicode.rst:1353 +msgid "" +"These are the ASCII codec APIs. Only 7-bit ASCII data is accepted. All " +"other codes generate errors." +msgstr "" + +#: ../../c-api/unicode.rst:1359 +msgid "" +"Create a Unicode object by decoding *size* bytes of the ASCII encoded string " +"*str*. Return ``NULL`` if an exception was raised by the codec." +msgstr "" + +#: ../../c-api/unicode.rst:1365 +msgid "" +"Encode a Unicode object using ASCII and return the result as Python bytes " +"object. Error handling is \"strict\". Return ``NULL`` if an exception was " +"raised by the codec." +msgstr "" + +#: ../../c-api/unicode.rst:1371 +msgid "Character Map Codecs" +msgstr "" + +#: ../../c-api/unicode.rst:1373 +msgid "" +"This codec is special in that it can be used to implement many different " +"codecs (and this is in fact what was done to obtain most of the standard " +"codecs included in the :mod:`!encodings` package). The codec uses mappings " +"to encode and decode characters. The mapping objects provided must support " +"the :meth:`~object.__getitem__` mapping interface; dictionaries and " +"sequences work well." +msgstr "" + +#: ../../c-api/unicode.rst:1379 +msgid "These are the mapping codec APIs:" +msgstr "這些是對映編解碼器的 API：" + +#: ../../c-api/unicode.rst:1384 +msgid "" +"Create a Unicode object by decoding *size* bytes of the encoded string *str* " +"using the given *mapping* object. Return ``NULL`` if an exception was " +"raised by the codec." +msgstr "" + +#: ../../c-api/unicode.rst:1388 +msgid "" +"If *mapping* is ``NULL``, Latin-1 decoding will be applied. Else *mapping* " +"must map bytes ordinals (integers in the range from 0 to 255) to Unicode " +"strings, integers (which are then interpreted as Unicode ordinals) or " +"``None``. Unmapped data bytes -- ones which cause a :exc:`LookupError`, as " +"well as ones which get mapped to ``None``, ``0xFFFE`` or ``'\\ufffe'``, are " +"treated as undefined mappings and cause an error." +msgstr "" + +#: ../../c-api/unicode.rst:1399 +msgid "" +"Encode a Unicode object using the given *mapping* object and return the " +"result as a bytes object. Error handling is \"strict\". Return ``NULL`` if " +"an exception was raised by the codec." +msgstr "" + +#: ../../c-api/unicode.rst:1403 +msgid "" +"The *mapping* object must map Unicode ordinal integers to bytes objects, " +"integers in the range from 0 to 255 or ``None``. Unmapped character " +"ordinals (ones which cause a :exc:`LookupError`) as well as mapped to " +"``None`` are treated as \"undefined mapping\" and cause an error." +msgstr "" + +#: ../../c-api/unicode.rst:1409 +msgid "The following codec API is special in that maps Unicode to Unicode." +msgstr "" + +#: ../../c-api/unicode.rst:1413 +msgid "" +"Translate a string by applying a character mapping table to it and return " +"the resulting Unicode object. Return ``NULL`` if an exception was raised by " +"the codec." +msgstr "" + +#: ../../c-api/unicode.rst:1417 +msgid "" +"The mapping table must map Unicode ordinal integers to Unicode ordinal " +"integers or ``None`` (causing deletion of the character)." +msgstr "" + +#: ../../c-api/unicode.rst:1420 +msgid "" +"Mapping tables need only provide the :meth:`~object.__getitem__` interface; " +"dictionaries and sequences work well. Unmapped character ordinals (ones " +"which cause a :exc:`LookupError`) are left untouched and are copied as-is." +msgstr "" + +#: ../../c-api/unicode.rst:1424 +msgid "" +"*errors* has the usual meaning for codecs. It may be ``NULL`` which " +"indicates to use the default error handling." +msgstr "" + +#: ../../c-api/unicode.rst:1429 +msgid "MBCS codecs for Windows" +msgstr "Windows 的 MBCS 編解碼器" + +#: ../../c-api/unicode.rst:1431 +msgid "" +"These are the MBCS codec APIs. They are currently only available on Windows " +"and use the Win32 MBCS converters to implement the conversions. Note that " +"MBCS (or DBCS) is a class of encodings, not just one. The target encoding " +"is defined by the user settings on the machine running the codec." +msgstr "" + +#: ../../c-api/unicode.rst:1438 +msgid "" +"Create a Unicode object by decoding *size* bytes of the MBCS encoded string " +"*str*. Return ``NULL`` if an exception was raised by the codec." +msgstr "" + +#: ../../c-api/unicode.rst:1445 +msgid "" +"If *consumed* is ``NULL``, behave like :c:func:`PyUnicode_DecodeMBCS`. If " +"*consumed* is not ``NULL``, :c:func:`PyUnicode_DecodeMBCSStateful` will not " +"decode trailing lead byte and the number of bytes that have been decoded " +"will be stored in *consumed*." +msgstr "" + +#: ../../c-api/unicode.rst:1454 +msgid "" +"Similar to :c:func:`PyUnicode_DecodeMBCSStateful`, except uses the code page " +"specified by *code_page*." +msgstr "" + +#: ../../c-api/unicode.rst:1460 +msgid "" +"Encode a Unicode object using MBCS and return the result as Python bytes " +"object. Error handling is \"strict\". Return ``NULL`` if an exception was " +"raised by the codec." +msgstr "" + +#: ../../c-api/unicode.rst:1467 +msgid "" +"Encode the Unicode object using the specified code page and return a Python " +"bytes object. Return ``NULL`` if an exception was raised by the codec. Use :" +"c:macro:`!CP_ACP` code page to get the MBCS encoder." +msgstr "" + +#: ../../c-api/unicode.rst:1477 +msgid "Methods and Slot Functions" +msgstr "" + +#: ../../c-api/unicode.rst:1479 +msgid "" +"The following APIs are capable of handling Unicode objects and strings on " +"input (we refer to them as strings in the descriptions) and return Unicode " +"objects or integers as appropriate." +msgstr "" + +#: ../../c-api/unicode.rst:1483 +msgid "They all return ``NULL`` or ``-1`` if an exception occurs." +msgstr "如果發生例外，則回傳 ``NULL`` 或 ``-1``。" + +#: ../../c-api/unicode.rst:1488 +msgid "Concat two strings giving a new Unicode string." +msgstr "" + +#: ../../c-api/unicode.rst:1493 +msgid "" +"Split a string giving a list of Unicode strings. If *sep* is ``NULL``, " +"splitting will be done at all whitespace substrings. Otherwise, splits " +"occur at the given separator. At most *maxsplit* splits will be done. If " +"negative, no limit is set. Separators are not included in the resulting " +"list." +msgstr "" + +#: ../../c-api/unicode.rst:1498 ../../c-api/unicode.rst:1508 +#: ../../c-api/unicode.rst:1529 ../../c-api/unicode.rst:1542 +msgid "On error, return ``NULL`` with an exception set." +msgstr "於錯誤發生時回傳 ``NULL`` 並設定例外。" + +#: ../../c-api/unicode.rst:1500 +msgid "Equivalent to :py:meth:`str.split`." +msgstr "等價於 :py:meth:`str.split`。" + +#: ../../c-api/unicode.rst:1505 +msgid "" +"Similar to :c:func:`PyUnicode_Split`, but splitting will be done beginning " +"at the end of the string." +msgstr "" + +#: ../../c-api/unicode.rst:1510 +msgid "Equivalent to :py:meth:`str.rsplit`." +msgstr "等價於 :py:meth:`str.rsplit`。" + +#: ../../c-api/unicode.rst:1515 +msgid "" +"Split a Unicode string at line breaks, returning a list of Unicode strings. " +"CRLF is considered to be one line break. If *keepends* is ``0``, the Line " +"break characters are not included in the resulting strings." +msgstr "" + +#: ../../c-api/unicode.rst:1522 +msgid "" +"Split a Unicode string at the first occurrence of *sep*, and return a 3-" +"tuple containing the part before the separator, the separator itself, and " +"the part after the separator. If the separator is not found, return a 3-" +"tuple containing the string itself, followed by two empty strings." +msgstr "" + +#: ../../c-api/unicode.rst:1527 ../../c-api/unicode.rst:1540 +msgid "*sep* must not be empty." +msgstr "*sep* 不得為空。" + +#: ../../c-api/unicode.rst:1531 +msgid "Equivalent to :py:meth:`str.partition`." +msgstr "等價於 :py:meth:`str.partition`。" + +#: ../../c-api/unicode.rst:1536 +msgid "" +"Similar to :c:func:`PyUnicode_Partition`, but split a Unicode string at the " +"last occurrence of *sep*. If the separator is not found, return a 3-tuple " +"containing two empty strings, followed by the string itself." +msgstr "" + +#: ../../c-api/unicode.rst:1544 +msgid "Equivalent to :py:meth:`str.rpartition`." +msgstr "等價於 :py:meth:`str.rpartition`。" + +#: ../../c-api/unicode.rst:1549 +msgid "" +"Join a sequence of strings using the given *separator* and return the " +"resulting Unicode string." +msgstr "" + +#: ../../c-api/unicode.rst:1556 +msgid "" +"Return ``1`` if *substr* matches ``unicode[start:end]`` at the given tail " +"end (*direction* == ``-1`` means to do a prefix match, *direction* == ``1`` " +"a suffix match), ``0`` otherwise. Return ``-1`` if an error occurred." +msgstr "" + +#: ../../c-api/unicode.rst:1564 +msgid "" +"Return the first position of *substr* in ``unicode[start:end]`` using the " +"given *direction* (*direction* == ``1`` means to do a forward search, " +"*direction* == ``-1`` a backward search). The return value is the index of " +"the first match; a value of ``-1`` indicates that no match was found, and " +"``-2`` indicates that an error occurred and an exception has been set." +msgstr "" + +#: ../../c-api/unicode.rst:1574 +msgid "" +"Return the first position of the character *ch* in ``unicode[start:end]`` " +"using the given *direction* (*direction* == ``1`` means to do a forward " +"search, *direction* == ``-1`` a backward search). The return value is the " +"index of the first match; a value of ``-1`` indicates that no match was " +"found, and ``-2`` indicates that an error occurred and an exception has been " +"set." +msgstr "" + +#: ../../c-api/unicode.rst:1582 +msgid "" +"*start* and *end* are now adjusted to behave like ``unicode[start:end]``." +msgstr "" + +#: ../../c-api/unicode.rst:1589 +msgid "" +"Return the number of non-overlapping occurrences of *substr* in " +"``unicode[start:end]``. Return ``-1`` if an error occurred." +msgstr "" + +#: ../../c-api/unicode.rst:1596 +msgid "" +"Replace at most *maxcount* occurrences of *substr* in *unicode* with " +"*replstr* and return the resulting Unicode object. *maxcount* == ``-1`` " +"means replace all occurrences." +msgstr "" + +#: ../../c-api/unicode.rst:1603 +msgid "" +"Compare two strings and return ``-1``, ``0``, ``1`` for less than, equal, " +"and greater than, respectively." +msgstr "" + +#: ../../c-api/unicode.rst:1606 +msgid "" +"This function returns ``-1`` upon failure, so one should call :c:func:" +"`PyErr_Occurred` to check for errors." +msgstr "" + +#: ../../c-api/unicode.rst:1611 +msgid "The :c:func:`PyUnicode_Equal` function." +msgstr ":c:func:`PyUnicode_Equal` 函式。" + +#: ../../c-api/unicode.rst:1616 +msgid "Test if two strings are equal:" +msgstr "測試兩個字串是否相等：" + +#: ../../c-api/unicode.rst:1618 +msgid "Return ``1`` if *a* is equal to *b*." +msgstr "如果 *a* 等於 *b*，則回傳 ``1``。" + +#: ../../c-api/unicode.rst:1619 +msgid "Return ``0`` if *a* is not equal to *b*." +msgstr "如果 *a* 不等於 *b*，則回傳 ``0``。" + +#: ../../c-api/unicode.rst:1620 +msgid "" +"Set a :exc:`TypeError` exception and return ``-1`` if *a* or *b* is not a :" +"class:`str` object." +msgstr "" + +#: ../../c-api/unicode.rst:1623 +msgid "The function always succeeds if *a* and *b* are :class:`str` objects." +msgstr "" + +#: ../../c-api/unicode.rst:1625 +msgid "" +"The function works for :class:`str` subclasses, but does not honor custom " +"``__eq__()`` method." +msgstr "" + +#: ../../c-api/unicode.rst:1630 +msgid "The :c:func:`PyUnicode_Compare` function." +msgstr ":c:func:`PyUnicode_Compare` 函式。" + +#: ../../c-api/unicode.rst:1637 +msgid "" +"Compare a Unicode object with a char buffer which is interpreted as being " +"UTF-8 or ASCII encoded and return true (``1``) if they are equal, or false " +"(``0``) otherwise. If the Unicode object contains surrogate code points " +"(``U+D800`` - ``U+DFFF``) or the C string is not valid UTF-8, false (``0``) " +"is returned." +msgstr "" + +#: ../../c-api/unicode.rst:1644 ../../c-api/unicode.rst:1665 +msgid "This function does not raise exceptions." +msgstr "此函式不會引發例外。" + +#: ../../c-api/unicode.rst:1651 +msgid "" +"Similar to :c:func:`PyUnicode_EqualToUTF8AndSize`, but compute *string* " +"length using :c:func:`!strlen`. If the Unicode object contains null " +"characters, false (``0``) is returned." +msgstr "" + +#: ../../c-api/unicode.rst:1660 +msgid "" +"Compare a Unicode object, *unicode*, with *string* and return ``-1``, ``0``, " +"``1`` for less than, equal, and greater than, respectively. It is best to " +"pass only ASCII-encoded strings, but the function interprets the input " +"string as ISO-8859-1 if it contains non-ASCII characters." +msgstr "" + +#: ../../c-api/unicode.rst:1670 +msgid "Rich compare two Unicode strings and return one of the following:" +msgstr "" + +#: ../../c-api/unicode.rst:1672 +msgid "``NULL`` in case an exception was raised" +msgstr "" + +#: ../../c-api/unicode.rst:1673 +msgid ":c:data:`Py_True` or :c:data:`Py_False` for successful comparisons" +msgstr "" + +#: ../../c-api/unicode.rst:1674 +msgid ":c:data:`Py_NotImplemented` in case the type combination is unknown" +msgstr "" + +#: ../../c-api/unicode.rst:1676 +msgid "" +"Possible values for *op* are :c:macro:`Py_GT`, :c:macro:`Py_GE`, :c:macro:" +"`Py_EQ`, :c:macro:`Py_NE`, :c:macro:`Py_LT`, and :c:macro:`Py_LE`." +msgstr "" + +#: ../../c-api/unicode.rst:1682 +msgid "" +"Return a new string object from *format* and *args*; this is analogous to " +"``format % args``." +msgstr "" + +#: ../../c-api/unicode.rst:1688 +msgid "" +"Check whether *substr* is contained in *unicode* and return true or false " +"accordingly." +msgstr "" + +#: ../../c-api/unicode.rst:1691 +msgid "" +"*substr* has to coerce to a one element Unicode string. ``-1`` is returned " +"if there was an error." +msgstr "" + +#: ../../c-api/unicode.rst:1697 +msgid "" +"Intern the argument :c:expr:`*p_unicode` in place. The argument must be the " +"address of a pointer variable pointing to a Python Unicode string object. " +"If there is an existing interned string that is the same as :c:expr:" +"`*p_unicode`, it sets :c:expr:`*p_unicode` to it (releasing the reference to " +"the old string object and creating a new :term:`strong reference` to the " +"interned string object), otherwise it leaves :c:expr:`*p_unicode` alone and " +"interns it." +msgstr "" + +#: ../../c-api/unicode.rst:1704 +msgid "" +"(Clarification: even though there is a lot of talk about references, think " +"of this function as reference-neutral. You must own the object you pass in; " +"after the call you no longer own the passed-in reference, but you newly own " +"the result.)" +msgstr "" + +#: ../../c-api/unicode.rst:1709 +msgid "" +"This function never raises an exception. On error, it leaves its argument " +"unchanged without interning it." +msgstr "" + +#: ../../c-api/unicode.rst:1712 +msgid "" +"Instances of subclasses of :py:class:`str` may not be interned, that is, :c:" +"expr:`PyUnicode_CheckExact(*p_unicode)` must be true. If it is not, then -- " +"as with any other error -- the argument is left unchanged." +msgstr "" + +#: ../../c-api/unicode.rst:1716 +msgid "" +"Note that interned strings are not “immortal”. You must keep a reference to " +"the result to benefit from interning." +msgstr "" + +#: ../../c-api/unicode.rst:1722 +msgid "" +"A combination of :c:func:`PyUnicode_FromString` and :c:func:" +"`PyUnicode_InternInPlace`, meant for statically allocated strings." +msgstr "" + +#: ../../c-api/unicode.rst:1725 +msgid "" +"Return a new (\"owned\") reference to either a new Unicode string object " +"that has been interned, or an earlier interned string object with the same " +"value." +msgstr "" + +#: ../../c-api/unicode.rst:1729 +msgid "" +"Python may keep a reference to the result, or make it :term:`immortal`, " +"preventing it from being garbage-collected promptly. For interning an " +"unbounded number of different strings, such as ones coming from user input, " +"prefer calling :c:func:`PyUnicode_FromString` and :c:func:" +"`PyUnicode_InternInPlace` directly." +msgstr "" + +#: ../../c-api/unicode.rst:1738 +msgid "" +"Return a non-zero value if *str* is interned, zero if not. The *str* " +"argument must be a string; this is not checked. This function always " +"succeeds." +msgstr "" + +#: ../../c-api/unicode.rst:1744 +msgid "" +"A non-zero return value may carry additional information about *how* the " +"string is interned. The meaning of such non-zero values, as well as each " +"specific string's intern-related details, may change between CPython " +"versions." +msgstr "" + +#: ../../c-api/unicode.rst:1751 +msgid "PyUnicodeWriter" +msgstr "PyUnicodeWriter" + +#: ../../c-api/unicode.rst:1753 +msgid "" +"The :c:type:`PyUnicodeWriter` API can be used to create a Python :class:" +"`str` object." +msgstr "" + +#: ../../c-api/unicode.rst:1760 +msgid "A Unicode writer instance." +msgstr "一個 Unicode 寫入器實例。" + +#: ../../c-api/unicode.rst:1762 +msgid "" +"The instance must be destroyed by :c:func:`PyUnicodeWriter_Finish` on " +"success, or :c:func:`PyUnicodeWriter_Discard` on error." +msgstr "" + +#: ../../c-api/unicode.rst:1767 +msgid "Create a Unicode writer instance." +msgstr "" + +#: ../../c-api/unicode.rst:1769 +msgid "*length* must be greater than or equal to ``0``." +msgstr "" + +#: ../../c-api/unicode.rst:1771 +msgid "" +"If *length* is greater than ``0``, preallocate an internal buffer of " +"*length* characters." +msgstr "" + +#: ../../c-api/unicode.rst:1774 ../../c-api/unicode.rst:1780 +msgid "Set an exception and return ``NULL`` on error." +msgstr "發生錯誤時，設定例外並回傳 ``NULL``。" + +#: ../../c-api/unicode.rst:1778 +msgid "" +"Return the final Python :class:`str` object and destroy the writer instance." +msgstr "" + +#: ../../c-api/unicode.rst:1782 ../../c-api/unicode.rst:1790 +msgid "The writer instance is invalid after this call." +msgstr "" + +#: ../../c-api/unicode.rst:1786 +msgid "Discard the internal Unicode buffer and destroy the writer instance." +msgstr "" + +#: ../../c-api/unicode.rst:1788 +msgid "If *writer* is ``NULL``, no operation is performed." +msgstr "" + +#: ../../c-api/unicode.rst:1794 +msgid "Write the single Unicode character *ch* into *writer*." +msgstr "" + +#: ../../c-api/unicode.rst:1796 ../../c-api/unicode.rst:1806 +#: ../../c-api/unicode.rst:1821 ../../c-api/unicode.rst:1833 +#: ../../c-api/unicode.rst:1842 ../../c-api/unicode.rst:1849 +#: ../../c-api/unicode.rst:1856 ../../c-api/unicode.rst:1867 +#: ../../c-api/unicode.rst:1874 ../../c-api/unicode.rst:1893 +msgid "" +"On success, return ``0``. On error, set an exception, leave the writer " +"unchanged, and return ``-1``." +msgstr "成功時回傳 ``0``，發生錯誤時設定例外、保持寫入器不變，並回傳 ``-1``。" + +#: ../../c-api/unicode.rst:1801 +msgid "" +"Decode the string *str* from UTF-8 in strict mode and write the output into " +"*writer*." +msgstr "" + +#: ../../c-api/unicode.rst:1803 ../../c-api/unicode.rst:1815 +#: ../../c-api/unicode.rst:1882 +msgid "" +"*size* is the string length in bytes. If *size* is equal to ``-1``, call " +"``strlen(str)`` to get the string length." +msgstr "" + +#: ../../c-api/unicode.rst:1809 +msgid "See also :c:func:`PyUnicodeWriter_DecodeUTF8Stateful`." +msgstr "另請參閱 :c:func:`PyUnicodeWriter_DecodeUTF8Stateful`。" + +#: ../../c-api/unicode.rst:1813 +msgid "Write the ASCII string *str* into *writer*." +msgstr "" + +#: ../../c-api/unicode.rst:1818 +msgid "" +"*str* must only contain ASCII characters. The behavior is undefined if *str* " +"contains non-ASCII characters." +msgstr "" + +#: ../../c-api/unicode.rst:1828 +msgid "Write the wide string *str* into *writer*." +msgstr "" + +#: ../../c-api/unicode.rst:1830 +msgid "" +"*size* is a number of wide characters. If *size* is equal to ``-1``, call " +"``wcslen(str)`` to get the string length." +msgstr "" + +#: ../../c-api/unicode.rst:1838 +msgid "Writer the UCS4 string *str* into *writer*." +msgstr "" + +#: ../../c-api/unicode.rst:1840 +msgid "*size* is a number of UCS4 characters." +msgstr "" + +#: ../../c-api/unicode.rst:1847 +msgid "" +"Call :c:func:`PyObject_Str` on *obj* and write the output into *writer*." +msgstr "" + +#: ../../c-api/unicode.rst:1854 +msgid "" +"Call :c:func:`PyObject_Repr` on *obj* and write the output into *writer*." +msgstr "" + +#: ../../c-api/unicode.rst:1861 +msgid "Write the substring ``str[start:end]`` into *writer*." +msgstr "" + +#: ../../c-api/unicode.rst:1863 +msgid "" +"*str* must be Python :class:`str` object. *start* must be greater than or " +"equal to 0, and less than or equal to *end*. *end* must be less than or " +"equal to *str* length." +msgstr "" + +#: ../../c-api/unicode.rst:1872 +msgid "" +"Similar to :c:func:`PyUnicode_FromFormat`, but write the output directly " +"into *writer*." +msgstr "類似於 :c:func:`PyUnicode_FromFormat`，但是直接將輸出寫入 *writer*。" + +#: ../../c-api/unicode.rst:1879 +msgid "" +"Decode the string *str* from UTF-8 with *errors* error handler and write the " +"output into *writer*." +msgstr "" + +#: ../../c-api/unicode.rst:1885 +msgid "" +"*errors* is an :ref:`error handler ` name, such as " +"``\"replace\"``. If *errors* is ``NULL``, use the strict error handler." +msgstr "" + +#: ../../c-api/unicode.rst:1888 +msgid "" +"If *consumed* is not ``NULL``, set *\\*consumed* to the number of decoded " +"bytes on success. If *consumed* is ``NULL``, treat trailing incomplete UTF-8 " +"byte sequences as an error." +msgstr "" + +#: ../../c-api/unicode.rst:1896 +msgid "See also :c:func:`PyUnicodeWriter_WriteUTF8`." +msgstr "另請參閱 :c:func:`PyUnicodeWriter_WriteUTF8`。" + +#: ../../c-api/unicode.rst:1899 +msgid "Deprecated API" +msgstr "已棄用的 API" + +#: ../../c-api/unicode.rst:1901 +msgid "The following API is deprecated." +msgstr "以下 API 已棄用。" + +#: ../../c-api/unicode.rst:1905 +msgid "" +"This is a typedef of :c:type:`wchar_t`, which is a 16-bit type or 32-bit " +"type depending on the platform. Please use :c:type:`wchar_t` directly " +"instead." +msgstr "" + +#: ../../c-api/unicode.rst:1909 +msgid "" +"In previous versions, this was a 16-bit type or a 32-bit type depending on " +"whether you selected a \"narrow\" or \"wide\" Unicode version of Python at " +"build time." +msgstr "" + +#: ../../c-api/unicode.rst:1919 +msgid "" +"Do nothing and return ``0``. This API is kept only for backward " +"compatibility, but there are no plans to remove it." +msgstr "" + +#: ../../c-api/unicode.rst:1925 +msgid "" +"This API does nothing since Python 3.12. Previously, this needed to be " +"called for each string created using the old API (:c:func:`!" +"PyUnicode_FromUnicode` or similar)." +msgstr "" + +#: ../../c-api/unicode.rst:1933 +msgid "" +"Do nothing and return ``1``. This API is kept only for backward " +"compatibility, but there are no plans to remove it." +msgstr "" + +#: ../../c-api/unicode.rst:1939 +msgid "" +"This API does nothing since Python 3.12. Previously, this could be called to " +"check if :c:func:`PyUnicode_READY` is necessary." +msgstr "" diff --git a/c-api/utilities.po b/c-api/utilities.po index 4510d3cca3..a8cfaca0a6 100644 --- a/c-api/utilities.po +++ b/c-api/utilities.po @@ -1,37 +1,37 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Leon H., 2017 -# Matt Wang , 2021 -# Phil Lin , 2022 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2018-06-26 18:54+0800\n" -"PO-Revision-Date: 2022-01-31 17:38+0800\n" -"Last-Translator: Phil Lin \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" -"X-Generator: Poedit 3.0.1\n" - -#: ../../c-api/utilities.rst:7 -msgid "Utilities" -msgstr "工具" - -#: ../../c-api/utilities.rst:9 -msgid "" -"The functions in this chapter perform various utility tasks, ranging from " -"helping C code be more portable across platforms, using Python modules from " -"C, and parsing function arguments and constructing Python values from C " -"values." -msgstr "" -"本章中的函式可用來執行各種工具任務，包括幫助 C 程式碼提升跨平臺可攜性 " -"(portable)、在 C 中使用 Python module（模組）、以及剖析函式引數並基於 C 中的" -"值來構建 Python 中的值等。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Leon H., 2017 +# Matt Wang , 2021 +# Phil Lin , 2022 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2018-06-26 18:54+0800\n" +"PO-Revision-Date: 2022-01-31 17:38+0800\n" +"Last-Translator: Phil Lin \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" +"X-Generator: Poedit 3.0.1\n" + +#: ../../c-api/utilities.rst:7 +msgid "Utilities" +msgstr "工具" + +#: ../../c-api/utilities.rst:9 +msgid "" +"The functions in this chapter perform various utility tasks, ranging from " +"helping C code be more portable across platforms, using Python modules from " +"C, and parsing function arguments and constructing Python values from C " +"values." +msgstr "" +"本章中的函式可用來執行各種工具任務，包括幫助 C 程式碼提升跨平臺可攜性 " +"(portable)、在 C 中使用 Python module（模組）、以及剖析函式引數並基於 C 中的" +"值來構建 Python 中的值等。" diff --git a/c-api/veryhigh.po b/c-api/veryhigh.po index 0663dd4fc7..95c9af846f 100644 --- a/c-api/veryhigh.po +++ b/c-api/veryhigh.po @@ -1,482 +1,482 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-25 00:13+0000\n" -"PO-Revision-Date: 2018-05-23 14:08+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" - -#: ../../c-api/veryhigh.rst:8 -msgid "The Very High Level Layer" -msgstr "" - -#: ../../c-api/veryhigh.rst:10 -msgid "" -"The functions in this chapter will let you execute Python source code given " -"in a file or a buffer, but they will not let you interact in a more detailed " -"way with the interpreter." -msgstr "" - -#: ../../c-api/veryhigh.rst:14 -msgid "" -"Several of these functions accept a start symbol from the grammar as a " -"parameter. The available start symbols are :c:data:`Py_eval_input`, :c:data:" -"`Py_file_input`, :c:data:`Py_single_input`, and :c:data:" -"`Py_func_type_input`. These are described following the functions which " -"accept them as parameters." -msgstr "" - -#: ../../c-api/veryhigh.rst:20 -msgid "" -"Note also that several of these functions take :c:expr:`FILE*` parameters. " -"One particular issue which needs to be handled carefully is that the :c:type:" -"`FILE` structure for different C libraries can be different and " -"incompatible. Under Windows (at least), it is possible for dynamically " -"linked extensions to actually use different libraries, so care should be " -"taken that :c:expr:`FILE*` parameters are only passed to these functions if " -"it is certain that they were created by the same library that the Python " -"runtime is using." -msgstr "" - -#: ../../c-api/veryhigh.rst:31 -msgid "" -"This is a simplified interface to :c:func:`PyRun_AnyFileExFlags` below, " -"leaving *closeit* set to ``0`` and *flags* set to ``NULL``." -msgstr "" - -#: ../../c-api/veryhigh.rst:37 -msgid "" -"This is a simplified interface to :c:func:`PyRun_AnyFileExFlags` below, " -"leaving the *closeit* argument set to ``0``." -msgstr "" - -#: ../../c-api/veryhigh.rst:43 -msgid "" -"This is a simplified interface to :c:func:`PyRun_AnyFileExFlags` below, " -"leaving the *flags* argument set to ``NULL``." -msgstr "" - -#: ../../c-api/veryhigh.rst:49 -msgid "" -"If *fp* refers to a file associated with an interactive device (console or " -"terminal input or Unix pseudo-terminal), return the value of :c:func:" -"`PyRun_InteractiveLoop`, otherwise return the result of :c:func:" -"`PyRun_SimpleFile`. *filename* is decoded from the filesystem encoding (:" -"func:`sys.getfilesystemencoding`). If *filename* is ``NULL``, this function " -"uses ``\"???\"`` as the filename. If *closeit* is true, the file is closed " -"before ``PyRun_SimpleFileExFlags()`` returns." -msgstr "" - -#: ../../c-api/veryhigh.rst:61 -msgid "" -"This is a simplified interface to :c:func:`PyRun_SimpleStringFlags` below, " -"leaving the :c:struct:`PyCompilerFlags`\\* argument set to ``NULL``." -msgstr "" - -#: ../../c-api/veryhigh.rst:67 -msgid "" -"Executes the Python source code from *command* in the :mod:`__main__` module " -"according to the *flags* argument. If :mod:`__main__` does not already " -"exist, it is created. Returns ``0`` on success or ``-1`` if an exception " -"was raised. If there was an error, there is no way to get the exception " -"information. For the meaning of *flags*, see below." -msgstr "" - -#: ../../c-api/veryhigh.rst:73 -msgid "" -"Note that if an otherwise unhandled :exc:`SystemExit` is raised, this " -"function will not return ``-1``, but exit the process, as long as :c:member:" -"`PyConfig.inspect` is zero." -msgstr "" - -#: ../../c-api/veryhigh.rst:80 -msgid "" -"This is a simplified interface to :c:func:`PyRun_SimpleFileExFlags` below, " -"leaving *closeit* set to ``0`` and *flags* set to ``NULL``." -msgstr "" - -#: ../../c-api/veryhigh.rst:86 -msgid "" -"This is a simplified interface to :c:func:`PyRun_SimpleFileExFlags` below, " -"leaving *flags* set to ``NULL``." -msgstr "" - -#: ../../c-api/veryhigh.rst:92 -msgid "" -"Similar to :c:func:`PyRun_SimpleStringFlags`, but the Python source code is " -"read from *fp* instead of an in-memory string. *filename* should be the name " -"of the file, it is decoded from :term:`filesystem encoding and error " -"handler`. If *closeit* is true, the file is closed before " -"``PyRun_SimpleFileExFlags()`` returns." -msgstr "" - -#: ../../c-api/veryhigh.rst:99 -msgid "" -"On Windows, *fp* should be opened as binary mode (e.g. ``fopen(filename, " -"\"rb\")``). Otherwise, Python may not handle script file with LF line ending " -"correctly." -msgstr "" - -#: ../../c-api/veryhigh.rst:105 -msgid "" -"Read and execute a single statement from a file associated with an " -"interactive device according to the *flags* argument. The user will be " -"prompted using ``sys.ps1`` and ``sys.ps2``. *filename* must be a Python :" -"class:`str` object." -msgstr "" - -#: ../../c-api/veryhigh.rst:110 -msgid "" -"Returns ``0`` when the input was executed successfully, ``-1`` if there was " -"an exception, or an error code from the :file:`errcode.h` include file " -"distributed as part of Python if there was a parse error. (Note that :file:" -"`errcode.h` is not included by :file:`Python.h`, so must be included " -"specifically if needed.)" -msgstr "" - -#: ../../c-api/veryhigh.rst:119 -msgid "" -"This is a simplified interface to :c:func:`PyRun_InteractiveOneFlags` below, " -"leaving *flags* set to ``NULL``." -msgstr "" - -#: ../../c-api/veryhigh.rst:125 -msgid "" -"Similar to :c:func:`PyRun_InteractiveOneObject`, but *filename* is a :c:expr:" -"`const char*`, which is decoded from the :term:`filesystem encoding and " -"error handler`." -msgstr "" - -#: ../../c-api/veryhigh.rst:132 -msgid "" -"This is a simplified interface to :c:func:`PyRun_InteractiveLoopFlags` " -"below, leaving *flags* set to ``NULL``." -msgstr "" - -#: ../../c-api/veryhigh.rst:138 -msgid "" -"Read and execute statements from a file associated with an interactive " -"device until EOF is reached. The user will be prompted using ``sys.ps1`` " -"and ``sys.ps2``. *filename* is decoded from the :term:`filesystem encoding " -"and error handler`. Returns ``0`` at EOF or a negative number upon failure." -msgstr "" - -#: ../../c-api/veryhigh.rst:146 -msgid "" -"Can be set to point to a function with the prototype ``int func(void)``. " -"The function will be called when Python's interpreter prompt is about to " -"become idle and wait for user input from the terminal. The return value is " -"ignored. Overriding this hook can be used to integrate the interpreter's " -"prompt with other event loops, as done in :file:`Modules/_tkinter.c` in the " -"Python source code." -msgstr "" - -#: ../../c-api/veryhigh.rst:154 ../../c-api/veryhigh.rst:178 -msgid "" -"This function is only called from the :ref:`main interpreter `." -msgstr "" - -#: ../../c-api/veryhigh.rst:161 -msgid "" -"Can be set to point to a function with the prototype ``char *func(FILE " -"*stdin, FILE *stdout, char *prompt)``, overriding the default function used " -"to read a single line of input at the interpreter's prompt. The function is " -"expected to output the string *prompt* if it's not ``NULL``, and then read a " -"line of input from the provided standard input file, returning the resulting " -"string. For example, The :mod:`readline` module sets this hook to provide " -"line-editing and tab-completion features." -msgstr "" - -#: ../../c-api/veryhigh.rst:170 -msgid "" -"The result must be a string allocated by :c:func:`PyMem_RawMalloc` or :c:" -"func:`PyMem_RawRealloc`, or ``NULL`` if an error occurred." -msgstr "" - -#: ../../c-api/veryhigh.rst:173 -msgid "" -"The result must be allocated by :c:func:`PyMem_RawMalloc` or :c:func:" -"`PyMem_RawRealloc`, instead of being allocated by :c:func:`PyMem_Malloc` or :" -"c:func:`PyMem_Realloc`." -msgstr "" - -#: ../../c-api/veryhigh.rst:184 -msgid "" -"This is a simplified interface to :c:func:`PyRun_StringFlags` below, leaving " -"*flags* set to ``NULL``." -msgstr "" - -#: ../../c-api/veryhigh.rst:190 -msgid "" -"Execute Python source code from *str* in the context specified by the " -"objects *globals* and *locals* with the compiler flags specified by " -"*flags*. *globals* must be a dictionary; *locals* can be any object that " -"implements the mapping protocol. The parameter *start* specifies the start " -"symbol and must one of the :ref:`available start symbols `." -msgstr "" - -#: ../../c-api/veryhigh.rst:196 -msgid "" -"Returns the result of executing the code as a Python object, or ``NULL`` if " -"an exception was raised." -msgstr "" - -#: ../../c-api/veryhigh.rst:202 -msgid "" -"This is a simplified interface to :c:func:`PyRun_FileExFlags` below, leaving " -"*closeit* set to ``0`` and *flags* set to ``NULL``." -msgstr "" - -#: ../../c-api/veryhigh.rst:208 -msgid "" -"This is a simplified interface to :c:func:`PyRun_FileExFlags` below, leaving " -"*flags* set to ``NULL``." -msgstr "" - -#: ../../c-api/veryhigh.rst:214 -msgid "" -"This is a simplified interface to :c:func:`PyRun_FileExFlags` below, leaving " -"*closeit* set to ``0``." -msgstr "" - -#: ../../c-api/veryhigh.rst:220 -msgid "" -"Similar to :c:func:`PyRun_StringFlags`, but the Python source code is read " -"from *fp* instead of an in-memory string. *filename* should be the name of " -"the file, it is decoded from the :term:`filesystem encoding and error " -"handler`. If *closeit* is true, the file is closed before :c:func:" -"`PyRun_FileExFlags` returns." -msgstr "" - -#: ../../c-api/veryhigh.rst:229 -msgid "" -"This is a simplified interface to :c:func:`Py_CompileStringFlags` below, " -"leaving *flags* set to ``NULL``." -msgstr "" - -#: ../../c-api/veryhigh.rst:235 -msgid "" -"This is a simplified interface to :c:func:`Py_CompileStringExFlags` below, " -"with *optimize* set to ``-1``." -msgstr "" - -#: ../../c-api/veryhigh.rst:241 -msgid "" -"Parse and compile the Python source code in *str*, returning the resulting " -"code object. The start symbol is given by *start*; this can be used to " -"constrain the code which can be compiled and should be :ref:`available start " -"symbols `. The filename specified by *filename* is used to " -"construct the code object and may appear in tracebacks or :exc:`SyntaxError` " -"exception messages. This returns ``NULL`` if the code cannot be parsed or " -"compiled." -msgstr "" - -#: ../../c-api/veryhigh.rst:249 -msgid "" -"The integer *optimize* specifies the optimization level of the compiler; a " -"value of ``-1`` selects the optimization level of the interpreter as given " -"by :option:`-O` options. Explicit levels are ``0`` (no optimization; " -"``__debug__`` is true), ``1`` (asserts are removed, ``__debug__`` is false) " -"or ``2`` (docstrings are removed too)." -msgstr "" - -#: ../../c-api/veryhigh.rst:260 -msgid "" -"Like :c:func:`Py_CompileStringObject`, but *filename* is a byte string " -"decoded from the :term:`filesystem encoding and error handler`." -msgstr "" - -#: ../../c-api/veryhigh.rst:267 -msgid "" -"This is a simplified interface to :c:func:`PyEval_EvalCodeEx`, with just the " -"code object, and global and local variables. The other arguments are set to " -"``NULL``." -msgstr "" - -#: ../../c-api/veryhigh.rst:274 -msgid "" -"Evaluate a precompiled code object, given a particular environment for its " -"evaluation. This environment consists of a dictionary of global variables, " -"a mapping object of local variables, arrays of arguments, keywords and " -"defaults, a dictionary of default values for :ref:`keyword-only ` arguments and a closure tuple of cells." -msgstr "" - -#: ../../c-api/veryhigh.rst:283 -msgid "" -"Evaluate an execution frame. This is a simplified interface to :c:func:" -"`PyEval_EvalFrameEx`, for backward compatibility." -msgstr "" - -#: ../../c-api/veryhigh.rst:289 -msgid "" -"This is the main, unvarnished function of Python interpretation. The code " -"object associated with the execution frame *f* is executed, interpreting " -"bytecode and executing calls as needed. The additional *throwflag* " -"parameter can mostly be ignored - if true, then it causes an exception to " -"immediately be thrown; this is used for the :meth:`~generator.throw` methods " -"of generator objects." -msgstr "" - -#: ../../c-api/veryhigh.rst:296 -msgid "" -"This function now includes a debug assertion to help ensure that it does not " -"silently discard an active exception." -msgstr "" - -#: ../../c-api/veryhigh.rst:303 -msgid "" -"This function changes the flags of the current evaluation frame, and returns " -"true on success, false on failure." -msgstr "" - -#: ../../c-api/veryhigh.rst:309 -msgid "" -"This is the structure used to hold compiler flags. In cases where code is " -"only being compiled, it is passed as ``int flags``, and in cases where code " -"is being executed, it is passed as ``PyCompilerFlags *flags``. In this " -"case, ``from __future__ import`` can modify *flags*." -msgstr "" - -#: ../../c-api/veryhigh.rst:314 -msgid "" -"Whenever ``PyCompilerFlags *flags`` is ``NULL``, :c:member:`~PyCompilerFlags." -"cf_flags` is treated as equal to ``0``, and any modification due to ``from " -"__future__ import`` is discarded." -msgstr "" - -#: ../../c-api/veryhigh.rst:320 -msgid "Compiler flags." -msgstr "編譯器旗標。" - -#: ../../c-api/veryhigh.rst:324 -msgid "" -"*cf_feature_version* is the minor Python version. It should be initialized " -"to ``PY_MINOR_VERSION``." -msgstr "" - -#: ../../c-api/veryhigh.rst:327 -msgid "" -"The field is ignored by default, it is used if and only if ``PyCF_ONLY_AST`` " -"flag is set in :c:member:`~PyCompilerFlags.cf_flags`." -msgstr "" - -#: ../../c-api/veryhigh.rst:330 -msgid "Added *cf_feature_version* field." -msgstr "新增 *cf_feature_version* 欄位。" - -#: ../../c-api/veryhigh.rst:333 -msgid "The available compiler flags are accessible as macros:" -msgstr "可用的編譯器旗標可透過巨集存取：" - -#: ../../c-api/veryhigh.rst:342 -msgid "" -"See :ref:`compiler flags ` in documentation of the :py:" -"mod:`!ast` Python module, which exports these constants under the same names." -msgstr "" - -#: ../../c-api/veryhigh.rst:346 -msgid "" -"The \"``PyCF``\" flags above can be combined with \"``CO_FUTURE``\" flags " -"such as :c:macro:`CO_FUTURE_ANNOTATIONS` to enable features normally " -"selectable using :ref:`future statements `. See :ref:" -"`c_codeobject_flags` for a complete list." -msgstr "" - -#: ../../c-api/veryhigh.rst:355 -msgid "Available start symbols" -msgstr "可用的起始符號" - -#: ../../c-api/veryhigh.rst:362 -msgid "" -"The start symbol from the Python grammar for isolated expressions; for use " -"with :c:func:`Py_CompileString`." -msgstr "" - -#: ../../c-api/veryhigh.rst:370 -msgid "" -"The start symbol from the Python grammar for sequences of statements as read " -"from a file or other source; for use with :c:func:`Py_CompileString`. This " -"is the symbol to use when compiling arbitrarily long Python source code." -msgstr "" - -#: ../../c-api/veryhigh.rst:379 -msgid "" -"The start symbol from the Python grammar for a single statement; for use " -"with :c:func:`Py_CompileString`. This is the symbol used for the interactive " -"interpreter loop." -msgstr "" - -#: ../../c-api/veryhigh.rst:388 -msgid "" -"The start symbol from the Python grammar for a function type; for use with :" -"c:func:`Py_CompileString`. This is used to parse \"signature type comments\" " -"from :pep:`484`." -msgstr "" - -#: ../../c-api/veryhigh.rst:392 -msgid "This requires the :c:macro:`PyCF_ONLY_AST` flag to be set." -msgstr "這需要設定 :c:macro:`PyCF_ONLY_AST` 旗標。" - -#: ../../c-api/veryhigh.rst:395 -msgid ":py:class:`ast.FunctionType`" -msgstr ":py:class:`ast.FunctionType`" - -#: ../../c-api/veryhigh.rst:396 -msgid ":pep:`484`" -msgstr ":pep:`484`" - -#: ../../c-api/veryhigh.rst:402 -msgid "Stack Effects" -msgstr "" - -#: ../../c-api/veryhigh.rst:405 -msgid ":py:func:`dis.stack_effect`" -msgstr ":py:func:`dis.stack_effect`" - -#: ../../c-api/veryhigh.rst:410 -msgid "Sentinel value representing an invalid stack effect." -msgstr "" - -#: ../../c-api/veryhigh.rst:412 -msgid "This is currently equivalent to ``INT_MAX``." -msgstr "這目前等同於 ``INT_MAX``。" - -#: ../../c-api/veryhigh.rst:419 -msgid "Compute the stack effect of *opcode* with argument *oparg*." -msgstr "" - -#: ../../c-api/veryhigh.rst:421 ../../c-api/veryhigh.rst:435 -msgid "" -"On success, this function returns the stack effect; on failure, this " -"returns :c:macro:`PY_INVALID_STACK_EFFECT`." -msgstr "" - -#: ../../c-api/veryhigh.rst:429 -msgid "" -"Similar to :c:func:`PyCompile_OpcodeStackEffect`, but don't include the " -"stack effect of jumping if *jump* is zero." -msgstr "" - -#: ../../c-api/veryhigh.rst:432 -msgid "" -"If *jump* is ``0``, this will not include the stack effect of jumping, but " -"if *jump* is ``1`` or ``-1``, this will include it." -msgstr "" - -#: ../../c-api/veryhigh.rst:360 ../../c-api/veryhigh.rst:368 -#: ../../c-api/veryhigh.rst:377 ../../c-api/veryhigh.rst:386 -msgid "Py_CompileString (C function)" -msgstr "Py_CompileString（C 函式）" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-25 00:13+0000\n" +"PO-Revision-Date: 2018-05-23 14:08+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" + +#: ../../c-api/veryhigh.rst:8 +msgid "The Very High Level Layer" +msgstr "" + +#: ../../c-api/veryhigh.rst:10 +msgid "" +"The functions in this chapter will let you execute Python source code given " +"in a file or a buffer, but they will not let you interact in a more detailed " +"way with the interpreter." +msgstr "" + +#: ../../c-api/veryhigh.rst:14 +msgid "" +"Several of these functions accept a start symbol from the grammar as a " +"parameter. The available start symbols are :c:data:`Py_eval_input`, :c:data:" +"`Py_file_input`, :c:data:`Py_single_input`, and :c:data:" +"`Py_func_type_input`. These are described following the functions which " +"accept them as parameters." +msgstr "" + +#: ../../c-api/veryhigh.rst:20 +msgid "" +"Note also that several of these functions take :c:expr:`FILE*` parameters. " +"One particular issue which needs to be handled carefully is that the :c:type:" +"`FILE` structure for different C libraries can be different and " +"incompatible. Under Windows (at least), it is possible for dynamically " +"linked extensions to actually use different libraries, so care should be " +"taken that :c:expr:`FILE*` parameters are only passed to these functions if " +"it is certain that they were created by the same library that the Python " +"runtime is using." +msgstr "" + +#: ../../c-api/veryhigh.rst:31 +msgid "" +"This is a simplified interface to :c:func:`PyRun_AnyFileExFlags` below, " +"leaving *closeit* set to ``0`` and *flags* set to ``NULL``." +msgstr "" + +#: ../../c-api/veryhigh.rst:37 +msgid "" +"This is a simplified interface to :c:func:`PyRun_AnyFileExFlags` below, " +"leaving the *closeit* argument set to ``0``." +msgstr "" + +#: ../../c-api/veryhigh.rst:43 +msgid "" +"This is a simplified interface to :c:func:`PyRun_AnyFileExFlags` below, " +"leaving the *flags* argument set to ``NULL``." +msgstr "" + +#: ../../c-api/veryhigh.rst:49 +msgid "" +"If *fp* refers to a file associated with an interactive device (console or " +"terminal input or Unix pseudo-terminal), return the value of :c:func:" +"`PyRun_InteractiveLoop`, otherwise return the result of :c:func:" +"`PyRun_SimpleFile`. *filename* is decoded from the filesystem encoding (:" +"func:`sys.getfilesystemencoding`). If *filename* is ``NULL``, this function " +"uses ``\"???\"`` as the filename. If *closeit* is true, the file is closed " +"before ``PyRun_SimpleFileExFlags()`` returns." +msgstr "" + +#: ../../c-api/veryhigh.rst:61 +msgid "" +"This is a simplified interface to :c:func:`PyRun_SimpleStringFlags` below, " +"leaving the :c:struct:`PyCompilerFlags`\\* argument set to ``NULL``." +msgstr "" + +#: ../../c-api/veryhigh.rst:67 +msgid "" +"Executes the Python source code from *command* in the :mod:`__main__` module " +"according to the *flags* argument. If :mod:`__main__` does not already " +"exist, it is created. Returns ``0`` on success or ``-1`` if an exception " +"was raised. If there was an error, there is no way to get the exception " +"information. For the meaning of *flags*, see below." +msgstr "" + +#: ../../c-api/veryhigh.rst:73 +msgid "" +"Note that if an otherwise unhandled :exc:`SystemExit` is raised, this " +"function will not return ``-1``, but exit the process, as long as :c:member:" +"`PyConfig.inspect` is zero." +msgstr "" + +#: ../../c-api/veryhigh.rst:80 +msgid "" +"This is a simplified interface to :c:func:`PyRun_SimpleFileExFlags` below, " +"leaving *closeit* set to ``0`` and *flags* set to ``NULL``." +msgstr "" + +#: ../../c-api/veryhigh.rst:86 +msgid "" +"This is a simplified interface to :c:func:`PyRun_SimpleFileExFlags` below, " +"leaving *flags* set to ``NULL``." +msgstr "" + +#: ../../c-api/veryhigh.rst:92 +msgid "" +"Similar to :c:func:`PyRun_SimpleStringFlags`, but the Python source code is " +"read from *fp* instead of an in-memory string. *filename* should be the name " +"of the file, it is decoded from :term:`filesystem encoding and error " +"handler`. If *closeit* is true, the file is closed before " +"``PyRun_SimpleFileExFlags()`` returns." +msgstr "" + +#: ../../c-api/veryhigh.rst:99 +msgid "" +"On Windows, *fp* should be opened as binary mode (e.g. ``fopen(filename, " +"\"rb\")``). Otherwise, Python may not handle script file with LF line ending " +"correctly." +msgstr "" + +#: ../../c-api/veryhigh.rst:105 +msgid "" +"Read and execute a single statement from a file associated with an " +"interactive device according to the *flags* argument. The user will be " +"prompted using ``sys.ps1`` and ``sys.ps2``. *filename* must be a Python :" +"class:`str` object." +msgstr "" + +#: ../../c-api/veryhigh.rst:110 +msgid "" +"Returns ``0`` when the input was executed successfully, ``-1`` if there was " +"an exception, or an error code from the :file:`errcode.h` include file " +"distributed as part of Python if there was a parse error. (Note that :file:" +"`errcode.h` is not included by :file:`Python.h`, so must be included " +"specifically if needed.)" +msgstr "" + +#: ../../c-api/veryhigh.rst:119 +msgid "" +"This is a simplified interface to :c:func:`PyRun_InteractiveOneFlags` below, " +"leaving *flags* set to ``NULL``." +msgstr "" + +#: ../../c-api/veryhigh.rst:125 +msgid "" +"Similar to :c:func:`PyRun_InteractiveOneObject`, but *filename* is a :c:expr:" +"`const char*`, which is decoded from the :term:`filesystem encoding and " +"error handler`." +msgstr "" + +#: ../../c-api/veryhigh.rst:132 +msgid "" +"This is a simplified interface to :c:func:`PyRun_InteractiveLoopFlags` " +"below, leaving *flags* set to ``NULL``." +msgstr "" + +#: ../../c-api/veryhigh.rst:138 +msgid "" +"Read and execute statements from a file associated with an interactive " +"device until EOF is reached. The user will be prompted using ``sys.ps1`` " +"and ``sys.ps2``. *filename* is decoded from the :term:`filesystem encoding " +"and error handler`. Returns ``0`` at EOF or a negative number upon failure." +msgstr "" + +#: ../../c-api/veryhigh.rst:146 +msgid "" +"Can be set to point to a function with the prototype ``int func(void)``. " +"The function will be called when Python's interpreter prompt is about to " +"become idle and wait for user input from the terminal. The return value is " +"ignored. Overriding this hook can be used to integrate the interpreter's " +"prompt with other event loops, as done in :file:`Modules/_tkinter.c` in the " +"Python source code." +msgstr "" + +#: ../../c-api/veryhigh.rst:154 ../../c-api/veryhigh.rst:178 +msgid "" +"This function is only called from the :ref:`main interpreter `." +msgstr "" + +#: ../../c-api/veryhigh.rst:161 +msgid "" +"Can be set to point to a function with the prototype ``char *func(FILE " +"*stdin, FILE *stdout, char *prompt)``, overriding the default function used " +"to read a single line of input at the interpreter's prompt. The function is " +"expected to output the string *prompt* if it's not ``NULL``, and then read a " +"line of input from the provided standard input file, returning the resulting " +"string. For example, The :mod:`readline` module sets this hook to provide " +"line-editing and tab-completion features." +msgstr "" + +#: ../../c-api/veryhigh.rst:170 +msgid "" +"The result must be a string allocated by :c:func:`PyMem_RawMalloc` or :c:" +"func:`PyMem_RawRealloc`, or ``NULL`` if an error occurred." +msgstr "" + +#: ../../c-api/veryhigh.rst:173 +msgid "" +"The result must be allocated by :c:func:`PyMem_RawMalloc` or :c:func:" +"`PyMem_RawRealloc`, instead of being allocated by :c:func:`PyMem_Malloc` or :" +"c:func:`PyMem_Realloc`." +msgstr "" + +#: ../../c-api/veryhigh.rst:184 +msgid "" +"This is a simplified interface to :c:func:`PyRun_StringFlags` below, leaving " +"*flags* set to ``NULL``." +msgstr "" + +#: ../../c-api/veryhigh.rst:190 +msgid "" +"Execute Python source code from *str* in the context specified by the " +"objects *globals* and *locals* with the compiler flags specified by " +"*flags*. *globals* must be a dictionary; *locals* can be any object that " +"implements the mapping protocol. The parameter *start* specifies the start " +"symbol and must one of the :ref:`available start symbols `." +msgstr "" + +#: ../../c-api/veryhigh.rst:196 +msgid "" +"Returns the result of executing the code as a Python object, or ``NULL`` if " +"an exception was raised." +msgstr "" + +#: ../../c-api/veryhigh.rst:202 +msgid "" +"This is a simplified interface to :c:func:`PyRun_FileExFlags` below, leaving " +"*closeit* set to ``0`` and *flags* set to ``NULL``." +msgstr "" + +#: ../../c-api/veryhigh.rst:208 +msgid "" +"This is a simplified interface to :c:func:`PyRun_FileExFlags` below, leaving " +"*flags* set to ``NULL``." +msgstr "" + +#: ../../c-api/veryhigh.rst:214 +msgid "" +"This is a simplified interface to :c:func:`PyRun_FileExFlags` below, leaving " +"*closeit* set to ``0``." +msgstr "" + +#: ../../c-api/veryhigh.rst:220 +msgid "" +"Similar to :c:func:`PyRun_StringFlags`, but the Python source code is read " +"from *fp* instead of an in-memory string. *filename* should be the name of " +"the file, it is decoded from the :term:`filesystem encoding and error " +"handler`. If *closeit* is true, the file is closed before :c:func:" +"`PyRun_FileExFlags` returns." +msgstr "" + +#: ../../c-api/veryhigh.rst:229 +msgid "" +"This is a simplified interface to :c:func:`Py_CompileStringFlags` below, " +"leaving *flags* set to ``NULL``." +msgstr "" + +#: ../../c-api/veryhigh.rst:235 +msgid "" +"This is a simplified interface to :c:func:`Py_CompileStringExFlags` below, " +"with *optimize* set to ``-1``." +msgstr "" + +#: ../../c-api/veryhigh.rst:241 +msgid "" +"Parse and compile the Python source code in *str*, returning the resulting " +"code object. The start symbol is given by *start*; this can be used to " +"constrain the code which can be compiled and should be :ref:`available start " +"symbols `. The filename specified by *filename* is used to " +"construct the code object and may appear in tracebacks or :exc:`SyntaxError` " +"exception messages. This returns ``NULL`` if the code cannot be parsed or " +"compiled." +msgstr "" + +#: ../../c-api/veryhigh.rst:249 +msgid "" +"The integer *optimize* specifies the optimization level of the compiler; a " +"value of ``-1`` selects the optimization level of the interpreter as given " +"by :option:`-O` options. Explicit levels are ``0`` (no optimization; " +"``__debug__`` is true), ``1`` (asserts are removed, ``__debug__`` is false) " +"or ``2`` (docstrings are removed too)." +msgstr "" + +#: ../../c-api/veryhigh.rst:260 +msgid "" +"Like :c:func:`Py_CompileStringObject`, but *filename* is a byte string " +"decoded from the :term:`filesystem encoding and error handler`." +msgstr "" + +#: ../../c-api/veryhigh.rst:267 +msgid "" +"This is a simplified interface to :c:func:`PyEval_EvalCodeEx`, with just the " +"code object, and global and local variables. The other arguments are set to " +"``NULL``." +msgstr "" + +#: ../../c-api/veryhigh.rst:274 +msgid "" +"Evaluate a precompiled code object, given a particular environment for its " +"evaluation. This environment consists of a dictionary of global variables, " +"a mapping object of local variables, arrays of arguments, keywords and " +"defaults, a dictionary of default values for :ref:`keyword-only ` arguments and a closure tuple of cells." +msgstr "" + +#: ../../c-api/veryhigh.rst:283 +msgid "" +"Evaluate an execution frame. This is a simplified interface to :c:func:" +"`PyEval_EvalFrameEx`, for backward compatibility." +msgstr "" + +#: ../../c-api/veryhigh.rst:289 +msgid "" +"This is the main, unvarnished function of Python interpretation. The code " +"object associated with the execution frame *f* is executed, interpreting " +"bytecode and executing calls as needed. The additional *throwflag* " +"parameter can mostly be ignored - if true, then it causes an exception to " +"immediately be thrown; this is used for the :meth:`~generator.throw` methods " +"of generator objects." +msgstr "" + +#: ../../c-api/veryhigh.rst:296 +msgid "" +"This function now includes a debug assertion to help ensure that it does not " +"silently discard an active exception." +msgstr "" + +#: ../../c-api/veryhigh.rst:303 +msgid "" +"This function changes the flags of the current evaluation frame, and returns " +"true on success, false on failure." +msgstr "" + +#: ../../c-api/veryhigh.rst:309 +msgid "" +"This is the structure used to hold compiler flags. In cases where code is " +"only being compiled, it is passed as ``int flags``, and in cases where code " +"is being executed, it is passed as ``PyCompilerFlags *flags``. In this " +"case, ``from __future__ import`` can modify *flags*." +msgstr "" + +#: ../../c-api/veryhigh.rst:314 +msgid "" +"Whenever ``PyCompilerFlags *flags`` is ``NULL``, :c:member:`~PyCompilerFlags." +"cf_flags` is treated as equal to ``0``, and any modification due to ``from " +"__future__ import`` is discarded." +msgstr "" + +#: ../../c-api/veryhigh.rst:320 +msgid "Compiler flags." +msgstr "編譯器旗標。" + +#: ../../c-api/veryhigh.rst:324 +msgid "" +"*cf_feature_version* is the minor Python version. It should be initialized " +"to ``PY_MINOR_VERSION``." +msgstr "" + +#: ../../c-api/veryhigh.rst:327 +msgid "" +"The field is ignored by default, it is used if and only if ``PyCF_ONLY_AST`` " +"flag is set in :c:member:`~PyCompilerFlags.cf_flags`." +msgstr "" + +#: ../../c-api/veryhigh.rst:330 +msgid "Added *cf_feature_version* field." +msgstr "新增 *cf_feature_version* 欄位。" + +#: ../../c-api/veryhigh.rst:333 +msgid "The available compiler flags are accessible as macros:" +msgstr "可用的編譯器旗標可透過巨集存取：" + +#: ../../c-api/veryhigh.rst:342 +msgid "" +"See :ref:`compiler flags ` in documentation of the :py:" +"mod:`!ast` Python module, which exports these constants under the same names." +msgstr "" + +#: ../../c-api/veryhigh.rst:346 +msgid "" +"The \"``PyCF``\" flags above can be combined with \"``CO_FUTURE``\" flags " +"such as :c:macro:`CO_FUTURE_ANNOTATIONS` to enable features normally " +"selectable using :ref:`future statements `. See :ref:" +"`c_codeobject_flags` for a complete list." +msgstr "" + +#: ../../c-api/veryhigh.rst:355 +msgid "Available start symbols" +msgstr "可用的起始符號" + +#: ../../c-api/veryhigh.rst:362 +msgid "" +"The start symbol from the Python grammar for isolated expressions; for use " +"with :c:func:`Py_CompileString`." +msgstr "" + +#: ../../c-api/veryhigh.rst:370 +msgid "" +"The start symbol from the Python grammar for sequences of statements as read " +"from a file or other source; for use with :c:func:`Py_CompileString`. This " +"is the symbol to use when compiling arbitrarily long Python source code." +msgstr "" + +#: ../../c-api/veryhigh.rst:379 +msgid "" +"The start symbol from the Python grammar for a single statement; for use " +"with :c:func:`Py_CompileString`. This is the symbol used for the interactive " +"interpreter loop." +msgstr "" + +#: ../../c-api/veryhigh.rst:388 +msgid "" +"The start symbol from the Python grammar for a function type; for use with :" +"c:func:`Py_CompileString`. This is used to parse \"signature type comments\" " +"from :pep:`484`." +msgstr "" + +#: ../../c-api/veryhigh.rst:392 +msgid "This requires the :c:macro:`PyCF_ONLY_AST` flag to be set." +msgstr "這需要設定 :c:macro:`PyCF_ONLY_AST` 旗標。" + +#: ../../c-api/veryhigh.rst:395 +msgid ":py:class:`ast.FunctionType`" +msgstr ":py:class:`ast.FunctionType`" + +#: ../../c-api/veryhigh.rst:396 +msgid ":pep:`484`" +msgstr ":pep:`484`" + +#: ../../c-api/veryhigh.rst:402 +msgid "Stack Effects" +msgstr "" + +#: ../../c-api/veryhigh.rst:405 +msgid ":py:func:`dis.stack_effect`" +msgstr ":py:func:`dis.stack_effect`" + +#: ../../c-api/veryhigh.rst:410 +msgid "Sentinel value representing an invalid stack effect." +msgstr "" + +#: ../../c-api/veryhigh.rst:412 +msgid "This is currently equivalent to ``INT_MAX``." +msgstr "這目前等同於 ``INT_MAX``。" + +#: ../../c-api/veryhigh.rst:419 +msgid "Compute the stack effect of *opcode* with argument *oparg*." +msgstr "" + +#: ../../c-api/veryhigh.rst:421 ../../c-api/veryhigh.rst:435 +msgid "" +"On success, this function returns the stack effect; on failure, this " +"returns :c:macro:`PY_INVALID_STACK_EFFECT`." +msgstr "" + +#: ../../c-api/veryhigh.rst:429 +msgid "" +"Similar to :c:func:`PyCompile_OpcodeStackEffect`, but don't include the " +"stack effect of jumping if *jump* is zero." +msgstr "" + +#: ../../c-api/veryhigh.rst:432 +msgid "" +"If *jump* is ``0``, this will not include the stack effect of jumping, but " +"if *jump* is ``1`` or ``-1``, this will include it." +msgstr "" + +#: ../../c-api/veryhigh.rst:360 ../../c-api/veryhigh.rst:368 +#: ../../c-api/veryhigh.rst:377 ../../c-api/veryhigh.rst:386 +msgid "Py_CompileString (C function)" +msgstr "Py_CompileString（C 函式）" diff --git a/c-api/weakref.po b/c-api/weakref.po index a6cc855273..1be34bb768 100644 --- a/c-api/weakref.po +++ b/c-api/weakref.po @@ -1,165 +1,165 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Leon H., 2017 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-13 00:15+0000\n" -"PO-Revision-Date: 2017-09-22 18:26+0000\n" -"Last-Translator: Leon H.\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" - -#: ../../c-api/weakref.rst:6 -msgid "Weak Reference Objects" -msgstr "弱參照物件" - -#: ../../c-api/weakref.rst:8 -msgid "" -"Python supports *weak references* as first-class objects. There are two " -"specific object types which directly implement weak references. The first " -"is a simple reference object, and the second acts as a proxy for the " -"original object as much as it can." -msgstr "" - -#: ../../c-api/weakref.rst:16 -msgid "" -"Return non-zero if *ob* is either a reference or proxy object. This " -"function always succeeds." -msgstr "" - -#: ../../c-api/weakref.rst:22 -msgid "" -"Return non-zero if *ob* is a reference object or a subclass of the reference " -"type. This function always succeeds." -msgstr "" - -#: ../../c-api/weakref.rst:28 -msgid "" -"Return non-zero if *ob* is a reference object, but not a subclass of the " -"reference type. This function always succeeds." -msgstr "" - -#: ../../c-api/weakref.rst:34 -msgid "" -"Return non-zero if *ob* is a proxy object. This function always succeeds." -msgstr "" - -#: ../../c-api/weakref.rst:39 -msgid "" -"Return a weak reference object for the object *ob*. This will always return " -"a new reference, but is not guaranteed to create a new object; an existing " -"reference object may be returned. The second parameter, *callback*, can be " -"a callable object that receives notification when *ob* is garbage collected; " -"it should accept a single parameter, which will be the weak reference object " -"itself. *callback* may also be ``None`` or ``NULL``. If *ob* is not a " -"weakly referenceable object, or if *callback* is not callable, ``None``, or " -"``NULL``, this will return ``NULL`` and raise :exc:`TypeError`." -msgstr "" - -#: ../../c-api/weakref.rst:49 ../../c-api/weakref.rst:65 -msgid "" -":c:func:`PyType_SUPPORTS_WEAKREFS` for checking if *ob* is weakly " -"referenceable." -msgstr "" - -#: ../../c-api/weakref.rst:55 -msgid "" -"Return a weak reference proxy object for the object *ob*. This will always " -"return a new reference, but is not guaranteed to create a new object; an " -"existing proxy object may be returned. The second parameter, *callback*, " -"can be a callable object that receives notification when *ob* is garbage " -"collected; it should accept a single parameter, which will be the weak " -"reference object itself. *callback* may also be ``None`` or ``NULL``. If " -"*ob* is not a weakly referenceable object, or if *callback* is not callable, " -"``None``, or ``NULL``, this will return ``NULL`` and raise :exc:`TypeError`." -msgstr "" - -#: ../../c-api/weakref.rst:71 -msgid "" -"Get a :term:`strong reference` to the referenced object from a weak " -"reference, *ref*, into *\\*pobj*." -msgstr "" - -#: ../../c-api/weakref.rst:74 -msgid "" -"On success, set *\\*pobj* to a new :term:`strong reference` to the " -"referenced object and return 1." -msgstr "" - -#: ../../c-api/weakref.rst:76 -msgid "If the reference is dead, set *\\*pobj* to ``NULL`` and return 0." -msgstr "" - -#: ../../c-api/weakref.rst:77 -msgid "On error, raise an exception and return -1." -msgstr "" - -#: ../../c-api/weakref.rst:84 -msgid "" -"Return a :term:`borrowed reference` to the referenced object from a weak " -"reference, *ref*. If the referent is no longer live, returns ``Py_None``." -msgstr "" - -#: ../../c-api/weakref.rst:89 -msgid "" -"This function returns a :term:`borrowed reference` to the referenced object. " -"This means that you should always call :c:func:`Py_INCREF` on the object " -"except when it cannot be destroyed before the last usage of the borrowed " -"reference." -msgstr "" - -#: ../../c-api/weakref.rst:94 ../../c-api/weakref.rst:102 -msgid "Use :c:func:`PyWeakref_GetRef` instead." -msgstr "" - -#: ../../c-api/weakref.rst:100 -msgid "Similar to :c:func:`PyWeakref_GetObject`, but does no error checking." -msgstr "" - -#: ../../c-api/weakref.rst:108 -msgid "" -"Test if the weak reference *ref* is dead. Returns 1 if the reference is " -"dead, 0 if it is alive, and -1 with an error set if *ref* is not a weak " -"reference object." -msgstr "" - -#: ../../c-api/weakref.rst:117 -msgid "" -"This function is called by the :c:member:`~PyTypeObject.tp_dealloc` handler " -"to clear weak references." -msgstr "" - -#: ../../c-api/weakref.rst:120 -msgid "" -"This iterates through the weak references for *object* and calls callbacks " -"for those references which have one. It returns when all callbacks have been " -"attempted." -msgstr "" - -#: ../../c-api/weakref.rst:127 -msgid "Clears the weakrefs for *object* without calling the callbacks." -msgstr "" - -#: ../../c-api/weakref.rst:129 -msgid "" -"This function is called by the :c:member:`~PyTypeObject.tp_dealloc` handler " -"for types with finalizers (i.e., :meth:`~object.__del__`). The handler for " -"those objects first calls :c:func:`PyObject_ClearWeakRefs` to clear weakrefs " -"and call their callbacks, then the finalizer, and finally this function to " -"clear any weakrefs that may have been created by the finalizer." -msgstr "" - -#: ../../c-api/weakref.rst:135 -msgid "" -"In most circumstances, it's more appropriate to use :c:func:" -"`PyObject_ClearWeakRefs` to clear weakrefs instead of this function." -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Leon H., 2017 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-13 00:15+0000\n" +"PO-Revision-Date: 2017-09-22 18:26+0000\n" +"Last-Translator: Leon H.\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" + +#: ../../c-api/weakref.rst:6 +msgid "Weak Reference Objects" +msgstr "弱參照物件" + +#: ../../c-api/weakref.rst:8 +msgid "" +"Python supports *weak references* as first-class objects. There are two " +"specific object types which directly implement weak references. The first " +"is a simple reference object, and the second acts as a proxy for the " +"original object as much as it can." +msgstr "" + +#: ../../c-api/weakref.rst:16 +msgid "" +"Return non-zero if *ob* is either a reference or proxy object. This " +"function always succeeds." +msgstr "" + +#: ../../c-api/weakref.rst:22 +msgid "" +"Return non-zero if *ob* is a reference object or a subclass of the reference " +"type. This function always succeeds." +msgstr "" + +#: ../../c-api/weakref.rst:28 +msgid "" +"Return non-zero if *ob* is a reference object, but not a subclass of the " +"reference type. This function always succeeds." +msgstr "" + +#: ../../c-api/weakref.rst:34 +msgid "" +"Return non-zero if *ob* is a proxy object. This function always succeeds." +msgstr "" + +#: ../../c-api/weakref.rst:39 +msgid "" +"Return a weak reference object for the object *ob*. This will always return " +"a new reference, but is not guaranteed to create a new object; an existing " +"reference object may be returned. The second parameter, *callback*, can be " +"a callable object that receives notification when *ob* is garbage collected; " +"it should accept a single parameter, which will be the weak reference object " +"itself. *callback* may also be ``None`` or ``NULL``. If *ob* is not a " +"weakly referenceable object, or if *callback* is not callable, ``None``, or " +"``NULL``, this will return ``NULL`` and raise :exc:`TypeError`." +msgstr "" + +#: ../../c-api/weakref.rst:49 ../../c-api/weakref.rst:65 +msgid "" +":c:func:`PyType_SUPPORTS_WEAKREFS` for checking if *ob* is weakly " +"referenceable." +msgstr "" + +#: ../../c-api/weakref.rst:55 +msgid "" +"Return a weak reference proxy object for the object *ob*. This will always " +"return a new reference, but is not guaranteed to create a new object; an " +"existing proxy object may be returned. The second parameter, *callback*, " +"can be a callable object that receives notification when *ob* is garbage " +"collected; it should accept a single parameter, which will be the weak " +"reference object itself. *callback* may also be ``None`` or ``NULL``. If " +"*ob* is not a weakly referenceable object, or if *callback* is not callable, " +"``None``, or ``NULL``, this will return ``NULL`` and raise :exc:`TypeError`." +msgstr "" + +#: ../../c-api/weakref.rst:71 +msgid "" +"Get a :term:`strong reference` to the referenced object from a weak " +"reference, *ref*, into *\\*pobj*." +msgstr "" + +#: ../../c-api/weakref.rst:74 +msgid "" +"On success, set *\\*pobj* to a new :term:`strong reference` to the " +"referenced object and return 1." +msgstr "" + +#: ../../c-api/weakref.rst:76 +msgid "If the reference is dead, set *\\*pobj* to ``NULL`` and return 0." +msgstr "" + +#: ../../c-api/weakref.rst:77 +msgid "On error, raise an exception and return -1." +msgstr "" + +#: ../../c-api/weakref.rst:84 +msgid "" +"Return a :term:`borrowed reference` to the referenced object from a weak " +"reference, *ref*. If the referent is no longer live, returns ``Py_None``." +msgstr "" + +#: ../../c-api/weakref.rst:89 +msgid "" +"This function returns a :term:`borrowed reference` to the referenced object. " +"This means that you should always call :c:func:`Py_INCREF` on the object " +"except when it cannot be destroyed before the last usage of the borrowed " +"reference." +msgstr "" + +#: ../../c-api/weakref.rst:94 ../../c-api/weakref.rst:102 +msgid "Use :c:func:`PyWeakref_GetRef` instead." +msgstr "" + +#: ../../c-api/weakref.rst:100 +msgid "Similar to :c:func:`PyWeakref_GetObject`, but does no error checking." +msgstr "" + +#: ../../c-api/weakref.rst:108 +msgid "" +"Test if the weak reference *ref* is dead. Returns 1 if the reference is " +"dead, 0 if it is alive, and -1 with an error set if *ref* is not a weak " +"reference object." +msgstr "" + +#: ../../c-api/weakref.rst:117 +msgid "" +"This function is called by the :c:member:`~PyTypeObject.tp_dealloc` handler " +"to clear weak references." +msgstr "" + +#: ../../c-api/weakref.rst:120 +msgid "" +"This iterates through the weak references for *object* and calls callbacks " +"for those references which have one. It returns when all callbacks have been " +"attempted." +msgstr "" + +#: ../../c-api/weakref.rst:127 +msgid "Clears the weakrefs for *object* without calling the callbacks." +msgstr "" + +#: ../../c-api/weakref.rst:129 +msgid "" +"This function is called by the :c:member:`~PyTypeObject.tp_dealloc` handler " +"for types with finalizers (i.e., :meth:`~object.__del__`). The handler for " +"those objects first calls :c:func:`PyObject_ClearWeakRefs` to clear weakrefs " +"and call their callbacks, then the finalizer, and finally this function to " +"clear any weakrefs that may have been created by the finalizer." +msgstr "" + +#: ../../c-api/weakref.rst:135 +msgid "" +"In most circumstances, it's more appropriate to use :c:func:" +"`PyObject_ClearWeakRefs` to clear weakrefs instead of this function." +msgstr "" diff --git a/contents.po b/contents.po index c7d37814e7..b38d5cc505 100644 --- a/contents.po +++ b/contents.po @@ -1,24 +1,24 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Ching-Lung Chuang, 2015 -# Liang-Bo Wang , 2015 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2018-06-26 18:54+0800\n" -"PO-Revision-Date: 2017-09-22 18:26+0000\n" -"Last-Translator: Liang-Bo Wang \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" - -#: ../../contents.rst:3 -msgid "Python Documentation contents" -msgstr "Python 說明文件內容" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Ching-Lung Chuang, 2015 +# Liang-Bo Wang , 2015 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2018-06-26 18:54+0800\n" +"PO-Revision-Date: 2017-09-22 18:26+0000\n" +"Last-Translator: Liang-Bo Wang \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" + +#: ../../contents.rst:3 +msgid "Python Documentation contents" +msgstr "Python 說明文件內容" diff --git a/copyright.po b/copyright.po index b19aacbaaf..9a99b66e11 100644 --- a/copyright.po +++ b/copyright.po @@ -1,58 +1,58 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Adrian Liaw , 2015 -# Ching-Lung Chuang, 2015 -# Liang-Bo Wang , 2016 -# meowmeowcat , 2021 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: 2021-06-25 20:17+0800\n" -"Last-Translator: meowmeowcat \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" -"X-Generator: Poedit 2.4.3\n" - -#: ../../copyright.rst:3 -msgid "Copyright" -msgstr "版權宣告" - -#: ../../copyright.rst:5 -msgid "Python and this documentation is:" -msgstr "Python 和這份說明文件的版權：" - -#: ../../copyright.rst:7 -msgid "Copyright © 2001 Python Software Foundation. All rights reserved." -msgstr "Copyright © 2001 Python 軟體基金會。保留所有權利。" - -#: ../../copyright.rst:9 -msgid "Copyright © 2000 BeOpen.com. All rights reserved." -msgstr "Copyright © 2000 BeOpen.com 保留所有權利。" - -#: ../../copyright.rst:11 -msgid "" -"Copyright © 1995-2000 Corporation for National Research Initiatives. All " -"rights reserved." -msgstr "" -"Copyright © 1995-2000 Corporation for National Research Initiatives 保留所有" -"權利。" - -#: ../../copyright.rst:14 -msgid "" -"Copyright © 1991-1995 Stichting Mathematisch Centrum. All rights reserved." -msgstr "Copyright © 1991-1995 Stichting Mathematisch Centrum 保留所有權利。" - -#: ../../copyright.rst:18 -msgid "" -"See :ref:`history-and-license` for complete license and permissions " -"information." -msgstr "完整的授權條款資訊請參見\\ :ref:`history-and-license`。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Adrian Liaw , 2015 +# Ching-Lung Chuang, 2015 +# Liang-Bo Wang , 2016 +# meowmeowcat , 2021 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: 2021-06-25 20:17+0800\n" +"Last-Translator: meowmeowcat \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" +"X-Generator: Poedit 2.4.3\n" + +#: ../../copyright.rst:3 +msgid "Copyright" +msgstr "版權宣告" + +#: ../../copyright.rst:5 +msgid "Python and this documentation is:" +msgstr "Python 和這份說明文件的版權：" + +#: ../../copyright.rst:7 +msgid "Copyright © 2001 Python Software Foundation. All rights reserved." +msgstr "Copyright © 2001 Python 軟體基金會。保留所有權利。" + +#: ../../copyright.rst:9 +msgid "Copyright © 2000 BeOpen.com. All rights reserved." +msgstr "Copyright © 2000 BeOpen.com 保留所有權利。" + +#: ../../copyright.rst:11 +msgid "" +"Copyright © 1995-2000 Corporation for National Research Initiatives. All " +"rights reserved." +msgstr "" +"Copyright © 1995-2000 Corporation for National Research Initiatives 保留所有" +"權利。" + +#: ../../copyright.rst:14 +msgid "" +"Copyright © 1991-1995 Stichting Mathematisch Centrum. All rights reserved." +msgstr "Copyright © 1991-1995 Stichting Mathematisch Centrum 保留所有權利。" + +#: ../../copyright.rst:18 +msgid "" +"See :ref:`history-and-license` for complete license and permissions " +"information." +msgstr "完整的授權條款資訊請參見\\ :ref:`history-and-license`。" diff --git a/deprecations/c-api-pending-removal-in-3.14.po b/deprecations/c-api-pending-removal-in-3.14.po index 8a9ae15c7c..3a885c3bcc 100644 --- a/deprecations/c-api-pending-removal-in-3.14.po +++ b/deprecations/c-api-pending-removal-in-3.14.po @@ -1,36 +1,36 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \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" - -#: ../../deprecations/c-api-pending-removal-in-3.14.rst:2 -msgid "Pending removal in Python 3.14" -msgstr "Python 3.14 中待移除的項目" - -#: ../../deprecations/c-api-pending-removal-in-3.14.rst:4 -msgid "" -"The ``ma_version_tag`` field in :c:type:`PyDictObject` for extension modules " -"(:pep:`699`; :gh:`101193`)." -msgstr "" -":c:type:`PyDictObject` 中的 ``ma_version_tag`` 欄位，用於擴充模組 " -"(:pep:`699`；:gh:`101193`)。" - -#: ../../deprecations/c-api-pending-removal-in-3.14.rst:7 -msgid "" -"Creating :c:data:`immutable types ` with mutable " -"bases (:gh:`95388`)." -msgstr "" -"使用可變基底建立\\ :c:data:`不可變型別 ` " -"(:gh:`95388`)。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \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" + +#: ../../deprecations/c-api-pending-removal-in-3.14.rst:2 +msgid "Pending removal in Python 3.14" +msgstr "Python 3.14 中待移除的項目" + +#: ../../deprecations/c-api-pending-removal-in-3.14.rst:4 +msgid "" +"The ``ma_version_tag`` field in :c:type:`PyDictObject` for extension modules " +"(:pep:`699`; :gh:`101193`)." +msgstr "" +":c:type:`PyDictObject` 中的 ``ma_version_tag`` 欄位，用於擴充模組 " +"(:pep:`699`；:gh:`101193`)。" + +#: ../../deprecations/c-api-pending-removal-in-3.14.rst:7 +msgid "" +"Creating :c:data:`immutable types ` with mutable " +"bases (:gh:`95388`)." +msgstr "" +"使用可變基底建立\\ :c:data:`不可變型別 ` " +"(:gh:`95388`)。" diff --git a/deprecations/c-api-pending-removal-in-3.15.po b/deprecations/c-api-pending-removal-in-3.15.po index 34f2be4674..6db0449510 100644 --- a/deprecations/c-api-pending-removal-in-3.15.po +++ b/deprecations/c-api-pending-removal-in-3.15.po @@ -1,382 +1,382 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \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" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:2 -msgid "Pending removal in Python 3.15" -msgstr "Python 3.15 中待移除的項目" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:4 -msgid "" -"The :c:func:`PyImport_ImportModuleNoBlock`: " -"Use :c:func:`PyImport_ImportModule` instead." -msgstr "" -":c:func:`PyImport_ImportModuleNoBlock`：請改" -"用 :c:func:`PyImport_ImportModule`。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:6 -msgid "" -":c:func:`PyWeakref_GetObject` and :c:func:`PyWeakref_GET_OBJECT`: " -"Use :c:func:`PyWeakref_GetRef` instead. The `pythoncapi-compat project " -"`__ can be used to " -"get :c:func:`PyWeakref_GetRef` on Python 3.12 and older." -msgstr "" -":c:func:`PyWeakref_GetObject` 和 :c:func:`PyWeakref_GET_OBJECT`：請改" -"用 :c:func:`PyWeakref_GetRef`。可以使用 `pythoncapi-compat 專案 `__\\ 來為 Python 3.12 和更早版本取" -"得 :c:func:`PyWeakref_GetRef`。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:10 -msgid "" -":c:type:`Py_UNICODE` type and the :c:macro:`!Py_UNICODE_WIDE` macro: " -"Use :c:type:`wchar_t` instead." -msgstr "" -":c:type:`Py_UNICODE` 型別與 :c:macro:`!Py_UNICODE_WIDE` 巨集：請改" -"用 :c:type:`wchar_t`。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:12 -msgid "" -":c:func:`!PyUnicode_AsDecodedObject`: Use :c:func:`PyCodec_Decode` instead." -msgstr "" -":c:func:`!PyUnicode_AsDecodedObject`：請改用 :c:func:`PyCodec_Decode`。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:14 -msgid "" -":c:func:`!PyUnicode_AsDecodedUnicode`: Use :c:func:`PyCodec_Decode` instead; " -"Note that some codecs (for example, \"base64\") may return a type other " -"than :class:`str`, such as :class:`bytes`." -msgstr "" -":c:func:`!PyUnicode_AsDecodedUnicode`：請改用 :c:func:`PyCodec_Decode`；請注" -"意某些編解碼器（例如 \"base64\"）可能會回傳非 :class:`str` 的型別，例" -"如 :class:`bytes`。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:17 -msgid "" -":c:func:`!PyUnicode_AsEncodedObject`: Use :c:func:`PyCodec_Encode` instead." -msgstr "" -":c:func:`!PyUnicode_AsEncodedObject`：請改用 :c:func:`PyCodec_Encode`。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:19 -msgid "" -":c:func:`!PyUnicode_AsEncodedUnicode`: Use :c:func:`PyCodec_Encode` instead; " -"Note that some codecs (for example, \"base64\") may return a type other " -"than :class:`bytes`, such as :class:`str`." -msgstr "" -":c:func:`!PyUnicode_AsEncodedUnicode`：請改用 :c:func:`PyCodec_Encode`；請注" -"意某些編解碼器（例如 \"base64\"）可能會回傳非 :class:`bytes` 的型別，例" -"如 :class:`str`。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:22 -msgid "Python initialization functions, deprecated in Python 3.13:" -msgstr "Python 初始化函式，自 Python 3.13 起已被棄用：" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:24 -msgid "" -":c:func:`Py_GetPath`: Use :c:func:`PyConfig_Get(\"module_search_paths\") " -"` (:data:`sys.path`) instead." -msgstr "" -":c:func:`Py_GetPath`：請改用 :c:func:`PyConfig_Get(\"module_search_paths\") " -"` (:data:`sys.path`)。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:27 -msgid "" -":c:func:`Py_GetPrefix`: Use :c:func:`PyConfig_Get(\"base_prefix\") " -"` (:data:`sys.base_prefix`) instead. " -"Use :c:func:`PyConfig_Get(\"prefix\") ` (:data:`sys.prefix`) " -"if :ref:`virtual environments ` need to be handled." -msgstr "" -":c:func:`Py_GetPrefix`：請改用 :c:func:`PyConfig_Get(\"base_prefix\") " -"` (:data:`sys.base_prefix`)。如果需要處理\\ :ref:`虛擬環境 " -"`，請改用 :c:func:`PyConfig_Get(\"prefix\") ` " -"(:data:`sys.prefix`)。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:32 -msgid "" -":c:func:`Py_GetExecPrefix`: Use :c:func:`PyConfig_Get(\"base_exec_prefix\") " -"` (:data:`sys.base_exec_prefix`) instead. " -"Use :c:func:`PyConfig_Get(\"exec_prefix\") ` " -"(:data:`sys.exec_prefix`) if :ref:`virtual environments ` need to " -"be handled." -msgstr "" -":c:func:`Py_GetExecPrefix`：請改" -"用 :c:func:`PyConfig_Get(\"base_exec_prefix\") ` " -"(:data:`sys.base_exec_prefix`)。如果需要處理\\ :ref:`虛擬環境 `，請" -"改用 :c:func:`PyConfig_Get(\"exec_prefix\") ` " -"(:data:`sys.exec_prefix`)。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:38 -msgid "" -":c:func:`Py_GetProgramFullPath`: Use :c:func:`PyConfig_Get(\"executable\") " -"` (:data:`sys.executable`) instead." -msgstr "" -":c:func:`Py_GetProgramFullPath`：請改" -"用 :c:func:`PyConfig_Get(\"executable\") ` " -"(:data:`sys.executable`)。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:41 -msgid "" -":c:func:`Py_GetProgramName`: Use :c:func:`PyConfig_Get(\"executable\") " -"` (:data:`sys.executable`) instead." -msgstr "" -":c:func:`Py_GetProgramName`：請改用 :c:func:`PyConfig_Get(\"executable\") " -"` (:data:`sys.executable`)。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:44 -msgid "" -":c:func:`Py_GetPythonHome`: Use :c:func:`PyConfig_Get(\"home\") " -"` or the :envvar:`PYTHONHOME` environment variable instead." -msgstr "" -":c:func:`Py_GetPythonHome`：請改用 :c:func:`PyConfig_Get(\"home\") " -"` 或 :envvar:`PYTHONHOME` 環境變數。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:48 -msgid "" -"The `pythoncapi-compat project `__ can be used to get :c:func:`PyConfig_Get` on Python 3.13 and older." -msgstr "" -"`pythoncapi-compat 專案 `__ 可" -"以用來為 Python 3.13 和更早版本取得 :c:func:`PyConfig_Get`。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:52 -msgid "" -"Functions to configure Python's initialization, deprecated in Python 3.11:" -msgstr "用於配置 Python 初始化的函式，自 Python 3.11 起已被棄用：" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:54 -msgid ":c:func:`!PySys_SetArgvEx()`: Set :c:member:`PyConfig.argv` instead." -msgstr ":c:func:`!PySys_SetArgvEx()`：請改用 :c:member:`PyConfig.argv`。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:56 -msgid ":c:func:`!PySys_SetArgv()`: Set :c:member:`PyConfig.argv` instead." -msgstr ":c:func:`!PySys_SetArgv()`：請改用 :c:member:`PyConfig.argv`。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:58 -msgid "" -":c:func:`!Py_SetProgramName()`: Set :c:member:`PyConfig.program_name` " -"instead." -msgstr "" -":c:func:`!Py_SetProgramName()`：請改用 :c:member:`PyConfig.program_name`。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:60 -msgid ":c:func:`!Py_SetPythonHome()`: Set :c:member:`PyConfig.home` instead." -msgstr ":c:func:`!Py_SetPythonHome()`：請改用 :c:member:`PyConfig.home`。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:62 -msgid "" -":c:func:`PySys_ResetWarnOptions`: Clear :data:`sys.warnoptions` and :data:`!" -"warnings.filters` instead." -msgstr "" -":c:func:`PySys_ResetWarnOptions`：請改為清除 :data:`sys.warnoptions` " -"和 :data:`!warnings.filters`。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:65 -msgid "" -"The :c:func:`Py_InitializeFromConfig` API should be used " -"with :c:type:`PyConfig` instead." -msgstr "" -"應改用帶有 :c:type:`PyConfig` 的 :c:func:`Py_InitializeFromConfig` API。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:68 -msgid "Global configuration variables:" -msgstr "全域配置變數：" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:70 -msgid "" -":c:var:`Py_DebugFlag`: Use :c:member:`PyConfig.parser_debug` " -"or :c:func:`PyConfig_Get(\"parser_debug\") ` instead." -msgstr "" -":c:var:`Py_DebugFlag`：請改用 :c:member:`PyConfig.parser_debug` " -"或 :c:func:`PyConfig_Get(\"parser_debug\") `。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:73 -msgid "" -":c:var:`Py_VerboseFlag`: Use :c:member:`PyConfig.verbose` " -"or :c:func:`PyConfig_Get(\"verbose\") ` instead." -msgstr "" -":c:var:`Py_VerboseFlag`：請改用 :c:member:`PyConfig.verbose` " -"或 :c:func:`PyConfig_Get(\"verbose\") `。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:76 -msgid "" -":c:var:`Py_QuietFlag`: Use :c:member:`PyConfig.quiet` " -"or :c:func:`PyConfig_Get(\"quiet\") ` instead." -msgstr "" -":c:var:`Py_QuietFlag`：請改用 :c:member:`PyConfig.quiet` " -"或 :c:func:`PyConfig_Get(\"quiet\") `。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:79 -msgid "" -":c:var:`Py_InteractiveFlag`: Use :c:member:`PyConfig.interactive` " -"or :c:func:`PyConfig_Get(\"interactive\") ` instead." -msgstr "" -":c:var:`Py_InteractiveFlag`：請改用 :c:member:`PyConfig.interactive` " -"或 :c:func:`PyConfig_Get(\"interactive\") `。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:82 -msgid "" -":c:var:`Py_InspectFlag`: Use :c:member:`PyConfig.inspect` " -"or :c:func:`PyConfig_Get(\"inspect\") ` instead." -msgstr "" -":c:var:`Py_InspectFlag`：請改用 :c:member:`PyConfig.inspect` " -"或 :c:func:`PyConfig_Get(\"inspect\") `。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:85 -msgid "" -":c:var:`Py_OptimizeFlag`: Use :c:member:`PyConfig.optimization_level` " -"or :c:func:`PyConfig_Get(\"optimization_level\") ` instead." -msgstr "" -":c:var:`Py_OptimizeFlag`：請改用 :c:member:`PyConfig.optimization_level` " -"或 :c:func:`PyConfig_Get(\"optimization_level\") `。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:88 -msgid "" -":c:var:`Py_NoSiteFlag`: Use :c:member:`PyConfig.site_import` " -"or :c:func:`PyConfig_Get(\"site_import\") ` instead." -msgstr "" -":c:var:`Py_NoSiteFlag`：請改用 :c:member:`PyConfig.site_import` " -"或 :c:func:`PyConfig_Get(\"site_import\") `。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:91 -msgid "" -":c:var:`Py_BytesWarningFlag`: Use :c:member:`PyConfig.bytes_warning` " -"or :c:func:`PyConfig_Get(\"bytes_warning\") ` instead." -msgstr "" -":c:var:`Py_BytesWarningFlag`：請改用 :c:member:`PyConfig.bytes_warning` " -"或 :c:func:`PyConfig_Get(\"bytes_warning\") `。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:94 -msgid "" -":c:var:`Py_FrozenFlag`: Use :c:member:`PyConfig.pathconfig_warnings` " -"or :c:func:`PyConfig_Get(\"pathconfig_warnings\") ` instead." -msgstr "" -":c:var:`Py_FrozenFlag`：請改用 :c:member:`PyConfig.pathconfig_warnings` " -"或 :c:func:`PyConfig_Get(\"pathconfig_warnings\") `。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:97 -msgid "" -":c:var:`Py_IgnoreEnvironmentFlag`: Use :c:member:`PyConfig.use_environment` " -"or :c:func:`PyConfig_Get(\"use_environment\") ` instead." -msgstr "" -":c:var:`Py_IgnoreEnvironmentFlag`：請改" -"用 :c:member:`PyConfig.use_environment` " -"或 :c:func:`PyConfig_Get(\"use_environment\") `。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:100 -msgid "" -":c:var:`Py_DontWriteBytecodeFlag`: Use :c:member:`PyConfig.write_bytecode` " -"or :c:func:`PyConfig_Get(\"write_bytecode\") ` instead." -msgstr "" -":c:var:`Py_DontWriteBytecodeFlag`：請改" -"用 :c:member:`PyConfig.write_bytecode` " -"或 :c:func:`PyConfig_Get(\"write_bytecode\") `。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:103 -msgid "" -":c:var:`Py_NoUserSiteDirectory`: " -"Use :c:member:`PyConfig.user_site_directory` " -"or :c:func:`PyConfig_Get(\"user_site_directory\") ` instead." -msgstr "" -":c:var:`Py_NoUserSiteDirectory`：請改" -"用 :c:member:`PyConfig.user_site_directory` " -"或 :c:func:`PyConfig_Get(\"user_site_directory\") `。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:106 -msgid "" -":c:var:`Py_UnbufferedStdioFlag`: Use :c:member:`PyConfig.buffered_stdio` " -"or :c:func:`PyConfig_Get(\"buffered_stdio\") ` instead." -msgstr "" -":c:var:`Py_UnbufferedStdioFlag`：請改用 :c:member:`PyConfig.buffered_stdio` " -"或 :c:func:`PyConfig_Get(\"buffered_stdio\") `。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:109 -msgid "" -":c:var:`Py_HashRandomizationFlag`: Use :c:member:`PyConfig.use_hash_seed` " -"and :c:member:`PyConfig.hash_seed` or :c:func:`PyConfig_Get(\"hash_seed\") " -"` instead." -msgstr "" -":c:var:`Py_HashRandomizationFlag`：請改用 :c:member:`PyConfig.use_hash_seed` " -"和 :c:member:`PyConfig.hash_seed` 或 :c:func:`PyConfig_Get(\"hash_seed\") " -"`。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:113 -msgid "" -":c:var:`Py_IsolatedFlag`: Use :c:member:`PyConfig.isolated` " -"or :c:func:`PyConfig_Get(\"isolated\") ` instead." -msgstr "" -":c:var:`Py_IsolatedFlag`：請改用 :c:member:`PyConfig.isolated` " -"或 :c:func:`PyConfig_Get(\"isolated\") `。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:116 -msgid "" -":c:var:`Py_LegacyWindowsFSEncodingFlag`: " -"Use :c:member:`PyPreConfig.legacy_windows_fs_encoding` " -"or :c:func:`PyConfig_Get(\"legacy_windows_fs_encoding\") ` " -"instead." -msgstr "" -":c:var:`Py_LegacyWindowsFSEncodingFlag`：請改" -"用 :c:member:`PyPreConfig.legacy_windows_fs_encoding` " -"或 :c:func:`PyConfig_Get(\"legacy_windows_fs_encoding\") `。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:119 -msgid "" -":c:var:`Py_LegacyWindowsStdioFlag`: " -"Use :c:member:`PyConfig.legacy_windows_stdio` " -"or :c:func:`PyConfig_Get(\"legacy_windows_stdio\") ` instead." -msgstr "" -":c:var:`Py_LegacyWindowsStdioFlag`：請改" -"用 :c:member:`PyConfig.legacy_windows_stdio` " -"或 :c:func:`PyConfig_Get(\"legacy_windows_stdio\") `。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:122 -msgid "" -":c:var:`!Py_FileSystemDefaultEncoding`, :c:var:`!" -"Py_HasFileSystemDefaultEncoding`: " -"Use :c:member:`PyConfig.filesystem_encoding` " -"or :c:func:`PyConfig_Get(\"filesystem_encoding\") ` instead." -msgstr "" -":c:var:`!Py_FileSystemDefaultEncoding`、:c:var:`!" -"Py_HasFileSystemDefaultEncoding`：請改" -"用 :c:member:`PyConfig.filesystem_encoding` " -"或 :c:func:`PyConfig_Get(\"filesystem_encoding\") `。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:125 -msgid "" -":c:var:`!Py_FileSystemDefaultEncodeErrors`: " -"Use :c:member:`PyConfig.filesystem_errors` " -"or :c:func:`PyConfig_Get(\"filesystem_errors\") ` instead." -msgstr "" -":c:var:`!Py_FileSystemDefaultEncodeErrors`：請改" -"用 :c:member:`PyConfig.filesystem_errors` " -"或 :c:func:`PyConfig_Get(\"filesystem_errors\") `。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:128 -msgid "" -":c:var:`!Py_UTF8Mode`: Use :c:member:`PyPreConfig.utf8_mode` " -"or :c:func:`PyConfig_Get(\"utf8_mode\") ` instead. " -"(see :c:func:`Py_PreInitialize`)" -msgstr "" -":c:var:`!Py_UTF8Mode`：請改用 :c:member:`PyPreConfig.utf8_mode` " -"或 :c:func:`PyConfig_Get(\"utf8_mode\") `。（請參" -"閱 :c:func:`Py_PreInitialize`）" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:133 -msgid "" -"The :c:func:`Py_InitializeFromConfig` API should be used " -"with :c:type:`PyConfig` to set these options. Or :c:func:`PyConfig_Get` can " -"be used to get these options at runtime." -msgstr "" -"應改用帶有 :c:type:`PyConfig` 的 :c:func:`Py_InitializeFromConfig` API 來設定" -"這些選項。或者也可以使用 :c:func:`PyConfig_Get` 在執行時取得這些選項。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \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" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:2 +msgid "Pending removal in Python 3.15" +msgstr "Python 3.15 中待移除的項目" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:4 +msgid "" +"The :c:func:`PyImport_ImportModuleNoBlock`: " +"Use :c:func:`PyImport_ImportModule` instead." +msgstr "" +":c:func:`PyImport_ImportModuleNoBlock`：請改" +"用 :c:func:`PyImport_ImportModule`。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:6 +msgid "" +":c:func:`PyWeakref_GetObject` and :c:func:`PyWeakref_GET_OBJECT`: " +"Use :c:func:`PyWeakref_GetRef` instead. The `pythoncapi-compat project " +"`__ can be used to " +"get :c:func:`PyWeakref_GetRef` on Python 3.12 and older." +msgstr "" +":c:func:`PyWeakref_GetObject` 和 :c:func:`PyWeakref_GET_OBJECT`：請改" +"用 :c:func:`PyWeakref_GetRef`。可以使用 `pythoncapi-compat 專案 `__\\ 來為 Python 3.12 和更早版本取" +"得 :c:func:`PyWeakref_GetRef`。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:10 +msgid "" +":c:type:`Py_UNICODE` type and the :c:macro:`!Py_UNICODE_WIDE` macro: " +"Use :c:type:`wchar_t` instead." +msgstr "" +":c:type:`Py_UNICODE` 型別與 :c:macro:`!Py_UNICODE_WIDE` 巨集：請改" +"用 :c:type:`wchar_t`。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:12 +msgid "" +":c:func:`!PyUnicode_AsDecodedObject`: Use :c:func:`PyCodec_Decode` instead." +msgstr "" +":c:func:`!PyUnicode_AsDecodedObject`：請改用 :c:func:`PyCodec_Decode`。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:14 +msgid "" +":c:func:`!PyUnicode_AsDecodedUnicode`: Use :c:func:`PyCodec_Decode` instead; " +"Note that some codecs (for example, \"base64\") may return a type other " +"than :class:`str`, such as :class:`bytes`." +msgstr "" +":c:func:`!PyUnicode_AsDecodedUnicode`：請改用 :c:func:`PyCodec_Decode`；請注" +"意某些編解碼器（例如 \"base64\"）可能會回傳非 :class:`str` 的型別，例" +"如 :class:`bytes`。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:17 +msgid "" +":c:func:`!PyUnicode_AsEncodedObject`: Use :c:func:`PyCodec_Encode` instead." +msgstr "" +":c:func:`!PyUnicode_AsEncodedObject`：請改用 :c:func:`PyCodec_Encode`。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:19 +msgid "" +":c:func:`!PyUnicode_AsEncodedUnicode`: Use :c:func:`PyCodec_Encode` instead; " +"Note that some codecs (for example, \"base64\") may return a type other " +"than :class:`bytes`, such as :class:`str`." +msgstr "" +":c:func:`!PyUnicode_AsEncodedUnicode`：請改用 :c:func:`PyCodec_Encode`；請注" +"意某些編解碼器（例如 \"base64\"）可能會回傳非 :class:`bytes` 的型別，例" +"如 :class:`str`。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:22 +msgid "Python initialization functions, deprecated in Python 3.13:" +msgstr "Python 初始化函式，自 Python 3.13 起已被棄用：" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:24 +msgid "" +":c:func:`Py_GetPath`: Use :c:func:`PyConfig_Get(\"module_search_paths\") " +"` (:data:`sys.path`) instead." +msgstr "" +":c:func:`Py_GetPath`：請改用 :c:func:`PyConfig_Get(\"module_search_paths\") " +"` (:data:`sys.path`)。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:27 +msgid "" +":c:func:`Py_GetPrefix`: Use :c:func:`PyConfig_Get(\"base_prefix\") " +"` (:data:`sys.base_prefix`) instead. " +"Use :c:func:`PyConfig_Get(\"prefix\") ` (:data:`sys.prefix`) " +"if :ref:`virtual environments ` need to be handled." +msgstr "" +":c:func:`Py_GetPrefix`：請改用 :c:func:`PyConfig_Get(\"base_prefix\") " +"` (:data:`sys.base_prefix`)。如果需要處理\\ :ref:`虛擬環境 " +"`，請改用 :c:func:`PyConfig_Get(\"prefix\") ` " +"(:data:`sys.prefix`)。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:32 +msgid "" +":c:func:`Py_GetExecPrefix`: Use :c:func:`PyConfig_Get(\"base_exec_prefix\") " +"` (:data:`sys.base_exec_prefix`) instead. " +"Use :c:func:`PyConfig_Get(\"exec_prefix\") ` " +"(:data:`sys.exec_prefix`) if :ref:`virtual environments ` need to " +"be handled." +msgstr "" +":c:func:`Py_GetExecPrefix`：請改" +"用 :c:func:`PyConfig_Get(\"base_exec_prefix\") ` " +"(:data:`sys.base_exec_prefix`)。如果需要處理\\ :ref:`虛擬環境 `，請" +"改用 :c:func:`PyConfig_Get(\"exec_prefix\") ` " +"(:data:`sys.exec_prefix`)。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:38 +msgid "" +":c:func:`Py_GetProgramFullPath`: Use :c:func:`PyConfig_Get(\"executable\") " +"` (:data:`sys.executable`) instead." +msgstr "" +":c:func:`Py_GetProgramFullPath`：請改" +"用 :c:func:`PyConfig_Get(\"executable\") ` " +"(:data:`sys.executable`)。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:41 +msgid "" +":c:func:`Py_GetProgramName`: Use :c:func:`PyConfig_Get(\"executable\") " +"` (:data:`sys.executable`) instead." +msgstr "" +":c:func:`Py_GetProgramName`：請改用 :c:func:`PyConfig_Get(\"executable\") " +"` (:data:`sys.executable`)。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:44 +msgid "" +":c:func:`Py_GetPythonHome`: Use :c:func:`PyConfig_Get(\"home\") " +"` or the :envvar:`PYTHONHOME` environment variable instead." +msgstr "" +":c:func:`Py_GetPythonHome`：請改用 :c:func:`PyConfig_Get(\"home\") " +"` 或 :envvar:`PYTHONHOME` 環境變數。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:48 +msgid "" +"The `pythoncapi-compat project `__ can be used to get :c:func:`PyConfig_Get` on Python 3.13 and older." +msgstr "" +"`pythoncapi-compat 專案 `__ 可" +"以用來為 Python 3.13 和更早版本取得 :c:func:`PyConfig_Get`。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:52 +msgid "" +"Functions to configure Python's initialization, deprecated in Python 3.11:" +msgstr "用於配置 Python 初始化的函式，自 Python 3.11 起已被棄用：" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:54 +msgid ":c:func:`!PySys_SetArgvEx()`: Set :c:member:`PyConfig.argv` instead." +msgstr ":c:func:`!PySys_SetArgvEx()`：請改用 :c:member:`PyConfig.argv`。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:56 +msgid ":c:func:`!PySys_SetArgv()`: Set :c:member:`PyConfig.argv` instead." +msgstr ":c:func:`!PySys_SetArgv()`：請改用 :c:member:`PyConfig.argv`。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:58 +msgid "" +":c:func:`!Py_SetProgramName()`: Set :c:member:`PyConfig.program_name` " +"instead." +msgstr "" +":c:func:`!Py_SetProgramName()`：請改用 :c:member:`PyConfig.program_name`。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:60 +msgid ":c:func:`!Py_SetPythonHome()`: Set :c:member:`PyConfig.home` instead." +msgstr ":c:func:`!Py_SetPythonHome()`：請改用 :c:member:`PyConfig.home`。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:62 +msgid "" +":c:func:`PySys_ResetWarnOptions`: Clear :data:`sys.warnoptions` and :data:`!" +"warnings.filters` instead." +msgstr "" +":c:func:`PySys_ResetWarnOptions`：請改為清除 :data:`sys.warnoptions` " +"和 :data:`!warnings.filters`。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:65 +msgid "" +"The :c:func:`Py_InitializeFromConfig` API should be used " +"with :c:type:`PyConfig` instead." +msgstr "" +"應改用帶有 :c:type:`PyConfig` 的 :c:func:`Py_InitializeFromConfig` API。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:68 +msgid "Global configuration variables:" +msgstr "全域配置變數：" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:70 +msgid "" +":c:var:`Py_DebugFlag`: Use :c:member:`PyConfig.parser_debug` " +"or :c:func:`PyConfig_Get(\"parser_debug\") ` instead." +msgstr "" +":c:var:`Py_DebugFlag`：請改用 :c:member:`PyConfig.parser_debug` " +"或 :c:func:`PyConfig_Get(\"parser_debug\") `。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:73 +msgid "" +":c:var:`Py_VerboseFlag`: Use :c:member:`PyConfig.verbose` " +"or :c:func:`PyConfig_Get(\"verbose\") ` instead." +msgstr "" +":c:var:`Py_VerboseFlag`：請改用 :c:member:`PyConfig.verbose` " +"或 :c:func:`PyConfig_Get(\"verbose\") `。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:76 +msgid "" +":c:var:`Py_QuietFlag`: Use :c:member:`PyConfig.quiet` " +"or :c:func:`PyConfig_Get(\"quiet\") ` instead." +msgstr "" +":c:var:`Py_QuietFlag`：請改用 :c:member:`PyConfig.quiet` " +"或 :c:func:`PyConfig_Get(\"quiet\") `。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:79 +msgid "" +":c:var:`Py_InteractiveFlag`: Use :c:member:`PyConfig.interactive` " +"or :c:func:`PyConfig_Get(\"interactive\") ` instead." +msgstr "" +":c:var:`Py_InteractiveFlag`：請改用 :c:member:`PyConfig.interactive` " +"或 :c:func:`PyConfig_Get(\"interactive\") `。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:82 +msgid "" +":c:var:`Py_InspectFlag`: Use :c:member:`PyConfig.inspect` " +"or :c:func:`PyConfig_Get(\"inspect\") ` instead." +msgstr "" +":c:var:`Py_InspectFlag`：請改用 :c:member:`PyConfig.inspect` " +"或 :c:func:`PyConfig_Get(\"inspect\") `。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:85 +msgid "" +":c:var:`Py_OptimizeFlag`: Use :c:member:`PyConfig.optimization_level` " +"or :c:func:`PyConfig_Get(\"optimization_level\") ` instead." +msgstr "" +":c:var:`Py_OptimizeFlag`：請改用 :c:member:`PyConfig.optimization_level` " +"或 :c:func:`PyConfig_Get(\"optimization_level\") `。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:88 +msgid "" +":c:var:`Py_NoSiteFlag`: Use :c:member:`PyConfig.site_import` " +"or :c:func:`PyConfig_Get(\"site_import\") ` instead." +msgstr "" +":c:var:`Py_NoSiteFlag`：請改用 :c:member:`PyConfig.site_import` " +"或 :c:func:`PyConfig_Get(\"site_import\") `。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:91 +msgid "" +":c:var:`Py_BytesWarningFlag`: Use :c:member:`PyConfig.bytes_warning` " +"or :c:func:`PyConfig_Get(\"bytes_warning\") ` instead." +msgstr "" +":c:var:`Py_BytesWarningFlag`：請改用 :c:member:`PyConfig.bytes_warning` " +"或 :c:func:`PyConfig_Get(\"bytes_warning\") `。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:94 +msgid "" +":c:var:`Py_FrozenFlag`: Use :c:member:`PyConfig.pathconfig_warnings` " +"or :c:func:`PyConfig_Get(\"pathconfig_warnings\") ` instead." +msgstr "" +":c:var:`Py_FrozenFlag`：請改用 :c:member:`PyConfig.pathconfig_warnings` " +"或 :c:func:`PyConfig_Get(\"pathconfig_warnings\") `。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:97 +msgid "" +":c:var:`Py_IgnoreEnvironmentFlag`: Use :c:member:`PyConfig.use_environment` " +"or :c:func:`PyConfig_Get(\"use_environment\") ` instead." +msgstr "" +":c:var:`Py_IgnoreEnvironmentFlag`：請改" +"用 :c:member:`PyConfig.use_environment` " +"或 :c:func:`PyConfig_Get(\"use_environment\") `。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:100 +msgid "" +":c:var:`Py_DontWriteBytecodeFlag`: Use :c:member:`PyConfig.write_bytecode` " +"or :c:func:`PyConfig_Get(\"write_bytecode\") ` instead." +msgstr "" +":c:var:`Py_DontWriteBytecodeFlag`：請改" +"用 :c:member:`PyConfig.write_bytecode` " +"或 :c:func:`PyConfig_Get(\"write_bytecode\") `。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:103 +msgid "" +":c:var:`Py_NoUserSiteDirectory`: " +"Use :c:member:`PyConfig.user_site_directory` " +"or :c:func:`PyConfig_Get(\"user_site_directory\") ` instead." +msgstr "" +":c:var:`Py_NoUserSiteDirectory`：請改" +"用 :c:member:`PyConfig.user_site_directory` " +"或 :c:func:`PyConfig_Get(\"user_site_directory\") `。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:106 +msgid "" +":c:var:`Py_UnbufferedStdioFlag`: Use :c:member:`PyConfig.buffered_stdio` " +"or :c:func:`PyConfig_Get(\"buffered_stdio\") ` instead." +msgstr "" +":c:var:`Py_UnbufferedStdioFlag`：請改用 :c:member:`PyConfig.buffered_stdio` " +"或 :c:func:`PyConfig_Get(\"buffered_stdio\") `。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:109 +msgid "" +":c:var:`Py_HashRandomizationFlag`: Use :c:member:`PyConfig.use_hash_seed` " +"and :c:member:`PyConfig.hash_seed` or :c:func:`PyConfig_Get(\"hash_seed\") " +"` instead." +msgstr "" +":c:var:`Py_HashRandomizationFlag`：請改用 :c:member:`PyConfig.use_hash_seed` " +"和 :c:member:`PyConfig.hash_seed` 或 :c:func:`PyConfig_Get(\"hash_seed\") " +"`。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:113 +msgid "" +":c:var:`Py_IsolatedFlag`: Use :c:member:`PyConfig.isolated` " +"or :c:func:`PyConfig_Get(\"isolated\") ` instead." +msgstr "" +":c:var:`Py_IsolatedFlag`：請改用 :c:member:`PyConfig.isolated` " +"或 :c:func:`PyConfig_Get(\"isolated\") `。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:116 +msgid "" +":c:var:`Py_LegacyWindowsFSEncodingFlag`: " +"Use :c:member:`PyPreConfig.legacy_windows_fs_encoding` " +"or :c:func:`PyConfig_Get(\"legacy_windows_fs_encoding\") ` " +"instead." +msgstr "" +":c:var:`Py_LegacyWindowsFSEncodingFlag`：請改" +"用 :c:member:`PyPreConfig.legacy_windows_fs_encoding` " +"或 :c:func:`PyConfig_Get(\"legacy_windows_fs_encoding\") `。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:119 +msgid "" +":c:var:`Py_LegacyWindowsStdioFlag`: " +"Use :c:member:`PyConfig.legacy_windows_stdio` " +"or :c:func:`PyConfig_Get(\"legacy_windows_stdio\") ` instead." +msgstr "" +":c:var:`Py_LegacyWindowsStdioFlag`：請改" +"用 :c:member:`PyConfig.legacy_windows_stdio` " +"或 :c:func:`PyConfig_Get(\"legacy_windows_stdio\") `。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:122 +msgid "" +":c:var:`!Py_FileSystemDefaultEncoding`, :c:var:`!" +"Py_HasFileSystemDefaultEncoding`: " +"Use :c:member:`PyConfig.filesystem_encoding` " +"or :c:func:`PyConfig_Get(\"filesystem_encoding\") ` instead." +msgstr "" +":c:var:`!Py_FileSystemDefaultEncoding`、:c:var:`!" +"Py_HasFileSystemDefaultEncoding`：請改" +"用 :c:member:`PyConfig.filesystem_encoding` " +"或 :c:func:`PyConfig_Get(\"filesystem_encoding\") `。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:125 +msgid "" +":c:var:`!Py_FileSystemDefaultEncodeErrors`: " +"Use :c:member:`PyConfig.filesystem_errors` " +"or :c:func:`PyConfig_Get(\"filesystem_errors\") ` instead." +msgstr "" +":c:var:`!Py_FileSystemDefaultEncodeErrors`：請改" +"用 :c:member:`PyConfig.filesystem_errors` " +"或 :c:func:`PyConfig_Get(\"filesystem_errors\") `。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:128 +msgid "" +":c:var:`!Py_UTF8Mode`: Use :c:member:`PyPreConfig.utf8_mode` " +"or :c:func:`PyConfig_Get(\"utf8_mode\") ` instead. " +"(see :c:func:`Py_PreInitialize`)" +msgstr "" +":c:var:`!Py_UTF8Mode`：請改用 :c:member:`PyPreConfig.utf8_mode` " +"或 :c:func:`PyConfig_Get(\"utf8_mode\") `。（請參" +"閱 :c:func:`Py_PreInitialize`）" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:133 +msgid "" +"The :c:func:`Py_InitializeFromConfig` API should be used " +"with :c:type:`PyConfig` to set these options. Or :c:func:`PyConfig_Get` can " +"be used to get these options at runtime." +msgstr "" +"應改用帶有 :c:type:`PyConfig` 的 :c:func:`Py_InitializeFromConfig` API 來設定" +"這些選項。或者也可以使用 :c:func:`PyConfig_Get` 在執行時取得這些選項。" diff --git a/deprecations/c-api-pending-removal-in-3.16.po b/deprecations/c-api-pending-removal-in-3.16.po index f6d770d35a..80879dfc50 100644 --- a/deprecations/c-api-pending-removal-in-3.16.po +++ b/deprecations/c-api-pending-removal-in-3.16.po @@ -1,24 +1,24 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-07-03 00:17+0000\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \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" - -#: ../../deprecations/c-api-pending-removal-in-3.16.rst:2 -msgid "Pending removal in Python 3.16" -msgstr "Python 3.16 中待移除的項目" - -#: ../../deprecations/c-api-pending-removal-in-3.16.rst:4 -msgid "The bundled copy of ``libmpdec``." -msgstr "``libmpdecimal`` 的打包副本 (bundled copy)。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-07-03 00:17+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \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" + +#: ../../deprecations/c-api-pending-removal-in-3.16.rst:2 +msgid "Pending removal in Python 3.16" +msgstr "Python 3.16 中待移除的項目" + +#: ../../deprecations/c-api-pending-removal-in-3.16.rst:4 +msgid "The bundled copy of ``libmpdec``." +msgstr "``libmpdecimal`` 的打包副本 (bundled copy)。" diff --git a/deprecations/c-api-pending-removal-in-3.18.po b/deprecations/c-api-pending-removal-in-3.18.po index 458022f9a8..eb102ea310 100644 --- a/deprecations/c-api-pending-removal-in-3.18.po +++ b/deprecations/c-api-pending-removal-in-3.18.po @@ -1,172 +1,172 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# FIRST AUTHOR , YEAR. -# -#, fuzzy -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-18 00:15+0000\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language-Team: LANGUAGE \n" -"Language: zh_TW\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=UTF-8\n" -"Content-Transfer-Encoding: 8bit\n" - -#: ../../deprecations/c-api-pending-removal-in-3.18.rst:2 -msgid "Pending removal in Python 3.18" -msgstr "Python 3.18 中待移除的項目" - -#: ../../deprecations/c-api-pending-removal-in-3.18.rst:4 -msgid "" -"The following private functions are deprecated and planned for removal in " -"Python 3.18:" -msgstr "以下私有函式已被棄用，並計劃在 Python 3.18 中移除：" - -#: ../../deprecations/c-api-pending-removal-in-3.18.rst:7 -msgid ":c:func:`!_PyBytes_Join`: use :c:func:`PyBytes_Join`." -msgstr ":c:func:`!_PyBytes_Join`：請改用 :c:func:`PyBytes_Join`。" - -#: ../../deprecations/c-api-pending-removal-in-3.18.rst:8 -msgid "" -":c:func:`!_PyDict_GetItemStringWithError`: use :c:func:" -"`PyDict_GetItemStringRef`." -msgstr "" -":c:func:`!_PyDict_GetItemStringWithError`：請改用 :c:func:" -"`PyDict_GetItemStringRef`。" - -#: ../../deprecations/c-api-pending-removal-in-3.18.rst:9 -msgid ":c:func:`!_PyDict_Pop()`: use :c:func:`PyDict_Pop`." -msgstr ":c:func:`!_PyDict_Pop()`：請改用 :c:func:`PyDict_Pop`。" - -#: ../../deprecations/c-api-pending-removal-in-3.18.rst:10 -msgid ":c:func:`!_PyLong_Sign()`: use :c:func:`PyLong_GetSign`." -msgstr ":c:func:`!_PyLong_Sign()`：請改用 :c:func:`PyLong_GetSign`。" - -#: ../../deprecations/c-api-pending-removal-in-3.18.rst:11 -msgid "" -":c:func:`!_PyLong_FromDigits` and :c:func:`!_PyLong_New`: use :c:func:" -"`PyLongWriter_Create`." -msgstr "" -":c:func:`!_PyLong_FromDigits` 和 :c:func:`!_PyLong_New`：請改用 :c:func:" -"`PyLongWriter_Create`。" - -#: ../../deprecations/c-api-pending-removal-in-3.18.rst:13 -msgid "" -":c:func:`!_PyThreadState_UncheckedGet`: use :c:func:" -"`PyThreadState_GetUnchecked`." -msgstr "" -":c:func:`!_PyThreadState_UncheckedGet`：請改用 :c:func:" -"`PyThreadState_GetUnchecked`。" - -#: ../../deprecations/c-api-pending-removal-in-3.18.rst:14 -msgid ":c:func:`!_PyUnicode_AsString`: use :c:func:`PyUnicode_AsUTF8`." -msgstr ":c:func:`!_PyUnicode_AsString`：請改用 :c:func:`PyUnicode_AsUTF8`。" - -#: ../../deprecations/c-api-pending-removal-in-3.18.rst:15 -msgid "" -":c:func:`!_PyUnicodeWriter_Init`: replace ``_PyUnicodeWriter_Init(&writer)`` " -"with :c:func:`writer = PyUnicodeWriter_Create(0) `." -msgstr "" -":c:func:`!_PyUnicodeWriter_Init`：將 ``_PyUnicodeWriter_Init(&writer)`` 替換" -"為 :c:func:`writer = PyUnicodeWriter_Create(0) `。" - -#: ../../deprecations/c-api-pending-removal-in-3.18.rst:18 -msgid "" -":c:func:`!_PyUnicodeWriter_Finish`: replace " -"``_PyUnicodeWriter_Finish(&writer)`` with :c:func:" -"`PyUnicodeWriter_Finish(writer) `." -msgstr "" -":c:func:`!_PyUnicodeWriter_Finish`：將 ``_PyUnicodeWriter_Finish(&writer)`` " -"替換為 :c:func:`PyUnicodeWriter_Finish(writer) `。" - -#: ../../deprecations/c-api-pending-removal-in-3.18.rst:21 -msgid "" -":c:func:`!_PyUnicodeWriter_Dealloc`: replace " -"``_PyUnicodeWriter_Dealloc(&writer)`` with :c:func:" -"`PyUnicodeWriter_Discard(writer) `." -msgstr "" -":c:func:`!_PyUnicodeWriter_Dealloc`：將 " -"``_PyUnicodeWriter_Dealloc(&writer)`` 替換為 :c:func:" -"`PyUnicodeWriter_Discard(writer) `。" - -#: ../../deprecations/c-api-pending-removal-in-3.18.rst:24 -msgid "" -":c:func:`!_PyUnicodeWriter_WriteChar`: replace " -"``_PyUnicodeWriter_WriteChar(&writer, ch)`` with :c:func:" -"`PyUnicodeWriter_WriteChar(writer, ch) `." -msgstr "" -":c:func:`!_PyUnicodeWriter_WriteChar`：將 " -"``_PyUnicodeWriter_WriteChar(&writer, ch)`` 替換為 :c:func:" -"`PyUnicodeWriter_WriteChar(writer, ch) `。" - -#: ../../deprecations/c-api-pending-removal-in-3.18.rst:27 -msgid "" -":c:func:`!_PyUnicodeWriter_WriteStr`: replace " -"``_PyUnicodeWriter_WriteStr(&writer, str)`` with :c:func:" -"`PyUnicodeWriter_WriteStr(writer, str) `." -msgstr "" -":c:func:`!_PyUnicodeWriter_WriteStr`：將 " -"``_PyUnicodeWriter_WriteStr(&writer, str)`` 替換為 :c:func:" -"`PyUnicodeWriter_WriteStr(writer, str) `。" - -#: ../../deprecations/c-api-pending-removal-in-3.18.rst:30 -msgid "" -":c:func:`!_PyUnicodeWriter_WriteSubstring`: replace " -"``_PyUnicodeWriter_WriteSubstring(&writer, str, start, end)`` with :c:func:" -"`PyUnicodeWriter_WriteSubstring(writer, str, start, end) " -"`." -msgstr "" -":c:func:`!_PyUnicodeWriter_WriteSubstring`：將 " -"``_PyUnicodeWriter_WriteSubstring(&writer, str, start, end)`` 替換為 :c:func:" -"`PyUnicodeWriter_WriteSubstring(writer, str, start, end) " -"`。" - -#: ../../deprecations/c-api-pending-removal-in-3.18.rst:33 -msgid "" -":c:func:`!_PyUnicodeWriter_WriteASCIIString`: replace " -"``_PyUnicodeWriter_WriteASCIIString(&writer, str)`` with :c:func:" -"`PyUnicodeWriter_WriteASCII(writer, str) `." -msgstr "" -":c:func:`!_PyUnicodeWriter_WriteASCIIString`：將 " -"``_PyUnicodeWriter_WriteASCIIString(&writer, str)`` 替換為 :c:func:" -"`PyUnicodeWriter_WriteASCII(writer, str) `。" - -#: ../../deprecations/c-api-pending-removal-in-3.18.rst:36 -msgid "" -":c:func:`!_PyUnicodeWriter_WriteLatin1String`: replace " -"``_PyUnicodeWriter_WriteLatin1String(&writer, str)`` with :c:func:" -"`PyUnicodeWriter_WriteUTF8(writer, str) `." -msgstr "" -":c:func:`!_PyUnicodeWriter_WriteLatin1String`：將 " -"``_PyUnicodeWriter_WriteLatin1String(&writer, str)`` 替換為 :c:func:" -"`PyUnicodeWriter_WriteUTF8(writer, str) `。" - -#: ../../deprecations/c-api-pending-removal-in-3.18.rst:39 -msgid ":c:func:`!_PyUnicodeWriter_Prepare`: (no replacement)." -msgstr ":c:func:`!_PyUnicodeWriter_Prepare`：（無替代方案）。" - -#: ../../deprecations/c-api-pending-removal-in-3.18.rst:40 -msgid ":c:func:`!_PyUnicodeWriter_PrepareKind`: (no replacement)." -msgstr ":c:func:`!_PyUnicodeWriter_PrepareKind`：（無替代方案）。" - -#: ../../deprecations/c-api-pending-removal-in-3.18.rst:41 -msgid ":c:func:`!_Py_HashPointer`: use :c:func:`Py_HashPointer`." -msgstr ":c:func:`!_Py_HashPointer`：請改用 :c:func:`Py_HashPointer`。" - -#: ../../deprecations/c-api-pending-removal-in-3.18.rst:42 -msgid ":c:func:`!_Py_fopen_obj`: use :c:func:`Py_fopen`." -msgstr ":c:func:`!_Py_fopen_obj`：請改用 :c:func:`Py_fopen`。" - -#: ../../deprecations/c-api-pending-removal-in-3.18.rst:44 -msgid "" -"The `pythoncapi-compat project `__ can be used to get these new public functions on Python 3.13 and older. " -"(Contributed by Victor Stinner in :gh:`128863`.)" -msgstr "" -"可以使用 `pythoncapi-compat project `__ 來取得這些於 Python 3.13 及更早版本的新公開函式。（由 " -"Victor Stinner 在 :gh:`128863` 貢獻）" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-18 00:15+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"Language: zh_TW\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../deprecations/c-api-pending-removal-in-3.18.rst:2 +msgid "Pending removal in Python 3.18" +msgstr "Python 3.18 中待移除的項目" + +#: ../../deprecations/c-api-pending-removal-in-3.18.rst:4 +msgid "" +"The following private functions are deprecated and planned for removal in " +"Python 3.18:" +msgstr "以下私有函式已被棄用，並計劃在 Python 3.18 中移除：" + +#: ../../deprecations/c-api-pending-removal-in-3.18.rst:7 +msgid ":c:func:`!_PyBytes_Join`: use :c:func:`PyBytes_Join`." +msgstr ":c:func:`!_PyBytes_Join`：請改用 :c:func:`PyBytes_Join`。" + +#: ../../deprecations/c-api-pending-removal-in-3.18.rst:8 +msgid "" +":c:func:`!_PyDict_GetItemStringWithError`: use :c:func:" +"`PyDict_GetItemStringRef`." +msgstr "" +":c:func:`!_PyDict_GetItemStringWithError`：請改用 :c:func:" +"`PyDict_GetItemStringRef`。" + +#: ../../deprecations/c-api-pending-removal-in-3.18.rst:9 +msgid ":c:func:`!_PyDict_Pop()`: use :c:func:`PyDict_Pop`." +msgstr ":c:func:`!_PyDict_Pop()`：請改用 :c:func:`PyDict_Pop`。" + +#: ../../deprecations/c-api-pending-removal-in-3.18.rst:10 +msgid ":c:func:`!_PyLong_Sign()`: use :c:func:`PyLong_GetSign`." +msgstr ":c:func:`!_PyLong_Sign()`：請改用 :c:func:`PyLong_GetSign`。" + +#: ../../deprecations/c-api-pending-removal-in-3.18.rst:11 +msgid "" +":c:func:`!_PyLong_FromDigits` and :c:func:`!_PyLong_New`: use :c:func:" +"`PyLongWriter_Create`." +msgstr "" +":c:func:`!_PyLong_FromDigits` 和 :c:func:`!_PyLong_New`：請改用 :c:func:" +"`PyLongWriter_Create`。" + +#: ../../deprecations/c-api-pending-removal-in-3.18.rst:13 +msgid "" +":c:func:`!_PyThreadState_UncheckedGet`: use :c:func:" +"`PyThreadState_GetUnchecked`." +msgstr "" +":c:func:`!_PyThreadState_UncheckedGet`：請改用 :c:func:" +"`PyThreadState_GetUnchecked`。" + +#: ../../deprecations/c-api-pending-removal-in-3.18.rst:14 +msgid ":c:func:`!_PyUnicode_AsString`: use :c:func:`PyUnicode_AsUTF8`." +msgstr ":c:func:`!_PyUnicode_AsString`：請改用 :c:func:`PyUnicode_AsUTF8`。" + +#: ../../deprecations/c-api-pending-removal-in-3.18.rst:15 +msgid "" +":c:func:`!_PyUnicodeWriter_Init`: replace ``_PyUnicodeWriter_Init(&writer)`` " +"with :c:func:`writer = PyUnicodeWriter_Create(0) `." +msgstr "" +":c:func:`!_PyUnicodeWriter_Init`：將 ``_PyUnicodeWriter_Init(&writer)`` 替換" +"為 :c:func:`writer = PyUnicodeWriter_Create(0) `。" + +#: ../../deprecations/c-api-pending-removal-in-3.18.rst:18 +msgid "" +":c:func:`!_PyUnicodeWriter_Finish`: replace " +"``_PyUnicodeWriter_Finish(&writer)`` with :c:func:" +"`PyUnicodeWriter_Finish(writer) `." +msgstr "" +":c:func:`!_PyUnicodeWriter_Finish`：將 ``_PyUnicodeWriter_Finish(&writer)`` " +"替換為 :c:func:`PyUnicodeWriter_Finish(writer) `。" + +#: ../../deprecations/c-api-pending-removal-in-3.18.rst:21 +msgid "" +":c:func:`!_PyUnicodeWriter_Dealloc`: replace " +"``_PyUnicodeWriter_Dealloc(&writer)`` with :c:func:" +"`PyUnicodeWriter_Discard(writer) `." +msgstr "" +":c:func:`!_PyUnicodeWriter_Dealloc`：將 " +"``_PyUnicodeWriter_Dealloc(&writer)`` 替換為 :c:func:" +"`PyUnicodeWriter_Discard(writer) `。" + +#: ../../deprecations/c-api-pending-removal-in-3.18.rst:24 +msgid "" +":c:func:`!_PyUnicodeWriter_WriteChar`: replace " +"``_PyUnicodeWriter_WriteChar(&writer, ch)`` with :c:func:" +"`PyUnicodeWriter_WriteChar(writer, ch) `." +msgstr "" +":c:func:`!_PyUnicodeWriter_WriteChar`：將 " +"``_PyUnicodeWriter_WriteChar(&writer, ch)`` 替換為 :c:func:" +"`PyUnicodeWriter_WriteChar(writer, ch) `。" + +#: ../../deprecations/c-api-pending-removal-in-3.18.rst:27 +msgid "" +":c:func:`!_PyUnicodeWriter_WriteStr`: replace " +"``_PyUnicodeWriter_WriteStr(&writer, str)`` with :c:func:" +"`PyUnicodeWriter_WriteStr(writer, str) `." +msgstr "" +":c:func:`!_PyUnicodeWriter_WriteStr`：將 " +"``_PyUnicodeWriter_WriteStr(&writer, str)`` 替換為 :c:func:" +"`PyUnicodeWriter_WriteStr(writer, str) `。" + +#: ../../deprecations/c-api-pending-removal-in-3.18.rst:30 +msgid "" +":c:func:`!_PyUnicodeWriter_WriteSubstring`: replace " +"``_PyUnicodeWriter_WriteSubstring(&writer, str, start, end)`` with :c:func:" +"`PyUnicodeWriter_WriteSubstring(writer, str, start, end) " +"`." +msgstr "" +":c:func:`!_PyUnicodeWriter_WriteSubstring`：將 " +"``_PyUnicodeWriter_WriteSubstring(&writer, str, start, end)`` 替換為 :c:func:" +"`PyUnicodeWriter_WriteSubstring(writer, str, start, end) " +"`。" + +#: ../../deprecations/c-api-pending-removal-in-3.18.rst:33 +msgid "" +":c:func:`!_PyUnicodeWriter_WriteASCIIString`: replace " +"``_PyUnicodeWriter_WriteASCIIString(&writer, str)`` with :c:func:" +"`PyUnicodeWriter_WriteASCII(writer, str) `." +msgstr "" +":c:func:`!_PyUnicodeWriter_WriteASCIIString`：將 " +"``_PyUnicodeWriter_WriteASCIIString(&writer, str)`` 替換為 :c:func:" +"`PyUnicodeWriter_WriteASCII(writer, str) `。" + +#: ../../deprecations/c-api-pending-removal-in-3.18.rst:36 +msgid "" +":c:func:`!_PyUnicodeWriter_WriteLatin1String`: replace " +"``_PyUnicodeWriter_WriteLatin1String(&writer, str)`` with :c:func:" +"`PyUnicodeWriter_WriteUTF8(writer, str) `." +msgstr "" +":c:func:`!_PyUnicodeWriter_WriteLatin1String`：將 " +"``_PyUnicodeWriter_WriteLatin1String(&writer, str)`` 替換為 :c:func:" +"`PyUnicodeWriter_WriteUTF8(writer, str) `。" + +#: ../../deprecations/c-api-pending-removal-in-3.18.rst:39 +msgid ":c:func:`!_PyUnicodeWriter_Prepare`: (no replacement)." +msgstr ":c:func:`!_PyUnicodeWriter_Prepare`：（無替代方案）。" + +#: ../../deprecations/c-api-pending-removal-in-3.18.rst:40 +msgid ":c:func:`!_PyUnicodeWriter_PrepareKind`: (no replacement)." +msgstr ":c:func:`!_PyUnicodeWriter_PrepareKind`：（無替代方案）。" + +#: ../../deprecations/c-api-pending-removal-in-3.18.rst:41 +msgid ":c:func:`!_Py_HashPointer`: use :c:func:`Py_HashPointer`." +msgstr ":c:func:`!_Py_HashPointer`：請改用 :c:func:`Py_HashPointer`。" + +#: ../../deprecations/c-api-pending-removal-in-3.18.rst:42 +msgid ":c:func:`!_Py_fopen_obj`: use :c:func:`Py_fopen`." +msgstr ":c:func:`!_Py_fopen_obj`：請改用 :c:func:`Py_fopen`。" + +#: ../../deprecations/c-api-pending-removal-in-3.18.rst:44 +msgid "" +"The `pythoncapi-compat project `__ can be used to get these new public functions on Python 3.13 and older. " +"(Contributed by Victor Stinner in :gh:`128863`.)" +msgstr "" +"可以使用 `pythoncapi-compat project `__ 來取得這些於 Python 3.13 及更早版本的新公開函式。（由 " +"Victor Stinner 在 :gh:`128863` 貢獻）" diff --git a/deprecations/c-api-pending-removal-in-future.po b/deprecations/c-api-pending-removal-in-future.po index 59952a6fbe..c199ae0f1c 100644 --- a/deprecations/c-api-pending-removal-in-future.po +++ b/deprecations/c-api-pending-removal-in-future.po @@ -1,123 +1,123 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \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" - -#: ../../deprecations/c-api-pending-removal-in-future.rst:2 -msgid "Pending removal in future versions" -msgstr "未來版本中的待移除項目" - -#: ../../deprecations/c-api-pending-removal-in-future.rst:4 -msgid "" -"The following APIs are deprecated and will be removed, although there is " -"currently no date scheduled for their removal." -msgstr "下列 API 已被棄用並將會被移除，不過目前尚未訂定移除日期。" - -#: ../../deprecations/c-api-pending-removal-in-future.rst:7 -msgid ":c:macro:`Py_TPFLAGS_HAVE_FINALIZE`: Unneeded since Python 3.8." -msgstr ":c:macro:`Py_TPFLAGS_HAVE_FINALIZE`：自 Python 3.8 起不再需要" - -#: ../../deprecations/c-api-pending-removal-in-future.rst:9 -msgid ":c:func:`PyErr_Fetch`: Use :c:func:`PyErr_GetRaisedException` instead." -msgstr ":c:func:`PyErr_Fetch`：請改用 :c:func:`PyErr_GetRaisedException`。" - -#: ../../deprecations/c-api-pending-removal-in-future.rst:11 -msgid "" -":c:func:`PyErr_NormalizeException`: Use :c:func:`PyErr_GetRaisedException` " -"instead." -msgstr "" -":c:func:`PyErr_NormalizeException`：請改" -"用 :c:func:`PyErr_GetRaisedException`。" - -#: ../../deprecations/c-api-pending-removal-in-future.rst:13 -msgid "" -":c:func:`PyErr_Restore`: Use :c:func:`PyErr_SetRaisedException` instead." -msgstr ":c:func:`PyErr_Restore`：請改用 :c:func:`PyErr_SetRaisedException`。" - -#: ../../deprecations/c-api-pending-removal-in-future.rst:15 -msgid "" -":c:func:`PyModule_GetFilename`: Use :c:func:`PyModule_GetFilenameObject` " -"instead." -msgstr "" -":c:func:`PyModule_GetFilename`：請改用 :c:func:`PyModule_GetFilenameObject`。" - -#: ../../deprecations/c-api-pending-removal-in-future.rst:17 -msgid ":c:func:`PyOS_AfterFork`: Use :c:func:`PyOS_AfterFork_Child` instead." -msgstr ":c:func:`PyOS_AfterFork`：請改用 :c:func:`PyOS_AfterFork_Child`。" - -#: ../../deprecations/c-api-pending-removal-in-future.rst:19 -msgid "" -":c:func:`PySlice_GetIndicesEx`: Use :c:func:`PySlice_Unpack` " -"and :c:func:`PySlice_AdjustIndices` instead." -msgstr "" -":c:func:`PySlice_GetIndicesEx`：請改用 :c:func:`PySlice_Unpack` " -"和 :c:func:`PySlice_AdjustIndices`。" - -#: ../../deprecations/c-api-pending-removal-in-future.rst:21 -msgid ":c:func:`PyUnicode_READY`: Unneeded since Python 3.12" -msgstr ":c:func:`PyUnicode_READY`：自 Python 3.12 起不再需要" - -#: ../../deprecations/c-api-pending-removal-in-future.rst:23 -msgid ":c:func:`!PyErr_Display`: Use :c:func:`PyErr_DisplayException` instead." -msgstr ":c:func:`!PyErr_Display`：請改用 :c:func:`PyErr_DisplayException`。" - -#: ../../deprecations/c-api-pending-removal-in-future.rst:25 -msgid "" -":c:func:`!_PyErr_ChainExceptions`: Use :c:func:`!_PyErr_ChainExceptions1` " -"instead." -msgstr "" -":c:func:`!_PyErr_ChainExceptions`：請改用 ``_PyErr_ChainExceptions1``。" - -#: ../../deprecations/c-api-pending-removal-in-future.rst:27 -msgid "" -":c:member:`!PyBytesObject.ob_shash` member: call :c:func:`PyObject_Hash` " -"instead." -msgstr "" -":c:member:`!PyBytesObject.ob_shash` 成員：請改為呼" -"叫 :c:func:`PyObject_Hash`。" - -#: ../../deprecations/c-api-pending-removal-in-future.rst:29 -msgid "Thread Local Storage (TLS) API:" -msgstr "執行緒局部儲存 (Thread Local Storage, TLS) API：" - -#: ../../deprecations/c-api-pending-removal-in-future.rst:31 -msgid "" -":c:func:`PyThread_create_key`: Use :c:func:`PyThread_tss_alloc` instead." -msgstr ":c:func:`PyThread_create_key`：請改用 :c:func:`PyThread_tss_alloc`。" - -#: ../../deprecations/c-api-pending-removal-in-future.rst:33 -msgid ":c:func:`PyThread_delete_key`: Use :c:func:`PyThread_tss_free` instead." -msgstr ":c:func:`PyThread_delete_key`：請改用 :c:func:`PyThread_tss_free`。" - -#: ../../deprecations/c-api-pending-removal-in-future.rst:35 -msgid "" -":c:func:`PyThread_set_key_value`: Use :c:func:`PyThread_tss_set` instead." -msgstr ":c:func:`PyThread_set_key_value`：請改用 :c:func:`PyThread_tss_set`。" - -#: ../../deprecations/c-api-pending-removal-in-future.rst:37 -msgid "" -":c:func:`PyThread_get_key_value`: Use :c:func:`PyThread_tss_get` instead." -msgstr ":c:func:`PyThread_get_key_value`：請改用 :c:func:`PyThread_tss_get`。" - -#: ../../deprecations/c-api-pending-removal-in-future.rst:39 -msgid "" -":c:func:`PyThread_delete_key_value`: Use :c:func:`PyThread_tss_delete` " -"instead." -msgstr "" -":c:func:`PyThread_delete_key_value`：請改用 :c:func:`PyThread_tss_delete`。" - -#: ../../deprecations/c-api-pending-removal-in-future.rst:41 -msgid ":c:func:`PyThread_ReInitTLS`: Unneeded since Python 3.7." -msgstr ":c:func:`PyThread_ReInitTLS`：自 Python 3.7 起不再需要。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \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" + +#: ../../deprecations/c-api-pending-removal-in-future.rst:2 +msgid "Pending removal in future versions" +msgstr "未來版本中的待移除項目" + +#: ../../deprecations/c-api-pending-removal-in-future.rst:4 +msgid "" +"The following APIs are deprecated and will be removed, although there is " +"currently no date scheduled for their removal." +msgstr "下列 API 已被棄用並將會被移除，不過目前尚未訂定移除日期。" + +#: ../../deprecations/c-api-pending-removal-in-future.rst:7 +msgid ":c:macro:`Py_TPFLAGS_HAVE_FINALIZE`: Unneeded since Python 3.8." +msgstr ":c:macro:`Py_TPFLAGS_HAVE_FINALIZE`：自 Python 3.8 起不再需要" + +#: ../../deprecations/c-api-pending-removal-in-future.rst:9 +msgid ":c:func:`PyErr_Fetch`: Use :c:func:`PyErr_GetRaisedException` instead." +msgstr ":c:func:`PyErr_Fetch`：請改用 :c:func:`PyErr_GetRaisedException`。" + +#: ../../deprecations/c-api-pending-removal-in-future.rst:11 +msgid "" +":c:func:`PyErr_NormalizeException`: Use :c:func:`PyErr_GetRaisedException` " +"instead." +msgstr "" +":c:func:`PyErr_NormalizeException`：請改" +"用 :c:func:`PyErr_GetRaisedException`。" + +#: ../../deprecations/c-api-pending-removal-in-future.rst:13 +msgid "" +":c:func:`PyErr_Restore`: Use :c:func:`PyErr_SetRaisedException` instead." +msgstr ":c:func:`PyErr_Restore`：請改用 :c:func:`PyErr_SetRaisedException`。" + +#: ../../deprecations/c-api-pending-removal-in-future.rst:15 +msgid "" +":c:func:`PyModule_GetFilename`: Use :c:func:`PyModule_GetFilenameObject` " +"instead." +msgstr "" +":c:func:`PyModule_GetFilename`：請改用 :c:func:`PyModule_GetFilenameObject`。" + +#: ../../deprecations/c-api-pending-removal-in-future.rst:17 +msgid ":c:func:`PyOS_AfterFork`: Use :c:func:`PyOS_AfterFork_Child` instead." +msgstr ":c:func:`PyOS_AfterFork`：請改用 :c:func:`PyOS_AfterFork_Child`。" + +#: ../../deprecations/c-api-pending-removal-in-future.rst:19 +msgid "" +":c:func:`PySlice_GetIndicesEx`: Use :c:func:`PySlice_Unpack` " +"and :c:func:`PySlice_AdjustIndices` instead." +msgstr "" +":c:func:`PySlice_GetIndicesEx`：請改用 :c:func:`PySlice_Unpack` " +"和 :c:func:`PySlice_AdjustIndices`。" + +#: ../../deprecations/c-api-pending-removal-in-future.rst:21 +msgid ":c:func:`PyUnicode_READY`: Unneeded since Python 3.12" +msgstr ":c:func:`PyUnicode_READY`：自 Python 3.12 起不再需要" + +#: ../../deprecations/c-api-pending-removal-in-future.rst:23 +msgid ":c:func:`!PyErr_Display`: Use :c:func:`PyErr_DisplayException` instead." +msgstr ":c:func:`!PyErr_Display`：請改用 :c:func:`PyErr_DisplayException`。" + +#: ../../deprecations/c-api-pending-removal-in-future.rst:25 +msgid "" +":c:func:`!_PyErr_ChainExceptions`: Use :c:func:`!_PyErr_ChainExceptions1` " +"instead." +msgstr "" +":c:func:`!_PyErr_ChainExceptions`：請改用 ``_PyErr_ChainExceptions1``。" + +#: ../../deprecations/c-api-pending-removal-in-future.rst:27 +msgid "" +":c:member:`!PyBytesObject.ob_shash` member: call :c:func:`PyObject_Hash` " +"instead." +msgstr "" +":c:member:`!PyBytesObject.ob_shash` 成員：請改為呼" +"叫 :c:func:`PyObject_Hash`。" + +#: ../../deprecations/c-api-pending-removal-in-future.rst:29 +msgid "Thread Local Storage (TLS) API:" +msgstr "執行緒局部儲存 (Thread Local Storage, TLS) API：" + +#: ../../deprecations/c-api-pending-removal-in-future.rst:31 +msgid "" +":c:func:`PyThread_create_key`: Use :c:func:`PyThread_tss_alloc` instead." +msgstr ":c:func:`PyThread_create_key`：請改用 :c:func:`PyThread_tss_alloc`。" + +#: ../../deprecations/c-api-pending-removal-in-future.rst:33 +msgid ":c:func:`PyThread_delete_key`: Use :c:func:`PyThread_tss_free` instead." +msgstr ":c:func:`PyThread_delete_key`：請改用 :c:func:`PyThread_tss_free`。" + +#: ../../deprecations/c-api-pending-removal-in-future.rst:35 +msgid "" +":c:func:`PyThread_set_key_value`: Use :c:func:`PyThread_tss_set` instead." +msgstr ":c:func:`PyThread_set_key_value`：請改用 :c:func:`PyThread_tss_set`。" + +#: ../../deprecations/c-api-pending-removal-in-future.rst:37 +msgid "" +":c:func:`PyThread_get_key_value`: Use :c:func:`PyThread_tss_get` instead." +msgstr ":c:func:`PyThread_get_key_value`：請改用 :c:func:`PyThread_tss_get`。" + +#: ../../deprecations/c-api-pending-removal-in-future.rst:39 +msgid "" +":c:func:`PyThread_delete_key_value`: Use :c:func:`PyThread_tss_delete` " +"instead." +msgstr "" +":c:func:`PyThread_delete_key_value`：請改用 :c:func:`PyThread_tss_delete`。" + +#: ../../deprecations/c-api-pending-removal-in-future.rst:41 +msgid ":c:func:`PyThread_ReInitTLS`: Unneeded since Python 3.7." +msgstr ":c:func:`PyThread_ReInitTLS`：自 Python 3.7 起不再需要。" diff --git a/deprecations/index.po b/deprecations/index.po index 54482a2de1..d51e6f9308 100644 --- a/deprecations/index.po +++ b/deprecations/index.po @@ -1,1615 +1,1615 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2026-01-07 00:14+0000\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \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" - -#: ../../deprecations/index.rst:2 -msgid "Deprecations" -msgstr "已棄用項目" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:2 -#: ../../deprecations/pending-removal-in-3.15.rst:2 -msgid "Pending removal in Python 3.15" -msgstr "Python 3.15 中待移除的項目" - -#: ../../deprecations/pending-removal-in-3.15.rst:4 -#: ../../deprecations/pending-removal-in-3.16.rst:4 -msgid "The import system:" -msgstr "引入系統 (import system)：" - -#: ../../deprecations/pending-removal-in-3.15.rst:6 -msgid "" -"Setting :attr:`~module.__cached__` on a module while failing to set :attr:" -"`__spec__.cached ` is deprecated. In " -"Python 3.15, :attr:`!__cached__` will cease to be set or take into " -"consideration by the import system or standard library. (:gh:`97879`)" -msgstr "" -"在模組上設定 :attr:`~module.__cached__` 而沒有設定 :attr:`__spec__.cached " -"` 的做法已被棄用。在 Python 3.15 中，" -"引入系統或標準函式庫將不再設定或考慮 :attr:`!__cached__`。(:gh:`97879`)" - -#: ../../deprecations/pending-removal-in-3.15.rst:11 -msgid "" -"Setting :attr:`~module.__package__` on a module while failing to set :attr:" -"`__spec__.parent ` is deprecated. In " -"Python 3.15, :attr:`!__package__` will cease to be set or take into " -"consideration by the import system or standard library. (:gh:`97879`)" -msgstr "" -"在模組上設定 :attr:`~module.__package__` 而沒有設定 :attr:`__spec__.parent " -"` 的做法已被棄用。在 Python 3.15 中，" -"引入系統或標準函式庫將不再設定或考慮 :attr:`!__package__`。(:gh:`97879`)" - -#: ../../deprecations/pending-removal-in-3.15.rst:16 -#: ../../deprecations/pending-removal-in-3.19.rst:4 -msgid ":mod:`ctypes`:" -msgstr ":mod:`ctypes`：" - -#: ../../deprecations/pending-removal-in-3.15.rst:18 -msgid "" -"The undocumented :func:`!ctypes.SetPointerType` function has been deprecated " -"since Python 3.13." -msgstr "" -"自 Python 3.13 起，未記錄的 :func:`!ctypes.SetPointerType` 函式已被棄用。" - -#: ../../deprecations/pending-removal-in-3.15.rst:21 -msgid ":mod:`http.server`:" -msgstr ":mod:`http.server`：" - -#: ../../deprecations/pending-removal-in-3.15.rst:23 -msgid "" -"The obsolete and rarely used :class:`~http.server.CGIHTTPRequestHandler` has " -"been deprecated since Python 3.13. No direct replacement exists. *Anything* " -"is better than CGI to interface a web server with a request handler." -msgstr "" -"過時且很少使用的 :class:`~http.server.CGIHTTPRequestHandler` 自 Python 3.13 " -"起已被棄用。不存在直接的替代。*任何東西*\\ 都比 CGI 更好地將 Web 伺服器與請求" -"處理程序介接起來。" - -#: ../../deprecations/pending-removal-in-3.15.rst:29 -msgid "" -"The :option:`!--cgi` flag to the :program:`python -m http.server` command-" -"line interface has been deprecated since Python 3.13." -msgstr "" -"自 Python 3.13 起，:program:`python -m http.server` 命令列介面的 :option:`!--" -"cgi` 旗標已被棄用。" - -#: ../../deprecations/pending-removal-in-3.15.rst:32 -#: ../../deprecations/pending-removal-in-future.rst:63 -msgid ":mod:`importlib`:" -msgstr ":mod:`importlib`：" - -#: ../../deprecations/pending-removal-in-3.15.rst:34 -msgid "``load_module()`` method: use ``exec_module()`` instead." -msgstr "``load_module()`` method：請改用 ``exec_module()``。" - -#: ../../deprecations/pending-removal-in-3.15.rst:36 -msgid ":class:`locale`:" -msgstr ":class:`locale`：" - -#: ../../deprecations/pending-removal-in-3.15.rst:38 -msgid "" -"The :func:`~locale.getdefaultlocale` function has been deprecated since " -"Python 3.11. Its removal was originally planned for Python 3.13 (:gh:" -"`90817`), but has been postponed to Python 3.15. Use :func:`~locale." -"getlocale`, :func:`~locale.setlocale`, and :func:`~locale.getencoding` " -"instead. (Contributed by Hugo van Kemenade in :gh:`111187`.)" -msgstr "" -":func:`~locale.getdefaultlocale` 已在 Python 3.11 中被棄用，原本計劃在 " -"Python 3.13 中移除 (:gh:`90817`)，但被延後至 Python 3.15。請改用 :func:" -"`~locale.getlocale`、:func:`~locale.setlocale` 和 :func:`~locale." -"getencoding`。 (由 Hugo van Kemenade 於 :gh:`111187` 貢獻。)" - -#: ../../deprecations/pending-removal-in-3.15.rst:46 -msgid ":mod:`pathlib`:" -msgstr ":mod:`pathlib`：" - -#: ../../deprecations/pending-removal-in-3.15.rst:48 -msgid "" -":meth:`.PurePath.is_reserved` has been deprecated since Python 3.13. Use :" -"func:`os.path.isreserved` to detect reserved paths on Windows." -msgstr "" -":meth:`.PurePath.is_reserved` 已自 Python 3.13 被棄用。請用 :func:`os.path." -"isreserved` 來偵測 Windows 上的保留路徑。" - -#: ../../deprecations/pending-removal-in-3.15.rst:52 -msgid ":mod:`platform`:" -msgstr ":mod:`platform`：" - -#: ../../deprecations/pending-removal-in-3.15.rst:54 -msgid "" -":func:`~platform.java_ver` has been deprecated since Python 3.13. This " -"function is only useful for Jython support, has a confusing API, and is " -"largely untested." -msgstr "" -"自 Python 3.13 起，:func:`~platform.java_ver` 已被棄用。此函式僅對 Jython 支" -"援有用，具有令人困惑的 API，基本上未經測試。" - -#: ../../deprecations/pending-removal-in-3.15.rst:58 -#: ../../deprecations/pending-removal-in-3.16.rst:96 -msgid ":mod:`sysconfig`:" -msgstr ":mod:`sysconfig`：" - -#: ../../deprecations/pending-removal-in-3.15.rst:60 -msgid "" -"The *check_home* argument of :func:`sysconfig.is_python_build` has been " -"deprecated since Python 3.12." -msgstr "" -":func:`sysconfig.is_python_build` 的 *check_home* 引數自 Python 3.12 起已被棄" -"用。" - -#: ../../deprecations/pending-removal-in-3.15.rst:63 -msgid ":mod:`threading`:" -msgstr ":mod:`threading`：" - -#: ../../deprecations/pending-removal-in-3.15.rst:65 -msgid "" -":func:`~threading.RLock` will take no arguments in Python 3.15. Passing any " -"arguments has been deprecated since Python 3.14, as the Python version does " -"not permit any arguments, but the C version allows any number of positional " -"or keyword arguments, ignoring every argument." -msgstr "" -":func:`~threading.RLock` 在 Python 3.15 中將不接受任何引數。自 Python 3.14 " -"起，傳遞任何引數的用法已被棄用，因為 Python 版本不允許任何引數，但 C 版本允許" -"任意數量的位置或關鍵字引數，並忽略每個引數。" - -#: ../../deprecations/pending-removal-in-3.15.rst:71 -msgid ":mod:`types`:" -msgstr ":mod:`types`：" - -#: ../../deprecations/pending-removal-in-3.15.rst:73 -msgid "" -":class:`types.CodeType`: Accessing :attr:`~codeobject.co_lnotab` was " -"deprecated in :pep:`626` since 3.10 and was planned to be removed in 3.12, " -"but it only got a proper :exc:`DeprecationWarning` in 3.12. May be removed " -"in 3.15. (Contributed by Nikita Sobolev in :gh:`101866`.)" -msgstr "" -":class:`types.CodeType`：自 3.10 起，存取 :attr:`~codeobject.co_lnotab` 已" -"在 :pep:`626` 中被棄用，並計劃在 3.12 中移除，但只在 3.12 中於適當時發出 :" -"exc:`DeprecationWarning`。可能在 3.15 中移除。（由 Nikita Sobolev 於 :gh:" -"`101866` 貢獻。）" - -#: ../../deprecations/pending-removal-in-3.15.rst:80 -#: ../../deprecations/pending-removal-in-3.17.rst:26 -msgid ":mod:`typing`:" -msgstr ":mod:`typing`：" - -#: ../../deprecations/pending-removal-in-3.15.rst:82 -msgid "" -"The undocumented keyword argument syntax for creating :class:`~typing." -"NamedTuple` classes (for example, ``Point = NamedTuple(\"Point\", x=int, " -"y=int)``) has been deprecated since Python 3.13. Use the class-based syntax " -"or the functional syntax instead." -msgstr "" -"用於建立 :class:`~typing.NamedTuple` 類別的未以文件記錄之關鍵字引數語法 " -"(``Point = NamedTuple(\"Point\", x=int, y=int)``) 已自 Python 3.13 棄用。請改" -"用基於類別的語法或函式語法 (functional syntax)。" - -#: ../../deprecations/pending-removal-in-3.15.rst:88 -msgid "" -"When using the functional syntax of :class:`~typing.TypedDict`\\s, failing " -"to pass a value to the *fields* parameter (``TD = TypedDict(\"TD\")``) or " -"passing ``None`` (``TD = TypedDict(\"TD\", None)``) has been deprecated " -"since Python 3.13. Use ``class TD(TypedDict): pass`` or ``TD = " -"TypedDict(\"TD\", {})`` to create a TypedDict with zero field." -msgstr "" -"當使用 :class:`~typing.TypedDict` 的函式語法時，未傳遞值給 *fields* 參數 " -"(``TD = TypedDict(\"TD\")``) 或傳遞 ``None`` (``TD = TypedDict(\"TD\", " -"None)``) 的做法自 Python 3.13 起已被棄用。請使用 ``class TD(TypedDict): " -"pass`` 或 ``TD = TypedDict(\"TD\", {})`` 來建立具有零個欄位的 TypedDict。" - -#: ../../deprecations/pending-removal-in-3.15.rst:95 -msgid "" -"The :func:`typing.no_type_check_decorator` decorator function has been " -"deprecated since Python 3.13. After eight years in the :mod:`typing` module, " -"it has yet to be supported by any major type checker." -msgstr "" -"自 Python 3.13 起，:func:`typing.no_type_check_decorator` 裝飾器函式已被棄" -"用。在 :mod:`typing` 模組中使用了八年之後，它尚未得到任何主要型別檢查器的支" -"援。" - -#: ../../deprecations/pending-removal-in-3.15.rst:100 -msgid ":mod:`wave`:" -msgstr ":mod:`wave`：" - -#: ../../deprecations/pending-removal-in-3.15.rst:102 -msgid "" -"The :meth:`~wave.Wave_read.getmark`, :meth:`!setmark`, and :meth:`~wave." -"Wave_read.getmarkers` methods of the :class:`~wave.Wave_read` and :class:" -"`~wave.Wave_write` classes have been deprecated since Python 3.13." -msgstr "" -"已棄用 :class:`~wave.Wave_read` 和 :class:`~wave.Wave_write` 類別的 :meth:" -"`~wave.Wave_read.getmark`、:meth:`!setmark` 和 :meth:`~wave.Wave_read." -"getmarkers` 方法自 Python 3.13 被棄用。" - -#: ../../deprecations/pending-removal-in-3.15.rst:107 -msgid ":mod:`zipimport`:" -msgstr ":mod:`zipimport`：" - -#: ../../deprecations/pending-removal-in-3.15.rst:109 -msgid "" -":meth:`~zipimport.zipimporter.load_module` has been deprecated since Python " -"3.10. Use :meth:`~zipimport.zipimporter.exec_module` instead. (Contributed " -"by Jiahao Li in :gh:`125746`.)" -msgstr "" -":meth:`~zipimport.zipimporter.load_module` 自 Python 3.10 被棄用。請改用 :" -"meth:`~zipimport.zipimporter.exec_module`。（由 Jiahao Li 於 :gh:`125746` 貢" -"獻。）" - -#: ../../deprecations/pending-removal-in-3.16.rst:2 -msgid "Pending removal in Python 3.16" -msgstr "Python 3.16 中待移除的項目" - -#: ../../deprecations/pending-removal-in-3.16.rst:6 -msgid "" -"Setting :attr:`~module.__loader__` on a module while failing to set :attr:" -"`__spec__.loader ` is deprecated. In " -"Python 3.16, :attr:`!__loader__` will cease to be set or taken into " -"consideration by the import system or the standard library." -msgstr "" -"在模組上設定 :attr:`~module.__loader__` 而沒有設定 :attr:`__spec__.loader " -"` 的做法將於 Python 3.16 被棄用。在 " -"Python 3.16 中，引入系統或標準函式庫將不再設定或考慮 :attr:`!__loader__`。" - -#: ../../deprecations/pending-removal-in-3.16.rst:11 -msgid ":mod:`array`:" -msgstr ":mod:`array`：" - -#: ../../deprecations/pending-removal-in-3.16.rst:13 -msgid "" -"The ``'u'`` format code (:c:type:`wchar_t`) has been deprecated in " -"documentation since Python 3.3 and at runtime since Python 3.13. Use the " -"``'w'`` format code (:c:type:`Py_UCS4`) for Unicode characters instead." -msgstr "" -"自 Python 3.3 起，``'u'`` 格式碼 (:c:type:`wchar_t`) 在文件中已被棄用，自 " -"Python 3.13 起在 runtime 已被棄用。請使用 ``'w'`` 格式碼 (:c:type:`Py_UCS4`) " -"來取代 Unicode 字元。" - -#: ../../deprecations/pending-removal-in-3.16.rst:19 -msgid ":mod:`asyncio`:" -msgstr ":mod:`asyncio`：" - -#: ../../deprecations/pending-removal-in-3.16.rst:21 -msgid "" -":func:`!asyncio.iscoroutinefunction` is deprecated and will be removed in " -"Python 3.16; use :func:`inspect.iscoroutinefunction` instead. (Contributed " -"by Jiahao Li and Kumar Aditya in :gh:`122875`.)" -msgstr "" -":func:`!asyncio.iscoroutinefunction` 已被棄用並將在 Python 3.16 中移除；請改" -"用 :func:`inspect.iscoroutinefunction`。（由 Jiahao Li 和 Kumar Aditya 於 :" -"gh:`122875` 貢獻。）" - -#: ../../deprecations/pending-removal-in-3.16.rst:26 -msgid "" -":mod:`asyncio` policy system is deprecated and will be removed in Python " -"3.16. In particular, the following classes and functions are deprecated:" -msgstr "" -":mod:`asyncio` 策略系統已被棄用並將在 Python 3.16 中移除。特別是以下類別和函" -"式已被棄用：" - -#: ../../deprecations/pending-removal-in-3.16.rst:29 -msgid ":class:`asyncio.AbstractEventLoopPolicy`" -msgstr ":class:`asyncio.AbstractEventLoopPolicy`" - -#: ../../deprecations/pending-removal-in-3.16.rst:30 -msgid ":class:`asyncio.DefaultEventLoopPolicy`" -msgstr ":class:`asyncio.DefaultEventLoopPolicy`" - -#: ../../deprecations/pending-removal-in-3.16.rst:31 -msgid ":class:`asyncio.WindowsSelectorEventLoopPolicy`" -msgstr ":class:`asyncio.WindowsSelectorEventLoopPolicy`" - -#: ../../deprecations/pending-removal-in-3.16.rst:32 -msgid ":class:`asyncio.WindowsProactorEventLoopPolicy`" -msgstr ":class:`asyncio.WindowsProactorEventLoopPolicy`" - -#: ../../deprecations/pending-removal-in-3.16.rst:33 -msgid ":func:`asyncio.get_event_loop_policy`" -msgstr ":func:`asyncio.get_event_loop_policy`" - -#: ../../deprecations/pending-removal-in-3.16.rst:34 -msgid ":func:`asyncio.set_event_loop_policy`" -msgstr ":func:`asyncio.set_event_loop_policy`" - -#: ../../deprecations/pending-removal-in-3.16.rst:36 -msgid "" -"Users should use :func:`asyncio.run` or :class:`asyncio.Runner` with " -"*loop_factory* to use the desired event loop implementation." -msgstr "" -"使用者應該使用 :func:`asyncio.run` 或 :class:`asyncio.Runner` 搭配 " -"*loop_factory* 來使用所需的事件迴圈實作。" - -#: ../../deprecations/pending-removal-in-3.16.rst:39 -msgid "For example, to use :class:`asyncio.SelectorEventLoop` on Windows::" -msgstr "例如在 Windows 上使用 :class:`asyncio.SelectorEventLoop`： ::" - -#: ../../deprecations/pending-removal-in-3.16.rst:41 -msgid "" -"import asyncio\n" -"\n" -"async def main():\n" -" ...\n" -"\n" -"asyncio.run(main(), loop_factory=asyncio.SelectorEventLoop)" -msgstr "" -"import asyncio\n" -"\n" -"async def main():\n" -" ...\n" -"\n" -"asyncio.run(main(), loop_factory=asyncio.SelectorEventLoop)" - -#: ../../deprecations/pending-removal-in-3.16.rst:48 -msgid "(Contributed by Kumar Aditya in :gh:`127949`.)" -msgstr "（由 Kumar Aditya 於 :gh:`127949` 貢獻。）" - -#: ../../deprecations/pending-removal-in-3.16.rst:50 -#: ../../deprecations/pending-removal-in-future.rst:16 -msgid ":mod:`builtins`:" -msgstr ":mod:`builtins`：" - -#: ../../deprecations/pending-removal-in-3.16.rst:52 -msgid "" -"Bitwise inversion on boolean types, ``~True`` or ``~False`` has been " -"deprecated since Python 3.12, as it produces surprising and unintuitive " -"results (``-2`` and ``-1``). Use ``not x`` instead for the logical negation " -"of a Boolean. In the rare case that you need the bitwise inversion of the " -"underlying integer, convert to ``int`` explicitly (``~int(x)``)." -msgstr "" -"自 Python 3.12 起，布林型別的位元反轉 ``~True`` 或 ``~False`` 已被棄用，因為" -"它會產生不預期且不直觀的結果（``-2`` 和 ``-1``）。使用 ``not x`` 代替布林值的" -"邏輯否定。在極少數情況下，你需要對底層的整數進行位元反轉，請明確轉換為 " -"``~int(x)`` (``~int(x)``)。" - -#: ../../deprecations/pending-removal-in-3.16.rst:59 -msgid ":mod:`functools`:" -msgstr ":mod:`functools`：" - -#: ../../deprecations/pending-removal-in-3.16.rst:61 -msgid "" -"Calling the Python implementation of :func:`functools.reduce` with " -"*function* or *sequence* as keyword arguments has been deprecated since " -"Python 3.14." -msgstr "" -"自 Python 3.14 起，使用 *function* 或 *sequence* 關鍵字引數呼叫 :func:" -"`functools.reduce` 的 Python 實作已被棄用。" - -#: ../../deprecations/pending-removal-in-3.16.rst:64 -msgid ":mod:`logging`:" -msgstr ":mod:`logging`：" - -#: ../../deprecations/pending-removal-in-3.16.rst:66 -msgid "" -"Support for custom logging handlers with the *strm* argument is deprecated " -"and scheduled for removal in Python 3.16. Define handlers with the *stream* " -"argument instead. (Contributed by Mariusz Felisiak in :gh:`115032`.)" -msgstr "" -"對具有 *strm* 引數的自訂日誌記錄處理函式的支援已被棄用，並計劃在 Python 3.16 " -"中移除。請改用 *stream* 引數。（由 Mariusz Felisiak 於 :gh:`115032` 貢獻。）" - -#: ../../deprecations/pending-removal-in-3.16.rst:70 -msgid ":mod:`mimetypes`:" -msgstr ":mod:`mimetypes`：" - -#: ../../deprecations/pending-removal-in-3.16.rst:72 -msgid "" -"Valid extensions start with a '.' or are empty for :meth:`mimetypes." -"MimeTypes.add_type`. Undotted extensions are deprecated and will raise a :" -"exc:`ValueError` in Python 3.16. (Contributed by Hugo van Kemenade in :gh:" -"`75223`.)" -msgstr "" -"有效的副檔名以 '.' 開頭或對 :meth:`mimetypes.MimeTypes.add_type` 為空字串。未" -"加點的副檔名已被棄用，並將在 Python 3.16 中引發 :exc:`ValueError`。（由 Hugo " -"van Kemenade 於 :gh:`75223` 貢獻。）" - -#: ../../deprecations/pending-removal-in-3.16.rst:78 -msgid ":mod:`shutil`:" -msgstr ":mod:`shutil`：" - -#: ../../deprecations/pending-removal-in-3.16.rst:80 -msgid "" -"The :class:`!ExecError` exception has been deprecated since Python 3.14. It " -"has not been used by any function in :mod:`!shutil` since Python 3.4, and is " -"now an alias of :exc:`RuntimeError`." -msgstr "" -"自 Python 3.14 起，:class:`!ExecError` 例外已被棄用。自 Python 3.4 以來，它尚" -"未被 :mod:`!shutil` 中的任何函式使用，現在是 :exc:`RuntimeError` 的別名。" - -#: ../../deprecations/pending-removal-in-3.16.rst:85 -msgid ":mod:`symtable`:" -msgstr ":mod:`symtable`：" - -#: ../../deprecations/pending-removal-in-3.16.rst:87 -msgid "" -"The :meth:`Class.get_methods ` method has been " -"deprecated since Python 3.14." -msgstr "" -"自 Python 3.14 起，:meth:`Class.get_methods ` 方" -"法已被棄用。" - -#: ../../deprecations/pending-removal-in-3.16.rst:90 -msgid ":mod:`sys`:" -msgstr ":mod:`sys`：" - -#: ../../deprecations/pending-removal-in-3.16.rst:92 -msgid "" -"The :func:`~sys._enablelegacywindowsfsencoding` function has been deprecated " -"since Python 3.13. Use the :envvar:`PYTHONLEGACYWINDOWSFSENCODING` " -"environment variable instead." -msgstr "" -"自 Python 3.13 起，:func:`~sys._enablelegacywindowsfsencoding` 函式已被棄用。" -"請改用 :envvar:`PYTHONLEGACYWINDOWSFSENCODING` 環境變數。" - -#: ../../deprecations/pending-removal-in-3.16.rst:98 -msgid "" -"The :func:`!sysconfig.expand_makefile_vars` function has been deprecated " -"since Python 3.14. Use the ``vars`` argument of :func:`sysconfig.get_paths` " -"instead." -msgstr "" -"自 Python 3.14 起，:func:`!sysconfig.expand_makefile_vars` 函式已被棄用。請改" -"用 :func:`sysconfig.get_paths` 的 ``vars`` 引數。" - -#: ../../deprecations/pending-removal-in-3.16.rst:102 -msgid ":mod:`tarfile`:" -msgstr ":mod:`tarfile`：" - -#: ../../deprecations/pending-removal-in-3.16.rst:104 -msgid "" -"The undocumented and unused :attr:`!TarFile.tarfile` attribute has been " -"deprecated since Python 3.13." -msgstr "" -"自 Python 3.13 起，未以文件記錄和未被使用的 :attr:`!TarFile.tarfile` 屬性已被" -"棄用。" - -#: ../../deprecations/pending-removal-in-3.17.rst:2 -msgid "Pending removal in Python 3.17" -msgstr "Python 3.17 中待移除的項目" - -#: ../../deprecations/pending-removal-in-3.17.rst:4 -msgid ":mod:`collections.abc`:" -msgstr ":mod:`collections.abc`：" - -#: ../../deprecations/pending-removal-in-3.17.rst:6 -msgid "" -":class:`collections.abc.ByteString` is scheduled for removal in Python 3.17." -msgstr ":class:`collections.abc.ByteString` 預計在 Python 3.17 中移除。" - -#: ../../deprecations/pending-removal-in-3.17.rst:8 -#: ../../deprecations/pending-removal-in-3.17.rst:36 -msgid "" -"Use ``isinstance(obj, collections.abc.Buffer)`` to test if ``obj`` " -"implements the :ref:`buffer protocol ` at runtime. For use in " -"type annotations, either use :class:`~collections.abc.Buffer` or a union " -"that explicitly specifies the types your code supports (e.g., ``bytes | " -"bytearray | memoryview``)." -msgstr "" -"使用 ``isinstance(obj, collections.abc.Buffer)`` 來測試 ``obj`` 是否在 " -"runtime 實作了\\ :ref:`緩衝區協定 `。在型別註解的使用中，請" -"用 :class:`~collections.abc.Buffer` 或明確指定你的程式碼所支援型別的聯集（例" -"如 ``bytes | bytearray | memoryview``）。" - -#: ../../deprecations/pending-removal-in-3.17.rst:14 -#: ../../deprecations/pending-removal-in-3.17.rst:42 -msgid "" -":class:`!ByteString` was originally intended to be an abstract class that " -"would serve as a supertype of both :class:`bytes` and :class:`bytearray`. " -"However, since the ABC never had any methods, knowing that an object was an " -"instance of :class:`!ByteString` never actually told you anything useful " -"about the object. Other common buffer types such as :class:`memoryview` were " -"also never understood as subtypes of :class:`!ByteString` (either at runtime " -"or by static type checkers)." -msgstr "" -":class:`!ByteString` 最初被設計為一個抽象類別，以作為 :class:`bytes` 和 :" -"class:`bytearray` 的超型別 (supertype)。然而由於 ABC 從未擁有任何方法，知道一" -"個物件是 :class:`!ByteString` 的實例從未真正告訴你任何關於該物件的有用資訊。" -"其他常見的緩衝區型別如 :class:`memoryview` 也從未被理解為 :class:`!" -"ByteString` 的子型別（無論是在 runtime 還是由靜態型別檢查器）。" - -#: ../../deprecations/pending-removal-in-3.17.rst:22 -#: ../../deprecations/pending-removal-in-3.17.rst:50 -msgid "" -"See :pep:`PEP 688 <688#current-options>` for more details. (Contributed by " -"Shantanu Jain in :gh:`91896`.)" -msgstr "" -"更多細節請見 :pep:`PEP 688 <688#current-options>`。（由 Shantanu Jain 於 :gh:" -"`91896` 貢獻。）" - -#: ../../deprecations/pending-removal-in-3.17.rst:28 -msgid "" -"Before Python 3.14, old-style unions were implemented using the private " -"class ``typing._UnionGenericAlias``. This class is no longer needed for the " -"implementation, but it has been retained for backward compatibility, with " -"removal scheduled for Python 3.17. Users should use documented introspection " -"helpers like :func:`typing.get_origin` and :func:`typing.get_args` instead " -"of relying on private implementation details." -msgstr "" -"在 Python 3.14 之前，舊式聯集是使用私有類別 ``typing._UnionGenericAlias`` 實" -"作的。這個類別不再被需要，但為了向後相容性而保留，並計劃將在 Python 3.17 中移" -"除。使用者應該改用文件中記錄的內省輔助函式，例如 :func:`typing.get_origin` " -"和 :func:`typing.get_args`，或者依賴私有實作細節。" - -#: ../../deprecations/pending-removal-in-3.17.rst:33 -msgid "" -":class:`typing.ByteString`, deprecated since Python 3.9, is scheduled for " -"removal in Python 3.17." -msgstr "" -":class:`typing.ByteString` 自 Python 3.9 起已被棄用，預計在 Python 3.17 中移" -"除。" - -#: ../../deprecations/c-api-pending-removal-in-3.18.rst:2 -#: ../../deprecations/pending-removal-in-3.18.rst:2 -msgid "Pending removal in Python 3.18" -msgstr "Python 3.18 中待移除的項目" - -#: ../../deprecations/pending-removal-in-3.18.rst:4 -msgid ":mod:`decimal`:" -msgstr ":mod:`decimal`：" - -#: ../../deprecations/pending-removal-in-3.18.rst:6 -msgid "" -"The non-standard and undocumented :class:`~decimal.Decimal` format specifier " -"``'N'``, which is only supported in the :mod:`!decimal` module's C " -"implementation, has been deprecated since Python 3.13. (Contributed by " -"Serhiy Storchaka in :gh:`89902`.)" -msgstr "" -"非標準且無文件記載的 :class:`~decimal.Decimal` 格式說明符號 ``'N'``，僅在 :mod:" -"`!decimal` 模組的 C 實作中被支援，自 Python 3.13 起已被棄用。（由 Serhiy " -"Storchaka 於 :gh:`89902` 中貢獻。）" - -#: ../../deprecations/pending-removal-in-3.19.rst:2 -msgid "Pending removal in Python 3.19" -msgstr "Python 3.19 中待移除的項目" - -#: ../../deprecations/pending-removal-in-3.19.rst:6 -msgid "" -"Implicitly switching to the MSVC-compatible struct layout by setting :attr:" -"`~ctypes.Structure._pack_` but not :attr:`~ctypes.Structure._layout_` on non-" -"Windows platforms." -msgstr "" -"在非 Windows 平台上，透過設定 :attr:`~ctypes.Structure._pack_` 而沒有設定 :" -"attr:`~ctypes.Structure._layout_` 來隱式地切換到與 MSVC 相容的結構佈局。" - -#: ../../deprecations/c-api-pending-removal-in-future.rst:2 -#: ../../deprecations/pending-removal-in-future.rst:2 -msgid "Pending removal in future versions" -msgstr "未來版本中的待移除項目" - -#: ../../deprecations/pending-removal-in-future.rst:4 -msgid "" -"The following APIs will be removed in the future, although there is " -"currently no date scheduled for their removal." -msgstr "以下 API 將在未來被移除，雖然目前尚未安排移除日期。" - -#: ../../deprecations/pending-removal-in-future.rst:7 -msgid ":mod:`argparse`:" -msgstr ":mod:`argparse`：" - -#: ../../deprecations/pending-removal-in-future.rst:9 -msgid "" -"Nesting argument groups and nesting mutually exclusive groups are deprecated." -msgstr "巢狀引數群組和巢狀互斥群組已被棄用。" - -#: ../../deprecations/pending-removal-in-future.rst:11 -msgid "" -"Passing the undocumented keyword argument *prefix_chars* to :meth:`~argparse." -"ArgumentParser.add_argument_group` is now deprecated." -msgstr "" -"將未以文件記錄的關鍵字引數 *prefix_chars* 傳遞給 :meth:`~argparse." -"ArgumentParser.add_argument_group` 的做法現在已被棄用。" - -#: ../../deprecations/pending-removal-in-future.rst:14 -msgid "The :class:`argparse.FileType` type converter is deprecated." -msgstr ":class:`argparse.FileType` 型別轉換器已被棄用。" - -#: ../../deprecations/pending-removal-in-future.rst:18 -msgid "" -"Generators: ``throw(type, exc, tb)`` and ``athrow(type, exc, tb)`` signature " -"is deprecated: use ``throw(exc)`` and ``athrow(exc)`` instead, the single " -"argument signature." -msgstr "" -"產生器：``throw(type, exc, tb)`` 和 ``athrow(type, exc, tb)`` 簽名已被棄用：" -"請改用 ``throw(exc)`` 和 ``athrow(exc)``，為單引數簽名。" - -#: ../../deprecations/pending-removal-in-future.rst:21 -msgid "" -"Currently Python accepts numeric literals immediately followed by keywords, " -"for example ``0in x``, ``1or x``, ``0if 1else 2``. It allows confusing and " -"ambiguous expressions like ``[0x1for x in y]`` (which can be interpreted as " -"``[0x1 for x in y]`` or ``[0x1f or x in y]``). A syntax warning is raised " -"if the numeric literal is immediately followed by one of keywords :keyword:" -"`and`, :keyword:`else`, :keyword:`for`, :keyword:`if`, :keyword:`in`, :" -"keyword:`is` and :keyword:`or`. In a future release it will be changed to a " -"syntax error. (:gh:`87999`)" -msgstr "" -"目前 Python 接受數值字面值後面立即接關鍵字，例如 ``0in x``、``1or x``、``0if " -"1else 2``。它讓運算式模糊且容易混淆，如 ``[0x1for x in y]``\\ （可以解釋為 " -"``[0x1 for x in y]`` 或 ``[0x1f or x in y]``）。如果數值字面值後立即接 :" -"keyword:`and`、:keyword:`else`、:keyword:`for`、:keyword:`if`、:keyword:" -"`in`、:keyword:`is` 和 :keyword:`or` 之一的關鍵字，則會引發語法警告。在未來版" -"本中，它將被更改為語法錯誤。(:gh:`87999`)" - -#: ../../deprecations/pending-removal-in-future.rst:29 -msgid "" -"Support for ``__index__()`` and ``__int__()`` method returning non-int type: " -"these methods will be required to return an instance of a strict subclass " -"of :class:`int`." -msgstr "" -"``__index__()`` 和 ``__int__()`` 方法回傳非 int 型別的支援：這些方法將需要回" -"傳 :class:`int` 的嚴格子類別實例。" - -#: ../../deprecations/pending-removal-in-future.rst:32 -msgid "" -"Support for ``__float__()`` method returning a strict subclass of :class:" -"`float`: these methods will be required to return an instance of :class:" -"`float`." -msgstr "" -"回傳 :class:`float` 嚴格子類別 ``__float__()`` 方法的支援：這些方法將需要回" -"傳 :class:`float` 的實例。" - -#: ../../deprecations/pending-removal-in-future.rst:35 -msgid "" -"Support for ``__complex__()`` method returning a strict subclass of :class:" -"`complex`: these methods will be required to return an instance of :class:" -"`complex`." -msgstr "" -"回傳 :class:`complex` 嚴格子類別 ``__complex__()`` 方法的支援：這些方法將需要" -"回傳 :class:`complex` 的實例。" - -#: ../../deprecations/pending-removal-in-future.rst:38 -msgid "Delegation of ``int()`` to ``__trunc__()`` method." -msgstr "將 ``int()`` 委派給 ``__trunc__()`` 方法。" - -#: ../../deprecations/pending-removal-in-future.rst:39 -msgid "" -"Passing a complex number as the *real* or *imag* argument in the :func:" -"`complex` constructor is now deprecated; it should only be passed as a " -"single positional argument. (Contributed by Serhiy Storchaka in :gh:" -"`109218`.)" -msgstr "" -"在 :func:`complex` 建構子中將複數作為 *real* 或 *imag* 引數傳遞現在已被棄用；" -"它應該只作為單個位置引數傳遞。 (由 Serhiy Storchaka 於 :gh:`109218` 貢獻。)" - -#: ../../deprecations/pending-removal-in-future.rst:44 -msgid "" -":mod:`calendar`: ``calendar.January`` and ``calendar.February`` constants " -"are deprecated and replaced by :data:`calendar.JANUARY` and :data:`calendar." -"FEBRUARY`. (Contributed by Prince Roshan in :gh:`103636`.)" -msgstr "" -":mod:`calendar`：``calendar.January`` 和 ``calendar.February`` 常數已被棄用並" -"被 :data:`calendar.JANUARY` 和 :data:`calendar.FEBRUARY` 取代。 (由 Prince " -"Roshan 於 :gh:`103636` 貢獻。)" - -#: ../../deprecations/pending-removal-in-future.rst:49 -msgid "" -":mod:`codecs`: use :func:`open` instead of :func:`codecs.open`. (:gh:" -"`133038`)" -msgstr "" -":mod:`codecs`：請改用 :func:`open` 而非 :func:`codecs.open`。(:gh:`133038`)" - -#: ../../deprecations/pending-removal-in-future.rst:51 -msgid "" -":attr:`codeobject.co_lnotab`: use the :meth:`codeobject.co_lines` method " -"instead." -msgstr "" -":attr:`codeobject.co_lnotab`：請改用 :meth:`codeobject.co_lines` 方法。" - -#: ../../deprecations/pending-removal-in-future.rst:54 -msgid ":mod:`datetime`:" -msgstr ":mod:`datetime`：" - -#: ../../deprecations/pending-removal-in-future.rst:56 -msgid "" -":meth:`~datetime.datetime.utcnow`: use ``datetime.datetime.now(tz=datetime." -"UTC)``." -msgstr "" -":meth:`~datetime.datetime.utcnow`：請改用 ``datetime.datetime." -"now(tz=datetime.UTC)``。" - -#: ../../deprecations/pending-removal-in-future.rst:58 -msgid "" -":meth:`~datetime.datetime.utcfromtimestamp`: use ``datetime.datetime." -"fromtimestamp(timestamp, tz=datetime.UTC)``." -msgstr "" -":meth:`~datetime.datetime.utcfromtimestamp`：請改用 ``datetime.datetime." -"fromtimestamp(timestamp, tz=datetime.UTC)``。" - -#: ../../deprecations/pending-removal-in-future.rst:61 -msgid ":mod:`gettext`: Plural value must be an integer." -msgstr ":mod:`gettext`：複數值必須是整數。" - -#: ../../deprecations/pending-removal-in-future.rst:65 -msgid "" -":func:`~importlib.util.cache_from_source` *debug_override* parameter is " -"deprecated: use the *optimization* parameter instead." -msgstr "" -":func:`~importlib.util.cache_from_source` *debug_override* 參數已被棄用：請改" -"用 *optimization* 參數。" - -#: ../../deprecations/pending-removal-in-future.rst:68 -msgid ":mod:`importlib.metadata`:" -msgstr ":mod:`importlib.metadata`：" - -#: ../../deprecations/pending-removal-in-future.rst:70 -msgid "``EntryPoints`` tuple interface." -msgstr "``EntryPoints`` 元組介面。" - -#: ../../deprecations/pending-removal-in-future.rst:71 -msgid "Implicit ``None`` on return values." -msgstr "回傳值上的隱式 ``None``。" - -#: ../../deprecations/pending-removal-in-future.rst:73 -msgid "" -":mod:`logging`: the ``warn()`` method has been deprecated since Python 3.3, " -"use :meth:`~logging.warning` instead." -msgstr "" -":mod:`logging`：自 Python 3.3 起，``warn()`` 方法已被棄用，請改用 :meth:" -"`~logging.warning`。" - -#: ../../deprecations/pending-removal-in-future.rst:76 -msgid "" -":mod:`mailbox`: Use of StringIO input and text mode is deprecated, use " -"BytesIO and binary mode instead." -msgstr "" -":mod:`mailbox`：已棄用 StringIO 輸入和文本模式，請改用 BytesIO 和二進位模式。" - -#: ../../deprecations/pending-removal-in-future.rst:79 -msgid "" -":mod:`os`: Calling :func:`os.register_at_fork` in multi-threaded process." -msgstr ":mod:`os`：在多執行緒行程中呼叫 :func:`os.register_at_fork`。" - -#: ../../deprecations/pending-removal-in-future.rst:81 -msgid "" -":class:`!pydoc.ErrorDuringImport`: A tuple value for *exc_info* parameter is " -"deprecated, use an exception instance." -msgstr "" -":class:`!pydoc.ErrorDuringImport`：*exc_info* 參數的元組值已被棄用，請用例外" -"實例。" - -#: ../../deprecations/pending-removal-in-future.rst:84 -msgid "" -":mod:`re`: More strict rules are now applied for numerical group references " -"and group names in regular expressions. Only sequence of ASCII digits is " -"now accepted as a numerical reference. The group name in bytes patterns and " -"replacement strings can now only contain ASCII letters and digits and " -"underscore. (Contributed by Serhiy Storchaka in :gh:`91760`.)" -msgstr "" -":mod:`re`：現在對正規表示式中的數值群組參照和群組名稱用了更嚴格的規則。現在只" -"有 ASCII 數碼序列被接受作為數值參照。位元組模式和替換字串中的群組名稱現在只能" -"包含 ASCII 字母、數碼和底線。（由 Serhiy Storchaka 於 :gh:`91760` 貢獻。）" - -#: ../../deprecations/pending-removal-in-future.rst:91 -msgid "" -":mod:`!sre_compile`, :mod:`!sre_constants` and :mod:`!sre_parse` modules." -msgstr ":mod:`!sre_compile`、:mod:`!sre_constants` 和 :mod:`!sre_parse` 模組。" - -#: ../../deprecations/pending-removal-in-future.rst:93 -msgid "" -":mod:`shutil`: :func:`~shutil.rmtree`'s *onerror* parameter is deprecated in " -"Python 3.12; use the *onexc* parameter instead." -msgstr "" -":mod:`shutil`：:func:`~shutil.rmtree` 的 *onerror* 參數在 Python 3.12 中已被" -"棄用；請改用 *onexc* 參數。" - -#: ../../deprecations/pending-removal-in-future.rst:96 -msgid ":mod:`ssl` options and protocols:" -msgstr ":mod:`ssl` 選項和協定：" - -#: ../../deprecations/pending-removal-in-future.rst:98 -msgid ":class:`ssl.SSLContext` without protocol argument is deprecated." -msgstr "不帶協定引數的 :class:`ssl.SSLContext` 已被棄用。" - -#: ../../deprecations/pending-removal-in-future.rst:99 -msgid "" -":class:`ssl.SSLContext`: :meth:`~ssl.SSLContext.set_npn_protocols` and :meth:" -"`!selected_npn_protocol` are deprecated: use ALPN instead." -msgstr "" -":class:`ssl.SSLContext`：:meth:`~ssl.SSLContext.set_npn_protocols` 和 :meth:" -"`!selected_npn_protocol` 已被棄用：請改用 ALPN。" - -#: ../../deprecations/pending-removal-in-future.rst:102 -msgid "``ssl.OP_NO_SSL*`` options" -msgstr "``ssl.OP_NO_SSL*`` 選項" - -#: ../../deprecations/pending-removal-in-future.rst:103 -msgid "``ssl.OP_NO_TLS*`` options" -msgstr "``ssl.OP_NO_TLS*`` 選項" - -#: ../../deprecations/pending-removal-in-future.rst:104 -msgid "``ssl.PROTOCOL_SSLv3``" -msgstr "``ssl.PROTOCOL_SSLv3``" - -#: ../../deprecations/pending-removal-in-future.rst:105 -msgid "``ssl.PROTOCOL_TLS``" -msgstr "``ssl.PROTOCOL_TLS``" - -#: ../../deprecations/pending-removal-in-future.rst:106 -msgid "``ssl.PROTOCOL_TLSv1``" -msgstr "``ssl.PROTOCOL_TLSv1``" - -#: ../../deprecations/pending-removal-in-future.rst:107 -msgid "``ssl.PROTOCOL_TLSv1_1``" -msgstr "``ssl.PROTOCOL_TLSv1_1``" - -#: ../../deprecations/pending-removal-in-future.rst:108 -msgid "``ssl.PROTOCOL_TLSv1_2``" -msgstr "``ssl.PROTOCOL_TLSv1_2``" - -#: ../../deprecations/pending-removal-in-future.rst:109 -msgid "``ssl.TLSVersion.SSLv3``" -msgstr "``ssl.TLSVersion.SSLv3``" - -#: ../../deprecations/pending-removal-in-future.rst:110 -msgid "``ssl.TLSVersion.TLSv1``" -msgstr "``ssl.TLSVersion.TLSv1``" - -#: ../../deprecations/pending-removal-in-future.rst:111 -msgid "``ssl.TLSVersion.TLSv1_1``" -msgstr "``ssl.TLSVersion.TLSv1_1``" - -#: ../../deprecations/pending-removal-in-future.rst:113 -msgid ":mod:`threading` methods:" -msgstr ":mod:`threading` 方法：" - -#: ../../deprecations/pending-removal-in-future.rst:115 -msgid "" -":meth:`!threading.Condition.notifyAll`: use :meth:`~threading.Condition." -"notify_all`." -msgstr "" -":meth:`!threading.Condition.notifyAll`：請用 :meth:`~threading.Condition." -"notify_all`。" - -#: ../../deprecations/pending-removal-in-future.rst:116 -msgid ":meth:`!threading.Event.isSet`: use :meth:`~threading.Event.is_set`." -msgstr ":meth:`!threading.Event.isSet`：請用 :meth:`~threading.Event.is_set`。" - -#: ../../deprecations/pending-removal-in-future.rst:117 -msgid "" -":meth:`!threading.Thread.isDaemon`, :meth:`threading.Thread.setDaemon`: use :" -"attr:`threading.Thread.daemon` attribute." -msgstr "" -":meth:`!threading.Thread.isDaemon`、:meth:`threading.Thread.setDaemon`：請" -"用 :attr:`threading.Thread.daemon` 屬性。" - -#: ../../deprecations/pending-removal-in-future.rst:119 -msgid "" -":meth:`!threading.Thread.getName`, :meth:`threading.Thread.setName`: use :" -"attr:`threading.Thread.name` attribute." -msgstr "" -":meth:`!threading.Thread.getName`、:meth:`threading.Thread.setName`：請用 :" -"attr:`threading.Thread.name` 屬性。" - -#: ../../deprecations/pending-removal-in-future.rst:121 -msgid ":meth:`!threading.currentThread`: use :meth:`threading.current_thread`." -msgstr "" -":meth:`!threading.currentThread`：請用 :meth:`threading.current_thread`。" - -#: ../../deprecations/pending-removal-in-future.rst:122 -msgid ":meth:`!threading.activeCount`: use :meth:`threading.active_count`." -msgstr ":meth:`!threading.activeCount`：請用 :meth:`threading.active_count`。" - -#: ../../deprecations/pending-removal-in-future.rst:124 -msgid ":class:`typing.Text` (:gh:`92332`)." -msgstr ":class:`typing.Text` (:gh:`92332`)。" - -#: ../../deprecations/pending-removal-in-future.rst:126 -msgid "" -"The internal class ``typing._UnionGenericAlias`` is no longer used to " -"implement :class:`typing.Union`. To preserve compatibility with users using " -"this private class, a compatibility shim will be provided until at least " -"Python 3.17. (Contributed by Jelle Zijlstra in :gh:`105499`.)" -msgstr "" -"內部類別 ``typing._UnionGenericAlias`` 不再用於實作 :class:`typing.Union`。為" -"了保持與此私有類別使用者的相容性，直到至少 Python 3.17 都將提供一個相容性 " -"shim。（由 Jelle Zijlstra 於 :gh:`105499` 貢獻。）" - -#: ../../deprecations/pending-removal-in-future.rst:131 -msgid "" -":class:`unittest.IsolatedAsyncioTestCase`: it is deprecated to return a " -"value that is not ``None`` from a test case." -msgstr "" -":class:`unittest.IsolatedAsyncioTestCase`：從測試案例中回傳非 ``None`` 的值已" -"被棄用。" - -#: ../../deprecations/pending-removal-in-future.rst:134 -msgid "" -":mod:`urllib.parse` deprecated functions: :func:`~urllib.parse.urlparse` " -"instead" -msgstr "" -":mod:`urllib.parse` 已棄用函式：請改用 :func:`~urllib.parse.urlparse`。" - -#: ../../deprecations/pending-removal-in-future.rst:136 -msgid "``splitattr()``" -msgstr "``splitattr()``" - -#: ../../deprecations/pending-removal-in-future.rst:137 -msgid "``splithost()``" -msgstr "``splithost()``" - -#: ../../deprecations/pending-removal-in-future.rst:138 -msgid "``splitnport()``" -msgstr "``splitnport()``" - -#: ../../deprecations/pending-removal-in-future.rst:139 -msgid "``splitpasswd()``" -msgstr "``splitpasswd()``" - -#: ../../deprecations/pending-removal-in-future.rst:140 -msgid "``splitport()``" -msgstr "``splitport()``" - -#: ../../deprecations/pending-removal-in-future.rst:141 -msgid "``splitquery()``" -msgstr "``splitquery()``" - -#: ../../deprecations/pending-removal-in-future.rst:142 -msgid "``splittag()``" -msgstr "``splittag()``" - -#: ../../deprecations/pending-removal-in-future.rst:143 -msgid "``splittype()``" -msgstr "``splittype()``" - -#: ../../deprecations/pending-removal-in-future.rst:144 -msgid "``splituser()``" -msgstr "``splituser()``" - -#: ../../deprecations/pending-removal-in-future.rst:145 -msgid "``splitvalue()``" -msgstr "``splitvalue()``" - -#: ../../deprecations/pending-removal-in-future.rst:146 -msgid "``to_bytes()``" -msgstr "``to_bytes()``" - -#: ../../deprecations/pending-removal-in-future.rst:148 -msgid "" -":mod:`wsgiref`: ``SimpleHandler.stdout.write()`` should not do partial " -"writes." -msgstr ":mod:`wsgiref`：``SimpleHandler.stdout.write()`` 不應該進行部分寫入。" - -#: ../../deprecations/pending-removal-in-future.rst:151 -msgid "" -":mod:`xml.etree.ElementTree`: Testing the truth value of an :class:`~xml." -"etree.ElementTree.Element` is deprecated. In a future release it will always " -"return ``True``. Prefer explicit ``len(elem)`` or ``elem is not None`` tests " -"instead." -msgstr "" -":mod:`xml.etree.ElementTree`：已棄用對 :class:`~xml.etree.ElementTree." -"Element` 的真值測試。在未來版本中，它將始終回傳 ``True``。請改用明確的 " -"``len(elem)`` 或 ``elem is not None`` 測試。" - -#: ../../deprecations/pending-removal-in-future.rst:156 -msgid "" -":func:`sys._clear_type_cache` is deprecated: use :func:`sys." -"_clear_internal_caches` instead." -msgstr "" -":func:`sys._clear_type_cache` 已被棄用：請改用 :func:`sys." -"_clear_internal_caches`。" - -#: ../../deprecations/index.rst:17 -msgid "C API deprecations" -msgstr "C API 的棄用項目" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:4 -msgid "" -"The :c:func:`PyImport_ImportModuleNoBlock`: Use :c:func:" -"`PyImport_ImportModule` instead." -msgstr "" -":c:func:`PyImport_ImportModuleNoBlock`：請改用 :c:func:" -"`PyImport_ImportModule`。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:6 -msgid "" -":c:func:`PyWeakref_GetObject` and :c:func:`PyWeakref_GET_OBJECT`: Use :c:" -"func:`PyWeakref_GetRef` instead. The `pythoncapi-compat project `__ can be used to get :c:func:" -"`PyWeakref_GetRef` on Python 3.12 and older." -msgstr "" -":c:func:`PyWeakref_GetObject` 和 :c:func:`PyWeakref_GET_OBJECT`：請改用 :c:" -"func:`PyWeakref_GetRef`。可以使用 `pythoncapi-compat 專案 `__\\ 來為 Python 3.12 和更早版本取得 :c:func:" -"`PyWeakref_GetRef`。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:10 -msgid "" -":c:type:`Py_UNICODE` type and the :c:macro:`!Py_UNICODE_WIDE` macro: Use :c:" -"type:`wchar_t` instead." -msgstr "" -":c:type:`Py_UNICODE` 型別與 :c:macro:`!Py_UNICODE_WIDE` 巨集：請改用 :c:type:" -"`wchar_t`。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:12 -msgid "" -":c:func:`!PyUnicode_AsDecodedObject`: Use :c:func:`PyCodec_Decode` instead." -msgstr "" -":c:func:`!PyUnicode_AsDecodedObject`：請改用 :c:func:`PyCodec_Decode`。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:14 -msgid "" -":c:func:`!PyUnicode_AsDecodedUnicode`: Use :c:func:`PyCodec_Decode` instead; " -"Note that some codecs (for example, \"base64\") may return a type other " -"than :class:`str`, such as :class:`bytes`." -msgstr "" -":c:func:`!PyUnicode_AsDecodedUnicode`：請改用 :c:func:`PyCodec_Decode`；請注" -"意某些編解碼器（例如 \"base64\"）可能會回傳非 :class:`str` 的型別，例如 :" -"class:`bytes`。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:17 -msgid "" -":c:func:`!PyUnicode_AsEncodedObject`: Use :c:func:`PyCodec_Encode` instead." -msgstr "" -":c:func:`!PyUnicode_AsEncodedObject`：請改用 :c:func:`PyCodec_Encode`。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:19 -msgid "" -":c:func:`!PyUnicode_AsEncodedUnicode`: Use :c:func:`PyCodec_Encode` instead; " -"Note that some codecs (for example, \"base64\") may return a type other " -"than :class:`bytes`, such as :class:`str`." -msgstr "" -":c:func:`!PyUnicode_AsEncodedUnicode`：請改用 :c:func:`PyCodec_Encode`；請注" -"意某些編解碼器（例如 \"base64\"）可能會回傳非 :class:`bytes` 的型別，例如 :" -"class:`str`。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:22 -msgid "Python initialization functions, deprecated in Python 3.13:" -msgstr "Python 初始化函式，自 Python 3.13 起已被棄用：" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:24 -msgid "" -":c:func:`Py_GetPath`: Use :c:func:`PyConfig_Get(\"module_search_paths\") " -"` (:data:`sys.path`) instead." -msgstr "" -":c:func:`Py_GetPath`：請改用 :c:func:`PyConfig_Get(\"module_search_paths\") " -"` (:data:`sys.path`)。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:27 -msgid "" -":c:func:`Py_GetPrefix`: Use :c:func:`PyConfig_Get(\"base_prefix\") " -"` (:data:`sys.base_prefix`) instead. Use :c:func:" -"`PyConfig_Get(\"prefix\") ` (:data:`sys.prefix`) if :ref:" -"`virtual environments ` need to be handled." -msgstr "" -":c:func:`Py_GetPrefix`：請改用 :c:func:`PyConfig_Get(\"base_prefix\") " -"` (:data:`sys.base_prefix`)。如果需要處理\\ :ref:`虛擬環境 " -"`，請改用 :c:func:`PyConfig_Get(\"prefix\") ` (:data:" -"`sys.prefix`)。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:32 -msgid "" -":c:func:`Py_GetExecPrefix`: Use :c:func:`PyConfig_Get(\"base_exec_prefix\") " -"` (:data:`sys.base_exec_prefix`) instead. Use :c:func:" -"`PyConfig_Get(\"exec_prefix\") ` (:data:`sys.exec_prefix`) if :" -"ref:`virtual environments ` need to be handled." -msgstr "" -":c:func:`Py_GetExecPrefix`：請改用 :c:func:" -"`PyConfig_Get(\"base_exec_prefix\") ` (:data:`sys." -"base_exec_prefix`)。如果需要處理\\ :ref:`虛擬環境 `，請改用 :c:" -"func:`PyConfig_Get(\"exec_prefix\") ` (:data:`sys." -"exec_prefix`)。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:38 -msgid "" -":c:func:`Py_GetProgramFullPath`: Use :c:func:`PyConfig_Get(\"executable\") " -"` (:data:`sys.executable`) instead." -msgstr "" -":c:func:`Py_GetProgramFullPath`：請改用 :c:func:" -"`PyConfig_Get(\"executable\") ` (:data:`sys.executable`)。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:41 -msgid "" -":c:func:`Py_GetProgramName`: Use :c:func:`PyConfig_Get(\"executable\") " -"` (:data:`sys.executable`) instead." -msgstr "" -":c:func:`Py_GetProgramName`：請改用 :c:func:`PyConfig_Get(\"executable\") " -"` (:data:`sys.executable`)。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:44 -msgid "" -":c:func:`Py_GetPythonHome`: Use :c:func:`PyConfig_Get(\"home\") " -"` or the :envvar:`PYTHONHOME` environment variable instead." -msgstr "" -":c:func:`Py_GetPythonHome`：請改用 :c:func:`PyConfig_Get(\"home\") " -"` 或 :envvar:`PYTHONHOME` 環境變數。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:48 -msgid "" -"The `pythoncapi-compat project `__ can be used to get :c:func:`PyConfig_Get` on Python 3.13 and older." -msgstr "" -"`pythoncapi-compat 專案 `__ 可" -"以用來為 Python 3.13 和更早版本取得 :c:func:`PyConfig_Get`。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:52 -msgid "" -"Functions to configure Python's initialization, deprecated in Python 3.11:" -msgstr "用於配置 Python 初始化的函式，自 Python 3.11 起已被棄用：" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:54 -msgid ":c:func:`!PySys_SetArgvEx()`: Set :c:member:`PyConfig.argv` instead." -msgstr ":c:func:`!PySys_SetArgvEx()`：請改用 :c:member:`PyConfig.argv`。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:56 -msgid ":c:func:`!PySys_SetArgv()`: Set :c:member:`PyConfig.argv` instead." -msgstr ":c:func:`!PySys_SetArgv()`：請改用 :c:member:`PyConfig.argv`。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:58 -msgid "" -":c:func:`!Py_SetProgramName()`: Set :c:member:`PyConfig.program_name` " -"instead." -msgstr "" -":c:func:`!Py_SetProgramName()`：請改用 :c:member:`PyConfig.program_name`。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:60 -msgid ":c:func:`!Py_SetPythonHome()`: Set :c:member:`PyConfig.home` instead." -msgstr ":c:func:`!Py_SetPythonHome()`：請改用 :c:member:`PyConfig.home`。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:62 -msgid "" -":c:func:`PySys_ResetWarnOptions`: Clear :data:`sys.warnoptions` and :data:`!" -"warnings.filters` instead." -msgstr "" -":c:func:`PySys_ResetWarnOptions`：請改為清除 :data:`sys.warnoptions` 和 :" -"data:`!warnings.filters`。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:65 -msgid "" -"The :c:func:`Py_InitializeFromConfig` API should be used with :c:type:" -"`PyConfig` instead." -msgstr "" -"應改用帶有 :c:type:`PyConfig` 的 :c:func:`Py_InitializeFromConfig` API。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:68 -msgid "Global configuration variables:" -msgstr "全域配置變數：" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:70 -msgid "" -":c:var:`Py_DebugFlag`: Use :c:member:`PyConfig.parser_debug` or :c:func:" -"`PyConfig_Get(\"parser_debug\") ` instead." -msgstr "" -":c:var:`Py_DebugFlag`：請改用 :c:member:`PyConfig.parser_debug` 或 :c:func:" -"`PyConfig_Get(\"parser_debug\") `。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:73 -msgid "" -":c:var:`Py_VerboseFlag`: Use :c:member:`PyConfig.verbose` or :c:func:" -"`PyConfig_Get(\"verbose\") ` instead." -msgstr "" -":c:var:`Py_VerboseFlag`：請改用 :c:member:`PyConfig.verbose` 或 :c:func:" -"`PyConfig_Get(\"verbose\") `。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:76 -msgid "" -":c:var:`Py_QuietFlag`: Use :c:member:`PyConfig.quiet` or :c:func:" -"`PyConfig_Get(\"quiet\") ` instead." -msgstr "" -":c:var:`Py_QuietFlag`：請改用 :c:member:`PyConfig.quiet` 或 :c:func:" -"`PyConfig_Get(\"quiet\") `。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:79 -msgid "" -":c:var:`Py_InteractiveFlag`: Use :c:member:`PyConfig.interactive` or :c:func:" -"`PyConfig_Get(\"interactive\") ` instead." -msgstr "" -":c:var:`Py_InteractiveFlag`：請改用 :c:member:`PyConfig.interactive` 或 :c:" -"func:`PyConfig_Get(\"interactive\") `。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:82 -msgid "" -":c:var:`Py_InspectFlag`: Use :c:member:`PyConfig.inspect` or :c:func:" -"`PyConfig_Get(\"inspect\") ` instead." -msgstr "" -":c:var:`Py_InspectFlag`：請改用 :c:member:`PyConfig.inspect` 或 :c:func:" -"`PyConfig_Get(\"inspect\") `。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:85 -msgid "" -":c:var:`Py_OptimizeFlag`: Use :c:member:`PyConfig.optimization_level` or :c:" -"func:`PyConfig_Get(\"optimization_level\") ` instead." -msgstr "" -":c:var:`Py_OptimizeFlag`：請改用 :c:member:`PyConfig.optimization_level` 或 :" -"c:func:`PyConfig_Get(\"optimization_level\") `。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:88 -msgid "" -":c:var:`Py_NoSiteFlag`: Use :c:member:`PyConfig.site_import` or :c:func:" -"`PyConfig_Get(\"site_import\") ` instead." -msgstr "" -":c:var:`Py_NoSiteFlag`：請改用 :c:member:`PyConfig.site_import` 或 :c:func:" -"`PyConfig_Get(\"site_import\") `。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:91 -msgid "" -":c:var:`Py_BytesWarningFlag`: Use :c:member:`PyConfig.bytes_warning` or :c:" -"func:`PyConfig_Get(\"bytes_warning\") ` instead." -msgstr "" -":c:var:`Py_BytesWarningFlag`：請改用 :c:member:`PyConfig.bytes_warning` 或 :" -"c:func:`PyConfig_Get(\"bytes_warning\") `。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:94 -msgid "" -":c:var:`Py_FrozenFlag`: Use :c:member:`PyConfig.pathconfig_warnings` or :c:" -"func:`PyConfig_Get(\"pathconfig_warnings\") ` instead." -msgstr "" -":c:var:`Py_FrozenFlag`：請改用 :c:member:`PyConfig.pathconfig_warnings` 或 :" -"c:func:`PyConfig_Get(\"pathconfig_warnings\") `。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:97 -msgid "" -":c:var:`Py_IgnoreEnvironmentFlag`: Use :c:member:`PyConfig.use_environment` " -"or :c:func:`PyConfig_Get(\"use_environment\") ` instead." -msgstr "" -":c:var:`Py_IgnoreEnvironmentFlag`：請改用 :c:member:`PyConfig." -"use_environment` 或 :c:func:`PyConfig_Get(\"use_environment\") " -"`。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:100 -msgid "" -":c:var:`Py_DontWriteBytecodeFlag`: Use :c:member:`PyConfig.write_bytecode` " -"or :c:func:`PyConfig_Get(\"write_bytecode\") ` instead." -msgstr "" -":c:var:`Py_DontWriteBytecodeFlag`：請改用 :c:member:`PyConfig." -"write_bytecode` 或 :c:func:`PyConfig_Get(\"write_bytecode\") " -"`。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:103 -msgid "" -":c:var:`Py_NoUserSiteDirectory`: Use :c:member:`PyConfig." -"user_site_directory` or :c:func:`PyConfig_Get(\"user_site_directory\") " -"` instead." -msgstr "" -":c:var:`Py_NoUserSiteDirectory`：請改用 :c:member:`PyConfig." -"user_site_directory` 或 :c:func:`PyConfig_Get(\"user_site_directory\") " -"`。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:106 -msgid "" -":c:var:`Py_UnbufferedStdioFlag`: Use :c:member:`PyConfig.buffered_stdio` or :" -"c:func:`PyConfig_Get(\"buffered_stdio\") ` instead." -msgstr "" -":c:var:`Py_UnbufferedStdioFlag`：請改用 :c:member:`PyConfig.buffered_stdio` " -"或 :c:func:`PyConfig_Get(\"buffered_stdio\") `。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:109 -msgid "" -":c:var:`Py_HashRandomizationFlag`: Use :c:member:`PyConfig.use_hash_seed` " -"and :c:member:`PyConfig.hash_seed` or :c:func:`PyConfig_Get(\"hash_seed\") " -"` instead." -msgstr "" -":c:var:`Py_HashRandomizationFlag`：請改用 :c:member:`PyConfig.use_hash_seed` " -"和 :c:member:`PyConfig.hash_seed` 或 :c:func:`PyConfig_Get(\"hash_seed\") " -"`。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:113 -msgid "" -":c:var:`Py_IsolatedFlag`: Use :c:member:`PyConfig.isolated` or :c:func:" -"`PyConfig_Get(\"isolated\") ` instead." -msgstr "" -":c:var:`Py_IsolatedFlag`：請改用 :c:member:`PyConfig.isolated` 或 :c:func:" -"`PyConfig_Get(\"isolated\") `。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:116 -msgid "" -":c:var:`Py_LegacyWindowsFSEncodingFlag`: Use :c:member:`PyPreConfig." -"legacy_windows_fs_encoding` or :c:func:" -"`PyConfig_Get(\"legacy_windows_fs_encoding\") ` instead." -msgstr "" -":c:var:`Py_LegacyWindowsFSEncodingFlag`：請改用 :c:member:`PyPreConfig." -"legacy_windows_fs_encoding` 或 :c:func:" -"`PyConfig_Get(\"legacy_windows_fs_encoding\") `。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:119 -msgid "" -":c:var:`Py_LegacyWindowsStdioFlag`: Use :c:member:`PyConfig." -"legacy_windows_stdio` or :c:func:`PyConfig_Get(\"legacy_windows_stdio\") " -"` instead." -msgstr "" -":c:var:`Py_LegacyWindowsStdioFlag`：請改用 :c:member:`PyConfig." -"legacy_windows_stdio` 或 :c:func:`PyConfig_Get(\"legacy_windows_stdio\") " -"`。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:122 -msgid "" -":c:var:`!Py_FileSystemDefaultEncoding`, :c:var:`!" -"Py_HasFileSystemDefaultEncoding`: Use :c:member:`PyConfig." -"filesystem_encoding` or :c:func:`PyConfig_Get(\"filesystem_encoding\") " -"` instead." -msgstr "" -":c:var:`!Py_FileSystemDefaultEncoding`、:c:var:`!" -"Py_HasFileSystemDefaultEncoding`：請改用 :c:member:`PyConfig." -"filesystem_encoding` 或 :c:func:`PyConfig_Get(\"filesystem_encoding\") " -"`。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:125 -msgid "" -":c:var:`!Py_FileSystemDefaultEncodeErrors`: Use :c:member:`PyConfig." -"filesystem_errors` or :c:func:`PyConfig_Get(\"filesystem_errors\") " -"` instead." -msgstr "" -":c:var:`!Py_FileSystemDefaultEncodeErrors`：請改用 :c:member:`PyConfig." -"filesystem_errors` 或 :c:func:`PyConfig_Get(\"filesystem_errors\") " -"`。" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:128 -msgid "" -":c:var:`!Py_UTF8Mode`: Use :c:member:`PyPreConfig.utf8_mode` or :c:func:" -"`PyConfig_Get(\"utf8_mode\") ` instead. (see :c:func:" -"`Py_PreInitialize`)" -msgstr "" -":c:var:`!Py_UTF8Mode`：請改用 :c:member:`PyPreConfig.utf8_mode` 或 :c:func:" -"`PyConfig_Get(\"utf8_mode\") `。（請參閱 :c:func:" -"`Py_PreInitialize`）" - -#: ../../deprecations/c-api-pending-removal-in-3.15.rst:133 -msgid "" -"The :c:func:`Py_InitializeFromConfig` API should be used with :c:type:" -"`PyConfig` to set these options. Or :c:func:`PyConfig_Get` can be used to " -"get these options at runtime." -msgstr "" -"應改用帶有 :c:type:`PyConfig` 的 :c:func:`Py_InitializeFromConfig` API 來設定" -"這些選項。或者也可以使用 :c:func:`PyConfig_Get` 在執行時取得這些選項。" - -#: ../../deprecations/c-api-pending-removal-in-3.18.rst:4 -msgid "" -"The following private functions are deprecated and planned for removal in " -"Python 3.18:" -msgstr "以下私有函式已被棄用，並計劃在 Python 3.18 中移除：" - -#: ../../deprecations/c-api-pending-removal-in-3.18.rst:7 -msgid ":c:func:`!_PyBytes_Join`: use :c:func:`PyBytes_Join`." -msgstr ":c:func:`!_PyBytes_Join`：請改用 :c:func:`PyBytes_Join`。" - -#: ../../deprecations/c-api-pending-removal-in-3.18.rst:8 -msgid "" -":c:func:`!_PyDict_GetItemStringWithError`: use :c:func:" -"`PyDict_GetItemStringRef`." -msgstr "" -":c:func:`!_PyDict_GetItemStringWithError`：請改用 :c:func:" -"`PyDict_GetItemStringRef`。" - -#: ../../deprecations/c-api-pending-removal-in-3.18.rst:9 -msgid ":c:func:`!_PyDict_Pop()`: use :c:func:`PyDict_Pop`." -msgstr ":c:func:`!_PyDict_Pop()`：請改用 :c:func:`PyDict_Pop`。" - -#: ../../deprecations/c-api-pending-removal-in-3.18.rst:10 -msgid ":c:func:`!_PyLong_Sign()`: use :c:func:`PyLong_GetSign`." -msgstr ":c:func:`!_PyLong_Sign()`：請改用 :c:func:`PyLong_GetSign`。" - -#: ../../deprecations/c-api-pending-removal-in-3.18.rst:11 -msgid "" -":c:func:`!_PyLong_FromDigits` and :c:func:`!_PyLong_New`: use :c:func:" -"`PyLongWriter_Create`." -msgstr "" -":c:func:`!_PyLong_FromDigits` 和 :c:func:`!_PyLong_New`：請改用 :c:func:" -"`PyLongWriter_Create`。" - -#: ../../deprecations/c-api-pending-removal-in-3.18.rst:13 -msgid "" -":c:func:`!_PyThreadState_UncheckedGet`: use :c:func:" -"`PyThreadState_GetUnchecked`." -msgstr "" -":c:func:`!_PyThreadState_UncheckedGet`：請改用 :c:func:" -"`PyThreadState_GetUnchecked`。" - -#: ../../deprecations/c-api-pending-removal-in-3.18.rst:14 -msgid ":c:func:`!_PyUnicode_AsString`: use :c:func:`PyUnicode_AsUTF8`." -msgstr ":c:func:`!_PyUnicode_AsString`：請改用 :c:func:`PyUnicode_AsUTF8`。" - -#: ../../deprecations/c-api-pending-removal-in-3.18.rst:15 -msgid "" -":c:func:`!_PyUnicodeWriter_Init`: replace ``_PyUnicodeWriter_Init(&writer)`` " -"with :c:func:`writer = PyUnicodeWriter_Create(0) `." -msgstr "" -":c:func:`!_PyUnicodeWriter_Init`：將 ``_PyUnicodeWriter_Init(&writer)`` 替換" -"為 :c:func:`writer = PyUnicodeWriter_Create(0) `。" - -#: ../../deprecations/c-api-pending-removal-in-3.18.rst:18 -msgid "" -":c:func:`!_PyUnicodeWriter_Finish`: replace " -"``_PyUnicodeWriter_Finish(&writer)`` with :c:func:" -"`PyUnicodeWriter_Finish(writer) `." -msgstr "" -":c:func:`!_PyUnicodeWriter_Finish`：將 ``_PyUnicodeWriter_Finish(&writer)`` " -"替換為 :c:func:`PyUnicodeWriter_Finish(writer) `。" - -#: ../../deprecations/c-api-pending-removal-in-3.18.rst:21 -msgid "" -":c:func:`!_PyUnicodeWriter_Dealloc`: replace " -"``_PyUnicodeWriter_Dealloc(&writer)`` with :c:func:" -"`PyUnicodeWriter_Discard(writer) `." -msgstr "" -":c:func:`!_PyUnicodeWriter_Dealloc`：將 " -"``_PyUnicodeWriter_Dealloc(&writer)`` 替換為 :c:func:" -"`PyUnicodeWriter_Discard(writer) `。" - -#: ../../deprecations/c-api-pending-removal-in-3.18.rst:24 -msgid "" -":c:func:`!_PyUnicodeWriter_WriteChar`: replace " -"``_PyUnicodeWriter_WriteChar(&writer, ch)`` with :c:func:" -"`PyUnicodeWriter_WriteChar(writer, ch) `." -msgstr "" -":c:func:`!_PyUnicodeWriter_WriteChar`：將 " -"``_PyUnicodeWriter_WriteChar(&writer, ch)`` 替換為 :c:func:" -"`PyUnicodeWriter_WriteChar(writer, ch) `。" - -#: ../../deprecations/c-api-pending-removal-in-3.18.rst:27 -msgid "" -":c:func:`!_PyUnicodeWriter_WriteStr`: replace " -"``_PyUnicodeWriter_WriteStr(&writer, str)`` with :c:func:" -"`PyUnicodeWriter_WriteStr(writer, str) `." -msgstr "" -":c:func:`!_PyUnicodeWriter_WriteStr`：將 " -"``_PyUnicodeWriter_WriteStr(&writer, str)`` 替換為 :c:func:" -"`PyUnicodeWriter_WriteStr(writer, str) `。" - -#: ../../deprecations/c-api-pending-removal-in-3.18.rst:30 -msgid "" -":c:func:`!_PyUnicodeWriter_WriteSubstring`: replace " -"``_PyUnicodeWriter_WriteSubstring(&writer, str, start, end)`` with :c:func:" -"`PyUnicodeWriter_WriteSubstring(writer, str, start, end) " -"`." -msgstr "" -":c:func:`!_PyUnicodeWriter_WriteSubstring`：將 " -"``_PyUnicodeWriter_WriteSubstring(&writer, str, start, end)`` 替換為 :c:func:" -"`PyUnicodeWriter_WriteSubstring(writer, str, start, end) " -"`。" - -#: ../../deprecations/c-api-pending-removal-in-3.18.rst:33 -msgid "" -":c:func:`!_PyUnicodeWriter_WriteASCIIString`: replace " -"``_PyUnicodeWriter_WriteASCIIString(&writer, str)`` with :c:func:" -"`PyUnicodeWriter_WriteASCII(writer, str) `." -msgstr "" -":c:func:`!_PyUnicodeWriter_WriteASCIIString`：將 " -"``_PyUnicodeWriter_WriteASCIIString(&writer, str)`` 替換為 :c:func:" -"`PyUnicodeWriter_WriteASCII(writer, str) `。" - -#: ../../deprecations/c-api-pending-removal-in-3.18.rst:36 -msgid "" -":c:func:`!_PyUnicodeWriter_WriteLatin1String`: replace " -"``_PyUnicodeWriter_WriteLatin1String(&writer, str)`` with :c:func:" -"`PyUnicodeWriter_WriteUTF8(writer, str) `." -msgstr "" -":c:func:`!_PyUnicodeWriter_WriteLatin1String`：將 " -"``_PyUnicodeWriter_WriteLatin1String(&writer, str)`` 替換為 :c:func:" -"`PyUnicodeWriter_WriteUTF8(writer, str) `。" - -#: ../../deprecations/c-api-pending-removal-in-3.18.rst:39 -msgid ":c:func:`!_PyUnicodeWriter_Prepare`: (no replacement)." -msgstr ":c:func:`!_PyUnicodeWriter_Prepare`：（無替代方案）。" - -#: ../../deprecations/c-api-pending-removal-in-3.18.rst:40 -msgid ":c:func:`!_PyUnicodeWriter_PrepareKind`: (no replacement)." -msgstr ":c:func:`!_PyUnicodeWriter_PrepareKind`：（無替代方案）。" - -#: ../../deprecations/c-api-pending-removal-in-3.18.rst:41 -msgid ":c:func:`!_Py_HashPointer`: use :c:func:`Py_HashPointer`." -msgstr ":c:func:`!_Py_HashPointer`：請改用 :c:func:`Py_HashPointer`。" - -#: ../../deprecations/c-api-pending-removal-in-3.18.rst:42 -msgid ":c:func:`!_Py_fopen_obj`: use :c:func:`Py_fopen`." -msgstr ":c:func:`!_Py_fopen_obj`：請改用 :c:func:`Py_fopen`。" - -#: ../../deprecations/c-api-pending-removal-in-3.18.rst:44 -msgid "" -"The `pythoncapi-compat project `__ can be used to get these new public functions on Python 3.13 and older. " -"(Contributed by Victor Stinner in :gh:`128863`.)" -msgstr "" -"可以使用 `pythoncapi-compat project `__ 來取得這些於 Python 3.13 及更早版本的新公開函式。（由 Victor " -"Stinner 在 :gh:`128863` 貢獻）" - -#: ../../deprecations/c-api-pending-removal-in-future.rst:4 -msgid "" -"The following APIs are deprecated and will be removed, although there is " -"currently no date scheduled for their removal." -msgstr "下列 API 已被棄用並將會被移除，不過目前尚未訂定移除日期。" - -#: ../../deprecations/c-api-pending-removal-in-future.rst:7 -msgid ":c:macro:`Py_TPFLAGS_HAVE_FINALIZE`: Unneeded since Python 3.8." -msgstr ":c:macro:`Py_TPFLAGS_HAVE_FINALIZE`：自 Python 3.8 起不再需要" - -#: ../../deprecations/c-api-pending-removal-in-future.rst:9 -msgid ":c:func:`PyErr_Fetch`: Use :c:func:`PyErr_GetRaisedException` instead." -msgstr ":c:func:`PyErr_Fetch`：請改用 :c:func:`PyErr_GetRaisedException`。" - -#: ../../deprecations/c-api-pending-removal-in-future.rst:11 -msgid "" -":c:func:`PyErr_NormalizeException`: Use :c:func:`PyErr_GetRaisedException` " -"instead." -msgstr "" -":c:func:`PyErr_NormalizeException`：請改用 :c:func:" -"`PyErr_GetRaisedException`。" - -#: ../../deprecations/c-api-pending-removal-in-future.rst:13 -msgid "" -":c:func:`PyErr_Restore`: Use :c:func:`PyErr_SetRaisedException` instead." -msgstr ":c:func:`PyErr_Restore`：請改用 :c:func:`PyErr_SetRaisedException`。" - -#: ../../deprecations/c-api-pending-removal-in-future.rst:15 -msgid "" -":c:func:`PyModule_GetFilename`: Use :c:func:`PyModule_GetFilenameObject` " -"instead." -msgstr "" -":c:func:`PyModule_GetFilename`：請改用 :c:func:`PyModule_GetFilenameObject`。" - -#: ../../deprecations/c-api-pending-removal-in-future.rst:17 -msgid ":c:func:`PyOS_AfterFork`: Use :c:func:`PyOS_AfterFork_Child` instead." -msgstr ":c:func:`PyOS_AfterFork`：請改用 :c:func:`PyOS_AfterFork_Child`。" - -#: ../../deprecations/c-api-pending-removal-in-future.rst:19 -msgid "" -":c:func:`PySlice_GetIndicesEx`: Use :c:func:`PySlice_Unpack` and :c:func:" -"`PySlice_AdjustIndices` instead." -msgstr "" -":c:func:`PySlice_GetIndicesEx`：請改用 :c:func:`PySlice_Unpack` 和 :c:func:" -"`PySlice_AdjustIndices`。" - -#: ../../deprecations/c-api-pending-removal-in-future.rst:21 -msgid ":c:func:`PyUnicode_READY`: Unneeded since Python 3.12" -msgstr ":c:func:`PyUnicode_READY`：自 Python 3.12 起不再需要" - -#: ../../deprecations/c-api-pending-removal-in-future.rst:23 -msgid ":c:func:`!PyErr_Display`: Use :c:func:`PyErr_DisplayException` instead." -msgstr ":c:func:`!PyErr_Display`：請改用 :c:func:`PyErr_DisplayException`。" - -#: ../../deprecations/c-api-pending-removal-in-future.rst:25 -msgid "" -":c:func:`!_PyErr_ChainExceptions`: Use :c:func:`!_PyErr_ChainExceptions1` " -"instead." -msgstr "" -":c:func:`!_PyErr_ChainExceptions`：請改用 ``_PyErr_ChainExceptions1``。" - -#: ../../deprecations/c-api-pending-removal-in-future.rst:27 -msgid "" -":c:member:`!PyBytesObject.ob_shash` member: call :c:func:`PyObject_Hash` " -"instead." -msgstr "" -":c:member:`!PyBytesObject.ob_shash` 成員：請改為呼叫 :c:func:" -"`PyObject_Hash`。" - -#: ../../deprecations/c-api-pending-removal-in-future.rst:29 -msgid "Thread Local Storage (TLS) API:" -msgstr "執行緒局部儲存 (Thread Local Storage, TLS) API：" - -#: ../../deprecations/c-api-pending-removal-in-future.rst:31 -msgid "" -":c:func:`PyThread_create_key`: Use :c:func:`PyThread_tss_alloc` instead." -msgstr ":c:func:`PyThread_create_key`：請改用 :c:func:`PyThread_tss_alloc`。" - -#: ../../deprecations/c-api-pending-removal-in-future.rst:33 -msgid ":c:func:`PyThread_delete_key`: Use :c:func:`PyThread_tss_free` instead." -msgstr ":c:func:`PyThread_delete_key`：請改用 :c:func:`PyThread_tss_free`。" - -#: ../../deprecations/c-api-pending-removal-in-future.rst:35 -msgid "" -":c:func:`PyThread_set_key_value`: Use :c:func:`PyThread_tss_set` instead." -msgstr ":c:func:`PyThread_set_key_value`：請改用 :c:func:`PyThread_tss_set`。" - -#: ../../deprecations/c-api-pending-removal-in-future.rst:37 -msgid "" -":c:func:`PyThread_get_key_value`: Use :c:func:`PyThread_tss_get` instead." -msgstr ":c:func:`PyThread_get_key_value`：請改用 :c:func:`PyThread_tss_get`。" - -#: ../../deprecations/c-api-pending-removal-in-future.rst:39 -msgid "" -":c:func:`PyThread_delete_key_value`: Use :c:func:`PyThread_tss_delete` " -"instead." -msgstr "" -":c:func:`PyThread_delete_key_value`：請改用 :c:func:`PyThread_tss_delete`。" - -#: ../../deprecations/c-api-pending-removal-in-future.rst:41 -msgid ":c:func:`PyThread_ReInitTLS`: Unneeded since Python 3.7." -msgstr ":c:func:`PyThread_ReInitTLS`：自 Python 3.7 起不再需要。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-01-07 00:14+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \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" + +#: ../../deprecations/index.rst:2 +msgid "Deprecations" +msgstr "已棄用項目" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:2 +#: ../../deprecations/pending-removal-in-3.15.rst:2 +msgid "Pending removal in Python 3.15" +msgstr "Python 3.15 中待移除的項目" + +#: ../../deprecations/pending-removal-in-3.15.rst:4 +#: ../../deprecations/pending-removal-in-3.16.rst:4 +msgid "The import system:" +msgstr "引入系統 (import system)：" + +#: ../../deprecations/pending-removal-in-3.15.rst:6 +msgid "" +"Setting :attr:`~module.__cached__` on a module while failing to set :attr:" +"`__spec__.cached ` is deprecated. In " +"Python 3.15, :attr:`!__cached__` will cease to be set or take into " +"consideration by the import system or standard library. (:gh:`97879`)" +msgstr "" +"在模組上設定 :attr:`~module.__cached__` 而沒有設定 :attr:`__spec__.cached " +"` 的做法已被棄用。在 Python 3.15 中，" +"引入系統或標準函式庫將不再設定或考慮 :attr:`!__cached__`。(:gh:`97879`)" + +#: ../../deprecations/pending-removal-in-3.15.rst:11 +msgid "" +"Setting :attr:`~module.__package__` on a module while failing to set :attr:" +"`__spec__.parent ` is deprecated. In " +"Python 3.15, :attr:`!__package__` will cease to be set or take into " +"consideration by the import system or standard library. (:gh:`97879`)" +msgstr "" +"在模組上設定 :attr:`~module.__package__` 而沒有設定 :attr:`__spec__.parent " +"` 的做法已被棄用。在 Python 3.15 中，" +"引入系統或標準函式庫將不再設定或考慮 :attr:`!__package__`。(:gh:`97879`)" + +#: ../../deprecations/pending-removal-in-3.15.rst:16 +#: ../../deprecations/pending-removal-in-3.19.rst:4 +msgid ":mod:`ctypes`:" +msgstr ":mod:`ctypes`：" + +#: ../../deprecations/pending-removal-in-3.15.rst:18 +msgid "" +"The undocumented :func:`!ctypes.SetPointerType` function has been deprecated " +"since Python 3.13." +msgstr "" +"自 Python 3.13 起，未記錄的 :func:`!ctypes.SetPointerType` 函式已被棄用。" + +#: ../../deprecations/pending-removal-in-3.15.rst:21 +msgid ":mod:`http.server`:" +msgstr ":mod:`http.server`：" + +#: ../../deprecations/pending-removal-in-3.15.rst:23 +msgid "" +"The obsolete and rarely used :class:`~http.server.CGIHTTPRequestHandler` has " +"been deprecated since Python 3.13. No direct replacement exists. *Anything* " +"is better than CGI to interface a web server with a request handler." +msgstr "" +"過時且很少使用的 :class:`~http.server.CGIHTTPRequestHandler` 自 Python 3.13 " +"起已被棄用。不存在直接的替代。*任何東西*\\ 都比 CGI 更好地將 Web 伺服器與請求" +"處理程序介接起來。" + +#: ../../deprecations/pending-removal-in-3.15.rst:29 +msgid "" +"The :option:`!--cgi` flag to the :program:`python -m http.server` command-" +"line interface has been deprecated since Python 3.13." +msgstr "" +"自 Python 3.13 起，:program:`python -m http.server` 命令列介面的 :option:`!--" +"cgi` 旗標已被棄用。" + +#: ../../deprecations/pending-removal-in-3.15.rst:32 +#: ../../deprecations/pending-removal-in-future.rst:63 +msgid ":mod:`importlib`:" +msgstr ":mod:`importlib`：" + +#: ../../deprecations/pending-removal-in-3.15.rst:34 +msgid "``load_module()`` method: use ``exec_module()`` instead." +msgstr "``load_module()`` method：請改用 ``exec_module()``。" + +#: ../../deprecations/pending-removal-in-3.15.rst:36 +msgid ":class:`locale`:" +msgstr ":class:`locale`：" + +#: ../../deprecations/pending-removal-in-3.15.rst:38 +msgid "" +"The :func:`~locale.getdefaultlocale` function has been deprecated since " +"Python 3.11. Its removal was originally planned for Python 3.13 (:gh:" +"`90817`), but has been postponed to Python 3.15. Use :func:`~locale." +"getlocale`, :func:`~locale.setlocale`, and :func:`~locale.getencoding` " +"instead. (Contributed by Hugo van Kemenade in :gh:`111187`.)" +msgstr "" +":func:`~locale.getdefaultlocale` 已在 Python 3.11 中被棄用，原本計劃在 " +"Python 3.13 中移除 (:gh:`90817`)，但被延後至 Python 3.15。請改用 :func:" +"`~locale.getlocale`、:func:`~locale.setlocale` 和 :func:`~locale." +"getencoding`。 (由 Hugo van Kemenade 於 :gh:`111187` 貢獻。)" + +#: ../../deprecations/pending-removal-in-3.15.rst:46 +msgid ":mod:`pathlib`:" +msgstr ":mod:`pathlib`：" + +#: ../../deprecations/pending-removal-in-3.15.rst:48 +msgid "" +":meth:`.PurePath.is_reserved` has been deprecated since Python 3.13. Use :" +"func:`os.path.isreserved` to detect reserved paths on Windows." +msgstr "" +":meth:`.PurePath.is_reserved` 已自 Python 3.13 被棄用。請用 :func:`os.path." +"isreserved` 來偵測 Windows 上的保留路徑。" + +#: ../../deprecations/pending-removal-in-3.15.rst:52 +msgid ":mod:`platform`:" +msgstr ":mod:`platform`：" + +#: ../../deprecations/pending-removal-in-3.15.rst:54 +msgid "" +":func:`~platform.java_ver` has been deprecated since Python 3.13. This " +"function is only useful for Jython support, has a confusing API, and is " +"largely untested." +msgstr "" +"自 Python 3.13 起，:func:`~platform.java_ver` 已被棄用。此函式僅對 Jython 支" +"援有用，具有令人困惑的 API，基本上未經測試。" + +#: ../../deprecations/pending-removal-in-3.15.rst:58 +#: ../../deprecations/pending-removal-in-3.16.rst:96 +msgid ":mod:`sysconfig`:" +msgstr ":mod:`sysconfig`：" + +#: ../../deprecations/pending-removal-in-3.15.rst:60 +msgid "" +"The *check_home* argument of :func:`sysconfig.is_python_build` has been " +"deprecated since Python 3.12." +msgstr "" +":func:`sysconfig.is_python_build` 的 *check_home* 引數自 Python 3.12 起已被棄" +"用。" + +#: ../../deprecations/pending-removal-in-3.15.rst:63 +msgid ":mod:`threading`:" +msgstr ":mod:`threading`：" + +#: ../../deprecations/pending-removal-in-3.15.rst:65 +msgid "" +":func:`~threading.RLock` will take no arguments in Python 3.15. Passing any " +"arguments has been deprecated since Python 3.14, as the Python version does " +"not permit any arguments, but the C version allows any number of positional " +"or keyword arguments, ignoring every argument." +msgstr "" +":func:`~threading.RLock` 在 Python 3.15 中將不接受任何引數。自 Python 3.14 " +"起，傳遞任何引數的用法已被棄用，因為 Python 版本不允許任何引數，但 C 版本允許" +"任意數量的位置或關鍵字引數，並忽略每個引數。" + +#: ../../deprecations/pending-removal-in-3.15.rst:71 +msgid ":mod:`types`:" +msgstr ":mod:`types`：" + +#: ../../deprecations/pending-removal-in-3.15.rst:73 +msgid "" +":class:`types.CodeType`: Accessing :attr:`~codeobject.co_lnotab` was " +"deprecated in :pep:`626` since 3.10 and was planned to be removed in 3.12, " +"but it only got a proper :exc:`DeprecationWarning` in 3.12. May be removed " +"in 3.15. (Contributed by Nikita Sobolev in :gh:`101866`.)" +msgstr "" +":class:`types.CodeType`：自 3.10 起，存取 :attr:`~codeobject.co_lnotab` 已" +"在 :pep:`626` 中被棄用，並計劃在 3.12 中移除，但只在 3.12 中於適當時發出 :" +"exc:`DeprecationWarning`。可能在 3.15 中移除。（由 Nikita Sobolev 於 :gh:" +"`101866` 貢獻。）" + +#: ../../deprecations/pending-removal-in-3.15.rst:80 +#: ../../deprecations/pending-removal-in-3.17.rst:26 +msgid ":mod:`typing`:" +msgstr ":mod:`typing`：" + +#: ../../deprecations/pending-removal-in-3.15.rst:82 +msgid "" +"The undocumented keyword argument syntax for creating :class:`~typing." +"NamedTuple` classes (for example, ``Point = NamedTuple(\"Point\", x=int, " +"y=int)``) has been deprecated since Python 3.13. Use the class-based syntax " +"or the functional syntax instead." +msgstr "" +"用於建立 :class:`~typing.NamedTuple` 類別的未以文件記錄之關鍵字引數語法 " +"(``Point = NamedTuple(\"Point\", x=int, y=int)``) 已自 Python 3.13 棄用。請改" +"用基於類別的語法或函式語法 (functional syntax)。" + +#: ../../deprecations/pending-removal-in-3.15.rst:88 +msgid "" +"When using the functional syntax of :class:`~typing.TypedDict`\\s, failing " +"to pass a value to the *fields* parameter (``TD = TypedDict(\"TD\")``) or " +"passing ``None`` (``TD = TypedDict(\"TD\", None)``) has been deprecated " +"since Python 3.13. Use ``class TD(TypedDict): pass`` or ``TD = " +"TypedDict(\"TD\", {})`` to create a TypedDict with zero field." +msgstr "" +"當使用 :class:`~typing.TypedDict` 的函式語法時，未傳遞值給 *fields* 參數 " +"(``TD = TypedDict(\"TD\")``) 或傳遞 ``None`` (``TD = TypedDict(\"TD\", " +"None)``) 的做法自 Python 3.13 起已被棄用。請使用 ``class TD(TypedDict): " +"pass`` 或 ``TD = TypedDict(\"TD\", {})`` 來建立具有零個欄位的 TypedDict。" + +#: ../../deprecations/pending-removal-in-3.15.rst:95 +msgid "" +"The :func:`typing.no_type_check_decorator` decorator function has been " +"deprecated since Python 3.13. After eight years in the :mod:`typing` module, " +"it has yet to be supported by any major type checker." +msgstr "" +"自 Python 3.13 起，:func:`typing.no_type_check_decorator` 裝飾器函式已被棄" +"用。在 :mod:`typing` 模組中使用了八年之後，它尚未得到任何主要型別檢查器的支" +"援。" + +#: ../../deprecations/pending-removal-in-3.15.rst:100 +msgid ":mod:`wave`:" +msgstr ":mod:`wave`：" + +#: ../../deprecations/pending-removal-in-3.15.rst:102 +msgid "" +"The :meth:`~wave.Wave_read.getmark`, :meth:`!setmark`, and :meth:`~wave." +"Wave_read.getmarkers` methods of the :class:`~wave.Wave_read` and :class:" +"`~wave.Wave_write` classes have been deprecated since Python 3.13." +msgstr "" +"已棄用 :class:`~wave.Wave_read` 和 :class:`~wave.Wave_write` 類別的 :meth:" +"`~wave.Wave_read.getmark`、:meth:`!setmark` 和 :meth:`~wave.Wave_read." +"getmarkers` 方法自 Python 3.13 被棄用。" + +#: ../../deprecations/pending-removal-in-3.15.rst:107 +msgid ":mod:`zipimport`:" +msgstr ":mod:`zipimport`：" + +#: ../../deprecations/pending-removal-in-3.15.rst:109 +msgid "" +":meth:`~zipimport.zipimporter.load_module` has been deprecated since Python " +"3.10. Use :meth:`~zipimport.zipimporter.exec_module` instead. (Contributed " +"by Jiahao Li in :gh:`125746`.)" +msgstr "" +":meth:`~zipimport.zipimporter.load_module` 自 Python 3.10 被棄用。請改用 :" +"meth:`~zipimport.zipimporter.exec_module`。（由 Jiahao Li 於 :gh:`125746` 貢" +"獻。）" + +#: ../../deprecations/pending-removal-in-3.16.rst:2 +msgid "Pending removal in Python 3.16" +msgstr "Python 3.16 中待移除的項目" + +#: ../../deprecations/pending-removal-in-3.16.rst:6 +msgid "" +"Setting :attr:`~module.__loader__` on a module while failing to set :attr:" +"`__spec__.loader ` is deprecated. In " +"Python 3.16, :attr:`!__loader__` will cease to be set or taken into " +"consideration by the import system or the standard library." +msgstr "" +"在模組上設定 :attr:`~module.__loader__` 而沒有設定 :attr:`__spec__.loader " +"` 的做法將於 Python 3.16 被棄用。在 " +"Python 3.16 中，引入系統或標準函式庫將不再設定或考慮 :attr:`!__loader__`。" + +#: ../../deprecations/pending-removal-in-3.16.rst:11 +msgid ":mod:`array`:" +msgstr ":mod:`array`：" + +#: ../../deprecations/pending-removal-in-3.16.rst:13 +msgid "" +"The ``'u'`` format code (:c:type:`wchar_t`) has been deprecated in " +"documentation since Python 3.3 and at runtime since Python 3.13. Use the " +"``'w'`` format code (:c:type:`Py_UCS4`) for Unicode characters instead." +msgstr "" +"自 Python 3.3 起，``'u'`` 格式碼 (:c:type:`wchar_t`) 在文件中已被棄用，自 " +"Python 3.13 起在 runtime 已被棄用。請使用 ``'w'`` 格式碼 (:c:type:`Py_UCS4`) " +"來取代 Unicode 字元。" + +#: ../../deprecations/pending-removal-in-3.16.rst:19 +msgid ":mod:`asyncio`:" +msgstr ":mod:`asyncio`：" + +#: ../../deprecations/pending-removal-in-3.16.rst:21 +msgid "" +":func:`!asyncio.iscoroutinefunction` is deprecated and will be removed in " +"Python 3.16; use :func:`inspect.iscoroutinefunction` instead. (Contributed " +"by Jiahao Li and Kumar Aditya in :gh:`122875`.)" +msgstr "" +":func:`!asyncio.iscoroutinefunction` 已被棄用並將在 Python 3.16 中移除；請改" +"用 :func:`inspect.iscoroutinefunction`。（由 Jiahao Li 和 Kumar Aditya 於 :" +"gh:`122875` 貢獻。）" + +#: ../../deprecations/pending-removal-in-3.16.rst:26 +msgid "" +":mod:`asyncio` policy system is deprecated and will be removed in Python " +"3.16. In particular, the following classes and functions are deprecated:" +msgstr "" +":mod:`asyncio` 策略系統已被棄用並將在 Python 3.16 中移除。特別是以下類別和函" +"式已被棄用：" + +#: ../../deprecations/pending-removal-in-3.16.rst:29 +msgid ":class:`asyncio.AbstractEventLoopPolicy`" +msgstr ":class:`asyncio.AbstractEventLoopPolicy`" + +#: ../../deprecations/pending-removal-in-3.16.rst:30 +msgid ":class:`asyncio.DefaultEventLoopPolicy`" +msgstr ":class:`asyncio.DefaultEventLoopPolicy`" + +#: ../../deprecations/pending-removal-in-3.16.rst:31 +msgid ":class:`asyncio.WindowsSelectorEventLoopPolicy`" +msgstr ":class:`asyncio.WindowsSelectorEventLoopPolicy`" + +#: ../../deprecations/pending-removal-in-3.16.rst:32 +msgid ":class:`asyncio.WindowsProactorEventLoopPolicy`" +msgstr ":class:`asyncio.WindowsProactorEventLoopPolicy`" + +#: ../../deprecations/pending-removal-in-3.16.rst:33 +msgid ":func:`asyncio.get_event_loop_policy`" +msgstr ":func:`asyncio.get_event_loop_policy`" + +#: ../../deprecations/pending-removal-in-3.16.rst:34 +msgid ":func:`asyncio.set_event_loop_policy`" +msgstr ":func:`asyncio.set_event_loop_policy`" + +#: ../../deprecations/pending-removal-in-3.16.rst:36 +msgid "" +"Users should use :func:`asyncio.run` or :class:`asyncio.Runner` with " +"*loop_factory* to use the desired event loop implementation." +msgstr "" +"使用者應該使用 :func:`asyncio.run` 或 :class:`asyncio.Runner` 搭配 " +"*loop_factory* 來使用所需的事件迴圈實作。" + +#: ../../deprecations/pending-removal-in-3.16.rst:39 +msgid "For example, to use :class:`asyncio.SelectorEventLoop` on Windows::" +msgstr "例如在 Windows 上使用 :class:`asyncio.SelectorEventLoop`： ::" + +#: ../../deprecations/pending-removal-in-3.16.rst:41 +msgid "" +"import asyncio\n" +"\n" +"async def main():\n" +" ...\n" +"\n" +"asyncio.run(main(), loop_factory=asyncio.SelectorEventLoop)" +msgstr "" +"import asyncio\n" +"\n" +"async def main():\n" +" ...\n" +"\n" +"asyncio.run(main(), loop_factory=asyncio.SelectorEventLoop)" + +#: ../../deprecations/pending-removal-in-3.16.rst:48 +msgid "(Contributed by Kumar Aditya in :gh:`127949`.)" +msgstr "（由 Kumar Aditya 於 :gh:`127949` 貢獻。）" + +#: ../../deprecations/pending-removal-in-3.16.rst:50 +#: ../../deprecations/pending-removal-in-future.rst:16 +msgid ":mod:`builtins`:" +msgstr ":mod:`builtins`：" + +#: ../../deprecations/pending-removal-in-3.16.rst:52 +msgid "" +"Bitwise inversion on boolean types, ``~True`` or ``~False`` has been " +"deprecated since Python 3.12, as it produces surprising and unintuitive " +"results (``-2`` and ``-1``). Use ``not x`` instead for the logical negation " +"of a Boolean. In the rare case that you need the bitwise inversion of the " +"underlying integer, convert to ``int`` explicitly (``~int(x)``)." +msgstr "" +"自 Python 3.12 起，布林型別的位元反轉 ``~True`` 或 ``~False`` 已被棄用，因為" +"它會產生不預期且不直觀的結果（``-2`` 和 ``-1``）。使用 ``not x`` 代替布林值的" +"邏輯否定。在極少數情況下，你需要對底層的整數進行位元反轉，請明確轉換為 " +"``~int(x)`` (``~int(x)``)。" + +#: ../../deprecations/pending-removal-in-3.16.rst:59 +msgid ":mod:`functools`:" +msgstr ":mod:`functools`：" + +#: ../../deprecations/pending-removal-in-3.16.rst:61 +msgid "" +"Calling the Python implementation of :func:`functools.reduce` with " +"*function* or *sequence* as keyword arguments has been deprecated since " +"Python 3.14." +msgstr "" +"自 Python 3.14 起，使用 *function* 或 *sequence* 關鍵字引數呼叫 :func:" +"`functools.reduce` 的 Python 實作已被棄用。" + +#: ../../deprecations/pending-removal-in-3.16.rst:64 +msgid ":mod:`logging`:" +msgstr ":mod:`logging`：" + +#: ../../deprecations/pending-removal-in-3.16.rst:66 +msgid "" +"Support for custom logging handlers with the *strm* argument is deprecated " +"and scheduled for removal in Python 3.16. Define handlers with the *stream* " +"argument instead. (Contributed by Mariusz Felisiak in :gh:`115032`.)" +msgstr "" +"對具有 *strm* 引數的自訂日誌記錄處理函式的支援已被棄用，並計劃在 Python 3.16 " +"中移除。請改用 *stream* 引數。（由 Mariusz Felisiak 於 :gh:`115032` 貢獻。）" + +#: ../../deprecations/pending-removal-in-3.16.rst:70 +msgid ":mod:`mimetypes`:" +msgstr ":mod:`mimetypes`：" + +#: ../../deprecations/pending-removal-in-3.16.rst:72 +msgid "" +"Valid extensions start with a '.' or are empty for :meth:`mimetypes." +"MimeTypes.add_type`. Undotted extensions are deprecated and will raise a :" +"exc:`ValueError` in Python 3.16. (Contributed by Hugo van Kemenade in :gh:" +"`75223`.)" +msgstr "" +"有效的副檔名以 '.' 開頭或對 :meth:`mimetypes.MimeTypes.add_type` 為空字串。未" +"加點的副檔名已被棄用，並將在 Python 3.16 中引發 :exc:`ValueError`。（由 Hugo " +"van Kemenade 於 :gh:`75223` 貢獻。）" + +#: ../../deprecations/pending-removal-in-3.16.rst:78 +msgid ":mod:`shutil`:" +msgstr ":mod:`shutil`：" + +#: ../../deprecations/pending-removal-in-3.16.rst:80 +msgid "" +"The :class:`!ExecError` exception has been deprecated since Python 3.14. It " +"has not been used by any function in :mod:`!shutil` since Python 3.4, and is " +"now an alias of :exc:`RuntimeError`." +msgstr "" +"自 Python 3.14 起，:class:`!ExecError` 例外已被棄用。自 Python 3.4 以來，它尚" +"未被 :mod:`!shutil` 中的任何函式使用，現在是 :exc:`RuntimeError` 的別名。" + +#: ../../deprecations/pending-removal-in-3.16.rst:85 +msgid ":mod:`symtable`:" +msgstr ":mod:`symtable`：" + +#: ../../deprecations/pending-removal-in-3.16.rst:87 +msgid "" +"The :meth:`Class.get_methods ` method has been " +"deprecated since Python 3.14." +msgstr "" +"自 Python 3.14 起，:meth:`Class.get_methods ` 方" +"法已被棄用。" + +#: ../../deprecations/pending-removal-in-3.16.rst:90 +msgid ":mod:`sys`:" +msgstr ":mod:`sys`：" + +#: ../../deprecations/pending-removal-in-3.16.rst:92 +msgid "" +"The :func:`~sys._enablelegacywindowsfsencoding` function has been deprecated " +"since Python 3.13. Use the :envvar:`PYTHONLEGACYWINDOWSFSENCODING` " +"environment variable instead." +msgstr "" +"自 Python 3.13 起，:func:`~sys._enablelegacywindowsfsencoding` 函式已被棄用。" +"請改用 :envvar:`PYTHONLEGACYWINDOWSFSENCODING` 環境變數。" + +#: ../../deprecations/pending-removal-in-3.16.rst:98 +msgid "" +"The :func:`!sysconfig.expand_makefile_vars` function has been deprecated " +"since Python 3.14. Use the ``vars`` argument of :func:`sysconfig.get_paths` " +"instead." +msgstr "" +"自 Python 3.14 起，:func:`!sysconfig.expand_makefile_vars` 函式已被棄用。請改" +"用 :func:`sysconfig.get_paths` 的 ``vars`` 引數。" + +#: ../../deprecations/pending-removal-in-3.16.rst:102 +msgid ":mod:`tarfile`:" +msgstr ":mod:`tarfile`：" + +#: ../../deprecations/pending-removal-in-3.16.rst:104 +msgid "" +"The undocumented and unused :attr:`!TarFile.tarfile` attribute has been " +"deprecated since Python 3.13." +msgstr "" +"自 Python 3.13 起，未以文件記錄和未被使用的 :attr:`!TarFile.tarfile` 屬性已被" +"棄用。" + +#: ../../deprecations/pending-removal-in-3.17.rst:2 +msgid "Pending removal in Python 3.17" +msgstr "Python 3.17 中待移除的項目" + +#: ../../deprecations/pending-removal-in-3.17.rst:4 +msgid ":mod:`collections.abc`:" +msgstr ":mod:`collections.abc`：" + +#: ../../deprecations/pending-removal-in-3.17.rst:6 +msgid "" +":class:`collections.abc.ByteString` is scheduled for removal in Python 3.17." +msgstr ":class:`collections.abc.ByteString` 預計在 Python 3.17 中移除。" + +#: ../../deprecations/pending-removal-in-3.17.rst:8 +#: ../../deprecations/pending-removal-in-3.17.rst:36 +msgid "" +"Use ``isinstance(obj, collections.abc.Buffer)`` to test if ``obj`` " +"implements the :ref:`buffer protocol ` at runtime. For use in " +"type annotations, either use :class:`~collections.abc.Buffer` or a union " +"that explicitly specifies the types your code supports (e.g., ``bytes | " +"bytearray | memoryview``)." +msgstr "" +"使用 ``isinstance(obj, collections.abc.Buffer)`` 來測試 ``obj`` 是否在 " +"runtime 實作了\\ :ref:`緩衝區協定 `。在型別註解的使用中，請" +"用 :class:`~collections.abc.Buffer` 或明確指定你的程式碼所支援型別的聯集（例" +"如 ``bytes | bytearray | memoryview``）。" + +#: ../../deprecations/pending-removal-in-3.17.rst:14 +#: ../../deprecations/pending-removal-in-3.17.rst:42 +msgid "" +":class:`!ByteString` was originally intended to be an abstract class that " +"would serve as a supertype of both :class:`bytes` and :class:`bytearray`. " +"However, since the ABC never had any methods, knowing that an object was an " +"instance of :class:`!ByteString` never actually told you anything useful " +"about the object. Other common buffer types such as :class:`memoryview` were " +"also never understood as subtypes of :class:`!ByteString` (either at runtime " +"or by static type checkers)." +msgstr "" +":class:`!ByteString` 最初被設計為一個抽象類別，以作為 :class:`bytes` 和 :" +"class:`bytearray` 的超型別 (supertype)。然而由於 ABC 從未擁有任何方法，知道一" +"個物件是 :class:`!ByteString` 的實例從未真正告訴你任何關於該物件的有用資訊。" +"其他常見的緩衝區型別如 :class:`memoryview` 也從未被理解為 :class:`!" +"ByteString` 的子型別（無論是在 runtime 還是由靜態型別檢查器）。" + +#: ../../deprecations/pending-removal-in-3.17.rst:22 +#: ../../deprecations/pending-removal-in-3.17.rst:50 +msgid "" +"See :pep:`PEP 688 <688#current-options>` for more details. (Contributed by " +"Shantanu Jain in :gh:`91896`.)" +msgstr "" +"更多細節請見 :pep:`PEP 688 <688#current-options>`。（由 Shantanu Jain 於 :gh:" +"`91896` 貢獻。）" + +#: ../../deprecations/pending-removal-in-3.17.rst:28 +msgid "" +"Before Python 3.14, old-style unions were implemented using the private " +"class ``typing._UnionGenericAlias``. This class is no longer needed for the " +"implementation, but it has been retained for backward compatibility, with " +"removal scheduled for Python 3.17. Users should use documented introspection " +"helpers like :func:`typing.get_origin` and :func:`typing.get_args` instead " +"of relying on private implementation details." +msgstr "" +"在 Python 3.14 之前，舊式聯集是使用私有類別 ``typing._UnionGenericAlias`` 實" +"作的。這個類別不再被需要，但為了向後相容性而保留，並計劃將在 Python 3.17 中移" +"除。使用者應該改用文件中記錄的內省輔助函式，例如 :func:`typing.get_origin` " +"和 :func:`typing.get_args`，或者依賴私有實作細節。" + +#: ../../deprecations/pending-removal-in-3.17.rst:33 +msgid "" +":class:`typing.ByteString`, deprecated since Python 3.9, is scheduled for " +"removal in Python 3.17." +msgstr "" +":class:`typing.ByteString` 自 Python 3.9 起已被棄用，預計在 Python 3.17 中移" +"除。" + +#: ../../deprecations/c-api-pending-removal-in-3.18.rst:2 +#: ../../deprecations/pending-removal-in-3.18.rst:2 +msgid "Pending removal in Python 3.18" +msgstr "Python 3.18 中待移除的項目" + +#: ../../deprecations/pending-removal-in-3.18.rst:4 +msgid ":mod:`decimal`:" +msgstr ":mod:`decimal`：" + +#: ../../deprecations/pending-removal-in-3.18.rst:6 +msgid "" +"The non-standard and undocumented :class:`~decimal.Decimal` format specifier " +"``'N'``, which is only supported in the :mod:`!decimal` module's C " +"implementation, has been deprecated since Python 3.13. (Contributed by " +"Serhiy Storchaka in :gh:`89902`.)" +msgstr "" +"非標準且無文件記載的 :class:`~decimal.Decimal` 格式說明符號 ``'N'``，僅在 :mod:" +"`!decimal` 模組的 C 實作中被支援，自 Python 3.13 起已被棄用。（由 Serhiy " +"Storchaka 於 :gh:`89902` 中貢獻。）" + +#: ../../deprecations/pending-removal-in-3.19.rst:2 +msgid "Pending removal in Python 3.19" +msgstr "Python 3.19 中待移除的項目" + +#: ../../deprecations/pending-removal-in-3.19.rst:6 +msgid "" +"Implicitly switching to the MSVC-compatible struct layout by setting :attr:" +"`~ctypes.Structure._pack_` but not :attr:`~ctypes.Structure._layout_` on non-" +"Windows platforms." +msgstr "" +"在非 Windows 平台上，透過設定 :attr:`~ctypes.Structure._pack_` 而沒有設定 :" +"attr:`~ctypes.Structure._layout_` 來隱式地切換到與 MSVC 相容的結構佈局。" + +#: ../../deprecations/c-api-pending-removal-in-future.rst:2 +#: ../../deprecations/pending-removal-in-future.rst:2 +msgid "Pending removal in future versions" +msgstr "未來版本中的待移除項目" + +#: ../../deprecations/pending-removal-in-future.rst:4 +msgid "" +"The following APIs will be removed in the future, although there is " +"currently no date scheduled for their removal." +msgstr "以下 API 將在未來被移除，雖然目前尚未安排移除日期。" + +#: ../../deprecations/pending-removal-in-future.rst:7 +msgid ":mod:`argparse`:" +msgstr ":mod:`argparse`：" + +#: ../../deprecations/pending-removal-in-future.rst:9 +msgid "" +"Nesting argument groups and nesting mutually exclusive groups are deprecated." +msgstr "巢狀引數群組和巢狀互斥群組已被棄用。" + +#: ../../deprecations/pending-removal-in-future.rst:11 +msgid "" +"Passing the undocumented keyword argument *prefix_chars* to :meth:`~argparse." +"ArgumentParser.add_argument_group` is now deprecated." +msgstr "" +"將未以文件記錄的關鍵字引數 *prefix_chars* 傳遞給 :meth:`~argparse." +"ArgumentParser.add_argument_group` 的做法現在已被棄用。" + +#: ../../deprecations/pending-removal-in-future.rst:14 +msgid "The :class:`argparse.FileType` type converter is deprecated." +msgstr ":class:`argparse.FileType` 型別轉換器已被棄用。" + +#: ../../deprecations/pending-removal-in-future.rst:18 +msgid "" +"Generators: ``throw(type, exc, tb)`` and ``athrow(type, exc, tb)`` signature " +"is deprecated: use ``throw(exc)`` and ``athrow(exc)`` instead, the single " +"argument signature." +msgstr "" +"產生器：``throw(type, exc, tb)`` 和 ``athrow(type, exc, tb)`` 簽名已被棄用：" +"請改用 ``throw(exc)`` 和 ``athrow(exc)``，為單引數簽名。" + +#: ../../deprecations/pending-removal-in-future.rst:21 +msgid "" +"Currently Python accepts numeric literals immediately followed by keywords, " +"for example ``0in x``, ``1or x``, ``0if 1else 2``. It allows confusing and " +"ambiguous expressions like ``[0x1for x in y]`` (which can be interpreted as " +"``[0x1 for x in y]`` or ``[0x1f or x in y]``). A syntax warning is raised " +"if the numeric literal is immediately followed by one of keywords :keyword:" +"`and`, :keyword:`else`, :keyword:`for`, :keyword:`if`, :keyword:`in`, :" +"keyword:`is` and :keyword:`or`. In a future release it will be changed to a " +"syntax error. (:gh:`87999`)" +msgstr "" +"目前 Python 接受數值字面值後面立即接關鍵字，例如 ``0in x``、``1or x``、``0if " +"1else 2``。它讓運算式模糊且容易混淆，如 ``[0x1for x in y]``\\ （可以解釋為 " +"``[0x1 for x in y]`` 或 ``[0x1f or x in y]``）。如果數值字面值後立即接 :" +"keyword:`and`、:keyword:`else`、:keyword:`for`、:keyword:`if`、:keyword:" +"`in`、:keyword:`is` 和 :keyword:`or` 之一的關鍵字，則會引發語法警告。在未來版" +"本中，它將被更改為語法錯誤。(:gh:`87999`)" + +#: ../../deprecations/pending-removal-in-future.rst:29 +msgid "" +"Support for ``__index__()`` and ``__int__()`` method returning non-int type: " +"these methods will be required to return an instance of a strict subclass " +"of :class:`int`." +msgstr "" +"``__index__()`` 和 ``__int__()`` 方法回傳非 int 型別的支援：這些方法將需要回" +"傳 :class:`int` 的嚴格子類別實例。" + +#: ../../deprecations/pending-removal-in-future.rst:32 +msgid "" +"Support for ``__float__()`` method returning a strict subclass of :class:" +"`float`: these methods will be required to return an instance of :class:" +"`float`." +msgstr "" +"回傳 :class:`float` 嚴格子類別 ``__float__()`` 方法的支援：這些方法將需要回" +"傳 :class:`float` 的實例。" + +#: ../../deprecations/pending-removal-in-future.rst:35 +msgid "" +"Support for ``__complex__()`` method returning a strict subclass of :class:" +"`complex`: these methods will be required to return an instance of :class:" +"`complex`." +msgstr "" +"回傳 :class:`complex` 嚴格子類別 ``__complex__()`` 方法的支援：這些方法將需要" +"回傳 :class:`complex` 的實例。" + +#: ../../deprecations/pending-removal-in-future.rst:38 +msgid "Delegation of ``int()`` to ``__trunc__()`` method." +msgstr "將 ``int()`` 委派給 ``__trunc__()`` 方法。" + +#: ../../deprecations/pending-removal-in-future.rst:39 +msgid "" +"Passing a complex number as the *real* or *imag* argument in the :func:" +"`complex` constructor is now deprecated; it should only be passed as a " +"single positional argument. (Contributed by Serhiy Storchaka in :gh:" +"`109218`.)" +msgstr "" +"在 :func:`complex` 建構子中將複數作為 *real* 或 *imag* 引數傳遞現在已被棄用；" +"它應該只作為單個位置引數傳遞。 (由 Serhiy Storchaka 於 :gh:`109218` 貢獻。)" + +#: ../../deprecations/pending-removal-in-future.rst:44 +msgid "" +":mod:`calendar`: ``calendar.January`` and ``calendar.February`` constants " +"are deprecated and replaced by :data:`calendar.JANUARY` and :data:`calendar." +"FEBRUARY`. (Contributed by Prince Roshan in :gh:`103636`.)" +msgstr "" +":mod:`calendar`：``calendar.January`` 和 ``calendar.February`` 常數已被棄用並" +"被 :data:`calendar.JANUARY` 和 :data:`calendar.FEBRUARY` 取代。 (由 Prince " +"Roshan 於 :gh:`103636` 貢獻。)" + +#: ../../deprecations/pending-removal-in-future.rst:49 +msgid "" +":mod:`codecs`: use :func:`open` instead of :func:`codecs.open`. (:gh:" +"`133038`)" +msgstr "" +":mod:`codecs`：請改用 :func:`open` 而非 :func:`codecs.open`。(:gh:`133038`)" + +#: ../../deprecations/pending-removal-in-future.rst:51 +msgid "" +":attr:`codeobject.co_lnotab`: use the :meth:`codeobject.co_lines` method " +"instead." +msgstr "" +":attr:`codeobject.co_lnotab`：請改用 :meth:`codeobject.co_lines` 方法。" + +#: ../../deprecations/pending-removal-in-future.rst:54 +msgid ":mod:`datetime`:" +msgstr ":mod:`datetime`：" + +#: ../../deprecations/pending-removal-in-future.rst:56 +msgid "" +":meth:`~datetime.datetime.utcnow`: use ``datetime.datetime.now(tz=datetime." +"UTC)``." +msgstr "" +":meth:`~datetime.datetime.utcnow`：請改用 ``datetime.datetime." +"now(tz=datetime.UTC)``。" + +#: ../../deprecations/pending-removal-in-future.rst:58 +msgid "" +":meth:`~datetime.datetime.utcfromtimestamp`: use ``datetime.datetime." +"fromtimestamp(timestamp, tz=datetime.UTC)``." +msgstr "" +":meth:`~datetime.datetime.utcfromtimestamp`：請改用 ``datetime.datetime." +"fromtimestamp(timestamp, tz=datetime.UTC)``。" + +#: ../../deprecations/pending-removal-in-future.rst:61 +msgid ":mod:`gettext`: Plural value must be an integer." +msgstr ":mod:`gettext`：複數值必須是整數。" + +#: ../../deprecations/pending-removal-in-future.rst:65 +msgid "" +":func:`~importlib.util.cache_from_source` *debug_override* parameter is " +"deprecated: use the *optimization* parameter instead." +msgstr "" +":func:`~importlib.util.cache_from_source` *debug_override* 參數已被棄用：請改" +"用 *optimization* 參數。" + +#: ../../deprecations/pending-removal-in-future.rst:68 +msgid ":mod:`importlib.metadata`:" +msgstr ":mod:`importlib.metadata`：" + +#: ../../deprecations/pending-removal-in-future.rst:70 +msgid "``EntryPoints`` tuple interface." +msgstr "``EntryPoints`` 元組介面。" + +#: ../../deprecations/pending-removal-in-future.rst:71 +msgid "Implicit ``None`` on return values." +msgstr "回傳值上的隱式 ``None``。" + +#: ../../deprecations/pending-removal-in-future.rst:73 +msgid "" +":mod:`logging`: the ``warn()`` method has been deprecated since Python 3.3, " +"use :meth:`~logging.warning` instead." +msgstr "" +":mod:`logging`：自 Python 3.3 起，``warn()`` 方法已被棄用，請改用 :meth:" +"`~logging.warning`。" + +#: ../../deprecations/pending-removal-in-future.rst:76 +msgid "" +":mod:`mailbox`: Use of StringIO input and text mode is deprecated, use " +"BytesIO and binary mode instead." +msgstr "" +":mod:`mailbox`：已棄用 StringIO 輸入和文本模式，請改用 BytesIO 和二進位模式。" + +#: ../../deprecations/pending-removal-in-future.rst:79 +msgid "" +":mod:`os`: Calling :func:`os.register_at_fork` in multi-threaded process." +msgstr ":mod:`os`：在多執行緒行程中呼叫 :func:`os.register_at_fork`。" + +#: ../../deprecations/pending-removal-in-future.rst:81 +msgid "" +":class:`!pydoc.ErrorDuringImport`: A tuple value for *exc_info* parameter is " +"deprecated, use an exception instance." +msgstr "" +":class:`!pydoc.ErrorDuringImport`：*exc_info* 參數的元組值已被棄用，請用例外" +"實例。" + +#: ../../deprecations/pending-removal-in-future.rst:84 +msgid "" +":mod:`re`: More strict rules are now applied for numerical group references " +"and group names in regular expressions. Only sequence of ASCII digits is " +"now accepted as a numerical reference. The group name in bytes patterns and " +"replacement strings can now only contain ASCII letters and digits and " +"underscore. (Contributed by Serhiy Storchaka in :gh:`91760`.)" +msgstr "" +":mod:`re`：現在對正規表示式中的數值群組參照和群組名稱用了更嚴格的規則。現在只" +"有 ASCII 數碼序列被接受作為數值參照。位元組模式和替換字串中的群組名稱現在只能" +"包含 ASCII 字母、數碼和底線。（由 Serhiy Storchaka 於 :gh:`91760` 貢獻。）" + +#: ../../deprecations/pending-removal-in-future.rst:91 +msgid "" +":mod:`!sre_compile`, :mod:`!sre_constants` and :mod:`!sre_parse` modules." +msgstr ":mod:`!sre_compile`、:mod:`!sre_constants` 和 :mod:`!sre_parse` 模組。" + +#: ../../deprecations/pending-removal-in-future.rst:93 +msgid "" +":mod:`shutil`: :func:`~shutil.rmtree`'s *onerror* parameter is deprecated in " +"Python 3.12; use the *onexc* parameter instead." +msgstr "" +":mod:`shutil`：:func:`~shutil.rmtree` 的 *onerror* 參數在 Python 3.12 中已被" +"棄用；請改用 *onexc* 參數。" + +#: ../../deprecations/pending-removal-in-future.rst:96 +msgid ":mod:`ssl` options and protocols:" +msgstr ":mod:`ssl` 選項和協定：" + +#: ../../deprecations/pending-removal-in-future.rst:98 +msgid ":class:`ssl.SSLContext` without protocol argument is deprecated." +msgstr "不帶協定引數的 :class:`ssl.SSLContext` 已被棄用。" + +#: ../../deprecations/pending-removal-in-future.rst:99 +msgid "" +":class:`ssl.SSLContext`: :meth:`~ssl.SSLContext.set_npn_protocols` and :meth:" +"`!selected_npn_protocol` are deprecated: use ALPN instead." +msgstr "" +":class:`ssl.SSLContext`：:meth:`~ssl.SSLContext.set_npn_protocols` 和 :meth:" +"`!selected_npn_protocol` 已被棄用：請改用 ALPN。" + +#: ../../deprecations/pending-removal-in-future.rst:102 +msgid "``ssl.OP_NO_SSL*`` options" +msgstr "``ssl.OP_NO_SSL*`` 選項" + +#: ../../deprecations/pending-removal-in-future.rst:103 +msgid "``ssl.OP_NO_TLS*`` options" +msgstr "``ssl.OP_NO_TLS*`` 選項" + +#: ../../deprecations/pending-removal-in-future.rst:104 +msgid "``ssl.PROTOCOL_SSLv3``" +msgstr "``ssl.PROTOCOL_SSLv3``" + +#: ../../deprecations/pending-removal-in-future.rst:105 +msgid "``ssl.PROTOCOL_TLS``" +msgstr "``ssl.PROTOCOL_TLS``" + +#: ../../deprecations/pending-removal-in-future.rst:106 +msgid "``ssl.PROTOCOL_TLSv1``" +msgstr "``ssl.PROTOCOL_TLSv1``" + +#: ../../deprecations/pending-removal-in-future.rst:107 +msgid "``ssl.PROTOCOL_TLSv1_1``" +msgstr "``ssl.PROTOCOL_TLSv1_1``" + +#: ../../deprecations/pending-removal-in-future.rst:108 +msgid "``ssl.PROTOCOL_TLSv1_2``" +msgstr "``ssl.PROTOCOL_TLSv1_2``" + +#: ../../deprecations/pending-removal-in-future.rst:109 +msgid "``ssl.TLSVersion.SSLv3``" +msgstr "``ssl.TLSVersion.SSLv3``" + +#: ../../deprecations/pending-removal-in-future.rst:110 +msgid "``ssl.TLSVersion.TLSv1``" +msgstr "``ssl.TLSVersion.TLSv1``" + +#: ../../deprecations/pending-removal-in-future.rst:111 +msgid "``ssl.TLSVersion.TLSv1_1``" +msgstr "``ssl.TLSVersion.TLSv1_1``" + +#: ../../deprecations/pending-removal-in-future.rst:113 +msgid ":mod:`threading` methods:" +msgstr ":mod:`threading` 方法：" + +#: ../../deprecations/pending-removal-in-future.rst:115 +msgid "" +":meth:`!threading.Condition.notifyAll`: use :meth:`~threading.Condition." +"notify_all`." +msgstr "" +":meth:`!threading.Condition.notifyAll`：請用 :meth:`~threading.Condition." +"notify_all`。" + +#: ../../deprecations/pending-removal-in-future.rst:116 +msgid ":meth:`!threading.Event.isSet`: use :meth:`~threading.Event.is_set`." +msgstr ":meth:`!threading.Event.isSet`：請用 :meth:`~threading.Event.is_set`。" + +#: ../../deprecations/pending-removal-in-future.rst:117 +msgid "" +":meth:`!threading.Thread.isDaemon`, :meth:`threading.Thread.setDaemon`: use :" +"attr:`threading.Thread.daemon` attribute." +msgstr "" +":meth:`!threading.Thread.isDaemon`、:meth:`threading.Thread.setDaemon`：請" +"用 :attr:`threading.Thread.daemon` 屬性。" + +#: ../../deprecations/pending-removal-in-future.rst:119 +msgid "" +":meth:`!threading.Thread.getName`, :meth:`threading.Thread.setName`: use :" +"attr:`threading.Thread.name` attribute." +msgstr "" +":meth:`!threading.Thread.getName`、:meth:`threading.Thread.setName`：請用 :" +"attr:`threading.Thread.name` 屬性。" + +#: ../../deprecations/pending-removal-in-future.rst:121 +msgid ":meth:`!threading.currentThread`: use :meth:`threading.current_thread`." +msgstr "" +":meth:`!threading.currentThread`：請用 :meth:`threading.current_thread`。" + +#: ../../deprecations/pending-removal-in-future.rst:122 +msgid ":meth:`!threading.activeCount`: use :meth:`threading.active_count`." +msgstr ":meth:`!threading.activeCount`：請用 :meth:`threading.active_count`。" + +#: ../../deprecations/pending-removal-in-future.rst:124 +msgid ":class:`typing.Text` (:gh:`92332`)." +msgstr ":class:`typing.Text` (:gh:`92332`)。" + +#: ../../deprecations/pending-removal-in-future.rst:126 +msgid "" +"The internal class ``typing._UnionGenericAlias`` is no longer used to " +"implement :class:`typing.Union`. To preserve compatibility with users using " +"this private class, a compatibility shim will be provided until at least " +"Python 3.17. (Contributed by Jelle Zijlstra in :gh:`105499`.)" +msgstr "" +"內部類別 ``typing._UnionGenericAlias`` 不再用於實作 :class:`typing.Union`。為" +"了保持與此私有類別使用者的相容性，直到至少 Python 3.17 都將提供一個相容性 " +"shim。（由 Jelle Zijlstra 於 :gh:`105499` 貢獻。）" + +#: ../../deprecations/pending-removal-in-future.rst:131 +msgid "" +":class:`unittest.IsolatedAsyncioTestCase`: it is deprecated to return a " +"value that is not ``None`` from a test case." +msgstr "" +":class:`unittest.IsolatedAsyncioTestCase`：從測試案例中回傳非 ``None`` 的值已" +"被棄用。" + +#: ../../deprecations/pending-removal-in-future.rst:134 +msgid "" +":mod:`urllib.parse` deprecated functions: :func:`~urllib.parse.urlparse` " +"instead" +msgstr "" +":mod:`urllib.parse` 已棄用函式：請改用 :func:`~urllib.parse.urlparse`。" + +#: ../../deprecations/pending-removal-in-future.rst:136 +msgid "``splitattr()``" +msgstr "``splitattr()``" + +#: ../../deprecations/pending-removal-in-future.rst:137 +msgid "``splithost()``" +msgstr "``splithost()``" + +#: ../../deprecations/pending-removal-in-future.rst:138 +msgid "``splitnport()``" +msgstr "``splitnport()``" + +#: ../../deprecations/pending-removal-in-future.rst:139 +msgid "``splitpasswd()``" +msgstr "``splitpasswd()``" + +#: ../../deprecations/pending-removal-in-future.rst:140 +msgid "``splitport()``" +msgstr "``splitport()``" + +#: ../../deprecations/pending-removal-in-future.rst:141 +msgid "``splitquery()``" +msgstr "``splitquery()``" + +#: ../../deprecations/pending-removal-in-future.rst:142 +msgid "``splittag()``" +msgstr "``splittag()``" + +#: ../../deprecations/pending-removal-in-future.rst:143 +msgid "``splittype()``" +msgstr "``splittype()``" + +#: ../../deprecations/pending-removal-in-future.rst:144 +msgid "``splituser()``" +msgstr "``splituser()``" + +#: ../../deprecations/pending-removal-in-future.rst:145 +msgid "``splitvalue()``" +msgstr "``splitvalue()``" + +#: ../../deprecations/pending-removal-in-future.rst:146 +msgid "``to_bytes()``" +msgstr "``to_bytes()``" + +#: ../../deprecations/pending-removal-in-future.rst:148 +msgid "" +":mod:`wsgiref`: ``SimpleHandler.stdout.write()`` should not do partial " +"writes." +msgstr ":mod:`wsgiref`：``SimpleHandler.stdout.write()`` 不應該進行部分寫入。" + +#: ../../deprecations/pending-removal-in-future.rst:151 +msgid "" +":mod:`xml.etree.ElementTree`: Testing the truth value of an :class:`~xml." +"etree.ElementTree.Element` is deprecated. In a future release it will always " +"return ``True``. Prefer explicit ``len(elem)`` or ``elem is not None`` tests " +"instead." +msgstr "" +":mod:`xml.etree.ElementTree`：已棄用對 :class:`~xml.etree.ElementTree." +"Element` 的真值測試。在未來版本中，它將始終回傳 ``True``。請改用明確的 " +"``len(elem)`` 或 ``elem is not None`` 測試。" + +#: ../../deprecations/pending-removal-in-future.rst:156 +msgid "" +":func:`sys._clear_type_cache` is deprecated: use :func:`sys." +"_clear_internal_caches` instead." +msgstr "" +":func:`sys._clear_type_cache` 已被棄用：請改用 :func:`sys." +"_clear_internal_caches`。" + +#: ../../deprecations/index.rst:17 +msgid "C API deprecations" +msgstr "C API 的棄用項目" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:4 +msgid "" +"The :c:func:`PyImport_ImportModuleNoBlock`: Use :c:func:" +"`PyImport_ImportModule` instead." +msgstr "" +":c:func:`PyImport_ImportModuleNoBlock`：請改用 :c:func:" +"`PyImport_ImportModule`。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:6 +msgid "" +":c:func:`PyWeakref_GetObject` and :c:func:`PyWeakref_GET_OBJECT`: Use :c:" +"func:`PyWeakref_GetRef` instead. The `pythoncapi-compat project `__ can be used to get :c:func:" +"`PyWeakref_GetRef` on Python 3.12 and older." +msgstr "" +":c:func:`PyWeakref_GetObject` 和 :c:func:`PyWeakref_GET_OBJECT`：請改用 :c:" +"func:`PyWeakref_GetRef`。可以使用 `pythoncapi-compat 專案 `__\\ 來為 Python 3.12 和更早版本取得 :c:func:" +"`PyWeakref_GetRef`。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:10 +msgid "" +":c:type:`Py_UNICODE` type and the :c:macro:`!Py_UNICODE_WIDE` macro: Use :c:" +"type:`wchar_t` instead." +msgstr "" +":c:type:`Py_UNICODE` 型別與 :c:macro:`!Py_UNICODE_WIDE` 巨集：請改用 :c:type:" +"`wchar_t`。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:12 +msgid "" +":c:func:`!PyUnicode_AsDecodedObject`: Use :c:func:`PyCodec_Decode` instead." +msgstr "" +":c:func:`!PyUnicode_AsDecodedObject`：請改用 :c:func:`PyCodec_Decode`。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:14 +msgid "" +":c:func:`!PyUnicode_AsDecodedUnicode`: Use :c:func:`PyCodec_Decode` instead; " +"Note that some codecs (for example, \"base64\") may return a type other " +"than :class:`str`, such as :class:`bytes`." +msgstr "" +":c:func:`!PyUnicode_AsDecodedUnicode`：請改用 :c:func:`PyCodec_Decode`；請注" +"意某些編解碼器（例如 \"base64\"）可能會回傳非 :class:`str` 的型別，例如 :" +"class:`bytes`。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:17 +msgid "" +":c:func:`!PyUnicode_AsEncodedObject`: Use :c:func:`PyCodec_Encode` instead." +msgstr "" +":c:func:`!PyUnicode_AsEncodedObject`：請改用 :c:func:`PyCodec_Encode`。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:19 +msgid "" +":c:func:`!PyUnicode_AsEncodedUnicode`: Use :c:func:`PyCodec_Encode` instead; " +"Note that some codecs (for example, \"base64\") may return a type other " +"than :class:`bytes`, such as :class:`str`." +msgstr "" +":c:func:`!PyUnicode_AsEncodedUnicode`：請改用 :c:func:`PyCodec_Encode`；請注" +"意某些編解碼器（例如 \"base64\"）可能會回傳非 :class:`bytes` 的型別，例如 :" +"class:`str`。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:22 +msgid "Python initialization functions, deprecated in Python 3.13:" +msgstr "Python 初始化函式，自 Python 3.13 起已被棄用：" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:24 +msgid "" +":c:func:`Py_GetPath`: Use :c:func:`PyConfig_Get(\"module_search_paths\") " +"` (:data:`sys.path`) instead." +msgstr "" +":c:func:`Py_GetPath`：請改用 :c:func:`PyConfig_Get(\"module_search_paths\") " +"` (:data:`sys.path`)。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:27 +msgid "" +":c:func:`Py_GetPrefix`: Use :c:func:`PyConfig_Get(\"base_prefix\") " +"` (:data:`sys.base_prefix`) instead. Use :c:func:" +"`PyConfig_Get(\"prefix\") ` (:data:`sys.prefix`) if :ref:" +"`virtual environments ` need to be handled." +msgstr "" +":c:func:`Py_GetPrefix`：請改用 :c:func:`PyConfig_Get(\"base_prefix\") " +"` (:data:`sys.base_prefix`)。如果需要處理\\ :ref:`虛擬環境 " +"`，請改用 :c:func:`PyConfig_Get(\"prefix\") ` (:data:" +"`sys.prefix`)。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:32 +msgid "" +":c:func:`Py_GetExecPrefix`: Use :c:func:`PyConfig_Get(\"base_exec_prefix\") " +"` (:data:`sys.base_exec_prefix`) instead. Use :c:func:" +"`PyConfig_Get(\"exec_prefix\") ` (:data:`sys.exec_prefix`) if :" +"ref:`virtual environments ` need to be handled." +msgstr "" +":c:func:`Py_GetExecPrefix`：請改用 :c:func:" +"`PyConfig_Get(\"base_exec_prefix\") ` (:data:`sys." +"base_exec_prefix`)。如果需要處理\\ :ref:`虛擬環境 `，請改用 :c:" +"func:`PyConfig_Get(\"exec_prefix\") ` (:data:`sys." +"exec_prefix`)。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:38 +msgid "" +":c:func:`Py_GetProgramFullPath`: Use :c:func:`PyConfig_Get(\"executable\") " +"` (:data:`sys.executable`) instead." +msgstr "" +":c:func:`Py_GetProgramFullPath`：請改用 :c:func:" +"`PyConfig_Get(\"executable\") ` (:data:`sys.executable`)。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:41 +msgid "" +":c:func:`Py_GetProgramName`: Use :c:func:`PyConfig_Get(\"executable\") " +"` (:data:`sys.executable`) instead." +msgstr "" +":c:func:`Py_GetProgramName`：請改用 :c:func:`PyConfig_Get(\"executable\") " +"` (:data:`sys.executable`)。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:44 +msgid "" +":c:func:`Py_GetPythonHome`: Use :c:func:`PyConfig_Get(\"home\") " +"` or the :envvar:`PYTHONHOME` environment variable instead." +msgstr "" +":c:func:`Py_GetPythonHome`：請改用 :c:func:`PyConfig_Get(\"home\") " +"` 或 :envvar:`PYTHONHOME` 環境變數。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:48 +msgid "" +"The `pythoncapi-compat project `__ can be used to get :c:func:`PyConfig_Get` on Python 3.13 and older." +msgstr "" +"`pythoncapi-compat 專案 `__ 可" +"以用來為 Python 3.13 和更早版本取得 :c:func:`PyConfig_Get`。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:52 +msgid "" +"Functions to configure Python's initialization, deprecated in Python 3.11:" +msgstr "用於配置 Python 初始化的函式，自 Python 3.11 起已被棄用：" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:54 +msgid ":c:func:`!PySys_SetArgvEx()`: Set :c:member:`PyConfig.argv` instead." +msgstr ":c:func:`!PySys_SetArgvEx()`：請改用 :c:member:`PyConfig.argv`。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:56 +msgid ":c:func:`!PySys_SetArgv()`: Set :c:member:`PyConfig.argv` instead." +msgstr ":c:func:`!PySys_SetArgv()`：請改用 :c:member:`PyConfig.argv`。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:58 +msgid "" +":c:func:`!Py_SetProgramName()`: Set :c:member:`PyConfig.program_name` " +"instead." +msgstr "" +":c:func:`!Py_SetProgramName()`：請改用 :c:member:`PyConfig.program_name`。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:60 +msgid ":c:func:`!Py_SetPythonHome()`: Set :c:member:`PyConfig.home` instead." +msgstr ":c:func:`!Py_SetPythonHome()`：請改用 :c:member:`PyConfig.home`。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:62 +msgid "" +":c:func:`PySys_ResetWarnOptions`: Clear :data:`sys.warnoptions` and :data:`!" +"warnings.filters` instead." +msgstr "" +":c:func:`PySys_ResetWarnOptions`：請改為清除 :data:`sys.warnoptions` 和 :" +"data:`!warnings.filters`。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:65 +msgid "" +"The :c:func:`Py_InitializeFromConfig` API should be used with :c:type:" +"`PyConfig` instead." +msgstr "" +"應改用帶有 :c:type:`PyConfig` 的 :c:func:`Py_InitializeFromConfig` API。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:68 +msgid "Global configuration variables:" +msgstr "全域配置變數：" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:70 +msgid "" +":c:var:`Py_DebugFlag`: Use :c:member:`PyConfig.parser_debug` or :c:func:" +"`PyConfig_Get(\"parser_debug\") ` instead." +msgstr "" +":c:var:`Py_DebugFlag`：請改用 :c:member:`PyConfig.parser_debug` 或 :c:func:" +"`PyConfig_Get(\"parser_debug\") `。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:73 +msgid "" +":c:var:`Py_VerboseFlag`: Use :c:member:`PyConfig.verbose` or :c:func:" +"`PyConfig_Get(\"verbose\") ` instead." +msgstr "" +":c:var:`Py_VerboseFlag`：請改用 :c:member:`PyConfig.verbose` 或 :c:func:" +"`PyConfig_Get(\"verbose\") `。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:76 +msgid "" +":c:var:`Py_QuietFlag`: Use :c:member:`PyConfig.quiet` or :c:func:" +"`PyConfig_Get(\"quiet\") ` instead." +msgstr "" +":c:var:`Py_QuietFlag`：請改用 :c:member:`PyConfig.quiet` 或 :c:func:" +"`PyConfig_Get(\"quiet\") `。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:79 +msgid "" +":c:var:`Py_InteractiveFlag`: Use :c:member:`PyConfig.interactive` or :c:func:" +"`PyConfig_Get(\"interactive\") ` instead." +msgstr "" +":c:var:`Py_InteractiveFlag`：請改用 :c:member:`PyConfig.interactive` 或 :c:" +"func:`PyConfig_Get(\"interactive\") `。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:82 +msgid "" +":c:var:`Py_InspectFlag`: Use :c:member:`PyConfig.inspect` or :c:func:" +"`PyConfig_Get(\"inspect\") ` instead." +msgstr "" +":c:var:`Py_InspectFlag`：請改用 :c:member:`PyConfig.inspect` 或 :c:func:" +"`PyConfig_Get(\"inspect\") `。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:85 +msgid "" +":c:var:`Py_OptimizeFlag`: Use :c:member:`PyConfig.optimization_level` or :c:" +"func:`PyConfig_Get(\"optimization_level\") ` instead." +msgstr "" +":c:var:`Py_OptimizeFlag`：請改用 :c:member:`PyConfig.optimization_level` 或 :" +"c:func:`PyConfig_Get(\"optimization_level\") `。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:88 +msgid "" +":c:var:`Py_NoSiteFlag`: Use :c:member:`PyConfig.site_import` or :c:func:" +"`PyConfig_Get(\"site_import\") ` instead." +msgstr "" +":c:var:`Py_NoSiteFlag`：請改用 :c:member:`PyConfig.site_import` 或 :c:func:" +"`PyConfig_Get(\"site_import\") `。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:91 +msgid "" +":c:var:`Py_BytesWarningFlag`: Use :c:member:`PyConfig.bytes_warning` or :c:" +"func:`PyConfig_Get(\"bytes_warning\") ` instead." +msgstr "" +":c:var:`Py_BytesWarningFlag`：請改用 :c:member:`PyConfig.bytes_warning` 或 :" +"c:func:`PyConfig_Get(\"bytes_warning\") `。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:94 +msgid "" +":c:var:`Py_FrozenFlag`: Use :c:member:`PyConfig.pathconfig_warnings` or :c:" +"func:`PyConfig_Get(\"pathconfig_warnings\") ` instead." +msgstr "" +":c:var:`Py_FrozenFlag`：請改用 :c:member:`PyConfig.pathconfig_warnings` 或 :" +"c:func:`PyConfig_Get(\"pathconfig_warnings\") `。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:97 +msgid "" +":c:var:`Py_IgnoreEnvironmentFlag`: Use :c:member:`PyConfig.use_environment` " +"or :c:func:`PyConfig_Get(\"use_environment\") ` instead." +msgstr "" +":c:var:`Py_IgnoreEnvironmentFlag`：請改用 :c:member:`PyConfig." +"use_environment` 或 :c:func:`PyConfig_Get(\"use_environment\") " +"`。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:100 +msgid "" +":c:var:`Py_DontWriteBytecodeFlag`: Use :c:member:`PyConfig.write_bytecode` " +"or :c:func:`PyConfig_Get(\"write_bytecode\") ` instead." +msgstr "" +":c:var:`Py_DontWriteBytecodeFlag`：請改用 :c:member:`PyConfig." +"write_bytecode` 或 :c:func:`PyConfig_Get(\"write_bytecode\") " +"`。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:103 +msgid "" +":c:var:`Py_NoUserSiteDirectory`: Use :c:member:`PyConfig." +"user_site_directory` or :c:func:`PyConfig_Get(\"user_site_directory\") " +"` instead." +msgstr "" +":c:var:`Py_NoUserSiteDirectory`：請改用 :c:member:`PyConfig." +"user_site_directory` 或 :c:func:`PyConfig_Get(\"user_site_directory\") " +"`。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:106 +msgid "" +":c:var:`Py_UnbufferedStdioFlag`: Use :c:member:`PyConfig.buffered_stdio` or :" +"c:func:`PyConfig_Get(\"buffered_stdio\") ` instead." +msgstr "" +":c:var:`Py_UnbufferedStdioFlag`：請改用 :c:member:`PyConfig.buffered_stdio` " +"或 :c:func:`PyConfig_Get(\"buffered_stdio\") `。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:109 +msgid "" +":c:var:`Py_HashRandomizationFlag`: Use :c:member:`PyConfig.use_hash_seed` " +"and :c:member:`PyConfig.hash_seed` or :c:func:`PyConfig_Get(\"hash_seed\") " +"` instead." +msgstr "" +":c:var:`Py_HashRandomizationFlag`：請改用 :c:member:`PyConfig.use_hash_seed` " +"和 :c:member:`PyConfig.hash_seed` 或 :c:func:`PyConfig_Get(\"hash_seed\") " +"`。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:113 +msgid "" +":c:var:`Py_IsolatedFlag`: Use :c:member:`PyConfig.isolated` or :c:func:" +"`PyConfig_Get(\"isolated\") ` instead." +msgstr "" +":c:var:`Py_IsolatedFlag`：請改用 :c:member:`PyConfig.isolated` 或 :c:func:" +"`PyConfig_Get(\"isolated\") `。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:116 +msgid "" +":c:var:`Py_LegacyWindowsFSEncodingFlag`: Use :c:member:`PyPreConfig." +"legacy_windows_fs_encoding` or :c:func:" +"`PyConfig_Get(\"legacy_windows_fs_encoding\") ` instead." +msgstr "" +":c:var:`Py_LegacyWindowsFSEncodingFlag`：請改用 :c:member:`PyPreConfig." +"legacy_windows_fs_encoding` 或 :c:func:" +"`PyConfig_Get(\"legacy_windows_fs_encoding\") `。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:119 +msgid "" +":c:var:`Py_LegacyWindowsStdioFlag`: Use :c:member:`PyConfig." +"legacy_windows_stdio` or :c:func:`PyConfig_Get(\"legacy_windows_stdio\") " +"` instead." +msgstr "" +":c:var:`Py_LegacyWindowsStdioFlag`：請改用 :c:member:`PyConfig." +"legacy_windows_stdio` 或 :c:func:`PyConfig_Get(\"legacy_windows_stdio\") " +"`。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:122 +msgid "" +":c:var:`!Py_FileSystemDefaultEncoding`, :c:var:`!" +"Py_HasFileSystemDefaultEncoding`: Use :c:member:`PyConfig." +"filesystem_encoding` or :c:func:`PyConfig_Get(\"filesystem_encoding\") " +"` instead." +msgstr "" +":c:var:`!Py_FileSystemDefaultEncoding`、:c:var:`!" +"Py_HasFileSystemDefaultEncoding`：請改用 :c:member:`PyConfig." +"filesystem_encoding` 或 :c:func:`PyConfig_Get(\"filesystem_encoding\") " +"`。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:125 +msgid "" +":c:var:`!Py_FileSystemDefaultEncodeErrors`: Use :c:member:`PyConfig." +"filesystem_errors` or :c:func:`PyConfig_Get(\"filesystem_errors\") " +"` instead." +msgstr "" +":c:var:`!Py_FileSystemDefaultEncodeErrors`：請改用 :c:member:`PyConfig." +"filesystem_errors` 或 :c:func:`PyConfig_Get(\"filesystem_errors\") " +"`。" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:128 +msgid "" +":c:var:`!Py_UTF8Mode`: Use :c:member:`PyPreConfig.utf8_mode` or :c:func:" +"`PyConfig_Get(\"utf8_mode\") ` instead. (see :c:func:" +"`Py_PreInitialize`)" +msgstr "" +":c:var:`!Py_UTF8Mode`：請改用 :c:member:`PyPreConfig.utf8_mode` 或 :c:func:" +"`PyConfig_Get(\"utf8_mode\") `。（請參閱 :c:func:" +"`Py_PreInitialize`）" + +#: ../../deprecations/c-api-pending-removal-in-3.15.rst:133 +msgid "" +"The :c:func:`Py_InitializeFromConfig` API should be used with :c:type:" +"`PyConfig` to set these options. Or :c:func:`PyConfig_Get` can be used to " +"get these options at runtime." +msgstr "" +"應改用帶有 :c:type:`PyConfig` 的 :c:func:`Py_InitializeFromConfig` API 來設定" +"這些選項。或者也可以使用 :c:func:`PyConfig_Get` 在執行時取得這些選項。" + +#: ../../deprecations/c-api-pending-removal-in-3.18.rst:4 +msgid "" +"The following private functions are deprecated and planned for removal in " +"Python 3.18:" +msgstr "以下私有函式已被棄用，並計劃在 Python 3.18 中移除：" + +#: ../../deprecations/c-api-pending-removal-in-3.18.rst:7 +msgid ":c:func:`!_PyBytes_Join`: use :c:func:`PyBytes_Join`." +msgstr ":c:func:`!_PyBytes_Join`：請改用 :c:func:`PyBytes_Join`。" + +#: ../../deprecations/c-api-pending-removal-in-3.18.rst:8 +msgid "" +":c:func:`!_PyDict_GetItemStringWithError`: use :c:func:" +"`PyDict_GetItemStringRef`." +msgstr "" +":c:func:`!_PyDict_GetItemStringWithError`：請改用 :c:func:" +"`PyDict_GetItemStringRef`。" + +#: ../../deprecations/c-api-pending-removal-in-3.18.rst:9 +msgid ":c:func:`!_PyDict_Pop()`: use :c:func:`PyDict_Pop`." +msgstr ":c:func:`!_PyDict_Pop()`：請改用 :c:func:`PyDict_Pop`。" + +#: ../../deprecations/c-api-pending-removal-in-3.18.rst:10 +msgid ":c:func:`!_PyLong_Sign()`: use :c:func:`PyLong_GetSign`." +msgstr ":c:func:`!_PyLong_Sign()`：請改用 :c:func:`PyLong_GetSign`。" + +#: ../../deprecations/c-api-pending-removal-in-3.18.rst:11 +msgid "" +":c:func:`!_PyLong_FromDigits` and :c:func:`!_PyLong_New`: use :c:func:" +"`PyLongWriter_Create`." +msgstr "" +":c:func:`!_PyLong_FromDigits` 和 :c:func:`!_PyLong_New`：請改用 :c:func:" +"`PyLongWriter_Create`。" + +#: ../../deprecations/c-api-pending-removal-in-3.18.rst:13 +msgid "" +":c:func:`!_PyThreadState_UncheckedGet`: use :c:func:" +"`PyThreadState_GetUnchecked`." +msgstr "" +":c:func:`!_PyThreadState_UncheckedGet`：請改用 :c:func:" +"`PyThreadState_GetUnchecked`。" + +#: ../../deprecations/c-api-pending-removal-in-3.18.rst:14 +msgid ":c:func:`!_PyUnicode_AsString`: use :c:func:`PyUnicode_AsUTF8`." +msgstr ":c:func:`!_PyUnicode_AsString`：請改用 :c:func:`PyUnicode_AsUTF8`。" + +#: ../../deprecations/c-api-pending-removal-in-3.18.rst:15 +msgid "" +":c:func:`!_PyUnicodeWriter_Init`: replace ``_PyUnicodeWriter_Init(&writer)`` " +"with :c:func:`writer = PyUnicodeWriter_Create(0) `." +msgstr "" +":c:func:`!_PyUnicodeWriter_Init`：將 ``_PyUnicodeWriter_Init(&writer)`` 替換" +"為 :c:func:`writer = PyUnicodeWriter_Create(0) `。" + +#: ../../deprecations/c-api-pending-removal-in-3.18.rst:18 +msgid "" +":c:func:`!_PyUnicodeWriter_Finish`: replace " +"``_PyUnicodeWriter_Finish(&writer)`` with :c:func:" +"`PyUnicodeWriter_Finish(writer) `." +msgstr "" +":c:func:`!_PyUnicodeWriter_Finish`：將 ``_PyUnicodeWriter_Finish(&writer)`` " +"替換為 :c:func:`PyUnicodeWriter_Finish(writer) `。" + +#: ../../deprecations/c-api-pending-removal-in-3.18.rst:21 +msgid "" +":c:func:`!_PyUnicodeWriter_Dealloc`: replace " +"``_PyUnicodeWriter_Dealloc(&writer)`` with :c:func:" +"`PyUnicodeWriter_Discard(writer) `." +msgstr "" +":c:func:`!_PyUnicodeWriter_Dealloc`：將 " +"``_PyUnicodeWriter_Dealloc(&writer)`` 替換為 :c:func:" +"`PyUnicodeWriter_Discard(writer) `。" + +#: ../../deprecations/c-api-pending-removal-in-3.18.rst:24 +msgid "" +":c:func:`!_PyUnicodeWriter_WriteChar`: replace " +"``_PyUnicodeWriter_WriteChar(&writer, ch)`` with :c:func:" +"`PyUnicodeWriter_WriteChar(writer, ch) `." +msgstr "" +":c:func:`!_PyUnicodeWriter_WriteChar`：將 " +"``_PyUnicodeWriter_WriteChar(&writer, ch)`` 替換為 :c:func:" +"`PyUnicodeWriter_WriteChar(writer, ch) `。" + +#: ../../deprecations/c-api-pending-removal-in-3.18.rst:27 +msgid "" +":c:func:`!_PyUnicodeWriter_WriteStr`: replace " +"``_PyUnicodeWriter_WriteStr(&writer, str)`` with :c:func:" +"`PyUnicodeWriter_WriteStr(writer, str) `." +msgstr "" +":c:func:`!_PyUnicodeWriter_WriteStr`：將 " +"``_PyUnicodeWriter_WriteStr(&writer, str)`` 替換為 :c:func:" +"`PyUnicodeWriter_WriteStr(writer, str) `。" + +#: ../../deprecations/c-api-pending-removal-in-3.18.rst:30 +msgid "" +":c:func:`!_PyUnicodeWriter_WriteSubstring`: replace " +"``_PyUnicodeWriter_WriteSubstring(&writer, str, start, end)`` with :c:func:" +"`PyUnicodeWriter_WriteSubstring(writer, str, start, end) " +"`." +msgstr "" +":c:func:`!_PyUnicodeWriter_WriteSubstring`：將 " +"``_PyUnicodeWriter_WriteSubstring(&writer, str, start, end)`` 替換為 :c:func:" +"`PyUnicodeWriter_WriteSubstring(writer, str, start, end) " +"`。" + +#: ../../deprecations/c-api-pending-removal-in-3.18.rst:33 +msgid "" +":c:func:`!_PyUnicodeWriter_WriteASCIIString`: replace " +"``_PyUnicodeWriter_WriteASCIIString(&writer, str)`` with :c:func:" +"`PyUnicodeWriter_WriteASCII(writer, str) `." +msgstr "" +":c:func:`!_PyUnicodeWriter_WriteASCIIString`：將 " +"``_PyUnicodeWriter_WriteASCIIString(&writer, str)`` 替換為 :c:func:" +"`PyUnicodeWriter_WriteASCII(writer, str) `。" + +#: ../../deprecations/c-api-pending-removal-in-3.18.rst:36 +msgid "" +":c:func:`!_PyUnicodeWriter_WriteLatin1String`: replace " +"``_PyUnicodeWriter_WriteLatin1String(&writer, str)`` with :c:func:" +"`PyUnicodeWriter_WriteUTF8(writer, str) `." +msgstr "" +":c:func:`!_PyUnicodeWriter_WriteLatin1String`：將 " +"``_PyUnicodeWriter_WriteLatin1String(&writer, str)`` 替換為 :c:func:" +"`PyUnicodeWriter_WriteUTF8(writer, str) `。" + +#: ../../deprecations/c-api-pending-removal-in-3.18.rst:39 +msgid ":c:func:`!_PyUnicodeWriter_Prepare`: (no replacement)." +msgstr ":c:func:`!_PyUnicodeWriter_Prepare`：（無替代方案）。" + +#: ../../deprecations/c-api-pending-removal-in-3.18.rst:40 +msgid ":c:func:`!_PyUnicodeWriter_PrepareKind`: (no replacement)." +msgstr ":c:func:`!_PyUnicodeWriter_PrepareKind`：（無替代方案）。" + +#: ../../deprecations/c-api-pending-removal-in-3.18.rst:41 +msgid ":c:func:`!_Py_HashPointer`: use :c:func:`Py_HashPointer`." +msgstr ":c:func:`!_Py_HashPointer`：請改用 :c:func:`Py_HashPointer`。" + +#: ../../deprecations/c-api-pending-removal-in-3.18.rst:42 +msgid ":c:func:`!_Py_fopen_obj`: use :c:func:`Py_fopen`." +msgstr ":c:func:`!_Py_fopen_obj`：請改用 :c:func:`Py_fopen`。" + +#: ../../deprecations/c-api-pending-removal-in-3.18.rst:44 +msgid "" +"The `pythoncapi-compat project `__ can be used to get these new public functions on Python 3.13 and older. " +"(Contributed by Victor Stinner in :gh:`128863`.)" +msgstr "" +"可以使用 `pythoncapi-compat project `__ 來取得這些於 Python 3.13 及更早版本的新公開函式。（由 Victor " +"Stinner 在 :gh:`128863` 貢獻）" + +#: ../../deprecations/c-api-pending-removal-in-future.rst:4 +msgid "" +"The following APIs are deprecated and will be removed, although there is " +"currently no date scheduled for their removal." +msgstr "下列 API 已被棄用並將會被移除，不過目前尚未訂定移除日期。" + +#: ../../deprecations/c-api-pending-removal-in-future.rst:7 +msgid ":c:macro:`Py_TPFLAGS_HAVE_FINALIZE`: Unneeded since Python 3.8." +msgstr ":c:macro:`Py_TPFLAGS_HAVE_FINALIZE`：自 Python 3.8 起不再需要" + +#: ../../deprecations/c-api-pending-removal-in-future.rst:9 +msgid ":c:func:`PyErr_Fetch`: Use :c:func:`PyErr_GetRaisedException` instead." +msgstr ":c:func:`PyErr_Fetch`：請改用 :c:func:`PyErr_GetRaisedException`。" + +#: ../../deprecations/c-api-pending-removal-in-future.rst:11 +msgid "" +":c:func:`PyErr_NormalizeException`: Use :c:func:`PyErr_GetRaisedException` " +"instead." +msgstr "" +":c:func:`PyErr_NormalizeException`：請改用 :c:func:" +"`PyErr_GetRaisedException`。" + +#: ../../deprecations/c-api-pending-removal-in-future.rst:13 +msgid "" +":c:func:`PyErr_Restore`: Use :c:func:`PyErr_SetRaisedException` instead." +msgstr ":c:func:`PyErr_Restore`：請改用 :c:func:`PyErr_SetRaisedException`。" + +#: ../../deprecations/c-api-pending-removal-in-future.rst:15 +msgid "" +":c:func:`PyModule_GetFilename`: Use :c:func:`PyModule_GetFilenameObject` " +"instead." +msgstr "" +":c:func:`PyModule_GetFilename`：請改用 :c:func:`PyModule_GetFilenameObject`。" + +#: ../../deprecations/c-api-pending-removal-in-future.rst:17 +msgid ":c:func:`PyOS_AfterFork`: Use :c:func:`PyOS_AfterFork_Child` instead." +msgstr ":c:func:`PyOS_AfterFork`：請改用 :c:func:`PyOS_AfterFork_Child`。" + +#: ../../deprecations/c-api-pending-removal-in-future.rst:19 +msgid "" +":c:func:`PySlice_GetIndicesEx`: Use :c:func:`PySlice_Unpack` and :c:func:" +"`PySlice_AdjustIndices` instead." +msgstr "" +":c:func:`PySlice_GetIndicesEx`：請改用 :c:func:`PySlice_Unpack` 和 :c:func:" +"`PySlice_AdjustIndices`。" + +#: ../../deprecations/c-api-pending-removal-in-future.rst:21 +msgid ":c:func:`PyUnicode_READY`: Unneeded since Python 3.12" +msgstr ":c:func:`PyUnicode_READY`：自 Python 3.12 起不再需要" + +#: ../../deprecations/c-api-pending-removal-in-future.rst:23 +msgid ":c:func:`!PyErr_Display`: Use :c:func:`PyErr_DisplayException` instead." +msgstr ":c:func:`!PyErr_Display`：請改用 :c:func:`PyErr_DisplayException`。" + +#: ../../deprecations/c-api-pending-removal-in-future.rst:25 +msgid "" +":c:func:`!_PyErr_ChainExceptions`: Use :c:func:`!_PyErr_ChainExceptions1` " +"instead." +msgstr "" +":c:func:`!_PyErr_ChainExceptions`：請改用 ``_PyErr_ChainExceptions1``。" + +#: ../../deprecations/c-api-pending-removal-in-future.rst:27 +msgid "" +":c:member:`!PyBytesObject.ob_shash` member: call :c:func:`PyObject_Hash` " +"instead." +msgstr "" +":c:member:`!PyBytesObject.ob_shash` 成員：請改為呼叫 :c:func:" +"`PyObject_Hash`。" + +#: ../../deprecations/c-api-pending-removal-in-future.rst:29 +msgid "Thread Local Storage (TLS) API:" +msgstr "執行緒局部儲存 (Thread Local Storage, TLS) API：" + +#: ../../deprecations/c-api-pending-removal-in-future.rst:31 +msgid "" +":c:func:`PyThread_create_key`: Use :c:func:`PyThread_tss_alloc` instead." +msgstr ":c:func:`PyThread_create_key`：請改用 :c:func:`PyThread_tss_alloc`。" + +#: ../../deprecations/c-api-pending-removal-in-future.rst:33 +msgid ":c:func:`PyThread_delete_key`: Use :c:func:`PyThread_tss_free` instead." +msgstr ":c:func:`PyThread_delete_key`：請改用 :c:func:`PyThread_tss_free`。" + +#: ../../deprecations/c-api-pending-removal-in-future.rst:35 +msgid "" +":c:func:`PyThread_set_key_value`: Use :c:func:`PyThread_tss_set` instead." +msgstr ":c:func:`PyThread_set_key_value`：請改用 :c:func:`PyThread_tss_set`。" + +#: ../../deprecations/c-api-pending-removal-in-future.rst:37 +msgid "" +":c:func:`PyThread_get_key_value`: Use :c:func:`PyThread_tss_get` instead." +msgstr ":c:func:`PyThread_get_key_value`：請改用 :c:func:`PyThread_tss_get`。" + +#: ../../deprecations/c-api-pending-removal-in-future.rst:39 +msgid "" +":c:func:`PyThread_delete_key_value`: Use :c:func:`PyThread_tss_delete` " +"instead." +msgstr "" +":c:func:`PyThread_delete_key_value`：請改用 :c:func:`PyThread_tss_delete`。" + +#: ../../deprecations/c-api-pending-removal-in-future.rst:41 +msgid ":c:func:`PyThread_ReInitTLS`: Unneeded since Python 3.7." +msgstr ":c:func:`PyThread_ReInitTLS`：自 Python 3.7 起不再需要。" diff --git a/deprecations/pending-removal-in-3.13.po b/deprecations/pending-removal-in-3.13.po index 75a9fcc92a..0c1a1d483b 100644 --- a/deprecations/pending-removal-in-3.13.po +++ b/deprecations/pending-removal-in-3.13.po @@ -1,148 +1,148 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-14 19:37+0000\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \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" - -#: ../../deprecations/pending-removal-in-3.13.rst:2 -msgid "Pending removal in Python 3.13" -msgstr "Python 3.13 中待移除的項目" - -#: ../../deprecations/pending-removal-in-3.13.rst:4 -msgid "Modules (see :pep:`594`):" -msgstr "模組（請見 :pep:`594`）：" - -#: ../../deprecations/pending-removal-in-3.13.rst:6 -msgid ":mod:`!aifc`" -msgstr ":mod:`!aifc`" - -#: ../../deprecations/pending-removal-in-3.13.rst:7 -msgid ":mod:`!audioop`" -msgstr ":mod:`!audioop`" - -#: ../../deprecations/pending-removal-in-3.13.rst:8 -msgid ":mod:`!cgi`" -msgstr ":mod:`!cgi`" - -#: ../../deprecations/pending-removal-in-3.13.rst:9 -msgid ":mod:`!cgitb`" -msgstr ":mod:`!cgitb`" - -#: ../../deprecations/pending-removal-in-3.13.rst:10 -msgid ":mod:`!chunk`" -msgstr ":mod:`!chunk`" - -#: ../../deprecations/pending-removal-in-3.13.rst:11 -msgid ":mod:`!crypt`" -msgstr ":mod:`!crypt`" - -#: ../../deprecations/pending-removal-in-3.13.rst:12 -msgid ":mod:`!imghdr`" -msgstr ":mod:`!imghdr`" - -#: ../../deprecations/pending-removal-in-3.13.rst:13 -msgid ":mod:`!mailcap`" -msgstr ":mod:`!mailcap`" - -#: ../../deprecations/pending-removal-in-3.13.rst:14 -msgid ":mod:`!msilib`" -msgstr ":mod:`!msilib`" - -#: ../../deprecations/pending-removal-in-3.13.rst:15 -msgid ":mod:`!nis`" -msgstr ":mod:`!nis`" - -#: ../../deprecations/pending-removal-in-3.13.rst:16 -msgid ":mod:`!nntplib`" -msgstr ":mod:`!nntplib`" - -#: ../../deprecations/pending-removal-in-3.13.rst:17 -msgid ":mod:`!ossaudiodev`" -msgstr ":mod:`!ossaudiodev`" - -#: ../../deprecations/pending-removal-in-3.13.rst:18 -msgid ":mod:`!pipes`" -msgstr ":mod:`!pipes`" - -#: ../../deprecations/pending-removal-in-3.13.rst:19 -msgid ":mod:`!sndhdr`" -msgstr ":mod:`!sndhdr`" - -#: ../../deprecations/pending-removal-in-3.13.rst:20 -msgid ":mod:`!spwd`" -msgstr ":mod:`!spwd`" - -#: ../../deprecations/pending-removal-in-3.13.rst:21 -msgid ":mod:`!sunau`" -msgstr ":mod:`!sunau`" - -#: ../../deprecations/pending-removal-in-3.13.rst:22 -msgid ":mod:`!telnetlib`" -msgstr ":mod:`!telnetlib`" - -#: ../../deprecations/pending-removal-in-3.13.rst:23 -msgid ":mod:`!uu`" -msgstr ":mod:`!uu`" - -#: ../../deprecations/pending-removal-in-3.13.rst:24 -msgid ":mod:`!xdrlib`" -msgstr ":mod:`!xdrlib`" - -#: ../../deprecations/pending-removal-in-3.13.rst:26 -msgid "Other modules:" -msgstr "其他模組：" - -#: ../../deprecations/pending-removal-in-3.13.rst:28 -msgid ":mod:`!lib2to3`, and the :program:`2to3` program (:gh:`84540`)" -msgstr ":mod:`!lib2to3` 和 :program:`2to3` 程式 (:gh:`84540`)" - -#: ../../deprecations/pending-removal-in-3.13.rst:30 -msgid "APIs:" -msgstr "API：" - -#: ../../deprecations/pending-removal-in-3.13.rst:32 -msgid ":class:`!configparser.LegacyInterpolation` (:gh:`90765`)" -msgstr ":class:`!configparser.LegacyInterpolation` (:gh:`90765`)" - -#: ../../deprecations/pending-removal-in-3.13.rst:33 -msgid "``locale.resetlocale()`` (:gh:`90817`)" -msgstr "``locale.resetlocale()`` (:gh:`90817`)" - -#: ../../deprecations/pending-removal-in-3.13.rst:34 -msgid ":meth:`!turtle.RawTurtle.settiltangle` (:gh:`50096`)" -msgstr ":meth:`!turtle.RawTurtle.settiltangle` (:gh:`50096`)" - -#: ../../deprecations/pending-removal-in-3.13.rst:35 -msgid ":func:`!unittest.findTestCases` (:gh:`50096`)" -msgstr ":func:`!unittest.findTestCases` (:gh:`50096`)" - -#: ../../deprecations/pending-removal-in-3.13.rst:36 -msgid ":func:`!unittest.getTestCaseNames` (:gh:`50096`)" -msgstr ":func:`!unittest.getTestCaseNames` (:gh:`50096`)" - -#: ../../deprecations/pending-removal-in-3.13.rst:37 -msgid ":func:`!unittest.makeSuite` (:gh:`50096`)" -msgstr ":func:`!unittest.makeSuite` (:gh:`50096`)" - -#: ../../deprecations/pending-removal-in-3.13.rst:38 -msgid ":meth:`!unittest.TestProgram.usageExit` (:gh:`67048`)" -msgstr ":meth:`!unittest.TestProgram.usageExit` (:gh:`67048`)" - -#: ../../deprecations/pending-removal-in-3.13.rst:39 -msgid ":class:`!webbrowser.MacOSX` (:gh:`86421`)" -msgstr ":class:`!webbrowser.MacOSX` (:gh:`86421`)" - -#: ../../deprecations/pending-removal-in-3.13.rst:40 -msgid ":class:`classmethod` descriptor chaining (:gh:`89519`)" -msgstr ":class:`classmethod` 描述器鏈接 (:gh:`89519`)" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-14 19:37+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \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" + +#: ../../deprecations/pending-removal-in-3.13.rst:2 +msgid "Pending removal in Python 3.13" +msgstr "Python 3.13 中待移除的項目" + +#: ../../deprecations/pending-removal-in-3.13.rst:4 +msgid "Modules (see :pep:`594`):" +msgstr "模組（請見 :pep:`594`）：" + +#: ../../deprecations/pending-removal-in-3.13.rst:6 +msgid ":mod:`!aifc`" +msgstr ":mod:`!aifc`" + +#: ../../deprecations/pending-removal-in-3.13.rst:7 +msgid ":mod:`!audioop`" +msgstr ":mod:`!audioop`" + +#: ../../deprecations/pending-removal-in-3.13.rst:8 +msgid ":mod:`!cgi`" +msgstr ":mod:`!cgi`" + +#: ../../deprecations/pending-removal-in-3.13.rst:9 +msgid ":mod:`!cgitb`" +msgstr ":mod:`!cgitb`" + +#: ../../deprecations/pending-removal-in-3.13.rst:10 +msgid ":mod:`!chunk`" +msgstr ":mod:`!chunk`" + +#: ../../deprecations/pending-removal-in-3.13.rst:11 +msgid ":mod:`!crypt`" +msgstr ":mod:`!crypt`" + +#: ../../deprecations/pending-removal-in-3.13.rst:12 +msgid ":mod:`!imghdr`" +msgstr ":mod:`!imghdr`" + +#: ../../deprecations/pending-removal-in-3.13.rst:13 +msgid ":mod:`!mailcap`" +msgstr ":mod:`!mailcap`" + +#: ../../deprecations/pending-removal-in-3.13.rst:14 +msgid ":mod:`!msilib`" +msgstr ":mod:`!msilib`" + +#: ../../deprecations/pending-removal-in-3.13.rst:15 +msgid ":mod:`!nis`" +msgstr ":mod:`!nis`" + +#: ../../deprecations/pending-removal-in-3.13.rst:16 +msgid ":mod:`!nntplib`" +msgstr ":mod:`!nntplib`" + +#: ../../deprecations/pending-removal-in-3.13.rst:17 +msgid ":mod:`!ossaudiodev`" +msgstr ":mod:`!ossaudiodev`" + +#: ../../deprecations/pending-removal-in-3.13.rst:18 +msgid ":mod:`!pipes`" +msgstr ":mod:`!pipes`" + +#: ../../deprecations/pending-removal-in-3.13.rst:19 +msgid ":mod:`!sndhdr`" +msgstr ":mod:`!sndhdr`" + +#: ../../deprecations/pending-removal-in-3.13.rst:20 +msgid ":mod:`!spwd`" +msgstr ":mod:`!spwd`" + +#: ../../deprecations/pending-removal-in-3.13.rst:21 +msgid ":mod:`!sunau`" +msgstr ":mod:`!sunau`" + +#: ../../deprecations/pending-removal-in-3.13.rst:22 +msgid ":mod:`!telnetlib`" +msgstr ":mod:`!telnetlib`" + +#: ../../deprecations/pending-removal-in-3.13.rst:23 +msgid ":mod:`!uu`" +msgstr ":mod:`!uu`" + +#: ../../deprecations/pending-removal-in-3.13.rst:24 +msgid ":mod:`!xdrlib`" +msgstr ":mod:`!xdrlib`" + +#: ../../deprecations/pending-removal-in-3.13.rst:26 +msgid "Other modules:" +msgstr "其他模組：" + +#: ../../deprecations/pending-removal-in-3.13.rst:28 +msgid ":mod:`!lib2to3`, and the :program:`2to3` program (:gh:`84540`)" +msgstr ":mod:`!lib2to3` 和 :program:`2to3` 程式 (:gh:`84540`)" + +#: ../../deprecations/pending-removal-in-3.13.rst:30 +msgid "APIs:" +msgstr "API：" + +#: ../../deprecations/pending-removal-in-3.13.rst:32 +msgid ":class:`!configparser.LegacyInterpolation` (:gh:`90765`)" +msgstr ":class:`!configparser.LegacyInterpolation` (:gh:`90765`)" + +#: ../../deprecations/pending-removal-in-3.13.rst:33 +msgid "``locale.resetlocale()`` (:gh:`90817`)" +msgstr "``locale.resetlocale()`` (:gh:`90817`)" + +#: ../../deprecations/pending-removal-in-3.13.rst:34 +msgid ":meth:`!turtle.RawTurtle.settiltangle` (:gh:`50096`)" +msgstr ":meth:`!turtle.RawTurtle.settiltangle` (:gh:`50096`)" + +#: ../../deprecations/pending-removal-in-3.13.rst:35 +msgid ":func:`!unittest.findTestCases` (:gh:`50096`)" +msgstr ":func:`!unittest.findTestCases` (:gh:`50096`)" + +#: ../../deprecations/pending-removal-in-3.13.rst:36 +msgid ":func:`!unittest.getTestCaseNames` (:gh:`50096`)" +msgstr ":func:`!unittest.getTestCaseNames` (:gh:`50096`)" + +#: ../../deprecations/pending-removal-in-3.13.rst:37 +msgid ":func:`!unittest.makeSuite` (:gh:`50096`)" +msgstr ":func:`!unittest.makeSuite` (:gh:`50096`)" + +#: ../../deprecations/pending-removal-in-3.13.rst:38 +msgid ":meth:`!unittest.TestProgram.usageExit` (:gh:`67048`)" +msgstr ":meth:`!unittest.TestProgram.usageExit` (:gh:`67048`)" + +#: ../../deprecations/pending-removal-in-3.13.rst:39 +msgid ":class:`!webbrowser.MacOSX` (:gh:`86421`)" +msgstr ":class:`!webbrowser.MacOSX` (:gh:`86421`)" + +#: ../../deprecations/pending-removal-in-3.13.rst:40 +msgid ":class:`classmethod` descriptor chaining (:gh:`89519`)" +msgstr ":class:`classmethod` 描述器鏈接 (:gh:`89519`)" diff --git a/deprecations/pending-removal-in-3.14.po b/deprecations/pending-removal-in-3.14.po index add170a79b..e5e2d663d9 100644 --- a/deprecations/pending-removal-in-3.14.po +++ b/deprecations/pending-removal-in-3.14.po @@ -1,248 +1,248 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-18 00:15+0000\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \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" - -#: ../../deprecations/pending-removal-in-3.14.rst:2 -msgid "Pending removal in Python 3.14" -msgstr "Python 3.14 中待移除的項目" - -#: ../../deprecations/pending-removal-in-3.14.rst:4 -msgid "" -":mod:`argparse`: The *type*, *choices*, and *metavar* parameters of :class:`!" -"argparse.BooleanOptionalAction` are deprecated and will be removed in 3.14. " -"(Contributed by Nikita Sobolev in :gh:`92248`.)" -msgstr "" -":mod:`argparse`：:class:`!argparse.BooleanOptionalAction` 的 *type*、" -"*choices* 和 *metavar* 參數已被棄用，將在 3.14 中移除。 (由 Nikita Sobolev " -"於 :gh:`92248` 貢獻。)" - -#: ../../deprecations/pending-removal-in-3.14.rst:9 -msgid "" -":mod:`ast`: The following features have been deprecated in documentation " -"since Python 3.8, now cause a :exc:`DeprecationWarning` to be emitted at " -"runtime when they are accessed or used, and will be removed in Python 3.14:" -msgstr "" -":mod:`ast`：自 Python 3.8 起，下列功能已在文件中被棄用，現在在存取或使用時會" -"於 runtime 發出 :exc:`DeprecationWarning`，並將在 Python 3.14 中移除：" - -#: ../../deprecations/pending-removal-in-3.14.rst:13 -msgid ":class:`!ast.Num`" -msgstr ":class:`!ast.Num`" - -#: ../../deprecations/pending-removal-in-3.14.rst:14 -msgid ":class:`!ast.Str`" -msgstr ":class:`!ast.Str`" - -#: ../../deprecations/pending-removal-in-3.14.rst:15 -msgid ":class:`!ast.Bytes`" -msgstr ":class:`!ast.Bytes`" - -#: ../../deprecations/pending-removal-in-3.14.rst:16 -msgid ":class:`!ast.NameConstant`" -msgstr ":class:`!ast.NameConstant`" - -#: ../../deprecations/pending-removal-in-3.14.rst:17 -msgid ":class:`!ast.Ellipsis`" -msgstr ":class:`!ast.Ellipsis`" - -#: ../../deprecations/pending-removal-in-3.14.rst:19 -msgid "" -"Use :class:`ast.Constant` instead. (Contributed by Serhiy Storchaka in :gh:" -"`90953`.)" -msgstr "" -"請改用 :class:`ast.Constant`。（由 Serhiy Storchaka 於 :gh:`90953` 貢獻。）" - -#: ../../deprecations/pending-removal-in-3.14.rst:22 -msgid ":mod:`asyncio`:" -msgstr ":mod:`asyncio`：" - -#: ../../deprecations/pending-removal-in-3.14.rst:24 -msgid "" -"The child watcher classes :class:`!asyncio.MultiLoopChildWatcher`, :class:`!" -"asyncio.FastChildWatcher`, :class:`!asyncio.AbstractChildWatcher` and :class:" -"`!asyncio.SafeChildWatcher` are deprecated and will be removed in Python " -"3.14. (Contributed by Kumar Aditya in :gh:`94597`.)" -msgstr "" -"已棄用並將在 Python 3.14 中移除的 child watcher 類別：:class:`!asyncio." -"MultiLoopChildWatcher`、:class:`!asyncio.FastChildWatcher`、:class:`!asyncio." -"AbstractChildWatcher` 和 :class:`!asyncio.SafeChildWatcher`。 (由 Kumar " -"Aditya 於 :gh:`94597` 貢獻。)" - -#: ../../deprecations/pending-removal-in-3.14.rst:30 -msgid "" -":func:`!asyncio.set_child_watcher`, :func:`!asyncio.get_child_watcher`, :" -"meth:`!asyncio.AbstractEventLoopPolicy.set_child_watcher` and :meth:`!" -"asyncio.AbstractEventLoopPolicy.get_child_watcher` are deprecated and will " -"be removed in Python 3.14. (Contributed by Kumar Aditya in :gh:`94597`.)" -msgstr "" -":func:`!asyncio.set_child_watcher`、:func:`!asyncio.get_child_watcher`、:" -"meth:`!asyncio.AbstractEventLoopPolicy.set_child_watcher` 和 :meth:`!asyncio." -"AbstractEventLoopPolicy.get_child_watcher` 已被棄用並將在 Python 3.14 中移" -"除。（由 Kumar Aditya 於 :gh:`94597` 貢獻。）" - -#: ../../deprecations/pending-removal-in-3.14.rst:36 -msgid "" -"The :meth:`~asyncio.get_event_loop` method of the default event loop policy " -"now emits a :exc:`DeprecationWarning` if there is no current event loop set " -"and it decides to create one. (Contributed by Serhiy Storchaka and Guido van " -"Rossum in :gh:`100160`.)" -msgstr "" -"預設事件迴圈策略的 :meth:`~asyncio.get_event_loop` 方法現在會在沒有設定目前事" -"件迴圈且決定建立一個時發出 :exc:`DeprecationWarning`。 (由 Serhiy Storchaka " -"和 Guido van Rossum 於 :gh:`100160` 貢獻。)" - -#: ../../deprecations/pending-removal-in-3.14.rst:41 -msgid "" -":mod:`email`: Deprecated the *isdst* parameter in :func:`email.utils." -"localtime`. (Contributed by Alan Williams in :gh:`72346`.)" -msgstr "" -":mod:`email`：已棄用 :func:`email.utils.localtime` 中的 *isdst* 參數。（由 " -"Alan Williams 於 :gh:`72346` 貢獻。）" - -#: ../../deprecations/pending-removal-in-3.14.rst:44 -msgid ":mod:`importlib.abc` deprecated classes:" -msgstr ":mod:`importlib.abc` 的已棄用類別：" - -#: ../../deprecations/pending-removal-in-3.14.rst:46 -msgid ":class:`!importlib.abc.ResourceReader`" -msgstr ":class:`!importlib.abc.ResourceReader`" - -#: ../../deprecations/pending-removal-in-3.14.rst:47 -msgid ":class:`!importlib.abc.Traversable`" -msgstr ":class:`!importlib.abc.Traversable`" - -#: ../../deprecations/pending-removal-in-3.14.rst:48 -msgid ":class:`!importlib.abc.TraversableResources`" -msgstr ":class:`!importlib.abc.TraversableResources`" - -#: ../../deprecations/pending-removal-in-3.14.rst:50 -msgid "Use :mod:`importlib.resources.abc` classes instead:" -msgstr "請改用 :mod:`importlib.resources.abc` 類別：" - -#: ../../deprecations/pending-removal-in-3.14.rst:52 -msgid ":class:`importlib.resources.abc.Traversable`" -msgstr ":class:`importlib.resources.abc.Traversable`" - -#: ../../deprecations/pending-removal-in-3.14.rst:53 -msgid ":class:`importlib.resources.abc.TraversableResources`" -msgstr ":class:`importlib.resources.abc.TraversableResources`" - -#: ../../deprecations/pending-removal-in-3.14.rst:55 -msgid "(Contributed by Jason R. Coombs and Hugo van Kemenade in :gh:`93963`.)" -msgstr "（由 Jason R. Coombs 和 Hugo van Kemenade 貢獻於 :gh:`93963`。）" - -#: ../../deprecations/pending-removal-in-3.14.rst:57 -msgid "" -":mod:`itertools` had undocumented, inefficient, historically buggy, and " -"inconsistent support for copy, deepcopy, and pickle operations. This will be " -"removed in 3.14 for a significant reduction in code volume and maintenance " -"burden. (Contributed by Raymond Hettinger in :gh:`101588`.)" -msgstr "" -":mod:`itertools` 有不以文件記錄、效率低下、過去常有 bug 且不一致的 copy、" -"deepcopy 和 pickle 操作支援。將在 3.14 中移除以大幅減少程式碼量和維護負擔。 " -"(由 Raymond Hettinger 於 :gh:`101588` 貢獻。)" - -#: ../../deprecations/pending-removal-in-3.14.rst:63 -msgid "" -":mod:`multiprocessing`: The default start method will change to a safer one " -"on Linux, BSDs, and other non-macOS POSIX platforms where ``'fork'`` is " -"currently the default (:gh:`84559`). Adding a runtime warning about this was " -"deemed too disruptive as the majority of code is not expected to care. Use " -"the :func:`~multiprocessing.get_context` or :func:`~multiprocessing." -"set_start_method` APIs to explicitly specify when your code *requires* " -"``'fork'``. See :ref:`multiprocessing-start-methods`." -msgstr "" -":mod:`multiprocessing`：預設的啟動方法將在 Linux、BSD 和其他非 macOS POSIX 平" -"台上更改為更安全的 方法，目前 ``'fork'`` 是預設值 (:gh:`84559`)。對此增加一" -"個 runtime 警告被認為太過擾人，因為 大多數程式碼不會在意。請使用 :func:" -"`~multiprocessing.get_context` 或 :func:`~multiprocessing.set_start_method` " -"API 來明確指定你的程式碼何時\\ *需要* ``'fork'``。請參閱 :ref:" -"`multiprocessing-start-methods`。" - -#: ../../deprecations/pending-removal-in-3.14.rst:71 -msgid "" -":mod:`pathlib`: :meth:`~pathlib.PurePath.is_relative_to` and :meth:`~pathlib." -"PurePath.relative_to`: passing additional arguments is deprecated." -msgstr "" -":mod:`pathlib`：已棄用 :meth:`~pathlib.PurePath.is_relative_to` 和 :meth:" -"`~pathlib.PurePath.relative_to`：額外引數的傳遞已被棄用。" - -#: ../../deprecations/pending-removal-in-3.14.rst:75 -msgid "" -":mod:`pkgutil`: :func:`!pkgutil.find_loader` and :func:`!pkgutil.get_loader` " -"now raise :exc:`DeprecationWarning`; use :func:`importlib.util.find_spec` " -"instead. (Contributed by Nikita Sobolev in :gh:`97850`.)" -msgstr "" -":mod:`pkgutil`：:func:`!pkgutil.find_loader` 和 :func:`!pkgutil.get_loader` " -"現在會引發 :exc:`DeprecationWarning`；請改用 :func:`importlib.util." -"find_spec`。 (由 Nikita Sobolev 於 :gh:`97850` 貢獻。)" - -#: ../../deprecations/pending-removal-in-3.14.rst:80 -msgid ":mod:`pty`:" -msgstr ":mod:`pty`：" - -#: ../../deprecations/pending-removal-in-3.14.rst:82 -msgid "``master_open()``: use :func:`pty.openpty`." -msgstr "``master_open()``：請用 :func:`pty.openpty`。" - -#: ../../deprecations/pending-removal-in-3.14.rst:83 -msgid "``slave_open()``: use :func:`pty.openpty`." -msgstr "``slave_open()``：請用 :func:`pty.openpty`。" - -#: ../../deprecations/pending-removal-in-3.14.rst:85 -msgid ":mod:`sqlite3`:" -msgstr ":mod:`sqlite3`：" - -#: ../../deprecations/pending-removal-in-3.14.rst:87 -msgid ":data:`!version` and :data:`!version_info`." -msgstr ":data:`!version` 和 :data:`!version_info`。" - -#: ../../deprecations/pending-removal-in-3.14.rst:89 -msgid "" -":meth:`~sqlite3.Cursor.execute` and :meth:`~sqlite3.Cursor.executemany` if :" -"ref:`named placeholders ` are used and *parameters* is " -"a sequence instead of a :class:`dict`." -msgstr "" -":meth:`~sqlite3.Cursor.execute` 和 :meth:`~sqlite3.Cursor.executemany`，如果" -"使用 :ref:`named placeholders ` 且 *parameters* 是序列" -"而不是 :class:`dict`。" - -#: ../../deprecations/pending-removal-in-3.14.rst:93 -msgid "" -":mod:`urllib`: :class:`!urllib.parse.Quoter` is deprecated: it was not " -"intended to be a public API. (Contributed by Gregory P. Smith in :gh:" -"`88168`.)" -msgstr "" -":mod:`urllib`：:class:`!urllib.parse.Quoter` 已被棄用：它並非預期的公開 API。" -"(由 Gregory P. Smith 於 :gh:`88168` 貢獻。)" - -#~ msgid "" -#~ ":mod:`collections.abc`: Deprecated :class:`!collections.abc.ByteString`. " -#~ "Prefer :class:`!Sequence` or :class:`~collections.abc.Buffer`. For use in " -#~ "typing, prefer a union, like ``bytes | bytearray``, or :class:" -#~ "`collections.abc.Buffer`. (Contributed by Shantanu Jain in :gh:`91896`.)" -#~ msgstr "" -#~ ":mod:`collections.abc`：已棄用 :class:`!collections.abc.ByteString`。請改" -#~ "用 :class:`!Sequence` 或 :class:`~collections.abc.Buffer`。在 typing 中使" -#~ "用時，請改用聯集，如 ``bytes | bytearray``，或 :class:`collections.abc." -#~ "Buffer`。（由 Shantanu Jain 於 :gh:`91896` 貢獻。）" - -#~ msgid "" -#~ ":mod:`typing`: :class:`!typing.ByteString`, deprecated since Python 3.9, " -#~ "now causes a :exc:`DeprecationWarning` to be emitted when it is used." -#~ msgstr "" -#~ ":mod:`typing`：自 Python 3.9 起已被棄用的 :class:`!typing.ByteString` 現在" -#~ "在使用時會發出 :exc:`DeprecationWarning`。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-18 00:15+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \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" + +#: ../../deprecations/pending-removal-in-3.14.rst:2 +msgid "Pending removal in Python 3.14" +msgstr "Python 3.14 中待移除的項目" + +#: ../../deprecations/pending-removal-in-3.14.rst:4 +msgid "" +":mod:`argparse`: The *type*, *choices*, and *metavar* parameters of :class:`!" +"argparse.BooleanOptionalAction` are deprecated and will be removed in 3.14. " +"(Contributed by Nikita Sobolev in :gh:`92248`.)" +msgstr "" +":mod:`argparse`：:class:`!argparse.BooleanOptionalAction` 的 *type*、" +"*choices* 和 *metavar* 參數已被棄用，將在 3.14 中移除。 (由 Nikita Sobolev " +"於 :gh:`92248` 貢獻。)" + +#: ../../deprecations/pending-removal-in-3.14.rst:9 +msgid "" +":mod:`ast`: The following features have been deprecated in documentation " +"since Python 3.8, now cause a :exc:`DeprecationWarning` to be emitted at " +"runtime when they are accessed or used, and will be removed in Python 3.14:" +msgstr "" +":mod:`ast`：自 Python 3.8 起，下列功能已在文件中被棄用，現在在存取或使用時會" +"於 runtime 發出 :exc:`DeprecationWarning`，並將在 Python 3.14 中移除：" + +#: ../../deprecations/pending-removal-in-3.14.rst:13 +msgid ":class:`!ast.Num`" +msgstr ":class:`!ast.Num`" + +#: ../../deprecations/pending-removal-in-3.14.rst:14 +msgid ":class:`!ast.Str`" +msgstr ":class:`!ast.Str`" + +#: ../../deprecations/pending-removal-in-3.14.rst:15 +msgid ":class:`!ast.Bytes`" +msgstr ":class:`!ast.Bytes`" + +#: ../../deprecations/pending-removal-in-3.14.rst:16 +msgid ":class:`!ast.NameConstant`" +msgstr ":class:`!ast.NameConstant`" + +#: ../../deprecations/pending-removal-in-3.14.rst:17 +msgid ":class:`!ast.Ellipsis`" +msgstr ":class:`!ast.Ellipsis`" + +#: ../../deprecations/pending-removal-in-3.14.rst:19 +msgid "" +"Use :class:`ast.Constant` instead. (Contributed by Serhiy Storchaka in :gh:" +"`90953`.)" +msgstr "" +"請改用 :class:`ast.Constant`。（由 Serhiy Storchaka 於 :gh:`90953` 貢獻。）" + +#: ../../deprecations/pending-removal-in-3.14.rst:22 +msgid ":mod:`asyncio`:" +msgstr ":mod:`asyncio`：" + +#: ../../deprecations/pending-removal-in-3.14.rst:24 +msgid "" +"The child watcher classes :class:`!asyncio.MultiLoopChildWatcher`, :class:`!" +"asyncio.FastChildWatcher`, :class:`!asyncio.AbstractChildWatcher` and :class:" +"`!asyncio.SafeChildWatcher` are deprecated and will be removed in Python " +"3.14. (Contributed by Kumar Aditya in :gh:`94597`.)" +msgstr "" +"已棄用並將在 Python 3.14 中移除的 child watcher 類別：:class:`!asyncio." +"MultiLoopChildWatcher`、:class:`!asyncio.FastChildWatcher`、:class:`!asyncio." +"AbstractChildWatcher` 和 :class:`!asyncio.SafeChildWatcher`。 (由 Kumar " +"Aditya 於 :gh:`94597` 貢獻。)" + +#: ../../deprecations/pending-removal-in-3.14.rst:30 +msgid "" +":func:`!asyncio.set_child_watcher`, :func:`!asyncio.get_child_watcher`, :" +"meth:`!asyncio.AbstractEventLoopPolicy.set_child_watcher` and :meth:`!" +"asyncio.AbstractEventLoopPolicy.get_child_watcher` are deprecated and will " +"be removed in Python 3.14. (Contributed by Kumar Aditya in :gh:`94597`.)" +msgstr "" +":func:`!asyncio.set_child_watcher`、:func:`!asyncio.get_child_watcher`、:" +"meth:`!asyncio.AbstractEventLoopPolicy.set_child_watcher` 和 :meth:`!asyncio." +"AbstractEventLoopPolicy.get_child_watcher` 已被棄用並將在 Python 3.14 中移" +"除。（由 Kumar Aditya 於 :gh:`94597` 貢獻。）" + +#: ../../deprecations/pending-removal-in-3.14.rst:36 +msgid "" +"The :meth:`~asyncio.get_event_loop` method of the default event loop policy " +"now emits a :exc:`DeprecationWarning` if there is no current event loop set " +"and it decides to create one. (Contributed by Serhiy Storchaka and Guido van " +"Rossum in :gh:`100160`.)" +msgstr "" +"預設事件迴圈策略的 :meth:`~asyncio.get_event_loop` 方法現在會在沒有設定目前事" +"件迴圈且決定建立一個時發出 :exc:`DeprecationWarning`。 (由 Serhiy Storchaka " +"和 Guido van Rossum 於 :gh:`100160` 貢獻。)" + +#: ../../deprecations/pending-removal-in-3.14.rst:41 +msgid "" +":mod:`email`: Deprecated the *isdst* parameter in :func:`email.utils." +"localtime`. (Contributed by Alan Williams in :gh:`72346`.)" +msgstr "" +":mod:`email`：已棄用 :func:`email.utils.localtime` 中的 *isdst* 參數。（由 " +"Alan Williams 於 :gh:`72346` 貢獻。）" + +#: ../../deprecations/pending-removal-in-3.14.rst:44 +msgid ":mod:`importlib.abc` deprecated classes:" +msgstr ":mod:`importlib.abc` 的已棄用類別：" + +#: ../../deprecations/pending-removal-in-3.14.rst:46 +msgid ":class:`!importlib.abc.ResourceReader`" +msgstr ":class:`!importlib.abc.ResourceReader`" + +#: ../../deprecations/pending-removal-in-3.14.rst:47 +msgid ":class:`!importlib.abc.Traversable`" +msgstr ":class:`!importlib.abc.Traversable`" + +#: ../../deprecations/pending-removal-in-3.14.rst:48 +msgid ":class:`!importlib.abc.TraversableResources`" +msgstr ":class:`!importlib.abc.TraversableResources`" + +#: ../../deprecations/pending-removal-in-3.14.rst:50 +msgid "Use :mod:`importlib.resources.abc` classes instead:" +msgstr "請改用 :mod:`importlib.resources.abc` 類別：" + +#: ../../deprecations/pending-removal-in-3.14.rst:52 +msgid ":class:`importlib.resources.abc.Traversable`" +msgstr ":class:`importlib.resources.abc.Traversable`" + +#: ../../deprecations/pending-removal-in-3.14.rst:53 +msgid ":class:`importlib.resources.abc.TraversableResources`" +msgstr ":class:`importlib.resources.abc.TraversableResources`" + +#: ../../deprecations/pending-removal-in-3.14.rst:55 +msgid "(Contributed by Jason R. Coombs and Hugo van Kemenade in :gh:`93963`.)" +msgstr "（由 Jason R. Coombs 和 Hugo van Kemenade 貢獻於 :gh:`93963`。）" + +#: ../../deprecations/pending-removal-in-3.14.rst:57 +msgid "" +":mod:`itertools` had undocumented, inefficient, historically buggy, and " +"inconsistent support for copy, deepcopy, and pickle operations. This will be " +"removed in 3.14 for a significant reduction in code volume and maintenance " +"burden. (Contributed by Raymond Hettinger in :gh:`101588`.)" +msgstr "" +":mod:`itertools` 有不以文件記錄、效率低下、過去常有 bug 且不一致的 copy、" +"deepcopy 和 pickle 操作支援。將在 3.14 中移除以大幅減少程式碼量和維護負擔。 " +"(由 Raymond Hettinger 於 :gh:`101588` 貢獻。)" + +#: ../../deprecations/pending-removal-in-3.14.rst:63 +msgid "" +":mod:`multiprocessing`: The default start method will change to a safer one " +"on Linux, BSDs, and other non-macOS POSIX platforms where ``'fork'`` is " +"currently the default (:gh:`84559`). Adding a runtime warning about this was " +"deemed too disruptive as the majority of code is not expected to care. Use " +"the :func:`~multiprocessing.get_context` or :func:`~multiprocessing." +"set_start_method` APIs to explicitly specify when your code *requires* " +"``'fork'``. See :ref:`multiprocessing-start-methods`." +msgstr "" +":mod:`multiprocessing`：預設的啟動方法將在 Linux、BSD 和其他非 macOS POSIX 平" +"台上更改為更安全的 方法，目前 ``'fork'`` 是預設值 (:gh:`84559`)。對此增加一" +"個 runtime 警告被認為太過擾人，因為 大多數程式碼不會在意。請使用 :func:" +"`~multiprocessing.get_context` 或 :func:`~multiprocessing.set_start_method` " +"API 來明確指定你的程式碼何時\\ *需要* ``'fork'``。請參閱 :ref:" +"`multiprocessing-start-methods`。" + +#: ../../deprecations/pending-removal-in-3.14.rst:71 +msgid "" +":mod:`pathlib`: :meth:`~pathlib.PurePath.is_relative_to` and :meth:`~pathlib." +"PurePath.relative_to`: passing additional arguments is deprecated." +msgstr "" +":mod:`pathlib`：已棄用 :meth:`~pathlib.PurePath.is_relative_to` 和 :meth:" +"`~pathlib.PurePath.relative_to`：額外引數的傳遞已被棄用。" + +#: ../../deprecations/pending-removal-in-3.14.rst:75 +msgid "" +":mod:`pkgutil`: :func:`!pkgutil.find_loader` and :func:`!pkgutil.get_loader` " +"now raise :exc:`DeprecationWarning`; use :func:`importlib.util.find_spec` " +"instead. (Contributed by Nikita Sobolev in :gh:`97850`.)" +msgstr "" +":mod:`pkgutil`：:func:`!pkgutil.find_loader` 和 :func:`!pkgutil.get_loader` " +"現在會引發 :exc:`DeprecationWarning`；請改用 :func:`importlib.util." +"find_spec`。 (由 Nikita Sobolev 於 :gh:`97850` 貢獻。)" + +#: ../../deprecations/pending-removal-in-3.14.rst:80 +msgid ":mod:`pty`:" +msgstr ":mod:`pty`：" + +#: ../../deprecations/pending-removal-in-3.14.rst:82 +msgid "``master_open()``: use :func:`pty.openpty`." +msgstr "``master_open()``：請用 :func:`pty.openpty`。" + +#: ../../deprecations/pending-removal-in-3.14.rst:83 +msgid "``slave_open()``: use :func:`pty.openpty`." +msgstr "``slave_open()``：請用 :func:`pty.openpty`。" + +#: ../../deprecations/pending-removal-in-3.14.rst:85 +msgid ":mod:`sqlite3`:" +msgstr ":mod:`sqlite3`：" + +#: ../../deprecations/pending-removal-in-3.14.rst:87 +msgid ":data:`!version` and :data:`!version_info`." +msgstr ":data:`!version` 和 :data:`!version_info`。" + +#: ../../deprecations/pending-removal-in-3.14.rst:89 +msgid "" +":meth:`~sqlite3.Cursor.execute` and :meth:`~sqlite3.Cursor.executemany` if :" +"ref:`named placeholders ` are used and *parameters* is " +"a sequence instead of a :class:`dict`." +msgstr "" +":meth:`~sqlite3.Cursor.execute` 和 :meth:`~sqlite3.Cursor.executemany`，如果" +"使用 :ref:`named placeholders ` 且 *parameters* 是序列" +"而不是 :class:`dict`。" + +#: ../../deprecations/pending-removal-in-3.14.rst:93 +msgid "" +":mod:`urllib`: :class:`!urllib.parse.Quoter` is deprecated: it was not " +"intended to be a public API. (Contributed by Gregory P. Smith in :gh:" +"`88168`.)" +msgstr "" +":mod:`urllib`：:class:`!urllib.parse.Quoter` 已被棄用：它並非預期的公開 API。" +"(由 Gregory P. Smith 於 :gh:`88168` 貢獻。)" + +#~ msgid "" +#~ ":mod:`collections.abc`: Deprecated :class:`!collections.abc.ByteString`. " +#~ "Prefer :class:`!Sequence` or :class:`~collections.abc.Buffer`. For use in " +#~ "typing, prefer a union, like ``bytes | bytearray``, or :class:" +#~ "`collections.abc.Buffer`. (Contributed by Shantanu Jain in :gh:`91896`.)" +#~ msgstr "" +#~ ":mod:`collections.abc`：已棄用 :class:`!collections.abc.ByteString`。請改" +#~ "用 :class:`!Sequence` 或 :class:`~collections.abc.Buffer`。在 typing 中使" +#~ "用時，請改用聯集，如 ``bytes | bytearray``，或 :class:`collections.abc." +#~ "Buffer`。（由 Shantanu Jain 於 :gh:`91896` 貢獻。）" + +#~ msgid "" +#~ ":mod:`typing`: :class:`!typing.ByteString`, deprecated since Python 3.9, " +#~ "now causes a :exc:`DeprecationWarning` to be emitted when it is used." +#~ msgstr "" +#~ ":mod:`typing`：自 Python 3.9 起已被棄用的 :class:`!typing.ByteString` 現在" +#~ "在使用時會發出 :exc:`DeprecationWarning`。" diff --git a/deprecations/pending-removal-in-3.15.po b/deprecations/pending-removal-in-3.15.po index 0d86e896d6..dcd36095ba 100644 --- a/deprecations/pending-removal-in-3.15.po +++ b/deprecations/pending-removal-in-3.15.po @@ -1,242 +1,242 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \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" - -#: ../../deprecations/pending-removal-in-3.15.rst:2 -msgid "Pending removal in Python 3.15" -msgstr "Python 3.15 中待移除的項目" - -#: ../../deprecations/pending-removal-in-3.15.rst:4 -msgid "The import system:" -msgstr "引入系統 (import system)：" - -#: ../../deprecations/pending-removal-in-3.15.rst:6 -msgid "" -"Setting :attr:`~module.__cached__` on a module while failing to " -"set :attr:`__spec__.cached ` is " -"deprecated. In Python 3.15, :attr:`!__cached__` will cease to be set or take " -"into consideration by the import system or standard library. (:gh:`97879`)" -msgstr "" -"在模組上設定 :attr:`~module.__cached__` 而沒有設定 :attr:`__spec__.cached " -"` 的做法已被棄用。在 Python 3.15 中，" -"引入系統或標準函式庫將不再設定或考慮 :attr:`!__cached__`。(:gh:`97879`)" - -#: ../../deprecations/pending-removal-in-3.15.rst:11 -msgid "" -"Setting :attr:`~module.__package__` on a module while failing to " -"set :attr:`__spec__.parent ` is " -"deprecated. In Python 3.15, :attr:`!__package__` will cease to be set or " -"take into consideration by the import system or standard library. " -"(:gh:`97879`)" -msgstr "" -"在模組上設定 :attr:`~module.__package__` 而沒有設定 :attr:`__spec__.parent " -"` 的做法已被棄用。在 Python 3.15 中，" -"引入系統或標準函式庫將不再設定或考慮 :attr:`!__package__`。(:gh:`97879`)" - -#: ../../deprecations/pending-removal-in-3.15.rst:16 -msgid ":mod:`ctypes`:" -msgstr ":mod:`ctypes`：" - -#: ../../deprecations/pending-removal-in-3.15.rst:18 -msgid "" -"The undocumented :func:`!ctypes.SetPointerType` function has been deprecated " -"since Python 3.13." -msgstr "" -"自 Python 3.13 起，未記錄的 :func:`!ctypes.SetPointerType` 函式已被棄用。" - -#: ../../deprecations/pending-removal-in-3.15.rst:21 -msgid ":mod:`http.server`:" -msgstr ":mod:`http.server`：" - -#: ../../deprecations/pending-removal-in-3.15.rst:23 -msgid "" -"The obsolete and rarely used :class:`~http.server.CGIHTTPRequestHandler` has " -"been deprecated since Python 3.13. No direct replacement exists. *Anything* " -"is better than CGI to interface a web server with a request handler." -msgstr "" -"過時且很少使用的 :class:`~http.server.CGIHTTPRequestHandler` 自 Python 3.13 " -"起已被棄用。不存在直接的替代。*任何東西*\\ 都比 CGI 更好地將 Web 伺服器與請求" -"處理程序介接起來。" - -#: ../../deprecations/pending-removal-in-3.15.rst:29 -msgid "" -"The :option:`!--cgi` flag to the :program:`python -m http.server` command-" -"line interface has been deprecated since Python 3.13." -msgstr "" -"自 Python 3.13 起，:program:`python -m http.server` 命令列介面的 :option:`!--" -"cgi` 旗標已被棄用。" - -#: ../../deprecations/pending-removal-in-3.15.rst:32 -msgid ":mod:`importlib`:" -msgstr ":mod:`importlib`：" - -#: ../../deprecations/pending-removal-in-3.15.rst:34 -msgid "``load_module()`` method: use ``exec_module()`` instead." -msgstr "``load_module()`` method：請改用 ``exec_module()``。" - -#: ../../deprecations/pending-removal-in-3.15.rst:36 -msgid ":class:`locale`:" -msgstr ":class:`locale`：" - -#: ../../deprecations/pending-removal-in-3.15.rst:38 -msgid "" -"The :func:`~locale.getdefaultlocale` function has been deprecated since " -"Python 3.11. Its removal was originally planned for Python 3.13 " -"(:gh:`90817`), but has been postponed to Python 3.15. " -"Use :func:`~locale.getlocale`, :func:`~locale.setlocale`, " -"and :func:`~locale.getencoding` instead. (Contributed by Hugo van Kemenade " -"in :gh:`111187`.)" -msgstr "" -":func:`~locale.getdefaultlocale` 已在 Python 3.11 中被棄用，原本計劃在 " -"Python 3.13 中移除 (:gh:`90817`)，但被延後至 Python 3.15。請改" -"用 :func:`~locale.getlocale`、:func:`~locale.setlocale` " -"和 :func:`~locale.getencoding`。 (由 Hugo van Kemenade 於 :gh:`111187` 貢" -"獻。)" - -#: ../../deprecations/pending-removal-in-3.15.rst:46 -msgid ":mod:`pathlib`:" -msgstr ":mod:`pathlib`：" - -#: ../../deprecations/pending-removal-in-3.15.rst:48 -msgid "" -":meth:`.PurePath.is_reserved` has been deprecated since Python 3.13. " -"Use :func:`os.path.isreserved` to detect reserved paths on Windows." -msgstr "" -":meth:`.PurePath.is_reserved` 已自 Python 3.13 被棄用。請" -"用 :func:`os.path.isreserved` 來偵測 Windows 上的保留路徑。" - -#: ../../deprecations/pending-removal-in-3.15.rst:52 -msgid ":mod:`platform`:" -msgstr ":mod:`platform`：" - -#: ../../deprecations/pending-removal-in-3.15.rst:54 -msgid "" -":func:`~platform.java_ver` has been deprecated since Python 3.13. This " -"function is only useful for Jython support, has a confusing API, and is " -"largely untested." -msgstr "" -"自 Python 3.13 起，:func:`~platform.java_ver` 已被棄用。此函式僅對 Jython 支" -"援有用，具有令人困惑的 API，基本上未經測試。" - -#: ../../deprecations/pending-removal-in-3.15.rst:58 -msgid ":mod:`sysconfig`:" -msgstr ":mod:`sysconfig`：" - -#: ../../deprecations/pending-removal-in-3.15.rst:60 -msgid "" -"The *check_home* argument of :func:`sysconfig.is_python_build` has been " -"deprecated since Python 3.12." -msgstr "" -":func:`sysconfig.is_python_build` 的 *check_home* 引數自 Python 3.12 起已被棄" -"用。" - -#: ../../deprecations/pending-removal-in-3.15.rst:63 -msgid ":mod:`threading`:" -msgstr ":mod:`threading`：" - -#: ../../deprecations/pending-removal-in-3.15.rst:65 -msgid "" -":func:`~threading.RLock` will take no arguments in Python 3.15. Passing any " -"arguments has been deprecated since Python 3.14, as the Python version does " -"not permit any arguments, but the C version allows any number of positional " -"or keyword arguments, ignoring every argument." -msgstr "" -":func:`~threading.RLock` 在 Python 3.15 中將不接受任何引數。自 Python 3.14 " -"起，傳遞任何引數的用法已被棄用，因為 Python 版本不允許任何引數，但 C 版本允許" -"任意數量的位置或關鍵字引數，並忽略每個引數。" - -#: ../../deprecations/pending-removal-in-3.15.rst:71 -msgid ":mod:`types`:" -msgstr ":mod:`types`：" - -#: ../../deprecations/pending-removal-in-3.15.rst:73 -msgid "" -":class:`types.CodeType`: Accessing :attr:`~codeobject.co_lnotab` was " -"deprecated in :pep:`626` since 3.10 and was planned to be removed in 3.12, " -"but it only got a proper :exc:`DeprecationWarning` in 3.12. May be removed " -"in 3.15. (Contributed by Nikita Sobolev in :gh:`101866`.)" -msgstr "" -":class:`types.CodeType`：自 3.10 起，存取 :attr:`~codeobject.co_lnotab` 已" -"在 :pep:`626` 中被棄用，並計劃在 3.12 中移除，但只在 3.12 中於適當時發" -"出 :exc:`DeprecationWarning`。可能在 3.15 中移除。（由 Nikita Sobolev " -"於 :gh:`101866` 貢獻。）" - -#: ../../deprecations/pending-removal-in-3.15.rst:80 -msgid ":mod:`typing`:" -msgstr ":mod:`typing`：" - -#: ../../deprecations/pending-removal-in-3.15.rst:82 -msgid "" -"The undocumented keyword argument syntax for " -"creating :class:`~typing.NamedTuple` classes (for example, ``Point = " -"NamedTuple(\"Point\", x=int, y=int)``) has been deprecated since Python " -"3.13. Use the class-based syntax or the functional syntax instead." -msgstr "" -"用於建立 :class:`~typing.NamedTuple` 類別的未以文件記錄之關鍵字引數語法 " -"(``Point = NamedTuple(\"Point\", x=int, y=int)``) 已自 Python 3.13 棄用。請改" -"用基於類別的語法或函式語法 (functional syntax)。" - -#: ../../deprecations/pending-removal-in-3.15.rst:88 -msgid "" -"When using the functional syntax of :class:`~typing.TypedDict`\\s, failing " -"to pass a value to the *fields* parameter (``TD = TypedDict(\"TD\")``) or " -"passing ``None`` (``TD = TypedDict(\"TD\", None)``) has been deprecated " -"since Python 3.13. Use ``class TD(TypedDict): pass`` or ``TD = " -"TypedDict(\"TD\", {})`` to create a TypedDict with zero field." -msgstr "" -"當使用 :class:`~typing.TypedDict` 的函式語法時，未傳遞值給 *fields* 參數 " -"(``TD = TypedDict(\"TD\")``) 或傳遞 ``None`` (``TD = TypedDict(\"TD\", " -"None)``) 的做法自 Python 3.13 起已被棄用。請使用 ``class TD(TypedDict): " -"pass`` 或 ``TD = TypedDict(\"TD\", {})`` 來建立具有零個欄位的 TypedDict。" - -#: ../../deprecations/pending-removal-in-3.15.rst:95 -msgid "" -"The :func:`typing.no_type_check_decorator` decorator function has been " -"deprecated since Python 3.13. After eight years in the :mod:`typing` module, " -"it has yet to be supported by any major type checker." -msgstr "" -"自 Python 3.13 起，:func:`typing.no_type_check_decorator` 裝飾器函式已被棄" -"用。在 :mod:`typing` 模組中使用了八年之後，它尚未得到任何主要型別檢查器的支" -"援。" - -#: ../../deprecations/pending-removal-in-3.15.rst:100 -msgid ":mod:`wave`:" -msgstr ":mod:`wave`：" - -#: ../../deprecations/pending-removal-in-3.15.rst:102 -msgid "" -"The :meth:`~wave.Wave_read.getmark`, :meth:`!setmark`, " -"and :meth:`~wave.Wave_read.getmarkers` methods of " -"the :class:`~wave.Wave_read` and :class:`~wave.Wave_write` classes have been " -"deprecated since Python 3.13." -msgstr "" -"已棄用 :class:`~wave.Wave_read` 和 :class:`~wave.Wave_write` 類別" -"的 :meth:`~wave.Wave_read.getmark`、:meth:`!setmark` " -"和 :meth:`~wave.Wave_read.getmarkers` 方法自 Python 3.13 被棄用。" - -#: ../../deprecations/pending-removal-in-3.15.rst:107 -msgid ":mod:`zipimport`:" -msgstr ":mod:`zipimport`：" - -#: ../../deprecations/pending-removal-in-3.15.rst:109 -msgid "" -":meth:`~zipimport.zipimporter.load_module` has been deprecated since Python " -"3.10. Use :meth:`~zipimport.zipimporter.exec_module` instead. (Contributed " -"by Jiahao Li in :gh:`125746`.)" -msgstr "" -":meth:`~zipimport.zipimporter.load_module` 自 Python 3.10 被棄用。請改" -"用 :meth:`~zipimport.zipimporter.exec_module`。（由 Jiahao Li " -"於 :gh:`125746` 貢獻。）" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \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" + +#: ../../deprecations/pending-removal-in-3.15.rst:2 +msgid "Pending removal in Python 3.15" +msgstr "Python 3.15 中待移除的項目" + +#: ../../deprecations/pending-removal-in-3.15.rst:4 +msgid "The import system:" +msgstr "引入系統 (import system)：" + +#: ../../deprecations/pending-removal-in-3.15.rst:6 +msgid "" +"Setting :attr:`~module.__cached__` on a module while failing to " +"set :attr:`__spec__.cached ` is " +"deprecated. In Python 3.15, :attr:`!__cached__` will cease to be set or take " +"into consideration by the import system or standard library. (:gh:`97879`)" +msgstr "" +"在模組上設定 :attr:`~module.__cached__` 而沒有設定 :attr:`__spec__.cached " +"` 的做法已被棄用。在 Python 3.15 中，" +"引入系統或標準函式庫將不再設定或考慮 :attr:`!__cached__`。(:gh:`97879`)" + +#: ../../deprecations/pending-removal-in-3.15.rst:11 +msgid "" +"Setting :attr:`~module.__package__` on a module while failing to " +"set :attr:`__spec__.parent ` is " +"deprecated. In Python 3.15, :attr:`!__package__` will cease to be set or " +"take into consideration by the import system or standard library. " +"(:gh:`97879`)" +msgstr "" +"在模組上設定 :attr:`~module.__package__` 而沒有設定 :attr:`__spec__.parent " +"` 的做法已被棄用。在 Python 3.15 中，" +"引入系統或標準函式庫將不再設定或考慮 :attr:`!__package__`。(:gh:`97879`)" + +#: ../../deprecations/pending-removal-in-3.15.rst:16 +msgid ":mod:`ctypes`:" +msgstr ":mod:`ctypes`：" + +#: ../../deprecations/pending-removal-in-3.15.rst:18 +msgid "" +"The undocumented :func:`!ctypes.SetPointerType` function has been deprecated " +"since Python 3.13." +msgstr "" +"自 Python 3.13 起，未記錄的 :func:`!ctypes.SetPointerType` 函式已被棄用。" + +#: ../../deprecations/pending-removal-in-3.15.rst:21 +msgid ":mod:`http.server`:" +msgstr ":mod:`http.server`：" + +#: ../../deprecations/pending-removal-in-3.15.rst:23 +msgid "" +"The obsolete and rarely used :class:`~http.server.CGIHTTPRequestHandler` has " +"been deprecated since Python 3.13. No direct replacement exists. *Anything* " +"is better than CGI to interface a web server with a request handler." +msgstr "" +"過時且很少使用的 :class:`~http.server.CGIHTTPRequestHandler` 自 Python 3.13 " +"起已被棄用。不存在直接的替代。*任何東西*\\ 都比 CGI 更好地將 Web 伺服器與請求" +"處理程序介接起來。" + +#: ../../deprecations/pending-removal-in-3.15.rst:29 +msgid "" +"The :option:`!--cgi` flag to the :program:`python -m http.server` command-" +"line interface has been deprecated since Python 3.13." +msgstr "" +"自 Python 3.13 起，:program:`python -m http.server` 命令列介面的 :option:`!--" +"cgi` 旗標已被棄用。" + +#: ../../deprecations/pending-removal-in-3.15.rst:32 +msgid ":mod:`importlib`:" +msgstr ":mod:`importlib`：" + +#: ../../deprecations/pending-removal-in-3.15.rst:34 +msgid "``load_module()`` method: use ``exec_module()`` instead." +msgstr "``load_module()`` method：請改用 ``exec_module()``。" + +#: ../../deprecations/pending-removal-in-3.15.rst:36 +msgid ":class:`locale`:" +msgstr ":class:`locale`：" + +#: ../../deprecations/pending-removal-in-3.15.rst:38 +msgid "" +"The :func:`~locale.getdefaultlocale` function has been deprecated since " +"Python 3.11. Its removal was originally planned for Python 3.13 " +"(:gh:`90817`), but has been postponed to Python 3.15. " +"Use :func:`~locale.getlocale`, :func:`~locale.setlocale`, " +"and :func:`~locale.getencoding` instead. (Contributed by Hugo van Kemenade " +"in :gh:`111187`.)" +msgstr "" +":func:`~locale.getdefaultlocale` 已在 Python 3.11 中被棄用，原本計劃在 " +"Python 3.13 中移除 (:gh:`90817`)，但被延後至 Python 3.15。請改" +"用 :func:`~locale.getlocale`、:func:`~locale.setlocale` " +"和 :func:`~locale.getencoding`。 (由 Hugo van Kemenade 於 :gh:`111187` 貢" +"獻。)" + +#: ../../deprecations/pending-removal-in-3.15.rst:46 +msgid ":mod:`pathlib`:" +msgstr ":mod:`pathlib`：" + +#: ../../deprecations/pending-removal-in-3.15.rst:48 +msgid "" +":meth:`.PurePath.is_reserved` has been deprecated since Python 3.13. " +"Use :func:`os.path.isreserved` to detect reserved paths on Windows." +msgstr "" +":meth:`.PurePath.is_reserved` 已自 Python 3.13 被棄用。請" +"用 :func:`os.path.isreserved` 來偵測 Windows 上的保留路徑。" + +#: ../../deprecations/pending-removal-in-3.15.rst:52 +msgid ":mod:`platform`:" +msgstr ":mod:`platform`：" + +#: ../../deprecations/pending-removal-in-3.15.rst:54 +msgid "" +":func:`~platform.java_ver` has been deprecated since Python 3.13. This " +"function is only useful for Jython support, has a confusing API, and is " +"largely untested." +msgstr "" +"自 Python 3.13 起，:func:`~platform.java_ver` 已被棄用。此函式僅對 Jython 支" +"援有用，具有令人困惑的 API，基本上未經測試。" + +#: ../../deprecations/pending-removal-in-3.15.rst:58 +msgid ":mod:`sysconfig`:" +msgstr ":mod:`sysconfig`：" + +#: ../../deprecations/pending-removal-in-3.15.rst:60 +msgid "" +"The *check_home* argument of :func:`sysconfig.is_python_build` has been " +"deprecated since Python 3.12." +msgstr "" +":func:`sysconfig.is_python_build` 的 *check_home* 引數自 Python 3.12 起已被棄" +"用。" + +#: ../../deprecations/pending-removal-in-3.15.rst:63 +msgid ":mod:`threading`:" +msgstr ":mod:`threading`：" + +#: ../../deprecations/pending-removal-in-3.15.rst:65 +msgid "" +":func:`~threading.RLock` will take no arguments in Python 3.15. Passing any " +"arguments has been deprecated since Python 3.14, as the Python version does " +"not permit any arguments, but the C version allows any number of positional " +"or keyword arguments, ignoring every argument." +msgstr "" +":func:`~threading.RLock` 在 Python 3.15 中將不接受任何引數。自 Python 3.14 " +"起，傳遞任何引數的用法已被棄用，因為 Python 版本不允許任何引數，但 C 版本允許" +"任意數量的位置或關鍵字引數，並忽略每個引數。" + +#: ../../deprecations/pending-removal-in-3.15.rst:71 +msgid ":mod:`types`:" +msgstr ":mod:`types`：" + +#: ../../deprecations/pending-removal-in-3.15.rst:73 +msgid "" +":class:`types.CodeType`: Accessing :attr:`~codeobject.co_lnotab` was " +"deprecated in :pep:`626` since 3.10 and was planned to be removed in 3.12, " +"but it only got a proper :exc:`DeprecationWarning` in 3.12. May be removed " +"in 3.15. (Contributed by Nikita Sobolev in :gh:`101866`.)" +msgstr "" +":class:`types.CodeType`：自 3.10 起，存取 :attr:`~codeobject.co_lnotab` 已" +"在 :pep:`626` 中被棄用，並計劃在 3.12 中移除，但只在 3.12 中於適當時發" +"出 :exc:`DeprecationWarning`。可能在 3.15 中移除。（由 Nikita Sobolev " +"於 :gh:`101866` 貢獻。）" + +#: ../../deprecations/pending-removal-in-3.15.rst:80 +msgid ":mod:`typing`:" +msgstr ":mod:`typing`：" + +#: ../../deprecations/pending-removal-in-3.15.rst:82 +msgid "" +"The undocumented keyword argument syntax for " +"creating :class:`~typing.NamedTuple` classes (for example, ``Point = " +"NamedTuple(\"Point\", x=int, y=int)``) has been deprecated since Python " +"3.13. Use the class-based syntax or the functional syntax instead." +msgstr "" +"用於建立 :class:`~typing.NamedTuple` 類別的未以文件記錄之關鍵字引數語法 " +"(``Point = NamedTuple(\"Point\", x=int, y=int)``) 已自 Python 3.13 棄用。請改" +"用基於類別的語法或函式語法 (functional syntax)。" + +#: ../../deprecations/pending-removal-in-3.15.rst:88 +msgid "" +"When using the functional syntax of :class:`~typing.TypedDict`\\s, failing " +"to pass a value to the *fields* parameter (``TD = TypedDict(\"TD\")``) or " +"passing ``None`` (``TD = TypedDict(\"TD\", None)``) has been deprecated " +"since Python 3.13. Use ``class TD(TypedDict): pass`` or ``TD = " +"TypedDict(\"TD\", {})`` to create a TypedDict with zero field." +msgstr "" +"當使用 :class:`~typing.TypedDict` 的函式語法時，未傳遞值給 *fields* 參數 " +"(``TD = TypedDict(\"TD\")``) 或傳遞 ``None`` (``TD = TypedDict(\"TD\", " +"None)``) 的做法自 Python 3.13 起已被棄用。請使用 ``class TD(TypedDict): " +"pass`` 或 ``TD = TypedDict(\"TD\", {})`` 來建立具有零個欄位的 TypedDict。" + +#: ../../deprecations/pending-removal-in-3.15.rst:95 +msgid "" +"The :func:`typing.no_type_check_decorator` decorator function has been " +"deprecated since Python 3.13. After eight years in the :mod:`typing` module, " +"it has yet to be supported by any major type checker." +msgstr "" +"自 Python 3.13 起，:func:`typing.no_type_check_decorator` 裝飾器函式已被棄" +"用。在 :mod:`typing` 模組中使用了八年之後，它尚未得到任何主要型別檢查器的支" +"援。" + +#: ../../deprecations/pending-removal-in-3.15.rst:100 +msgid ":mod:`wave`:" +msgstr ":mod:`wave`：" + +#: ../../deprecations/pending-removal-in-3.15.rst:102 +msgid "" +"The :meth:`~wave.Wave_read.getmark`, :meth:`!setmark`, " +"and :meth:`~wave.Wave_read.getmarkers` methods of " +"the :class:`~wave.Wave_read` and :class:`~wave.Wave_write` classes have been " +"deprecated since Python 3.13." +msgstr "" +"已棄用 :class:`~wave.Wave_read` 和 :class:`~wave.Wave_write` 類別" +"的 :meth:`~wave.Wave_read.getmark`、:meth:`!setmark` " +"和 :meth:`~wave.Wave_read.getmarkers` 方法自 Python 3.13 被棄用。" + +#: ../../deprecations/pending-removal-in-3.15.rst:107 +msgid ":mod:`zipimport`:" +msgstr ":mod:`zipimport`：" + +#: ../../deprecations/pending-removal-in-3.15.rst:109 +msgid "" +":meth:`~zipimport.zipimporter.load_module` has been deprecated since Python " +"3.10. Use :meth:`~zipimport.zipimporter.exec_module` instead. (Contributed " +"by Jiahao Li in :gh:`125746`.)" +msgstr "" +":meth:`~zipimport.zipimporter.load_module` 自 Python 3.10 被棄用。請改" +"用 :meth:`~zipimport.zipimporter.exec_module`。（由 Jiahao Li " +"於 :gh:`125746` 貢獻。）" diff --git a/deprecations/pending-removal-in-3.16.po b/deprecations/pending-removal-in-3.16.po index f2590b23cd..ddaf08dd95 100644 --- a/deprecations/pending-removal-in-3.16.po +++ b/deprecations/pending-removal-in-3.16.po @@ -1,248 +1,248 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \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" - -#: ../../deprecations/pending-removal-in-3.16.rst:2 -msgid "Pending removal in Python 3.16" -msgstr "Python 3.16 中待移除的項目" - -#: ../../deprecations/pending-removal-in-3.16.rst:4 -msgid "The import system:" -msgstr "引入系統 (import system)：" - -#: ../../deprecations/pending-removal-in-3.16.rst:6 -msgid "" -"Setting :attr:`~module.__loader__` on a module while failing to " -"set :attr:`__spec__.loader ` is " -"deprecated. In Python 3.16, :attr:`!__loader__` will cease to be set or " -"taken into consideration by the import system or the standard library." -msgstr "" -"在模組上設定 :attr:`~module.__loader__` 而沒有設定 :attr:`__spec__.loader " -"` 的做法將於 Python 3.16 被棄用。在 " -"Python 3.16 中，引入系統或標準函式庫將不再設定或考慮 :attr:`!__loader__`。" - -#: ../../deprecations/pending-removal-in-3.16.rst:11 -msgid ":mod:`array`:" -msgstr ":mod:`array`：" - -#: ../../deprecations/pending-removal-in-3.16.rst:13 -msgid "" -"The ``'u'`` format code (:c:type:`wchar_t`) has been deprecated in " -"documentation since Python 3.3 and at runtime since Python 3.13. Use the " -"``'w'`` format code (:c:type:`Py_UCS4`) for Unicode characters instead." -msgstr "" -"自 Python 3.3 起，``'u'`` 格式碼 (:c:type:`wchar_t`) 在文件中已被棄用，自 " -"Python 3.13 起在 runtime 已被棄用。請使用 ``'w'`` 格式碼 (:c:type:`Py_UCS4`) " -"來取代 Unicode 字元。" - -#: ../../deprecations/pending-removal-in-3.16.rst:19 -msgid ":mod:`asyncio`:" -msgstr ":mod:`asyncio`：" - -#: ../../deprecations/pending-removal-in-3.16.rst:21 -msgid "" -":func:`!asyncio.iscoroutinefunction` is deprecated and will be removed in " -"Python 3.16; use :func:`inspect.iscoroutinefunction` instead. (Contributed " -"by Jiahao Li and Kumar Aditya in :gh:`122875`.)" -msgstr "" -":func:`!asyncio.iscoroutinefunction` 已被棄用並將在 Python 3.16 中移除；請改" -"用 :func:`inspect.iscoroutinefunction`。（由 Jiahao Li 和 Kumar Aditya " -"於 :gh:`122875` 貢獻。）" - -#: ../../deprecations/pending-removal-in-3.16.rst:26 -msgid "" -":mod:`asyncio` policy system is deprecated and will be removed in Python " -"3.16. In particular, the following classes and functions are deprecated:" -msgstr "" -":mod:`asyncio` 策略系統已被棄用並將在 Python 3.16 中移除。特別是以下類別和函" -"式已被棄用：" - -#: ../../deprecations/pending-removal-in-3.16.rst:29 -msgid ":class:`asyncio.AbstractEventLoopPolicy`" -msgstr ":class:`asyncio.AbstractEventLoopPolicy`" - -#: ../../deprecations/pending-removal-in-3.16.rst:30 -msgid ":class:`asyncio.DefaultEventLoopPolicy`" -msgstr ":class:`asyncio.DefaultEventLoopPolicy`" - -#: ../../deprecations/pending-removal-in-3.16.rst:31 -msgid ":class:`asyncio.WindowsSelectorEventLoopPolicy`" -msgstr ":class:`asyncio.WindowsSelectorEventLoopPolicy`" - -#: ../../deprecations/pending-removal-in-3.16.rst:32 -msgid ":class:`asyncio.WindowsProactorEventLoopPolicy`" -msgstr ":class:`asyncio.WindowsProactorEventLoopPolicy`" - -#: ../../deprecations/pending-removal-in-3.16.rst:33 -msgid ":func:`asyncio.get_event_loop_policy`" -msgstr ":func:`asyncio.get_event_loop_policy`" - -#: ../../deprecations/pending-removal-in-3.16.rst:34 -msgid ":func:`asyncio.set_event_loop_policy`" -msgstr ":func:`asyncio.set_event_loop_policy`" - -#: ../../deprecations/pending-removal-in-3.16.rst:36 -msgid "" -"Users should use :func:`asyncio.run` or :class:`asyncio.Runner` with " -"*loop_factory* to use the desired event loop implementation." -msgstr "" -"使用者應該使用 :func:`asyncio.run` 或 :class:`asyncio.Runner` 搭配 " -"*loop_factory* 來使用所需的事件迴圈實作。" - -#: ../../deprecations/pending-removal-in-3.16.rst:39 -msgid "For example, to use :class:`asyncio.SelectorEventLoop` on Windows::" -msgstr "例如在 Windows 上使用 :class:`asyncio.SelectorEventLoop`： ::" - -#: ../../deprecations/pending-removal-in-3.16.rst:41 -msgid "" -"import asyncio\n" -"\n" -"async def main():\n" -" ...\n" -"\n" -"asyncio.run(main(), loop_factory=asyncio.SelectorEventLoop)" -msgstr "" -"import asyncio\n" -"\n" -"async def main():\n" -" ...\n" -"\n" -"asyncio.run(main(), loop_factory=asyncio.SelectorEventLoop)" - -#: ../../deprecations/pending-removal-in-3.16.rst:48 -msgid "(Contributed by Kumar Aditya in :gh:`127949`.)" -msgstr "（由 Kumar Aditya 於 :gh:`127949` 貢獻。）" - -#: ../../deprecations/pending-removal-in-3.16.rst:50 -msgid ":mod:`builtins`:" -msgstr ":mod:`builtins`：" - -#: ../../deprecations/pending-removal-in-3.16.rst:52 -msgid "" -"Bitwise inversion on boolean types, ``~True`` or ``~False`` has been " -"deprecated since Python 3.12, as it produces surprising and unintuitive " -"results (``-2`` and ``-1``). Use ``not x`` instead for the logical negation " -"of a Boolean. In the rare case that you need the bitwise inversion of the " -"underlying integer, convert to ``int`` explicitly (``~int(x)``)." -msgstr "" -"自 Python 3.12 起，布林型別的位元反轉 ``~True`` 或 ``~False`` 已被棄用，因為" -"它會產生不預期且不直觀的結果（``-2`` 和 ``-1``）。使用 ``not x`` 代替布林值的" -"邏輯否定。在極少數情況下，你需要對底層的整數進行位元反轉，請明確轉換為 " -"``~int(x)`` (``~int(x)``)。" - -#: ../../deprecations/pending-removal-in-3.16.rst:59 -msgid ":mod:`functools`:" -msgstr ":mod:`functools`：" - -#: ../../deprecations/pending-removal-in-3.16.rst:61 -msgid "" -"Calling the Python implementation of :func:`functools.reduce` with " -"*function* or *sequence* as keyword arguments has been deprecated since " -"Python 3.14." -msgstr "" -"自 Python 3.14 起，使用 *function* 或 *sequence* 關鍵字引數呼" -"叫 :func:`functools.reduce` 的 Python 實作已被棄用。" - -#: ../../deprecations/pending-removal-in-3.16.rst:64 -msgid ":mod:`logging`:" -msgstr ":mod:`logging`：" - -#: ../../deprecations/pending-removal-in-3.16.rst:66 -msgid "" -"Support for custom logging handlers with the *strm* argument is deprecated " -"and scheduled for removal in Python 3.16. Define handlers with the *stream* " -"argument instead. (Contributed by Mariusz Felisiak in :gh:`115032`.)" -msgstr "" -"對具有 *strm* 引數的自訂日誌記錄處理函式的支援已被棄用，並計劃在 Python 3.16 " -"中移除。請改用 *stream* 引數。（由 Mariusz Felisiak 於 :gh:`115032` 貢獻。）" - -#: ../../deprecations/pending-removal-in-3.16.rst:70 -msgid ":mod:`mimetypes`:" -msgstr ":mod:`mimetypes`：" - -#: ../../deprecations/pending-removal-in-3.16.rst:72 -msgid "" -"Valid extensions start with a '.' or are empty " -"for :meth:`mimetypes.MimeTypes.add_type`. Undotted extensions are deprecated " -"and will raise a :exc:`ValueError` in Python 3.16. (Contributed by Hugo van " -"Kemenade in :gh:`75223`.)" -msgstr "" -"有效的副檔名以 '.' 開頭或對 :meth:`mimetypes.MimeTypes.add_type` 為空字串。未" -"加點的副檔名已被棄用，並將在 Python 3.16 中引發 :exc:`ValueError`。（由 Hugo " -"van Kemenade 於 :gh:`75223` 貢獻。）" - -#: ../../deprecations/pending-removal-in-3.16.rst:78 -msgid ":mod:`shutil`:" -msgstr ":mod:`shutil`：" - -#: ../../deprecations/pending-removal-in-3.16.rst:80 -msgid "" -"The :class:`!ExecError` exception has been deprecated since Python 3.14. It " -"has not been used by any function in :mod:`!shutil` since Python 3.4, and is " -"now an alias of :exc:`RuntimeError`." -msgstr "" -"自 Python 3.14 起，:class:`!ExecError` 例外已被棄用。自 Python 3.4 以來，它尚" -"未被 :mod:`!shutil` 中的任何函式使用，現在是 :exc:`RuntimeError` 的別名。" - -#: ../../deprecations/pending-removal-in-3.16.rst:85 -msgid ":mod:`symtable`:" -msgstr ":mod:`symtable`：" - -#: ../../deprecations/pending-removal-in-3.16.rst:87 -msgid "" -"The :meth:`Class.get_methods ` method has been " -"deprecated since Python 3.14." -msgstr "" -"自 Python 3.14 起，:meth:`Class.get_methods ` 方" -"法已被棄用。" - -#: ../../deprecations/pending-removal-in-3.16.rst:90 -msgid ":mod:`sys`:" -msgstr ":mod:`sys`：" - -#: ../../deprecations/pending-removal-in-3.16.rst:92 -msgid "" -"The :func:`~sys._enablelegacywindowsfsencoding` function has been deprecated " -"since Python 3.13. Use the :envvar:`PYTHONLEGACYWINDOWSFSENCODING` " -"environment variable instead." -msgstr "" -"自 Python 3.13 起，:func:`~sys._enablelegacywindowsfsencoding` 函式已被棄用。" -"請改用 :envvar:`PYTHONLEGACYWINDOWSFSENCODING` 環境變數。" - -#: ../../deprecations/pending-removal-in-3.16.rst:96 -msgid ":mod:`sysconfig`:" -msgstr ":mod:`sysconfig`：" - -#: ../../deprecations/pending-removal-in-3.16.rst:98 -msgid "" -"The :func:`!sysconfig.expand_makefile_vars` function has been deprecated " -"since Python 3.14. Use the ``vars`` argument of :func:`sysconfig.get_paths` " -"instead." -msgstr "" -"自 Python 3.14 起，:func:`!sysconfig.expand_makefile_vars` 函式已被棄用。請改" -"用 :func:`sysconfig.get_paths` 的 ``vars`` 引數。" - -#: ../../deprecations/pending-removal-in-3.16.rst:102 -msgid ":mod:`tarfile`:" -msgstr ":mod:`tarfile`：" - -#: ../../deprecations/pending-removal-in-3.16.rst:104 -msgid "" -"The undocumented and unused :attr:`!TarFile.tarfile` attribute has been " -"deprecated since Python 3.13." -msgstr "" -"自 Python 3.13 起，未以文件記錄和未被使用的 :attr:`!TarFile.tarfile` 屬性已被" -"棄用。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \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" + +#: ../../deprecations/pending-removal-in-3.16.rst:2 +msgid "Pending removal in Python 3.16" +msgstr "Python 3.16 中待移除的項目" + +#: ../../deprecations/pending-removal-in-3.16.rst:4 +msgid "The import system:" +msgstr "引入系統 (import system)：" + +#: ../../deprecations/pending-removal-in-3.16.rst:6 +msgid "" +"Setting :attr:`~module.__loader__` on a module while failing to " +"set :attr:`__spec__.loader ` is " +"deprecated. In Python 3.16, :attr:`!__loader__` will cease to be set or " +"taken into consideration by the import system or the standard library." +msgstr "" +"在模組上設定 :attr:`~module.__loader__` 而沒有設定 :attr:`__spec__.loader " +"` 的做法將於 Python 3.16 被棄用。在 " +"Python 3.16 中，引入系統或標準函式庫將不再設定或考慮 :attr:`!__loader__`。" + +#: ../../deprecations/pending-removal-in-3.16.rst:11 +msgid ":mod:`array`:" +msgstr ":mod:`array`：" + +#: ../../deprecations/pending-removal-in-3.16.rst:13 +msgid "" +"The ``'u'`` format code (:c:type:`wchar_t`) has been deprecated in " +"documentation since Python 3.3 and at runtime since Python 3.13. Use the " +"``'w'`` format code (:c:type:`Py_UCS4`) for Unicode characters instead." +msgstr "" +"自 Python 3.3 起，``'u'`` 格式碼 (:c:type:`wchar_t`) 在文件中已被棄用，自 " +"Python 3.13 起在 runtime 已被棄用。請使用 ``'w'`` 格式碼 (:c:type:`Py_UCS4`) " +"來取代 Unicode 字元。" + +#: ../../deprecations/pending-removal-in-3.16.rst:19 +msgid ":mod:`asyncio`:" +msgstr ":mod:`asyncio`：" + +#: ../../deprecations/pending-removal-in-3.16.rst:21 +msgid "" +":func:`!asyncio.iscoroutinefunction` is deprecated and will be removed in " +"Python 3.16; use :func:`inspect.iscoroutinefunction` instead. (Contributed " +"by Jiahao Li and Kumar Aditya in :gh:`122875`.)" +msgstr "" +":func:`!asyncio.iscoroutinefunction` 已被棄用並將在 Python 3.16 中移除；請改" +"用 :func:`inspect.iscoroutinefunction`。（由 Jiahao Li 和 Kumar Aditya " +"於 :gh:`122875` 貢獻。）" + +#: ../../deprecations/pending-removal-in-3.16.rst:26 +msgid "" +":mod:`asyncio` policy system is deprecated and will be removed in Python " +"3.16. In particular, the following classes and functions are deprecated:" +msgstr "" +":mod:`asyncio` 策略系統已被棄用並將在 Python 3.16 中移除。特別是以下類別和函" +"式已被棄用：" + +#: ../../deprecations/pending-removal-in-3.16.rst:29 +msgid ":class:`asyncio.AbstractEventLoopPolicy`" +msgstr ":class:`asyncio.AbstractEventLoopPolicy`" + +#: ../../deprecations/pending-removal-in-3.16.rst:30 +msgid ":class:`asyncio.DefaultEventLoopPolicy`" +msgstr ":class:`asyncio.DefaultEventLoopPolicy`" + +#: ../../deprecations/pending-removal-in-3.16.rst:31 +msgid ":class:`asyncio.WindowsSelectorEventLoopPolicy`" +msgstr ":class:`asyncio.WindowsSelectorEventLoopPolicy`" + +#: ../../deprecations/pending-removal-in-3.16.rst:32 +msgid ":class:`asyncio.WindowsProactorEventLoopPolicy`" +msgstr ":class:`asyncio.WindowsProactorEventLoopPolicy`" + +#: ../../deprecations/pending-removal-in-3.16.rst:33 +msgid ":func:`asyncio.get_event_loop_policy`" +msgstr ":func:`asyncio.get_event_loop_policy`" + +#: ../../deprecations/pending-removal-in-3.16.rst:34 +msgid ":func:`asyncio.set_event_loop_policy`" +msgstr ":func:`asyncio.set_event_loop_policy`" + +#: ../../deprecations/pending-removal-in-3.16.rst:36 +msgid "" +"Users should use :func:`asyncio.run` or :class:`asyncio.Runner` with " +"*loop_factory* to use the desired event loop implementation." +msgstr "" +"使用者應該使用 :func:`asyncio.run` 或 :class:`asyncio.Runner` 搭配 " +"*loop_factory* 來使用所需的事件迴圈實作。" + +#: ../../deprecations/pending-removal-in-3.16.rst:39 +msgid "For example, to use :class:`asyncio.SelectorEventLoop` on Windows::" +msgstr "例如在 Windows 上使用 :class:`asyncio.SelectorEventLoop`： ::" + +#: ../../deprecations/pending-removal-in-3.16.rst:41 +msgid "" +"import asyncio\n" +"\n" +"async def main():\n" +" ...\n" +"\n" +"asyncio.run(main(), loop_factory=asyncio.SelectorEventLoop)" +msgstr "" +"import asyncio\n" +"\n" +"async def main():\n" +" ...\n" +"\n" +"asyncio.run(main(), loop_factory=asyncio.SelectorEventLoop)" + +#: ../../deprecations/pending-removal-in-3.16.rst:48 +msgid "(Contributed by Kumar Aditya in :gh:`127949`.)" +msgstr "（由 Kumar Aditya 於 :gh:`127949` 貢獻。）" + +#: ../../deprecations/pending-removal-in-3.16.rst:50 +msgid ":mod:`builtins`:" +msgstr ":mod:`builtins`：" + +#: ../../deprecations/pending-removal-in-3.16.rst:52 +msgid "" +"Bitwise inversion on boolean types, ``~True`` or ``~False`` has been " +"deprecated since Python 3.12, as it produces surprising and unintuitive " +"results (``-2`` and ``-1``). Use ``not x`` instead for the logical negation " +"of a Boolean. In the rare case that you need the bitwise inversion of the " +"underlying integer, convert to ``int`` explicitly (``~int(x)``)." +msgstr "" +"自 Python 3.12 起，布林型別的位元反轉 ``~True`` 或 ``~False`` 已被棄用，因為" +"它會產生不預期且不直觀的結果（``-2`` 和 ``-1``）。使用 ``not x`` 代替布林值的" +"邏輯否定。在極少數情況下，你需要對底層的整數進行位元反轉，請明確轉換為 " +"``~int(x)`` (``~int(x)``)。" + +#: ../../deprecations/pending-removal-in-3.16.rst:59 +msgid ":mod:`functools`:" +msgstr ":mod:`functools`：" + +#: ../../deprecations/pending-removal-in-3.16.rst:61 +msgid "" +"Calling the Python implementation of :func:`functools.reduce` with " +"*function* or *sequence* as keyword arguments has been deprecated since " +"Python 3.14." +msgstr "" +"自 Python 3.14 起，使用 *function* 或 *sequence* 關鍵字引數呼" +"叫 :func:`functools.reduce` 的 Python 實作已被棄用。" + +#: ../../deprecations/pending-removal-in-3.16.rst:64 +msgid ":mod:`logging`:" +msgstr ":mod:`logging`：" + +#: ../../deprecations/pending-removal-in-3.16.rst:66 +msgid "" +"Support for custom logging handlers with the *strm* argument is deprecated " +"and scheduled for removal in Python 3.16. Define handlers with the *stream* " +"argument instead. (Contributed by Mariusz Felisiak in :gh:`115032`.)" +msgstr "" +"對具有 *strm* 引數的自訂日誌記錄處理函式的支援已被棄用，並計劃在 Python 3.16 " +"中移除。請改用 *stream* 引數。（由 Mariusz Felisiak 於 :gh:`115032` 貢獻。）" + +#: ../../deprecations/pending-removal-in-3.16.rst:70 +msgid ":mod:`mimetypes`:" +msgstr ":mod:`mimetypes`：" + +#: ../../deprecations/pending-removal-in-3.16.rst:72 +msgid "" +"Valid extensions start with a '.' or are empty " +"for :meth:`mimetypes.MimeTypes.add_type`. Undotted extensions are deprecated " +"and will raise a :exc:`ValueError` in Python 3.16. (Contributed by Hugo van " +"Kemenade in :gh:`75223`.)" +msgstr "" +"有效的副檔名以 '.' 開頭或對 :meth:`mimetypes.MimeTypes.add_type` 為空字串。未" +"加點的副檔名已被棄用，並將在 Python 3.16 中引發 :exc:`ValueError`。（由 Hugo " +"van Kemenade 於 :gh:`75223` 貢獻。）" + +#: ../../deprecations/pending-removal-in-3.16.rst:78 +msgid ":mod:`shutil`:" +msgstr ":mod:`shutil`：" + +#: ../../deprecations/pending-removal-in-3.16.rst:80 +msgid "" +"The :class:`!ExecError` exception has been deprecated since Python 3.14. It " +"has not been used by any function in :mod:`!shutil` since Python 3.4, and is " +"now an alias of :exc:`RuntimeError`." +msgstr "" +"自 Python 3.14 起，:class:`!ExecError` 例外已被棄用。自 Python 3.4 以來，它尚" +"未被 :mod:`!shutil` 中的任何函式使用，現在是 :exc:`RuntimeError` 的別名。" + +#: ../../deprecations/pending-removal-in-3.16.rst:85 +msgid ":mod:`symtable`:" +msgstr ":mod:`symtable`：" + +#: ../../deprecations/pending-removal-in-3.16.rst:87 +msgid "" +"The :meth:`Class.get_methods ` method has been " +"deprecated since Python 3.14." +msgstr "" +"自 Python 3.14 起，:meth:`Class.get_methods ` 方" +"法已被棄用。" + +#: ../../deprecations/pending-removal-in-3.16.rst:90 +msgid ":mod:`sys`:" +msgstr ":mod:`sys`：" + +#: ../../deprecations/pending-removal-in-3.16.rst:92 +msgid "" +"The :func:`~sys._enablelegacywindowsfsencoding` function has been deprecated " +"since Python 3.13. Use the :envvar:`PYTHONLEGACYWINDOWSFSENCODING` " +"environment variable instead." +msgstr "" +"自 Python 3.13 起，:func:`~sys._enablelegacywindowsfsencoding` 函式已被棄用。" +"請改用 :envvar:`PYTHONLEGACYWINDOWSFSENCODING` 環境變數。" + +#: ../../deprecations/pending-removal-in-3.16.rst:96 +msgid ":mod:`sysconfig`:" +msgstr ":mod:`sysconfig`：" + +#: ../../deprecations/pending-removal-in-3.16.rst:98 +msgid "" +"The :func:`!sysconfig.expand_makefile_vars` function has been deprecated " +"since Python 3.14. Use the ``vars`` argument of :func:`sysconfig.get_paths` " +"instead." +msgstr "" +"自 Python 3.14 起，:func:`!sysconfig.expand_makefile_vars` 函式已被棄用。請改" +"用 :func:`sysconfig.get_paths` 的 ``vars`` 引數。" + +#: ../../deprecations/pending-removal-in-3.16.rst:102 +msgid ":mod:`tarfile`:" +msgstr ":mod:`tarfile`：" + +#: ../../deprecations/pending-removal-in-3.16.rst:104 +msgid "" +"The undocumented and unused :attr:`!TarFile.tarfile` attribute has been " +"deprecated since Python 3.13." +msgstr "" +"自 Python 3.13 起，未以文件記錄和未被使用的 :attr:`!TarFile.tarfile` 屬性已被" +"棄用。" diff --git a/deprecations/pending-removal-in-3.17.po b/deprecations/pending-removal-in-3.17.po index 3357e9e6ed..f489a736ad 100644 --- a/deprecations/pending-removal-in-3.17.po +++ b/deprecations/pending-removal-in-3.17.po @@ -1,93 +1,93 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# FIRST AUTHOR , YEAR. -# -#, fuzzy -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-19 00:15+0000\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language-Team: LANGUAGE \n" -"Language: zh_TW\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=UTF-8\n" -"Content-Transfer-Encoding: 8bit\n" - -#: ../../deprecations/pending-removal-in-3.17.rst:2 -msgid "Pending removal in Python 3.17" -msgstr "Python 3.17 中待移除的項目" - -#: ../../deprecations/pending-removal-in-3.17.rst:4 -msgid ":mod:`collections.abc`:" -msgstr ":mod:`collections.abc`：" - -#: ../../deprecations/pending-removal-in-3.17.rst:6 -msgid "" -":class:`collections.abc.ByteString` is scheduled for removal in Python 3.17." -msgstr ":class:`collections.abc.ByteString` 預計在 Python 3.17 中移除。" - -#: ../../deprecations/pending-removal-in-3.17.rst:8 -#: ../../deprecations/pending-removal-in-3.17.rst:36 -msgid "" -"Use ``isinstance(obj, collections.abc.Buffer)`` to test if ``obj`` " -"implements the :ref:`buffer protocol ` at runtime. For use in " -"type annotations, either use :class:`~collections.abc.Buffer` or a union " -"that explicitly specifies the types your code supports (e.g., ``bytes | " -"bytearray | memoryview``)." -msgstr "" -"使用 ``isinstance(obj, collections.abc.Buffer)`` 來測試 ``obj`` 是否在 runtime " -"實作了\\ :ref:`緩衝區協定 `。在型別註解的使用中，請用 :class:`~" -"collections.abc.Buffer` 或明確指定你的程式碼所支援型別的聯集（例如 " -"``bytes | bytearray | memoryview``）。" - -#: ../../deprecations/pending-removal-in-3.17.rst:14 -#: ../../deprecations/pending-removal-in-3.17.rst:42 -msgid "" -":class:`!ByteString` was originally intended to be an abstract class that " -"would serve as a supertype of both :class:`bytes` and :class:`bytearray`. " -"However, since the ABC never had any methods, knowing that an object was an " -"instance of :class:`!ByteString` never actually told you anything useful " -"about the object. Other common buffer types such as :class:`memoryview` were " -"also never understood as subtypes of :class:`!ByteString` (either at runtime " -"or by static type checkers)." -msgstr "" -":class:`!ByteString` 最初被設計為一個抽象類別，以作為 :class:`bytes` 和 :class:`bytearray` " -"的超型別 (supertype)。然而由於 ABC 從未擁有任何方法，知道一個物件是 :class:`!ByteString` 的" -"實例從未真正告訴你任何關於該物件的有用資訊。其他常見的緩衝區型別如 :class:`memoryview` " -"也從未被理解為 :class:`!ByteString` 的子型別（無論是在 runtime 還是由靜態型別檢查器）。" - -#: ../../deprecations/pending-removal-in-3.17.rst:22 -#: ../../deprecations/pending-removal-in-3.17.rst:50 -msgid "" -"See :pep:`PEP 688 <688#current-options>` for more details. (Contributed by " -"Shantanu Jain in :gh:`91896`.)" -msgstr "" -"更多細節請見 :pep:`PEP 688 <688#current-options>`。（由 Shantanu Jain 於 :gh:`91896` 貢獻。）" - -#: ../../deprecations/pending-removal-in-3.17.rst:26 -msgid ":mod:`typing`:" -msgstr ":mod:`typing`：" - -#: ../../deprecations/pending-removal-in-3.17.rst:28 -msgid "" -"Before Python 3.14, old-style unions were implemented using the private " -"class ``typing._UnionGenericAlias``. This class is no longer needed for the " -"implementation, but it has been retained for backward compatibility, with " -"removal scheduled for Python 3.17. Users should use documented introspection " -"helpers like :func:`typing.get_origin` and :func:`typing.get_args` instead " -"of relying on private implementation details." -msgstr "" -"在 Python 3.14 之前，舊式聯集是使用私有類別 ``typing._UnionGenericAlias`` 實" -"作的。這個類別不再被需要，但為了向後相容性而保留，並計劃將在 Python 3.17 中移" -"除。使用者應該改用文件中記錄的內省輔助函式，例如 :func:`typing.get_origin` " -"和 :func:`typing.get_args`，或者依賴私有實作細節。" - -#: ../../deprecations/pending-removal-in-3.17.rst:33 -msgid "" -":class:`typing.ByteString`, deprecated since Python 3.9, is scheduled for " -"removal in Python 3.17." -msgstr "" -":class:`typing.ByteString` 自 Python 3.9 起已被棄用，預計在 Python 3.17 中移除。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-19 00:15+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"Language: zh_TW\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../deprecations/pending-removal-in-3.17.rst:2 +msgid "Pending removal in Python 3.17" +msgstr "Python 3.17 中待移除的項目" + +#: ../../deprecations/pending-removal-in-3.17.rst:4 +msgid ":mod:`collections.abc`:" +msgstr ":mod:`collections.abc`：" + +#: ../../deprecations/pending-removal-in-3.17.rst:6 +msgid "" +":class:`collections.abc.ByteString` is scheduled for removal in Python 3.17." +msgstr ":class:`collections.abc.ByteString` 預計在 Python 3.17 中移除。" + +#: ../../deprecations/pending-removal-in-3.17.rst:8 +#: ../../deprecations/pending-removal-in-3.17.rst:36 +msgid "" +"Use ``isinstance(obj, collections.abc.Buffer)`` to test if ``obj`` " +"implements the :ref:`buffer protocol ` at runtime. For use in " +"type annotations, either use :class:`~collections.abc.Buffer` or a union " +"that explicitly specifies the types your code supports (e.g., ``bytes | " +"bytearray | memoryview``)." +msgstr "" +"使用 ``isinstance(obj, collections.abc.Buffer)`` 來測試 ``obj`` 是否在 runtime " +"實作了\\ :ref:`緩衝區協定 `。在型別註解的使用中，請用 :class:`~" +"collections.abc.Buffer` 或明確指定你的程式碼所支援型別的聯集（例如 " +"``bytes | bytearray | memoryview``）。" + +#: ../../deprecations/pending-removal-in-3.17.rst:14 +#: ../../deprecations/pending-removal-in-3.17.rst:42 +msgid "" +":class:`!ByteString` was originally intended to be an abstract class that " +"would serve as a supertype of both :class:`bytes` and :class:`bytearray`. " +"However, since the ABC never had any methods, knowing that an object was an " +"instance of :class:`!ByteString` never actually told you anything useful " +"about the object. Other common buffer types such as :class:`memoryview` were " +"also never understood as subtypes of :class:`!ByteString` (either at runtime " +"or by static type checkers)." +msgstr "" +":class:`!ByteString` 最初被設計為一個抽象類別，以作為 :class:`bytes` 和 :class:`bytearray` " +"的超型別 (supertype)。然而由於 ABC 從未擁有任何方法，知道一個物件是 :class:`!ByteString` 的" +"實例從未真正告訴你任何關於該物件的有用資訊。其他常見的緩衝區型別如 :class:`memoryview` " +"也從未被理解為 :class:`!ByteString` 的子型別（無論是在 runtime 還是由靜態型別檢查器）。" + +#: ../../deprecations/pending-removal-in-3.17.rst:22 +#: ../../deprecations/pending-removal-in-3.17.rst:50 +msgid "" +"See :pep:`PEP 688 <688#current-options>` for more details. (Contributed by " +"Shantanu Jain in :gh:`91896`.)" +msgstr "" +"更多細節請見 :pep:`PEP 688 <688#current-options>`。（由 Shantanu Jain 於 :gh:`91896` 貢獻。）" + +#: ../../deprecations/pending-removal-in-3.17.rst:26 +msgid ":mod:`typing`:" +msgstr ":mod:`typing`：" + +#: ../../deprecations/pending-removal-in-3.17.rst:28 +msgid "" +"Before Python 3.14, old-style unions were implemented using the private " +"class ``typing._UnionGenericAlias``. This class is no longer needed for the " +"implementation, but it has been retained for backward compatibility, with " +"removal scheduled for Python 3.17. Users should use documented introspection " +"helpers like :func:`typing.get_origin` and :func:`typing.get_args` instead " +"of relying on private implementation details." +msgstr "" +"在 Python 3.14 之前，舊式聯集是使用私有類別 ``typing._UnionGenericAlias`` 實" +"作的。這個類別不再被需要，但為了向後相容性而保留，並計劃將在 Python 3.17 中移" +"除。使用者應該改用文件中記錄的內省輔助函式，例如 :func:`typing.get_origin` " +"和 :func:`typing.get_args`，或者依賴私有實作細節。" + +#: ../../deprecations/pending-removal-in-3.17.rst:33 +msgid "" +":class:`typing.ByteString`, deprecated since Python 3.9, is scheduled for " +"removal in Python 3.17." +msgstr "" +":class:`typing.ByteString` 自 Python 3.9 起已被棄用，預計在 Python 3.17 中移除。" diff --git a/deprecations/pending-removal-in-3.18.po b/deprecations/pending-removal-in-3.18.po index 7b72422013..0abfa72fbb 100644 --- a/deprecations/pending-removal-in-3.18.po +++ b/deprecations/pending-removal-in-3.18.po @@ -1,37 +1,37 @@ -# SOME DESCRIPTIVE TITLE. -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# FIRST AUTHOR , YEAR. -# -#, fuzzy -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2026-01-07 00:14+0000\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language-Team: LANGUAGE \n" -"Language: zh_TW\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=UTF-8\n" -"Content-Transfer-Encoding: 8bit\n" - -#: ../../deprecations/pending-removal-in-3.18.rst:2 -msgid "Pending removal in Python 3.18" -msgstr "Python 3.18 中待移除的項目" - -#: ../../deprecations/pending-removal-in-3.18.rst:4 -msgid ":mod:`decimal`:" -msgstr ":mod:`decimal`：" - -#: ../../deprecations/pending-removal-in-3.18.rst:6 -msgid "" -"The non-standard and undocumented :class:`~decimal.Decimal` format specifier " -"``'N'``, which is only supported in the :mod:`!decimal` module's C " -"implementation, has been deprecated since Python 3.13. (Contributed by " -"Serhiy Storchaka in :gh:`89902`.)" -msgstr "" -"非標準且無文件記載的 :class:`~decimal.Decimal` 格式說明符號 ``'N'``，僅在 :mod:" -"`!decimal` 模組的 C 實作中被支援，自 Python 3.13 起已被棄用。（由 Serhiy " -"Storchaka 於 :gh:`89902` 中貢獻。）" +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-01-07 00:14+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"Language: zh_TW\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../deprecations/pending-removal-in-3.18.rst:2 +msgid "Pending removal in Python 3.18" +msgstr "Python 3.18 中待移除的項目" + +#: ../../deprecations/pending-removal-in-3.18.rst:4 +msgid ":mod:`decimal`:" +msgstr ":mod:`decimal`：" + +#: ../../deprecations/pending-removal-in-3.18.rst:6 +msgid "" +"The non-standard and undocumented :class:`~decimal.Decimal` format specifier " +"``'N'``, which is only supported in the :mod:`!decimal` module's C " +"implementation, has been deprecated since Python 3.13. (Contributed by " +"Serhiy Storchaka in :gh:`89902`.)" +msgstr "" +"非標準且無文件記載的 :class:`~decimal.Decimal` 格式說明符號 ``'N'``，僅在 :mod:" +"`!decimal` 模組的 C 實作中被支援，自 Python 3.13 起已被棄用。（由 Serhiy " +"Storchaka 於 :gh:`89902` 中貢獻。）" diff --git a/deprecations/pending-removal-in-3.19.po b/deprecations/pending-removal-in-3.19.po index 79fc1b949e..e7dfc93aec 100644 --- a/deprecations/pending-removal-in-3.19.po +++ b/deprecations/pending-removal-in-3.19.po @@ -1,34 +1,34 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# FIRST AUTHOR , YEAR. -# -#, fuzzy -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language-Team: LANGUAGE \n" -"Language: zh_TW\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=UTF-8\n" -"Content-Transfer-Encoding: 8bit\n" - -#: ../../deprecations/pending-removal-in-3.19.rst:2 -msgid "Pending removal in Python 3.19" -msgstr "Python 3.19 中待移除的項目" - -#: ../../deprecations/pending-removal-in-3.19.rst:4 -msgid ":mod:`ctypes`:" -msgstr ":mod:`ctypes`：" - -#: ../../deprecations/pending-removal-in-3.19.rst:6 -msgid "" -"Implicitly switching to the MSVC-compatible struct layout by " -"setting :attr:`~ctypes.Structure._pack_` but " -"not :attr:`~ctypes.Structure._layout_` on non-Windows platforms." -msgstr "" -"在非 Windows 平台上，透過設定 :attr:`~ctypes.Structure._pack_` 而沒有設" -"定 :attr:`~ctypes.Structure._layout_` 來隱式地切換到與 MSVC 相容的結構佈局。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"Language: zh_TW\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../deprecations/pending-removal-in-3.19.rst:2 +msgid "Pending removal in Python 3.19" +msgstr "Python 3.19 中待移除的項目" + +#: ../../deprecations/pending-removal-in-3.19.rst:4 +msgid ":mod:`ctypes`:" +msgstr ":mod:`ctypes`：" + +#: ../../deprecations/pending-removal-in-3.19.rst:6 +msgid "" +"Implicitly switching to the MSVC-compatible struct layout by " +"setting :attr:`~ctypes.Structure._pack_` but " +"not :attr:`~ctypes.Structure._layout_` on non-Windows platforms." +msgstr "" +"在非 Windows 平台上，透過設定 :attr:`~ctypes.Structure._pack_` 而沒有設" +"定 :attr:`~ctypes.Structure._layout_` 來隱式地切換到與 MSVC 相容的結構佈局。" diff --git a/deprecations/pending-removal-in-future.po b/deprecations/pending-removal-in-future.po index 6b666a7e95..b642fc42f1 100644 --- a/deprecations/pending-removal-in-future.po +++ b/deprecations/pending-removal-in-future.po @@ -1,441 +1,441 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# FIRST AUTHOR , YEAR -# -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-10-06 00:15+0000\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \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" - -#: ../../deprecations/pending-removal-in-future.rst:2 -msgid "Pending removal in future versions" -msgstr "未來版本中的待移除項目" - -#: ../../deprecations/pending-removal-in-future.rst:4 -msgid "" -"The following APIs will be removed in the future, although there is " -"currently no date scheduled for their removal." -msgstr "以下 API 將在未來被移除，雖然目前尚未安排移除日期。" - -#: ../../deprecations/pending-removal-in-future.rst:7 -msgid ":mod:`argparse`:" -msgstr ":mod:`argparse`：" - -#: ../../deprecations/pending-removal-in-future.rst:9 -msgid "" -"Nesting argument groups and nesting mutually exclusive groups are deprecated." -msgstr "巢狀引數群組和巢狀互斥群組已被棄用。" - -#: ../../deprecations/pending-removal-in-future.rst:11 -msgid "" -"Passing the undocumented keyword argument *prefix_chars* to :meth:`~argparse." -"ArgumentParser.add_argument_group` is now deprecated." -msgstr "" -"將未以文件記錄的關鍵字引數 *prefix_chars* 傳遞給 :meth:`~argparse." -"ArgumentParser.add_argument_group` 的做法現在已被棄用。" - -#: ../../deprecations/pending-removal-in-future.rst:14 -msgid "The :class:`argparse.FileType` type converter is deprecated." -msgstr ":class:`argparse.FileType` 型別轉換器已被棄用。" - -#: ../../deprecations/pending-removal-in-future.rst:16 -msgid ":mod:`builtins`:" -msgstr ":mod:`builtins`：" - -#: ../../deprecations/pending-removal-in-future.rst:18 -msgid "" -"Generators: ``throw(type, exc, tb)`` and ``athrow(type, exc, tb)`` signature " -"is deprecated: use ``throw(exc)`` and ``athrow(exc)`` instead, the single " -"argument signature." -msgstr "" -"產生器：``throw(type, exc, tb)`` 和 ``athrow(type, exc, tb)`` 簽名已被棄用：" -"請改用 ``throw(exc)`` 和 ``athrow(exc)``，為單引數簽名。" - -#: ../../deprecations/pending-removal-in-future.rst:21 -msgid "" -"Currently Python accepts numeric literals immediately followed by keywords, " -"for example ``0in x``, ``1or x``, ``0if 1else 2``. It allows confusing and " -"ambiguous expressions like ``[0x1for x in y]`` (which can be interpreted as " -"``[0x1 for x in y]`` or ``[0x1f or x in y]``). A syntax warning is raised " -"if the numeric literal is immediately followed by one of keywords :keyword:" -"`and`, :keyword:`else`, :keyword:`for`, :keyword:`if`, :keyword:`in`, :" -"keyword:`is` and :keyword:`or`. In a future release it will be changed to a " -"syntax error. (:gh:`87999`)" -msgstr "" -"目前 Python 接受數值字面值後面立即接關鍵字，例如 ``0in x``、``1or x``、``0if " -"1else 2``。它讓運算式模糊且容易混淆，如 ``[0x1for x in y]``\\ （可以解釋為 " -"``[0x1 for x in y]`` 或 ``[0x1f or x in y]``）。如果數值字面值後立即接 :" -"keyword:`and`、:keyword:`else`、:keyword:`for`、:keyword:`if`、:keyword:" -"`in`、:keyword:`is` 和 :keyword:`or` 之一的關鍵字，則會引發語法警告。在未來版" -"本中，它將被更改為語法錯誤。(:gh:`87999`)" - -#: ../../deprecations/pending-removal-in-future.rst:29 -msgid "" -"Support for ``__index__()`` and ``__int__()`` method returning non-int type: " -"these methods will be required to return an instance of a strict subclass " -"of :class:`int`." -msgstr "" -"``__index__()`` 和 ``__int__()`` 方法回傳非 int 型別的支援：這些方法將需要回" -"傳 :class:`int` 的嚴格子類別實例。" - -#: ../../deprecations/pending-removal-in-future.rst:32 -msgid "" -"Support for ``__float__()`` method returning a strict subclass of :class:" -"`float`: these methods will be required to return an instance of :class:" -"`float`." -msgstr "" -"回傳 :class:`float` 嚴格子類別 ``__float__()`` 方法的支援：這些方法將需要回" -"傳 :class:`float` 的實例。" - -#: ../../deprecations/pending-removal-in-future.rst:35 -msgid "" -"Support for ``__complex__()`` method returning a strict subclass of :class:" -"`complex`: these methods will be required to return an instance of :class:" -"`complex`." -msgstr "" -"回傳 :class:`complex` 嚴格子類別 ``__complex__()`` 方法的支援：這些方法將需要" -"回傳 :class:`complex` 的實例。" - -#: ../../deprecations/pending-removal-in-future.rst:38 -msgid "Delegation of ``int()`` to ``__trunc__()`` method." -msgstr "將 ``int()`` 委派給 ``__trunc__()`` 方法。" - -#: ../../deprecations/pending-removal-in-future.rst:39 -msgid "" -"Passing a complex number as the *real* or *imag* argument in the :func:" -"`complex` constructor is now deprecated; it should only be passed as a " -"single positional argument. (Contributed by Serhiy Storchaka in :gh:" -"`109218`.)" -msgstr "" -"在 :func:`complex` 建構子中將複數作為 *real* 或 *imag* 引數傳遞現在已被棄用；" -"它應該只作為單個位置引數傳遞。 (由 Serhiy Storchaka 於 :gh:`109218` 貢獻。)" - -#: ../../deprecations/pending-removal-in-future.rst:44 -msgid "" -":mod:`calendar`: ``calendar.January`` and ``calendar.February`` constants " -"are deprecated and replaced by :data:`calendar.JANUARY` and :data:`calendar." -"FEBRUARY`. (Contributed by Prince Roshan in :gh:`103636`.)" -msgstr "" -":mod:`calendar`：``calendar.January`` 和 ``calendar.February`` 常數已被棄用並" -"被 :data:`calendar.JANUARY` 和 :data:`calendar.FEBRUARY` 取代。 (由 Prince " -"Roshan 於 :gh:`103636` 貢獻。)" - -#: ../../deprecations/pending-removal-in-future.rst:49 -msgid "" -":mod:`codecs`: use :func:`open` instead of :func:`codecs.open`. (:gh:" -"`133038`)" -msgstr "" -":mod:`codecs`：請改用 :func:`open` 而非 :func:`codecs.open`。(:gh:`133038`)" - -#: ../../deprecations/pending-removal-in-future.rst:51 -msgid "" -":attr:`codeobject.co_lnotab`: use the :meth:`codeobject.co_lines` method " -"instead." -msgstr "" -":attr:`codeobject.co_lnotab`：請改用 :meth:`codeobject.co_lines` 方法。" - -#: ../../deprecations/pending-removal-in-future.rst:54 -msgid ":mod:`datetime`:" -msgstr ":mod:`datetime`：" - -#: ../../deprecations/pending-removal-in-future.rst:56 -msgid "" -":meth:`~datetime.datetime.utcnow`: use ``datetime.datetime.now(tz=datetime." -"UTC)``." -msgstr "" -":meth:`~datetime.datetime.utcnow`：請改用 ``datetime.datetime." -"now(tz=datetime.UTC)``。" - -#: ../../deprecations/pending-removal-in-future.rst:58 -msgid "" -":meth:`~datetime.datetime.utcfromtimestamp`: use ``datetime.datetime." -"fromtimestamp(timestamp, tz=datetime.UTC)``." -msgstr "" -":meth:`~datetime.datetime.utcfromtimestamp`：請改用 ``datetime.datetime." -"fromtimestamp(timestamp, tz=datetime.UTC)``。" - -#: ../../deprecations/pending-removal-in-future.rst:61 -msgid ":mod:`gettext`: Plural value must be an integer." -msgstr ":mod:`gettext`：複數值必須是整數。" - -#: ../../deprecations/pending-removal-in-future.rst:63 -msgid ":mod:`importlib`:" -msgstr ":mod:`importlib`：" - -#: ../../deprecations/pending-removal-in-future.rst:65 -msgid "" -":func:`~importlib.util.cache_from_source` *debug_override* parameter is " -"deprecated: use the *optimization* parameter instead." -msgstr "" -":func:`~importlib.util.cache_from_source` *debug_override* 參數已被棄用：請改" -"用 *optimization* 參數。" - -#: ../../deprecations/pending-removal-in-future.rst:68 -msgid ":mod:`importlib.metadata`:" -msgstr ":mod:`importlib.metadata`：" - -#: ../../deprecations/pending-removal-in-future.rst:70 -msgid "``EntryPoints`` tuple interface." -msgstr "``EntryPoints`` 元組介面。" - -#: ../../deprecations/pending-removal-in-future.rst:71 -msgid "Implicit ``None`` on return values." -msgstr "回傳值上的隱式 ``None``。" - -#: ../../deprecations/pending-removal-in-future.rst:73 -msgid "" -":mod:`logging`: the ``warn()`` method has been deprecated since Python 3.3, " -"use :meth:`~logging.warning` instead." -msgstr "" -":mod:`logging`：自 Python 3.3 起，``warn()`` 方法已被棄用，請改用 :meth:" -"`~logging.warning`。" - -#: ../../deprecations/pending-removal-in-future.rst:76 -msgid "" -":mod:`mailbox`: Use of StringIO input and text mode is deprecated, use " -"BytesIO and binary mode instead." -msgstr "" -":mod:`mailbox`：已棄用 StringIO 輸入和文本模式，請改用 BytesIO 和二進位模式。" - -#: ../../deprecations/pending-removal-in-future.rst:79 -msgid "" -":mod:`os`: Calling :func:`os.register_at_fork` in multi-threaded process." -msgstr ":mod:`os`：在多執行緒行程中呼叫 :func:`os.register_at_fork`。" - -#: ../../deprecations/pending-removal-in-future.rst:81 -msgid "" -":class:`!pydoc.ErrorDuringImport`: A tuple value for *exc_info* parameter is " -"deprecated, use an exception instance." -msgstr "" -":class:`!pydoc.ErrorDuringImport`：*exc_info* 參數的元組值已被棄用，請用例外" -"實例。" - -#: ../../deprecations/pending-removal-in-future.rst:84 -msgid "" -":mod:`re`: More strict rules are now applied for numerical group references " -"and group names in regular expressions. Only sequence of ASCII digits is " -"now accepted as a numerical reference. The group name in bytes patterns and " -"replacement strings can now only contain ASCII letters and digits and " -"underscore. (Contributed by Serhiy Storchaka in :gh:`91760`.)" -msgstr "" -":mod:`re`：現在對正規表示式中的數值群組參照和群組名稱用了更嚴格的規則。現在只" -"有 ASCII 數碼序列被接受作為數值參照。位元組模式和替換字串中的群組名稱現在只能" -"包含 ASCII 字母、數碼和底線。（由 Serhiy Storchaka 於 :gh:`91760` 貢獻。）" - -#: ../../deprecations/pending-removal-in-future.rst:91 -msgid "" -":mod:`!sre_compile`, :mod:`!sre_constants` and :mod:`!sre_parse` modules." -msgstr ":mod:`!sre_compile`、:mod:`!sre_constants` 和 :mod:`!sre_parse` 模組。" - -#: ../../deprecations/pending-removal-in-future.rst:93 -msgid "" -":mod:`shutil`: :func:`~shutil.rmtree`'s *onerror* parameter is deprecated in " -"Python 3.12; use the *onexc* parameter instead." -msgstr "" -":mod:`shutil`：:func:`~shutil.rmtree` 的 *onerror* 參數在 Python 3.12 中已被" -"棄用；請改用 *onexc* 參數。" - -#: ../../deprecations/pending-removal-in-future.rst:96 -msgid ":mod:`ssl` options and protocols:" -msgstr ":mod:`ssl` 選項和協定：" - -#: ../../deprecations/pending-removal-in-future.rst:98 -msgid ":class:`ssl.SSLContext` without protocol argument is deprecated." -msgstr "不帶協定引數的 :class:`ssl.SSLContext` 已被棄用。" - -#: ../../deprecations/pending-removal-in-future.rst:99 -msgid "" -":class:`ssl.SSLContext`: :meth:`~ssl.SSLContext.set_npn_protocols` and :meth:" -"`!selected_npn_protocol` are deprecated: use ALPN instead." -msgstr "" -":class:`ssl.SSLContext`：:meth:`~ssl.SSLContext.set_npn_protocols` 和 :meth:" -"`!selected_npn_protocol` 已被棄用：請改用 ALPN。" - -#: ../../deprecations/pending-removal-in-future.rst:102 -msgid "``ssl.OP_NO_SSL*`` options" -msgstr "``ssl.OP_NO_SSL*`` 選項" - -#: ../../deprecations/pending-removal-in-future.rst:103 -msgid "``ssl.OP_NO_TLS*`` options" -msgstr "``ssl.OP_NO_TLS*`` 選項" - -#: ../../deprecations/pending-removal-in-future.rst:104 -msgid "``ssl.PROTOCOL_SSLv3``" -msgstr "``ssl.PROTOCOL_SSLv3``" - -#: ../../deprecations/pending-removal-in-future.rst:105 -msgid "``ssl.PROTOCOL_TLS``" -msgstr "``ssl.PROTOCOL_TLS``" - -#: ../../deprecations/pending-removal-in-future.rst:106 -msgid "``ssl.PROTOCOL_TLSv1``" -msgstr "``ssl.PROTOCOL_TLSv1``" - -#: ../../deprecations/pending-removal-in-future.rst:107 -msgid "``ssl.PROTOCOL_TLSv1_1``" -msgstr "``ssl.PROTOCOL_TLSv1_1``" - -#: ../../deprecations/pending-removal-in-future.rst:108 -msgid "``ssl.PROTOCOL_TLSv1_2``" -msgstr "``ssl.PROTOCOL_TLSv1_2``" - -#: ../../deprecations/pending-removal-in-future.rst:109 -msgid "``ssl.TLSVersion.SSLv3``" -msgstr "``ssl.TLSVersion.SSLv3``" - -#: ../../deprecations/pending-removal-in-future.rst:110 -msgid "``ssl.TLSVersion.TLSv1``" -msgstr "``ssl.TLSVersion.TLSv1``" - -#: ../../deprecations/pending-removal-in-future.rst:111 -msgid "``ssl.TLSVersion.TLSv1_1``" -msgstr "``ssl.TLSVersion.TLSv1_1``" - -#: ../../deprecations/pending-removal-in-future.rst:113 -msgid ":mod:`threading` methods:" -msgstr ":mod:`threading` 方法：" - -#: ../../deprecations/pending-removal-in-future.rst:115 -msgid "" -":meth:`!threading.Condition.notifyAll`: use :meth:`~threading.Condition." -"notify_all`." -msgstr "" -":meth:`!threading.Condition.notifyAll`：請用 :meth:`~threading.Condition." -"notify_all`。" - -#: ../../deprecations/pending-removal-in-future.rst:116 -msgid ":meth:`!threading.Event.isSet`: use :meth:`~threading.Event.is_set`." -msgstr ":meth:`!threading.Event.isSet`：請用 :meth:`~threading.Event.is_set`。" - -#: ../../deprecations/pending-removal-in-future.rst:117 -msgid "" -":meth:`!threading.Thread.isDaemon`, :meth:`threading.Thread.setDaemon`: use :" -"attr:`threading.Thread.daemon` attribute." -msgstr "" -":meth:`!threading.Thread.isDaemon`、:meth:`threading.Thread.setDaemon`：請" -"用 :attr:`threading.Thread.daemon` 屬性。" - -#: ../../deprecations/pending-removal-in-future.rst:119 -msgid "" -":meth:`!threading.Thread.getName`, :meth:`threading.Thread.setName`: use :" -"attr:`threading.Thread.name` attribute." -msgstr "" -":meth:`!threading.Thread.getName`、:meth:`threading.Thread.setName`：請用 :" -"attr:`threading.Thread.name` 屬性。" - -#: ../../deprecations/pending-removal-in-future.rst:121 -msgid ":meth:`!threading.currentThread`: use :meth:`threading.current_thread`." -msgstr "" -":meth:`!threading.currentThread`：請用 :meth:`threading.current_thread`。" - -#: ../../deprecations/pending-removal-in-future.rst:122 -msgid ":meth:`!threading.activeCount`: use :meth:`threading.active_count`." -msgstr ":meth:`!threading.activeCount`：請用 :meth:`threading.active_count`。" - -#: ../../deprecations/pending-removal-in-future.rst:124 -msgid ":class:`typing.Text` (:gh:`92332`)." -msgstr ":class:`typing.Text` (:gh:`92332`)。" - -#: ../../deprecations/pending-removal-in-future.rst:126 -msgid "" -"The internal class ``typing._UnionGenericAlias`` is no longer used to " -"implement :class:`typing.Union`. To preserve compatibility with users using " -"this private class, a compatibility shim will be provided until at least " -"Python 3.17. (Contributed by Jelle Zijlstra in :gh:`105499`.)" -msgstr "" -"內部類別 ``typing._UnionGenericAlias`` 不再用於實作 :class:`typing.Union`。為" -"了保持與此私有類別使用者的相容性，直到至少 Python 3.17 都將提供一個相容性 " -"shim。（由 Jelle Zijlstra 於 :gh:`105499` 貢獻。）" - -#: ../../deprecations/pending-removal-in-future.rst:131 -msgid "" -":class:`unittest.IsolatedAsyncioTestCase`: it is deprecated to return a " -"value that is not ``None`` from a test case." -msgstr "" -":class:`unittest.IsolatedAsyncioTestCase`：從測試案例中回傳非 ``None`` 的值已" -"被棄用。" - -#: ../../deprecations/pending-removal-in-future.rst:134 -msgid "" -":mod:`urllib.parse` deprecated functions: :func:`~urllib.parse.urlparse` " -"instead" -msgstr "" -":mod:`urllib.parse` 已棄用函式：請改用 :func:`~urllib.parse.urlparse`。" - -#: ../../deprecations/pending-removal-in-future.rst:136 -msgid "``splitattr()``" -msgstr "``splitattr()``" - -#: ../../deprecations/pending-removal-in-future.rst:137 -msgid "``splithost()``" -msgstr "``splithost()``" - -#: ../../deprecations/pending-removal-in-future.rst:138 -msgid "``splitnport()``" -msgstr "``splitnport()``" - -#: ../../deprecations/pending-removal-in-future.rst:139 -msgid "``splitpasswd()``" -msgstr "``splitpasswd()``" - -#: ../../deprecations/pending-removal-in-future.rst:140 -msgid "``splitport()``" -msgstr "``splitport()``" - -#: ../../deprecations/pending-removal-in-future.rst:141 -msgid "``splitquery()``" -msgstr "``splitquery()``" - -#: ../../deprecations/pending-removal-in-future.rst:142 -msgid "``splittag()``" -msgstr "``splittag()``" - -#: ../../deprecations/pending-removal-in-future.rst:143 -msgid "``splittype()``" -msgstr "``splittype()``" - -#: ../../deprecations/pending-removal-in-future.rst:144 -msgid "``splituser()``" -msgstr "``splituser()``" - -#: ../../deprecations/pending-removal-in-future.rst:145 -msgid "``splitvalue()``" -msgstr "``splitvalue()``" - -#: ../../deprecations/pending-removal-in-future.rst:146 -msgid "``to_bytes()``" -msgstr "``to_bytes()``" - -#: ../../deprecations/pending-removal-in-future.rst:148 -msgid "" -":mod:`wsgiref`: ``SimpleHandler.stdout.write()`` should not do partial " -"writes." -msgstr ":mod:`wsgiref`：``SimpleHandler.stdout.write()`` 不應該進行部分寫入。" - -#: ../../deprecations/pending-removal-in-future.rst:151 -msgid "" -":mod:`xml.etree.ElementTree`: Testing the truth value of an :class:`~xml." -"etree.ElementTree.Element` is deprecated. In a future release it will always " -"return ``True``. Prefer explicit ``len(elem)`` or ``elem is not None`` tests " -"instead." -msgstr "" -":mod:`xml.etree.ElementTree`：已棄用對 :class:`~xml.etree.ElementTree." -"Element` 的真值測試。在未來版本中，它將始終回傳 ``True``。請改用明確的 " -"``len(elem)`` 或 ``elem is not None`` 測試。" - -#: ../../deprecations/pending-removal-in-future.rst:156 -msgid "" -":func:`sys._clear_type_cache` is deprecated: use :func:`sys." -"_clear_internal_caches` instead." -msgstr "" -":func:`sys._clear_type_cache` 已被棄用：請改用 :func:`sys." -"_clear_internal_caches`。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# FIRST AUTHOR , YEAR +# +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-10-06 00:15+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \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" + +#: ../../deprecations/pending-removal-in-future.rst:2 +msgid "Pending removal in future versions" +msgstr "未來版本中的待移除項目" + +#: ../../deprecations/pending-removal-in-future.rst:4 +msgid "" +"The following APIs will be removed in the future, although there is " +"currently no date scheduled for their removal." +msgstr "以下 API 將在未來被移除，雖然目前尚未安排移除日期。" + +#: ../../deprecations/pending-removal-in-future.rst:7 +msgid ":mod:`argparse`:" +msgstr ":mod:`argparse`：" + +#: ../../deprecations/pending-removal-in-future.rst:9 +msgid "" +"Nesting argument groups and nesting mutually exclusive groups are deprecated." +msgstr "巢狀引數群組和巢狀互斥群組已被棄用。" + +#: ../../deprecations/pending-removal-in-future.rst:11 +msgid "" +"Passing the undocumented keyword argument *prefix_chars* to :meth:`~argparse." +"ArgumentParser.add_argument_group` is now deprecated." +msgstr "" +"將未以文件記錄的關鍵字引數 *prefix_chars* 傳遞給 :meth:`~argparse." +"ArgumentParser.add_argument_group` 的做法現在已被棄用。" + +#: ../../deprecations/pending-removal-in-future.rst:14 +msgid "The :class:`argparse.FileType` type converter is deprecated." +msgstr ":class:`argparse.FileType` 型別轉換器已被棄用。" + +#: ../../deprecations/pending-removal-in-future.rst:16 +msgid ":mod:`builtins`:" +msgstr ":mod:`builtins`：" + +#: ../../deprecations/pending-removal-in-future.rst:18 +msgid "" +"Generators: ``throw(type, exc, tb)`` and ``athrow(type, exc, tb)`` signature " +"is deprecated: use ``throw(exc)`` and ``athrow(exc)`` instead, the single " +"argument signature." +msgstr "" +"產生器：``throw(type, exc, tb)`` 和 ``athrow(type, exc, tb)`` 簽名已被棄用：" +"請改用 ``throw(exc)`` 和 ``athrow(exc)``，為單引數簽名。" + +#: ../../deprecations/pending-removal-in-future.rst:21 +msgid "" +"Currently Python accepts numeric literals immediately followed by keywords, " +"for example ``0in x``, ``1or x``, ``0if 1else 2``. It allows confusing and " +"ambiguous expressions like ``[0x1for x in y]`` (which can be interpreted as " +"``[0x1 for x in y]`` or ``[0x1f or x in y]``). A syntax warning is raised " +"if the numeric literal is immediately followed by one of keywords :keyword:" +"`and`, :keyword:`else`, :keyword:`for`, :keyword:`if`, :keyword:`in`, :" +"keyword:`is` and :keyword:`or`. In a future release it will be changed to a " +"syntax error. (:gh:`87999`)" +msgstr "" +"目前 Python 接受數值字面值後面立即接關鍵字，例如 ``0in x``、``1or x``、``0if " +"1else 2``。它讓運算式模糊且容易混淆，如 ``[0x1for x in y]``\\ （可以解釋為 " +"``[0x1 for x in y]`` 或 ``[0x1f or x in y]``）。如果數值字面值後立即接 :" +"keyword:`and`、:keyword:`else`、:keyword:`for`、:keyword:`if`、:keyword:" +"`in`、:keyword:`is` 和 :keyword:`or` 之一的關鍵字，則會引發語法警告。在未來版" +"本中，它將被更改為語法錯誤。(:gh:`87999`)" + +#: ../../deprecations/pending-removal-in-future.rst:29 +msgid "" +"Support for ``__index__()`` and ``__int__()`` method returning non-int type: " +"these methods will be required to return an instance of a strict subclass " +"of :class:`int`." +msgstr "" +"``__index__()`` 和 ``__int__()`` 方法回傳非 int 型別的支援：這些方法將需要回" +"傳 :class:`int` 的嚴格子類別實例。" + +#: ../../deprecations/pending-removal-in-future.rst:32 +msgid "" +"Support for ``__float__()`` method returning a strict subclass of :class:" +"`float`: these methods will be required to return an instance of :class:" +"`float`." +msgstr "" +"回傳 :class:`float` 嚴格子類別 ``__float__()`` 方法的支援：這些方法將需要回" +"傳 :class:`float` 的實例。" + +#: ../../deprecations/pending-removal-in-future.rst:35 +msgid "" +"Support for ``__complex__()`` method returning a strict subclass of :class:" +"`complex`: these methods will be required to return an instance of :class:" +"`complex`." +msgstr "" +"回傳 :class:`complex` 嚴格子類別 ``__complex__()`` 方法的支援：這些方法將需要" +"回傳 :class:`complex` 的實例。" + +#: ../../deprecations/pending-removal-in-future.rst:38 +msgid "Delegation of ``int()`` to ``__trunc__()`` method." +msgstr "將 ``int()`` 委派給 ``__trunc__()`` 方法。" + +#: ../../deprecations/pending-removal-in-future.rst:39 +msgid "" +"Passing a complex number as the *real* or *imag* argument in the :func:" +"`complex` constructor is now deprecated; it should only be passed as a " +"single positional argument. (Contributed by Serhiy Storchaka in :gh:" +"`109218`.)" +msgstr "" +"在 :func:`complex` 建構子中將複數作為 *real* 或 *imag* 引數傳遞現在已被棄用；" +"它應該只作為單個位置引數傳遞。 (由 Serhiy Storchaka 於 :gh:`109218` 貢獻。)" + +#: ../../deprecations/pending-removal-in-future.rst:44 +msgid "" +":mod:`calendar`: ``calendar.January`` and ``calendar.February`` constants " +"are deprecated and replaced by :data:`calendar.JANUARY` and :data:`calendar." +"FEBRUARY`. (Contributed by Prince Roshan in :gh:`103636`.)" +msgstr "" +":mod:`calendar`：``calendar.January`` 和 ``calendar.February`` 常數已被棄用並" +"被 :data:`calendar.JANUARY` 和 :data:`calendar.FEBRUARY` 取代。 (由 Prince " +"Roshan 於 :gh:`103636` 貢獻。)" + +#: ../../deprecations/pending-removal-in-future.rst:49 +msgid "" +":mod:`codecs`: use :func:`open` instead of :func:`codecs.open`. (:gh:" +"`133038`)" +msgstr "" +":mod:`codecs`：請改用 :func:`open` 而非 :func:`codecs.open`。(:gh:`133038`)" + +#: ../../deprecations/pending-removal-in-future.rst:51 +msgid "" +":attr:`codeobject.co_lnotab`: use the :meth:`codeobject.co_lines` method " +"instead." +msgstr "" +":attr:`codeobject.co_lnotab`：請改用 :meth:`codeobject.co_lines` 方法。" + +#: ../../deprecations/pending-removal-in-future.rst:54 +msgid ":mod:`datetime`:" +msgstr ":mod:`datetime`：" + +#: ../../deprecations/pending-removal-in-future.rst:56 +msgid "" +":meth:`~datetime.datetime.utcnow`: use ``datetime.datetime.now(tz=datetime." +"UTC)``." +msgstr "" +":meth:`~datetime.datetime.utcnow`：請改用 ``datetime.datetime." +"now(tz=datetime.UTC)``。" + +#: ../../deprecations/pending-removal-in-future.rst:58 +msgid "" +":meth:`~datetime.datetime.utcfromtimestamp`: use ``datetime.datetime." +"fromtimestamp(timestamp, tz=datetime.UTC)``." +msgstr "" +":meth:`~datetime.datetime.utcfromtimestamp`：請改用 ``datetime.datetime." +"fromtimestamp(timestamp, tz=datetime.UTC)``。" + +#: ../../deprecations/pending-removal-in-future.rst:61 +msgid ":mod:`gettext`: Plural value must be an integer." +msgstr ":mod:`gettext`：複數值必須是整數。" + +#: ../../deprecations/pending-removal-in-future.rst:63 +msgid ":mod:`importlib`:" +msgstr ":mod:`importlib`：" + +#: ../../deprecations/pending-removal-in-future.rst:65 +msgid "" +":func:`~importlib.util.cache_from_source` *debug_override* parameter is " +"deprecated: use the *optimization* parameter instead." +msgstr "" +":func:`~importlib.util.cache_from_source` *debug_override* 參數已被棄用：請改" +"用 *optimization* 參數。" + +#: ../../deprecations/pending-removal-in-future.rst:68 +msgid ":mod:`importlib.metadata`:" +msgstr ":mod:`importlib.metadata`：" + +#: ../../deprecations/pending-removal-in-future.rst:70 +msgid "``EntryPoints`` tuple interface." +msgstr "``EntryPoints`` 元組介面。" + +#: ../../deprecations/pending-removal-in-future.rst:71 +msgid "Implicit ``None`` on return values." +msgstr "回傳值上的隱式 ``None``。" + +#: ../../deprecations/pending-removal-in-future.rst:73 +msgid "" +":mod:`logging`: the ``warn()`` method has been deprecated since Python 3.3, " +"use :meth:`~logging.warning` instead." +msgstr "" +":mod:`logging`：自 Python 3.3 起，``warn()`` 方法已被棄用，請改用 :meth:" +"`~logging.warning`。" + +#: ../../deprecations/pending-removal-in-future.rst:76 +msgid "" +":mod:`mailbox`: Use of StringIO input and text mode is deprecated, use " +"BytesIO and binary mode instead." +msgstr "" +":mod:`mailbox`：已棄用 StringIO 輸入和文本模式，請改用 BytesIO 和二進位模式。" + +#: ../../deprecations/pending-removal-in-future.rst:79 +msgid "" +":mod:`os`: Calling :func:`os.register_at_fork` in multi-threaded process." +msgstr ":mod:`os`：在多執行緒行程中呼叫 :func:`os.register_at_fork`。" + +#: ../../deprecations/pending-removal-in-future.rst:81 +msgid "" +":class:`!pydoc.ErrorDuringImport`: A tuple value for *exc_info* parameter is " +"deprecated, use an exception instance." +msgstr "" +":class:`!pydoc.ErrorDuringImport`：*exc_info* 參數的元組值已被棄用，請用例外" +"實例。" + +#: ../../deprecations/pending-removal-in-future.rst:84 +msgid "" +":mod:`re`: More strict rules are now applied for numerical group references " +"and group names in regular expressions. Only sequence of ASCII digits is " +"now accepted as a numerical reference. The group name in bytes patterns and " +"replacement strings can now only contain ASCII letters and digits and " +"underscore. (Contributed by Serhiy Storchaka in :gh:`91760`.)" +msgstr "" +":mod:`re`：現在對正規表示式中的數值群組參照和群組名稱用了更嚴格的規則。現在只" +"有 ASCII 數碼序列被接受作為數值參照。位元組模式和替換字串中的群組名稱現在只能" +"包含 ASCII 字母、數碼和底線。（由 Serhiy Storchaka 於 :gh:`91760` 貢獻。）" + +#: ../../deprecations/pending-removal-in-future.rst:91 +msgid "" +":mod:`!sre_compile`, :mod:`!sre_constants` and :mod:`!sre_parse` modules." +msgstr ":mod:`!sre_compile`、:mod:`!sre_constants` 和 :mod:`!sre_parse` 模組。" + +#: ../../deprecations/pending-removal-in-future.rst:93 +msgid "" +":mod:`shutil`: :func:`~shutil.rmtree`'s *onerror* parameter is deprecated in " +"Python 3.12; use the *onexc* parameter instead." +msgstr "" +":mod:`shutil`：:func:`~shutil.rmtree` 的 *onerror* 參數在 Python 3.12 中已被" +"棄用；請改用 *onexc* 參數。" + +#: ../../deprecations/pending-removal-in-future.rst:96 +msgid ":mod:`ssl` options and protocols:" +msgstr ":mod:`ssl` 選項和協定：" + +#: ../../deprecations/pending-removal-in-future.rst:98 +msgid ":class:`ssl.SSLContext` without protocol argument is deprecated." +msgstr "不帶協定引數的 :class:`ssl.SSLContext` 已被棄用。" + +#: ../../deprecations/pending-removal-in-future.rst:99 +msgid "" +":class:`ssl.SSLContext`: :meth:`~ssl.SSLContext.set_npn_protocols` and :meth:" +"`!selected_npn_protocol` are deprecated: use ALPN instead." +msgstr "" +":class:`ssl.SSLContext`：:meth:`~ssl.SSLContext.set_npn_protocols` 和 :meth:" +"`!selected_npn_protocol` 已被棄用：請改用 ALPN。" + +#: ../../deprecations/pending-removal-in-future.rst:102 +msgid "``ssl.OP_NO_SSL*`` options" +msgstr "``ssl.OP_NO_SSL*`` 選項" + +#: ../../deprecations/pending-removal-in-future.rst:103 +msgid "``ssl.OP_NO_TLS*`` options" +msgstr "``ssl.OP_NO_TLS*`` 選項" + +#: ../../deprecations/pending-removal-in-future.rst:104 +msgid "``ssl.PROTOCOL_SSLv3``" +msgstr "``ssl.PROTOCOL_SSLv3``" + +#: ../../deprecations/pending-removal-in-future.rst:105 +msgid "``ssl.PROTOCOL_TLS``" +msgstr "``ssl.PROTOCOL_TLS``" + +#: ../../deprecations/pending-removal-in-future.rst:106 +msgid "``ssl.PROTOCOL_TLSv1``" +msgstr "``ssl.PROTOCOL_TLSv1``" + +#: ../../deprecations/pending-removal-in-future.rst:107 +msgid "``ssl.PROTOCOL_TLSv1_1``" +msgstr "``ssl.PROTOCOL_TLSv1_1``" + +#: ../../deprecations/pending-removal-in-future.rst:108 +msgid "``ssl.PROTOCOL_TLSv1_2``" +msgstr "``ssl.PROTOCOL_TLSv1_2``" + +#: ../../deprecations/pending-removal-in-future.rst:109 +msgid "``ssl.TLSVersion.SSLv3``" +msgstr "``ssl.TLSVersion.SSLv3``" + +#: ../../deprecations/pending-removal-in-future.rst:110 +msgid "``ssl.TLSVersion.TLSv1``" +msgstr "``ssl.TLSVersion.TLSv1``" + +#: ../../deprecations/pending-removal-in-future.rst:111 +msgid "``ssl.TLSVersion.TLSv1_1``" +msgstr "``ssl.TLSVersion.TLSv1_1``" + +#: ../../deprecations/pending-removal-in-future.rst:113 +msgid ":mod:`threading` methods:" +msgstr ":mod:`threading` 方法：" + +#: ../../deprecations/pending-removal-in-future.rst:115 +msgid "" +":meth:`!threading.Condition.notifyAll`: use :meth:`~threading.Condition." +"notify_all`." +msgstr "" +":meth:`!threading.Condition.notifyAll`：請用 :meth:`~threading.Condition." +"notify_all`。" + +#: ../../deprecations/pending-removal-in-future.rst:116 +msgid ":meth:`!threading.Event.isSet`: use :meth:`~threading.Event.is_set`." +msgstr ":meth:`!threading.Event.isSet`：請用 :meth:`~threading.Event.is_set`。" + +#: ../../deprecations/pending-removal-in-future.rst:117 +msgid "" +":meth:`!threading.Thread.isDaemon`, :meth:`threading.Thread.setDaemon`: use :" +"attr:`threading.Thread.daemon` attribute." +msgstr "" +":meth:`!threading.Thread.isDaemon`、:meth:`threading.Thread.setDaemon`：請" +"用 :attr:`threading.Thread.daemon` 屬性。" + +#: ../../deprecations/pending-removal-in-future.rst:119 +msgid "" +":meth:`!threading.Thread.getName`, :meth:`threading.Thread.setName`: use :" +"attr:`threading.Thread.name` attribute." +msgstr "" +":meth:`!threading.Thread.getName`、:meth:`threading.Thread.setName`：請用 :" +"attr:`threading.Thread.name` 屬性。" + +#: ../../deprecations/pending-removal-in-future.rst:121 +msgid ":meth:`!threading.currentThread`: use :meth:`threading.current_thread`." +msgstr "" +":meth:`!threading.currentThread`：請用 :meth:`threading.current_thread`。" + +#: ../../deprecations/pending-removal-in-future.rst:122 +msgid ":meth:`!threading.activeCount`: use :meth:`threading.active_count`." +msgstr ":meth:`!threading.activeCount`：請用 :meth:`threading.active_count`。" + +#: ../../deprecations/pending-removal-in-future.rst:124 +msgid ":class:`typing.Text` (:gh:`92332`)." +msgstr ":class:`typing.Text` (:gh:`92332`)。" + +#: ../../deprecations/pending-removal-in-future.rst:126 +msgid "" +"The internal class ``typing._UnionGenericAlias`` is no longer used to " +"implement :class:`typing.Union`. To preserve compatibility with users using " +"this private class, a compatibility shim will be provided until at least " +"Python 3.17. (Contributed by Jelle Zijlstra in :gh:`105499`.)" +msgstr "" +"內部類別 ``typing._UnionGenericAlias`` 不再用於實作 :class:`typing.Union`。為" +"了保持與此私有類別使用者的相容性，直到至少 Python 3.17 都將提供一個相容性 " +"shim。（由 Jelle Zijlstra 於 :gh:`105499` 貢獻。）" + +#: ../../deprecations/pending-removal-in-future.rst:131 +msgid "" +":class:`unittest.IsolatedAsyncioTestCase`: it is deprecated to return a " +"value that is not ``None`` from a test case." +msgstr "" +":class:`unittest.IsolatedAsyncioTestCase`：從測試案例中回傳非 ``None`` 的值已" +"被棄用。" + +#: ../../deprecations/pending-removal-in-future.rst:134 +msgid "" +":mod:`urllib.parse` deprecated functions: :func:`~urllib.parse.urlparse` " +"instead" +msgstr "" +":mod:`urllib.parse` 已棄用函式：請改用 :func:`~urllib.parse.urlparse`。" + +#: ../../deprecations/pending-removal-in-future.rst:136 +msgid "``splitattr()``" +msgstr "``splitattr()``" + +#: ../../deprecations/pending-removal-in-future.rst:137 +msgid "``splithost()``" +msgstr "``splithost()``" + +#: ../../deprecations/pending-removal-in-future.rst:138 +msgid "``splitnport()``" +msgstr "``splitnport()``" + +#: ../../deprecations/pending-removal-in-future.rst:139 +msgid "``splitpasswd()``" +msgstr "``splitpasswd()``" + +#: ../../deprecations/pending-removal-in-future.rst:140 +msgid "``splitport()``" +msgstr "``splitport()``" + +#: ../../deprecations/pending-removal-in-future.rst:141 +msgid "``splitquery()``" +msgstr "``splitquery()``" + +#: ../../deprecations/pending-removal-in-future.rst:142 +msgid "``splittag()``" +msgstr "``splittag()``" + +#: ../../deprecations/pending-removal-in-future.rst:143 +msgid "``splittype()``" +msgstr "``splittype()``" + +#: ../../deprecations/pending-removal-in-future.rst:144 +msgid "``splituser()``" +msgstr "``splituser()``" + +#: ../../deprecations/pending-removal-in-future.rst:145 +msgid "``splitvalue()``" +msgstr "``splitvalue()``" + +#: ../../deprecations/pending-removal-in-future.rst:146 +msgid "``to_bytes()``" +msgstr "``to_bytes()``" + +#: ../../deprecations/pending-removal-in-future.rst:148 +msgid "" +":mod:`wsgiref`: ``SimpleHandler.stdout.write()`` should not do partial " +"writes." +msgstr ":mod:`wsgiref`：``SimpleHandler.stdout.write()`` 不應該進行部分寫入。" + +#: ../../deprecations/pending-removal-in-future.rst:151 +msgid "" +":mod:`xml.etree.ElementTree`: Testing the truth value of an :class:`~xml." +"etree.ElementTree.Element` is deprecated. In a future release it will always " +"return ``True``. Prefer explicit ``len(elem)`` or ``elem is not None`` tests " +"instead." +msgstr "" +":mod:`xml.etree.ElementTree`：已棄用對 :class:`~xml.etree.ElementTree." +"Element` 的真值測試。在未來版本中，它將始終回傳 ``True``。請改用明確的 " +"``len(elem)`` 或 ``elem is not None`` 測試。" + +#: ../../deprecations/pending-removal-in-future.rst:156 +msgid "" +":func:`sys._clear_type_cache` is deprecated: use :func:`sys." +"_clear_internal_caches` instead." +msgstr "" +":func:`sys._clear_type_cache` 已被棄用：請改用 :func:`sys." +"_clear_internal_caches`。" diff --git a/distributing/index.po b/distributing/index.po index 6b969cb0e4..69af54044d 100644 --- a/distributing/index.po +++ b/distributing/index.po @@ -1,34 +1,34 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Leon H., 2017 -# Steven Hsu , 2021 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2023-08-18 00:03+0000\n" -"PO-Revision-Date: 2021-07-04 18:06+0800\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" -"X-Generator: Poedit 3.2.2\n" - -#: ../../distributing/index.rst:10 -msgid "Distributing Python Modules" -msgstr "發布 Python 模組" - -#: ../../distributing/index.rst:14 -msgid "" -"Information and guidance on distributing Python modules and packages has " -"been moved to the `Python Packaging User Guide`_, and the tutorial on " -"`packaging Python projects`_." -msgstr "" -"有關發布 Python 模組和套件的資訊和指南已移至 `Python Packaging User Guide`_，" -"而相關教學已經移至 `packaging Python projects`_。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Leon H., 2017 +# Steven Hsu , 2021 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-08-18 00:03+0000\n" +"PO-Revision-Date: 2021-07-04 18:06+0800\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" +"X-Generator: Poedit 3.2.2\n" + +#: ../../distributing/index.rst:10 +msgid "Distributing Python Modules" +msgstr "發布 Python 模組" + +#: ../../distributing/index.rst:14 +msgid "" +"Information and guidance on distributing Python modules and packages has " +"been moved to the `Python Packaging User Guide`_, and the tutorial on " +"`packaging Python projects`_." +msgstr "" +"有關發布 Python 模組和套件的資訊和指南已移至 `Python Packaging User Guide`_，" +"而相關教學已經移至 `packaging Python projects`_。" diff --git a/extending/building.po b/extending/building.po index 42cf78789f..99b9ac64e3 100644 --- a/extending/building.po +++ b/extending/building.po @@ -1,56 +1,56 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Adrian Liaw , 2018 -# Matt Wang , 2025 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: 2025-02-07 14:09+0000\n" -"Last-Translator: Matt Wang \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" - -#: ../../extending/building.rst:7 -msgid "Building C and C++ Extensions" -msgstr "建立 C 與 C++ 擴充套件" - -#: ../../extending/building.rst:9 -msgid "" -"A C extension for CPython is a shared library (for example, a ``.so`` file " -"on Linux, ``.pyd`` on Windows), which exports an *initialization function*." -msgstr "" -"一個 CPython 的 C 擴充套件是一個共用函式庫（例如在 Linux 上的 ``.so`` 檔案，" -"在 Windows 上的 ``.pyd``），會匯出一個\\ *初始化函式*。" - -#: ../../extending/building.rst:12 -msgid "See :ref:`extension-modules` for details." -msgstr "詳見 :ref:`extension-modules`。" - -#: ../../extending/building.rst:21 -msgid "Building C and C++ Extensions with setuptools" -msgstr "用 setuptools 建置 C 與 C++ 擴充套件" - -#: ../../extending/building.rst:24 -msgid "" -"Building, packaging and distributing extension modules is best done with " -"third-party tools, and is out of scope of this document. One suitable tool " -"is Setuptools, whose documentation can be found at https://" -"setuptools.pypa.io/en/latest/setuptools.html." -msgstr "" - -#: ../../extending/building.rst:29 -msgid "" -"The :mod:`distutils` module, which was included in the standard library " -"until Python 3.12, is now maintained as part of Setuptools." -msgstr "" -"直到 Python 3.12 版本前，:mod:`distutils` 模組都被包含在標準函式庫中，" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Adrian Liaw , 2018 +# Matt Wang , 2025 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: 2025-02-07 14:09+0000\n" +"Last-Translator: Matt Wang \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" + +#: ../../extending/building.rst:7 +msgid "Building C and C++ Extensions" +msgstr "建立 C 與 C++ 擴充套件" + +#: ../../extending/building.rst:9 +msgid "" +"A C extension for CPython is a shared library (for example, a ``.so`` file " +"on Linux, ``.pyd`` on Windows), which exports an *initialization function*." +msgstr "" +"一個 CPython 的 C 擴充套件是一個共用函式庫（例如在 Linux 上的 ``.so`` 檔案，" +"在 Windows 上的 ``.pyd``），會匯出一個\\ *初始化函式*。" + +#: ../../extending/building.rst:12 +msgid "See :ref:`extension-modules` for details." +msgstr "詳見 :ref:`extension-modules`。" + +#: ../../extending/building.rst:21 +msgid "Building C and C++ Extensions with setuptools" +msgstr "用 setuptools 建置 C 與 C++ 擴充套件" + +#: ../../extending/building.rst:24 +msgid "" +"Building, packaging and distributing extension modules is best done with " +"third-party tools, and is out of scope of this document. One suitable tool " +"is Setuptools, whose documentation can be found at https://" +"setuptools.pypa.io/en/latest/setuptools.html." +msgstr "" + +#: ../../extending/building.rst:29 +msgid "" +"The :mod:`distutils` module, which was included in the standard library " +"until Python 3.12, is now maintained as part of Setuptools." +msgstr "" +"直到 Python 3.12 版本前，:mod:`distutils` 模組都被包含在標準函式庫中，" "現在是作為 Setuptools 的一部分來維護。" \ No newline at end of file diff --git a/extending/embedding.po b/extending/embedding.po index c796af330d..972c5a67a0 100644 --- a/extending/embedding.po +++ b/extending/embedding.po @@ -1,713 +1,713 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Leon H., 2017 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-06-27 07:36+0000\n" -"PO-Revision-Date: 2018-05-23 14:09+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" - -#: ../../extending/embedding.rst:8 -msgid "Embedding Python in Another Application" -msgstr "在其它 App 內嵌入 Python" - -#: ../../extending/embedding.rst:10 -msgid "" -"The previous chapters discussed how to extend Python, that is, how to extend " -"the functionality of Python by attaching a library of C functions to it. It " -"is also possible to do it the other way around: enrich your C/C++ " -"application by embedding Python in it. Embedding provides your application " -"with the ability to implement some of the functionality of your application " -"in Python rather than C or C++. This can be used for many purposes; one " -"example would be to allow users to tailor the application to their needs by " -"writing some scripts in Python. You can also use it yourself if some of the " -"functionality can be written in Python more easily." -msgstr "" -"前面的章節討論了如何擴充 Python，也就是如何透過附加一個 C 函式庫來擴充 " -"Python 的功能。但也可以反過來做：將 Python 嵌入你的 C/C++ 應用程式中" -"。嵌入讓你的應用程式能夠以 Python 而非 C 或 C++ 來實作應用程式的某些功能。" -"這可以用於許多目的；其中一個例子是允許使用者透過撰寫一些 Python 腳本來根據他們" -"的需求客製化應用程式。如果某些功能用 Python 寫起來比較容易，你也可以自己使用" -"這種方法。" - -#: ../../extending/embedding.rst:20 -msgid "" -"Embedding Python is similar to extending it, but not quite. The difference " -"is that when you extend Python, the main program of the application is still " -"the Python interpreter, while if you embed Python, the main program may have " -"nothing to do with Python --- instead, some parts of the application " -"occasionally call the Python interpreter to run some Python code." -msgstr "" -"嵌入 Python 與擴充 Python 類似，但不完全相同。差別在於當你擴充 Python 時，應用程式" -"的主程式仍然是 Python 直譯器，而當你嵌入 Python，主程式可能與 Python " -"無關 — 相反地，應用程式的某些部分偶爾會呼叫 Python 直譯器來執行一些 Python " -"程式碼。" - -#: ../../extending/embedding.rst:26 -msgid "" -"So if you are embedding Python, you are providing your own main program. " -"One of the things this main program has to do is initialize the Python " -"interpreter. At the very least, you have to call the function :c:func:" -"`Py_Initialize`. There are optional calls to pass command line arguments to " -"Python. Then later you can call the interpreter from any part of the " -"application." -msgstr "" -"所以如果你要嵌入 Python，你要提供自己的主程式。這個主程式必須做的事情之一是" -"初始化 Python 直譯器，或至少必須要呼叫函式 :c:func:`Py_Initialize`。還有一些" -"可選的呼叫來傳遞命令列引數給 Python。然後你就可以在應用程式的任何部分呼叫直譯" -"器。" - -#: ../../extending/embedding.rst:32 -msgid "" -"There are several different ways to call the interpreter: you can pass a " -"string containing Python statements to :c:func:`PyRun_SimpleString`, or you " -"can pass a stdio file pointer and a file name (for identification in error " -"messages only) to :c:func:`PyRun_SimpleFile`. You can also call the lower-" -"level operations described in the previous chapters to construct and use " -"Python objects." -msgstr "" -"有幾種不同的方式來呼叫直譯器：你可以傳遞一個包含 Python 陳述式的字串給 :c:func:" -"`PyRun_SimpleString`，或者你可以傳遞一個 stdio 檔案指標和檔案名稱（僅用於錯誤" -"訊息中的識別）給 :c:func:`PyRun_SimpleFile`。你也可以呼叫前面章節中描述的較低" -"層級操作來建構和使用 Python 物件。" - -#: ../../extending/embedding.rst:41 -msgid ":ref:`c-api-index`" -msgstr ":ref:`c-api-index`" - -#: ../../extending/embedding.rst:42 -msgid "" -"The details of Python's C interface are given in this manual. A great deal " -"of necessary information can be found here." -msgstr "" -"Python 的 C 介面詳細資訊在此手冊中提供。大量必要的資訊可以在這裡找到。" - -#: ../../extending/embedding.rst:49 -msgid "Very High Level Embedding" -msgstr "非常高階的嵌入" - -#: ../../extending/embedding.rst:51 -msgid "" -"The simplest form of embedding Python is the use of the very high level " -"interface. This interface is intended to execute a Python script without " -"needing to interact with the application directly. This can for example be " -"used to perform some operation on a file. ::" -msgstr "" -"嵌入 Python 最簡單的形式是使用非常高階的介面。此介面用於執行 Python 腳本而" -"無需直接與應用程式互動。例如這可以用來對檔案執行一些操作。 ::" - -#: ../../extending/embedding.rst:56 -msgid "" -"#define PY_SSIZE_T_CLEAN\n" -"#include \n" -"\n" -"int\n" -"main(int argc, char *argv[])\n" -"{\n" -" PyStatus status;\n" -" PyConfig config;\n" -" PyConfig_InitPythonConfig(&config);\n" -"\n" -" /* optional but recommended */\n" -" status = PyConfig_SetBytesString(&config, &config.program_name, " -"argv[0]);\n" -" if (PyStatus_Exception(status)) {\n" -" goto exception;\n" -" }\n" -"\n" -" status = Py_InitializeFromConfig(&config);\n" -" if (PyStatus_Exception(status)) {\n" -" goto exception;\n" -" }\n" -" PyConfig_Clear(&config);\n" -"\n" -" PyRun_SimpleString(\"from time import time,ctime\\n\"\n" -" \"print('Today is', ctime(time()))\\n\");\n" -" if (Py_FinalizeEx() < 0) {\n" -" exit(120);\n" -" }\n" -" return 0;\n" -"\n" -" exception:\n" -" PyConfig_Clear(&config);\n" -" Py_ExitStatusException(status);\n" -"}" -msgstr "" -"#define PY_SSIZE_T_CLEAN\n" -"#include \n" -"\n" -"int\n" -"main(int argc, char *argv[])\n" -"{\n" -" PyStatus status;\n" -" PyConfig config;\n" -" PyConfig_InitPythonConfig(&config);\n" -"\n" -" /* 建議但非必要 */\n" -" status = PyConfig_SetBytesString(&config, &config.program_name, " -"argv[0]);\n" -" if (PyStatus_Exception(status)) {\n" -" goto exception;\n" -" }\n" -"\n" -" status = Py_InitializeFromConfig(&config);\n" -" if (PyStatus_Exception(status)) {\n" -" goto exception;\n" -" }\n" -" PyConfig_Clear(&config);\n" -"\n" -" PyRun_SimpleString(\"from time import time,ctime\\n\"\n" -" \"print('Today is', ctime(time()))\\n\");\n" -" if (Py_FinalizeEx() < 0) {\n" -" exit(120);\n" -" }\n" -" return 0;\n" -"\n" -" exception:\n" -" PyConfig_Clear(&config);\n" -" Py_ExitStatusException(status);\n" -"}" - -#: ../../extending/embedding.rst:92 -msgid "" -"``#define PY_SSIZE_T_CLEAN`` was used to indicate that ``Py_ssize_t`` should " -"be used in some APIs instead of ``int``. It is not necessary since Python " -"3.13, but we keep it here for backward compatibility. See :ref:`arg-parsing-" -"string-and-buffers` for a description of this macro." -msgstr "" -"``#define PY_SSIZE_T_CLEAN`` 被用來指示某些 API 應該使用 ``Py_ssize_t`` 而不是 " -"``int``。從 Python 3.13 開始不再需要它，但我們保留它以維持向後相容性。" -"關於此巨集的描述請參閱 :ref:`arg-parsing-string-and-buffers`。" - -#: ../../extending/embedding.rst:97 -msgid "" -"Setting :c:member:`PyConfig.program_name` should be called before :c:func:" -"`Py_InitializeFromConfig` to inform the interpreter about paths to Python " -"run-time libraries. Next, the Python interpreter is initialized with :c:" -"func:`Py_Initialize`, followed by the execution of a hard-coded Python " -"script that prints the date and time. Afterwards, the :c:func:" -"`Py_FinalizeEx` call shuts the interpreter down, followed by the end of the " -"program. In a real program, you may want to get the Python script from " -"another source, perhaps a text-editor routine, a file, or a database. " -"Getting the Python code from a file can better be done by using the :c:func:" -"`PyRun_SimpleFile` function, which saves you the trouble of allocating " -"memory space and loading the file contents." -msgstr "" -":c:member:`PyConfig.program_name` 的設定應該在 :c:func:`Py_InitializeFromConfig` " -"前呼叫，以告知直譯器 Python run-time 函式庫的路徑。接下來，Python 直譯器會用 :c:" -"func:`Py_Initialize` 初始化，然後執行一個硬編碼的 Python 腳本來印出日期和時間。" -"之後，:c:func:`Py_FinalizeEx` 呼叫會關閉直譯器，接著程式結束。在真實的程式中，" -"你可能想要從另一個來源取得 Python 腳本，或許是文字編輯器例程、檔案或資料庫。" -"從檔案取得 Python 程式碼可以更好地使用 :c:func:`PyRun_SimpleFile` 函式來完成，" -"這樣可以省去分配記憶體空間和載入檔案內容的麻煩。" - -#: ../../extending/embedding.rst:112 -msgid "Beyond Very High Level Embedding: An overview" -msgstr "超越非常高階嵌入：概觀" - -#: ../../extending/embedding.rst:114 -msgid "" -"The high level interface gives you the ability to execute arbitrary pieces " -"of Python code from your application, but exchanging data values is quite " -"cumbersome to say the least. If you want that, you should use lower level " -"calls. At the cost of having to write more C code, you can achieve almost " -"anything." -msgstr "" -"高階介面讓你能夠從應用程式中執行任意的 Python 程式碼片段，但交換資料" -"值的過程可以說相當繁瑣。如果你想進行這類操作，應該使用較低階的呼叫。" -"雖然需要撰寫更多的 C 程式碼，但幾乎可以實現任何功能。" - -#: ../../extending/embedding.rst:119 -msgid "" -"It should be noted that extending Python and embedding Python is quite the " -"same activity, despite the different intent. Most topics discussed in the " -"previous chapters are still valid. To show this, consider what the extension " -"code from Python to C really does:" -msgstr "" -"需要注意的是，雖然目的不同，但擴充 Python 與嵌入 Python 其實是非常相似的操作，" -"前面章節討論的大多數主題在這裡同樣適用。為了說明這一點，請思考從 Python 到 C " -"的擴充程式碼實際上做了什麼：" - -#: ../../extending/embedding.rst:124 -msgid "Convert data values from Python to C," -msgstr "將資料值從 Python 轉換為 C，" - -#: ../../extending/embedding.rst:126 -msgid "Perform a function call to a C routine using the converted values, and" -msgstr "使用轉換後的值呼叫 C 例程，並" - -#: ../../extending/embedding.rst:128 -msgid "Convert the data values from the call from C to Python." -msgstr "將呼叫中的資料值從 C 轉換為 Python。" - -#: ../../extending/embedding.rst:130 -msgid "When embedding Python, the interface code does:" -msgstr "當嵌入 Python 時，介面程式碼會：" - -#: ../../extending/embedding.rst:132 -msgid "Convert data values from C to Python," -msgstr "將資料值從 C 轉換為 Python，" - -#: ../../extending/embedding.rst:134 -msgid "" -"Perform a function call to a Python interface routine using the converted " -"values, and" -msgstr "使用轉換後的值呼叫 Python 介面例程，並" - -#: ../../extending/embedding.rst:137 -msgid "Convert the data values from the call from Python to C." -msgstr "將呼叫中的資料值從 Python 轉換為 C。" - -#: ../../extending/embedding.rst:139 -msgid "" -"As you can see, the data conversion steps are simply swapped to accommodate " -"the different direction of the cross-language transfer. The only difference " -"is the routine that you call between both data conversions. When extending, " -"you call a C routine, when embedding, you call a Python routine." -msgstr "" -"如你所見，資料轉換的步驟只是互換了順序，以配合跨語言傳遞方向的不同。唯一的差別在於" -"兩個資料轉換之間所呼叫的例程：在擴充時你呼叫的是 C 例程；在嵌入時則呼叫 Python " -"例程。" - -#: ../../extending/embedding.rst:144 -msgid "" -"This chapter will not discuss how to convert data from Python to C and vice " -"versa. Also, proper use of references and dealing with errors is assumed to " -"be understood. Since these aspects do not differ from extending the " -"interpreter, you can refer to earlier chapters for the required information." -msgstr "" -"本章不會討論如何將資料從 Python 轉換為 C 或從 C 轉換回 Python，且假設讀者已經知道參照的" -"正確使用方式與錯誤處理。由於這些部分與擴充直譯器時相同，" -"相關資訊可參考前面的章節。" - -#: ../../extending/embedding.rst:153 -msgid "Pure Embedding" -msgstr "純嵌入" - -#: ../../extending/embedding.rst:155 -msgid "" -"The first program aims to execute a function in a Python script. Like in the " -"section about the very high level interface, the Python interpreter does not " -"directly interact with the application (but that will change in the next " -"section)." -msgstr "" -"第一個程式的目標是執行 Python 腳本中的函式。就像在非常高階介面的章節中一樣，" -"Python 直譯器不會直接與應用程式互動（但這在下一節會改變）。" - -#: ../../extending/embedding.rst:160 -msgid "The code to run a function defined in a Python script is:" -msgstr "執行 Python 腳本中定義函式的程式碼是：" - -#: ../../extending/embedding.rst:162 -msgid "" -"#define PY_SSIZE_T_CLEAN\n" -"#include \n" -"\n" -"int\n" -"main(int argc, char *argv[])\n" -"{\n" -" PyObject *pName, *pModule, *pFunc;\n" -" PyObject *pArgs, *pValue;\n" -" int i;\n" -"\n" -" if (argc < 3) {\n" -" fprintf(stderr,\"Usage: call pythonfile funcname [args]\\n\");\n" -" return 1;\n" -" }\n" -"\n" -" Py_Initialize();\n" -" pName = PyUnicode_DecodeFSDefault(argv[1]);\n" -" /* Error checking of pName left out */\n" -"\n" -" pModule = PyImport_Import(pName);\n" -" Py_DECREF(pName);\n" -"\n" -" if (pModule != NULL) {\n" -" pFunc = PyObject_GetAttrString(pModule, argv[2]);\n" -" /* pFunc is a new reference */\n" -"\n" -" if (pFunc && PyCallable_Check(pFunc)) {\n" -" pArgs = PyTuple_New(argc - 3);\n" -" for (i = 0; i < argc - 3; ++i) {\n" -" pValue = PyLong_FromLong(atoi(argv[i + 3]));\n" -" if (!pValue) {\n" -" Py_DECREF(pArgs);\n" -" Py_DECREF(pModule);\n" -" fprintf(stderr, \"Cannot convert argument\\n\");\n" -" return 1;\n" -" }\n" -" /* pValue reference stolen here: */\n" -" PyTuple_SetItem(pArgs, i, pValue);\n" -" }\n" -" pValue = PyObject_CallObject(pFunc, pArgs);\n" -" Py_DECREF(pArgs);\n" -" if (pValue != NULL) {\n" -" printf(\"Result of call: %ld\\n\", PyLong_AsLong(pValue));\n" -" Py_DECREF(pValue);\n" -" }\n" -" else {\n" -" Py_DECREF(pFunc);\n" -" Py_DECREF(pModule);\n" -" PyErr_Print();\n" -" fprintf(stderr,\"Call failed\\n\");\n" -" return 1;\n" -" }\n" -" }\n" -" else {\n" -" if (PyErr_Occurred())\n" -" PyErr_Print();\n" -" fprintf(stderr, \"Cannot find function \\\"%s\\\"\\n\", " -"argv[2]);\n" -" }\n" -" Py_XDECREF(pFunc);\n" -" Py_DECREF(pModule);\n" -" }\n" -" else {\n" -" PyErr_Print();\n" -" fprintf(stderr, \"Failed to load \\\"%s\\\"\\n\", argv[1]);\n" -" return 1;\n" -" }\n" -" if (Py_FinalizeEx() < 0) {\n" -" return 120;\n" -" }\n" -" return 0;\n" -"}\n" -msgstr "" - -#: ../../extending/embedding.rst:165 -msgid "" -"This code loads a Python script using ``argv[1]``, and calls the function " -"named in ``argv[2]``. Its integer arguments are the other values of the " -"``argv`` array. If you :ref:`compile and link ` this program " -"(let's call the finished executable :program:`call`), and use it to execute " -"a Python script, such as:" -msgstr "" -"此程式碼使用 ``argv[1]`` 載入 Python 腳本，並呼叫 ``argv[2]`` 中所指定的函式。" -"其整數引數則來自 ``argv`` 陣列中的其他值。如果你\\ :ref:`編譯並連結 `\\ 此" -"程式（我們稱完成的可執行檔為 :program:`call`），並用它來執行 Python 腳本，" -"例如：" - -#: ../../extending/embedding.rst:171 -msgid "" -"def multiply(a,b):\n" -" print(\"Will compute\", a, \"times\", b)\n" -" c = 0\n" -" for i in range(0, a):\n" -" c = c + b\n" -" return c" -msgstr "" -"def multiply(a,b):\n" -" print(\"Will compute\", a, \"times\", b)\n" -" c = 0\n" -" for i in range(0, a):\n" -" c = c + b\n" -" return c" - -#: ../../extending/embedding.rst:180 -msgid "then the result should be:" -msgstr "那麼結果應該是：" - -#: ../../extending/embedding.rst:182 -msgid "" -"$ call multiply multiply 3 2\n" -"Will compute 3 times 2\n" -"Result of call: 6" -msgstr "" -"$ call multiply multiply 3 2\n" -"Will compute 3 times 2\n" -"Result of call: 6" - -#: ../../extending/embedding.rst:188 -msgid "" -"Although the program is quite large for its functionality, most of the code " -"is for data conversion between Python and C, and for error reporting. The " -"interesting part with respect to embedding Python starts with ::" -msgstr "" -"雖然以其功能而言這個程式相當龐大，但大部分的程式碼是用於 Python 與 C 之間的資料" -"轉換以及錯誤回報。至於與嵌入 Python 有關的重點部分，則從以下開始： ::" - -#: ../../extending/embedding.rst:192 -msgid "" -"Py_Initialize();\n" -"pName = PyUnicode_DecodeFSDefault(argv[1]);\n" -"/* Error checking of pName left out */\n" -"pModule = PyImport_Import(pName);" -msgstr "" -"Py_Initialize();\n" -"pName = PyUnicode_DecodeFSDefault(argv[1]);\n" -"/* Error checking of pName left out */\n" -"pModule = PyImport_Import(pName);" - -#: ../../extending/embedding.rst:197 -msgid "" -"After initializing the interpreter, the script is loaded using :c:func:" -"`PyImport_Import`. This routine needs a Python string as its argument, " -"which is constructed using the :c:func:`PyUnicode_DecodeFSDefault` data " -"conversion routine. ::" -msgstr "" -"在初始化直譯器後，腳本使用 :c:func:`PyImport_Import` 載入。此例程需要一個 " -"Python 字串作為其引數，該字串使用 :c:func:`PyUnicode_DecodeFSDefault` 資料" -"轉換例程建構。 ::" - -#: ../../extending/embedding.rst:202 -msgid "" -"pFunc = PyObject_GetAttrString(pModule, argv[2]);\n" -"/* pFunc is a new reference */\n" -"\n" -"if (pFunc && PyCallable_Check(pFunc)) {\n" -" ...\n" -"}\n" -"Py_XDECREF(pFunc);" -msgstr "" -"pFunc = PyObject_GetAttrString(pModule, argv[2]);\n" -"/* pFunc is a new reference */\n" -"\n" -"if (pFunc && PyCallable_Check(pFunc)) {\n" -" ...\n" -"}\n" -"Py_XDECREF(pFunc);" - -#: ../../extending/embedding.rst:210 -msgid "" -"Once the script is loaded, the name we're looking for is retrieved using :c:" -"func:`PyObject_GetAttrString`. If the name exists, and the object returned " -"is callable, you can safely assume that it is a function. The program then " -"proceeds by constructing a tuple of arguments as normal. The call to the " -"Python function is then made with::" -msgstr "" -"腳本載入後，會使用 :c:func:`PyObject_GetAttrString` 來取得所需的名稱。如果" -"該名稱存在，且回傳的物件是可呼叫的，便可安全地假設它是一個函式。接著，程式會以" -"一般方式建立引數的元組。之後便以下列方式呼叫該 Python 函式： ::" - -#: ../../extending/embedding.rst:216 -msgid "pValue = PyObject_CallObject(pFunc, pArgs);" -msgstr "pValue = PyObject_CallObject(pFunc, pArgs);" - -#: ../../extending/embedding.rst:218 -msgid "" -"Upon return of the function, ``pValue`` is either ``NULL`` or it contains a " -"reference to the return value of the function. Be sure to release the " -"reference after examining the value." -msgstr "" -"函式回傳時，``pValue`` 要不是 ``NULL`` 就是包含函式回傳值的參照。請務必在檢查" -"值之後釋放參照。" - -#: ../../extending/embedding.rst:226 -msgid "Extending Embedded Python" -msgstr "擴充嵌入式 Python" - -#: ../../extending/embedding.rst:228 -msgid "" -"Until now, the embedded Python interpreter had no access to functionality " -"from the application itself. The Python API allows this by extending the " -"embedded interpreter. That is, the embedded interpreter gets extended with " -"routines provided by the application. While it sounds complex, it is not so " -"bad. Simply forget for a while that the application starts the Python " -"interpreter. Instead, consider the application to be a set of subroutines, " -"and write some glue code that gives Python access to those routines, just " -"like you would write a normal Python extension. For example::" -msgstr "" -"到目前為止，嵌入式 Python 直譯器尚無法存取應用程式本身的功能。Python API 允許透過" -"擴充嵌入式直譯器來達成這點。也就是說，嵌入式直譯器可以由應用程式所提供的例程加以" -"擴充。雖然聽起來複雜但其實並不難。只要暫時忘記是應用程式啟動了 Python 直譯器，" -"改以將應用程式視為一組子程序，並撰寫一些膠合程式碼讓 Python 能夠存取" -"這些例程，就像你撰寫一般 Python 擴充一樣。例如： ::" - -#: ../../extending/embedding.rst:237 -msgid "" -"static int numargs=0;\n" -"\n" -"/* Return the number of arguments of the application command line */\n" -"static PyObject*\n" -"emb_numargs(PyObject *self, PyObject *args)\n" -"{\n" -" if(!PyArg_ParseTuple(args, \":numargs\"))\n" -" return NULL;\n" -" return PyLong_FromLong(numargs);\n" -"}\n" -"\n" -"static PyMethodDef emb_module_methods[] = {\n" -" {\"numargs\", emb_numargs, METH_VARARGS,\n" -" \"Return the number of arguments received by the process.\"},\n" -" {NULL, NULL, 0, NULL}\n" -"};\n" -"\n" -"static struct PyModuleDef emb_module = {\n" -" .m_base = PyModuleDef_HEAD_INIT,\n" -" .m_name = \"emb\",\n" -" .m_size = 0,\n" -" .m_methods = emb_module_methods,\n" -"};\n" -"\n" -"static PyObject*\n" -"PyInit_emb(void)\n" -"{\n" -" return PyModuleDef_Init(&emb_module);\n" -"}" -msgstr "" - -#: ../../extending/embedding.rst:267 -msgid "" -"Insert the above code just above the :c:func:`main` function. Also, insert " -"the following two statements before the call to :c:func:`Py_Initialize`::" -msgstr "" -"在 :c:func:`main` 函式的正上方插入上述程式碼。同時，在呼叫 :c:func:" -"`Py_Initialize` 之前插入以下兩個陳述式： ::" - -#: ../../extending/embedding.rst:270 -msgid "" -"numargs = argc;\n" -"PyImport_AppendInittab(\"emb\", &PyInit_emb);" -msgstr "" -"numargs = argc;\n" -"PyImport_AppendInittab(\"emb\", &PyInit_emb);" - -#: ../../extending/embedding.rst:273 -msgid "" -"These two lines initialize the ``numargs`` variable, and make the :func:`!" -"emb.numargs` function accessible to the embedded Python interpreter. With " -"these extensions, the Python script can do things like" -msgstr "" -"這兩行初始化 ``numargs`` 變數，並讓 :func:`!emb.numargs` 函式可供嵌入式 Python " -"直譯器使用。有了這些擴充後，Python 腳本便可以執行像是以下的操作" - -#: ../../extending/embedding.rst:277 -msgid "" -"import emb\n" -"print(\"Number of arguments\", emb.numargs())" -msgstr "" -"import emb\n" -"print(\"Number of arguments\", emb.numargs())" - -#: ../../extending/embedding.rst:282 -msgid "" -"In a real application, the methods will expose an API of the application to " -"Python." -msgstr "在真實的應用程式中，這些方法會向 Python 公開應用程式的 API。" - -#: ../../extending/embedding.rst:292 -msgid "Embedding Python in C++" -msgstr "在 C++ 中嵌入 Python" - -#: ../../extending/embedding.rst:294 -msgid "" -"It is also possible to embed Python in a C++ program; precisely how this is " -"done will depend on the details of the C++ system used; in general you will " -"need to write the main program in C++, and use the C++ compiler to compile " -"and link your program. There is no need to recompile Python itself using C+" -"+." -msgstr "" -"也可以將 Python 嵌入 C++ 程式中；具體如何做取決於所使用的 C++ 系統的細節；" -"一般來說，你需要用 C++ 撰寫主程式，並使用 C++ 編譯器來編譯和連結你的程式。" -"不需要使用 C++ 重新編譯 Python 本身。" - -#: ../../extending/embedding.rst:303 -msgid "Compiling and Linking under Unix-like systems" -msgstr "在類 Unix 系統下編譯和連結" - -#: ../../extending/embedding.rst:305 -msgid "" -"It is not necessarily trivial to find the right flags to pass to your " -"compiler (and linker) in order to embed the Python interpreter into your " -"application, particularly because Python needs to load library modules " -"implemented as C dynamic extensions (:file:`.so` files) linked against it." -msgstr "" -"要找到傳遞給編譯器（和連結器）的正確旗標以便將 Python 直譯器嵌入你的應用程式" -"中，並不一定是簡單的事，特別是因為 Python 需要載入作為 C 動態擴充（:file:`.so` 檔案）實作的函式庫" -"模組，而這些模組又必須與 Python 進行連結。" - -#: ../../extending/embedding.rst:311 -msgid "" -"To find out the required compiler and linker flags, you can execute the :" -"file:`python{X.Y}-config` script which is generated as part of the " -"installation process (a :file:`python3-config` script may also be " -"available). This script has several options, of which the following will be " -"directly useful to you:" -msgstr "" -"要找出所需的編譯器和連結器旗標，你可以執行作為安裝過程的一部分產生的 :file:" -"`python{X.Y}-config` 腳本（也可能有 :file:`python3-config` 腳本可用）。此腳本" -"提供多種選項，其中以下幾個最為實用：" - -#: ../../extending/embedding.rst:317 -msgid "" -"``pythonX.Y-config --cflags`` will give you the recommended flags when " -"compiling:" -msgstr "``pythonX.Y-config --cflags`` 會給你編譯時建議的旗標：" - -#: ../../extending/embedding.rst:320 -msgid "" -"$ /opt/bin/python3.11-config --cflags\n" -"-I/opt/include/python3.11 -I/opt/include/python3.11 -Wsign-compare -DNDEBUG " -"-g -fwrapv -O3 -Wall" -msgstr "" -"$ /opt/bin/python3.11-config --cflags\n" -"-I/opt/include/python3.11 -I/opt/include/python3.11 -Wsign-compare -DNDEBUG " -"-g -fwrapv -O3 -Wall" - -#: ../../extending/embedding.rst:325 -msgid "" -"``pythonX.Y-config --ldflags --embed`` will give you the recommended flags " -"when linking:" -msgstr "``pythonX.Y-config --ldflags --embed`` 會給你連結時建議的旗標：" - -#: ../../extending/embedding.rst:328 -msgid "" -"$ /opt/bin/python3.11-config --ldflags --embed\n" -"-L/opt/lib/python3.11/config-3.11-x86_64-linux-gnu -L/opt/lib -lpython3.11 -" -"lpthread -ldl -lutil -lm" -msgstr "" -"$ /opt/bin/python3.11-config --ldflags --embed\n" -"-L/opt/lib/python3.11/config-3.11-x86_64-linux-gnu -L/opt/lib -lpython3.11 -" -"lpthread -ldl -lutil -lm" - -#: ../../extending/embedding.rst:334 -msgid "" -"To avoid confusion between several Python installations (and especially " -"between the system Python and your own compiled Python), it is recommended " -"that you use the absolute path to :file:`python{X.Y}-config`, as in the " -"above example." -msgstr "" -"為了避免多個 Python 安裝之間產生混淆（特別是系統自帶的 Python 與自行編譯的 Python " -"之間），建議使用 :file:`python{X.Y}-config` 的絕對路徑，如上面的例子所示。" - -#: ../../extending/embedding.rst:339 -msgid "" -"If this procedure doesn't work for you (it is not guaranteed to work for all " -"Unix-like platforms; however, we welcome :ref:`bug reports `) you will have to read your system's documentation about dynamic " -"linking and/or examine Python's :file:`Makefile` (use :func:`sysconfig." -"get_makefile_filename` to find its location) and compilation options. In " -"this case, the :mod:`sysconfig` module is a useful tool to programmatically " -"extract the configuration values that you will want to combine together. " -"For example:" -msgstr "" -"如果此程序對你不起作用（並不保證在所有類 Unix 平台上都能運作；不過我們歡迎\\ :ref:" -"`錯誤回報 `），你將需要參閱系統的動態連結相關文件，並／或檢查 " -"Python 的 :file:`Makefile`\\ （可使用 :func:`sysconfig.get_makefile_filename` 來" -"找到其位置）和編譯選項。在這種情況下，:mod:`sysconfig` 模組是一個實用的工具，" -"可用於以程式化方式擷取並組合所需的組態值。例如：" - -#: ../../extending/embedding.rst:348 -msgid "" -">>> import sysconfig\n" -">>> sysconfig.get_config_var('LIBS')\n" -"'-lpthread -ldl -lutil'\n" -">>> sysconfig.get_config_var('LINKFORSHARED')\n" -"'-Xlinker -export-dynamic'" -msgstr "" -">>> import sysconfig\n" -">>> sysconfig.get_config_var('LIBS')\n" -"'-lpthread -ldl -lutil'\n" -">>> sysconfig.get_config_var('LINKFORSHARED')\n" -"'-Xlinker -export-dynamic'" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Leon H., 2017 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-06-27 07:36+0000\n" +"PO-Revision-Date: 2018-05-23 14:09+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" + +#: ../../extending/embedding.rst:8 +msgid "Embedding Python in Another Application" +msgstr "在其它 App 內嵌入 Python" + +#: ../../extending/embedding.rst:10 +msgid "" +"The previous chapters discussed how to extend Python, that is, how to extend " +"the functionality of Python by attaching a library of C functions to it. It " +"is also possible to do it the other way around: enrich your C/C++ " +"application by embedding Python in it. Embedding provides your application " +"with the ability to implement some of the functionality of your application " +"in Python rather than C or C++. This can be used for many purposes; one " +"example would be to allow users to tailor the application to their needs by " +"writing some scripts in Python. You can also use it yourself if some of the " +"functionality can be written in Python more easily." +msgstr "" +"前面的章節討論了如何擴充 Python，也就是如何透過附加一個 C 函式庫來擴充 " +"Python 的功能。但也可以反過來做：將 Python 嵌入你的 C/C++ 應用程式中" +"。嵌入讓你的應用程式能夠以 Python 而非 C 或 C++ 來實作應用程式的某些功能。" +"這可以用於許多目的；其中一個例子是允許使用者透過撰寫一些 Python 腳本來根據他們" +"的需求客製化應用程式。如果某些功能用 Python 寫起來比較容易，你也可以自己使用" +"這種方法。" + +#: ../../extending/embedding.rst:20 +msgid "" +"Embedding Python is similar to extending it, but not quite. The difference " +"is that when you extend Python, the main program of the application is still " +"the Python interpreter, while if you embed Python, the main program may have " +"nothing to do with Python --- instead, some parts of the application " +"occasionally call the Python interpreter to run some Python code." +msgstr "" +"嵌入 Python 與擴充 Python 類似，但不完全相同。差別在於當你擴充 Python 時，應用程式" +"的主程式仍然是 Python 直譯器，而當你嵌入 Python，主程式可能與 Python " +"無關 — 相反地，應用程式的某些部分偶爾會呼叫 Python 直譯器來執行一些 Python " +"程式碼。" + +#: ../../extending/embedding.rst:26 +msgid "" +"So if you are embedding Python, you are providing your own main program. " +"One of the things this main program has to do is initialize the Python " +"interpreter. At the very least, you have to call the function :c:func:" +"`Py_Initialize`. There are optional calls to pass command line arguments to " +"Python. Then later you can call the interpreter from any part of the " +"application." +msgstr "" +"所以如果你要嵌入 Python，你要提供自己的主程式。這個主程式必須做的事情之一是" +"初始化 Python 直譯器，或至少必須要呼叫函式 :c:func:`Py_Initialize`。還有一些" +"可選的呼叫來傳遞命令列引數給 Python。然後你就可以在應用程式的任何部分呼叫直譯" +"器。" + +#: ../../extending/embedding.rst:32 +msgid "" +"There are several different ways to call the interpreter: you can pass a " +"string containing Python statements to :c:func:`PyRun_SimpleString`, or you " +"can pass a stdio file pointer and a file name (for identification in error " +"messages only) to :c:func:`PyRun_SimpleFile`. You can also call the lower-" +"level operations described in the previous chapters to construct and use " +"Python objects." +msgstr "" +"有幾種不同的方式來呼叫直譯器：你可以傳遞一個包含 Python 陳述式的字串給 :c:func:" +"`PyRun_SimpleString`，或者你可以傳遞一個 stdio 檔案指標和檔案名稱（僅用於錯誤" +"訊息中的識別）給 :c:func:`PyRun_SimpleFile`。你也可以呼叫前面章節中描述的較低" +"層級操作來建構和使用 Python 物件。" + +#: ../../extending/embedding.rst:41 +msgid ":ref:`c-api-index`" +msgstr ":ref:`c-api-index`" + +#: ../../extending/embedding.rst:42 +msgid "" +"The details of Python's C interface are given in this manual. A great deal " +"of necessary information can be found here." +msgstr "" +"Python 的 C 介面詳細資訊在此手冊中提供。大量必要的資訊可以在這裡找到。" + +#: ../../extending/embedding.rst:49 +msgid "Very High Level Embedding" +msgstr "非常高階的嵌入" + +#: ../../extending/embedding.rst:51 +msgid "" +"The simplest form of embedding Python is the use of the very high level " +"interface. This interface is intended to execute a Python script without " +"needing to interact with the application directly. This can for example be " +"used to perform some operation on a file. ::" +msgstr "" +"嵌入 Python 最簡單的形式是使用非常高階的介面。此介面用於執行 Python 腳本而" +"無需直接與應用程式互動。例如這可以用來對檔案執行一些操作。 ::" + +#: ../../extending/embedding.rst:56 +msgid "" +"#define PY_SSIZE_T_CLEAN\n" +"#include \n" +"\n" +"int\n" +"main(int argc, char *argv[])\n" +"{\n" +" PyStatus status;\n" +" PyConfig config;\n" +" PyConfig_InitPythonConfig(&config);\n" +"\n" +" /* optional but recommended */\n" +" status = PyConfig_SetBytesString(&config, &config.program_name, " +"argv[0]);\n" +" if (PyStatus_Exception(status)) {\n" +" goto exception;\n" +" }\n" +"\n" +" status = Py_InitializeFromConfig(&config);\n" +" if (PyStatus_Exception(status)) {\n" +" goto exception;\n" +" }\n" +" PyConfig_Clear(&config);\n" +"\n" +" PyRun_SimpleString(\"from time import time,ctime\\n\"\n" +" \"print('Today is', ctime(time()))\\n\");\n" +" if (Py_FinalizeEx() < 0) {\n" +" exit(120);\n" +" }\n" +" return 0;\n" +"\n" +" exception:\n" +" PyConfig_Clear(&config);\n" +" Py_ExitStatusException(status);\n" +"}" +msgstr "" +"#define PY_SSIZE_T_CLEAN\n" +"#include \n" +"\n" +"int\n" +"main(int argc, char *argv[])\n" +"{\n" +" PyStatus status;\n" +" PyConfig config;\n" +" PyConfig_InitPythonConfig(&config);\n" +"\n" +" /* 建議但非必要 */\n" +" status = PyConfig_SetBytesString(&config, &config.program_name, " +"argv[0]);\n" +" if (PyStatus_Exception(status)) {\n" +" goto exception;\n" +" }\n" +"\n" +" status = Py_InitializeFromConfig(&config);\n" +" if (PyStatus_Exception(status)) {\n" +" goto exception;\n" +" }\n" +" PyConfig_Clear(&config);\n" +"\n" +" PyRun_SimpleString(\"from time import time,ctime\\n\"\n" +" \"print('Today is', ctime(time()))\\n\");\n" +" if (Py_FinalizeEx() < 0) {\n" +" exit(120);\n" +" }\n" +" return 0;\n" +"\n" +" exception:\n" +" PyConfig_Clear(&config);\n" +" Py_ExitStatusException(status);\n" +"}" + +#: ../../extending/embedding.rst:92 +msgid "" +"``#define PY_SSIZE_T_CLEAN`` was used to indicate that ``Py_ssize_t`` should " +"be used in some APIs instead of ``int``. It is not necessary since Python " +"3.13, but we keep it here for backward compatibility. See :ref:`arg-parsing-" +"string-and-buffers` for a description of this macro." +msgstr "" +"``#define PY_SSIZE_T_CLEAN`` 被用來指示某些 API 應該使用 ``Py_ssize_t`` 而不是 " +"``int``。從 Python 3.13 開始不再需要它，但我們保留它以維持向後相容性。" +"關於此巨集的描述請參閱 :ref:`arg-parsing-string-and-buffers`。" + +#: ../../extending/embedding.rst:97 +msgid "" +"Setting :c:member:`PyConfig.program_name` should be called before :c:func:" +"`Py_InitializeFromConfig` to inform the interpreter about paths to Python " +"run-time libraries. Next, the Python interpreter is initialized with :c:" +"func:`Py_Initialize`, followed by the execution of a hard-coded Python " +"script that prints the date and time. Afterwards, the :c:func:" +"`Py_FinalizeEx` call shuts the interpreter down, followed by the end of the " +"program. In a real program, you may want to get the Python script from " +"another source, perhaps a text-editor routine, a file, or a database. " +"Getting the Python code from a file can better be done by using the :c:func:" +"`PyRun_SimpleFile` function, which saves you the trouble of allocating " +"memory space and loading the file contents." +msgstr "" +":c:member:`PyConfig.program_name` 的設定應該在 :c:func:`Py_InitializeFromConfig` " +"前呼叫，以告知直譯器 Python run-time 函式庫的路徑。接下來，Python 直譯器會用 :c:" +"func:`Py_Initialize` 初始化，然後執行一個硬編碼的 Python 腳本來印出日期和時間。" +"之後，:c:func:`Py_FinalizeEx` 呼叫會關閉直譯器，接著程式結束。在真實的程式中，" +"你可能想要從另一個來源取得 Python 腳本，或許是文字編輯器例程、檔案或資料庫。" +"從檔案取得 Python 程式碼可以更好地使用 :c:func:`PyRun_SimpleFile` 函式來完成，" +"這樣可以省去分配記憶體空間和載入檔案內容的麻煩。" + +#: ../../extending/embedding.rst:112 +msgid "Beyond Very High Level Embedding: An overview" +msgstr "超越非常高階嵌入：概觀" + +#: ../../extending/embedding.rst:114 +msgid "" +"The high level interface gives you the ability to execute arbitrary pieces " +"of Python code from your application, but exchanging data values is quite " +"cumbersome to say the least. If you want that, you should use lower level " +"calls. At the cost of having to write more C code, you can achieve almost " +"anything." +msgstr "" +"高階介面讓你能夠從應用程式中執行任意的 Python 程式碼片段，但交換資料" +"值的過程可以說相當繁瑣。如果你想進行這類操作，應該使用較低階的呼叫。" +"雖然需要撰寫更多的 C 程式碼，但幾乎可以實現任何功能。" + +#: ../../extending/embedding.rst:119 +msgid "" +"It should be noted that extending Python and embedding Python is quite the " +"same activity, despite the different intent. Most topics discussed in the " +"previous chapters are still valid. To show this, consider what the extension " +"code from Python to C really does:" +msgstr "" +"需要注意的是，雖然目的不同，但擴充 Python 與嵌入 Python 其實是非常相似的操作，" +"前面章節討論的大多數主題在這裡同樣適用。為了說明這一點，請思考從 Python 到 C " +"的擴充程式碼實際上做了什麼：" + +#: ../../extending/embedding.rst:124 +msgid "Convert data values from Python to C," +msgstr "將資料值從 Python 轉換為 C，" + +#: ../../extending/embedding.rst:126 +msgid "Perform a function call to a C routine using the converted values, and" +msgstr "使用轉換後的值呼叫 C 例程，並" + +#: ../../extending/embedding.rst:128 +msgid "Convert the data values from the call from C to Python." +msgstr "將呼叫中的資料值從 C 轉換為 Python。" + +#: ../../extending/embedding.rst:130 +msgid "When embedding Python, the interface code does:" +msgstr "當嵌入 Python 時，介面程式碼會：" + +#: ../../extending/embedding.rst:132 +msgid "Convert data values from C to Python," +msgstr "將資料值從 C 轉換為 Python，" + +#: ../../extending/embedding.rst:134 +msgid "" +"Perform a function call to a Python interface routine using the converted " +"values, and" +msgstr "使用轉換後的值呼叫 Python 介面例程，並" + +#: ../../extending/embedding.rst:137 +msgid "Convert the data values from the call from Python to C." +msgstr "將呼叫中的資料值從 Python 轉換為 C。" + +#: ../../extending/embedding.rst:139 +msgid "" +"As you can see, the data conversion steps are simply swapped to accommodate " +"the different direction of the cross-language transfer. The only difference " +"is the routine that you call between both data conversions. When extending, " +"you call a C routine, when embedding, you call a Python routine." +msgstr "" +"如你所見，資料轉換的步驟只是互換了順序，以配合跨語言傳遞方向的不同。唯一的差別在於" +"兩個資料轉換之間所呼叫的例程：在擴充時你呼叫的是 C 例程；在嵌入時則呼叫 Python " +"例程。" + +#: ../../extending/embedding.rst:144 +msgid "" +"This chapter will not discuss how to convert data from Python to C and vice " +"versa. Also, proper use of references and dealing with errors is assumed to " +"be understood. Since these aspects do not differ from extending the " +"interpreter, you can refer to earlier chapters for the required information." +msgstr "" +"本章不會討論如何將資料從 Python 轉換為 C 或從 C 轉換回 Python，且假設讀者已經知道參照的" +"正確使用方式與錯誤處理。由於這些部分與擴充直譯器時相同，" +"相關資訊可參考前面的章節。" + +#: ../../extending/embedding.rst:153 +msgid "Pure Embedding" +msgstr "純嵌入" + +#: ../../extending/embedding.rst:155 +msgid "" +"The first program aims to execute a function in a Python script. Like in the " +"section about the very high level interface, the Python interpreter does not " +"directly interact with the application (but that will change in the next " +"section)." +msgstr "" +"第一個程式的目標是執行 Python 腳本中的函式。就像在非常高階介面的章節中一樣，" +"Python 直譯器不會直接與應用程式互動（但這在下一節會改變）。" + +#: ../../extending/embedding.rst:160 +msgid "The code to run a function defined in a Python script is:" +msgstr "執行 Python 腳本中定義函式的程式碼是：" + +#: ../../extending/embedding.rst:162 +msgid "" +"#define PY_SSIZE_T_CLEAN\n" +"#include \n" +"\n" +"int\n" +"main(int argc, char *argv[])\n" +"{\n" +" PyObject *pName, *pModule, *pFunc;\n" +" PyObject *pArgs, *pValue;\n" +" int i;\n" +"\n" +" if (argc < 3) {\n" +" fprintf(stderr,\"Usage: call pythonfile funcname [args]\\n\");\n" +" return 1;\n" +" }\n" +"\n" +" Py_Initialize();\n" +" pName = PyUnicode_DecodeFSDefault(argv[1]);\n" +" /* Error checking of pName left out */\n" +"\n" +" pModule = PyImport_Import(pName);\n" +" Py_DECREF(pName);\n" +"\n" +" if (pModule != NULL) {\n" +" pFunc = PyObject_GetAttrString(pModule, argv[2]);\n" +" /* pFunc is a new reference */\n" +"\n" +" if (pFunc && PyCallable_Check(pFunc)) {\n" +" pArgs = PyTuple_New(argc - 3);\n" +" for (i = 0; i < argc - 3; ++i) {\n" +" pValue = PyLong_FromLong(atoi(argv[i + 3]));\n" +" if (!pValue) {\n" +" Py_DECREF(pArgs);\n" +" Py_DECREF(pModule);\n" +" fprintf(stderr, \"Cannot convert argument\\n\");\n" +" return 1;\n" +" }\n" +" /* pValue reference stolen here: */\n" +" PyTuple_SetItem(pArgs, i, pValue);\n" +" }\n" +" pValue = PyObject_CallObject(pFunc, pArgs);\n" +" Py_DECREF(pArgs);\n" +" if (pValue != NULL) {\n" +" printf(\"Result of call: %ld\\n\", PyLong_AsLong(pValue));\n" +" Py_DECREF(pValue);\n" +" }\n" +" else {\n" +" Py_DECREF(pFunc);\n" +" Py_DECREF(pModule);\n" +" PyErr_Print();\n" +" fprintf(stderr,\"Call failed\\n\");\n" +" return 1;\n" +" }\n" +" }\n" +" else {\n" +" if (PyErr_Occurred())\n" +" PyErr_Print();\n" +" fprintf(stderr, \"Cannot find function \\\"%s\\\"\\n\", " +"argv[2]);\n" +" }\n" +" Py_XDECREF(pFunc);\n" +" Py_DECREF(pModule);\n" +" }\n" +" else {\n" +" PyErr_Print();\n" +" fprintf(stderr, \"Failed to load \\\"%s\\\"\\n\", argv[1]);\n" +" return 1;\n" +" }\n" +" if (Py_FinalizeEx() < 0) {\n" +" return 120;\n" +" }\n" +" return 0;\n" +"}\n" +msgstr "" + +#: ../../extending/embedding.rst:165 +msgid "" +"This code loads a Python script using ``argv[1]``, and calls the function " +"named in ``argv[2]``. Its integer arguments are the other values of the " +"``argv`` array. If you :ref:`compile and link ` this program " +"(let's call the finished executable :program:`call`), and use it to execute " +"a Python script, such as:" +msgstr "" +"此程式碼使用 ``argv[1]`` 載入 Python 腳本，並呼叫 ``argv[2]`` 中所指定的函式。" +"其整數引數則來自 ``argv`` 陣列中的其他值。如果你\\ :ref:`編譯並連結 `\\ 此" +"程式（我們稱完成的可執行檔為 :program:`call`），並用它來執行 Python 腳本，" +"例如：" + +#: ../../extending/embedding.rst:171 +msgid "" +"def multiply(a,b):\n" +" print(\"Will compute\", a, \"times\", b)\n" +" c = 0\n" +" for i in range(0, a):\n" +" c = c + b\n" +" return c" +msgstr "" +"def multiply(a,b):\n" +" print(\"Will compute\", a, \"times\", b)\n" +" c = 0\n" +" for i in range(0, a):\n" +" c = c + b\n" +" return c" + +#: ../../extending/embedding.rst:180 +msgid "then the result should be:" +msgstr "那麼結果應該是：" + +#: ../../extending/embedding.rst:182 +msgid "" +"$ call multiply multiply 3 2\n" +"Will compute 3 times 2\n" +"Result of call: 6" +msgstr "" +"$ call multiply multiply 3 2\n" +"Will compute 3 times 2\n" +"Result of call: 6" + +#: ../../extending/embedding.rst:188 +msgid "" +"Although the program is quite large for its functionality, most of the code " +"is for data conversion between Python and C, and for error reporting. The " +"interesting part with respect to embedding Python starts with ::" +msgstr "" +"雖然以其功能而言這個程式相當龐大，但大部分的程式碼是用於 Python 與 C 之間的資料" +"轉換以及錯誤回報。至於與嵌入 Python 有關的重點部分，則從以下開始： ::" + +#: ../../extending/embedding.rst:192 +msgid "" +"Py_Initialize();\n" +"pName = PyUnicode_DecodeFSDefault(argv[1]);\n" +"/* Error checking of pName left out */\n" +"pModule = PyImport_Import(pName);" +msgstr "" +"Py_Initialize();\n" +"pName = PyUnicode_DecodeFSDefault(argv[1]);\n" +"/* Error checking of pName left out */\n" +"pModule = PyImport_Import(pName);" + +#: ../../extending/embedding.rst:197 +msgid "" +"After initializing the interpreter, the script is loaded using :c:func:" +"`PyImport_Import`. This routine needs a Python string as its argument, " +"which is constructed using the :c:func:`PyUnicode_DecodeFSDefault` data " +"conversion routine. ::" +msgstr "" +"在初始化直譯器後，腳本使用 :c:func:`PyImport_Import` 載入。此例程需要一個 " +"Python 字串作為其引數，該字串使用 :c:func:`PyUnicode_DecodeFSDefault` 資料" +"轉換例程建構。 ::" + +#: ../../extending/embedding.rst:202 +msgid "" +"pFunc = PyObject_GetAttrString(pModule, argv[2]);\n" +"/* pFunc is a new reference */\n" +"\n" +"if (pFunc && PyCallable_Check(pFunc)) {\n" +" ...\n" +"}\n" +"Py_XDECREF(pFunc);" +msgstr "" +"pFunc = PyObject_GetAttrString(pModule, argv[2]);\n" +"/* pFunc is a new reference */\n" +"\n" +"if (pFunc && PyCallable_Check(pFunc)) {\n" +" ...\n" +"}\n" +"Py_XDECREF(pFunc);" + +#: ../../extending/embedding.rst:210 +msgid "" +"Once the script is loaded, the name we're looking for is retrieved using :c:" +"func:`PyObject_GetAttrString`. If the name exists, and the object returned " +"is callable, you can safely assume that it is a function. The program then " +"proceeds by constructing a tuple of arguments as normal. The call to the " +"Python function is then made with::" +msgstr "" +"腳本載入後，會使用 :c:func:`PyObject_GetAttrString` 來取得所需的名稱。如果" +"該名稱存在，且回傳的物件是可呼叫的，便可安全地假設它是一個函式。接著，程式會以" +"一般方式建立引數的元組。之後便以下列方式呼叫該 Python 函式： ::" + +#: ../../extending/embedding.rst:216 +msgid "pValue = PyObject_CallObject(pFunc, pArgs);" +msgstr "pValue = PyObject_CallObject(pFunc, pArgs);" + +#: ../../extending/embedding.rst:218 +msgid "" +"Upon return of the function, ``pValue`` is either ``NULL`` or it contains a " +"reference to the return value of the function. Be sure to release the " +"reference after examining the value." +msgstr "" +"函式回傳時，``pValue`` 要不是 ``NULL`` 就是包含函式回傳值的參照。請務必在檢查" +"值之後釋放參照。" + +#: ../../extending/embedding.rst:226 +msgid "Extending Embedded Python" +msgstr "擴充嵌入式 Python" + +#: ../../extending/embedding.rst:228 +msgid "" +"Until now, the embedded Python interpreter had no access to functionality " +"from the application itself. The Python API allows this by extending the " +"embedded interpreter. That is, the embedded interpreter gets extended with " +"routines provided by the application. While it sounds complex, it is not so " +"bad. Simply forget for a while that the application starts the Python " +"interpreter. Instead, consider the application to be a set of subroutines, " +"and write some glue code that gives Python access to those routines, just " +"like you would write a normal Python extension. For example::" +msgstr "" +"到目前為止，嵌入式 Python 直譯器尚無法存取應用程式本身的功能。Python API 允許透過" +"擴充嵌入式直譯器來達成這點。也就是說，嵌入式直譯器可以由應用程式所提供的例程加以" +"擴充。雖然聽起來複雜但其實並不難。只要暫時忘記是應用程式啟動了 Python 直譯器，" +"改以將應用程式視為一組子程序，並撰寫一些膠合程式碼讓 Python 能夠存取" +"這些例程，就像你撰寫一般 Python 擴充一樣。例如： ::" + +#: ../../extending/embedding.rst:237 +msgid "" +"static int numargs=0;\n" +"\n" +"/* Return the number of arguments of the application command line */\n" +"static PyObject*\n" +"emb_numargs(PyObject *self, PyObject *args)\n" +"{\n" +" if(!PyArg_ParseTuple(args, \":numargs\"))\n" +" return NULL;\n" +" return PyLong_FromLong(numargs);\n" +"}\n" +"\n" +"static PyMethodDef emb_module_methods[] = {\n" +" {\"numargs\", emb_numargs, METH_VARARGS,\n" +" \"Return the number of arguments received by the process.\"},\n" +" {NULL, NULL, 0, NULL}\n" +"};\n" +"\n" +"static struct PyModuleDef emb_module = {\n" +" .m_base = PyModuleDef_HEAD_INIT,\n" +" .m_name = \"emb\",\n" +" .m_size = 0,\n" +" .m_methods = emb_module_methods,\n" +"};\n" +"\n" +"static PyObject*\n" +"PyInit_emb(void)\n" +"{\n" +" return PyModuleDef_Init(&emb_module);\n" +"}" +msgstr "" + +#: ../../extending/embedding.rst:267 +msgid "" +"Insert the above code just above the :c:func:`main` function. Also, insert " +"the following two statements before the call to :c:func:`Py_Initialize`::" +msgstr "" +"在 :c:func:`main` 函式的正上方插入上述程式碼。同時，在呼叫 :c:func:" +"`Py_Initialize` 之前插入以下兩個陳述式： ::" + +#: ../../extending/embedding.rst:270 +msgid "" +"numargs = argc;\n" +"PyImport_AppendInittab(\"emb\", &PyInit_emb);" +msgstr "" +"numargs = argc;\n" +"PyImport_AppendInittab(\"emb\", &PyInit_emb);" + +#: ../../extending/embedding.rst:273 +msgid "" +"These two lines initialize the ``numargs`` variable, and make the :func:`!" +"emb.numargs` function accessible to the embedded Python interpreter. With " +"these extensions, the Python script can do things like" +msgstr "" +"這兩行初始化 ``numargs`` 變數，並讓 :func:`!emb.numargs` 函式可供嵌入式 Python " +"直譯器使用。有了這些擴充後，Python 腳本便可以執行像是以下的操作" + +#: ../../extending/embedding.rst:277 +msgid "" +"import emb\n" +"print(\"Number of arguments\", emb.numargs())" +msgstr "" +"import emb\n" +"print(\"Number of arguments\", emb.numargs())" + +#: ../../extending/embedding.rst:282 +msgid "" +"In a real application, the methods will expose an API of the application to " +"Python." +msgstr "在真實的應用程式中，這些方法會向 Python 公開應用程式的 API。" + +#: ../../extending/embedding.rst:292 +msgid "Embedding Python in C++" +msgstr "在 C++ 中嵌入 Python" + +#: ../../extending/embedding.rst:294 +msgid "" +"It is also possible to embed Python in a C++ program; precisely how this is " +"done will depend on the details of the C++ system used; in general you will " +"need to write the main program in C++, and use the C++ compiler to compile " +"and link your program. There is no need to recompile Python itself using C+" +"+." +msgstr "" +"也可以將 Python 嵌入 C++ 程式中；具體如何做取決於所使用的 C++ 系統的細節；" +"一般來說，你需要用 C++ 撰寫主程式，並使用 C++ 編譯器來編譯和連結你的程式。" +"不需要使用 C++ 重新編譯 Python 本身。" + +#: ../../extending/embedding.rst:303 +msgid "Compiling and Linking under Unix-like systems" +msgstr "在類 Unix 系統下編譯和連結" + +#: ../../extending/embedding.rst:305 +msgid "" +"It is not necessarily trivial to find the right flags to pass to your " +"compiler (and linker) in order to embed the Python interpreter into your " +"application, particularly because Python needs to load library modules " +"implemented as C dynamic extensions (:file:`.so` files) linked against it." +msgstr "" +"要找到傳遞給編譯器（和連結器）的正確旗標以便將 Python 直譯器嵌入你的應用程式" +"中，並不一定是簡單的事，特別是因為 Python 需要載入作為 C 動態擴充（:file:`.so` 檔案）實作的函式庫" +"模組，而這些模組又必須與 Python 進行連結。" + +#: ../../extending/embedding.rst:311 +msgid "" +"To find out the required compiler and linker flags, you can execute the :" +"file:`python{X.Y}-config` script which is generated as part of the " +"installation process (a :file:`python3-config` script may also be " +"available). This script has several options, of which the following will be " +"directly useful to you:" +msgstr "" +"要找出所需的編譯器和連結器旗標，你可以執行作為安裝過程的一部分產生的 :file:" +"`python{X.Y}-config` 腳本（也可能有 :file:`python3-config` 腳本可用）。此腳本" +"提供多種選項，其中以下幾個最為實用：" + +#: ../../extending/embedding.rst:317 +msgid "" +"``pythonX.Y-config --cflags`` will give you the recommended flags when " +"compiling:" +msgstr "``pythonX.Y-config --cflags`` 會給你編譯時建議的旗標：" + +#: ../../extending/embedding.rst:320 +msgid "" +"$ /opt/bin/python3.11-config --cflags\n" +"-I/opt/include/python3.11 -I/opt/include/python3.11 -Wsign-compare -DNDEBUG " +"-g -fwrapv -O3 -Wall" +msgstr "" +"$ /opt/bin/python3.11-config --cflags\n" +"-I/opt/include/python3.11 -I/opt/include/python3.11 -Wsign-compare -DNDEBUG " +"-g -fwrapv -O3 -Wall" + +#: ../../extending/embedding.rst:325 +msgid "" +"``pythonX.Y-config --ldflags --embed`` will give you the recommended flags " +"when linking:" +msgstr "``pythonX.Y-config --ldflags --embed`` 會給你連結時建議的旗標：" + +#: ../../extending/embedding.rst:328 +msgid "" +"$ /opt/bin/python3.11-config --ldflags --embed\n" +"-L/opt/lib/python3.11/config-3.11-x86_64-linux-gnu -L/opt/lib -lpython3.11 -" +"lpthread -ldl -lutil -lm" +msgstr "" +"$ /opt/bin/python3.11-config --ldflags --embed\n" +"-L/opt/lib/python3.11/config-3.11-x86_64-linux-gnu -L/opt/lib -lpython3.11 -" +"lpthread -ldl -lutil -lm" + +#: ../../extending/embedding.rst:334 +msgid "" +"To avoid confusion between several Python installations (and especially " +"between the system Python and your own compiled Python), it is recommended " +"that you use the absolute path to :file:`python{X.Y}-config`, as in the " +"above example." +msgstr "" +"為了避免多個 Python 安裝之間產生混淆（特別是系統自帶的 Python 與自行編譯的 Python " +"之間），建議使用 :file:`python{X.Y}-config` 的絕對路徑，如上面的例子所示。" + +#: ../../extending/embedding.rst:339 +msgid "" +"If this procedure doesn't work for you (it is not guaranteed to work for all " +"Unix-like platforms; however, we welcome :ref:`bug reports `) you will have to read your system's documentation about dynamic " +"linking and/or examine Python's :file:`Makefile` (use :func:`sysconfig." +"get_makefile_filename` to find its location) and compilation options. In " +"this case, the :mod:`sysconfig` module is a useful tool to programmatically " +"extract the configuration values that you will want to combine together. " +"For example:" +msgstr "" +"如果此程序對你不起作用（並不保證在所有類 Unix 平台上都能運作；不過我們歡迎\\ :ref:" +"`錯誤回報 `），你將需要參閱系統的動態連結相關文件，並／或檢查 " +"Python 的 :file:`Makefile`\\ （可使用 :func:`sysconfig.get_makefile_filename` 來" +"找到其位置）和編譯選項。在這種情況下，:mod:`sysconfig` 模組是一個實用的工具，" +"可用於以程式化方式擷取並組合所需的組態值。例如：" + +#: ../../extending/embedding.rst:348 +msgid "" +">>> import sysconfig\n" +">>> sysconfig.get_config_var('LIBS')\n" +"'-lpthread -ldl -lutil'\n" +">>> sysconfig.get_config_var('LINKFORSHARED')\n" +"'-Xlinker -export-dynamic'" +msgstr "" +">>> import sysconfig\n" +">>> sysconfig.get_config_var('LIBS')\n" +"'-lpthread -ldl -lutil'\n" +">>> sysconfig.get_config_var('LINKFORSHARED')\n" +"'-Xlinker -export-dynamic'" diff --git a/extending/extending.po b/extending/extending.po index 154c37d898..a8723739c5 100644 --- a/extending/extending.po +++ b/extending/extending.po @@ -1,2305 +1,2305 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Leon H., 2017 -# Adrian Liaw , 2018 -# Matt Wang , 2025 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-25 00:13+0000\n" -"PO-Revision-Date: 2025-02-17 14:34+0000\n" -"Last-Translator: Matt Wang \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" - -#: ../../extending/extending.rst:8 -msgid "Extending Python with C or C++" -msgstr "以 C 或 C++ 擴充 Python" - -#: ../../extending/extending.rst:10 -msgid "" -"It is quite easy to add new built-in modules to Python, if you know how to " -"program in C. Such :dfn:`extension modules` can do two things that can't be " -"done directly in Python: they can implement new built-in object types, and " -"they can call C library functions and system calls." -msgstr "" -"如果你會撰寫 C 程式語言，那要向 Python 新增內建模組就不困難。這種\\ :dfn:`擴" -"充模組 (extension modules)` 可以做兩件在 Python 中無法直接完成的事：它們可以" -"實作新的內建物件型別，並且可以呼叫 C 的函式庫函式和系統呼叫。" - -#: ../../extending/extending.rst:15 -msgid "" -"To support extensions, the Python API (Application Programmers Interface) " -"defines a set of functions, macros and variables that provide access to most " -"aspects of the Python run-time system. The Python API is incorporated in a " -"C source file by including the header ``\"Python.h\"``." -msgstr "" -"為了支援擴充，Python API (Application Programmers Interface) 定義了一組函式、" -"巨集和變數，提供對 Python run-time 系統大部分面向的存取。Python API 是透過引" -"入標頭檔 ``\"Python.h\"`` 來被納入到一個 C 原始碼檔案中。" - -#: ../../extending/extending.rst:20 -msgid "" -"The compilation of an extension module depends on its intended use as well " -"as on your system setup; details are given in later chapters." -msgstr "" -"擴充模組的編譯取決於其預期用途以及你的系統設定；詳細資訊將在後面的章節中提" -"供。" - -#: ../../extending/extending.rst:25 -msgid "" -"The C extension interface is specific to CPython, and extension modules do " -"not work on other Python implementations. In many cases, it is possible to " -"avoid writing C extensions and preserve portability to other " -"implementations. For example, if your use case is calling C library " -"functions or system calls, you should consider using the :mod:`ctypes` " -"module or the `cffi `_ library rather than " -"writing custom C code. These modules let you write Python code to interface " -"with C code and are more portable between implementations of Python than " -"writing and compiling a C extension module." -msgstr "" -"C 擴充介面是 CPython 所特有的，擴充模組在其他 Python 實作上無法運作。在許多情" -"況下，可以避免撰寫 C 擴充並保留對其他實作的可移植性。例如，如果你的用例是呼" -"叫 C 函式庫函式或系統呼叫，你應該考慮使用 :mod:`ctypes` 模組或 `cffi " -"`_ 函式庫，而不是編寫自訂的 C 程式碼。這些模" -"組讓你可以撰寫 Python 程式碼來與 C 程式碼介接，而且比起撰寫和編譯 C 擴充模" -"組，這些模組在 Python 實作之間更容易移植。" - -#: ../../extending/extending.rst:40 -msgid "A Simple Example" -msgstr "一個簡單範例" - -#: ../../extending/extending.rst:42 -msgid "" -"Let's create an extension module called ``spam`` (the favorite food of Monty " -"Python fans...) and let's say we want to create a Python interface to the C " -"library function :c:func:`system` [#]_. This function takes a null-" -"terminated character string as argument and returns an integer. We want " -"this function to be callable from Python as follows:" -msgstr "" -"讓我們來建立一個叫做 ``spam``\\ （Monty Python 粉絲最愛的食物...）的擴充模" -"組。假設我們要建立一個 Python 介面給 C 函式庫的函式 :c:func:`system` [#]_ 使" -"用，這個函式接受一個以 null 終止的 (null-terminated) 字元字串做為引數，並回傳" -"一個整數。我們希望這個函式可以在 Python 中被呼叫，如下所示：" - -#: ../../extending/extending.rst:48 -msgid "" -">>> import spam\n" -">>> status = spam.system(\"ls -l\")" -msgstr "" -">>> import spam\n" -">>> status = spam.system(\"ls -l\")" - -#: ../../extending/extending.rst:53 -msgid "" -"Begin by creating a file :file:`spammodule.c`. (Historically, if a module " -"is called ``spam``, the C file containing its implementation is called :file:" -"`spammodule.c`; if the module name is very long, like ``spammify``, the " -"module name can be just :file:`spammify.c`.)" -msgstr "" -"首先建立一個檔案 :file:`spammodule.c`。（從過去歷史來看，如果一個模組叫做 " -"``spam``，包含其實作的 C 檔案就會叫做 :file:`spammodule.c`；如果模組名稱很" -"長，像是 ``spammify``，模組名稱也可以只是 :file:`spammify.c`）。" - -#: ../../extending/extending.rst:58 -msgid "The first two lines of our file can be::" -msgstr "我們檔案的前兩列可以為： ::" - -#: ../../extending/extending.rst:60 ../../extending/extending.rst:706 -msgid "" -"#define PY_SSIZE_T_CLEAN\n" -"#include " -msgstr "" -"#define PY_SSIZE_T_CLEAN\n" -"#include " - -#: ../../extending/extending.rst:63 -msgid "" -"which pulls in the Python API (you can add a comment describing the purpose " -"of the module and a copyright notice if you like)." -msgstr "" -"這會將 Python API 拉進來（你可以加入註解來說明模組的目的，也可以加入版權聲" -"明)。" - -#: ../../extending/extending.rst:68 -msgid "" -"Since Python may define some pre-processor definitions which affect the " -"standard headers on some systems, you *must* include :file:`Python.h` before " -"any standard headers are included." -msgstr "" -"由於 Python 可能定義一些影響系統上某些標準標頭檔的預處理器定義，你\\ *必須" -"*\\ 在引入任何標準標頭檔之前引入 :file:`Python.h`。" - -#: ../../extending/extending.rst:72 -msgid "" -"``#define PY_SSIZE_T_CLEAN`` was used to indicate that ``Py_ssize_t`` should " -"be used in some APIs instead of ``int``. It is not necessary since Python " -"3.13, but we keep it here for backward compatibility. See :ref:`arg-parsing-" -"string-and-buffers` for a description of this macro." -msgstr "" -"``#define PY_SSIZE_T_CLEAN`` 被用來表示在某些 API 中應該使用 ``Py_ssize_t`` " -"而不是 ``int``。自 Python 3.13 起，它就不再是必要的了，但我們在此保留它以便向" -"後相容。關於這個巨集的描述請參閱 :ref:`arg-parsing-string-and-buffers`。" - -#: ../../extending/extending.rst:77 -msgid "" -"All user-visible symbols defined by :file:`Python.h` have a prefix of ``Py`` " -"or ``PY``, except those defined in standard header files." -msgstr "" - -#: ../../extending/extending.rst:82 -msgid "" -"For backward compatibility, :file:`Python.h` includes several standard " -"header files. C extensions should include the standard headers that they " -"use, and should not rely on these implicit includes. If using the limited C " -"API version 3.13 or newer, the implicit includes are:" -msgstr "" - -#: ../../extending/extending.rst:87 -msgid "````" -msgstr "````" - -#: ../../extending/extending.rst:88 -msgid "```` (on Windows)" -msgstr "````\\ （在 Windows 上）" - -#: ../../extending/extending.rst:89 -msgid "````" -msgstr "````" - -#: ../../extending/extending.rst:90 -msgid "````" -msgstr "````" - -#: ../../extending/extending.rst:91 -msgid "````" -msgstr "````" - -#: ../../extending/extending.rst:92 -msgid "````" -msgstr "````" - -#: ../../extending/extending.rst:93 -msgid "````" -msgstr "````" - -#: ../../extending/extending.rst:94 -msgid "```` (if present)" -msgstr "````\\ （如果存在）" - -#: ../../extending/extending.rst:96 -msgid "" -"If :c:macro:`Py_LIMITED_API` is not defined, or is set to version 3.12 or " -"older, the headers below are also included:" -msgstr "" - -#: ../../extending/extending.rst:99 -msgid "````" -msgstr "````" - -#: ../../extending/extending.rst:100 -msgid "```` (on POSIX)" -msgstr "````\\ （在 POSIX 上）" - -#: ../../extending/extending.rst:102 -msgid "" -"If :c:macro:`Py_LIMITED_API` is not defined, or is set to version 3.10 or " -"older, the headers below are also included:" -msgstr "" - -#: ../../extending/extending.rst:105 -msgid "````" -msgstr "````" - -#: ../../extending/extending.rst:106 -msgid "````" -msgstr "````" - -#: ../../extending/extending.rst:107 -msgid "````" -msgstr "````" - -#: ../../extending/extending.rst:108 -msgid "````" -msgstr "````" - -#: ../../extending/extending.rst:110 -msgid "" -"The next thing we add to our module file is the C function that will be " -"called when the Python expression ``spam.system(string)`` is evaluated " -"(we'll see shortly how it ends up being called)::" -msgstr "" -"接下來我們要加入到模組檔案的是 C 函式，當 Python 運算式 ``spam." -"system(string)`` 要被求值 (evaluated) 時就會被呼叫（我們很快就會看到它最後是" -"如何被呼叫的）： ::" - -#: ../../extending/extending.rst:114 -msgid "" -"static PyObject *\n" -"spam_system(PyObject *self, PyObject *args)\n" -"{\n" -" const char *command;\n" -" int sts;\n" -"\n" -" if (!PyArg_ParseTuple(args, \"s\", &command))\n" -" return NULL;\n" -" sts = system(command);\n" -" return PyLong_FromLong(sts);\n" -"}" -msgstr "" -"static PyObject *\n" -"spam_system(PyObject *self, PyObject *args)\n" -"{\n" -" const char *command;\n" -" int sts;\n" -"\n" -" if (!PyArg_ParseTuple(args, \"s\", &command))\n" -" return NULL;\n" -" sts = system(command);\n" -" return PyLong_FromLong(sts);\n" -"}" - -#: ../../extending/extending.rst:126 -msgid "" -"There is a straightforward translation from the argument list in Python (for " -"example, the single expression ``\"ls -l\"``) to the arguments passed to the " -"C function. The C function always has two arguments, conventionally named " -"*self* and *args*." -msgstr "" -"可以很直觀地從 Python 的引數串列（例如單一的運算式 ``\"ls -l\"``）直接轉換成" -"傳給 C 函式的引數。C 函式總是有兩個引數，習慣上會命名為 *self* 和 *args*。" - -#: ../../extending/extending.rst:131 -msgid "" -"The *self* argument points to the module object for module-level functions; " -"for a method it would point to the object instance." -msgstr "" -"對於模組層級的函式，*self* 引數會指向模組物件；而對於方法來說則是指向物件的實" -"例。" - -#: ../../extending/extending.rst:134 -msgid "" -"The *args* argument will be a pointer to a Python tuple object containing " -"the arguments. Each item of the tuple corresponds to an argument in the " -"call's argument list. The arguments are Python objects --- in order to do " -"anything with them in our C function we have to convert them to C values. " -"The function :c:func:`PyArg_ParseTuple` in the Python API checks the " -"argument types and converts them to C values. It uses a template string to " -"determine the required types of the arguments as well as the types of the C " -"variables into which to store the converted values. More about this later." -msgstr "" -"*args* 引數會是一個指向包含引數的 Python 元組物件的指標。元組中的每一項都對應" -"於呼叫的引數串列中的一個引數。引數是 Python 物件 --- 為了在我們的 C 函式中對" -"它們做任何事情，我們必須先將它們轉換成 C 值。Python API 中的 :c:func:" -"`PyArg_ParseTuple` 函式能夠檢查引數型別並將他們轉換為 C 值。它使用模板字串來" -"決定所需的引數型別以及儲存轉換值的 C 變數型別。稍後會再詳細說明。" - -#: ../../extending/extending.rst:143 -msgid "" -":c:func:`PyArg_ParseTuple` returns true (nonzero) if all arguments have the " -"right type and its components have been stored in the variables whose " -"addresses are passed. It returns false (zero) if an invalid argument list " -"was passed. In the latter case it also raises an appropriate exception so " -"the calling function can return ``NULL`` immediately (as we saw in the " -"example)." -msgstr "" -"如果所有的引數都有正確的型別，且其元件已儲存在傳入位址的變數中，則 :c:func:" -"`PyArg_ParseTuple` 會回傳 true（非零）。如果傳入的是無效引數串列則回傳 false" -"（零）。在後者情況下，它也會產生適當的例外，因此呼叫函式可以立即回傳 " -"``NULL``\\ （就像我們在範例中所看到的）。" - -#: ../../extending/extending.rst:153 -msgid "Intermezzo: Errors and Exceptions" -msgstr "插曲：錯誤與例外" - -#: ../../extending/extending.rst:155 -msgid "" -"An important convention throughout the Python interpreter is the following: " -"when a function fails, it should set an exception condition and return an " -"error value (usually ``-1`` or a ``NULL`` pointer). Exception information " -"is stored in three members of the interpreter's thread state. These are " -"``NULL`` if there is no exception. Otherwise they are the C equivalents of " -"the members of the Python tuple returned by :meth:`sys.exc_info`. These are " -"the exception type, exception instance, and a traceback object. It is " -"important to know about them to understand how errors are passed around." -msgstr "" -"在整個 Python 直譯器中的一個重要慣例為：當一個函式失敗時，它就應該設定一個例" -"外條件，並回傳一個錯誤值（通常是 ``-1`` 或一個 ``NULL`` 指標）。例外資訊會儲" -"存在直譯器執行緒狀態的三個成員中。如果沒有例外，它們就會是 ``NULL``。否則，它" -"們是由 :meth:`sys.exc_info` 所回傳的 Python 元組中的 C 等效元組。它們是例外型" -"別、例外實例和回溯物件。了解它們對於理解錯誤是如何傳遞是很重要的。" - -#: ../../extending/extending.rst:164 -msgid "" -"The Python API defines a number of functions to set various types of " -"exceptions." -msgstr "Python API 定義了許多能夠設定各種類型例外的函式。" - -#: ../../extending/extending.rst:166 -msgid "" -"The most common one is :c:func:`PyErr_SetString`. Its arguments are an " -"exception object and a C string. The exception object is usually a " -"predefined object like :c:data:`PyExc_ZeroDivisionError`. The C string " -"indicates the cause of the error and is converted to a Python string object " -"and stored as the \"associated value\" of the exception." -msgstr "" -"最常見的是 :c:func:`PyErr_SetString`。它的引數是一個例外物件和一個 C 字串。例" -"外物件通常是預先定義的物件，例如 :c:data:`PyExc_ZeroDivisionError`。C 字串則" -"指出錯誤的原因，並被轉換為 Python 字串物件且被儲存為例外的「關聯值 " -"(associated value)」。" - -#: ../../extending/extending.rst:172 -msgid "" -"Another useful function is :c:func:`PyErr_SetFromErrno`, which only takes an " -"exception argument and constructs the associated value by inspection of the " -"global variable :c:data:`errno`. The most general function is :c:func:" -"`PyErr_SetObject`, which takes two object arguments, the exception and its " -"associated value. You don't need to :c:func:`Py_INCREF` the objects passed " -"to any of these functions." -msgstr "" -"另一個有用的函式是 :c:func:`PyErr_SetFromErrno`，它只接受一個例外引數，並透過" -"檢查全域變數 :c:data:`errno` 來建立關聯值。最一般的函式是 :c:func:" -"`PyErr_SetObject`，它接受兩個物件引數，即例外和它的關聯值。你不需要對傳給任何" -"這些函式的物件呼叫 :c:func:`Py_INCREF`。" - -#: ../../extending/extending.rst:179 -msgid "" -"You can test non-destructively whether an exception has been set with :c:" -"func:`PyErr_Occurred`. This returns the current exception object, or " -"``NULL`` if no exception has occurred. You normally don't need to call :c:" -"func:`PyErr_Occurred` to see whether an error occurred in a function call, " -"since you should be able to tell from the return value." -msgstr "" -"你可以使用 :c:func:`PyErr_Occurred` 來不具破壞性地測試例外是否已被設定。這會" -"回傳目前的例外物件，如果沒有例外發生則回傳 ``NULL``。你通常不需要呼叫 :c:" -"func:`PyErr_Occurred` 來查看函式呼叫是否發生錯誤，因為你應可從回傳值就得知。" - -#: ../../extending/extending.rst:185 -msgid "" -"When a function *f* that calls another function *g* detects that the latter " -"fails, *f* should itself return an error value (usually ``NULL`` or " -"``-1``). It should *not* call one of the ``PyErr_*`` functions --- one has " -"already been called by *g*. *f*'s caller is then supposed to also return an " -"error indication to *its* caller, again *without* calling ``PyErr_*``, and " -"so on --- the most detailed cause of the error was already reported by the " -"function that first detected it. Once the error reaches the Python " -"interpreter's main loop, this aborts the currently executing Python code and " -"tries to find an exception handler specified by the Python programmer." -msgstr "" -"當函式 *f* 呼叫另一個函式 *g* 時檢測到後者失敗，*f* 本身應該回傳一個錯誤值" -"（通常是 ``NULL`` 或 ``-1``）。它\\ *不*\\ 應該呼叫 ``PyErr_*`` 函式的其中一" -"個，這會已被 *g* 呼叫過。*f* 的呼叫者然後也應該回傳一個錯誤指示給\\ *它的*\\ " -"呼叫者，同樣\\ *不會*\\ 呼叫 ``PyErr_*``，依此類推 --- 最詳細的錯誤原因已經被" -"首先檢測到它的函式回報了。一旦錯誤到達 Python 直譯器的主要迴圈，這會中止目前" -"執行的 Python 程式碼，並嘗試尋找 Python 程式設計者指定的例外處理程式。" - -#: ../../extending/extending.rst:195 -msgid "" -"(There are situations where a module can actually give a more detailed error " -"message by calling another ``PyErr_*`` function, and in such cases it is " -"fine to do so. As a general rule, however, this is not necessary, and can " -"cause information about the cause of the error to be lost: most operations " -"can fail for a variety of reasons.)" -msgstr "" -"（在某些情況下，模組可以透過呼叫另一個 ``PyErr_*`` 函式來提供更詳細的錯誤訊" -"息，在這種情況下這樣做是沒問題的。然而這一般來說並非必要，而且可能會導致錯誤" -"原因資訊的遺失：大多數的操作都可能因為各種原因而失敗。）" - -#: ../../extending/extending.rst:201 -msgid "" -"To ignore an exception set by a function call that failed, the exception " -"condition must be cleared explicitly by calling :c:func:`PyErr_Clear`. The " -"only time C code should call :c:func:`PyErr_Clear` is if it doesn't want to " -"pass the error on to the interpreter but wants to handle it completely by " -"itself (possibly by trying something else, or pretending nothing went wrong)." -msgstr "" -"要忽略由函式呼叫失敗所設定的例外，必須明確地呼叫 :c:func:`PyErr_Clear` 來清除" -"例外條件。C 程式碼唯一要呼叫 :c:func:`PyErr_Clear` 的情況為當它不想將錯誤傳遞" -"給直譯器而想要完全是自己來處理它時（可能是要再嘗試其他東西，或者假裝什麼都沒" -"出錯）。" - -#: ../../extending/extending.rst:207 -msgid "" -"Every failing :c:func:`malloc` call must be turned into an exception --- the " -"direct caller of :c:func:`malloc` (or :c:func:`realloc`) must call :c:func:" -"`PyErr_NoMemory` and return a failure indicator itself. All the object-" -"creating functions (for example, :c:func:`PyLong_FromLong`) already do this, " -"so this note is only relevant to those who call :c:func:`malloc` directly." -msgstr "" -"每個失敗的 :c:func:`malloc` 呼叫都必須被轉換成一個例外 --- :c:func:" -"`malloc`\\ （或 :c:func:`realloc`）的直接呼叫者必須呼叫 :c:func:" -"`PyErr_NoMemory` 並回傳一個失敗指示器。所有建立物件的函式（例如 :c:func:" -"`PyLong_FromLong`）都已經這麼做了，所以這個注意事項只和那些直接呼叫 :c:func:" -"`malloc` 的函式有關。" - -#: ../../extending/extending.rst:213 -msgid "" -"Also note that, with the important exception of :c:func:`PyArg_ParseTuple` " -"and friends, functions that return an integer status usually return a " -"positive value or zero for success and ``-1`` for failure, like Unix system " -"calls." -msgstr "" -"還要注意的是，有 :c:func:`PyArg_ParseTuple` 及同系列函式的這些重要例外，回傳" -"整數狀態的函式通常會回傳一個正值或 0 表示成功、回傳 ``-1`` 表示失敗，就像 " -"Unix 系統呼叫一樣。" - -#: ../../extending/extending.rst:217 -msgid "" -"Finally, be careful to clean up garbage (by making :c:func:`Py_XDECREF` or :" -"c:func:`Py_DECREF` calls for objects you have already created) when you " -"return an error indicator!" -msgstr "" -"最後，在回傳錯誤指示器時要注意垃圾清理（透過對你已經建立的物件呼叫 :c:func:" -"`Py_XDECREF` 或 :c:func:`Py_DECREF`）！" - -#: ../../extending/extending.rst:221 -msgid "" -"The choice of which exception to raise is entirely yours. There are " -"predeclared C objects corresponding to all built-in Python exceptions, such " -"as :c:data:`PyExc_ZeroDivisionError`, which you can use directly. Of course, " -"you should choose exceptions wisely --- don't use :c:data:`PyExc_TypeError` " -"to mean that a file couldn't be opened (that should probably be :c:data:" -"`PyExc_OSError`). If something's wrong with the argument list, the :c:func:" -"`PyArg_ParseTuple` function usually raises :c:data:`PyExc_TypeError`. If " -"you have an argument whose value must be in a particular range or must " -"satisfy other conditions, :c:data:`PyExc_ValueError` is appropriate." -msgstr "" -"你完全可以自行選擇要產生的例外。有一些預先宣告的 C 物件會對應到所有內建的 " -"Python 例外，例如 :c:data:`PyExc_ZeroDivisionError`，你可以直接使用它們。當" -"然，你應該明智地選擇例外，像是不要使用 :c:data:`PyExc_TypeError` 來表示檔案無" -"法打開（應該是 :c:data:`PyExc_OSError`）。如果引數串列有問題，:c:func:" -"`PyArg_ParseTuple` 函式通常會引發 :c:data:`PyExc_TypeError`。如果你有一個引數" -"的值必須在一個特定的範圍內或必須滿足其他條件，則可以使用 :c:data:" -"`PyExc_ValueError`。" - -#: ../../extending/extending.rst:231 -msgid "" -"You can also define a new exception that is unique to your module. The " -"simplest way to do this is to declare a static global object variable at the " -"beginning of the file::" -msgstr "" -"你也可以定義一個你的模組特有的新例外。最簡單的方式是在檔案的開頭宣告一個靜態" -"全域物件變數： ::" - -#: ../../extending/extending.rst:235 -msgid "static PyObject *SpamError = NULL;" -msgstr "static PyObject *SpamError = NULL;" - -#: ../../extending/extending.rst:237 -msgid "" -"and initialize it by calling :c:func:`PyErr_NewException` in the module's :c:" -"data:`Py_mod_exec` function (:c:func:`!spam_module_exec`)::" -msgstr "" - -#: ../../extending/extending.rst:240 -msgid "SpamError = PyErr_NewException(\"spam.error\", NULL, NULL);" -msgstr "" - -#: ../../extending/extending.rst:242 -msgid "" -"Since :c:data:`!SpamError` is a global variable, it will be overwritten " -"every time the module is reinitialized, when the :c:data:`Py_mod_exec` " -"function is called." -msgstr "" - -#: ../../extending/extending.rst:245 -msgid "" -"For now, let's avoid the issue: we will block repeated initialization by " -"raising an :py:exc:`ImportError`::" -msgstr "" - -#: ../../extending/extending.rst:248 -msgid "" -"static PyObject *SpamError = NULL;\n" -"\n" -"static int\n" -"spam_module_exec(PyObject *m)\n" -"{\n" -" if (SpamError != NULL) {\n" -" PyErr_SetString(PyExc_ImportError,\n" -" \"cannot initialize spam module more than once\");\n" -" return -1;\n" -" }\n" -" SpamError = PyErr_NewException(\"spam.error\", NULL, NULL);\n" -" if (PyModule_AddObjectRef(m, \"SpamError\", SpamError) < 0) {\n" -" return -1;\n" -" }\n" -"\n" -" return 0;\n" -"}\n" -"\n" -"static PyModuleDef_Slot spam_module_slots[] = {\n" -" {Py_mod_exec, spam_module_exec},\n" -" {0, NULL}\n" -"};\n" -"\n" -"static struct PyModuleDef spam_module = {\n" -" .m_base = PyModuleDef_HEAD_INIT,\n" -" .m_name = \"spam\",\n" -" .m_size = 0, // non-negative\n" -" .m_slots = spam_module_slots,\n" -"};\n" -"\n" -"PyMODINIT_FUNC\n" -"PyInit_spam(void)\n" -"{\n" -" return PyModuleDef_Init(&spam_module);\n" -"}" -msgstr "" - -#: ../../extending/extending.rst:284 -msgid "" -"Note that the Python name for the exception object is :exc:`!spam.error`. " -"The :c:func:`PyErr_NewException` function may create a class with the base " -"class being :exc:`Exception` (unless another class is passed in instead of " -"``NULL``), described in :ref:`bltin-exceptions`." -msgstr "" -"請注意，例外物件的 Python 名稱是 :exc:`!spam.error`。如同\\ :ref:`bltin-" -"exceptions`\\ 所述，:c:func:`PyErr_NewException` 函式可能會建立一個基底類別" -"為 :exc:`Exception` 的類別（除非傳入另一個類別來代替 ``NULL``）。" - -#: ../../extending/extending.rst:289 -msgid "" -"Note also that the :c:data:`!SpamError` variable retains a reference to the " -"newly created exception class; this is intentional! Since the exception " -"could be removed from the module by external code, an owned reference to the " -"class is needed to ensure that it will not be discarded, causing :c:data:`!" -"SpamError` to become a dangling pointer. Should it become a dangling " -"pointer, C code which raises the exception could cause a core dump or other " -"unintended side effects." -msgstr "" -"請注意，:c:data:`!SpamError` 變數保留了對新建立的例外類別的參照；這是故意的！" -"因為外部程式碼可能會從模組中移除這個例外，所以需要一個對這個類別的參照來確保" -"它不會被丟棄而導致 :c:data:`!SpamError` 變成一個迷途指標 (dangling pointer)。" -"如果它變成迷途指標，那產生例外的 C 程式碼可能會導致核心轉儲 (core dump) 或其" -"他不預期的 side effect。" - -#: ../../extending/extending.rst:296 -msgid "" -"For now, the :c:func:`Py_DECREF` call to remove this reference is missing. " -"Even when the Python interpreter shuts down, the global :c:data:`!SpamError` " -"variable will not be garbage-collected. It will \"leak\". We did, however, " -"ensure that this will happen at most once per process." -msgstr "" - -#: ../../extending/extending.rst:301 -msgid "" -"We discuss the use of :c:macro:`PyMODINIT_FUNC` as a function return type " -"later in this sample." -msgstr "我們稍後會討論 :c:macro:`PyMODINIT_FUNC` 作為函式回傳型別的用法。" - -#: ../../extending/extending.rst:304 -msgid "" -"The :exc:`!spam.error` exception can be raised in your extension module " -"using a call to :c:func:`PyErr_SetString` as shown below::" -msgstr "" -"可以在你的擴充模組中呼叫 :c:func:`PyErr_SetString` 來引發 :exc:`!spam.error` " -"例外，如下所示： ::" - -#: ../../extending/extending.rst:307 -msgid "" -"static PyObject *\n" -"spam_system(PyObject *self, PyObject *args)\n" -"{\n" -" const char *command;\n" -" int sts;\n" -"\n" -" if (!PyArg_ParseTuple(args, \"s\", &command))\n" -" return NULL;\n" -" sts = system(command);\n" -" if (sts < 0) {\n" -" PyErr_SetString(SpamError, \"System command failed\");\n" -" return NULL;\n" -" }\n" -" return PyLong_FromLong(sts);\n" -"}" -msgstr "" -"static PyObject *\n" -"spam_system(PyObject *self, PyObject *args)\n" -"{\n" -" const char *command;\n" -" int sts;\n" -"\n" -" if (!PyArg_ParseTuple(args, \"s\", &command))\n" -" return NULL;\n" -" sts = system(command);\n" -" if (sts < 0) {\n" -" PyErr_SetString(SpamError, \"System command failed\");\n" -" return NULL;\n" -" }\n" -" return PyLong_FromLong(sts);\n" -"}" - -#: ../../extending/extending.rst:327 -msgid "Back to the Example" -msgstr "回到範例" - -#: ../../extending/extending.rst:329 -msgid "" -"Going back to our example function, you should now be able to understand " -"this statement::" -msgstr "回到我們的範例函式，現在你應該可以理解這個陳述式了： ::" - -#: ../../extending/extending.rst:332 -msgid "" -"if (!PyArg_ParseTuple(args, \"s\", &command))\n" -" return NULL;" -msgstr "" -"if (!PyArg_ParseTuple(args, \"s\", &command))\n" -" return NULL;" - -#: ../../extending/extending.rst:335 -msgid "" -"It returns ``NULL`` (the error indicator for functions returning object " -"pointers) if an error is detected in the argument list, relying on the " -"exception set by :c:func:`PyArg_ParseTuple`. Otherwise the string value of " -"the argument has been copied to the local variable :c:data:`!command`. This " -"is a pointer assignment and you are not supposed to modify the string to " -"which it points (so in Standard C, the variable :c:data:`!command` should " -"properly be declared as ``const char *command``)." -msgstr "" -"如果在引數串列中檢測到錯誤則會回傳 ``NULL``\\ （回傳物件指標之函式的錯誤指示" -"器），其依賴於 :c:func:`PyArg_ParseTuple` 設定的例外，否則引數的字串值會已被" -"複製到區域變數 :c:data:`!command` 中。這是一個指標賦值，你不應該修改它所指向" -"的字串（所以在標準 C 中，:c:data:`!command` 變數應該正確地被宣告為 ``const " -"char *command``）。" - -#: ../../extending/extending.rst:343 -msgid "" -"The next statement is a call to the Unix function :c:func:`system`, passing " -"it the string we just got from :c:func:`PyArg_ParseTuple`::" -msgstr "" -"接下來的陳述式會呼叫 Unix 函式 :c:func:`system`，並將剛才從 :c:func:" -"`PyArg_ParseTuple` 得到的字串傳給它：" - -#: ../../extending/extending.rst:346 -msgid "sts = system(command);" -msgstr "sts = system(command);" - -#: ../../extending/extending.rst:348 -msgid "" -"Our :func:`!spam.system` function must return the value of :c:data:`!sts` as " -"a Python object. This is done using the function :c:func:" -"`PyLong_FromLong`. ::" -msgstr "" -"我們的 :func:`!spam.system` 函式必須以 Python 物件的形式來回傳 :c:data:`!" -"sts` 的值。這是透過 :c:func:`PyLong_FromLong` 函式來達成。 ::" - -#: ../../extending/extending.rst:351 -msgid "return PyLong_FromLong(sts);" -msgstr "return PyLong_FromLong(sts);" - -#: ../../extending/extending.rst:353 -msgid "" -"In this case, it will return an integer object. (Yes, even integers are " -"objects on the heap in Python!)" -msgstr "" -"在這種情況下它會回傳一個整數物件。(是的，在 Python 中連整數也是堆積 (heap) 上" -"的物件！)" - -#: ../../extending/extending.rst:356 -msgid "" -"If you have a C function that returns no useful argument (a function " -"returning :c:expr:`void`), the corresponding Python function must return " -"``None``. You need this idiom to do so (which is implemented by the :c:" -"macro:`Py_RETURN_NONE` macro)::" -msgstr "" -"如果你有一個不回傳任何有用引數的 C 函式（一個回傳 :c:expr:`void` 的函式），對" -"應的 Python 函式必須回傳 ``None``。你需要以下這個慣例來達成（由 :c:macro:" -"`Py_RETURN_NONE` 巨集實作）： ::" - -#: ../../extending/extending.rst:361 -msgid "" -"Py_INCREF(Py_None);\n" -"return Py_None;" -msgstr "" -"Py_INCREF(Py_None);\n" -"return Py_None;" - -#: ../../extending/extending.rst:364 -msgid "" -":c:data:`Py_None` is the C name for the special Python object ``None``. It " -"is a genuine Python object rather than a ``NULL`` pointer, which means " -"\"error\" in most contexts, as we have seen." -msgstr "" -":c:data:`Py_None` 是特殊 Python 物件 ``None`` 的 C 名稱。它是一個真正的 " -"Python 物件而不是一個 ``NULL`` 指標，在大多數的情況下它的意思是「錯誤」，如我" -"們所見過的那樣。" - -#: ../../extending/extending.rst:372 -msgid "The Module's Method Table and Initialization Function" -msgstr "模組的方法表和初始化函式" - -#: ../../extending/extending.rst:374 -msgid "" -"I promised to show how :c:func:`!spam_system` is called from Python " -"programs. First, we need to list its name and address in a \"method table\"::" -msgstr "" -"我承諾過要展示 :c:func:`!spam_system` 是如何從 Python 程式中呼叫的。首先，我" -"們需要在「方法表」中列出它的名稱和位址： ::" - -#: ../../extending/extending.rst:377 -msgid "" -"static PyMethodDef spam_methods[] = {\n" -" ...\n" -" {\"system\", spam_system, METH_VARARGS,\n" -" \"Execute a shell command.\"},\n" -" ...\n" -" {NULL, NULL, 0, NULL} /* Sentinel */\n" -"};" -msgstr "" -"static PyMethodDef spam_methods[] = {\n" -" ...\n" -" {\"system\", spam_system, METH_VARARGS,\n" -" \"Execute a shell command.\"},\n" -" ...\n" -" {NULL, NULL, 0, NULL} /* Sentinel */\n" -"};" - -#: ../../extending/extending.rst:385 -msgid "" -"Note the third entry (``METH_VARARGS``). This is a flag telling the " -"interpreter the calling convention to be used for the C function. It should " -"normally always be ``METH_VARARGS`` or ``METH_VARARGS | METH_KEYWORDS``; a " -"value of ``0`` means that an obsolete variant of :c:func:`PyArg_ParseTuple` " -"is used." -msgstr "" -"請注意第三個項目 (``METH_VARARGS``)。這是一個告訴直譯器 C 函式之呼叫方式的旗" -"標。通常應該是 ``METH_VARARGS`` 或 ``METH_VARARGS | METH_KEYWORDS``；``0`` 表" -"示是使用 :c:func:`PyArg_ParseTuple` 的一個過時變體。" - -#: ../../extending/extending.rst:390 -msgid "" -"When using only ``METH_VARARGS``, the function should expect the Python-" -"level parameters to be passed in as a tuple acceptable for parsing via :c:" -"func:`PyArg_ParseTuple`; more information on this function is provided below." -msgstr "" -"當只使用 ``METH_VARARGS`` 時，函式應預期 Python 層級的參數是以元組形式傳入且" -"能夠接受以 :c:func:`PyArg_ParseTuple` 進行剖析；有關此函式的更多資訊將在下面" -"提供。" - -#: ../../extending/extending.rst:394 -msgid "" -"The :c:macro:`METH_KEYWORDS` bit may be set in the third field if keyword " -"arguments should be passed to the function. In this case, the C function " -"should accept a third ``PyObject *`` parameter which will be a dictionary of " -"keywords. Use :c:func:`PyArg_ParseTupleAndKeywords` to parse the arguments " -"to such a function." -msgstr "" -"如果要將關鍵字引數傳給函式，可以在第三個欄位設定 :c:macro:`METH_KEYWORDS` 位" -"元。在這種情況下，C 函式應該要能接受第三個 ``PyObject *`` 參數，這個參數將會" -"是關鍵字的字典。可使用 :c:func:`PyArg_ParseTupleAndKeywords` 來剖析這種函式的" -"引數。" - -#: ../../extending/extending.rst:400 -msgid "" -"The method table must be referenced in the module definition structure::" -msgstr "方法表必須在模組定義結構中被參照： ::" - -#: ../../extending/extending.rst:402 -msgid "" -"static struct PyModuleDef spam_module = {\n" -" ...\n" -" .m_methods = spam_methods,\n" -" ...\n" -"};" -msgstr "" - -#: ../../extending/extending.rst:408 -msgid "" -"This structure, in turn, must be passed to the interpreter in the module's " -"initialization function. The initialization function must be named :c:func:" -"`!PyInit_name`, where *name* is the name of the module, and should be the " -"only non-\\ ``static`` item defined in the module file::" -msgstr "" -"反過來說，這個結構必須在模組的初始化函式中被傳給直譯器。初始化函式必須被命名" -"為 :c:func:`!PyInit_name`，其中 *name* 是模組的名稱，且應該是模組檔案中唯一定" -"義的非「靜態 (``static``)」項目： ::" - -#: ../../extending/extending.rst:413 -msgid "" -"PyMODINIT_FUNC\n" -"PyInit_spam(void)\n" -"{\n" -" return PyModuleDef_Init(&spam_module);\n" -"}" -msgstr "" -"PyMODINIT_FUNC\n" -"PyInit_spam(void)\n" -"{\n" -" return PyModuleDef_Init(&spam_module);\n" -"}" - -#: ../../extending/extending.rst:419 -msgid "" -"Note that :c:macro:`PyMODINIT_FUNC` declares the function as ``PyObject *`` " -"return type, declares any special linkage declarations required by the " -"platform, and for C++ declares the function as ``extern \"C\"``." -msgstr "" -"請注意，:c:macro:`PyMODINIT_FUNC` 宣告函式的回傳型別為 ``PyObject *``、宣告平" -"台所需的任何特殊連結宣告、並針對 C++ 宣告函式為 ``extern \"C\"``。" - -#: ../../extending/extending.rst:423 -msgid "" -":c:func:`!PyInit_spam` is called when each interpreter imports its module :" -"mod:`!spam` for the first time. (See below for comments about embedding " -"Python.) A pointer to the module definition must be returned via :c:func:" -"`PyModuleDef_Init`, so that the import machinery can create the module and " -"store it in ``sys.modules``." -msgstr "" - -#: ../../extending/extending.rst:428 -msgid "" -"When embedding Python, the :c:func:`!PyInit_spam` function is not called " -"automatically unless there's an entry in the :c:data:`PyImport_Inittab` " -"table. To add the module to the initialization table, use :c:func:" -"`PyImport_AppendInittab`, optionally followed by an import of the module::" -msgstr "" -"嵌入 Python 時，除非在 :c:data:`PyImport_Inittab` 表中有相關條目，否則不會自" -"動呼叫 :c:func:`!PyInit_spam` 函式。要將模組加入初始化表，請使用 :c:func:" -"`PyImport_AppendInittab` 並在隨後選擇性地將該模組引入： ::" - -#: ../../extending/extending.rst:433 -msgid "" -"#define PY_SSIZE_T_CLEAN\n" -"#include \n" -"\n" -"int\n" -"main(int argc, char *argv[])\n" -"{\n" -" PyStatus status;\n" -" PyConfig config;\n" -" PyConfig_InitPythonConfig(&config);\n" -"\n" -" /* Add a built-in module, before Py_Initialize */\n" -" if (PyImport_AppendInittab(\"spam\", PyInit_spam) == -1) {\n" -" fprintf(stderr, \"Error: could not extend in-built modules " -"table\\n\");\n" -" exit(1);\n" -" }\n" -"\n" -" /* Pass argv[0] to the Python interpreter */\n" -" status = PyConfig_SetBytesString(&config, &config.program_name, " -"argv[0]);\n" -" if (PyStatus_Exception(status)) {\n" -" goto exception;\n" -" }\n" -"\n" -" /* Initialize the Python interpreter. Required.\n" -" If this step fails, it will be a fatal error. */\n" -" status = Py_InitializeFromConfig(&config);\n" -" if (PyStatus_Exception(status)) {\n" -" goto exception;\n" -" }\n" -" PyConfig_Clear(&config);\n" -"\n" -" /* Optionally import the module; alternatively,\n" -" import can be deferred until the embedded script\n" -" imports it. */\n" -" PyObject *pmodule = PyImport_ImportModule(\"spam\");\n" -" if (!pmodule) {\n" -" PyErr_Print();\n" -" fprintf(stderr, \"Error: could not import module 'spam'\\n\");\n" -" }\n" -"\n" -" // ... use Python C API here ...\n" -"\n" -" return 0;\n" -"\n" -" exception:\n" -" PyConfig_Clear(&config);\n" -" Py_ExitStatusException(status);\n" -"}" -msgstr "" -"#define PY_SSIZE_T_CLEAN\n" -"#include \n" -"\n" -"int\n" -"main(int argc, char *argv[])\n" -"{\n" -" PyStatus status;\n" -" PyConfig config;\n" -" PyConfig_InitPythonConfig(&config);\n" -"\n" -" /* 在 Py_Initialize 之前加入內建模組 */\n" -" if (PyImport_AppendInittab(\"spam\", PyInit_spam) == -1) {\n" -" fprintf(stderr, \"Error: could not extend in-built modules " -"table\\n\");\n" -" exit(1);\n" -" }\n" -"\n" -" /* 將 argv[0] 傳給 Python 直譯器 */\n" -" status = PyConfig_SetBytesString(&config, &config.program_name, " -"argv[0]);\n" -" if (PyStatus_Exception(status)) {\n" -" goto exception;\n" -" }\n" -"\n" -" /* 初始化 Python 直譯器。這會是必要的。\n" -" 如果此步驟失敗就會導致嚴重錯誤。*/\n" -" status = Py_InitializeFromConfig(&config);\n" -" if (PyStatus_Exception(status)) {\n" -" goto exception;\n" -" }\n" -" PyConfig_Clear(&config);\n" -"\n" -" /* 可選擇引入模組；或者\n" -" 可以延遲引入，直至嵌入式腳本\n" -" 將其引入。*/\n" -" PyObject *pmodule = PyImport_ImportModule(\"spam\");\n" -" if (!pmodule) {\n" -" PyErr_Print();\n" -" fprintf(stderr, \"Error: could not import module 'spam'\\n\");\n" -" }\n" -"\n" -" // ... 在此使用 Python C API ...\n" -"\n" -" return 0;\n" -"\n" -" exception:\n" -" PyConfig_Clear(&config);\n" -" Py_ExitStatusException(status);\n" -"}" - -#: ../../extending/extending.rst:483 -msgid "" -"If you declare a global variable or a local static one, the module may " -"experience unintended side-effects on re-initialisation, for example when " -"removing entries from ``sys.modules`` or importing compiled modules into " -"multiple interpreters within a process (or following a :c:func:`fork` " -"without an intervening :c:func:`exec`). If module state is not yet fully :" -"ref:`isolated `, authors should consider marking " -"the module as having no support for subinterpreters (via :c:macro:" -"`Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED`)." -msgstr "" - -#: ../../extending/extending.rst:492 -msgid "" -"A more substantial example module is included in the Python source " -"distribution as :file:`Modules/xxlimited.c`. This file may be used as a " -"template or simply read as an example." -msgstr "" -"Python 原始碼發行版本中包含了一個更實質的範例模組 :file:`Modules/xxlimited." -"c`。這個檔案可以當作模板使用，也可以簡單地當作範例來閱讀。" - -#: ../../extending/extending.rst:500 -msgid "Compilation and Linkage" -msgstr "" - -#: ../../extending/extending.rst:502 -msgid "" -"There are two more things to do before you can use your new extension: " -"compiling and linking it with the Python system. If you use dynamic " -"loading, the details may depend on the style of dynamic loading your system " -"uses; see the chapters about building extension modules (chapter :ref:" -"`building`) and additional information that pertains only to building on " -"Windows (chapter :ref:`building-on-windows`) for more information about this." -msgstr "" - -#: ../../extending/extending.rst:509 -msgid "" -"If you can't use dynamic loading, or if you want to make your module a " -"permanent part of the Python interpreter, you will have to change the " -"configuration setup and rebuild the interpreter. Luckily, this is very " -"simple on Unix: just place your file (:file:`spammodule.c` for example) in " -"the :file:`Modules/` directory of an unpacked source distribution, add a " -"line to the file :file:`Modules/Setup.local` describing your file:" -msgstr "" - -#: ../../extending/extending.rst:516 -msgid "spam spammodule.o" -msgstr "spam spammodule.o" - -#: ../../extending/extending.rst:520 -msgid "" -"and rebuild the interpreter by running :program:`make` in the toplevel " -"directory. You can also run :program:`make` in the :file:`Modules/` " -"subdirectory, but then you must first rebuild :file:`Makefile` there by " -"running ':program:`make` Makefile'. (This is necessary each time you change " -"the :file:`Setup` file.)" -msgstr "" - -#: ../../extending/extending.rst:526 -msgid "" -"If your module requires additional libraries to link with, these can be " -"listed on the line in the configuration file as well, for instance:" -msgstr "" - -#: ../../extending/extending.rst:529 -msgid "spam spammodule.o -lX11" -msgstr "spam spammodule.o -lX11" - -#: ../../extending/extending.rst:537 -msgid "Calling Python Functions from C" -msgstr "" - -#: ../../extending/extending.rst:539 -msgid "" -"So far we have concentrated on making C functions callable from Python. The " -"reverse is also useful: calling Python functions from C. This is especially " -"the case for libraries that support so-called \"callback\" functions. If a " -"C interface makes use of callbacks, the equivalent Python often needs to " -"provide a callback mechanism to the Python programmer; the implementation " -"will require calling the Python callback functions from a C callback. Other " -"uses are also imaginable." -msgstr "" - -#: ../../extending/extending.rst:547 -msgid "" -"Fortunately, the Python interpreter is easily called recursively, and there " -"is a standard interface to call a Python function. (I won't dwell on how to " -"call the Python parser with a particular string as input --- if you're " -"interested, have a look at the implementation of the :option:`-c` command " -"line option in :file:`Modules/main.c` from the Python source code.)" -msgstr "" - -#: ../../extending/extending.rst:553 -msgid "" -"Calling a Python function is easy. First, the Python program must somehow " -"pass you the Python function object. You should provide a function (or some " -"other interface) to do this. When this function is called, save a pointer " -"to the Python function object (be careful to :c:func:`Py_INCREF` it!) in a " -"global variable --- or wherever you see fit. For example, the following " -"function might be part of a module definition::" -msgstr "" - -#: ../../extending/extending.rst:560 -msgid "" -"static PyObject *my_callback = NULL;\n" -"\n" -"static PyObject *\n" -"my_set_callback(PyObject *dummy, PyObject *args)\n" -"{\n" -" PyObject *result = NULL;\n" -" PyObject *temp;\n" -"\n" -" if (PyArg_ParseTuple(args, \"O:set_callback\", &temp)) {\n" -" if (!PyCallable_Check(temp)) {\n" -" PyErr_SetString(PyExc_TypeError, \"parameter must be " -"callable\");\n" -" return NULL;\n" -" }\n" -" Py_XINCREF(temp); /* Add a reference to new callback */\n" -" Py_XDECREF(my_callback); /* Dispose of previous callback */\n" -" my_callback = temp; /* Remember new callback */\n" -" /* Boilerplate to return \"None\" */\n" -" Py_INCREF(Py_None);\n" -" result = Py_None;\n" -" }\n" -" return result;\n" -"}" -msgstr "" - -#: ../../extending/extending.rst:583 -msgid "" -"This function must be registered with the interpreter using the :c:macro:" -"`METH_VARARGS` flag; this is described in section :ref:`methodtable`. The :" -"c:func:`PyArg_ParseTuple` function and its arguments are documented in " -"section :ref:`parsetuple`." -msgstr "" - -#: ../../extending/extending.rst:588 -msgid "" -"The macros :c:func:`Py_XINCREF` and :c:func:`Py_XDECREF` increment/decrement " -"the reference count of an object and are safe in the presence of ``NULL`` " -"pointers (but note that *temp* will not be ``NULL`` in this context). More " -"info on them in section :ref:`refcounts`." -msgstr "" - -#: ../../extending/extending.rst:595 -msgid "" -"Later, when it is time to call the function, you call the C function :c:func:" -"`PyObject_CallObject`. This function has two arguments, both pointers to " -"arbitrary Python objects: the Python function, and the argument list. The " -"argument list must always be a tuple object, whose length is the number of " -"arguments. To call the Python function with no arguments, pass in ``NULL``, " -"or an empty tuple; to call it with one argument, pass a singleton tuple. :c:" -"func:`Py_BuildValue` returns a tuple when its format string consists of zero " -"or more format codes between parentheses. For example::" -msgstr "" - -#: ../../extending/extending.rst:604 -msgid "" -"int arg;\n" -"PyObject *arglist;\n" -"PyObject *result;\n" -"...\n" -"arg = 123;\n" -"...\n" -"/* Time to call the callback */\n" -"arglist = Py_BuildValue(\"(i)\", arg);\n" -"result = PyObject_CallObject(my_callback, arglist);\n" -"Py_DECREF(arglist);" -msgstr "" - -#: ../../extending/extending.rst:615 -msgid "" -":c:func:`PyObject_CallObject` returns a Python object pointer: this is the " -"return value of the Python function. :c:func:`PyObject_CallObject` is " -"\"reference-count-neutral\" with respect to its arguments. In the example a " -"new tuple was created to serve as the argument list, which is :c:func:" -"`Py_DECREF`\\ -ed immediately after the :c:func:`PyObject_CallObject` call." -msgstr "" - -#: ../../extending/extending.rst:622 -msgid "" -"The return value of :c:func:`PyObject_CallObject` is \"new\": either it is a " -"brand new object, or it is an existing object whose reference count has been " -"incremented. So, unless you want to save it in a global variable, you " -"should somehow :c:func:`Py_DECREF` the result, even (especially!) if you are " -"not interested in its value." -msgstr "" - -#: ../../extending/extending.rst:628 -msgid "" -"Before you do this, however, it is important to check that the return value " -"isn't ``NULL``. If it is, the Python function terminated by raising an " -"exception. If the C code that called :c:func:`PyObject_CallObject` is called " -"from Python, it should now return an error indication to its Python caller, " -"so the interpreter can print a stack trace, or the calling Python code can " -"handle the exception. If this is not possible or desirable, the exception " -"should be cleared by calling :c:func:`PyErr_Clear`. For example::" -msgstr "" - -#: ../../extending/extending.rst:636 -msgid "" -"if (result == NULL)\n" -" return NULL; /* Pass error back */\n" -"...use result...\n" -"Py_DECREF(result);" -msgstr "" - -#: ../../extending/extending.rst:641 -msgid "" -"Depending on the desired interface to the Python callback function, you may " -"also have to provide an argument list to :c:func:`PyObject_CallObject`. In " -"some cases the argument list is also provided by the Python program, through " -"the same interface that specified the callback function. It can then be " -"saved and used in the same manner as the function object. In other cases, " -"you may have to construct a new tuple to pass as the argument list. The " -"simplest way to do this is to call :c:func:`Py_BuildValue`. For example, if " -"you want to pass an integral event code, you might use the following code::" -msgstr "" - -#: ../../extending/extending.rst:650 -msgid "" -"PyObject *arglist;\n" -"...\n" -"arglist = Py_BuildValue(\"(l)\", eventcode);\n" -"result = PyObject_CallObject(my_callback, arglist);\n" -"Py_DECREF(arglist);\n" -"if (result == NULL)\n" -" return NULL; /* Pass error back */\n" -"/* Here maybe use the result */\n" -"Py_DECREF(result);" -msgstr "" - -#: ../../extending/extending.rst:660 -msgid "" -"Note the placement of ``Py_DECREF(arglist)`` immediately after the call, " -"before the error check! Also note that strictly speaking this code is not " -"complete: :c:func:`Py_BuildValue` may run out of memory, and this should be " -"checked." -msgstr "" - -#: ../../extending/extending.rst:664 -msgid "" -"You may also call a function with keyword arguments by using :c:func:" -"`PyObject_Call`, which supports arguments and keyword arguments. As in the " -"above example, we use :c:func:`Py_BuildValue` to construct the dictionary. ::" -msgstr "" - -#: ../../extending/extending.rst:668 -msgid "" -"PyObject *dict;\n" -"...\n" -"dict = Py_BuildValue(\"{s:i}\", \"name\", val);\n" -"result = PyObject_Call(my_callback, NULL, dict);\n" -"Py_DECREF(dict);\n" -"if (result == NULL)\n" -" return NULL; /* Pass error back */\n" -"/* Here maybe use the result */\n" -"Py_DECREF(result);" -msgstr "" - -#: ../../extending/extending.rst:682 -msgid "Extracting Parameters in Extension Functions" -msgstr "" - -#: ../../extending/extending.rst:686 -msgid "The :c:func:`PyArg_ParseTuple` function is declared as follows::" -msgstr "" - -#: ../../extending/extending.rst:688 -msgid "int PyArg_ParseTuple(PyObject *arg, const char *format, ...);" -msgstr "" - -#: ../../extending/extending.rst:690 -msgid "" -"The *arg* argument must be a tuple object containing an argument list passed " -"from Python to a C function. The *format* argument must be a format string, " -"whose syntax is explained in :ref:`arg-parsing` in the Python/C API " -"Reference Manual. The remaining arguments must be addresses of variables " -"whose type is determined by the format string." -msgstr "" - -#: ../../extending/extending.rst:696 -msgid "" -"Note that while :c:func:`PyArg_ParseTuple` checks that the Python arguments " -"have the required types, it cannot check the validity of the addresses of C " -"variables passed to the call: if you make mistakes there, your code will " -"probably crash or at least overwrite random bits in memory. So be careful!" -msgstr "" - -#: ../../extending/extending.rst:701 -msgid "" -"Note that any Python object references which are provided to the caller are " -"*borrowed* references; do not decrement their reference count!" -msgstr "" - -#: ../../extending/extending.rst:704 -msgid "Some example calls::" -msgstr "一些呼叫範例： ::" - -#: ../../extending/extending.rst:711 -msgid "" -"int ok;\n" -"int i, j;\n" -"long k, l;\n" -"const char *s;\n" -"Py_ssize_t size;\n" -"\n" -"ok = PyArg_ParseTuple(args, \"\"); /* No arguments */\n" -" /* Python call: f() */" -msgstr "" -"int ok;\n" -"int i, j;\n" -"long k, l;\n" -"const char *s;\n" -"Py_ssize_t size;\n" -"\n" -"ok = PyArg_ParseTuple(args, \"\"); /* 沒有引數 */\n" -" /* Python 呼叫：f() */" - -#: ../../extending/extending.rst:722 -msgid "" -"ok = PyArg_ParseTuple(args, \"s\", &s); /* A string */\n" -" /* Possible Python call: f('whoops!') */" -msgstr "" - -#: ../../extending/extending.rst:727 -msgid "" -"ok = PyArg_ParseTuple(args, \"lls\", &k, &l, &s); /* Two longs and a string " -"*/\n" -" /* Possible Python call: f(1, 2, 'three') */" -msgstr "" - -#: ../../extending/extending.rst:732 -msgid "" -"ok = PyArg_ParseTuple(args, \"(ii)s#\", &i, &j, &s, &size);\n" -" /* A pair of ints and a string, whose size is also returned */\n" -" /* Possible Python call: f((1, 2), 'three') */" -msgstr "" - -#: ../../extending/extending.rst:738 -msgid "" -"{\n" -" const char *file;\n" -" const char *mode = \"r\";\n" -" int bufsize = 0;\n" -" ok = PyArg_ParseTuple(args, \"s|si\", &file, &mode, &bufsize);\n" -" /* A string, and optionally another string and an integer */\n" -" /* Possible Python calls:\n" -" f('spam')\n" -" f('spam', 'w')\n" -" f('spam', 'wb', 100000) */\n" -"}" -msgstr "" - -#: ../../extending/extending.rst:752 -msgid "" -"{\n" -" int left, top, right, bottom, h, v;\n" -" ok = PyArg_ParseTuple(args, \"((ii)(ii))(ii)\",\n" -" &left, &top, &right, &bottom, &h, &v);\n" -" /* A rectangle and a point */\n" -" /* Possible Python call:\n" -" f(((0, 0), (400, 300)), (10, 10)) */\n" -"}" -msgstr "" - -#: ../../extending/extending.rst:763 -msgid "" -"{\n" -" Py_complex c;\n" -" ok = PyArg_ParseTuple(args, \"D:myfunction\", &c);\n" -" /* a complex, also providing a function name for errors */\n" -" /* Possible Python call: myfunction(1+2j) */\n" -"}" -msgstr "" - -#: ../../extending/extending.rst:774 -msgid "Keyword Parameters for Extension Functions" -msgstr "" - -#: ../../extending/extending.rst:778 -msgid "" -"The :c:func:`PyArg_ParseTupleAndKeywords` function is declared as follows::" -msgstr "" - -#: ../../extending/extending.rst:780 -msgid "" -"int PyArg_ParseTupleAndKeywords(PyObject *arg, PyObject *kwdict,\n" -" const char *format, char * const " -"*kwlist, ...);" -msgstr "" -"int PyArg_ParseTupleAndKeywords(PyObject *arg, PyObject *kwdict,\n" -" const char *format, char * const " -"*kwlist, ...);" - -#: ../../extending/extending.rst:783 -msgid "" -"The *arg* and *format* parameters are identical to those of the :c:func:" -"`PyArg_ParseTuple` function. The *kwdict* parameter is the dictionary of " -"keywords received as the third parameter from the Python runtime. The " -"*kwlist* parameter is a ``NULL``-terminated list of strings which identify " -"the parameters; the names are matched with the type information from " -"*format* from left to right. On success, :c:func:" -"`PyArg_ParseTupleAndKeywords` returns true, otherwise it returns false and " -"raises an appropriate exception." -msgstr "" - -#: ../../extending/extending.rst:793 -msgid "" -"Nested tuples cannot be parsed when using keyword arguments! Keyword " -"parameters passed in which are not present in the *kwlist* will cause :exc:" -"`TypeError` to be raised." -msgstr "" - -#: ../../extending/extending.rst:799 -msgid "" -"Here is an example module which uses keywords, based on an example by Geoff " -"Philbrick (philbrick@hks.com)::" -msgstr "" - -#: ../../extending/extending.rst:802 -msgid "" -"#define PY_SSIZE_T_CLEAN\n" -"#include \n" -"\n" -"static PyObject *\n" -"keywdarg_parrot(PyObject *self, PyObject *args, PyObject *keywds)\n" -"{\n" -" int voltage;\n" -" const char *state = \"a stiff\";\n" -" const char *action = \"voom\";\n" -" const char *type = \"Norwegian Blue\";\n" -"\n" -" static char *kwlist[] = {\"voltage\", \"state\", \"action\", \"type\", " -"NULL};\n" -"\n" -" if (!PyArg_ParseTupleAndKeywords(args, keywds, \"i|sss\", kwlist,\n" -" &voltage, &state, &action, &type))\n" -" return NULL;\n" -"\n" -" printf(\"-- This parrot wouldn't %s if you put %i Volts through it." -"\\n\",\n" -" action, voltage);\n" -" printf(\"-- Lovely plumage, the %s -- It's %s!\\n\", type, state);\n" -"\n" -" Py_RETURN_NONE;\n" -"}\n" -"\n" -"static PyMethodDef keywdarg_methods[] = {\n" -" /* The cast of the function is necessary since PyCFunction values\n" -" * only take two PyObject* parameters, and keywdarg_parrot() takes\n" -" * three.\n" -" */\n" -" {\"parrot\", (PyCFunction)(void(*)(void))keywdarg_parrot, METH_VARARGS | " -"METH_KEYWORDS,\n" -" \"Print a lovely skit to standard output.\"},\n" -" {NULL, NULL, 0, NULL} /* sentinel */\n" -"};\n" -"\n" -"static struct PyModuleDef keywdarg_module = {\n" -" .m_base = PyModuleDef_HEAD_INIT,\n" -" .m_name = \"keywdarg\",\n" -" .m_size = 0,\n" -" .m_methods = keywdarg_methods,\n" -"};\n" -"\n" -"PyMODINIT_FUNC\n" -"PyInit_keywdarg(void)\n" -"{\n" -" return PyModuleDef_Init(&keywdarg_module);\n" -"}" -msgstr "" - -#: ../../extending/extending.rst:853 -msgid "Building Arbitrary Values" -msgstr "" - -#: ../../extending/extending.rst:855 -msgid "" -"This function is the counterpart to :c:func:`PyArg_ParseTuple`. It is " -"declared as follows::" -msgstr "" - -#: ../../extending/extending.rst:858 -msgid "PyObject *Py_BuildValue(const char *format, ...);" -msgstr "PyObject *Py_BuildValue(const char *format, ...);" - -#: ../../extending/extending.rst:860 -msgid "" -"It recognizes a set of format units similar to the ones recognized by :c:" -"func:`PyArg_ParseTuple`, but the arguments (which are input to the function, " -"not output) must not be pointers, just values. It returns a new Python " -"object, suitable for returning from a C function called from Python." -msgstr "" - -#: ../../extending/extending.rst:865 -msgid "" -"One difference with :c:func:`PyArg_ParseTuple`: while the latter requires " -"its first argument to be a tuple (since Python argument lists are always " -"represented as tuples internally), :c:func:`Py_BuildValue` does not always " -"build a tuple. It builds a tuple only if its format string contains two or " -"more format units. If the format string is empty, it returns ``None``; if it " -"contains exactly one format unit, it returns whatever object is described by " -"that format unit. To force it to return a tuple of size 0 or one, " -"parenthesize the format string." -msgstr "" - -#: ../../extending/extending.rst:873 -msgid "" -"Examples (to the left the call, to the right the resulting Python value):" -msgstr "" - -#: ../../extending/extending.rst:875 -msgid "" -"Py_BuildValue(\"\") None\n" -"Py_BuildValue(\"i\", 123) 123\n" -"Py_BuildValue(\"iii\", 123, 456, 789) (123, 456, 789)\n" -"Py_BuildValue(\"s\", \"hello\") 'hello'\n" -"Py_BuildValue(\"y\", \"hello\") b'hello'\n" -"Py_BuildValue(\"ss\", \"hello\", \"world\") ('hello', 'world')\n" -"Py_BuildValue(\"s#\", \"hello\", 4) 'hell'\n" -"Py_BuildValue(\"y#\", \"hello\", 4) b'hell'\n" -"Py_BuildValue(\"()\") ()\n" -"Py_BuildValue(\"(i)\", 123) (123,)\n" -"Py_BuildValue(\"(ii)\", 123, 456) (123, 456)\n" -"Py_BuildValue(\"(i,i)\", 123, 456) (123, 456)\n" -"Py_BuildValue(\"[i,i]\", 123, 456) [123, 456]\n" -"Py_BuildValue(\"{s:i,s:i}\",\n" -" \"abc\", 123, \"def\", 456) {'abc': 123, 'def': 456}\n" -"Py_BuildValue(\"((ii)(ii)) (ii)\",\n" -" 1, 2, 3, 4, 5, 6) (((1, 2), (3, 4)), (5, 6))" -msgstr "" -"Py_BuildValue(\"\") None\n" -"Py_BuildValue(\"i\", 123) 123\n" -"Py_BuildValue(\"iii\", 123, 456, 789) (123, 456, 789)\n" -"Py_BuildValue(\"s\", \"hello\") 'hello'\n" -"Py_BuildValue(\"y\", \"hello\") b'hello'\n" -"Py_BuildValue(\"ss\", \"hello\", \"world\") ('hello', 'world')\n" -"Py_BuildValue(\"s#\", \"hello\", 4) 'hell'\n" -"Py_BuildValue(\"y#\", \"hello\", 4) b'hell'\n" -"Py_BuildValue(\"()\") ()\n" -"Py_BuildValue(\"(i)\", 123) (123,)\n" -"Py_BuildValue(\"(ii)\", 123, 456) (123, 456)\n" -"Py_BuildValue(\"(i,i)\", 123, 456) (123, 456)\n" -"Py_BuildValue(\"[i,i]\", 123, 456) [123, 456]\n" -"Py_BuildValue(\"{s:i,s:i}\",\n" -" \"abc\", 123, \"def\", 456) {'abc': 123, 'def': 456}\n" -"Py_BuildValue(\"((ii)(ii)) (ii)\",\n" -" 1, 2, 3, 4, 5, 6) (((1, 2), (3, 4)), (5, 6))" - -#: ../../extending/extending.rst:899 -msgid "Reference Counts" -msgstr "參照計數" - -#: ../../extending/extending.rst:901 -msgid "" -"In languages like C or C++, the programmer is responsible for dynamic " -"allocation and deallocation of memory on the heap. In C, this is done using " -"the functions :c:func:`malloc` and :c:func:`free`. In C++, the operators " -"``new`` and ``delete`` are used with essentially the same meaning and we'll " -"restrict the following discussion to the C case." -msgstr "" - -#: ../../extending/extending.rst:907 -msgid "" -"Every block of memory allocated with :c:func:`malloc` should eventually be " -"returned to the pool of available memory by exactly one call to :c:func:" -"`free`. It is important to call :c:func:`free` at the right time. If a " -"block's address is forgotten but :c:func:`free` is not called for it, the " -"memory it occupies cannot be reused until the program terminates. This is " -"called a :dfn:`memory leak`. On the other hand, if a program calls :c:func:" -"`free` for a block and then continues to use the block, it creates a " -"conflict with reuse of the block through another :c:func:`malloc` call. " -"This is called :dfn:`using freed memory`. It has the same bad consequences " -"as referencing uninitialized data --- core dumps, wrong results, mysterious " -"crashes." -msgstr "" - -#: ../../extending/extending.rst:918 -msgid "" -"Common causes of memory leaks are unusual paths through the code. For " -"instance, a function may allocate a block of memory, do some calculation, " -"and then free the block again. Now a change in the requirements for the " -"function may add a test to the calculation that detects an error condition " -"and can return prematurely from the function. It's easy to forget to free " -"the allocated memory block when taking this premature exit, especially when " -"it is added later to the code. Such leaks, once introduced, often go " -"undetected for a long time: the error exit is taken only in a small fraction " -"of all calls, and most modern machines have plenty of virtual memory, so the " -"leak only becomes apparent in a long-running process that uses the leaking " -"function frequently. Therefore, it's important to prevent leaks from " -"happening by having a coding convention or strategy that minimizes this kind " -"of errors." -msgstr "" - -#: ../../extending/extending.rst:931 -msgid "" -"Since Python makes heavy use of :c:func:`malloc` and :c:func:`free`, it " -"needs a strategy to avoid memory leaks as well as the use of freed memory. " -"The chosen method is called :dfn:`reference counting`. The principle is " -"simple: every object contains a counter, which is incremented when a " -"reference to the object is stored somewhere, and which is decremented when a " -"reference to it is deleted. When the counter reaches zero, the last " -"reference to the object has been deleted and the object is freed." -msgstr "" - -#: ../../extending/extending.rst:939 -msgid "" -"An alternative strategy is called :dfn:`automatic garbage collection`. " -"(Sometimes, reference counting is also referred to as a garbage collection " -"strategy, hence my use of \"automatic\" to distinguish the two.) The big " -"advantage of automatic garbage collection is that the user doesn't need to " -"call :c:func:`free` explicitly. (Another claimed advantage is an " -"improvement in speed or memory usage --- this is no hard fact however.) The " -"disadvantage is that for C, there is no truly portable automatic garbage " -"collector, while reference counting can be implemented portably (as long as " -"the functions :c:func:`malloc` and :c:func:`free` are available --- which " -"the C Standard guarantees). Maybe some day a sufficiently portable automatic " -"garbage collector will be available for C. Until then, we'll have to live " -"with reference counts." -msgstr "" - -#: ../../extending/extending.rst:951 -msgid "" -"While Python uses the traditional reference counting implementation, it also " -"offers a cycle detector that works to detect reference cycles. This allows " -"applications to not worry about creating direct or indirect circular " -"references; these are the weakness of garbage collection implemented using " -"only reference counting. Reference cycles consist of objects which contain " -"(possibly indirect) references to themselves, so that each object in the " -"cycle has a reference count which is non-zero. Typical reference counting " -"implementations are not able to reclaim the memory belonging to any objects " -"in a reference cycle, or referenced from the objects in the cycle, even " -"though there are no further references to the cycle itself." -msgstr "" - -#: ../../extending/extending.rst:962 -msgid "" -"The cycle detector is able to detect garbage cycles and can reclaim them. " -"The :mod:`gc` module exposes a way to run the detector (the :func:`~gc." -"collect` function), as well as configuration interfaces and the ability to " -"disable the detector at runtime." -msgstr "" - -#: ../../extending/extending.rst:971 -msgid "Reference Counting in Python" -msgstr "Python 中的參照計數" - -#: ../../extending/extending.rst:973 -msgid "" -"There are two macros, ``Py_INCREF(x)`` and ``Py_DECREF(x)``, which handle " -"the incrementing and decrementing of the reference count. :c:func:" -"`Py_DECREF` also frees the object when the count reaches zero. For " -"flexibility, it doesn't call :c:func:`free` directly --- rather, it makes a " -"call through a function pointer in the object's :dfn:`type object`. For " -"this purpose (and others), every object also contains a pointer to its type " -"object." -msgstr "" - -#: ../../extending/extending.rst:980 -msgid "" -"The big question now remains: when to use ``Py_INCREF(x)`` and " -"``Py_DECREF(x)``? Let's first introduce some terms. Nobody \"owns\" an " -"object; however, you can :dfn:`own a reference` to an object. An object's " -"reference count is now defined as the number of owned references to it. The " -"owner of a reference is responsible for calling :c:func:`Py_DECREF` when the " -"reference is no longer needed. Ownership of a reference can be " -"transferred. There are three ways to dispose of an owned reference: pass it " -"on, store it, or call :c:func:`Py_DECREF`. Forgetting to dispose of an owned " -"reference creates a memory leak." -msgstr "" - -#: ../../extending/extending.rst:989 -msgid "" -"It is also possible to :dfn:`borrow` [#]_ a reference to an object. The " -"borrower of a reference should not call :c:func:`Py_DECREF`. The borrower " -"must not hold on to the object longer than the owner from which it was " -"borrowed. Using a borrowed reference after the owner has disposed of it " -"risks using freed memory and should be avoided completely [#]_." -msgstr "" - -#: ../../extending/extending.rst:995 -msgid "" -"The advantage of borrowing over owning a reference is that you don't need to " -"take care of disposing of the reference on all possible paths through the " -"code --- in other words, with a borrowed reference you don't run the risk of " -"leaking when a premature exit is taken. The disadvantage of borrowing over " -"owning is that there are some subtle situations where in seemingly correct " -"code a borrowed reference can be used after the owner from which it was " -"borrowed has in fact disposed of it." -msgstr "" - -#: ../../extending/extending.rst:1003 -msgid "" -"A borrowed reference can be changed into an owned reference by calling :c:" -"func:`Py_INCREF`. This does not affect the status of the owner from which " -"the reference was borrowed --- it creates a new owned reference, and gives " -"full owner responsibilities (the new owner must dispose of the reference " -"properly, as well as the previous owner)." -msgstr "" - -#: ../../extending/extending.rst:1013 -msgid "Ownership Rules" -msgstr "" - -#: ../../extending/extending.rst:1015 -msgid "" -"Whenever an object reference is passed into or out of a function, it is part " -"of the function's interface specification whether ownership is transferred " -"with the reference or not." -msgstr "" - -#: ../../extending/extending.rst:1019 -msgid "" -"Most functions that return a reference to an object pass on ownership with " -"the reference. In particular, all functions whose function it is to create " -"a new object, such as :c:func:`PyLong_FromLong` and :c:func:`Py_BuildValue`, " -"pass ownership to the receiver. Even if the object is not actually new, you " -"still receive ownership of a new reference to that object. For instance, :c:" -"func:`PyLong_FromLong` maintains a cache of popular values and can return a " -"reference to a cached item." -msgstr "" - -#: ../../extending/extending.rst:1027 -msgid "" -"Many functions that extract objects from other objects also transfer " -"ownership with the reference, for instance :c:func:" -"`PyObject_GetAttrString`. The picture is less clear, here, however, since a " -"few common routines are exceptions: :c:func:`PyTuple_GetItem`, :c:func:" -"`PyList_GetItem`, :c:func:`PyDict_GetItem`, and :c:func:" -"`PyDict_GetItemString` all return references that you borrow from the tuple, " -"list or dictionary." -msgstr "" - -#: ../../extending/extending.rst:1034 -msgid "" -"The function :c:func:`PyImport_AddModule` also returns a borrowed reference, " -"even though it may actually create the object it returns: this is possible " -"because an owned reference to the object is stored in ``sys.modules``." -msgstr "" - -#: ../../extending/extending.rst:1038 -msgid "" -"When you pass an object reference into another function, in general, the " -"function borrows the reference from you --- if it needs to store it, it will " -"use :c:func:`Py_INCREF` to become an independent owner. There are exactly " -"two important exceptions to this rule: :c:func:`PyTuple_SetItem` and :c:func:" -"`PyList_SetItem`. These functions take over ownership of the item passed to " -"them --- even if they fail! (Note that :c:func:`PyDict_SetItem` and friends " -"don't take over ownership --- they are \"normal.\")" -msgstr "" - -#: ../../extending/extending.rst:1046 -msgid "" -"When a C function is called from Python, it borrows references to its " -"arguments from the caller. The caller owns a reference to the object, so " -"the borrowed reference's lifetime is guaranteed until the function returns. " -"Only when such a borrowed reference must be stored or passed on, it must be " -"turned into an owned reference by calling :c:func:`Py_INCREF`." -msgstr "" - -#: ../../extending/extending.rst:1052 -msgid "" -"The object reference returned from a C function that is called from Python " -"must be an owned reference --- ownership is transferred from the function to " -"its caller." -msgstr "" - -#: ../../extending/extending.rst:1060 -msgid "Thin Ice" -msgstr "" - -#: ../../extending/extending.rst:1062 -msgid "" -"There are a few situations where seemingly harmless use of a borrowed " -"reference can lead to problems. These all have to do with implicit " -"invocations of the interpreter, which can cause the owner of a reference to " -"dispose of it." -msgstr "" - -#: ../../extending/extending.rst:1066 -msgid "" -"The first and most important case to know about is using :c:func:`Py_DECREF` " -"on an unrelated object while borrowing a reference to a list item. For " -"instance::" -msgstr "" - -#: ../../extending/extending.rst:1069 -msgid "" -"void\n" -"bug(PyObject *list)\n" -"{\n" -" PyObject *item = PyList_GetItem(list, 0);\n" -"\n" -" PyList_SetItem(list, 1, PyLong_FromLong(0L));\n" -" PyObject_Print(item, stdout, 0); /* BUG! */\n" -"}" -msgstr "" -"void\n" -"bug(PyObject *list)\n" -"{\n" -" PyObject *item = PyList_GetItem(list, 0);\n" -"\n" -" PyList_SetItem(list, 1, PyLong_FromLong(0L));\n" -" PyObject_Print(item, stdout, 0); /* BUG! */\n" -"}" - -#: ../../extending/extending.rst:1078 -msgid "" -"This function first borrows a reference to ``list[0]``, then replaces " -"``list[1]`` with the value ``0``, and finally prints the borrowed reference. " -"Looks harmless, right? But it's not!" -msgstr "" - -#: ../../extending/extending.rst:1082 -msgid "" -"Let's follow the control flow into :c:func:`PyList_SetItem`. The list owns " -"references to all its items, so when item 1 is replaced, it has to dispose " -"of the original item 1. Now let's suppose the original item 1 was an " -"instance of a user-defined class, and let's further suppose that the class " -"defined a :meth:`!__del__` method. If this class instance has a reference " -"count of 1, disposing of it will call its :meth:`!__del__` method. " -"Internally, :c:func:`PyList_SetItem` calls :c:func:`Py_DECREF` on the " -"replaced item, which invokes replaced item's corresponding :c:member:" -"`~PyTypeObject.tp_dealloc` function. During deallocation, :c:member:" -"`~PyTypeObject.tp_dealloc` calls :c:member:`~PyTypeObject.tp_finalize`, " -"which is mapped to the :meth:`!__del__` method for class instances (see :pep:" -"`442`). This entire sequence happens synchronously within the :c:func:" -"`PyList_SetItem` call." -msgstr "" - -#: ../../extending/extending.rst:1096 -msgid "" -"Since it is written in Python, the :meth:`!__del__` method can execute " -"arbitrary Python code. Could it perhaps do something to invalidate the " -"reference to ``item`` in :c:func:`!bug`? You bet! Assuming that the list " -"passed into :c:func:`!bug` is accessible to the :meth:`!__del__` method, it " -"could execute a statement to the effect of ``del list[0]``, and assuming " -"this was the last reference to that object, it would free the memory " -"associated with it, thereby invalidating ``item``." -msgstr "" - -#: ../../extending/extending.rst:1104 -msgid "" -"The solution, once you know the source of the problem, is easy: temporarily " -"increment the reference count. The correct version of the function reads::" -msgstr "" - -#: ../../extending/extending.rst:1107 -msgid "" -"void\n" -"no_bug(PyObject *list)\n" -"{\n" -" PyObject *item = PyList_GetItem(list, 0);\n" -"\n" -" Py_INCREF(item);\n" -" PyList_SetItem(list, 1, PyLong_FromLong(0L));\n" -" PyObject_Print(item, stdout, 0);\n" -" Py_DECREF(item);\n" -"}" -msgstr "" -"void\n" -"no_bug(PyObject *list)\n" -"{\n" -" PyObject *item = PyList_GetItem(list, 0);\n" -"\n" -" Py_INCREF(item);\n" -" PyList_SetItem(list, 1, PyLong_FromLong(0L));\n" -" PyObject_Print(item, stdout, 0);\n" -" Py_DECREF(item);\n" -"}" - -#: ../../extending/extending.rst:1118 -msgid "" -"This is a true story. An older version of Python contained variants of this " -"bug and someone spent a considerable amount of time in a C debugger to " -"figure out why his :meth:`!__del__` methods would fail..." -msgstr "" - -#: ../../extending/extending.rst:1122 -msgid "" -"The second case of problems with a borrowed reference is a variant involving " -"threads. Normally, multiple threads in the Python interpreter can't get in " -"each other's way, because there is a :term:`global lock ` protecting Python's entire object space. However, it is possible to " -"temporarily release this lock using the macro :c:macro:" -"`Py_BEGIN_ALLOW_THREADS`, and to re-acquire it using :c:macro:" -"`Py_END_ALLOW_THREADS`. This is common around blocking I/O calls, to let " -"other threads use the processor while waiting for the I/O to complete. " -"Obviously, the following function has the same problem as the previous one::" -msgstr "" - -#: ../../extending/extending.rst:1132 -msgid "" -"void\n" -"bug(PyObject *list)\n" -"{\n" -" PyObject *item = PyList_GetItem(list, 0);\n" -" Py_BEGIN_ALLOW_THREADS\n" -" ...some blocking I/O call...\n" -" Py_END_ALLOW_THREADS\n" -" PyObject_Print(item, stdout, 0); /* BUG! */\n" -"}" -msgstr "" - -#: ../../extending/extending.rst:1146 -msgid "NULL Pointers" -msgstr "NULL 指標" - -#: ../../extending/extending.rst:1148 -msgid "" -"In general, functions that take object references as arguments do not expect " -"you to pass them ``NULL`` pointers, and will dump core (or cause later core " -"dumps) if you do so. Functions that return object references generally " -"return ``NULL`` only to indicate that an exception occurred. The reason for " -"not testing for ``NULL`` arguments is that functions often pass the objects " -"they receive on to other function --- if each function were to test for " -"``NULL``, there would be a lot of redundant tests and the code would run " -"more slowly." -msgstr "" - -#: ../../extending/extending.rst:1156 -msgid "" -"It is better to test for ``NULL`` only at the \"source:\" when a pointer " -"that may be ``NULL`` is received, for example, from :c:func:`malloc` or from " -"a function that may raise an exception." -msgstr "" - -#: ../../extending/extending.rst:1160 -msgid "" -"The macros :c:func:`Py_INCREF` and :c:func:`Py_DECREF` do not check for " -"``NULL`` pointers --- however, their variants :c:func:`Py_XINCREF` and :c:" -"func:`Py_XDECREF` do." -msgstr "" - -#: ../../extending/extending.rst:1164 -msgid "" -"The macros for checking for a particular object type (``Pytype_Check()``) " -"don't check for ``NULL`` pointers --- again, there is much code that calls " -"several of these in a row to test an object against various different " -"expected types, and this would generate redundant tests. There are no " -"variants with ``NULL`` checking." -msgstr "" - -#: ../../extending/extending.rst:1170 -msgid "" -"The C function calling mechanism guarantees that the argument list passed to " -"C functions (``args`` in the examples) is never ``NULL`` --- in fact it " -"guarantees that it is always a tuple [#]_." -msgstr "" - -#: ../../extending/extending.rst:1174 -msgid "" -"It is a severe error to ever let a ``NULL`` pointer \"escape\" to the Python " -"user." -msgstr "" - -#: ../../extending/extending.rst:1185 -msgid "Writing Extensions in C++" -msgstr "" - -#: ../../extending/extending.rst:1187 -msgid "" -"It is possible to write extension modules in C++. Some restrictions apply. " -"If the main program (the Python interpreter) is compiled and linked by the C " -"compiler, global or static objects with constructors cannot be used. This " -"is not a problem if the main program is linked by the C++ compiler. " -"Functions that will be called by the Python interpreter (in particular, " -"module initialization functions) have to be declared using ``extern \"C\"``. " -"It is unnecessary to enclose the Python header files in ``extern \"C\" {...}" -"`` --- they use this form already if the symbol ``__cplusplus`` is defined " -"(all recent C++ compilers define this symbol)." -msgstr "" - -#: ../../extending/extending.rst:1201 -msgid "Providing a C API for an Extension Module" -msgstr "" - -#: ../../extending/extending.rst:1206 -msgid "" -"Many extension modules just provide new functions and types to be used from " -"Python, but sometimes the code in an extension module can be useful for " -"other extension modules. For example, an extension module could implement a " -"type \"collection\" which works like lists without order. Just like the " -"standard Python list type has a C API which permits extension modules to " -"create and manipulate lists, this new collection type should have a set of C " -"functions for direct manipulation from other extension modules." -msgstr "" - -#: ../../extending/extending.rst:1214 -msgid "" -"At first sight this seems easy: just write the functions (without declaring " -"them ``static``, of course), provide an appropriate header file, and " -"document the C API. And in fact this would work if all extension modules " -"were always linked statically with the Python interpreter. When modules are " -"used as shared libraries, however, the symbols defined in one module may not " -"be visible to another module. The details of visibility depend on the " -"operating system; some systems use one global namespace for the Python " -"interpreter and all extension modules (Windows, for example), whereas others " -"require an explicit list of imported symbols at module link time (AIX is one " -"example), or offer a choice of different strategies (most Unices). And even " -"if symbols are globally visible, the module whose functions one wishes to " -"call might not have been loaded yet!" -msgstr "" - -#: ../../extending/extending.rst:1226 -msgid "" -"Portability therefore requires not to make any assumptions about symbol " -"visibility. This means that all symbols in extension modules should be " -"declared ``static``, except for the module's initialization function, in " -"order to avoid name clashes with other extension modules (as discussed in " -"section :ref:`methodtable`). And it means that symbols that *should* be " -"accessible from other extension modules must be exported in a different way." -msgstr "" - -#: ../../extending/extending.rst:1233 -msgid "" -"Python provides a special mechanism to pass C-level information (pointers) " -"from one extension module to another one: Capsules. A Capsule is a Python " -"data type which stores a pointer (:c:expr:`void \\*`). Capsules can only be " -"created and accessed via their C API, but they can be passed around like any " -"other Python object. In particular, they can be assigned to a name in an " -"extension module's namespace. Other extension modules can then import this " -"module, retrieve the value of this name, and then retrieve the pointer from " -"the Capsule." -msgstr "" - -#: ../../extending/extending.rst:1241 -msgid "" -"There are many ways in which Capsules can be used to export the C API of an " -"extension module. Each function could get its own Capsule, or all C API " -"pointers could be stored in an array whose address is published in a " -"Capsule. And the various tasks of storing and retrieving the pointers can be " -"distributed in different ways between the module providing the code and the " -"client modules." -msgstr "" - -#: ../../extending/extending.rst:1247 -msgid "" -"Whichever method you choose, it's important to name your Capsules properly. " -"The function :c:func:`PyCapsule_New` takes a name parameter (:c:expr:`const " -"char \\*`); you're permitted to pass in a ``NULL`` name, but we strongly " -"encourage you to specify a name. Properly named Capsules provide a degree " -"of runtime type-safety; there is no feasible way to tell one unnamed Capsule " -"from another." -msgstr "" - -#: ../../extending/extending.rst:1254 -msgid "" -"In particular, Capsules used to expose C APIs should be given a name " -"following this convention::" -msgstr "" - -#: ../../extending/extending.rst:1257 -msgid "modulename.attributename" -msgstr "modulename.attributename" - -#: ../../extending/extending.rst:1259 -msgid "" -"The convenience function :c:func:`PyCapsule_Import` makes it easy to load a " -"C API provided via a Capsule, but only if the Capsule's name matches this " -"convention. This behavior gives C API users a high degree of certainty that " -"the Capsule they load contains the correct C API." -msgstr "" - -#: ../../extending/extending.rst:1264 -msgid "" -"The following example demonstrates an approach that puts most of the burden " -"on the writer of the exporting module, which is appropriate for commonly " -"used library modules. It stores all C API pointers (just one in the " -"example!) in an array of :c:expr:`void` pointers which becomes the value of " -"a Capsule. The header file corresponding to the module provides a macro that " -"takes care of importing the module and retrieving its C API pointers; client " -"modules only have to call this macro before accessing the C API." -msgstr "" - -#: ../../extending/extending.rst:1272 -msgid "" -"The exporting module is a modification of the :mod:`!spam` module from " -"section :ref:`extending-simpleexample`. The function :func:`!spam.system` " -"does not call the C library function :c:func:`system` directly, but a " -"function :c:func:`!PySpam_System`, which would of course do something more " -"complicated in reality (such as adding \"spam\" to every command). This " -"function :c:func:`!PySpam_System` is also exported to other extension " -"modules." -msgstr "" - -#: ../../extending/extending.rst:1279 -msgid "" -"The function :c:func:`!PySpam_System` is a plain C function, declared " -"``static`` like everything else::" -msgstr "" - -#: ../../extending/extending.rst:1282 -msgid "" -"static int\n" -"PySpam_System(const char *command)\n" -"{\n" -" return system(command);\n" -"}" -msgstr "" -"static int\n" -"PySpam_System(const char *command)\n" -"{\n" -" return system(command);\n" -"}" - -#: ../../extending/extending.rst:1288 -msgid "The function :c:func:`!spam_system` is modified in a trivial way::" -msgstr "" - -#: ../../extending/extending.rst:1290 -msgid "" -"static PyObject *\n" -"spam_system(PyObject *self, PyObject *args)\n" -"{\n" -" const char *command;\n" -" int sts;\n" -"\n" -" if (!PyArg_ParseTuple(args, \"s\", &command))\n" -" return NULL;\n" -" sts = PySpam_System(command);\n" -" return PyLong_FromLong(sts);\n" -"}" -msgstr "" -"static PyObject *\n" -"spam_system(PyObject *self, PyObject *args)\n" -"{\n" -" const char *command;\n" -" int sts;\n" -"\n" -" if (!PyArg_ParseTuple(args, \"s\", &command))\n" -" return NULL;\n" -" sts = PySpam_System(command);\n" -" return PyLong_FromLong(sts);\n" -"}" - -#: ../../extending/extending.rst:1302 -msgid "In the beginning of the module, right after the line ::" -msgstr "" - -#: ../../extending/extending.rst:1304 -msgid "#include " -msgstr "#include " - -#: ../../extending/extending.rst:1306 -msgid "two more lines must be added::" -msgstr "" - -#: ../../extending/extending.rst:1308 -msgid "" -"#define SPAM_MODULE\n" -"#include \"spammodule.h\"" -msgstr "" -"#define SPAM_MODULE\n" -"#include \"spammodule.h\"" - -#: ../../extending/extending.rst:1311 -msgid "" -"The ``#define`` is used to tell the header file that it is being included in " -"the exporting module, not a client module. Finally, the module's :c:data:" -"`mod_exec ` function must take care of initializing the C API " -"pointer array::" -msgstr "" - -#: ../../extending/extending.rst:1315 -msgid "" -"static int\n" -"spam_module_exec(PyObject *m)\n" -"{\n" -" static void *PySpam_API[PySpam_API_pointers];\n" -" PyObject *c_api_object;\n" -"\n" -" /* Initialize the C API pointer array */\n" -" PySpam_API[PySpam_System_NUM] = (void *)PySpam_System;\n" -"\n" -" /* Create a Capsule containing the API pointer array's address */\n" -" c_api_object = PyCapsule_New((void *)PySpam_API, \"spam._C_API\", " -"NULL);\n" -"\n" -" if (PyModule_Add(m, \"_C_API\", c_api_object) < 0) {\n" -" return -1;\n" -" }\n" -"\n" -" return 0;\n" -"}" -msgstr "" - -#: ../../extending/extending.rst:1334 -msgid "" -"Note that ``PySpam_API`` is declared ``static``; otherwise the pointer array " -"would disappear when :c:func:`!PyInit_spam` terminates!" -msgstr "" - -#: ../../extending/extending.rst:1337 -msgid "" -"The bulk of the work is in the header file :file:`spammodule.h`, which looks " -"like this::" -msgstr "" - -#: ../../extending/extending.rst:1340 -msgid "" -"#ifndef Py_SPAMMODULE_H\n" -"#define Py_SPAMMODULE_H\n" -"#ifdef __cplusplus\n" -"extern \"C\" {\n" -"#endif\n" -"\n" -"/* Header file for spammodule */\n" -"\n" -"/* C API functions */\n" -"#define PySpam_System_NUM 0\n" -"#define PySpam_System_RETURN int\n" -"#define PySpam_System_PROTO (const char *command)\n" -"\n" -"/* Total number of C API pointers */\n" -"#define PySpam_API_pointers 1\n" -"\n" -"\n" -"#ifdef SPAM_MODULE\n" -"/* This section is used when compiling spammodule.c */\n" -"\n" -"static PySpam_System_RETURN PySpam_System PySpam_System_PROTO;\n" -"\n" -"#else\n" -"/* This section is used in modules that use spammodule's API */\n" -"\n" -"static void **PySpam_API;\n" -"\n" -"#define PySpam_System \\\n" -" (*(PySpam_System_RETURN (*)PySpam_System_PROTO) " -"PySpam_API[PySpam_System_NUM])\n" -"\n" -"/* Return -1 on error, 0 on success.\n" -" * PyCapsule_Import will set an exception if there's an error.\n" -" */\n" -"static int\n" -"import_spam(void)\n" -"{\n" -" PySpam_API = (void **)PyCapsule_Import(\"spam._C_API\", 0);\n" -" return (PySpam_API != NULL) ? 0 : -1;\n" -"}\n" -"\n" -"#endif\n" -"\n" -"#ifdef __cplusplus\n" -"}\n" -"#endif\n" -"\n" -"#endif /* !defined(Py_SPAMMODULE_H) */" -msgstr "" - -#: ../../extending/extending.rst:1388 -msgid "" -"All that a client module must do in order to have access to the function :c:" -"func:`!PySpam_System` is to call the function (or rather macro) :c:func:`!" -"import_spam` in its :c:data:`mod_exec ` function::" -msgstr "" - -#: ../../extending/extending.rst:1392 -msgid "" -"static int\n" -"client_module_exec(PyObject *m)\n" -"{\n" -" if (import_spam() < 0) {\n" -" return -1;\n" -" }\n" -" /* additional initialization can happen here */\n" -" return 0;\n" -"}" -msgstr "" - -#: ../../extending/extending.rst:1402 -msgid "" -"The main disadvantage of this approach is that the file :file:`spammodule.h` " -"is rather complicated. However, the basic structure is the same for each " -"function that is exported, so it has to be learned only once." -msgstr "" - -#: ../../extending/extending.rst:1406 -msgid "" -"Finally it should be mentioned that Capsules offer additional functionality, " -"which is especially useful for memory allocation and deallocation of the " -"pointer stored in a Capsule. The details are described in the Python/C API " -"Reference Manual in the section :ref:`capsules` and in the implementation of " -"Capsules (files :file:`Include/pycapsule.h` and :file:`Objects/pycapsule.c` " -"in the Python source code distribution)." -msgstr "" - -#: ../../extending/extending.rst:1414 -msgid "Footnotes" -msgstr "註腳" - -#: ../../extending/extending.rst:1415 -msgid "" -"An interface for this function already exists in the standard module :mod:" -"`os` --- it was chosen as a simple and straightforward example." -msgstr "" - -#: ../../extending/extending.rst:1418 -msgid "" -"The metaphor of \"borrowing\" a reference is not completely correct: the " -"owner still has a copy of the reference." -msgstr "" - -#: ../../extending/extending.rst:1421 -msgid "" -"Checking that the reference count is at least 1 **does not work** --- the " -"reference count itself could be in freed memory and may thus be reused for " -"another object!" -msgstr "" - -#: ../../extending/extending.rst:1425 -msgid "" -"These guarantees don't hold when you use the \"old\" style calling " -"convention --- this is still found in much existing code." -msgstr "" - -#: ../../extending/extending.rst:593 -msgid "PyObject_CallObject (C function)" -msgstr "PyObject_CallObject（C 函式）" - -#: ../../extending/extending.rst:684 -msgid "PyArg_ParseTuple (C function)" -msgstr "PyArg_ParseTuple（C 函式）" - -#: ../../extending/extending.rst:776 -msgid "PyArg_ParseTupleAndKeywords (C function)" -msgstr "PyArg_ParseTupleAndKeywords（C 函式）" - -#: ../../extending/extending.rst:797 -msgid "Philbrick, Geoff" -msgstr "Philbrick, Geoff" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Leon H., 2017 +# Adrian Liaw , 2018 +# Matt Wang , 2025 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-25 00:13+0000\n" +"PO-Revision-Date: 2025-02-17 14:34+0000\n" +"Last-Translator: Matt Wang \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" + +#: ../../extending/extending.rst:8 +msgid "Extending Python with C or C++" +msgstr "以 C 或 C++ 擴充 Python" + +#: ../../extending/extending.rst:10 +msgid "" +"It is quite easy to add new built-in modules to Python, if you know how to " +"program in C. Such :dfn:`extension modules` can do two things that can't be " +"done directly in Python: they can implement new built-in object types, and " +"they can call C library functions and system calls." +msgstr "" +"如果你會撰寫 C 程式語言，那要向 Python 新增內建模組就不困難。這種\\ :dfn:`擴" +"充模組 (extension modules)` 可以做兩件在 Python 中無法直接完成的事：它們可以" +"實作新的內建物件型別，並且可以呼叫 C 的函式庫函式和系統呼叫。" + +#: ../../extending/extending.rst:15 +msgid "" +"To support extensions, the Python API (Application Programmers Interface) " +"defines a set of functions, macros and variables that provide access to most " +"aspects of the Python run-time system. The Python API is incorporated in a " +"C source file by including the header ``\"Python.h\"``." +msgstr "" +"為了支援擴充，Python API (Application Programmers Interface) 定義了一組函式、" +"巨集和變數，提供對 Python run-time 系統大部分面向的存取。Python API 是透過引" +"入標頭檔 ``\"Python.h\"`` 來被納入到一個 C 原始碼檔案中。" + +#: ../../extending/extending.rst:20 +msgid "" +"The compilation of an extension module depends on its intended use as well " +"as on your system setup; details are given in later chapters." +msgstr "" +"擴充模組的編譯取決於其預期用途以及你的系統設定；詳細資訊將在後面的章節中提" +"供。" + +#: ../../extending/extending.rst:25 +msgid "" +"The C extension interface is specific to CPython, and extension modules do " +"not work on other Python implementations. In many cases, it is possible to " +"avoid writing C extensions and preserve portability to other " +"implementations. For example, if your use case is calling C library " +"functions or system calls, you should consider using the :mod:`ctypes` " +"module or the `cffi `_ library rather than " +"writing custom C code. These modules let you write Python code to interface " +"with C code and are more portable between implementations of Python than " +"writing and compiling a C extension module." +msgstr "" +"C 擴充介面是 CPython 所特有的，擴充模組在其他 Python 實作上無法運作。在許多情" +"況下，可以避免撰寫 C 擴充並保留對其他實作的可移植性。例如，如果你的用例是呼" +"叫 C 函式庫函式或系統呼叫，你應該考慮使用 :mod:`ctypes` 模組或 `cffi " +"`_ 函式庫，而不是編寫自訂的 C 程式碼。這些模" +"組讓你可以撰寫 Python 程式碼來與 C 程式碼介接，而且比起撰寫和編譯 C 擴充模" +"組，這些模組在 Python 實作之間更容易移植。" + +#: ../../extending/extending.rst:40 +msgid "A Simple Example" +msgstr "一個簡單範例" + +#: ../../extending/extending.rst:42 +msgid "" +"Let's create an extension module called ``spam`` (the favorite food of Monty " +"Python fans...) and let's say we want to create a Python interface to the C " +"library function :c:func:`system` [#]_. This function takes a null-" +"terminated character string as argument and returns an integer. We want " +"this function to be callable from Python as follows:" +msgstr "" +"讓我們來建立一個叫做 ``spam``\\ （Monty Python 粉絲最愛的食物...）的擴充模" +"組。假設我們要建立一個 Python 介面給 C 函式庫的函式 :c:func:`system` [#]_ 使" +"用，這個函式接受一個以 null 終止的 (null-terminated) 字元字串做為引數，並回傳" +"一個整數。我們希望這個函式可以在 Python 中被呼叫，如下所示：" + +#: ../../extending/extending.rst:48 +msgid "" +">>> import spam\n" +">>> status = spam.system(\"ls -l\")" +msgstr "" +">>> import spam\n" +">>> status = spam.system(\"ls -l\")" + +#: ../../extending/extending.rst:53 +msgid "" +"Begin by creating a file :file:`spammodule.c`. (Historically, if a module " +"is called ``spam``, the C file containing its implementation is called :file:" +"`spammodule.c`; if the module name is very long, like ``spammify``, the " +"module name can be just :file:`spammify.c`.)" +msgstr "" +"首先建立一個檔案 :file:`spammodule.c`。（從過去歷史來看，如果一個模組叫做 " +"``spam``，包含其實作的 C 檔案就會叫做 :file:`spammodule.c`；如果模組名稱很" +"長，像是 ``spammify``，模組名稱也可以只是 :file:`spammify.c`）。" + +#: ../../extending/extending.rst:58 +msgid "The first two lines of our file can be::" +msgstr "我們檔案的前兩列可以為： ::" + +#: ../../extending/extending.rst:60 ../../extending/extending.rst:706 +msgid "" +"#define PY_SSIZE_T_CLEAN\n" +"#include " +msgstr "" +"#define PY_SSIZE_T_CLEAN\n" +"#include " + +#: ../../extending/extending.rst:63 +msgid "" +"which pulls in the Python API (you can add a comment describing the purpose " +"of the module and a copyright notice if you like)." +msgstr "" +"這會將 Python API 拉進來（你可以加入註解來說明模組的目的，也可以加入版權聲" +"明)。" + +#: ../../extending/extending.rst:68 +msgid "" +"Since Python may define some pre-processor definitions which affect the " +"standard headers on some systems, you *must* include :file:`Python.h` before " +"any standard headers are included." +msgstr "" +"由於 Python 可能定義一些影響系統上某些標準標頭檔的預處理器定義，你\\ *必須" +"*\\ 在引入任何標準標頭檔之前引入 :file:`Python.h`。" + +#: ../../extending/extending.rst:72 +msgid "" +"``#define PY_SSIZE_T_CLEAN`` was used to indicate that ``Py_ssize_t`` should " +"be used in some APIs instead of ``int``. It is not necessary since Python " +"3.13, but we keep it here for backward compatibility. See :ref:`arg-parsing-" +"string-and-buffers` for a description of this macro." +msgstr "" +"``#define PY_SSIZE_T_CLEAN`` 被用來表示在某些 API 中應該使用 ``Py_ssize_t`` " +"而不是 ``int``。自 Python 3.13 起，它就不再是必要的了，但我們在此保留它以便向" +"後相容。關於這個巨集的描述請參閱 :ref:`arg-parsing-string-and-buffers`。" + +#: ../../extending/extending.rst:77 +msgid "" +"All user-visible symbols defined by :file:`Python.h` have a prefix of ``Py`` " +"or ``PY``, except those defined in standard header files." +msgstr "" + +#: ../../extending/extending.rst:82 +msgid "" +"For backward compatibility, :file:`Python.h` includes several standard " +"header files. C extensions should include the standard headers that they " +"use, and should not rely on these implicit includes. If using the limited C " +"API version 3.13 or newer, the implicit includes are:" +msgstr "" + +#: ../../extending/extending.rst:87 +msgid "````" +msgstr "````" + +#: ../../extending/extending.rst:88 +msgid "```` (on Windows)" +msgstr "````\\ （在 Windows 上）" + +#: ../../extending/extending.rst:89 +msgid "````" +msgstr "````" + +#: ../../extending/extending.rst:90 +msgid "````" +msgstr "````" + +#: ../../extending/extending.rst:91 +msgid "````" +msgstr "````" + +#: ../../extending/extending.rst:92 +msgid "````" +msgstr "````" + +#: ../../extending/extending.rst:93 +msgid "````" +msgstr "````" + +#: ../../extending/extending.rst:94 +msgid "```` (if present)" +msgstr "````\\ （如果存在）" + +#: ../../extending/extending.rst:96 +msgid "" +"If :c:macro:`Py_LIMITED_API` is not defined, or is set to version 3.12 or " +"older, the headers below are also included:" +msgstr "" + +#: ../../extending/extending.rst:99 +msgid "````" +msgstr "````" + +#: ../../extending/extending.rst:100 +msgid "```` (on POSIX)" +msgstr "````\\ （在 POSIX 上）" + +#: ../../extending/extending.rst:102 +msgid "" +"If :c:macro:`Py_LIMITED_API` is not defined, or is set to version 3.10 or " +"older, the headers below are also included:" +msgstr "" + +#: ../../extending/extending.rst:105 +msgid "````" +msgstr "````" + +#: ../../extending/extending.rst:106 +msgid "````" +msgstr "````" + +#: ../../extending/extending.rst:107 +msgid "````" +msgstr "````" + +#: ../../extending/extending.rst:108 +msgid "````" +msgstr "````" + +#: ../../extending/extending.rst:110 +msgid "" +"The next thing we add to our module file is the C function that will be " +"called when the Python expression ``spam.system(string)`` is evaluated " +"(we'll see shortly how it ends up being called)::" +msgstr "" +"接下來我們要加入到模組檔案的是 C 函式，當 Python 運算式 ``spam." +"system(string)`` 要被求值 (evaluated) 時就會被呼叫（我們很快就會看到它最後是" +"如何被呼叫的）： ::" + +#: ../../extending/extending.rst:114 +msgid "" +"static PyObject *\n" +"spam_system(PyObject *self, PyObject *args)\n" +"{\n" +" const char *command;\n" +" int sts;\n" +"\n" +" if (!PyArg_ParseTuple(args, \"s\", &command))\n" +" return NULL;\n" +" sts = system(command);\n" +" return PyLong_FromLong(sts);\n" +"}" +msgstr "" +"static PyObject *\n" +"spam_system(PyObject *self, PyObject *args)\n" +"{\n" +" const char *command;\n" +" int sts;\n" +"\n" +" if (!PyArg_ParseTuple(args, \"s\", &command))\n" +" return NULL;\n" +" sts = system(command);\n" +" return PyLong_FromLong(sts);\n" +"}" + +#: ../../extending/extending.rst:126 +msgid "" +"There is a straightforward translation from the argument list in Python (for " +"example, the single expression ``\"ls -l\"``) to the arguments passed to the " +"C function. The C function always has two arguments, conventionally named " +"*self* and *args*." +msgstr "" +"可以很直觀地從 Python 的引數串列（例如單一的運算式 ``\"ls -l\"``）直接轉換成" +"傳給 C 函式的引數。C 函式總是有兩個引數，習慣上會命名為 *self* 和 *args*。" + +#: ../../extending/extending.rst:131 +msgid "" +"The *self* argument points to the module object for module-level functions; " +"for a method it would point to the object instance." +msgstr "" +"對於模組層級的函式，*self* 引數會指向模組物件；而對於方法來說則是指向物件的實" +"例。" + +#: ../../extending/extending.rst:134 +msgid "" +"The *args* argument will be a pointer to a Python tuple object containing " +"the arguments. Each item of the tuple corresponds to an argument in the " +"call's argument list. The arguments are Python objects --- in order to do " +"anything with them in our C function we have to convert them to C values. " +"The function :c:func:`PyArg_ParseTuple` in the Python API checks the " +"argument types and converts them to C values. It uses a template string to " +"determine the required types of the arguments as well as the types of the C " +"variables into which to store the converted values. More about this later." +msgstr "" +"*args* 引數會是一個指向包含引數的 Python 元組物件的指標。元組中的每一項都對應" +"於呼叫的引數串列中的一個引數。引數是 Python 物件 --- 為了在我們的 C 函式中對" +"它們做任何事情，我們必須先將它們轉換成 C 值。Python API 中的 :c:func:" +"`PyArg_ParseTuple` 函式能夠檢查引數型別並將他們轉換為 C 值。它使用模板字串來" +"決定所需的引數型別以及儲存轉換值的 C 變數型別。稍後會再詳細說明。" + +#: ../../extending/extending.rst:143 +msgid "" +":c:func:`PyArg_ParseTuple` returns true (nonzero) if all arguments have the " +"right type and its components have been stored in the variables whose " +"addresses are passed. It returns false (zero) if an invalid argument list " +"was passed. In the latter case it also raises an appropriate exception so " +"the calling function can return ``NULL`` immediately (as we saw in the " +"example)." +msgstr "" +"如果所有的引數都有正確的型別，且其元件已儲存在傳入位址的變數中，則 :c:func:" +"`PyArg_ParseTuple` 會回傳 true（非零）。如果傳入的是無效引數串列則回傳 false" +"（零）。在後者情況下，它也會產生適當的例外，因此呼叫函式可以立即回傳 " +"``NULL``\\ （就像我們在範例中所看到的）。" + +#: ../../extending/extending.rst:153 +msgid "Intermezzo: Errors and Exceptions" +msgstr "插曲：錯誤與例外" + +#: ../../extending/extending.rst:155 +msgid "" +"An important convention throughout the Python interpreter is the following: " +"when a function fails, it should set an exception condition and return an " +"error value (usually ``-1`` or a ``NULL`` pointer). Exception information " +"is stored in three members of the interpreter's thread state. These are " +"``NULL`` if there is no exception. Otherwise they are the C equivalents of " +"the members of the Python tuple returned by :meth:`sys.exc_info`. These are " +"the exception type, exception instance, and a traceback object. It is " +"important to know about them to understand how errors are passed around." +msgstr "" +"在整個 Python 直譯器中的一個重要慣例為：當一個函式失敗時，它就應該設定一個例" +"外條件，並回傳一個錯誤值（通常是 ``-1`` 或一個 ``NULL`` 指標）。例外資訊會儲" +"存在直譯器執行緒狀態的三個成員中。如果沒有例外，它們就會是 ``NULL``。否則，它" +"們是由 :meth:`sys.exc_info` 所回傳的 Python 元組中的 C 等效元組。它們是例外型" +"別、例外實例和回溯物件。了解它們對於理解錯誤是如何傳遞是很重要的。" + +#: ../../extending/extending.rst:164 +msgid "" +"The Python API defines a number of functions to set various types of " +"exceptions." +msgstr "Python API 定義了許多能夠設定各種類型例外的函式。" + +#: ../../extending/extending.rst:166 +msgid "" +"The most common one is :c:func:`PyErr_SetString`. Its arguments are an " +"exception object and a C string. The exception object is usually a " +"predefined object like :c:data:`PyExc_ZeroDivisionError`. The C string " +"indicates the cause of the error and is converted to a Python string object " +"and stored as the \"associated value\" of the exception." +msgstr "" +"最常見的是 :c:func:`PyErr_SetString`。它的引數是一個例外物件和一個 C 字串。例" +"外物件通常是預先定義的物件，例如 :c:data:`PyExc_ZeroDivisionError`。C 字串則" +"指出錯誤的原因，並被轉換為 Python 字串物件且被儲存為例外的「關聯值 " +"(associated value)」。" + +#: ../../extending/extending.rst:172 +msgid "" +"Another useful function is :c:func:`PyErr_SetFromErrno`, which only takes an " +"exception argument and constructs the associated value by inspection of the " +"global variable :c:data:`errno`. The most general function is :c:func:" +"`PyErr_SetObject`, which takes two object arguments, the exception and its " +"associated value. You don't need to :c:func:`Py_INCREF` the objects passed " +"to any of these functions." +msgstr "" +"另一個有用的函式是 :c:func:`PyErr_SetFromErrno`，它只接受一個例外引數，並透過" +"檢查全域變數 :c:data:`errno` 來建立關聯值。最一般的函式是 :c:func:" +"`PyErr_SetObject`，它接受兩個物件引數，即例外和它的關聯值。你不需要對傳給任何" +"這些函式的物件呼叫 :c:func:`Py_INCREF`。" + +#: ../../extending/extending.rst:179 +msgid "" +"You can test non-destructively whether an exception has been set with :c:" +"func:`PyErr_Occurred`. This returns the current exception object, or " +"``NULL`` if no exception has occurred. You normally don't need to call :c:" +"func:`PyErr_Occurred` to see whether an error occurred in a function call, " +"since you should be able to tell from the return value." +msgstr "" +"你可以使用 :c:func:`PyErr_Occurred` 來不具破壞性地測試例外是否已被設定。這會" +"回傳目前的例外物件，如果沒有例外發生則回傳 ``NULL``。你通常不需要呼叫 :c:" +"func:`PyErr_Occurred` 來查看函式呼叫是否發生錯誤，因為你應可從回傳值就得知。" + +#: ../../extending/extending.rst:185 +msgid "" +"When a function *f* that calls another function *g* detects that the latter " +"fails, *f* should itself return an error value (usually ``NULL`` or " +"``-1``). It should *not* call one of the ``PyErr_*`` functions --- one has " +"already been called by *g*. *f*'s caller is then supposed to also return an " +"error indication to *its* caller, again *without* calling ``PyErr_*``, and " +"so on --- the most detailed cause of the error was already reported by the " +"function that first detected it. Once the error reaches the Python " +"interpreter's main loop, this aborts the currently executing Python code and " +"tries to find an exception handler specified by the Python programmer." +msgstr "" +"當函式 *f* 呼叫另一個函式 *g* 時檢測到後者失敗，*f* 本身應該回傳一個錯誤值" +"（通常是 ``NULL`` 或 ``-1``）。它\\ *不*\\ 應該呼叫 ``PyErr_*`` 函式的其中一" +"個，這會已被 *g* 呼叫過。*f* 的呼叫者然後也應該回傳一個錯誤指示給\\ *它的*\\ " +"呼叫者，同樣\\ *不會*\\ 呼叫 ``PyErr_*``，依此類推 --- 最詳細的錯誤原因已經被" +"首先檢測到它的函式回報了。一旦錯誤到達 Python 直譯器的主要迴圈，這會中止目前" +"執行的 Python 程式碼，並嘗試尋找 Python 程式設計者指定的例外處理程式。" + +#: ../../extending/extending.rst:195 +msgid "" +"(There are situations where a module can actually give a more detailed error " +"message by calling another ``PyErr_*`` function, and in such cases it is " +"fine to do so. As a general rule, however, this is not necessary, and can " +"cause information about the cause of the error to be lost: most operations " +"can fail for a variety of reasons.)" +msgstr "" +"（在某些情況下，模組可以透過呼叫另一個 ``PyErr_*`` 函式來提供更詳細的錯誤訊" +"息，在這種情況下這樣做是沒問題的。然而這一般來說並非必要，而且可能會導致錯誤" +"原因資訊的遺失：大多數的操作都可能因為各種原因而失敗。）" + +#: ../../extending/extending.rst:201 +msgid "" +"To ignore an exception set by a function call that failed, the exception " +"condition must be cleared explicitly by calling :c:func:`PyErr_Clear`. The " +"only time C code should call :c:func:`PyErr_Clear` is if it doesn't want to " +"pass the error on to the interpreter but wants to handle it completely by " +"itself (possibly by trying something else, or pretending nothing went wrong)." +msgstr "" +"要忽略由函式呼叫失敗所設定的例外，必須明確地呼叫 :c:func:`PyErr_Clear` 來清除" +"例外條件。C 程式碼唯一要呼叫 :c:func:`PyErr_Clear` 的情況為當它不想將錯誤傳遞" +"給直譯器而想要完全是自己來處理它時（可能是要再嘗試其他東西，或者假裝什麼都沒" +"出錯）。" + +#: ../../extending/extending.rst:207 +msgid "" +"Every failing :c:func:`malloc` call must be turned into an exception --- the " +"direct caller of :c:func:`malloc` (or :c:func:`realloc`) must call :c:func:" +"`PyErr_NoMemory` and return a failure indicator itself. All the object-" +"creating functions (for example, :c:func:`PyLong_FromLong`) already do this, " +"so this note is only relevant to those who call :c:func:`malloc` directly." +msgstr "" +"每個失敗的 :c:func:`malloc` 呼叫都必須被轉換成一個例外 --- :c:func:" +"`malloc`\\ （或 :c:func:`realloc`）的直接呼叫者必須呼叫 :c:func:" +"`PyErr_NoMemory` 並回傳一個失敗指示器。所有建立物件的函式（例如 :c:func:" +"`PyLong_FromLong`）都已經這麼做了，所以這個注意事項只和那些直接呼叫 :c:func:" +"`malloc` 的函式有關。" + +#: ../../extending/extending.rst:213 +msgid "" +"Also note that, with the important exception of :c:func:`PyArg_ParseTuple` " +"and friends, functions that return an integer status usually return a " +"positive value or zero for success and ``-1`` for failure, like Unix system " +"calls." +msgstr "" +"還要注意的是，有 :c:func:`PyArg_ParseTuple` 及同系列函式的這些重要例外，回傳" +"整數狀態的函式通常會回傳一個正值或 0 表示成功、回傳 ``-1`` 表示失敗，就像 " +"Unix 系統呼叫一樣。" + +#: ../../extending/extending.rst:217 +msgid "" +"Finally, be careful to clean up garbage (by making :c:func:`Py_XDECREF` or :" +"c:func:`Py_DECREF` calls for objects you have already created) when you " +"return an error indicator!" +msgstr "" +"最後，在回傳錯誤指示器時要注意垃圾清理（透過對你已經建立的物件呼叫 :c:func:" +"`Py_XDECREF` 或 :c:func:`Py_DECREF`）！" + +#: ../../extending/extending.rst:221 +msgid "" +"The choice of which exception to raise is entirely yours. There are " +"predeclared C objects corresponding to all built-in Python exceptions, such " +"as :c:data:`PyExc_ZeroDivisionError`, which you can use directly. Of course, " +"you should choose exceptions wisely --- don't use :c:data:`PyExc_TypeError` " +"to mean that a file couldn't be opened (that should probably be :c:data:" +"`PyExc_OSError`). If something's wrong with the argument list, the :c:func:" +"`PyArg_ParseTuple` function usually raises :c:data:`PyExc_TypeError`. If " +"you have an argument whose value must be in a particular range or must " +"satisfy other conditions, :c:data:`PyExc_ValueError` is appropriate." +msgstr "" +"你完全可以自行選擇要產生的例外。有一些預先宣告的 C 物件會對應到所有內建的 " +"Python 例外，例如 :c:data:`PyExc_ZeroDivisionError`，你可以直接使用它們。當" +"然，你應該明智地選擇例外，像是不要使用 :c:data:`PyExc_TypeError` 來表示檔案無" +"法打開（應該是 :c:data:`PyExc_OSError`）。如果引數串列有問題，:c:func:" +"`PyArg_ParseTuple` 函式通常會引發 :c:data:`PyExc_TypeError`。如果你有一個引數" +"的值必須在一個特定的範圍內或必須滿足其他條件，則可以使用 :c:data:" +"`PyExc_ValueError`。" + +#: ../../extending/extending.rst:231 +msgid "" +"You can also define a new exception that is unique to your module. The " +"simplest way to do this is to declare a static global object variable at the " +"beginning of the file::" +msgstr "" +"你也可以定義一個你的模組特有的新例外。最簡單的方式是在檔案的開頭宣告一個靜態" +"全域物件變數： ::" + +#: ../../extending/extending.rst:235 +msgid "static PyObject *SpamError = NULL;" +msgstr "static PyObject *SpamError = NULL;" + +#: ../../extending/extending.rst:237 +msgid "" +"and initialize it by calling :c:func:`PyErr_NewException` in the module's :c:" +"data:`Py_mod_exec` function (:c:func:`!spam_module_exec`)::" +msgstr "" + +#: ../../extending/extending.rst:240 +msgid "SpamError = PyErr_NewException(\"spam.error\", NULL, NULL);" +msgstr "" + +#: ../../extending/extending.rst:242 +msgid "" +"Since :c:data:`!SpamError` is a global variable, it will be overwritten " +"every time the module is reinitialized, when the :c:data:`Py_mod_exec` " +"function is called." +msgstr "" + +#: ../../extending/extending.rst:245 +msgid "" +"For now, let's avoid the issue: we will block repeated initialization by " +"raising an :py:exc:`ImportError`::" +msgstr "" + +#: ../../extending/extending.rst:248 +msgid "" +"static PyObject *SpamError = NULL;\n" +"\n" +"static int\n" +"spam_module_exec(PyObject *m)\n" +"{\n" +" if (SpamError != NULL) {\n" +" PyErr_SetString(PyExc_ImportError,\n" +" \"cannot initialize spam module more than once\");\n" +" return -1;\n" +" }\n" +" SpamError = PyErr_NewException(\"spam.error\", NULL, NULL);\n" +" if (PyModule_AddObjectRef(m, \"SpamError\", SpamError) < 0) {\n" +" return -1;\n" +" }\n" +"\n" +" return 0;\n" +"}\n" +"\n" +"static PyModuleDef_Slot spam_module_slots[] = {\n" +" {Py_mod_exec, spam_module_exec},\n" +" {0, NULL}\n" +"};\n" +"\n" +"static struct PyModuleDef spam_module = {\n" +" .m_base = PyModuleDef_HEAD_INIT,\n" +" .m_name = \"spam\",\n" +" .m_size = 0, // non-negative\n" +" .m_slots = spam_module_slots,\n" +"};\n" +"\n" +"PyMODINIT_FUNC\n" +"PyInit_spam(void)\n" +"{\n" +" return PyModuleDef_Init(&spam_module);\n" +"}" +msgstr "" + +#: ../../extending/extending.rst:284 +msgid "" +"Note that the Python name for the exception object is :exc:`!spam.error`. " +"The :c:func:`PyErr_NewException` function may create a class with the base " +"class being :exc:`Exception` (unless another class is passed in instead of " +"``NULL``), described in :ref:`bltin-exceptions`." +msgstr "" +"請注意，例外物件的 Python 名稱是 :exc:`!spam.error`。如同\\ :ref:`bltin-" +"exceptions`\\ 所述，:c:func:`PyErr_NewException` 函式可能會建立一個基底類別" +"為 :exc:`Exception` 的類別（除非傳入另一個類別來代替 ``NULL``）。" + +#: ../../extending/extending.rst:289 +msgid "" +"Note also that the :c:data:`!SpamError` variable retains a reference to the " +"newly created exception class; this is intentional! Since the exception " +"could be removed from the module by external code, an owned reference to the " +"class is needed to ensure that it will not be discarded, causing :c:data:`!" +"SpamError` to become a dangling pointer. Should it become a dangling " +"pointer, C code which raises the exception could cause a core dump or other " +"unintended side effects." +msgstr "" +"請注意，:c:data:`!SpamError` 變數保留了對新建立的例外類別的參照；這是故意的！" +"因為外部程式碼可能會從模組中移除這個例外，所以需要一個對這個類別的參照來確保" +"它不會被丟棄而導致 :c:data:`!SpamError` 變成一個迷途指標 (dangling pointer)。" +"如果它變成迷途指標，那產生例外的 C 程式碼可能會導致核心轉儲 (core dump) 或其" +"他不預期的 side effect。" + +#: ../../extending/extending.rst:296 +msgid "" +"For now, the :c:func:`Py_DECREF` call to remove this reference is missing. " +"Even when the Python interpreter shuts down, the global :c:data:`!SpamError` " +"variable will not be garbage-collected. It will \"leak\". We did, however, " +"ensure that this will happen at most once per process." +msgstr "" + +#: ../../extending/extending.rst:301 +msgid "" +"We discuss the use of :c:macro:`PyMODINIT_FUNC` as a function return type " +"later in this sample." +msgstr "我們稍後會討論 :c:macro:`PyMODINIT_FUNC` 作為函式回傳型別的用法。" + +#: ../../extending/extending.rst:304 +msgid "" +"The :exc:`!spam.error` exception can be raised in your extension module " +"using a call to :c:func:`PyErr_SetString` as shown below::" +msgstr "" +"可以在你的擴充模組中呼叫 :c:func:`PyErr_SetString` 來引發 :exc:`!spam.error` " +"例外，如下所示： ::" + +#: ../../extending/extending.rst:307 +msgid "" +"static PyObject *\n" +"spam_system(PyObject *self, PyObject *args)\n" +"{\n" +" const char *command;\n" +" int sts;\n" +"\n" +" if (!PyArg_ParseTuple(args, \"s\", &command))\n" +" return NULL;\n" +" sts = system(command);\n" +" if (sts < 0) {\n" +" PyErr_SetString(SpamError, \"System command failed\");\n" +" return NULL;\n" +" }\n" +" return PyLong_FromLong(sts);\n" +"}" +msgstr "" +"static PyObject *\n" +"spam_system(PyObject *self, PyObject *args)\n" +"{\n" +" const char *command;\n" +" int sts;\n" +"\n" +" if (!PyArg_ParseTuple(args, \"s\", &command))\n" +" return NULL;\n" +" sts = system(command);\n" +" if (sts < 0) {\n" +" PyErr_SetString(SpamError, \"System command failed\");\n" +" return NULL;\n" +" }\n" +" return PyLong_FromLong(sts);\n" +"}" + +#: ../../extending/extending.rst:327 +msgid "Back to the Example" +msgstr "回到範例" + +#: ../../extending/extending.rst:329 +msgid "" +"Going back to our example function, you should now be able to understand " +"this statement::" +msgstr "回到我們的範例函式，現在你應該可以理解這個陳述式了： ::" + +#: ../../extending/extending.rst:332 +msgid "" +"if (!PyArg_ParseTuple(args, \"s\", &command))\n" +" return NULL;" +msgstr "" +"if (!PyArg_ParseTuple(args, \"s\", &command))\n" +" return NULL;" + +#: ../../extending/extending.rst:335 +msgid "" +"It returns ``NULL`` (the error indicator for functions returning object " +"pointers) if an error is detected in the argument list, relying on the " +"exception set by :c:func:`PyArg_ParseTuple`. Otherwise the string value of " +"the argument has been copied to the local variable :c:data:`!command`. This " +"is a pointer assignment and you are not supposed to modify the string to " +"which it points (so in Standard C, the variable :c:data:`!command` should " +"properly be declared as ``const char *command``)." +msgstr "" +"如果在引數串列中檢測到錯誤則會回傳 ``NULL``\\ （回傳物件指標之函式的錯誤指示" +"器），其依賴於 :c:func:`PyArg_ParseTuple` 設定的例外，否則引數的字串值會已被" +"複製到區域變數 :c:data:`!command` 中。這是一個指標賦值，你不應該修改它所指向" +"的字串（所以在標準 C 中，:c:data:`!command` 變數應該正確地被宣告為 ``const " +"char *command``）。" + +#: ../../extending/extending.rst:343 +msgid "" +"The next statement is a call to the Unix function :c:func:`system`, passing " +"it the string we just got from :c:func:`PyArg_ParseTuple`::" +msgstr "" +"接下來的陳述式會呼叫 Unix 函式 :c:func:`system`，並將剛才從 :c:func:" +"`PyArg_ParseTuple` 得到的字串傳給它：" + +#: ../../extending/extending.rst:346 +msgid "sts = system(command);" +msgstr "sts = system(command);" + +#: ../../extending/extending.rst:348 +msgid "" +"Our :func:`!spam.system` function must return the value of :c:data:`!sts` as " +"a Python object. This is done using the function :c:func:" +"`PyLong_FromLong`. ::" +msgstr "" +"我們的 :func:`!spam.system` 函式必須以 Python 物件的形式來回傳 :c:data:`!" +"sts` 的值。這是透過 :c:func:`PyLong_FromLong` 函式來達成。 ::" + +#: ../../extending/extending.rst:351 +msgid "return PyLong_FromLong(sts);" +msgstr "return PyLong_FromLong(sts);" + +#: ../../extending/extending.rst:353 +msgid "" +"In this case, it will return an integer object. (Yes, even integers are " +"objects on the heap in Python!)" +msgstr "" +"在這種情況下它會回傳一個整數物件。(是的，在 Python 中連整數也是堆積 (heap) 上" +"的物件！)" + +#: ../../extending/extending.rst:356 +msgid "" +"If you have a C function that returns no useful argument (a function " +"returning :c:expr:`void`), the corresponding Python function must return " +"``None``. You need this idiom to do so (which is implemented by the :c:" +"macro:`Py_RETURN_NONE` macro)::" +msgstr "" +"如果你有一個不回傳任何有用引數的 C 函式（一個回傳 :c:expr:`void` 的函式），對" +"應的 Python 函式必須回傳 ``None``。你需要以下這個慣例來達成（由 :c:macro:" +"`Py_RETURN_NONE` 巨集實作）： ::" + +#: ../../extending/extending.rst:361 +msgid "" +"Py_INCREF(Py_None);\n" +"return Py_None;" +msgstr "" +"Py_INCREF(Py_None);\n" +"return Py_None;" + +#: ../../extending/extending.rst:364 +msgid "" +":c:data:`Py_None` is the C name for the special Python object ``None``. It " +"is a genuine Python object rather than a ``NULL`` pointer, which means " +"\"error\" in most contexts, as we have seen." +msgstr "" +":c:data:`Py_None` 是特殊 Python 物件 ``None`` 的 C 名稱。它是一個真正的 " +"Python 物件而不是一個 ``NULL`` 指標，在大多數的情況下它的意思是「錯誤」，如我" +"們所見過的那樣。" + +#: ../../extending/extending.rst:372 +msgid "The Module's Method Table and Initialization Function" +msgstr "模組的方法表和初始化函式" + +#: ../../extending/extending.rst:374 +msgid "" +"I promised to show how :c:func:`!spam_system` is called from Python " +"programs. First, we need to list its name and address in a \"method table\"::" +msgstr "" +"我承諾過要展示 :c:func:`!spam_system` 是如何從 Python 程式中呼叫的。首先，我" +"們需要在「方法表」中列出它的名稱和位址： ::" + +#: ../../extending/extending.rst:377 +msgid "" +"static PyMethodDef spam_methods[] = {\n" +" ...\n" +" {\"system\", spam_system, METH_VARARGS,\n" +" \"Execute a shell command.\"},\n" +" ...\n" +" {NULL, NULL, 0, NULL} /* Sentinel */\n" +"};" +msgstr "" +"static PyMethodDef spam_methods[] = {\n" +" ...\n" +" {\"system\", spam_system, METH_VARARGS,\n" +" \"Execute a shell command.\"},\n" +" ...\n" +" {NULL, NULL, 0, NULL} /* Sentinel */\n" +"};" + +#: ../../extending/extending.rst:385 +msgid "" +"Note the third entry (``METH_VARARGS``). This is a flag telling the " +"interpreter the calling convention to be used for the C function. It should " +"normally always be ``METH_VARARGS`` or ``METH_VARARGS | METH_KEYWORDS``; a " +"value of ``0`` means that an obsolete variant of :c:func:`PyArg_ParseTuple` " +"is used." +msgstr "" +"請注意第三個項目 (``METH_VARARGS``)。這是一個告訴直譯器 C 函式之呼叫方式的旗" +"標。通常應該是 ``METH_VARARGS`` 或 ``METH_VARARGS | METH_KEYWORDS``；``0`` 表" +"示是使用 :c:func:`PyArg_ParseTuple` 的一個過時變體。" + +#: ../../extending/extending.rst:390 +msgid "" +"When using only ``METH_VARARGS``, the function should expect the Python-" +"level parameters to be passed in as a tuple acceptable for parsing via :c:" +"func:`PyArg_ParseTuple`; more information on this function is provided below." +msgstr "" +"當只使用 ``METH_VARARGS`` 時，函式應預期 Python 層級的參數是以元組形式傳入且" +"能夠接受以 :c:func:`PyArg_ParseTuple` 進行剖析；有關此函式的更多資訊將在下面" +"提供。" + +#: ../../extending/extending.rst:394 +msgid "" +"The :c:macro:`METH_KEYWORDS` bit may be set in the third field if keyword " +"arguments should be passed to the function. In this case, the C function " +"should accept a third ``PyObject *`` parameter which will be a dictionary of " +"keywords. Use :c:func:`PyArg_ParseTupleAndKeywords` to parse the arguments " +"to such a function." +msgstr "" +"如果要將關鍵字引數傳給函式，可以在第三個欄位設定 :c:macro:`METH_KEYWORDS` 位" +"元。在這種情況下，C 函式應該要能接受第三個 ``PyObject *`` 參數，這個參數將會" +"是關鍵字的字典。可使用 :c:func:`PyArg_ParseTupleAndKeywords` 來剖析這種函式的" +"引數。" + +#: ../../extending/extending.rst:400 +msgid "" +"The method table must be referenced in the module definition structure::" +msgstr "方法表必須在模組定義結構中被參照： ::" + +#: ../../extending/extending.rst:402 +msgid "" +"static struct PyModuleDef spam_module = {\n" +" ...\n" +" .m_methods = spam_methods,\n" +" ...\n" +"};" +msgstr "" + +#: ../../extending/extending.rst:408 +msgid "" +"This structure, in turn, must be passed to the interpreter in the module's " +"initialization function. The initialization function must be named :c:func:" +"`!PyInit_name`, where *name* is the name of the module, and should be the " +"only non-\\ ``static`` item defined in the module file::" +msgstr "" +"反過來說，這個結構必須在模組的初始化函式中被傳給直譯器。初始化函式必須被命名" +"為 :c:func:`!PyInit_name`，其中 *name* 是模組的名稱，且應該是模組檔案中唯一定" +"義的非「靜態 (``static``)」項目： ::" + +#: ../../extending/extending.rst:413 +msgid "" +"PyMODINIT_FUNC\n" +"PyInit_spam(void)\n" +"{\n" +" return PyModuleDef_Init(&spam_module);\n" +"}" +msgstr "" +"PyMODINIT_FUNC\n" +"PyInit_spam(void)\n" +"{\n" +" return PyModuleDef_Init(&spam_module);\n" +"}" + +#: ../../extending/extending.rst:419 +msgid "" +"Note that :c:macro:`PyMODINIT_FUNC` declares the function as ``PyObject *`` " +"return type, declares any special linkage declarations required by the " +"platform, and for C++ declares the function as ``extern \"C\"``." +msgstr "" +"請注意，:c:macro:`PyMODINIT_FUNC` 宣告函式的回傳型別為 ``PyObject *``、宣告平" +"台所需的任何特殊連結宣告、並針對 C++ 宣告函式為 ``extern \"C\"``。" + +#: ../../extending/extending.rst:423 +msgid "" +":c:func:`!PyInit_spam` is called when each interpreter imports its module :" +"mod:`!spam` for the first time. (See below for comments about embedding " +"Python.) A pointer to the module definition must be returned via :c:func:" +"`PyModuleDef_Init`, so that the import machinery can create the module and " +"store it in ``sys.modules``." +msgstr "" + +#: ../../extending/extending.rst:428 +msgid "" +"When embedding Python, the :c:func:`!PyInit_spam` function is not called " +"automatically unless there's an entry in the :c:data:`PyImport_Inittab` " +"table. To add the module to the initialization table, use :c:func:" +"`PyImport_AppendInittab`, optionally followed by an import of the module::" +msgstr "" +"嵌入 Python 時，除非在 :c:data:`PyImport_Inittab` 表中有相關條目，否則不會自" +"動呼叫 :c:func:`!PyInit_spam` 函式。要將模組加入初始化表，請使用 :c:func:" +"`PyImport_AppendInittab` 並在隨後選擇性地將該模組引入： ::" + +#: ../../extending/extending.rst:433 +msgid "" +"#define PY_SSIZE_T_CLEAN\n" +"#include \n" +"\n" +"int\n" +"main(int argc, char *argv[])\n" +"{\n" +" PyStatus status;\n" +" PyConfig config;\n" +" PyConfig_InitPythonConfig(&config);\n" +"\n" +" /* Add a built-in module, before Py_Initialize */\n" +" if (PyImport_AppendInittab(\"spam\", PyInit_spam) == -1) {\n" +" fprintf(stderr, \"Error: could not extend in-built modules " +"table\\n\");\n" +" exit(1);\n" +" }\n" +"\n" +" /* Pass argv[0] to the Python interpreter */\n" +" status = PyConfig_SetBytesString(&config, &config.program_name, " +"argv[0]);\n" +" if (PyStatus_Exception(status)) {\n" +" goto exception;\n" +" }\n" +"\n" +" /* Initialize the Python interpreter. Required.\n" +" If this step fails, it will be a fatal error. */\n" +" status = Py_InitializeFromConfig(&config);\n" +" if (PyStatus_Exception(status)) {\n" +" goto exception;\n" +" }\n" +" PyConfig_Clear(&config);\n" +"\n" +" /* Optionally import the module; alternatively,\n" +" import can be deferred until the embedded script\n" +" imports it. */\n" +" PyObject *pmodule = PyImport_ImportModule(\"spam\");\n" +" if (!pmodule) {\n" +" PyErr_Print();\n" +" fprintf(stderr, \"Error: could not import module 'spam'\\n\");\n" +" }\n" +"\n" +" // ... use Python C API here ...\n" +"\n" +" return 0;\n" +"\n" +" exception:\n" +" PyConfig_Clear(&config);\n" +" Py_ExitStatusException(status);\n" +"}" +msgstr "" +"#define PY_SSIZE_T_CLEAN\n" +"#include \n" +"\n" +"int\n" +"main(int argc, char *argv[])\n" +"{\n" +" PyStatus status;\n" +" PyConfig config;\n" +" PyConfig_InitPythonConfig(&config);\n" +"\n" +" /* 在 Py_Initialize 之前加入內建模組 */\n" +" if (PyImport_AppendInittab(\"spam\", PyInit_spam) == -1) {\n" +" fprintf(stderr, \"Error: could not extend in-built modules " +"table\\n\");\n" +" exit(1);\n" +" }\n" +"\n" +" /* 將 argv[0] 傳給 Python 直譯器 */\n" +" status = PyConfig_SetBytesString(&config, &config.program_name, " +"argv[0]);\n" +" if (PyStatus_Exception(status)) {\n" +" goto exception;\n" +" }\n" +"\n" +" /* 初始化 Python 直譯器。這會是必要的。\n" +" 如果此步驟失敗就會導致嚴重錯誤。*/\n" +" status = Py_InitializeFromConfig(&config);\n" +" if (PyStatus_Exception(status)) {\n" +" goto exception;\n" +" }\n" +" PyConfig_Clear(&config);\n" +"\n" +" /* 可選擇引入模組；或者\n" +" 可以延遲引入，直至嵌入式腳本\n" +" 將其引入。*/\n" +" PyObject *pmodule = PyImport_ImportModule(\"spam\");\n" +" if (!pmodule) {\n" +" PyErr_Print();\n" +" fprintf(stderr, \"Error: could not import module 'spam'\\n\");\n" +" }\n" +"\n" +" // ... 在此使用 Python C API ...\n" +"\n" +" return 0;\n" +"\n" +" exception:\n" +" PyConfig_Clear(&config);\n" +" Py_ExitStatusException(status);\n" +"}" + +#: ../../extending/extending.rst:483 +msgid "" +"If you declare a global variable or a local static one, the module may " +"experience unintended side-effects on re-initialisation, for example when " +"removing entries from ``sys.modules`` or importing compiled modules into " +"multiple interpreters within a process (or following a :c:func:`fork` " +"without an intervening :c:func:`exec`). If module state is not yet fully :" +"ref:`isolated `, authors should consider marking " +"the module as having no support for subinterpreters (via :c:macro:" +"`Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED`)." +msgstr "" + +#: ../../extending/extending.rst:492 +msgid "" +"A more substantial example module is included in the Python source " +"distribution as :file:`Modules/xxlimited.c`. This file may be used as a " +"template or simply read as an example." +msgstr "" +"Python 原始碼發行版本中包含了一個更實質的範例模組 :file:`Modules/xxlimited." +"c`。這個檔案可以當作模板使用，也可以簡單地當作範例來閱讀。" + +#: ../../extending/extending.rst:500 +msgid "Compilation and Linkage" +msgstr "" + +#: ../../extending/extending.rst:502 +msgid "" +"There are two more things to do before you can use your new extension: " +"compiling and linking it with the Python system. If you use dynamic " +"loading, the details may depend on the style of dynamic loading your system " +"uses; see the chapters about building extension modules (chapter :ref:" +"`building`) and additional information that pertains only to building on " +"Windows (chapter :ref:`building-on-windows`) for more information about this." +msgstr "" + +#: ../../extending/extending.rst:509 +msgid "" +"If you can't use dynamic loading, or if you want to make your module a " +"permanent part of the Python interpreter, you will have to change the " +"configuration setup and rebuild the interpreter. Luckily, this is very " +"simple on Unix: just place your file (:file:`spammodule.c` for example) in " +"the :file:`Modules/` directory of an unpacked source distribution, add a " +"line to the file :file:`Modules/Setup.local` describing your file:" +msgstr "" + +#: ../../extending/extending.rst:516 +msgid "spam spammodule.o" +msgstr "spam spammodule.o" + +#: ../../extending/extending.rst:520 +msgid "" +"and rebuild the interpreter by running :program:`make` in the toplevel " +"directory. You can also run :program:`make` in the :file:`Modules/` " +"subdirectory, but then you must first rebuild :file:`Makefile` there by " +"running ':program:`make` Makefile'. (This is necessary each time you change " +"the :file:`Setup` file.)" +msgstr "" + +#: ../../extending/extending.rst:526 +msgid "" +"If your module requires additional libraries to link with, these can be " +"listed on the line in the configuration file as well, for instance:" +msgstr "" + +#: ../../extending/extending.rst:529 +msgid "spam spammodule.o -lX11" +msgstr "spam spammodule.o -lX11" + +#: ../../extending/extending.rst:537 +msgid "Calling Python Functions from C" +msgstr "" + +#: ../../extending/extending.rst:539 +msgid "" +"So far we have concentrated on making C functions callable from Python. The " +"reverse is also useful: calling Python functions from C. This is especially " +"the case for libraries that support so-called \"callback\" functions. If a " +"C interface makes use of callbacks, the equivalent Python often needs to " +"provide a callback mechanism to the Python programmer; the implementation " +"will require calling the Python callback functions from a C callback. Other " +"uses are also imaginable." +msgstr "" + +#: ../../extending/extending.rst:547 +msgid "" +"Fortunately, the Python interpreter is easily called recursively, and there " +"is a standard interface to call a Python function. (I won't dwell on how to " +"call the Python parser with a particular string as input --- if you're " +"interested, have a look at the implementation of the :option:`-c` command " +"line option in :file:`Modules/main.c` from the Python source code.)" +msgstr "" + +#: ../../extending/extending.rst:553 +msgid "" +"Calling a Python function is easy. First, the Python program must somehow " +"pass you the Python function object. You should provide a function (or some " +"other interface) to do this. When this function is called, save a pointer " +"to the Python function object (be careful to :c:func:`Py_INCREF` it!) in a " +"global variable --- or wherever you see fit. For example, the following " +"function might be part of a module definition::" +msgstr "" + +#: ../../extending/extending.rst:560 +msgid "" +"static PyObject *my_callback = NULL;\n" +"\n" +"static PyObject *\n" +"my_set_callback(PyObject *dummy, PyObject *args)\n" +"{\n" +" PyObject *result = NULL;\n" +" PyObject *temp;\n" +"\n" +" if (PyArg_ParseTuple(args, \"O:set_callback\", &temp)) {\n" +" if (!PyCallable_Check(temp)) {\n" +" PyErr_SetString(PyExc_TypeError, \"parameter must be " +"callable\");\n" +" return NULL;\n" +" }\n" +" Py_XINCREF(temp); /* Add a reference to new callback */\n" +" Py_XDECREF(my_callback); /* Dispose of previous callback */\n" +" my_callback = temp; /* Remember new callback */\n" +" /* Boilerplate to return \"None\" */\n" +" Py_INCREF(Py_None);\n" +" result = Py_None;\n" +" }\n" +" return result;\n" +"}" +msgstr "" + +#: ../../extending/extending.rst:583 +msgid "" +"This function must be registered with the interpreter using the :c:macro:" +"`METH_VARARGS` flag; this is described in section :ref:`methodtable`. The :" +"c:func:`PyArg_ParseTuple` function and its arguments are documented in " +"section :ref:`parsetuple`." +msgstr "" + +#: ../../extending/extending.rst:588 +msgid "" +"The macros :c:func:`Py_XINCREF` and :c:func:`Py_XDECREF` increment/decrement " +"the reference count of an object and are safe in the presence of ``NULL`` " +"pointers (but note that *temp* will not be ``NULL`` in this context). More " +"info on them in section :ref:`refcounts`." +msgstr "" + +#: ../../extending/extending.rst:595 +msgid "" +"Later, when it is time to call the function, you call the C function :c:func:" +"`PyObject_CallObject`. This function has two arguments, both pointers to " +"arbitrary Python objects: the Python function, and the argument list. The " +"argument list must always be a tuple object, whose length is the number of " +"arguments. To call the Python function with no arguments, pass in ``NULL``, " +"or an empty tuple; to call it with one argument, pass a singleton tuple. :c:" +"func:`Py_BuildValue` returns a tuple when its format string consists of zero " +"or more format codes between parentheses. For example::" +msgstr "" + +#: ../../extending/extending.rst:604 +msgid "" +"int arg;\n" +"PyObject *arglist;\n" +"PyObject *result;\n" +"...\n" +"arg = 123;\n" +"...\n" +"/* Time to call the callback */\n" +"arglist = Py_BuildValue(\"(i)\", arg);\n" +"result = PyObject_CallObject(my_callback, arglist);\n" +"Py_DECREF(arglist);" +msgstr "" + +#: ../../extending/extending.rst:615 +msgid "" +":c:func:`PyObject_CallObject` returns a Python object pointer: this is the " +"return value of the Python function. :c:func:`PyObject_CallObject` is " +"\"reference-count-neutral\" with respect to its arguments. In the example a " +"new tuple was created to serve as the argument list, which is :c:func:" +"`Py_DECREF`\\ -ed immediately after the :c:func:`PyObject_CallObject` call." +msgstr "" + +#: ../../extending/extending.rst:622 +msgid "" +"The return value of :c:func:`PyObject_CallObject` is \"new\": either it is a " +"brand new object, or it is an existing object whose reference count has been " +"incremented. So, unless you want to save it in a global variable, you " +"should somehow :c:func:`Py_DECREF` the result, even (especially!) if you are " +"not interested in its value." +msgstr "" + +#: ../../extending/extending.rst:628 +msgid "" +"Before you do this, however, it is important to check that the return value " +"isn't ``NULL``. If it is, the Python function terminated by raising an " +"exception. If the C code that called :c:func:`PyObject_CallObject` is called " +"from Python, it should now return an error indication to its Python caller, " +"so the interpreter can print a stack trace, or the calling Python code can " +"handle the exception. If this is not possible or desirable, the exception " +"should be cleared by calling :c:func:`PyErr_Clear`. For example::" +msgstr "" + +#: ../../extending/extending.rst:636 +msgid "" +"if (result == NULL)\n" +" return NULL; /* Pass error back */\n" +"...use result...\n" +"Py_DECREF(result);" +msgstr "" + +#: ../../extending/extending.rst:641 +msgid "" +"Depending on the desired interface to the Python callback function, you may " +"also have to provide an argument list to :c:func:`PyObject_CallObject`. In " +"some cases the argument list is also provided by the Python program, through " +"the same interface that specified the callback function. It can then be " +"saved and used in the same manner as the function object. In other cases, " +"you may have to construct a new tuple to pass as the argument list. The " +"simplest way to do this is to call :c:func:`Py_BuildValue`. For example, if " +"you want to pass an integral event code, you might use the following code::" +msgstr "" + +#: ../../extending/extending.rst:650 +msgid "" +"PyObject *arglist;\n" +"...\n" +"arglist = Py_BuildValue(\"(l)\", eventcode);\n" +"result = PyObject_CallObject(my_callback, arglist);\n" +"Py_DECREF(arglist);\n" +"if (result == NULL)\n" +" return NULL; /* Pass error back */\n" +"/* Here maybe use the result */\n" +"Py_DECREF(result);" +msgstr "" + +#: ../../extending/extending.rst:660 +msgid "" +"Note the placement of ``Py_DECREF(arglist)`` immediately after the call, " +"before the error check! Also note that strictly speaking this code is not " +"complete: :c:func:`Py_BuildValue` may run out of memory, and this should be " +"checked." +msgstr "" + +#: ../../extending/extending.rst:664 +msgid "" +"You may also call a function with keyword arguments by using :c:func:" +"`PyObject_Call`, which supports arguments and keyword arguments. As in the " +"above example, we use :c:func:`Py_BuildValue` to construct the dictionary. ::" +msgstr "" + +#: ../../extending/extending.rst:668 +msgid "" +"PyObject *dict;\n" +"...\n" +"dict = Py_BuildValue(\"{s:i}\", \"name\", val);\n" +"result = PyObject_Call(my_callback, NULL, dict);\n" +"Py_DECREF(dict);\n" +"if (result == NULL)\n" +" return NULL; /* Pass error back */\n" +"/* Here maybe use the result */\n" +"Py_DECREF(result);" +msgstr "" + +#: ../../extending/extending.rst:682 +msgid "Extracting Parameters in Extension Functions" +msgstr "" + +#: ../../extending/extending.rst:686 +msgid "The :c:func:`PyArg_ParseTuple` function is declared as follows::" +msgstr "" + +#: ../../extending/extending.rst:688 +msgid "int PyArg_ParseTuple(PyObject *arg, const char *format, ...);" +msgstr "" + +#: ../../extending/extending.rst:690 +msgid "" +"The *arg* argument must be a tuple object containing an argument list passed " +"from Python to a C function. The *format* argument must be a format string, " +"whose syntax is explained in :ref:`arg-parsing` in the Python/C API " +"Reference Manual. The remaining arguments must be addresses of variables " +"whose type is determined by the format string." +msgstr "" + +#: ../../extending/extending.rst:696 +msgid "" +"Note that while :c:func:`PyArg_ParseTuple` checks that the Python arguments " +"have the required types, it cannot check the validity of the addresses of C " +"variables passed to the call: if you make mistakes there, your code will " +"probably crash or at least overwrite random bits in memory. So be careful!" +msgstr "" + +#: ../../extending/extending.rst:701 +msgid "" +"Note that any Python object references which are provided to the caller are " +"*borrowed* references; do not decrement their reference count!" +msgstr "" + +#: ../../extending/extending.rst:704 +msgid "Some example calls::" +msgstr "一些呼叫範例： ::" + +#: ../../extending/extending.rst:711 +msgid "" +"int ok;\n" +"int i, j;\n" +"long k, l;\n" +"const char *s;\n" +"Py_ssize_t size;\n" +"\n" +"ok = PyArg_ParseTuple(args, \"\"); /* No arguments */\n" +" /* Python call: f() */" +msgstr "" +"int ok;\n" +"int i, j;\n" +"long k, l;\n" +"const char *s;\n" +"Py_ssize_t size;\n" +"\n" +"ok = PyArg_ParseTuple(args, \"\"); /* 沒有引數 */\n" +" /* Python 呼叫：f() */" + +#: ../../extending/extending.rst:722 +msgid "" +"ok = PyArg_ParseTuple(args, \"s\", &s); /* A string */\n" +" /* Possible Python call: f('whoops!') */" +msgstr "" + +#: ../../extending/extending.rst:727 +msgid "" +"ok = PyArg_ParseTuple(args, \"lls\", &k, &l, &s); /* Two longs and a string " +"*/\n" +" /* Possible Python call: f(1, 2, 'three') */" +msgstr "" + +#: ../../extending/extending.rst:732 +msgid "" +"ok = PyArg_ParseTuple(args, \"(ii)s#\", &i, &j, &s, &size);\n" +" /* A pair of ints and a string, whose size is also returned */\n" +" /* Possible Python call: f((1, 2), 'three') */" +msgstr "" + +#: ../../extending/extending.rst:738 +msgid "" +"{\n" +" const char *file;\n" +" const char *mode = \"r\";\n" +" int bufsize = 0;\n" +" ok = PyArg_ParseTuple(args, \"s|si\", &file, &mode, &bufsize);\n" +" /* A string, and optionally another string and an integer */\n" +" /* Possible Python calls:\n" +" f('spam')\n" +" f('spam', 'w')\n" +" f('spam', 'wb', 100000) */\n" +"}" +msgstr "" + +#: ../../extending/extending.rst:752 +msgid "" +"{\n" +" int left, top, right, bottom, h, v;\n" +" ok = PyArg_ParseTuple(args, \"((ii)(ii))(ii)\",\n" +" &left, &top, &right, &bottom, &h, &v);\n" +" /* A rectangle and a point */\n" +" /* Possible Python call:\n" +" f(((0, 0), (400, 300)), (10, 10)) */\n" +"}" +msgstr "" + +#: ../../extending/extending.rst:763 +msgid "" +"{\n" +" Py_complex c;\n" +" ok = PyArg_ParseTuple(args, \"D:myfunction\", &c);\n" +" /* a complex, also providing a function name for errors */\n" +" /* Possible Python call: myfunction(1+2j) */\n" +"}" +msgstr "" + +#: ../../extending/extending.rst:774 +msgid "Keyword Parameters for Extension Functions" +msgstr "" + +#: ../../extending/extending.rst:778 +msgid "" +"The :c:func:`PyArg_ParseTupleAndKeywords` function is declared as follows::" +msgstr "" + +#: ../../extending/extending.rst:780 +msgid "" +"int PyArg_ParseTupleAndKeywords(PyObject *arg, PyObject *kwdict,\n" +" const char *format, char * const " +"*kwlist, ...);" +msgstr "" +"int PyArg_ParseTupleAndKeywords(PyObject *arg, PyObject *kwdict,\n" +" const char *format, char * const " +"*kwlist, ...);" + +#: ../../extending/extending.rst:783 +msgid "" +"The *arg* and *format* parameters are identical to those of the :c:func:" +"`PyArg_ParseTuple` function. The *kwdict* parameter is the dictionary of " +"keywords received as the third parameter from the Python runtime. The " +"*kwlist* parameter is a ``NULL``-terminated list of strings which identify " +"the parameters; the names are matched with the type information from " +"*format* from left to right. On success, :c:func:" +"`PyArg_ParseTupleAndKeywords` returns true, otherwise it returns false and " +"raises an appropriate exception." +msgstr "" + +#: ../../extending/extending.rst:793 +msgid "" +"Nested tuples cannot be parsed when using keyword arguments! Keyword " +"parameters passed in which are not present in the *kwlist* will cause :exc:" +"`TypeError` to be raised." +msgstr "" + +#: ../../extending/extending.rst:799 +msgid "" +"Here is an example module which uses keywords, based on an example by Geoff " +"Philbrick (philbrick@hks.com)::" +msgstr "" + +#: ../../extending/extending.rst:802 +msgid "" +"#define PY_SSIZE_T_CLEAN\n" +"#include \n" +"\n" +"static PyObject *\n" +"keywdarg_parrot(PyObject *self, PyObject *args, PyObject *keywds)\n" +"{\n" +" int voltage;\n" +" const char *state = \"a stiff\";\n" +" const char *action = \"voom\";\n" +" const char *type = \"Norwegian Blue\";\n" +"\n" +" static char *kwlist[] = {\"voltage\", \"state\", \"action\", \"type\", " +"NULL};\n" +"\n" +" if (!PyArg_ParseTupleAndKeywords(args, keywds, \"i|sss\", kwlist,\n" +" &voltage, &state, &action, &type))\n" +" return NULL;\n" +"\n" +" printf(\"-- This parrot wouldn't %s if you put %i Volts through it." +"\\n\",\n" +" action, voltage);\n" +" printf(\"-- Lovely plumage, the %s -- It's %s!\\n\", type, state);\n" +"\n" +" Py_RETURN_NONE;\n" +"}\n" +"\n" +"static PyMethodDef keywdarg_methods[] = {\n" +" /* The cast of the function is necessary since PyCFunction values\n" +" * only take two PyObject* parameters, and keywdarg_parrot() takes\n" +" * three.\n" +" */\n" +" {\"parrot\", (PyCFunction)(void(*)(void))keywdarg_parrot, METH_VARARGS | " +"METH_KEYWORDS,\n" +" \"Print a lovely skit to standard output.\"},\n" +" {NULL, NULL, 0, NULL} /* sentinel */\n" +"};\n" +"\n" +"static struct PyModuleDef keywdarg_module = {\n" +" .m_base = PyModuleDef_HEAD_INIT,\n" +" .m_name = \"keywdarg\",\n" +" .m_size = 0,\n" +" .m_methods = keywdarg_methods,\n" +"};\n" +"\n" +"PyMODINIT_FUNC\n" +"PyInit_keywdarg(void)\n" +"{\n" +" return PyModuleDef_Init(&keywdarg_module);\n" +"}" +msgstr "" + +#: ../../extending/extending.rst:853 +msgid "Building Arbitrary Values" +msgstr "" + +#: ../../extending/extending.rst:855 +msgid "" +"This function is the counterpart to :c:func:`PyArg_ParseTuple`. It is " +"declared as follows::" +msgstr "" + +#: ../../extending/extending.rst:858 +msgid "PyObject *Py_BuildValue(const char *format, ...);" +msgstr "PyObject *Py_BuildValue(const char *format, ...);" + +#: ../../extending/extending.rst:860 +msgid "" +"It recognizes a set of format units similar to the ones recognized by :c:" +"func:`PyArg_ParseTuple`, but the arguments (which are input to the function, " +"not output) must not be pointers, just values. It returns a new Python " +"object, suitable for returning from a C function called from Python." +msgstr "" + +#: ../../extending/extending.rst:865 +msgid "" +"One difference with :c:func:`PyArg_ParseTuple`: while the latter requires " +"its first argument to be a tuple (since Python argument lists are always " +"represented as tuples internally), :c:func:`Py_BuildValue` does not always " +"build a tuple. It builds a tuple only if its format string contains two or " +"more format units. If the format string is empty, it returns ``None``; if it " +"contains exactly one format unit, it returns whatever object is described by " +"that format unit. To force it to return a tuple of size 0 or one, " +"parenthesize the format string." +msgstr "" + +#: ../../extending/extending.rst:873 +msgid "" +"Examples (to the left the call, to the right the resulting Python value):" +msgstr "" + +#: ../../extending/extending.rst:875 +msgid "" +"Py_BuildValue(\"\") None\n" +"Py_BuildValue(\"i\", 123) 123\n" +"Py_BuildValue(\"iii\", 123, 456, 789) (123, 456, 789)\n" +"Py_BuildValue(\"s\", \"hello\") 'hello'\n" +"Py_BuildValue(\"y\", \"hello\") b'hello'\n" +"Py_BuildValue(\"ss\", \"hello\", \"world\") ('hello', 'world')\n" +"Py_BuildValue(\"s#\", \"hello\", 4) 'hell'\n" +"Py_BuildValue(\"y#\", \"hello\", 4) b'hell'\n" +"Py_BuildValue(\"()\") ()\n" +"Py_BuildValue(\"(i)\", 123) (123,)\n" +"Py_BuildValue(\"(ii)\", 123, 456) (123, 456)\n" +"Py_BuildValue(\"(i,i)\", 123, 456) (123, 456)\n" +"Py_BuildValue(\"[i,i]\", 123, 456) [123, 456]\n" +"Py_BuildValue(\"{s:i,s:i}\",\n" +" \"abc\", 123, \"def\", 456) {'abc': 123, 'def': 456}\n" +"Py_BuildValue(\"((ii)(ii)) (ii)\",\n" +" 1, 2, 3, 4, 5, 6) (((1, 2), (3, 4)), (5, 6))" +msgstr "" +"Py_BuildValue(\"\") None\n" +"Py_BuildValue(\"i\", 123) 123\n" +"Py_BuildValue(\"iii\", 123, 456, 789) (123, 456, 789)\n" +"Py_BuildValue(\"s\", \"hello\") 'hello'\n" +"Py_BuildValue(\"y\", \"hello\") b'hello'\n" +"Py_BuildValue(\"ss\", \"hello\", \"world\") ('hello', 'world')\n" +"Py_BuildValue(\"s#\", \"hello\", 4) 'hell'\n" +"Py_BuildValue(\"y#\", \"hello\", 4) b'hell'\n" +"Py_BuildValue(\"()\") ()\n" +"Py_BuildValue(\"(i)\", 123) (123,)\n" +"Py_BuildValue(\"(ii)\", 123, 456) (123, 456)\n" +"Py_BuildValue(\"(i,i)\", 123, 456) (123, 456)\n" +"Py_BuildValue(\"[i,i]\", 123, 456) [123, 456]\n" +"Py_BuildValue(\"{s:i,s:i}\",\n" +" \"abc\", 123, \"def\", 456) {'abc': 123, 'def': 456}\n" +"Py_BuildValue(\"((ii)(ii)) (ii)\",\n" +" 1, 2, 3, 4, 5, 6) (((1, 2), (3, 4)), (5, 6))" + +#: ../../extending/extending.rst:899 +msgid "Reference Counts" +msgstr "參照計數" + +#: ../../extending/extending.rst:901 +msgid "" +"In languages like C or C++, the programmer is responsible for dynamic " +"allocation and deallocation of memory on the heap. In C, this is done using " +"the functions :c:func:`malloc` and :c:func:`free`. In C++, the operators " +"``new`` and ``delete`` are used with essentially the same meaning and we'll " +"restrict the following discussion to the C case." +msgstr "" + +#: ../../extending/extending.rst:907 +msgid "" +"Every block of memory allocated with :c:func:`malloc` should eventually be " +"returned to the pool of available memory by exactly one call to :c:func:" +"`free`. It is important to call :c:func:`free` at the right time. If a " +"block's address is forgotten but :c:func:`free` is not called for it, the " +"memory it occupies cannot be reused until the program terminates. This is " +"called a :dfn:`memory leak`. On the other hand, if a program calls :c:func:" +"`free` for a block and then continues to use the block, it creates a " +"conflict with reuse of the block through another :c:func:`malloc` call. " +"This is called :dfn:`using freed memory`. It has the same bad consequences " +"as referencing uninitialized data --- core dumps, wrong results, mysterious " +"crashes." +msgstr "" + +#: ../../extending/extending.rst:918 +msgid "" +"Common causes of memory leaks are unusual paths through the code. For " +"instance, a function may allocate a block of memory, do some calculation, " +"and then free the block again. Now a change in the requirements for the " +"function may add a test to the calculation that detects an error condition " +"and can return prematurely from the function. It's easy to forget to free " +"the allocated memory block when taking this premature exit, especially when " +"it is added later to the code. Such leaks, once introduced, often go " +"undetected for a long time: the error exit is taken only in a small fraction " +"of all calls, and most modern machines have plenty of virtual memory, so the " +"leak only becomes apparent in a long-running process that uses the leaking " +"function frequently. Therefore, it's important to prevent leaks from " +"happening by having a coding convention or strategy that minimizes this kind " +"of errors." +msgstr "" + +#: ../../extending/extending.rst:931 +msgid "" +"Since Python makes heavy use of :c:func:`malloc` and :c:func:`free`, it " +"needs a strategy to avoid memory leaks as well as the use of freed memory. " +"The chosen method is called :dfn:`reference counting`. The principle is " +"simple: every object contains a counter, which is incremented when a " +"reference to the object is stored somewhere, and which is decremented when a " +"reference to it is deleted. When the counter reaches zero, the last " +"reference to the object has been deleted and the object is freed." +msgstr "" + +#: ../../extending/extending.rst:939 +msgid "" +"An alternative strategy is called :dfn:`automatic garbage collection`. " +"(Sometimes, reference counting is also referred to as a garbage collection " +"strategy, hence my use of \"automatic\" to distinguish the two.) The big " +"advantage of automatic garbage collection is that the user doesn't need to " +"call :c:func:`free` explicitly. (Another claimed advantage is an " +"improvement in speed or memory usage --- this is no hard fact however.) The " +"disadvantage is that for C, there is no truly portable automatic garbage " +"collector, while reference counting can be implemented portably (as long as " +"the functions :c:func:`malloc` and :c:func:`free` are available --- which " +"the C Standard guarantees). Maybe some day a sufficiently portable automatic " +"garbage collector will be available for C. Until then, we'll have to live " +"with reference counts." +msgstr "" + +#: ../../extending/extending.rst:951 +msgid "" +"While Python uses the traditional reference counting implementation, it also " +"offers a cycle detector that works to detect reference cycles. This allows " +"applications to not worry about creating direct or indirect circular " +"references; these are the weakness of garbage collection implemented using " +"only reference counting. Reference cycles consist of objects which contain " +"(possibly indirect) references to themselves, so that each object in the " +"cycle has a reference count which is non-zero. Typical reference counting " +"implementations are not able to reclaim the memory belonging to any objects " +"in a reference cycle, or referenced from the objects in the cycle, even " +"though there are no further references to the cycle itself." +msgstr "" + +#: ../../extending/extending.rst:962 +msgid "" +"The cycle detector is able to detect garbage cycles and can reclaim them. " +"The :mod:`gc` module exposes a way to run the detector (the :func:`~gc." +"collect` function), as well as configuration interfaces and the ability to " +"disable the detector at runtime." +msgstr "" + +#: ../../extending/extending.rst:971 +msgid "Reference Counting in Python" +msgstr "Python 中的參照計數" + +#: ../../extending/extending.rst:973 +msgid "" +"There are two macros, ``Py_INCREF(x)`` and ``Py_DECREF(x)``, which handle " +"the incrementing and decrementing of the reference count. :c:func:" +"`Py_DECREF` also frees the object when the count reaches zero. For " +"flexibility, it doesn't call :c:func:`free` directly --- rather, it makes a " +"call through a function pointer in the object's :dfn:`type object`. For " +"this purpose (and others), every object also contains a pointer to its type " +"object." +msgstr "" + +#: ../../extending/extending.rst:980 +msgid "" +"The big question now remains: when to use ``Py_INCREF(x)`` and " +"``Py_DECREF(x)``? Let's first introduce some terms. Nobody \"owns\" an " +"object; however, you can :dfn:`own a reference` to an object. An object's " +"reference count is now defined as the number of owned references to it. The " +"owner of a reference is responsible for calling :c:func:`Py_DECREF` when the " +"reference is no longer needed. Ownership of a reference can be " +"transferred. There are three ways to dispose of an owned reference: pass it " +"on, store it, or call :c:func:`Py_DECREF`. Forgetting to dispose of an owned " +"reference creates a memory leak." +msgstr "" + +#: ../../extending/extending.rst:989 +msgid "" +"It is also possible to :dfn:`borrow` [#]_ a reference to an object. The " +"borrower of a reference should not call :c:func:`Py_DECREF`. The borrower " +"must not hold on to the object longer than the owner from which it was " +"borrowed. Using a borrowed reference after the owner has disposed of it " +"risks using freed memory and should be avoided completely [#]_." +msgstr "" + +#: ../../extending/extending.rst:995 +msgid "" +"The advantage of borrowing over owning a reference is that you don't need to " +"take care of disposing of the reference on all possible paths through the " +"code --- in other words, with a borrowed reference you don't run the risk of " +"leaking when a premature exit is taken. The disadvantage of borrowing over " +"owning is that there are some subtle situations where in seemingly correct " +"code a borrowed reference can be used after the owner from which it was " +"borrowed has in fact disposed of it." +msgstr "" + +#: ../../extending/extending.rst:1003 +msgid "" +"A borrowed reference can be changed into an owned reference by calling :c:" +"func:`Py_INCREF`. This does not affect the status of the owner from which " +"the reference was borrowed --- it creates a new owned reference, and gives " +"full owner responsibilities (the new owner must dispose of the reference " +"properly, as well as the previous owner)." +msgstr "" + +#: ../../extending/extending.rst:1013 +msgid "Ownership Rules" +msgstr "" + +#: ../../extending/extending.rst:1015 +msgid "" +"Whenever an object reference is passed into or out of a function, it is part " +"of the function's interface specification whether ownership is transferred " +"with the reference or not." +msgstr "" + +#: ../../extending/extending.rst:1019 +msgid "" +"Most functions that return a reference to an object pass on ownership with " +"the reference. In particular, all functions whose function it is to create " +"a new object, such as :c:func:`PyLong_FromLong` and :c:func:`Py_BuildValue`, " +"pass ownership to the receiver. Even if the object is not actually new, you " +"still receive ownership of a new reference to that object. For instance, :c:" +"func:`PyLong_FromLong` maintains a cache of popular values and can return a " +"reference to a cached item." +msgstr "" + +#: ../../extending/extending.rst:1027 +msgid "" +"Many functions that extract objects from other objects also transfer " +"ownership with the reference, for instance :c:func:" +"`PyObject_GetAttrString`. The picture is less clear, here, however, since a " +"few common routines are exceptions: :c:func:`PyTuple_GetItem`, :c:func:" +"`PyList_GetItem`, :c:func:`PyDict_GetItem`, and :c:func:" +"`PyDict_GetItemString` all return references that you borrow from the tuple, " +"list or dictionary." +msgstr "" + +#: ../../extending/extending.rst:1034 +msgid "" +"The function :c:func:`PyImport_AddModule` also returns a borrowed reference, " +"even though it may actually create the object it returns: this is possible " +"because an owned reference to the object is stored in ``sys.modules``." +msgstr "" + +#: ../../extending/extending.rst:1038 +msgid "" +"When you pass an object reference into another function, in general, the " +"function borrows the reference from you --- if it needs to store it, it will " +"use :c:func:`Py_INCREF` to become an independent owner. There are exactly " +"two important exceptions to this rule: :c:func:`PyTuple_SetItem` and :c:func:" +"`PyList_SetItem`. These functions take over ownership of the item passed to " +"them --- even if they fail! (Note that :c:func:`PyDict_SetItem` and friends " +"don't take over ownership --- they are \"normal.\")" +msgstr "" + +#: ../../extending/extending.rst:1046 +msgid "" +"When a C function is called from Python, it borrows references to its " +"arguments from the caller. The caller owns a reference to the object, so " +"the borrowed reference's lifetime is guaranteed until the function returns. " +"Only when such a borrowed reference must be stored or passed on, it must be " +"turned into an owned reference by calling :c:func:`Py_INCREF`." +msgstr "" + +#: ../../extending/extending.rst:1052 +msgid "" +"The object reference returned from a C function that is called from Python " +"must be an owned reference --- ownership is transferred from the function to " +"its caller." +msgstr "" + +#: ../../extending/extending.rst:1060 +msgid "Thin Ice" +msgstr "" + +#: ../../extending/extending.rst:1062 +msgid "" +"There are a few situations where seemingly harmless use of a borrowed " +"reference can lead to problems. These all have to do with implicit " +"invocations of the interpreter, which can cause the owner of a reference to " +"dispose of it." +msgstr "" + +#: ../../extending/extending.rst:1066 +msgid "" +"The first and most important case to know about is using :c:func:`Py_DECREF` " +"on an unrelated object while borrowing a reference to a list item. For " +"instance::" +msgstr "" + +#: ../../extending/extending.rst:1069 +msgid "" +"void\n" +"bug(PyObject *list)\n" +"{\n" +" PyObject *item = PyList_GetItem(list, 0);\n" +"\n" +" PyList_SetItem(list, 1, PyLong_FromLong(0L));\n" +" PyObject_Print(item, stdout, 0); /* BUG! */\n" +"}" +msgstr "" +"void\n" +"bug(PyObject *list)\n" +"{\n" +" PyObject *item = PyList_GetItem(list, 0);\n" +"\n" +" PyList_SetItem(list, 1, PyLong_FromLong(0L));\n" +" PyObject_Print(item, stdout, 0); /* BUG! */\n" +"}" + +#: ../../extending/extending.rst:1078 +msgid "" +"This function first borrows a reference to ``list[0]``, then replaces " +"``list[1]`` with the value ``0``, and finally prints the borrowed reference. " +"Looks harmless, right? But it's not!" +msgstr "" + +#: ../../extending/extending.rst:1082 +msgid "" +"Let's follow the control flow into :c:func:`PyList_SetItem`. The list owns " +"references to all its items, so when item 1 is replaced, it has to dispose " +"of the original item 1. Now let's suppose the original item 1 was an " +"instance of a user-defined class, and let's further suppose that the class " +"defined a :meth:`!__del__` method. If this class instance has a reference " +"count of 1, disposing of it will call its :meth:`!__del__` method. " +"Internally, :c:func:`PyList_SetItem` calls :c:func:`Py_DECREF` on the " +"replaced item, which invokes replaced item's corresponding :c:member:" +"`~PyTypeObject.tp_dealloc` function. During deallocation, :c:member:" +"`~PyTypeObject.tp_dealloc` calls :c:member:`~PyTypeObject.tp_finalize`, " +"which is mapped to the :meth:`!__del__` method for class instances (see :pep:" +"`442`). This entire sequence happens synchronously within the :c:func:" +"`PyList_SetItem` call." +msgstr "" + +#: ../../extending/extending.rst:1096 +msgid "" +"Since it is written in Python, the :meth:`!__del__` method can execute " +"arbitrary Python code. Could it perhaps do something to invalidate the " +"reference to ``item`` in :c:func:`!bug`? You bet! Assuming that the list " +"passed into :c:func:`!bug` is accessible to the :meth:`!__del__` method, it " +"could execute a statement to the effect of ``del list[0]``, and assuming " +"this was the last reference to that object, it would free the memory " +"associated with it, thereby invalidating ``item``." +msgstr "" + +#: ../../extending/extending.rst:1104 +msgid "" +"The solution, once you know the source of the problem, is easy: temporarily " +"increment the reference count. The correct version of the function reads::" +msgstr "" + +#: ../../extending/extending.rst:1107 +msgid "" +"void\n" +"no_bug(PyObject *list)\n" +"{\n" +" PyObject *item = PyList_GetItem(list, 0);\n" +"\n" +" Py_INCREF(item);\n" +" PyList_SetItem(list, 1, PyLong_FromLong(0L));\n" +" PyObject_Print(item, stdout, 0);\n" +" Py_DECREF(item);\n" +"}" +msgstr "" +"void\n" +"no_bug(PyObject *list)\n" +"{\n" +" PyObject *item = PyList_GetItem(list, 0);\n" +"\n" +" Py_INCREF(item);\n" +" PyList_SetItem(list, 1, PyLong_FromLong(0L));\n" +" PyObject_Print(item, stdout, 0);\n" +" Py_DECREF(item);\n" +"}" + +#: ../../extending/extending.rst:1118 +msgid "" +"This is a true story. An older version of Python contained variants of this " +"bug and someone spent a considerable amount of time in a C debugger to " +"figure out why his :meth:`!__del__` methods would fail..." +msgstr "" + +#: ../../extending/extending.rst:1122 +msgid "" +"The second case of problems with a borrowed reference is a variant involving " +"threads. Normally, multiple threads in the Python interpreter can't get in " +"each other's way, because there is a :term:`global lock ` protecting Python's entire object space. However, it is possible to " +"temporarily release this lock using the macro :c:macro:" +"`Py_BEGIN_ALLOW_THREADS`, and to re-acquire it using :c:macro:" +"`Py_END_ALLOW_THREADS`. This is common around blocking I/O calls, to let " +"other threads use the processor while waiting for the I/O to complete. " +"Obviously, the following function has the same problem as the previous one::" +msgstr "" + +#: ../../extending/extending.rst:1132 +msgid "" +"void\n" +"bug(PyObject *list)\n" +"{\n" +" PyObject *item = PyList_GetItem(list, 0);\n" +" Py_BEGIN_ALLOW_THREADS\n" +" ...some blocking I/O call...\n" +" Py_END_ALLOW_THREADS\n" +" PyObject_Print(item, stdout, 0); /* BUG! */\n" +"}" +msgstr "" + +#: ../../extending/extending.rst:1146 +msgid "NULL Pointers" +msgstr "NULL 指標" + +#: ../../extending/extending.rst:1148 +msgid "" +"In general, functions that take object references as arguments do not expect " +"you to pass them ``NULL`` pointers, and will dump core (or cause later core " +"dumps) if you do so. Functions that return object references generally " +"return ``NULL`` only to indicate that an exception occurred. The reason for " +"not testing for ``NULL`` arguments is that functions often pass the objects " +"they receive on to other function --- if each function were to test for " +"``NULL``, there would be a lot of redundant tests and the code would run " +"more slowly." +msgstr "" + +#: ../../extending/extending.rst:1156 +msgid "" +"It is better to test for ``NULL`` only at the \"source:\" when a pointer " +"that may be ``NULL`` is received, for example, from :c:func:`malloc` or from " +"a function that may raise an exception." +msgstr "" + +#: ../../extending/extending.rst:1160 +msgid "" +"The macros :c:func:`Py_INCREF` and :c:func:`Py_DECREF` do not check for " +"``NULL`` pointers --- however, their variants :c:func:`Py_XINCREF` and :c:" +"func:`Py_XDECREF` do." +msgstr "" + +#: ../../extending/extending.rst:1164 +msgid "" +"The macros for checking for a particular object type (``Pytype_Check()``) " +"don't check for ``NULL`` pointers --- again, there is much code that calls " +"several of these in a row to test an object against various different " +"expected types, and this would generate redundant tests. There are no " +"variants with ``NULL`` checking." +msgstr "" + +#: ../../extending/extending.rst:1170 +msgid "" +"The C function calling mechanism guarantees that the argument list passed to " +"C functions (``args`` in the examples) is never ``NULL`` --- in fact it " +"guarantees that it is always a tuple [#]_." +msgstr "" + +#: ../../extending/extending.rst:1174 +msgid "" +"It is a severe error to ever let a ``NULL`` pointer \"escape\" to the Python " +"user." +msgstr "" + +#: ../../extending/extending.rst:1185 +msgid "Writing Extensions in C++" +msgstr "" + +#: ../../extending/extending.rst:1187 +msgid "" +"It is possible to write extension modules in C++. Some restrictions apply. " +"If the main program (the Python interpreter) is compiled and linked by the C " +"compiler, global or static objects with constructors cannot be used. This " +"is not a problem if the main program is linked by the C++ compiler. " +"Functions that will be called by the Python interpreter (in particular, " +"module initialization functions) have to be declared using ``extern \"C\"``. " +"It is unnecessary to enclose the Python header files in ``extern \"C\" {...}" +"`` --- they use this form already if the symbol ``__cplusplus`` is defined " +"(all recent C++ compilers define this symbol)." +msgstr "" + +#: ../../extending/extending.rst:1201 +msgid "Providing a C API for an Extension Module" +msgstr "" + +#: ../../extending/extending.rst:1206 +msgid "" +"Many extension modules just provide new functions and types to be used from " +"Python, but sometimes the code in an extension module can be useful for " +"other extension modules. For example, an extension module could implement a " +"type \"collection\" which works like lists without order. Just like the " +"standard Python list type has a C API which permits extension modules to " +"create and manipulate lists, this new collection type should have a set of C " +"functions for direct manipulation from other extension modules." +msgstr "" + +#: ../../extending/extending.rst:1214 +msgid "" +"At first sight this seems easy: just write the functions (without declaring " +"them ``static``, of course), provide an appropriate header file, and " +"document the C API. And in fact this would work if all extension modules " +"were always linked statically with the Python interpreter. When modules are " +"used as shared libraries, however, the symbols defined in one module may not " +"be visible to another module. The details of visibility depend on the " +"operating system; some systems use one global namespace for the Python " +"interpreter and all extension modules (Windows, for example), whereas others " +"require an explicit list of imported symbols at module link time (AIX is one " +"example), or offer a choice of different strategies (most Unices). And even " +"if symbols are globally visible, the module whose functions one wishes to " +"call might not have been loaded yet!" +msgstr "" + +#: ../../extending/extending.rst:1226 +msgid "" +"Portability therefore requires not to make any assumptions about symbol " +"visibility. This means that all symbols in extension modules should be " +"declared ``static``, except for the module's initialization function, in " +"order to avoid name clashes with other extension modules (as discussed in " +"section :ref:`methodtable`). And it means that symbols that *should* be " +"accessible from other extension modules must be exported in a different way." +msgstr "" + +#: ../../extending/extending.rst:1233 +msgid "" +"Python provides a special mechanism to pass C-level information (pointers) " +"from one extension module to another one: Capsules. A Capsule is a Python " +"data type which stores a pointer (:c:expr:`void \\*`). Capsules can only be " +"created and accessed via their C API, but they can be passed around like any " +"other Python object. In particular, they can be assigned to a name in an " +"extension module's namespace. Other extension modules can then import this " +"module, retrieve the value of this name, and then retrieve the pointer from " +"the Capsule." +msgstr "" + +#: ../../extending/extending.rst:1241 +msgid "" +"There are many ways in which Capsules can be used to export the C API of an " +"extension module. Each function could get its own Capsule, or all C API " +"pointers could be stored in an array whose address is published in a " +"Capsule. And the various tasks of storing and retrieving the pointers can be " +"distributed in different ways between the module providing the code and the " +"client modules." +msgstr "" + +#: ../../extending/extending.rst:1247 +msgid "" +"Whichever method you choose, it's important to name your Capsules properly. " +"The function :c:func:`PyCapsule_New` takes a name parameter (:c:expr:`const " +"char \\*`); you're permitted to pass in a ``NULL`` name, but we strongly " +"encourage you to specify a name. Properly named Capsules provide a degree " +"of runtime type-safety; there is no feasible way to tell one unnamed Capsule " +"from another." +msgstr "" + +#: ../../extending/extending.rst:1254 +msgid "" +"In particular, Capsules used to expose C APIs should be given a name " +"following this convention::" +msgstr "" + +#: ../../extending/extending.rst:1257 +msgid "modulename.attributename" +msgstr "modulename.attributename" + +#: ../../extending/extending.rst:1259 +msgid "" +"The convenience function :c:func:`PyCapsule_Import` makes it easy to load a " +"C API provided via a Capsule, but only if the Capsule's name matches this " +"convention. This behavior gives C API users a high degree of certainty that " +"the Capsule they load contains the correct C API." +msgstr "" + +#: ../../extending/extending.rst:1264 +msgid "" +"The following example demonstrates an approach that puts most of the burden " +"on the writer of the exporting module, which is appropriate for commonly " +"used library modules. It stores all C API pointers (just one in the " +"example!) in an array of :c:expr:`void` pointers which becomes the value of " +"a Capsule. The header file corresponding to the module provides a macro that " +"takes care of importing the module and retrieving its C API pointers; client " +"modules only have to call this macro before accessing the C API." +msgstr "" + +#: ../../extending/extending.rst:1272 +msgid "" +"The exporting module is a modification of the :mod:`!spam` module from " +"section :ref:`extending-simpleexample`. The function :func:`!spam.system` " +"does not call the C library function :c:func:`system` directly, but a " +"function :c:func:`!PySpam_System`, which would of course do something more " +"complicated in reality (such as adding \"spam\" to every command). This " +"function :c:func:`!PySpam_System` is also exported to other extension " +"modules." +msgstr "" + +#: ../../extending/extending.rst:1279 +msgid "" +"The function :c:func:`!PySpam_System` is a plain C function, declared " +"``static`` like everything else::" +msgstr "" + +#: ../../extending/extending.rst:1282 +msgid "" +"static int\n" +"PySpam_System(const char *command)\n" +"{\n" +" return system(command);\n" +"}" +msgstr "" +"static int\n" +"PySpam_System(const char *command)\n" +"{\n" +" return system(command);\n" +"}" + +#: ../../extending/extending.rst:1288 +msgid "The function :c:func:`!spam_system` is modified in a trivial way::" +msgstr "" + +#: ../../extending/extending.rst:1290 +msgid "" +"static PyObject *\n" +"spam_system(PyObject *self, PyObject *args)\n" +"{\n" +" const char *command;\n" +" int sts;\n" +"\n" +" if (!PyArg_ParseTuple(args, \"s\", &command))\n" +" return NULL;\n" +" sts = PySpam_System(command);\n" +" return PyLong_FromLong(sts);\n" +"}" +msgstr "" +"static PyObject *\n" +"spam_system(PyObject *self, PyObject *args)\n" +"{\n" +" const char *command;\n" +" int sts;\n" +"\n" +" if (!PyArg_ParseTuple(args, \"s\", &command))\n" +" return NULL;\n" +" sts = PySpam_System(command);\n" +" return PyLong_FromLong(sts);\n" +"}" + +#: ../../extending/extending.rst:1302 +msgid "In the beginning of the module, right after the line ::" +msgstr "" + +#: ../../extending/extending.rst:1304 +msgid "#include " +msgstr "#include " + +#: ../../extending/extending.rst:1306 +msgid "two more lines must be added::" +msgstr "" + +#: ../../extending/extending.rst:1308 +msgid "" +"#define SPAM_MODULE\n" +"#include \"spammodule.h\"" +msgstr "" +"#define SPAM_MODULE\n" +"#include \"spammodule.h\"" + +#: ../../extending/extending.rst:1311 +msgid "" +"The ``#define`` is used to tell the header file that it is being included in " +"the exporting module, not a client module. Finally, the module's :c:data:" +"`mod_exec ` function must take care of initializing the C API " +"pointer array::" +msgstr "" + +#: ../../extending/extending.rst:1315 +msgid "" +"static int\n" +"spam_module_exec(PyObject *m)\n" +"{\n" +" static void *PySpam_API[PySpam_API_pointers];\n" +" PyObject *c_api_object;\n" +"\n" +" /* Initialize the C API pointer array */\n" +" PySpam_API[PySpam_System_NUM] = (void *)PySpam_System;\n" +"\n" +" /* Create a Capsule containing the API pointer array's address */\n" +" c_api_object = PyCapsule_New((void *)PySpam_API, \"spam._C_API\", " +"NULL);\n" +"\n" +" if (PyModule_Add(m, \"_C_API\", c_api_object) < 0) {\n" +" return -1;\n" +" }\n" +"\n" +" return 0;\n" +"}" +msgstr "" + +#: ../../extending/extending.rst:1334 +msgid "" +"Note that ``PySpam_API`` is declared ``static``; otherwise the pointer array " +"would disappear when :c:func:`!PyInit_spam` terminates!" +msgstr "" + +#: ../../extending/extending.rst:1337 +msgid "" +"The bulk of the work is in the header file :file:`spammodule.h`, which looks " +"like this::" +msgstr "" + +#: ../../extending/extending.rst:1340 +msgid "" +"#ifndef Py_SPAMMODULE_H\n" +"#define Py_SPAMMODULE_H\n" +"#ifdef __cplusplus\n" +"extern \"C\" {\n" +"#endif\n" +"\n" +"/* Header file for spammodule */\n" +"\n" +"/* C API functions */\n" +"#define PySpam_System_NUM 0\n" +"#define PySpam_System_RETURN int\n" +"#define PySpam_System_PROTO (const char *command)\n" +"\n" +"/* Total number of C API pointers */\n" +"#define PySpam_API_pointers 1\n" +"\n" +"\n" +"#ifdef SPAM_MODULE\n" +"/* This section is used when compiling spammodule.c */\n" +"\n" +"static PySpam_System_RETURN PySpam_System PySpam_System_PROTO;\n" +"\n" +"#else\n" +"/* This section is used in modules that use spammodule's API */\n" +"\n" +"static void **PySpam_API;\n" +"\n" +"#define PySpam_System \\\n" +" (*(PySpam_System_RETURN (*)PySpam_System_PROTO) " +"PySpam_API[PySpam_System_NUM])\n" +"\n" +"/* Return -1 on error, 0 on success.\n" +" * PyCapsule_Import will set an exception if there's an error.\n" +" */\n" +"static int\n" +"import_spam(void)\n" +"{\n" +" PySpam_API = (void **)PyCapsule_Import(\"spam._C_API\", 0);\n" +" return (PySpam_API != NULL) ? 0 : -1;\n" +"}\n" +"\n" +"#endif\n" +"\n" +"#ifdef __cplusplus\n" +"}\n" +"#endif\n" +"\n" +"#endif /* !defined(Py_SPAMMODULE_H) */" +msgstr "" + +#: ../../extending/extending.rst:1388 +msgid "" +"All that a client module must do in order to have access to the function :c:" +"func:`!PySpam_System` is to call the function (or rather macro) :c:func:`!" +"import_spam` in its :c:data:`mod_exec ` function::" +msgstr "" + +#: ../../extending/extending.rst:1392 +msgid "" +"static int\n" +"client_module_exec(PyObject *m)\n" +"{\n" +" if (import_spam() < 0) {\n" +" return -1;\n" +" }\n" +" /* additional initialization can happen here */\n" +" return 0;\n" +"}" +msgstr "" + +#: ../../extending/extending.rst:1402 +msgid "" +"The main disadvantage of this approach is that the file :file:`spammodule.h` " +"is rather complicated. However, the basic structure is the same for each " +"function that is exported, so it has to be learned only once." +msgstr "" + +#: ../../extending/extending.rst:1406 +msgid "" +"Finally it should be mentioned that Capsules offer additional functionality, " +"which is especially useful for memory allocation and deallocation of the " +"pointer stored in a Capsule. The details are described in the Python/C API " +"Reference Manual in the section :ref:`capsules` and in the implementation of " +"Capsules (files :file:`Include/pycapsule.h` and :file:`Objects/pycapsule.c` " +"in the Python source code distribution)." +msgstr "" + +#: ../../extending/extending.rst:1414 +msgid "Footnotes" +msgstr "註腳" + +#: ../../extending/extending.rst:1415 +msgid "" +"An interface for this function already exists in the standard module :mod:" +"`os` --- it was chosen as a simple and straightforward example." +msgstr "" + +#: ../../extending/extending.rst:1418 +msgid "" +"The metaphor of \"borrowing\" a reference is not completely correct: the " +"owner still has a copy of the reference." +msgstr "" + +#: ../../extending/extending.rst:1421 +msgid "" +"Checking that the reference count is at least 1 **does not work** --- the " +"reference count itself could be in freed memory and may thus be reused for " +"another object!" +msgstr "" + +#: ../../extending/extending.rst:1425 +msgid "" +"These guarantees don't hold when you use the \"old\" style calling " +"convention --- this is still found in much existing code." +msgstr "" + +#: ../../extending/extending.rst:593 +msgid "PyObject_CallObject (C function)" +msgstr "PyObject_CallObject（C 函式）" + +#: ../../extending/extending.rst:684 +msgid "PyArg_ParseTuple (C function)" +msgstr "PyArg_ParseTuple（C 函式）" + +#: ../../extending/extending.rst:776 +msgid "PyArg_ParseTupleAndKeywords (C function)" +msgstr "PyArg_ParseTupleAndKeywords（C 函式）" + +#: ../../extending/extending.rst:797 +msgid "Philbrick, Geoff" +msgstr "Philbrick, Geoff" diff --git a/extending/index.po b/extending/index.po index 8b55a61493..28845ed8cd 100644 --- a/extending/index.po +++ b/extending/index.po @@ -1,124 +1,124 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Steven Hsu , 2021 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-06-27 07:36+0000\n" -"PO-Revision-Date: 2021-07-06 22:18+0800\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" -"X-Generator: Poedit 2.4.3\n" - -#: ../../extending/index.rst:5 -msgid "Extending and Embedding the Python Interpreter" -msgstr "擴充和嵌入 Python 直譯器" - -#: ../../extending/index.rst:7 -msgid "" -"This document describes how to write modules in C or C++ to extend the " -"Python interpreter with new modules. Those modules can not only define new " -"functions but also new object types and their methods. The document also " -"describes how to embed the Python interpreter in another application, for " -"use as an extension language. Finally, it shows how to compile and link " -"extension modules so that they can be loaded dynamically (at run time) into " -"the interpreter, if the underlying operating system supports this feature." -msgstr "" -"這份說明文件描述如何在 C 或 C++ 中編寫模組，並使用新模組來擴充 Python 直譯器" -"功能。那些模組不僅可以定義新的函式，也可以定義新的物件型別及其方法 (method)。" -"文件內容也會描述如何將 Python 直譯器嵌入另一個應用程式中，做為一種擴充語言 " -"(extension language) 使用。最後，它會展示如何編譯及連結擴充模組，使那些模組可" -"以動態地（在執行環境）被載入到直譯器中，前提是底層作業系統有支援這個功能。" - -#: ../../extending/index.rst:15 -msgid "" -"This document assumes basic knowledge about Python. For an informal " -"introduction to the language, see :ref:`tutorial-index`. :ref:`reference-" -"index` gives a more formal definition of the language. :ref:`library-index` " -"documents the existing object types, functions and modules (both built-in " -"and written in Python) that give the language its wide application range." -msgstr "" -"這份說明文件假設你具備 Python 的基礎知識。關於此語言的非正式介紹，請參閱 :" -"ref:`tutorial-index`。:ref:`reference-index`\\ 給予此語言更為正式的定義。:" -"ref:`library-index` 記錄了賦予此語言廣泛應用範圍的物件型別、函式與（內建的和" -"以 Python 編寫的）模組。" - -#: ../../extending/index.rst:21 -msgid "" -"For a detailed description of the whole Python/C API, see the separate :ref:" -"`c-api-index`." -msgstr "關於完整的 Python/C API 詳細介紹，請參閱另外一份 :ref:`c-api-index`。" - -#: ../../extending/index.rst:26 -msgid "Recommended third party tools" -msgstr "推薦的第三方工具" - -#: ../../extending/index.rst:28 -msgid "" -"This guide only covers the basic tools for creating extensions provided as " -"part of this version of CPython. Some :ref:`third party tools ` " -"offer both simpler and more sophisticated approaches to creating C and C++ " -"extensions for Python." -msgstr "" -"這份指南僅涵蓋了此 CPython 版本所提供的、用以建立擴充的基本工具。有一些\\ " -":ref:`第三方工具 `，提供了更為簡單及更為複雜的多種方法，來為 Python 建立 " -"C 和 C++ 擴充。" - -#: ../../extending/index.rst:35 -msgid "Creating extensions without third party tools" -msgstr "不使用第三方工具建立擴充" - -#: ../../extending/index.rst:37 -msgid "" -"This section of the guide covers creating C and C++ extensions without " -"assistance from third party tools. It is intended primarily for creators of " -"those tools, rather than being a recommended way to create your own C " -"extensions." -msgstr "" -"本指南中的這一節將說明，在沒有第三方工具的協助下，如何建立 C 和 C ++ 擴充。它" -"主要是寫給使用那些工具的創作者們，而不是讓你建立自己的 C 擴充的推薦方法。" - -#: ../../extending/index.rst:44 -msgid ":pep:`489` -- Multi-phase extension module initialization" -msgstr ":pep:`489` -- 多階段擴充模組初始化" - -#: ../../extending/index.rst:57 -msgid "Embedding the CPython runtime in a larger application" -msgstr "在更大的應用程式中嵌入 CPython 運行環境 (runtime)" - -#: ../../extending/index.rst:59 -msgid "" -"Sometimes, rather than creating an extension that runs inside the Python " -"interpreter as the main application, it is desirable to instead embed the " -"CPython runtime inside a larger application. This section covers some of the " -"details involved in doing that successfully." -msgstr "" -"有時候，相較於建立一個擴充，使其在 Python 直譯器中可作為主應用程式運行，還不" -"如將 CPython 運行環境嵌入至一個更大的應用程式中更可取。本節將涵蓋一些要成功完" -"成此任務所涉及的細節。" - -#~ msgid "" -#~ "`Python Packaging User Guide: Binary Extensions `_" -#~ msgstr "" -#~ "`Python 封裝使用者指南：二進制擴充 `_" - -#~ msgid "" -#~ "The Python Packaging User Guide not only covers several available tools " -#~ "that simplify the creation of binary extensions, but also discusses the " -#~ "various reasons why creating an extension module may be desirable in the " -#~ "first place." -#~ msgstr "" -#~ "Python 封裝使用者指南 (Python Packaging User Guide) 不僅涵蓋了數個可以用來" -#~ "簡化二進制擴充建立過程的工具，也會討論為何建立一個擴充模組可能會是你的優先" -#~ "考量。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Steven Hsu , 2021 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-06-27 07:36+0000\n" +"PO-Revision-Date: 2021-07-06 22:18+0800\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" +"X-Generator: Poedit 2.4.3\n" + +#: ../../extending/index.rst:5 +msgid "Extending and Embedding the Python Interpreter" +msgstr "擴充和嵌入 Python 直譯器" + +#: ../../extending/index.rst:7 +msgid "" +"This document describes how to write modules in C or C++ to extend the " +"Python interpreter with new modules. Those modules can not only define new " +"functions but also new object types and their methods. The document also " +"describes how to embed the Python interpreter in another application, for " +"use as an extension language. Finally, it shows how to compile and link " +"extension modules so that they can be loaded dynamically (at run time) into " +"the interpreter, if the underlying operating system supports this feature." +msgstr "" +"這份說明文件描述如何在 C 或 C++ 中編寫模組，並使用新模組來擴充 Python 直譯器" +"功能。那些模組不僅可以定義新的函式，也可以定義新的物件型別及其方法 (method)。" +"文件內容也會描述如何將 Python 直譯器嵌入另一個應用程式中，做為一種擴充語言 " +"(extension language) 使用。最後，它會展示如何編譯及連結擴充模組，使那些模組可" +"以動態地（在執行環境）被載入到直譯器中，前提是底層作業系統有支援這個功能。" + +#: ../../extending/index.rst:15 +msgid "" +"This document assumes basic knowledge about Python. For an informal " +"introduction to the language, see :ref:`tutorial-index`. :ref:`reference-" +"index` gives a more formal definition of the language. :ref:`library-index` " +"documents the existing object types, functions and modules (both built-in " +"and written in Python) that give the language its wide application range." +msgstr "" +"這份說明文件假設你具備 Python 的基礎知識。關於此語言的非正式介紹，請參閱 :" +"ref:`tutorial-index`。:ref:`reference-index`\\ 給予此語言更為正式的定義。:" +"ref:`library-index` 記錄了賦予此語言廣泛應用範圍的物件型別、函式與（內建的和" +"以 Python 編寫的）模組。" + +#: ../../extending/index.rst:21 +msgid "" +"For a detailed description of the whole Python/C API, see the separate :ref:" +"`c-api-index`." +msgstr "關於完整的 Python/C API 詳細介紹，請參閱另外一份 :ref:`c-api-index`。" + +#: ../../extending/index.rst:26 +msgid "Recommended third party tools" +msgstr "推薦的第三方工具" + +#: ../../extending/index.rst:28 +msgid "" +"This guide only covers the basic tools for creating extensions provided as " +"part of this version of CPython. Some :ref:`third party tools ` " +"offer both simpler and more sophisticated approaches to creating C and C++ " +"extensions for Python." +msgstr "" +"這份指南僅涵蓋了此 CPython 版本所提供的、用以建立擴充的基本工具。有一些\\ " +":ref:`第三方工具 `，提供了更為簡單及更為複雜的多種方法，來為 Python 建立 " +"C 和 C++ 擴充。" + +#: ../../extending/index.rst:35 +msgid "Creating extensions without third party tools" +msgstr "不使用第三方工具建立擴充" + +#: ../../extending/index.rst:37 +msgid "" +"This section of the guide covers creating C and C++ extensions without " +"assistance from third party tools. It is intended primarily for creators of " +"those tools, rather than being a recommended way to create your own C " +"extensions." +msgstr "" +"本指南中的這一節將說明，在沒有第三方工具的協助下，如何建立 C 和 C ++ 擴充。它" +"主要是寫給使用那些工具的創作者們，而不是讓你建立自己的 C 擴充的推薦方法。" + +#: ../../extending/index.rst:44 +msgid ":pep:`489` -- Multi-phase extension module initialization" +msgstr ":pep:`489` -- 多階段擴充模組初始化" + +#: ../../extending/index.rst:57 +msgid "Embedding the CPython runtime in a larger application" +msgstr "在更大的應用程式中嵌入 CPython 運行環境 (runtime)" + +#: ../../extending/index.rst:59 +msgid "" +"Sometimes, rather than creating an extension that runs inside the Python " +"interpreter as the main application, it is desirable to instead embed the " +"CPython runtime inside a larger application. This section covers some of the " +"details involved in doing that successfully." +msgstr "" +"有時候，相較於建立一個擴充，使其在 Python 直譯器中可作為主應用程式運行，還不" +"如將 CPython 運行環境嵌入至一個更大的應用程式中更可取。本節將涵蓋一些要成功完" +"成此任務所涉及的細節。" + +#~ msgid "" +#~ "`Python Packaging User Guide: Binary Extensions `_" +#~ msgstr "" +#~ "`Python 封裝使用者指南：二進制擴充 `_" + +#~ msgid "" +#~ "The Python Packaging User Guide not only covers several available tools " +#~ "that simplify the creation of binary extensions, but also discusses the " +#~ "various reasons why creating an extension module may be desirable in the " +#~ "first place." +#~ msgstr "" +#~ "Python 封裝使用者指南 (Python Packaging User Guide) 不僅涵蓋了數個可以用來" +#~ "簡化二進制擴充建立過程的工具，也會討論為何建立一個擴充模組可能會是你的優先" +#~ "考量。" diff --git a/extending/newtypes.po b/extending/newtypes.po index 6ddb5552cf..d1ffca74ea 100644 --- a/extending/newtypes.po +++ b/extending/newtypes.po @@ -1,1099 +1,1099 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Leon H., 2017 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: 2018-05-23 14:34+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" - -#: ../../extending/newtypes.rst:7 -msgid "Defining Extension Types: Assorted Topics" -msgstr "" - -#: ../../extending/newtypes.rst:11 -msgid "" -"This section aims to give a quick fly-by on the various type methods you can " -"implement and what they do." -msgstr "" - -#: ../../extending/newtypes.rst:14 -msgid "" -"Here is the definition of :c:type:`PyTypeObject`, with some fields only used " -"in :ref:`debug builds ` omitted:" -msgstr "" - -#: ../../extending/newtypes.rst:17 -msgid "" -"typedef struct _typeobject {\n" -" PyObject_VAR_HEAD\n" -" const char *tp_name; /* For printing, in format \".\" */\n" -" Py_ssize_t tp_basicsize, tp_itemsize; /* For allocation */\n" -"\n" -" /* Methods to implement standard operations */\n" -"\n" -" destructor tp_dealloc;\n" -" Py_ssize_t tp_vectorcall_offset;\n" -" getattrfunc tp_getattr;\n" -" setattrfunc tp_setattr;\n" -" PyAsyncMethods *tp_as_async; /* formerly known as tp_compare (Python 2)\n" -" or tp_reserved (Python 3) */\n" -" reprfunc tp_repr;\n" -"\n" -" /* Method suites for standard classes */\n" -"\n" -" PyNumberMethods *tp_as_number;\n" -" PySequenceMethods *tp_as_sequence;\n" -" PyMappingMethods *tp_as_mapping;\n" -"\n" -" /* More standard operations (here for binary compatibility) */\n" -"\n" -" hashfunc tp_hash;\n" -" ternaryfunc tp_call;\n" -" reprfunc tp_str;\n" -" getattrofunc tp_getattro;\n" -" setattrofunc tp_setattro;\n" -"\n" -" /* Functions to access object as input/output buffer */\n" -" PyBufferProcs *tp_as_buffer;\n" -"\n" -" /* Flags to define presence of optional/expanded features */\n" -" unsigned long tp_flags;\n" -"\n" -" const char *tp_doc; /* Documentation string */\n" -"\n" -" /* Assigned meaning in release 2.0 */\n" -" /* call function for all accessible objects */\n" -" traverseproc tp_traverse;\n" -"\n" -" /* delete references to contained objects */\n" -" inquiry tp_clear;\n" -"\n" -" /* Assigned meaning in release 2.1 */\n" -" /* rich comparisons */\n" -" richcmpfunc tp_richcompare;\n" -"\n" -" /* weak reference enabler */\n" -" Py_ssize_t tp_weaklistoffset;\n" -"\n" -" /* Iterators */\n" -" getiterfunc tp_iter;\n" -" iternextfunc tp_iternext;\n" -"\n" -" /* Attribute descriptor and subclassing stuff */\n" -" PyMethodDef *tp_methods;\n" -" PyMemberDef *tp_members;\n" -" PyGetSetDef *tp_getset;\n" -" // Strong reference on a heap type, borrowed reference on a static type\n" -" PyTypeObject *tp_base;\n" -" PyObject *tp_dict;\n" -" descrgetfunc tp_descr_get;\n" -" descrsetfunc tp_descr_set;\n" -" Py_ssize_t tp_dictoffset;\n" -" initproc tp_init;\n" -" allocfunc tp_alloc;\n" -" newfunc tp_new;\n" -" freefunc tp_free; /* Low-level free-memory routine */\n" -" inquiry tp_is_gc; /* For PyObject_IS_GC */\n" -" PyObject *tp_bases;\n" -" PyObject *tp_mro; /* method resolution order */\n" -" PyObject *tp_cache; /* no longer used */\n" -" void *tp_subclasses; /* for static builtin types this is an index */\n" -" PyObject *tp_weaklist; /* not used for static builtin types */\n" -" destructor tp_del;\n" -"\n" -" /* Type attribute cache version tag. Added in version 2.6.\n" -" * If zero, the cache is invalid and must be initialized.\n" -" */\n" -" unsigned int tp_version_tag;\n" -"\n" -" destructor tp_finalize;\n" -" vectorcallfunc tp_vectorcall;\n" -"\n" -" /* bitset of which type-watchers care about this type */\n" -" unsigned char tp_watched;\n" -"\n" -" /* Number of tp_version_tag values used.\n" -" * Set to _Py_ATTR_CACHE_UNUSED if the attribute cache is\n" -" * disabled for this type (e.g. due to custom MRO entries).\n" -" * Otherwise, limited to MAX_VERSIONS_PER_CLASS (defined elsewhere).\n" -" */\n" -" uint16_t tp_versions_used;\n" -"} PyTypeObject;\n" -msgstr "" - -#: ../../extending/newtypes.rst:20 -msgid "" -"Now that's a *lot* of methods. Don't worry too much though -- if you have a " -"type you want to define, the chances are very good that you will only " -"implement a handful of these." -msgstr "" - -#: ../../extending/newtypes.rst:24 -msgid "" -"As you probably expect by now, we're going to go over this and give more " -"information about the various handlers. We won't go in the order they are " -"defined in the structure, because there is a lot of historical baggage that " -"impacts the ordering of the fields. It's often easiest to find an example " -"that includes the fields you need and then change the values to suit your " -"new type. ::" -msgstr "" - -#: ../../extending/newtypes.rst:31 -msgid "const char *tp_name; /* For printing */" -msgstr "" - -#: ../../extending/newtypes.rst:33 -msgid "" -"The name of the type -- as mentioned in the previous chapter, this will " -"appear in various places, almost entirely for diagnostic purposes. Try to " -"choose something that will be helpful in such a situation! ::" -msgstr "" - -#: ../../extending/newtypes.rst:37 -msgid "Py_ssize_t tp_basicsize, tp_itemsize; /* For allocation */" -msgstr "" - -#: ../../extending/newtypes.rst:39 -msgid "" -"These fields tell the runtime how much memory to allocate when new objects " -"of this type are created. Python has some built-in support for variable " -"length structures (think: strings, tuples) which is where " -"the :c:member:`~PyTypeObject.tp_itemsize` field comes in. This will be " -"dealt with later. ::" -msgstr "" - -#: ../../extending/newtypes.rst:44 -msgid "const char *tp_doc;" -msgstr "const char *tp_doc;" - -#: ../../extending/newtypes.rst:46 -msgid "" -"Here you can put a string (or its address) that you want returned when the " -"Python script references ``obj.__doc__`` to retrieve the doc string." -msgstr "" - -#: ../../extending/newtypes.rst:49 -msgid "" -"Now we come to the basic type methods -- the ones most extension types will " -"implement." -msgstr "" - -#: ../../extending/newtypes.rst:54 -msgid "Finalization and De-allocation" -msgstr "" - -#: ../../extending/newtypes.rst:64 -msgid "destructor tp_dealloc;" -msgstr "destructor tp_dealloc;" - -#: ../../extending/newtypes.rst:66 -msgid "" -"This function is called when the reference count of the instance of your " -"type is reduced to zero and the Python interpreter wants to reclaim it. If " -"your type has memory to free or other clean-up to perform, you can put it " -"here. The object itself needs to be freed here as well. Here is an example " -"of this function::" -msgstr "" - -#: ../../extending/newtypes.rst:72 -msgid "" -"static void\n" -"newdatatype_dealloc(PyObject *op)\n" -"{\n" -" newdatatypeobject *self = (newdatatypeobject *) op;\n" -" free(self->obj_UnderlyingDatatypePtr);\n" -" Py_TYPE(self)->tp_free(self);\n" -"}" -msgstr "" -"static void\n" -"newdatatype_dealloc(PyObject *op)\n" -"{\n" -" newdatatypeobject *self = (newdatatypeobject *) op;\n" -" free(self->obj_UnderlyingDatatypePtr);\n" -" Py_TYPE(self)->tp_free(self);\n" -"}" - -#: ../../extending/newtypes.rst:80 -msgid "" -"If your type supports garbage collection, the destructor should " -"call :c:func:`PyObject_GC_UnTrack` before clearing any member fields::" -msgstr "" - -#: ../../extending/newtypes.rst:83 -msgid "" -"static void\n" -"newdatatype_dealloc(PyObject *op)\n" -"{\n" -" newdatatypeobject *self = (newdatatypeobject *) op;\n" -" PyObject_GC_UnTrack(op);\n" -" Py_CLEAR(self->other_obj);\n" -" ...\n" -" Py_TYPE(self)->tp_free(self);\n" -"}" -msgstr "" -"static void\n" -"newdatatype_dealloc(PyObject *op)\n" -"{\n" -" newdatatypeobject *self = (newdatatypeobject *) op;\n" -" PyObject_GC_UnTrack(op);\n" -" Py_CLEAR(self->other_obj);\n" -" ...\n" -" Py_TYPE(self)->tp_free(self);\n" -"}" - -#: ../../extending/newtypes.rst:97 -msgid "" -"One important requirement of the deallocator function is that it leaves any " -"pending exceptions alone. This is important since deallocators are " -"frequently called as the interpreter unwinds the Python stack; when the " -"stack is unwound due to an exception (rather than normal returns), nothing " -"is done to protect the deallocators from seeing that an exception has " -"already been set. Any actions which a deallocator performs which may cause " -"additional Python code to be executed may detect that an exception has been " -"set. This can lead to misleading errors from the interpreter. The proper " -"way to protect against this is to save a pending exception before performing " -"the unsafe action, and restoring it when done. This can be done using " -"the :c:func:`PyErr_Fetch` and :c:func:`PyErr_Restore` functions::" -msgstr "" - -#: ../../extending/newtypes.rst:109 -msgid "" -"static void\n" -"my_dealloc(PyObject *obj)\n" -"{\n" -" MyObject *self = (MyObject *) obj;\n" -" PyObject *cbresult;\n" -"\n" -" if (self->my_callback != NULL) {\n" -" PyObject *err_type, *err_value, *err_traceback;\n" -"\n" -" /* This saves the current exception state */\n" -" PyErr_Fetch(&err_type, &err_value, &err_traceback);\n" -"\n" -" cbresult = PyObject_CallNoArgs(self->my_callback);\n" -" if (cbresult == NULL) {\n" -" PyErr_WriteUnraisable(self->my_callback);\n" -" }\n" -" else {\n" -" Py_DECREF(cbresult);\n" -" }\n" -"\n" -" /* This restores the saved exception state */\n" -" PyErr_Restore(err_type, err_value, err_traceback);\n" -"\n" -" Py_DECREF(self->my_callback);\n" -" }\n" -" Py_TYPE(self)->tp_free(self);\n" -"}" -msgstr "" - -#: ../../extending/newtypes.rst:138 -msgid "" -"There are limitations to what you can safely do in a deallocator function. " -"First, if your type supports garbage collection " -"(using :c:member:`~PyTypeObject.tp_traverse` and/" -"or :c:member:`~PyTypeObject.tp_clear`), some of the object's members can " -"have been cleared or finalized by the " -"time :c:member:`~PyTypeObject.tp_dealloc` is called. Second, " -"in :c:member:`~PyTypeObject.tp_dealloc`, your object is in an unstable " -"state: its reference count is equal to zero. Any call to a non-trivial " -"object or API (as in the example above) might end up " -"calling :c:member:`~PyTypeObject.tp_dealloc` again, causing a double free " -"and a crash." -msgstr "" - -#: ../../extending/newtypes.rst:147 -msgid "" -"Starting with Python 3.4, it is recommended not to put any complex " -"finalization code in :c:member:`~PyTypeObject.tp_dealloc`, and instead use " -"the new :c:member:`~PyTypeObject.tp_finalize` type method." -msgstr "" - -#: ../../extending/newtypes.rst:152 -msgid ":pep:`442` explains the new finalization scheme." -msgstr "" - -#: ../../extending/newtypes.rst:159 -msgid "Object Presentation" -msgstr "" - -#: ../../extending/newtypes.rst:161 -msgid "" -"In Python, there are two ways to generate a textual representation of an " -"object: the :func:`repr` function, and the :func:`str` function. " -"(The :func:`print` function just calls :func:`str`.) These handlers are " -"both optional." -msgstr "" - -#: ../../extending/newtypes.rst:167 -msgid "" -"reprfunc tp_repr;\n" -"reprfunc tp_str;" -msgstr "" -"reprfunc tp_repr;\n" -"reprfunc tp_str;" - -#: ../../extending/newtypes.rst:170 -msgid "" -"The :c:member:`~PyTypeObject.tp_repr` handler should return a string object " -"containing a representation of the instance for which it is called. Here is " -"a simple example::" -msgstr "" - -#: ../../extending/newtypes.rst:174 -msgid "" -"static PyObject *\n" -"newdatatype_repr(PyObject *op)\n" -"{\n" -" newdatatypeobject *self = (newdatatypeobject *) op;\n" -" return PyUnicode_FromFormat(\"Repr-ified_newdatatype{{size:%d}}\",\n" -" self->obj_UnderlyingDatatypePtr->size);\n" -"}" -msgstr "" -"static PyObject *\n" -"newdatatype_repr(PyObject *op)\n" -"{\n" -" newdatatypeobject *self = (newdatatypeobject *) op;\n" -" return PyUnicode_FromFormat(\"Repr-ified_newdatatype{{size:%d}}\",\n" -" self->obj_UnderlyingDatatypePtr->size);\n" -"}" - -#: ../../extending/newtypes.rst:182 -msgid "" -"If no :c:member:`~PyTypeObject.tp_repr` handler is specified, the " -"interpreter will supply a representation that uses the " -"type's :c:member:`~PyTypeObject.tp_name` and a uniquely identifying value " -"for the object." -msgstr "" - -#: ../../extending/newtypes.rst:186 -msgid "" -"The :c:member:`~PyTypeObject.tp_str` handler is to :func:`str` what " -"the :c:member:`~PyTypeObject.tp_repr` handler described above is " -"to :func:`repr`; that is, it is called when Python code calls :func:`str` on " -"an instance of your object. Its implementation is very similar to " -"the :c:member:`~PyTypeObject.tp_repr` function, but the resulting string is " -"intended for human consumption. If :c:member:`~PyTypeObject.tp_str` is not " -"specified, the :c:member:`~PyTypeObject.tp_repr` handler is used instead." -msgstr "" - -#: ../../extending/newtypes.rst:193 -msgid "Here is a simple example::" -msgstr "以下是個簡單的範例： ::" - -#: ../../extending/newtypes.rst:195 -msgid "" -"static PyObject *\n" -"newdatatype_str(PyObject *op)\n" -"{\n" -" newdatatypeobject *self = (newdatatypeobject *) op;\n" -" return PyUnicode_FromFormat(\"Stringified_newdatatype{{size:%d}}\",\n" -" self->obj_UnderlyingDatatypePtr->size);\n" -"}" -msgstr "" -"static PyObject *\n" -"newdatatype_str(PyObject *op)\n" -"{\n" -" newdatatypeobject *self = (newdatatypeobject *) op;\n" -" return PyUnicode_FromFormat(\"Stringified_newdatatype{{size:%d}}\",\n" -" self->obj_UnderlyingDatatypePtr->size);\n" -"}" - -#: ../../extending/newtypes.rst:206 -msgid "Attribute Management" -msgstr "" - -#: ../../extending/newtypes.rst:208 -msgid "" -"For every object which can support attributes, the corresponding type must " -"provide the functions that control how the attributes are resolved. There " -"needs to be a function which can retrieve attributes (if any are defined), " -"and another to set attributes (if setting attributes is allowed). Removing " -"an attribute is a special case, for which the new value passed to the " -"handler is ``NULL``." -msgstr "" - -#: ../../extending/newtypes.rst:214 -msgid "" -"Python supports two pairs of attribute handlers; a type that supports " -"attributes only needs to implement the functions for one pair. The " -"difference is that one pair takes the name of the attribute as " -"a :c:expr:`char\\*`, while the other accepts a :c:expr:`PyObject*`. Each " -"type can use whichever pair makes more sense for the implementation's " -"convenience. ::" -msgstr "" - -#: ../../extending/newtypes.rst:220 -msgid "" -"getattrfunc tp_getattr; /* char * version */\n" -"setattrfunc tp_setattr;\n" -"/* ... */\n" -"getattrofunc tp_getattro; /* PyObject * version */\n" -"setattrofunc tp_setattro;" -msgstr "" -"getattrfunc tp_getattr; /* char * version */\n" -"setattrfunc tp_setattr;\n" -"/* ... */\n" -"getattrofunc tp_getattro; /* PyObject * version */\n" -"setattrofunc tp_setattro;" - -#: ../../extending/newtypes.rst:226 -msgid "" -"If accessing attributes of an object is always a simple operation (this will " -"be explained shortly), there are generic implementations which can be used " -"to provide the :c:expr:`PyObject*` version of the attribute management " -"functions. The actual need for type-specific attribute handlers almost " -"completely disappeared starting with Python 2.2, though there are many " -"examples which have not been updated to use some of the new generic " -"mechanism that is available." -msgstr "" - -#: ../../extending/newtypes.rst:237 -msgid "Generic Attribute Management" -msgstr "" - -#: ../../extending/newtypes.rst:239 -msgid "" -"Most extension types only use *simple* attributes. So, what makes the " -"attributes simple? There are only a couple of conditions that must be met:" -msgstr "" - -#: ../../extending/newtypes.rst:242 -msgid "" -"The name of the attributes must be known when :c:func:`PyType_Ready` is " -"called." -msgstr "" - -#: ../../extending/newtypes.rst:245 -msgid "" -"No special processing is needed to record that an attribute was looked up or " -"set, nor do actions need to be taken based on the value." -msgstr "" - -#: ../../extending/newtypes.rst:248 -msgid "" -"Note that this list does not place any restrictions on the values of the " -"attributes, when the values are computed, or how relevant data is stored." -msgstr "" - -#: ../../extending/newtypes.rst:251 -msgid "" -"When :c:func:`PyType_Ready` is called, it uses three tables referenced by " -"the type object to create :term:`descriptor`\\s which are placed in the " -"dictionary of the type object. Each descriptor controls access to one " -"attribute of the instance object. Each of the tables is optional; if all " -"three are ``NULL``, instances of the type will only have attributes that are " -"inherited from their base type, and should leave " -"the :c:member:`~PyTypeObject.tp_getattro` " -"and :c:member:`~PyTypeObject.tp_setattro` fields ``NULL`` as well, allowing " -"the base type to handle attributes." -msgstr "" - -#: ../../extending/newtypes.rst:259 -msgid "The tables are declared as three fields of the type object::" -msgstr "" - -#: ../../extending/newtypes.rst:261 -msgid "" -"struct PyMethodDef *tp_methods;\n" -"struct PyMemberDef *tp_members;\n" -"struct PyGetSetDef *tp_getset;" -msgstr "" -"struct PyMethodDef *tp_methods;\n" -"struct PyMemberDef *tp_members;\n" -"struct PyGetSetDef *tp_getset;" - -#: ../../extending/newtypes.rst:265 -msgid "" -"If :c:member:`~PyTypeObject.tp_methods` is not ``NULL``, it must refer to an " -"array of :c:type:`PyMethodDef` structures. Each entry in the table is an " -"instance of this structure::" -msgstr "" - -#: ../../extending/newtypes.rst:269 -msgid "" -"typedef struct PyMethodDef {\n" -" const char *ml_name; /* method name */\n" -" PyCFunction ml_meth; /* implementation function */\n" -" int ml_flags; /* flags */\n" -" const char *ml_doc; /* docstring */\n" -"} PyMethodDef;" -msgstr "" - -#: ../../extending/newtypes.rst:276 -msgid "" -"One entry should be defined for each method provided by the type; no entries " -"are needed for methods inherited from a base type. One additional entry is " -"needed at the end; it is a sentinel that marks the end of the array. " -"The :c:member:`~PyMethodDef.ml_name` field of the sentinel must be ``NULL``." -msgstr "" - -#: ../../extending/newtypes.rst:281 -msgid "" -"The second table is used to define attributes which map directly to data " -"stored in the instance. A variety of primitive C types are supported, and " -"access may be read-only or read-write. The structures in the table are " -"defined as::" -msgstr "" - -#: ../../extending/newtypes.rst:285 -msgid "" -"typedef struct PyMemberDef {\n" -" const char *name;\n" -" int type;\n" -" int offset;\n" -" int flags;\n" -" const char *doc;\n" -"} PyMemberDef;" -msgstr "" -"typedef struct PyMemberDef {\n" -" const char *name;\n" -" int type;\n" -" int offset;\n" -" int flags;\n" -" const char *doc;\n" -"} PyMemberDef;" - -#: ../../extending/newtypes.rst:293 -msgid "" -"For each entry in the table, a :term:`descriptor` will be constructed and " -"added to the type which will be able to extract a value from the instance " -"structure. The :c:member:`~PyMemberDef.type` field should contain a type " -"code like :c:macro:`Py_T_INT` or :c:macro:`Py_T_DOUBLE`; the value will be " -"used to determine how to convert Python values to and from C values. " -"The :c:member:`~PyMemberDef.flags` field is used to store flags which " -"control how the attribute can be accessed: you can set it " -"to :c:macro:`Py_READONLY` to prevent Python code from setting it." -msgstr "" - -#: ../../extending/newtypes.rst:301 -msgid "" -"An interesting advantage of using the :c:member:`~PyTypeObject.tp_members` " -"table to build descriptors that are used at runtime is that any attribute " -"defined this way can have an associated doc string simply by providing the " -"text in the table. An application can use the introspection API to retrieve " -"the descriptor from the class object, and get the doc string using " -"its :attr:`~type.__doc__` attribute." -msgstr "" - -#: ../../extending/newtypes.rst:307 -msgid "" -"As with the :c:member:`~PyTypeObject.tp_methods` table, a sentinel entry " -"with a :c:member:`~PyMethodDef.ml_name` value of ``NULL`` is required." -msgstr "" - -#: ../../extending/newtypes.rst:321 -msgid "Type-specific Attribute Management" -msgstr "" - -#: ../../extending/newtypes.rst:323 -msgid "" -"For simplicity, only the :c:expr:`char\\*` version will be demonstrated " -"here; the type of the name parameter is the only difference between " -"the :c:expr:`char\\*` and :c:expr:`PyObject*` flavors of the interface. This " -"example effectively does the same thing as the generic example above, but " -"does not use the generic support added in Python 2.2. It explains how the " -"handler functions are called, so that if you do need to extend their " -"functionality, you'll understand what needs to be done." -msgstr "" - -#: ../../extending/newtypes.rst:331 -msgid "" -"The :c:member:`~PyTypeObject.tp_getattr` handler is called when the object " -"requires an attribute look-up. It is called in the same situations where " -"the :meth:`~object.__getattr__` method of a class would be called." -msgstr "" - -#: ../../extending/newtypes.rst:335 -msgid "Here is an example::" -msgstr "舉例來說： ::" - -#: ../../extending/newtypes.rst:337 -msgid "" -"static PyObject *\n" -"newdatatype_getattr(PyObject *op, char *name)\n" -"{\n" -" newdatatypeobject *self = (newdatatypeobject *) op;\n" -" if (strcmp(name, \"data\") == 0) {\n" -" return PyLong_FromLong(self->data);\n" -" }\n" -"\n" -" PyErr_Format(PyExc_AttributeError,\n" -" \"'%.100s' object has no attribute '%.400s'\",\n" -" Py_TYPE(self)->tp_name, name);\n" -" return NULL;\n" -"}" -msgstr "" - -#: ../../extending/newtypes.rst:351 -msgid "" -"The :c:member:`~PyTypeObject.tp_setattr` handler is called when " -"the :meth:`~object.__setattr__` or :meth:`~object.__delattr__` method of a " -"class instance would be called. When an attribute should be deleted, the " -"third parameter will be ``NULL``. Here is an example that simply raises an " -"exception; if this were really all you wanted, " -"the :c:member:`~PyTypeObject.tp_setattr` handler should be set to " -"``NULL``. ::" -msgstr "" - -#: ../../extending/newtypes.rst:357 -msgid "" -"static int\n" -"newdatatype_setattr(PyObject *op, char *name, PyObject *v)\n" -"{\n" -" PyErr_Format(PyExc_RuntimeError, \"Read-only attribute: %s\", name);\n" -" return -1;\n" -"}" -msgstr "" - -#: ../../extending/newtypes.rst:365 -msgid "Object Comparison" -msgstr "" - -#: ../../extending/newtypes.rst:369 -msgid "richcmpfunc tp_richcompare;" -msgstr "richcmpfunc tp_richcompare;" - -#: ../../extending/newtypes.rst:371 -msgid "" -"The :c:member:`~PyTypeObject.tp_richcompare` handler is called when " -"comparisons are needed. It is analogous to the :ref:`rich comparison " -"methods `, like :meth:`!__lt__`, and also called " -"by :c:func:`PyObject_RichCompare` and :c:func:`PyObject_RichCompareBool`." -msgstr "" - -#: ../../extending/newtypes.rst:376 -msgid "" -"This function is called with two Python objects and the operator as " -"arguments, where the operator is one of ``Py_EQ``, ``Py_NE``, ``Py_LE``, " -"``Py_GE``, ``Py_LT`` or ``Py_GT``. It should compare the two objects with " -"respect to the specified operator and return ``Py_True`` or ``Py_False`` if " -"the comparison is successful, ``Py_NotImplemented`` to indicate that " -"comparison is not implemented and the other object's comparison method " -"should be tried, or ``NULL`` if an exception was set." -msgstr "" - -#: ../../extending/newtypes.rst:384 -msgid "" -"Here is a sample implementation, for a datatype that is considered equal if " -"the size of an internal pointer is equal::" -msgstr "" - -#: ../../extending/newtypes.rst:387 -msgid "" -"static PyObject *\n" -"newdatatype_richcmp(PyObject *lhs, PyObject *rhs, int op)\n" -"{\n" -" newdatatypeobject *obj1 = (newdatatypeobject *) lhs;\n" -" newdatatypeobject *obj2 = (newdatatypeobject *) rhs;\n" -" PyObject *result;\n" -" int c, size1, size2;\n" -"\n" -" /* code to make sure that both arguments are of type\n" -" newdatatype omitted */\n" -"\n" -" size1 = obj1->obj_UnderlyingDatatypePtr->size;\n" -" size2 = obj2->obj_UnderlyingDatatypePtr->size;\n" -"\n" -" switch (op) {\n" -" case Py_LT: c = size1 < size2; break;\n" -" case Py_LE: c = size1 <= size2; break;\n" -" case Py_EQ: c = size1 == size2; break;\n" -" case Py_NE: c = size1 != size2; break;\n" -" case Py_GT: c = size1 > size2; break;\n" -" case Py_GE: c = size1 >= size2; break;\n" -" }\n" -" result = c ? Py_True : Py_False;\n" -" return Py_NewRef(result);\n" -" }" -msgstr "" - -#: ../../extending/newtypes.rst:415 -msgid "Abstract Protocol Support" -msgstr "" - -#: ../../extending/newtypes.rst:417 -msgid "" -"Python supports a variety of *abstract* 'protocols;' the specific interfaces " -"provided to use these interfaces are documented in :ref:`abstract`." -msgstr "" - -#: ../../extending/newtypes.rst:421 -msgid "" -"A number of these abstract interfaces were defined early in the development " -"of the Python implementation. In particular, the number, mapping, and " -"sequence protocols have been part of Python since the beginning. Other " -"protocols have been added over time. For protocols which depend on several " -"handler routines from the type implementation, the older protocols have been " -"defined as optional blocks of handlers referenced by the type object. For " -"newer protocols there are additional slots in the main type object, with a " -"flag bit being set to indicate that the slots are present and should be " -"checked by the interpreter. (The flag bit does not indicate that the slot " -"values are non-``NULL``. The flag may be set to indicate the presence of a " -"slot, but a slot may still be unfilled.) ::" -msgstr "" - -#: ../../extending/newtypes.rst:432 -msgid "" -"PyNumberMethods *tp_as_number;\n" -"PySequenceMethods *tp_as_sequence;\n" -"PyMappingMethods *tp_as_mapping;" -msgstr "" -"PyNumberMethods *tp_as_number;\n" -"PySequenceMethods *tp_as_sequence;\n" -"PyMappingMethods *tp_as_mapping;" - -#: ../../extending/newtypes.rst:436 -msgid "" -"If you wish your object to be able to act like a number, a sequence, or a " -"mapping object, then you place the address of a structure that implements " -"the C type :c:type:`PyNumberMethods`, :c:type:`PySequenceMethods`, " -"or :c:type:`PyMappingMethods`, respectively. It is up to you to fill in this " -"structure with appropriate values. You can find examples of the use of each " -"of these in the :file:`Objects` directory of the Python source " -"distribution. ::" -msgstr "" - -#: ../../extending/newtypes.rst:443 -msgid "hashfunc tp_hash;" -msgstr "hashfunc tp_hash;" - -#: ../../extending/newtypes.rst:445 -msgid "" -"This function, if you choose to provide it, should return a hash number for " -"an instance of your data type. Here is a simple example::" -msgstr "" - -#: ../../extending/newtypes.rst:448 -msgid "" -"static Py_hash_t\n" -"newdatatype_hash(PyObject *op)\n" -"{\n" -" newdatatypeobject *self = (newdatatypeobject *) op;\n" -" Py_hash_t result;\n" -" result = self->some_size + 32767 * self->some_number;\n" -" if (result == -1) {\n" -" result = -2;\n" -" }\n" -" return result;\n" -"}" -msgstr "" -"static Py_hash_t\n" -"newdatatype_hash(PyObject *op)\n" -"{\n" -" newdatatypeobject *self = (newdatatypeobject *) op;\n" -" Py_hash_t result;\n" -" result = self->some_size + 32767 * self->some_number;\n" -" if (result == -1) {\n" -" result = -2;\n" -" }\n" -" return result;\n" -"}" - -#: ../../extending/newtypes.rst:460 -msgid "" -":c:type:`Py_hash_t` is a signed integer type with a platform-varying width. " -"Returning ``-1`` from :c:member:`~PyTypeObject.tp_hash` indicates an error, " -"which is why you should be careful to avoid returning it when hash " -"computation is successful, as seen above." -msgstr "" - -#: ../../extending/newtypes.rst:467 -msgid "ternaryfunc tp_call;" -msgstr "ternaryfunc tp_call;" - -#: ../../extending/newtypes.rst:469 -msgid "" -"This function is called when an instance of your data type is \"called\", " -"for example, if ``obj1`` is an instance of your data type and the Python " -"script contains ``obj1('hello')``, the :c:member:`~PyTypeObject.tp_call` " -"handler is invoked." -msgstr "" - -#: ../../extending/newtypes.rst:473 -msgid "This function takes three arguments:" -msgstr "" - -#: ../../extending/newtypes.rst:475 -msgid "" -"*self* is the instance of the data type which is the subject of the call. If " -"the call is ``obj1('hello')``, then *self* is ``obj1``." -msgstr "" - -#: ../../extending/newtypes.rst:478 -msgid "" -"*args* is a tuple containing the arguments to the call. You can " -"use :c:func:`PyArg_ParseTuple` to extract the arguments." -msgstr "" - -#: ../../extending/newtypes.rst:481 -msgid "" -"*kwds* is a dictionary of keyword arguments that were passed. If this is non-" -"``NULL`` and you support keyword arguments, " -"use :c:func:`PyArg_ParseTupleAndKeywords` to extract the arguments. If you " -"do not want to support keyword arguments and this is non-``NULL``, raise " -"a :exc:`TypeError` with a message saying that keyword arguments are not " -"supported." -msgstr "" - -#: ../../extending/newtypes.rst:487 -msgid "Here is a toy ``tp_call`` implementation::" -msgstr "" - -#: ../../extending/newtypes.rst:489 -msgid "" -"static PyObject *\n" -"newdatatype_call(PyObject *op, PyObject *args, PyObject *kwds)\n" -"{\n" -" newdatatypeobject *self = (newdatatypeobject *) op;\n" -" PyObject *result;\n" -" const char *arg1;\n" -" const char *arg2;\n" -" const char *arg3;\n" -"\n" -" if (!PyArg_ParseTuple(args, \"sss:call\", &arg1, &arg2, &arg3)) {\n" -" return NULL;\n" -" }\n" -" result = PyUnicode_FromFormat(\n" -" \"Returning -- value: [%d] arg1: [%s] arg2: [%s] arg3: [%s]\\n\",\n" -" self->obj_UnderlyingDatatypePtr->size,\n" -" arg1, arg2, arg3);\n" -" return result;\n" -"}" -msgstr "" -"static PyObject *\n" -"newdatatype_call(PyObject *op, PyObject *args, PyObject *kwds)\n" -"{\n" -" newdatatypeobject *self = (newdatatypeobject *) op;\n" -" PyObject *result;\n" -" const char *arg1;\n" -" const char *arg2;\n" -" const char *arg3;\n" -"\n" -" if (!PyArg_ParseTuple(args, \"sss:call\", &arg1, &arg2, &arg3)) {\n" -" return NULL;\n" -" }\n" -" result = PyUnicode_FromFormat(\n" -" \"Returning -- value: [%d] arg1: [%s] arg2: [%s] arg3: [%s]\\n\",\n" -" self->obj_UnderlyingDatatypePtr->size,\n" -" arg1, arg2, arg3);\n" -" return result;\n" -"}" - -#: ../../extending/newtypes.rst:510 -msgid "" -"/* Iterators */\n" -"getiterfunc tp_iter;\n" -"iternextfunc tp_iternext;" -msgstr "" -"/* 疊代器 */\n" -"getiterfunc tp_iter;\n" -"iternextfunc tp_iternext;" - -#: ../../extending/newtypes.rst:514 -msgid "" -"These functions provide support for the iterator protocol. Both handlers " -"take exactly one parameter, the instance for which they are being called, " -"and return a new reference. In the case of an error, they should set an " -"exception and return ``NULL``. :c:member:`~PyTypeObject.tp_iter` " -"corresponds to the Python :meth:`~object.__iter__` method, " -"while :c:member:`~PyTypeObject.tp_iternext` corresponds to the " -"Python :meth:`~iterator.__next__` method." -msgstr "" - -#: ../../extending/newtypes.rst:521 -msgid "" -"Any :term:`iterable` object must implement " -"the :c:member:`~PyTypeObject.tp_iter` handler, which must return " -"an :term:`iterator` object. Here the same guidelines apply as for Python " -"classes:" -msgstr "" - -#: ../../extending/newtypes.rst:525 -msgid "" -"For collections (such as lists and tuples) which can support multiple " -"independent iterators, a new iterator should be created and returned by each " -"call to :c:member:`~PyTypeObject.tp_iter`." -msgstr "" - -#: ../../extending/newtypes.rst:528 -msgid "" -"Objects which can only be iterated over once (usually due to side effects of " -"iteration, such as file objects) can " -"implement :c:member:`~PyTypeObject.tp_iter` by returning a new reference to " -"themselves -- and should also therefore implement " -"the :c:member:`~PyTypeObject.tp_iternext` handler." -msgstr "" - -#: ../../extending/newtypes.rst:533 -msgid "" -"Any :term:`iterator` object should implement " -"both :c:member:`~PyTypeObject.tp_iter` " -"and :c:member:`~PyTypeObject.tp_iternext`. An " -"iterator's :c:member:`~PyTypeObject.tp_iter` handler should return a new " -"reference to the iterator. Its :c:member:`~PyTypeObject.tp_iternext` " -"handler should return a new reference to the next object in the iteration, " -"if there is one. If the iteration has reached the " -"end, :c:member:`~PyTypeObject.tp_iternext` may return ``NULL`` without " -"setting an exception, or it may set :exc:`StopIteration` *in addition* to " -"returning ``NULL``; avoiding the exception can yield slightly better " -"performance. If an actual error " -"occurs, :c:member:`~PyTypeObject.tp_iternext` should always set an exception " -"and return ``NULL``." -msgstr "" - -#: ../../extending/newtypes.rst:549 -msgid "Weak Reference Support" -msgstr "" - -#: ../../extending/newtypes.rst:551 -msgid "" -"One of the goals of Python's weak reference implementation is to allow any " -"type to participate in the weak reference mechanism without incurring the " -"overhead on performance-critical objects (such as numbers)." -msgstr "" - -#: ../../extending/newtypes.rst:556 -msgid "Documentation for the :mod:`weakref` module." -msgstr "" - -#: ../../extending/newtypes.rst:558 -msgid "" -"For an object to be weakly referenceable, the extension type must set the " -"``Py_TPFLAGS_MANAGED_WEAKREF`` bit of the :c:member:`~PyTypeObject.tp_flags` " -"field. The legacy :c:member:`~PyTypeObject.tp_weaklistoffset` field should " -"be left as zero." -msgstr "" - -#: ../../extending/newtypes.rst:563 -msgid "" -"Concretely, here is how the statically declared type object would look::" -msgstr "" - -#: ../../extending/newtypes.rst:565 -msgid "" -"static PyTypeObject TrivialType = {\n" -" PyVarObject_HEAD_INIT(NULL, 0)\n" -" /* ... other members omitted for brevity ... */\n" -" .tp_flags = Py_TPFLAGS_MANAGED_WEAKREF | ...,\n" -"};" -msgstr "" - -#: ../../extending/newtypes.rst:572 -msgid "" -"The only further addition is that ``tp_dealloc`` needs to clear any weak " -"references (by calling :c:func:`PyObject_ClearWeakRefs`)::" -msgstr "" - -#: ../../extending/newtypes.rst:575 -msgid "" -"static void\n" -"Trivial_dealloc(PyObject *op)\n" -"{\n" -" /* Clear weakrefs first before calling any destructors */\n" -" PyObject_ClearWeakRefs(op);\n" -" /* ... remainder of destruction code omitted for brevity ... */\n" -" Py_TYPE(op)->tp_free(op);\n" -"}" -msgstr "" - -#: ../../extending/newtypes.rst:586 -msgid "More Suggestions" -msgstr "" - -#: ../../extending/newtypes.rst:588 -msgid "" -"In order to learn how to implement any specific method for your new data " -"type, get the :term:`CPython` source code. Go to the :file:`Objects` " -"directory, then search the C source files for ``tp_`` plus the function you " -"want (for example, ``tp_richcompare``). You will find examples of the " -"function you want to implement." -msgstr "" - -#: ../../extending/newtypes.rst:594 -msgid "" -"When you need to verify that an object is a concrete instance of the type " -"you are implementing, use the :c:func:`PyObject_TypeCheck` function. A " -"sample of its use might be something like the following::" -msgstr "" - -#: ../../extending/newtypes.rst:598 -msgid "" -"if (!PyObject_TypeCheck(some_object, &MyType)) {\n" -" PyErr_SetString(PyExc_TypeError, \"arg #1 not a mything\");\n" -" return NULL;\n" -"}" -msgstr "" - -#: ../../extending/newtypes.rst:604 -msgid "Download CPython source releases." -msgstr "" - -#: ../../extending/newtypes.rst:605 -msgid "https://www.python.org/downloads/source/" -msgstr "https://www.python.org/downloads/source/" - -#: ../../extending/newtypes.rst:607 -msgid "" -"The CPython project on GitHub, where the CPython source code is developed." -msgstr "" - -#: ../../extending/newtypes.rst:608 -msgid "https://github.com/python/cpython" -msgstr "https://github.com/python/cpython" - -#: ../../extending/newtypes.rst:56 -msgid "object" -msgstr "object（物件）" - -#: ../../extending/newtypes.rst:56 -msgid "deallocation" -msgstr "" - -#: ../../extending/newtypes.rst:56 -msgid "deallocation, object" -msgstr "" - -#: ../../extending/newtypes.rst:56 -msgid "finalization" -msgstr "" - -#: ../../extending/newtypes.rst:56 -msgid "finalization, of objects" -msgstr "" - -#: ../../extending/newtypes.rst:93 -msgid "PyErr_Fetch (C function)" -msgstr "PyErr_Fetch（C 函式）" - -#: ../../extending/newtypes.rst:93 -msgid "PyErr_Restore (C function)" -msgstr "PyErr_Restore（C 函式）" - -#: ../../extending/newtypes.rst:154 -msgid "string" -msgstr "string（字串）" - -#: ../../extending/newtypes.rst:154 -msgid "object representation" -msgstr "object representation（物件表示）" - -#: ../../extending/newtypes.rst:154 -msgid "built-in function" -msgstr "built-in function（內建函式）" - -#: ../../extending/newtypes.rst:154 -msgid "repr" -msgstr "repr" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Leon H., 2017 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: 2018-05-23 14:34+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" + +#: ../../extending/newtypes.rst:7 +msgid "Defining Extension Types: Assorted Topics" +msgstr "" + +#: ../../extending/newtypes.rst:11 +msgid "" +"This section aims to give a quick fly-by on the various type methods you can " +"implement and what they do." +msgstr "" + +#: ../../extending/newtypes.rst:14 +msgid "" +"Here is the definition of :c:type:`PyTypeObject`, with some fields only used " +"in :ref:`debug builds ` omitted:" +msgstr "" + +#: ../../extending/newtypes.rst:17 +msgid "" +"typedef struct _typeobject {\n" +" PyObject_VAR_HEAD\n" +" const char *tp_name; /* For printing, in format \".\" */\n" +" Py_ssize_t tp_basicsize, tp_itemsize; /* For allocation */\n" +"\n" +" /* Methods to implement standard operations */\n" +"\n" +" destructor tp_dealloc;\n" +" Py_ssize_t tp_vectorcall_offset;\n" +" getattrfunc tp_getattr;\n" +" setattrfunc tp_setattr;\n" +" PyAsyncMethods *tp_as_async; /* formerly known as tp_compare (Python 2)\n" +" or tp_reserved (Python 3) */\n" +" reprfunc tp_repr;\n" +"\n" +" /* Method suites for standard classes */\n" +"\n" +" PyNumberMethods *tp_as_number;\n" +" PySequenceMethods *tp_as_sequence;\n" +" PyMappingMethods *tp_as_mapping;\n" +"\n" +" /* More standard operations (here for binary compatibility) */\n" +"\n" +" hashfunc tp_hash;\n" +" ternaryfunc tp_call;\n" +" reprfunc tp_str;\n" +" getattrofunc tp_getattro;\n" +" setattrofunc tp_setattro;\n" +"\n" +" /* Functions to access object as input/output buffer */\n" +" PyBufferProcs *tp_as_buffer;\n" +"\n" +" /* Flags to define presence of optional/expanded features */\n" +" unsigned long tp_flags;\n" +"\n" +" const char *tp_doc; /* Documentation string */\n" +"\n" +" /* Assigned meaning in release 2.0 */\n" +" /* call function for all accessible objects */\n" +" traverseproc tp_traverse;\n" +"\n" +" /* delete references to contained objects */\n" +" inquiry tp_clear;\n" +"\n" +" /* Assigned meaning in release 2.1 */\n" +" /* rich comparisons */\n" +" richcmpfunc tp_richcompare;\n" +"\n" +" /* weak reference enabler */\n" +" Py_ssize_t tp_weaklistoffset;\n" +"\n" +" /* Iterators */\n" +" getiterfunc tp_iter;\n" +" iternextfunc tp_iternext;\n" +"\n" +" /* Attribute descriptor and subclassing stuff */\n" +" PyMethodDef *tp_methods;\n" +" PyMemberDef *tp_members;\n" +" PyGetSetDef *tp_getset;\n" +" // Strong reference on a heap type, borrowed reference on a static type\n" +" PyTypeObject *tp_base;\n" +" PyObject *tp_dict;\n" +" descrgetfunc tp_descr_get;\n" +" descrsetfunc tp_descr_set;\n" +" Py_ssize_t tp_dictoffset;\n" +" initproc tp_init;\n" +" allocfunc tp_alloc;\n" +" newfunc tp_new;\n" +" freefunc tp_free; /* Low-level free-memory routine */\n" +" inquiry tp_is_gc; /* For PyObject_IS_GC */\n" +" PyObject *tp_bases;\n" +" PyObject *tp_mro; /* method resolution order */\n" +" PyObject *tp_cache; /* no longer used */\n" +" void *tp_subclasses; /* for static builtin types this is an index */\n" +" PyObject *tp_weaklist; /* not used for static builtin types */\n" +" destructor tp_del;\n" +"\n" +" /* Type attribute cache version tag. Added in version 2.6.\n" +" * If zero, the cache is invalid and must be initialized.\n" +" */\n" +" unsigned int tp_version_tag;\n" +"\n" +" destructor tp_finalize;\n" +" vectorcallfunc tp_vectorcall;\n" +"\n" +" /* bitset of which type-watchers care about this type */\n" +" unsigned char tp_watched;\n" +"\n" +" /* Number of tp_version_tag values used.\n" +" * Set to _Py_ATTR_CACHE_UNUSED if the attribute cache is\n" +" * disabled for this type (e.g. due to custom MRO entries).\n" +" * Otherwise, limited to MAX_VERSIONS_PER_CLASS (defined elsewhere).\n" +" */\n" +" uint16_t tp_versions_used;\n" +"} PyTypeObject;\n" +msgstr "" + +#: ../../extending/newtypes.rst:20 +msgid "" +"Now that's a *lot* of methods. Don't worry too much though -- if you have a " +"type you want to define, the chances are very good that you will only " +"implement a handful of these." +msgstr "" + +#: ../../extending/newtypes.rst:24 +msgid "" +"As you probably expect by now, we're going to go over this and give more " +"information about the various handlers. We won't go in the order they are " +"defined in the structure, because there is a lot of historical baggage that " +"impacts the ordering of the fields. It's often easiest to find an example " +"that includes the fields you need and then change the values to suit your " +"new type. ::" +msgstr "" + +#: ../../extending/newtypes.rst:31 +msgid "const char *tp_name; /* For printing */" +msgstr "" + +#: ../../extending/newtypes.rst:33 +msgid "" +"The name of the type -- as mentioned in the previous chapter, this will " +"appear in various places, almost entirely for diagnostic purposes. Try to " +"choose something that will be helpful in such a situation! ::" +msgstr "" + +#: ../../extending/newtypes.rst:37 +msgid "Py_ssize_t tp_basicsize, tp_itemsize; /* For allocation */" +msgstr "" + +#: ../../extending/newtypes.rst:39 +msgid "" +"These fields tell the runtime how much memory to allocate when new objects " +"of this type are created. Python has some built-in support for variable " +"length structures (think: strings, tuples) which is where " +"the :c:member:`~PyTypeObject.tp_itemsize` field comes in. This will be " +"dealt with later. ::" +msgstr "" + +#: ../../extending/newtypes.rst:44 +msgid "const char *tp_doc;" +msgstr "const char *tp_doc;" + +#: ../../extending/newtypes.rst:46 +msgid "" +"Here you can put a string (or its address) that you want returned when the " +"Python script references ``obj.__doc__`` to retrieve the doc string." +msgstr "" + +#: ../../extending/newtypes.rst:49 +msgid "" +"Now we come to the basic type methods -- the ones most extension types will " +"implement." +msgstr "" + +#: ../../extending/newtypes.rst:54 +msgid "Finalization and De-allocation" +msgstr "" + +#: ../../extending/newtypes.rst:64 +msgid "destructor tp_dealloc;" +msgstr "destructor tp_dealloc;" + +#: ../../extending/newtypes.rst:66 +msgid "" +"This function is called when the reference count of the instance of your " +"type is reduced to zero and the Python interpreter wants to reclaim it. If " +"your type has memory to free or other clean-up to perform, you can put it " +"here. The object itself needs to be freed here as well. Here is an example " +"of this function::" +msgstr "" + +#: ../../extending/newtypes.rst:72 +msgid "" +"static void\n" +"newdatatype_dealloc(PyObject *op)\n" +"{\n" +" newdatatypeobject *self = (newdatatypeobject *) op;\n" +" free(self->obj_UnderlyingDatatypePtr);\n" +" Py_TYPE(self)->tp_free(self);\n" +"}" +msgstr "" +"static void\n" +"newdatatype_dealloc(PyObject *op)\n" +"{\n" +" newdatatypeobject *self = (newdatatypeobject *) op;\n" +" free(self->obj_UnderlyingDatatypePtr);\n" +" Py_TYPE(self)->tp_free(self);\n" +"}" + +#: ../../extending/newtypes.rst:80 +msgid "" +"If your type supports garbage collection, the destructor should " +"call :c:func:`PyObject_GC_UnTrack` before clearing any member fields::" +msgstr "" + +#: ../../extending/newtypes.rst:83 +msgid "" +"static void\n" +"newdatatype_dealloc(PyObject *op)\n" +"{\n" +" newdatatypeobject *self = (newdatatypeobject *) op;\n" +" PyObject_GC_UnTrack(op);\n" +" Py_CLEAR(self->other_obj);\n" +" ...\n" +" Py_TYPE(self)->tp_free(self);\n" +"}" +msgstr "" +"static void\n" +"newdatatype_dealloc(PyObject *op)\n" +"{\n" +" newdatatypeobject *self = (newdatatypeobject *) op;\n" +" PyObject_GC_UnTrack(op);\n" +" Py_CLEAR(self->other_obj);\n" +" ...\n" +" Py_TYPE(self)->tp_free(self);\n" +"}" + +#: ../../extending/newtypes.rst:97 +msgid "" +"One important requirement of the deallocator function is that it leaves any " +"pending exceptions alone. This is important since deallocators are " +"frequently called as the interpreter unwinds the Python stack; when the " +"stack is unwound due to an exception (rather than normal returns), nothing " +"is done to protect the deallocators from seeing that an exception has " +"already been set. Any actions which a deallocator performs which may cause " +"additional Python code to be executed may detect that an exception has been " +"set. This can lead to misleading errors from the interpreter. The proper " +"way to protect against this is to save a pending exception before performing " +"the unsafe action, and restoring it when done. This can be done using " +"the :c:func:`PyErr_Fetch` and :c:func:`PyErr_Restore` functions::" +msgstr "" + +#: ../../extending/newtypes.rst:109 +msgid "" +"static void\n" +"my_dealloc(PyObject *obj)\n" +"{\n" +" MyObject *self = (MyObject *) obj;\n" +" PyObject *cbresult;\n" +"\n" +" if (self->my_callback != NULL) {\n" +" PyObject *err_type, *err_value, *err_traceback;\n" +"\n" +" /* This saves the current exception state */\n" +" PyErr_Fetch(&err_type, &err_value, &err_traceback);\n" +"\n" +" cbresult = PyObject_CallNoArgs(self->my_callback);\n" +" if (cbresult == NULL) {\n" +" PyErr_WriteUnraisable(self->my_callback);\n" +" }\n" +" else {\n" +" Py_DECREF(cbresult);\n" +" }\n" +"\n" +" /* This restores the saved exception state */\n" +" PyErr_Restore(err_type, err_value, err_traceback);\n" +"\n" +" Py_DECREF(self->my_callback);\n" +" }\n" +" Py_TYPE(self)->tp_free(self);\n" +"}" +msgstr "" + +#: ../../extending/newtypes.rst:138 +msgid "" +"There are limitations to what you can safely do in a deallocator function. " +"First, if your type supports garbage collection " +"(using :c:member:`~PyTypeObject.tp_traverse` and/" +"or :c:member:`~PyTypeObject.tp_clear`), some of the object's members can " +"have been cleared or finalized by the " +"time :c:member:`~PyTypeObject.tp_dealloc` is called. Second, " +"in :c:member:`~PyTypeObject.tp_dealloc`, your object is in an unstable " +"state: its reference count is equal to zero. Any call to a non-trivial " +"object or API (as in the example above) might end up " +"calling :c:member:`~PyTypeObject.tp_dealloc` again, causing a double free " +"and a crash." +msgstr "" + +#: ../../extending/newtypes.rst:147 +msgid "" +"Starting with Python 3.4, it is recommended not to put any complex " +"finalization code in :c:member:`~PyTypeObject.tp_dealloc`, and instead use " +"the new :c:member:`~PyTypeObject.tp_finalize` type method." +msgstr "" + +#: ../../extending/newtypes.rst:152 +msgid ":pep:`442` explains the new finalization scheme." +msgstr "" + +#: ../../extending/newtypes.rst:159 +msgid "Object Presentation" +msgstr "" + +#: ../../extending/newtypes.rst:161 +msgid "" +"In Python, there are two ways to generate a textual representation of an " +"object: the :func:`repr` function, and the :func:`str` function. " +"(The :func:`print` function just calls :func:`str`.) These handlers are " +"both optional." +msgstr "" + +#: ../../extending/newtypes.rst:167 +msgid "" +"reprfunc tp_repr;\n" +"reprfunc tp_str;" +msgstr "" +"reprfunc tp_repr;\n" +"reprfunc tp_str;" + +#: ../../extending/newtypes.rst:170 +msgid "" +"The :c:member:`~PyTypeObject.tp_repr` handler should return a string object " +"containing a representation of the instance for which it is called. Here is " +"a simple example::" +msgstr "" + +#: ../../extending/newtypes.rst:174 +msgid "" +"static PyObject *\n" +"newdatatype_repr(PyObject *op)\n" +"{\n" +" newdatatypeobject *self = (newdatatypeobject *) op;\n" +" return PyUnicode_FromFormat(\"Repr-ified_newdatatype{{size:%d}}\",\n" +" self->obj_UnderlyingDatatypePtr->size);\n" +"}" +msgstr "" +"static PyObject *\n" +"newdatatype_repr(PyObject *op)\n" +"{\n" +" newdatatypeobject *self = (newdatatypeobject *) op;\n" +" return PyUnicode_FromFormat(\"Repr-ified_newdatatype{{size:%d}}\",\n" +" self->obj_UnderlyingDatatypePtr->size);\n" +"}" + +#: ../../extending/newtypes.rst:182 +msgid "" +"If no :c:member:`~PyTypeObject.tp_repr` handler is specified, the " +"interpreter will supply a representation that uses the " +"type's :c:member:`~PyTypeObject.tp_name` and a uniquely identifying value " +"for the object." +msgstr "" + +#: ../../extending/newtypes.rst:186 +msgid "" +"The :c:member:`~PyTypeObject.tp_str` handler is to :func:`str` what " +"the :c:member:`~PyTypeObject.tp_repr` handler described above is " +"to :func:`repr`; that is, it is called when Python code calls :func:`str` on " +"an instance of your object. Its implementation is very similar to " +"the :c:member:`~PyTypeObject.tp_repr` function, but the resulting string is " +"intended for human consumption. If :c:member:`~PyTypeObject.tp_str` is not " +"specified, the :c:member:`~PyTypeObject.tp_repr` handler is used instead." +msgstr "" + +#: ../../extending/newtypes.rst:193 +msgid "Here is a simple example::" +msgstr "以下是個簡單的範例： ::" + +#: ../../extending/newtypes.rst:195 +msgid "" +"static PyObject *\n" +"newdatatype_str(PyObject *op)\n" +"{\n" +" newdatatypeobject *self = (newdatatypeobject *) op;\n" +" return PyUnicode_FromFormat(\"Stringified_newdatatype{{size:%d}}\",\n" +" self->obj_UnderlyingDatatypePtr->size);\n" +"}" +msgstr "" +"static PyObject *\n" +"newdatatype_str(PyObject *op)\n" +"{\n" +" newdatatypeobject *self = (newdatatypeobject *) op;\n" +" return PyUnicode_FromFormat(\"Stringified_newdatatype{{size:%d}}\",\n" +" self->obj_UnderlyingDatatypePtr->size);\n" +"}" + +#: ../../extending/newtypes.rst:206 +msgid "Attribute Management" +msgstr "" + +#: ../../extending/newtypes.rst:208 +msgid "" +"For every object which can support attributes, the corresponding type must " +"provide the functions that control how the attributes are resolved. There " +"needs to be a function which can retrieve attributes (if any are defined), " +"and another to set attributes (if setting attributes is allowed). Removing " +"an attribute is a special case, for which the new value passed to the " +"handler is ``NULL``." +msgstr "" + +#: ../../extending/newtypes.rst:214 +msgid "" +"Python supports two pairs of attribute handlers; a type that supports " +"attributes only needs to implement the functions for one pair. The " +"difference is that one pair takes the name of the attribute as " +"a :c:expr:`char\\*`, while the other accepts a :c:expr:`PyObject*`. Each " +"type can use whichever pair makes more sense for the implementation's " +"convenience. ::" +msgstr "" + +#: ../../extending/newtypes.rst:220 +msgid "" +"getattrfunc tp_getattr; /* char * version */\n" +"setattrfunc tp_setattr;\n" +"/* ... */\n" +"getattrofunc tp_getattro; /* PyObject * version */\n" +"setattrofunc tp_setattro;" +msgstr "" +"getattrfunc tp_getattr; /* char * version */\n" +"setattrfunc tp_setattr;\n" +"/* ... */\n" +"getattrofunc tp_getattro; /* PyObject * version */\n" +"setattrofunc tp_setattro;" + +#: ../../extending/newtypes.rst:226 +msgid "" +"If accessing attributes of an object is always a simple operation (this will " +"be explained shortly), there are generic implementations which can be used " +"to provide the :c:expr:`PyObject*` version of the attribute management " +"functions. The actual need for type-specific attribute handlers almost " +"completely disappeared starting with Python 2.2, though there are many " +"examples which have not been updated to use some of the new generic " +"mechanism that is available." +msgstr "" + +#: ../../extending/newtypes.rst:237 +msgid "Generic Attribute Management" +msgstr "" + +#: ../../extending/newtypes.rst:239 +msgid "" +"Most extension types only use *simple* attributes. So, what makes the " +"attributes simple? There are only a couple of conditions that must be met:" +msgstr "" + +#: ../../extending/newtypes.rst:242 +msgid "" +"The name of the attributes must be known when :c:func:`PyType_Ready` is " +"called." +msgstr "" + +#: ../../extending/newtypes.rst:245 +msgid "" +"No special processing is needed to record that an attribute was looked up or " +"set, nor do actions need to be taken based on the value." +msgstr "" + +#: ../../extending/newtypes.rst:248 +msgid "" +"Note that this list does not place any restrictions on the values of the " +"attributes, when the values are computed, or how relevant data is stored." +msgstr "" + +#: ../../extending/newtypes.rst:251 +msgid "" +"When :c:func:`PyType_Ready` is called, it uses three tables referenced by " +"the type object to create :term:`descriptor`\\s which are placed in the " +"dictionary of the type object. Each descriptor controls access to one " +"attribute of the instance object. Each of the tables is optional; if all " +"three are ``NULL``, instances of the type will only have attributes that are " +"inherited from their base type, and should leave " +"the :c:member:`~PyTypeObject.tp_getattro` " +"and :c:member:`~PyTypeObject.tp_setattro` fields ``NULL`` as well, allowing " +"the base type to handle attributes." +msgstr "" + +#: ../../extending/newtypes.rst:259 +msgid "The tables are declared as three fields of the type object::" +msgstr "" + +#: ../../extending/newtypes.rst:261 +msgid "" +"struct PyMethodDef *tp_methods;\n" +"struct PyMemberDef *tp_members;\n" +"struct PyGetSetDef *tp_getset;" +msgstr "" +"struct PyMethodDef *tp_methods;\n" +"struct PyMemberDef *tp_members;\n" +"struct PyGetSetDef *tp_getset;" + +#: ../../extending/newtypes.rst:265 +msgid "" +"If :c:member:`~PyTypeObject.tp_methods` is not ``NULL``, it must refer to an " +"array of :c:type:`PyMethodDef` structures. Each entry in the table is an " +"instance of this structure::" +msgstr "" + +#: ../../extending/newtypes.rst:269 +msgid "" +"typedef struct PyMethodDef {\n" +" const char *ml_name; /* method name */\n" +" PyCFunction ml_meth; /* implementation function */\n" +" int ml_flags; /* flags */\n" +" const char *ml_doc; /* docstring */\n" +"} PyMethodDef;" +msgstr "" + +#: ../../extending/newtypes.rst:276 +msgid "" +"One entry should be defined for each method provided by the type; no entries " +"are needed for methods inherited from a base type. One additional entry is " +"needed at the end; it is a sentinel that marks the end of the array. " +"The :c:member:`~PyMethodDef.ml_name` field of the sentinel must be ``NULL``." +msgstr "" + +#: ../../extending/newtypes.rst:281 +msgid "" +"The second table is used to define attributes which map directly to data " +"stored in the instance. A variety of primitive C types are supported, and " +"access may be read-only or read-write. The structures in the table are " +"defined as::" +msgstr "" + +#: ../../extending/newtypes.rst:285 +msgid "" +"typedef struct PyMemberDef {\n" +" const char *name;\n" +" int type;\n" +" int offset;\n" +" int flags;\n" +" const char *doc;\n" +"} PyMemberDef;" +msgstr "" +"typedef struct PyMemberDef {\n" +" const char *name;\n" +" int type;\n" +" int offset;\n" +" int flags;\n" +" const char *doc;\n" +"} PyMemberDef;" + +#: ../../extending/newtypes.rst:293 +msgid "" +"For each entry in the table, a :term:`descriptor` will be constructed and " +"added to the type which will be able to extract a value from the instance " +"structure. The :c:member:`~PyMemberDef.type` field should contain a type " +"code like :c:macro:`Py_T_INT` or :c:macro:`Py_T_DOUBLE`; the value will be " +"used to determine how to convert Python values to and from C values. " +"The :c:member:`~PyMemberDef.flags` field is used to store flags which " +"control how the attribute can be accessed: you can set it " +"to :c:macro:`Py_READONLY` to prevent Python code from setting it." +msgstr "" + +#: ../../extending/newtypes.rst:301 +msgid "" +"An interesting advantage of using the :c:member:`~PyTypeObject.tp_members` " +"table to build descriptors that are used at runtime is that any attribute " +"defined this way can have an associated doc string simply by providing the " +"text in the table. An application can use the introspection API to retrieve " +"the descriptor from the class object, and get the doc string using " +"its :attr:`~type.__doc__` attribute." +msgstr "" + +#: ../../extending/newtypes.rst:307 +msgid "" +"As with the :c:member:`~PyTypeObject.tp_methods` table, a sentinel entry " +"with a :c:member:`~PyMethodDef.ml_name` value of ``NULL`` is required." +msgstr "" + +#: ../../extending/newtypes.rst:321 +msgid "Type-specific Attribute Management" +msgstr "" + +#: ../../extending/newtypes.rst:323 +msgid "" +"For simplicity, only the :c:expr:`char\\*` version will be demonstrated " +"here; the type of the name parameter is the only difference between " +"the :c:expr:`char\\*` and :c:expr:`PyObject*` flavors of the interface. This " +"example effectively does the same thing as the generic example above, but " +"does not use the generic support added in Python 2.2. It explains how the " +"handler functions are called, so that if you do need to extend their " +"functionality, you'll understand what needs to be done." +msgstr "" + +#: ../../extending/newtypes.rst:331 +msgid "" +"The :c:member:`~PyTypeObject.tp_getattr` handler is called when the object " +"requires an attribute look-up. It is called in the same situations where " +"the :meth:`~object.__getattr__` method of a class would be called." +msgstr "" + +#: ../../extending/newtypes.rst:335 +msgid "Here is an example::" +msgstr "舉例來說： ::" + +#: ../../extending/newtypes.rst:337 +msgid "" +"static PyObject *\n" +"newdatatype_getattr(PyObject *op, char *name)\n" +"{\n" +" newdatatypeobject *self = (newdatatypeobject *) op;\n" +" if (strcmp(name, \"data\") == 0) {\n" +" return PyLong_FromLong(self->data);\n" +" }\n" +"\n" +" PyErr_Format(PyExc_AttributeError,\n" +" \"'%.100s' object has no attribute '%.400s'\",\n" +" Py_TYPE(self)->tp_name, name);\n" +" return NULL;\n" +"}" +msgstr "" + +#: ../../extending/newtypes.rst:351 +msgid "" +"The :c:member:`~PyTypeObject.tp_setattr` handler is called when " +"the :meth:`~object.__setattr__` or :meth:`~object.__delattr__` method of a " +"class instance would be called. When an attribute should be deleted, the " +"third parameter will be ``NULL``. Here is an example that simply raises an " +"exception; if this were really all you wanted, " +"the :c:member:`~PyTypeObject.tp_setattr` handler should be set to " +"``NULL``. ::" +msgstr "" + +#: ../../extending/newtypes.rst:357 +msgid "" +"static int\n" +"newdatatype_setattr(PyObject *op, char *name, PyObject *v)\n" +"{\n" +" PyErr_Format(PyExc_RuntimeError, \"Read-only attribute: %s\", name);\n" +" return -1;\n" +"}" +msgstr "" + +#: ../../extending/newtypes.rst:365 +msgid "Object Comparison" +msgstr "" + +#: ../../extending/newtypes.rst:369 +msgid "richcmpfunc tp_richcompare;" +msgstr "richcmpfunc tp_richcompare;" + +#: ../../extending/newtypes.rst:371 +msgid "" +"The :c:member:`~PyTypeObject.tp_richcompare` handler is called when " +"comparisons are needed. It is analogous to the :ref:`rich comparison " +"methods `, like :meth:`!__lt__`, and also called " +"by :c:func:`PyObject_RichCompare` and :c:func:`PyObject_RichCompareBool`." +msgstr "" + +#: ../../extending/newtypes.rst:376 +msgid "" +"This function is called with two Python objects and the operator as " +"arguments, where the operator is one of ``Py_EQ``, ``Py_NE``, ``Py_LE``, " +"``Py_GE``, ``Py_LT`` or ``Py_GT``. It should compare the two objects with " +"respect to the specified operator and return ``Py_True`` or ``Py_False`` if " +"the comparison is successful, ``Py_NotImplemented`` to indicate that " +"comparison is not implemented and the other object's comparison method " +"should be tried, or ``NULL`` if an exception was set." +msgstr "" + +#: ../../extending/newtypes.rst:384 +msgid "" +"Here is a sample implementation, for a datatype that is considered equal if " +"the size of an internal pointer is equal::" +msgstr "" + +#: ../../extending/newtypes.rst:387 +msgid "" +"static PyObject *\n" +"newdatatype_richcmp(PyObject *lhs, PyObject *rhs, int op)\n" +"{\n" +" newdatatypeobject *obj1 = (newdatatypeobject *) lhs;\n" +" newdatatypeobject *obj2 = (newdatatypeobject *) rhs;\n" +" PyObject *result;\n" +" int c, size1, size2;\n" +"\n" +" /* code to make sure that both arguments are of type\n" +" newdatatype omitted */\n" +"\n" +" size1 = obj1->obj_UnderlyingDatatypePtr->size;\n" +" size2 = obj2->obj_UnderlyingDatatypePtr->size;\n" +"\n" +" switch (op) {\n" +" case Py_LT: c = size1 < size2; break;\n" +" case Py_LE: c = size1 <= size2; break;\n" +" case Py_EQ: c = size1 == size2; break;\n" +" case Py_NE: c = size1 != size2; break;\n" +" case Py_GT: c = size1 > size2; break;\n" +" case Py_GE: c = size1 >= size2; break;\n" +" }\n" +" result = c ? Py_True : Py_False;\n" +" return Py_NewRef(result);\n" +" }" +msgstr "" + +#: ../../extending/newtypes.rst:415 +msgid "Abstract Protocol Support" +msgstr "" + +#: ../../extending/newtypes.rst:417 +msgid "" +"Python supports a variety of *abstract* 'protocols;' the specific interfaces " +"provided to use these interfaces are documented in :ref:`abstract`." +msgstr "" + +#: ../../extending/newtypes.rst:421 +msgid "" +"A number of these abstract interfaces were defined early in the development " +"of the Python implementation. In particular, the number, mapping, and " +"sequence protocols have been part of Python since the beginning. Other " +"protocols have been added over time. For protocols which depend on several " +"handler routines from the type implementation, the older protocols have been " +"defined as optional blocks of handlers referenced by the type object. For " +"newer protocols there are additional slots in the main type object, with a " +"flag bit being set to indicate that the slots are present and should be " +"checked by the interpreter. (The flag bit does not indicate that the slot " +"values are non-``NULL``. The flag may be set to indicate the presence of a " +"slot, but a slot may still be unfilled.) ::" +msgstr "" + +#: ../../extending/newtypes.rst:432 +msgid "" +"PyNumberMethods *tp_as_number;\n" +"PySequenceMethods *tp_as_sequence;\n" +"PyMappingMethods *tp_as_mapping;" +msgstr "" +"PyNumberMethods *tp_as_number;\n" +"PySequenceMethods *tp_as_sequence;\n" +"PyMappingMethods *tp_as_mapping;" + +#: ../../extending/newtypes.rst:436 +msgid "" +"If you wish your object to be able to act like a number, a sequence, or a " +"mapping object, then you place the address of a structure that implements " +"the C type :c:type:`PyNumberMethods`, :c:type:`PySequenceMethods`, " +"or :c:type:`PyMappingMethods`, respectively. It is up to you to fill in this " +"structure with appropriate values. You can find examples of the use of each " +"of these in the :file:`Objects` directory of the Python source " +"distribution. ::" +msgstr "" + +#: ../../extending/newtypes.rst:443 +msgid "hashfunc tp_hash;" +msgstr "hashfunc tp_hash;" + +#: ../../extending/newtypes.rst:445 +msgid "" +"This function, if you choose to provide it, should return a hash number for " +"an instance of your data type. Here is a simple example::" +msgstr "" + +#: ../../extending/newtypes.rst:448 +msgid "" +"static Py_hash_t\n" +"newdatatype_hash(PyObject *op)\n" +"{\n" +" newdatatypeobject *self = (newdatatypeobject *) op;\n" +" Py_hash_t result;\n" +" result = self->some_size + 32767 * self->some_number;\n" +" if (result == -1) {\n" +" result = -2;\n" +" }\n" +" return result;\n" +"}" +msgstr "" +"static Py_hash_t\n" +"newdatatype_hash(PyObject *op)\n" +"{\n" +" newdatatypeobject *self = (newdatatypeobject *) op;\n" +" Py_hash_t result;\n" +" result = self->some_size + 32767 * self->some_number;\n" +" if (result == -1) {\n" +" result = -2;\n" +" }\n" +" return result;\n" +"}" + +#: ../../extending/newtypes.rst:460 +msgid "" +":c:type:`Py_hash_t` is a signed integer type with a platform-varying width. " +"Returning ``-1`` from :c:member:`~PyTypeObject.tp_hash` indicates an error, " +"which is why you should be careful to avoid returning it when hash " +"computation is successful, as seen above." +msgstr "" + +#: ../../extending/newtypes.rst:467 +msgid "ternaryfunc tp_call;" +msgstr "ternaryfunc tp_call;" + +#: ../../extending/newtypes.rst:469 +msgid "" +"This function is called when an instance of your data type is \"called\", " +"for example, if ``obj1`` is an instance of your data type and the Python " +"script contains ``obj1('hello')``, the :c:member:`~PyTypeObject.tp_call` " +"handler is invoked." +msgstr "" + +#: ../../extending/newtypes.rst:473 +msgid "This function takes three arguments:" +msgstr "" + +#: ../../extending/newtypes.rst:475 +msgid "" +"*self* is the instance of the data type which is the subject of the call. If " +"the call is ``obj1('hello')``, then *self* is ``obj1``." +msgstr "" + +#: ../../extending/newtypes.rst:478 +msgid "" +"*args* is a tuple containing the arguments to the call. You can " +"use :c:func:`PyArg_ParseTuple` to extract the arguments." +msgstr "" + +#: ../../extending/newtypes.rst:481 +msgid "" +"*kwds* is a dictionary of keyword arguments that were passed. If this is non-" +"``NULL`` and you support keyword arguments, " +"use :c:func:`PyArg_ParseTupleAndKeywords` to extract the arguments. If you " +"do not want to support keyword arguments and this is non-``NULL``, raise " +"a :exc:`TypeError` with a message saying that keyword arguments are not " +"supported." +msgstr "" + +#: ../../extending/newtypes.rst:487 +msgid "Here is a toy ``tp_call`` implementation::" +msgstr "" + +#: ../../extending/newtypes.rst:489 +msgid "" +"static PyObject *\n" +"newdatatype_call(PyObject *op, PyObject *args, PyObject *kwds)\n" +"{\n" +" newdatatypeobject *self = (newdatatypeobject *) op;\n" +" PyObject *result;\n" +" const char *arg1;\n" +" const char *arg2;\n" +" const char *arg3;\n" +"\n" +" if (!PyArg_ParseTuple(args, \"sss:call\", &arg1, &arg2, &arg3)) {\n" +" return NULL;\n" +" }\n" +" result = PyUnicode_FromFormat(\n" +" \"Returning -- value: [%d] arg1: [%s] arg2: [%s] arg3: [%s]\\n\",\n" +" self->obj_UnderlyingDatatypePtr->size,\n" +" arg1, arg2, arg3);\n" +" return result;\n" +"}" +msgstr "" +"static PyObject *\n" +"newdatatype_call(PyObject *op, PyObject *args, PyObject *kwds)\n" +"{\n" +" newdatatypeobject *self = (newdatatypeobject *) op;\n" +" PyObject *result;\n" +" const char *arg1;\n" +" const char *arg2;\n" +" const char *arg3;\n" +"\n" +" if (!PyArg_ParseTuple(args, \"sss:call\", &arg1, &arg2, &arg3)) {\n" +" return NULL;\n" +" }\n" +" result = PyUnicode_FromFormat(\n" +" \"Returning -- value: [%d] arg1: [%s] arg2: [%s] arg3: [%s]\\n\",\n" +" self->obj_UnderlyingDatatypePtr->size,\n" +" arg1, arg2, arg3);\n" +" return result;\n" +"}" + +#: ../../extending/newtypes.rst:510 +msgid "" +"/* Iterators */\n" +"getiterfunc tp_iter;\n" +"iternextfunc tp_iternext;" +msgstr "" +"/* 疊代器 */\n" +"getiterfunc tp_iter;\n" +"iternextfunc tp_iternext;" + +#: ../../extending/newtypes.rst:514 +msgid "" +"These functions provide support for the iterator protocol. Both handlers " +"take exactly one parameter, the instance for which they are being called, " +"and return a new reference. In the case of an error, they should set an " +"exception and return ``NULL``. :c:member:`~PyTypeObject.tp_iter` " +"corresponds to the Python :meth:`~object.__iter__` method, " +"while :c:member:`~PyTypeObject.tp_iternext` corresponds to the " +"Python :meth:`~iterator.__next__` method." +msgstr "" + +#: ../../extending/newtypes.rst:521 +msgid "" +"Any :term:`iterable` object must implement " +"the :c:member:`~PyTypeObject.tp_iter` handler, which must return " +"an :term:`iterator` object. Here the same guidelines apply as for Python " +"classes:" +msgstr "" + +#: ../../extending/newtypes.rst:525 +msgid "" +"For collections (such as lists and tuples) which can support multiple " +"independent iterators, a new iterator should be created and returned by each " +"call to :c:member:`~PyTypeObject.tp_iter`." +msgstr "" + +#: ../../extending/newtypes.rst:528 +msgid "" +"Objects which can only be iterated over once (usually due to side effects of " +"iteration, such as file objects) can " +"implement :c:member:`~PyTypeObject.tp_iter` by returning a new reference to " +"themselves -- and should also therefore implement " +"the :c:member:`~PyTypeObject.tp_iternext` handler." +msgstr "" + +#: ../../extending/newtypes.rst:533 +msgid "" +"Any :term:`iterator` object should implement " +"both :c:member:`~PyTypeObject.tp_iter` " +"and :c:member:`~PyTypeObject.tp_iternext`. An " +"iterator's :c:member:`~PyTypeObject.tp_iter` handler should return a new " +"reference to the iterator. Its :c:member:`~PyTypeObject.tp_iternext` " +"handler should return a new reference to the next object in the iteration, " +"if there is one. If the iteration has reached the " +"end, :c:member:`~PyTypeObject.tp_iternext` may return ``NULL`` without " +"setting an exception, or it may set :exc:`StopIteration` *in addition* to " +"returning ``NULL``; avoiding the exception can yield slightly better " +"performance. If an actual error " +"occurs, :c:member:`~PyTypeObject.tp_iternext` should always set an exception " +"and return ``NULL``." +msgstr "" + +#: ../../extending/newtypes.rst:549 +msgid "Weak Reference Support" +msgstr "" + +#: ../../extending/newtypes.rst:551 +msgid "" +"One of the goals of Python's weak reference implementation is to allow any " +"type to participate in the weak reference mechanism without incurring the " +"overhead on performance-critical objects (such as numbers)." +msgstr "" + +#: ../../extending/newtypes.rst:556 +msgid "Documentation for the :mod:`weakref` module." +msgstr "" + +#: ../../extending/newtypes.rst:558 +msgid "" +"For an object to be weakly referenceable, the extension type must set the " +"``Py_TPFLAGS_MANAGED_WEAKREF`` bit of the :c:member:`~PyTypeObject.tp_flags` " +"field. The legacy :c:member:`~PyTypeObject.tp_weaklistoffset` field should " +"be left as zero." +msgstr "" + +#: ../../extending/newtypes.rst:563 +msgid "" +"Concretely, here is how the statically declared type object would look::" +msgstr "" + +#: ../../extending/newtypes.rst:565 +msgid "" +"static PyTypeObject TrivialType = {\n" +" PyVarObject_HEAD_INIT(NULL, 0)\n" +" /* ... other members omitted for brevity ... */\n" +" .tp_flags = Py_TPFLAGS_MANAGED_WEAKREF | ...,\n" +"};" +msgstr "" + +#: ../../extending/newtypes.rst:572 +msgid "" +"The only further addition is that ``tp_dealloc`` needs to clear any weak " +"references (by calling :c:func:`PyObject_ClearWeakRefs`)::" +msgstr "" + +#: ../../extending/newtypes.rst:575 +msgid "" +"static void\n" +"Trivial_dealloc(PyObject *op)\n" +"{\n" +" /* Clear weakrefs first before calling any destructors */\n" +" PyObject_ClearWeakRefs(op);\n" +" /* ... remainder of destruction code omitted for brevity ... */\n" +" Py_TYPE(op)->tp_free(op);\n" +"}" +msgstr "" + +#: ../../extending/newtypes.rst:586 +msgid "More Suggestions" +msgstr "" + +#: ../../extending/newtypes.rst:588 +msgid "" +"In order to learn how to implement any specific method for your new data " +"type, get the :term:`CPython` source code. Go to the :file:`Objects` " +"directory, then search the C source files for ``tp_`` plus the function you " +"want (for example, ``tp_richcompare``). You will find examples of the " +"function you want to implement." +msgstr "" + +#: ../../extending/newtypes.rst:594 +msgid "" +"When you need to verify that an object is a concrete instance of the type " +"you are implementing, use the :c:func:`PyObject_TypeCheck` function. A " +"sample of its use might be something like the following::" +msgstr "" + +#: ../../extending/newtypes.rst:598 +msgid "" +"if (!PyObject_TypeCheck(some_object, &MyType)) {\n" +" PyErr_SetString(PyExc_TypeError, \"arg #1 not a mything\");\n" +" return NULL;\n" +"}" +msgstr "" + +#: ../../extending/newtypes.rst:604 +msgid "Download CPython source releases." +msgstr "" + +#: ../../extending/newtypes.rst:605 +msgid "https://www.python.org/downloads/source/" +msgstr "https://www.python.org/downloads/source/" + +#: ../../extending/newtypes.rst:607 +msgid "" +"The CPython project on GitHub, where the CPython source code is developed." +msgstr "" + +#: ../../extending/newtypes.rst:608 +msgid "https://github.com/python/cpython" +msgstr "https://github.com/python/cpython" + +#: ../../extending/newtypes.rst:56 +msgid "object" +msgstr "object（物件）" + +#: ../../extending/newtypes.rst:56 +msgid "deallocation" +msgstr "" + +#: ../../extending/newtypes.rst:56 +msgid "deallocation, object" +msgstr "" + +#: ../../extending/newtypes.rst:56 +msgid "finalization" +msgstr "" + +#: ../../extending/newtypes.rst:56 +msgid "finalization, of objects" +msgstr "" + +#: ../../extending/newtypes.rst:93 +msgid "PyErr_Fetch (C function)" +msgstr "PyErr_Fetch（C 函式）" + +#: ../../extending/newtypes.rst:93 +msgid "PyErr_Restore (C function)" +msgstr "PyErr_Restore（C 函式）" + +#: ../../extending/newtypes.rst:154 +msgid "string" +msgstr "string（字串）" + +#: ../../extending/newtypes.rst:154 +msgid "object representation" +msgstr "object representation（物件表示）" + +#: ../../extending/newtypes.rst:154 +msgid "built-in function" +msgstr "built-in function（內建函式）" + +#: ../../extending/newtypes.rst:154 +msgid "repr" +msgstr "repr" diff --git a/extending/newtypes_tutorial.po b/extending/newtypes_tutorial.po index f9af9cb62f..1e37be4d5e 100644 --- a/extending/newtypes_tutorial.po +++ b/extending/newtypes_tutorial.po @@ -1,2327 +1,2327 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: 2018-07-15 18:56+0800\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" - -#: ../../extending/newtypes_tutorial.rst:7 -msgid "Defining Extension Types: Tutorial" -msgstr "擴充型別定義教學" - -#: ../../extending/newtypes_tutorial.rst:14 -msgid "" -"Python allows the writer of a C extension module to define new types that " -"can be manipulated from Python code, much like the built-in :class:`str` " -"and :class:`list` types. The code for all extension types follows a " -"pattern, but there are some details that you need to understand before you " -"can get started. This document is a gentle introduction to the topic." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:24 -msgid "The Basics" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:26 -msgid "" -"The :term:`CPython` runtime sees all Python objects as variables of " -"type :c:expr:`PyObject*`, which serves as a \"base type\" for all Python " -"objects. The :c:type:`PyObject` structure itself only contains the " -"object's :term:`reference count` and a pointer to the object's \"type " -"object\". This is where the action is; the type object determines which (C) " -"functions get called by the interpreter when, for instance, an attribute " -"gets looked up on an object, a method called, or it is multiplied by another " -"object. These C functions are called \"type methods\"." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:35 -msgid "" -"So, if you want to define a new extension type, you need to create a new " -"type object." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:38 -msgid "" -"This sort of thing can only be explained by example, so here's a minimal, " -"but complete, module that defines a new type named :class:`!Custom` inside a " -"C extension module :mod:`!custom`:" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:43 -msgid "" -"What we're showing here is the traditional way of defining *static* " -"extension types. It should be adequate for most uses. The C API also " -"allows defining heap-allocated extension types using " -"the :c:func:`PyType_FromSpec` function, which isn't covered in this tutorial." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:48 -msgid "" -"#define PY_SSIZE_T_CLEAN\n" -"#include \n" -"\n" -"typedef struct {\n" -" PyObject_HEAD\n" -" /* Type-specific fields go here. */\n" -"} CustomObject;\n" -"\n" -"static PyTypeObject CustomType = {\n" -" .ob_base = PyVarObject_HEAD_INIT(NULL, 0)\n" -" .tp_name = \"custom.Custom\",\n" -" .tp_doc = PyDoc_STR(\"Custom objects\"),\n" -" .tp_basicsize = sizeof(CustomObject),\n" -" .tp_itemsize = 0,\n" -" .tp_flags = Py_TPFLAGS_DEFAULT,\n" -" .tp_new = PyType_GenericNew,\n" -"};\n" -"\n" -"static int\n" -"custom_module_exec(PyObject *m)\n" -"{\n" -" if (PyType_Ready(&CustomType) < 0) {\n" -" return -1;\n" -" }\n" -"\n" -" if (PyModule_AddObjectRef(m, \"Custom\", (PyObject *) &CustomType) < 0) " -"{\n" -" return -1;\n" -" }\n" -"\n" -" return 0;\n" -"}\n" -"\n" -"static PyModuleDef_Slot custom_module_slots[] = {\n" -" {Py_mod_exec, custom_module_exec},\n" -" // Just use this while using static types\n" -" {Py_mod_multiple_interpreters, " -"Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED},\n" -" {0, NULL}\n" -"};\n" -"\n" -"static PyModuleDef custom_module = {\n" -" .m_base = PyModuleDef_HEAD_INIT,\n" -" .m_name = \"custom\",\n" -" .m_doc = \"Example module that creates an extension type.\",\n" -" .m_size = 0,\n" -" .m_slots = custom_module_slots,\n" -"};\n" -"\n" -"PyMODINIT_FUNC\n" -"PyInit_custom(void)\n" -"{\n" -" return PyModuleDef_Init(&custom_module);\n" -"}\n" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:50 -msgid "" -"Now that's quite a bit to take in at once, but hopefully bits will seem " -"familiar from the previous chapter. This file defines three things:" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:53 -msgid "" -"What a :class:`!Custom` **object** contains: this is the ``CustomObject`` " -"struct, which is allocated once for each :class:`!Custom` instance." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:55 -msgid "" -"How the :class:`!Custom` **type** behaves: this is the ``CustomType`` " -"struct, which defines a set of flags and function pointers that the " -"interpreter inspects when specific operations are requested." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:58 -msgid "" -"How to define and execute the :mod:`!custom` module: this is the " -"``PyInit_custom`` function and the associated ``custom_module`` struct for " -"defining the module, and the ``custom_module_exec`` function to set up a " -"fresh module object." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:63 -msgid "The first bit is::" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:65 -msgid "" -"typedef struct {\n" -" PyObject_HEAD\n" -"} CustomObject;" -msgstr "" -"typedef struct {\n" -" PyObject_HEAD\n" -"} CustomObject;" - -#: ../../extending/newtypes_tutorial.rst:69 -msgid "" -"This is what a Custom object will contain. ``PyObject_HEAD`` is mandatory " -"at the start of each object struct and defines a field called ``ob_base`` of " -"type :c:type:`PyObject`, containing a pointer to a type object and a " -"reference count (these can be accessed using the macros :c:macro:`Py_TYPE` " -"and :c:macro:`Py_REFCNT` respectively). The reason for the macro is to " -"abstract away the layout and to enable additional fields in :ref:`debug " -"builds `." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:78 -msgid "" -"There is no semicolon above after the :c:macro:`PyObject_HEAD` macro. Be " -"wary of adding one by accident: some compilers will complain." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:81 -msgid "" -"Of course, objects generally store additional data besides the standard " -"``PyObject_HEAD`` boilerplate; for example, here is the definition for " -"standard Python floats::" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:85 -msgid "" -"typedef struct {\n" -" PyObject_HEAD\n" -" double ob_fval;\n" -"} PyFloatObject;" -msgstr "" -"typedef struct {\n" -" PyObject_HEAD\n" -" double ob_fval;\n" -"} PyFloatObject;" - -#: ../../extending/newtypes_tutorial.rst:90 -msgid "The second bit is the definition of the type object. ::" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:92 -msgid "" -"static PyTypeObject CustomType = {\n" -" .ob_base = PyVarObject_HEAD_INIT(NULL, 0)\n" -" .tp_name = \"custom.Custom\",\n" -" .tp_doc = PyDoc_STR(\"Custom objects\"),\n" -" .tp_basicsize = sizeof(CustomObject),\n" -" .tp_itemsize = 0,\n" -" .tp_flags = Py_TPFLAGS_DEFAULT,\n" -" .tp_new = PyType_GenericNew,\n" -"};" -msgstr "" -"static PyTypeObject CustomType = {\n" -" .ob_base = PyVarObject_HEAD_INIT(NULL, 0)\n" -" .tp_name = \"custom.Custom\",\n" -" .tp_doc = PyDoc_STR(\"Custom objects\"),\n" -" .tp_basicsize = sizeof(CustomObject),\n" -" .tp_itemsize = 0,\n" -" .tp_flags = Py_TPFLAGS_DEFAULT,\n" -" .tp_new = PyType_GenericNew,\n" -"};" - -#: ../../extending/newtypes_tutorial.rst:103 -msgid "" -"We recommend using C99-style designated initializers as above, to avoid " -"listing all the :c:type:`PyTypeObject` fields that you don't care about and " -"also to avoid caring about the fields' declaration order." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:107 -msgid "" -"The actual definition of :c:type:`PyTypeObject` in :file:`object.h` has many " -"more :ref:`fields ` than the definition above. The remaining " -"fields will be filled with zeros by the C compiler, and it's common practice " -"to not specify them explicitly unless you need them." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:112 -msgid "We're going to pick it apart, one field at a time::" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:114 -msgid ".ob_base = PyVarObject_HEAD_INIT(NULL, 0)" -msgstr ".ob_base = PyVarObject_HEAD_INIT(NULL, 0)" - -#: ../../extending/newtypes_tutorial.rst:116 -msgid "" -"This line is mandatory boilerplate to initialize the ``ob_base`` field " -"mentioned above. ::" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:119 -msgid ".tp_name = \"custom.Custom\"," -msgstr ".tp_name = \"custom.Custom\"," - -#: ../../extending/newtypes_tutorial.rst:121 -msgid "" -"The name of our type. This will appear in the default textual " -"representation of our objects and in some error messages, for example:" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:124 -msgid "" -">>> \"\" + custom.Custom()\n" -"Traceback (most recent call last):\n" -" File \"\", line 1, in \n" -"TypeError: can only concatenate str (not \"custom.Custom\") to str" -msgstr "" -">>> \"\" + custom.Custom()\n" -"Traceback (most recent call last):\n" -" File \"\", line 1, in \n" -"TypeError: can only concatenate str (not \"custom.Custom\") to str" - -#: ../../extending/newtypes_tutorial.rst:131 -msgid "" -"Note that the name is a dotted name that includes both the module name and " -"the name of the type within the module. The module in this case is :mod:`!" -"custom` and the type is :class:`!Custom`, so we set the type name " -"to :class:`!custom.Custom`. Using the real dotted import path is important " -"to make your type compatible with the :mod:`pydoc` and :mod:`pickle` " -"modules. ::" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:137 -msgid "" -".tp_basicsize = sizeof(CustomObject),\n" -".tp_itemsize = 0," -msgstr "" -".tp_basicsize = sizeof(CustomObject),\n" -".tp_itemsize = 0," - -#: ../../extending/newtypes_tutorial.rst:140 -msgid "" -"This is so that Python knows how much memory to allocate when creating " -"new :class:`!Custom` instances. :c:member:`~PyTypeObject.tp_itemsize` is " -"only used for variable-sized objects and should otherwise be zero." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:146 -msgid "" -"If you want your type to be subclassable from Python, and your type has the " -"same :c:member:`~PyTypeObject.tp_basicsize` as its base type, you may have " -"problems with multiple inheritance. A Python subclass of your type will " -"have to list your type first in its :attr:`~type.__bases__`, or else it will " -"not be able to call your type's :meth:`~object.__new__` method without " -"getting an error. You can avoid this problem by ensuring that your type has " -"a larger value for :c:member:`~PyTypeObject.tp_basicsize` than its base type " -"does. Most of the time, this will be true anyway, because either your base " -"type will be :class:`object`, or else you will be adding data members to " -"your base type, and therefore increasing its size." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:156 -msgid "We set the class flags to :c:macro:`Py_TPFLAGS_DEFAULT`. ::" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:158 -msgid ".tp_flags = Py_TPFLAGS_DEFAULT," -msgstr ".tp_flags = Py_TPFLAGS_DEFAULT," - -#: ../../extending/newtypes_tutorial.rst:160 -msgid "" -"All types should include this constant in their flags. It enables all of " -"the members defined until at least Python 3.3. If you need further members, " -"you will need to OR the corresponding flags." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:164 -msgid "" -"We provide a doc string for the type in :c:member:`~PyTypeObject.tp_doc`. ::" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:166 -msgid ".tp_doc = PyDoc_STR(\"Custom objects\")," -msgstr ".tp_doc = PyDoc_STR(\"Custom objects\")," - -#: ../../extending/newtypes_tutorial.rst:168 -msgid "" -"To enable object creation, we have to provide " -"a :c:member:`~PyTypeObject.tp_new` handler. This is the equivalent of the " -"Python method :meth:`~object.__new__`, but has to be specified explicitly. " -"In this case, we can just use the default implementation provided by the API " -"function :c:func:`PyType_GenericNew`. ::" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:173 -msgid ".tp_new = PyType_GenericNew," -msgstr ".tp_new = PyType_GenericNew," - -#: ../../extending/newtypes_tutorial.rst:175 -msgid "" -"Everything else in the file should be familiar, except for some code " -"in :c:func:`!custom_module_exec`::" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:178 -msgid "" -"if (PyType_Ready(&CustomType) < 0) {\n" -" return -1;\n" -"}" -msgstr "" -"if (PyType_Ready(&CustomType) < 0) {\n" -" return -1;\n" -"}" - -#: ../../extending/newtypes_tutorial.rst:182 -msgid "" -"This initializes the :class:`!Custom` type, filling in a number of members " -"to the appropriate default values, including :c:member:`~PyObject.ob_type` " -"that we initially set to ``NULL``. ::" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:186 -msgid "" -"if (PyModule_AddObjectRef(m, \"Custom\", (PyObject *) &CustomType) < 0) {\n" -" return -1;\n" -"}" -msgstr "" -"if (PyModule_AddObjectRef(m, \"Custom\", (PyObject *) &CustomType) < 0) {\n" -" return -1;\n" -"}" - -#: ../../extending/newtypes_tutorial.rst:190 -msgid "" -"This adds the type to the module dictionary. This allows us to " -"create :class:`!Custom` instances by calling the :class:`!Custom` class:" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:193 -msgid "" -">>> import custom\n" -">>> mycustom = custom.Custom()" -msgstr "" -">>> import custom\n" -">>> mycustom = custom.Custom()" - -#: ../../extending/newtypes_tutorial.rst:198 -msgid "" -"That's it! All that remains is to build it; put the above code in a file " -"called :file:`custom.c`," -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:201 -msgid "" -"[build-system]\n" -"requires = [\"setuptools\"]\n" -"build-backend = \"setuptools.build_meta\"\n" -"\n" -"[project]\n" -"name = \"custom\"\n" -"version = \"1\"\n" -msgstr "" -"[build-system]\n" -"requires = [\"setuptools\"]\n" -"build-backend = \"setuptools.build_meta\"\n" -"\n" -"[project]\n" -"name = \"custom\"\n" -"version = \"1\"\n" - -#: ../../extending/newtypes_tutorial.rst:203 -msgid "in a file called :file:`pyproject.toml`, and" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:205 -msgid "" -"from setuptools import Extension, setup\n" -"setup(ext_modules=[Extension(\"custom\", [\"custom.c\"])])" -msgstr "" -"from setuptools import Extension, setup\n" -"setup(ext_modules=[Extension(\"custom\", [\"custom.c\"])])" - -#: ../../extending/newtypes_tutorial.rst:210 -msgid "in a file called :file:`setup.py`; then typing" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:212 -#: ../../extending/newtypes_tutorial.rst:550 -msgid "$ python -m pip install ." -msgstr "$ python -m pip install ." - -#: ../../extending/newtypes_tutorial.rst:216 -msgid "" -"in a shell should produce a file :file:`custom.so` in a subdirectory and " -"install it; now fire up Python --- you should be able to ``import custom`` " -"and play around with ``Custom`` objects." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:220 -msgid "That wasn't so hard, was it?" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:222 -msgid "" -"Of course, the current Custom type is pretty uninteresting. It has no data " -"and doesn't do anything. It can't even be subclassed." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:227 -msgid "Adding data and methods to the Basic example" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:229 -msgid "" -"Let's extend the basic example to add some data and methods. Let's also " -"make the type usable as a base class. We'll create a new module, :mod:`!" -"custom2` that adds these capabilities:" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:233 -msgid "" -"#define PY_SSIZE_T_CLEAN\n" -"#include \n" -"#include /* for offsetof() */\n" -"\n" -"typedef struct {\n" -" PyObject_HEAD\n" -" PyObject *first; /* first name */\n" -" PyObject *last; /* last name */\n" -" int number;\n" -"} CustomObject;\n" -"\n" -"static void\n" -"Custom_dealloc(PyObject *op)\n" -"{\n" -" CustomObject *self = (CustomObject *) op;\n" -" Py_XDECREF(self->first);\n" -" Py_XDECREF(self->last);\n" -" Py_TYPE(self)->tp_free(self);\n" -"}\n" -"\n" -"static PyObject *\n" -"Custom_new(PyTypeObject *type, PyObject *args, PyObject *kwds)\n" -"{\n" -" CustomObject *self;\n" -" self = (CustomObject *) type->tp_alloc(type, 0);\n" -" if (self != NULL) {\n" -" self->first = Py_GetConstant(Py_CONSTANT_EMPTY_STR);\n" -" if (self->first == NULL) {\n" -" Py_DECREF(self);\n" -" return NULL;\n" -" }\n" -" self->last = Py_GetConstant(Py_CONSTANT_EMPTY_STR);\n" -" if (self->last == NULL) {\n" -" Py_DECREF(self);\n" -" return NULL;\n" -" }\n" -" self->number = 0;\n" -" }\n" -" return (PyObject *) self;\n" -"}\n" -"\n" -"static int\n" -"Custom_init(PyObject *op, PyObject *args, PyObject *kwds)\n" -"{\n" -" CustomObject *self = (CustomObject *) op;\n" -" static char *kwlist[] = {\"first\", \"last\", \"number\", NULL};\n" -" PyObject *first = NULL, *last = NULL;\n" -"\n" -" if (!PyArg_ParseTupleAndKeywords(args, kwds, \"|OOi\", kwlist,\n" -" &first, &last,\n" -" &self->number))\n" -" return -1;\n" -"\n" -" if (first) {\n" -" Py_XSETREF(self->first, Py_NewRef(first));\n" -" }\n" -" if (last) {\n" -" Py_XSETREF(self->last, Py_NewRef(last));\n" -" }\n" -" return 0;\n" -"}\n" -"\n" -"static PyMemberDef Custom_members[] = {\n" -" {\"first\", Py_T_OBJECT_EX, offsetof(CustomObject, first), 0,\n" -" \"first name\"},\n" -" {\"last\", Py_T_OBJECT_EX, offsetof(CustomObject, last), 0,\n" -" \"last name\"},\n" -" {\"number\", Py_T_INT, offsetof(CustomObject, number), 0,\n" -" \"custom number\"},\n" -" {NULL} /* Sentinel */\n" -"};\n" -"\n" -"static PyObject *\n" -"Custom_name(PyObject *op, PyObject *Py_UNUSED(dummy))\n" -"{\n" -" CustomObject *self = (CustomObject *) op;\n" -" if (self->first == NULL) {\n" -" PyErr_SetString(PyExc_AttributeError, \"first\");\n" -" return NULL;\n" -" }\n" -" if (self->last == NULL) {\n" -" PyErr_SetString(PyExc_AttributeError, \"last\");\n" -" return NULL;\n" -" }\n" -" return PyUnicode_FromFormat(\"%S %S\", self->first, self->last);\n" -"}\n" -"\n" -"static PyMethodDef Custom_methods[] = {\n" -" {\"name\", Custom_name, METH_NOARGS,\n" -" \"Return the name, combining the first and last name\"\n" -" },\n" -" {NULL} /* Sentinel */\n" -"};\n" -"\n" -"static PyTypeObject CustomType = {\n" -" .ob_base = PyVarObject_HEAD_INIT(NULL, 0)\n" -" .tp_name = \"custom2.Custom\",\n" -" .tp_doc = PyDoc_STR(\"Custom objects\"),\n" -" .tp_basicsize = sizeof(CustomObject),\n" -" .tp_itemsize = 0,\n" -" .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE,\n" -" .tp_new = Custom_new,\n" -" .tp_init = Custom_init,\n" -" .tp_dealloc = Custom_dealloc,\n" -" .tp_members = Custom_members,\n" -" .tp_methods = Custom_methods,\n" -"};\n" -"\n" -"static int\n" -"custom_module_exec(PyObject *m)\n" -"{\n" -" if (PyType_Ready(&CustomType) < 0) {\n" -" return -1;\n" -" }\n" -"\n" -" if (PyModule_AddObjectRef(m, \"Custom\", (PyObject *) &CustomType) < 0) " -"{\n" -" return -1;\n" -" }\n" -"\n" -" return 0;\n" -"}\n" -"\n" -"static PyModuleDef_Slot custom_module_slots[] = {\n" -" {Py_mod_exec, custom_module_exec},\n" -" {Py_mod_multiple_interpreters, " -"Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED},\n" -" {0, NULL}\n" -"};\n" -"\n" -"static PyModuleDef custom_module = {\n" -" .m_base = PyModuleDef_HEAD_INIT,\n" -" .m_name = \"custom2\",\n" -" .m_doc = \"Example module that creates an extension type.\",\n" -" .m_size = 0,\n" -" .m_slots = custom_module_slots,\n" -"};\n" -"\n" -"PyMODINIT_FUNC\n" -"PyInit_custom2(void)\n" -"{\n" -" return PyModuleDef_Init(&custom_module);\n" -"}\n" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:236 -msgid "This version of the module has a number of changes." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:238 -msgid "" -"The :class:`!Custom` type now has three data attributes in its C struct, " -"*first*, *last*, and *number*. The *first* and *last* variables are Python " -"strings containing first and last names. The *number* attribute is a C " -"integer." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:242 -msgid "The object structure is updated accordingly::" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:244 -msgid "" -"typedef struct {\n" -" PyObject_HEAD\n" -" PyObject *first; /* first name */\n" -" PyObject *last; /* last name */\n" -" int number;\n" -"} CustomObject;" -msgstr "" -"typedef struct {\n" -" PyObject_HEAD\n" -" PyObject *first; /* first name */\n" -" PyObject *last; /* last name */\n" -" int number;\n" -"} CustomObject;" - -#: ../../extending/newtypes_tutorial.rst:251 -msgid "" -"Because we now have data to manage, we have to be more careful about object " -"allocation and deallocation. At a minimum, we need a deallocation method::" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:254 -msgid "" -"static void\n" -"Custom_dealloc(PyObject *op)\n" -"{\n" -" CustomObject *self = (CustomObject *) op;\n" -" Py_XDECREF(self->first);\n" -" Py_XDECREF(self->last);\n" -" Py_TYPE(self)->tp_free(self);\n" -"}" -msgstr "" -"static void\n" -"Custom_dealloc(PyObject *op)\n" -"{\n" -" CustomObject *self = (CustomObject *) op;\n" -" Py_XDECREF(self->first);\n" -" Py_XDECREF(self->last);\n" -" Py_TYPE(self)->tp_free(self);\n" -"}" - -#: ../../extending/newtypes_tutorial.rst:263 -msgid "which is assigned to the :c:member:`~PyTypeObject.tp_dealloc` member::" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:265 -msgid ".tp_dealloc = Custom_dealloc," -msgstr ".tp_dealloc = Custom_dealloc," - -#: ../../extending/newtypes_tutorial.rst:267 -msgid "" -"This method first clears the reference counts of the two Python " -"attributes. :c:func:`Py_XDECREF` correctly handles the case where its " -"argument is ``NULL`` (which might happen here if ``tp_new`` failed midway). " -"It then calls the :c:member:`~PyTypeObject.tp_free` member of the object's " -"type (computed by ``Py_TYPE(self)``) to free the object's memory. Note that " -"the object's type might not be :class:`!CustomType`, because the object may " -"be an instance of a subclass." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:277 -msgid "" -"The explicit cast to ``CustomObject *`` above is needed because we defined " -"``Custom_dealloc`` to take a ``PyObject *`` argument, as the ``tp_dealloc`` " -"function pointer expects to receive a ``PyObject *`` argument. By assigning " -"to the ``tp_dealloc`` slot of a type, we declare that it can only be called " -"with instances of our ``CustomObject`` class, so the cast to ``(CustomObject " -"*)`` is safe. This is object-oriented polymorphism, in C!" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:285 -msgid "" -"In existing code, or in previous versions of this tutorial, you might see " -"similar functions take a pointer to the subtype object structure " -"(``CustomObject*``) directly, like this::" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:289 -msgid "" -"Custom_dealloc(CustomObject *self)\n" -"{\n" -" Py_XDECREF(self->first);\n" -" Py_XDECREF(self->last);\n" -" Py_TYPE(self)->tp_free((PyObject *) self);\n" -"}\n" -"...\n" -".tp_dealloc = (destructor) Custom_dealloc," -msgstr "" -"Custom_dealloc(CustomObject *self)\n" -"{\n" -" Py_XDECREF(self->first);\n" -" Py_XDECREF(self->last);\n" -" Py_TYPE(self)->tp_free((PyObject *) self);\n" -"}\n" -"...\n" -".tp_dealloc = (destructor) Custom_dealloc," - -#: ../../extending/newtypes_tutorial.rst:298 -msgid "" -"This does the same thing on all architectures that CPython supports, but " -"according to the C standard, it invokes undefined behavior." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:302 -msgid "" -"We want to make sure that the first and last names are initialized to empty " -"strings, so we provide a ``tp_new`` implementation::" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:305 -msgid "" -"static PyObject *\n" -"Custom_new(PyTypeObject *type, PyObject *args, PyObject *kwds)\n" -"{\n" -" CustomObject *self;\n" -" self = (CustomObject *) type->tp_alloc(type, 0);\n" -" if (self != NULL) {\n" -" self->first = PyUnicode_FromString(\"\");\n" -" if (self->first == NULL) {\n" -" Py_DECREF(self);\n" -" return NULL;\n" -" }\n" -" self->last = PyUnicode_FromString(\"\");\n" -" if (self->last == NULL) {\n" -" Py_DECREF(self);\n" -" return NULL;\n" -" }\n" -" self->number = 0;\n" -" }\n" -" return (PyObject *) self;\n" -"}" -msgstr "" -"static PyObject *\n" -"Custom_new(PyTypeObject *type, PyObject *args, PyObject *kwds)\n" -"{\n" -" CustomObject *self;\n" -" self = (CustomObject *) type->tp_alloc(type, 0);\n" -" if (self != NULL) {\n" -" self->first = PyUnicode_FromString(\"\");\n" -" if (self->first == NULL) {\n" -" Py_DECREF(self);\n" -" return NULL;\n" -" }\n" -" self->last = PyUnicode_FromString(\"\");\n" -" if (self->last == NULL) {\n" -" Py_DECREF(self);\n" -" return NULL;\n" -" }\n" -" self->number = 0;\n" -" }\n" -" return (PyObject *) self;\n" -"}" - -#: ../../extending/newtypes_tutorial.rst:326 -msgid "and install it in the :c:member:`~PyTypeObject.tp_new` member::" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:328 -msgid ".tp_new = Custom_new," -msgstr ".tp_new = Custom_new," - -#: ../../extending/newtypes_tutorial.rst:330 -msgid "" -"The ``tp_new`` handler is responsible for creating (as opposed to " -"initializing) objects of the type. It is exposed in Python as " -"the :meth:`~object.__new__` method. It is not required to define a " -"``tp_new`` member, and indeed many extension types will simply " -"reuse :c:func:`PyType_GenericNew` as done in the first version of " -"the :class:`!Custom` type above. In this case, we use the ``tp_new`` " -"handler to initialize the ``first`` and ``last`` attributes to non-``NULL`` " -"default values." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:338 -msgid "" -"``tp_new`` is passed the type being instantiated (not necessarily " -"``CustomType``, if a subclass is instantiated) and any arguments passed when " -"the type was called, and is expected to return the instance created. " -"``tp_new`` handlers always accept positional and keyword arguments, but they " -"often ignore the arguments, leaving the argument handling to initializer " -"(a.k.a. ``tp_init`` in C or ``__init__`` in Python) methods." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:346 -msgid "" -"``tp_new`` shouldn't call ``tp_init`` explicitly, as the interpreter will do " -"it itself." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:349 -msgid "" -"The ``tp_new`` implementation calls the :c:member:`~PyTypeObject.tp_alloc` " -"slot to allocate memory::" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:352 -msgid "self = (CustomObject *) type->tp_alloc(type, 0);" -msgstr "self = (CustomObject *) type->tp_alloc(type, 0);" - -#: ../../extending/newtypes_tutorial.rst:354 -msgid "" -"Since memory allocation may fail, we must check " -"the :c:member:`~PyTypeObject.tp_alloc` result against ``NULL`` before " -"proceeding." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:358 -msgid "" -"We didn't fill the :c:member:`~PyTypeObject.tp_alloc` slot ourselves. " -"Rather :c:func:`PyType_Ready` fills it for us by inheriting it from our base " -"class, which is :class:`object` by default. Most types use the default " -"allocation strategy." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:364 -msgid "" -"If you are creating a co-operative :c:member:`~PyTypeObject.tp_new` (one " -"that calls a base type's :c:member:`~PyTypeObject.tp_new` " -"or :meth:`~object.__new__`), you must *not* try to determine what method to " -"call using method resolution order at runtime. Always statically determine " -"what type you are going to call, and call " -"its :c:member:`~PyTypeObject.tp_new` directly, or via ``type->tp_base-" -">tp_new``. If you do not do this, Python subclasses of your type that also " -"inherit from other Python-defined classes may not work correctly. " -"(Specifically, you may not be able to create instances of such subclasses " -"without getting a :exc:`TypeError`.)" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:374 -msgid "" -"We also define an initialization function which accepts arguments to provide " -"initial values for our instance::" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:377 -msgid "" -"static int\n" -"Custom_init(PyObject *op, PyObject *args, PyObject *kwds)\n" -"{\n" -" CustomObject *self = (CustomObject *) op;\n" -" static char *kwlist[] = {\"first\", \"last\", \"number\", NULL};\n" -" PyObject *first = NULL, *last = NULL, *tmp;\n" -"\n" -" if (!PyArg_ParseTupleAndKeywords(args, kwds, \"|OOi\", kwlist,\n" -" &first, &last,\n" -" &self->number))\n" -" return -1;\n" -"\n" -" if (first) {\n" -" tmp = self->first;\n" -" Py_INCREF(first);\n" -" self->first = first;\n" -" Py_XDECREF(tmp);\n" -" }\n" -" if (last) {\n" -" tmp = self->last;\n" -" Py_INCREF(last);\n" -" self->last = last;\n" -" Py_XDECREF(tmp);\n" -" }\n" -" return 0;\n" -"}" -msgstr "" -"static int\n" -"Custom_init(PyObject *op, PyObject *args, PyObject *kwds)\n" -"{\n" -" CustomObject *self = (CustomObject *) op;\n" -" static char *kwlist[] = {\"first\", \"last\", \"number\", NULL};\n" -" PyObject *first = NULL, *last = NULL, *tmp;\n" -"\n" -" if (!PyArg_ParseTupleAndKeywords(args, kwds, \"|OOi\", kwlist,\n" -" &first, &last,\n" -" &self->number))\n" -" return -1;\n" -"\n" -" if (first) {\n" -" tmp = self->first;\n" -" Py_INCREF(first);\n" -" self->first = first;\n" -" Py_XDECREF(tmp);\n" -" }\n" -" if (last) {\n" -" tmp = self->last;\n" -" Py_INCREF(last);\n" -" self->last = last;\n" -" Py_XDECREF(tmp);\n" -" }\n" -" return 0;\n" -"}" - -#: ../../extending/newtypes_tutorial.rst:404 -msgid "by filling the :c:member:`~PyTypeObject.tp_init` slot. ::" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:406 -msgid ".tp_init = Custom_init," -msgstr ".tp_init = Custom_init," - -#: ../../extending/newtypes_tutorial.rst:408 -msgid "" -"The :c:member:`~PyTypeObject.tp_init` slot is exposed in Python as " -"the :meth:`~object.__init__` method. It is used to initialize an object " -"after it's created. Initializers always accept positional and keyword " -"arguments, and they should return either ``0`` on success or ``-1`` on error." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:413 -msgid "" -"Unlike the ``tp_new`` handler, there is no guarantee that ``tp_init`` is " -"called at all (for example, the :mod:`pickle` module by default doesn't " -"call :meth:`~object.__init__` on unpickled instances). It can also be " -"called multiple times. Anyone can call the :meth:`!__init__` method on our " -"objects. For this reason, we have to be extra careful when assigning the " -"new attribute values. We might be tempted, for example to assign the " -"``first`` member like this::" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:421 -msgid "" -"if (first) {\n" -" Py_XDECREF(self->first);\n" -" Py_INCREF(first);\n" -" self->first = first;\n" -"}" -msgstr "" -"if (first) {\n" -" Py_XDECREF(self->first);\n" -" Py_INCREF(first);\n" -" self->first = first;\n" -"}" - -#: ../../extending/newtypes_tutorial.rst:427 -msgid "" -"But this would be risky. Our type doesn't restrict the type of the " -"``first`` member, so it could be any kind of object. It could have a " -"destructor that causes code to be executed that tries to access the " -"``first`` member; or that destructor could detach the :term:`thread state " -"` and let arbitrary code run in other threads that " -"accesses and modifies our object." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:434 -msgid "" -"To be paranoid and protect ourselves against this possibility, we almost " -"always reassign members before decrementing their reference counts. When " -"don't we have to do this?" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:438 -msgid "when we absolutely know that the reference count is greater than 1;" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:440 -msgid "" -"when we know that deallocation of the object [#]_ will neither detach " -"the :term:`thread state ` nor cause any calls back " -"into our type's code;" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:443 -msgid "" -"when decrementing a reference count in " -"a :c:member:`~PyTypeObject.tp_dealloc` handler on a type which doesn't " -"support cyclic garbage collection [#]_." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:446 -msgid "" -"We want to expose our instance variables as attributes. There are a number " -"of ways to do that. The simplest way is to define member definitions::" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:449 -msgid "" -"static PyMemberDef Custom_members[] = {\n" -" {\"first\", Py_T_OBJECT_EX, offsetof(CustomObject, first), 0,\n" -" \"first name\"},\n" -" {\"last\", Py_T_OBJECT_EX, offsetof(CustomObject, last), 0,\n" -" \"last name\"},\n" -" {\"number\", Py_T_INT, offsetof(CustomObject, number), 0,\n" -" \"custom number\"},\n" -" {NULL} /* Sentinel */\n" -"};" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:459 -msgid "" -"and put the definitions in the :c:member:`~PyTypeObject.tp_members` slot::" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:461 -msgid ".tp_members = Custom_members," -msgstr ".tp_members = Custom_members," - -#: ../../extending/newtypes_tutorial.rst:463 -msgid "" -"Each member definition has a member name, type, offset, access flags and " -"documentation string. See the :ref:`Generic-Attribute-Management` section " -"below for details." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:467 -msgid "" -"A disadvantage of this approach is that it doesn't provide a way to restrict " -"the types of objects that can be assigned to the Python attributes. We " -"expect the first and last names to be strings, but any Python objects can be " -"assigned. Further, the attributes can be deleted, setting the C pointers to " -"``NULL``. Even though we can make sure the members are initialized to non-" -"``NULL`` values, the members can be set to ``NULL`` if the attributes are " -"deleted." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:474 -msgid "" -"We define a single method, :meth:`!Custom.name`, that outputs the objects " -"name as the concatenation of the first and last names. ::" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:477 -msgid "" -"static PyObject *\n" -"Custom_name(PyObject *op, PyObject *Py_UNUSED(dummy))\n" -"{\n" -" CustomObject *self = (CustomObject *) op;\n" -" if (self->first == NULL) {\n" -" PyErr_SetString(PyExc_AttributeError, \"first\");\n" -" return NULL;\n" -" }\n" -" if (self->last == NULL) {\n" -" PyErr_SetString(PyExc_AttributeError, \"last\");\n" -" return NULL;\n" -" }\n" -" return PyUnicode_FromFormat(\"%S %S\", self->first, self->last);\n" -"}" -msgstr "" -"static PyObject *\n" -"Custom_name(PyObject *op, PyObject *Py_UNUSED(dummy))\n" -"{\n" -" CustomObject *self = (CustomObject *) op;\n" -" if (self->first == NULL) {\n" -" PyErr_SetString(PyExc_AttributeError, \"first\");\n" -" return NULL;\n" -" }\n" -" if (self->last == NULL) {\n" -" PyErr_SetString(PyExc_AttributeError, \"last\");\n" -" return NULL;\n" -" }\n" -" return PyUnicode_FromFormat(\"%S %S\", self->first, self->last);\n" -"}" - -#: ../../extending/newtypes_tutorial.rst:492 -msgid "" -"The method is implemented as a C function that takes a :class:`!Custom` " -"(or :class:`!Custom` subclass) instance as the first argument. Methods " -"always take an instance as the first argument. Methods often take positional " -"and keyword arguments as well, but in this case we don't take any and don't " -"need to accept a positional argument tuple or keyword argument dictionary. " -"This method is equivalent to the Python method:" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:499 -msgid "" -"def name(self):\n" -" return \"%s %s\" % (self.first, self.last)" -msgstr "" -"def name(self):\n" -" return \"%s %s\" % (self.first, self.last)" - -#: ../../extending/newtypes_tutorial.rst:504 -msgid "" -"Note that we have to check for the possibility that our :attr:`!first` " -"and :attr:`!last` members are ``NULL``. This is because they can be " -"deleted, in which case they are set to ``NULL``. It would be better to " -"prevent deletion of these attributes and to restrict the attribute values to " -"be strings. We'll see how to do that in the next section." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:510 -msgid "" -"Now that we've defined the method, we need to create an array of method " -"definitions::" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:513 -msgid "" -"static PyMethodDef Custom_methods[] = {\n" -" {\"name\", Custom_name, METH_NOARGS,\n" -" \"Return the name, combining the first and last name\"\n" -" },\n" -" {NULL} /* Sentinel */\n" -"};" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:520 -msgid "" -"(note that we used the :c:macro:`METH_NOARGS` flag to indicate that the " -"method is expecting no arguments other than *self*)" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:523 -msgid "and assign it to the :c:member:`~PyTypeObject.tp_methods` slot::" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:525 -msgid ".tp_methods = Custom_methods," -msgstr ".tp_methods = Custom_methods," - -#: ../../extending/newtypes_tutorial.rst:527 -msgid "" -"Finally, we'll make our type usable as a base class for subclassing. We've " -"written our methods carefully so far so that they don't make any assumptions " -"about the type of the object being created or used, so all we need to do is " -"to add the :c:macro:`Py_TPFLAGS_BASETYPE` to our class flag definition::" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:532 -msgid ".tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE," -msgstr ".tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE," - -#: ../../extending/newtypes_tutorial.rst:534 -msgid "" -"We rename :c:func:`!PyInit_custom` to :c:func:`!PyInit_custom2`, update the " -"module name in the :c:type:`PyModuleDef` struct, and update the full class " -"name in the :c:type:`PyTypeObject` struct." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:538 -msgid "Finally, we update our :file:`setup.py` file to include the new module," -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:540 -msgid "" -"from setuptools import Extension, setup\n" -"setup(ext_modules=[\n" -" Extension(\"custom\", [\"custom.c\"]),\n" -" Extension(\"custom2\", [\"custom2.c\"]),\n" -"])" -msgstr "" -"from setuptools import Extension, setup\n" -"setup(ext_modules=[\n" -" Extension(\"custom\", [\"custom.c\"]),\n" -" Extension(\"custom2\", [\"custom2.c\"]),\n" -"])" - -#: ../../extending/newtypes_tutorial.rst:548 -msgid "and then we re-install so that we can ``import custom2``:" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:555 -msgid "Providing finer control over data attributes" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:557 -msgid "" -"In this section, we'll provide finer control over how the :attr:`!first` " -"and :attr:`!last` attributes are set in the :class:`!Custom` example. In the " -"previous version of our module, the instance variables :attr:`!first` " -"and :attr:`!last` could be set to non-string values or even deleted. We want " -"to make sure that these attributes always contain strings." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:563 -msgid "" -"#define PY_SSIZE_T_CLEAN\n" -"#include \n" -"#include /* for offsetof() */\n" -"\n" -"typedef struct {\n" -" PyObject_HEAD\n" -" PyObject *first; /* first name */\n" -" PyObject *last; /* last name */\n" -" int number;\n" -"} CustomObject;\n" -"\n" -"static void\n" -"Custom_dealloc(PyObject *op)\n" -"{\n" -" CustomObject *self = (CustomObject *) op;\n" -" Py_XDECREF(self->first);\n" -" Py_XDECREF(self->last);\n" -" Py_TYPE(self)->tp_free(self);\n" -"}\n" -"\n" -"static PyObject *\n" -"Custom_new(PyTypeObject *type, PyObject *args, PyObject *kwds)\n" -"{\n" -" CustomObject *self;\n" -" self = (CustomObject *) type->tp_alloc(type, 0);\n" -" if (self != NULL) {\n" -" self->first = Py_GetConstant(Py_CONSTANT_EMPTY_STR);\n" -" if (self->first == NULL) {\n" -" Py_DECREF(self);\n" -" return NULL;\n" -" }\n" -" self->last = Py_GetConstant(Py_CONSTANT_EMPTY_STR);\n" -" if (self->last == NULL) {\n" -" Py_DECREF(self);\n" -" return NULL;\n" -" }\n" -" self->number = 0;\n" -" }\n" -" return (PyObject *) self;\n" -"}\n" -"\n" -"static int\n" -"Custom_init(PyObject *op, PyObject *args, PyObject *kwds)\n" -"{\n" -" CustomObject *self = (CustomObject *) op;\n" -" static char *kwlist[] = {\"first\", \"last\", \"number\", NULL};\n" -" PyObject *first = NULL, *last = NULL;\n" -"\n" -" if (!PyArg_ParseTupleAndKeywords(args, kwds, \"|UUi\", kwlist,\n" -" &first, &last,\n" -" &self->number))\n" -" return -1;\n" -"\n" -" if (first) {\n" -" Py_SETREF(self->first, Py_NewRef(first));\n" -" }\n" -" if (last) {\n" -" Py_SETREF(self->last, Py_NewRef(last));\n" -" }\n" -" return 0;\n" -"}\n" -"\n" -"static PyMemberDef Custom_members[] = {\n" -" {\"number\", Py_T_INT, offsetof(CustomObject, number), 0,\n" -" \"custom number\"},\n" -" {NULL} /* Sentinel */\n" -"};\n" -"\n" -"static PyObject *\n" -"Custom_getfirst(PyObject *op, void *closure)\n" -"{\n" -" CustomObject *self = (CustomObject *) op;\n" -" return Py_NewRef(self->first);\n" -"}\n" -"\n" -"static int\n" -"Custom_setfirst(PyObject *op, PyObject *value, void *closure)\n" -"{\n" -" CustomObject *self = (CustomObject *) op;\n" -" if (value == NULL) {\n" -" PyErr_SetString(PyExc_TypeError, \"Cannot delete the first " -"attribute\");\n" -" return -1;\n" -" }\n" -" if (!PyUnicode_Check(value)) {\n" -" PyErr_SetString(PyExc_TypeError,\n" -" \"The first attribute value must be a string\");\n" -" return -1;\n" -" }\n" -" Py_SETREF(self->first, Py_NewRef(value));\n" -" return 0;\n" -"}\n" -"\n" -"static PyObject *\n" -"Custom_getlast(PyObject *op, void *closure)\n" -"{\n" -" CustomObject *self = (CustomObject *) op;\n" -" return Py_NewRef(self->last);\n" -"}\n" -"\n" -"static int\n" -"Custom_setlast(PyObject *op, PyObject *value, void *closure)\n" -"{\n" -" CustomObject *self = (CustomObject *) op;\n" -" if (value == NULL) {\n" -" PyErr_SetString(PyExc_TypeError, \"Cannot delete the last " -"attribute\");\n" -" return -1;\n" -" }\n" -" if (!PyUnicode_Check(value)) {\n" -" PyErr_SetString(PyExc_TypeError,\n" -" \"The last attribute value must be a string\");\n" -" return -1;\n" -" }\n" -" Py_SETREF(self->last, Py_NewRef(value));\n" -" return 0;\n" -"}\n" -"\n" -"static PyGetSetDef Custom_getsetters[] = {\n" -" {\"first\", Custom_getfirst, Custom_setfirst,\n" -" \"first name\", NULL},\n" -" {\"last\", Custom_getlast, Custom_setlast,\n" -" \"last name\", NULL},\n" -" {NULL} /* Sentinel */\n" -"};\n" -"\n" -"static PyObject *\n" -"Custom_name(PyObject *op, PyObject *Py_UNUSED(dummy))\n" -"{\n" -" CustomObject *self = (CustomObject *) op;\n" -" return PyUnicode_FromFormat(\"%S %S\", self->first, self->last);\n" -"}\n" -"\n" -"static PyMethodDef Custom_methods[] = {\n" -" {\"name\", Custom_name, METH_NOARGS,\n" -" \"Return the name, combining the first and last name\"\n" -" },\n" -" {NULL} /* Sentinel */\n" -"};\n" -"\n" -"static PyTypeObject CustomType = {\n" -" .ob_base = PyVarObject_HEAD_INIT(NULL, 0)\n" -" .tp_name = \"custom3.Custom\",\n" -" .tp_doc = PyDoc_STR(\"Custom objects\"),\n" -" .tp_basicsize = sizeof(CustomObject),\n" -" .tp_itemsize = 0,\n" -" .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE,\n" -" .tp_new = Custom_new,\n" -" .tp_init = Custom_init,\n" -" .tp_dealloc = Custom_dealloc,\n" -" .tp_members = Custom_members,\n" -" .tp_methods = Custom_methods,\n" -" .tp_getset = Custom_getsetters,\n" -"};\n" -"\n" -"static int\n" -"custom_module_exec(PyObject *m)\n" -"{\n" -" if (PyType_Ready(&CustomType) < 0) {\n" -" return -1;\n" -" }\n" -"\n" -" if (PyModule_AddObjectRef(m, \"Custom\", (PyObject *) &CustomType) < 0) " -"{\n" -" return -1;\n" -" }\n" -"\n" -" return 0;\n" -"}\n" -"\n" -"static PyModuleDef_Slot custom_module_slots[] = {\n" -" {Py_mod_exec, custom_module_exec},\n" -" {Py_mod_multiple_interpreters, " -"Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED},\n" -" {0, NULL}\n" -"};\n" -"\n" -"static PyModuleDef custom_module = {\n" -" .m_base = PyModuleDef_HEAD_INIT,\n" -" .m_name = \"custom3\",\n" -" .m_doc = \"Example module that creates an extension type.\",\n" -" .m_size = 0,\n" -" .m_slots = custom_module_slots,\n" -"};\n" -"\n" -"PyMODINIT_FUNC\n" -"PyInit_custom3(void)\n" -"{\n" -" return PyModuleDef_Init(&custom_module);\n" -"}\n" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:566 -msgid "" -"To provide greater control, over the :attr:`!first` and :attr:`!last` " -"attributes, we'll use custom getter and setter functions. Here are the " -"functions for getting and setting the :attr:`!first` attribute::" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:570 -msgid "" -"static PyObject *\n" -"Custom_getfirst(PyObject *op, void *closure)\n" -"{\n" -" CustomObject *self = (CustomObject *) op;\n" -" Py_INCREF(self->first);\n" -" return self->first;\n" -"}\n" -"\n" -"static int\n" -"Custom_setfirst(PyObject *op, PyObject *value, void *closure)\n" -"{\n" -" CustomObject *self = (CustomObject *) op;\n" -" PyObject *tmp;\n" -" if (value == NULL) {\n" -" PyErr_SetString(PyExc_TypeError, \"Cannot delete the first " -"attribute\");\n" -" return -1;\n" -" }\n" -" if (!PyUnicode_Check(value)) {\n" -" PyErr_SetString(PyExc_TypeError,\n" -" \"The first attribute value must be a string\");\n" -" return -1;\n" -" }\n" -" tmp = self->first;\n" -" Py_INCREF(value);\n" -" self->first = value;\n" -" Py_DECREF(tmp);\n" -" return 0;\n" -"}" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:599 -msgid "" -"The getter function is passed a :class:`!Custom` object and a \"closure\", " -"which is a void pointer. In this case, the closure is ignored. (The " -"closure supports an advanced usage in which definition data is passed to the " -"getter and setter. This could, for example, be used to allow a single set of " -"getter and setter functions that decide the attribute to get or set based on " -"data in the closure.)" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:605 -msgid "" -"The setter function is passed the :class:`!Custom` object, the new value, " -"and the closure. The new value may be ``NULL``, in which case the attribute " -"is being deleted. In our setter, we raise an error if the attribute is " -"deleted or if its new value is not a string." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:610 -msgid "We create an array of :c:type:`PyGetSetDef` structures::" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:612 -msgid "" -"static PyGetSetDef Custom_getsetters[] = {\n" -" {\"first\", Custom_getfirst, Custom_setfirst,\n" -" \"first name\", NULL},\n" -" {\"last\", Custom_getlast, Custom_setlast,\n" -" \"last name\", NULL},\n" -" {NULL} /* Sentinel */\n" -"};" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:620 -msgid "and register it in the :c:member:`~PyTypeObject.tp_getset` slot::" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:622 -msgid ".tp_getset = Custom_getsetters," -msgstr ".tp_getset = Custom_getsetters," - -#: ../../extending/newtypes_tutorial.rst:624 -msgid "" -"The last item in a :c:type:`PyGetSetDef` structure is the \"closure\" " -"mentioned above. In this case, we aren't using a closure, so we just pass " -"``NULL``." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:627 -msgid "We also remove the member definitions for these attributes::" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:629 -msgid "" -"static PyMemberDef Custom_members[] = {\n" -" {\"number\", Py_T_INT, offsetof(CustomObject, number), 0,\n" -" \"custom number\"},\n" -" {NULL} /* Sentinel */\n" -"};" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:635 -msgid "" -"We also need to update the :c:member:`~PyTypeObject.tp_init` handler to only " -"allow strings [#]_ to be passed::" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:638 -msgid "" -"static int\n" -"Custom_init(PyObject *op, PyObject *args, PyObject *kwds)\n" -"{\n" -" CustomObject *self = (CustomObject *) op;\n" -" static char *kwlist[] = {\"first\", \"last\", \"number\", NULL};\n" -" PyObject *first = NULL, *last = NULL, *tmp;\n" -"\n" -" if (!PyArg_ParseTupleAndKeywords(args, kwds, \"|UUi\", kwlist,\n" -" &first, &last,\n" -" &self->number))\n" -" return -1;\n" -"\n" -" if (first) {\n" -" tmp = self->first;\n" -" Py_INCREF(first);\n" -" self->first = first;\n" -" Py_DECREF(tmp);\n" -" }\n" -" if (last) {\n" -" tmp = self->last;\n" -" Py_INCREF(last);\n" -" self->last = last;\n" -" Py_DECREF(tmp);\n" -" }\n" -" return 0;\n" -"}" -msgstr "" -"static int\n" -"Custom_init(PyObject *op, PyObject *args, PyObject *kwds)\n" -"{\n" -" CustomObject *self = (CustomObject *) op;\n" -" static char *kwlist[] = {\"first\", \"last\", \"number\", NULL};\n" -" PyObject *first = NULL, *last = NULL, *tmp;\n" -"\n" -" if (!PyArg_ParseTupleAndKeywords(args, kwds, \"|UUi\", kwlist,\n" -" &first, &last,\n" -" &self->number))\n" -" return -1;\n" -"\n" -" if (first) {\n" -" tmp = self->first;\n" -" Py_INCREF(first);\n" -" self->first = first;\n" -" Py_DECREF(tmp);\n" -" }\n" -" if (last) {\n" -" tmp = self->last;\n" -" Py_INCREF(last);\n" -" self->last = last;\n" -" Py_DECREF(tmp);\n" -" }\n" -" return 0;\n" -"}" - -#: ../../extending/newtypes_tutorial.rst:665 -msgid "" -"With these changes, we can assure that the ``first`` and ``last`` members " -"are never ``NULL`` so we can remove checks for ``NULL`` values in almost all " -"cases. This means that most of the :c:func:`Py_XDECREF` calls can be " -"converted to :c:func:`Py_DECREF` calls. The only place we can't change " -"these calls is in the ``tp_dealloc`` implementation, where there is the " -"possibility that the initialization of these members failed in ``tp_new``." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:672 -msgid "" -"We also rename the module initialization function and module name in the " -"initialization function, as we did before, and we add an extra definition to " -"the :file:`setup.py` file." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:678 -msgid "Supporting cyclic garbage collection" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:680 -msgid "" -"Python has a :term:`cyclic garbage collector (GC) ` that " -"can identify unneeded objects even when their reference counts are not zero. " -"This can happen when objects are involved in cycles. For example, consider:" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:684 -msgid "" -">>> l = []\n" -">>> l.append(l)\n" -">>> del l" -msgstr "" -">>> l = []\n" -">>> l.append(l)\n" -">>> del l" - -#: ../../extending/newtypes_tutorial.rst:690 -msgid "" -"In this example, we create a list that contains itself. When we delete it, " -"it still has a reference from itself. Its reference count doesn't drop to " -"zero. Fortunately, Python's cyclic garbage collector will eventually figure " -"out that the list is garbage and free it." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:695 -msgid "" -"In the second version of the :class:`!Custom` example, we allowed any kind " -"of object to be stored in the :attr:`!first` or :attr:`!last` attributes " -"[#]_. Besides, in the second and third versions, we allowed " -"subclassing :class:`!Custom`, and subclasses may add arbitrary attributes. " -"For any of those two reasons, :class:`!Custom` objects can participate in " -"cycles:" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:701 -msgid "" -">>> import custom3\n" -">>> class Derived(custom3.Custom): pass\n" -"...\n" -">>> n = Derived()\n" -">>> n.some_attribute = n" -msgstr "" -">>> import custom3\n" -">>> class Derived(custom3.Custom): pass\n" -"...\n" -">>> n = Derived()\n" -">>> n.some_attribute = n" - -#: ../../extending/newtypes_tutorial.rst:709 -msgid "" -"To allow a :class:`!Custom` instance participating in a reference cycle to " -"be properly detected and collected by the cyclic GC, our :class:`!Custom` " -"type needs to fill two additional slots and to enable a flag that enables " -"these slots:" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:713 -msgid "" -"#define PY_SSIZE_T_CLEAN\n" -"#include \n" -"#include /* for offsetof() */\n" -"\n" -"typedef struct {\n" -" PyObject_HEAD\n" -" PyObject *first; /* first name */\n" -" PyObject *last; /* last name */\n" -" int number;\n" -"} CustomObject;\n" -"\n" -"static int\n" -"Custom_traverse(PyObject *op, visitproc visit, void *arg)\n" -"{\n" -" CustomObject *self = (CustomObject *) op;\n" -" Py_VISIT(self->first);\n" -" Py_VISIT(self->last);\n" -" return 0;\n" -"}\n" -"\n" -"static int\n" -"Custom_clear(PyObject *op)\n" -"{\n" -" CustomObject *self = (CustomObject *) op;\n" -" Py_CLEAR(self->first);\n" -" Py_CLEAR(self->last);\n" -" return 0;\n" -"}\n" -"\n" -"static void\n" -"Custom_dealloc(PyObject *op)\n" -"{\n" -" PyObject_GC_UnTrack(op);\n" -" (void)Custom_clear(op);\n" -" Py_TYPE(op)->tp_free(op);\n" -"}\n" -"\n" -"static PyObject *\n" -"Custom_new(PyTypeObject *type, PyObject *args, PyObject *kwds)\n" -"{\n" -" CustomObject *self;\n" -" self = (CustomObject *) type->tp_alloc(type, 0);\n" -" if (self != NULL) {\n" -" self->first = Py_GetConstant(Py_CONSTANT_EMPTY_STR);\n" -" if (self->first == NULL) {\n" -" Py_DECREF(self);\n" -" return NULL;\n" -" }\n" -" self->last = Py_GetConstant(Py_CONSTANT_EMPTY_STR);\n" -" if (self->last == NULL) {\n" -" Py_DECREF(self);\n" -" return NULL;\n" -" }\n" -" self->number = 0;\n" -" }\n" -" return (PyObject *) self;\n" -"}\n" -"\n" -"static int\n" -"Custom_init(PyObject *op, PyObject *args, PyObject *kwds)\n" -"{\n" -" CustomObject *self = (CustomObject *) op;\n" -" static char *kwlist[] = {\"first\", \"last\", \"number\", NULL};\n" -" PyObject *first = NULL, *last = NULL;\n" -"\n" -" if (!PyArg_ParseTupleAndKeywords(args, kwds, \"|UUi\", kwlist,\n" -" &first, &last,\n" -" &self->number))\n" -" return -1;\n" -"\n" -" if (first) {\n" -" Py_SETREF(self->first, Py_NewRef(first));\n" -" }\n" -" if (last) {\n" -" Py_SETREF(self->last, Py_NewRef(last));\n" -" }\n" -" return 0;\n" -"}\n" -"\n" -"static PyMemberDef Custom_members[] = {\n" -" {\"number\", Py_T_INT, offsetof(CustomObject, number), 0,\n" -" \"custom number\"},\n" -" {NULL} /* Sentinel */\n" -"};\n" -"\n" -"static PyObject *\n" -"Custom_getfirst(PyObject *op, void *closure)\n" -"{\n" -" CustomObject *self = (CustomObject *) op;\n" -" return Py_NewRef(self->first);\n" -"}\n" -"\n" -"static int\n" -"Custom_setfirst(PyObject *op, PyObject *value, void *closure)\n" -"{\n" -" CustomObject *self = (CustomObject *) op;\n" -" if (value == NULL) {\n" -" PyErr_SetString(PyExc_TypeError, \"Cannot delete the first " -"attribute\");\n" -" return -1;\n" -" }\n" -" if (!PyUnicode_Check(value)) {\n" -" PyErr_SetString(PyExc_TypeError,\n" -" \"The first attribute value must be a string\");\n" -" return -1;\n" -" }\n" -" Py_XSETREF(self->first, Py_NewRef(value));\n" -" return 0;\n" -"}\n" -"\n" -"static PyObject *\n" -"Custom_getlast(PyObject *op, void *closure)\n" -"{\n" -" CustomObject *self = (CustomObject *) op;\n" -" return Py_NewRef(self->last);\n" -"}\n" -"\n" -"static int\n" -"Custom_setlast(PyObject *op, PyObject *value, void *closure)\n" -"{\n" -" CustomObject *self = (CustomObject *) op;\n" -" if (value == NULL) {\n" -" PyErr_SetString(PyExc_TypeError, \"Cannot delete the last " -"attribute\");\n" -" return -1;\n" -" }\n" -" if (!PyUnicode_Check(value)) {\n" -" PyErr_SetString(PyExc_TypeError,\n" -" \"The last attribute value must be a string\");\n" -" return -1;\n" -" }\n" -" Py_XSETREF(self->last, Py_NewRef(value));\n" -" return 0;\n" -"}\n" -"\n" -"static PyGetSetDef Custom_getsetters[] = {\n" -" {\"first\", Custom_getfirst, Custom_setfirst,\n" -" \"first name\", NULL},\n" -" {\"last\", Custom_getlast, Custom_setlast,\n" -" \"last name\", NULL},\n" -" {NULL} /* Sentinel */\n" -"};\n" -"\n" -"static PyObject *\n" -"Custom_name(PyObject *op, PyObject *Py_UNUSED(dummy))\n" -"{\n" -" CustomObject *self = (CustomObject *) op;\n" -" return PyUnicode_FromFormat(\"%S %S\", self->first, self->last);\n" -"}\n" -"\n" -"static PyMethodDef Custom_methods[] = {\n" -" {\"name\", Custom_name, METH_NOARGS,\n" -" \"Return the name, combining the first and last name\"\n" -" },\n" -" {NULL} /* Sentinel */\n" -"};\n" -"\n" -"static PyTypeObject CustomType = {\n" -" .ob_base = PyVarObject_HEAD_INIT(NULL, 0)\n" -" .tp_name = \"custom4.Custom\",\n" -" .tp_doc = PyDoc_STR(\"Custom objects\"),\n" -" .tp_basicsize = sizeof(CustomObject),\n" -" .tp_itemsize = 0,\n" -" .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | " -"Py_TPFLAGS_HAVE_GC,\n" -" .tp_new = Custom_new,\n" -" .tp_init = Custom_init,\n" -" .tp_dealloc = Custom_dealloc,\n" -" .tp_traverse = Custom_traverse,\n" -" .tp_clear = Custom_clear,\n" -" .tp_members = Custom_members,\n" -" .tp_methods = Custom_methods,\n" -" .tp_getset = Custom_getsetters,\n" -"};\n" -"\n" -"static int\n" -"custom_module_exec(PyObject *m)\n" -"{\n" -" if (PyType_Ready(&CustomType) < 0) {\n" -" return -1;\n" -" }\n" -"\n" -" if (PyModule_AddObjectRef(m, \"Custom\", (PyObject *) &CustomType) < 0) " -"{\n" -" return -1;\n" -" }\n" -"\n" -" return 0;\n" -"}\n" -"\n" -"static PyModuleDef_Slot custom_module_slots[] = {\n" -" {Py_mod_exec, custom_module_exec},\n" -" {Py_mod_multiple_interpreters, " -"Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED},\n" -" {0, NULL}\n" -"};\n" -"\n" -"static PyModuleDef custom_module = {\n" -" .m_base = PyModuleDef_HEAD_INIT,\n" -" .m_name = \"custom4\",\n" -" .m_doc = \"Example module that creates an extension type.\",\n" -" .m_size = 0,\n" -" .m_slots = custom_module_slots,\n" -"};\n" -"\n" -"PyMODINIT_FUNC\n" -"PyInit_custom4(void)\n" -"{\n" -" return PyModuleDef_Init(&custom_module);\n" -"}\n" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:716 -msgid "" -"First, the traversal method lets the cyclic GC know about subobjects that " -"could participate in cycles::" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:719 -msgid "" -"static int\n" -"Custom_traverse(PyObject *op, visitproc visit, void *arg)\n" -"{\n" -" CustomObject *self = (CustomObject *) op;\n" -" int vret;\n" -" if (self->first) {\n" -" vret = visit(self->first, arg);\n" -" if (vret != 0)\n" -" return vret;\n" -" }\n" -" if (self->last) {\n" -" vret = visit(self->last, arg);\n" -" if (vret != 0)\n" -" return vret;\n" -" }\n" -" return 0;\n" -"}" -msgstr "" -"static int\n" -"Custom_traverse(PyObject *op, visitproc visit, void *arg)\n" -"{\n" -" CustomObject *self = (CustomObject *) op;\n" -" int vret;\n" -" if (self->first) {\n" -" vret = visit(self->first, arg);\n" -" if (vret != 0)\n" -" return vret;\n" -" }\n" -" if (self->last) {\n" -" vret = visit(self->last, arg);\n" -" if (vret != 0)\n" -" return vret;\n" -" }\n" -" return 0;\n" -"}" - -#: ../../extending/newtypes_tutorial.rst:737 -msgid "" -"For each subobject that can participate in cycles, we need to call " -"the :c:func:`!visit` function, which is passed to the traversal method. " -"The :c:func:`!visit` function takes as arguments the subobject and the extra " -"argument *arg* passed to the traversal method. It returns an integer value " -"that must be returned if it is non-zero." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:743 -msgid "" -"Python provides a :c:func:`Py_VISIT` macro that automates calling visit " -"functions. With :c:func:`Py_VISIT`, we can minimize the amount of " -"boilerplate in ``Custom_traverse``::" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:747 -msgid "" -"static int\n" -"Custom_traverse(PyObject *op, visitproc visit, void *arg)\n" -"{\n" -" CustomObject *self = (CustomObject *) op;\n" -" Py_VISIT(self->first);\n" -" Py_VISIT(self->last);\n" -" return 0;\n" -"}" -msgstr "" -"static int\n" -"Custom_traverse(PyObject *op, visitproc visit, void *arg)\n" -"{\n" -" CustomObject *self = (CustomObject *) op;\n" -" Py_VISIT(self->first);\n" -" Py_VISIT(self->last);\n" -" return 0;\n" -"}" - -#: ../../extending/newtypes_tutorial.rst:757 -msgid "" -"The :c:member:`~PyTypeObject.tp_traverse` implementation must name its " -"arguments exactly *visit* and *arg* in order to use :c:func:`Py_VISIT`." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:760 -msgid "" -"Second, we need to provide a method for clearing any subobjects that can " -"participate in cycles::" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:763 -msgid "" -"static int\n" -"Custom_clear(PyObject *op)\n" -"{\n" -" CustomObject *self = (CustomObject *) op;\n" -" Py_CLEAR(self->first);\n" -" Py_CLEAR(self->last);\n" -" return 0;\n" -"}" -msgstr "" -"static int\n" -"Custom_clear(PyObject *op)\n" -"{\n" -" CustomObject *self = (CustomObject *) op;\n" -" Py_CLEAR(self->first);\n" -" Py_CLEAR(self->last);\n" -" return 0;\n" -"}" - -#: ../../extending/newtypes_tutorial.rst:772 -msgid "" -"Notice the use of the :c:func:`Py_CLEAR` macro. It is the recommended and " -"safe way to clear data attributes of arbitrary types while decrementing " -"their reference counts. If you were to call :c:func:`Py_XDECREF` instead on " -"the attribute before setting it to ``NULL``, there is a possibility that the " -"attribute's destructor would call back into code that reads the attribute " -"again (*especially* if there is a reference cycle)." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:780 -msgid "You could emulate :c:func:`Py_CLEAR` by writing::" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:782 -msgid "" -"PyObject *tmp;\n" -"tmp = self->first;\n" -"self->first = NULL;\n" -"Py_XDECREF(tmp);" -msgstr "" -"PyObject *tmp;\n" -"tmp = self->first;\n" -"self->first = NULL;\n" -"Py_XDECREF(tmp);" - -#: ../../extending/newtypes_tutorial.rst:787 -msgid "" -"Nevertheless, it is much easier and less error-prone to always " -"use :c:func:`Py_CLEAR` when deleting an attribute. Don't try to micro-" -"optimize at the expense of robustness!" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:791 -msgid "" -"The deallocator ``Custom_dealloc`` may call arbitrary code when clearing " -"attributes. It means the circular GC can be triggered inside the function. " -"Since the GC assumes reference count is not zero, we need to untrack the " -"object from the GC by calling :c:func:`PyObject_GC_UnTrack` before clearing " -"members. Here is our reimplemented deallocator " -"using :c:func:`PyObject_GC_UnTrack` and ``Custom_clear``::" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:798 -msgid "" -"static void\n" -"Custom_dealloc(PyObject *op)\n" -"{\n" -" PyObject_GC_UnTrack(op);\n" -" (void)Custom_clear(op);\n" -" Py_TYPE(op)->tp_free(op);\n" -"}" -msgstr "" -"static void\n" -"Custom_dealloc(PyObject *op)\n" -"{\n" -" PyObject_GC_UnTrack(op);\n" -" (void)Custom_clear(op);\n" -" Py_TYPE(op)->tp_free(op);\n" -"}" - -#: ../../extending/newtypes_tutorial.rst:806 -msgid "" -"Finally, we add the :c:macro:`Py_TPFLAGS_HAVE_GC` flag to the class flags::" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:808 -msgid "" -".tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC," -msgstr "" -".tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC," - -#: ../../extending/newtypes_tutorial.rst:810 -msgid "" -"That's pretty much it. If we had written " -"custom :c:member:`~PyTypeObject.tp_alloc` " -"or :c:member:`~PyTypeObject.tp_free` handlers, we'd need to modify them for " -"cyclic garbage collection. Most extensions will use the versions " -"automatically provided." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:816 -msgid "Subclassing other types" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:818 -msgid "" -"It is possible to create new extension types that are derived from existing " -"types. It is easiest to inherit from the built in types, since an extension " -"can easily use the :c:type:`PyTypeObject` it needs. It can be difficult to " -"share these :c:type:`PyTypeObject` structures between extension modules." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:823 -msgid "" -"In this example we will create a :class:`!SubList` type that inherits from " -"the built-in :class:`list` type. The new type will be completely compatible " -"with regular lists, but will have an additional :meth:`!increment` method " -"that increases an internal counter:" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:828 -msgid "" -">>> import sublist\n" -">>> s = sublist.SubList(range(3))\n" -">>> s.extend(s)\n" -">>> print(len(s))\n" -"6\n" -">>> print(s.increment())\n" -"1\n" -">>> print(s.increment())\n" -"2" -msgstr "" -">>> import sublist\n" -">>> s = sublist.SubList(range(3))\n" -">>> s.extend(s)\n" -">>> print(len(s))\n" -"6\n" -">>> print(s.increment())\n" -"1\n" -">>> print(s.increment())\n" -"2" - -#: ../../extending/newtypes_tutorial.rst:840 -msgid "" -"#define PY_SSIZE_T_CLEAN\n" -"#include \n" -"\n" -"typedef struct {\n" -" PyListObject list;\n" -" int state;\n" -"} SubListObject;\n" -"\n" -"static PyObject *\n" -"SubList_increment(PyObject *op, PyObject *Py_UNUSED(dummy))\n" -"{\n" -" SubListObject *self = (SubListObject *) op;\n" -" self->state++;\n" -" return PyLong_FromLong(self->state);\n" -"}\n" -"\n" -"static PyMethodDef SubList_methods[] = {\n" -" {\"increment\", SubList_increment, METH_NOARGS,\n" -" PyDoc_STR(\"increment state counter\")},\n" -" {NULL},\n" -"};\n" -"\n" -"static int\n" -"SubList_init(PyObject *op, PyObject *args, PyObject *kwds)\n" -"{\n" -" SubListObject *self = (SubListObject *) op;\n" -" if (PyList_Type.tp_init(op, args, kwds) < 0)\n" -" return -1;\n" -" self->state = 0;\n" -" return 0;\n" -"}\n" -"\n" -"static PyTypeObject SubListType = {\n" -" .ob_base = PyVarObject_HEAD_INIT(NULL, 0)\n" -" .tp_name = \"sublist.SubList\",\n" -" .tp_doc = PyDoc_STR(\"SubList objects\"),\n" -" .tp_basicsize = sizeof(SubListObject),\n" -" .tp_itemsize = 0,\n" -" .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE,\n" -" .tp_init = SubList_init,\n" -" .tp_methods = SubList_methods,\n" -"};\n" -"\n" -"static int\n" -"sublist_module_exec(PyObject *m)\n" -"{\n" -" SubListType.tp_base = &PyList_Type;\n" -" if (PyType_Ready(&SubListType) < 0) {\n" -" return -1;\n" -" }\n" -"\n" -" if (PyModule_AddObjectRef(m, \"SubList\", (PyObject *) &SubListType) < " -"0) {\n" -" return -1;\n" -" }\n" -"\n" -" return 0;\n" -"}\n" -"\n" -"static PyModuleDef_Slot sublist_module_slots[] = {\n" -" {Py_mod_exec, sublist_module_exec},\n" -" {Py_mod_multiple_interpreters, " -"Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED},\n" -" {0, NULL}\n" -"};\n" -"\n" -"static PyModuleDef sublist_module = {\n" -" .m_base = PyModuleDef_HEAD_INIT,\n" -" .m_name = \"sublist\",\n" -" .m_doc = \"Example module that creates an extension type.\",\n" -" .m_size = 0,\n" -" .m_slots = sublist_module_slots,\n" -"};\n" -"\n" -"PyMODINIT_FUNC\n" -"PyInit_sublist(void)\n" -"{\n" -" return PyModuleDef_Init(&sublist_module);\n" -"}\n" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:843 -msgid "" -"As you can see, the source code closely resembles the :class:`!Custom` " -"examples in previous sections. We will break down the main differences " -"between them. ::" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:846 -msgid "" -"typedef struct {\n" -" PyListObject list;\n" -" int state;\n" -"} SubListObject;" -msgstr "" -"typedef struct {\n" -" PyListObject list;\n" -" int state;\n" -"} SubListObject;" - -#: ../../extending/newtypes_tutorial.rst:851 -msgid "" -"The primary difference for derived type objects is that the base type's " -"object structure must be the first value. The base type will already " -"include the :c:func:`PyObject_HEAD` at the beginning of its structure." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:855 -msgid "" -"When a Python object is a :class:`!SubList` instance, its ``PyObject *`` " -"pointer can be safely cast to both ``PyListObject *`` and ``SubListObject " -"*``::" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:858 -msgid "" -"static int\n" -"SubList_init(PyObject *op, PyObject *args, PyObject *kwds)\n" -"{\n" -" SubListObject *self = (SubListObject *) op;\n" -" if (PyList_Type.tp_init(op, args, kwds) < 0)\n" -" return -1;\n" -" self->state = 0;\n" -" return 0;\n" -"}" -msgstr "" -"static int\n" -"SubList_init(PyObject *op, PyObject *args, PyObject *kwds)\n" -"{\n" -" SubListObject *self = (SubListObject *) op;\n" -" if (PyList_Type.tp_init(op, args, kwds) < 0)\n" -" return -1;\n" -" self->state = 0;\n" -" return 0;\n" -"}" - -#: ../../extending/newtypes_tutorial.rst:868 -msgid "" -"We see above how to call through to the :meth:`~object.__init__` method of " -"the base type." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:871 -msgid "" -"This pattern is important when writing a type with " -"custom :c:member:`~PyTypeObject.tp_new` " -"and :c:member:`~PyTypeObject.tp_dealloc` members. " -"The :c:member:`~PyTypeObject.tp_new` handler should not actually create the " -"memory for the object with its :c:member:`~PyTypeObject.tp_alloc`, but let " -"the base class handle it by calling its own :c:member:`~PyTypeObject.tp_new`." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:877 -msgid "" -"The :c:type:`PyTypeObject` struct supports " -"a :c:member:`~PyTypeObject.tp_base` specifying the type's concrete base " -"class. Due to cross-platform compiler issues, you can't fill that field " -"directly with a reference to :c:type:`PyList_Type`; it should be done in " -"the :c:data:`Py_mod_exec` function::" -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:883 -msgid "" -"static int\n" -"sublist_module_exec(PyObject *m)\n" -"{\n" -" SubListType.tp_base = &PyList_Type;\n" -" if (PyType_Ready(&SubListType) < 0) {\n" -" return -1;\n" -" }\n" -"\n" -" if (PyModule_AddObjectRef(m, \"SubList\", (PyObject *) &SubListType) < " -"0) {\n" -" return -1;\n" -" }\n" -"\n" -" return 0;\n" -"}" -msgstr "" -"static int\n" -"sublist_module_exec(PyObject *m)\n" -"{\n" -" SubListType.tp_base = &PyList_Type;\n" -" if (PyType_Ready(&SubListType) < 0) {\n" -" return -1;\n" -" }\n" -"\n" -" if (PyModule_AddObjectRef(m, \"SubList\", (PyObject *) &SubListType) < " -"0) {\n" -" return -1;\n" -" }\n" -"\n" -" return 0;\n" -"}" - -#: ../../extending/newtypes_tutorial.rst:898 -msgid "" -"Before calling :c:func:`PyType_Ready`, the type structure must have " -"the :c:member:`~PyTypeObject.tp_base` slot filled in. When we are deriving " -"an existing type, it is not necessary to fill out " -"the :c:member:`~PyTypeObject.tp_alloc` slot with :c:func:`PyType_GenericNew` " -"-- the allocation function from the base type will be inherited." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:904 -msgid "" -"After that, calling :c:func:`PyType_Ready` and adding the type object to the " -"module is the same as with the basic :class:`!Custom` examples." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:909 -msgid "Footnotes" -msgstr "註腳" - -#: ../../extending/newtypes_tutorial.rst:910 -msgid "" -"This is true when we know that the object is a basic type, like a string or " -"a float." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:913 -msgid "" -"We relied on this in the :c:member:`~PyTypeObject.tp_dealloc` handler in " -"this example, because our type doesn't support garbage collection." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:916 -msgid "" -"We now know that the first and last members are strings, so perhaps we could " -"be less careful about decrementing their reference counts, however, we " -"accept instances of string subclasses. Even though deallocating normal " -"strings won't call back into our objects, we can't guarantee that " -"deallocating an instance of a string subclass won't call back into our " -"objects." -msgstr "" - -#: ../../extending/newtypes_tutorial.rst:922 -msgid "" -"Also, even with our attributes restricted to strings instances, the user " -"could pass arbitrary :class:`str` subclasses and therefore still create " -"reference cycles." -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: 2018-07-15 18:56+0800\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" + +#: ../../extending/newtypes_tutorial.rst:7 +msgid "Defining Extension Types: Tutorial" +msgstr "擴充型別定義教學" + +#: ../../extending/newtypes_tutorial.rst:14 +msgid "" +"Python allows the writer of a C extension module to define new types that " +"can be manipulated from Python code, much like the built-in :class:`str` " +"and :class:`list` types. The code for all extension types follows a " +"pattern, but there are some details that you need to understand before you " +"can get started. This document is a gentle introduction to the topic." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:24 +msgid "The Basics" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:26 +msgid "" +"The :term:`CPython` runtime sees all Python objects as variables of " +"type :c:expr:`PyObject*`, which serves as a \"base type\" for all Python " +"objects. The :c:type:`PyObject` structure itself only contains the " +"object's :term:`reference count` and a pointer to the object's \"type " +"object\". This is where the action is; the type object determines which (C) " +"functions get called by the interpreter when, for instance, an attribute " +"gets looked up on an object, a method called, or it is multiplied by another " +"object. These C functions are called \"type methods\"." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:35 +msgid "" +"So, if you want to define a new extension type, you need to create a new " +"type object." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:38 +msgid "" +"This sort of thing can only be explained by example, so here's a minimal, " +"but complete, module that defines a new type named :class:`!Custom` inside a " +"C extension module :mod:`!custom`:" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:43 +msgid "" +"What we're showing here is the traditional way of defining *static* " +"extension types. It should be adequate for most uses. The C API also " +"allows defining heap-allocated extension types using " +"the :c:func:`PyType_FromSpec` function, which isn't covered in this tutorial." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:48 +msgid "" +"#define PY_SSIZE_T_CLEAN\n" +"#include \n" +"\n" +"typedef struct {\n" +" PyObject_HEAD\n" +" /* Type-specific fields go here. */\n" +"} CustomObject;\n" +"\n" +"static PyTypeObject CustomType = {\n" +" .ob_base = PyVarObject_HEAD_INIT(NULL, 0)\n" +" .tp_name = \"custom.Custom\",\n" +" .tp_doc = PyDoc_STR(\"Custom objects\"),\n" +" .tp_basicsize = sizeof(CustomObject),\n" +" .tp_itemsize = 0,\n" +" .tp_flags = Py_TPFLAGS_DEFAULT,\n" +" .tp_new = PyType_GenericNew,\n" +"};\n" +"\n" +"static int\n" +"custom_module_exec(PyObject *m)\n" +"{\n" +" if (PyType_Ready(&CustomType) < 0) {\n" +" return -1;\n" +" }\n" +"\n" +" if (PyModule_AddObjectRef(m, \"Custom\", (PyObject *) &CustomType) < 0) " +"{\n" +" return -1;\n" +" }\n" +"\n" +" return 0;\n" +"}\n" +"\n" +"static PyModuleDef_Slot custom_module_slots[] = {\n" +" {Py_mod_exec, custom_module_exec},\n" +" // Just use this while using static types\n" +" {Py_mod_multiple_interpreters, " +"Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED},\n" +" {0, NULL}\n" +"};\n" +"\n" +"static PyModuleDef custom_module = {\n" +" .m_base = PyModuleDef_HEAD_INIT,\n" +" .m_name = \"custom\",\n" +" .m_doc = \"Example module that creates an extension type.\",\n" +" .m_size = 0,\n" +" .m_slots = custom_module_slots,\n" +"};\n" +"\n" +"PyMODINIT_FUNC\n" +"PyInit_custom(void)\n" +"{\n" +" return PyModuleDef_Init(&custom_module);\n" +"}\n" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:50 +msgid "" +"Now that's quite a bit to take in at once, but hopefully bits will seem " +"familiar from the previous chapter. This file defines three things:" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:53 +msgid "" +"What a :class:`!Custom` **object** contains: this is the ``CustomObject`` " +"struct, which is allocated once for each :class:`!Custom` instance." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:55 +msgid "" +"How the :class:`!Custom` **type** behaves: this is the ``CustomType`` " +"struct, which defines a set of flags and function pointers that the " +"interpreter inspects when specific operations are requested." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:58 +msgid "" +"How to define and execute the :mod:`!custom` module: this is the " +"``PyInit_custom`` function and the associated ``custom_module`` struct for " +"defining the module, and the ``custom_module_exec`` function to set up a " +"fresh module object." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:63 +msgid "The first bit is::" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:65 +msgid "" +"typedef struct {\n" +" PyObject_HEAD\n" +"} CustomObject;" +msgstr "" +"typedef struct {\n" +" PyObject_HEAD\n" +"} CustomObject;" + +#: ../../extending/newtypes_tutorial.rst:69 +msgid "" +"This is what a Custom object will contain. ``PyObject_HEAD`` is mandatory " +"at the start of each object struct and defines a field called ``ob_base`` of " +"type :c:type:`PyObject`, containing a pointer to a type object and a " +"reference count (these can be accessed using the macros :c:macro:`Py_TYPE` " +"and :c:macro:`Py_REFCNT` respectively). The reason for the macro is to " +"abstract away the layout and to enable additional fields in :ref:`debug " +"builds `." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:78 +msgid "" +"There is no semicolon above after the :c:macro:`PyObject_HEAD` macro. Be " +"wary of adding one by accident: some compilers will complain." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:81 +msgid "" +"Of course, objects generally store additional data besides the standard " +"``PyObject_HEAD`` boilerplate; for example, here is the definition for " +"standard Python floats::" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:85 +msgid "" +"typedef struct {\n" +" PyObject_HEAD\n" +" double ob_fval;\n" +"} PyFloatObject;" +msgstr "" +"typedef struct {\n" +" PyObject_HEAD\n" +" double ob_fval;\n" +"} PyFloatObject;" + +#: ../../extending/newtypes_tutorial.rst:90 +msgid "The second bit is the definition of the type object. ::" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:92 +msgid "" +"static PyTypeObject CustomType = {\n" +" .ob_base = PyVarObject_HEAD_INIT(NULL, 0)\n" +" .tp_name = \"custom.Custom\",\n" +" .tp_doc = PyDoc_STR(\"Custom objects\"),\n" +" .tp_basicsize = sizeof(CustomObject),\n" +" .tp_itemsize = 0,\n" +" .tp_flags = Py_TPFLAGS_DEFAULT,\n" +" .tp_new = PyType_GenericNew,\n" +"};" +msgstr "" +"static PyTypeObject CustomType = {\n" +" .ob_base = PyVarObject_HEAD_INIT(NULL, 0)\n" +" .tp_name = \"custom.Custom\",\n" +" .tp_doc = PyDoc_STR(\"Custom objects\"),\n" +" .tp_basicsize = sizeof(CustomObject),\n" +" .tp_itemsize = 0,\n" +" .tp_flags = Py_TPFLAGS_DEFAULT,\n" +" .tp_new = PyType_GenericNew,\n" +"};" + +#: ../../extending/newtypes_tutorial.rst:103 +msgid "" +"We recommend using C99-style designated initializers as above, to avoid " +"listing all the :c:type:`PyTypeObject` fields that you don't care about and " +"also to avoid caring about the fields' declaration order." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:107 +msgid "" +"The actual definition of :c:type:`PyTypeObject` in :file:`object.h` has many " +"more :ref:`fields ` than the definition above. The remaining " +"fields will be filled with zeros by the C compiler, and it's common practice " +"to not specify them explicitly unless you need them." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:112 +msgid "We're going to pick it apart, one field at a time::" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:114 +msgid ".ob_base = PyVarObject_HEAD_INIT(NULL, 0)" +msgstr ".ob_base = PyVarObject_HEAD_INIT(NULL, 0)" + +#: ../../extending/newtypes_tutorial.rst:116 +msgid "" +"This line is mandatory boilerplate to initialize the ``ob_base`` field " +"mentioned above. ::" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:119 +msgid ".tp_name = \"custom.Custom\"," +msgstr ".tp_name = \"custom.Custom\"," + +#: ../../extending/newtypes_tutorial.rst:121 +msgid "" +"The name of our type. This will appear in the default textual " +"representation of our objects and in some error messages, for example:" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:124 +msgid "" +">>> \"\" + custom.Custom()\n" +"Traceback (most recent call last):\n" +" File \"\", line 1, in \n" +"TypeError: can only concatenate str (not \"custom.Custom\") to str" +msgstr "" +">>> \"\" + custom.Custom()\n" +"Traceback (most recent call last):\n" +" File \"\", line 1, in \n" +"TypeError: can only concatenate str (not \"custom.Custom\") to str" + +#: ../../extending/newtypes_tutorial.rst:131 +msgid "" +"Note that the name is a dotted name that includes both the module name and " +"the name of the type within the module. The module in this case is :mod:`!" +"custom` and the type is :class:`!Custom`, so we set the type name " +"to :class:`!custom.Custom`. Using the real dotted import path is important " +"to make your type compatible with the :mod:`pydoc` and :mod:`pickle` " +"modules. ::" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:137 +msgid "" +".tp_basicsize = sizeof(CustomObject),\n" +".tp_itemsize = 0," +msgstr "" +".tp_basicsize = sizeof(CustomObject),\n" +".tp_itemsize = 0," + +#: ../../extending/newtypes_tutorial.rst:140 +msgid "" +"This is so that Python knows how much memory to allocate when creating " +"new :class:`!Custom` instances. :c:member:`~PyTypeObject.tp_itemsize` is " +"only used for variable-sized objects and should otherwise be zero." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:146 +msgid "" +"If you want your type to be subclassable from Python, and your type has the " +"same :c:member:`~PyTypeObject.tp_basicsize` as its base type, you may have " +"problems with multiple inheritance. A Python subclass of your type will " +"have to list your type first in its :attr:`~type.__bases__`, or else it will " +"not be able to call your type's :meth:`~object.__new__` method without " +"getting an error. You can avoid this problem by ensuring that your type has " +"a larger value for :c:member:`~PyTypeObject.tp_basicsize` than its base type " +"does. Most of the time, this will be true anyway, because either your base " +"type will be :class:`object`, or else you will be adding data members to " +"your base type, and therefore increasing its size." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:156 +msgid "We set the class flags to :c:macro:`Py_TPFLAGS_DEFAULT`. ::" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:158 +msgid ".tp_flags = Py_TPFLAGS_DEFAULT," +msgstr ".tp_flags = Py_TPFLAGS_DEFAULT," + +#: ../../extending/newtypes_tutorial.rst:160 +msgid "" +"All types should include this constant in their flags. It enables all of " +"the members defined until at least Python 3.3. If you need further members, " +"you will need to OR the corresponding flags." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:164 +msgid "" +"We provide a doc string for the type in :c:member:`~PyTypeObject.tp_doc`. ::" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:166 +msgid ".tp_doc = PyDoc_STR(\"Custom objects\")," +msgstr ".tp_doc = PyDoc_STR(\"Custom objects\")," + +#: ../../extending/newtypes_tutorial.rst:168 +msgid "" +"To enable object creation, we have to provide " +"a :c:member:`~PyTypeObject.tp_new` handler. This is the equivalent of the " +"Python method :meth:`~object.__new__`, but has to be specified explicitly. " +"In this case, we can just use the default implementation provided by the API " +"function :c:func:`PyType_GenericNew`. ::" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:173 +msgid ".tp_new = PyType_GenericNew," +msgstr ".tp_new = PyType_GenericNew," + +#: ../../extending/newtypes_tutorial.rst:175 +msgid "" +"Everything else in the file should be familiar, except for some code " +"in :c:func:`!custom_module_exec`::" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:178 +msgid "" +"if (PyType_Ready(&CustomType) < 0) {\n" +" return -1;\n" +"}" +msgstr "" +"if (PyType_Ready(&CustomType) < 0) {\n" +" return -1;\n" +"}" + +#: ../../extending/newtypes_tutorial.rst:182 +msgid "" +"This initializes the :class:`!Custom` type, filling in a number of members " +"to the appropriate default values, including :c:member:`~PyObject.ob_type` " +"that we initially set to ``NULL``. ::" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:186 +msgid "" +"if (PyModule_AddObjectRef(m, \"Custom\", (PyObject *) &CustomType) < 0) {\n" +" return -1;\n" +"}" +msgstr "" +"if (PyModule_AddObjectRef(m, \"Custom\", (PyObject *) &CustomType) < 0) {\n" +" return -1;\n" +"}" + +#: ../../extending/newtypes_tutorial.rst:190 +msgid "" +"This adds the type to the module dictionary. This allows us to " +"create :class:`!Custom` instances by calling the :class:`!Custom` class:" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:193 +msgid "" +">>> import custom\n" +">>> mycustom = custom.Custom()" +msgstr "" +">>> import custom\n" +">>> mycustom = custom.Custom()" + +#: ../../extending/newtypes_tutorial.rst:198 +msgid "" +"That's it! All that remains is to build it; put the above code in a file " +"called :file:`custom.c`," +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:201 +msgid "" +"[build-system]\n" +"requires = [\"setuptools\"]\n" +"build-backend = \"setuptools.build_meta\"\n" +"\n" +"[project]\n" +"name = \"custom\"\n" +"version = \"1\"\n" +msgstr "" +"[build-system]\n" +"requires = [\"setuptools\"]\n" +"build-backend = \"setuptools.build_meta\"\n" +"\n" +"[project]\n" +"name = \"custom\"\n" +"version = \"1\"\n" + +#: ../../extending/newtypes_tutorial.rst:203 +msgid "in a file called :file:`pyproject.toml`, and" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:205 +msgid "" +"from setuptools import Extension, setup\n" +"setup(ext_modules=[Extension(\"custom\", [\"custom.c\"])])" +msgstr "" +"from setuptools import Extension, setup\n" +"setup(ext_modules=[Extension(\"custom\", [\"custom.c\"])])" + +#: ../../extending/newtypes_tutorial.rst:210 +msgid "in a file called :file:`setup.py`; then typing" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:212 +#: ../../extending/newtypes_tutorial.rst:550 +msgid "$ python -m pip install ." +msgstr "$ python -m pip install ." + +#: ../../extending/newtypes_tutorial.rst:216 +msgid "" +"in a shell should produce a file :file:`custom.so` in a subdirectory and " +"install it; now fire up Python --- you should be able to ``import custom`` " +"and play around with ``Custom`` objects." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:220 +msgid "That wasn't so hard, was it?" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:222 +msgid "" +"Of course, the current Custom type is pretty uninteresting. It has no data " +"and doesn't do anything. It can't even be subclassed." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:227 +msgid "Adding data and methods to the Basic example" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:229 +msgid "" +"Let's extend the basic example to add some data and methods. Let's also " +"make the type usable as a base class. We'll create a new module, :mod:`!" +"custom2` that adds these capabilities:" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:233 +msgid "" +"#define PY_SSIZE_T_CLEAN\n" +"#include \n" +"#include /* for offsetof() */\n" +"\n" +"typedef struct {\n" +" PyObject_HEAD\n" +" PyObject *first; /* first name */\n" +" PyObject *last; /* last name */\n" +" int number;\n" +"} CustomObject;\n" +"\n" +"static void\n" +"Custom_dealloc(PyObject *op)\n" +"{\n" +" CustomObject *self = (CustomObject *) op;\n" +" Py_XDECREF(self->first);\n" +" Py_XDECREF(self->last);\n" +" Py_TYPE(self)->tp_free(self);\n" +"}\n" +"\n" +"static PyObject *\n" +"Custom_new(PyTypeObject *type, PyObject *args, PyObject *kwds)\n" +"{\n" +" CustomObject *self;\n" +" self = (CustomObject *) type->tp_alloc(type, 0);\n" +" if (self != NULL) {\n" +" self->first = Py_GetConstant(Py_CONSTANT_EMPTY_STR);\n" +" if (self->first == NULL) {\n" +" Py_DECREF(self);\n" +" return NULL;\n" +" }\n" +" self->last = Py_GetConstant(Py_CONSTANT_EMPTY_STR);\n" +" if (self->last == NULL) {\n" +" Py_DECREF(self);\n" +" return NULL;\n" +" }\n" +" self->number = 0;\n" +" }\n" +" return (PyObject *) self;\n" +"}\n" +"\n" +"static int\n" +"Custom_init(PyObject *op, PyObject *args, PyObject *kwds)\n" +"{\n" +" CustomObject *self = (CustomObject *) op;\n" +" static char *kwlist[] = {\"first\", \"last\", \"number\", NULL};\n" +" PyObject *first = NULL, *last = NULL;\n" +"\n" +" if (!PyArg_ParseTupleAndKeywords(args, kwds, \"|OOi\", kwlist,\n" +" &first, &last,\n" +" &self->number))\n" +" return -1;\n" +"\n" +" if (first) {\n" +" Py_XSETREF(self->first, Py_NewRef(first));\n" +" }\n" +" if (last) {\n" +" Py_XSETREF(self->last, Py_NewRef(last));\n" +" }\n" +" return 0;\n" +"}\n" +"\n" +"static PyMemberDef Custom_members[] = {\n" +" {\"first\", Py_T_OBJECT_EX, offsetof(CustomObject, first), 0,\n" +" \"first name\"},\n" +" {\"last\", Py_T_OBJECT_EX, offsetof(CustomObject, last), 0,\n" +" \"last name\"},\n" +" {\"number\", Py_T_INT, offsetof(CustomObject, number), 0,\n" +" \"custom number\"},\n" +" {NULL} /* Sentinel */\n" +"};\n" +"\n" +"static PyObject *\n" +"Custom_name(PyObject *op, PyObject *Py_UNUSED(dummy))\n" +"{\n" +" CustomObject *self = (CustomObject *) op;\n" +" if (self->first == NULL) {\n" +" PyErr_SetString(PyExc_AttributeError, \"first\");\n" +" return NULL;\n" +" }\n" +" if (self->last == NULL) {\n" +" PyErr_SetString(PyExc_AttributeError, \"last\");\n" +" return NULL;\n" +" }\n" +" return PyUnicode_FromFormat(\"%S %S\", self->first, self->last);\n" +"}\n" +"\n" +"static PyMethodDef Custom_methods[] = {\n" +" {\"name\", Custom_name, METH_NOARGS,\n" +" \"Return the name, combining the first and last name\"\n" +" },\n" +" {NULL} /* Sentinel */\n" +"};\n" +"\n" +"static PyTypeObject CustomType = {\n" +" .ob_base = PyVarObject_HEAD_INIT(NULL, 0)\n" +" .tp_name = \"custom2.Custom\",\n" +" .tp_doc = PyDoc_STR(\"Custom objects\"),\n" +" .tp_basicsize = sizeof(CustomObject),\n" +" .tp_itemsize = 0,\n" +" .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE,\n" +" .tp_new = Custom_new,\n" +" .tp_init = Custom_init,\n" +" .tp_dealloc = Custom_dealloc,\n" +" .tp_members = Custom_members,\n" +" .tp_methods = Custom_methods,\n" +"};\n" +"\n" +"static int\n" +"custom_module_exec(PyObject *m)\n" +"{\n" +" if (PyType_Ready(&CustomType) < 0) {\n" +" return -1;\n" +" }\n" +"\n" +" if (PyModule_AddObjectRef(m, \"Custom\", (PyObject *) &CustomType) < 0) " +"{\n" +" return -1;\n" +" }\n" +"\n" +" return 0;\n" +"}\n" +"\n" +"static PyModuleDef_Slot custom_module_slots[] = {\n" +" {Py_mod_exec, custom_module_exec},\n" +" {Py_mod_multiple_interpreters, " +"Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED},\n" +" {0, NULL}\n" +"};\n" +"\n" +"static PyModuleDef custom_module = {\n" +" .m_base = PyModuleDef_HEAD_INIT,\n" +" .m_name = \"custom2\",\n" +" .m_doc = \"Example module that creates an extension type.\",\n" +" .m_size = 0,\n" +" .m_slots = custom_module_slots,\n" +"};\n" +"\n" +"PyMODINIT_FUNC\n" +"PyInit_custom2(void)\n" +"{\n" +" return PyModuleDef_Init(&custom_module);\n" +"}\n" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:236 +msgid "This version of the module has a number of changes." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:238 +msgid "" +"The :class:`!Custom` type now has three data attributes in its C struct, " +"*first*, *last*, and *number*. The *first* and *last* variables are Python " +"strings containing first and last names. The *number* attribute is a C " +"integer." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:242 +msgid "The object structure is updated accordingly::" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:244 +msgid "" +"typedef struct {\n" +" PyObject_HEAD\n" +" PyObject *first; /* first name */\n" +" PyObject *last; /* last name */\n" +" int number;\n" +"} CustomObject;" +msgstr "" +"typedef struct {\n" +" PyObject_HEAD\n" +" PyObject *first; /* first name */\n" +" PyObject *last; /* last name */\n" +" int number;\n" +"} CustomObject;" + +#: ../../extending/newtypes_tutorial.rst:251 +msgid "" +"Because we now have data to manage, we have to be more careful about object " +"allocation and deallocation. At a minimum, we need a deallocation method::" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:254 +msgid "" +"static void\n" +"Custom_dealloc(PyObject *op)\n" +"{\n" +" CustomObject *self = (CustomObject *) op;\n" +" Py_XDECREF(self->first);\n" +" Py_XDECREF(self->last);\n" +" Py_TYPE(self)->tp_free(self);\n" +"}" +msgstr "" +"static void\n" +"Custom_dealloc(PyObject *op)\n" +"{\n" +" CustomObject *self = (CustomObject *) op;\n" +" Py_XDECREF(self->first);\n" +" Py_XDECREF(self->last);\n" +" Py_TYPE(self)->tp_free(self);\n" +"}" + +#: ../../extending/newtypes_tutorial.rst:263 +msgid "which is assigned to the :c:member:`~PyTypeObject.tp_dealloc` member::" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:265 +msgid ".tp_dealloc = Custom_dealloc," +msgstr ".tp_dealloc = Custom_dealloc," + +#: ../../extending/newtypes_tutorial.rst:267 +msgid "" +"This method first clears the reference counts of the two Python " +"attributes. :c:func:`Py_XDECREF` correctly handles the case where its " +"argument is ``NULL`` (which might happen here if ``tp_new`` failed midway). " +"It then calls the :c:member:`~PyTypeObject.tp_free` member of the object's " +"type (computed by ``Py_TYPE(self)``) to free the object's memory. Note that " +"the object's type might not be :class:`!CustomType`, because the object may " +"be an instance of a subclass." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:277 +msgid "" +"The explicit cast to ``CustomObject *`` above is needed because we defined " +"``Custom_dealloc`` to take a ``PyObject *`` argument, as the ``tp_dealloc`` " +"function pointer expects to receive a ``PyObject *`` argument. By assigning " +"to the ``tp_dealloc`` slot of a type, we declare that it can only be called " +"with instances of our ``CustomObject`` class, so the cast to ``(CustomObject " +"*)`` is safe. This is object-oriented polymorphism, in C!" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:285 +msgid "" +"In existing code, or in previous versions of this tutorial, you might see " +"similar functions take a pointer to the subtype object structure " +"(``CustomObject*``) directly, like this::" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:289 +msgid "" +"Custom_dealloc(CustomObject *self)\n" +"{\n" +" Py_XDECREF(self->first);\n" +" Py_XDECREF(self->last);\n" +" Py_TYPE(self)->tp_free((PyObject *) self);\n" +"}\n" +"...\n" +".tp_dealloc = (destructor) Custom_dealloc," +msgstr "" +"Custom_dealloc(CustomObject *self)\n" +"{\n" +" Py_XDECREF(self->first);\n" +" Py_XDECREF(self->last);\n" +" Py_TYPE(self)->tp_free((PyObject *) self);\n" +"}\n" +"...\n" +".tp_dealloc = (destructor) Custom_dealloc," + +#: ../../extending/newtypes_tutorial.rst:298 +msgid "" +"This does the same thing on all architectures that CPython supports, but " +"according to the C standard, it invokes undefined behavior." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:302 +msgid "" +"We want to make sure that the first and last names are initialized to empty " +"strings, so we provide a ``tp_new`` implementation::" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:305 +msgid "" +"static PyObject *\n" +"Custom_new(PyTypeObject *type, PyObject *args, PyObject *kwds)\n" +"{\n" +" CustomObject *self;\n" +" self = (CustomObject *) type->tp_alloc(type, 0);\n" +" if (self != NULL) {\n" +" self->first = PyUnicode_FromString(\"\");\n" +" if (self->first == NULL) {\n" +" Py_DECREF(self);\n" +" return NULL;\n" +" }\n" +" self->last = PyUnicode_FromString(\"\");\n" +" if (self->last == NULL) {\n" +" Py_DECREF(self);\n" +" return NULL;\n" +" }\n" +" self->number = 0;\n" +" }\n" +" return (PyObject *) self;\n" +"}" +msgstr "" +"static PyObject *\n" +"Custom_new(PyTypeObject *type, PyObject *args, PyObject *kwds)\n" +"{\n" +" CustomObject *self;\n" +" self = (CustomObject *) type->tp_alloc(type, 0);\n" +" if (self != NULL) {\n" +" self->first = PyUnicode_FromString(\"\");\n" +" if (self->first == NULL) {\n" +" Py_DECREF(self);\n" +" return NULL;\n" +" }\n" +" self->last = PyUnicode_FromString(\"\");\n" +" if (self->last == NULL) {\n" +" Py_DECREF(self);\n" +" return NULL;\n" +" }\n" +" self->number = 0;\n" +" }\n" +" return (PyObject *) self;\n" +"}" + +#: ../../extending/newtypes_tutorial.rst:326 +msgid "and install it in the :c:member:`~PyTypeObject.tp_new` member::" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:328 +msgid ".tp_new = Custom_new," +msgstr ".tp_new = Custom_new," + +#: ../../extending/newtypes_tutorial.rst:330 +msgid "" +"The ``tp_new`` handler is responsible for creating (as opposed to " +"initializing) objects of the type. It is exposed in Python as " +"the :meth:`~object.__new__` method. It is not required to define a " +"``tp_new`` member, and indeed many extension types will simply " +"reuse :c:func:`PyType_GenericNew` as done in the first version of " +"the :class:`!Custom` type above. In this case, we use the ``tp_new`` " +"handler to initialize the ``first`` and ``last`` attributes to non-``NULL`` " +"default values." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:338 +msgid "" +"``tp_new`` is passed the type being instantiated (not necessarily " +"``CustomType``, if a subclass is instantiated) and any arguments passed when " +"the type was called, and is expected to return the instance created. " +"``tp_new`` handlers always accept positional and keyword arguments, but they " +"often ignore the arguments, leaving the argument handling to initializer " +"(a.k.a. ``tp_init`` in C or ``__init__`` in Python) methods." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:346 +msgid "" +"``tp_new`` shouldn't call ``tp_init`` explicitly, as the interpreter will do " +"it itself." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:349 +msgid "" +"The ``tp_new`` implementation calls the :c:member:`~PyTypeObject.tp_alloc` " +"slot to allocate memory::" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:352 +msgid "self = (CustomObject *) type->tp_alloc(type, 0);" +msgstr "self = (CustomObject *) type->tp_alloc(type, 0);" + +#: ../../extending/newtypes_tutorial.rst:354 +msgid "" +"Since memory allocation may fail, we must check " +"the :c:member:`~PyTypeObject.tp_alloc` result against ``NULL`` before " +"proceeding." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:358 +msgid "" +"We didn't fill the :c:member:`~PyTypeObject.tp_alloc` slot ourselves. " +"Rather :c:func:`PyType_Ready` fills it for us by inheriting it from our base " +"class, which is :class:`object` by default. Most types use the default " +"allocation strategy." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:364 +msgid "" +"If you are creating a co-operative :c:member:`~PyTypeObject.tp_new` (one " +"that calls a base type's :c:member:`~PyTypeObject.tp_new` " +"or :meth:`~object.__new__`), you must *not* try to determine what method to " +"call using method resolution order at runtime. Always statically determine " +"what type you are going to call, and call " +"its :c:member:`~PyTypeObject.tp_new` directly, or via ``type->tp_base-" +">tp_new``. If you do not do this, Python subclasses of your type that also " +"inherit from other Python-defined classes may not work correctly. " +"(Specifically, you may not be able to create instances of such subclasses " +"without getting a :exc:`TypeError`.)" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:374 +msgid "" +"We also define an initialization function which accepts arguments to provide " +"initial values for our instance::" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:377 +msgid "" +"static int\n" +"Custom_init(PyObject *op, PyObject *args, PyObject *kwds)\n" +"{\n" +" CustomObject *self = (CustomObject *) op;\n" +" static char *kwlist[] = {\"first\", \"last\", \"number\", NULL};\n" +" PyObject *first = NULL, *last = NULL, *tmp;\n" +"\n" +" if (!PyArg_ParseTupleAndKeywords(args, kwds, \"|OOi\", kwlist,\n" +" &first, &last,\n" +" &self->number))\n" +" return -1;\n" +"\n" +" if (first) {\n" +" tmp = self->first;\n" +" Py_INCREF(first);\n" +" self->first = first;\n" +" Py_XDECREF(tmp);\n" +" }\n" +" if (last) {\n" +" tmp = self->last;\n" +" Py_INCREF(last);\n" +" self->last = last;\n" +" Py_XDECREF(tmp);\n" +" }\n" +" return 0;\n" +"}" +msgstr "" +"static int\n" +"Custom_init(PyObject *op, PyObject *args, PyObject *kwds)\n" +"{\n" +" CustomObject *self = (CustomObject *) op;\n" +" static char *kwlist[] = {\"first\", \"last\", \"number\", NULL};\n" +" PyObject *first = NULL, *last = NULL, *tmp;\n" +"\n" +" if (!PyArg_ParseTupleAndKeywords(args, kwds, \"|OOi\", kwlist,\n" +" &first, &last,\n" +" &self->number))\n" +" return -1;\n" +"\n" +" if (first) {\n" +" tmp = self->first;\n" +" Py_INCREF(first);\n" +" self->first = first;\n" +" Py_XDECREF(tmp);\n" +" }\n" +" if (last) {\n" +" tmp = self->last;\n" +" Py_INCREF(last);\n" +" self->last = last;\n" +" Py_XDECREF(tmp);\n" +" }\n" +" return 0;\n" +"}" + +#: ../../extending/newtypes_tutorial.rst:404 +msgid "by filling the :c:member:`~PyTypeObject.tp_init` slot. ::" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:406 +msgid ".tp_init = Custom_init," +msgstr ".tp_init = Custom_init," + +#: ../../extending/newtypes_tutorial.rst:408 +msgid "" +"The :c:member:`~PyTypeObject.tp_init` slot is exposed in Python as " +"the :meth:`~object.__init__` method. It is used to initialize an object " +"after it's created. Initializers always accept positional and keyword " +"arguments, and they should return either ``0`` on success or ``-1`` on error." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:413 +msgid "" +"Unlike the ``tp_new`` handler, there is no guarantee that ``tp_init`` is " +"called at all (for example, the :mod:`pickle` module by default doesn't " +"call :meth:`~object.__init__` on unpickled instances). It can also be " +"called multiple times. Anyone can call the :meth:`!__init__` method on our " +"objects. For this reason, we have to be extra careful when assigning the " +"new attribute values. We might be tempted, for example to assign the " +"``first`` member like this::" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:421 +msgid "" +"if (first) {\n" +" Py_XDECREF(self->first);\n" +" Py_INCREF(first);\n" +" self->first = first;\n" +"}" +msgstr "" +"if (first) {\n" +" Py_XDECREF(self->first);\n" +" Py_INCREF(first);\n" +" self->first = first;\n" +"}" + +#: ../../extending/newtypes_tutorial.rst:427 +msgid "" +"But this would be risky. Our type doesn't restrict the type of the " +"``first`` member, so it could be any kind of object. It could have a " +"destructor that causes code to be executed that tries to access the " +"``first`` member; or that destructor could detach the :term:`thread state " +"` and let arbitrary code run in other threads that " +"accesses and modifies our object." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:434 +msgid "" +"To be paranoid and protect ourselves against this possibility, we almost " +"always reassign members before decrementing their reference counts. When " +"don't we have to do this?" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:438 +msgid "when we absolutely know that the reference count is greater than 1;" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:440 +msgid "" +"when we know that deallocation of the object [#]_ will neither detach " +"the :term:`thread state ` nor cause any calls back " +"into our type's code;" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:443 +msgid "" +"when decrementing a reference count in " +"a :c:member:`~PyTypeObject.tp_dealloc` handler on a type which doesn't " +"support cyclic garbage collection [#]_." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:446 +msgid "" +"We want to expose our instance variables as attributes. There are a number " +"of ways to do that. The simplest way is to define member definitions::" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:449 +msgid "" +"static PyMemberDef Custom_members[] = {\n" +" {\"first\", Py_T_OBJECT_EX, offsetof(CustomObject, first), 0,\n" +" \"first name\"},\n" +" {\"last\", Py_T_OBJECT_EX, offsetof(CustomObject, last), 0,\n" +" \"last name\"},\n" +" {\"number\", Py_T_INT, offsetof(CustomObject, number), 0,\n" +" \"custom number\"},\n" +" {NULL} /* Sentinel */\n" +"};" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:459 +msgid "" +"and put the definitions in the :c:member:`~PyTypeObject.tp_members` slot::" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:461 +msgid ".tp_members = Custom_members," +msgstr ".tp_members = Custom_members," + +#: ../../extending/newtypes_tutorial.rst:463 +msgid "" +"Each member definition has a member name, type, offset, access flags and " +"documentation string. See the :ref:`Generic-Attribute-Management` section " +"below for details." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:467 +msgid "" +"A disadvantage of this approach is that it doesn't provide a way to restrict " +"the types of objects that can be assigned to the Python attributes. We " +"expect the first and last names to be strings, but any Python objects can be " +"assigned. Further, the attributes can be deleted, setting the C pointers to " +"``NULL``. Even though we can make sure the members are initialized to non-" +"``NULL`` values, the members can be set to ``NULL`` if the attributes are " +"deleted." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:474 +msgid "" +"We define a single method, :meth:`!Custom.name`, that outputs the objects " +"name as the concatenation of the first and last names. ::" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:477 +msgid "" +"static PyObject *\n" +"Custom_name(PyObject *op, PyObject *Py_UNUSED(dummy))\n" +"{\n" +" CustomObject *self = (CustomObject *) op;\n" +" if (self->first == NULL) {\n" +" PyErr_SetString(PyExc_AttributeError, \"first\");\n" +" return NULL;\n" +" }\n" +" if (self->last == NULL) {\n" +" PyErr_SetString(PyExc_AttributeError, \"last\");\n" +" return NULL;\n" +" }\n" +" return PyUnicode_FromFormat(\"%S %S\", self->first, self->last);\n" +"}" +msgstr "" +"static PyObject *\n" +"Custom_name(PyObject *op, PyObject *Py_UNUSED(dummy))\n" +"{\n" +" CustomObject *self = (CustomObject *) op;\n" +" if (self->first == NULL) {\n" +" PyErr_SetString(PyExc_AttributeError, \"first\");\n" +" return NULL;\n" +" }\n" +" if (self->last == NULL) {\n" +" PyErr_SetString(PyExc_AttributeError, \"last\");\n" +" return NULL;\n" +" }\n" +" return PyUnicode_FromFormat(\"%S %S\", self->first, self->last);\n" +"}" + +#: ../../extending/newtypes_tutorial.rst:492 +msgid "" +"The method is implemented as a C function that takes a :class:`!Custom` " +"(or :class:`!Custom` subclass) instance as the first argument. Methods " +"always take an instance as the first argument. Methods often take positional " +"and keyword arguments as well, but in this case we don't take any and don't " +"need to accept a positional argument tuple or keyword argument dictionary. " +"This method is equivalent to the Python method:" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:499 +msgid "" +"def name(self):\n" +" return \"%s %s\" % (self.first, self.last)" +msgstr "" +"def name(self):\n" +" return \"%s %s\" % (self.first, self.last)" + +#: ../../extending/newtypes_tutorial.rst:504 +msgid "" +"Note that we have to check for the possibility that our :attr:`!first` " +"and :attr:`!last` members are ``NULL``. This is because they can be " +"deleted, in which case they are set to ``NULL``. It would be better to " +"prevent deletion of these attributes and to restrict the attribute values to " +"be strings. We'll see how to do that in the next section." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:510 +msgid "" +"Now that we've defined the method, we need to create an array of method " +"definitions::" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:513 +msgid "" +"static PyMethodDef Custom_methods[] = {\n" +" {\"name\", Custom_name, METH_NOARGS,\n" +" \"Return the name, combining the first and last name\"\n" +" },\n" +" {NULL} /* Sentinel */\n" +"};" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:520 +msgid "" +"(note that we used the :c:macro:`METH_NOARGS` flag to indicate that the " +"method is expecting no arguments other than *self*)" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:523 +msgid "and assign it to the :c:member:`~PyTypeObject.tp_methods` slot::" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:525 +msgid ".tp_methods = Custom_methods," +msgstr ".tp_methods = Custom_methods," + +#: ../../extending/newtypes_tutorial.rst:527 +msgid "" +"Finally, we'll make our type usable as a base class for subclassing. We've " +"written our methods carefully so far so that they don't make any assumptions " +"about the type of the object being created or used, so all we need to do is " +"to add the :c:macro:`Py_TPFLAGS_BASETYPE` to our class flag definition::" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:532 +msgid ".tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE," +msgstr ".tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE," + +#: ../../extending/newtypes_tutorial.rst:534 +msgid "" +"We rename :c:func:`!PyInit_custom` to :c:func:`!PyInit_custom2`, update the " +"module name in the :c:type:`PyModuleDef` struct, and update the full class " +"name in the :c:type:`PyTypeObject` struct." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:538 +msgid "Finally, we update our :file:`setup.py` file to include the new module," +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:540 +msgid "" +"from setuptools import Extension, setup\n" +"setup(ext_modules=[\n" +" Extension(\"custom\", [\"custom.c\"]),\n" +" Extension(\"custom2\", [\"custom2.c\"]),\n" +"])" +msgstr "" +"from setuptools import Extension, setup\n" +"setup(ext_modules=[\n" +" Extension(\"custom\", [\"custom.c\"]),\n" +" Extension(\"custom2\", [\"custom2.c\"]),\n" +"])" + +#: ../../extending/newtypes_tutorial.rst:548 +msgid "and then we re-install so that we can ``import custom2``:" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:555 +msgid "Providing finer control over data attributes" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:557 +msgid "" +"In this section, we'll provide finer control over how the :attr:`!first` " +"and :attr:`!last` attributes are set in the :class:`!Custom` example. In the " +"previous version of our module, the instance variables :attr:`!first` " +"and :attr:`!last` could be set to non-string values or even deleted. We want " +"to make sure that these attributes always contain strings." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:563 +msgid "" +"#define PY_SSIZE_T_CLEAN\n" +"#include \n" +"#include /* for offsetof() */\n" +"\n" +"typedef struct {\n" +" PyObject_HEAD\n" +" PyObject *first; /* first name */\n" +" PyObject *last; /* last name */\n" +" int number;\n" +"} CustomObject;\n" +"\n" +"static void\n" +"Custom_dealloc(PyObject *op)\n" +"{\n" +" CustomObject *self = (CustomObject *) op;\n" +" Py_XDECREF(self->first);\n" +" Py_XDECREF(self->last);\n" +" Py_TYPE(self)->tp_free(self);\n" +"}\n" +"\n" +"static PyObject *\n" +"Custom_new(PyTypeObject *type, PyObject *args, PyObject *kwds)\n" +"{\n" +" CustomObject *self;\n" +" self = (CustomObject *) type->tp_alloc(type, 0);\n" +" if (self != NULL) {\n" +" self->first = Py_GetConstant(Py_CONSTANT_EMPTY_STR);\n" +" if (self->first == NULL) {\n" +" Py_DECREF(self);\n" +" return NULL;\n" +" }\n" +" self->last = Py_GetConstant(Py_CONSTANT_EMPTY_STR);\n" +" if (self->last == NULL) {\n" +" Py_DECREF(self);\n" +" return NULL;\n" +" }\n" +" self->number = 0;\n" +" }\n" +" return (PyObject *) self;\n" +"}\n" +"\n" +"static int\n" +"Custom_init(PyObject *op, PyObject *args, PyObject *kwds)\n" +"{\n" +" CustomObject *self = (CustomObject *) op;\n" +" static char *kwlist[] = {\"first\", \"last\", \"number\", NULL};\n" +" PyObject *first = NULL, *last = NULL;\n" +"\n" +" if (!PyArg_ParseTupleAndKeywords(args, kwds, \"|UUi\", kwlist,\n" +" &first, &last,\n" +" &self->number))\n" +" return -1;\n" +"\n" +" if (first) {\n" +" Py_SETREF(self->first, Py_NewRef(first));\n" +" }\n" +" if (last) {\n" +" Py_SETREF(self->last, Py_NewRef(last));\n" +" }\n" +" return 0;\n" +"}\n" +"\n" +"static PyMemberDef Custom_members[] = {\n" +" {\"number\", Py_T_INT, offsetof(CustomObject, number), 0,\n" +" \"custom number\"},\n" +" {NULL} /* Sentinel */\n" +"};\n" +"\n" +"static PyObject *\n" +"Custom_getfirst(PyObject *op, void *closure)\n" +"{\n" +" CustomObject *self = (CustomObject *) op;\n" +" return Py_NewRef(self->first);\n" +"}\n" +"\n" +"static int\n" +"Custom_setfirst(PyObject *op, PyObject *value, void *closure)\n" +"{\n" +" CustomObject *self = (CustomObject *) op;\n" +" if (value == NULL) {\n" +" PyErr_SetString(PyExc_TypeError, \"Cannot delete the first " +"attribute\");\n" +" return -1;\n" +" }\n" +" if (!PyUnicode_Check(value)) {\n" +" PyErr_SetString(PyExc_TypeError,\n" +" \"The first attribute value must be a string\");\n" +" return -1;\n" +" }\n" +" Py_SETREF(self->first, Py_NewRef(value));\n" +" return 0;\n" +"}\n" +"\n" +"static PyObject *\n" +"Custom_getlast(PyObject *op, void *closure)\n" +"{\n" +" CustomObject *self = (CustomObject *) op;\n" +" return Py_NewRef(self->last);\n" +"}\n" +"\n" +"static int\n" +"Custom_setlast(PyObject *op, PyObject *value, void *closure)\n" +"{\n" +" CustomObject *self = (CustomObject *) op;\n" +" if (value == NULL) {\n" +" PyErr_SetString(PyExc_TypeError, \"Cannot delete the last " +"attribute\");\n" +" return -1;\n" +" }\n" +" if (!PyUnicode_Check(value)) {\n" +" PyErr_SetString(PyExc_TypeError,\n" +" \"The last attribute value must be a string\");\n" +" return -1;\n" +" }\n" +" Py_SETREF(self->last, Py_NewRef(value));\n" +" return 0;\n" +"}\n" +"\n" +"static PyGetSetDef Custom_getsetters[] = {\n" +" {\"first\", Custom_getfirst, Custom_setfirst,\n" +" \"first name\", NULL},\n" +" {\"last\", Custom_getlast, Custom_setlast,\n" +" \"last name\", NULL},\n" +" {NULL} /* Sentinel */\n" +"};\n" +"\n" +"static PyObject *\n" +"Custom_name(PyObject *op, PyObject *Py_UNUSED(dummy))\n" +"{\n" +" CustomObject *self = (CustomObject *) op;\n" +" return PyUnicode_FromFormat(\"%S %S\", self->first, self->last);\n" +"}\n" +"\n" +"static PyMethodDef Custom_methods[] = {\n" +" {\"name\", Custom_name, METH_NOARGS,\n" +" \"Return the name, combining the first and last name\"\n" +" },\n" +" {NULL} /* Sentinel */\n" +"};\n" +"\n" +"static PyTypeObject CustomType = {\n" +" .ob_base = PyVarObject_HEAD_INIT(NULL, 0)\n" +" .tp_name = \"custom3.Custom\",\n" +" .tp_doc = PyDoc_STR(\"Custom objects\"),\n" +" .tp_basicsize = sizeof(CustomObject),\n" +" .tp_itemsize = 0,\n" +" .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE,\n" +" .tp_new = Custom_new,\n" +" .tp_init = Custom_init,\n" +" .tp_dealloc = Custom_dealloc,\n" +" .tp_members = Custom_members,\n" +" .tp_methods = Custom_methods,\n" +" .tp_getset = Custom_getsetters,\n" +"};\n" +"\n" +"static int\n" +"custom_module_exec(PyObject *m)\n" +"{\n" +" if (PyType_Ready(&CustomType) < 0) {\n" +" return -1;\n" +" }\n" +"\n" +" if (PyModule_AddObjectRef(m, \"Custom\", (PyObject *) &CustomType) < 0) " +"{\n" +" return -1;\n" +" }\n" +"\n" +" return 0;\n" +"}\n" +"\n" +"static PyModuleDef_Slot custom_module_slots[] = {\n" +" {Py_mod_exec, custom_module_exec},\n" +" {Py_mod_multiple_interpreters, " +"Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED},\n" +" {0, NULL}\n" +"};\n" +"\n" +"static PyModuleDef custom_module = {\n" +" .m_base = PyModuleDef_HEAD_INIT,\n" +" .m_name = \"custom3\",\n" +" .m_doc = \"Example module that creates an extension type.\",\n" +" .m_size = 0,\n" +" .m_slots = custom_module_slots,\n" +"};\n" +"\n" +"PyMODINIT_FUNC\n" +"PyInit_custom3(void)\n" +"{\n" +" return PyModuleDef_Init(&custom_module);\n" +"}\n" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:566 +msgid "" +"To provide greater control, over the :attr:`!first` and :attr:`!last` " +"attributes, we'll use custom getter and setter functions. Here are the " +"functions for getting and setting the :attr:`!first` attribute::" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:570 +msgid "" +"static PyObject *\n" +"Custom_getfirst(PyObject *op, void *closure)\n" +"{\n" +" CustomObject *self = (CustomObject *) op;\n" +" Py_INCREF(self->first);\n" +" return self->first;\n" +"}\n" +"\n" +"static int\n" +"Custom_setfirst(PyObject *op, PyObject *value, void *closure)\n" +"{\n" +" CustomObject *self = (CustomObject *) op;\n" +" PyObject *tmp;\n" +" if (value == NULL) {\n" +" PyErr_SetString(PyExc_TypeError, \"Cannot delete the first " +"attribute\");\n" +" return -1;\n" +" }\n" +" if (!PyUnicode_Check(value)) {\n" +" PyErr_SetString(PyExc_TypeError,\n" +" \"The first attribute value must be a string\");\n" +" return -1;\n" +" }\n" +" tmp = self->first;\n" +" Py_INCREF(value);\n" +" self->first = value;\n" +" Py_DECREF(tmp);\n" +" return 0;\n" +"}" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:599 +msgid "" +"The getter function is passed a :class:`!Custom` object and a \"closure\", " +"which is a void pointer. In this case, the closure is ignored. (The " +"closure supports an advanced usage in which definition data is passed to the " +"getter and setter. This could, for example, be used to allow a single set of " +"getter and setter functions that decide the attribute to get or set based on " +"data in the closure.)" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:605 +msgid "" +"The setter function is passed the :class:`!Custom` object, the new value, " +"and the closure. The new value may be ``NULL``, in which case the attribute " +"is being deleted. In our setter, we raise an error if the attribute is " +"deleted or if its new value is not a string." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:610 +msgid "We create an array of :c:type:`PyGetSetDef` structures::" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:612 +msgid "" +"static PyGetSetDef Custom_getsetters[] = {\n" +" {\"first\", Custom_getfirst, Custom_setfirst,\n" +" \"first name\", NULL},\n" +" {\"last\", Custom_getlast, Custom_setlast,\n" +" \"last name\", NULL},\n" +" {NULL} /* Sentinel */\n" +"};" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:620 +msgid "and register it in the :c:member:`~PyTypeObject.tp_getset` slot::" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:622 +msgid ".tp_getset = Custom_getsetters," +msgstr ".tp_getset = Custom_getsetters," + +#: ../../extending/newtypes_tutorial.rst:624 +msgid "" +"The last item in a :c:type:`PyGetSetDef` structure is the \"closure\" " +"mentioned above. In this case, we aren't using a closure, so we just pass " +"``NULL``." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:627 +msgid "We also remove the member definitions for these attributes::" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:629 +msgid "" +"static PyMemberDef Custom_members[] = {\n" +" {\"number\", Py_T_INT, offsetof(CustomObject, number), 0,\n" +" \"custom number\"},\n" +" {NULL} /* Sentinel */\n" +"};" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:635 +msgid "" +"We also need to update the :c:member:`~PyTypeObject.tp_init` handler to only " +"allow strings [#]_ to be passed::" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:638 +msgid "" +"static int\n" +"Custom_init(PyObject *op, PyObject *args, PyObject *kwds)\n" +"{\n" +" CustomObject *self = (CustomObject *) op;\n" +" static char *kwlist[] = {\"first\", \"last\", \"number\", NULL};\n" +" PyObject *first = NULL, *last = NULL, *tmp;\n" +"\n" +" if (!PyArg_ParseTupleAndKeywords(args, kwds, \"|UUi\", kwlist,\n" +" &first, &last,\n" +" &self->number))\n" +" return -1;\n" +"\n" +" if (first) {\n" +" tmp = self->first;\n" +" Py_INCREF(first);\n" +" self->first = first;\n" +" Py_DECREF(tmp);\n" +" }\n" +" if (last) {\n" +" tmp = self->last;\n" +" Py_INCREF(last);\n" +" self->last = last;\n" +" Py_DECREF(tmp);\n" +" }\n" +" return 0;\n" +"}" +msgstr "" +"static int\n" +"Custom_init(PyObject *op, PyObject *args, PyObject *kwds)\n" +"{\n" +" CustomObject *self = (CustomObject *) op;\n" +" static char *kwlist[] = {\"first\", \"last\", \"number\", NULL};\n" +" PyObject *first = NULL, *last = NULL, *tmp;\n" +"\n" +" if (!PyArg_ParseTupleAndKeywords(args, kwds, \"|UUi\", kwlist,\n" +" &first, &last,\n" +" &self->number))\n" +" return -1;\n" +"\n" +" if (first) {\n" +" tmp = self->first;\n" +" Py_INCREF(first);\n" +" self->first = first;\n" +" Py_DECREF(tmp);\n" +" }\n" +" if (last) {\n" +" tmp = self->last;\n" +" Py_INCREF(last);\n" +" self->last = last;\n" +" Py_DECREF(tmp);\n" +" }\n" +" return 0;\n" +"}" + +#: ../../extending/newtypes_tutorial.rst:665 +msgid "" +"With these changes, we can assure that the ``first`` and ``last`` members " +"are never ``NULL`` so we can remove checks for ``NULL`` values in almost all " +"cases. This means that most of the :c:func:`Py_XDECREF` calls can be " +"converted to :c:func:`Py_DECREF` calls. The only place we can't change " +"these calls is in the ``tp_dealloc`` implementation, where there is the " +"possibility that the initialization of these members failed in ``tp_new``." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:672 +msgid "" +"We also rename the module initialization function and module name in the " +"initialization function, as we did before, and we add an extra definition to " +"the :file:`setup.py` file." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:678 +msgid "Supporting cyclic garbage collection" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:680 +msgid "" +"Python has a :term:`cyclic garbage collector (GC) ` that " +"can identify unneeded objects even when their reference counts are not zero. " +"This can happen when objects are involved in cycles. For example, consider:" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:684 +msgid "" +">>> l = []\n" +">>> l.append(l)\n" +">>> del l" +msgstr "" +">>> l = []\n" +">>> l.append(l)\n" +">>> del l" + +#: ../../extending/newtypes_tutorial.rst:690 +msgid "" +"In this example, we create a list that contains itself. When we delete it, " +"it still has a reference from itself. Its reference count doesn't drop to " +"zero. Fortunately, Python's cyclic garbage collector will eventually figure " +"out that the list is garbage and free it." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:695 +msgid "" +"In the second version of the :class:`!Custom` example, we allowed any kind " +"of object to be stored in the :attr:`!first` or :attr:`!last` attributes " +"[#]_. Besides, in the second and third versions, we allowed " +"subclassing :class:`!Custom`, and subclasses may add arbitrary attributes. " +"For any of those two reasons, :class:`!Custom` objects can participate in " +"cycles:" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:701 +msgid "" +">>> import custom3\n" +">>> class Derived(custom3.Custom): pass\n" +"...\n" +">>> n = Derived()\n" +">>> n.some_attribute = n" +msgstr "" +">>> import custom3\n" +">>> class Derived(custom3.Custom): pass\n" +"...\n" +">>> n = Derived()\n" +">>> n.some_attribute = n" + +#: ../../extending/newtypes_tutorial.rst:709 +msgid "" +"To allow a :class:`!Custom` instance participating in a reference cycle to " +"be properly detected and collected by the cyclic GC, our :class:`!Custom` " +"type needs to fill two additional slots and to enable a flag that enables " +"these slots:" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:713 +msgid "" +"#define PY_SSIZE_T_CLEAN\n" +"#include \n" +"#include /* for offsetof() */\n" +"\n" +"typedef struct {\n" +" PyObject_HEAD\n" +" PyObject *first; /* first name */\n" +" PyObject *last; /* last name */\n" +" int number;\n" +"} CustomObject;\n" +"\n" +"static int\n" +"Custom_traverse(PyObject *op, visitproc visit, void *arg)\n" +"{\n" +" CustomObject *self = (CustomObject *) op;\n" +" Py_VISIT(self->first);\n" +" Py_VISIT(self->last);\n" +" return 0;\n" +"}\n" +"\n" +"static int\n" +"Custom_clear(PyObject *op)\n" +"{\n" +" CustomObject *self = (CustomObject *) op;\n" +" Py_CLEAR(self->first);\n" +" Py_CLEAR(self->last);\n" +" return 0;\n" +"}\n" +"\n" +"static void\n" +"Custom_dealloc(PyObject *op)\n" +"{\n" +" PyObject_GC_UnTrack(op);\n" +" (void)Custom_clear(op);\n" +" Py_TYPE(op)->tp_free(op);\n" +"}\n" +"\n" +"static PyObject *\n" +"Custom_new(PyTypeObject *type, PyObject *args, PyObject *kwds)\n" +"{\n" +" CustomObject *self;\n" +" self = (CustomObject *) type->tp_alloc(type, 0);\n" +" if (self != NULL) {\n" +" self->first = Py_GetConstant(Py_CONSTANT_EMPTY_STR);\n" +" if (self->first == NULL) {\n" +" Py_DECREF(self);\n" +" return NULL;\n" +" }\n" +" self->last = Py_GetConstant(Py_CONSTANT_EMPTY_STR);\n" +" if (self->last == NULL) {\n" +" Py_DECREF(self);\n" +" return NULL;\n" +" }\n" +" self->number = 0;\n" +" }\n" +" return (PyObject *) self;\n" +"}\n" +"\n" +"static int\n" +"Custom_init(PyObject *op, PyObject *args, PyObject *kwds)\n" +"{\n" +" CustomObject *self = (CustomObject *) op;\n" +" static char *kwlist[] = {\"first\", \"last\", \"number\", NULL};\n" +" PyObject *first = NULL, *last = NULL;\n" +"\n" +" if (!PyArg_ParseTupleAndKeywords(args, kwds, \"|UUi\", kwlist,\n" +" &first, &last,\n" +" &self->number))\n" +" return -1;\n" +"\n" +" if (first) {\n" +" Py_SETREF(self->first, Py_NewRef(first));\n" +" }\n" +" if (last) {\n" +" Py_SETREF(self->last, Py_NewRef(last));\n" +" }\n" +" return 0;\n" +"}\n" +"\n" +"static PyMemberDef Custom_members[] = {\n" +" {\"number\", Py_T_INT, offsetof(CustomObject, number), 0,\n" +" \"custom number\"},\n" +" {NULL} /* Sentinel */\n" +"};\n" +"\n" +"static PyObject *\n" +"Custom_getfirst(PyObject *op, void *closure)\n" +"{\n" +" CustomObject *self = (CustomObject *) op;\n" +" return Py_NewRef(self->first);\n" +"}\n" +"\n" +"static int\n" +"Custom_setfirst(PyObject *op, PyObject *value, void *closure)\n" +"{\n" +" CustomObject *self = (CustomObject *) op;\n" +" if (value == NULL) {\n" +" PyErr_SetString(PyExc_TypeError, \"Cannot delete the first " +"attribute\");\n" +" return -1;\n" +" }\n" +" if (!PyUnicode_Check(value)) {\n" +" PyErr_SetString(PyExc_TypeError,\n" +" \"The first attribute value must be a string\");\n" +" return -1;\n" +" }\n" +" Py_XSETREF(self->first, Py_NewRef(value));\n" +" return 0;\n" +"}\n" +"\n" +"static PyObject *\n" +"Custom_getlast(PyObject *op, void *closure)\n" +"{\n" +" CustomObject *self = (CustomObject *) op;\n" +" return Py_NewRef(self->last);\n" +"}\n" +"\n" +"static int\n" +"Custom_setlast(PyObject *op, PyObject *value, void *closure)\n" +"{\n" +" CustomObject *self = (CustomObject *) op;\n" +" if (value == NULL) {\n" +" PyErr_SetString(PyExc_TypeError, \"Cannot delete the last " +"attribute\");\n" +" return -1;\n" +" }\n" +" if (!PyUnicode_Check(value)) {\n" +" PyErr_SetString(PyExc_TypeError,\n" +" \"The last attribute value must be a string\");\n" +" return -1;\n" +" }\n" +" Py_XSETREF(self->last, Py_NewRef(value));\n" +" return 0;\n" +"}\n" +"\n" +"static PyGetSetDef Custom_getsetters[] = {\n" +" {\"first\", Custom_getfirst, Custom_setfirst,\n" +" \"first name\", NULL},\n" +" {\"last\", Custom_getlast, Custom_setlast,\n" +" \"last name\", NULL},\n" +" {NULL} /* Sentinel */\n" +"};\n" +"\n" +"static PyObject *\n" +"Custom_name(PyObject *op, PyObject *Py_UNUSED(dummy))\n" +"{\n" +" CustomObject *self = (CustomObject *) op;\n" +" return PyUnicode_FromFormat(\"%S %S\", self->first, self->last);\n" +"}\n" +"\n" +"static PyMethodDef Custom_methods[] = {\n" +" {\"name\", Custom_name, METH_NOARGS,\n" +" \"Return the name, combining the first and last name\"\n" +" },\n" +" {NULL} /* Sentinel */\n" +"};\n" +"\n" +"static PyTypeObject CustomType = {\n" +" .ob_base = PyVarObject_HEAD_INIT(NULL, 0)\n" +" .tp_name = \"custom4.Custom\",\n" +" .tp_doc = PyDoc_STR(\"Custom objects\"),\n" +" .tp_basicsize = sizeof(CustomObject),\n" +" .tp_itemsize = 0,\n" +" .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | " +"Py_TPFLAGS_HAVE_GC,\n" +" .tp_new = Custom_new,\n" +" .tp_init = Custom_init,\n" +" .tp_dealloc = Custom_dealloc,\n" +" .tp_traverse = Custom_traverse,\n" +" .tp_clear = Custom_clear,\n" +" .tp_members = Custom_members,\n" +" .tp_methods = Custom_methods,\n" +" .tp_getset = Custom_getsetters,\n" +"};\n" +"\n" +"static int\n" +"custom_module_exec(PyObject *m)\n" +"{\n" +" if (PyType_Ready(&CustomType) < 0) {\n" +" return -1;\n" +" }\n" +"\n" +" if (PyModule_AddObjectRef(m, \"Custom\", (PyObject *) &CustomType) < 0) " +"{\n" +" return -1;\n" +" }\n" +"\n" +" return 0;\n" +"}\n" +"\n" +"static PyModuleDef_Slot custom_module_slots[] = {\n" +" {Py_mod_exec, custom_module_exec},\n" +" {Py_mod_multiple_interpreters, " +"Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED},\n" +" {0, NULL}\n" +"};\n" +"\n" +"static PyModuleDef custom_module = {\n" +" .m_base = PyModuleDef_HEAD_INIT,\n" +" .m_name = \"custom4\",\n" +" .m_doc = \"Example module that creates an extension type.\",\n" +" .m_size = 0,\n" +" .m_slots = custom_module_slots,\n" +"};\n" +"\n" +"PyMODINIT_FUNC\n" +"PyInit_custom4(void)\n" +"{\n" +" return PyModuleDef_Init(&custom_module);\n" +"}\n" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:716 +msgid "" +"First, the traversal method lets the cyclic GC know about subobjects that " +"could participate in cycles::" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:719 +msgid "" +"static int\n" +"Custom_traverse(PyObject *op, visitproc visit, void *arg)\n" +"{\n" +" CustomObject *self = (CustomObject *) op;\n" +" int vret;\n" +" if (self->first) {\n" +" vret = visit(self->first, arg);\n" +" if (vret != 0)\n" +" return vret;\n" +" }\n" +" if (self->last) {\n" +" vret = visit(self->last, arg);\n" +" if (vret != 0)\n" +" return vret;\n" +" }\n" +" return 0;\n" +"}" +msgstr "" +"static int\n" +"Custom_traverse(PyObject *op, visitproc visit, void *arg)\n" +"{\n" +" CustomObject *self = (CustomObject *) op;\n" +" int vret;\n" +" if (self->first) {\n" +" vret = visit(self->first, arg);\n" +" if (vret != 0)\n" +" return vret;\n" +" }\n" +" if (self->last) {\n" +" vret = visit(self->last, arg);\n" +" if (vret != 0)\n" +" return vret;\n" +" }\n" +" return 0;\n" +"}" + +#: ../../extending/newtypes_tutorial.rst:737 +msgid "" +"For each subobject that can participate in cycles, we need to call " +"the :c:func:`!visit` function, which is passed to the traversal method. " +"The :c:func:`!visit` function takes as arguments the subobject and the extra " +"argument *arg* passed to the traversal method. It returns an integer value " +"that must be returned if it is non-zero." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:743 +msgid "" +"Python provides a :c:func:`Py_VISIT` macro that automates calling visit " +"functions. With :c:func:`Py_VISIT`, we can minimize the amount of " +"boilerplate in ``Custom_traverse``::" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:747 +msgid "" +"static int\n" +"Custom_traverse(PyObject *op, visitproc visit, void *arg)\n" +"{\n" +" CustomObject *self = (CustomObject *) op;\n" +" Py_VISIT(self->first);\n" +" Py_VISIT(self->last);\n" +" return 0;\n" +"}" +msgstr "" +"static int\n" +"Custom_traverse(PyObject *op, visitproc visit, void *arg)\n" +"{\n" +" CustomObject *self = (CustomObject *) op;\n" +" Py_VISIT(self->first);\n" +" Py_VISIT(self->last);\n" +" return 0;\n" +"}" + +#: ../../extending/newtypes_tutorial.rst:757 +msgid "" +"The :c:member:`~PyTypeObject.tp_traverse` implementation must name its " +"arguments exactly *visit* and *arg* in order to use :c:func:`Py_VISIT`." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:760 +msgid "" +"Second, we need to provide a method for clearing any subobjects that can " +"participate in cycles::" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:763 +msgid "" +"static int\n" +"Custom_clear(PyObject *op)\n" +"{\n" +" CustomObject *self = (CustomObject *) op;\n" +" Py_CLEAR(self->first);\n" +" Py_CLEAR(self->last);\n" +" return 0;\n" +"}" +msgstr "" +"static int\n" +"Custom_clear(PyObject *op)\n" +"{\n" +" CustomObject *self = (CustomObject *) op;\n" +" Py_CLEAR(self->first);\n" +" Py_CLEAR(self->last);\n" +" return 0;\n" +"}" + +#: ../../extending/newtypes_tutorial.rst:772 +msgid "" +"Notice the use of the :c:func:`Py_CLEAR` macro. It is the recommended and " +"safe way to clear data attributes of arbitrary types while decrementing " +"their reference counts. If you were to call :c:func:`Py_XDECREF` instead on " +"the attribute before setting it to ``NULL``, there is a possibility that the " +"attribute's destructor would call back into code that reads the attribute " +"again (*especially* if there is a reference cycle)." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:780 +msgid "You could emulate :c:func:`Py_CLEAR` by writing::" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:782 +msgid "" +"PyObject *tmp;\n" +"tmp = self->first;\n" +"self->first = NULL;\n" +"Py_XDECREF(tmp);" +msgstr "" +"PyObject *tmp;\n" +"tmp = self->first;\n" +"self->first = NULL;\n" +"Py_XDECREF(tmp);" + +#: ../../extending/newtypes_tutorial.rst:787 +msgid "" +"Nevertheless, it is much easier and less error-prone to always " +"use :c:func:`Py_CLEAR` when deleting an attribute. Don't try to micro-" +"optimize at the expense of robustness!" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:791 +msgid "" +"The deallocator ``Custom_dealloc`` may call arbitrary code when clearing " +"attributes. It means the circular GC can be triggered inside the function. " +"Since the GC assumes reference count is not zero, we need to untrack the " +"object from the GC by calling :c:func:`PyObject_GC_UnTrack` before clearing " +"members. Here is our reimplemented deallocator " +"using :c:func:`PyObject_GC_UnTrack` and ``Custom_clear``::" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:798 +msgid "" +"static void\n" +"Custom_dealloc(PyObject *op)\n" +"{\n" +" PyObject_GC_UnTrack(op);\n" +" (void)Custom_clear(op);\n" +" Py_TYPE(op)->tp_free(op);\n" +"}" +msgstr "" +"static void\n" +"Custom_dealloc(PyObject *op)\n" +"{\n" +" PyObject_GC_UnTrack(op);\n" +" (void)Custom_clear(op);\n" +" Py_TYPE(op)->tp_free(op);\n" +"}" + +#: ../../extending/newtypes_tutorial.rst:806 +msgid "" +"Finally, we add the :c:macro:`Py_TPFLAGS_HAVE_GC` flag to the class flags::" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:808 +msgid "" +".tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC," +msgstr "" +".tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC," + +#: ../../extending/newtypes_tutorial.rst:810 +msgid "" +"That's pretty much it. If we had written " +"custom :c:member:`~PyTypeObject.tp_alloc` " +"or :c:member:`~PyTypeObject.tp_free` handlers, we'd need to modify them for " +"cyclic garbage collection. Most extensions will use the versions " +"automatically provided." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:816 +msgid "Subclassing other types" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:818 +msgid "" +"It is possible to create new extension types that are derived from existing " +"types. It is easiest to inherit from the built in types, since an extension " +"can easily use the :c:type:`PyTypeObject` it needs. It can be difficult to " +"share these :c:type:`PyTypeObject` structures between extension modules." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:823 +msgid "" +"In this example we will create a :class:`!SubList` type that inherits from " +"the built-in :class:`list` type. The new type will be completely compatible " +"with regular lists, but will have an additional :meth:`!increment` method " +"that increases an internal counter:" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:828 +msgid "" +">>> import sublist\n" +">>> s = sublist.SubList(range(3))\n" +">>> s.extend(s)\n" +">>> print(len(s))\n" +"6\n" +">>> print(s.increment())\n" +"1\n" +">>> print(s.increment())\n" +"2" +msgstr "" +">>> import sublist\n" +">>> s = sublist.SubList(range(3))\n" +">>> s.extend(s)\n" +">>> print(len(s))\n" +"6\n" +">>> print(s.increment())\n" +"1\n" +">>> print(s.increment())\n" +"2" + +#: ../../extending/newtypes_tutorial.rst:840 +msgid "" +"#define PY_SSIZE_T_CLEAN\n" +"#include \n" +"\n" +"typedef struct {\n" +" PyListObject list;\n" +" int state;\n" +"} SubListObject;\n" +"\n" +"static PyObject *\n" +"SubList_increment(PyObject *op, PyObject *Py_UNUSED(dummy))\n" +"{\n" +" SubListObject *self = (SubListObject *) op;\n" +" self->state++;\n" +" return PyLong_FromLong(self->state);\n" +"}\n" +"\n" +"static PyMethodDef SubList_methods[] = {\n" +" {\"increment\", SubList_increment, METH_NOARGS,\n" +" PyDoc_STR(\"increment state counter\")},\n" +" {NULL},\n" +"};\n" +"\n" +"static int\n" +"SubList_init(PyObject *op, PyObject *args, PyObject *kwds)\n" +"{\n" +" SubListObject *self = (SubListObject *) op;\n" +" if (PyList_Type.tp_init(op, args, kwds) < 0)\n" +" return -1;\n" +" self->state = 0;\n" +" return 0;\n" +"}\n" +"\n" +"static PyTypeObject SubListType = {\n" +" .ob_base = PyVarObject_HEAD_INIT(NULL, 0)\n" +" .tp_name = \"sublist.SubList\",\n" +" .tp_doc = PyDoc_STR(\"SubList objects\"),\n" +" .tp_basicsize = sizeof(SubListObject),\n" +" .tp_itemsize = 0,\n" +" .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE,\n" +" .tp_init = SubList_init,\n" +" .tp_methods = SubList_methods,\n" +"};\n" +"\n" +"static int\n" +"sublist_module_exec(PyObject *m)\n" +"{\n" +" SubListType.tp_base = &PyList_Type;\n" +" if (PyType_Ready(&SubListType) < 0) {\n" +" return -1;\n" +" }\n" +"\n" +" if (PyModule_AddObjectRef(m, \"SubList\", (PyObject *) &SubListType) < " +"0) {\n" +" return -1;\n" +" }\n" +"\n" +" return 0;\n" +"}\n" +"\n" +"static PyModuleDef_Slot sublist_module_slots[] = {\n" +" {Py_mod_exec, sublist_module_exec},\n" +" {Py_mod_multiple_interpreters, " +"Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED},\n" +" {0, NULL}\n" +"};\n" +"\n" +"static PyModuleDef sublist_module = {\n" +" .m_base = PyModuleDef_HEAD_INIT,\n" +" .m_name = \"sublist\",\n" +" .m_doc = \"Example module that creates an extension type.\",\n" +" .m_size = 0,\n" +" .m_slots = sublist_module_slots,\n" +"};\n" +"\n" +"PyMODINIT_FUNC\n" +"PyInit_sublist(void)\n" +"{\n" +" return PyModuleDef_Init(&sublist_module);\n" +"}\n" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:843 +msgid "" +"As you can see, the source code closely resembles the :class:`!Custom` " +"examples in previous sections. We will break down the main differences " +"between them. ::" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:846 +msgid "" +"typedef struct {\n" +" PyListObject list;\n" +" int state;\n" +"} SubListObject;" +msgstr "" +"typedef struct {\n" +" PyListObject list;\n" +" int state;\n" +"} SubListObject;" + +#: ../../extending/newtypes_tutorial.rst:851 +msgid "" +"The primary difference for derived type objects is that the base type's " +"object structure must be the first value. The base type will already " +"include the :c:func:`PyObject_HEAD` at the beginning of its structure." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:855 +msgid "" +"When a Python object is a :class:`!SubList` instance, its ``PyObject *`` " +"pointer can be safely cast to both ``PyListObject *`` and ``SubListObject " +"*``::" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:858 +msgid "" +"static int\n" +"SubList_init(PyObject *op, PyObject *args, PyObject *kwds)\n" +"{\n" +" SubListObject *self = (SubListObject *) op;\n" +" if (PyList_Type.tp_init(op, args, kwds) < 0)\n" +" return -1;\n" +" self->state = 0;\n" +" return 0;\n" +"}" +msgstr "" +"static int\n" +"SubList_init(PyObject *op, PyObject *args, PyObject *kwds)\n" +"{\n" +" SubListObject *self = (SubListObject *) op;\n" +" if (PyList_Type.tp_init(op, args, kwds) < 0)\n" +" return -1;\n" +" self->state = 0;\n" +" return 0;\n" +"}" + +#: ../../extending/newtypes_tutorial.rst:868 +msgid "" +"We see above how to call through to the :meth:`~object.__init__` method of " +"the base type." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:871 +msgid "" +"This pattern is important when writing a type with " +"custom :c:member:`~PyTypeObject.tp_new` " +"and :c:member:`~PyTypeObject.tp_dealloc` members. " +"The :c:member:`~PyTypeObject.tp_new` handler should not actually create the " +"memory for the object with its :c:member:`~PyTypeObject.tp_alloc`, but let " +"the base class handle it by calling its own :c:member:`~PyTypeObject.tp_new`." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:877 +msgid "" +"The :c:type:`PyTypeObject` struct supports " +"a :c:member:`~PyTypeObject.tp_base` specifying the type's concrete base " +"class. Due to cross-platform compiler issues, you can't fill that field " +"directly with a reference to :c:type:`PyList_Type`; it should be done in " +"the :c:data:`Py_mod_exec` function::" +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:883 +msgid "" +"static int\n" +"sublist_module_exec(PyObject *m)\n" +"{\n" +" SubListType.tp_base = &PyList_Type;\n" +" if (PyType_Ready(&SubListType) < 0) {\n" +" return -1;\n" +" }\n" +"\n" +" if (PyModule_AddObjectRef(m, \"SubList\", (PyObject *) &SubListType) < " +"0) {\n" +" return -1;\n" +" }\n" +"\n" +" return 0;\n" +"}" +msgstr "" +"static int\n" +"sublist_module_exec(PyObject *m)\n" +"{\n" +" SubListType.tp_base = &PyList_Type;\n" +" if (PyType_Ready(&SubListType) < 0) {\n" +" return -1;\n" +" }\n" +"\n" +" if (PyModule_AddObjectRef(m, \"SubList\", (PyObject *) &SubListType) < " +"0) {\n" +" return -1;\n" +" }\n" +"\n" +" return 0;\n" +"}" + +#: ../../extending/newtypes_tutorial.rst:898 +msgid "" +"Before calling :c:func:`PyType_Ready`, the type structure must have " +"the :c:member:`~PyTypeObject.tp_base` slot filled in. When we are deriving " +"an existing type, it is not necessary to fill out " +"the :c:member:`~PyTypeObject.tp_alloc` slot with :c:func:`PyType_GenericNew` " +"-- the allocation function from the base type will be inherited." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:904 +msgid "" +"After that, calling :c:func:`PyType_Ready` and adding the type object to the " +"module is the same as with the basic :class:`!Custom` examples." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:909 +msgid "Footnotes" +msgstr "註腳" + +#: ../../extending/newtypes_tutorial.rst:910 +msgid "" +"This is true when we know that the object is a basic type, like a string or " +"a float." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:913 +msgid "" +"We relied on this in the :c:member:`~PyTypeObject.tp_dealloc` handler in " +"this example, because our type doesn't support garbage collection." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:916 +msgid "" +"We now know that the first and last members are strings, so perhaps we could " +"be less careful about decrementing their reference counts, however, we " +"accept instances of string subclasses. Even though deallocating normal " +"strings won't call back into our objects, we can't guarantee that " +"deallocating an instance of a string subclass won't call back into our " +"objects." +msgstr "" + +#: ../../extending/newtypes_tutorial.rst:922 +msgid "" +"Also, even with our attributes restricted to strings instances, the user " +"could pass arbitrary :class:`str` subclasses and therefore still create " +"reference cycles." +msgstr "" diff --git a/extending/windows.po b/extending/windows.po index 39a4c461b1..a22f2ec43a 100644 --- a/extending/windows.po +++ b/extending/windows.po @@ -1,238 +1,238 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: 2015-12-09 17:51+0000\n" -"Last-Translator: Liang-Bo Wang \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" - -#: ../../extending/windows.rst:8 -msgid "Building C and C++ Extensions on Windows" -msgstr "建置 Windows 上的 C 和 C++ 擴充" - -#: ../../extending/windows.rst:10 -msgid "" -"This chapter briefly explains how to create a Windows extension module for " -"Python using Microsoft Visual C++, and follows with more detailed background " -"information on how it works. The explanatory material is useful for both " -"the Windows programmer learning to build Python extensions and the Unix " -"programmer interested in producing software which can be successfully built " -"on both Unix and Windows." -msgstr "" - -#: ../../extending/windows.rst:17 -msgid "" -"Module authors are encouraged to use the distutils approach for building " -"extension modules, instead of the one described in this section. You will " -"still need the C compiler that was used to build Python; typically Microsoft " -"Visual C++." -msgstr "" - -#: ../../extending/windows.rst:24 -msgid "" -"This chapter mentions a number of filenames that include an encoded Python " -"version number. These filenames are represented with the version number " -"shown as ``XY``; in practice, ``'X'`` will be the major version number and " -"``'Y'`` will be the minor version number of the Python release you're " -"working with. For example, if you are using Python 2.2.1, ``XY`` will " -"actually be ``22``." -msgstr "" - -#: ../../extending/windows.rst:34 -msgid "A Cookbook Approach" -msgstr "" - -#: ../../extending/windows.rst:36 -msgid "" -"There are two approaches to building extension modules on Windows, just as " -"there are on Unix: use the ``setuptools`` package to control the build " -"process, or do things manually. The setuptools approach works well for most " -"extensions; documentation on using ``setuptools`` to build and package " -"extension modules is available in :ref:`setuptools-index`. If you find you " -"really need to do things manually, it may be instructive to study the " -"project file for the :source:`winsound ` standard " -"library module." -msgstr "" - -#: ../../extending/windows.rst:48 -msgid "Differences Between Unix and Windows" -msgstr "" - -#: ../../extending/windows.rst:53 -msgid "" -"Unix and Windows use completely different paradigms for run-time loading of " -"code. Before you try to build a module that can be dynamically loaded, be " -"aware of how your system works." -msgstr "" - -#: ../../extending/windows.rst:57 -msgid "" -"In Unix, a shared object (:file:`.so`) file contains code to be used by the " -"program, and also the names of functions and data that it expects to find in " -"the program. When the file is joined to the program, all references to " -"those functions and data in the file's code are changed to point to the " -"actual locations in the program where the functions and data are placed in " -"memory. This is basically a link operation." -msgstr "" - -#: ../../extending/windows.rst:64 -msgid "" -"In Windows, a dynamic-link library (:file:`.dll`) file has no dangling " -"references. Instead, an access to functions or data goes through a lookup " -"table. So the DLL code does not have to be fixed up at runtime to refer to " -"the program's memory; instead, the code already uses the DLL's lookup table, " -"and the lookup table is modified at runtime to point to the functions and " -"data." -msgstr "" - -#: ../../extending/windows.rst:70 -msgid "" -"In Unix, there is only one type of library file (:file:`.a`) which contains " -"code from several object files (:file:`.o`). During the link step to create " -"a shared object file (:file:`.so`), the linker may find that it doesn't know " -"where an identifier is defined. The linker will look for it in the object " -"files in the libraries; if it finds it, it will include all the code from " -"that object file." -msgstr "" - -#: ../../extending/windows.rst:76 -msgid "" -"In Windows, there are two types of library, a static library and an import " -"library (both called :file:`.lib`). A static library is like a " -"Unix :file:`.a` file; it contains code to be included as necessary. An " -"import library is basically used only to reassure the linker that a certain " -"identifier is legal, and will be present in the program when the DLL is " -"loaded. So the linker uses the information from the import library to build " -"the lookup table for using identifiers that are not included in the DLL. " -"When an application or a DLL is linked, an import library may be generated, " -"which will need to be used for all future DLLs that depend on the symbols in " -"the application or DLL." -msgstr "" - -#: ../../extending/windows.rst:86 -msgid "" -"Suppose you are building two dynamic-load modules, B and C, which should " -"share another block of code A. On Unix, you would *not* pass :file:`A.a` to " -"the linker for :file:`B.so` and :file:`C.so`; that would cause it to be " -"included twice, so that B and C would each have their own copy. In Windows, " -"building :file:`A.dll` will also build :file:`A.lib`. You *do* " -"pass :file:`A.lib` to the linker for B and C. :file:`A.lib` does not " -"contain code; it just contains information which will be used at runtime to " -"access A's code." -msgstr "" - -#: ../../extending/windows.rst:94 -msgid "" -"In Windows, using an import library is sort of like using ``import spam``; " -"it gives you access to spam's names, but does not create a separate copy. " -"On Unix, linking with a library is more like ``from spam import *``; it does " -"create a separate copy." -msgstr "" - -#: ../../extending/windows.rst:101 -msgid "" -"Turn off the implicit, ``#pragma``-based linkage with the Python library, " -"performed inside CPython header files." -msgstr "" - -#: ../../extending/windows.rst:110 -msgid "Using DLLs in Practice" -msgstr "" - -#: ../../extending/windows.rst:115 -msgid "" -"Windows Python is built in Microsoft Visual C++; using other compilers may " -"or may not work. The rest of this section is MSVC++ specific." -msgstr "" - -#: ../../extending/windows.rst:118 -msgid "" -"When creating DLLs in Windows, you can use the CPython library in two ways:" -msgstr "" - -#: ../../extending/windows.rst:120 -msgid "" -"By default, inclusion of :file:`PC/pyconfig.h` directly or " -"via :file:`Python.h` triggers an implicit, configure-aware link with the " -"library. The header file chooses :file:`pythonXY_d.lib` for " -"Debug, :file:`pythonXY.lib` for Release, and :file:`pythonX.lib` for Release " -"with the :ref:`Limited API ` enabled." -msgstr "" - -#: ../../extending/windows.rst:126 ../../extending/windows.rst:144 -msgid "" -"To build two DLLs, spam and ni (which uses C functions found in spam), you " -"could use these commands::" -msgstr "" - -#: ../../extending/windows.rst:129 -msgid "" -"cl /LD /I/python/include spam.c\n" -"cl /LD /I/python/include ni.c spam.lib" -msgstr "" -"cl /LD /I/python/include spam.c\n" -"cl /LD /I/python/include ni.c spam.lib" - -#: ../../extending/windows.rst:132 -msgid "" -"The first command created three files: :file:`spam.obj`, :file:`spam.dll` " -"and :file:`spam.lib`. :file:`Spam.dll` does not contain any Python " -"functions (such as :c:func:`PyArg_ParseTuple`), but it does know how to find " -"the Python code thanks to the implicitly linked :file:`pythonXY.lib`." -msgstr "" - -#: ../../extending/windows.rst:137 ../../extending/windows.rst:155 -msgid "" -"The second command created :file:`ni.dll` (and :file:`.obj` " -"and :file:`.lib`), which knows how to find the necessary functions from " -"spam, and also from the Python executable." -msgstr "" - -#: ../../extending/windows.rst:141 -msgid "" -"Manually by defining :c:macro:`Py_NO_LINK_LIB` macro before " -"including :file:`Python.h`. You must pass :file:`pythonXY.lib` to the linker." -msgstr "" - -#: ../../extending/windows.rst:147 -msgid "" -"cl /LD /DPy_NO_LINK_LIB /I/python/include spam.c ../libs/pythonXY.lib\n" -"cl /LD /DPy_NO_LINK_LIB /I/python/include ni.c spam.lib ../libs/pythonXY.lib" -msgstr "" -"cl /LD /DPy_NO_LINK_LIB /I/python/include spam.c ../libs/pythonXY.lib\n" -"cl /LD /DPy_NO_LINK_LIB /I/python/include ni.c spam.lib ../libs/pythonXY.lib" - -#: ../../extending/windows.rst:150 -msgid "" -"The first command created three files: :file:`spam.obj`, :file:`spam.dll` " -"and :file:`spam.lib`. :file:`Spam.dll` does not contain any Python " -"functions (such as :c:func:`PyArg_ParseTuple`), but it does know how to find " -"the Python code thanks to :file:`pythonXY.lib`." -msgstr "" - -#: ../../extending/windows.rst:159 -msgid "" -"Not every identifier is exported to the lookup table. If you want any other " -"modules (including Python) to be able to see your identifiers, you have to " -"say ``_declspec(dllexport)``, as in ``void _declspec(dllexport) " -"initspam(void)`` or ``PyObject _declspec(dllexport) *NiGetSpamData(void)``." -msgstr "" - -#: ../../extending/windows.rst:164 -msgid "" -"Developer Studio will throw in a lot of import libraries that you do not " -"really need, adding about 100K to your executable. To get rid of them, use " -"the Project Settings dialog, Link tab, to specify *ignore default " -"libraries*. Add the correct :file:`msvcrt{xx}.lib` to the list of libraries." -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: 2015-12-09 17:51+0000\n" +"Last-Translator: Liang-Bo Wang \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" + +#: ../../extending/windows.rst:8 +msgid "Building C and C++ Extensions on Windows" +msgstr "建置 Windows 上的 C 和 C++ 擴充" + +#: ../../extending/windows.rst:10 +msgid "" +"This chapter briefly explains how to create a Windows extension module for " +"Python using Microsoft Visual C++, and follows with more detailed background " +"information on how it works. The explanatory material is useful for both " +"the Windows programmer learning to build Python extensions and the Unix " +"programmer interested in producing software which can be successfully built " +"on both Unix and Windows." +msgstr "" + +#: ../../extending/windows.rst:17 +msgid "" +"Module authors are encouraged to use the distutils approach for building " +"extension modules, instead of the one described in this section. You will " +"still need the C compiler that was used to build Python; typically Microsoft " +"Visual C++." +msgstr "" + +#: ../../extending/windows.rst:24 +msgid "" +"This chapter mentions a number of filenames that include an encoded Python " +"version number. These filenames are represented with the version number " +"shown as ``XY``; in practice, ``'X'`` will be the major version number and " +"``'Y'`` will be the minor version number of the Python release you're " +"working with. For example, if you are using Python 2.2.1, ``XY`` will " +"actually be ``22``." +msgstr "" + +#: ../../extending/windows.rst:34 +msgid "A Cookbook Approach" +msgstr "" + +#: ../../extending/windows.rst:36 +msgid "" +"There are two approaches to building extension modules on Windows, just as " +"there are on Unix: use the ``setuptools`` package to control the build " +"process, or do things manually. The setuptools approach works well for most " +"extensions; documentation on using ``setuptools`` to build and package " +"extension modules is available in :ref:`setuptools-index`. If you find you " +"really need to do things manually, it may be instructive to study the " +"project file for the :source:`winsound ` standard " +"library module." +msgstr "" + +#: ../../extending/windows.rst:48 +msgid "Differences Between Unix and Windows" +msgstr "" + +#: ../../extending/windows.rst:53 +msgid "" +"Unix and Windows use completely different paradigms for run-time loading of " +"code. Before you try to build a module that can be dynamically loaded, be " +"aware of how your system works." +msgstr "" + +#: ../../extending/windows.rst:57 +msgid "" +"In Unix, a shared object (:file:`.so`) file contains code to be used by the " +"program, and also the names of functions and data that it expects to find in " +"the program. When the file is joined to the program, all references to " +"those functions and data in the file's code are changed to point to the " +"actual locations in the program where the functions and data are placed in " +"memory. This is basically a link operation." +msgstr "" + +#: ../../extending/windows.rst:64 +msgid "" +"In Windows, a dynamic-link library (:file:`.dll`) file has no dangling " +"references. Instead, an access to functions or data goes through a lookup " +"table. So the DLL code does not have to be fixed up at runtime to refer to " +"the program's memory; instead, the code already uses the DLL's lookup table, " +"and the lookup table is modified at runtime to point to the functions and " +"data." +msgstr "" + +#: ../../extending/windows.rst:70 +msgid "" +"In Unix, there is only one type of library file (:file:`.a`) which contains " +"code from several object files (:file:`.o`). During the link step to create " +"a shared object file (:file:`.so`), the linker may find that it doesn't know " +"where an identifier is defined. The linker will look for it in the object " +"files in the libraries; if it finds it, it will include all the code from " +"that object file." +msgstr "" + +#: ../../extending/windows.rst:76 +msgid "" +"In Windows, there are two types of library, a static library and an import " +"library (both called :file:`.lib`). A static library is like a " +"Unix :file:`.a` file; it contains code to be included as necessary. An " +"import library is basically used only to reassure the linker that a certain " +"identifier is legal, and will be present in the program when the DLL is " +"loaded. So the linker uses the information from the import library to build " +"the lookup table for using identifiers that are not included in the DLL. " +"When an application or a DLL is linked, an import library may be generated, " +"which will need to be used for all future DLLs that depend on the symbols in " +"the application or DLL." +msgstr "" + +#: ../../extending/windows.rst:86 +msgid "" +"Suppose you are building two dynamic-load modules, B and C, which should " +"share another block of code A. On Unix, you would *not* pass :file:`A.a` to " +"the linker for :file:`B.so` and :file:`C.so`; that would cause it to be " +"included twice, so that B and C would each have their own copy. In Windows, " +"building :file:`A.dll` will also build :file:`A.lib`. You *do* " +"pass :file:`A.lib` to the linker for B and C. :file:`A.lib` does not " +"contain code; it just contains information which will be used at runtime to " +"access A's code." +msgstr "" + +#: ../../extending/windows.rst:94 +msgid "" +"In Windows, using an import library is sort of like using ``import spam``; " +"it gives you access to spam's names, but does not create a separate copy. " +"On Unix, linking with a library is more like ``from spam import *``; it does " +"create a separate copy." +msgstr "" + +#: ../../extending/windows.rst:101 +msgid "" +"Turn off the implicit, ``#pragma``-based linkage with the Python library, " +"performed inside CPython header files." +msgstr "" + +#: ../../extending/windows.rst:110 +msgid "Using DLLs in Practice" +msgstr "" + +#: ../../extending/windows.rst:115 +msgid "" +"Windows Python is built in Microsoft Visual C++; using other compilers may " +"or may not work. The rest of this section is MSVC++ specific." +msgstr "" + +#: ../../extending/windows.rst:118 +msgid "" +"When creating DLLs in Windows, you can use the CPython library in two ways:" +msgstr "" + +#: ../../extending/windows.rst:120 +msgid "" +"By default, inclusion of :file:`PC/pyconfig.h` directly or " +"via :file:`Python.h` triggers an implicit, configure-aware link with the " +"library. The header file chooses :file:`pythonXY_d.lib` for " +"Debug, :file:`pythonXY.lib` for Release, and :file:`pythonX.lib` for Release " +"with the :ref:`Limited API ` enabled." +msgstr "" + +#: ../../extending/windows.rst:126 ../../extending/windows.rst:144 +msgid "" +"To build two DLLs, spam and ni (which uses C functions found in spam), you " +"could use these commands::" +msgstr "" + +#: ../../extending/windows.rst:129 +msgid "" +"cl /LD /I/python/include spam.c\n" +"cl /LD /I/python/include ni.c spam.lib" +msgstr "" +"cl /LD /I/python/include spam.c\n" +"cl /LD /I/python/include ni.c spam.lib" + +#: ../../extending/windows.rst:132 +msgid "" +"The first command created three files: :file:`spam.obj`, :file:`spam.dll` " +"and :file:`spam.lib`. :file:`Spam.dll` does not contain any Python " +"functions (such as :c:func:`PyArg_ParseTuple`), but it does know how to find " +"the Python code thanks to the implicitly linked :file:`pythonXY.lib`." +msgstr "" + +#: ../../extending/windows.rst:137 ../../extending/windows.rst:155 +msgid "" +"The second command created :file:`ni.dll` (and :file:`.obj` " +"and :file:`.lib`), which knows how to find the necessary functions from " +"spam, and also from the Python executable." +msgstr "" + +#: ../../extending/windows.rst:141 +msgid "" +"Manually by defining :c:macro:`Py_NO_LINK_LIB` macro before " +"including :file:`Python.h`. You must pass :file:`pythonXY.lib` to the linker." +msgstr "" + +#: ../../extending/windows.rst:147 +msgid "" +"cl /LD /DPy_NO_LINK_LIB /I/python/include spam.c ../libs/pythonXY.lib\n" +"cl /LD /DPy_NO_LINK_LIB /I/python/include ni.c spam.lib ../libs/pythonXY.lib" +msgstr "" +"cl /LD /DPy_NO_LINK_LIB /I/python/include spam.c ../libs/pythonXY.lib\n" +"cl /LD /DPy_NO_LINK_LIB /I/python/include ni.c spam.lib ../libs/pythonXY.lib" + +#: ../../extending/windows.rst:150 +msgid "" +"The first command created three files: :file:`spam.obj`, :file:`spam.dll` " +"and :file:`spam.lib`. :file:`Spam.dll` does not contain any Python " +"functions (such as :c:func:`PyArg_ParseTuple`), but it does know how to find " +"the Python code thanks to :file:`pythonXY.lib`." +msgstr "" + +#: ../../extending/windows.rst:159 +msgid "" +"Not every identifier is exported to the lookup table. If you want any other " +"modules (including Python) to be able to see your identifiers, you have to " +"say ``_declspec(dllexport)``, as in ``void _declspec(dllexport) " +"initspam(void)`` or ``PyObject _declspec(dllexport) *NiGetSpamData(void)``." +msgstr "" + +#: ../../extending/windows.rst:164 +msgid "" +"Developer Studio will throw in a lot of import libraries that you do not " +"really need, adding about 100K to your executable. To get rid of them, use " +"the Project Settings dialog, Link tab, to specify *ignore default " +"libraries*. Add the correct :file:`msvcrt{xx}.lib` to the list of libraries." +msgstr "" diff --git a/faq/design.po b/faq/design.po index f5363b34de..a65117d02e 100644 --- a/faq/design.po +++ b/faq/design.po @@ -1,1569 +1,1569 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Ching-Lung Chuang, 2015 -# SiriusKoan, 2022 -# Steven Hsu , 2023 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: 2023-08-31 11:34+0800\n" -"Last-Translator: Steven Hsu \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" -"X-Generator: Poedit 3.3.2\n" -"X-Poedit-Bookmarks: -1,-1,-1,-1,-1,93,25,-1,-1,-1\n" - -#: ../../faq/design.rst:3 -msgid "Design and History FAQ" -msgstr "設計和歷史常見問答集" - -#: ../../faq/design.rst:6 -msgid "Contents" -msgstr "目錄" - -#: ../../faq/design.rst:11 -msgid "Why does Python use indentation for grouping of statements?" -msgstr "為什麼 Python 使用縮排將陳述式進行分組？" - -#: ../../faq/design.rst:13 -msgid "" -"Guido van Rossum believes that using indentation for grouping is extremely " -"elegant and contributes a lot to the clarity of the average Python program. " -"Most people learn to love this feature after a while." -msgstr "" -"Guido van Rossum 相信使用縮排來分組超級優雅，並且對提高一般 Python 程式的清晰" -"度有許多貢獻。許多人在學習一段時間之後就愛上了這個功能。" - -#: ../../faq/design.rst:17 -msgid "" -"Since there are no begin/end brackets there cannot be a disagreement between " -"grouping perceived by the parser and the human reader. Occasionally C " -"programmers will encounter a fragment of code like this::" -msgstr "" -"因為沒有開始/結束括號，因此剖析器和人類讀者感知到的分組就不存在分歧。偶爾 C " -"語言的程式設計師會遇到這樣的程式碼片段： ::" - -#: ../../faq/design.rst:21 -msgid "" -"if (x <= y)\n" -" x++;\n" -" y--;\n" -"z++;" -msgstr "" -"if (x <= y)\n" -" x++;\n" -" y--;\n" -"z++;" - -#: ../../faq/design.rst:26 -msgid "" -"Only the ``x++`` statement is executed if the condition is true, but the " -"indentation leads many to believe otherwise. Even experienced C programmers " -"will sometimes stare at it a long time wondering as to why ``y`` is being " -"decremented even for ``x > y``." -msgstr "" -"如果條件為真，只有 ``x++`` 陳述式會被執行，但縮排會讓很多人對他有不同的理解。" -"即使是資深的 C 語言開發者有時也會盯著他許久，思考為何即便 ``x > y``，但 " -"``y`` 還是減少了。" - -#: ../../faq/design.rst:31 -msgid "" -"Because there are no begin/end brackets, Python is much less prone to coding-" -"style conflicts. In C there are many different ways to place the braces. " -"After becoming used to reading and writing code using a particular style, it " -"is normal to feel somewhat uneasy when reading (or being required to write) " -"in a different one." -msgstr "" -"因為沒有開頭與結尾的括號，Python 比起其他語言會更不容易遇到程式碼風格的衝突。" -"在 C 語言中，有多種不同的方法來放置花括號。在習慣讀寫特定風格後，去讀（或是必" -"須去寫）另一種風格會覺得不太舒服。" - -#: ../../faq/design.rst:38 -msgid "" -"Many coding styles place begin/end brackets on a line by themselves. This " -"makes programs considerably longer and wastes valuable screen space, making " -"it harder to get a good overview of a program. Ideally, a function should " -"fit on one screen (say, 20--30 lines). 20 lines of Python can do a lot more " -"work than 20 lines of C. This is not solely due to the lack of begin/end " -"brackets -- the lack of declarations and the high-level data types are also " -"responsible -- but the indentation-based syntax certainly helps." -msgstr "" -"很多程式碼風格會把 begin/end 獨立放在一行。這會讓程式碼很長且浪費珍貴的螢幕空" -"間，要概覽程式時也變得較為困難。理想上來說，一個函式應該要佔一個螢幕（大概 " -"20 至 30 行）。20 行的 Python 程式碼比起 20 行的 C 程式碼可以做更多事。雖然沒" -"有開頭與結尾的括號並非單一原因（沒有變數宣告及高階的資料型別同樣有關），但縮" -"排式的語法確實給了幫助。" - -#: ../../faq/design.rst:48 -msgid "Why am I getting strange results with simple arithmetic operations?" -msgstr "為什麼我會從簡單的數學運算得到奇怪的結果？" - -#: ../../faq/design.rst:50 -msgid "See the next question." -msgstr "請見下一個問題。" - -#: ../../faq/design.rst:54 -msgid "Why are floating-point calculations so inaccurate?" -msgstr "為何浮點數運算如此不精確？" - -#: ../../faq/design.rst:56 -msgid "Users are often surprised by results like this::" -msgstr "使用者時常對這樣的結果感到驚訝： ::" - -#: ../../faq/design.rst:58 -msgid "" -">>> 1.2 - 1.0\n" -"0.19999999999999996" -msgstr "" -">>> 1.2 - 1.0\n" -"0.19999999999999996" - -#: ../../faq/design.rst:61 -msgid "" -"and think it is a bug in Python. It's not. This has little to do with " -"Python, and much more to do with how the underlying platform handles " -"floating-point numbers." -msgstr "" -"然後認為這是 Python 的 bug，但這並不是。這跟 Python 幾乎沒有關係，而是和底層" -"如何處理浮點數有關係。" - -#: ../../faq/design.rst:65 -msgid "" -"The :class:`float` type in CPython uses a C ``double`` for storage. " -"A :class:`float` object's value is stored in binary floating-point with a " -"fixed precision (typically 53 bits) and Python uses C operations, which in " -"turn rely on the hardware implementation in the processor, to perform " -"floating-point operations. This means that as far as floating-point " -"operations are concerned, Python behaves like many popular languages " -"including C and Java." -msgstr "" -"CPython 的 :class:`float` 型別使用了 C 的 ``double`` 型別來儲存。一" -"個 :class:`float` 物件的值會以固定的精度（通常為 53 位元）存為二進制浮點數，" -"Python 使用 C 來運算浮點數，而他的結果會依處理器中的硬體實作方式來決定。這表" -"示就浮點數運算來說，Python 和 C、Java 等很多受歡迎的語言有一樣的行為。" - -#: ../../faq/design.rst:72 -msgid "" -"Many numbers that can be written easily in decimal notation cannot be " -"expressed exactly in binary floating point. For example, after::" -msgstr "" -"很多數字可以簡單地寫成十進位表示，但卻無法簡單地以二進制浮點數表示。比方說，" -"在以下程式碼執行後： ::" - -#: ../../faq/design.rst:75 -msgid ">>> x = 1.2" -msgstr ">>> x = 1.2" - -#: ../../faq/design.rst:77 -msgid "" -"the value stored for ``x`` is a (very good) approximation to the decimal " -"value ``1.2``, but is not exactly equal to it. On a typical machine, the " -"actual stored value is::" -msgstr "" -"``x`` 裡的值是一個（很接近）1.2 的估計值，但並非精確地等於 1.2。以一般的電腦" -"來說，他實際儲存的值是： ::" - -#: ../../faq/design.rst:81 -msgid "1.0011001100110011001100110011001100110011001100110011 (binary)" -msgstr "1.0011001100110011001100110011001100110011001100110011 (binary)" - -#: ../../faq/design.rst:83 -msgid "which is exactly::" -msgstr "而這個值正是： ::" - -#: ../../faq/design.rst:85 -msgid "1.1999999999999999555910790149937383830547332763671875 (decimal)" -msgstr "1.1999999999999999555910790149937383830547332763671875 (decimal)" - -#: ../../faq/design.rst:87 -msgid "" -"The typical precision of 53 bits provides Python floats with 15--16 decimal " -"digits of accuracy." -msgstr "53 位元的精度讓 Python 可以有 15 至 16 小數位的準確度。" - -#: ../../faq/design.rst:90 -msgid "" -"For a fuller explanation, please see the :ref:`floating-point arithmetic " -"` chapter in the Python tutorial." -msgstr "" -"要更完全的解釋可以查閱在 Python 教學的\\ :ref:`浮點運算 `\\ 一" -"章。" - -#: ../../faq/design.rst:95 -msgid "Why are Python strings immutable?" -msgstr "為什麼 Python 字串不可變動？" - -#: ../../faq/design.rst:97 -msgid "There are several advantages." -msgstr "有許多優點。" - -#: ../../faq/design.rst:99 -msgid "" -"One is performance: knowing that a string is immutable means we can allocate " -"space for it at creation time, and the storage requirements are fixed and " -"unchanging. This is also one of the reasons for the distinction between " -"tuples and lists." -msgstr "" -"其一是效能：知道字串不可變動後，我們就可以在創造他的時候就分配好空間，而後他" -"的儲存空間需求就是固定不變的。這也是元組 (tuple) 和串列 (list) 相異的其中一個" -"原因。" - -#: ../../faq/design.rst:104 -msgid "" -"Another advantage is that strings in Python are considered as \"elemental\" " -"as numbers. No amount of activity will change the value 8 to anything else, " -"and in Python, no amount of activity will change the string \"eight\" to " -"anything else." -msgstr "" -"另一個優點是在 Python 中，字串和數字一樣「基本」。沒有任何行為會把 8 這個數值" -"改成其他數值；同理，在 Python 中也沒有任何行為會修改字串「eight」。" - -#: ../../faq/design.rst:112 -msgid "Why must 'self' be used explicitly in method definitions and calls?" -msgstr "為何「self」在方法 (method) 定義和呼叫時一定要明確使用？" - -#: ../../faq/design.rst:114 -msgid "" -"The idea was borrowed from Modula-3. It turns out to be very useful, for a " -"variety of reasons." -msgstr "此構想從 Modula-3 而來。因為許多原因，他可以說是非常實用。" - -#: ../../faq/design.rst:117 -msgid "" -"First, it's more obvious that you are using a method or instance attribute " -"instead of a local variable. Reading ``self.x`` or ``self.meth()`` makes it " -"absolutely clear that an instance variable or method is used even if you " -"don't know the class definition by heart. In C++, you can sort of tell by " -"the lack of a local variable declaration (assuming globals are rare or " -"easily recognizable) -- but in Python, there are no local variable " -"declarations, so you'd have to look up the class definition to be sure. " -"Some C++ and Java coding standards call for instance attributes to have an " -"``m_`` prefix, so this explicitness is still useful in those languages, too." -msgstr "" -"第一，這樣可以更明顯表現出你在用方法 (method) 或是實例 (instance) 的屬性，而" -"非一個區域變數。即使不知道類別 (class) 的定義，當看到 ``self.x`` 或 " -"``self.meth()``，就會很清楚地知道是正在使用實例的變數或是方法。在 C++ 裡，你" -"可以藉由沒有區域變數宣告來判斷這件事 ── 但在 Python 裡沒有區域變數宣告，所以" -"你必須去看類別的定義來確定。有些 C++ 和 Java 的程式碼規格要求要在實例屬性的名" -"稱加上前綴 ``m_``，所以這種明確性在那些語言也是很好用的。" - -#: ../../faq/design.rst:127 -msgid "" -"Second, it means that no special syntax is necessary if you want to " -"explicitly reference or call the method from a particular class. In C++, if " -"you want to use a method from a base class which is overridden in a derived " -"class, you have to use the ``::`` operator -- in Python you can write " -"``baseclass.methodname(self, )``. This is particularly " -"useful for :meth:`~object.__init__` methods, and in general in cases where a " -"derived class method wants to extend the base class method of the same name " -"and thus has to call the base class method somehow." -msgstr "" -"第二，當你想明確地使用或呼叫在某個類別裡的方法的時候，你不需要特殊的語法。在 " -"C++ 裡，如果你想用一個在繼承類別時被覆寫的基底類別方法，必須要用 ``::`` 運算" -"子 -- 但在 Python 裡，你可以直接寫成 ``baseclass.methodname(self, )``。這在 :meth:`~object.__init__` 方法很好用，特別是在一個繼承的類別要" -"擴充基底類別的方法而要呼叫他時。" - -#: ../../faq/design.rst:136 -msgid "" -"Finally, for instance variables it solves a syntactic problem with " -"assignment: since local variables in Python are (by definition!) those " -"variables to which a value is assigned in a function body (and that aren't " -"explicitly declared global), there has to be some way to tell the " -"interpreter that an assignment was meant to assign to an instance variable " -"instead of to a local variable, and it should preferably be syntactic (for " -"efficiency reasons). C++ does this through declarations, but Python doesn't " -"have declarations and it would be a pity having to introduce them just for " -"this purpose. Using the explicit ``self.var`` solves this nicely. " -"Similarly, for using instance variables, having to write ``self.var`` means " -"that references to unqualified names inside a method don't have to search " -"the instance's directories. To put it another way, local variables and " -"instance variables live in two different namespaces, and you need to tell " -"Python which namespace to use." -msgstr "" -"最後，他解決了關於實例變數指派的語法問題：因為區域變數在 Python 是（定義為）" -"在函式內被指派值的變數（且沒有被明確宣告成全域），所以會需要一個方法來告訴直" -"譯器這個指派運算是針對實例變數，而非針對區域變數，這在語法層面處理較好（為了" -"效率）。C++ 用宣告解決了這件事，但 Python 沒有，而為了這個原因而引入變數宣告" -"機制又略嫌浪費。但使用明確的 ``self.var`` 就可以把這個問題圓滿解決。同理，在" -"用實例變數的時候必須寫成 ``self.var`` 即代表對於在方法中不特定的名稱不需要去" -"看實例的內容。換句話說，區域變數和實例變數存在於兩個不同的命名空間 " -"(namespace)，而你需要告訴 Python 要使用哪一個。" - -#: ../../faq/design.rst:154 -msgid "Why can't I use an assignment in an expression?" -msgstr "為何我不能在運算式 (expression) 中使用指派運算？" - -#: ../../faq/design.rst:156 -msgid "Starting in Python 3.8, you can!" -msgstr "從 Python 3.8 開始，你可以這麼做了！" - -#: ../../faq/design.rst:158 -msgid "" -"Assignment expressions using the walrus operator ``:=`` assign a variable in " -"an expression::" -msgstr "指派運算式使用海象運算子 ``:=`` 來在運算式中指派變數值： ::" - -#: ../../faq/design.rst:161 -msgid "" -"while chunk := fp.read(200):\n" -" print(chunk)" -msgstr "" -"while chunk := fp.read(200):\n" -" print(chunk)" - -#: ../../faq/design.rst:164 -msgid "See :pep:`572` for more information." -msgstr "更多資訊請見 :pep:`572`。" - -#: ../../faq/design.rst:169 -msgid "" -"Why does Python use methods for some functionality (e.g. list.index()) but " -"functions for other (e.g. len(list))?" -msgstr "" -"為何 Python 對於一些功能實作使用方法（像是 list.index()），另一些使用函式（像" -"是 len(list)）？" - -#: ../../faq/design.rst:171 -msgid "As Guido said:" -msgstr "如 Guido 所說：" - -#: ../../faq/design.rst:173 -msgid "" -"(a) For some operations, prefix notation just reads better than postfix -- " -"prefix (and infix!) operations have a long tradition in mathematics which " -"likes notations where the visuals help the mathematician thinking about a " -"problem. Compare the easy with which we rewrite a formula like x*(a+b) into " -"x*a + x*b to the clumsiness of doing the same thing using a raw OO notation." -msgstr "" -"（一） 對一些運算來說，前綴寫法看起來會比後綴寫法好 ── 前綴（和中綴！）運算在" -"數學上有更久遠的傳統，這些符號在視覺上幫助數學家們更容易思考問題。想想把 " -"x*(a+b) 這種式子展開成 x*a + x*b 的簡單，再比較一下古老的圈圈符號記法的笨拙就" -"知道了。" - -#: ../../faq/design.rst:180 -msgid "" -"(b) When I read code that says len(x) I *know* that it is asking for the " -"length of something. This tells me two things: the result is an integer, and " -"the argument is some kind of container. To the contrary, when I read " -"x.len(), I have to already know that x is some kind of container " -"implementing an interface or inheriting from a class that has a standard " -"len(). Witness the confusion we occasionally have when a class that is not " -"implementing a mapping has a get() or keys() method, or something that isn't " -"a file has a write() method." -msgstr "" -"（二） 當我看到一段程式碼寫著 len(x)，我\\ *知道*\\ 他要找某個東西的長度。這" -"告訴了我兩件事：結果是一個整數、參數是某種容器。相對地，當我看到 x.len()，我" -"必須先知道 x 是某種容器，並實作了一個介面或是繼承了一個有標準 len() 的類別。" -"遇到一個沒有實作對映 (mapping) 的類別卻有 get() 或 keys() 方法，或是不是檔案" -"但卻有 write() 方法時，我們偶爾會覺得困惑。" - -#: ../../faq/design.rst:189 -msgid "https://mail.python.org/pipermail/python-3000/2006-November/004643.html" -msgstr "" -"https://mail.python.org/pipermail/python-3000/2006-November/004643.html" - -#: ../../faq/design.rst:193 -msgid "Why is join() a string method instead of a list or tuple method?" -msgstr "為何 join() 是字串方法而非串列 (list) 或元組 (tuple) 方法？" - -#: ../../faq/design.rst:195 -msgid "" -"Strings became much more like other standard types starting in Python 1.6, " -"when methods were added which give the same functionality that has always " -"been available using the functions of the string module. Most of these new " -"methods have been widely accepted, but the one which appears to make some " -"programmers feel uncomfortable is::" -msgstr "" -"自 Python 1.6 之後，字串變得很像其他標準的型別，也在此時，一些可以和字串模組" -"的函式有相同功能的方法也被加入。大多數的新方法都被廣泛接受，但有一個方法似乎" -"讓一些程式人員不舒服： ::" - -#: ../../faq/design.rst:201 -msgid "\", \".join(['1', '2', '4', '8', '16'])" -msgstr "\", \".join(['1', '2', '4', '8', '16'])" - -#: ../../faq/design.rst:203 -msgid "which gives the result::" -msgstr "結果是： ::" - -#: ../../faq/design.rst:205 -msgid "\"1, 2, 4, 8, 16\"" -msgstr "\"1, 2, 4, 8, 16\"" - -#: ../../faq/design.rst:207 -msgid "There are two common arguments against this usage." -msgstr "通常有兩個反對這個用法的論點。" - -#: ../../faq/design.rst:209 -msgid "" -"The first runs along the lines of: \"It looks really ugly using a method of " -"a string literal (string constant)\", to which the answer is that it might, " -"but a string literal is just a fixed value. If the methods are to be allowed " -"on names bound to strings there is no logical reason to make them " -"unavailable on literals." -msgstr "" -"第一項這麼說：「用字串文本 (string literal) （字串常數）看起來真的很醜」，也" -"許真的如此，但字串文本就只是一個固定值。如果方法可以用在值為字串的變數上，那" -"沒道理字串文本不能被使用。" - -#: ../../faq/design.rst:215 -msgid "" -"The second objection is typically cast as: \"I am really telling a sequence " -"to join its members together with a string constant\". Sadly, you aren't. " -"For some reason there seems to be much less difficulty with " -"having :meth:`~str.split` as a string method, since in that case it is easy " -"to see that ::" -msgstr "" -"第二個反對意見通常是：「我是在叫一個序列把它的成員用一個字串常數連接起來」。" -"但很遺憾地，你並不是在這樣做。因為某種原因，把 :meth:`~str.split` 當成字串方" -"法比較簡單，因為這樣我們可以輕易地看到： ::" - -#: ../../faq/design.rst:220 -msgid "\"1, 2, 4, 8, 16\".split(\", \")" -msgstr "\"1, 2, 4, 8, 16\".split(\", \")" - -#: ../../faq/design.rst:222 -msgid "" -"is an instruction to a string literal to return the substrings delimited by " -"the given separator (or, by default, arbitrary runs of white space)." -msgstr "" -"這是在叫一個字串文本回傳由指定的分隔符號（或是預設為空白）分出的子字串的指" -"令。" - -#: ../../faq/design.rst:225 -msgid "" -":meth:`~str.join` is a string method because in using it you are telling the " -"separator string to iterate over a sequence of strings and insert itself " -"between adjacent elements. This method can be used with any argument which " -"obeys the rules for sequence objects, including any new classes you might " -"define yourself. Similar methods exist for bytes and bytearray objects." -msgstr "" -":meth:`~str.join` 是一個字串方法，因為在用他的時候，你是告訴分隔字串去走遍整" -"個字串序列，並將自己插入到相鄰的兩項之間。這個方法的參數可以是任何符合序列規" -"則的物件，包括自己定義的新類別。在 bytes 和 bytearray 物件也有類似的方法可用。" - -#: ../../faq/design.rst:233 -msgid "How fast are exceptions?" -msgstr "例外處理有多快？" - -#: ../../faq/design.rst:235 -msgid "" -"A :keyword:`try`/:keyword:`except` block is extremely efficient if no " -"exceptions are raised. Actually catching an exception is expensive. In " -"versions of Python prior to 2.0 it was common to use this idiom::" -msgstr "" -"如果沒有例外被丟出，一個 :keyword:`try`/:keyword:`except` 區塊是非常有效率" -"的。事實上，抓捕例外要付出昂貴的代價。在 Python 2.0 以前，這樣使用是相當常見" -"的： ::" - -#: ../../faq/design.rst:240 -msgid "" -"try:\n" -" value = mydict[key]\n" -"except KeyError:\n" -" mydict[key] = getvalue(key)\n" -" value = mydict[key]" -msgstr "" -"try:\n" -" value = mydict[key]\n" -"except KeyError:\n" -" mydict[key] = getvalue(key)\n" -" value = mydict[key]" - -#: ../../faq/design.rst:246 -msgid "" -"This only made sense when you expected the dict to have the key almost all " -"the time. If that wasn't the case, you coded it like this::" -msgstr "" -"這只有在你預料這個字典大多數時候都有鍵的時候才合理。如果並非如此，你應該寫" -"成： ::" - -#: ../../faq/design.rst:249 -msgid "" -"if key in mydict:\n" -" value = mydict[key]\n" -"else:\n" -" value = mydict[key] = getvalue(key)" -msgstr "" -"if key in mydict:\n" -" value = mydict[key]\n" -"else:\n" -" value = mydict[key] = getvalue(key)" - -#: ../../faq/design.rst:254 -msgid "" -"For this specific case, you could also use ``value = dict.setdefault(key, " -"getvalue(key))``, but only if the ``getvalue()`` call is cheap enough " -"because it is evaluated in all cases." -msgstr "" -"單就這個情況來說，你也可以用 ``value = dict.setdefault(key, " -"getvalue(key))``，不過只有在 ``getvalue()`` 代價不大的時候才能用，畢竟他每次" -"都會被執行。" - -#: ../../faq/design.rst:260 -msgid "Why isn't there a switch or case statement in Python?" -msgstr "為什麼 Python 內沒有 switch 或 case 陳述式？" - -#: ../../faq/design.rst:262 -msgid "" -"In general, structured switch statements execute one block of code when an " -"expression has a particular value or set of values. Since Python 3.10 one " -"can easily match literal values, or constants within a namespace, with a " -"``match ... case`` statement. An older alternative is a sequence of ``if... " -"elif... elif... else``." -msgstr "" - -#: ../../faq/design.rst:268 -msgid "" -"For cases where you need to choose from a very large number of " -"possibilities, you can create a dictionary mapping case values to functions " -"to call. For example::" -msgstr "如果可能性很多，你可以用字典去對映要呼叫的函式。舉例來說： ::" - -#: ../../faq/design.rst:272 -msgid "" -"functions = {'a': function_1,\n" -" 'b': function_2,\n" -" 'c': self.method_1}\n" -"\n" -"func = functions[value]\n" -"func()" -msgstr "" -"if key in mydict:\n" -" value = mydict[key]\n" -"else:\n" -" value = mydict[key] = getvalue(key)" - -#: ../../faq/design.rst:279 -msgid "" -"For calling methods on objects, you can simplify yet further by using " -"the :func:`getattr` built-in to retrieve methods with a particular name::" -msgstr "" -"對於呼叫物件裡的方法，你可以利用內建用來找尋特定方法的函式 :func:`getattr` 來" -"做進一步的簡化： ::" - -#: ../../faq/design.rst:282 -msgid "" -"class MyVisitor:\n" -" def visit_a(self):\n" -" ...\n" -"\n" -" def dispatch(self, value):\n" -" method_name = 'visit_' + str(value)\n" -" method = getattr(self, method_name)\n" -" method()" -msgstr "" -"class MyVisitor:\n" -" def visit_a(self):\n" -" ...\n" -"\n" -" def dispatch(self, value):\n" -" method_name = 'visit_' + str(value)\n" -" method = getattr(self, method_name)\n" -" method()" - -#: ../../faq/design.rst:291 -msgid "" -"It's suggested that you use a prefix for the method names, such as " -"``visit_`` in this example. Without such a prefix, if values are coming " -"from an untrusted source, an attacker would be able to call any method on " -"your object." -msgstr "" -"我們建議在方法名稱加上前綴，以這個例子來說是 像是 ``visit_``。沒有前綴的話，" -"一旦收到從不信任來源的值，攻擊者便可以隨意呼叫在你的專案內的方法。" - -#: ../../faq/design.rst:295 -msgid "" -"Imitating switch with fallthrough, as with C's switch-case-default, is " -"possible, much harder, and less needed." -msgstr "" - -#: ../../faq/design.rst:300 -msgid "" -"Can't you emulate threads in the interpreter instead of relying on an OS-" -"specific thread implementation?" -msgstr "為何不能在直譯器上模擬執行緒，而要使用作業系統的特定實作方式？" - -#: ../../faq/design.rst:302 -msgid "" -"Answer 1: Unfortunately, the interpreter pushes at least one C stack frame " -"for each Python stack frame. Also, extensions can call back into Python at " -"almost random moments. Therefore, a complete threads implementation " -"requires thread support for C." -msgstr "" -"答案一：很不幸地，直譯器對每個 Python 的堆疊框 (stack frame) 會推至少一個 C " -"的堆疊框。同時，擴充套件可以隨時呼叫 Python，因此完整的實作必須要支援 C 的執" -"行緒。" - -#: ../../faq/design.rst:307 -msgid "" -"Answer 2: Fortunately, there is `Stackless Python `_, which has a completely redesigned " -"interpreter loop that avoids the C stack." -msgstr "" -"答案二：幸運地，`無堆疊 (Stackless) Python `_ 完全重新設計了直譯器迴圈，並避免了 C 堆疊。" - -#: ../../faq/design.rst:312 -msgid "Why can't lambda expressions contain statements?" -msgstr "為何 lambda 運算式不能包含陳述式？" - -#: ../../faq/design.rst:314 -msgid "" -"Python lambda expressions cannot contain statements because Python's " -"syntactic framework can't handle statements nested inside expressions. " -"However, in Python, this is not a serious problem. Unlike lambda forms in " -"other languages, where they add functionality, Python lambdas are only a " -"shorthand notation if you're too lazy to define a function." -msgstr "" -"Python 的 lambda 運算式不能包含陳述式是因為 Python 的語法框架無法處理包在運算" -"式中的陳述式。然而，在 Python 裡這並不是一個嚴重的問題。不像在其他語言中有獨" -"立功能的 lambda，Python 的 lambda 只是一個在你懶得定義函式時可用的一個簡寫表" -"達法。" - -#: ../../faq/design.rst:320 -msgid "" -"Functions are already first class objects in Python, and can be declared in " -"a local scope. Therefore the only advantage of using a lambda instead of a " -"locally defined function is that you don't need to invent a name for the " -"function -- but that's just a local variable to which the function object " -"(which is exactly the same type of object that a lambda expression yields) " -"is assigned!" -msgstr "" -"函式已經是 Python 裡的一級物件 (first class objects)，而且可以在區域範圍內被" -"宣告。因此唯一用 lambda 而非區域性的函式的優點就是你不需要多想一個函式名稱 — " -"但這樣就會是一個區域變數被指定成函式物件（和 lambda 運算式的結果同類）！" - -#: ../../faq/design.rst:328 -msgid "Can Python be compiled to machine code, C or some other language?" -msgstr "Python 可以被編譯成機器語言、C 語言或其他種語言嗎？" - -#: ../../faq/design.rst:330 -msgid "" -"`Cython `_ compiles a modified version of Python with " -"optional annotations into C extensions. `Nuitka `_ is " -"an up-and-coming compiler of Python into C++ code, aiming to support the " -"full Python language." -msgstr "" -"`Cython `_ 可以編譯一個調整過有選擇性註解的 Python 版" -"本。`Nuitka `_ 是一個有潛力編譯器，可以把 Python 編譯成 " -"C++，他的目標是支援完整的 Python 語言。" - -#: ../../faq/design.rst:337 -msgid "How does Python manage memory?" -msgstr "Python 如何管理記憶體？" - -#: ../../faq/design.rst:339 -msgid "" -"The details of Python memory management depend on the implementation. The " -"standard implementation of Python, :term:`CPython`, uses reference counting " -"to detect inaccessible objects, and another mechanism to collect reference " -"cycles, periodically executing a cycle detection algorithm which looks for " -"inaccessible cycles and deletes the objects involved. The :mod:`gc` module " -"provides functions to perform a garbage collection, obtain debugging " -"statistics, and tune the collector's parameters." -msgstr "" -"Python 記憶體管理的細節取決於實作。Python 的標準實作 :term:`CPython` 使用參照" -"計次 (reference counting) 來偵測不再被存取的物件，並用另一個機制來收集參照循" -"環 (reference cycle)、定期執行循環偵測演算法來找不再使用的循環並刪除相關物" -"件。 :mod:`gc` 模組提供了可以執行垃圾收集、抓取除錯統計數據和調整收集器參數的" -"函式。" - -#: ../../faq/design.rst:347 -msgid "" -"Other implementations (such as `Jython `_ or `PyPy " -"`_), however, can rely on a different mechanism such as a " -"full-blown garbage collector. This difference can cause some subtle porting " -"problems if your Python code depends on the behavior of the reference " -"counting implementation." -msgstr "" -"然而，在其他實作（像是 `Jython `_ 或 `PyPy `_）中，會使用像是成熟的垃圾收集器等不同機制。如果你的 Python 程式碼" -"的表現取決於參照計次的實作，這個相異處會導致一些微小的移植問題。" - -#: ../../faq/design.rst:353 -msgid "" -"In some Python implementations, the following code (which is fine in " -"CPython) will probably run out of file descriptors::" -msgstr "" -"在一些 Python 實作中，下面這段程式碼（在 CPython 可以正常運作）可能會把檔案描" -"述子 (file descriptor) 用盡： ::" - -#: ../../faq/design.rst:356 -msgid "" -"for file in very_long_list_of_files:\n" -" f = open(file)\n" -" c = f.read(1)" -msgstr "" -"for file in very_long_list_of_files:\n" -" f = open(file)\n" -" c = f.read(1)" - -#: ../../faq/design.rst:360 -msgid "" -"Indeed, using CPython's reference counting and destructor scheme, each new " -"assignment to ``f`` closes the previous file. With a traditional GC, " -"however, those file objects will only get collected (and closed) at varying " -"and possibly long intervals." -msgstr "" -"實際上，使用 CPython 的參照計次和解構方案 (destructor scheme)，每個對 ``f`` " -"的新指派都會關閉前面打開的檔案。然而用傳統的垃圾回收 (GC) 的話，這些檔案物件" -"只會在不固定且有可能很長的時間後被收集（並關閉）。" - -#: ../../faq/design.rst:365 -msgid "" -"If you want to write code that will work with any Python implementation, you " -"should explicitly close the file or use the :keyword:`with` statement; this " -"will work regardless of memory management scheme::" -msgstr "" -"如果你希望你的程式碼在任何 Python 實作版本中都可以運作，那你應該清楚地關閉檔" -"案或是使用 :keyword:`with` 陳述式，如此一來，不用管記憶體管理的方法，他也會正" -"常運作： ::" - -#: ../../faq/design.rst:369 -msgid "" -"for file in very_long_list_of_files:\n" -" with open(file) as f:\n" -" c = f.read(1)" -msgstr "" -"for file in very_long_list_of_files:\n" -" with open(file) as f:\n" -" c = f.read(1)" - -#: ../../faq/design.rst:375 -msgid "Why doesn't CPython use a more traditional garbage collection scheme?" -msgstr "為何 CPython 不使用更多傳統的垃圾回收機制？" - -#: ../../faq/design.rst:377 -msgid "" -"For one thing, this is not a C standard feature and hence it's not portable. " -"(Yes, we know about the Boehm GC library. It has bits of assembler code for " -"*most* common platforms, not for all of them, and although it is mostly " -"transparent, it isn't completely transparent; patches are required to get " -"Python to work with it.)" -msgstr "" -"第一，這並不是 C 的標準功能，因此他的可攜性低。（對，我們知道 Boehm GC 函式" -"庫。他有可相容於\\ *大多數*\\ 平台的組合語言程式碼，但依然不是全部，而即便它" -"大多數是通透的，也並不完全，要讓它跟 Python 相容還是需要做一些修補。）" - -#: ../../faq/design.rst:383 -msgid "" -"Traditional GC also becomes a problem when Python is embedded into other " -"applications. While in a standalone Python it's fine to replace the " -"standard ``malloc()`` and ``free()`` with versions provided by the GC " -"library, an application embedding Python may want to have its *own* " -"substitute for ``malloc()`` and ``free()``, and may not want Python's. " -"Right now, CPython works with anything that implements ``malloc()`` and " -"``free()`` properly." -msgstr "" -"傳統的垃圾收集 (GC) 在 Python 被嵌入其他應用程式時也成了一個問題。在獨立的 " -"Python 程式裡當然可以把標準的 ``malloc()`` 和 ``free()`` 換成 GC 函式庫提供的" -"其他版本；但一個嵌著 Python 的應用程式可能想用\\ *自己*\\ 的 malloc() 和 " -"free() 替代品，而不是用 Python 的。以現在來說，CPython 和實作 malloc() 和 " -"free() 的程式相處融洽。" - -#: ../../faq/design.rst:392 -msgid "Why isn't all memory freed when CPython exits?" -msgstr "當 CPython 結束時，為何所有的記憶體不會被釋放？" - -#: ../../faq/design.rst:394 -msgid "" -"Objects referenced from the global namespaces of Python modules are not " -"always deallocated when Python exits. This may happen if there are circular " -"references. There are also certain bits of memory that are allocated by the " -"C library that are impossible to free (e.g. a tool like Purify will complain " -"about these). Python is, however, aggressive about cleaning up memory on " -"exit and does try to destroy every single object." -msgstr "" -"當離開 Python 時，從 Python 模組的全域命名空間來的物件並非總是會被釋放。在有" -"循環引用的時候，這可能會發生。有些記憶體是被 C 函式庫取用的，他們不可能被釋放" -"（例如：像是 Purify 之類的工具會抱怨）。然而，Python 在關閉的時候會積極清理記" -"憶體並嘗試刪除每個物件。" - -#: ../../faq/design.rst:401 -msgid "" -"If you want to force Python to delete certain things on deallocation use " -"the :mod:`atexit` module to run a function that will force those deletions." -msgstr "" -"如果你想要強迫 Python 在釋放記憶體時刪除特定的東西，你可以用 :mod:`atexit` 模" -"組來執行會強制刪除的函式。" - -#: ../../faq/design.rst:406 -msgid "Why are there separate tuple and list data types?" -msgstr "為何要把元組 (tuple) 和串列 (list) 分成兩個資料型別？" - -#: ../../faq/design.rst:408 -msgid "" -"Lists and tuples, while similar in many respects, are generally used in " -"fundamentally different ways. Tuples can be thought of as being similar to " -"Pascal ``records`` or C ``structs``; they're small collections of related " -"data which may be of different types which are operated on as a group. For " -"example, a Cartesian coordinate is appropriately represented as a tuple of " -"two or three numbers." -msgstr "" -"串列和元組在很多方面相當相似，但通常用在完全不同的地方。元組可以想成 Pascal " -"的 ``record`` 或是 C 的 ``struct``，是一小群相關聯但可能是不同型別的資料集" -"合，以一組為單位進行操作。舉例來說，一個笛卡兒坐標系可以適當地表示成一個有二" -"或三個值的元組。" - -#: ../../faq/design.rst:415 -msgid "" -"Lists, on the other hand, are more like arrays in other languages. They " -"tend to hold a varying number of objects all of which have the same type and " -"which are operated on one-by-one. For example, :func:`os.listdir('.') " -"` returns a list of strings representing the files in the " -"current directory. Functions which operate on this output would generally " -"not break if you added another file or two to the directory." -msgstr "" -"另一方面，串列更像是其他語言的陣列 (array)。他可以有不固定個同類別物件，且為" -"逐項操作。舉例來說，:func:`os.listdir('.') ` 回傳當下目錄裡的檔" -"案，以包含字串的串列表示。如果你新增了幾個檔案到這個目錄，一般來說操作結果的" -"函式也會正常運作。" - -#: ../../faq/design.rst:423 -msgid "" -"Tuples are immutable, meaning that once a tuple has been created, you can't " -"replace any of its elements with a new value. Lists are mutable, meaning " -"that you can always change a list's elements. Only immutable elements can " -"be used as dictionary keys, and hence only tuples and not lists can be used " -"as keys." -msgstr "" -"元組則是不可變的，代表一旦元組被建立，你就不能夠改變裡面的任何一個值。而串列" -"可變，所以你可以改變裡面的元素。只有不可變的元素可以成為字典的鍵，所以只能把" -"元組當成鍵，而串列則不行。" - -#: ../../faq/design.rst:430 -msgid "How are lists implemented in CPython?" -msgstr "串列 (list) 在 CPython 中是怎麼實作的？" - -#: ../../faq/design.rst:432 -msgid "" -"CPython's lists are really variable-length arrays, not Lisp-style linked " -"lists. The implementation uses a contiguous array of references to other " -"objects, and keeps a pointer to this array and the array's length in a list " -"head structure." -msgstr "" -"CPython 的串列 (list) 事實上是可變長度的陣列 (array)，而不是像 Lisp 語言的鏈" -"接串列 (linked list)。實作上，他是一個連續的物件參照 (reference) 陣列，並把指" -"向此陣列的指標 (pointer) 和陣列長度存在串列的標頭結構內。" - -#: ../../faq/design.rst:436 -msgid "" -"This makes indexing a list ``a[i]`` an operation whose cost is independent " -"of the size of the list or the value of the index." -msgstr "因此，用索引來找串列特定項 ``a[i]`` 的代價和串列大小或是索引值無關。" - -#: ../../faq/design.rst:439 -msgid "" -"When items are appended or inserted, the array of references is resized. " -"Some cleverness is applied to improve the performance of appending items " -"repeatedly; when the array must be grown, some extra space is allocated so " -"the next few times don't require an actual resize." -msgstr "" -"當新物件被新增或插入時，陣列會被調整大小。為了改善多次加入物件的效率，我們有" -"用一些巧妙的方法，當陣列必須變大時，會多收集一些額外的空間，接下來幾次新增時" -"就不需要再調整大小了。" - -#: ../../faq/design.rst:446 -msgid "How are dictionaries implemented in CPython?" -msgstr "字典 (dictionaries) 在 CPython 中是怎麼實作的？" - -#: ../../faq/design.rst:448 -msgid "" -"CPython's dictionaries are implemented as resizable hash tables. Compared " -"to B-trees, this gives better performance for lookup (the most common " -"operation by far) under most circumstances, and the implementation is " -"simpler." -msgstr "" -"CPython 的字典是用可調整大小的雜湊表 (hash table) 實作的。比起 B 樹 (B-" -"tree)，在搜尋（目前為止最常見的操作）方面有更好的表現，實作上也較為簡單。" - -#: ../../faq/design.rst:452 -msgid "" -"Dictionaries work by computing a hash code for each key stored in the " -"dictionary using the :func:`hash` built-in function. The hash code varies " -"widely depending on the key and a per-process seed; for example, " -"``'Python'`` could hash to ``-539294296`` while ``'python'``, a string that " -"differs by a single bit, could hash to ``1142331976``. The hash code is " -"then used to calculate a location in an internal array where the value will " -"be stored. Assuming that you're storing keys that all have different hash " -"values, this means that dictionaries take constant time -- *O*\\ (1), in Big-" -"O notation -- to retrieve a key." -msgstr "" -"字典利用內建 :func:`hash` 函式，對每個鍵做雜湊計算。雜湊結果依據鍵的值和個別" -"執行緒 (processes) 的種子而有相當大的差距。例如，``'Python'`` 的雜湊是 " -"``-539294296``，而只差一個字的 ``'python'`` 則是 ``1142331976``。雜湊結果接著" -"被用來計算值在內部陣列儲存的位置。假設你存的鍵都有不同的雜湊值，那字典只需要" -"常數時間 — 用大 O 表示法 (Big-O notation) 就是 *O*\\ (1) — 來找任意一個鍵。" - -#: ../../faq/design.rst:463 -msgid "Why must dictionary keys be immutable?" -msgstr "為何字典的鍵一定是不可變的？" - -#: ../../faq/design.rst:465 -msgid "" -"The hash table implementation of dictionaries uses a hash value calculated " -"from the key value to find the key. If the key were a mutable object, its " -"value could change, and thus its hash could also change. But since whoever " -"changes the key object can't tell that it was being used as a dictionary " -"key, it can't move the entry around in the dictionary. Then, when you try " -"to look up the same object in the dictionary it won't be found because its " -"hash value is different. If you tried to look up the old value it wouldn't " -"be found either, because the value of the object found in that hash bin " -"would be different." -msgstr "" -"實作字典用的雜湊表是根據鍵的值做計算從而找到鍵的。如果鍵可變的話，他的值就可" -"以改變，則雜湊的結果也會一起變動。但改變鍵的物件的人無從得知他被用來當成字典" -"的鍵，所以無法修改字典的內容。然後，當你嘗試在字典中尋找這個物件時，因為雜湊" -"值不同的緣故，你找不到他。而如果你嘗試用舊的值去尋找，也一樣找不到，因為他的" -"雜湊結果和原先物件不同。" - -#: ../../faq/design.rst:474 -msgid "" -"If you want a dictionary indexed with a list, simply convert the list to a " -"tuple first; the function ``tuple(L)`` creates a tuple with the same entries " -"as the list ``L``. Tuples are immutable and can therefore be used as " -"dictionary keys." -msgstr "" -"如果你想要用串列作為字典的索引，把他轉換成元組即可。``tuple(L)`` 函式會建立一" -"個和串列 ``L`` 一樣內容的元組。而元組是不可變的，所以可以用來當成字典的鍵。" - -#: ../../faq/design.rst:478 -msgid "Some unacceptable solutions that have been proposed:" -msgstr "也有人提出一些不能接受的方法：" - -#: ../../faq/design.rst:480 -msgid "" -"Hash lists by their address (object ID). This doesn't work because if you " -"construct a new list with the same value it won't be found; e.g.::" -msgstr "" -"用串列的記憶體位址（物件 id）來雜湊。這不會成功，因為你如果用同樣的值建立一個" -"新的串列，是找不到的。舉例來說： ::" - -#: ../../faq/design.rst:483 -msgid "" -"mydict = {[1, 2]: '12'}\n" -"print(mydict[[1, 2]])" -msgstr "" -"mydict = {[1, 2]: '12'}\n" -"print(mydict[[1, 2]])" - -#: ../../faq/design.rst:486 -msgid "" -"would raise a :exc:`KeyError` exception because the id of the ``[1, 2]`` " -"used in the second line differs from that in the first line. In other " -"words, dictionary keys should be compared using ``==``, not " -"using :keyword:`is`." -msgstr "" -"這將會導致 :exc:`KeyError` 例外，因為 ``[1, 2]`` 的 id 在第一行和第二行是不同" -"的。換句話說，字典的鍵應該要用 ``==`` 來做比較，而不是用 :keyword:`is`。" - -#: ../../faq/design.rst:490 -msgid "" -"Make a copy when using a list as a key. This doesn't work because the list, " -"being a mutable object, could contain a reference to itself, and then the " -"copying code would run into an infinite loop." -msgstr "" -"複製一個串列作為鍵。這一樣不會成功，因為串列是可變的，他可以包含自己的參照，" -"所以複製會形成一個無窮迴圈。" - -#: ../../faq/design.rst:494 -msgid "" -"Allow lists as keys but tell the user not to modify them. This would allow " -"a class of hard-to-track bugs in programs when you forgot or modified a list " -"by accident. It also invalidates an important invariant of dictionaries: " -"every value in ``d.keys()`` is usable as a key of the dictionary." -msgstr "" -"允許串列作為鍵，但告訴使用者不要更動他。當你不小心忘記或是更動了這個串列，會" -"產生一種難以追蹤的 bug。他同時也違背了一項字典的重要定則：在 ``d.keys()`` 的" -"每個值都可以當成字典的鍵。" - -#: ../../faq/design.rst:499 -msgid "" -"Mark lists as read-only once they are used as a dictionary key. The problem " -"is that it's not just the top-level object that could change its value; you " -"could use a tuple containing a list as a key. Entering anything as a key " -"into a dictionary would require marking all objects reachable from there as " -"read-only -- and again, self-referential objects could cause an infinite " -"loop." -msgstr "" -"一旦串列被當成鍵，把他標記成只能讀取。問題是，這不只要避免最上層的物件改變" -"值，就像用元組包含串列來做為鍵。把一個物件當成鍵，需要將從他開始可以接觸到的" -"所有物件都標記成只能讀取 — 所以再一次，自己參照自己的物件會導致無窮迴圈。" - -#: ../../faq/design.rst:505 -msgid "" -"There is a trick to get around this if you need to, but use it at your own " -"risk: You can wrap a mutable structure inside a class instance which has " -"both a :meth:`~object.__eq__` and a :meth:`~object.__hash__` method. You " -"must then make sure that the hash value for all such wrapper objects that " -"reside in a dictionary (or other hash based structure), remain fixed while " -"the object is in the dictionary (or other structure). ::" -msgstr "" -"如果你需要的話，這裡有個小技巧可以幫你，但請自己承擔風險：你可以把一個可變物" -"件包裝進一個有 :meth:`~object.__eq__` 和 :meth:`~object.__hash__` 方法的類別" -"實例。只要這種包裝物件還存在於字典（或其他類似結構）中，你就必須確定在字典" -"（或其他用雜湊為基底的結構）中他們的雜湊值會保持恆定。 ::" - -#: ../../faq/design.rst:513 -msgid "" -"class ListWrapper:\n" -" def __init__(self, the_list):\n" -" self.the_list = the_list\n" -"\n" -" def __eq__(self, other):\n" -" return self.the_list == other.the_list\n" -"\n" -" def __hash__(self):\n" -" l = self.the_list\n" -" result = 98767 - len(l)*555\n" -" for i, el in enumerate(l):\n" -" try:\n" -" result = result + (hash(el) % 9999999) * 1001 + i\n" -" except Exception:\n" -" result = (result % 7777777) + i * 333\n" -" return result" -msgstr "" -"class ListWrapper:\n" -" def __init__(self, the_list):\n" -" self.the_list = the_list\n" -"\n" -" def __eq__(self, other):\n" -" return self.the_list == other.the_list\n" -"\n" -" def __hash__(self):\n" -" l = self.the_list\n" -" result = 98767 - len(l)*555\n" -" for i, el in enumerate(l):\n" -" try:\n" -" result = result + (hash(el) % 9999999) * 1001 + i\n" -" except Exception:\n" -" result = (result % 7777777) + i * 333\n" -" return result" - -#: ../../faq/design.rst:530 -msgid "" -"Note that the hash computation is complicated by the possibility that some " -"members of the list may be unhashable and also by the possibility of " -"arithmetic overflow." -msgstr "" -"請注意，雜湊的計算可能變得複雜，因為有串列成員不可雜湊 (unhashable) 和算術溢" -"位的可能性。" - -#: ../../faq/design.rst:534 -msgid "" -"Furthermore it must always be the case that if ``o1 == o2`` (ie " -"``o1.__eq__(o2) is True``) then ``hash(o1) == hash(o2)`` (ie, " -"``o1.__hash__() == o2.__hash__()``), regardless of whether the object is in " -"a dictionary or not. If you fail to meet these restrictions dictionaries " -"and other hash based structures will misbehave." -msgstr "" -"此外，不管物件是否在字典中，如果 ``o1 == o2``\\ （即 ``o1.__eq__(o2) is " -"True``），則 ``hash(o1) == hash(o2)``\\ （即 ``o1.__hash__() == " -"o2.__hash__()``），這個事實必須要成立。如果無法滿足這項限制，那字典和其他用雜" -"湊為基底的結構會出現不正常的行為。" - -#: ../../faq/design.rst:539 -msgid "" -"In the case of :class:`!ListWrapper`, whenever the wrapper object is in a " -"dictionary the wrapped list must not change to avoid anomalies. Don't do " -"this unless you are prepared to think hard about the requirements and the " -"consequences of not meeting them correctly. Consider yourself warned." -msgstr "" -"至於 :class:`!ListWrapper`，只要這個包裝過的物件在字典中，裡面的串列就不能改" -"變以避免不正常的事情發生。除非你已經謹慎思考過你的需求和無法滿足條件的後果，" -"不然請不要這麼做。請自行注意。" - -#: ../../faq/design.rst:546 -msgid "Why doesn't list.sort() return the sorted list?" -msgstr "為何 list.sort() 不是回傳排序過的串列？" - -#: ../../faq/design.rst:548 -msgid "" -"In situations where performance matters, making a copy of the list just to " -"sort it would be wasteful. Therefore, :meth:`list.sort` sorts the list in " -"place. In order to remind you of that fact, it does not return the sorted " -"list. This way, you won't be fooled into accidentally overwriting a list " -"when you need a sorted copy but also need to keep the unsorted version " -"around." -msgstr "" -"在重視效能的情況下，把串列複製一份有些浪費。因此，:meth:`list.sort` 直接在串" -"列裡做排序。為了提醒你這件事，他不會回傳排序過的串列。這樣一來，當你需要排序" -"過和未排序過的串列時，你就不會被誤導而不小心覆蓋掉串列。" - -#: ../../faq/design.rst:554 -msgid "" -"If you want to return a new list, use the built-in :func:`sorted` function " -"instead. This function creates a new list from a provided iterable, sorts " -"it and returns it. For example, here's how to iterate over the keys of a " -"dictionary in sorted order::" -msgstr "" -"如果你想要他回傳新的串列，那可以改用內建的 :func:`sorted`。他會用提供的可疊代" -"物件 (iterable) 來排序建立新串列，並回傳之。例如，以下這個範例會說明如何有序" -"地疊代字典的鍵： ::" - -#: ../../faq/design.rst:559 -msgid "" -"for key in sorted(mydict):\n" -" ... # do whatever with mydict[key]..." -msgstr "" - -#: ../../faq/design.rst:564 -msgid "How do you specify and enforce an interface spec in Python?" -msgstr "如何在 Python 中指定和強制使用一個介面規範 (interface spec)？" - -#: ../../faq/design.rst:566 -msgid "" -"An interface specification for a module as provided by languages such as C++ " -"and Java describes the prototypes for the methods and functions of the " -"module. Many feel that compile-time enforcement of interface specifications " -"helps in the construction of large programs." -msgstr "" -"像是 C++ 和 Java 等語言提供了模組的介面規範，他描述了該模組的方法和函式的原" -"型。很多人認為這種在編譯時強制執行的介面規範在建構大型程式時十分有幫助。" - -#: ../../faq/design.rst:571 -msgid "" -"Python 2.6 adds an :mod:`abc` module that lets you define Abstract Base " -"Classes (ABCs). You can then use :func:`isinstance` and :func:`issubclass` " -"to check whether an instance or a class implements a particular ABC. " -"The :mod:`collections.abc` module defines a set of useful ABCs such " -"as :class:`~collections.abc.Iterable`, :class:`~collections.abc.Container`, " -"and :class:`~collections.abc.MutableMapping`." -msgstr "" -"Python 2.6 加入了 :mod:`abc` 模組，讓你可以定義抽象基底類別 (Abstract Base " -"Class, ABC)。你可以使用 :func:`isinstance` 和 :func:`issubclass` 來確認一個實" -"例或是類別是否實作了某個抽象基底類別。而 :mod:`collections.abc` 模組定義了一" -"系列好用的抽象基底類別，像" -"是 :class:`~collections.abc.Iterable`、:class:`~collections.abc.Container` " -"和 :class:`~collections.abc.MutableMapping`。" - -#: ../../faq/design.rst:578 -msgid "" -"For Python, many of the advantages of interface specifications can be " -"obtained by an appropriate test discipline for components." -msgstr "對 Python 來說，很多介面規範的優點可以用對元件適當的測試規則來達到。" - -#: ../../faq/design.rst:581 -msgid "" -"A good test suite for a module can both provide a regression test and serve " -"as a module interface specification and a set of examples. Many Python " -"modules can be run as a script to provide a simple \"self test.\" Even " -"modules which use complex external interfaces can often be tested in " -"isolation using trivial \"stub\" emulations of the external interface. " -"The :mod:`doctest` and :mod:`unittest` modules or third-party test " -"frameworks can be used to construct exhaustive test suites that exercise " -"every line of code in a module." -msgstr "" -"一個針對模組的好測試套件提供了迴歸測試 (regression testing)，並作為模組介面規" -"範和一組範例。許多 Python 模組可以直接當成腳本執行，並提供簡單的「自我測" -"試」。即便模組使用了複雜的外部介面，他依然可以用外部介面的簡單的「樁」(stub) " -"模擬來獨立測試。:mod:`doctest` 和 :mod:`unittest` 模組或第三方的測試框架可以" -"用來建構詳盡徹底的測試套件來測試模組裡的每一行程式碼。" - -#: ../../faq/design.rst:589 -msgid "" -"An appropriate testing discipline can help build large complex applications " -"in Python as well as having interface specifications would. In fact, it can " -"be better because an interface specification cannot test certain properties " -"of a program. For example, the :meth:`list.append` method is expected to " -"add new elements to the end of some internal list; an interface " -"specification cannot test that your :meth:`list.append` implementation will " -"actually do this correctly, but it's trivial to check this property in a " -"test suite." -msgstr "" -"就像介面規範一樣，一個適當的測試規則在建造大型又複雜的 Python 應用程式時可以" -"幫上忙。事實上，他可能可以有更好的表現，因為介面規範無法測試程式的特定屬性。" -"舉例來說，:meth:`list.append` 方法應該要在某個內部的串列最後面加上新的元素，" -"而介面規範沒辦法測試你的 :meth:`list.append` 是不是真的有正確的實作，但這在" -"測試套件裡是件很簡單的事。" - -#: ../../faq/design.rst:597 -msgid "" -"Writing test suites is very helpful, and you might want to design your code " -"to make it easily tested. One increasingly popular technique, test-driven " -"development, calls for writing parts of the test suite first, before you " -"write any of the actual code. Of course Python allows you to be sloppy and " -"not write test cases at all." -msgstr "" -"撰寫測試套件相當有幫助，而你會像要把程式碼設計成好測試的樣子。測試驅動開發 " -"(test-driven development) 是一個越來越受歡迎的設計方法，他要求先完成部分的測" -"試套件，再去撰寫真的要用的程式碼。當然 Python 也允許你草率地不寫任何測試。" - -#: ../../faq/design.rst:605 -msgid "Why is there no goto?" -msgstr "為何沒有 goto 語法？" - -#: ../../faq/design.rst:607 -msgid "" -"In the 1970s people realized that unrestricted goto could lead to messy " -"\"spaghetti\" code that was hard to understand and revise. In a high-level " -"language, it is also unneeded as long as there are ways to branch (in " -"Python, with :keyword:`if` statements and :keyword:`or`, :keyword:`and`, " -"and :keyword:`if`/:keyword:`else` expressions) and loop " -"(with :keyword:`while` and :keyword:`for` statements, possibly " -"containing :keyword:`continue` and :keyword:`break`)." -msgstr "" -"在 1970 年代，人們了解到沒有限制的 goto 會導致混亂、難以理解和修改的「義大利" -"麵」程式碼 (\"spaghetti\" code)。在高階語言裡，這也是不需要的，因為有方法可以" -"做邏輯分支（以 Python 來說，用 :keyword:`if` 陳述式" -"和 :keyword:`or`、:keyword:`and` 及 :keyword:`if`/:keyword:`else` 運算式）和" -"迴圈（用 :keyword:`while` 和 :keyword:`for` 陳述式，可能會" -"有 :keyword:`continue` 和 :keyword:`break`）。" - -#: ../../faq/design.rst:614 -msgid "" -"One can also use exceptions to provide a \"structured goto\" that works even " -"across function calls. Many feel that exceptions can conveniently emulate " -"all reasonable uses of the ``go`` or ``goto`` constructs of C, Fortran, and " -"other languages. For example::" -msgstr "" -"我們也可以用例外來做「結構化的 goto」，這甚至可以跨函式呼叫。很多人覺得例外可" -"以方便地模擬在 C、Fortran 和其他語言裡各種合理使用的 ``go`` 和 ``goto``。例" -"如： ::" - -#: ../../faq/design.rst:620 -msgid "" -"class label(Exception): pass # declare a label\n" -"\n" -"try:\n" -" ...\n" -" if condition: raise label() # goto label\n" -" ...\n" -"except label: # where to goto\n" -" pass\n" -"..." -msgstr "" - -#: ../../faq/design.rst:630 -msgid "" -"This doesn't allow you to jump into the middle of a loop, but that's usually " -"considered an abuse of ``goto`` anyway. Use sparingly." -msgstr "" -"這依然不能讓你跳進迴圈內，這通常被認為是對 ``goto`` 的濫用。請小心使用。" - -#: ../../faq/design.rst:635 -msgid "Why can't raw strings (r-strings) end with a backslash?" -msgstr "為何純字串 (r-string) 不能以反斜線結尾？" - -#: ../../faq/design.rst:637 -msgid "" -"More precisely, they can't end with an odd number of backslashes: the " -"unpaired backslash at the end escapes the closing quote character, leaving " -"an unterminated string." -msgstr "" -"更精確地來說，他不能以奇數個反斜線結尾：尾端未配對的反斜線會使結尾的引號被轉" -"義 (escapes)，變成一個未結束的字串。" - -#: ../../faq/design.rst:641 -msgid "" -"Raw strings were designed to ease creating input for processors (chiefly " -"regular expression engines) that want to do their own backslash escape " -"processing. Such processors consider an unmatched trailing backslash to be " -"an error anyway, so raw strings disallow that. In return, they allow you to " -"pass on the string quote character by escaping it with a backslash. These " -"rules work well when r-strings are used for their intended purpose." -msgstr "" -"設計出純字串是為了提供有自己反斜線跳脫處理的處理器（主要是正規表示式）一個方" -"便的輸入方式。這種處理器會把未配對的結尾反斜線當成錯誤，所以純字串不允許如" -"此。相對地，他讓你用一個反斜線跳脫引號。這些規則在他們預想的目的上正常地運" -"作。" - -#: ../../faq/design.rst:648 -msgid "" -"If you're trying to build Windows pathnames, note that all Windows system " -"calls accept forward slashes too::" -msgstr "" -"如果你嘗試建立 Windows 的路徑名稱，請注意 Windows 系統指令也接受一般斜線： ::" - -#: ../../faq/design.rst:651 -msgid "f = open(\"/mydir/file.txt\") # works fine!" -msgstr "" - -#: ../../faq/design.rst:653 -msgid "" -"If you're trying to build a pathname for a DOS command, try e.g. one of ::" -msgstr "如果你嘗試建立 DOS 指令的路徑名稱，試試看使用以下的範例： ::" - -#: ../../faq/design.rst:655 -msgid "" -"dir = r\"\\this\\is\\my\\dos\\dir\" \"\\\\\"\n" -"dir = r\"\\this\\is\\my\\dos\\dir\\ \"[:-1]\n" -"dir = \"\\\\this\\\\is\\\\my\\\\dos\\\\dir\\\\\"" -msgstr "" - -#: ../../faq/design.rst:661 -msgid "Why doesn't Python have a \"with\" statement for attribute assignments?" -msgstr "為何 Python 沒有屬性賦值的 with 陳述式？" - -#: ../../faq/design.rst:663 -msgid "" -"Python has a :keyword:`with` statement that wraps the execution of a block, " -"calling code on the entrance and exit from the block. Some languages have a " -"construct that looks like this::" -msgstr "" -"Python 的 :keyword:`with` 陳述式包裝了一區塊程式的執行，在進入和離開該區塊時" -"執行程式碼。一些語言會有像如下的結構： ::" - -#: ../../faq/design.rst:667 -msgid "" -"with obj:\n" -" a = 1 # equivalent to obj.a = 1\n" -" total = total + 1 # obj.total = obj.total + 1" -msgstr "" - -#: ../../faq/design.rst:671 -msgid "In Python, such a construct would be ambiguous." -msgstr "但在 Python，這種結構是模糊的。" - -#: ../../faq/design.rst:673 -msgid "" -"Other languages, such as Object Pascal, Delphi, and C++, use static types, " -"so it's possible to know, in an unambiguous way, what member is being " -"assigned to. This is the main point of static typing -- the compiler " -"*always* knows the scope of every variable at compile time." -msgstr "" -"在其他語言裡，像是 Object Pascal、Delphi 和 C++，使用的是靜態型別，所以我們可" -"以清楚地知道是哪一個成員被指派值。這是靜態型別的重點 — 在編譯的時候，編譯器" -"\\ *永遠*\\ 都知道每個變數的作用域 (scope)。" - -#: ../../faq/design.rst:678 -msgid "" -"Python uses dynamic types. It is impossible to know in advance which " -"attribute will be referenced at runtime. Member attributes may be added or " -"removed from objects on the fly. This makes it impossible to know, from a " -"simple reading, what attribute is being referenced: a local one, a global " -"one, or a member attribute?" -msgstr "" -"Python 使用的是動態型別。所以我們不可能提前知道在執行時哪個屬性會被使用到。成" -"員屬性可能在執行時從物件中被新增或移除。這使得如果簡單來看的話，我們無法得知" -"以下哪個屬性會被使用：區域的、全域的、或是成員屬性？" - -#: ../../faq/design.rst:684 -msgid "For instance, take the following incomplete snippet::" -msgstr "以下列不完整的程式碼為例： ::" - -#: ../../faq/design.rst:686 -msgid "" -"def foo(a):\n" -" with a:\n" -" print(x)" -msgstr "" -"def foo(a):\n" -" with a:\n" -" print(x)" - -#: ../../faq/design.rst:690 -msgid "" -"The snippet assumes that ``a`` must have a member attribute called ``x``. " -"However, there is nothing in Python that tells the interpreter this. What " -"should happen if ``a`` is, let us say, an integer? If there is a global " -"variable named ``x``, will it be used inside the :keyword:`with` block? As " -"you see, the dynamic nature of Python makes such choices much harder." -msgstr "" -"這段程式碼假設 ``a`` 有一個叫做 ``x`` 的成員屬性。然後，Python 裡並沒有任何跡" -"象告訴直譯器這件事。在假設「a」是一個整數的話，那會發生什麼事？如果有一個全域" -"變數稱為 ``x``，那在這個 :keyword:`with` 區塊會被使用嗎？如你所見，Python 動" -"態的天性使得這種選擇更加困難。" - -#: ../../faq/design.rst:696 -msgid "" -"The primary benefit of :keyword:`with` and similar language features " -"(reduction of code volume) can, however, easily be achieved in Python by " -"assignment. Instead of::" -msgstr "" -"然而 :keyword:`with` 陳述式或類似的語言特性（減少程式碼量）的主要好處可以透過" -"賦值來達成。相較於這樣寫： ::" - -#: ../../faq/design.rst:699 -msgid "" -"function(args).mydict[index][index].a = 21\n" -"function(args).mydict[index][index].b = 42\n" -"function(args).mydict[index][index].c = 63" -msgstr "" -"function(args).mydict[index][index].a = 21\n" -"function(args).mydict[index][index].b = 42\n" -"function(args).mydict[index][index].c = 63" - -#: ../../faq/design.rst:703 -msgid "write this::" -msgstr "應該寫成這樣： ::" - -#: ../../faq/design.rst:705 -msgid "" -"ref = function(args).mydict[index][index]\n" -"ref.a = 21\n" -"ref.b = 42\n" -"ref.c = 63" -msgstr "" -"ref = function(args).mydict[index][index]\n" -"ref.a = 21\n" -"ref.b = 42\n" -"ref.c = 63" - -#: ../../faq/design.rst:710 -msgid "" -"This also has the side-effect of increasing execution speed because name " -"bindings are resolved at run-time in Python, and the second version only " -"needs to perform the resolution once." -msgstr "" -"這也有提升執行速度的副作用，因為 Python 的名稱綁定解析會在執行的時候發生，而" -"第二版只需要執行解析一次即可。" - -#: ../../faq/design.rst:714 -msgid "" -"Similar proposals that would introduce syntax to further reduce code volume, " -"such as using a 'leading dot', have been rejected in favour of explicitness " -"(see https://mail.python.org/pipermail/python-ideas/2016-May/040070.html)." -msgstr "" -"類似的提案包括引入語法以進一步減少程式碼量，例如使用「前導點 (leading " -"dot)」，但這些提案已被捨棄，以維持程式的明確性（參閱 https://mail.python.org/" -"pipermail/python-ideas/2016-May/040070.html）。" - -#: ../../faq/design.rst:720 -msgid "Why don't generators support the with statement?" -msgstr "為何產生器 (generator) 不支援 with 陳述式？" - -#: ../../faq/design.rst:722 -msgid "" -"For technical reasons, a generator used directly as a context manager would " -"not work correctly. When, as is most common, a generator is used as an " -"iterator run to completion, no closing is needed. When it is, wrap it " -"as :func:`contextlib.closing(generator) ` in " -"the :keyword:`with` statement." -msgstr "" -"出於技術原因，把產生器直接用作情境 (context) 管理器會無法正常運作。因為通常來" -"說，產生器是被當成疊代器 (iterator)，到最後完成時不需要被手動關閉。但如果你需" -"要的話，你可以在 :keyword:`with` 陳述式裡" -"用 :func:`contextlib.closing(generator) ` 來包裝他。" - -#: ../../faq/design.rst:730 -msgid "Why are colons required for the if/while/def/class statements?" -msgstr "為何 if、while、def、class 陳述式裡需要冒號？" - -#: ../../faq/design.rst:732 -msgid "" -"The colon is required primarily to enhance readability (one of the results " -"of the experimental ABC language). Consider this::" -msgstr "" -"需要冒號主要是為了增加可讀性（由 ABC 語言的實驗得知）。試想如下範例： ::" - -#: ../../faq/design.rst:735 -msgid "" -"if a == b\n" -" print(a)" -msgstr "" -"if a == b\n" -" print(a)" - -#: ../../faq/design.rst:738 -msgid "versus ::" -msgstr "以及： ::" - -#: ../../faq/design.rst:740 -msgid "" -"if a == b:\n" -" print(a)" -msgstr "" -"if a == b:\n" -" print(a)" - -#: ../../faq/design.rst:743 -msgid "" -"Notice how the second one is slightly easier to read. Notice further how a " -"colon sets off the example in this FAQ answer; it's a standard usage in " -"English." -msgstr "" -"注意第二個例子稍微易讀一些的原因。可以更進一步觀察，一個冒號是如何放在這個 " -"FAQ 答案的例子裡的，這是標準的英文用法。" - -#: ../../faq/design.rst:746 -msgid "" -"Another minor reason is that the colon makes it easier for editors with " -"syntax highlighting; they can look for colons to decide when indentation " -"needs to be increased instead of having to do a more elaborate parsing of " -"the program text." -msgstr "" -"另一個小原因是冒號會使編輯器更容易做語法突顯，他們只需要看冒號的位置就可以決" -"定是否需要更多縮排，而不用做更多繁複精密的程式碼剖析。" - -#: ../../faq/design.rst:752 -msgid "Why does Python allow commas at the end of lists and tuples?" -msgstr "為何 Python 允許在串列和元組末端加上逗號？" - -#: ../../faq/design.rst:754 -msgid "" -"Python lets you add a trailing comma at the end of lists, tuples, and " -"dictionaries::" -msgstr "Python 允許你在串列、元組和字典的結尾加上逗號： ::" - -#: ../../faq/design.rst:757 -msgid "" -"[1, 2, 3,]\n" -"('a', 'b', 'c',)\n" -"d = {\n" -" \"A\": [1, 5],\n" -" \"B\": [6, 7], # last trailing comma is optional but good style\n" -"}" -msgstr "" - -#: ../../faq/design.rst:765 -msgid "There are several reasons to allow this." -msgstr "這有許多原因可被允許。" - -#: ../../faq/design.rst:767 -msgid "" -"When you have a literal value for a list, tuple, or dictionary spread across " -"multiple lines, it's easier to add more elements because you don't have to " -"remember to add a comma to the previous line. The lines can also be " -"reordered without creating a syntax error." -msgstr "" -"當你要把串列、元組或字典的值寫成多行時，這樣做會讓你新增元素時較為方便，因為" -"你不需要在前一行加上逗號。這幾行的值也可以被重新排序，而不會導致語法錯誤。" - -#: ../../faq/design.rst:772 -msgid "" -"Accidentally omitting the comma can lead to errors that are hard to " -"diagnose. For example::" -msgstr "不小心遺漏了逗號會導致難以發現的錯誤，例如： ::" - -#: ../../faq/design.rst:775 -msgid "" -"x = [\n" -" \"fee\",\n" -" \"fie\"\n" -" \"foo\",\n" -" \"fum\"\n" -"]" -msgstr "" -"x = [\n" -" \"fee\",\n" -" \"fie\"\n" -" \"foo\",\n" -" \"fum\"\n" -"]" - -#: ../../faq/design.rst:782 -msgid "" -"This list looks like it has four elements, but it actually contains three: " -"\"fee\", \"fiefoo\" and \"fum\". Always adding the comma avoids this source " -"of error." -msgstr "" -"這個串列看起來有四個元素，但他其實只有三個：「fee」、「fiefoo」、「fum」。永" -"遠記得加上逗號以避免這種錯誤。" - -#: ../../faq/design.rst:785 -msgid "" -"Allowing the trailing comma may also make programmatic code generation " -"easier." -msgstr "允許結尾逗號也讓生成的程式碼更容易產生。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Ching-Lung Chuang, 2015 +# SiriusKoan, 2022 +# Steven Hsu , 2023 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: 2023-08-31 11:34+0800\n" +"Last-Translator: Steven Hsu \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" +"X-Generator: Poedit 3.3.2\n" +"X-Poedit-Bookmarks: -1,-1,-1,-1,-1,93,25,-1,-1,-1\n" + +#: ../../faq/design.rst:3 +msgid "Design and History FAQ" +msgstr "設計和歷史常見問答集" + +#: ../../faq/design.rst:6 +msgid "Contents" +msgstr "目錄" + +#: ../../faq/design.rst:11 +msgid "Why does Python use indentation for grouping of statements?" +msgstr "為什麼 Python 使用縮排將陳述式進行分組？" + +#: ../../faq/design.rst:13 +msgid "" +"Guido van Rossum believes that using indentation for grouping is extremely " +"elegant and contributes a lot to the clarity of the average Python program. " +"Most people learn to love this feature after a while." +msgstr "" +"Guido van Rossum 相信使用縮排來分組超級優雅，並且對提高一般 Python 程式的清晰" +"度有許多貢獻。許多人在學習一段時間之後就愛上了這個功能。" + +#: ../../faq/design.rst:17 +msgid "" +"Since there are no begin/end brackets there cannot be a disagreement between " +"grouping perceived by the parser and the human reader. Occasionally C " +"programmers will encounter a fragment of code like this::" +msgstr "" +"因為沒有開始/結束括號，因此剖析器和人類讀者感知到的分組就不存在分歧。偶爾 C " +"語言的程式設計師會遇到這樣的程式碼片段： ::" + +#: ../../faq/design.rst:21 +msgid "" +"if (x <= y)\n" +" x++;\n" +" y--;\n" +"z++;" +msgstr "" +"if (x <= y)\n" +" x++;\n" +" y--;\n" +"z++;" + +#: ../../faq/design.rst:26 +msgid "" +"Only the ``x++`` statement is executed if the condition is true, but the " +"indentation leads many to believe otherwise. Even experienced C programmers " +"will sometimes stare at it a long time wondering as to why ``y`` is being " +"decremented even for ``x > y``." +msgstr "" +"如果條件為真，只有 ``x++`` 陳述式會被執行，但縮排會讓很多人對他有不同的理解。" +"即使是資深的 C 語言開發者有時也會盯著他許久，思考為何即便 ``x > y``，但 " +"``y`` 還是減少了。" + +#: ../../faq/design.rst:31 +msgid "" +"Because there are no begin/end brackets, Python is much less prone to coding-" +"style conflicts. In C there are many different ways to place the braces. " +"After becoming used to reading and writing code using a particular style, it " +"is normal to feel somewhat uneasy when reading (or being required to write) " +"in a different one." +msgstr "" +"因為沒有開頭與結尾的括號，Python 比起其他語言會更不容易遇到程式碼風格的衝突。" +"在 C 語言中，有多種不同的方法來放置花括號。在習慣讀寫特定風格後，去讀（或是必" +"須去寫）另一種風格會覺得不太舒服。" + +#: ../../faq/design.rst:38 +msgid "" +"Many coding styles place begin/end brackets on a line by themselves. This " +"makes programs considerably longer and wastes valuable screen space, making " +"it harder to get a good overview of a program. Ideally, a function should " +"fit on one screen (say, 20--30 lines). 20 lines of Python can do a lot more " +"work than 20 lines of C. This is not solely due to the lack of begin/end " +"brackets -- the lack of declarations and the high-level data types are also " +"responsible -- but the indentation-based syntax certainly helps." +msgstr "" +"很多程式碼風格會把 begin/end 獨立放在一行。這會讓程式碼很長且浪費珍貴的螢幕空" +"間，要概覽程式時也變得較為困難。理想上來說，一個函式應該要佔一個螢幕（大概 " +"20 至 30 行）。20 行的 Python 程式碼比起 20 行的 C 程式碼可以做更多事。雖然沒" +"有開頭與結尾的括號並非單一原因（沒有變數宣告及高階的資料型別同樣有關），但縮" +"排式的語法確實給了幫助。" + +#: ../../faq/design.rst:48 +msgid "Why am I getting strange results with simple arithmetic operations?" +msgstr "為什麼我會從簡單的數學運算得到奇怪的結果？" + +#: ../../faq/design.rst:50 +msgid "See the next question." +msgstr "請見下一個問題。" + +#: ../../faq/design.rst:54 +msgid "Why are floating-point calculations so inaccurate?" +msgstr "為何浮點數運算如此不精確？" + +#: ../../faq/design.rst:56 +msgid "Users are often surprised by results like this::" +msgstr "使用者時常對這樣的結果感到驚訝： ::" + +#: ../../faq/design.rst:58 +msgid "" +">>> 1.2 - 1.0\n" +"0.19999999999999996" +msgstr "" +">>> 1.2 - 1.0\n" +"0.19999999999999996" + +#: ../../faq/design.rst:61 +msgid "" +"and think it is a bug in Python. It's not. This has little to do with " +"Python, and much more to do with how the underlying platform handles " +"floating-point numbers." +msgstr "" +"然後認為這是 Python 的 bug，但這並不是。這跟 Python 幾乎沒有關係，而是和底層" +"如何處理浮點數有關係。" + +#: ../../faq/design.rst:65 +msgid "" +"The :class:`float` type in CPython uses a C ``double`` for storage. " +"A :class:`float` object's value is stored in binary floating-point with a " +"fixed precision (typically 53 bits) and Python uses C operations, which in " +"turn rely on the hardware implementation in the processor, to perform " +"floating-point operations. This means that as far as floating-point " +"operations are concerned, Python behaves like many popular languages " +"including C and Java." +msgstr "" +"CPython 的 :class:`float` 型別使用了 C 的 ``double`` 型別來儲存。一" +"個 :class:`float` 物件的值會以固定的精度（通常為 53 位元）存為二進制浮點數，" +"Python 使用 C 來運算浮點數，而他的結果會依處理器中的硬體實作方式來決定。這表" +"示就浮點數運算來說，Python 和 C、Java 等很多受歡迎的語言有一樣的行為。" + +#: ../../faq/design.rst:72 +msgid "" +"Many numbers that can be written easily in decimal notation cannot be " +"expressed exactly in binary floating point. For example, after::" +msgstr "" +"很多數字可以簡單地寫成十進位表示，但卻無法簡單地以二進制浮點數表示。比方說，" +"在以下程式碼執行後： ::" + +#: ../../faq/design.rst:75 +msgid ">>> x = 1.2" +msgstr ">>> x = 1.2" + +#: ../../faq/design.rst:77 +msgid "" +"the value stored for ``x`` is a (very good) approximation to the decimal " +"value ``1.2``, but is not exactly equal to it. On a typical machine, the " +"actual stored value is::" +msgstr "" +"``x`` 裡的值是一個（很接近）1.2 的估計值，但並非精確地等於 1.2。以一般的電腦" +"來說，他實際儲存的值是： ::" + +#: ../../faq/design.rst:81 +msgid "1.0011001100110011001100110011001100110011001100110011 (binary)" +msgstr "1.0011001100110011001100110011001100110011001100110011 (binary)" + +#: ../../faq/design.rst:83 +msgid "which is exactly::" +msgstr "而這個值正是： ::" + +#: ../../faq/design.rst:85 +msgid "1.1999999999999999555910790149937383830547332763671875 (decimal)" +msgstr "1.1999999999999999555910790149937383830547332763671875 (decimal)" + +#: ../../faq/design.rst:87 +msgid "" +"The typical precision of 53 bits provides Python floats with 15--16 decimal " +"digits of accuracy." +msgstr "53 位元的精度讓 Python 可以有 15 至 16 小數位的準確度。" + +#: ../../faq/design.rst:90 +msgid "" +"For a fuller explanation, please see the :ref:`floating-point arithmetic " +"` chapter in the Python tutorial." +msgstr "" +"要更完全的解釋可以查閱在 Python 教學的\\ :ref:`浮點運算 `\\ 一" +"章。" + +#: ../../faq/design.rst:95 +msgid "Why are Python strings immutable?" +msgstr "為什麼 Python 字串不可變動？" + +#: ../../faq/design.rst:97 +msgid "There are several advantages." +msgstr "有許多優點。" + +#: ../../faq/design.rst:99 +msgid "" +"One is performance: knowing that a string is immutable means we can allocate " +"space for it at creation time, and the storage requirements are fixed and " +"unchanging. This is also one of the reasons for the distinction between " +"tuples and lists." +msgstr "" +"其一是效能：知道字串不可變動後，我們就可以在創造他的時候就分配好空間，而後他" +"的儲存空間需求就是固定不變的。這也是元組 (tuple) 和串列 (list) 相異的其中一個" +"原因。" + +#: ../../faq/design.rst:104 +msgid "" +"Another advantage is that strings in Python are considered as \"elemental\" " +"as numbers. No amount of activity will change the value 8 to anything else, " +"and in Python, no amount of activity will change the string \"eight\" to " +"anything else." +msgstr "" +"另一個優點是在 Python 中，字串和數字一樣「基本」。沒有任何行為會把 8 這個數值" +"改成其他數值；同理，在 Python 中也沒有任何行為會修改字串「eight」。" + +#: ../../faq/design.rst:112 +msgid "Why must 'self' be used explicitly in method definitions and calls?" +msgstr "為何「self」在方法 (method) 定義和呼叫時一定要明確使用？" + +#: ../../faq/design.rst:114 +msgid "" +"The idea was borrowed from Modula-3. It turns out to be very useful, for a " +"variety of reasons." +msgstr "此構想從 Modula-3 而來。因為許多原因，他可以說是非常實用。" + +#: ../../faq/design.rst:117 +msgid "" +"First, it's more obvious that you are using a method or instance attribute " +"instead of a local variable. Reading ``self.x`` or ``self.meth()`` makes it " +"absolutely clear that an instance variable or method is used even if you " +"don't know the class definition by heart. In C++, you can sort of tell by " +"the lack of a local variable declaration (assuming globals are rare or " +"easily recognizable) -- but in Python, there are no local variable " +"declarations, so you'd have to look up the class definition to be sure. " +"Some C++ and Java coding standards call for instance attributes to have an " +"``m_`` prefix, so this explicitness is still useful in those languages, too." +msgstr "" +"第一，這樣可以更明顯表現出你在用方法 (method) 或是實例 (instance) 的屬性，而" +"非一個區域變數。即使不知道類別 (class) 的定義，當看到 ``self.x`` 或 " +"``self.meth()``，就會很清楚地知道是正在使用實例的變數或是方法。在 C++ 裡，你" +"可以藉由沒有區域變數宣告來判斷這件事 ── 但在 Python 裡沒有區域變數宣告，所以" +"你必須去看類別的定義來確定。有些 C++ 和 Java 的程式碼規格要求要在實例屬性的名" +"稱加上前綴 ``m_``，所以這種明確性在那些語言也是很好用的。" + +#: ../../faq/design.rst:127 +msgid "" +"Second, it means that no special syntax is necessary if you want to " +"explicitly reference or call the method from a particular class. In C++, if " +"you want to use a method from a base class which is overridden in a derived " +"class, you have to use the ``::`` operator -- in Python you can write " +"``baseclass.methodname(self, )``. This is particularly " +"useful for :meth:`~object.__init__` methods, and in general in cases where a " +"derived class method wants to extend the base class method of the same name " +"and thus has to call the base class method somehow." +msgstr "" +"第二，當你想明確地使用或呼叫在某個類別裡的方法的時候，你不需要特殊的語法。在 " +"C++ 裡，如果你想用一個在繼承類別時被覆寫的基底類別方法，必須要用 ``::`` 運算" +"子 -- 但在 Python 裡，你可以直接寫成 ``baseclass.methodname(self, )``。這在 :meth:`~object.__init__` 方法很好用，特別是在一個繼承的類別要" +"擴充基底類別的方法而要呼叫他時。" + +#: ../../faq/design.rst:136 +msgid "" +"Finally, for instance variables it solves a syntactic problem with " +"assignment: since local variables in Python are (by definition!) those " +"variables to which a value is assigned in a function body (and that aren't " +"explicitly declared global), there has to be some way to tell the " +"interpreter that an assignment was meant to assign to an instance variable " +"instead of to a local variable, and it should preferably be syntactic (for " +"efficiency reasons). C++ does this through declarations, but Python doesn't " +"have declarations and it would be a pity having to introduce them just for " +"this purpose. Using the explicit ``self.var`` solves this nicely. " +"Similarly, for using instance variables, having to write ``self.var`` means " +"that references to unqualified names inside a method don't have to search " +"the instance's directories. To put it another way, local variables and " +"instance variables live in two different namespaces, and you need to tell " +"Python which namespace to use." +msgstr "" +"最後，他解決了關於實例變數指派的語法問題：因為區域變數在 Python 是（定義為）" +"在函式內被指派值的變數（且沒有被明確宣告成全域），所以會需要一個方法來告訴直" +"譯器這個指派運算是針對實例變數，而非針對區域變數，這在語法層面處理較好（為了" +"效率）。C++ 用宣告解決了這件事，但 Python 沒有，而為了這個原因而引入變數宣告" +"機制又略嫌浪費。但使用明確的 ``self.var`` 就可以把這個問題圓滿解決。同理，在" +"用實例變數的時候必須寫成 ``self.var`` 即代表對於在方法中不特定的名稱不需要去" +"看實例的內容。換句話說，區域變數和實例變數存在於兩個不同的命名空間 " +"(namespace)，而你需要告訴 Python 要使用哪一個。" + +#: ../../faq/design.rst:154 +msgid "Why can't I use an assignment in an expression?" +msgstr "為何我不能在運算式 (expression) 中使用指派運算？" + +#: ../../faq/design.rst:156 +msgid "Starting in Python 3.8, you can!" +msgstr "從 Python 3.8 開始，你可以這麼做了！" + +#: ../../faq/design.rst:158 +msgid "" +"Assignment expressions using the walrus operator ``:=`` assign a variable in " +"an expression::" +msgstr "指派運算式使用海象運算子 ``:=`` 來在運算式中指派變數值： ::" + +#: ../../faq/design.rst:161 +msgid "" +"while chunk := fp.read(200):\n" +" print(chunk)" +msgstr "" +"while chunk := fp.read(200):\n" +" print(chunk)" + +#: ../../faq/design.rst:164 +msgid "See :pep:`572` for more information." +msgstr "更多資訊請見 :pep:`572`。" + +#: ../../faq/design.rst:169 +msgid "" +"Why does Python use methods for some functionality (e.g. list.index()) but " +"functions for other (e.g. len(list))?" +msgstr "" +"為何 Python 對於一些功能實作使用方法（像是 list.index()），另一些使用函式（像" +"是 len(list)）？" + +#: ../../faq/design.rst:171 +msgid "As Guido said:" +msgstr "如 Guido 所說：" + +#: ../../faq/design.rst:173 +msgid "" +"(a) For some operations, prefix notation just reads better than postfix -- " +"prefix (and infix!) operations have a long tradition in mathematics which " +"likes notations where the visuals help the mathematician thinking about a " +"problem. Compare the easy with which we rewrite a formula like x*(a+b) into " +"x*a + x*b to the clumsiness of doing the same thing using a raw OO notation." +msgstr "" +"（一） 對一些運算來說，前綴寫法看起來會比後綴寫法好 ── 前綴（和中綴！）運算在" +"數學上有更久遠的傳統，這些符號在視覺上幫助數學家們更容易思考問題。想想把 " +"x*(a+b) 這種式子展開成 x*a + x*b 的簡單，再比較一下古老的圈圈符號記法的笨拙就" +"知道了。" + +#: ../../faq/design.rst:180 +msgid "" +"(b) When I read code that says len(x) I *know* that it is asking for the " +"length of something. This tells me two things: the result is an integer, and " +"the argument is some kind of container. To the contrary, when I read " +"x.len(), I have to already know that x is some kind of container " +"implementing an interface or inheriting from a class that has a standard " +"len(). Witness the confusion we occasionally have when a class that is not " +"implementing a mapping has a get() or keys() method, or something that isn't " +"a file has a write() method." +msgstr "" +"（二） 當我看到一段程式碼寫著 len(x)，我\\ *知道*\\ 他要找某個東西的長度。這" +"告訴了我兩件事：結果是一個整數、參數是某種容器。相對地，當我看到 x.len()，我" +"必須先知道 x 是某種容器，並實作了一個介面或是繼承了一個有標準 len() 的類別。" +"遇到一個沒有實作對映 (mapping) 的類別卻有 get() 或 keys() 方法，或是不是檔案" +"但卻有 write() 方法時，我們偶爾會覺得困惑。" + +#: ../../faq/design.rst:189 +msgid "https://mail.python.org/pipermail/python-3000/2006-November/004643.html" +msgstr "" +"https://mail.python.org/pipermail/python-3000/2006-November/004643.html" + +#: ../../faq/design.rst:193 +msgid "Why is join() a string method instead of a list or tuple method?" +msgstr "為何 join() 是字串方法而非串列 (list) 或元組 (tuple) 方法？" + +#: ../../faq/design.rst:195 +msgid "" +"Strings became much more like other standard types starting in Python 1.6, " +"when methods were added which give the same functionality that has always " +"been available using the functions of the string module. Most of these new " +"methods have been widely accepted, but the one which appears to make some " +"programmers feel uncomfortable is::" +msgstr "" +"自 Python 1.6 之後，字串變得很像其他標準的型別，也在此時，一些可以和字串模組" +"的函式有相同功能的方法也被加入。大多數的新方法都被廣泛接受，但有一個方法似乎" +"讓一些程式人員不舒服： ::" + +#: ../../faq/design.rst:201 +msgid "\", \".join(['1', '2', '4', '8', '16'])" +msgstr "\", \".join(['1', '2', '4', '8', '16'])" + +#: ../../faq/design.rst:203 +msgid "which gives the result::" +msgstr "結果是： ::" + +#: ../../faq/design.rst:205 +msgid "\"1, 2, 4, 8, 16\"" +msgstr "\"1, 2, 4, 8, 16\"" + +#: ../../faq/design.rst:207 +msgid "There are two common arguments against this usage." +msgstr "通常有兩個反對這個用法的論點。" + +#: ../../faq/design.rst:209 +msgid "" +"The first runs along the lines of: \"It looks really ugly using a method of " +"a string literal (string constant)\", to which the answer is that it might, " +"but a string literal is just a fixed value. If the methods are to be allowed " +"on names bound to strings there is no logical reason to make them " +"unavailable on literals." +msgstr "" +"第一項這麼說：「用字串文本 (string literal) （字串常數）看起來真的很醜」，也" +"許真的如此，但字串文本就只是一個固定值。如果方法可以用在值為字串的變數上，那" +"沒道理字串文本不能被使用。" + +#: ../../faq/design.rst:215 +msgid "" +"The second objection is typically cast as: \"I am really telling a sequence " +"to join its members together with a string constant\". Sadly, you aren't. " +"For some reason there seems to be much less difficulty with " +"having :meth:`~str.split` as a string method, since in that case it is easy " +"to see that ::" +msgstr "" +"第二個反對意見通常是：「我是在叫一個序列把它的成員用一個字串常數連接起來」。" +"但很遺憾地，你並不是在這樣做。因為某種原因，把 :meth:`~str.split` 當成字串方" +"法比較簡單，因為這樣我們可以輕易地看到： ::" + +#: ../../faq/design.rst:220 +msgid "\"1, 2, 4, 8, 16\".split(\", \")" +msgstr "\"1, 2, 4, 8, 16\".split(\", \")" + +#: ../../faq/design.rst:222 +msgid "" +"is an instruction to a string literal to return the substrings delimited by " +"the given separator (or, by default, arbitrary runs of white space)." +msgstr "" +"這是在叫一個字串文本回傳由指定的分隔符號（或是預設為空白）分出的子字串的指" +"令。" + +#: ../../faq/design.rst:225 +msgid "" +":meth:`~str.join` is a string method because in using it you are telling the " +"separator string to iterate over a sequence of strings and insert itself " +"between adjacent elements. This method can be used with any argument which " +"obeys the rules for sequence objects, including any new classes you might " +"define yourself. Similar methods exist for bytes and bytearray objects." +msgstr "" +":meth:`~str.join` 是一個字串方法，因為在用他的時候，你是告訴分隔字串去走遍整" +"個字串序列，並將自己插入到相鄰的兩項之間。這個方法的參數可以是任何符合序列規" +"則的物件，包括自己定義的新類別。在 bytes 和 bytearray 物件也有類似的方法可用。" + +#: ../../faq/design.rst:233 +msgid "How fast are exceptions?" +msgstr "例外處理有多快？" + +#: ../../faq/design.rst:235 +msgid "" +"A :keyword:`try`/:keyword:`except` block is extremely efficient if no " +"exceptions are raised. Actually catching an exception is expensive. In " +"versions of Python prior to 2.0 it was common to use this idiom::" +msgstr "" +"如果沒有例外被丟出，一個 :keyword:`try`/:keyword:`except` 區塊是非常有效率" +"的。事實上，抓捕例外要付出昂貴的代價。在 Python 2.0 以前，這樣使用是相當常見" +"的： ::" + +#: ../../faq/design.rst:240 +msgid "" +"try:\n" +" value = mydict[key]\n" +"except KeyError:\n" +" mydict[key] = getvalue(key)\n" +" value = mydict[key]" +msgstr "" +"try:\n" +" value = mydict[key]\n" +"except KeyError:\n" +" mydict[key] = getvalue(key)\n" +" value = mydict[key]" + +#: ../../faq/design.rst:246 +msgid "" +"This only made sense when you expected the dict to have the key almost all " +"the time. If that wasn't the case, you coded it like this::" +msgstr "" +"這只有在你預料這個字典大多數時候都有鍵的時候才合理。如果並非如此，你應該寫" +"成： ::" + +#: ../../faq/design.rst:249 +msgid "" +"if key in mydict:\n" +" value = mydict[key]\n" +"else:\n" +" value = mydict[key] = getvalue(key)" +msgstr "" +"if key in mydict:\n" +" value = mydict[key]\n" +"else:\n" +" value = mydict[key] = getvalue(key)" + +#: ../../faq/design.rst:254 +msgid "" +"For this specific case, you could also use ``value = dict.setdefault(key, " +"getvalue(key))``, but only if the ``getvalue()`` call is cheap enough " +"because it is evaluated in all cases." +msgstr "" +"單就這個情況來說，你也可以用 ``value = dict.setdefault(key, " +"getvalue(key))``，不過只有在 ``getvalue()`` 代價不大的時候才能用，畢竟他每次" +"都會被執行。" + +#: ../../faq/design.rst:260 +msgid "Why isn't there a switch or case statement in Python?" +msgstr "為什麼 Python 內沒有 switch 或 case 陳述式？" + +#: ../../faq/design.rst:262 +msgid "" +"In general, structured switch statements execute one block of code when an " +"expression has a particular value or set of values. Since Python 3.10 one " +"can easily match literal values, or constants within a namespace, with a " +"``match ... case`` statement. An older alternative is a sequence of ``if... " +"elif... elif... else``." +msgstr "" + +#: ../../faq/design.rst:268 +msgid "" +"For cases where you need to choose from a very large number of " +"possibilities, you can create a dictionary mapping case values to functions " +"to call. For example::" +msgstr "如果可能性很多，你可以用字典去對映要呼叫的函式。舉例來說： ::" + +#: ../../faq/design.rst:272 +msgid "" +"functions = {'a': function_1,\n" +" 'b': function_2,\n" +" 'c': self.method_1}\n" +"\n" +"func = functions[value]\n" +"func()" +msgstr "" +"if key in mydict:\n" +" value = mydict[key]\n" +"else:\n" +" value = mydict[key] = getvalue(key)" + +#: ../../faq/design.rst:279 +msgid "" +"For calling methods on objects, you can simplify yet further by using " +"the :func:`getattr` built-in to retrieve methods with a particular name::" +msgstr "" +"對於呼叫物件裡的方法，你可以利用內建用來找尋特定方法的函式 :func:`getattr` 來" +"做進一步的簡化： ::" + +#: ../../faq/design.rst:282 +msgid "" +"class MyVisitor:\n" +" def visit_a(self):\n" +" ...\n" +"\n" +" def dispatch(self, value):\n" +" method_name = 'visit_' + str(value)\n" +" method = getattr(self, method_name)\n" +" method()" +msgstr "" +"class MyVisitor:\n" +" def visit_a(self):\n" +" ...\n" +"\n" +" def dispatch(self, value):\n" +" method_name = 'visit_' + str(value)\n" +" method = getattr(self, method_name)\n" +" method()" + +#: ../../faq/design.rst:291 +msgid "" +"It's suggested that you use a prefix for the method names, such as " +"``visit_`` in this example. Without such a prefix, if values are coming " +"from an untrusted source, an attacker would be able to call any method on " +"your object." +msgstr "" +"我們建議在方法名稱加上前綴，以這個例子來說是 像是 ``visit_``。沒有前綴的話，" +"一旦收到從不信任來源的值，攻擊者便可以隨意呼叫在你的專案內的方法。" + +#: ../../faq/design.rst:295 +msgid "" +"Imitating switch with fallthrough, as with C's switch-case-default, is " +"possible, much harder, and less needed." +msgstr "" + +#: ../../faq/design.rst:300 +msgid "" +"Can't you emulate threads in the interpreter instead of relying on an OS-" +"specific thread implementation?" +msgstr "為何不能在直譯器上模擬執行緒，而要使用作業系統的特定實作方式？" + +#: ../../faq/design.rst:302 +msgid "" +"Answer 1: Unfortunately, the interpreter pushes at least one C stack frame " +"for each Python stack frame. Also, extensions can call back into Python at " +"almost random moments. Therefore, a complete threads implementation " +"requires thread support for C." +msgstr "" +"答案一：很不幸地，直譯器對每個 Python 的堆疊框 (stack frame) 會推至少一個 C " +"的堆疊框。同時，擴充套件可以隨時呼叫 Python，因此完整的實作必須要支援 C 的執" +"行緒。" + +#: ../../faq/design.rst:307 +msgid "" +"Answer 2: Fortunately, there is `Stackless Python `_, which has a completely redesigned " +"interpreter loop that avoids the C stack." +msgstr "" +"答案二：幸運地，`無堆疊 (Stackless) Python `_ 完全重新設計了直譯器迴圈，並避免了 C 堆疊。" + +#: ../../faq/design.rst:312 +msgid "Why can't lambda expressions contain statements?" +msgstr "為何 lambda 運算式不能包含陳述式？" + +#: ../../faq/design.rst:314 +msgid "" +"Python lambda expressions cannot contain statements because Python's " +"syntactic framework can't handle statements nested inside expressions. " +"However, in Python, this is not a serious problem. Unlike lambda forms in " +"other languages, where they add functionality, Python lambdas are only a " +"shorthand notation if you're too lazy to define a function." +msgstr "" +"Python 的 lambda 運算式不能包含陳述式是因為 Python 的語法框架無法處理包在運算" +"式中的陳述式。然而，在 Python 裡這並不是一個嚴重的問題。不像在其他語言中有獨" +"立功能的 lambda，Python 的 lambda 只是一個在你懶得定義函式時可用的一個簡寫表" +"達法。" + +#: ../../faq/design.rst:320 +msgid "" +"Functions are already first class objects in Python, and can be declared in " +"a local scope. Therefore the only advantage of using a lambda instead of a " +"locally defined function is that you don't need to invent a name for the " +"function -- but that's just a local variable to which the function object " +"(which is exactly the same type of object that a lambda expression yields) " +"is assigned!" +msgstr "" +"函式已經是 Python 裡的一級物件 (first class objects)，而且可以在區域範圍內被" +"宣告。因此唯一用 lambda 而非區域性的函式的優點就是你不需要多想一個函式名稱 — " +"但這樣就會是一個區域變數被指定成函式物件（和 lambda 運算式的結果同類）！" + +#: ../../faq/design.rst:328 +msgid "Can Python be compiled to machine code, C or some other language?" +msgstr "Python 可以被編譯成機器語言、C 語言或其他種語言嗎？" + +#: ../../faq/design.rst:330 +msgid "" +"`Cython `_ compiles a modified version of Python with " +"optional annotations into C extensions. `Nuitka `_ is " +"an up-and-coming compiler of Python into C++ code, aiming to support the " +"full Python language." +msgstr "" +"`Cython `_ 可以編譯一個調整過有選擇性註解的 Python 版" +"本。`Nuitka `_ 是一個有潛力編譯器，可以把 Python 編譯成 " +"C++，他的目標是支援完整的 Python 語言。" + +#: ../../faq/design.rst:337 +msgid "How does Python manage memory?" +msgstr "Python 如何管理記憶體？" + +#: ../../faq/design.rst:339 +msgid "" +"The details of Python memory management depend on the implementation. The " +"standard implementation of Python, :term:`CPython`, uses reference counting " +"to detect inaccessible objects, and another mechanism to collect reference " +"cycles, periodically executing a cycle detection algorithm which looks for " +"inaccessible cycles and deletes the objects involved. The :mod:`gc` module " +"provides functions to perform a garbage collection, obtain debugging " +"statistics, and tune the collector's parameters." +msgstr "" +"Python 記憶體管理的細節取決於實作。Python 的標準實作 :term:`CPython` 使用參照" +"計次 (reference counting) 來偵測不再被存取的物件，並用另一個機制來收集參照循" +"環 (reference cycle)、定期執行循環偵測演算法來找不再使用的循環並刪除相關物" +"件。 :mod:`gc` 模組提供了可以執行垃圾收集、抓取除錯統計數據和調整收集器參數的" +"函式。" + +#: ../../faq/design.rst:347 +msgid "" +"Other implementations (such as `Jython `_ or `PyPy " +"`_), however, can rely on a different mechanism such as a " +"full-blown garbage collector. This difference can cause some subtle porting " +"problems if your Python code depends on the behavior of the reference " +"counting implementation." +msgstr "" +"然而，在其他實作（像是 `Jython `_ 或 `PyPy `_）中，會使用像是成熟的垃圾收集器等不同機制。如果你的 Python 程式碼" +"的表現取決於參照計次的實作，這個相異處會導致一些微小的移植問題。" + +#: ../../faq/design.rst:353 +msgid "" +"In some Python implementations, the following code (which is fine in " +"CPython) will probably run out of file descriptors::" +msgstr "" +"在一些 Python 實作中，下面這段程式碼（在 CPython 可以正常運作）可能會把檔案描" +"述子 (file descriptor) 用盡： ::" + +#: ../../faq/design.rst:356 +msgid "" +"for file in very_long_list_of_files:\n" +" f = open(file)\n" +" c = f.read(1)" +msgstr "" +"for file in very_long_list_of_files:\n" +" f = open(file)\n" +" c = f.read(1)" + +#: ../../faq/design.rst:360 +msgid "" +"Indeed, using CPython's reference counting and destructor scheme, each new " +"assignment to ``f`` closes the previous file. With a traditional GC, " +"however, those file objects will only get collected (and closed) at varying " +"and possibly long intervals." +msgstr "" +"實際上，使用 CPython 的參照計次和解構方案 (destructor scheme)，每個對 ``f`` " +"的新指派都會關閉前面打開的檔案。然而用傳統的垃圾回收 (GC) 的話，這些檔案物件" +"只會在不固定且有可能很長的時間後被收集（並關閉）。" + +#: ../../faq/design.rst:365 +msgid "" +"If you want to write code that will work with any Python implementation, you " +"should explicitly close the file or use the :keyword:`with` statement; this " +"will work regardless of memory management scheme::" +msgstr "" +"如果你希望你的程式碼在任何 Python 實作版本中都可以運作，那你應該清楚地關閉檔" +"案或是使用 :keyword:`with` 陳述式，如此一來，不用管記憶體管理的方法，他也會正" +"常運作： ::" + +#: ../../faq/design.rst:369 +msgid "" +"for file in very_long_list_of_files:\n" +" with open(file) as f:\n" +" c = f.read(1)" +msgstr "" +"for file in very_long_list_of_files:\n" +" with open(file) as f:\n" +" c = f.read(1)" + +#: ../../faq/design.rst:375 +msgid "Why doesn't CPython use a more traditional garbage collection scheme?" +msgstr "為何 CPython 不使用更多傳統的垃圾回收機制？" + +#: ../../faq/design.rst:377 +msgid "" +"For one thing, this is not a C standard feature and hence it's not portable. " +"(Yes, we know about the Boehm GC library. It has bits of assembler code for " +"*most* common platforms, not for all of them, and although it is mostly " +"transparent, it isn't completely transparent; patches are required to get " +"Python to work with it.)" +msgstr "" +"第一，這並不是 C 的標準功能，因此他的可攜性低。（對，我們知道 Boehm GC 函式" +"庫。他有可相容於\\ *大多數*\\ 平台的組合語言程式碼，但依然不是全部，而即便它" +"大多數是通透的，也並不完全，要讓它跟 Python 相容還是需要做一些修補。）" + +#: ../../faq/design.rst:383 +msgid "" +"Traditional GC also becomes a problem when Python is embedded into other " +"applications. While in a standalone Python it's fine to replace the " +"standard ``malloc()`` and ``free()`` with versions provided by the GC " +"library, an application embedding Python may want to have its *own* " +"substitute for ``malloc()`` and ``free()``, and may not want Python's. " +"Right now, CPython works with anything that implements ``malloc()`` and " +"``free()`` properly." +msgstr "" +"傳統的垃圾收集 (GC) 在 Python 被嵌入其他應用程式時也成了一個問題。在獨立的 " +"Python 程式裡當然可以把標準的 ``malloc()`` 和 ``free()`` 換成 GC 函式庫提供的" +"其他版本；但一個嵌著 Python 的應用程式可能想用\\ *自己*\\ 的 malloc() 和 " +"free() 替代品，而不是用 Python 的。以現在來說，CPython 和實作 malloc() 和 " +"free() 的程式相處融洽。" + +#: ../../faq/design.rst:392 +msgid "Why isn't all memory freed when CPython exits?" +msgstr "當 CPython 結束時，為何所有的記憶體不會被釋放？" + +#: ../../faq/design.rst:394 +msgid "" +"Objects referenced from the global namespaces of Python modules are not " +"always deallocated when Python exits. This may happen if there are circular " +"references. There are also certain bits of memory that are allocated by the " +"C library that are impossible to free (e.g. a tool like Purify will complain " +"about these). Python is, however, aggressive about cleaning up memory on " +"exit and does try to destroy every single object." +msgstr "" +"當離開 Python 時，從 Python 模組的全域命名空間來的物件並非總是會被釋放。在有" +"循環引用的時候，這可能會發生。有些記憶體是被 C 函式庫取用的，他們不可能被釋放" +"（例如：像是 Purify 之類的工具會抱怨）。然而，Python 在關閉的時候會積極清理記" +"憶體並嘗試刪除每個物件。" + +#: ../../faq/design.rst:401 +msgid "" +"If you want to force Python to delete certain things on deallocation use " +"the :mod:`atexit` module to run a function that will force those deletions." +msgstr "" +"如果你想要強迫 Python 在釋放記憶體時刪除特定的東西，你可以用 :mod:`atexit` 模" +"組來執行會強制刪除的函式。" + +#: ../../faq/design.rst:406 +msgid "Why are there separate tuple and list data types?" +msgstr "為何要把元組 (tuple) 和串列 (list) 分成兩個資料型別？" + +#: ../../faq/design.rst:408 +msgid "" +"Lists and tuples, while similar in many respects, are generally used in " +"fundamentally different ways. Tuples can be thought of as being similar to " +"Pascal ``records`` or C ``structs``; they're small collections of related " +"data which may be of different types which are operated on as a group. For " +"example, a Cartesian coordinate is appropriately represented as a tuple of " +"two or three numbers." +msgstr "" +"串列和元組在很多方面相當相似，但通常用在完全不同的地方。元組可以想成 Pascal " +"的 ``record`` 或是 C 的 ``struct``，是一小群相關聯但可能是不同型別的資料集" +"合，以一組為單位進行操作。舉例來說，一個笛卡兒坐標系可以適當地表示成一個有二" +"或三個值的元組。" + +#: ../../faq/design.rst:415 +msgid "" +"Lists, on the other hand, are more like arrays in other languages. They " +"tend to hold a varying number of objects all of which have the same type and " +"which are operated on one-by-one. For example, :func:`os.listdir('.') " +"` returns a list of strings representing the files in the " +"current directory. Functions which operate on this output would generally " +"not break if you added another file or two to the directory." +msgstr "" +"另一方面，串列更像是其他語言的陣列 (array)。他可以有不固定個同類別物件，且為" +"逐項操作。舉例來說，:func:`os.listdir('.') ` 回傳當下目錄裡的檔" +"案，以包含字串的串列表示。如果你新增了幾個檔案到這個目錄，一般來說操作結果的" +"函式也會正常運作。" + +#: ../../faq/design.rst:423 +msgid "" +"Tuples are immutable, meaning that once a tuple has been created, you can't " +"replace any of its elements with a new value. Lists are mutable, meaning " +"that you can always change a list's elements. Only immutable elements can " +"be used as dictionary keys, and hence only tuples and not lists can be used " +"as keys." +msgstr "" +"元組則是不可變的，代表一旦元組被建立，你就不能夠改變裡面的任何一個值。而串列" +"可變，所以你可以改變裡面的元素。只有不可變的元素可以成為字典的鍵，所以只能把" +"元組當成鍵，而串列則不行。" + +#: ../../faq/design.rst:430 +msgid "How are lists implemented in CPython?" +msgstr "串列 (list) 在 CPython 中是怎麼實作的？" + +#: ../../faq/design.rst:432 +msgid "" +"CPython's lists are really variable-length arrays, not Lisp-style linked " +"lists. The implementation uses a contiguous array of references to other " +"objects, and keeps a pointer to this array and the array's length in a list " +"head structure." +msgstr "" +"CPython 的串列 (list) 事實上是可變長度的陣列 (array)，而不是像 Lisp 語言的鏈" +"接串列 (linked list)。實作上，他是一個連續的物件參照 (reference) 陣列，並把指" +"向此陣列的指標 (pointer) 和陣列長度存在串列的標頭結構內。" + +#: ../../faq/design.rst:436 +msgid "" +"This makes indexing a list ``a[i]`` an operation whose cost is independent " +"of the size of the list or the value of the index." +msgstr "因此，用索引來找串列特定項 ``a[i]`` 的代價和串列大小或是索引值無關。" + +#: ../../faq/design.rst:439 +msgid "" +"When items are appended or inserted, the array of references is resized. " +"Some cleverness is applied to improve the performance of appending items " +"repeatedly; when the array must be grown, some extra space is allocated so " +"the next few times don't require an actual resize." +msgstr "" +"當新物件被新增或插入時，陣列會被調整大小。為了改善多次加入物件的效率，我們有" +"用一些巧妙的方法，當陣列必須變大時，會多收集一些額外的空間，接下來幾次新增時" +"就不需要再調整大小了。" + +#: ../../faq/design.rst:446 +msgid "How are dictionaries implemented in CPython?" +msgstr "字典 (dictionaries) 在 CPython 中是怎麼實作的？" + +#: ../../faq/design.rst:448 +msgid "" +"CPython's dictionaries are implemented as resizable hash tables. Compared " +"to B-trees, this gives better performance for lookup (the most common " +"operation by far) under most circumstances, and the implementation is " +"simpler." +msgstr "" +"CPython 的字典是用可調整大小的雜湊表 (hash table) 實作的。比起 B 樹 (B-" +"tree)，在搜尋（目前為止最常見的操作）方面有更好的表現，實作上也較為簡單。" + +#: ../../faq/design.rst:452 +msgid "" +"Dictionaries work by computing a hash code for each key stored in the " +"dictionary using the :func:`hash` built-in function. The hash code varies " +"widely depending on the key and a per-process seed; for example, " +"``'Python'`` could hash to ``-539294296`` while ``'python'``, a string that " +"differs by a single bit, could hash to ``1142331976``. The hash code is " +"then used to calculate a location in an internal array where the value will " +"be stored. Assuming that you're storing keys that all have different hash " +"values, this means that dictionaries take constant time -- *O*\\ (1), in Big-" +"O notation -- to retrieve a key." +msgstr "" +"字典利用內建 :func:`hash` 函式，對每個鍵做雜湊計算。雜湊結果依據鍵的值和個別" +"執行緒 (processes) 的種子而有相當大的差距。例如，``'Python'`` 的雜湊是 " +"``-539294296``，而只差一個字的 ``'python'`` 則是 ``1142331976``。雜湊結果接著" +"被用來計算值在內部陣列儲存的位置。假設你存的鍵都有不同的雜湊值，那字典只需要" +"常數時間 — 用大 O 表示法 (Big-O notation) 就是 *O*\\ (1) — 來找任意一個鍵。" + +#: ../../faq/design.rst:463 +msgid "Why must dictionary keys be immutable?" +msgstr "為何字典的鍵一定是不可變的？" + +#: ../../faq/design.rst:465 +msgid "" +"The hash table implementation of dictionaries uses a hash value calculated " +"from the key value to find the key. If the key were a mutable object, its " +"value could change, and thus its hash could also change. But since whoever " +"changes the key object can't tell that it was being used as a dictionary " +"key, it can't move the entry around in the dictionary. Then, when you try " +"to look up the same object in the dictionary it won't be found because its " +"hash value is different. If you tried to look up the old value it wouldn't " +"be found either, because the value of the object found in that hash bin " +"would be different." +msgstr "" +"實作字典用的雜湊表是根據鍵的值做計算從而找到鍵的。如果鍵可變的話，他的值就可" +"以改變，則雜湊的結果也會一起變動。但改變鍵的物件的人無從得知他被用來當成字典" +"的鍵，所以無法修改字典的內容。然後，當你嘗試在字典中尋找這個物件時，因為雜湊" +"值不同的緣故，你找不到他。而如果你嘗試用舊的值去尋找，也一樣找不到，因為他的" +"雜湊結果和原先物件不同。" + +#: ../../faq/design.rst:474 +msgid "" +"If you want a dictionary indexed with a list, simply convert the list to a " +"tuple first; the function ``tuple(L)`` creates a tuple with the same entries " +"as the list ``L``. Tuples are immutable and can therefore be used as " +"dictionary keys." +msgstr "" +"如果你想要用串列作為字典的索引，把他轉換成元組即可。``tuple(L)`` 函式會建立一" +"個和串列 ``L`` 一樣內容的元組。而元組是不可變的，所以可以用來當成字典的鍵。" + +#: ../../faq/design.rst:478 +msgid "Some unacceptable solutions that have been proposed:" +msgstr "也有人提出一些不能接受的方法：" + +#: ../../faq/design.rst:480 +msgid "" +"Hash lists by their address (object ID). This doesn't work because if you " +"construct a new list with the same value it won't be found; e.g.::" +msgstr "" +"用串列的記憶體位址（物件 id）來雜湊。這不會成功，因為你如果用同樣的值建立一個" +"新的串列，是找不到的。舉例來說： ::" + +#: ../../faq/design.rst:483 +msgid "" +"mydict = {[1, 2]: '12'}\n" +"print(mydict[[1, 2]])" +msgstr "" +"mydict = {[1, 2]: '12'}\n" +"print(mydict[[1, 2]])" + +#: ../../faq/design.rst:486 +msgid "" +"would raise a :exc:`KeyError` exception because the id of the ``[1, 2]`` " +"used in the second line differs from that in the first line. In other " +"words, dictionary keys should be compared using ``==``, not " +"using :keyword:`is`." +msgstr "" +"這將會導致 :exc:`KeyError` 例外，因為 ``[1, 2]`` 的 id 在第一行和第二行是不同" +"的。換句話說，字典的鍵應該要用 ``==`` 來做比較，而不是用 :keyword:`is`。" + +#: ../../faq/design.rst:490 +msgid "" +"Make a copy when using a list as a key. This doesn't work because the list, " +"being a mutable object, could contain a reference to itself, and then the " +"copying code would run into an infinite loop." +msgstr "" +"複製一個串列作為鍵。這一樣不會成功，因為串列是可變的，他可以包含自己的參照，" +"所以複製會形成一個無窮迴圈。" + +#: ../../faq/design.rst:494 +msgid "" +"Allow lists as keys but tell the user not to modify them. This would allow " +"a class of hard-to-track bugs in programs when you forgot or modified a list " +"by accident. It also invalidates an important invariant of dictionaries: " +"every value in ``d.keys()`` is usable as a key of the dictionary." +msgstr "" +"允許串列作為鍵，但告訴使用者不要更動他。當你不小心忘記或是更動了這個串列，會" +"產生一種難以追蹤的 bug。他同時也違背了一項字典的重要定則：在 ``d.keys()`` 的" +"每個值都可以當成字典的鍵。" + +#: ../../faq/design.rst:499 +msgid "" +"Mark lists as read-only once they are used as a dictionary key. The problem " +"is that it's not just the top-level object that could change its value; you " +"could use a tuple containing a list as a key. Entering anything as a key " +"into a dictionary would require marking all objects reachable from there as " +"read-only -- and again, self-referential objects could cause an infinite " +"loop." +msgstr "" +"一旦串列被當成鍵，把他標記成只能讀取。問題是，這不只要避免最上層的物件改變" +"值，就像用元組包含串列來做為鍵。把一個物件當成鍵，需要將從他開始可以接觸到的" +"所有物件都標記成只能讀取 — 所以再一次，自己參照自己的物件會導致無窮迴圈。" + +#: ../../faq/design.rst:505 +msgid "" +"There is a trick to get around this if you need to, but use it at your own " +"risk: You can wrap a mutable structure inside a class instance which has " +"both a :meth:`~object.__eq__` and a :meth:`~object.__hash__` method. You " +"must then make sure that the hash value for all such wrapper objects that " +"reside in a dictionary (or other hash based structure), remain fixed while " +"the object is in the dictionary (or other structure). ::" +msgstr "" +"如果你需要的話，這裡有個小技巧可以幫你，但請自己承擔風險：你可以把一個可變物" +"件包裝進一個有 :meth:`~object.__eq__` 和 :meth:`~object.__hash__` 方法的類別" +"實例。只要這種包裝物件還存在於字典（或其他類似結構）中，你就必須確定在字典" +"（或其他用雜湊為基底的結構）中他們的雜湊值會保持恆定。 ::" + +#: ../../faq/design.rst:513 +msgid "" +"class ListWrapper:\n" +" def __init__(self, the_list):\n" +" self.the_list = the_list\n" +"\n" +" def __eq__(self, other):\n" +" return self.the_list == other.the_list\n" +"\n" +" def __hash__(self):\n" +" l = self.the_list\n" +" result = 98767 - len(l)*555\n" +" for i, el in enumerate(l):\n" +" try:\n" +" result = result + (hash(el) % 9999999) * 1001 + i\n" +" except Exception:\n" +" result = (result % 7777777) + i * 333\n" +" return result" +msgstr "" +"class ListWrapper:\n" +" def __init__(self, the_list):\n" +" self.the_list = the_list\n" +"\n" +" def __eq__(self, other):\n" +" return self.the_list == other.the_list\n" +"\n" +" def __hash__(self):\n" +" l = self.the_list\n" +" result = 98767 - len(l)*555\n" +" for i, el in enumerate(l):\n" +" try:\n" +" result = result + (hash(el) % 9999999) * 1001 + i\n" +" except Exception:\n" +" result = (result % 7777777) + i * 333\n" +" return result" + +#: ../../faq/design.rst:530 +msgid "" +"Note that the hash computation is complicated by the possibility that some " +"members of the list may be unhashable and also by the possibility of " +"arithmetic overflow." +msgstr "" +"請注意，雜湊的計算可能變得複雜，因為有串列成員不可雜湊 (unhashable) 和算術溢" +"位的可能性。" + +#: ../../faq/design.rst:534 +msgid "" +"Furthermore it must always be the case that if ``o1 == o2`` (ie " +"``o1.__eq__(o2) is True``) then ``hash(o1) == hash(o2)`` (ie, " +"``o1.__hash__() == o2.__hash__()``), regardless of whether the object is in " +"a dictionary or not. If you fail to meet these restrictions dictionaries " +"and other hash based structures will misbehave." +msgstr "" +"此外，不管物件是否在字典中，如果 ``o1 == o2``\\ （即 ``o1.__eq__(o2) is " +"True``），則 ``hash(o1) == hash(o2)``\\ （即 ``o1.__hash__() == " +"o2.__hash__()``），這個事實必須要成立。如果無法滿足這項限制，那字典和其他用雜" +"湊為基底的結構會出現不正常的行為。" + +#: ../../faq/design.rst:539 +msgid "" +"In the case of :class:`!ListWrapper`, whenever the wrapper object is in a " +"dictionary the wrapped list must not change to avoid anomalies. Don't do " +"this unless you are prepared to think hard about the requirements and the " +"consequences of not meeting them correctly. Consider yourself warned." +msgstr "" +"至於 :class:`!ListWrapper`，只要這個包裝過的物件在字典中，裡面的串列就不能改" +"變以避免不正常的事情發生。除非你已經謹慎思考過你的需求和無法滿足條件的後果，" +"不然請不要這麼做。請自行注意。" + +#: ../../faq/design.rst:546 +msgid "Why doesn't list.sort() return the sorted list?" +msgstr "為何 list.sort() 不是回傳排序過的串列？" + +#: ../../faq/design.rst:548 +msgid "" +"In situations where performance matters, making a copy of the list just to " +"sort it would be wasteful. Therefore, :meth:`list.sort` sorts the list in " +"place. In order to remind you of that fact, it does not return the sorted " +"list. This way, you won't be fooled into accidentally overwriting a list " +"when you need a sorted copy but also need to keep the unsorted version " +"around." +msgstr "" +"在重視效能的情況下，把串列複製一份有些浪費。因此，:meth:`list.sort` 直接在串" +"列裡做排序。為了提醒你這件事，他不會回傳排序過的串列。這樣一來，當你需要排序" +"過和未排序過的串列時，你就不會被誤導而不小心覆蓋掉串列。" + +#: ../../faq/design.rst:554 +msgid "" +"If you want to return a new list, use the built-in :func:`sorted` function " +"instead. This function creates a new list from a provided iterable, sorts " +"it and returns it. For example, here's how to iterate over the keys of a " +"dictionary in sorted order::" +msgstr "" +"如果你想要他回傳新的串列，那可以改用內建的 :func:`sorted`。他會用提供的可疊代" +"物件 (iterable) 來排序建立新串列，並回傳之。例如，以下這個範例會說明如何有序" +"地疊代字典的鍵： ::" + +#: ../../faq/design.rst:559 +msgid "" +"for key in sorted(mydict):\n" +" ... # do whatever with mydict[key]..." +msgstr "" + +#: ../../faq/design.rst:564 +msgid "How do you specify and enforce an interface spec in Python?" +msgstr "如何在 Python 中指定和強制使用一個介面規範 (interface spec)？" + +#: ../../faq/design.rst:566 +msgid "" +"An interface specification for a module as provided by languages such as C++ " +"and Java describes the prototypes for the methods and functions of the " +"module. Many feel that compile-time enforcement of interface specifications " +"helps in the construction of large programs." +msgstr "" +"像是 C++ 和 Java 等語言提供了模組的介面規範，他描述了該模組的方法和函式的原" +"型。很多人認為這種在編譯時強制執行的介面規範在建構大型程式時十分有幫助。" + +#: ../../faq/design.rst:571 +msgid "" +"Python 2.6 adds an :mod:`abc` module that lets you define Abstract Base " +"Classes (ABCs). You can then use :func:`isinstance` and :func:`issubclass` " +"to check whether an instance or a class implements a particular ABC. " +"The :mod:`collections.abc` module defines a set of useful ABCs such " +"as :class:`~collections.abc.Iterable`, :class:`~collections.abc.Container`, " +"and :class:`~collections.abc.MutableMapping`." +msgstr "" +"Python 2.6 加入了 :mod:`abc` 模組，讓你可以定義抽象基底類別 (Abstract Base " +"Class, ABC)。你可以使用 :func:`isinstance` 和 :func:`issubclass` 來確認一個實" +"例或是類別是否實作了某個抽象基底類別。而 :mod:`collections.abc` 模組定義了一" +"系列好用的抽象基底類別，像" +"是 :class:`~collections.abc.Iterable`、:class:`~collections.abc.Container` " +"和 :class:`~collections.abc.MutableMapping`。" + +#: ../../faq/design.rst:578 +msgid "" +"For Python, many of the advantages of interface specifications can be " +"obtained by an appropriate test discipline for components." +msgstr "對 Python 來說，很多介面規範的優點可以用對元件適當的測試規則來達到。" + +#: ../../faq/design.rst:581 +msgid "" +"A good test suite for a module can both provide a regression test and serve " +"as a module interface specification and a set of examples. Many Python " +"modules can be run as a script to provide a simple \"self test.\" Even " +"modules which use complex external interfaces can often be tested in " +"isolation using trivial \"stub\" emulations of the external interface. " +"The :mod:`doctest` and :mod:`unittest` modules or third-party test " +"frameworks can be used to construct exhaustive test suites that exercise " +"every line of code in a module." +msgstr "" +"一個針對模組的好測試套件提供了迴歸測試 (regression testing)，並作為模組介面規" +"範和一組範例。許多 Python 模組可以直接當成腳本執行，並提供簡單的「自我測" +"試」。即便模組使用了複雜的外部介面，他依然可以用外部介面的簡單的「樁」(stub) " +"模擬來獨立測試。:mod:`doctest` 和 :mod:`unittest` 模組或第三方的測試框架可以" +"用來建構詳盡徹底的測試套件來測試模組裡的每一行程式碼。" + +#: ../../faq/design.rst:589 +msgid "" +"An appropriate testing discipline can help build large complex applications " +"in Python as well as having interface specifications would. In fact, it can " +"be better because an interface specification cannot test certain properties " +"of a program. For example, the :meth:`list.append` method is expected to " +"add new elements to the end of some internal list; an interface " +"specification cannot test that your :meth:`list.append` implementation will " +"actually do this correctly, but it's trivial to check this property in a " +"test suite." +msgstr "" +"就像介面規範一樣，一個適當的測試規則在建造大型又複雜的 Python 應用程式時可以" +"幫上忙。事實上，他可能可以有更好的表現，因為介面規範無法測試程式的特定屬性。" +"舉例來說，:meth:`list.append` 方法應該要在某個內部的串列最後面加上新的元素，" +"而介面規範沒辦法測試你的 :meth:`list.append` 是不是真的有正確的實作，但這在" +"測試套件裡是件很簡單的事。" + +#: ../../faq/design.rst:597 +msgid "" +"Writing test suites is very helpful, and you might want to design your code " +"to make it easily tested. One increasingly popular technique, test-driven " +"development, calls for writing parts of the test suite first, before you " +"write any of the actual code. Of course Python allows you to be sloppy and " +"not write test cases at all." +msgstr "" +"撰寫測試套件相當有幫助，而你會像要把程式碼設計成好測試的樣子。測試驅動開發 " +"(test-driven development) 是一個越來越受歡迎的設計方法，他要求先完成部分的測" +"試套件，再去撰寫真的要用的程式碼。當然 Python 也允許你草率地不寫任何測試。" + +#: ../../faq/design.rst:605 +msgid "Why is there no goto?" +msgstr "為何沒有 goto 語法？" + +#: ../../faq/design.rst:607 +msgid "" +"In the 1970s people realized that unrestricted goto could lead to messy " +"\"spaghetti\" code that was hard to understand and revise. In a high-level " +"language, it is also unneeded as long as there are ways to branch (in " +"Python, with :keyword:`if` statements and :keyword:`or`, :keyword:`and`, " +"and :keyword:`if`/:keyword:`else` expressions) and loop " +"(with :keyword:`while` and :keyword:`for` statements, possibly " +"containing :keyword:`continue` and :keyword:`break`)." +msgstr "" +"在 1970 年代，人們了解到沒有限制的 goto 會導致混亂、難以理解和修改的「義大利" +"麵」程式碼 (\"spaghetti\" code)。在高階語言裡，這也是不需要的，因為有方法可以" +"做邏輯分支（以 Python 來說，用 :keyword:`if` 陳述式" +"和 :keyword:`or`、:keyword:`and` 及 :keyword:`if`/:keyword:`else` 運算式）和" +"迴圈（用 :keyword:`while` 和 :keyword:`for` 陳述式，可能會" +"有 :keyword:`continue` 和 :keyword:`break`）。" + +#: ../../faq/design.rst:614 +msgid "" +"One can also use exceptions to provide a \"structured goto\" that works even " +"across function calls. Many feel that exceptions can conveniently emulate " +"all reasonable uses of the ``go`` or ``goto`` constructs of C, Fortran, and " +"other languages. For example::" +msgstr "" +"我們也可以用例外來做「結構化的 goto」，這甚至可以跨函式呼叫。很多人覺得例外可" +"以方便地模擬在 C、Fortran 和其他語言裡各種合理使用的 ``go`` 和 ``goto``。例" +"如： ::" + +#: ../../faq/design.rst:620 +msgid "" +"class label(Exception): pass # declare a label\n" +"\n" +"try:\n" +" ...\n" +" if condition: raise label() # goto label\n" +" ...\n" +"except label: # where to goto\n" +" pass\n" +"..." +msgstr "" + +#: ../../faq/design.rst:630 +msgid "" +"This doesn't allow you to jump into the middle of a loop, but that's usually " +"considered an abuse of ``goto`` anyway. Use sparingly." +msgstr "" +"這依然不能讓你跳進迴圈內，這通常被認為是對 ``goto`` 的濫用。請小心使用。" + +#: ../../faq/design.rst:635 +msgid "Why can't raw strings (r-strings) end with a backslash?" +msgstr "為何純字串 (r-string) 不能以反斜線結尾？" + +#: ../../faq/design.rst:637 +msgid "" +"More precisely, they can't end with an odd number of backslashes: the " +"unpaired backslash at the end escapes the closing quote character, leaving " +"an unterminated string." +msgstr "" +"更精確地來說，他不能以奇數個反斜線結尾：尾端未配對的反斜線會使結尾的引號被轉" +"義 (escapes)，變成一個未結束的字串。" + +#: ../../faq/design.rst:641 +msgid "" +"Raw strings were designed to ease creating input for processors (chiefly " +"regular expression engines) that want to do their own backslash escape " +"processing. Such processors consider an unmatched trailing backslash to be " +"an error anyway, so raw strings disallow that. In return, they allow you to " +"pass on the string quote character by escaping it with a backslash. These " +"rules work well when r-strings are used for their intended purpose." +msgstr "" +"設計出純字串是為了提供有自己反斜線跳脫處理的處理器（主要是正規表示式）一個方" +"便的輸入方式。這種處理器會把未配對的結尾反斜線當成錯誤，所以純字串不允許如" +"此。相對地，他讓你用一個反斜線跳脫引號。這些規則在他們預想的目的上正常地運" +"作。" + +#: ../../faq/design.rst:648 +msgid "" +"If you're trying to build Windows pathnames, note that all Windows system " +"calls accept forward slashes too::" +msgstr "" +"如果你嘗試建立 Windows 的路徑名稱，請注意 Windows 系統指令也接受一般斜線： ::" + +#: ../../faq/design.rst:651 +msgid "f = open(\"/mydir/file.txt\") # works fine!" +msgstr "" + +#: ../../faq/design.rst:653 +msgid "" +"If you're trying to build a pathname for a DOS command, try e.g. one of ::" +msgstr "如果你嘗試建立 DOS 指令的路徑名稱，試試看使用以下的範例： ::" + +#: ../../faq/design.rst:655 +msgid "" +"dir = r\"\\this\\is\\my\\dos\\dir\" \"\\\\\"\n" +"dir = r\"\\this\\is\\my\\dos\\dir\\ \"[:-1]\n" +"dir = \"\\\\this\\\\is\\\\my\\\\dos\\\\dir\\\\\"" +msgstr "" + +#: ../../faq/design.rst:661 +msgid "Why doesn't Python have a \"with\" statement for attribute assignments?" +msgstr "為何 Python 沒有屬性賦值的 with 陳述式？" + +#: ../../faq/design.rst:663 +msgid "" +"Python has a :keyword:`with` statement that wraps the execution of a block, " +"calling code on the entrance and exit from the block. Some languages have a " +"construct that looks like this::" +msgstr "" +"Python 的 :keyword:`with` 陳述式包裝了一區塊程式的執行，在進入和離開該區塊時" +"執行程式碼。一些語言會有像如下的結構： ::" + +#: ../../faq/design.rst:667 +msgid "" +"with obj:\n" +" a = 1 # equivalent to obj.a = 1\n" +" total = total + 1 # obj.total = obj.total + 1" +msgstr "" + +#: ../../faq/design.rst:671 +msgid "In Python, such a construct would be ambiguous." +msgstr "但在 Python，這種結構是模糊的。" + +#: ../../faq/design.rst:673 +msgid "" +"Other languages, such as Object Pascal, Delphi, and C++, use static types, " +"so it's possible to know, in an unambiguous way, what member is being " +"assigned to. This is the main point of static typing -- the compiler " +"*always* knows the scope of every variable at compile time." +msgstr "" +"在其他語言裡，像是 Object Pascal、Delphi 和 C++，使用的是靜態型別，所以我們可" +"以清楚地知道是哪一個成員被指派值。這是靜態型別的重點 — 在編譯的時候，編譯器" +"\\ *永遠*\\ 都知道每個變數的作用域 (scope)。" + +#: ../../faq/design.rst:678 +msgid "" +"Python uses dynamic types. It is impossible to know in advance which " +"attribute will be referenced at runtime. Member attributes may be added or " +"removed from objects on the fly. This makes it impossible to know, from a " +"simple reading, what attribute is being referenced: a local one, a global " +"one, or a member attribute?" +msgstr "" +"Python 使用的是動態型別。所以我們不可能提前知道在執行時哪個屬性會被使用到。成" +"員屬性可能在執行時從物件中被新增或移除。這使得如果簡單來看的話，我們無法得知" +"以下哪個屬性會被使用：區域的、全域的、或是成員屬性？" + +#: ../../faq/design.rst:684 +msgid "For instance, take the following incomplete snippet::" +msgstr "以下列不完整的程式碼為例： ::" + +#: ../../faq/design.rst:686 +msgid "" +"def foo(a):\n" +" with a:\n" +" print(x)" +msgstr "" +"def foo(a):\n" +" with a:\n" +" print(x)" + +#: ../../faq/design.rst:690 +msgid "" +"The snippet assumes that ``a`` must have a member attribute called ``x``. " +"However, there is nothing in Python that tells the interpreter this. What " +"should happen if ``a`` is, let us say, an integer? If there is a global " +"variable named ``x``, will it be used inside the :keyword:`with` block? As " +"you see, the dynamic nature of Python makes such choices much harder." +msgstr "" +"這段程式碼假設 ``a`` 有一個叫做 ``x`` 的成員屬性。然後，Python 裡並沒有任何跡" +"象告訴直譯器這件事。在假設「a」是一個整數的話，那會發生什麼事？如果有一個全域" +"變數稱為 ``x``，那在這個 :keyword:`with` 區塊會被使用嗎？如你所見，Python 動" +"態的天性使得這種選擇更加困難。" + +#: ../../faq/design.rst:696 +msgid "" +"The primary benefit of :keyword:`with` and similar language features " +"(reduction of code volume) can, however, easily be achieved in Python by " +"assignment. Instead of::" +msgstr "" +"然而 :keyword:`with` 陳述式或類似的語言特性（減少程式碼量）的主要好處可以透過" +"賦值來達成。相較於這樣寫： ::" + +#: ../../faq/design.rst:699 +msgid "" +"function(args).mydict[index][index].a = 21\n" +"function(args).mydict[index][index].b = 42\n" +"function(args).mydict[index][index].c = 63" +msgstr "" +"function(args).mydict[index][index].a = 21\n" +"function(args).mydict[index][index].b = 42\n" +"function(args).mydict[index][index].c = 63" + +#: ../../faq/design.rst:703 +msgid "write this::" +msgstr "應該寫成這樣： ::" + +#: ../../faq/design.rst:705 +msgid "" +"ref = function(args).mydict[index][index]\n" +"ref.a = 21\n" +"ref.b = 42\n" +"ref.c = 63" +msgstr "" +"ref = function(args).mydict[index][index]\n" +"ref.a = 21\n" +"ref.b = 42\n" +"ref.c = 63" + +#: ../../faq/design.rst:710 +msgid "" +"This also has the side-effect of increasing execution speed because name " +"bindings are resolved at run-time in Python, and the second version only " +"needs to perform the resolution once." +msgstr "" +"這也有提升執行速度的副作用，因為 Python 的名稱綁定解析會在執行的時候發生，而" +"第二版只需要執行解析一次即可。" + +#: ../../faq/design.rst:714 +msgid "" +"Similar proposals that would introduce syntax to further reduce code volume, " +"such as using a 'leading dot', have been rejected in favour of explicitness " +"(see https://mail.python.org/pipermail/python-ideas/2016-May/040070.html)." +msgstr "" +"類似的提案包括引入語法以進一步減少程式碼量，例如使用「前導點 (leading " +"dot)」，但這些提案已被捨棄，以維持程式的明確性（參閱 https://mail.python.org/" +"pipermail/python-ideas/2016-May/040070.html）。" + +#: ../../faq/design.rst:720 +msgid "Why don't generators support the with statement?" +msgstr "為何產生器 (generator) 不支援 with 陳述式？" + +#: ../../faq/design.rst:722 +msgid "" +"For technical reasons, a generator used directly as a context manager would " +"not work correctly. When, as is most common, a generator is used as an " +"iterator run to completion, no closing is needed. When it is, wrap it " +"as :func:`contextlib.closing(generator) ` in " +"the :keyword:`with` statement." +msgstr "" +"出於技術原因，把產生器直接用作情境 (context) 管理器會無法正常運作。因為通常來" +"說，產生器是被當成疊代器 (iterator)，到最後完成時不需要被手動關閉。但如果你需" +"要的話，你可以在 :keyword:`with` 陳述式裡" +"用 :func:`contextlib.closing(generator) ` 來包裝他。" + +#: ../../faq/design.rst:730 +msgid "Why are colons required for the if/while/def/class statements?" +msgstr "為何 if、while、def、class 陳述式裡需要冒號？" + +#: ../../faq/design.rst:732 +msgid "" +"The colon is required primarily to enhance readability (one of the results " +"of the experimental ABC language). Consider this::" +msgstr "" +"需要冒號主要是為了增加可讀性（由 ABC 語言的實驗得知）。試想如下範例： ::" + +#: ../../faq/design.rst:735 +msgid "" +"if a == b\n" +" print(a)" +msgstr "" +"if a == b\n" +" print(a)" + +#: ../../faq/design.rst:738 +msgid "versus ::" +msgstr "以及： ::" + +#: ../../faq/design.rst:740 +msgid "" +"if a == b:\n" +" print(a)" +msgstr "" +"if a == b:\n" +" print(a)" + +#: ../../faq/design.rst:743 +msgid "" +"Notice how the second one is slightly easier to read. Notice further how a " +"colon sets off the example in this FAQ answer; it's a standard usage in " +"English." +msgstr "" +"注意第二個例子稍微易讀一些的原因。可以更進一步觀察，一個冒號是如何放在這個 " +"FAQ 答案的例子裡的，這是標準的英文用法。" + +#: ../../faq/design.rst:746 +msgid "" +"Another minor reason is that the colon makes it easier for editors with " +"syntax highlighting; they can look for colons to decide when indentation " +"needs to be increased instead of having to do a more elaborate parsing of " +"the program text." +msgstr "" +"另一個小原因是冒號會使編輯器更容易做語法突顯，他們只需要看冒號的位置就可以決" +"定是否需要更多縮排，而不用做更多繁複精密的程式碼剖析。" + +#: ../../faq/design.rst:752 +msgid "Why does Python allow commas at the end of lists and tuples?" +msgstr "為何 Python 允許在串列和元組末端加上逗號？" + +#: ../../faq/design.rst:754 +msgid "" +"Python lets you add a trailing comma at the end of lists, tuples, and " +"dictionaries::" +msgstr "Python 允許你在串列、元組和字典的結尾加上逗號： ::" + +#: ../../faq/design.rst:757 +msgid "" +"[1, 2, 3,]\n" +"('a', 'b', 'c',)\n" +"d = {\n" +" \"A\": [1, 5],\n" +" \"B\": [6, 7], # last trailing comma is optional but good style\n" +"}" +msgstr "" + +#: ../../faq/design.rst:765 +msgid "There are several reasons to allow this." +msgstr "這有許多原因可被允許。" + +#: ../../faq/design.rst:767 +msgid "" +"When you have a literal value for a list, tuple, or dictionary spread across " +"multiple lines, it's easier to add more elements because you don't have to " +"remember to add a comma to the previous line. The lines can also be " +"reordered without creating a syntax error." +msgstr "" +"當你要把串列、元組或字典的值寫成多行時，這樣做會讓你新增元素時較為方便，因為" +"你不需要在前一行加上逗號。這幾行的值也可以被重新排序，而不會導致語法錯誤。" + +#: ../../faq/design.rst:772 +msgid "" +"Accidentally omitting the comma can lead to errors that are hard to " +"diagnose. For example::" +msgstr "不小心遺漏了逗號會導致難以發現的錯誤，例如： ::" + +#: ../../faq/design.rst:775 +msgid "" +"x = [\n" +" \"fee\",\n" +" \"fie\"\n" +" \"foo\",\n" +" \"fum\"\n" +"]" +msgstr "" +"x = [\n" +" \"fee\",\n" +" \"fie\"\n" +" \"foo\",\n" +" \"fum\"\n" +"]" + +#: ../../faq/design.rst:782 +msgid "" +"This list looks like it has four elements, but it actually contains three: " +"\"fee\", \"fiefoo\" and \"fum\". Always adding the comma avoids this source " +"of error." +msgstr "" +"這個串列看起來有四個元素，但他其實只有三個：「fee」、「fiefoo」、「fum」。永" +"遠記得加上逗號以避免這種錯誤。" + +#: ../../faq/design.rst:785 +msgid "" +"Allowing the trailing comma may also make programmatic code generation " +"easier." +msgstr "允許結尾逗號也讓生成的程式碼更容易產生。" diff --git a/faq/extending.po b/faq/extending.po index 2aa7bfff67..206634ae7c 100644 --- a/faq/extending.po +++ b/faq/extending.po @@ -1,512 +1,512 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-06-27 07:36+0000\n" -"PO-Revision-Date: 2023-02-18 13:08+0800\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" -"X-Generator: Poedit 3.2.2\n" - -#: ../../faq/extending.rst:3 -msgid "Extending/Embedding FAQ" -msgstr "擴充/嵌入常見問題集" - -#: ../../faq/extending.rst:6 -msgid "Contents" -msgstr "目錄" - -#: ../../faq/extending.rst:16 -msgid "Can I create my own functions in C?" -msgstr "我可以在 C 中建立自己的函式嗎？" - -#: ../../faq/extending.rst:18 -msgid "" -"Yes, you can create built-in modules containing functions, variables, " -"exceptions and even new types in C. This is explained in the document :ref:" -"`extending-index`." -msgstr "" -"是的，你可以在 C 中建立包含函式、變數、例外甚至新型別的內建模組，:ref:" -"`extending-index` 文件中有相關說明。" - -#: ../../faq/extending.rst:22 -msgid "Most intermediate or advanced Python books will also cover this topic." -msgstr "大多數中級或進階 Python 書籍也會涵蓋這個主題。" - -#: ../../faq/extending.rst:26 -msgid "Can I create my own functions in C++?" -msgstr "我可以在 C++ 中建立自己的函式嗎？" - -#: ../../faq/extending.rst:28 -msgid "" -"Yes, using the C compatibility features found in C++. Place ``extern " -"\"C\" { ... }`` around the Python include files and put ``extern \"C\"`` " -"before each function that is going to be called by the Python interpreter. " -"Global or static C++ objects with constructors are probably not a good idea." -msgstr "" -"是的，可使用 C++ 中的 C 相容性功能。將 ``extern \"C\" { ... }`` 放在 Python 引入" -"檔案周圍，並將 ``extern \"C\"`` 放在每個將由 Python 直譯器呼叫的函式之前。" -"但具有構造函式的全域或靜態 C++ 物件可能不是一個好主意。" - -#: ../../faq/extending.rst:37 -msgid "Writing C is hard; are there any alternatives?" -msgstr "寫 C 很難；還有其他選擇嗎？" - -#: ../../faq/extending.rst:39 -msgid "" -"There are a number of alternatives to writing your own C extensions, " -"depending on what you're trying to do. :ref:`Recommended third party tools " -"` offer both simpler and more sophisticated approaches to " -"creating C and C++ extensions for Python." -msgstr "" - -#: ../../faq/extending.rst:46 -msgid "How can I execute arbitrary Python statements from C?" -msgstr "如何從 C 執行任意 Python 陳述式？" - -#: ../../faq/extending.rst:48 -msgid "" -"The highest-level function to do this is :c:func:`PyRun_SimpleString` which " -"takes a single string argument to be executed in the context of the module " -"``__main__`` and returns ``0`` for success and ``-1`` when an exception " -"occurred (including :exc:`SyntaxError`). If you want more control, use :c:" -"func:`PyRun_String`; see the source for :c:func:`PyRun_SimpleString` in " -"``Python/pythonrun.c``." -msgstr "" -"執行此操作的最高階函式是 :c:func:`PyRun_SimpleString`，它接受一個要在模組 " -"``__main__`` 的情境中執行的單一字串引數，成功時回傳 ``0``，發生例外（包" -"括 :exc:`SyntaxError`）時回傳 ``-1``。如果你想要更多控制，請使用 :c:" -"func:`PyRun_String`；請參閱 ``Python/pythonrun.c`` 中 :c:func:`PyRun_SimpleString` 的" -"原始碼。" - -#: ../../faq/extending.rst:57 -msgid "How can I evaluate an arbitrary Python expression from C?" -msgstr "如何計算來自 C 的任意 Python 運算式？" - -#: ../../faq/extending.rst:59 -msgid "" -"Call the function :c:func:`PyRun_String` from the previous question with the " -"start symbol :c:data:`Py_eval_input`; it parses an expression, evaluates it " -"and returns its value." -msgstr "" -"呼叫前一個問題中的 :c:func:`PyRun_String` 函式，並使用起始符號 :c:" -"data:`Py_eval_input`；它會剖析一個運算式，計算它並回傳它的值。" - -#: ../../faq/extending.rst:65 -msgid "How do I extract C values from a Python object?" -msgstr "如何從 Python 物件中提取 C 值？" - -#: ../../faq/extending.rst:67 -msgid "" -"That depends on the object's type. If it's a tuple, :c:func:`PyTuple_Size` " -"returns its length and :c:func:`PyTuple_GetItem` returns the item at a " -"specified index. Lists have similar functions, :c:func:`PyList_Size` and :c:" -"func:`PyList_GetItem`." -msgstr "" -"這取決於物件的型別。如果它是一個元組，:c:func:`PyTuple_Size` 會回傳它的長度，:" -"c:func:`PyTuple_GetItem` 則回傳指定索引的項目。串列具有類似的函式 :c:func:" -"`PyList_Size` 和 :c:func:`PyList_GetItem`。" - -#: ../../faq/extending.rst:72 -msgid "" -"For bytes, :c:func:`PyBytes_Size` returns its length and :c:func:" -"`PyBytes_AsStringAndSize` provides a pointer to its value and its length. " -"Note that Python bytes objects may contain null bytes so C's :c:func:`!" -"strlen` should not be used." -msgstr "" -"對於位元組，:c:func:`PyBytes_Size` 會回傳它的長度，:c:func:" -"`PyBytes_AsStringAndSize` 則提供指向該值與該長度的指標。請注意，Python 位元組物" -"件可能包含空位元組，因此不應使用 C 的 :c:func:`!strlen`。" - -#: ../../faq/extending.rst:77 -msgid "" -"To test the type of an object, first make sure it isn't ``NULL``, and then " -"use :c:func:`PyBytes_Check`, :c:func:`PyTuple_Check`, :c:func:" -"`PyList_Check`, etc." -msgstr "" -"要測試物件的型別，首先確保它不是 ``NULL``，然後再使用 :c:func:" -"`PyBytes_Check`、:c:func:`PyTuple_Check`、:c:func:`PyList_Check` 等函式。" - -#: ../../faq/extending.rst:80 -msgid "" -"There is also a high-level API to Python objects which is provided by the so-" -"called 'abstract' interface -- read ``Include/abstract.h`` for further " -"details. It allows interfacing with any kind of Python sequence using calls " -"like :c:func:`PySequence_Length`, :c:func:`PySequence_GetItem`, etc. as well " -"as many other useful protocols such as numbers (:c:func:`PyNumber_Index` et " -"al.) and mappings in the PyMapping APIs." -msgstr "" -"還有一個針對 Python 物件的高階 API，它由所謂的「抽象」介面所提供 —— 請閱讀 " -"``Include/abstract.h`` 以了解更多詳細資訊。它允許使用 :c:func:`PySequence_Length`" -"、:c:func:`PySequence_GetItem` 等函式的呼叫以及許多其他有用的協定，例如數值" -"（:c:func:`PyNumber_Index` 等）和 PyMapping API 中的對映，來與任何類型的 Python 序列做介接。" - -#: ../../faq/extending.rst:89 -msgid "How do I use Py_BuildValue() to create a tuple of arbitrary length?" -msgstr "如何使用 Py_BuildValue() 建立任意長度的元組？" - -#: ../../faq/extending.rst:91 -msgid "You can't. Use :c:func:`PyTuple_Pack` instead." -msgstr "這無法做到。請改用 :c:func:`PyTuple_Pack`。" - -#: ../../faq/extending.rst:95 -msgid "How do I call an object's method from C?" -msgstr "如何從 C 呼叫物件的方法？" - -#: ../../faq/extending.rst:97 -msgid "" -"The :c:func:`PyObject_CallMethod` function can be used to call an arbitrary " -"method of an object. The parameters are the object, the name of the method " -"to call, a format string like that used with :c:func:`Py_BuildValue`, and " -"the argument values::" -msgstr "" -":c:func:`PyObject_CallMethod` 函式可用於呼叫物件的任意方法。參數是物件、要呼" -"叫的方法名稱、與 :c:func:`Py_BuildValue` 一起使用的格式字串，以及引數" -"值： ::" - -#: ../../faq/extending.rst:102 -msgid "" -"PyObject *\n" -"PyObject_CallMethod(PyObject *object, const char *method_name,\n" -" const char *arg_format, ...);" -msgstr "" -"PyObject *\n" -"PyObject_CallMethod(PyObject *object, const char *method_name,\n" -" const char *arg_format, ...);" - -#: ../../faq/extending.rst:106 -msgid "" -"This works for any object that has methods -- whether built-in or user-" -"defined. You are responsible for eventually :c:func:`Py_DECREF`\\ 'ing the " -"return value." -msgstr "" -"這適用於任何具有方法的物件 —— 無論是內建的還是使用者定義的。你負責最終為回傳值來 :c:func:" -"`Py_DECREF`。" - -#: ../../faq/extending.rst:109 -msgid "" -"To call, e.g., a file object's \"seek\" method with arguments 10, 0 " -"(assuming the file object pointer is \"f\")::" -msgstr "" -"例如，使用引數 10、0 呼叫檔案物件的 \"seek\" 方法（假設檔案物件指標為 " -"\"f\"）： ::" - -#: ../../faq/extending.rst:112 -msgid "" -"res = PyObject_CallMethod(f, \"seek\", \"(ii)\", 10, 0);\n" -"if (res == NULL) {\n" -" ... an exception occurred ...\n" -"}\n" -"else {\n" -" Py_DECREF(res);\n" -"}" -msgstr "" -"res = PyObject_CallMethod(f, \"seek\", \"(ii)\", 10, 0);\n" -"if (res == NULL) {\n" -" ... 發生一個例外 ...\n" -"}\n" -"else {\n" -" Py_DECREF(res);\n" -"}" - -#: ../../faq/extending.rst:120 -msgid "" -"Note that since :c:func:`PyObject_CallObject` *always* wants a tuple for the " -"argument list, to call a function without arguments, pass \"()\" for the " -"format, and to call a function with one argument, surround the argument in " -"parentheses, e.g. \"(i)\"." -msgstr "" -"請注意，由於 :c:func:`PyObject_CallObject` *總是*\\ 需要一個元組作為引數列表，" -"若要呼叫一個不帶引數的函式，要傳遞 \"()\" 作為格式，並呼叫一個帶有一個引數的函式，" -"將引數括起來在括號中，例如 \"(i)\"。" - -#: ../../faq/extending.rst:127 -msgid "" -"How do I catch the output from PyErr_Print() (or anything that prints to " -"stdout/stderr)?" -msgstr "我如何捕捉 PyErr_Print() 的輸出（或任何印出到 stdout/stderr 的東西）？" - -#: ../../faq/extending.rst:129 -msgid "" -"In Python code, define an object that supports the ``write()`` method. " -"Assign this object to :data:`sys.stdout` and :data:`sys.stderr`. Call " -"print_error, or just allow the standard traceback mechanism to work. Then, " -"the output will go wherever your ``write()`` method sends it." -msgstr "" -"在 Python 程式碼中定義一個支援 ``write()`` 方法的物件。將此物件分配給 :" -"data:`sys.stdout` 和 :data:`sys.stderr`。呼叫 print_error，或者只允許標準的回" -"溯機制起作用。然後，輸出將會傳送到你的 ``write()`` 方法所指定的位置。" - -#: ../../faq/extending.rst:134 -msgid "The easiest way to do this is to use the :class:`io.StringIO` class:" -msgstr "最簡單的方法是使用 :class:`io.StringIO` 類別：" - -#: ../../faq/extending.rst:136 -msgid "" -">>> import io, sys\n" -">>> sys.stdout = io.StringIO()\n" -">>> print('foo')\n" -">>> print('hello world!')\n" -">>> sys.stderr.write(sys.stdout.getvalue())\n" -"foo\n" -"hello world!" -msgstr "" -">>> import io, sys\n" -">>> sys.stdout = io.StringIO()\n" -">>> print('foo')\n" -">>> print('hello world!')\n" -">>> sys.stderr.write(sys.stdout.getvalue())\n" -"foo\n" -"hello world!" - -#: ../../faq/extending.rst:146 -msgid "A custom object to do the same would look like this:" -msgstr "執行相同操作的自訂物件如下所示：" - -#: ../../faq/extending.rst:148 -msgid "" -">>> import io, sys\n" -">>> class StdoutCatcher(io.TextIOBase):\n" -"... def __init__(self):\n" -"... self.data = []\n" -"... def write(self, stuff):\n" -"... self.data.append(stuff)\n" -"...\n" -">>> import sys\n" -">>> sys.stdout = StdoutCatcher()\n" -">>> print('foo')\n" -">>> print('hello world!')\n" -">>> sys.stderr.write(''.join(sys.stdout.data))\n" -"foo\n" -"hello world!" -msgstr "" -">>> import io, sys\n" -">>> class StdoutCatcher(io.TextIOBase):\n" -"... def __init__(self):\n" -"... self.data = []\n" -"... def write(self, stuff):\n" -"... self.data.append(stuff)\n" -"...\n" -">>> import sys\n" -">>> sys.stdout = StdoutCatcher()\n" -">>> print('foo')\n" -">>> print('hello world!')\n" -">>> sys.stderr.write(''.join(sys.stdout.data))\n" -"foo\n" -"hello world!" - -#: ../../faq/extending.rst:167 -msgid "How do I access a module written in Python from C?" -msgstr "如何從 C 存取用 Python 編寫的模組？" - -#: ../../faq/extending.rst:169 -msgid "You can get a pointer to the module object as follows::" -msgstr "你可以取得指向模組物件的指標，如下所示： ::" - -#: ../../faq/extending.rst:171 -msgid "module = PyImport_ImportModule(\"\");" -msgstr "module = PyImport_ImportModule(\"\");" - -#: ../../faq/extending.rst:173 -msgid "" -"If the module hasn't been imported yet (i.e. it is not yet present in :data:" -"`sys.modules`), this initializes the module; otherwise it simply returns the " -"value of ``sys.modules[\"\"]``. Note that it doesn't enter the " -"module into any namespace -- it only ensures it has been initialized and is " -"stored in :data:`sys.modules`." -msgstr "" -"如果模組還沒有被引入（即它還沒有出現在 :data:`sys.modules` 中），這會初始化模" -"組；否則它只回傳 ``sys.modules[\"\"]`` 的值。請注意，它不會將模組" -"輸入任何命名空間——它只會確保它已被初始化並儲存在 :data:`sys.modules` 中。" - -#: ../../faq/extending.rst:179 -msgid "" -"You can then access the module's attributes (i.e. any name defined in the " -"module) as follows::" -msgstr "然後你可以存取模組的屬性（即模組中定義的任何名稱），如下所示： ::" - -#: ../../faq/extending.rst:182 -msgid "attr = PyObject_GetAttrString(module, \"\");" -msgstr "attr = PyObject_GetAttrString(module, \"\");" - -#: ../../faq/extending.rst:184 -msgid "" -"Calling :c:func:`PyObject_SetAttrString` to assign to variables in the " -"module also works." -msgstr "呼叫 :c:func:`PyObject_SetAttrString` 來分配模組中的變數也有效。" - -#: ../../faq/extending.rst:189 -msgid "How do I interface to C++ objects from Python?" -msgstr "我如何從 Python 介接到 C++ 物件？" - -#: ../../faq/extending.rst:191 -msgid "" -"Depending on your requirements, there are many approaches. To do this " -"manually, begin by reading :ref:`the \"Extending and Embedding\" document " -"`. Realize that for the Python run-time system, there " -"isn't a whole lot of difference between C and C++ -- so the strategy of " -"building a new Python type around a C structure (pointer) type will also " -"work for C++ objects." -msgstr "" -"根據你的要求不同而有多種不同方法。要手動執行此操作，請先閱讀\\ :ref:`「擴充和嵌入」說明" -"文件 `。對於 Python run-time 系統，C 和 C++ 之間並" -"沒有太多區別 —— 因此圍繞 C 結構（指標）型別來構建新 Python 型別的策略也適" -"用於 C++ 物件。" - -#: ../../faq/extending.rst:197 -msgid "For C++ libraries, see :ref:`c-wrapper-software`." -msgstr "對於 C++ 函式庫，請參閱 :ref:`c-wrapper-software`。" - -#: ../../faq/extending.rst:201 -msgid "I added a module using the Setup file and the make fails; why?" -msgstr "我使用安裝檔案新增了一個模組，但 make 失敗了；為什麼？" - -#: ../../faq/extending.rst:203 -msgid "" -"Setup must end in a newline, if there is no newline there, the build process " -"fails. (Fixing this requires some ugly shell script hackery, and this bug " -"is so minor that it doesn't seem worth the effort.)" -msgstr "" -"安裝程式必須以換行符結尾，如果那裡沒有換行符，構建過程將失敗。（解決這個問題" -"需要一些醜陋的 shell 腳本 hackery，而且這個錯誤很小，似乎不值得付出努力。）" - -#: ../../faq/extending.rst:209 -msgid "How do I debug an extension?" -msgstr "如何為擴充套件除錯？" - -#: ../../faq/extending.rst:211 -msgid "" -"When using GDB with dynamically loaded extensions, you can't set a " -"breakpoint in your extension until your extension is loaded." -msgstr "" -"將 GDB 與動態載入的擴充一起使用時，在載入擴充之前不能在擴充中設定斷點。" - -#: ../../faq/extending.rst:214 -msgid "In your ``.gdbinit`` file (or interactively), add the command:" -msgstr "在你的 ``.gdbinit`` 檔案中（或交互地），新增命令：" - -#: ../../faq/extending.rst:216 -msgid "br _PyImport_LoadDynamicModule" -msgstr "br _PyImport_LoadDynamicModule" - -#: ../../faq/extending.rst:220 -msgid "Then, when you run GDB:" -msgstr "然後，當你運行 GDB 時：" - -#: ../../faq/extending.rst:222 -msgid "" -"$ gdb /local/bin/python\n" -"gdb) run myscript.py\n" -"gdb) continue # repeat until your extension is loaded\n" -"gdb) finish # so that your extension is loaded\n" -"gdb) br myfunction.c:50\n" -"gdb) continue" -msgstr "" - -#: ../../faq/extending.rst:232 -msgid "" -"I want to compile a Python module on my Linux system, but some files are " -"missing. Why?" -msgstr "" -"我想在我的 Linux 系統上編譯一個 Python 模組，但是缺少一些檔案。為什麼？" - -#: ../../faq/extending.rst:234 -msgid "" -"Most packaged versions of Python omit some files required for compiling " -"Python extensions." -msgstr "大多數打包版本的 Python 省略了編譯 Python 擴充所需的一些檔案。" - -#: ../../faq/extending.rst:237 -msgid "For Red Hat, install the python3-devel RPM to get the necessary files." -msgstr "在 Red Hat 上，請安裝 python3-devel RPM 來取得必要的檔案。" - -#: ../../faq/extending.rst:239 -msgid "For Debian, run ``apt-get install python3-dev``." -msgstr "對於 Debian，運行 ``apt-get install python3-dev``。" - -#: ../../faq/extending.rst:242 -msgid "How do I tell \"incomplete input\" from \"invalid input\"?" -msgstr "如何從「無效輸入」區分出「不完整輸入」？" - -#: ../../faq/extending.rst:244 -msgid "" -"Sometimes you want to emulate the Python interactive interpreter's behavior, " -"where it gives you a continuation prompt when the input is incomplete (e.g. " -"you typed the start of an \"if\" statement or you didn't close your " -"parentheses or triple string quotes), but it gives you a syntax error " -"message immediately when the input is invalid." -msgstr "" -"有時你會想模擬 Python 交互式直譯器的行為，當輸入不完整時（例如，當你輸入了 \"if\" 陳述式的" -"開頭或者你沒有關閉你的括號或三重字串引號）它會給你一個繼續提示字元，" -"但是當輸入無效時，它會立即為你提供語法錯誤訊息。" - -#: ../../faq/extending.rst:250 -msgid "" -"In Python you can use the :mod:`codeop` module, which approximates the " -"parser's behavior sufficiently. IDLE uses this, for example." -msgstr "" -"在 Python 中，你可以使用 :mod:`codeop` 模組，它充分模擬了剖析器 (parser) 的行" -"為。像是 IDLE 就有使用它。" - -#: ../../faq/extending.rst:253 -msgid "" -"The easiest way to do it in C is to call :c:func:`PyRun_InteractiveLoop` " -"(perhaps in a separate thread) and let the Python interpreter handle the " -"input for you. You can also set the :c:func:`PyOS_ReadlineFunctionPointer` " -"to point at your custom input function. See ``Modules/readline.c`` and " -"``Parser/myreadline.c`` for more hints." -msgstr "" -"在 C 中執行此操作的最簡單方法是呼叫 :c:func:`PyRun_InteractiveLoop`\\ （可能是在單" -"獨的執行緒中）並讓 Python 直譯器為你處理輸入。你還可以將 :c:func:" -"`PyOS_ReadlineFunctionPointer` 設定為指向你的自訂輸入函式。有關更多提示，請" -"參閱 ``Modules/readline.c`` 和 ``Parser/myreadline.c``。" - -#: ../../faq/extending.rst:260 -msgid "How do I find undefined g++ symbols __builtin_new or __pure_virtual?" -msgstr "如何找到未定義的 g++ 符號 __builtin_new 或 __pure_virtual？" - -#: ../../faq/extending.rst:262 -msgid "" -"To dynamically load g++ extension modules, you must recompile Python, relink " -"it using g++ (change LINKCC in the Python Modules Makefile), and link your " -"extension module using g++ (e.g., ``g++ -shared -o mymodule.so mymodule.o``)." -msgstr "" -"要動態載入 g++ 擴充模組，你必須重新編譯 Python，並使用 g++ 重新鏈接它（更改 " -"Python 模組 Makefile 中的 LINKCC），且使用 g++ 鏈接你的擴充模組（例如，``g++ " -"-shared -o mymodule.so mymodule.o``）。" - -#: ../../faq/extending.rst:268 -msgid "" -"Can I create an object class with some methods implemented in C and others " -"in Python (e.g. through inheritance)?" -msgstr "" -"我可以用一些用 C 實作的方法和用 Python 實作的其他方法（例如透過繼承）建立一個" -"物件類別嗎？" - -#: ../../faq/extending.rst:270 -msgid "" -"Yes, you can inherit from built-in classes such as :class:`int`, :class:" -"`list`, :class:`dict`, etc." -msgstr "" -"是的，你可以繼承內建類別，例如 :class:`int`、:class:`list`、:class:`dict` " -"等。" - -#: ../../faq/extending.rst:273 -msgid "" -"The Boost Python Library (BPL, https://www.boost.org/libs/python/doc/index." -"html) provides a way of doing this from C++ (i.e. you can inherit from an " -"extension class written in C++ using the BPL)." -msgstr "" -"Boost Python 函式庫（BPL，https://www.boost.org/libs/python/doc/index.html）" -"提供了一種從 C++ 執行此操作的方法（即你可以使用 BPL 來繼承用 C++ 編寫的擴充類" -"別）。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-06-27 07:36+0000\n" +"PO-Revision-Date: 2023-02-18 13:08+0800\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" +"X-Generator: Poedit 3.2.2\n" + +#: ../../faq/extending.rst:3 +msgid "Extending/Embedding FAQ" +msgstr "擴充/嵌入常見問題集" + +#: ../../faq/extending.rst:6 +msgid "Contents" +msgstr "目錄" + +#: ../../faq/extending.rst:16 +msgid "Can I create my own functions in C?" +msgstr "我可以在 C 中建立自己的函式嗎？" + +#: ../../faq/extending.rst:18 +msgid "" +"Yes, you can create built-in modules containing functions, variables, " +"exceptions and even new types in C. This is explained in the document :ref:" +"`extending-index`." +msgstr "" +"是的，你可以在 C 中建立包含函式、變數、例外甚至新型別的內建模組，:ref:" +"`extending-index` 文件中有相關說明。" + +#: ../../faq/extending.rst:22 +msgid "Most intermediate or advanced Python books will also cover this topic." +msgstr "大多數中級或進階 Python 書籍也會涵蓋這個主題。" + +#: ../../faq/extending.rst:26 +msgid "Can I create my own functions in C++?" +msgstr "我可以在 C++ 中建立自己的函式嗎？" + +#: ../../faq/extending.rst:28 +msgid "" +"Yes, using the C compatibility features found in C++. Place ``extern " +"\"C\" { ... }`` around the Python include files and put ``extern \"C\"`` " +"before each function that is going to be called by the Python interpreter. " +"Global or static C++ objects with constructors are probably not a good idea." +msgstr "" +"是的，可使用 C++ 中的 C 相容性功能。將 ``extern \"C\" { ... }`` 放在 Python 引入" +"檔案周圍，並將 ``extern \"C\"`` 放在每個將由 Python 直譯器呼叫的函式之前。" +"但具有構造函式的全域或靜態 C++ 物件可能不是一個好主意。" + +#: ../../faq/extending.rst:37 +msgid "Writing C is hard; are there any alternatives?" +msgstr "寫 C 很難；還有其他選擇嗎？" + +#: ../../faq/extending.rst:39 +msgid "" +"There are a number of alternatives to writing your own C extensions, " +"depending on what you're trying to do. :ref:`Recommended third party tools " +"` offer both simpler and more sophisticated approaches to " +"creating C and C++ extensions for Python." +msgstr "" + +#: ../../faq/extending.rst:46 +msgid "How can I execute arbitrary Python statements from C?" +msgstr "如何從 C 執行任意 Python 陳述式？" + +#: ../../faq/extending.rst:48 +msgid "" +"The highest-level function to do this is :c:func:`PyRun_SimpleString` which " +"takes a single string argument to be executed in the context of the module " +"``__main__`` and returns ``0`` for success and ``-1`` when an exception " +"occurred (including :exc:`SyntaxError`). If you want more control, use :c:" +"func:`PyRun_String`; see the source for :c:func:`PyRun_SimpleString` in " +"``Python/pythonrun.c``." +msgstr "" +"執行此操作的最高階函式是 :c:func:`PyRun_SimpleString`，它接受一個要在模組 " +"``__main__`` 的情境中執行的單一字串引數，成功時回傳 ``0``，發生例外（包" +"括 :exc:`SyntaxError`）時回傳 ``-1``。如果你想要更多控制，請使用 :c:" +"func:`PyRun_String`；請參閱 ``Python/pythonrun.c`` 中 :c:func:`PyRun_SimpleString` 的" +"原始碼。" + +#: ../../faq/extending.rst:57 +msgid "How can I evaluate an arbitrary Python expression from C?" +msgstr "如何計算來自 C 的任意 Python 運算式？" + +#: ../../faq/extending.rst:59 +msgid "" +"Call the function :c:func:`PyRun_String` from the previous question with the " +"start symbol :c:data:`Py_eval_input`; it parses an expression, evaluates it " +"and returns its value." +msgstr "" +"呼叫前一個問題中的 :c:func:`PyRun_String` 函式，並使用起始符號 :c:" +"data:`Py_eval_input`；它會剖析一個運算式，計算它並回傳它的值。" + +#: ../../faq/extending.rst:65 +msgid "How do I extract C values from a Python object?" +msgstr "如何從 Python 物件中提取 C 值？" + +#: ../../faq/extending.rst:67 +msgid "" +"That depends on the object's type. If it's a tuple, :c:func:`PyTuple_Size` " +"returns its length and :c:func:`PyTuple_GetItem` returns the item at a " +"specified index. Lists have similar functions, :c:func:`PyList_Size` and :c:" +"func:`PyList_GetItem`." +msgstr "" +"這取決於物件的型別。如果它是一個元組，:c:func:`PyTuple_Size` 會回傳它的長度，:" +"c:func:`PyTuple_GetItem` 則回傳指定索引的項目。串列具有類似的函式 :c:func:" +"`PyList_Size` 和 :c:func:`PyList_GetItem`。" + +#: ../../faq/extending.rst:72 +msgid "" +"For bytes, :c:func:`PyBytes_Size` returns its length and :c:func:" +"`PyBytes_AsStringAndSize` provides a pointer to its value and its length. " +"Note that Python bytes objects may contain null bytes so C's :c:func:`!" +"strlen` should not be used." +msgstr "" +"對於位元組，:c:func:`PyBytes_Size` 會回傳它的長度，:c:func:" +"`PyBytes_AsStringAndSize` 則提供指向該值與該長度的指標。請注意，Python 位元組物" +"件可能包含空位元組，因此不應使用 C 的 :c:func:`!strlen`。" + +#: ../../faq/extending.rst:77 +msgid "" +"To test the type of an object, first make sure it isn't ``NULL``, and then " +"use :c:func:`PyBytes_Check`, :c:func:`PyTuple_Check`, :c:func:" +"`PyList_Check`, etc." +msgstr "" +"要測試物件的型別，首先確保它不是 ``NULL``，然後再使用 :c:func:" +"`PyBytes_Check`、:c:func:`PyTuple_Check`、:c:func:`PyList_Check` 等函式。" + +#: ../../faq/extending.rst:80 +msgid "" +"There is also a high-level API to Python objects which is provided by the so-" +"called 'abstract' interface -- read ``Include/abstract.h`` for further " +"details. It allows interfacing with any kind of Python sequence using calls " +"like :c:func:`PySequence_Length`, :c:func:`PySequence_GetItem`, etc. as well " +"as many other useful protocols such as numbers (:c:func:`PyNumber_Index` et " +"al.) and mappings in the PyMapping APIs." +msgstr "" +"還有一個針對 Python 物件的高階 API，它由所謂的「抽象」介面所提供 —— 請閱讀 " +"``Include/abstract.h`` 以了解更多詳細資訊。它允許使用 :c:func:`PySequence_Length`" +"、:c:func:`PySequence_GetItem` 等函式的呼叫以及許多其他有用的協定，例如數值" +"（:c:func:`PyNumber_Index` 等）和 PyMapping API 中的對映，來與任何類型的 Python 序列做介接。" + +#: ../../faq/extending.rst:89 +msgid "How do I use Py_BuildValue() to create a tuple of arbitrary length?" +msgstr "如何使用 Py_BuildValue() 建立任意長度的元組？" + +#: ../../faq/extending.rst:91 +msgid "You can't. Use :c:func:`PyTuple_Pack` instead." +msgstr "這無法做到。請改用 :c:func:`PyTuple_Pack`。" + +#: ../../faq/extending.rst:95 +msgid "How do I call an object's method from C?" +msgstr "如何從 C 呼叫物件的方法？" + +#: ../../faq/extending.rst:97 +msgid "" +"The :c:func:`PyObject_CallMethod` function can be used to call an arbitrary " +"method of an object. The parameters are the object, the name of the method " +"to call, a format string like that used with :c:func:`Py_BuildValue`, and " +"the argument values::" +msgstr "" +":c:func:`PyObject_CallMethod` 函式可用於呼叫物件的任意方法。參數是物件、要呼" +"叫的方法名稱、與 :c:func:`Py_BuildValue` 一起使用的格式字串，以及引數" +"值： ::" + +#: ../../faq/extending.rst:102 +msgid "" +"PyObject *\n" +"PyObject_CallMethod(PyObject *object, const char *method_name,\n" +" const char *arg_format, ...);" +msgstr "" +"PyObject *\n" +"PyObject_CallMethod(PyObject *object, const char *method_name,\n" +" const char *arg_format, ...);" + +#: ../../faq/extending.rst:106 +msgid "" +"This works for any object that has methods -- whether built-in or user-" +"defined. You are responsible for eventually :c:func:`Py_DECREF`\\ 'ing the " +"return value." +msgstr "" +"這適用於任何具有方法的物件 —— 無論是內建的還是使用者定義的。你負責最終為回傳值來 :c:func:" +"`Py_DECREF`。" + +#: ../../faq/extending.rst:109 +msgid "" +"To call, e.g., a file object's \"seek\" method with arguments 10, 0 " +"(assuming the file object pointer is \"f\")::" +msgstr "" +"例如，使用引數 10、0 呼叫檔案物件的 \"seek\" 方法（假設檔案物件指標為 " +"\"f\"）： ::" + +#: ../../faq/extending.rst:112 +msgid "" +"res = PyObject_CallMethod(f, \"seek\", \"(ii)\", 10, 0);\n" +"if (res == NULL) {\n" +" ... an exception occurred ...\n" +"}\n" +"else {\n" +" Py_DECREF(res);\n" +"}" +msgstr "" +"res = PyObject_CallMethod(f, \"seek\", \"(ii)\", 10, 0);\n" +"if (res == NULL) {\n" +" ... 發生一個例外 ...\n" +"}\n" +"else {\n" +" Py_DECREF(res);\n" +"}" + +#: ../../faq/extending.rst:120 +msgid "" +"Note that since :c:func:`PyObject_CallObject` *always* wants a tuple for the " +"argument list, to call a function without arguments, pass \"()\" for the " +"format, and to call a function with one argument, surround the argument in " +"parentheses, e.g. \"(i)\"." +msgstr "" +"請注意，由於 :c:func:`PyObject_CallObject` *總是*\\ 需要一個元組作為引數列表，" +"若要呼叫一個不帶引數的函式，要傳遞 \"()\" 作為格式，並呼叫一個帶有一個引數的函式，" +"將引數括起來在括號中，例如 \"(i)\"。" + +#: ../../faq/extending.rst:127 +msgid "" +"How do I catch the output from PyErr_Print() (or anything that prints to " +"stdout/stderr)?" +msgstr "我如何捕捉 PyErr_Print() 的輸出（或任何印出到 stdout/stderr 的東西）？" + +#: ../../faq/extending.rst:129 +msgid "" +"In Python code, define an object that supports the ``write()`` method. " +"Assign this object to :data:`sys.stdout` and :data:`sys.stderr`. Call " +"print_error, or just allow the standard traceback mechanism to work. Then, " +"the output will go wherever your ``write()`` method sends it." +msgstr "" +"在 Python 程式碼中定義一個支援 ``write()`` 方法的物件。將此物件分配給 :" +"data:`sys.stdout` 和 :data:`sys.stderr`。呼叫 print_error，或者只允許標準的回" +"溯機制起作用。然後，輸出將會傳送到你的 ``write()`` 方法所指定的位置。" + +#: ../../faq/extending.rst:134 +msgid "The easiest way to do this is to use the :class:`io.StringIO` class:" +msgstr "最簡單的方法是使用 :class:`io.StringIO` 類別：" + +#: ../../faq/extending.rst:136 +msgid "" +">>> import io, sys\n" +">>> sys.stdout = io.StringIO()\n" +">>> print('foo')\n" +">>> print('hello world!')\n" +">>> sys.stderr.write(sys.stdout.getvalue())\n" +"foo\n" +"hello world!" +msgstr "" +">>> import io, sys\n" +">>> sys.stdout = io.StringIO()\n" +">>> print('foo')\n" +">>> print('hello world!')\n" +">>> sys.stderr.write(sys.stdout.getvalue())\n" +"foo\n" +"hello world!" + +#: ../../faq/extending.rst:146 +msgid "A custom object to do the same would look like this:" +msgstr "執行相同操作的自訂物件如下所示：" + +#: ../../faq/extending.rst:148 +msgid "" +">>> import io, sys\n" +">>> class StdoutCatcher(io.TextIOBase):\n" +"... def __init__(self):\n" +"... self.data = []\n" +"... def write(self, stuff):\n" +"... self.data.append(stuff)\n" +"...\n" +">>> import sys\n" +">>> sys.stdout = StdoutCatcher()\n" +">>> print('foo')\n" +">>> print('hello world!')\n" +">>> sys.stderr.write(''.join(sys.stdout.data))\n" +"foo\n" +"hello world!" +msgstr "" +">>> import io, sys\n" +">>> class StdoutCatcher(io.TextIOBase):\n" +"... def __init__(self):\n" +"... self.data = []\n" +"... def write(self, stuff):\n" +"... self.data.append(stuff)\n" +"...\n" +">>> import sys\n" +">>> sys.stdout = StdoutCatcher()\n" +">>> print('foo')\n" +">>> print('hello world!')\n" +">>> sys.stderr.write(''.join(sys.stdout.data))\n" +"foo\n" +"hello world!" + +#: ../../faq/extending.rst:167 +msgid "How do I access a module written in Python from C?" +msgstr "如何從 C 存取用 Python 編寫的模組？" + +#: ../../faq/extending.rst:169 +msgid "You can get a pointer to the module object as follows::" +msgstr "你可以取得指向模組物件的指標，如下所示： ::" + +#: ../../faq/extending.rst:171 +msgid "module = PyImport_ImportModule(\"\");" +msgstr "module = PyImport_ImportModule(\"\");" + +#: ../../faq/extending.rst:173 +msgid "" +"If the module hasn't been imported yet (i.e. it is not yet present in :data:" +"`sys.modules`), this initializes the module; otherwise it simply returns the " +"value of ``sys.modules[\"\"]``. Note that it doesn't enter the " +"module into any namespace -- it only ensures it has been initialized and is " +"stored in :data:`sys.modules`." +msgstr "" +"如果模組還沒有被引入（即它還沒有出現在 :data:`sys.modules` 中），這會初始化模" +"組；否則它只回傳 ``sys.modules[\"\"]`` 的值。請注意，它不會將模組" +"輸入任何命名空間——它只會確保它已被初始化並儲存在 :data:`sys.modules` 中。" + +#: ../../faq/extending.rst:179 +msgid "" +"You can then access the module's attributes (i.e. any name defined in the " +"module) as follows::" +msgstr "然後你可以存取模組的屬性（即模組中定義的任何名稱），如下所示： ::" + +#: ../../faq/extending.rst:182 +msgid "attr = PyObject_GetAttrString(module, \"\");" +msgstr "attr = PyObject_GetAttrString(module, \"\");" + +#: ../../faq/extending.rst:184 +msgid "" +"Calling :c:func:`PyObject_SetAttrString` to assign to variables in the " +"module also works." +msgstr "呼叫 :c:func:`PyObject_SetAttrString` 來分配模組中的變數也有效。" + +#: ../../faq/extending.rst:189 +msgid "How do I interface to C++ objects from Python?" +msgstr "我如何從 Python 介接到 C++ 物件？" + +#: ../../faq/extending.rst:191 +msgid "" +"Depending on your requirements, there are many approaches. To do this " +"manually, begin by reading :ref:`the \"Extending and Embedding\" document " +"`. Realize that for the Python run-time system, there " +"isn't a whole lot of difference between C and C++ -- so the strategy of " +"building a new Python type around a C structure (pointer) type will also " +"work for C++ objects." +msgstr "" +"根據你的要求不同而有多種不同方法。要手動執行此操作，請先閱讀\\ :ref:`「擴充和嵌入」說明" +"文件 `。對於 Python run-time 系統，C 和 C++ 之間並" +"沒有太多區別 —— 因此圍繞 C 結構（指標）型別來構建新 Python 型別的策略也適" +"用於 C++ 物件。" + +#: ../../faq/extending.rst:197 +msgid "For C++ libraries, see :ref:`c-wrapper-software`." +msgstr "對於 C++ 函式庫，請參閱 :ref:`c-wrapper-software`。" + +#: ../../faq/extending.rst:201 +msgid "I added a module using the Setup file and the make fails; why?" +msgstr "我使用安裝檔案新增了一個模組，但 make 失敗了；為什麼？" + +#: ../../faq/extending.rst:203 +msgid "" +"Setup must end in a newline, if there is no newline there, the build process " +"fails. (Fixing this requires some ugly shell script hackery, and this bug " +"is so minor that it doesn't seem worth the effort.)" +msgstr "" +"安裝程式必須以換行符結尾，如果那裡沒有換行符，構建過程將失敗。（解決這個問題" +"需要一些醜陋的 shell 腳本 hackery，而且這個錯誤很小，似乎不值得付出努力。）" + +#: ../../faq/extending.rst:209 +msgid "How do I debug an extension?" +msgstr "如何為擴充套件除錯？" + +#: ../../faq/extending.rst:211 +msgid "" +"When using GDB with dynamically loaded extensions, you can't set a " +"breakpoint in your extension until your extension is loaded." +msgstr "" +"將 GDB 與動態載入的擴充一起使用時，在載入擴充之前不能在擴充中設定斷點。" + +#: ../../faq/extending.rst:214 +msgid "In your ``.gdbinit`` file (or interactively), add the command:" +msgstr "在你的 ``.gdbinit`` 檔案中（或交互地），新增命令：" + +#: ../../faq/extending.rst:216 +msgid "br _PyImport_LoadDynamicModule" +msgstr "br _PyImport_LoadDynamicModule" + +#: ../../faq/extending.rst:220 +msgid "Then, when you run GDB:" +msgstr "然後，當你運行 GDB 時：" + +#: ../../faq/extending.rst:222 +msgid "" +"$ gdb /local/bin/python\n" +"gdb) run myscript.py\n" +"gdb) continue # repeat until your extension is loaded\n" +"gdb) finish # so that your extension is loaded\n" +"gdb) br myfunction.c:50\n" +"gdb) continue" +msgstr "" + +#: ../../faq/extending.rst:232 +msgid "" +"I want to compile a Python module on my Linux system, but some files are " +"missing. Why?" +msgstr "" +"我想在我的 Linux 系統上編譯一個 Python 模組，但是缺少一些檔案。為什麼？" + +#: ../../faq/extending.rst:234 +msgid "" +"Most packaged versions of Python omit some files required for compiling " +"Python extensions." +msgstr "大多數打包版本的 Python 省略了編譯 Python 擴充所需的一些檔案。" + +#: ../../faq/extending.rst:237 +msgid "For Red Hat, install the python3-devel RPM to get the necessary files." +msgstr "在 Red Hat 上，請安裝 python3-devel RPM 來取得必要的檔案。" + +#: ../../faq/extending.rst:239 +msgid "For Debian, run ``apt-get install python3-dev``." +msgstr "對於 Debian，運行 ``apt-get install python3-dev``。" + +#: ../../faq/extending.rst:242 +msgid "How do I tell \"incomplete input\" from \"invalid input\"?" +msgstr "如何從「無效輸入」區分出「不完整輸入」？" + +#: ../../faq/extending.rst:244 +msgid "" +"Sometimes you want to emulate the Python interactive interpreter's behavior, " +"where it gives you a continuation prompt when the input is incomplete (e.g. " +"you typed the start of an \"if\" statement or you didn't close your " +"parentheses or triple string quotes), but it gives you a syntax error " +"message immediately when the input is invalid." +msgstr "" +"有時你會想模擬 Python 交互式直譯器的行為，當輸入不完整時（例如，當你輸入了 \"if\" 陳述式的" +"開頭或者你沒有關閉你的括號或三重字串引號）它會給你一個繼續提示字元，" +"但是當輸入無效時，它會立即為你提供語法錯誤訊息。" + +#: ../../faq/extending.rst:250 +msgid "" +"In Python you can use the :mod:`codeop` module, which approximates the " +"parser's behavior sufficiently. IDLE uses this, for example." +msgstr "" +"在 Python 中，你可以使用 :mod:`codeop` 模組，它充分模擬了剖析器 (parser) 的行" +"為。像是 IDLE 就有使用它。" + +#: ../../faq/extending.rst:253 +msgid "" +"The easiest way to do it in C is to call :c:func:`PyRun_InteractiveLoop` " +"(perhaps in a separate thread) and let the Python interpreter handle the " +"input for you. You can also set the :c:func:`PyOS_ReadlineFunctionPointer` " +"to point at your custom input function. See ``Modules/readline.c`` and " +"``Parser/myreadline.c`` for more hints." +msgstr "" +"在 C 中執行此操作的最簡單方法是呼叫 :c:func:`PyRun_InteractiveLoop`\\ （可能是在單" +"獨的執行緒中）並讓 Python 直譯器為你處理輸入。你還可以將 :c:func:" +"`PyOS_ReadlineFunctionPointer` 設定為指向你的自訂輸入函式。有關更多提示，請" +"參閱 ``Modules/readline.c`` 和 ``Parser/myreadline.c``。" + +#: ../../faq/extending.rst:260 +msgid "How do I find undefined g++ symbols __builtin_new or __pure_virtual?" +msgstr "如何找到未定義的 g++ 符號 __builtin_new 或 __pure_virtual？" + +#: ../../faq/extending.rst:262 +msgid "" +"To dynamically load g++ extension modules, you must recompile Python, relink " +"it using g++ (change LINKCC in the Python Modules Makefile), and link your " +"extension module using g++ (e.g., ``g++ -shared -o mymodule.so mymodule.o``)." +msgstr "" +"要動態載入 g++ 擴充模組，你必須重新編譯 Python，並使用 g++ 重新鏈接它（更改 " +"Python 模組 Makefile 中的 LINKCC），且使用 g++ 鏈接你的擴充模組（例如，``g++ " +"-shared -o mymodule.so mymodule.o``）。" + +#: ../../faq/extending.rst:268 +msgid "" +"Can I create an object class with some methods implemented in C and others " +"in Python (e.g. through inheritance)?" +msgstr "" +"我可以用一些用 C 實作的方法和用 Python 實作的其他方法（例如透過繼承）建立一個" +"物件類別嗎？" + +#: ../../faq/extending.rst:270 +msgid "" +"Yes, you can inherit from built-in classes such as :class:`int`, :class:" +"`list`, :class:`dict`, etc." +msgstr "" +"是的，你可以繼承內建類別，例如 :class:`int`、:class:`list`、:class:`dict` " +"等。" + +#: ../../faq/extending.rst:273 +msgid "" +"The Boost Python Library (BPL, https://www.boost.org/libs/python/doc/index." +"html) provides a way of doing this from C++ (i.e. you can inherit from an " +"extension class written in C++ using the BPL)." +msgstr "" +"Boost Python 函式庫（BPL，https://www.boost.org/libs/python/doc/index.html）" +"提供了一種從 C++ 執行此操作的方法（即你可以使用 BPL 來繼承用 C++ 編寫的擴充類" +"別）。" diff --git a/faq/general.po b/faq/general.po index b5ec25461d..880163e478 100644 --- a/faq/general.po +++ b/faq/general.po @@ -1,892 +1,892 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# jerrychen , 2016 -# Ching-Lung Chuang, 2015 -# Steven Hsu , 2022 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-10-22 00:14+0000\n" -"PO-Revision-Date: 2023-06-23 16:56+0800\n" -"Last-Translator: Matt Wang \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" -"X-Generator: Poedit 3.3.1\n" - -#: ../../faq/general.rst:5 -msgid "General Python FAQ" -msgstr "一般的 Python 常見問答集" - -#: ../../faq/general.rst:8 -msgid "Contents" -msgstr "目錄" - -#: ../../faq/general.rst:13 -msgid "General Information" -msgstr "一般資訊" - -#: ../../faq/general.rst:16 -msgid "What is Python?" -msgstr "什麼是 Python？" - -#: ../../faq/general.rst:18 -msgid "" -"Python is an interpreted, interactive, object-oriented programming " -"language. It incorporates modules, exceptions, dynamic typing, very high " -"level dynamic data types, and classes. It supports multiple programming " -"paradigms beyond object-oriented programming, such as procedural and " -"functional programming. Python combines remarkable power with very clear " -"syntax. It has interfaces to many system calls and libraries, as well as to " -"various window systems, and is extensible in C or C++. It is also usable as " -"an extension language for applications that need a programmable interface. " -"Finally, Python is portable: it runs on many Unix variants including Linux " -"and macOS, and on Windows." -msgstr "" -"Python 是一種直譯的、互動的、物件導向的程式設計語言。它結合了模組、例外、動態" -"型別 (dynamic typing)、非常高階的動態資料型別，以及 class（類別）。它能支援物" -"件導向程式設計之外的多種程式設計典範，例如程序式 (procedural) 和函式語言 " -"(functional) 程式設計。Python 結合了卓越的功能與非常清晰的語法。它有許多系統" -"呼叫和函式庫的介面，以及各種視窗系統的介面，並且在 C 或 C++ 中可以擴充。它還" -"可以作為一種擴充語言，使用於需要可程式化介面 (programmable interface) 的應用" -"程式。最後，Python 是可攜的 (portable)：它能運行在許多 Unix 的變體上，包括 " -"Linux 和 macOS，也能運行在 Windows 上。" - -#: ../../faq/general.rst:28 -msgid "" -"To find out more, start with :ref:`tutorial-index`. The `Beginner's Guide " -"to Python `_ links to other " -"introductory tutorials and resources for learning Python." -msgstr "" -"要尋找更多內容，請從 :ref:`tutorial-index`\\ 開始。`Python 初學者指南 " -"`_\\ 可連結到其他介紹式教學以及" -"學習 Python 的資源。" - -#: ../../faq/general.rst:34 -msgid "What is the Python Software Foundation?" -msgstr "什麼是 Python 軟體基金會？" - -#: ../../faq/general.rst:36 -msgid "" -"The Python Software Foundation is an independent non-profit organization " -"that holds the copyright on Python versions 2.1 and newer. The PSF's " -"mission is to advance open source technology related to the Python " -"programming language and to publicize the use of Python. The PSF's home " -"page is at https://www.python.org/psf/." -msgstr "" -"Python 軟體基金會 (Python Software Foundation) 是一個獨立的非營利性組織，它擁" -"有 Python 2.1 版與之後各版本的版權。PSF 的使命在於推展 Python 程式設計語言相" -"關的開放原始碼技術，以及宣傳 Python 的使用。PSF 首頁的網址是 https://www." -"python.org/psf/。" - -#: ../../faq/general.rst:42 -msgid "" -"Donations to the PSF are tax-exempt in the US. If you use Python and find " -"it helpful, please contribute via `the PSF donation page `_." -msgstr "" -"在美國捐款給 PSF 是免稅的。如果你使用了 Python 且發現它很有用，請至 `PSF 捐款" -"頁面 `_\\ 為它做出貢獻。" - -#: ../../faq/general.rst:48 -msgid "Are there copyright restrictions on the use of Python?" -msgstr "使用 Python 時有任何版權限制嗎？" - -#: ../../faq/general.rst:50 -msgid "" -"You can do anything you want with the source, as long as you leave the " -"copyrights in and display those copyrights in any documentation about Python " -"that you produce. If you honor the copyright rules, it's OK to use Python " -"for commercial use, to sell copies of Python in source or binary form " -"(modified or unmodified), or to sell products that incorporate Python in " -"some form. We would still like to know about all commercial use of Python, " -"of course." -msgstr "" -"你可以對原始碼做任何你想做的事情，只要你保留版權，並且在你製作的任何關於 " -"Python 的說明文件中顯示這些版權即可。如果你遵守版權規則，就可以將 Python 用於" -"商業用途，以原始碼或二進制形式（修改或未修改）銷售 Python 的複本，或者以某種" -"形式銷售內含 Python 的產品。當然，我們仍然會想要知道所有的 Python 商業用途。" - -#: ../../faq/general.rst:57 -msgid "" -"See `the license page `_ to find " -"further explanations and the full text of the PSF License." -msgstr "" -"請參閱 `授權頁面 `_，查詢更深入的說明" -"和 PSF 授權全文的連結。" - -#: ../../faq/general.rst:60 -msgid "" -"The Python logo is trademarked, and in certain cases permission is required " -"to use it. Consult `the Trademark Usage Policy `__ for more information." -msgstr "" -"Python 標誌是註冊商標，在某些情況下需要許可才能使用它。請參閱\\ `商標使用政" -"策 `__\\ 以取得更多資訊。" - -#: ../../faq/general.rst:66 -msgid "Why was Python created in the first place?" -msgstr "當初為什麼 Python 會被創造出來？" - -#: ../../faq/general.rst:68 -msgid "" -"Here's a *very* brief summary of what started it all, written by Guido van " -"Rossum:" -msgstr "" -"以下是由 Guido van Rossum 所撰寫，關於這一切如何開始的\\ *非常*\\ 簡短的摘" -"要：" - -#: ../../faq/general.rst:71 -msgid "" -"I had extensive experience with implementing an interpreted language in the " -"ABC group at CWI, and from working with this group I had learned a lot about " -"language design. This is the origin of many Python features, including the " -"use of indentation for statement grouping and the inclusion of very-high-" -"level data types (although the details are all different in Python)." -msgstr "" -"我在 CWI 的 ABC 小組中擁有實作直譯語言方面的豐富經驗，而透過與該小組的合作，" -"我學到了很多關於語言設計的知識。這是許多 Python 功能的起源，包括使用縮排進行" -"陳述式分組以及納入非常高階的資料型別（儘管在 Python 中的細節都已經不同）。" - -#: ../../faq/general.rst:78 -msgid "" -"I had a number of gripes about the ABC language, but also liked many of its " -"features. It was impossible to extend the ABC language (or its " -"implementation) to remedy my complaints -- in fact its lack of extensibility " -"was one of its biggest problems. I had some experience with using Modula-2+ " -"and talked with the designers of Modula-3 and read the Modula-3 report. " -"Modula-3 is the origin of the syntax and semantics used for exceptions, and " -"some other Python features." -msgstr "" -"我對 ABC 語言有一些牢騷，但我也喜歡它的許多功能。想要擴充 ABC 語言（或其實" -"作）來去除我的抱怨是不可能的。事實上，缺乏可擴充性就是它最大的問題之一。我有" -"一些使用 Modula-2+ 的經驗，也與 Modula-3 的設計者交談過，並閱讀了 Modula-3 的" -"報告。Modula-3 就是用於例外及另外一些 Python 功能的語法和語義的起源。" - -#: ../../faq/general.rst:86 -msgid "" -"I was working in the Amoeba distributed operating system group at CWI. We " -"needed a better way to do system administration than by writing either C " -"programs or Bourne shell scripts, since Amoeba had its own system call " -"interface which wasn't easily accessible from the Bourne shell. My " -"experience with error handling in Amoeba made me acutely aware of the " -"importance of exceptions as a programming language feature." -msgstr "" -"我當時正在 CWI 的 Amoeba 分散式作業系統小組工作。我們需要一種比編寫 C 程式或 " -"Bourne shell 腳本更好的方法來進行系統管理，因為 Amoeba 有自己的系統呼叫介面，" -"而它無法簡單地從 Bourne shell 進行存取。我在 Amoeba 中處理錯誤的經驗，使我深" -"切地意識到例外作為程式設計語言功能的重要性。" - -#: ../../faq/general.rst:93 -msgid "" -"It occurred to me that a scripting language with a syntax like ABC but with " -"access to the Amoeba system calls would fill the need. I realized that it " -"would be foolish to write an Amoeba-specific language, so I decided that I " -"needed a language that was generally extensible." -msgstr "" -"我突然想到，一種具有類似 ABC 的語法但可以存取 Amoeba 系統呼叫的腳本語言將能滿" -"足該需求。我了解編寫 Amoeba 專用語言是愚蠢的，所以我決定，我需要一種可以廣泛" -"擴充的語言。" - -#: ../../faq/general.rst:98 -msgid "" -"During the 1989 Christmas holidays, I had a lot of time on my hand, so I " -"decided to give it a try. During the next year, while still mostly working " -"on it in my own time, Python was used in the Amoeba project with increasing " -"success, and the feedback from colleagues made me add many early " -"improvements." -msgstr "" -"在 1989 年的聖誕節假期，我有很多自由時間，所以我決定來嘗試一下。在接下來的一" -"年裡，雖然我大部分時間仍然在為此而努力，但 Python 在 Amoeba 專案中的使用得到" -"了越來越多的成功，且同事們的回饋也使我為它增加了許多早期的改進。" - -#: ../../faq/general.rst:104 -msgid "" -"In February 1991, after just over a year of development, I decided to post " -"to USENET. The rest is in the ``Misc/HISTORY`` file." -msgstr "" -"在 1991 年 2月，經過一年多的發展，我決定將它發表到 USENET。其他的記錄都在 " -"``Misc/HISTORY`` 檔案中。" - -#: ../../faq/general.rst:109 -msgid "What is Python good for?" -msgstr "什麼是 Python 擅長的事情？" - -#: ../../faq/general.rst:111 -msgid "" -"Python is a high-level general-purpose programming language that can be " -"applied to many different classes of problems." -msgstr "" -"Python 是一種高階的、用途廣泛的程式設計語言，可以用來解決許多不同類型的問題。" - -#: ../../faq/general.rst:114 -msgid "" -"The language comes with a large standard library that covers areas such as " -"string processing (regular expressions, Unicode, calculating differences " -"between files), internet protocols (HTTP, FTP, SMTP, XML-RPC, POP, IMAP), " -"software engineering (unit testing, logging, profiling, parsing Python " -"code), and operating system interfaces (system calls, filesystems, TCP/IP " -"sockets). Look at the table of contents for :ref:`library-index` to get an " -"idea of what's available. A wide variety of third-party extensions are also " -"available. Consult `the Python Package Index `_ to find " -"packages of interest to you." -msgstr "" -"這個語言提供了一個大型的標準函式庫，涵蓋了字串處理（正規表示式、Unicode、檔案" -"之間的差異計算）、網際網路協定（HTTP、FTP、SMTP、XML-RPC、POP、IMAP）、軟體工" -"程（單元測試、日誌記錄、效能分析、剖析 Python 程式碼）以及作業系統介面（系統" -"呼叫、檔案系統、TCP/IP 插座 (socket)）等領域。請查看 :ref:`library-index` 的" -"目錄，以了解可用的函式。此外，還有各式各樣的第三方擴充。請查詢 `Python 套件索" -"引 (Python Package Index) `_ 來尋找你有興趣的套件。" - -#: ../../faq/general.rst:128 -msgid "How does the Python version numbering scheme work?" -msgstr "Python 的版本編號系統是如何運作的？" - -#: ../../faq/general.rst:130 -msgid "Python versions are numbered \"A.B.C\" or \"A.B\":" -msgstr "Python 各版本會被編號為 \"A.B.C\" 或 \"A.B\"：" - -#: ../../faq/general.rst:132 -msgid "" -"*A* is the major version number -- it is only incremented for really major " -"changes in the language." -msgstr "*A* 為主要版本編號 -- 它只會在語言中有真正重大的變更時才會增加。" - -#: ../../faq/general.rst:134 -msgid "" -"*B* is the minor version number -- it is incremented for less earth-" -"shattering changes." -msgstr "*B* 為次要版本編號 -- 只有在影響範圍較小的變更出現時增加。" - -#: ../../faq/general.rst:136 -msgid "" -"*C* is the micro version number -- it is incremented for each bugfix release." -msgstr "*C* 為微小版本編號 —- 會在每個錯誤修正發布 (bugfix release) 增加。" - -#: ../../faq/general.rst:138 -msgid "" -"Not all releases are bugfix releases. In the run-up to a new feature " -"release, a series of development releases are made, denoted as alpha, beta, " -"or release candidate. Alphas are early releases in which interfaces aren't " -"yet finalized; it's not unexpected to see an interface change between two " -"alpha releases. Betas are more stable, preserving existing interfaces but " -"possibly adding new modules, and release candidates are frozen, making no " -"changes except as needed to fix critical bugs." -msgstr "" -"並非所有的發布版本都是錯誤修正發布版本。在一個新功能發布版本的準備階段，會發" -"布一系列開發版本，標示為 alpha、beta 或候選發布版本 (release candidate)。" -"Alpha 是介面尚未最終化的早期發布版本；看到兩個 alpha 發布版本之間的介面變更並" -"不會令人意外。Beta 則更為穩定，保留了現有的介面，但可能會增加新的模組，而候選" -"發布版本會被凍結，除了需要修正關鍵錯誤之外，不會再進行任何變更。" - -#: ../../faq/general.rst:146 -msgid "Alpha, beta and release candidate versions have an additional suffix:" -msgstr "Alpha、beta 和候選發布版本都有一個額外的後綴：" - -#: ../../faq/general.rst:148 -msgid "The suffix for an alpha version is \"aN\" for some small number *N*." -msgstr "Alpha 版本的後綴是 \"aN\"，其中 *N* 是某個較小的數字。" - -#: ../../faq/general.rst:149 -msgid "The suffix for a beta version is \"bN\" for some small number *N*." -msgstr "Beta 版本的後綴是 \"bN\"，其中 *N* 是某個較小的數字。" - -#: ../../faq/general.rst:150 -msgid "" -"The suffix for a release candidate version is \"rcN\" for some small number " -"*N*." -msgstr "候選發布版本的後綴是 \"rcN\"，其中 *N* 是某個較小的數字。" - -#: ../../faq/general.rst:152 -msgid "" -"In other words, all versions labeled *2.0aN* precede the versions labeled " -"*2.0bN*, which precede versions labeled *2.0rcN*, and *those* precede 2.0." -msgstr "" -"換句話說，所有標記為 *2.0aN* 的版本都在標記為 *2.0bN* 的版本之前，而 *2.0bN* " -"版本都在標記為 *2.0rcN* 的版本之前，而\\ *它們*\\ 都是在 2.0 版之前。" - -#: ../../faq/general.rst:155 -msgid "" -"You may also find version numbers with a \"+\" suffix, e.g. \"2.2+\". These " -"are unreleased versions, built directly from the CPython development " -"repository. In practice, after a final minor release is made, the version " -"is incremented to the next minor version, which becomes the \"a0\" version, " -"e.g. \"2.4a0\"." -msgstr "" -"你還可以找到帶有「+」後綴的版本編號，例如「2.2+」。這些是未發布的版本，直接" -"從 CPython 的開發儲存庫被建置。實際上，在每一次的最終次要版本發布完成之後，版" -"本編號將會被增加到下一個次要版本，並成為「a0」版，例如「2.4a0」。" - -#: ../../faq/general.rst:160 -msgid "" -"See the `Developer's Guide `__ for more information about the development cycle, " -"and :pep:`387` to learn more about Python's backward compatibility policy. " -"See also the documentation for :data:`sys.version`, :data:`sys.hexversion`, " -"and :data:`sys.version_info`." -msgstr "" -"請參閱\\ `開發人員指南 `__\\ 以獲得更多關於開發週期的資訊，並參閱 :pep:`387` 以瞭" -"解更多關於 Python 的向後相容性政策。另外，也請查看 :data:`sys.version`、:" -"data:`sys.hexversion` 和 :data:`sys.version_info` 的說明文件。" - -#: ../../faq/general.rst:169 -msgid "How do I obtain a copy of the Python source?" -msgstr "我要如何得到 Python 的原始碼複本？" - -#: ../../faq/general.rst:171 -msgid "" -"The latest Python source distribution is always available from python.org, " -"at https://www.python.org/downloads/. The latest development sources can be " -"obtained at https://github.com/python/cpython/." -msgstr "" -"最新的 Python 原始碼發行版永遠可以從 python.org 取得，在 https://www.python." -"org/downloads/。最新的開發中原始碼可以在 https://github.com/python/cpython/ " -"取得。" - -#: ../../faq/general.rst:175 -msgid "" -"The source distribution is a gzipped tar file containing the complete C " -"source, Sphinx-formatted documentation, Python library modules, example " -"programs, and several useful pieces of freely distributable software. The " -"source will compile and run out of the box on most UNIX platforms." -msgstr "" -"原始碼發行版是一個以 gzip 壓縮的 tar 檔，它包含完整的 C 原始碼、Sphinx 格式的" -"說明文件、Python 函式庫模組、範例程式，以及幾個好用的可自由發行軟體。該原始碼" -"在大多數 UNIX 平台上，都是可以立即編譯及運行的。" - -#: ../../faq/general.rst:180 -msgid "" -"Consult the `Getting Started section of the Python Developer's Guide " -"`__ for more information on getting the " -"source code and compiling it." -msgstr "" -"關於取得和編譯原始碼的詳細資訊，請參閱 `Python 開發人員指南中的 \"Getting " -"Started\" 段落 `__。" - -#: ../../faq/general.rst:186 -msgid "How do I get documentation on Python?" -msgstr "我要如何取得 Python 的說明文件？" - -#: ../../faq/general.rst:188 -msgid "" -"The standard documentation for the current stable version of Python is " -"available at https://docs.python.org/3/. EPUB, plain text, and downloadable " -"HTML versions are also available at https://docs.python.org/3/download.html." -msgstr "" -"Python 目前穩定版本的標準說明文件可在 https://docs.python.org/3/ 找到。EPUB、" -"純文字和可下載的 HTML 版本也可在 https://docs.python.org/3/download.html 找" -"到。" - -#: ../../faq/general.rst:192 -msgid "" -"The documentation is written in reStructuredText and processed by `the " -"Sphinx documentation tool `__. The " -"reStructuredText source for the documentation is part of the Python source " -"distribution." -msgstr "" -"說明文件是以 reStructuredText 格式編寫，並由 `Sphinx 說明文件工具 `__\\ 處理。說明文件的 reStructuredText 原始碼是 Python 原始" -"碼發行版的一部分。" - -#: ../../faq/general.rst:198 -msgid "I've never programmed before. Is there a Python tutorial?" -msgstr "我從來沒有寫過程式，有沒有 Python 的教學？" - -#: ../../faq/general.rst:200 -msgid "" -"There are numerous tutorials and books available. The standard " -"documentation includes :ref:`tutorial-index`." -msgstr "有許多可用的教學和書籍。標準說明文件包括 :ref:`tutorial-index`。" - -#: ../../faq/general.rst:203 -msgid "" -"Consult `the Beginner's Guide `_ to find information for beginning Python programmers, " -"including lists of tutorials." -msgstr "" -"要尋找 Python 程式設計初學者的資訊，包括教學資源列表，請參閱\\ `初學者指南 " -"`_。" - -#: ../../faq/general.rst:208 -msgid "Is there a newsgroup or mailing list devoted to Python?" -msgstr "有沒有 Python 專屬的新聞群組或郵件討論群？" - -#: ../../faq/general.rst:210 -msgid "" -"There is a newsgroup, :newsgroup:`comp.lang.python`, and a mailing list, " -"`python-list `_. The " -"newsgroup and mailing list are gatewayed into each other -- if you can read " -"news it's unnecessary to subscribe to the mailing list. :newsgroup:`comp." -"lang.python` is high-traffic, receiving hundreds of postings every day, and " -"Usenet readers are often more able to cope with this volume." -msgstr "" -"有一個新聞群組 (newsgroup)，:newsgroup:`comp.lang.python`，也有一個郵件討論" -"群 (mailing list)，`python-list `_。新聞群組和郵件討論群是彼此相通的——如果你能閱讀新聞，則無需加" -"入郵件討論群。:newsgroup:`comp.lang.python` 的流量很高，每天會收到數百篇文" -"章，而 Usenet 的讀者通常較能夠處理這樣的文章數量。" - -#: ../../faq/general.rst:217 -msgid "" -"Announcements of new software releases and events can be found in comp.lang." -"python.announce, a low-traffic moderated list that receives about five " -"postings per day. It's available as `the python-announce mailing list " -"`_." -msgstr "" -"新的軟體發布版本及事件的通知，可以在 comp.lang.python.announce 中找到，這是一" -"個低流量的精選討論群，每天收到大約五篇文章。它也能從 `python-announce 郵件討" -"論群 `_\\ 的頁面中訂閱。" - -#: ../../faq/general.rst:222 -msgid "" -"More info about other mailing lists and newsgroups can be found at https://" -"www.python.org/community/lists/." -msgstr "" -"關於其他郵件討論群和新聞群組的更多資訊，可以在 https://www.python.org/" -"community/lists/ 中找到。" - -#: ../../faq/general.rst:227 -msgid "How do I get a beta test version of Python?" -msgstr "如何取得 Python 的 beta 測試版本？" - -#: ../../faq/general.rst:229 -msgid "" -"Alpha and beta releases are available from https://www.python.org/" -"downloads/. All releases are announced on the comp.lang.python and comp." -"lang.python.announce newsgroups and on the Python home page at https://www." -"python.org/; an RSS feed of news is available." -msgstr "" -"Alpha 和 beta 發布版本可以從 https://www.python.org/downloads/ 取得。所有的發" -"布版本都會在 comp.lang.python 和 comp.lang.python.announce 新聞群組上宣布，也" -"會在 Python 首頁 https://www.python.org/ 中宣布；RSS 新聞摘要也是可使用的。" - -#: ../../faq/general.rst:234 -msgid "" -"You can also access the development version of Python through Git. See `The " -"Python Developer's Guide `_ for details." -msgstr "" -"你也可以藉由 Git 來存取 Python 的開發版本。更多詳細資訊，請參閱 `Python 開發" -"人員指南 `_。" - -#: ../../faq/general.rst:239 -msgid "How do I submit bug reports and patches for Python?" -msgstr "如何提交 Python 的錯誤報告和修補程式？" - -#: ../../faq/general.rst:241 -msgid "" -"To report a bug or submit a patch, use the issue tracker at https://github." -"com/python/cpython/issues." -msgstr "" -"要回報一個錯誤 (bug) 或提交一個修補程式 (patch)，請使用於 https://github.com/" -"python/cpython/issues 的問題追蹤系統。" - -#: ../../faq/general.rst:244 -msgid "" -"For more information on how Python is developed, consult `the Python " -"Developer's Guide `_." -msgstr "" -"關於如何開發 Python 的更多資訊，請參閱 `Python 開發人員指南 `_。" - -#: ../../faq/general.rst:249 -msgid "Are there any published articles about Python that I can reference?" -msgstr "是否有關於 Python 的任何已出版文章可供參考？" - -#: ../../faq/general.rst:251 -msgid "It's probably best to cite your favorite book about Python." -msgstr "也許最好是引用你最喜歡的關於 Python 的書。" - -#: ../../faq/general.rst:253 -msgid "" -"The `very first article `_ about Python was " -"written in 1991 and is now quite outdated." -msgstr "" -"`最早討論 Python 的文章 `_\\ 是在 1991 年寫的，" -"但現在來看已經過時了。" - -#: ../../faq/general.rst:256 -msgid "" -"Guido van Rossum and Jelke de Boer, \"Interactively Testing Remote Servers " -"Using the Python Programming Language\", CWI Quarterly, Volume 4, Issue 4 " -"(December 1991), Amsterdam, pp 283--303." -msgstr "" -"Guido van Rossum 和 Jelke de Boer，「使用 Python 程式設計語言互動式測試遠端伺" -"服器」，CWI 季刊，第 4 卷，第 4 期（1991 年 12 月），阿姆斯特丹，第 283–303 " -"頁。" - -#: ../../faq/general.rst:262 -msgid "Are there any books on Python?" -msgstr "有沒有關於 Python 的書？" - -#: ../../faq/general.rst:264 -msgid "" -"Yes, there are many, and more are being published. See the python.org wiki " -"at https://wiki.python.org/moin/PythonBooks for a list." -msgstr "" -"有，很多書已經出版，也有更多正在出版中的書。請參閱 python.org 的 wiki 在 " -"https://wiki.python.org/moin/PythonBooks 頁面中的書目清單。" - -#: ../../faq/general.rst:267 -msgid "" -"You can also search online bookstores for \"Python\" and filter out the " -"Monty Python references; or perhaps search for \"Python\" and \"language\"." -msgstr "" -"你也可以在網路書店搜尋關鍵字「Python」，並過濾掉 Monty Python 的結果；或者可" -"以搜尋「Python」和「語言」。" - -#: ../../faq/general.rst:272 -msgid "Where in the world is www.python.org located?" -msgstr "www.python.org 的真實位置在哪裡？" - -#: ../../faq/general.rst:274 -msgid "" -"The Python project's infrastructure is located all over the world and is " -"managed by the Python Infrastructure Team. Details `here `__." -msgstr "" -"Python 專案的基礎建設遍佈世界各地，由 Python 基礎建設團隊管理。詳細資訊\\ `在" -"此 `__。" - -#: ../../faq/general.rst:279 -msgid "Why is it called Python?" -msgstr "為什麼要取名為 Python？" - -#: ../../faq/general.rst:281 -msgid "" -"When he began implementing Python, Guido van Rossum was also reading the " -"published scripts from `\"Monty Python's Flying Circus\" `__, a BBC comedy series from the 1970s. " -"Van Rossum thought he needed a name that was short, unique, and slightly " -"mysterious, so he decided to call the language Python." -msgstr "" -"當 Guido van Rossum 開始實作 Python 時，他也正在閱讀 1970 年代 BBC 喜劇節目" -"\\ `「Monty Python 的飛行馬戲團」 `__\\ 的出版劇本。Van Rossum 認為他需要一個簡短、獨特且略帶神秘" -"的名字，因此他決定將該語言稱為 Python。" - -#: ../../faq/general.rst:289 -msgid "Do I have to like \"Monty Python's Flying Circus\"?" -msgstr "我需要喜歡「Monty Python 的飛行馬戲團」嗎？" - -#: ../../faq/general.rst:291 -msgid "No, but it helps. :)" -msgstr "不需要，但它有幫助。:)" - -#: ../../faq/general.rst:295 -msgid "Python in the real world" -msgstr "在真實世界中的 Python" - -#: ../../faq/general.rst:298 -msgid "How stable is Python?" -msgstr "Python 的穩定性如何？" - -#: ../../faq/general.rst:300 -msgid "" -"Very stable. New, stable releases have been coming out roughly every 6 to " -"18 months since 1991, and this seems likely to continue. As of version 3.9, " -"Python will have a new feature release every 12 months (:pep:`602`)." -msgstr "" -"非常穩定。自從 1991 年開始，大約每隔 6 到 18 個月都會發布新的穩定版本，而且這" -"看起來會繼續進行。從 3.9 版開始，Python 每隔 12 個月將會釋出一個新功能發行版" -"本 (:pep:`602`)。" - -#: ../../faq/general.rst:304 -msgid "" -"The developers issue bugfix releases of older versions, so the stability of " -"existing releases gradually improves. Bugfix releases, indicated by a third " -"component of the version number (e.g. 3.5.3, 3.6.2), are managed for " -"stability; only fixes for known problems are included in a bugfix release, " -"and it's guaranteed that interfaces will remain the same throughout a series " -"of bugfix releases." -msgstr "" -"開發人員會釋出針對先前版本的錯誤修正發布版本，因此現有發布版本的穩定性會逐漸" -"提高。錯誤修正發布版本是由版本編號的第三個部分表示（例如 3.5.3，3.6.2），這些" -"版本會被用於改善穩定性；在錯誤修正發布版本中，只會包含針對已知問題的修正，並" -"且會保證介面在一系列的錯誤修正發布版本中維持不變。" - -#: ../../faq/general.rst:311 -msgid "" -"The latest stable releases can always be found on the `Python download page " -"`_. Python 3.x is the recommended version " -"and supported by most widely used libraries. Python 2.x :pep:`is not " -"maintained anymore <373>`." -msgstr "" -"最新的穩定發布版本隨時都可以在 `Python 下載頁面 `_\\ 上找到。Python 3.x 是推薦的版本，並且被大多數廣泛使用的函式庫" -"所支援。Python 2.x :pep:`已不再被維護 <0373>`。" - -#: ../../faq/general.rst:317 -msgid "How many people are using Python?" -msgstr "有多少人在使用 Python？" - -#: ../../faq/general.rst:319 -msgid "" -"There are probably millions of users, though it's difficult to obtain an " -"exact count." -msgstr "可能有幾百萬個使用者，但實際的數量是難以確定的。" - -#: ../../faq/general.rst:322 -msgid "" -"Python is available for free download, so there are no sales figures, and " -"it's available from many different sites and packaged with many Linux " -"distributions, so download statistics don't tell the whole story either." -msgstr "" -"Python 是可以免費下載的，所以不會有銷售數據，而且它可以從許多不同的網站取得，" -"並與許多 Linux 發行版套裝在一起，所以下載次數的統計也無法反映完整的情況。" - -#: ../../faq/general.rst:326 -msgid "" -"The comp.lang.python newsgroup is very active, but not all Python users post " -"to the group or even read it." -msgstr "" -"comp.lang.python 新聞群組非常活躍，但並非所有 Python 使用者都會在該群組發表文" -"章或甚至閱讀它。" - -#: ../../faq/general.rst:331 -msgid "Have any significant projects been done in Python?" -msgstr "有沒有任何重要的專案使用 Python 完成開發？" - -#: ../../faq/general.rst:333 -msgid "" -"See https://www.python.org/about/success for a list of projects that use " -"Python. Consulting the proceedings for `past Python conferences `_ will reveal contributions from many " -"different companies and organizations." -msgstr "" -"要查看使用 Python 的專案清單，請參閱 https://www.python.org/about/success。藉" -"由查詢\\ `過去的 Python 會議記錄 `_\\ 可以看見來自許多不同公司和組織的貢獻。" - -#: ../../faq/general.rst:338 -msgid "" -"High-profile Python projects include `the Mailman mailing list manager " -"`_ and `the Zope application server `_. Several Linux distributions, most notably `Red Hat `_, have written part or all of their installer and system " -"administration software in Python. Companies that use Python internally " -"include Google, Yahoo, and Lucasfilm Ltd." -msgstr "" -"備受矚目的 Python 專案包括 `Mailman 郵件討論群管理員 `_\\ 和 `Zope 應用程式伺服器 `_。有一些 Linux 發行" -"版，最著名的是 `Red Hat `_，已經用 Python 編寫了部分" -"或全部的安裝程式及系統管理軟體。內部使用 Python 的公司包括 Google、Yahoo 和 " -"Lucasfilm Ltd。" - -#: ../../faq/general.rst:347 -msgid "What new developments are expected for Python in the future?" -msgstr "Python 未來預期會有哪些新的開發？" - -#: ../../faq/general.rst:349 -msgid "" -"See https://peps.python.org/ for the Python Enhancement Proposals (PEPs). " -"PEPs are design documents describing a suggested new feature for Python, " -"providing a concise technical specification and a rationale. Look for a PEP " -"titled \"Python X.Y Release Schedule\", where X.Y is a version that hasn't " -"been publicly released yet." -msgstr "" -"請至 https://peps.python.org/ 參閱 Python 增強提案 (Python Enhancement " -"Proposal, PEP)。PEP 是用來描述一項被建議的 Python 新功能的設計文件，它提供了" -"簡潔的技術規範及基本原理。請尋找一篇名為「Python X.Y Release Schedule（發布時" -"程表）」的 PEP，其中 X.Y 是一個尚未公開發布的版本。" - -#: ../../faq/general.rst:355 -msgid "" -"New development is discussed on `the python-dev mailing list `_." -msgstr "" -"新的開發會在 `python-dev 郵件討論群 `_\\ 中討論。" - -#: ../../faq/general.rst:360 -msgid "Is it reasonable to propose incompatible changes to Python?" -msgstr "對 Python 提出不相容的變更建議是否適當？" - -#: ../../faq/general.rst:362 -msgid "" -"In general, no. There are already millions of lines of Python code around " -"the world, so any change in the language that invalidates more than a very " -"small fraction of existing programs has to be frowned upon. Even if you can " -"provide a conversion program, there's still the problem of updating all " -"documentation; many books have been written about Python, and we don't want " -"to invalidate them all at a single stroke." -msgstr "" -"一般來說，不適當。全世界已經有數百萬行 Python 程式碼，因此在語言中的任何變" -"更，若會使現有程式的一小部分成為無效，它都是不被允許的。即使你可以提供轉換程" -"式，仍然會有需要更新全部說明文件的問題；市面上已經有很多介紹 Python 的書，而" -"我們不想一下子就把它們都變為無效。" - -#: ../../faq/general.rst:369 -msgid "" -"Providing a gradual upgrade path is necessary if a feature has to be " -"changed. :pep:`5` describes the procedure followed for introducing backward-" -"incompatible changes while minimizing disruption for users." -msgstr "" -"如果一項功能必須被變更，那麼一定要提供逐步升級的路徑。:pep:`5` 描述了要引進反" -"向不相容 (backward-incompatible) 的變更，同時也要對使用者的擾亂最小化，所需遵" -"循的程序。" - -#: ../../faq/general.rst:375 -msgid "Is Python a good language for beginning programmers?" -msgstr "Python 對於入門的程式設計師而言是否為好的語言？" - -#: ../../faq/general.rst:377 -msgid "Yes." -msgstr "是的。" - -#: ../../faq/general.rst:379 -msgid "" -"It is still common to start students with a procedural and statically typed " -"language such as Pascal, C, or a subset of C++ or Java. Students may be " -"better served by learning Python as their first language. Python has a very " -"simple and consistent syntax and a large standard library and, most " -"importantly, using Python in a beginning programming course lets students " -"concentrate on important programming skills such as problem decomposition " -"and data type design. With Python, students can be quickly introduced to " -"basic concepts such as loops and procedures. They can probably even work " -"with user-defined objects in their very first course." -msgstr "" -"學生們仍然普遍地會從一種程序語言和靜態型別語言 (statically typed language) 開" -"始入門，這些語言像是 Pascal、C，或是 C++ 或 Java 的某個子集。透過學習 Python " -"作為他們的第一個語言，學生們可能會學得更好。Python 具有非常簡單且一致的語法和" -"一個大型的標準函式庫，最重要的是，在入門程式設計課程中使用 Python 可以讓學生" -"專注於重要的程式設計技巧，例如問題的分解和資料型別的設計。使用 Python，可以快" -"速地向學生介紹基本觀念，例如迴圈和程序。他們甚至可能在第一堂課中就學到使用者" -"自訂的物件。" - -#: ../../faq/general.rst:389 -msgid "" -"For a student who has never programmed before, using a statically typed " -"language seems unnatural. It presents additional complexity that the " -"student must master and slows the pace of the course. The students are " -"trying to learn to think like a computer, decompose problems, design " -"consistent interfaces, and encapsulate data. While learning to use a " -"statically typed language is important in the long term, it is not " -"necessarily the best topic to address in the students' first programming " -"course." -msgstr "" -"對於以前從未進行過程式設計的學生來說，使用靜態型別語言似乎是不自然的。它使學" -"生必須掌握額外的複雜性，並減慢了課程的節奏。學生們正在試圖學著像電腦一樣思" -"考、分解問題、設計一致的介面，並封裝資料。雖然從長遠來看，學習使用靜態型別語" -"言很重要，但在學生的第一堂程式設計課程中，它不一定是最好的課程主題。" - -#: ../../faq/general.rst:397 -msgid "" -"Many other aspects of Python make it a good first language. Like Java, " -"Python has a large standard library so that students can be assigned " -"programming projects very early in the course that *do* something. " -"Assignments aren't restricted to the standard four-function calculator and " -"check balancing programs. By using the standard library, students can gain " -"the satisfaction of working on realistic applications as they learn the " -"fundamentals of programming. Using the standard library also teaches " -"students about code reuse. Third-party modules such as PyGame are also " -"helpful in extending the students' reach." -msgstr "" -"Python 的許多其他面向使它成為一種很好的第一語言。像 Java 一樣，Python 有一個" -"大型的標準函式庫，因此學生可以在課程的早期就被指派程式設計的專案，且這些專案" -"能夠\\ *做*\\ 一些事情。指派的內容不會侷限於標準的四功能計算機和平衡檢驗程" -"式。透過使用標準函式庫，學生可以在學習程式設計基礎知識的同時，獲得處理真實應" -"用程式的滿足感。使用標準函式庫還可以教導學生程式碼再使用 (code reuse) 的課" -"題。像是 PyGame 等第三方模組也有助於延伸學生的學習領域。" - -#: ../../faq/general.rst:406 -msgid "" -"Python's interactive interpreter enables students to test language features " -"while they're programming. They can keep a window with the interpreter " -"running while they enter their program's source in another window. If they " -"can't remember the methods for a list, they can do something like this::" -msgstr "" -"Python 的互動式直譯器使學生能夠在程式設計時測試語言的功能。他們可以開著一個運" -"行直譯器的視窗，同時在另一個視窗中輸入他們的程式原始碼。如果他們不記得 list" -"（串列）的 method（方法），他們可以像這樣做： ::" - -#: ../../faq/general.rst:411 -msgid "" -">>> L = []\n" -">>> dir(L)\n" -"['__add__', '__class__', '__contains__', '__delattr__', '__delitem__',\n" -"'__dir__', '__doc__', '__eq__', '__format__', '__ge__',\n" -"'__getattribute__', '__getitem__', '__gt__', '__hash__', '__iadd__',\n" -"'__imul__', '__init__', '__iter__', '__le__', '__len__', '__lt__',\n" -"'__mul__', '__ne__', '__new__', '__reduce__', '__reduce_ex__',\n" -"'__repr__', '__reversed__', '__rmul__', '__setattr__', '__setitem__',\n" -"'__sizeof__', '__str__', '__subclasshook__', 'append', 'clear',\n" -"'copy', 'count', 'extend', 'index', 'insert', 'pop', 'remove',\n" -"'reverse', 'sort']\n" -">>> [d for d in dir(L) if '__' not in d]\n" -"['append', 'clear', 'copy', 'count', 'extend', 'index', 'insert', 'pop', " -"'remove', 'reverse', 'sort']\n" -"\n" -">>> help(L.append)\n" -"Help on built-in function append:\n" -"\n" -"append(...)\n" -" L.append(object) -> None -- append object to end\n" -"\n" -">>> L.append(1)\n" -">>> L\n" -"[1]" -msgstr "" -">>> L = []\n" -">>> dir(L)\n" -"['__add__', '__class__', '__contains__', '__delattr__', '__delitem__',\n" -"'__dir__', '__doc__', '__eq__', '__format__', '__ge__',\n" -"'__getattribute__', '__getitem__', '__gt__', '__hash__', '__iadd__',\n" -"'__imul__', '__init__', '__iter__', '__le__', '__len__', '__lt__',\n" -"'__mul__', '__ne__', '__new__', '__reduce__', '__reduce_ex__',\n" -"'__repr__', '__reversed__', '__rmul__', '__setattr__', '__setitem__',\n" -"'__sizeof__', '__str__', '__subclasshook__', 'append', 'clear',\n" -"'copy', 'count', 'extend', 'index', 'insert', 'pop', 'remove',\n" -"'reverse', 'sort']\n" -">>> [d for d in dir(L) if '__' not in d]\n" -"['append', 'clear', 'copy', 'count', 'extend', 'index', 'insert', 'pop', " -"'remove', 'reverse', 'sort']\n" -"\n" -">>> help(L.append)\n" -"Help on built-in function append:\n" -"\n" -"append(...)\n" -" L.append(object) -> None -- append object to end\n" -"\n" -">>> L.append(1)\n" -">>> L\n" -"[1]" - -#: ../../faq/general.rst:435 -msgid "" -"With the interpreter, documentation is never far from the student as they " -"are programming." -msgstr "有了直譯器，當學生正在程式設計時，說明文件永遠都不會遠離他們。" - -#: ../../faq/general.rst:438 -msgid "" -"There are also good IDEs for Python. IDLE is a cross-platform IDE for " -"Python that is written in Python using Tkinter. Emacs users will be happy to " -"know that there is a very good Python mode for Emacs. All of these " -"programming environments provide syntax highlighting, auto-indenting, and " -"access to the interactive interpreter while coding. Consult `the Python " -"wiki `_ for a full list of " -"Python editing environments." -msgstr "" -"Python 也有很好的 IDE。IDLE 是 Python 的一個跨平臺 IDE，它以 Python 編寫並使" -"用 Tkinter。Emacs 使用者會很高興知道 Emacs 有一個非常好的 Python 模式。這些程" -"式設計環境全部都能提供語法突顯 (syntax highlighting)、自動縮排，以及在編寫程" -"式時存取互動式直譯器。要查看 Python 編輯環境的完整清單，請參閱 `Python wiki " -"`_。" - -#: ../../faq/general.rst:446 -msgid "" -"If you want to discuss Python's use in education, you may be interested in " -"joining `the edu-sig mailing list `_." -msgstr "" -"如果你想討論 Python 在教育領域中的使用，你可能會有興趣加入 `edu-sig 郵件討論" -"群 `_。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# jerrychen , 2016 +# Ching-Lung Chuang, 2015 +# Steven Hsu , 2022 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-10-22 00:14+0000\n" +"PO-Revision-Date: 2023-06-23 16:56+0800\n" +"Last-Translator: Matt Wang \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" +"X-Generator: Poedit 3.3.1\n" + +#: ../../faq/general.rst:5 +msgid "General Python FAQ" +msgstr "一般的 Python 常見問答集" + +#: ../../faq/general.rst:8 +msgid "Contents" +msgstr "目錄" + +#: ../../faq/general.rst:13 +msgid "General Information" +msgstr "一般資訊" + +#: ../../faq/general.rst:16 +msgid "What is Python?" +msgstr "什麼是 Python？" + +#: ../../faq/general.rst:18 +msgid "" +"Python is an interpreted, interactive, object-oriented programming " +"language. It incorporates modules, exceptions, dynamic typing, very high " +"level dynamic data types, and classes. It supports multiple programming " +"paradigms beyond object-oriented programming, such as procedural and " +"functional programming. Python combines remarkable power with very clear " +"syntax. It has interfaces to many system calls and libraries, as well as to " +"various window systems, and is extensible in C or C++. It is also usable as " +"an extension language for applications that need a programmable interface. " +"Finally, Python is portable: it runs on many Unix variants including Linux " +"and macOS, and on Windows." +msgstr "" +"Python 是一種直譯的、互動的、物件導向的程式設計語言。它結合了模組、例外、動態" +"型別 (dynamic typing)、非常高階的動態資料型別，以及 class（類別）。它能支援物" +"件導向程式設計之外的多種程式設計典範，例如程序式 (procedural) 和函式語言 " +"(functional) 程式設計。Python 結合了卓越的功能與非常清晰的語法。它有許多系統" +"呼叫和函式庫的介面，以及各種視窗系統的介面，並且在 C 或 C++ 中可以擴充。它還" +"可以作為一種擴充語言，使用於需要可程式化介面 (programmable interface) 的應用" +"程式。最後，Python 是可攜的 (portable)：它能運行在許多 Unix 的變體上，包括 " +"Linux 和 macOS，也能運行在 Windows 上。" + +#: ../../faq/general.rst:28 +msgid "" +"To find out more, start with :ref:`tutorial-index`. The `Beginner's Guide " +"to Python `_ links to other " +"introductory tutorials and resources for learning Python." +msgstr "" +"要尋找更多內容，請從 :ref:`tutorial-index`\\ 開始。`Python 初學者指南 " +"`_\\ 可連結到其他介紹式教學以及" +"學習 Python 的資源。" + +#: ../../faq/general.rst:34 +msgid "What is the Python Software Foundation?" +msgstr "什麼是 Python 軟體基金會？" + +#: ../../faq/general.rst:36 +msgid "" +"The Python Software Foundation is an independent non-profit organization " +"that holds the copyright on Python versions 2.1 and newer. The PSF's " +"mission is to advance open source technology related to the Python " +"programming language and to publicize the use of Python. The PSF's home " +"page is at https://www.python.org/psf/." +msgstr "" +"Python 軟體基金會 (Python Software Foundation) 是一個獨立的非營利性組織，它擁" +"有 Python 2.1 版與之後各版本的版權。PSF 的使命在於推展 Python 程式設計語言相" +"關的開放原始碼技術，以及宣傳 Python 的使用。PSF 首頁的網址是 https://www." +"python.org/psf/。" + +#: ../../faq/general.rst:42 +msgid "" +"Donations to the PSF are tax-exempt in the US. If you use Python and find " +"it helpful, please contribute via `the PSF donation page `_." +msgstr "" +"在美國捐款給 PSF 是免稅的。如果你使用了 Python 且發現它很有用，請至 `PSF 捐款" +"頁面 `_\\ 為它做出貢獻。" + +#: ../../faq/general.rst:48 +msgid "Are there copyright restrictions on the use of Python?" +msgstr "使用 Python 時有任何版權限制嗎？" + +#: ../../faq/general.rst:50 +msgid "" +"You can do anything you want with the source, as long as you leave the " +"copyrights in and display those copyrights in any documentation about Python " +"that you produce. If you honor the copyright rules, it's OK to use Python " +"for commercial use, to sell copies of Python in source or binary form " +"(modified or unmodified), or to sell products that incorporate Python in " +"some form. We would still like to know about all commercial use of Python, " +"of course." +msgstr "" +"你可以對原始碼做任何你想做的事情，只要你保留版權，並且在你製作的任何關於 " +"Python 的說明文件中顯示這些版權即可。如果你遵守版權規則，就可以將 Python 用於" +"商業用途，以原始碼或二進制形式（修改或未修改）銷售 Python 的複本，或者以某種" +"形式銷售內含 Python 的產品。當然，我們仍然會想要知道所有的 Python 商業用途。" + +#: ../../faq/general.rst:57 +msgid "" +"See `the license page `_ to find " +"further explanations and the full text of the PSF License." +msgstr "" +"請參閱 `授權頁面 `_，查詢更深入的說明" +"和 PSF 授權全文的連結。" + +#: ../../faq/general.rst:60 +msgid "" +"The Python logo is trademarked, and in certain cases permission is required " +"to use it. Consult `the Trademark Usage Policy `__ for more information." +msgstr "" +"Python 標誌是註冊商標，在某些情況下需要許可才能使用它。請參閱\\ `商標使用政" +"策 `__\\ 以取得更多資訊。" + +#: ../../faq/general.rst:66 +msgid "Why was Python created in the first place?" +msgstr "當初為什麼 Python 會被創造出來？" + +#: ../../faq/general.rst:68 +msgid "" +"Here's a *very* brief summary of what started it all, written by Guido van " +"Rossum:" +msgstr "" +"以下是由 Guido van Rossum 所撰寫，關於這一切如何開始的\\ *非常*\\ 簡短的摘" +"要：" + +#: ../../faq/general.rst:71 +msgid "" +"I had extensive experience with implementing an interpreted language in the " +"ABC group at CWI, and from working with this group I had learned a lot about " +"language design. This is the origin of many Python features, including the " +"use of indentation for statement grouping and the inclusion of very-high-" +"level data types (although the details are all different in Python)." +msgstr "" +"我在 CWI 的 ABC 小組中擁有實作直譯語言方面的豐富經驗，而透過與該小組的合作，" +"我學到了很多關於語言設計的知識。這是許多 Python 功能的起源，包括使用縮排進行" +"陳述式分組以及納入非常高階的資料型別（儘管在 Python 中的細節都已經不同）。" + +#: ../../faq/general.rst:78 +msgid "" +"I had a number of gripes about the ABC language, but also liked many of its " +"features. It was impossible to extend the ABC language (or its " +"implementation) to remedy my complaints -- in fact its lack of extensibility " +"was one of its biggest problems. I had some experience with using Modula-2+ " +"and talked with the designers of Modula-3 and read the Modula-3 report. " +"Modula-3 is the origin of the syntax and semantics used for exceptions, and " +"some other Python features." +msgstr "" +"我對 ABC 語言有一些牢騷，但我也喜歡它的許多功能。想要擴充 ABC 語言（或其實" +"作）來去除我的抱怨是不可能的。事實上，缺乏可擴充性就是它最大的問題之一。我有" +"一些使用 Modula-2+ 的經驗，也與 Modula-3 的設計者交談過，並閱讀了 Modula-3 的" +"報告。Modula-3 就是用於例外及另外一些 Python 功能的語法和語義的起源。" + +#: ../../faq/general.rst:86 +msgid "" +"I was working in the Amoeba distributed operating system group at CWI. We " +"needed a better way to do system administration than by writing either C " +"programs or Bourne shell scripts, since Amoeba had its own system call " +"interface which wasn't easily accessible from the Bourne shell. My " +"experience with error handling in Amoeba made me acutely aware of the " +"importance of exceptions as a programming language feature." +msgstr "" +"我當時正在 CWI 的 Amoeba 分散式作業系統小組工作。我們需要一種比編寫 C 程式或 " +"Bourne shell 腳本更好的方法來進行系統管理，因為 Amoeba 有自己的系統呼叫介面，" +"而它無法簡單地從 Bourne shell 進行存取。我在 Amoeba 中處理錯誤的經驗，使我深" +"切地意識到例外作為程式設計語言功能的重要性。" + +#: ../../faq/general.rst:93 +msgid "" +"It occurred to me that a scripting language with a syntax like ABC but with " +"access to the Amoeba system calls would fill the need. I realized that it " +"would be foolish to write an Amoeba-specific language, so I decided that I " +"needed a language that was generally extensible." +msgstr "" +"我突然想到，一種具有類似 ABC 的語法但可以存取 Amoeba 系統呼叫的腳本語言將能滿" +"足該需求。我了解編寫 Amoeba 專用語言是愚蠢的，所以我決定，我需要一種可以廣泛" +"擴充的語言。" + +#: ../../faq/general.rst:98 +msgid "" +"During the 1989 Christmas holidays, I had a lot of time on my hand, so I " +"decided to give it a try. During the next year, while still mostly working " +"on it in my own time, Python was used in the Amoeba project with increasing " +"success, and the feedback from colleagues made me add many early " +"improvements." +msgstr "" +"在 1989 年的聖誕節假期，我有很多自由時間，所以我決定來嘗試一下。在接下來的一" +"年裡，雖然我大部分時間仍然在為此而努力，但 Python 在 Amoeba 專案中的使用得到" +"了越來越多的成功，且同事們的回饋也使我為它增加了許多早期的改進。" + +#: ../../faq/general.rst:104 +msgid "" +"In February 1991, after just over a year of development, I decided to post " +"to USENET. The rest is in the ``Misc/HISTORY`` file." +msgstr "" +"在 1991 年 2月，經過一年多的發展，我決定將它發表到 USENET。其他的記錄都在 " +"``Misc/HISTORY`` 檔案中。" + +#: ../../faq/general.rst:109 +msgid "What is Python good for?" +msgstr "什麼是 Python 擅長的事情？" + +#: ../../faq/general.rst:111 +msgid "" +"Python is a high-level general-purpose programming language that can be " +"applied to many different classes of problems." +msgstr "" +"Python 是一種高階的、用途廣泛的程式設計語言，可以用來解決許多不同類型的問題。" + +#: ../../faq/general.rst:114 +msgid "" +"The language comes with a large standard library that covers areas such as " +"string processing (regular expressions, Unicode, calculating differences " +"between files), internet protocols (HTTP, FTP, SMTP, XML-RPC, POP, IMAP), " +"software engineering (unit testing, logging, profiling, parsing Python " +"code), and operating system interfaces (system calls, filesystems, TCP/IP " +"sockets). Look at the table of contents for :ref:`library-index` to get an " +"idea of what's available. A wide variety of third-party extensions are also " +"available. Consult `the Python Package Index `_ to find " +"packages of interest to you." +msgstr "" +"這個語言提供了一個大型的標準函式庫，涵蓋了字串處理（正規表示式、Unicode、檔案" +"之間的差異計算）、網際網路協定（HTTP、FTP、SMTP、XML-RPC、POP、IMAP）、軟體工" +"程（單元測試、日誌記錄、效能分析、剖析 Python 程式碼）以及作業系統介面（系統" +"呼叫、檔案系統、TCP/IP 插座 (socket)）等領域。請查看 :ref:`library-index` 的" +"目錄，以了解可用的函式。此外，還有各式各樣的第三方擴充。請查詢 `Python 套件索" +"引 (Python Package Index) `_ 來尋找你有興趣的套件。" + +#: ../../faq/general.rst:128 +msgid "How does the Python version numbering scheme work?" +msgstr "Python 的版本編號系統是如何運作的？" + +#: ../../faq/general.rst:130 +msgid "Python versions are numbered \"A.B.C\" or \"A.B\":" +msgstr "Python 各版本會被編號為 \"A.B.C\" 或 \"A.B\"：" + +#: ../../faq/general.rst:132 +msgid "" +"*A* is the major version number -- it is only incremented for really major " +"changes in the language." +msgstr "*A* 為主要版本編號 -- 它只會在語言中有真正重大的變更時才會增加。" + +#: ../../faq/general.rst:134 +msgid "" +"*B* is the minor version number -- it is incremented for less earth-" +"shattering changes." +msgstr "*B* 為次要版本編號 -- 只有在影響範圍較小的變更出現時增加。" + +#: ../../faq/general.rst:136 +msgid "" +"*C* is the micro version number -- it is incremented for each bugfix release." +msgstr "*C* 為微小版本編號 —- 會在每個錯誤修正發布 (bugfix release) 增加。" + +#: ../../faq/general.rst:138 +msgid "" +"Not all releases are bugfix releases. In the run-up to a new feature " +"release, a series of development releases are made, denoted as alpha, beta, " +"or release candidate. Alphas are early releases in which interfaces aren't " +"yet finalized; it's not unexpected to see an interface change between two " +"alpha releases. Betas are more stable, preserving existing interfaces but " +"possibly adding new modules, and release candidates are frozen, making no " +"changes except as needed to fix critical bugs." +msgstr "" +"並非所有的發布版本都是錯誤修正發布版本。在一個新功能發布版本的準備階段，會發" +"布一系列開發版本，標示為 alpha、beta 或候選發布版本 (release candidate)。" +"Alpha 是介面尚未最終化的早期發布版本；看到兩個 alpha 發布版本之間的介面變更並" +"不會令人意外。Beta 則更為穩定，保留了現有的介面，但可能會增加新的模組，而候選" +"發布版本會被凍結，除了需要修正關鍵錯誤之外，不會再進行任何變更。" + +#: ../../faq/general.rst:146 +msgid "Alpha, beta and release candidate versions have an additional suffix:" +msgstr "Alpha、beta 和候選發布版本都有一個額外的後綴：" + +#: ../../faq/general.rst:148 +msgid "The suffix for an alpha version is \"aN\" for some small number *N*." +msgstr "Alpha 版本的後綴是 \"aN\"，其中 *N* 是某個較小的數字。" + +#: ../../faq/general.rst:149 +msgid "The suffix for a beta version is \"bN\" for some small number *N*." +msgstr "Beta 版本的後綴是 \"bN\"，其中 *N* 是某個較小的數字。" + +#: ../../faq/general.rst:150 +msgid "" +"The suffix for a release candidate version is \"rcN\" for some small number " +"*N*." +msgstr "候選發布版本的後綴是 \"rcN\"，其中 *N* 是某個較小的數字。" + +#: ../../faq/general.rst:152 +msgid "" +"In other words, all versions labeled *2.0aN* precede the versions labeled " +"*2.0bN*, which precede versions labeled *2.0rcN*, and *those* precede 2.0." +msgstr "" +"換句話說，所有標記為 *2.0aN* 的版本都在標記為 *2.0bN* 的版本之前，而 *2.0bN* " +"版本都在標記為 *2.0rcN* 的版本之前，而\\ *它們*\\ 都是在 2.0 版之前。" + +#: ../../faq/general.rst:155 +msgid "" +"You may also find version numbers with a \"+\" suffix, e.g. \"2.2+\". These " +"are unreleased versions, built directly from the CPython development " +"repository. In practice, after a final minor release is made, the version " +"is incremented to the next minor version, which becomes the \"a0\" version, " +"e.g. \"2.4a0\"." +msgstr "" +"你還可以找到帶有「+」後綴的版本編號，例如「2.2+」。這些是未發布的版本，直接" +"從 CPython 的開發儲存庫被建置。實際上，在每一次的最終次要版本發布完成之後，版" +"本編號將會被增加到下一個次要版本，並成為「a0」版，例如「2.4a0」。" + +#: ../../faq/general.rst:160 +msgid "" +"See the `Developer's Guide `__ for more information about the development cycle, " +"and :pep:`387` to learn more about Python's backward compatibility policy. " +"See also the documentation for :data:`sys.version`, :data:`sys.hexversion`, " +"and :data:`sys.version_info`." +msgstr "" +"請參閱\\ `開發人員指南 `__\\ 以獲得更多關於開發週期的資訊，並參閱 :pep:`387` 以瞭" +"解更多關於 Python 的向後相容性政策。另外，也請查看 :data:`sys.version`、:" +"data:`sys.hexversion` 和 :data:`sys.version_info` 的說明文件。" + +#: ../../faq/general.rst:169 +msgid "How do I obtain a copy of the Python source?" +msgstr "我要如何得到 Python 的原始碼複本？" + +#: ../../faq/general.rst:171 +msgid "" +"The latest Python source distribution is always available from python.org, " +"at https://www.python.org/downloads/. The latest development sources can be " +"obtained at https://github.com/python/cpython/." +msgstr "" +"最新的 Python 原始碼發行版永遠可以從 python.org 取得，在 https://www.python." +"org/downloads/。最新的開發中原始碼可以在 https://github.com/python/cpython/ " +"取得。" + +#: ../../faq/general.rst:175 +msgid "" +"The source distribution is a gzipped tar file containing the complete C " +"source, Sphinx-formatted documentation, Python library modules, example " +"programs, and several useful pieces of freely distributable software. The " +"source will compile and run out of the box on most UNIX platforms." +msgstr "" +"原始碼發行版是一個以 gzip 壓縮的 tar 檔，它包含完整的 C 原始碼、Sphinx 格式的" +"說明文件、Python 函式庫模組、範例程式，以及幾個好用的可自由發行軟體。該原始碼" +"在大多數 UNIX 平台上，都是可以立即編譯及運行的。" + +#: ../../faq/general.rst:180 +msgid "" +"Consult the `Getting Started section of the Python Developer's Guide " +"`__ for more information on getting the " +"source code and compiling it." +msgstr "" +"關於取得和編譯原始碼的詳細資訊，請參閱 `Python 開發人員指南中的 \"Getting " +"Started\" 段落 `__。" + +#: ../../faq/general.rst:186 +msgid "How do I get documentation on Python?" +msgstr "我要如何取得 Python 的說明文件？" + +#: ../../faq/general.rst:188 +msgid "" +"The standard documentation for the current stable version of Python is " +"available at https://docs.python.org/3/. EPUB, plain text, and downloadable " +"HTML versions are also available at https://docs.python.org/3/download.html." +msgstr "" +"Python 目前穩定版本的標準說明文件可在 https://docs.python.org/3/ 找到。EPUB、" +"純文字和可下載的 HTML 版本也可在 https://docs.python.org/3/download.html 找" +"到。" + +#: ../../faq/general.rst:192 +msgid "" +"The documentation is written in reStructuredText and processed by `the " +"Sphinx documentation tool `__. The " +"reStructuredText source for the documentation is part of the Python source " +"distribution." +msgstr "" +"說明文件是以 reStructuredText 格式編寫，並由 `Sphinx 說明文件工具 `__\\ 處理。說明文件的 reStructuredText 原始碼是 Python 原始" +"碼發行版的一部分。" + +#: ../../faq/general.rst:198 +msgid "I've never programmed before. Is there a Python tutorial?" +msgstr "我從來沒有寫過程式，有沒有 Python 的教學？" + +#: ../../faq/general.rst:200 +msgid "" +"There are numerous tutorials and books available. The standard " +"documentation includes :ref:`tutorial-index`." +msgstr "有許多可用的教學和書籍。標準說明文件包括 :ref:`tutorial-index`。" + +#: ../../faq/general.rst:203 +msgid "" +"Consult `the Beginner's Guide `_ to find information for beginning Python programmers, " +"including lists of tutorials." +msgstr "" +"要尋找 Python 程式設計初學者的資訊，包括教學資源列表，請參閱\\ `初學者指南 " +"`_。" + +#: ../../faq/general.rst:208 +msgid "Is there a newsgroup or mailing list devoted to Python?" +msgstr "有沒有 Python 專屬的新聞群組或郵件討論群？" + +#: ../../faq/general.rst:210 +msgid "" +"There is a newsgroup, :newsgroup:`comp.lang.python`, and a mailing list, " +"`python-list `_. The " +"newsgroup and mailing list are gatewayed into each other -- if you can read " +"news it's unnecessary to subscribe to the mailing list. :newsgroup:`comp." +"lang.python` is high-traffic, receiving hundreds of postings every day, and " +"Usenet readers are often more able to cope with this volume." +msgstr "" +"有一個新聞群組 (newsgroup)，:newsgroup:`comp.lang.python`，也有一個郵件討論" +"群 (mailing list)，`python-list `_。新聞群組和郵件討論群是彼此相通的——如果你能閱讀新聞，則無需加" +"入郵件討論群。:newsgroup:`comp.lang.python` 的流量很高，每天會收到數百篇文" +"章，而 Usenet 的讀者通常較能夠處理這樣的文章數量。" + +#: ../../faq/general.rst:217 +msgid "" +"Announcements of new software releases and events can be found in comp.lang." +"python.announce, a low-traffic moderated list that receives about five " +"postings per day. It's available as `the python-announce mailing list " +"`_." +msgstr "" +"新的軟體發布版本及事件的通知，可以在 comp.lang.python.announce 中找到，這是一" +"個低流量的精選討論群，每天收到大約五篇文章。它也能從 `python-announce 郵件討" +"論群 `_\\ 的頁面中訂閱。" + +#: ../../faq/general.rst:222 +msgid "" +"More info about other mailing lists and newsgroups can be found at https://" +"www.python.org/community/lists/." +msgstr "" +"關於其他郵件討論群和新聞群組的更多資訊，可以在 https://www.python.org/" +"community/lists/ 中找到。" + +#: ../../faq/general.rst:227 +msgid "How do I get a beta test version of Python?" +msgstr "如何取得 Python 的 beta 測試版本？" + +#: ../../faq/general.rst:229 +msgid "" +"Alpha and beta releases are available from https://www.python.org/" +"downloads/. All releases are announced on the comp.lang.python and comp." +"lang.python.announce newsgroups and on the Python home page at https://www." +"python.org/; an RSS feed of news is available." +msgstr "" +"Alpha 和 beta 發布版本可以從 https://www.python.org/downloads/ 取得。所有的發" +"布版本都會在 comp.lang.python 和 comp.lang.python.announce 新聞群組上宣布，也" +"會在 Python 首頁 https://www.python.org/ 中宣布；RSS 新聞摘要也是可使用的。" + +#: ../../faq/general.rst:234 +msgid "" +"You can also access the development version of Python through Git. See `The " +"Python Developer's Guide `_ for details." +msgstr "" +"你也可以藉由 Git 來存取 Python 的開發版本。更多詳細資訊，請參閱 `Python 開發" +"人員指南 `_。" + +#: ../../faq/general.rst:239 +msgid "How do I submit bug reports and patches for Python?" +msgstr "如何提交 Python 的錯誤報告和修補程式？" + +#: ../../faq/general.rst:241 +msgid "" +"To report a bug or submit a patch, use the issue tracker at https://github." +"com/python/cpython/issues." +msgstr "" +"要回報一個錯誤 (bug) 或提交一個修補程式 (patch)，請使用於 https://github.com/" +"python/cpython/issues 的問題追蹤系統。" + +#: ../../faq/general.rst:244 +msgid "" +"For more information on how Python is developed, consult `the Python " +"Developer's Guide `_." +msgstr "" +"關於如何開發 Python 的更多資訊，請參閱 `Python 開發人員指南 `_。" + +#: ../../faq/general.rst:249 +msgid "Are there any published articles about Python that I can reference?" +msgstr "是否有關於 Python 的任何已出版文章可供參考？" + +#: ../../faq/general.rst:251 +msgid "It's probably best to cite your favorite book about Python." +msgstr "也許最好是引用你最喜歡的關於 Python 的書。" + +#: ../../faq/general.rst:253 +msgid "" +"The `very first article `_ about Python was " +"written in 1991 and is now quite outdated." +msgstr "" +"`最早討論 Python 的文章 `_\\ 是在 1991 年寫的，" +"但現在來看已經過時了。" + +#: ../../faq/general.rst:256 +msgid "" +"Guido van Rossum and Jelke de Boer, \"Interactively Testing Remote Servers " +"Using the Python Programming Language\", CWI Quarterly, Volume 4, Issue 4 " +"(December 1991), Amsterdam, pp 283--303." +msgstr "" +"Guido van Rossum 和 Jelke de Boer，「使用 Python 程式設計語言互動式測試遠端伺" +"服器」，CWI 季刊，第 4 卷，第 4 期（1991 年 12 月），阿姆斯特丹，第 283–303 " +"頁。" + +#: ../../faq/general.rst:262 +msgid "Are there any books on Python?" +msgstr "有沒有關於 Python 的書？" + +#: ../../faq/general.rst:264 +msgid "" +"Yes, there are many, and more are being published. See the python.org wiki " +"at https://wiki.python.org/moin/PythonBooks for a list." +msgstr "" +"有，很多書已經出版，也有更多正在出版中的書。請參閱 python.org 的 wiki 在 " +"https://wiki.python.org/moin/PythonBooks 頁面中的書目清單。" + +#: ../../faq/general.rst:267 +msgid "" +"You can also search online bookstores for \"Python\" and filter out the " +"Monty Python references; or perhaps search for \"Python\" and \"language\"." +msgstr "" +"你也可以在網路書店搜尋關鍵字「Python」，並過濾掉 Monty Python 的結果；或者可" +"以搜尋「Python」和「語言」。" + +#: ../../faq/general.rst:272 +msgid "Where in the world is www.python.org located?" +msgstr "www.python.org 的真實位置在哪裡？" + +#: ../../faq/general.rst:274 +msgid "" +"The Python project's infrastructure is located all over the world and is " +"managed by the Python Infrastructure Team. Details `here `__." +msgstr "" +"Python 專案的基礎建設遍佈世界各地，由 Python 基礎建設團隊管理。詳細資訊\\ `在" +"此 `__。" + +#: ../../faq/general.rst:279 +msgid "Why is it called Python?" +msgstr "為什麼要取名為 Python？" + +#: ../../faq/general.rst:281 +msgid "" +"When he began implementing Python, Guido van Rossum was also reading the " +"published scripts from `\"Monty Python's Flying Circus\" `__, a BBC comedy series from the 1970s. " +"Van Rossum thought he needed a name that was short, unique, and slightly " +"mysterious, so he decided to call the language Python." +msgstr "" +"當 Guido van Rossum 開始實作 Python 時，他也正在閱讀 1970 年代 BBC 喜劇節目" +"\\ `「Monty Python 的飛行馬戲團」 `__\\ 的出版劇本。Van Rossum 認為他需要一個簡短、獨特且略帶神秘" +"的名字，因此他決定將該語言稱為 Python。" + +#: ../../faq/general.rst:289 +msgid "Do I have to like \"Monty Python's Flying Circus\"?" +msgstr "我需要喜歡「Monty Python 的飛行馬戲團」嗎？" + +#: ../../faq/general.rst:291 +msgid "No, but it helps. :)" +msgstr "不需要，但它有幫助。:)" + +#: ../../faq/general.rst:295 +msgid "Python in the real world" +msgstr "在真實世界中的 Python" + +#: ../../faq/general.rst:298 +msgid "How stable is Python?" +msgstr "Python 的穩定性如何？" + +#: ../../faq/general.rst:300 +msgid "" +"Very stable. New, stable releases have been coming out roughly every 6 to " +"18 months since 1991, and this seems likely to continue. As of version 3.9, " +"Python will have a new feature release every 12 months (:pep:`602`)." +msgstr "" +"非常穩定。自從 1991 年開始，大約每隔 6 到 18 個月都會發布新的穩定版本，而且這" +"看起來會繼續進行。從 3.9 版開始，Python 每隔 12 個月將會釋出一個新功能發行版" +"本 (:pep:`602`)。" + +#: ../../faq/general.rst:304 +msgid "" +"The developers issue bugfix releases of older versions, so the stability of " +"existing releases gradually improves. Bugfix releases, indicated by a third " +"component of the version number (e.g. 3.5.3, 3.6.2), are managed for " +"stability; only fixes for known problems are included in a bugfix release, " +"and it's guaranteed that interfaces will remain the same throughout a series " +"of bugfix releases." +msgstr "" +"開發人員會釋出針對先前版本的錯誤修正發布版本，因此現有發布版本的穩定性會逐漸" +"提高。錯誤修正發布版本是由版本編號的第三個部分表示（例如 3.5.3，3.6.2），這些" +"版本會被用於改善穩定性；在錯誤修正發布版本中，只會包含針對已知問題的修正，並" +"且會保證介面在一系列的錯誤修正發布版本中維持不變。" + +#: ../../faq/general.rst:311 +msgid "" +"The latest stable releases can always be found on the `Python download page " +"`_. Python 3.x is the recommended version " +"and supported by most widely used libraries. Python 2.x :pep:`is not " +"maintained anymore <373>`." +msgstr "" +"最新的穩定發布版本隨時都可以在 `Python 下載頁面 `_\\ 上找到。Python 3.x 是推薦的版本，並且被大多數廣泛使用的函式庫" +"所支援。Python 2.x :pep:`已不再被維護 <0373>`。" + +#: ../../faq/general.rst:317 +msgid "How many people are using Python?" +msgstr "有多少人在使用 Python？" + +#: ../../faq/general.rst:319 +msgid "" +"There are probably millions of users, though it's difficult to obtain an " +"exact count." +msgstr "可能有幾百萬個使用者，但實際的數量是難以確定的。" + +#: ../../faq/general.rst:322 +msgid "" +"Python is available for free download, so there are no sales figures, and " +"it's available from many different sites and packaged with many Linux " +"distributions, so download statistics don't tell the whole story either." +msgstr "" +"Python 是可以免費下載的，所以不會有銷售數據，而且它可以從許多不同的網站取得，" +"並與許多 Linux 發行版套裝在一起，所以下載次數的統計也無法反映完整的情況。" + +#: ../../faq/general.rst:326 +msgid "" +"The comp.lang.python newsgroup is very active, but not all Python users post " +"to the group or even read it." +msgstr "" +"comp.lang.python 新聞群組非常活躍，但並非所有 Python 使用者都會在該群組發表文" +"章或甚至閱讀它。" + +#: ../../faq/general.rst:331 +msgid "Have any significant projects been done in Python?" +msgstr "有沒有任何重要的專案使用 Python 完成開發？" + +#: ../../faq/general.rst:333 +msgid "" +"See https://www.python.org/about/success for a list of projects that use " +"Python. Consulting the proceedings for `past Python conferences `_ will reveal contributions from many " +"different companies and organizations." +msgstr "" +"要查看使用 Python 的專案清單，請參閱 https://www.python.org/about/success。藉" +"由查詢\\ `過去的 Python 會議記錄 `_\\ 可以看見來自許多不同公司和組織的貢獻。" + +#: ../../faq/general.rst:338 +msgid "" +"High-profile Python projects include `the Mailman mailing list manager " +"`_ and `the Zope application server `_. Several Linux distributions, most notably `Red Hat `_, have written part or all of their installer and system " +"administration software in Python. Companies that use Python internally " +"include Google, Yahoo, and Lucasfilm Ltd." +msgstr "" +"備受矚目的 Python 專案包括 `Mailman 郵件討論群管理員 `_\\ 和 `Zope 應用程式伺服器 `_。有一些 Linux 發行" +"版，最著名的是 `Red Hat `_，已經用 Python 編寫了部分" +"或全部的安裝程式及系統管理軟體。內部使用 Python 的公司包括 Google、Yahoo 和 " +"Lucasfilm Ltd。" + +#: ../../faq/general.rst:347 +msgid "What new developments are expected for Python in the future?" +msgstr "Python 未來預期會有哪些新的開發？" + +#: ../../faq/general.rst:349 +msgid "" +"See https://peps.python.org/ for the Python Enhancement Proposals (PEPs). " +"PEPs are design documents describing a suggested new feature for Python, " +"providing a concise technical specification and a rationale. Look for a PEP " +"titled \"Python X.Y Release Schedule\", where X.Y is a version that hasn't " +"been publicly released yet." +msgstr "" +"請至 https://peps.python.org/ 參閱 Python 增強提案 (Python Enhancement " +"Proposal, PEP)。PEP 是用來描述一項被建議的 Python 新功能的設計文件，它提供了" +"簡潔的技術規範及基本原理。請尋找一篇名為「Python X.Y Release Schedule（發布時" +"程表）」的 PEP，其中 X.Y 是一個尚未公開發布的版本。" + +#: ../../faq/general.rst:355 +msgid "" +"New development is discussed on `the python-dev mailing list `_." +msgstr "" +"新的開發會在 `python-dev 郵件討論群 `_\\ 中討論。" + +#: ../../faq/general.rst:360 +msgid "Is it reasonable to propose incompatible changes to Python?" +msgstr "對 Python 提出不相容的變更建議是否適當？" + +#: ../../faq/general.rst:362 +msgid "" +"In general, no. There are already millions of lines of Python code around " +"the world, so any change in the language that invalidates more than a very " +"small fraction of existing programs has to be frowned upon. Even if you can " +"provide a conversion program, there's still the problem of updating all " +"documentation; many books have been written about Python, and we don't want " +"to invalidate them all at a single stroke." +msgstr "" +"一般來說，不適當。全世界已經有數百萬行 Python 程式碼，因此在語言中的任何變" +"更，若會使現有程式的一小部分成為無效，它都是不被允許的。即使你可以提供轉換程" +"式，仍然會有需要更新全部說明文件的問題；市面上已經有很多介紹 Python 的書，而" +"我們不想一下子就把它們都變為無效。" + +#: ../../faq/general.rst:369 +msgid "" +"Providing a gradual upgrade path is necessary if a feature has to be " +"changed. :pep:`5` describes the procedure followed for introducing backward-" +"incompatible changes while minimizing disruption for users." +msgstr "" +"如果一項功能必須被變更，那麼一定要提供逐步升級的路徑。:pep:`5` 描述了要引進反" +"向不相容 (backward-incompatible) 的變更，同時也要對使用者的擾亂最小化，所需遵" +"循的程序。" + +#: ../../faq/general.rst:375 +msgid "Is Python a good language for beginning programmers?" +msgstr "Python 對於入門的程式設計師而言是否為好的語言？" + +#: ../../faq/general.rst:377 +msgid "Yes." +msgstr "是的。" + +#: ../../faq/general.rst:379 +msgid "" +"It is still common to start students with a procedural and statically typed " +"language such as Pascal, C, or a subset of C++ or Java. Students may be " +"better served by learning Python as their first language. Python has a very " +"simple and consistent syntax and a large standard library and, most " +"importantly, using Python in a beginning programming course lets students " +"concentrate on important programming skills such as problem decomposition " +"and data type design. With Python, students can be quickly introduced to " +"basic concepts such as loops and procedures. They can probably even work " +"with user-defined objects in their very first course." +msgstr "" +"學生們仍然普遍地會從一種程序語言和靜態型別語言 (statically typed language) 開" +"始入門，這些語言像是 Pascal、C，或是 C++ 或 Java 的某個子集。透過學習 Python " +"作為他們的第一個語言，學生們可能會學得更好。Python 具有非常簡單且一致的語法和" +"一個大型的標準函式庫，最重要的是，在入門程式設計課程中使用 Python 可以讓學生" +"專注於重要的程式設計技巧，例如問題的分解和資料型別的設計。使用 Python，可以快" +"速地向學生介紹基本觀念，例如迴圈和程序。他們甚至可能在第一堂課中就學到使用者" +"自訂的物件。" + +#: ../../faq/general.rst:389 +msgid "" +"For a student who has never programmed before, using a statically typed " +"language seems unnatural. It presents additional complexity that the " +"student must master and slows the pace of the course. The students are " +"trying to learn to think like a computer, decompose problems, design " +"consistent interfaces, and encapsulate data. While learning to use a " +"statically typed language is important in the long term, it is not " +"necessarily the best topic to address in the students' first programming " +"course." +msgstr "" +"對於以前從未進行過程式設計的學生來說，使用靜態型別語言似乎是不自然的。它使學" +"生必須掌握額外的複雜性，並減慢了課程的節奏。學生們正在試圖學著像電腦一樣思" +"考、分解問題、設計一致的介面，並封裝資料。雖然從長遠來看，學習使用靜態型別語" +"言很重要，但在學生的第一堂程式設計課程中，它不一定是最好的課程主題。" + +#: ../../faq/general.rst:397 +msgid "" +"Many other aspects of Python make it a good first language. Like Java, " +"Python has a large standard library so that students can be assigned " +"programming projects very early in the course that *do* something. " +"Assignments aren't restricted to the standard four-function calculator and " +"check balancing programs. By using the standard library, students can gain " +"the satisfaction of working on realistic applications as they learn the " +"fundamentals of programming. Using the standard library also teaches " +"students about code reuse. Third-party modules such as PyGame are also " +"helpful in extending the students' reach." +msgstr "" +"Python 的許多其他面向使它成為一種很好的第一語言。像 Java 一樣，Python 有一個" +"大型的標準函式庫，因此學生可以在課程的早期就被指派程式設計的專案，且這些專案" +"能夠\\ *做*\\ 一些事情。指派的內容不會侷限於標準的四功能計算機和平衡檢驗程" +"式。透過使用標準函式庫，學生可以在學習程式設計基礎知識的同時，獲得處理真實應" +"用程式的滿足感。使用標準函式庫還可以教導學生程式碼再使用 (code reuse) 的課" +"題。像是 PyGame 等第三方模組也有助於延伸學生的學習領域。" + +#: ../../faq/general.rst:406 +msgid "" +"Python's interactive interpreter enables students to test language features " +"while they're programming. They can keep a window with the interpreter " +"running while they enter their program's source in another window. If they " +"can't remember the methods for a list, they can do something like this::" +msgstr "" +"Python 的互動式直譯器使學生能夠在程式設計時測試語言的功能。他們可以開著一個運" +"行直譯器的視窗，同時在另一個視窗中輸入他們的程式原始碼。如果他們不記得 list" +"（串列）的 method（方法），他們可以像這樣做： ::" + +#: ../../faq/general.rst:411 +msgid "" +">>> L = []\n" +">>> dir(L)\n" +"['__add__', '__class__', '__contains__', '__delattr__', '__delitem__',\n" +"'__dir__', '__doc__', '__eq__', '__format__', '__ge__',\n" +"'__getattribute__', '__getitem__', '__gt__', '__hash__', '__iadd__',\n" +"'__imul__', '__init__', '__iter__', '__le__', '__len__', '__lt__',\n" +"'__mul__', '__ne__', '__new__', '__reduce__', '__reduce_ex__',\n" +"'__repr__', '__reversed__', '__rmul__', '__setattr__', '__setitem__',\n" +"'__sizeof__', '__str__', '__subclasshook__', 'append', 'clear',\n" +"'copy', 'count', 'extend', 'index', 'insert', 'pop', 'remove',\n" +"'reverse', 'sort']\n" +">>> [d for d in dir(L) if '__' not in d]\n" +"['append', 'clear', 'copy', 'count', 'extend', 'index', 'insert', 'pop', " +"'remove', 'reverse', 'sort']\n" +"\n" +">>> help(L.append)\n" +"Help on built-in function append:\n" +"\n" +"append(...)\n" +" L.append(object) -> None -- append object to end\n" +"\n" +">>> L.append(1)\n" +">>> L\n" +"[1]" +msgstr "" +">>> L = []\n" +">>> dir(L)\n" +"['__add__', '__class__', '__contains__', '__delattr__', '__delitem__',\n" +"'__dir__', '__doc__', '__eq__', '__format__', '__ge__',\n" +"'__getattribute__', '__getitem__', '__gt__', '__hash__', '__iadd__',\n" +"'__imul__', '__init__', '__iter__', '__le__', '__len__', '__lt__',\n" +"'__mul__', '__ne__', '__new__', '__reduce__', '__reduce_ex__',\n" +"'__repr__', '__reversed__', '__rmul__', '__setattr__', '__setitem__',\n" +"'__sizeof__', '__str__', '__subclasshook__', 'append', 'clear',\n" +"'copy', 'count', 'extend', 'index', 'insert', 'pop', 'remove',\n" +"'reverse', 'sort']\n" +">>> [d for d in dir(L) if '__' not in d]\n" +"['append', 'clear', 'copy', 'count', 'extend', 'index', 'insert', 'pop', " +"'remove', 'reverse', 'sort']\n" +"\n" +">>> help(L.append)\n" +"Help on built-in function append:\n" +"\n" +"append(...)\n" +" L.append(object) -> None -- append object to end\n" +"\n" +">>> L.append(1)\n" +">>> L\n" +"[1]" + +#: ../../faq/general.rst:435 +msgid "" +"With the interpreter, documentation is never far from the student as they " +"are programming." +msgstr "有了直譯器，當學生正在程式設計時，說明文件永遠都不會遠離他們。" + +#: ../../faq/general.rst:438 +msgid "" +"There are also good IDEs for Python. IDLE is a cross-platform IDE for " +"Python that is written in Python using Tkinter. Emacs users will be happy to " +"know that there is a very good Python mode for Emacs. All of these " +"programming environments provide syntax highlighting, auto-indenting, and " +"access to the interactive interpreter while coding. Consult `the Python " +"wiki `_ for a full list of " +"Python editing environments." +msgstr "" +"Python 也有很好的 IDE。IDLE 是 Python 的一個跨平臺 IDE，它以 Python 編寫並使" +"用 Tkinter。Emacs 使用者會很高興知道 Emacs 有一個非常好的 Python 模式。這些程" +"式設計環境全部都能提供語法突顯 (syntax highlighting)、自動縮排，以及在編寫程" +"式時存取互動式直譯器。要查看 Python 編輯環境的完整清單，請參閱 `Python wiki " +"`_。" + +#: ../../faq/general.rst:446 +msgid "" +"If you want to discuss Python's use in education, you may be interested in " +"joining `the edu-sig mailing list `_." +msgstr "" +"如果你想討論 Python 在教育領域中的使用，你可能會有興趣加入 `edu-sig 郵件討論" +"群 `_。" diff --git a/faq/gui.po b/faq/gui.po index 3faa585cf1..e98e0402a2 100644 --- a/faq/gui.po +++ b/faq/gui.po @@ -1,141 +1,141 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Ching-Lung Chuang, 2015 -# Steven Hsu, 2022 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-09-23 07:52+0800\n" -"PO-Revision-Date: 2022-07-02 17:41+0800\n" -"Last-Translator: Steven Hsu \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" -"X-Generator: Poedit 3.1\n" - -#: ../../faq/gui.rst:5 -msgid "Graphic User Interface FAQ" -msgstr "圖形使用者介面常見問答集" - -#: ../../faq/gui.rst:8 -msgid "Contents" -msgstr "目錄" - -#: ../../faq/gui.rst:15 -msgid "General GUI Questions" -msgstr "圖形使用者介面 (GUI) 的常見問題" - -#: ../../faq/gui.rst:18 -msgid "What GUI toolkits exist for Python?" -msgstr "Python 有哪些 GUI 套件？" - -#: ../../faq/gui.rst:20 -msgid "" -"Standard builds of Python include an object-oriented interface to the Tcl/Tk " -"widget set, called :ref:`tkinter `. This is probably the easiest " -"to install (since it comes included with most `binary distributions `_ of Python) and use. For more info about Tk, " -"including pointers to the source, see the `Tcl/Tk home page `_. Tcl/Tk is fully portable to the macOS, Windows, and Unix platforms." -msgstr "" -"Python 的標準版本會包含一個 Tcl/Tk 小工具集 (widget set) 的物件導向介面，稱" -"為 :ref:`tkinter `。這可能是最容易安裝（因為它已包含在 Python 的大多" -"數\\ `二進制發行版本 `_\\ 中）和使用的。有" -"關 Tk 的詳細資訊（包含指向原始碼的指標），請參閱 `Tcl/Tk 首頁 `_。Tcl/Tk 在 macOS、Windows 和 Unix 平台上是完全可攜 (portable) 的。" - -#: ../../faq/gui.rst:28 -msgid "" -"Depending on what platform(s) you are aiming at, there are also several " -"alternatives. A `list of cross-platform `_ and `platform-specific `_ GUI " -"frameworks can be found on the python wiki." -msgstr "" -"根據你要使用的平台，還有其他幾種選擇。在 python wiki 上可以找到一份\\ `跨平台" -"的 `_\\ 以及\\ `各平台專屬的 `_ GUI 框架清單。" - -#: ../../faq/gui.rst:36 -msgid "Tkinter questions" -msgstr "Tkinter 的問答" - -#: ../../faq/gui.rst:39 -msgid "How do I freeze Tkinter applications?" -msgstr "如何凍結 Tkinter 應用程式？" - -#: ../../faq/gui.rst:41 -msgid "" -"Freeze is a tool to create stand-alone applications. When freezing Tkinter " -"applications, the applications will not be truly stand-alone, as the " -"application will still need the Tcl and Tk libraries." -msgstr "" -"凍結 (freeze) 是一個能建立獨立應用程式的工具。在凍結 Tkinter 應用程式時，該應" -"用程式不是真正的獨立，因為該應用程式仍然需要 Tcl 和 Tk 函式庫。" - -#: ../../faq/gui.rst:45 -msgid "" -"One solution is to ship the application with the Tcl and Tk libraries, and " -"point to them at run-time using the :envvar:`!TCL_LIBRARY` and :envvar:`!" -"TK_LIBRARY` environment variables." -msgstr "" -"將應用程式與 Tcl 和 Tk 函式庫一併發送是一種解決方法，並在執行環境 (run-time) " -"使用 :envvar:`!TCL_LIBRARY` 和 :envvar:`!TK_LIBRARY` 環境變數來指向該函式庫。" - -#: ../../faq/gui.rst:49 -msgid "" -"Various third-party freeze libraries such as py2exe and cx_Freeze have " -"handling for Tkinter applications built-in." -msgstr "" -"各種第三方凍結函式庫，例如 py2exe 和 cx_Freeze，都有內建了對 Tkinter 應用程式的處理。" - -#: ../../faq/gui.rst:54 -msgid "Can I have Tk events handled while waiting for I/O?" -msgstr "是否可以在等待 I/O 時處理 Tk 事件？" - -#: ../../faq/gui.rst:56 -msgid "" -"On platforms other than Windows, yes, and you don't even need threads! But " -"you'll have to restructure your I/O code a bit. Tk has the equivalent of " -"Xt's :c:func:`!XtAddInput` call, which allows you to register a callback " -"function which will be called from the Tk mainloop when I/O is possible on a " -"file descriptor. See :ref:`tkinter-file-handlers`." -msgstr "" -"在 Windows 以外的平台上是可以的，你甚至不需要執行緒！但是，你必須稍微調整你" -"的 I/O 程式碼。Tk 具有等效於 Xt 的 :c:func:`!XtAddInput` 的函式呼叫，它能讓你" -"記錄一個回呼 (callback) 函式，當 I/O 在一個檔案描述符 (file descriptor) 上可" -"進行時，該函式將會從 Tk mainloop 被呼叫。請參閱\\ :ref:`tkinter-file-" -"handlers`。" - -#: ../../faq/gui.rst:64 -msgid "I can't get key bindings to work in Tkinter: why?" -msgstr "我無法讓鍵繫結 (key binding) 在 Tkinter 中作用：為什麼？" - -#: ../../faq/gui.rst:66 -msgid "" -"An often-heard complaint is that event handlers :ref:`bound ` to events with the :meth:`!bind` method don't get handled even when " -"the appropriate key is pressed." -msgstr "" -"一個經常聽到的抱怨是，儘管事件處理程式 (event handler) 已經\\ :ref:`繫結 " -"`\\ 到帶有 :meth:`!bind` method 的事件，但在按下相應的鍵" -"時，該事件也沒有被處理。" - -#: ../../faq/gui.rst:70 -msgid "" -"The most common cause is that the widget to which the binding applies " -"doesn't have \"keyboard focus\". Check out the Tk documentation for the " -"focus command. Usually a widget is given the keyboard focus by clicking in " -"it (but not for labels; see the takefocus option)." -msgstr "" -"最常見的原因是，繫結到的小工具並沒有「鍵盤焦點 (keyboard focus)」。請查看 Tk " -"說明文件中關於焦點命令的敘述。通常，點擊一個小工具，會讓它得到鍵盤焦點（但不" -"適用於標籤；請參閱 takefocus 選項）。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Ching-Lung Chuang, 2015 +# Steven Hsu, 2022 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-09-23 07:52+0800\n" +"PO-Revision-Date: 2022-07-02 17:41+0800\n" +"Last-Translator: Steven Hsu \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" +"X-Generator: Poedit 3.1\n" + +#: ../../faq/gui.rst:5 +msgid "Graphic User Interface FAQ" +msgstr "圖形使用者介面常見問答集" + +#: ../../faq/gui.rst:8 +msgid "Contents" +msgstr "目錄" + +#: ../../faq/gui.rst:15 +msgid "General GUI Questions" +msgstr "圖形使用者介面 (GUI) 的常見問題" + +#: ../../faq/gui.rst:18 +msgid "What GUI toolkits exist for Python?" +msgstr "Python 有哪些 GUI 套件？" + +#: ../../faq/gui.rst:20 +msgid "" +"Standard builds of Python include an object-oriented interface to the Tcl/Tk " +"widget set, called :ref:`tkinter `. This is probably the easiest " +"to install (since it comes included with most `binary distributions `_ of Python) and use. For more info about Tk, " +"including pointers to the source, see the `Tcl/Tk home page `_. Tcl/Tk is fully portable to the macOS, Windows, and Unix platforms." +msgstr "" +"Python 的標準版本會包含一個 Tcl/Tk 小工具集 (widget set) 的物件導向介面，稱" +"為 :ref:`tkinter `。這可能是最容易安裝（因為它已包含在 Python 的大多" +"數\\ `二進制發行版本 `_\\ 中）和使用的。有" +"關 Tk 的詳細資訊（包含指向原始碼的指標），請參閱 `Tcl/Tk 首頁 `_。Tcl/Tk 在 macOS、Windows 和 Unix 平台上是完全可攜 (portable) 的。" + +#: ../../faq/gui.rst:28 +msgid "" +"Depending on what platform(s) you are aiming at, there are also several " +"alternatives. A `list of cross-platform `_ and `platform-specific `_ GUI " +"frameworks can be found on the python wiki." +msgstr "" +"根據你要使用的平台，還有其他幾種選擇。在 python wiki 上可以找到一份\\ `跨平台" +"的 `_\\ 以及\\ `各平台專屬的 `_ GUI 框架清單。" + +#: ../../faq/gui.rst:36 +msgid "Tkinter questions" +msgstr "Tkinter 的問答" + +#: ../../faq/gui.rst:39 +msgid "How do I freeze Tkinter applications?" +msgstr "如何凍結 Tkinter 應用程式？" + +#: ../../faq/gui.rst:41 +msgid "" +"Freeze is a tool to create stand-alone applications. When freezing Tkinter " +"applications, the applications will not be truly stand-alone, as the " +"application will still need the Tcl and Tk libraries." +msgstr "" +"凍結 (freeze) 是一個能建立獨立應用程式的工具。在凍結 Tkinter 應用程式時，該應" +"用程式不是真正的獨立，因為該應用程式仍然需要 Tcl 和 Tk 函式庫。" + +#: ../../faq/gui.rst:45 +msgid "" +"One solution is to ship the application with the Tcl and Tk libraries, and " +"point to them at run-time using the :envvar:`!TCL_LIBRARY` and :envvar:`!" +"TK_LIBRARY` environment variables." +msgstr "" +"將應用程式與 Tcl 和 Tk 函式庫一併發送是一種解決方法，並在執行環境 (run-time) " +"使用 :envvar:`!TCL_LIBRARY` 和 :envvar:`!TK_LIBRARY` 環境變數來指向該函式庫。" + +#: ../../faq/gui.rst:49 +msgid "" +"Various third-party freeze libraries such as py2exe and cx_Freeze have " +"handling for Tkinter applications built-in." +msgstr "" +"各種第三方凍結函式庫，例如 py2exe 和 cx_Freeze，都有內建了對 Tkinter 應用程式的處理。" + +#: ../../faq/gui.rst:54 +msgid "Can I have Tk events handled while waiting for I/O?" +msgstr "是否可以在等待 I/O 時處理 Tk 事件？" + +#: ../../faq/gui.rst:56 +msgid "" +"On platforms other than Windows, yes, and you don't even need threads! But " +"you'll have to restructure your I/O code a bit. Tk has the equivalent of " +"Xt's :c:func:`!XtAddInput` call, which allows you to register a callback " +"function which will be called from the Tk mainloop when I/O is possible on a " +"file descriptor. See :ref:`tkinter-file-handlers`." +msgstr "" +"在 Windows 以外的平台上是可以的，你甚至不需要執行緒！但是，你必須稍微調整你" +"的 I/O 程式碼。Tk 具有等效於 Xt 的 :c:func:`!XtAddInput` 的函式呼叫，它能讓你" +"記錄一個回呼 (callback) 函式，當 I/O 在一個檔案描述符 (file descriptor) 上可" +"進行時，該函式將會從 Tk mainloop 被呼叫。請參閱\\ :ref:`tkinter-file-" +"handlers`。" + +#: ../../faq/gui.rst:64 +msgid "I can't get key bindings to work in Tkinter: why?" +msgstr "我無法讓鍵繫結 (key binding) 在 Tkinter 中作用：為什麼？" + +#: ../../faq/gui.rst:66 +msgid "" +"An often-heard complaint is that event handlers :ref:`bound ` to events with the :meth:`!bind` method don't get handled even when " +"the appropriate key is pressed." +msgstr "" +"一個經常聽到的抱怨是，儘管事件處理程式 (event handler) 已經\\ :ref:`繫結 " +"`\\ 到帶有 :meth:`!bind` method 的事件，但在按下相應的鍵" +"時，該事件也沒有被處理。" + +#: ../../faq/gui.rst:70 +msgid "" +"The most common cause is that the widget to which the binding applies " +"doesn't have \"keyboard focus\". Check out the Tk documentation for the " +"focus command. Usually a widget is given the keyboard focus by clicking in " +"it (but not for labels; see the takefocus option)." +msgstr "" +"最常見的原因是，繫結到的小工具並沒有「鍵盤焦點 (keyboard focus)」。請查看 Tk " +"說明文件中關於焦點命令的敘述。通常，點擊一個小工具，會讓它得到鍵盤焦點（但不" +"適用於標籤；請參閱 takefocus 選項）。" diff --git a/faq/index.po b/faq/index.po index 914e8e08c4..a40fb0343a 100644 --- a/faq/index.po +++ b/faq/index.po @@ -1,23 +1,23 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Adrian Liaw , 2015 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2018-06-26 18:54+0800\n" -"PO-Revision-Date: 2017-09-22 18:26+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" - -#: ../../faq/index.rst:5 -msgid "Python Frequently Asked Questions" -msgstr "Python 常見問題" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Adrian Liaw , 2015 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2018-06-26 18:54+0800\n" +"PO-Revision-Date: 2017-09-22 18:26+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" + +#: ../../faq/index.rst:5 +msgid "Python Frequently Asked Questions" +msgstr "Python 常見問題" diff --git a/faq/installed.po b/faq/installed.po index f6a7bc424f..a55b7fc248 100644 --- a/faq/installed.po +++ b/faq/installed.po @@ -1,136 +1,136 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Ching-Lung Chuang, 2015 -# Matt Wang , 2021 -# -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2021-09-24 00:11+0000\n" -"PO-Revision-Date: 2021-12-09 21:50+0800\n" -"Last-Translator: Ching-Lung Chuang\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" -"X-Generator: Poedit 3.0\n" - -#: ../../faq/installed.rst:3 -msgid "\"Why is Python Installed on my Computer?\" FAQ" -msgstr "「為什麼 Python 被安裝在我的機器上？」常見問答集" - -#: ../../faq/installed.rst:6 -msgid "What is Python?" -msgstr "什麼是 Python？" - -#: ../../faq/installed.rst:8 -msgid "" -"Python is a programming language. It's used for many different " -"applications. It's used in some high schools and colleges as an introductory " -"programming language because Python is easy to learn, but it's also used by " -"professional software developers at places such as Google, NASA, and " -"Lucasfilm Ltd." -msgstr "" -"Python 是一種程式語言。它被使用於不同種類的應用程式中。因為 Python 屬於容易學" -"習的語言，它在一些高中和大學課程中被用作介紹程式語言的工具；但它也被專業的軟" -"體開發人員所使用，例如 Google、美國太空總署與盧卡斯電影公司。" - -#: ../../faq/installed.rst:13 -msgid "" -"If you wish to learn more about Python, start with the `Beginner's Guide to " -"Python `_." -msgstr "" -"若你想學習更多關於 Python 的知識，可以先從 `Python 初學者指引 `_\\ 開始閱讀。" - -#: ../../faq/installed.rst:18 -msgid "Why is Python installed on my machine?" -msgstr "為什麼 Python 被安裝在我的機器上?" - -#: ../../faq/installed.rst:20 -msgid "" -"If you find Python installed on your system but don't remember installing " -"it, there are several possible ways it could have gotten there." -msgstr "" -"若你發現曾安裝 Python 於系統中，但不記得何時安裝過，那有可能是透過以下幾種途" -"徑安裝的。" - -#: ../../faq/installed.rst:23 -msgid "" -"Perhaps another user on the computer wanted to learn programming and " -"installed it; you'll have to figure out who's been using the machine and " -"might have installed it." -msgstr "" -"也許其他使用此電腦的使用者想要學習撰寫程式並且安裝了 Python；你需要回想一下誰" -"曾經使用此機器且可能進行安裝。" - -#: ../../faq/installed.rst:26 -msgid "" -"A third-party application installed on the machine might have been written " -"in Python and included a Python installation. There are many such " -"applications, from GUI programs to network servers and administrative " -"scripts." -msgstr "" -"安裝於機器的第三方應用程式可能以 Python 語言撰寫並且安裝了 Python。這樣的應用" -"程式並不少，從 GUI 程式到網路伺服器和管理者腳本都有。" - -#: ../../faq/installed.rst:29 -msgid "" -"Some Windows machines also have Python installed. At this writing we're " -"aware of computers from Hewlett-Packard and Compaq that include Python. " -"Apparently some of HP/Compaq's administrative tools are written in Python." -msgstr "" -"一些安裝 Windows 的機器也被安裝 Python。截至撰寫此文件的當下，我們得知 HP 與 " -"Compaq 出廠的機器都預設安裝 Python。顯然的 HP 與 Compaq 部分的管理工具程式是" -"透過 Python 語言所撰寫。" - -#: ../../faq/installed.rst:32 -msgid "" -"Many Unix-compatible operating systems, such as macOS and some Linux " -"distributions, have Python installed by default; it's included in the base " -"installation." -msgstr "" -"許多相容於 Unix 系統，例如 macOS 和一些 Linux 發行版本預設安裝 Python；它被包" -"含在基礎安裝內。" - -#: ../../faq/installed.rst:38 -msgid "Can I delete Python?" -msgstr "我能夠自行刪除 Python 嗎？" - -#: ../../faq/installed.rst:40 -msgid "That depends on where Python came from." -msgstr "需要依據 Python 的安裝方式決定。" - -#: ../../faq/installed.rst:42 -msgid "" -"If someone installed it deliberately, you can remove it without hurting " -"anything. On Windows, use the Add/Remove Programs icon in the Control Panel." -msgstr "" -"若有人是有意地安裝 Python，你可自行移除移除它，這不會造成其他影響。Windows 作" -"業系統中，請於控制台 (Control Panel) 中尋找新增/移除程式來解除安裝。" - -#: ../../faq/installed.rst:45 -msgid "" -"If Python was installed by a third-party application, you can also remove " -"it, but that application will no longer work. You should use that " -"application's uninstaller rather than removing Python directly." -msgstr "" -"若 Python 是透過第三方應用程式安裝時，你也可自行移除，不過該應用程式將無法正" -"常執行。你應該使用應用程式解除安裝功能而非直接刪除 Python。" - -#: ../../faq/installed.rst:49 -msgid "" -"If Python came with your operating system, removing it is not recommended. " -"If you remove it, whatever tools were written in Python will no longer run, " -"and some of them might be important to you. Reinstalling the whole system " -"would then be required to fix things again." -msgstr "" -"當作業系統預設安裝 Python，不建議移除它。對你而言某些工具程式是重要不可或缺" -"的，若自行移除它，透過 Python 撰寫的工具程式將無法正常執行。重新安裝整個系" -"統，才能再次解決這些問題。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Ching-Lung Chuang, 2015 +# Matt Wang , 2021 +# +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2021-09-24 00:11+0000\n" +"PO-Revision-Date: 2021-12-09 21:50+0800\n" +"Last-Translator: Ching-Lung Chuang\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" +"X-Generator: Poedit 3.0\n" + +#: ../../faq/installed.rst:3 +msgid "\"Why is Python Installed on my Computer?\" FAQ" +msgstr "「為什麼 Python 被安裝在我的機器上？」常見問答集" + +#: ../../faq/installed.rst:6 +msgid "What is Python?" +msgstr "什麼是 Python？" + +#: ../../faq/installed.rst:8 +msgid "" +"Python is a programming language. It's used for many different " +"applications. It's used in some high schools and colleges as an introductory " +"programming language because Python is easy to learn, but it's also used by " +"professional software developers at places such as Google, NASA, and " +"Lucasfilm Ltd." +msgstr "" +"Python 是一種程式語言。它被使用於不同種類的應用程式中。因為 Python 屬於容易學" +"習的語言，它在一些高中和大學課程中被用作介紹程式語言的工具；但它也被專業的軟" +"體開發人員所使用，例如 Google、美國太空總署與盧卡斯電影公司。" + +#: ../../faq/installed.rst:13 +msgid "" +"If you wish to learn more about Python, start with the `Beginner's Guide to " +"Python `_." +msgstr "" +"若你想學習更多關於 Python 的知識，可以先從 `Python 初學者指引 `_\\ 開始閱讀。" + +#: ../../faq/installed.rst:18 +msgid "Why is Python installed on my machine?" +msgstr "為什麼 Python 被安裝在我的機器上?" + +#: ../../faq/installed.rst:20 +msgid "" +"If you find Python installed on your system but don't remember installing " +"it, there are several possible ways it could have gotten there." +msgstr "" +"若你發現曾安裝 Python 於系統中，但不記得何時安裝過，那有可能是透過以下幾種途" +"徑安裝的。" + +#: ../../faq/installed.rst:23 +msgid "" +"Perhaps another user on the computer wanted to learn programming and " +"installed it; you'll have to figure out who's been using the machine and " +"might have installed it." +msgstr "" +"也許其他使用此電腦的使用者想要學習撰寫程式並且安裝了 Python；你需要回想一下誰" +"曾經使用此機器且可能進行安裝。" + +#: ../../faq/installed.rst:26 +msgid "" +"A third-party application installed on the machine might have been written " +"in Python and included a Python installation. There are many such " +"applications, from GUI programs to network servers and administrative " +"scripts." +msgstr "" +"安裝於機器的第三方應用程式可能以 Python 語言撰寫並且安裝了 Python。這樣的應用" +"程式並不少，從 GUI 程式到網路伺服器和管理者腳本都有。" + +#: ../../faq/installed.rst:29 +msgid "" +"Some Windows machines also have Python installed. At this writing we're " +"aware of computers from Hewlett-Packard and Compaq that include Python. " +"Apparently some of HP/Compaq's administrative tools are written in Python." +msgstr "" +"一些安裝 Windows 的機器也被安裝 Python。截至撰寫此文件的當下，我們得知 HP 與 " +"Compaq 出廠的機器都預設安裝 Python。顯然的 HP 與 Compaq 部分的管理工具程式是" +"透過 Python 語言所撰寫。" + +#: ../../faq/installed.rst:32 +msgid "" +"Many Unix-compatible operating systems, such as macOS and some Linux " +"distributions, have Python installed by default; it's included in the base " +"installation." +msgstr "" +"許多相容於 Unix 系統，例如 macOS 和一些 Linux 發行版本預設安裝 Python；它被包" +"含在基礎安裝內。" + +#: ../../faq/installed.rst:38 +msgid "Can I delete Python?" +msgstr "我能夠自行刪除 Python 嗎？" + +#: ../../faq/installed.rst:40 +msgid "That depends on where Python came from." +msgstr "需要依據 Python 的安裝方式決定。" + +#: ../../faq/installed.rst:42 +msgid "" +"If someone installed it deliberately, you can remove it without hurting " +"anything. On Windows, use the Add/Remove Programs icon in the Control Panel." +msgstr "" +"若有人是有意地安裝 Python，你可自行移除移除它，這不會造成其他影響。Windows 作" +"業系統中，請於控制台 (Control Panel) 中尋找新增/移除程式來解除安裝。" + +#: ../../faq/installed.rst:45 +msgid "" +"If Python was installed by a third-party application, you can also remove " +"it, but that application will no longer work. You should use that " +"application's uninstaller rather than removing Python directly." +msgstr "" +"若 Python 是透過第三方應用程式安裝時，你也可自行移除，不過該應用程式將無法正" +"常執行。你應該使用應用程式解除安裝功能而非直接刪除 Python。" + +#: ../../faq/installed.rst:49 +msgid "" +"If Python came with your operating system, removing it is not recommended. " +"If you remove it, whatever tools were written in Python will no longer run, " +"and some of them might be important to you. Reinstalling the whole system " +"would then be required to fix things again." +msgstr "" +"當作業系統預設安裝 Python，不建議移除它。對你而言某些工具程式是重要不可或缺" +"的，若自行移除它，透過 Python 撰寫的工具程式將無法正常執行。重新安裝整個系" +"統，才能再次解決這些問題。" diff --git a/faq/library.po b/faq/library.po index a69d64d728..3052e51756 100644 --- a/faq/library.po +++ b/faq/library.po @@ -1,1349 +1,1349 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# jerrychen , 2016 -# Ching-Lung Chuang, 2015 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: 2023-02-18 13:22+0800\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" -"X-Generator: Poedit 3.2.2\n" - -#: ../../faq/library.rst:5 -msgid "Library and Extension FAQ" -msgstr "函式庫和擴充功能的常見問題" - -#: ../../faq/library.rst:8 -msgid "Contents" -msgstr "目錄" - -#: ../../faq/library.rst:12 -msgid "General Library Questions" -msgstr "常見函式問題" - -#: ../../faq/library.rst:15 -msgid "How do I find a module or application to perform task X?" -msgstr "我如何找到執行任務 X 的模組或應用程式？" - -#: ../../faq/library.rst:17 -msgid "" -"Check :ref:`the Library Reference ` to see if there's a " -"relevant standard library module. (Eventually you'll learn what's in the " -"standard library and will be able to skip this step.)" -msgstr "" -"查看\\ :ref:`函式庫參照 `\\ 以了解是否有相關的標準函式庫模組。 " -"（當你熟悉標準函式庫中的內容後就可以能跳過這一步。）" - -#: ../../faq/library.rst:21 -msgid "" -"For third-party packages, search the `Python Package Index `_ or try `Google `_ or another web search " -"engine. Searching for \"Python\" plus a keyword or two for your topic of " -"interest will usually find something helpful." -msgstr "" -"對於第三方套件，搜尋 `Python 套件索引 `_\\ 或嘗試使用 `Google " -"`_ 或其他網路搜尋引擎。搜尋 \"Python\" 加上你感興趣主題的一" -"兩個關鍵字，通常能夠找到有用的東西。" - -#: ../../faq/library.rst:28 -msgid "Where is the math.py (socket.py, regex.py, etc.) source file?" -msgstr "哪裡可以找到 math.py (socket.py, regex.py, 等...) 來源檔案？" - -#: ../../faq/library.rst:30 -#, fuzzy -msgid "" -"If you can't find a source file for a module it may be a built-in or " -"dynamically loaded module implemented in C, C++ or other compiled language. " -"In this case you may not have the source file or it may be something " -"like :file:`mathmodule.c`, somewhere in a C source directory (not on the " -"Python Path)." -msgstr "" -"如果找不到模組的源檔案，它可能是用 C、C++ 或其他編譯語言實作的內置或動態載入" -"的模組。在這種情況下，你可能沒有源檔案，或者它可能類似" -"於 :file:`mathmodule.c`，位於 C 源目錄中（不在 Python 路徑中）。" - -#: ../../faq/library.rst:35 -msgid "There are (at least) three kinds of modules in Python:" -msgstr "有（至少）三種 Python 模組：" - -#: ../../faq/library.rst:37 -msgid "modules written in Python (.py);" -msgstr "以 Python 編寫的模組 (.py)；" - -#: ../../faq/library.rst:38 -msgid "" -"modules written in C and dynamically loaded (.dll, .pyd, .so, .sl, etc);" -msgstr "用 C 編寫並動態載入的模組（.dll、.pyd、.so、.sl 等）；" - -#: ../../faq/library.rst:39 -msgid "" -"modules written in C and linked with the interpreter; to get a list of " -"these, type::" -msgstr "用 C 編寫並與直譯器鏈接的模組；要獲得這些 list，請輸入： ::" - -#: ../../faq/library.rst:42 -msgid "" -"import sys\n" -"print(sys.builtin_module_names)" -msgstr "" -"import sys\n" -"print(sys.builtin_module_names)" - -#: ../../faq/library.rst:47 -msgid "How do I make a Python script executable on Unix?" -msgstr "我如何使 Python script 執行在 Unix？" - -#: ../../faq/library.rst:49 -#, fuzzy -msgid "" -"You need to do two things: the script file's mode must be executable and the " -"first line must begin with ``#!`` followed by the path of the Python " -"interpreter." -msgstr "" -"你需要作兩件事：腳本程式必須可以被執行而且第一行必須 ``#!`` 開頭後面接上 " -"Python 直譯器的路徑。" - -#: ../../faq/library.rst:53 -msgid "" -"The first is done by executing ``chmod +x scriptfile`` or perhaps ``chmod " -"755 scriptfile``." -msgstr "" -"第一個是透過執行 ``chmod +x scriptfile`` 或者可能是 ``chmod 755 scriptfile`` " -"來完成的。" - -#: ../../faq/library.rst:56 -msgid "" -"The second can be done in a number of ways. The most straightforward way is " -"to write ::" -msgstr "第二個則可以透過多種方式完成。最直接的方法是寫： ::" - -#: ../../faq/library.rst:59 -msgid "#!/usr/local/bin/python" -msgstr "#!/usr/local/bin/python" - -#: ../../faq/library.rst:61 -msgid "" -"as the very first line of your file, using the pathname for where the Python " -"interpreter is installed on your platform." -msgstr "作為檔案的第一行，使用 Python 直譯器安裝在你的平台上的路徑名稱。" - -#: ../../faq/library.rst:64 -#, fuzzy -msgid "" -"If you would like the script to be independent of where the Python " -"interpreter lives, you can use the :program:`env` program. Almost all Unix " -"variants support the following, assuming the Python interpreter is in a " -"directory on the user's :envvar:`PATH`::" -msgstr "" -"如果你希望腳本獨立於 Python 直譯器所在的位置，你可以使用 :program:`env` 程" -"式。幾乎所有 Unix 變體都支援以下內容，假設 Python 直譯器位於使用者" -"的 :envvar:`PATH` 上的目錄中： ::" - -#: ../../faq/library.rst:69 -msgid "#!/usr/bin/env python" -msgstr "#!/usr/bin/env python" - -#: ../../faq/library.rst:71 -msgid "" -"*Don't* do this for CGI scripts. The :envvar:`PATH` variable for CGI " -"scripts is often very minimal, so you need to use the actual absolute " -"pathname of the interpreter." -msgstr "" -"*不要*\\ 對 CGI 腳本執行此操作。CGI 腳本的 :envvar:`PATH` 變數通常非常小，因" -"此你需要使用直譯器的實際絕對路徑名稱。" - -#: ../../faq/library.rst:75 -#, fuzzy -msgid "" -"Occasionally, a user's environment is so full that the :program:`/usr/bin/" -"env` program fails; or there's no env program at all. In that case, you can " -"try the following hack (due to Alex Rezinsky):" -msgstr "" -"有時，使用者的環境太滿以至於:program:`/usr/bin/env` 程式失敗；或者根本就沒有 " -"env 程式。在這種情況下，你可以嘗試以下 hack（由於 Alex Rezinsky）：" - -#: ../../faq/library.rst:79 -msgid "" -"#! /bin/sh\n" -"\"\"\":\"\n" -"exec python $0 ${1+\"$@\"}\n" -"\"\"\"" -msgstr "" -"#! /bin/sh\n" -"\"\"\":\"\n" -"exec python $0 ${1+\"$@\"}\n" -"\"\"\"" - -#: ../../faq/library.rst:86 -msgid "" -"The minor disadvantage is that this defines the script's __doc__ string. " -"However, you can fix that by adding ::" -msgstr "" -"次要缺點是這定義了腳本的 __doc__ 字串。但是你可以透過新增下面這一行來解決這個" -"問題： ::" - -#: ../../faq/library.rst:89 -msgid "__doc__ = \"\"\"...Whatever...\"\"\"" -msgstr "__doc__ = \"\"\"...Whatever...\"\"\"" - -#: ../../faq/library.rst:94 -msgid "Is there a curses/termcap package for Python?" -msgstr "是否有適用於 Python 的 curses/termcap 套件？" - -#: ../../faq/library.rst:98 -#, fuzzy -msgid "" -"For Unix variants: The standard Python source distribution comes with a " -"curses module in the :source:`Modules` subdirectory, though it's not " -"compiled by default. (Note that this is not available in the Windows " -"distribution -- there is no curses module for Windows.)" -msgstr "" -"對於 Unix 變體：標準 Python 源程式碼分發版在 :source:`Modules` 子目錄中附帶一" -"個 curses 模組，但預設情況下未編譯它。（請注意，這在 Windows 發行版中不可用——" -"沒有適用於 Windows 的 curses 模組。）" - -#: ../../faq/library.rst:103 -#, fuzzy -msgid "" -"The :mod:`curses` module supports basic curses features as well as many " -"additional functions from ncurses and SYSV curses such as colour, " -"alternative character set support, pads, and mouse support. This means the " -"module isn't compatible with operating systems that only have BSD curses, " -"but there don't seem to be any currently maintained OSes that fall into this " -"category." -msgstr "" -":mod:`curses` 模組支援基本的 curses 功能以及 ncurses 和 SYSV curses 的許多附" -"加功能，例如顏色、替代字元集支援、鍵盤和鼠標支援。這意味著該模組與僅具有 BSD " -"curses 的作業系統不相容，但似乎沒有任何目前維護的作業系統屬於此類型。" - -#: ../../faq/library.rst:111 -msgid "Is there an equivalent to C's onexit() in Python?" -msgstr "Python 中是否有等同於 C 的 onexit() 的函式？" - -#: ../../faq/library.rst:113 -msgid "" -"The :mod:`atexit` module provides a register function that is similar to " -"C's :c:func:`!onexit`." -msgstr ":mod:`atexit` 模組提供了一個類似於 C :c:func:`!onexit` 的註冊函式。" - -#: ../../faq/library.rst:118 -msgid "Why don't my signal handlers work?" -msgstr "為什麼我的訊號處理程式不起作用？" - -#: ../../faq/library.rst:120 -msgid "" -"The most common problem is that the signal handler is declared with the " -"wrong argument list. It is called as ::" -msgstr "最常見的問題是訊號處理程式是用錯誤的引數串列聲明的。它以以下形式來呼叫： ::" - -#: ../../faq/library.rst:123 -msgid "handler(signum, frame)" -msgstr "handler(signum, frame)" - -#: ../../faq/library.rst:125 -msgid "so it should be declared with two parameters::" -msgstr "所以它應該用兩個參數聲明： ::" - -#: ../../faq/library.rst:127 -msgid "" -"def handler(signum, frame):\n" -" ..." -msgstr "" -"def handler(signum, frame):\n" -" ..." - -#: ../../faq/library.rst:132 -msgid "Common tasks" -msgstr "常見課題" - -#: ../../faq/library.rst:135 -msgid "How do I test a Python program or component?" -msgstr "如何測試 Python 程式或元件？" - -#: ../../faq/library.rst:137 -#, fuzzy -msgid "" -"Python comes with two testing frameworks. The :mod:`doctest` module finds " -"examples in the docstrings for a module and runs them, comparing the output " -"with the expected output given in the docstring." -msgstr "" -"Python 帶有兩個測試框架。 :mod:`doctest` 模組在模組的文件字串中查詢示例並運行" -"它們，將輸出與文件字串中給出的預期輸出進行比較。" - -#: ../../faq/library.rst:141 -msgid "" -"The :mod:`unittest` module is a fancier testing framework modelled on Java " -"and Smalltalk testing frameworks." -msgstr "" -":mod:`unittest` 模組是一個更炫目的測試框架，它以 Java 和 Smalltalk 測試框架為" -"模型。" - -#: ../../faq/library.rst:144 -#, fuzzy -msgid "" -"To make testing easier, you should use good modular design in your program. " -"Your program should have almost all functionality encapsulated in either " -"functions or class methods -- and this sometimes has the surprising and " -"delightful effect of making the program run faster (because local variable " -"accesses are faster than global accesses). Furthermore the program should " -"avoid depending on mutating global variables, since this makes testing much " -"more difficult to do." -msgstr "" -"為了使測試更容易，你應該在程式中使用良好的模組化設計。你的程式應該將幾乎所有" -"功能都封裝在函式或類別方法中——這有時會產生使程式運行得更快的令人驚訝和令人愉" -"快的效果（因為局部變數存取比全域存取更快）。此外，該程式應避免依賴於可變的全" -"局變數，因為這會使測試變得更加困難。" - -#: ../../faq/library.rst:152 -#, fuzzy -msgid "The \"global main logic\" of your program may be as simple as ::" -msgstr "你程式的「全域主邏輯」可能像一樣簡單： ::" - -#: ../../faq/library.rst:154 -msgid "" -"if __name__ == \"__main__\":\n" -" main_logic()" -msgstr "" -"if __name__ == \"__main__\":\n" -" main_logic()" - -#: ../../faq/library.rst:157 -#, fuzzy -msgid "at the bottom of the main module of your program." -msgstr "在你的程式主模組的底端。" - -#: ../../faq/library.rst:159 -#, fuzzy -msgid "" -"Once your program is organized as a tractable collection of function and " -"class behaviours, you should write test functions that exercise the " -"behaviours. A test suite that automates a sequence of tests can be " -"associated with each module. This sounds like a lot of work, but since " -"Python is so terse and flexible it's surprisingly easy. You can make coding " -"much more pleasant and fun by writing your test functions in parallel with " -"the \"production code\", since this makes it easy to find bugs and even " -"design flaws earlier." -msgstr "" -"一旦你的程式被組織為函式和類別行為的易於處理的集合，你就應該編寫測試函式來執" -"行這些行為。可將一系列測試自動化的測試套件與每個模組相關聯。這聽起來像是很多" -"工作，但由於 Python 如此簡潔和靈活，所以它非常容易。透過與 \"生產程式碼\" 並" -"行編寫測試函式，你可以使編碼變得更加愉快和有趣，因為這使得更早地發現錯誤甚至" -"設計缺陷變得容易。" - -#: ../../faq/library.rst:167 -#, fuzzy -msgid "" -"\"Support modules\" that are not intended to be the main module of a program " -"may include a self-test of the module. ::" -msgstr "不打算成為程式主要模組的 \"支援模組\" 可能包括模組的自檢： ::" - -#: ../../faq/library.rst:170 -msgid "" -"if __name__ == \"__main__\":\n" -" self_test()" -msgstr "" -"if __name__ == \"__main__\":\n" -" self_test()" - -#: ../../faq/library.rst:173 -#, fuzzy -msgid "" -"Even programs that interact with complex external interfaces may be tested " -"when the external interfaces are unavailable by using \"fake\" interfaces " -"implemented in Python." -msgstr "" -"即使是與復雜外部介面交互的程式也可以在外部介面不可用時透過使用 Python 中實作" -"的 \"假\" 介面進行測試。" - -#: ../../faq/library.rst:179 -msgid "How do I create documentation from doc strings?" -msgstr "如何從文件字串建立文件？" - -#: ../../faq/library.rst:181 -#, fuzzy -msgid "" -"The :mod:`pydoc` module can create HTML from the doc strings in your Python " -"source code. An alternative for creating API documentation purely from " -"docstrings is `epydoc `_. `Sphinx `_ can also include docstring content." -msgstr "" -":mod:`pydoc` 模組可以從 Python 源程式碼中的文件字串建立 HTML。純粹從文件字串" -"建立 API 文件的另一種方法是 `epydoc `_。 " -"`Sphinx `_ 也可以包含文件字串內容。" - -#: ../../faq/library.rst:188 -#, fuzzy -msgid "How do I get a single keypress at a time?" -msgstr "我如何一次獲得一個按鍵？" - -#: ../../faq/library.rst:190 -msgid "" -"For Unix variants there are several solutions. It's straightforward to do " -"this using curses, but curses is a fairly large module to learn." -msgstr "" -"對於 Unix 變體有幾種解決方案。使用 curses 執行此操作很直觀，但 curses 是一" -"個學習成本較大的模組。" - -#: ../../faq/library.rst:234 -msgid "Threads" -msgstr "執行緒" - -#: ../../faq/library.rst:237 -msgid "How do I program using threads?" -msgstr "如何使用執行緒編寫程式？" - -#: ../../faq/library.rst:239 -#, fuzzy -msgid "" -"Be sure to use the :mod:`threading` module and not the :mod:`_thread` " -"module. The :mod:`threading` module builds convenient abstractions on top of " -"the low-level primitives provided by the :mod:`_thread` module." -msgstr "" -"請務必使用 :mod:`threading` 模組而不是 :mod:`_thread` 模" -"組。 :mod:`threading` 模組在 :mod:`_thread` 模組提供的低階原語之上構建方便的" -"抽象。" - -#: ../../faq/library.rst:245 -msgid "None of my threads seem to run: why?" -msgstr "我的執行緒似乎都沒有運行：為什麼？" - -#: ../../faq/library.rst:247 -#, fuzzy -msgid "" -"As soon as the main thread exits, all threads are killed. Your main thread " -"is running too quickly, giving the threads no time to do any work." -msgstr "" -"一旦主執行緒退出，所有執行緒都會被殺死。你的主執行緒運行得太快，執行緒沒有時" -"間做任何工作。" - -#: ../../faq/library.rst:250 -msgid "" -"A simple fix is to add a sleep to the end of the program that's long enough " -"for all the threads to finish::" -msgstr "" -"一個簡單的修復方式是在程式末尾新增一個足夠長的 sleep，讓所有執行緒都完成： ::" - -#: ../../faq/library.rst:253 -msgid "" -"import threading, time\n" -"\n" -"def thread_task(name, n):\n" -" for i in range(n):\n" -" print(name, i)\n" -"\n" -"for i in range(10):\n" -" T = threading.Thread(target=thread_task, args=(str(i), i))\n" -" T.start()\n" -"\n" -"time.sleep(10) # <---------------------------!" -msgstr "" -"import threading, time\n" -"\n" -"def thread_task(name, n):\n" -" for i in range(n):\n" -" print(name, i)\n" -"\n" -"for i in range(10):\n" -" T = threading.Thread(target=thread_task, args=(str(i), i))\n" -" T.start()\n" -"\n" -"time.sleep(10) # <---------------------------!" - -#: ../../faq/library.rst:265 -#, fuzzy -msgid "" -"But now (on many platforms) the threads don't run in parallel, but appear to " -"run sequentially, one at a time! The reason is that the OS thread scheduler " -"doesn't start a new thread until the previous thread is blocked." -msgstr "" -"但是現在（在許多平台上）執行緒不是並行運行的，而是看起來是順序運行的，一次一" -"個！原因是作業系統執行緒調度程式在前一個執行緒被阻塞之前不會啟動一個新執行" -"緒。" - -#: ../../faq/library.rst:269 -msgid "A simple fix is to add a tiny sleep to the start of the run function::" -msgstr "一個簡單的修復方式是在運行函式的開頭新增一個小 sleep： ::" - -#: ../../faq/library.rst:271 -msgid "" -"def thread_task(name, n):\n" -" time.sleep(0.001) # <--------------------!\n" -" for i in range(n):\n" -" print(name, i)\n" -"\n" -"for i in range(10):\n" -" T = threading.Thread(target=thread_task, args=(str(i), i))\n" -" T.start()\n" -"\n" -"time.sleep(10)" -msgstr "" -"def thread_task(name, n):\n" -" time.sleep(0.001) # <--------------------!\n" -" for i in range(n):\n" -" print(name, i)\n" -"\n" -"for i in range(10):\n" -" T = threading.Thread(target=thread_task, args=(str(i), i))\n" -" T.start()\n" -"\n" -"time.sleep(10)" - -#: ../../faq/library.rst:282 -#, fuzzy -msgid "" -"Instead of trying to guess a good delay value for :func:`time.sleep`, it's " -"better to use some kind of semaphore mechanism. One idea is to use " -"the :mod:`queue` module to create a queue object, let each thread append a " -"token to the queue when it finishes, and let the main thread read as many " -"tokens from the queue as there are threads." -msgstr "" -"與其嘗試為 :func:`time.sleep` 猜測一個好的延遲值，不如使用某種訊號量機制。一" -"種想法是使用 :mod:`queue` 模組建立一個隊列物件，讓每個執行緒在完成時向隊列新" -"增一個權杖，並讓主執行緒從隊列中讀取與執行緒數一樣多的權杖。" - -#: ../../faq/library.rst:290 -#, fuzzy -msgid "How do I parcel out work among a bunch of worker threads?" -msgstr "我如何在一堆工作執行緒中分配工作？" - -#: ../../faq/library.rst:292 -#, fuzzy -msgid "" -"The easiest way is to use the :mod:`concurrent.futures` module, especially " -"the :mod:`~concurrent.futures.ThreadPoolExecutor` class." -msgstr "" -"最簡單的方法是使用 :mod:`concurrent.futures` 模組，尤其" -"是 :mod:`~concurrent.futures.ThreadPoolExecutor` 類別。" - -#: ../../faq/library.rst:295 -#, fuzzy -msgid "" -"Or, if you want fine control over the dispatching algorithm, you can write " -"your own logic manually. Use the :mod:`queue` module to create a queue " -"containing a list of jobs. The :class:`~queue.Queue` class maintains a list " -"of objects and has a ``.put(obj)`` method that adds items to the queue and a " -"``.get()`` method to return them. The class will take care of the locking " -"necessary to ensure that each job is handed out exactly once." -msgstr "" -"或者，如果你想對調度演算法進行精細控制，你可以手動編寫自己的邏輯。使" -"用 :mod:`queue` 模組建立一個包含作業列表的隊列。 :class:`~queue.Queue` 類別維" -"護一個物件列表，並有一個 `.put(obj)`` 方法將項目新增到隊列和一個 ``.get()`` " -"方法回傳它們。該類別將負責必要的鎖定，以確保每個作業都恰好分發一次。" - -#: ../../faq/library.rst:302 -msgid "Here's a trivial example::" -msgstr "這是一個簡單的例子： ::" - -#: ../../faq/library.rst:304 -msgid "" -"import threading, queue, time\n" -"\n" -"# The worker thread gets jobs off the queue. When the queue is empty, it\n" -"# assumes there will be no more work and exits.\n" -"# (Realistically workers will run until terminated.)\n" -"def worker():\n" -" print('Running worker')\n" -" time.sleep(0.1)\n" -" while True:\n" -" try:\n" -" arg = q.get(block=False)\n" -" except queue.Empty:\n" -" print('Worker', threading.current_thread(), end=' ')\n" -" print('queue empty')\n" -" break\n" -" else:\n" -" print('Worker', threading.current_thread(), end=' ')\n" -" print('running with argument', arg)\n" -" time.sleep(0.5)\n" -"\n" -"# Create queue\n" -"q = queue.Queue()\n" -"\n" -"# Start a pool of 5 workers\n" -"for i in range(5):\n" -" t = threading.Thread(target=worker, name='worker %i' % (i+1))\n" -" t.start()\n" -"\n" -"# Begin adding work to the queue\n" -"for i in range(50):\n" -" q.put(i)\n" -"\n" -"# Give threads time to run\n" -"print('Main thread sleeping')\n" -"time.sleep(5)" -msgstr "" - -#: ../../faq/library.rst:340 -msgid "When run, this will produce the following output:" -msgstr "運行時，這將產生以下輸出：" - -#: ../../faq/library.rst:342 -msgid "" -"Running worker\n" -"Running worker\n" -"Running worker\n" -"Running worker\n" -"Running worker\n" -"Main thread sleeping\n" -"Worker running with argument 0\n" -"Worker running with argument 1\n" -"Worker running with argument 2\n" -"Worker running with argument 3\n" -"Worker running with argument 4\n" -"Worker running with argument 5\n" -"..." -msgstr "" -"Running worker\n" -"Running worker\n" -"Running worker\n" -"Running worker\n" -"Running worker\n" -"Main thread sleeping\n" -"Worker running with argument 0\n" -"Worker running with argument 1\n" -"Worker running with argument 2\n" -"Worker running with argument 3\n" -"Worker running with argument 4\n" -"Worker running with argument 5\n" -"..." - -#: ../../faq/library.rst:358 -#, fuzzy -msgid "" -"Consult the module's documentation for more details; " -"the :class:`~queue.Queue` class provides a featureful interface." -msgstr "" -"有關更多詳細資訊，請參閱模組的文件； :class:`~queue.Queue` 類別提供了一個功能" -"強大的介面。" - -#: ../../faq/library.rst:363 -msgid "What kinds of global value mutation are thread-safe?" -msgstr "什麼樣的全域值變化是執行緒安全的？" - -#: ../../faq/library.rst:365 -#, fuzzy -msgid "" -"A :term:`global interpreter lock` (GIL) is used internally to ensure that " -"only one thread runs in the Python VM at a time. In general, Python offers " -"to switch among threads only between bytecode instructions; how frequently " -"it switches can be set via :func:`sys.setswitchinterval`. Each bytecode " -"instruction and therefore all the C implementation code reached from each " -"instruction is therefore atomic from the point of view of a Python program." -msgstr "" -"內部使用 :term:`全域直譯器鎖 (GIL, global interpreter lock)`\\ 來確保一次只有" -"一個執行緒在 Python VM 中運行。通常，Python 僅提供位元組碼指令之間的執行緒切" -"換；可以透過 :func:`sys.setswitchinterval` 設定它切換的頻率。因此，從 Python " -"程式的角度來看，每條位元組碼指令以及從每條指令到達的所有 C 實作程式碼都是原子" -"的。" - -#: ../../faq/library.rst:372 -#, fuzzy -msgid "" -"In theory, this means an exact accounting requires an exact understanding of " -"the PVM bytecode implementation. In practice, it means that operations on " -"shared variables of built-in data types (ints, lists, dicts, etc) that " -"\"look atomic\" really are." -msgstr "" -"從理論上講，這意味著準確的記賬需要對 PVM 位元組碼實作有準確的理解。實際上，這" -"意味著對 \"看起來原子\" 的內置資料型別（整數、列表、字典等）的共享變數的操作" -"確實是原子的。" - -#: ../../faq/library.rst:377 -#, fuzzy -msgid "" -"For example, the following operations are all atomic (L, L1, L2 are lists, " -"D, D1, D2 are dicts, x, y are objects, i, j are ints)::" -msgstr "" -"例如，以下操作都是原子的（L、L1、L2 是列表，D、D1、D2 是字典，x、y 是物件，" -"i、j 是整數）： ::" - -#: ../../faq/library.rst:380 -msgid "" -"L.append(x)\n" -"L1.extend(L2)\n" -"x = L[i]\n" -"x = L.pop()\n" -"L1[i:j] = L2\n" -"L.sort()\n" -"x = y\n" -"x.field = y\n" -"D[x] = y\n" -"D1.update(D2)\n" -"D.keys()" -msgstr "" -"L.append(x)\n" -"L1.extend(L2)\n" -"x = L[i]\n" -"x = L.pop()\n" -"L1[i:j] = L2\n" -"L.sort()\n" -"x = y\n" -"x.field = y\n" -"D[x] = y\n" -"D1.update(D2)\n" -"D.keys()" - -#: ../../faq/library.rst:392 -msgid "These aren't::" -msgstr "這些不是： ::" - -#: ../../faq/library.rst:394 -msgid "" -"i = i+1\n" -"L.append(L[-1])\n" -"L[i] = L[j]\n" -"D[x] = D[x] + 1" -msgstr "" -"i = i+1\n" -"L.append(L[-1])\n" -"L[i] = L[j]\n" -"D[x] = D[x] + 1" - -#: ../../faq/library.rst:399 -#, fuzzy -msgid "" -"Operations that replace other objects may invoke those other " -"objects' :meth:`~object.__del__` method when their reference count reaches " -"zero, and that can affect things. This is especially true for the mass " -"updates to dictionaries and lists. When in doubt, use a mutex!" -msgstr "" -"替換其他物件的操作可能會在引用計數達到零時叫用其他物件的 :meth:`__del__` 方" -"法，這可能會影響事情。對於字典和列表的大量更新尤其如此。如有疑問，請使用互斥" -"體！" - -#: ../../faq/library.rst:406 -msgid "Can't we get rid of the Global Interpreter Lock?" -msgstr "不能擺脫全域直譯器鎖嗎？" - -#: ../../faq/library.rst:408 -#, fuzzy -msgid "" -"The :term:`global interpreter lock` (GIL) is often seen as a hindrance to " -"Python's deployment on high-end multiprocessor server machines, because a " -"multi-threaded Python program effectively only uses one CPU, due to the " -"insistence that (almost) all Python code can only run while the GIL is held." -msgstr "" -":term:`global interpreter lock` (GIL) 通常被視為 Python 在高階多處理器伺服器" -"機器上部署的障礙，因為多執行緒 Python 程式實際上只使用一個 CPU，因為堅持（幾" -"乎）所有 Python 程式碼只能在持有 GIL 的情況下運行。" - -#: ../../faq/library.rst:413 -msgid "" -"With the approval of :pep:`703` work is now underway to remove the GIL from " -"the CPython implementation of Python. Initially it will be implemented as " -"an optional compiler flag when building the interpreter, and so separate " -"builds will be available with and without the GIL. Long-term, the hope is " -"to settle on a single build, once the performance implications of removing " -"the GIL are fully understood. Python 3.13 is likely to be the first release " -"containing this work, although it may not be completely functional in this " -"release." -msgstr "" - -#: ../../faq/library.rst:422 -#, fuzzy -msgid "" -"The current work to remove the GIL is based on a `fork of Python 3.9 with " -"the GIL removed `_ by Sam Gross. Prior " -"to that, in the days of Python 1.5, Greg Stein actually implemented a " -"comprehensive patch set (the \"free threading\" patches) that removed the " -"GIL and replaced it with fine-grained locking. Adam Olsen did a similar " -"experiment in his `python-safethread `_ project. Unfortunately, both of these earlier " -"experiments exhibited a sharp drop in single-thread performance (at least " -"30% slower), due to the amount of fine-grained locking necessary to " -"compensate for the removal of the GIL. The Python 3.9 fork is the first " -"attempt at removing the GIL with an acceptable performance impact." -msgstr "" -"回到 Python 1.5 時代，Greg Stein 實際上實作了一個全面的補丁集（ \"自由執行緒" -"\" 補丁），刪除了 GIL 並用細粒度鎖定取而代之。 Adam Olsen 最近在他的 `python-" -"safethread `_ 項目中做了" -"一個類似的實驗。不幸的是，這兩個實驗都表現出單執行緒性能的急劇下降（至少慢了 " -"30%），這是由於需要大量的細粒度鎖定來補償 GIL 的移除。" - -#: ../../faq/library.rst:437 -#, fuzzy -msgid "" -"The presence of the GIL in current Python releases doesn't mean that you " -"can't make good use of Python on multi-CPU machines! You just have to be " -"creative with dividing the work up between multiple *processes* rather than " -"multiple *threads*. The :class:`~concurrent.futures.ProcessPoolExecutor` " -"class in the new :mod:`concurrent.futures` module provides an easy way of " -"doing so; the :mod:`multiprocessing` module provides a lower-level API in " -"case you want more control over dispatching of tasks." -msgstr "" -"這並不意味著你不能在多 CPU 機器上用好 Python！你只需要創造性地將工作分配給多" -"個*行程*而​​不是多個*執行緒*。新的 :mod:`concurrent.futures` 模組中" -"的 :class:`~concurrent.futures.ProcessPoolExecutor` 類別提供了一種簡單的方" -"法； :mod:`multiprocessing` 模組提供了一個較低階別的 API，以防你希望更好地控" -"制任務的調度。" - -#: ../../faq/library.rst:446 -#, fuzzy -msgid "" -"Judicious use of C extensions will also help; if you use a C extension to " -"perform a time-consuming task, the extension can release the GIL while the " -"thread of execution is in the C code and allow other threads to get some " -"work done. Some standard library modules such as :mod:`zlib` " -"and :mod:`hashlib` already do this." -msgstr "" -"明智地使用 C 擴充也會有所幫助；如果你使用 C 擴充來執行耗時任務，則該擴充可以" -"在執行執行緒在 C 程式碼中時釋放 GIL，並允許其他執行緒完成一些工作。一些標準函" -"式庫模組，例如 :mod:`zlib` 和 :mod:`hashlib` 已經這樣做了。" - -#: ../../faq/library.rst:452 -msgid "" -"An alternative approach to reducing the impact of the GIL is to make the GIL " -"a per-interpreter-state lock rather than truly global. This was :ref:`first " -"implemented in Python 3.12 ` and is available in the C " -"API. A Python interface to it is expected in Python 3.13. The main " -"limitation to it at the moment is likely to be 3rd party extension modules, " -"since these must be written with multiple interpreters in mind in order to " -"be usable, so many older extension modules will not be usable." -msgstr "" -"減少 GIL 影響的另一種方法是將 GIL 設置為直譯器各自狀態的鎖 (per-interpreter-" -"state lock)，而不是真正的全域鎖。這在 :ref:`Python 3.12 中首次實現 " -"`，並且可於 C API 中使用。預計 Python 3.13 將會提供其 " -"Python 介面。目前主要的限制可能是第三方擴充模組，因為實作時必須考慮到多個直譯" -"器才能使用，因此許多舊的擴充模組將無法使用。" - -#: ../../faq/library.rst:462 -msgid "Input and Output" -msgstr "輸入與輸出" - -#: ../../faq/library.rst:465 -msgid "How do I delete a file? (And other file questions...)" -msgstr "如何刪除檔案？（以及其他檔案問題...）" - -#: ../../faq/library.rst:467 -#, fuzzy -msgid "" -"Use ``os.remove(filename)`` or ``os.unlink(filename)``; for documentation, " -"see the :mod:`os` module. The two functions are " -"identical; :func:`~os.unlink` is simply the name of the Unix system call for " -"this function." -msgstr "" -"使用 ``os.remove(filename)`` 或 ``os.unlink(filename)``；有關文件，請參" -"閱 :mod:`os` 模組。這兩個功能是相同的； :func:`~os.unlink` 只是這個函式的 " -"Unix 系統呼叫的名稱。" - -#: ../../faq/library.rst:471 -#, fuzzy -msgid "" -"To remove a directory, use :func:`os.rmdir`; use :func:`os.mkdir` to create " -"one. ``os.makedirs(path)`` will create any intermediate directories in " -"``path`` that don't exist. ``os.removedirs(path)`` will remove intermediate " -"directories as long as they're empty; if you want to delete an entire " -"directory tree and its contents, use :func:`shutil.rmtree`." -msgstr "" -"要刪除目錄，請使用 :func:`os.rmdir`;使用 :func:`os.mkdir` 建立一個。 " -"``os.makedirs(path)`` 將在 ``path`` 中建立任何不存在的中間目錄。 " -"``os.removedirs(path)`` 將刪除中間目錄，只要它們是空的；如果要刪除整個目錄樹" -"及其內容，請使用 :func:`shutil.rmtree`。" - -#: ../../faq/library.rst:477 -msgid "To rename a file, use ``os.rename(old_path, new_path)``." -msgstr "要重新命名檔案，請使用 ``os.rename(old_path, new_path)``。" - -#: ../../faq/library.rst:479 -#, fuzzy -msgid "" -"To truncate a file, open it using ``f = open(filename, \"rb+\")``, and use " -"``f.truncate(offset)``; offset defaults to the current seek position. " -"There's also ``os.ftruncate(fd, offset)`` for files opened " -"with :func:`os.open`, where *fd* is the file descriptor (a small integer)." -msgstr "" -"要截斷一個檔案，使用``f = open(filename, \"rb+\")``打開它，然後使用" -"``f.truncate(offset)``；偏移量預設為目前搜尋位置。對於使用 :func:`os.open` 打" -"開的檔案，還有 ``os.ftruncate(fd, offset)``，其中 *fd* 是檔案描述器（一個小整" -"數）。" - -#: ../../faq/library.rst:484 -msgid "" -"The :mod:`shutil` module also contains a number of functions to work on " -"files including :func:`~shutil.copyfile`, :func:`~shutil.copytree`, " -"and :func:`~shutil.rmtree`." -msgstr "" -":mod:`shutil` 模組還包含許多用於檔案處理的函式，包" -"括 :func:`~shutil.copyfile`、:func:`~shutil.copytree` " -"和 :func:`~shutil.rmtree`。" - -#: ../../faq/library.rst:490 -msgid "How do I copy a file?" -msgstr "如何複製檔案？" - -#: ../../faq/library.rst:492 -#, fuzzy -msgid "" -"The :mod:`shutil` module contains a :func:`~shutil.copyfile` function. Note " -"that on Windows NTFS volumes, it does not copy `alternate data streams " -"`_ nor " -"`resource forks `__ on macOS " -"HFS+ volumes, though both are now rarely used. It also doesn't copy file " -"permissions and metadata, though using :func:`shutil.copy2` instead will " -"preserve most (though not all) of it." -msgstr "" -":mod:`shutil` 模組包含一個 :func:`~shutil.copyfile` 函式。請注意，在 Windows " -"NTFS 卷上，它不會複製 `alternate data streams `_ 也不會複製 `resource forks `__ 在 macOS HFS+ 卷上，儘管現在兩者都很" -"少使用。它也不會複製檔案權限和元資料，儘管使用 :func:`shutil.copy2` 會保留其" -"中的大部分（儘管不是全部）。" - -#: ../../faq/library.rst:503 -msgid "How do I read (or write) binary data?" -msgstr "如何讀取（或寫入）二進位制資料？" - -#: ../../faq/library.rst:505 -#, fuzzy -msgid "" -"To read or write complex binary data formats, it's best to use " -"the :mod:`struct` module. It allows you to take a string containing binary " -"data (usually numbers) and convert it to Python objects; and vice versa." -msgstr "" -"要讀取或寫入複雜的二進制資料格式，最好使用 :mod:`struct` 模組。它允許你取得包" -"含二進制資料（通常是數字）的字串並將其轉換為 Python 物件；反之亦然。" - -#: ../../faq/library.rst:509 -#, fuzzy -msgid "" -"For example, the following code reads two 2-byte integers and one 4-byte " -"integer in big-endian format from a file::" -msgstr "" -"例如，以下程式碼從一個檔案中以大端格式讀取兩個 2 位元組整數和一個 4 位元組整" -"數： ::" - -#: ../../faq/library.rst:512 -msgid "" -"import struct\n" -"\n" -"with open(filename, \"rb\") as f:\n" -" s = f.read(8)\n" -" x, y, z = struct.unpack(\">hhl\", s)" -msgstr "" -"import struct\n" -"\n" -"with open(filename, \"rb\") as f:\n" -" s = f.read(8)\n" -" x, y, z = struct.unpack(\">hhl\", s)" - -#: ../../faq/library.rst:518 -#, fuzzy -msgid "" -"The '>' in the format string forces big-endian data; the letter 'h' reads " -"one \"short integer\" (2 bytes), and 'l' reads one \"long integer\" (4 " -"bytes) from the string." -msgstr "" -"格式字串中的 \">\" 強制使用大端資料；字母 'h' 讀取一個 \"短整數\" （2 位元" -"組）， 'l' 從字串中讀取一個 \"長整數\" （4 位元組）。" - -#: ../../faq/library.rst:522 -#, fuzzy -msgid "" -"For data that is more regular (e.g. a homogeneous list of ints or floats), " -"you can also use the :mod:`array` module." -msgstr "" -"對於更規則的資料（例如，整數或浮點數的同類列表），你還可以使用 :mod:`array` " -"模組。" - -#: ../../faq/library.rst:527 -#, fuzzy -msgid "" -"To read and write binary data, it is mandatory to open the file in binary " -"mode (here, passing ``\"rb\"`` to :func:`open`). If you use ``\"r\"`` " -"instead (the default), the file will be open in text mode and ``f.read()`` " -"will return :class:`str` objects rather than :class:`bytes` objects." -msgstr "" -"要讀取和寫入二進位資料，必須以二進位模式打開檔案（這裡，將 ``\"rb\"`` 傳遞" -"給 :func:`open`）。如果你改用 ``\"r\"``\\ （預設設定），檔案將以文本模式打開，並" -"且 ``f.read()`` 將回傳 :class:`str` 物件而不是 :class:`bytes` 物件。" - -#: ../../faq/library.rst:535 -msgid "I can't seem to use os.read() on a pipe created with os.popen(); why?" -msgstr "我似乎無法在用 os.popen() 建立的 pipe 上使用 os.read()；為什麼？" - -#: ../../faq/library.rst:537 -#, fuzzy -msgid "" -":func:`os.read` is a low-level function which takes a file descriptor, a " -"small integer representing the opened file. :func:`os.popen` creates a high-" -"level file object, the same type returned by the built-in :func:`open` " -"function. Thus, to read *n* bytes from a pipe *p* created " -"with :func:`os.popen`, you need to use ``p.read(n)``." -msgstr "" -":func:`os.read` 是一個低階函式，它接受一個檔案描述器，一個代表打開檔案的小整" -"數。 :func:`os.popen` 建立一個高階檔案物件，與內置的 :func:`open` 函式回傳的" -"型別相同。因此，要從使用 :func:`os.popen` 建立的管道 *p* 中讀取 *n* 個位元" -"組，你需要使用 ``p.read(n)``。" - -#: ../../faq/library.rst:545 -msgid "How do I access the serial (RS232) port?" -msgstr "如何存取序列 (RS232) 連接埠？" - -#: ../../faq/library.rst:547 -msgid "For Win32, OSX, Linux, BSD, Jython, IronPython:" -msgstr "對於 Win32、OSX、Linux、BSD、Jython、IronPython：" - -#: ../../faq/library.rst:549 -msgid ":pypi:`pyserial`" -msgstr ":pypi:`pyserial`" - -#: ../../faq/library.rst:551 -msgid "For Unix, see a Usenet post by Mitch Chapman:" -msgstr "對於 Unix，請參閱 Mitch Chapman 的 Usenet 貼文：" - -#: ../../faq/library.rst:553 -msgid "https://groups.google.com/groups?selm=34A04430.CF9@ohioee.com" -msgstr "https://groups.google.com/groups?selm=34A04430.CF9@ohioee.com" - -#: ../../faq/library.rst:557 -msgid "Why doesn't closing sys.stdout (stdin, stderr) really close it?" -msgstr "為什麼關閉 sys.stdout (stdin, stderr) 並沒有真正關閉它？" - -#: ../../faq/library.rst:559 -msgid "" -"Python :term:`file objects ` are a high-level layer of " -"abstraction on low-level C file descriptors." -msgstr "" -"Python :term:`檔案物件 `\\ 是低階 C 檔案描述器的高階抽象層。" - -#: ../../faq/library.rst:562 -#, fuzzy -msgid "" -"For most file objects you create in Python via the built-in :func:`open` " -"function, ``f.close()`` marks the Python file object as being closed from " -"Python's point of view, and also arranges to close the underlying C file " -"descriptor. This also happens automatically in ``f``'s destructor, when " -"``f`` becomes garbage." -msgstr "" -"對於你透過內置的 :func:`open` 函式在 Python 中建立的大多數檔案物件，" -"``f.close()`` 從 Python 的角度將 Python 檔案物件標記為已關閉，並安排關閉底層 " -"C 檔案描述器。當 ``f`` 變成垃圾時，這也會自動發生在 ``f`` 的析構函式中。" - -#: ../../faq/library.rst:568 -#, fuzzy -msgid "" -"But stdin, stdout and stderr are treated specially by Python, because of the " -"special status also given to them by C. Running ``sys.stdout.close()`` " -"marks the Python-level file object as being closed, but does *not* close the " -"associated C file descriptor." -msgstr "" -"但是 stdin、stdout 和 stderr 被 Python 特殊對待，因為 C 也賦予它們特殊的狀" -"態。運行 ``sys.stdout.close()`` 將 Python 級檔案物件標記為已關閉，但是 * " -"not* 關閉關聯的 C 檔案描述器。" - -#: ../../faq/library.rst:573 -#, fuzzy -msgid "" -"To close the underlying C file descriptor for one of these three, you should " -"first be sure that's what you really want to do (e.g., you may confuse " -"extension modules trying to do I/O). If it is, use :func:`os.close`::" -msgstr "" -"要關閉這三個之一的底層 C 檔案描述器，你應該首先確定這是你真正想要做的（例如，" -"你可能會混淆試圖執行 I/O 的擴充模組）。如果是，使用 :func:`os.close`： ::" - -#: ../../faq/library.rst:577 -msgid "" -"os.close(stdin.fileno())\n" -"os.close(stdout.fileno())\n" -"os.close(stderr.fileno())" -msgstr "" -"os.close(stdin.fileno())\n" -"os.close(stdout.fileno())\n" -"os.close(stderr.fileno())" - -#: ../../faq/library.rst:581 -msgid "Or you can use the numeric constants 0, 1 and 2, respectively." -msgstr "或者你可以分別使用數字常數 0、1 和 2。" - -#: ../../faq/library.rst:585 -msgid "Network/Internet Programming" -msgstr "網路 (Network)/網際網路 (Internet) 程式" - -#: ../../faq/library.rst:588 -msgid "What WWW tools are there for Python?" -msgstr "Python 有哪些 WWW 工具？" - -#: ../../faq/library.rst:590 -#, fuzzy -msgid "" -"See the chapters titled :ref:`internet` and :ref:`netdata` in the Library " -"Reference Manual. Python has many modules that will help you build server-" -"side and client-side web systems." -msgstr "" -"請參閱函式庫參考手冊中標題為 :ref:`internet` 和 :ref:`netdata` 的章節。 " -"Python 有許多模組可以幫助你構建伺服器端和用戶端 Web 系統。" - -#: ../../faq/library.rst:596 -msgid "" -"A summary of available frameworks is maintained by Paul Boddie at https://" -"wiki.python.org/moin/WebProgramming\\ ." -msgstr "" -"Paul Boddie 有在 https://wiki.python.org/moin/" -"WebProgramming\\ 維護可用框架的摘要。" - -#: ../../faq/library.rst:601 -msgid "What module should I use to help with generating HTML?" -msgstr "我應該使用什麼模組來輔助產生 HTML？" - -#: ../../faq/library.rst:605 -msgid "" -"You can find a collection of useful links on the `Web Programming wiki page " -"`_." -msgstr "" -"你可以在 \"網頁程式維基頁面 \" 上找到一組有用的鏈接。" - -#: ../../faq/library.rst:610 -msgid "How do I send mail from a Python script?" -msgstr "如何從 Python 腳本發送郵件？" - -#: ../../faq/library.rst:612 -msgid "Use the standard library module :mod:`smtplib`." -msgstr "使用標準函式庫模組 :mod:`smtplib`。" - -#: ../../faq/library.rst:614 -#, fuzzy -msgid "" -"Here's a very simple interactive mail sender that uses it. This method will " -"work on any host that supports an SMTP listener. ::" -msgstr "" -"這是一個使用它的非常簡單的交互式郵件發件人。此方法適用於任何支援 SMTP 偵聽器" -"的主機。： ::" - -#: ../../faq/library.rst:617 -msgid "" -"import sys, smtplib\n" -"\n" -"fromaddr = input(\"From: \")\n" -"toaddrs = input(\"To: \").split(',')\n" -"print(\"Enter message, end with ^D:\")\n" -"msg = ''\n" -"while True:\n" -" line = sys.stdin.readline()\n" -" if not line:\n" -" break\n" -" msg += line\n" -"\n" -"# The actual mail send\n" -"server = smtplib.SMTP('localhost')\n" -"server.sendmail(fromaddr, toaddrs, msg)\n" -"server.quit()" -msgstr "" -"import sys, smtplib\n" -"\n" -"fromaddr = input(\"From: \")\n" -"toaddrs = input(\"To: \").split(',')\n" -"print(\"Enter message, end with ^D:\")\n" -"msg = ''\n" -"while True:\n" -" line = sys.stdin.readline()\n" -" if not line:\n" -" break\n" -" msg += line\n" -"\n" -"# The actual mail send\n" -"server = smtplib.SMTP('localhost')\n" -"server.sendmail(fromaddr, toaddrs, msg)\n" -"server.quit()" - -#: ../../faq/library.rst:634 -msgid "" -"A Unix-only alternative uses sendmail. The location of the sendmail program " -"varies between systems; sometimes it is ``/usr/lib/sendmail``, sometimes ``/" -"usr/sbin/sendmail``. The sendmail manual page will help you out. Here's " -"some sample code::" -msgstr "" -"使用 sendmail 是僅適用於 Unix 的替代方案。sendmail 程式的位置會因系統而異；有" -"時是 ``/usr/lib/sendmail``，有時是 ``/usr/sbin/sendmail``。sendmail 使用手冊" -"將能夠幫助你。這是一些範例程式碼： ::" - -#: ../../faq/library.rst:639 -msgid "" -"import os\n" -"\n" -"SENDMAIL = \"/usr/sbin/sendmail\" # sendmail location\n" -"p = os.popen(\"%s -t -i\" % SENDMAIL, \"w\")\n" -"p.write(\"To: receiver@example.com\\n\")\n" -"p.write(\"Subject: test\\n\")\n" -"p.write(\"\\n\") # blank line separating headers from body\n" -"p.write(\"Some text\\n\")\n" -"p.write(\"some more text\\n\")\n" -"sts = p.close()\n" -"if sts != 0:\n" -" print(\"Sendmail exit status\", sts)" -msgstr "" - -#: ../../faq/library.rst:654 -msgid "How do I avoid blocking in the connect() method of a socket?" -msgstr "如何避免阻塞 socket 的 connect() 方法？" - -#: ../../faq/library.rst:656 -msgid "" -"The :mod:`select` module is commonly used to help with asynchronous I/O on " -"sockets." -msgstr ":mod:`select` 模組通常用於幫助處理 socket 上的非同步 I/O。" - -#: ../../faq/library.rst:659 -#, fuzzy -msgid "" -"To prevent the TCP connect from blocking, you can set the socket to non-" -"blocking mode. Then when you do the :meth:`~socket.socket.connect`, you " -"will either connect immediately (unlikely) or get an exception that contains " -"the error number as ``.errno``. ``errno.EINPROGRESS`` indicates that the " -"connection is in progress, but hasn't finished yet. Different OSes will " -"return different values, so you're going to have to check what's returned on " -"your system." -msgstr "" -"為防止 TCP 連接阻塞，可以將 socket 設定為非阻塞模式。然後當你執" -"行 :meth:`socket.connect` 時，你要麼立即連接（不太可能），要麼得到一個例外，" -"其中包含錯誤號 ``.errno``。 ``errno.EINPROGRESS`` 表示連接正在進行中，但尚未" -"完成。不同的作業系統將回傳不同的值，因此你將不得不檢查系統回傳的內容。" - -#: ../../faq/library.rst:667 -#, fuzzy -msgid "" -"You can use the :meth:`~socket.socket.connect_ex` method to avoid creating " -"an exception. It will just return the errno value. To poll, you can " -"call :meth:`~socket.socket.connect_ex` again later -- ``0`` or " -"``errno.EISCONN`` indicate that you're connected -- or you can pass this " -"socket to :meth:`select.select` to check if it's writable." -msgstr "" -"你可以使用 :meth:`socket.connect_ex` 方法來避免建立例外。它只會回傳 errno " -"值。要輪詢，你可以稍後再次呼叫 :meth:`socket.connect_ex` - ``0`` 或 " -"``errno.EISCONN`` 表示你已連接 - 或者你可以將此 socket 傳遞" -"給 :meth:`select.select` 檢查它是否可寫。" - -#: ../../faq/library.rst:675 -msgid "" -"The :mod:`asyncio` module provides a general purpose single-threaded and " -"concurrent asynchronous library, which can be used for writing non-blocking " -"network code. The third-party `Twisted `_ library is a " -"popular and feature-rich alternative." -msgstr "" -":mod:`asyncio` 模組提供了一個通用的單執行緒並發非同步函式庫，可用於編寫非阻塞" -"網路程式碼。第三方 `Twisted `_ 函式庫是一種流行且功能豐" -"富的替代方案。" - -#: ../../faq/library.rst:683 -msgid "Databases" -msgstr "資料庫" - -#: ../../faq/library.rst:686 -msgid "Are there any interfaces to database packages in Python?" -msgstr "Python 中是否有任何資料庫套件的介面？" - -#: ../../faq/library.rst:688 -msgid "Yes." -msgstr "有的。" - -#: ../../faq/library.rst:690 -#, fuzzy -msgid "" -"Interfaces to disk-based hashes such as :mod:`DBM ` and :mod:`GDBM " -"` are also included with standard Python. There is also " -"the :mod:`sqlite3` module, which provides a lightweight disk-based " -"relational database." -msgstr "" -"基於磁碟的雜湊介面，例如 :mod:`DBM ` 和 :mod:`GDBM ` 也包" -"含在標準 Python 中。還有 :mod:`sqlite3` 模組，它提供了一個輕量級的基於磁碟的" -"關係資料庫。" - -#: ../../faq/library.rst:695 -#, fuzzy -msgid "" -"Support for most relational databases is available. See the " -"`DatabaseProgramming wiki page `_ for details." -msgstr "" -"支援大多數關係資料庫。有關詳細資訊，請參閱 `DatabaseProgramming 維基頁面 " -"`_。" - -#: ../../faq/library.rst:701 -msgid "How do you implement persistent objects in Python?" -msgstr "你如何在 Python 中實作持久性物件？" - -#: ../../faq/library.rst:703 -#, fuzzy -msgid "" -"The :mod:`pickle` library module solves this in a very general way (though " -"you still can't store things like open files, sockets or windows), and " -"the :mod:`shelve` library module uses pickle and (g)dbm to create persistent " -"mappings containing arbitrary Python objects." -msgstr "" -":mod:`pickle` 函式庫模組以一種非常通用的方式解決了這個問題（儘管你仍然不能存" -"儲諸如打開的檔案、socket 或窗口之類的東西），而 :mod:`shelve` 函式庫模組使用 " -"pickle 和 (g) dbm 建立包含任意 Python 物件的持久對映。" - -#: ../../faq/library.rst:710 -msgid "Mathematics and Numerics" -msgstr "數學和數值" - -#: ../../faq/library.rst:713 -msgid "How do I generate random numbers in Python?" -msgstr "如何在 Python 中生成隨機數？" - -#: ../../faq/library.rst:715 -msgid "" -"The standard module :mod:`random` implements a random number generator. " -"Usage is simple::" -msgstr "標準模組 :mod:`random` 實作了一個隨機數生成器。用法很簡單： ::" - -#: ../../faq/library.rst:718 -msgid "" -"import random\n" -"random.random()" -msgstr "" -"import random\n" -"random.random()" - -#: ../../faq/library.rst:721 -msgid "This returns a random floating-point number in the range [0, 1)." -msgstr "這將回傳 [0, 1) 範圍內的隨機浮點數。" - -#: ../../faq/library.rst:723 -msgid "" -"There are also many other specialized generators in this module, such as:" -msgstr "該模組中還有許多其他專用生成器，例如：" - -#: ../../faq/library.rst:725 -msgid "``randrange(a, b)`` chooses an integer in the range [a, b)." -msgstr "``randrange(a, b)`` 會選擇 [a, b) 範圍內的一個整數。" - -#: ../../faq/library.rst:726 -msgid "``uniform(a, b)`` chooses a floating-point number in the range [a, b)." -msgstr "``uniform(a, b)`` 會選擇 [a, b) 範圍內的浮點數。" - -#: ../../faq/library.rst:727 -msgid "" -"``normalvariate(mean, sdev)`` samples the normal (Gaussian) distribution." -msgstr "``normalvariate(mean, sdev)`` 對常態（高斯）分佈進行取樣 (sample)。" - -#: ../../faq/library.rst:729 -msgid "Some higher-level functions operate on sequences directly, such as:" -msgstr "一些更高階的函式會直接對序列進行操作，例如：" - -#: ../../faq/library.rst:731 -msgid "``choice(S)`` chooses a random element from a given sequence." -msgstr "``choice(S)`` 會從給定序列中選擇一個隨機元素。" - -#: ../../faq/library.rst:732 -msgid "``shuffle(L)`` shuffles a list in-place, i.e. permutes it randomly." -msgstr "``shuffle(L)`` 會原地 (in-place) 打亂 list，即隨機排列它。" - -#: ../../faq/library.rst:734 -msgid "" -"There's also a ``Random`` class you can instantiate to create independent " -"multiple random number generators." -msgstr "" -"還有一個 ``Random`` 類別，你可以將它實例化以建立多個獨立的隨機數生成器。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# jerrychen , 2016 +# Ching-Lung Chuang, 2015 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: 2023-02-18 13:22+0800\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" +"X-Generator: Poedit 3.2.2\n" + +#: ../../faq/library.rst:5 +msgid "Library and Extension FAQ" +msgstr "函式庫和擴充功能的常見問題" + +#: ../../faq/library.rst:8 +msgid "Contents" +msgstr "目錄" + +#: ../../faq/library.rst:12 +msgid "General Library Questions" +msgstr "常見函式問題" + +#: ../../faq/library.rst:15 +msgid "How do I find a module or application to perform task X?" +msgstr "我如何找到執行任務 X 的模組或應用程式？" + +#: ../../faq/library.rst:17 +msgid "" +"Check :ref:`the Library Reference ` to see if there's a " +"relevant standard library module. (Eventually you'll learn what's in the " +"standard library and will be able to skip this step.)" +msgstr "" +"查看\\ :ref:`函式庫參照 `\\ 以了解是否有相關的標準函式庫模組。 " +"（當你熟悉標準函式庫中的內容後就可以能跳過這一步。）" + +#: ../../faq/library.rst:21 +msgid "" +"For third-party packages, search the `Python Package Index `_ or try `Google `_ or another web search " +"engine. Searching for \"Python\" plus a keyword or two for your topic of " +"interest will usually find something helpful." +msgstr "" +"對於第三方套件，搜尋 `Python 套件索引 `_\\ 或嘗試使用 `Google " +"`_ 或其他網路搜尋引擎。搜尋 \"Python\" 加上你感興趣主題的一" +"兩個關鍵字，通常能夠找到有用的東西。" + +#: ../../faq/library.rst:28 +msgid "Where is the math.py (socket.py, regex.py, etc.) source file?" +msgstr "哪裡可以找到 math.py (socket.py, regex.py, 等...) 來源檔案？" + +#: ../../faq/library.rst:30 +#, fuzzy +msgid "" +"If you can't find a source file for a module it may be a built-in or " +"dynamically loaded module implemented in C, C++ or other compiled language. " +"In this case you may not have the source file or it may be something " +"like :file:`mathmodule.c`, somewhere in a C source directory (not on the " +"Python Path)." +msgstr "" +"如果找不到模組的源檔案，它可能是用 C、C++ 或其他編譯語言實作的內置或動態載入" +"的模組。在這種情況下，你可能沒有源檔案，或者它可能類似" +"於 :file:`mathmodule.c`，位於 C 源目錄中（不在 Python 路徑中）。" + +#: ../../faq/library.rst:35 +msgid "There are (at least) three kinds of modules in Python:" +msgstr "有（至少）三種 Python 模組：" + +#: ../../faq/library.rst:37 +msgid "modules written in Python (.py);" +msgstr "以 Python 編寫的模組 (.py)；" + +#: ../../faq/library.rst:38 +msgid "" +"modules written in C and dynamically loaded (.dll, .pyd, .so, .sl, etc);" +msgstr "用 C 編寫並動態載入的模組（.dll、.pyd、.so、.sl 等）；" + +#: ../../faq/library.rst:39 +msgid "" +"modules written in C and linked with the interpreter; to get a list of " +"these, type::" +msgstr "用 C 編寫並與直譯器鏈接的模組；要獲得這些 list，請輸入： ::" + +#: ../../faq/library.rst:42 +msgid "" +"import sys\n" +"print(sys.builtin_module_names)" +msgstr "" +"import sys\n" +"print(sys.builtin_module_names)" + +#: ../../faq/library.rst:47 +msgid "How do I make a Python script executable on Unix?" +msgstr "我如何使 Python script 執行在 Unix？" + +#: ../../faq/library.rst:49 +#, fuzzy +msgid "" +"You need to do two things: the script file's mode must be executable and the " +"first line must begin with ``#!`` followed by the path of the Python " +"interpreter." +msgstr "" +"你需要作兩件事：腳本程式必須可以被執行而且第一行必須 ``#!`` 開頭後面接上 " +"Python 直譯器的路徑。" + +#: ../../faq/library.rst:53 +msgid "" +"The first is done by executing ``chmod +x scriptfile`` or perhaps ``chmod " +"755 scriptfile``." +msgstr "" +"第一個是透過執行 ``chmod +x scriptfile`` 或者可能是 ``chmod 755 scriptfile`` " +"來完成的。" + +#: ../../faq/library.rst:56 +msgid "" +"The second can be done in a number of ways. The most straightforward way is " +"to write ::" +msgstr "第二個則可以透過多種方式完成。最直接的方法是寫： ::" + +#: ../../faq/library.rst:59 +msgid "#!/usr/local/bin/python" +msgstr "#!/usr/local/bin/python" + +#: ../../faq/library.rst:61 +msgid "" +"as the very first line of your file, using the pathname for where the Python " +"interpreter is installed on your platform." +msgstr "作為檔案的第一行，使用 Python 直譯器安裝在你的平台上的路徑名稱。" + +#: ../../faq/library.rst:64 +#, fuzzy +msgid "" +"If you would like the script to be independent of where the Python " +"interpreter lives, you can use the :program:`env` program. Almost all Unix " +"variants support the following, assuming the Python interpreter is in a " +"directory on the user's :envvar:`PATH`::" +msgstr "" +"如果你希望腳本獨立於 Python 直譯器所在的位置，你可以使用 :program:`env` 程" +"式。幾乎所有 Unix 變體都支援以下內容，假設 Python 直譯器位於使用者" +"的 :envvar:`PATH` 上的目錄中： ::" + +#: ../../faq/library.rst:69 +msgid "#!/usr/bin/env python" +msgstr "#!/usr/bin/env python" + +#: ../../faq/library.rst:71 +msgid "" +"*Don't* do this for CGI scripts. The :envvar:`PATH` variable for CGI " +"scripts is often very minimal, so you need to use the actual absolute " +"pathname of the interpreter." +msgstr "" +"*不要*\\ 對 CGI 腳本執行此操作。CGI 腳本的 :envvar:`PATH` 變數通常非常小，因" +"此你需要使用直譯器的實際絕對路徑名稱。" + +#: ../../faq/library.rst:75 +#, fuzzy +msgid "" +"Occasionally, a user's environment is so full that the :program:`/usr/bin/" +"env` program fails; or there's no env program at all. In that case, you can " +"try the following hack (due to Alex Rezinsky):" +msgstr "" +"有時，使用者的環境太滿以至於:program:`/usr/bin/env` 程式失敗；或者根本就沒有 " +"env 程式。在這種情況下，你可以嘗試以下 hack（由於 Alex Rezinsky）：" + +#: ../../faq/library.rst:79 +msgid "" +"#! /bin/sh\n" +"\"\"\":\"\n" +"exec python $0 ${1+\"$@\"}\n" +"\"\"\"" +msgstr "" +"#! /bin/sh\n" +"\"\"\":\"\n" +"exec python $0 ${1+\"$@\"}\n" +"\"\"\"" + +#: ../../faq/library.rst:86 +msgid "" +"The minor disadvantage is that this defines the script's __doc__ string. " +"However, you can fix that by adding ::" +msgstr "" +"次要缺點是這定義了腳本的 __doc__ 字串。但是你可以透過新增下面這一行來解決這個" +"問題： ::" + +#: ../../faq/library.rst:89 +msgid "__doc__ = \"\"\"...Whatever...\"\"\"" +msgstr "__doc__ = \"\"\"...Whatever...\"\"\"" + +#: ../../faq/library.rst:94 +msgid "Is there a curses/termcap package for Python?" +msgstr "是否有適用於 Python 的 curses/termcap 套件？" + +#: ../../faq/library.rst:98 +#, fuzzy +msgid "" +"For Unix variants: The standard Python source distribution comes with a " +"curses module in the :source:`Modules` subdirectory, though it's not " +"compiled by default. (Note that this is not available in the Windows " +"distribution -- there is no curses module for Windows.)" +msgstr "" +"對於 Unix 變體：標準 Python 源程式碼分發版在 :source:`Modules` 子目錄中附帶一" +"個 curses 模組，但預設情況下未編譯它。（請注意，這在 Windows 發行版中不可用——" +"沒有適用於 Windows 的 curses 模組。）" + +#: ../../faq/library.rst:103 +#, fuzzy +msgid "" +"The :mod:`curses` module supports basic curses features as well as many " +"additional functions from ncurses and SYSV curses such as colour, " +"alternative character set support, pads, and mouse support. This means the " +"module isn't compatible with operating systems that only have BSD curses, " +"but there don't seem to be any currently maintained OSes that fall into this " +"category." +msgstr "" +":mod:`curses` 模組支援基本的 curses 功能以及 ncurses 和 SYSV curses 的許多附" +"加功能，例如顏色、替代字元集支援、鍵盤和鼠標支援。這意味著該模組與僅具有 BSD " +"curses 的作業系統不相容，但似乎沒有任何目前維護的作業系統屬於此類型。" + +#: ../../faq/library.rst:111 +msgid "Is there an equivalent to C's onexit() in Python?" +msgstr "Python 中是否有等同於 C 的 onexit() 的函式？" + +#: ../../faq/library.rst:113 +msgid "" +"The :mod:`atexit` module provides a register function that is similar to " +"C's :c:func:`!onexit`." +msgstr ":mod:`atexit` 模組提供了一個類似於 C :c:func:`!onexit` 的註冊函式。" + +#: ../../faq/library.rst:118 +msgid "Why don't my signal handlers work?" +msgstr "為什麼我的訊號處理程式不起作用？" + +#: ../../faq/library.rst:120 +msgid "" +"The most common problem is that the signal handler is declared with the " +"wrong argument list. It is called as ::" +msgstr "最常見的問題是訊號處理程式是用錯誤的引數串列聲明的。它以以下形式來呼叫： ::" + +#: ../../faq/library.rst:123 +msgid "handler(signum, frame)" +msgstr "handler(signum, frame)" + +#: ../../faq/library.rst:125 +msgid "so it should be declared with two parameters::" +msgstr "所以它應該用兩個參數聲明： ::" + +#: ../../faq/library.rst:127 +msgid "" +"def handler(signum, frame):\n" +" ..." +msgstr "" +"def handler(signum, frame):\n" +" ..." + +#: ../../faq/library.rst:132 +msgid "Common tasks" +msgstr "常見課題" + +#: ../../faq/library.rst:135 +msgid "How do I test a Python program or component?" +msgstr "如何測試 Python 程式或元件？" + +#: ../../faq/library.rst:137 +#, fuzzy +msgid "" +"Python comes with two testing frameworks. The :mod:`doctest` module finds " +"examples in the docstrings for a module and runs them, comparing the output " +"with the expected output given in the docstring." +msgstr "" +"Python 帶有兩個測試框架。 :mod:`doctest` 模組在模組的文件字串中查詢示例並運行" +"它們，將輸出與文件字串中給出的預期輸出進行比較。" + +#: ../../faq/library.rst:141 +msgid "" +"The :mod:`unittest` module is a fancier testing framework modelled on Java " +"and Smalltalk testing frameworks." +msgstr "" +":mod:`unittest` 模組是一個更炫目的測試框架，它以 Java 和 Smalltalk 測試框架為" +"模型。" + +#: ../../faq/library.rst:144 +#, fuzzy +msgid "" +"To make testing easier, you should use good modular design in your program. " +"Your program should have almost all functionality encapsulated in either " +"functions or class methods -- and this sometimes has the surprising and " +"delightful effect of making the program run faster (because local variable " +"accesses are faster than global accesses). Furthermore the program should " +"avoid depending on mutating global variables, since this makes testing much " +"more difficult to do." +msgstr "" +"為了使測試更容易，你應該在程式中使用良好的模組化設計。你的程式應該將幾乎所有" +"功能都封裝在函式或類別方法中——這有時會產生使程式運行得更快的令人驚訝和令人愉" +"快的效果（因為局部變數存取比全域存取更快）。此外，該程式應避免依賴於可變的全" +"局變數，因為這會使測試變得更加困難。" + +#: ../../faq/library.rst:152 +#, fuzzy +msgid "The \"global main logic\" of your program may be as simple as ::" +msgstr "你程式的「全域主邏輯」可能像一樣簡單： ::" + +#: ../../faq/library.rst:154 +msgid "" +"if __name__ == \"__main__\":\n" +" main_logic()" +msgstr "" +"if __name__ == \"__main__\":\n" +" main_logic()" + +#: ../../faq/library.rst:157 +#, fuzzy +msgid "at the bottom of the main module of your program." +msgstr "在你的程式主模組的底端。" + +#: ../../faq/library.rst:159 +#, fuzzy +msgid "" +"Once your program is organized as a tractable collection of function and " +"class behaviours, you should write test functions that exercise the " +"behaviours. A test suite that automates a sequence of tests can be " +"associated with each module. This sounds like a lot of work, but since " +"Python is so terse and flexible it's surprisingly easy. You can make coding " +"much more pleasant and fun by writing your test functions in parallel with " +"the \"production code\", since this makes it easy to find bugs and even " +"design flaws earlier." +msgstr "" +"一旦你的程式被組織為函式和類別行為的易於處理的集合，你就應該編寫測試函式來執" +"行這些行為。可將一系列測試自動化的測試套件與每個模組相關聯。這聽起來像是很多" +"工作，但由於 Python 如此簡潔和靈活，所以它非常容易。透過與 \"生產程式碼\" 並" +"行編寫測試函式，你可以使編碼變得更加愉快和有趣，因為這使得更早地發現錯誤甚至" +"設計缺陷變得容易。" + +#: ../../faq/library.rst:167 +#, fuzzy +msgid "" +"\"Support modules\" that are not intended to be the main module of a program " +"may include a self-test of the module. ::" +msgstr "不打算成為程式主要模組的 \"支援模組\" 可能包括模組的自檢： ::" + +#: ../../faq/library.rst:170 +msgid "" +"if __name__ == \"__main__\":\n" +" self_test()" +msgstr "" +"if __name__ == \"__main__\":\n" +" self_test()" + +#: ../../faq/library.rst:173 +#, fuzzy +msgid "" +"Even programs that interact with complex external interfaces may be tested " +"when the external interfaces are unavailable by using \"fake\" interfaces " +"implemented in Python." +msgstr "" +"即使是與復雜外部介面交互的程式也可以在外部介面不可用時透過使用 Python 中實作" +"的 \"假\" 介面進行測試。" + +#: ../../faq/library.rst:179 +msgid "How do I create documentation from doc strings?" +msgstr "如何從文件字串建立文件？" + +#: ../../faq/library.rst:181 +#, fuzzy +msgid "" +"The :mod:`pydoc` module can create HTML from the doc strings in your Python " +"source code. An alternative for creating API documentation purely from " +"docstrings is `epydoc `_. `Sphinx `_ can also include docstring content." +msgstr "" +":mod:`pydoc` 模組可以從 Python 源程式碼中的文件字串建立 HTML。純粹從文件字串" +"建立 API 文件的另一種方法是 `epydoc `_。 " +"`Sphinx `_ 也可以包含文件字串內容。" + +#: ../../faq/library.rst:188 +#, fuzzy +msgid "How do I get a single keypress at a time?" +msgstr "我如何一次獲得一個按鍵？" + +#: ../../faq/library.rst:190 +msgid "" +"For Unix variants there are several solutions. It's straightforward to do " +"this using curses, but curses is a fairly large module to learn." +msgstr "" +"對於 Unix 變體有幾種解決方案。使用 curses 執行此操作很直觀，但 curses 是一" +"個學習成本較大的模組。" + +#: ../../faq/library.rst:234 +msgid "Threads" +msgstr "執行緒" + +#: ../../faq/library.rst:237 +msgid "How do I program using threads?" +msgstr "如何使用執行緒編寫程式？" + +#: ../../faq/library.rst:239 +#, fuzzy +msgid "" +"Be sure to use the :mod:`threading` module and not the :mod:`_thread` " +"module. The :mod:`threading` module builds convenient abstractions on top of " +"the low-level primitives provided by the :mod:`_thread` module." +msgstr "" +"請務必使用 :mod:`threading` 模組而不是 :mod:`_thread` 模" +"組。 :mod:`threading` 模組在 :mod:`_thread` 模組提供的低階原語之上構建方便的" +"抽象。" + +#: ../../faq/library.rst:245 +msgid "None of my threads seem to run: why?" +msgstr "我的執行緒似乎都沒有運行：為什麼？" + +#: ../../faq/library.rst:247 +#, fuzzy +msgid "" +"As soon as the main thread exits, all threads are killed. Your main thread " +"is running too quickly, giving the threads no time to do any work." +msgstr "" +"一旦主執行緒退出，所有執行緒都會被殺死。你的主執行緒運行得太快，執行緒沒有時" +"間做任何工作。" + +#: ../../faq/library.rst:250 +msgid "" +"A simple fix is to add a sleep to the end of the program that's long enough " +"for all the threads to finish::" +msgstr "" +"一個簡單的修復方式是在程式末尾新增一個足夠長的 sleep，讓所有執行緒都完成： ::" + +#: ../../faq/library.rst:253 +msgid "" +"import threading, time\n" +"\n" +"def thread_task(name, n):\n" +" for i in range(n):\n" +" print(name, i)\n" +"\n" +"for i in range(10):\n" +" T = threading.Thread(target=thread_task, args=(str(i), i))\n" +" T.start()\n" +"\n" +"time.sleep(10) # <---------------------------!" +msgstr "" +"import threading, time\n" +"\n" +"def thread_task(name, n):\n" +" for i in range(n):\n" +" print(name, i)\n" +"\n" +"for i in range(10):\n" +" T = threading.Thread(target=thread_task, args=(str(i), i))\n" +" T.start()\n" +"\n" +"time.sleep(10) # <---------------------------!" + +#: ../../faq/library.rst:265 +#, fuzzy +msgid "" +"But now (on many platforms) the threads don't run in parallel, but appear to " +"run sequentially, one at a time! The reason is that the OS thread scheduler " +"doesn't start a new thread until the previous thread is blocked." +msgstr "" +"但是現在（在許多平台上）執行緒不是並行運行的，而是看起來是順序運行的，一次一" +"個！原因是作業系統執行緒調度程式在前一個執行緒被阻塞之前不會啟動一個新執行" +"緒。" + +#: ../../faq/library.rst:269 +msgid "A simple fix is to add a tiny sleep to the start of the run function::" +msgstr "一個簡單的修復方式是在運行函式的開頭新增一個小 sleep： ::" + +#: ../../faq/library.rst:271 +msgid "" +"def thread_task(name, n):\n" +" time.sleep(0.001) # <--------------------!\n" +" for i in range(n):\n" +" print(name, i)\n" +"\n" +"for i in range(10):\n" +" T = threading.Thread(target=thread_task, args=(str(i), i))\n" +" T.start()\n" +"\n" +"time.sleep(10)" +msgstr "" +"def thread_task(name, n):\n" +" time.sleep(0.001) # <--------------------!\n" +" for i in range(n):\n" +" print(name, i)\n" +"\n" +"for i in range(10):\n" +" T = threading.Thread(target=thread_task, args=(str(i), i))\n" +" T.start()\n" +"\n" +"time.sleep(10)" + +#: ../../faq/library.rst:282 +#, fuzzy +msgid "" +"Instead of trying to guess a good delay value for :func:`time.sleep`, it's " +"better to use some kind of semaphore mechanism. One idea is to use " +"the :mod:`queue` module to create a queue object, let each thread append a " +"token to the queue when it finishes, and let the main thread read as many " +"tokens from the queue as there are threads." +msgstr "" +"與其嘗試為 :func:`time.sleep` 猜測一個好的延遲值，不如使用某種訊號量機制。一" +"種想法是使用 :mod:`queue` 模組建立一個隊列物件，讓每個執行緒在完成時向隊列新" +"增一個權杖，並讓主執行緒從隊列中讀取與執行緒數一樣多的權杖。" + +#: ../../faq/library.rst:290 +#, fuzzy +msgid "How do I parcel out work among a bunch of worker threads?" +msgstr "我如何在一堆工作執行緒中分配工作？" + +#: ../../faq/library.rst:292 +#, fuzzy +msgid "" +"The easiest way is to use the :mod:`concurrent.futures` module, especially " +"the :mod:`~concurrent.futures.ThreadPoolExecutor` class." +msgstr "" +"最簡單的方法是使用 :mod:`concurrent.futures` 模組，尤其" +"是 :mod:`~concurrent.futures.ThreadPoolExecutor` 類別。" + +#: ../../faq/library.rst:295 +#, fuzzy +msgid "" +"Or, if you want fine control over the dispatching algorithm, you can write " +"your own logic manually. Use the :mod:`queue` module to create a queue " +"containing a list of jobs. The :class:`~queue.Queue` class maintains a list " +"of objects and has a ``.put(obj)`` method that adds items to the queue and a " +"``.get()`` method to return them. The class will take care of the locking " +"necessary to ensure that each job is handed out exactly once." +msgstr "" +"或者，如果你想對調度演算法進行精細控制，你可以手動編寫自己的邏輯。使" +"用 :mod:`queue` 模組建立一個包含作業列表的隊列。 :class:`~queue.Queue` 類別維" +"護一個物件列表，並有一個 `.put(obj)`` 方法將項目新增到隊列和一個 ``.get()`` " +"方法回傳它們。該類別將負責必要的鎖定，以確保每個作業都恰好分發一次。" + +#: ../../faq/library.rst:302 +msgid "Here's a trivial example::" +msgstr "這是一個簡單的例子： ::" + +#: ../../faq/library.rst:304 +msgid "" +"import threading, queue, time\n" +"\n" +"# The worker thread gets jobs off the queue. When the queue is empty, it\n" +"# assumes there will be no more work and exits.\n" +"# (Realistically workers will run until terminated.)\n" +"def worker():\n" +" print('Running worker')\n" +" time.sleep(0.1)\n" +" while True:\n" +" try:\n" +" arg = q.get(block=False)\n" +" except queue.Empty:\n" +" print('Worker', threading.current_thread(), end=' ')\n" +" print('queue empty')\n" +" break\n" +" else:\n" +" print('Worker', threading.current_thread(), end=' ')\n" +" print('running with argument', arg)\n" +" time.sleep(0.5)\n" +"\n" +"# Create queue\n" +"q = queue.Queue()\n" +"\n" +"# Start a pool of 5 workers\n" +"for i in range(5):\n" +" t = threading.Thread(target=worker, name='worker %i' % (i+1))\n" +" t.start()\n" +"\n" +"# Begin adding work to the queue\n" +"for i in range(50):\n" +" q.put(i)\n" +"\n" +"# Give threads time to run\n" +"print('Main thread sleeping')\n" +"time.sleep(5)" +msgstr "" + +#: ../../faq/library.rst:340 +msgid "When run, this will produce the following output:" +msgstr "運行時，這將產生以下輸出：" + +#: ../../faq/library.rst:342 +msgid "" +"Running worker\n" +"Running worker\n" +"Running worker\n" +"Running worker\n" +"Running worker\n" +"Main thread sleeping\n" +"Worker running with argument 0\n" +"Worker running with argument 1\n" +"Worker running with argument 2\n" +"Worker running with argument 3\n" +"Worker running with argument 4\n" +"Worker running with argument 5\n" +"..." +msgstr "" +"Running worker\n" +"Running worker\n" +"Running worker\n" +"Running worker\n" +"Running worker\n" +"Main thread sleeping\n" +"Worker running with argument 0\n" +"Worker running with argument 1\n" +"Worker running with argument 2\n" +"Worker running with argument 3\n" +"Worker running with argument 4\n" +"Worker running with argument 5\n" +"..." + +#: ../../faq/library.rst:358 +#, fuzzy +msgid "" +"Consult the module's documentation for more details; " +"the :class:`~queue.Queue` class provides a featureful interface." +msgstr "" +"有關更多詳細資訊，請參閱模組的文件； :class:`~queue.Queue` 類別提供了一個功能" +"強大的介面。" + +#: ../../faq/library.rst:363 +msgid "What kinds of global value mutation are thread-safe?" +msgstr "什麼樣的全域值變化是執行緒安全的？" + +#: ../../faq/library.rst:365 +#, fuzzy +msgid "" +"A :term:`global interpreter lock` (GIL) is used internally to ensure that " +"only one thread runs in the Python VM at a time. In general, Python offers " +"to switch among threads only between bytecode instructions; how frequently " +"it switches can be set via :func:`sys.setswitchinterval`. Each bytecode " +"instruction and therefore all the C implementation code reached from each " +"instruction is therefore atomic from the point of view of a Python program." +msgstr "" +"內部使用 :term:`全域直譯器鎖 (GIL, global interpreter lock)`\\ 來確保一次只有" +"一個執行緒在 Python VM 中運行。通常，Python 僅提供位元組碼指令之間的執行緒切" +"換；可以透過 :func:`sys.setswitchinterval` 設定它切換的頻率。因此，從 Python " +"程式的角度來看，每條位元組碼指令以及從每條指令到達的所有 C 實作程式碼都是原子" +"的。" + +#: ../../faq/library.rst:372 +#, fuzzy +msgid "" +"In theory, this means an exact accounting requires an exact understanding of " +"the PVM bytecode implementation. In practice, it means that operations on " +"shared variables of built-in data types (ints, lists, dicts, etc) that " +"\"look atomic\" really are." +msgstr "" +"從理論上講，這意味著準確的記賬需要對 PVM 位元組碼實作有準確的理解。實際上，這" +"意味著對 \"看起來原子\" 的內置資料型別（整數、列表、字典等）的共享變數的操作" +"確實是原子的。" + +#: ../../faq/library.rst:377 +#, fuzzy +msgid "" +"For example, the following operations are all atomic (L, L1, L2 are lists, " +"D, D1, D2 are dicts, x, y are objects, i, j are ints)::" +msgstr "" +"例如，以下操作都是原子的（L、L1、L2 是列表，D、D1、D2 是字典，x、y 是物件，" +"i、j 是整數）： ::" + +#: ../../faq/library.rst:380 +msgid "" +"L.append(x)\n" +"L1.extend(L2)\n" +"x = L[i]\n" +"x = L.pop()\n" +"L1[i:j] = L2\n" +"L.sort()\n" +"x = y\n" +"x.field = y\n" +"D[x] = y\n" +"D1.update(D2)\n" +"D.keys()" +msgstr "" +"L.append(x)\n" +"L1.extend(L2)\n" +"x = L[i]\n" +"x = L.pop()\n" +"L1[i:j] = L2\n" +"L.sort()\n" +"x = y\n" +"x.field = y\n" +"D[x] = y\n" +"D1.update(D2)\n" +"D.keys()" + +#: ../../faq/library.rst:392 +msgid "These aren't::" +msgstr "這些不是： ::" + +#: ../../faq/library.rst:394 +msgid "" +"i = i+1\n" +"L.append(L[-1])\n" +"L[i] = L[j]\n" +"D[x] = D[x] + 1" +msgstr "" +"i = i+1\n" +"L.append(L[-1])\n" +"L[i] = L[j]\n" +"D[x] = D[x] + 1" + +#: ../../faq/library.rst:399 +#, fuzzy +msgid "" +"Operations that replace other objects may invoke those other " +"objects' :meth:`~object.__del__` method when their reference count reaches " +"zero, and that can affect things. This is especially true for the mass " +"updates to dictionaries and lists. When in doubt, use a mutex!" +msgstr "" +"替換其他物件的操作可能會在引用計數達到零時叫用其他物件的 :meth:`__del__` 方" +"法，這可能會影響事情。對於字典和列表的大量更新尤其如此。如有疑問，請使用互斥" +"體！" + +#: ../../faq/library.rst:406 +msgid "Can't we get rid of the Global Interpreter Lock?" +msgstr "不能擺脫全域直譯器鎖嗎？" + +#: ../../faq/library.rst:408 +#, fuzzy +msgid "" +"The :term:`global interpreter lock` (GIL) is often seen as a hindrance to " +"Python's deployment on high-end multiprocessor server machines, because a " +"multi-threaded Python program effectively only uses one CPU, due to the " +"insistence that (almost) all Python code can only run while the GIL is held." +msgstr "" +":term:`global interpreter lock` (GIL) 通常被視為 Python 在高階多處理器伺服器" +"機器上部署的障礙，因為多執行緒 Python 程式實際上只使用一個 CPU，因為堅持（幾" +"乎）所有 Python 程式碼只能在持有 GIL 的情況下運行。" + +#: ../../faq/library.rst:413 +msgid "" +"With the approval of :pep:`703` work is now underway to remove the GIL from " +"the CPython implementation of Python. Initially it will be implemented as " +"an optional compiler flag when building the interpreter, and so separate " +"builds will be available with and without the GIL. Long-term, the hope is " +"to settle on a single build, once the performance implications of removing " +"the GIL are fully understood. Python 3.13 is likely to be the first release " +"containing this work, although it may not be completely functional in this " +"release." +msgstr "" + +#: ../../faq/library.rst:422 +#, fuzzy +msgid "" +"The current work to remove the GIL is based on a `fork of Python 3.9 with " +"the GIL removed `_ by Sam Gross. Prior " +"to that, in the days of Python 1.5, Greg Stein actually implemented a " +"comprehensive patch set (the \"free threading\" patches) that removed the " +"GIL and replaced it with fine-grained locking. Adam Olsen did a similar " +"experiment in his `python-safethread `_ project. Unfortunately, both of these earlier " +"experiments exhibited a sharp drop in single-thread performance (at least " +"30% slower), due to the amount of fine-grained locking necessary to " +"compensate for the removal of the GIL. The Python 3.9 fork is the first " +"attempt at removing the GIL with an acceptable performance impact." +msgstr "" +"回到 Python 1.5 時代，Greg Stein 實際上實作了一個全面的補丁集（ \"自由執行緒" +"\" 補丁），刪除了 GIL 並用細粒度鎖定取而代之。 Adam Olsen 最近在他的 `python-" +"safethread `_ 項目中做了" +"一個類似的實驗。不幸的是，這兩個實驗都表現出單執行緒性能的急劇下降（至少慢了 " +"30%），這是由於需要大量的細粒度鎖定來補償 GIL 的移除。" + +#: ../../faq/library.rst:437 +#, fuzzy +msgid "" +"The presence of the GIL in current Python releases doesn't mean that you " +"can't make good use of Python on multi-CPU machines! You just have to be " +"creative with dividing the work up between multiple *processes* rather than " +"multiple *threads*. The :class:`~concurrent.futures.ProcessPoolExecutor` " +"class in the new :mod:`concurrent.futures` module provides an easy way of " +"doing so; the :mod:`multiprocessing` module provides a lower-level API in " +"case you want more control over dispatching of tasks." +msgstr "" +"這並不意味著你不能在多 CPU 機器上用好 Python！你只需要創造性地將工作分配給多" +"個*行程*而​​不是多個*執行緒*。新的 :mod:`concurrent.futures` 模組中" +"的 :class:`~concurrent.futures.ProcessPoolExecutor` 類別提供了一種簡單的方" +"法； :mod:`multiprocessing` 模組提供了一個較低階別的 API，以防你希望更好地控" +"制任務的調度。" + +#: ../../faq/library.rst:446 +#, fuzzy +msgid "" +"Judicious use of C extensions will also help; if you use a C extension to " +"perform a time-consuming task, the extension can release the GIL while the " +"thread of execution is in the C code and allow other threads to get some " +"work done. Some standard library modules such as :mod:`zlib` " +"and :mod:`hashlib` already do this." +msgstr "" +"明智地使用 C 擴充也會有所幫助；如果你使用 C 擴充來執行耗時任務，則該擴充可以" +"在執行執行緒在 C 程式碼中時釋放 GIL，並允許其他執行緒完成一些工作。一些標準函" +"式庫模組，例如 :mod:`zlib` 和 :mod:`hashlib` 已經這樣做了。" + +#: ../../faq/library.rst:452 +msgid "" +"An alternative approach to reducing the impact of the GIL is to make the GIL " +"a per-interpreter-state lock rather than truly global. This was :ref:`first " +"implemented in Python 3.12 ` and is available in the C " +"API. A Python interface to it is expected in Python 3.13. The main " +"limitation to it at the moment is likely to be 3rd party extension modules, " +"since these must be written with multiple interpreters in mind in order to " +"be usable, so many older extension modules will not be usable." +msgstr "" +"減少 GIL 影響的另一種方法是將 GIL 設置為直譯器各自狀態的鎖 (per-interpreter-" +"state lock)，而不是真正的全域鎖。這在 :ref:`Python 3.12 中首次實現 " +"`，並且可於 C API 中使用。預計 Python 3.13 將會提供其 " +"Python 介面。目前主要的限制可能是第三方擴充模組，因為實作時必須考慮到多個直譯" +"器才能使用，因此許多舊的擴充模組將無法使用。" + +#: ../../faq/library.rst:462 +msgid "Input and Output" +msgstr "輸入與輸出" + +#: ../../faq/library.rst:465 +msgid "How do I delete a file? (And other file questions...)" +msgstr "如何刪除檔案？（以及其他檔案問題...）" + +#: ../../faq/library.rst:467 +#, fuzzy +msgid "" +"Use ``os.remove(filename)`` or ``os.unlink(filename)``; for documentation, " +"see the :mod:`os` module. The two functions are " +"identical; :func:`~os.unlink` is simply the name of the Unix system call for " +"this function." +msgstr "" +"使用 ``os.remove(filename)`` 或 ``os.unlink(filename)``；有關文件，請參" +"閱 :mod:`os` 模組。這兩個功能是相同的； :func:`~os.unlink` 只是這個函式的 " +"Unix 系統呼叫的名稱。" + +#: ../../faq/library.rst:471 +#, fuzzy +msgid "" +"To remove a directory, use :func:`os.rmdir`; use :func:`os.mkdir` to create " +"one. ``os.makedirs(path)`` will create any intermediate directories in " +"``path`` that don't exist. ``os.removedirs(path)`` will remove intermediate " +"directories as long as they're empty; if you want to delete an entire " +"directory tree and its contents, use :func:`shutil.rmtree`." +msgstr "" +"要刪除目錄，請使用 :func:`os.rmdir`;使用 :func:`os.mkdir` 建立一個。 " +"``os.makedirs(path)`` 將在 ``path`` 中建立任何不存在的中間目錄。 " +"``os.removedirs(path)`` 將刪除中間目錄，只要它們是空的；如果要刪除整個目錄樹" +"及其內容，請使用 :func:`shutil.rmtree`。" + +#: ../../faq/library.rst:477 +msgid "To rename a file, use ``os.rename(old_path, new_path)``." +msgstr "要重新命名檔案，請使用 ``os.rename(old_path, new_path)``。" + +#: ../../faq/library.rst:479 +#, fuzzy +msgid "" +"To truncate a file, open it using ``f = open(filename, \"rb+\")``, and use " +"``f.truncate(offset)``; offset defaults to the current seek position. " +"There's also ``os.ftruncate(fd, offset)`` for files opened " +"with :func:`os.open`, where *fd* is the file descriptor (a small integer)." +msgstr "" +"要截斷一個檔案，使用``f = open(filename, \"rb+\")``打開它，然後使用" +"``f.truncate(offset)``；偏移量預設為目前搜尋位置。對於使用 :func:`os.open` 打" +"開的檔案，還有 ``os.ftruncate(fd, offset)``，其中 *fd* 是檔案描述器（一個小整" +"數）。" + +#: ../../faq/library.rst:484 +msgid "" +"The :mod:`shutil` module also contains a number of functions to work on " +"files including :func:`~shutil.copyfile`, :func:`~shutil.copytree`, " +"and :func:`~shutil.rmtree`." +msgstr "" +":mod:`shutil` 模組還包含許多用於檔案處理的函式，包" +"括 :func:`~shutil.copyfile`、:func:`~shutil.copytree` " +"和 :func:`~shutil.rmtree`。" + +#: ../../faq/library.rst:490 +msgid "How do I copy a file?" +msgstr "如何複製檔案？" + +#: ../../faq/library.rst:492 +#, fuzzy +msgid "" +"The :mod:`shutil` module contains a :func:`~shutil.copyfile` function. Note " +"that on Windows NTFS volumes, it does not copy `alternate data streams " +"`_ nor " +"`resource forks `__ on macOS " +"HFS+ volumes, though both are now rarely used. It also doesn't copy file " +"permissions and metadata, though using :func:`shutil.copy2` instead will " +"preserve most (though not all) of it." +msgstr "" +":mod:`shutil` 模組包含一個 :func:`~shutil.copyfile` 函式。請注意，在 Windows " +"NTFS 卷上，它不會複製 `alternate data streams `_ 也不會複製 `resource forks `__ 在 macOS HFS+ 卷上，儘管現在兩者都很" +"少使用。它也不會複製檔案權限和元資料，儘管使用 :func:`shutil.copy2` 會保留其" +"中的大部分（儘管不是全部）。" + +#: ../../faq/library.rst:503 +msgid "How do I read (or write) binary data?" +msgstr "如何讀取（或寫入）二進位制資料？" + +#: ../../faq/library.rst:505 +#, fuzzy +msgid "" +"To read or write complex binary data formats, it's best to use " +"the :mod:`struct` module. It allows you to take a string containing binary " +"data (usually numbers) and convert it to Python objects; and vice versa." +msgstr "" +"要讀取或寫入複雜的二進制資料格式，最好使用 :mod:`struct` 模組。它允許你取得包" +"含二進制資料（通常是數字）的字串並將其轉換為 Python 物件；反之亦然。" + +#: ../../faq/library.rst:509 +#, fuzzy +msgid "" +"For example, the following code reads two 2-byte integers and one 4-byte " +"integer in big-endian format from a file::" +msgstr "" +"例如，以下程式碼從一個檔案中以大端格式讀取兩個 2 位元組整數和一個 4 位元組整" +"數： ::" + +#: ../../faq/library.rst:512 +msgid "" +"import struct\n" +"\n" +"with open(filename, \"rb\") as f:\n" +" s = f.read(8)\n" +" x, y, z = struct.unpack(\">hhl\", s)" +msgstr "" +"import struct\n" +"\n" +"with open(filename, \"rb\") as f:\n" +" s = f.read(8)\n" +" x, y, z = struct.unpack(\">hhl\", s)" + +#: ../../faq/library.rst:518 +#, fuzzy +msgid "" +"The '>' in the format string forces big-endian data; the letter 'h' reads " +"one \"short integer\" (2 bytes), and 'l' reads one \"long integer\" (4 " +"bytes) from the string." +msgstr "" +"格式字串中的 \">\" 強制使用大端資料；字母 'h' 讀取一個 \"短整數\" （2 位元" +"組）， 'l' 從字串中讀取一個 \"長整數\" （4 位元組）。" + +#: ../../faq/library.rst:522 +#, fuzzy +msgid "" +"For data that is more regular (e.g. a homogeneous list of ints or floats), " +"you can also use the :mod:`array` module." +msgstr "" +"對於更規則的資料（例如，整數或浮點數的同類列表），你還可以使用 :mod:`array` " +"模組。" + +#: ../../faq/library.rst:527 +#, fuzzy +msgid "" +"To read and write binary data, it is mandatory to open the file in binary " +"mode (here, passing ``\"rb\"`` to :func:`open`). If you use ``\"r\"`` " +"instead (the default), the file will be open in text mode and ``f.read()`` " +"will return :class:`str` objects rather than :class:`bytes` objects." +msgstr "" +"要讀取和寫入二進位資料，必須以二進位模式打開檔案（這裡，將 ``\"rb\"`` 傳遞" +"給 :func:`open`）。如果你改用 ``\"r\"``\\ （預設設定），檔案將以文本模式打開，並" +"且 ``f.read()`` 將回傳 :class:`str` 物件而不是 :class:`bytes` 物件。" + +#: ../../faq/library.rst:535 +msgid "I can't seem to use os.read() on a pipe created with os.popen(); why?" +msgstr "我似乎無法在用 os.popen() 建立的 pipe 上使用 os.read()；為什麼？" + +#: ../../faq/library.rst:537 +#, fuzzy +msgid "" +":func:`os.read` is a low-level function which takes a file descriptor, a " +"small integer representing the opened file. :func:`os.popen` creates a high-" +"level file object, the same type returned by the built-in :func:`open` " +"function. Thus, to read *n* bytes from a pipe *p* created " +"with :func:`os.popen`, you need to use ``p.read(n)``." +msgstr "" +":func:`os.read` 是一個低階函式，它接受一個檔案描述器，一個代表打開檔案的小整" +"數。 :func:`os.popen` 建立一個高階檔案物件，與內置的 :func:`open` 函式回傳的" +"型別相同。因此，要從使用 :func:`os.popen` 建立的管道 *p* 中讀取 *n* 個位元" +"組，你需要使用 ``p.read(n)``。" + +#: ../../faq/library.rst:545 +msgid "How do I access the serial (RS232) port?" +msgstr "如何存取序列 (RS232) 連接埠？" + +#: ../../faq/library.rst:547 +msgid "For Win32, OSX, Linux, BSD, Jython, IronPython:" +msgstr "對於 Win32、OSX、Linux、BSD、Jython、IronPython：" + +#: ../../faq/library.rst:549 +msgid ":pypi:`pyserial`" +msgstr ":pypi:`pyserial`" + +#: ../../faq/library.rst:551 +msgid "For Unix, see a Usenet post by Mitch Chapman:" +msgstr "對於 Unix，請參閱 Mitch Chapman 的 Usenet 貼文：" + +#: ../../faq/library.rst:553 +msgid "https://groups.google.com/groups?selm=34A04430.CF9@ohioee.com" +msgstr "https://groups.google.com/groups?selm=34A04430.CF9@ohioee.com" + +#: ../../faq/library.rst:557 +msgid "Why doesn't closing sys.stdout (stdin, stderr) really close it?" +msgstr "為什麼關閉 sys.stdout (stdin, stderr) 並沒有真正關閉它？" + +#: ../../faq/library.rst:559 +msgid "" +"Python :term:`file objects ` are a high-level layer of " +"abstraction on low-level C file descriptors." +msgstr "" +"Python :term:`檔案物件 `\\ 是低階 C 檔案描述器的高階抽象層。" + +#: ../../faq/library.rst:562 +#, fuzzy +msgid "" +"For most file objects you create in Python via the built-in :func:`open` " +"function, ``f.close()`` marks the Python file object as being closed from " +"Python's point of view, and also arranges to close the underlying C file " +"descriptor. This also happens automatically in ``f``'s destructor, when " +"``f`` becomes garbage." +msgstr "" +"對於你透過內置的 :func:`open` 函式在 Python 中建立的大多數檔案物件，" +"``f.close()`` 從 Python 的角度將 Python 檔案物件標記為已關閉，並安排關閉底層 " +"C 檔案描述器。當 ``f`` 變成垃圾時，這也會自動發生在 ``f`` 的析構函式中。" + +#: ../../faq/library.rst:568 +#, fuzzy +msgid "" +"But stdin, stdout and stderr are treated specially by Python, because of the " +"special status also given to them by C. Running ``sys.stdout.close()`` " +"marks the Python-level file object as being closed, but does *not* close the " +"associated C file descriptor." +msgstr "" +"但是 stdin、stdout 和 stderr 被 Python 特殊對待，因為 C 也賦予它們特殊的狀" +"態。運行 ``sys.stdout.close()`` 將 Python 級檔案物件標記為已關閉，但是 * " +"not* 關閉關聯的 C 檔案描述器。" + +#: ../../faq/library.rst:573 +#, fuzzy +msgid "" +"To close the underlying C file descriptor for one of these three, you should " +"first be sure that's what you really want to do (e.g., you may confuse " +"extension modules trying to do I/O). If it is, use :func:`os.close`::" +msgstr "" +"要關閉這三個之一的底層 C 檔案描述器，你應該首先確定這是你真正想要做的（例如，" +"你可能會混淆試圖執行 I/O 的擴充模組）。如果是，使用 :func:`os.close`： ::" + +#: ../../faq/library.rst:577 +msgid "" +"os.close(stdin.fileno())\n" +"os.close(stdout.fileno())\n" +"os.close(stderr.fileno())" +msgstr "" +"os.close(stdin.fileno())\n" +"os.close(stdout.fileno())\n" +"os.close(stderr.fileno())" + +#: ../../faq/library.rst:581 +msgid "Or you can use the numeric constants 0, 1 and 2, respectively." +msgstr "或者你可以分別使用數字常數 0、1 和 2。" + +#: ../../faq/library.rst:585 +msgid "Network/Internet Programming" +msgstr "網路 (Network)/網際網路 (Internet) 程式" + +#: ../../faq/library.rst:588 +msgid "What WWW tools are there for Python?" +msgstr "Python 有哪些 WWW 工具？" + +#: ../../faq/library.rst:590 +#, fuzzy +msgid "" +"See the chapters titled :ref:`internet` and :ref:`netdata` in the Library " +"Reference Manual. Python has many modules that will help you build server-" +"side and client-side web systems." +msgstr "" +"請參閱函式庫參考手冊中標題為 :ref:`internet` 和 :ref:`netdata` 的章節。 " +"Python 有許多模組可以幫助你構建伺服器端和用戶端 Web 系統。" + +#: ../../faq/library.rst:596 +msgid "" +"A summary of available frameworks is maintained by Paul Boddie at https://" +"wiki.python.org/moin/WebProgramming\\ ." +msgstr "" +"Paul Boddie 有在 https://wiki.python.org/moin/" +"WebProgramming\\ 維護可用框架的摘要。" + +#: ../../faq/library.rst:601 +msgid "What module should I use to help with generating HTML?" +msgstr "我應該使用什麼模組來輔助產生 HTML？" + +#: ../../faq/library.rst:605 +msgid "" +"You can find a collection of useful links on the `Web Programming wiki page " +"`_." +msgstr "" +"你可以在 \"網頁程式維基頁面 \" 上找到一組有用的鏈接。" + +#: ../../faq/library.rst:610 +msgid "How do I send mail from a Python script?" +msgstr "如何從 Python 腳本發送郵件？" + +#: ../../faq/library.rst:612 +msgid "Use the standard library module :mod:`smtplib`." +msgstr "使用標準函式庫模組 :mod:`smtplib`。" + +#: ../../faq/library.rst:614 +#, fuzzy +msgid "" +"Here's a very simple interactive mail sender that uses it. This method will " +"work on any host that supports an SMTP listener. ::" +msgstr "" +"這是一個使用它的非常簡單的交互式郵件發件人。此方法適用於任何支援 SMTP 偵聽器" +"的主機。： ::" + +#: ../../faq/library.rst:617 +msgid "" +"import sys, smtplib\n" +"\n" +"fromaddr = input(\"From: \")\n" +"toaddrs = input(\"To: \").split(',')\n" +"print(\"Enter message, end with ^D:\")\n" +"msg = ''\n" +"while True:\n" +" line = sys.stdin.readline()\n" +" if not line:\n" +" break\n" +" msg += line\n" +"\n" +"# The actual mail send\n" +"server = smtplib.SMTP('localhost')\n" +"server.sendmail(fromaddr, toaddrs, msg)\n" +"server.quit()" +msgstr "" +"import sys, smtplib\n" +"\n" +"fromaddr = input(\"From: \")\n" +"toaddrs = input(\"To: \").split(',')\n" +"print(\"Enter message, end with ^D:\")\n" +"msg = ''\n" +"while True:\n" +" line = sys.stdin.readline()\n" +" if not line:\n" +" break\n" +" msg += line\n" +"\n" +"# The actual mail send\n" +"server = smtplib.SMTP('localhost')\n" +"server.sendmail(fromaddr, toaddrs, msg)\n" +"server.quit()" + +#: ../../faq/library.rst:634 +msgid "" +"A Unix-only alternative uses sendmail. The location of the sendmail program " +"varies between systems; sometimes it is ``/usr/lib/sendmail``, sometimes ``/" +"usr/sbin/sendmail``. The sendmail manual page will help you out. Here's " +"some sample code::" +msgstr "" +"使用 sendmail 是僅適用於 Unix 的替代方案。sendmail 程式的位置會因系統而異；有" +"時是 ``/usr/lib/sendmail``，有時是 ``/usr/sbin/sendmail``。sendmail 使用手冊" +"將能夠幫助你。這是一些範例程式碼： ::" + +#: ../../faq/library.rst:639 +msgid "" +"import os\n" +"\n" +"SENDMAIL = \"/usr/sbin/sendmail\" # sendmail location\n" +"p = os.popen(\"%s -t -i\" % SENDMAIL, \"w\")\n" +"p.write(\"To: receiver@example.com\\n\")\n" +"p.write(\"Subject: test\\n\")\n" +"p.write(\"\\n\") # blank line separating headers from body\n" +"p.write(\"Some text\\n\")\n" +"p.write(\"some more text\\n\")\n" +"sts = p.close()\n" +"if sts != 0:\n" +" print(\"Sendmail exit status\", sts)" +msgstr "" + +#: ../../faq/library.rst:654 +msgid "How do I avoid blocking in the connect() method of a socket?" +msgstr "如何避免阻塞 socket 的 connect() 方法？" + +#: ../../faq/library.rst:656 +msgid "" +"The :mod:`select` module is commonly used to help with asynchronous I/O on " +"sockets." +msgstr ":mod:`select` 模組通常用於幫助處理 socket 上的非同步 I/O。" + +#: ../../faq/library.rst:659 +#, fuzzy +msgid "" +"To prevent the TCP connect from blocking, you can set the socket to non-" +"blocking mode. Then when you do the :meth:`~socket.socket.connect`, you " +"will either connect immediately (unlikely) or get an exception that contains " +"the error number as ``.errno``. ``errno.EINPROGRESS`` indicates that the " +"connection is in progress, but hasn't finished yet. Different OSes will " +"return different values, so you're going to have to check what's returned on " +"your system." +msgstr "" +"為防止 TCP 連接阻塞，可以將 socket 設定為非阻塞模式。然後當你執" +"行 :meth:`socket.connect` 時，你要麼立即連接（不太可能），要麼得到一個例外，" +"其中包含錯誤號 ``.errno``。 ``errno.EINPROGRESS`` 表示連接正在進行中，但尚未" +"完成。不同的作業系統將回傳不同的值，因此你將不得不檢查系統回傳的內容。" + +#: ../../faq/library.rst:667 +#, fuzzy +msgid "" +"You can use the :meth:`~socket.socket.connect_ex` method to avoid creating " +"an exception. It will just return the errno value. To poll, you can " +"call :meth:`~socket.socket.connect_ex` again later -- ``0`` or " +"``errno.EISCONN`` indicate that you're connected -- or you can pass this " +"socket to :meth:`select.select` to check if it's writable." +msgstr "" +"你可以使用 :meth:`socket.connect_ex` 方法來避免建立例外。它只會回傳 errno " +"值。要輪詢，你可以稍後再次呼叫 :meth:`socket.connect_ex` - ``0`` 或 " +"``errno.EISCONN`` 表示你已連接 - 或者你可以將此 socket 傳遞" +"給 :meth:`select.select` 檢查它是否可寫。" + +#: ../../faq/library.rst:675 +msgid "" +"The :mod:`asyncio` module provides a general purpose single-threaded and " +"concurrent asynchronous library, which can be used for writing non-blocking " +"network code. The third-party `Twisted `_ library is a " +"popular and feature-rich alternative." +msgstr "" +":mod:`asyncio` 模組提供了一個通用的單執行緒並發非同步函式庫，可用於編寫非阻塞" +"網路程式碼。第三方 `Twisted `_ 函式庫是一種流行且功能豐" +"富的替代方案。" + +#: ../../faq/library.rst:683 +msgid "Databases" +msgstr "資料庫" + +#: ../../faq/library.rst:686 +msgid "Are there any interfaces to database packages in Python?" +msgstr "Python 中是否有任何資料庫套件的介面？" + +#: ../../faq/library.rst:688 +msgid "Yes." +msgstr "有的。" + +#: ../../faq/library.rst:690 +#, fuzzy +msgid "" +"Interfaces to disk-based hashes such as :mod:`DBM ` and :mod:`GDBM " +"` are also included with standard Python. There is also " +"the :mod:`sqlite3` module, which provides a lightweight disk-based " +"relational database." +msgstr "" +"基於磁碟的雜湊介面，例如 :mod:`DBM ` 和 :mod:`GDBM ` 也包" +"含在標準 Python 中。還有 :mod:`sqlite3` 模組，它提供了一個輕量級的基於磁碟的" +"關係資料庫。" + +#: ../../faq/library.rst:695 +#, fuzzy +msgid "" +"Support for most relational databases is available. See the " +"`DatabaseProgramming wiki page `_ for details." +msgstr "" +"支援大多數關係資料庫。有關詳細資訊，請參閱 `DatabaseProgramming 維基頁面 " +"`_。" + +#: ../../faq/library.rst:701 +msgid "How do you implement persistent objects in Python?" +msgstr "你如何在 Python 中實作持久性物件？" + +#: ../../faq/library.rst:703 +#, fuzzy +msgid "" +"The :mod:`pickle` library module solves this in a very general way (though " +"you still can't store things like open files, sockets or windows), and " +"the :mod:`shelve` library module uses pickle and (g)dbm to create persistent " +"mappings containing arbitrary Python objects." +msgstr "" +":mod:`pickle` 函式庫模組以一種非常通用的方式解決了這個問題（儘管你仍然不能存" +"儲諸如打開的檔案、socket 或窗口之類的東西），而 :mod:`shelve` 函式庫模組使用 " +"pickle 和 (g) dbm 建立包含任意 Python 物件的持久對映。" + +#: ../../faq/library.rst:710 +msgid "Mathematics and Numerics" +msgstr "數學和數值" + +#: ../../faq/library.rst:713 +msgid "How do I generate random numbers in Python?" +msgstr "如何在 Python 中生成隨機數？" + +#: ../../faq/library.rst:715 +msgid "" +"The standard module :mod:`random` implements a random number generator. " +"Usage is simple::" +msgstr "標準模組 :mod:`random` 實作了一個隨機數生成器。用法很簡單： ::" + +#: ../../faq/library.rst:718 +msgid "" +"import random\n" +"random.random()" +msgstr "" +"import random\n" +"random.random()" + +#: ../../faq/library.rst:721 +msgid "This returns a random floating-point number in the range [0, 1)." +msgstr "這將回傳 [0, 1) 範圍內的隨機浮點數。" + +#: ../../faq/library.rst:723 +msgid "" +"There are also many other specialized generators in this module, such as:" +msgstr "該模組中還有許多其他專用生成器，例如：" + +#: ../../faq/library.rst:725 +msgid "``randrange(a, b)`` chooses an integer in the range [a, b)." +msgstr "``randrange(a, b)`` 會選擇 [a, b) 範圍內的一個整數。" + +#: ../../faq/library.rst:726 +msgid "``uniform(a, b)`` chooses a floating-point number in the range [a, b)." +msgstr "``uniform(a, b)`` 會選擇 [a, b) 範圍內的浮點數。" + +#: ../../faq/library.rst:727 +msgid "" +"``normalvariate(mean, sdev)`` samples the normal (Gaussian) distribution." +msgstr "``normalvariate(mean, sdev)`` 對常態（高斯）分佈進行取樣 (sample)。" + +#: ../../faq/library.rst:729 +msgid "Some higher-level functions operate on sequences directly, such as:" +msgstr "一些更高階的函式會直接對序列進行操作，例如：" + +#: ../../faq/library.rst:731 +msgid "``choice(S)`` chooses a random element from a given sequence." +msgstr "``choice(S)`` 會從給定序列中選擇一個隨機元素。" + +#: ../../faq/library.rst:732 +msgid "``shuffle(L)`` shuffles a list in-place, i.e. permutes it randomly." +msgstr "``shuffle(L)`` 會原地 (in-place) 打亂 list，即隨機排列它。" + +#: ../../faq/library.rst:734 +msgid "" +"There's also a ``Random`` class you can instantiate to create independent " +"multiple random number generators." +msgstr "" +"還有一個 ``Random`` 類別，你可以將它實例化以建立多個獨立的隨機數生成器。" diff --git a/faq/programming.po b/faq/programming.po index 2c133e52fc..e60eb98acb 100644 --- a/faq/programming.po +++ b/faq/programming.po @@ -1,4567 +1,4567 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# jerrychen , 2016 -# Ching-Lung Chuang, 2015 -# hsiao yi , 2016 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: 2024-04-25 14:17+0800\n" -"Last-Translator: KNChiu \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" -"X-Generator: Poedit 3.4.2\n" - -#: ../../faq/programming.rst:5 -msgid "Programming FAQ" -msgstr "程式開發常見問答集" - -#: ../../faq/programming.rst:8 -msgid "Contents" -msgstr "目錄" - -#: ../../faq/programming.rst:12 -msgid "General Questions" -msgstr "常見問題" - -#: ../../faq/programming.rst:15 -msgid "" -"Is there a source code level debugger with breakpoints, single-stepping, " -"etc.?" -msgstr "是否有可以使用在程式碼階段,具有中斷點,步驟執行等功能的除錯器？" - -#: ../../faq/programming.rst:17 ../../faq/programming.rst:58 -msgid "Yes." -msgstr "有的。" - -#: ../../faq/programming.rst:19 -msgid "" -"Several debuggers for Python are described below, and the built-in " -"function :func:`breakpoint` allows you to drop into any of them." -msgstr "" -"下面描述了幾個 Python 除錯器，內建函式 :func:`breakpoint` 允許你進入其中任何" -"一個。" - -#: ../../faq/programming.rst:22 -msgid "" -"The pdb module is a simple but adequate console-mode debugger for Python. It " -"is part of the standard Python library, and is :mod:`documented in the " -"Library Reference Manual `. You can also write your own debugger by " -"using the code for pdb as an example." -msgstr "" -"pdb 模組是一個簡單但足夠的 Python 控制台模式除錯器。它是標準 Python 函式庫的" -"一部分，並\\ :mod:`記錄在函式庫參考手冊 `\\ 中。你也可以參考 pdb 的程式" -"碼作為範例來編寫自己的除錯器。" - -#: ../../faq/programming.rst:27 -msgid "" -"The IDLE interactive development environment, which is part of the standard " -"Python distribution (normally available as `Tools/scripts/idle3 `_), includes a " -"graphical debugger." -msgstr "" -"IDLE 交互式開發環境，它是標準 Python 發行版的一部分（通常作為 `Tools/scripts/" -"idle3 `_ 提" -"供），包括一個圖形除錯器。" - -#: ../../faq/programming.rst:32 -msgid "" -"PythonWin is a Python IDE that includes a GUI debugger based on pdb. The " -"PythonWin debugger colors breakpoints and has quite a few cool features such " -"as debugging non-PythonWin programs. PythonWin is available as part of " -"`pywin32 `_ project and as a part of " -"the `ActivePython `_ " -"distribution." -msgstr "" -"PythonWin 是一個 Python IDE，它包含一個基於 pdb 的 GUI 除錯器。 PythonWin 除" -"錯器為斷點著色並具有許多很酷的功能，例如除錯非 PythonWin 程式。 PythonWin 作" -"為 `pywin32 `_ 專案的一部分和作為 " -"`ActivePython `_ 的一部分發佈。" - -#: ../../faq/programming.rst:39 -msgid "" -"`Eric `_ is an IDE built on PyQt and " -"the Scintilla editing component." -msgstr "" -"`Eric `_ 是一個基於 PyQt 和 Scintilla " -"編輯元件所建構的 IDE。" - -#: ../../faq/programming.rst:42 -msgid "" -"`trepan3k `_ is a gdb-like " -"debugger." -msgstr "" -"`trepan3k `_ 是一個類似 gdb 的除錯" -"器。" - -#: ../../faq/programming.rst:44 -msgid "" -"`Visual Studio Code `_ is an IDE with " -"debugging tools that integrates with version-control software." -msgstr "" -"`Visual Studio Code `_ 是一個整合了版本控制軟" -"體與除錯工具的 IDE。" - -#: ../../faq/programming.rst:47 -msgid "" -"There are a number of commercial Python IDEs that include graphical " -"debuggers. They include:" -msgstr "有數個商業化Python整合化開發工具包含圖形除錯功能。這些包含：" - -#: ../../faq/programming.rst:50 -msgid "`Wing IDE `_" -msgstr "`Wing IDE `_" - -#: ../../faq/programming.rst:51 -msgid "`Komodo IDE `_" -msgstr "`Komodo IDE `_" - -#: ../../faq/programming.rst:52 -msgid "`PyCharm `_" -msgstr "`PyCharm `_" - -#: ../../faq/programming.rst:56 -msgid "Are there tools to help find bugs or perform static analysis?" -msgstr "有沒有工具能夠幫忙找 bug 或執行靜態分析？" - -#: ../../faq/programming.rst:60 -msgid "" -"`Pylint `_ and `Pyflakes " -"`_ do basic checking that will help you " -"catch bugs sooner." -msgstr "" -"`Pylint `_ 和 `Pyflakes " -"`_ 進行基本檢查以幫助你儘早抓出錯誤。" - -#: ../../faq/programming.rst:64 -msgid "" -"Static type checkers such as `Mypy `_, `Pyre " -"`_, and `Pytype `_ can check type hints in Python source code." -msgstr "" -"靜態型別檢查器，例如 `Mypy `_、`Pyre `_ 和 `Pytype `_ 可以檢查 " -"Python 原始碼中的型別提示。" - -#: ../../faq/programming.rst:73 -msgid "How can I create a stand-alone binary from a Python script?" -msgstr "如何從 Python 腳本建立獨立的二進位檔案？" - -#: ../../faq/programming.rst:75 -msgid "" -"You don't need the ability to compile Python to C code if all you want is a " -"stand-alone program that users can download and run without having to " -"install the Python distribution first. There are a number of tools that " -"determine the set of modules required by a program and bind these modules " -"together with a Python binary to produce a single executable." -msgstr "" -"如果你想要的只是一個使用者可以下載並執行而無需先安裝 Python 發行版的獨立程" -"式，則不需要將 Python 編譯為 C 程式碼的能力。有許多工具可以判斷程式所需的模組" -"集，並將這些模組與 Python 二進位檔案綁定在一起以產生單個可執行檔。" - -#: ../../faq/programming.rst:81 -msgid "" -"One is to use the freeze tool, which is included in the Python source tree " -"as `Tools/freeze `_. It converts Python byte code to C arrays; with a C compiler you " -"can embed all your modules into a new program, which is then linked with the " -"standard Python modules." -msgstr "" -"一種是使用 freeze 工具，它位於 Python 原始碼樹中的 `Tools/freeze `_。它將 Python 位元組碼轉" -"換為 C 陣列；使用 C 編譯器，你可以將所有模組嵌入到一個新程式中，然後將其與標" -"準 Python 模組連結。" - -#: ../../faq/programming.rst:87 -#, fuzzy -msgid "" -"It works by scanning your source recursively for import statements (in both " -"forms) and looking for the modules in the standard Python path as well as in " -"the source directory (for built-in modules). It then turns the bytecode for " -"modules written in Python into C code (array initializers that can be turned " -"into code objects using the marshal module) and creates a custom-made config " -"file that only contains those built-in modules which are actually used in " -"the program. It then compiles the generated C code and links it with the " -"rest of the Python interpreter to form a self-contained binary which acts " -"exactly like your script." -msgstr "" -"它的工作原理是遞迴地掃描你的源程式碼以查詢引入陳述式（兩種形式）並在標準 " -"Python 路徑和源目錄（對於內建模組）中查詢模組。然後它將用 Python 編寫的模組的" -"位元組碼轉換為 C 程式碼（數組初始化器可以使用 marshal 模組轉換為程式碼物件）" -"並建立一個定制的配置檔案，該檔案僅包含那些實際使用的內建模組程式。然後它編譯" -"生成的 C 程式碼並將其與 Python 直譯器的其餘部分鏈接以形成一個獨立的二進製檔" -"案，其行為與你的腳本完全一樣。" - -#: ../../faq/programming.rst:96 -msgid "" -"The following packages can help with the creation of console and GUI " -"executables:" -msgstr "以下套件可以幫助建立 console 和 GUI 可執行檔案：" - -#: ../../faq/programming.rst:99 -msgid "`Nuitka `_ (Cross-platform)" -msgstr "`Nuitka `_\\ （跨平台）" - -#: ../../faq/programming.rst:100 -msgid "`PyInstaller `_ (Cross-platform)" -msgstr "`PyInstaller `_\\ （跨平台）" - -#: ../../faq/programming.rst:101 -msgid "" -"`PyOxidizer `_ (Cross-platform)" -msgstr "" -"`PyOxidizer `_\\ （跨平台）" - -#: ../../faq/programming.rst:102 -msgid "" -"`cx_Freeze `_ (Cross-platform)" -msgstr "" -"`cx_Freeze `_\\ （跨平台）" - -#: ../../faq/programming.rst:103 -msgid "`py2app `_ (macOS only)" -msgstr "`py2app `_\\ （僅限 macOS）" - -#: ../../faq/programming.rst:104 -msgid "`py2exe `_ (Windows only)" -msgstr "`py2exe `_\\ （僅限 Windows）" - -#: ../../faq/programming.rst:107 -msgid "Are there coding standards or a style guide for Python programs?" -msgstr "Python 程式碼是否有編碼標準或風格指南？" - -#: ../../faq/programming.rst:109 -msgid "" -"Yes. The coding style required for standard library modules is documented " -"as :pep:`8`." -msgstr "是的。標準函式庫模組所需的編碼風格稱為 :pep:`8`。" - -#: ../../faq/programming.rst:114 -msgid "Core Language" -msgstr "核心語言" - -#: ../../faq/programming.rst:119 -msgid "Why am I getting an UnboundLocalError when the variable has a value?" -msgstr "為什麼當變數有值時，我仍得到錯誤訊息 UnboundLocalError？" - -#: ../../faq/programming.rst:121 -#, fuzzy -msgid "" -"It can be a surprise to get the :exc:`UnboundLocalError` in previously " -"working code when it is modified by adding an assignment statement somewhere " -"in the body of a function." -msgstr "" -"當透過在函式主體的某處新增賦值陳述式修改以前的工作程式碼時，在以前的工作程式" -"碼中得到 :exc:`UnboundLocalError` 可能會令人驚訝。" - -#: ../../faq/programming.rst:125 -msgid "This code:" -msgstr "這段程式碼:" - -#: ../../faq/programming.rst:134 -msgid "works, but this code:" -msgstr "可以執行,但是這段程式:" - -#: ../../faq/programming.rst:141 -msgid "results in an :exc:`!UnboundLocalError`:" -msgstr "導致 :exc:`!UnboundLocalError`：" - -#: ../../faq/programming.rst:148 -#, fuzzy -msgid "" -"This is because when you make an assignment to a variable in a scope, that " -"variable becomes local to that scope and shadows any similarly named " -"variable in the outer scope. Since the last statement in foo assigns a new " -"value to ``x``, the compiler recognizes it as a local variable. " -"Consequently when the earlier ``print(x)`` attempts to print the " -"uninitialized local variable and an error results." -msgstr "" -"這是因為當你對作用域中的變數進行賦值時，該變數將成為該作用域的局部變數，並隱" -"藏外部作用域中任何類似命名的變數。由於 foo 中的最後一條陳述式為 ``x`` 分配了" -"一個新值，因此編譯器將其識別為局部變數。因此，當較早的 ``print(x)`` 嘗試印出" -"未初始化的局部變數並產生錯誤時。" - -#: ../../faq/programming.rst:155 -msgid "" -"In the example above you can access the outer scope variable by declaring it " -"global:" -msgstr "在上面的範例中，你可以透過將其聲明為全域變數來存取外部範圍變數：" - -#: ../../faq/programming.rst:167 -#, fuzzy -msgid "" -"This explicit declaration is required in order to remind you that (unlike " -"the superficially analogous situation with class and instance variables) you " -"are actually modifying the value of the variable in the outer scope:" -msgstr "" -"需要此顯式聲明是為了提醒你（與類別和實例變數表面上類似的情況不同）你實際上是" -"在外部範圍內修改變數的值：" - -#: ../../faq/programming.rst:174 -msgid "" -"You can do a similar thing in a nested scope using the :keyword:`nonlocal` " -"keyword:" -msgstr "你可以使用 :keyword:`nonlocal` 關鍵字在巢狀作用域內做類似的事情：" - -#: ../../faq/programming.rst:192 -msgid "What are the rules for local and global variables in Python?" -msgstr "Python 的區域變數和全域變數有什麼規則？" - -#: ../../faq/programming.rst:194 -#, fuzzy -msgid "" -"In Python, variables that are only referenced inside a function are " -"implicitly global. If a variable is assigned a value anywhere within the " -"function's body, it's assumed to be a local unless explicitly declared as " -"global." -msgstr "" -"在 Python 中，僅在函式內部參照的變數是隱式全域變數。如果一個變數在函式體內的" -"任何地方被賦值，除非明確聲明為全域變數，否則它被假定為局部變數。" - -#: ../../faq/programming.rst:198 -#, fuzzy -msgid "" -"Though a bit surprising at first, a moment's consideration explains this. " -"On one hand, requiring :keyword:`global` for assigned variables provides a " -"bar against unintended side-effects. On the other hand, if ``global`` was " -"required for all global references, you'd be using ``global`` all the time. " -"You'd have to declare as global every reference to a built-in function or to " -"a component of an imported module. This clutter would defeat the usefulness " -"of the ``global`` declaration for identifying side-effects." -msgstr "" -"雖然起初有點令人驚訝，但稍加考慮就可以解釋這一點。一方面，要" -"求 :keyword:`global` 分配的變數可以防止意外的副作用。另一方面，如果所有全域參" -"照都需要 ``global``，那麼你將一直使用 ``global``。你必須將對內建函式或引入模" -"組的組件的每個參照聲明為全域。這種混亂會破壞用於識別副作用的 ``global`` 聲明" -"的有用性。" - -#: ../../faq/programming.rst:208 -msgid "" -"Why do lambdas defined in a loop with different values all return the same " -"result?" -msgstr "為什麼以不同的值在迴圈中定義的 lambda 都回傳相同的結果？" - -#: ../../faq/programming.rst:210 -msgid "" -"Assume you use a for loop to define a few different lambdas (or even plain " -"functions), e.g.::" -msgstr "" -"假設你使用 for 迴圈來定義幾個不同的 lambda（甚至是普通函式），例如： ::" - -#: ../../faq/programming.rst:213 -msgid "" -">>> squares = []\n" -">>> for x in range(5):\n" -"... squares.append(lambda: x**2)" -msgstr "" -">>> squares = []\n" -">>> for x in range(5):\n" -"... squares.append(lambda: x**2)" - -#: ../../faq/programming.rst:217 -msgid "" -"This gives you a list that contains 5 lambdas that calculate ``x**2``. You " -"might expect that, when called, they would return, respectively, ``0``, " -"``1``, ``4``, ``9``, and ``16``. However, when you actually try you will " -"see that they all return ``16``::" -msgstr "" -"這會提供一個包含五個計算 ``x**2`` 的 lambda 串列。你可能會預期在呼叫它時，它" -"們會分別回傳 ``0``、``1``、``4``、``9`` 和 ``16``，然而當你實際嘗試你會發現它" -"們都回傳 ``16``： ::" - -#: ../../faq/programming.rst:222 -msgid "" -">>> squares[2]()\n" -"16\n" -">>> squares[4]()\n" -"16" -msgstr "" -">>> squares[2]()\n" -"16\n" -">>> squares[4]()\n" -"16" - -#: ../../faq/programming.rst:227 -msgid "" -"This happens because ``x`` is not local to the lambdas, but is defined in " -"the outer scope, and it is accessed when the lambda is called --- not when " -"it is defined. At the end of the loop, the value of ``x`` is ``4``, so all " -"the functions now return ``4**2``, i.e. ``16``. You can also verify this by " -"changing the value of ``x`` and see how the results of the lambdas change::" -msgstr "" -"發生這種情況是因為 ``x`` 不是 lambda 的局部變數，而是在外部作用域中定義的，且" -"是在呼叫 lambda 時才會存取它，並非於定義時就會存取。在迴圈結束時，``x`` 的值" -"為 ``4``，因此所有函式都回傳 ``4**2``，即為 ``16``。你還可以透過更改 ``x`` 的" -"值來驗證這一點，並查看 lambda 運算式的結果如何變化： ::" - -#: ../../faq/programming.rst:233 -msgid "" -">>> x = 8\n" -">>> squares[2]()\n" -"64" -msgstr "" -">>> x = 8\n" -">>> squares[2]()\n" -"64" - -#: ../../faq/programming.rst:237 -msgid "" -"In order to avoid this, you need to save the values in variables local to " -"the lambdas, so that they don't rely on the value of the global ``x``::" -msgstr "" -"為了避免這種情況，你需要將值保存在 lambda 的局部變數中，這樣它們就不會依賴於" -"全域 ``x`` 的值： ::" - -#: ../../faq/programming.rst:240 -msgid "" -">>> squares = []\n" -">>> for x in range(5):\n" -"... squares.append(lambda n=x: n**2)" -msgstr "" -">>> squares = []\n" -">>> for x in range(5):\n" -"... squares.append(lambda n=x: n**2)" - -#: ../../faq/programming.rst:244 -#, fuzzy -msgid "" -"Here, ``n=x`` creates a new variable ``n`` local to the lambda and computed " -"when the lambda is defined so that it has the same value that ``x`` had at " -"that point in the loop. This means that the value of ``n`` will be ``0`` in " -"the first lambda, ``1`` in the second, ``2`` in the third, and so on. " -"Therefore each lambda will now return the correct result::" -msgstr "" -"在這裡，``n=x`` 建立了一個新變數 ``n`` 局部於 lambda 並在定義 lambda 時計算，" -"因此它具有與 ``x`` 在迴圈中的那個點相同的值。這意味著 ``n`` 的值在第一個 " -"lambda 中為 ``0`` ，在第二個中為 ``1`` ，在第三個中為 ``2`` ，依此類推。因此" -"每個 lambda 現在將回傳正確的結果： ::" - -#: ../../faq/programming.rst:250 -msgid "" -">>> squares[2]()\n" -"4\n" -">>> squares[4]()\n" -"16" -msgstr "" -">>> squares[2]()\n" -"4\n" -">>> squares[4]()\n" -"16" - -#: ../../faq/programming.rst:255 -msgid "" -"Note that this behaviour is not peculiar to lambdas, but applies to regular " -"functions too." -msgstr "請注意，此行為並非 lambda 所特有，也適用於常規函式。" - -#: ../../faq/programming.rst:260 -msgid "How do I share global variables across modules?" -msgstr "如何跨模組共享全域變數？" - -#: ../../faq/programming.rst:262 -#, fuzzy -msgid "" -"The canonical way to share information across modules within a single " -"program is to create a special module (often called config or cfg). Just " -"import the config module in all modules of your application; the module then " -"becomes available as a global name. Because there is only one instance of " -"each module, any changes made to the module object get reflected " -"everywhere. For example:" -msgstr "" -"在單個程式中跨模組共享資訊的規範方法是建立一個特殊模組（通常稱為 config 或 " -"cfg）。只需在應用程式的所有模組中引入配置模組；然後該模組可作為全域名稱使用。" -"因為每個模組只有一個實例，所以對模組物件所做的任何更改都會在各處反映出來。例" -"如：" - -#: ../../faq/programming.rst:268 -msgid "config.py::" -msgstr "config.py： ::" - -#: ../../faq/programming.rst:270 -msgid "x = 0 # Default value of the 'x' configuration setting" -msgstr "x = 0 # 'x' 配置設定的預設值" - -#: ../../faq/programming.rst:272 -msgid "mod.py::" -msgstr "mod.py： ::" - -#: ../../faq/programming.rst:274 -msgid "" -"import config\n" -"config.x = 1" -msgstr "" -"import config\n" -"config.x = 1" - -#: ../../faq/programming.rst:277 -msgid "main.py::" -msgstr "main.py： ::" - -#: ../../faq/programming.rst:279 -msgid "" -"import config\n" -"import mod\n" -"print(config.x)" -msgstr "" -"import config\n" -"import mod\n" -"print(config.x)" - -#: ../../faq/programming.rst:283 -msgid "" -"Note that using a module is also the basis for implementing the singleton " -"design pattern, for the same reason." -msgstr "請注意，出於同樣的原因，使用模組也是實作單例設計模式的基礎。" - -#: ../../faq/programming.rst:288 -msgid "What are the \"best practices\" for using import in a module?" -msgstr "在模組中使用 import 的「最佳實踐」有哪些？" - -#: ../../faq/programming.rst:290 -#, fuzzy -msgid "" -"In general, don't use ``from modulename import *``. Doing so clutters the " -"importer's namespace, and makes it much harder for linters to detect " -"undefined names." -msgstr "" -"一般來說，不要使用``from modulename import *``。這樣做會使引入器的命名空間混" -"亂，並使 linters 更難檢測未定義的名稱。" - -#: ../../faq/programming.rst:294 -#, fuzzy -msgid "" -"Import modules at the top of a file. Doing so makes it clear what other " -"modules your code requires and avoids questions of whether the module name " -"is in scope. Using one import per line makes it easy to add and delete " -"module imports, but using multiple imports per line uses less screen space." -msgstr "" -"在檔案頂部引入模組。這樣做可以明確你的程式碼需要哪些其他模組，並避免模組名稱" -"是否在範圍內的問題。每行使用一個引入可以輕鬆新增和刪除模組引入，但每行使用多" -"個引入會佔用更少的屏幕空間。" - -#: ../../faq/programming.rst:299 -#, fuzzy -msgid "It's good practice if you import modules in the following order:" -msgstr "如果你按以下順序引入模組，這是一個很好的做法：" - -#: ../../faq/programming.rst:301 -msgid "" -"standard library modules -- " -"e.g. :mod:`sys`, :mod:`os`, :mod:`argparse`, :mod:`re`" -msgstr "" -"標準函式庫模組 —— 例如 :mod:`sys`、:mod:`os`、:mod:`argparse`、:mod:`re`" - -#: ../../faq/programming.rst:302 -#, fuzzy -msgid "" -"third-party library modules (anything installed in Python's site-packages " -"directory) -- e.g. :mod:`!dateutil`, :mod:`!requests`, :mod:`!PIL.Image`" -msgstr "" -"第三方函式庫模組（任何安裝在 Python 的站點包目錄中的模組）——例如:mod:`!" -"dateutil`, :mod:`!requests`, :mod:`!PIL.Image`" - -#: ../../faq/programming.rst:304 -msgid "locally developed modules" -msgstr "本地開發的模組" - -#: ../../faq/programming.rst:306 -#, fuzzy -msgid "" -"It is sometimes necessary to move imports to a function or class to avoid " -"problems with circular imports. Gordon McMillan says:" -msgstr "有時需要將引入移動到函式或類別以避免循環引入的問題。戈登麥克米蘭 說：" - -#: ../../faq/programming.rst:309 -#, fuzzy -msgid "" -"Circular imports are fine where both modules use the \"import \" " -"form of import. They fail when the 2nd module wants to grab a name out of " -"the first (\"from module import name\") and the import is at the top level. " -"That's because names in the 1st are not yet available, because the first " -"module is busy importing the 2nd." -msgstr "" -"在兩個模組都使用 \"import \" 引入形式的情況下，循環引入很好。當第二個" -"模組想要從第一個模組中取得一個名稱（ \"from module import name\" ）並且引入位" -"於頂層時，它們會失敗。那是因為 1st 中的名稱尚不可用，因為第一個模組正忙於導" -"入 2nd。" - -#: ../../faq/programming.rst:315 -#, fuzzy -msgid "" -"In this case, if the second module is only used in one function, then the " -"import can easily be moved into that function. By the time the import is " -"called, the first module will have finished initializing, and the second " -"module can do its import." -msgstr "" -"在這種情況下，如果第二個模組只在一個函式中使用，那麼引入可以很容易地移到那個" -"函式中。在呼叫引入時，第一個模組將完成初始化，第二個模組可以進行引入。" - -#: ../../faq/programming.rst:320 -#, fuzzy -msgid "" -"It may also be necessary to move imports out of the top level of code if " -"some of the modules are platform-specific. In that case, it may not even be " -"possible to import all of the modules at the top of the file. In this case, " -"importing the correct modules in the corresponding platform-specific code is " -"a good option." -msgstr "" -"如果某些模組是特定於平台的，則可能還需要將引入移出程式碼的頂層。在這種情況" -"下，甚至可能無法引入檔案頂部的所有模組。在這種情況下，在相應的特定於平台的程" -"式碼中引入正確的模組是一個不錯的選擇。" - -#: ../../faq/programming.rst:325 -#, fuzzy -msgid "" -"Only move imports into a local scope, such as inside a function definition, " -"if it's necessary to solve a problem such as avoiding a circular import or " -"are trying to reduce the initialization time of a module. This technique is " -"especially helpful if many of the imports are unnecessary depending on how " -"the program executes. You may also want to move imports into a function if " -"the modules are only ever used in that function. Note that loading a module " -"the first time may be expensive because of the one time initialization of " -"the module, but loading a module multiple times is virtually free, costing " -"only a couple of dictionary lookups. Even if the module name has gone out " -"of scope, the module is probably available in :data:`sys.modules`." -msgstr "" -"如果有必要解決諸如避免循環引入之類的問題或試圖減少模組的初始化時間，則僅將導" -"入移動到局部範圍內，例如在函式定義內。如果根據程式的執行方式，許多引入是不必" -"要的，則此技術特別有用。如果模組僅在該函式中使用，你可能還想將引入移動到該函" -"式中。請注意，由於模組的一次性初始化，第一次載入模組可能很昂貴，但多次載入模" -"組實際上是免費的，只需幾次字典查詢。即使模組名稱超出範圍，該模組也可能" -"在 :data:`sys.modules` 中可用。" - -#: ../../faq/programming.rst:338 -msgid "Why are default values shared between objects?" -msgstr "為什麼物件之間共享預設值？" - -#: ../../faq/programming.rst:340 -msgid "" -"This type of bug commonly bites neophyte programmers. Consider this " -"function::" -msgstr "這種類型的錯誤通常會困擾新手程式員。像是這個函式： ::" - -#: ../../faq/programming.rst:342 -msgid "" -"def foo(mydict={}): # Danger: shared reference to one dict for all calls\n" -" ... compute something ...\n" -" mydict[key] = value\n" -" return mydict" -msgstr "" -"def foo(mydict={}): # 危險：所有呼叫共享對字典的參照\n" -" ... 計算一些東西 ...\n" -" mydict[key] = value\n" -" return mydict" - -#: ../../faq/programming.rst:347 -msgid "" -"The first time you call this function, ``mydict`` contains a single item. " -"The second time, ``mydict`` contains two items because when ``foo()`` begins " -"executing, ``mydict`` starts out with an item already in it." -msgstr "" -"第一次呼叫此函式時， ``mydict`` 包含一個項目。第二次後 ``mydict`` 包含兩個項" -"目，因為當 ``foo()`` 開始執行時，``mydict`` 以其中已有的項目開始。" - -#: ../../faq/programming.rst:351 -#, fuzzy -msgid "" -"It is often expected that a function call creates new objects for default " -"values. This is not what happens. Default values are created exactly once, " -"when the function is defined. If that object is changed, like the " -"dictionary in this example, subsequent calls to the function will refer to " -"this changed object." -msgstr "" -"通常期望函式呼叫為預設值建立新物件。這不是發生的事情。當定義函式時，預設值只" -"建立一次。如果該物件發生更改，如本例中的字典，則對該函式的後續呼叫將參照該已" -"更改的物件。" - -#: ../../faq/programming.rst:356 -#, fuzzy -msgid "" -"By definition, immutable objects such as numbers, strings, tuples, and " -"``None``, are safe from change. Changes to mutable objects such as " -"dictionaries, lists, and class instances can lead to confusion." -msgstr "" -"根據定義，數字、字串、元組和 ``None`` 等不可變物件是安全的，不會發生變化。對" -"字典、串列和類別實例等可變物件的更改可能會導致混淆。" - -#: ../../faq/programming.rst:360 -msgid "" -"Because of this feature, it is good programming practice to not use mutable " -"objects as default values. Instead, use ``None`` as the default value and " -"inside the function, check if the parameter is ``None`` and create a new " -"list/dictionary/whatever if it is. For example, don't write::" -msgstr "" -"由於這個特性，不使用可變物件作為預設值是一個很好的程式設計習慣，而是應使用 " -"``None`` 作為預設值，並在函式內部檢查參數是否為 ``None``，再建立一個新的串列/" -"字典/或其他東西。例如，不要這樣寫： ::" - -#: ../../faq/programming.rst:365 -msgid "" -"def foo(mydict={}):\n" -" ..." -msgstr "" -"def foo(mydict={}):\n" -" ..." - -#: ../../faq/programming.rst:368 -msgid "but::" -msgstr "而是寫成： ::" - -#: ../../faq/programming.rst:370 -msgid "" -"def foo(mydict=None):\n" -" if mydict is None:\n" -" mydict = {} # create a new dict for local namespace" -msgstr "" -"def foo(mydict=None):\n" -" if mydict is None:\n" -" mydict = {} # 為區域命名空間建立一個新字典" - -#: ../../faq/programming.rst:374 -#, fuzzy -msgid "" -"This feature can be useful. When you have a function that's time-consuming " -"to compute, a common technique is to cache the parameters and the resulting " -"value of each call to the function, and return the cached value if the same " -"value is requested again. This is called \"memoizing\", and can be " -"implemented like this::" -msgstr "" -"此功能可能很有用。當你有一個計算起來很耗時的函式時，一種常用的技術是快取參數" -"和每次呼叫該函式的結果值，並在再次請求相同的值時回傳快取的值。這稱為「記憶" -"化」，可以像這樣實作： ::" - -#: ../../faq/programming.rst:379 -msgid "" -"# Callers can only provide two parameters and optionally pass _cache by " -"keyword\n" -"def expensive(arg1, arg2, *, _cache={}):\n" -" if (arg1, arg2) in _cache:\n" -" return _cache[(arg1, arg2)]\n" -"\n" -" # Calculate the value\n" -" result = ... expensive computation ...\n" -" _cache[(arg1, arg2)] = result # Store result in the cache\n" -" return result" -msgstr "" -"# 呼叫者只能提供兩個參數，並選擇性地透過關鍵字傳遞 _cache\n" -"def expensive(arg1, arg2, *, _cache={}):\n" -" if (arg1, arg2) in _cache:\n" -" return _cache[(arg1, arg2)]\n" -"\n" -" # Calculate the value\n" -" result = ... expensive computation ...\n" -" _cache[(arg1, arg2)] = result # 將結果儲存在快取中\n" -" return result" - -#: ../../faq/programming.rst:389 -msgid "" -"You could use a global variable containing a dictionary instead of the " -"default value; it's a matter of taste." -msgstr "你可以使用包含字典的全域變數而不是預設值；這取決於喜好。" - -#: ../../faq/programming.rst:394 -#, fuzzy -msgid "" -"How can I pass optional or keyword parameters from one function to another?" -msgstr "如何將可選參數或關鍵字參數從一個函式傳遞到另一個函式？" - -#: ../../faq/programming.rst:396 -#, fuzzy -msgid "" -"Collect the arguments using the ``*`` and ``**`` specifiers in the " -"function's parameter list; this gives you the positional arguments as a " -"tuple and the keyword arguments as a dictionary. You can then pass these " -"arguments when calling another function by using ``*`` and ``**``::" -msgstr "" -"在函式的引數list中使用``*`` 和``**`` 說明符收集參數；這為你提供了作為元組的位" -"置引數和作為字典的關鍵字引數。然後，你可以在使用 ``*`` 和 ``**`` 呼叫另一個函" -"式時傳遞這些引數： ::" - -#: ../../faq/programming.rst:401 -msgid "" -"def f(x, *args, **kwargs):\n" -" ...\n" -" kwargs['width'] = '14.3c'\n" -" ...\n" -" g(x, *args, **kwargs)" -msgstr "" -"def f(x, *args, **kwargs):\n" -" ...\n" -" kwargs['width'] = '14.3c'\n" -" ...\n" -" g(x, *args, **kwargs)" - -#: ../../faq/programming.rst:415 -msgid "What is the difference between arguments and parameters?" -msgstr "引數 (arguments) 和參數 (parameters) 有什麼區別？" - -#: ../../faq/programming.rst:417 -msgid "" -":term:`Parameters ` are defined by the names that appear in a " -"function definition, whereas :term:`arguments ` are the values " -"actually passed to a function when calling it. Parameters define " -"what :term:`kind of arguments ` a function can accept. For " -"example, given the function definition::" -msgstr "" -":term:`參數 `\\ 由出現在函式定義中的名稱定義，而\\ :term:`引數 " -"`\\ 是呼叫函式時實際傳遞給函式的值。參數定義函式可以接受的" -"\\ :term:`引數種類 `。例如，給定以下函式定義： ::" - -#: ../../faq/programming.rst:423 -msgid "" -"def func(foo, bar=None, **kwargs):\n" -" pass" -msgstr "" -"def func(foo, bar=None, **kwargs):\n" -" pass" - -#: ../../faq/programming.rst:426 -msgid "" -"*foo*, *bar* and *kwargs* are parameters of ``func``. However, when calling " -"``func``, for example::" -msgstr "" -"*foo*、*bar* 和 *kwargs* 是 ``func`` 的參數。然而當呼叫 ``func`` 時，例" -"如： ::" - -#: ../../faq/programming.rst:429 -msgid "func(42, bar=314, extra=somevar)" -msgstr "func(42, bar=314, extra=somevar)" - -#: ../../faq/programming.rst:431 -msgid "the values ``42``, ``314``, and ``somevar`` are arguments." -msgstr "``42``、``314`` 和 ``somevar`` 是引數。" - -#: ../../faq/programming.rst:435 -msgid "Why did changing list 'y' also change list 'x'?" -msgstr "為什麼更改串列 'y' 也會更改串列 'x'？" - -#: ../../faq/programming.rst:437 -msgid "If you wrote code like::" -msgstr "如果你寫了像這樣的程式碼： ::" - -#: ../../faq/programming.rst:439 -msgid "" -">>> x = []\n" -">>> y = x\n" -">>> y.append(10)\n" -">>> y\n" -"[10]\n" -">>> x\n" -"[10]" -msgstr "" -">>> x = []\n" -">>> y = x\n" -">>> y.append(10)\n" -">>> y\n" -"[10]\n" -">>> x\n" -"[10]" - -#: ../../faq/programming.rst:447 -msgid "" -"you might be wondering why appending an element to ``y`` changed ``x`` too." -msgstr "你可能想知道為什麼將一個元素附加到 ``y`` 時也會改變 ``x``。" - -#: ../../faq/programming.rst:449 -msgid "There are two factors that produce this result:" -msgstr "產生這個結果的原因有兩個：" - -#: ../../faq/programming.rst:451 -#, fuzzy -msgid "" -"Variables are simply names that refer to objects. Doing ``y = x`` doesn't " -"create a copy of the list -- it creates a new variable ``y`` that refers to " -"the same object ``x`` refers to. This means that there is only one object " -"(the list), and both ``x`` and ``y`` refer to it." -msgstr "" -"變數只是參照物件的名稱。執行 ``y = x`` 不會建立list的副本——它會建立一個新變" -"數 ``y``，它指向 ``x`` 指向的同一物件。這意味著只有一個物件（list），並且 " -"``x`` 和 ``y`` 都參照它。" - -#: ../../faq/programming.rst:455 -msgid "" -"Lists are :term:`mutable`, which means that you can change their content." -msgstr "list 是 :term:`mutable`，這意味著你可以變更它們的內容。" - -#: ../../faq/programming.rst:457 -#, fuzzy -msgid "" -"After the call to :meth:`~sequence.append`, the content of the mutable " -"object has changed from ``[]`` to ``[10]``. Since both the variables refer " -"to the same object, using either name accesses the modified value ``[10]``." -msgstr "" -"在呼叫 :meth:`!append` 之後，可變物件的內容從 ``[]`` 變成了 ``[10]``。由於這" -"兩個變數都參照同一個物件，因此使用任一名稱都可以存取修改後的值 ``[10]``。" - -#: ../../faq/programming.rst:461 -msgid "If we instead assign an immutable object to ``x``::" -msgstr "如果我們改為賦予一個不可變物件給 ``x``： ::" - -#: ../../faq/programming.rst:463 -msgid "" -">>> x = 5 # ints are immutable\n" -">>> y = x\n" -">>> x = x + 1 # 5 can't be mutated, we are creating a new object here\n" -">>> x\n" -"6\n" -">>> y\n" -"5" -msgstr "" -">>> x = 5 # 整數為不可變的\n" -">>> y = x\n" -">>> x = x + 1 # 5 不可變，在這邊會建立一個新物件\n" -">>> x\n" -"6\n" -">>> y\n" -"5" - -#: ../../faq/programming.rst:471 -#, fuzzy -msgid "" -"we can see that in this case ``x`` and ``y`` are not equal anymore. This is " -"because integers are :term:`immutable`, and when we do ``x = x + 1`` we are " -"not mutating the int ``5`` by incrementing its value; instead, we are " -"creating a new object (the int ``6``) and assigning it to ``x`` (that is, " -"changing which object ``x`` refers to). After this assignment we have two " -"objects (the ints ``6`` and ``5``) and two variables that refer to them " -"(``x`` now refers to ``6`` but ``y`` still refers to ``5``)." -msgstr "" -"我們可以看到，在這種情況下，``x`` 和 ``y`` 不再相等。這是因為整數是不可變的，" -"當我們做 x = x + 1 時，我們並沒有透過增加它的值來改變 int 5 ；相反，我們正在" -"建立一個新物件（int ``6``）並將其分配給``x``\\ （也就是說，更改``x``指向的物" -"件）。在這個賦值之後，我們有兩個物件（整數 ``6`` 和 ``5``）和兩個參照它們的變" -"數（``x`` 現在指的是 ``6`` 但 ``y`` 仍然指的是``5``）。" - -#: ../../faq/programming.rst:479 -#, fuzzy -msgid "" -"Some operations (for example ``y.append(10)`` and ``y.sort()``) mutate the " -"object, whereas superficially similar operations (for example ``y = y + " -"[10]`` and :func:`sorted(y) `) create a new object. In general in " -"Python (and in all cases in the standard library) a method that mutates an " -"object will return ``None`` to help avoid getting the two types of " -"operations confused. So if you mistakenly write ``y.sort()`` thinking it " -"will give you a sorted copy of ``y``, you'll instead end up with ``None``, " -"which will likely cause your program to generate an easily diagnosed error." -msgstr "" -"一些操作（例如 ``y.append(10)`` 和 ``y.sort()``）會改變物件，而表面上相似的操" -"作（例如 ``y = y + [10]`` 和： func:`sorted(y) `) 建立一個新物件。通" -"常在 Python 中（以及在標準函式庫中的所有情況下）改變物件的方法將回傳 " -"``None`` 以幫助避免混淆這兩種型別的操作。因此，如果你錯誤地編寫了 " -"``y.sort()``，認為它會為你提供 ``y`` 的排序副本，那麼你最終會得到 ``None``，" -"這可能會導致你的程式生成一個容易診斷的錯誤。" - -#: ../../faq/programming.rst:488 -#, fuzzy -msgid "" -"However, there is one class of operations where the same operation sometimes " -"has different behaviors with different types: the augmented assignment " -"operators. For example, ``+=`` mutates lists but not tuples or ints " -"(``a_list += [1, 2, 3]`` is equivalent to ``a_list.extend([1, 2, 3])`` and " -"mutates ``a_list``, whereas ``some_tuple += (1, 2, 3)`` and ``some_int += " -"1`` create new objects)." -msgstr "" -"但是，有一種操作，其中相同的操作有時具有不同型別的不同行為：擴充賦值運算子。" -"例如，``+=`` 改變list而不是元組或整數（``a_list += [1, 2, 3]`` 等同於" -"``a_list.extend([1, 2, 3])``並改變 ``a_list``，而 ``some_tuple += (1, 2, " -"3)`` 和 ``some_int += 1`` 建立新物件）。" - -#: ../../faq/programming.rst:495 -msgid "In other words:" -msgstr "換句話說：" - -#: ../../faq/programming.rst:497 -#, fuzzy -msgid "" -"If we have a mutable object (:class:`list`, :class:`dict`, :class:`set`, " -"etc.), we can use some specific operations to mutate it and all the " -"variables that refer to it will see the change." -msgstr "" -"如果我們有一個可變物件（:class:`list`、:class:`dict`、:class:`set` 等），我們" -"可以使用一些特定的操作來改變它，所有參照它的變數都會看到變化。" - -#: ../../faq/programming.rst:500 -#, fuzzy -msgid "" -"If we have an immutable object (:class:`str`, :class:`int`, :class:`tuple`, " -"etc.), all the variables that refer to it will always see the same value, " -"but operations that transform that value into a new value always return a " -"new object." -msgstr "" -"如果我們有一個不可變物件（:class:`str`、:class:`int`、:class:`tuple` 等），所" -"有參照它的變數將始終看到相同的值，但是轉換的操作將該值轉化為新值總是回傳一個" -"新物件。" - -#: ../../faq/programming.rst:505 -#, fuzzy -msgid "" -"If you want to know if two variables refer to the same object or not, you " -"can use the :keyword:`is` operator, or the built-in function :func:`id`." -msgstr "" -"如果你想知道兩個變數是否參照同一個物件，你可以使用 :keyword:`is` 運算子，或內" -"置函式 :func:`id`。" - -#: ../../faq/programming.rst:510 -msgid "How do I write a function with output parameters (call by reference)?" -msgstr "如何編寫帶有輸出參數的函式（透過傳參照呼叫 (call by reference)）？" - -#: ../../faq/programming.rst:512 -msgid "" -"Remember that arguments are passed by assignment in Python. Since " -"assignment just creates references to objects, there's no alias between an " -"argument name in the caller and callee, and so no call-by-reference per se. " -"You can achieve the desired effect in a number of ways." -msgstr "" -"請記住，在 Python 中引數是透過賦值傳遞的。由於賦值只是建立對物件的參照，因此" -"呼叫者和被呼叫者的引數名稱之間沒有別名，因此本身沒有傳參照呼叫。你可以透過多" -"種方式實作所需的效果。" - -#: ../../faq/programming.rst:517 -msgid "By returning a tuple of the results::" -msgstr "透過回傳結果的元組： ::" - -#: ../../faq/programming.rst:519 -msgid "" -">>> def func1(a, b):\n" -"... a = 'new-value' # a and b are local names\n" -"... b = b + 1 # assigned to new objects\n" -"... return a, b # return new values\n" -"...\n" -">>> x, y = 'old-value', 99\n" -">>> func1(x, y)\n" -"('new-value', 100)" -msgstr "" -">>> def func1(a, b):\n" -"... a = 'new-value' # a 和 b 為區域名稱\n" -"... b = b + 1 # 賦值到新物件\n" -"... return a, b # 回傳新值\n" -"...\n" -">>> x, y = 'old-value', 99\n" -">>> func1(x, y)\n" -"('new-value', 100)" - -#: ../../faq/programming.rst:528 -msgid "This is almost always the clearest solution." -msgstr "這幾乎都會是最清楚的方案。" - -#: ../../faq/programming.rst:530 -msgid "" -"By using global variables. This isn't thread-safe, and is not recommended." -msgstr "透過使用全域變數。這不是執行緒安全的，所以不推薦。" - -#: ../../faq/programming.rst:532 -msgid "By passing a mutable (changeable in-place) object::" -msgstr "透過傳遞一個可變的（可於原地 (in-place) 改變的）物件： ::" - -#: ../../faq/programming.rst:534 -msgid "" -">>> def func2(a):\n" -"... a[0] = 'new-value' # 'a' references a mutable list\n" -"... a[1] = a[1] + 1 # changes a shared object\n" -"...\n" -">>> args = ['old-value', 99]\n" -">>> func2(args)\n" -">>> args\n" -"['new-value', 100]" -msgstr "" -">>> def func2(a):\n" -"... a[0] = 'new-value' # 'a' 參照一個可變的串列\n" -"... a[1] = a[1] + 1 # 改變共享的物件\n" -"...\n" -">>> args = ['old-value', 99]\n" -">>> func2(args)\n" -">>> args\n" -"['new-value', 100]" - -#: ../../faq/programming.rst:543 -msgid "By passing in a dictionary that gets mutated::" -msgstr "透過傳入一個發生改變的字典： ::" - -#: ../../faq/programming.rst:545 -msgid "" -">>> def func3(args):\n" -"... args['a'] = 'new-value' # args is a mutable dictionary\n" -"... args['b'] = args['b'] + 1 # change it in-place\n" -"...\n" -">>> args = {'a': 'old-value', 'b': 99}\n" -">>> func3(args)\n" -">>> args\n" -"{'a': 'new-value', 'b': 100}" -msgstr "" -">>> def func3(args):\n" -"... args['a'] = 'new-value' # args 是可變字典\n" -"... args['b'] = args['b'] + 1 # 原地改變它\n" -"...\n" -">>> args = {'a': 'old-value', 'b': 99}\n" -">>> func3(args)\n" -">>> args\n" -"{'a': 'new-value', 'b': 100}" - -#: ../../faq/programming.rst:554 -msgid "Or bundle up values in a class instance::" -msgstr "或者在類別實例中捆綁值： ::" - -#: ../../faq/programming.rst:556 -msgid "" -">>> class Namespace:\n" -"... def __init__(self, /, **args):\n" -"... for key, value in args.items():\n" -"... setattr(self, key, value)\n" -"...\n" -">>> def func4(args):\n" -"... args.a = 'new-value' # args is a mutable Namespace\n" -"... args.b = args.b + 1 # change object in-place\n" -"...\n" -">>> args = Namespace(a='old-value', b=99)\n" -">>> func4(args)\n" -">>> vars(args)\n" -"{'a': 'new-value', 'b': 100}" -msgstr "" -">>> class Namespace:\n" -"... def __init__(self, /, **args):\n" -"... for key, value in args.items():\n" -"... setattr(self, key, value)\n" -"...\n" -">>> def func4(args):\n" -"... args.a = 'new-value' # args 是可變命名空間\n" -"... args.b = args.b + 1 # 原地改變物件\n" -"...\n" -">>> args = Namespace(a='old-value', b=99)\n" -">>> func4(args)\n" -">>> vars(args)\n" -"{'a': 'new-value', 'b': 100}" - -#: ../../faq/programming.rst:571 -msgid "There's almost never a good reason to get this complicated." -msgstr "幾乎不會有要讓事情變得如此複雜的充分理由。" - -#: ../../faq/programming.rst:573 -msgid "Your best choice is to return a tuple containing the multiple results." -msgstr "你最好的選擇是回傳一個包含多個結果的元組。" - -#: ../../faq/programming.rst:577 -msgid "How do you make a higher order function in Python?" -msgstr "你如何在 Python 中建立高階函式？" - -#: ../../faq/programming.rst:579 -msgid "" -"You have two choices: you can use nested scopes or you can use callable " -"objects. For example, suppose you wanted to define ``linear(a,b)`` which " -"returns a function ``f(x)`` that computes the value ``a*x+b``. Using nested " -"scopes::" -msgstr "" -"你有兩種選擇：可以使用巢狀作用域，也可以使用可呼叫物件。例如，假設你想定義 " -"``linear(a,b)``，它會回傳 ``a*x+b`` 計算值的函式 ``f(x)``。使用巢狀作用" -"域： ::" - -#: ../../faq/programming.rst:583 -msgid "" -"def linear(a, b):\n" -" def result(x):\n" -" return a * x + b\n" -" return result" -msgstr "" -"def linear(a, b):\n" -" def result(x):\n" -" return a * x + b\n" -" return result" - -#: ../../faq/programming.rst:588 -msgid "Or using a callable object::" -msgstr "或者使用可呼叫物件： ::" - -#: ../../faq/programming.rst:590 -msgid "" -"class linear:\n" -"\n" -" def __init__(self, a, b):\n" -" self.a, self.b = a, b\n" -"\n" -" def __call__(self, x):\n" -" return self.a * x + self.b" -msgstr "" -"class linear:\n" -"\n" -" def __init__(self, a, b):\n" -" self.a, self.b = a, b\n" -"\n" -" def __call__(self, x):\n" -" return self.a * x + self.b" - -#: ../../faq/programming.rst:598 -msgid "In both cases, ::" -msgstr "在這兩種情況下： ::" - -#: ../../faq/programming.rst:600 -msgid "taxes = linear(0.3, 2)" -msgstr "taxes = linear(0.3, 2)" - -#: ../../faq/programming.rst:602 -msgid "gives a callable object where ``taxes(10e6) == 0.3 * 10e6 + 2``." -msgstr "給定一個可呼叫物件，其中 ``taxes(10e6) == 0.3 * 10e6 + 2``。" - -#: ../../faq/programming.rst:604 -#, fuzzy -msgid "" -"The callable object approach has the disadvantage that it is a bit slower " -"and results in slightly longer code. However, note that a collection of " -"callables can share their signature via inheritance::" -msgstr "" -"可呼叫物件方法的缺點是它有點慢並且導致程式碼稍長。但是，請注意，可呼叫集合可" -"以透過繼承共享它們的簽名： ::" - -#: ../../faq/programming.rst:608 -msgid "" -"class exponential(linear):\n" -" # __init__ inherited\n" -" def __call__(self, x):\n" -" return self.a * (x ** self.b)" -msgstr "" -"class exponential(linear):\n" -" # __init__ inherited\n" -" def __call__(self, x):\n" -" return self.a * (x ** self.b)" - -#: ../../faq/programming.rst:613 -msgid "Object can encapsulate state for several methods::" -msgstr "物件可以封裝多個方法的狀態： ::" - -#: ../../faq/programming.rst:615 -msgid "" -"class counter:\n" -"\n" -" value = 0\n" -"\n" -" def set(self, x):\n" -" self.value = x\n" -"\n" -" def up(self):\n" -" self.value = self.value + 1\n" -"\n" -" def down(self):\n" -" self.value = self.value - 1\n" -"\n" -"count = counter()\n" -"inc, dec, reset = count.up, count.down, count.set" -msgstr "" -"class counter:\n" -"\n" -" value = 0\n" -"\n" -" def set(self, x):\n" -" self.value = x\n" -"\n" -" def up(self):\n" -" self.value = self.value + 1\n" -"\n" -" def down(self):\n" -" self.value = self.value - 1\n" -"\n" -"count = counter()\n" -"inc, dec, reset = count.up, count.down, count.set" - -#: ../../faq/programming.rst:631 -msgid "" -"Here ``inc()``, ``dec()`` and ``reset()`` act like functions which share the " -"same counting variable." -msgstr "" -"這裡的 ``inc()``、``dec()`` 和 ``reset()`` 就像共享相同計數變數的函式一樣。" - -#: ../../faq/programming.rst:636 -msgid "How do I copy an object in Python?" -msgstr "如何在 Python 中複製物件？" - -#: ../../faq/programming.rst:638 -#, fuzzy -msgid "" -"In general, try :func:`copy.copy` or :func:`copy.deepcopy` for the general " -"case. Not all objects can be copied, but most can." -msgstr "" -"一般來說，對於一般情況，請嘗試 :func:`copy.copy` 或 :func:`copy.deepcopy`。並" -"非所有物件都可以複製，但大多數都可以。" - -#: ../../faq/programming.rst:641 -#, fuzzy -msgid "" -"Some objects can be copied more easily. Dictionaries have " -"a :meth:`~dict.copy` method::" -msgstr "可以更輕鬆地複製某些物件。字典有一個 :meth:`~dict.copy` 方法： ::" - -#: ../../faq/programming.rst:644 -msgid "newdict = olddict.copy()" -msgstr "newdict = olddict.copy()" - -#: ../../faq/programming.rst:646 -msgid "Sequences can be copied by slicing::" -msgstr "序列可以透過切片 (slicing) 複製： ::" - -#: ../../faq/programming.rst:648 -msgid "new_l = l[:]" -msgstr "new_l = l[:]" - -#: ../../faq/programming.rst:652 -msgid "How can I find the methods or attributes of an object?" -msgstr "如何找到物件的方法或屬性？" - -#: ../../faq/programming.rst:654 -#, fuzzy -msgid "" -"For an instance ``x`` of a user-defined class, :func:`dir(x) ` returns " -"an alphabetized list of the names containing the instance attributes and " -"methods and attributes defined by its class." -msgstr "" -"對於使用者定義類別的實例 ``x``，:func:`dir(x) ` 回傳一個按字母順序排列的" -"名稱list，其中包含其類別定義的實例屬性、方法和屬性。" - -#: ../../faq/programming.rst:660 -msgid "How can my code discover the name of an object?" -msgstr "我的程式碼如何發現物件的名稱？" - -#: ../../faq/programming.rst:662 -#, fuzzy -msgid "" -"Generally speaking, it can't, because objects don't really have names. " -"Essentially, assignment always binds a name to a value; the same is true of " -"``def`` and ``class`` statements, but in that case the value is a callable. " -"Consider the following code::" -msgstr "" -"一般來說，它不能，因為物件並沒有真正的名字。本質上，賦值總是將名稱綁定到值； " -"``def`` 和 ``class`` 陳述式也是如此，但在那種情況下，值是可呼叫的。考慮以下程" -"式碼： ::" - -#: ../../faq/programming.rst:667 -msgid "" -">>> class A:\n" -"... pass\n" -"...\n" -">>> B = A\n" -">>> a = B()\n" -">>> b = a\n" -">>> print(b)\n" -"<__main__.A object at 0x16D07CC>\n" -">>> print(a)\n" -"<__main__.A object at 0x16D07CC>" -msgstr "" -">>> class A:\n" -"... pass\n" -"...\n" -">>> B = A\n" -">>> a = B()\n" -">>> b = a\n" -">>> print(b)\n" -"<__main__.A object at 0x16D07CC>\n" -">>> print(a)\n" -"<__main__.A object at 0x16D07CC>" - -#: ../../faq/programming.rst:678 -#, fuzzy -msgid "" -"Arguably the class has a name: even though it is bound to two names and " -"invoked through the name ``B`` the created instance is still reported as an " -"instance of class ``A``. However, it is impossible to say whether the " -"instance's name is ``a`` or ``b``, since both names are bound to the same " -"value." -msgstr "" -"可以說該類別有一個名稱：即使它綁定到兩個名稱並透過名稱 ``B`` 叫用，建立的實例" -"仍然被報告為類別 ``A`` 的實例。但是，無法確定實例的名稱是 ``a`` 還是 ``b`` ，" -"因為這兩個名稱都綁定到相同的值。" - -#: ../../faq/programming.rst:683 -#, fuzzy -msgid "" -"Generally speaking it should not be necessary for your code to \"know the " -"names\" of particular values. Unless you are deliberately writing " -"introspective programs, this is usually an indication that a change of " -"approach might be beneficial." -msgstr "" -"一般來說，你的程式碼不必「知道特定值的名稱」。除非你有意編寫內省程式，否則這" -"通常表明改變方法可能是有益的。" - -#: ../../faq/programming.rst:688 -msgid "" -"In comp.lang.python, Fredrik Lundh once gave an excellent analogy in answer " -"to this question:" -msgstr "" -"在 comp.lang.python 中，Fredrik Lundh 曾針對這個問題給出了一個極好的比喻：" - -#: ../../faq/programming.rst:691 -msgid "" -"The same way as you get the name of that cat you found on your porch: the " -"cat (object) itself cannot tell you its name, and it doesn't really care -- " -"so the only way to find out what it's called is to ask all your neighbours " -"(namespaces) if it's their cat (object)..." -msgstr "" -"就像你在門廊上發現的那隻貓的名字一樣：貓（物件）本身不能告訴你它的名字，它也" -"不關心 - 所以找出它叫什麼的唯一方法是詢問所有鄰居（命名空間）是否是他們的貓" -"（物件）..." - -#: ../../faq/programming.rst:696 -msgid "" -"....and don't be surprised if you'll find that it's known by many names, or " -"no name at all!" -msgstr "....如果你發現它有很多名字，或者根本沒有名字，請不要感到驚訝！" - -#: ../../faq/programming.rst:701 -msgid "What's up with the comma operator's precedence?" -msgstr "逗號運算子的優先級是什麼？" - -#: ../../faq/programming.rst:703 -#, fuzzy -msgid "Comma is not an operator in Python. Consider this session::" -msgstr "逗號不是 Python 中的運算子。考慮這個會話： ::" - -#: ../../faq/programming.rst:705 -msgid "" -">>> \"a\" in \"b\", \"a\"\n" -"(False, 'a')" -msgstr "" -">>> \"a\" in \"b\", \"a\"\n" -"(False, 'a')" - -#: ../../faq/programming.rst:708 -#, fuzzy -msgid "" -"Since the comma is not an operator, but a separator between expressions the " -"above is evaluated as if you had entered::" -msgstr "" -"由於逗號不是運算子，而是運算式之間的分隔符，因此上面的計算就像你輸入的那" -"樣： ::" - -#: ../../faq/programming.rst:711 -msgid "(\"a\" in \"b\"), \"a\"" -msgstr "(\"a\" in \"b\"), \"a\"" - -#: ../../faq/programming.rst:713 -msgid "not::" -msgstr "而不是： ::" - -#: ../../faq/programming.rst:715 -msgid "\"a\" in (\"b\", \"a\")" -msgstr "\"a\" in (\"b\", \"a\")" - -#: ../../faq/programming.rst:717 -#, fuzzy -msgid "" -"The same is true of the various assignment operators (``=``, ``+=`` etc). " -"They are not truly operators but syntactic delimiters in assignment " -"statements." -msgstr "" -"各種賦值運算子（``=``、``+=`` 等）也是如此。它們不是真正的運算子，而是賦值語" -"句中的句法定界符。" - -#: ../../faq/programming.rst:722 -msgid "Is there an equivalent of C's \"?:\" ternary operator?" -msgstr "是否有等效於 C 的 \"?:\" 三元運算子？" - -#: ../../faq/programming.rst:724 -msgid "Yes, there is. The syntax is as follows::" -msgstr "有的，語法如下： ::" - -#: ../../faq/programming.rst:726 -msgid "" -"[on_true] if [expression] else [on_false]\n" -"\n" -"x, y = 50, 25\n" -"small = x if x < y else y" -msgstr "" -"[on_true] if [expression] else [on_false]\n" -"\n" -"x, y = 50, 25\n" -"small = x if x < y else y" - -#: ../../faq/programming.rst:731 -#, fuzzy -msgid "" -"Before this syntax was introduced in Python 2.5, a common idiom was to use " -"logical operators::" -msgstr "" -"在 Python 2.5 中引入此語法之前，一個常見的習慣用法是使用邏輯運算子： ::" - -#: ../../faq/programming.rst:734 -msgid "[expression] and [on_true] or [on_false]" -msgstr "[expression] and [on_true] or [on_false]" - -#: ../../faq/programming.rst:736 -#, fuzzy -msgid "" -"However, this idiom is unsafe, as it can give wrong results when *on_true* " -"has a false boolean value. Therefore, it is always better to use the ``... " -"if ... else ...`` form." -msgstr "" -"然而，這個慣用語是不安全的，因為當 *on_true* 有一個錯誤的布林值時它會給出錯誤" -"的結果。因此，最好使用 ``... if ... else ...`` 形式。" - -#: ../../faq/programming.rst:742 -#, fuzzy -msgid "Is it possible to write obfuscated one-liners in Python?" -msgstr "是否可以在 Python 中編寫混淆的單行程式碼？" - -#: ../../faq/programming.rst:744 -#, fuzzy -msgid "" -"Yes. Usually this is done by nesting :keyword:`lambda` within :keyword:`!" -"lambda`. See the following three examples, slightly adapted from Ulf " -"Bartelt::" -msgstr "" -"是的。通常這是透過在 :keyword:`!lambda` 中嵌套 :keyword:`lambda` 來完成的。請" -"參閱以下三個範例，稍微改編自 Ulf Bartelt： ::" - -#: ../../faq/programming.rst:747 -msgid "" -"from functools import reduce\n" -"\n" -"# Primes < 1000\n" -"print(list(filter(None,map(lambda y:y*reduce(lambda x,y:x*y!=0,\n" -"map(lambda x,y=y:y%x,range(2,int(pow(y,0.5)+1))),1),range(2,1000)))))\n" -"\n" -"# First 10 Fibonacci numbers\n" -"print(list(map(lambda x,f=lambda x,f:(f(x-1,f)+f(x-2,f)) if x>1 else 1:\n" -"f(x,f), range(10))))\n" -"\n" -"# Mandelbrot set\n" -"print((lambda Ru,Ro,Iu,Io,IM,Sx,Sy:reduce(lambda x,y:x+'\\n'+y,map(lambda " -"y,\n" -"Iu=Iu,Io=Io,Ru=Ru,Ro=Ro,Sy=Sy,L=lambda yc,Iu=Iu,Io=Io,Ru=Ru,Ro=Ro,i=IM,\n" -"Sx=Sx,Sy=Sy:reduce(lambda x,y:x+y,map(lambda x,xc=Ru,yc=yc,Ru=Ru,Ro=Ro,\n" -"i=i,Sx=Sx,F=lambda xc,yc,x,y,k,f=lambda xc,yc,x,y,k,f:(k<=0)or (x*x+y*y\n" -">=4.0) or 1+f(xc,yc,x*x-y*y+xc,2.0*x*y+yc,k-1,f):f(xc,yc,x,y,k,f):chr(\n" -"64+F(Ru+x*(Ro-Ru)/Sx,yc,0,0,i)),range(Sx))):L(Iu+y*(Io-Iu)/Sy),range(Sy\n" -"))))(-2.1, 0.7, -1.2, 1.2, 30, 80, 24))\n" -"# \\___ ___/ \\___ ___/ | | |__ lines on screen\n" -"# V V | |______ columns on screen\n" -"# | | |__________ maximum of \"iterations\"\n" -"# | |_________________ range on y axis\n" -"# |____________________________ range on x axis" -msgstr "" - -#: ../../faq/programming.rst:771 -msgid "Don't try this at home, kids!" -msgstr "孩子們，不要在家裡嘗試這個！" - -#: ../../faq/programming.rst:777 -msgid "What does the slash(/) in the parameter list of a function mean?" -msgstr "函式參數串列中的斜線 (/) 是什麼意思？" - -#: ../../faq/programming.rst:779 -#, fuzzy -msgid "" -"A slash in the argument list of a function denotes that the parameters prior " -"to it are positional-only. Positional-only parameters are the ones without " -"an externally usable name. Upon calling a function that accepts positional-" -"only parameters, arguments are mapped to parameters based solely on their " -"position. For example, :func:`divmod` is a function that accepts positional-" -"only parameters. Its documentation looks like this::" -msgstr "" -"函式引數list中的斜線表示它前面的參數是位置參數。僅位置參數是沒有外部可用名稱" -"的參數。在呼叫接受僅位置參數的函式時，參數僅根據其位置對映到參數。例" -"如，:func:`divmod` 是一個只接受位置參數的函式。它的文件看起來像這樣： ::" - -#: ../../faq/programming.rst:786 -msgid "" -">>> help(divmod)\n" -"Help on built-in function divmod in module builtins:\n" -"\n" -"divmod(x, y, /)\n" -" Return the tuple (x//y, x%y). Invariant: div*y + mod == x." -msgstr "" -">>> help(divmod)\n" -"Help on built-in function divmod in module builtins:\n" -"\n" -"divmod(x, y, /)\n" -" Return the tuple (x//y, x%y). Invariant: div*y + mod == x." - -#: ../../faq/programming.rst:792 -msgid "" -"The slash at the end of the parameter list means that both parameters are " -"positional-only. Thus, calling :func:`divmod` with keyword arguments would " -"lead to an error::" -msgstr "" -"參數串列最後的斜線表示兩個參數都是僅限位置參數。因此使用關鍵字引數呼" -"叫 :func:`divmod` 會導致錯誤： ::" - -#: ../../faq/programming.rst:796 -msgid "" -">>> divmod(x=3, y=4)\n" -"Traceback (most recent call last):\n" -" File \"\", line 1, in \n" -"TypeError: divmod() takes no keyword arguments" -msgstr "" -">>> divmod(x=3, y=4)\n" -"Traceback (most recent call last):\n" -" File \"\", line 1, in \n" -"TypeError: divmod() takes no keyword arguments" - -#: ../../faq/programming.rst:803 -msgid "Numbers and strings" -msgstr "數字和字串" - -#: ../../faq/programming.rst:806 -msgid "How do I specify hexadecimal and octal integers?" -msgstr "如何指定十六進位和八進位整數？" - -#: ../../faq/programming.rst:808 -#, fuzzy -msgid "" -"To specify an octal digit, precede the octal value with a zero, and then a " -"lower or uppercase \"o\". For example, to set the variable \"a\" to the " -"octal value \"10\" (8 in decimal), type::" -msgstr "" -"要指定八進位數字，請在八進位值前面加上零，然後是小寫或大寫的 \"o\" 。例如，要" -"將變數 \"a\" 設定為八進位值 \"10\" （十進位為 8），請鍵入： ::" - -#: ../../faq/programming.rst:812 -msgid "" -">>> a = 0o10\n" -">>> a\n" -"8" -msgstr "" -">>> a = 0o10\n" -">>> a\n" -"8" - -#: ../../faq/programming.rst:816 -#, fuzzy -msgid "" -"Hexadecimal is just as easy. Simply precede the hexadecimal number with a " -"zero, and then a lower or uppercase \"x\". Hexadecimal digits can be " -"specified in lower or uppercase. For example, in the Python interpreter::" -msgstr "" -"十六進位也很容易。只需在十六進位數前面加上一個零，然後是一個小寫或大寫的 " -"\"x\" 。可以用小寫或大寫形式指定十六進位數字。例如，在 Python 直譯器中： ::" - -#: ../../faq/programming.rst:820 -msgid "" -">>> a = 0xa5\n" -">>> a\n" -"165\n" -">>> b = 0XB2\n" -">>> b\n" -"178" -msgstr "" -">>> a = 0xa5\n" -">>> a\n" -"165\n" -">>> b = 0XB2\n" -">>> b\n" -"178" - -#: ../../faq/programming.rst:829 -msgid "Why does -22 // 10 return -3?" -msgstr "為什麼 -22 // 10 回傳 -3？" - -#: ../../faq/programming.rst:831 -#, fuzzy -msgid "" -"It's primarily driven by the desire that ``i % j`` have the same sign as " -"``j``. If you want that, and also want::" -msgstr "" -"它主要是由希望 ``i % j`` 與 ``j`` 具有相同的符號驅動的。如果你想要那個，也想" -"要： ::" - -#: ../../faq/programming.rst:834 -msgid "i == (i // j) * j + (i % j)" -msgstr "i == (i // j) * j + (i % j)" - -#: ../../faq/programming.rst:836 -msgid "" -"then integer division has to return the floor. C also requires that " -"identity to hold, and then compilers that truncate ``i // j`` need to make " -"``i % j`` have the same sign as ``i``." -msgstr "" -"那麼整數除法必須回傳向下取整的結果。 C 還要求保留​​該識別性，然後截斷 ``i // " -"j`` 的編譯器需要使 ``i % j`` 具有與 ``i`` 相同的符號。" - -#: ../../faq/programming.rst:840 -#, fuzzy -msgid "" -"There are few real use cases for ``i % j`` when ``j`` is negative. When " -"``j`` is positive, there are many, and in virtually all of them it's more " -"useful for ``i % j`` to be ``>= 0``. If the clock says 10 now, what did it " -"say 200 hours ago? ``-190 % 12 == 2`` is useful; ``-190 % 12 == -10`` is a " -"bug waiting to bite." -msgstr "" -"當 j 為負時，i % j 的實際用例很少。當 ``j`` 為正時，有很多，並且在幾乎所有情" -"況下，``i % j`` 為 ``>= 0`` 更有用。如果時鐘現在是 10 點，那麼 200 小時前它是" -"什麼？ ``-190 % 12 == 2`` 很有用； ``-190 % 12 == -10`` 是一個等著咬人的錯" -"誤。" - -#: ../../faq/programming.rst:848 -#, fuzzy -msgid "How do I get int literal attribute instead of SyntaxError?" -msgstr "如何取得 int 文字屬性而不是 SyntaxError？" - -#: ../../faq/programming.rst:850 -msgid "" -"Trying to lookup an ``int`` literal attribute in the normal manner gives " -"a :exc:`SyntaxError` because the period is seen as a decimal point::" -msgstr "" -"嘗試以正常方式查找 ``int`` 字面值屬性會給出一個 :exc:`SyntaxError`，因為句點" -"被視為小數點： ::" - -#: ../../faq/programming.rst:853 -msgid "" -">>> 1.__class__\n" -" File \"\", line 1\n" -" 1.__class__\n" -" ^\n" -"SyntaxError: invalid decimal literal" -msgstr "" -">>> 1.__class__\n" -" File \"\", line 1\n" -" 1.__class__\n" -" ^\n" -"SyntaxError: invalid decimal literal" - -#: ../../faq/programming.rst:859 -msgid "" -"The solution is to separate the literal from the period with either a space " -"or parentheses." -msgstr "解決方式是用空格或圓括號將字面值與句點分開。" - -#: ../../faq/programming.rst:869 -msgid "How do I convert a string to a number?" -msgstr "如何將字串轉換為數字？" - -#: ../../faq/programming.rst:871 -#, fuzzy -msgid "" -"For integers, use the built-in :func:`int` type constructor, e.g. " -"``int('144') == 144``. Similarly, :func:`float` converts to a floating-" -"point number, e.g. ``float('144') == 144.0``." -msgstr "" -"對於整數，使用內建的 int 型別建構函式，例如``int('144') == 144``。同" -"樣，:func:`float` 轉換為浮點數，例如``浮動（'144'）== 144.0``。" - -#: ../../faq/programming.rst:875 -#, fuzzy -msgid "" -"By default, these interpret the number as decimal, so that ``int('0144') == " -"144`` holds true, and ``int('0x144')`` raises :exc:`ValueError`. " -"``int(string, base)`` takes the base to convert from as a second optional " -"argument, so ``int( '0x144', 16) == 324``. If the base is specified as 0, " -"the number is interpreted using Python's rules: a leading '0o' indicates " -"octal, and '0x' indicates a hex number." -msgstr "" -"預設情況下，這些將數字解釋為十進位，因此 ``int('0144') == 144`` 成立，而 " -"``int('0x144')`` 引發 :exc:`ValueError`。 ``int(string, base)`` 將要轉換的基" -"數作為第二個可選引數，因此 ``int( '0x144', 16) == 324``。如果基數指定為 0，則" -"使用 Python 的規則解釋該數字：前導 \"0o\" 表示八進位， \"0x\" 表示十六進位" -"數。" - -#: ../../faq/programming.rst:882 -#, fuzzy -msgid "" -"Do not use the built-in function :func:`eval` if all you need is to convert " -"strings to numbers. :func:`eval` will be significantly slower and it " -"presents a security risk: someone could pass you a Python expression that " -"might have unwanted side effects. For example, someone could pass " -"``__import__('os').system(\"rm -rf $HOME\")`` which would erase your home " -"directory." -msgstr "" -"如果你只需要將字串轉換為數字，請不要使用內建函式 :func:`eval`。 :func:`eval` " -"會顯著變慢，並且會帶來安全風險：有人可能會向你傳遞一個可能會產生不良副作用的 " -"Python 運算式。例如，有人可以透過 ``__import__('os').system(\"rm -rf " -"$HOME\")`` 來清除你的主目錄。" - -#: ../../faq/programming.rst:889 -#, fuzzy -msgid "" -":func:`eval` also has the effect of interpreting numbers as Python " -"expressions, so that e.g. ``eval('09')`` gives a syntax error because Python " -"does not allow leading '0' in a decimal number (except '0')." -msgstr "" -":func:`eval` 還具有將數字解釋為 Python 運算式的效果，例如``eval('09')`` 會給" -"出語法錯誤，因為 Python 不允許在十進位數中前導 '0'（'0' 除外）。" - -#: ../../faq/programming.rst:895 -msgid "How do I convert a number to a string?" -msgstr "如何將數字轉換為字串？" - -#: ../../faq/programming.rst:897 -#, fuzzy -msgid "" -"To convert, e.g., the number ``144`` to the string ``'144'``, use the built-" -"in type constructor :func:`str`. If you want a hexadecimal or octal " -"representation, use the built-in functions :func:`hex` or :func:`oct`. For " -"fancy formatting, see the :ref:`f-strings` and :ref:`formatstrings` " -"sections, e.g. ``\"{:04d}\".format(144)`` yields ``'0144'`` and ``\"{:.3f}" -"\".format(1.0/3.0)`` yields ``'0.333'``." -msgstr "" -"例如，要將數字 ``144`` 轉換為字串 ``'144'``，請使用內建型別建構函" -"式 :func:`str`。如果你想要十六進製或八進製表示，請使用內建函式 :func:`hex` " -"或 :func:`oct`。對於精美的格式，請參閱:ref:`f-strings` " -"和:ref:`formatstrings` 部分，例如``\"{:04d}\".format(144)`` 產生 ``'0144'`` " -"和 ``\"{:.3f}\".format(1.0/3.0)`` 產生 ``'0.333'`` ." - -#: ../../faq/programming.rst:906 -msgid "How do I modify a string in place?" -msgstr "如何原地修改字串？" - -#: ../../faq/programming.rst:908 -msgid "" -"You can't, because strings are immutable. In most situations, you should " -"simply construct a new string from the various parts you want to assemble it " -"from. However, if you need an object with the ability to modify in-place " -"unicode data, try using an :class:`io.StringIO` object or the :mod:`array` " -"module::" -msgstr "" -"這沒辦法做到，因為字串是不可變的。在大多數情況下，你應以要拿來組裝的各個部分" -"建構出一個新字串。但是如果你需要一個能夠原地修改 unicode 資料的物件，請嘗試使" -"用 :class:`io.StringIO` 物件或 :mod:`array` 模組： ::" - -#: ../../faq/programming.rst:914 -msgid "" -">>> import io\n" -">>> s = \"Hello, world\"\n" -">>> sio = io.StringIO(s)\n" -">>> sio.getvalue()\n" -"'Hello, world'\n" -">>> sio.seek(7)\n" -"7\n" -">>> sio.write(\"there!\")\n" -"6\n" -">>> sio.getvalue()\n" -"'Hello, there!'\n" -"\n" -">>> import array\n" -">>> a = array.array('w', s)\n" -">>> print(a)\n" -"array('w', 'Hello, world')\n" -">>> a[0] = 'y'\n" -">>> print(a)\n" -"array('w', 'yello, world')\n" -">>> a.tounicode()\n" -"'yello, world'" -msgstr "" -">>> import io\n" -">>> s = \"Hello, world\"\n" -">>> sio = io.StringIO(s)\n" -">>> sio.getvalue()\n" -"'Hello, world'\n" -">>> sio.seek(7)\n" -"7\n" -">>> sio.write(\"there!\")\n" -"6\n" -">>> sio.getvalue()\n" -"'Hello, there!'\n" -"\n" -">>> import array\n" -">>> a = array.array('w', s)\n" -">>> print(a)\n" -"array('w', 'Hello, world')\n" -">>> a[0] = 'y'\n" -">>> print(a)\n" -"array('w', 'yello, world')\n" -">>> a.tounicode()\n" -"'yello, world'" - -#: ../../faq/programming.rst:938 -msgid "How do I use strings to call functions/methods?" -msgstr "如何使用字串呼叫函式/方法？" - -#: ../../faq/programming.rst:940 -msgid "There are various techniques." -msgstr "有各式各樣的技法。" - -#: ../../faq/programming.rst:942 -#, fuzzy -msgid "" -"The best is to use a dictionary that maps strings to functions. The primary " -"advantage of this technique is that the strings do not need to match the " -"names of the functions. This is also the primary technique used to emulate " -"a case construct::" -msgstr "" -"最好的方法是使用將字串對映到函式的字典。這種技術的主要優點是字串不需要與函式" -"名稱相匹配。這也是用於模擬案例建構的主要技術： ::" - -#: ../../faq/programming.rst:947 -msgid "" -"def a():\n" -" pass\n" -"\n" -"def b():\n" -" pass\n" -"\n" -"dispatch = {'go': a, 'stop': b} # Note lack of parens for funcs\n" -"\n" -"dispatch[get_input()]() # Note trailing parens to call function" -msgstr "" - -#: ../../faq/programming.rst:957 -msgid "Use the built-in function :func:`getattr`::" -msgstr "使用內建函式 :func:`getattr`： ::" - -#: ../../faq/programming.rst:959 -msgid "" -"import foo\n" -"getattr(foo, 'bar')()" -msgstr "" -"import foo\n" -"getattr(foo, 'bar')()" - -#: ../../faq/programming.rst:962 -msgid "" -"Note that :func:`getattr` works on any object, including classes, class " -"instances, modules, and so on." -msgstr "請注意 :func:`getattr` 適用於任何物件，包括類別、類別實例、模組等。" - -#: ../../faq/programming.rst:965 -msgid "This is used in several places in the standard library, like this::" -msgstr "這在標準函式庫中的幾個地方被使用，如： ::" - -#: ../../faq/programming.rst:967 -msgid "" -"class Foo:\n" -" def do_foo(self):\n" -" ...\n" -"\n" -" def do_bar(self):\n" -" ...\n" -"\n" -"f = getattr(foo_instance, 'do_' + opname)\n" -"f()" -msgstr "" -"class Foo:\n" -" def do_foo(self):\n" -" ...\n" -"\n" -" def do_bar(self):\n" -" ...\n" -"\n" -"f = getattr(foo_instance, 'do_' + opname)\n" -"f()" - -#: ../../faq/programming.rst:978 -msgid "Use :func:`locals` to resolve the function name::" -msgstr "使用 :func:`locals` 解析函式名稱： ::" - -#: ../../faq/programming.rst:980 -msgid "" -"def myFunc():\n" -" print(\"hello\")\n" -"\n" -"fname = \"myFunc\"\n" -"\n" -"f = locals()[fname]\n" -"f()" -msgstr "" -"def myFunc():\n" -" print(\"hello\")\n" -"\n" -"fname = \"myFunc\"\n" -"\n" -"f = locals()[fname]\n" -"f()" - -#: ../../faq/programming.rst:990 -#, fuzzy -msgid "" -"Is there an equivalent to Perl's ``chomp()`` for removing trailing newlines " -"from strings?" -msgstr "" -"是否有與 Perl 的 chomp() 等效的方法，能用於從字串中刪除後綴的換行符號？" - -#: ../../faq/programming.rst:992 -msgid "" -"You can use ``S.rstrip(\"\\r\\n\")`` to remove all occurrences of any line " -"terminator from the end of the string ``S`` without removing other trailing " -"whitespace. If the string ``S`` represents more than one line, with several " -"empty lines at the end, the line terminators for all the blank lines will be " -"removed::" -msgstr "" - -#: ../../faq/programming.rst:998 -msgid "" -">>> lines = (\"line 1 \\r\\n\"\n" -"... \"\\r\\n\"\n" -"... \"\\r\\n\")\n" -">>> lines.rstrip(\"\\n\\r\")\n" -"'line 1 '" -msgstr "" -">>> lines = (\"line 1 \\r\\n\"\n" -"... \"\\r\\n\"\n" -"... \"\\r\\n\")\n" -">>> lines.rstrip(\"\\n\\r\")\n" -"'line 1 '" - -#: ../../faq/programming.rst:1004 -#, fuzzy -msgid "" -"Since this is typically only desired when reading text one line at a time, " -"using ``S.rstrip()`` this way works well." -msgstr "" -"由於這通常只在一次讀取一行文本時才需要，因此使用 ``S.rstrip()`` 這種方式效果" -"很好。" - -#: ../../faq/programming.rst:1009 -#, fuzzy -msgid "Is there a ``scanf()`` or ``sscanf()`` equivalent?" -msgstr "是否有 scanf() 或 sscanf() 的等效方法？" - -#: ../../faq/programming.rst:1011 -#, fuzzy -msgid "Not as such." -msgstr "不是這樣的。" - -#: ../../faq/programming.rst:1013 -#, fuzzy -msgid "" -"For simple input parsing, the easiest approach is usually to split the line " -"into whitespace-delimited words using the :meth:`~str.split` method of " -"string objects and then convert decimal strings to numeric values " -"using :func:`int` or :func:`float`. :meth:`!split` supports an optional " -"\"sep\" parameter which is useful if the line uses something other than " -"whitespace as a separator." -msgstr "" -"對於簡單的輸入解析，最簡單的方法通常是使用字串物件的 :meth:`~str.split` 方法" -"將行拆分為以空格分隔的單詞，然後使用 :func:`int` 或將十進製字串轉換為數" -"值:func:`浮動`。 :meth:`!split` 支援可選的 \"sep\" 參數，如果該行使用空格以外" -"的其他內容作為分隔符，該參數很有用。" - -#: ../../faq/programming.rst:1019 -#, fuzzy -msgid "" -"For more complicated input parsing, regular expressions are more powerful " -"than C's ``sscanf`` and better suited for the task." -msgstr "" -"對於更複雜的輸入解析，正則運算式比 C 的 ``sscanf`` 更強大，更適合這項任務。" - -#: ../../faq/programming.rst:1024 -#, fuzzy -msgid "What does ``UnicodeDecodeError`` or ``UnicodeEncodeError`` error mean?" -msgstr "'UnicodeDecodeError' 或 'UnicodeEncodeErro' 錯誤是什麼意思？" - -#: ../../faq/programming.rst:1026 -msgid "See the :ref:`unicode-howto`." -msgstr "請參閱 :ref:`unicode-howto`。" - -#: ../../faq/programming.rst:1032 -#, fuzzy -msgid "Can I end a raw string with an odd number of backslashes?" -msgstr "我可以用奇數個反斜線結束原始字串嗎？" - -#: ../../faq/programming.rst:1034 -#, fuzzy -msgid "" -"A raw string ending with an odd number of backslashes will escape the " -"string's quote::" -msgstr "以奇數個反斜線結尾的原始字串將跳脫字串的引號： ::" - -#: ../../faq/programming.rst:1036 -msgid "" -">>> r'C:\\this\\will\\not\\work\\'\n" -" File \"\", line 1\n" -" r'C:\\this\\will\\not\\work\\'\n" -" ^\n" -"SyntaxError: unterminated string literal (detected at line 1)" -msgstr "" -">>> r'C:\\this\\will\\not\\work\\'\n" -" File \"\", line 1\n" -" r'C:\\this\\will\\not\\work\\'\n" -" ^\n" -"SyntaxError: unterminated string literal (detected at line 1)" - -#: ../../faq/programming.rst:1042 -#, fuzzy -msgid "" -"There are several workarounds for this. One is to use regular strings and " -"double the backslashes::" -msgstr "有幾種解決方法。一種是使用常規字串並加倍反斜線： ::" - -#: ../../faq/programming.rst:1045 -msgid "" -">>> 'C:\\\\this\\\\will\\\\work\\\\'\n" -"'C:\\\\this\\\\will\\\\work\\\\'" -msgstr "" -">>> 'C:\\\\this\\\\will\\\\work\\\\'\n" -"'C:\\\\this\\\\will\\\\work\\\\'" - -#: ../../faq/programming.rst:1048 -#, fuzzy -msgid "" -"Another is to concatenate a regular string containing an escaped backslash " -"to the raw string::" -msgstr "另一種方法是將包含跳脫反斜線的常規字串連接到原始字串： ::" - -#: ../../faq/programming.rst:1051 -msgid "" -">>> r'C:\\this\\will\\work' '\\\\'\n" -"'C:\\\\this\\\\will\\\\work\\\\'" -msgstr "" -">>> r'C:\\this\\will\\work' '\\\\'\n" -"'C:\\\\this\\\\will\\\\work\\\\'" - -#: ../../faq/programming.rst:1054 -#, fuzzy -msgid "" -"It is also possible to use :func:`os.path.join` to append a backslash on " -"Windows::" -msgstr "也可以使用 :func:`os.path.join` 在 Windows 上附加反斜線： ::" - -#: ../../faq/programming.rst:1056 -msgid "" -">>> os.path.join(r'C:\\this\\will\\work', '')\n" -"'C:\\\\this\\\\will\\\\work\\\\'" -msgstr "" -">>> os.path.join(r'C:\\this\\will\\work', '')\n" -"'C:\\\\this\\\\will\\\\work\\\\'" - -#: ../../faq/programming.rst:1059 -#, fuzzy -msgid "" -"Note that while a backslash will \"escape\" a quote for the purposes of " -"determining where the raw string ends, no escaping occurs when interpreting " -"the value of the raw string. That is, the backslash remains present in the " -"value of the raw string::" -msgstr "" -"請注意，雖然為了確定原始字串的結束位置而使用反斜線「跳脫」引號，但在解釋原始" -"字串的值時不會發生跳脫。也就是說，反斜線仍然存在於原始字串的值中： ::" - -#: ../../faq/programming.rst:1064 -msgid "" -">>> r'backslash\\'preserved'\n" -"\"backslash\\\\'preserved\"" -msgstr "" -">>> r'backslash\\'preserved'\n" -"\"backslash\\\\'preserved\"" - -#: ../../faq/programming.rst:1067 -#, fuzzy -msgid "Also see the specification in the :ref:`language reference `." -msgstr "另請參閱 :ref:`語言參考 ` 中的規範。" - -#: ../../faq/programming.rst:1070 -msgid "Performance" -msgstr "效能" - -#: ../../faq/programming.rst:1073 -msgid "My program is too slow. How do I speed it up?" -msgstr "我的程式太慢了。我該如何加快速度？" - -#: ../../faq/programming.rst:1075 -#, fuzzy -msgid "" -"That's a tough one, in general. First, here are a list of things to " -"remember before diving further:" -msgstr "" -"總的來說，這是一個艱難的過程。首先，這裡列出了在進一步潛水之前要記住的事項：" - -#: ../../faq/programming.rst:1078 -#, fuzzy -msgid "" -"Performance characteristics vary across Python implementations. This FAQ " -"focuses on :term:`CPython`." -msgstr "性能特徵因 Python 實作而異。此 FAQ 重點關注 :term:`CPython`。" - -#: ../../faq/programming.rst:1080 -#, fuzzy -msgid "" -"Behaviour can vary across operating systems, especially when talking about I/" -"O or multi-threading." -msgstr "行為可能因作業系統而異，尤其是在談論 I/O 或多執行緒時。" - -#: ../../faq/programming.rst:1082 -#, fuzzy -msgid "" -"You should always find the hot spots in your program *before* attempting to " -"optimize any code (see the :mod:`profile` module)." -msgstr "" -"在嘗試最佳化任何程式碼\\ *之前*，你應該始終找到程式中的熱點（請參" -"閱 :mod:`profile` 模組）。" - -#: ../../faq/programming.rst:1084 -#, fuzzy -msgid "" -"Writing benchmark scripts will allow you to iterate quickly when searching " -"for improvements (see the :mod:`timeit` module)." -msgstr "" -"編寫基準測試腳本將允許你在搜尋改進時快速疊代（請參閱 :mod:`timeit` 模組）。" - -#: ../../faq/programming.rst:1086 -#, fuzzy -msgid "" -"It is highly recommended to have good code coverage (through unit testing or " -"any other technique) before potentially introducing regressions hidden in " -"sophisticated optimizations." -msgstr "" -"強烈建議在可能引入隱藏在復雜最佳化中的回歸之前擁有良好的程式碼覆蓋率（透過單" -"元測試或任何其他技術）。" - -#: ../../faq/programming.rst:1090 -#, fuzzy -msgid "" -"That being said, there are many tricks to speed up Python code. Here are " -"some general principles which go a long way towards reaching acceptable " -"performance levels:" -msgstr "" -"也就是說，有很多技巧可以加速 Python 程式碼。以下是一些對達到可接受的性能水平" -"大有幫助的一般原則：" - -#: ../../faq/programming.rst:1094 -#, fuzzy -msgid "" -"Making your algorithms faster (or changing to faster ones) can yield much " -"larger benefits than trying to sprinkle micro-optimization tricks all over " -"your code." -msgstr "" -"讓你的演算法更快（或更改為更快的演算法）可以產生比嘗試在你的程式碼中散佈微最" -"佳化技巧大得多的好處。" - -#: ../../faq/programming.rst:1098 -#, fuzzy -msgid "" -"Use the right data structures. Study documentation for the :ref:`bltin-" -"types` and the :mod:`collections` module." -msgstr "" -"使用正確的資料結構。研究 :ref:`bltin-types` 和 :mod:`collections` 模組的文" -"件。" - -#: ../../faq/programming.rst:1101 -#, fuzzy -msgid "" -"When the standard library provides a primitive for doing something, it is " -"likely (although not guaranteed) to be faster than any alternative you may " -"come up with. This is doubly true for primitives written in C, such as " -"builtins and some extension types. For example, be sure to use either " -"the :meth:`list.sort` built-in method or the related :func:`sorted` function " -"to do sorting (and see the :ref:`sortinghowto` for examples of moderately " -"advanced usage)." -msgstr "" -"當標準函式庫提供用於執行某些操作的原語時，它很可能（儘管不能保證）比你可能想" -"出的任何替代方法都更快。對於用 C 編寫的原語，例如內建函式和一些擴充型別，情況" -"更是如此。例如，請務必使用 :meth:`list.sort` 內建方法或相關的 :func:`sorted` " -"函式進行排序（有關高階用法的範例，請參閱 :ref:`sortinghowto` )." - -#: ../../faq/programming.rst:1109 -#, fuzzy -msgid "" -"Abstractions tend to create indirections and force the interpreter to work " -"more. If the levels of indirection outweigh the amount of useful work done, " -"your program will be slower. You should avoid excessive abstraction, " -"especially under the form of tiny functions or methods (which are also often " -"detrimental to readability)." -msgstr "" -"抽象往往會產生間接性並迫使直譯器工作更多。如果間接級別超過了完成的有用工作" -"量，你的程式就會變慢。你應該避免過度抽象，尤其是在微小的函式或方法的形式下" -"（這通常也不利於可讀性）。" - -#: ../../faq/programming.rst:1115 -#, fuzzy -msgid "" -"If you have reached the limit of what pure Python can allow, there are tools " -"to take you further away. For example, `Cython `_ can " -"compile a slightly modified version of Python code into a C extension, and " -"can be used on many different platforms. Cython can take advantage of " -"compilation (and optional type annotations) to make your code significantly " -"faster than when interpreted. If you are confident in your C programming " -"skills, you can also :ref:`write a C extension module ` " -"yourself." -msgstr "" -"如果你已經達到純 Python 所能允許的極限，可以使用一些工具讓你走得更遠。例如，" -"`Cython `_ 可以將稍微修改過的 Python 程式碼編譯成 C 擴" -"充，並且可以在許多不同的平台上使用。Cython 可以利用編譯（和可選的型別註釋）使" -"你的程式碼比解釋時快得多。如果你對自己的 C 程式設計技能有信心，你也可以" -"\\ :ref:`自己編寫一個 C 擴充模組 `。" - -#: ../../faq/programming.rst:1125 -msgid "" -"The wiki page devoted to `performance tips `_." -msgstr "" -"有個 wiki 頁面專門介紹\\ `效能改進小提示 `_。" - -#: ../../faq/programming.rst:1131 -#, fuzzy -msgid "What is the most efficient way to concatenate many strings together?" -msgstr "將多個字串連接在一起的最有效方法是什麼？" - -#: ../../faq/programming.rst:1133 -#, fuzzy -msgid "" -":class:`str` and :class:`bytes` objects are immutable, therefore " -"concatenating many strings together is inefficient as each concatenation " -"creates a new object. In the general case, the total runtime cost is " -"quadratic in the total string length." -msgstr "" -":class:`str` 和 :class:`bytes` 物件是不可變的，因此將多個字串連接在一起效率低" -"下，因為每次連接都會建立一個新物件。在一般情況下，總執行環境 (runtime) 成本是" -"總字串長度的二次方。" - -#: ../../faq/programming.rst:1138 -#, fuzzy -msgid "" -"To accumulate many :class:`str` objects, the recommended idiom is to place " -"them into a list and call :meth:`str.join` at the end::" -msgstr "" -"要累積許多 :class:`str` 物件，推薦的習慣用法是將它們放入list中並在末尾呼" -"叫 :meth:`str.join`： ::" - -#: ../../faq/programming.rst:1141 -msgid "" -"chunks = []\n" -"for s in my_strings:\n" -" chunks.append(s)\n" -"result = ''.join(chunks)" -msgstr "" -"chunks = []\n" -"for s in my_strings:\n" -" chunks.append(s)\n" -"result = ''.join(chunks)" - -#: ../../faq/programming.rst:1146 -#, fuzzy -msgid "(another reasonably efficient idiom is to use :class:`io.StringIO`)" -msgstr "（另一個相當有效的習慣用法是使用 :class:`io.StringIO`）" - -#: ../../faq/programming.rst:1148 -#, fuzzy -msgid "" -"To accumulate many :class:`bytes` objects, the recommended idiom is to " -"extend a :class:`bytearray` object using in-place concatenation (the ``+=`` " -"operator)::" -msgstr "" -"要累積許多 :class:`bytes` 物件，推薦的習慣用法是使用原地連接（``+=`` 運算子）" -"擴充一個 :class:`bytearray` 物件： ::" - -#: ../../faq/programming.rst:1151 -msgid "" -"result = bytearray()\n" -"for b in my_bytes_objects:\n" -" result += b" -msgstr "" -"result = bytearray()\n" -"for b in my_bytes_objects:\n" -" result += b" - -#: ../../faq/programming.rst:1157 -msgid "Sequences (Tuples/Lists)" -msgstr "序列（元組/串列）" - -#: ../../faq/programming.rst:1160 -msgid "How do I convert between tuples and lists?" -msgstr "如何在元組和串列之間進行轉換？" - -#: ../../faq/programming.rst:1162 -msgid "" -"The type constructor ``tuple(seq)`` converts any sequence (actually, any " -"iterable) into a tuple with the same items in the same order." -msgstr "" -"型別建構函式 ``tuple(seq)`` 將任何序列（實際上是任何可疊代物件）轉換為具有相" -"同順序的相同項的元組。" - -#: ../../faq/programming.rst:1165 -#, fuzzy -msgid "" -"For example, ``tuple([1, 2, 3])`` yields ``(1, 2, 3)`` and ``tuple('abc')`` " -"yields ``('a', 'b', 'c')``. If the argument is a tuple, it does not make a " -"copy but returns the same object, so it is cheap to call :func:`tuple` when " -"you aren't sure that an object is already a tuple." -msgstr "" -"例如，``tuple([1, 2, 3])`` 產生 ``(1, 2, 3)`` 而 ``tuple('abc')`` 產生 " -"``('a', 'b ', 'c')``。如果引數是一個元組，它不會復製而是回傳同一個物件，所以" -"當你不確定一個物件是否已經是一個元組時呼叫 :func:`tuple` 是便宜的。" - -#: ../../faq/programming.rst:1170 -#, fuzzy -msgid "" -"The type constructor ``list(seq)`` converts any sequence or iterable into a " -"list with the same items in the same order. For example, ``list((1, 2, " -"3))`` yields ``[1, 2, 3]`` and ``list('abc')`` yields ``['a', 'b', 'c']``. " -"If the argument is a list, it makes a copy just like ``seq[:]`` would." -msgstr "" -"型別建構函式 ``list(seq)`` 將任何序列或可疊代物件轉換為具有相同順序的相同項目" -"的list。例如，``list((1, 2, 3))`` 產生``[1, 2, 3]`` 和``list('abc')`` 產生" -"``['a', 'b ', 'c']``。如果引數是一個list，它會像 ``seq[:]`` 那樣製作一個副" -"本。" - -#: ../../faq/programming.rst:1177 -msgid "What's a negative index?" -msgstr "什麼是負索引？" - -#: ../../faq/programming.rst:1179 -#, fuzzy -msgid "" -"Python sequences are indexed with positive numbers and negative numbers. " -"For positive numbers 0 is the first index 1 is the second index and so " -"forth. For negative indices -1 is the last index and -2 is the penultimate " -"(next to last) index and so forth. Think of ``seq[-n]`` as the same as " -"``seq[len(seq)-n]``." -msgstr "" -"Python 序列使用正數和負數進行索引。對於正數，0 是第一個索引，1 是第二個索引，" -"依此類推。對於負索引，-1 是最後一個索引，-2 是倒數第二個（倒數第二個）索引，" -"依此類推。將 ``seq[-n]`` 視為與 ``seq[len(seq)-n]`` 相同。" - -#: ../../faq/programming.rst:1184 -#, fuzzy -msgid "" -"Using negative indices can be very convenient. For example ``S[:-1]`` is " -"all of the string except for its last character, which is useful for " -"removing the trailing newline from a string." -msgstr "" -"使用負索引會非常方便。例如 ``S[:-1]`` 是除最後一個字元之外的所有字串，這對於" -"從字串中刪除尾隨換行符很有用。" - -#: ../../faq/programming.rst:1190 -#, fuzzy -msgid "How do I iterate over a sequence in reverse order?" -msgstr "如何以相反的順序疊代序列？" - -#: ../../faq/programming.rst:1192 -#, fuzzy -msgid "Use the :func:`reversed` built-in function::" -msgstr "使用 :func:`reversed` 內建函式： ::" - -#: ../../faq/programming.rst:1194 -msgid "" -"for x in reversed(sequence):\n" -" ... # do something with x ..." -msgstr "" - -#: ../../faq/programming.rst:1197 -#, fuzzy -msgid "" -"This won't touch your original sequence, but build a new copy with reversed " -"order to iterate over." -msgstr "這不會觸及你的原始序列，但會構建一個具有相反順序的新副本以進行疊代。" - -#: ../../faq/programming.rst:1202 -msgid "How do you remove duplicates from a list?" -msgstr "如何從串列中刪除重複項？" - -#: ../../faq/programming.rst:1204 -msgid "See the Python Cookbook for a long discussion of many ways to do this:" -msgstr "請參閱 Python Cookbook 以得到有關執行此操作的各種方法的詳細討論：" - -#: ../../faq/programming.rst:1206 -msgid "https://code.activestate.com/recipes/52560/" -msgstr "https://code.activestate.com/recipes/52560/" - -#: ../../faq/programming.rst:1208 -msgid "" -"If you don't mind reordering the list, sort it and then scan from the end of " -"the list, deleting duplicates as you go::" -msgstr "" -"如果你不介意重新排序串列，可以對其進行排序，然後從串列末尾開始掃描，同時刪除" -"重複項： ::" - -#: ../../faq/programming.rst:1211 -msgid "" -"if mylist:\n" -" mylist.sort()\n" -" last = mylist[-1]\n" -" for i in range(len(mylist)-2, -1, -1):\n" -" if last == mylist[i]:\n" -" del mylist[i]\n" -" else:\n" -" last = mylist[i]" -msgstr "" -"if mylist:\n" -" mylist.sort()\n" -" last = mylist[-1]\n" -" for i in range(len(mylist)-2, -1, -1):\n" -" if last == mylist[i]:\n" -" del mylist[i]\n" -" else:\n" -" last = mylist[i]" - -#: ../../faq/programming.rst:1220 -msgid "" -"If all elements of the list may be used as set keys (i.e. they are " -"all :term:`hashable`) this is often faster ::" -msgstr "" -"如果串列的所有元素都可以做為集合的鍵（即它們都必須是 :term:`hashable`），那這" -"通常會更快： ::" - -#: ../../faq/programming.rst:1223 -msgid "mylist = list(set(mylist))" -msgstr "mylist = list(set(mylist))" - -#: ../../faq/programming.rst:1225 -msgid "" -"This converts the list into a set, thereby removing duplicates, and then " -"back into a list." -msgstr "這會將串列轉換為一個集合，從而刪除重複項，然後再轉換回串列。" - -#: ../../faq/programming.rst:1230 -msgid "How do you remove multiple items from a list" -msgstr "如何從串列中刪除多個項目" - -#: ../../faq/programming.rst:1232 -#, fuzzy -msgid "" -"As with removing duplicates, explicitly iterating in reverse with a delete " -"condition is one possibility. However, it is easier and faster to use slice " -"replacement with an implicit or explicit forward iteration. Here are three " -"variations.::" -msgstr "" -"與刪除重複項一樣，使用刪除條件顯式反向疊代是一種可能性。但是，透過隱式或顯式" -"前向疊代使用切片替換更容易和更快。這是三種變體： ::" - -#: ../../faq/programming.rst:1237 -msgid "" -"mylist[:] = filter(keep_function, mylist)\n" -"mylist[:] = (x for x in mylist if keep_condition)\n" -"mylist[:] = [x for x in mylist if keep_condition]" -msgstr "" - -#: ../../faq/programming.rst:1241 -#, fuzzy -msgid "The list comprehension may be fastest." -msgstr "list理解可能是最快的。" - -#: ../../faq/programming.rst:1245 -#, fuzzy -msgid "How do you make an array in Python?" -msgstr "你如何在 Python 中建立數組？" - -#: ../../faq/programming.rst:1247 -#, fuzzy -msgid "Use a list::" -msgstr "使用 list： ::" - -#: ../../faq/programming.rst:1249 -msgid "[\"this\", 1, \"is\", \"an\", \"array\"]" -msgstr "" - -#: ../../faq/programming.rst:1251 -#, fuzzy -msgid "" -"Lists are equivalent to C or Pascal arrays in their time complexity; the " -"primary difference is that a Python list can contain objects of many " -"different types." -msgstr "" -"list在時間複雜度上等同於 C 或 Pascal 數組；主要區別在於 Python list可以包含許" -"多不同型別的物件。" - -#: ../../faq/programming.rst:1254 -#, fuzzy -msgid "" -"The ``array`` module also provides methods for creating arrays of fixed " -"types with compact representations, but they are slower to index than " -"lists. Also note that `NumPy `_ and other third party " -"packages define array-like structures with various characteristics as well." -msgstr "" -"``array`` 模組還提供了建立具有緊湊表示的固定型別數組的方法，但它們的索引速度" -"比list慢。另請注意，`NumPy `_ 和其他第三方包也定義了具有" -"各種特徵的類似數組的結構。" - -#: ../../faq/programming.rst:1260 -#, fuzzy -msgid "" -"To get Lisp-style linked lists, you can emulate *cons cells* using tuples::" -msgstr "要獲得 Lisp 風格的鍊錶，你可以使用元組模擬 *cons cells*： ::" - -#: ../../faq/programming.rst:1262 -msgid "lisp_list = (\"like\", (\"this\", (\"example\", None) ) )" -msgstr "" - -#: ../../faq/programming.rst:1264 -#, fuzzy -msgid "" -"If mutability is desired, you could use lists instead of tuples. Here the " -"analogue of a Lisp *car* is ``lisp_list[0]`` and the analogue of *cdr* is " -"``lisp_list[1]``. Only do this if you're sure you really need to, because " -"it's usually a lot slower than using Python lists." -msgstr "" -"如果需要可變性，你可以使用list而不是元組。這裡 Lisp *car* 的類比是 " -"``lisp_list[0]`` 而 *cdr* 的類比是 ``lisp_list[1]``。只有在確定確實需要時才這" -"樣做，因為它通常比使用 Python list慢很多。" - -#: ../../faq/programming.rst:1273 -msgid "How do I create a multidimensional list?" -msgstr "如何建立多維度串列？" - -#: ../../faq/programming.rst:1275 -msgid "You probably tried to make a multidimensional array like this::" -msgstr "你可能會這樣建立一個多維度陣列： ::" - -#: ../../faq/programming.rst:1277 -msgid ">>> A = [[None] * 2] * 3" -msgstr ">>> A = [[None] * 2] * 3" - -#: ../../faq/programming.rst:1279 -msgid "This looks correct if you print it:" -msgstr "如果你印出它，這看起來是正確的：" - -#: ../../faq/programming.rst:1285 -msgid "" -">>> A\n" -"[[None, None], [None, None], [None, None]]" -msgstr "" -">>> A\n" -"[[None, None], [None, None], [None, None]]" - -#: ../../faq/programming.rst:1290 -msgid "But when you assign a value, it shows up in multiple places:" -msgstr "但是當你賦予一個值時，它會出現在多個地方：" - -#: ../../faq/programming.rst:1296 -msgid "" -">>> A[0][0] = 5\n" -">>> A\n" -"[[5, None], [5, None], [5, None]]" -msgstr "" -">>> A[0][0] = 5\n" -">>> A\n" -"[[5, None], [5, None], [5, None]]" - -#: ../../faq/programming.rst:1302 -msgid "" -"The reason is that replicating a list with ``*`` doesn't create copies, it " -"only creates references to the existing objects. The ``*3`` creates a list " -"containing 3 references to the same list of length two. Changes to one row " -"will show in all rows, which is almost certainly not what you want." -msgstr "" -"原因是複製帶有 ``*`` 的串列不會建立副本，它只會建立對現有物件的參照。``*3`` " -"建立一個串列，其中包含 3 個對長度為 2 的相同串列的參照。對其中一列的變更也將" -"顯示在所有其他列中，而這幾乎不會是你想要的。" - -#: ../../faq/programming.rst:1307 -msgid "" -"The suggested approach is to create a list of the desired length first and " -"then fill in each element with a newly created list::" -msgstr "建議的方法是先建立所需長度的串列，然後用新建立的串列填充每個元素： ::" - -#: ../../faq/programming.rst:1310 -msgid "" -"A = [None] * 3\n" -"for i in range(3):\n" -" A[i] = [None] * 2" -msgstr "" -"A = [None] * 3\n" -"for i in range(3):\n" -" A[i] = [None] * 2" - -#: ../../faq/programming.rst:1314 -msgid "" -"This generates a list containing 3 different lists of length two. You can " -"also use a list comprehension::" -msgstr "" -"這會產生一個包含 3 個長度為 2 的不同串列的串列。你也可以使用串列綜合運算" -"式： ::" - -#: ../../faq/programming.rst:1317 -msgid "" -"w, h = 2, 3\n" -"A = [[None] * w for i in range(h)]" -msgstr "" -"w, h = 2, 3\n" -"A = [[None] * w for i in range(h)]" - -#: ../../faq/programming.rst:1320 -msgid "" -"Or, you can use an extension that provides a matrix datatype; `NumPy " -"`_ is the best known." -msgstr "" -"或者你也可以使用提供矩陣資料型別的擴充套件；`NumPy `_ 是" -"其中最著名的一個。" - -#: ../../faq/programming.rst:1325 -msgid "How do I apply a method or function to a sequence of objects?" -msgstr "如何將方法或函式應用於物件序列？" - -#: ../../faq/programming.rst:1327 -#, fuzzy -msgid "" -"To call a method or function and accumulate the return values is a list, " -"a :term:`list comprehension` is an elegant solution::" -msgstr "" -"呼叫一個方法或函式並累積回傳值是一個list，一個 :term:`list comprehension` 是" -"一個優雅的解決方案： ::" - -#: ../../faq/programming.rst:1330 -msgid "" -"result = [obj.method() for obj in mylist]\n" -"\n" -"result = [function(obj) for obj in mylist]" -msgstr "" -"result = [obj.method() for obj in mylist]\n" -"\n" -"result = [function(obj) for obj in mylist]" - -#: ../../faq/programming.rst:1334 -#, fuzzy -msgid "" -"To just run the method or function without saving the return values, a " -"plain :keyword:`for` loop will suffice::" -msgstr "要只運行方法或函式而不保存回傳值，一個普通的 for 迴圈就足夠了： ::" - -#: ../../faq/programming.rst:1337 -msgid "" -"for obj in mylist:\n" -" obj.method()\n" -"\n" -"for obj in mylist:\n" -" function(obj)" -msgstr "" -"for obj in mylist:\n" -" obj.method()\n" -"\n" -"for obj in mylist:\n" -" function(obj)" - -#: ../../faq/programming.rst:1346 -msgid "" -"Why does a_tuple[i] += ['item'] raise an exception when the addition works?" -msgstr "為什麼 a_tuple[i] += ['item'] 做加法時會引發例外？" - -#: ../../faq/programming.rst:1348 -#, fuzzy -msgid "" -"This is because of a combination of the fact that augmented assignment " -"operators are *assignment* operators, and the difference between mutable and " -"immutable objects in Python." -msgstr "" -"這是因為增強賦值運算子是 *assignment* 運算子這一事實，以及 Python 中可變物件" -"和不可變物件之間的區別。" - -#: ../../faq/programming.rst:1352 -#, fuzzy -msgid "" -"This discussion applies in general when augmented assignment operators are " -"applied to elements of a tuple that point to mutable objects, but we'll use " -"a ``list`` and ``+=`` as our exemplar." -msgstr "" -"當擴充賦值運算子應用於指向可變物件的元組元素時，此討論通常適用，但我們將使用 " -"``list`` 和 ``+=\" 作為範例。" - -#: ../../faq/programming.rst:1356 -msgid "If you wrote::" -msgstr "如果你寫了： ::" - -#: ../../faq/programming.rst:1358 -msgid "" -">>> a_tuple = (1, 2)\n" -">>> a_tuple[0] += 1\n" -"Traceback (most recent call last):\n" -" ...\n" -"TypeError: 'tuple' object does not support item assignment" -msgstr "" -">>> a_tuple = (1, 2)\n" -">>> a_tuple[0] += 1\n" -"Traceback (most recent call last):\n" -" ...\n" -"TypeError: 'tuple' object does not support item assignment" - -#: ../../faq/programming.rst:1364 -#, fuzzy -msgid "" -"The reason for the exception should be immediately clear: ``1`` is added to " -"the object ``a_tuple[0]`` points to (``1``), producing the result object, " -"``2``, but when we attempt to assign the result of the computation, ``2``, " -"to element ``0`` of the tuple, we get an error because we can't change what " -"an element of a tuple points to." -msgstr "" -"例外的原因應該立即清楚：``1`` 被新增到物件``a_tuple[0]`` 指向 (``1``)，產生結" -"果物件，``2``，但是當我們嘗試將計算結果 ``2`` 分配給元組的元素 ``0`` 時，我們" -"會得到一個錯誤，因為我們無法更改元組的元素指向的內容。" - -#: ../../faq/programming.rst:1370 -msgid "" -"Under the covers, what this augmented assignment statement is doing is " -"approximately this::" -msgstr "這個增強賦值陳述式在背後大致是做這些事情： ::" - -#: ../../faq/programming.rst:1373 -msgid "" -">>> result = a_tuple[0] + 1\n" -">>> a_tuple[0] = result\n" -"Traceback (most recent call last):\n" -" ...\n" -"TypeError: 'tuple' object does not support item assignment" -msgstr "" -">>> result = a_tuple[0] + 1\n" -">>> a_tuple[0] = result\n" -"Traceback (most recent call last):\n" -" ...\n" -"TypeError: 'tuple' object does not support item assignment" - -#: ../../faq/programming.rst:1379 -#, fuzzy -msgid "" -"It is the assignment part of the operation that produces the error, since a " -"tuple is immutable." -msgstr "產生錯誤的是操作的賦值部分，因為元組是不可變的。" - -#: ../../faq/programming.rst:1382 -msgid "When you write something like::" -msgstr "當你寫這樣的東西時： ::" - -#: ../../faq/programming.rst:1384 -msgid "" -">>> a_tuple = (['foo'], 'bar')\n" -">>> a_tuple[0] += ['item']\n" -"Traceback (most recent call last):\n" -" ...\n" -"TypeError: 'tuple' object does not support item assignment" -msgstr "" -">>> a_tuple = (['foo'], 'bar')\n" -">>> a_tuple[0] += ['item']\n" -"Traceback (most recent call last):\n" -" ...\n" -"TypeError: 'tuple' object does not support item assignment" - -#: ../../faq/programming.rst:1390 -#, fuzzy -msgid "" -"The exception is a bit more surprising, and even more surprising is the fact " -"that even though there was an error, the append worked::" -msgstr "這個例外有點令人驚訝，更令人驚訝的是即使出現錯誤，追加仍然有效： ::" - -#: ../../faq/programming.rst:1393 -msgid "" -">>> a_tuple[0]\n" -"['foo', 'item']" -msgstr "" -">>> a_tuple[0]\n" -"['foo', 'item']" - -#: ../../faq/programming.rst:1396 -#, fuzzy -msgid "" -"To see why this happens, you need to know that (a) if an object implements " -"an :meth:`~object.__iadd__` magic method, it gets called when the ``+=`` " -"augmented assignment is executed, and its return value is what gets used in " -"the assignment statement; and (b) for lists, :meth:`!__iadd__` is equivalent " -"to calling :meth:`~sequence.extend` on the list and returning the list. " -"That's why we say that for lists, ``+=`` is a \"shorthand\" " -"for :meth:`list.extend`::" -msgstr "" -"要了解為什麼會發生這種情況，你需要知道 (a) 如果一個物件實作了一" -"個 :meth:`~object.__iadd__` 魔術方法，它會在執行 ``+=`` 增廣賦值時被呼叫，並" -"且它的回傳value 是賦值陳述式中使用的值； (b) 對於list，:meth:`!__iadd__` 相當" -"於在list上呼叫 :meth:`!extend` 並回傳list。這就是為什麼我們說對於list，" -"``+=`` 是 :meth:`!list.extend` 的「簡寫」： ::" - -#: ../../faq/programming.rst:1404 -msgid "" -">>> a_list = []\n" -">>> a_list += [1]\n" -">>> a_list\n" -"[1]" -msgstr "" -">>> a_list = []\n" -">>> a_list += [1]\n" -">>> a_list\n" -"[1]" - -#: ../../faq/programming.rst:1409 -msgid "This is equivalent to::" -msgstr "這等價於： ::" - -#: ../../faq/programming.rst:1411 -msgid "" -">>> result = a_list.__iadd__([1])\n" -">>> a_list = result" -msgstr "" -">>> result = a_list.__iadd__([1])\n" -">>> a_list = result" - -#: ../../faq/programming.rst:1414 -#, fuzzy -msgid "" -"The object pointed to by a_list has been mutated, and the pointer to the " -"mutated object is assigned back to ``a_list``. The end result of the " -"assignment is a no-op, since it is a pointer to the same object that " -"``a_list`` was previously pointing to, but the assignment still happens." -msgstr "" -"a_list 指向的物件已經發生變異，指向變異物件的指標被分配回 ``a_list``。賦值的" -"最終結果是空操作，因為它是一個指向與 ``a_list`` 先前指向的同一物件的指標，但" -"賦值仍然發生。" - -#: ../../faq/programming.rst:1419 -msgid "Thus, in our tuple example what is happening is equivalent to::" -msgstr "因此，在我們的元組範例中，發生的事情等同於： ::" - -#: ../../faq/programming.rst:1421 -msgid "" -">>> result = a_tuple[0].__iadd__(['item'])\n" -">>> a_tuple[0] = result\n" -"Traceback (most recent call last):\n" -" ...\n" -"TypeError: 'tuple' object does not support item assignment" -msgstr "" -">>> result = a_tuple[0].__iadd__(['item'])\n" -">>> a_tuple[0] = result\n" -"Traceback (most recent call last):\n" -" ...\n" -"TypeError: 'tuple' object does not support item assignment" - -#: ../../faq/programming.rst:1427 -#, fuzzy -msgid "" -"The :meth:`!__iadd__` succeeds, and thus the list is extended, but even " -"though ``result`` points to the same object that ``a_tuple[0]`` already " -"points to, that final assignment still results in an error, because tuples " -"are immutable." -msgstr "" -":meth:`!__iadd__` 成功，因此list被擴充，但即使 ``result`` 指向與 " -"``a_tuple[0]`` 已經指向的同一個物件，最終的賦值仍然導致一個錯誤，因為元組是不" -"可變的。" - -#: ../../faq/programming.rst:1433 -msgid "" -"I want to do a complicated sort: can you do a Schwartzian Transform in " -"Python?" -msgstr "我想做一個複雜的排序：你能用 Python 做一個 Schwartzian 變換嗎？" - -#: ../../faq/programming.rst:1435 -#, fuzzy -msgid "" -"The technique, attributed to Randal Schwartz of the Perl community, sorts " -"the elements of a list by a metric which maps each element to its \"sort " -"value\". In Python, use the ``key`` argument for the :meth:`list.sort` " -"method::" -msgstr "" -"該技術歸功於 Perl 社區的 Randal Schwartz，它透過將每個元素對映到其「排序值」" -"的度量對串列的元素進行排序。在 Python 中，對 :meth:`list.sort` 方法使用 " -"``key`` 引數： ::" - -#: ../../faq/programming.rst:1439 -msgid "" -"Isorted = L[:]\n" -"Isorted.sort(key=lambda s: int(s[10:15]))" -msgstr "" -"Isorted = L[:]\n" -"Isorted.sort(key=lambda s: int(s[10:15]))" - -#: ../../faq/programming.rst:1444 -msgid "How can I sort one list by values from another list?" -msgstr "如何根據另一個串列中的值對一個串列進行排序？" - -#: ../../faq/programming.rst:1446 -msgid "" -"Merge them into an iterator of tuples, sort the resulting list, and then " -"pick out the element you want. ::" -msgstr "" -"將它們合併到一個元組疊代器中，對結果的串列進行排序，然後挑選出你想要的元" -"素。 ::" - -#: ../../faq/programming.rst:1449 -msgid "" -">>> list1 = [\"what\", \"I'm\", \"sorting\", \"by\"]\n" -">>> list2 = [\"something\", \"else\", \"to\", \"sort\"]\n" -">>> pairs = zip(list1, list2)\n" -">>> pairs = sorted(pairs)\n" -">>> pairs\n" -"[(\"I'm\", 'else'), ('by', 'sort'), ('sorting', 'to'), ('what', " -"'something')]\n" -">>> result = [x[1] for x in pairs]\n" -">>> result\n" -"['else', 'sort', 'to', 'something']" -msgstr "" -">>> list1 = [\"what\", \"I'm\", \"sorting\", \"by\"]\n" -">>> list2 = [\"something\", \"else\", \"to\", \"sort\"]\n" -">>> pairs = zip(list1, list2)\n" -">>> pairs = sorted(pairs)\n" -">>> pairs\n" -"[(\"I'm\", 'else'), ('by', 'sort'), ('sorting', 'to'), ('what', " -"'something')]\n" -">>> result = [x[1] for x in pairs]\n" -">>> result\n" -"['else', 'sort', 'to', 'something']" - -#: ../../faq/programming.rst:1461 -msgid "Objects" -msgstr "物件" - -#: ../../faq/programming.rst:1464 -msgid "What is a class?" -msgstr "什麼是類別 (class)？" - -#: ../../faq/programming.rst:1466 -#, fuzzy -msgid "" -"A class is the particular object type created by executing a class " -"statement. Class objects are used as templates to create instance objects, " -"which embody both the data (attributes) and code (methods) specific to a " -"datatype." -msgstr "" -"類別是透過執行類別陳述式建立的特定物件型別。類別物件用作建立實例物件的模板，" -"實例物件包含特定於資料型別的資料（屬性）和程式碼（方法）。" - -#: ../../faq/programming.rst:1470 -#, fuzzy -msgid "" -"A class can be based on one or more other classes, called its base " -"class(es). It then inherits the attributes and methods of its base classes. " -"This allows an object model to be successively refined by inheritance. You " -"might have a generic ``Mailbox`` class that provides basic accessor methods " -"for a mailbox, and subclasses such as ``MboxMailbox``, ``MaildirMailbox``, " -"``OutlookMailbox`` that handle various specific mailbox formats." -msgstr "" -"一個類別可以基於一個或多個其他類別，稱為它的基底類別。然後它繼承其基底類別的" -"屬性和方法。這允許物件模型透過繼承不斷地細化。你可能有一個通用的 ``Mailbox`` " -"類別，它為郵箱提供基本的存取器方法，以及處理各種特定郵箱格式的子類別，例如 " -"``MboxMailbox`` 、 ``MaildirMailbox`` 、 ``OutlookMailbox`` 。" - -#: ../../faq/programming.rst:1479 -msgid "What is a method?" -msgstr "什麼是方法 (method)？" - -#: ../../faq/programming.rst:1481 -#, fuzzy -msgid "" -"A method is a function on some object ``x`` that you normally call as " -"``x.name(arguments...)``. Methods are defined as functions inside the class " -"definition::" -msgstr "" -"方法是一些物件 ``x`` 上的函式，你通常將其稱為 ``x.name(arguments...)`` 。方法" -"在類別定義中被定義為函式： ::" - -#: ../../faq/programming.rst:1485 -msgid "" -"class C:\n" -" def meth(self, arg):\n" -" return arg * 2 + self.attribute" -msgstr "" -"class C:\n" -" def meth(self, arg):\n" -" return arg * 2 + self.attribute" - -#: ../../faq/programming.rst:1491 -msgid "What is self?" -msgstr "什麼是 self？" - -#: ../../faq/programming.rst:1493 -msgid "" -"Self is merely a conventional name for the first argument of a method. A " -"method defined as ``meth(self, a, b, c)`` should be called as ``x.meth(a, b, " -"c)`` for some instance ``x`` of the class in which the definition occurs; " -"the called method will think it is called as ``meth(x, a, b, c)``." -msgstr "" -"Self 只是方法第一個引數的約定名稱。對於所定義類別的某個實例 ``x``，一個定義" -"為 ``meth(self, a, b, c)`` 的方法應該以 ``x.meth(a, b, c)`` 形式來呼叫；被呼" -"叫的方法會認為它是以 ``meth(x, a, b, c)`` 來呼叫的。" - -#: ../../faq/programming.rst:1498 -msgid "See also :ref:`why-self`." -msgstr "另請參閱 :ref:`why-self`。" - -#: ../../faq/programming.rst:1502 -msgid "" -"How do I check if an object is an instance of a given class or of a subclass " -"of it?" -msgstr "如何檢查物件是否是給定類別的實例或其子類別的實例？" - -#: ../../faq/programming.rst:1504 -#, fuzzy -msgid "" -"Use the built-in function :func:`isinstance(obj, cls) `. You " -"can check if an object is an instance of any of a number of classes by " -"providing a tuple instead of a single class, e.g. ``isinstance(obj, (class1, " -"class2, ...))``, and can also check whether an object is one of Python's " -"built-in types, e.g. ``isinstance(obj, str)`` or ``isinstance(obj, (int, " -"float, complex))``." -msgstr "" -"使用內建函式 :func:`isinstance(obj, cls) `。你可以透過提供元組而" -"不是單個類別來檢查物件是否是多個類別中的任何一個的實例，例如" -"``isinstance(obj, (class1, class2, ...))``，還可以檢查物件是否是 Python 的內" -"置型別之一，例如``isinstance(obj, str)`` 或 ``isinstance(obj, (int, float, " -"complex))``。" - -#: ../../faq/programming.rst:1511 -msgid "" -"Note that :func:`isinstance` also checks for virtual inheritance from " -"an :term:`abstract base class`. So, the test will return ``True`` for a " -"registered class even if hasn't directly or indirectly inherited from it. " -"To test for \"true inheritance\", scan the :term:`MRO` of the class:" -msgstr "" -"請注意，:func:`isinstance` 還會檢查來自\\ :term:`抽象基底類別 (abstract base " -"class) ` 的虛擬繼承。因此對已註冊類別的檢驗會回傳 " -"``True``，即使沒有直接或間接繼承自它。要測試「真正繼承」，請掃描該類別" -"的 :term:`MRO`：" - -#: ../../faq/programming.rst:1516 -msgid "" -"from collections.abc import Mapping\n" -"\n" -"class P:\n" -" pass\n" -"\n" -"class C(P):\n" -" pass\n" -"\n" -"Mapping.register(P)" -msgstr "" -"from collections.abc import Mapping\n" -"\n" -"class P:\n" -" pass\n" -"\n" -"class C(P):\n" -" pass\n" -"\n" -"Mapping.register(P)" - -#: ../../faq/programming.rst:1528 -msgid "" -">>> c = C()\n" -">>> isinstance(c, C) # direct\n" -"True\n" -">>> isinstance(c, P) # indirect\n" -"True\n" -">>> isinstance(c, Mapping) # virtual\n" -"True\n" -"\n" -"# Actual inheritance chain\n" -">>> type(c).__mro__\n" -"(, , )\n" -"\n" -"# Test for \"true inheritance\"\n" -">>> Mapping in type(c).__mro__\n" -"False" -msgstr "" -">>> c = C()\n" -">>> isinstance(c, C) # 直接\n" -"True\n" -">>> isinstance(c, P) # 間接\n" -"True\n" -">>> isinstance(c, Mapping) # 虛擬\n" -"True\n" -"\n" -"# 實際的繼承鏈結\n" -">>> type(c).__mro__\n" -"(, , )\n" -"\n" -"# 「真正繼承」的檢驗\n" -">>> Mapping in type(c).__mro__\n" -"False" - -#: ../../faq/programming.rst:1546 -#, fuzzy -msgid "" -"Note that most programs do not use :func:`isinstance` on user-defined " -"classes very often. If you are developing the classes yourself, a more " -"proper object-oriented style is to define methods on the classes that " -"encapsulate a particular behaviour, instead of checking the object's class " -"and doing a different thing based on what class it is. For example, if you " -"have a function that does something::" -msgstr "" -"請注意，大多數程式不會經常在使用者定義的類別上使用 :func:`isinstance`。如果你" -"自己開發類別，更合適的面向物件風格是在封裝特定行為的類別上定義方法，而不是檢" -"查物件的類別並根據它是什麼類別做不同的事情。例如，如果你有一個函式做某事： ::" - -#: ../../faq/programming.rst:1553 -msgid "" -"def search(obj):\n" -" if isinstance(obj, Mailbox):\n" -" ... # code to search a mailbox\n" -" elif isinstance(obj, Document):\n" -" ... # code to search a document\n" -" elif ..." -msgstr "" -"def search(obj):\n" -" if isinstance(obj, Mailbox):\n" -" ... # 搜尋信箱的程式碼\n" -" elif isinstance(obj, Document):\n" -" ... # 搜尋文件的程式碼\n" -" elif ..." - -#: ../../faq/programming.rst:1560 -msgid "" -"A better approach is to define a ``search()`` method on all the classes and " -"just call it::" -msgstr "更好的方法是在所有類別上定義一個 ``search()`` 方法然後呼叫它： ::" - -#: ../../faq/programming.rst:1563 -msgid "" -"class Mailbox:\n" -" def search(self):\n" -" ... # code to search a mailbox\n" -"\n" -"class Document:\n" -" def search(self):\n" -" ... # code to search a document\n" -"\n" -"obj.search()" -msgstr "" -"class Mailbox:\n" -" def search(self):\n" -" ... # 搜尋信箱的程式碼\n" -"\n" -"class Document:\n" -" def search(self):\n" -" ... # 搜尋文件的程式碼\n" -"\n" -"obj.search()" - -#: ../../faq/programming.rst:1575 -msgid "What is delegation?" -msgstr "什麼是委派 (delegation)？" - -#: ../../faq/programming.rst:1577 -msgid "" -"Delegation is an object oriented technique (also called a design pattern). " -"Let's say you have an object ``x`` and want to change the behaviour of just " -"one of its methods. You can create a new class that provides a new " -"implementation of the method you're interested in changing and delegates all " -"other methods to the corresponding method of ``x``." -msgstr "" -"委派是一種物件導向的技法（也稱為設計模式）。假設你有一個物件 ``x`` 並且只想更" -"改其中一個方法的行為。你可以建立一個新類別，它提供你想改變的那個方法的新實" -"作，並將所有其他方法委派給 ``x`` 的相應方法。" - -#: ../../faq/programming.rst:1583 -msgid "" -"Python programmers can easily implement delegation. For example, the " -"following class implements a class that behaves like a file but converts all " -"written data to uppercase::" -msgstr "" -"Python 程式設計師可以輕鬆地實作委派。舉例來說，以下類別實作了一個行為類似檔案" -"的類別，但將所有寫入的資料轉換為大寫：" - -#: ../../faq/programming.rst:1587 -msgid "" -"class UpperOut:\n" -"\n" -" def __init__(self, outfile):\n" -" self._outfile = outfile\n" -"\n" -" def write(self, s):\n" -" self._outfile.write(s.upper())\n" -"\n" -" def __getattr__(self, name):\n" -" return getattr(self._outfile, name)" -msgstr "" -"class UpperOut:\n" -"\n" -" def __init__(self, outfile):\n" -" self._outfile = outfile\n" -"\n" -" def write(self, s):\n" -" self._outfile.write(s.upper())\n" -"\n" -" def __getattr__(self, name):\n" -" return getattr(self._outfile, name)" - -#: ../../faq/programming.rst:1598 -#, fuzzy -msgid "" -"Here the ``UpperOut`` class redefines the ``write()`` method to convert the " -"argument string to uppercase before calling the underlying " -"``self._outfile.write()`` method. All other methods are delegated to the " -"underlying ``self._outfile`` object. The delegation is accomplished via " -"the :meth:`~object.__getattr__` method; consult :ref:`the language reference " -"` for more information about controlling attribute access." -msgstr "" -"這裡的 ``UpperOut`` 類別重新定義了``write()`` 方法，在呼叫底層的" -"``self._outfile.write()`` 方法之前將引數字串轉換為大寫。所有其他方法都委託給" -"底層的 ``self._outfile`` 物件。委託是透過 :meth:`~object.__getattr__` 方法完" -"成的；有關控制屬性存取的更多資訊，請參閱語言參考 。" - -#: ../../faq/programming.rst:1605 -#, fuzzy -msgid "" -"Note that for more general cases delegation can get trickier. When " -"attributes must be set as well as retrieved, the class must define " -"a :meth:`~object.__setattr__` method too, and it must do so carefully. The " -"basic implementation of :meth:`!__setattr__` is roughly equivalent to the " -"following::" -msgstr "" -"請注意，對於更一般的情況，委託可能會變得更加棘手。當必須設定和檢索屬性時，該" -"類別也必須定義一個 :meth:`~object.__setattr__` 方法，而且必須小心謹" -"慎。 :meth:`!__setattr__` 的基本實作大致等同於以下： ::" - -#: ../../faq/programming.rst:1610 -msgid "" -"class X:\n" -" ...\n" -" def __setattr__(self, name, value):\n" -" self.__dict__[name] = value\n" -" ..." -msgstr "" -"class X:\n" -" ...\n" -" def __setattr__(self, name, value):\n" -" self.__dict__[name] = value\n" -" ..." - -#: ../../faq/programming.rst:1616 -msgid "" -"Many :meth:`~object.__setattr__` implementations call :meth:`!" -"object.__setattr__` to set an attribute on self without causing infinite " -"recursion::" -msgstr "" -"許多 :meth:`~object.__setattr__` 的實作會呼叫 :meth:`!object.__setattr__` 以" -"設定 self 的屬性，而不會導致無限遞迴。" - -#: ../../faq/programming.rst:1619 -msgid "" -"class X:\n" -" def __setattr__(self, name, value):\n" -" # Custom logic here...\n" -" object.__setattr__(self, name, value)" -msgstr "" -"class X:\n" -" def __setattr__(self, name, value):\n" -" # 自訂邏輯放在這裡...\n" -" object.__setattr__(self, name, value)" - -#: ../../faq/programming.rst:1624 -msgid "" -"Alternatively, it is possible to set attributes by inserting entries " -"into :attr:`self.__dict__ ` directly." -msgstr "" - -#: ../../faq/programming.rst:1629 -#, fuzzy -msgid "" -"How do I call a method defined in a base class from a derived class that " -"extends it?" -msgstr "如何從擴充它的衍生類別呼叫基底類別中定義的方法？" - -#: ../../faq/programming.rst:1631 -msgid "Use the built-in :func:`super` function::" -msgstr "使用內建的 :func:`super` 函式： ::" - -#: ../../faq/programming.rst:1633 -msgid "" -"class Derived(Base):\n" -" def meth(self):\n" -" super().meth() # calls Base.meth" -msgstr "" -"class Derived(Base):\n" -" def meth(self):\n" -" super().meth() # 呼叫 Base.meth" - -#: ../../faq/programming.rst:1637 -msgid "" -"In the example, :func:`super` will automatically determine the instance from " -"which it was called (the ``self`` value), look up the :term:`method " -"resolution order` (MRO) with ``type(self).__mro__``, and return the next in " -"line after ``Derived`` in the MRO: ``Base``." -msgstr "" - -#: ../../faq/programming.rst:1644 -msgid "How can I organize my code to make it easier to change the base class?" -msgstr "我可以如何組織我的程式碼以使得更改基底類別變的更容易？" - -#: ../../faq/programming.rst:1646 -#, fuzzy -msgid "" -"You could assign the base class to an alias and derive from the alias. Then " -"all you have to change is the value assigned to the alias. Incidentally, " -"this trick is also handy if you want to decide dynamically (e.g. depending " -"on availability of resources) which base class to use. Example::" -msgstr "" -"你可以將基底類別分配給別名並從別名衍生。然後，你只需更改分配給別名的值。順便" -"說一句，如果你想動態決定（例如，取決於資源的可用性）使用哪個基底類別，這個技" -"巧也很方便。例子： ::" - -#: ../../faq/programming.rst:1651 -msgid "" -"class Base:\n" -" ...\n" -"\n" -"BaseAlias = Base\n" -"\n" -"class Derived(BaseAlias):\n" -" ..." -msgstr "" -"class Base:\n" -" ...\n" -"\n" -"BaseAlias = Base\n" -"\n" -"class Derived(BaseAlias):\n" -" ..." - -#: ../../faq/programming.rst:1661 -msgid "How do I create static class data and static class methods?" -msgstr "如何建立靜態類別資料和靜態類別方法？" - -#: ../../faq/programming.rst:1663 -msgid "" -"Both static data and static methods (in the sense of C++ or Java) are " -"supported in Python." -msgstr "Python 支援靜態資料和靜態方法（在 C++ 或 Java 的意義上）。" - -#: ../../faq/programming.rst:1666 -msgid "" -"For static data, simply define a class attribute. To assign a new value to " -"the attribute, you have to explicitly use the class name in the assignment::" -msgstr "" -"對於靜態資料，只需定義一個類別屬性即可。要為屬性分配新值，你必須在分配中顯式" -"使用類別名稱： ::" - -#: ../../faq/programming.rst:1669 -msgid "" -"class C:\n" -" count = 0 # number of times C.__init__ called\n" -"\n" -" def __init__(self):\n" -" C.count = C.count + 1\n" -"\n" -" def getcount(self):\n" -" return C.count # or return self.count" -msgstr "" -"class C:\n" -" count = 0 # C.__init__ 被呼叫的次數\n" -"\n" -" def __init__(self):\n" -" C.count = C.count + 1\n" -"\n" -" def getcount(self):\n" -" return C.count # 或回傳 self.count" - -#: ../../faq/programming.rst:1678 -msgid "" -"``c.count`` also refers to ``C.count`` for any ``c`` such that " -"``isinstance(c, C)`` holds, unless overridden by ``c`` itself or by some " -"class on the base-class search path from ``c.__class__`` back to ``C``." -msgstr "" -"``c.count`` 還指代任何 ``c`` 的 ``C.count`` 使得 ``isinstance(c, C)`` 成立，" -"除非被 ``c`` 本身或某些人覆蓋從 ``c.__class__`` 回到 ``C`` 的基底類別搜尋路徑" -"上的類別。" - -#: ../../faq/programming.rst:1682 -#, fuzzy -msgid "" -"Caution: within a method of C, an assignment like ``self.count = 42`` " -"creates a new and unrelated instance named \"count\" in ``self``'s own " -"dict. Rebinding of a class-static data name must always specify the class " -"whether inside a method or not::" -msgstr "" -"注意：在 C 的方法中，像 self.count = 42 這樣的賦值會在 self 自己的字典中建立" -"一個名為 \"count\" 的新的不相關實例。類別靜態資料名稱的重新綁定必須始終指定類" -"別是否在方法內： ::" - -#: ../../faq/programming.rst:1687 -msgid "C.count = 314" -msgstr "C.count = 314" - -#: ../../faq/programming.rst:1689 -msgid "Static methods are possible::" -msgstr "靜態方法是可能的： ::" - -#: ../../faq/programming.rst:1691 -msgid "" -"class C:\n" -" @staticmethod\n" -" def static(arg1, arg2, arg3):\n" -" # No 'self' parameter!\n" -" ..." -msgstr "" -"class C:\n" -" @staticmethod\n" -" def static(arg1, arg2, arg3):\n" -" # 沒有 'self' 參數！\n" -" ..." - -#: ../../faq/programming.rst:1697 -#, fuzzy -msgid "" -"However, a far more straightforward way to get the effect of a static method " -"is via a simple module-level function::" -msgstr "" -"然而，獲得靜態方法效果的一種更直接的方法是透過一個簡單的模組級函式： ::" - -#: ../../faq/programming.rst:1700 -msgid "" -"def getcount():\n" -" return C.count" -msgstr "" -"def getcount():\n" -" return C.count" - -#: ../../faq/programming.rst:1703 -#, fuzzy -msgid "" -"If your code is structured so as to define one class (or tightly related " -"class hierarchy) per module, this supplies the desired encapsulation." -msgstr "" -"如果你的程式碼結構化以便為每個模組定義一個類別（或緊密相關的類別層次結構），" -"則這提供了所需的封裝。" - -#: ../../faq/programming.rst:1708 -msgid "How can I overload constructors (or methods) in Python?" -msgstr "如何在 Python 中多載 (overload) 建構函式（或方法）？" - -#: ../../faq/programming.rst:1710 -msgid "" -"This answer actually applies to all methods, but the question usually comes " -"up first in the context of constructors." -msgstr "" -"這個答案實際上適用於所有方法，但這個問題通常會先出現在建構函式的情境中。" - -#: ../../faq/programming.rst:1713 -msgid "In C++ you'd write" -msgstr "在 C++ 中你會寫成" - -#: ../../faq/programming.rst:1715 -msgid "" -"class C {\n" -" C() { cout << \"No arguments\\n\"; }\n" -" C(int i) { cout << \"Argument is \" << i << \"\\n\"; }\n" -"}" -msgstr "" -"class C {\n" -" C() { cout << \"No arguments\\n\"; }\n" -" C(int i) { cout << \"Argument is \" << i << \"\\n\"; }\n" -"}" - -#: ../../faq/programming.rst:1722 -msgid "" -"In Python you have to write a single constructor that catches all cases " -"using default arguments. For example::" -msgstr "" -"在 Python 中，你必須編寫一個建構函式來捕獲所有使用預設引數的情況。例如： ::" - -#: ../../faq/programming.rst:1725 -msgid "" -"class C:\n" -" def __init__(self, i=None):\n" -" if i is None:\n" -" print(\"No arguments\")\n" -" else:\n" -" print(\"Argument is\", i)" -msgstr "" -"class C:\n" -" def __init__(self, i=None):\n" -" if i is None:\n" -" print(\"No arguments\")\n" -" else:\n" -" print(\"Argument is\", i)" - -#: ../../faq/programming.rst:1732 -msgid "This is not entirely equivalent, but close enough in practice." -msgstr "這並不完全等價，但在實際情況中已夠接近。" - -#: ../../faq/programming.rst:1734 -msgid "You could also try a variable-length argument list, e.g. ::" -msgstr "你也可以嘗試長度可變的引數串列，例如： ::" - -#: ../../faq/programming.rst:1736 -msgid "" -"def __init__(self, *args):\n" -" ..." -msgstr "" -"def __init__(self, *args):\n" -" ..." - -#: ../../faq/programming.rst:1739 -msgid "The same approach works for all method definitions." -msgstr "相同的手段適用於所有方法的定義。" - -#: ../../faq/programming.rst:1743 -msgid "I try to use __spam and I get an error about _SomeClassName__spam." -msgstr "我嘗試使用 __spam，但收到有關 _SomeClassName__spam 的錯誤。" - -#: ../../faq/programming.rst:1745 -msgid "" -"Variable names with double leading underscores are \"mangled\" to provide a " -"simple but effective way to define class private variables. Any identifier " -"of the form ``__spam`` (at least two leading underscores, at most one " -"trailing underscore) is textually replaced with ``_classname__spam``, where " -"``classname`` is the current class name with any leading underscores " -"stripped." -msgstr "" -"帶有雙前導底線的變數名會被「破壞 (mangled)」以做為提供定義類別私有變數的一個" -"簡單但有效的方法。``__spam`` 形式的任何識別字（至少兩個前導底線，最多一個尾隨" -"底線）在文字上會被替換為 ``_classname__spam``，其中 ``classname`` 是目前類別" -"之所有前導底線被去除的名稱。" - -#: ../../faq/programming.rst:1751 -msgid "" -"The identifier can be used unchanged within the class, but to access it " -"outside the class, the mangled name must be used:" -msgstr "" - -#: ../../faq/programming.rst:1754 -msgid "" -"class A:\n" -" def __one(self):\n" -" return 1\n" -" def two(self):\n" -" return 2 * self.__one()\n" -"\n" -"class B(A):\n" -" def three(self):\n" -" return 3 * self._A__one()\n" -"\n" -"four = 4 * A()._A__one()" -msgstr "" -"class A:\n" -" def __one(self):\n" -" return 1\n" -" def two(self):\n" -" return 2 * self.__one()\n" -"\n" -"class B(A):\n" -" def three(self):\n" -" return 3 * self._A__one()\n" -"\n" -"four = 4 * A()._A__one()" - -#: ../../faq/programming.rst:1768 -#, fuzzy -msgid "" -"In particular, this does not guarantee privacy since an outside user can " -"still deliberately access the private attribute; many Python programmers " -"never bother to use private variable names at all." -msgstr "" -"這並不能保證隱私：外部使用者仍然可以故意存取 \"_classname__spam\" 屬性，並且" -"私有值在物件的 __dict__ 中可見。許多 Python 程式員根本懶得使用私有變數名。" - -#: ../../faq/programming.rst:1774 -msgid "" -"The :ref:`private name mangling specifications ` for " -"details and special cases." -msgstr "" - -#: ../../faq/programming.rst:1778 -msgid "My class defines __del__ but it is not called when I delete the object." -msgstr "我的類別定義了 __del__ 但是當我刪除物件時它沒有被呼叫。" - -#: ../../faq/programming.rst:1780 -msgid "There are several possible reasons for this." -msgstr "這有幾個可能的原因。" - -#: ../../faq/programming.rst:1782 -msgid "" -"The :keyword:`del` statement does not necessarily " -"call :meth:`~object.__del__` -- it simply decrements the object's reference " -"count, and if this reaches zero :meth:`!__del__` is called." -msgstr "" -":keyword:`del` 陳述式不一定會呼叫 :meth:`~object.__del__` -- 它只是減少物件的" -"參照計數，如果達到零則呼叫 :meth:`!__del__`。" - -#: ../../faq/programming.rst:1786 -#, fuzzy -msgid "" -"If your data structures contain circular links (e.g. a tree where each child " -"has a parent reference and each parent has a list of children) the reference " -"counts will never go back to zero. Once in a while Python runs an algorithm " -"to detect such cycles, but the garbage collector might run some time after " -"the last reference to your data structure vanishes, so your :meth:`!__del__` " -"method may be called at an inconvenient and random time. This is " -"inconvenient if you're trying to reproduce a problem. Worse, the order in " -"which object's :meth:`!__del__` methods are executed is arbitrary. You can " -"run :func:`gc.collect` to force a collection, but there *are* pathological " -"cases where objects will never be collected." -msgstr "" -"如果你的資料結構包含循環鏈接（例如，一棵樹，其中每個子項都有一個父項參照，每" -"個父項都有一個子項list），參照計數將永遠不會回到零。 Python 偶爾會運行一種演" -"算法來檢測此類別循環，但垃圾收集器可能會在對你的資料結構的最後一次參照消失後" -"運行一段時間，因此你的 :meth:`!__del__` 方法可能會在不方便且隨機的時間呼叫.如" -"果你試圖重現問題，這會很不方便。更糟糕的是，物件的 :meth:`!__del__` 方法的執" -"行順序是任意的。你可以運行 :func:`gc.collect` 來強制收集，但*存在*永遠不會收" -"集物件的病態情況。" - -#: ../../faq/programming.rst:1797 -#, fuzzy -msgid "" -"Despite the cycle collector, it's still a good idea to define an explicit " -"``close()`` method on objects to be called whenever you're done with them. " -"The ``close()`` method can then remove attributes that refer to subobjects. " -"Don't call :meth:`!__del__` directly -- :meth:`!__del__` should call " -"``close()`` and ``close()`` should make sure that it can be called more than " -"once for the same object." -msgstr "" -"儘管有循環收集器，但在物件上定義一個顯式的 ``close()`` 方法仍然是一個好主意，" -"以便在你完成使用它們時呼叫它們。然後，``close()`` 方法可以刪除參照子物件的屬" -"性。不要直接呼叫 :meth:`!__del__` -- :meth:`!__del__` 應該呼叫 ``close()`` 並" -"且 ``close()`` 應該確保它可以多次呼叫同一個物件。" - -#: ../../faq/programming.rst:1804 -#, fuzzy -msgid "" -"Another way to avoid cyclical references is to use the :mod:`weakref` " -"module, which allows you to point to objects without incrementing their " -"reference count. Tree data structures, for instance, should use weak " -"references for their parent and sibling references (if they need them!)." -msgstr "" -"另一種避免循環參照的方法是使用 :mod:`weakref` 模組，它允許你在不增加參照計數" -"的情況下指向物件。例如，樹資料結構應該對其父參照和同級參照使用弱參照（如果需" -"要的話！）。" - -#: ../../faq/programming.rst:1817 -msgid "" -"Finally, if your :meth:`!__del__` method raises an exception, a warning " -"message is printed to :data:`sys.stderr`." -msgstr "" -"最後，如果你的 :meth:`!__del__` 方法引發例外，則會將一條警告訊息印出" -"到 :data:`sys.stderr`。" - -#: ../../faq/programming.rst:1822 -msgid "How do I get a list of all instances of a given class?" -msgstr "我該如何取得給定類別的所有實例的串列？" - -#: ../../faq/programming.rst:1824 -msgid "" -"Python does not keep track of all instances of a class (or of a built-in " -"type). You can program the class's constructor to keep track of all " -"instances by keeping a list of weak references to each instance." -msgstr "" -"Python 不會追蹤類別（或內建型別）的所有實例。你可以將類別的建構函式進行改寫，" -"以透過保留對每個實例之弱參照串列來追蹤所有實例。" - -#: ../../faq/programming.rst:1830 -msgid "Why does the result of ``id()`` appear to be not unique?" -msgstr "為什麼 ``id()`` 的結果看起來不唯一？" - -#: ../../faq/programming.rst:1832 -#, fuzzy -msgid "" -"The :func:`id` builtin returns an integer that is guaranteed to be unique " -"during the lifetime of the object. Since in CPython, this is the object's " -"memory address, it happens frequently that after an object is deleted from " -"memory, the next freshly created object is allocated at the same position in " -"memory. This is illustrated by this example:" -msgstr "" -":func:`id` 內建函式回傳一個整數，保證在物件的生命週期內是唯一的。因為在 " -"CPython 中，這是物件的記憶體地址，所以經常發生在從記憶體中刪除一個物件後，下" -"一個新建立的物件被分配在記憶體中的相同位置。這個例子說明了這一點：" - -#: ../../faq/programming.rst:1843 -#, fuzzy -msgid "" -"The two ids belong to different integer objects that are created before, and " -"deleted immediately after execution of the ``id()`` call. To be sure that " -"objects whose id you want to examine are still alive, create another " -"reference to the object:" -msgstr "" -"這兩個 id 屬於之前建立的不同整數物件，並在執行 ``id()`` 呼叫後立即刪除。要確" -"保你要檢查其 id 的物件仍然存在，請建立對該物件的另一個參照：" - -#: ../../faq/programming.rst:1856 -msgid "When can I rely on identity tests with the *is* operator?" -msgstr "我什麼時候可以依靠 *is* 運算子進行識別性測試？" - -#: ../../faq/programming.rst:1858 -msgid "" -"The ``is`` operator tests for object identity. The test ``a is b`` is " -"equivalent to ``id(a) == id(b)``." -msgstr "" -"``is`` 運算子測試物件識別性。測試 ``a is b`` 等同於 ``id(a) == id(b)`` 。" - -#: ../../faq/programming.rst:1861 -msgid "" -"The most important property of an identity test is that an object is always " -"identical to itself, ``a is a`` always returns ``True``. Identity tests are " -"usually faster than equality tests. And unlike equality tests, identity " -"tests are guaranteed to return a boolean ``True`` or ``False``." -msgstr "" -"識別性測試最重要的屬性是物件始終與自身相同， ``a is a`` 總是回傳 ``True`` 。" -"識別性測試通常比相等性測試更快。與相等性測試不同，識別性測試保證回傳布林值 " -"``True`` 或 ``False`` 。" - -#: ../../faq/programming.rst:1866 -msgid "" -"However, identity tests can *only* be substituted for equality tests when " -"object identity is assured. Generally, there are three circumstances where " -"identity is guaranteed:" -msgstr "" -"然而，*只有*\\ 當物件識別性得到保證時，識別性測試才能代替相等性測試。一般來" -"說，保證識別性的情況有以下三種：" - -#: ../../faq/programming.rst:1870 -#, fuzzy -msgid "" -"Assignments create new names but do not change object identity. After the " -"assignment ``new = old``, it is guaranteed that ``new is old``." -msgstr "" -"1) 賦值建立新名稱但不改變物件識別性。賦值 ``new = old`` 後，保證 ``new is " -"old``。" - -#: ../../faq/programming.rst:1873 -#, fuzzy -msgid "" -"Putting an object in a container that stores object references does not " -"change object identity. After the list assignment ``s[0] = x``, it is " -"guaranteed that ``s[0] is x``." -msgstr "" -"2) 將物件放入儲存物件參照的容器中不會改變物件識別性。在 list 賦值 ``s[0] = " -"x`` 之後，保證 ``s[0] 是 x``。" - -#: ../../faq/programming.rst:1877 -#, fuzzy -msgid "" -"If an object is a singleton, it means that only one instance of that object " -"can exist. After the assignments ``a = None`` and ``b = None``, it is " -"guaranteed that ``a is b`` because ``None`` is a singleton." -msgstr "" -"3）如果一個物件是單例，則意味著該物件只能存在一個實例。在賦值 ``a = None`` " -"和 ``b = None`` 之後，可以保證 ``a is b`` 因為 ``None`` 是單例。" - -#: ../../faq/programming.rst:1881 -msgid "" -"In most other circumstances, identity tests are inadvisable and equality " -"tests are preferred. In particular, identity tests should not be used to " -"check constants such as :class:`int` and :class:`str` which aren't " -"guaranteed to be singletons::" -msgstr "" -"在大多數其他情況下，識別性測試是不可取的，相等性測試是首選。特別是，識別性測" -"試不應用於檢查常數，例如不能保證是單例的 :class:`int` 和 :class:`str`： ::" - -#: ../../faq/programming.rst:1886 -msgid "" -">>> a = 1000\n" -">>> b = 500\n" -">>> c = b + 500\n" -">>> a is c\n" -"False\n" -"\n" -">>> a = 'Python'\n" -">>> b = 'Py'\n" -">>> c = b + 'thon'\n" -">>> a is c\n" -"False" -msgstr "" -">>> a = 1000\n" -">>> b = 500\n" -">>> c = b + 500\n" -">>> a is c\n" -"False\n" -"\n" -">>> a = 'Python'\n" -">>> b = 'Py'\n" -">>> c = b + 'thon'\n" -">>> a is c\n" -"False" - -#: ../../faq/programming.rst:1898 -msgid "Likewise, new instances of mutable containers are never identical::" -msgstr "同樣地，可變容器的新實例永遠不會相同： ::" - -#: ../../faq/programming.rst:1900 -msgid "" -">>> a = []\n" -">>> b = []\n" -">>> a is b\n" -"False" -msgstr "" -">>> a = []\n" -">>> b = []\n" -">>> a is b\n" -"False" - -#: ../../faq/programming.rst:1905 -msgid "" -"In the standard library code, you will see several common patterns for " -"correctly using identity tests:" -msgstr "在標準函式庫程式碼中，你將看到幾種正確使用識別性測試的常見模式：" - -#: ../../faq/programming.rst:1908 -msgid "" -"As recommended by :pep:`8`, an identity test is the preferred way to check " -"for ``None``. This reads like plain English in code and avoids confusion " -"with other objects that may have boolean values that evaluate to false." -msgstr "" -"正如 :pep:`8` 所推薦的，識別性測試是檢查 ``None`` 的首選方法。這在程式碼中讀" -"起來像簡單的英語，並避免與其他可能具有評估為 false 的布林值的物件混淆。" - -#: ../../faq/programming.rst:1912 -#, fuzzy -msgid "" -"Detecting optional arguments can be tricky when ``None`` is a valid input " -"value. In those situations, you can create a singleton sentinel object " -"guaranteed to be distinct from other objects. For example, here is how to " -"implement a method that behaves like :meth:`dict.pop`:" -msgstr "" -"當 ``None`` 是有效輸入值時，檢測可選引數可能會很棘手。在這些情況下，你可以建" -"立一個保證與其他物件不同的單例哨兵物件。例如，這裡是如何實作一個行為類似" -"於 :meth:`dict.pop` 的方法：" - -#: ../../faq/programming.rst:1917 -msgid "" -"_sentinel = object()\n" -"\n" -"def pop(self, key, default=_sentinel):\n" -" if key in self:\n" -" value = self[key]\n" -" del self[key]\n" -" return value\n" -" if default is _sentinel:\n" -" raise KeyError(key)\n" -" return default" -msgstr "" -"_sentinel = object()\n" -"\n" -"def pop(self, key, default=_sentinel):\n" -" if key in self:\n" -" value = self[key]\n" -" del self[key]\n" -" return value\n" -" if default is _sentinel:\n" -" raise KeyError(key)\n" -" return default" - -#: ../../faq/programming.rst:1930 -msgid "" -"Container implementations sometimes need to augment equality tests with " -"identity tests. This prevents the code from being confused by objects such " -"as ``float('NaN')`` that are not equal to themselves." -msgstr "" -"容器實作有時需要透過識別性測試來增強相等性測試。這可以防止程式碼被諸如 " -"float('NaN') 之類的不等於自身的物件所混淆。" - -#: ../../faq/programming.rst:1934 -msgid "" -"For example, here is the implementation of :meth:`!" -"collections.abc.Sequence.__contains__`::" -msgstr "" -"例如，以下是 :meth:`!collections.abc.Sequence.__contains__` 的實作： ::" - -#: ../../faq/programming.rst:1937 -msgid "" -"def __contains__(self, value):\n" -" for v in self:\n" -" if v is value or v == value:\n" -" return True\n" -" return False" -msgstr "" -"def __contains__(self, value):\n" -" for v in self:\n" -" if v is value or v == value:\n" -" return True\n" -" return False" - -#: ../../faq/programming.rst:1945 -msgid "" -"How can a subclass control what data is stored in an immutable instance?" -msgstr "子類別如何控制不可變實例中儲存的資料？" - -#: ../../faq/programming.rst:1947 -#, fuzzy -msgid "" -"When subclassing an immutable type, override the :meth:`~object.__new__` " -"method instead of the :meth:`~object.__init__` method. The latter only runs " -"*after* an instance is created, which is too late to alter data in an " -"immutable instance." -msgstr "" -"當對不可變型別進行子類別化時，覆蓋 :meth:`~object.__new__` 方法而不" -"是 :meth:`~object.__init__` 方法。後者僅在*建立實例後*運行，這為時已晚，無法" -"更改不可變實例中的資料。" - -#: ../../faq/programming.rst:1952 -msgid "" -"All of these immutable classes have a different signature than their parent " -"class:" -msgstr "所有這些不可變類別都具有與其父類別不同的簽名：" - -#: ../../faq/programming.rst:1955 -msgid "" -"from datetime import date\n" -"\n" -"class FirstOfMonthDate(date):\n" -" \"Always choose the first day of the month\"\n" -" def __new__(cls, year, month, day):\n" -" return super().__new__(cls, year, month, 1)\n" -"\n" -"class NamedInt(int):\n" -" \"Allow text names for some numbers\"\n" -" xlat = {'zero': 0, 'one': 1, 'ten': 10}\n" -" def __new__(cls, value):\n" -" value = cls.xlat.get(value, value)\n" -" return super().__new__(cls, value)\n" -"\n" -"class TitleStr(str):\n" -" \"Convert str to name suitable for a URL path\"\n" -" def __new__(cls, s):\n" -" s = s.lower().replace(' ', '-')\n" -" s = ''.join([c for c in s if c.isalnum() or c == '-'])\n" -" return super().__new__(cls, s)" -msgstr "" -"from datetime import date\n" -"\n" -"class FirstOfMonthDate(date):\n" -" \"總是選擇每個月的第一天\"\n" -" def __new__(cls, year, month, day):\n" -" return super().__new__(cls, year, month, 1)\n" -"\n" -"class NamedInt(int):\n" -" \"允許一些數字的文字名稱\"\n" -" xlat = {'zero': 0, 'one': 1, 'ten': 10}\n" -" def __new__(cls, value):\n" -" value = cls.xlat.get(value, value)\n" -" return super().__new__(cls, value)\n" -"\n" -"class TitleStr(str):\n" -" \"將 str 轉換成適合作為 URL 路徑的名稱\"\n" -" def __new__(cls, s):\n" -" s = s.lower().replace(' ', '-')\n" -" s = ''.join([c for c in s if c.isalnum() or c == '-'])\n" -" return super().__new__(cls, s)" - -#: ../../faq/programming.rst:1978 -msgid "The classes can be used like this:" -msgstr "這些類別可以像這樣使用：" - -#: ../../faq/programming.rst:1980 -msgid "" -">>> FirstOfMonthDate(2012, 2, 14)\n" -"FirstOfMonthDate(2012, 2, 1)\n" -">>> NamedInt('ten')\n" -"10\n" -">>> NamedInt(20)\n" -"20\n" -">>> TitleStr('Blog: Why Python Rocks')\n" -"'blog-why-python-rocks'" -msgstr "" -">>> FirstOfMonthDate(2012, 2, 14)\n" -"FirstOfMonthDate(2012, 2, 1)\n" -">>> NamedInt('ten')\n" -"10\n" -">>> NamedInt(20)\n" -"20\n" -">>> TitleStr('Blog: Why Python Rocks')\n" -"'blog-why-python-rocks'" - -#: ../../faq/programming.rst:1995 -msgid "How do I cache method calls?" -msgstr "如何快取方法呼叫？" - -#: ../../faq/programming.rst:1997 -#, fuzzy -msgid "" -"The two principal tools for caching methods " -"are :func:`functools.cached_property` and :func:`functools.lru_cache`. The " -"former stores results at the instance level and the latter at the class " -"level." -msgstr "" -"快取方法的兩個主要工具是 func:`functools.cached_property` " -"和 :func:`functools.lru_cache`。前者在實例級別儲存結果，後者在類別級別儲存結" -"果。" - -#: ../../faq/programming.rst:2002 -#, fuzzy -msgid "" -"The *cached_property* approach only works with methods that do not take any " -"arguments. It does not create a reference to the instance. The cached " -"method result will be kept only as long as the instance is alive." -msgstr "" -"*cached_property* 方法僅適用於不帶任何引數的方法，它不會建立對實例的參照，只" -"要實例還活著，快取的方法結果就會被保留。" - -#: ../../faq/programming.rst:2006 -#, fuzzy -msgid "" -"The advantage is that when an instance is no longer used, the cached method " -"result will be released right away. The disadvantage is that if instances " -"accumulate, so too will the accumulated method results. They can grow " -"without bound." -msgstr "" -"好處是當一個實例不再使用時，快取的方法結果會立即釋放。缺點是如果實例累積，累" -"積的方法結果也會累積。他們可以不受限制地成長。" - -#: ../../faq/programming.rst:2011 -msgid "" -"The *lru_cache* approach works with methods that have :term:`hashable` " -"arguments. It creates a reference to the instance unless special efforts " -"are made to pass in weak references." -msgstr "" -"*lru_cache* 方法適用於具有\\ :term:`可雜湊 `\\ 引數的方法。除非特別" -"努力傳遞弱參照，否則它會建立對實例的參照。" - -#: ../../faq/programming.rst:2015 -#, fuzzy -msgid "" -"The advantage of the least recently used algorithm is that the cache is " -"bounded by the specified *maxsize*. The disadvantage is that instances are " -"kept alive until they age out of the cache or until the cache is cleared." -msgstr "" -"最近最少使用演算法的優點是快取受指定的 *maxsize* 限制。缺點是實例會一直保持活" -"動狀態，直到它們從快取中老化或快取被清除。" - -#: ../../faq/programming.rst:2020 -msgid "This example shows the various techniques::" -msgstr "這個例子展示了各種技術： ::" - -#: ../../faq/programming.rst:2022 -msgid "" -"class Weather:\n" -" \"Lookup weather information on a government website\"\n" -"\n" -" def __init__(self, station_id):\n" -" self._station_id = station_id\n" -" # The _station_id is private and immutable\n" -"\n" -" def current_temperature(self):\n" -" \"Latest hourly observation\"\n" -" # Do not cache this because old results\n" -" # can be out of date.\n" -"\n" -" @cached_property\n" -" def location(self):\n" -" \"Return the longitude/latitude coordinates of the station\"\n" -" # Result only depends on the station_id\n" -"\n" -" @lru_cache(maxsize=20)\n" -" def historic_rainfall(self, date, units='mm'):\n" -" \"Rainfall on a given date\"\n" -" # Depends on the station_id, date, and units." -msgstr "" - -#: ../../faq/programming.rst:2044 -#, fuzzy -msgid "" -"The above example assumes that the *station_id* never changes. If the " -"relevant instance attributes are mutable, the *cached_property* approach " -"can't be made to work because it cannot detect changes to the attributes." -msgstr "" -"上面的例子假設 *station_id* 永遠不會改變。如果相關的實例屬性是可變的，則 " -"*cached_property* 方法無法工作，因為它無法檢測到屬性的更改。" - -#: ../../faq/programming.rst:2049 -#, fuzzy -msgid "" -"To make the *lru_cache* approach work when the *station_id* is mutable, the " -"class needs to define the :meth:`~object.__eq__` " -"and :meth:`~object.__hash__` methods so that the cache can detect relevant " -"attribute updates::" -msgstr "" -"要在 *station_id* 可變時使 *lru_cache* 方法起作用，該類別需要定" -"義 :meth:`~object.__eq__` 和 :meth:`~object.__hash__` 方法，以便快取可以檢測" -"相關屬性更新： ::" - -#: ../../faq/programming.rst:2053 -msgid "" -"class Weather:\n" -" \"Example with a mutable station identifier\"\n" -"\n" -" def __init__(self, station_id):\n" -" self.station_id = station_id\n" -"\n" -" def change_station(self, station_id):\n" -" self.station_id = station_id\n" -"\n" -" def __eq__(self, other):\n" -" return self.station_id == other.station_id\n" -"\n" -" def __hash__(self):\n" -" return hash(self.station_id)\n" -"\n" -" @lru_cache(maxsize=20)\n" -" def historic_rainfall(self, date, units='cm'):\n" -" 'Rainfall on a given date'\n" -" # Depends on the station_id, date, and units." -msgstr "" - -#: ../../faq/programming.rst:2075 -msgid "Modules" -msgstr "模組" - -#: ../../faq/programming.rst:2078 -msgid "How do I create a .pyc file?" -msgstr "如何建立 .pyc 檔案？" - -#: ../../faq/programming.rst:2080 -#, fuzzy -msgid "" -"When a module is imported for the first time (or when the source file has " -"changed since the current compiled file was created) a ``.pyc`` file " -"containing the compiled code should be created in a ``__pycache__`` " -"subdirectory of the directory containing the ``.py`` file. The ``.pyc`` " -"file will have a filename that starts with the same name as the ``.py`` " -"file, and ends with ``.pyc``, with a middle component that depends on the " -"particular ``python`` binary that created it. (See :pep:`3147` for details.)" -msgstr "" -"第一次引入模組時（或者源檔案自建立目前編譯檔案後發生更改時）應在 " -"``__pycache__`` 的子目錄中建立包含編譯程式碼的 ``.pyc`` 檔案包含 .py 檔案的目" -"錄。 ``.pyc`` 檔案的檔案名以與``.py`` 檔案相同的名稱開頭，以``.pyc`` 結尾，中" -"間部分依賴於特定的``python `` 建立它的二進製檔案。（有關詳細資訊，請參" -"閱 :pep:`3147`。）" - -#: ../../faq/programming.rst:2088 -#, fuzzy -msgid "" -"One reason that a ``.pyc`` file may not be created is a permissions problem " -"with the directory containing the source file, meaning that the " -"``__pycache__`` subdirectory cannot be created. This can happen, for " -"example, if you develop as one user but run as another, such as if you are " -"testing with a web server." -msgstr "" -"無法建立 .pyc 檔案的原因之一是包含源檔案的目錄存在權限問題，這意味著無法建立 " -"__pycache__ 子目錄。例如，如果你以一個使用者的身份開發但以另一個使用者的身份" -"運行，例如你正在使用 Web 伺服器進行測試，就會發生這種情況。" - -#: ../../faq/programming.rst:2093 -#, fuzzy -msgid "" -"Unless the :envvar:`PYTHONDONTWRITEBYTECODE` environment variable is set, " -"creation of a .pyc file is automatic if you're importing a module and Python " -"has the ability (permissions, free space, etc...) to create a " -"``__pycache__`` subdirectory and write the compiled module to that " -"subdirectory." -msgstr "" -"除非 :envvar:`PYTHONDONTWRITEBYTECODE` 環境變數有被設定，如果你正在引入一個模" -"組並且 Python 有能力（權限、空閒空間等）建立一個 .pyc 檔案是自動的建立一個" -"``__pycache__ `` 子目錄並將編譯後的模組寫入該子目錄。" - -#: ../../faq/programming.rst:2098 -#, fuzzy -msgid "" -"Running Python on a top level script is not considered an import and no " -"``.pyc`` will be created. For example, if you have a top-level module " -"``foo.py`` that imports another module ``xyz.py``, when you run ``foo`` (by " -"typing ``python foo.py`` as a shell command), a ``.pyc`` will be created for " -"``xyz`` because ``xyz`` is imported, but no ``.pyc`` file will be created " -"for ``foo`` since ``foo.py`` isn't being imported." -msgstr "" -"在頂級腳本上運行 Python 不被視為引入，也不會建立 ``.pyc``。例如，如果你有一個" -"頂級模組 ``foo.py`` 引入另一個模組 ``xyz.py`` ，當你運行 ``foo`` 時（透過輸" -"入 ``python foo.py`` 作為一個 shell 命令），將為 xyz 建立一個 .pyc 因為引入" -"了 xyz，但是不會為 foo 建立 .pyc 檔案，因為 ` `foo.py`` 沒有被引入。" - -#: ../../faq/programming.rst:2105 -msgid "" -"If you need to create a ``.pyc`` file for ``foo`` -- that is, to create a " -"``.pyc`` file for a module that is not imported -- you can, using " -"the :mod:`py_compile` and :mod:`compileall` modules." -msgstr "" -"如果你需要為 ``foo`` 建立一個 ``.pyc`` 檔案 —— 也就是說，要為一個未引入的模組" -"建立一個 ``.pyc`` 檔案 —— 你可以使用 :mod:`py_compile` 和 :mod:`compileall` " -"模組。" - -#: ../../faq/programming.rst:2109 -msgid "" -"The :mod:`py_compile` module can manually compile any module. One way is to " -"use the ``compile()`` function in that module interactively::" -msgstr "" -":mod:`py_compile` 模組允許手動編譯任何模組。其中一種方法是在該模組中以交互方" -"式使用 ``compile()`` 函式： ::" - -#: ../../faq/programming.rst:2112 -msgid "" -">>> import py_compile\n" -">>> py_compile.compile('foo.py')" -msgstr "" -">>> import py_compile\n" -">>> py_compile.compile('foo.py')" - -#: ../../faq/programming.rst:2115 -msgid "" -"This will write the ``.pyc`` to a ``__pycache__`` subdirectory in the same " -"location as ``foo.py`` (or you can override that with the optional parameter " -"``cfile``)." -msgstr "" -"這會將 ``.pyc`` 寫入與 ``foo.py`` 相同位置的 ``__pycache__`` 子目錄（或者你可" -"以使用可選參數 ``cfile`` 覆蓋它）。" - -#: ../../faq/programming.rst:2119 -#, fuzzy -msgid "" -"You can also automatically compile all files in a directory or directories " -"using the :mod:`compileall` module. You can do it from the shell prompt by " -"running ``compileall.py`` and providing the path of a directory containing " -"Python files to compile::" -msgstr "" -"你還可以使用 :mod:`compileall` 模組自動編譯目錄中的所有檔案。你可以在 shell " -"提示符下運行 ``compileall.py`` 並提供包含要編譯的 Python 檔案的目錄路徑： ::" - -#: ../../faq/programming.rst:2124 -msgid "python -m compileall ." -msgstr "python -m compileall ." - -#: ../../faq/programming.rst:2128 -msgid "How do I find the current module name?" -msgstr "如何找到目前模組名稱？" - -#: ../../faq/programming.rst:2130 -#, fuzzy -msgid "" -"A module can find out its own module name by looking at the predefined " -"global variable ``__name__``. If this has the value ``'__main__'``, the " -"program is running as a script. Many modules that are usually used by " -"importing them also provide a command-line interface or a self-test, and " -"only execute this code after checking ``__name__``::" -msgstr "" -"模組可以透過查看預定義的全域變數 ``__name__`` 來找出自己的模組名稱。如果它的" -"值為``'__main__'``，則該程式作為腳本運行。許多通常透過引入使用的模組還提供命" -"令行介面或自檢，只有在檢查 ``__name__`` 後才執行此程式碼： ::" - -#: ../../faq/programming.rst:2136 -msgid "" -"def main():\n" -" print('Running test...')\n" -" ...\n" -"\n" -"if __name__ == '__main__':\n" -" main()" -msgstr "" -"def main():\n" -" print('Running test...')\n" -" ...\n" -"\n" -"if __name__ == '__main__':\n" -" main()" - -#: ../../faq/programming.rst:2145 -msgid "How can I have modules that mutually import each other?" -msgstr "要怎樣才能擁有相互引入的模組？" - -#: ../../faq/programming.rst:2147 -msgid "Suppose you have the following modules:" -msgstr "假設你有以下模組：" - -#: ../../faq/programming.rst:2149 -msgid ":file:`foo.py`::" -msgstr ":file:`foo.py`： ::" - -#: ../../faq/programming.rst:2151 -msgid "" -"from bar import bar_var\n" -"foo_var = 1" -msgstr "" -"from bar import bar_var\n" -"foo_var = 1" - -#: ../../faq/programming.rst:2154 -msgid ":file:`bar.py`::" -msgstr ":file:`bar.py`： ::" - -#: ../../faq/programming.rst:2156 -msgid "" -"from foo import foo_var\n" -"bar_var = 2" -msgstr "" -"from foo import foo_var\n" -"bar_var = 2" - -#: ../../faq/programming.rst:2159 -msgid "The problem is that the interpreter will perform the following steps:" -msgstr "問題是直譯器將執行以下步驟：" - -#: ../../faq/programming.rst:2161 -msgid "main imports ``foo``" -msgstr "主要引入 ``foo``" - -#: ../../faq/programming.rst:2162 -msgid "Empty globals for ``foo`` are created" -msgstr "建立了 ``foo`` 的空全域變數" - -#: ../../faq/programming.rst:2163 -msgid "``foo`` is compiled and starts executing" -msgstr "``foo`` 被編譯並開始執行" - -#: ../../faq/programming.rst:2164 -msgid "``foo`` imports ``bar``" -msgstr "``foo`` 引入 ``bar``" - -#: ../../faq/programming.rst:2165 -msgid "Empty globals for ``bar`` are created" -msgstr "建立了 ``bar`` 的空全域變數" - -#: ../../faq/programming.rst:2166 -msgid "``bar`` is compiled and starts executing" -msgstr "``bar`` 已被編譯並開始執行" - -#: ../../faq/programming.rst:2167 -msgid "" -"``bar`` imports ``foo`` (which is a no-op since there already is a module " -"named ``foo``)" -msgstr "" -"``bar`` 引入 ``foo``\\ （這是一個空操作，因為已經有一個名為 ``foo`` 的模組）" - -#: ../../faq/programming.rst:2168 -msgid "" -"The import mechanism tries to read ``foo_var`` from ``foo`` globals, to set " -"``bar.foo_var = foo.foo_var``" -msgstr "" -"引入機制嘗試從 ``foo`` 全域變數中讀取 ``foo_var``，以設定 ``bar.foo_var = " -"foo.foo_var``" - -#: ../../faq/programming.rst:2170 -msgid "" -"The last step fails, because Python isn't done with interpreting ``foo`` yet " -"and the global symbol dictionary for ``foo`` is still empty." -msgstr "" -"最後一步失敗了，因為 Python 還沒有完成對 ``foo`` 的直譯，而 ``foo`` 的全域符" -"號字典仍然是空的。" - -#: ../../faq/programming.rst:2173 -#, fuzzy -msgid "" -"The same thing happens when you use ``import foo``, and then try to access " -"``foo.foo_var`` in global code." -msgstr "" -"當你使用 ``import foo``，然後嘗試在全域程式碼中存取 ``foo.foo_var`` 時，也會" -"發生同樣的事情。" - -#: ../../faq/programming.rst:2176 -msgid "There are (at least) three possible workarounds for this problem." -msgstr "此問題有（至少）三種可能的解決方法。" - -#: ../../faq/programming.rst:2178 -#, fuzzy -msgid "" -"Guido van Rossum recommends avoiding all uses of ``from " -"import ...``, and placing all code inside functions. Initializations of " -"global variables and class variables should use constants or built-in " -"functions only. This means everything from an imported module is referenced " -"as ``.``." -msgstr "" -"Guido van Rossum 建議避免使用``from import ...``，並將所有程式碼放在" -"函式中。全域變數和類別變數的初始化應該只使用常數或內建函式。這意味著來自引入" -"模組的所有內容都被參照為 ``.``。" - -#: ../../faq/programming.rst:2183 -msgid "" -"Jim Roskind suggests performing steps in the following order in each module:" -msgstr "Jim Roskind 建議在每個模組中按以下順序執行各個步驟：" - -#: ../../faq/programming.rst:2185 -#, fuzzy -msgid "" -"exports (globals, functions, and classes that don't need imported base " -"classes)" -msgstr "匯出（不需要引入基底類別的全域變數、函式和類別）" - -#: ../../faq/programming.rst:2187 -msgid "``import`` statements" -msgstr "``import`` 陳述式" - -#: ../../faq/programming.rst:2188 -msgid "" -"active code (including globals that are initialized from imported values)." -msgstr "活躍程式碼（包括從引入值初始化的全域變數）。" - -#: ../../faq/programming.rst:2190 -msgid "" -"Van Rossum doesn't like this approach much because the imports appear in a " -"strange place, but it does work." -msgstr "" -"Van Rossum 不太喜歡這種方法，因為引入出現在一個奇怪的地方，但它確實有效。" - -#: ../../faq/programming.rst:2193 -msgid "" -"Matthias Urlichs recommends restructuring your code so that the recursive " -"import is not necessary in the first place." -msgstr "" -"Matthias Urlichs 建議重組 (restructuring) 你的程式碼，以便打從一開始就不需要" -"遞迴引入。" - -#: ../../faq/programming.rst:2196 -msgid "These solutions are not mutually exclusive." -msgstr "這些方案並不衝突。" - -#: ../../faq/programming.rst:2200 -msgid "__import__('x.y.z') returns ; how do I get z?" -msgstr "__import__('x.y.z') 回傳 ，那我怎麼得到 z？" - -#: ../../faq/programming.rst:2202 -#, fuzzy -msgid "" -"Consider using the convenience function :func:`~importlib.import_module` " -"from :mod:`importlib` instead::" -msgstr "" -"考慮使用來自 :mod:`importlib` 的便利函式 :func:`~importlib.import_module` 代" -"替： ::" - -#: ../../faq/programming.rst:2205 -msgid "z = importlib.import_module('x.y.z')" -msgstr "z = importlib.import_module('x.y.z')" - -#: ../../faq/programming.rst:2209 -msgid "" -"When I edit an imported module and reimport it, the changes don't show up. " -"Why does this happen?" -msgstr "當我編輯需要引入的模組並重新引入它時，更動沒有反應出來。為什麼會這樣？" - -#: ../../faq/programming.rst:2211 -#, fuzzy -msgid "" -"For reasons of efficiency as well as consistency, Python only reads the " -"module file on the first time a module is imported. If it didn't, in a " -"program consisting of many modules where each one imports the same basic " -"module, the basic module would be parsed and re-parsed many times. To force " -"re-reading of a changed module, do this::" -msgstr "" -"出於效率和一致性的原因，Python 僅在第一次引入模組時讀取模組檔案。如果沒有，在" -"一個由許多模組組成的程式中，每個模組都引入相同的基本模組，基本模組將被解析和" -"重新解析很多次。要強制重新讀取已更改的模組，請執行以下操作： ::" - -#: ../../faq/programming.rst:2217 -msgid "" -"import importlib\n" -"import modname\n" -"importlib.reload(modname)" -msgstr "" -"import importlib\n" -"import modname\n" -"importlib.reload(modname)" - -#: ../../faq/programming.rst:2221 -msgid "" -"Warning: this technique is not 100% fool-proof. In particular, modules " -"containing statements like ::" -msgstr "警告：此技術並非 100% 萬無一失。尤其是包含像這樣陳述式的模組： ::" - -#: ../../faq/programming.rst:2224 -msgid "from modname import some_objects" -msgstr "from modname import some_objects" - -#: ../../faq/programming.rst:2226 -#, fuzzy -msgid "" -"will continue to work with the old version of the imported objects. If the " -"module contains class definitions, existing class instances will *not* be " -"updated to use the new class definition. This can result in the following " -"paradoxical behaviour::" -msgstr "" -"將繼續使用舊版本的引入物件。如果模組包含類別定義，現有的類別實例將*不會*更新" -"為使用新的類別定義。這可能會導致以下自相矛盾的行為： ::" - -#: ../../faq/programming.rst:2231 -msgid "" -">>> import importlib\n" -">>> import cls\n" -">>> c = cls.C() # Create an instance of C\n" -">>> importlib.reload(cls)\n" -"\n" -">>> isinstance(c, cls.C) # isinstance is false?!?\n" -"False" -msgstr "" -">>> import importlib\n" -">>> import cls\n" -">>> c = cls.C() # 建立一個 C 的實例\n" -">>> importlib.reload(cls)\n" -"\n" -">>> isinstance(c, cls.C) # isinstance 為 false？！？\n" -"False" - -#: ../../faq/programming.rst:2239 -msgid "" -"The nature of the problem is made clear if you print out the \"identity\" of " -"the class objects::" -msgstr "如果印出類別物件的「識別性」，問題的本質就很清楚了： ::" - -#: ../../faq/programming.rst:2242 -msgid "" -">>> hex(id(c.__class__))\n" -"'0x7352a0'\n" -">>> hex(id(cls.C))\n" -"'0x4198d0'" -msgstr "" -">>> hex(id(c.__class__))\n" -"'0x7352a0'\n" -">>> hex(id(cls.C))\n" -"'0x4198d0'" - -#: ../../faq/programming.rst:408 -msgid "argument" -msgstr "argument（引數）" - -#: ../../faq/programming.rst:408 -msgid "difference from parameter" -msgstr "與 parameter（參數）的差異" - -#: ../../faq/programming.rst:408 -msgid "parameter" -msgstr "parameter（參數）" - -#: ../../faq/programming.rst:408 -msgid "difference from argument" -msgstr "與 argument（引數）的差異" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# jerrychen , 2016 +# Ching-Lung Chuang, 2015 +# hsiao yi , 2016 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: 2024-04-25 14:17+0800\n" +"Last-Translator: KNChiu \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" +"X-Generator: Poedit 3.4.2\n" + +#: ../../faq/programming.rst:5 +msgid "Programming FAQ" +msgstr "程式開發常見問答集" + +#: ../../faq/programming.rst:8 +msgid "Contents" +msgstr "目錄" + +#: ../../faq/programming.rst:12 +msgid "General Questions" +msgstr "常見問題" + +#: ../../faq/programming.rst:15 +msgid "" +"Is there a source code level debugger with breakpoints, single-stepping, " +"etc.?" +msgstr "是否有可以使用在程式碼階段,具有中斷點,步驟執行等功能的除錯器？" + +#: ../../faq/programming.rst:17 ../../faq/programming.rst:58 +msgid "Yes." +msgstr "有的。" + +#: ../../faq/programming.rst:19 +msgid "" +"Several debuggers for Python are described below, and the built-in " +"function :func:`breakpoint` allows you to drop into any of them." +msgstr "" +"下面描述了幾個 Python 除錯器，內建函式 :func:`breakpoint` 允許你進入其中任何" +"一個。" + +#: ../../faq/programming.rst:22 +msgid "" +"The pdb module is a simple but adequate console-mode debugger for Python. It " +"is part of the standard Python library, and is :mod:`documented in the " +"Library Reference Manual `. You can also write your own debugger by " +"using the code for pdb as an example." +msgstr "" +"pdb 模組是一個簡單但足夠的 Python 控制台模式除錯器。它是標準 Python 函式庫的" +"一部分，並\\ :mod:`記錄在函式庫參考手冊 `\\ 中。你也可以參考 pdb 的程式" +"碼作為範例來編寫自己的除錯器。" + +#: ../../faq/programming.rst:27 +msgid "" +"The IDLE interactive development environment, which is part of the standard " +"Python distribution (normally available as `Tools/scripts/idle3 `_), includes a " +"graphical debugger." +msgstr "" +"IDLE 交互式開發環境，它是標準 Python 發行版的一部分（通常作為 `Tools/scripts/" +"idle3 `_ 提" +"供），包括一個圖形除錯器。" + +#: ../../faq/programming.rst:32 +msgid "" +"PythonWin is a Python IDE that includes a GUI debugger based on pdb. The " +"PythonWin debugger colors breakpoints and has quite a few cool features such " +"as debugging non-PythonWin programs. PythonWin is available as part of " +"`pywin32 `_ project and as a part of " +"the `ActivePython `_ " +"distribution." +msgstr "" +"PythonWin 是一個 Python IDE，它包含一個基於 pdb 的 GUI 除錯器。 PythonWin 除" +"錯器為斷點著色並具有許多很酷的功能，例如除錯非 PythonWin 程式。 PythonWin 作" +"為 `pywin32 `_ 專案的一部分和作為 " +"`ActivePython `_ 的一部分發佈。" + +#: ../../faq/programming.rst:39 +msgid "" +"`Eric `_ is an IDE built on PyQt and " +"the Scintilla editing component." +msgstr "" +"`Eric `_ 是一個基於 PyQt 和 Scintilla " +"編輯元件所建構的 IDE。" + +#: ../../faq/programming.rst:42 +msgid "" +"`trepan3k `_ is a gdb-like " +"debugger." +msgstr "" +"`trepan3k `_ 是一個類似 gdb 的除錯" +"器。" + +#: ../../faq/programming.rst:44 +msgid "" +"`Visual Studio Code `_ is an IDE with " +"debugging tools that integrates with version-control software." +msgstr "" +"`Visual Studio Code `_ 是一個整合了版本控制軟" +"體與除錯工具的 IDE。" + +#: ../../faq/programming.rst:47 +msgid "" +"There are a number of commercial Python IDEs that include graphical " +"debuggers. They include:" +msgstr "有數個商業化Python整合化開發工具包含圖形除錯功能。這些包含：" + +#: ../../faq/programming.rst:50 +msgid "`Wing IDE `_" +msgstr "`Wing IDE `_" + +#: ../../faq/programming.rst:51 +msgid "`Komodo IDE `_" +msgstr "`Komodo IDE `_" + +#: ../../faq/programming.rst:52 +msgid "`PyCharm `_" +msgstr "`PyCharm `_" + +#: ../../faq/programming.rst:56 +msgid "Are there tools to help find bugs or perform static analysis?" +msgstr "有沒有工具能夠幫忙找 bug 或執行靜態分析？" + +#: ../../faq/programming.rst:60 +msgid "" +"`Pylint `_ and `Pyflakes " +"`_ do basic checking that will help you " +"catch bugs sooner." +msgstr "" +"`Pylint `_ 和 `Pyflakes " +"`_ 進行基本檢查以幫助你儘早抓出錯誤。" + +#: ../../faq/programming.rst:64 +msgid "" +"Static type checkers such as `Mypy `_, `Pyre " +"`_, and `Pytype `_ can check type hints in Python source code." +msgstr "" +"靜態型別檢查器，例如 `Mypy `_、`Pyre `_ 和 `Pytype `_ 可以檢查 " +"Python 原始碼中的型別提示。" + +#: ../../faq/programming.rst:73 +msgid "How can I create a stand-alone binary from a Python script?" +msgstr "如何從 Python 腳本建立獨立的二進位檔案？" + +#: ../../faq/programming.rst:75 +msgid "" +"You don't need the ability to compile Python to C code if all you want is a " +"stand-alone program that users can download and run without having to " +"install the Python distribution first. There are a number of tools that " +"determine the set of modules required by a program and bind these modules " +"together with a Python binary to produce a single executable." +msgstr "" +"如果你想要的只是一個使用者可以下載並執行而無需先安裝 Python 發行版的獨立程" +"式，則不需要將 Python 編譯為 C 程式碼的能力。有許多工具可以判斷程式所需的模組" +"集，並將這些模組與 Python 二進位檔案綁定在一起以產生單個可執行檔。" + +#: ../../faq/programming.rst:81 +msgid "" +"One is to use the freeze tool, which is included in the Python source tree " +"as `Tools/freeze `_. It converts Python byte code to C arrays; with a C compiler you " +"can embed all your modules into a new program, which is then linked with the " +"standard Python modules." +msgstr "" +"一種是使用 freeze 工具，它位於 Python 原始碼樹中的 `Tools/freeze `_。它將 Python 位元組碼轉" +"換為 C 陣列；使用 C 編譯器，你可以將所有模組嵌入到一個新程式中，然後將其與標" +"準 Python 模組連結。" + +#: ../../faq/programming.rst:87 +#, fuzzy +msgid "" +"It works by scanning your source recursively for import statements (in both " +"forms) and looking for the modules in the standard Python path as well as in " +"the source directory (for built-in modules). It then turns the bytecode for " +"modules written in Python into C code (array initializers that can be turned " +"into code objects using the marshal module) and creates a custom-made config " +"file that only contains those built-in modules which are actually used in " +"the program. It then compiles the generated C code and links it with the " +"rest of the Python interpreter to form a self-contained binary which acts " +"exactly like your script." +msgstr "" +"它的工作原理是遞迴地掃描你的源程式碼以查詢引入陳述式（兩種形式）並在標準 " +"Python 路徑和源目錄（對於內建模組）中查詢模組。然後它將用 Python 編寫的模組的" +"位元組碼轉換為 C 程式碼（數組初始化器可以使用 marshal 模組轉換為程式碼物件）" +"並建立一個定制的配置檔案，該檔案僅包含那些實際使用的內建模組程式。然後它編譯" +"生成的 C 程式碼並將其與 Python 直譯器的其餘部分鏈接以形成一個獨立的二進製檔" +"案，其行為與你的腳本完全一樣。" + +#: ../../faq/programming.rst:96 +msgid "" +"The following packages can help with the creation of console and GUI " +"executables:" +msgstr "以下套件可以幫助建立 console 和 GUI 可執行檔案：" + +#: ../../faq/programming.rst:99 +msgid "`Nuitka `_ (Cross-platform)" +msgstr "`Nuitka `_\\ （跨平台）" + +#: ../../faq/programming.rst:100 +msgid "`PyInstaller `_ (Cross-platform)" +msgstr "`PyInstaller `_\\ （跨平台）" + +#: ../../faq/programming.rst:101 +msgid "" +"`PyOxidizer `_ (Cross-platform)" +msgstr "" +"`PyOxidizer `_\\ （跨平台）" + +#: ../../faq/programming.rst:102 +msgid "" +"`cx_Freeze `_ (Cross-platform)" +msgstr "" +"`cx_Freeze `_\\ （跨平台）" + +#: ../../faq/programming.rst:103 +msgid "`py2app `_ (macOS only)" +msgstr "`py2app `_\\ （僅限 macOS）" + +#: ../../faq/programming.rst:104 +msgid "`py2exe `_ (Windows only)" +msgstr "`py2exe `_\\ （僅限 Windows）" + +#: ../../faq/programming.rst:107 +msgid "Are there coding standards or a style guide for Python programs?" +msgstr "Python 程式碼是否有編碼標準或風格指南？" + +#: ../../faq/programming.rst:109 +msgid "" +"Yes. The coding style required for standard library modules is documented " +"as :pep:`8`." +msgstr "是的。標準函式庫模組所需的編碼風格稱為 :pep:`8`。" + +#: ../../faq/programming.rst:114 +msgid "Core Language" +msgstr "核心語言" + +#: ../../faq/programming.rst:119 +msgid "Why am I getting an UnboundLocalError when the variable has a value?" +msgstr "為什麼當變數有值時，我仍得到錯誤訊息 UnboundLocalError？" + +#: ../../faq/programming.rst:121 +#, fuzzy +msgid "" +"It can be a surprise to get the :exc:`UnboundLocalError` in previously " +"working code when it is modified by adding an assignment statement somewhere " +"in the body of a function." +msgstr "" +"當透過在函式主體的某處新增賦值陳述式修改以前的工作程式碼時，在以前的工作程式" +"碼中得到 :exc:`UnboundLocalError` 可能會令人驚訝。" + +#: ../../faq/programming.rst:125 +msgid "This code:" +msgstr "這段程式碼:" + +#: ../../faq/programming.rst:134 +msgid "works, but this code:" +msgstr "可以執行,但是這段程式:" + +#: ../../faq/programming.rst:141 +msgid "results in an :exc:`!UnboundLocalError`:" +msgstr "導致 :exc:`!UnboundLocalError`：" + +#: ../../faq/programming.rst:148 +#, fuzzy +msgid "" +"This is because when you make an assignment to a variable in a scope, that " +"variable becomes local to that scope and shadows any similarly named " +"variable in the outer scope. Since the last statement in foo assigns a new " +"value to ``x``, the compiler recognizes it as a local variable. " +"Consequently when the earlier ``print(x)`` attempts to print the " +"uninitialized local variable and an error results." +msgstr "" +"這是因為當你對作用域中的變數進行賦值時，該變數將成為該作用域的局部變數，並隱" +"藏外部作用域中任何類似命名的變數。由於 foo 中的最後一條陳述式為 ``x`` 分配了" +"一個新值，因此編譯器將其識別為局部變數。因此，當較早的 ``print(x)`` 嘗試印出" +"未初始化的局部變數並產生錯誤時。" + +#: ../../faq/programming.rst:155 +msgid "" +"In the example above you can access the outer scope variable by declaring it " +"global:" +msgstr "在上面的範例中，你可以透過將其聲明為全域變數來存取外部範圍變數：" + +#: ../../faq/programming.rst:167 +#, fuzzy +msgid "" +"This explicit declaration is required in order to remind you that (unlike " +"the superficially analogous situation with class and instance variables) you " +"are actually modifying the value of the variable in the outer scope:" +msgstr "" +"需要此顯式聲明是為了提醒你（與類別和實例變數表面上類似的情況不同）你實際上是" +"在外部範圍內修改變數的值：" + +#: ../../faq/programming.rst:174 +msgid "" +"You can do a similar thing in a nested scope using the :keyword:`nonlocal` " +"keyword:" +msgstr "你可以使用 :keyword:`nonlocal` 關鍵字在巢狀作用域內做類似的事情：" + +#: ../../faq/programming.rst:192 +msgid "What are the rules for local and global variables in Python?" +msgstr "Python 的區域變數和全域變數有什麼規則？" + +#: ../../faq/programming.rst:194 +#, fuzzy +msgid "" +"In Python, variables that are only referenced inside a function are " +"implicitly global. If a variable is assigned a value anywhere within the " +"function's body, it's assumed to be a local unless explicitly declared as " +"global." +msgstr "" +"在 Python 中，僅在函式內部參照的變數是隱式全域變數。如果一個變數在函式體內的" +"任何地方被賦值，除非明確聲明為全域變數，否則它被假定為局部變數。" + +#: ../../faq/programming.rst:198 +#, fuzzy +msgid "" +"Though a bit surprising at first, a moment's consideration explains this. " +"On one hand, requiring :keyword:`global` for assigned variables provides a " +"bar against unintended side-effects. On the other hand, if ``global`` was " +"required for all global references, you'd be using ``global`` all the time. " +"You'd have to declare as global every reference to a built-in function or to " +"a component of an imported module. This clutter would defeat the usefulness " +"of the ``global`` declaration for identifying side-effects." +msgstr "" +"雖然起初有點令人驚訝，但稍加考慮就可以解釋這一點。一方面，要" +"求 :keyword:`global` 分配的變數可以防止意外的副作用。另一方面，如果所有全域參" +"照都需要 ``global``，那麼你將一直使用 ``global``。你必須將對內建函式或引入模" +"組的組件的每個參照聲明為全域。這種混亂會破壞用於識別副作用的 ``global`` 聲明" +"的有用性。" + +#: ../../faq/programming.rst:208 +msgid "" +"Why do lambdas defined in a loop with different values all return the same " +"result?" +msgstr "為什麼以不同的值在迴圈中定義的 lambda 都回傳相同的結果？" + +#: ../../faq/programming.rst:210 +msgid "" +"Assume you use a for loop to define a few different lambdas (or even plain " +"functions), e.g.::" +msgstr "" +"假設你使用 for 迴圈來定義幾個不同的 lambda（甚至是普通函式），例如： ::" + +#: ../../faq/programming.rst:213 +msgid "" +">>> squares = []\n" +">>> for x in range(5):\n" +"... squares.append(lambda: x**2)" +msgstr "" +">>> squares = []\n" +">>> for x in range(5):\n" +"... squares.append(lambda: x**2)" + +#: ../../faq/programming.rst:217 +msgid "" +"This gives you a list that contains 5 lambdas that calculate ``x**2``. You " +"might expect that, when called, they would return, respectively, ``0``, " +"``1``, ``4``, ``9``, and ``16``. However, when you actually try you will " +"see that they all return ``16``::" +msgstr "" +"這會提供一個包含五個計算 ``x**2`` 的 lambda 串列。你可能會預期在呼叫它時，它" +"們會分別回傳 ``0``、``1``、``4``、``9`` 和 ``16``，然而當你實際嘗試你會發現它" +"們都回傳 ``16``： ::" + +#: ../../faq/programming.rst:222 +msgid "" +">>> squares[2]()\n" +"16\n" +">>> squares[4]()\n" +"16" +msgstr "" +">>> squares[2]()\n" +"16\n" +">>> squares[4]()\n" +"16" + +#: ../../faq/programming.rst:227 +msgid "" +"This happens because ``x`` is not local to the lambdas, but is defined in " +"the outer scope, and it is accessed when the lambda is called --- not when " +"it is defined. At the end of the loop, the value of ``x`` is ``4``, so all " +"the functions now return ``4**2``, i.e. ``16``. You can also verify this by " +"changing the value of ``x`` and see how the results of the lambdas change::" +msgstr "" +"發生這種情況是因為 ``x`` 不是 lambda 的局部變數，而是在外部作用域中定義的，且" +"是在呼叫 lambda 時才會存取它，並非於定義時就會存取。在迴圈結束時，``x`` 的值" +"為 ``4``，因此所有函式都回傳 ``4**2``，即為 ``16``。你還可以透過更改 ``x`` 的" +"值來驗證這一點，並查看 lambda 運算式的結果如何變化： ::" + +#: ../../faq/programming.rst:233 +msgid "" +">>> x = 8\n" +">>> squares[2]()\n" +"64" +msgstr "" +">>> x = 8\n" +">>> squares[2]()\n" +"64" + +#: ../../faq/programming.rst:237 +msgid "" +"In order to avoid this, you need to save the values in variables local to " +"the lambdas, so that they don't rely on the value of the global ``x``::" +msgstr "" +"為了避免這種情況，你需要將值保存在 lambda 的局部變數中，這樣它們就不會依賴於" +"全域 ``x`` 的值： ::" + +#: ../../faq/programming.rst:240 +msgid "" +">>> squares = []\n" +">>> for x in range(5):\n" +"... squares.append(lambda n=x: n**2)" +msgstr "" +">>> squares = []\n" +">>> for x in range(5):\n" +"... squares.append(lambda n=x: n**2)" + +#: ../../faq/programming.rst:244 +#, fuzzy +msgid "" +"Here, ``n=x`` creates a new variable ``n`` local to the lambda and computed " +"when the lambda is defined so that it has the same value that ``x`` had at " +"that point in the loop. This means that the value of ``n`` will be ``0`` in " +"the first lambda, ``1`` in the second, ``2`` in the third, and so on. " +"Therefore each lambda will now return the correct result::" +msgstr "" +"在這裡，``n=x`` 建立了一個新變數 ``n`` 局部於 lambda 並在定義 lambda 時計算，" +"因此它具有與 ``x`` 在迴圈中的那個點相同的值。這意味著 ``n`` 的值在第一個 " +"lambda 中為 ``0`` ，在第二個中為 ``1`` ，在第三個中為 ``2`` ，依此類推。因此" +"每個 lambda 現在將回傳正確的結果： ::" + +#: ../../faq/programming.rst:250 +msgid "" +">>> squares[2]()\n" +"4\n" +">>> squares[4]()\n" +"16" +msgstr "" +">>> squares[2]()\n" +"4\n" +">>> squares[4]()\n" +"16" + +#: ../../faq/programming.rst:255 +msgid "" +"Note that this behaviour is not peculiar to lambdas, but applies to regular " +"functions too." +msgstr "請注意，此行為並非 lambda 所特有，也適用於常規函式。" + +#: ../../faq/programming.rst:260 +msgid "How do I share global variables across modules?" +msgstr "如何跨模組共享全域變數？" + +#: ../../faq/programming.rst:262 +#, fuzzy +msgid "" +"The canonical way to share information across modules within a single " +"program is to create a special module (often called config or cfg). Just " +"import the config module in all modules of your application; the module then " +"becomes available as a global name. Because there is only one instance of " +"each module, any changes made to the module object get reflected " +"everywhere. For example:" +msgstr "" +"在單個程式中跨模組共享資訊的規範方法是建立一個特殊模組（通常稱為 config 或 " +"cfg）。只需在應用程式的所有模組中引入配置模組；然後該模組可作為全域名稱使用。" +"因為每個模組只有一個實例，所以對模組物件所做的任何更改都會在各處反映出來。例" +"如：" + +#: ../../faq/programming.rst:268 +msgid "config.py::" +msgstr "config.py： ::" + +#: ../../faq/programming.rst:270 +msgid "x = 0 # Default value of the 'x' configuration setting" +msgstr "x = 0 # 'x' 配置設定的預設值" + +#: ../../faq/programming.rst:272 +msgid "mod.py::" +msgstr "mod.py： ::" + +#: ../../faq/programming.rst:274 +msgid "" +"import config\n" +"config.x = 1" +msgstr "" +"import config\n" +"config.x = 1" + +#: ../../faq/programming.rst:277 +msgid "main.py::" +msgstr "main.py： ::" + +#: ../../faq/programming.rst:279 +msgid "" +"import config\n" +"import mod\n" +"print(config.x)" +msgstr "" +"import config\n" +"import mod\n" +"print(config.x)" + +#: ../../faq/programming.rst:283 +msgid "" +"Note that using a module is also the basis for implementing the singleton " +"design pattern, for the same reason." +msgstr "請注意，出於同樣的原因，使用模組也是實作單例設計模式的基礎。" + +#: ../../faq/programming.rst:288 +msgid "What are the \"best practices\" for using import in a module?" +msgstr "在模組中使用 import 的「最佳實踐」有哪些？" + +#: ../../faq/programming.rst:290 +#, fuzzy +msgid "" +"In general, don't use ``from modulename import *``. Doing so clutters the " +"importer's namespace, and makes it much harder for linters to detect " +"undefined names." +msgstr "" +"一般來說，不要使用``from modulename import *``。這樣做會使引入器的命名空間混" +"亂，並使 linters 更難檢測未定義的名稱。" + +#: ../../faq/programming.rst:294 +#, fuzzy +msgid "" +"Import modules at the top of a file. Doing so makes it clear what other " +"modules your code requires and avoids questions of whether the module name " +"is in scope. Using one import per line makes it easy to add and delete " +"module imports, but using multiple imports per line uses less screen space." +msgstr "" +"在檔案頂部引入模組。這樣做可以明確你的程式碼需要哪些其他模組，並避免模組名稱" +"是否在範圍內的問題。每行使用一個引入可以輕鬆新增和刪除模組引入，但每行使用多" +"個引入會佔用更少的屏幕空間。" + +#: ../../faq/programming.rst:299 +#, fuzzy +msgid "It's good practice if you import modules in the following order:" +msgstr "如果你按以下順序引入模組，這是一個很好的做法：" + +#: ../../faq/programming.rst:301 +msgid "" +"standard library modules -- " +"e.g. :mod:`sys`, :mod:`os`, :mod:`argparse`, :mod:`re`" +msgstr "" +"標準函式庫模組 —— 例如 :mod:`sys`、:mod:`os`、:mod:`argparse`、:mod:`re`" + +#: ../../faq/programming.rst:302 +#, fuzzy +msgid "" +"third-party library modules (anything installed in Python's site-packages " +"directory) -- e.g. :mod:`!dateutil`, :mod:`!requests`, :mod:`!PIL.Image`" +msgstr "" +"第三方函式庫模組（任何安裝在 Python 的站點包目錄中的模組）——例如:mod:`!" +"dateutil`, :mod:`!requests`, :mod:`!PIL.Image`" + +#: ../../faq/programming.rst:304 +msgid "locally developed modules" +msgstr "本地開發的模組" + +#: ../../faq/programming.rst:306 +#, fuzzy +msgid "" +"It is sometimes necessary to move imports to a function or class to avoid " +"problems with circular imports. Gordon McMillan says:" +msgstr "有時需要將引入移動到函式或類別以避免循環引入的問題。戈登麥克米蘭 說：" + +#: ../../faq/programming.rst:309 +#, fuzzy +msgid "" +"Circular imports are fine where both modules use the \"import \" " +"form of import. They fail when the 2nd module wants to grab a name out of " +"the first (\"from module import name\") and the import is at the top level. " +"That's because names in the 1st are not yet available, because the first " +"module is busy importing the 2nd." +msgstr "" +"在兩個模組都使用 \"import \" 引入形式的情況下，循環引入很好。當第二個" +"模組想要從第一個模組中取得一個名稱（ \"from module import name\" ）並且引入位" +"於頂層時，它們會失敗。那是因為 1st 中的名稱尚不可用，因為第一個模組正忙於導" +"入 2nd。" + +#: ../../faq/programming.rst:315 +#, fuzzy +msgid "" +"In this case, if the second module is only used in one function, then the " +"import can easily be moved into that function. By the time the import is " +"called, the first module will have finished initializing, and the second " +"module can do its import." +msgstr "" +"在這種情況下，如果第二個模組只在一個函式中使用，那麼引入可以很容易地移到那個" +"函式中。在呼叫引入時，第一個模組將完成初始化，第二個模組可以進行引入。" + +#: ../../faq/programming.rst:320 +#, fuzzy +msgid "" +"It may also be necessary to move imports out of the top level of code if " +"some of the modules are platform-specific. In that case, it may not even be " +"possible to import all of the modules at the top of the file. In this case, " +"importing the correct modules in the corresponding platform-specific code is " +"a good option." +msgstr "" +"如果某些模組是特定於平台的，則可能還需要將引入移出程式碼的頂層。在這種情況" +"下，甚至可能無法引入檔案頂部的所有模組。在這種情況下，在相應的特定於平台的程" +"式碼中引入正確的模組是一個不錯的選擇。" + +#: ../../faq/programming.rst:325 +#, fuzzy +msgid "" +"Only move imports into a local scope, such as inside a function definition, " +"if it's necessary to solve a problem such as avoiding a circular import or " +"are trying to reduce the initialization time of a module. This technique is " +"especially helpful if many of the imports are unnecessary depending on how " +"the program executes. You may also want to move imports into a function if " +"the modules are only ever used in that function. Note that loading a module " +"the first time may be expensive because of the one time initialization of " +"the module, but loading a module multiple times is virtually free, costing " +"only a couple of dictionary lookups. Even if the module name has gone out " +"of scope, the module is probably available in :data:`sys.modules`." +msgstr "" +"如果有必要解決諸如避免循環引入之類的問題或試圖減少模組的初始化時間，則僅將導" +"入移動到局部範圍內，例如在函式定義內。如果根據程式的執行方式，許多引入是不必" +"要的，則此技術特別有用。如果模組僅在該函式中使用，你可能還想將引入移動到該函" +"式中。請注意，由於模組的一次性初始化，第一次載入模組可能很昂貴，但多次載入模" +"組實際上是免費的，只需幾次字典查詢。即使模組名稱超出範圍，該模組也可能" +"在 :data:`sys.modules` 中可用。" + +#: ../../faq/programming.rst:338 +msgid "Why are default values shared between objects?" +msgstr "為什麼物件之間共享預設值？" + +#: ../../faq/programming.rst:340 +msgid "" +"This type of bug commonly bites neophyte programmers. Consider this " +"function::" +msgstr "這種類型的錯誤通常會困擾新手程式員。像是這個函式： ::" + +#: ../../faq/programming.rst:342 +msgid "" +"def foo(mydict={}): # Danger: shared reference to one dict for all calls\n" +" ... compute something ...\n" +" mydict[key] = value\n" +" return mydict" +msgstr "" +"def foo(mydict={}): # 危險：所有呼叫共享對字典的參照\n" +" ... 計算一些東西 ...\n" +" mydict[key] = value\n" +" return mydict" + +#: ../../faq/programming.rst:347 +msgid "" +"The first time you call this function, ``mydict`` contains a single item. " +"The second time, ``mydict`` contains two items because when ``foo()`` begins " +"executing, ``mydict`` starts out with an item already in it." +msgstr "" +"第一次呼叫此函式時， ``mydict`` 包含一個項目。第二次後 ``mydict`` 包含兩個項" +"目，因為當 ``foo()`` 開始執行時，``mydict`` 以其中已有的項目開始。" + +#: ../../faq/programming.rst:351 +#, fuzzy +msgid "" +"It is often expected that a function call creates new objects for default " +"values. This is not what happens. Default values are created exactly once, " +"when the function is defined. If that object is changed, like the " +"dictionary in this example, subsequent calls to the function will refer to " +"this changed object." +msgstr "" +"通常期望函式呼叫為預設值建立新物件。這不是發生的事情。當定義函式時，預設值只" +"建立一次。如果該物件發生更改，如本例中的字典，則對該函式的後續呼叫將參照該已" +"更改的物件。" + +#: ../../faq/programming.rst:356 +#, fuzzy +msgid "" +"By definition, immutable objects such as numbers, strings, tuples, and " +"``None``, are safe from change. Changes to mutable objects such as " +"dictionaries, lists, and class instances can lead to confusion." +msgstr "" +"根據定義，數字、字串、元組和 ``None`` 等不可變物件是安全的，不會發生變化。對" +"字典、串列和類別實例等可變物件的更改可能會導致混淆。" + +#: ../../faq/programming.rst:360 +msgid "" +"Because of this feature, it is good programming practice to not use mutable " +"objects as default values. Instead, use ``None`` as the default value and " +"inside the function, check if the parameter is ``None`` and create a new " +"list/dictionary/whatever if it is. For example, don't write::" +msgstr "" +"由於這個特性，不使用可變物件作為預設值是一個很好的程式設計習慣，而是應使用 " +"``None`` 作為預設值，並在函式內部檢查參數是否為 ``None``，再建立一個新的串列/" +"字典/或其他東西。例如，不要這樣寫： ::" + +#: ../../faq/programming.rst:365 +msgid "" +"def foo(mydict={}):\n" +" ..." +msgstr "" +"def foo(mydict={}):\n" +" ..." + +#: ../../faq/programming.rst:368 +msgid "but::" +msgstr "而是寫成： ::" + +#: ../../faq/programming.rst:370 +msgid "" +"def foo(mydict=None):\n" +" if mydict is None:\n" +" mydict = {} # create a new dict for local namespace" +msgstr "" +"def foo(mydict=None):\n" +" if mydict is None:\n" +" mydict = {} # 為區域命名空間建立一個新字典" + +#: ../../faq/programming.rst:374 +#, fuzzy +msgid "" +"This feature can be useful. When you have a function that's time-consuming " +"to compute, a common technique is to cache the parameters and the resulting " +"value of each call to the function, and return the cached value if the same " +"value is requested again. This is called \"memoizing\", and can be " +"implemented like this::" +msgstr "" +"此功能可能很有用。當你有一個計算起來很耗時的函式時，一種常用的技術是快取參數" +"和每次呼叫該函式的結果值，並在再次請求相同的值時回傳快取的值。這稱為「記憶" +"化」，可以像這樣實作： ::" + +#: ../../faq/programming.rst:379 +msgid "" +"# Callers can only provide two parameters and optionally pass _cache by " +"keyword\n" +"def expensive(arg1, arg2, *, _cache={}):\n" +" if (arg1, arg2) in _cache:\n" +" return _cache[(arg1, arg2)]\n" +"\n" +" # Calculate the value\n" +" result = ... expensive computation ...\n" +" _cache[(arg1, arg2)] = result # Store result in the cache\n" +" return result" +msgstr "" +"# 呼叫者只能提供兩個參數，並選擇性地透過關鍵字傳遞 _cache\n" +"def expensive(arg1, arg2, *, _cache={}):\n" +" if (arg1, arg2) in _cache:\n" +" return _cache[(arg1, arg2)]\n" +"\n" +" # Calculate the value\n" +" result = ... expensive computation ...\n" +" _cache[(arg1, arg2)] = result # 將結果儲存在快取中\n" +" return result" + +#: ../../faq/programming.rst:389 +msgid "" +"You could use a global variable containing a dictionary instead of the " +"default value; it's a matter of taste." +msgstr "你可以使用包含字典的全域變數而不是預設值；這取決於喜好。" + +#: ../../faq/programming.rst:394 +#, fuzzy +msgid "" +"How can I pass optional or keyword parameters from one function to another?" +msgstr "如何將可選參數或關鍵字參數從一個函式傳遞到另一個函式？" + +#: ../../faq/programming.rst:396 +#, fuzzy +msgid "" +"Collect the arguments using the ``*`` and ``**`` specifiers in the " +"function's parameter list; this gives you the positional arguments as a " +"tuple and the keyword arguments as a dictionary. You can then pass these " +"arguments when calling another function by using ``*`` and ``**``::" +msgstr "" +"在函式的引數list中使用``*`` 和``**`` 說明符收集參數；這為你提供了作為元組的位" +"置引數和作為字典的關鍵字引數。然後，你可以在使用 ``*`` 和 ``**`` 呼叫另一個函" +"式時傳遞這些引數： ::" + +#: ../../faq/programming.rst:401 +msgid "" +"def f(x, *args, **kwargs):\n" +" ...\n" +" kwargs['width'] = '14.3c'\n" +" ...\n" +" g(x, *args, **kwargs)" +msgstr "" +"def f(x, *args, **kwargs):\n" +" ...\n" +" kwargs['width'] = '14.3c'\n" +" ...\n" +" g(x, *args, **kwargs)" + +#: ../../faq/programming.rst:415 +msgid "What is the difference between arguments and parameters?" +msgstr "引數 (arguments) 和參數 (parameters) 有什麼區別？" + +#: ../../faq/programming.rst:417 +msgid "" +":term:`Parameters ` are defined by the names that appear in a " +"function definition, whereas :term:`arguments ` are the values " +"actually passed to a function when calling it. Parameters define " +"what :term:`kind of arguments ` a function can accept. For " +"example, given the function definition::" +msgstr "" +":term:`參數 `\\ 由出現在函式定義中的名稱定義，而\\ :term:`引數 " +"`\\ 是呼叫函式時實際傳遞給函式的值。參數定義函式可以接受的" +"\\ :term:`引數種類 `。例如，給定以下函式定義： ::" + +#: ../../faq/programming.rst:423 +msgid "" +"def func(foo, bar=None, **kwargs):\n" +" pass" +msgstr "" +"def func(foo, bar=None, **kwargs):\n" +" pass" + +#: ../../faq/programming.rst:426 +msgid "" +"*foo*, *bar* and *kwargs* are parameters of ``func``. However, when calling " +"``func``, for example::" +msgstr "" +"*foo*、*bar* 和 *kwargs* 是 ``func`` 的參數。然而當呼叫 ``func`` 時，例" +"如： ::" + +#: ../../faq/programming.rst:429 +msgid "func(42, bar=314, extra=somevar)" +msgstr "func(42, bar=314, extra=somevar)" + +#: ../../faq/programming.rst:431 +msgid "the values ``42``, ``314``, and ``somevar`` are arguments." +msgstr "``42``、``314`` 和 ``somevar`` 是引數。" + +#: ../../faq/programming.rst:435 +msgid "Why did changing list 'y' also change list 'x'?" +msgstr "為什麼更改串列 'y' 也會更改串列 'x'？" + +#: ../../faq/programming.rst:437 +msgid "If you wrote code like::" +msgstr "如果你寫了像這樣的程式碼： ::" + +#: ../../faq/programming.rst:439 +msgid "" +">>> x = []\n" +">>> y = x\n" +">>> y.append(10)\n" +">>> y\n" +"[10]\n" +">>> x\n" +"[10]" +msgstr "" +">>> x = []\n" +">>> y = x\n" +">>> y.append(10)\n" +">>> y\n" +"[10]\n" +">>> x\n" +"[10]" + +#: ../../faq/programming.rst:447 +msgid "" +"you might be wondering why appending an element to ``y`` changed ``x`` too." +msgstr "你可能想知道為什麼將一個元素附加到 ``y`` 時也會改變 ``x``。" + +#: ../../faq/programming.rst:449 +msgid "There are two factors that produce this result:" +msgstr "產生這個結果的原因有兩個：" + +#: ../../faq/programming.rst:451 +#, fuzzy +msgid "" +"Variables are simply names that refer to objects. Doing ``y = x`` doesn't " +"create a copy of the list -- it creates a new variable ``y`` that refers to " +"the same object ``x`` refers to. This means that there is only one object " +"(the list), and both ``x`` and ``y`` refer to it." +msgstr "" +"變數只是參照物件的名稱。執行 ``y = x`` 不會建立list的副本——它會建立一個新變" +"數 ``y``，它指向 ``x`` 指向的同一物件。這意味著只有一個物件（list），並且 " +"``x`` 和 ``y`` 都參照它。" + +#: ../../faq/programming.rst:455 +msgid "" +"Lists are :term:`mutable`, which means that you can change their content." +msgstr "list 是 :term:`mutable`，這意味著你可以變更它們的內容。" + +#: ../../faq/programming.rst:457 +#, fuzzy +msgid "" +"After the call to :meth:`~sequence.append`, the content of the mutable " +"object has changed from ``[]`` to ``[10]``. Since both the variables refer " +"to the same object, using either name accesses the modified value ``[10]``." +msgstr "" +"在呼叫 :meth:`!append` 之後，可變物件的內容從 ``[]`` 變成了 ``[10]``。由於這" +"兩個變數都參照同一個物件，因此使用任一名稱都可以存取修改後的值 ``[10]``。" + +#: ../../faq/programming.rst:461 +msgid "If we instead assign an immutable object to ``x``::" +msgstr "如果我們改為賦予一個不可變物件給 ``x``： ::" + +#: ../../faq/programming.rst:463 +msgid "" +">>> x = 5 # ints are immutable\n" +">>> y = x\n" +">>> x = x + 1 # 5 can't be mutated, we are creating a new object here\n" +">>> x\n" +"6\n" +">>> y\n" +"5" +msgstr "" +">>> x = 5 # 整數為不可變的\n" +">>> y = x\n" +">>> x = x + 1 # 5 不可變，在這邊會建立一個新物件\n" +">>> x\n" +"6\n" +">>> y\n" +"5" + +#: ../../faq/programming.rst:471 +#, fuzzy +msgid "" +"we can see that in this case ``x`` and ``y`` are not equal anymore. This is " +"because integers are :term:`immutable`, and when we do ``x = x + 1`` we are " +"not mutating the int ``5`` by incrementing its value; instead, we are " +"creating a new object (the int ``6``) and assigning it to ``x`` (that is, " +"changing which object ``x`` refers to). After this assignment we have two " +"objects (the ints ``6`` and ``5``) and two variables that refer to them " +"(``x`` now refers to ``6`` but ``y`` still refers to ``5``)." +msgstr "" +"我們可以看到，在這種情況下，``x`` 和 ``y`` 不再相等。這是因為整數是不可變的，" +"當我們做 x = x + 1 時，我們並沒有透過增加它的值來改變 int 5 ；相反，我們正在" +"建立一個新物件（int ``6``）並將其分配給``x``\\ （也就是說，更改``x``指向的物" +"件）。在這個賦值之後，我們有兩個物件（整數 ``6`` 和 ``5``）和兩個參照它們的變" +"數（``x`` 現在指的是 ``6`` 但 ``y`` 仍然指的是``5``）。" + +#: ../../faq/programming.rst:479 +#, fuzzy +msgid "" +"Some operations (for example ``y.append(10)`` and ``y.sort()``) mutate the " +"object, whereas superficially similar operations (for example ``y = y + " +"[10]`` and :func:`sorted(y) `) create a new object. In general in " +"Python (and in all cases in the standard library) a method that mutates an " +"object will return ``None`` to help avoid getting the two types of " +"operations confused. So if you mistakenly write ``y.sort()`` thinking it " +"will give you a sorted copy of ``y``, you'll instead end up with ``None``, " +"which will likely cause your program to generate an easily diagnosed error." +msgstr "" +"一些操作（例如 ``y.append(10)`` 和 ``y.sort()``）會改變物件，而表面上相似的操" +"作（例如 ``y = y + [10]`` 和： func:`sorted(y) `) 建立一個新物件。通" +"常在 Python 中（以及在標準函式庫中的所有情況下）改變物件的方法將回傳 " +"``None`` 以幫助避免混淆這兩種型別的操作。因此，如果你錯誤地編寫了 " +"``y.sort()``，認為它會為你提供 ``y`` 的排序副本，那麼你最終會得到 ``None``，" +"這可能會導致你的程式生成一個容易診斷的錯誤。" + +#: ../../faq/programming.rst:488 +#, fuzzy +msgid "" +"However, there is one class of operations where the same operation sometimes " +"has different behaviors with different types: the augmented assignment " +"operators. For example, ``+=`` mutates lists but not tuples or ints " +"(``a_list += [1, 2, 3]`` is equivalent to ``a_list.extend([1, 2, 3])`` and " +"mutates ``a_list``, whereas ``some_tuple += (1, 2, 3)`` and ``some_int += " +"1`` create new objects)." +msgstr "" +"但是，有一種操作，其中相同的操作有時具有不同型別的不同行為：擴充賦值運算子。" +"例如，``+=`` 改變list而不是元組或整數（``a_list += [1, 2, 3]`` 等同於" +"``a_list.extend([1, 2, 3])``並改變 ``a_list``，而 ``some_tuple += (1, 2, " +"3)`` 和 ``some_int += 1`` 建立新物件）。" + +#: ../../faq/programming.rst:495 +msgid "In other words:" +msgstr "換句話說：" + +#: ../../faq/programming.rst:497 +#, fuzzy +msgid "" +"If we have a mutable object (:class:`list`, :class:`dict`, :class:`set`, " +"etc.), we can use some specific operations to mutate it and all the " +"variables that refer to it will see the change." +msgstr "" +"如果我們有一個可變物件（:class:`list`、:class:`dict`、:class:`set` 等），我們" +"可以使用一些特定的操作來改變它，所有參照它的變數都會看到變化。" + +#: ../../faq/programming.rst:500 +#, fuzzy +msgid "" +"If we have an immutable object (:class:`str`, :class:`int`, :class:`tuple`, " +"etc.), all the variables that refer to it will always see the same value, " +"but operations that transform that value into a new value always return a " +"new object." +msgstr "" +"如果我們有一個不可變物件（:class:`str`、:class:`int`、:class:`tuple` 等），所" +"有參照它的變數將始終看到相同的值，但是轉換的操作將該值轉化為新值總是回傳一個" +"新物件。" + +#: ../../faq/programming.rst:505 +#, fuzzy +msgid "" +"If you want to know if two variables refer to the same object or not, you " +"can use the :keyword:`is` operator, or the built-in function :func:`id`." +msgstr "" +"如果你想知道兩個變數是否參照同一個物件，你可以使用 :keyword:`is` 運算子，或內" +"置函式 :func:`id`。" + +#: ../../faq/programming.rst:510 +msgid "How do I write a function with output parameters (call by reference)?" +msgstr "如何編寫帶有輸出參數的函式（透過傳參照呼叫 (call by reference)）？" + +#: ../../faq/programming.rst:512 +msgid "" +"Remember that arguments are passed by assignment in Python. Since " +"assignment just creates references to objects, there's no alias between an " +"argument name in the caller and callee, and so no call-by-reference per se. " +"You can achieve the desired effect in a number of ways." +msgstr "" +"請記住，在 Python 中引數是透過賦值傳遞的。由於賦值只是建立對物件的參照，因此" +"呼叫者和被呼叫者的引數名稱之間沒有別名，因此本身沒有傳參照呼叫。你可以透過多" +"種方式實作所需的效果。" + +#: ../../faq/programming.rst:517 +msgid "By returning a tuple of the results::" +msgstr "透過回傳結果的元組： ::" + +#: ../../faq/programming.rst:519 +msgid "" +">>> def func1(a, b):\n" +"... a = 'new-value' # a and b are local names\n" +"... b = b + 1 # assigned to new objects\n" +"... return a, b # return new values\n" +"...\n" +">>> x, y = 'old-value', 99\n" +">>> func1(x, y)\n" +"('new-value', 100)" +msgstr "" +">>> def func1(a, b):\n" +"... a = 'new-value' # a 和 b 為區域名稱\n" +"... b = b + 1 # 賦值到新物件\n" +"... return a, b # 回傳新值\n" +"...\n" +">>> x, y = 'old-value', 99\n" +">>> func1(x, y)\n" +"('new-value', 100)" + +#: ../../faq/programming.rst:528 +msgid "This is almost always the clearest solution." +msgstr "這幾乎都會是最清楚的方案。" + +#: ../../faq/programming.rst:530 +msgid "" +"By using global variables. This isn't thread-safe, and is not recommended." +msgstr "透過使用全域變數。這不是執行緒安全的，所以不推薦。" + +#: ../../faq/programming.rst:532 +msgid "By passing a mutable (changeable in-place) object::" +msgstr "透過傳遞一個可變的（可於原地 (in-place) 改變的）物件： ::" + +#: ../../faq/programming.rst:534 +msgid "" +">>> def func2(a):\n" +"... a[0] = 'new-value' # 'a' references a mutable list\n" +"... a[1] = a[1] + 1 # changes a shared object\n" +"...\n" +">>> args = ['old-value', 99]\n" +">>> func2(args)\n" +">>> args\n" +"['new-value', 100]" +msgstr "" +">>> def func2(a):\n" +"... a[0] = 'new-value' # 'a' 參照一個可變的串列\n" +"... a[1] = a[1] + 1 # 改變共享的物件\n" +"...\n" +">>> args = ['old-value', 99]\n" +">>> func2(args)\n" +">>> args\n" +"['new-value', 100]" + +#: ../../faq/programming.rst:543 +msgid "By passing in a dictionary that gets mutated::" +msgstr "透過傳入一個發生改變的字典： ::" + +#: ../../faq/programming.rst:545 +msgid "" +">>> def func3(args):\n" +"... args['a'] = 'new-value' # args is a mutable dictionary\n" +"... args['b'] = args['b'] + 1 # change it in-place\n" +"...\n" +">>> args = {'a': 'old-value', 'b': 99}\n" +">>> func3(args)\n" +">>> args\n" +"{'a': 'new-value', 'b': 100}" +msgstr "" +">>> def func3(args):\n" +"... args['a'] = 'new-value' # args 是可變字典\n" +"... args['b'] = args['b'] + 1 # 原地改變它\n" +"...\n" +">>> args = {'a': 'old-value', 'b': 99}\n" +">>> func3(args)\n" +">>> args\n" +"{'a': 'new-value', 'b': 100}" + +#: ../../faq/programming.rst:554 +msgid "Or bundle up values in a class instance::" +msgstr "或者在類別實例中捆綁值： ::" + +#: ../../faq/programming.rst:556 +msgid "" +">>> class Namespace:\n" +"... def __init__(self, /, **args):\n" +"... for key, value in args.items():\n" +"... setattr(self, key, value)\n" +"...\n" +">>> def func4(args):\n" +"... args.a = 'new-value' # args is a mutable Namespace\n" +"... args.b = args.b + 1 # change object in-place\n" +"...\n" +">>> args = Namespace(a='old-value', b=99)\n" +">>> func4(args)\n" +">>> vars(args)\n" +"{'a': 'new-value', 'b': 100}" +msgstr "" +">>> class Namespace:\n" +"... def __init__(self, /, **args):\n" +"... for key, value in args.items():\n" +"... setattr(self, key, value)\n" +"...\n" +">>> def func4(args):\n" +"... args.a = 'new-value' # args 是可變命名空間\n" +"... args.b = args.b + 1 # 原地改變物件\n" +"...\n" +">>> args = Namespace(a='old-value', b=99)\n" +">>> func4(args)\n" +">>> vars(args)\n" +"{'a': 'new-value', 'b': 100}" + +#: ../../faq/programming.rst:571 +msgid "There's almost never a good reason to get this complicated." +msgstr "幾乎不會有要讓事情變得如此複雜的充分理由。" + +#: ../../faq/programming.rst:573 +msgid "Your best choice is to return a tuple containing the multiple results." +msgstr "你最好的選擇是回傳一個包含多個結果的元組。" + +#: ../../faq/programming.rst:577 +msgid "How do you make a higher order function in Python?" +msgstr "你如何在 Python 中建立高階函式？" + +#: ../../faq/programming.rst:579 +msgid "" +"You have two choices: you can use nested scopes or you can use callable " +"objects. For example, suppose you wanted to define ``linear(a,b)`` which " +"returns a function ``f(x)`` that computes the value ``a*x+b``. Using nested " +"scopes::" +msgstr "" +"你有兩種選擇：可以使用巢狀作用域，也可以使用可呼叫物件。例如，假設你想定義 " +"``linear(a,b)``，它會回傳 ``a*x+b`` 計算值的函式 ``f(x)``。使用巢狀作用" +"域： ::" + +#: ../../faq/programming.rst:583 +msgid "" +"def linear(a, b):\n" +" def result(x):\n" +" return a * x + b\n" +" return result" +msgstr "" +"def linear(a, b):\n" +" def result(x):\n" +" return a * x + b\n" +" return result" + +#: ../../faq/programming.rst:588 +msgid "Or using a callable object::" +msgstr "或者使用可呼叫物件： ::" + +#: ../../faq/programming.rst:590 +msgid "" +"class linear:\n" +"\n" +" def __init__(self, a, b):\n" +" self.a, self.b = a, b\n" +"\n" +" def __call__(self, x):\n" +" return self.a * x + self.b" +msgstr "" +"class linear:\n" +"\n" +" def __init__(self, a, b):\n" +" self.a, self.b = a, b\n" +"\n" +" def __call__(self, x):\n" +" return self.a * x + self.b" + +#: ../../faq/programming.rst:598 +msgid "In both cases, ::" +msgstr "在這兩種情況下： ::" + +#: ../../faq/programming.rst:600 +msgid "taxes = linear(0.3, 2)" +msgstr "taxes = linear(0.3, 2)" + +#: ../../faq/programming.rst:602 +msgid "gives a callable object where ``taxes(10e6) == 0.3 * 10e6 + 2``." +msgstr "給定一個可呼叫物件，其中 ``taxes(10e6) == 0.3 * 10e6 + 2``。" + +#: ../../faq/programming.rst:604 +#, fuzzy +msgid "" +"The callable object approach has the disadvantage that it is a bit slower " +"and results in slightly longer code. However, note that a collection of " +"callables can share their signature via inheritance::" +msgstr "" +"可呼叫物件方法的缺點是它有點慢並且導致程式碼稍長。但是，請注意，可呼叫集合可" +"以透過繼承共享它們的簽名： ::" + +#: ../../faq/programming.rst:608 +msgid "" +"class exponential(linear):\n" +" # __init__ inherited\n" +" def __call__(self, x):\n" +" return self.a * (x ** self.b)" +msgstr "" +"class exponential(linear):\n" +" # __init__ inherited\n" +" def __call__(self, x):\n" +" return self.a * (x ** self.b)" + +#: ../../faq/programming.rst:613 +msgid "Object can encapsulate state for several methods::" +msgstr "物件可以封裝多個方法的狀態： ::" + +#: ../../faq/programming.rst:615 +msgid "" +"class counter:\n" +"\n" +" value = 0\n" +"\n" +" def set(self, x):\n" +" self.value = x\n" +"\n" +" def up(self):\n" +" self.value = self.value + 1\n" +"\n" +" def down(self):\n" +" self.value = self.value - 1\n" +"\n" +"count = counter()\n" +"inc, dec, reset = count.up, count.down, count.set" +msgstr "" +"class counter:\n" +"\n" +" value = 0\n" +"\n" +" def set(self, x):\n" +" self.value = x\n" +"\n" +" def up(self):\n" +" self.value = self.value + 1\n" +"\n" +" def down(self):\n" +" self.value = self.value - 1\n" +"\n" +"count = counter()\n" +"inc, dec, reset = count.up, count.down, count.set" + +#: ../../faq/programming.rst:631 +msgid "" +"Here ``inc()``, ``dec()`` and ``reset()`` act like functions which share the " +"same counting variable." +msgstr "" +"這裡的 ``inc()``、``dec()`` 和 ``reset()`` 就像共享相同計數變數的函式一樣。" + +#: ../../faq/programming.rst:636 +msgid "How do I copy an object in Python?" +msgstr "如何在 Python 中複製物件？" + +#: ../../faq/programming.rst:638 +#, fuzzy +msgid "" +"In general, try :func:`copy.copy` or :func:`copy.deepcopy` for the general " +"case. Not all objects can be copied, but most can." +msgstr "" +"一般來說，對於一般情況，請嘗試 :func:`copy.copy` 或 :func:`copy.deepcopy`。並" +"非所有物件都可以複製，但大多數都可以。" + +#: ../../faq/programming.rst:641 +#, fuzzy +msgid "" +"Some objects can be copied more easily. Dictionaries have " +"a :meth:`~dict.copy` method::" +msgstr "可以更輕鬆地複製某些物件。字典有一個 :meth:`~dict.copy` 方法： ::" + +#: ../../faq/programming.rst:644 +msgid "newdict = olddict.copy()" +msgstr "newdict = olddict.copy()" + +#: ../../faq/programming.rst:646 +msgid "Sequences can be copied by slicing::" +msgstr "序列可以透過切片 (slicing) 複製： ::" + +#: ../../faq/programming.rst:648 +msgid "new_l = l[:]" +msgstr "new_l = l[:]" + +#: ../../faq/programming.rst:652 +msgid "How can I find the methods or attributes of an object?" +msgstr "如何找到物件的方法或屬性？" + +#: ../../faq/programming.rst:654 +#, fuzzy +msgid "" +"For an instance ``x`` of a user-defined class, :func:`dir(x) ` returns " +"an alphabetized list of the names containing the instance attributes and " +"methods and attributes defined by its class." +msgstr "" +"對於使用者定義類別的實例 ``x``，:func:`dir(x) ` 回傳一個按字母順序排列的" +"名稱list，其中包含其類別定義的實例屬性、方法和屬性。" + +#: ../../faq/programming.rst:660 +msgid "How can my code discover the name of an object?" +msgstr "我的程式碼如何發現物件的名稱？" + +#: ../../faq/programming.rst:662 +#, fuzzy +msgid "" +"Generally speaking, it can't, because objects don't really have names. " +"Essentially, assignment always binds a name to a value; the same is true of " +"``def`` and ``class`` statements, but in that case the value is a callable. " +"Consider the following code::" +msgstr "" +"一般來說，它不能，因為物件並沒有真正的名字。本質上，賦值總是將名稱綁定到值； " +"``def`` 和 ``class`` 陳述式也是如此，但在那種情況下，值是可呼叫的。考慮以下程" +"式碼： ::" + +#: ../../faq/programming.rst:667 +msgid "" +">>> class A:\n" +"... pass\n" +"...\n" +">>> B = A\n" +">>> a = B()\n" +">>> b = a\n" +">>> print(b)\n" +"<__main__.A object at 0x16D07CC>\n" +">>> print(a)\n" +"<__main__.A object at 0x16D07CC>" +msgstr "" +">>> class A:\n" +"... pass\n" +"...\n" +">>> B = A\n" +">>> a = B()\n" +">>> b = a\n" +">>> print(b)\n" +"<__main__.A object at 0x16D07CC>\n" +">>> print(a)\n" +"<__main__.A object at 0x16D07CC>" + +#: ../../faq/programming.rst:678 +#, fuzzy +msgid "" +"Arguably the class has a name: even though it is bound to two names and " +"invoked through the name ``B`` the created instance is still reported as an " +"instance of class ``A``. However, it is impossible to say whether the " +"instance's name is ``a`` or ``b``, since both names are bound to the same " +"value." +msgstr "" +"可以說該類別有一個名稱：即使它綁定到兩個名稱並透過名稱 ``B`` 叫用，建立的實例" +"仍然被報告為類別 ``A`` 的實例。但是，無法確定實例的名稱是 ``a`` 還是 ``b`` ，" +"因為這兩個名稱都綁定到相同的值。" + +#: ../../faq/programming.rst:683 +#, fuzzy +msgid "" +"Generally speaking it should not be necessary for your code to \"know the " +"names\" of particular values. Unless you are deliberately writing " +"introspective programs, this is usually an indication that a change of " +"approach might be beneficial." +msgstr "" +"一般來說，你的程式碼不必「知道特定值的名稱」。除非你有意編寫內省程式，否則這" +"通常表明改變方法可能是有益的。" + +#: ../../faq/programming.rst:688 +msgid "" +"In comp.lang.python, Fredrik Lundh once gave an excellent analogy in answer " +"to this question:" +msgstr "" +"在 comp.lang.python 中，Fredrik Lundh 曾針對這個問題給出了一個極好的比喻：" + +#: ../../faq/programming.rst:691 +msgid "" +"The same way as you get the name of that cat you found on your porch: the " +"cat (object) itself cannot tell you its name, and it doesn't really care -- " +"so the only way to find out what it's called is to ask all your neighbours " +"(namespaces) if it's their cat (object)..." +msgstr "" +"就像你在門廊上發現的那隻貓的名字一樣：貓（物件）本身不能告訴你它的名字，它也" +"不關心 - 所以找出它叫什麼的唯一方法是詢問所有鄰居（命名空間）是否是他們的貓" +"（物件）..." + +#: ../../faq/programming.rst:696 +msgid "" +"....and don't be surprised if you'll find that it's known by many names, or " +"no name at all!" +msgstr "....如果你發現它有很多名字，或者根本沒有名字，請不要感到驚訝！" + +#: ../../faq/programming.rst:701 +msgid "What's up with the comma operator's precedence?" +msgstr "逗號運算子的優先級是什麼？" + +#: ../../faq/programming.rst:703 +#, fuzzy +msgid "Comma is not an operator in Python. Consider this session::" +msgstr "逗號不是 Python 中的運算子。考慮這個會話： ::" + +#: ../../faq/programming.rst:705 +msgid "" +">>> \"a\" in \"b\", \"a\"\n" +"(False, 'a')" +msgstr "" +">>> \"a\" in \"b\", \"a\"\n" +"(False, 'a')" + +#: ../../faq/programming.rst:708 +#, fuzzy +msgid "" +"Since the comma is not an operator, but a separator between expressions the " +"above is evaluated as if you had entered::" +msgstr "" +"由於逗號不是運算子，而是運算式之間的分隔符，因此上面的計算就像你輸入的那" +"樣： ::" + +#: ../../faq/programming.rst:711 +msgid "(\"a\" in \"b\"), \"a\"" +msgstr "(\"a\" in \"b\"), \"a\"" + +#: ../../faq/programming.rst:713 +msgid "not::" +msgstr "而不是： ::" + +#: ../../faq/programming.rst:715 +msgid "\"a\" in (\"b\", \"a\")" +msgstr "\"a\" in (\"b\", \"a\")" + +#: ../../faq/programming.rst:717 +#, fuzzy +msgid "" +"The same is true of the various assignment operators (``=``, ``+=`` etc). " +"They are not truly operators but syntactic delimiters in assignment " +"statements." +msgstr "" +"各種賦值運算子（``=``、``+=`` 等）也是如此。它們不是真正的運算子，而是賦值語" +"句中的句法定界符。" + +#: ../../faq/programming.rst:722 +msgid "Is there an equivalent of C's \"?:\" ternary operator?" +msgstr "是否有等效於 C 的 \"?:\" 三元運算子？" + +#: ../../faq/programming.rst:724 +msgid "Yes, there is. The syntax is as follows::" +msgstr "有的，語法如下： ::" + +#: ../../faq/programming.rst:726 +msgid "" +"[on_true] if [expression] else [on_false]\n" +"\n" +"x, y = 50, 25\n" +"small = x if x < y else y" +msgstr "" +"[on_true] if [expression] else [on_false]\n" +"\n" +"x, y = 50, 25\n" +"small = x if x < y else y" + +#: ../../faq/programming.rst:731 +#, fuzzy +msgid "" +"Before this syntax was introduced in Python 2.5, a common idiom was to use " +"logical operators::" +msgstr "" +"在 Python 2.5 中引入此語法之前，一個常見的習慣用法是使用邏輯運算子： ::" + +#: ../../faq/programming.rst:734 +msgid "[expression] and [on_true] or [on_false]" +msgstr "[expression] and [on_true] or [on_false]" + +#: ../../faq/programming.rst:736 +#, fuzzy +msgid "" +"However, this idiom is unsafe, as it can give wrong results when *on_true* " +"has a false boolean value. Therefore, it is always better to use the ``... " +"if ... else ...`` form." +msgstr "" +"然而，這個慣用語是不安全的，因為當 *on_true* 有一個錯誤的布林值時它會給出錯誤" +"的結果。因此，最好使用 ``... if ... else ...`` 形式。" + +#: ../../faq/programming.rst:742 +#, fuzzy +msgid "Is it possible to write obfuscated one-liners in Python?" +msgstr "是否可以在 Python 中編寫混淆的單行程式碼？" + +#: ../../faq/programming.rst:744 +#, fuzzy +msgid "" +"Yes. Usually this is done by nesting :keyword:`lambda` within :keyword:`!" +"lambda`. See the following three examples, slightly adapted from Ulf " +"Bartelt::" +msgstr "" +"是的。通常這是透過在 :keyword:`!lambda` 中嵌套 :keyword:`lambda` 來完成的。請" +"參閱以下三個範例，稍微改編自 Ulf Bartelt： ::" + +#: ../../faq/programming.rst:747 +msgid "" +"from functools import reduce\n" +"\n" +"# Primes < 1000\n" +"print(list(filter(None,map(lambda y:y*reduce(lambda x,y:x*y!=0,\n" +"map(lambda x,y=y:y%x,range(2,int(pow(y,0.5)+1))),1),range(2,1000)))))\n" +"\n" +"# First 10 Fibonacci numbers\n" +"print(list(map(lambda x,f=lambda x,f:(f(x-1,f)+f(x-2,f)) if x>1 else 1:\n" +"f(x,f), range(10))))\n" +"\n" +"# Mandelbrot set\n" +"print((lambda Ru,Ro,Iu,Io,IM,Sx,Sy:reduce(lambda x,y:x+'\\n'+y,map(lambda " +"y,\n" +"Iu=Iu,Io=Io,Ru=Ru,Ro=Ro,Sy=Sy,L=lambda yc,Iu=Iu,Io=Io,Ru=Ru,Ro=Ro,i=IM,\n" +"Sx=Sx,Sy=Sy:reduce(lambda x,y:x+y,map(lambda x,xc=Ru,yc=yc,Ru=Ru,Ro=Ro,\n" +"i=i,Sx=Sx,F=lambda xc,yc,x,y,k,f=lambda xc,yc,x,y,k,f:(k<=0)or (x*x+y*y\n" +">=4.0) or 1+f(xc,yc,x*x-y*y+xc,2.0*x*y+yc,k-1,f):f(xc,yc,x,y,k,f):chr(\n" +"64+F(Ru+x*(Ro-Ru)/Sx,yc,0,0,i)),range(Sx))):L(Iu+y*(Io-Iu)/Sy),range(Sy\n" +"))))(-2.1, 0.7, -1.2, 1.2, 30, 80, 24))\n" +"# \\___ ___/ \\___ ___/ | | |__ lines on screen\n" +"# V V | |______ columns on screen\n" +"# | | |__________ maximum of \"iterations\"\n" +"# | |_________________ range on y axis\n" +"# |____________________________ range on x axis" +msgstr "" + +#: ../../faq/programming.rst:771 +msgid "Don't try this at home, kids!" +msgstr "孩子們，不要在家裡嘗試這個！" + +#: ../../faq/programming.rst:777 +msgid "What does the slash(/) in the parameter list of a function mean?" +msgstr "函式參數串列中的斜線 (/) 是什麼意思？" + +#: ../../faq/programming.rst:779 +#, fuzzy +msgid "" +"A slash in the argument list of a function denotes that the parameters prior " +"to it are positional-only. Positional-only parameters are the ones without " +"an externally usable name. Upon calling a function that accepts positional-" +"only parameters, arguments are mapped to parameters based solely on their " +"position. For example, :func:`divmod` is a function that accepts positional-" +"only parameters. Its documentation looks like this::" +msgstr "" +"函式引數list中的斜線表示它前面的參數是位置參數。僅位置參數是沒有外部可用名稱" +"的參數。在呼叫接受僅位置參數的函式時，參數僅根據其位置對映到參數。例" +"如，:func:`divmod` 是一個只接受位置參數的函式。它的文件看起來像這樣： ::" + +#: ../../faq/programming.rst:786 +msgid "" +">>> help(divmod)\n" +"Help on built-in function divmod in module builtins:\n" +"\n" +"divmod(x, y, /)\n" +" Return the tuple (x//y, x%y). Invariant: div*y + mod == x." +msgstr "" +">>> help(divmod)\n" +"Help on built-in function divmod in module builtins:\n" +"\n" +"divmod(x, y, /)\n" +" Return the tuple (x//y, x%y). Invariant: div*y + mod == x." + +#: ../../faq/programming.rst:792 +msgid "" +"The slash at the end of the parameter list means that both parameters are " +"positional-only. Thus, calling :func:`divmod` with keyword arguments would " +"lead to an error::" +msgstr "" +"參數串列最後的斜線表示兩個參數都是僅限位置參數。因此使用關鍵字引數呼" +"叫 :func:`divmod` 會導致錯誤： ::" + +#: ../../faq/programming.rst:796 +msgid "" +">>> divmod(x=3, y=4)\n" +"Traceback (most recent call last):\n" +" File \"\", line 1, in \n" +"TypeError: divmod() takes no keyword arguments" +msgstr "" +">>> divmod(x=3, y=4)\n" +"Traceback (most recent call last):\n" +" File \"\", line 1, in \n" +"TypeError: divmod() takes no keyword arguments" + +#: ../../faq/programming.rst:803 +msgid "Numbers and strings" +msgstr "數字和字串" + +#: ../../faq/programming.rst:806 +msgid "How do I specify hexadecimal and octal integers?" +msgstr "如何指定十六進位和八進位整數？" + +#: ../../faq/programming.rst:808 +#, fuzzy +msgid "" +"To specify an octal digit, precede the octal value with a zero, and then a " +"lower or uppercase \"o\". For example, to set the variable \"a\" to the " +"octal value \"10\" (8 in decimal), type::" +msgstr "" +"要指定八進位數字，請在八進位值前面加上零，然後是小寫或大寫的 \"o\" 。例如，要" +"將變數 \"a\" 設定為八進位值 \"10\" （十進位為 8），請鍵入： ::" + +#: ../../faq/programming.rst:812 +msgid "" +">>> a = 0o10\n" +">>> a\n" +"8" +msgstr "" +">>> a = 0o10\n" +">>> a\n" +"8" + +#: ../../faq/programming.rst:816 +#, fuzzy +msgid "" +"Hexadecimal is just as easy. Simply precede the hexadecimal number with a " +"zero, and then a lower or uppercase \"x\". Hexadecimal digits can be " +"specified in lower or uppercase. For example, in the Python interpreter::" +msgstr "" +"十六進位也很容易。只需在十六進位數前面加上一個零，然後是一個小寫或大寫的 " +"\"x\" 。可以用小寫或大寫形式指定十六進位數字。例如，在 Python 直譯器中： ::" + +#: ../../faq/programming.rst:820 +msgid "" +">>> a = 0xa5\n" +">>> a\n" +"165\n" +">>> b = 0XB2\n" +">>> b\n" +"178" +msgstr "" +">>> a = 0xa5\n" +">>> a\n" +"165\n" +">>> b = 0XB2\n" +">>> b\n" +"178" + +#: ../../faq/programming.rst:829 +msgid "Why does -22 // 10 return -3?" +msgstr "為什麼 -22 // 10 回傳 -3？" + +#: ../../faq/programming.rst:831 +#, fuzzy +msgid "" +"It's primarily driven by the desire that ``i % j`` have the same sign as " +"``j``. If you want that, and also want::" +msgstr "" +"它主要是由希望 ``i % j`` 與 ``j`` 具有相同的符號驅動的。如果你想要那個，也想" +"要： ::" + +#: ../../faq/programming.rst:834 +msgid "i == (i // j) * j + (i % j)" +msgstr "i == (i // j) * j + (i % j)" + +#: ../../faq/programming.rst:836 +msgid "" +"then integer division has to return the floor. C also requires that " +"identity to hold, and then compilers that truncate ``i // j`` need to make " +"``i % j`` have the same sign as ``i``." +msgstr "" +"那麼整數除法必須回傳向下取整的結果。 C 還要求保留​​該識別性，然後截斷 ``i // " +"j`` 的編譯器需要使 ``i % j`` 具有與 ``i`` 相同的符號。" + +#: ../../faq/programming.rst:840 +#, fuzzy +msgid "" +"There are few real use cases for ``i % j`` when ``j`` is negative. When " +"``j`` is positive, there are many, and in virtually all of them it's more " +"useful for ``i % j`` to be ``>= 0``. If the clock says 10 now, what did it " +"say 200 hours ago? ``-190 % 12 == 2`` is useful; ``-190 % 12 == -10`` is a " +"bug waiting to bite." +msgstr "" +"當 j 為負時，i % j 的實際用例很少。當 ``j`` 為正時，有很多，並且在幾乎所有情" +"況下，``i % j`` 為 ``>= 0`` 更有用。如果時鐘現在是 10 點，那麼 200 小時前它是" +"什麼？ ``-190 % 12 == 2`` 很有用； ``-190 % 12 == -10`` 是一個等著咬人的錯" +"誤。" + +#: ../../faq/programming.rst:848 +#, fuzzy +msgid "How do I get int literal attribute instead of SyntaxError?" +msgstr "如何取得 int 文字屬性而不是 SyntaxError？" + +#: ../../faq/programming.rst:850 +msgid "" +"Trying to lookup an ``int`` literal attribute in the normal manner gives " +"a :exc:`SyntaxError` because the period is seen as a decimal point::" +msgstr "" +"嘗試以正常方式查找 ``int`` 字面值屬性會給出一個 :exc:`SyntaxError`，因為句點" +"被視為小數點： ::" + +#: ../../faq/programming.rst:853 +msgid "" +">>> 1.__class__\n" +" File \"\", line 1\n" +" 1.__class__\n" +" ^\n" +"SyntaxError: invalid decimal literal" +msgstr "" +">>> 1.__class__\n" +" File \"\", line 1\n" +" 1.__class__\n" +" ^\n" +"SyntaxError: invalid decimal literal" + +#: ../../faq/programming.rst:859 +msgid "" +"The solution is to separate the literal from the period with either a space " +"or parentheses." +msgstr "解決方式是用空格或圓括號將字面值與句點分開。" + +#: ../../faq/programming.rst:869 +msgid "How do I convert a string to a number?" +msgstr "如何將字串轉換為數字？" + +#: ../../faq/programming.rst:871 +#, fuzzy +msgid "" +"For integers, use the built-in :func:`int` type constructor, e.g. " +"``int('144') == 144``. Similarly, :func:`float` converts to a floating-" +"point number, e.g. ``float('144') == 144.0``." +msgstr "" +"對於整數，使用內建的 int 型別建構函式，例如``int('144') == 144``。同" +"樣，:func:`float` 轉換為浮點數，例如``浮動（'144'）== 144.0``。" + +#: ../../faq/programming.rst:875 +#, fuzzy +msgid "" +"By default, these interpret the number as decimal, so that ``int('0144') == " +"144`` holds true, and ``int('0x144')`` raises :exc:`ValueError`. " +"``int(string, base)`` takes the base to convert from as a second optional " +"argument, so ``int( '0x144', 16) == 324``. If the base is specified as 0, " +"the number is interpreted using Python's rules: a leading '0o' indicates " +"octal, and '0x' indicates a hex number." +msgstr "" +"預設情況下，這些將數字解釋為十進位，因此 ``int('0144') == 144`` 成立，而 " +"``int('0x144')`` 引發 :exc:`ValueError`。 ``int(string, base)`` 將要轉換的基" +"數作為第二個可選引數，因此 ``int( '0x144', 16) == 324``。如果基數指定為 0，則" +"使用 Python 的規則解釋該數字：前導 \"0o\" 表示八進位， \"0x\" 表示十六進位" +"數。" + +#: ../../faq/programming.rst:882 +#, fuzzy +msgid "" +"Do not use the built-in function :func:`eval` if all you need is to convert " +"strings to numbers. :func:`eval` will be significantly slower and it " +"presents a security risk: someone could pass you a Python expression that " +"might have unwanted side effects. For example, someone could pass " +"``__import__('os').system(\"rm -rf $HOME\")`` which would erase your home " +"directory." +msgstr "" +"如果你只需要將字串轉換為數字，請不要使用內建函式 :func:`eval`。 :func:`eval` " +"會顯著變慢，並且會帶來安全風險：有人可能會向你傳遞一個可能會產生不良副作用的 " +"Python 運算式。例如，有人可以透過 ``__import__('os').system(\"rm -rf " +"$HOME\")`` 來清除你的主目錄。" + +#: ../../faq/programming.rst:889 +#, fuzzy +msgid "" +":func:`eval` also has the effect of interpreting numbers as Python " +"expressions, so that e.g. ``eval('09')`` gives a syntax error because Python " +"does not allow leading '0' in a decimal number (except '0')." +msgstr "" +":func:`eval` 還具有將數字解釋為 Python 運算式的效果，例如``eval('09')`` 會給" +"出語法錯誤，因為 Python 不允許在十進位數中前導 '0'（'0' 除外）。" + +#: ../../faq/programming.rst:895 +msgid "How do I convert a number to a string?" +msgstr "如何將數字轉換為字串？" + +#: ../../faq/programming.rst:897 +#, fuzzy +msgid "" +"To convert, e.g., the number ``144`` to the string ``'144'``, use the built-" +"in type constructor :func:`str`. If you want a hexadecimal or octal " +"representation, use the built-in functions :func:`hex` or :func:`oct`. For " +"fancy formatting, see the :ref:`f-strings` and :ref:`formatstrings` " +"sections, e.g. ``\"{:04d}\".format(144)`` yields ``'0144'`` and ``\"{:.3f}" +"\".format(1.0/3.0)`` yields ``'0.333'``." +msgstr "" +"例如，要將數字 ``144`` 轉換為字串 ``'144'``，請使用內建型別建構函" +"式 :func:`str`。如果你想要十六進製或八進製表示，請使用內建函式 :func:`hex` " +"或 :func:`oct`。對於精美的格式，請參閱:ref:`f-strings` " +"和:ref:`formatstrings` 部分，例如``\"{:04d}\".format(144)`` 產生 ``'0144'`` " +"和 ``\"{:.3f}\".format(1.0/3.0)`` 產生 ``'0.333'`` ." + +#: ../../faq/programming.rst:906 +msgid "How do I modify a string in place?" +msgstr "如何原地修改字串？" + +#: ../../faq/programming.rst:908 +msgid "" +"You can't, because strings are immutable. In most situations, you should " +"simply construct a new string from the various parts you want to assemble it " +"from. However, if you need an object with the ability to modify in-place " +"unicode data, try using an :class:`io.StringIO` object or the :mod:`array` " +"module::" +msgstr "" +"這沒辦法做到，因為字串是不可變的。在大多數情況下，你應以要拿來組裝的各個部分" +"建構出一個新字串。但是如果你需要一個能夠原地修改 unicode 資料的物件，請嘗試使" +"用 :class:`io.StringIO` 物件或 :mod:`array` 模組： ::" + +#: ../../faq/programming.rst:914 +msgid "" +">>> import io\n" +">>> s = \"Hello, world\"\n" +">>> sio = io.StringIO(s)\n" +">>> sio.getvalue()\n" +"'Hello, world'\n" +">>> sio.seek(7)\n" +"7\n" +">>> sio.write(\"there!\")\n" +"6\n" +">>> sio.getvalue()\n" +"'Hello, there!'\n" +"\n" +">>> import array\n" +">>> a = array.array('w', s)\n" +">>> print(a)\n" +"array('w', 'Hello, world')\n" +">>> a[0] = 'y'\n" +">>> print(a)\n" +"array('w', 'yello, world')\n" +">>> a.tounicode()\n" +"'yello, world'" +msgstr "" +">>> import io\n" +">>> s = \"Hello, world\"\n" +">>> sio = io.StringIO(s)\n" +">>> sio.getvalue()\n" +"'Hello, world'\n" +">>> sio.seek(7)\n" +"7\n" +">>> sio.write(\"there!\")\n" +"6\n" +">>> sio.getvalue()\n" +"'Hello, there!'\n" +"\n" +">>> import array\n" +">>> a = array.array('w', s)\n" +">>> print(a)\n" +"array('w', 'Hello, world')\n" +">>> a[0] = 'y'\n" +">>> print(a)\n" +"array('w', 'yello, world')\n" +">>> a.tounicode()\n" +"'yello, world'" + +#: ../../faq/programming.rst:938 +msgid "How do I use strings to call functions/methods?" +msgstr "如何使用字串呼叫函式/方法？" + +#: ../../faq/programming.rst:940 +msgid "There are various techniques." +msgstr "有各式各樣的技法。" + +#: ../../faq/programming.rst:942 +#, fuzzy +msgid "" +"The best is to use a dictionary that maps strings to functions. The primary " +"advantage of this technique is that the strings do not need to match the " +"names of the functions. This is also the primary technique used to emulate " +"a case construct::" +msgstr "" +"最好的方法是使用將字串對映到函式的字典。這種技術的主要優點是字串不需要與函式" +"名稱相匹配。這也是用於模擬案例建構的主要技術： ::" + +#: ../../faq/programming.rst:947 +msgid "" +"def a():\n" +" pass\n" +"\n" +"def b():\n" +" pass\n" +"\n" +"dispatch = {'go': a, 'stop': b} # Note lack of parens for funcs\n" +"\n" +"dispatch[get_input()]() # Note trailing parens to call function" +msgstr "" + +#: ../../faq/programming.rst:957 +msgid "Use the built-in function :func:`getattr`::" +msgstr "使用內建函式 :func:`getattr`： ::" + +#: ../../faq/programming.rst:959 +msgid "" +"import foo\n" +"getattr(foo, 'bar')()" +msgstr "" +"import foo\n" +"getattr(foo, 'bar')()" + +#: ../../faq/programming.rst:962 +msgid "" +"Note that :func:`getattr` works on any object, including classes, class " +"instances, modules, and so on." +msgstr "請注意 :func:`getattr` 適用於任何物件，包括類別、類別實例、模組等。" + +#: ../../faq/programming.rst:965 +msgid "This is used in several places in the standard library, like this::" +msgstr "這在標準函式庫中的幾個地方被使用，如： ::" + +#: ../../faq/programming.rst:967 +msgid "" +"class Foo:\n" +" def do_foo(self):\n" +" ...\n" +"\n" +" def do_bar(self):\n" +" ...\n" +"\n" +"f = getattr(foo_instance, 'do_' + opname)\n" +"f()" +msgstr "" +"class Foo:\n" +" def do_foo(self):\n" +" ...\n" +"\n" +" def do_bar(self):\n" +" ...\n" +"\n" +"f = getattr(foo_instance, 'do_' + opname)\n" +"f()" + +#: ../../faq/programming.rst:978 +msgid "Use :func:`locals` to resolve the function name::" +msgstr "使用 :func:`locals` 解析函式名稱： ::" + +#: ../../faq/programming.rst:980 +msgid "" +"def myFunc():\n" +" print(\"hello\")\n" +"\n" +"fname = \"myFunc\"\n" +"\n" +"f = locals()[fname]\n" +"f()" +msgstr "" +"def myFunc():\n" +" print(\"hello\")\n" +"\n" +"fname = \"myFunc\"\n" +"\n" +"f = locals()[fname]\n" +"f()" + +#: ../../faq/programming.rst:990 +#, fuzzy +msgid "" +"Is there an equivalent to Perl's ``chomp()`` for removing trailing newlines " +"from strings?" +msgstr "" +"是否有與 Perl 的 chomp() 等效的方法，能用於從字串中刪除後綴的換行符號？" + +#: ../../faq/programming.rst:992 +msgid "" +"You can use ``S.rstrip(\"\\r\\n\")`` to remove all occurrences of any line " +"terminator from the end of the string ``S`` without removing other trailing " +"whitespace. If the string ``S`` represents more than one line, with several " +"empty lines at the end, the line terminators for all the blank lines will be " +"removed::" +msgstr "" + +#: ../../faq/programming.rst:998 +msgid "" +">>> lines = (\"line 1 \\r\\n\"\n" +"... \"\\r\\n\"\n" +"... \"\\r\\n\")\n" +">>> lines.rstrip(\"\\n\\r\")\n" +"'line 1 '" +msgstr "" +">>> lines = (\"line 1 \\r\\n\"\n" +"... \"\\r\\n\"\n" +"... \"\\r\\n\")\n" +">>> lines.rstrip(\"\\n\\r\")\n" +"'line 1 '" + +#: ../../faq/programming.rst:1004 +#, fuzzy +msgid "" +"Since this is typically only desired when reading text one line at a time, " +"using ``S.rstrip()`` this way works well." +msgstr "" +"由於這通常只在一次讀取一行文本時才需要，因此使用 ``S.rstrip()`` 這種方式效果" +"很好。" + +#: ../../faq/programming.rst:1009 +#, fuzzy +msgid "Is there a ``scanf()`` or ``sscanf()`` equivalent?" +msgstr "是否有 scanf() 或 sscanf() 的等效方法？" + +#: ../../faq/programming.rst:1011 +#, fuzzy +msgid "Not as such." +msgstr "不是這樣的。" + +#: ../../faq/programming.rst:1013 +#, fuzzy +msgid "" +"For simple input parsing, the easiest approach is usually to split the line " +"into whitespace-delimited words using the :meth:`~str.split` method of " +"string objects and then convert decimal strings to numeric values " +"using :func:`int` or :func:`float`. :meth:`!split` supports an optional " +"\"sep\" parameter which is useful if the line uses something other than " +"whitespace as a separator." +msgstr "" +"對於簡單的輸入解析，最簡單的方法通常是使用字串物件的 :meth:`~str.split` 方法" +"將行拆分為以空格分隔的單詞，然後使用 :func:`int` 或將十進製字串轉換為數" +"值:func:`浮動`。 :meth:`!split` 支援可選的 \"sep\" 參數，如果該行使用空格以外" +"的其他內容作為分隔符，該參數很有用。" + +#: ../../faq/programming.rst:1019 +#, fuzzy +msgid "" +"For more complicated input parsing, regular expressions are more powerful " +"than C's ``sscanf`` and better suited for the task." +msgstr "" +"對於更複雜的輸入解析，正則運算式比 C 的 ``sscanf`` 更強大，更適合這項任務。" + +#: ../../faq/programming.rst:1024 +#, fuzzy +msgid "What does ``UnicodeDecodeError`` or ``UnicodeEncodeError`` error mean?" +msgstr "'UnicodeDecodeError' 或 'UnicodeEncodeErro' 錯誤是什麼意思？" + +#: ../../faq/programming.rst:1026 +msgid "See the :ref:`unicode-howto`." +msgstr "請參閱 :ref:`unicode-howto`。" + +#: ../../faq/programming.rst:1032 +#, fuzzy +msgid "Can I end a raw string with an odd number of backslashes?" +msgstr "我可以用奇數個反斜線結束原始字串嗎？" + +#: ../../faq/programming.rst:1034 +#, fuzzy +msgid "" +"A raw string ending with an odd number of backslashes will escape the " +"string's quote::" +msgstr "以奇數個反斜線結尾的原始字串將跳脫字串的引號： ::" + +#: ../../faq/programming.rst:1036 +msgid "" +">>> r'C:\\this\\will\\not\\work\\'\n" +" File \"\", line 1\n" +" r'C:\\this\\will\\not\\work\\'\n" +" ^\n" +"SyntaxError: unterminated string literal (detected at line 1)" +msgstr "" +">>> r'C:\\this\\will\\not\\work\\'\n" +" File \"\", line 1\n" +" r'C:\\this\\will\\not\\work\\'\n" +" ^\n" +"SyntaxError: unterminated string literal (detected at line 1)" + +#: ../../faq/programming.rst:1042 +#, fuzzy +msgid "" +"There are several workarounds for this. One is to use regular strings and " +"double the backslashes::" +msgstr "有幾種解決方法。一種是使用常規字串並加倍反斜線： ::" + +#: ../../faq/programming.rst:1045 +msgid "" +">>> 'C:\\\\this\\\\will\\\\work\\\\'\n" +"'C:\\\\this\\\\will\\\\work\\\\'" +msgstr "" +">>> 'C:\\\\this\\\\will\\\\work\\\\'\n" +"'C:\\\\this\\\\will\\\\work\\\\'" + +#: ../../faq/programming.rst:1048 +#, fuzzy +msgid "" +"Another is to concatenate a regular string containing an escaped backslash " +"to the raw string::" +msgstr "另一種方法是將包含跳脫反斜線的常規字串連接到原始字串： ::" + +#: ../../faq/programming.rst:1051 +msgid "" +">>> r'C:\\this\\will\\work' '\\\\'\n" +"'C:\\\\this\\\\will\\\\work\\\\'" +msgstr "" +">>> r'C:\\this\\will\\work' '\\\\'\n" +"'C:\\\\this\\\\will\\\\work\\\\'" + +#: ../../faq/programming.rst:1054 +#, fuzzy +msgid "" +"It is also possible to use :func:`os.path.join` to append a backslash on " +"Windows::" +msgstr "也可以使用 :func:`os.path.join` 在 Windows 上附加反斜線： ::" + +#: ../../faq/programming.rst:1056 +msgid "" +">>> os.path.join(r'C:\\this\\will\\work', '')\n" +"'C:\\\\this\\\\will\\\\work\\\\'" +msgstr "" +">>> os.path.join(r'C:\\this\\will\\work', '')\n" +"'C:\\\\this\\\\will\\\\work\\\\'" + +#: ../../faq/programming.rst:1059 +#, fuzzy +msgid "" +"Note that while a backslash will \"escape\" a quote for the purposes of " +"determining where the raw string ends, no escaping occurs when interpreting " +"the value of the raw string. That is, the backslash remains present in the " +"value of the raw string::" +msgstr "" +"請注意，雖然為了確定原始字串的結束位置而使用反斜線「跳脫」引號，但在解釋原始" +"字串的值時不會發生跳脫。也就是說，反斜線仍然存在於原始字串的值中： ::" + +#: ../../faq/programming.rst:1064 +msgid "" +">>> r'backslash\\'preserved'\n" +"\"backslash\\\\'preserved\"" +msgstr "" +">>> r'backslash\\'preserved'\n" +"\"backslash\\\\'preserved\"" + +#: ../../faq/programming.rst:1067 +#, fuzzy +msgid "Also see the specification in the :ref:`language reference `." +msgstr "另請參閱 :ref:`語言參考 ` 中的規範。" + +#: ../../faq/programming.rst:1070 +msgid "Performance" +msgstr "效能" + +#: ../../faq/programming.rst:1073 +msgid "My program is too slow. How do I speed it up?" +msgstr "我的程式太慢了。我該如何加快速度？" + +#: ../../faq/programming.rst:1075 +#, fuzzy +msgid "" +"That's a tough one, in general. First, here are a list of things to " +"remember before diving further:" +msgstr "" +"總的來說，這是一個艱難的過程。首先，這裡列出了在進一步潛水之前要記住的事項：" + +#: ../../faq/programming.rst:1078 +#, fuzzy +msgid "" +"Performance characteristics vary across Python implementations. This FAQ " +"focuses on :term:`CPython`." +msgstr "性能特徵因 Python 實作而異。此 FAQ 重點關注 :term:`CPython`。" + +#: ../../faq/programming.rst:1080 +#, fuzzy +msgid "" +"Behaviour can vary across operating systems, especially when talking about I/" +"O or multi-threading." +msgstr "行為可能因作業系統而異，尤其是在談論 I/O 或多執行緒時。" + +#: ../../faq/programming.rst:1082 +#, fuzzy +msgid "" +"You should always find the hot spots in your program *before* attempting to " +"optimize any code (see the :mod:`profile` module)." +msgstr "" +"在嘗試最佳化任何程式碼\\ *之前*，你應該始終找到程式中的熱點（請參" +"閱 :mod:`profile` 模組）。" + +#: ../../faq/programming.rst:1084 +#, fuzzy +msgid "" +"Writing benchmark scripts will allow you to iterate quickly when searching " +"for improvements (see the :mod:`timeit` module)." +msgstr "" +"編寫基準測試腳本將允許你在搜尋改進時快速疊代（請參閱 :mod:`timeit` 模組）。" + +#: ../../faq/programming.rst:1086 +#, fuzzy +msgid "" +"It is highly recommended to have good code coverage (through unit testing or " +"any other technique) before potentially introducing regressions hidden in " +"sophisticated optimizations." +msgstr "" +"強烈建議在可能引入隱藏在復雜最佳化中的回歸之前擁有良好的程式碼覆蓋率（透過單" +"元測試或任何其他技術）。" + +#: ../../faq/programming.rst:1090 +#, fuzzy +msgid "" +"That being said, there are many tricks to speed up Python code. Here are " +"some general principles which go a long way towards reaching acceptable " +"performance levels:" +msgstr "" +"也就是說，有很多技巧可以加速 Python 程式碼。以下是一些對達到可接受的性能水平" +"大有幫助的一般原則：" + +#: ../../faq/programming.rst:1094 +#, fuzzy +msgid "" +"Making your algorithms faster (or changing to faster ones) can yield much " +"larger benefits than trying to sprinkle micro-optimization tricks all over " +"your code." +msgstr "" +"讓你的演算法更快（或更改為更快的演算法）可以產生比嘗試在你的程式碼中散佈微最" +"佳化技巧大得多的好處。" + +#: ../../faq/programming.rst:1098 +#, fuzzy +msgid "" +"Use the right data structures. Study documentation for the :ref:`bltin-" +"types` and the :mod:`collections` module." +msgstr "" +"使用正確的資料結構。研究 :ref:`bltin-types` 和 :mod:`collections` 模組的文" +"件。" + +#: ../../faq/programming.rst:1101 +#, fuzzy +msgid "" +"When the standard library provides a primitive for doing something, it is " +"likely (although not guaranteed) to be faster than any alternative you may " +"come up with. This is doubly true for primitives written in C, such as " +"builtins and some extension types. For example, be sure to use either " +"the :meth:`list.sort` built-in method or the related :func:`sorted` function " +"to do sorting (and see the :ref:`sortinghowto` for examples of moderately " +"advanced usage)." +msgstr "" +"當標準函式庫提供用於執行某些操作的原語時，它很可能（儘管不能保證）比你可能想" +"出的任何替代方法都更快。對於用 C 編寫的原語，例如內建函式和一些擴充型別，情況" +"更是如此。例如，請務必使用 :meth:`list.sort` 內建方法或相關的 :func:`sorted` " +"函式進行排序（有關高階用法的範例，請參閱 :ref:`sortinghowto` )." + +#: ../../faq/programming.rst:1109 +#, fuzzy +msgid "" +"Abstractions tend to create indirections and force the interpreter to work " +"more. If the levels of indirection outweigh the amount of useful work done, " +"your program will be slower. You should avoid excessive abstraction, " +"especially under the form of tiny functions or methods (which are also often " +"detrimental to readability)." +msgstr "" +"抽象往往會產生間接性並迫使直譯器工作更多。如果間接級別超過了完成的有用工作" +"量，你的程式就會變慢。你應該避免過度抽象，尤其是在微小的函式或方法的形式下" +"（這通常也不利於可讀性）。" + +#: ../../faq/programming.rst:1115 +#, fuzzy +msgid "" +"If you have reached the limit of what pure Python can allow, there are tools " +"to take you further away. For example, `Cython `_ can " +"compile a slightly modified version of Python code into a C extension, and " +"can be used on many different platforms. Cython can take advantage of " +"compilation (and optional type annotations) to make your code significantly " +"faster than when interpreted. If you are confident in your C programming " +"skills, you can also :ref:`write a C extension module ` " +"yourself." +msgstr "" +"如果你已經達到純 Python 所能允許的極限，可以使用一些工具讓你走得更遠。例如，" +"`Cython `_ 可以將稍微修改過的 Python 程式碼編譯成 C 擴" +"充，並且可以在許多不同的平台上使用。Cython 可以利用編譯（和可選的型別註釋）使" +"你的程式碼比解釋時快得多。如果你對自己的 C 程式設計技能有信心，你也可以" +"\\ :ref:`自己編寫一個 C 擴充模組 `。" + +#: ../../faq/programming.rst:1125 +msgid "" +"The wiki page devoted to `performance tips `_." +msgstr "" +"有個 wiki 頁面專門介紹\\ `效能改進小提示 `_。" + +#: ../../faq/programming.rst:1131 +#, fuzzy +msgid "What is the most efficient way to concatenate many strings together?" +msgstr "將多個字串連接在一起的最有效方法是什麼？" + +#: ../../faq/programming.rst:1133 +#, fuzzy +msgid "" +":class:`str` and :class:`bytes` objects are immutable, therefore " +"concatenating many strings together is inefficient as each concatenation " +"creates a new object. In the general case, the total runtime cost is " +"quadratic in the total string length." +msgstr "" +":class:`str` 和 :class:`bytes` 物件是不可變的，因此將多個字串連接在一起效率低" +"下，因為每次連接都會建立一個新物件。在一般情況下，總執行環境 (runtime) 成本是" +"總字串長度的二次方。" + +#: ../../faq/programming.rst:1138 +#, fuzzy +msgid "" +"To accumulate many :class:`str` objects, the recommended idiom is to place " +"them into a list and call :meth:`str.join` at the end::" +msgstr "" +"要累積許多 :class:`str` 物件，推薦的習慣用法是將它們放入list中並在末尾呼" +"叫 :meth:`str.join`： ::" + +#: ../../faq/programming.rst:1141 +msgid "" +"chunks = []\n" +"for s in my_strings:\n" +" chunks.append(s)\n" +"result = ''.join(chunks)" +msgstr "" +"chunks = []\n" +"for s in my_strings:\n" +" chunks.append(s)\n" +"result = ''.join(chunks)" + +#: ../../faq/programming.rst:1146 +#, fuzzy +msgid "(another reasonably efficient idiom is to use :class:`io.StringIO`)" +msgstr "（另一個相當有效的習慣用法是使用 :class:`io.StringIO`）" + +#: ../../faq/programming.rst:1148 +#, fuzzy +msgid "" +"To accumulate many :class:`bytes` objects, the recommended idiom is to " +"extend a :class:`bytearray` object using in-place concatenation (the ``+=`` " +"operator)::" +msgstr "" +"要累積許多 :class:`bytes` 物件，推薦的習慣用法是使用原地連接（``+=`` 運算子）" +"擴充一個 :class:`bytearray` 物件： ::" + +#: ../../faq/programming.rst:1151 +msgid "" +"result = bytearray()\n" +"for b in my_bytes_objects:\n" +" result += b" +msgstr "" +"result = bytearray()\n" +"for b in my_bytes_objects:\n" +" result += b" + +#: ../../faq/programming.rst:1157 +msgid "Sequences (Tuples/Lists)" +msgstr "序列（元組/串列）" + +#: ../../faq/programming.rst:1160 +msgid "How do I convert between tuples and lists?" +msgstr "如何在元組和串列之間進行轉換？" + +#: ../../faq/programming.rst:1162 +msgid "" +"The type constructor ``tuple(seq)`` converts any sequence (actually, any " +"iterable) into a tuple with the same items in the same order." +msgstr "" +"型別建構函式 ``tuple(seq)`` 將任何序列（實際上是任何可疊代物件）轉換為具有相" +"同順序的相同項的元組。" + +#: ../../faq/programming.rst:1165 +#, fuzzy +msgid "" +"For example, ``tuple([1, 2, 3])`` yields ``(1, 2, 3)`` and ``tuple('abc')`` " +"yields ``('a', 'b', 'c')``. If the argument is a tuple, it does not make a " +"copy but returns the same object, so it is cheap to call :func:`tuple` when " +"you aren't sure that an object is already a tuple." +msgstr "" +"例如，``tuple([1, 2, 3])`` 產生 ``(1, 2, 3)`` 而 ``tuple('abc')`` 產生 " +"``('a', 'b ', 'c')``。如果引數是一個元組，它不會復製而是回傳同一個物件，所以" +"當你不確定一個物件是否已經是一個元組時呼叫 :func:`tuple` 是便宜的。" + +#: ../../faq/programming.rst:1170 +#, fuzzy +msgid "" +"The type constructor ``list(seq)`` converts any sequence or iterable into a " +"list with the same items in the same order. For example, ``list((1, 2, " +"3))`` yields ``[1, 2, 3]`` and ``list('abc')`` yields ``['a', 'b', 'c']``. " +"If the argument is a list, it makes a copy just like ``seq[:]`` would." +msgstr "" +"型別建構函式 ``list(seq)`` 將任何序列或可疊代物件轉換為具有相同順序的相同項目" +"的list。例如，``list((1, 2, 3))`` 產生``[1, 2, 3]`` 和``list('abc')`` 產生" +"``['a', 'b ', 'c']``。如果引數是一個list，它會像 ``seq[:]`` 那樣製作一個副" +"本。" + +#: ../../faq/programming.rst:1177 +msgid "What's a negative index?" +msgstr "什麼是負索引？" + +#: ../../faq/programming.rst:1179 +#, fuzzy +msgid "" +"Python sequences are indexed with positive numbers and negative numbers. " +"For positive numbers 0 is the first index 1 is the second index and so " +"forth. For negative indices -1 is the last index and -2 is the penultimate " +"(next to last) index and so forth. Think of ``seq[-n]`` as the same as " +"``seq[len(seq)-n]``." +msgstr "" +"Python 序列使用正數和負數進行索引。對於正數，0 是第一個索引，1 是第二個索引，" +"依此類推。對於負索引，-1 是最後一個索引，-2 是倒數第二個（倒數第二個）索引，" +"依此類推。將 ``seq[-n]`` 視為與 ``seq[len(seq)-n]`` 相同。" + +#: ../../faq/programming.rst:1184 +#, fuzzy +msgid "" +"Using negative indices can be very convenient. For example ``S[:-1]`` is " +"all of the string except for its last character, which is useful for " +"removing the trailing newline from a string." +msgstr "" +"使用負索引會非常方便。例如 ``S[:-1]`` 是除最後一個字元之外的所有字串，這對於" +"從字串中刪除尾隨換行符很有用。" + +#: ../../faq/programming.rst:1190 +#, fuzzy +msgid "How do I iterate over a sequence in reverse order?" +msgstr "如何以相反的順序疊代序列？" + +#: ../../faq/programming.rst:1192 +#, fuzzy +msgid "Use the :func:`reversed` built-in function::" +msgstr "使用 :func:`reversed` 內建函式： ::" + +#: ../../faq/programming.rst:1194 +msgid "" +"for x in reversed(sequence):\n" +" ... # do something with x ..." +msgstr "" + +#: ../../faq/programming.rst:1197 +#, fuzzy +msgid "" +"This won't touch your original sequence, but build a new copy with reversed " +"order to iterate over." +msgstr "這不會觸及你的原始序列，但會構建一個具有相反順序的新副本以進行疊代。" + +#: ../../faq/programming.rst:1202 +msgid "How do you remove duplicates from a list?" +msgstr "如何從串列中刪除重複項？" + +#: ../../faq/programming.rst:1204 +msgid "See the Python Cookbook for a long discussion of many ways to do this:" +msgstr "請參閱 Python Cookbook 以得到有關執行此操作的各種方法的詳細討論：" + +#: ../../faq/programming.rst:1206 +msgid "https://code.activestate.com/recipes/52560/" +msgstr "https://code.activestate.com/recipes/52560/" + +#: ../../faq/programming.rst:1208 +msgid "" +"If you don't mind reordering the list, sort it and then scan from the end of " +"the list, deleting duplicates as you go::" +msgstr "" +"如果你不介意重新排序串列，可以對其進行排序，然後從串列末尾開始掃描，同時刪除" +"重複項： ::" + +#: ../../faq/programming.rst:1211 +msgid "" +"if mylist:\n" +" mylist.sort()\n" +" last = mylist[-1]\n" +" for i in range(len(mylist)-2, -1, -1):\n" +" if last == mylist[i]:\n" +" del mylist[i]\n" +" else:\n" +" last = mylist[i]" +msgstr "" +"if mylist:\n" +" mylist.sort()\n" +" last = mylist[-1]\n" +" for i in range(len(mylist)-2, -1, -1):\n" +" if last == mylist[i]:\n" +" del mylist[i]\n" +" else:\n" +" last = mylist[i]" + +#: ../../faq/programming.rst:1220 +msgid "" +"If all elements of the list may be used as set keys (i.e. they are " +"all :term:`hashable`) this is often faster ::" +msgstr "" +"如果串列的所有元素都可以做為集合的鍵（即它們都必須是 :term:`hashable`），那這" +"通常會更快： ::" + +#: ../../faq/programming.rst:1223 +msgid "mylist = list(set(mylist))" +msgstr "mylist = list(set(mylist))" + +#: ../../faq/programming.rst:1225 +msgid "" +"This converts the list into a set, thereby removing duplicates, and then " +"back into a list." +msgstr "這會將串列轉換為一個集合，從而刪除重複項，然後再轉換回串列。" + +#: ../../faq/programming.rst:1230 +msgid "How do you remove multiple items from a list" +msgstr "如何從串列中刪除多個項目" + +#: ../../faq/programming.rst:1232 +#, fuzzy +msgid "" +"As with removing duplicates, explicitly iterating in reverse with a delete " +"condition is one possibility. However, it is easier and faster to use slice " +"replacement with an implicit or explicit forward iteration. Here are three " +"variations.::" +msgstr "" +"與刪除重複項一樣，使用刪除條件顯式反向疊代是一種可能性。但是，透過隱式或顯式" +"前向疊代使用切片替換更容易和更快。這是三種變體： ::" + +#: ../../faq/programming.rst:1237 +msgid "" +"mylist[:] = filter(keep_function, mylist)\n" +"mylist[:] = (x for x in mylist if keep_condition)\n" +"mylist[:] = [x for x in mylist if keep_condition]" +msgstr "" + +#: ../../faq/programming.rst:1241 +#, fuzzy +msgid "The list comprehension may be fastest." +msgstr "list理解可能是最快的。" + +#: ../../faq/programming.rst:1245 +#, fuzzy +msgid "How do you make an array in Python?" +msgstr "你如何在 Python 中建立數組？" + +#: ../../faq/programming.rst:1247 +#, fuzzy +msgid "Use a list::" +msgstr "使用 list： ::" + +#: ../../faq/programming.rst:1249 +msgid "[\"this\", 1, \"is\", \"an\", \"array\"]" +msgstr "" + +#: ../../faq/programming.rst:1251 +#, fuzzy +msgid "" +"Lists are equivalent to C or Pascal arrays in their time complexity; the " +"primary difference is that a Python list can contain objects of many " +"different types." +msgstr "" +"list在時間複雜度上等同於 C 或 Pascal 數組；主要區別在於 Python list可以包含許" +"多不同型別的物件。" + +#: ../../faq/programming.rst:1254 +#, fuzzy +msgid "" +"The ``array`` module also provides methods for creating arrays of fixed " +"types with compact representations, but they are slower to index than " +"lists. Also note that `NumPy `_ and other third party " +"packages define array-like structures with various characteristics as well." +msgstr "" +"``array`` 模組還提供了建立具有緊湊表示的固定型別數組的方法，但它們的索引速度" +"比list慢。另請注意，`NumPy `_ 和其他第三方包也定義了具有" +"各種特徵的類似數組的結構。" + +#: ../../faq/programming.rst:1260 +#, fuzzy +msgid "" +"To get Lisp-style linked lists, you can emulate *cons cells* using tuples::" +msgstr "要獲得 Lisp 風格的鍊錶，你可以使用元組模擬 *cons cells*： ::" + +#: ../../faq/programming.rst:1262 +msgid "lisp_list = (\"like\", (\"this\", (\"example\", None) ) )" +msgstr "" + +#: ../../faq/programming.rst:1264 +#, fuzzy +msgid "" +"If mutability is desired, you could use lists instead of tuples. Here the " +"analogue of a Lisp *car* is ``lisp_list[0]`` and the analogue of *cdr* is " +"``lisp_list[1]``. Only do this if you're sure you really need to, because " +"it's usually a lot slower than using Python lists." +msgstr "" +"如果需要可變性，你可以使用list而不是元組。這裡 Lisp *car* 的類比是 " +"``lisp_list[0]`` 而 *cdr* 的類比是 ``lisp_list[1]``。只有在確定確實需要時才這" +"樣做，因為它通常比使用 Python list慢很多。" + +#: ../../faq/programming.rst:1273 +msgid "How do I create a multidimensional list?" +msgstr "如何建立多維度串列？" + +#: ../../faq/programming.rst:1275 +msgid "You probably tried to make a multidimensional array like this::" +msgstr "你可能會這樣建立一個多維度陣列： ::" + +#: ../../faq/programming.rst:1277 +msgid ">>> A = [[None] * 2] * 3" +msgstr ">>> A = [[None] * 2] * 3" + +#: ../../faq/programming.rst:1279 +msgid "This looks correct if you print it:" +msgstr "如果你印出它，這看起來是正確的：" + +#: ../../faq/programming.rst:1285 +msgid "" +">>> A\n" +"[[None, None], [None, None], [None, None]]" +msgstr "" +">>> A\n" +"[[None, None], [None, None], [None, None]]" + +#: ../../faq/programming.rst:1290 +msgid "But when you assign a value, it shows up in multiple places:" +msgstr "但是當你賦予一個值時，它會出現在多個地方：" + +#: ../../faq/programming.rst:1296 +msgid "" +">>> A[0][0] = 5\n" +">>> A\n" +"[[5, None], [5, None], [5, None]]" +msgstr "" +">>> A[0][0] = 5\n" +">>> A\n" +"[[5, None], [5, None], [5, None]]" + +#: ../../faq/programming.rst:1302 +msgid "" +"The reason is that replicating a list with ``*`` doesn't create copies, it " +"only creates references to the existing objects. The ``*3`` creates a list " +"containing 3 references to the same list of length two. Changes to one row " +"will show in all rows, which is almost certainly not what you want." +msgstr "" +"原因是複製帶有 ``*`` 的串列不會建立副本，它只會建立對現有物件的參照。``*3`` " +"建立一個串列，其中包含 3 個對長度為 2 的相同串列的參照。對其中一列的變更也將" +"顯示在所有其他列中，而這幾乎不會是你想要的。" + +#: ../../faq/programming.rst:1307 +msgid "" +"The suggested approach is to create a list of the desired length first and " +"then fill in each element with a newly created list::" +msgstr "建議的方法是先建立所需長度的串列，然後用新建立的串列填充每個元素： ::" + +#: ../../faq/programming.rst:1310 +msgid "" +"A = [None] * 3\n" +"for i in range(3):\n" +" A[i] = [None] * 2" +msgstr "" +"A = [None] * 3\n" +"for i in range(3):\n" +" A[i] = [None] * 2" + +#: ../../faq/programming.rst:1314 +msgid "" +"This generates a list containing 3 different lists of length two. You can " +"also use a list comprehension::" +msgstr "" +"這會產生一個包含 3 個長度為 2 的不同串列的串列。你也可以使用串列綜合運算" +"式： ::" + +#: ../../faq/programming.rst:1317 +msgid "" +"w, h = 2, 3\n" +"A = [[None] * w for i in range(h)]" +msgstr "" +"w, h = 2, 3\n" +"A = [[None] * w for i in range(h)]" + +#: ../../faq/programming.rst:1320 +msgid "" +"Or, you can use an extension that provides a matrix datatype; `NumPy " +"`_ is the best known." +msgstr "" +"或者你也可以使用提供矩陣資料型別的擴充套件；`NumPy `_ 是" +"其中最著名的一個。" + +#: ../../faq/programming.rst:1325 +msgid "How do I apply a method or function to a sequence of objects?" +msgstr "如何將方法或函式應用於物件序列？" + +#: ../../faq/programming.rst:1327 +#, fuzzy +msgid "" +"To call a method or function and accumulate the return values is a list, " +"a :term:`list comprehension` is an elegant solution::" +msgstr "" +"呼叫一個方法或函式並累積回傳值是一個list，一個 :term:`list comprehension` 是" +"一個優雅的解決方案： ::" + +#: ../../faq/programming.rst:1330 +msgid "" +"result = [obj.method() for obj in mylist]\n" +"\n" +"result = [function(obj) for obj in mylist]" +msgstr "" +"result = [obj.method() for obj in mylist]\n" +"\n" +"result = [function(obj) for obj in mylist]" + +#: ../../faq/programming.rst:1334 +#, fuzzy +msgid "" +"To just run the method or function without saving the return values, a " +"plain :keyword:`for` loop will suffice::" +msgstr "要只運行方法或函式而不保存回傳值，一個普通的 for 迴圈就足夠了： ::" + +#: ../../faq/programming.rst:1337 +msgid "" +"for obj in mylist:\n" +" obj.method()\n" +"\n" +"for obj in mylist:\n" +" function(obj)" +msgstr "" +"for obj in mylist:\n" +" obj.method()\n" +"\n" +"for obj in mylist:\n" +" function(obj)" + +#: ../../faq/programming.rst:1346 +msgid "" +"Why does a_tuple[i] += ['item'] raise an exception when the addition works?" +msgstr "為什麼 a_tuple[i] += ['item'] 做加法時會引發例外？" + +#: ../../faq/programming.rst:1348 +#, fuzzy +msgid "" +"This is because of a combination of the fact that augmented assignment " +"operators are *assignment* operators, and the difference between mutable and " +"immutable objects in Python." +msgstr "" +"這是因為增強賦值運算子是 *assignment* 運算子這一事實，以及 Python 中可變物件" +"和不可變物件之間的區別。" + +#: ../../faq/programming.rst:1352 +#, fuzzy +msgid "" +"This discussion applies in general when augmented assignment operators are " +"applied to elements of a tuple that point to mutable objects, but we'll use " +"a ``list`` and ``+=`` as our exemplar." +msgstr "" +"當擴充賦值運算子應用於指向可變物件的元組元素時，此討論通常適用，但我們將使用 " +"``list`` 和 ``+=\" 作為範例。" + +#: ../../faq/programming.rst:1356 +msgid "If you wrote::" +msgstr "如果你寫了： ::" + +#: ../../faq/programming.rst:1358 +msgid "" +">>> a_tuple = (1, 2)\n" +">>> a_tuple[0] += 1\n" +"Traceback (most recent call last):\n" +" ...\n" +"TypeError: 'tuple' object does not support item assignment" +msgstr "" +">>> a_tuple = (1, 2)\n" +">>> a_tuple[0] += 1\n" +"Traceback (most recent call last):\n" +" ...\n" +"TypeError: 'tuple' object does not support item assignment" + +#: ../../faq/programming.rst:1364 +#, fuzzy +msgid "" +"The reason for the exception should be immediately clear: ``1`` is added to " +"the object ``a_tuple[0]`` points to (``1``), producing the result object, " +"``2``, but when we attempt to assign the result of the computation, ``2``, " +"to element ``0`` of the tuple, we get an error because we can't change what " +"an element of a tuple points to." +msgstr "" +"例外的原因應該立即清楚：``1`` 被新增到物件``a_tuple[0]`` 指向 (``1``)，產生結" +"果物件，``2``，但是當我們嘗試將計算結果 ``2`` 分配給元組的元素 ``0`` 時，我們" +"會得到一個錯誤，因為我們無法更改元組的元素指向的內容。" + +#: ../../faq/programming.rst:1370 +msgid "" +"Under the covers, what this augmented assignment statement is doing is " +"approximately this::" +msgstr "這個增強賦值陳述式在背後大致是做這些事情： ::" + +#: ../../faq/programming.rst:1373 +msgid "" +">>> result = a_tuple[0] + 1\n" +">>> a_tuple[0] = result\n" +"Traceback (most recent call last):\n" +" ...\n" +"TypeError: 'tuple' object does not support item assignment" +msgstr "" +">>> result = a_tuple[0] + 1\n" +">>> a_tuple[0] = result\n" +"Traceback (most recent call last):\n" +" ...\n" +"TypeError: 'tuple' object does not support item assignment" + +#: ../../faq/programming.rst:1379 +#, fuzzy +msgid "" +"It is the assignment part of the operation that produces the error, since a " +"tuple is immutable." +msgstr "產生錯誤的是操作的賦值部分，因為元組是不可變的。" + +#: ../../faq/programming.rst:1382 +msgid "When you write something like::" +msgstr "當你寫這樣的東西時： ::" + +#: ../../faq/programming.rst:1384 +msgid "" +">>> a_tuple = (['foo'], 'bar')\n" +">>> a_tuple[0] += ['item']\n" +"Traceback (most recent call last):\n" +" ...\n" +"TypeError: 'tuple' object does not support item assignment" +msgstr "" +">>> a_tuple = (['foo'], 'bar')\n" +">>> a_tuple[0] += ['item']\n" +"Traceback (most recent call last):\n" +" ...\n" +"TypeError: 'tuple' object does not support item assignment" + +#: ../../faq/programming.rst:1390 +#, fuzzy +msgid "" +"The exception is a bit more surprising, and even more surprising is the fact " +"that even though there was an error, the append worked::" +msgstr "這個例外有點令人驚訝，更令人驚訝的是即使出現錯誤，追加仍然有效： ::" + +#: ../../faq/programming.rst:1393 +msgid "" +">>> a_tuple[0]\n" +"['foo', 'item']" +msgstr "" +">>> a_tuple[0]\n" +"['foo', 'item']" + +#: ../../faq/programming.rst:1396 +#, fuzzy +msgid "" +"To see why this happens, you need to know that (a) if an object implements " +"an :meth:`~object.__iadd__` magic method, it gets called when the ``+=`` " +"augmented assignment is executed, and its return value is what gets used in " +"the assignment statement; and (b) for lists, :meth:`!__iadd__` is equivalent " +"to calling :meth:`~sequence.extend` on the list and returning the list. " +"That's why we say that for lists, ``+=`` is a \"shorthand\" " +"for :meth:`list.extend`::" +msgstr "" +"要了解為什麼會發生這種情況，你需要知道 (a) 如果一個物件實作了一" +"個 :meth:`~object.__iadd__` 魔術方法，它會在執行 ``+=`` 增廣賦值時被呼叫，並" +"且它的回傳value 是賦值陳述式中使用的值； (b) 對於list，:meth:`!__iadd__` 相當" +"於在list上呼叫 :meth:`!extend` 並回傳list。這就是為什麼我們說對於list，" +"``+=`` 是 :meth:`!list.extend` 的「簡寫」： ::" + +#: ../../faq/programming.rst:1404 +msgid "" +">>> a_list = []\n" +">>> a_list += [1]\n" +">>> a_list\n" +"[1]" +msgstr "" +">>> a_list = []\n" +">>> a_list += [1]\n" +">>> a_list\n" +"[1]" + +#: ../../faq/programming.rst:1409 +msgid "This is equivalent to::" +msgstr "這等價於： ::" + +#: ../../faq/programming.rst:1411 +msgid "" +">>> result = a_list.__iadd__([1])\n" +">>> a_list = result" +msgstr "" +">>> result = a_list.__iadd__([1])\n" +">>> a_list = result" + +#: ../../faq/programming.rst:1414 +#, fuzzy +msgid "" +"The object pointed to by a_list has been mutated, and the pointer to the " +"mutated object is assigned back to ``a_list``. The end result of the " +"assignment is a no-op, since it is a pointer to the same object that " +"``a_list`` was previously pointing to, but the assignment still happens." +msgstr "" +"a_list 指向的物件已經發生變異，指向變異物件的指標被分配回 ``a_list``。賦值的" +"最終結果是空操作，因為它是一個指向與 ``a_list`` 先前指向的同一物件的指標，但" +"賦值仍然發生。" + +#: ../../faq/programming.rst:1419 +msgid "Thus, in our tuple example what is happening is equivalent to::" +msgstr "因此，在我們的元組範例中，發生的事情等同於： ::" + +#: ../../faq/programming.rst:1421 +msgid "" +">>> result = a_tuple[0].__iadd__(['item'])\n" +">>> a_tuple[0] = result\n" +"Traceback (most recent call last):\n" +" ...\n" +"TypeError: 'tuple' object does not support item assignment" +msgstr "" +">>> result = a_tuple[0].__iadd__(['item'])\n" +">>> a_tuple[0] = result\n" +"Traceback (most recent call last):\n" +" ...\n" +"TypeError: 'tuple' object does not support item assignment" + +#: ../../faq/programming.rst:1427 +#, fuzzy +msgid "" +"The :meth:`!__iadd__` succeeds, and thus the list is extended, but even " +"though ``result`` points to the same object that ``a_tuple[0]`` already " +"points to, that final assignment still results in an error, because tuples " +"are immutable." +msgstr "" +":meth:`!__iadd__` 成功，因此list被擴充，但即使 ``result`` 指向與 " +"``a_tuple[0]`` 已經指向的同一個物件，最終的賦值仍然導致一個錯誤，因為元組是不" +"可變的。" + +#: ../../faq/programming.rst:1433 +msgid "" +"I want to do a complicated sort: can you do a Schwartzian Transform in " +"Python?" +msgstr "我想做一個複雜的排序：你能用 Python 做一個 Schwartzian 變換嗎？" + +#: ../../faq/programming.rst:1435 +#, fuzzy +msgid "" +"The technique, attributed to Randal Schwartz of the Perl community, sorts " +"the elements of a list by a metric which maps each element to its \"sort " +"value\". In Python, use the ``key`` argument for the :meth:`list.sort` " +"method::" +msgstr "" +"該技術歸功於 Perl 社區的 Randal Schwartz，它透過將每個元素對映到其「排序值」" +"的度量對串列的元素進行排序。在 Python 中，對 :meth:`list.sort` 方法使用 " +"``key`` 引數： ::" + +#: ../../faq/programming.rst:1439 +msgid "" +"Isorted = L[:]\n" +"Isorted.sort(key=lambda s: int(s[10:15]))" +msgstr "" +"Isorted = L[:]\n" +"Isorted.sort(key=lambda s: int(s[10:15]))" + +#: ../../faq/programming.rst:1444 +msgid "How can I sort one list by values from another list?" +msgstr "如何根據另一個串列中的值對一個串列進行排序？" + +#: ../../faq/programming.rst:1446 +msgid "" +"Merge them into an iterator of tuples, sort the resulting list, and then " +"pick out the element you want. ::" +msgstr "" +"將它們合併到一個元組疊代器中，對結果的串列進行排序，然後挑選出你想要的元" +"素。 ::" + +#: ../../faq/programming.rst:1449 +msgid "" +">>> list1 = [\"what\", \"I'm\", \"sorting\", \"by\"]\n" +">>> list2 = [\"something\", \"else\", \"to\", \"sort\"]\n" +">>> pairs = zip(list1, list2)\n" +">>> pairs = sorted(pairs)\n" +">>> pairs\n" +"[(\"I'm\", 'else'), ('by', 'sort'), ('sorting', 'to'), ('what', " +"'something')]\n" +">>> result = [x[1] for x in pairs]\n" +">>> result\n" +"['else', 'sort', 'to', 'something']" +msgstr "" +">>> list1 = [\"what\", \"I'm\", \"sorting\", \"by\"]\n" +">>> list2 = [\"something\", \"else\", \"to\", \"sort\"]\n" +">>> pairs = zip(list1, list2)\n" +">>> pairs = sorted(pairs)\n" +">>> pairs\n" +"[(\"I'm\", 'else'), ('by', 'sort'), ('sorting', 'to'), ('what', " +"'something')]\n" +">>> result = [x[1] for x in pairs]\n" +">>> result\n" +"['else', 'sort', 'to', 'something']" + +#: ../../faq/programming.rst:1461 +msgid "Objects" +msgstr "物件" + +#: ../../faq/programming.rst:1464 +msgid "What is a class?" +msgstr "什麼是類別 (class)？" + +#: ../../faq/programming.rst:1466 +#, fuzzy +msgid "" +"A class is the particular object type created by executing a class " +"statement. Class objects are used as templates to create instance objects, " +"which embody both the data (attributes) and code (methods) specific to a " +"datatype." +msgstr "" +"類別是透過執行類別陳述式建立的特定物件型別。類別物件用作建立實例物件的模板，" +"實例物件包含特定於資料型別的資料（屬性）和程式碼（方法）。" + +#: ../../faq/programming.rst:1470 +#, fuzzy +msgid "" +"A class can be based on one or more other classes, called its base " +"class(es). It then inherits the attributes and methods of its base classes. " +"This allows an object model to be successively refined by inheritance. You " +"might have a generic ``Mailbox`` class that provides basic accessor methods " +"for a mailbox, and subclasses such as ``MboxMailbox``, ``MaildirMailbox``, " +"``OutlookMailbox`` that handle various specific mailbox formats." +msgstr "" +"一個類別可以基於一個或多個其他類別，稱為它的基底類別。然後它繼承其基底類別的" +"屬性和方法。這允許物件模型透過繼承不斷地細化。你可能有一個通用的 ``Mailbox`` " +"類別，它為郵箱提供基本的存取器方法，以及處理各種特定郵箱格式的子類別，例如 " +"``MboxMailbox`` 、 ``MaildirMailbox`` 、 ``OutlookMailbox`` 。" + +#: ../../faq/programming.rst:1479 +msgid "What is a method?" +msgstr "什麼是方法 (method)？" + +#: ../../faq/programming.rst:1481 +#, fuzzy +msgid "" +"A method is a function on some object ``x`` that you normally call as " +"``x.name(arguments...)``. Methods are defined as functions inside the class " +"definition::" +msgstr "" +"方法是一些物件 ``x`` 上的函式，你通常將其稱為 ``x.name(arguments...)`` 。方法" +"在類別定義中被定義為函式： ::" + +#: ../../faq/programming.rst:1485 +msgid "" +"class C:\n" +" def meth(self, arg):\n" +" return arg * 2 + self.attribute" +msgstr "" +"class C:\n" +" def meth(self, arg):\n" +" return arg * 2 + self.attribute" + +#: ../../faq/programming.rst:1491 +msgid "What is self?" +msgstr "什麼是 self？" + +#: ../../faq/programming.rst:1493 +msgid "" +"Self is merely a conventional name for the first argument of a method. A " +"method defined as ``meth(self, a, b, c)`` should be called as ``x.meth(a, b, " +"c)`` for some instance ``x`` of the class in which the definition occurs; " +"the called method will think it is called as ``meth(x, a, b, c)``." +msgstr "" +"Self 只是方法第一個引數的約定名稱。對於所定義類別的某個實例 ``x``，一個定義" +"為 ``meth(self, a, b, c)`` 的方法應該以 ``x.meth(a, b, c)`` 形式來呼叫；被呼" +"叫的方法會認為它是以 ``meth(x, a, b, c)`` 來呼叫的。" + +#: ../../faq/programming.rst:1498 +msgid "See also :ref:`why-self`." +msgstr "另請參閱 :ref:`why-self`。" + +#: ../../faq/programming.rst:1502 +msgid "" +"How do I check if an object is an instance of a given class or of a subclass " +"of it?" +msgstr "如何檢查物件是否是給定類別的實例或其子類別的實例？" + +#: ../../faq/programming.rst:1504 +#, fuzzy +msgid "" +"Use the built-in function :func:`isinstance(obj, cls) `. You " +"can check if an object is an instance of any of a number of classes by " +"providing a tuple instead of a single class, e.g. ``isinstance(obj, (class1, " +"class2, ...))``, and can also check whether an object is one of Python's " +"built-in types, e.g. ``isinstance(obj, str)`` or ``isinstance(obj, (int, " +"float, complex))``." +msgstr "" +"使用內建函式 :func:`isinstance(obj, cls) `。你可以透過提供元組而" +"不是單個類別來檢查物件是否是多個類別中的任何一個的實例，例如" +"``isinstance(obj, (class1, class2, ...))``，還可以檢查物件是否是 Python 的內" +"置型別之一，例如``isinstance(obj, str)`` 或 ``isinstance(obj, (int, float, " +"complex))``。" + +#: ../../faq/programming.rst:1511 +msgid "" +"Note that :func:`isinstance` also checks for virtual inheritance from " +"an :term:`abstract base class`. So, the test will return ``True`` for a " +"registered class even if hasn't directly or indirectly inherited from it. " +"To test for \"true inheritance\", scan the :term:`MRO` of the class:" +msgstr "" +"請注意，:func:`isinstance` 還會檢查來自\\ :term:`抽象基底類別 (abstract base " +"class) ` 的虛擬繼承。因此對已註冊類別的檢驗會回傳 " +"``True``，即使沒有直接或間接繼承自它。要測試「真正繼承」，請掃描該類別" +"的 :term:`MRO`：" + +#: ../../faq/programming.rst:1516 +msgid "" +"from collections.abc import Mapping\n" +"\n" +"class P:\n" +" pass\n" +"\n" +"class C(P):\n" +" pass\n" +"\n" +"Mapping.register(P)" +msgstr "" +"from collections.abc import Mapping\n" +"\n" +"class P:\n" +" pass\n" +"\n" +"class C(P):\n" +" pass\n" +"\n" +"Mapping.register(P)" + +#: ../../faq/programming.rst:1528 +msgid "" +">>> c = C()\n" +">>> isinstance(c, C) # direct\n" +"True\n" +">>> isinstance(c, P) # indirect\n" +"True\n" +">>> isinstance(c, Mapping) # virtual\n" +"True\n" +"\n" +"# Actual inheritance chain\n" +">>> type(c).__mro__\n" +"(, , )\n" +"\n" +"# Test for \"true inheritance\"\n" +">>> Mapping in type(c).__mro__\n" +"False" +msgstr "" +">>> c = C()\n" +">>> isinstance(c, C) # 直接\n" +"True\n" +">>> isinstance(c, P) # 間接\n" +"True\n" +">>> isinstance(c, Mapping) # 虛擬\n" +"True\n" +"\n" +"# 實際的繼承鏈結\n" +">>> type(c).__mro__\n" +"(, , )\n" +"\n" +"# 「真正繼承」的檢驗\n" +">>> Mapping in type(c).__mro__\n" +"False" + +#: ../../faq/programming.rst:1546 +#, fuzzy +msgid "" +"Note that most programs do not use :func:`isinstance` on user-defined " +"classes very often. If you are developing the classes yourself, a more " +"proper object-oriented style is to define methods on the classes that " +"encapsulate a particular behaviour, instead of checking the object's class " +"and doing a different thing based on what class it is. For example, if you " +"have a function that does something::" +msgstr "" +"請注意，大多數程式不會經常在使用者定義的類別上使用 :func:`isinstance`。如果你" +"自己開發類別，更合適的面向物件風格是在封裝特定行為的類別上定義方法，而不是檢" +"查物件的類別並根據它是什麼類別做不同的事情。例如，如果你有一個函式做某事： ::" + +#: ../../faq/programming.rst:1553 +msgid "" +"def search(obj):\n" +" if isinstance(obj, Mailbox):\n" +" ... # code to search a mailbox\n" +" elif isinstance(obj, Document):\n" +" ... # code to search a document\n" +" elif ..." +msgstr "" +"def search(obj):\n" +" if isinstance(obj, Mailbox):\n" +" ... # 搜尋信箱的程式碼\n" +" elif isinstance(obj, Document):\n" +" ... # 搜尋文件的程式碼\n" +" elif ..." + +#: ../../faq/programming.rst:1560 +msgid "" +"A better approach is to define a ``search()`` method on all the classes and " +"just call it::" +msgstr "更好的方法是在所有類別上定義一個 ``search()`` 方法然後呼叫它： ::" + +#: ../../faq/programming.rst:1563 +msgid "" +"class Mailbox:\n" +" def search(self):\n" +" ... # code to search a mailbox\n" +"\n" +"class Document:\n" +" def search(self):\n" +" ... # code to search a document\n" +"\n" +"obj.search()" +msgstr "" +"class Mailbox:\n" +" def search(self):\n" +" ... # 搜尋信箱的程式碼\n" +"\n" +"class Document:\n" +" def search(self):\n" +" ... # 搜尋文件的程式碼\n" +"\n" +"obj.search()" + +#: ../../faq/programming.rst:1575 +msgid "What is delegation?" +msgstr "什麼是委派 (delegation)？" + +#: ../../faq/programming.rst:1577 +msgid "" +"Delegation is an object oriented technique (also called a design pattern). " +"Let's say you have an object ``x`` and want to change the behaviour of just " +"one of its methods. You can create a new class that provides a new " +"implementation of the method you're interested in changing and delegates all " +"other methods to the corresponding method of ``x``." +msgstr "" +"委派是一種物件導向的技法（也稱為設計模式）。假設你有一個物件 ``x`` 並且只想更" +"改其中一個方法的行為。你可以建立一個新類別，它提供你想改變的那個方法的新實" +"作，並將所有其他方法委派給 ``x`` 的相應方法。" + +#: ../../faq/programming.rst:1583 +msgid "" +"Python programmers can easily implement delegation. For example, the " +"following class implements a class that behaves like a file but converts all " +"written data to uppercase::" +msgstr "" +"Python 程式設計師可以輕鬆地實作委派。舉例來說，以下類別實作了一個行為類似檔案" +"的類別，但將所有寫入的資料轉換為大寫：" + +#: ../../faq/programming.rst:1587 +msgid "" +"class UpperOut:\n" +"\n" +" def __init__(self, outfile):\n" +" self._outfile = outfile\n" +"\n" +" def write(self, s):\n" +" self._outfile.write(s.upper())\n" +"\n" +" def __getattr__(self, name):\n" +" return getattr(self._outfile, name)" +msgstr "" +"class UpperOut:\n" +"\n" +" def __init__(self, outfile):\n" +" self._outfile = outfile\n" +"\n" +" def write(self, s):\n" +" self._outfile.write(s.upper())\n" +"\n" +" def __getattr__(self, name):\n" +" return getattr(self._outfile, name)" + +#: ../../faq/programming.rst:1598 +#, fuzzy +msgid "" +"Here the ``UpperOut`` class redefines the ``write()`` method to convert the " +"argument string to uppercase before calling the underlying " +"``self._outfile.write()`` method. All other methods are delegated to the " +"underlying ``self._outfile`` object. The delegation is accomplished via " +"the :meth:`~object.__getattr__` method; consult :ref:`the language reference " +"` for more information about controlling attribute access." +msgstr "" +"這裡的 ``UpperOut`` 類別重新定義了``write()`` 方法，在呼叫底層的" +"``self._outfile.write()`` 方法之前將引數字串轉換為大寫。所有其他方法都委託給" +"底層的 ``self._outfile`` 物件。委託是透過 :meth:`~object.__getattr__` 方法完" +"成的；有關控制屬性存取的更多資訊，請參閱語言參考 。" + +#: ../../faq/programming.rst:1605 +#, fuzzy +msgid "" +"Note that for more general cases delegation can get trickier. When " +"attributes must be set as well as retrieved, the class must define " +"a :meth:`~object.__setattr__` method too, and it must do so carefully. The " +"basic implementation of :meth:`!__setattr__` is roughly equivalent to the " +"following::" +msgstr "" +"請注意，對於更一般的情況，委託可能會變得更加棘手。當必須設定和檢索屬性時，該" +"類別也必須定義一個 :meth:`~object.__setattr__` 方法，而且必須小心謹" +"慎。 :meth:`!__setattr__` 的基本實作大致等同於以下： ::" + +#: ../../faq/programming.rst:1610 +msgid "" +"class X:\n" +" ...\n" +" def __setattr__(self, name, value):\n" +" self.__dict__[name] = value\n" +" ..." +msgstr "" +"class X:\n" +" ...\n" +" def __setattr__(self, name, value):\n" +" self.__dict__[name] = value\n" +" ..." + +#: ../../faq/programming.rst:1616 +msgid "" +"Many :meth:`~object.__setattr__` implementations call :meth:`!" +"object.__setattr__` to set an attribute on self without causing infinite " +"recursion::" +msgstr "" +"許多 :meth:`~object.__setattr__` 的實作會呼叫 :meth:`!object.__setattr__` 以" +"設定 self 的屬性，而不會導致無限遞迴。" + +#: ../../faq/programming.rst:1619 +msgid "" +"class X:\n" +" def __setattr__(self, name, value):\n" +" # Custom logic here...\n" +" object.__setattr__(self, name, value)" +msgstr "" +"class X:\n" +" def __setattr__(self, name, value):\n" +" # 自訂邏輯放在這裡...\n" +" object.__setattr__(self, name, value)" + +#: ../../faq/programming.rst:1624 +msgid "" +"Alternatively, it is possible to set attributes by inserting entries " +"into :attr:`self.__dict__ ` directly." +msgstr "" + +#: ../../faq/programming.rst:1629 +#, fuzzy +msgid "" +"How do I call a method defined in a base class from a derived class that " +"extends it?" +msgstr "如何從擴充它的衍生類別呼叫基底類別中定義的方法？" + +#: ../../faq/programming.rst:1631 +msgid "Use the built-in :func:`super` function::" +msgstr "使用內建的 :func:`super` 函式： ::" + +#: ../../faq/programming.rst:1633 +msgid "" +"class Derived(Base):\n" +" def meth(self):\n" +" super().meth() # calls Base.meth" +msgstr "" +"class Derived(Base):\n" +" def meth(self):\n" +" super().meth() # 呼叫 Base.meth" + +#: ../../faq/programming.rst:1637 +msgid "" +"In the example, :func:`super` will automatically determine the instance from " +"which it was called (the ``self`` value), look up the :term:`method " +"resolution order` (MRO) with ``type(self).__mro__``, and return the next in " +"line after ``Derived`` in the MRO: ``Base``." +msgstr "" + +#: ../../faq/programming.rst:1644 +msgid "How can I organize my code to make it easier to change the base class?" +msgstr "我可以如何組織我的程式碼以使得更改基底類別變的更容易？" + +#: ../../faq/programming.rst:1646 +#, fuzzy +msgid "" +"You could assign the base class to an alias and derive from the alias. Then " +"all you have to change is the value assigned to the alias. Incidentally, " +"this trick is also handy if you want to decide dynamically (e.g. depending " +"on availability of resources) which base class to use. Example::" +msgstr "" +"你可以將基底類別分配給別名並從別名衍生。然後，你只需更改分配給別名的值。順便" +"說一句，如果你想動態決定（例如，取決於資源的可用性）使用哪個基底類別，這個技" +"巧也很方便。例子： ::" + +#: ../../faq/programming.rst:1651 +msgid "" +"class Base:\n" +" ...\n" +"\n" +"BaseAlias = Base\n" +"\n" +"class Derived(BaseAlias):\n" +" ..." +msgstr "" +"class Base:\n" +" ...\n" +"\n" +"BaseAlias = Base\n" +"\n" +"class Derived(BaseAlias):\n" +" ..." + +#: ../../faq/programming.rst:1661 +msgid "How do I create static class data and static class methods?" +msgstr "如何建立靜態類別資料和靜態類別方法？" + +#: ../../faq/programming.rst:1663 +msgid "" +"Both static data and static methods (in the sense of C++ or Java) are " +"supported in Python." +msgstr "Python 支援靜態資料和靜態方法（在 C++ 或 Java 的意義上）。" + +#: ../../faq/programming.rst:1666 +msgid "" +"For static data, simply define a class attribute. To assign a new value to " +"the attribute, you have to explicitly use the class name in the assignment::" +msgstr "" +"對於靜態資料，只需定義一個類別屬性即可。要為屬性分配新值，你必須在分配中顯式" +"使用類別名稱： ::" + +#: ../../faq/programming.rst:1669 +msgid "" +"class C:\n" +" count = 0 # number of times C.__init__ called\n" +"\n" +" def __init__(self):\n" +" C.count = C.count + 1\n" +"\n" +" def getcount(self):\n" +" return C.count # or return self.count" +msgstr "" +"class C:\n" +" count = 0 # C.__init__ 被呼叫的次數\n" +"\n" +" def __init__(self):\n" +" C.count = C.count + 1\n" +"\n" +" def getcount(self):\n" +" return C.count # 或回傳 self.count" + +#: ../../faq/programming.rst:1678 +msgid "" +"``c.count`` also refers to ``C.count`` for any ``c`` such that " +"``isinstance(c, C)`` holds, unless overridden by ``c`` itself or by some " +"class on the base-class search path from ``c.__class__`` back to ``C``." +msgstr "" +"``c.count`` 還指代任何 ``c`` 的 ``C.count`` 使得 ``isinstance(c, C)`` 成立，" +"除非被 ``c`` 本身或某些人覆蓋從 ``c.__class__`` 回到 ``C`` 的基底類別搜尋路徑" +"上的類別。" + +#: ../../faq/programming.rst:1682 +#, fuzzy +msgid "" +"Caution: within a method of C, an assignment like ``self.count = 42`` " +"creates a new and unrelated instance named \"count\" in ``self``'s own " +"dict. Rebinding of a class-static data name must always specify the class " +"whether inside a method or not::" +msgstr "" +"注意：在 C 的方法中，像 self.count = 42 這樣的賦值會在 self 自己的字典中建立" +"一個名為 \"count\" 的新的不相關實例。類別靜態資料名稱的重新綁定必須始終指定類" +"別是否在方法內： ::" + +#: ../../faq/programming.rst:1687 +msgid "C.count = 314" +msgstr "C.count = 314" + +#: ../../faq/programming.rst:1689 +msgid "Static methods are possible::" +msgstr "靜態方法是可能的： ::" + +#: ../../faq/programming.rst:1691 +msgid "" +"class C:\n" +" @staticmethod\n" +" def static(arg1, arg2, arg3):\n" +" # No 'self' parameter!\n" +" ..." +msgstr "" +"class C:\n" +" @staticmethod\n" +" def static(arg1, arg2, arg3):\n" +" # 沒有 'self' 參數！\n" +" ..." + +#: ../../faq/programming.rst:1697 +#, fuzzy +msgid "" +"However, a far more straightforward way to get the effect of a static method " +"is via a simple module-level function::" +msgstr "" +"然而，獲得靜態方法效果的一種更直接的方法是透過一個簡單的模組級函式： ::" + +#: ../../faq/programming.rst:1700 +msgid "" +"def getcount():\n" +" return C.count" +msgstr "" +"def getcount():\n" +" return C.count" + +#: ../../faq/programming.rst:1703 +#, fuzzy +msgid "" +"If your code is structured so as to define one class (or tightly related " +"class hierarchy) per module, this supplies the desired encapsulation." +msgstr "" +"如果你的程式碼結構化以便為每個模組定義一個類別（或緊密相關的類別層次結構），" +"則這提供了所需的封裝。" + +#: ../../faq/programming.rst:1708 +msgid "How can I overload constructors (or methods) in Python?" +msgstr "如何在 Python 中多載 (overload) 建構函式（或方法）？" + +#: ../../faq/programming.rst:1710 +msgid "" +"This answer actually applies to all methods, but the question usually comes " +"up first in the context of constructors." +msgstr "" +"這個答案實際上適用於所有方法，但這個問題通常會先出現在建構函式的情境中。" + +#: ../../faq/programming.rst:1713 +msgid "In C++ you'd write" +msgstr "在 C++ 中你會寫成" + +#: ../../faq/programming.rst:1715 +msgid "" +"class C {\n" +" C() { cout << \"No arguments\\n\"; }\n" +" C(int i) { cout << \"Argument is \" << i << \"\\n\"; }\n" +"}" +msgstr "" +"class C {\n" +" C() { cout << \"No arguments\\n\"; }\n" +" C(int i) { cout << \"Argument is \" << i << \"\\n\"; }\n" +"}" + +#: ../../faq/programming.rst:1722 +msgid "" +"In Python you have to write a single constructor that catches all cases " +"using default arguments. For example::" +msgstr "" +"在 Python 中，你必須編寫一個建構函式來捕獲所有使用預設引數的情況。例如： ::" + +#: ../../faq/programming.rst:1725 +msgid "" +"class C:\n" +" def __init__(self, i=None):\n" +" if i is None:\n" +" print(\"No arguments\")\n" +" else:\n" +" print(\"Argument is\", i)" +msgstr "" +"class C:\n" +" def __init__(self, i=None):\n" +" if i is None:\n" +" print(\"No arguments\")\n" +" else:\n" +" print(\"Argument is\", i)" + +#: ../../faq/programming.rst:1732 +msgid "This is not entirely equivalent, but close enough in practice." +msgstr "這並不完全等價，但在實際情況中已夠接近。" + +#: ../../faq/programming.rst:1734 +msgid "You could also try a variable-length argument list, e.g. ::" +msgstr "你也可以嘗試長度可變的引數串列，例如： ::" + +#: ../../faq/programming.rst:1736 +msgid "" +"def __init__(self, *args):\n" +" ..." +msgstr "" +"def __init__(self, *args):\n" +" ..." + +#: ../../faq/programming.rst:1739 +msgid "The same approach works for all method definitions." +msgstr "相同的手段適用於所有方法的定義。" + +#: ../../faq/programming.rst:1743 +msgid "I try to use __spam and I get an error about _SomeClassName__spam." +msgstr "我嘗試使用 __spam，但收到有關 _SomeClassName__spam 的錯誤。" + +#: ../../faq/programming.rst:1745 +msgid "" +"Variable names with double leading underscores are \"mangled\" to provide a " +"simple but effective way to define class private variables. Any identifier " +"of the form ``__spam`` (at least two leading underscores, at most one " +"trailing underscore) is textually replaced with ``_classname__spam``, where " +"``classname`` is the current class name with any leading underscores " +"stripped." +msgstr "" +"帶有雙前導底線的變數名會被「破壞 (mangled)」以做為提供定義類別私有變數的一個" +"簡單但有效的方法。``__spam`` 形式的任何識別字（至少兩個前導底線，最多一個尾隨" +"底線）在文字上會被替換為 ``_classname__spam``，其中 ``classname`` 是目前類別" +"之所有前導底線被去除的名稱。" + +#: ../../faq/programming.rst:1751 +msgid "" +"The identifier can be used unchanged within the class, but to access it " +"outside the class, the mangled name must be used:" +msgstr "" + +#: ../../faq/programming.rst:1754 +msgid "" +"class A:\n" +" def __one(self):\n" +" return 1\n" +" def two(self):\n" +" return 2 * self.__one()\n" +"\n" +"class B(A):\n" +" def three(self):\n" +" return 3 * self._A__one()\n" +"\n" +"four = 4 * A()._A__one()" +msgstr "" +"class A:\n" +" def __one(self):\n" +" return 1\n" +" def two(self):\n" +" return 2 * self.__one()\n" +"\n" +"class B(A):\n" +" def three(self):\n" +" return 3 * self._A__one()\n" +"\n" +"four = 4 * A()._A__one()" + +#: ../../faq/programming.rst:1768 +#, fuzzy +msgid "" +"In particular, this does not guarantee privacy since an outside user can " +"still deliberately access the private attribute; many Python programmers " +"never bother to use private variable names at all." +msgstr "" +"這並不能保證隱私：外部使用者仍然可以故意存取 \"_classname__spam\" 屬性，並且" +"私有值在物件的 __dict__ 中可見。許多 Python 程式員根本懶得使用私有變數名。" + +#: ../../faq/programming.rst:1774 +msgid "" +"The :ref:`private name mangling specifications ` for " +"details and special cases." +msgstr "" + +#: ../../faq/programming.rst:1778 +msgid "My class defines __del__ but it is not called when I delete the object." +msgstr "我的類別定義了 __del__ 但是當我刪除物件時它沒有被呼叫。" + +#: ../../faq/programming.rst:1780 +msgid "There are several possible reasons for this." +msgstr "這有幾個可能的原因。" + +#: ../../faq/programming.rst:1782 +msgid "" +"The :keyword:`del` statement does not necessarily " +"call :meth:`~object.__del__` -- it simply decrements the object's reference " +"count, and if this reaches zero :meth:`!__del__` is called." +msgstr "" +":keyword:`del` 陳述式不一定會呼叫 :meth:`~object.__del__` -- 它只是減少物件的" +"參照計數，如果達到零則呼叫 :meth:`!__del__`。" + +#: ../../faq/programming.rst:1786 +#, fuzzy +msgid "" +"If your data structures contain circular links (e.g. a tree where each child " +"has a parent reference and each parent has a list of children) the reference " +"counts will never go back to zero. Once in a while Python runs an algorithm " +"to detect such cycles, but the garbage collector might run some time after " +"the last reference to your data structure vanishes, so your :meth:`!__del__` " +"method may be called at an inconvenient and random time. This is " +"inconvenient if you're trying to reproduce a problem. Worse, the order in " +"which object's :meth:`!__del__` methods are executed is arbitrary. You can " +"run :func:`gc.collect` to force a collection, but there *are* pathological " +"cases where objects will never be collected." +msgstr "" +"如果你的資料結構包含循環鏈接（例如，一棵樹，其中每個子項都有一個父項參照，每" +"個父項都有一個子項list），參照計數將永遠不會回到零。 Python 偶爾會運行一種演" +"算法來檢測此類別循環，但垃圾收集器可能會在對你的資料結構的最後一次參照消失後" +"運行一段時間，因此你的 :meth:`!__del__` 方法可能會在不方便且隨機的時間呼叫.如" +"果你試圖重現問題，這會很不方便。更糟糕的是，物件的 :meth:`!__del__` 方法的執" +"行順序是任意的。你可以運行 :func:`gc.collect` 來強制收集，但*存在*永遠不會收" +"集物件的病態情況。" + +#: ../../faq/programming.rst:1797 +#, fuzzy +msgid "" +"Despite the cycle collector, it's still a good idea to define an explicit " +"``close()`` method on objects to be called whenever you're done with them. " +"The ``close()`` method can then remove attributes that refer to subobjects. " +"Don't call :meth:`!__del__` directly -- :meth:`!__del__` should call " +"``close()`` and ``close()`` should make sure that it can be called more than " +"once for the same object." +msgstr "" +"儘管有循環收集器，但在物件上定義一個顯式的 ``close()`` 方法仍然是一個好主意，" +"以便在你完成使用它們時呼叫它們。然後，``close()`` 方法可以刪除參照子物件的屬" +"性。不要直接呼叫 :meth:`!__del__` -- :meth:`!__del__` 應該呼叫 ``close()`` 並" +"且 ``close()`` 應該確保它可以多次呼叫同一個物件。" + +#: ../../faq/programming.rst:1804 +#, fuzzy +msgid "" +"Another way to avoid cyclical references is to use the :mod:`weakref` " +"module, which allows you to point to objects without incrementing their " +"reference count. Tree data structures, for instance, should use weak " +"references for their parent and sibling references (if they need them!)." +msgstr "" +"另一種避免循環參照的方法是使用 :mod:`weakref` 模組，它允許你在不增加參照計數" +"的情況下指向物件。例如，樹資料結構應該對其父參照和同級參照使用弱參照（如果需" +"要的話！）。" + +#: ../../faq/programming.rst:1817 +msgid "" +"Finally, if your :meth:`!__del__` method raises an exception, a warning " +"message is printed to :data:`sys.stderr`." +msgstr "" +"最後，如果你的 :meth:`!__del__` 方法引發例外，則會將一條警告訊息印出" +"到 :data:`sys.stderr`。" + +#: ../../faq/programming.rst:1822 +msgid "How do I get a list of all instances of a given class?" +msgstr "我該如何取得給定類別的所有實例的串列？" + +#: ../../faq/programming.rst:1824 +msgid "" +"Python does not keep track of all instances of a class (or of a built-in " +"type). You can program the class's constructor to keep track of all " +"instances by keeping a list of weak references to each instance." +msgstr "" +"Python 不會追蹤類別（或內建型別）的所有實例。你可以將類別的建構函式進行改寫，" +"以透過保留對每個實例之弱參照串列來追蹤所有實例。" + +#: ../../faq/programming.rst:1830 +msgid "Why does the result of ``id()`` appear to be not unique?" +msgstr "為什麼 ``id()`` 的結果看起來不唯一？" + +#: ../../faq/programming.rst:1832 +#, fuzzy +msgid "" +"The :func:`id` builtin returns an integer that is guaranteed to be unique " +"during the lifetime of the object. Since in CPython, this is the object's " +"memory address, it happens frequently that after an object is deleted from " +"memory, the next freshly created object is allocated at the same position in " +"memory. This is illustrated by this example:" +msgstr "" +":func:`id` 內建函式回傳一個整數，保證在物件的生命週期內是唯一的。因為在 " +"CPython 中，這是物件的記憶體地址，所以經常發生在從記憶體中刪除一個物件後，下" +"一個新建立的物件被分配在記憶體中的相同位置。這個例子說明了這一點：" + +#: ../../faq/programming.rst:1843 +#, fuzzy +msgid "" +"The two ids belong to different integer objects that are created before, and " +"deleted immediately after execution of the ``id()`` call. To be sure that " +"objects whose id you want to examine are still alive, create another " +"reference to the object:" +msgstr "" +"這兩個 id 屬於之前建立的不同整數物件，並在執行 ``id()`` 呼叫後立即刪除。要確" +"保你要檢查其 id 的物件仍然存在，請建立對該物件的另一個參照：" + +#: ../../faq/programming.rst:1856 +msgid "When can I rely on identity tests with the *is* operator?" +msgstr "我什麼時候可以依靠 *is* 運算子進行識別性測試？" + +#: ../../faq/programming.rst:1858 +msgid "" +"The ``is`` operator tests for object identity. The test ``a is b`` is " +"equivalent to ``id(a) == id(b)``." +msgstr "" +"``is`` 運算子測試物件識別性。測試 ``a is b`` 等同於 ``id(a) == id(b)`` 。" + +#: ../../faq/programming.rst:1861 +msgid "" +"The most important property of an identity test is that an object is always " +"identical to itself, ``a is a`` always returns ``True``. Identity tests are " +"usually faster than equality tests. And unlike equality tests, identity " +"tests are guaranteed to return a boolean ``True`` or ``False``." +msgstr "" +"識別性測試最重要的屬性是物件始終與自身相同， ``a is a`` 總是回傳 ``True`` 。" +"識別性測試通常比相等性測試更快。與相等性測試不同，識別性測試保證回傳布林值 " +"``True`` 或 ``False`` 。" + +#: ../../faq/programming.rst:1866 +msgid "" +"However, identity tests can *only* be substituted for equality tests when " +"object identity is assured. Generally, there are three circumstances where " +"identity is guaranteed:" +msgstr "" +"然而，*只有*\\ 當物件識別性得到保證時，識別性測試才能代替相等性測試。一般來" +"說，保證識別性的情況有以下三種：" + +#: ../../faq/programming.rst:1870 +#, fuzzy +msgid "" +"Assignments create new names but do not change object identity. After the " +"assignment ``new = old``, it is guaranteed that ``new is old``." +msgstr "" +"1) 賦值建立新名稱但不改變物件識別性。賦值 ``new = old`` 後，保證 ``new is " +"old``。" + +#: ../../faq/programming.rst:1873 +#, fuzzy +msgid "" +"Putting an object in a container that stores object references does not " +"change object identity. After the list assignment ``s[0] = x``, it is " +"guaranteed that ``s[0] is x``." +msgstr "" +"2) 將物件放入儲存物件參照的容器中不會改變物件識別性。在 list 賦值 ``s[0] = " +"x`` 之後，保證 ``s[0] 是 x``。" + +#: ../../faq/programming.rst:1877 +#, fuzzy +msgid "" +"If an object is a singleton, it means that only one instance of that object " +"can exist. After the assignments ``a = None`` and ``b = None``, it is " +"guaranteed that ``a is b`` because ``None`` is a singleton." +msgstr "" +"3）如果一個物件是單例，則意味著該物件只能存在一個實例。在賦值 ``a = None`` " +"和 ``b = None`` 之後，可以保證 ``a is b`` 因為 ``None`` 是單例。" + +#: ../../faq/programming.rst:1881 +msgid "" +"In most other circumstances, identity tests are inadvisable and equality " +"tests are preferred. In particular, identity tests should not be used to " +"check constants such as :class:`int` and :class:`str` which aren't " +"guaranteed to be singletons::" +msgstr "" +"在大多數其他情況下，識別性測試是不可取的，相等性測試是首選。特別是，識別性測" +"試不應用於檢查常數，例如不能保證是單例的 :class:`int` 和 :class:`str`： ::" + +#: ../../faq/programming.rst:1886 +msgid "" +">>> a = 1000\n" +">>> b = 500\n" +">>> c = b + 500\n" +">>> a is c\n" +"False\n" +"\n" +">>> a = 'Python'\n" +">>> b = 'Py'\n" +">>> c = b + 'thon'\n" +">>> a is c\n" +"False" +msgstr "" +">>> a = 1000\n" +">>> b = 500\n" +">>> c = b + 500\n" +">>> a is c\n" +"False\n" +"\n" +">>> a = 'Python'\n" +">>> b = 'Py'\n" +">>> c = b + 'thon'\n" +">>> a is c\n" +"False" + +#: ../../faq/programming.rst:1898 +msgid "Likewise, new instances of mutable containers are never identical::" +msgstr "同樣地，可變容器的新實例永遠不會相同： ::" + +#: ../../faq/programming.rst:1900 +msgid "" +">>> a = []\n" +">>> b = []\n" +">>> a is b\n" +"False" +msgstr "" +">>> a = []\n" +">>> b = []\n" +">>> a is b\n" +"False" + +#: ../../faq/programming.rst:1905 +msgid "" +"In the standard library code, you will see several common patterns for " +"correctly using identity tests:" +msgstr "在標準函式庫程式碼中，你將看到幾種正確使用識別性測試的常見模式：" + +#: ../../faq/programming.rst:1908 +msgid "" +"As recommended by :pep:`8`, an identity test is the preferred way to check " +"for ``None``. This reads like plain English in code and avoids confusion " +"with other objects that may have boolean values that evaluate to false." +msgstr "" +"正如 :pep:`8` 所推薦的，識別性測試是檢查 ``None`` 的首選方法。這在程式碼中讀" +"起來像簡單的英語，並避免與其他可能具有評估為 false 的布林值的物件混淆。" + +#: ../../faq/programming.rst:1912 +#, fuzzy +msgid "" +"Detecting optional arguments can be tricky when ``None`` is a valid input " +"value. In those situations, you can create a singleton sentinel object " +"guaranteed to be distinct from other objects. For example, here is how to " +"implement a method that behaves like :meth:`dict.pop`:" +msgstr "" +"當 ``None`` 是有效輸入值時，檢測可選引數可能會很棘手。在這些情況下，你可以建" +"立一個保證與其他物件不同的單例哨兵物件。例如，這裡是如何實作一個行為類似" +"於 :meth:`dict.pop` 的方法：" + +#: ../../faq/programming.rst:1917 +msgid "" +"_sentinel = object()\n" +"\n" +"def pop(self, key, default=_sentinel):\n" +" if key in self:\n" +" value = self[key]\n" +" del self[key]\n" +" return value\n" +" if default is _sentinel:\n" +" raise KeyError(key)\n" +" return default" +msgstr "" +"_sentinel = object()\n" +"\n" +"def pop(self, key, default=_sentinel):\n" +" if key in self:\n" +" value = self[key]\n" +" del self[key]\n" +" return value\n" +" if default is _sentinel:\n" +" raise KeyError(key)\n" +" return default" + +#: ../../faq/programming.rst:1930 +msgid "" +"Container implementations sometimes need to augment equality tests with " +"identity tests. This prevents the code from being confused by objects such " +"as ``float('NaN')`` that are not equal to themselves." +msgstr "" +"容器實作有時需要透過識別性測試來增強相等性測試。這可以防止程式碼被諸如 " +"float('NaN') 之類的不等於自身的物件所混淆。" + +#: ../../faq/programming.rst:1934 +msgid "" +"For example, here is the implementation of :meth:`!" +"collections.abc.Sequence.__contains__`::" +msgstr "" +"例如，以下是 :meth:`!collections.abc.Sequence.__contains__` 的實作： ::" + +#: ../../faq/programming.rst:1937 +msgid "" +"def __contains__(self, value):\n" +" for v in self:\n" +" if v is value or v == value:\n" +" return True\n" +" return False" +msgstr "" +"def __contains__(self, value):\n" +" for v in self:\n" +" if v is value or v == value:\n" +" return True\n" +" return False" + +#: ../../faq/programming.rst:1945 +msgid "" +"How can a subclass control what data is stored in an immutable instance?" +msgstr "子類別如何控制不可變實例中儲存的資料？" + +#: ../../faq/programming.rst:1947 +#, fuzzy +msgid "" +"When subclassing an immutable type, override the :meth:`~object.__new__` " +"method instead of the :meth:`~object.__init__` method. The latter only runs " +"*after* an instance is created, which is too late to alter data in an " +"immutable instance." +msgstr "" +"當對不可變型別進行子類別化時，覆蓋 :meth:`~object.__new__` 方法而不" +"是 :meth:`~object.__init__` 方法。後者僅在*建立實例後*運行，這為時已晚，無法" +"更改不可變實例中的資料。" + +#: ../../faq/programming.rst:1952 +msgid "" +"All of these immutable classes have a different signature than their parent " +"class:" +msgstr "所有這些不可變類別都具有與其父類別不同的簽名：" + +#: ../../faq/programming.rst:1955 +msgid "" +"from datetime import date\n" +"\n" +"class FirstOfMonthDate(date):\n" +" \"Always choose the first day of the month\"\n" +" def __new__(cls, year, month, day):\n" +" return super().__new__(cls, year, month, 1)\n" +"\n" +"class NamedInt(int):\n" +" \"Allow text names for some numbers\"\n" +" xlat = {'zero': 0, 'one': 1, 'ten': 10}\n" +" def __new__(cls, value):\n" +" value = cls.xlat.get(value, value)\n" +" return super().__new__(cls, value)\n" +"\n" +"class TitleStr(str):\n" +" \"Convert str to name suitable for a URL path\"\n" +" def __new__(cls, s):\n" +" s = s.lower().replace(' ', '-')\n" +" s = ''.join([c for c in s if c.isalnum() or c == '-'])\n" +" return super().__new__(cls, s)" +msgstr "" +"from datetime import date\n" +"\n" +"class FirstOfMonthDate(date):\n" +" \"總是選擇每個月的第一天\"\n" +" def __new__(cls, year, month, day):\n" +" return super().__new__(cls, year, month, 1)\n" +"\n" +"class NamedInt(int):\n" +" \"允許一些數字的文字名稱\"\n" +" xlat = {'zero': 0, 'one': 1, 'ten': 10}\n" +" def __new__(cls, value):\n" +" value = cls.xlat.get(value, value)\n" +" return super().__new__(cls, value)\n" +"\n" +"class TitleStr(str):\n" +" \"將 str 轉換成適合作為 URL 路徑的名稱\"\n" +" def __new__(cls, s):\n" +" s = s.lower().replace(' ', '-')\n" +" s = ''.join([c for c in s if c.isalnum() or c == '-'])\n" +" return super().__new__(cls, s)" + +#: ../../faq/programming.rst:1978 +msgid "The classes can be used like this:" +msgstr "這些類別可以像這樣使用：" + +#: ../../faq/programming.rst:1980 +msgid "" +">>> FirstOfMonthDate(2012, 2, 14)\n" +"FirstOfMonthDate(2012, 2, 1)\n" +">>> NamedInt('ten')\n" +"10\n" +">>> NamedInt(20)\n" +"20\n" +">>> TitleStr('Blog: Why Python Rocks')\n" +"'blog-why-python-rocks'" +msgstr "" +">>> FirstOfMonthDate(2012, 2, 14)\n" +"FirstOfMonthDate(2012, 2, 1)\n" +">>> NamedInt('ten')\n" +"10\n" +">>> NamedInt(20)\n" +"20\n" +">>> TitleStr('Blog: Why Python Rocks')\n" +"'blog-why-python-rocks'" + +#: ../../faq/programming.rst:1995 +msgid "How do I cache method calls?" +msgstr "如何快取方法呼叫？" + +#: ../../faq/programming.rst:1997 +#, fuzzy +msgid "" +"The two principal tools for caching methods " +"are :func:`functools.cached_property` and :func:`functools.lru_cache`. The " +"former stores results at the instance level and the latter at the class " +"level." +msgstr "" +"快取方法的兩個主要工具是 func:`functools.cached_property` " +"和 :func:`functools.lru_cache`。前者在實例級別儲存結果，後者在類別級別儲存結" +"果。" + +#: ../../faq/programming.rst:2002 +#, fuzzy +msgid "" +"The *cached_property* approach only works with methods that do not take any " +"arguments. It does not create a reference to the instance. The cached " +"method result will be kept only as long as the instance is alive." +msgstr "" +"*cached_property* 方法僅適用於不帶任何引數的方法，它不會建立對實例的參照，只" +"要實例還活著，快取的方法結果就會被保留。" + +#: ../../faq/programming.rst:2006 +#, fuzzy +msgid "" +"The advantage is that when an instance is no longer used, the cached method " +"result will be released right away. The disadvantage is that if instances " +"accumulate, so too will the accumulated method results. They can grow " +"without bound." +msgstr "" +"好處是當一個實例不再使用時，快取的方法結果會立即釋放。缺點是如果實例累積，累" +"積的方法結果也會累積。他們可以不受限制地成長。" + +#: ../../faq/programming.rst:2011 +msgid "" +"The *lru_cache* approach works with methods that have :term:`hashable` " +"arguments. It creates a reference to the instance unless special efforts " +"are made to pass in weak references." +msgstr "" +"*lru_cache* 方法適用於具有\\ :term:`可雜湊 `\\ 引數的方法。除非特別" +"努力傳遞弱參照，否則它會建立對實例的參照。" + +#: ../../faq/programming.rst:2015 +#, fuzzy +msgid "" +"The advantage of the least recently used algorithm is that the cache is " +"bounded by the specified *maxsize*. The disadvantage is that instances are " +"kept alive until they age out of the cache or until the cache is cleared." +msgstr "" +"最近最少使用演算法的優點是快取受指定的 *maxsize* 限制。缺點是實例會一直保持活" +"動狀態，直到它們從快取中老化或快取被清除。" + +#: ../../faq/programming.rst:2020 +msgid "This example shows the various techniques::" +msgstr "這個例子展示了各種技術： ::" + +#: ../../faq/programming.rst:2022 +msgid "" +"class Weather:\n" +" \"Lookup weather information on a government website\"\n" +"\n" +" def __init__(self, station_id):\n" +" self._station_id = station_id\n" +" # The _station_id is private and immutable\n" +"\n" +" def current_temperature(self):\n" +" \"Latest hourly observation\"\n" +" # Do not cache this because old results\n" +" # can be out of date.\n" +"\n" +" @cached_property\n" +" def location(self):\n" +" \"Return the longitude/latitude coordinates of the station\"\n" +" # Result only depends on the station_id\n" +"\n" +" @lru_cache(maxsize=20)\n" +" def historic_rainfall(self, date, units='mm'):\n" +" \"Rainfall on a given date\"\n" +" # Depends on the station_id, date, and units." +msgstr "" + +#: ../../faq/programming.rst:2044 +#, fuzzy +msgid "" +"The above example assumes that the *station_id* never changes. If the " +"relevant instance attributes are mutable, the *cached_property* approach " +"can't be made to work because it cannot detect changes to the attributes." +msgstr "" +"上面的例子假設 *station_id* 永遠不會改變。如果相關的實例屬性是可變的，則 " +"*cached_property* 方法無法工作，因為它無法檢測到屬性的更改。" + +#: ../../faq/programming.rst:2049 +#, fuzzy +msgid "" +"To make the *lru_cache* approach work when the *station_id* is mutable, the " +"class needs to define the :meth:`~object.__eq__` " +"and :meth:`~object.__hash__` methods so that the cache can detect relevant " +"attribute updates::" +msgstr "" +"要在 *station_id* 可變時使 *lru_cache* 方法起作用，該類別需要定" +"義 :meth:`~object.__eq__` 和 :meth:`~object.__hash__` 方法，以便快取可以檢測" +"相關屬性更新： ::" + +#: ../../faq/programming.rst:2053 +msgid "" +"class Weather:\n" +" \"Example with a mutable station identifier\"\n" +"\n" +" def __init__(self, station_id):\n" +" self.station_id = station_id\n" +"\n" +" def change_station(self, station_id):\n" +" self.station_id = station_id\n" +"\n" +" def __eq__(self, other):\n" +" return self.station_id == other.station_id\n" +"\n" +" def __hash__(self):\n" +" return hash(self.station_id)\n" +"\n" +" @lru_cache(maxsize=20)\n" +" def historic_rainfall(self, date, units='cm'):\n" +" 'Rainfall on a given date'\n" +" # Depends on the station_id, date, and units." +msgstr "" + +#: ../../faq/programming.rst:2075 +msgid "Modules" +msgstr "模組" + +#: ../../faq/programming.rst:2078 +msgid "How do I create a .pyc file?" +msgstr "如何建立 .pyc 檔案？" + +#: ../../faq/programming.rst:2080 +#, fuzzy +msgid "" +"When a module is imported for the first time (or when the source file has " +"changed since the current compiled file was created) a ``.pyc`` file " +"containing the compiled code should be created in a ``__pycache__`` " +"subdirectory of the directory containing the ``.py`` file. The ``.pyc`` " +"file will have a filename that starts with the same name as the ``.py`` " +"file, and ends with ``.pyc``, with a middle component that depends on the " +"particular ``python`` binary that created it. (See :pep:`3147` for details.)" +msgstr "" +"第一次引入模組時（或者源檔案自建立目前編譯檔案後發生更改時）應在 " +"``__pycache__`` 的子目錄中建立包含編譯程式碼的 ``.pyc`` 檔案包含 .py 檔案的目" +"錄。 ``.pyc`` 檔案的檔案名以與``.py`` 檔案相同的名稱開頭，以``.pyc`` 結尾，中" +"間部分依賴於特定的``python `` 建立它的二進製檔案。（有關詳細資訊，請參" +"閱 :pep:`3147`。）" + +#: ../../faq/programming.rst:2088 +#, fuzzy +msgid "" +"One reason that a ``.pyc`` file may not be created is a permissions problem " +"with the directory containing the source file, meaning that the " +"``__pycache__`` subdirectory cannot be created. This can happen, for " +"example, if you develop as one user but run as another, such as if you are " +"testing with a web server." +msgstr "" +"無法建立 .pyc 檔案的原因之一是包含源檔案的目錄存在權限問題，這意味著無法建立 " +"__pycache__ 子目錄。例如，如果你以一個使用者的身份開發但以另一個使用者的身份" +"運行，例如你正在使用 Web 伺服器進行測試，就會發生這種情況。" + +#: ../../faq/programming.rst:2093 +#, fuzzy +msgid "" +"Unless the :envvar:`PYTHONDONTWRITEBYTECODE` environment variable is set, " +"creation of a .pyc file is automatic if you're importing a module and Python " +"has the ability (permissions, free space, etc...) to create a " +"``__pycache__`` subdirectory and write the compiled module to that " +"subdirectory." +msgstr "" +"除非 :envvar:`PYTHONDONTWRITEBYTECODE` 環境變數有被設定，如果你正在引入一個模" +"組並且 Python 有能力（權限、空閒空間等）建立一個 .pyc 檔案是自動的建立一個" +"``__pycache__ `` 子目錄並將編譯後的模組寫入該子目錄。" + +#: ../../faq/programming.rst:2098 +#, fuzzy +msgid "" +"Running Python on a top level script is not considered an import and no " +"``.pyc`` will be created. For example, if you have a top-level module " +"``foo.py`` that imports another module ``xyz.py``, when you run ``foo`` (by " +"typing ``python foo.py`` as a shell command), a ``.pyc`` will be created for " +"``xyz`` because ``xyz`` is imported, but no ``.pyc`` file will be created " +"for ``foo`` since ``foo.py`` isn't being imported." +msgstr "" +"在頂級腳本上運行 Python 不被視為引入，也不會建立 ``.pyc``。例如，如果你有一個" +"頂級模組 ``foo.py`` 引入另一個模組 ``xyz.py`` ，當你運行 ``foo`` 時（透過輸" +"入 ``python foo.py`` 作為一個 shell 命令），將為 xyz 建立一個 .pyc 因為引入" +"了 xyz，但是不會為 foo 建立 .pyc 檔案，因為 ` `foo.py`` 沒有被引入。" + +#: ../../faq/programming.rst:2105 +msgid "" +"If you need to create a ``.pyc`` file for ``foo`` -- that is, to create a " +"``.pyc`` file for a module that is not imported -- you can, using " +"the :mod:`py_compile` and :mod:`compileall` modules." +msgstr "" +"如果你需要為 ``foo`` 建立一個 ``.pyc`` 檔案 —— 也就是說，要為一個未引入的模組" +"建立一個 ``.pyc`` 檔案 —— 你可以使用 :mod:`py_compile` 和 :mod:`compileall` " +"模組。" + +#: ../../faq/programming.rst:2109 +msgid "" +"The :mod:`py_compile` module can manually compile any module. One way is to " +"use the ``compile()`` function in that module interactively::" +msgstr "" +":mod:`py_compile` 模組允許手動編譯任何模組。其中一種方法是在該模組中以交互方" +"式使用 ``compile()`` 函式： ::" + +#: ../../faq/programming.rst:2112 +msgid "" +">>> import py_compile\n" +">>> py_compile.compile('foo.py')" +msgstr "" +">>> import py_compile\n" +">>> py_compile.compile('foo.py')" + +#: ../../faq/programming.rst:2115 +msgid "" +"This will write the ``.pyc`` to a ``__pycache__`` subdirectory in the same " +"location as ``foo.py`` (or you can override that with the optional parameter " +"``cfile``)." +msgstr "" +"這會將 ``.pyc`` 寫入與 ``foo.py`` 相同位置的 ``__pycache__`` 子目錄（或者你可" +"以使用可選參數 ``cfile`` 覆蓋它）。" + +#: ../../faq/programming.rst:2119 +#, fuzzy +msgid "" +"You can also automatically compile all files in a directory or directories " +"using the :mod:`compileall` module. You can do it from the shell prompt by " +"running ``compileall.py`` and providing the path of a directory containing " +"Python files to compile::" +msgstr "" +"你還可以使用 :mod:`compileall` 模組自動編譯目錄中的所有檔案。你可以在 shell " +"提示符下運行 ``compileall.py`` 並提供包含要編譯的 Python 檔案的目錄路徑： ::" + +#: ../../faq/programming.rst:2124 +msgid "python -m compileall ." +msgstr "python -m compileall ." + +#: ../../faq/programming.rst:2128 +msgid "How do I find the current module name?" +msgstr "如何找到目前模組名稱？" + +#: ../../faq/programming.rst:2130 +#, fuzzy +msgid "" +"A module can find out its own module name by looking at the predefined " +"global variable ``__name__``. If this has the value ``'__main__'``, the " +"program is running as a script. Many modules that are usually used by " +"importing them also provide a command-line interface or a self-test, and " +"only execute this code after checking ``__name__``::" +msgstr "" +"模組可以透過查看預定義的全域變數 ``__name__`` 來找出自己的模組名稱。如果它的" +"值為``'__main__'``，則該程式作為腳本運行。許多通常透過引入使用的模組還提供命" +"令行介面或自檢，只有在檢查 ``__name__`` 後才執行此程式碼： ::" + +#: ../../faq/programming.rst:2136 +msgid "" +"def main():\n" +" print('Running test...')\n" +" ...\n" +"\n" +"if __name__ == '__main__':\n" +" main()" +msgstr "" +"def main():\n" +" print('Running test...')\n" +" ...\n" +"\n" +"if __name__ == '__main__':\n" +" main()" + +#: ../../faq/programming.rst:2145 +msgid "How can I have modules that mutually import each other?" +msgstr "要怎樣才能擁有相互引入的模組？" + +#: ../../faq/programming.rst:2147 +msgid "Suppose you have the following modules:" +msgstr "假設你有以下模組：" + +#: ../../faq/programming.rst:2149 +msgid ":file:`foo.py`::" +msgstr ":file:`foo.py`： ::" + +#: ../../faq/programming.rst:2151 +msgid "" +"from bar import bar_var\n" +"foo_var = 1" +msgstr "" +"from bar import bar_var\n" +"foo_var = 1" + +#: ../../faq/programming.rst:2154 +msgid ":file:`bar.py`::" +msgstr ":file:`bar.py`： ::" + +#: ../../faq/programming.rst:2156 +msgid "" +"from foo import foo_var\n" +"bar_var = 2" +msgstr "" +"from foo import foo_var\n" +"bar_var = 2" + +#: ../../faq/programming.rst:2159 +msgid "The problem is that the interpreter will perform the following steps:" +msgstr "問題是直譯器將執行以下步驟：" + +#: ../../faq/programming.rst:2161 +msgid "main imports ``foo``" +msgstr "主要引入 ``foo``" + +#: ../../faq/programming.rst:2162 +msgid "Empty globals for ``foo`` are created" +msgstr "建立了 ``foo`` 的空全域變數" + +#: ../../faq/programming.rst:2163 +msgid "``foo`` is compiled and starts executing" +msgstr "``foo`` 被編譯並開始執行" + +#: ../../faq/programming.rst:2164 +msgid "``foo`` imports ``bar``" +msgstr "``foo`` 引入 ``bar``" + +#: ../../faq/programming.rst:2165 +msgid "Empty globals for ``bar`` are created" +msgstr "建立了 ``bar`` 的空全域變數" + +#: ../../faq/programming.rst:2166 +msgid "``bar`` is compiled and starts executing" +msgstr "``bar`` 已被編譯並開始執行" + +#: ../../faq/programming.rst:2167 +msgid "" +"``bar`` imports ``foo`` (which is a no-op since there already is a module " +"named ``foo``)" +msgstr "" +"``bar`` 引入 ``foo``\\ （這是一個空操作，因為已經有一個名為 ``foo`` 的模組）" + +#: ../../faq/programming.rst:2168 +msgid "" +"The import mechanism tries to read ``foo_var`` from ``foo`` globals, to set " +"``bar.foo_var = foo.foo_var``" +msgstr "" +"引入機制嘗試從 ``foo`` 全域變數中讀取 ``foo_var``，以設定 ``bar.foo_var = " +"foo.foo_var``" + +#: ../../faq/programming.rst:2170 +msgid "" +"The last step fails, because Python isn't done with interpreting ``foo`` yet " +"and the global symbol dictionary for ``foo`` is still empty." +msgstr "" +"最後一步失敗了，因為 Python 還沒有完成對 ``foo`` 的直譯，而 ``foo`` 的全域符" +"號字典仍然是空的。" + +#: ../../faq/programming.rst:2173 +#, fuzzy +msgid "" +"The same thing happens when you use ``import foo``, and then try to access " +"``foo.foo_var`` in global code." +msgstr "" +"當你使用 ``import foo``，然後嘗試在全域程式碼中存取 ``foo.foo_var`` 時，也會" +"發生同樣的事情。" + +#: ../../faq/programming.rst:2176 +msgid "There are (at least) three possible workarounds for this problem." +msgstr "此問題有（至少）三種可能的解決方法。" + +#: ../../faq/programming.rst:2178 +#, fuzzy +msgid "" +"Guido van Rossum recommends avoiding all uses of ``from " +"import ...``, and placing all code inside functions. Initializations of " +"global variables and class variables should use constants or built-in " +"functions only. This means everything from an imported module is referenced " +"as ``.``." +msgstr "" +"Guido van Rossum 建議避免使用``from import ...``，並將所有程式碼放在" +"函式中。全域變數和類別變數的初始化應該只使用常數或內建函式。這意味著來自引入" +"模組的所有內容都被參照為 ``.``。" + +#: ../../faq/programming.rst:2183 +msgid "" +"Jim Roskind suggests performing steps in the following order in each module:" +msgstr "Jim Roskind 建議在每個模組中按以下順序執行各個步驟：" + +#: ../../faq/programming.rst:2185 +#, fuzzy +msgid "" +"exports (globals, functions, and classes that don't need imported base " +"classes)" +msgstr "匯出（不需要引入基底類別的全域變數、函式和類別）" + +#: ../../faq/programming.rst:2187 +msgid "``import`` statements" +msgstr "``import`` 陳述式" + +#: ../../faq/programming.rst:2188 +msgid "" +"active code (including globals that are initialized from imported values)." +msgstr "活躍程式碼（包括從引入值初始化的全域變數）。" + +#: ../../faq/programming.rst:2190 +msgid "" +"Van Rossum doesn't like this approach much because the imports appear in a " +"strange place, but it does work." +msgstr "" +"Van Rossum 不太喜歡這種方法，因為引入出現在一個奇怪的地方，但它確實有效。" + +#: ../../faq/programming.rst:2193 +msgid "" +"Matthias Urlichs recommends restructuring your code so that the recursive " +"import is not necessary in the first place." +msgstr "" +"Matthias Urlichs 建議重組 (restructuring) 你的程式碼，以便打從一開始就不需要" +"遞迴引入。" + +#: ../../faq/programming.rst:2196 +msgid "These solutions are not mutually exclusive." +msgstr "這些方案並不衝突。" + +#: ../../faq/programming.rst:2200 +msgid "__import__('x.y.z') returns ; how do I get z?" +msgstr "__import__('x.y.z') 回傳 ，那我怎麼得到 z？" + +#: ../../faq/programming.rst:2202 +#, fuzzy +msgid "" +"Consider using the convenience function :func:`~importlib.import_module` " +"from :mod:`importlib` instead::" +msgstr "" +"考慮使用來自 :mod:`importlib` 的便利函式 :func:`~importlib.import_module` 代" +"替： ::" + +#: ../../faq/programming.rst:2205 +msgid "z = importlib.import_module('x.y.z')" +msgstr "z = importlib.import_module('x.y.z')" + +#: ../../faq/programming.rst:2209 +msgid "" +"When I edit an imported module and reimport it, the changes don't show up. " +"Why does this happen?" +msgstr "當我編輯需要引入的模組並重新引入它時，更動沒有反應出來。為什麼會這樣？" + +#: ../../faq/programming.rst:2211 +#, fuzzy +msgid "" +"For reasons of efficiency as well as consistency, Python only reads the " +"module file on the first time a module is imported. If it didn't, in a " +"program consisting of many modules where each one imports the same basic " +"module, the basic module would be parsed and re-parsed many times. To force " +"re-reading of a changed module, do this::" +msgstr "" +"出於效率和一致性的原因，Python 僅在第一次引入模組時讀取模組檔案。如果沒有，在" +"一個由許多模組組成的程式中，每個模組都引入相同的基本模組，基本模組將被解析和" +"重新解析很多次。要強制重新讀取已更改的模組，請執行以下操作： ::" + +#: ../../faq/programming.rst:2217 +msgid "" +"import importlib\n" +"import modname\n" +"importlib.reload(modname)" +msgstr "" +"import importlib\n" +"import modname\n" +"importlib.reload(modname)" + +#: ../../faq/programming.rst:2221 +msgid "" +"Warning: this technique is not 100% fool-proof. In particular, modules " +"containing statements like ::" +msgstr "警告：此技術並非 100% 萬無一失。尤其是包含像這樣陳述式的模組： ::" + +#: ../../faq/programming.rst:2224 +msgid "from modname import some_objects" +msgstr "from modname import some_objects" + +#: ../../faq/programming.rst:2226 +#, fuzzy +msgid "" +"will continue to work with the old version of the imported objects. If the " +"module contains class definitions, existing class instances will *not* be " +"updated to use the new class definition. This can result in the following " +"paradoxical behaviour::" +msgstr "" +"將繼續使用舊版本的引入物件。如果模組包含類別定義，現有的類別實例將*不會*更新" +"為使用新的類別定義。這可能會導致以下自相矛盾的行為： ::" + +#: ../../faq/programming.rst:2231 +msgid "" +">>> import importlib\n" +">>> import cls\n" +">>> c = cls.C() # Create an instance of C\n" +">>> importlib.reload(cls)\n" +"\n" +">>> isinstance(c, cls.C) # isinstance is false?!?\n" +"False" +msgstr "" +">>> import importlib\n" +">>> import cls\n" +">>> c = cls.C() # 建立一個 C 的實例\n" +">>> importlib.reload(cls)\n" +"\n" +">>> isinstance(c, cls.C) # isinstance 為 false？！？\n" +"False" + +#: ../../faq/programming.rst:2239 +msgid "" +"The nature of the problem is made clear if you print out the \"identity\" of " +"the class objects::" +msgstr "如果印出類別物件的「識別性」，問題的本質就很清楚了： ::" + +#: ../../faq/programming.rst:2242 +msgid "" +">>> hex(id(c.__class__))\n" +"'0x7352a0'\n" +">>> hex(id(cls.C))\n" +"'0x4198d0'" +msgstr "" +">>> hex(id(c.__class__))\n" +"'0x7352a0'\n" +">>> hex(id(cls.C))\n" +"'0x4198d0'" + +#: ../../faq/programming.rst:408 +msgid "argument" +msgstr "argument（引數）" + +#: ../../faq/programming.rst:408 +msgid "difference from parameter" +msgstr "與 parameter（參數）的差異" + +#: ../../faq/programming.rst:408 +msgid "parameter" +msgstr "parameter（參數）" + +#: ../../faq/programming.rst:408 +msgid "difference from argument" +msgstr "與 argument（引數）的差異" diff --git a/faq/windows.po b/faq/windows.po index 9c39108b53..62d5e2c158 100644 --- a/faq/windows.po +++ b/faq/windows.po @@ -1,556 +1,556 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Cecil Sheng , 2015 -# Liang-Bo Wang , 2015 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-09-01 22:24+0800\n" -"PO-Revision-Date: 2022-11-09 17:25+0800\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" -"X-Generator: Poedit 3.2\n" - -#: ../../faq/windows.rst:9 -msgid "Python on Windows FAQ" -msgstr "在 Windows 使用 Python 的常見問答集" - -#: ../../faq/windows.rst:12 -msgid "Contents" -msgstr "目錄" - -#: ../../faq/windows.rst:22 -msgid "How do I run a Python program under Windows?" -msgstr "如何在 Windows 作業系統裡運行 Python 程式？" - -#: ../../faq/windows.rst:24 -msgid "" -"This is not necessarily a straightforward question. If you are already " -"familiar with running programs from the Windows command line then everything " -"will seem obvious; otherwise, you might need a little more guidance." -msgstr "" -"這個問題的答案可能有點複雜。如果你經常使用「命令提示字元」執行程式，那這對你" -"來說不會是什麼難事。如果不然，那就需要更仔細的說明了。" - -#: ../../faq/windows.rst:28 -msgid "" -"Unless you use some sort of integrated development environment, you will end " -"up *typing* Windows commands into what is referred to as a \"Command prompt " -"window\". Usually you can create such a window from your search bar by " -"searching for ``cmd``. You should be able to recognize when you have " -"started such a window because you will see a Windows \"command prompt\", " -"which usually looks like this:" -msgstr "" -"除非你使用某種整合開發環境，否則你最終將會在所謂的「命令提示字元視窗」中 *打" -"字輸入* Windows 命令。通常，你可以透過從搜尋欄中搜尋 ``cmd`` 來建立這樣的視" -"窗。你應該能夠認出何時已啟動這樣的視窗，因為你將看到 Windows「命令提示字" -"元」，它通常看起來像這樣：" - -#: ../../faq/windows.rst:35 -msgid "C:\\>" -msgstr "C:\\>" - -#: ../../faq/windows.rst:39 -msgid "" -"The letter may be different, and there might be other things after it, so " -"you might just as easily see something like:" -msgstr "" -"第一個字母可能不一樣，且後面也可能還有其他內容，因此你可能會很容易看到類似以" -"下的文字：" - -#: ../../faq/windows.rst:42 -msgid "D:\\YourName\\Projects\\Python>" -msgstr "D:\\YourName\\Projects\\Python>" - -#: ../../faq/windows.rst:46 -msgid "" -"depending on how your computer has been set up and what else you have " -"recently done with it. Once you have started such a window, you are well on " -"the way to running Python programs." -msgstr "" -"取決於你的電腦如何被設置，以及你最近對它所做的其他操作。一旦你啟動了這樣一個" -"視窗，你就即將可以運行 Python 程式了。" - -#: ../../faq/windows.rst:50 -msgid "" -"You need to realize that your Python scripts have to be processed by another " -"program called the Python *interpreter*. The interpreter reads your script, " -"compiles it into bytecodes, and then executes the bytecodes to run your " -"program. So, how do you arrange for the interpreter to handle your Python?" -msgstr "" -"你需要了解，你的 Python 腳本必須被另一個稱為 Python *直譯器*\\ 的程序來處理。" -"直譯器會讀取你的腳本，將其編譯為位元組碼，然後執行該位元組碼以運行你的程式。" -"那麼，你要如何安排直譯器來處理你的 Python 呢？" - -#: ../../faq/windows.rst:55 -msgid "" -"First, you need to make sure that your command window recognises the word " -"\"py\" as an instruction to start the interpreter. If you have opened a " -"command window, you should try entering the command ``py`` and hitting " -"return:" -msgstr "" -"首先，你需要確保你的命令視窗會將單字 \"py\" 識別為啟動直譯器的指令。如果你已" -"經開啟一個命令視窗，則你應該試試輸入命令 ``py`` 並按下 return 鍵：" - -#: ../../faq/windows.rst:60 -msgid "C:\\Users\\YourName> py" -msgstr "C:\\Users\\YourName> py" - -#: ../../faq/windows.rst:64 -msgid "You should then see something like:" -msgstr "然後，你應該看到類似下面的內容：" - -#: ../../faq/windows.rst:66 -msgid "" -"Python 3.6.4 (v3.6.4:d48eceb, Dec 19 2017, 06:04:45) [MSC v.1900 32 bit " -"(Intel)] on win32\n" -"Type \"help\", \"copyright\", \"credits\" or \"license\" for more " -"information.\n" -">>>" -msgstr "" -"Python 3.6.4 (v3.6.4:d48eceb, Dec 19 2017, 06:04:45) [MSC v.1900 32 bit " -"(Intel)] on win32\n" -"Type \"help\", \"copyright\", \"credits\" or \"license\" for more " -"information.\n" -">>>" - -#: ../../faq/windows.rst:72 -msgid "" -"You have started the interpreter in \"interactive mode\". That means you can " -"enter Python statements or expressions interactively and have them executed " -"or evaluated while you wait. This is one of Python's strongest features. " -"Check it by entering a few expressions of your choice and seeing the results:" -msgstr "" -"你已經啟動直譯器中的「互動模式」。這表示你能夠以互動方式輸入 Python 陳述式或" -"運算式，並在等待時執行或計算它們。這是 Python 最強大的功能之一。輸入你所選的" -"幾個運算式並查看結果，可以檢驗此功能：" - -#: ../../faq/windows.rst:77 -msgid "" -">>> print(\"Hello\")\n" -"Hello\n" -">>> \"Hello\" * 3\n" -"'HelloHelloHello'" -msgstr "" -">>> print(\"Hello\")\n" -"Hello\n" -">>> \"Hello\" * 3\n" -"'HelloHelloHello'" - -#: ../../faq/windows.rst:84 -msgid "" -"Many people use the interactive mode as a convenient yet highly programmable " -"calculator. When you want to end your interactive Python session, call " -"the :func:`exit` function or hold the :kbd:`Ctrl` key down while you enter " -"a :kbd:`Z`, then hit the \":kbd:`Enter`\" key to get back to your Windows " -"command prompt." -msgstr "" -"許多人將互動模式作為方便但可高度程式化的計算機。如果你要結束互動式 Python 對" -"話，請呼叫 :func:`exit` 函式或是按住 :kbd:`Ctrl` 鍵再輸入 :kbd:`Z`，然後按下 " -"\":kbd:`Enter`\" 鍵以返回 Windows 命令提示字元。" - -#: ../../faq/windows.rst:90 -msgid "" -"You may also find that you have a Start-menu entry such " -"as :menuselection:`Start --> Programs --> Python 3.x --> Python (command " -"line)` that results in you seeing the ``>>>`` prompt in a new window. If " -"so, the window will disappear after you call the :func:`exit` function or " -"enter the :kbd:`Ctrl-Z` character; Windows is running a single \"python\" " -"command in the window, and closes it when you terminate the interpreter." -msgstr "" -"你可能還會發現你有一個開始功能表項目，像是：:menuselection:`開始 --> 所有程" -"式 --> Python 3.x --> Python（命令行）`，它會讓你在一個新視窗中看到 ``>>>`` " -"提示字元。如果是這樣，該視窗將在你呼叫 :func:`exit` 函式或輸入 :kbd:`Ctrl-Z` " -"字元後消失；Windows 正在該視窗中運行單一個「python」命令，並在你終止直譯器時" -"將其關閉。" - -#: ../../faq/windows.rst:97 -msgid "" -"Now that we know the ``py`` command is recognized, you can give your Python " -"script to it. You'll have to give either an absolute or a relative path to " -"the Python script. Let's say your Python script is located in your desktop " -"and is named ``hello.py``, and your command prompt is nicely opened in your " -"home directory so you're seeing something similar to::" -msgstr "" -"現在我們知道 ``py`` 命令已被識別，而你可以將你的 Python 腳本提供給它。你必須" -"為 Python 腳本給定絕對路徑或相對路徑。假設你的 Python 腳本位於桌面上，並被命" -"名為 ``hello.py``，且你的命令提示字元在你的家目錄 (home directory) 中順利地被" -"開啟，那麼你就會看到類似以下的內容： ::" - -#: ../../faq/windows.rst:104 -msgid "C:\\Users\\YourName>" -msgstr "C:\\Users\\YourName>" - -#: ../../faq/windows.rst:106 -msgid "" -"So now you'll ask the ``py`` command to give your script to Python by typing " -"``py`` followed by your script path::" -msgstr "" -"因此，現在你將透過鍵入 ``py`` 加上腳本路徑，來使用 ``py`` 命令將你的腳本提供" -"給 Python： ::" - -#: ../../faq/windows.rst:110 -msgid "" -"C:\\Users\\YourName> py Desktop\\hello.py\n" -"hello" -msgstr "" -"C:\\Users\\YourName> py Desktop\\hello.py\n" -"hello" - -#: ../../faq/windows.rst:114 -msgid "How do I make Python scripts executable?" -msgstr "如何使 Python 腳本可以執行？" - -#: ../../faq/windows.rst:116 -msgid "" -"On Windows, the standard Python installer already associates the .py " -"extension with a file type (Python.File) and gives that file type an open " -"command that runs the interpreter (``D:\\Program Files\\Python\\python.exe " -"\"%1\" %*``). This is enough to make scripts executable from the command " -"prompt as 'foo.py'. If you'd rather be able to execute the script by simple " -"typing 'foo' with no extension you need to add .py to the PATHEXT " -"environment variable." -msgstr "" -"在 Windows 上，標準的 Python 安裝程式已將 .py 副檔名與一種檔案類型 " -"(Python.File) 進行關聯，並為該檔案類型提供一個開啟命令來運行直譯器 (``D:" -"\\Program Files\\Python\\python.exe \"%1\" %*``)。這足以使腳本能以類似 " -"'foo.py' 的形式從命令提示字元被執行。如果你希望能夠簡單地輸入 'foo' 來執行腳" -"本，而不用加上副檔名，則需要將 .py 新增至 PATHEXT 環境變數中。" - -#: ../../faq/windows.rst:124 -msgid "Why does Python sometimes take so long to start?" -msgstr "為什麼 Python 有時需要這麼長的時間才能開始？" - -#: ../../faq/windows.rst:126 -msgid "" -"Usually Python starts very quickly on Windows, but occasionally there are " -"bug reports that Python suddenly begins to take a long time to start up. " -"This is made even more puzzling because Python will work fine on other " -"Windows systems which appear to be configured identically." -msgstr "" -"通常 Python 在 Windows 上啟動得非常快，但偶爾會有一些錯誤報告，內容是 Python " -"突然開始需要很長的時間才能啟動。這種情形更令人費解，因為 Python 在其他 " -"Windows 系統上可以正常工作，而那些系統似乎也有相同的配置。" - -#: ../../faq/windows.rst:131 -msgid "" -"The problem may be caused by a misconfiguration of virus checking software " -"on the problem machine. Some virus scanners have been known to introduce " -"startup overhead of two orders of magnitude when the scanner is configured " -"to monitor all reads from the filesystem. Try checking the configuration of " -"virus scanning software on your systems to ensure that they are indeed " -"configured identically. McAfee, when configured to scan all file system read " -"activity, is a particular offender." -msgstr "" -"這個問題可能是由發生此問題的電腦上的病毒檢查軟體配置錯誤所引起的。目前已知某" -"些病毒掃描程式，在它們被配置為監視來自檔案系統的所有讀取時，會引入兩個數量級" -"的啟動負擔。請試著檢查你系統上的病毒掃描軟體配置，以確保它們的配置確實相同。" -"當 McAfee 被配置為掃描所有檔案系統的讀取活動時，它是一個特定的違規者。" - -#: ../../faq/windows.rst:141 -msgid "How do I make an executable from a Python script?" -msgstr "如何從 Python 腳本製作可執行檔？" - -#: ../../faq/windows.rst:143 -msgid "" -"See :ref:`faq-create-standalone-binary` for a list of tools that can be used " -"to make executables." -msgstr "" -"請參閱\\ :ref:`faq-create-standalone-binary`\\ 該章節列出了用於製作可執行檔的" -"工具清單。" - -#: ../../faq/windows.rst:148 -msgid "Is a ``*.pyd`` file the same as a DLL?" -msgstr "``*.pyd`` 檔是否與 DLL 相同？" - -#: ../../faq/windows.rst:150 -msgid "" -"Yes, .pyd files are dll's, but there are a few differences. If you have a " -"DLL named ``foo.pyd``, then it must have a function ``PyInit_foo()``. You " -"can then write Python \"import foo\", and Python will search for foo.pyd (as " -"well as foo.py, foo.pyc) and if it finds it, will attempt to call " -"``PyInit_foo()`` to initialize it. You do not link your .exe with foo.lib, " -"as that would cause Windows to require the DLL to be present." -msgstr "" -"是的，.pyd 檔類似於 dll，但也有一些區別。如果你有一個名為 ``foo.pyd`` 的 " -"DLL，則它必須具有函式 ``PyInit_foo()``。接著你可以將 \"import foo\" 寫入 " -"Python 腳本，Python 將會搜尋 foo.pyd（以及 foo.py、foo.pyc），如果 Python 找" -"到它，將會嘗試呼叫 ``PyInit_foo()`` 來將它初始化。你並不會將你的 .exe 與 " -"foo.lib 連結 (link)，因為這會導致 Windows 要求 DLL 的存在。" - -#: ../../faq/windows.rst:157 -msgid "" -"Note that the search path for foo.pyd is PYTHONPATH, not the same as the " -"path that Windows uses to search for foo.dll. Also, foo.pyd need not be " -"present to run your program, whereas if you linked your program with a dll, " -"the dll is required. Of course, foo.pyd is required if you want to say " -"``import foo``. In a DLL, linkage is declared in the source code with " -"``__declspec(dllexport)``. In a .pyd, linkage is defined in a list of " -"available functions." -msgstr "" -"請注意，foo.pyd 的搜尋路徑是 PYTHONPATH，與 Windows 用於搜尋 foo.dll 的路徑不" -"同。此外，foo.pyd 不需存在即可運行你的程式，然而如果你將程式連結了一個 dll，" -"則該 dll 會是必要的。當然，如果你想要 ``import foo``，foo.pyd 就是必要的。在 " -"DLL 中，連結是以 ``__declspec(dllexport)`` 在原始碼中被宣告。在 .pyd 中，連結" -"是在一個可用函式的 list（串列）中被定義。" - -#: ../../faq/windows.rst:166 -msgid "How can I embed Python into a Windows application?" -msgstr "如何將 Python 嵌入 Windows 應用程式中？" - -#: ../../faq/windows.rst:168 -msgid "" -"Embedding the Python interpreter in a Windows app can be summarized as " -"follows:" -msgstr "在 Windows 應用程式中嵌入 Python 直譯器的過程可以總結如下：" - -#: ../../faq/windows.rst:170 -msgid "" -"Do **not** build Python into your .exe file directly. On Windows, Python " -"must be a DLL to handle importing modules that are themselves DLL's. (This " -"is the first key undocumented fact.) Instead, link " -"to :file:`python{NN}.dll`; it is typically installed in ``C:" -"\\Windows\\System``. *NN* is the Python version, a number such as \"33\" " -"for Python 3.3." -msgstr "" -"**不要**\\ 直接將 Python 建置到你的 .exe 檔中。在 Windows 上，Python 必須是一" -"個 DLL 來處理模組的 import，而那些模組本身也是 DLL。（這是第一個未正式記載的" -"關鍵事實。）請改為連結到 :file:`python{NN}.dll`；它通常被安裝在 ``C:" -"\\Windows\\System`` 中。*NN* 是 Python 版本，例如 \"33\" 就是指 Python 3.3。" - -#: ../../faq/windows.rst:176 -msgid "" -"You can link to Python in two different ways. Load-time linking means " -"linking against :file:`python{NN}.lib`, while run-time linking means linking " -"against :file:`python{NN}.dll`. (General note: :file:`python{NN}.lib` is " -"the so-called \"import lib\" corresponding to :file:`python{NN}.dll`. It " -"merely defines symbols for the linker.)" -msgstr "" -"你可以透過兩種不同的方式連結到 Python。載入時連結 (load-time linking) 表示要" -"連結到 :file:`python{NN}.lib`，而執行環境連結 (run-time linking) 表示要連結" -"到 :file:`python{NN}.dll`。（一般註解：:file:`python{NN}.lib` " -"是 :file:`python{NN}.dll` 相對應的所謂 \"import lib\"。它只會為鏈接器定義符" -"號。）" - -#: ../../faq/windows.rst:182 -msgid "" -"Run-time linking greatly simplifies link options; everything happens at run " -"time. Your code must load :file:`python{NN}.dll` using the Windows " -"``LoadLibraryEx()`` routine. The code must also use access routines and " -"data in :file:`python{NN}.dll` (that is, Python's C API's) using pointers " -"obtained by the Windows ``GetProcAddress()`` routine. Macros can make using " -"these pointers transparent to any C code that calls routines in Python's C " -"API." -msgstr "" -"執行環境連結大大簡化了連結選項；所有事情都會發生在執行環境。你的程式碼必須使" -"用 Windows ``LoadLibraryEx()`` 常式 (routine) 來載入 :file:`python{NN}.dll`。" -"該程式碼也必須用 Windows ``GetProcAddress()`` 常式所取得的指標，來使" -"用 :file:`python{NN}.dll` 中的（即為 Python C API 的）存取常式和資料。對於任" -"何呼叫 Python C API 常式的 C 程式碼，巨集可以讓使用這些指標的過程透明化。" - -#: ../../faq/windows.rst:191 -msgid "" -"If you use SWIG, it is easy to create a Python \"extension module\" that " -"will make the app's data and methods available to Python. SWIG will handle " -"just about all the grungy details for you. The result is C code that you " -"link *into* your .exe file (!) You do **not** have to create a DLL file, " -"and this also simplifies linking." -msgstr "" -"如果你使用 SWIG，則可輕鬆地建立一個 Python 「擴充模組」，該模組將使應用程式的" -"資料和 method（方法）可供 Python 使用。SWIG 會為你處理幾乎所有的繁瑣細節。結" -"果就是，你會將 C 程式碼連結\\ *到*\\ 你的 .exe 檔裡（！）你\\ **不必**\\ 建" -"立 DLL 檔，而這也簡化了連結。" - -#: ../../faq/windows.rst:197 -msgid "" -"SWIG will create an init function (a C function) whose name depends on the " -"name of the extension module. For example, if the name of the module is " -"leo, the init function will be called initleo(). If you use SWIG shadow " -"classes, as you should, the init function will be called initleoc(). This " -"initializes a mostly hidden helper class used by the shadow class." -msgstr "" -"SWIG 將建立一個 init 函式（一個 C 函式），其名稱取決於擴充模組的名稱。例如，" -"如果模組的名稱是 leo，則該 init 函式會命名為 initleo()。如果你使用 SWIG " -"shadow class（類別），則 init 函式會命名為 initleoc()。這會初始化被 shadow " -"class 所用的大多數隱藏的 helper class。" - -#: ../../faq/windows.rst:203 -msgid "" -"The reason you can link the C code in step 2 into your .exe file is that " -"calling the initialization function is equivalent to importing the module " -"into Python! (This is the second key undocumented fact.)" -msgstr "" -"你可以將步驟 2 中的 C 程式碼連結到 .exe 檔中的原因是，呼叫初始化函式就等效於 " -"import 模組進 Python！（這是第二個未正式記載的關鍵事實。）" - -#: ../../faq/windows.rst:207 -msgid "" -"In short, you can use the following code to initialize the Python " -"interpreter with your extension module." -msgstr "簡而言之，你可以使用以下程式碼，以你的擴充模組初始化 Python 直譯器。" - -#: ../../faq/windows.rst:210 -msgid "" -"#include \n" -"...\n" -"Py_Initialize(); // Initialize Python.\n" -"initmyAppc(); // Initialize (import) the helper class.\n" -"PyRun_SimpleString(\"import myApp\"); // Import the shadow class." -msgstr "" -"#include \n" -"...\n" -"Py_Initialize(); // 初始化 Python。\n" -"initmyAppc(); // 初始化（引入）幫助類別。\n" -"PyRun_SimpleString(\"import myApp\"); // 引入 shadow 類別。" - -#: ../../faq/windows.rst:218 -msgid "" -"There are two problems with Python's C API which will become apparent if you " -"use a compiler other than MSVC, the compiler used to build pythonNN.dll." -msgstr "" -"Python 的 C API 有兩個問題，如果你使用 MSVC（用於建置 pythonNN.dll 的編譯器）" -"以外的編譯器，這些問題將會變得明顯。" - -#: ../../faq/windows.rst:221 -msgid "" -"Problem 1: The so-called \"Very High Level\" functions that take ``FILE *`` " -"arguments will not work in a multi-compiler environment because each " -"compiler's notion of a ``struct FILE`` will be different. From an " -"implementation standpoint these are very low level functions." -msgstr "" -"問題 1：使用 ``FILE *`` 引數的所謂「非常高階」的函式，在多編譯器 (multi-" -"compiler) 的環境中會無法作用，因為每個編譯器對 ``struct FILE`` 的概念不同。從" -"實作的觀點來看，這些都是非常\\ _低階_\\ 的函式。" - -#: ../../faq/windows.rst:226 -msgid "" -"Problem 2: SWIG generates the following code when generating wrappers to " -"void functions:" -msgstr "問題 2：SWIG 在為 void 函式產生包裝函式 (wrapper) 時會產生以下程式碼：" - -#: ../../faq/windows.rst:229 -msgid "" -"Py_INCREF(Py_None);\n" -"_resultobj = Py_None;\n" -"return _resultobj;" -msgstr "" -"Py_INCREF(Py_None);\n" -"_resultobj = Py_None;\n" -"return _resultobj;" - -#: ../../faq/windows.rst:235 -msgid "" -"Alas, Py_None is a macro that expands to a reference to a complex data " -"structure called _Py_NoneStruct inside pythonNN.dll. Again, this code will " -"fail in a mult-compiler environment. Replace such code by:" -msgstr "" -"唉，Py_None 是一個巨集，它會延伸到一個參照，指向 pythonNN.dll 內部的一種稱為 " -"_Py_NoneStruct 的複雜資料結構。同樣的，此程式碼在多編譯器環境中將會失效。請將" -"此類程式碼替換為：" - -#: ../../faq/windows.rst:239 -msgid "return Py_BuildValue(\"\");" -msgstr "return Py_BuildValue(\"\");" - -#: ../../faq/windows.rst:243 -msgid "" -"It may be possible to use SWIG's ``%typemap`` command to make the change " -"automatically, though I have not been able to get this to work (I'm a " -"complete SWIG newbie)." -msgstr "" -"有可能可以使用 SWIG 的 ``%typemap`` 命令以自動進行程式碼變更，雖然我未曾這樣" -"正常運作過（我是一個完全的 SWIG 新手）。" - -#: ../../faq/windows.rst:247 -msgid "" -"Using a Python shell script to put up a Python interpreter window from " -"inside your Windows app is not a good idea; the resulting window will be " -"independent of your app's windowing system. Rather, you (or the " -"wxPythonWindow class) should create a \"native\" interpreter window. It is " -"easy to connect that window to the Python interpreter. You can redirect " -"Python's i/o to _any_ object that supports read and write, so all you need " -"is a Python object (defined in your extension module) that contains read() " -"and write() methods." -msgstr "" -"使用 Python shell 腳本從你的 Windows 應用程式內部建造一個 Python 直譯器視窗不" -"是一個好主意；該視窗將會獨立於你的應用程式視窗系統。與其如此，你（或 " -"wxPythonWindow class）應該要建立一個「本機」直譯器視窗。將該視窗連接到 " -"Python 直譯器是很容易的。你可以將 Python 的 i/o 重定向 (redirect) 到可支援讀" -"取和寫入的任何物件，因此你只需要一個包含 read() 和 write() method 的 Python " -"物件（在你的擴充模組中被定義）就可以了。" - -#: ../../faq/windows.rst:256 -msgid "How do I keep editors from inserting tabs into my Python source?" -msgstr "如何防止編輯器在我的 Python 原始碼中插入 tab？" - -#: ../../faq/windows.rst:258 -msgid "" -"The FAQ does not recommend using tabs, and the Python style guide, :pep:`8`, " -"recommends 4 spaces for distributed Python code; this is also the Emacs " -"python-mode default." -msgstr "" -"FAQ 不建議使用 tab，且 Python 風格指南 :pep:`8` 建議在分散式 Python 程式碼使" -"用 4 個空格；這也是 Emacs 的 python 模式預設值。" - -#: ../../faq/windows.rst:262 -msgid "" -"Under any editor, mixing tabs and spaces is a bad idea. MSVC is no " -"different in this respect, and is easily configured to use spaces: " -"Take :menuselection:`Tools --> Options --> Tabs`, and for file type " -"\"Default\" set \"Tab size\" and \"Indent size\" to 4, and select the " -"\"Insert spaces\" radio button." -msgstr "" -"在任何編輯器下，將 tab 和空格混合都是一個壞主意。MSVC 在這方面也是一樣，且可" -"以輕鬆配置為使用空格：選擇\\ :menuselection:`工具 --> 選項 --> Tabs`，然後對" -"於「預設」檔案類型，將「Tab 大小」和「縮排大小」設定為 4，然後選擇「插入空" -"格」單選鈕。" - -#: ../../faq/windows.rst:267 -msgid "" -"Python raises :exc:`IndentationError` or :exc:`TabError` if mixed tabs and " -"spaces are causing problems in leading whitespace. You may also run " -"the :mod:`tabnanny` module to check a directory tree in batch mode." -msgstr "" -"如果混合 tab 和空格造成前導空白字元出現問題，則 Python 會引" -"發 :exc:`IndentationError` 或 :exc:`TabError`。你也可以運行 :mod:`tabnanny` " -"模組，在批次模式下檢查目錄樹。" - -#: ../../faq/windows.rst:274 -msgid "How do I check for a keypress without blocking?" -msgstr "如何在不阻塞的情況下檢查 keypress？" - -#: ../../faq/windows.rst:276 -msgid "" -"Use the :mod:`msvcrt` module. This is a standard Windows-specific extension " -"module. It defines a function ``kbhit()`` which checks whether a keyboard " -"hit is present, and ``getch()`` which gets one character without echoing it." -msgstr "" -"使用 :mod:`msvcrt` 模組。這是一個標準的 Windows 專用擴充模組。它定義了一個函" -"式 ``kbhit()``，該函式會檢查是否出現鍵盤打擊 (keyboard hit)，以及函式 " -"``getch()``，該函式會取得一個字元且不會將其印出。" - -#: ../../faq/windows.rst:281 -msgid "How do I solve the missing api-ms-win-crt-runtime-l1-1-0.dll error?" -msgstr "如何解決遺漏 api-ms-win-crt-runtime-l1-1-0.dll 的錯誤？" - -#: ../../faq/windows.rst:283 -msgid "" -"This can occur on Python 3.5 and later when using Windows 8.1 or earlier " -"without all updates having been installed. First ensure your operating " -"system is supported and is up to date, and if that does not resolve the " -"issue, visit the `Microsoft support page `_ for guidance on manually installing the C Runtime update." -msgstr "" -"使用 Windows 8.1 或更早版本時，若尚未安裝所有的更新，則可能會在 Python 3.5 以" -"上的版本發生這種情況。首先要確保你的作業系統仍受支援並且是最新的，如果這無法" -"解決問題，請造訪 `Microsoft 支援頁面 `_\\ 以取得關於手動安裝 C Runtime 更新的指南。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Cecil Sheng , 2015 +# Liang-Bo Wang , 2015 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-09-01 22:24+0800\n" +"PO-Revision-Date: 2022-11-09 17:25+0800\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" +"X-Generator: Poedit 3.2\n" + +#: ../../faq/windows.rst:9 +msgid "Python on Windows FAQ" +msgstr "在 Windows 使用 Python 的常見問答集" + +#: ../../faq/windows.rst:12 +msgid "Contents" +msgstr "目錄" + +#: ../../faq/windows.rst:22 +msgid "How do I run a Python program under Windows?" +msgstr "如何在 Windows 作業系統裡運行 Python 程式？" + +#: ../../faq/windows.rst:24 +msgid "" +"This is not necessarily a straightforward question. If you are already " +"familiar with running programs from the Windows command line then everything " +"will seem obvious; otherwise, you might need a little more guidance." +msgstr "" +"這個問題的答案可能有點複雜。如果你經常使用「命令提示字元」執行程式，那這對你" +"來說不會是什麼難事。如果不然，那就需要更仔細的說明了。" + +#: ../../faq/windows.rst:28 +msgid "" +"Unless you use some sort of integrated development environment, you will end " +"up *typing* Windows commands into what is referred to as a \"Command prompt " +"window\". Usually you can create such a window from your search bar by " +"searching for ``cmd``. You should be able to recognize when you have " +"started such a window because you will see a Windows \"command prompt\", " +"which usually looks like this:" +msgstr "" +"除非你使用某種整合開發環境，否則你最終將會在所謂的「命令提示字元視窗」中 *打" +"字輸入* Windows 命令。通常，你可以透過從搜尋欄中搜尋 ``cmd`` 來建立這樣的視" +"窗。你應該能夠認出何時已啟動這樣的視窗，因為你將看到 Windows「命令提示字" +"元」，它通常看起來像這樣：" + +#: ../../faq/windows.rst:35 +msgid "C:\\>" +msgstr "C:\\>" + +#: ../../faq/windows.rst:39 +msgid "" +"The letter may be different, and there might be other things after it, so " +"you might just as easily see something like:" +msgstr "" +"第一個字母可能不一樣，且後面也可能還有其他內容，因此你可能會很容易看到類似以" +"下的文字：" + +#: ../../faq/windows.rst:42 +msgid "D:\\YourName\\Projects\\Python>" +msgstr "D:\\YourName\\Projects\\Python>" + +#: ../../faq/windows.rst:46 +msgid "" +"depending on how your computer has been set up and what else you have " +"recently done with it. Once you have started such a window, you are well on " +"the way to running Python programs." +msgstr "" +"取決於你的電腦如何被設置，以及你最近對它所做的其他操作。一旦你啟動了這樣一個" +"視窗，你就即將可以運行 Python 程式了。" + +#: ../../faq/windows.rst:50 +msgid "" +"You need to realize that your Python scripts have to be processed by another " +"program called the Python *interpreter*. The interpreter reads your script, " +"compiles it into bytecodes, and then executes the bytecodes to run your " +"program. So, how do you arrange for the interpreter to handle your Python?" +msgstr "" +"你需要了解，你的 Python 腳本必須被另一個稱為 Python *直譯器*\\ 的程序來處理。" +"直譯器會讀取你的腳本，將其編譯為位元組碼，然後執行該位元組碼以運行你的程式。" +"那麼，你要如何安排直譯器來處理你的 Python 呢？" + +#: ../../faq/windows.rst:55 +msgid "" +"First, you need to make sure that your command window recognises the word " +"\"py\" as an instruction to start the interpreter. If you have opened a " +"command window, you should try entering the command ``py`` and hitting " +"return:" +msgstr "" +"首先，你需要確保你的命令視窗會將單字 \"py\" 識別為啟動直譯器的指令。如果你已" +"經開啟一個命令視窗，則你應該試試輸入命令 ``py`` 並按下 return 鍵：" + +#: ../../faq/windows.rst:60 +msgid "C:\\Users\\YourName> py" +msgstr "C:\\Users\\YourName> py" + +#: ../../faq/windows.rst:64 +msgid "You should then see something like:" +msgstr "然後，你應該看到類似下面的內容：" + +#: ../../faq/windows.rst:66 +msgid "" +"Python 3.6.4 (v3.6.4:d48eceb, Dec 19 2017, 06:04:45) [MSC v.1900 32 bit " +"(Intel)] on win32\n" +"Type \"help\", \"copyright\", \"credits\" or \"license\" for more " +"information.\n" +">>>" +msgstr "" +"Python 3.6.4 (v3.6.4:d48eceb, Dec 19 2017, 06:04:45) [MSC v.1900 32 bit " +"(Intel)] on win32\n" +"Type \"help\", \"copyright\", \"credits\" or \"license\" for more " +"information.\n" +">>>" + +#: ../../faq/windows.rst:72 +msgid "" +"You have started the interpreter in \"interactive mode\". That means you can " +"enter Python statements or expressions interactively and have them executed " +"or evaluated while you wait. This is one of Python's strongest features. " +"Check it by entering a few expressions of your choice and seeing the results:" +msgstr "" +"你已經啟動直譯器中的「互動模式」。這表示你能夠以互動方式輸入 Python 陳述式或" +"運算式，並在等待時執行或計算它們。這是 Python 最強大的功能之一。輸入你所選的" +"幾個運算式並查看結果，可以檢驗此功能：" + +#: ../../faq/windows.rst:77 +msgid "" +">>> print(\"Hello\")\n" +"Hello\n" +">>> \"Hello\" * 3\n" +"'HelloHelloHello'" +msgstr "" +">>> print(\"Hello\")\n" +"Hello\n" +">>> \"Hello\" * 3\n" +"'HelloHelloHello'" + +#: ../../faq/windows.rst:84 +msgid "" +"Many people use the interactive mode as a convenient yet highly programmable " +"calculator. When you want to end your interactive Python session, call " +"the :func:`exit` function or hold the :kbd:`Ctrl` key down while you enter " +"a :kbd:`Z`, then hit the \":kbd:`Enter`\" key to get back to your Windows " +"command prompt." +msgstr "" +"許多人將互動模式作為方便但可高度程式化的計算機。如果你要結束互動式 Python 對" +"話，請呼叫 :func:`exit` 函式或是按住 :kbd:`Ctrl` 鍵再輸入 :kbd:`Z`，然後按下 " +"\":kbd:`Enter`\" 鍵以返回 Windows 命令提示字元。" + +#: ../../faq/windows.rst:90 +msgid "" +"You may also find that you have a Start-menu entry such " +"as :menuselection:`Start --> Programs --> Python 3.x --> Python (command " +"line)` that results in you seeing the ``>>>`` prompt in a new window. If " +"so, the window will disappear after you call the :func:`exit` function or " +"enter the :kbd:`Ctrl-Z` character; Windows is running a single \"python\" " +"command in the window, and closes it when you terminate the interpreter." +msgstr "" +"你可能還會發現你有一個開始功能表項目，像是：:menuselection:`開始 --> 所有程" +"式 --> Python 3.x --> Python（命令行）`，它會讓你在一個新視窗中看到 ``>>>`` " +"提示字元。如果是這樣，該視窗將在你呼叫 :func:`exit` 函式或輸入 :kbd:`Ctrl-Z` " +"字元後消失；Windows 正在該視窗中運行單一個「python」命令，並在你終止直譯器時" +"將其關閉。" + +#: ../../faq/windows.rst:97 +msgid "" +"Now that we know the ``py`` command is recognized, you can give your Python " +"script to it. You'll have to give either an absolute or a relative path to " +"the Python script. Let's say your Python script is located in your desktop " +"and is named ``hello.py``, and your command prompt is nicely opened in your " +"home directory so you're seeing something similar to::" +msgstr "" +"現在我們知道 ``py`` 命令已被識別，而你可以將你的 Python 腳本提供給它。你必須" +"為 Python 腳本給定絕對路徑或相對路徑。假設你的 Python 腳本位於桌面上，並被命" +"名為 ``hello.py``，且你的命令提示字元在你的家目錄 (home directory) 中順利地被" +"開啟，那麼你就會看到類似以下的內容： ::" + +#: ../../faq/windows.rst:104 +msgid "C:\\Users\\YourName>" +msgstr "C:\\Users\\YourName>" + +#: ../../faq/windows.rst:106 +msgid "" +"So now you'll ask the ``py`` command to give your script to Python by typing " +"``py`` followed by your script path::" +msgstr "" +"因此，現在你將透過鍵入 ``py`` 加上腳本路徑，來使用 ``py`` 命令將你的腳本提供" +"給 Python： ::" + +#: ../../faq/windows.rst:110 +msgid "" +"C:\\Users\\YourName> py Desktop\\hello.py\n" +"hello" +msgstr "" +"C:\\Users\\YourName> py Desktop\\hello.py\n" +"hello" + +#: ../../faq/windows.rst:114 +msgid "How do I make Python scripts executable?" +msgstr "如何使 Python 腳本可以執行？" + +#: ../../faq/windows.rst:116 +msgid "" +"On Windows, the standard Python installer already associates the .py " +"extension with a file type (Python.File) and gives that file type an open " +"command that runs the interpreter (``D:\\Program Files\\Python\\python.exe " +"\"%1\" %*``). This is enough to make scripts executable from the command " +"prompt as 'foo.py'. If you'd rather be able to execute the script by simple " +"typing 'foo' with no extension you need to add .py to the PATHEXT " +"environment variable." +msgstr "" +"在 Windows 上，標準的 Python 安裝程式已將 .py 副檔名與一種檔案類型 " +"(Python.File) 進行關聯，並為該檔案類型提供一個開啟命令來運行直譯器 (``D:" +"\\Program Files\\Python\\python.exe \"%1\" %*``)。這足以使腳本能以類似 " +"'foo.py' 的形式從命令提示字元被執行。如果你希望能夠簡單地輸入 'foo' 來執行腳" +"本，而不用加上副檔名，則需要將 .py 新增至 PATHEXT 環境變數中。" + +#: ../../faq/windows.rst:124 +msgid "Why does Python sometimes take so long to start?" +msgstr "為什麼 Python 有時需要這麼長的時間才能開始？" + +#: ../../faq/windows.rst:126 +msgid "" +"Usually Python starts very quickly on Windows, but occasionally there are " +"bug reports that Python suddenly begins to take a long time to start up. " +"This is made even more puzzling because Python will work fine on other " +"Windows systems which appear to be configured identically." +msgstr "" +"通常 Python 在 Windows 上啟動得非常快，但偶爾會有一些錯誤報告，內容是 Python " +"突然開始需要很長的時間才能啟動。這種情形更令人費解，因為 Python 在其他 " +"Windows 系統上可以正常工作，而那些系統似乎也有相同的配置。" + +#: ../../faq/windows.rst:131 +msgid "" +"The problem may be caused by a misconfiguration of virus checking software " +"on the problem machine. Some virus scanners have been known to introduce " +"startup overhead of two orders of magnitude when the scanner is configured " +"to monitor all reads from the filesystem. Try checking the configuration of " +"virus scanning software on your systems to ensure that they are indeed " +"configured identically. McAfee, when configured to scan all file system read " +"activity, is a particular offender." +msgstr "" +"這個問題可能是由發生此問題的電腦上的病毒檢查軟體配置錯誤所引起的。目前已知某" +"些病毒掃描程式，在它們被配置為監視來自檔案系統的所有讀取時，會引入兩個數量級" +"的啟動負擔。請試著檢查你系統上的病毒掃描軟體配置，以確保它們的配置確實相同。" +"當 McAfee 被配置為掃描所有檔案系統的讀取活動時，它是一個特定的違規者。" + +#: ../../faq/windows.rst:141 +msgid "How do I make an executable from a Python script?" +msgstr "如何從 Python 腳本製作可執行檔？" + +#: ../../faq/windows.rst:143 +msgid "" +"See :ref:`faq-create-standalone-binary` for a list of tools that can be used " +"to make executables." +msgstr "" +"請參閱\\ :ref:`faq-create-standalone-binary`\\ 該章節列出了用於製作可執行檔的" +"工具清單。" + +#: ../../faq/windows.rst:148 +msgid "Is a ``*.pyd`` file the same as a DLL?" +msgstr "``*.pyd`` 檔是否與 DLL 相同？" + +#: ../../faq/windows.rst:150 +msgid "" +"Yes, .pyd files are dll's, but there are a few differences. If you have a " +"DLL named ``foo.pyd``, then it must have a function ``PyInit_foo()``. You " +"can then write Python \"import foo\", and Python will search for foo.pyd (as " +"well as foo.py, foo.pyc) and if it finds it, will attempt to call " +"``PyInit_foo()`` to initialize it. You do not link your .exe with foo.lib, " +"as that would cause Windows to require the DLL to be present." +msgstr "" +"是的，.pyd 檔類似於 dll，但也有一些區別。如果你有一個名為 ``foo.pyd`` 的 " +"DLL，則它必須具有函式 ``PyInit_foo()``。接著你可以將 \"import foo\" 寫入 " +"Python 腳本，Python 將會搜尋 foo.pyd（以及 foo.py、foo.pyc），如果 Python 找" +"到它，將會嘗試呼叫 ``PyInit_foo()`` 來將它初始化。你並不會將你的 .exe 與 " +"foo.lib 連結 (link)，因為這會導致 Windows 要求 DLL 的存在。" + +#: ../../faq/windows.rst:157 +msgid "" +"Note that the search path for foo.pyd is PYTHONPATH, not the same as the " +"path that Windows uses to search for foo.dll. Also, foo.pyd need not be " +"present to run your program, whereas if you linked your program with a dll, " +"the dll is required. Of course, foo.pyd is required if you want to say " +"``import foo``. In a DLL, linkage is declared in the source code with " +"``__declspec(dllexport)``. In a .pyd, linkage is defined in a list of " +"available functions." +msgstr "" +"請注意，foo.pyd 的搜尋路徑是 PYTHONPATH，與 Windows 用於搜尋 foo.dll 的路徑不" +"同。此外，foo.pyd 不需存在即可運行你的程式，然而如果你將程式連結了一個 dll，" +"則該 dll 會是必要的。當然，如果你想要 ``import foo``，foo.pyd 就是必要的。在 " +"DLL 中，連結是以 ``__declspec(dllexport)`` 在原始碼中被宣告。在 .pyd 中，連結" +"是在一個可用函式的 list（串列）中被定義。" + +#: ../../faq/windows.rst:166 +msgid "How can I embed Python into a Windows application?" +msgstr "如何將 Python 嵌入 Windows 應用程式中？" + +#: ../../faq/windows.rst:168 +msgid "" +"Embedding the Python interpreter in a Windows app can be summarized as " +"follows:" +msgstr "在 Windows 應用程式中嵌入 Python 直譯器的過程可以總結如下：" + +#: ../../faq/windows.rst:170 +msgid "" +"Do **not** build Python into your .exe file directly. On Windows, Python " +"must be a DLL to handle importing modules that are themselves DLL's. (This " +"is the first key undocumented fact.) Instead, link " +"to :file:`python{NN}.dll`; it is typically installed in ``C:" +"\\Windows\\System``. *NN* is the Python version, a number such as \"33\" " +"for Python 3.3." +msgstr "" +"**不要**\\ 直接將 Python 建置到你的 .exe 檔中。在 Windows 上，Python 必須是一" +"個 DLL 來處理模組的 import，而那些模組本身也是 DLL。（這是第一個未正式記載的" +"關鍵事實。）請改為連結到 :file:`python{NN}.dll`；它通常被安裝在 ``C:" +"\\Windows\\System`` 中。*NN* 是 Python 版本，例如 \"33\" 就是指 Python 3.3。" + +#: ../../faq/windows.rst:176 +msgid "" +"You can link to Python in two different ways. Load-time linking means " +"linking against :file:`python{NN}.lib`, while run-time linking means linking " +"against :file:`python{NN}.dll`. (General note: :file:`python{NN}.lib` is " +"the so-called \"import lib\" corresponding to :file:`python{NN}.dll`. It " +"merely defines symbols for the linker.)" +msgstr "" +"你可以透過兩種不同的方式連結到 Python。載入時連結 (load-time linking) 表示要" +"連結到 :file:`python{NN}.lib`，而執行環境連結 (run-time linking) 表示要連結" +"到 :file:`python{NN}.dll`。（一般註解：:file:`python{NN}.lib` " +"是 :file:`python{NN}.dll` 相對應的所謂 \"import lib\"。它只會為鏈接器定義符" +"號。）" + +#: ../../faq/windows.rst:182 +msgid "" +"Run-time linking greatly simplifies link options; everything happens at run " +"time. Your code must load :file:`python{NN}.dll` using the Windows " +"``LoadLibraryEx()`` routine. The code must also use access routines and " +"data in :file:`python{NN}.dll` (that is, Python's C API's) using pointers " +"obtained by the Windows ``GetProcAddress()`` routine. Macros can make using " +"these pointers transparent to any C code that calls routines in Python's C " +"API." +msgstr "" +"執行環境連結大大簡化了連結選項；所有事情都會發生在執行環境。你的程式碼必須使" +"用 Windows ``LoadLibraryEx()`` 常式 (routine) 來載入 :file:`python{NN}.dll`。" +"該程式碼也必須用 Windows ``GetProcAddress()`` 常式所取得的指標，來使" +"用 :file:`python{NN}.dll` 中的（即為 Python C API 的）存取常式和資料。對於任" +"何呼叫 Python C API 常式的 C 程式碼，巨集可以讓使用這些指標的過程透明化。" + +#: ../../faq/windows.rst:191 +msgid "" +"If you use SWIG, it is easy to create a Python \"extension module\" that " +"will make the app's data and methods available to Python. SWIG will handle " +"just about all the grungy details for you. The result is C code that you " +"link *into* your .exe file (!) You do **not** have to create a DLL file, " +"and this also simplifies linking." +msgstr "" +"如果你使用 SWIG，則可輕鬆地建立一個 Python 「擴充模組」，該模組將使應用程式的" +"資料和 method（方法）可供 Python 使用。SWIG 會為你處理幾乎所有的繁瑣細節。結" +"果就是，你會將 C 程式碼連結\\ *到*\\ 你的 .exe 檔裡（！）你\\ **不必**\\ 建" +"立 DLL 檔，而這也簡化了連結。" + +#: ../../faq/windows.rst:197 +msgid "" +"SWIG will create an init function (a C function) whose name depends on the " +"name of the extension module. For example, if the name of the module is " +"leo, the init function will be called initleo(). If you use SWIG shadow " +"classes, as you should, the init function will be called initleoc(). This " +"initializes a mostly hidden helper class used by the shadow class." +msgstr "" +"SWIG 將建立一個 init 函式（一個 C 函式），其名稱取決於擴充模組的名稱。例如，" +"如果模組的名稱是 leo，則該 init 函式會命名為 initleo()。如果你使用 SWIG " +"shadow class（類別），則 init 函式會命名為 initleoc()。這會初始化被 shadow " +"class 所用的大多數隱藏的 helper class。" + +#: ../../faq/windows.rst:203 +msgid "" +"The reason you can link the C code in step 2 into your .exe file is that " +"calling the initialization function is equivalent to importing the module " +"into Python! (This is the second key undocumented fact.)" +msgstr "" +"你可以將步驟 2 中的 C 程式碼連結到 .exe 檔中的原因是，呼叫初始化函式就等效於 " +"import 模組進 Python！（這是第二個未正式記載的關鍵事實。）" + +#: ../../faq/windows.rst:207 +msgid "" +"In short, you can use the following code to initialize the Python " +"interpreter with your extension module." +msgstr "簡而言之，你可以使用以下程式碼，以你的擴充模組初始化 Python 直譯器。" + +#: ../../faq/windows.rst:210 +msgid "" +"#include \n" +"...\n" +"Py_Initialize(); // Initialize Python.\n" +"initmyAppc(); // Initialize (import) the helper class.\n" +"PyRun_SimpleString(\"import myApp\"); // Import the shadow class." +msgstr "" +"#include \n" +"...\n" +"Py_Initialize(); // 初始化 Python。\n" +"initmyAppc(); // 初始化（引入）幫助類別。\n" +"PyRun_SimpleString(\"import myApp\"); // 引入 shadow 類別。" + +#: ../../faq/windows.rst:218 +msgid "" +"There are two problems with Python's C API which will become apparent if you " +"use a compiler other than MSVC, the compiler used to build pythonNN.dll." +msgstr "" +"Python 的 C API 有兩個問題，如果你使用 MSVC（用於建置 pythonNN.dll 的編譯器）" +"以外的編譯器，這些問題將會變得明顯。" + +#: ../../faq/windows.rst:221 +msgid "" +"Problem 1: The so-called \"Very High Level\" functions that take ``FILE *`` " +"arguments will not work in a multi-compiler environment because each " +"compiler's notion of a ``struct FILE`` will be different. From an " +"implementation standpoint these are very low level functions." +msgstr "" +"問題 1：使用 ``FILE *`` 引數的所謂「非常高階」的函式，在多編譯器 (multi-" +"compiler) 的環境中會無法作用，因為每個編譯器對 ``struct FILE`` 的概念不同。從" +"實作的觀點來看，這些都是非常\\ _低階_\\ 的函式。" + +#: ../../faq/windows.rst:226 +msgid "" +"Problem 2: SWIG generates the following code when generating wrappers to " +"void functions:" +msgstr "問題 2：SWIG 在為 void 函式產生包裝函式 (wrapper) 時會產生以下程式碼：" + +#: ../../faq/windows.rst:229 +msgid "" +"Py_INCREF(Py_None);\n" +"_resultobj = Py_None;\n" +"return _resultobj;" +msgstr "" +"Py_INCREF(Py_None);\n" +"_resultobj = Py_None;\n" +"return _resultobj;" + +#: ../../faq/windows.rst:235 +msgid "" +"Alas, Py_None is a macro that expands to a reference to a complex data " +"structure called _Py_NoneStruct inside pythonNN.dll. Again, this code will " +"fail in a mult-compiler environment. Replace such code by:" +msgstr "" +"唉，Py_None 是一個巨集，它會延伸到一個參照，指向 pythonNN.dll 內部的一種稱為 " +"_Py_NoneStruct 的複雜資料結構。同樣的，此程式碼在多編譯器環境中將會失效。請將" +"此類程式碼替換為：" + +#: ../../faq/windows.rst:239 +msgid "return Py_BuildValue(\"\");" +msgstr "return Py_BuildValue(\"\");" + +#: ../../faq/windows.rst:243 +msgid "" +"It may be possible to use SWIG's ``%typemap`` command to make the change " +"automatically, though I have not been able to get this to work (I'm a " +"complete SWIG newbie)." +msgstr "" +"有可能可以使用 SWIG 的 ``%typemap`` 命令以自動進行程式碼變更，雖然我未曾這樣" +"正常運作過（我是一個完全的 SWIG 新手）。" + +#: ../../faq/windows.rst:247 +msgid "" +"Using a Python shell script to put up a Python interpreter window from " +"inside your Windows app is not a good idea; the resulting window will be " +"independent of your app's windowing system. Rather, you (or the " +"wxPythonWindow class) should create a \"native\" interpreter window. It is " +"easy to connect that window to the Python interpreter. You can redirect " +"Python's i/o to _any_ object that supports read and write, so all you need " +"is a Python object (defined in your extension module) that contains read() " +"and write() methods." +msgstr "" +"使用 Python shell 腳本從你的 Windows 應用程式內部建造一個 Python 直譯器視窗不" +"是一個好主意；該視窗將會獨立於你的應用程式視窗系統。與其如此，你（或 " +"wxPythonWindow class）應該要建立一個「本機」直譯器視窗。將該視窗連接到 " +"Python 直譯器是很容易的。你可以將 Python 的 i/o 重定向 (redirect) 到可支援讀" +"取和寫入的任何物件，因此你只需要一個包含 read() 和 write() method 的 Python " +"物件（在你的擴充模組中被定義）就可以了。" + +#: ../../faq/windows.rst:256 +msgid "How do I keep editors from inserting tabs into my Python source?" +msgstr "如何防止編輯器在我的 Python 原始碼中插入 tab？" + +#: ../../faq/windows.rst:258 +msgid "" +"The FAQ does not recommend using tabs, and the Python style guide, :pep:`8`, " +"recommends 4 spaces for distributed Python code; this is also the Emacs " +"python-mode default." +msgstr "" +"FAQ 不建議使用 tab，且 Python 風格指南 :pep:`8` 建議在分散式 Python 程式碼使" +"用 4 個空格；這也是 Emacs 的 python 模式預設值。" + +#: ../../faq/windows.rst:262 +msgid "" +"Under any editor, mixing tabs and spaces is a bad idea. MSVC is no " +"different in this respect, and is easily configured to use spaces: " +"Take :menuselection:`Tools --> Options --> Tabs`, and for file type " +"\"Default\" set \"Tab size\" and \"Indent size\" to 4, and select the " +"\"Insert spaces\" radio button." +msgstr "" +"在任何編輯器下，將 tab 和空格混合都是一個壞主意。MSVC 在這方面也是一樣，且可" +"以輕鬆配置為使用空格：選擇\\ :menuselection:`工具 --> 選項 --> Tabs`，然後對" +"於「預設」檔案類型，將「Tab 大小」和「縮排大小」設定為 4，然後選擇「插入空" +"格」單選鈕。" + +#: ../../faq/windows.rst:267 +msgid "" +"Python raises :exc:`IndentationError` or :exc:`TabError` if mixed tabs and " +"spaces are causing problems in leading whitespace. You may also run " +"the :mod:`tabnanny` module to check a directory tree in batch mode." +msgstr "" +"如果混合 tab 和空格造成前導空白字元出現問題，則 Python 會引" +"發 :exc:`IndentationError` 或 :exc:`TabError`。你也可以運行 :mod:`tabnanny` " +"模組，在批次模式下檢查目錄樹。" + +#: ../../faq/windows.rst:274 +msgid "How do I check for a keypress without blocking?" +msgstr "如何在不阻塞的情況下檢查 keypress？" + +#: ../../faq/windows.rst:276 +msgid "" +"Use the :mod:`msvcrt` module. This is a standard Windows-specific extension " +"module. It defines a function ``kbhit()`` which checks whether a keyboard " +"hit is present, and ``getch()`` which gets one character without echoing it." +msgstr "" +"使用 :mod:`msvcrt` 模組。這是一個標準的 Windows 專用擴充模組。它定義了一個函" +"式 ``kbhit()``，該函式會檢查是否出現鍵盤打擊 (keyboard hit)，以及函式 " +"``getch()``，該函式會取得一個字元且不會將其印出。" + +#: ../../faq/windows.rst:281 +msgid "How do I solve the missing api-ms-win-crt-runtime-l1-1-0.dll error?" +msgstr "如何解決遺漏 api-ms-win-crt-runtime-l1-1-0.dll 的錯誤？" + +#: ../../faq/windows.rst:283 +msgid "" +"This can occur on Python 3.5 and later when using Windows 8.1 or earlier " +"without all updates having been installed. First ensure your operating " +"system is supported and is up to date, and if that does not resolve the " +"issue, visit the `Microsoft support page `_ for guidance on manually installing the C Runtime update." +msgstr "" +"使用 Windows 8.1 或更早版本時，若尚未安裝所有的更新，則可能會在 Python 3.5 以" +"上的版本發生這種情況。首先要確保你的作業系統仍受支援並且是最新的，如果這無法" +"解決問題，請造訪 `Microsoft 支援頁面 `_\\ 以取得關於手動安裝 C Runtime 更新的指南。" diff --git a/glossary.po b/glossary.po index adfd51e065..5fc2ffb986 100644 --- a/glossary.po +++ b/glossary.po @@ -1,3678 +1,3678 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# Translators: -# Steven Hsu , 2021-2022 -# Matt Wang , 2021 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-12-17 17:02+0000\n" -"PO-Revision-Date: 2023-07-02 22:47+0800\n" -"Last-Translator: Matt Wang \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" -"X-Generator: Poedit 3.3.2\n" - -#: ../../glossary.rst:5 -msgid "Glossary" -msgstr "術語表" - -#: ../../glossary.rst:10 -msgid "``>>>``" -msgstr "``>>>``" - -#: ../../glossary.rst:12 -msgid "" -"The default Python prompt of the :term:`interactive` shell. Often seen for " -"code examples which can be executed interactively in the interpreter." -msgstr "" -":term:`互動式 ` shell 的預設 Python 提示字元。常見於能在直譯器中" -"以互動方式被執行的程式碼範例。" - -#: ../../glossary.rst:15 -msgid "``...``" -msgstr "``...``" - -#: ../../glossary.rst:17 -msgid "Can refer to:" -msgstr "可以表示：" - -#: ../../glossary.rst:19 -msgid "" -"The default Python prompt of the :term:`interactive` shell when entering the " -"code for an indented code block, when within a pair of matching left and " -"right delimiters (parentheses, square brackets, curly braces or triple " -"quotes), or after specifying a decorator." -msgstr "" -"在一個被縮排的程式碼區塊、在一對匹配的左右定界符（delimiter，例如括號、方括" -"號、花括號或三引號）內部，或是在指定一個裝飾器 (decorator) 之後，要輸入程式碼" -"時，:term:`互動式 ` shell 顯示的預設 Python 提示字元。" - -#: ../../glossary.rst:26 -msgid "" -"The three dots form of the :ref:`Ellipsis ` object." -msgstr "" - -#: ../../glossary.rst:27 -msgid "abstract base class" -msgstr "abstract base class（抽象基底類別）" - -#: ../../glossary.rst:29 -msgid "" -"Abstract base classes complement :term:`duck-typing` by providing a way to " -"define interfaces when other techniques like :func:`hasattr` would be clumsy " -"or subtly wrong (for example with :ref:`magic methods `). " -"ABCs introduce virtual subclasses, which are classes that don't inherit from " -"a class but are still recognized by :func:`isinstance` and :func:" -"`issubclass`; see the :mod:`abc` module documentation. Python comes with " -"many built-in ABCs for data structures (in the :mod:`collections.abc` " -"module), numbers (in the :mod:`numbers` module), streams (in the :mod:`io` " -"module), import finders and loaders (in the :mod:`importlib.abc` module). " -"You can create your own ABCs with the :mod:`abc` module." -msgstr "" -"抽象基底類別（又稱為 ABC）提供了一種定義介面的方法，作為 :term:`duck-" -"typing`\\ （鴨子型別）的補充。其他類似的技術，像是 :func:`hasattr`，則顯得笨" -"拙或是帶有細微的錯誤（例如使用\\ :ref:`魔術方法 (magic method) `\\ ）。ABC 採用虛擬的 subclass（子類別），它們並不繼承自另一個 class" -"（類別），但仍可被 :func:`isinstance` 及 :func:`issubclass` 辨識；請參閱 :" -"mod:`abc` 模組的說明文件。Python 有許多內建的 ABC，用於資料結構（在 :mod:" -"`collections.abc` 模組）、數字（在 :mod:`numbers` 模組）、串流（在 :mod:`io` " -"模組）及 import 尋檢器和載入器（在 :mod:`importlib.abc` 模組）。你可以使用 :" -"mod:`abc` 模組建立自己的 ABC。" - -#: ../../glossary.rst:40 -msgid "annotate function" -msgstr "annotate function（註釋函式）" - -#: ../../glossary.rst:42 -msgid "" -"A function that can be called to retrieve the :term:`annotations " -"` of an object. This function is accessible as the :attr:" -"`~object.__annotate__` attribute of functions, classes, and modules. " -"Annotate functions are a subset of :term:`evaluate functions `." -msgstr "" - -#: ../../glossary.rst:46 -msgid "annotation" -msgstr "annotation（註釋）" - -#: ../../glossary.rst:48 -msgid "" -"A label associated with a variable, a class attribute or a function " -"parameter or return value, used by convention as a :term:`type hint`." -msgstr "" -"一個與變數、class 屬性、函式的參數或回傳值相關聯的標籤。照慣例，它被用來作" -"為 :term:`type hint`\\ （型別提示）。" - -#: ../../glossary.rst:52 -msgid "" -"Annotations of local variables cannot be accessed at runtime, but " -"annotations of global variables, class attributes, and functions can be " -"retrieved by calling :func:`annotationlib.get_annotations` on modules, " -"classes, and functions, respectively." -msgstr "" -"在 runtime 的區域變數註釋無法被存取，但全域變數、類別屬性和函式的註釋，分別能" -"夠以對模組、類別和函式呼叫 :func:`annotationlib.get_annotations` 來取得。" - -#: ../../glossary.rst:57 -msgid "" -"See :term:`variable annotation`, :term:`function annotation`, :pep:`484`, :" -"pep:`526`, and :pep:`649`, which describe this functionality. Also see :ref:" -"`annotations-howto` for best practices on working with annotations." -msgstr "" -"請參閱 :term:`variable annotation`、:term:`function annotation`、:pep:" -"`484`、:pep:`526` 和 :pep:`649`，這些章節皆有此功能的說明。關於註釋的最佳實踐" -"方法也請參閱 :ref:`annotations-howto`。" - -#: ../../glossary.rst:61 -msgid "argument" -msgstr "argument（引數）" - -#: ../../glossary.rst:63 -msgid "" -"A value passed to a :term:`function` (or :term:`method`) when calling the " -"function. There are two kinds of argument:" -msgstr "" -"呼叫函式時被傳遞給 :term:`function`\\ （或 :term:`method`\\ ）的值。引數有兩" -"種：" - -#: ../../glossary.rst:66 -msgid "" -":dfn:`keyword argument`: an argument preceded by an identifier (e.g. " -"``name=``) in a function call or passed as a value in a dictionary preceded " -"by ``**``. For example, ``3`` and ``5`` are both keyword arguments in the " -"following calls to :func:`complex`::" -msgstr "" -":dfn:`關鍵字引數 (keyword argument)`：在函式呼叫中，以識別字（identifier，例" -"如 ``name=``\\ ）開頭的引數，或是以 ``**`` 後面 dictionary（字典）內的值被傳" -"遞的引數。例如，``3`` 和 ``5`` 都是以下 :func:`complex` 呼叫中的關鍵字引" -"數： ::" - -#: ../../glossary.rst:71 -msgid "" -"complex(real=3, imag=5)\n" -"complex(**{'real': 3, 'imag': 5})" -msgstr "" -"complex(real=3, imag=5)\n" -"complex(**{'real': 3, 'imag': 5})" - -#: ../../glossary.rst:74 -msgid "" -":dfn:`positional argument`: an argument that is not a keyword argument. " -"Positional arguments can appear at the beginning of an argument list and/or " -"be passed as elements of an :term:`iterable` preceded by ``*``. For example, " -"``3`` and ``5`` are both positional arguments in the following calls::" -msgstr "" -":dfn:`位置引數 (positional argument)`：不是關鍵字引數的引數。位置引數可在一個" -"引數列表的起始處出現，和（或）作為 ``*`` 之後的 :term:`iterable`\\ （可疊代物" -"件）中的元素被傳遞。例如，``3`` 和 ``5`` 都是以下呼叫中的位置引數： ::" - -#: ../../glossary.rst:80 -msgid "" -"complex(3, 5)\n" -"complex(*(3, 5))" -msgstr "" -"complex(3, 5)\n" -"complex(*(3, 5))" - -#: ../../glossary.rst:83 -msgid "" -"Arguments are assigned to the named local variables in a function body. See " -"the :ref:`calls` section for the rules governing this assignment. " -"Syntactically, any expression can be used to represent an argument; the " -"evaluated value is assigned to the local variable." -msgstr "" -"引數會被指定給函式主體中的附名區域變數。關於支配這個指定過程的規則，請參閱" -"\\ :ref:`calls`\\ 章節。在語法上，任何運算式都可以被用來表示一個引數；其評估" -"值會被指定給區域變數。" - -#: ../../glossary.rst:88 -msgid "" -"See also the :term:`parameter` glossary entry, the FAQ question on :ref:`the " -"difference between arguments and parameters `, " -"and :pep:`362`." -msgstr "" -"另請參閱術語表的 :term:`parameter`\\ （參數）條目、常見問題中的\\ :ref:`引數" -"和參數之間的差異 `，以及 :pep:`362`。" - -#: ../../glossary.rst:91 -msgid "asynchronous context manager" -msgstr "asynchronous context manager（非同步情境管理器）" - -#: ../../glossary.rst:93 -msgid "" -"An object which controls the environment seen in an :keyword:`async with` " -"statement by defining :meth:`~object.__aenter__` and :meth:`~object." -"__aexit__` methods. Introduced by :pep:`492`." -msgstr "" -"一個可以控制 :keyword:`async with` 陳述式中所見環境的物件，而它是透過定義 :" -"meth:`~object.__aenter__` 和 :meth:`~object.__aexit__` method（方法）來控制" -"的。由 :pep:`492` 引入。" - -#: ../../glossary.rst:96 -msgid "asynchronous generator" -msgstr "asynchronous generator（非同步產生器）" - -#: ../../glossary.rst:98 -msgid "" -"A function which returns an :term:`asynchronous generator iterator`. It " -"looks like a coroutine function defined with :keyword:`async def` except " -"that it contains :keyword:`yield` expressions for producing a series of " -"values usable in an :keyword:`async for` loop." -msgstr "" -"一個會回傳 :term:`asynchronous generator iterator`\\ （非同步產生器疊代器）的" -"函式。它看起來像一個以 :keyword:`async def` 定義的協程函式 (coroutine " -"function)，但不同的是它包含了 :keyword:`yield` 運算式，能生成一系列可用於 :" -"keyword:`async for` 迴圈的值。" - -#: ../../glossary.rst:103 -msgid "" -"Usually refers to an asynchronous generator function, but may refer to an " -"*asynchronous generator iterator* in some contexts. In cases where the " -"intended meaning isn't clear, using the full terms avoids ambiguity." -msgstr "" -"這個術語通常用來表示一個非同步產生器函式，但在某些情境中，也可能是表示\\ *非" -"同步產生器疊代器 (asynchronous generator iterator)*。萬一想表達的意思不夠清" -"楚，那就使用完整的術語，以避免歧義。" - -#: ../../glossary.rst:107 -msgid "" -"An asynchronous generator function may contain :keyword:`await` expressions " -"as well as :keyword:`async for`, and :keyword:`async with` statements." -msgstr "" -"一個非同步產生器函式可能包含 :keyword:`await` 運算式，以及 :keyword:`async " -"for` 和 :keyword:`async with` 陳述式。" - -#: ../../glossary.rst:110 -msgid "asynchronous generator iterator" -msgstr "asynchronous generator iterator（非同步產生器疊代器）" - -#: ../../glossary.rst:112 -msgid "An object created by an :term:`asynchronous generator` function." -msgstr "" -"一個由 :term:`asynchronous generator`\\ （非同步產生器）函式所建立的物件。" - -#: ../../glossary.rst:114 -msgid "" -"This is an :term:`asynchronous iterator` which when called using the :meth:" -"`~object.__anext__` method returns an awaitable object which will execute " -"the body of the asynchronous generator function until the next :keyword:" -"`yield` expression." -msgstr "" -"這是一個 :term:`asynchronous iterator`\\ （非同步疊代器），當它以 :meth:" -"`~object.__anext__` method 被呼叫時，會回傳一個可等待物件 (awaitable " -"object)，該物件將執行非同步產生器的函式主體，直到遇到下一個 :keyword:`yield` " -"運算式。" - -#: ../../glossary.rst:119 -msgid "" -"Each :keyword:`yield` temporarily suspends processing, remembering the " -"execution state (including local variables and pending try-statements). " -"When the *asynchronous generator iterator* effectively resumes with another " -"awaitable returned by :meth:`~object.__anext__`, it picks up where it left " -"off. See :pep:`492` and :pep:`525`." -msgstr "" -"每個 :keyword:`yield` 會暫停處理程序，並記住執行狀態（包括區域變數及擱置中的 " -"try 陳述式）。當\\ *非同步產生器疊代器*\\ 以另一個被 :meth:`~object." -"__anext__` 回傳的可等待物件有效地回復時，它會從停止的地方繼續執行。請參閱 :" -"pep:`492` 和 :pep:`525`。" - -#: ../../glossary.rst:124 -msgid "asynchronous iterable" -msgstr "asynchronous iterable（非同步可疊代物件）" - -#: ../../glossary.rst:126 -msgid "" -"An object, that can be used in an :keyword:`async for` statement. Must " -"return an :term:`asynchronous iterator` from its :meth:`~object.__aiter__` " -"method. Introduced by :pep:`492`." -msgstr "" -"一個物件，它可以在 :keyword:`async for` 陳述式中被使用。必須從它的 :meth:" -"`~object.__aiter__` method 回傳一個 :term:`asynchronous iterator`\\ （非同步" -"疊代器）。由 :pep:`492` 引入。" - -#: ../../glossary.rst:129 -msgid "asynchronous iterator" -msgstr "asynchronous iterator（非同步疊代器）" - -#: ../../glossary.rst:131 -msgid "" -"An object that implements the :meth:`~object.__aiter__` and :meth:`~object." -"__anext__` methods. :meth:`~object.__anext__` must return an :term:" -"`awaitable` object. :keyword:`async for` resolves the awaitables returned by " -"an asynchronous iterator's :meth:`~object.__anext__` method until it raises " -"a :exc:`StopAsyncIteration` exception. Introduced by :pep:`492`." -msgstr "" -"一個實作 :meth:`~object.__aiter__` 和 :meth:`~object.__anext__` method 的物" -"件。:meth:`~object.__anext__` 必須回傳一個 :term:`awaitable`\\ （可等待物" -"件）。:keyword:`async for` 會解析非同步疊代器的 :meth:`~object.__anext__` " -"method 所回傳的可等待物件，直到它引發 :exc:`StopAsyncIteration` 例外。由 :" -"pep:`492` 引入。" - -#: ../../glossary.rst:136 -msgid "atomic operation" -msgstr "" - -#: ../../glossary.rst:138 -msgid "" -"An operation that appears to execute as a single, indivisible step: no other " -"thread can observe it half-done, and its effects become visible all at " -"once. Python does not guarantee that high-level statements are atomic (for " -"example, ``x += 1`` performs multiple bytecode operations and is not " -"atomic). Atomicity is only guaranteed where explicitly documented. See " -"also :term:`race condition` and :term:`data race`." -msgstr "" - -#: ../../glossary.rst:144 -msgid "attached thread state" -msgstr "" - -#: ../../glossary.rst:147 -msgid "A :term:`thread state` that is active for the current OS thread." -msgstr "" - -#: ../../glossary.rst:149 -msgid "" -"When a :term:`thread state` is attached, the OS thread has access to the " -"full Python C API and can safely invoke the bytecode interpreter." -msgstr "" - -#: ../../glossary.rst:153 -msgid "" -"Unless a function explicitly notes otherwise, attempting to call the C API " -"without an attached thread state will result in a fatal error or undefined " -"behavior. A thread state can be attached and detached explicitly by the " -"user through the C API, or implicitly by the runtime, including during " -"blocking C calls and by the bytecode interpreter in between calls." -msgstr "" - -#: ../../glossary.rst:160 -msgid "" -"On most builds of Python, having an attached thread state implies that the " -"caller holds the :term:`GIL` for the current interpreter, so only one OS " -"thread can have an attached thread state at a given moment. In :term:`free-" -"threaded ` builds of Python, threads can concurrently hold " -"an attached thread state, allowing for true parallelism of the bytecode " -"interpreter." -msgstr "" - -#: ../../glossary.rst:166 -msgid "attribute" -msgstr "attribute（屬性）" - -#: ../../glossary.rst:168 -msgid "" -"A value associated with an object which is usually referenced by name using " -"dotted expressions. For example, if an object *o* has an attribute *a* it " -"would be referenced as *o.a*." -msgstr "" -"一個與某物件相關聯的值，該值大多能透過使用點分隔運算式 (dotted expression) 的" -"名稱被參照。例如，如果物件 *o* 有一個屬性 *a*，則該屬性能以 *o.a* 被參照。" - -#: ../../glossary.rst:173 -msgid "" -"It is possible to give an object an attribute whose name is not an " -"identifier as defined by :ref:`identifiers`, for example using :func:" -"`setattr`, if the object allows it. Such an attribute will not be accessible " -"using a dotted expression, and would instead need to be retrieved with :func:" -"`getattr`." -msgstr "" -"如果一個物件允許，給予該物件一個名稱不是由\\ :ref:`identifiers`\\ 所定義之識" -"別符 (identifier) 的屬性是有可能的，例如使用 :func:`setattr`。像這樣的屬性將" -"無法使用點分隔運算式來存取，而是需要使用 :func:`getattr` 來取得它。" - -#: ../../glossary.rst:178 -msgid "awaitable" -msgstr "awaitable（可等待物件）" - -#: ../../glossary.rst:180 -msgid "" -"An object that can be used in an :keyword:`await` expression. Can be a :" -"term:`coroutine` or an object with an :meth:`~object.__await__` method. See " -"also :pep:`492`." -msgstr "" -"一個可以在 :keyword:`await` 運算式中被使用的物件。它可以是一個 :term:" -"`coroutine`\\ （協程），或是一個有 :meth:`~object.__await__` method 的物件。" -"另請參閱 :pep:`492`。" - -#: ../../glossary.rst:183 -msgid "BDFL" -msgstr "BDFL" - -#: ../../glossary.rst:185 -msgid "" -"Benevolent Dictator For Life, a.k.a. `Guido van Rossum `_, Python's creator." -msgstr "" -"Benevolent Dictator For Life（終身仁慈獨裁者），又名 `Guido van Rossum " -"`_，Python 的創造者。" - -#: ../../glossary.rst:187 -msgid "binary file" -msgstr "binary file（二進位檔案）" - -#: ../../glossary.rst:189 -msgid "" -"A :term:`file object` able to read and write :term:`bytes-like objects " -"`. Examples of binary files are files opened in binary " -"mode (``'rb'``, ``'wb'`` or ``'rb+'``), :data:`sys.stdin.buffer `, :data:`sys.stdout.buffer `, and instances of :class:`io." -"BytesIO` and :class:`gzip.GzipFile`." -msgstr "" -"一個能夠讀取和寫入 :term:`bytes-like objects `\\ （類位元" -"組串物件）的 :term:`file object`\\ （檔案物件）。二進位檔案的例子有：以二進位" -"模式（``'rb'``、``'wb'`` 或 ``'rb+'``）開啟的檔案、:data:`sys.stdin.buffer " -"`、:data:`sys.stdout.buffer `，以及 :class:`io." -"BytesIO` 和 :class:`gzip.GzipFile` 實例。" - -#: ../../glossary.rst:196 -msgid "" -"See also :term:`text file` for a file object able to read and write :class:" -"`str` objects." -msgstr "" -"另請參閱 :term:`text file`\\ （文字檔案），它是一個能夠讀取和寫入 :class:" -"`str` 物件的檔案物件。" - -#: ../../glossary.rst:198 -msgid "borrowed reference" -msgstr "borrowed reference（借用參照）" - -#: ../../glossary.rst:200 -msgid "" -"In Python's C API, a borrowed reference is a reference to an object, where " -"the code using the object does not own the reference. It becomes a dangling " -"pointer if the object is destroyed. For example, a garbage collection can " -"remove the last :term:`strong reference` to the object and so destroy it." -msgstr "" -"在 Python 的 C API 中，借用參照是一個對物件的參照，其中使用該物件的程式碼並不" -"擁有這個參照。如果該物件被銷毀，它會成為一個迷途指標 (dangling pointer)。例" -"如，一次垃圾回收 (garbage collection) 可以移除對物件的最後一個 :term:`strong " -"reference`\\ （強參照），而將該物件銷毀。" - -#: ../../glossary.rst:206 -msgid "" -"Calling :c:func:`Py_INCREF` on the :term:`borrowed reference` is recommended " -"to convert it to a :term:`strong reference` in-place, except when the object " -"cannot be destroyed before the last usage of the borrowed reference. The :c:" -"func:`Py_NewRef` function can be used to create a new :term:`strong " -"reference`." -msgstr "" -"對 :term:`borrowed reference` 呼叫 :c:func:`Py_INCREF` 以將它原地 (in-place) " -"轉換為 :term:`strong reference` 是被建議的做法，除非該物件不能在最後一次使用" -"借用參照之前被銷毀。:c:func:`Py_NewRef` 函式可用於建立一個新的 :term:`strong " -"reference`。" - -#: ../../glossary.rst:211 -msgid "bytes-like object" -msgstr "bytes-like object（類位元組串物件）" - -#: ../../glossary.rst:213 -msgid "" -"An object that supports the :ref:`bufferobjects` and can export a C-:term:" -"`contiguous` buffer. This includes all :class:`bytes`, :class:`bytearray`, " -"and :class:`array.array` objects, as well as many common :class:`memoryview` " -"objects. Bytes-like objects can be used for various operations that work " -"with binary data; these include compression, saving to a binary file, and " -"sending over a socket." -msgstr "" -"一個支援\\ :ref:`bufferobjects`\\ 且能夠匯出 C-:term:`contiguous` 緩衝區的物" -"件。這包括所有的 :class:`bytes`、:class:`bytearray` 和 :class:`array.array` " -"物件，以及許多常見的 :class:`memoryview` 物件。類位元組串物件可用於處理二進位" -"資料的各種運算；這些運算包括壓縮、儲存至二進位檔案和透過 socket（插座）發送。" - -#: ../../glossary.rst:220 -msgid "" -"Some operations need the binary data to be mutable. The documentation often " -"refers to these as \"read-write bytes-like objects\". Example mutable " -"buffer objects include :class:`bytearray` and a :class:`memoryview` of a :" -"class:`bytearray`. Other operations require the binary data to be stored in " -"immutable objects (\"read-only bytes-like objects\"); examples of these " -"include :class:`bytes` and a :class:`memoryview` of a :class:`bytes` object." -msgstr "" -"有些運算需要二進位資料是可變的。說明文件通常會將這些物件稱為「可讀寫的類位元" -"組串物件」。可變緩衝區的物件包括 :class:`bytearray`，以及 :class:`bytearray` " -"的 :class:`memoryview`。其他的運算需要讓二進位資料被儲存在不可變物件（「唯讀" -"的類位元組串物件」）中；這些物件包括 :class:`bytes`，以及 :class:`bytes` 物件" -"的 :class:`memoryview`。" - -#: ../../glossary.rst:228 -msgid "bytecode" -msgstr "bytecode（位元組碼）" - -#: ../../glossary.rst:230 -msgid "" -"Python source code is compiled into bytecode, the internal representation of " -"a Python program in the CPython interpreter. The bytecode is also cached in " -"``.pyc`` files so that executing the same file is faster the second time " -"(recompilation from source to bytecode can be avoided). This \"intermediate " -"language\" is said to run on a :term:`virtual machine` that executes the " -"machine code corresponding to each bytecode. Do note that bytecodes are not " -"expected to work between different Python virtual machines, nor to be stable " -"between Python releases." -msgstr "" -"Python 的原始碼會被編譯成位元組碼，它是 Python 程式在 CPython 直譯器中的內部" -"表示法。該位元組碼也會被暫存在 ``.pyc`` 檔案中，以便第二次執行同一個檔案時能" -"夠更快速（可以不用從原始碼重新編譯為位元組碼）。這種「中間語言 (intermediate " -"language)」據說是運行在一個 :term:`virtual machine`\\ （虛擬機器）上，該虛擬" -"機器會執行與每個位元組碼對應的機器碼 (machine code)。要注意的是，位元組碼理論" -"上是無法在不同的 Python 虛擬機器之間運作的，也不能在不同版本的 Python 之間保" -"持穩定。" - -#: ../../glossary.rst:240 -msgid "" -"A list of bytecode instructions can be found in the documentation for :ref:" -"`the dis module `." -msgstr "" -"位元組碼的指令列表可以在 :ref:`dis 模組 `\\ 的說明文件中找到。" - -#: ../../glossary.rst:242 -msgid "callable" -msgstr "callable（可呼叫物件）" - -#: ../../glossary.rst:244 -msgid "" -"A callable is an object that can be called, possibly with a set of arguments " -"(see :term:`argument`), with the following syntax::" -msgstr "" -"一個 callable 是可以被呼叫的物件，呼叫時可能以下列形式帶有一組引數（請見 :" -"term:`argument`）： ::" - -#: ../../glossary.rst:247 -msgid "callable(argument1, argument2, argumentN)" -msgstr "callable(argument1, argument2, argumentN)" - -#: ../../glossary.rst:249 -msgid "" -"A :term:`function`, and by extension a :term:`method`, is a callable. An " -"instance of a class that implements the :meth:`~object.__call__` method is " -"also a callable." -msgstr "" -"一個 :term:`function` 與其延伸的 :term:`method` 都是 callable。一個有實作 :" -"meth:`~object.__call__` 方法的 class 之實例也是個 callable。" - -#: ../../glossary.rst:252 -msgid "callback" -msgstr "callback（回呼）" - -#: ../../glossary.rst:254 -msgid "" -"A subroutine function which is passed as an argument to be executed at some " -"point in the future." -msgstr "" -"作為引數被傳遞的一個副程式 (subroutine) 函式，會在未來的某個時間點被執行。" - -#: ../../glossary.rst:256 -msgid "class" -msgstr "class（類別）" - -#: ../../glossary.rst:258 -msgid "" -"A template for creating user-defined objects. Class definitions normally " -"contain method definitions which operate on instances of the class." -msgstr "" -"一個用於建立使用者定義物件的模板。Class 的定義通常會包含 method 的定義，這些 " -"method 可以在 class 的實例上進行操作。" - -#: ../../glossary.rst:261 -msgid "class variable" -msgstr "class variable（類別變數）" - -#: ../../glossary.rst:263 -msgid "" -"A variable defined in a class and intended to be modified only at class " -"level (i.e., not in an instance of the class)." -msgstr "" -"一個在 class 中被定義，且應該只能在 class 層次（意即不是在 class 的實例中）被" -"修改的變數。" - -#: ../../glossary.rst:265 -msgid "closure variable" -msgstr "closure variable（閉包變數）" - -#: ../../glossary.rst:267 -msgid "" -"A :term:`free variable` referenced from a :term:`nested scope` that is " -"defined in an outer scope rather than being resolved at runtime from the " -"globals or builtin namespaces. May be explicitly defined with the :keyword:" -"`nonlocal` keyword to allow write access, or implicitly defined if the " -"variable is only being read." -msgstr "" -"從外部作用域中定義且從\\ :term:`巢狀作用域 `\\ 參照的\\ :term:`" -"自由變數 `，不是於 runtime 從全域或內建命名空間解析。可以使" -"用 :keyword:`nonlocal` 關鍵字明確定義以允許寫入存取，或者如果僅需讀取變數則隱" -"式定義即可。" - -#: ../../glossary.rst:272 -msgid "" -"For example, in the ``inner`` function in the following code, both ``x`` and " -"``print`` are :term:`free variables `, but only ``x`` is a " -"*closure variable*::" -msgstr "" -"例如在下面程式碼中的 ``inner`` 函式中，``x`` 和 ``print`` 都是\\ :term:`自由" -"變數 `，但只有 ``x`` 是\\ *閉包變數*： ::" - -#: ../../glossary.rst:275 -msgid "" -"def outer():\n" -" x = 0\n" -" def inner():\n" -" nonlocal x\n" -" x += 1\n" -" print(x)\n" -" return inner" -msgstr "" -"def outer():\n" -" x = 0\n" -" def inner():\n" -" nonlocal x\n" -" x += 1\n" -" print(x)\n" -" return inner" - -#: ../../glossary.rst:283 -msgid "" -"Due to the :attr:`codeobject.co_freevars` attribute (which, despite its " -"name, only includes the names of closure variables rather than listing all " -"referenced free variables), the more general :term:`free variable` term is " -"sometimes used even when the intended meaning is to refer specifically to " -"closure variables." -msgstr "" -"由於 :attr:`codeobject.co_freevars` 屬性（儘管名稱如此，但它僅包含閉包變數的" -"名稱，而不是列出所有參照的自由變數），當預期含義是特指閉包變數時，有時候甚至" -"也會使用更通用的\\ :term:`自由變數 `\\ 一詞。" - -#: ../../glossary.rst:287 -msgid "complex number" -msgstr "complex number（複數）" - -#: ../../glossary.rst:289 -msgid "" -"An extension of the familiar real number system in which all numbers are " -"expressed as a sum of a real part and an imaginary part. Imaginary numbers " -"are real multiples of the imaginary unit (the square root of ``-1``), often " -"written ``i`` in mathematics or ``j`` in engineering. Python has built-in " -"support for complex numbers, which are written with this latter notation; " -"the imaginary part is written with a ``j`` suffix, e.g., ``3+1j``. To get " -"access to complex equivalents of the :mod:`math` module, use :mod:`cmath`. " -"Use of complex numbers is a fairly advanced mathematical feature. If you're " -"not aware of a need for them, it's almost certain you can safely ignore them." -msgstr "" -"一個我們熟悉的實數系統的擴充，在此所有數字都會被表示為一個實部和一個虛部之" -"和。虛數就是虛數單位（``-1`` 的平方根）的實數倍，此單位通常在數學中被寫為 " -"``i``，在工程學中被寫為 ``j``。Python 內建了對複數的支援，它是用後者的記法來" -"表示複數；虛部會帶著一個後綴的 ``j`` 被編寫，例如 ``3+1j``。若要將 :mod:" -"`math` 模組內的工具等效地用於複數，請使用 :mod:`cmath` 模組。複數的使用是一個" -"相當進階的數學功能。如果你沒有察覺到對它們的需求，那麼幾乎能確定你可以安全地" -"忽略它們。" - -#: ../../glossary.rst:299 -msgid "concurrency" -msgstr "concurrency（並行性）" - -#: ../../glossary.rst:301 -msgid "" -"The ability of a computer program to perform multiple tasks at the same " -"time. Python provides libraries for writing programs that make use of " -"different forms of concurrency. :mod:`asyncio` is a library for dealing " -"with asynchronous tasks and coroutines. :mod:`threading` provides access to " -"operating system threads and :mod:`multiprocessing` to operating system " -"processes. Multi-core processors can execute threads and processes on " -"different CPU cores at the same time (see :term:`parallelism`)." -msgstr "" - -#: ../../glossary.rst:309 -msgid "concurrent modification" -msgstr "" - -#: ../../glossary.rst:311 -msgid "" -"When multiple threads modify shared data at the same time. Concurrent " -"modification without proper synchronization can cause :term:`race conditions " -"`, and might also trigger a :term:`data race `, " -"data corruption, or both." -msgstr "" - -#: ../../glossary.rst:315 -msgid "context" -msgstr "context（情境）" - -#: ../../glossary.rst:317 -msgid "" -"This term has different meanings depending on where and how it is used. Some " -"common meanings:" -msgstr "" - -#: ../../glossary.rst:320 -msgid "" -"The temporary state or environment established by a :term:`context manager` " -"via a :keyword:`with` statement." -msgstr "" - -#: ../../glossary.rst:322 -msgid "" -"The collection of key­value bindings associated with a particular :class:" -"`contextvars.Context` object and accessed via :class:`~contextvars." -"ContextVar` objects. Also see :term:`context variable`." -msgstr "" - -#: ../../glossary.rst:326 -msgid "" -"A :class:`contextvars.Context` object. Also see :term:`current context`." -msgstr "" -"一個 :class:`contextvars.Context` 物件。另請參閱 :term:`current context`。" - -#: ../../glossary.rst:328 -msgid "context management protocol" -msgstr "context management protocol（情境管理協定）" - -#: ../../glossary.rst:330 -msgid "" -"The :meth:`~object.__enter__` and :meth:`~object.__exit__` methods called by " -"the :keyword:`with` statement. See :pep:`343`." -msgstr "" -"由 :keyword:`with` 陳述式所呼叫的 :meth:`~object.__enter__` 和 :meth:" -"`~object.__exit__` 方法。另請參閱 :pep:`343`。" - -#: ../../glossary.rst:332 -msgid "context manager" -msgstr "context manager（情境管理器）" - -#: ../../glossary.rst:334 -msgid "" -"An object which implements the :term:`context management protocol` and " -"controls the environment seen in a :keyword:`with` statement. See :pep:" -"`343`." -msgstr "" - -#: ../../glossary.rst:337 -msgid "context variable" -msgstr "context variable（情境變數）" - -#: ../../glossary.rst:339 -msgid "" -"A variable whose value depends on which context is the :term:`current " -"context`. Values are accessed via :class:`contextvars.ContextVar` objects. " -"Context variables are primarily used to isolate state between concurrent " -"asynchronous tasks." -msgstr "" - -#: ../../glossary.rst:343 -msgid "contiguous" -msgstr "contiguous（連續的）" - -#: ../../glossary.rst:347 -msgid "" -"A buffer is considered contiguous exactly if it is either *C-contiguous* or " -"*Fortran contiguous*. Zero-dimensional buffers are C and Fortran " -"contiguous. In one-dimensional arrays, the items must be laid out in memory " -"next to each other, in order of increasing indexes starting from zero. In " -"multidimensional C-contiguous arrays, the last index varies the fastest when " -"visiting items in order of memory address. However, in Fortran contiguous " -"arrays, the first index varies the fastest." -msgstr "" -"如果一個緩衝區是 *C-contiguous* 或是 *Fortran contiguous*，則它會確切地被視為" -"是連續的。零維 (zero-dimensional) 的緩衝區都是 C 及 Fortran contiguous。在一" -"維 (one-dimensional) 陣列中，各項目必須在記憶體中彼此相鄰地排列，而其索引順序" -"是從零開始遞增。在多維的 (multidimensional) C-contiguous 陣列中，按記憶體位址" -"的順序瀏覽各個項目時，最後一個索引的變化最快。然而，在 Fortran contiguous 陣" -"列中，第一個索引的變化最快。" - -#: ../../glossary.rst:355 -msgid "coroutine" -msgstr "coroutine（協程）" - -#: ../../glossary.rst:357 -msgid "" -"Coroutines are a more generalized form of subroutines. Subroutines are " -"entered at one point and exited at another point. Coroutines can be " -"entered, exited, and resumed at many different points. They can be " -"implemented with the :keyword:`async def` statement. See also :pep:`492`." -msgstr "" -"協程是副程式 (subroutine) 的一種更為廣義的形式。副程式是在某個時間點被進入並" -"在另一個時間點被退出。協程可以在許多不同的時間點被進入、退出和回復。它們能夠" -"以 :keyword:`async def` 陳述式被實作。另請參閱 :pep:`492`。" - -#: ../../glossary.rst:362 -msgid "coroutine function" -msgstr "coroutine function（協程函式）" - -#: ../../glossary.rst:364 -msgid "" -"A function which returns a :term:`coroutine` object. A coroutine function " -"may be defined with the :keyword:`async def` statement, and may contain :" -"keyword:`await`, :keyword:`async for`, and :keyword:`async with` keywords. " -"These were introduced by :pep:`492`." -msgstr "" -"一個回傳 :term:`coroutine`\\ （協程）物件的函式。一個協程函式能以 :keyword:" -"`async def` 陳述式被定義，並可能會包含 :keyword:`await`、:keyword:`async " -"for` 和 :keyword:`async with` 關鍵字。這些關鍵字由 :pep:`492` 引入。" - -#: ../../glossary.rst:369 -msgid "CPython" -msgstr "CPython" - -#: ../../glossary.rst:371 -msgid "" -"The canonical implementation of the Python programming language, as " -"distributed on `python.org `_. The term \"CPython\" " -"is used when necessary to distinguish this implementation from others such " -"as Jython or IronPython." -msgstr "" -"Python 程式語言的標準實作 (canonical implementation)，被發布在 `python.org " -"`_ 上。「CPython」這個術語在必要時被使用，以區分此實" -"作與其它語言的實作，例如 Jython 或 IronPython。" - -#: ../../glossary.rst:375 -msgid "current context" -msgstr "" - -#: ../../glossary.rst:377 -msgid "" -"The :term:`context` (:class:`contextvars.Context` object) that is currently " -"used by :class:`~contextvars.ContextVar` objects to access (get or set) the " -"values of :term:`context variables `. Each thread has its " -"own current context. Frameworks for executing asynchronous tasks (see :mod:" -"`asyncio`) associate each task with a context which becomes the current " -"context whenever the task starts or resumes execution." -msgstr "" - -#: ../../glossary.rst:383 -msgid "cyclic isolate" -msgstr "" - -#: ../../glossary.rst:385 -msgid "" -"A subgroup of one or more objects that reference each other in a reference " -"cycle, but are not referenced by objects outside the group. The goal of " -"the :term:`cyclic garbage collector ` is to identify " -"these groups and break the reference cycles so that the memory can be " -"reclaimed." -msgstr "" - -#: ../../glossary.rst:389 -msgid "data race" -msgstr "" - -#: ../../glossary.rst:391 -msgid "" -"A situation where multiple threads access the same memory location " -"concurrently, at least one of the accesses is a write, and the threads do " -"not use any synchronization to control their access. Data races lead to :" -"term:`non-deterministic` behavior and can cause data corruption. Proper use " -"of :term:`locks ` and other :term:`synchronization primitives " -"` prevents data races. Note that data races can " -"only happen in native code, but that :term:`native code` might be exposed in " -"a Python API. See also :term:`race condition` and :term:`thread-safe`." -msgstr "" - -#: ../../glossary.rst:400 -msgid "deadlock" -msgstr "" - -#: ../../glossary.rst:402 -msgid "" -"A situation in which two or more tasks (threads, processes, or coroutines) " -"wait indefinitely for each other to release resources or complete actions, " -"preventing any from making progress. For example, if thread A holds lock 1 " -"and waits for lock 2, while thread B holds lock 2 and waits for lock 1, both " -"threads will wait indefinitely. In Python this often arises from acquiring " -"multiple locks in conflicting orders or from circular join/await " -"dependencies. Deadlocks can be avoided by always acquiring multiple :term:" -"`locks ` in a consistent order. See also :term:`lock` and :term:" -"`reentrant`." -msgstr "" - -#: ../../glossary.rst:411 -msgid "decorator" -msgstr "decorator（裝飾器）" - -#: ../../glossary.rst:413 -msgid "" -"A function returning another function, usually applied as a function " -"transformation using the ``@wrapper`` syntax. Common examples for " -"decorators are :func:`classmethod` and :func:`staticmethod`." -msgstr "" -"一個函式，它會回傳另一個函式，通常它會使用 ``@wrapper`` 語法，被應用為一種函" -"式的變換 (function transformation)。裝飾器的常見範例是 :func:`classmethod` " -"和 :func:`staticmethod`。" - -#: ../../glossary.rst:417 -msgid "" -"The decorator syntax is merely syntactic sugar, the following two function " -"definitions are semantically equivalent::" -msgstr "裝飾器語法只是語法糖。以下兩個函式定義在語義上是等效的： ::" - -#: ../../glossary.rst:420 -msgid "" -"def f(arg):\n" -" ...\n" -"f = staticmethod(f)\n" -"\n" -"@staticmethod\n" -"def f(arg):\n" -" ..." -msgstr "" -"def f(arg):\n" -" ...\n" -"f = staticmethod(f)\n" -"\n" -"@staticmethod\n" -"def f(arg):\n" -" ..." - -#: ../../glossary.rst:428 -msgid "" -"The same concept exists for classes, but is less commonly used there. See " -"the documentation for :ref:`function definitions ` and :ref:`class " -"definitions ` for more about decorators." -msgstr "" -"Class 也存在相同的概念，但在那裡比較不常用。關於裝飾器的更多內容，請參閱\\ :" -"ref:`函式定義 `\\ 和 :ref:`class 定義 `\\ 的說明文件。" - -#: ../../glossary.rst:431 -msgid "descriptor" -msgstr "descriptor（描述器）" - -#: ../../glossary.rst:433 -msgid "" -"Any object which defines the methods :meth:`~object.__get__`, :meth:`~object." -"__set__`, or :meth:`~object.__delete__`. When a class attribute is a " -"descriptor, its special binding behavior is triggered upon attribute " -"lookup. Normally, using *a.b* to get, set or delete an attribute looks up " -"the object named *b* in the class dictionary for *a*, but if *b* is a " -"descriptor, the respective descriptor method gets called. Understanding " -"descriptors is a key to a deep understanding of Python because they are the " -"basis for many features including functions, methods, properties, class " -"methods, static methods, and reference to super classes." -msgstr "" -"任何定義了 :meth:`~object.__get__`、:meth:`~object.__set__` 或 :meth:" -"`~object.__delete__` method 的物件。當一個 class 屬性是一個描述器時，它的特殊" -"連結行為會在屬性查找時被觸發。通常，使用 *a.b* 來取得、設定或刪除某個屬性時，" -"會在 *a* 的 class 字典中查找名稱為 *b* 的物件，但如果 *b* 是一個描述器，則相" -"對應的描述器 method 會被呼叫。對描述器的理解是深入理解 Python 的關鍵，因為它" -"們是許多功能的基礎，這些功能包括函式、method、屬性 (property)、class method、" -"靜態 method，以及對 super class（父類別）的參照。" - -#: ../../glossary.rst:444 -msgid "" -"For more information about descriptors' methods, see :ref:`descriptors` or " -"the :ref:`Descriptor How To Guide `." -msgstr "" -"關於描述器 method 的更多資訊，請參閱\\ :ref:`descriptors`\\ 或\\ :ref:`描述器" -"使用指南 `。" - -#: ../../glossary.rst:446 -msgid "dictionary" -msgstr "dictionary（字典）" - -#: ../../glossary.rst:448 -msgid "" -"An associative array, where arbitrary keys are mapped to values. The keys " -"can be any object with :meth:`~object.__hash__` and :meth:`~object.__eq__` " -"methods. Called a hash in Perl." -msgstr "" -"一個關聯陣列 (associative array)，其中任意的鍵會被對映到值。鍵可以是任何帶" -"有 :meth:`~object.__hash__` 和 :meth:`~object.__eq__` method 的物件。在 Perl " -"中被稱為雜湊 (hash)。" - -#: ../../glossary.rst:452 -msgid "dictionary comprehension" -msgstr "dictionary comprehension（字典綜合運算）" - -#: ../../glossary.rst:454 -msgid "" -"A compact way to process all or part of the elements in an iterable and " -"return a dictionary with the results. ``results = {n: n ** 2 for n in " -"range(10)}`` generates a dictionary containing key ``n`` mapped to value ``n " -"** 2``. See :ref:`comprehensions`." -msgstr "" -"一種緊密的方法，用來處理一個可疊代物件中的全部或部分元素，並將處理結果以一個" -"字典回傳。``results = {n: n ** 2 for n in range(10)}`` 會產生一個字典，它包含" -"了鍵 ``n`` 對映到值 ``n ** 2``。請參閱\\ :ref:`comprehensions`。" - -#: ../../glossary.rst:458 -msgid "dictionary view" -msgstr "dictionary view（字典檢視）" - -#: ../../glossary.rst:460 -msgid "" -"The objects returned from :meth:`dict.keys`, :meth:`dict.values`, and :meth:" -"`dict.items` are called dictionary views. They provide a dynamic view on the " -"dictionary’s entries, which means that when the dictionary changes, the view " -"reflects these changes. To force the dictionary view to become a full list " -"use ``list(dictview)``. See :ref:`dict-views`." -msgstr "" -"從 :meth:`dict.keys`、:meth:`dict.values` 及 :meth:`dict.items` 回傳的物件被" -"稱為字典檢視。它們提供了字典中項目的動態檢視，這表示當字典有變動時，該檢視會" -"反映這些變動。若要強制將字典檢視轉為完整的 list（串列），須使用 " -"``list(dictview)``。請參閱\\ :ref:`dict-views`。" - -#: ../../glossary.rst:466 -msgid "docstring" -msgstr "docstring（說明字串）" - -#: ../../glossary.rst:468 -msgid "" -"A string literal which appears as the first expression in a class, function " -"or module. While ignored when the suite is executed, it is recognized by " -"the compiler and put into the :attr:`~definition.__doc__` attribute of the " -"enclosing class, function or module. Since it is available via " -"introspection, it is the canonical place for documentation of the object." -msgstr "" -"一個在 class、函式或模組中，作為第一個運算式出現的字串文本。雖然它在套件執行" -"時會被忽略，但它會被編譯器辨識，並被放入所屬 class、函式或模組的 :attr:" -"`~definition.__doc__` 屬性中。由於說明字串可以透過內省 (introspection) 來瀏" -"覽，因此它是物件的說明文件存放的標準位置。" - -#: ../../glossary.rst:474 -msgid "duck-typing" -msgstr "duck-typing（鴨子型別）" - -#: ../../glossary.rst:476 -msgid "" -"A programming style which does not look at an object's type to determine if " -"it has the right interface; instead, the method or attribute is simply " -"called or used (\"If it looks like a duck and quacks like a duck, it must be " -"a duck.\") By emphasizing interfaces rather than specific types, well-" -"designed code improves its flexibility by allowing polymorphic " -"substitution. Duck-typing avoids tests using :func:`type` or :func:" -"`isinstance`. (Note, however, that duck-typing can be complemented with :" -"term:`abstract base classes `.) Instead, it typically " -"employs :func:`hasattr` tests or :term:`EAFP` programming." -msgstr "" -"一種程式設計風格，它不是藉由檢查一個物件的型別來確定它是否具有正確的介面；取" -"而代之的是，method 或屬性會單純地被呼叫或使用。（「如果它看起來像一隻鴨子而且" -"叫起來像一隻鴨子，那麼它一定是一隻鴨子。」）因為強調介面而非特定型別，精心設" -"計的程式碼能讓多形替代 (polymorphic substitution) 來增進它的靈活性。鴨子型別" -"要避免使用 :func:`type` 或 :func:`isinstance` 進行測試。（但是請注意，鴨子型" -"別可以用\\ :term:`抽象基底類別 (abstract base class) ` " -"來補充。）然而，它通常會採用 :func:`hasattr` 測試，或是 :term:`EAFP` 程式設計" -"風格。" - -#: ../../glossary.rst:485 -msgid "dunder" -msgstr "dunder（雙底線）" - -#: ../../glossary.rst:487 -msgid "" -"An informal short-hand for \"double underscore\", used when talking about a :" -"term:`special method`. For example, ``__init__`` is often pronounced " -"\"dunder init\"." -msgstr "" -"一個非正式的縮寫，代表「雙底線 (double underscore)」，當談論到\\ :term:`特殊" -"方法 `\\ 時使用。例如，``__init__`` 通常被叫做 \"dunder " -"init\"。" - -#: ../../glossary.rst:490 -msgid "EAFP" -msgstr "EAFP" - -#: ../../glossary.rst:492 -msgid "" -"Easier to ask for forgiveness than permission. This common Python coding " -"style assumes the existence of valid keys or attributes and catches " -"exceptions if the assumption proves false. This clean and fast style is " -"characterized by the presence of many :keyword:`try` and :keyword:`except` " -"statements. The technique contrasts with the :term:`LBYL` style common to " -"many other languages such as C." -msgstr "" -"Easier to ask for forgiveness than permission.（請求寬恕比請求許可更容易。）" -"這種常見的 Python 編碼風格會先假設有效的鍵或屬性的存在，並在該假設被推翻時再" -"捕獲例外。這種乾淨且快速的風格，其特色是存在許多的 :keyword:`try` 和 :" -"keyword:`except` 陳述式。該技術與許多其他語言（例如 C）常見的 :term:`LBYL` 風" -"格形成了對比。" - -#: ../../glossary.rst:498 -msgid "evaluate function" -msgstr "evaluate function（求值函式）" - -#: ../../glossary.rst:500 -msgid "" -"A function that can be called to evaluate a lazily evaluated attribute of an " -"object, such as the value of type aliases created with the :keyword:`type` " -"statement." -msgstr "" - -#: ../../glossary.rst:503 -msgid "expression" -msgstr "expression（運算式）" - -#: ../../glossary.rst:505 -msgid "" -"A piece of syntax which can be evaluated to some value. In other words, an " -"expression is an accumulation of expression elements like literals, names, " -"attribute access, operators or function calls which all return a value. In " -"contrast to many other languages, not all language constructs are " -"expressions. There are also :term:`statement`\\s which cannot be used as " -"expressions, such as :keyword:`while`. Assignments are also statements, not " -"expressions." -msgstr "" -"一段可以被評估並求值的語法。換句話說，一個運算式就是文字、名稱、屬性存取、運" -"算子或函式呼叫等運算式元件的累積，而這些元件都能回傳一個值。與許多其他語言不" -"同的是，並非所有的 Python 語言構造都是運算式。另外有一些 :term:`statement`\\ " -"（陳述式）不能被用作運算式，例如 :keyword:`while`。賦值 (assignment) 也是陳述" -"式，而不是運算式。" - -#: ../../glossary.rst:512 -msgid "extension module" -msgstr "extension module（擴充模組）" - -#: ../../glossary.rst:514 -msgid "" -"A module written in C or C++, using Python's C API to interact with the core " -"and with user code." -msgstr "" -"一個以 C 或 C++ 編寫的模組，它使用 Python 的 C API 來與核心及使用者程式碼進行" -"互動。" - -#: ../../glossary.rst:516 -msgid "f-string" -msgstr "f-string（f 字串）" - -#: ../../glossary.rst:517 -msgid "f-strings" -msgstr "f-strings（f 字串）" - -#: ../../glossary.rst:519 -msgid "" -"String literals prefixed with ``f`` or ``F`` are commonly called \"f-" -"strings\" which is short for :ref:`formatted string literals `. " -"See also :pep:`498`." -msgstr "" -"以 ``f`` 或 ``F`` 為前綴的字串文本通常被稱為「f 字串」，它是\\ :ref:`格式化的" -"字串文本 `\\ 的縮寫。另請參閱 :pep:`498`。" - -#: ../../glossary.rst:522 -msgid "file object" -msgstr "file object（檔案物件）" - -#: ../../glossary.rst:524 -msgid "" -"An object exposing a file-oriented API (with methods such as :meth:`!read` " -"or :meth:`!write`) to an underlying resource. Depending on the way it was " -"created, a file object can mediate access to a real on-disk file or to " -"another type of storage or communication device (for example standard input/" -"output, in-memory buffers, sockets, pipes, etc.). File objects are also " -"called :dfn:`file-like objects` or :dfn:`streams`." -msgstr "" -"一個讓使用者透過檔案導向 (file-oriented) API（如 :meth:`!read` 或 :meth:`!" -"write` 等 method）來操作底層資源的物件。根據檔案物件被建立的方式，它能夠協調" -"對真實磁碟檔案或是其他類型的儲存器或通訊裝置（例如標準輸入／輸出、記憶體內緩" -"衝區、socket（插座）、管線 (pipe) 等）的存取。檔案物件也被稱為\\ :dfn:`類檔案" -"物件 (file-like object)` 或\\ :dfn:`串流 (stream)`。" - -#: ../../glossary.rst:532 -msgid "" -"There are actually three categories of file objects: raw :term:`binary files " -"`, buffered :term:`binary files ` and :term:`text " -"files `. Their interfaces are defined in the :mod:`io` module. " -"The canonical way to create a file object is by using the :func:`open` " -"function." -msgstr "" -"實際上，有三種檔案物件：原始的\\ :term:`二進位檔案 `、緩衝的\\ :" -"term:`二進位檔案 `\\ 和\\ :term:`文字檔案 `。它們的介" -"面在 :mod:`io` 模組中被定義。建立檔案物件的標準方法是使用 :func:`open` 函式。" - -#: ../../glossary.rst:537 -msgid "file-like object" -msgstr "file-like object（類檔案物件）" - -#: ../../glossary.rst:539 -msgid "A synonym for :term:`file object`." -msgstr ":term:`file object`\\ （檔案物件）的同義字。" - -#: ../../glossary.rst:540 -msgid "filesystem encoding and error handler" -msgstr "filesystem encoding and error handler（檔案系統編碼和錯誤處理函式）" - -#: ../../glossary.rst:542 -msgid "" -"Encoding and error handler used by Python to decode bytes from the operating " -"system and encode Unicode to the operating system." -msgstr "" -"Python 所使用的一種編碼和錯誤處理函式，用來解碼來自作業系統的位元組，以及將 " -"Unicode 編碼到作業系統。" - -#: ../../glossary.rst:545 -msgid "" -"The filesystem encoding must guarantee to successfully decode all bytes " -"below 128. If the file system encoding fails to provide this guarantee, API " -"functions can raise :exc:`UnicodeError`." -msgstr "" -"檔案系統編碼必須保證能成功解碼所有小於 128 的位元組。如果檔案系統編碼無法提供" -"此保證，則 API 函式會引發 :exc:`UnicodeError`。" - -#: ../../glossary.rst:549 -msgid "" -"The :func:`sys.getfilesystemencoding` and :func:`sys." -"getfilesystemencodeerrors` functions can be used to get the filesystem " -"encoding and error handler." -msgstr "" -":func:`sys.getfilesystemencoding` 和 :func:`sys.getfilesystemencodeerrors` 函" -"式可用於取得檔案系統編碼和錯誤處理函式。" - -#: ../../glossary.rst:553 -msgid "" -"The :term:`filesystem encoding and error handler` are configured at Python " -"startup by the :c:func:`PyConfig_Read` function: see :c:member:`~PyConfig." -"filesystem_encoding` and :c:member:`~PyConfig.filesystem_errors` members of :" -"c:type:`PyConfig`." -msgstr "" -":term:`filesystem encoding and error handler`\\ （檔案系統編碼和錯誤處理函" -"式）會在 Python 啟動時由 :c:func:`PyConfig_Read` 函式來配置：請參閱 :c:" -"member:`~PyConfig.filesystem_encoding`，以及 :c:type:`PyConfig` 的成員 :c:" -"member:`~PyConfig.filesystem_errors`。" - -#: ../../glossary.rst:558 -msgid "See also the :term:`locale encoding`." -msgstr "另請參閱 :term:`locale encoding`\\ （區域編碼）。" - -#: ../../glossary.rst:559 -msgid "finder" -msgstr "finder（尋檢器）" - -#: ../../glossary.rst:561 -msgid "" -"An object that tries to find the :term:`loader` for a module that is being " -"imported." -msgstr "" -"一個物件，它會嘗試為正在被 import 的模組尋找 :term:`loader`\\ （載入器）。" - -#: ../../glossary.rst:564 -msgid "" -"There are two types of finder: :term:`meta path finders ` " -"for use with :data:`sys.meta_path`, and :term:`path entry finders ` for use with :data:`sys.path_hooks`." -msgstr "" -"有兩種類型的尋檢器：:term:`元路徑尋檢器 (meta path finder) ` 會使用 :data:`sys.meta_path`，而\\ :term:`路徑項目尋檢器 (path " -"entry finder) ` 會使用 :data:`sys.path_hooks`。" - -#: ../../glossary.rst:568 -msgid "" -"See :ref:`finders-and-loaders` and :mod:`importlib` for much more detail." -msgstr "請參閱 :ref:`finders-and-loaders` 和 :mod:`importlib` 以了解更多細節。" - -#: ../../glossary.rst:569 -msgid "floor division" -msgstr "floor division（向下取整除法）" - -#: ../../glossary.rst:571 -msgid "" -"Mathematical division that rounds down to nearest integer. The floor " -"division operator is ``//``. For example, the expression ``11 // 4`` " -"evaluates to ``2`` in contrast to the ``2.75`` returned by float true " -"division. Note that ``(-11) // 4`` is ``-3`` because that is ``-2.75`` " -"rounded *downward*. See :pep:`238`." -msgstr "" -"向下無條件捨去到最接近整數的數學除法。向下取整除法的運算子是 ``//``。例如，運" -"算式 ``11 // 4`` 的計算結果為 ``2``，與 float（浮點數）真除法所回傳的 " -"``2.75`` 不同。請注意，``(-11) // 4`` 的結果是 ``-3``，因為是 ``-2.75`` 被\\ " -"*向下*\\ 無條件捨去。請參閱 :pep:`238`。" - -#: ../../glossary.rst:576 -msgid "free threading" -msgstr "free threading（自由執行緒）" - -#: ../../glossary.rst:578 -msgid "" -"A threading model where multiple threads can run Python bytecode " -"simultaneously within the same interpreter. This is in contrast to the :" -"term:`global interpreter lock` which allows only one thread to execute " -"Python bytecode at a time. See :pep:`703`." -msgstr "" -"為一種執行緒模型，多個執行緒可以在同一直譯器中同時運行 Python 位元組碼。這與" -"\\ :term:`全域直譯器鎖 `\\ 形成對比，後者一次只允許" -"一個執行緒執行 Python 位元組碼。請參閱 :pep:`703`。" - -#: ../../glossary.rst:582 -msgid "free variable" -msgstr "free variable（自由變數）" - -#: ../../glossary.rst:584 -msgid "" -"Formally, as defined in the :ref:`language execution model `, a " -"free variable is any variable used in a namespace which is not a local " -"variable in that namespace. See :term:`closure variable` for an example. " -"Pragmatically, due to the name of the :attr:`codeobject.co_freevars` " -"attribute, the term is also sometimes used as a synonym for :term:`closure " -"variable`." -msgstr "" - -#: ../../glossary.rst:589 -msgid "function" -msgstr "function（函式）" - -#: ../../glossary.rst:591 -msgid "" -"A series of statements which returns some value to a caller. It can also be " -"passed zero or more :term:`arguments ` which may be used in the " -"execution of the body. See also :term:`parameter`, :term:`method`, and the :" -"ref:`function` section." -msgstr "" -"一連串的陳述式，它能夠向呼叫者回傳一些值。它也可以被傳遞零個或多個\\ :term:`" -"引數 `，這些引數可被使用於函式本體的執行。另請參閱 :term:" -"`parameter`\\ （參數）、:term:`method`\\ （方法），以及\\ :ref:`function`\\ " -"章節。" - -#: ../../glossary.rst:595 -msgid "function annotation" -msgstr "function annotation（函式註釋）" - -#: ../../glossary.rst:597 -msgid "An :term:`annotation` of a function parameter or return value." -msgstr "函式參數或回傳值的一個 :term:`annotation`\\ （註釋）。" - -#: ../../glossary.rst:599 -msgid "" -"Function annotations are usually used for :term:`type hints `: " -"for example, this function is expected to take two :class:`int` arguments " -"and is also expected to have an :class:`int` return value::" -msgstr "" -"函式註釋通常被使用於\\ :term:`型別提示 `：例如，這個函式預期會得到" -"兩個 :class:`int` 引數，並會有一個 :class:`int` 回傳值： ::" - -#: ../../glossary.rst:604 -msgid "" -"def sum_two_numbers(a: int, b: int) -> int:\n" -" return a + b" -msgstr "" -"def sum_two_numbers(a: int, b: int) -> int:\n" -" return a + b" - -#: ../../glossary.rst:607 -msgid "Function annotation syntax is explained in section :ref:`function`." -msgstr "函式註釋的語法在\\ :ref:`function`\\ 章節有詳細解釋。" - -#: ../../glossary.rst:609 -msgid "" -"See :term:`variable annotation` and :pep:`484`, which describe this " -"functionality. Also see :ref:`annotations-howto` for best practices on " -"working with annotations." -msgstr "" -"請參閱 :term:`variable annotation` 和 :pep:`484`，皆有此功能的描述。關於註釋" -"的最佳實踐方法，另請參閱 :ref:`annotations-howto`。" - -#: ../../glossary.rst:613 -msgid "__future__" -msgstr "__future__" - -#: ../../glossary.rst:615 -msgid "" -"A :ref:`future statement `, ``from __future__ import ``, " -"directs the compiler to compile the current module using syntax or semantics " -"that will become standard in a future release of Python. The :mod:" -"`__future__` module documents the possible values of *feature*. By " -"importing this module and evaluating its variables, you can see when a new " -"feature was first added to the language and when it will (or did) become the " -"default::" -msgstr "" -":ref:`future 陳述式 `：``from __future__ import ``，會指示編" -"譯器使用那些在 Python 未來的發布版本中將成為標準的語法或語義，來編譯目前的模" -"組。而 :mod:`__future__` 模組則記錄了 *feature（功能）*\\ 可能的值。透過 " -"import 此模組並對其變數求值，你可以看見一個新的功能是何時首次被新增到此語言" -"中，以及它何時將會（或已經）成為預設的功能： ::" - -#: ../../glossary.rst:623 -msgid "" -">>> import __future__\n" -">>> __future__.division\n" -"_Feature((2, 2, 0, 'alpha', 2), (3, 0, 0, 'alpha', 0), 8192)" -msgstr "" -">>> import __future__\n" -">>> __future__.division\n" -"_Feature((2, 2, 0, 'alpha', 2), (3, 0, 0, 'alpha', 0), 8192)" - -#: ../../glossary.rst:626 -msgid "garbage collection" -msgstr "garbage collection（垃圾回收）" - -#: ../../glossary.rst:628 -msgid "" -"The process of freeing memory when it is not used anymore. Python performs " -"garbage collection via reference counting and a cyclic garbage collector " -"that is able to detect and break reference cycles. The garbage collector " -"can be controlled using the :mod:`gc` module." -msgstr "" -"當記憶體不再被使用時，將其釋放的過程。Python 執行垃圾回收，是透過參照計數 " -"(reference counting)，以及一個能夠檢測和中斷參照循環 (reference cycle) 的循環" -"垃圾回收器 (cyclic garbage collector) 來完成。垃圾回收器可以使用 :mod:`gc` 模" -"組對其進行控制。" - -#: ../../glossary.rst:633 ../../glossary.rst:634 -msgid "generator" -msgstr "generator（產生器）" - -#: ../../glossary.rst:636 -msgid "" -"A function which returns a :term:`generator iterator`. It looks like a " -"normal function except that it contains :keyword:`yield` expressions for " -"producing a series of values usable in a for-loop or that can be retrieved " -"one at a time with the :func:`next` function." -msgstr "" -"一個會回傳 :term:`generator iterator`\\ （產生器疊代器）的函式。它看起來像一" -"個正常的函式，但不同的是它包含了 :keyword:`yield` 運算式，能產生一系列的值，" -"這些值可用於 for 迴圈，或是以 :func:`next` 函式，每次檢索其中的一個值。" - -#: ../../glossary.rst:641 -msgid "" -"Usually refers to a generator function, but may refer to a *generator " -"iterator* in some contexts. In cases where the intended meaning isn't " -"clear, using the full terms avoids ambiguity." -msgstr "" -"這個術語通常用來表示一個產生器函式，但在某些情境中，也可能是表示\\ *產生器疊" -"代器*。萬一想表達的意思不夠清楚，那就使用完整的術語，以避免歧義。" - -#: ../../glossary.rst:644 -msgid "generator iterator" -msgstr "generator iterator（產生器疊代器）" - -#: ../../glossary.rst:646 -msgid "An object created by a :term:`generator` function." -msgstr "一個由 :term:`generator`\\ （產生器）函式所建立的物件。" - -#: ../../glossary.rst:648 -msgid "" -"Each :keyword:`yield` temporarily suspends processing, remembering the " -"execution state (including local variables and pending try-statements). " -"When the *generator iterator* resumes, it picks up where it left off (in " -"contrast to functions which start fresh on every invocation)." -msgstr "" -"每個 :keyword:`yield` 會暫停處理程序，並記住執行狀態（包括區域變數及擱置中的 " -"try 陳述式）。當\\ *產生器疊代器*\\ 回復時，它會從停止的地方繼續執行（與那些" -"每次呼叫時都要重新開始的函式有所不同）。" - -#: ../../glossary.rst:654 ../../glossary.rst:655 -msgid "generator expression" -msgstr "generator expression（產生器運算式）" - -#: ../../glossary.rst:657 -msgid "" -"An :term:`expression` that returns an :term:`iterator`. It looks like a " -"normal expression followed by a :keyword:`!for` clause defining a loop " -"variable, range, and an optional :keyword:`!if` clause. The combined " -"expression generates values for an enclosing function::" -msgstr "" -"一個會回傳\\ :term:`疊代器 `\\ 的\\ :term:`運算式 `。它" -"看起來像一個正常的運算式，後面接著一個 :keyword:`!for` 子句，該子句定義了迴圈" -"變數、範圍以及一個選擇性的 :keyword:`!if` 子句。該組合運算式會為外層函式產生" -"多個值： ::" - -#: ../../glossary.rst:662 -msgid "" -">>> sum(i*i for i in range(10)) # sum of squares 0, 1, 4, ... 81\n" -"285" -msgstr "" -">>> sum(i*i for i in range(10)) # 平方之和 0, 1, 4, ... 81\n" -"285" - -#: ../../glossary.rst:664 -msgid "generic function" -msgstr "generic function（泛型函式）" - -#: ../../glossary.rst:666 -msgid "" -"A function composed of multiple functions implementing the same operation " -"for different types. Which implementation should be used during a call is " -"determined by the dispatch algorithm." -msgstr "" -"一個由多個函式組成的函式，該函式會對不同的型別實作相同的運算。呼叫期間應該使" -"用哪種實作，是由調度演算法 (dispatch algorithm) 來決定。" - -#: ../../glossary.rst:670 -msgid "" -"See also the :term:`single dispatch` glossary entry, the :func:`functools." -"singledispatch` decorator, and :pep:`443`." -msgstr "" -"另請參閱 :term:`single dispatch`\\ （單一調度）術語表條目、:func:`functools." -"singledispatch` 裝飾器和 :pep:`443`。" - -#: ../../glossary.rst:672 -msgid "generic type" -msgstr "generic type（泛型型別）" - -#: ../../glossary.rst:674 -msgid "" -"A :term:`type` that can be parameterized; typically a :ref:`container " -"class` such as :class:`list` or :class:`dict`. Used for :" -"term:`type hints ` and :term:`annotations `." -msgstr "" -"一個能夠被參數化 (parameterized) 的 :term:`type`\\ （型別）；通常是一個 :ref:" -"`容器型別 `，像是 :class:`list` 和 :class:`dict`。它被用於" -"\\ :term:`型別提示 `\\ 和\\ :term:`註釋 `。" - -#: ../../glossary.rst:679 -msgid "" -"For more details, see :ref:`generic alias types`, :pep:" -"`483`, :pep:`484`, :pep:`585`, and the :mod:`typing` module." -msgstr "" -"詳情請參閱\\ :ref:`泛型別名型別 `、:pep:`483`、:pep:" -"`484`、:pep:`585` 和 :mod:`typing` 模組。" - -#: ../../glossary.rst:681 -msgid "GIL" -msgstr "GIL" - -#: ../../glossary.rst:683 -msgid "See :term:`global interpreter lock`." -msgstr "請參閱 :term:`global interpreter lock`\\ （全域直譯器鎖）。" - -#: ../../glossary.rst:684 -msgid "global interpreter lock" -msgstr "global interpreter lock（全域直譯器鎖）" - -#: ../../glossary.rst:686 -msgid "" -"The mechanism used by the :term:`CPython` interpreter to assure that only " -"one thread executes Python :term:`bytecode` at a time. This simplifies the " -"CPython implementation by making the object model (including critical built-" -"in types such as :class:`dict`) implicitly safe against concurrent access. " -"Locking the entire interpreter makes it easier for the interpreter to be " -"multi-threaded, at the expense of much of the parallelism afforded by multi-" -"processor machines." -msgstr "" -":term:`CPython` 直譯器所使用的機制，用以確保每次都只有一個執行緒能執行 " -"Python 的 :term:`bytecode`\\ （位元組碼）。透過使物件模型（包括關鍵的內建型" -"別，如 :class:`dict`\\ ）自動地避免並行存取 (concurrent access) 的危險，此機" -"制可以簡化 CPython 的實作。鎖定整個直譯器，會使直譯器更容易成為多執行緒 " -"(multi-threaded)，但代價是會犧牲掉多處理器的機器能夠提供的一大部分平行性 " -"(parallelism)。" - -#: ../../glossary.rst:695 -msgid "" -"However, some extension modules, either standard or third-party, are " -"designed so as to release the GIL when doing computationally intensive tasks " -"such as compression or hashing. Also, the GIL is always released when doing " -"I/O." -msgstr "" -"然而，有些擴充模組，無論是標準的或是第三方的，它們被設計成在執行壓縮或雜湊等" -"計算密集 (computationally intensive) 的任務時，可以解除 GIL。另外，在執行 I/" -"O 時，GIL 總是會被解除。" - -#: ../../glossary.rst:700 -msgid "" -"As of Python 3.13, the GIL can be disabled using the :option:`--disable-gil` " -"build configuration. After building Python with this option, code must be " -"run with :option:`-X gil=0 <-X>` or after setting the :envvar:`PYTHON_GIL=0 " -"` environment variable. This feature enables improved " -"performance for multi-threaded applications and makes it easier to use multi-" -"core CPUs efficiently. For more details, see :pep:`703`." -msgstr "" -"從 Python 3.13 開始可以使用 :option:`--disable-gil` 建置設定來停用 GIL。使用" -"此選項建立 Python 後，必須使用 :option:`-X gil=0 <-X>` 來執行程式碼，或者設" -"定 :envvar:`PYTHON_GIL=0 ` 環境變數後再執行程式碼。此功能可以提高" -"多執行緒應用程式的效能，並使多核心 CPU 的高效使用變得更加容易。有關更多詳細資" -"訊，請參閱 :pep:`703`。" - -#: ../../glossary.rst:707 -msgid "" -"In prior versions of Python's C API, a function might declare that it " -"requires the GIL to be held in order to use it. This refers to having an :" -"term:`attached thread state`." -msgstr "" - -#: ../../glossary.rst:710 -msgid "global state" -msgstr "" - -#: ../../glossary.rst:712 -msgid "" -"Data that is accessible throughout a program, such as module-level " -"variables, class variables, or C static variables in :term:`extension " -"modules `. In multi-threaded programs, global state " -"shared between threads typically requires synchronization to avoid :term:" -"`race conditions ` and :term:`data races `." -msgstr "" - -#: ../../glossary.rst:718 -msgid "hash-based pyc" -msgstr "hash-based pyc（雜湊架構的 pyc）" - -#: ../../glossary.rst:720 -msgid "" -"A bytecode cache file that uses the hash rather than the last-modified time " -"of the corresponding source file to determine its validity. See :ref:`pyc-" -"invalidation`." -msgstr "" -"一個位元組碼 (bytecode) 暫存檔，它使用雜湊值而不是對應原始檔案的最後修改時" -"間，來確定其有效性。請參閱\\ :ref:`pyc-invalidation`。" - -#: ../../glossary.rst:723 -msgid "hashable" -msgstr "hashable（可雜湊的）" - -#: ../../glossary.rst:725 -msgid "" -"An object is *hashable* if it has a hash value which never changes during " -"its lifetime (it needs a :meth:`~object.__hash__` method), and can be " -"compared to other objects (it needs an :meth:`~object.__eq__` method). " -"Hashable objects which compare equal must have the same hash value." -msgstr "" -"如果一個物件有一個雜湊值，該值在其生命週期中永不改變（它需要一個 :meth:" -"`~object.__hash__` method），且可與其他物件互相比較（它需要一個 :meth:" -"`~object.__eq__` method），那麼它就是一個\\ *可雜湊*\\ 物件。比較結果為相等的" -"多個可雜湊物件，它們必須擁有相同的雜湊值。" - -#: ../../glossary.rst:731 -msgid "" -"Hashability makes an object usable as a dictionary key and a set member, " -"because these data structures use the hash value internally." -msgstr "" -"可雜湊性 (hashability) 使一個物件可用作 dictionary（字典）的鍵和 set（集合）" -"的成員，因為這些資料結構都在其內部使用了雜湊值。" - -#: ../../glossary.rst:734 -msgid "" -"Most of Python's immutable built-in objects are hashable; mutable containers " -"(such as lists or dictionaries) are not; immutable containers (such as " -"tuples and frozensets) are only hashable if their elements are hashable. " -"Objects which are instances of user-defined classes are hashable by " -"default. They all compare unequal (except with themselves), and their hash " -"value is derived from their :func:`id`." -msgstr "" -"大多數的 Python 不可變內建物件都是可雜湊的；可變的容器（例如 list 或 " -"dictionary）並不是；而不可變的容器（例如 tuple（元組）和 frozenset），只有當" -"它們的元素是可雜湊的，它們本身才是可雜湊的。若物件是使用者自定 class 的實例，" -"則這些物件會被預設為可雜湊的。它們在互相比較時都是不相等的（除非它們與自己比" -"較），而它們的雜湊值則是衍生自它們的 :func:`id`。" - -#: ../../glossary.rst:741 -msgid "IDLE" -msgstr "IDLE" - -#: ../../glossary.rst:743 -msgid "" -"An Integrated Development and Learning Environment for Python. :ref:`idle` " -"is a basic editor and interpreter environment which ships with the standard " -"distribution of Python." -msgstr "" -"Python 的 Integrated Development and Learning Environment（整合開發與學習環" -"境）。:ref:`idle` 是一個基本的編輯器和直譯器環境，它和 Python 的標準發行版本" -"一起被提供。" - -#: ../../glossary.rst:746 -msgid "immortal" -msgstr "immortal（不滅）" - -#: ../../glossary.rst:748 -msgid "" -"*Immortal objects* are a CPython implementation detail introduced in :pep:" -"`683`." -msgstr "*不滅物件 (Immortal objects)* 是 :pep:`683` 引入的 CPython 實作細節。" - -#: ../../glossary.rst:751 -msgid "" -"If an object is immortal, its :term:`reference count` is never modified, and " -"therefore it is never deallocated while the interpreter is running. For " -"example, :const:`True` and :const:`None` are immortal in CPython." -msgstr "" -"如果一個物件是不滅的，它的\\ :term:`參照計數 `\\ 永遠不會被" -"修改，因此在直譯器運行時它永遠不會被釋放。例如，:const:`True` 和 :const:" -"`None` 在 CPython 中是不滅的。" - -#: ../../glossary.rst:755 -msgid "" -"Immortal objects can be identified via :func:`sys._is_immortal`, or via :c:" -"func:`PyUnstable_IsImmortal` in the C API." -msgstr "" - -#: ../../glossary.rst:757 -msgid "immutable" -msgstr "immutable（不可變物件）" - -#: ../../glossary.rst:759 -msgid "" -"An object with a fixed value. Immutable objects include numbers, strings " -"and tuples. Such an object cannot be altered. A new object has to be " -"created if a different value has to be stored. They play an important role " -"in places where a constant hash value is needed, for example as a key in a " -"dictionary. Immutable objects are inherently :term:`thread-safe` because " -"their state cannot be modified after creation, eliminating concerns about " -"improperly synchronized :term:`concurrent modification`." -msgstr "" -"一個具有固定值的物件。不可變物件包括數字、字串和 tuple（元組）。這類物件是不" -"能被改變的。如果必須儲存一個不同的值，則需要建立一個新的物件。它們在需要恆" -"定雜湊值的地方扮演重要的角色，例如 dictionary 中的一個鍵。不可變物件本" -"質上是\\ :term:`執行緒安全的 `，因為它們的狀態在建立後無法被修改，" -"從而消除了對不當同步的\\ :term:`並行修改 `\\ 的疑慮。" - -#: ../../glossary.rst:766 -msgid "import path" -msgstr "import path（引入路徑）" - -#: ../../glossary.rst:768 -msgid "" -"A list of locations (or :term:`path entries `) that are searched " -"by the :term:`path based finder` for modules to import. During import, this " -"list of locations usually comes from :data:`sys.path`, but for subpackages " -"it may also come from the parent package's ``__path__`` attribute." -msgstr "" -"一個位置（或\\ :term:`路徑項目 `\\ ）的列表，而那些位置就是在 " -"import 模組時，會被 :term:`path based finder`\\ （基於路徑的尋檢器）搜尋模組" -"的位置。在 import 期間，此位置列表通常是來自 :data:`sys.path`，但對於子套件 " -"(subpackage) 而言，它也可能是來自父套件的 ``__path__`` 屬性。" - -#: ../../glossary.rst:773 -msgid "importing" -msgstr "importing（引入）" - -#: ../../glossary.rst:775 -msgid "" -"The process by which Python code in one module is made available to Python " -"code in another module." -msgstr "" -"一個過程。一個模組中的 Python 程式碼可以透過此過程，被另一個模組中的 Python " -"程式碼使用。" - -#: ../../glossary.rst:777 -msgid "importer" -msgstr "importer（引入器）" - -#: ../../glossary.rst:779 -msgid "" -"An object that both finds and loads a module; both a :term:`finder` and :" -"term:`loader` object." -msgstr "" -"一個能夠尋找及載入模組的物件；它既是 :term:`finder`\\ （尋檢器）也是 :term:" -"`loader`\\ （載入器）物件。" - -#: ../../glossary.rst:781 -msgid "interactive" -msgstr "interactive（互動的）" - -#: ../../glossary.rst:783 -msgid "" -"Python has an interactive interpreter which means you can enter statements " -"and expressions at the interpreter prompt, immediately execute them and see " -"their results. Just launch ``python`` with no arguments (possibly by " -"selecting it from your computer's main menu). It is a very powerful way to " -"test out new ideas or inspect modules and packages (remember ``help(x)``). " -"For more on interactive mode, see :ref:`tut-interac`." -msgstr "" -"Python 有一個互動式直譯器，這表示你可以在直譯器的提示字元輸入陳述式和運算式，" -"立即執行它們並且看到它們的結果。只要啟動 ``python``，不需要任何引數（可能藉由" -"從你的電腦的主選單選擇它）。這是測試新想法或檢查模組和包的非常強大的方法（請" -"記住help(x)）。更多互動式模式相關資訊請見 :ref:`tut-interac`。" - -#: ../../glossary.rst:790 -msgid "interpreted" -msgstr "interpreted（直譯的）" - -#: ../../glossary.rst:792 -msgid "" -"Python is an interpreted language, as opposed to a compiled one, though the " -"distinction can be blurry because of the presence of the bytecode compiler. " -"This means that source files can be run directly without explicitly creating " -"an executable which is then run. Interpreted languages typically have a " -"shorter development/debug cycle than compiled ones, though their programs " -"generally also run more slowly. See also :term:`interactive`." -msgstr "" -"Python 是一種直譯語言，而不是編譯語言，不過這個區分可能有些模糊，因為有位元組" -"碼 (bytecode) 編譯器的存在。這表示原始檔案可以直接被運行，而不需明確地建立另" -"一個執行檔，然後再執行它。直譯語言通常比編譯語言有更短的開發／除錯週期，不過" -"它們的程式通常也運行得較慢。另請參閱 :term:`interactive`\\ （互動的）。" - -#: ../../glossary.rst:799 -msgid "interpreter shutdown" -msgstr "interpreter shutdown（直譯器關閉）" - -#: ../../glossary.rst:801 -msgid "" -"When asked to shut down, the Python interpreter enters a special phase where " -"it gradually releases all allocated resources, such as modules and various " -"critical internal structures. It also makes several calls to the :term:" -"`garbage collector `. This can trigger the execution of " -"code in user-defined destructors or weakref callbacks. Code executed during " -"the shutdown phase can encounter various exceptions as the resources it " -"relies on may not function anymore (common examples are library modules or " -"the warnings machinery)." -msgstr "" -"當 Python 直譯器被要求關閉時，它會進入一個特殊階段，在此它逐漸釋放所有被配置" -"的資源，例如模組和各種關鍵內部結構。它也會多次呼叫\\ :term:`垃圾回收器 " -"(garbage collector) `。這能夠觸發使用者自定的解構函式 " -"(destructor) 或弱引用的回呼 (weakref callback)，並執行其中的程式碼。在關閉階" -"段被執行的程式碼會遇到各種例外，因為它所依賴的資源可能不再有作用了（常見的例" -"子是函式庫模組或是警告機制）。" - -#: ../../glossary.rst:810 -msgid "" -"The main reason for interpreter shutdown is that the ``__main__`` module or " -"the script being run has finished executing." -msgstr "" -"直譯器關閉的主要原因，是 ``__main__`` 模組或正被運行的腳本已經執行完成。" - -#: ../../glossary.rst:812 -msgid "iterable" -msgstr "iterable（可疊代物件）" - -#: ../../glossary.rst:814 -msgid "" -"An object capable of returning its members one at a time. Examples of " -"iterables include all sequence types (such as :class:`list`, :class:`str`, " -"and :class:`tuple`) and some non-sequence types like :class:`dict`, :term:" -"`file objects `, and objects of any classes you define with an :" -"meth:`~object.__iter__` method or with a :meth:`~object.__getitem__` method " -"that implements :term:`sequence` semantics." -msgstr "" -"一種能夠一次回傳一個其中成員的物件。可疊代物件的例子包括所有的序列型別（像" -"是 :class:`list`、:class:`str` 和 :class:`tuple`\\ ）和某些非序列型別，像是 :" -"class:`dict`、:term:`檔案物件 `，以及你所定義的任何 class 物件，" -"只要那些 class 有實作 :term:`sequence`\\ （序列）語意的 :meth:`~object." -"__iter__` 或是 :meth:`~object.__getitem__` method，該物件就是可疊代物件。" - -#: ../../glossary.rst:822 -msgid "" -"Iterables can be used in a :keyword:`for` loop and in many other places " -"where a sequence is needed (:func:`zip`, :func:`map`, ...). When an " -"iterable object is passed as an argument to the built-in function :func:" -"`iter`, it returns an iterator for the object. This iterator is good for " -"one pass over the set of values. When using iterables, it is usually not " -"necessary to call :func:`iter` or deal with iterator objects yourself. The :" -"keyword:`for` statement does that automatically for you, creating a " -"temporary unnamed variable to hold the iterator for the duration of the " -"loop. See also :term:`iterator`, :term:`sequence`, and :term:`generator`." -msgstr "" -"可疊代物件可用於 :keyword:`for` 迴圈和許多其他需要一個序列的地方 (:func:" -"`zip`、:func:`map`\\ ...)。當一個可疊代物件作為引數被傳遞給內建函式 :func:" -"`iter` 時，它會為該物件回傳一個疊代器。此疊代器適用於針對一組值進行一遍 (one " -"pass) 運算。使用疊代器時，通常不一定要呼叫 :func:`iter` 或自行處理疊代器物" -"件。:keyword:`for` 陳述式會自動地為你處理這些事，它會建立一個暫時性的未命名變" -"數，用於在迴圈期間保有該疊代器。另請參閱 :term:`iterator`\\ （疊代器）、:" -"term:`sequence`\\ （序列）和 :term:`generator`\\ （產生器）。" - -#: ../../glossary.rst:832 -msgid "iterator" -msgstr "iterator（疊代器）" - -#: ../../glossary.rst:834 -msgid "" -"An object representing a stream of data. Repeated calls to the iterator's :" -"meth:`~iterator.__next__` method (or passing it to the built-in function :" -"func:`next`) return successive items in the stream. When no more data are " -"available a :exc:`StopIteration` exception is raised instead. At this " -"point, the iterator object is exhausted and any further calls to its :meth:`!" -"__next__` method just raise :exc:`StopIteration` again. Iterators are " -"required to have an :meth:`~iterator.__iter__` method that returns the " -"iterator object itself so every iterator is also iterable and may be used in " -"most places where other iterables are accepted. One notable exception is " -"code which attempts multiple iteration passes. A container object (such as " -"a :class:`list`) produces a fresh new iterator each time you pass it to the :" -"func:`iter` function or use it in a :keyword:`for` loop. Attempting this " -"with an iterator will just return the same exhausted iterator object used in " -"the previous iteration pass, making it appear like an empty container." -msgstr "" -"一個表示資料流的物件。重複地呼叫疊代器的 :meth:`~iterator.__next__` method" -"（或是將它傳遞給內建函式 :func:`next`\\ ）會依序回傳資料流中的各項目。當不再" -"有資料時，則會引發 :exc:`StopIteration` 例外。此時，該疊代器物件已被用盡，而" -"任何對其 :meth:`!__next__` method 的進一步呼叫，都只會再次引發 :exc:" -"`StopIteration`。疊代器必須有一個 :meth:`~iterator.__iter__` method，它會回傳" -"疊代器物件本身，所以每個疊代器也都是可疊代物件，且可以用於大多數適用其他可疊" -"代物件的場合。一個明顯的例外，是嘗試多遍疊代 (multiple iteration passes) 的程" -"式碼。一個容器物件（像是 :class:`list`）在每次你將它傳遞給 :func:`iter` 函式" -"或在 :keyword:`for` 迴圈中使用它時，都會產生一個全新的疊代器。使用疊代器嘗試" -"此事（多遍疊代）時，只會回傳在前一遍疊代中被用過的、同一個已被用盡的疊代器物" -"件，使其看起來就像一個空的容器。" - -#: ../../glossary.rst:849 -msgid "More information can be found in :ref:`typeiter`." -msgstr "在\\ :ref:`typeiter`\\ 文中可以找到更多資訊。" - -#: ../../glossary.rst:853 -msgid "" -"CPython does not consistently apply the requirement that an iterator define :" -"meth:`~iterator.__iter__`. And also please note that :term:`free-threaded " -"` CPython does not guarantee :term:`thread-safe` behavior of " -"iterator operations." -msgstr "" -"CPython 並不是始終如一地都會檢查「疊代器有定義 :meth:`~iterator." -"__iter__`\\ 」這個規定。另請注意，:term:`free-threading（自由執行緒）` CPython 不保證疊代器操作的\\ :term:`執行緒安全 ` 行為。" - -#: ../../glossary.rst:859 -msgid "key function" -msgstr "key function（鍵函式）" - -#: ../../glossary.rst:861 -msgid "" -"A key function or collation function is a callable that returns a value used " -"for sorting or ordering. For example, :func:`locale.strxfrm` is used to " -"produce a sort key that is aware of locale specific sort conventions." -msgstr "" -"鍵函式或理序函式 (collation function) 是一個可呼叫 (callable) 函式，它會回傳" -"一個用於排序 (sorting) 或定序 (ordering) 的值。例如，:func:`locale.strxfrm` " -"被用來產生一個了解區域特定排序慣例的排序鍵。" - -#: ../../glossary.rst:866 -msgid "" -"A number of tools in Python accept key functions to control how elements are " -"ordered or grouped. They include :func:`min`, :func:`max`, :func:`sorted`, :" -"meth:`list.sort`, :func:`heapq.merge`, :func:`heapq.nsmallest`, :func:`heapq." -"nlargest`, and :func:`itertools.groupby`." -msgstr "" -"Python 中的許多工具，都接受以鍵函式來控制元素被定序或分組的方式。它們包括 :" -"func:`min`、:func:`max`、:func:`sorted`、:meth:`list.sort`、:func:`heapq." -"merge`、:func:`heapq.nsmallest`、:func:`heapq.nlargest` 和 :func:`itertools." -"groupby`。" - -#: ../../glossary.rst:872 -msgid "" -"There are several ways to create a key function. For example. the :meth:" -"`str.casefold` method can serve as a key function for case insensitive " -"sorts. Alternatively, a key function can be built from a :keyword:`lambda` " -"expression such as ``lambda r: (r[0], r[2])``. Also, :func:`operator." -"attrgetter`, :func:`operator.itemgetter`, and :func:`operator.methodcaller` " -"are three key function constructors. See the :ref:`Sorting HOW TO " -"` for examples of how to create and use key functions." -msgstr "" -"有幾種方法可以建立一個鍵函式。例如，:meth:`str.casefold` method 可以作為不分大小" -"寫排序的鍵函式。或者，一個鍵函式也可以從 :keyword:`lambda` 運算式被建造，例" -"如 ``lambda r: (r[0], r[2])``。另外，:func:`operator.attrgetter`、:func:" -"`operator.itemgetter` 和 :func:`operator.methodcaller` 為三個鍵函式的建構函" -"式 (constructor)。關於如何建立和使用鍵函式的範例，請參閱\\ :ref:`如何排序 " -"`。" - -#: ../../glossary.rst:879 -msgid "keyword argument" -msgstr "keyword argument（關鍵字引數）" - -#: ../../glossary.rst:881 ../../glossary.rst:1248 -msgid "See :term:`argument`." -msgstr "請參閱 :term:`argument`\\ （引數）。" - -#: ../../glossary.rst:882 -msgid "lambda" -msgstr "lambda" - -#: ../../glossary.rst:884 -msgid "" -"An anonymous inline function consisting of a single :term:`expression` which " -"is evaluated when the function is called. The syntax to create a lambda " -"function is ``lambda [parameters]: expression``" -msgstr "" -"由單一 :term:`expression`\\ （運算式）所組成的一個匿名行內函式 (inline " -"function)，於該函式被呼叫時求值。建立 lambda 函式的語法是 ``lambda " -"[parameters]: expression``" - -#: ../../glossary.rst:887 -msgid "LBYL" -msgstr "LBYL" - -#: ../../glossary.rst:889 -msgid "" -"Look before you leap. This coding style explicitly tests for pre-conditions " -"before making calls or lookups. This style contrasts with the :term:`EAFP` " -"approach and is characterized by the presence of many :keyword:`if` " -"statements." -msgstr "" -"Look before you leap.（三思而後行。）這種編碼風格會在進行呼叫或查找之前，明確" -"地測試先決條件。這種風格與 :term:`EAFP` 方式形成對比，且它的特色是會有許多 :" -"keyword:`if` 陳述式的存在。" - -#: ../../glossary.rst:894 -msgid "" -"In a multi-threaded environment, the LBYL approach can risk introducing a :" -"term:`race condition` between \"the looking\" and \"the leaping\". For " -"example, the code, ``if key in mapping: return mapping[key]`` can fail if " -"another thread removes *key* from *mapping* after the test, but before the " -"lookup. This issue can be solved with :term:`locks ` or by using the :" -"term:`EAFP` approach. See also :term:`thread-safe`." -msgstr "" -"在一個多執行緒環境中，LBYL 方式有在「三思」和「後行」之間引入\\ :term:`競爭條件 " -"` 的風險。例如以下程式碼 ``if key in mapping: return " -"mapping[key]``，如果另一個執行緒在測試之後但在查找之前，從 *mapping* 中移除" -"了 *key*，則該程式碼就會失效。這個問題可以用\\ :term:`鎖 `\\ 或使用 :term:" -"`EAFP` 編碼方式來解決。另請參閱\\ :term:`執行緒安全 `。" - -#: ../../glossary.rst:900 -msgid "lexical analyzer" -msgstr "lexical analyzer（詞法分析器）" - -#: ../../glossary.rst:903 -msgid "Formal name for the *tokenizer*; see :term:`token`." -msgstr "tokenizer 的正式名稱；請參閱 :term:`token`。" - -#: ../../glossary.rst:904 -msgid "list" -msgstr "list（串列）" - -#: ../../glossary.rst:906 -msgid "" -"A built-in Python :term:`sequence`. Despite its name it is more akin to an " -"array in other languages than to a linked list since access to elements is " -"*O*\\ (1)." -msgstr "" -"一個 Python 內建的 :term:`sequence` （序列）。儘管它的名字是 list，它其實更類" -"似其他語言中的一個陣列 (array) 而較不像一個鏈結串列 (linked list)，因為存取元" -"素的時間複雜度是 *O*\\ (1)。" - -#: ../../glossary.rst:909 -msgid "list comprehension" -msgstr "list comprehension（串列綜合運算）" - -#: ../../glossary.rst:911 -msgid "" -"A compact way to process all or part of the elements in a sequence and " -"return a list with the results. ``result = ['{:#04x}'.format(x) for x in " -"range(256) if x % 2 == 0]`` generates a list of strings containing even hex " -"numbers (0x..) in the range from 0 to 255. The :keyword:`if` clause is " -"optional. If omitted, all elements in ``range(256)`` are processed." -msgstr "" -"一種用來處理一個序列中的全部或部分元素，並將處理結果以一個 list 回傳的簡要方" -"法。``result = ['{:#04x}'.format(x) for x in range(256) if x % 2 == 0]`` 會產" -"生一個字串 list，其中包含 0 到 255 範圍內，所有偶數的十六進位數 (0x..)。:" -"keyword:`if` 子句是選擇性的。如果省略它，則 ``range(256)`` 中的所有元素都會被" -"處理。" - -#: ../../glossary.rst:917 -msgid "lock" -msgstr "lock（鎖）" - -#: ../../glossary.rst:919 -msgid "" -"A :term:`synchronization primitive` that allows only one thread at a time to " -"access a shared resource. A thread must acquire a lock before accessing the " -"protected resource and release it afterward. If a thread attempts to " -"acquire a lock that is already held by another thread, it will block until " -"the lock becomes available. Python's :mod:`threading` module provides :" -"class:`~threading.Lock` (a basic lock) and :class:`~threading.RLock` (a :" -"term:`reentrant` lock). Locks are used to prevent :term:`race conditions " -"` and ensure :term:`thread-safe` access to shared data. " -"Alternative design patterns to locks exist such as queues, producer/consumer " -"patterns, and thread-local state. See also :term:`deadlock`, and :term:" -"`reentrant`." -msgstr "" - -#: ../../glossary.rst:930 -msgid "loader" -msgstr "loader（載入器）" - -#: ../../glossary.rst:932 -msgid "" -"An object that loads a module. It must define the :meth:`!exec_module` and :" -"meth:`!create_module` methods to implement the :class:`~importlib.abc." -"Loader` interface. A loader is typically returned by a :term:`finder`. See " -"also:" -msgstr "" -"一個能夠載入模組的物件。它必須定義 :meth:`!exec_module` 和 :meth:`!" -"create_module` 方法以實作 :class:`~importlib.abc.Loader` 介面。載入器通常是" -"被 :term:`finder`\\ （尋檢器）回傳。更多細節請參閱：" - -#: ../../glossary.rst:938 -msgid ":ref:`finders-and-loaders`" -msgstr ":ref:`finders-and-loaders`" - -#: ../../glossary.rst:939 -msgid ":class:`importlib.abc.Loader`" -msgstr ":class:`importlib.abc.Loader`" - -#: ../../glossary.rst:940 -msgid ":pep:`302`" -msgstr ":pep:`302`" - -#: ../../glossary.rst:941 -msgid "locale encoding" -msgstr "locale encoding（區域編碼）" - -#: ../../glossary.rst:943 -msgid "" -"On Unix, it is the encoding of the LC_CTYPE locale. It can be set with :func:" -"`locale.setlocale(locale.LC_CTYPE, new_locale) `." -msgstr "" -"在 Unix 上，它是 LC_CTYPE 區域設定的編碼。它可以用 :func:`locale." -"setlocale(locale.LC_CTYPE, new_locale) ` 來設定。" - -#: ../../glossary.rst:946 -msgid "On Windows, it is the ANSI code page (ex: ``\"cp1252\"``)." -msgstr "在 Windows 上，它是 ANSI 碼頁（code page，例如 ``\"cp1252\"``\\ ）。" - -#: ../../glossary.rst:948 -msgid "" -"On Android and VxWorks, Python uses ``\"utf-8\"`` as the locale encoding." -msgstr "在 Android 和 VxWorks 上，Python 使用 ``\"utf-8\"`` 作為區域編碼。" - -#: ../../glossary.rst:950 -msgid ":func:`locale.getencoding` can be used to get the locale encoding." -msgstr ":func:`locale.getencoding` 可以用來取得區域編碼。" - -#: ../../glossary.rst:952 -msgid "See also the :term:`filesystem encoding and error handler`." -msgstr "也請參考 :term:`filesystem encoding and error handler`。" - -#: ../../glossary.rst:953 -msgid "magic method" -msgstr "magic method（魔術方法）" - -#: ../../glossary.rst:957 -msgid "An informal synonym for :term:`special method`." -msgstr ":term:`special method`\\ （特殊方法）的一個非正式同義詞。" - -#: ../../glossary.rst:958 -msgid "mapping" -msgstr "mapping（對映）" - -#: ../../glossary.rst:960 -msgid "" -"A container object that supports arbitrary key lookups and implements the " -"methods specified in the :class:`collections.abc.Mapping` or :class:" -"`collections.abc.MutableMapping` :ref:`abstract base classes `. Examples include :class:`dict`, :class:" -"`collections.defaultdict`, :class:`collections.OrderedDict` and :class:" -"`collections.Counter`." -msgstr "" -"一個容器物件，它支援任意鍵的查找，且能實作 :ref:`abstract base classes（抽象" -"基底類別） `\\ 中，:class:`collections." -"abc.Mapping` 或 :class:`collections.abc.MutableMapping` 所指定的 method。範例" -"包括 :class:`dict`、:class:`collections.defaultdict`、:class:`collections." -"OrderedDict` 和 :class:`collections.Counter`。" - -#: ../../glossary.rst:966 -msgid "meta path finder" -msgstr "meta path finder（元路徑尋檢器）" - -#: ../../glossary.rst:968 -msgid "" -"A :term:`finder` returned by a search of :data:`sys.meta_path`. Meta path " -"finders are related to, but different from :term:`path entry finders `." -msgstr "" -"一種經由搜尋 :data:`sys.meta_path` 而回傳的 :term:`finder`\\ （尋檢器）。元路" -"徑尋檢器與\\ :term:`路徑項目尋檢器 (path entry finder) ` " -"相關但是不同。" - -#: ../../glossary.rst:972 -msgid "" -"See :class:`importlib.abc.MetaPathFinder` for the methods that meta path " -"finders implement." -msgstr "" -"關於元路徑尋檢器實作的 method，請參閱 :class:`importlib.abc.MetaPathFinder`。" - -#: ../../glossary.rst:974 -msgid "metaclass" -msgstr "metaclass（元類別）" - -#: ../../glossary.rst:976 -msgid "" -"The class of a class. Class definitions create a class name, a class " -"dictionary, and a list of base classes. The metaclass is responsible for " -"taking those three arguments and creating the class. Most object oriented " -"programming languages provide a default implementation. What makes Python " -"special is that it is possible to create custom metaclasses. Most users " -"never need this tool, but when the need arises, metaclasses can provide " -"powerful, elegant solutions. They have been used for logging attribute " -"access, adding thread-safety, tracking object creation, implementing " -"singletons, and many other tasks." -msgstr "" -"一種 class 的 class。Class 定義過程會建立一個 class 名稱、一個 class " -"dictionary（字典），以及一個 base class（基底類別）的列表。Metaclass 負責接受" -"這三個引數，並建立該 class。大多數的物件導向程式語言會提供一個預設的實作。" -"Python 的特別之處在於它能夠建立自訂的 metaclass。大部分的使用者從未需要此工" -"具，但是當需要時，metaclass 可以提供強大且優雅的解決方案。它們已被用於記錄屬" -"性存取、增加執行緒安全性、追蹤物件建立、實作單例模式 (singleton)，以及許多其" -"他的任務。" - -#: ../../glossary.rst:986 -msgid "More information can be found in :ref:`metaclasses`." -msgstr "更多資訊可以在\\ :ref:`metaclasses`\\ 章節中找到。" - -#: ../../glossary.rst:955 ../../glossary.rst:987 ../../glossary.rst:1430 -msgid "method" -msgstr "method（方法）" - -#: ../../glossary.rst:989 -msgid "" -"A function which is defined inside a class body. If called as an attribute " -"of an instance of that class, the method will get the instance object as its " -"first :term:`argument` (which is usually called ``self``). See :term:" -"`function` and :term:`nested scope`." -msgstr "" -"一個在 class 本體內被定義的函式。如果 method 作為其 class 實例的一個屬性被呼" -"叫，則它將會得到該實例物件成為它的第一個 :term:`argument`\\ （引數）（此引數" -"通常被稱為 ``self``）。請參閱 :term:`function`\\ （函式）和 :term:`nested " -"scope`\\ （巢狀作用域）。" - -#: ../../glossary.rst:993 -msgid "method resolution order" -msgstr "method resolution order（方法解析順序）" - -#: ../../glossary.rst:995 -msgid "" -"Method Resolution Order is the order in which base classes are searched for " -"a member during lookup. See :ref:`python_2.3_mro` for details of the " -"algorithm used by the Python interpreter since the 2.3 release." -msgstr "" -"方法解析順序是在查找某個成員的過程中，base class（基底類別）被搜尋的順序。關" -"於 Python 自 2.3 版直譯器所使用的演算法細節，請參閱 :ref:`python_2.3_mro`。" - -#: ../../glossary.rst:998 -msgid "module" -msgstr "module（模組）" - -#: ../../glossary.rst:1000 -msgid "" -"An object that serves as an organizational unit of Python code. Modules " -"have a namespace containing arbitrary Python objects. Modules are loaded " -"into Python by the process of :term:`importing`." -msgstr "" -"一個擔任 Python 程式碼的組織單位 (organizational unit) 的物件。模組有一個命名" -"空間，它包含任意的 Python 物件。模組是藉由 :term:`importing` 的過程，被載入" -"至 Python。" - -#: ../../glossary.rst:1004 -msgid "See also :term:`package`." -msgstr "另請參閱 :term:`package`\\ （套件）。" - -#: ../../glossary.rst:1005 -msgid "module spec" -msgstr "module spec（模組規格）" - -#: ../../glossary.rst:1007 -msgid "" -"A namespace containing the import-related information used to load a module. " -"An instance of :class:`importlib.machinery.ModuleSpec`." -msgstr "" -"一個命名空間，它包含用於載入模組的 import 相關資訊。它是 :class:`importlib." -"machinery.ModuleSpec` 的一個實例。" - -#: ../../glossary.rst:1010 -msgid "See also :ref:`module-specs`." -msgstr "另請參閱 :ref:`module-specs`。" - -#: ../../glossary.rst:1011 -msgid "MRO" -msgstr "MRO" - -#: ../../glossary.rst:1013 -msgid "See :term:`method resolution order`." -msgstr "請參閱 :term:`method resolution order`\\ （方法解析順序）。" - -#: ../../glossary.rst:1014 -msgid "mutable" -msgstr "mutable（可變物件）" - -#: ../../glossary.rst:1016 -msgid "" -"An :term:`object` with state that is allowed to change during the course of " -"the program. In multi-threaded programs, mutable objects that are shared " -"between threads require careful synchronization to avoid :term:`race " -"conditions `. See also :term:`immutable`, :term:`thread-" -"safe`, and :term:`concurrent modification`." -msgstr "" - -#: ../../glossary.rst:1021 -msgid "named tuple" -msgstr "named tuple（附名元組）" - -#: ../../glossary.rst:1023 -msgid "" -"The term \"named tuple\" applies to any type or class that inherits from " -"tuple and whose indexable elements are also accessible using named " -"attributes. The type or class may have other features as well." -msgstr "" -"術語「named tuple（附名元組）」是指從 tuple 繼承的任何型別或 class，且它的可" -"索引 (indexable) 元素也可以用附名屬性來存取。這些型別或 class 也可以具有其他" -"的特性。" - -#: ../../glossary.rst:1027 -msgid "" -"Several built-in types are named tuples, including the values returned by :" -"func:`time.localtime` and :func:`os.stat`. Another example is :data:`sys." -"float_info`::" -msgstr "" -"有些內建型別是 named tuple，包括由 :func:`time.localtime` 和 :func:`os.stat` " -"回傳的值。另一個例子是 :data:`sys.float_info`： ::" - -#: ../../glossary.rst:1031 -msgid "" -">>> sys.float_info[1] # indexed access\n" -"1024\n" -">>> sys.float_info.max_exp # named field access\n" -"1024\n" -">>> isinstance(sys.float_info, tuple) # kind of tuple\n" -"True" -msgstr "" -">>> sys.float_info[1] # 以索引存取\n" -"1024\n" -">>> sys.float_info.max_exp # 以欄位名稱存取\n" -"1024\n" -">>> isinstance(sys.float_info, tuple) # 屬於 tuple 型別\n" -"True" - -#: ../../glossary.rst:1038 -msgid "" -"Some named tuples are built-in types (such as the above examples). " -"Alternatively, a named tuple can be created from a regular class definition " -"that inherits from :class:`tuple` and that defines named fields. Such a " -"class can be written by hand, or it can be created by inheriting :class:" -"`typing.NamedTuple`, or with the factory function :func:`collections." -"namedtuple`. The latter techniques also add some extra methods that may not " -"be found in hand-written or built-in named tuples." -msgstr "" -"有些 named tuple 是內建型別（如上例）。或者，一個 named tuple 也可以從一個正" -"規的 class 定義來建立，只要該 class 是繼承自 :class:`tuple`，且定義了附名欄" -"位 (named field) 即可。這類的 class 可以手工編寫、可以繼承自 :class:`typing." -"NamedTuple` 來建立，也可以使用工廠函式 (factory function) :func:`collections." -"namedtuple` 來建立。後者技術也增加了一些額外的 method，這些 method 可能是在手" -"寫或內建的 named tuple 中，無法找到的。" - -#: ../../glossary.rst:1046 -msgid "namespace" -msgstr "namespace（命名空間）" - -#: ../../glossary.rst:1048 -msgid "" -"The place where a variable is stored. Namespaces are implemented as " -"dictionaries. There are the local, global and built-in namespaces as well " -"as nested namespaces in objects (in methods). Namespaces support modularity " -"by preventing naming conflicts. For instance, the functions :func:`builtins." -"open <.open>` and :func:`os.open` are distinguished by their namespaces. " -"Namespaces also aid readability and maintainability by making it clear which " -"module implements a function. For instance, writing :func:`random.seed` or :" -"func:`itertools.islice` makes it clear that those functions are implemented " -"by the :mod:`random` and :mod:`itertools` modules, respectively." -msgstr "" -"變數被儲存的地方。命名空間是以 dictionary（字典）被實作。有區域的、全域的及內" -"建的命名空間，而在物件中（在 method 中）也有巢狀的命名空間。命名空間藉由防止" -"命名衝突，來支援模組化。例如，函式 :func:`builtins.open <.open>` 和 :func:" -"`os.open` 是透過它們的命名空間來區分彼此。命名空間也藉由明確地區分是哪個模組" -"在實作一個函式，來增進可讀性及可維護性。例如，寫出 :func:`random.seed` 或 :" -"func:`itertools.islice` 明確地表示，這些函式分別是由 :mod:`random` 和 :mod:" -"`itertools` 模組在實作。" - -#: ../../glossary.rst:1058 -msgid "namespace package" -msgstr "namespace package（命名空間套件）" - -#: ../../glossary.rst:1060 -msgid "" -"A :term:`package` which serves only as a container for subpackages. " -"Namespace packages may have no physical representation, and specifically are " -"not like a :term:`regular package` because they have no ``__init__.py`` file." -msgstr "" -"一個 :term:`package`\\ （套件），它只能作為子套件 (subpackage) 的一個容器。命" -"名空間套件可能沒有實體的表示法，而且具體來說它們不像是一個 :term:`regular " -"package`\\ （正規套件），因為它們並沒有 ``__init__.py`` 這個檔案。" - -#: ../../glossary.rst:1065 -msgid "" -"Namespace packages allow several individually installable packages to have a " -"common parent package. Otherwise, it is recommended to use a :term:`regular " -"package`." -msgstr "" -"命名空間套件允許數個可獨立安裝的套件擁有一個共同的父套件。除此之外，建議使" -"用 :term:`regular package`。" - -#: ../../glossary.rst:1068 -msgid "" -"For more information, see :pep:`420` and :ref:`reference-namespace-package`." -msgstr "更多資訊，請參閱 :pep:`420` 和 :ref:`reference-namespace-package`。" - -#: ../../glossary.rst:1070 -msgid "See also :term:`module`." -msgstr "另請參閱 :term:`module`\\ （模組）。" - -#: ../../glossary.rst:1071 -msgid "native code" -msgstr "" - -#: ../../glossary.rst:1073 -msgid "" -"Code that is compiled to machine instructions and runs directly on the " -"processor, as opposed to code that is interpreted or runs in a virtual " -"machine. In the context of Python, native code typically refers to C, C++, " -"Rust or Fortran code in :term:`extension modules ` that " -"can be called from Python. See also :term:`extension module`." -msgstr "" - -#: ../../glossary.rst:1078 -msgid "nested scope" -msgstr "nested scope（巢狀作用域）" - -#: ../../glossary.rst:1080 -msgid "" -"The ability to refer to a variable in an enclosing definition. For " -"instance, a function defined inside another function can refer to variables " -"in the outer function. Note that nested scopes by default work only for " -"reference and not for assignment. Local variables both read and write in " -"the innermost scope. Likewise, global variables read and write to the " -"global namespace. The :keyword:`nonlocal` allows writing to outer scopes." -msgstr "" -"能夠參照外層定義 (enclosing definition) 中的變數的能力。舉例來說，一個函式如" -"果是在另一個函式中被定義，則它便能夠參照外層函式中的變數。請注意，在預設情況" -"下，巢狀作用域僅適用於參照，而無法用於賦值。區域變數能在最內層作用域中讀取及" -"寫入。同樣地，全域變數是在全域命名空間中讀取及寫入。:keyword:`nonlocal` 容許" -"對外層作用域進行寫入。" - -#: ../../glossary.rst:1087 -msgid "new-style class" -msgstr "new-style class（新式類別）" - -#: ../../glossary.rst:1089 -msgid "" -"Old name for the flavor of classes now used for all class objects. In " -"earlier Python versions, only new-style classes could use Python's newer, " -"versatile features like :attr:`~object.__slots__`, descriptors, properties, :" -"meth:`~object.__getattribute__`, class methods, and static methods." -msgstr "" -"一個舊名，它是指現在所有的 class 物件所使用的 class 風格。在早期的 Python 版" -"本中，只有新式 class 才能使用 Python 較新的、多樣的功能，像是 :attr:`~object." -"__slots__`、描述器 (descriptor)、屬性 (property)、:meth:`~object." -"__getattribute__`、class method（類別方法）和 static method（靜態方法）。" - -#: ../../glossary.rst:1094 -msgid "non-deterministic" -msgstr "" - -#: ../../glossary.rst:1096 -msgid "" -"Behavior where the outcome of a program can vary between executions with the " -"same inputs. In multi-threaded programs, non-deterministic behavior often " -"results from :term:`race conditions ` where the relative " -"timing or interleaving of threads affects the result. Proper synchronization " -"using :term:`locks ` and other :term:`synchronization primitives " -"` helps ensure deterministic behavior." -msgstr "" - -#: ../../glossary.rst:1103 -msgid "object" -msgstr "object（物件）" - -#: ../../glossary.rst:1105 -msgid "" -"Any data with state (attributes or value) and defined behavior (methods). " -"Also the ultimate base class of any :term:`new-style class`." -msgstr "" -"具有狀態（屬性或值）及被定義的行為（method）的任何資料。它也是任何 :term:" -"`new-style class`\\ （新式類別）的最終 base class（基底類別）。" - -#: ../../glossary.rst:1108 -msgid "optimized scope" -msgstr "optimized scope（最佳化作用域）" - -#: ../../glossary.rst:1110 -msgid "" -"A scope where target local variable names are reliably known to the compiler " -"when the code is compiled, allowing optimization of read and write access to " -"these names. The local namespaces for functions, generators, coroutines, " -"comprehensions, and generator expressions are optimized in this fashion. " -"Note: most interpreter optimizations are applied to all scopes, only those " -"relying on a known set of local and nonlocal variable names are restricted " -"to optimized scopes." -msgstr "" - -#: ../../glossary.rst:1117 -msgid "optional module" -msgstr "optional module（可選模組）" - -#: ../../glossary.rst:1119 -msgid "" -"An :term:`extension module` that is part of the :term:`standard library`, " -"but may be absent in some builds of :term:`CPython`, usually due to missing " -"third-party libraries or because the module is not available for a given " -"platform." -msgstr "" - -#: ../../glossary.rst:1124 -msgid "" -"See :ref:`optional-module-requirements` for a list of optional modules that " -"require third-party libraries." -msgstr "" - -#: ../../glossary.rst:1126 -msgid "package" -msgstr "package（套件）" - -#: ../../glossary.rst:1128 -msgid "" -"A Python :term:`module` which can contain submodules or recursively, " -"subpackages. Technically, a package is a Python module with a ``__path__`` " -"attribute." -msgstr "" -"一個 Python 的 :term:`module`\\ （模組），它可以包含子模組 (submodule) 或是遞" -"迴的子套件 (subpackage)。技術上而言，套件就是具有 ``__path__`` 屬性的一個 " -"Python 模組。" - -#: ../../glossary.rst:1132 -msgid "See also :term:`regular package` and :term:`namespace package`." -msgstr "" -"另請參閱 :term:`regular package`\\ （正規套件）和 :term:`namespace " -"package`\\ （命名空間套件）。" - -#: ../../glossary.rst:1133 -msgid "parallelism" -msgstr "" - -#: ../../glossary.rst:1135 -msgid "" -"Executing multiple operations at the same time (e.g. on multiple CPU " -"cores). In Python builds with the :term:`global interpreter lock (GIL) " -"`, only one thread runs Python bytecode at a time, " -"so taking advantage of multiple CPU cores typically involves multiple " -"processes (e.g. :mod:`multiprocessing`) or native extensions that release " -"the GIL. In :term:`free-threaded ` Python, multiple Python " -"threads can run Python code simultaneously on different cores." -msgstr "" - -#: ../../glossary.rst:1143 -msgid "parameter" -msgstr "parameter（參數）" - -#: ../../glossary.rst:1145 -msgid "" -"A named entity in a :term:`function` (or method) definition that specifies " -"an :term:`argument` (or in some cases, arguments) that the function can " -"accept. There are five kinds of parameter:" -msgstr "" -"在 :term:`function`\\ （函式）或 method 定義中的一個命名實體 (named entity)，" -"它指明該函式能夠接受的一個 :term:`argument`\\ （引數），或在某些情況下指示多" -"個引數。共有有五種不同的參數類型：" - -#: ../../glossary.rst:1149 -msgid "" -":dfn:`positional-or-keyword`: specifies an argument that can be passed " -"either :term:`positionally ` or as a :term:`keyword argument " -"`. This is the default kind of parameter, for example *foo* and " -"*bar* in the following::" -msgstr "" -":dfn:`positional-or-keyword`\\ （位置或關鍵字）：指明一個可以\\ :term:`按照位" -"置 `\\ 或是作為\\ :term:`關鍵字引數 `\\ 被傳遞的引數。這" -"是參數的預設類型，例如以下的 *foo* 和 *bar*： ::" - -#: ../../glossary.rst:1154 -msgid "def func(foo, bar=None): ..." -msgstr "def func(foo, bar=None): ..." - -#: ../../glossary.rst:1158 -msgid "" -":dfn:`positional-only`: specifies an argument that can be supplied only by " -"position. Positional-only parameters can be defined by including a ``/`` " -"character in the parameter list of the function definition after them, for " -"example *posonly1* and *posonly2* in the following::" -msgstr "" -":dfn:`positional-only`\\ （僅限位置）：指明一個只能按照位置被提供的引數。在函" -"式定義的參數列表中包含一個 ``/`` 字元，就可以在該字元前面定義僅限位置參數，例" -"如以下的 *posonly1* 和 *posonly2*： ::" - -#: ../../glossary.rst:1163 -msgid "def func(posonly1, posonly2, /, positional_or_keyword): ..." -msgstr "def func(posonly1, posonly2, /, positional_or_keyword): ..." - -#: ../../glossary.rst:1167 -msgid "" -":dfn:`keyword-only`: specifies an argument that can be supplied only by " -"keyword. Keyword-only parameters can be defined by including a single var-" -"positional parameter or bare ``*`` in the parameter list of the function " -"definition before them, for example *kw_only1* and *kw_only2* in the " -"following::" -msgstr "" -":dfn:`keyword-only`\\ （僅限關鍵字）：指明一個只能以關鍵字被提供的引數。在函" -"式定義的參數列表中，包含一個任意數量位置參數 (var-positional parameter) 或是" -"單純的 ``*`` 字元，就可以在其後方定義僅限關鍵字參數，例如以下的 *kw_only1* " -"和 *kw_only2*： ::" - -#: ../../glossary.rst:1173 -msgid "def func(arg, *, kw_only1, kw_only2): ..." -msgstr "def func(arg, *, kw_only1, kw_only2): ..." - -#: ../../glossary.rst:1175 -msgid "" -":dfn:`var-positional`: specifies that an arbitrary sequence of positional " -"arguments can be provided (in addition to any positional arguments already " -"accepted by other parameters). Such a parameter can be defined by " -"prepending the parameter name with ``*``, for example *args* in the " -"following::" -msgstr "" -":dfn:`var-positional`\\ （任意數量位置）：指明一串能以任意序列被提供的位置引" -"數（在已被其他參數接受的任何位置引數之外）。這類參數是透過在其參數名稱字首加" -"上 ``*`` 來定義的，例如以下的 *args*： ::" - -#: ../../glossary.rst:1181 -msgid "def func(*args, **kwargs): ..." -msgstr "def func(*args, **kwargs): ..." - -#: ../../glossary.rst:1183 -msgid "" -":dfn:`var-keyword`: specifies that arbitrarily many keyword arguments can be " -"provided (in addition to any keyword arguments already accepted by other " -"parameters). Such a parameter can be defined by prepending the parameter " -"name with ``**``, for example *kwargs* in the example above." -msgstr "" -":dfn:`var-keyword`\\ （任意數量關鍵字）：指明可被提供的任意數量關鍵字引數（在" -"已被其他參數接受的任何關鍵字引數之外）。這類參數是透過在其參數名稱字首加上 " -"``**`` 來定義的，例如上面範例中的 *kwargs*。" - -#: ../../glossary.rst:1189 -msgid "" -"Parameters can specify both optional and required arguments, as well as " -"default values for some optional arguments." -msgstr "" -"參數可以指明引數是選擇性的或必需的，也可以為一些選擇性的引數指定預設值。" - -#: ../../glossary.rst:1192 -msgid "" -"See also the :term:`argument` glossary entry, the FAQ question on :ref:`the " -"difference between arguments and parameters `, " -"the :class:`inspect.Parameter` class, the :ref:`function` section, and :pep:" -"`362`." -msgstr "" -"另請參閱術語表的 :term:`argument`\\ （引數）條目、常見問題中的\\ :ref:`引數和" -"參數之間的差異 `、:class:`inspect.Parameter` " -"class、:ref:`function`\\ 章節，以及 :pep:`362`。" - -#: ../../glossary.rst:1196 -msgid "path entry" -msgstr "path entry（路徑項目）" - -#: ../../glossary.rst:1198 -msgid "" -"A single location on the :term:`import path` which the :term:`path based " -"finder` consults to find modules for importing." -msgstr "" -"在 :term:`import path`\\ （引入路徑）中的一個位置，而 :term:`path based " -"finder` （基於路徑的尋檢器）會參考該位置來尋找要 import 的模組。" - -#: ../../glossary.rst:1200 -msgid "path entry finder" -msgstr "path entry finder（路徑項目尋檢器）" - -#: ../../glossary.rst:1202 -msgid "" -"A :term:`finder` returned by a callable on :data:`sys.path_hooks` (i.e. a :" -"term:`path entry hook`) which knows how to locate modules given a :term:" -"`path entry`." -msgstr "" -"被 :data:`sys.path_hooks` 中的一個可呼叫物件 (callable)（意即一個 :term:" -"`path entry hook`\\ ）所回傳的一種 :term:`finder`，它知道如何以一個 :term:" -"`path entry`\\ 定位模組。" - -#: ../../glossary.rst:1206 -msgid "" -"See :class:`importlib.abc.PathEntryFinder` for the methods that path entry " -"finders implement." -msgstr "" -"關於路徑項目尋檢器實作的 method，請參閱 :class:`importlib.abc." -"PathEntryFinder`。" - -#: ../../glossary.rst:1208 -msgid "path entry hook" -msgstr "path entry hook（路徑項目鉤）" - -#: ../../glossary.rst:1210 -msgid "" -"A callable on the :data:`sys.path_hooks` list which returns a :term:`path " -"entry finder` if it knows how to find modules on a specific :term:`path " -"entry`." -msgstr "" -"在 :data:`sys.path_hooks` 列表中的一個可呼叫物件 (callable)，若它知道如何在一" -"個特定的 :term:`path entry` 中尋找模組，則會回傳一個 :term:`path entry " -"finder`\\ （路徑項目尋檢器）。" - -#: ../../glossary.rst:1213 -msgid "path based finder" -msgstr "path based finder（基於路徑的尋檢器）" - -#: ../../glossary.rst:1215 -msgid "" -"One of the default :term:`meta path finders ` which " -"searches an :term:`import path` for modules." -msgstr "" -"預設的\\ :term:`元路徑尋檢器 (meta path finder) ` 之一，它" -"會在一個 :term:`import path` 中搜尋模組。" - -#: ../../glossary.rst:1217 -msgid "path-like object" -msgstr "path-like object（類路徑物件）" - -#: ../../glossary.rst:1219 -msgid "" -"An object representing a file system path. A path-like object is either a :" -"class:`str` or :class:`bytes` object representing a path, or an object " -"implementing the :class:`os.PathLike` protocol. An object that supports the :" -"class:`os.PathLike` protocol can be converted to a :class:`str` or :class:" -"`bytes` file system path by calling the :func:`os.fspath` function; :func:" -"`os.fsdecode` and :func:`os.fsencode` can be used to guarantee a :class:" -"`str` or :class:`bytes` result instead, respectively. Introduced by :pep:" -"`519`." -msgstr "" -"一個表示檔案系統路徑的物件。類路徑物件可以是一個表示路徑的 :class:`str` 或 :" -"class:`bytes` 物件，或是一個實作 :class:`os.PathLike` 協定的物件。透過呼叫 :" -"func:`os.fspath` 函式，一個支援 :class:`os.PathLike` 協定的物件可以被轉換為 :" -"class:`str` 或 :class:`bytes` 檔案系統路徑；而 :func:`os.fsdecode` 及 :func:" -"`os.fsencode` 則分別可用於確保 :class:`str` 及 :class:`bytes` 的結果。由 :" -"pep:`519` 引入。" - -#: ../../glossary.rst:1227 -msgid "PEP" -msgstr "PEP" - -#: ../../glossary.rst:1229 -msgid "" -"Python Enhancement Proposal. A PEP is a design document providing " -"information to the Python community, or describing a new feature for Python " -"or its processes or environment. PEPs should provide a concise technical " -"specification and a rationale for proposed features." -msgstr "" -"Python Enhancement Proposal（Python 增強提案）。PEP 是一份設計說明文件，它能" -"為 Python 社群提供資訊，或是描述 Python 的一個新功能或該功能的程序和環境。" -"PEP 應該要提供簡潔的技術規範以及被提案功能的運作原理。" - -#: ../../glossary.rst:1235 -msgid "" -"PEPs are intended to be the primary mechanisms for proposing major new " -"features, for collecting community input on an issue, and for documenting " -"the design decisions that have gone into Python. The PEP author is " -"responsible for building consensus within the community and documenting " -"dissenting opinions." -msgstr "" -"PEP 的存在目的，是要成為重大新功能的提案、社群中關於某個問題的意見收集，以及" -"已納入 Python 的設計決策的記錄，這些過程的主要機制。PEP 的作者要負責在社群內" -"建立共識並記錄反對意見。" - -#: ../../glossary.rst:1241 -msgid "See :pep:`1`." -msgstr "請參閱 :pep:`1`。" - -#: ../../glossary.rst:1242 -msgid "portion" -msgstr "portion（部分）" - -#: ../../glossary.rst:1244 -msgid "" -"A set of files in a single directory (possibly stored in a zip file) that " -"contribute to a namespace package, as defined in :pep:`420`." -msgstr "" -"在單一目錄中的一組檔案（也可能儲存在一個 zip 檔中），這些檔案能對一個命名空間" -"套件 (namespace package) 有所貢獻，如同 :pep:`420` 中的定義。" - -#: ../../glossary.rst:1246 -msgid "positional argument" -msgstr "positional argument（位置引數）" - -#: ../../glossary.rst:1249 -msgid "provisional API" -msgstr "provisional API（暫行 API）" - -#: ../../glossary.rst:1251 -msgid "" -"A provisional API is one which has been deliberately excluded from the " -"standard library's backwards compatibility guarantees. While major changes " -"to such interfaces are not expected, as long as they are marked provisional, " -"backwards incompatible changes (up to and including removal of the " -"interface) may occur if deemed necessary by core developers. Such changes " -"will not be made gratuitously -- they will occur only if serious fundamental " -"flaws are uncovered that were missed prior to the inclusion of the API." -msgstr "" -"暫行 API 是指，從標準函式庫的向後相容性 (backwards compatibility) 保證中，故" -"意被排除的 API。雖然此類介面，只要它們被標示為暫行的，理論上並不會有重大的變" -"更，但如果核心開發人員認為有必要，也可能會出現向後不相容的變更（甚至包括移除" -"該介面）。這種變更並不會無端地產生——只有 API 被納入之前未察覺的嚴重基本缺陷被" -"揭露時，它們才會發生。" - -#: ../../glossary.rst:1260 -msgid "" -"Even for provisional APIs, backwards incompatible changes are seen as a " -"\"solution of last resort\" - every attempt will still be made to find a " -"backwards compatible resolution to any identified problems." -msgstr "" -"即使對於暫行 API，向後不相容的變更也會被視為「最後的解決方案」——對於任何被發" -"現的問題，仍然會盡可能找出一個向後相容的解決方案。" - -#: ../../glossary.rst:1264 -msgid "" -"This process allows the standard library to continue to evolve over time, " -"without locking in problematic design errors for extended periods of time. " -"See :pep:`411` for more details." -msgstr "" -"這個過程使得標準函式庫能隨著時間不斷進化，而避免耗費過長的時間去鎖定有問題的" -"設計錯誤。請參閱 :pep:`411` 了解更多細節。" - -#: ../../glossary.rst:1267 -msgid "provisional package" -msgstr "provisional package（暫行套件）" - -#: ../../glossary.rst:1269 -msgid "See :term:`provisional API`." -msgstr "請參閱 :term:`provisional API`\\ （暫行 API）。" - -#: ../../glossary.rst:1270 -msgid "Python 3000" -msgstr "Python 3000" - -#: ../../glossary.rst:1272 -msgid "" -"Nickname for the Python 3.x release line (coined long ago when the release " -"of version 3 was something in the distant future.) This is also abbreviated " -"\"Py3k\"." -msgstr "" -"Python 3.x 系列版本的暱稱（很久以前創造的，當時第 3 版的發布是在遙遠的未" -"來。）也可以縮寫為「Py3k」。" - -#: ../../glossary.rst:1275 -msgid "Pythonic" -msgstr "Pythonic（Python 風格的）" - -#: ../../glossary.rst:1277 -msgid "" -"An idea or piece of code which closely follows the most common idioms of the " -"Python language, rather than implementing code using concepts common to " -"other languages. For example, a common idiom in Python is to loop over all " -"elements of an iterable using a :keyword:`for` statement. Many other " -"languages don't have this type of construct, so people unfamiliar with " -"Python sometimes use a numerical counter instead::" -msgstr "" -"一個想法或一段程式碼，它應用了 Python 語言最常見的慣用語，而不是使用其他語言" -"常見的概念來實作程式碼。例如，Python 中常見的一種習慣用法，是使用一個 :" -"keyword:`for` 陳述式，對一個可疊代物件的所有元素進行迴圈。許多其他語言並沒有" -"這種類型的架構，所以不熟悉 Python 的人有時會使用一個數值計數器來代替： ::" - -#: ../../glossary.rst:1284 -msgid "" -"for i in range(len(food)):\n" -" print(food[i])" -msgstr "" -"for i in range(len(food)):\n" -" print(food[i])" - -#: ../../glossary.rst:1287 -msgid "As opposed to the cleaner, Pythonic method::" -msgstr "相較之下，以下方法更簡潔、更具有 Python 風格： ::" - -#: ../../glossary.rst:1289 -msgid "" -"for piece in food:\n" -" print(piece)" -msgstr "" -"for piece in food:\n" -" print(piece)" - -#: ../../glossary.rst:1291 -msgid "qualified name" -msgstr "qualified name（限定名稱）" - -#: ../../glossary.rst:1293 -msgid "" -"A dotted name showing the \"path\" from a module's global scope to a class, " -"function or method defined in that module, as defined in :pep:`3155`. For " -"top-level functions and classes, the qualified name is the same as the " -"object's name::" -msgstr "" -"一個「點分隔名稱」，它顯示從一個模組的全域作用域到該模組中定義的 class、函式" -"或 method 的「路徑」，如 :pep:`3155` 中的定義。對於頂層的函式和 class 而言，" -"限定名稱與其物件名稱相同： ::" - -#: ../../glossary.rst:1298 -msgid "" -">>> class C:\n" -"... class D:\n" -"... def meth(self):\n" -"... pass\n" -"...\n" -">>> C.__qualname__\n" -"'C'\n" -">>> C.D.__qualname__\n" -"'C.D'\n" -">>> C.D.meth.__qualname__\n" -"'C.D.meth'" -msgstr "" -">>> class C:\n" -"... class D:\n" -"... def meth(self):\n" -"... pass\n" -"...\n" -">>> C.__qualname__\n" -"'C'\n" -">>> C.D.__qualname__\n" -"'C.D'\n" -">>> C.D.meth.__qualname__\n" -"'C.D.meth'" - -#: ../../glossary.rst:1310 -msgid "" -"When used to refer to modules, the *fully qualified name* means the entire " -"dotted path to the module, including any parent packages, e.g. ``email.mime." -"text``::" -msgstr "" -"當用於引用模組時，*完全限定名稱 (fully qualified name)* 是表示該模組的完整點" -"分隔路徑，包括任何的父套件，例如 ``email.mime.text``： ::" - -#: ../../glossary.rst:1314 -msgid "" -">>> import email.mime.text\n" -">>> email.mime.text.__name__\n" -"'email.mime.text'" -msgstr "" -">>> import email.mime.text\n" -">>> email.mime.text.__name__\n" -"'email.mime.text'" - -#: ../../glossary.rst:1317 -msgid "race condition" -msgstr "" - -#: ../../glossary.rst:1319 -msgid "" -"A condition of a program where the its behavior depends on the relative " -"timing or ordering of events, particularly in multi-threaded programs. Race " -"conditions can lead to :term:`non-deterministic` behavior and bugs that are " -"difficult to reproduce. A :term:`data race` is a specific type of race " -"condition involving unsynchronized access to shared memory. The :term:" -"`LBYL` coding style is particularly susceptible to race conditions in multi-" -"threaded code. Using :term:`locks ` and other :term:`synchronization " -"primitives ` helps prevent race conditions." -msgstr "" - -#: ../../glossary.rst:1329 -msgid "reference count" -msgstr "reference count（參照計數）" - -#: ../../glossary.rst:1331 -msgid "" -"The number of references to an object. When the reference count of an " -"object drops to zero, it is deallocated. Some objects are :term:`immortal` " -"and have reference counts that are never modified, and therefore the objects " -"are never deallocated. Reference counting is generally not visible to " -"Python code, but it is a key element of the :term:`CPython` implementation. " -"Programmers can call the :func:`sys.getrefcount` function to return the " -"reference count for a particular object." -msgstr "" -"對於一個物件的參照次數。當一個物件的參照計數下降到零時，它會被解除配置 " -"(deallocated)。有些物件是「\\ :term:`不滅的 ` (immortal)」並擁有不" -"會被改變的參照計數，也因此永遠不會被解除配置。參照計數通常在 Python 程式碼中" -"看不到，但它卻是 :term:`CPython` 實作的一個關鍵元素。程式設計師可以呼叫 :" -"func:`~sys.getrefcount` 函式來回傳一個特定物件的參照計數。" - -#: ../../glossary.rst:1340 -msgid "" -"In :term:`CPython`, reference counts are not considered to be stable or well-" -"defined values; the number of references to an object, and how that number " -"is affected by Python code, may be different between versions." -msgstr "" -"在 :term:`CPython` 中，參照計數不被視為穩定或明確定義的值；對物件的參照數量，" -"以及該數量如何受到 Python 程式碼的影響，在不同版本之間可能會有所不同。" - -#: ../../glossary.rst:1344 -msgid "regular package" -msgstr "regular package（正規套件）" - -#: ../../glossary.rst:1346 -msgid "" -"A traditional :term:`package`, such as a directory containing an ``__init__." -"py`` file." -msgstr "" -"一個傳統的 :term:`package`\\ （套件），例如一個包含 ``__init__.py`` 檔案的目" -"錄。" - -#: ../../glossary.rst:1349 -msgid "See also :term:`namespace package`." -msgstr "另請參閱 :term:`namespace package`\\ （命名空間套件）。" - -#: ../../glossary.rst:1350 -msgid "reentrant" -msgstr "" - -#: ../../glossary.rst:1352 -msgid "" -"A property of a function or :term:`lock` that allows it to be called or " -"acquired multiple times by the same thread without causing errors or a :term:" -"`deadlock`." -msgstr "" - -#: ../../glossary.rst:1356 -msgid "" -"For functions, reentrancy means the function can be safely called again " -"before a previous invocation has completed, which is important when " -"functions may be called recursively or from signal handlers. Thread-unsafe " -"functions may be :term:`non-deterministic` if they're called reentrantly in " -"a multithreaded program." -msgstr "" - -#: ../../glossary.rst:1362 -msgid "" -"For locks, Python's :class:`threading.RLock` (reentrant lock) is reentrant, " -"meaning a thread that already holds the lock can acquire it again without " -"blocking. In contrast, :class:`threading.Lock` is not reentrant - " -"attempting to acquire it twice from the same thread will cause a deadlock." -msgstr "" - -#: ../../glossary.rst:1368 -msgid "See also :term:`lock` and :term:`deadlock`." -msgstr "另請參閱 :term:`lock` 和 :term:`deadlock`。" - -#: ../../glossary.rst:1369 -msgid "REPL" -msgstr "REPL" - -#: ../../glossary.rst:1371 -msgid "" -"An acronym for the \"read–eval–print loop\", another name for the :term:" -"`interactive` interpreter shell." -msgstr "" -"「read-eval-print 迴圈 (read–eval–print loop)」的縮寫，是\\ :term:`互動式 " -"`\\ 直譯器 shell 的另一個名稱。" - -#: ../../glossary.rst:1373 -msgid "__slots__" -msgstr "__slots__" - -#: ../../glossary.rst:1375 -msgid "" -"A declaration inside a class that saves memory by pre-declaring space for " -"instance attributes and eliminating instance dictionaries. Though popular, " -"the technique is somewhat tricky to get right and is best reserved for rare " -"cases where there are large numbers of instances in a memory-critical " -"application." -msgstr "" -"在 class 內部的一個宣告，它藉由預先宣告實例屬性的空間，以及消除實例 " -"dictionary（字典），來節省記憶體。雖然該技術很普遍，但它有點難以正確地使用，" -"最好保留給那種在一個記憶體關鍵 (memory-critical) 的應用程式中存在大量實例的罕" -"見情況。" - -#: ../../glossary.rst:1380 -msgid "sequence" -msgstr "sequence（序列）" - -#: ../../glossary.rst:1382 -msgid "" -"An :term:`iterable` which supports efficient element access using integer " -"indices via the :meth:`~object.__getitem__` special method and defines a :" -"meth:`~object.__len__` method that returns the length of the sequence. Some " -"built-in sequence types are :class:`list`, :class:`str`, :class:`tuple`, " -"and :class:`bytes`. Note that :class:`dict` also supports :meth:`~object." -"__getitem__` and :meth:`!__len__`, but is considered a mapping rather than a " -"sequence because the lookups use arbitrary :term:`hashable` keys rather than " -"integers." -msgstr "" -"一個 :term:`iterable`\\ （可疊代物件），它透過 :meth:`~object.__getitem__` " -"special method（特殊方法），使用整數索引來支援高效率的元素存取，並定義了一" -"個 :meth:`~object.__len__` method 來回傳該序列的長度。一些內建序列型別包括 :" -"class:`list`、:class:`str`、:class:`tuple` 和 :class:`bytes`。請注意，雖然 :" -"class:`dict` 也支援 :meth:`~object.__getitem__` 和 :meth:`!__len__`，但它被視" -"為對映 (mapping) 而不是序列，因為其查找方式是使用任意的 :term:`hashable` 鍵，" -"而不是整數。" - -#: ../../glossary.rst:1391 -msgid "" -"The :class:`collections.abc.Sequence` abstract base class defines a much " -"richer interface that goes beyond just :meth:`~object.__getitem__` and :meth:" -"`~object.__len__`, adding :meth:`~sequence.count`, :meth:`~sequence.index`, :" -"meth:`~object.__contains__`, and :meth:`~object.__reversed__`. Types that " -"implement this expanded interface can be registered explicitly using :func:" -"`~abc.ABCMeta.register`. For more documentation on sequence methods " -"generally, see :ref:`Common Sequence Operations `." -msgstr "" -"抽象基底類別 (abstract base class) :class:`collections.abc.Sequence` 定義了一" -"個更加豐富的介面，並不僅止於 :meth:`~object.__getitem__` 和 :meth:`~object." -"__len__`，還增加了 :meth:`~sequence.count`、:meth:`~sequence.index`、:meth:" -"`~object.__contains__` 和 :meth:`~object.__reversed__`。實作此擴充介面的型" -"別，可以使用 :func:`~abc.ABCMeta.register` 被明確地註冊。更多關於序列方法的文" -"件，請見\\ :ref:`常見序列操作 `。" - -#: ../../glossary.rst:1401 -msgid "set comprehension" -msgstr "set comprehension（集合綜合運算）" - -#: ../../glossary.rst:1403 -msgid "" -"A compact way to process all or part of the elements in an iterable and " -"return a set with the results. ``results = {c for c in 'abracadabra' if c " -"not in 'abc'}`` generates the set of strings ``{'r', 'd'}``. See :ref:" -"`comprehensions`." -msgstr "" -"一種緊密的方法，用來處理一個可疊代物件中的全部或部分元素，並將處理結果以一個 " -"set 回傳。``results = {c for c in 'abracadabra' if c not in 'abc'}`` 會產生一" -"個字串 set：``{'r', 'd'}``。請參閱\\ :ref:`comprehensions`。" - -#: ../../glossary.rst:1407 -msgid "single dispatch" -msgstr "single dispatch（單一調度）" - -#: ../../glossary.rst:1409 -msgid "" -"A form of :term:`generic function` dispatch where the implementation is " -"chosen based on the type of a single argument." -msgstr "" -":term:`generic function`\\ （泛型函式）調度的一種形式，在此，實作的選擇是基於" -"單一引數的型別。" - -#: ../../glossary.rst:1411 -msgid "slice" -msgstr "slice（切片）" - -#: ../../glossary.rst:1413 -msgid "" -"An object usually containing a portion of a :term:`sequence`. A slice is " -"created using the subscript notation, ``[]`` with colons between numbers " -"when several are given, such as in ``variable_name[1:3:5]``. The bracket " -"(subscript) notation uses :class:`slice` objects internally." -msgstr "" -"一個物件，它通常包含一段 :term:`sequence`\\ （序列）的某一部分。建立一段切片" -"的方法是使用下標符號 (subscript notation) ``[]``，若要給出多個數字，則在數字" -"之間使用冒號，例如 ``variable_name[1:3:5]``。在括號（下標）符號的內部，會使" -"用 :class:`slice` 物件。" - -#: ../../glossary.rst:1417 -msgid "soft deprecated" -msgstr "soft deprecated（軟性棄用）" - -#: ../../glossary.rst:1419 -msgid "" -"A soft deprecated API should not be used in new code, but it is safe for " -"already existing code to use it. The API remains documented and tested, but " -"will not be enhanced further." -msgstr "" -"被軟性棄用的 API 代表不應再用於新程式碼中，但在現有程式碼中繼續使用它仍會是安" -"全的。API 仍會以文件記錄並會被測試，但不會被繼續改進。" - -#: ../../glossary.rst:1423 -msgid "" -"Soft deprecation, unlike normal deprecation, does not plan on removing the " -"API and will not emit warnings." -msgstr "與正常棄用不同，軟性棄用沒有刪除 API 的規劃，也不會發出警告。" - -#: ../../glossary.rst:1426 -msgid "" -"See `PEP 387: Soft Deprecation `_." -msgstr "" -"請參閱 `PEP 387：軟性棄用 `_。" - -#: ../../glossary.rst:1428 -msgid "special method" -msgstr "special method（特殊方法）" - -#: ../../glossary.rst:1432 -msgid "" -"A method that is called implicitly by Python to execute a certain operation " -"on a type, such as addition. Such methods have names starting and ending " -"with double underscores. Special methods are documented in :ref:" -"`specialnames`." -msgstr "" -"一種會被 Python 自動呼叫的 method，用於對某種型別執行某種運算，例如加法。這" -"種 method 的名稱會在開頭和結尾有兩個下底線。Special method 在\\ :ref:" -"`specialnames`\\ 中有詳細說明。" - -#: ../../glossary.rst:1436 -msgid "standard library" -msgstr "標準函式庫" - -#: ../../glossary.rst:1438 -msgid "" -"The collection of :term:`packages `, :term:`modules ` and :" -"term:`extension modules ` distributed as a part of the " -"official Python interpreter package. The exact membership of the collection " -"may vary based on platform, available system libraries, or other criteria. " -"Documentation can be found at :ref:`library-index`." -msgstr "" -"包含\\ :term:`套件 `、:term:`模組 `\\ 和\\ :term:`擴充模組 " -"`\\ 的集合，它們是作為官方 Python 直譯器套件的一部分來發" -"行。該集合的成員可能會因平台、可用的系統函式庫或其他條件而有所不同。相關文件" -"可以在 :ref:`library-index` 中找到。" - -#: ../../glossary.rst:1444 -msgid "" -"See also :data:`sys.stdlib_module_names` for a list of all possible standard " -"library module names." -msgstr "" -"請參閱 :data:`sys.stdlib_module_names` 以取得所有可能的標準函式庫模組名稱的列" -"表。" - -#: ../../glossary.rst:1446 -msgid "statement" -msgstr "statement（陳述式）" - -#: ../../glossary.rst:1448 -msgid "" -"A statement is part of a suite (a \"block\" of code). A statement is either " -"an :term:`expression` or one of several constructs with a keyword, such as :" -"keyword:`if`, :keyword:`while` or :keyword:`for`." -msgstr "" -"陳述式是一個套組（suite，一個程式碼「區塊」）中的一部分。陳述式可以是一個 :" -"term:`expression`\\ （運算式），或是含有關鍵字（例如 :keyword:`if`、:keyword:" -"`while` 或 :keyword:`for`\\ ）的多種結構之一。" - -#: ../../glossary.rst:1451 -msgid "static type checker" -msgstr "static type checker（靜態型別檢查器）" - -#: ../../glossary.rst:1453 -msgid "" -"An external tool that reads Python code and analyzes it, looking for issues " -"such as incorrect types. See also :term:`type hints ` and the :" -"mod:`typing` module." -msgstr "" -"會讀取 Python 程式碼並分析的外部工具，能夠找出錯誤，像是使用了不正確的型別。" -"另請參閱\\ :term:`型別提示 (type hints) ` 以及 :mod:`typing` 模" -"組。" - -#: ../../glossary.rst:1456 -msgid "stdlib" -msgstr "stdlib（標準函式庫）" - -#: ../../glossary.rst:1458 -msgid "An abbreviation of :term:`standard library`." -msgstr ":term:`standard library` 的縮寫。" - -#: ../../glossary.rst:1459 -msgid "strong reference" -msgstr "strong reference（強參照）" - -#: ../../glossary.rst:1461 -msgid "" -"In Python's C API, a strong reference is a reference to an object which is " -"owned by the code holding the reference. The strong reference is taken by " -"calling :c:func:`Py_INCREF` when the reference is created and released with :" -"c:func:`Py_DECREF` when the reference is deleted." -msgstr "" -"在 Python 的 C API 中，強參照是對物件的參照，該物件為持有該參照的程式碼所擁" -"有。建立參照時透過呼叫 :c:func:`Py_INCREF` 來獲得強參照、刪除參照時透過 :c:" -"func:`Py_DECREF` 釋放強參照。" - -#: ../../glossary.rst:1467 -msgid "" -"The :c:func:`Py_NewRef` function can be used to create a strong reference to " -"an object. Usually, the :c:func:`Py_DECREF` function must be called on the " -"strong reference before exiting the scope of the strong reference, to avoid " -"leaking one reference." -msgstr "" -":c:func:`Py_NewRef` 函式可用於建立一個對物件的強參照。通常，在退出強參照的作" -"用域之前，必須在該強參照上呼叫 :c:func:`Py_DECREF` 函式，以避免洩漏一個參照。" - -#: ../../glossary.rst:1472 -msgid "See also :term:`borrowed reference`." -msgstr "另請參閱 :term:`borrowed reference`\\ （借用參照）。" - -#: ../../glossary.rst:1473 -msgid "synchronization primitive" -msgstr "" - -#: ../../glossary.rst:1475 -msgid "" -"A basic building block for coordinating (synchronizing) the execution of " -"multiple threads to ensure :term:`thread-safe` access to shared resources. " -"Python's :mod:`threading` module provides several synchronization primitives " -"including :class:`~threading.Lock`, :class:`~threading.RLock`, :class:" -"`~threading.Semaphore`, :class:`~threading.Condition`, :class:`~threading." -"Event`, and :class:`~threading.Barrier`. Additionally, the :mod:`queue` " -"module provides multi-producer, multi-consumer queues that are especially " -"useful in multithreaded programs. These primitives help prevent :term:`race " -"conditions ` and coordinate thread execution. See also :" -"term:`lock`." -msgstr "" - -#: ../../glossary.rst:1485 -msgid "t-string" -msgstr "t-string（t 字串）" - -#: ../../glossary.rst:1486 -msgid "t-strings" -msgstr "t-strings（t 字串）" - -#: ../../glossary.rst:1488 -msgid "" -"String literals prefixed with ``t`` or ``T`` are commonly called \"t-" -"strings\" which is short for :ref:`template string literals `." -msgstr "" -"以 ``t`` 或 ``T`` 為前綴的字串文本通常被稱為「t 字串」，它是\\ :ref:`模板化的" -"字串文本 `\\ 的縮寫。" - -#: ../../glossary.rst:1491 -msgid "text encoding" -msgstr "text encoding（文字編碼）" - -#: ../../glossary.rst:1493 -msgid "" -"A string in Python is a sequence of Unicode code points (in range " -"``U+0000``--``U+10FFFF``). To store or transfer a string, it needs to be " -"serialized as a sequence of bytes." -msgstr "" -"Python 中的字串是一個 Unicode 編碼位置 (code point) 的序列（範圍在 " -"``U+0000`` -- ``U+10FFFF`` 之間）。若要儲存或傳送一個字串，它必須被序列化為一" -"個位元組序列。" - -#: ../../glossary.rst:1497 -msgid "" -"Serializing a string into a sequence of bytes is known as \"encoding\", and " -"recreating the string from the sequence of bytes is known as \"decoding\"." -msgstr "" -"將一個字串序列化為位元組序列，稱為「編碼」，而從位元組序列重新建立該字串則稱" -"為「解碼 (decoding)」。" - -#: ../../glossary.rst:1500 -msgid "" -"There are a variety of different text serialization :ref:`codecs `, which are collectively referred to as \"text encodings\"." -msgstr "" -"有多種不同的文字序列化編解碼器 (:ref:`codecs `)，它們被統" -"稱為「文字編碼」。" - -#: ../../glossary.rst:1503 -msgid "text file" -msgstr "text file（文字檔案）" - -#: ../../glossary.rst:1505 -msgid "" -"A :term:`file object` able to read and write :class:`str` objects. Often, a " -"text file actually accesses a byte-oriented datastream and handles the :term:" -"`text encoding` automatically. Examples of text files are files opened in " -"text mode (``'r'`` or ``'w'``), :data:`sys.stdin`, :data:`sys.stdout`, and " -"instances of :class:`io.StringIO`." -msgstr "" -"一個能夠讀取和寫入 :class:`str` 物件的一個 :term:`file object`\\ （檔案物" -"件）。通常，文字檔案實際上是存取位元組導向的資料流 (byte-oriented " -"datastream) 並會自動處理 :term:`text encoding`\\ （文字編碼）。文字檔案的例子" -"有：以文字模式（``'r'`` 或 ``'w'``）開啟的檔案、:data:`sys.stdin`、:data:" -"`sys.stdout` 以及 :class:`io.StringIO` 的實例。" - -#: ../../glossary.rst:1512 -msgid "" -"See also :term:`binary file` for a file object able to read and write :term:" -"`bytes-like objects `." -msgstr "" -"另請參閱 :term:`binary file`\\ （二進位檔案），它是一個能夠讀取和寫入\\ :" -"term:`類位元組串物件 (bytes-like object) ` 的檔案物件。" - -#: ../../glossary.rst:1514 -msgid "thread state" -msgstr "" - -#: ../../glossary.rst:1517 -msgid "" -"The information used by the :term:`CPython` runtime to run in an OS thread. " -"For example, this includes the current exception, if any, and the state of " -"the bytecode interpreter." -msgstr "" - -#: ../../glossary.rst:1521 -msgid "" -"Each thread state is bound to a single OS thread, but threads may have many " -"thread states available. At most, one of them may be :term:`attached " -"` at once." -msgstr "" - -#: ../../glossary.rst:1525 -msgid "" -"An :term:`attached thread state` is required to call most of Python's C API, " -"unless a function explicitly documents otherwise. The bytecode interpreter " -"only runs under an attached thread state." -msgstr "" - -#: ../../glossary.rst:1529 -msgid "" -"Each thread state belongs to a single interpreter, but each interpreter may " -"have many thread states, including multiple for the same OS thread. Thread " -"states from multiple interpreters may be bound to the same thread, but only " -"one can be :term:`attached ` in that thread at any " -"given moment." -msgstr "" - -#: ../../glossary.rst:1535 -msgid "" -"See :ref:`Thread State and the Global Interpreter Lock ` for more " -"information." -msgstr "" - -#: ../../glossary.rst:1537 -msgid "thread-safe" -msgstr "" - -#: ../../glossary.rst:1539 -msgid "" -"A module, function, or class that behaves correctly when used by multiple " -"threads concurrently. Thread-safe code uses appropriate :term:" -"`synchronization primitives ` like :term:`locks " -"` to protect shared mutable state, or is designed to avoid shared " -"mutable state entirely. In the :term:`free-threaded ` " -"build, built-in types like :class:`dict`, :class:`list`, and :class:`set` " -"use internal locking to make many operations thread-safe, although thread " -"safety is not necessarily guaranteed. Code that is not thread-safe may " -"experience :term:`race conditions ` and :term:`data races " -"` when used in multi-threaded programs." -msgstr "" - -#: ../../glossary.rst:1550 -msgid "token" -msgstr "token" - -#: ../../glossary.rst:1553 -msgid "" -"A small unit of source code, generated by the :ref:`lexical analyzer " -"` (also called the *tokenizer*). Names, numbers, strings, " -"operators, newlines and similar are represented by tokens." -msgstr "" -"原始碼的小單位，由 :ref:`詞法分析器 ` （也稱為 *tokenizer*）產生。名" -"稱、數字、字串、運算子、換行符號等都以 token 表示。" - -#: ../../glossary.rst:1558 -msgid "" -"The :mod:`tokenize` module exposes Python's lexical analyzer. The :mod:" -"`token` module contains information on the various types of tokens." -msgstr "" -":mod:`tokenize` 模組公開了 Python 的詞法分析器。:mod:`token` 模組包含各種 " -"token 類型的資訊。" - -#: ../../glossary.rst:1561 -msgid "triple-quoted string" -msgstr "triple-quoted string（三引號內字串）" - -#: ../../glossary.rst:1563 -msgid "" -"A string which is bound by three instances of either a quotation mark (\") " -"or an apostrophe ('). While they don't provide any functionality not " -"available with single-quoted strings, they are useful for a number of " -"reasons. They allow you to include unescaped single and double quotes " -"within a string and they can span multiple lines without the use of the " -"continuation character, making them especially useful when writing " -"docstrings." -msgstr "" -"由三個雙引號 (\") 或單引號 (') 的作為邊界的一個字串。雖然它們並沒有提供異於單" -"引號字串的任何額外功能，但基於許多原因，它們仍是很有用的。它們讓你可以在字串" -"中包含未跳脫 (unescaped) 的單引號和雙引號，而且它們不需使用連續字元 " -"(continuation character) 就可以跨越多行，這使得它們在編寫說明字串時特別有用。" - -#: ../../glossary.rst:1570 -msgid "type" -msgstr "type（型別）" - -#: ../../glossary.rst:1572 -msgid "" -"The type of a Python object determines what kind of object it is; every " -"object has a type. An object's type is accessible as its :attr:`~object." -"__class__` attribute or can be retrieved with ``type(obj)``." -msgstr "" -"一個 Python 物件的型別決定了它是什麼類型的物件；每個物件都有一個型別。一個物" -"件的型別可以用它的 :attr:`~object.__class__` 屬性來存取，或以 ``type(obj)`` " -"來檢索。" - -#: ../../glossary.rst:1576 -msgid "type alias" -msgstr "type alias（型別別名）" - -#: ../../glossary.rst:1578 -msgid "A synonym for a type, created by assigning the type to an identifier." -msgstr "一個型別的同義詞，透過將型別指定給一個識別符 (identifier) 來建立。" - -#: ../../glossary.rst:1580 -msgid "" -"Type aliases are useful for simplifying :term:`type hints `. For " -"example::" -msgstr "" -"型別別名對於簡化\\ :term:`型別提示 (type hint) ` 很有用。例如： ::" - -#: ../../glossary.rst:1583 -msgid "" -"def remove_gray_shades(\n" -" colors: list[tuple[int, int, int]]) -> list[tuple[int, int, int]]:\n" -" pass" -msgstr "" -"def remove_gray_shades(\n" -" colors: list[tuple[int, int, int]]) -> list[tuple[int, int, int]]:\n" -" pass" - -#: ../../glossary.rst:1587 -msgid "could be made more readable like this::" -msgstr "可以寫成這樣，更具有可讀性： ::" - -#: ../../glossary.rst:1589 -msgid "" -"Color = tuple[int, int, int]\n" -"\n" -"def remove_gray_shades(colors: list[Color]) -> list[Color]:\n" -" pass" -msgstr "" -"Color = tuple[int, int, int]\n" -"\n" -"def remove_gray_shades(colors: list[Color]) -> list[Color]:\n" -" pass" - -#: ../../glossary.rst:1594 ../../glossary.rst:1608 -msgid "See :mod:`typing` and :pep:`484`, which describe this functionality." -msgstr "請參閱 :mod:`typing` 和 :pep:`484`，有此功能的描述。" - -#: ../../glossary.rst:1595 -msgid "type hint" -msgstr "type hint（型別提示）" - -#: ../../glossary.rst:1597 -msgid "" -"An :term:`annotation` that specifies the expected type for a variable, a " -"class attribute, or a function parameter or return value." -msgstr "" -"一種 :term:`annotation`\\ （註釋），它指定一個變數、一個 class 屬性或一個函式" -"的參數或回傳值的預期型別。" - -#: ../../glossary.rst:1600 -msgid "" -"Type hints are optional and are not enforced by Python but they are useful " -"to :term:`static type checkers `. They can also aid " -"IDEs with code completion and refactoring." -msgstr "" -"型別提示是選擇性的，而不是被 Python 強制的，但它們對\\ :term:`靜態型別檢查器 " -"(static type checkers) `\\ 很有用，並能協助 IDE 完成程式" -"碼的補全 (completion) 和重構 (refactoring)。" - -#: ../../glossary.rst:1604 -msgid "" -"Type hints of global variables, class attributes, and functions, but not " -"local variables, can be accessed using :func:`typing.get_type_hints`." -msgstr "" -"全域變數、class 屬性和函式（不含區域變數）的型別提示，都可以使用 :func:" -"`typing.get_type_hints` 來存取。" - -#: ../../glossary.rst:1609 -msgid "universal newlines" -msgstr "universal newlines（通用換行字元）" - -#: ../../glossary.rst:1611 -msgid "" -"A manner of interpreting text streams in which all of the following are " -"recognized as ending a line: the Unix end-of-line convention ``'\\n'``, the " -"Windows convention ``'\\r\\n'``, and the old Macintosh convention " -"``'\\r'``. See :pep:`278` and :pep:`3116`, as well as :func:`bytes." -"splitlines` for an additional use." -msgstr "" -"一種解譯文字流 (text stream) 的方式，會將以下所有的情況識別為一行的結束：" -"Unix 行尾慣例 ``'\\n'``、Windows 慣例 ``'\\r\\n'`` 和舊的 Macintosh 慣例 " -"``'\\r'``。請參閱 :pep:`278` 和 :pep:`3116`，以及用於 :func:`bytes." -"splitlines` 的附加用途。" - -#: ../../glossary.rst:1616 -msgid "variable annotation" -msgstr "variable annotation（變數註釋）" - -#: ../../glossary.rst:1618 -msgid "An :term:`annotation` of a variable or a class attribute." -msgstr "一個變數或 class 屬性的 :term:`annotation`\\ （註釋）。" - -#: ../../glossary.rst:1620 -msgid "" -"When annotating a variable or a class attribute, assignment is optional::" -msgstr "註釋變數或 class 屬性時，賦值是選擇性的： ::" - -#: ../../glossary.rst:1622 -msgid "" -"class C:\n" -" field: 'annotation'" -msgstr "" -"class C:\n" -" field: 'annotation'" - -#: ../../glossary.rst:1625 -msgid "" -"Variable annotations are usually used for :term:`type hints `: " -"for example this variable is expected to take :class:`int` values::" -msgstr "" -"變數註釋通常用於\\ :term:`型別提示 (type hint) `：例如，這個變數預" -"期會取得 :class:`int`\\ （整數）值： ::" - -#: ../../glossary.rst:1629 -msgid "count: int = 0" -msgstr "count: int = 0" - -#: ../../glossary.rst:1631 -msgid "Variable annotation syntax is explained in section :ref:`annassign`." -msgstr "變數註釋的語法在\\ :ref:`annassign`\\ 章節有詳細的解釋。" - -#: ../../glossary.rst:1633 -msgid "" -"See :term:`function annotation`, :pep:`484` and :pep:`526`, which describe " -"this functionality. Also see :ref:`annotations-howto` for best practices on " -"working with annotations." -msgstr "" -"請參閱 :term:`function annotation`\\ （函式註釋）、:pep:`484` 和 :pep:`526`，" -"皆有此功能的描述。關於註釋的最佳實踐方法，另請參閱 :ref:`annotations-howto`。" - -#: ../../glossary.rst:1637 -msgid "virtual environment" -msgstr "virtual environment（虛擬環境）" - -#: ../../glossary.rst:1639 -msgid "" -"A cooperatively isolated runtime environment that allows Python users and " -"applications to install and upgrade Python distribution packages without " -"interfering with the behaviour of other Python applications running on the " -"same system." -msgstr "" -"一個協作隔離 (cooperatively isolated) 的執行環境，能讓 Python 的使用者和應用" -"程式得以安裝和升級 Python 發佈套件，而不會對同一個系統上運行的其他 Python 應" -"用程式的行為產生干擾。" - -#: ../../glossary.rst:1644 -msgid "See also :mod:`venv`." -msgstr "另請參閱 :mod:`venv`。" - -#: ../../glossary.rst:1645 -msgid "virtual machine" -msgstr "virtual machine（虛擬機器）" - -#: ../../glossary.rst:1647 -msgid "" -"A computer defined entirely in software. Python's virtual machine executes " -"the :term:`bytecode` emitted by the bytecode compiler." -msgstr "" -"一部完全由軟體所定義的電腦 (computer)。Python 的虛擬機器會執行由 :term:" -"`bytecode`\\ （位元組碼）編譯器所發出的位元組碼。" - -#: ../../glossary.rst:1649 -msgid "walrus operator" -msgstr "walrus operator（海象運算子）" - -#: ../../glossary.rst:1651 -msgid "" -"A light-hearted way to refer to the :ref:`assignment expression ` operator ``:=`` because it looks a bit like a walrus if you " -"turn your head." -msgstr "" - -#: ../../glossary.rst:1654 -msgid "Zen of Python" -msgstr "Zen of Python（Python 之禪）" - -#: ../../glossary.rst:1656 -msgid "" -"Listing of Python design principles and philosophies that are helpful in " -"understanding and using the language. The listing can be found by typing " -"\"``import this``\" at the interactive prompt." -msgstr "" -"Python 設計原則與哲學的列表，其內容有助於理解和使用此語言。此列表可以透過在互" -"動式提式字元後輸入「``import this``」來找到它。" - -#: ../../glossary.rst:24 -msgid "..." -msgstr "..." - -#: ../../glossary.rst:24 -msgid "ellipsis literal" -msgstr "刪節號字面值" - -#: ../../glossary.rst:345 -msgid "C-contiguous" -msgstr "C-contiguous（C 連續的）" - -#: ../../glossary.rst:345 -msgid "Fortran contiguous" -msgstr "Fortran contiguous（Fortran 連續的）" - -#: ../../glossary.rst:955 -msgid "magic" -msgstr "magic" - -#: ../../glossary.rst:1430 -msgid "special" -msgstr "special" - -#~ msgid "" -#~ "Mutable objects can change their value but keep their :func:`id`. See " -#~ "also :term:`immutable`." -#~ msgstr "" -#~ "可變物件可以改變它們的值，但維持它們的 :func:`id`。另請參閱 :term:" -#~ "`immutable`\\ （不可變物件）。" - -#~ msgid "The :const:`Ellipsis` built-in constant." -#~ msgstr "內建常數 :const:`Ellipsis`。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# Translators: +# Steven Hsu , 2021-2022 +# Matt Wang , 2021 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-12-17 17:02+0000\n" +"PO-Revision-Date: 2023-07-02 22:47+0800\n" +"Last-Translator: Matt Wang \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" +"X-Generator: Poedit 3.3.2\n" + +#: ../../glossary.rst:5 +msgid "Glossary" +msgstr "術語表" + +#: ../../glossary.rst:10 +msgid "``>>>``" +msgstr "``>>>``" + +#: ../../glossary.rst:12 +msgid "" +"The default Python prompt of the :term:`interactive` shell. Often seen for " +"code examples which can be executed interactively in the interpreter." +msgstr "" +":term:`互動式 ` shell 的預設 Python 提示字元。常見於能在直譯器中" +"以互動方式被執行的程式碼範例。" + +#: ../../glossary.rst:15 +msgid "``...``" +msgstr "``...``" + +#: ../../glossary.rst:17 +msgid "Can refer to:" +msgstr "可以表示：" + +#: ../../glossary.rst:19 +msgid "" +"The default Python prompt of the :term:`interactive` shell when entering the " +"code for an indented code block, when within a pair of matching left and " +"right delimiters (parentheses, square brackets, curly braces or triple " +"quotes), or after specifying a decorator." +msgstr "" +"在一個被縮排的程式碼區塊、在一對匹配的左右定界符（delimiter，例如括號、方括" +"號、花括號或三引號）內部，或是在指定一個裝飾器 (decorator) 之後，要輸入程式碼" +"時，:term:`互動式 ` shell 顯示的預設 Python 提示字元。" + +#: ../../glossary.rst:26 +msgid "" +"The three dots form of the :ref:`Ellipsis ` object." +msgstr "" + +#: ../../glossary.rst:27 +msgid "abstract base class" +msgstr "abstract base class（抽象基底類別）" + +#: ../../glossary.rst:29 +msgid "" +"Abstract base classes complement :term:`duck-typing` by providing a way to " +"define interfaces when other techniques like :func:`hasattr` would be clumsy " +"or subtly wrong (for example with :ref:`magic methods `). " +"ABCs introduce virtual subclasses, which are classes that don't inherit from " +"a class but are still recognized by :func:`isinstance` and :func:" +"`issubclass`; see the :mod:`abc` module documentation. Python comes with " +"many built-in ABCs for data structures (in the :mod:`collections.abc` " +"module), numbers (in the :mod:`numbers` module), streams (in the :mod:`io` " +"module), import finders and loaders (in the :mod:`importlib.abc` module). " +"You can create your own ABCs with the :mod:`abc` module." +msgstr "" +"抽象基底類別（又稱為 ABC）提供了一種定義介面的方法，作為 :term:`duck-" +"typing`\\ （鴨子型別）的補充。其他類似的技術，像是 :func:`hasattr`，則顯得笨" +"拙或是帶有細微的錯誤（例如使用\\ :ref:`魔術方法 (magic method) `\\ ）。ABC 採用虛擬的 subclass（子類別），它們並不繼承自另一個 class" +"（類別），但仍可被 :func:`isinstance` 及 :func:`issubclass` 辨識；請參閱 :" +"mod:`abc` 模組的說明文件。Python 有許多內建的 ABC，用於資料結構（在 :mod:" +"`collections.abc` 模組）、數字（在 :mod:`numbers` 模組）、串流（在 :mod:`io` " +"模組）及 import 尋檢器和載入器（在 :mod:`importlib.abc` 模組）。你可以使用 :" +"mod:`abc` 模組建立自己的 ABC。" + +#: ../../glossary.rst:40 +msgid "annotate function" +msgstr "annotate function（註釋函式）" + +#: ../../glossary.rst:42 +msgid "" +"A function that can be called to retrieve the :term:`annotations " +"` of an object. This function is accessible as the :attr:" +"`~object.__annotate__` attribute of functions, classes, and modules. " +"Annotate functions are a subset of :term:`evaluate functions `." +msgstr "" + +#: ../../glossary.rst:46 +msgid "annotation" +msgstr "annotation（註釋）" + +#: ../../glossary.rst:48 +msgid "" +"A label associated with a variable, a class attribute or a function " +"parameter or return value, used by convention as a :term:`type hint`." +msgstr "" +"一個與變數、class 屬性、函式的參數或回傳值相關聯的標籤。照慣例，它被用來作" +"為 :term:`type hint`\\ （型別提示）。" + +#: ../../glossary.rst:52 +msgid "" +"Annotations of local variables cannot be accessed at runtime, but " +"annotations of global variables, class attributes, and functions can be " +"retrieved by calling :func:`annotationlib.get_annotations` on modules, " +"classes, and functions, respectively." +msgstr "" +"在 runtime 的區域變數註釋無法被存取，但全域變數、類別屬性和函式的註釋，分別能" +"夠以對模組、類別和函式呼叫 :func:`annotationlib.get_annotations` 來取得。" + +#: ../../glossary.rst:57 +msgid "" +"See :term:`variable annotation`, :term:`function annotation`, :pep:`484`, :" +"pep:`526`, and :pep:`649`, which describe this functionality. Also see :ref:" +"`annotations-howto` for best practices on working with annotations." +msgstr "" +"請參閱 :term:`variable annotation`、:term:`function annotation`、:pep:" +"`484`、:pep:`526` 和 :pep:`649`，這些章節皆有此功能的說明。關於註釋的最佳實踐" +"方法也請參閱 :ref:`annotations-howto`。" + +#: ../../glossary.rst:61 +msgid "argument" +msgstr "argument（引數）" + +#: ../../glossary.rst:63 +msgid "" +"A value passed to a :term:`function` (or :term:`method`) when calling the " +"function. There are two kinds of argument:" +msgstr "" +"呼叫函式時被傳遞給 :term:`function`\\ （或 :term:`method`\\ ）的值。引數有兩" +"種：" + +#: ../../glossary.rst:66 +msgid "" +":dfn:`keyword argument`: an argument preceded by an identifier (e.g. " +"``name=``) in a function call or passed as a value in a dictionary preceded " +"by ``**``. For example, ``3`` and ``5`` are both keyword arguments in the " +"following calls to :func:`complex`::" +msgstr "" +":dfn:`關鍵字引數 (keyword argument)`：在函式呼叫中，以識別字（identifier，例" +"如 ``name=``\\ ）開頭的引數，或是以 ``**`` 後面 dictionary（字典）內的值被傳" +"遞的引數。例如，``3`` 和 ``5`` 都是以下 :func:`complex` 呼叫中的關鍵字引" +"數： ::" + +#: ../../glossary.rst:71 +msgid "" +"complex(real=3, imag=5)\n" +"complex(**{'real': 3, 'imag': 5})" +msgstr "" +"complex(real=3, imag=5)\n" +"complex(**{'real': 3, 'imag': 5})" + +#: ../../glossary.rst:74 +msgid "" +":dfn:`positional argument`: an argument that is not a keyword argument. " +"Positional arguments can appear at the beginning of an argument list and/or " +"be passed as elements of an :term:`iterable` preceded by ``*``. For example, " +"``3`` and ``5`` are both positional arguments in the following calls::" +msgstr "" +":dfn:`位置引數 (positional argument)`：不是關鍵字引數的引數。位置引數可在一個" +"引數列表的起始處出現，和（或）作為 ``*`` 之後的 :term:`iterable`\\ （可疊代物" +"件）中的元素被傳遞。例如，``3`` 和 ``5`` 都是以下呼叫中的位置引數： ::" + +#: ../../glossary.rst:80 +msgid "" +"complex(3, 5)\n" +"complex(*(3, 5))" +msgstr "" +"complex(3, 5)\n" +"complex(*(3, 5))" + +#: ../../glossary.rst:83 +msgid "" +"Arguments are assigned to the named local variables in a function body. See " +"the :ref:`calls` section for the rules governing this assignment. " +"Syntactically, any expression can be used to represent an argument; the " +"evaluated value is assigned to the local variable." +msgstr "" +"引數會被指定給函式主體中的附名區域變數。關於支配這個指定過程的規則，請參閱" +"\\ :ref:`calls`\\ 章節。在語法上，任何運算式都可以被用來表示一個引數；其評估" +"值會被指定給區域變數。" + +#: ../../glossary.rst:88 +msgid "" +"See also the :term:`parameter` glossary entry, the FAQ question on :ref:`the " +"difference between arguments and parameters `, " +"and :pep:`362`." +msgstr "" +"另請參閱術語表的 :term:`parameter`\\ （參數）條目、常見問題中的\\ :ref:`引數" +"和參數之間的差異 `，以及 :pep:`362`。" + +#: ../../glossary.rst:91 +msgid "asynchronous context manager" +msgstr "asynchronous context manager（非同步情境管理器）" + +#: ../../glossary.rst:93 +msgid "" +"An object which controls the environment seen in an :keyword:`async with` " +"statement by defining :meth:`~object.__aenter__` and :meth:`~object." +"__aexit__` methods. Introduced by :pep:`492`." +msgstr "" +"一個可以控制 :keyword:`async with` 陳述式中所見環境的物件，而它是透過定義 :" +"meth:`~object.__aenter__` 和 :meth:`~object.__aexit__` method（方法）來控制" +"的。由 :pep:`492` 引入。" + +#: ../../glossary.rst:96 +msgid "asynchronous generator" +msgstr "asynchronous generator（非同步產生器）" + +#: ../../glossary.rst:98 +msgid "" +"A function which returns an :term:`asynchronous generator iterator`. It " +"looks like a coroutine function defined with :keyword:`async def` except " +"that it contains :keyword:`yield` expressions for producing a series of " +"values usable in an :keyword:`async for` loop." +msgstr "" +"一個會回傳 :term:`asynchronous generator iterator`\\ （非同步產生器疊代器）的" +"函式。它看起來像一個以 :keyword:`async def` 定義的協程函式 (coroutine " +"function)，但不同的是它包含了 :keyword:`yield` 運算式，能生成一系列可用於 :" +"keyword:`async for` 迴圈的值。" + +#: ../../glossary.rst:103 +msgid "" +"Usually refers to an asynchronous generator function, but may refer to an " +"*asynchronous generator iterator* in some contexts. In cases where the " +"intended meaning isn't clear, using the full terms avoids ambiguity." +msgstr "" +"這個術語通常用來表示一個非同步產生器函式，但在某些情境中，也可能是表示\\ *非" +"同步產生器疊代器 (asynchronous generator iterator)*。萬一想表達的意思不夠清" +"楚，那就使用完整的術語，以避免歧義。" + +#: ../../glossary.rst:107 +msgid "" +"An asynchronous generator function may contain :keyword:`await` expressions " +"as well as :keyword:`async for`, and :keyword:`async with` statements." +msgstr "" +"一個非同步產生器函式可能包含 :keyword:`await` 運算式，以及 :keyword:`async " +"for` 和 :keyword:`async with` 陳述式。" + +#: ../../glossary.rst:110 +msgid "asynchronous generator iterator" +msgstr "asynchronous generator iterator（非同步產生器疊代器）" + +#: ../../glossary.rst:112 +msgid "An object created by an :term:`asynchronous generator` function." +msgstr "" +"一個由 :term:`asynchronous generator`\\ （非同步產生器）函式所建立的物件。" + +#: ../../glossary.rst:114 +msgid "" +"This is an :term:`asynchronous iterator` which when called using the :meth:" +"`~object.__anext__` method returns an awaitable object which will execute " +"the body of the asynchronous generator function until the next :keyword:" +"`yield` expression." +msgstr "" +"這是一個 :term:`asynchronous iterator`\\ （非同步疊代器），當它以 :meth:" +"`~object.__anext__` method 被呼叫時，會回傳一個可等待物件 (awaitable " +"object)，該物件將執行非同步產生器的函式主體，直到遇到下一個 :keyword:`yield` " +"運算式。" + +#: ../../glossary.rst:119 +msgid "" +"Each :keyword:`yield` temporarily suspends processing, remembering the " +"execution state (including local variables and pending try-statements). " +"When the *asynchronous generator iterator* effectively resumes with another " +"awaitable returned by :meth:`~object.__anext__`, it picks up where it left " +"off. See :pep:`492` and :pep:`525`." +msgstr "" +"每個 :keyword:`yield` 會暫停處理程序，並記住執行狀態（包括區域變數及擱置中的 " +"try 陳述式）。當\\ *非同步產生器疊代器*\\ 以另一個被 :meth:`~object." +"__anext__` 回傳的可等待物件有效地回復時，它會從停止的地方繼續執行。請參閱 :" +"pep:`492` 和 :pep:`525`。" + +#: ../../glossary.rst:124 +msgid "asynchronous iterable" +msgstr "asynchronous iterable（非同步可疊代物件）" + +#: ../../glossary.rst:126 +msgid "" +"An object, that can be used in an :keyword:`async for` statement. Must " +"return an :term:`asynchronous iterator` from its :meth:`~object.__aiter__` " +"method. Introduced by :pep:`492`." +msgstr "" +"一個物件，它可以在 :keyword:`async for` 陳述式中被使用。必須從它的 :meth:" +"`~object.__aiter__` method 回傳一個 :term:`asynchronous iterator`\\ （非同步" +"疊代器）。由 :pep:`492` 引入。" + +#: ../../glossary.rst:129 +msgid "asynchronous iterator" +msgstr "asynchronous iterator（非同步疊代器）" + +#: ../../glossary.rst:131 +msgid "" +"An object that implements the :meth:`~object.__aiter__` and :meth:`~object." +"__anext__` methods. :meth:`~object.__anext__` must return an :term:" +"`awaitable` object. :keyword:`async for` resolves the awaitables returned by " +"an asynchronous iterator's :meth:`~object.__anext__` method until it raises " +"a :exc:`StopAsyncIteration` exception. Introduced by :pep:`492`." +msgstr "" +"一個實作 :meth:`~object.__aiter__` 和 :meth:`~object.__anext__` method 的物" +"件。:meth:`~object.__anext__` 必須回傳一個 :term:`awaitable`\\ （可等待物" +"件）。:keyword:`async for` 會解析非同步疊代器的 :meth:`~object.__anext__` " +"method 所回傳的可等待物件，直到它引發 :exc:`StopAsyncIteration` 例外。由 :" +"pep:`492` 引入。" + +#: ../../glossary.rst:136 +msgid "atomic operation" +msgstr "" + +#: ../../glossary.rst:138 +msgid "" +"An operation that appears to execute as a single, indivisible step: no other " +"thread can observe it half-done, and its effects become visible all at " +"once. Python does not guarantee that high-level statements are atomic (for " +"example, ``x += 1`` performs multiple bytecode operations and is not " +"atomic). Atomicity is only guaranteed where explicitly documented. See " +"also :term:`race condition` and :term:`data race`." +msgstr "" + +#: ../../glossary.rst:144 +msgid "attached thread state" +msgstr "" + +#: ../../glossary.rst:147 +msgid "A :term:`thread state` that is active for the current OS thread." +msgstr "" + +#: ../../glossary.rst:149 +msgid "" +"When a :term:`thread state` is attached, the OS thread has access to the " +"full Python C API and can safely invoke the bytecode interpreter." +msgstr "" + +#: ../../glossary.rst:153 +msgid "" +"Unless a function explicitly notes otherwise, attempting to call the C API " +"without an attached thread state will result in a fatal error or undefined " +"behavior. A thread state can be attached and detached explicitly by the " +"user through the C API, or implicitly by the runtime, including during " +"blocking C calls and by the bytecode interpreter in between calls." +msgstr "" + +#: ../../glossary.rst:160 +msgid "" +"On most builds of Python, having an attached thread state implies that the " +"caller holds the :term:`GIL` for the current interpreter, so only one OS " +"thread can have an attached thread state at a given moment. In :term:`free-" +"threaded ` builds of Python, threads can concurrently hold " +"an attached thread state, allowing for true parallelism of the bytecode " +"interpreter." +msgstr "" + +#: ../../glossary.rst:166 +msgid "attribute" +msgstr "attribute（屬性）" + +#: ../../glossary.rst:168 +msgid "" +"A value associated with an object which is usually referenced by name using " +"dotted expressions. For example, if an object *o* has an attribute *a* it " +"would be referenced as *o.a*." +msgstr "" +"一個與某物件相關聯的值，該值大多能透過使用點分隔運算式 (dotted expression) 的" +"名稱被參照。例如，如果物件 *o* 有一個屬性 *a*，則該屬性能以 *o.a* 被參照。" + +#: ../../glossary.rst:173 +msgid "" +"It is possible to give an object an attribute whose name is not an " +"identifier as defined by :ref:`identifiers`, for example using :func:" +"`setattr`, if the object allows it. Such an attribute will not be accessible " +"using a dotted expression, and would instead need to be retrieved with :func:" +"`getattr`." +msgstr "" +"如果一個物件允許，給予該物件一個名稱不是由\\ :ref:`identifiers`\\ 所定義之識" +"別符 (identifier) 的屬性是有可能的，例如使用 :func:`setattr`。像這樣的屬性將" +"無法使用點分隔運算式來存取，而是需要使用 :func:`getattr` 來取得它。" + +#: ../../glossary.rst:178 +msgid "awaitable" +msgstr "awaitable（可等待物件）" + +#: ../../glossary.rst:180 +msgid "" +"An object that can be used in an :keyword:`await` expression. Can be a :" +"term:`coroutine` or an object with an :meth:`~object.__await__` method. See " +"also :pep:`492`." +msgstr "" +"一個可以在 :keyword:`await` 運算式中被使用的物件。它可以是一個 :term:" +"`coroutine`\\ （協程），或是一個有 :meth:`~object.__await__` method 的物件。" +"另請參閱 :pep:`492`。" + +#: ../../glossary.rst:183 +msgid "BDFL" +msgstr "BDFL" + +#: ../../glossary.rst:185 +msgid "" +"Benevolent Dictator For Life, a.k.a. `Guido van Rossum `_, Python's creator." +msgstr "" +"Benevolent Dictator For Life（終身仁慈獨裁者），又名 `Guido van Rossum " +"`_，Python 的創造者。" + +#: ../../glossary.rst:187 +msgid "binary file" +msgstr "binary file（二進位檔案）" + +#: ../../glossary.rst:189 +msgid "" +"A :term:`file object` able to read and write :term:`bytes-like objects " +"`. Examples of binary files are files opened in binary " +"mode (``'rb'``, ``'wb'`` or ``'rb+'``), :data:`sys.stdin.buffer `, :data:`sys.stdout.buffer `, and instances of :class:`io." +"BytesIO` and :class:`gzip.GzipFile`." +msgstr "" +"一個能夠讀取和寫入 :term:`bytes-like objects `\\ （類位元" +"組串物件）的 :term:`file object`\\ （檔案物件）。二進位檔案的例子有：以二進位" +"模式（``'rb'``、``'wb'`` 或 ``'rb+'``）開啟的檔案、:data:`sys.stdin.buffer " +"`、:data:`sys.stdout.buffer `，以及 :class:`io." +"BytesIO` 和 :class:`gzip.GzipFile` 實例。" + +#: ../../glossary.rst:196 +msgid "" +"See also :term:`text file` for a file object able to read and write :class:" +"`str` objects." +msgstr "" +"另請參閱 :term:`text file`\\ （文字檔案），它是一個能夠讀取和寫入 :class:" +"`str` 物件的檔案物件。" + +#: ../../glossary.rst:198 +msgid "borrowed reference" +msgstr "borrowed reference（借用參照）" + +#: ../../glossary.rst:200 +msgid "" +"In Python's C API, a borrowed reference is a reference to an object, where " +"the code using the object does not own the reference. It becomes a dangling " +"pointer if the object is destroyed. For example, a garbage collection can " +"remove the last :term:`strong reference` to the object and so destroy it." +msgstr "" +"在 Python 的 C API 中，借用參照是一個對物件的參照，其中使用該物件的程式碼並不" +"擁有這個參照。如果該物件被銷毀，它會成為一個迷途指標 (dangling pointer)。例" +"如，一次垃圾回收 (garbage collection) 可以移除對物件的最後一個 :term:`strong " +"reference`\\ （強參照），而將該物件銷毀。" + +#: ../../glossary.rst:206 +msgid "" +"Calling :c:func:`Py_INCREF` on the :term:`borrowed reference` is recommended " +"to convert it to a :term:`strong reference` in-place, except when the object " +"cannot be destroyed before the last usage of the borrowed reference. The :c:" +"func:`Py_NewRef` function can be used to create a new :term:`strong " +"reference`." +msgstr "" +"對 :term:`borrowed reference` 呼叫 :c:func:`Py_INCREF` 以將它原地 (in-place) " +"轉換為 :term:`strong reference` 是被建議的做法，除非該物件不能在最後一次使用" +"借用參照之前被銷毀。:c:func:`Py_NewRef` 函式可用於建立一個新的 :term:`strong " +"reference`。" + +#: ../../glossary.rst:211 +msgid "bytes-like object" +msgstr "bytes-like object（類位元組串物件）" + +#: ../../glossary.rst:213 +msgid "" +"An object that supports the :ref:`bufferobjects` and can export a C-:term:" +"`contiguous` buffer. This includes all :class:`bytes`, :class:`bytearray`, " +"and :class:`array.array` objects, as well as many common :class:`memoryview` " +"objects. Bytes-like objects can be used for various operations that work " +"with binary data; these include compression, saving to a binary file, and " +"sending over a socket." +msgstr "" +"一個支援\\ :ref:`bufferobjects`\\ 且能夠匯出 C-:term:`contiguous` 緩衝區的物" +"件。這包括所有的 :class:`bytes`、:class:`bytearray` 和 :class:`array.array` " +"物件，以及許多常見的 :class:`memoryview` 物件。類位元組串物件可用於處理二進位" +"資料的各種運算；這些運算包括壓縮、儲存至二進位檔案和透過 socket（插座）發送。" + +#: ../../glossary.rst:220 +msgid "" +"Some operations need the binary data to be mutable. The documentation often " +"refers to these as \"read-write bytes-like objects\". Example mutable " +"buffer objects include :class:`bytearray` and a :class:`memoryview` of a :" +"class:`bytearray`. Other operations require the binary data to be stored in " +"immutable objects (\"read-only bytes-like objects\"); examples of these " +"include :class:`bytes` and a :class:`memoryview` of a :class:`bytes` object." +msgstr "" +"有些運算需要二進位資料是可變的。說明文件通常會將這些物件稱為「可讀寫的類位元" +"組串物件」。可變緩衝區的物件包括 :class:`bytearray`，以及 :class:`bytearray` " +"的 :class:`memoryview`。其他的運算需要讓二進位資料被儲存在不可變物件（「唯讀" +"的類位元組串物件」）中；這些物件包括 :class:`bytes`，以及 :class:`bytes` 物件" +"的 :class:`memoryview`。" + +#: ../../glossary.rst:228 +msgid "bytecode" +msgstr "bytecode（位元組碼）" + +#: ../../glossary.rst:230 +msgid "" +"Python source code is compiled into bytecode, the internal representation of " +"a Python program in the CPython interpreter. The bytecode is also cached in " +"``.pyc`` files so that executing the same file is faster the second time " +"(recompilation from source to bytecode can be avoided). This \"intermediate " +"language\" is said to run on a :term:`virtual machine` that executes the " +"machine code corresponding to each bytecode. Do note that bytecodes are not " +"expected to work between different Python virtual machines, nor to be stable " +"between Python releases." +msgstr "" +"Python 的原始碼會被編譯成位元組碼，它是 Python 程式在 CPython 直譯器中的內部" +"表示法。該位元組碼也會被暫存在 ``.pyc`` 檔案中，以便第二次執行同一個檔案時能" +"夠更快速（可以不用從原始碼重新編譯為位元組碼）。這種「中間語言 (intermediate " +"language)」據說是運行在一個 :term:`virtual machine`\\ （虛擬機器）上，該虛擬" +"機器會執行與每個位元組碼對應的機器碼 (machine code)。要注意的是，位元組碼理論" +"上是無法在不同的 Python 虛擬機器之間運作的，也不能在不同版本的 Python 之間保" +"持穩定。" + +#: ../../glossary.rst:240 +msgid "" +"A list of bytecode instructions can be found in the documentation for :ref:" +"`the dis module `." +msgstr "" +"位元組碼的指令列表可以在 :ref:`dis 模組 `\\ 的說明文件中找到。" + +#: ../../glossary.rst:242 +msgid "callable" +msgstr "callable（可呼叫物件）" + +#: ../../glossary.rst:244 +msgid "" +"A callable is an object that can be called, possibly with a set of arguments " +"(see :term:`argument`), with the following syntax::" +msgstr "" +"一個 callable 是可以被呼叫的物件，呼叫時可能以下列形式帶有一組引數（請見 :" +"term:`argument`）： ::" + +#: ../../glossary.rst:247 +msgid "callable(argument1, argument2, argumentN)" +msgstr "callable(argument1, argument2, argumentN)" + +#: ../../glossary.rst:249 +msgid "" +"A :term:`function`, and by extension a :term:`method`, is a callable. An " +"instance of a class that implements the :meth:`~object.__call__` method is " +"also a callable." +msgstr "" +"一個 :term:`function` 與其延伸的 :term:`method` 都是 callable。一個有實作 :" +"meth:`~object.__call__` 方法的 class 之實例也是個 callable。" + +#: ../../glossary.rst:252 +msgid "callback" +msgstr "callback（回呼）" + +#: ../../glossary.rst:254 +msgid "" +"A subroutine function which is passed as an argument to be executed at some " +"point in the future." +msgstr "" +"作為引數被傳遞的一個副程式 (subroutine) 函式，會在未來的某個時間點被執行。" + +#: ../../glossary.rst:256 +msgid "class" +msgstr "class（類別）" + +#: ../../glossary.rst:258 +msgid "" +"A template for creating user-defined objects. Class definitions normally " +"contain method definitions which operate on instances of the class." +msgstr "" +"一個用於建立使用者定義物件的模板。Class 的定義通常會包含 method 的定義，這些 " +"method 可以在 class 的實例上進行操作。" + +#: ../../glossary.rst:261 +msgid "class variable" +msgstr "class variable（類別變數）" + +#: ../../glossary.rst:263 +msgid "" +"A variable defined in a class and intended to be modified only at class " +"level (i.e., not in an instance of the class)." +msgstr "" +"一個在 class 中被定義，且應該只能在 class 層次（意即不是在 class 的實例中）被" +"修改的變數。" + +#: ../../glossary.rst:265 +msgid "closure variable" +msgstr "closure variable（閉包變數）" + +#: ../../glossary.rst:267 +msgid "" +"A :term:`free variable` referenced from a :term:`nested scope` that is " +"defined in an outer scope rather than being resolved at runtime from the " +"globals or builtin namespaces. May be explicitly defined with the :keyword:" +"`nonlocal` keyword to allow write access, or implicitly defined if the " +"variable is only being read." +msgstr "" +"從外部作用域中定義且從\\ :term:`巢狀作用域 `\\ 參照的\\ :term:`" +"自由變數 `，不是於 runtime 從全域或內建命名空間解析。可以使" +"用 :keyword:`nonlocal` 關鍵字明確定義以允許寫入存取，或者如果僅需讀取變數則隱" +"式定義即可。" + +#: ../../glossary.rst:272 +msgid "" +"For example, in the ``inner`` function in the following code, both ``x`` and " +"``print`` are :term:`free variables `, but only ``x`` is a " +"*closure variable*::" +msgstr "" +"例如在下面程式碼中的 ``inner`` 函式中，``x`` 和 ``print`` 都是\\ :term:`自由" +"變數 `，但只有 ``x`` 是\\ *閉包變數*： ::" + +#: ../../glossary.rst:275 +msgid "" +"def outer():\n" +" x = 0\n" +" def inner():\n" +" nonlocal x\n" +" x += 1\n" +" print(x)\n" +" return inner" +msgstr "" +"def outer():\n" +" x = 0\n" +" def inner():\n" +" nonlocal x\n" +" x += 1\n" +" print(x)\n" +" return inner" + +#: ../../glossary.rst:283 +msgid "" +"Due to the :attr:`codeobject.co_freevars` attribute (which, despite its " +"name, only includes the names of closure variables rather than listing all " +"referenced free variables), the more general :term:`free variable` term is " +"sometimes used even when the intended meaning is to refer specifically to " +"closure variables." +msgstr "" +"由於 :attr:`codeobject.co_freevars` 屬性（儘管名稱如此，但它僅包含閉包變數的" +"名稱，而不是列出所有參照的自由變數），當預期含義是特指閉包變數時，有時候甚至" +"也會使用更通用的\\ :term:`自由變數 `\\ 一詞。" + +#: ../../glossary.rst:287 +msgid "complex number" +msgstr "complex number（複數）" + +#: ../../glossary.rst:289 +msgid "" +"An extension of the familiar real number system in which all numbers are " +"expressed as a sum of a real part and an imaginary part. Imaginary numbers " +"are real multiples of the imaginary unit (the square root of ``-1``), often " +"written ``i`` in mathematics or ``j`` in engineering. Python has built-in " +"support for complex numbers, which are written with this latter notation; " +"the imaginary part is written with a ``j`` suffix, e.g., ``3+1j``. To get " +"access to complex equivalents of the :mod:`math` module, use :mod:`cmath`. " +"Use of complex numbers is a fairly advanced mathematical feature. If you're " +"not aware of a need for them, it's almost certain you can safely ignore them." +msgstr "" +"一個我們熟悉的實數系統的擴充，在此所有數字都會被表示為一個實部和一個虛部之" +"和。虛數就是虛數單位（``-1`` 的平方根）的實數倍，此單位通常在數學中被寫為 " +"``i``，在工程學中被寫為 ``j``。Python 內建了對複數的支援，它是用後者的記法來" +"表示複數；虛部會帶著一個後綴的 ``j`` 被編寫，例如 ``3+1j``。若要將 :mod:" +"`math` 模組內的工具等效地用於複數，請使用 :mod:`cmath` 模組。複數的使用是一個" +"相當進階的數學功能。如果你沒有察覺到對它們的需求，那麼幾乎能確定你可以安全地" +"忽略它們。" + +#: ../../glossary.rst:299 +msgid "concurrency" +msgstr "concurrency（並行性）" + +#: ../../glossary.rst:301 +msgid "" +"The ability of a computer program to perform multiple tasks at the same " +"time. Python provides libraries for writing programs that make use of " +"different forms of concurrency. :mod:`asyncio` is a library for dealing " +"with asynchronous tasks and coroutines. :mod:`threading` provides access to " +"operating system threads and :mod:`multiprocessing` to operating system " +"processes. Multi-core processors can execute threads and processes on " +"different CPU cores at the same time (see :term:`parallelism`)." +msgstr "" + +#: ../../glossary.rst:309 +msgid "concurrent modification" +msgstr "" + +#: ../../glossary.rst:311 +msgid "" +"When multiple threads modify shared data at the same time. Concurrent " +"modification without proper synchronization can cause :term:`race conditions " +"`, and might also trigger a :term:`data race `, " +"data corruption, or both." +msgstr "" + +#: ../../glossary.rst:315 +msgid "context" +msgstr "context（情境）" + +#: ../../glossary.rst:317 +msgid "" +"This term has different meanings depending on where and how it is used. Some " +"common meanings:" +msgstr "" + +#: ../../glossary.rst:320 +msgid "" +"The temporary state or environment established by a :term:`context manager` " +"via a :keyword:`with` statement." +msgstr "" + +#: ../../glossary.rst:322 +msgid "" +"The collection of key­value bindings associated with a particular :class:" +"`contextvars.Context` object and accessed via :class:`~contextvars." +"ContextVar` objects. Also see :term:`context variable`." +msgstr "" + +#: ../../glossary.rst:326 +msgid "" +"A :class:`contextvars.Context` object. Also see :term:`current context`." +msgstr "" +"一個 :class:`contextvars.Context` 物件。另請參閱 :term:`current context`。" + +#: ../../glossary.rst:328 +msgid "context management protocol" +msgstr "context management protocol（情境管理協定）" + +#: ../../glossary.rst:330 +msgid "" +"The :meth:`~object.__enter__` and :meth:`~object.__exit__` methods called by " +"the :keyword:`with` statement. See :pep:`343`." +msgstr "" +"由 :keyword:`with` 陳述式所呼叫的 :meth:`~object.__enter__` 和 :meth:" +"`~object.__exit__` 方法。另請參閱 :pep:`343`。" + +#: ../../glossary.rst:332 +msgid "context manager" +msgstr "context manager（情境管理器）" + +#: ../../glossary.rst:334 +msgid "" +"An object which implements the :term:`context management protocol` and " +"controls the environment seen in a :keyword:`with` statement. See :pep:" +"`343`." +msgstr "" + +#: ../../glossary.rst:337 +msgid "context variable" +msgstr "context variable（情境變數）" + +#: ../../glossary.rst:339 +msgid "" +"A variable whose value depends on which context is the :term:`current " +"context`. Values are accessed via :class:`contextvars.ContextVar` objects. " +"Context variables are primarily used to isolate state between concurrent " +"asynchronous tasks." +msgstr "" + +#: ../../glossary.rst:343 +msgid "contiguous" +msgstr "contiguous（連續的）" + +#: ../../glossary.rst:347 +msgid "" +"A buffer is considered contiguous exactly if it is either *C-contiguous* or " +"*Fortran contiguous*. Zero-dimensional buffers are C and Fortran " +"contiguous. In one-dimensional arrays, the items must be laid out in memory " +"next to each other, in order of increasing indexes starting from zero. In " +"multidimensional C-contiguous arrays, the last index varies the fastest when " +"visiting items in order of memory address. However, in Fortran contiguous " +"arrays, the first index varies the fastest." +msgstr "" +"如果一個緩衝區是 *C-contiguous* 或是 *Fortran contiguous*，則它會確切地被視為" +"是連續的。零維 (zero-dimensional) 的緩衝區都是 C 及 Fortran contiguous。在一" +"維 (one-dimensional) 陣列中，各項目必須在記憶體中彼此相鄰地排列，而其索引順序" +"是從零開始遞增。在多維的 (multidimensional) C-contiguous 陣列中，按記憶體位址" +"的順序瀏覽各個項目時，最後一個索引的變化最快。然而，在 Fortran contiguous 陣" +"列中，第一個索引的變化最快。" + +#: ../../glossary.rst:355 +msgid "coroutine" +msgstr "coroutine（協程）" + +#: ../../glossary.rst:357 +msgid "" +"Coroutines are a more generalized form of subroutines. Subroutines are " +"entered at one point and exited at another point. Coroutines can be " +"entered, exited, and resumed at many different points. They can be " +"implemented with the :keyword:`async def` statement. See also :pep:`492`." +msgstr "" +"協程是副程式 (subroutine) 的一種更為廣義的形式。副程式是在某個時間點被進入並" +"在另一個時間點被退出。協程可以在許多不同的時間點被進入、退出和回復。它們能夠" +"以 :keyword:`async def` 陳述式被實作。另請參閱 :pep:`492`。" + +#: ../../glossary.rst:362 +msgid "coroutine function" +msgstr "coroutine function（協程函式）" + +#: ../../glossary.rst:364 +msgid "" +"A function which returns a :term:`coroutine` object. A coroutine function " +"may be defined with the :keyword:`async def` statement, and may contain :" +"keyword:`await`, :keyword:`async for`, and :keyword:`async with` keywords. " +"These were introduced by :pep:`492`." +msgstr "" +"一個回傳 :term:`coroutine`\\ （協程）物件的函式。一個協程函式能以 :keyword:" +"`async def` 陳述式被定義，並可能會包含 :keyword:`await`、:keyword:`async " +"for` 和 :keyword:`async with` 關鍵字。這些關鍵字由 :pep:`492` 引入。" + +#: ../../glossary.rst:369 +msgid "CPython" +msgstr "CPython" + +#: ../../glossary.rst:371 +msgid "" +"The canonical implementation of the Python programming language, as " +"distributed on `python.org `_. The term \"CPython\" " +"is used when necessary to distinguish this implementation from others such " +"as Jython or IronPython." +msgstr "" +"Python 程式語言的標準實作 (canonical implementation)，被發布在 `python.org " +"`_ 上。「CPython」這個術語在必要時被使用，以區分此實" +"作與其它語言的實作，例如 Jython 或 IronPython。" + +#: ../../glossary.rst:375 +msgid "current context" +msgstr "" + +#: ../../glossary.rst:377 +msgid "" +"The :term:`context` (:class:`contextvars.Context` object) that is currently " +"used by :class:`~contextvars.ContextVar` objects to access (get or set) the " +"values of :term:`context variables `. Each thread has its " +"own current context. Frameworks for executing asynchronous tasks (see :mod:" +"`asyncio`) associate each task with a context which becomes the current " +"context whenever the task starts or resumes execution." +msgstr "" + +#: ../../glossary.rst:383 +msgid "cyclic isolate" +msgstr "" + +#: ../../glossary.rst:385 +msgid "" +"A subgroup of one or more objects that reference each other in a reference " +"cycle, but are not referenced by objects outside the group. The goal of " +"the :term:`cyclic garbage collector ` is to identify " +"these groups and break the reference cycles so that the memory can be " +"reclaimed." +msgstr "" + +#: ../../glossary.rst:389 +msgid "data race" +msgstr "" + +#: ../../glossary.rst:391 +msgid "" +"A situation where multiple threads access the same memory location " +"concurrently, at least one of the accesses is a write, and the threads do " +"not use any synchronization to control their access. Data races lead to :" +"term:`non-deterministic` behavior and can cause data corruption. Proper use " +"of :term:`locks ` and other :term:`synchronization primitives " +"` prevents data races. Note that data races can " +"only happen in native code, but that :term:`native code` might be exposed in " +"a Python API. See also :term:`race condition` and :term:`thread-safe`." +msgstr "" + +#: ../../glossary.rst:400 +msgid "deadlock" +msgstr "" + +#: ../../glossary.rst:402 +msgid "" +"A situation in which two or more tasks (threads, processes, or coroutines) " +"wait indefinitely for each other to release resources or complete actions, " +"preventing any from making progress. For example, if thread A holds lock 1 " +"and waits for lock 2, while thread B holds lock 2 and waits for lock 1, both " +"threads will wait indefinitely. In Python this often arises from acquiring " +"multiple locks in conflicting orders or from circular join/await " +"dependencies. Deadlocks can be avoided by always acquiring multiple :term:" +"`locks ` in a consistent order. See also :term:`lock` and :term:" +"`reentrant`." +msgstr "" + +#: ../../glossary.rst:411 +msgid "decorator" +msgstr "decorator（裝飾器）" + +#: ../../glossary.rst:413 +msgid "" +"A function returning another function, usually applied as a function " +"transformation using the ``@wrapper`` syntax. Common examples for " +"decorators are :func:`classmethod` and :func:`staticmethod`." +msgstr "" +"一個函式，它會回傳另一個函式，通常它會使用 ``@wrapper`` 語法，被應用為一種函" +"式的變換 (function transformation)。裝飾器的常見範例是 :func:`classmethod` " +"和 :func:`staticmethod`。" + +#: ../../glossary.rst:417 +msgid "" +"The decorator syntax is merely syntactic sugar, the following two function " +"definitions are semantically equivalent::" +msgstr "裝飾器語法只是語法糖。以下兩個函式定義在語義上是等效的： ::" + +#: ../../glossary.rst:420 +msgid "" +"def f(arg):\n" +" ...\n" +"f = staticmethod(f)\n" +"\n" +"@staticmethod\n" +"def f(arg):\n" +" ..." +msgstr "" +"def f(arg):\n" +" ...\n" +"f = staticmethod(f)\n" +"\n" +"@staticmethod\n" +"def f(arg):\n" +" ..." + +#: ../../glossary.rst:428 +msgid "" +"The same concept exists for classes, but is less commonly used there. See " +"the documentation for :ref:`function definitions ` and :ref:`class " +"definitions ` for more about decorators." +msgstr "" +"Class 也存在相同的概念，但在那裡比較不常用。關於裝飾器的更多內容，請參閱\\ :" +"ref:`函式定義 `\\ 和 :ref:`class 定義 `\\ 的說明文件。" + +#: ../../glossary.rst:431 +msgid "descriptor" +msgstr "descriptor（描述器）" + +#: ../../glossary.rst:433 +msgid "" +"Any object which defines the methods :meth:`~object.__get__`, :meth:`~object." +"__set__`, or :meth:`~object.__delete__`. When a class attribute is a " +"descriptor, its special binding behavior is triggered upon attribute " +"lookup. Normally, using *a.b* to get, set or delete an attribute looks up " +"the object named *b* in the class dictionary for *a*, but if *b* is a " +"descriptor, the respective descriptor method gets called. Understanding " +"descriptors is a key to a deep understanding of Python because they are the " +"basis for many features including functions, methods, properties, class " +"methods, static methods, and reference to super classes." +msgstr "" +"任何定義了 :meth:`~object.__get__`、:meth:`~object.__set__` 或 :meth:" +"`~object.__delete__` method 的物件。當一個 class 屬性是一個描述器時，它的特殊" +"連結行為會在屬性查找時被觸發。通常，使用 *a.b* 來取得、設定或刪除某個屬性時，" +"會在 *a* 的 class 字典中查找名稱為 *b* 的物件，但如果 *b* 是一個描述器，則相" +"對應的描述器 method 會被呼叫。對描述器的理解是深入理解 Python 的關鍵，因為它" +"們是許多功能的基礎，這些功能包括函式、method、屬性 (property)、class method、" +"靜態 method，以及對 super class（父類別）的參照。" + +#: ../../glossary.rst:444 +msgid "" +"For more information about descriptors' methods, see :ref:`descriptors` or " +"the :ref:`Descriptor How To Guide `." +msgstr "" +"關於描述器 method 的更多資訊，請參閱\\ :ref:`descriptors`\\ 或\\ :ref:`描述器" +"使用指南 `。" + +#: ../../glossary.rst:446 +msgid "dictionary" +msgstr "dictionary（字典）" + +#: ../../glossary.rst:448 +msgid "" +"An associative array, where arbitrary keys are mapped to values. The keys " +"can be any object with :meth:`~object.__hash__` and :meth:`~object.__eq__` " +"methods. Called a hash in Perl." +msgstr "" +"一個關聯陣列 (associative array)，其中任意的鍵會被對映到值。鍵可以是任何帶" +"有 :meth:`~object.__hash__` 和 :meth:`~object.__eq__` method 的物件。在 Perl " +"中被稱為雜湊 (hash)。" + +#: ../../glossary.rst:452 +msgid "dictionary comprehension" +msgstr "dictionary comprehension（字典綜合運算）" + +#: ../../glossary.rst:454 +msgid "" +"A compact way to process all or part of the elements in an iterable and " +"return a dictionary with the results. ``results = {n: n ** 2 for n in " +"range(10)}`` generates a dictionary containing key ``n`` mapped to value ``n " +"** 2``. See :ref:`comprehensions`." +msgstr "" +"一種緊密的方法，用來處理一個可疊代物件中的全部或部分元素，並將處理結果以一個" +"字典回傳。``results = {n: n ** 2 for n in range(10)}`` 會產生一個字典，它包含" +"了鍵 ``n`` 對映到值 ``n ** 2``。請參閱\\ :ref:`comprehensions`。" + +#: ../../glossary.rst:458 +msgid "dictionary view" +msgstr "dictionary view（字典檢視）" + +#: ../../glossary.rst:460 +msgid "" +"The objects returned from :meth:`dict.keys`, :meth:`dict.values`, and :meth:" +"`dict.items` are called dictionary views. They provide a dynamic view on the " +"dictionary’s entries, which means that when the dictionary changes, the view " +"reflects these changes. To force the dictionary view to become a full list " +"use ``list(dictview)``. See :ref:`dict-views`." +msgstr "" +"從 :meth:`dict.keys`、:meth:`dict.values` 及 :meth:`dict.items` 回傳的物件被" +"稱為字典檢視。它們提供了字典中項目的動態檢視，這表示當字典有變動時，該檢視會" +"反映這些變動。若要強制將字典檢視轉為完整的 list（串列），須使用 " +"``list(dictview)``。請參閱\\ :ref:`dict-views`。" + +#: ../../glossary.rst:466 +msgid "docstring" +msgstr "docstring（說明字串）" + +#: ../../glossary.rst:468 +msgid "" +"A string literal which appears as the first expression in a class, function " +"or module. While ignored when the suite is executed, it is recognized by " +"the compiler and put into the :attr:`~definition.__doc__` attribute of the " +"enclosing class, function or module. Since it is available via " +"introspection, it is the canonical place for documentation of the object." +msgstr "" +"一個在 class、函式或模組中，作為第一個運算式出現的字串文本。雖然它在套件執行" +"時會被忽略，但它會被編譯器辨識，並被放入所屬 class、函式或模組的 :attr:" +"`~definition.__doc__` 屬性中。由於說明字串可以透過內省 (introspection) 來瀏" +"覽，因此它是物件的說明文件存放的標準位置。" + +#: ../../glossary.rst:474 +msgid "duck-typing" +msgstr "duck-typing（鴨子型別）" + +#: ../../glossary.rst:476 +msgid "" +"A programming style which does not look at an object's type to determine if " +"it has the right interface; instead, the method or attribute is simply " +"called or used (\"If it looks like a duck and quacks like a duck, it must be " +"a duck.\") By emphasizing interfaces rather than specific types, well-" +"designed code improves its flexibility by allowing polymorphic " +"substitution. Duck-typing avoids tests using :func:`type` or :func:" +"`isinstance`. (Note, however, that duck-typing can be complemented with :" +"term:`abstract base classes `.) Instead, it typically " +"employs :func:`hasattr` tests or :term:`EAFP` programming." +msgstr "" +"一種程式設計風格，它不是藉由檢查一個物件的型別來確定它是否具有正確的介面；取" +"而代之的是，method 或屬性會單純地被呼叫或使用。（「如果它看起來像一隻鴨子而且" +"叫起來像一隻鴨子，那麼它一定是一隻鴨子。」）因為強調介面而非特定型別，精心設" +"計的程式碼能讓多形替代 (polymorphic substitution) 來增進它的靈活性。鴨子型別" +"要避免使用 :func:`type` 或 :func:`isinstance` 進行測試。（但是請注意，鴨子型" +"別可以用\\ :term:`抽象基底類別 (abstract base class) ` " +"來補充。）然而，它通常會採用 :func:`hasattr` 測試，或是 :term:`EAFP` 程式設計" +"風格。" + +#: ../../glossary.rst:485 +msgid "dunder" +msgstr "dunder（雙底線）" + +#: ../../glossary.rst:487 +msgid "" +"An informal short-hand for \"double underscore\", used when talking about a :" +"term:`special method`. For example, ``__init__`` is often pronounced " +"\"dunder init\"." +msgstr "" +"一個非正式的縮寫，代表「雙底線 (double underscore)」，當談論到\\ :term:`特殊" +"方法 `\\ 時使用。例如，``__init__`` 通常被叫做 \"dunder " +"init\"。" + +#: ../../glossary.rst:490 +msgid "EAFP" +msgstr "EAFP" + +#: ../../glossary.rst:492 +msgid "" +"Easier to ask for forgiveness than permission. This common Python coding " +"style assumes the existence of valid keys or attributes and catches " +"exceptions if the assumption proves false. This clean and fast style is " +"characterized by the presence of many :keyword:`try` and :keyword:`except` " +"statements. The technique contrasts with the :term:`LBYL` style common to " +"many other languages such as C." +msgstr "" +"Easier to ask for forgiveness than permission.（請求寬恕比請求許可更容易。）" +"這種常見的 Python 編碼風格會先假設有效的鍵或屬性的存在，並在該假設被推翻時再" +"捕獲例外。這種乾淨且快速的風格，其特色是存在許多的 :keyword:`try` 和 :" +"keyword:`except` 陳述式。該技術與許多其他語言（例如 C）常見的 :term:`LBYL` 風" +"格形成了對比。" + +#: ../../glossary.rst:498 +msgid "evaluate function" +msgstr "evaluate function（求值函式）" + +#: ../../glossary.rst:500 +msgid "" +"A function that can be called to evaluate a lazily evaluated attribute of an " +"object, such as the value of type aliases created with the :keyword:`type` " +"statement." +msgstr "" + +#: ../../glossary.rst:503 +msgid "expression" +msgstr "expression（運算式）" + +#: ../../glossary.rst:505 +msgid "" +"A piece of syntax which can be evaluated to some value. In other words, an " +"expression is an accumulation of expression elements like literals, names, " +"attribute access, operators or function calls which all return a value. In " +"contrast to many other languages, not all language constructs are " +"expressions. There are also :term:`statement`\\s which cannot be used as " +"expressions, such as :keyword:`while`. Assignments are also statements, not " +"expressions." +msgstr "" +"一段可以被評估並求值的語法。換句話說，一個運算式就是文字、名稱、屬性存取、運" +"算子或函式呼叫等運算式元件的累積，而這些元件都能回傳一個值。與許多其他語言不" +"同的是，並非所有的 Python 語言構造都是運算式。另外有一些 :term:`statement`\\ " +"（陳述式）不能被用作運算式，例如 :keyword:`while`。賦值 (assignment) 也是陳述" +"式，而不是運算式。" + +#: ../../glossary.rst:512 +msgid "extension module" +msgstr "extension module（擴充模組）" + +#: ../../glossary.rst:514 +msgid "" +"A module written in C or C++, using Python's C API to interact with the core " +"and with user code." +msgstr "" +"一個以 C 或 C++ 編寫的模組，它使用 Python 的 C API 來與核心及使用者程式碼進行" +"互動。" + +#: ../../glossary.rst:516 +msgid "f-string" +msgstr "f-string（f 字串）" + +#: ../../glossary.rst:517 +msgid "f-strings" +msgstr "f-strings（f 字串）" + +#: ../../glossary.rst:519 +msgid "" +"String literals prefixed with ``f`` or ``F`` are commonly called \"f-" +"strings\" which is short for :ref:`formatted string literals `. " +"See also :pep:`498`." +msgstr "" +"以 ``f`` 或 ``F`` 為前綴的字串文本通常被稱為「f 字串」，它是\\ :ref:`格式化的" +"字串文本 `\\ 的縮寫。另請參閱 :pep:`498`。" + +#: ../../glossary.rst:522 +msgid "file object" +msgstr "file object（檔案物件）" + +#: ../../glossary.rst:524 +msgid "" +"An object exposing a file-oriented API (with methods such as :meth:`!read` " +"or :meth:`!write`) to an underlying resource. Depending on the way it was " +"created, a file object can mediate access to a real on-disk file or to " +"another type of storage or communication device (for example standard input/" +"output, in-memory buffers, sockets, pipes, etc.). File objects are also " +"called :dfn:`file-like objects` or :dfn:`streams`." +msgstr "" +"一個讓使用者透過檔案導向 (file-oriented) API（如 :meth:`!read` 或 :meth:`!" +"write` 等 method）來操作底層資源的物件。根據檔案物件被建立的方式，它能夠協調" +"對真實磁碟檔案或是其他類型的儲存器或通訊裝置（例如標準輸入／輸出、記憶體內緩" +"衝區、socket（插座）、管線 (pipe) 等）的存取。檔案物件也被稱為\\ :dfn:`類檔案" +"物件 (file-like object)` 或\\ :dfn:`串流 (stream)`。" + +#: ../../glossary.rst:532 +msgid "" +"There are actually three categories of file objects: raw :term:`binary files " +"`, buffered :term:`binary files ` and :term:`text " +"files `. Their interfaces are defined in the :mod:`io` module. " +"The canonical way to create a file object is by using the :func:`open` " +"function." +msgstr "" +"實際上，有三種檔案物件：原始的\\ :term:`二進位檔案 `、緩衝的\\ :" +"term:`二進位檔案 `\\ 和\\ :term:`文字檔案 `。它們的介" +"面在 :mod:`io` 模組中被定義。建立檔案物件的標準方法是使用 :func:`open` 函式。" + +#: ../../glossary.rst:537 +msgid "file-like object" +msgstr "file-like object（類檔案物件）" + +#: ../../glossary.rst:539 +msgid "A synonym for :term:`file object`." +msgstr ":term:`file object`\\ （檔案物件）的同義字。" + +#: ../../glossary.rst:540 +msgid "filesystem encoding and error handler" +msgstr "filesystem encoding and error handler（檔案系統編碼和錯誤處理函式）" + +#: ../../glossary.rst:542 +msgid "" +"Encoding and error handler used by Python to decode bytes from the operating " +"system and encode Unicode to the operating system." +msgstr "" +"Python 所使用的一種編碼和錯誤處理函式，用來解碼來自作業系統的位元組，以及將 " +"Unicode 編碼到作業系統。" + +#: ../../glossary.rst:545 +msgid "" +"The filesystem encoding must guarantee to successfully decode all bytes " +"below 128. If the file system encoding fails to provide this guarantee, API " +"functions can raise :exc:`UnicodeError`." +msgstr "" +"檔案系統編碼必須保證能成功解碼所有小於 128 的位元組。如果檔案系統編碼無法提供" +"此保證，則 API 函式會引發 :exc:`UnicodeError`。" + +#: ../../glossary.rst:549 +msgid "" +"The :func:`sys.getfilesystemencoding` and :func:`sys." +"getfilesystemencodeerrors` functions can be used to get the filesystem " +"encoding and error handler." +msgstr "" +":func:`sys.getfilesystemencoding` 和 :func:`sys.getfilesystemencodeerrors` 函" +"式可用於取得檔案系統編碼和錯誤處理函式。" + +#: ../../glossary.rst:553 +msgid "" +"The :term:`filesystem encoding and error handler` are configured at Python " +"startup by the :c:func:`PyConfig_Read` function: see :c:member:`~PyConfig." +"filesystem_encoding` and :c:member:`~PyConfig.filesystem_errors` members of :" +"c:type:`PyConfig`." +msgstr "" +":term:`filesystem encoding and error handler`\\ （檔案系統編碼和錯誤處理函" +"式）會在 Python 啟動時由 :c:func:`PyConfig_Read` 函式來配置：請參閱 :c:" +"member:`~PyConfig.filesystem_encoding`，以及 :c:type:`PyConfig` 的成員 :c:" +"member:`~PyConfig.filesystem_errors`。" + +#: ../../glossary.rst:558 +msgid "See also the :term:`locale encoding`." +msgstr "另請參閱 :term:`locale encoding`\\ （區域編碼）。" + +#: ../../glossary.rst:559 +msgid "finder" +msgstr "finder（尋檢器）" + +#: ../../glossary.rst:561 +msgid "" +"An object that tries to find the :term:`loader` for a module that is being " +"imported." +msgstr "" +"一個物件，它會嘗試為正在被 import 的模組尋找 :term:`loader`\\ （載入器）。" + +#: ../../glossary.rst:564 +msgid "" +"There are two types of finder: :term:`meta path finders ` " +"for use with :data:`sys.meta_path`, and :term:`path entry finders ` for use with :data:`sys.path_hooks`." +msgstr "" +"有兩種類型的尋檢器：:term:`元路徑尋檢器 (meta path finder) ` 會使用 :data:`sys.meta_path`，而\\ :term:`路徑項目尋檢器 (path " +"entry finder) ` 會使用 :data:`sys.path_hooks`。" + +#: ../../glossary.rst:568 +msgid "" +"See :ref:`finders-and-loaders` and :mod:`importlib` for much more detail." +msgstr "請參閱 :ref:`finders-and-loaders` 和 :mod:`importlib` 以了解更多細節。" + +#: ../../glossary.rst:569 +msgid "floor division" +msgstr "floor division（向下取整除法）" + +#: ../../glossary.rst:571 +msgid "" +"Mathematical division that rounds down to nearest integer. The floor " +"division operator is ``//``. For example, the expression ``11 // 4`` " +"evaluates to ``2`` in contrast to the ``2.75`` returned by float true " +"division. Note that ``(-11) // 4`` is ``-3`` because that is ``-2.75`` " +"rounded *downward*. See :pep:`238`." +msgstr "" +"向下無條件捨去到最接近整數的數學除法。向下取整除法的運算子是 ``//``。例如，運" +"算式 ``11 // 4`` 的計算結果為 ``2``，與 float（浮點數）真除法所回傳的 " +"``2.75`` 不同。請注意，``(-11) // 4`` 的結果是 ``-3``，因為是 ``-2.75`` 被\\ " +"*向下*\\ 無條件捨去。請參閱 :pep:`238`。" + +#: ../../glossary.rst:576 +msgid "free threading" +msgstr "free threading（自由執行緒）" + +#: ../../glossary.rst:578 +msgid "" +"A threading model where multiple threads can run Python bytecode " +"simultaneously within the same interpreter. This is in contrast to the :" +"term:`global interpreter lock` which allows only one thread to execute " +"Python bytecode at a time. See :pep:`703`." +msgstr "" +"為一種執行緒模型，多個執行緒可以在同一直譯器中同時運行 Python 位元組碼。這與" +"\\ :term:`全域直譯器鎖 `\\ 形成對比，後者一次只允許" +"一個執行緒執行 Python 位元組碼。請參閱 :pep:`703`。" + +#: ../../glossary.rst:582 +msgid "free variable" +msgstr "free variable（自由變數）" + +#: ../../glossary.rst:584 +msgid "" +"Formally, as defined in the :ref:`language execution model `, a " +"free variable is any variable used in a namespace which is not a local " +"variable in that namespace. See :term:`closure variable` for an example. " +"Pragmatically, due to the name of the :attr:`codeobject.co_freevars` " +"attribute, the term is also sometimes used as a synonym for :term:`closure " +"variable`." +msgstr "" + +#: ../../glossary.rst:589 +msgid "function" +msgstr "function（函式）" + +#: ../../glossary.rst:591 +msgid "" +"A series of statements which returns some value to a caller. It can also be " +"passed zero or more :term:`arguments ` which may be used in the " +"execution of the body. See also :term:`parameter`, :term:`method`, and the :" +"ref:`function` section." +msgstr "" +"一連串的陳述式，它能夠向呼叫者回傳一些值。它也可以被傳遞零個或多個\\ :term:`" +"引數 `，這些引數可被使用於函式本體的執行。另請參閱 :term:" +"`parameter`\\ （參數）、:term:`method`\\ （方法），以及\\ :ref:`function`\\ " +"章節。" + +#: ../../glossary.rst:595 +msgid "function annotation" +msgstr "function annotation（函式註釋）" + +#: ../../glossary.rst:597 +msgid "An :term:`annotation` of a function parameter or return value." +msgstr "函式參數或回傳值的一個 :term:`annotation`\\ （註釋）。" + +#: ../../glossary.rst:599 +msgid "" +"Function annotations are usually used for :term:`type hints `: " +"for example, this function is expected to take two :class:`int` arguments " +"and is also expected to have an :class:`int` return value::" +msgstr "" +"函式註釋通常被使用於\\ :term:`型別提示 `：例如，這個函式預期會得到" +"兩個 :class:`int` 引數，並會有一個 :class:`int` 回傳值： ::" + +#: ../../glossary.rst:604 +msgid "" +"def sum_two_numbers(a: int, b: int) -> int:\n" +" return a + b" +msgstr "" +"def sum_two_numbers(a: int, b: int) -> int:\n" +" return a + b" + +#: ../../glossary.rst:607 +msgid "Function annotation syntax is explained in section :ref:`function`." +msgstr "函式註釋的語法在\\ :ref:`function`\\ 章節有詳細解釋。" + +#: ../../glossary.rst:609 +msgid "" +"See :term:`variable annotation` and :pep:`484`, which describe this " +"functionality. Also see :ref:`annotations-howto` for best practices on " +"working with annotations." +msgstr "" +"請參閱 :term:`variable annotation` 和 :pep:`484`，皆有此功能的描述。關於註釋" +"的最佳實踐方法，另請參閱 :ref:`annotations-howto`。" + +#: ../../glossary.rst:613 +msgid "__future__" +msgstr "__future__" + +#: ../../glossary.rst:615 +msgid "" +"A :ref:`future statement `, ``from __future__ import ``, " +"directs the compiler to compile the current module using syntax or semantics " +"that will become standard in a future release of Python. The :mod:" +"`__future__` module documents the possible values of *feature*. By " +"importing this module and evaluating its variables, you can see when a new " +"feature was first added to the language and when it will (or did) become the " +"default::" +msgstr "" +":ref:`future 陳述式 `：``from __future__ import ``，會指示編" +"譯器使用那些在 Python 未來的發布版本中將成為標準的語法或語義，來編譯目前的模" +"組。而 :mod:`__future__` 模組則記錄了 *feature（功能）*\\ 可能的值。透過 " +"import 此模組並對其變數求值，你可以看見一個新的功能是何時首次被新增到此語言" +"中，以及它何時將會（或已經）成為預設的功能： ::" + +#: ../../glossary.rst:623 +msgid "" +">>> import __future__\n" +">>> __future__.division\n" +"_Feature((2, 2, 0, 'alpha', 2), (3, 0, 0, 'alpha', 0), 8192)" +msgstr "" +">>> import __future__\n" +">>> __future__.division\n" +"_Feature((2, 2, 0, 'alpha', 2), (3, 0, 0, 'alpha', 0), 8192)" + +#: ../../glossary.rst:626 +msgid "garbage collection" +msgstr "garbage collection（垃圾回收）" + +#: ../../glossary.rst:628 +msgid "" +"The process of freeing memory when it is not used anymore. Python performs " +"garbage collection via reference counting and a cyclic garbage collector " +"that is able to detect and break reference cycles. The garbage collector " +"can be controlled using the :mod:`gc` module." +msgstr "" +"當記憶體不再被使用時，將其釋放的過程。Python 執行垃圾回收，是透過參照計數 " +"(reference counting)，以及一個能夠檢測和中斷參照循環 (reference cycle) 的循環" +"垃圾回收器 (cyclic garbage collector) 來完成。垃圾回收器可以使用 :mod:`gc` 模" +"組對其進行控制。" + +#: ../../glossary.rst:633 ../../glossary.rst:634 +msgid "generator" +msgstr "generator（產生器）" + +#: ../../glossary.rst:636 +msgid "" +"A function which returns a :term:`generator iterator`. It looks like a " +"normal function except that it contains :keyword:`yield` expressions for " +"producing a series of values usable in a for-loop or that can be retrieved " +"one at a time with the :func:`next` function." +msgstr "" +"一個會回傳 :term:`generator iterator`\\ （產生器疊代器）的函式。它看起來像一" +"個正常的函式，但不同的是它包含了 :keyword:`yield` 運算式，能產生一系列的值，" +"這些值可用於 for 迴圈，或是以 :func:`next` 函式，每次檢索其中的一個值。" + +#: ../../glossary.rst:641 +msgid "" +"Usually refers to a generator function, but may refer to a *generator " +"iterator* in some contexts. In cases where the intended meaning isn't " +"clear, using the full terms avoids ambiguity." +msgstr "" +"這個術語通常用來表示一個產生器函式，但在某些情境中，也可能是表示\\ *產生器疊" +"代器*。萬一想表達的意思不夠清楚，那就使用完整的術語，以避免歧義。" + +#: ../../glossary.rst:644 +msgid "generator iterator" +msgstr "generator iterator（產生器疊代器）" + +#: ../../glossary.rst:646 +msgid "An object created by a :term:`generator` function." +msgstr "一個由 :term:`generator`\\ （產生器）函式所建立的物件。" + +#: ../../glossary.rst:648 +msgid "" +"Each :keyword:`yield` temporarily suspends processing, remembering the " +"execution state (including local variables and pending try-statements). " +"When the *generator iterator* resumes, it picks up where it left off (in " +"contrast to functions which start fresh on every invocation)." +msgstr "" +"每個 :keyword:`yield` 會暫停處理程序，並記住執行狀態（包括區域變數及擱置中的 " +"try 陳述式）。當\\ *產生器疊代器*\\ 回復時，它會從停止的地方繼續執行（與那些" +"每次呼叫時都要重新開始的函式有所不同）。" + +#: ../../glossary.rst:654 ../../glossary.rst:655 +msgid "generator expression" +msgstr "generator expression（產生器運算式）" + +#: ../../glossary.rst:657 +msgid "" +"An :term:`expression` that returns an :term:`iterator`. It looks like a " +"normal expression followed by a :keyword:`!for` clause defining a loop " +"variable, range, and an optional :keyword:`!if` clause. The combined " +"expression generates values for an enclosing function::" +msgstr "" +"一個會回傳\\ :term:`疊代器 `\\ 的\\ :term:`運算式 `。它" +"看起來像一個正常的運算式，後面接著一個 :keyword:`!for` 子句，該子句定義了迴圈" +"變數、範圍以及一個選擇性的 :keyword:`!if` 子句。該組合運算式會為外層函式產生" +"多個值： ::" + +#: ../../glossary.rst:662 +msgid "" +">>> sum(i*i for i in range(10)) # sum of squares 0, 1, 4, ... 81\n" +"285" +msgstr "" +">>> sum(i*i for i in range(10)) # 平方之和 0, 1, 4, ... 81\n" +"285" + +#: ../../glossary.rst:664 +msgid "generic function" +msgstr "generic function（泛型函式）" + +#: ../../glossary.rst:666 +msgid "" +"A function composed of multiple functions implementing the same operation " +"for different types. Which implementation should be used during a call is " +"determined by the dispatch algorithm." +msgstr "" +"一個由多個函式組成的函式，該函式會對不同的型別實作相同的運算。呼叫期間應該使" +"用哪種實作，是由調度演算法 (dispatch algorithm) 來決定。" + +#: ../../glossary.rst:670 +msgid "" +"See also the :term:`single dispatch` glossary entry, the :func:`functools." +"singledispatch` decorator, and :pep:`443`." +msgstr "" +"另請參閱 :term:`single dispatch`\\ （單一調度）術語表條目、:func:`functools." +"singledispatch` 裝飾器和 :pep:`443`。" + +#: ../../glossary.rst:672 +msgid "generic type" +msgstr "generic type（泛型型別）" + +#: ../../glossary.rst:674 +msgid "" +"A :term:`type` that can be parameterized; typically a :ref:`container " +"class` such as :class:`list` or :class:`dict`. Used for :" +"term:`type hints ` and :term:`annotations `." +msgstr "" +"一個能夠被參數化 (parameterized) 的 :term:`type`\\ （型別）；通常是一個 :ref:" +"`容器型別 `，像是 :class:`list` 和 :class:`dict`。它被用於" +"\\ :term:`型別提示 `\\ 和\\ :term:`註釋 `。" + +#: ../../glossary.rst:679 +msgid "" +"For more details, see :ref:`generic alias types`, :pep:" +"`483`, :pep:`484`, :pep:`585`, and the :mod:`typing` module." +msgstr "" +"詳情請參閱\\ :ref:`泛型別名型別 `、:pep:`483`、:pep:" +"`484`、:pep:`585` 和 :mod:`typing` 模組。" + +#: ../../glossary.rst:681 +msgid "GIL" +msgstr "GIL" + +#: ../../glossary.rst:683 +msgid "See :term:`global interpreter lock`." +msgstr "請參閱 :term:`global interpreter lock`\\ （全域直譯器鎖）。" + +#: ../../glossary.rst:684 +msgid "global interpreter lock" +msgstr "global interpreter lock（全域直譯器鎖）" + +#: ../../glossary.rst:686 +msgid "" +"The mechanism used by the :term:`CPython` interpreter to assure that only " +"one thread executes Python :term:`bytecode` at a time. This simplifies the " +"CPython implementation by making the object model (including critical built-" +"in types such as :class:`dict`) implicitly safe against concurrent access. " +"Locking the entire interpreter makes it easier for the interpreter to be " +"multi-threaded, at the expense of much of the parallelism afforded by multi-" +"processor machines." +msgstr "" +":term:`CPython` 直譯器所使用的機制，用以確保每次都只有一個執行緒能執行 " +"Python 的 :term:`bytecode`\\ （位元組碼）。透過使物件模型（包括關鍵的內建型" +"別，如 :class:`dict`\\ ）自動地避免並行存取 (concurrent access) 的危險，此機" +"制可以簡化 CPython 的實作。鎖定整個直譯器，會使直譯器更容易成為多執行緒 " +"(multi-threaded)，但代價是會犧牲掉多處理器的機器能夠提供的一大部分平行性 " +"(parallelism)。" + +#: ../../glossary.rst:695 +msgid "" +"However, some extension modules, either standard or third-party, are " +"designed so as to release the GIL when doing computationally intensive tasks " +"such as compression or hashing. Also, the GIL is always released when doing " +"I/O." +msgstr "" +"然而，有些擴充模組，無論是標準的或是第三方的，它們被設計成在執行壓縮或雜湊等" +"計算密集 (computationally intensive) 的任務時，可以解除 GIL。另外，在執行 I/" +"O 時，GIL 總是會被解除。" + +#: ../../glossary.rst:700 +msgid "" +"As of Python 3.13, the GIL can be disabled using the :option:`--disable-gil` " +"build configuration. After building Python with this option, code must be " +"run with :option:`-X gil=0 <-X>` or after setting the :envvar:`PYTHON_GIL=0 " +"` environment variable. This feature enables improved " +"performance for multi-threaded applications and makes it easier to use multi-" +"core CPUs efficiently. For more details, see :pep:`703`." +msgstr "" +"從 Python 3.13 開始可以使用 :option:`--disable-gil` 建置設定來停用 GIL。使用" +"此選項建立 Python 後，必須使用 :option:`-X gil=0 <-X>` 來執行程式碼，或者設" +"定 :envvar:`PYTHON_GIL=0 ` 環境變數後再執行程式碼。此功能可以提高" +"多執行緒應用程式的效能，並使多核心 CPU 的高效使用變得更加容易。有關更多詳細資" +"訊，請參閱 :pep:`703`。" + +#: ../../glossary.rst:707 +msgid "" +"In prior versions of Python's C API, a function might declare that it " +"requires the GIL to be held in order to use it. This refers to having an :" +"term:`attached thread state`." +msgstr "" + +#: ../../glossary.rst:710 +msgid "global state" +msgstr "" + +#: ../../glossary.rst:712 +msgid "" +"Data that is accessible throughout a program, such as module-level " +"variables, class variables, or C static variables in :term:`extension " +"modules `. In multi-threaded programs, global state " +"shared between threads typically requires synchronization to avoid :term:" +"`race conditions ` and :term:`data races `." +msgstr "" + +#: ../../glossary.rst:718 +msgid "hash-based pyc" +msgstr "hash-based pyc（雜湊架構的 pyc）" + +#: ../../glossary.rst:720 +msgid "" +"A bytecode cache file that uses the hash rather than the last-modified time " +"of the corresponding source file to determine its validity. See :ref:`pyc-" +"invalidation`." +msgstr "" +"一個位元組碼 (bytecode) 暫存檔，它使用雜湊值而不是對應原始檔案的最後修改時" +"間，來確定其有效性。請參閱\\ :ref:`pyc-invalidation`。" + +#: ../../glossary.rst:723 +msgid "hashable" +msgstr "hashable（可雜湊的）" + +#: ../../glossary.rst:725 +msgid "" +"An object is *hashable* if it has a hash value which never changes during " +"its lifetime (it needs a :meth:`~object.__hash__` method), and can be " +"compared to other objects (it needs an :meth:`~object.__eq__` method). " +"Hashable objects which compare equal must have the same hash value." +msgstr "" +"如果一個物件有一個雜湊值，該值在其生命週期中永不改變（它需要一個 :meth:" +"`~object.__hash__` method），且可與其他物件互相比較（它需要一個 :meth:" +"`~object.__eq__` method），那麼它就是一個\\ *可雜湊*\\ 物件。比較結果為相等的" +"多個可雜湊物件，它們必須擁有相同的雜湊值。" + +#: ../../glossary.rst:731 +msgid "" +"Hashability makes an object usable as a dictionary key and a set member, " +"because these data structures use the hash value internally." +msgstr "" +"可雜湊性 (hashability) 使一個物件可用作 dictionary（字典）的鍵和 set（集合）" +"的成員，因為這些資料結構都在其內部使用了雜湊值。" + +#: ../../glossary.rst:734 +msgid "" +"Most of Python's immutable built-in objects are hashable; mutable containers " +"(such as lists or dictionaries) are not; immutable containers (such as " +"tuples and frozensets) are only hashable if their elements are hashable. " +"Objects which are instances of user-defined classes are hashable by " +"default. They all compare unequal (except with themselves), and their hash " +"value is derived from their :func:`id`." +msgstr "" +"大多數的 Python 不可變內建物件都是可雜湊的；可變的容器（例如 list 或 " +"dictionary）並不是；而不可變的容器（例如 tuple（元組）和 frozenset），只有當" +"它們的元素是可雜湊的，它們本身才是可雜湊的。若物件是使用者自定 class 的實例，" +"則這些物件會被預設為可雜湊的。它們在互相比較時都是不相等的（除非它們與自己比" +"較），而它們的雜湊值則是衍生自它們的 :func:`id`。" + +#: ../../glossary.rst:741 +msgid "IDLE" +msgstr "IDLE" + +#: ../../glossary.rst:743 +msgid "" +"An Integrated Development and Learning Environment for Python. :ref:`idle` " +"is a basic editor and interpreter environment which ships with the standard " +"distribution of Python." +msgstr "" +"Python 的 Integrated Development and Learning Environment（整合開發與學習環" +"境）。:ref:`idle` 是一個基本的編輯器和直譯器環境，它和 Python 的標準發行版本" +"一起被提供。" + +#: ../../glossary.rst:746 +msgid "immortal" +msgstr "immortal（不滅）" + +#: ../../glossary.rst:748 +msgid "" +"*Immortal objects* are a CPython implementation detail introduced in :pep:" +"`683`." +msgstr "*不滅物件 (Immortal objects)* 是 :pep:`683` 引入的 CPython 實作細節。" + +#: ../../glossary.rst:751 +msgid "" +"If an object is immortal, its :term:`reference count` is never modified, and " +"therefore it is never deallocated while the interpreter is running. For " +"example, :const:`True` and :const:`None` are immortal in CPython." +msgstr "" +"如果一個物件是不滅的，它的\\ :term:`參照計數 `\\ 永遠不會被" +"修改，因此在直譯器運行時它永遠不會被釋放。例如，:const:`True` 和 :const:" +"`None` 在 CPython 中是不滅的。" + +#: ../../glossary.rst:755 +msgid "" +"Immortal objects can be identified via :func:`sys._is_immortal`, or via :c:" +"func:`PyUnstable_IsImmortal` in the C API." +msgstr "" + +#: ../../glossary.rst:757 +msgid "immutable" +msgstr "immutable（不可變物件）" + +#: ../../glossary.rst:759 +msgid "" +"An object with a fixed value. Immutable objects include numbers, strings " +"and tuples. Such an object cannot be altered. A new object has to be " +"created if a different value has to be stored. They play an important role " +"in places where a constant hash value is needed, for example as a key in a " +"dictionary. Immutable objects are inherently :term:`thread-safe` because " +"their state cannot be modified after creation, eliminating concerns about " +"improperly synchronized :term:`concurrent modification`." +msgstr "" +"一個具有固定值的物件。不可變物件包括數字、字串和 tuple（元組）。這類物件是不" +"能被改變的。如果必須儲存一個不同的值，則需要建立一個新的物件。它們在需要恆" +"定雜湊值的地方扮演重要的角色，例如 dictionary 中的一個鍵。不可變物件本" +"質上是\\ :term:`執行緒安全的 `，因為它們的狀態在建立後無法被修改，" +"從而消除了對不當同步的\\ :term:`並行修改 `\\ 的疑慮。" + +#: ../../glossary.rst:766 +msgid "import path" +msgstr "import path（引入路徑）" + +#: ../../glossary.rst:768 +msgid "" +"A list of locations (or :term:`path entries `) that are searched " +"by the :term:`path based finder` for modules to import. During import, this " +"list of locations usually comes from :data:`sys.path`, but for subpackages " +"it may also come from the parent package's ``__path__`` attribute." +msgstr "" +"一個位置（或\\ :term:`路徑項目 `\\ ）的列表，而那些位置就是在 " +"import 模組時，會被 :term:`path based finder`\\ （基於路徑的尋檢器）搜尋模組" +"的位置。在 import 期間，此位置列表通常是來自 :data:`sys.path`，但對於子套件 " +"(subpackage) 而言，它也可能是來自父套件的 ``__path__`` 屬性。" + +#: ../../glossary.rst:773 +msgid "importing" +msgstr "importing（引入）" + +#: ../../glossary.rst:775 +msgid "" +"The process by which Python code in one module is made available to Python " +"code in another module." +msgstr "" +"一個過程。一個模組中的 Python 程式碼可以透過此過程，被另一個模組中的 Python " +"程式碼使用。" + +#: ../../glossary.rst:777 +msgid "importer" +msgstr "importer（引入器）" + +#: ../../glossary.rst:779 +msgid "" +"An object that both finds and loads a module; both a :term:`finder` and :" +"term:`loader` object." +msgstr "" +"一個能夠尋找及載入模組的物件；它既是 :term:`finder`\\ （尋檢器）也是 :term:" +"`loader`\\ （載入器）物件。" + +#: ../../glossary.rst:781 +msgid "interactive" +msgstr "interactive（互動的）" + +#: ../../glossary.rst:783 +msgid "" +"Python has an interactive interpreter which means you can enter statements " +"and expressions at the interpreter prompt, immediately execute them and see " +"their results. Just launch ``python`` with no arguments (possibly by " +"selecting it from your computer's main menu). It is a very powerful way to " +"test out new ideas or inspect modules and packages (remember ``help(x)``). " +"For more on interactive mode, see :ref:`tut-interac`." +msgstr "" +"Python 有一個互動式直譯器，這表示你可以在直譯器的提示字元輸入陳述式和運算式，" +"立即執行它們並且看到它們的結果。只要啟動 ``python``，不需要任何引數（可能藉由" +"從你的電腦的主選單選擇它）。這是測試新想法或檢查模組和包的非常強大的方法（請" +"記住help(x)）。更多互動式模式相關資訊請見 :ref:`tut-interac`。" + +#: ../../glossary.rst:790 +msgid "interpreted" +msgstr "interpreted（直譯的）" + +#: ../../glossary.rst:792 +msgid "" +"Python is an interpreted language, as opposed to a compiled one, though the " +"distinction can be blurry because of the presence of the bytecode compiler. " +"This means that source files can be run directly without explicitly creating " +"an executable which is then run. Interpreted languages typically have a " +"shorter development/debug cycle than compiled ones, though their programs " +"generally also run more slowly. See also :term:`interactive`." +msgstr "" +"Python 是一種直譯語言，而不是編譯語言，不過這個區分可能有些模糊，因為有位元組" +"碼 (bytecode) 編譯器的存在。這表示原始檔案可以直接被運行，而不需明確地建立另" +"一個執行檔，然後再執行它。直譯語言通常比編譯語言有更短的開發／除錯週期，不過" +"它們的程式通常也運行得較慢。另請參閱 :term:`interactive`\\ （互動的）。" + +#: ../../glossary.rst:799 +msgid "interpreter shutdown" +msgstr "interpreter shutdown（直譯器關閉）" + +#: ../../glossary.rst:801 +msgid "" +"When asked to shut down, the Python interpreter enters a special phase where " +"it gradually releases all allocated resources, such as modules and various " +"critical internal structures. It also makes several calls to the :term:" +"`garbage collector `. This can trigger the execution of " +"code in user-defined destructors or weakref callbacks. Code executed during " +"the shutdown phase can encounter various exceptions as the resources it " +"relies on may not function anymore (common examples are library modules or " +"the warnings machinery)." +msgstr "" +"當 Python 直譯器被要求關閉時，它會進入一個特殊階段，在此它逐漸釋放所有被配置" +"的資源，例如模組和各種關鍵內部結構。它也會多次呼叫\\ :term:`垃圾回收器 " +"(garbage collector) `。這能夠觸發使用者自定的解構函式 " +"(destructor) 或弱引用的回呼 (weakref callback)，並執行其中的程式碼。在關閉階" +"段被執行的程式碼會遇到各種例外，因為它所依賴的資源可能不再有作用了（常見的例" +"子是函式庫模組或是警告機制）。" + +#: ../../glossary.rst:810 +msgid "" +"The main reason for interpreter shutdown is that the ``__main__`` module or " +"the script being run has finished executing." +msgstr "" +"直譯器關閉的主要原因，是 ``__main__`` 模組或正被運行的腳本已經執行完成。" + +#: ../../glossary.rst:812 +msgid "iterable" +msgstr "iterable（可疊代物件）" + +#: ../../glossary.rst:814 +msgid "" +"An object capable of returning its members one at a time. Examples of " +"iterables include all sequence types (such as :class:`list`, :class:`str`, " +"and :class:`tuple`) and some non-sequence types like :class:`dict`, :term:" +"`file objects `, and objects of any classes you define with an :" +"meth:`~object.__iter__` method or with a :meth:`~object.__getitem__` method " +"that implements :term:`sequence` semantics." +msgstr "" +"一種能夠一次回傳一個其中成員的物件。可疊代物件的例子包括所有的序列型別（像" +"是 :class:`list`、:class:`str` 和 :class:`tuple`\\ ）和某些非序列型別，像是 :" +"class:`dict`、:term:`檔案物件 `，以及你所定義的任何 class 物件，" +"只要那些 class 有實作 :term:`sequence`\\ （序列）語意的 :meth:`~object." +"__iter__` 或是 :meth:`~object.__getitem__` method，該物件就是可疊代物件。" + +#: ../../glossary.rst:822 +msgid "" +"Iterables can be used in a :keyword:`for` loop and in many other places " +"where a sequence is needed (:func:`zip`, :func:`map`, ...). When an " +"iterable object is passed as an argument to the built-in function :func:" +"`iter`, it returns an iterator for the object. This iterator is good for " +"one pass over the set of values. When using iterables, it is usually not " +"necessary to call :func:`iter` or deal with iterator objects yourself. The :" +"keyword:`for` statement does that automatically for you, creating a " +"temporary unnamed variable to hold the iterator for the duration of the " +"loop. See also :term:`iterator`, :term:`sequence`, and :term:`generator`." +msgstr "" +"可疊代物件可用於 :keyword:`for` 迴圈和許多其他需要一個序列的地方 (:func:" +"`zip`、:func:`map`\\ ...)。當一個可疊代物件作為引數被傳遞給內建函式 :func:" +"`iter` 時，它會為該物件回傳一個疊代器。此疊代器適用於針對一組值進行一遍 (one " +"pass) 運算。使用疊代器時，通常不一定要呼叫 :func:`iter` 或自行處理疊代器物" +"件。:keyword:`for` 陳述式會自動地為你處理這些事，它會建立一個暫時性的未命名變" +"數，用於在迴圈期間保有該疊代器。另請參閱 :term:`iterator`\\ （疊代器）、:" +"term:`sequence`\\ （序列）和 :term:`generator`\\ （產生器）。" + +#: ../../glossary.rst:832 +msgid "iterator" +msgstr "iterator（疊代器）" + +#: ../../glossary.rst:834 +msgid "" +"An object representing a stream of data. Repeated calls to the iterator's :" +"meth:`~iterator.__next__` method (or passing it to the built-in function :" +"func:`next`) return successive items in the stream. When no more data are " +"available a :exc:`StopIteration` exception is raised instead. At this " +"point, the iterator object is exhausted and any further calls to its :meth:`!" +"__next__` method just raise :exc:`StopIteration` again. Iterators are " +"required to have an :meth:`~iterator.__iter__` method that returns the " +"iterator object itself so every iterator is also iterable and may be used in " +"most places where other iterables are accepted. One notable exception is " +"code which attempts multiple iteration passes. A container object (such as " +"a :class:`list`) produces a fresh new iterator each time you pass it to the :" +"func:`iter` function or use it in a :keyword:`for` loop. Attempting this " +"with an iterator will just return the same exhausted iterator object used in " +"the previous iteration pass, making it appear like an empty container." +msgstr "" +"一個表示資料流的物件。重複地呼叫疊代器的 :meth:`~iterator.__next__` method" +"（或是將它傳遞給內建函式 :func:`next`\\ ）會依序回傳資料流中的各項目。當不再" +"有資料時，則會引發 :exc:`StopIteration` 例外。此時，該疊代器物件已被用盡，而" +"任何對其 :meth:`!__next__` method 的進一步呼叫，都只會再次引發 :exc:" +"`StopIteration`。疊代器必須有一個 :meth:`~iterator.__iter__` method，它會回傳" +"疊代器物件本身，所以每個疊代器也都是可疊代物件，且可以用於大多數適用其他可疊" +"代物件的場合。一個明顯的例外，是嘗試多遍疊代 (multiple iteration passes) 的程" +"式碼。一個容器物件（像是 :class:`list`）在每次你將它傳遞給 :func:`iter` 函式" +"或在 :keyword:`for` 迴圈中使用它時，都會產生一個全新的疊代器。使用疊代器嘗試" +"此事（多遍疊代）時，只會回傳在前一遍疊代中被用過的、同一個已被用盡的疊代器物" +"件，使其看起來就像一個空的容器。" + +#: ../../glossary.rst:849 +msgid "More information can be found in :ref:`typeiter`." +msgstr "在\\ :ref:`typeiter`\\ 文中可以找到更多資訊。" + +#: ../../glossary.rst:853 +msgid "" +"CPython does not consistently apply the requirement that an iterator define :" +"meth:`~iterator.__iter__`. And also please note that :term:`free-threaded " +"` CPython does not guarantee :term:`thread-safe` behavior of " +"iterator operations." +msgstr "" +"CPython 並不是始終如一地都會檢查「疊代器有定義 :meth:`~iterator." +"__iter__`\\ 」這個規定。另請注意，:term:`free-threading（自由執行緒）` CPython 不保證疊代器操作的\\ :term:`執行緒安全 ` 行為。" + +#: ../../glossary.rst:859 +msgid "key function" +msgstr "key function（鍵函式）" + +#: ../../glossary.rst:861 +msgid "" +"A key function or collation function is a callable that returns a value used " +"for sorting or ordering. For example, :func:`locale.strxfrm` is used to " +"produce a sort key that is aware of locale specific sort conventions." +msgstr "" +"鍵函式或理序函式 (collation function) 是一個可呼叫 (callable) 函式，它會回傳" +"一個用於排序 (sorting) 或定序 (ordering) 的值。例如，:func:`locale.strxfrm` " +"被用來產生一個了解區域特定排序慣例的排序鍵。" + +#: ../../glossary.rst:866 +msgid "" +"A number of tools in Python accept key functions to control how elements are " +"ordered or grouped. They include :func:`min`, :func:`max`, :func:`sorted`, :" +"meth:`list.sort`, :func:`heapq.merge`, :func:`heapq.nsmallest`, :func:`heapq." +"nlargest`, and :func:`itertools.groupby`." +msgstr "" +"Python 中的許多工具，都接受以鍵函式來控制元素被定序或分組的方式。它們包括 :" +"func:`min`、:func:`max`、:func:`sorted`、:meth:`list.sort`、:func:`heapq." +"merge`、:func:`heapq.nsmallest`、:func:`heapq.nlargest` 和 :func:`itertools." +"groupby`。" + +#: ../../glossary.rst:872 +msgid "" +"There are several ways to create a key function. For example. the :meth:" +"`str.casefold` method can serve as a key function for case insensitive " +"sorts. Alternatively, a key function can be built from a :keyword:`lambda` " +"expression such as ``lambda r: (r[0], r[2])``. Also, :func:`operator." +"attrgetter`, :func:`operator.itemgetter`, and :func:`operator.methodcaller` " +"are three key function constructors. See the :ref:`Sorting HOW TO " +"` for examples of how to create and use key functions." +msgstr "" +"有幾種方法可以建立一個鍵函式。例如，:meth:`str.casefold` method 可以作為不分大小" +"寫排序的鍵函式。或者，一個鍵函式也可以從 :keyword:`lambda` 運算式被建造，例" +"如 ``lambda r: (r[0], r[2])``。另外，:func:`operator.attrgetter`、:func:" +"`operator.itemgetter` 和 :func:`operator.methodcaller` 為三個鍵函式的建構函" +"式 (constructor)。關於如何建立和使用鍵函式的範例，請參閱\\ :ref:`如何排序 " +"`。" + +#: ../../glossary.rst:879 +msgid "keyword argument" +msgstr "keyword argument（關鍵字引數）" + +#: ../../glossary.rst:881 ../../glossary.rst:1248 +msgid "See :term:`argument`." +msgstr "請參閱 :term:`argument`\\ （引數）。" + +#: ../../glossary.rst:882 +msgid "lambda" +msgstr "lambda" + +#: ../../glossary.rst:884 +msgid "" +"An anonymous inline function consisting of a single :term:`expression` which " +"is evaluated when the function is called. The syntax to create a lambda " +"function is ``lambda [parameters]: expression``" +msgstr "" +"由單一 :term:`expression`\\ （運算式）所組成的一個匿名行內函式 (inline " +"function)，於該函式被呼叫時求值。建立 lambda 函式的語法是 ``lambda " +"[parameters]: expression``" + +#: ../../glossary.rst:887 +msgid "LBYL" +msgstr "LBYL" + +#: ../../glossary.rst:889 +msgid "" +"Look before you leap. This coding style explicitly tests for pre-conditions " +"before making calls or lookups. This style contrasts with the :term:`EAFP` " +"approach and is characterized by the presence of many :keyword:`if` " +"statements." +msgstr "" +"Look before you leap.（三思而後行。）這種編碼風格會在進行呼叫或查找之前，明確" +"地測試先決條件。這種風格與 :term:`EAFP` 方式形成對比，且它的特色是會有許多 :" +"keyword:`if` 陳述式的存在。" + +#: ../../glossary.rst:894 +msgid "" +"In a multi-threaded environment, the LBYL approach can risk introducing a :" +"term:`race condition` between \"the looking\" and \"the leaping\". For " +"example, the code, ``if key in mapping: return mapping[key]`` can fail if " +"another thread removes *key* from *mapping* after the test, but before the " +"lookup. This issue can be solved with :term:`locks ` or by using the :" +"term:`EAFP` approach. See also :term:`thread-safe`." +msgstr "" +"在一個多執行緒環境中，LBYL 方式有在「三思」和「後行」之間引入\\ :term:`競爭條件 " +"` 的風險。例如以下程式碼 ``if key in mapping: return " +"mapping[key]``，如果另一個執行緒在測試之後但在查找之前，從 *mapping* 中移除" +"了 *key*，則該程式碼就會失效。這個問題可以用\\ :term:`鎖 `\\ 或使用 :term:" +"`EAFP` 編碼方式來解決。另請參閱\\ :term:`執行緒安全 `。" + +#: ../../glossary.rst:900 +msgid "lexical analyzer" +msgstr "lexical analyzer（詞法分析器）" + +#: ../../glossary.rst:903 +msgid "Formal name for the *tokenizer*; see :term:`token`." +msgstr "tokenizer 的正式名稱；請參閱 :term:`token`。" + +#: ../../glossary.rst:904 +msgid "list" +msgstr "list（串列）" + +#: ../../glossary.rst:906 +msgid "" +"A built-in Python :term:`sequence`. Despite its name it is more akin to an " +"array in other languages than to a linked list since access to elements is " +"*O*\\ (1)." +msgstr "" +"一個 Python 內建的 :term:`sequence` （序列）。儘管它的名字是 list，它其實更類" +"似其他語言中的一個陣列 (array) 而較不像一個鏈結串列 (linked list)，因為存取元" +"素的時間複雜度是 *O*\\ (1)。" + +#: ../../glossary.rst:909 +msgid "list comprehension" +msgstr "list comprehension（串列綜合運算）" + +#: ../../glossary.rst:911 +msgid "" +"A compact way to process all or part of the elements in a sequence and " +"return a list with the results. ``result = ['{:#04x}'.format(x) for x in " +"range(256) if x % 2 == 0]`` generates a list of strings containing even hex " +"numbers (0x..) in the range from 0 to 255. The :keyword:`if` clause is " +"optional. If omitted, all elements in ``range(256)`` are processed." +msgstr "" +"一種用來處理一個序列中的全部或部分元素，並將處理結果以一個 list 回傳的簡要方" +"法。``result = ['{:#04x}'.format(x) for x in range(256) if x % 2 == 0]`` 會產" +"生一個字串 list，其中包含 0 到 255 範圍內，所有偶數的十六進位數 (0x..)。:" +"keyword:`if` 子句是選擇性的。如果省略它，則 ``range(256)`` 中的所有元素都會被" +"處理。" + +#: ../../glossary.rst:917 +msgid "lock" +msgstr "lock（鎖）" + +#: ../../glossary.rst:919 +msgid "" +"A :term:`synchronization primitive` that allows only one thread at a time to " +"access a shared resource. A thread must acquire a lock before accessing the " +"protected resource and release it afterward. If a thread attempts to " +"acquire a lock that is already held by another thread, it will block until " +"the lock becomes available. Python's :mod:`threading` module provides :" +"class:`~threading.Lock` (a basic lock) and :class:`~threading.RLock` (a :" +"term:`reentrant` lock). Locks are used to prevent :term:`race conditions " +"` and ensure :term:`thread-safe` access to shared data. " +"Alternative design patterns to locks exist such as queues, producer/consumer " +"patterns, and thread-local state. See also :term:`deadlock`, and :term:" +"`reentrant`." +msgstr "" + +#: ../../glossary.rst:930 +msgid "loader" +msgstr "loader（載入器）" + +#: ../../glossary.rst:932 +msgid "" +"An object that loads a module. It must define the :meth:`!exec_module` and :" +"meth:`!create_module` methods to implement the :class:`~importlib.abc." +"Loader` interface. A loader is typically returned by a :term:`finder`. See " +"also:" +msgstr "" +"一個能夠載入模組的物件。它必須定義 :meth:`!exec_module` 和 :meth:`!" +"create_module` 方法以實作 :class:`~importlib.abc.Loader` 介面。載入器通常是" +"被 :term:`finder`\\ （尋檢器）回傳。更多細節請參閱：" + +#: ../../glossary.rst:938 +msgid ":ref:`finders-and-loaders`" +msgstr ":ref:`finders-and-loaders`" + +#: ../../glossary.rst:939 +msgid ":class:`importlib.abc.Loader`" +msgstr ":class:`importlib.abc.Loader`" + +#: ../../glossary.rst:940 +msgid ":pep:`302`" +msgstr ":pep:`302`" + +#: ../../glossary.rst:941 +msgid "locale encoding" +msgstr "locale encoding（區域編碼）" + +#: ../../glossary.rst:943 +msgid "" +"On Unix, it is the encoding of the LC_CTYPE locale. It can be set with :func:" +"`locale.setlocale(locale.LC_CTYPE, new_locale) `." +msgstr "" +"在 Unix 上，它是 LC_CTYPE 區域設定的編碼。它可以用 :func:`locale." +"setlocale(locale.LC_CTYPE, new_locale) ` 來設定。" + +#: ../../glossary.rst:946 +msgid "On Windows, it is the ANSI code page (ex: ``\"cp1252\"``)." +msgstr "在 Windows 上，它是 ANSI 碼頁（code page，例如 ``\"cp1252\"``\\ ）。" + +#: ../../glossary.rst:948 +msgid "" +"On Android and VxWorks, Python uses ``\"utf-8\"`` as the locale encoding." +msgstr "在 Android 和 VxWorks 上，Python 使用 ``\"utf-8\"`` 作為區域編碼。" + +#: ../../glossary.rst:950 +msgid ":func:`locale.getencoding` can be used to get the locale encoding." +msgstr ":func:`locale.getencoding` 可以用來取得區域編碼。" + +#: ../../glossary.rst:952 +msgid "See also the :term:`filesystem encoding and error handler`." +msgstr "也請參考 :term:`filesystem encoding and error handler`。" + +#: ../../glossary.rst:953 +msgid "magic method" +msgstr "magic method（魔術方法）" + +#: ../../glossary.rst:957 +msgid "An informal synonym for :term:`special method`." +msgstr ":term:`special method`\\ （特殊方法）的一個非正式同義詞。" + +#: ../../glossary.rst:958 +msgid "mapping" +msgstr "mapping（對映）" + +#: ../../glossary.rst:960 +msgid "" +"A container object that supports arbitrary key lookups and implements the " +"methods specified in the :class:`collections.abc.Mapping` or :class:" +"`collections.abc.MutableMapping` :ref:`abstract base classes `. Examples include :class:`dict`, :class:" +"`collections.defaultdict`, :class:`collections.OrderedDict` and :class:" +"`collections.Counter`." +msgstr "" +"一個容器物件，它支援任意鍵的查找，且能實作 :ref:`abstract base classes（抽象" +"基底類別） `\\ 中，:class:`collections." +"abc.Mapping` 或 :class:`collections.abc.MutableMapping` 所指定的 method。範例" +"包括 :class:`dict`、:class:`collections.defaultdict`、:class:`collections." +"OrderedDict` 和 :class:`collections.Counter`。" + +#: ../../glossary.rst:966 +msgid "meta path finder" +msgstr "meta path finder（元路徑尋檢器）" + +#: ../../glossary.rst:968 +msgid "" +"A :term:`finder` returned by a search of :data:`sys.meta_path`. Meta path " +"finders are related to, but different from :term:`path entry finders `." +msgstr "" +"一種經由搜尋 :data:`sys.meta_path` 而回傳的 :term:`finder`\\ （尋檢器）。元路" +"徑尋檢器與\\ :term:`路徑項目尋檢器 (path entry finder) ` " +"相關但是不同。" + +#: ../../glossary.rst:972 +msgid "" +"See :class:`importlib.abc.MetaPathFinder` for the methods that meta path " +"finders implement." +msgstr "" +"關於元路徑尋檢器實作的 method，請參閱 :class:`importlib.abc.MetaPathFinder`。" + +#: ../../glossary.rst:974 +msgid "metaclass" +msgstr "metaclass（元類別）" + +#: ../../glossary.rst:976 +msgid "" +"The class of a class. Class definitions create a class name, a class " +"dictionary, and a list of base classes. The metaclass is responsible for " +"taking those three arguments and creating the class. Most object oriented " +"programming languages provide a default implementation. What makes Python " +"special is that it is possible to create custom metaclasses. Most users " +"never need this tool, but when the need arises, metaclasses can provide " +"powerful, elegant solutions. They have been used for logging attribute " +"access, adding thread-safety, tracking object creation, implementing " +"singletons, and many other tasks." +msgstr "" +"一種 class 的 class。Class 定義過程會建立一個 class 名稱、一個 class " +"dictionary（字典），以及一個 base class（基底類別）的列表。Metaclass 負責接受" +"這三個引數，並建立該 class。大多數的物件導向程式語言會提供一個預設的實作。" +"Python 的特別之處在於它能夠建立自訂的 metaclass。大部分的使用者從未需要此工" +"具，但是當需要時，metaclass 可以提供強大且優雅的解決方案。它們已被用於記錄屬" +"性存取、增加執行緒安全性、追蹤物件建立、實作單例模式 (singleton)，以及許多其" +"他的任務。" + +#: ../../glossary.rst:986 +msgid "More information can be found in :ref:`metaclasses`." +msgstr "更多資訊可以在\\ :ref:`metaclasses`\\ 章節中找到。" + +#: ../../glossary.rst:955 ../../glossary.rst:987 ../../glossary.rst:1430 +msgid "method" +msgstr "method（方法）" + +#: ../../glossary.rst:989 +msgid "" +"A function which is defined inside a class body. If called as an attribute " +"of an instance of that class, the method will get the instance object as its " +"first :term:`argument` (which is usually called ``self``). See :term:" +"`function` and :term:`nested scope`." +msgstr "" +"一個在 class 本體內被定義的函式。如果 method 作為其 class 實例的一個屬性被呼" +"叫，則它將會得到該實例物件成為它的第一個 :term:`argument`\\ （引數）（此引數" +"通常被稱為 ``self``）。請參閱 :term:`function`\\ （函式）和 :term:`nested " +"scope`\\ （巢狀作用域）。" + +#: ../../glossary.rst:993 +msgid "method resolution order" +msgstr "method resolution order（方法解析順序）" + +#: ../../glossary.rst:995 +msgid "" +"Method Resolution Order is the order in which base classes are searched for " +"a member during lookup. See :ref:`python_2.3_mro` for details of the " +"algorithm used by the Python interpreter since the 2.3 release." +msgstr "" +"方法解析順序是在查找某個成員的過程中，base class（基底類別）被搜尋的順序。關" +"於 Python 自 2.3 版直譯器所使用的演算法細節，請參閱 :ref:`python_2.3_mro`。" + +#: ../../glossary.rst:998 +msgid "module" +msgstr "module（模組）" + +#: ../../glossary.rst:1000 +msgid "" +"An object that serves as an organizational unit of Python code. Modules " +"have a namespace containing arbitrary Python objects. Modules are loaded " +"into Python by the process of :term:`importing`." +msgstr "" +"一個擔任 Python 程式碼的組織單位 (organizational unit) 的物件。模組有一個命名" +"空間，它包含任意的 Python 物件。模組是藉由 :term:`importing` 的過程，被載入" +"至 Python。" + +#: ../../glossary.rst:1004 +msgid "See also :term:`package`." +msgstr "另請參閱 :term:`package`\\ （套件）。" + +#: ../../glossary.rst:1005 +msgid "module spec" +msgstr "module spec（模組規格）" + +#: ../../glossary.rst:1007 +msgid "" +"A namespace containing the import-related information used to load a module. " +"An instance of :class:`importlib.machinery.ModuleSpec`." +msgstr "" +"一個命名空間，它包含用於載入模組的 import 相關資訊。它是 :class:`importlib." +"machinery.ModuleSpec` 的一個實例。" + +#: ../../glossary.rst:1010 +msgid "See also :ref:`module-specs`." +msgstr "另請參閱 :ref:`module-specs`。" + +#: ../../glossary.rst:1011 +msgid "MRO" +msgstr "MRO" + +#: ../../glossary.rst:1013 +msgid "See :term:`method resolution order`." +msgstr "請參閱 :term:`method resolution order`\\ （方法解析順序）。" + +#: ../../glossary.rst:1014 +msgid "mutable" +msgstr "mutable（可變物件）" + +#: ../../glossary.rst:1016 +msgid "" +"An :term:`object` with state that is allowed to change during the course of " +"the program. In multi-threaded programs, mutable objects that are shared " +"between threads require careful synchronization to avoid :term:`race " +"conditions `. See also :term:`immutable`, :term:`thread-" +"safe`, and :term:`concurrent modification`." +msgstr "" + +#: ../../glossary.rst:1021 +msgid "named tuple" +msgstr "named tuple（附名元組）" + +#: ../../glossary.rst:1023 +msgid "" +"The term \"named tuple\" applies to any type or class that inherits from " +"tuple and whose indexable elements are also accessible using named " +"attributes. The type or class may have other features as well." +msgstr "" +"術語「named tuple（附名元組）」是指從 tuple 繼承的任何型別或 class，且它的可" +"索引 (indexable) 元素也可以用附名屬性來存取。這些型別或 class 也可以具有其他" +"的特性。" + +#: ../../glossary.rst:1027 +msgid "" +"Several built-in types are named tuples, including the values returned by :" +"func:`time.localtime` and :func:`os.stat`. Another example is :data:`sys." +"float_info`::" +msgstr "" +"有些內建型別是 named tuple，包括由 :func:`time.localtime` 和 :func:`os.stat` " +"回傳的值。另一個例子是 :data:`sys.float_info`： ::" + +#: ../../glossary.rst:1031 +msgid "" +">>> sys.float_info[1] # indexed access\n" +"1024\n" +">>> sys.float_info.max_exp # named field access\n" +"1024\n" +">>> isinstance(sys.float_info, tuple) # kind of tuple\n" +"True" +msgstr "" +">>> sys.float_info[1] # 以索引存取\n" +"1024\n" +">>> sys.float_info.max_exp # 以欄位名稱存取\n" +"1024\n" +">>> isinstance(sys.float_info, tuple) # 屬於 tuple 型別\n" +"True" + +#: ../../glossary.rst:1038 +msgid "" +"Some named tuples are built-in types (such as the above examples). " +"Alternatively, a named tuple can be created from a regular class definition " +"that inherits from :class:`tuple` and that defines named fields. Such a " +"class can be written by hand, or it can be created by inheriting :class:" +"`typing.NamedTuple`, or with the factory function :func:`collections." +"namedtuple`. The latter techniques also add some extra methods that may not " +"be found in hand-written or built-in named tuples." +msgstr "" +"有些 named tuple 是內建型別（如上例）。或者，一個 named tuple 也可以從一個正" +"規的 class 定義來建立，只要該 class 是繼承自 :class:`tuple`，且定義了附名欄" +"位 (named field) 即可。這類的 class 可以手工編寫、可以繼承自 :class:`typing." +"NamedTuple` 來建立，也可以使用工廠函式 (factory function) :func:`collections." +"namedtuple` 來建立。後者技術也增加了一些額外的 method，這些 method 可能是在手" +"寫或內建的 named tuple 中，無法找到的。" + +#: ../../glossary.rst:1046 +msgid "namespace" +msgstr "namespace（命名空間）" + +#: ../../glossary.rst:1048 +msgid "" +"The place where a variable is stored. Namespaces are implemented as " +"dictionaries. There are the local, global and built-in namespaces as well " +"as nested namespaces in objects (in methods). Namespaces support modularity " +"by preventing naming conflicts. For instance, the functions :func:`builtins." +"open <.open>` and :func:`os.open` are distinguished by their namespaces. " +"Namespaces also aid readability and maintainability by making it clear which " +"module implements a function. For instance, writing :func:`random.seed` or :" +"func:`itertools.islice` makes it clear that those functions are implemented " +"by the :mod:`random` and :mod:`itertools` modules, respectively." +msgstr "" +"變數被儲存的地方。命名空間是以 dictionary（字典）被實作。有區域的、全域的及內" +"建的命名空間，而在物件中（在 method 中）也有巢狀的命名空間。命名空間藉由防止" +"命名衝突，來支援模組化。例如，函式 :func:`builtins.open <.open>` 和 :func:" +"`os.open` 是透過它們的命名空間來區分彼此。命名空間也藉由明確地區分是哪個模組" +"在實作一個函式，來增進可讀性及可維護性。例如，寫出 :func:`random.seed` 或 :" +"func:`itertools.islice` 明確地表示，這些函式分別是由 :mod:`random` 和 :mod:" +"`itertools` 模組在實作。" + +#: ../../glossary.rst:1058 +msgid "namespace package" +msgstr "namespace package（命名空間套件）" + +#: ../../glossary.rst:1060 +msgid "" +"A :term:`package` which serves only as a container for subpackages. " +"Namespace packages may have no physical representation, and specifically are " +"not like a :term:`regular package` because they have no ``__init__.py`` file." +msgstr "" +"一個 :term:`package`\\ （套件），它只能作為子套件 (subpackage) 的一個容器。命" +"名空間套件可能沒有實體的表示法，而且具體來說它們不像是一個 :term:`regular " +"package`\\ （正規套件），因為它們並沒有 ``__init__.py`` 這個檔案。" + +#: ../../glossary.rst:1065 +msgid "" +"Namespace packages allow several individually installable packages to have a " +"common parent package. Otherwise, it is recommended to use a :term:`regular " +"package`." +msgstr "" +"命名空間套件允許數個可獨立安裝的套件擁有一個共同的父套件。除此之外，建議使" +"用 :term:`regular package`。" + +#: ../../glossary.rst:1068 +msgid "" +"For more information, see :pep:`420` and :ref:`reference-namespace-package`." +msgstr "更多資訊，請參閱 :pep:`420` 和 :ref:`reference-namespace-package`。" + +#: ../../glossary.rst:1070 +msgid "See also :term:`module`." +msgstr "另請參閱 :term:`module`\\ （模組）。" + +#: ../../glossary.rst:1071 +msgid "native code" +msgstr "" + +#: ../../glossary.rst:1073 +msgid "" +"Code that is compiled to machine instructions and runs directly on the " +"processor, as opposed to code that is interpreted or runs in a virtual " +"machine. In the context of Python, native code typically refers to C, C++, " +"Rust or Fortran code in :term:`extension modules ` that " +"can be called from Python. See also :term:`extension module`." +msgstr "" + +#: ../../glossary.rst:1078 +msgid "nested scope" +msgstr "nested scope（巢狀作用域）" + +#: ../../glossary.rst:1080 +msgid "" +"The ability to refer to a variable in an enclosing definition. For " +"instance, a function defined inside another function can refer to variables " +"in the outer function. Note that nested scopes by default work only for " +"reference and not for assignment. Local variables both read and write in " +"the innermost scope. Likewise, global variables read and write to the " +"global namespace. The :keyword:`nonlocal` allows writing to outer scopes." +msgstr "" +"能夠參照外層定義 (enclosing definition) 中的變數的能力。舉例來說，一個函式如" +"果是在另一個函式中被定義，則它便能夠參照外層函式中的變數。請注意，在預設情況" +"下，巢狀作用域僅適用於參照，而無法用於賦值。區域變數能在最內層作用域中讀取及" +"寫入。同樣地，全域變數是在全域命名空間中讀取及寫入。:keyword:`nonlocal` 容許" +"對外層作用域進行寫入。" + +#: ../../glossary.rst:1087 +msgid "new-style class" +msgstr "new-style class（新式類別）" + +#: ../../glossary.rst:1089 +msgid "" +"Old name for the flavor of classes now used for all class objects. In " +"earlier Python versions, only new-style classes could use Python's newer, " +"versatile features like :attr:`~object.__slots__`, descriptors, properties, :" +"meth:`~object.__getattribute__`, class methods, and static methods." +msgstr "" +"一個舊名，它是指現在所有的 class 物件所使用的 class 風格。在早期的 Python 版" +"本中，只有新式 class 才能使用 Python 較新的、多樣的功能，像是 :attr:`~object." +"__slots__`、描述器 (descriptor)、屬性 (property)、:meth:`~object." +"__getattribute__`、class method（類別方法）和 static method（靜態方法）。" + +#: ../../glossary.rst:1094 +msgid "non-deterministic" +msgstr "" + +#: ../../glossary.rst:1096 +msgid "" +"Behavior where the outcome of a program can vary between executions with the " +"same inputs. In multi-threaded programs, non-deterministic behavior often " +"results from :term:`race conditions ` where the relative " +"timing or interleaving of threads affects the result. Proper synchronization " +"using :term:`locks ` and other :term:`synchronization primitives " +"` helps ensure deterministic behavior." +msgstr "" + +#: ../../glossary.rst:1103 +msgid "object" +msgstr "object（物件）" + +#: ../../glossary.rst:1105 +msgid "" +"Any data with state (attributes or value) and defined behavior (methods). " +"Also the ultimate base class of any :term:`new-style class`." +msgstr "" +"具有狀態（屬性或值）及被定義的行為（method）的任何資料。它也是任何 :term:" +"`new-style class`\\ （新式類別）的最終 base class（基底類別）。" + +#: ../../glossary.rst:1108 +msgid "optimized scope" +msgstr "optimized scope（最佳化作用域）" + +#: ../../glossary.rst:1110 +msgid "" +"A scope where target local variable names are reliably known to the compiler " +"when the code is compiled, allowing optimization of read and write access to " +"these names. The local namespaces for functions, generators, coroutines, " +"comprehensions, and generator expressions are optimized in this fashion. " +"Note: most interpreter optimizations are applied to all scopes, only those " +"relying on a known set of local and nonlocal variable names are restricted " +"to optimized scopes." +msgstr "" + +#: ../../glossary.rst:1117 +msgid "optional module" +msgstr "optional module（可選模組）" + +#: ../../glossary.rst:1119 +msgid "" +"An :term:`extension module` that is part of the :term:`standard library`, " +"but may be absent in some builds of :term:`CPython`, usually due to missing " +"third-party libraries or because the module is not available for a given " +"platform." +msgstr "" + +#: ../../glossary.rst:1124 +msgid "" +"See :ref:`optional-module-requirements` for a list of optional modules that " +"require third-party libraries." +msgstr "" + +#: ../../glossary.rst:1126 +msgid "package" +msgstr "package（套件）" + +#: ../../glossary.rst:1128 +msgid "" +"A Python :term:`module` which can contain submodules or recursively, " +"subpackages. Technically, a package is a Python module with a ``__path__`` " +"attribute." +msgstr "" +"一個 Python 的 :term:`module`\\ （模組），它可以包含子模組 (submodule) 或是遞" +"迴的子套件 (subpackage)。技術上而言，套件就是具有 ``__path__`` 屬性的一個 " +"Python 模組。" + +#: ../../glossary.rst:1132 +msgid "See also :term:`regular package` and :term:`namespace package`." +msgstr "" +"另請參閱 :term:`regular package`\\ （正規套件）和 :term:`namespace " +"package`\\ （命名空間套件）。" + +#: ../../glossary.rst:1133 +msgid "parallelism" +msgstr "" + +#: ../../glossary.rst:1135 +msgid "" +"Executing multiple operations at the same time (e.g. on multiple CPU " +"cores). In Python builds with the :term:`global interpreter lock (GIL) " +"`, only one thread runs Python bytecode at a time, " +"so taking advantage of multiple CPU cores typically involves multiple " +"processes (e.g. :mod:`multiprocessing`) or native extensions that release " +"the GIL. In :term:`free-threaded ` Python, multiple Python " +"threads can run Python code simultaneously on different cores." +msgstr "" + +#: ../../glossary.rst:1143 +msgid "parameter" +msgstr "parameter（參數）" + +#: ../../glossary.rst:1145 +msgid "" +"A named entity in a :term:`function` (or method) definition that specifies " +"an :term:`argument` (or in some cases, arguments) that the function can " +"accept. There are five kinds of parameter:" +msgstr "" +"在 :term:`function`\\ （函式）或 method 定義中的一個命名實體 (named entity)，" +"它指明該函式能夠接受的一個 :term:`argument`\\ （引數），或在某些情況下指示多" +"個引數。共有有五種不同的參數類型：" + +#: ../../glossary.rst:1149 +msgid "" +":dfn:`positional-or-keyword`: specifies an argument that can be passed " +"either :term:`positionally ` or as a :term:`keyword argument " +"`. This is the default kind of parameter, for example *foo* and " +"*bar* in the following::" +msgstr "" +":dfn:`positional-or-keyword`\\ （位置或關鍵字）：指明一個可以\\ :term:`按照位" +"置 `\\ 或是作為\\ :term:`關鍵字引數 `\\ 被傳遞的引數。這" +"是參數的預設類型，例如以下的 *foo* 和 *bar*： ::" + +#: ../../glossary.rst:1154 +msgid "def func(foo, bar=None): ..." +msgstr "def func(foo, bar=None): ..." + +#: ../../glossary.rst:1158 +msgid "" +":dfn:`positional-only`: specifies an argument that can be supplied only by " +"position. Positional-only parameters can be defined by including a ``/`` " +"character in the parameter list of the function definition after them, for " +"example *posonly1* and *posonly2* in the following::" +msgstr "" +":dfn:`positional-only`\\ （僅限位置）：指明一個只能按照位置被提供的引數。在函" +"式定義的參數列表中包含一個 ``/`` 字元，就可以在該字元前面定義僅限位置參數，例" +"如以下的 *posonly1* 和 *posonly2*： ::" + +#: ../../glossary.rst:1163 +msgid "def func(posonly1, posonly2, /, positional_or_keyword): ..." +msgstr "def func(posonly1, posonly2, /, positional_or_keyword): ..." + +#: ../../glossary.rst:1167 +msgid "" +":dfn:`keyword-only`: specifies an argument that can be supplied only by " +"keyword. Keyword-only parameters can be defined by including a single var-" +"positional parameter or bare ``*`` in the parameter list of the function " +"definition before them, for example *kw_only1* and *kw_only2* in the " +"following::" +msgstr "" +":dfn:`keyword-only`\\ （僅限關鍵字）：指明一個只能以關鍵字被提供的引數。在函" +"式定義的參數列表中，包含一個任意數量位置參數 (var-positional parameter) 或是" +"單純的 ``*`` 字元，就可以在其後方定義僅限關鍵字參數，例如以下的 *kw_only1* " +"和 *kw_only2*： ::" + +#: ../../glossary.rst:1173 +msgid "def func(arg, *, kw_only1, kw_only2): ..." +msgstr "def func(arg, *, kw_only1, kw_only2): ..." + +#: ../../glossary.rst:1175 +msgid "" +":dfn:`var-positional`: specifies that an arbitrary sequence of positional " +"arguments can be provided (in addition to any positional arguments already " +"accepted by other parameters). Such a parameter can be defined by " +"prepending the parameter name with ``*``, for example *args* in the " +"following::" +msgstr "" +":dfn:`var-positional`\\ （任意數量位置）：指明一串能以任意序列被提供的位置引" +"數（在已被其他參數接受的任何位置引數之外）。這類參數是透過在其參數名稱字首加" +"上 ``*`` 來定義的，例如以下的 *args*： ::" + +#: ../../glossary.rst:1181 +msgid "def func(*args, **kwargs): ..." +msgstr "def func(*args, **kwargs): ..." + +#: ../../glossary.rst:1183 +msgid "" +":dfn:`var-keyword`: specifies that arbitrarily many keyword arguments can be " +"provided (in addition to any keyword arguments already accepted by other " +"parameters). Such a parameter can be defined by prepending the parameter " +"name with ``**``, for example *kwargs* in the example above." +msgstr "" +":dfn:`var-keyword`\\ （任意數量關鍵字）：指明可被提供的任意數量關鍵字引數（在" +"已被其他參數接受的任何關鍵字引數之外）。這類參數是透過在其參數名稱字首加上 " +"``**`` 來定義的，例如上面範例中的 *kwargs*。" + +#: ../../glossary.rst:1189 +msgid "" +"Parameters can specify both optional and required arguments, as well as " +"default values for some optional arguments." +msgstr "" +"參數可以指明引數是選擇性的或必需的，也可以為一些選擇性的引數指定預設值。" + +#: ../../glossary.rst:1192 +msgid "" +"See also the :term:`argument` glossary entry, the FAQ question on :ref:`the " +"difference between arguments and parameters `, " +"the :class:`inspect.Parameter` class, the :ref:`function` section, and :pep:" +"`362`." +msgstr "" +"另請參閱術語表的 :term:`argument`\\ （引數）條目、常見問題中的\\ :ref:`引數和" +"參數之間的差異 `、:class:`inspect.Parameter` " +"class、:ref:`function`\\ 章節，以及 :pep:`362`。" + +#: ../../glossary.rst:1196 +msgid "path entry" +msgstr "path entry（路徑項目）" + +#: ../../glossary.rst:1198 +msgid "" +"A single location on the :term:`import path` which the :term:`path based " +"finder` consults to find modules for importing." +msgstr "" +"在 :term:`import path`\\ （引入路徑）中的一個位置，而 :term:`path based " +"finder` （基於路徑的尋檢器）會參考該位置來尋找要 import 的模組。" + +#: ../../glossary.rst:1200 +msgid "path entry finder" +msgstr "path entry finder（路徑項目尋檢器）" + +#: ../../glossary.rst:1202 +msgid "" +"A :term:`finder` returned by a callable on :data:`sys.path_hooks` (i.e. a :" +"term:`path entry hook`) which knows how to locate modules given a :term:" +"`path entry`." +msgstr "" +"被 :data:`sys.path_hooks` 中的一個可呼叫物件 (callable)（意即一個 :term:" +"`path entry hook`\\ ）所回傳的一種 :term:`finder`，它知道如何以一個 :term:" +"`path entry`\\ 定位模組。" + +#: ../../glossary.rst:1206 +msgid "" +"See :class:`importlib.abc.PathEntryFinder` for the methods that path entry " +"finders implement." +msgstr "" +"關於路徑項目尋檢器實作的 method，請參閱 :class:`importlib.abc." +"PathEntryFinder`。" + +#: ../../glossary.rst:1208 +msgid "path entry hook" +msgstr "path entry hook（路徑項目鉤）" + +#: ../../glossary.rst:1210 +msgid "" +"A callable on the :data:`sys.path_hooks` list which returns a :term:`path " +"entry finder` if it knows how to find modules on a specific :term:`path " +"entry`." +msgstr "" +"在 :data:`sys.path_hooks` 列表中的一個可呼叫物件 (callable)，若它知道如何在一" +"個特定的 :term:`path entry` 中尋找模組，則會回傳一個 :term:`path entry " +"finder`\\ （路徑項目尋檢器）。" + +#: ../../glossary.rst:1213 +msgid "path based finder" +msgstr "path based finder（基於路徑的尋檢器）" + +#: ../../glossary.rst:1215 +msgid "" +"One of the default :term:`meta path finders ` which " +"searches an :term:`import path` for modules." +msgstr "" +"預設的\\ :term:`元路徑尋檢器 (meta path finder) ` 之一，它" +"會在一個 :term:`import path` 中搜尋模組。" + +#: ../../glossary.rst:1217 +msgid "path-like object" +msgstr "path-like object（類路徑物件）" + +#: ../../glossary.rst:1219 +msgid "" +"An object representing a file system path. A path-like object is either a :" +"class:`str` or :class:`bytes` object representing a path, or an object " +"implementing the :class:`os.PathLike` protocol. An object that supports the :" +"class:`os.PathLike` protocol can be converted to a :class:`str` or :class:" +"`bytes` file system path by calling the :func:`os.fspath` function; :func:" +"`os.fsdecode` and :func:`os.fsencode` can be used to guarantee a :class:" +"`str` or :class:`bytes` result instead, respectively. Introduced by :pep:" +"`519`." +msgstr "" +"一個表示檔案系統路徑的物件。類路徑物件可以是一個表示路徑的 :class:`str` 或 :" +"class:`bytes` 物件，或是一個實作 :class:`os.PathLike` 協定的物件。透過呼叫 :" +"func:`os.fspath` 函式，一個支援 :class:`os.PathLike` 協定的物件可以被轉換為 :" +"class:`str` 或 :class:`bytes` 檔案系統路徑；而 :func:`os.fsdecode` 及 :func:" +"`os.fsencode` 則分別可用於確保 :class:`str` 及 :class:`bytes` 的結果。由 :" +"pep:`519` 引入。" + +#: ../../glossary.rst:1227 +msgid "PEP" +msgstr "PEP" + +#: ../../glossary.rst:1229 +msgid "" +"Python Enhancement Proposal. A PEP is a design document providing " +"information to the Python community, or describing a new feature for Python " +"or its processes or environment. PEPs should provide a concise technical " +"specification and a rationale for proposed features." +msgstr "" +"Python Enhancement Proposal（Python 增強提案）。PEP 是一份設計說明文件，它能" +"為 Python 社群提供資訊，或是描述 Python 的一個新功能或該功能的程序和環境。" +"PEP 應該要提供簡潔的技術規範以及被提案功能的運作原理。" + +#: ../../glossary.rst:1235 +msgid "" +"PEPs are intended to be the primary mechanisms for proposing major new " +"features, for collecting community input on an issue, and for documenting " +"the design decisions that have gone into Python. The PEP author is " +"responsible for building consensus within the community and documenting " +"dissenting opinions." +msgstr "" +"PEP 的存在目的，是要成為重大新功能的提案、社群中關於某個問題的意見收集，以及" +"已納入 Python 的設計決策的記錄，這些過程的主要機制。PEP 的作者要負責在社群內" +"建立共識並記錄反對意見。" + +#: ../../glossary.rst:1241 +msgid "See :pep:`1`." +msgstr "請參閱 :pep:`1`。" + +#: ../../glossary.rst:1242 +msgid "portion" +msgstr "portion（部分）" + +#: ../../glossary.rst:1244 +msgid "" +"A set of files in a single directory (possibly stored in a zip file) that " +"contribute to a namespace package, as defined in :pep:`420`." +msgstr "" +"在單一目錄中的一組檔案（也可能儲存在一個 zip 檔中），這些檔案能對一個命名空間" +"套件 (namespace package) 有所貢獻，如同 :pep:`420` 中的定義。" + +#: ../../glossary.rst:1246 +msgid "positional argument" +msgstr "positional argument（位置引數）" + +#: ../../glossary.rst:1249 +msgid "provisional API" +msgstr "provisional API（暫行 API）" + +#: ../../glossary.rst:1251 +msgid "" +"A provisional API is one which has been deliberately excluded from the " +"standard library's backwards compatibility guarantees. While major changes " +"to such interfaces are not expected, as long as they are marked provisional, " +"backwards incompatible changes (up to and including removal of the " +"interface) may occur if deemed necessary by core developers. Such changes " +"will not be made gratuitously -- they will occur only if serious fundamental " +"flaws are uncovered that were missed prior to the inclusion of the API." +msgstr "" +"暫行 API 是指，從標準函式庫的向後相容性 (backwards compatibility) 保證中，故" +"意被排除的 API。雖然此類介面，只要它們被標示為暫行的，理論上並不會有重大的變" +"更，但如果核心開發人員認為有必要，也可能會出現向後不相容的變更（甚至包括移除" +"該介面）。這種變更並不會無端地產生——只有 API 被納入之前未察覺的嚴重基本缺陷被" +"揭露時，它們才會發生。" + +#: ../../glossary.rst:1260 +msgid "" +"Even for provisional APIs, backwards incompatible changes are seen as a " +"\"solution of last resort\" - every attempt will still be made to find a " +"backwards compatible resolution to any identified problems." +msgstr "" +"即使對於暫行 API，向後不相容的變更也會被視為「最後的解決方案」——對於任何被發" +"現的問題，仍然會盡可能找出一個向後相容的解決方案。" + +#: ../../glossary.rst:1264 +msgid "" +"This process allows the standard library to continue to evolve over time, " +"without locking in problematic design errors for extended periods of time. " +"See :pep:`411` for more details." +msgstr "" +"這個過程使得標準函式庫能隨著時間不斷進化，而避免耗費過長的時間去鎖定有問題的" +"設計錯誤。請參閱 :pep:`411` 了解更多細節。" + +#: ../../glossary.rst:1267 +msgid "provisional package" +msgstr "provisional package（暫行套件）" + +#: ../../glossary.rst:1269 +msgid "See :term:`provisional API`." +msgstr "請參閱 :term:`provisional API`\\ （暫行 API）。" + +#: ../../glossary.rst:1270 +msgid "Python 3000" +msgstr "Python 3000" + +#: ../../glossary.rst:1272 +msgid "" +"Nickname for the Python 3.x release line (coined long ago when the release " +"of version 3 was something in the distant future.) This is also abbreviated " +"\"Py3k\"." +msgstr "" +"Python 3.x 系列版本的暱稱（很久以前創造的，當時第 3 版的發布是在遙遠的未" +"來。）也可以縮寫為「Py3k」。" + +#: ../../glossary.rst:1275 +msgid "Pythonic" +msgstr "Pythonic（Python 風格的）" + +#: ../../glossary.rst:1277 +msgid "" +"An idea or piece of code which closely follows the most common idioms of the " +"Python language, rather than implementing code using concepts common to " +"other languages. For example, a common idiom in Python is to loop over all " +"elements of an iterable using a :keyword:`for` statement. Many other " +"languages don't have this type of construct, so people unfamiliar with " +"Python sometimes use a numerical counter instead::" +msgstr "" +"一個想法或一段程式碼，它應用了 Python 語言最常見的慣用語，而不是使用其他語言" +"常見的概念來實作程式碼。例如，Python 中常見的一種習慣用法，是使用一個 :" +"keyword:`for` 陳述式，對一個可疊代物件的所有元素進行迴圈。許多其他語言並沒有" +"這種類型的架構，所以不熟悉 Python 的人有時會使用一個數值計數器來代替： ::" + +#: ../../glossary.rst:1284 +msgid "" +"for i in range(len(food)):\n" +" print(food[i])" +msgstr "" +"for i in range(len(food)):\n" +" print(food[i])" + +#: ../../glossary.rst:1287 +msgid "As opposed to the cleaner, Pythonic method::" +msgstr "相較之下，以下方法更簡潔、更具有 Python 風格： ::" + +#: ../../glossary.rst:1289 +msgid "" +"for piece in food:\n" +" print(piece)" +msgstr "" +"for piece in food:\n" +" print(piece)" + +#: ../../glossary.rst:1291 +msgid "qualified name" +msgstr "qualified name（限定名稱）" + +#: ../../glossary.rst:1293 +msgid "" +"A dotted name showing the \"path\" from a module's global scope to a class, " +"function or method defined in that module, as defined in :pep:`3155`. For " +"top-level functions and classes, the qualified name is the same as the " +"object's name::" +msgstr "" +"一個「點分隔名稱」，它顯示從一個模組的全域作用域到該模組中定義的 class、函式" +"或 method 的「路徑」，如 :pep:`3155` 中的定義。對於頂層的函式和 class 而言，" +"限定名稱與其物件名稱相同： ::" + +#: ../../glossary.rst:1298 +msgid "" +">>> class C:\n" +"... class D:\n" +"... def meth(self):\n" +"... pass\n" +"...\n" +">>> C.__qualname__\n" +"'C'\n" +">>> C.D.__qualname__\n" +"'C.D'\n" +">>> C.D.meth.__qualname__\n" +"'C.D.meth'" +msgstr "" +">>> class C:\n" +"... class D:\n" +"... def meth(self):\n" +"... pass\n" +"...\n" +">>> C.__qualname__\n" +"'C'\n" +">>> C.D.__qualname__\n" +"'C.D'\n" +">>> C.D.meth.__qualname__\n" +"'C.D.meth'" + +#: ../../glossary.rst:1310 +msgid "" +"When used to refer to modules, the *fully qualified name* means the entire " +"dotted path to the module, including any parent packages, e.g. ``email.mime." +"text``::" +msgstr "" +"當用於引用模組時，*完全限定名稱 (fully qualified name)* 是表示該模組的完整點" +"分隔路徑，包括任何的父套件，例如 ``email.mime.text``： ::" + +#: ../../glossary.rst:1314 +msgid "" +">>> import email.mime.text\n" +">>> email.mime.text.__name__\n" +"'email.mime.text'" +msgstr "" +">>> import email.mime.text\n" +">>> email.mime.text.__name__\n" +"'email.mime.text'" + +#: ../../glossary.rst:1317 +msgid "race condition" +msgstr "" + +#: ../../glossary.rst:1319 +msgid "" +"A condition of a program where the its behavior depends on the relative " +"timing or ordering of events, particularly in multi-threaded programs. Race " +"conditions can lead to :term:`non-deterministic` behavior and bugs that are " +"difficult to reproduce. A :term:`data race` is a specific type of race " +"condition involving unsynchronized access to shared memory. The :term:" +"`LBYL` coding style is particularly susceptible to race conditions in multi-" +"threaded code. Using :term:`locks ` and other :term:`synchronization " +"primitives ` helps prevent race conditions." +msgstr "" + +#: ../../glossary.rst:1329 +msgid "reference count" +msgstr "reference count（參照計數）" + +#: ../../glossary.rst:1331 +msgid "" +"The number of references to an object. When the reference count of an " +"object drops to zero, it is deallocated. Some objects are :term:`immortal` " +"and have reference counts that are never modified, and therefore the objects " +"are never deallocated. Reference counting is generally not visible to " +"Python code, but it is a key element of the :term:`CPython` implementation. " +"Programmers can call the :func:`sys.getrefcount` function to return the " +"reference count for a particular object." +msgstr "" +"對於一個物件的參照次數。當一個物件的參照計數下降到零時，它會被解除配置 " +"(deallocated)。有些物件是「\\ :term:`不滅的 ` (immortal)」並擁有不" +"會被改變的參照計數，也因此永遠不會被解除配置。參照計數通常在 Python 程式碼中" +"看不到，但它卻是 :term:`CPython` 實作的一個關鍵元素。程式設計師可以呼叫 :" +"func:`~sys.getrefcount` 函式來回傳一個特定物件的參照計數。" + +#: ../../glossary.rst:1340 +msgid "" +"In :term:`CPython`, reference counts are not considered to be stable or well-" +"defined values; the number of references to an object, and how that number " +"is affected by Python code, may be different between versions." +msgstr "" +"在 :term:`CPython` 中，參照計數不被視為穩定或明確定義的值；對物件的參照數量，" +"以及該數量如何受到 Python 程式碼的影響，在不同版本之間可能會有所不同。" + +#: ../../glossary.rst:1344 +msgid "regular package" +msgstr "regular package（正規套件）" + +#: ../../glossary.rst:1346 +msgid "" +"A traditional :term:`package`, such as a directory containing an ``__init__." +"py`` file." +msgstr "" +"一個傳統的 :term:`package`\\ （套件），例如一個包含 ``__init__.py`` 檔案的目" +"錄。" + +#: ../../glossary.rst:1349 +msgid "See also :term:`namespace package`." +msgstr "另請參閱 :term:`namespace package`\\ （命名空間套件）。" + +#: ../../glossary.rst:1350 +msgid "reentrant" +msgstr "" + +#: ../../glossary.rst:1352 +msgid "" +"A property of a function or :term:`lock` that allows it to be called or " +"acquired multiple times by the same thread without causing errors or a :term:" +"`deadlock`." +msgstr "" + +#: ../../glossary.rst:1356 +msgid "" +"For functions, reentrancy means the function can be safely called again " +"before a previous invocation has completed, which is important when " +"functions may be called recursively or from signal handlers. Thread-unsafe " +"functions may be :term:`non-deterministic` if they're called reentrantly in " +"a multithreaded program." +msgstr "" + +#: ../../glossary.rst:1362 +msgid "" +"For locks, Python's :class:`threading.RLock` (reentrant lock) is reentrant, " +"meaning a thread that already holds the lock can acquire it again without " +"blocking. In contrast, :class:`threading.Lock` is not reentrant - " +"attempting to acquire it twice from the same thread will cause a deadlock." +msgstr "" + +#: ../../glossary.rst:1368 +msgid "See also :term:`lock` and :term:`deadlock`." +msgstr "另請參閱 :term:`lock` 和 :term:`deadlock`。" + +#: ../../glossary.rst:1369 +msgid "REPL" +msgstr "REPL" + +#: ../../glossary.rst:1371 +msgid "" +"An acronym for the \"read–eval–print loop\", another name for the :term:" +"`interactive` interpreter shell." +msgstr "" +"「read-eval-print 迴圈 (read–eval–print loop)」的縮寫，是\\ :term:`互動式 " +"`\\ 直譯器 shell 的另一個名稱。" + +#: ../../glossary.rst:1373 +msgid "__slots__" +msgstr "__slots__" + +#: ../../glossary.rst:1375 +msgid "" +"A declaration inside a class that saves memory by pre-declaring space for " +"instance attributes and eliminating instance dictionaries. Though popular, " +"the technique is somewhat tricky to get right and is best reserved for rare " +"cases where there are large numbers of instances in a memory-critical " +"application." +msgstr "" +"在 class 內部的一個宣告，它藉由預先宣告實例屬性的空間，以及消除實例 " +"dictionary（字典），來節省記憶體。雖然該技術很普遍，但它有點難以正確地使用，" +"最好保留給那種在一個記憶體關鍵 (memory-critical) 的應用程式中存在大量實例的罕" +"見情況。" + +#: ../../glossary.rst:1380 +msgid "sequence" +msgstr "sequence（序列）" + +#: ../../glossary.rst:1382 +msgid "" +"An :term:`iterable` which supports efficient element access using integer " +"indices via the :meth:`~object.__getitem__` special method and defines a :" +"meth:`~object.__len__` method that returns the length of the sequence. Some " +"built-in sequence types are :class:`list`, :class:`str`, :class:`tuple`, " +"and :class:`bytes`. Note that :class:`dict` also supports :meth:`~object." +"__getitem__` and :meth:`!__len__`, but is considered a mapping rather than a " +"sequence because the lookups use arbitrary :term:`hashable` keys rather than " +"integers." +msgstr "" +"一個 :term:`iterable`\\ （可疊代物件），它透過 :meth:`~object.__getitem__` " +"special method（特殊方法），使用整數索引來支援高效率的元素存取，並定義了一" +"個 :meth:`~object.__len__` method 來回傳該序列的長度。一些內建序列型別包括 :" +"class:`list`、:class:`str`、:class:`tuple` 和 :class:`bytes`。請注意，雖然 :" +"class:`dict` 也支援 :meth:`~object.__getitem__` 和 :meth:`!__len__`，但它被視" +"為對映 (mapping) 而不是序列，因為其查找方式是使用任意的 :term:`hashable` 鍵，" +"而不是整數。" + +#: ../../glossary.rst:1391 +msgid "" +"The :class:`collections.abc.Sequence` abstract base class defines a much " +"richer interface that goes beyond just :meth:`~object.__getitem__` and :meth:" +"`~object.__len__`, adding :meth:`~sequence.count`, :meth:`~sequence.index`, :" +"meth:`~object.__contains__`, and :meth:`~object.__reversed__`. Types that " +"implement this expanded interface can be registered explicitly using :func:" +"`~abc.ABCMeta.register`. For more documentation on sequence methods " +"generally, see :ref:`Common Sequence Operations `." +msgstr "" +"抽象基底類別 (abstract base class) :class:`collections.abc.Sequence` 定義了一" +"個更加豐富的介面，並不僅止於 :meth:`~object.__getitem__` 和 :meth:`~object." +"__len__`，還增加了 :meth:`~sequence.count`、:meth:`~sequence.index`、:meth:" +"`~object.__contains__` 和 :meth:`~object.__reversed__`。實作此擴充介面的型" +"別，可以使用 :func:`~abc.ABCMeta.register` 被明確地註冊。更多關於序列方法的文" +"件，請見\\ :ref:`常見序列操作 `。" + +#: ../../glossary.rst:1401 +msgid "set comprehension" +msgstr "set comprehension（集合綜合運算）" + +#: ../../glossary.rst:1403 +msgid "" +"A compact way to process all or part of the elements in an iterable and " +"return a set with the results. ``results = {c for c in 'abracadabra' if c " +"not in 'abc'}`` generates the set of strings ``{'r', 'd'}``. See :ref:" +"`comprehensions`." +msgstr "" +"一種緊密的方法，用來處理一個可疊代物件中的全部或部分元素，並將處理結果以一個 " +"set 回傳。``results = {c for c in 'abracadabra' if c not in 'abc'}`` 會產生一" +"個字串 set：``{'r', 'd'}``。請參閱\\ :ref:`comprehensions`。" + +#: ../../glossary.rst:1407 +msgid "single dispatch" +msgstr "single dispatch（單一調度）" + +#: ../../glossary.rst:1409 +msgid "" +"A form of :term:`generic function` dispatch where the implementation is " +"chosen based on the type of a single argument." +msgstr "" +":term:`generic function`\\ （泛型函式）調度的一種形式，在此，實作的選擇是基於" +"單一引數的型別。" + +#: ../../glossary.rst:1411 +msgid "slice" +msgstr "slice（切片）" + +#: ../../glossary.rst:1413 +msgid "" +"An object usually containing a portion of a :term:`sequence`. A slice is " +"created using the subscript notation, ``[]`` with colons between numbers " +"when several are given, such as in ``variable_name[1:3:5]``. The bracket " +"(subscript) notation uses :class:`slice` objects internally." +msgstr "" +"一個物件，它通常包含一段 :term:`sequence`\\ （序列）的某一部分。建立一段切片" +"的方法是使用下標符號 (subscript notation) ``[]``，若要給出多個數字，則在數字" +"之間使用冒號，例如 ``variable_name[1:3:5]``。在括號（下標）符號的內部，會使" +"用 :class:`slice` 物件。" + +#: ../../glossary.rst:1417 +msgid "soft deprecated" +msgstr "soft deprecated（軟性棄用）" + +#: ../../glossary.rst:1419 +msgid "" +"A soft deprecated API should not be used in new code, but it is safe for " +"already existing code to use it. The API remains documented and tested, but " +"will not be enhanced further." +msgstr "" +"被軟性棄用的 API 代表不應再用於新程式碼中，但在現有程式碼中繼續使用它仍會是安" +"全的。API 仍會以文件記錄並會被測試，但不會被繼續改進。" + +#: ../../glossary.rst:1423 +msgid "" +"Soft deprecation, unlike normal deprecation, does not plan on removing the " +"API and will not emit warnings." +msgstr "與正常棄用不同，軟性棄用沒有刪除 API 的規劃，也不會發出警告。" + +#: ../../glossary.rst:1426 +msgid "" +"See `PEP 387: Soft Deprecation `_." +msgstr "" +"請參閱 `PEP 387：軟性棄用 `_。" + +#: ../../glossary.rst:1428 +msgid "special method" +msgstr "special method（特殊方法）" + +#: ../../glossary.rst:1432 +msgid "" +"A method that is called implicitly by Python to execute a certain operation " +"on a type, such as addition. Such methods have names starting and ending " +"with double underscores. Special methods are documented in :ref:" +"`specialnames`." +msgstr "" +"一種會被 Python 自動呼叫的 method，用於對某種型別執行某種運算，例如加法。這" +"種 method 的名稱會在開頭和結尾有兩個下底線。Special method 在\\ :ref:" +"`specialnames`\\ 中有詳細說明。" + +#: ../../glossary.rst:1436 +msgid "standard library" +msgstr "標準函式庫" + +#: ../../glossary.rst:1438 +msgid "" +"The collection of :term:`packages `, :term:`modules ` and :" +"term:`extension modules ` distributed as a part of the " +"official Python interpreter package. The exact membership of the collection " +"may vary based on platform, available system libraries, or other criteria. " +"Documentation can be found at :ref:`library-index`." +msgstr "" +"包含\\ :term:`套件 `、:term:`模組 `\\ 和\\ :term:`擴充模組 " +"`\\ 的集合，它們是作為官方 Python 直譯器套件的一部分來發" +"行。該集合的成員可能會因平台、可用的系統函式庫或其他條件而有所不同。相關文件" +"可以在 :ref:`library-index` 中找到。" + +#: ../../glossary.rst:1444 +msgid "" +"See also :data:`sys.stdlib_module_names` for a list of all possible standard " +"library module names." +msgstr "" +"請參閱 :data:`sys.stdlib_module_names` 以取得所有可能的標準函式庫模組名稱的列" +"表。" + +#: ../../glossary.rst:1446 +msgid "statement" +msgstr "statement（陳述式）" + +#: ../../glossary.rst:1448 +msgid "" +"A statement is part of a suite (a \"block\" of code). A statement is either " +"an :term:`expression` or one of several constructs with a keyword, such as :" +"keyword:`if`, :keyword:`while` or :keyword:`for`." +msgstr "" +"陳述式是一個套組（suite，一個程式碼「區塊」）中的一部分。陳述式可以是一個 :" +"term:`expression`\\ （運算式），或是含有關鍵字（例如 :keyword:`if`、:keyword:" +"`while` 或 :keyword:`for`\\ ）的多種結構之一。" + +#: ../../glossary.rst:1451 +msgid "static type checker" +msgstr "static type checker（靜態型別檢查器）" + +#: ../../glossary.rst:1453 +msgid "" +"An external tool that reads Python code and analyzes it, looking for issues " +"such as incorrect types. See also :term:`type hints ` and the :" +"mod:`typing` module." +msgstr "" +"會讀取 Python 程式碼並分析的外部工具，能夠找出錯誤，像是使用了不正確的型別。" +"另請參閱\\ :term:`型別提示 (type hints) ` 以及 :mod:`typing` 模" +"組。" + +#: ../../glossary.rst:1456 +msgid "stdlib" +msgstr "stdlib（標準函式庫）" + +#: ../../glossary.rst:1458 +msgid "An abbreviation of :term:`standard library`." +msgstr ":term:`standard library` 的縮寫。" + +#: ../../glossary.rst:1459 +msgid "strong reference" +msgstr "strong reference（強參照）" + +#: ../../glossary.rst:1461 +msgid "" +"In Python's C API, a strong reference is a reference to an object which is " +"owned by the code holding the reference. The strong reference is taken by " +"calling :c:func:`Py_INCREF` when the reference is created and released with :" +"c:func:`Py_DECREF` when the reference is deleted." +msgstr "" +"在 Python 的 C API 中，強參照是對物件的參照，該物件為持有該參照的程式碼所擁" +"有。建立參照時透過呼叫 :c:func:`Py_INCREF` 來獲得強參照、刪除參照時透過 :c:" +"func:`Py_DECREF` 釋放強參照。" + +#: ../../glossary.rst:1467 +msgid "" +"The :c:func:`Py_NewRef` function can be used to create a strong reference to " +"an object. Usually, the :c:func:`Py_DECREF` function must be called on the " +"strong reference before exiting the scope of the strong reference, to avoid " +"leaking one reference." +msgstr "" +":c:func:`Py_NewRef` 函式可用於建立一個對物件的強參照。通常，在退出強參照的作" +"用域之前，必須在該強參照上呼叫 :c:func:`Py_DECREF` 函式，以避免洩漏一個參照。" + +#: ../../glossary.rst:1472 +msgid "See also :term:`borrowed reference`." +msgstr "另請參閱 :term:`borrowed reference`\\ （借用參照）。" + +#: ../../glossary.rst:1473 +msgid "synchronization primitive" +msgstr "" + +#: ../../glossary.rst:1475 +msgid "" +"A basic building block for coordinating (synchronizing) the execution of " +"multiple threads to ensure :term:`thread-safe` access to shared resources. " +"Python's :mod:`threading` module provides several synchronization primitives " +"including :class:`~threading.Lock`, :class:`~threading.RLock`, :class:" +"`~threading.Semaphore`, :class:`~threading.Condition`, :class:`~threading." +"Event`, and :class:`~threading.Barrier`. Additionally, the :mod:`queue` " +"module provides multi-producer, multi-consumer queues that are especially " +"useful in multithreaded programs. These primitives help prevent :term:`race " +"conditions ` and coordinate thread execution. See also :" +"term:`lock`." +msgstr "" + +#: ../../glossary.rst:1485 +msgid "t-string" +msgstr "t-string（t 字串）" + +#: ../../glossary.rst:1486 +msgid "t-strings" +msgstr "t-strings（t 字串）" + +#: ../../glossary.rst:1488 +msgid "" +"String literals prefixed with ``t`` or ``T`` are commonly called \"t-" +"strings\" which is short for :ref:`template string literals `." +msgstr "" +"以 ``t`` 或 ``T`` 為前綴的字串文本通常被稱為「t 字串」，它是\\ :ref:`模板化的" +"字串文本 `\\ 的縮寫。" + +#: ../../glossary.rst:1491 +msgid "text encoding" +msgstr "text encoding（文字編碼）" + +#: ../../glossary.rst:1493 +msgid "" +"A string in Python is a sequence of Unicode code points (in range " +"``U+0000``--``U+10FFFF``). To store or transfer a string, it needs to be " +"serialized as a sequence of bytes." +msgstr "" +"Python 中的字串是一個 Unicode 編碼位置 (code point) 的序列（範圍在 " +"``U+0000`` -- ``U+10FFFF`` 之間）。若要儲存或傳送一個字串，它必須被序列化為一" +"個位元組序列。" + +#: ../../glossary.rst:1497 +msgid "" +"Serializing a string into a sequence of bytes is known as \"encoding\", and " +"recreating the string from the sequence of bytes is known as \"decoding\"." +msgstr "" +"將一個字串序列化為位元組序列，稱為「編碼」，而從位元組序列重新建立該字串則稱" +"為「解碼 (decoding)」。" + +#: ../../glossary.rst:1500 +msgid "" +"There are a variety of different text serialization :ref:`codecs `, which are collectively referred to as \"text encodings\"." +msgstr "" +"有多種不同的文字序列化編解碼器 (:ref:`codecs `)，它們被統" +"稱為「文字編碼」。" + +#: ../../glossary.rst:1503 +msgid "text file" +msgstr "text file（文字檔案）" + +#: ../../glossary.rst:1505 +msgid "" +"A :term:`file object` able to read and write :class:`str` objects. Often, a " +"text file actually accesses a byte-oriented datastream and handles the :term:" +"`text encoding` automatically. Examples of text files are files opened in " +"text mode (``'r'`` or ``'w'``), :data:`sys.stdin`, :data:`sys.stdout`, and " +"instances of :class:`io.StringIO`." +msgstr "" +"一個能夠讀取和寫入 :class:`str` 物件的一個 :term:`file object`\\ （檔案物" +"件）。通常，文字檔案實際上是存取位元組導向的資料流 (byte-oriented " +"datastream) 並會自動處理 :term:`text encoding`\\ （文字編碼）。文字檔案的例子" +"有：以文字模式（``'r'`` 或 ``'w'``）開啟的檔案、:data:`sys.stdin`、:data:" +"`sys.stdout` 以及 :class:`io.StringIO` 的實例。" + +#: ../../glossary.rst:1512 +msgid "" +"See also :term:`binary file` for a file object able to read and write :term:" +"`bytes-like objects `." +msgstr "" +"另請參閱 :term:`binary file`\\ （二進位檔案），它是一個能夠讀取和寫入\\ :" +"term:`類位元組串物件 (bytes-like object) ` 的檔案物件。" + +#: ../../glossary.rst:1514 +msgid "thread state" +msgstr "" + +#: ../../glossary.rst:1517 +msgid "" +"The information used by the :term:`CPython` runtime to run in an OS thread. " +"For example, this includes the current exception, if any, and the state of " +"the bytecode interpreter." +msgstr "" + +#: ../../glossary.rst:1521 +msgid "" +"Each thread state is bound to a single OS thread, but threads may have many " +"thread states available. At most, one of them may be :term:`attached " +"` at once." +msgstr "" + +#: ../../glossary.rst:1525 +msgid "" +"An :term:`attached thread state` is required to call most of Python's C API, " +"unless a function explicitly documents otherwise. The bytecode interpreter " +"only runs under an attached thread state." +msgstr "" + +#: ../../glossary.rst:1529 +msgid "" +"Each thread state belongs to a single interpreter, but each interpreter may " +"have many thread states, including multiple for the same OS thread. Thread " +"states from multiple interpreters may be bound to the same thread, but only " +"one can be :term:`attached ` in that thread at any " +"given moment." +msgstr "" + +#: ../../glossary.rst:1535 +msgid "" +"See :ref:`Thread State and the Global Interpreter Lock ` for more " +"information." +msgstr "" + +#: ../../glossary.rst:1537 +msgid "thread-safe" +msgstr "" + +#: ../../glossary.rst:1539 +msgid "" +"A module, function, or class that behaves correctly when used by multiple " +"threads concurrently. Thread-safe code uses appropriate :term:" +"`synchronization primitives ` like :term:`locks " +"` to protect shared mutable state, or is designed to avoid shared " +"mutable state entirely. In the :term:`free-threaded ` " +"build, built-in types like :class:`dict`, :class:`list`, and :class:`set` " +"use internal locking to make many operations thread-safe, although thread " +"safety is not necessarily guaranteed. Code that is not thread-safe may " +"experience :term:`race conditions ` and :term:`data races " +"` when used in multi-threaded programs." +msgstr "" + +#: ../../glossary.rst:1550 +msgid "token" +msgstr "token" + +#: ../../glossary.rst:1553 +msgid "" +"A small unit of source code, generated by the :ref:`lexical analyzer " +"` (also called the *tokenizer*). Names, numbers, strings, " +"operators, newlines and similar are represented by tokens." +msgstr "" +"原始碼的小單位，由 :ref:`詞法分析器 ` （也稱為 *tokenizer*）產生。名" +"稱、數字、字串、運算子、換行符號等都以 token 表示。" + +#: ../../glossary.rst:1558 +msgid "" +"The :mod:`tokenize` module exposes Python's lexical analyzer. The :mod:" +"`token` module contains information on the various types of tokens." +msgstr "" +":mod:`tokenize` 模組公開了 Python 的詞法分析器。:mod:`token` 模組包含各種 " +"token 類型的資訊。" + +#: ../../glossary.rst:1561 +msgid "triple-quoted string" +msgstr "triple-quoted string（三引號內字串）" + +#: ../../glossary.rst:1563 +msgid "" +"A string which is bound by three instances of either a quotation mark (\") " +"or an apostrophe ('). While they don't provide any functionality not " +"available with single-quoted strings, they are useful for a number of " +"reasons. They allow you to include unescaped single and double quotes " +"within a string and they can span multiple lines without the use of the " +"continuation character, making them especially useful when writing " +"docstrings." +msgstr "" +"由三個雙引號 (\") 或單引號 (') 的作為邊界的一個字串。雖然它們並沒有提供異於單" +"引號字串的任何額外功能，但基於許多原因，它們仍是很有用的。它們讓你可以在字串" +"中包含未跳脫 (unescaped) 的單引號和雙引號，而且它們不需使用連續字元 " +"(continuation character) 就可以跨越多行，這使得它們在編寫說明字串時特別有用。" + +#: ../../glossary.rst:1570 +msgid "type" +msgstr "type（型別）" + +#: ../../glossary.rst:1572 +msgid "" +"The type of a Python object determines what kind of object it is; every " +"object has a type. An object's type is accessible as its :attr:`~object." +"__class__` attribute or can be retrieved with ``type(obj)``." +msgstr "" +"一個 Python 物件的型別決定了它是什麼類型的物件；每個物件都有一個型別。一個物" +"件的型別可以用它的 :attr:`~object.__class__` 屬性來存取，或以 ``type(obj)`` " +"來檢索。" + +#: ../../glossary.rst:1576 +msgid "type alias" +msgstr "type alias（型別別名）" + +#: ../../glossary.rst:1578 +msgid "A synonym for a type, created by assigning the type to an identifier." +msgstr "一個型別的同義詞，透過將型別指定給一個識別符 (identifier) 來建立。" + +#: ../../glossary.rst:1580 +msgid "" +"Type aliases are useful for simplifying :term:`type hints `. For " +"example::" +msgstr "" +"型別別名對於簡化\\ :term:`型別提示 (type hint) ` 很有用。例如： ::" + +#: ../../glossary.rst:1583 +msgid "" +"def remove_gray_shades(\n" +" colors: list[tuple[int, int, int]]) -> list[tuple[int, int, int]]:\n" +" pass" +msgstr "" +"def remove_gray_shades(\n" +" colors: list[tuple[int, int, int]]) -> list[tuple[int, int, int]]:\n" +" pass" + +#: ../../glossary.rst:1587 +msgid "could be made more readable like this::" +msgstr "可以寫成這樣，更具有可讀性： ::" + +#: ../../glossary.rst:1589 +msgid "" +"Color = tuple[int, int, int]\n" +"\n" +"def remove_gray_shades(colors: list[Color]) -> list[Color]:\n" +" pass" +msgstr "" +"Color = tuple[int, int, int]\n" +"\n" +"def remove_gray_shades(colors: list[Color]) -> list[Color]:\n" +" pass" + +#: ../../glossary.rst:1594 ../../glossary.rst:1608 +msgid "See :mod:`typing` and :pep:`484`, which describe this functionality." +msgstr "請參閱 :mod:`typing` 和 :pep:`484`，有此功能的描述。" + +#: ../../glossary.rst:1595 +msgid "type hint" +msgstr "type hint（型別提示）" + +#: ../../glossary.rst:1597 +msgid "" +"An :term:`annotation` that specifies the expected type for a variable, a " +"class attribute, or a function parameter or return value." +msgstr "" +"一種 :term:`annotation`\\ （註釋），它指定一個變數、一個 class 屬性或一個函式" +"的參數或回傳值的預期型別。" + +#: ../../glossary.rst:1600 +msgid "" +"Type hints are optional and are not enforced by Python but they are useful " +"to :term:`static type checkers `. They can also aid " +"IDEs with code completion and refactoring." +msgstr "" +"型別提示是選擇性的，而不是被 Python 強制的，但它們對\\ :term:`靜態型別檢查器 " +"(static type checkers) `\\ 很有用，並能協助 IDE 完成程式" +"碼的補全 (completion) 和重構 (refactoring)。" + +#: ../../glossary.rst:1604 +msgid "" +"Type hints of global variables, class attributes, and functions, but not " +"local variables, can be accessed using :func:`typing.get_type_hints`." +msgstr "" +"全域變數、class 屬性和函式（不含區域變數）的型別提示，都可以使用 :func:" +"`typing.get_type_hints` 來存取。" + +#: ../../glossary.rst:1609 +msgid "universal newlines" +msgstr "universal newlines（通用換行字元）" + +#: ../../glossary.rst:1611 +msgid "" +"A manner of interpreting text streams in which all of the following are " +"recognized as ending a line: the Unix end-of-line convention ``'\\n'``, the " +"Windows convention ``'\\r\\n'``, and the old Macintosh convention " +"``'\\r'``. See :pep:`278` and :pep:`3116`, as well as :func:`bytes." +"splitlines` for an additional use." +msgstr "" +"一種解譯文字流 (text stream) 的方式，會將以下所有的情況識別為一行的結束：" +"Unix 行尾慣例 ``'\\n'``、Windows 慣例 ``'\\r\\n'`` 和舊的 Macintosh 慣例 " +"``'\\r'``。請參閱 :pep:`278` 和 :pep:`3116`，以及用於 :func:`bytes." +"splitlines` 的附加用途。" + +#: ../../glossary.rst:1616 +msgid "variable annotation" +msgstr "variable annotation（變數註釋）" + +#: ../../glossary.rst:1618 +msgid "An :term:`annotation` of a variable or a class attribute." +msgstr "一個變數或 class 屬性的 :term:`annotation`\\ （註釋）。" + +#: ../../glossary.rst:1620 +msgid "" +"When annotating a variable or a class attribute, assignment is optional::" +msgstr "註釋變數或 class 屬性時，賦值是選擇性的： ::" + +#: ../../glossary.rst:1622 +msgid "" +"class C:\n" +" field: 'annotation'" +msgstr "" +"class C:\n" +" field: 'annotation'" + +#: ../../glossary.rst:1625 +msgid "" +"Variable annotations are usually used for :term:`type hints `: " +"for example this variable is expected to take :class:`int` values::" +msgstr "" +"變數註釋通常用於\\ :term:`型別提示 (type hint) `：例如，這個變數預" +"期會取得 :class:`int`\\ （整數）值： ::" + +#: ../../glossary.rst:1629 +msgid "count: int = 0" +msgstr "count: int = 0" + +#: ../../glossary.rst:1631 +msgid "Variable annotation syntax is explained in section :ref:`annassign`." +msgstr "變數註釋的語法在\\ :ref:`annassign`\\ 章節有詳細的解釋。" + +#: ../../glossary.rst:1633 +msgid "" +"See :term:`function annotation`, :pep:`484` and :pep:`526`, which describe " +"this functionality. Also see :ref:`annotations-howto` for best practices on " +"working with annotations." +msgstr "" +"請參閱 :term:`function annotation`\\ （函式註釋）、:pep:`484` 和 :pep:`526`，" +"皆有此功能的描述。關於註釋的最佳實踐方法，另請參閱 :ref:`annotations-howto`。" + +#: ../../glossary.rst:1637 +msgid "virtual environment" +msgstr "virtual environment（虛擬環境）" + +#: ../../glossary.rst:1639 +msgid "" +"A cooperatively isolated runtime environment that allows Python users and " +"applications to install and upgrade Python distribution packages without " +"interfering with the behaviour of other Python applications running on the " +"same system." +msgstr "" +"一個協作隔離 (cooperatively isolated) 的執行環境，能讓 Python 的使用者和應用" +"程式得以安裝和升級 Python 發佈套件，而不會對同一個系統上運行的其他 Python 應" +"用程式的行為產生干擾。" + +#: ../../glossary.rst:1644 +msgid "See also :mod:`venv`." +msgstr "另請參閱 :mod:`venv`。" + +#: ../../glossary.rst:1645 +msgid "virtual machine" +msgstr "virtual machine（虛擬機器）" + +#: ../../glossary.rst:1647 +msgid "" +"A computer defined entirely in software. Python's virtual machine executes " +"the :term:`bytecode` emitted by the bytecode compiler." +msgstr "" +"一部完全由軟體所定義的電腦 (computer)。Python 的虛擬機器會執行由 :term:" +"`bytecode`\\ （位元組碼）編譯器所發出的位元組碼。" + +#: ../../glossary.rst:1649 +msgid "walrus operator" +msgstr "walrus operator（海象運算子）" + +#: ../../glossary.rst:1651 +msgid "" +"A light-hearted way to refer to the :ref:`assignment expression ` operator ``:=`` because it looks a bit like a walrus if you " +"turn your head." +msgstr "" + +#: ../../glossary.rst:1654 +msgid "Zen of Python" +msgstr "Zen of Python（Python 之禪）" + +#: ../../glossary.rst:1656 +msgid "" +"Listing of Python design principles and philosophies that are helpful in " +"understanding and using the language. The listing can be found by typing " +"\"``import this``\" at the interactive prompt." +msgstr "" +"Python 設計原則與哲學的列表，其內容有助於理解和使用此語言。此列表可以透過在互" +"動式提式字元後輸入「``import this``」來找到它。" + +#: ../../glossary.rst:24 +msgid "..." +msgstr "..." + +#: ../../glossary.rst:24 +msgid "ellipsis literal" +msgstr "刪節號字面值" + +#: ../../glossary.rst:345 +msgid "C-contiguous" +msgstr "C-contiguous（C 連續的）" + +#: ../../glossary.rst:345 +msgid "Fortran contiguous" +msgstr "Fortran contiguous（Fortran 連續的）" + +#: ../../glossary.rst:955 +msgid "magic" +msgstr "magic" + +#: ../../glossary.rst:1430 +msgid "special" +msgstr "special" + +#~ msgid "" +#~ "Mutable objects can change their value but keep their :func:`id`. See " +#~ "also :term:`immutable`." +#~ msgstr "" +#~ "可變物件可以改變它們的值，但維持它們的 :func:`id`。另請參閱 :term:" +#~ "`immutable`\\ （不可變物件）。" + +#~ msgid "The :const:`Ellipsis` built-in constant." +#~ msgstr "內建常數 :const:`Ellipsis`。" diff --git a/howto/a-conceptual-overview-of-asyncio.po b/howto/a-conceptual-overview-of-asyncio.po index d07c49702c..b06131c4e7 100644 --- a/howto/a-conceptual-overview-of-asyncio.po +++ b/howto/a-conceptual-overview-of-asyncio.po @@ -1,918 +1,918 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# FIRST AUTHOR , YEAR. -# -#, fuzzy -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-26 00:14+0000\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language-Team: LANGUAGE \n" -"Language: zh_TW\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=UTF-8\n" -"Content-Transfer-Encoding: 8bit\n" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:5 -msgid "A Conceptual Overview of :mod:`!asyncio`" -msgstr ":mod:`!asyncio` 的概念性總覽" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:7 -msgid "" -"This :ref:`HOWTO ` article seeks to help you build a sturdy mental " -"model of how :mod:`asyncio` fundamentally works, helping you understand the " -"how and why behind the recommended patterns." -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:11 -msgid "" -"You might be curious about some key :mod:`!asyncio` concepts. By the end of " -"this article, you'll be able to comfortably answer these questions:" -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:14 -msgid "What's happening behind the scenes when an object is awaited?" -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:15 -msgid "" -"How does :mod:`!asyncio` differentiate between a task which doesn't need CPU " -"time (such as a network request or file read) as opposed to a task that does " -"(such as computing n-factorial)?" -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:18 -msgid "" -"How to write an asynchronous variant of an operation, such as an async sleep " -"or database request." -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:23 -msgid "" -"The `guide `_ that inspired this HOWTO article, by Alexander Nordin." -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:25 -msgid "" -"This in-depth `YouTube tutorial series `_ on ``asyncio`` " -"created by Python core team member, Łukasz Langa." -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:28 -msgid "" -"`500 Lines or Less: A Web Crawler With asyncio Coroutines `_ by A. Jesse Jiryu " -"Davis and Guido van Rossum." -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:34 -msgid "A conceptual overview part 1: the high-level" -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:36 -msgid "" -"In part 1, we'll cover the main, high-level building blocks of :mod:`!" -"asyncio`: the event loop, coroutine functions, coroutine objects, tasks, and " -"``await``." -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:41 -msgid "Event Loop" -msgstr "事件迴圈" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:43 -msgid "" -"Everything in :mod:`!asyncio` happens relative to the event loop. It's the " -"star of the show. It's like an orchestra conductor. It's behind the scenes " -"managing resources. Some power is explicitly granted to it, but a lot of its " -"ability to get things done comes from the respect and cooperation of its " -"worker bees." -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:50 -msgid "" -"In more technical terms, the event loop contains a collection of jobs to be " -"run. Some jobs are added directly by you, and some indirectly by :mod:`!" -"asyncio`. The event loop takes a job from its backlog of work and invokes it " -"(or \"gives it control\"), similar to calling a function, and then that job " -"runs. Once it pauses or completes, it returns control to the event loop. The " -"event loop will then select another job from its pool and invoke it. You can " -"*roughly* think of the collection of jobs as a queue: jobs are added and " -"then processed one at a time, generally (but not always) in order. This " -"process repeats indefinitely, with the event loop cycling endlessly onwards. " -"If there are no more jobs pending execution, the event loop is smart enough " -"to rest and avoid needlessly wasting CPU cycles, and will come back when " -"there's more work to be done." -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:64 -msgid "" -"Effective execution relies on jobs sharing well and cooperating; a greedy " -"job could hog control and leave the other jobs to starve, rendering the " -"overall event loop approach rather useless." -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:70 -msgid "" -"import asyncio\n" -"\n" -"# This creates an event loop and indefinitely cycles through\n" -"# its collection of jobs.\n" -"event_loop = asyncio.new_event_loop()\n" -"event_loop.run_forever()" -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:79 -msgid "Asynchronous functions and coroutines" -msgstr "非同步函式與協程" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:81 -msgid "This is a basic, boring Python function::" -msgstr "這是一個基本的、無聊的 Python 函式：" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:83 -msgid "" -"def hello_printer():\n" -" print(\n" -" \"Hi, I am a lowly, simple printer, though I have all I \"\n" -" \"need in life -- \\nfresh paper and my dearly beloved octopus \"\n" -" \"partner in crime.\"\n" -" )" -msgstr "" -"def hello_printer():\n" -" print(\n" -" \"Hi, I am a lowly, simple printer, though I have all I \"\n" -" \"need in life -- \\nfresh paper and my dearly beloved octopus \"\n" -" \"partner in crime.\"\n" -" )" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:90 -msgid "Calling a regular function invokes its logic or body::" -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:92 -msgid "" -">>> hello_printer()\n" -"Hi, I am a lowly, simple printer, though I have all I need in life --\n" -"fresh paper and my dearly beloved octopus partner in crime." -msgstr "" -">>> hello_printer()\n" -"Hi, I am a lowly, simple printer, though I have all I need in life --\n" -"fresh paper and my dearly beloved octopus partner in crime." - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:96 -msgid "" -"The :ref:`async def `, as opposed to just a plain ``def``, makes " -"this an asynchronous function (or \"coroutine function\"). Calling it " -"creates and returns a :ref:`coroutine ` object." -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:102 -msgid "" -"async def loudmouth_penguin(magic_number: int):\n" -" print(\n" -" \"I am a super special talking penguin. Far cooler than that printer. " -"\"\n" -" f\"By the way, my lucky number is: {magic_number}.\"\n" -" )" -msgstr "" -"async def loudmouth_penguin(magic_number: int):\n" -" print(\n" -" \"I am a super special talking penguin. Far cooler than that printer. " -"\"\n" -" f\"By the way, my lucky number is: {magic_number}.\"\n" -" )" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:108 -msgid "" -"Calling the async function, ``loudmouth_penguin``, does not execute the " -"print statement; instead, it creates a coroutine object::" -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:111 -msgid "" -">>> loudmouth_penguin(magic_number=3)\n" -"" -msgstr "" -">>> loudmouth_penguin(magic_number=3)\n" -"" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:114 -msgid "" -"The terms \"coroutine function\" and \"coroutine object\" are often " -"conflated as coroutine. That can be confusing! In this article, coroutine " -"specifically refers to a coroutine object, or more precisely, an instance " -"of :data:`types.CoroutineType` (native coroutine). Note that coroutines can " -"also exist as instances of :class:`collections.abc.Coroutine` -- a " -"distinction that matters for type checking." -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:123 -msgid "" -"A coroutine represents the function's body or logic. A coroutine has to be " -"explicitly started; again, merely creating the coroutine does not start it. " -"Notably, the coroutine can be paused and resumed at various points within " -"the function's body. That pausing and resuming ability is what allows for " -"asynchronous behavior!" -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:130 -msgid "" -"Coroutines and coroutine functions were built by leveraging the " -"functionality of :term:`generators ` and :term:" -"`generator functions `. Recall, a generator function is a " -"function that :keyword:`yield`\\s, like this one::" -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:136 -msgid "" -"def get_random_number():\n" -" # This would be a bad random number generator!\n" -" print(\"Hi\")\n" -" yield 1\n" -" print(\"Hello\")\n" -" yield 7\n" -" print(\"Howdy\")\n" -" yield 4\n" -" ..." -msgstr "" -"def get_random_number():\n" -" # 這是個很爛的隨機數產生器！\n" -" print(\"Hi\")\n" -" yield 1\n" -" print(\"Hello\")\n" -" yield 7\n" -" print(\"Howdy\")\n" -" yield 4\n" -" ..." - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:146 -msgid "" -"Similar to a coroutine function, calling a generator function does not run " -"it. Instead, it creates a generator object::" -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:149 -msgid "" -">>> get_random_number()\n" -"" -msgstr "" -">>> get_random_number()\n" -"" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:152 -msgid "" -"You can proceed to the next ``yield`` of a generator by using the built-in " -"function :func:`next`. In other words, the generator runs, then pauses. For " -"example::" -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:157 -msgid "" -">>> generator = get_random_number()\n" -">>> next(generator)\n" -"Hi\n" -"1\n" -">>> next(generator)\n" -"Hello\n" -"7" -msgstr "" -">>> generator = get_random_number()\n" -">>> next(generator)\n" -"Hi\n" -"1\n" -">>> next(generator)\n" -"Hello\n" -"7" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:167 -msgid "Tasks" -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:169 -msgid "" -"Roughly speaking, :ref:`tasks ` are coroutines (not " -"coroutine functions) tied to an event loop. A task also maintains a list of " -"callback functions whose importance will become clear in a moment when we " -"discuss :keyword:`await`. The recommended way to create tasks is via :func:" -"`asyncio.create_task`." -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:175 -msgid "" -"Creating a task automatically schedules it for execution (by adding a " -"callback to run it in the event loop's to-do list, that is, collection of " -"jobs)." -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:178 -msgid "" -":mod:`!asyncio` automatically associates tasks with the event loop for you. " -"This automatic association was purposely designed into :mod:`!asyncio` for " -"the sake of simplicity. Without it, you'd have to keep track of the event " -"loop object and pass it to any coroutine function that wants to create " -"tasks, adding redundant clutter to your code." -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:187 -msgid "" -"coroutine = loudmouth_penguin(magic_number=5)\n" -"# This creates a Task object and schedules its execution via the event " -"loop.\n" -"task = asyncio.create_task(coroutine)" -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:191 -msgid "" -"Earlier, we manually created the event loop and set it to run forever. In " -"practice, it's recommended to use (and common to see) :func:`asyncio.run`, " -"which takes care of managing the event loop and ensuring the provided " -"coroutine finishes before advancing. For example, many async programs follow " -"this setup::" -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:197 -msgid "" -"import asyncio\n" -"\n" -"async def main():\n" -" # Perform all sorts of wacky, wild asynchronous things...\n" -" ...\n" -"\n" -"if __name__ == \"__main__\":\n" -" asyncio.run(main())\n" -" # The program will not reach the following print statement until the\n" -" # coroutine main() finishes.\n" -" print(\"coroutine main() is done!\")" -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:209 -msgid "" -"It's important to be aware that the task itself is not added to the event " -"loop, only a callback to the task is. This matters if the task object you " -"created is garbage collected before it's called by the event loop. For " -"example, consider this program:" -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:215 -msgid "" -"async def hello():\n" -" print(\"hello!\")\n" -"\n" -"async def main():\n" -" asyncio.create_task(hello())\n" -" # Other asynchronous instructions which run for a while\n" -" # and cede control to the event loop...\n" -" ...\n" -"\n" -"asyncio.run(main())" -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:229 -msgid "" -"Because there's no reference to the task object created on line 5, it " -"*might* be garbage collected before the event loop invokes it. Later " -"instructions in the coroutine ``main()`` hand control back to the event loop " -"so it can invoke other jobs. When the event loop eventually tries to run the " -"task, it might fail and discover the task object does not exist! This can " -"also happen even if a coroutine keeps a reference to a task but completes " -"before that task finishes. When the coroutine exits, local variables go out " -"of scope and may be subject to garbage collection. In practice, ``asyncio`` " -"and Python's garbage collector work pretty hard to ensure this sort of thing " -"doesn't happen. But that's no reason to be reckless!" -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:245 -msgid "await" -msgstr "await" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:247 -msgid "" -":keyword:`await` is a Python keyword that's commonly used in one of two " -"different ways::" -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:250 -msgid "" -"await task\n" -"await coroutine" -msgstr "" -"await task\n" -"await coroutine" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:253 -msgid "" -"In a crucial way, the behavior of ``await`` depends on the type of object " -"being awaited." -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:256 -msgid "" -"Awaiting a task will cede control from the current task or coroutine to the " -"event loop. In the process of relinquishing control, a few important things " -"happen. We'll use the following code example to illustrate::" -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:261 -msgid "" -"async def plant_a_tree():\n" -" dig_the_hole_task = asyncio.create_task(dig_the_hole())\n" -" await dig_the_hole_task\n" -"\n" -" # Other instructions associated with planting a tree.\n" -" ..." -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:268 -msgid "" -"In this example, imagine the event loop has passed control to the start of " -"the coroutine ``plant_a_tree()``. As seen above, the coroutine creates a " -"task and then awaits it. The ``await dig_the_hole_task`` instruction adds a " -"callback (which will resume ``plant_a_tree()``) to the ``dig_the_hole_task`` " -"object's list of callbacks. And then, the instruction cedes control to the " -"event loop. Some time later, the event loop will pass control to " -"``dig_the_hole_task`` and the task will finish whatever it needs to do. Once " -"the task finishes, it will add its various callbacks to the event loop, in " -"this case, a call to resume ``plant_a_tree()``." -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:279 -msgid "" -"Generally speaking, when the awaited task finishes (``dig_the_hole_task``), " -"the original task or coroutine (``plant_a_tree()``) is added back to the " -"event loop's to-do list to be resumed." -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:283 -msgid "" -"This is a basic, yet reliable mental model. In practice, the control " -"handoffs are slightly more complex, but not by much. In part 2, we'll walk " -"through the details that make this possible." -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:287 -msgid "" -"**Unlike tasks, awaiting a coroutine does not hand control back to the event " -"loop!** Wrapping a coroutine in a task first, then awaiting that would cede " -"control. The behavior of ``await coroutine`` is effectively the same as " -"invoking a regular, synchronous Python function. Consider this program::" -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:295 -msgid "" -"import asyncio\n" -"\n" -"async def coro_a():\n" -" print(\"I am coro_a(). Hi!\")\n" -"\n" -"async def coro_b():\n" -" print(\"I am coro_b(). I sure hope no one hogs the event loop...\")\n" -"\n" -"async def main():\n" -" task_b = asyncio.create_task(coro_b())\n" -" num_repeats = 3\n" -" for _ in range(num_repeats):\n" -" await coro_a()\n" -" await task_b\n" -"\n" -"asyncio.run(main())" -msgstr "" -"import asyncio\n" -"\n" -"async def coro_a():\n" -" print(\"I am coro_a(). Hi!\")\n" -"\n" -"async def coro_b():\n" -" print(\"I am coro_b(). I sure hope no one hogs the event loop...\")\n" -"\n" -"async def main():\n" -" task_b = asyncio.create_task(coro_b())\n" -" num_repeats = 3\n" -" for _ in range(num_repeats):\n" -" await coro_a()\n" -" await task_b\n" -"\n" -"asyncio.run(main())" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:312 -msgid "" -"The first statement in the coroutine ``main()`` creates ``task_b`` and " -"schedules it for execution via the event loop. Then, ``coro_a()`` is " -"repeatedly awaited. Control never cedes to the event loop, which is why we " -"see the output of all three ``coro_a()`` invocations before ``coro_b()``'s " -"output:" -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:318 -msgid "" -"I am coro_a(). Hi!\n" -"I am coro_a(). Hi!\n" -"I am coro_a(). Hi!\n" -"I am coro_b(). I sure hope no one hogs the event loop..." -msgstr "" -"I am coro_a(). Hi!\n" -"I am coro_a(). Hi!\n" -"I am coro_a(). Hi!\n" -"I am coro_b(). I sure hope no one hogs the event loop..." - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:325 -msgid "" -"If we change ``await coro_a()`` to ``await asyncio.create_task(coro_a())``, " -"the behavior changes. The coroutine ``main()`` cedes control to the event " -"loop with that statement. The event loop then proceeds through its backlog " -"of work, calling ``task_b`` and then the task which wraps ``coro_a()`` " -"before resuming the coroutine ``main()``." -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:332 -msgid "" -"I am coro_b(). I sure hope no one hogs the event loop...\n" -"I am coro_a(). Hi!\n" -"I am coro_a(). Hi!\n" -"I am coro_a(). Hi!" -msgstr "" -"I am coro_b(). I sure hope no one hogs the event loop...\n" -"I am coro_a(). Hi!\n" -"I am coro_a(). Hi!\n" -"I am coro_a(). Hi!" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:339 -msgid "" -"This behavior of ``await coroutine`` can trip a lot of people up! That " -"example highlights how using only ``await coroutine`` could unintentionally " -"hog control from other tasks and effectively stall the event loop. :func:" -"`asyncio.run` can help you detect such occurrences via the ``debug=True`` " -"flag, which enables :ref:`debug mode `. Among other " -"things, it will log any coroutines that monopolize execution for 100ms or " -"longer." -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:349 -msgid "" -"The design intentionally trades off some conceptual clarity around usage of " -"``await`` for improved performance. Each time a task is awaited, control " -"needs to be passed all the way up the call stack to the event loop. That " -"might sound minor, but in a large program with many ``await`` statements and " -"a deep call stack, that overhead can add up to a meaningful performance drag." -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:358 -msgid "A conceptual overview part 2: the nuts and bolts" -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:360 -msgid "" -"Part 2 goes into detail on the mechanisms :mod:`!asyncio` uses to manage " -"control flow. This is where the magic happens. You'll come away from this " -"section knowing what ``await`` does behind the scenes and how to make your " -"own asynchronous operators." -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:368 -msgid "The inner workings of coroutines" -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:370 -msgid ":mod:`!asyncio` leverages four components to pass around control." -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:372 -msgid "" -":meth:`coroutine.send(arg) ` is the method used to start or " -"resume a coroutine. If the coroutine was paused and is now being resumed, " -"the argument ``arg`` will be sent in as the return value of the ``yield`` " -"statement which originally paused it. If the coroutine is being used for the " -"first time (as opposed to being resumed), ``arg`` must be ``None``." -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:380 -msgid "" -"class Rock:\n" -" def __await__(self):\n" -" value_sent_in = yield 7\n" -" print(f\"Rock.__await__ resuming with value: {value_sent_in}.\")\n" -" return value_sent_in\n" -"\n" -"async def main():\n" -" print(\"Beginning coroutine main().\")\n" -" rock = Rock()\n" -" print(\"Awaiting rock...\")\n" -" value_from_rock = await rock\n" -" print(f\"Coroutine received value: {value_from_rock} from rock.\")\n" -" return 23\n" -"\n" -"coroutine = main()\n" -"intermediate_result = coroutine.send(None)\n" -"print(f\"Coroutine paused and returned intermediate value: " -"{intermediate_result}.\")\n" -"\n" -"print(f\"Resuming coroutine and sending in value: 42.\")\n" -"try:\n" -" coroutine.send(42)\n" -"except StopIteration as e:\n" -" returned_value = e.value\n" -"print(f\"Coroutine main() finished and provided value: {returned_value}.\")" -msgstr "" -"class Rock:\n" -" def __await__(self):\n" -" value_sent_in = yield 7\n" -" print(f\"Rock.__await__ resuming with value: {value_sent_in}.\")\n" -" return value_sent_in\n" -"\n" -"async def main():\n" -" print(\"Beginning coroutine main().\")\n" -" rock = Rock()\n" -" print(\"Awaiting rock...\")\n" -" value_from_rock = await rock\n" -" print(f\"Coroutine received value: {value_from_rock} from rock.\")\n" -" return 23\n" -"\n" -"coroutine = main()\n" -"intermediate_result = coroutine.send(None)\n" -"print(f\"Coroutine paused and returned intermediate value: " -"{intermediate_result}.\")\n" -"\n" -"print(f\"Resuming coroutine and sending in value: 42.\")\n" -"try:\n" -" coroutine.send(42)\n" -"except StopIteration as e:\n" -" returned_value = e.value\n" -"print(f\"Coroutine main() finished and provided value: {returned_value}.\")" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:408 -msgid "" -":ref:`yield `, as usual, pauses execution and returns control to " -"the caller. In the example above, the ``yield``, on line 3, is called by " -"``... = await rock`` on line 11. More broadly speaking, ``await`` calls the :" -"meth:`~object.__await__` method of the given object. ``await`` also does one " -"more very special thing: it propagates (or \"passes along\") any ``yield``\\ " -"s it receives up the call chain. In this case, that's back to ``... = " -"coroutine.send(None)`` on line 16." -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:418 -msgid "" -"The coroutine is resumed via the ``coroutine.send(42)`` call on line 21. The " -"coroutine picks back up from where it ``yield``\\ ed (or paused) on line 3 " -"and executes the remaining statements in its body. When a coroutine " -"finishes, it raises a :exc:`StopIteration` exception with the return value " -"attached in the :attr:`~StopIteration.value` attribute." -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:424 -msgid "That snippet produces this output:" -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:426 -msgid "" -"Beginning coroutine main().\n" -"Awaiting rock...\n" -"Coroutine paused and returned intermediate value: 7.\n" -"Resuming coroutine and sending in value: 42.\n" -"Rock.__await__ resuming with value: 42.\n" -"Coroutine received value: 42 from rock.\n" -"Coroutine main() finished and provided value: 23." -msgstr "" -"Beginning coroutine main().\n" -"Awaiting rock...\n" -"Coroutine paused and returned intermediate value: 7.\n" -"Resuming coroutine and sending in value: 42.\n" -"Rock.__await__ resuming with value: 42.\n" -"Coroutine received value: 42 from rock.\n" -"Coroutine main() finished and provided value: 23." - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:436 -msgid "" -"It's worth pausing for a moment here and making sure you followed the " -"various ways that control flow and values were passed. A lot of important " -"ideas were covered and it's worth ensuring your understanding is firm." -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:440 -msgid "" -"The only way to yield (or effectively cede control) from a coroutine is to " -"``await`` an object that ``yield``\\ s in its ``__await__`` method. That " -"might sound odd to you. You might be thinking:" -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:444 -msgid "" -"1. What about a ``yield`` directly within the coroutine function? The " -"coroutine function becomes an :ref:`async generator function `, a different beast entirely." -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:449 -msgid "" -"2. What about a :ref:`yield from ` within the coroutine function " -"to a (plain) generator? That causes the error: ``SyntaxError: yield from not " -"allowed in a coroutine.`` This was intentionally designed for the sake of " -"simplicity -- mandating only one way of using coroutines. Initially " -"``yield`` was barred as well, but was re-accepted to allow for async " -"generators. Despite that, ``yield from`` and ``await`` effectively do the " -"same thing." -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:460 -msgid "Futures" -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:462 -msgid "" -"A :ref:`future ` is an object meant to represent a " -"computation's status and result. The term is a nod to the idea of something " -"still to come or not yet happened, and the object is a way to keep an eye on " -"that something." -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:467 -msgid "" -"A future has a few important attributes. One is its state, which can be " -"either \"pending\", \"cancelled\", or \"done\". Another is its result, which " -"is set when the state transitions to done. Unlike a coroutine, a future does " -"not represent the actual computation to be done; instead, it represents the " -"status and result of that computation, kind of like a status light (red, " -"yellow, or green) or indicator." -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:474 -msgid "" -":class:`asyncio.Task` subclasses :class:`asyncio.Future` in order to gain " -"these various capabilities. The prior section said tasks store a list of " -"callbacks, which wasn't entirely accurate. It's actually the ``Future`` " -"class that implements this logic, which ``Task`` inherits." -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:481 -msgid "" -"Futures may also be used directly (not via tasks). Tasks mark themselves as " -"done when their coroutine is complete. Futures are much more versatile and " -"will be marked as done when you say so. In this way, they're the flexible " -"interface for you to make your own conditions for waiting and resuming." -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:489 -msgid "A homemade asyncio.sleep" -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:491 -msgid "" -"We'll go through an example of how you could leverage a future to create " -"your own variant of asynchronous sleep (``async_sleep``) which mimics :func:" -"`asyncio.sleep`." -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:495 -msgid "" -"This snippet registers a few tasks with the event loop and then awaits the " -"task created by ``asyncio.create_task``, which wraps the ``async_sleep(3)`` " -"coroutine. We want that task to finish only after three seconds have " -"elapsed, but without preventing other tasks from running." -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:502 -msgid "" -"async def other_work():\n" -" print(\"I like work. Work work.\")\n" -"\n" -"async def main():\n" -" # Add a few other tasks to the event loop, so there's something\n" -" # to do while asynchronously sleeping.\n" -" work_tasks = [\n" -" asyncio.create_task(other_work()),\n" -" asyncio.create_task(other_work()),\n" -" asyncio.create_task(other_work())\n" -" ]\n" -" print(\n" -" \"Beginning asynchronous sleep at time: \"\n" -" f\"{datetime.datetime.now().strftime(\"%H:%M:%S\")}.\"\n" -" )\n" -" await asyncio.create_task(async_sleep(3))\n" -" print(\n" -" \"Done asynchronous sleep at time: \"\n" -" f\"{datetime.datetime.now().strftime(\"%H:%M:%S\")}.\"\n" -" )\n" -" # asyncio.gather effectively awaits each task in the collection.\n" -" await asyncio.gather(*work_tasks)" -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:526 -msgid "" -"Below, we use a future to enable custom control over when that task will be " -"marked as done. If :meth:`future.set_result() ` " -"(the method responsible for marking that future as done) is never called, " -"then this task will never finish. We've also enlisted the help of another " -"task, which we'll see in a moment, that will monitor how much time has " -"elapsed and, accordingly, call ``future.set_result()``." -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:537 -msgid "" -"async def async_sleep(seconds: float):\n" -" future = asyncio.Future()\n" -" time_to_wake = time.time() + seconds\n" -" # Add the watcher-task to the event loop.\n" -" watcher_task = asyncio.create_task(_sleep_watcher(future, " -"time_to_wake))\n" -" # Block until the future is marked as done.\n" -" await future" -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:545 -msgid "" -"Below, we use a rather bare ``YieldToEventLoop()`` object to ``yield`` from " -"its ``__await__`` method, ceding control to the event loop. This is " -"effectively the same as calling ``asyncio.sleep(0)``, but this approach " -"offers more clarity, not to mention it's somewhat cheating to use ``asyncio." -"sleep`` when showcasing how to implement it!" -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:551 -msgid "" -"As usual, the event loop cycles through its tasks, giving them control and " -"receiving control back when they pause or finish. The ``watcher_task``, " -"which runs the coroutine ``_sleep_watcher(...)``, will be invoked once per " -"full cycle of the event loop. On each resumption, it'll check the time and " -"if not enough has elapsed, then it'll pause once again and hand control back " -"to the event loop. Once enough time has elapsed, ``_sleep_watcher(...)`` " -"marks the future as done and completes by exiting its infinite ``while`` " -"loop. Given this helper task is only invoked once per cycle of the event " -"loop, you'd be correct to note that this asynchronous sleep will sleep *at " -"least* three seconds, rather than exactly three seconds. Note this is also " -"true of ``asyncio.sleep``." -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:567 -msgid "" -"class YieldToEventLoop:\n" -" def __await__(self):\n" -" yield\n" -"\n" -"async def _sleep_watcher(future, time_to_wake):\n" -" while True:\n" -" if time.time() >= time_to_wake:\n" -" # This marks the future as done.\n" -" future.set_result(None)\n" -" break\n" -" else:\n" -" await YieldToEventLoop()" -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:580 -msgid "Here is the full program's output:" -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:582 -msgid "" -"$ python custom-async-sleep.py\n" -"Beginning asynchronous sleep at time: 14:52:22.\n" -"I like work. Work work.\n" -"I like work. Work work.\n" -"I like work. Work work.\n" -"Done asynchronous sleep at time: 14:52:25." -msgstr "" -"$ python custom-async-sleep.py\n" -"Beginning asynchronous sleep at time: 14:52:22.\n" -"I like work. Work work.\n" -"I like work. Work work.\n" -"I like work. Work work.\n" -"Done asynchronous sleep at time: 14:52:25." - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:591 -msgid "" -"You might feel this implementation of asynchronous sleep was unnecessarily " -"convoluted. And, well, it was. The example was meant to showcase the " -"versatility of futures with a simple example that could be mimicked for more " -"complex needs. For reference, you could implement it without futures, like " -"so::" -msgstr "" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:598 -msgid "" -"async def simpler_async_sleep(seconds):\n" -" time_to_wake = time.time() + seconds\n" -" while True:\n" -" if time.time() >= time_to_wake:\n" -" return\n" -" else:\n" -" await YieldToEventLoop()" -msgstr "" -"async def simpler_async_sleep(seconds):\n" -" time_to_wake = time.time() + seconds\n" -" while True:\n" -" if time.time() >= time_to_wake:\n" -" return\n" -" else:\n" -" await YieldToEventLoop()" - -#: ../../howto/a-conceptual-overview-of-asyncio.rst:606 -msgid "" -"But that's all for now. Hopefully you're ready to more confidently dive into " -"some async programming or check out advanced topics in the :mod:`rest of the " -"documentation `." -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-26 00:14+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"Language: zh_TW\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:5 +msgid "A Conceptual Overview of :mod:`!asyncio`" +msgstr ":mod:`!asyncio` 的概念性總覽" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:7 +msgid "" +"This :ref:`HOWTO ` article seeks to help you build a sturdy mental " +"model of how :mod:`asyncio` fundamentally works, helping you understand the " +"how and why behind the recommended patterns." +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:11 +msgid "" +"You might be curious about some key :mod:`!asyncio` concepts. By the end of " +"this article, you'll be able to comfortably answer these questions:" +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:14 +msgid "What's happening behind the scenes when an object is awaited?" +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:15 +msgid "" +"How does :mod:`!asyncio` differentiate between a task which doesn't need CPU " +"time (such as a network request or file read) as opposed to a task that does " +"(such as computing n-factorial)?" +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:18 +msgid "" +"How to write an asynchronous variant of an operation, such as an async sleep " +"or database request." +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:23 +msgid "" +"The `guide `_ that inspired this HOWTO article, by Alexander Nordin." +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:25 +msgid "" +"This in-depth `YouTube tutorial series `_ on ``asyncio`` " +"created by Python core team member, Łukasz Langa." +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:28 +msgid "" +"`500 Lines or Less: A Web Crawler With asyncio Coroutines `_ by A. Jesse Jiryu " +"Davis and Guido van Rossum." +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:34 +msgid "A conceptual overview part 1: the high-level" +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:36 +msgid "" +"In part 1, we'll cover the main, high-level building blocks of :mod:`!" +"asyncio`: the event loop, coroutine functions, coroutine objects, tasks, and " +"``await``." +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:41 +msgid "Event Loop" +msgstr "事件迴圈" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:43 +msgid "" +"Everything in :mod:`!asyncio` happens relative to the event loop. It's the " +"star of the show. It's like an orchestra conductor. It's behind the scenes " +"managing resources. Some power is explicitly granted to it, but a lot of its " +"ability to get things done comes from the respect and cooperation of its " +"worker bees." +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:50 +msgid "" +"In more technical terms, the event loop contains a collection of jobs to be " +"run. Some jobs are added directly by you, and some indirectly by :mod:`!" +"asyncio`. The event loop takes a job from its backlog of work and invokes it " +"(or \"gives it control\"), similar to calling a function, and then that job " +"runs. Once it pauses or completes, it returns control to the event loop. The " +"event loop will then select another job from its pool and invoke it. You can " +"*roughly* think of the collection of jobs as a queue: jobs are added and " +"then processed one at a time, generally (but not always) in order. This " +"process repeats indefinitely, with the event loop cycling endlessly onwards. " +"If there are no more jobs pending execution, the event loop is smart enough " +"to rest and avoid needlessly wasting CPU cycles, and will come back when " +"there's more work to be done." +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:64 +msgid "" +"Effective execution relies on jobs sharing well and cooperating; a greedy " +"job could hog control and leave the other jobs to starve, rendering the " +"overall event loop approach rather useless." +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:70 +msgid "" +"import asyncio\n" +"\n" +"# This creates an event loop and indefinitely cycles through\n" +"# its collection of jobs.\n" +"event_loop = asyncio.new_event_loop()\n" +"event_loop.run_forever()" +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:79 +msgid "Asynchronous functions and coroutines" +msgstr "非同步函式與協程" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:81 +msgid "This is a basic, boring Python function::" +msgstr "這是一個基本的、無聊的 Python 函式：" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:83 +msgid "" +"def hello_printer():\n" +" print(\n" +" \"Hi, I am a lowly, simple printer, though I have all I \"\n" +" \"need in life -- \\nfresh paper and my dearly beloved octopus \"\n" +" \"partner in crime.\"\n" +" )" +msgstr "" +"def hello_printer():\n" +" print(\n" +" \"Hi, I am a lowly, simple printer, though I have all I \"\n" +" \"need in life -- \\nfresh paper and my dearly beloved octopus \"\n" +" \"partner in crime.\"\n" +" )" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:90 +msgid "Calling a regular function invokes its logic or body::" +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:92 +msgid "" +">>> hello_printer()\n" +"Hi, I am a lowly, simple printer, though I have all I need in life --\n" +"fresh paper and my dearly beloved octopus partner in crime." +msgstr "" +">>> hello_printer()\n" +"Hi, I am a lowly, simple printer, though I have all I need in life --\n" +"fresh paper and my dearly beloved octopus partner in crime." + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:96 +msgid "" +"The :ref:`async def `, as opposed to just a plain ``def``, makes " +"this an asynchronous function (or \"coroutine function\"). Calling it " +"creates and returns a :ref:`coroutine ` object." +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:102 +msgid "" +"async def loudmouth_penguin(magic_number: int):\n" +" print(\n" +" \"I am a super special talking penguin. Far cooler than that printer. " +"\"\n" +" f\"By the way, my lucky number is: {magic_number}.\"\n" +" )" +msgstr "" +"async def loudmouth_penguin(magic_number: int):\n" +" print(\n" +" \"I am a super special talking penguin. Far cooler than that printer. " +"\"\n" +" f\"By the way, my lucky number is: {magic_number}.\"\n" +" )" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:108 +msgid "" +"Calling the async function, ``loudmouth_penguin``, does not execute the " +"print statement; instead, it creates a coroutine object::" +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:111 +msgid "" +">>> loudmouth_penguin(magic_number=3)\n" +"" +msgstr "" +">>> loudmouth_penguin(magic_number=3)\n" +"" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:114 +msgid "" +"The terms \"coroutine function\" and \"coroutine object\" are often " +"conflated as coroutine. That can be confusing! In this article, coroutine " +"specifically refers to a coroutine object, or more precisely, an instance " +"of :data:`types.CoroutineType` (native coroutine). Note that coroutines can " +"also exist as instances of :class:`collections.abc.Coroutine` -- a " +"distinction that matters for type checking." +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:123 +msgid "" +"A coroutine represents the function's body or logic. A coroutine has to be " +"explicitly started; again, merely creating the coroutine does not start it. " +"Notably, the coroutine can be paused and resumed at various points within " +"the function's body. That pausing and resuming ability is what allows for " +"asynchronous behavior!" +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:130 +msgid "" +"Coroutines and coroutine functions were built by leveraging the " +"functionality of :term:`generators ` and :term:" +"`generator functions `. Recall, a generator function is a " +"function that :keyword:`yield`\\s, like this one::" +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:136 +msgid "" +"def get_random_number():\n" +" # This would be a bad random number generator!\n" +" print(\"Hi\")\n" +" yield 1\n" +" print(\"Hello\")\n" +" yield 7\n" +" print(\"Howdy\")\n" +" yield 4\n" +" ..." +msgstr "" +"def get_random_number():\n" +" # 這是個很爛的隨機數產生器！\n" +" print(\"Hi\")\n" +" yield 1\n" +" print(\"Hello\")\n" +" yield 7\n" +" print(\"Howdy\")\n" +" yield 4\n" +" ..." + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:146 +msgid "" +"Similar to a coroutine function, calling a generator function does not run " +"it. Instead, it creates a generator object::" +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:149 +msgid "" +">>> get_random_number()\n" +"" +msgstr "" +">>> get_random_number()\n" +"" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:152 +msgid "" +"You can proceed to the next ``yield`` of a generator by using the built-in " +"function :func:`next`. In other words, the generator runs, then pauses. For " +"example::" +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:157 +msgid "" +">>> generator = get_random_number()\n" +">>> next(generator)\n" +"Hi\n" +"1\n" +">>> next(generator)\n" +"Hello\n" +"7" +msgstr "" +">>> generator = get_random_number()\n" +">>> next(generator)\n" +"Hi\n" +"1\n" +">>> next(generator)\n" +"Hello\n" +"7" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:167 +msgid "Tasks" +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:169 +msgid "" +"Roughly speaking, :ref:`tasks ` are coroutines (not " +"coroutine functions) tied to an event loop. A task also maintains a list of " +"callback functions whose importance will become clear in a moment when we " +"discuss :keyword:`await`. The recommended way to create tasks is via :func:" +"`asyncio.create_task`." +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:175 +msgid "" +"Creating a task automatically schedules it for execution (by adding a " +"callback to run it in the event loop's to-do list, that is, collection of " +"jobs)." +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:178 +msgid "" +":mod:`!asyncio` automatically associates tasks with the event loop for you. " +"This automatic association was purposely designed into :mod:`!asyncio` for " +"the sake of simplicity. Without it, you'd have to keep track of the event " +"loop object and pass it to any coroutine function that wants to create " +"tasks, adding redundant clutter to your code." +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:187 +msgid "" +"coroutine = loudmouth_penguin(magic_number=5)\n" +"# This creates a Task object and schedules its execution via the event " +"loop.\n" +"task = asyncio.create_task(coroutine)" +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:191 +msgid "" +"Earlier, we manually created the event loop and set it to run forever. In " +"practice, it's recommended to use (and common to see) :func:`asyncio.run`, " +"which takes care of managing the event loop and ensuring the provided " +"coroutine finishes before advancing. For example, many async programs follow " +"this setup::" +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:197 +msgid "" +"import asyncio\n" +"\n" +"async def main():\n" +" # Perform all sorts of wacky, wild asynchronous things...\n" +" ...\n" +"\n" +"if __name__ == \"__main__\":\n" +" asyncio.run(main())\n" +" # The program will not reach the following print statement until the\n" +" # coroutine main() finishes.\n" +" print(\"coroutine main() is done!\")" +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:209 +msgid "" +"It's important to be aware that the task itself is not added to the event " +"loop, only a callback to the task is. This matters if the task object you " +"created is garbage collected before it's called by the event loop. For " +"example, consider this program:" +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:215 +msgid "" +"async def hello():\n" +" print(\"hello!\")\n" +"\n" +"async def main():\n" +" asyncio.create_task(hello())\n" +" # Other asynchronous instructions which run for a while\n" +" # and cede control to the event loop...\n" +" ...\n" +"\n" +"asyncio.run(main())" +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:229 +msgid "" +"Because there's no reference to the task object created on line 5, it " +"*might* be garbage collected before the event loop invokes it. Later " +"instructions in the coroutine ``main()`` hand control back to the event loop " +"so it can invoke other jobs. When the event loop eventually tries to run the " +"task, it might fail and discover the task object does not exist! This can " +"also happen even if a coroutine keeps a reference to a task but completes " +"before that task finishes. When the coroutine exits, local variables go out " +"of scope and may be subject to garbage collection. In practice, ``asyncio`` " +"and Python's garbage collector work pretty hard to ensure this sort of thing " +"doesn't happen. But that's no reason to be reckless!" +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:245 +msgid "await" +msgstr "await" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:247 +msgid "" +":keyword:`await` is a Python keyword that's commonly used in one of two " +"different ways::" +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:250 +msgid "" +"await task\n" +"await coroutine" +msgstr "" +"await task\n" +"await coroutine" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:253 +msgid "" +"In a crucial way, the behavior of ``await`` depends on the type of object " +"being awaited." +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:256 +msgid "" +"Awaiting a task will cede control from the current task or coroutine to the " +"event loop. In the process of relinquishing control, a few important things " +"happen. We'll use the following code example to illustrate::" +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:261 +msgid "" +"async def plant_a_tree():\n" +" dig_the_hole_task = asyncio.create_task(dig_the_hole())\n" +" await dig_the_hole_task\n" +"\n" +" # Other instructions associated with planting a tree.\n" +" ..." +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:268 +msgid "" +"In this example, imagine the event loop has passed control to the start of " +"the coroutine ``plant_a_tree()``. As seen above, the coroutine creates a " +"task and then awaits it. The ``await dig_the_hole_task`` instruction adds a " +"callback (which will resume ``plant_a_tree()``) to the ``dig_the_hole_task`` " +"object's list of callbacks. And then, the instruction cedes control to the " +"event loop. Some time later, the event loop will pass control to " +"``dig_the_hole_task`` and the task will finish whatever it needs to do. Once " +"the task finishes, it will add its various callbacks to the event loop, in " +"this case, a call to resume ``plant_a_tree()``." +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:279 +msgid "" +"Generally speaking, when the awaited task finishes (``dig_the_hole_task``), " +"the original task or coroutine (``plant_a_tree()``) is added back to the " +"event loop's to-do list to be resumed." +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:283 +msgid "" +"This is a basic, yet reliable mental model. In practice, the control " +"handoffs are slightly more complex, but not by much. In part 2, we'll walk " +"through the details that make this possible." +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:287 +msgid "" +"**Unlike tasks, awaiting a coroutine does not hand control back to the event " +"loop!** Wrapping a coroutine in a task first, then awaiting that would cede " +"control. The behavior of ``await coroutine`` is effectively the same as " +"invoking a regular, synchronous Python function. Consider this program::" +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:295 +msgid "" +"import asyncio\n" +"\n" +"async def coro_a():\n" +" print(\"I am coro_a(). Hi!\")\n" +"\n" +"async def coro_b():\n" +" print(\"I am coro_b(). I sure hope no one hogs the event loop...\")\n" +"\n" +"async def main():\n" +" task_b = asyncio.create_task(coro_b())\n" +" num_repeats = 3\n" +" for _ in range(num_repeats):\n" +" await coro_a()\n" +" await task_b\n" +"\n" +"asyncio.run(main())" +msgstr "" +"import asyncio\n" +"\n" +"async def coro_a():\n" +" print(\"I am coro_a(). Hi!\")\n" +"\n" +"async def coro_b():\n" +" print(\"I am coro_b(). I sure hope no one hogs the event loop...\")\n" +"\n" +"async def main():\n" +" task_b = asyncio.create_task(coro_b())\n" +" num_repeats = 3\n" +" for _ in range(num_repeats):\n" +" await coro_a()\n" +" await task_b\n" +"\n" +"asyncio.run(main())" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:312 +msgid "" +"The first statement in the coroutine ``main()`` creates ``task_b`` and " +"schedules it for execution via the event loop. Then, ``coro_a()`` is " +"repeatedly awaited. Control never cedes to the event loop, which is why we " +"see the output of all three ``coro_a()`` invocations before ``coro_b()``'s " +"output:" +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:318 +msgid "" +"I am coro_a(). Hi!\n" +"I am coro_a(). Hi!\n" +"I am coro_a(). Hi!\n" +"I am coro_b(). I sure hope no one hogs the event loop..." +msgstr "" +"I am coro_a(). Hi!\n" +"I am coro_a(). Hi!\n" +"I am coro_a(). Hi!\n" +"I am coro_b(). I sure hope no one hogs the event loop..." + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:325 +msgid "" +"If we change ``await coro_a()`` to ``await asyncio.create_task(coro_a())``, " +"the behavior changes. The coroutine ``main()`` cedes control to the event " +"loop with that statement. The event loop then proceeds through its backlog " +"of work, calling ``task_b`` and then the task which wraps ``coro_a()`` " +"before resuming the coroutine ``main()``." +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:332 +msgid "" +"I am coro_b(). I sure hope no one hogs the event loop...\n" +"I am coro_a(). Hi!\n" +"I am coro_a(). Hi!\n" +"I am coro_a(). Hi!" +msgstr "" +"I am coro_b(). I sure hope no one hogs the event loop...\n" +"I am coro_a(). Hi!\n" +"I am coro_a(). Hi!\n" +"I am coro_a(). Hi!" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:339 +msgid "" +"This behavior of ``await coroutine`` can trip a lot of people up! That " +"example highlights how using only ``await coroutine`` could unintentionally " +"hog control from other tasks and effectively stall the event loop. :func:" +"`asyncio.run` can help you detect such occurrences via the ``debug=True`` " +"flag, which enables :ref:`debug mode `. Among other " +"things, it will log any coroutines that monopolize execution for 100ms or " +"longer." +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:349 +msgid "" +"The design intentionally trades off some conceptual clarity around usage of " +"``await`` for improved performance. Each time a task is awaited, control " +"needs to be passed all the way up the call stack to the event loop. That " +"might sound minor, but in a large program with many ``await`` statements and " +"a deep call stack, that overhead can add up to a meaningful performance drag." +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:358 +msgid "A conceptual overview part 2: the nuts and bolts" +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:360 +msgid "" +"Part 2 goes into detail on the mechanisms :mod:`!asyncio` uses to manage " +"control flow. This is where the magic happens. You'll come away from this " +"section knowing what ``await`` does behind the scenes and how to make your " +"own asynchronous operators." +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:368 +msgid "The inner workings of coroutines" +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:370 +msgid ":mod:`!asyncio` leverages four components to pass around control." +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:372 +msgid "" +":meth:`coroutine.send(arg) ` is the method used to start or " +"resume a coroutine. If the coroutine was paused and is now being resumed, " +"the argument ``arg`` will be sent in as the return value of the ``yield`` " +"statement which originally paused it. If the coroutine is being used for the " +"first time (as opposed to being resumed), ``arg`` must be ``None``." +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:380 +msgid "" +"class Rock:\n" +" def __await__(self):\n" +" value_sent_in = yield 7\n" +" print(f\"Rock.__await__ resuming with value: {value_sent_in}.\")\n" +" return value_sent_in\n" +"\n" +"async def main():\n" +" print(\"Beginning coroutine main().\")\n" +" rock = Rock()\n" +" print(\"Awaiting rock...\")\n" +" value_from_rock = await rock\n" +" print(f\"Coroutine received value: {value_from_rock} from rock.\")\n" +" return 23\n" +"\n" +"coroutine = main()\n" +"intermediate_result = coroutine.send(None)\n" +"print(f\"Coroutine paused and returned intermediate value: " +"{intermediate_result}.\")\n" +"\n" +"print(f\"Resuming coroutine and sending in value: 42.\")\n" +"try:\n" +" coroutine.send(42)\n" +"except StopIteration as e:\n" +" returned_value = e.value\n" +"print(f\"Coroutine main() finished and provided value: {returned_value}.\")" +msgstr "" +"class Rock:\n" +" def __await__(self):\n" +" value_sent_in = yield 7\n" +" print(f\"Rock.__await__ resuming with value: {value_sent_in}.\")\n" +" return value_sent_in\n" +"\n" +"async def main():\n" +" print(\"Beginning coroutine main().\")\n" +" rock = Rock()\n" +" print(\"Awaiting rock...\")\n" +" value_from_rock = await rock\n" +" print(f\"Coroutine received value: {value_from_rock} from rock.\")\n" +" return 23\n" +"\n" +"coroutine = main()\n" +"intermediate_result = coroutine.send(None)\n" +"print(f\"Coroutine paused and returned intermediate value: " +"{intermediate_result}.\")\n" +"\n" +"print(f\"Resuming coroutine and sending in value: 42.\")\n" +"try:\n" +" coroutine.send(42)\n" +"except StopIteration as e:\n" +" returned_value = e.value\n" +"print(f\"Coroutine main() finished and provided value: {returned_value}.\")" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:408 +msgid "" +":ref:`yield `, as usual, pauses execution and returns control to " +"the caller. In the example above, the ``yield``, on line 3, is called by " +"``... = await rock`` on line 11. More broadly speaking, ``await`` calls the :" +"meth:`~object.__await__` method of the given object. ``await`` also does one " +"more very special thing: it propagates (or \"passes along\") any ``yield``\\ " +"s it receives up the call chain. In this case, that's back to ``... = " +"coroutine.send(None)`` on line 16." +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:418 +msgid "" +"The coroutine is resumed via the ``coroutine.send(42)`` call on line 21. The " +"coroutine picks back up from where it ``yield``\\ ed (or paused) on line 3 " +"and executes the remaining statements in its body. When a coroutine " +"finishes, it raises a :exc:`StopIteration` exception with the return value " +"attached in the :attr:`~StopIteration.value` attribute." +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:424 +msgid "That snippet produces this output:" +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:426 +msgid "" +"Beginning coroutine main().\n" +"Awaiting rock...\n" +"Coroutine paused and returned intermediate value: 7.\n" +"Resuming coroutine and sending in value: 42.\n" +"Rock.__await__ resuming with value: 42.\n" +"Coroutine received value: 42 from rock.\n" +"Coroutine main() finished and provided value: 23." +msgstr "" +"Beginning coroutine main().\n" +"Awaiting rock...\n" +"Coroutine paused and returned intermediate value: 7.\n" +"Resuming coroutine and sending in value: 42.\n" +"Rock.__await__ resuming with value: 42.\n" +"Coroutine received value: 42 from rock.\n" +"Coroutine main() finished and provided value: 23." + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:436 +msgid "" +"It's worth pausing for a moment here and making sure you followed the " +"various ways that control flow and values were passed. A lot of important " +"ideas were covered and it's worth ensuring your understanding is firm." +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:440 +msgid "" +"The only way to yield (or effectively cede control) from a coroutine is to " +"``await`` an object that ``yield``\\ s in its ``__await__`` method. That " +"might sound odd to you. You might be thinking:" +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:444 +msgid "" +"1. What about a ``yield`` directly within the coroutine function? The " +"coroutine function becomes an :ref:`async generator function `, a different beast entirely." +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:449 +msgid "" +"2. What about a :ref:`yield from ` within the coroutine function " +"to a (plain) generator? That causes the error: ``SyntaxError: yield from not " +"allowed in a coroutine.`` This was intentionally designed for the sake of " +"simplicity -- mandating only one way of using coroutines. Initially " +"``yield`` was barred as well, but was re-accepted to allow for async " +"generators. Despite that, ``yield from`` and ``await`` effectively do the " +"same thing." +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:460 +msgid "Futures" +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:462 +msgid "" +"A :ref:`future ` is an object meant to represent a " +"computation's status and result. The term is a nod to the idea of something " +"still to come or not yet happened, and the object is a way to keep an eye on " +"that something." +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:467 +msgid "" +"A future has a few important attributes. One is its state, which can be " +"either \"pending\", \"cancelled\", or \"done\". Another is its result, which " +"is set when the state transitions to done. Unlike a coroutine, a future does " +"not represent the actual computation to be done; instead, it represents the " +"status and result of that computation, kind of like a status light (red, " +"yellow, or green) or indicator." +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:474 +msgid "" +":class:`asyncio.Task` subclasses :class:`asyncio.Future` in order to gain " +"these various capabilities. The prior section said tasks store a list of " +"callbacks, which wasn't entirely accurate. It's actually the ``Future`` " +"class that implements this logic, which ``Task`` inherits." +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:481 +msgid "" +"Futures may also be used directly (not via tasks). Tasks mark themselves as " +"done when their coroutine is complete. Futures are much more versatile and " +"will be marked as done when you say so. In this way, they're the flexible " +"interface for you to make your own conditions for waiting and resuming." +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:489 +msgid "A homemade asyncio.sleep" +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:491 +msgid "" +"We'll go through an example of how you could leverage a future to create " +"your own variant of asynchronous sleep (``async_sleep``) which mimics :func:" +"`asyncio.sleep`." +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:495 +msgid "" +"This snippet registers a few tasks with the event loop and then awaits the " +"task created by ``asyncio.create_task``, which wraps the ``async_sleep(3)`` " +"coroutine. We want that task to finish only after three seconds have " +"elapsed, but without preventing other tasks from running." +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:502 +msgid "" +"async def other_work():\n" +" print(\"I like work. Work work.\")\n" +"\n" +"async def main():\n" +" # Add a few other tasks to the event loop, so there's something\n" +" # to do while asynchronously sleeping.\n" +" work_tasks = [\n" +" asyncio.create_task(other_work()),\n" +" asyncio.create_task(other_work()),\n" +" asyncio.create_task(other_work())\n" +" ]\n" +" print(\n" +" \"Beginning asynchronous sleep at time: \"\n" +" f\"{datetime.datetime.now().strftime(\"%H:%M:%S\")}.\"\n" +" )\n" +" await asyncio.create_task(async_sleep(3))\n" +" print(\n" +" \"Done asynchronous sleep at time: \"\n" +" f\"{datetime.datetime.now().strftime(\"%H:%M:%S\")}.\"\n" +" )\n" +" # asyncio.gather effectively awaits each task in the collection.\n" +" await asyncio.gather(*work_tasks)" +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:526 +msgid "" +"Below, we use a future to enable custom control over when that task will be " +"marked as done. If :meth:`future.set_result() ` " +"(the method responsible for marking that future as done) is never called, " +"then this task will never finish. We've also enlisted the help of another " +"task, which we'll see in a moment, that will monitor how much time has " +"elapsed and, accordingly, call ``future.set_result()``." +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:537 +msgid "" +"async def async_sleep(seconds: float):\n" +" future = asyncio.Future()\n" +" time_to_wake = time.time() + seconds\n" +" # Add the watcher-task to the event loop.\n" +" watcher_task = asyncio.create_task(_sleep_watcher(future, " +"time_to_wake))\n" +" # Block until the future is marked as done.\n" +" await future" +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:545 +msgid "" +"Below, we use a rather bare ``YieldToEventLoop()`` object to ``yield`` from " +"its ``__await__`` method, ceding control to the event loop. This is " +"effectively the same as calling ``asyncio.sleep(0)``, but this approach " +"offers more clarity, not to mention it's somewhat cheating to use ``asyncio." +"sleep`` when showcasing how to implement it!" +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:551 +msgid "" +"As usual, the event loop cycles through its tasks, giving them control and " +"receiving control back when they pause or finish. The ``watcher_task``, " +"which runs the coroutine ``_sleep_watcher(...)``, will be invoked once per " +"full cycle of the event loop. On each resumption, it'll check the time and " +"if not enough has elapsed, then it'll pause once again and hand control back " +"to the event loop. Once enough time has elapsed, ``_sleep_watcher(...)`` " +"marks the future as done and completes by exiting its infinite ``while`` " +"loop. Given this helper task is only invoked once per cycle of the event " +"loop, you'd be correct to note that this asynchronous sleep will sleep *at " +"least* three seconds, rather than exactly three seconds. Note this is also " +"true of ``asyncio.sleep``." +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:567 +msgid "" +"class YieldToEventLoop:\n" +" def __await__(self):\n" +" yield\n" +"\n" +"async def _sleep_watcher(future, time_to_wake):\n" +" while True:\n" +" if time.time() >= time_to_wake:\n" +" # This marks the future as done.\n" +" future.set_result(None)\n" +" break\n" +" else:\n" +" await YieldToEventLoop()" +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:580 +msgid "Here is the full program's output:" +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:582 +msgid "" +"$ python custom-async-sleep.py\n" +"Beginning asynchronous sleep at time: 14:52:22.\n" +"I like work. Work work.\n" +"I like work. Work work.\n" +"I like work. Work work.\n" +"Done asynchronous sleep at time: 14:52:25." +msgstr "" +"$ python custom-async-sleep.py\n" +"Beginning asynchronous sleep at time: 14:52:22.\n" +"I like work. Work work.\n" +"I like work. Work work.\n" +"I like work. Work work.\n" +"Done asynchronous sleep at time: 14:52:25." + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:591 +msgid "" +"You might feel this implementation of asynchronous sleep was unnecessarily " +"convoluted. And, well, it was. The example was meant to showcase the " +"versatility of futures with a simple example that could be mimicked for more " +"complex needs. For reference, you could implement it without futures, like " +"so::" +msgstr "" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:598 +msgid "" +"async def simpler_async_sleep(seconds):\n" +" time_to_wake = time.time() + seconds\n" +" while True:\n" +" if time.time() >= time_to_wake:\n" +" return\n" +" else:\n" +" await YieldToEventLoop()" +msgstr "" +"async def simpler_async_sleep(seconds):\n" +" time_to_wake = time.time() + seconds\n" +" while True:\n" +" if time.time() >= time_to_wake:\n" +" return\n" +" else:\n" +" await YieldToEventLoop()" + +#: ../../howto/a-conceptual-overview-of-asyncio.rst:606 +msgid "" +"But that's all for now. Hopefully you're ready to more confidently dive into " +"some async programming or check out advanced topics in the :mod:`rest of the " +"documentation `." +msgstr "" diff --git a/howto/annotations.po b/howto/annotations.po index f6a5b8f4ca..8183a70509 100644 --- a/howto/annotations.po +++ b/howto/annotations.po @@ -1,494 +1,494 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# FIRST AUTHOR , YEAR. -# -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-12-01 00:17+0000\n" -"PO-Revision-Date: 2023-11-08 23:11+0800\n" -"Last-Translator: rockleon \n" -"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" -"tw)\n" -"Language: zh_TW\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=UTF-8\n" -"Content-Transfer-Encoding: 8bit\n" -"X-Generator: Poedit 3.4.1\n" - -#: ../../howto/annotations.rst:5 -msgid "Annotations Best Practices" -msgstr "註釋 (annotation) 最佳實踐" - -#: ../../howto/annotations.rst:0 -msgid "author" -msgstr "作者" - -#: ../../howto/annotations.rst:7 -msgid "Larry Hastings" -msgstr "Larry Hastings" - -#: ../../howto/annotations.rst:9 -msgid "Abstract" -msgstr "摘要" - -#: ../../howto/annotations.rst:11 -msgid "" -"This document is designed to encapsulate the best practices for working with " -"annotations dicts. If you write Python code that examines " -"``__annotations__`` on Python objects, we encourage you to follow the " -"guidelines described below." -msgstr "" -"本文件旨在封裝 (encapsulate) 使用註釋字典 (annotations dicts) 的最佳實踐。如" -"果你寫 Python 程式碼並在調查 Python 物件上的 ``__annotations__`` ，我們鼓勵你" -"遵循下面描述的準則。" - -#: ../../howto/annotations.rst:16 -msgid "" -"The document is organized into four sections: best practices for accessing " -"the annotations of an object in Python versions 3.10 and newer, best " -"practices for accessing the annotations of an object in Python versions 3.9 " -"and older, other best practices for ``__annotations__`` that apply to any " -"Python version, and quirks of ``__annotations__``." -msgstr "" -"本文件分為四個部分：在 Python 3.10 及更高版本中存取物件註釋的最佳實踐、在 " -"Python 3.9 及更早版本中存取物件註釋的最佳實踐、適用於任何Python 版本 " -"``__annotations__`` 的最佳實踐，以及 ``__annotations__`` 的奇異之處。" - -#: ../../howto/annotations.rst:26 -msgid "" -"Note that this document is specifically about working with " -"``__annotations__``, not uses *for* annotations. If you're looking for " -"information on how to use \"type hints\" in your code, please see the :mod:" -"`typing` module." -msgstr "" -"請注意，本文件是特別說明 ``__annotations__`` 的使用，而非\\ *如何使用*\\ 註" -"釋。如果你正在尋找如何在你的程式碼中使用「型別提示 (type hint)」的資訊，請查" -"閱模組 (module) :mod:`typing`。" - -#: ../../howto/annotations.rst:33 -msgid "Accessing The Annotations Dict Of An Object In Python 3.10 And Newer" -msgstr "在 Python 3.10 及更高版本中存取物件的註釋字典" - -#: ../../howto/annotations.rst:35 -msgid "" -"Python 3.10 adds a new function to the standard library: :func:`inspect." -"get_annotations`. In Python versions 3.10 through 3.13, calling this " -"function is the best practice for accessing the annotations dict of any " -"object that supports annotations. This function can also \"un-stringize\" " -"stringized annotations for you." -msgstr "" -"Python 3.10 在標準函式庫中新增了一個新函式：:func:`inspect.get_annotations`。" -"在 Python 3.10 到 3.13，呼叫此函式是存取任何支援註釋的物件的註釋字典的最佳實" -"踐。此函式也可以為你「取消字串化 (un-stringize)」字串化註釋。" - -#: ../../howto/annotations.rst:42 -msgid "" -"In Python 3.14, there is a new :mod:`annotationlib` module with " -"functionality for working with annotations. This includes a :func:" -"`annotationlib.get_annotations` function, which supersedes :func:`inspect." -"get_annotations`." -msgstr "" - -#: ../../howto/annotations.rst:47 -msgid "" -"If for some reason :func:`inspect.get_annotations` isn't viable for your use " -"case, you may access the ``__annotations__`` data member manually. Best " -"practice for this changed in Python 3.10 as well: as of Python 3.10, ``o." -"__annotations__`` is guaranteed to *always* work on Python functions, " -"classes, and modules. If you're certain the object you're examining is one " -"of these three *specific* objects, you may simply use ``o.__annotations__`` " -"to get at the object's annotations dict." -msgstr "" -"若由於某種原因 :func:`inspect.get_annotations` 對你的場合不可行，你可以手動存" -"取 ``__annotations__`` 資料成員。 Python 3.10 中的最佳實踐也已經改變：從 " -"Python 3.10 開始，保證 ``o.__annotations__`` \\ *始終*\\ 適用於 Python 函式、" -"類別 (class) 和模組。如果你確定正在檢查的物件是這三個\\ *特定*\\ 物件之一，你" -"可以簡單地使用 ``o.__annotations__`` 來取得物件的註釋字典。" - -#: ../../howto/annotations.rst:57 -msgid "" -"However, other types of callables--for example, callables created by :func:" -"`functools.partial`--may not have an ``__annotations__`` attribute defined. " -"When accessing the ``__annotations__`` of a possibly unknown object, best " -"practice in Python versions 3.10 and newer is to call :func:`getattr` with " -"three arguments, for example ``getattr(o, '__annotations__', None)``." -msgstr "" -"但是，其他型別的 callable（可呼叫物件）（例如，由 :func:`functools.partial` " -"建立的 callable）可能沒有定義 ``__annotations__`` 屬性 (attribute)。當存取可" -"能未知的物件的 ``__annotations__`` 時，Python 3.10 及更高版本中的最佳實踐是使" -"用三個參數呼叫 :func:`getattr`，例如 ``getattr(o, '__annotations__', " -"None)``。" - -#: ../../howto/annotations.rst:65 -msgid "" -"Before Python 3.10, accessing ``__annotations__`` on a class that defines no " -"annotations but that has a parent class with annotations would return the " -"parent's ``__annotations__``. In Python 3.10 and newer, the child class's " -"annotations will be an empty dict instead." -msgstr "" -"在 Python 3.10 之前，存取未定義註釋但具有註釋的父類別的類別上的 " -"``__annotations__`` 將傳回父類別的 ``__annotations__``。在 Python 3.10 及更高" -"版本中，子類別的註釋將會是一個空字典。" - -#: ../../howto/annotations.rst:73 -msgid "Accessing The Annotations Dict Of An Object In Python 3.9 And Older" -msgstr "在 Python 3.9 及更早版本中存取物件的註釋字典" - -#: ../../howto/annotations.rst:75 -msgid "" -"In Python 3.9 and older, accessing the annotations dict of an object is much " -"more complicated than in newer versions. The problem is a design flaw in " -"these older versions of Python, specifically to do with class annotations." -msgstr "" -"在 Python 3.9 及更早版本中，存取物件的註釋字典比新版本複雜得多。問題出在於這" -"些舊版 Python 中有設計缺陷，特別是與類別註釋有關的設計缺陷。" - -#: ../../howto/annotations.rst:80 -msgid "" -"Best practice for accessing the annotations dict of other objects--" -"functions, other callables, and modules--is the same as best practice for " -"3.10, assuming you aren't calling :func:`inspect.get_annotations`: you " -"should use three-argument :func:`getattr` to access the object's " -"``__annotations__`` attribute." -msgstr "" -"存取其他物件（如函式、其他 callable 和模組）的註釋字典的最佳實踐與 3.10 的最" -"佳實踐相同，假設你沒有呼叫 :func:`inspect.get_annotations`：你應該使用三個：" -"參數 :func:`getattr` 來存取物件的 ``__annotations__`` 屬性。" - -#: ../../howto/annotations.rst:87 -msgid "" -"Unfortunately, this isn't best practice for classes. The problem is that, " -"since ``__annotations__`` is optional on classes, and because classes can " -"inherit attributes from their base classes, accessing the " -"``__annotations__`` attribute of a class may inadvertently return the " -"annotations dict of a *base class.* As an example::" -msgstr "" -"不幸的是，這不是類別的最佳實踐。問題是，由於 ``__annotations__`` 在類別上是選" -"填的 (optional)，並且因為類別可以從其基底類別 (base class) 繼承屬性，所以存取" -"類別的 ``__annotations__`` 屬性可能會無意中回傳\\ *基底類別的註釋字典。*\\ 舉" -"例來說： ::" - -#: ../../howto/annotations.rst:94 -msgid "" -"class Base:\n" -" a: int = 3\n" -" b: str = 'abc'\n" -"\n" -"class Derived(Base):\n" -" pass\n" -"\n" -"print(Derived.__annotations__)" -msgstr "" -"class Base:\n" -" a: int = 3\n" -" b: str = 'abc'\n" -"\n" -"class Derived(Base):\n" -" pass\n" -"\n" -"print(Derived.__annotations__)" - -#: ../../howto/annotations.rst:103 -msgid "This will print the annotations dict from ``Base``, not ``Derived``." -msgstr "這將印出 (print) 來自 ``Base`` 的註釋字典，而不是 ``Derived``。" - -#: ../../howto/annotations.rst:106 -msgid "" -"Your code will have to have a separate code path if the object you're " -"examining is a class (``isinstance(o, type)``). In that case, best practice " -"relies on an implementation detail of Python 3.9 and before: if a class has " -"annotations defined, they are stored in the class's :attr:`~type.__dict__` " -"dictionary. Since the class may or may not have annotations defined, best " -"practice is to call the :meth:`~dict.get` method on the class dict." -msgstr "" -"如果你正在檢查的物件是一個類別 (``isinstance(o, type)``)，你的程式碼將必須有" -"一個單獨的程式碼路徑。在這種情況下，最佳實踐依賴 Python 3.9 及之前版本的實作" -"細節 (implementation detail)：如果一個類別定義了註釋，它們將儲存在該類別的 :" -"attr:`~type.__dict__` 字典中。由於類別可能定義了註釋，也可能沒有定義，因此最" -"佳實踐是在類別字典上呼叫 :meth:`~dict.get` 方法。" - -#: ../../howto/annotations.rst:114 -msgid "" -"To put it all together, here is some sample code that safely accesses the " -"``__annotations__`` attribute on an arbitrary object in Python 3.9 and " -"before::" -msgstr "" -"總而言之，以下是一些範例程式碼，可以安全地存取 Python 3.9 及先前版本中任意物" -"件上的 ``__annotations__`` 屬性：" - -#: ../../howto/annotations.rst:118 -msgid "" -"if isinstance(o, type):\n" -" ann = o.__dict__.get('__annotations__', None)\n" -"else:\n" -" ann = getattr(o, '__annotations__', None)" -msgstr "" -"if isinstance(o, type):\n" -" ann = o.__dict__.get('__annotations__', None)\n" -"else:\n" -" ann = getattr(o, '__annotations__', None)" - -#: ../../howto/annotations.rst:123 -msgid "" -"After running this code, ``ann`` should be either a dictionary or ``None``. " -"You're encouraged to double-check the type of ``ann`` using :func:" -"`isinstance` before further examination." -msgstr "" -"運行此程式碼後，``ann`` 應該是字典或 ``None``。我們鼓勵你在進一步檢查之前使" -"用 :func:`isinstance` 仔細檢查 ``ann`` 的型別。" - -#: ../../howto/annotations.rst:128 -msgid "" -"Note that some exotic or malformed type objects may not have a :attr:`~type." -"__dict__` attribute, so for extra safety you may also wish to use :func:" -"`getattr` to access :attr:`!__dict__`." -msgstr "" -"請注意，某些外來 (exotic) 或格式錯誤 (malform) 的型別物件可能沒有 :attr:" -"`~type.__dict__` 屬性，因此為了額外的安全，你可能還希望使用 :func:`getattr` " -"來存取 :attr:`!__dict__`。" - -#: ../../howto/annotations.rst:134 -msgid "Manually Un-Stringizing Stringized Annotations" -msgstr "手動取消字串化註釋" - -#: ../../howto/annotations.rst:136 -msgid "" -"In situations where some annotations may be \"stringized\", and you wish to " -"evaluate those strings to produce the Python values they represent, it " -"really is best to call :func:`inspect.get_annotations` to do this work for " -"you." -msgstr "" -"在某些註釋可能被「字串化」的情況下，並且你希望評估這些字串以產生它們表示的 " -"Python 值，最好呼叫 :func:`inspect.get_annotations` 來為你完成這項工作。" - -#: ../../howto/annotations.rst:142 -msgid "" -"If you're using Python 3.9 or older, or if for some reason you can't use :" -"func:`inspect.get_annotations`, you'll need to duplicate its logic. You're " -"encouraged to examine the implementation of :func:`inspect.get_annotations` " -"in the current Python version and follow a similar approach." -msgstr "" -"如果你使用的是 Python 3.9 或更早版本，或者由於某種原因你無法使用 :func:" -"`inspect.get_annotations`，則需要複製其邏輯。我們鼓勵你檢查目前 Python 版本" -"中 :func:`inspect.get_annotations` 的實作並遵循類似的方法。" - -#: ../../howto/annotations.rst:148 -msgid "" -"In a nutshell, if you wish to evaluate a stringized annotation on an " -"arbitrary object ``o``:" -msgstr "簡而言之，如果你希望評估任意物件 ``o`` 上的字串化註釋： ::" - -#: ../../howto/annotations.rst:151 -msgid "" -"If ``o`` is a module, use ``o.__dict__`` as the ``globals`` when calling :" -"func:`eval`." -msgstr "" -"如果 ``o`` 是一個模組，則在呼叫 :func:`eval` 時使用 ``o.__dict__`` 作為\\ ``" -"全域變數``。" - -#: ../../howto/annotations.rst:153 -msgid "" -"If ``o`` is a class, use ``sys.modules[o.__module__].__dict__`` as the " -"``globals``, and ``dict(vars(o))`` as the ``locals``, when calling :func:" -"`eval`." -msgstr "" -"如果 ``o`` 是一個類別，當呼叫 :func:`eval` 時，則使用 ``sys.modules[o." -"__module__].__dict__`` 作為\\ ``全域變數``，使用 ``dict(vars(o))`` 作為\\ ``" -"區域變數``。" - -#: ../../howto/annotations.rst:156 -msgid "" -"If ``o`` is a wrapped callable using :func:`functools.update_wrapper`, :func:" -"`functools.wraps`, or :func:`functools.partial`, iteratively unwrap it by " -"accessing either ``o.__wrapped__`` or ``o.func`` as appropriate, until you " -"have found the root unwrapped function." -msgstr "" -"如果 ``o`` 是使用 :func:`functools.update_wrapper`、:func:`functools.wraps` " -"或 :func:`functools.partial` 包裝的 callable ，請依據需求，透過存取 ``o." -"__wrapped__`` 或 ``o.func`` 來疊代解開它，直到找到根解包函式。" - -#: ../../howto/annotations.rst:160 -msgid "" -"If ``o`` is a callable (but not a class), use :attr:`o.__globals__ ` as the globals when calling :func:`eval`." -msgstr "" -"如果 ``o`` 是 callable（但不是類別），則在呼叫 :func:`eval` 時使用 :attr:`o." -"__globals__ ` 作為全域變數。" - -#: ../../howto/annotations.rst:164 -msgid "" -"However, not all string values used as annotations can be successfully " -"turned into Python values by :func:`eval`. String values could theoretically " -"contain any valid string, and in practice there are valid use cases for type " -"hints that require annotating with string values that specifically *can't* " -"be evaluated. For example:" -msgstr "" -"然而，並非所有用作註釋的字串值都可以透過 :func:`eval` 成功轉換為 Python 值。" -"理論上，字串值可以包含任何有效的字串，並且在實踐中，型別提示存在有效的用例，" -"需要使用特定「無法」評估的字串值進行註釋。例如： ::" - -#: ../../howto/annotations.rst:171 -msgid "" -":pep:`604` union types using ``|``, before support for this was added to " -"Python 3.10." -msgstr "" -"在 Python 3.10 支援 :pep:`604` 聯合型別 (union type) ``|`` 之前使用它。" - -#: ../../howto/annotations.rst:173 -msgid "" -"Definitions that aren't needed at runtime, only imported when :const:`typing." -"TYPE_CHECKING` is true." -msgstr "" -"Runtime 中不需要的定義，僅在 :const:`typing.TYPE_CHECKING` 為 true 時匯入。" - -#: ../../howto/annotations.rst:176 -msgid "" -"If :func:`eval` attempts to evaluate such values, it will fail and raise an " -"exception. So, when designing a library API that works with annotations, " -"it's recommended to only attempt to evaluate string values when explicitly " -"requested to by the caller." -msgstr "" -"如果 :func:`eval` 嘗試計算這類型的值，它將失敗並引發例外。因此，在設計使用註" -"釋的函式庫 API 時，建議僅在呼叫者 (caller) 明確請求時嘗試評估字串值。" - -#: ../../howto/annotations.rst:184 -msgid "Best Practices For ``__annotations__`` In Any Python Version" -msgstr "任何 Python 版本中 ``__annotations__`` 的最佳實踐" - -#: ../../howto/annotations.rst:186 -msgid "" -"You should avoid assigning to the ``__annotations__`` member of objects " -"directly. Let Python manage setting ``__annotations__``." -msgstr "" -"你應該避免直接指派給物件的 ``__annotations__`` 成員。讓 Python 管理設定 " -"``__annotations__``。" - -#: ../../howto/annotations.rst:189 -msgid "" -"If you do assign directly to the ``__annotations__`` member of an object, " -"you should always set it to a ``dict`` object." -msgstr "" -"如果你直接指派給物件的 ``__annotations__`` 成員，則應始終將其設為 ``dict`` 物" -"件。" - -#: ../../howto/annotations.rst:192 -msgid "" -"You should avoid accessing ``__annotations__`` directly on any object. " -"Instead, use :func:`annotationlib.get_annotations` (Python 3.14+) or :func:" -"`inspect.get_annotations` (Python 3.10+)." -msgstr "" - -#: ../../howto/annotations.rst:196 -msgid "" -"If you do directly access the ``__annotations__`` member of an object, you " -"should ensure that it's a dictionary before attempting to examine its " -"contents." -msgstr "" -"如果直接存取物件的 ``__annotations__`` 成員，則應確保它是字典，然後再嘗試檢查" -"其內容。" - -#: ../../howto/annotations.rst:200 -msgid "You should avoid modifying ``__annotations__`` dicts." -msgstr "你應該避免修改 ``__annotations__`` 字典。" - -#: ../../howto/annotations.rst:202 -msgid "" -"You should avoid deleting the ``__annotations__`` attribute of an object." -msgstr "你應該避免刪除物件的 ``__annotations__`` 屬性。" - -#: ../../howto/annotations.rst:207 -msgid "``__annotations__`` Quirks" -msgstr "``__annotations__`` 奇異之處" - -#: ../../howto/annotations.rst:209 -msgid "" -"In all versions of Python 3, function objects lazy-create an annotations " -"dict if no annotations are defined on that object. You can delete the " -"``__annotations__`` attribute using ``del fn.__annotations__``, but if you " -"then access ``fn.__annotations__`` the object will create a new empty dict " -"that it will store and return as its annotations. Deleting the annotations " -"on a function before it has lazily created its annotations dict will throw " -"an ``AttributeError``; using ``del fn.__annotations__`` twice in a row is " -"guaranteed to always throw an ``AttributeError``." -msgstr "" -"在 Python 3 的所有版本中，如果沒有在該物件上定義註釋，則函式物件會延遲建立 " -"(lazy-create) 註釋字典。你可以使用 ``del fn.__annotations__`` 刪除 " -"``__annotations__`` 屬性，但如果你隨後存取 ``fn.__annotations__``，該物件將建" -"立一個新的空字典，它將作為註釋儲存並傳回。在函式延遲建立註釋字典之前刪除函式" -"上的註釋將拋出 ``AttributeError``；連續兩次使用 ``del fn.__annotations__`` 保" -"證總是拋出 ``AttributeError`` 。" - -#: ../../howto/annotations.rst:219 -msgid "" -"Everything in the above paragraph also applies to class and module objects " -"in Python 3.10 and newer." -msgstr "上一段的所有內容也適用於 Python 3.10 及更高版本中的類別和模組物件。" - -#: ../../howto/annotations.rst:222 -msgid "" -"In all versions of Python 3, you can set ``__annotations__`` on a function " -"object to ``None``. However, subsequently accessing the annotations on that " -"object using ``fn.__annotations__`` will lazy-create an empty dictionary as " -"per the first paragraph of this section. This is *not* true of modules and " -"classes, in any Python version; those objects permit setting " -"``__annotations__`` to any Python value, and will retain whatever value is " -"set." -msgstr "" -"在 Python 3 的所有版本中，你可以將函式物件上的 ``__annotations__`` 設定為 " -"``None``。但是，隨後使用 ``fn.__annotations__`` 存取該物件上的註釋將根據本節" -"第一段的內容延遲建立一個空字典。對於任何 Python 版本中的模組和類別來說，情況" -"\\ *並非如此*\\；這些物件允許將 ``__annotations__`` 設定為任何 Python 值，並" -"且將保留設定的任何值。" - -#: ../../howto/annotations.rst:230 -msgid "" -"If Python stringizes your annotations for you (using ``from __future__ " -"import annotations``), and you specify a string as an annotation, the string " -"will itself be quoted. In effect the annotation is quoted *twice.* For " -"example::" -msgstr "" -"如果 Python 為你字串化你的註釋（使用 ``from __future__ import " -"annotations``），並且你指定一個字串作為註釋，則該字串本身將被引用。實際上，註" -"釋被引用了\\ *兩次。*\\ 例如： ::" - -#: ../../howto/annotations.rst:236 -msgid "" -"from __future__ import annotations\n" -"def foo(a: \"str\"): pass\n" -"\n" -"print(foo.__annotations__)" -msgstr "" -"from __future__ import annotations\n" -"def foo(a: \"str\"): pass\n" -"\n" -"print(foo.__annotations__)" - -#: ../../howto/annotations.rst:241 -msgid "" -"This prints ``{'a': \"'str'\"}``. This shouldn't really be considered a " -"\"quirk\"; it's mentioned here simply because it might be surprising." -msgstr "" -"這會印出 ``{'a': \"'str'\"}``。這不應該被認為是一個「奇異的事」，他在這裡被簡" -"單提及，因為他可能會讓人意想不到。" - -#: ../../howto/annotations.rst:244 -msgid "" -"If you use a class with a custom metaclass and access ``__annotations__`` on " -"the class, you may observe unexpected behavior; see :pep:`749 <749#pep749-" -"metaclasses>` for some examples. You can avoid these quirks by using :func:" -"`annotationlib.get_annotations` on Python 3.14+ or :func:`inspect." -"get_annotations` on Python 3.10+. On earlier versions of Python, you can " -"avoid these bugs by accessing the annotations from the class's :attr:`~type." -"__dict__` (for example, ``cls.__dict__.get('__annotations__', None)``)." -msgstr "" - -#: ../../howto/annotations.rst:253 -msgid "" -"In some versions of Python, instances of classes may have an " -"``__annotations__`` attribute. However, this is not supported functionality. " -"If you need the annotations of an instance, you can use :func:`type` to " -"access its class (for example, ``annotationlib." -"get_annotations(type(myinstance))`` on Python 3.14+)." -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# FIRST AUTHOR , YEAR. +# +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-12-01 00:17+0000\n" +"PO-Revision-Date: 2023-11-08 23:11+0800\n" +"Last-Translator: rockleon \n" +"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" +"tw)\n" +"Language: zh_TW\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"X-Generator: Poedit 3.4.1\n" + +#: ../../howto/annotations.rst:5 +msgid "Annotations Best Practices" +msgstr "註釋 (annotation) 最佳實踐" + +#: ../../howto/annotations.rst:0 +msgid "author" +msgstr "作者" + +#: ../../howto/annotations.rst:7 +msgid "Larry Hastings" +msgstr "Larry Hastings" + +#: ../../howto/annotations.rst:9 +msgid "Abstract" +msgstr "摘要" + +#: ../../howto/annotations.rst:11 +msgid "" +"This document is designed to encapsulate the best practices for working with " +"annotations dicts. If you write Python code that examines " +"``__annotations__`` on Python objects, we encourage you to follow the " +"guidelines described below." +msgstr "" +"本文件旨在封裝 (encapsulate) 使用註釋字典 (annotations dicts) 的最佳實踐。如" +"果你寫 Python 程式碼並在調查 Python 物件上的 ``__annotations__`` ，我們鼓勵你" +"遵循下面描述的準則。" + +#: ../../howto/annotations.rst:16 +msgid "" +"The document is organized into four sections: best practices for accessing " +"the annotations of an object in Python versions 3.10 and newer, best " +"practices for accessing the annotations of an object in Python versions 3.9 " +"and older, other best practices for ``__annotations__`` that apply to any " +"Python version, and quirks of ``__annotations__``." +msgstr "" +"本文件分為四個部分：在 Python 3.10 及更高版本中存取物件註釋的最佳實踐、在 " +"Python 3.9 及更早版本中存取物件註釋的最佳實踐、適用於任何Python 版本 " +"``__annotations__`` 的最佳實踐，以及 ``__annotations__`` 的奇異之處。" + +#: ../../howto/annotations.rst:26 +msgid "" +"Note that this document is specifically about working with " +"``__annotations__``, not uses *for* annotations. If you're looking for " +"information on how to use \"type hints\" in your code, please see the :mod:" +"`typing` module." +msgstr "" +"請注意，本文件是特別說明 ``__annotations__`` 的使用，而非\\ *如何使用*\\ 註" +"釋。如果你正在尋找如何在你的程式碼中使用「型別提示 (type hint)」的資訊，請查" +"閱模組 (module) :mod:`typing`。" + +#: ../../howto/annotations.rst:33 +msgid "Accessing The Annotations Dict Of An Object In Python 3.10 And Newer" +msgstr "在 Python 3.10 及更高版本中存取物件的註釋字典" + +#: ../../howto/annotations.rst:35 +msgid "" +"Python 3.10 adds a new function to the standard library: :func:`inspect." +"get_annotations`. In Python versions 3.10 through 3.13, calling this " +"function is the best practice for accessing the annotations dict of any " +"object that supports annotations. This function can also \"un-stringize\" " +"stringized annotations for you." +msgstr "" +"Python 3.10 在標準函式庫中新增了一個新函式：:func:`inspect.get_annotations`。" +"在 Python 3.10 到 3.13，呼叫此函式是存取任何支援註釋的物件的註釋字典的最佳實" +"踐。此函式也可以為你「取消字串化 (un-stringize)」字串化註釋。" + +#: ../../howto/annotations.rst:42 +msgid "" +"In Python 3.14, there is a new :mod:`annotationlib` module with " +"functionality for working with annotations. This includes a :func:" +"`annotationlib.get_annotations` function, which supersedes :func:`inspect." +"get_annotations`." +msgstr "" + +#: ../../howto/annotations.rst:47 +msgid "" +"If for some reason :func:`inspect.get_annotations` isn't viable for your use " +"case, you may access the ``__annotations__`` data member manually. Best " +"practice for this changed in Python 3.10 as well: as of Python 3.10, ``o." +"__annotations__`` is guaranteed to *always* work on Python functions, " +"classes, and modules. If you're certain the object you're examining is one " +"of these three *specific* objects, you may simply use ``o.__annotations__`` " +"to get at the object's annotations dict." +msgstr "" +"若由於某種原因 :func:`inspect.get_annotations` 對你的場合不可行，你可以手動存" +"取 ``__annotations__`` 資料成員。 Python 3.10 中的最佳實踐也已經改變：從 " +"Python 3.10 開始，保證 ``o.__annotations__`` \\ *始終*\\ 適用於 Python 函式、" +"類別 (class) 和模組。如果你確定正在檢查的物件是這三個\\ *特定*\\ 物件之一，你" +"可以簡單地使用 ``o.__annotations__`` 來取得物件的註釋字典。" + +#: ../../howto/annotations.rst:57 +msgid "" +"However, other types of callables--for example, callables created by :func:" +"`functools.partial`--may not have an ``__annotations__`` attribute defined. " +"When accessing the ``__annotations__`` of a possibly unknown object, best " +"practice in Python versions 3.10 and newer is to call :func:`getattr` with " +"three arguments, for example ``getattr(o, '__annotations__', None)``." +msgstr "" +"但是，其他型別的 callable（可呼叫物件）（例如，由 :func:`functools.partial` " +"建立的 callable）可能沒有定義 ``__annotations__`` 屬性 (attribute)。當存取可" +"能未知的物件的 ``__annotations__`` 時，Python 3.10 及更高版本中的最佳實踐是使" +"用三個參數呼叫 :func:`getattr`，例如 ``getattr(o, '__annotations__', " +"None)``。" + +#: ../../howto/annotations.rst:65 +msgid "" +"Before Python 3.10, accessing ``__annotations__`` on a class that defines no " +"annotations but that has a parent class with annotations would return the " +"parent's ``__annotations__``. In Python 3.10 and newer, the child class's " +"annotations will be an empty dict instead." +msgstr "" +"在 Python 3.10 之前，存取未定義註釋但具有註釋的父類別的類別上的 " +"``__annotations__`` 將傳回父類別的 ``__annotations__``。在 Python 3.10 及更高" +"版本中，子類別的註釋將會是一個空字典。" + +#: ../../howto/annotations.rst:73 +msgid "Accessing The Annotations Dict Of An Object In Python 3.9 And Older" +msgstr "在 Python 3.9 及更早版本中存取物件的註釋字典" + +#: ../../howto/annotations.rst:75 +msgid "" +"In Python 3.9 and older, accessing the annotations dict of an object is much " +"more complicated than in newer versions. The problem is a design flaw in " +"these older versions of Python, specifically to do with class annotations." +msgstr "" +"在 Python 3.9 及更早版本中，存取物件的註釋字典比新版本複雜得多。問題出在於這" +"些舊版 Python 中有設計缺陷，特別是與類別註釋有關的設計缺陷。" + +#: ../../howto/annotations.rst:80 +msgid "" +"Best practice for accessing the annotations dict of other objects--" +"functions, other callables, and modules--is the same as best practice for " +"3.10, assuming you aren't calling :func:`inspect.get_annotations`: you " +"should use three-argument :func:`getattr` to access the object's " +"``__annotations__`` attribute." +msgstr "" +"存取其他物件（如函式、其他 callable 和模組）的註釋字典的最佳實踐與 3.10 的最" +"佳實踐相同，假設你沒有呼叫 :func:`inspect.get_annotations`：你應該使用三個：" +"參數 :func:`getattr` 來存取物件的 ``__annotations__`` 屬性。" + +#: ../../howto/annotations.rst:87 +msgid "" +"Unfortunately, this isn't best practice for classes. The problem is that, " +"since ``__annotations__`` is optional on classes, and because classes can " +"inherit attributes from their base classes, accessing the " +"``__annotations__`` attribute of a class may inadvertently return the " +"annotations dict of a *base class.* As an example::" +msgstr "" +"不幸的是，這不是類別的最佳實踐。問題是，由於 ``__annotations__`` 在類別上是選" +"填的 (optional)，並且因為類別可以從其基底類別 (base class) 繼承屬性，所以存取" +"類別的 ``__annotations__`` 屬性可能會無意中回傳\\ *基底類別的註釋字典。*\\ 舉" +"例來說： ::" + +#: ../../howto/annotations.rst:94 +msgid "" +"class Base:\n" +" a: int = 3\n" +" b: str = 'abc'\n" +"\n" +"class Derived(Base):\n" +" pass\n" +"\n" +"print(Derived.__annotations__)" +msgstr "" +"class Base:\n" +" a: int = 3\n" +" b: str = 'abc'\n" +"\n" +"class Derived(Base):\n" +" pass\n" +"\n" +"print(Derived.__annotations__)" + +#: ../../howto/annotations.rst:103 +msgid "This will print the annotations dict from ``Base``, not ``Derived``." +msgstr "這將印出 (print) 來自 ``Base`` 的註釋字典，而不是 ``Derived``。" + +#: ../../howto/annotations.rst:106 +msgid "" +"Your code will have to have a separate code path if the object you're " +"examining is a class (``isinstance(o, type)``). In that case, best practice " +"relies on an implementation detail of Python 3.9 and before: if a class has " +"annotations defined, they are stored in the class's :attr:`~type.__dict__` " +"dictionary. Since the class may or may not have annotations defined, best " +"practice is to call the :meth:`~dict.get` method on the class dict." +msgstr "" +"如果你正在檢查的物件是一個類別 (``isinstance(o, type)``)，你的程式碼將必須有" +"一個單獨的程式碼路徑。在這種情況下，最佳實踐依賴 Python 3.9 及之前版本的實作" +"細節 (implementation detail)：如果一個類別定義了註釋，它們將儲存在該類別的 :" +"attr:`~type.__dict__` 字典中。由於類別可能定義了註釋，也可能沒有定義，因此最" +"佳實踐是在類別字典上呼叫 :meth:`~dict.get` 方法。" + +#: ../../howto/annotations.rst:114 +msgid "" +"To put it all together, here is some sample code that safely accesses the " +"``__annotations__`` attribute on an arbitrary object in Python 3.9 and " +"before::" +msgstr "" +"總而言之，以下是一些範例程式碼，可以安全地存取 Python 3.9 及先前版本中任意物" +"件上的 ``__annotations__`` 屬性：" + +#: ../../howto/annotations.rst:118 +msgid "" +"if isinstance(o, type):\n" +" ann = o.__dict__.get('__annotations__', None)\n" +"else:\n" +" ann = getattr(o, '__annotations__', None)" +msgstr "" +"if isinstance(o, type):\n" +" ann = o.__dict__.get('__annotations__', None)\n" +"else:\n" +" ann = getattr(o, '__annotations__', None)" + +#: ../../howto/annotations.rst:123 +msgid "" +"After running this code, ``ann`` should be either a dictionary or ``None``. " +"You're encouraged to double-check the type of ``ann`` using :func:" +"`isinstance` before further examination." +msgstr "" +"運行此程式碼後，``ann`` 應該是字典或 ``None``。我們鼓勵你在進一步檢查之前使" +"用 :func:`isinstance` 仔細檢查 ``ann`` 的型別。" + +#: ../../howto/annotations.rst:128 +msgid "" +"Note that some exotic or malformed type objects may not have a :attr:`~type." +"__dict__` attribute, so for extra safety you may also wish to use :func:" +"`getattr` to access :attr:`!__dict__`." +msgstr "" +"請注意，某些外來 (exotic) 或格式錯誤 (malform) 的型別物件可能沒有 :attr:" +"`~type.__dict__` 屬性，因此為了額外的安全，你可能還希望使用 :func:`getattr` " +"來存取 :attr:`!__dict__`。" + +#: ../../howto/annotations.rst:134 +msgid "Manually Un-Stringizing Stringized Annotations" +msgstr "手動取消字串化註釋" + +#: ../../howto/annotations.rst:136 +msgid "" +"In situations where some annotations may be \"stringized\", and you wish to " +"evaluate those strings to produce the Python values they represent, it " +"really is best to call :func:`inspect.get_annotations` to do this work for " +"you." +msgstr "" +"在某些註釋可能被「字串化」的情況下，並且你希望評估這些字串以產生它們表示的 " +"Python 值，最好呼叫 :func:`inspect.get_annotations` 來為你完成這項工作。" + +#: ../../howto/annotations.rst:142 +msgid "" +"If you're using Python 3.9 or older, or if for some reason you can't use :" +"func:`inspect.get_annotations`, you'll need to duplicate its logic. You're " +"encouraged to examine the implementation of :func:`inspect.get_annotations` " +"in the current Python version and follow a similar approach." +msgstr "" +"如果你使用的是 Python 3.9 或更早版本，或者由於某種原因你無法使用 :func:" +"`inspect.get_annotations`，則需要複製其邏輯。我們鼓勵你檢查目前 Python 版本" +"中 :func:`inspect.get_annotations` 的實作並遵循類似的方法。" + +#: ../../howto/annotations.rst:148 +msgid "" +"In a nutshell, if you wish to evaluate a stringized annotation on an " +"arbitrary object ``o``:" +msgstr "簡而言之，如果你希望評估任意物件 ``o`` 上的字串化註釋： ::" + +#: ../../howto/annotations.rst:151 +msgid "" +"If ``o`` is a module, use ``o.__dict__`` as the ``globals`` when calling :" +"func:`eval`." +msgstr "" +"如果 ``o`` 是一個模組，則在呼叫 :func:`eval` 時使用 ``o.__dict__`` 作為\\ ``" +"全域變數``。" + +#: ../../howto/annotations.rst:153 +msgid "" +"If ``o`` is a class, use ``sys.modules[o.__module__].__dict__`` as the " +"``globals``, and ``dict(vars(o))`` as the ``locals``, when calling :func:" +"`eval`." +msgstr "" +"如果 ``o`` 是一個類別，當呼叫 :func:`eval` 時，則使用 ``sys.modules[o." +"__module__].__dict__`` 作為\\ ``全域變數``，使用 ``dict(vars(o))`` 作為\\ ``" +"區域變數``。" + +#: ../../howto/annotations.rst:156 +msgid "" +"If ``o`` is a wrapped callable using :func:`functools.update_wrapper`, :func:" +"`functools.wraps`, or :func:`functools.partial`, iteratively unwrap it by " +"accessing either ``o.__wrapped__`` or ``o.func`` as appropriate, until you " +"have found the root unwrapped function." +msgstr "" +"如果 ``o`` 是使用 :func:`functools.update_wrapper`、:func:`functools.wraps` " +"或 :func:`functools.partial` 包裝的 callable ，請依據需求，透過存取 ``o." +"__wrapped__`` 或 ``o.func`` 來疊代解開它，直到找到根解包函式。" + +#: ../../howto/annotations.rst:160 +msgid "" +"If ``o`` is a callable (but not a class), use :attr:`o.__globals__ ` as the globals when calling :func:`eval`." +msgstr "" +"如果 ``o`` 是 callable（但不是類別），則在呼叫 :func:`eval` 時使用 :attr:`o." +"__globals__ ` 作為全域變數。" + +#: ../../howto/annotations.rst:164 +msgid "" +"However, not all string values used as annotations can be successfully " +"turned into Python values by :func:`eval`. String values could theoretically " +"contain any valid string, and in practice there are valid use cases for type " +"hints that require annotating with string values that specifically *can't* " +"be evaluated. For example:" +msgstr "" +"然而，並非所有用作註釋的字串值都可以透過 :func:`eval` 成功轉換為 Python 值。" +"理論上，字串值可以包含任何有效的字串，並且在實踐中，型別提示存在有效的用例，" +"需要使用特定「無法」評估的字串值進行註釋。例如： ::" + +#: ../../howto/annotations.rst:171 +msgid "" +":pep:`604` union types using ``|``, before support for this was added to " +"Python 3.10." +msgstr "" +"在 Python 3.10 支援 :pep:`604` 聯合型別 (union type) ``|`` 之前使用它。" + +#: ../../howto/annotations.rst:173 +msgid "" +"Definitions that aren't needed at runtime, only imported when :const:`typing." +"TYPE_CHECKING` is true." +msgstr "" +"Runtime 中不需要的定義，僅在 :const:`typing.TYPE_CHECKING` 為 true 時匯入。" + +#: ../../howto/annotations.rst:176 +msgid "" +"If :func:`eval` attempts to evaluate such values, it will fail and raise an " +"exception. So, when designing a library API that works with annotations, " +"it's recommended to only attempt to evaluate string values when explicitly " +"requested to by the caller." +msgstr "" +"如果 :func:`eval` 嘗試計算這類型的值，它將失敗並引發例外。因此，在設計使用註" +"釋的函式庫 API 時，建議僅在呼叫者 (caller) 明確請求時嘗試評估字串值。" + +#: ../../howto/annotations.rst:184 +msgid "Best Practices For ``__annotations__`` In Any Python Version" +msgstr "任何 Python 版本中 ``__annotations__`` 的最佳實踐" + +#: ../../howto/annotations.rst:186 +msgid "" +"You should avoid assigning to the ``__annotations__`` member of objects " +"directly. Let Python manage setting ``__annotations__``." +msgstr "" +"你應該避免直接指派給物件的 ``__annotations__`` 成員。讓 Python 管理設定 " +"``__annotations__``。" + +#: ../../howto/annotations.rst:189 +msgid "" +"If you do assign directly to the ``__annotations__`` member of an object, " +"you should always set it to a ``dict`` object." +msgstr "" +"如果你直接指派給物件的 ``__annotations__`` 成員，則應始終將其設為 ``dict`` 物" +"件。" + +#: ../../howto/annotations.rst:192 +msgid "" +"You should avoid accessing ``__annotations__`` directly on any object. " +"Instead, use :func:`annotationlib.get_annotations` (Python 3.14+) or :func:" +"`inspect.get_annotations` (Python 3.10+)." +msgstr "" + +#: ../../howto/annotations.rst:196 +msgid "" +"If you do directly access the ``__annotations__`` member of an object, you " +"should ensure that it's a dictionary before attempting to examine its " +"contents." +msgstr "" +"如果直接存取物件的 ``__annotations__`` 成員，則應確保它是字典，然後再嘗試檢查" +"其內容。" + +#: ../../howto/annotations.rst:200 +msgid "You should avoid modifying ``__annotations__`` dicts." +msgstr "你應該避免修改 ``__annotations__`` 字典。" + +#: ../../howto/annotations.rst:202 +msgid "" +"You should avoid deleting the ``__annotations__`` attribute of an object." +msgstr "你應該避免刪除物件的 ``__annotations__`` 屬性。" + +#: ../../howto/annotations.rst:207 +msgid "``__annotations__`` Quirks" +msgstr "``__annotations__`` 奇異之處" + +#: ../../howto/annotations.rst:209 +msgid "" +"In all versions of Python 3, function objects lazy-create an annotations " +"dict if no annotations are defined on that object. You can delete the " +"``__annotations__`` attribute using ``del fn.__annotations__``, but if you " +"then access ``fn.__annotations__`` the object will create a new empty dict " +"that it will store and return as its annotations. Deleting the annotations " +"on a function before it has lazily created its annotations dict will throw " +"an ``AttributeError``; using ``del fn.__annotations__`` twice in a row is " +"guaranteed to always throw an ``AttributeError``." +msgstr "" +"在 Python 3 的所有版本中，如果沒有在該物件上定義註釋，則函式物件會延遲建立 " +"(lazy-create) 註釋字典。你可以使用 ``del fn.__annotations__`` 刪除 " +"``__annotations__`` 屬性，但如果你隨後存取 ``fn.__annotations__``，該物件將建" +"立一個新的空字典，它將作為註釋儲存並傳回。在函式延遲建立註釋字典之前刪除函式" +"上的註釋將拋出 ``AttributeError``；連續兩次使用 ``del fn.__annotations__`` 保" +"證總是拋出 ``AttributeError`` 。" + +#: ../../howto/annotations.rst:219 +msgid "" +"Everything in the above paragraph also applies to class and module objects " +"in Python 3.10 and newer." +msgstr "上一段的所有內容也適用於 Python 3.10 及更高版本中的類別和模組物件。" + +#: ../../howto/annotations.rst:222 +msgid "" +"In all versions of Python 3, you can set ``__annotations__`` on a function " +"object to ``None``. However, subsequently accessing the annotations on that " +"object using ``fn.__annotations__`` will lazy-create an empty dictionary as " +"per the first paragraph of this section. This is *not* true of modules and " +"classes, in any Python version; those objects permit setting " +"``__annotations__`` to any Python value, and will retain whatever value is " +"set." +msgstr "" +"在 Python 3 的所有版本中，你可以將函式物件上的 ``__annotations__`` 設定為 " +"``None``。但是，隨後使用 ``fn.__annotations__`` 存取該物件上的註釋將根據本節" +"第一段的內容延遲建立一個空字典。對於任何 Python 版本中的模組和類別來說，情況" +"\\ *並非如此*\\；這些物件允許將 ``__annotations__`` 設定為任何 Python 值，並" +"且將保留設定的任何值。" + +#: ../../howto/annotations.rst:230 +msgid "" +"If Python stringizes your annotations for you (using ``from __future__ " +"import annotations``), and you specify a string as an annotation, the string " +"will itself be quoted. In effect the annotation is quoted *twice.* For " +"example::" +msgstr "" +"如果 Python 為你字串化你的註釋（使用 ``from __future__ import " +"annotations``），並且你指定一個字串作為註釋，則該字串本身將被引用。實際上，註" +"釋被引用了\\ *兩次。*\\ 例如： ::" + +#: ../../howto/annotations.rst:236 +msgid "" +"from __future__ import annotations\n" +"def foo(a: \"str\"): pass\n" +"\n" +"print(foo.__annotations__)" +msgstr "" +"from __future__ import annotations\n" +"def foo(a: \"str\"): pass\n" +"\n" +"print(foo.__annotations__)" + +#: ../../howto/annotations.rst:241 +msgid "" +"This prints ``{'a': \"'str'\"}``. This shouldn't really be considered a " +"\"quirk\"; it's mentioned here simply because it might be surprising." +msgstr "" +"這會印出 ``{'a': \"'str'\"}``。這不應該被認為是一個「奇異的事」，他在這裡被簡" +"單提及，因為他可能會讓人意想不到。" + +#: ../../howto/annotations.rst:244 +msgid "" +"If you use a class with a custom metaclass and access ``__annotations__`` on " +"the class, you may observe unexpected behavior; see :pep:`749 <749#pep749-" +"metaclasses>` for some examples. You can avoid these quirks by using :func:" +"`annotationlib.get_annotations` on Python 3.14+ or :func:`inspect." +"get_annotations` on Python 3.10+. On earlier versions of Python, you can " +"avoid these bugs by accessing the annotations from the class's :attr:`~type." +"__dict__` (for example, ``cls.__dict__.get('__annotations__', None)``)." +msgstr "" + +#: ../../howto/annotations.rst:253 +msgid "" +"In some versions of Python, instances of classes may have an " +"``__annotations__`` attribute. However, this is not supported functionality. " +"If you need the annotations of an instance, you can use :func:`type` to " +"access its class (for example, ``annotationlib." +"get_annotations(type(myinstance))`` on Python 3.14+)." +msgstr "" diff --git a/howto/argparse-optparse.po b/howto/argparse-optparse.po index 6d64dccdf7..b474238576 100644 --- a/howto/argparse-optparse.po +++ b/howto/argparse-optparse.po @@ -1,166 +1,166 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -#, fuzzy -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-12-29 11:18+0000\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \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" - -#: ../../howto/argparse-optparse.rst:8 -msgid "Migrating ``optparse`` code to ``argparse``" -msgstr "將 ``optparse`` 程式碼遷移到 ``argparse``" - -#: ../../howto/argparse-optparse.rst:10 -msgid "" -"The :mod:`argparse` module offers several higher level features not natively " -"provided by the :mod:`optparse` module, including:" -msgstr "" -":mod:`argparse` 模組提供了一些高階功能，這些功能在 :mod:`optparse` 模組中並未" -"原生提供，包括：" - -#: ../../howto/argparse-optparse.rst:13 -msgid "Handling positional arguments." -msgstr "處理位置引數。" - -#: ../../howto/argparse-optparse.rst:14 -msgid "Supporting subcommands." -msgstr "支援子命令。" - -#: ../../howto/argparse-optparse.rst:15 -msgid "Allowing alternative option prefixes like ``+`` and ``/``." -msgstr "允許替代選項前綴，如 ``+`` 和 ``/``。" - -#: ../../howto/argparse-optparse.rst:16 -msgid "Handling zero-or-more and one-or-more style arguments." -msgstr "" -"處理零或多個 (zero-or-more) 和一個或多個 (and one-or-more) 樣式的引數。" - -#: ../../howto/argparse-optparse.rst:17 -msgid "Producing more informative usage messages." -msgstr "產生更多資訊的使用訊息。" - -#: ../../howto/argparse-optparse.rst:18 -msgid "Providing a much simpler interface for custom ``type`` and ``action``." -msgstr "為自訂 ``type`` 和 ``action`` 提供了一個更簡單的介面。" - -#: ../../howto/argparse-optparse.rst:20 -msgid "" -"Originally, the :mod:`argparse` module attempted to maintain compatibility " -"with :mod:`optparse`. However, the fundamental design differences between " -"supporting declarative command line option processing (while leaving " -"positional argument processing to application code), and supporting both " -"named options and positional arguments in the declarative interface mean " -"that the API has diverged from that of ``optparse`` over time." -msgstr "" -"最初 :mod:`argparse` 模組試圖保持與 :mod:`optparse` 的相容性，但在基礎設計上" -"的存在差異 -- 支援宣告式 (declarative) 命令列選項處理 (同時將位置引數處理留給" -"應用程式的程式碼) 和在宣告式介面中支援命名選項 (named options) 和位置引數 -- " -"代表 API 隨著時間的推移已經與 ``optparse`` API 分歧。" - -#: ../../howto/argparse-optparse.rst:27 -msgid "" -"As described in :ref:`choosing-an-argument-parser`, applications that are " -"currently using :mod:`optparse` and are happy with the way it works can just " -"continue to use ``optparse``." -msgstr "" -"如 :ref:`choosing-an-argument-parser` 中所述，目前使用 :mod:`optparse` 並對其" -"運作方式滿意的應用程式可以繼續使用 ``optparse``。" - -#: ../../howto/argparse-optparse.rst:31 -msgid "" -"Application developers that are considering migrating should also review the " -"list of intrinsic behavioural differences described in that section before " -"deciding whether or not migration is desirable." -msgstr "" -"在決定是否遷移之前，應用程式開發人員應該先檢閱該段落中描述的內在行為差異清" -"單，來決定是否值得遷移。" - -#: ../../howto/argparse-optparse.rst:35 -msgid "" -"For applications that do choose to migrate from :mod:`optparse` to :mod:" -"`argparse`, the following suggestions should be helpful:" -msgstr "" -"對於選擇從 :mod:`optparse` 遷移到 :mod:`argparse` 的應用程式，以下建議應會有" -"所幫助：" - -#: ../../howto/argparse-optparse.rst:38 -msgid "" -"Replace all :meth:`optparse.OptionParser.add_option` calls with :meth:" -"`ArgumentParser.add_argument` calls." -msgstr "" -"將所有 :meth:`optparse.OptionParser.add_option` 呼叫替換為 :meth:" -"`ArgumentParser.add_argument` 呼叫。" - -#: ../../howto/argparse-optparse.rst:41 -msgid "" -"Replace ``(options, args) = parser.parse_args()`` with ``args = parser." -"parse_args()`` and add additional :meth:`ArgumentParser.add_argument` calls " -"for the positional arguments. Keep in mind that what was previously called " -"``options``, now in the :mod:`argparse` context is called ``args``." -msgstr "" -"將 ``(options, args) = parser.parse_args()`` 替換為 ``args = parser." -"parse_args()``，並為位置引數新增額外的 :meth:`ArgumentParser.add_argument` 呼" -"叫。請記住，以前稱為 ``options`` 的東西，在 :mod:`argparse` 情境中現在稱為 " -"``args``。" - -#: ../../howto/argparse-optparse.rst:46 -msgid "" -"Replace :meth:`optparse.OptionParser.disable_interspersed_args` by using :" -"meth:`~ArgumentParser.parse_intermixed_args` instead of :meth:" -"`~ArgumentParser.parse_args`." -msgstr "" -"使用 :meth:`~ArgumentParser.parse_intermixed_args` 來替換掉 :meth:`optparse." -"OptionParser.disable_interspersed_args`，而不是使用 :meth:`~ArgumentParser." -"parse_args`。" - -#: ../../howto/argparse-optparse.rst:50 -msgid "" -"Replace callback actions and the ``callback_*`` keyword arguments with " -"``type`` or ``action`` arguments." -msgstr "" -"將回呼動作和 ``callback_*`` 關鍵字引數替換為 ``type`` 或 ``action`` 引數。" - -#: ../../howto/argparse-optparse.rst:53 -msgid "" -"Replace string names for ``type`` keyword arguments with the corresponding " -"type objects (e.g. int, float, complex, etc)." -msgstr "" -"將 ``type`` 關鍵字引數的字串名稱替換為相應的類型物件 (例如 int、float、" -"complex 等)。" - -#: ../../howto/argparse-optparse.rst:56 -msgid "" -"Replace :class:`optparse.Values` with :class:`Namespace` and :exc:`optparse." -"OptionError` and :exc:`optparse.OptionValueError` with :exc:`ArgumentError`." -msgstr "" -"將 :class:`optparse.Values` 替換為 :class:`Namespace`，並將 :exc:`optparse." -"OptionError` 和 :exc:`optparse.OptionValueError` 替換為 :exc:" -"`ArgumentError`。" - -#: ../../howto/argparse-optparse.rst:60 -msgid "" -"Replace strings with implicit arguments such as ``%default`` or ``%prog`` " -"with the standard Python syntax to use dictionaries to format strings, that " -"is, ``%(default)s`` and ``%(prog)s``." -msgstr "" -"將隱式引數的字串，如 ``%default`` 或 ``%prog`` 替換為使用字典來格式化字串的標" -"準 Python 語法，即 ``%(default)s`` 和 ``%(prog)s``。" - -#: ../../howto/argparse-optparse.rst:64 -msgid "" -"Replace the OptionParser constructor ``version`` argument with a call to " -"``parser.add_argument('--version', action='version', version='')``." -msgstr "" -"將 OptionParser 建構函式的 ``version`` 引數替換為呼叫 ``parser." -"add_argument('--version', action='version', version='')``。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-12-29 11:18+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \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" + +#: ../../howto/argparse-optparse.rst:8 +msgid "Migrating ``optparse`` code to ``argparse``" +msgstr "將 ``optparse`` 程式碼遷移到 ``argparse``" + +#: ../../howto/argparse-optparse.rst:10 +msgid "" +"The :mod:`argparse` module offers several higher level features not natively " +"provided by the :mod:`optparse` module, including:" +msgstr "" +":mod:`argparse` 模組提供了一些高階功能，這些功能在 :mod:`optparse` 模組中並未" +"原生提供，包括：" + +#: ../../howto/argparse-optparse.rst:13 +msgid "Handling positional arguments." +msgstr "處理位置引數。" + +#: ../../howto/argparse-optparse.rst:14 +msgid "Supporting subcommands." +msgstr "支援子命令。" + +#: ../../howto/argparse-optparse.rst:15 +msgid "Allowing alternative option prefixes like ``+`` and ``/``." +msgstr "允許替代選項前綴，如 ``+`` 和 ``/``。" + +#: ../../howto/argparse-optparse.rst:16 +msgid "Handling zero-or-more and one-or-more style arguments." +msgstr "" +"處理零或多個 (zero-or-more) 和一個或多個 (and one-or-more) 樣式的引數。" + +#: ../../howto/argparse-optparse.rst:17 +msgid "Producing more informative usage messages." +msgstr "產生更多資訊的使用訊息。" + +#: ../../howto/argparse-optparse.rst:18 +msgid "Providing a much simpler interface for custom ``type`` and ``action``." +msgstr "為自訂 ``type`` 和 ``action`` 提供了一個更簡單的介面。" + +#: ../../howto/argparse-optparse.rst:20 +msgid "" +"Originally, the :mod:`argparse` module attempted to maintain compatibility " +"with :mod:`optparse`. However, the fundamental design differences between " +"supporting declarative command line option processing (while leaving " +"positional argument processing to application code), and supporting both " +"named options and positional arguments in the declarative interface mean " +"that the API has diverged from that of ``optparse`` over time." +msgstr "" +"最初 :mod:`argparse` 模組試圖保持與 :mod:`optparse` 的相容性，但在基礎設計上" +"的存在差異 -- 支援宣告式 (declarative) 命令列選項處理 (同時將位置引數處理留給" +"應用程式的程式碼) 和在宣告式介面中支援命名選項 (named options) 和位置引數 -- " +"代表 API 隨著時間的推移已經與 ``optparse`` API 分歧。" + +#: ../../howto/argparse-optparse.rst:27 +msgid "" +"As described in :ref:`choosing-an-argument-parser`, applications that are " +"currently using :mod:`optparse` and are happy with the way it works can just " +"continue to use ``optparse``." +msgstr "" +"如 :ref:`choosing-an-argument-parser` 中所述，目前使用 :mod:`optparse` 並對其" +"運作方式滿意的應用程式可以繼續使用 ``optparse``。" + +#: ../../howto/argparse-optparse.rst:31 +msgid "" +"Application developers that are considering migrating should also review the " +"list of intrinsic behavioural differences described in that section before " +"deciding whether or not migration is desirable." +msgstr "" +"在決定是否遷移之前，應用程式開發人員應該先檢閱該段落中描述的內在行為差異清" +"單，來決定是否值得遷移。" + +#: ../../howto/argparse-optparse.rst:35 +msgid "" +"For applications that do choose to migrate from :mod:`optparse` to :mod:" +"`argparse`, the following suggestions should be helpful:" +msgstr "" +"對於選擇從 :mod:`optparse` 遷移到 :mod:`argparse` 的應用程式，以下建議應會有" +"所幫助：" + +#: ../../howto/argparse-optparse.rst:38 +msgid "" +"Replace all :meth:`optparse.OptionParser.add_option` calls with :meth:" +"`ArgumentParser.add_argument` calls." +msgstr "" +"將所有 :meth:`optparse.OptionParser.add_option` 呼叫替換為 :meth:" +"`ArgumentParser.add_argument` 呼叫。" + +#: ../../howto/argparse-optparse.rst:41 +msgid "" +"Replace ``(options, args) = parser.parse_args()`` with ``args = parser." +"parse_args()`` and add additional :meth:`ArgumentParser.add_argument` calls " +"for the positional arguments. Keep in mind that what was previously called " +"``options``, now in the :mod:`argparse` context is called ``args``." +msgstr "" +"將 ``(options, args) = parser.parse_args()`` 替換為 ``args = parser." +"parse_args()``，並為位置引數新增額外的 :meth:`ArgumentParser.add_argument` 呼" +"叫。請記住，以前稱為 ``options`` 的東西，在 :mod:`argparse` 情境中現在稱為 " +"``args``。" + +#: ../../howto/argparse-optparse.rst:46 +msgid "" +"Replace :meth:`optparse.OptionParser.disable_interspersed_args` by using :" +"meth:`~ArgumentParser.parse_intermixed_args` instead of :meth:" +"`~ArgumentParser.parse_args`." +msgstr "" +"使用 :meth:`~ArgumentParser.parse_intermixed_args` 來替換掉 :meth:`optparse." +"OptionParser.disable_interspersed_args`，而不是使用 :meth:`~ArgumentParser." +"parse_args`。" + +#: ../../howto/argparse-optparse.rst:50 +msgid "" +"Replace callback actions and the ``callback_*`` keyword arguments with " +"``type`` or ``action`` arguments." +msgstr "" +"將回呼動作和 ``callback_*`` 關鍵字引數替換為 ``type`` 或 ``action`` 引數。" + +#: ../../howto/argparse-optparse.rst:53 +msgid "" +"Replace string names for ``type`` keyword arguments with the corresponding " +"type objects (e.g. int, float, complex, etc)." +msgstr "" +"將 ``type`` 關鍵字引數的字串名稱替換為相應的類型物件 (例如 int、float、" +"complex 等)。" + +#: ../../howto/argparse-optparse.rst:56 +msgid "" +"Replace :class:`optparse.Values` with :class:`Namespace` and :exc:`optparse." +"OptionError` and :exc:`optparse.OptionValueError` with :exc:`ArgumentError`." +msgstr "" +"將 :class:`optparse.Values` 替換為 :class:`Namespace`，並將 :exc:`optparse." +"OptionError` 和 :exc:`optparse.OptionValueError` 替換為 :exc:" +"`ArgumentError`。" + +#: ../../howto/argparse-optparse.rst:60 +msgid "" +"Replace strings with implicit arguments such as ``%default`` or ``%prog`` " +"with the standard Python syntax to use dictionaries to format strings, that " +"is, ``%(default)s`` and ``%(prog)s``." +msgstr "" +"將隱式引數的字串，如 ``%default`` 或 ``%prog`` 替換為使用字典來格式化字串的標" +"準 Python 語法，即 ``%(default)s`` 和 ``%(prog)s``。" + +#: ../../howto/argparse-optparse.rst:64 +msgid "" +"Replace the OptionParser constructor ``version`` argument with a call to " +"``parser.add_argument('--version', action='version', version='')``." +msgstr "" +"將 OptionParser 建構函式的 ``version`` 引數替換為呼叫 ``parser." +"add_argument('--version', action='version', version='')``。" diff --git a/howto/argparse.po b/howto/argparse.po index fde89eb929..f5527fb02e 100644 --- a/howto/argparse.po +++ b/howto/argparse.po @@ -1,1741 +1,1741 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# jerrychen , 2016 -# Evan Gui , 2016 -# Liang-Bo Wang , 2016 -# Adrian Liaw , 2018 -# Phil Lin , 2022 -# Matt Wang , 2023 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-12-29 11:18+0000\n" -"PO-Revision-Date: 2023-12-11 17:33+0800\n" -"Last-Translator: Matt Wang \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" -"X-Generator: Poedit 3.0.1\n" - -#: ../../howto/argparse.rst:5 -msgid "Argparse Tutorial" -msgstr "Argparse 教學" - -#: ../../howto/argparse.rst:0 -msgid "author" -msgstr "作者" - -#: ../../howto/argparse.rst:7 -msgid "Tshepang Mbambo" -msgstr "Tshepang Mbambo" - -#: ../../howto/argparse.rst:11 -msgid "" -"This tutorial is intended to be a gentle introduction to :mod:`argparse`, " -"the recommended command-line parsing module in the Python standard library." -msgstr "" -"本教學旨在簡要介紹 :mod:`argparse` 這個 Python 標準函式庫中推薦的命令列剖析模" -"組。" - -#: ../../howto/argparse.rst:16 -msgid "" -"The standard library includes two other libraries directly related to " -"command-line parameter processing: the lower level :mod:`optparse` module " -"(which may require more code to configure for a given application, but also " -"allows an application to request behaviors that ``argparse`` doesn't " -"support), and the very low level :mod:`getopt` (which specifically serves as " -"an equivalent to the :c:func:`!getopt` family of functions available to C " -"programmers). While neither of those modules is covered directly in this " -"guide, many of the core concepts in ``argparse`` first originated in " -"``optparse``, so some aspects of this tutorial will also be relevant to " -"``optparse`` users." -msgstr "" -"標準函式庫包含另外兩個與命令列參數處理直接相關的函式庫：較低階的 :mod:" -"`optparse` 模組（可能需要更多程式碼來為給定應用程式設定，但也允許應用程式要" -"求 ``argparse`` 不支援的行為），以及非常低階的 :mod:`getopt`\\ （專門用作 C " -"程式設計師可用的 :c:func:`!getopt` 函式系列的等價）。雖然這個指南並未直接涵蓋" -"這些模組，但 ``argparse`` 的許多核心概念最初來自於 ``optparse``，因此本教學的" -"某些部分也適用於 ``optparse`` 使用者。" - -#: ../../howto/argparse.rst:29 -msgid "Concepts" -msgstr "概念" - -#: ../../howto/argparse.rst:31 -msgid "" -"Let's show the sort of functionality that we are going to explore in this " -"introductory tutorial by making use of the :command:`ls` command:" -msgstr "" -"讓我們透過使用 :command:`ls` 指令來展示我們將在本介紹教學中探索的功能類型：" - -#: ../../howto/argparse.rst:34 -msgid "" -"$ ls\n" -"cpython devguide prog.py pypy rm-unused-function.patch\n" -"$ ls pypy\n" -"ctypes_configure demo dotviewer include lib_pypy lib-python ...\n" -"$ ls -l\n" -"total 20\n" -"drwxr-xr-x 19 wena wena 4096 Feb 18 18:51 cpython\n" -"drwxr-xr-x 4 wena wena 4096 Feb 8 12:04 devguide\n" -"-rwxr-xr-x 1 wena wena 535 Feb 19 00:05 prog.py\n" -"drwxr-xr-x 14 wena wena 4096 Feb 7 00:59 pypy\n" -"-rw-r--r-- 1 wena wena 741 Feb 18 01:01 rm-unused-function.patch\n" -"$ ls --help\n" -"Usage: ls [OPTION]... [FILE]...\n" -"List information about the FILEs (the current directory by default).\n" -"Sort entries alphabetically if none of -cftuvSUX nor --sort is specified.\n" -"..." -msgstr "" -"$ ls\n" -"cpython devguide prog.py pypy rm-unused-function.patch\n" -"$ ls pypy\n" -"ctypes_configure demo dotviewer include lib_pypy lib-python ...\n" -"$ ls -l\n" -"total 20\n" -"drwxr-xr-x 19 wena wena 4096 Feb 18 18:51 cpython\n" -"drwxr-xr-x 4 wena wena 4096 Feb 8 12:04 devguide\n" -"-rwxr-xr-x 1 wena wena 535 Feb 19 00:05 prog.py\n" -"drwxr-xr-x 14 wena wena 4096 Feb 7 00:59 pypy\n" -"-rw-r--r-- 1 wena wena 741 Feb 18 01:01 rm-unused-function.patch\n" -"$ ls --help\n" -"Usage: ls [OPTION]... [FILE]...\n" -"List information about the FILEs (the current directory by default).\n" -"Sort entries alphabetically if none of -cftuvSUX nor --sort is specified.\n" -"..." - -#: ../../howto/argparse.rst:53 -msgid "A few concepts we can learn from the four commands:" -msgstr "我們可以從這四個命令中學到一些概念：" - -#: ../../howto/argparse.rst:55 -msgid "" -"The :command:`ls` command is useful when run without any options at all. It " -"defaults to displaying the contents of the current directory." -msgstr "" -":command:`ls` 命令即便在沒有任何選項的情況下執行仍非常有用。它預設顯示目前目" -"錄的內容。" - -#: ../../howto/argparse.rst:58 -msgid "" -"If we want beyond what it provides by default, we tell it a bit more. In " -"this case, we want it to display a different directory, ``pypy``. What we " -"did is specify what is known as a positional argument. It's named so because " -"the program should know what to do with the value, solely based on where it " -"appears on the command line. This concept is more relevant to a command " -"like :command:`cp`, whose most basic usage is ``cp SRC DEST``. The first " -"position is *what you want copied,* and the second position is *where you " -"want it copied to*." -msgstr "" -"如果我們想要看到比它預設提供更多的內容，我們也需要多告訴它一點。在本例中，我" -"們希望它顯示不同的目錄 ``pypy``，我們做的是指定所謂的位置引數。之所以如此命名" -"是因為程式應該只根據該值在命令列中出現的位置來知道如何處理該值。這個概念與 :" -"command:`cp` 這樣的指令更相關，其最基本的用法是 ``cp SRC DEST``。第一個是\\ *" -"你想要複製的位置*，第二個是\\ *你想要複製過去的位置*。" - -#: ../../howto/argparse.rst:67 -msgid "" -"Now, say we want to change behaviour of the program. In our example, we " -"display more info for each file instead of just showing the file names. The " -"``-l`` in that case is known as an optional argument." -msgstr "" -"現在假設我們想要改變程式的行為。在我們的範例中，我們顯示每個檔案的更多資訊，" -"而不僅是顯示檔案名稱。在這種情況下，``-l`` 被稱為可選引數。" - -#: ../../howto/argparse.rst:71 -msgid "" -"That's a snippet of the help text. It's very useful in that you can come " -"across a program you have never used before, and can figure out how it works " -"simply by reading its help text." -msgstr "" -"這是幫助文字的片段。它非常有用，因為當你遇到以前從未使用過的程式時，只需閱讀" -"其幫助文字即可了解它的工作原理。" - -#: ../../howto/argparse.rst:77 -msgid "The basics" -msgstr "基本用法" - -#: ../../howto/argparse.rst:79 -msgid "Let us start with a very simple example which does (almost) nothing::" -msgstr "讓我們從一個非常簡單的例子開始，它（幾乎）什麼都不做： ::" - -#: ../../howto/argparse.rst:81 -msgid "" -"import argparse\n" -"parser = argparse.ArgumentParser()\n" -"parser.parse_args()" -msgstr "" -"import argparse\n" -"parser = argparse.ArgumentParser()\n" -"parser.parse_args()" - -#: ../../howto/argparse.rst:85 ../../howto/argparse.rst:193 -#: ../../howto/argparse.rst:214 -msgid "Following is a result of running the code:" -msgstr "程式碼執行結果如下：" - -#: ../../howto/argparse.rst:87 -msgid "" -"$ python prog.py\n" -"$ python prog.py --help\n" -"usage: prog.py [-h]\n" -"\n" -"options:\n" -" -h, --help show this help message and exit\n" -"$ python prog.py --verbose\n" -"usage: prog.py [-h]\n" -"prog.py: error: unrecognized arguments: --verbose\n" -"$ python prog.py foo\n" -"usage: prog.py [-h]\n" -"prog.py: error: unrecognized arguments: foo" -msgstr "" -"$ python prog.py\n" -"$ python prog.py --help\n" -"usage: prog.py [-h]\n" -"\n" -"options:\n" -" -h, --help show this help message and exit\n" -"$ python prog.py --verbose\n" -"usage: prog.py [-h]\n" -"prog.py: error: unrecognized arguments: --verbose\n" -"$ python prog.py foo\n" -"usage: prog.py [-h]\n" -"prog.py: error: unrecognized arguments: foo" - -#: ../../howto/argparse.rst:102 ../../howto/argparse.rst:259 -#: ../../howto/argparse.rst:303 -msgid "Here is what is happening:" -msgstr "這是發生的事情：" - -#: ../../howto/argparse.rst:104 -msgid "" -"Running the script without any options results in nothing displayed to " -"stdout. Not so useful." -msgstr "執行不帶任何選項的腳本不會在標準輸出中顯示任何內容。不太有用。" - -#: ../../howto/argparse.rst:107 -msgid "" -"The second one starts to display the usefulness of the :mod:`argparse` " -"module. We have done almost nothing, but already we get a nice help message." -msgstr "" -"第二個開始能夠顯現 :mod:`argparse` 模組的有用之處。我們幾乎什麼也沒做，但我們" -"已經收到了一個很好的幫助訊息。" - -#: ../../howto/argparse.rst:110 -msgid "" -"The ``--help`` option, which can also be shortened to ``-h``, is the only " -"option we get for free (i.e. no need to specify it). Specifying anything " -"else results in an error. But even then, we do get a useful usage message, " -"also for free." -msgstr "" -"``--help`` 選項也可以縮寫為 ``-h``，是我們能隨意獲得的唯一選項（即無需指定" -"它）。指定任何其他內容都會導致錯誤。但即便如此，我們也還是輕鬆地獲得了有用的" -"使用資訊。" - -#: ../../howto/argparse.rst:117 -msgid "Introducing Positional arguments" -msgstr "位置引數的介紹" - -#: ../../howto/argparse.rst:119 -msgid "An example::" -msgstr "例如： ::" - -#: ../../howto/argparse.rst:121 -msgid "" -"import argparse\n" -"parser = argparse.ArgumentParser()\n" -"parser.add_argument(\"echo\")\n" -"args = parser.parse_args()\n" -"print(args.echo)" -msgstr "" -"import argparse\n" -"parser = argparse.ArgumentParser()\n" -"parser.add_argument(\"echo\")\n" -"args = parser.parse_args()\n" -"print(args.echo)" - -#: ../../howto/argparse.rst:127 -msgid "And running the code:" -msgstr "執行這段程式碼：" - -#: ../../howto/argparse.rst:129 -msgid "" -"$ python prog.py\n" -"usage: prog.py [-h] echo\n" -"prog.py: error: the following arguments are required: echo\n" -"$ python prog.py --help\n" -"usage: prog.py [-h] echo\n" -"\n" -"positional arguments:\n" -" echo\n" -"\n" -"options:\n" -" -h, --help show this help message and exit\n" -"$ python prog.py foo\n" -"foo" -msgstr "" -"$ python prog.py\n" -"usage: prog.py [-h] echo\n" -"prog.py: error: the following arguments are required: echo\n" -"$ python prog.py --help\n" -"usage: prog.py [-h] echo\n" -"\n" -"positional arguments:\n" -" echo\n" -"\n" -"options:\n" -" -h, --help show this help message and exit\n" -"$ python prog.py foo\n" -"foo" - -#: ../../howto/argparse.rst:145 -msgid "Here is what's happening:" -msgstr "這是會發生的事情：" - -#: ../../howto/argparse.rst:147 -msgid "" -"We've added the :meth:`~ArgumentParser.add_argument` method, which is what " -"we use to specify which command-line options the program is willing to " -"accept. In this case, I've named it ``echo`` so that it's in line with its " -"function." -msgstr "" -"我們新增了 :meth:`~ArgumentParser.add_argument` 方法，我們用它來指定程式願意" -"接受哪些命令列選項。在本例中，我將其命名為 ``echo``，以便與其功能一致。" - -#: ../../howto/argparse.rst:151 -msgid "Calling our program now requires us to specify an option." -msgstr "現在呼叫我們的程式時需要指定一個選項。" - -#: ../../howto/argparse.rst:153 -msgid "" -"The :meth:`~ArgumentParser.parse_args` method actually returns some data " -"from the options specified, in this case, ``echo``." -msgstr "" -":meth:`~ArgumentParser.parse_args` 方法實際上從指定的選項中回傳一些資料，在本" -"例中為 ``echo``。" - -#: ../../howto/argparse.rst:156 -msgid "" -"The variable is some form of 'magic' that :mod:`argparse` performs for free " -"(i.e. no need to specify which variable that value is stored in). You will " -"also notice that its name matches the string argument given to the method, " -"``echo``." -msgstr "" -"該變數是某種形式的「魔法」，:mod:`argparse` 可以自由執行（即無需指定該值儲存" -"在哪個變數中）。你還會注意到，它的名稱與提供給方法 ``echo`` 的字串引數相符。" - -#: ../../howto/argparse.rst:161 -msgid "" -"Note however that, although the help display looks nice and all, it " -"currently is not as helpful as it can be. For example we see that we got " -"``echo`` as a positional argument, but we don't know what it does, other " -"than by guessing or by reading the source code. So, let's make it a bit more " -"useful::" -msgstr "" -"但請注意，儘管幫助顯示看起來不錯，但它目前還沒有發揮出應有的用處。例如，我們" -"看到 ``echo`` 作為位置引數，但除了猜測或閱讀原始程式碼之外，我們不知道它的作" -"用。那麼，我們來讓它變得更有用一點： ::" - -#: ../../howto/argparse.rst:166 -msgid "" -"import argparse\n" -"parser = argparse.ArgumentParser()\n" -"parser.add_argument(\"echo\", help=\"echo the string you use here\")\n" -"args = parser.parse_args()\n" -"print(args.echo)" -msgstr "" -"import argparse\n" -"parser = argparse.ArgumentParser()\n" -"parser.add_argument(\"echo\", help=\"echo the string you use here\")\n" -"args = parser.parse_args()\n" -"print(args.echo)" - -#: ../../howto/argparse.rst:172 -msgid "And we get:" -msgstr "然後我們得到：" - -#: ../../howto/argparse.rst:174 -msgid "" -"$ python prog.py -h\n" -"usage: prog.py [-h] echo\n" -"\n" -"positional arguments:\n" -" echo echo the string you use here\n" -"\n" -"options:\n" -" -h, --help show this help message and exit" -msgstr "" -"$ python prog.py -h\n" -"usage: prog.py [-h] echo\n" -"\n" -"positional arguments:\n" -" echo echo the string you use here\n" -"\n" -"options:\n" -" -h, --help show this help message and exit" - -#: ../../howto/argparse.rst:185 -msgid "Now, how about doing something even more useful::" -msgstr "現在來做一些更有用處的事情： ::" - -#: ../../howto/argparse.rst:187 -msgid "" -"import argparse\n" -"parser = argparse.ArgumentParser()\n" -"parser.add_argument(\"square\", help=\"display a square of a given " -"number\")\n" -"args = parser.parse_args()\n" -"print(args.square**2)" -msgstr "" -"import argparse\n" -"parser = argparse.ArgumentParser()\n" -"parser.add_argument(\"square\", help=\"display a square of a given " -"number\")\n" -"args = parser.parse_args()\n" -"print(args.square**2)" - -#: ../../howto/argparse.rst:195 -msgid "" -"$ python prog.py 4\n" -"Traceback (most recent call last):\n" -" File \"prog.py\", line 5, in \n" -" print(args.square**2)\n" -"TypeError: unsupported operand type(s) for ** or pow(): 'str' and 'int'" -msgstr "" -"$ python prog.py 4\n" -"Traceback (most recent call last):\n" -" File \"prog.py\", line 5, in \n" -" print(args.square**2)\n" -"TypeError: unsupported operand type(s) for ** or pow(): 'str' and 'int'" - -#: ../../howto/argparse.rst:203 -msgid "" -"That didn't go so well. That's because :mod:`argparse` treats the options we " -"give it as strings, unless we tell it otherwise. So, let's tell :mod:" -"`argparse` to treat that input as an integer::" -msgstr "" -"進展不太順利。這是因為，除非我們另有說明，:mod:`argparse` 會將我們給它的選項" -"視為字串。因此，讓我們告訴 :mod:`argparse` 將該輸入視為整數： ::" - -#: ../../howto/argparse.rst:207 -msgid "" -"import argparse\n" -"parser = argparse.ArgumentParser()\n" -"parser.add_argument(\"square\", help=\"display a square of a given " -"number\",\n" -" type=int)\n" -"args = parser.parse_args()\n" -"print(args.square**2)" -msgstr "" -"import argparse\n" -"parser = argparse.ArgumentParser()\n" -"parser.add_argument(\"square\", help=\"display a square of a given " -"number\",\n" -" type=int)\n" -"args = parser.parse_args()\n" -"print(args.square**2)" - -#: ../../howto/argparse.rst:216 -msgid "" -"$ python prog.py 4\n" -"16\n" -"$ python prog.py four\n" -"usage: prog.py [-h] square\n" -"prog.py: error: argument square: invalid int value: 'four'" -msgstr "" -"$ python prog.py 4\n" -"16\n" -"$ python prog.py four\n" -"usage: prog.py [-h] square\n" -"prog.py: error: argument square: invalid int value: 'four'" - -#: ../../howto/argparse.rst:224 -msgid "" -"That went well. The program now even helpfully quits on bad illegal input " -"before proceeding." -msgstr "順利進展。現在該程式甚至可以在繼續操作之前因錯誤的非法輸入而退出。" - -#: ../../howto/argparse.rst:229 -msgid "Introducing Optional arguments" -msgstr "可選引數的介紹" - -#: ../../howto/argparse.rst:231 -msgid "" -"So far we have been playing with positional arguments. Let us have a look on " -"how to add optional ones::" -msgstr "到目前為止，我們一直在討論位置引數。我們來看看如何新增可選引數： ::" - -#: ../../howto/argparse.rst:234 -msgid "" -"import argparse\n" -"parser = argparse.ArgumentParser()\n" -"parser.add_argument(\"--verbosity\", help=\"increase output verbosity\")\n" -"args = parser.parse_args()\n" -"if args.verbosity:\n" -" print(\"verbosity turned on\")" -msgstr "" -"import argparse\n" -"parser = argparse.ArgumentParser()\n" -"parser.add_argument(\"--verbosity\", help=\"increase output verbosity\")\n" -"args = parser.parse_args()\n" -"if args.verbosity:\n" -" print(\"verbosity turned on\")" - -#: ../../howto/argparse.rst:241 ../../howto/argparse.rst:287 -#: ../../howto/argparse.rst:403 ../../howto/argparse.rst:437 -msgid "And the output:" -msgstr "接者是結果：" - -#: ../../howto/argparse.rst:243 -msgid "" -"$ python prog.py --verbosity 1\n" -"verbosity turned on\n" -"$ python prog.py\n" -"$ python prog.py --help\n" -"usage: prog.py [-h] [--verbosity VERBOSITY]\n" -"\n" -"options:\n" -" -h, --help show this help message and exit\n" -" --verbosity VERBOSITY\n" -" increase output verbosity\n" -"$ python prog.py --verbosity\n" -"usage: prog.py [-h] [--verbosity VERBOSITY]\n" -"prog.py: error: argument --verbosity: expected one argument" -msgstr "" -"$ python prog.py --verbosity 1\n" -"verbosity turned on\n" -"$ python prog.py\n" -"$ python prog.py --help\n" -"usage: prog.py [-h] [--verbosity VERBOSITY]\n" -"\n" -"options:\n" -" -h, --help show this help message and exit\n" -" --verbosity VERBOSITY\n" -" increase output verbosity\n" -"$ python prog.py --verbosity\n" -"usage: prog.py [-h] [--verbosity VERBOSITY]\n" -"prog.py: error: argument --verbosity: expected one argument" - -#: ../../howto/argparse.rst:261 -msgid "" -"The program is written so as to display something when ``--verbosity`` is " -"specified and display nothing when not." -msgstr "" -"程式被編寫為在指定 ``--verbosity`` 時顯示一些內容，並在未指定時不顯示任何內" -"容。" - -#: ../../howto/argparse.rst:264 -msgid "" -"To show that the option is actually optional, there is no error when running " -"the program without it. Note that by default, if an optional argument isn't " -"used, the relevant variable, in this case ``args.verbosity``, is given " -"``None`` as a value, which is the reason it fails the truth test of the :" -"keyword:`if` statement." -msgstr "" -"為了表示該選項實際上是可選的，沒使用它來執行程式並不會出現錯誤。請注意，預設" -"情況下，如果未使用可選引數，則相關變數（在本例中為 ``args.verbosity``）將被賦" -"予 ``None`` 作為值，這就是它未能通過 :keyword:`if` 陳述式真值測試的原因。" - -#: ../../howto/argparse.rst:270 -msgid "The help message is a bit different." -msgstr "幫助訊息有點不同。" - -#: ../../howto/argparse.rst:272 -msgid "" -"When using the ``--verbosity`` option, one must also specify some value, any " -"value." -msgstr "當使用 ``--verbosity`` 選項時必須要指定一些值，任何值都可以。" - -#: ../../howto/argparse.rst:275 -msgid "" -"The above example accepts arbitrary integer values for ``--verbosity``, but " -"for our simple program, only two values are actually useful, ``True`` or " -"``False``. Let's modify the code accordingly::" -msgstr "" -"在上面的例子中，``--verbosity`` 接受任意的整數，但對我們的程式來說只接受兩個" -"輸入值， ``True`` 或 ``False``。所以我們來修改一下程式碼使其符合： ::" - -#: ../../howto/argparse.rst:279 -msgid "" -"import argparse\n" -"parser = argparse.ArgumentParser()\n" -"parser.add_argument(\"--verbose\", help=\"increase output verbosity\",\n" -" action=\"store_true\")\n" -"args = parser.parse_args()\n" -"if args.verbose:\n" -" print(\"verbosity turned on\")" -msgstr "" -"import argparse\n" -"parser = argparse.ArgumentParser()\n" -"parser.add_argument(\"--verbose\", help=\"increase output verbosity\",\n" -" action=\"store_true\")\n" -"args = parser.parse_args()\n" -"if args.verbose:\n" -" print(\"verbosity turned on\")" - -#: ../../howto/argparse.rst:289 -msgid "" -"$ python prog.py --verbose\n" -"verbosity turned on\n" -"$ python prog.py --verbose 1\n" -"usage: prog.py [-h] [--verbose]\n" -"prog.py: error: unrecognized arguments: 1\n" -"$ python prog.py --help\n" -"usage: prog.py [-h] [--verbose]\n" -"\n" -"options:\n" -" -h, --help show this help message and exit\n" -" --verbose increase output verbosity" -msgstr "" -"$ python prog.py --verbose\n" -"verbosity turned on\n" -"$ python prog.py --verbose 1\n" -"usage: prog.py [-h] [--verbose]\n" -"prog.py: error: unrecognized arguments: 1\n" -"$ python prog.py --help\n" -"usage: prog.py [-h] [--verbose]\n" -"\n" -"options:\n" -" -h, --help show this help message and exit\n" -" --verbose increase output verbosity" - -#: ../../howto/argparse.rst:305 -msgid "" -"The option is now more of a flag than something that requires a value. We " -"even changed the name of the option to match that idea. Note that we now " -"specify a new keyword, ``action``, and give it the value ``\"store_true\"``. " -"This means that, if the option is specified, assign the value ``True`` to " -"``args.verbose``. Not specifying it implies ``False``." -msgstr "" -"這個選項現在更像是一個旗標，而不是需要值的東西。我們甚至更改了選項的名稱以符" -"合這個想法。請注意，我們現在指定一個新的關鍵字 ``action``，並為其指定值 " -"``\"store_true\"``。這意味著，如果指定了該選項，則將值 ``True`` 指派給 " -"``args.verbose``。不指定它代表為 ``False``。" - -#: ../../howto/argparse.rst:312 -msgid "" -"It complains when you specify a value, in true spirit of what flags actually " -"are." -msgstr "當你指定一個值時，它會本著旗標的實際精神來抱怨。" - -#: ../../howto/argparse.rst:315 -msgid "Notice the different help text." -msgstr "請注意不同的幫助文字。" - -#: ../../howto/argparse.rst:319 -msgid "Short options" -msgstr "短選項" - -#: ../../howto/argparse.rst:321 -msgid "" -"If you are familiar with command line usage, you will notice that I haven't " -"yet touched on the topic of short versions of the options. It's quite " -"simple::" -msgstr "" -"如果你熟悉命令列用法，你會注意到我尚未提及選項的簡短版本。這很簡單： ::" - -#: ../../howto/argparse.rst:325 -msgid "" -"import argparse\n" -"parser = argparse.ArgumentParser()\n" -"parser.add_argument(\"-v\", \"--verbose\", help=\"increase output " -"verbosity\",\n" -" action=\"store_true\")\n" -"args = parser.parse_args()\n" -"if args.verbose:\n" -" print(\"verbosity turned on\")" -msgstr "" -"import argparse\n" -"parser = argparse.ArgumentParser()\n" -"parser.add_argument(\"-v\", \"--verbose\", help=\"increase output " -"verbosity\",\n" -" action=\"store_true\")\n" -"args = parser.parse_args()\n" -"if args.verbose:\n" -" print(\"verbosity turned on\")" - -#: ../../howto/argparse.rst:333 -msgid "And here goes:" -msgstr "而這為：" - -#: ../../howto/argparse.rst:335 -msgid "" -"$ python prog.py -v\n" -"verbosity turned on\n" -"$ python prog.py --help\n" -"usage: prog.py [-h] [-v]\n" -"\n" -"options:\n" -" -h, --help show this help message and exit\n" -" -v, --verbose increase output verbosity" -msgstr "" -"$ python prog.py -v\n" -"verbosity turned on\n" -"$ python prog.py --help\n" -"usage: prog.py [-h] [-v]\n" -"\n" -"options:\n" -" -h, --help show this help message and exit\n" -" -v, --verbose increase output verbosity" - -#: ../../howto/argparse.rst:346 -msgid "Note that the new ability is also reflected in the help text." -msgstr "請注意，新功能也反映在幫助文字中。" - -#: ../../howto/argparse.rst:350 -msgid "Combining Positional and Optional arguments" -msgstr "組合位置引數和可選引數" - -#: ../../howto/argparse.rst:352 -msgid "Our program keeps growing in complexity::" -msgstr "我們的程式的複雜性不斷增加： ::" - -#: ../../howto/argparse.rst:354 -msgid "" -"import argparse\n" -"parser = argparse.ArgumentParser()\n" -"parser.add_argument(\"square\", type=int,\n" -" help=\"display a square of a given number\")\n" -"parser.add_argument(\"-v\", \"--verbose\", action=\"store_true\",\n" -" help=\"increase output verbosity\")\n" -"args = parser.parse_args()\n" -"answer = args.square**2\n" -"if args.verbose:\n" -" print(f\"the square of {args.square} equals {answer}\")\n" -"else:\n" -" print(answer)" -msgstr "" -"import argparse\n" -"parser = argparse.ArgumentParser()\n" -"parser.add_argument(\"square\", type=int,\n" -" help=\"display a square of a given number\")\n" -"parser.add_argument(\"-v\", \"--verbose\", action=\"store_true\",\n" -" help=\"increase output verbosity\")\n" -"args = parser.parse_args()\n" -"answer = args.square**2\n" -"if args.verbose:\n" -" print(f\"the square of {args.square} equals {answer}\")\n" -"else:\n" -" print(answer)" - -#: ../../howto/argparse.rst:367 -msgid "And now the output:" -msgstr "然後現在的輸出結果：" - -#: ../../howto/argparse.rst:369 -msgid "" -"$ python prog.py\n" -"usage: prog.py [-h] [-v] square\n" -"prog.py: error: the following arguments are required: square\n" -"$ python prog.py 4\n" -"16\n" -"$ python prog.py 4 --verbose\n" -"the square of 4 equals 16\n" -"$ python prog.py --verbose 4\n" -"the square of 4 equals 16" -msgstr "" -"$ python prog.py\n" -"usage: prog.py [-h] [-v] square\n" -"prog.py: error: the following arguments are required: square\n" -"$ python prog.py 4\n" -"16\n" -"$ python prog.py 4 --verbose\n" -"the square of 4 equals 16\n" -"$ python prog.py --verbose 4\n" -"the square of 4 equals 16" - -#: ../../howto/argparse.rst:381 -msgid "We've brought back a positional argument, hence the complaint." -msgstr "我們帶回了位置引數，因而被抱怨。" - -#: ../../howto/argparse.rst:383 -msgid "Note that the order does not matter." -msgstr "請注意，順序並不重要。" - -#: ../../howto/argparse.rst:385 -msgid "" -"How about we give this program of ours back the ability to have multiple " -"verbosity values, and actually get to use them::" -msgstr "" -"我們讓這個程式擁有多個訊息詳細級別 (verbosity) 之值的能力，並實際使用它" -"們： ::" - -#: ../../howto/argparse.rst:388 -msgid "" -"import argparse\n" -"parser = argparse.ArgumentParser()\n" -"parser.add_argument(\"square\", type=int,\n" -" help=\"display a square of a given number\")\n" -"parser.add_argument(\"-v\", \"--verbosity\", type=int,\n" -" help=\"increase output verbosity\")\n" -"args = parser.parse_args()\n" -"answer = args.square**2\n" -"if args.verbosity == 2:\n" -" print(f\"the square of {args.square} equals {answer}\")\n" -"elif args.verbosity == 1:\n" -" print(f\"{args.square}^2 == {answer}\")\n" -"else:\n" -" print(answer)" -msgstr "" -"import argparse\n" -"parser = argparse.ArgumentParser()\n" -"parser.add_argument(\"square\", type=int,\n" -" help=\"display a square of a given number\")\n" -"parser.add_argument(\"-v\", \"--verbosity\", type=int,\n" -" help=\"increase output verbosity\")\n" -"args = parser.parse_args()\n" -"answer = args.square**2\n" -"if args.verbosity == 2:\n" -" print(f\"the square of {args.square} equals {answer}\")\n" -"elif args.verbosity == 1:\n" -" print(f\"{args.square}^2 == {answer}\")\n" -"else:\n" -" print(answer)" - -#: ../../howto/argparse.rst:405 -msgid "" -"$ python prog.py 4\n" -"16\n" -"$ python prog.py 4 -v\n" -"usage: prog.py [-h] [-v VERBOSITY] square\n" -"prog.py: error: argument -v/--verbosity: expected one argument\n" -"$ python prog.py 4 -v 1\n" -"4^2 == 16\n" -"$ python prog.py 4 -v 2\n" -"the square of 4 equals 16\n" -"$ python prog.py 4 -v 3\n" -"16" -msgstr "" -"$ python prog.py 4\n" -"16\n" -"$ python prog.py 4 -v\n" -"usage: prog.py [-h] [-v VERBOSITY] square\n" -"prog.py: error: argument -v/--verbosity: expected one argument\n" -"$ python prog.py 4 -v 1\n" -"4^2 == 16\n" -"$ python prog.py 4 -v 2\n" -"the square of 4 equals 16\n" -"$ python prog.py 4 -v 3\n" -"16" - -#: ../../howto/argparse.rst:419 -msgid "" -"These all look good except the last one, which exposes a bug in our program. " -"Let's fix it by restricting the values the ``--verbosity`` option can " -"accept::" -msgstr "" -"除了最後一個外都看起來正常，它透露了我們程式中的一個錯誤。我們可透過限制 ``--" -"verbosity`` 選項可以接受的值來修復它： ::" - -#: ../../howto/argparse.rst:422 -msgid "" -"import argparse\n" -"parser = argparse.ArgumentParser()\n" -"parser.add_argument(\"square\", type=int,\n" -" help=\"display a square of a given number\")\n" -"parser.add_argument(\"-v\", \"--verbosity\", type=int, choices=[0, 1, 2],\n" -" help=\"increase output verbosity\")\n" -"args = parser.parse_args()\n" -"answer = args.square**2\n" -"if args.verbosity == 2:\n" -" print(f\"the square of {args.square} equals {answer}\")\n" -"elif args.verbosity == 1:\n" -" print(f\"{args.square}^2 == {answer}\")\n" -"else:\n" -" print(answer)" -msgstr "" -"import argparse\n" -"parser = argparse.ArgumentParser()\n" -"parser.add_argument(\"square\", type=int,\n" -" help=\"display a square of a given number\")\n" -"parser.add_argument(\"-v\", \"--verbosity\", type=int, choices=[0, 1, 2],\n" -" help=\"increase output verbosity\")\n" -"args = parser.parse_args()\n" -"answer = args.square**2\n" -"if args.verbosity == 2:\n" -" print(f\"the square of {args.square} equals {answer}\")\n" -"elif args.verbosity == 1:\n" -" print(f\"{args.square}^2 == {answer}\")\n" -"else:\n" -" print(answer)" - -#: ../../howto/argparse.rst:439 -msgid "" -"$ python prog.py 4 -v 3\n" -"usage: prog.py [-h] [-v {0,1,2}] square\n" -"prog.py: error: argument -v/--verbosity: invalid choice: 3 (choose from 0, " -"1, 2)\n" -"$ python prog.py 4 -h\n" -"usage: prog.py [-h] [-v {0,1,2}] square\n" -"\n" -"positional arguments:\n" -" square display a square of a given number\n" -"\n" -"options:\n" -" -h, --help show this help message and exit\n" -" -v, --verbosity {0,1,2}\n" -" increase output verbosity" -msgstr "" -"$ python prog.py 4 -v 3\n" -"usage: prog.py [-h] [-v {0,1,2}] square\n" -"prog.py: error: argument -v/--verbosity: invalid choice: 3 (choose from 0, " -"1, 2)\n" -"$ python prog.py 4 -h\n" -"usage: prog.py [-h] [-v {0,1,2}] square\n" -"\n" -"positional arguments:\n" -" square display a square of a given number\n" -"\n" -"options:\n" -" -h, --help show this help message and exit\n" -" -v, --verbosity {0,1,2}\n" -" increase output verbosity" - -#: ../../howto/argparse.rst:455 -msgid "" -"Note that the change also reflects both in the error message as well as the " -"help string." -msgstr "請注意，更改也會反映在錯誤訊息和幫助字串中。" - -#: ../../howto/argparse.rst:458 -msgid "" -"Now, let's use a different approach of playing with verbosity, which is " -"pretty common. It also matches the way the CPython executable handles its " -"own verbosity argument (check the output of ``python --help``)::" -msgstr "" -"現在，讓我們使用另一種常見方法來玩玩訊息詳細級別。它也與 CPython 執行檔處理其" -"自身訊息詳細級別引數的方式相符（請見 ``python --help`` 的輸出）： ::" - -#: ../../howto/argparse.rst:462 -msgid "" -"import argparse\n" -"parser = argparse.ArgumentParser()\n" -"parser.add_argument(\"square\", type=int,\n" -" help=\"display the square of a given number\")\n" -"parser.add_argument(\"-v\", \"--verbosity\", action=\"count\",\n" -" help=\"increase output verbosity\")\n" -"args = parser.parse_args()\n" -"answer = args.square**2\n" -"if args.verbosity == 2:\n" -" print(f\"the square of {args.square} equals {answer}\")\n" -"elif args.verbosity == 1:\n" -" print(f\"{args.square}^2 == {answer}\")\n" -"else:\n" -" print(answer)" -msgstr "" -"import argparse\n" -"parser = argparse.ArgumentParser()\n" -"parser.add_argument(\"square\", type=int,\n" -" help=\"display the square of a given number\")\n" -"parser.add_argument(\"-v\", \"--verbosity\", action=\"count\",\n" -" help=\"increase output verbosity\")\n" -"args = parser.parse_args()\n" -"answer = args.square**2\n" -"if args.verbosity == 2:\n" -" print(f\"the square of {args.square} equals {answer}\")\n" -"elif args.verbosity == 1:\n" -" print(f\"{args.square}^2 == {answer}\")\n" -"else:\n" -" print(answer)" - -#: ../../howto/argparse.rst:477 -msgid "" -"We have introduced another action, \"count\", to count the number of " -"occurrences of specific options." -msgstr "我們已經介紹過另一個操作 \"count\" 用來計算指定的選項出現的次數。" - -#: ../../howto/argparse.rst:481 -msgid "" -"$ python prog.py 4\n" -"16\n" -"$ python prog.py 4 -v\n" -"4^2 == 16\n" -"$ python prog.py 4 -vv\n" -"the square of 4 equals 16\n" -"$ python prog.py 4 --verbosity --verbosity\n" -"the square of 4 equals 16\n" -"$ python prog.py 4 -v 1\n" -"usage: prog.py [-h] [-v] square\n" -"prog.py: error: unrecognized arguments: 1\n" -"$ python prog.py 4 -h\n" -"usage: prog.py [-h] [-v] square\n" -"\n" -"positional arguments:\n" -" square display a square of a given number\n" -"\n" -"options:\n" -" -h, --help show this help message and exit\n" -" -v, --verbosity increase output verbosity\n" -"$ python prog.py 4 -vvv\n" -"16" -msgstr "" -"$ python prog.py 4\n" -"16\n" -"$ python prog.py 4 -v\n" -"4^2 == 16\n" -"$ python prog.py 4 -vv\n" -"the square of 4 equals 16\n" -"$ python prog.py 4 --verbosity --verbosity\n" -"the square of 4 equals 16\n" -"$ python prog.py 4 -v 1\n" -"usage: prog.py [-h] [-v] square\n" -"prog.py: error: unrecognized arguments: 1\n" -"$ python prog.py 4 -h\n" -"usage: prog.py [-h] [-v] square\n" -"\n" -"positional arguments:\n" -" square display a square of a given number\n" -"\n" -"options:\n" -" -h, --help show this help message and exit\n" -" -v, --verbosity increase output verbosity\n" -"$ python prog.py 4 -vvv\n" -"16" - -#: ../../howto/argparse.rst:506 -msgid "" -"Yes, it's now more of a flag (similar to ``action=\"store_true\"``) in the " -"previous version of our script. That should explain the complaint." -msgstr "" -"是的，現在它更像是我們上一版腳本中的旗標（類似於 " -"``action=\"store_true\"``），這應該可以解釋抱怨的原因。" - -#: ../../howto/argparse.rst:509 -msgid "It also behaves similar to \"store_true\" action." -msgstr "它的行為也類似 \"store_true\" 操作。" - -#: ../../howto/argparse.rst:511 -msgid "" -"Now here's a demonstration of what the \"count\" action gives. You've " -"probably seen this sort of usage before." -msgstr "現在這裡示範了 \"count\" 動作的作用。你可能以前見過這種用法。" - -#: ../../howto/argparse.rst:514 -msgid "" -"And if you don't specify the ``-v`` flag, that flag is considered to have " -"``None`` value." -msgstr "如果你不指定 ``-v`` 旗標，則該旗標被視為具有 ``None`` 值。" - -#: ../../howto/argparse.rst:517 -msgid "" -"As should be expected, specifying the long form of the flag, we should get " -"the same output." -msgstr "正如預期的那樣，指定長形式旗標，我們應該得到相同的輸出。" - -#: ../../howto/argparse.rst:520 -msgid "" -"Sadly, our help output isn't very informative on the new ability our script " -"has acquired, but that can always be fixed by improving the documentation " -"for our script (e.g. via the ``help`` keyword argument)." -msgstr "" -"遺憾的是，我們的幫助輸出對於我們腳本獲得的新功能並沒有提供太多資訊，但我們都" -"可以透過改進腳本的文件來解決這個問題（例如：透過 ``help`` 關鍵字引數）。" - -#: ../../howto/argparse.rst:524 -msgid "That last output exposes a bug in our program." -msgstr "最後的輸出透露了我們程式中的一個錯誤。" - -#: ../../howto/argparse.rst:527 -msgid "Let's fix::" -msgstr "讓我們來解決問題： ::" - -#: ../../howto/argparse.rst:529 -msgid "" -"import argparse\n" -"parser = argparse.ArgumentParser()\n" -"parser.add_argument(\"square\", type=int,\n" -" help=\"display a square of a given number\")\n" -"parser.add_argument(\"-v\", \"--verbosity\", action=\"count\",\n" -" help=\"increase output verbosity\")\n" -"args = parser.parse_args()\n" -"answer = args.square**2\n" -"\n" -"# bugfix: replace == with >=\n" -"if args.verbosity >= 2:\n" -" print(f\"the square of {args.square} equals {answer}\")\n" -"elif args.verbosity >= 1:\n" -" print(f\"{args.square}^2 == {answer}\")\n" -"else:\n" -" print(answer)" -msgstr "" -"import argparse\n" -"parser = argparse.ArgumentParser()\n" -"parser.add_argument(\"square\", type=int,\n" -" help=\"display a square of a given number\")\n" -"parser.add_argument(\"-v\", \"--verbosity\", action=\"count\",\n" -" help=\"increase output verbosity\")\n" -"args = parser.parse_args()\n" -"answer = args.square**2\n" -"\n" -"# bugfix: replace == with >=\n" -"if args.verbosity >= 2:\n" -" print(f\"the square of {args.square} equals {answer}\")\n" -"elif args.verbosity >= 1:\n" -" print(f\"{args.square}^2 == {answer}\")\n" -"else:\n" -" print(answer)" - -#: ../../howto/argparse.rst:546 -msgid "And this is what it gives:" -msgstr "這就是它給出的：" - -#: ../../howto/argparse.rst:548 -msgid "" -"$ python prog.py 4 -vvv\n" -"the square of 4 equals 16\n" -"$ python prog.py 4 -vvvv\n" -"the square of 4 equals 16\n" -"$ python prog.py 4\n" -"Traceback (most recent call last):\n" -" File \"prog.py\", line 11, in \n" -" if args.verbosity >= 2:\n" -"TypeError: '>=' not supported between instances of 'NoneType' and 'int'" -msgstr "" -"$ python prog.py 4 -vvv\n" -"the square of 4 equals 16\n" -"$ python prog.py 4 -vvvv\n" -"the square of 4 equals 16\n" -"$ python prog.py 4\n" -"Traceback (most recent call last):\n" -" File \"prog.py\", line 11, in \n" -" if args.verbosity >= 2:\n" -"TypeError: '>=' not supported between instances of 'NoneType' and 'int'" - -#: ../../howto/argparse.rst:561 -msgid "" -"First output went well, and fixes the bug we had before. That is, we want " -"any value >= 2 to be as verbose as possible." -msgstr "" -"第一次輸出順利進行，並修復了我們之前遇到的錯誤。也就是說，我們希望任何 >= 2 " -"的值都盡可能詳細。" - -#: ../../howto/argparse.rst:564 -msgid "Third output not so good." -msgstr "第三個輸出不太好。" - -#: ../../howto/argparse.rst:566 -msgid "Let's fix that bug::" -msgstr "我們來修復這個錯誤： ::" - -#: ../../howto/argparse.rst:568 -msgid "" -"import argparse\n" -"parser = argparse.ArgumentParser()\n" -"parser.add_argument(\"square\", type=int,\n" -" help=\"display a square of a given number\")\n" -"parser.add_argument(\"-v\", \"--verbosity\", action=\"count\", default=0,\n" -" help=\"increase output verbosity\")\n" -"args = parser.parse_args()\n" -"answer = args.square**2\n" -"if args.verbosity >= 2:\n" -" print(f\"the square of {args.square} equals {answer}\")\n" -"elif args.verbosity >= 1:\n" -" print(f\"{args.square}^2 == {answer}\")\n" -"else:\n" -" print(answer)" -msgstr "" -"import argparse\n" -"parser = argparse.ArgumentParser()\n" -"parser.add_argument(\"square\", type=int,\n" -" help=\"display a square of a given number\")\n" -"parser.add_argument(\"-v\", \"--verbosity\", action=\"count\", default=0,\n" -" help=\"increase output verbosity\")\n" -"args = parser.parse_args()\n" -"answer = args.square**2\n" -"if args.verbosity >= 2:\n" -" print(f\"the square of {args.square} equals {answer}\")\n" -"elif args.verbosity >= 1:\n" -" print(f\"{args.square}^2 == {answer}\")\n" -"else:\n" -" print(answer)" - -#: ../../howto/argparse.rst:583 -msgid "" -"We've just introduced yet another keyword, ``default``. We've set it to " -"``0`` in order to make it comparable to the other int values. Remember that " -"by default, if an optional argument isn't specified, it gets the ``None`` " -"value, and that cannot be compared to an int value (hence the :exc:" -"`TypeError` exception)." -msgstr "" -"我們剛剛引入了另一個關鍵字 ``default``。我們將其設為 ``0``，以便使其與其他 " -"int 值進行比較。請記住，預設情況下，如果未指定可選引數，它將獲得 ``None`` " -"值，並且不能與 int 值進行比較（因此會出現 :exc:`TypeError` 例外）。" - -#: ../../howto/argparse.rst:590 -msgid "And:" -msgstr "而且：" - -#: ../../howto/argparse.rst:592 -msgid "" -"$ python prog.py 4\n" -"16" -msgstr "" -"$ python prog.py 4\n" -"16" - -#: ../../howto/argparse.rst:597 -msgid "" -"You can go quite far just with what we've learned so far, and we have only " -"scratched the surface. The :mod:`argparse` module is very powerful, and " -"we'll explore a bit more of it before we end this tutorial." -msgstr "" -"僅憑我們迄今為止所學到的知識就可以做到很多事情了，不過其實這樣只有學到一點皮" -"毛而已。:mod:`argparse` 模組非常強大，在結束本教學之前我們會對它進行更多探" -"索。" - -#: ../../howto/argparse.rst:604 -msgid "Getting a little more advanced" -msgstr "更進階一點" - -#: ../../howto/argparse.rst:606 -msgid "" -"What if we wanted to expand our tiny program to perform other powers, not " -"just squares::" -msgstr "如果我們想擴充我們的小程式來執行其他次方的運算，而不僅是平方： ::" - -#: ../../howto/argparse.rst:609 -msgid "" -"import argparse\n" -"parser = argparse.ArgumentParser()\n" -"parser.add_argument(\"x\", type=int, help=\"the base\")\n" -"parser.add_argument(\"y\", type=int, help=\"the exponent\")\n" -"parser.add_argument(\"-v\", \"--verbosity\", action=\"count\", default=0)\n" -"args = parser.parse_args()\n" -"answer = args.x**args.y\n" -"if args.verbosity >= 2:\n" -" print(f\"{args.x} to the power {args.y} equals {answer}\")\n" -"elif args.verbosity >= 1:\n" -" print(f\"{args.x}^{args.y} == {answer}\")\n" -"else:\n" -" print(answer)" -msgstr "" -"import argparse\n" -"parser = argparse.ArgumentParser()\n" -"parser.add_argument(\"x\", type=int, help=\"the base\")\n" -"parser.add_argument(\"y\", type=int, help=\"the exponent\")\n" -"parser.add_argument(\"-v\", \"--verbosity\", action=\"count\", default=0)\n" -"args = parser.parse_args()\n" -"answer = args.x**args.y\n" -"if args.verbosity >= 2:\n" -" print(f\"{args.x} to the power {args.y} equals {answer}\")\n" -"elif args.verbosity >= 1:\n" -" print(f\"{args.x}^{args.y} == {answer}\")\n" -"else:\n" -" print(answer)" - -#: ../../howto/argparse.rst:623 ../../howto/argparse.rst:661 -#: ../../howto/argparse.rst:877 -msgid "Output:" -msgstr "結果：" - -#: ../../howto/argparse.rst:625 -msgid "" -"$ python prog.py\n" -"usage: prog.py [-h] [-v] x y\n" -"prog.py: error: the following arguments are required: x, y\n" -"$ python prog.py -h\n" -"usage: prog.py [-h] [-v] x y\n" -"\n" -"positional arguments:\n" -" x the base\n" -" y the exponent\n" -"\n" -"options:\n" -" -h, --help show this help message and exit\n" -" -v, --verbosity\n" -"$ python prog.py 4 2 -v\n" -"4^2 == 16" -msgstr "" -"$ python prog.py\n" -"usage: prog.py [-h] [-v] x y\n" -"prog.py: error: the following arguments are required: x, y\n" -"$ python prog.py -h\n" -"usage: prog.py [-h] [-v] x y\n" -"\n" -"positional arguments:\n" -" x the base\n" -" y the exponent\n" -"\n" -"options:\n" -" -h, --help show this help message and exit\n" -" -v, --verbosity\n" -"$ python prog.py 4 2 -v\n" -"4^2 == 16" - -#: ../../howto/argparse.rst:644 -msgid "" -"Notice that so far we've been using verbosity level to *change* the text " -"that gets displayed. The following example instead uses verbosity level to " -"display *more* text instead::" -msgstr "" -"請注意，到目前為止，我們一直在使用詳細級別來\\ *更改*\\ 顯示的文字。以下範例" -"使用詳細級別來顯示\\ *更多*\\ 文字： ::" - -#: ../../howto/argparse.rst:648 -msgid "" -"import argparse\n" -"parser = argparse.ArgumentParser()\n" -"parser.add_argument(\"x\", type=int, help=\"the base\")\n" -"parser.add_argument(\"y\", type=int, help=\"the exponent\")\n" -"parser.add_argument(\"-v\", \"--verbosity\", action=\"count\", default=0)\n" -"args = parser.parse_args()\n" -"answer = args.x**args.y\n" -"if args.verbosity >= 2:\n" -" print(f\"Running '{__file__}'\")\n" -"if args.verbosity >= 1:\n" -" print(f\"{args.x}^{args.y} == \", end=\"\")\n" -"print(answer)" -msgstr "" -"import argparse\n" -"parser = argparse.ArgumentParser()\n" -"parser.add_argument(\"x\", type=int, help=\"the base\")\n" -"parser.add_argument(\"y\", type=int, help=\"the exponent\")\n" -"parser.add_argument(\"-v\", \"--verbosity\", action=\"count\", default=0)\n" -"args = parser.parse_args()\n" -"answer = args.x**args.y\n" -"if args.verbosity >= 2:\n" -" print(f\"Running '{__file__}'\")\n" -"if args.verbosity >= 1:\n" -" print(f\"{args.x}^{args.y} == \", end=\"\")\n" -"print(answer)" - -#: ../../howto/argparse.rst:663 -msgid "" -"$ python prog.py 4 2\n" -"16\n" -"$ python prog.py 4 2 -v\n" -"4^2 == 16\n" -"$ python prog.py 4 2 -vv\n" -"Running 'prog.py'\n" -"4^2 == 16" -msgstr "" -"$ python prog.py 4 2\n" -"16\n" -"$ python prog.py 4 2 -v\n" -"4^2 == 16\n" -"$ python prog.py 4 2 -vv\n" -"Running 'prog.py'\n" -"4^2 == 16" - -#: ../../howto/argparse.rst:677 -msgid "Specifying ambiguous arguments" -msgstr "指定不明確的引數" - -#: ../../howto/argparse.rst:679 -msgid "" -"When there is ambiguity in deciding whether an argument is positional or for " -"an argument, ``--`` can be used to tell :meth:`~ArgumentParser.parse_args` " -"that everything after that is a positional argument::" -msgstr "" -"當決定一個引數是位置引數還是引數會有歧義，可以使用 ``--`` 來告訴 :meth:" -"`~ArgumentParser.parse_args` 之後的所有內容都是位置引數： ::" - -#: ../../howto/argparse.rst:683 -msgid "" -">>> parser = argparse.ArgumentParser(prog='PROG')\n" -">>> parser.add_argument('-n', nargs='+')\n" -">>> parser.add_argument('args', nargs='*')\n" -"\n" -">>> # ambiguous, so parse_args assumes it's an option\n" -">>> parser.parse_args(['-f'])\n" -"usage: PROG [-h] [-n N [N ...]] [args ...]\n" -"PROG: error: unrecognized arguments: -f\n" -"\n" -">>> parser.parse_args(['--', '-f'])\n" -"Namespace(args=['-f'], n=None)\n" -"\n" -">>> # ambiguous, so the -n option greedily accepts arguments\n" -">>> parser.parse_args(['-n', '1', '2', '3'])\n" -"Namespace(args=[], n=['1', '2', '3'])\n" -"\n" -">>> parser.parse_args(['-n', '1', '--', '2', '3'])\n" -"Namespace(args=['2', '3'], n=['1'])" -msgstr "" -">>> parser = argparse.ArgumentParser(prog='PROG')\n" -">>> parser.add_argument('-n', nargs='+')\n" -">>> parser.add_argument('args', nargs='*')\n" -"\n" -">>> # ambiguous, so parse_args assumes it's an option\n" -">>> parser.parse_args(['-f'])\n" -"usage: PROG [-h] [-n N [N ...]] [args ...]\n" -"PROG: error: unrecognized arguments: -f\n" -"\n" -">>> parser.parse_args(['--', '-f'])\n" -"Namespace(args=['-f'], n=None)\n" -"\n" -">>> # ambiguous, so the -n option greedily accepts arguments\n" -">>> parser.parse_args(['-n', '1', '2', '3'])\n" -"Namespace(args=[], n=['1', '2', '3'])\n" -"\n" -">>> parser.parse_args(['-n', '1', '--', '2', '3'])\n" -"Namespace(args=['2', '3'], n=['1'])" - -#: ../../howto/argparse.rst:704 -msgid "Conflicting options" -msgstr "相互衝突的選項" - -#: ../../howto/argparse.rst:706 -msgid "" -"So far, we have been working with two methods of an :class:`argparse." -"ArgumentParser` instance. Let's introduce a third one, :meth:" -"`~ArgumentParser.add_mutually_exclusive_group`. It allows for us to specify " -"options that conflict with each other. Let's also change the rest of the " -"program so that the new functionality makes more sense: we'll introduce the " -"``--quiet`` option, which will be the opposite of the ``--verbose`` one::" -msgstr "" -"到目前為止，我們一直在使用 :class:`argparse.ArgumentParser` 實例的兩種方法。" -"讓我們介紹第三個，:meth:`~ArgumentParser.add_mutually_exclusive_group`，它允" -"許我們指定彼此衝突的選項。我們還可以更改程式的其餘部分，以使得新功能更有意" -"義：我們將引入 ``--quiet`` 選項，該選項與 ``--verbose`` 選項相反： ::" - -#: ../../howto/argparse.rst:714 -msgid "" -"import argparse\n" -"\n" -"parser = argparse.ArgumentParser()\n" -"group = parser.add_mutually_exclusive_group()\n" -"group.add_argument(\"-v\", \"--verbose\", action=\"store_true\")\n" -"group.add_argument(\"-q\", \"--quiet\", action=\"store_true\")\n" -"parser.add_argument(\"x\", type=int, help=\"the base\")\n" -"parser.add_argument(\"y\", type=int, help=\"the exponent\")\n" -"args = parser.parse_args()\n" -"answer = args.x**args.y\n" -"\n" -"if args.quiet:\n" -" print(answer)\n" -"elif args.verbose:\n" -" print(f\"{args.x} to the power {args.y} equals {answer}\")\n" -"else:\n" -" print(f\"{args.x}^{args.y} == {answer}\")" -msgstr "" -"import argparse\n" -"\n" -"parser = argparse.ArgumentParser()\n" -"group = parser.add_mutually_exclusive_group()\n" -"group.add_argument(\"-v\", \"--verbose\", action=\"store_true\")\n" -"group.add_argument(\"-q\", \"--quiet\", action=\"store_true\")\n" -"parser.add_argument(\"x\", type=int, help=\"the base\")\n" -"parser.add_argument(\"y\", type=int, help=\"the exponent\")\n" -"args = parser.parse_args()\n" -"answer = args.x**args.y\n" -"\n" -"if args.quiet:\n" -" print(answer)\n" -"elif args.verbose:\n" -" print(f\"{args.x} to the power {args.y} equals {answer}\")\n" -"else:\n" -" print(f\"{args.x}^{args.y} == {answer}\")" - -#: ../../howto/argparse.rst:732 -msgid "" -"Our program is now simpler, and we've lost some functionality for the sake " -"of demonstration. Anyways, here's the output:" -msgstr "" -"我們的程式現在更簡單了，我們因為功能展示失去了一些功能，但無論如何，以下這是" -"輸出：" - -#: ../../howto/argparse.rst:735 -msgid "" -"$ python prog.py 4 2\n" -"4^2 == 16\n" -"$ python prog.py 4 2 -q\n" -"16\n" -"$ python prog.py 4 2 -v\n" -"4 to the power 2 equals 16\n" -"$ python prog.py 4 2 -vq\n" -"usage: prog.py [-h] [-v | -q] x y\n" -"prog.py: error: argument -q/--quiet: not allowed with argument -v/--verbose\n" -"$ python prog.py 4 2 -v --quiet\n" -"usage: prog.py [-h] [-v | -q] x y\n" -"prog.py: error: argument -q/--quiet: not allowed with argument -v/--verbose" -msgstr "" -"$ python prog.py 4 2\n" -"4^2 == 16\n" -"$ python prog.py 4 2 -q\n" -"16\n" -"$ python prog.py 4 2 -v\n" -"4 to the power 2 equals 16\n" -"$ python prog.py 4 2 -vq\n" -"usage: prog.py [-h] [-v | -q] x y\n" -"prog.py: error: argument -q/--quiet: not allowed with argument -v/--verbose\n" -"$ python prog.py 4 2 -v --quiet\n" -"usage: prog.py [-h] [-v | -q] x y\n" -"prog.py: error: argument -q/--quiet: not allowed with argument -v/--verbose" - -#: ../../howto/argparse.rst:750 -msgid "" -"That should be easy to follow. I've added that last output so you can see " -"the sort of flexibility you get, i.e. mixing long form options with short " -"form ones." -msgstr "" -"這應該很容易理解。我新增了最後一個輸出，以便看到所獲得的靈活性，即可以混合長" -"形式與短形式選項。" - -#: ../../howto/argparse.rst:754 -msgid "" -"Before we conclude, you probably want to tell your users the main purpose of " -"your program, just in case they don't know::" -msgstr "" -"在我們結束之前，你可能想告訴使用者你的程式的主要目的，以防他們不知道： ::" - -#: ../../howto/argparse.rst:757 -msgid "" -"import argparse\n" -"\n" -"parser = argparse.ArgumentParser(description=\"calculate X to the power of " -"Y\")\n" -"group = parser.add_mutually_exclusive_group()\n" -"group.add_argument(\"-v\", \"--verbose\", action=\"store_true\")\n" -"group.add_argument(\"-q\", \"--quiet\", action=\"store_true\")\n" -"parser.add_argument(\"x\", type=int, help=\"the base\")\n" -"parser.add_argument(\"y\", type=int, help=\"the exponent\")\n" -"args = parser.parse_args()\n" -"answer = args.x**args.y\n" -"\n" -"if args.quiet:\n" -" print(answer)\n" -"elif args.verbose:\n" -" print(f\"{args.x} to the power {args.y} equals {answer}\")\n" -"else:\n" -" print(f\"{args.x}^{args.y} == {answer}\")" -msgstr "" -"import argparse\n" -"\n" -"parser = argparse.ArgumentParser(description=\"calculate X to the power of " -"Y\")\n" -"group = parser.add_mutually_exclusive_group()\n" -"group.add_argument(\"-v\", \"--verbose\", action=\"store_true\")\n" -"group.add_argument(\"-q\", \"--quiet\", action=\"store_true\")\n" -"parser.add_argument(\"x\", type=int, help=\"the base\")\n" -"parser.add_argument(\"y\", type=int, help=\"the exponent\")\n" -"args = parser.parse_args()\n" -"answer = args.x**args.y\n" -"\n" -"if args.quiet:\n" -" print(answer)\n" -"elif args.verbose:\n" -" print(f\"{args.x} to the power {args.y} equals {answer}\")\n" -"else:\n" -" print(f\"{args.x}^{args.y} == {answer}\")" - -#: ../../howto/argparse.rst:775 -msgid "" -"Note that slight difference in the usage text. Note the ``[-v | -q]``, which " -"tells us that we can either use ``-v`` or ``-q``, but not both at the same " -"time:" -msgstr "" -"請注意用法文字中的細微差別。注意 ``[-v | -q]``，它告訴我們可以使用 ``-v`` 或 " -"``-q``，但不能同時使用：" - -#: ../../howto/argparse.rst:779 ../../howto/argparse.rst:806 -msgid "" -"$ python prog.py --help\n" -"usage: prog.py [-h] [-v | -q] x y\n" -"\n" -"calculate X to the power of Y\n" -"\n" -"positional arguments:\n" -" x the base\n" -" y the exponent\n" -"\n" -"options:\n" -" -h, --help show this help message and exit\n" -" -v, --verbose\n" -" -q, --quiet" -msgstr "" -"$ python prog.py --help\n" -"usage: prog.py [-h] [-v | -q] x y\n" -"\n" -"calculate X to the power of Y\n" -"\n" -"positional arguments:\n" -" x the base\n" -" y the exponent\n" -"\n" -"options:\n" -" -h, --help show this help message and exit\n" -" -v, --verbose\n" -" -q, --quiet" - -#: ../../howto/argparse.rst:797 -msgid "How to translate the argparse output" -msgstr "如何翻譯 argparse 輸出" - -#: ../../howto/argparse.rst:799 -msgid "" -"The output of the :mod:`argparse` module such as its help text and error " -"messages are all made translatable using the :mod:`gettext` module. This " -"allows applications to easily localize messages produced by :mod:`argparse`. " -"See also :ref:`i18n-howto`." -msgstr "" -":mod:`argparse` 模組的輸出，例如幫助文字和錯誤訊息，都可以透過使用 :mod:" -"`gettext` 模組進行翻譯。這允許應用程式能輕鬆在地化 :mod:`argparse` 生成的訊" -"息。另請參閱 :ref:`i18n-howto`。" - -#: ../../howto/argparse.rst:804 -msgid "For instance, in this :mod:`argparse` output:" -msgstr "例如，在此 :mod:`argparse` 輸出中：" - -#: ../../howto/argparse.rst:822 -msgid "" -"The strings ``usage:``, ``positional arguments:``, ``options:`` and ``show " -"this help message and exit`` are all translatable." -msgstr "" -"字串 ``usage:``、``positional arguments:``、``options:`` 和 ``show this help " -"message and exit`` 都是可被翻譯的。" - -#: ../../howto/argparse.rst:825 -msgid "" -"In order to translate these strings, they must first be extracted into a ``." -"po`` file. For example, using `Babel `__, run this " -"command:" -msgstr "" -"為了翻譯這些字串，必須先將它們提取到 ``.po`` 檔案中。例如，使用 `Babel " -"`__ 並執行下列命令：" - -#: ../../howto/argparse.rst:829 -msgid "$ pybabel extract -o messages.po /usr/lib/python3.12/argparse.py" -msgstr "$ pybabel extract -o messages.po /usr/lib/python3.12/argparse.py" - -#: ../../howto/argparse.rst:833 -msgid "" -"This command will extract all translatable strings from the :mod:`argparse` " -"module and output them into a file named ``messages.po``. This command " -"assumes that your Python installation is in ``/usr/lib``." -msgstr "" -"此命令將從 :mod:`argparse` 模組中提取出所有可翻譯的字串，並將它們輸出到名為 " -"``messages.po`` 的檔案中。這個指令假設你的 Python 是安裝在 ``/usr/lib`` 中。" - -#: ../../howto/argparse.rst:837 -msgid "" -"You can find out the location of the :mod:`argparse` module on your system " -"using this script::" -msgstr "你可以使用以下腳本找到 :mod:`argparse` 模組在系統上的位置： ::" - -#: ../../howto/argparse.rst:840 -msgid "" -"import argparse\n" -"print(argparse.__file__)" -msgstr "" -"import argparse\n" -"print(argparse.__file__)" - -#: ../../howto/argparse.rst:843 -msgid "" -"Once the messages in the ``.po`` file are translated and the translations " -"are installed using :mod:`gettext`, :mod:`argparse` will be able to display " -"the translated messages." -msgstr "" -"一旦翻譯了 ``.po`` 檔案中的訊息並使用 :mod:`gettext` 安裝了翻譯，:mod:" -"`argparse` 將能夠顯示翻譯後的訊息。" - -#: ../../howto/argparse.rst:847 -msgid "" -"To translate your own strings in the :mod:`argparse` output, use :mod:" -"`gettext`." -msgstr "若要在 :mod:`argparse` 輸出中翻譯你自己的字串，請使用 :mod:`gettext`。" - -#: ../../howto/argparse.rst:850 -msgid "Custom type converters" -msgstr "自訂型別轉換器" - -#: ../../howto/argparse.rst:852 -msgid "" -"The :mod:`argparse` module allows you to specify custom type converters for " -"your command-line arguments. This allows you to modify user input before " -"it's stored in the :class:`argparse.Namespace`. This can be useful when you " -"need to pre-process the input before it is used in your program." -msgstr "" - -#: ../../howto/argparse.rst:857 -msgid "" -"When using a custom type converter, you can use any callable that takes a " -"single string argument (the argument value) and returns the converted value. " -"However, if you need to handle more complex scenarios, you can use a custom " -"action class with the **action** parameter instead." -msgstr "" - -#: ../../howto/argparse.rst:862 -msgid "" -"For example, let's say you want to handle arguments with different prefixes " -"and process them accordingly::" -msgstr "" - -#: ../../howto/argparse.rst:865 -msgid "" -"import argparse\n" -"\n" -"parser = argparse.ArgumentParser(prefix_chars='-+')\n" -"\n" -"parser.add_argument('-a', metavar='', action='append',\n" -" type=lambda x: ('-', x))\n" -"parser.add_argument('+a', metavar='', action='append',\n" -" type=lambda x: ('+', x))\n" -"\n" -"args = parser.parse_args()\n" -"print(args)" -msgstr "" -"import argparse\n" -"\n" -"parser = argparse.ArgumentParser(prefix_chars='-+')\n" -"\n" -"parser.add_argument('-a', metavar='', action='append',\n" -" type=lambda x: ('-', x))\n" -"parser.add_argument('+a', metavar='', action='append',\n" -" type=lambda x: ('+', x))\n" -"\n" -"args = parser.parse_args()\n" -"print(args)" - -#: ../../howto/argparse.rst:879 -msgid "" -"$ python prog.py -a value1 +a value2\n" -"Namespace(a=[('-', 'value1'), ('+', 'value2')])" -msgstr "" -"$ python prog.py -a value1 +a value2\n" -"Namespace(a=[('-', 'value1'), ('+', 'value2')])" - -#: ../../howto/argparse.rst:884 -msgid "In this example, we:" -msgstr "在這個範例當中，我們：" - -#: ../../howto/argparse.rst:886 -msgid "" -"Created a parser with custom prefix characters using the ``prefix_chars`` " -"parameter." -msgstr "" - -#: ../../howto/argparse.rst:889 -msgid "" -"Defined two arguments, ``-a`` and ``+a``, which used the ``type`` parameter " -"to create custom type converters to store the value in a tuple with the " -"prefix." -msgstr "" - -#: ../../howto/argparse.rst:892 -msgid "" -"Without the custom type converters, the arguments would have treated the ``-" -"a`` and ``+a`` as the same argument, which would have been undesirable. By " -"using custom type converters, we were able to differentiate between the two " -"arguments." -msgstr "" - -#: ../../howto/argparse.rst:897 -msgid "Conclusion" -msgstr "結論" - -#: ../../howto/argparse.rst:899 -msgid "" -"The :mod:`argparse` module offers a lot more than shown here. Its docs are " -"quite detailed and thorough, and full of examples. Having gone through this " -"tutorial, you should easily digest them without feeling overwhelmed." -msgstr "" -":mod:`argparse` 模組提供的功能比此篇內容的要多得多。它的文件非常詳細與透徹並" -"有很多範例。讀完本教學後，你應該可以輕鬆消化它們，而不會感到不知所措。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# jerrychen , 2016 +# Evan Gui , 2016 +# Liang-Bo Wang , 2016 +# Adrian Liaw , 2018 +# Phil Lin , 2022 +# Matt Wang , 2023 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-12-29 11:18+0000\n" +"PO-Revision-Date: 2023-12-11 17:33+0800\n" +"Last-Translator: Matt Wang \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" +"X-Generator: Poedit 3.0.1\n" + +#: ../../howto/argparse.rst:5 +msgid "Argparse Tutorial" +msgstr "Argparse 教學" + +#: ../../howto/argparse.rst:0 +msgid "author" +msgstr "作者" + +#: ../../howto/argparse.rst:7 +msgid "Tshepang Mbambo" +msgstr "Tshepang Mbambo" + +#: ../../howto/argparse.rst:11 +msgid "" +"This tutorial is intended to be a gentle introduction to :mod:`argparse`, " +"the recommended command-line parsing module in the Python standard library." +msgstr "" +"本教學旨在簡要介紹 :mod:`argparse` 這個 Python 標準函式庫中推薦的命令列剖析模" +"組。" + +#: ../../howto/argparse.rst:16 +msgid "" +"The standard library includes two other libraries directly related to " +"command-line parameter processing: the lower level :mod:`optparse` module " +"(which may require more code to configure for a given application, but also " +"allows an application to request behaviors that ``argparse`` doesn't " +"support), and the very low level :mod:`getopt` (which specifically serves as " +"an equivalent to the :c:func:`!getopt` family of functions available to C " +"programmers). While neither of those modules is covered directly in this " +"guide, many of the core concepts in ``argparse`` first originated in " +"``optparse``, so some aspects of this tutorial will also be relevant to " +"``optparse`` users." +msgstr "" +"標準函式庫包含另外兩個與命令列參數處理直接相關的函式庫：較低階的 :mod:" +"`optparse` 模組（可能需要更多程式碼來為給定應用程式設定，但也允許應用程式要" +"求 ``argparse`` 不支援的行為），以及非常低階的 :mod:`getopt`\\ （專門用作 C " +"程式設計師可用的 :c:func:`!getopt` 函式系列的等價）。雖然這個指南並未直接涵蓋" +"這些模組，但 ``argparse`` 的許多核心概念最初來自於 ``optparse``，因此本教學的" +"某些部分也適用於 ``optparse`` 使用者。" + +#: ../../howto/argparse.rst:29 +msgid "Concepts" +msgstr "概念" + +#: ../../howto/argparse.rst:31 +msgid "" +"Let's show the sort of functionality that we are going to explore in this " +"introductory tutorial by making use of the :command:`ls` command:" +msgstr "" +"讓我們透過使用 :command:`ls` 指令來展示我們將在本介紹教學中探索的功能類型：" + +#: ../../howto/argparse.rst:34 +msgid "" +"$ ls\n" +"cpython devguide prog.py pypy rm-unused-function.patch\n" +"$ ls pypy\n" +"ctypes_configure demo dotviewer include lib_pypy lib-python ...\n" +"$ ls -l\n" +"total 20\n" +"drwxr-xr-x 19 wena wena 4096 Feb 18 18:51 cpython\n" +"drwxr-xr-x 4 wena wena 4096 Feb 8 12:04 devguide\n" +"-rwxr-xr-x 1 wena wena 535 Feb 19 00:05 prog.py\n" +"drwxr-xr-x 14 wena wena 4096 Feb 7 00:59 pypy\n" +"-rw-r--r-- 1 wena wena 741 Feb 18 01:01 rm-unused-function.patch\n" +"$ ls --help\n" +"Usage: ls [OPTION]... [FILE]...\n" +"List information about the FILEs (the current directory by default).\n" +"Sort entries alphabetically if none of -cftuvSUX nor --sort is specified.\n" +"..." +msgstr "" +"$ ls\n" +"cpython devguide prog.py pypy rm-unused-function.patch\n" +"$ ls pypy\n" +"ctypes_configure demo dotviewer include lib_pypy lib-python ...\n" +"$ ls -l\n" +"total 20\n" +"drwxr-xr-x 19 wena wena 4096 Feb 18 18:51 cpython\n" +"drwxr-xr-x 4 wena wena 4096 Feb 8 12:04 devguide\n" +"-rwxr-xr-x 1 wena wena 535 Feb 19 00:05 prog.py\n" +"drwxr-xr-x 14 wena wena 4096 Feb 7 00:59 pypy\n" +"-rw-r--r-- 1 wena wena 741 Feb 18 01:01 rm-unused-function.patch\n" +"$ ls --help\n" +"Usage: ls [OPTION]... [FILE]...\n" +"List information about the FILEs (the current directory by default).\n" +"Sort entries alphabetically if none of -cftuvSUX nor --sort is specified.\n" +"..." + +#: ../../howto/argparse.rst:53 +msgid "A few concepts we can learn from the four commands:" +msgstr "我們可以從這四個命令中學到一些概念：" + +#: ../../howto/argparse.rst:55 +msgid "" +"The :command:`ls` command is useful when run without any options at all. It " +"defaults to displaying the contents of the current directory." +msgstr "" +":command:`ls` 命令即便在沒有任何選項的情況下執行仍非常有用。它預設顯示目前目" +"錄的內容。" + +#: ../../howto/argparse.rst:58 +msgid "" +"If we want beyond what it provides by default, we tell it a bit more. In " +"this case, we want it to display a different directory, ``pypy``. What we " +"did is specify what is known as a positional argument. It's named so because " +"the program should know what to do with the value, solely based on where it " +"appears on the command line. This concept is more relevant to a command " +"like :command:`cp`, whose most basic usage is ``cp SRC DEST``. The first " +"position is *what you want copied,* and the second position is *where you " +"want it copied to*." +msgstr "" +"如果我們想要看到比它預設提供更多的內容，我們也需要多告訴它一點。在本例中，我" +"們希望它顯示不同的目錄 ``pypy``，我們做的是指定所謂的位置引數。之所以如此命名" +"是因為程式應該只根據該值在命令列中出現的位置來知道如何處理該值。這個概念與 :" +"command:`cp` 這樣的指令更相關，其最基本的用法是 ``cp SRC DEST``。第一個是\\ *" +"你想要複製的位置*，第二個是\\ *你想要複製過去的位置*。" + +#: ../../howto/argparse.rst:67 +msgid "" +"Now, say we want to change behaviour of the program. In our example, we " +"display more info for each file instead of just showing the file names. The " +"``-l`` in that case is known as an optional argument." +msgstr "" +"現在假設我們想要改變程式的行為。在我們的範例中，我們顯示每個檔案的更多資訊，" +"而不僅是顯示檔案名稱。在這種情況下，``-l`` 被稱為可選引數。" + +#: ../../howto/argparse.rst:71 +msgid "" +"That's a snippet of the help text. It's very useful in that you can come " +"across a program you have never used before, and can figure out how it works " +"simply by reading its help text." +msgstr "" +"這是幫助文字的片段。它非常有用，因為當你遇到以前從未使用過的程式時，只需閱讀" +"其幫助文字即可了解它的工作原理。" + +#: ../../howto/argparse.rst:77 +msgid "The basics" +msgstr "基本用法" + +#: ../../howto/argparse.rst:79 +msgid "Let us start with a very simple example which does (almost) nothing::" +msgstr "讓我們從一個非常簡單的例子開始，它（幾乎）什麼都不做： ::" + +#: ../../howto/argparse.rst:81 +msgid "" +"import argparse\n" +"parser = argparse.ArgumentParser()\n" +"parser.parse_args()" +msgstr "" +"import argparse\n" +"parser = argparse.ArgumentParser()\n" +"parser.parse_args()" + +#: ../../howto/argparse.rst:85 ../../howto/argparse.rst:193 +#: ../../howto/argparse.rst:214 +msgid "Following is a result of running the code:" +msgstr "程式碼執行結果如下：" + +#: ../../howto/argparse.rst:87 +msgid "" +"$ python prog.py\n" +"$ python prog.py --help\n" +"usage: prog.py [-h]\n" +"\n" +"options:\n" +" -h, --help show this help message and exit\n" +"$ python prog.py --verbose\n" +"usage: prog.py [-h]\n" +"prog.py: error: unrecognized arguments: --verbose\n" +"$ python prog.py foo\n" +"usage: prog.py [-h]\n" +"prog.py: error: unrecognized arguments: foo" +msgstr "" +"$ python prog.py\n" +"$ python prog.py --help\n" +"usage: prog.py [-h]\n" +"\n" +"options:\n" +" -h, --help show this help message and exit\n" +"$ python prog.py --verbose\n" +"usage: prog.py [-h]\n" +"prog.py: error: unrecognized arguments: --verbose\n" +"$ python prog.py foo\n" +"usage: prog.py [-h]\n" +"prog.py: error: unrecognized arguments: foo" + +#: ../../howto/argparse.rst:102 ../../howto/argparse.rst:259 +#: ../../howto/argparse.rst:303 +msgid "Here is what is happening:" +msgstr "這是發生的事情：" + +#: ../../howto/argparse.rst:104 +msgid "" +"Running the script without any options results in nothing displayed to " +"stdout. Not so useful." +msgstr "執行不帶任何選項的腳本不會在標準輸出中顯示任何內容。不太有用。" + +#: ../../howto/argparse.rst:107 +msgid "" +"The second one starts to display the usefulness of the :mod:`argparse` " +"module. We have done almost nothing, but already we get a nice help message." +msgstr "" +"第二個開始能夠顯現 :mod:`argparse` 模組的有用之處。我們幾乎什麼也沒做，但我們" +"已經收到了一個很好的幫助訊息。" + +#: ../../howto/argparse.rst:110 +msgid "" +"The ``--help`` option, which can also be shortened to ``-h``, is the only " +"option we get for free (i.e. no need to specify it). Specifying anything " +"else results in an error. But even then, we do get a useful usage message, " +"also for free." +msgstr "" +"``--help`` 選項也可以縮寫為 ``-h``，是我們能隨意獲得的唯一選項（即無需指定" +"它）。指定任何其他內容都會導致錯誤。但即便如此，我們也還是輕鬆地獲得了有用的" +"使用資訊。" + +#: ../../howto/argparse.rst:117 +msgid "Introducing Positional arguments" +msgstr "位置引數的介紹" + +#: ../../howto/argparse.rst:119 +msgid "An example::" +msgstr "例如： ::" + +#: ../../howto/argparse.rst:121 +msgid "" +"import argparse\n" +"parser = argparse.ArgumentParser()\n" +"parser.add_argument(\"echo\")\n" +"args = parser.parse_args()\n" +"print(args.echo)" +msgstr "" +"import argparse\n" +"parser = argparse.ArgumentParser()\n" +"parser.add_argument(\"echo\")\n" +"args = parser.parse_args()\n" +"print(args.echo)" + +#: ../../howto/argparse.rst:127 +msgid "And running the code:" +msgstr "執行這段程式碼：" + +#: ../../howto/argparse.rst:129 +msgid "" +"$ python prog.py\n" +"usage: prog.py [-h] echo\n" +"prog.py: error: the following arguments are required: echo\n" +"$ python prog.py --help\n" +"usage: prog.py [-h] echo\n" +"\n" +"positional arguments:\n" +" echo\n" +"\n" +"options:\n" +" -h, --help show this help message and exit\n" +"$ python prog.py foo\n" +"foo" +msgstr "" +"$ python prog.py\n" +"usage: prog.py [-h] echo\n" +"prog.py: error: the following arguments are required: echo\n" +"$ python prog.py --help\n" +"usage: prog.py [-h] echo\n" +"\n" +"positional arguments:\n" +" echo\n" +"\n" +"options:\n" +" -h, --help show this help message and exit\n" +"$ python prog.py foo\n" +"foo" + +#: ../../howto/argparse.rst:145 +msgid "Here is what's happening:" +msgstr "這是會發生的事情：" + +#: ../../howto/argparse.rst:147 +msgid "" +"We've added the :meth:`~ArgumentParser.add_argument` method, which is what " +"we use to specify which command-line options the program is willing to " +"accept. In this case, I've named it ``echo`` so that it's in line with its " +"function." +msgstr "" +"我們新增了 :meth:`~ArgumentParser.add_argument` 方法，我們用它來指定程式願意" +"接受哪些命令列選項。在本例中，我將其命名為 ``echo``，以便與其功能一致。" + +#: ../../howto/argparse.rst:151 +msgid "Calling our program now requires us to specify an option." +msgstr "現在呼叫我們的程式時需要指定一個選項。" + +#: ../../howto/argparse.rst:153 +msgid "" +"The :meth:`~ArgumentParser.parse_args` method actually returns some data " +"from the options specified, in this case, ``echo``." +msgstr "" +":meth:`~ArgumentParser.parse_args` 方法實際上從指定的選項中回傳一些資料，在本" +"例中為 ``echo``。" + +#: ../../howto/argparse.rst:156 +msgid "" +"The variable is some form of 'magic' that :mod:`argparse` performs for free " +"(i.e. no need to specify which variable that value is stored in). You will " +"also notice that its name matches the string argument given to the method, " +"``echo``." +msgstr "" +"該變數是某種形式的「魔法」，:mod:`argparse` 可以自由執行（即無需指定該值儲存" +"在哪個變數中）。你還會注意到，它的名稱與提供給方法 ``echo`` 的字串引數相符。" + +#: ../../howto/argparse.rst:161 +msgid "" +"Note however that, although the help display looks nice and all, it " +"currently is not as helpful as it can be. For example we see that we got " +"``echo`` as a positional argument, but we don't know what it does, other " +"than by guessing or by reading the source code. So, let's make it a bit more " +"useful::" +msgstr "" +"但請注意，儘管幫助顯示看起來不錯，但它目前還沒有發揮出應有的用處。例如，我們" +"看到 ``echo`` 作為位置引數，但除了猜測或閱讀原始程式碼之外，我們不知道它的作" +"用。那麼，我們來讓它變得更有用一點： ::" + +#: ../../howto/argparse.rst:166 +msgid "" +"import argparse\n" +"parser = argparse.ArgumentParser()\n" +"parser.add_argument(\"echo\", help=\"echo the string you use here\")\n" +"args = parser.parse_args()\n" +"print(args.echo)" +msgstr "" +"import argparse\n" +"parser = argparse.ArgumentParser()\n" +"parser.add_argument(\"echo\", help=\"echo the string you use here\")\n" +"args = parser.parse_args()\n" +"print(args.echo)" + +#: ../../howto/argparse.rst:172 +msgid "And we get:" +msgstr "然後我們得到：" + +#: ../../howto/argparse.rst:174 +msgid "" +"$ python prog.py -h\n" +"usage: prog.py [-h] echo\n" +"\n" +"positional arguments:\n" +" echo echo the string you use here\n" +"\n" +"options:\n" +" -h, --help show this help message and exit" +msgstr "" +"$ python prog.py -h\n" +"usage: prog.py [-h] echo\n" +"\n" +"positional arguments:\n" +" echo echo the string you use here\n" +"\n" +"options:\n" +" -h, --help show this help message and exit" + +#: ../../howto/argparse.rst:185 +msgid "Now, how about doing something even more useful::" +msgstr "現在來做一些更有用處的事情： ::" + +#: ../../howto/argparse.rst:187 +msgid "" +"import argparse\n" +"parser = argparse.ArgumentParser()\n" +"parser.add_argument(\"square\", help=\"display a square of a given " +"number\")\n" +"args = parser.parse_args()\n" +"print(args.square**2)" +msgstr "" +"import argparse\n" +"parser = argparse.ArgumentParser()\n" +"parser.add_argument(\"square\", help=\"display a square of a given " +"number\")\n" +"args = parser.parse_args()\n" +"print(args.square**2)" + +#: ../../howto/argparse.rst:195 +msgid "" +"$ python prog.py 4\n" +"Traceback (most recent call last):\n" +" File \"prog.py\", line 5, in \n" +" print(args.square**2)\n" +"TypeError: unsupported operand type(s) for ** or pow(): 'str' and 'int'" +msgstr "" +"$ python prog.py 4\n" +"Traceback (most recent call last):\n" +" File \"prog.py\", line 5, in \n" +" print(args.square**2)\n" +"TypeError: unsupported operand type(s) for ** or pow(): 'str' and 'int'" + +#: ../../howto/argparse.rst:203 +msgid "" +"That didn't go so well. That's because :mod:`argparse` treats the options we " +"give it as strings, unless we tell it otherwise. So, let's tell :mod:" +"`argparse` to treat that input as an integer::" +msgstr "" +"進展不太順利。這是因為，除非我們另有說明，:mod:`argparse` 會將我們給它的選項" +"視為字串。因此，讓我們告訴 :mod:`argparse` 將該輸入視為整數： ::" + +#: ../../howto/argparse.rst:207 +msgid "" +"import argparse\n" +"parser = argparse.ArgumentParser()\n" +"parser.add_argument(\"square\", help=\"display a square of a given " +"number\",\n" +" type=int)\n" +"args = parser.parse_args()\n" +"print(args.square**2)" +msgstr "" +"import argparse\n" +"parser = argparse.ArgumentParser()\n" +"parser.add_argument(\"square\", help=\"display a square of a given " +"number\",\n" +" type=int)\n" +"args = parser.parse_args()\n" +"print(args.square**2)" + +#: ../../howto/argparse.rst:216 +msgid "" +"$ python prog.py 4\n" +"16\n" +"$ python prog.py four\n" +"usage: prog.py [-h] square\n" +"prog.py: error: argument square: invalid int value: 'four'" +msgstr "" +"$ python prog.py 4\n" +"16\n" +"$ python prog.py four\n" +"usage: prog.py [-h] square\n" +"prog.py: error: argument square: invalid int value: 'four'" + +#: ../../howto/argparse.rst:224 +msgid "" +"That went well. The program now even helpfully quits on bad illegal input " +"before proceeding." +msgstr "順利進展。現在該程式甚至可以在繼續操作之前因錯誤的非法輸入而退出。" + +#: ../../howto/argparse.rst:229 +msgid "Introducing Optional arguments" +msgstr "可選引數的介紹" + +#: ../../howto/argparse.rst:231 +msgid "" +"So far we have been playing with positional arguments. Let us have a look on " +"how to add optional ones::" +msgstr "到目前為止，我們一直在討論位置引數。我們來看看如何新增可選引數： ::" + +#: ../../howto/argparse.rst:234 +msgid "" +"import argparse\n" +"parser = argparse.ArgumentParser()\n" +"parser.add_argument(\"--verbosity\", help=\"increase output verbosity\")\n" +"args = parser.parse_args()\n" +"if args.verbosity:\n" +" print(\"verbosity turned on\")" +msgstr "" +"import argparse\n" +"parser = argparse.ArgumentParser()\n" +"parser.add_argument(\"--verbosity\", help=\"increase output verbosity\")\n" +"args = parser.parse_args()\n" +"if args.verbosity:\n" +" print(\"verbosity turned on\")" + +#: ../../howto/argparse.rst:241 ../../howto/argparse.rst:287 +#: ../../howto/argparse.rst:403 ../../howto/argparse.rst:437 +msgid "And the output:" +msgstr "接者是結果：" + +#: ../../howto/argparse.rst:243 +msgid "" +"$ python prog.py --verbosity 1\n" +"verbosity turned on\n" +"$ python prog.py\n" +"$ python prog.py --help\n" +"usage: prog.py [-h] [--verbosity VERBOSITY]\n" +"\n" +"options:\n" +" -h, --help show this help message and exit\n" +" --verbosity VERBOSITY\n" +" increase output verbosity\n" +"$ python prog.py --verbosity\n" +"usage: prog.py [-h] [--verbosity VERBOSITY]\n" +"prog.py: error: argument --verbosity: expected one argument" +msgstr "" +"$ python prog.py --verbosity 1\n" +"verbosity turned on\n" +"$ python prog.py\n" +"$ python prog.py --help\n" +"usage: prog.py [-h] [--verbosity VERBOSITY]\n" +"\n" +"options:\n" +" -h, --help show this help message and exit\n" +" --verbosity VERBOSITY\n" +" increase output verbosity\n" +"$ python prog.py --verbosity\n" +"usage: prog.py [-h] [--verbosity VERBOSITY]\n" +"prog.py: error: argument --verbosity: expected one argument" + +#: ../../howto/argparse.rst:261 +msgid "" +"The program is written so as to display something when ``--verbosity`` is " +"specified and display nothing when not." +msgstr "" +"程式被編寫為在指定 ``--verbosity`` 時顯示一些內容，並在未指定時不顯示任何內" +"容。" + +#: ../../howto/argparse.rst:264 +msgid "" +"To show that the option is actually optional, there is no error when running " +"the program without it. Note that by default, if an optional argument isn't " +"used, the relevant variable, in this case ``args.verbosity``, is given " +"``None`` as a value, which is the reason it fails the truth test of the :" +"keyword:`if` statement." +msgstr "" +"為了表示該選項實際上是可選的，沒使用它來執行程式並不會出現錯誤。請注意，預設" +"情況下，如果未使用可選引數，則相關變數（在本例中為 ``args.verbosity``）將被賦" +"予 ``None`` 作為值，這就是它未能通過 :keyword:`if` 陳述式真值測試的原因。" + +#: ../../howto/argparse.rst:270 +msgid "The help message is a bit different." +msgstr "幫助訊息有點不同。" + +#: ../../howto/argparse.rst:272 +msgid "" +"When using the ``--verbosity`` option, one must also specify some value, any " +"value." +msgstr "當使用 ``--verbosity`` 選項時必須要指定一些值，任何值都可以。" + +#: ../../howto/argparse.rst:275 +msgid "" +"The above example accepts arbitrary integer values for ``--verbosity``, but " +"for our simple program, only two values are actually useful, ``True`` or " +"``False``. Let's modify the code accordingly::" +msgstr "" +"在上面的例子中，``--verbosity`` 接受任意的整數，但對我們的程式來說只接受兩個" +"輸入值， ``True`` 或 ``False``。所以我們來修改一下程式碼使其符合： ::" + +#: ../../howto/argparse.rst:279 +msgid "" +"import argparse\n" +"parser = argparse.ArgumentParser()\n" +"parser.add_argument(\"--verbose\", help=\"increase output verbosity\",\n" +" action=\"store_true\")\n" +"args = parser.parse_args()\n" +"if args.verbose:\n" +" print(\"verbosity turned on\")" +msgstr "" +"import argparse\n" +"parser = argparse.ArgumentParser()\n" +"parser.add_argument(\"--verbose\", help=\"increase output verbosity\",\n" +" action=\"store_true\")\n" +"args = parser.parse_args()\n" +"if args.verbose:\n" +" print(\"verbosity turned on\")" + +#: ../../howto/argparse.rst:289 +msgid "" +"$ python prog.py --verbose\n" +"verbosity turned on\n" +"$ python prog.py --verbose 1\n" +"usage: prog.py [-h] [--verbose]\n" +"prog.py: error: unrecognized arguments: 1\n" +"$ python prog.py --help\n" +"usage: prog.py [-h] [--verbose]\n" +"\n" +"options:\n" +" -h, --help show this help message and exit\n" +" --verbose increase output verbosity" +msgstr "" +"$ python prog.py --verbose\n" +"verbosity turned on\n" +"$ python prog.py --verbose 1\n" +"usage: prog.py [-h] [--verbose]\n" +"prog.py: error: unrecognized arguments: 1\n" +"$ python prog.py --help\n" +"usage: prog.py [-h] [--verbose]\n" +"\n" +"options:\n" +" -h, --help show this help message and exit\n" +" --verbose increase output verbosity" + +#: ../../howto/argparse.rst:305 +msgid "" +"The option is now more of a flag than something that requires a value. We " +"even changed the name of the option to match that idea. Note that we now " +"specify a new keyword, ``action``, and give it the value ``\"store_true\"``. " +"This means that, if the option is specified, assign the value ``True`` to " +"``args.verbose``. Not specifying it implies ``False``." +msgstr "" +"這個選項現在更像是一個旗標，而不是需要值的東西。我們甚至更改了選項的名稱以符" +"合這個想法。請注意，我們現在指定一個新的關鍵字 ``action``，並為其指定值 " +"``\"store_true\"``。這意味著，如果指定了該選項，則將值 ``True`` 指派給 " +"``args.verbose``。不指定它代表為 ``False``。" + +#: ../../howto/argparse.rst:312 +msgid "" +"It complains when you specify a value, in true spirit of what flags actually " +"are." +msgstr "當你指定一個值時，它會本著旗標的實際精神來抱怨。" + +#: ../../howto/argparse.rst:315 +msgid "Notice the different help text." +msgstr "請注意不同的幫助文字。" + +#: ../../howto/argparse.rst:319 +msgid "Short options" +msgstr "短選項" + +#: ../../howto/argparse.rst:321 +msgid "" +"If you are familiar with command line usage, you will notice that I haven't " +"yet touched on the topic of short versions of the options. It's quite " +"simple::" +msgstr "" +"如果你熟悉命令列用法，你會注意到我尚未提及選項的簡短版本。這很簡單： ::" + +#: ../../howto/argparse.rst:325 +msgid "" +"import argparse\n" +"parser = argparse.ArgumentParser()\n" +"parser.add_argument(\"-v\", \"--verbose\", help=\"increase output " +"verbosity\",\n" +" action=\"store_true\")\n" +"args = parser.parse_args()\n" +"if args.verbose:\n" +" print(\"verbosity turned on\")" +msgstr "" +"import argparse\n" +"parser = argparse.ArgumentParser()\n" +"parser.add_argument(\"-v\", \"--verbose\", help=\"increase output " +"verbosity\",\n" +" action=\"store_true\")\n" +"args = parser.parse_args()\n" +"if args.verbose:\n" +" print(\"verbosity turned on\")" + +#: ../../howto/argparse.rst:333 +msgid "And here goes:" +msgstr "而這為：" + +#: ../../howto/argparse.rst:335 +msgid "" +"$ python prog.py -v\n" +"verbosity turned on\n" +"$ python prog.py --help\n" +"usage: prog.py [-h] [-v]\n" +"\n" +"options:\n" +" -h, --help show this help message and exit\n" +" -v, --verbose increase output verbosity" +msgstr "" +"$ python prog.py -v\n" +"verbosity turned on\n" +"$ python prog.py --help\n" +"usage: prog.py [-h] [-v]\n" +"\n" +"options:\n" +" -h, --help show this help message and exit\n" +" -v, --verbose increase output verbosity" + +#: ../../howto/argparse.rst:346 +msgid "Note that the new ability is also reflected in the help text." +msgstr "請注意，新功能也反映在幫助文字中。" + +#: ../../howto/argparse.rst:350 +msgid "Combining Positional and Optional arguments" +msgstr "組合位置引數和可選引數" + +#: ../../howto/argparse.rst:352 +msgid "Our program keeps growing in complexity::" +msgstr "我們的程式的複雜性不斷增加： ::" + +#: ../../howto/argparse.rst:354 +msgid "" +"import argparse\n" +"parser = argparse.ArgumentParser()\n" +"parser.add_argument(\"square\", type=int,\n" +" help=\"display a square of a given number\")\n" +"parser.add_argument(\"-v\", \"--verbose\", action=\"store_true\",\n" +" help=\"increase output verbosity\")\n" +"args = parser.parse_args()\n" +"answer = args.square**2\n" +"if args.verbose:\n" +" print(f\"the square of {args.square} equals {answer}\")\n" +"else:\n" +" print(answer)" +msgstr "" +"import argparse\n" +"parser = argparse.ArgumentParser()\n" +"parser.add_argument(\"square\", type=int,\n" +" help=\"display a square of a given number\")\n" +"parser.add_argument(\"-v\", \"--verbose\", action=\"store_true\",\n" +" help=\"increase output verbosity\")\n" +"args = parser.parse_args()\n" +"answer = args.square**2\n" +"if args.verbose:\n" +" print(f\"the square of {args.square} equals {answer}\")\n" +"else:\n" +" print(answer)" + +#: ../../howto/argparse.rst:367 +msgid "And now the output:" +msgstr "然後現在的輸出結果：" + +#: ../../howto/argparse.rst:369 +msgid "" +"$ python prog.py\n" +"usage: prog.py [-h] [-v] square\n" +"prog.py: error: the following arguments are required: square\n" +"$ python prog.py 4\n" +"16\n" +"$ python prog.py 4 --verbose\n" +"the square of 4 equals 16\n" +"$ python prog.py --verbose 4\n" +"the square of 4 equals 16" +msgstr "" +"$ python prog.py\n" +"usage: prog.py [-h] [-v] square\n" +"prog.py: error: the following arguments are required: square\n" +"$ python prog.py 4\n" +"16\n" +"$ python prog.py 4 --verbose\n" +"the square of 4 equals 16\n" +"$ python prog.py --verbose 4\n" +"the square of 4 equals 16" + +#: ../../howto/argparse.rst:381 +msgid "We've brought back a positional argument, hence the complaint." +msgstr "我們帶回了位置引數，因而被抱怨。" + +#: ../../howto/argparse.rst:383 +msgid "Note that the order does not matter." +msgstr "請注意，順序並不重要。" + +#: ../../howto/argparse.rst:385 +msgid "" +"How about we give this program of ours back the ability to have multiple " +"verbosity values, and actually get to use them::" +msgstr "" +"我們讓這個程式擁有多個訊息詳細級別 (verbosity) 之值的能力，並實際使用它" +"們： ::" + +#: ../../howto/argparse.rst:388 +msgid "" +"import argparse\n" +"parser = argparse.ArgumentParser()\n" +"parser.add_argument(\"square\", type=int,\n" +" help=\"display a square of a given number\")\n" +"parser.add_argument(\"-v\", \"--verbosity\", type=int,\n" +" help=\"increase output verbosity\")\n" +"args = parser.parse_args()\n" +"answer = args.square**2\n" +"if args.verbosity == 2:\n" +" print(f\"the square of {args.square} equals {answer}\")\n" +"elif args.verbosity == 1:\n" +" print(f\"{args.square}^2 == {answer}\")\n" +"else:\n" +" print(answer)" +msgstr "" +"import argparse\n" +"parser = argparse.ArgumentParser()\n" +"parser.add_argument(\"square\", type=int,\n" +" help=\"display a square of a given number\")\n" +"parser.add_argument(\"-v\", \"--verbosity\", type=int,\n" +" help=\"increase output verbosity\")\n" +"args = parser.parse_args()\n" +"answer = args.square**2\n" +"if args.verbosity == 2:\n" +" print(f\"the square of {args.square} equals {answer}\")\n" +"elif args.verbosity == 1:\n" +" print(f\"{args.square}^2 == {answer}\")\n" +"else:\n" +" print(answer)" + +#: ../../howto/argparse.rst:405 +msgid "" +"$ python prog.py 4\n" +"16\n" +"$ python prog.py 4 -v\n" +"usage: prog.py [-h] [-v VERBOSITY] square\n" +"prog.py: error: argument -v/--verbosity: expected one argument\n" +"$ python prog.py 4 -v 1\n" +"4^2 == 16\n" +"$ python prog.py 4 -v 2\n" +"the square of 4 equals 16\n" +"$ python prog.py 4 -v 3\n" +"16" +msgstr "" +"$ python prog.py 4\n" +"16\n" +"$ python prog.py 4 -v\n" +"usage: prog.py [-h] [-v VERBOSITY] square\n" +"prog.py: error: argument -v/--verbosity: expected one argument\n" +"$ python prog.py 4 -v 1\n" +"4^2 == 16\n" +"$ python prog.py 4 -v 2\n" +"the square of 4 equals 16\n" +"$ python prog.py 4 -v 3\n" +"16" + +#: ../../howto/argparse.rst:419 +msgid "" +"These all look good except the last one, which exposes a bug in our program. " +"Let's fix it by restricting the values the ``--verbosity`` option can " +"accept::" +msgstr "" +"除了最後一個外都看起來正常，它透露了我們程式中的一個錯誤。我們可透過限制 ``--" +"verbosity`` 選項可以接受的值來修復它： ::" + +#: ../../howto/argparse.rst:422 +msgid "" +"import argparse\n" +"parser = argparse.ArgumentParser()\n" +"parser.add_argument(\"square\", type=int,\n" +" help=\"display a square of a given number\")\n" +"parser.add_argument(\"-v\", \"--verbosity\", type=int, choices=[0, 1, 2],\n" +" help=\"increase output verbosity\")\n" +"args = parser.parse_args()\n" +"answer = args.square**2\n" +"if args.verbosity == 2:\n" +" print(f\"the square of {args.square} equals {answer}\")\n" +"elif args.verbosity == 1:\n" +" print(f\"{args.square}^2 == {answer}\")\n" +"else:\n" +" print(answer)" +msgstr "" +"import argparse\n" +"parser = argparse.ArgumentParser()\n" +"parser.add_argument(\"square\", type=int,\n" +" help=\"display a square of a given number\")\n" +"parser.add_argument(\"-v\", \"--verbosity\", type=int, choices=[0, 1, 2],\n" +" help=\"increase output verbosity\")\n" +"args = parser.parse_args()\n" +"answer = args.square**2\n" +"if args.verbosity == 2:\n" +" print(f\"the square of {args.square} equals {answer}\")\n" +"elif args.verbosity == 1:\n" +" print(f\"{args.square}^2 == {answer}\")\n" +"else:\n" +" print(answer)" + +#: ../../howto/argparse.rst:439 +msgid "" +"$ python prog.py 4 -v 3\n" +"usage: prog.py [-h] [-v {0,1,2}] square\n" +"prog.py: error: argument -v/--verbosity: invalid choice: 3 (choose from 0, " +"1, 2)\n" +"$ python prog.py 4 -h\n" +"usage: prog.py [-h] [-v {0,1,2}] square\n" +"\n" +"positional arguments:\n" +" square display a square of a given number\n" +"\n" +"options:\n" +" -h, --help show this help message and exit\n" +" -v, --verbosity {0,1,2}\n" +" increase output verbosity" +msgstr "" +"$ python prog.py 4 -v 3\n" +"usage: prog.py [-h] [-v {0,1,2}] square\n" +"prog.py: error: argument -v/--verbosity: invalid choice: 3 (choose from 0, " +"1, 2)\n" +"$ python prog.py 4 -h\n" +"usage: prog.py [-h] [-v {0,1,2}] square\n" +"\n" +"positional arguments:\n" +" square display a square of a given number\n" +"\n" +"options:\n" +" -h, --help show this help message and exit\n" +" -v, --verbosity {0,1,2}\n" +" increase output verbosity" + +#: ../../howto/argparse.rst:455 +msgid "" +"Note that the change also reflects both in the error message as well as the " +"help string." +msgstr "請注意，更改也會反映在錯誤訊息和幫助字串中。" + +#: ../../howto/argparse.rst:458 +msgid "" +"Now, let's use a different approach of playing with verbosity, which is " +"pretty common. It also matches the way the CPython executable handles its " +"own verbosity argument (check the output of ``python --help``)::" +msgstr "" +"現在，讓我們使用另一種常見方法來玩玩訊息詳細級別。它也與 CPython 執行檔處理其" +"自身訊息詳細級別引數的方式相符（請見 ``python --help`` 的輸出）： ::" + +#: ../../howto/argparse.rst:462 +msgid "" +"import argparse\n" +"parser = argparse.ArgumentParser()\n" +"parser.add_argument(\"square\", type=int,\n" +" help=\"display the square of a given number\")\n" +"parser.add_argument(\"-v\", \"--verbosity\", action=\"count\",\n" +" help=\"increase output verbosity\")\n" +"args = parser.parse_args()\n" +"answer = args.square**2\n" +"if args.verbosity == 2:\n" +" print(f\"the square of {args.square} equals {answer}\")\n" +"elif args.verbosity == 1:\n" +" print(f\"{args.square}^2 == {answer}\")\n" +"else:\n" +" print(answer)" +msgstr "" +"import argparse\n" +"parser = argparse.ArgumentParser()\n" +"parser.add_argument(\"square\", type=int,\n" +" help=\"display the square of a given number\")\n" +"parser.add_argument(\"-v\", \"--verbosity\", action=\"count\",\n" +" help=\"increase output verbosity\")\n" +"args = parser.parse_args()\n" +"answer = args.square**2\n" +"if args.verbosity == 2:\n" +" print(f\"the square of {args.square} equals {answer}\")\n" +"elif args.verbosity == 1:\n" +" print(f\"{args.square}^2 == {answer}\")\n" +"else:\n" +" print(answer)" + +#: ../../howto/argparse.rst:477 +msgid "" +"We have introduced another action, \"count\", to count the number of " +"occurrences of specific options." +msgstr "我們已經介紹過另一個操作 \"count\" 用來計算指定的選項出現的次數。" + +#: ../../howto/argparse.rst:481 +msgid "" +"$ python prog.py 4\n" +"16\n" +"$ python prog.py 4 -v\n" +"4^2 == 16\n" +"$ python prog.py 4 -vv\n" +"the square of 4 equals 16\n" +"$ python prog.py 4 --verbosity --verbosity\n" +"the square of 4 equals 16\n" +"$ python prog.py 4 -v 1\n" +"usage: prog.py [-h] [-v] square\n" +"prog.py: error: unrecognized arguments: 1\n" +"$ python prog.py 4 -h\n" +"usage: prog.py [-h] [-v] square\n" +"\n" +"positional arguments:\n" +" square display a square of a given number\n" +"\n" +"options:\n" +" -h, --help show this help message and exit\n" +" -v, --verbosity increase output verbosity\n" +"$ python prog.py 4 -vvv\n" +"16" +msgstr "" +"$ python prog.py 4\n" +"16\n" +"$ python prog.py 4 -v\n" +"4^2 == 16\n" +"$ python prog.py 4 -vv\n" +"the square of 4 equals 16\n" +"$ python prog.py 4 --verbosity --verbosity\n" +"the square of 4 equals 16\n" +"$ python prog.py 4 -v 1\n" +"usage: prog.py [-h] [-v] square\n" +"prog.py: error: unrecognized arguments: 1\n" +"$ python prog.py 4 -h\n" +"usage: prog.py [-h] [-v] square\n" +"\n" +"positional arguments:\n" +" square display a square of a given number\n" +"\n" +"options:\n" +" -h, --help show this help message and exit\n" +" -v, --verbosity increase output verbosity\n" +"$ python prog.py 4 -vvv\n" +"16" + +#: ../../howto/argparse.rst:506 +msgid "" +"Yes, it's now more of a flag (similar to ``action=\"store_true\"``) in the " +"previous version of our script. That should explain the complaint." +msgstr "" +"是的，現在它更像是我們上一版腳本中的旗標（類似於 " +"``action=\"store_true\"``），這應該可以解釋抱怨的原因。" + +#: ../../howto/argparse.rst:509 +msgid "It also behaves similar to \"store_true\" action." +msgstr "它的行為也類似 \"store_true\" 操作。" + +#: ../../howto/argparse.rst:511 +msgid "" +"Now here's a demonstration of what the \"count\" action gives. You've " +"probably seen this sort of usage before." +msgstr "現在這裡示範了 \"count\" 動作的作用。你可能以前見過這種用法。" + +#: ../../howto/argparse.rst:514 +msgid "" +"And if you don't specify the ``-v`` flag, that flag is considered to have " +"``None`` value." +msgstr "如果你不指定 ``-v`` 旗標，則該旗標被視為具有 ``None`` 值。" + +#: ../../howto/argparse.rst:517 +msgid "" +"As should be expected, specifying the long form of the flag, we should get " +"the same output." +msgstr "正如預期的那樣，指定長形式旗標，我們應該得到相同的輸出。" + +#: ../../howto/argparse.rst:520 +msgid "" +"Sadly, our help output isn't very informative on the new ability our script " +"has acquired, but that can always be fixed by improving the documentation " +"for our script (e.g. via the ``help`` keyword argument)." +msgstr "" +"遺憾的是，我們的幫助輸出對於我們腳本獲得的新功能並沒有提供太多資訊，但我們都" +"可以透過改進腳本的文件來解決這個問題（例如：透過 ``help`` 關鍵字引數）。" + +#: ../../howto/argparse.rst:524 +msgid "That last output exposes a bug in our program." +msgstr "最後的輸出透露了我們程式中的一個錯誤。" + +#: ../../howto/argparse.rst:527 +msgid "Let's fix::" +msgstr "讓我們來解決問題： ::" + +#: ../../howto/argparse.rst:529 +msgid "" +"import argparse\n" +"parser = argparse.ArgumentParser()\n" +"parser.add_argument(\"square\", type=int,\n" +" help=\"display a square of a given number\")\n" +"parser.add_argument(\"-v\", \"--verbosity\", action=\"count\",\n" +" help=\"increase output verbosity\")\n" +"args = parser.parse_args()\n" +"answer = args.square**2\n" +"\n" +"# bugfix: replace == with >=\n" +"if args.verbosity >= 2:\n" +" print(f\"the square of {args.square} equals {answer}\")\n" +"elif args.verbosity >= 1:\n" +" print(f\"{args.square}^2 == {answer}\")\n" +"else:\n" +" print(answer)" +msgstr "" +"import argparse\n" +"parser = argparse.ArgumentParser()\n" +"parser.add_argument(\"square\", type=int,\n" +" help=\"display a square of a given number\")\n" +"parser.add_argument(\"-v\", \"--verbosity\", action=\"count\",\n" +" help=\"increase output verbosity\")\n" +"args = parser.parse_args()\n" +"answer = args.square**2\n" +"\n" +"# bugfix: replace == with >=\n" +"if args.verbosity >= 2:\n" +" print(f\"the square of {args.square} equals {answer}\")\n" +"elif args.verbosity >= 1:\n" +" print(f\"{args.square}^2 == {answer}\")\n" +"else:\n" +" print(answer)" + +#: ../../howto/argparse.rst:546 +msgid "And this is what it gives:" +msgstr "這就是它給出的：" + +#: ../../howto/argparse.rst:548 +msgid "" +"$ python prog.py 4 -vvv\n" +"the square of 4 equals 16\n" +"$ python prog.py 4 -vvvv\n" +"the square of 4 equals 16\n" +"$ python prog.py 4\n" +"Traceback (most recent call last):\n" +" File \"prog.py\", line 11, in \n" +" if args.verbosity >= 2:\n" +"TypeError: '>=' not supported between instances of 'NoneType' and 'int'" +msgstr "" +"$ python prog.py 4 -vvv\n" +"the square of 4 equals 16\n" +"$ python prog.py 4 -vvvv\n" +"the square of 4 equals 16\n" +"$ python prog.py 4\n" +"Traceback (most recent call last):\n" +" File \"prog.py\", line 11, in \n" +" if args.verbosity >= 2:\n" +"TypeError: '>=' not supported between instances of 'NoneType' and 'int'" + +#: ../../howto/argparse.rst:561 +msgid "" +"First output went well, and fixes the bug we had before. That is, we want " +"any value >= 2 to be as verbose as possible." +msgstr "" +"第一次輸出順利進行，並修復了我們之前遇到的錯誤。也就是說，我們希望任何 >= 2 " +"的值都盡可能詳細。" + +#: ../../howto/argparse.rst:564 +msgid "Third output not so good." +msgstr "第三個輸出不太好。" + +#: ../../howto/argparse.rst:566 +msgid "Let's fix that bug::" +msgstr "我們來修復這個錯誤： ::" + +#: ../../howto/argparse.rst:568 +msgid "" +"import argparse\n" +"parser = argparse.ArgumentParser()\n" +"parser.add_argument(\"square\", type=int,\n" +" help=\"display a square of a given number\")\n" +"parser.add_argument(\"-v\", \"--verbosity\", action=\"count\", default=0,\n" +" help=\"increase output verbosity\")\n" +"args = parser.parse_args()\n" +"answer = args.square**2\n" +"if args.verbosity >= 2:\n" +" print(f\"the square of {args.square} equals {answer}\")\n" +"elif args.verbosity >= 1:\n" +" print(f\"{args.square}^2 == {answer}\")\n" +"else:\n" +" print(answer)" +msgstr "" +"import argparse\n" +"parser = argparse.ArgumentParser()\n" +"parser.add_argument(\"square\", type=int,\n" +" help=\"display a square of a given number\")\n" +"parser.add_argument(\"-v\", \"--verbosity\", action=\"count\", default=0,\n" +" help=\"increase output verbosity\")\n" +"args = parser.parse_args()\n" +"answer = args.square**2\n" +"if args.verbosity >= 2:\n" +" print(f\"the square of {args.square} equals {answer}\")\n" +"elif args.verbosity >= 1:\n" +" print(f\"{args.square}^2 == {answer}\")\n" +"else:\n" +" print(answer)" + +#: ../../howto/argparse.rst:583 +msgid "" +"We've just introduced yet another keyword, ``default``. We've set it to " +"``0`` in order to make it comparable to the other int values. Remember that " +"by default, if an optional argument isn't specified, it gets the ``None`` " +"value, and that cannot be compared to an int value (hence the :exc:" +"`TypeError` exception)." +msgstr "" +"我們剛剛引入了另一個關鍵字 ``default``。我們將其設為 ``0``，以便使其與其他 " +"int 值進行比較。請記住，預設情況下，如果未指定可選引數，它將獲得 ``None`` " +"值，並且不能與 int 值進行比較（因此會出現 :exc:`TypeError` 例外）。" + +#: ../../howto/argparse.rst:590 +msgid "And:" +msgstr "而且：" + +#: ../../howto/argparse.rst:592 +msgid "" +"$ python prog.py 4\n" +"16" +msgstr "" +"$ python prog.py 4\n" +"16" + +#: ../../howto/argparse.rst:597 +msgid "" +"You can go quite far just with what we've learned so far, and we have only " +"scratched the surface. The :mod:`argparse` module is very powerful, and " +"we'll explore a bit more of it before we end this tutorial." +msgstr "" +"僅憑我們迄今為止所學到的知識就可以做到很多事情了，不過其實這樣只有學到一點皮" +"毛而已。:mod:`argparse` 模組非常強大，在結束本教學之前我們會對它進行更多探" +"索。" + +#: ../../howto/argparse.rst:604 +msgid "Getting a little more advanced" +msgstr "更進階一點" + +#: ../../howto/argparse.rst:606 +msgid "" +"What if we wanted to expand our tiny program to perform other powers, not " +"just squares::" +msgstr "如果我們想擴充我們的小程式來執行其他次方的運算，而不僅是平方： ::" + +#: ../../howto/argparse.rst:609 +msgid "" +"import argparse\n" +"parser = argparse.ArgumentParser()\n" +"parser.add_argument(\"x\", type=int, help=\"the base\")\n" +"parser.add_argument(\"y\", type=int, help=\"the exponent\")\n" +"parser.add_argument(\"-v\", \"--verbosity\", action=\"count\", default=0)\n" +"args = parser.parse_args()\n" +"answer = args.x**args.y\n" +"if args.verbosity >= 2:\n" +" print(f\"{args.x} to the power {args.y} equals {answer}\")\n" +"elif args.verbosity >= 1:\n" +" print(f\"{args.x}^{args.y} == {answer}\")\n" +"else:\n" +" print(answer)" +msgstr "" +"import argparse\n" +"parser = argparse.ArgumentParser()\n" +"parser.add_argument(\"x\", type=int, help=\"the base\")\n" +"parser.add_argument(\"y\", type=int, help=\"the exponent\")\n" +"parser.add_argument(\"-v\", \"--verbosity\", action=\"count\", default=0)\n" +"args = parser.parse_args()\n" +"answer = args.x**args.y\n" +"if args.verbosity >= 2:\n" +" print(f\"{args.x} to the power {args.y} equals {answer}\")\n" +"elif args.verbosity >= 1:\n" +" print(f\"{args.x}^{args.y} == {answer}\")\n" +"else:\n" +" print(answer)" + +#: ../../howto/argparse.rst:623 ../../howto/argparse.rst:661 +#: ../../howto/argparse.rst:877 +msgid "Output:" +msgstr "結果：" + +#: ../../howto/argparse.rst:625 +msgid "" +"$ python prog.py\n" +"usage: prog.py [-h] [-v] x y\n" +"prog.py: error: the following arguments are required: x, y\n" +"$ python prog.py -h\n" +"usage: prog.py [-h] [-v] x y\n" +"\n" +"positional arguments:\n" +" x the base\n" +" y the exponent\n" +"\n" +"options:\n" +" -h, --help show this help message and exit\n" +" -v, --verbosity\n" +"$ python prog.py 4 2 -v\n" +"4^2 == 16" +msgstr "" +"$ python prog.py\n" +"usage: prog.py [-h] [-v] x y\n" +"prog.py: error: the following arguments are required: x, y\n" +"$ python prog.py -h\n" +"usage: prog.py [-h] [-v] x y\n" +"\n" +"positional arguments:\n" +" x the base\n" +" y the exponent\n" +"\n" +"options:\n" +" -h, --help show this help message and exit\n" +" -v, --verbosity\n" +"$ python prog.py 4 2 -v\n" +"4^2 == 16" + +#: ../../howto/argparse.rst:644 +msgid "" +"Notice that so far we've been using verbosity level to *change* the text " +"that gets displayed. The following example instead uses verbosity level to " +"display *more* text instead::" +msgstr "" +"請注意，到目前為止，我們一直在使用詳細級別來\\ *更改*\\ 顯示的文字。以下範例" +"使用詳細級別來顯示\\ *更多*\\ 文字： ::" + +#: ../../howto/argparse.rst:648 +msgid "" +"import argparse\n" +"parser = argparse.ArgumentParser()\n" +"parser.add_argument(\"x\", type=int, help=\"the base\")\n" +"parser.add_argument(\"y\", type=int, help=\"the exponent\")\n" +"parser.add_argument(\"-v\", \"--verbosity\", action=\"count\", default=0)\n" +"args = parser.parse_args()\n" +"answer = args.x**args.y\n" +"if args.verbosity >= 2:\n" +" print(f\"Running '{__file__}'\")\n" +"if args.verbosity >= 1:\n" +" print(f\"{args.x}^{args.y} == \", end=\"\")\n" +"print(answer)" +msgstr "" +"import argparse\n" +"parser = argparse.ArgumentParser()\n" +"parser.add_argument(\"x\", type=int, help=\"the base\")\n" +"parser.add_argument(\"y\", type=int, help=\"the exponent\")\n" +"parser.add_argument(\"-v\", \"--verbosity\", action=\"count\", default=0)\n" +"args = parser.parse_args()\n" +"answer = args.x**args.y\n" +"if args.verbosity >= 2:\n" +" print(f\"Running '{__file__}'\")\n" +"if args.verbosity >= 1:\n" +" print(f\"{args.x}^{args.y} == \", end=\"\")\n" +"print(answer)" + +#: ../../howto/argparse.rst:663 +msgid "" +"$ python prog.py 4 2\n" +"16\n" +"$ python prog.py 4 2 -v\n" +"4^2 == 16\n" +"$ python prog.py 4 2 -vv\n" +"Running 'prog.py'\n" +"4^2 == 16" +msgstr "" +"$ python prog.py 4 2\n" +"16\n" +"$ python prog.py 4 2 -v\n" +"4^2 == 16\n" +"$ python prog.py 4 2 -vv\n" +"Running 'prog.py'\n" +"4^2 == 16" + +#: ../../howto/argparse.rst:677 +msgid "Specifying ambiguous arguments" +msgstr "指定不明確的引數" + +#: ../../howto/argparse.rst:679 +msgid "" +"When there is ambiguity in deciding whether an argument is positional or for " +"an argument, ``--`` can be used to tell :meth:`~ArgumentParser.parse_args` " +"that everything after that is a positional argument::" +msgstr "" +"當決定一個引數是位置引數還是引數會有歧義，可以使用 ``--`` 來告訴 :meth:" +"`~ArgumentParser.parse_args` 之後的所有內容都是位置引數： ::" + +#: ../../howto/argparse.rst:683 +msgid "" +">>> parser = argparse.ArgumentParser(prog='PROG')\n" +">>> parser.add_argument('-n', nargs='+')\n" +">>> parser.add_argument('args', nargs='*')\n" +"\n" +">>> # ambiguous, so parse_args assumes it's an option\n" +">>> parser.parse_args(['-f'])\n" +"usage: PROG [-h] [-n N [N ...]] [args ...]\n" +"PROG: error: unrecognized arguments: -f\n" +"\n" +">>> parser.parse_args(['--', '-f'])\n" +"Namespace(args=['-f'], n=None)\n" +"\n" +">>> # ambiguous, so the -n option greedily accepts arguments\n" +">>> parser.parse_args(['-n', '1', '2', '3'])\n" +"Namespace(args=[], n=['1', '2', '3'])\n" +"\n" +">>> parser.parse_args(['-n', '1', '--', '2', '3'])\n" +"Namespace(args=['2', '3'], n=['1'])" +msgstr "" +">>> parser = argparse.ArgumentParser(prog='PROG')\n" +">>> parser.add_argument('-n', nargs='+')\n" +">>> parser.add_argument('args', nargs='*')\n" +"\n" +">>> # ambiguous, so parse_args assumes it's an option\n" +">>> parser.parse_args(['-f'])\n" +"usage: PROG [-h] [-n N [N ...]] [args ...]\n" +"PROG: error: unrecognized arguments: -f\n" +"\n" +">>> parser.parse_args(['--', '-f'])\n" +"Namespace(args=['-f'], n=None)\n" +"\n" +">>> # ambiguous, so the -n option greedily accepts arguments\n" +">>> parser.parse_args(['-n', '1', '2', '3'])\n" +"Namespace(args=[], n=['1', '2', '3'])\n" +"\n" +">>> parser.parse_args(['-n', '1', '--', '2', '3'])\n" +"Namespace(args=['2', '3'], n=['1'])" + +#: ../../howto/argparse.rst:704 +msgid "Conflicting options" +msgstr "相互衝突的選項" + +#: ../../howto/argparse.rst:706 +msgid "" +"So far, we have been working with two methods of an :class:`argparse." +"ArgumentParser` instance. Let's introduce a third one, :meth:" +"`~ArgumentParser.add_mutually_exclusive_group`. It allows for us to specify " +"options that conflict with each other. Let's also change the rest of the " +"program so that the new functionality makes more sense: we'll introduce the " +"``--quiet`` option, which will be the opposite of the ``--verbose`` one::" +msgstr "" +"到目前為止，我們一直在使用 :class:`argparse.ArgumentParser` 實例的兩種方法。" +"讓我們介紹第三個，:meth:`~ArgumentParser.add_mutually_exclusive_group`，它允" +"許我們指定彼此衝突的選項。我們還可以更改程式的其餘部分，以使得新功能更有意" +"義：我們將引入 ``--quiet`` 選項，該選項與 ``--verbose`` 選項相反： ::" + +#: ../../howto/argparse.rst:714 +msgid "" +"import argparse\n" +"\n" +"parser = argparse.ArgumentParser()\n" +"group = parser.add_mutually_exclusive_group()\n" +"group.add_argument(\"-v\", \"--verbose\", action=\"store_true\")\n" +"group.add_argument(\"-q\", \"--quiet\", action=\"store_true\")\n" +"parser.add_argument(\"x\", type=int, help=\"the base\")\n" +"parser.add_argument(\"y\", type=int, help=\"the exponent\")\n" +"args = parser.parse_args()\n" +"answer = args.x**args.y\n" +"\n" +"if args.quiet:\n" +" print(answer)\n" +"elif args.verbose:\n" +" print(f\"{args.x} to the power {args.y} equals {answer}\")\n" +"else:\n" +" print(f\"{args.x}^{args.y} == {answer}\")" +msgstr "" +"import argparse\n" +"\n" +"parser = argparse.ArgumentParser()\n" +"group = parser.add_mutually_exclusive_group()\n" +"group.add_argument(\"-v\", \"--verbose\", action=\"store_true\")\n" +"group.add_argument(\"-q\", \"--quiet\", action=\"store_true\")\n" +"parser.add_argument(\"x\", type=int, help=\"the base\")\n" +"parser.add_argument(\"y\", type=int, help=\"the exponent\")\n" +"args = parser.parse_args()\n" +"answer = args.x**args.y\n" +"\n" +"if args.quiet:\n" +" print(answer)\n" +"elif args.verbose:\n" +" print(f\"{args.x} to the power {args.y} equals {answer}\")\n" +"else:\n" +" print(f\"{args.x}^{args.y} == {answer}\")" + +#: ../../howto/argparse.rst:732 +msgid "" +"Our program is now simpler, and we've lost some functionality for the sake " +"of demonstration. Anyways, here's the output:" +msgstr "" +"我們的程式現在更簡單了，我們因為功能展示失去了一些功能，但無論如何，以下這是" +"輸出：" + +#: ../../howto/argparse.rst:735 +msgid "" +"$ python prog.py 4 2\n" +"4^2 == 16\n" +"$ python prog.py 4 2 -q\n" +"16\n" +"$ python prog.py 4 2 -v\n" +"4 to the power 2 equals 16\n" +"$ python prog.py 4 2 -vq\n" +"usage: prog.py [-h] [-v | -q] x y\n" +"prog.py: error: argument -q/--quiet: not allowed with argument -v/--verbose\n" +"$ python prog.py 4 2 -v --quiet\n" +"usage: prog.py [-h] [-v | -q] x y\n" +"prog.py: error: argument -q/--quiet: not allowed with argument -v/--verbose" +msgstr "" +"$ python prog.py 4 2\n" +"4^2 == 16\n" +"$ python prog.py 4 2 -q\n" +"16\n" +"$ python prog.py 4 2 -v\n" +"4 to the power 2 equals 16\n" +"$ python prog.py 4 2 -vq\n" +"usage: prog.py [-h] [-v | -q] x y\n" +"prog.py: error: argument -q/--quiet: not allowed with argument -v/--verbose\n" +"$ python prog.py 4 2 -v --quiet\n" +"usage: prog.py [-h] [-v | -q] x y\n" +"prog.py: error: argument -q/--quiet: not allowed with argument -v/--verbose" + +#: ../../howto/argparse.rst:750 +msgid "" +"That should be easy to follow. I've added that last output so you can see " +"the sort of flexibility you get, i.e. mixing long form options with short " +"form ones." +msgstr "" +"這應該很容易理解。我新增了最後一個輸出，以便看到所獲得的靈活性，即可以混合長" +"形式與短形式選項。" + +#: ../../howto/argparse.rst:754 +msgid "" +"Before we conclude, you probably want to tell your users the main purpose of " +"your program, just in case they don't know::" +msgstr "" +"在我們結束之前，你可能想告訴使用者你的程式的主要目的，以防他們不知道： ::" + +#: ../../howto/argparse.rst:757 +msgid "" +"import argparse\n" +"\n" +"parser = argparse.ArgumentParser(description=\"calculate X to the power of " +"Y\")\n" +"group = parser.add_mutually_exclusive_group()\n" +"group.add_argument(\"-v\", \"--verbose\", action=\"store_true\")\n" +"group.add_argument(\"-q\", \"--quiet\", action=\"store_true\")\n" +"parser.add_argument(\"x\", type=int, help=\"the base\")\n" +"parser.add_argument(\"y\", type=int, help=\"the exponent\")\n" +"args = parser.parse_args()\n" +"answer = args.x**args.y\n" +"\n" +"if args.quiet:\n" +" print(answer)\n" +"elif args.verbose:\n" +" print(f\"{args.x} to the power {args.y} equals {answer}\")\n" +"else:\n" +" print(f\"{args.x}^{args.y} == {answer}\")" +msgstr "" +"import argparse\n" +"\n" +"parser = argparse.ArgumentParser(description=\"calculate X to the power of " +"Y\")\n" +"group = parser.add_mutually_exclusive_group()\n" +"group.add_argument(\"-v\", \"--verbose\", action=\"store_true\")\n" +"group.add_argument(\"-q\", \"--quiet\", action=\"store_true\")\n" +"parser.add_argument(\"x\", type=int, help=\"the base\")\n" +"parser.add_argument(\"y\", type=int, help=\"the exponent\")\n" +"args = parser.parse_args()\n" +"answer = args.x**args.y\n" +"\n" +"if args.quiet:\n" +" print(answer)\n" +"elif args.verbose:\n" +" print(f\"{args.x} to the power {args.y} equals {answer}\")\n" +"else:\n" +" print(f\"{args.x}^{args.y} == {answer}\")" + +#: ../../howto/argparse.rst:775 +msgid "" +"Note that slight difference in the usage text. Note the ``[-v | -q]``, which " +"tells us that we can either use ``-v`` or ``-q``, but not both at the same " +"time:" +msgstr "" +"請注意用法文字中的細微差別。注意 ``[-v | -q]``，它告訴我們可以使用 ``-v`` 或 " +"``-q``，但不能同時使用：" + +#: ../../howto/argparse.rst:779 ../../howto/argparse.rst:806 +msgid "" +"$ python prog.py --help\n" +"usage: prog.py [-h] [-v | -q] x y\n" +"\n" +"calculate X to the power of Y\n" +"\n" +"positional arguments:\n" +" x the base\n" +" y the exponent\n" +"\n" +"options:\n" +" -h, --help show this help message and exit\n" +" -v, --verbose\n" +" -q, --quiet" +msgstr "" +"$ python prog.py --help\n" +"usage: prog.py [-h] [-v | -q] x y\n" +"\n" +"calculate X to the power of Y\n" +"\n" +"positional arguments:\n" +" x the base\n" +" y the exponent\n" +"\n" +"options:\n" +" -h, --help show this help message and exit\n" +" -v, --verbose\n" +" -q, --quiet" + +#: ../../howto/argparse.rst:797 +msgid "How to translate the argparse output" +msgstr "如何翻譯 argparse 輸出" + +#: ../../howto/argparse.rst:799 +msgid "" +"The output of the :mod:`argparse` module such as its help text and error " +"messages are all made translatable using the :mod:`gettext` module. This " +"allows applications to easily localize messages produced by :mod:`argparse`. " +"See also :ref:`i18n-howto`." +msgstr "" +":mod:`argparse` 模組的輸出，例如幫助文字和錯誤訊息，都可以透過使用 :mod:" +"`gettext` 模組進行翻譯。這允許應用程式能輕鬆在地化 :mod:`argparse` 生成的訊" +"息。另請參閱 :ref:`i18n-howto`。" + +#: ../../howto/argparse.rst:804 +msgid "For instance, in this :mod:`argparse` output:" +msgstr "例如，在此 :mod:`argparse` 輸出中：" + +#: ../../howto/argparse.rst:822 +msgid "" +"The strings ``usage:``, ``positional arguments:``, ``options:`` and ``show " +"this help message and exit`` are all translatable." +msgstr "" +"字串 ``usage:``、``positional arguments:``、``options:`` 和 ``show this help " +"message and exit`` 都是可被翻譯的。" + +#: ../../howto/argparse.rst:825 +msgid "" +"In order to translate these strings, they must first be extracted into a ``." +"po`` file. For example, using `Babel `__, run this " +"command:" +msgstr "" +"為了翻譯這些字串，必須先將它們提取到 ``.po`` 檔案中。例如，使用 `Babel " +"`__ 並執行下列命令：" + +#: ../../howto/argparse.rst:829 +msgid "$ pybabel extract -o messages.po /usr/lib/python3.12/argparse.py" +msgstr "$ pybabel extract -o messages.po /usr/lib/python3.12/argparse.py" + +#: ../../howto/argparse.rst:833 +msgid "" +"This command will extract all translatable strings from the :mod:`argparse` " +"module and output them into a file named ``messages.po``. This command " +"assumes that your Python installation is in ``/usr/lib``." +msgstr "" +"此命令將從 :mod:`argparse` 模組中提取出所有可翻譯的字串，並將它們輸出到名為 " +"``messages.po`` 的檔案中。這個指令假設你的 Python 是安裝在 ``/usr/lib`` 中。" + +#: ../../howto/argparse.rst:837 +msgid "" +"You can find out the location of the :mod:`argparse` module on your system " +"using this script::" +msgstr "你可以使用以下腳本找到 :mod:`argparse` 模組在系統上的位置： ::" + +#: ../../howto/argparse.rst:840 +msgid "" +"import argparse\n" +"print(argparse.__file__)" +msgstr "" +"import argparse\n" +"print(argparse.__file__)" + +#: ../../howto/argparse.rst:843 +msgid "" +"Once the messages in the ``.po`` file are translated and the translations " +"are installed using :mod:`gettext`, :mod:`argparse` will be able to display " +"the translated messages." +msgstr "" +"一旦翻譯了 ``.po`` 檔案中的訊息並使用 :mod:`gettext` 安裝了翻譯，:mod:" +"`argparse` 將能夠顯示翻譯後的訊息。" + +#: ../../howto/argparse.rst:847 +msgid "" +"To translate your own strings in the :mod:`argparse` output, use :mod:" +"`gettext`." +msgstr "若要在 :mod:`argparse` 輸出中翻譯你自己的字串，請使用 :mod:`gettext`。" + +#: ../../howto/argparse.rst:850 +msgid "Custom type converters" +msgstr "自訂型別轉換器" + +#: ../../howto/argparse.rst:852 +msgid "" +"The :mod:`argparse` module allows you to specify custom type converters for " +"your command-line arguments. This allows you to modify user input before " +"it's stored in the :class:`argparse.Namespace`. This can be useful when you " +"need to pre-process the input before it is used in your program." +msgstr "" + +#: ../../howto/argparse.rst:857 +msgid "" +"When using a custom type converter, you can use any callable that takes a " +"single string argument (the argument value) and returns the converted value. " +"However, if you need to handle more complex scenarios, you can use a custom " +"action class with the **action** parameter instead." +msgstr "" + +#: ../../howto/argparse.rst:862 +msgid "" +"For example, let's say you want to handle arguments with different prefixes " +"and process them accordingly::" +msgstr "" + +#: ../../howto/argparse.rst:865 +msgid "" +"import argparse\n" +"\n" +"parser = argparse.ArgumentParser(prefix_chars='-+')\n" +"\n" +"parser.add_argument('-a', metavar='', action='append',\n" +" type=lambda x: ('-', x))\n" +"parser.add_argument('+a', metavar='', action='append',\n" +" type=lambda x: ('+', x))\n" +"\n" +"args = parser.parse_args()\n" +"print(args)" +msgstr "" +"import argparse\n" +"\n" +"parser = argparse.ArgumentParser(prefix_chars='-+')\n" +"\n" +"parser.add_argument('-a', metavar='', action='append',\n" +" type=lambda x: ('-', x))\n" +"parser.add_argument('+a', metavar='', action='append',\n" +" type=lambda x: ('+', x))\n" +"\n" +"args = parser.parse_args()\n" +"print(args)" + +#: ../../howto/argparse.rst:879 +msgid "" +"$ python prog.py -a value1 +a value2\n" +"Namespace(a=[('-', 'value1'), ('+', 'value2')])" +msgstr "" +"$ python prog.py -a value1 +a value2\n" +"Namespace(a=[('-', 'value1'), ('+', 'value2')])" + +#: ../../howto/argparse.rst:884 +msgid "In this example, we:" +msgstr "在這個範例當中，我們：" + +#: ../../howto/argparse.rst:886 +msgid "" +"Created a parser with custom prefix characters using the ``prefix_chars`` " +"parameter." +msgstr "" + +#: ../../howto/argparse.rst:889 +msgid "" +"Defined two arguments, ``-a`` and ``+a``, which used the ``type`` parameter " +"to create custom type converters to store the value in a tuple with the " +"prefix." +msgstr "" + +#: ../../howto/argparse.rst:892 +msgid "" +"Without the custom type converters, the arguments would have treated the ``-" +"a`` and ``+a`` as the same argument, which would have been undesirable. By " +"using custom type converters, we were able to differentiate between the two " +"arguments." +msgstr "" + +#: ../../howto/argparse.rst:897 +msgid "Conclusion" +msgstr "結論" + +#: ../../howto/argparse.rst:899 +msgid "" +"The :mod:`argparse` module offers a lot more than shown here. Its docs are " +"quite detailed and thorough, and full of examples. Having gone through this " +"tutorial, you should easily digest them without feeling overwhelmed." +msgstr "" +":mod:`argparse` 模組提供的功能比此篇內容的要多得多。它的文件非常詳細與透徹並" +"有很多範例。讀完本教學後，你應該可以輕鬆消化它們，而不會感到不知所措。" diff --git a/howto/clinic.po b/howto/clinic.po index 091628bfa0..2622b93ae7 100644 --- a/howto/clinic.po +++ b/howto/clinic.po @@ -1,30 +1,30 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2023-10-13 00:03+0000\n" -"PO-Revision-Date: 2018-05-23 14:36+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" - -#: ../../howto/clinic.rst:8 -msgid "Argument Clinic How-To" -msgstr "Argument Clinic 指南" - -#: ../../howto/clinic.rst:13 -msgid "" -"The Argument Clinic How-TO has been moved to the `Python Developer's Guide " -"`__." -msgstr "" -"Argument Clinic 操作方法已移至「`Python 開發人員指南 `__」。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-10-13 00:03+0000\n" +"PO-Revision-Date: 2018-05-23 14:36+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" + +#: ../../howto/clinic.rst:8 +msgid "Argument Clinic How-To" +msgstr "Argument Clinic 指南" + +#: ../../howto/clinic.rst:13 +msgid "" +"The Argument Clinic How-TO has been moved to the `Python Developer's Guide " +"`__." +msgstr "" +"Argument Clinic 操作方法已移至「`Python 開發人員指南 `__」。" diff --git a/howto/cporting.po b/howto/cporting.po index 63e3f6d9df..676e19d9ce 100644 --- a/howto/cporting.po +++ b/howto/cporting.po @@ -1,50 +1,50 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Leon H., 2017 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-06-27 07:36+0000\n" -"PO-Revision-Date: 2018-05-23 14:36+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" - -#: ../../howto/cporting.rst:7 -msgid "Porting Extension Modules to Python 3" -msgstr "遷移延伸模組到 Python 3" - -#: ../../howto/cporting.rst:9 -msgid "" -"We recommend the following resources for porting extension modules to Python " -"3:" -msgstr "" - -#: ../../howto/cporting.rst:11 -msgid "" -"The `Migrating C extensions`_ chapter from *Supporting Python 3: An in-depth " -"guide*, a book on moving from Python 2 to Python 3 in general, guides the " -"reader through porting an extension module." -msgstr "" - -#: ../../howto/cporting.rst:15 -msgid "" -"The `Porting guide`_ from the *py3c* project provides opinionated " -"suggestions with supporting code." -msgstr "" - -#: ../../howto/cporting.rst:17 -msgid "" -":ref:`Recommended third party tools ` offer abstractions over " -"the Python's C API. Extensions generally need to be re-written to use one of " -"them, but the library then handles differences between various Python " -"versions and implementations." -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Leon H., 2017 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-06-27 07:36+0000\n" +"PO-Revision-Date: 2018-05-23 14:36+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" + +#: ../../howto/cporting.rst:7 +msgid "Porting Extension Modules to Python 3" +msgstr "遷移延伸模組到 Python 3" + +#: ../../howto/cporting.rst:9 +msgid "" +"We recommend the following resources for porting extension modules to Python " +"3:" +msgstr "" + +#: ../../howto/cporting.rst:11 +msgid "" +"The `Migrating C extensions`_ chapter from *Supporting Python 3: An in-depth " +"guide*, a book on moving from Python 2 to Python 3 in general, guides the " +"reader through porting an extension module." +msgstr "" + +#: ../../howto/cporting.rst:15 +msgid "" +"The `Porting guide`_ from the *py3c* project provides opinionated " +"suggestions with supporting code." +msgstr "" + +#: ../../howto/cporting.rst:17 +msgid "" +":ref:`Recommended third party tools ` offer abstractions over " +"the Python's C API. Extensions generally need to be re-written to use one of " +"them, but the library then handles differences between various Python " +"versions and implementations." +msgstr "" diff --git a/howto/curses.po b/howto/curses.po index 38eb0c2a5e..2219986634 100644 --- a/howto/curses.po +++ b/howto/curses.po @@ -1,879 +1,879 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-12-01 00:17+0000\n" -"PO-Revision-Date: 2018-05-23 14:36+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" - -#: ../../howto/curses.rst:5 -msgid "Curses Programming with Python" -msgstr "" - -#: ../../howto/curses.rst:0 -msgid "Author" -msgstr "作者" - -#: ../../howto/curses.rst:9 -msgid "A.M. Kuchling, Eric S. Raymond" -msgstr "A.M. Kuchling, Eric S. Raymond" - -#: ../../howto/curses.rst:0 -msgid "Release" -msgstr "發佈版本" - -#: ../../howto/curses.rst:10 -msgid "2.04" -msgstr "2.04" - -#: ../../howto/curses.rst:13 -msgid "Abstract" -msgstr "摘要" - -#: ../../howto/curses.rst:15 -msgid "" -"This document describes how to use the :mod:`curses` extension module to " -"control text-mode displays." -msgstr "" - -#: ../../howto/curses.rst:20 -msgid "What is curses?" -msgstr "" - -#: ../../howto/curses.rst:22 -msgid "" -"The curses library supplies a terminal-independent screen-painting and " -"keyboard-handling facility for text-based terminals; such terminals include " -"VT100s, the Linux console, and the simulated terminal provided by various " -"programs. Display terminals support various control codes to perform common " -"operations such as moving the cursor, scrolling the screen, and erasing " -"areas. Different terminals use widely differing codes, and often have their " -"own minor quirks." -msgstr "" - -#: ../../howto/curses.rst:30 -msgid "" -"In a world of graphical displays, one might ask \"why bother\"? It's true " -"that character-cell display terminals are an obsolete technology, but there " -"are niches in which being able to do fancy things with them are still " -"valuable. One niche is on small-footprint or embedded Unixes that don't run " -"an X server. Another is tools such as OS installers and kernel " -"configurators that may have to run before any graphical support is available." -msgstr "" - -#: ../../howto/curses.rst:38 -msgid "" -"The curses library provides fairly basic functionality, providing the " -"programmer with an abstraction of a display containing multiple non-" -"overlapping windows of text. The contents of a window can be changed in " -"various ways---adding text, erasing it, changing its appearance---and the " -"curses library will figure out what control codes need to be sent to the " -"terminal to produce the right output. curses doesn't provide many user-" -"interface concepts such as buttons, checkboxes, or dialogs; if you need such " -"features, consider a user interface library such as :pypi:`Urwid`." -msgstr "" - -#: ../../howto/curses.rst:48 -msgid "" -"The curses library was originally written for BSD Unix; the later System V " -"versions of Unix from AT&T added many enhancements and new functions. BSD " -"curses is no longer maintained, having been replaced by ncurses, which is an " -"open-source implementation of the AT&T interface. If you're using an open-" -"source Unix such as Linux or FreeBSD, your system almost certainly uses " -"ncurses. Since most current commercial Unix versions are based on System V " -"code, all the functions described here will probably be available. The " -"older versions of curses carried by some proprietary Unixes may not support " -"everything, though." -msgstr "" - -#: ../../howto/curses.rst:58 -msgid "" -"The Windows version of Python doesn't include the :mod:`curses` module. A " -"ported version called :pypi:`UniCurses` is available." -msgstr "" - -#: ../../howto/curses.rst:63 -msgid "The Python curses module" -msgstr "Python curses 模組" - -#: ../../howto/curses.rst:65 -msgid "" -"The Python module is a fairly simple wrapper over the C functions provided " -"by curses; if you're already familiar with curses programming in C, it's " -"really easy to transfer that knowledge to Python. The biggest difference is " -"that the Python interface makes things simpler by merging different C " -"functions such as :c:func:`!addstr`, :c:func:`!mvaddstr`, and :c:func:`!" -"mvwaddstr` into a single :meth:`~curses.window.addstr` method. You'll see " -"this covered in more detail later." -msgstr "" - -#: ../../howto/curses.rst:73 -msgid "" -"This HOWTO is an introduction to writing text-mode programs with curses and " -"Python. It doesn't attempt to be a complete guide to the curses API; for " -"that, see the Python library guide's section on ncurses, and the C manual " -"pages for ncurses. It will, however, give you the basic ideas." -msgstr "" - -#: ../../howto/curses.rst:80 -msgid "Starting and ending a curses application" -msgstr "" - -#: ../../howto/curses.rst:82 -msgid "" -"Before doing anything, curses must be initialized. This is done by calling " -"the :func:`~curses.initscr` function, which will determine the terminal " -"type, send any required setup codes to the terminal, and create various " -"internal data structures. If successful, :func:`!initscr` returns a window " -"object representing the entire screen; this is usually called ``stdscr`` " -"after the name of the corresponding C variable. ::" -msgstr "" - -#: ../../howto/curses.rst:90 -msgid "" -"import curses\n" -"stdscr = curses.initscr()" -msgstr "" -"import curses\n" -"stdscr = curses.initscr()" - -#: ../../howto/curses.rst:93 -msgid "" -"Usually curses applications turn off automatic echoing of keys to the " -"screen, in order to be able to read keys and only display them under certain " -"circumstances. This requires calling the :func:`~curses.noecho` function. ::" -msgstr "" - -#: ../../howto/curses.rst:98 -msgid "curses.noecho()" -msgstr "curses.noecho()" - -#: ../../howto/curses.rst:100 -msgid "" -"Applications will also commonly need to react to keys instantly, without " -"requiring the Enter key to be pressed; this is called cbreak mode, as " -"opposed to the usual buffered input mode. ::" -msgstr "" - -#: ../../howto/curses.rst:104 -msgid "curses.cbreak()" -msgstr "curses.cbreak()" - -#: ../../howto/curses.rst:106 -msgid "" -"Terminals usually return special keys, such as the cursor keys or navigation " -"keys such as Page Up and Home, as a multibyte escape sequence. While you " -"could write your application to expect such sequences and process them " -"accordingly, curses can do it for you, returning a special value such as :" -"const:`curses.KEY_LEFT`. To get curses to do the job, you'll have to enable " -"keypad mode. ::" -msgstr "" - -#: ../../howto/curses.rst:113 -msgid "stdscr.keypad(True)" -msgstr "stdscr.keypad(True)" - -#: ../../howto/curses.rst:115 -msgid "" -"Terminating a curses application is much easier than starting one. You'll " -"need to call::" -msgstr "" - -#: ../../howto/curses.rst:118 -msgid "" -"curses.nocbreak()\n" -"stdscr.keypad(False)\n" -"curses.echo()" -msgstr "" -"curses.nocbreak()\n" -"stdscr.keypad(False)\n" -"curses.echo()" - -#: ../../howto/curses.rst:122 -msgid "" -"to reverse the curses-friendly terminal settings. Then call the :func:" -"`~curses.endwin` function to restore the terminal to its original operating " -"mode. ::" -msgstr "" - -#: ../../howto/curses.rst:126 -msgid "curses.endwin()" -msgstr "curses.endwin()" - -#: ../../howto/curses.rst:128 -msgid "" -"A common problem when debugging a curses application is to get your terminal " -"messed up when the application dies without restoring the terminal to its " -"previous state. In Python this commonly happens when your code is buggy and " -"raises an uncaught exception. Keys are no longer echoed to the screen when " -"you type them, for example, which makes using the shell difficult." -msgstr "" - -#: ../../howto/curses.rst:134 -msgid "" -"In Python you can avoid these complications and make debugging much easier " -"by importing the :func:`curses.wrapper` function and using it like this::" -msgstr "" - -#: ../../howto/curses.rst:137 -msgid "" -"from curses import wrapper\n" -"\n" -"def main(stdscr):\n" -" # Clear screen\n" -" stdscr.clear()\n" -"\n" -" # This raises ZeroDivisionError when i == 10.\n" -" for i in range(0, 11):\n" -" v = i-10\n" -" stdscr.addstr(i, 0, '10 divided by {} is {}'.format(v, 10/v))\n" -"\n" -" stdscr.refresh()\n" -" stdscr.getkey()\n" -"\n" -"wrapper(main)" -msgstr "" - -#: ../../howto/curses.rst:153 -msgid "" -"The :func:`~curses.wrapper` function takes a callable object and does the " -"initializations described above, also initializing colors if color support " -"is present. :func:`!wrapper` then runs your provided callable. Once the " -"callable returns, :func:`!wrapper` will restore the original state of the " -"terminal. The callable is called inside a :keyword:`try`...\\ :keyword:" -"`except` that catches exceptions, restores the state of the terminal, and " -"then re-raises the exception. Therefore your terminal won't be left in a " -"funny state on exception and you'll be able to read the exception's message " -"and traceback." -msgstr "" - -#: ../../howto/curses.rst:165 -msgid "Windows and Pads" -msgstr "" - -#: ../../howto/curses.rst:167 -msgid "" -"Windows are the basic abstraction in curses. A window object represents a " -"rectangular area of the screen, and supports methods to display text, erase " -"it, allow the user to input strings, and so forth." -msgstr "" - -#: ../../howto/curses.rst:171 -msgid "" -"The ``stdscr`` object returned by the :func:`~curses.initscr` function is a " -"window object that covers the entire screen. Many programs may need only " -"this single window, but you might wish to divide the screen into smaller " -"windows, in order to redraw or clear them separately. The :func:`~curses." -"newwin` function creates a new window of a given size, returning the new " -"window object. ::" -msgstr "" - -#: ../../howto/curses.rst:178 -msgid "" -"begin_x = 20; begin_y = 7\n" -"height = 5; width = 40\n" -"win = curses.newwin(height, width, begin_y, begin_x)" -msgstr "" -"begin_x = 20; begin_y = 7\n" -"height = 5; width = 40\n" -"win = curses.newwin(height, width, begin_y, begin_x)" - -#: ../../howto/curses.rst:182 -msgid "" -"Note that the coordinate system used in curses is unusual. Coordinates are " -"always passed in the order *y,x*, and the top-left corner of a window is " -"coordinate (0,0). This breaks the normal convention for handling " -"coordinates where the *x* coordinate comes first. This is an unfortunate " -"difference from most other computer applications, but it's been part of " -"curses since it was first written, and it's too late to change things now." -msgstr "" - -#: ../../howto/curses.rst:190 -msgid "" -"Your application can determine the size of the screen by using the :data:" -"`curses.LINES` and :data:`curses.COLS` variables to obtain the *y* and *x* " -"sizes. Legal coordinates will then extend from ``(0,0)`` to ``(curses.LINES " -"- 1, curses.COLS - 1)``." -msgstr "" - -#: ../../howto/curses.rst:195 -msgid "" -"When you call a method to display or erase text, the effect doesn't " -"immediately show up on the display. Instead you must call the :meth:" -"`~curses.window.refresh` method of window objects to update the screen." -msgstr "" - -#: ../../howto/curses.rst:200 -msgid "" -"This is because curses was originally written with slow 300-baud terminal " -"connections in mind; with these terminals, minimizing the time required to " -"redraw the screen was very important. Instead curses accumulates changes to " -"the screen and displays them in the most efficient manner when you call :" -"meth:`!refresh`. For example, if your program displays some text in a " -"window and then clears the window, there's no need to send the original text " -"because they're never visible." -msgstr "" - -#: ../../howto/curses.rst:209 -msgid "" -"In practice, explicitly telling curses to redraw a window doesn't really " -"complicate programming with curses much. Most programs go into a flurry of " -"activity, and then pause waiting for a keypress or some other action on the " -"part of the user. All you have to do is to be sure that the screen has been " -"redrawn before pausing to wait for user input, by first calling :meth:`!" -"stdscr.refresh` or the :meth:`!refresh` method of some other relevant window." -msgstr "" - -#: ../../howto/curses.rst:217 -msgid "" -"A pad is a special case of a window; it can be larger than the actual " -"display screen, and only a portion of the pad displayed at a time. Creating " -"a pad requires the pad's height and width, while refreshing a pad requires " -"giving the coordinates of the on-screen area where a subsection of the pad " -"will be displayed. ::" -msgstr "" - -#: ../../howto/curses.rst:223 -msgid "" -"pad = curses.newpad(100, 100)\n" -"# These loops fill the pad with letters; addch() is\n" -"# explained in the next section\n" -"for y in range(0, 99):\n" -" for x in range(0, 99):\n" -" pad.addch(y,x, ord('a') + (x*x+y*y) % 26)\n" -"\n" -"# Displays a section of the pad in the middle of the screen.\n" -"# (0,0) : coordinate of upper-left corner of pad area to display.\n" -"# (5,5) : coordinate of upper-left corner of window area to be filled\n" -"# with pad content.\n" -"# (20, 75) : coordinate of lower-right corner of window area to be\n" -"# : filled with pad content.\n" -"pad.refresh( 0,0, 5,5, 20,75)" -msgstr "" - -#: ../../howto/curses.rst:238 -msgid "" -"The :meth:`!refresh` call displays a section of the pad in the rectangle " -"extending from coordinate (5,5) to coordinate (20,75) on the screen; the " -"upper left corner of the displayed section is coordinate (0,0) on the pad. " -"Beyond that difference, pads are exactly like ordinary windows and support " -"the same methods." -msgstr "" - -#: ../../howto/curses.rst:244 -msgid "" -"If you have multiple windows and pads on screen there is a more efficient " -"way to update the screen and prevent annoying screen flicker as each part of " -"the screen gets updated. :meth:`!refresh` actually does two things:" -msgstr "" - -#: ../../howto/curses.rst:249 -msgid "" -"Calls the :meth:`~curses.window.noutrefresh` method of each window to update " -"an underlying data structure representing the desired state of the screen." -msgstr "" - -#: ../../howto/curses.rst:252 -msgid "" -"Calls the function :func:`~curses.doupdate` function to change the physical " -"screen to match the desired state recorded in the data structure." -msgstr "" - -#: ../../howto/curses.rst:255 -msgid "" -"Instead you can call :meth:`!noutrefresh` on a number of windows to update " -"the data structure, and then call :func:`!doupdate` to update the screen." -msgstr "" - -#: ../../howto/curses.rst:261 -msgid "Displaying Text" -msgstr "" - -#: ../../howto/curses.rst:263 -msgid "" -"From a C programmer's point of view, curses may sometimes look like a twisty " -"maze of functions, all subtly different. For example, :c:func:`!addstr` " -"displays a string at the current cursor location in the ``stdscr`` window, " -"while :c:func:`!mvaddstr` moves to a given y,x coordinate first before " -"displaying the string. :c:func:`!waddstr` is just like :c:func:`!addstr`, " -"but allows specifying a window to use instead of using ``stdscr`` by " -"default. :c:func:`!mvwaddstr` allows specifying both a window and a " -"coordinate." -msgstr "" - -#: ../../howto/curses.rst:272 -msgid "" -"Fortunately the Python interface hides all these details. ``stdscr`` is a " -"window object like any other, and methods such as :meth:`~curses.window." -"addstr` accept multiple argument forms. Usually there are four different " -"forms." -msgstr "" - -#: ../../howto/curses.rst:278 -msgid "Form" -msgstr "" - -#: ../../howto/curses.rst:278 ../../howto/curses.rst:346 -msgid "Description" -msgstr "描述" - -#: ../../howto/curses.rst:280 -msgid "*str* or *ch*" -msgstr "*str* 或 *ch*" - -#: ../../howto/curses.rst:280 -msgid "Display the string *str* or character *ch* at the current position" -msgstr "" - -#: ../../howto/curses.rst:283 -msgid "*str* or *ch*, *attr*" -msgstr "" - -#: ../../howto/curses.rst:283 -msgid "" -"Display the string *str* or character *ch*, using attribute *attr* at the " -"current position" -msgstr "" - -#: ../../howto/curses.rst:287 -msgid "*y*, *x*, *str* or *ch*" -msgstr "*y*、*x*、*str* 或 *ch*" - -#: ../../howto/curses.rst:287 -msgid "Move to position *y,x* within the window, and display *str* or *ch*" -msgstr "" - -#: ../../howto/curses.rst:290 -msgid "*y*, *x*, *str* or *ch*, *attr*" -msgstr "*y*、*x*、*str* 或 *ch*、*attr*" - -#: ../../howto/curses.rst:290 -msgid "" -"Move to position *y,x* within the window, and display *str* or *ch*, using " -"attribute *attr*" -msgstr "" - -#: ../../howto/curses.rst:294 -msgid "" -"Attributes allow displaying text in highlighted forms such as boldface, " -"underline, reverse code, or in color. They'll be explained in more detail " -"in the next subsection." -msgstr "" - -#: ../../howto/curses.rst:299 -msgid "" -"The :meth:`~curses.window.addstr` method takes a Python string or bytestring " -"as the value to be displayed. The contents of bytestrings are sent to the " -"terminal as-is. Strings are encoded to bytes using the value of the " -"window's :attr:`~window.encoding` attribute; this defaults to the default " -"system encoding as returned by :func:`locale.getencoding`." -msgstr "" - -#: ../../howto/curses.rst:305 -msgid "" -"The :meth:`~curses.window.addch` methods take a character, which can be " -"either a string of length 1, a bytestring of length 1, or an integer." -msgstr "" - -#: ../../howto/curses.rst:308 -msgid "" -"Constants are provided for extension characters; these constants are " -"integers greater than 255. For example, :const:`ACS_PLMINUS` is a +/- " -"symbol, and :const:`ACS_ULCORNER` is the upper left corner of a box (handy " -"for drawing borders). You can also use the appropriate Unicode character." -msgstr "" - -#: ../../howto/curses.rst:314 -msgid "" -"Windows remember where the cursor was left after the last operation, so if " -"you leave out the *y,x* coordinates, the string or character will be " -"displayed wherever the last operation left off. You can also move the " -"cursor with the ``move(y,x)`` method. Because some terminals always display " -"a flashing cursor, you may want to ensure that the cursor is positioned in " -"some location where it won't be distracting; it can be confusing to have the " -"cursor blinking at some apparently random location." -msgstr "" - -#: ../../howto/curses.rst:322 -msgid "" -"If your application doesn't need a blinking cursor at all, you can call " -"``curs_set(False)`` to make it invisible. For compatibility with older " -"curses versions, there's a ``leaveok(bool)`` function that's a synonym for :" -"func:`~curses.curs_set`. When *bool* is true, the curses library will " -"attempt to suppress the flashing cursor, and you won't need to worry about " -"leaving it in odd locations." -msgstr "" - -#: ../../howto/curses.rst:331 -msgid "Attributes and Color" -msgstr "" - -#: ../../howto/curses.rst:333 -msgid "" -"Characters can be displayed in different ways. Status lines in a text-based " -"application are commonly shown in reverse video, or a text viewer may need " -"to highlight certain words. curses supports this by allowing you to specify " -"an attribute for each cell on the screen." -msgstr "" - -#: ../../howto/curses.rst:338 -msgid "" -"An attribute is an integer, each bit representing a different attribute. " -"You can try to display text with multiple attribute bits set, but curses " -"doesn't guarantee that all the possible combinations are available, or that " -"they're all visually distinct. That depends on the ability of the terminal " -"being used, so it's safest to stick to the most commonly available " -"attributes, listed here." -msgstr "" - -#: ../../howto/curses.rst:346 -msgid "Attribute" -msgstr "屬性" - -#: ../../howto/curses.rst:348 -msgid ":const:`A_BLINK`" -msgstr ":const:`A_BLINK`" - -#: ../../howto/curses.rst:348 -msgid "Blinking text" -msgstr "" - -#: ../../howto/curses.rst:350 -msgid ":const:`A_BOLD`" -msgstr ":const:`A_BOLD`" - -#: ../../howto/curses.rst:350 -msgid "Extra bright or bold text" -msgstr "" - -#: ../../howto/curses.rst:352 -msgid ":const:`A_DIM`" -msgstr ":const:`A_DIM`" - -#: ../../howto/curses.rst:352 -msgid "Half bright text" -msgstr "" - -#: ../../howto/curses.rst:354 -msgid ":const:`A_REVERSE`" -msgstr ":const:`A_REVERSE`" - -#: ../../howto/curses.rst:354 -msgid "Reverse-video text" -msgstr "" - -#: ../../howto/curses.rst:356 -msgid ":const:`A_STANDOUT`" -msgstr ":const:`A_STANDOUT`" - -#: ../../howto/curses.rst:356 -msgid "The best highlighting mode available" -msgstr "" - -#: ../../howto/curses.rst:358 -msgid ":const:`A_UNDERLINE`" -msgstr ":const:`A_UNDERLINE`" - -#: ../../howto/curses.rst:358 -msgid "Underlined text" -msgstr "" - -#: ../../howto/curses.rst:361 -msgid "" -"So, to display a reverse-video status line on the top line of the screen, " -"you could code::" -msgstr "" - -#: ../../howto/curses.rst:364 -msgid "" -"stdscr.addstr(0, 0, \"Current mode: Typing mode\",\n" -" curses.A_REVERSE)\n" -"stdscr.refresh()" -msgstr "" - -#: ../../howto/curses.rst:368 -msgid "" -"The curses library also supports color on those terminals that provide it. " -"The most common such terminal is probably the Linux console, followed by " -"color xterms." -msgstr "" - -#: ../../howto/curses.rst:372 -msgid "" -"To use color, you must call the :func:`~curses.start_color` function soon " -"after calling :func:`~curses.initscr`, to initialize the default color set " -"(the :func:`curses.wrapper` function does this automatically). Once that's " -"done, the :func:`~curses.has_colors` function returns TRUE if the terminal " -"in use can actually display color. (Note: curses uses the American spelling " -"'color', instead of the Canadian/British spelling 'colour'. If you're used " -"to the British spelling, you'll have to resign yourself to misspelling it " -"for the sake of these functions.)" -msgstr "" - -#: ../../howto/curses.rst:382 -msgid "" -"The curses library maintains a finite number of color pairs, containing a " -"foreground (or text) color and a background color. You can get the " -"attribute value corresponding to a color pair with the :func:`~curses." -"color_pair` function; this can be bitwise-OR'ed with other attributes such " -"as :const:`A_REVERSE`, but again, such combinations are not guaranteed to " -"work on all terminals." -msgstr "" - -#: ../../howto/curses.rst:389 -msgid "An example, which displays a line of text using color pair 1::" -msgstr "" - -#: ../../howto/curses.rst:391 -msgid "" -"stdscr.addstr(\"Pretty text\", curses.color_pair(1))\n" -"stdscr.refresh()" -msgstr "" - -#: ../../howto/curses.rst:394 -msgid "" -"As I said before, a color pair consists of a foreground and background " -"color. The ``init_pair(n, f, b)`` function changes the definition of color " -"pair *n*, to foreground color f and background color b. Color pair 0 is " -"hard-wired to white on black, and cannot be changed." -msgstr "" - -#: ../../howto/curses.rst:399 -msgid "" -"Colors are numbered, and :func:`start_color` initializes 8 basic colors when " -"it activates color mode. They are: 0:black, 1:red, 2:green, 3:yellow, 4:" -"blue, 5:magenta, 6:cyan, and 7:white. The :mod:`curses` module defines " -"named constants for each of these colors: :const:`curses.COLOR_BLACK`, :" -"const:`curses.COLOR_RED`, and so forth." -msgstr "" - -#: ../../howto/curses.rst:405 -msgid "" -"Let's put all this together. To change color 1 to red text on a white " -"background, you would call::" -msgstr "" - -#: ../../howto/curses.rst:408 -msgid "curses.init_pair(1, curses.COLOR_RED, curses.COLOR_WHITE)" -msgstr "curses.init_pair(1, curses.COLOR_RED, curses.COLOR_WHITE)" - -#: ../../howto/curses.rst:410 -msgid "" -"When you change a color pair, any text already displayed using that color " -"pair will change to the new colors. You can also display new text in this " -"color with::" -msgstr "" - -#: ../../howto/curses.rst:414 -msgid "stdscr.addstr(0,0, \"RED ALERT!\", curses.color_pair(1))" -msgstr "stdscr.addstr(0,0, \"RED ALERT!\", curses.color_pair(1))" - -#: ../../howto/curses.rst:416 -msgid "" -"Very fancy terminals can change the definitions of the actual colors to a " -"given RGB value. This lets you change color 1, which is usually red, to " -"purple or blue or any other color you like. Unfortunately, the Linux " -"console doesn't support this, so I'm unable to try it out, and can't provide " -"any examples. You can check if your terminal can do this by calling :func:" -"`~curses.can_change_color`, which returns ``True`` if the capability is " -"there. If you're lucky enough to have such a talented terminal, consult " -"your system's man pages for more information." -msgstr "" - -#: ../../howto/curses.rst:427 -msgid "User Input" -msgstr "使用者輸入" - -#: ../../howto/curses.rst:429 -msgid "" -"The C curses library offers only very simple input mechanisms. Python's :mod:" -"`curses` module adds a basic text-input widget. (Other libraries such as :" -"pypi:`Urwid` have more extensive collections of widgets.)" -msgstr "" - -#: ../../howto/curses.rst:433 -msgid "There are two methods for getting input from a window:" -msgstr "" - -#: ../../howto/curses.rst:435 -msgid "" -":meth:`~curses.window.getch` refreshes the screen and then waits for the " -"user to hit a key, displaying the key if :func:`~curses.echo` has been " -"called earlier. You can optionally specify a coordinate to which the cursor " -"should be moved before pausing." -msgstr "" - -#: ../../howto/curses.rst:440 -msgid "" -":meth:`~curses.window.getkey` does the same thing but converts the integer " -"to a string. Individual characters are returned as 1-character strings, and " -"special keys such as function keys return longer strings containing a key " -"name such as ``KEY_UP`` or ``^G``." -msgstr "" - -#: ../../howto/curses.rst:445 -msgid "" -"It's possible to not wait for the user using the :meth:`~curses.window." -"nodelay` window method. After ``nodelay(True)``, :meth:`!getch` and :meth:`!" -"getkey` for the window become non-blocking. To signal that no input is " -"ready, :meth:`!getch` returns ``curses.ERR`` (a value of -1) and :meth:`!" -"getkey` raises an exception. There's also a :func:`~curses.halfdelay` " -"function, which can be used to (in effect) set a timer on each :meth:`!" -"getch`; if no input becomes available within a specified delay (measured in " -"tenths of a second), curses raises an exception." -msgstr "" - -#: ../../howto/curses.rst:455 -msgid "" -"The :meth:`!getch` method returns an integer; if it's between 0 and 255, it " -"represents the ASCII code of the key pressed. Values greater than 255 are " -"special keys such as Page Up, Home, or the cursor keys. You can compare the " -"value returned to constants such as :const:`curses.KEY_PPAGE`, :const:" -"`curses.KEY_HOME`, or :const:`curses.KEY_LEFT`. The main loop of your " -"program may look something like this::" -msgstr "" - -#: ../../howto/curses.rst:462 -msgid "" -"while True:\n" -" c = stdscr.getch()\n" -" if c == ord('p'):\n" -" PrintDocument()\n" -" elif c == ord('q'):\n" -" break # Exit the while loop\n" -" elif c == curses.KEY_HOME:\n" -" x = y = 0" -msgstr "" - -#: ../../howto/curses.rst:471 -msgid "" -"The :mod:`curses.ascii` module supplies ASCII class membership functions " -"that take either integer or 1-character string arguments; these may be " -"useful in writing more readable tests for such loops. It also supplies " -"conversion functions that take either integer or 1-character-string " -"arguments and return the same type. For example, :func:`curses.ascii.ctrl` " -"returns the control character corresponding to its argument." -msgstr "" - -#: ../../howto/curses.rst:478 -msgid "" -"There's also a method to retrieve an entire string, :meth:`~curses.window." -"getstr`. It isn't used very often, because its functionality is quite " -"limited; the only editing keys available are the backspace key and the Enter " -"key, which terminates the string. It can optionally be limited to a fixed " -"number of characters. ::" -msgstr "" - -#: ../../howto/curses.rst:484 -msgid "" -"curses.echo() # Enable echoing of characters\n" -"\n" -"# Get a 15-character string, with the cursor on the top line\n" -"s = stdscr.getstr(0,0, 15)" -msgstr "" - -#: ../../howto/curses.rst:489 -msgid "" -"The :mod:`curses.textpad` module supplies a text box that supports an Emacs-" -"like set of keybindings. Various methods of the :class:`~curses.textpad." -"Textbox` class support editing with input validation and gathering the edit " -"results either with or without trailing spaces. Here's an example::" -msgstr "" - -#: ../../howto/curses.rst:495 -msgid "" -"import curses\n" -"from curses.textpad import Textbox, rectangle\n" -"\n" -"def main(stdscr):\n" -" stdscr.addstr(0, 0, \"Enter IM message: (hit Ctrl-G to send)\")\n" -"\n" -" editwin = curses.newwin(5,30, 2,1)\n" -" rectangle(stdscr, 1,0, 1+5+1, 1+30+1)\n" -" stdscr.refresh()\n" -"\n" -" box = Textbox(editwin)\n" -"\n" -" # Let the user edit until Ctrl-G is struck.\n" -" box.edit()\n" -"\n" -" # Get resulting contents\n" -" message = box.gather()" -msgstr "" - -#: ../../howto/curses.rst:513 -msgid "" -"See the library documentation on :mod:`curses.textpad` for more details." -msgstr "" - -#: ../../howto/curses.rst:517 -msgid "For More Information" -msgstr "" - -#: ../../howto/curses.rst:519 -msgid "" -"This HOWTO doesn't cover some advanced topics, such as reading the contents " -"of the screen or capturing mouse events from an xterm instance, but the " -"Python library page for the :mod:`curses` module is now reasonably " -"complete. You should browse it next." -msgstr "" - -#: ../../howto/curses.rst:524 -msgid "" -"If you're in doubt about the detailed behavior of the curses functions, " -"consult the manual pages for your curses implementation, whether it's " -"ncurses or a proprietary Unix vendor's. The manual pages will document any " -"quirks, and provide complete lists of all the functions, attributes, and :" -"ref:`ACS_\\* ` characters available to you." -msgstr "" - -#: ../../howto/curses.rst:531 -msgid "" -"Because the curses API is so large, some functions aren't supported in the " -"Python interface. Often this isn't because they're difficult to implement, " -"but because no one has needed them yet. Also, Python doesn't yet support " -"the menu library associated with ncurses. Patches adding support for these " -"would be welcome; see `the Python Developer's Guide `_ to learn more about submitting patches to Python." -msgstr "" - -#: ../../howto/curses.rst:539 -msgid "" -"`Writing Programs with NCURSES `_: a lengthy tutorial for C programmers." -msgstr "" - -#: ../../howto/curses.rst:541 -msgid "`The ncurses man page `_" -msgstr "`ncurses 使用者手冊 `_" - -#: ../../howto/curses.rst:542 -msgid "" -"`The ncurses FAQ `_" -msgstr "" -"`ncurses 問答集 `_" - -#: ../../howto/curses.rst:543 -msgid "" -"`\"Use curses... don't swear\" `_: video of a PyCon 2013 talk on controlling terminals using " -"curses or Urwid." -msgstr "" - -#: ../../howto/curses.rst:545 -msgid "" -"`\"Console Applications with Urwid\" `_: video of a PyCon CA 2012 talk demonstrating some " -"applications written using Urwid." -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-12-01 00:17+0000\n" +"PO-Revision-Date: 2018-05-23 14:36+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" + +#: ../../howto/curses.rst:5 +msgid "Curses Programming with Python" +msgstr "" + +#: ../../howto/curses.rst:0 +msgid "Author" +msgstr "作者" + +#: ../../howto/curses.rst:9 +msgid "A.M. Kuchling, Eric S. Raymond" +msgstr "A.M. Kuchling, Eric S. Raymond" + +#: ../../howto/curses.rst:0 +msgid "Release" +msgstr "發佈版本" + +#: ../../howto/curses.rst:10 +msgid "2.04" +msgstr "2.04" + +#: ../../howto/curses.rst:13 +msgid "Abstract" +msgstr "摘要" + +#: ../../howto/curses.rst:15 +msgid "" +"This document describes how to use the :mod:`curses` extension module to " +"control text-mode displays." +msgstr "" + +#: ../../howto/curses.rst:20 +msgid "What is curses?" +msgstr "" + +#: ../../howto/curses.rst:22 +msgid "" +"The curses library supplies a terminal-independent screen-painting and " +"keyboard-handling facility for text-based terminals; such terminals include " +"VT100s, the Linux console, and the simulated terminal provided by various " +"programs. Display terminals support various control codes to perform common " +"operations such as moving the cursor, scrolling the screen, and erasing " +"areas. Different terminals use widely differing codes, and often have their " +"own minor quirks." +msgstr "" + +#: ../../howto/curses.rst:30 +msgid "" +"In a world of graphical displays, one might ask \"why bother\"? It's true " +"that character-cell display terminals are an obsolete technology, but there " +"are niches in which being able to do fancy things with them are still " +"valuable. One niche is on small-footprint or embedded Unixes that don't run " +"an X server. Another is tools such as OS installers and kernel " +"configurators that may have to run before any graphical support is available." +msgstr "" + +#: ../../howto/curses.rst:38 +msgid "" +"The curses library provides fairly basic functionality, providing the " +"programmer with an abstraction of a display containing multiple non-" +"overlapping windows of text. The contents of a window can be changed in " +"various ways---adding text, erasing it, changing its appearance---and the " +"curses library will figure out what control codes need to be sent to the " +"terminal to produce the right output. curses doesn't provide many user-" +"interface concepts such as buttons, checkboxes, or dialogs; if you need such " +"features, consider a user interface library such as :pypi:`Urwid`." +msgstr "" + +#: ../../howto/curses.rst:48 +msgid "" +"The curses library was originally written for BSD Unix; the later System V " +"versions of Unix from AT&T added many enhancements and new functions. BSD " +"curses is no longer maintained, having been replaced by ncurses, which is an " +"open-source implementation of the AT&T interface. If you're using an open-" +"source Unix such as Linux or FreeBSD, your system almost certainly uses " +"ncurses. Since most current commercial Unix versions are based on System V " +"code, all the functions described here will probably be available. The " +"older versions of curses carried by some proprietary Unixes may not support " +"everything, though." +msgstr "" + +#: ../../howto/curses.rst:58 +msgid "" +"The Windows version of Python doesn't include the :mod:`curses` module. A " +"ported version called :pypi:`UniCurses` is available." +msgstr "" + +#: ../../howto/curses.rst:63 +msgid "The Python curses module" +msgstr "Python curses 模組" + +#: ../../howto/curses.rst:65 +msgid "" +"The Python module is a fairly simple wrapper over the C functions provided " +"by curses; if you're already familiar with curses programming in C, it's " +"really easy to transfer that knowledge to Python. The biggest difference is " +"that the Python interface makes things simpler by merging different C " +"functions such as :c:func:`!addstr`, :c:func:`!mvaddstr`, and :c:func:`!" +"mvwaddstr` into a single :meth:`~curses.window.addstr` method. You'll see " +"this covered in more detail later." +msgstr "" + +#: ../../howto/curses.rst:73 +msgid "" +"This HOWTO is an introduction to writing text-mode programs with curses and " +"Python. It doesn't attempt to be a complete guide to the curses API; for " +"that, see the Python library guide's section on ncurses, and the C manual " +"pages for ncurses. It will, however, give you the basic ideas." +msgstr "" + +#: ../../howto/curses.rst:80 +msgid "Starting and ending a curses application" +msgstr "" + +#: ../../howto/curses.rst:82 +msgid "" +"Before doing anything, curses must be initialized. This is done by calling " +"the :func:`~curses.initscr` function, which will determine the terminal " +"type, send any required setup codes to the terminal, and create various " +"internal data structures. If successful, :func:`!initscr` returns a window " +"object representing the entire screen; this is usually called ``stdscr`` " +"after the name of the corresponding C variable. ::" +msgstr "" + +#: ../../howto/curses.rst:90 +msgid "" +"import curses\n" +"stdscr = curses.initscr()" +msgstr "" +"import curses\n" +"stdscr = curses.initscr()" + +#: ../../howto/curses.rst:93 +msgid "" +"Usually curses applications turn off automatic echoing of keys to the " +"screen, in order to be able to read keys and only display them under certain " +"circumstances. This requires calling the :func:`~curses.noecho` function. ::" +msgstr "" + +#: ../../howto/curses.rst:98 +msgid "curses.noecho()" +msgstr "curses.noecho()" + +#: ../../howto/curses.rst:100 +msgid "" +"Applications will also commonly need to react to keys instantly, without " +"requiring the Enter key to be pressed; this is called cbreak mode, as " +"opposed to the usual buffered input mode. ::" +msgstr "" + +#: ../../howto/curses.rst:104 +msgid "curses.cbreak()" +msgstr "curses.cbreak()" + +#: ../../howto/curses.rst:106 +msgid "" +"Terminals usually return special keys, such as the cursor keys or navigation " +"keys such as Page Up and Home, as a multibyte escape sequence. While you " +"could write your application to expect such sequences and process them " +"accordingly, curses can do it for you, returning a special value such as :" +"const:`curses.KEY_LEFT`. To get curses to do the job, you'll have to enable " +"keypad mode. ::" +msgstr "" + +#: ../../howto/curses.rst:113 +msgid "stdscr.keypad(True)" +msgstr "stdscr.keypad(True)" + +#: ../../howto/curses.rst:115 +msgid "" +"Terminating a curses application is much easier than starting one. You'll " +"need to call::" +msgstr "" + +#: ../../howto/curses.rst:118 +msgid "" +"curses.nocbreak()\n" +"stdscr.keypad(False)\n" +"curses.echo()" +msgstr "" +"curses.nocbreak()\n" +"stdscr.keypad(False)\n" +"curses.echo()" + +#: ../../howto/curses.rst:122 +msgid "" +"to reverse the curses-friendly terminal settings. Then call the :func:" +"`~curses.endwin` function to restore the terminal to its original operating " +"mode. ::" +msgstr "" + +#: ../../howto/curses.rst:126 +msgid "curses.endwin()" +msgstr "curses.endwin()" + +#: ../../howto/curses.rst:128 +msgid "" +"A common problem when debugging a curses application is to get your terminal " +"messed up when the application dies without restoring the terminal to its " +"previous state. In Python this commonly happens when your code is buggy and " +"raises an uncaught exception. Keys are no longer echoed to the screen when " +"you type them, for example, which makes using the shell difficult." +msgstr "" + +#: ../../howto/curses.rst:134 +msgid "" +"In Python you can avoid these complications and make debugging much easier " +"by importing the :func:`curses.wrapper` function and using it like this::" +msgstr "" + +#: ../../howto/curses.rst:137 +msgid "" +"from curses import wrapper\n" +"\n" +"def main(stdscr):\n" +" # Clear screen\n" +" stdscr.clear()\n" +"\n" +" # This raises ZeroDivisionError when i == 10.\n" +" for i in range(0, 11):\n" +" v = i-10\n" +" stdscr.addstr(i, 0, '10 divided by {} is {}'.format(v, 10/v))\n" +"\n" +" stdscr.refresh()\n" +" stdscr.getkey()\n" +"\n" +"wrapper(main)" +msgstr "" + +#: ../../howto/curses.rst:153 +msgid "" +"The :func:`~curses.wrapper` function takes a callable object and does the " +"initializations described above, also initializing colors if color support " +"is present. :func:`!wrapper` then runs your provided callable. Once the " +"callable returns, :func:`!wrapper` will restore the original state of the " +"terminal. The callable is called inside a :keyword:`try`...\\ :keyword:" +"`except` that catches exceptions, restores the state of the terminal, and " +"then re-raises the exception. Therefore your terminal won't be left in a " +"funny state on exception and you'll be able to read the exception's message " +"and traceback." +msgstr "" + +#: ../../howto/curses.rst:165 +msgid "Windows and Pads" +msgstr "" + +#: ../../howto/curses.rst:167 +msgid "" +"Windows are the basic abstraction in curses. A window object represents a " +"rectangular area of the screen, and supports methods to display text, erase " +"it, allow the user to input strings, and so forth." +msgstr "" + +#: ../../howto/curses.rst:171 +msgid "" +"The ``stdscr`` object returned by the :func:`~curses.initscr` function is a " +"window object that covers the entire screen. Many programs may need only " +"this single window, but you might wish to divide the screen into smaller " +"windows, in order to redraw or clear them separately. The :func:`~curses." +"newwin` function creates a new window of a given size, returning the new " +"window object. ::" +msgstr "" + +#: ../../howto/curses.rst:178 +msgid "" +"begin_x = 20; begin_y = 7\n" +"height = 5; width = 40\n" +"win = curses.newwin(height, width, begin_y, begin_x)" +msgstr "" +"begin_x = 20; begin_y = 7\n" +"height = 5; width = 40\n" +"win = curses.newwin(height, width, begin_y, begin_x)" + +#: ../../howto/curses.rst:182 +msgid "" +"Note that the coordinate system used in curses is unusual. Coordinates are " +"always passed in the order *y,x*, and the top-left corner of a window is " +"coordinate (0,0). This breaks the normal convention for handling " +"coordinates where the *x* coordinate comes first. This is an unfortunate " +"difference from most other computer applications, but it's been part of " +"curses since it was first written, and it's too late to change things now." +msgstr "" + +#: ../../howto/curses.rst:190 +msgid "" +"Your application can determine the size of the screen by using the :data:" +"`curses.LINES` and :data:`curses.COLS` variables to obtain the *y* and *x* " +"sizes. Legal coordinates will then extend from ``(0,0)`` to ``(curses.LINES " +"- 1, curses.COLS - 1)``." +msgstr "" + +#: ../../howto/curses.rst:195 +msgid "" +"When you call a method to display or erase text, the effect doesn't " +"immediately show up on the display. Instead you must call the :meth:" +"`~curses.window.refresh` method of window objects to update the screen." +msgstr "" + +#: ../../howto/curses.rst:200 +msgid "" +"This is because curses was originally written with slow 300-baud terminal " +"connections in mind; with these terminals, minimizing the time required to " +"redraw the screen was very important. Instead curses accumulates changes to " +"the screen and displays them in the most efficient manner when you call :" +"meth:`!refresh`. For example, if your program displays some text in a " +"window and then clears the window, there's no need to send the original text " +"because they're never visible." +msgstr "" + +#: ../../howto/curses.rst:209 +msgid "" +"In practice, explicitly telling curses to redraw a window doesn't really " +"complicate programming with curses much. Most programs go into a flurry of " +"activity, and then pause waiting for a keypress or some other action on the " +"part of the user. All you have to do is to be sure that the screen has been " +"redrawn before pausing to wait for user input, by first calling :meth:`!" +"stdscr.refresh` or the :meth:`!refresh` method of some other relevant window." +msgstr "" + +#: ../../howto/curses.rst:217 +msgid "" +"A pad is a special case of a window; it can be larger than the actual " +"display screen, and only a portion of the pad displayed at a time. Creating " +"a pad requires the pad's height and width, while refreshing a pad requires " +"giving the coordinates of the on-screen area where a subsection of the pad " +"will be displayed. ::" +msgstr "" + +#: ../../howto/curses.rst:223 +msgid "" +"pad = curses.newpad(100, 100)\n" +"# These loops fill the pad with letters; addch() is\n" +"# explained in the next section\n" +"for y in range(0, 99):\n" +" for x in range(0, 99):\n" +" pad.addch(y,x, ord('a') + (x*x+y*y) % 26)\n" +"\n" +"# Displays a section of the pad in the middle of the screen.\n" +"# (0,0) : coordinate of upper-left corner of pad area to display.\n" +"# (5,5) : coordinate of upper-left corner of window area to be filled\n" +"# with pad content.\n" +"# (20, 75) : coordinate of lower-right corner of window area to be\n" +"# : filled with pad content.\n" +"pad.refresh( 0,0, 5,5, 20,75)" +msgstr "" + +#: ../../howto/curses.rst:238 +msgid "" +"The :meth:`!refresh` call displays a section of the pad in the rectangle " +"extending from coordinate (5,5) to coordinate (20,75) on the screen; the " +"upper left corner of the displayed section is coordinate (0,0) on the pad. " +"Beyond that difference, pads are exactly like ordinary windows and support " +"the same methods." +msgstr "" + +#: ../../howto/curses.rst:244 +msgid "" +"If you have multiple windows and pads on screen there is a more efficient " +"way to update the screen and prevent annoying screen flicker as each part of " +"the screen gets updated. :meth:`!refresh` actually does two things:" +msgstr "" + +#: ../../howto/curses.rst:249 +msgid "" +"Calls the :meth:`~curses.window.noutrefresh` method of each window to update " +"an underlying data structure representing the desired state of the screen." +msgstr "" + +#: ../../howto/curses.rst:252 +msgid "" +"Calls the function :func:`~curses.doupdate` function to change the physical " +"screen to match the desired state recorded in the data structure." +msgstr "" + +#: ../../howto/curses.rst:255 +msgid "" +"Instead you can call :meth:`!noutrefresh` on a number of windows to update " +"the data structure, and then call :func:`!doupdate` to update the screen." +msgstr "" + +#: ../../howto/curses.rst:261 +msgid "Displaying Text" +msgstr "" + +#: ../../howto/curses.rst:263 +msgid "" +"From a C programmer's point of view, curses may sometimes look like a twisty " +"maze of functions, all subtly different. For example, :c:func:`!addstr` " +"displays a string at the current cursor location in the ``stdscr`` window, " +"while :c:func:`!mvaddstr` moves to a given y,x coordinate first before " +"displaying the string. :c:func:`!waddstr` is just like :c:func:`!addstr`, " +"but allows specifying a window to use instead of using ``stdscr`` by " +"default. :c:func:`!mvwaddstr` allows specifying both a window and a " +"coordinate." +msgstr "" + +#: ../../howto/curses.rst:272 +msgid "" +"Fortunately the Python interface hides all these details. ``stdscr`` is a " +"window object like any other, and methods such as :meth:`~curses.window." +"addstr` accept multiple argument forms. Usually there are four different " +"forms." +msgstr "" + +#: ../../howto/curses.rst:278 +msgid "Form" +msgstr "" + +#: ../../howto/curses.rst:278 ../../howto/curses.rst:346 +msgid "Description" +msgstr "描述" + +#: ../../howto/curses.rst:280 +msgid "*str* or *ch*" +msgstr "*str* 或 *ch*" + +#: ../../howto/curses.rst:280 +msgid "Display the string *str* or character *ch* at the current position" +msgstr "" + +#: ../../howto/curses.rst:283 +msgid "*str* or *ch*, *attr*" +msgstr "" + +#: ../../howto/curses.rst:283 +msgid "" +"Display the string *str* or character *ch*, using attribute *attr* at the " +"current position" +msgstr "" + +#: ../../howto/curses.rst:287 +msgid "*y*, *x*, *str* or *ch*" +msgstr "*y*、*x*、*str* 或 *ch*" + +#: ../../howto/curses.rst:287 +msgid "Move to position *y,x* within the window, and display *str* or *ch*" +msgstr "" + +#: ../../howto/curses.rst:290 +msgid "*y*, *x*, *str* or *ch*, *attr*" +msgstr "*y*、*x*、*str* 或 *ch*、*attr*" + +#: ../../howto/curses.rst:290 +msgid "" +"Move to position *y,x* within the window, and display *str* or *ch*, using " +"attribute *attr*" +msgstr "" + +#: ../../howto/curses.rst:294 +msgid "" +"Attributes allow displaying text in highlighted forms such as boldface, " +"underline, reverse code, or in color. They'll be explained in more detail " +"in the next subsection." +msgstr "" + +#: ../../howto/curses.rst:299 +msgid "" +"The :meth:`~curses.window.addstr` method takes a Python string or bytestring " +"as the value to be displayed. The contents of bytestrings are sent to the " +"terminal as-is. Strings are encoded to bytes using the value of the " +"window's :attr:`~window.encoding` attribute; this defaults to the default " +"system encoding as returned by :func:`locale.getencoding`." +msgstr "" + +#: ../../howto/curses.rst:305 +msgid "" +"The :meth:`~curses.window.addch` methods take a character, which can be " +"either a string of length 1, a bytestring of length 1, or an integer." +msgstr "" + +#: ../../howto/curses.rst:308 +msgid "" +"Constants are provided for extension characters; these constants are " +"integers greater than 255. For example, :const:`ACS_PLMINUS` is a +/- " +"symbol, and :const:`ACS_ULCORNER` is the upper left corner of a box (handy " +"for drawing borders). You can also use the appropriate Unicode character." +msgstr "" + +#: ../../howto/curses.rst:314 +msgid "" +"Windows remember where the cursor was left after the last operation, so if " +"you leave out the *y,x* coordinates, the string or character will be " +"displayed wherever the last operation left off. You can also move the " +"cursor with the ``move(y,x)`` method. Because some terminals always display " +"a flashing cursor, you may want to ensure that the cursor is positioned in " +"some location where it won't be distracting; it can be confusing to have the " +"cursor blinking at some apparently random location." +msgstr "" + +#: ../../howto/curses.rst:322 +msgid "" +"If your application doesn't need a blinking cursor at all, you can call " +"``curs_set(False)`` to make it invisible. For compatibility with older " +"curses versions, there's a ``leaveok(bool)`` function that's a synonym for :" +"func:`~curses.curs_set`. When *bool* is true, the curses library will " +"attempt to suppress the flashing cursor, and you won't need to worry about " +"leaving it in odd locations." +msgstr "" + +#: ../../howto/curses.rst:331 +msgid "Attributes and Color" +msgstr "" + +#: ../../howto/curses.rst:333 +msgid "" +"Characters can be displayed in different ways. Status lines in a text-based " +"application are commonly shown in reverse video, or a text viewer may need " +"to highlight certain words. curses supports this by allowing you to specify " +"an attribute for each cell on the screen." +msgstr "" + +#: ../../howto/curses.rst:338 +msgid "" +"An attribute is an integer, each bit representing a different attribute. " +"You can try to display text with multiple attribute bits set, but curses " +"doesn't guarantee that all the possible combinations are available, or that " +"they're all visually distinct. That depends on the ability of the terminal " +"being used, so it's safest to stick to the most commonly available " +"attributes, listed here." +msgstr "" + +#: ../../howto/curses.rst:346 +msgid "Attribute" +msgstr "屬性" + +#: ../../howto/curses.rst:348 +msgid ":const:`A_BLINK`" +msgstr ":const:`A_BLINK`" + +#: ../../howto/curses.rst:348 +msgid "Blinking text" +msgstr "" + +#: ../../howto/curses.rst:350 +msgid ":const:`A_BOLD`" +msgstr ":const:`A_BOLD`" + +#: ../../howto/curses.rst:350 +msgid "Extra bright or bold text" +msgstr "" + +#: ../../howto/curses.rst:352 +msgid ":const:`A_DIM`" +msgstr ":const:`A_DIM`" + +#: ../../howto/curses.rst:352 +msgid "Half bright text" +msgstr "" + +#: ../../howto/curses.rst:354 +msgid ":const:`A_REVERSE`" +msgstr ":const:`A_REVERSE`" + +#: ../../howto/curses.rst:354 +msgid "Reverse-video text" +msgstr "" + +#: ../../howto/curses.rst:356 +msgid ":const:`A_STANDOUT`" +msgstr ":const:`A_STANDOUT`" + +#: ../../howto/curses.rst:356 +msgid "The best highlighting mode available" +msgstr "" + +#: ../../howto/curses.rst:358 +msgid ":const:`A_UNDERLINE`" +msgstr ":const:`A_UNDERLINE`" + +#: ../../howto/curses.rst:358 +msgid "Underlined text" +msgstr "" + +#: ../../howto/curses.rst:361 +msgid "" +"So, to display a reverse-video status line on the top line of the screen, " +"you could code::" +msgstr "" + +#: ../../howto/curses.rst:364 +msgid "" +"stdscr.addstr(0, 0, \"Current mode: Typing mode\",\n" +" curses.A_REVERSE)\n" +"stdscr.refresh()" +msgstr "" + +#: ../../howto/curses.rst:368 +msgid "" +"The curses library also supports color on those terminals that provide it. " +"The most common such terminal is probably the Linux console, followed by " +"color xterms." +msgstr "" + +#: ../../howto/curses.rst:372 +msgid "" +"To use color, you must call the :func:`~curses.start_color` function soon " +"after calling :func:`~curses.initscr`, to initialize the default color set " +"(the :func:`curses.wrapper` function does this automatically). Once that's " +"done, the :func:`~curses.has_colors` function returns TRUE if the terminal " +"in use can actually display color. (Note: curses uses the American spelling " +"'color', instead of the Canadian/British spelling 'colour'. If you're used " +"to the British spelling, you'll have to resign yourself to misspelling it " +"for the sake of these functions.)" +msgstr "" + +#: ../../howto/curses.rst:382 +msgid "" +"The curses library maintains a finite number of color pairs, containing a " +"foreground (or text) color and a background color. You can get the " +"attribute value corresponding to a color pair with the :func:`~curses." +"color_pair` function; this can be bitwise-OR'ed with other attributes such " +"as :const:`A_REVERSE`, but again, such combinations are not guaranteed to " +"work on all terminals." +msgstr "" + +#: ../../howto/curses.rst:389 +msgid "An example, which displays a line of text using color pair 1::" +msgstr "" + +#: ../../howto/curses.rst:391 +msgid "" +"stdscr.addstr(\"Pretty text\", curses.color_pair(1))\n" +"stdscr.refresh()" +msgstr "" + +#: ../../howto/curses.rst:394 +msgid "" +"As I said before, a color pair consists of a foreground and background " +"color. The ``init_pair(n, f, b)`` function changes the definition of color " +"pair *n*, to foreground color f and background color b. Color pair 0 is " +"hard-wired to white on black, and cannot be changed." +msgstr "" + +#: ../../howto/curses.rst:399 +msgid "" +"Colors are numbered, and :func:`start_color` initializes 8 basic colors when " +"it activates color mode. They are: 0:black, 1:red, 2:green, 3:yellow, 4:" +"blue, 5:magenta, 6:cyan, and 7:white. The :mod:`curses` module defines " +"named constants for each of these colors: :const:`curses.COLOR_BLACK`, :" +"const:`curses.COLOR_RED`, and so forth." +msgstr "" + +#: ../../howto/curses.rst:405 +msgid "" +"Let's put all this together. To change color 1 to red text on a white " +"background, you would call::" +msgstr "" + +#: ../../howto/curses.rst:408 +msgid "curses.init_pair(1, curses.COLOR_RED, curses.COLOR_WHITE)" +msgstr "curses.init_pair(1, curses.COLOR_RED, curses.COLOR_WHITE)" + +#: ../../howto/curses.rst:410 +msgid "" +"When you change a color pair, any text already displayed using that color " +"pair will change to the new colors. You can also display new text in this " +"color with::" +msgstr "" + +#: ../../howto/curses.rst:414 +msgid "stdscr.addstr(0,0, \"RED ALERT!\", curses.color_pair(1))" +msgstr "stdscr.addstr(0,0, \"RED ALERT!\", curses.color_pair(1))" + +#: ../../howto/curses.rst:416 +msgid "" +"Very fancy terminals can change the definitions of the actual colors to a " +"given RGB value. This lets you change color 1, which is usually red, to " +"purple or blue or any other color you like. Unfortunately, the Linux " +"console doesn't support this, so I'm unable to try it out, and can't provide " +"any examples. You can check if your terminal can do this by calling :func:" +"`~curses.can_change_color`, which returns ``True`` if the capability is " +"there. If you're lucky enough to have such a talented terminal, consult " +"your system's man pages for more information." +msgstr "" + +#: ../../howto/curses.rst:427 +msgid "User Input" +msgstr "使用者輸入" + +#: ../../howto/curses.rst:429 +msgid "" +"The C curses library offers only very simple input mechanisms. Python's :mod:" +"`curses` module adds a basic text-input widget. (Other libraries such as :" +"pypi:`Urwid` have more extensive collections of widgets.)" +msgstr "" + +#: ../../howto/curses.rst:433 +msgid "There are two methods for getting input from a window:" +msgstr "" + +#: ../../howto/curses.rst:435 +msgid "" +":meth:`~curses.window.getch` refreshes the screen and then waits for the " +"user to hit a key, displaying the key if :func:`~curses.echo` has been " +"called earlier. You can optionally specify a coordinate to which the cursor " +"should be moved before pausing." +msgstr "" + +#: ../../howto/curses.rst:440 +msgid "" +":meth:`~curses.window.getkey` does the same thing but converts the integer " +"to a string. Individual characters are returned as 1-character strings, and " +"special keys such as function keys return longer strings containing a key " +"name such as ``KEY_UP`` or ``^G``." +msgstr "" + +#: ../../howto/curses.rst:445 +msgid "" +"It's possible to not wait for the user using the :meth:`~curses.window." +"nodelay` window method. After ``nodelay(True)``, :meth:`!getch` and :meth:`!" +"getkey` for the window become non-blocking. To signal that no input is " +"ready, :meth:`!getch` returns ``curses.ERR`` (a value of -1) and :meth:`!" +"getkey` raises an exception. There's also a :func:`~curses.halfdelay` " +"function, which can be used to (in effect) set a timer on each :meth:`!" +"getch`; if no input becomes available within a specified delay (measured in " +"tenths of a second), curses raises an exception." +msgstr "" + +#: ../../howto/curses.rst:455 +msgid "" +"The :meth:`!getch` method returns an integer; if it's between 0 and 255, it " +"represents the ASCII code of the key pressed. Values greater than 255 are " +"special keys such as Page Up, Home, or the cursor keys. You can compare the " +"value returned to constants such as :const:`curses.KEY_PPAGE`, :const:" +"`curses.KEY_HOME`, or :const:`curses.KEY_LEFT`. The main loop of your " +"program may look something like this::" +msgstr "" + +#: ../../howto/curses.rst:462 +msgid "" +"while True:\n" +" c = stdscr.getch()\n" +" if c == ord('p'):\n" +" PrintDocument()\n" +" elif c == ord('q'):\n" +" break # Exit the while loop\n" +" elif c == curses.KEY_HOME:\n" +" x = y = 0" +msgstr "" + +#: ../../howto/curses.rst:471 +msgid "" +"The :mod:`curses.ascii` module supplies ASCII class membership functions " +"that take either integer or 1-character string arguments; these may be " +"useful in writing more readable tests for such loops. It also supplies " +"conversion functions that take either integer or 1-character-string " +"arguments and return the same type. For example, :func:`curses.ascii.ctrl` " +"returns the control character corresponding to its argument." +msgstr "" + +#: ../../howto/curses.rst:478 +msgid "" +"There's also a method to retrieve an entire string, :meth:`~curses.window." +"getstr`. It isn't used very often, because its functionality is quite " +"limited; the only editing keys available are the backspace key and the Enter " +"key, which terminates the string. It can optionally be limited to a fixed " +"number of characters. ::" +msgstr "" + +#: ../../howto/curses.rst:484 +msgid "" +"curses.echo() # Enable echoing of characters\n" +"\n" +"# Get a 15-character string, with the cursor on the top line\n" +"s = stdscr.getstr(0,0, 15)" +msgstr "" + +#: ../../howto/curses.rst:489 +msgid "" +"The :mod:`curses.textpad` module supplies a text box that supports an Emacs-" +"like set of keybindings. Various methods of the :class:`~curses.textpad." +"Textbox` class support editing with input validation and gathering the edit " +"results either with or without trailing spaces. Here's an example::" +msgstr "" + +#: ../../howto/curses.rst:495 +msgid "" +"import curses\n" +"from curses.textpad import Textbox, rectangle\n" +"\n" +"def main(stdscr):\n" +" stdscr.addstr(0, 0, \"Enter IM message: (hit Ctrl-G to send)\")\n" +"\n" +" editwin = curses.newwin(5,30, 2,1)\n" +" rectangle(stdscr, 1,0, 1+5+1, 1+30+1)\n" +" stdscr.refresh()\n" +"\n" +" box = Textbox(editwin)\n" +"\n" +" # Let the user edit until Ctrl-G is struck.\n" +" box.edit()\n" +"\n" +" # Get resulting contents\n" +" message = box.gather()" +msgstr "" + +#: ../../howto/curses.rst:513 +msgid "" +"See the library documentation on :mod:`curses.textpad` for more details." +msgstr "" + +#: ../../howto/curses.rst:517 +msgid "For More Information" +msgstr "" + +#: ../../howto/curses.rst:519 +msgid "" +"This HOWTO doesn't cover some advanced topics, such as reading the contents " +"of the screen or capturing mouse events from an xterm instance, but the " +"Python library page for the :mod:`curses` module is now reasonably " +"complete. You should browse it next." +msgstr "" + +#: ../../howto/curses.rst:524 +msgid "" +"If you're in doubt about the detailed behavior of the curses functions, " +"consult the manual pages for your curses implementation, whether it's " +"ncurses or a proprietary Unix vendor's. The manual pages will document any " +"quirks, and provide complete lists of all the functions, attributes, and :" +"ref:`ACS_\\* ` characters available to you." +msgstr "" + +#: ../../howto/curses.rst:531 +msgid "" +"Because the curses API is so large, some functions aren't supported in the " +"Python interface. Often this isn't because they're difficult to implement, " +"but because no one has needed them yet. Also, Python doesn't yet support " +"the menu library associated with ncurses. Patches adding support for these " +"would be welcome; see `the Python Developer's Guide `_ to learn more about submitting patches to Python." +msgstr "" + +#: ../../howto/curses.rst:539 +msgid "" +"`Writing Programs with NCURSES `_: a lengthy tutorial for C programmers." +msgstr "" + +#: ../../howto/curses.rst:541 +msgid "`The ncurses man page `_" +msgstr "`ncurses 使用者手冊 `_" + +#: ../../howto/curses.rst:542 +msgid "" +"`The ncurses FAQ `_" +msgstr "" +"`ncurses 問答集 `_" + +#: ../../howto/curses.rst:543 +msgid "" +"`\"Use curses... don't swear\" `_: video of a PyCon 2013 talk on controlling terminals using " +"curses or Urwid." +msgstr "" + +#: ../../howto/curses.rst:545 +msgid "" +"`\"Console Applications with Urwid\" `_: video of a PyCon CA 2012 talk demonstrating some " +"applications written using Urwid." +msgstr "" diff --git a/howto/descriptor.po b/howto/descriptor.po index a706a11aca..1e63589612 100644 --- a/howto/descriptor.po +++ b/howto/descriptor.po @@ -1,2068 +1,2068 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Leon H., 2017 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-09 05:11+0800\n" -"PO-Revision-Date: 2018-05-23 14:36+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" - -#: ../../howto/descriptor.rst:5 -msgid "Descriptor Guide" -msgstr "描述器 (Descriptor) 指南" - -#: ../../howto/descriptor.rst:0 -msgid "Author" -msgstr "作者" - -#: ../../howto/descriptor.rst:7 -msgid "Raymond Hettinger" -msgstr "Raymond Hettinger" - -#: ../../howto/descriptor.rst:0 -msgid "Contact" -msgstr "聯絡方式" - -#: ../../howto/descriptor.rst:8 -msgid "" -msgstr "" - -#: ../../howto/descriptor.rst:11 -msgid "Contents" -msgstr "目錄" - -#: ../../howto/descriptor.rst:13 -msgid "" -":term:`Descriptors ` let objects customize attribute lookup, " -"storage, and deletion." -msgstr ":term:`描述器 `\\ 讓物件自訂屬性能夠被查找、儲存和刪除。" - -#: ../../howto/descriptor.rst:16 -msgid "This guide has four major sections:" -msgstr "此指南有四個主要章節：" - -#: ../../howto/descriptor.rst:18 -msgid "" -"The \"primer\" gives a basic overview, moving gently from simple examples, " -"adding one feature at a time. Start here if you're new to descriptors." -msgstr "" - -#: ../../howto/descriptor.rst:21 -msgid "" -"The second section shows a complete, practical descriptor example. If you " -"already know the basics, start there." -msgstr "" - -#: ../../howto/descriptor.rst:24 -msgid "" -"The third section provides a more technical tutorial that goes into the " -"detailed mechanics of how descriptors work. Most people don't need this " -"level of detail." -msgstr "" - -#: ../../howto/descriptor.rst:28 -msgid "" -"The last section has pure Python equivalents for built-in descriptors that " -"are written in C. Read this if you're curious about how functions turn into " -"bound methods or about the implementation of common tools " -"like :func:`classmethod`, :func:`staticmethod`, :func:`property`, " -"and :term:`__slots__`." -msgstr "" - -#: ../../howto/descriptor.rst:36 -msgid "Primer" -msgstr "" - -#: ../../howto/descriptor.rst:38 -msgid "" -"In this primer, we start with the most basic possible example and then we'll " -"add new capabilities one by one." -msgstr "" - -#: ../../howto/descriptor.rst:43 -msgid "Simple example: A descriptor that returns a constant" -msgstr "" - -#: ../../howto/descriptor.rst:45 -msgid "" -"The :class:`!Ten` class is a descriptor whose :meth:`~object.__get__` method " -"always returns the constant ``10``:" -msgstr "" - -#: ../../howto/descriptor.rst:48 -msgid "" -"class Ten:\n" -" def __get__(self, obj, objtype=None):\n" -" return 10" -msgstr "" -"class Ten:\n" -" def __get__(self, obj, objtype=None):\n" -" return 10" - -#: ../../howto/descriptor.rst:54 -msgid "" -"To use the descriptor, it must be stored as a class variable in another " -"class:" -msgstr "" - -#: ../../howto/descriptor.rst:56 -msgid "" -"class A:\n" -" x = 5 # Regular class attribute\n" -" y = Ten() # Descriptor instance" -msgstr "" - -#: ../../howto/descriptor.rst:62 -msgid "" -"An interactive session shows the difference between normal attribute lookup " -"and descriptor lookup:" -msgstr "" - -#: ../../howto/descriptor.rst:65 -msgid "" -">>> a = A() # Make an instance of class A\n" -">>> a.x # Normal attribute lookup\n" -"5\n" -">>> a.y # Descriptor lookup\n" -"10" -msgstr "" - -#: ../../howto/descriptor.rst:73 -msgid "" -"In the ``a.x`` attribute lookup, the dot operator finds ``'x': 5`` in the " -"class dictionary. In the ``a.y`` lookup, the dot operator finds a " -"descriptor instance, recognized by its ``__get__`` method. Calling that " -"method returns ``10``." -msgstr "" - -#: ../../howto/descriptor.rst:78 -msgid "" -"Note that the value ``10`` is not stored in either the class dictionary or " -"the instance dictionary. Instead, the value ``10`` is computed on demand." -msgstr "" - -#: ../../howto/descriptor.rst:81 -msgid "" -"This example shows how a simple descriptor works, but it isn't very useful. " -"For retrieving constants, normal attribute lookup would be better." -msgstr "" - -#: ../../howto/descriptor.rst:84 -msgid "" -"In the next section, we'll create something more useful, a dynamic lookup." -msgstr "" - -#: ../../howto/descriptor.rst:88 -msgid "Dynamic lookups" -msgstr "" - -#: ../../howto/descriptor.rst:90 -msgid "" -"Interesting descriptors typically run computations instead of returning " -"constants:" -msgstr "" - -#: ../../howto/descriptor.rst:93 -msgid "" -"import os\n" -"\n" -"class DirectorySize:\n" -"\n" -" def __get__(self, obj, objtype=None):\n" -" return len(os.listdir(obj.dirname))\n" -"\n" -"class Directory:\n" -"\n" -" size = DirectorySize() # Descriptor instance\n" -"\n" -" def __init__(self, dirname):\n" -" self.dirname = dirname # Regular instance attribute" -msgstr "" - -#: ../../howto/descriptor.rst:109 -msgid "" -"An interactive session shows that the lookup is dynamic — it computes " -"different, updated answers each time::" -msgstr "" - -#: ../../howto/descriptor.rst:112 -msgid "" -">>> s = Directory('songs')\n" -">>> g = Directory('games')\n" -">>> s.size # The songs directory has twenty " -"files\n" -"20\n" -">>> g.size # The games directory has three " -"files\n" -"3\n" -">>> os.remove('games/chess') # Delete a game\n" -">>> g.size # File count is automatically " -"updated\n" -"2" -msgstr "" - -#: ../../howto/descriptor.rst:122 -msgid "" -"Besides showing how descriptors can run computations, this example also " -"reveals the purpose of the parameters to :meth:`~object.__get__`. The " -"*self* parameter is *size*, an instance of *DirectorySize*. The *obj* " -"parameter is either *g* or *s*, an instance of *Directory*. It is the *obj* " -"parameter that lets the :meth:`~object.__get__` method learn the target " -"directory. The *objtype* parameter is the class *Directory*." -msgstr "" - -#: ../../howto/descriptor.rst:131 -msgid "Managed attributes" -msgstr "" - -#: ../../howto/descriptor.rst:133 -msgid "" -"A popular use for descriptors is managing access to instance data. The " -"descriptor is assigned to a public attribute in the class dictionary while " -"the actual data is stored as a private attribute in the instance " -"dictionary. The descriptor's :meth:`~object.__get__` " -"and :meth:`~object.__set__` methods are triggered when the public attribute " -"is accessed." -msgstr "" - -#: ../../howto/descriptor.rst:139 -msgid "" -"In the following example, *age* is the public attribute and *_age* is the " -"private attribute. When the public attribute is accessed, the descriptor " -"logs the lookup or update:" -msgstr "" - -#: ../../howto/descriptor.rst:143 -msgid "" -"import logging\n" -"\n" -"logging.basicConfig(level=logging.INFO)\n" -"\n" -"class LoggedAgeAccess:\n" -"\n" -" def __get__(self, obj, objtype=None):\n" -" value = obj._age\n" -" logging.info('Accessing %r giving %r', 'age', value)\n" -" return value\n" -"\n" -" def __set__(self, obj, value):\n" -" logging.info('Updating %r to %r', 'age', value)\n" -" obj._age = value\n" -"\n" -"class Person:\n" -"\n" -" age = LoggedAgeAccess() # Descriptor instance\n" -"\n" -" def __init__(self, name, age):\n" -" self.name = name # Regular instance attribute\n" -" self.age = age # Calls __set__()\n" -"\n" -" def birthday(self):\n" -" self.age += 1 # Calls both __get__() and __set__()" -msgstr "" - -#: ../../howto/descriptor.rst:172 -msgid "" -"An interactive session shows that all access to the managed attribute *age* " -"is logged, but that the regular attribute *name* is not logged:" -msgstr "" - -#: ../../howto/descriptor.rst:181 -msgid "" -">>> mary = Person('Mary M', 30) # The initial age update is logged\n" -"INFO:root:Updating 'age' to 30\n" -">>> dave = Person('David D', 40)\n" -"INFO:root:Updating 'age' to 40\n" -"\n" -">>> vars(mary) # The actual data is in a private " -"attribute\n" -"{'name': 'Mary M', '_age': 30}\n" -">>> vars(dave)\n" -"{'name': 'David D', '_age': 40}\n" -"\n" -">>> mary.age # Access the data and log the " -"lookup\n" -"INFO:root:Accessing 'age' giving 30\n" -"30\n" -">>> mary.birthday() # Updates are logged as well\n" -"INFO:root:Accessing 'age' giving 30\n" -"INFO:root:Updating 'age' to 31\n" -"\n" -">>> dave.name # Regular attribute lookup isn't " -"logged\n" -"'David D'\n" -">>> dave.age # Only the managed attribute is " -"logged\n" -"INFO:root:Accessing 'age' giving 40\n" -"40" -msgstr "" - -#: ../../howto/descriptor.rst:206 -msgid "" -"One major issue with this example is that the private name *_age* is " -"hardwired in the *LoggedAgeAccess* class. That means that each instance can " -"only have one logged attribute and that its name is unchangeable. In the " -"next example, we'll fix that problem." -msgstr "" - -#: ../../howto/descriptor.rst:213 -msgid "Customized names" -msgstr "" - -#: ../../howto/descriptor.rst:215 -msgid "" -"When a class uses descriptors, it can inform each descriptor about which " -"variable name was used." -msgstr "" - -#: ../../howto/descriptor.rst:218 -msgid "" -"In this example, the :class:`!Person` class has two descriptor instances, " -"*name* and *age*. When the :class:`!Person` class is defined, it makes a " -"callback to :meth:`~object.__set_name__` in *LoggedAccess* so that the field " -"names can be recorded, giving each descriptor its own *public_name* and " -"*private_name*:" -msgstr "" - -#: ../../howto/descriptor.rst:223 -msgid "" -"import logging\n" -"\n" -"logging.basicConfig(level=logging.INFO)\n" -"\n" -"class LoggedAccess:\n" -"\n" -" def __set_name__(self, owner, name):\n" -" self.public_name = name\n" -" self.private_name = '_' + name\n" -"\n" -" def __get__(self, obj, objtype=None):\n" -" value = getattr(obj, self.private_name)\n" -" logging.info('Accessing %r giving %r', self.public_name, value)\n" -" return value\n" -"\n" -" def __set__(self, obj, value):\n" -" logging.info('Updating %r to %r', self.public_name, value)\n" -" setattr(obj, self.private_name, value)\n" -"\n" -"class Person:\n" -"\n" -" name = LoggedAccess() # First descriptor instance\n" -" age = LoggedAccess() # Second descriptor instance\n" -"\n" -" def __init__(self, name, age):\n" -" self.name = name # Calls the first descriptor\n" -" self.age = age # Calls the second descriptor\n" -"\n" -" def birthday(self):\n" -" self.age += 1" -msgstr "" - -#: ../../howto/descriptor.rst:256 -msgid "" -"An interactive session shows that the :class:`!Person` class has " -"called :meth:`~object.__set_name__` so that the field names would be " -"recorded. Here we call :func:`vars` to look up the descriptor without " -"triggering it:" -msgstr "" - -#: ../../howto/descriptor.rst:260 -msgid "" -">>> vars(vars(Person)['name'])\n" -"{'public_name': 'name', 'private_name': '_name'}\n" -">>> vars(vars(Person)['age'])\n" -"{'public_name': 'age', 'private_name': '_age'}" -msgstr "" -">>> vars(vars(Person)['name'])\n" -"{'public_name': 'name', 'private_name': '_name'}\n" -">>> vars(vars(Person)['age'])\n" -"{'public_name': 'age', 'private_name': '_age'}" - -#: ../../howto/descriptor.rst:267 -msgid "The new class now logs access to both *name* and *age*:" -msgstr "" - -#: ../../howto/descriptor.rst:275 -msgid "" -">>> pete = Person('Peter P', 10)\n" -"INFO:root:Updating 'name' to 'Peter P'\n" -"INFO:root:Updating 'age' to 10\n" -">>> kate = Person('Catherine C', 20)\n" -"INFO:root:Updating 'name' to 'Catherine C'\n" -"INFO:root:Updating 'age' to 20" -msgstr "" -">>> pete = Person('Peter P', 10)\n" -"INFO:root:Updating 'name' to 'Peter P'\n" -"INFO:root:Updating 'age' to 10\n" -">>> kate = Person('Catherine C', 20)\n" -"INFO:root:Updating 'name' to 'Catherine C'\n" -"INFO:root:Updating 'age' to 20" - -#: ../../howto/descriptor.rst:284 -msgid "The two *Person* instances contain only the private names:" -msgstr "" - -#: ../../howto/descriptor.rst:286 -msgid "" -">>> vars(pete)\n" -"{'_name': 'Peter P', '_age': 10}\n" -">>> vars(kate)\n" -"{'_name': 'Catherine C', '_age': 20}" -msgstr "" -">>> vars(pete)\n" -"{'_name': 'Peter P', '_age': 10}\n" -">>> vars(kate)\n" -"{'_name': 'Catherine C', '_age': 20}" - -#: ../../howto/descriptor.rst:295 -msgid "Closing thoughts" -msgstr "" - -#: ../../howto/descriptor.rst:297 -msgid "" -"A :term:`descriptor` is what we call any object that " -"defines :meth:`~object.__get__`, :meth:`~object.__set__`, " -"or :meth:`~object.__delete__`." -msgstr "" - -#: ../../howto/descriptor.rst:300 -msgid "" -"Optionally, descriptors can have a :meth:`~object.__set_name__` method. " -"This is only used in cases where a descriptor needs to know either the class " -"where it was created or the name of class variable it was assigned to. " -"(This method, if present, is called even if the class is not a descriptor.)" -msgstr "" - -#: ../../howto/descriptor.rst:305 -msgid "" -"Descriptors get invoked by the dot operator during attribute lookup. If a " -"descriptor is accessed indirectly with ``vars(some_class)" -"[descriptor_name]``, the descriptor instance is returned without invoking it." -msgstr "" - -#: ../../howto/descriptor.rst:309 -msgid "" -"Descriptors only work when used as class variables. When put in instances, " -"they have no effect." -msgstr "" - -#: ../../howto/descriptor.rst:312 -msgid "" -"The main motivation for descriptors is to provide a hook allowing objects " -"stored in class variables to control what happens during attribute lookup." -msgstr "" - -#: ../../howto/descriptor.rst:315 -msgid "" -"Traditionally, the calling class controls what happens during lookup. " -"Descriptors invert that relationship and allow the data being looked-up to " -"have a say in the matter." -msgstr "" - -#: ../../howto/descriptor.rst:319 -msgid "" -"Descriptors are used throughout the language. It is how functions turn into " -"bound methods. Common tools " -"like :func:`classmethod`, :func:`staticmethod`, :func:`property`, " -"and :func:`functools.cached_property` are all implemented as descriptors." -msgstr "" - -#: ../../howto/descriptor.rst:326 -msgid "Complete Practical Example" -msgstr "" - -#: ../../howto/descriptor.rst:328 -msgid "" -"In this example, we create a practical and powerful tool for locating " -"notoriously hard to find data corruption bugs." -msgstr "" - -#: ../../howto/descriptor.rst:333 -msgid "Validator class" -msgstr "" - -#: ../../howto/descriptor.rst:335 -msgid "" -"A validator is a descriptor for managed attribute access. Prior to storing " -"any data, it verifies that the new value meets various type and range " -"restrictions. If those restrictions aren't met, it raises an exception to " -"prevent data corruption at its source." -msgstr "" - -#: ../../howto/descriptor.rst:340 -msgid "" -"This :class:`!Validator` class is both an :term:`abstract base class` and a " -"managed attribute descriptor:" -msgstr "" - -#: ../../howto/descriptor.rst:343 -msgid "" -"from abc import ABC, abstractmethod\n" -"\n" -"class Validator(ABC):\n" -"\n" -" def __set_name__(self, owner, name):\n" -" self.private_name = '_' + name\n" -"\n" -" def __get__(self, obj, objtype=None):\n" -" return getattr(obj, self.private_name)\n" -"\n" -" def __set__(self, obj, value):\n" -" self.validate(value)\n" -" setattr(obj, self.private_name, value)\n" -"\n" -" @abstractmethod\n" -" def validate(self, value):\n" -" pass" -msgstr "" -"from abc import ABC, abstractmethod\n" -"\n" -"class Validator(ABC):\n" -"\n" -" def __set_name__(self, owner, name):\n" -" self.private_name = '_' + name\n" -"\n" -" def __get__(self, obj, objtype=None):\n" -" return getattr(obj, self.private_name)\n" -"\n" -" def __set__(self, obj, value):\n" -" self.validate(value)\n" -" setattr(obj, self.private_name, value)\n" -"\n" -" @abstractmethod\n" -" def validate(self, value):\n" -" pass" - -#: ../../howto/descriptor.rst:363 -msgid "" -"Custom validators need to inherit from :class:`!Validator` and must supply " -"a :meth:`!validate` method to test various restrictions as needed." -msgstr "" - -#: ../../howto/descriptor.rst:368 -msgid "Custom validators" -msgstr "" - -#: ../../howto/descriptor.rst:370 -msgid "Here are three practical data validation utilities:" -msgstr "" - -#: ../../howto/descriptor.rst:372 -msgid "" -":class:`!OneOf` verifies that a value is one of a restricted set of options." -msgstr "" - -#: ../../howto/descriptor.rst:374 -msgid "" -":class:`!Number` verifies that a value is either an :class:`int` " -"or :class:`float`. Optionally, it verifies that a value is between a given " -"minimum or maximum." -msgstr "" - -#: ../../howto/descriptor.rst:378 -msgid "" -":class:`!String` verifies that a value is a :class:`str`. Optionally, it " -"validates a given minimum or maximum length. It can validate a user-defined " -"`predicate `_ " -"as well." -msgstr "" - -#: ../../howto/descriptor.rst:383 -msgid "" -"class OneOf(Validator):\n" -"\n" -" def __init__(self, *options):\n" -" self.options = set(options)\n" -"\n" -" def validate(self, value):\n" -" if value not in self.options:\n" -" raise ValueError(\n" -" f'Expected {value!r} to be one of {self.options!r}'\n" -" )\n" -"\n" -"class Number(Validator):\n" -"\n" -" def __init__(self, minvalue=None, maxvalue=None):\n" -" self.minvalue = minvalue\n" -" self.maxvalue = maxvalue\n" -"\n" -" def validate(self, value):\n" -" if not isinstance(value, (int, float)):\n" -" raise TypeError(f'Expected {value!r} to be an int or float')\n" -" if self.minvalue is not None and value < self.minvalue:\n" -" raise ValueError(\n" -" f'Expected {value!r} to be at least {self.minvalue!r}'\n" -" )\n" -" if self.maxvalue is not None and value > self.maxvalue:\n" -" raise ValueError(\n" -" f'Expected {value!r} to be no more than {self.maxvalue!r}'\n" -" )\n" -"\n" -"class String(Validator):\n" -"\n" -" def __init__(self, minsize=None, maxsize=None, predicate=None):\n" -" self.minsize = minsize\n" -" self.maxsize = maxsize\n" -" self.predicate = predicate\n" -"\n" -" def validate(self, value):\n" -" if not isinstance(value, str):\n" -" raise TypeError(f'Expected {value!r} to be a str')\n" -" if self.minsize is not None and len(value) < self.minsize:\n" -" raise ValueError(\n" -" f'Expected {value!r} to be no smaller than {self.minsize!" -"r}'\n" -" )\n" -" if self.maxsize is not None and len(value) > self.maxsize:\n" -" raise ValueError(\n" -" f'Expected {value!r} to be no bigger than {self.maxsize!r}'\n" -" )\n" -" if self.predicate is not None and not self.predicate(value):\n" -" raise ValueError(\n" -" f'Expected {self.predicate} to be true for {value!r}'\n" -" )" -msgstr "" - -#: ../../howto/descriptor.rst:439 -msgid "Practical application" -msgstr "" - -#: ../../howto/descriptor.rst:441 -msgid "Here's how the data validators can be used in a real class:" -msgstr "" - -#: ../../howto/descriptor.rst:443 -msgid "" -"class Component:\n" -"\n" -" name = String(minsize=3, maxsize=10, predicate=str.isupper)\n" -" kind = OneOf('wood', 'metal', 'plastic')\n" -" quantity = Number(minvalue=0)\n" -"\n" -" def __init__(self, name, kind, quantity):\n" -" self.name = name\n" -" self.kind = kind\n" -" self.quantity = quantity" -msgstr "" - -#: ../../howto/descriptor.rst:456 -msgid "The descriptors prevent invalid instances from being created:" -msgstr "" - -#: ../../howto/descriptor.rst:458 -msgid "" -">>> Component('Widget', 'metal', 5) # Blocked: 'Widget' is not all " -"uppercase\n" -"Traceback (most recent call last):\n" -" ...\n" -"ValueError: Expected to be true for " -"'Widget'\n" -"\n" -">>> Component('WIDGET', 'metle', 5) # Blocked: 'metle' is misspelled\n" -"Traceback (most recent call last):\n" -" ...\n" -"ValueError: Expected 'metle' to be one of {'metal', 'plastic', 'wood'}\n" -"\n" -">>> Component('WIDGET', 'metal', -5) # Blocked: -5 is negative\n" -"Traceback (most recent call last):\n" -" ...\n" -"ValueError: Expected -5 to be at least 0\n" -"\n" -">>> Component('WIDGET', 'metal', 'V') # Blocked: 'V' isn't a number\n" -"Traceback (most recent call last):\n" -" ...\n" -"TypeError: Expected 'V' to be an int or float\n" -"\n" -">>> c = Component('WIDGET', 'metal', 5) # Allowed: The inputs are valid" -msgstr "" - -#: ../../howto/descriptor.rst:484 -msgid "Technical Tutorial" -msgstr "" - -#: ../../howto/descriptor.rst:486 -msgid "" -"What follows is a more technical tutorial for the mechanics and details of " -"how descriptors work." -msgstr "" - -#: ../../howto/descriptor.rst:491 -msgid "Abstract" -msgstr "摘要" - -#: ../../howto/descriptor.rst:493 -msgid "" -"Defines descriptors, summarizes the protocol, and shows how descriptors are " -"called. Provides an example showing how object relational mappings work." -msgstr "" - -#: ../../howto/descriptor.rst:496 -msgid "" -"Learning about descriptors not only provides access to a larger toolset, it " -"creates a deeper understanding of how Python works." -msgstr "" - -#: ../../howto/descriptor.rst:501 -msgid "Definition and introduction" -msgstr "" - -#: ../../howto/descriptor.rst:503 -msgid "" -"In general, a descriptor is an attribute value that has one of the methods " -"in the descriptor protocol. Those methods " -"are :meth:`~object.__get__`, :meth:`~object.__set__`, " -"and :meth:`~object.__delete__`. If any of those methods are defined for an " -"attribute, it is said to be a :term:`descriptor`." -msgstr "" - -#: ../../howto/descriptor.rst:508 -msgid "" -"The default behavior for attribute access is to get, set, or delete the " -"attribute from an object's dictionary. For instance, ``a.x`` has a lookup " -"chain starting with ``a.__dict__['x']``, then ``type(a).__dict__['x']``, and " -"continuing through the method resolution order of ``type(a)``. If the looked-" -"up value is an object defining one of the descriptor methods, then Python " -"may override the default behavior and invoke the descriptor method instead. " -"Where this occurs in the precedence chain depends on which descriptor " -"methods were defined." -msgstr "" - -#: ../../howto/descriptor.rst:517 -msgid "" -"Descriptors are a powerful, general purpose protocol. They are the " -"mechanism behind properties, methods, static methods, class methods, " -"and :func:`super`. They are used throughout Python itself. Descriptors " -"simplify the underlying C code and offer a flexible set of new tools for " -"everyday Python programs." -msgstr "" - -#: ../../howto/descriptor.rst:525 -msgid "Descriptor protocol" -msgstr "描述器協定" - -#: ../../howto/descriptor.rst:527 -msgid "``descr.__get__(self, obj, type=None)``" -msgstr "``descr.__get__(self, obj, type=None)``" - -#: ../../howto/descriptor.rst:529 -msgid "``descr.__set__(self, obj, value)``" -msgstr "``descr.__set__(self, obj, value)``" - -#: ../../howto/descriptor.rst:531 -msgid "``descr.__delete__(self, obj)``" -msgstr "``descr.__delete__(self, obj)``" - -#: ../../howto/descriptor.rst:533 -msgid "" -"That is all there is to it. Define any of these methods and an object is " -"considered a descriptor and can override default behavior upon being looked " -"up as an attribute." -msgstr "" - -#: ../../howto/descriptor.rst:537 -msgid "" -"If an object defines :meth:`~object.__set__` or :meth:`~object.__delete__`, " -"it is considered a data descriptor. Descriptors that only " -"define :meth:`~object.__get__` are called non-data descriptors (they are " -"often used for methods but other uses are possible)." -msgstr "" - -#: ../../howto/descriptor.rst:542 -msgid "" -"Data and non-data descriptors differ in how overrides are calculated with " -"respect to entries in an instance's dictionary. If an instance's dictionary " -"has an entry with the same name as a data descriptor, the data descriptor " -"takes precedence. If an instance's dictionary has an entry with the same " -"name as a non-data descriptor, the dictionary entry takes precedence." -msgstr "" - -#: ../../howto/descriptor.rst:548 -msgid "" -"To make a read-only data descriptor, define both :meth:`~object.__get__` " -"and :meth:`~object.__set__` with the :meth:`~object.__set__` raising " -"an :exc:`AttributeError` when called. Defining the :meth:`~object.__set__` " -"method with an exception raising placeholder is enough to make it a data " -"descriptor." -msgstr "" - -#: ../../howto/descriptor.rst:555 -msgid "Overview of descriptor invocation" -msgstr "" - -#: ../../howto/descriptor.rst:557 -msgid "" -"A descriptor can be called directly with ``desc.__get__(obj)`` or " -"``desc.__get__(None, cls)``." -msgstr "" - -#: ../../howto/descriptor.rst:560 -msgid "" -"But it is more common for a descriptor to be invoked automatically from " -"attribute access." -msgstr "" - -#: ../../howto/descriptor.rst:563 -msgid "" -"The expression ``obj.x`` looks up the attribute ``x`` in the chain of " -"namespaces for ``obj``. If the search finds a descriptor outside of the " -"instance :attr:`~object.__dict__`, its :meth:`~object.__get__` method is " -"invoked according to the precedence rules listed below." -msgstr "" - -#: ../../howto/descriptor.rst:568 -msgid "" -"The details of invocation depend on whether ``obj`` is an object, class, or " -"instance of super." -msgstr "" - -#: ../../howto/descriptor.rst:573 -msgid "Invocation from an instance" -msgstr "" - -#: ../../howto/descriptor.rst:575 -msgid "" -"Instance lookup scans through a chain of namespaces giving data descriptors " -"the highest priority, followed by instance variables, then non-data " -"descriptors, then class variables, and lastly :meth:`~object.__getattr__` if " -"it is provided." -msgstr "" - -#: ../../howto/descriptor.rst:580 -msgid "" -"If a descriptor is found for ``a.x``, then it is invoked with: " -"``desc.__get__(a, type(a))``." -msgstr "" - -#: ../../howto/descriptor.rst:583 -msgid "" -"The logic for a dotted lookup is in :meth:`object.__getattribute__`. Here " -"is a pure Python equivalent:" -msgstr "" - -#: ../../howto/descriptor.rst:586 -msgid "" -"def find_name_in_mro(cls, name, default):\n" -" \"Emulate _PyType_Lookup() in Objects/typeobject.c\"\n" -" for base in cls.__mro__:\n" -" if name in vars(base):\n" -" return vars(base)[name]\n" -" return default\n" -"\n" -"def object_getattribute(obj, name):\n" -" \"Emulate PyObject_GenericGetAttr() in Objects/object.c\"\n" -" null = object()\n" -" objtype = type(obj)\n" -" cls_var = find_name_in_mro(objtype, name, null)\n" -" descr_get = getattr(type(cls_var), '__get__', null)\n" -" if descr_get is not null:\n" -" if (hasattr(type(cls_var), '__set__')\n" -" or hasattr(type(cls_var), '__delete__')):\n" -" return descr_get(cls_var, obj, objtype) # data descriptor\n" -" if hasattr(obj, '__dict__') and name in vars(obj):\n" -" return vars(obj)[name] # instance variable\n" -" if descr_get is not null:\n" -" return descr_get(cls_var, obj, objtype) # non-data " -"descriptor\n" -" if cls_var is not null:\n" -" return cls_var # class variable\n" -" raise AttributeError(name)" -msgstr "" - -#: ../../howto/descriptor.rst:722 -msgid "" -"Note, there is no :meth:`~object.__getattr__` hook in " -"the :meth:`~object.__getattribute__` code. That is why " -"calling :meth:`~object.__getattribute__` directly or with " -"``super().__getattribute__`` will bypass :meth:`~object.__getattr__` " -"entirely." -msgstr "" - -#: ../../howto/descriptor.rst:726 -msgid "" -"Instead, it is the dot operator and the :func:`getattr` function that are " -"responsible for invoking :meth:`~object.__getattr__` " -"whenever :meth:`~object.__getattribute__` raises an :exc:`AttributeError`. " -"Their logic is encapsulated in a helper function:" -msgstr "" - -#: ../../howto/descriptor.rst:731 -msgid "" -"def getattr_hook(obj, name):\n" -" \"Emulate slot_tp_getattr_hook() in Objects/typeobject.c\"\n" -" try:\n" -" return obj.__getattribute__(name)\n" -" except AttributeError:\n" -" if not hasattr(type(obj), '__getattr__'):\n" -" raise\n" -" return type(obj).__getattr__(obj, name) # __getattr__" -msgstr "" -"def getattr_hook(obj, name):\n" -" \"Emulate slot_tp_getattr_hook() in Objects/typeobject.c\"\n" -" try:\n" -" return obj.__getattribute__(name)\n" -" except AttributeError:\n" -" if not hasattr(type(obj), '__getattr__'):\n" -" raise\n" -" return type(obj).__getattr__(obj, name) # __getattr__" - -#: ../../howto/descriptor.rst:776 -msgid "Invocation from a class" -msgstr "" - -#: ../../howto/descriptor.rst:778 -msgid "" -"The logic for a dotted lookup such as ``A.x`` is in :meth:`!" -"type.__getattribute__`. The steps are similar to those for :meth:`!" -"object.__getattribute__` but the instance dictionary lookup is replaced by a " -"search through the class's :term:`method resolution order`." -msgstr "" - -#: ../../howto/descriptor.rst:783 -msgid "If a descriptor is found, it is invoked with ``desc.__get__(None, A)``." -msgstr "" - -#: ../../howto/descriptor.rst:785 -msgid "" -"The full C implementation can be found in :c:func:`!type_getattro` " -"and :c:func:`!_PyType_Lookup` in :source:`Objects/typeobject.c`." -msgstr "" - -#: ../../howto/descriptor.rst:790 -msgid "Invocation from super" -msgstr "" - -#: ../../howto/descriptor.rst:792 -msgid "" -"The logic for super's dotted lookup is in " -"the :meth:`~object.__getattribute__` method for object returned " -"by :func:`super`." -msgstr "" - -#: ../../howto/descriptor.rst:795 -msgid "" -"A dotted lookup such as ``super(A, obj).m`` searches " -"``obj.__class__.__mro__`` for the base class ``B`` immediately following " -"``A`` and then returns ``B.__dict__['m'].__get__(obj, A)``. If not a " -"descriptor, ``m`` is returned unchanged." -msgstr "" - -#: ../../howto/descriptor.rst:800 -msgid "" -"The full C implementation can be found in :c:func:`!super_getattro` " -"in :source:`Objects/typeobject.c`. A pure Python equivalent can be found in " -"`Guido's Tutorial `_." -msgstr "" - -#: ../../howto/descriptor.rst:807 -msgid "Summary of invocation logic" -msgstr "" - -#: ../../howto/descriptor.rst:809 -msgid "" -"The mechanism for descriptors is embedded in " -"the :meth:`~object.__getattribute__` methods " -"for :class:`object`, :class:`type`, and :func:`super`." -msgstr "" - -#: ../../howto/descriptor.rst:812 -msgid "The important points to remember are:" -msgstr "要記住的重點是：" - -#: ../../howto/descriptor.rst:814 -msgid "Descriptors are invoked by the :meth:`~object.__getattribute__` method." -msgstr "" - -#: ../../howto/descriptor.rst:816 -msgid "" -"Classes inherit this machinery from :class:`object`, :class:`type`, " -"or :func:`super`." -msgstr "" - -#: ../../howto/descriptor.rst:819 -msgid "" -"Overriding :meth:`~object.__getattribute__` prevents automatic descriptor " -"calls because all the descriptor logic is in that method." -msgstr "" - -#: ../../howto/descriptor.rst:822 -msgid "" -":meth:`!object.__getattribute__` and :meth:`!type.__getattribute__` make " -"different calls to :meth:`~object.__get__`. The first includes the instance " -"and may include the class. The second puts in ``None`` for the instance and " -"always includes the class." -msgstr "" - -#: ../../howto/descriptor.rst:827 -msgid "Data descriptors always override instance dictionaries." -msgstr "" - -#: ../../howto/descriptor.rst:829 -msgid "Non-data descriptors may be overridden by instance dictionaries." -msgstr "" - -#: ../../howto/descriptor.rst:833 -msgid "Automatic name notification" -msgstr "" - -#: ../../howto/descriptor.rst:835 -msgid "" -"Sometimes it is desirable for a descriptor to know what class variable name " -"it was assigned to. When a new class is created, the :class:`type` " -"metaclass scans the dictionary of the new class. If any of the entries are " -"descriptors and if they define :meth:`~object.__set_name__`, that method is " -"called with two arguments. The *owner* is the class where the descriptor is " -"used, and the *name* is the class variable the descriptor was assigned to." -msgstr "" - -#: ../../howto/descriptor.rst:842 -msgid "" -"The implementation details are in :c:func:`!type_new` and :c:func:`!" -"set_names` in :source:`Objects/typeobject.c`." -msgstr "" - -#: ../../howto/descriptor.rst:845 -msgid "" -"Since the update logic is in :meth:`!type.__new__`, notifications only take " -"place at the time of class creation. If descriptors are added to the class " -"afterwards, :meth:`~object.__set_name__` will need to be called manually." -msgstr "" - -#: ../../howto/descriptor.rst:851 -msgid "ORM example" -msgstr "ORM 範例" - -#: ../../howto/descriptor.rst:853 -msgid "" -"The following code is a simplified skeleton showing how data descriptors " -"could be used to implement an `object relational mapping `_." -msgstr "" - -#: ../../howto/descriptor.rst:857 -msgid "" -"The essential idea is that the data is stored in an external database. The " -"Python instances only hold keys to the database's tables. Descriptors take " -"care of lookups or updates:" -msgstr "" - -#: ../../howto/descriptor.rst:861 -msgid "" -"class Field:\n" -"\n" -" def __set_name__(self, owner, name):\n" -" self.fetch = f'SELECT {name} FROM {owner.table} WHERE {owner.key}" -"=?;'\n" -" self.store = f'UPDATE {owner.table} SET {name}=? WHERE {owner.key}" -"=?;'\n" -"\n" -" def __get__(self, obj, objtype=None):\n" -" return conn.execute(self.fetch, [obj.key]).fetchone()[0]\n" -"\n" -" def __set__(self, obj, value):\n" -" conn.execute(self.store, [value, obj.key])\n" -" conn.commit()" -msgstr "" -"class Field:\n" -"\n" -" def __set_name__(self, owner, name):\n" -" self.fetch = f'SELECT {name} FROM {owner.table} WHERE {owner.key}" -"=?;'\n" -" self.store = f'UPDATE {owner.table} SET {name}=? WHERE {owner.key}" -"=?;'\n" -"\n" -" def __get__(self, obj, objtype=None):\n" -" return conn.execute(self.fetch, [obj.key]).fetchone()[0]\n" -"\n" -" def __set__(self, obj, value):\n" -" conn.execute(self.store, [value, obj.key])\n" -" conn.commit()" - -#: ../../howto/descriptor.rst:876 -msgid "" -"We can use the :class:`!Field` class to define `models `_ that describe the schema for each " -"table in a database:" -msgstr "" - -#: ../../howto/descriptor.rst:880 -msgid "" -"class Movie:\n" -" table = 'Movies' # Table name\n" -" key = 'title' # Primary key\n" -" director = Field()\n" -" year = Field()\n" -"\n" -" def __init__(self, key):\n" -" self.key = key\n" -"\n" -"class Song:\n" -" table = 'Music'\n" -" key = 'title'\n" -" artist = Field()\n" -" year = Field()\n" -" genre = Field()\n" -"\n" -" def __init__(self, key):\n" -" self.key = key" -msgstr "" - -#: ../../howto/descriptor.rst:901 -msgid "To use the models, first connect to the database::" -msgstr "" - -#: ../../howto/descriptor.rst:903 -msgid "" -">>> import sqlite3\n" -">>> conn = sqlite3.connect('entertainment.db')" -msgstr "" -">>> import sqlite3\n" -">>> conn = sqlite3.connect('entertainment.db')" - -#: ../../howto/descriptor.rst:906 -msgid "" -"An interactive session shows how data is retrieved from the database and how " -"it can be updated:" -msgstr "" - -#: ../../howto/descriptor.rst:934 -msgid "" -">>> Movie('Star Wars').director\n" -"'George Lucas'\n" -">>> jaws = Movie('Jaws')\n" -">>> f'Released in {jaws.year} by {jaws.director}'\n" -"'Released in 1975 by Steven Spielberg'\n" -"\n" -">>> Song('Country Roads').artist\n" -"'John Denver'\n" -"\n" -">>> Movie('Star Wars').director = 'J.J. Abrams'\n" -">>> Movie('Star Wars').director\n" -"'J.J. Abrams'" -msgstr "" -">>> Movie('Star Wars').director\n" -"'George Lucas'\n" -">>> jaws = Movie('Jaws')\n" -">>> f'Released in {jaws.year} by {jaws.director}'\n" -"'Released in 1975 by Steven Spielberg'\n" -"\n" -">>> Song('Country Roads').artist\n" -"'John Denver'\n" -"\n" -">>> Movie('Star Wars').director = 'J.J. Abrams'\n" -">>> Movie('Star Wars').director\n" -"'J.J. Abrams'" - -#: ../../howto/descriptor.rst:955 -msgid "Pure Python Equivalents" -msgstr "" - -#: ../../howto/descriptor.rst:957 -msgid "" -"The descriptor protocol is simple and offers exciting possibilities. " -"Several use cases are so common that they have been prepackaged into built-" -"in tools. Properties, bound methods, static methods, class methods, and " -"\\_\\_slots\\_\\_ are all based on the descriptor protocol." -msgstr "" - -#: ../../howto/descriptor.rst:964 -msgid "Properties" -msgstr "" - -#: ../../howto/descriptor.rst:966 -msgid "" -"Calling :func:`property` is a succinct way of building a data descriptor " -"that triggers a function call upon access to an attribute. Its signature " -"is::" -msgstr "" - -#: ../../howto/descriptor.rst:969 -msgid "property(fget=None, fset=None, fdel=None, doc=None) -> property" -msgstr "property(fget=None, fset=None, fdel=None, doc=None) -> property" - -#: ../../howto/descriptor.rst:971 -msgid "" -"The documentation shows a typical use to define a managed attribute ``x``:" -msgstr "" - -#: ../../howto/descriptor.rst:973 -msgid "" -"class C:\n" -" def getx(self): return self.__x\n" -" def setx(self, value): self.__x = value\n" -" def delx(self): del self.__x\n" -" x = property(getx, setx, delx, \"I'm the 'x' property.\")" -msgstr "" -"class C:\n" -" def getx(self): return self.__x\n" -" def setx(self, value): self.__x = value\n" -" def delx(self): del self.__x\n" -" x = property(getx, setx, delx, \"I'm the 'x' property.\")" - -#: ../../howto/descriptor.rst:995 -msgid "" -"To see how :func:`property` is implemented in terms of the descriptor " -"protocol, here is a pure Python equivalent that implements most of the core " -"functionality:" -msgstr "" - -#: ../../howto/descriptor.rst:998 -msgid "" -"class Property:\n" -" \"Emulate PyProperty_Type() in Objects/descrobject.c\"\n" -"\n" -" def __init__(self, fget=None, fset=None, fdel=None, doc=None):\n" -" self.fget = fget\n" -" self.fset = fset\n" -" self.fdel = fdel\n" -" if doc is None and fget is not None:\n" -" doc = fget.__doc__\n" -" self.__doc__ = doc\n" -"\n" -" def __set_name__(self, owner, name):\n" -" self.__name__ = name\n" -"\n" -" def __get__(self, obj, objtype=None):\n" -" if obj is None:\n" -" return self\n" -" if self.fget is None:\n" -" raise AttributeError\n" -" return self.fget(obj)\n" -"\n" -" def __set__(self, obj, value):\n" -" if self.fset is None:\n" -" raise AttributeError\n" -" self.fset(obj, value)\n" -"\n" -" def __delete__(self, obj):\n" -" if self.fdel is None:\n" -" raise AttributeError\n" -" self.fdel(obj)\n" -"\n" -" def getter(self, fget):\n" -" return type(self)(fget, self.fset, self.fdel, self.__doc__)\n" -"\n" -" def setter(self, fset):\n" -" return type(self)(self.fget, fset, self.fdel, self.__doc__)\n" -"\n" -" def deleter(self, fdel):\n" -" return type(self)(self.fget, self.fset, fdel, self.__doc__)" -msgstr "" - -#: ../../howto/descriptor.rst:1122 -msgid "" -"The :func:`property` builtin helps whenever a user interface has granted " -"attribute access and then subsequent changes require the intervention of a " -"method." -msgstr "" - -#: ../../howto/descriptor.rst:1126 -msgid "" -"For instance, a spreadsheet class may grant access to a cell value through " -"``Cell('b10').value``. Subsequent improvements to the program require the " -"cell to be recalculated on every access; however, the programmer does not " -"want to affect existing client code accessing the attribute directly. The " -"solution is to wrap access to the value attribute in a property data " -"descriptor:" -msgstr "" - -#: ../../howto/descriptor.rst:1132 -msgid "" -"class Cell:\n" -" ...\n" -"\n" -" @property\n" -" def value(self):\n" -" \"Recalculate the cell before returning value\"\n" -" self.recalc()\n" -" return self._value" -msgstr "" - -#: ../../howto/descriptor.rst:1143 -msgid "" -"Either the built-in :func:`property` or our :func:`!Property` equivalent " -"would work in this example." -msgstr "" - -#: ../../howto/descriptor.rst:1148 -msgid "Functions and methods" -msgstr "" - -#: ../../howto/descriptor.rst:1150 -msgid "" -"Python's object oriented features are built upon a function based " -"environment. Using non-data descriptors, the two are merged seamlessly." -msgstr "" - -#: ../../howto/descriptor.rst:1153 -msgid "" -"Functions stored in class dictionaries get turned into methods when invoked. " -"Methods only differ from regular functions in that the object instance is " -"prepended to the other arguments. By convention, the instance is called " -"*self* but could be called *this* or any other variable name." -msgstr "" - -#: ../../howto/descriptor.rst:1158 -msgid "" -"Methods can be created manually with :class:`types.MethodType` which is " -"roughly equivalent to:" -msgstr "" - -#: ../../howto/descriptor.rst:1161 -msgid "" -"class MethodType:\n" -" \"Emulate PyMethod_Type in Objects/classobject.c\"\n" -"\n" -" def __init__(self, func, obj):\n" -" self.__func__ = func\n" -" self.__self__ = obj\n" -"\n" -" def __call__(self, *args, **kwargs):\n" -" func = self.__func__\n" -" obj = self.__self__\n" -" return func(obj, *args, **kwargs)\n" -"\n" -" def __getattribute__(self, name):\n" -" \"Emulate method_getset() in Objects/classobject.c\"\n" -" if name == '__doc__':\n" -" return self.__func__.__doc__\n" -" return object.__getattribute__(self, name)\n" -"\n" -" def __getattr__(self, name):\n" -" \"Emulate method_getattro() in Objects/classobject.c\"\n" -" return getattr(self.__func__, name)\n" -"\n" -" def __get__(self, obj, objtype=None):\n" -" \"Emulate method_descr_get() in Objects/classobject.c\"\n" -" return self" -msgstr "" - -#: ../../howto/descriptor.rst:1189 -msgid "" -"To support automatic creation of methods, functions include " -"the :meth:`~object.__get__` method for binding methods during attribute " -"access. This means that functions are non-data descriptors that return " -"bound methods during dotted lookup from an instance. Here's how it works:" -msgstr "" - -#: ../../howto/descriptor.rst:1194 -msgid "" -"class Function:\n" -" ...\n" -"\n" -" def __get__(self, obj, objtype=None):\n" -" \"Simulate func_descr_get() in Objects/funcobject.c\"\n" -" if obj is None:\n" -" return self\n" -" return MethodType(self, obj)" -msgstr "" - -#: ../../howto/descriptor.rst:1205 -msgid "" -"Running the following class in the interpreter shows how the function " -"descriptor works in practice:" -msgstr "" - -#: ../../howto/descriptor.rst:1208 -msgid "" -"class D:\n" -" def f(self):\n" -" return self\n" -"\n" -"class D2:\n" -" pass" -msgstr "" -"class D:\n" -" def f(self):\n" -" return self\n" -"\n" -"class D2:\n" -" pass" - -#: ../../howto/descriptor.rst:1226 -msgid "" -"The function has a :term:`qualified name` attribute to support introspection:" -msgstr "" - -#: ../../howto/descriptor.rst:1228 -msgid "" -">>> D.f.__qualname__\n" -"'D.f'" -msgstr "" -">>> D.f.__qualname__\n" -"'D.f'" - -#: ../../howto/descriptor.rst:1233 -msgid "" -"Accessing the function through the class dictionary does not " -"invoke :meth:`~object.__get__`. Instead, it just returns the underlying " -"function object::" -msgstr "" - -#: ../../howto/descriptor.rst:1236 -msgid "" -">>> D.__dict__['f']\n" -"" -msgstr "" -">>> D.__dict__['f']\n" -"" - -#: ../../howto/descriptor.rst:1239 -msgid "" -"Dotted access from a class calls :meth:`~object.__get__` which just returns " -"the underlying function unchanged::" -msgstr "" - -#: ../../howto/descriptor.rst:1242 -msgid "" -">>> D.f\n" -"" -msgstr "" -">>> D.f\n" -"" - -#: ../../howto/descriptor.rst:1245 -msgid "" -"The interesting behavior occurs during dotted access from an instance. The " -"dotted lookup calls :meth:`~object.__get__` which returns a bound method " -"object::" -msgstr "" - -#: ../../howto/descriptor.rst:1248 -msgid "" -">>> d = D()\n" -">>> d.f\n" -">" -msgstr "" -">>> d = D()\n" -">>> d.f\n" -">" - -#: ../../howto/descriptor.rst:1252 -msgid "" -"Internally, the bound method stores the underlying function and the bound " -"instance::" -msgstr "" - -#: ../../howto/descriptor.rst:1255 -msgid "" -">>> d.f.__func__\n" -"\n" -"\n" -">>> d.f.__self__\n" -"<__main__.D object at 0x00B18C90>" -msgstr "" -">>> d.f.__func__\n" -"\n" -"\n" -">>> d.f.__self__\n" -"<__main__.D object at 0x00B18C90>" - -#: ../../howto/descriptor.rst:1261 -msgid "" -"If you have ever wondered where *self* comes from in regular methods or " -"where *cls* comes from in class methods, this is it!" -msgstr "" - -#: ../../howto/descriptor.rst:1266 -msgid "Kinds of methods" -msgstr "" - -#: ../../howto/descriptor.rst:1268 -msgid "" -"Non-data descriptors provide a simple mechanism for variations on the usual " -"patterns of binding functions into methods." -msgstr "" - -#: ../../howto/descriptor.rst:1271 -msgid "" -"To recap, functions have a :meth:`~object.__get__` method so that they can " -"be converted to a method when accessed as attributes. The non-data " -"descriptor transforms an ``obj.f(*args)`` call into ``f(obj, *args)``. " -"Calling ``cls.f(*args)`` becomes ``f(*args)``." -msgstr "" - -#: ../../howto/descriptor.rst:1276 -msgid "This chart summarizes the binding and its two most useful variants:" -msgstr "" - -#: ../../howto/descriptor.rst:1279 -msgid "Transformation" -msgstr "" - -#: ../../howto/descriptor.rst:1279 -msgid "Called from an object" -msgstr "" - -#: ../../howto/descriptor.rst:1279 -msgid "Called from a class" -msgstr "" - -#: ../../howto/descriptor.rst:1282 -msgid "function" -msgstr "函式" - -#: ../../howto/descriptor.rst:1282 -msgid "f(obj, \\*args)" -msgstr "f(obj, \\*args)" - -#: ../../howto/descriptor.rst:1282 ../../howto/descriptor.rst:1284 -msgid "f(\\*args)" -msgstr "f(\\*args)" - -#: ../../howto/descriptor.rst:1284 -msgid "staticmethod" -msgstr "staticmethod" - -#: ../../howto/descriptor.rst:1286 -msgid "classmethod" -msgstr "classmethod" - -#: ../../howto/descriptor.rst:1286 -msgid "f(type(obj), \\*args)" -msgstr "f(type(obj), \\*args)" - -#: ../../howto/descriptor.rst:1286 -msgid "f(cls, \\*args)" -msgstr "f(cls, \\*args)" - -#: ../../howto/descriptor.rst:1291 -msgid "Static methods" -msgstr "" - -#: ../../howto/descriptor.rst:1293 -msgid "" -"Static methods return the underlying function without changes. Calling " -"either ``c.f`` or ``C.f`` is the equivalent of a direct lookup into " -"``object.__getattribute__(c, \"f\")`` or ``object.__getattribute__(C, " -"\"f\")``. As a result, the function becomes identically accessible from " -"either an object or a class." -msgstr "" - -#: ../../howto/descriptor.rst:1299 -msgid "" -"Good candidates for static methods are methods that do not reference the " -"``self`` variable." -msgstr "" - -#: ../../howto/descriptor.rst:1302 -msgid "" -"For instance, a statistics package may include a container class for " -"experimental data. The class provides normal methods for computing the " -"average, mean, median, and other descriptive statistics that depend on the " -"data. However, there may be useful functions which are conceptually related " -"but do not depend on the data. For instance, ``erf(x)`` is handy conversion " -"routine that comes up in statistical work but does not directly depend on a " -"particular dataset. It can be called either from an object or the class: " -"``s.erf(1.5) --> 0.9332`` or ``Sample.erf(1.5) --> 0.9332``." -msgstr "" - -#: ../../howto/descriptor.rst:1311 -msgid "" -"Since static methods return the underlying function with no changes, the " -"example calls are unexciting:" -msgstr "" - -#: ../../howto/descriptor.rst:1314 -msgid "" -"class E:\n" -" @staticmethod\n" -" def f(x):\n" -" return x * 10" -msgstr "" -"class E:\n" -" @staticmethod\n" -" def f(x):\n" -" return x * 10" - -#: ../../howto/descriptor.rst:1321 -msgid "" -">>> E.f(3)\n" -"30\n" -">>> E().f(3)\n" -"30" -msgstr "" -">>> E.f(3)\n" -"30\n" -">>> E().f(3)\n" -"30" - -#: ../../howto/descriptor.rst:1328 -msgid "" -"Using the non-data descriptor protocol, a pure Python version " -"of :func:`staticmethod` would look like this:" -msgstr "" - -#: ../../howto/descriptor.rst:1331 -msgid "" -"import functools\n" -"\n" -"class StaticMethod:\n" -" \"Emulate PyStaticMethod_Type() in Objects/funcobject.c\"\n" -"\n" -" def __init__(self, f):\n" -" self.f = f\n" -" functools.update_wrapper(self, f)\n" -"\n" -" def __get__(self, obj, objtype=None):\n" -" return self.f\n" -"\n" -" def __call__(self, *args, **kwds):\n" -" return self.f(*args, **kwds)\n" -"\n" -" @property\n" -" def __annotations__(self):\n" -" return self.f.__annotations__" -msgstr "" - -#: ../../howto/descriptor.rst:1352 -msgid "" -"The :func:`functools.update_wrapper` call adds a ``__wrapped__`` attribute " -"that refers to the underlying function. Also it carries forward the " -"attributes necessary to make the wrapper look like the wrapped function, " -"including :attr:`~function.__name__`, :attr:`~function.__qualname__`, " -"and :attr:`~function.__doc__`." -msgstr "" - -#: ../../howto/descriptor.rst:1421 -msgid "Class methods" -msgstr "" - -#: ../../howto/descriptor.rst:1423 -msgid "" -"Unlike static methods, class methods prepend the class reference to the " -"argument list before calling the function. This format is the same for " -"whether the caller is an object or a class:" -msgstr "" - -#: ../../howto/descriptor.rst:1427 -msgid "" -"class F:\n" -" @classmethod\n" -" def f(cls, x):\n" -" return cls.__name__, x" -msgstr "" -"class F:\n" -" @classmethod\n" -" def f(cls, x):\n" -" return cls.__name__, x" - -#: ../../howto/descriptor.rst:1434 -msgid "" -">>> F.f(3)\n" -"('F', 3)\n" -">>> F().f(3)\n" -"('F', 3)" -msgstr "" -">>> F.f(3)\n" -"('F', 3)\n" -">>> F().f(3)\n" -"('F', 3)" - -#: ../../howto/descriptor.rst:1441 -msgid "" -"This behavior is useful whenever the method only needs to have a class " -"reference and does not rely on data stored in a specific instance. One use " -"for class methods is to create alternate class constructors. For example, " -"the classmethod :func:`dict.fromkeys` creates a new dictionary from a list " -"of keys. The pure Python equivalent is:" -msgstr "" - -#: ../../howto/descriptor.rst:1447 -msgid "" -"class Dict(dict):\n" -" @classmethod\n" -" def fromkeys(cls, iterable, value=None):\n" -" \"Emulate dict_fromkeys() in Objects/dictobject.c\"\n" -" d = cls()\n" -" for key in iterable:\n" -" d[key] = value\n" -" return d" -msgstr "" - -#: ../../howto/descriptor.rst:1458 -msgid "Now a new dictionary of unique keys can be constructed like this:" -msgstr "" - -#: ../../howto/descriptor.rst:1460 -msgid "" -">>> d = Dict.fromkeys('abracadabra')\n" -">>> type(d) is Dict\n" -"True\n" -">>> d\n" -"{'a': None, 'b': None, 'r': None, 'c': None, 'd': None}" -msgstr "" -">>> d = Dict.fromkeys('abracadabra')\n" -">>> type(d) is Dict\n" -"True\n" -">>> d\n" -"{'a': None, 'b': None, 'r': None, 'c': None, 'd': None}" - -#: ../../howto/descriptor.rst:1468 -msgid "" -"Using the non-data descriptor protocol, a pure Python version " -"of :func:`classmethod` would look like this:" -msgstr "" - -#: ../../howto/descriptor.rst:1471 -msgid "" -"import functools\n" -"\n" -"class ClassMethod:\n" -" \"Emulate PyClassMethod_Type() in Objects/funcobject.c\"\n" -"\n" -" def __init__(self, f):\n" -" self.f = f\n" -" functools.update_wrapper(self, f)\n" -"\n" -" def __get__(self, obj, cls=None):\n" -" if cls is None:\n" -" cls = type(obj)\n" -" return MethodType(self.f, cls)" -msgstr "" - -#: ../../howto/descriptor.rst:1533 -msgid "" -"The :func:`functools.update_wrapper` call in ``ClassMethod`` adds a " -"``__wrapped__`` attribute that refers to the underlying function. Also it " -"carries forward the attributes necessary to make the wrapper look like the " -"wrapped " -"function: :attr:`~function.__name__`, :attr:`~function.__qualname__`, :attr:`~function.__doc__`, " -"and :attr:`~function.__annotations__`." -msgstr "" - -#: ../../howto/descriptor.rst:1542 -msgid "Member objects and __slots__" -msgstr "" - -#: ../../howto/descriptor.rst:1544 -msgid "" -"When a class defines ``__slots__``, it replaces instance dictionaries with a " -"fixed-length array of slot values. From a user point of view that has " -"several effects:" -msgstr "" - -#: ../../howto/descriptor.rst:1548 -msgid "" -"1. Provides immediate detection of bugs due to misspelled attribute " -"assignments. Only attribute names specified in ``__slots__`` are allowed:" -msgstr "" - -#: ../../howto/descriptor.rst:1551 -msgid "" -"class Vehicle:\n" -" __slots__ = ('id_number', 'make', 'model')" -msgstr "" -"class Vehicle:\n" -" __slots__ = ('id_number', 'make', 'model')" - -#: ../../howto/descriptor.rst:1556 -msgid "" -">>> auto = Vehicle()\n" -">>> auto.id_nubmer = 'VYE483814LQEX'\n" -"Traceback (most recent call last):\n" -" ...\n" -"AttributeError: 'Vehicle' object has no attribute 'id_nubmer'" -msgstr "" -">>> auto = Vehicle()\n" -">>> auto.id_nubmer = 'VYE483814LQEX'\n" -"Traceback (most recent call last):\n" -" ...\n" -"AttributeError: 'Vehicle' object has no attribute 'id_nubmer'" - -#: ../../howto/descriptor.rst:1564 -msgid "" -"2. Helps create immutable objects where descriptors manage access to private " -"attributes stored in ``__slots__``:" -msgstr "" - -#: ../../howto/descriptor.rst:1567 -msgid "" -"class Immutable:\n" -"\n" -" __slots__ = ('_dept', '_name') # Replace the instance " -"dictionary\n" -"\n" -" def __init__(self, dept, name):\n" -" self._dept = dept # Store to private attribute\n" -" self._name = name # Store to private attribute\n" -"\n" -" @property # Read-only descriptor\n" -" def dept(self):\n" -" return self._dept\n" -"\n" -" @property\n" -" def name(self): # Read-only descriptor\n" -" return self._name" -msgstr "" - -#: ../../howto/descriptor.rst:1585 -msgid "" -">>> mark = Immutable('Botany', 'Mark Watney')\n" -">>> mark.dept\n" -"'Botany'\n" -">>> mark.dept = 'Space Pirate'\n" -"Traceback (most recent call last):\n" -" ...\n" -"AttributeError: property 'dept' of 'Immutable' object has no setter\n" -">>> mark.location = 'Mars'\n" -"Traceback (most recent call last):\n" -" ...\n" -"AttributeError: 'Immutable' object has no attribute 'location'" -msgstr "" -">>> mark = Immutable('Botany', 'Mark Watney')\n" -">>> mark.dept\n" -"'Botany'\n" -">>> mark.dept = 'Space Pirate'\n" -"Traceback (most recent call last):\n" -" ...\n" -"AttributeError: property 'dept' of 'Immutable' object has no setter\n" -">>> mark.location = 'Mars'\n" -"Traceback (most recent call last):\n" -" ...\n" -"AttributeError: 'Immutable' object has no attribute 'location'" - -#: ../../howto/descriptor.rst:1599 -msgid "" -"3. Saves memory. On a 64-bit Linux build, an instance with two attributes " -"takes 48 bytes with ``__slots__`` and 152 bytes without. This `flyweight " -"design pattern `_ likely " -"only matters when a large number of instances are going to be created." -msgstr "" - -#: ../../howto/descriptor.rst:1604 -msgid "" -"4. Improves speed. Reading instance variables is 35% faster with " -"``__slots__`` (as measured with Python 3.10 on an Apple M1 processor)." -msgstr "" - -#: ../../howto/descriptor.rst:1607 -msgid "" -"5. Blocks tools like :func:`functools.cached_property` which require an " -"instance dictionary to function correctly:" -msgstr "" - -#: ../../howto/descriptor.rst:1610 -msgid "" -"from functools import cached_property\n" -"\n" -"class CP:\n" -" __slots__ = () # Eliminates the instance dict\n" -"\n" -" @cached_property # Requires an instance dict\n" -" def pi(self):\n" -" return 4 * sum((-1.0)**n / (2.0*n + 1.0)\n" -" for n in reversed(range(100_000)))" -msgstr "" - -#: ../../howto/descriptor.rst:1622 -msgid "" -">>> CP().pi\n" -"Traceback (most recent call last):\n" -" ...\n" -"TypeError: No '__dict__' attribute on 'CP' instance to cache 'pi' property." -msgstr "" -">>> CP().pi\n" -"Traceback (most recent call last):\n" -" ...\n" -"TypeError: No '__dict__' attribute on 'CP' instance to cache 'pi' property." - -#: ../../howto/descriptor.rst:1629 -msgid "" -"It is not possible to create an exact drop-in pure Python version of " -"``__slots__`` because it requires direct access to C structures and control " -"over object memory allocation. However, we can build a mostly faithful " -"simulation where the actual C structure for slots is emulated by a private " -"``_slotvalues`` list. Reads and writes to that private structure are " -"managed by member descriptors:" -msgstr "" - -#: ../../howto/descriptor.rst:1636 -msgid "" -"null = object()\n" -"\n" -"class Member:\n" -"\n" -" def __init__(self, name, clsname, offset):\n" -" 'Emulate PyMemberDef in Include/structmember.h'\n" -" # Also see descr_new() in Objects/descrobject.c\n" -" self.name = name\n" -" self.clsname = clsname\n" -" self.offset = offset\n" -"\n" -" def __get__(self, obj, objtype=None):\n" -" 'Emulate member_get() in Objects/descrobject.c'\n" -" # Also see PyMember_GetOne() in Python/structmember.c\n" -" if obj is None:\n" -" return self\n" -" value = obj._slotvalues[self.offset]\n" -" if value is null:\n" -" raise AttributeError(self.name)\n" -" return value\n" -"\n" -" def __set__(self, obj, value):\n" -" 'Emulate member_set() in Objects/descrobject.c'\n" -" obj._slotvalues[self.offset] = value\n" -"\n" -" def __delete__(self, obj):\n" -" 'Emulate member_delete() in Objects/descrobject.c'\n" -" value = obj._slotvalues[self.offset]\n" -" if value is null:\n" -" raise AttributeError(self.name)\n" -" obj._slotvalues[self.offset] = null\n" -"\n" -" def __repr__(self):\n" -" 'Emulate member_repr() in Objects/descrobject.c'\n" -" return f''" -msgstr "" - -#: ../../howto/descriptor.rst:1674 -msgid "" -"The :meth:`!type.__new__` method takes care of adding member objects to " -"class variables:" -msgstr "" - -#: ../../howto/descriptor.rst:1677 -msgid "" -"class Type(type):\n" -" 'Simulate how the type metaclass adds member objects for slots'\n" -"\n" -" def __new__(mcls, clsname, bases, mapping, **kwargs):\n" -" 'Emulate type_new() in Objects/typeobject.c'\n" -" # type_new() calls PyTypeReady() which calls add_methods()\n" -" slot_names = mapping.get('slot_names', [])\n" -" for offset, name in enumerate(slot_names):\n" -" mapping[name] = Member(name, clsname, offset)\n" -" return type.__new__(mcls, clsname, bases, mapping, **kwargs)" -msgstr "" - -#: ../../howto/descriptor.rst:1690 -msgid "" -"The :meth:`object.__new__` method takes care of creating instances that have " -"slots instead of an instance dictionary. Here is a rough simulation in pure " -"Python:" -msgstr "" - -#: ../../howto/descriptor.rst:1694 -msgid "" -"class Object:\n" -" 'Simulate how object.__new__() allocates memory for __slots__'\n" -"\n" -" def __new__(cls, *args, **kwargs):\n" -" 'Emulate object_new() in Objects/typeobject.c'\n" -" inst = super().__new__(cls)\n" -" if hasattr(cls, 'slot_names'):\n" -" empty_slots = [null] * len(cls.slot_names)\n" -" object.__setattr__(inst, '_slotvalues', empty_slots)\n" -" return inst\n" -"\n" -" def __setattr__(self, name, value):\n" -" 'Emulate _PyObject_GenericSetAttrWithDict() Objects/object.c'\n" -" cls = type(self)\n" -" if hasattr(cls, 'slot_names') and name not in cls.slot_names:\n" -" raise AttributeError(\n" -" f'{cls.__name__!r} object has no attribute {name!r}'\n" -" )\n" -" super().__setattr__(name, value)\n" -"\n" -" def __delattr__(self, name):\n" -" 'Emulate _PyObject_GenericSetAttrWithDict() Objects/object.c'\n" -" cls = type(self)\n" -" if hasattr(cls, 'slot_names') and name not in cls.slot_names:\n" -" raise AttributeError(\n" -" f'{cls.__name__!r} object has no attribute {name!r}'\n" -" )\n" -" super().__delattr__(name)" -msgstr "" - -#: ../../howto/descriptor.rst:1725 -msgid "" -"To use the simulation in a real class, just inherit from :class:`!Object` " -"and set the :term:`metaclass` to :class:`Type`:" -msgstr "" - -#: ../../howto/descriptor.rst:1728 -msgid "" -"class H(Object, metaclass=Type):\n" -" 'Instance variables stored in slots'\n" -"\n" -" slot_names = ['x', 'y']\n" -"\n" -" def __init__(self, x, y):\n" -" self.x = x\n" -" self.y = y" -msgstr "" - -#: ../../howto/descriptor.rst:1739 -msgid "" -"At this point, the metaclass has loaded member objects for *x* and *y*::" -msgstr "" - -#: ../../howto/descriptor.rst:1741 -msgid "" -">>> from pprint import pp\n" -">>> pp(dict(vars(H)))\n" -"{'__module__': '__main__',\n" -" '__doc__': 'Instance variables stored in slots',\n" -" 'slot_names': ['x', 'y'],\n" -" '__init__': ,\n" -" 'x': ,\n" -" 'y': }" -msgstr "" -">>> from pprint import pp\n" -">>> pp(dict(vars(H)))\n" -"{'__module__': '__main__',\n" -" '__doc__': 'Instance variables stored in slots',\n" -" 'slot_names': ['x', 'y'],\n" -" '__init__': ,\n" -" 'x': ,\n" -" 'y': }" - -#: ../../howto/descriptor.rst:1760 -msgid "" -"When instances are created, they have a ``slot_values`` list where the " -"attributes are stored:" -msgstr "" - -#: ../../howto/descriptor.rst:1763 -msgid "" -">>> h = H(10, 20)\n" -">>> vars(h)\n" -"{'_slotvalues': [10, 20]}\n" -">>> h.x = 55\n" -">>> vars(h)\n" -"{'_slotvalues': [55, 20]}" -msgstr "" -">>> h = H(10, 20)\n" -">>> vars(h)\n" -"{'_slotvalues': [10, 20]}\n" -">>> h.x = 55\n" -">>> vars(h)\n" -"{'_slotvalues': [55, 20]}" - -#: ../../howto/descriptor.rst:1772 -msgid "Misspelled or unassigned attributes will raise an exception:" -msgstr "" - -#: ../../howto/descriptor.rst:1774 -msgid "" -">>> h.xz\n" -"Traceback (most recent call last):\n" -" ...\n" -"AttributeError: 'H' object has no attribute 'xz'" -msgstr "" -">>> h.xz\n" -"Traceback (most recent call last):\n" -" ...\n" -"AttributeError: 'H' object has no attribute 'xz'" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Leon H., 2017 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-09 05:11+0800\n" +"PO-Revision-Date: 2018-05-23 14:36+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" + +#: ../../howto/descriptor.rst:5 +msgid "Descriptor Guide" +msgstr "描述器 (Descriptor) 指南" + +#: ../../howto/descriptor.rst:0 +msgid "Author" +msgstr "作者" + +#: ../../howto/descriptor.rst:7 +msgid "Raymond Hettinger" +msgstr "Raymond Hettinger" + +#: ../../howto/descriptor.rst:0 +msgid "Contact" +msgstr "聯絡方式" + +#: ../../howto/descriptor.rst:8 +msgid "" +msgstr "" + +#: ../../howto/descriptor.rst:11 +msgid "Contents" +msgstr "目錄" + +#: ../../howto/descriptor.rst:13 +msgid "" +":term:`Descriptors ` let objects customize attribute lookup, " +"storage, and deletion." +msgstr ":term:`描述器 `\\ 讓物件自訂屬性能夠被查找、儲存和刪除。" + +#: ../../howto/descriptor.rst:16 +msgid "This guide has four major sections:" +msgstr "此指南有四個主要章節：" + +#: ../../howto/descriptor.rst:18 +msgid "" +"The \"primer\" gives a basic overview, moving gently from simple examples, " +"adding one feature at a time. Start here if you're new to descriptors." +msgstr "" + +#: ../../howto/descriptor.rst:21 +msgid "" +"The second section shows a complete, practical descriptor example. If you " +"already know the basics, start there." +msgstr "" + +#: ../../howto/descriptor.rst:24 +msgid "" +"The third section provides a more technical tutorial that goes into the " +"detailed mechanics of how descriptors work. Most people don't need this " +"level of detail." +msgstr "" + +#: ../../howto/descriptor.rst:28 +msgid "" +"The last section has pure Python equivalents for built-in descriptors that " +"are written in C. Read this if you're curious about how functions turn into " +"bound methods or about the implementation of common tools " +"like :func:`classmethod`, :func:`staticmethod`, :func:`property`, " +"and :term:`__slots__`." +msgstr "" + +#: ../../howto/descriptor.rst:36 +msgid "Primer" +msgstr "" + +#: ../../howto/descriptor.rst:38 +msgid "" +"In this primer, we start with the most basic possible example and then we'll " +"add new capabilities one by one." +msgstr "" + +#: ../../howto/descriptor.rst:43 +msgid "Simple example: A descriptor that returns a constant" +msgstr "" + +#: ../../howto/descriptor.rst:45 +msgid "" +"The :class:`!Ten` class is a descriptor whose :meth:`~object.__get__` method " +"always returns the constant ``10``:" +msgstr "" + +#: ../../howto/descriptor.rst:48 +msgid "" +"class Ten:\n" +" def __get__(self, obj, objtype=None):\n" +" return 10" +msgstr "" +"class Ten:\n" +" def __get__(self, obj, objtype=None):\n" +" return 10" + +#: ../../howto/descriptor.rst:54 +msgid "" +"To use the descriptor, it must be stored as a class variable in another " +"class:" +msgstr "" + +#: ../../howto/descriptor.rst:56 +msgid "" +"class A:\n" +" x = 5 # Regular class attribute\n" +" y = Ten() # Descriptor instance" +msgstr "" + +#: ../../howto/descriptor.rst:62 +msgid "" +"An interactive session shows the difference between normal attribute lookup " +"and descriptor lookup:" +msgstr "" + +#: ../../howto/descriptor.rst:65 +msgid "" +">>> a = A() # Make an instance of class A\n" +">>> a.x # Normal attribute lookup\n" +"5\n" +">>> a.y # Descriptor lookup\n" +"10" +msgstr "" + +#: ../../howto/descriptor.rst:73 +msgid "" +"In the ``a.x`` attribute lookup, the dot operator finds ``'x': 5`` in the " +"class dictionary. In the ``a.y`` lookup, the dot operator finds a " +"descriptor instance, recognized by its ``__get__`` method. Calling that " +"method returns ``10``." +msgstr "" + +#: ../../howto/descriptor.rst:78 +msgid "" +"Note that the value ``10`` is not stored in either the class dictionary or " +"the instance dictionary. Instead, the value ``10`` is computed on demand." +msgstr "" + +#: ../../howto/descriptor.rst:81 +msgid "" +"This example shows how a simple descriptor works, but it isn't very useful. " +"For retrieving constants, normal attribute lookup would be better." +msgstr "" + +#: ../../howto/descriptor.rst:84 +msgid "" +"In the next section, we'll create something more useful, a dynamic lookup." +msgstr "" + +#: ../../howto/descriptor.rst:88 +msgid "Dynamic lookups" +msgstr "" + +#: ../../howto/descriptor.rst:90 +msgid "" +"Interesting descriptors typically run computations instead of returning " +"constants:" +msgstr "" + +#: ../../howto/descriptor.rst:93 +msgid "" +"import os\n" +"\n" +"class DirectorySize:\n" +"\n" +" def __get__(self, obj, objtype=None):\n" +" return len(os.listdir(obj.dirname))\n" +"\n" +"class Directory:\n" +"\n" +" size = DirectorySize() # Descriptor instance\n" +"\n" +" def __init__(self, dirname):\n" +" self.dirname = dirname # Regular instance attribute" +msgstr "" + +#: ../../howto/descriptor.rst:109 +msgid "" +"An interactive session shows that the lookup is dynamic — it computes " +"different, updated answers each time::" +msgstr "" + +#: ../../howto/descriptor.rst:112 +msgid "" +">>> s = Directory('songs')\n" +">>> g = Directory('games')\n" +">>> s.size # The songs directory has twenty " +"files\n" +"20\n" +">>> g.size # The games directory has three " +"files\n" +"3\n" +">>> os.remove('games/chess') # Delete a game\n" +">>> g.size # File count is automatically " +"updated\n" +"2" +msgstr "" + +#: ../../howto/descriptor.rst:122 +msgid "" +"Besides showing how descriptors can run computations, this example also " +"reveals the purpose of the parameters to :meth:`~object.__get__`. The " +"*self* parameter is *size*, an instance of *DirectorySize*. The *obj* " +"parameter is either *g* or *s*, an instance of *Directory*. It is the *obj* " +"parameter that lets the :meth:`~object.__get__` method learn the target " +"directory. The *objtype* parameter is the class *Directory*." +msgstr "" + +#: ../../howto/descriptor.rst:131 +msgid "Managed attributes" +msgstr "" + +#: ../../howto/descriptor.rst:133 +msgid "" +"A popular use for descriptors is managing access to instance data. The " +"descriptor is assigned to a public attribute in the class dictionary while " +"the actual data is stored as a private attribute in the instance " +"dictionary. The descriptor's :meth:`~object.__get__` " +"and :meth:`~object.__set__` methods are triggered when the public attribute " +"is accessed." +msgstr "" + +#: ../../howto/descriptor.rst:139 +msgid "" +"In the following example, *age* is the public attribute and *_age* is the " +"private attribute. When the public attribute is accessed, the descriptor " +"logs the lookup or update:" +msgstr "" + +#: ../../howto/descriptor.rst:143 +msgid "" +"import logging\n" +"\n" +"logging.basicConfig(level=logging.INFO)\n" +"\n" +"class LoggedAgeAccess:\n" +"\n" +" def __get__(self, obj, objtype=None):\n" +" value = obj._age\n" +" logging.info('Accessing %r giving %r', 'age', value)\n" +" return value\n" +"\n" +" def __set__(self, obj, value):\n" +" logging.info('Updating %r to %r', 'age', value)\n" +" obj._age = value\n" +"\n" +"class Person:\n" +"\n" +" age = LoggedAgeAccess() # Descriptor instance\n" +"\n" +" def __init__(self, name, age):\n" +" self.name = name # Regular instance attribute\n" +" self.age = age # Calls __set__()\n" +"\n" +" def birthday(self):\n" +" self.age += 1 # Calls both __get__() and __set__()" +msgstr "" + +#: ../../howto/descriptor.rst:172 +msgid "" +"An interactive session shows that all access to the managed attribute *age* " +"is logged, but that the regular attribute *name* is not logged:" +msgstr "" + +#: ../../howto/descriptor.rst:181 +msgid "" +">>> mary = Person('Mary M', 30) # The initial age update is logged\n" +"INFO:root:Updating 'age' to 30\n" +">>> dave = Person('David D', 40)\n" +"INFO:root:Updating 'age' to 40\n" +"\n" +">>> vars(mary) # The actual data is in a private " +"attribute\n" +"{'name': 'Mary M', '_age': 30}\n" +">>> vars(dave)\n" +"{'name': 'David D', '_age': 40}\n" +"\n" +">>> mary.age # Access the data and log the " +"lookup\n" +"INFO:root:Accessing 'age' giving 30\n" +"30\n" +">>> mary.birthday() # Updates are logged as well\n" +"INFO:root:Accessing 'age' giving 30\n" +"INFO:root:Updating 'age' to 31\n" +"\n" +">>> dave.name # Regular attribute lookup isn't " +"logged\n" +"'David D'\n" +">>> dave.age # Only the managed attribute is " +"logged\n" +"INFO:root:Accessing 'age' giving 40\n" +"40" +msgstr "" + +#: ../../howto/descriptor.rst:206 +msgid "" +"One major issue with this example is that the private name *_age* is " +"hardwired in the *LoggedAgeAccess* class. That means that each instance can " +"only have one logged attribute and that its name is unchangeable. In the " +"next example, we'll fix that problem." +msgstr "" + +#: ../../howto/descriptor.rst:213 +msgid "Customized names" +msgstr "" + +#: ../../howto/descriptor.rst:215 +msgid "" +"When a class uses descriptors, it can inform each descriptor about which " +"variable name was used." +msgstr "" + +#: ../../howto/descriptor.rst:218 +msgid "" +"In this example, the :class:`!Person` class has two descriptor instances, " +"*name* and *age*. When the :class:`!Person` class is defined, it makes a " +"callback to :meth:`~object.__set_name__` in *LoggedAccess* so that the field " +"names can be recorded, giving each descriptor its own *public_name* and " +"*private_name*:" +msgstr "" + +#: ../../howto/descriptor.rst:223 +msgid "" +"import logging\n" +"\n" +"logging.basicConfig(level=logging.INFO)\n" +"\n" +"class LoggedAccess:\n" +"\n" +" def __set_name__(self, owner, name):\n" +" self.public_name = name\n" +" self.private_name = '_' + name\n" +"\n" +" def __get__(self, obj, objtype=None):\n" +" value = getattr(obj, self.private_name)\n" +" logging.info('Accessing %r giving %r', self.public_name, value)\n" +" return value\n" +"\n" +" def __set__(self, obj, value):\n" +" logging.info('Updating %r to %r', self.public_name, value)\n" +" setattr(obj, self.private_name, value)\n" +"\n" +"class Person:\n" +"\n" +" name = LoggedAccess() # First descriptor instance\n" +" age = LoggedAccess() # Second descriptor instance\n" +"\n" +" def __init__(self, name, age):\n" +" self.name = name # Calls the first descriptor\n" +" self.age = age # Calls the second descriptor\n" +"\n" +" def birthday(self):\n" +" self.age += 1" +msgstr "" + +#: ../../howto/descriptor.rst:256 +msgid "" +"An interactive session shows that the :class:`!Person` class has " +"called :meth:`~object.__set_name__` so that the field names would be " +"recorded. Here we call :func:`vars` to look up the descriptor without " +"triggering it:" +msgstr "" + +#: ../../howto/descriptor.rst:260 +msgid "" +">>> vars(vars(Person)['name'])\n" +"{'public_name': 'name', 'private_name': '_name'}\n" +">>> vars(vars(Person)['age'])\n" +"{'public_name': 'age', 'private_name': '_age'}" +msgstr "" +">>> vars(vars(Person)['name'])\n" +"{'public_name': 'name', 'private_name': '_name'}\n" +">>> vars(vars(Person)['age'])\n" +"{'public_name': 'age', 'private_name': '_age'}" + +#: ../../howto/descriptor.rst:267 +msgid "The new class now logs access to both *name* and *age*:" +msgstr "" + +#: ../../howto/descriptor.rst:275 +msgid "" +">>> pete = Person('Peter P', 10)\n" +"INFO:root:Updating 'name' to 'Peter P'\n" +"INFO:root:Updating 'age' to 10\n" +">>> kate = Person('Catherine C', 20)\n" +"INFO:root:Updating 'name' to 'Catherine C'\n" +"INFO:root:Updating 'age' to 20" +msgstr "" +">>> pete = Person('Peter P', 10)\n" +"INFO:root:Updating 'name' to 'Peter P'\n" +"INFO:root:Updating 'age' to 10\n" +">>> kate = Person('Catherine C', 20)\n" +"INFO:root:Updating 'name' to 'Catherine C'\n" +"INFO:root:Updating 'age' to 20" + +#: ../../howto/descriptor.rst:284 +msgid "The two *Person* instances contain only the private names:" +msgstr "" + +#: ../../howto/descriptor.rst:286 +msgid "" +">>> vars(pete)\n" +"{'_name': 'Peter P', '_age': 10}\n" +">>> vars(kate)\n" +"{'_name': 'Catherine C', '_age': 20}" +msgstr "" +">>> vars(pete)\n" +"{'_name': 'Peter P', '_age': 10}\n" +">>> vars(kate)\n" +"{'_name': 'Catherine C', '_age': 20}" + +#: ../../howto/descriptor.rst:295 +msgid "Closing thoughts" +msgstr "" + +#: ../../howto/descriptor.rst:297 +msgid "" +"A :term:`descriptor` is what we call any object that " +"defines :meth:`~object.__get__`, :meth:`~object.__set__`, " +"or :meth:`~object.__delete__`." +msgstr "" + +#: ../../howto/descriptor.rst:300 +msgid "" +"Optionally, descriptors can have a :meth:`~object.__set_name__` method. " +"This is only used in cases where a descriptor needs to know either the class " +"where it was created or the name of class variable it was assigned to. " +"(This method, if present, is called even if the class is not a descriptor.)" +msgstr "" + +#: ../../howto/descriptor.rst:305 +msgid "" +"Descriptors get invoked by the dot operator during attribute lookup. If a " +"descriptor is accessed indirectly with ``vars(some_class)" +"[descriptor_name]``, the descriptor instance is returned without invoking it." +msgstr "" + +#: ../../howto/descriptor.rst:309 +msgid "" +"Descriptors only work when used as class variables. When put in instances, " +"they have no effect." +msgstr "" + +#: ../../howto/descriptor.rst:312 +msgid "" +"The main motivation for descriptors is to provide a hook allowing objects " +"stored in class variables to control what happens during attribute lookup." +msgstr "" + +#: ../../howto/descriptor.rst:315 +msgid "" +"Traditionally, the calling class controls what happens during lookup. " +"Descriptors invert that relationship and allow the data being looked-up to " +"have a say in the matter." +msgstr "" + +#: ../../howto/descriptor.rst:319 +msgid "" +"Descriptors are used throughout the language. It is how functions turn into " +"bound methods. Common tools " +"like :func:`classmethod`, :func:`staticmethod`, :func:`property`, " +"and :func:`functools.cached_property` are all implemented as descriptors." +msgstr "" + +#: ../../howto/descriptor.rst:326 +msgid "Complete Practical Example" +msgstr "" + +#: ../../howto/descriptor.rst:328 +msgid "" +"In this example, we create a practical and powerful tool for locating " +"notoriously hard to find data corruption bugs." +msgstr "" + +#: ../../howto/descriptor.rst:333 +msgid "Validator class" +msgstr "" + +#: ../../howto/descriptor.rst:335 +msgid "" +"A validator is a descriptor for managed attribute access. Prior to storing " +"any data, it verifies that the new value meets various type and range " +"restrictions. If those restrictions aren't met, it raises an exception to " +"prevent data corruption at its source." +msgstr "" + +#: ../../howto/descriptor.rst:340 +msgid "" +"This :class:`!Validator` class is both an :term:`abstract base class` and a " +"managed attribute descriptor:" +msgstr "" + +#: ../../howto/descriptor.rst:343 +msgid "" +"from abc import ABC, abstractmethod\n" +"\n" +"class Validator(ABC):\n" +"\n" +" def __set_name__(self, owner, name):\n" +" self.private_name = '_' + name\n" +"\n" +" def __get__(self, obj, objtype=None):\n" +" return getattr(obj, self.private_name)\n" +"\n" +" def __set__(self, obj, value):\n" +" self.validate(value)\n" +" setattr(obj, self.private_name, value)\n" +"\n" +" @abstractmethod\n" +" def validate(self, value):\n" +" pass" +msgstr "" +"from abc import ABC, abstractmethod\n" +"\n" +"class Validator(ABC):\n" +"\n" +" def __set_name__(self, owner, name):\n" +" self.private_name = '_' + name\n" +"\n" +" def __get__(self, obj, objtype=None):\n" +" return getattr(obj, self.private_name)\n" +"\n" +" def __set__(self, obj, value):\n" +" self.validate(value)\n" +" setattr(obj, self.private_name, value)\n" +"\n" +" @abstractmethod\n" +" def validate(self, value):\n" +" pass" + +#: ../../howto/descriptor.rst:363 +msgid "" +"Custom validators need to inherit from :class:`!Validator` and must supply " +"a :meth:`!validate` method to test various restrictions as needed." +msgstr "" + +#: ../../howto/descriptor.rst:368 +msgid "Custom validators" +msgstr "" + +#: ../../howto/descriptor.rst:370 +msgid "Here are three practical data validation utilities:" +msgstr "" + +#: ../../howto/descriptor.rst:372 +msgid "" +":class:`!OneOf` verifies that a value is one of a restricted set of options." +msgstr "" + +#: ../../howto/descriptor.rst:374 +msgid "" +":class:`!Number` verifies that a value is either an :class:`int` " +"or :class:`float`. Optionally, it verifies that a value is between a given " +"minimum or maximum." +msgstr "" + +#: ../../howto/descriptor.rst:378 +msgid "" +":class:`!String` verifies that a value is a :class:`str`. Optionally, it " +"validates a given minimum or maximum length. It can validate a user-defined " +"`predicate `_ " +"as well." +msgstr "" + +#: ../../howto/descriptor.rst:383 +msgid "" +"class OneOf(Validator):\n" +"\n" +" def __init__(self, *options):\n" +" self.options = set(options)\n" +"\n" +" def validate(self, value):\n" +" if value not in self.options:\n" +" raise ValueError(\n" +" f'Expected {value!r} to be one of {self.options!r}'\n" +" )\n" +"\n" +"class Number(Validator):\n" +"\n" +" def __init__(self, minvalue=None, maxvalue=None):\n" +" self.minvalue = minvalue\n" +" self.maxvalue = maxvalue\n" +"\n" +" def validate(self, value):\n" +" if not isinstance(value, (int, float)):\n" +" raise TypeError(f'Expected {value!r} to be an int or float')\n" +" if self.minvalue is not None and value < self.minvalue:\n" +" raise ValueError(\n" +" f'Expected {value!r} to be at least {self.minvalue!r}'\n" +" )\n" +" if self.maxvalue is not None and value > self.maxvalue:\n" +" raise ValueError(\n" +" f'Expected {value!r} to be no more than {self.maxvalue!r}'\n" +" )\n" +"\n" +"class String(Validator):\n" +"\n" +" def __init__(self, minsize=None, maxsize=None, predicate=None):\n" +" self.minsize = minsize\n" +" self.maxsize = maxsize\n" +" self.predicate = predicate\n" +"\n" +" def validate(self, value):\n" +" if not isinstance(value, str):\n" +" raise TypeError(f'Expected {value!r} to be a str')\n" +" if self.minsize is not None and len(value) < self.minsize:\n" +" raise ValueError(\n" +" f'Expected {value!r} to be no smaller than {self.minsize!" +"r}'\n" +" )\n" +" if self.maxsize is not None and len(value) > self.maxsize:\n" +" raise ValueError(\n" +" f'Expected {value!r} to be no bigger than {self.maxsize!r}'\n" +" )\n" +" if self.predicate is not None and not self.predicate(value):\n" +" raise ValueError(\n" +" f'Expected {self.predicate} to be true for {value!r}'\n" +" )" +msgstr "" + +#: ../../howto/descriptor.rst:439 +msgid "Practical application" +msgstr "" + +#: ../../howto/descriptor.rst:441 +msgid "Here's how the data validators can be used in a real class:" +msgstr "" + +#: ../../howto/descriptor.rst:443 +msgid "" +"class Component:\n" +"\n" +" name = String(minsize=3, maxsize=10, predicate=str.isupper)\n" +" kind = OneOf('wood', 'metal', 'plastic')\n" +" quantity = Number(minvalue=0)\n" +"\n" +" def __init__(self, name, kind, quantity):\n" +" self.name = name\n" +" self.kind = kind\n" +" self.quantity = quantity" +msgstr "" + +#: ../../howto/descriptor.rst:456 +msgid "The descriptors prevent invalid instances from being created:" +msgstr "" + +#: ../../howto/descriptor.rst:458 +msgid "" +">>> Component('Widget', 'metal', 5) # Blocked: 'Widget' is not all " +"uppercase\n" +"Traceback (most recent call last):\n" +" ...\n" +"ValueError: Expected to be true for " +"'Widget'\n" +"\n" +">>> Component('WIDGET', 'metle', 5) # Blocked: 'metle' is misspelled\n" +"Traceback (most recent call last):\n" +" ...\n" +"ValueError: Expected 'metle' to be one of {'metal', 'plastic', 'wood'}\n" +"\n" +">>> Component('WIDGET', 'metal', -5) # Blocked: -5 is negative\n" +"Traceback (most recent call last):\n" +" ...\n" +"ValueError: Expected -5 to be at least 0\n" +"\n" +">>> Component('WIDGET', 'metal', 'V') # Blocked: 'V' isn't a number\n" +"Traceback (most recent call last):\n" +" ...\n" +"TypeError: Expected 'V' to be an int or float\n" +"\n" +">>> c = Component('WIDGET', 'metal', 5) # Allowed: The inputs are valid" +msgstr "" + +#: ../../howto/descriptor.rst:484 +msgid "Technical Tutorial" +msgstr "" + +#: ../../howto/descriptor.rst:486 +msgid "" +"What follows is a more technical tutorial for the mechanics and details of " +"how descriptors work." +msgstr "" + +#: ../../howto/descriptor.rst:491 +msgid "Abstract" +msgstr "摘要" + +#: ../../howto/descriptor.rst:493 +msgid "" +"Defines descriptors, summarizes the protocol, and shows how descriptors are " +"called. Provides an example showing how object relational mappings work." +msgstr "" + +#: ../../howto/descriptor.rst:496 +msgid "" +"Learning about descriptors not only provides access to a larger toolset, it " +"creates a deeper understanding of how Python works." +msgstr "" + +#: ../../howto/descriptor.rst:501 +msgid "Definition and introduction" +msgstr "" + +#: ../../howto/descriptor.rst:503 +msgid "" +"In general, a descriptor is an attribute value that has one of the methods " +"in the descriptor protocol. Those methods " +"are :meth:`~object.__get__`, :meth:`~object.__set__`, " +"and :meth:`~object.__delete__`. If any of those methods are defined for an " +"attribute, it is said to be a :term:`descriptor`." +msgstr "" + +#: ../../howto/descriptor.rst:508 +msgid "" +"The default behavior for attribute access is to get, set, or delete the " +"attribute from an object's dictionary. For instance, ``a.x`` has a lookup " +"chain starting with ``a.__dict__['x']``, then ``type(a).__dict__['x']``, and " +"continuing through the method resolution order of ``type(a)``. If the looked-" +"up value is an object defining one of the descriptor methods, then Python " +"may override the default behavior and invoke the descriptor method instead. " +"Where this occurs in the precedence chain depends on which descriptor " +"methods were defined." +msgstr "" + +#: ../../howto/descriptor.rst:517 +msgid "" +"Descriptors are a powerful, general purpose protocol. They are the " +"mechanism behind properties, methods, static methods, class methods, " +"and :func:`super`. They are used throughout Python itself. Descriptors " +"simplify the underlying C code and offer a flexible set of new tools for " +"everyday Python programs." +msgstr "" + +#: ../../howto/descriptor.rst:525 +msgid "Descriptor protocol" +msgstr "描述器協定" + +#: ../../howto/descriptor.rst:527 +msgid "``descr.__get__(self, obj, type=None)``" +msgstr "``descr.__get__(self, obj, type=None)``" + +#: ../../howto/descriptor.rst:529 +msgid "``descr.__set__(self, obj, value)``" +msgstr "``descr.__set__(self, obj, value)``" + +#: ../../howto/descriptor.rst:531 +msgid "``descr.__delete__(self, obj)``" +msgstr "``descr.__delete__(self, obj)``" + +#: ../../howto/descriptor.rst:533 +msgid "" +"That is all there is to it. Define any of these methods and an object is " +"considered a descriptor and can override default behavior upon being looked " +"up as an attribute." +msgstr "" + +#: ../../howto/descriptor.rst:537 +msgid "" +"If an object defines :meth:`~object.__set__` or :meth:`~object.__delete__`, " +"it is considered a data descriptor. Descriptors that only " +"define :meth:`~object.__get__` are called non-data descriptors (they are " +"often used for methods but other uses are possible)." +msgstr "" + +#: ../../howto/descriptor.rst:542 +msgid "" +"Data and non-data descriptors differ in how overrides are calculated with " +"respect to entries in an instance's dictionary. If an instance's dictionary " +"has an entry with the same name as a data descriptor, the data descriptor " +"takes precedence. If an instance's dictionary has an entry with the same " +"name as a non-data descriptor, the dictionary entry takes precedence." +msgstr "" + +#: ../../howto/descriptor.rst:548 +msgid "" +"To make a read-only data descriptor, define both :meth:`~object.__get__` " +"and :meth:`~object.__set__` with the :meth:`~object.__set__` raising " +"an :exc:`AttributeError` when called. Defining the :meth:`~object.__set__` " +"method with an exception raising placeholder is enough to make it a data " +"descriptor." +msgstr "" + +#: ../../howto/descriptor.rst:555 +msgid "Overview of descriptor invocation" +msgstr "" + +#: ../../howto/descriptor.rst:557 +msgid "" +"A descriptor can be called directly with ``desc.__get__(obj)`` or " +"``desc.__get__(None, cls)``." +msgstr "" + +#: ../../howto/descriptor.rst:560 +msgid "" +"But it is more common for a descriptor to be invoked automatically from " +"attribute access." +msgstr "" + +#: ../../howto/descriptor.rst:563 +msgid "" +"The expression ``obj.x`` looks up the attribute ``x`` in the chain of " +"namespaces for ``obj``. If the search finds a descriptor outside of the " +"instance :attr:`~object.__dict__`, its :meth:`~object.__get__` method is " +"invoked according to the precedence rules listed below." +msgstr "" + +#: ../../howto/descriptor.rst:568 +msgid "" +"The details of invocation depend on whether ``obj`` is an object, class, or " +"instance of super." +msgstr "" + +#: ../../howto/descriptor.rst:573 +msgid "Invocation from an instance" +msgstr "" + +#: ../../howto/descriptor.rst:575 +msgid "" +"Instance lookup scans through a chain of namespaces giving data descriptors " +"the highest priority, followed by instance variables, then non-data " +"descriptors, then class variables, and lastly :meth:`~object.__getattr__` if " +"it is provided." +msgstr "" + +#: ../../howto/descriptor.rst:580 +msgid "" +"If a descriptor is found for ``a.x``, then it is invoked with: " +"``desc.__get__(a, type(a))``." +msgstr "" + +#: ../../howto/descriptor.rst:583 +msgid "" +"The logic for a dotted lookup is in :meth:`object.__getattribute__`. Here " +"is a pure Python equivalent:" +msgstr "" + +#: ../../howto/descriptor.rst:586 +msgid "" +"def find_name_in_mro(cls, name, default):\n" +" \"Emulate _PyType_Lookup() in Objects/typeobject.c\"\n" +" for base in cls.__mro__:\n" +" if name in vars(base):\n" +" return vars(base)[name]\n" +" return default\n" +"\n" +"def object_getattribute(obj, name):\n" +" \"Emulate PyObject_GenericGetAttr() in Objects/object.c\"\n" +" null = object()\n" +" objtype = type(obj)\n" +" cls_var = find_name_in_mro(objtype, name, null)\n" +" descr_get = getattr(type(cls_var), '__get__', null)\n" +" if descr_get is not null:\n" +" if (hasattr(type(cls_var), '__set__')\n" +" or hasattr(type(cls_var), '__delete__')):\n" +" return descr_get(cls_var, obj, objtype) # data descriptor\n" +" if hasattr(obj, '__dict__') and name in vars(obj):\n" +" return vars(obj)[name] # instance variable\n" +" if descr_get is not null:\n" +" return descr_get(cls_var, obj, objtype) # non-data " +"descriptor\n" +" if cls_var is not null:\n" +" return cls_var # class variable\n" +" raise AttributeError(name)" +msgstr "" + +#: ../../howto/descriptor.rst:722 +msgid "" +"Note, there is no :meth:`~object.__getattr__` hook in " +"the :meth:`~object.__getattribute__` code. That is why " +"calling :meth:`~object.__getattribute__` directly or with " +"``super().__getattribute__`` will bypass :meth:`~object.__getattr__` " +"entirely." +msgstr "" + +#: ../../howto/descriptor.rst:726 +msgid "" +"Instead, it is the dot operator and the :func:`getattr` function that are " +"responsible for invoking :meth:`~object.__getattr__` " +"whenever :meth:`~object.__getattribute__` raises an :exc:`AttributeError`. " +"Their logic is encapsulated in a helper function:" +msgstr "" + +#: ../../howto/descriptor.rst:731 +msgid "" +"def getattr_hook(obj, name):\n" +" \"Emulate slot_tp_getattr_hook() in Objects/typeobject.c\"\n" +" try:\n" +" return obj.__getattribute__(name)\n" +" except AttributeError:\n" +" if not hasattr(type(obj), '__getattr__'):\n" +" raise\n" +" return type(obj).__getattr__(obj, name) # __getattr__" +msgstr "" +"def getattr_hook(obj, name):\n" +" \"Emulate slot_tp_getattr_hook() in Objects/typeobject.c\"\n" +" try:\n" +" return obj.__getattribute__(name)\n" +" except AttributeError:\n" +" if not hasattr(type(obj), '__getattr__'):\n" +" raise\n" +" return type(obj).__getattr__(obj, name) # __getattr__" + +#: ../../howto/descriptor.rst:776 +msgid "Invocation from a class" +msgstr "" + +#: ../../howto/descriptor.rst:778 +msgid "" +"The logic for a dotted lookup such as ``A.x`` is in :meth:`!" +"type.__getattribute__`. The steps are similar to those for :meth:`!" +"object.__getattribute__` but the instance dictionary lookup is replaced by a " +"search through the class's :term:`method resolution order`." +msgstr "" + +#: ../../howto/descriptor.rst:783 +msgid "If a descriptor is found, it is invoked with ``desc.__get__(None, A)``." +msgstr "" + +#: ../../howto/descriptor.rst:785 +msgid "" +"The full C implementation can be found in :c:func:`!type_getattro` " +"and :c:func:`!_PyType_Lookup` in :source:`Objects/typeobject.c`." +msgstr "" + +#: ../../howto/descriptor.rst:790 +msgid "Invocation from super" +msgstr "" + +#: ../../howto/descriptor.rst:792 +msgid "" +"The logic for super's dotted lookup is in " +"the :meth:`~object.__getattribute__` method for object returned " +"by :func:`super`." +msgstr "" + +#: ../../howto/descriptor.rst:795 +msgid "" +"A dotted lookup such as ``super(A, obj).m`` searches " +"``obj.__class__.__mro__`` for the base class ``B`` immediately following " +"``A`` and then returns ``B.__dict__['m'].__get__(obj, A)``. If not a " +"descriptor, ``m`` is returned unchanged." +msgstr "" + +#: ../../howto/descriptor.rst:800 +msgid "" +"The full C implementation can be found in :c:func:`!super_getattro` " +"in :source:`Objects/typeobject.c`. A pure Python equivalent can be found in " +"`Guido's Tutorial `_." +msgstr "" + +#: ../../howto/descriptor.rst:807 +msgid "Summary of invocation logic" +msgstr "" + +#: ../../howto/descriptor.rst:809 +msgid "" +"The mechanism for descriptors is embedded in " +"the :meth:`~object.__getattribute__` methods " +"for :class:`object`, :class:`type`, and :func:`super`." +msgstr "" + +#: ../../howto/descriptor.rst:812 +msgid "The important points to remember are:" +msgstr "要記住的重點是：" + +#: ../../howto/descriptor.rst:814 +msgid "Descriptors are invoked by the :meth:`~object.__getattribute__` method." +msgstr "" + +#: ../../howto/descriptor.rst:816 +msgid "" +"Classes inherit this machinery from :class:`object`, :class:`type`, " +"or :func:`super`." +msgstr "" + +#: ../../howto/descriptor.rst:819 +msgid "" +"Overriding :meth:`~object.__getattribute__` prevents automatic descriptor " +"calls because all the descriptor logic is in that method." +msgstr "" + +#: ../../howto/descriptor.rst:822 +msgid "" +":meth:`!object.__getattribute__` and :meth:`!type.__getattribute__` make " +"different calls to :meth:`~object.__get__`. The first includes the instance " +"and may include the class. The second puts in ``None`` for the instance and " +"always includes the class." +msgstr "" + +#: ../../howto/descriptor.rst:827 +msgid "Data descriptors always override instance dictionaries." +msgstr "" + +#: ../../howto/descriptor.rst:829 +msgid "Non-data descriptors may be overridden by instance dictionaries." +msgstr "" + +#: ../../howto/descriptor.rst:833 +msgid "Automatic name notification" +msgstr "" + +#: ../../howto/descriptor.rst:835 +msgid "" +"Sometimes it is desirable for a descriptor to know what class variable name " +"it was assigned to. When a new class is created, the :class:`type` " +"metaclass scans the dictionary of the new class. If any of the entries are " +"descriptors and if they define :meth:`~object.__set_name__`, that method is " +"called with two arguments. The *owner* is the class where the descriptor is " +"used, and the *name* is the class variable the descriptor was assigned to." +msgstr "" + +#: ../../howto/descriptor.rst:842 +msgid "" +"The implementation details are in :c:func:`!type_new` and :c:func:`!" +"set_names` in :source:`Objects/typeobject.c`." +msgstr "" + +#: ../../howto/descriptor.rst:845 +msgid "" +"Since the update logic is in :meth:`!type.__new__`, notifications only take " +"place at the time of class creation. If descriptors are added to the class " +"afterwards, :meth:`~object.__set_name__` will need to be called manually." +msgstr "" + +#: ../../howto/descriptor.rst:851 +msgid "ORM example" +msgstr "ORM 範例" + +#: ../../howto/descriptor.rst:853 +msgid "" +"The following code is a simplified skeleton showing how data descriptors " +"could be used to implement an `object relational mapping `_." +msgstr "" + +#: ../../howto/descriptor.rst:857 +msgid "" +"The essential idea is that the data is stored in an external database. The " +"Python instances only hold keys to the database's tables. Descriptors take " +"care of lookups or updates:" +msgstr "" + +#: ../../howto/descriptor.rst:861 +msgid "" +"class Field:\n" +"\n" +" def __set_name__(self, owner, name):\n" +" self.fetch = f'SELECT {name} FROM {owner.table} WHERE {owner.key}" +"=?;'\n" +" self.store = f'UPDATE {owner.table} SET {name}=? WHERE {owner.key}" +"=?;'\n" +"\n" +" def __get__(self, obj, objtype=None):\n" +" return conn.execute(self.fetch, [obj.key]).fetchone()[0]\n" +"\n" +" def __set__(self, obj, value):\n" +" conn.execute(self.store, [value, obj.key])\n" +" conn.commit()" +msgstr "" +"class Field:\n" +"\n" +" def __set_name__(self, owner, name):\n" +" self.fetch = f'SELECT {name} FROM {owner.table} WHERE {owner.key}" +"=?;'\n" +" self.store = f'UPDATE {owner.table} SET {name}=? WHERE {owner.key}" +"=?;'\n" +"\n" +" def __get__(self, obj, objtype=None):\n" +" return conn.execute(self.fetch, [obj.key]).fetchone()[0]\n" +"\n" +" def __set__(self, obj, value):\n" +" conn.execute(self.store, [value, obj.key])\n" +" conn.commit()" + +#: ../../howto/descriptor.rst:876 +msgid "" +"We can use the :class:`!Field` class to define `models `_ that describe the schema for each " +"table in a database:" +msgstr "" + +#: ../../howto/descriptor.rst:880 +msgid "" +"class Movie:\n" +" table = 'Movies' # Table name\n" +" key = 'title' # Primary key\n" +" director = Field()\n" +" year = Field()\n" +"\n" +" def __init__(self, key):\n" +" self.key = key\n" +"\n" +"class Song:\n" +" table = 'Music'\n" +" key = 'title'\n" +" artist = Field()\n" +" year = Field()\n" +" genre = Field()\n" +"\n" +" def __init__(self, key):\n" +" self.key = key" +msgstr "" + +#: ../../howto/descriptor.rst:901 +msgid "To use the models, first connect to the database::" +msgstr "" + +#: ../../howto/descriptor.rst:903 +msgid "" +">>> import sqlite3\n" +">>> conn = sqlite3.connect('entertainment.db')" +msgstr "" +">>> import sqlite3\n" +">>> conn = sqlite3.connect('entertainment.db')" + +#: ../../howto/descriptor.rst:906 +msgid "" +"An interactive session shows how data is retrieved from the database and how " +"it can be updated:" +msgstr "" + +#: ../../howto/descriptor.rst:934 +msgid "" +">>> Movie('Star Wars').director\n" +"'George Lucas'\n" +">>> jaws = Movie('Jaws')\n" +">>> f'Released in {jaws.year} by {jaws.director}'\n" +"'Released in 1975 by Steven Spielberg'\n" +"\n" +">>> Song('Country Roads').artist\n" +"'John Denver'\n" +"\n" +">>> Movie('Star Wars').director = 'J.J. Abrams'\n" +">>> Movie('Star Wars').director\n" +"'J.J. Abrams'" +msgstr "" +">>> Movie('Star Wars').director\n" +"'George Lucas'\n" +">>> jaws = Movie('Jaws')\n" +">>> f'Released in {jaws.year} by {jaws.director}'\n" +"'Released in 1975 by Steven Spielberg'\n" +"\n" +">>> Song('Country Roads').artist\n" +"'John Denver'\n" +"\n" +">>> Movie('Star Wars').director = 'J.J. Abrams'\n" +">>> Movie('Star Wars').director\n" +"'J.J. Abrams'" + +#: ../../howto/descriptor.rst:955 +msgid "Pure Python Equivalents" +msgstr "" + +#: ../../howto/descriptor.rst:957 +msgid "" +"The descriptor protocol is simple and offers exciting possibilities. " +"Several use cases are so common that they have been prepackaged into built-" +"in tools. Properties, bound methods, static methods, class methods, and " +"\\_\\_slots\\_\\_ are all based on the descriptor protocol." +msgstr "" + +#: ../../howto/descriptor.rst:964 +msgid "Properties" +msgstr "" + +#: ../../howto/descriptor.rst:966 +msgid "" +"Calling :func:`property` is a succinct way of building a data descriptor " +"that triggers a function call upon access to an attribute. Its signature " +"is::" +msgstr "" + +#: ../../howto/descriptor.rst:969 +msgid "property(fget=None, fset=None, fdel=None, doc=None) -> property" +msgstr "property(fget=None, fset=None, fdel=None, doc=None) -> property" + +#: ../../howto/descriptor.rst:971 +msgid "" +"The documentation shows a typical use to define a managed attribute ``x``:" +msgstr "" + +#: ../../howto/descriptor.rst:973 +msgid "" +"class C:\n" +" def getx(self): return self.__x\n" +" def setx(self, value): self.__x = value\n" +" def delx(self): del self.__x\n" +" x = property(getx, setx, delx, \"I'm the 'x' property.\")" +msgstr "" +"class C:\n" +" def getx(self): return self.__x\n" +" def setx(self, value): self.__x = value\n" +" def delx(self): del self.__x\n" +" x = property(getx, setx, delx, \"I'm the 'x' property.\")" + +#: ../../howto/descriptor.rst:995 +msgid "" +"To see how :func:`property` is implemented in terms of the descriptor " +"protocol, here is a pure Python equivalent that implements most of the core " +"functionality:" +msgstr "" + +#: ../../howto/descriptor.rst:998 +msgid "" +"class Property:\n" +" \"Emulate PyProperty_Type() in Objects/descrobject.c\"\n" +"\n" +" def __init__(self, fget=None, fset=None, fdel=None, doc=None):\n" +" self.fget = fget\n" +" self.fset = fset\n" +" self.fdel = fdel\n" +" if doc is None and fget is not None:\n" +" doc = fget.__doc__\n" +" self.__doc__ = doc\n" +"\n" +" def __set_name__(self, owner, name):\n" +" self.__name__ = name\n" +"\n" +" def __get__(self, obj, objtype=None):\n" +" if obj is None:\n" +" return self\n" +" if self.fget is None:\n" +" raise AttributeError\n" +" return self.fget(obj)\n" +"\n" +" def __set__(self, obj, value):\n" +" if self.fset is None:\n" +" raise AttributeError\n" +" self.fset(obj, value)\n" +"\n" +" def __delete__(self, obj):\n" +" if self.fdel is None:\n" +" raise AttributeError\n" +" self.fdel(obj)\n" +"\n" +" def getter(self, fget):\n" +" return type(self)(fget, self.fset, self.fdel, self.__doc__)\n" +"\n" +" def setter(self, fset):\n" +" return type(self)(self.fget, fset, self.fdel, self.__doc__)\n" +"\n" +" def deleter(self, fdel):\n" +" return type(self)(self.fget, self.fset, fdel, self.__doc__)" +msgstr "" + +#: ../../howto/descriptor.rst:1122 +msgid "" +"The :func:`property` builtin helps whenever a user interface has granted " +"attribute access and then subsequent changes require the intervention of a " +"method." +msgstr "" + +#: ../../howto/descriptor.rst:1126 +msgid "" +"For instance, a spreadsheet class may grant access to a cell value through " +"``Cell('b10').value``. Subsequent improvements to the program require the " +"cell to be recalculated on every access; however, the programmer does not " +"want to affect existing client code accessing the attribute directly. The " +"solution is to wrap access to the value attribute in a property data " +"descriptor:" +msgstr "" + +#: ../../howto/descriptor.rst:1132 +msgid "" +"class Cell:\n" +" ...\n" +"\n" +" @property\n" +" def value(self):\n" +" \"Recalculate the cell before returning value\"\n" +" self.recalc()\n" +" return self._value" +msgstr "" + +#: ../../howto/descriptor.rst:1143 +msgid "" +"Either the built-in :func:`property` or our :func:`!Property` equivalent " +"would work in this example." +msgstr "" + +#: ../../howto/descriptor.rst:1148 +msgid "Functions and methods" +msgstr "" + +#: ../../howto/descriptor.rst:1150 +msgid "" +"Python's object oriented features are built upon a function based " +"environment. Using non-data descriptors, the two are merged seamlessly." +msgstr "" + +#: ../../howto/descriptor.rst:1153 +msgid "" +"Functions stored in class dictionaries get turned into methods when invoked. " +"Methods only differ from regular functions in that the object instance is " +"prepended to the other arguments. By convention, the instance is called " +"*self* but could be called *this* or any other variable name." +msgstr "" + +#: ../../howto/descriptor.rst:1158 +msgid "" +"Methods can be created manually with :class:`types.MethodType` which is " +"roughly equivalent to:" +msgstr "" + +#: ../../howto/descriptor.rst:1161 +msgid "" +"class MethodType:\n" +" \"Emulate PyMethod_Type in Objects/classobject.c\"\n" +"\n" +" def __init__(self, func, obj):\n" +" self.__func__ = func\n" +" self.__self__ = obj\n" +"\n" +" def __call__(self, *args, **kwargs):\n" +" func = self.__func__\n" +" obj = self.__self__\n" +" return func(obj, *args, **kwargs)\n" +"\n" +" def __getattribute__(self, name):\n" +" \"Emulate method_getset() in Objects/classobject.c\"\n" +" if name == '__doc__':\n" +" return self.__func__.__doc__\n" +" return object.__getattribute__(self, name)\n" +"\n" +" def __getattr__(self, name):\n" +" \"Emulate method_getattro() in Objects/classobject.c\"\n" +" return getattr(self.__func__, name)\n" +"\n" +" def __get__(self, obj, objtype=None):\n" +" \"Emulate method_descr_get() in Objects/classobject.c\"\n" +" return self" +msgstr "" + +#: ../../howto/descriptor.rst:1189 +msgid "" +"To support automatic creation of methods, functions include " +"the :meth:`~object.__get__` method for binding methods during attribute " +"access. This means that functions are non-data descriptors that return " +"bound methods during dotted lookup from an instance. Here's how it works:" +msgstr "" + +#: ../../howto/descriptor.rst:1194 +msgid "" +"class Function:\n" +" ...\n" +"\n" +" def __get__(self, obj, objtype=None):\n" +" \"Simulate func_descr_get() in Objects/funcobject.c\"\n" +" if obj is None:\n" +" return self\n" +" return MethodType(self, obj)" +msgstr "" + +#: ../../howto/descriptor.rst:1205 +msgid "" +"Running the following class in the interpreter shows how the function " +"descriptor works in practice:" +msgstr "" + +#: ../../howto/descriptor.rst:1208 +msgid "" +"class D:\n" +" def f(self):\n" +" return self\n" +"\n" +"class D2:\n" +" pass" +msgstr "" +"class D:\n" +" def f(self):\n" +" return self\n" +"\n" +"class D2:\n" +" pass" + +#: ../../howto/descriptor.rst:1226 +msgid "" +"The function has a :term:`qualified name` attribute to support introspection:" +msgstr "" + +#: ../../howto/descriptor.rst:1228 +msgid "" +">>> D.f.__qualname__\n" +"'D.f'" +msgstr "" +">>> D.f.__qualname__\n" +"'D.f'" + +#: ../../howto/descriptor.rst:1233 +msgid "" +"Accessing the function through the class dictionary does not " +"invoke :meth:`~object.__get__`. Instead, it just returns the underlying " +"function object::" +msgstr "" + +#: ../../howto/descriptor.rst:1236 +msgid "" +">>> D.__dict__['f']\n" +"" +msgstr "" +">>> D.__dict__['f']\n" +"" + +#: ../../howto/descriptor.rst:1239 +msgid "" +"Dotted access from a class calls :meth:`~object.__get__` which just returns " +"the underlying function unchanged::" +msgstr "" + +#: ../../howto/descriptor.rst:1242 +msgid "" +">>> D.f\n" +"" +msgstr "" +">>> D.f\n" +"" + +#: ../../howto/descriptor.rst:1245 +msgid "" +"The interesting behavior occurs during dotted access from an instance. The " +"dotted lookup calls :meth:`~object.__get__` which returns a bound method " +"object::" +msgstr "" + +#: ../../howto/descriptor.rst:1248 +msgid "" +">>> d = D()\n" +">>> d.f\n" +">" +msgstr "" +">>> d = D()\n" +">>> d.f\n" +">" + +#: ../../howto/descriptor.rst:1252 +msgid "" +"Internally, the bound method stores the underlying function and the bound " +"instance::" +msgstr "" + +#: ../../howto/descriptor.rst:1255 +msgid "" +">>> d.f.__func__\n" +"\n" +"\n" +">>> d.f.__self__\n" +"<__main__.D object at 0x00B18C90>" +msgstr "" +">>> d.f.__func__\n" +"\n" +"\n" +">>> d.f.__self__\n" +"<__main__.D object at 0x00B18C90>" + +#: ../../howto/descriptor.rst:1261 +msgid "" +"If you have ever wondered where *self* comes from in regular methods or " +"where *cls* comes from in class methods, this is it!" +msgstr "" + +#: ../../howto/descriptor.rst:1266 +msgid "Kinds of methods" +msgstr "" + +#: ../../howto/descriptor.rst:1268 +msgid "" +"Non-data descriptors provide a simple mechanism for variations on the usual " +"patterns of binding functions into methods." +msgstr "" + +#: ../../howto/descriptor.rst:1271 +msgid "" +"To recap, functions have a :meth:`~object.__get__` method so that they can " +"be converted to a method when accessed as attributes. The non-data " +"descriptor transforms an ``obj.f(*args)`` call into ``f(obj, *args)``. " +"Calling ``cls.f(*args)`` becomes ``f(*args)``." +msgstr "" + +#: ../../howto/descriptor.rst:1276 +msgid "This chart summarizes the binding and its two most useful variants:" +msgstr "" + +#: ../../howto/descriptor.rst:1279 +msgid "Transformation" +msgstr "" + +#: ../../howto/descriptor.rst:1279 +msgid "Called from an object" +msgstr "" + +#: ../../howto/descriptor.rst:1279 +msgid "Called from a class" +msgstr "" + +#: ../../howto/descriptor.rst:1282 +msgid "function" +msgstr "函式" + +#: ../../howto/descriptor.rst:1282 +msgid "f(obj, \\*args)" +msgstr "f(obj, \\*args)" + +#: ../../howto/descriptor.rst:1282 ../../howto/descriptor.rst:1284 +msgid "f(\\*args)" +msgstr "f(\\*args)" + +#: ../../howto/descriptor.rst:1284 +msgid "staticmethod" +msgstr "staticmethod" + +#: ../../howto/descriptor.rst:1286 +msgid "classmethod" +msgstr "classmethod" + +#: ../../howto/descriptor.rst:1286 +msgid "f(type(obj), \\*args)" +msgstr "f(type(obj), \\*args)" + +#: ../../howto/descriptor.rst:1286 +msgid "f(cls, \\*args)" +msgstr "f(cls, \\*args)" + +#: ../../howto/descriptor.rst:1291 +msgid "Static methods" +msgstr "" + +#: ../../howto/descriptor.rst:1293 +msgid "" +"Static methods return the underlying function without changes. Calling " +"either ``c.f`` or ``C.f`` is the equivalent of a direct lookup into " +"``object.__getattribute__(c, \"f\")`` or ``object.__getattribute__(C, " +"\"f\")``. As a result, the function becomes identically accessible from " +"either an object or a class." +msgstr "" + +#: ../../howto/descriptor.rst:1299 +msgid "" +"Good candidates for static methods are methods that do not reference the " +"``self`` variable." +msgstr "" + +#: ../../howto/descriptor.rst:1302 +msgid "" +"For instance, a statistics package may include a container class for " +"experimental data. The class provides normal methods for computing the " +"average, mean, median, and other descriptive statistics that depend on the " +"data. However, there may be useful functions which are conceptually related " +"but do not depend on the data. For instance, ``erf(x)`` is handy conversion " +"routine that comes up in statistical work but does not directly depend on a " +"particular dataset. It can be called either from an object or the class: " +"``s.erf(1.5) --> 0.9332`` or ``Sample.erf(1.5) --> 0.9332``." +msgstr "" + +#: ../../howto/descriptor.rst:1311 +msgid "" +"Since static methods return the underlying function with no changes, the " +"example calls are unexciting:" +msgstr "" + +#: ../../howto/descriptor.rst:1314 +msgid "" +"class E:\n" +" @staticmethod\n" +" def f(x):\n" +" return x * 10" +msgstr "" +"class E:\n" +" @staticmethod\n" +" def f(x):\n" +" return x * 10" + +#: ../../howto/descriptor.rst:1321 +msgid "" +">>> E.f(3)\n" +"30\n" +">>> E().f(3)\n" +"30" +msgstr "" +">>> E.f(3)\n" +"30\n" +">>> E().f(3)\n" +"30" + +#: ../../howto/descriptor.rst:1328 +msgid "" +"Using the non-data descriptor protocol, a pure Python version " +"of :func:`staticmethod` would look like this:" +msgstr "" + +#: ../../howto/descriptor.rst:1331 +msgid "" +"import functools\n" +"\n" +"class StaticMethod:\n" +" \"Emulate PyStaticMethod_Type() in Objects/funcobject.c\"\n" +"\n" +" def __init__(self, f):\n" +" self.f = f\n" +" functools.update_wrapper(self, f)\n" +"\n" +" def __get__(self, obj, objtype=None):\n" +" return self.f\n" +"\n" +" def __call__(self, *args, **kwds):\n" +" return self.f(*args, **kwds)\n" +"\n" +" @property\n" +" def __annotations__(self):\n" +" return self.f.__annotations__" +msgstr "" + +#: ../../howto/descriptor.rst:1352 +msgid "" +"The :func:`functools.update_wrapper` call adds a ``__wrapped__`` attribute " +"that refers to the underlying function. Also it carries forward the " +"attributes necessary to make the wrapper look like the wrapped function, " +"including :attr:`~function.__name__`, :attr:`~function.__qualname__`, " +"and :attr:`~function.__doc__`." +msgstr "" + +#: ../../howto/descriptor.rst:1421 +msgid "Class methods" +msgstr "" + +#: ../../howto/descriptor.rst:1423 +msgid "" +"Unlike static methods, class methods prepend the class reference to the " +"argument list before calling the function. This format is the same for " +"whether the caller is an object or a class:" +msgstr "" + +#: ../../howto/descriptor.rst:1427 +msgid "" +"class F:\n" +" @classmethod\n" +" def f(cls, x):\n" +" return cls.__name__, x" +msgstr "" +"class F:\n" +" @classmethod\n" +" def f(cls, x):\n" +" return cls.__name__, x" + +#: ../../howto/descriptor.rst:1434 +msgid "" +">>> F.f(3)\n" +"('F', 3)\n" +">>> F().f(3)\n" +"('F', 3)" +msgstr "" +">>> F.f(3)\n" +"('F', 3)\n" +">>> F().f(3)\n" +"('F', 3)" + +#: ../../howto/descriptor.rst:1441 +msgid "" +"This behavior is useful whenever the method only needs to have a class " +"reference and does not rely on data stored in a specific instance. One use " +"for class methods is to create alternate class constructors. For example, " +"the classmethod :func:`dict.fromkeys` creates a new dictionary from a list " +"of keys. The pure Python equivalent is:" +msgstr "" + +#: ../../howto/descriptor.rst:1447 +msgid "" +"class Dict(dict):\n" +" @classmethod\n" +" def fromkeys(cls, iterable, value=None):\n" +" \"Emulate dict_fromkeys() in Objects/dictobject.c\"\n" +" d = cls()\n" +" for key in iterable:\n" +" d[key] = value\n" +" return d" +msgstr "" + +#: ../../howto/descriptor.rst:1458 +msgid "Now a new dictionary of unique keys can be constructed like this:" +msgstr "" + +#: ../../howto/descriptor.rst:1460 +msgid "" +">>> d = Dict.fromkeys('abracadabra')\n" +">>> type(d) is Dict\n" +"True\n" +">>> d\n" +"{'a': None, 'b': None, 'r': None, 'c': None, 'd': None}" +msgstr "" +">>> d = Dict.fromkeys('abracadabra')\n" +">>> type(d) is Dict\n" +"True\n" +">>> d\n" +"{'a': None, 'b': None, 'r': None, 'c': None, 'd': None}" + +#: ../../howto/descriptor.rst:1468 +msgid "" +"Using the non-data descriptor protocol, a pure Python version " +"of :func:`classmethod` would look like this:" +msgstr "" + +#: ../../howto/descriptor.rst:1471 +msgid "" +"import functools\n" +"\n" +"class ClassMethod:\n" +" \"Emulate PyClassMethod_Type() in Objects/funcobject.c\"\n" +"\n" +" def __init__(self, f):\n" +" self.f = f\n" +" functools.update_wrapper(self, f)\n" +"\n" +" def __get__(self, obj, cls=None):\n" +" if cls is None:\n" +" cls = type(obj)\n" +" return MethodType(self.f, cls)" +msgstr "" + +#: ../../howto/descriptor.rst:1533 +msgid "" +"The :func:`functools.update_wrapper` call in ``ClassMethod`` adds a " +"``__wrapped__`` attribute that refers to the underlying function. Also it " +"carries forward the attributes necessary to make the wrapper look like the " +"wrapped " +"function: :attr:`~function.__name__`, :attr:`~function.__qualname__`, :attr:`~function.__doc__`, " +"and :attr:`~function.__annotations__`." +msgstr "" + +#: ../../howto/descriptor.rst:1542 +msgid "Member objects and __slots__" +msgstr "" + +#: ../../howto/descriptor.rst:1544 +msgid "" +"When a class defines ``__slots__``, it replaces instance dictionaries with a " +"fixed-length array of slot values. From a user point of view that has " +"several effects:" +msgstr "" + +#: ../../howto/descriptor.rst:1548 +msgid "" +"1. Provides immediate detection of bugs due to misspelled attribute " +"assignments. Only attribute names specified in ``__slots__`` are allowed:" +msgstr "" + +#: ../../howto/descriptor.rst:1551 +msgid "" +"class Vehicle:\n" +" __slots__ = ('id_number', 'make', 'model')" +msgstr "" +"class Vehicle:\n" +" __slots__ = ('id_number', 'make', 'model')" + +#: ../../howto/descriptor.rst:1556 +msgid "" +">>> auto = Vehicle()\n" +">>> auto.id_nubmer = 'VYE483814LQEX'\n" +"Traceback (most recent call last):\n" +" ...\n" +"AttributeError: 'Vehicle' object has no attribute 'id_nubmer'" +msgstr "" +">>> auto = Vehicle()\n" +">>> auto.id_nubmer = 'VYE483814LQEX'\n" +"Traceback (most recent call last):\n" +" ...\n" +"AttributeError: 'Vehicle' object has no attribute 'id_nubmer'" + +#: ../../howto/descriptor.rst:1564 +msgid "" +"2. Helps create immutable objects where descriptors manage access to private " +"attributes stored in ``__slots__``:" +msgstr "" + +#: ../../howto/descriptor.rst:1567 +msgid "" +"class Immutable:\n" +"\n" +" __slots__ = ('_dept', '_name') # Replace the instance " +"dictionary\n" +"\n" +" def __init__(self, dept, name):\n" +" self._dept = dept # Store to private attribute\n" +" self._name = name # Store to private attribute\n" +"\n" +" @property # Read-only descriptor\n" +" def dept(self):\n" +" return self._dept\n" +"\n" +" @property\n" +" def name(self): # Read-only descriptor\n" +" return self._name" +msgstr "" + +#: ../../howto/descriptor.rst:1585 +msgid "" +">>> mark = Immutable('Botany', 'Mark Watney')\n" +">>> mark.dept\n" +"'Botany'\n" +">>> mark.dept = 'Space Pirate'\n" +"Traceback (most recent call last):\n" +" ...\n" +"AttributeError: property 'dept' of 'Immutable' object has no setter\n" +">>> mark.location = 'Mars'\n" +"Traceback (most recent call last):\n" +" ...\n" +"AttributeError: 'Immutable' object has no attribute 'location'" +msgstr "" +">>> mark = Immutable('Botany', 'Mark Watney')\n" +">>> mark.dept\n" +"'Botany'\n" +">>> mark.dept = 'Space Pirate'\n" +"Traceback (most recent call last):\n" +" ...\n" +"AttributeError: property 'dept' of 'Immutable' object has no setter\n" +">>> mark.location = 'Mars'\n" +"Traceback (most recent call last):\n" +" ...\n" +"AttributeError: 'Immutable' object has no attribute 'location'" + +#: ../../howto/descriptor.rst:1599 +msgid "" +"3. Saves memory. On a 64-bit Linux build, an instance with two attributes " +"takes 48 bytes with ``__slots__`` and 152 bytes without. This `flyweight " +"design pattern `_ likely " +"only matters when a large number of instances are going to be created." +msgstr "" + +#: ../../howto/descriptor.rst:1604 +msgid "" +"4. Improves speed. Reading instance variables is 35% faster with " +"``__slots__`` (as measured with Python 3.10 on an Apple M1 processor)." +msgstr "" + +#: ../../howto/descriptor.rst:1607 +msgid "" +"5. Blocks tools like :func:`functools.cached_property` which require an " +"instance dictionary to function correctly:" +msgstr "" + +#: ../../howto/descriptor.rst:1610 +msgid "" +"from functools import cached_property\n" +"\n" +"class CP:\n" +" __slots__ = () # Eliminates the instance dict\n" +"\n" +" @cached_property # Requires an instance dict\n" +" def pi(self):\n" +" return 4 * sum((-1.0)**n / (2.0*n + 1.0)\n" +" for n in reversed(range(100_000)))" +msgstr "" + +#: ../../howto/descriptor.rst:1622 +msgid "" +">>> CP().pi\n" +"Traceback (most recent call last):\n" +" ...\n" +"TypeError: No '__dict__' attribute on 'CP' instance to cache 'pi' property." +msgstr "" +">>> CP().pi\n" +"Traceback (most recent call last):\n" +" ...\n" +"TypeError: No '__dict__' attribute on 'CP' instance to cache 'pi' property." + +#: ../../howto/descriptor.rst:1629 +msgid "" +"It is not possible to create an exact drop-in pure Python version of " +"``__slots__`` because it requires direct access to C structures and control " +"over object memory allocation. However, we can build a mostly faithful " +"simulation where the actual C structure for slots is emulated by a private " +"``_slotvalues`` list. Reads and writes to that private structure are " +"managed by member descriptors:" +msgstr "" + +#: ../../howto/descriptor.rst:1636 +msgid "" +"null = object()\n" +"\n" +"class Member:\n" +"\n" +" def __init__(self, name, clsname, offset):\n" +" 'Emulate PyMemberDef in Include/structmember.h'\n" +" # Also see descr_new() in Objects/descrobject.c\n" +" self.name = name\n" +" self.clsname = clsname\n" +" self.offset = offset\n" +"\n" +" def __get__(self, obj, objtype=None):\n" +" 'Emulate member_get() in Objects/descrobject.c'\n" +" # Also see PyMember_GetOne() in Python/structmember.c\n" +" if obj is None:\n" +" return self\n" +" value = obj._slotvalues[self.offset]\n" +" if value is null:\n" +" raise AttributeError(self.name)\n" +" return value\n" +"\n" +" def __set__(self, obj, value):\n" +" 'Emulate member_set() in Objects/descrobject.c'\n" +" obj._slotvalues[self.offset] = value\n" +"\n" +" def __delete__(self, obj):\n" +" 'Emulate member_delete() in Objects/descrobject.c'\n" +" value = obj._slotvalues[self.offset]\n" +" if value is null:\n" +" raise AttributeError(self.name)\n" +" obj._slotvalues[self.offset] = null\n" +"\n" +" def __repr__(self):\n" +" 'Emulate member_repr() in Objects/descrobject.c'\n" +" return f''" +msgstr "" + +#: ../../howto/descriptor.rst:1674 +msgid "" +"The :meth:`!type.__new__` method takes care of adding member objects to " +"class variables:" +msgstr "" + +#: ../../howto/descriptor.rst:1677 +msgid "" +"class Type(type):\n" +" 'Simulate how the type metaclass adds member objects for slots'\n" +"\n" +" def __new__(mcls, clsname, bases, mapping, **kwargs):\n" +" 'Emulate type_new() in Objects/typeobject.c'\n" +" # type_new() calls PyTypeReady() which calls add_methods()\n" +" slot_names = mapping.get('slot_names', [])\n" +" for offset, name in enumerate(slot_names):\n" +" mapping[name] = Member(name, clsname, offset)\n" +" return type.__new__(mcls, clsname, bases, mapping, **kwargs)" +msgstr "" + +#: ../../howto/descriptor.rst:1690 +msgid "" +"The :meth:`object.__new__` method takes care of creating instances that have " +"slots instead of an instance dictionary. Here is a rough simulation in pure " +"Python:" +msgstr "" + +#: ../../howto/descriptor.rst:1694 +msgid "" +"class Object:\n" +" 'Simulate how object.__new__() allocates memory for __slots__'\n" +"\n" +" def __new__(cls, *args, **kwargs):\n" +" 'Emulate object_new() in Objects/typeobject.c'\n" +" inst = super().__new__(cls)\n" +" if hasattr(cls, 'slot_names'):\n" +" empty_slots = [null] * len(cls.slot_names)\n" +" object.__setattr__(inst, '_slotvalues', empty_slots)\n" +" return inst\n" +"\n" +" def __setattr__(self, name, value):\n" +" 'Emulate _PyObject_GenericSetAttrWithDict() Objects/object.c'\n" +" cls = type(self)\n" +" if hasattr(cls, 'slot_names') and name not in cls.slot_names:\n" +" raise AttributeError(\n" +" f'{cls.__name__!r} object has no attribute {name!r}'\n" +" )\n" +" super().__setattr__(name, value)\n" +"\n" +" def __delattr__(self, name):\n" +" 'Emulate _PyObject_GenericSetAttrWithDict() Objects/object.c'\n" +" cls = type(self)\n" +" if hasattr(cls, 'slot_names') and name not in cls.slot_names:\n" +" raise AttributeError(\n" +" f'{cls.__name__!r} object has no attribute {name!r}'\n" +" )\n" +" super().__delattr__(name)" +msgstr "" + +#: ../../howto/descriptor.rst:1725 +msgid "" +"To use the simulation in a real class, just inherit from :class:`!Object` " +"and set the :term:`metaclass` to :class:`Type`:" +msgstr "" + +#: ../../howto/descriptor.rst:1728 +msgid "" +"class H(Object, metaclass=Type):\n" +" 'Instance variables stored in slots'\n" +"\n" +" slot_names = ['x', 'y']\n" +"\n" +" def __init__(self, x, y):\n" +" self.x = x\n" +" self.y = y" +msgstr "" + +#: ../../howto/descriptor.rst:1739 +msgid "" +"At this point, the metaclass has loaded member objects for *x* and *y*::" +msgstr "" + +#: ../../howto/descriptor.rst:1741 +msgid "" +">>> from pprint import pp\n" +">>> pp(dict(vars(H)))\n" +"{'__module__': '__main__',\n" +" '__doc__': 'Instance variables stored in slots',\n" +" 'slot_names': ['x', 'y'],\n" +" '__init__': ,\n" +" 'x': ,\n" +" 'y': }" +msgstr "" +">>> from pprint import pp\n" +">>> pp(dict(vars(H)))\n" +"{'__module__': '__main__',\n" +" '__doc__': 'Instance variables stored in slots',\n" +" 'slot_names': ['x', 'y'],\n" +" '__init__': ,\n" +" 'x': ,\n" +" 'y': }" + +#: ../../howto/descriptor.rst:1760 +msgid "" +"When instances are created, they have a ``slot_values`` list where the " +"attributes are stored:" +msgstr "" + +#: ../../howto/descriptor.rst:1763 +msgid "" +">>> h = H(10, 20)\n" +">>> vars(h)\n" +"{'_slotvalues': [10, 20]}\n" +">>> h.x = 55\n" +">>> vars(h)\n" +"{'_slotvalues': [55, 20]}" +msgstr "" +">>> h = H(10, 20)\n" +">>> vars(h)\n" +"{'_slotvalues': [10, 20]}\n" +">>> h.x = 55\n" +">>> vars(h)\n" +"{'_slotvalues': [55, 20]}" + +#: ../../howto/descriptor.rst:1772 +msgid "Misspelled or unassigned attributes will raise an exception:" +msgstr "" + +#: ../../howto/descriptor.rst:1774 +msgid "" +">>> h.xz\n" +"Traceback (most recent call last):\n" +" ...\n" +"AttributeError: 'H' object has no attribute 'xz'" +msgstr "" +">>> h.xz\n" +"Traceback (most recent call last):\n" +" ...\n" +"AttributeError: 'H' object has no attribute 'xz'" diff --git a/howto/enum.po b/howto/enum.po index b4df357415..4c805c643d 100644 --- a/howto/enum.po +++ b/howto/enum.po @@ -1,2908 +1,2908 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -#, fuzzy -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-12 00:14+0000\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \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" - -#: ../../howto/enum.rst:5 -msgid "Enum HOWTO" -msgstr "" - -#: ../../howto/enum.rst:11 -msgid "" -"An :class:`Enum` is a set of symbolic names bound to unique values. They " -"are similar to global variables, but they offer a more useful :func:`repr`, " -"grouping, type-safety, and a few other features." -msgstr "" - -#: ../../howto/enum.rst:15 -msgid "" -"They are most useful when you have a variable that can take one of a limited " -"selection of values. For example, the days of the week::" -msgstr "" - -#: ../../howto/enum.rst:18 -msgid "" -">>> from enum import Enum\n" -">>> class Weekday(Enum):\n" -"... MONDAY = 1\n" -"... TUESDAY = 2\n" -"... WEDNESDAY = 3\n" -"... THURSDAY = 4\n" -"... FRIDAY = 5\n" -"... SATURDAY = 6\n" -"... SUNDAY = 7" -msgstr "" -">>> from enum import Enum\n" -">>> class Weekday(Enum):\n" -"... MONDAY = 1\n" -"... TUESDAY = 2\n" -"... WEDNESDAY = 3\n" -"... THURSDAY = 4\n" -"... FRIDAY = 5\n" -"... SATURDAY = 6\n" -"... SUNDAY = 7" - -#: ../../howto/enum.rst:28 -msgid "Or perhaps the RGB primary colors::" -msgstr "" - -#: ../../howto/enum.rst:30 -msgid "" -">>> from enum import Enum\n" -">>> class Color(Enum):\n" -"... RED = 1\n" -"... GREEN = 2\n" -"... BLUE = 3" -msgstr "" -">>> from enum import Enum\n" -">>> class Color(Enum):\n" -"... RED = 1\n" -"... GREEN = 2\n" -"... BLUE = 3" - -#: ../../howto/enum.rst:36 -msgid "" -"As you can see, creating an :class:`Enum` is as simple as writing a class " -"that inherits from :class:`Enum` itself." -msgstr "" - -#: ../../howto/enum.rst:39 -msgid "Case of Enum Members" -msgstr "" - -#: ../../howto/enum.rst:41 -msgid "" -"Because Enums are used to represent constants, and to help avoid issues with " -"name clashes between mixin-class methods/attributes and enum names, we " -"strongly recommend using UPPER_CASE names for members, and will be using " -"that style in our examples." -msgstr "" - -#: ../../howto/enum.rst:46 -msgid "" -"Depending on the nature of the enum a member's value may or may not be " -"important, but either way that value can be used to get the corresponding " -"member::" -msgstr "" - -#: ../../howto/enum.rst:50 -msgid "" -">>> Weekday(3)\n" -"" -msgstr "" -">>> Weekday(3)\n" -"" - -#: ../../howto/enum.rst:53 -msgid "" -"As you can see, the ``repr()`` of a member shows the enum name, the member " -"name, and the value. The ``str()`` of a member shows only the enum name and " -"member name::" -msgstr "" - -#: ../../howto/enum.rst:57 -msgid "" -">>> print(Weekday.THURSDAY)\n" -"Weekday.THURSDAY" -msgstr "" -">>> print(Weekday.THURSDAY)\n" -"Weekday.THURSDAY" - -#: ../../howto/enum.rst:60 -msgid "The *type* of an enumeration member is the enum it belongs to::" -msgstr "" - -#: ../../howto/enum.rst:62 -msgid "" -">>> type(Weekday.MONDAY)\n" -"\n" -">>> isinstance(Weekday.FRIDAY, Weekday)\n" -"True" -msgstr "" -">>> type(Weekday.MONDAY)\n" -"\n" -">>> isinstance(Weekday.FRIDAY, Weekday)\n" -"True>>> type(Weekday.MONDAY)\n" -"\n" -">>> isinstance(Weekday.FRIDAY, Weekday)\n" -"True" - -#: ../../howto/enum.rst:67 -msgid "Enum members have an attribute that contains just their :attr:`!name`::" -msgstr "" - -#: ../../howto/enum.rst:69 -msgid "" -">>> print(Weekday.TUESDAY.name)\n" -"TUESDAY" -msgstr "" -">>> print(Weekday.TUESDAY.name)\n" -"TUESDAY" - -#: ../../howto/enum.rst:72 -msgid "Likewise, they have an attribute for their :attr:`!value`::" -msgstr "" - -#: ../../howto/enum.rst:75 -msgid "" -">>> Weekday.WEDNESDAY.value\n" -"3" -msgstr "" -">>> Weekday.WEDNESDAY.value\n" -"3" - -#: ../../howto/enum.rst:78 -msgid "" -"Unlike many languages that treat enumerations solely as name/value pairs, " -"Python Enums can have behavior added. For example, :class:`datetime.date` " -"has two methods for returning the weekday: :meth:`~datetime.date.weekday` " -"and :meth:`~datetime.date.isoweekday`. The difference is that one of them " -"counts from 0-6 and the other from 1-7. Rather than keep track of that " -"ourselves we can add a method to the :class:`!Weekday` enum to extract the " -"day from the :class:`~datetime.date` instance and return the matching enum " -"member::" -msgstr "" - -#: ../../howto/enum.rst:87 -msgid "" -"@classmethod\n" -"def from_date(cls, date):\n" -" return cls(date.isoweekday())" -msgstr "" -"@classmethod\n" -"def from_date(cls, date):\n" -" return cls(date.isoweekday())" - -#: ../../howto/enum.rst:91 -msgid "The complete :class:`!Weekday` enum now looks like this::" -msgstr "" - -#: ../../howto/enum.rst:93 -msgid "" -">>> class Weekday(Enum):\n" -"... MONDAY = 1\n" -"... TUESDAY = 2\n" -"... WEDNESDAY = 3\n" -"... THURSDAY = 4\n" -"... FRIDAY = 5\n" -"... SATURDAY = 6\n" -"... SUNDAY = 7\n" -"... #\n" -"... @classmethod\n" -"... def from_date(cls, date):\n" -"... return cls(date.isoweekday())" -msgstr "" -">>> class Weekday(Enum):\n" -"... MONDAY = 1\n" -"... TUESDAY = 2\n" -"... WEDNESDAY = 3\n" -"... THURSDAY = 4\n" -"... FRIDAY = 5\n" -"... SATURDAY = 6\n" -"... SUNDAY = 7\n" -"... #\n" -"... @classmethod\n" -"... def from_date(cls, date):\n" -"... return cls(date.isoweekday())" - -#: ../../howto/enum.rst:106 -msgid "Now we can find out what today is! Observe::" -msgstr "" - -#: ../../howto/enum.rst:108 -msgid "" -">>> from datetime import date\n" -">>> Weekday.from_date(date.today())\n" -"" -msgstr "" -">>> from datetime import date\n" -">>> Weekday.from_date(date.today())\n" -"" - -#: ../../howto/enum.rst:112 -msgid "" -"Of course, if you're reading this on some other day, you'll see that day " -"instead." -msgstr "" - -#: ../../howto/enum.rst:114 -msgid "" -"This :class:`!Weekday` enum is great if our variable only needs one day, but " -"what if we need several? Maybe we're writing a function to plot chores " -"during a week, and don't want to use a :class:`list` -- we could use a " -"different type of :class:`Enum`::" -msgstr "" - -#: ../../howto/enum.rst:119 -msgid "" -">>> from enum import Flag\n" -">>> class Weekday(Flag):\n" -"... MONDAY = 1\n" -"... TUESDAY = 2\n" -"... WEDNESDAY = 4\n" -"... THURSDAY = 8\n" -"... FRIDAY = 16\n" -"... SATURDAY = 32\n" -"... SUNDAY = 64" -msgstr "" -">>> from enum import Flag\n" -">>> class Weekday(Flag):\n" -"... MONDAY = 1\n" -"... TUESDAY = 2\n" -"... WEDNESDAY = 4\n" -"... THURSDAY = 8\n" -"... FRIDAY = 16\n" -"... SATURDAY = 32\n" -"... SUNDAY = 64" - -#: ../../howto/enum.rst:129 -msgid "" -"We've changed two things: we're inherited from :class:`Flag`, and the values " -"are all powers of 2." -msgstr "" - -#: ../../howto/enum.rst:132 -msgid "" -"Just like the original :class:`!Weekday` enum above, we can have a single " -"selection::" -msgstr "" - -#: ../../howto/enum.rst:134 -msgid "" -">>> first_week_day = Weekday.MONDAY\n" -">>> first_week_day\n" -"" -msgstr "" -">>> first_week_day = Weekday.MONDAY\n" -">>> first_week_day\n" -"" - -#: ../../howto/enum.rst:138 -msgid "" -"But :class:`Flag` also allows us to combine several members into a single " -"variable::" -msgstr "" - -#: ../../howto/enum.rst:141 -msgid "" -">>> weekend = Weekday.SATURDAY | Weekday.SUNDAY\n" -">>> weekend\n" -"" -msgstr "" -">>> weekend = Weekday.SATURDAY | Weekday.SUNDAY\n" -">>> weekend\n" -"" - -#: ../../howto/enum.rst:145 -msgid "You can even iterate over a :class:`Flag` variable::" -msgstr "" - -#: ../../howto/enum.rst:147 -msgid "" -">>> for day in weekend:\n" -"... print(day)\n" -"Weekday.SATURDAY\n" -"Weekday.SUNDAY" -msgstr "" -">>> for day in weekend:\n" -"... print(day)\n" -"Weekday.SATURDAY\n" -"Weekday.SUNDAY" - -#: ../../howto/enum.rst:152 -msgid "Okay, let's get some chores set up::" -msgstr "" - -#: ../../howto/enum.rst:154 -msgid "" -">>> chores_for_ethan = {\n" -"... 'feed the cat': Weekday.MONDAY | Weekday.WEDNESDAY | Weekday." -"FRIDAY,\n" -"... 'do the dishes': Weekday.TUESDAY | Weekday.THURSDAY,\n" -"... 'answer SO questions': Weekday.SATURDAY,\n" -"... }" -msgstr "" -">>> chores_for_ethan = {\n" -"... 'feed the cat': Weekday.MONDAY | Weekday.WEDNESDAY | Weekday." -"FRIDAY,\n" -"... 'do the dishes': Weekday.TUESDAY | Weekday.THURSDAY,\n" -"... 'answer SO questions': Weekday.SATURDAY,\n" -"... }" - -#: ../../howto/enum.rst:160 -msgid "And a function to display the chores for a given day::" -msgstr "" - -#: ../../howto/enum.rst:162 -msgid "" -">>> def show_chores(chores, day):\n" -"... for chore, days in chores.items():\n" -"... if day in days:\n" -"... print(chore)\n" -"...\n" -">>> show_chores(chores_for_ethan, Weekday.SATURDAY)\n" -"answer SO questions" -msgstr "" -">>> def show_chores(chores, day):\n" -"... for chore, days in chores.items():\n" -"... if day in days:\n" -"... print(chore)\n" -"...\n" -">>> show_chores(chores_for_ethan, Weekday.SATURDAY)\n" -"answer SO questions" - -#: ../../howto/enum.rst:170 -msgid "" -"In cases where the actual values of the members do not matter, you can save " -"yourself some work and use :func:`auto` for the values::" -msgstr "" - -#: ../../howto/enum.rst:173 -msgid "" -">>> from enum import auto\n" -">>> class Weekday(Flag):\n" -"... MONDAY = auto()\n" -"... TUESDAY = auto()\n" -"... WEDNESDAY = auto()\n" -"... THURSDAY = auto()\n" -"... FRIDAY = auto()\n" -"... SATURDAY = auto()\n" -"... SUNDAY = auto()\n" -"... WEEKEND = SATURDAY | SUNDAY" -msgstr "" -">>> from enum import auto\n" -">>> class Weekday(Flag):\n" -"... MONDAY = auto()\n" -"... TUESDAY = auto()\n" -"... WEDNESDAY = auto()\n" -"... THURSDAY = auto()\n" -"... FRIDAY = auto()\n" -"... SATURDAY = auto()\n" -"... SUNDAY = auto()\n" -"... WEEKEND = SATURDAY | SUNDAY" - -#: ../../howto/enum.rst:189 -msgid "Programmatic access to enumeration members and their attributes" -msgstr "" - -#: ../../howto/enum.rst:191 -msgid "" -"Sometimes it's useful to access members in enumerations programmatically (i." -"e. situations where ``Color.RED`` won't do because the exact color is not " -"known at program-writing time). ``Enum`` allows such access::" -msgstr "" - -#: ../../howto/enum.rst:195 -msgid "" -">>> Color(1)\n" -"\n" -">>> Color(3)\n" -"" -msgstr "" -">>> Color(1)\n" -"\n" -">>> Color(3)\n" -"" - -#: ../../howto/enum.rst:200 -msgid "If you want to access enum members by *name*, use item access::" -msgstr "" - -#: ../../howto/enum.rst:202 -msgid "" -">>> Color['RED']\n" -"\n" -">>> Color['GREEN']\n" -"" -msgstr "" -">>> Color['RED']\n" -"\n" -">>> Color['GREEN']\n" -"" - -#: ../../howto/enum.rst:207 -msgid "" -"If you have an enum member and need its :attr:`!name` or :attr:`!value`::" -msgstr "" - -#: ../../howto/enum.rst:209 -msgid "" -">>> member = Color.RED\n" -">>> member.name\n" -"'RED'\n" -">>> member.value\n" -"1" -msgstr "" -">>> member = Color.RED\n" -">>> member.name\n" -"'RED'\n" -">>> member.value\n" -"1" - -#: ../../howto/enum.rst:217 -msgid "Duplicating enum members and values" -msgstr "" - -#: ../../howto/enum.rst:219 -msgid "Having two enum members with the same name is invalid::" -msgstr "" - -#: ../../howto/enum.rst:221 -msgid "" -">>> class Shape(Enum):\n" -"... SQUARE = 2\n" -"... SQUARE = 3\n" -"...\n" -"Traceback (most recent call last):\n" -"...\n" -"TypeError: 'SQUARE' already defined as 2" -msgstr "" -">>> class Shape(Enum):\n" -"... SQUARE = 2\n" -"... SQUARE = 3\n" -"...\n" -"Traceback (most recent call last):\n" -"...\n" -"TypeError: 'SQUARE' already defined as 2" - -#: ../../howto/enum.rst:229 -msgid "" -"However, an enum member can have other names associated with it. Given two " -"entries ``A`` and ``B`` with the same value (and ``A`` defined first), ``B`` " -"is an alias for the member ``A``. By-value lookup of the value of ``A`` " -"will return the member ``A``. By-name lookup of ``A`` will return the " -"member ``A``. By-name lookup of ``B`` will also return the member ``A``::" -msgstr "" - -#: ../../howto/enum.rst:235 -msgid "" -">>> class Shape(Enum):\n" -"... SQUARE = 2\n" -"... DIAMOND = 1\n" -"... CIRCLE = 3\n" -"... ALIAS_FOR_SQUARE = 2\n" -"...\n" -">>> Shape.SQUARE\n" -"\n" -">>> Shape.ALIAS_FOR_SQUARE\n" -"\n" -">>> Shape(2)\n" -"" -msgstr "" -">>> class Shape(Enum):\n" -"... SQUARE = 2\n" -"... DIAMOND = 1\n" -"... CIRCLE = 3\n" -"... ALIAS_FOR_SQUARE = 2\n" -"...\n" -">>> Shape.SQUARE\n" -"\n" -">>> Shape.ALIAS_FOR_SQUARE\n" -"\n" -">>> Shape(2)\n" -"" - -#: ../../howto/enum.rst:250 -msgid "" -"Attempting to create a member with the same name as an already defined " -"attribute (another member, a method, etc.) or attempting to create an " -"attribute with the same name as a member is not allowed." -msgstr "" - -#: ../../howto/enum.rst:256 -msgid "Ensuring unique enumeration values" -msgstr "" - -#: ../../howto/enum.rst:258 -msgid "" -"By default, enumerations allow multiple names as aliases for the same value. " -"When this behavior isn't desired, you can use the :func:`unique` decorator::" -msgstr "" - -#: ../../howto/enum.rst:261 -msgid "" -">>> from enum import Enum, unique\n" -">>> @unique\n" -"... class Mistake(Enum):\n" -"... ONE = 1\n" -"... TWO = 2\n" -"... THREE = 3\n" -"... FOUR = 3\n" -"...\n" -"Traceback (most recent call last):\n" -"...\n" -"ValueError: duplicate values found in : FOUR -> THREE" -msgstr "" -">>> from enum import Enum, unique\n" -">>> @unique\n" -"... class Mistake(Enum):\n" -"... ONE = 1\n" -"... TWO = 2\n" -"... THREE = 3\n" -"... FOUR = 3\n" -"...\n" -"Traceback (most recent call last):\n" -"...\n" -"ValueError: duplicate values found in : FOUR -> THREE" - -#: ../../howto/enum.rst:275 -msgid "Using automatic values" -msgstr "" - -#: ../../howto/enum.rst:277 -msgid "If the exact value is unimportant you can use :class:`auto`::" -msgstr "" - -#: ../../howto/enum.rst:279 -msgid "" -">>> from enum import Enum, auto\n" -">>> class Color(Enum):\n" -"... RED = auto()\n" -"... BLUE = auto()\n" -"... GREEN = auto()\n" -"...\n" -">>> [member.value for member in Color]\n" -"[1, 2, 3]" -msgstr "" -">>> from enum import Enum, auto\n" -">>> class Color(Enum):\n" -"... RED = auto()\n" -"... BLUE = auto()\n" -"... GREEN = auto()\n" -"...\n" -">>> [member.value for member in Color]\n" -"[1, 2, 3]" - -#: ../../howto/enum.rst:288 -msgid "" -"The values are chosen by :func:`~Enum._generate_next_value_`, which can be " -"overridden::" -msgstr "" - -#: ../../howto/enum.rst:291 -msgid "" -">>> class AutoName(Enum):\n" -"... @staticmethod\n" -"... def _generate_next_value_(name, start, count, last_values):\n" -"... return name\n" -"...\n" -">>> class Ordinal(AutoName):\n" -"... NORTH = auto()\n" -"... SOUTH = auto()\n" -"... EAST = auto()\n" -"... WEST = auto()\n" -"...\n" -">>> [member.value for member in Ordinal]\n" -"['NORTH', 'SOUTH', 'EAST', 'WEST']" -msgstr "" -">>> class AutoName(Enum):\n" -"... @staticmethod\n" -"... def _generate_next_value_(name, start, count, last_values):\n" -"... return name\n" -"...\n" -">>> class Ordinal(AutoName):\n" -"... NORTH = auto()\n" -"... SOUTH = auto()\n" -"... EAST = auto()\n" -"... WEST = auto()\n" -"...\n" -">>> [member.value for member in Ordinal]\n" -"['NORTH', 'SOUTH', 'EAST', 'WEST']" - -#: ../../howto/enum.rst:307 -msgid "" -"The :meth:`~Enum._generate_next_value_` method must be defined before any " -"members." -msgstr "" - -#: ../../howto/enum.rst:310 -msgid "Iteration" -msgstr "" - -#: ../../howto/enum.rst:312 -msgid "Iterating over the members of an enum does not provide the aliases::" -msgstr "" - -#: ../../howto/enum.rst:314 -msgid "" -">>> list(Shape)\n" -"[, , ]\n" -">>> list(Weekday)\n" -"[, , , , , , ]" -msgstr "" -">>> list(Shape)\n" -"[, , ]\n" -">>> list(Weekday)\n" -"[, , , , , , ]" - -#: ../../howto/enum.rst:319 -msgid "" -"Note that the aliases ``Shape.ALIAS_FOR_SQUARE`` and ``Weekday.WEEKEND`` " -"aren't shown." -msgstr "" - -#: ../../howto/enum.rst:321 -msgid "" -"The special attribute ``__members__`` is a read-only ordered mapping of " -"names to members. It includes all names defined in the enumeration, " -"including the aliases::" -msgstr "" - -#: ../../howto/enum.rst:325 -msgid "" -">>> for name, member in Shape.__members__.items():\n" -"... name, member\n" -"...\n" -"('SQUARE', )\n" -"('DIAMOND', )\n" -"('CIRCLE', )\n" -"('ALIAS_FOR_SQUARE', )" -msgstr "" -">>> for name, member in Shape.__members__.items():\n" -"... name, member\n" -"...\n" -"('SQUARE', )\n" -"('DIAMOND', )\n" -"('CIRCLE', )\n" -"('ALIAS_FOR_SQUARE', )" - -#: ../../howto/enum.rst:333 -msgid "" -"The ``__members__`` attribute can be used for detailed programmatic access " -"to the enumeration members. For example, finding all the aliases::" -msgstr "" - -#: ../../howto/enum.rst:336 -msgid "" -">>> [name for name, member in Shape.__members__.items() if member.name != " -"name]\n" -"['ALIAS_FOR_SQUARE']" -msgstr "" -">>> [name for name, member in Shape.__members__.items() if member.name != " -"name]\n" -"['ALIAS_FOR_SQUARE']" - -#: ../../howto/enum.rst:341 -msgid "" -"Aliases for flags include values with multiple flags set, such as ``3``, and " -"no flags set, i.e. ``0``." -msgstr "" - -#: ../../howto/enum.rst:346 -msgid "Comparisons" -msgstr "比較" - -#: ../../howto/enum.rst:348 -msgid "Enumeration members are compared by identity::" -msgstr "" - -#: ../../howto/enum.rst:350 -msgid "" -">>> Color.RED is Color.RED\n" -"True\n" -">>> Color.RED is Color.BLUE\n" -"False\n" -">>> Color.RED is not Color.BLUE\n" -"True" -msgstr "" -">>> Color.RED is Color.RED\n" -"True\n" -">>> Color.RED is Color.BLUE\n" -"False\n" -">>> Color.RED is not Color.BLUE\n" -"True" - -#: ../../howto/enum.rst:357 -msgid "" -"Ordered comparisons between enumeration values are *not* supported. Enum " -"members are not integers (but see `IntEnum`_ below)::" -msgstr "" - -#: ../../howto/enum.rst:360 -msgid "" -">>> Color.RED < Color.BLUE\n" -"Traceback (most recent call last):\n" -" File \"\", line 1, in \n" -"TypeError: '<' not supported between instances of 'Color' and 'Color'" -msgstr "" -">>> Color.RED < Color.BLUE\n" -"Traceback (most recent call last):\n" -" File \"\", line 1, in \n" -"TypeError: '<' not supported between instances of 'Color' and 'Color'" - -#: ../../howto/enum.rst:365 -msgid "Equality comparisons are defined though::" -msgstr "" - -#: ../../howto/enum.rst:367 -msgid "" -">>> Color.BLUE == Color.RED\n" -"False\n" -">>> Color.BLUE != Color.RED\n" -"True\n" -">>> Color.BLUE == Color.BLUE\n" -"True" -msgstr "" -">>> Color.BLUE == Color.RED\n" -"False\n" -">>> Color.BLUE != Color.RED\n" -"True\n" -">>> Color.BLUE == Color.BLUE\n" -"True" - -#: ../../howto/enum.rst:374 -msgid "" -"Comparisons against non-enumeration values will always compare not equal " -"(again, :class:`IntEnum` was explicitly designed to behave differently, see " -"below)::" -msgstr "" - -#: ../../howto/enum.rst:378 -msgid "" -">>> Color.BLUE == 2\n" -"False" -msgstr "" -">>> Color.BLUE == 2\n" -"False" - -#: ../../howto/enum.rst:383 -msgid "" -"It is possible to reload modules -- if a reloaded module contains enums, " -"they will be recreated, and the new members may not compare identical/equal " -"to the original members." -msgstr "" - -#: ../../howto/enum.rst:388 -msgid "Allowed members and attributes of enumerations" -msgstr "" - -#: ../../howto/enum.rst:390 -msgid "" -"Most of the examples above use integers for enumeration values. Using " -"integers is short and handy (and provided by default by the `Functional " -"API`_), but not strictly enforced. In the vast majority of use-cases, one " -"doesn't care what the actual value of an enumeration is. But if the value " -"*is* important, enumerations can have arbitrary values." -msgstr "" - -#: ../../howto/enum.rst:396 -msgid "" -"Enumerations are Python classes, and can have methods and special methods as " -"usual. If we have this enumeration::" -msgstr "" - -#: ../../howto/enum.rst:399 -msgid "" -">>> class Mood(Enum):\n" -"... FUNKY = 1\n" -"... HAPPY = 3\n" -"...\n" -"... def describe(self):\n" -"... # self is the member here\n" -"... return self.name, self.value\n" -"...\n" -"... def __str__(self):\n" -"... return 'my custom str! {0}'.format(self.value)\n" -"...\n" -"... @classmethod\n" -"... def favorite_mood(cls):\n" -"... # cls here is the enumeration\n" -"... return cls.HAPPY\n" -"..." -msgstr "" - -#: ../../howto/enum.rst:416 -msgid "Then::" -msgstr "然後： ::" - -#: ../../howto/enum.rst:418 -msgid "" -">>> Mood.favorite_mood()\n" -"\n" -">>> Mood.HAPPY.describe()\n" -"('HAPPY', 3)\n" -">>> str(Mood.FUNKY)\n" -"'my custom str! 1'" -msgstr "" -">>> Mood.favorite_mood()\n" -"\n" -">>> Mood.HAPPY.describe()\n" -"('HAPPY', 3)\n" -">>> str(Mood.FUNKY)\n" -"'my custom str! 1'" - -#: ../../howto/enum.rst:425 -msgid "" -"The rules for what is allowed are as follows: names that start and end with " -"a single underscore are reserved by enum and cannot be used; all other " -"attributes defined within an enumeration will become members of this " -"enumeration, with the exception of special methods (:meth:`~object." -"__str__`, :meth:`~object.__add__`, etc.), descriptors (methods are also " -"descriptors), and variable names listed in :attr:`~Enum._ignore_`." -msgstr "" - -#: ../../howto/enum.rst:432 -msgid "" -"Note: if your enumeration defines :meth:`~object.__new__` and/or :meth:" -"`~object.__init__`, any value(s) given to the enum member will be passed " -"into those methods. See `Planet`_ for an example." -msgstr "" - -#: ../../howto/enum.rst:438 -msgid "" -"The :meth:`~object.__new__` method, if defined, is used during creation of " -"the Enum members; it is then replaced by Enum's :meth:`~object.__new__` " -"which is used after class creation for lookup of existing members. See :ref:" -"`new-vs-init` for more details." -msgstr "" - -#: ../../howto/enum.rst:445 -msgid "Restricted Enum subclassing" -msgstr "" - -#: ../../howto/enum.rst:447 -msgid "" -"A new :class:`Enum` class must have one base enum class, up to one concrete " -"data type, and as many :class:`object`-based mixin classes as needed. The " -"order of these base classes is::" -msgstr "" - -#: ../../howto/enum.rst:451 -msgid "" -"class EnumName([mix-in, ...,] [data-type,] base-enum):\n" -" pass" -msgstr "" -"class EnumName([mix-in, ...,] [data-type,] base-enum):\n" -" pass" - -#: ../../howto/enum.rst:454 -msgid "" -"Also, subclassing an enumeration is allowed only if the enumeration does not " -"define any members. So this is forbidden::" -msgstr "" - -#: ../../howto/enum.rst:457 -msgid "" -">>> class MoreColor(Color):\n" -"... PINK = 17\n" -"...\n" -"Traceback (most recent call last):\n" -"...\n" -"TypeError: cannot extend " -msgstr "" -">>> class MoreColor(Color):\n" -"... PINK = 17\n" -"...\n" -"Traceback (most recent call last):\n" -"...\n" -"TypeError: cannot extend " - -#: ../../howto/enum.rst:464 -msgid "But this is allowed::" -msgstr "但這是允許的：" - -#: ../../howto/enum.rst:466 -msgid "" -">>> class Foo(Enum):\n" -"... def some_behavior(self):\n" -"... pass\n" -"...\n" -">>> class Bar(Foo):\n" -"... HAPPY = 1\n" -"... SAD = 2\n" -"..." -msgstr "" -">>> class Foo(Enum):\n" -"... def some_behavior(self):\n" -"... pass\n" -"...\n" -">>> class Bar(Foo):\n" -"... HAPPY = 1\n" -"... SAD = 2\n" -"..." - -#: ../../howto/enum.rst:475 -msgid "" -"Allowing subclassing of enums that define members would lead to a violation " -"of some important invariants of types and instances. On the other hand, it " -"makes sense to allow sharing some common behavior between a group of " -"enumerations. (See `OrderedEnum`_ for an example.)" -msgstr "" - -#: ../../howto/enum.rst:484 -msgid "Dataclass support" -msgstr "" - -#: ../../howto/enum.rst:486 -msgid "" -"When inheriting from a :class:`~dataclasses.dataclass`, the :meth:`~Enum." -"__repr__` omits the inherited class' name. For example::" -msgstr "" - -#: ../../howto/enum.rst:489 -msgid "" -">>> from dataclasses import dataclass, field\n" -">>> @dataclass\n" -"... class CreatureDataMixin:\n" -"... size: str\n" -"... legs: int\n" -"... tail: bool = field(repr=False, default=True)\n" -"...\n" -">>> class Creature(CreatureDataMixin, Enum):\n" -"... BEETLE = 'small', 6\n" -"... DOG = 'medium', 4\n" -"...\n" -">>> Creature.DOG\n" -"" -msgstr "" -">>> from dataclasses import dataclass, field\n" -">>> @dataclass\n" -"... class CreatureDataMixin:\n" -"... size: str\n" -"... legs: int\n" -"... tail: bool = field(repr=False, default=True)\n" -"...\n" -">>> class Creature(CreatureDataMixin, Enum):\n" -"... BEETLE = 'small', 6\n" -"... DOG = 'medium', 4\n" -"...\n" -">>> Creature.DOG\n" -"" - -#: ../../howto/enum.rst:503 -msgid "" -"Use the :func:`~dataclasses.dataclass` argument ``repr=False`` to use the " -"standard :func:`repr`." -msgstr "" - -#: ../../howto/enum.rst:506 -msgid "" -"Only the dataclass fields are shown in the value area, not the dataclass' " -"name." -msgstr "" - -#: ../../howto/enum.rst:512 -msgid "" -"Adding :func:`~dataclasses.dataclass` decorator to :class:`Enum` and its " -"subclasses is not supported. It will not raise any errors, but it will " -"produce very strange results at runtime, such as members being equal to each " -"other::" -msgstr "" - -#: ../../howto/enum.rst:517 -msgid "" -">>> @dataclass # don't do this: it does not make any sense\n" -"... class Color(Enum):\n" -"... RED = 1\n" -"... BLUE = 2\n" -"...\n" -">>> Color.RED is Color.BLUE\n" -"False\n" -">>> Color.RED == Color.BLUE # problem is here: they should not be equal\n" -"True" -msgstr "" -">>> @dataclass # 不要這樣做，這並不合理\n" -"... class Color(Enum):\n" -"... RED = 1\n" -"... BLUE = 2\n" -"...\n" -">>> Color.RED is Color.BLUE\n" -"False\n" -">>> Color.RED == Color.BLUE # 問題在此：它們不應該相等\n" -"True" - -#: ../../howto/enum.rst:529 -msgid "Pickling" -msgstr "" - -#: ../../howto/enum.rst:531 -msgid "Enumerations can be pickled and unpickled::" -msgstr "" - -#: ../../howto/enum.rst:533 -msgid "" -">>> from test.test_enum import Fruit\n" -">>> from pickle import dumps, loads\n" -">>> Fruit.TOMATO is loads(dumps(Fruit.TOMATO))\n" -"True" -msgstr "" -">>> from test.test_enum import Fruit\n" -">>> from pickle import dumps, loads\n" -">>> Fruit.TOMATO is loads(dumps(Fruit.TOMATO))\n" -"True" - -#: ../../howto/enum.rst:538 -msgid "" -"The usual restrictions for pickling apply: picklable enums must be defined " -"in the top level of a module, since unpickling requires them to be " -"importable from that module." -msgstr "" - -#: ../../howto/enum.rst:544 -msgid "" -"With pickle protocol version 4 it is possible to easily pickle enums nested " -"in other classes." -msgstr "" - -#: ../../howto/enum.rst:547 -msgid "" -"It is possible to modify how enum members are pickled/unpickled by defining :" -"meth:`~object.__reduce_ex__` in the enumeration class. The default method " -"is by-value, but enums with complicated values may want to use by-name::" -msgstr "" - -#: ../../howto/enum.rst:551 -msgid "" -">>> import enum\n" -">>> class MyEnum(enum.Enum):\n" -"... __reduce_ex__ = enum.pickle_by_enum_name" -msgstr "" -">>> import enum\n" -">>> class MyEnum(enum.Enum):\n" -"... __reduce_ex__ = enum.pickle_by_enum_name" - -#: ../../howto/enum.rst:557 -msgid "" -"Using by-name for flags is not recommended, as unnamed aliases will not " -"unpickle." -msgstr "" - -#: ../../howto/enum.rst:562 -msgid "Functional API" -msgstr "" - -#: ../../howto/enum.rst:564 -msgid "" -"The :class:`Enum` class is callable, providing the following functional API::" -msgstr "" - -#: ../../howto/enum.rst:566 -msgid "" -">>> Animal = Enum('Animal', 'ANT BEE CAT DOG')\n" -">>> Animal\n" -"\n" -">>> Animal.ANT\n" -"\n" -">>> list(Animal)\n" -"[, , , ]" -msgstr "" -">>> Animal = Enum('Animal', 'ANT BEE CAT DOG')\n" -">>> Animal\n" -"\n" -">>> Animal.ANT\n" -"\n" -">>> list(Animal)\n" -"[, , , ]" - -#: ../../howto/enum.rst:574 -msgid "" -"The semantics of this API resemble :class:`~collections.namedtuple`. The " -"first argument of the call to :class:`Enum` is the name of the enumeration." -msgstr "" - -#: ../../howto/enum.rst:577 -msgid "" -"The second argument is the *source* of enumeration member names. It can be " -"a whitespace-separated string of names, a sequence of names, a sequence of 2-" -"tuples with key/value pairs, or a mapping (e.g. dictionary) of names to " -"values. The last two options enable assigning arbitrary values to " -"enumerations; the others auto-assign increasing integers starting with 1 " -"(use the ``start`` parameter to specify a different starting value). A new " -"class derived from :class:`Enum` is returned. In other words, the above " -"assignment to :class:`!Animal` is equivalent to::" -msgstr "" - -#: ../../howto/enum.rst:586 -msgid "" -">>> class Animal(Enum):\n" -"... ANT = 1\n" -"... BEE = 2\n" -"... CAT = 3\n" -"... DOG = 4\n" -"..." -msgstr "" -">>> class Animal(Enum):\n" -"... ANT = 1\n" -"... BEE = 2\n" -"... CAT = 3\n" -"... DOG = 4\n" -"..." - -#: ../../howto/enum.rst:593 -msgid "" -"The reason for defaulting to ``1`` as the starting number and not ``0`` is " -"that ``0`` is ``False`` in a boolean sense, but by default enum members all " -"evaluate to ``True``." -msgstr "" - -#: ../../howto/enum.rst:597 -msgid "" -"Pickling enums created with the functional API can be tricky as frame stack " -"implementation details are used to try and figure out which module the " -"enumeration is being created in (e.g. it will fail if you use a utility " -"function in a separate module, and also may not work on IronPython or " -"Jython). The solution is to specify the module name explicitly as follows::" -msgstr "" - -#: ../../howto/enum.rst:603 -msgid ">>> Animal = Enum('Animal', 'ANT BEE CAT DOG', module=__name__)" -msgstr ">>> Animal = Enum('Animal', 'ANT BEE CAT DOG', module=__name__)" - -#: ../../howto/enum.rst:607 -msgid "" -"If ``module`` is not supplied, and Enum cannot determine what it is, the new " -"Enum members will not be unpicklable; to keep errors closer to the source, " -"pickling will be disabled." -msgstr "" - -#: ../../howto/enum.rst:611 -msgid "" -"The new pickle protocol 4 also, in some circumstances, relies on :attr:" -"`~type.__qualname__` being set to the location where pickle will be able to " -"find the class. For example, if the class was made available in class " -"SomeData in the global scope::" -msgstr "" - -#: ../../howto/enum.rst:616 -msgid "" -">>> Animal = Enum('Animal', 'ANT BEE CAT DOG', qualname='SomeData.Animal')" -msgstr "" -">>> Animal = Enum('Animal', 'ANT BEE CAT DOG', qualname='SomeData.Animal')" - -#: ../../howto/enum.rst:618 -msgid "The complete signature is::" -msgstr "" - -#: ../../howto/enum.rst:620 -msgid "" -"Enum(\n" -" value='NewEnumName',\n" -" names=<...>,\n" -" *,\n" -" module='...',\n" -" qualname='...',\n" -" type=,\n" -" start=1,\n" -" )" -msgstr "" -"Enum(\n" -" value='NewEnumName',\n" -" names=<...>,\n" -" *,\n" -" module='...',\n" -" qualname='...',\n" -" type=,\n" -" start=1,\n" -" )" - -#: ../../howto/enum.rst:630 -msgid "*value*: What the new enum class will record as its name." -msgstr "" - -#: ../../howto/enum.rst:632 -msgid "" -"*names*: The enum members. This can be a whitespace- or comma-separated " -"string (values will start at 1 unless otherwise specified)::" -msgstr "" - -#: ../../howto/enum.rst:635 -msgid "'RED GREEN BLUE' | 'RED,GREEN,BLUE' | 'RED, GREEN, BLUE'" -msgstr "'RED GREEN BLUE' | 'RED,GREEN,BLUE' | 'RED, GREEN, BLUE'" - -#: ../../howto/enum.rst:637 -msgid "or an iterator of names::" -msgstr "" - -#: ../../howto/enum.rst:639 -msgid "['RED', 'GREEN', 'BLUE']" -msgstr "['RED', 'GREEN', 'BLUE']" - -#: ../../howto/enum.rst:641 -msgid "or an iterator of (name, value) pairs::" -msgstr "" - -#: ../../howto/enum.rst:643 -msgid "[('CYAN', 4), ('MAGENTA', 5), ('YELLOW', 6)]" -msgstr "[('CYAN', 4), ('MAGENTA', 5), ('YELLOW', 6)]" - -#: ../../howto/enum.rst:645 -msgid "or a mapping::" -msgstr "" - -#: ../../howto/enum.rst:647 -msgid "{'CHARTREUSE': 7, 'SEA_GREEN': 11, 'ROSEMARY': 42}" -msgstr "{'CHARTREUSE': 7, 'SEA_GREEN': 11, 'ROSEMARY': 42}" - -#: ../../howto/enum.rst:649 -msgid "*module*: name of module where new enum class can be found." -msgstr "" - -#: ../../howto/enum.rst:651 -msgid "*qualname*: where in module new enum class can be found." -msgstr "" - -#: ../../howto/enum.rst:653 -msgid "*type*: type to mix in to new enum class." -msgstr "" - -#: ../../howto/enum.rst:655 -msgid "*start*: number to start counting at if only names are passed in." -msgstr "" - -#: ../../howto/enum.rst:657 -msgid "The *start* parameter was added." -msgstr "新增 *start* 參數。" - -#: ../../howto/enum.rst:662 -msgid "Derived Enumerations" -msgstr "" - -#: ../../howto/enum.rst:665 -msgid "IntEnum" -msgstr "IntEnum" - -#: ../../howto/enum.rst:667 -msgid "" -"The first variation of :class:`Enum` that is provided is also a subclass of :" -"class:`int`. Members of an :class:`IntEnum` can be compared to integers; by " -"extension, integer enumerations of different types can also be compared to " -"each other::" -msgstr "" - -#: ../../howto/enum.rst:672 -msgid "" -">>> from enum import IntEnum\n" -">>> class Shape(IntEnum):\n" -"... CIRCLE = 1\n" -"... SQUARE = 2\n" -"...\n" -">>> class Request(IntEnum):\n" -"... POST = 1\n" -"... GET = 2\n" -"...\n" -">>> Shape == 1\n" -"False\n" -">>> Shape.CIRCLE == 1\n" -"True\n" -">>> Shape.CIRCLE == Request.POST\n" -"True" -msgstr "" -">>> from enum import IntEnum\n" -">>> class Shape(IntEnum):\n" -"... CIRCLE = 1\n" -"... SQUARE = 2\n" -"...\n" -">>> class Request(IntEnum):\n" -"... POST = 1\n" -"... GET = 2\n" -"...\n" -">>> Shape == 1\n" -"False\n" -">>> Shape.CIRCLE == 1\n" -"True\n" -">>> Shape.CIRCLE == Request.POST\n" -"True" - -#: ../../howto/enum.rst:688 -msgid "" -"However, they still can't be compared to standard :class:`Enum` " -"enumerations::" -msgstr "" - -#: ../../howto/enum.rst:690 -msgid "" -">>> class Shape(IntEnum):\n" -"... CIRCLE = 1\n" -"... SQUARE = 2\n" -"...\n" -">>> class Color(Enum):\n" -"... RED = 1\n" -"... GREEN = 2\n" -"...\n" -">>> Shape.CIRCLE == Color.RED\n" -"False" -msgstr "" -">>> class Shape(IntEnum):\n" -"... CIRCLE = 1\n" -"... SQUARE = 2\n" -"...\n" -">>> class Color(Enum):\n" -"... RED = 1\n" -"... GREEN = 2\n" -"...\n" -">>> Shape.CIRCLE == Color.RED\n" -"False" - -#: ../../howto/enum.rst:701 -msgid "" -":class:`IntEnum` values behave like integers in other ways you'd expect::" -msgstr "" - -#: ../../howto/enum.rst:703 -msgid "" -">>> int(Shape.CIRCLE)\n" -"1\n" -">>> ['a', 'b', 'c'][Shape.CIRCLE]\n" -"'b'\n" -">>> [i for i in range(Shape.SQUARE)]\n" -"[0, 1]" -msgstr "" -">>> int(Shape.CIRCLE)\n" -"1\n" -">>> ['a', 'b', 'c'][Shape.CIRCLE]\n" -"'b'\n" -">>> [i for i in range(Shape.SQUARE)]\n" -"[0, 1]" - -#: ../../howto/enum.rst:712 -msgid "StrEnum" -msgstr "StrEnum" - -#: ../../howto/enum.rst:714 -msgid "" -"The second variation of :class:`Enum` that is provided is also a subclass " -"of :class:`str`. Members of a :class:`StrEnum` can be compared to strings; " -"by extension, string enumerations of different types can also be compared to " -"each other." -msgstr "" - -#: ../../howto/enum.rst:723 -msgid "IntFlag" -msgstr "IntFlag" - -#: ../../howto/enum.rst:725 -msgid "" -"The next variation of :class:`Enum` provided, :class:`IntFlag`, is also " -"based on :class:`int`. The difference being :class:`IntFlag` members can be " -"combined using the bitwise operators (&, \\|, ^, ~) and the result is still " -"an :class:`IntFlag` member, if possible. Like :class:`IntEnum`, :class:" -"`IntFlag` members are also integers and can be used wherever an :class:`int` " -"is used." -msgstr "" - -#: ../../howto/enum.rst:733 -msgid "" -"Any operation on an :class:`IntFlag` member besides the bit-wise operations " -"will lose the :class:`IntFlag` membership." -msgstr "" - -#: ../../howto/enum.rst:736 -msgid "" -"Bit-wise operations that result in invalid :class:`IntFlag` values will lose " -"the :class:`IntFlag` membership. See :class:`FlagBoundary` for details." -msgstr "" - -#: ../../howto/enum.rst:743 -msgid "Sample :class:`IntFlag` class::" -msgstr "" - -#: ../../howto/enum.rst:745 -msgid "" -">>> from enum import IntFlag\n" -">>> class Perm(IntFlag):\n" -"... R = 4\n" -"... W = 2\n" -"... X = 1\n" -"...\n" -">>> Perm.R | Perm.W\n" -"\n" -">>> Perm.R + Perm.W\n" -"6\n" -">>> RW = Perm.R | Perm.W\n" -">>> Perm.R in RW\n" -"True" -msgstr "" -">>> from enum import IntFlag\n" -">>> class Perm(IntFlag):\n" -"... R = 4\n" -"... W = 2\n" -"... X = 1\n" -"...\n" -">>> Perm.R | Perm.W\n" -"\n" -">>> Perm.R + Perm.W\n" -"6\n" -">>> RW = Perm.R | Perm.W\n" -">>> Perm.R in RW\n" -"True" - -#: ../../howto/enum.rst:759 -msgid "It is also possible to name the combinations::" -msgstr "" - -#: ../../howto/enum.rst:761 -msgid "" -">>> class Perm(IntFlag):\n" -"... R = 4\n" -"... W = 2\n" -"... X = 1\n" -"... RWX = 7\n" -"...\n" -">>> Perm.RWX\n" -"\n" -">>> ~Perm.RWX\n" -"\n" -">>> Perm(7)\n" -"" -msgstr "" -">>> class Perm(IntFlag):\n" -"... R = 4\n" -"... W = 2\n" -"... X = 1\n" -"... RWX = 7\n" -"...\n" -">>> Perm.RWX\n" -"\n" -">>> ~Perm.RWX\n" -"\n" -">>> Perm(7)\n" -"" - -#: ../../howto/enum.rst:776 -msgid "" -"Named combinations are considered aliases. Aliases do not show up during " -"iteration, but can be returned from by-value lookups." -msgstr "" - -#: ../../howto/enum.rst:781 -msgid "" -"Another important difference between :class:`IntFlag` and :class:`Enum` is " -"that if no flags are set (the value is 0), its boolean evaluation is :data:" -"`False`::" -msgstr "" - -#: ../../howto/enum.rst:784 -msgid "" -">>> Perm.R & Perm.X\n" -"\n" -">>> bool(Perm.R & Perm.X)\n" -"False" -msgstr "" -">>> Perm.R & Perm.X\n" -"\n" -">>> bool(Perm.R & Perm.X)\n" -"False" - -#: ../../howto/enum.rst:789 -msgid "" -"Because :class:`IntFlag` members are also subclasses of :class:`int` they " -"can be combined with them (but may lose :class:`IntFlag` membership::" -msgstr "" - -#: ../../howto/enum.rst:792 -msgid "" -">>> Perm.X | 4\n" -"\n" -"\n" -">>> Perm.X + 8\n" -"9" -msgstr "" -">>> Perm.X | 4\n" -"\n" -"\n" -">>> Perm.X + 8\n" -"9" - -#: ../../howto/enum.rst:800 -msgid "" -"The negation operator, ``~``, always returns an :class:`IntFlag` member with " -"a positive value::" -msgstr "" - -#: ../../howto/enum.rst:803 -msgid "" -">>> (~Perm.X).value == (Perm.R|Perm.W).value == 6\n" -"True" -msgstr "" -">>> (~Perm.X).value == (Perm.R|Perm.W).value == 6\n" -"True" - -#: ../../howto/enum.rst:806 -msgid ":class:`IntFlag` members can also be iterated over::" -msgstr ":class:`IntFlag` 成員也可以被疊代：" - -#: ../../howto/enum.rst:808 -msgid "" -">>> list(RW)\n" -"[, ]" -msgstr "" -">>> list(RW)\n" -"[, ]" - -#: ../../howto/enum.rst:815 -msgid "Flag" -msgstr "Flag" - -#: ../../howto/enum.rst:817 -msgid "" -"The last variation is :class:`Flag`. Like :class:`IntFlag`, :class:`Flag` " -"members can be combined using the bitwise operators (&, \\|, ^, ~). Unlike :" -"class:`IntFlag`, they cannot be combined with, nor compared against, any " -"other :class:`Flag` enumeration, nor :class:`int`. While it is possible to " -"specify the values directly it is recommended to use :class:`auto` as the " -"value and let :class:`Flag` select an appropriate value." -msgstr "" - -#: ../../howto/enum.rst:826 -msgid "" -"Like :class:`IntFlag`, if a combination of :class:`Flag` members results in " -"no flags being set, the boolean evaluation is :data:`False`::" -msgstr "" - -#: ../../howto/enum.rst:829 -msgid "" -">>> from enum import Flag, auto\n" -">>> class Color(Flag):\n" -"... RED = auto()\n" -"... BLUE = auto()\n" -"... GREEN = auto()\n" -"...\n" -">>> Color.RED & Color.GREEN\n" -"\n" -">>> bool(Color.RED & Color.GREEN)\n" -"False" -msgstr "" -">>> from enum import Flag, auto\n" -">>> class Color(Flag):\n" -"... RED = auto()\n" -"... BLUE = auto()\n" -"... GREEN = auto()\n" -"...\n" -">>> Color.RED & Color.GREEN\n" -"\n" -">>> bool(Color.RED & Color.GREEN)\n" -"False" - -#: ../../howto/enum.rst:840 -msgid "" -"Individual flags should have values that are powers of two (1, 2, 4, " -"8, ...), while combinations of flags will not::" -msgstr "" - -#: ../../howto/enum.rst:843 -msgid "" -">>> class Color(Flag):\n" -"... RED = auto()\n" -"... BLUE = auto()\n" -"... GREEN = auto()\n" -"... WHITE = RED | BLUE | GREEN\n" -"...\n" -">>> Color.WHITE\n" -"" -msgstr "" -">>> class Color(Flag):\n" -"... RED = auto()\n" -"... BLUE = auto()\n" -"... GREEN = auto()\n" -"... WHITE = RED | BLUE | GREEN\n" -"...\n" -">>> Color.WHITE\n" -"" - -#: ../../howto/enum.rst:852 -msgid "" -"Giving a name to the \"no flags set\" condition does not change its boolean " -"value::" -msgstr "" - -#: ../../howto/enum.rst:855 -msgid "" -">>> class Color(Flag):\n" -"... BLACK = 0\n" -"... RED = auto()\n" -"... BLUE = auto()\n" -"... GREEN = auto()\n" -"...\n" -">>> Color.BLACK\n" -"\n" -">>> bool(Color.BLACK)\n" -"False" -msgstr "" -">>> class Color(Flag):\n" -"... BLACK = 0\n" -"... RED = auto()\n" -"... BLUE = auto()\n" -"... GREEN = auto()\n" -"...\n" -">>> Color.BLACK\n" -"\n" -">>> bool(Color.BLACK)\n" -"False" - -#: ../../howto/enum.rst:866 -msgid ":class:`Flag` members can also be iterated over::" -msgstr ":class:`Flag` 成員也可以被疊代：" - -#: ../../howto/enum.rst:868 -msgid "" -">>> purple = Color.RED | Color.BLUE\n" -">>> list(purple)\n" -"[, ]" -msgstr "" -">>> purple = Color.RED | Color.BLUE\n" -">>> list(purple)\n" -"[, ]" - -#: ../../howto/enum.rst:876 -msgid "" -"For the majority of new code, :class:`Enum` and :class:`Flag` are strongly " -"recommended, since :class:`IntEnum` and :class:`IntFlag` break some semantic " -"promises of an enumeration (by being comparable to integers, and thus by " -"transitivity to other unrelated enumerations). :class:`IntEnum` and :class:" -"`IntFlag` should be used only in cases where :class:`Enum` and :class:`Flag` " -"will not do; for example, when integer constants are replaced with " -"enumerations, or for interoperability with other systems." -msgstr "" - -#: ../../howto/enum.rst:886 -msgid "Others" -msgstr "其他" - -#: ../../howto/enum.rst:888 -msgid "" -"While :class:`IntEnum` is part of the :mod:`enum` module, it would be very " -"simple to implement independently::" -msgstr "" - -#: ../../howto/enum.rst:891 -msgid "" -"class IntEnum(int, ReprEnum): # or Enum instead of ReprEnum\n" -" pass" -msgstr "" -"class IntEnum(int, ReprEnum): # 或用 Enum 取代 ReprEnum\n" -" pass" - -#: ../../howto/enum.rst:894 -msgid "" -"This demonstrates how similar derived enumerations can be defined; for " -"example a :class:`!FloatEnum` that mixes in :class:`float` instead of :class:" -"`int`." -msgstr "" - -#: ../../howto/enum.rst:897 -msgid "Some rules:" -msgstr "一些規則：" - -#: ../../howto/enum.rst:899 -msgid "" -"When subclassing :class:`Enum`, mix-in types must appear before the :class:" -"`Enum` class itself in the sequence of bases, as in the :class:`IntEnum` " -"example above." -msgstr "" - -#: ../../howto/enum.rst:902 -msgid "" -"Mix-in types must be subclassable. For example, :class:`bool` and :class:" -"`range` are not subclassable and will throw an error during Enum creation if " -"used as the mix-in type." -msgstr "" - -#: ../../howto/enum.rst:905 -msgid "" -"While :class:`Enum` can have members of any type, once you mix in an " -"additional type, all the members must have values of that type, e.g. :class:" -"`int` above. This restriction does not apply to mix-ins which only add " -"methods and don't specify another type." -msgstr "" - -#: ../../howto/enum.rst:909 -msgid "" -"When another data type is mixed in, the :attr:`~Enum.value` attribute is " -"*not the same* as the enum member itself, although it is equivalent and will " -"compare equal." -msgstr "" - -#: ../../howto/enum.rst:912 -msgid "" -"A ``data type`` is a mixin that defines :meth:`~object.__new__`, or a :class:" -"`~dataclasses.dataclass`" -msgstr "" - -#: ../../howto/enum.rst:914 -msgid "" -"%-style formatting: ``%s`` and ``%r`` call the :class:`Enum` class's :meth:" -"`~object.__str__` and :meth:`~object.__repr__` respectively; other codes " -"(such as ``%i`` or ``%h`` for IntEnum) treat the enum member as its mixed-in " -"type." -msgstr "" - -#: ../../howto/enum.rst:917 -msgid "" -":ref:`Formatted string literals `, :meth:`str.format`, and :func:" -"`format` will use the enum's :meth:`~object.__str__` method." -msgstr "" - -#: ../../howto/enum.rst:922 -msgid "" -"Because :class:`IntEnum`, :class:`IntFlag`, and :class:`StrEnum` are " -"designed to be drop-in replacements for existing constants, their :meth:" -"`~object.__str__` method has been reset to their data types' :meth:`~object." -"__str__` method." -msgstr "" - -#: ../../howto/enum.rst:930 -msgid "When to use :meth:`~object.__new__` vs. :meth:`~object.__init__`" -msgstr "" - -#: ../../howto/enum.rst:932 -msgid "" -":meth:`~object.__new__` must be used whenever you want to customize the " -"actual value of the :class:`Enum` member. Any other modifications may go in " -"either :meth:`~object.__new__` or :meth:`~object.__init__`, with :meth:" -"`~object.__init__` being preferred." -msgstr "" - -#: ../../howto/enum.rst:936 -msgid "" -"For example, if you want to pass several items to the constructor, but only " -"want one of them to be the value::" -msgstr "" - -#: ../../howto/enum.rst:939 -msgid "" -">>> class Coordinate(bytes, Enum):\n" -"... \"\"\"\n" -"... Coordinate with binary codes that can be indexed by the int code.\n" -"... \"\"\"\n" -"... def __new__(cls, value, label, unit):\n" -"... obj = bytes.__new__(cls, [value])\n" -"... obj._value_ = value\n" -"... obj.label = label\n" -"... obj.unit = unit\n" -"... return obj\n" -"... PX = (0, 'P.X', 'km')\n" -"... PY = (1, 'P.Y', 'km')\n" -"... VX = (2, 'V.X', 'km/s')\n" -"... VY = (3, 'V.Y', 'km/s')\n" -"...\n" -"\n" -">>> print(Coordinate['PY'])\n" -"Coordinate.PY\n" -"\n" -">>> print(Coordinate(3))\n" -"Coordinate.VY" -msgstr "" - -#: ../../howto/enum.rst:963 -msgid "" -"*Do not* call ``super().__new__()``, as the lookup-only ``__new__`` is the " -"one that is found; instead, use the data type directly." -msgstr "" - -#: ../../howto/enum.rst:968 -msgid "Finer Points" -msgstr "" - -#: ../../howto/enum.rst:971 -msgid "Supported ``__dunder__`` names" -msgstr "有支援的 ``__dunder__`` 名稱" - -#: ../../howto/enum.rst:973 -msgid "" -":attr:`~enum.EnumType.__members__` is a read-only ordered mapping of " -"``member_name``:``member`` items. It is only available on the class." -msgstr "" - -#: ../../howto/enum.rst:976 -msgid "" -":meth:`~object.__new__`, if specified, must create and return the enum " -"members; it is also a very good idea to set the member's :attr:`~Enum." -"_value_` appropriately. Once all the members are created it is no longer " -"used." -msgstr "" - -#: ../../howto/enum.rst:982 -msgid "Supported ``_sunder_`` names" -msgstr "有支援的 ``_sunder_`` 名稱" - -#: ../../howto/enum.rst:984 -msgid ":attr:`~Enum._name_` -- name of the member" -msgstr ":attr:`~Enum._name_` -- 成員的名稱" - -#: ../../howto/enum.rst:985 -msgid ":attr:`~Enum._value_` -- value of the member; can be set in ``__new__``" -msgstr "" - -#: ../../howto/enum.rst:986 -msgid "" -":meth:`~Enum._missing_` -- a lookup function used when a value is not found; " -"may be overridden" -msgstr "" - -#: ../../howto/enum.rst:988 -msgid "" -":attr:`~Enum._ignore_` -- a list of names, either as a :class:`list` or a :" -"class:`str`, that will not be transformed into members, and will be removed " -"from the final class" -msgstr "" - -#: ../../howto/enum.rst:991 -msgid "" -":meth:`~Enum._generate_next_value_` -- used to get an appropriate value for " -"an enum member; may be overridden" -msgstr "" - -#: ../../howto/enum.rst:993 -msgid "" -":meth:`~Enum._add_alias_` -- adds a new name as an alias to an existing " -"member." -msgstr "" - -#: ../../howto/enum.rst:995 -msgid "" -":meth:`~Enum._add_value_alias_` -- adds a new value as an alias to an " -"existing member. See `MultiValueEnum`_ for an example." -msgstr "" - -#: ../../howto/enum.rst:1000 -msgid "" -"For standard :class:`Enum` classes the next value chosen is the highest " -"value seen incremented by one." -msgstr "" - -#: ../../howto/enum.rst:1003 -msgid "" -"For :class:`Flag` classes the next value chosen will be the next highest " -"power-of-two." -msgstr "" - -#: ../../howto/enum.rst:1006 -msgid "" -"Prior versions would use the last seen value instead of the highest value." -msgstr "" - -#: ../../howto/enum.rst:1009 -msgid "``_missing_``, ``_order_``, ``_generate_next_value_``" -msgstr "``_missing_``、``_order_``、``_generate_next_value_``" - -#: ../../howto/enum.rst:1010 -msgid "``_ignore_``" -msgstr "``_ignore_``" - -#: ../../howto/enum.rst:1011 -msgid "``_add_alias_``, ``_add_value_alias_``" -msgstr "``_add_alias_``、``_add_value_alias_``" - -#: ../../howto/enum.rst:1013 -msgid "" -"To help keep Python 2 / Python 3 code in sync an :attr:`~Enum._order_` " -"attribute can be provided. It will be checked against the actual order of " -"the enumeration and raise an error if the two do not match::" -msgstr "" - -#: ../../howto/enum.rst:1017 -msgid "" -">>> class Color(Enum):\n" -"... _order_ = 'RED GREEN BLUE'\n" -"... RED = 1\n" -"... BLUE = 3\n" -"... GREEN = 2\n" -"...\n" -"Traceback (most recent call last):\n" -"...\n" -"TypeError: member order does not match _order_:\n" -" ['RED', 'BLUE', 'GREEN']\n" -" ['RED', 'GREEN', 'BLUE']" -msgstr "" -">>> class Color(Enum):\n" -"... _order_ = 'RED GREEN BLUE'\n" -"... RED = 1\n" -"... BLUE = 3\n" -"... GREEN = 2\n" -"...\n" -"Traceback (most recent call last):\n" -"...\n" -"TypeError: member order does not match _order_:\n" -" ['RED', 'BLUE', 'GREEN']\n" -" ['RED', 'GREEN', 'BLUE']" - -#: ../../howto/enum.rst:1031 -msgid "" -"In Python 2 code the :attr:`~Enum._order_` attribute is necessary as " -"definition order is lost before it can be recorded." -msgstr "" - -#: ../../howto/enum.rst:1036 -msgid "_Private__names" -msgstr "_Private__names" - -#: ../../howto/enum.rst:1038 -msgid "" -":ref:`Private names ` are not converted to enum " -"members, but remain normal attributes." -msgstr "" - -#: ../../howto/enum.rst:1045 -msgid "``Enum`` member type" -msgstr "" - -#: ../../howto/enum.rst:1047 -msgid "" -"Enum members are instances of their enum class, and are normally accessed as " -"``EnumClass.member``. In certain situations, such as writing custom enum " -"behavior, being able to access one member directly from another is useful, " -"and is supported; however, in order to avoid name clashes between member " -"names and attributes/methods from mixed-in classes, upper-case names are " -"strongly recommended." -msgstr "" - -#: ../../howto/enum.rst:1058 -msgid "Creating members that are mixed with other data types" -msgstr "" - -#: ../../howto/enum.rst:1060 -msgid "" -"When subclassing other data types, such as :class:`int` or :class:`str`, " -"with an :class:`Enum`, all values after the ``=`` are passed to that data " -"type's constructor. For example::" -msgstr "" - -#: ../../howto/enum.rst:1064 -msgid "" -">>> class MyEnum(IntEnum): # help(int) -> int(x, base=10) -> integer\n" -"... example = '11', 16 # so x='11' and base=16\n" -"...\n" -">>> MyEnum.example.value # and hex(11) is...\n" -"17" -msgstr "" -">>> class MyEnum(IntEnum): # help(int) -> int(x, base=10) -> integer\n" -"... example = '11', 16 # 所以 x='11' 且 base=16\n" -"...\n" -">>> MyEnum.example.value # 且 hex(11) 為...\n" -"17" - -#: ../../howto/enum.rst:1072 -msgid "Boolean value of ``Enum`` classes and members" -msgstr "" - -#: ../../howto/enum.rst:1074 -msgid "" -"Enum classes that are mixed with non-:class:`Enum` types (such as :class:" -"`int`, :class:`str`, etc.) are evaluated according to the mixed-in type's " -"rules; otherwise, all members evaluate as :data:`True`. To make your own " -"enum's boolean evaluation depend on the member's value add the following to " -"your class::" -msgstr "" - -#: ../../howto/enum.rst:1080 -msgid "" -"def __bool__(self):\n" -" return bool(self.value)" -msgstr "" -"def __bool__(self):\n" -" return bool(self.value)" - -#: ../../howto/enum.rst:1083 -msgid "Plain :class:`Enum` classes always evaluate as :data:`True`." -msgstr "" - -#: ../../howto/enum.rst:1087 -msgid "``Enum`` classes with methods" -msgstr "" - -#: ../../howto/enum.rst:1089 -msgid "" -"If you give your enum subclass extra methods, like the `Planet`_ class " -"below, those methods will show up in a :func:`dir` of the member, but not of " -"the class::" -msgstr "" - -#: ../../howto/enum.rst:1093 -msgid "" -">>> dir(Planet)\n" -"['EARTH', 'JUPITER', 'MARS', 'MERCURY', 'NEPTUNE', 'SATURN', 'URANUS', " -"'VENUS', '__class__', '__doc__', '__members__', '__module__']\n" -">>> dir(Planet.EARTH)\n" -"['__class__', '__doc__', '__module__', 'mass', 'name', 'radius', " -"'surface_gravity', 'value']" -msgstr "" -">>> dir(Planet)\n" -"['EARTH', 'JUPITER', 'MARS', 'MERCURY', 'NEPTUNE', 'SATURN', 'URANUS', " -"'VENUS', '__class__', '__doc__', '__members__', '__module__']\n" -">>> dir(Planet.EARTH)\n" -"['__class__', '__doc__', '__module__', 'mass', 'name', 'radius', " -"'surface_gravity', 'value']" - -#: ../../howto/enum.rst:1100 -msgid "Combining members of ``Flag``" -msgstr "``Flag`` 的成員組合" - -#: ../../howto/enum.rst:1102 -msgid "" -"Iterating over a combination of :class:`Flag` members will only return the " -"members that are comprised of a single bit::" -msgstr "" - -#: ../../howto/enum.rst:1105 -msgid "" -">>> class Color(Flag):\n" -"... RED = auto()\n" -"... GREEN = auto()\n" -"... BLUE = auto()\n" -"... MAGENTA = RED | BLUE\n" -"... YELLOW = RED | GREEN\n" -"... CYAN = GREEN | BLUE\n" -"...\n" -">>> Color(3) # named combination\n" -"\n" -">>> Color(7) # not named combination\n" -"" -msgstr "" - -#: ../../howto/enum.rst:1120 -msgid "``Flag`` and ``IntFlag`` minutia" -msgstr "" - -#: ../../howto/enum.rst:1122 -msgid "Using the following snippet for our examples::" -msgstr "" - -#: ../../howto/enum.rst:1124 -msgid "" -">>> class Color(IntFlag):\n" -"... BLACK = 0\n" -"... RED = 1\n" -"... GREEN = 2\n" -"... BLUE = 4\n" -"... PURPLE = RED | BLUE\n" -"... WHITE = RED | GREEN | BLUE\n" -"..." -msgstr "" -">>> class Color(IntFlag):\n" -"... BLACK = 0\n" -"... RED = 1\n" -"... GREEN = 2\n" -"... BLUE = 4\n" -"... PURPLE = RED | BLUE\n" -"... WHITE = RED | GREEN | BLUE\n" -"..." - -#: ../../howto/enum.rst:1133 -msgid "the following are true:" -msgstr "" - -#: ../../howto/enum.rst:1135 -msgid "single-bit flags are canonical" -msgstr "" - -#: ../../howto/enum.rst:1136 -msgid "multi-bit and zero-bit flags are aliases" -msgstr "" - -#: ../../howto/enum.rst:1137 -msgid "only canonical flags are returned during iteration::" -msgstr "" - -#: ../../howto/enum.rst:1139 -msgid "" -">>> list(Color.WHITE)\n" -"[, , ]" -msgstr "" -">>> list(Color.WHITE)\n" -"[, , ]" - -#: ../../howto/enum.rst:1142 -msgid "" -"negating a flag or flag set returns a new flag/flag set with the " -"corresponding positive integer value::" -msgstr "" - -#: ../../howto/enum.rst:1145 -msgid "" -">>> Color.BLUE\n" -"\n" -"\n" -">>> ~Color.BLUE\n" -"" -msgstr "" -">>> Color.BLUE\n" -"\n" -"\n" -">>> ~Color.BLUE\n" -"" - -#: ../../howto/enum.rst:1151 -msgid "names of pseudo-flags are constructed from their members' names::" -msgstr "" - -#: ../../howto/enum.rst:1153 -msgid "" -">>> (Color.RED | Color.GREEN).name\n" -"'RED|GREEN'\n" -"\n" -">>> class Perm(IntFlag):\n" -"... R = 4\n" -"... W = 2\n" -"... X = 1\n" -"...\n" -">>> (Perm.R & Perm.W).name is None # effectively Perm(0)\n" -"True" -msgstr "" -">>> (Color.RED | Color.GREEN).name\n" -"'RED|GREEN'\n" -"\n" -">>> class Perm(IntFlag):\n" -"... R = 4\n" -"... W = 2\n" -"... X = 1\n" -"...\n" -">>> (Perm.R & Perm.W).name is None # 效果為 Perm(0)\n" -"True" - -#: ../../howto/enum.rst:1164 -msgid "multi-bit flags, aka aliases, can be returned from operations::" -msgstr "" - -#: ../../howto/enum.rst:1166 -msgid "" -">>> Color.RED | Color.BLUE\n" -"\n" -"\n" -">>> Color(7) # or Color(-1)\n" -"\n" -"\n" -">>> Color(0)\n" -"" -msgstr "" -">>> Color.RED | Color.BLUE\n" -"\n" -"\n" -">>> Color(7) # 或 Color(-1)\n" -"\n" -"\n" -">>> Color(0)\n" -"" - -#: ../../howto/enum.rst:1175 -msgid "" -"membership / containment checking: zero-valued flags are always considered " -"to be contained::" -msgstr "" - -#: ../../howto/enum.rst:1178 -msgid "" -">>> Color.BLACK in Color.WHITE\n" -"True" -msgstr "" -">>> Color.BLACK in Color.WHITE\n" -"True" - -#: ../../howto/enum.rst:1181 -msgid "" -"otherwise, only if all bits of one flag are in the other flag will True be " -"returned::" -msgstr "" - -#: ../../howto/enum.rst:1184 -msgid "" -">>> Color.PURPLE in Color.WHITE\n" -"True\n" -"\n" -">>> Color.GREEN in Color.PURPLE\n" -"False" -msgstr "" -">>> Color.PURPLE in Color.WHITE\n" -"True\n" -"\n" -">>> Color.GREEN in Color.PURPLE\n" -"False" - -#: ../../howto/enum.rst:1190 -msgid "" -"There is a new boundary mechanism that controls how out-of-range / invalid " -"bits are handled: ``STRICT``, ``CONFORM``, ``EJECT``, and ``KEEP``:" -msgstr "" - -#: ../../howto/enum.rst:1193 -msgid "STRICT --> raises an exception when presented with invalid values" -msgstr "STRICT --> 當遇到無效值時引發例外" - -#: ../../howto/enum.rst:1194 -msgid "CONFORM --> discards any invalid bits" -msgstr "CONFORM --> 捨棄任何無效位元" - -#: ../../howto/enum.rst:1195 -msgid "EJECT --> lose Flag status and become a normal int with the given value" -msgstr "EJECT --> 失去 Flag 狀態並成為具有給定值的普通 int" - -#: ../../howto/enum.rst:1196 -msgid "KEEP --> keep the extra bits" -msgstr "KEEP --> 保留額外位元" - -#: ../../howto/enum.rst:1198 -msgid "keeps Flag status and extra bits" -msgstr "保留 Flag 狀態和額外位元" - -#: ../../howto/enum.rst:1199 -msgid "extra bits do not show up in iteration" -msgstr "" - -#: ../../howto/enum.rst:1200 -msgid "extra bits do show up in repr() and str()" -msgstr "" - -#: ../../howto/enum.rst:1202 -msgid "" -"The default for Flag is ``STRICT``, the default for ``IntFlag`` is " -"``EJECT``, and the default for ``_convert_`` is ``KEEP`` (see ``ssl." -"Options`` for an example of when ``KEEP`` is needed)." -msgstr "" - -#: ../../howto/enum.rst:1210 -msgid "How are Enums and Flags different?" -msgstr "Enums 和 Flags 有何不同？" - -#: ../../howto/enum.rst:1212 -msgid "" -"Enums have a custom metaclass that affects many aspects of both derived :" -"class:`Enum` classes and their instances (members)." -msgstr "" - -#: ../../howto/enum.rst:1217 -msgid "Enum Classes" -msgstr "Enum 類別" - -#: ../../howto/enum.rst:1219 -msgid "" -"The :class:`EnumType` metaclass is responsible for providing the :meth:" -"`~object.__contains__`, :meth:`~object.__dir__`, :meth:`~object.__iter__` " -"and other methods that allow one to do things with an :class:`Enum` class " -"that fail on a typical class, such as ``list(Color)`` or ``some_enum_var in " -"Color``. :class:`EnumType` is responsible for ensuring that various other " -"methods on the final :class:`Enum` class are correct (such as :meth:`~object." -"__new__`, :meth:`~object.__getnewargs__`, :meth:`~object.__str__` and :meth:" -"`~object.__repr__`)." -msgstr "" - -#: ../../howto/enum.rst:1228 -msgid "Flag Classes" -msgstr "Flag 類別" - -#: ../../howto/enum.rst:1230 -msgid "" -"Flags have an expanded view of aliasing: to be canonical, the value of a " -"flag needs to be a power-of-two value, and not a duplicate name. So, in " -"addition to the :class:`Enum` definition of alias, a flag with no value (a.k." -"a. ``0``) or with more than one power-of-two value (e.g. ``3``) is " -"considered an alias." -msgstr "" - -#: ../../howto/enum.rst:1236 -msgid "Enum Members (aka instances)" -msgstr "" - -#: ../../howto/enum.rst:1238 -msgid "" -"The most interesting thing about enum members is that they are singletons. :" -"class:`EnumType` creates them all while it is creating the enum class " -"itself, and then puts a custom :meth:`~object.__new__` in place to ensure " -"that no new ones are ever instantiated by returning only the existing member " -"instances." -msgstr "" - -#: ../../howto/enum.rst:1244 -msgid "Flag Members" -msgstr "Flag 成員" - -#: ../../howto/enum.rst:1246 -msgid "" -"Flag members can be iterated over just like the :class:`Flag` class, and " -"only the canonical members will be returned. For example::" -msgstr "" - -#: ../../howto/enum.rst:1249 -msgid "" -">>> list(Color)\n" -"[, , ]" -msgstr "" -">>> list(Color)\n" -"[, , ]" - -#: ../../howto/enum.rst:1252 -msgid "(Note that ``BLACK``, ``PURPLE``, and ``WHITE`` do not show up.)" -msgstr "" - -#: ../../howto/enum.rst:1254 -msgid "" -"Inverting a flag member returns the corresponding positive value, rather " -"than a negative value --- for example::" -msgstr "" - -#: ../../howto/enum.rst:1257 -msgid "" -">>> ~Color.RED\n" -"" -msgstr "" -">>> ~Color.RED\n" -"" - -#: ../../howto/enum.rst:1260 -msgid "" -"Flag members have a length corresponding to the number of power-of-two " -"values they contain. For example::" -msgstr "" - -#: ../../howto/enum.rst:1263 -msgid "" -">>> len(Color.PURPLE)\n" -"2" -msgstr "" -">>> len(Color.PURPLE)\n" -"2" - -#: ../../howto/enum.rst:1270 -msgid "Enum Cookbook" -msgstr "" - -#: ../../howto/enum.rst:1273 -msgid "" -"While :class:`Enum`, :class:`IntEnum`, :class:`StrEnum`, :class:`Flag`, and :" -"class:`IntFlag` are expected to cover the majority of use-cases, they cannot " -"cover them all. Here are recipes for some different types of enumerations " -"that can be used directly, or as examples for creating one's own." -msgstr "" - -#: ../../howto/enum.rst:1280 -msgid "Omitting values" -msgstr "省略值" - -#: ../../howto/enum.rst:1282 -msgid "" -"In many use-cases, one doesn't care what the actual value of an enumeration " -"is. There are several ways to define this type of simple enumeration:" -msgstr "" - -#: ../../howto/enum.rst:1285 -msgid "use instances of :class:`auto` for the value" -msgstr "" - -#: ../../howto/enum.rst:1286 -msgid "use instances of :class:`object` as the value" -msgstr "" - -#: ../../howto/enum.rst:1287 -msgid "use a descriptive string as the value" -msgstr "" - -#: ../../howto/enum.rst:1288 -msgid "" -"use a tuple as the value and a custom :meth:`~object.__new__` to replace the " -"tuple with an :class:`int` value" -msgstr "" - -#: ../../howto/enum.rst:1291 -msgid "" -"Using any of these methods signifies to the user that these values are not " -"important, and also enables one to add, remove, or reorder members without " -"having to renumber the remaining members." -msgstr "" - -#: ../../howto/enum.rst:1297 -msgid "Using :class:`auto`" -msgstr "使用 :class:`auto`" - -#: ../../howto/enum.rst:1299 -msgid "Using :class:`auto` would look like::" -msgstr "使用 :class:`auto` 會像這樣： ::" - -#: ../../howto/enum.rst:1301 -msgid "" -">>> class Color(Enum):\n" -"... RED = auto()\n" -"... BLUE = auto()\n" -"... GREEN = auto()\n" -"...\n" -">>> Color.GREEN\n" -"" -msgstr "" -">>> class Color(Enum):\n" -"... RED = auto()\n" -"... BLUE = auto()\n" -"... GREEN = auto()\n" -"...\n" -">>> Color.GREEN\n" -"" - -#: ../../howto/enum.rst:1311 -msgid "Using :class:`object`" -msgstr "使用 :class:`object`" - -#: ../../howto/enum.rst:1313 -msgid "Using :class:`object` would look like::" -msgstr "使用 :class:`object` 會像這樣： ::" - -#: ../../howto/enum.rst:1315 -msgid "" -">>> class Color(Enum):\n" -"... RED = object()\n" -"... GREEN = object()\n" -"... BLUE = object()\n" -"...\n" -">>> Color.GREEN\n" -">" -msgstr "" -">>> class Color(Enum):\n" -"... RED = object()\n" -"... GREEN = object()\n" -"... BLUE = object()\n" -"...\n" -">>> Color.GREEN\n" -">" - -#: ../../howto/enum.rst:1323 -msgid "" -"This is also a good example of why you might want to write your own :meth:" -"`~object.__repr__`::" -msgstr "" - -#: ../../howto/enum.rst:1326 -msgid "" -">>> class Color(Enum):\n" -"... RED = object()\n" -"... GREEN = object()\n" -"... BLUE = object()\n" -"... def __repr__(self):\n" -"... return \"<%s.%s>\" % (self.__class__.__name__, self._name_)\n" -"...\n" -">>> Color.GREEN\n" -"" -msgstr "" -">>> class Color(Enum):\n" -"... RED = object()\n" -"... GREEN = object()\n" -"... BLUE = object()\n" -"... def __repr__(self):\n" -"... return \"<%s.%s>\" % (self.__class__.__name__, self._name_)\n" -"...\n" -">>> Color.GREEN\n" -"" - -#: ../../howto/enum.rst:1339 -msgid "Using a descriptive string" -msgstr "" - -#: ../../howto/enum.rst:1341 -msgid "Using a string as the value would look like::" -msgstr "" - -#: ../../howto/enum.rst:1343 -msgid "" -">>> class Color(Enum):\n" -"... RED = 'stop'\n" -"... GREEN = 'go'\n" -"... BLUE = 'too fast!'\n" -"...\n" -">>> Color.GREEN\n" -"" -msgstr "" -">>> class Color(Enum):\n" -"... RED = 'stop'\n" -"... GREEN = 'go'\n" -"... BLUE = 'too fast!'\n" -"...\n" -">>> Color.GREEN\n" -"" - -#: ../../howto/enum.rst:1353 -msgid "Using a custom :meth:`~object.__new__`" -msgstr "使用自訂的 :meth:`~object.__new__`" - -#: ../../howto/enum.rst:1355 -msgid "Using an auto-numbering :meth:`~object.__new__` would look like::" -msgstr "" - -#: ../../howto/enum.rst:1357 -msgid "" -">>> class AutoNumber(Enum):\n" -"... def __new__(cls):\n" -"... value = len(cls.__members__) + 1\n" -"... obj = object.__new__(cls)\n" -"... obj._value_ = value\n" -"... return obj\n" -"...\n" -">>> class Color(AutoNumber):\n" -"... RED = ()\n" -"... GREEN = ()\n" -"... BLUE = ()\n" -"...\n" -">>> Color.GREEN\n" -"" -msgstr "" -">>> class AutoNumber(Enum):\n" -"... def __new__(cls):\n" -"... value = len(cls.__members__) + 1\n" -"... obj = object.__new__(cls)\n" -"... obj._value_ = value\n" -"... return obj\n" -"...\n" -">>> class Color(AutoNumber):\n" -"... RED = ()\n" -"... GREEN = ()\n" -"... BLUE = ()\n" -"...\n" -">>> Color.GREEN\n" -"" - -#: ../../howto/enum.rst:1372 -msgid "" -"To make a more general purpose ``AutoNumber``, add ``*args`` to the " -"signature::" -msgstr "" - -#: ../../howto/enum.rst:1374 -msgid "" -">>> class AutoNumber(Enum):\n" -"... def __new__(cls, *args): # this is the only change from above\n" -"... value = len(cls.__members__) + 1\n" -"... obj = object.__new__(cls)\n" -"... obj._value_ = value\n" -"... return obj\n" -"..." -msgstr "" -">>> class AutoNumber(Enum):\n" -"... def __new__(cls, *args): # 這是和上面相比唯一的變更\n" -"... value = len(cls.__members__) + 1\n" -"... obj = object.__new__(cls)\n" -"... obj._value_ = value\n" -"... return obj\n" -"..." - -#: ../../howto/enum.rst:1382 -msgid "" -"Then when you inherit from ``AutoNumber`` you can write your own " -"``__init__`` to handle any extra arguments::" -msgstr "" - -#: ../../howto/enum.rst:1385 -msgid "" -">>> class Swatch(AutoNumber):\n" -"... def __init__(self, pantone='unknown'):\n" -"... self.pantone = pantone\n" -"... AUBURN = '3497'\n" -"... SEA_GREEN = '1246'\n" -"... BLEACHED_CORAL = () # New color, no Pantone code yet!\n" -"...\n" -">>> Swatch.SEA_GREEN\n" -"\n" -">>> Swatch.SEA_GREEN.pantone\n" -"'1246'\n" -">>> Swatch.BLEACHED_CORAL.pantone\n" -"'unknown'" -msgstr "" - -#: ../../howto/enum.rst:1401 -msgid "" -"The :meth:`~object.__new__` method, if defined, is used during creation of " -"the Enum members; it is then replaced by Enum's :meth:`~object.__new__` " -"which is used after class creation for lookup of existing members." -msgstr "" - -#: ../../howto/enum.rst:1407 -msgid "" -"*Do not* call ``super().__new__()``, as the lookup-only ``__new__`` is the " -"one that is found; instead, use the data type directly -- e.g.::" -msgstr "" - -#: ../../howto/enum.rst:1410 -msgid "obj = int.__new__(cls, value)" -msgstr "obj = int.__new__(cls, value)" - -#: ../../howto/enum.rst:1414 -msgid "OrderedEnum" -msgstr "OrderedEnum" - -#: ../../howto/enum.rst:1416 -msgid "" -"An ordered enumeration that is not based on :class:`IntEnum` and so " -"maintains the normal :class:`Enum` invariants (such as not being comparable " -"to other enumerations)::" -msgstr "" - -#: ../../howto/enum.rst:1420 -msgid "" -">>> class OrderedEnum(Enum):\n" -"... def __ge__(self, other):\n" -"... if self.__class__ is other.__class__:\n" -"... return self.value >= other.value\n" -"... return NotImplemented\n" -"... def __gt__(self, other):\n" -"... if self.__class__ is other.__class__:\n" -"... return self.value > other.value\n" -"... return NotImplemented\n" -"... def __le__(self, other):\n" -"... if self.__class__ is other.__class__:\n" -"... return self.value <= other.value\n" -"... return NotImplemented\n" -"... def __lt__(self, other):\n" -"... if self.__class__ is other.__class__:\n" -"... return self.value < other.value\n" -"... return NotImplemented\n" -"...\n" -">>> class Grade(OrderedEnum):\n" -"... A = 5\n" -"... B = 4\n" -"... C = 3\n" -"... D = 2\n" -"... F = 1\n" -"...\n" -">>> Grade.C < Grade.A\n" -"True" -msgstr "" -">>> class OrderedEnum(Enum):\n" -"... def __ge__(self, other):\n" -"... if self.__class__ is other.__class__:\n" -"... return self.value >= other.value\n" -"... return NotImplemented\n" -"... def __gt__(self, other):\n" -"... if self.__class__ is other.__class__:\n" -"... return self.value > other.value\n" -"... return NotImplemented\n" -"... def __le__(self, other):\n" -"... if self.__class__ is other.__class__:\n" -"... return self.value <= other.value\n" -"... return NotImplemented\n" -"... def __lt__(self, other):\n" -"... if self.__class__ is other.__class__:\n" -"... return self.value < other.value\n" -"... return NotImplemented\n" -"...\n" -">>> class Grade(OrderedEnum):\n" -"... A = 5\n" -"... B = 4\n" -"... C = 3\n" -"... D = 2\n" -"... F = 1\n" -"...\n" -">>> Grade.C < Grade.A\n" -"True" - -#: ../../howto/enum.rst:1450 -msgid "DuplicateFreeEnum" -msgstr "DuplicateFreeEnum" - -#: ../../howto/enum.rst:1452 -msgid "" -"Raises an error if a duplicate member value is found instead of creating an " -"alias::" -msgstr "" - -#: ../../howto/enum.rst:1455 -msgid "" -">>> class DuplicateFreeEnum(Enum):\n" -"... def __init__(self, *args):\n" -"... cls = self.__class__\n" -"... if any(self.value == e.value for e in cls):\n" -"... a = self.name\n" -"... e = cls(self.value).name\n" -"... raise ValueError(\n" -"... \"aliases not allowed in DuplicateFreeEnum: %r --> " -"%r\"\n" -"... % (a, e))\n" -"...\n" -">>> class Color(DuplicateFreeEnum):\n" -"... RED = 1\n" -"... GREEN = 2\n" -"... BLUE = 3\n" -"... GRENE = 2\n" -"...\n" -"Traceback (most recent call last):\n" -" ...\n" -"ValueError: aliases not allowed in DuplicateFreeEnum: 'GRENE' --> 'GREEN'" -msgstr "" -">>> class DuplicateFreeEnum(Enum):\n" -"... def __init__(self, *args):\n" -"... cls = self.__class__\n" -"... if any(self.value == e.value for e in cls):\n" -"... a = self.name\n" -"... e = cls(self.value).name\n" -"... raise ValueError(\n" -"... \"aliases not allowed in DuplicateFreeEnum: %r --> " -"%r\"\n" -"... % (a, e))\n" -"...\n" -">>> class Color(DuplicateFreeEnum):\n" -"... RED = 1\n" -"... GREEN = 2\n" -"... BLUE = 3\n" -"... GRENE = 2\n" -"...\n" -"Traceback (most recent call last):\n" -" ...\n" -"ValueError: aliases not allowed in DuplicateFreeEnum: 'GRENE' --> 'GREEN'" - -#: ../../howto/enum.rst:1477 -msgid "" -"This is a useful example for subclassing Enum to add or change other " -"behaviors as well as disallowing aliases. If the only desired change is " -"disallowing aliases, the :func:`unique` decorator can be used instead." -msgstr "" - -#: ../../howto/enum.rst:1483 -msgid "MultiValueEnum" -msgstr "MultiValueEnum" - -#: ../../howto/enum.rst:1485 -msgid "Supports having more than one value per member::" -msgstr "" - -#: ../../howto/enum.rst:1487 -msgid "" -">>> class MultiValueEnum(Enum):\n" -"... def __new__(cls, value, *values):\n" -"... self = object.__new__(cls)\n" -"... self._value_ = value\n" -"... for v in values:\n" -"... self._add_value_alias_(v)\n" -"... return self\n" -"...\n" -">>> class DType(MultiValueEnum):\n" -"... float32 = 'f', 8\n" -"... double64 = 'd', 9\n" -"...\n" -">>> DType('f')\n" -"\n" -">>> DType(9)\n" -"" -msgstr "" -">>> class MultiValueEnum(Enum):\n" -"... def __new__(cls, value, *values):\n" -"... self = object.__new__(cls)\n" -"... self._value_ = value\n" -"... for v in values:\n" -"... self._add_value_alias_(v)\n" -"... return self\n" -"...\n" -">>> class DType(MultiValueEnum):\n" -"... float32 = 'f', 8\n" -"... double64 = 'd', 9\n" -"...\n" -">>> DType('f')\n" -"\n" -">>> DType(9)\n" -"" - -#: ../../howto/enum.rst:1506 -msgid "Planet" -msgstr "" - -#: ../../howto/enum.rst:1508 -msgid "" -"If :meth:`~object.__new__` or :meth:`~object.__init__` is defined, the value " -"of the enum member will be passed to those methods::" -msgstr "" - -#: ../../howto/enum.rst:1511 -msgid "" -">>> class Planet(Enum):\n" -"... MERCURY = (3.303e+23, 2.4397e6)\n" -"... VENUS = (4.869e+24, 6.0518e6)\n" -"... EARTH = (5.976e+24, 6.37814e6)\n" -"... MARS = (6.421e+23, 3.3972e6)\n" -"... JUPITER = (1.9e+27, 7.1492e7)\n" -"... SATURN = (5.688e+26, 6.0268e7)\n" -"... URANUS = (8.686e+25, 2.5559e7)\n" -"... NEPTUNE = (1.024e+26, 2.4746e7)\n" -"... def __init__(self, mass, radius):\n" -"... self.mass = mass # in kilograms\n" -"... self.radius = radius # in meters\n" -"... @property\n" -"... def surface_gravity(self):\n" -"... # universal gravitational constant (m3 kg-1 s-2)\n" -"... G = 6.67300E-11\n" -"... return G * self.mass / (self.radius * self.radius)\n" -"...\n" -">>> Planet.EARTH.value\n" -"(5.976e+24, 6378140.0)\n" -">>> Planet.EARTH.surface_gravity\n" -"9.802652743337129" -msgstr "" -">>> class Planet(Enum):\n" -"... MERCURY = (3.303e+23, 2.4397e6)\n" -"... VENUS = (4.869e+24, 6.0518e6)\n" -"... EARTH = (5.976e+24, 6.37814e6)\n" -"... MARS = (6.421e+23, 3.3972e6)\n" -"... JUPITER = (1.9e+27, 7.1492e7)\n" -"... SATURN = (5.688e+26, 6.0268e7)\n" -"... URANUS = (8.686e+25, 2.5559e7)\n" -"... NEPTUNE = (1.024e+26, 2.4746e7)\n" -"... def __init__(self, mass, radius):\n" -"... self.mass = mass # 以公斤表示\n" -"... self.radius = radius # 以公尺表示\n" -"... @property\n" -"... def surface_gravity(self):\n" -"... # 萬有引力常數 (m3 kg-1 s-2)\n" -"... G = 6.67300E-11\n" -"... return G * self.mass / (self.radius * self.radius)\n" -"...\n" -">>> Planet.EARTH.value\n" -"(5.976e+24, 6378140.0)\n" -">>> Planet.EARTH.surface_gravity\n" -"9.802652743337129" - -#: ../../howto/enum.rst:1537 -msgid "TimePeriod" -msgstr "" - -#: ../../howto/enum.rst:1539 -msgid "An example to show the :attr:`~Enum._ignore_` attribute in use::" -msgstr "" - -#: ../../howto/enum.rst:1541 -msgid "" -">>> from datetime import timedelta\n" -">>> class Period(timedelta, Enum):\n" -"... \"different lengths of time\"\n" -"... _ignore_ = 'Period i'\n" -"... Period = vars()\n" -"... for i in range(367):\n" -"... Period['day_%d' % i] = i\n" -"...\n" -">>> list(Period)[:2]\n" -"[, ]\n" -">>> list(Period)[-2:]\n" -"[, ]" -msgstr "" -">>> from datetime import timedelta\n" -">>> class Period(timedelta, Enum):\n" -"... \"不同長度的時間\"\n" -"... _ignore_ = 'Period i'\n" -"... Period = vars()\n" -"... for i in range(367):\n" -"... Period['day_%d' % i] = i\n" -"...\n" -">>> list(Period)[:2]\n" -"[, ]\n" -">>> list(Period)[-2:]\n" -"[, ]" - -#: ../../howto/enum.rst:1558 -msgid "Subclassing EnumType" -msgstr "子類別化 EnumType" - -#: ../../howto/enum.rst:1560 -msgid "" -"While most enum needs can be met by customizing :class:`Enum` subclasses, " -"either with class decorators or custom functions, :class:`EnumType` can be " -"subclassed to provide a different Enum experience." -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-12 00:14+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \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" + +#: ../../howto/enum.rst:5 +msgid "Enum HOWTO" +msgstr "" + +#: ../../howto/enum.rst:11 +msgid "" +"An :class:`Enum` is a set of symbolic names bound to unique values. They " +"are similar to global variables, but they offer a more useful :func:`repr`, " +"grouping, type-safety, and a few other features." +msgstr "" + +#: ../../howto/enum.rst:15 +msgid "" +"They are most useful when you have a variable that can take one of a limited " +"selection of values. For example, the days of the week::" +msgstr "" + +#: ../../howto/enum.rst:18 +msgid "" +">>> from enum import Enum\n" +">>> class Weekday(Enum):\n" +"... MONDAY = 1\n" +"... TUESDAY = 2\n" +"... WEDNESDAY = 3\n" +"... THURSDAY = 4\n" +"... FRIDAY = 5\n" +"... SATURDAY = 6\n" +"... SUNDAY = 7" +msgstr "" +">>> from enum import Enum\n" +">>> class Weekday(Enum):\n" +"... MONDAY = 1\n" +"... TUESDAY = 2\n" +"... WEDNESDAY = 3\n" +"... THURSDAY = 4\n" +"... FRIDAY = 5\n" +"... SATURDAY = 6\n" +"... SUNDAY = 7" + +#: ../../howto/enum.rst:28 +msgid "Or perhaps the RGB primary colors::" +msgstr "" + +#: ../../howto/enum.rst:30 +msgid "" +">>> from enum import Enum\n" +">>> class Color(Enum):\n" +"... RED = 1\n" +"... GREEN = 2\n" +"... BLUE = 3" +msgstr "" +">>> from enum import Enum\n" +">>> class Color(Enum):\n" +"... RED = 1\n" +"... GREEN = 2\n" +"... BLUE = 3" + +#: ../../howto/enum.rst:36 +msgid "" +"As you can see, creating an :class:`Enum` is as simple as writing a class " +"that inherits from :class:`Enum` itself." +msgstr "" + +#: ../../howto/enum.rst:39 +msgid "Case of Enum Members" +msgstr "" + +#: ../../howto/enum.rst:41 +msgid "" +"Because Enums are used to represent constants, and to help avoid issues with " +"name clashes between mixin-class methods/attributes and enum names, we " +"strongly recommend using UPPER_CASE names for members, and will be using " +"that style in our examples." +msgstr "" + +#: ../../howto/enum.rst:46 +msgid "" +"Depending on the nature of the enum a member's value may or may not be " +"important, but either way that value can be used to get the corresponding " +"member::" +msgstr "" + +#: ../../howto/enum.rst:50 +msgid "" +">>> Weekday(3)\n" +"" +msgstr "" +">>> Weekday(3)\n" +"" + +#: ../../howto/enum.rst:53 +msgid "" +"As you can see, the ``repr()`` of a member shows the enum name, the member " +"name, and the value. The ``str()`` of a member shows only the enum name and " +"member name::" +msgstr "" + +#: ../../howto/enum.rst:57 +msgid "" +">>> print(Weekday.THURSDAY)\n" +"Weekday.THURSDAY" +msgstr "" +">>> print(Weekday.THURSDAY)\n" +"Weekday.THURSDAY" + +#: ../../howto/enum.rst:60 +msgid "The *type* of an enumeration member is the enum it belongs to::" +msgstr "" + +#: ../../howto/enum.rst:62 +msgid "" +">>> type(Weekday.MONDAY)\n" +"\n" +">>> isinstance(Weekday.FRIDAY, Weekday)\n" +"True" +msgstr "" +">>> type(Weekday.MONDAY)\n" +"\n" +">>> isinstance(Weekday.FRIDAY, Weekday)\n" +"True>>> type(Weekday.MONDAY)\n" +"\n" +">>> isinstance(Weekday.FRIDAY, Weekday)\n" +"True" + +#: ../../howto/enum.rst:67 +msgid "Enum members have an attribute that contains just their :attr:`!name`::" +msgstr "" + +#: ../../howto/enum.rst:69 +msgid "" +">>> print(Weekday.TUESDAY.name)\n" +"TUESDAY" +msgstr "" +">>> print(Weekday.TUESDAY.name)\n" +"TUESDAY" + +#: ../../howto/enum.rst:72 +msgid "Likewise, they have an attribute for their :attr:`!value`::" +msgstr "" + +#: ../../howto/enum.rst:75 +msgid "" +">>> Weekday.WEDNESDAY.value\n" +"3" +msgstr "" +">>> Weekday.WEDNESDAY.value\n" +"3" + +#: ../../howto/enum.rst:78 +msgid "" +"Unlike many languages that treat enumerations solely as name/value pairs, " +"Python Enums can have behavior added. For example, :class:`datetime.date` " +"has two methods for returning the weekday: :meth:`~datetime.date.weekday` " +"and :meth:`~datetime.date.isoweekday`. The difference is that one of them " +"counts from 0-6 and the other from 1-7. Rather than keep track of that " +"ourselves we can add a method to the :class:`!Weekday` enum to extract the " +"day from the :class:`~datetime.date` instance and return the matching enum " +"member::" +msgstr "" + +#: ../../howto/enum.rst:87 +msgid "" +"@classmethod\n" +"def from_date(cls, date):\n" +" return cls(date.isoweekday())" +msgstr "" +"@classmethod\n" +"def from_date(cls, date):\n" +" return cls(date.isoweekday())" + +#: ../../howto/enum.rst:91 +msgid "The complete :class:`!Weekday` enum now looks like this::" +msgstr "" + +#: ../../howto/enum.rst:93 +msgid "" +">>> class Weekday(Enum):\n" +"... MONDAY = 1\n" +"... TUESDAY = 2\n" +"... WEDNESDAY = 3\n" +"... THURSDAY = 4\n" +"... FRIDAY = 5\n" +"... SATURDAY = 6\n" +"... SUNDAY = 7\n" +"... #\n" +"... @classmethod\n" +"... def from_date(cls, date):\n" +"... return cls(date.isoweekday())" +msgstr "" +">>> class Weekday(Enum):\n" +"... MONDAY = 1\n" +"... TUESDAY = 2\n" +"... WEDNESDAY = 3\n" +"... THURSDAY = 4\n" +"... FRIDAY = 5\n" +"... SATURDAY = 6\n" +"... SUNDAY = 7\n" +"... #\n" +"... @classmethod\n" +"... def from_date(cls, date):\n" +"... return cls(date.isoweekday())" + +#: ../../howto/enum.rst:106 +msgid "Now we can find out what today is! Observe::" +msgstr "" + +#: ../../howto/enum.rst:108 +msgid "" +">>> from datetime import date\n" +">>> Weekday.from_date(date.today())\n" +"" +msgstr "" +">>> from datetime import date\n" +">>> Weekday.from_date(date.today())\n" +"" + +#: ../../howto/enum.rst:112 +msgid "" +"Of course, if you're reading this on some other day, you'll see that day " +"instead." +msgstr "" + +#: ../../howto/enum.rst:114 +msgid "" +"This :class:`!Weekday` enum is great if our variable only needs one day, but " +"what if we need several? Maybe we're writing a function to plot chores " +"during a week, and don't want to use a :class:`list` -- we could use a " +"different type of :class:`Enum`::" +msgstr "" + +#: ../../howto/enum.rst:119 +msgid "" +">>> from enum import Flag\n" +">>> class Weekday(Flag):\n" +"... MONDAY = 1\n" +"... TUESDAY = 2\n" +"... WEDNESDAY = 4\n" +"... THURSDAY = 8\n" +"... FRIDAY = 16\n" +"... SATURDAY = 32\n" +"... SUNDAY = 64" +msgstr "" +">>> from enum import Flag\n" +">>> class Weekday(Flag):\n" +"... MONDAY = 1\n" +"... TUESDAY = 2\n" +"... WEDNESDAY = 4\n" +"... THURSDAY = 8\n" +"... FRIDAY = 16\n" +"... SATURDAY = 32\n" +"... SUNDAY = 64" + +#: ../../howto/enum.rst:129 +msgid "" +"We've changed two things: we're inherited from :class:`Flag`, and the values " +"are all powers of 2." +msgstr "" + +#: ../../howto/enum.rst:132 +msgid "" +"Just like the original :class:`!Weekday` enum above, we can have a single " +"selection::" +msgstr "" + +#: ../../howto/enum.rst:134 +msgid "" +">>> first_week_day = Weekday.MONDAY\n" +">>> first_week_day\n" +"" +msgstr "" +">>> first_week_day = Weekday.MONDAY\n" +">>> first_week_day\n" +"" + +#: ../../howto/enum.rst:138 +msgid "" +"But :class:`Flag` also allows us to combine several members into a single " +"variable::" +msgstr "" + +#: ../../howto/enum.rst:141 +msgid "" +">>> weekend = Weekday.SATURDAY | Weekday.SUNDAY\n" +">>> weekend\n" +"" +msgstr "" +">>> weekend = Weekday.SATURDAY | Weekday.SUNDAY\n" +">>> weekend\n" +"" + +#: ../../howto/enum.rst:145 +msgid "You can even iterate over a :class:`Flag` variable::" +msgstr "" + +#: ../../howto/enum.rst:147 +msgid "" +">>> for day in weekend:\n" +"... print(day)\n" +"Weekday.SATURDAY\n" +"Weekday.SUNDAY" +msgstr "" +">>> for day in weekend:\n" +"... print(day)\n" +"Weekday.SATURDAY\n" +"Weekday.SUNDAY" + +#: ../../howto/enum.rst:152 +msgid "Okay, let's get some chores set up::" +msgstr "" + +#: ../../howto/enum.rst:154 +msgid "" +">>> chores_for_ethan = {\n" +"... 'feed the cat': Weekday.MONDAY | Weekday.WEDNESDAY | Weekday." +"FRIDAY,\n" +"... 'do the dishes': Weekday.TUESDAY | Weekday.THURSDAY,\n" +"... 'answer SO questions': Weekday.SATURDAY,\n" +"... }" +msgstr "" +">>> chores_for_ethan = {\n" +"... 'feed the cat': Weekday.MONDAY | Weekday.WEDNESDAY | Weekday." +"FRIDAY,\n" +"... 'do the dishes': Weekday.TUESDAY | Weekday.THURSDAY,\n" +"... 'answer SO questions': Weekday.SATURDAY,\n" +"... }" + +#: ../../howto/enum.rst:160 +msgid "And a function to display the chores for a given day::" +msgstr "" + +#: ../../howto/enum.rst:162 +msgid "" +">>> def show_chores(chores, day):\n" +"... for chore, days in chores.items():\n" +"... if day in days:\n" +"... print(chore)\n" +"...\n" +">>> show_chores(chores_for_ethan, Weekday.SATURDAY)\n" +"answer SO questions" +msgstr "" +">>> def show_chores(chores, day):\n" +"... for chore, days in chores.items():\n" +"... if day in days:\n" +"... print(chore)\n" +"...\n" +">>> show_chores(chores_for_ethan, Weekday.SATURDAY)\n" +"answer SO questions" + +#: ../../howto/enum.rst:170 +msgid "" +"In cases where the actual values of the members do not matter, you can save " +"yourself some work and use :func:`auto` for the values::" +msgstr "" + +#: ../../howto/enum.rst:173 +msgid "" +">>> from enum import auto\n" +">>> class Weekday(Flag):\n" +"... MONDAY = auto()\n" +"... TUESDAY = auto()\n" +"... WEDNESDAY = auto()\n" +"... THURSDAY = auto()\n" +"... FRIDAY = auto()\n" +"... SATURDAY = auto()\n" +"... SUNDAY = auto()\n" +"... WEEKEND = SATURDAY | SUNDAY" +msgstr "" +">>> from enum import auto\n" +">>> class Weekday(Flag):\n" +"... MONDAY = auto()\n" +"... TUESDAY = auto()\n" +"... WEDNESDAY = auto()\n" +"... THURSDAY = auto()\n" +"... FRIDAY = auto()\n" +"... SATURDAY = auto()\n" +"... SUNDAY = auto()\n" +"... WEEKEND = SATURDAY | SUNDAY" + +#: ../../howto/enum.rst:189 +msgid "Programmatic access to enumeration members and their attributes" +msgstr "" + +#: ../../howto/enum.rst:191 +msgid "" +"Sometimes it's useful to access members in enumerations programmatically (i." +"e. situations where ``Color.RED`` won't do because the exact color is not " +"known at program-writing time). ``Enum`` allows such access::" +msgstr "" + +#: ../../howto/enum.rst:195 +msgid "" +">>> Color(1)\n" +"\n" +">>> Color(3)\n" +"" +msgstr "" +">>> Color(1)\n" +"\n" +">>> Color(3)\n" +"" + +#: ../../howto/enum.rst:200 +msgid "If you want to access enum members by *name*, use item access::" +msgstr "" + +#: ../../howto/enum.rst:202 +msgid "" +">>> Color['RED']\n" +"\n" +">>> Color['GREEN']\n" +"" +msgstr "" +">>> Color['RED']\n" +"\n" +">>> Color['GREEN']\n" +"" + +#: ../../howto/enum.rst:207 +msgid "" +"If you have an enum member and need its :attr:`!name` or :attr:`!value`::" +msgstr "" + +#: ../../howto/enum.rst:209 +msgid "" +">>> member = Color.RED\n" +">>> member.name\n" +"'RED'\n" +">>> member.value\n" +"1" +msgstr "" +">>> member = Color.RED\n" +">>> member.name\n" +"'RED'\n" +">>> member.value\n" +"1" + +#: ../../howto/enum.rst:217 +msgid "Duplicating enum members and values" +msgstr "" + +#: ../../howto/enum.rst:219 +msgid "Having two enum members with the same name is invalid::" +msgstr "" + +#: ../../howto/enum.rst:221 +msgid "" +">>> class Shape(Enum):\n" +"... SQUARE = 2\n" +"... SQUARE = 3\n" +"...\n" +"Traceback (most recent call last):\n" +"...\n" +"TypeError: 'SQUARE' already defined as 2" +msgstr "" +">>> class Shape(Enum):\n" +"... SQUARE = 2\n" +"... SQUARE = 3\n" +"...\n" +"Traceback (most recent call last):\n" +"...\n" +"TypeError: 'SQUARE' already defined as 2" + +#: ../../howto/enum.rst:229 +msgid "" +"However, an enum member can have other names associated with it. Given two " +"entries ``A`` and ``B`` with the same value (and ``A`` defined first), ``B`` " +"is an alias for the member ``A``. By-value lookup of the value of ``A`` " +"will return the member ``A``. By-name lookup of ``A`` will return the " +"member ``A``. By-name lookup of ``B`` will also return the member ``A``::" +msgstr "" + +#: ../../howto/enum.rst:235 +msgid "" +">>> class Shape(Enum):\n" +"... SQUARE = 2\n" +"... DIAMOND = 1\n" +"... CIRCLE = 3\n" +"... ALIAS_FOR_SQUARE = 2\n" +"...\n" +">>> Shape.SQUARE\n" +"\n" +">>> Shape.ALIAS_FOR_SQUARE\n" +"\n" +">>> Shape(2)\n" +"" +msgstr "" +">>> class Shape(Enum):\n" +"... SQUARE = 2\n" +"... DIAMOND = 1\n" +"... CIRCLE = 3\n" +"... ALIAS_FOR_SQUARE = 2\n" +"...\n" +">>> Shape.SQUARE\n" +"\n" +">>> Shape.ALIAS_FOR_SQUARE\n" +"\n" +">>> Shape(2)\n" +"" + +#: ../../howto/enum.rst:250 +msgid "" +"Attempting to create a member with the same name as an already defined " +"attribute (another member, a method, etc.) or attempting to create an " +"attribute with the same name as a member is not allowed." +msgstr "" + +#: ../../howto/enum.rst:256 +msgid "Ensuring unique enumeration values" +msgstr "" + +#: ../../howto/enum.rst:258 +msgid "" +"By default, enumerations allow multiple names as aliases for the same value. " +"When this behavior isn't desired, you can use the :func:`unique` decorator::" +msgstr "" + +#: ../../howto/enum.rst:261 +msgid "" +">>> from enum import Enum, unique\n" +">>> @unique\n" +"... class Mistake(Enum):\n" +"... ONE = 1\n" +"... TWO = 2\n" +"... THREE = 3\n" +"... FOUR = 3\n" +"...\n" +"Traceback (most recent call last):\n" +"...\n" +"ValueError: duplicate values found in : FOUR -> THREE" +msgstr "" +">>> from enum import Enum, unique\n" +">>> @unique\n" +"... class Mistake(Enum):\n" +"... ONE = 1\n" +"... TWO = 2\n" +"... THREE = 3\n" +"... FOUR = 3\n" +"...\n" +"Traceback (most recent call last):\n" +"...\n" +"ValueError: duplicate values found in : FOUR -> THREE" + +#: ../../howto/enum.rst:275 +msgid "Using automatic values" +msgstr "" + +#: ../../howto/enum.rst:277 +msgid "If the exact value is unimportant you can use :class:`auto`::" +msgstr "" + +#: ../../howto/enum.rst:279 +msgid "" +">>> from enum import Enum, auto\n" +">>> class Color(Enum):\n" +"... RED = auto()\n" +"... BLUE = auto()\n" +"... GREEN = auto()\n" +"...\n" +">>> [member.value for member in Color]\n" +"[1, 2, 3]" +msgstr "" +">>> from enum import Enum, auto\n" +">>> class Color(Enum):\n" +"... RED = auto()\n" +"... BLUE = auto()\n" +"... GREEN = auto()\n" +"...\n" +">>> [member.value for member in Color]\n" +"[1, 2, 3]" + +#: ../../howto/enum.rst:288 +msgid "" +"The values are chosen by :func:`~Enum._generate_next_value_`, which can be " +"overridden::" +msgstr "" + +#: ../../howto/enum.rst:291 +msgid "" +">>> class AutoName(Enum):\n" +"... @staticmethod\n" +"... def _generate_next_value_(name, start, count, last_values):\n" +"... return name\n" +"...\n" +">>> class Ordinal(AutoName):\n" +"... NORTH = auto()\n" +"... SOUTH = auto()\n" +"... EAST = auto()\n" +"... WEST = auto()\n" +"...\n" +">>> [member.value for member in Ordinal]\n" +"['NORTH', 'SOUTH', 'EAST', 'WEST']" +msgstr "" +">>> class AutoName(Enum):\n" +"... @staticmethod\n" +"... def _generate_next_value_(name, start, count, last_values):\n" +"... return name\n" +"...\n" +">>> class Ordinal(AutoName):\n" +"... NORTH = auto()\n" +"... SOUTH = auto()\n" +"... EAST = auto()\n" +"... WEST = auto()\n" +"...\n" +">>> [member.value for member in Ordinal]\n" +"['NORTH', 'SOUTH', 'EAST', 'WEST']" + +#: ../../howto/enum.rst:307 +msgid "" +"The :meth:`~Enum._generate_next_value_` method must be defined before any " +"members." +msgstr "" + +#: ../../howto/enum.rst:310 +msgid "Iteration" +msgstr "" + +#: ../../howto/enum.rst:312 +msgid "Iterating over the members of an enum does not provide the aliases::" +msgstr "" + +#: ../../howto/enum.rst:314 +msgid "" +">>> list(Shape)\n" +"[, , ]\n" +">>> list(Weekday)\n" +"[, , , , , , ]" +msgstr "" +">>> list(Shape)\n" +"[, , ]\n" +">>> list(Weekday)\n" +"[, , , , , , ]" + +#: ../../howto/enum.rst:319 +msgid "" +"Note that the aliases ``Shape.ALIAS_FOR_SQUARE`` and ``Weekday.WEEKEND`` " +"aren't shown." +msgstr "" + +#: ../../howto/enum.rst:321 +msgid "" +"The special attribute ``__members__`` is a read-only ordered mapping of " +"names to members. It includes all names defined in the enumeration, " +"including the aliases::" +msgstr "" + +#: ../../howto/enum.rst:325 +msgid "" +">>> for name, member in Shape.__members__.items():\n" +"... name, member\n" +"...\n" +"('SQUARE', )\n" +"('DIAMOND', )\n" +"('CIRCLE', )\n" +"('ALIAS_FOR_SQUARE', )" +msgstr "" +">>> for name, member in Shape.__members__.items():\n" +"... name, member\n" +"...\n" +"('SQUARE', )\n" +"('DIAMOND', )\n" +"('CIRCLE', )\n" +"('ALIAS_FOR_SQUARE', )" + +#: ../../howto/enum.rst:333 +msgid "" +"The ``__members__`` attribute can be used for detailed programmatic access " +"to the enumeration members. For example, finding all the aliases::" +msgstr "" + +#: ../../howto/enum.rst:336 +msgid "" +">>> [name for name, member in Shape.__members__.items() if member.name != " +"name]\n" +"['ALIAS_FOR_SQUARE']" +msgstr "" +">>> [name for name, member in Shape.__members__.items() if member.name != " +"name]\n" +"['ALIAS_FOR_SQUARE']" + +#: ../../howto/enum.rst:341 +msgid "" +"Aliases for flags include values with multiple flags set, such as ``3``, and " +"no flags set, i.e. ``0``." +msgstr "" + +#: ../../howto/enum.rst:346 +msgid "Comparisons" +msgstr "比較" + +#: ../../howto/enum.rst:348 +msgid "Enumeration members are compared by identity::" +msgstr "" + +#: ../../howto/enum.rst:350 +msgid "" +">>> Color.RED is Color.RED\n" +"True\n" +">>> Color.RED is Color.BLUE\n" +"False\n" +">>> Color.RED is not Color.BLUE\n" +"True" +msgstr "" +">>> Color.RED is Color.RED\n" +"True\n" +">>> Color.RED is Color.BLUE\n" +"False\n" +">>> Color.RED is not Color.BLUE\n" +"True" + +#: ../../howto/enum.rst:357 +msgid "" +"Ordered comparisons between enumeration values are *not* supported. Enum " +"members are not integers (but see `IntEnum`_ below)::" +msgstr "" + +#: ../../howto/enum.rst:360 +msgid "" +">>> Color.RED < Color.BLUE\n" +"Traceback (most recent call last):\n" +" File \"\", line 1, in \n" +"TypeError: '<' not supported between instances of 'Color' and 'Color'" +msgstr "" +">>> Color.RED < Color.BLUE\n" +"Traceback (most recent call last):\n" +" File \"\", line 1, in \n" +"TypeError: '<' not supported between instances of 'Color' and 'Color'" + +#: ../../howto/enum.rst:365 +msgid "Equality comparisons are defined though::" +msgstr "" + +#: ../../howto/enum.rst:367 +msgid "" +">>> Color.BLUE == Color.RED\n" +"False\n" +">>> Color.BLUE != Color.RED\n" +"True\n" +">>> Color.BLUE == Color.BLUE\n" +"True" +msgstr "" +">>> Color.BLUE == Color.RED\n" +"False\n" +">>> Color.BLUE != Color.RED\n" +"True\n" +">>> Color.BLUE == Color.BLUE\n" +"True" + +#: ../../howto/enum.rst:374 +msgid "" +"Comparisons against non-enumeration values will always compare not equal " +"(again, :class:`IntEnum` was explicitly designed to behave differently, see " +"below)::" +msgstr "" + +#: ../../howto/enum.rst:378 +msgid "" +">>> Color.BLUE == 2\n" +"False" +msgstr "" +">>> Color.BLUE == 2\n" +"False" + +#: ../../howto/enum.rst:383 +msgid "" +"It is possible to reload modules -- if a reloaded module contains enums, " +"they will be recreated, and the new members may not compare identical/equal " +"to the original members." +msgstr "" + +#: ../../howto/enum.rst:388 +msgid "Allowed members and attributes of enumerations" +msgstr "" + +#: ../../howto/enum.rst:390 +msgid "" +"Most of the examples above use integers for enumeration values. Using " +"integers is short and handy (and provided by default by the `Functional " +"API`_), but not strictly enforced. In the vast majority of use-cases, one " +"doesn't care what the actual value of an enumeration is. But if the value " +"*is* important, enumerations can have arbitrary values." +msgstr "" + +#: ../../howto/enum.rst:396 +msgid "" +"Enumerations are Python classes, and can have methods and special methods as " +"usual. If we have this enumeration::" +msgstr "" + +#: ../../howto/enum.rst:399 +msgid "" +">>> class Mood(Enum):\n" +"... FUNKY = 1\n" +"... HAPPY = 3\n" +"...\n" +"... def describe(self):\n" +"... # self is the member here\n" +"... return self.name, self.value\n" +"...\n" +"... def __str__(self):\n" +"... return 'my custom str! {0}'.format(self.value)\n" +"...\n" +"... @classmethod\n" +"... def favorite_mood(cls):\n" +"... # cls here is the enumeration\n" +"... return cls.HAPPY\n" +"..." +msgstr "" + +#: ../../howto/enum.rst:416 +msgid "Then::" +msgstr "然後： ::" + +#: ../../howto/enum.rst:418 +msgid "" +">>> Mood.favorite_mood()\n" +"\n" +">>> Mood.HAPPY.describe()\n" +"('HAPPY', 3)\n" +">>> str(Mood.FUNKY)\n" +"'my custom str! 1'" +msgstr "" +">>> Mood.favorite_mood()\n" +"\n" +">>> Mood.HAPPY.describe()\n" +"('HAPPY', 3)\n" +">>> str(Mood.FUNKY)\n" +"'my custom str! 1'" + +#: ../../howto/enum.rst:425 +msgid "" +"The rules for what is allowed are as follows: names that start and end with " +"a single underscore are reserved by enum and cannot be used; all other " +"attributes defined within an enumeration will become members of this " +"enumeration, with the exception of special methods (:meth:`~object." +"__str__`, :meth:`~object.__add__`, etc.), descriptors (methods are also " +"descriptors), and variable names listed in :attr:`~Enum._ignore_`." +msgstr "" + +#: ../../howto/enum.rst:432 +msgid "" +"Note: if your enumeration defines :meth:`~object.__new__` and/or :meth:" +"`~object.__init__`, any value(s) given to the enum member will be passed " +"into those methods. See `Planet`_ for an example." +msgstr "" + +#: ../../howto/enum.rst:438 +msgid "" +"The :meth:`~object.__new__` method, if defined, is used during creation of " +"the Enum members; it is then replaced by Enum's :meth:`~object.__new__` " +"which is used after class creation for lookup of existing members. See :ref:" +"`new-vs-init` for more details." +msgstr "" + +#: ../../howto/enum.rst:445 +msgid "Restricted Enum subclassing" +msgstr "" + +#: ../../howto/enum.rst:447 +msgid "" +"A new :class:`Enum` class must have one base enum class, up to one concrete " +"data type, and as many :class:`object`-based mixin classes as needed. The " +"order of these base classes is::" +msgstr "" + +#: ../../howto/enum.rst:451 +msgid "" +"class EnumName([mix-in, ...,] [data-type,] base-enum):\n" +" pass" +msgstr "" +"class EnumName([mix-in, ...,] [data-type,] base-enum):\n" +" pass" + +#: ../../howto/enum.rst:454 +msgid "" +"Also, subclassing an enumeration is allowed only if the enumeration does not " +"define any members. So this is forbidden::" +msgstr "" + +#: ../../howto/enum.rst:457 +msgid "" +">>> class MoreColor(Color):\n" +"... PINK = 17\n" +"...\n" +"Traceback (most recent call last):\n" +"...\n" +"TypeError: cannot extend " +msgstr "" +">>> class MoreColor(Color):\n" +"... PINK = 17\n" +"...\n" +"Traceback (most recent call last):\n" +"...\n" +"TypeError: cannot extend " + +#: ../../howto/enum.rst:464 +msgid "But this is allowed::" +msgstr "但這是允許的：" + +#: ../../howto/enum.rst:466 +msgid "" +">>> class Foo(Enum):\n" +"... def some_behavior(self):\n" +"... pass\n" +"...\n" +">>> class Bar(Foo):\n" +"... HAPPY = 1\n" +"... SAD = 2\n" +"..." +msgstr "" +">>> class Foo(Enum):\n" +"... def some_behavior(self):\n" +"... pass\n" +"...\n" +">>> class Bar(Foo):\n" +"... HAPPY = 1\n" +"... SAD = 2\n" +"..." + +#: ../../howto/enum.rst:475 +msgid "" +"Allowing subclassing of enums that define members would lead to a violation " +"of some important invariants of types and instances. On the other hand, it " +"makes sense to allow sharing some common behavior between a group of " +"enumerations. (See `OrderedEnum`_ for an example.)" +msgstr "" + +#: ../../howto/enum.rst:484 +msgid "Dataclass support" +msgstr "" + +#: ../../howto/enum.rst:486 +msgid "" +"When inheriting from a :class:`~dataclasses.dataclass`, the :meth:`~Enum." +"__repr__` omits the inherited class' name. For example::" +msgstr "" + +#: ../../howto/enum.rst:489 +msgid "" +">>> from dataclasses import dataclass, field\n" +">>> @dataclass\n" +"... class CreatureDataMixin:\n" +"... size: str\n" +"... legs: int\n" +"... tail: bool = field(repr=False, default=True)\n" +"...\n" +">>> class Creature(CreatureDataMixin, Enum):\n" +"... BEETLE = 'small', 6\n" +"... DOG = 'medium', 4\n" +"...\n" +">>> Creature.DOG\n" +"" +msgstr "" +">>> from dataclasses import dataclass, field\n" +">>> @dataclass\n" +"... class CreatureDataMixin:\n" +"... size: str\n" +"... legs: int\n" +"... tail: bool = field(repr=False, default=True)\n" +"...\n" +">>> class Creature(CreatureDataMixin, Enum):\n" +"... BEETLE = 'small', 6\n" +"... DOG = 'medium', 4\n" +"...\n" +">>> Creature.DOG\n" +"" + +#: ../../howto/enum.rst:503 +msgid "" +"Use the :func:`~dataclasses.dataclass` argument ``repr=False`` to use the " +"standard :func:`repr`." +msgstr "" + +#: ../../howto/enum.rst:506 +msgid "" +"Only the dataclass fields are shown in the value area, not the dataclass' " +"name." +msgstr "" + +#: ../../howto/enum.rst:512 +msgid "" +"Adding :func:`~dataclasses.dataclass` decorator to :class:`Enum` and its " +"subclasses is not supported. It will not raise any errors, but it will " +"produce very strange results at runtime, such as members being equal to each " +"other::" +msgstr "" + +#: ../../howto/enum.rst:517 +msgid "" +">>> @dataclass # don't do this: it does not make any sense\n" +"... class Color(Enum):\n" +"... RED = 1\n" +"... BLUE = 2\n" +"...\n" +">>> Color.RED is Color.BLUE\n" +"False\n" +">>> Color.RED == Color.BLUE # problem is here: they should not be equal\n" +"True" +msgstr "" +">>> @dataclass # 不要這樣做，這並不合理\n" +"... class Color(Enum):\n" +"... RED = 1\n" +"... BLUE = 2\n" +"...\n" +">>> Color.RED is Color.BLUE\n" +"False\n" +">>> Color.RED == Color.BLUE # 問題在此：它們不應該相等\n" +"True" + +#: ../../howto/enum.rst:529 +msgid "Pickling" +msgstr "" + +#: ../../howto/enum.rst:531 +msgid "Enumerations can be pickled and unpickled::" +msgstr "" + +#: ../../howto/enum.rst:533 +msgid "" +">>> from test.test_enum import Fruit\n" +">>> from pickle import dumps, loads\n" +">>> Fruit.TOMATO is loads(dumps(Fruit.TOMATO))\n" +"True" +msgstr "" +">>> from test.test_enum import Fruit\n" +">>> from pickle import dumps, loads\n" +">>> Fruit.TOMATO is loads(dumps(Fruit.TOMATO))\n" +"True" + +#: ../../howto/enum.rst:538 +msgid "" +"The usual restrictions for pickling apply: picklable enums must be defined " +"in the top level of a module, since unpickling requires them to be " +"importable from that module." +msgstr "" + +#: ../../howto/enum.rst:544 +msgid "" +"With pickle protocol version 4 it is possible to easily pickle enums nested " +"in other classes." +msgstr "" + +#: ../../howto/enum.rst:547 +msgid "" +"It is possible to modify how enum members are pickled/unpickled by defining :" +"meth:`~object.__reduce_ex__` in the enumeration class. The default method " +"is by-value, but enums with complicated values may want to use by-name::" +msgstr "" + +#: ../../howto/enum.rst:551 +msgid "" +">>> import enum\n" +">>> class MyEnum(enum.Enum):\n" +"... __reduce_ex__ = enum.pickle_by_enum_name" +msgstr "" +">>> import enum\n" +">>> class MyEnum(enum.Enum):\n" +"... __reduce_ex__ = enum.pickle_by_enum_name" + +#: ../../howto/enum.rst:557 +msgid "" +"Using by-name for flags is not recommended, as unnamed aliases will not " +"unpickle." +msgstr "" + +#: ../../howto/enum.rst:562 +msgid "Functional API" +msgstr "" + +#: ../../howto/enum.rst:564 +msgid "" +"The :class:`Enum` class is callable, providing the following functional API::" +msgstr "" + +#: ../../howto/enum.rst:566 +msgid "" +">>> Animal = Enum('Animal', 'ANT BEE CAT DOG')\n" +">>> Animal\n" +"\n" +">>> Animal.ANT\n" +"\n" +">>> list(Animal)\n" +"[, , , ]" +msgstr "" +">>> Animal = Enum('Animal', 'ANT BEE CAT DOG')\n" +">>> Animal\n" +"\n" +">>> Animal.ANT\n" +"\n" +">>> list(Animal)\n" +"[, , , ]" + +#: ../../howto/enum.rst:574 +msgid "" +"The semantics of this API resemble :class:`~collections.namedtuple`. The " +"first argument of the call to :class:`Enum` is the name of the enumeration." +msgstr "" + +#: ../../howto/enum.rst:577 +msgid "" +"The second argument is the *source* of enumeration member names. It can be " +"a whitespace-separated string of names, a sequence of names, a sequence of 2-" +"tuples with key/value pairs, or a mapping (e.g. dictionary) of names to " +"values. The last two options enable assigning arbitrary values to " +"enumerations; the others auto-assign increasing integers starting with 1 " +"(use the ``start`` parameter to specify a different starting value). A new " +"class derived from :class:`Enum` is returned. In other words, the above " +"assignment to :class:`!Animal` is equivalent to::" +msgstr "" + +#: ../../howto/enum.rst:586 +msgid "" +">>> class Animal(Enum):\n" +"... ANT = 1\n" +"... BEE = 2\n" +"... CAT = 3\n" +"... DOG = 4\n" +"..." +msgstr "" +">>> class Animal(Enum):\n" +"... ANT = 1\n" +"... BEE = 2\n" +"... CAT = 3\n" +"... DOG = 4\n" +"..." + +#: ../../howto/enum.rst:593 +msgid "" +"The reason for defaulting to ``1`` as the starting number and not ``0`` is " +"that ``0`` is ``False`` in a boolean sense, but by default enum members all " +"evaluate to ``True``." +msgstr "" + +#: ../../howto/enum.rst:597 +msgid "" +"Pickling enums created with the functional API can be tricky as frame stack " +"implementation details are used to try and figure out which module the " +"enumeration is being created in (e.g. it will fail if you use a utility " +"function in a separate module, and also may not work on IronPython or " +"Jython). The solution is to specify the module name explicitly as follows::" +msgstr "" + +#: ../../howto/enum.rst:603 +msgid ">>> Animal = Enum('Animal', 'ANT BEE CAT DOG', module=__name__)" +msgstr ">>> Animal = Enum('Animal', 'ANT BEE CAT DOG', module=__name__)" + +#: ../../howto/enum.rst:607 +msgid "" +"If ``module`` is not supplied, and Enum cannot determine what it is, the new " +"Enum members will not be unpicklable; to keep errors closer to the source, " +"pickling will be disabled." +msgstr "" + +#: ../../howto/enum.rst:611 +msgid "" +"The new pickle protocol 4 also, in some circumstances, relies on :attr:" +"`~type.__qualname__` being set to the location where pickle will be able to " +"find the class. For example, if the class was made available in class " +"SomeData in the global scope::" +msgstr "" + +#: ../../howto/enum.rst:616 +msgid "" +">>> Animal = Enum('Animal', 'ANT BEE CAT DOG', qualname='SomeData.Animal')" +msgstr "" +">>> Animal = Enum('Animal', 'ANT BEE CAT DOG', qualname='SomeData.Animal')" + +#: ../../howto/enum.rst:618 +msgid "The complete signature is::" +msgstr "" + +#: ../../howto/enum.rst:620 +msgid "" +"Enum(\n" +" value='NewEnumName',\n" +" names=<...>,\n" +" *,\n" +" module='...',\n" +" qualname='...',\n" +" type=,\n" +" start=1,\n" +" )" +msgstr "" +"Enum(\n" +" value='NewEnumName',\n" +" names=<...>,\n" +" *,\n" +" module='...',\n" +" qualname='...',\n" +" type=,\n" +" start=1,\n" +" )" + +#: ../../howto/enum.rst:630 +msgid "*value*: What the new enum class will record as its name." +msgstr "" + +#: ../../howto/enum.rst:632 +msgid "" +"*names*: The enum members. This can be a whitespace- or comma-separated " +"string (values will start at 1 unless otherwise specified)::" +msgstr "" + +#: ../../howto/enum.rst:635 +msgid "'RED GREEN BLUE' | 'RED,GREEN,BLUE' | 'RED, GREEN, BLUE'" +msgstr "'RED GREEN BLUE' | 'RED,GREEN,BLUE' | 'RED, GREEN, BLUE'" + +#: ../../howto/enum.rst:637 +msgid "or an iterator of names::" +msgstr "" + +#: ../../howto/enum.rst:639 +msgid "['RED', 'GREEN', 'BLUE']" +msgstr "['RED', 'GREEN', 'BLUE']" + +#: ../../howto/enum.rst:641 +msgid "or an iterator of (name, value) pairs::" +msgstr "" + +#: ../../howto/enum.rst:643 +msgid "[('CYAN', 4), ('MAGENTA', 5), ('YELLOW', 6)]" +msgstr "[('CYAN', 4), ('MAGENTA', 5), ('YELLOW', 6)]" + +#: ../../howto/enum.rst:645 +msgid "or a mapping::" +msgstr "" + +#: ../../howto/enum.rst:647 +msgid "{'CHARTREUSE': 7, 'SEA_GREEN': 11, 'ROSEMARY': 42}" +msgstr "{'CHARTREUSE': 7, 'SEA_GREEN': 11, 'ROSEMARY': 42}" + +#: ../../howto/enum.rst:649 +msgid "*module*: name of module where new enum class can be found." +msgstr "" + +#: ../../howto/enum.rst:651 +msgid "*qualname*: where in module new enum class can be found." +msgstr "" + +#: ../../howto/enum.rst:653 +msgid "*type*: type to mix in to new enum class." +msgstr "" + +#: ../../howto/enum.rst:655 +msgid "*start*: number to start counting at if only names are passed in." +msgstr "" + +#: ../../howto/enum.rst:657 +msgid "The *start* parameter was added." +msgstr "新增 *start* 參數。" + +#: ../../howto/enum.rst:662 +msgid "Derived Enumerations" +msgstr "" + +#: ../../howto/enum.rst:665 +msgid "IntEnum" +msgstr "IntEnum" + +#: ../../howto/enum.rst:667 +msgid "" +"The first variation of :class:`Enum` that is provided is also a subclass of :" +"class:`int`. Members of an :class:`IntEnum` can be compared to integers; by " +"extension, integer enumerations of different types can also be compared to " +"each other::" +msgstr "" + +#: ../../howto/enum.rst:672 +msgid "" +">>> from enum import IntEnum\n" +">>> class Shape(IntEnum):\n" +"... CIRCLE = 1\n" +"... SQUARE = 2\n" +"...\n" +">>> class Request(IntEnum):\n" +"... POST = 1\n" +"... GET = 2\n" +"...\n" +">>> Shape == 1\n" +"False\n" +">>> Shape.CIRCLE == 1\n" +"True\n" +">>> Shape.CIRCLE == Request.POST\n" +"True" +msgstr "" +">>> from enum import IntEnum\n" +">>> class Shape(IntEnum):\n" +"... CIRCLE = 1\n" +"... SQUARE = 2\n" +"...\n" +">>> class Request(IntEnum):\n" +"... POST = 1\n" +"... GET = 2\n" +"...\n" +">>> Shape == 1\n" +"False\n" +">>> Shape.CIRCLE == 1\n" +"True\n" +">>> Shape.CIRCLE == Request.POST\n" +"True" + +#: ../../howto/enum.rst:688 +msgid "" +"However, they still can't be compared to standard :class:`Enum` " +"enumerations::" +msgstr "" + +#: ../../howto/enum.rst:690 +msgid "" +">>> class Shape(IntEnum):\n" +"... CIRCLE = 1\n" +"... SQUARE = 2\n" +"...\n" +">>> class Color(Enum):\n" +"... RED = 1\n" +"... GREEN = 2\n" +"...\n" +">>> Shape.CIRCLE == Color.RED\n" +"False" +msgstr "" +">>> class Shape(IntEnum):\n" +"... CIRCLE = 1\n" +"... SQUARE = 2\n" +"...\n" +">>> class Color(Enum):\n" +"... RED = 1\n" +"... GREEN = 2\n" +"...\n" +">>> Shape.CIRCLE == Color.RED\n" +"False" + +#: ../../howto/enum.rst:701 +msgid "" +":class:`IntEnum` values behave like integers in other ways you'd expect::" +msgstr "" + +#: ../../howto/enum.rst:703 +msgid "" +">>> int(Shape.CIRCLE)\n" +"1\n" +">>> ['a', 'b', 'c'][Shape.CIRCLE]\n" +"'b'\n" +">>> [i for i in range(Shape.SQUARE)]\n" +"[0, 1]" +msgstr "" +">>> int(Shape.CIRCLE)\n" +"1\n" +">>> ['a', 'b', 'c'][Shape.CIRCLE]\n" +"'b'\n" +">>> [i for i in range(Shape.SQUARE)]\n" +"[0, 1]" + +#: ../../howto/enum.rst:712 +msgid "StrEnum" +msgstr "StrEnum" + +#: ../../howto/enum.rst:714 +msgid "" +"The second variation of :class:`Enum` that is provided is also a subclass " +"of :class:`str`. Members of a :class:`StrEnum` can be compared to strings; " +"by extension, string enumerations of different types can also be compared to " +"each other." +msgstr "" + +#: ../../howto/enum.rst:723 +msgid "IntFlag" +msgstr "IntFlag" + +#: ../../howto/enum.rst:725 +msgid "" +"The next variation of :class:`Enum` provided, :class:`IntFlag`, is also " +"based on :class:`int`. The difference being :class:`IntFlag` members can be " +"combined using the bitwise operators (&, \\|, ^, ~) and the result is still " +"an :class:`IntFlag` member, if possible. Like :class:`IntEnum`, :class:" +"`IntFlag` members are also integers and can be used wherever an :class:`int` " +"is used." +msgstr "" + +#: ../../howto/enum.rst:733 +msgid "" +"Any operation on an :class:`IntFlag` member besides the bit-wise operations " +"will lose the :class:`IntFlag` membership." +msgstr "" + +#: ../../howto/enum.rst:736 +msgid "" +"Bit-wise operations that result in invalid :class:`IntFlag` values will lose " +"the :class:`IntFlag` membership. See :class:`FlagBoundary` for details." +msgstr "" + +#: ../../howto/enum.rst:743 +msgid "Sample :class:`IntFlag` class::" +msgstr "" + +#: ../../howto/enum.rst:745 +msgid "" +">>> from enum import IntFlag\n" +">>> class Perm(IntFlag):\n" +"... R = 4\n" +"... W = 2\n" +"... X = 1\n" +"...\n" +">>> Perm.R | Perm.W\n" +"\n" +">>> Perm.R + Perm.W\n" +"6\n" +">>> RW = Perm.R | Perm.W\n" +">>> Perm.R in RW\n" +"True" +msgstr "" +">>> from enum import IntFlag\n" +">>> class Perm(IntFlag):\n" +"... R = 4\n" +"... W = 2\n" +"... X = 1\n" +"...\n" +">>> Perm.R | Perm.W\n" +"\n" +">>> Perm.R + Perm.W\n" +"6\n" +">>> RW = Perm.R | Perm.W\n" +">>> Perm.R in RW\n" +"True" + +#: ../../howto/enum.rst:759 +msgid "It is also possible to name the combinations::" +msgstr "" + +#: ../../howto/enum.rst:761 +msgid "" +">>> class Perm(IntFlag):\n" +"... R = 4\n" +"... W = 2\n" +"... X = 1\n" +"... RWX = 7\n" +"...\n" +">>> Perm.RWX\n" +"\n" +">>> ~Perm.RWX\n" +"\n" +">>> Perm(7)\n" +"" +msgstr "" +">>> class Perm(IntFlag):\n" +"... R = 4\n" +"... W = 2\n" +"... X = 1\n" +"... RWX = 7\n" +"...\n" +">>> Perm.RWX\n" +"\n" +">>> ~Perm.RWX\n" +"\n" +">>> Perm(7)\n" +"" + +#: ../../howto/enum.rst:776 +msgid "" +"Named combinations are considered aliases. Aliases do not show up during " +"iteration, but can be returned from by-value lookups." +msgstr "" + +#: ../../howto/enum.rst:781 +msgid "" +"Another important difference between :class:`IntFlag` and :class:`Enum` is " +"that if no flags are set (the value is 0), its boolean evaluation is :data:" +"`False`::" +msgstr "" + +#: ../../howto/enum.rst:784 +msgid "" +">>> Perm.R & Perm.X\n" +"\n" +">>> bool(Perm.R & Perm.X)\n" +"False" +msgstr "" +">>> Perm.R & Perm.X\n" +"\n" +">>> bool(Perm.R & Perm.X)\n" +"False" + +#: ../../howto/enum.rst:789 +msgid "" +"Because :class:`IntFlag` members are also subclasses of :class:`int` they " +"can be combined with them (but may lose :class:`IntFlag` membership::" +msgstr "" + +#: ../../howto/enum.rst:792 +msgid "" +">>> Perm.X | 4\n" +"\n" +"\n" +">>> Perm.X + 8\n" +"9" +msgstr "" +">>> Perm.X | 4\n" +"\n" +"\n" +">>> Perm.X + 8\n" +"9" + +#: ../../howto/enum.rst:800 +msgid "" +"The negation operator, ``~``, always returns an :class:`IntFlag` member with " +"a positive value::" +msgstr "" + +#: ../../howto/enum.rst:803 +msgid "" +">>> (~Perm.X).value == (Perm.R|Perm.W).value == 6\n" +"True" +msgstr "" +">>> (~Perm.X).value == (Perm.R|Perm.W).value == 6\n" +"True" + +#: ../../howto/enum.rst:806 +msgid ":class:`IntFlag` members can also be iterated over::" +msgstr ":class:`IntFlag` 成員也可以被疊代：" + +#: ../../howto/enum.rst:808 +msgid "" +">>> list(RW)\n" +"[, ]" +msgstr "" +">>> list(RW)\n" +"[, ]" + +#: ../../howto/enum.rst:815 +msgid "Flag" +msgstr "Flag" + +#: ../../howto/enum.rst:817 +msgid "" +"The last variation is :class:`Flag`. Like :class:`IntFlag`, :class:`Flag` " +"members can be combined using the bitwise operators (&, \\|, ^, ~). Unlike :" +"class:`IntFlag`, they cannot be combined with, nor compared against, any " +"other :class:`Flag` enumeration, nor :class:`int`. While it is possible to " +"specify the values directly it is recommended to use :class:`auto` as the " +"value and let :class:`Flag` select an appropriate value." +msgstr "" + +#: ../../howto/enum.rst:826 +msgid "" +"Like :class:`IntFlag`, if a combination of :class:`Flag` members results in " +"no flags being set, the boolean evaluation is :data:`False`::" +msgstr "" + +#: ../../howto/enum.rst:829 +msgid "" +">>> from enum import Flag, auto\n" +">>> class Color(Flag):\n" +"... RED = auto()\n" +"... BLUE = auto()\n" +"... GREEN = auto()\n" +"...\n" +">>> Color.RED & Color.GREEN\n" +"\n" +">>> bool(Color.RED & Color.GREEN)\n" +"False" +msgstr "" +">>> from enum import Flag, auto\n" +">>> class Color(Flag):\n" +"... RED = auto()\n" +"... BLUE = auto()\n" +"... GREEN = auto()\n" +"...\n" +">>> Color.RED & Color.GREEN\n" +"\n" +">>> bool(Color.RED & Color.GREEN)\n" +"False" + +#: ../../howto/enum.rst:840 +msgid "" +"Individual flags should have values that are powers of two (1, 2, 4, " +"8, ...), while combinations of flags will not::" +msgstr "" + +#: ../../howto/enum.rst:843 +msgid "" +">>> class Color(Flag):\n" +"... RED = auto()\n" +"... BLUE = auto()\n" +"... GREEN = auto()\n" +"... WHITE = RED | BLUE | GREEN\n" +"...\n" +">>> Color.WHITE\n" +"" +msgstr "" +">>> class Color(Flag):\n" +"... RED = auto()\n" +"... BLUE = auto()\n" +"... GREEN = auto()\n" +"... WHITE = RED | BLUE | GREEN\n" +"...\n" +">>> Color.WHITE\n" +"" + +#: ../../howto/enum.rst:852 +msgid "" +"Giving a name to the \"no flags set\" condition does not change its boolean " +"value::" +msgstr "" + +#: ../../howto/enum.rst:855 +msgid "" +">>> class Color(Flag):\n" +"... BLACK = 0\n" +"... RED = auto()\n" +"... BLUE = auto()\n" +"... GREEN = auto()\n" +"...\n" +">>> Color.BLACK\n" +"\n" +">>> bool(Color.BLACK)\n" +"False" +msgstr "" +">>> class Color(Flag):\n" +"... BLACK = 0\n" +"... RED = auto()\n" +"... BLUE = auto()\n" +"... GREEN = auto()\n" +"...\n" +">>> Color.BLACK\n" +"\n" +">>> bool(Color.BLACK)\n" +"False" + +#: ../../howto/enum.rst:866 +msgid ":class:`Flag` members can also be iterated over::" +msgstr ":class:`Flag` 成員也可以被疊代：" + +#: ../../howto/enum.rst:868 +msgid "" +">>> purple = Color.RED | Color.BLUE\n" +">>> list(purple)\n" +"[, ]" +msgstr "" +">>> purple = Color.RED | Color.BLUE\n" +">>> list(purple)\n" +"[, ]" + +#: ../../howto/enum.rst:876 +msgid "" +"For the majority of new code, :class:`Enum` and :class:`Flag` are strongly " +"recommended, since :class:`IntEnum` and :class:`IntFlag` break some semantic " +"promises of an enumeration (by being comparable to integers, and thus by " +"transitivity to other unrelated enumerations). :class:`IntEnum` and :class:" +"`IntFlag` should be used only in cases where :class:`Enum` and :class:`Flag` " +"will not do; for example, when integer constants are replaced with " +"enumerations, or for interoperability with other systems." +msgstr "" + +#: ../../howto/enum.rst:886 +msgid "Others" +msgstr "其他" + +#: ../../howto/enum.rst:888 +msgid "" +"While :class:`IntEnum` is part of the :mod:`enum` module, it would be very " +"simple to implement independently::" +msgstr "" + +#: ../../howto/enum.rst:891 +msgid "" +"class IntEnum(int, ReprEnum): # or Enum instead of ReprEnum\n" +" pass" +msgstr "" +"class IntEnum(int, ReprEnum): # 或用 Enum 取代 ReprEnum\n" +" pass" + +#: ../../howto/enum.rst:894 +msgid "" +"This demonstrates how similar derived enumerations can be defined; for " +"example a :class:`!FloatEnum` that mixes in :class:`float` instead of :class:" +"`int`." +msgstr "" + +#: ../../howto/enum.rst:897 +msgid "Some rules:" +msgstr "一些規則：" + +#: ../../howto/enum.rst:899 +msgid "" +"When subclassing :class:`Enum`, mix-in types must appear before the :class:" +"`Enum` class itself in the sequence of bases, as in the :class:`IntEnum` " +"example above." +msgstr "" + +#: ../../howto/enum.rst:902 +msgid "" +"Mix-in types must be subclassable. For example, :class:`bool` and :class:" +"`range` are not subclassable and will throw an error during Enum creation if " +"used as the mix-in type." +msgstr "" + +#: ../../howto/enum.rst:905 +msgid "" +"While :class:`Enum` can have members of any type, once you mix in an " +"additional type, all the members must have values of that type, e.g. :class:" +"`int` above. This restriction does not apply to mix-ins which only add " +"methods and don't specify another type." +msgstr "" + +#: ../../howto/enum.rst:909 +msgid "" +"When another data type is mixed in, the :attr:`~Enum.value` attribute is " +"*not the same* as the enum member itself, although it is equivalent and will " +"compare equal." +msgstr "" + +#: ../../howto/enum.rst:912 +msgid "" +"A ``data type`` is a mixin that defines :meth:`~object.__new__`, or a :class:" +"`~dataclasses.dataclass`" +msgstr "" + +#: ../../howto/enum.rst:914 +msgid "" +"%-style formatting: ``%s`` and ``%r`` call the :class:`Enum` class's :meth:" +"`~object.__str__` and :meth:`~object.__repr__` respectively; other codes " +"(such as ``%i`` or ``%h`` for IntEnum) treat the enum member as its mixed-in " +"type." +msgstr "" + +#: ../../howto/enum.rst:917 +msgid "" +":ref:`Formatted string literals `, :meth:`str.format`, and :func:" +"`format` will use the enum's :meth:`~object.__str__` method." +msgstr "" + +#: ../../howto/enum.rst:922 +msgid "" +"Because :class:`IntEnum`, :class:`IntFlag`, and :class:`StrEnum` are " +"designed to be drop-in replacements for existing constants, their :meth:" +"`~object.__str__` method has been reset to their data types' :meth:`~object." +"__str__` method." +msgstr "" + +#: ../../howto/enum.rst:930 +msgid "When to use :meth:`~object.__new__` vs. :meth:`~object.__init__`" +msgstr "" + +#: ../../howto/enum.rst:932 +msgid "" +":meth:`~object.__new__` must be used whenever you want to customize the " +"actual value of the :class:`Enum` member. Any other modifications may go in " +"either :meth:`~object.__new__` or :meth:`~object.__init__`, with :meth:" +"`~object.__init__` being preferred." +msgstr "" + +#: ../../howto/enum.rst:936 +msgid "" +"For example, if you want to pass several items to the constructor, but only " +"want one of them to be the value::" +msgstr "" + +#: ../../howto/enum.rst:939 +msgid "" +">>> class Coordinate(bytes, Enum):\n" +"... \"\"\"\n" +"... Coordinate with binary codes that can be indexed by the int code.\n" +"... \"\"\"\n" +"... def __new__(cls, value, label, unit):\n" +"... obj = bytes.__new__(cls, [value])\n" +"... obj._value_ = value\n" +"... obj.label = label\n" +"... obj.unit = unit\n" +"... return obj\n" +"... PX = (0, 'P.X', 'km')\n" +"... PY = (1, 'P.Y', 'km')\n" +"... VX = (2, 'V.X', 'km/s')\n" +"... VY = (3, 'V.Y', 'km/s')\n" +"...\n" +"\n" +">>> print(Coordinate['PY'])\n" +"Coordinate.PY\n" +"\n" +">>> print(Coordinate(3))\n" +"Coordinate.VY" +msgstr "" + +#: ../../howto/enum.rst:963 +msgid "" +"*Do not* call ``super().__new__()``, as the lookup-only ``__new__`` is the " +"one that is found; instead, use the data type directly." +msgstr "" + +#: ../../howto/enum.rst:968 +msgid "Finer Points" +msgstr "" + +#: ../../howto/enum.rst:971 +msgid "Supported ``__dunder__`` names" +msgstr "有支援的 ``__dunder__`` 名稱" + +#: ../../howto/enum.rst:973 +msgid "" +":attr:`~enum.EnumType.__members__` is a read-only ordered mapping of " +"``member_name``:``member`` items. It is only available on the class." +msgstr "" + +#: ../../howto/enum.rst:976 +msgid "" +":meth:`~object.__new__`, if specified, must create and return the enum " +"members; it is also a very good idea to set the member's :attr:`~Enum." +"_value_` appropriately. Once all the members are created it is no longer " +"used." +msgstr "" + +#: ../../howto/enum.rst:982 +msgid "Supported ``_sunder_`` names" +msgstr "有支援的 ``_sunder_`` 名稱" + +#: ../../howto/enum.rst:984 +msgid ":attr:`~Enum._name_` -- name of the member" +msgstr ":attr:`~Enum._name_` -- 成員的名稱" + +#: ../../howto/enum.rst:985 +msgid ":attr:`~Enum._value_` -- value of the member; can be set in ``__new__``" +msgstr "" + +#: ../../howto/enum.rst:986 +msgid "" +":meth:`~Enum._missing_` -- a lookup function used when a value is not found; " +"may be overridden" +msgstr "" + +#: ../../howto/enum.rst:988 +msgid "" +":attr:`~Enum._ignore_` -- a list of names, either as a :class:`list` or a :" +"class:`str`, that will not be transformed into members, and will be removed " +"from the final class" +msgstr "" + +#: ../../howto/enum.rst:991 +msgid "" +":meth:`~Enum._generate_next_value_` -- used to get an appropriate value for " +"an enum member; may be overridden" +msgstr "" + +#: ../../howto/enum.rst:993 +msgid "" +":meth:`~Enum._add_alias_` -- adds a new name as an alias to an existing " +"member." +msgstr "" + +#: ../../howto/enum.rst:995 +msgid "" +":meth:`~Enum._add_value_alias_` -- adds a new value as an alias to an " +"existing member. See `MultiValueEnum`_ for an example." +msgstr "" + +#: ../../howto/enum.rst:1000 +msgid "" +"For standard :class:`Enum` classes the next value chosen is the highest " +"value seen incremented by one." +msgstr "" + +#: ../../howto/enum.rst:1003 +msgid "" +"For :class:`Flag` classes the next value chosen will be the next highest " +"power-of-two." +msgstr "" + +#: ../../howto/enum.rst:1006 +msgid "" +"Prior versions would use the last seen value instead of the highest value." +msgstr "" + +#: ../../howto/enum.rst:1009 +msgid "``_missing_``, ``_order_``, ``_generate_next_value_``" +msgstr "``_missing_``、``_order_``、``_generate_next_value_``" + +#: ../../howto/enum.rst:1010 +msgid "``_ignore_``" +msgstr "``_ignore_``" + +#: ../../howto/enum.rst:1011 +msgid "``_add_alias_``, ``_add_value_alias_``" +msgstr "``_add_alias_``、``_add_value_alias_``" + +#: ../../howto/enum.rst:1013 +msgid "" +"To help keep Python 2 / Python 3 code in sync an :attr:`~Enum._order_` " +"attribute can be provided. It will be checked against the actual order of " +"the enumeration and raise an error if the two do not match::" +msgstr "" + +#: ../../howto/enum.rst:1017 +msgid "" +">>> class Color(Enum):\n" +"... _order_ = 'RED GREEN BLUE'\n" +"... RED = 1\n" +"... BLUE = 3\n" +"... GREEN = 2\n" +"...\n" +"Traceback (most recent call last):\n" +"...\n" +"TypeError: member order does not match _order_:\n" +" ['RED', 'BLUE', 'GREEN']\n" +" ['RED', 'GREEN', 'BLUE']" +msgstr "" +">>> class Color(Enum):\n" +"... _order_ = 'RED GREEN BLUE'\n" +"... RED = 1\n" +"... BLUE = 3\n" +"... GREEN = 2\n" +"...\n" +"Traceback (most recent call last):\n" +"...\n" +"TypeError: member order does not match _order_:\n" +" ['RED', 'BLUE', 'GREEN']\n" +" ['RED', 'GREEN', 'BLUE']" + +#: ../../howto/enum.rst:1031 +msgid "" +"In Python 2 code the :attr:`~Enum._order_` attribute is necessary as " +"definition order is lost before it can be recorded." +msgstr "" + +#: ../../howto/enum.rst:1036 +msgid "_Private__names" +msgstr "_Private__names" + +#: ../../howto/enum.rst:1038 +msgid "" +":ref:`Private names ` are not converted to enum " +"members, but remain normal attributes." +msgstr "" + +#: ../../howto/enum.rst:1045 +msgid "``Enum`` member type" +msgstr "" + +#: ../../howto/enum.rst:1047 +msgid "" +"Enum members are instances of their enum class, and are normally accessed as " +"``EnumClass.member``. In certain situations, such as writing custom enum " +"behavior, being able to access one member directly from another is useful, " +"and is supported; however, in order to avoid name clashes between member " +"names and attributes/methods from mixed-in classes, upper-case names are " +"strongly recommended." +msgstr "" + +#: ../../howto/enum.rst:1058 +msgid "Creating members that are mixed with other data types" +msgstr "" + +#: ../../howto/enum.rst:1060 +msgid "" +"When subclassing other data types, such as :class:`int` or :class:`str`, " +"with an :class:`Enum`, all values after the ``=`` are passed to that data " +"type's constructor. For example::" +msgstr "" + +#: ../../howto/enum.rst:1064 +msgid "" +">>> class MyEnum(IntEnum): # help(int) -> int(x, base=10) -> integer\n" +"... example = '11', 16 # so x='11' and base=16\n" +"...\n" +">>> MyEnum.example.value # and hex(11) is...\n" +"17" +msgstr "" +">>> class MyEnum(IntEnum): # help(int) -> int(x, base=10) -> integer\n" +"... example = '11', 16 # 所以 x='11' 且 base=16\n" +"...\n" +">>> MyEnum.example.value # 且 hex(11) 為...\n" +"17" + +#: ../../howto/enum.rst:1072 +msgid "Boolean value of ``Enum`` classes and members" +msgstr "" + +#: ../../howto/enum.rst:1074 +msgid "" +"Enum classes that are mixed with non-:class:`Enum` types (such as :class:" +"`int`, :class:`str`, etc.) are evaluated according to the mixed-in type's " +"rules; otherwise, all members evaluate as :data:`True`. To make your own " +"enum's boolean evaluation depend on the member's value add the following to " +"your class::" +msgstr "" + +#: ../../howto/enum.rst:1080 +msgid "" +"def __bool__(self):\n" +" return bool(self.value)" +msgstr "" +"def __bool__(self):\n" +" return bool(self.value)" + +#: ../../howto/enum.rst:1083 +msgid "Plain :class:`Enum` classes always evaluate as :data:`True`." +msgstr "" + +#: ../../howto/enum.rst:1087 +msgid "``Enum`` classes with methods" +msgstr "" + +#: ../../howto/enum.rst:1089 +msgid "" +"If you give your enum subclass extra methods, like the `Planet`_ class " +"below, those methods will show up in a :func:`dir` of the member, but not of " +"the class::" +msgstr "" + +#: ../../howto/enum.rst:1093 +msgid "" +">>> dir(Planet)\n" +"['EARTH', 'JUPITER', 'MARS', 'MERCURY', 'NEPTUNE', 'SATURN', 'URANUS', " +"'VENUS', '__class__', '__doc__', '__members__', '__module__']\n" +">>> dir(Planet.EARTH)\n" +"['__class__', '__doc__', '__module__', 'mass', 'name', 'radius', " +"'surface_gravity', 'value']" +msgstr "" +">>> dir(Planet)\n" +"['EARTH', 'JUPITER', 'MARS', 'MERCURY', 'NEPTUNE', 'SATURN', 'URANUS', " +"'VENUS', '__class__', '__doc__', '__members__', '__module__']\n" +">>> dir(Planet.EARTH)\n" +"['__class__', '__doc__', '__module__', 'mass', 'name', 'radius', " +"'surface_gravity', 'value']" + +#: ../../howto/enum.rst:1100 +msgid "Combining members of ``Flag``" +msgstr "``Flag`` 的成員組合" + +#: ../../howto/enum.rst:1102 +msgid "" +"Iterating over a combination of :class:`Flag` members will only return the " +"members that are comprised of a single bit::" +msgstr "" + +#: ../../howto/enum.rst:1105 +msgid "" +">>> class Color(Flag):\n" +"... RED = auto()\n" +"... GREEN = auto()\n" +"... BLUE = auto()\n" +"... MAGENTA = RED | BLUE\n" +"... YELLOW = RED | GREEN\n" +"... CYAN = GREEN | BLUE\n" +"...\n" +">>> Color(3) # named combination\n" +"\n" +">>> Color(7) # not named combination\n" +"" +msgstr "" + +#: ../../howto/enum.rst:1120 +msgid "``Flag`` and ``IntFlag`` minutia" +msgstr "" + +#: ../../howto/enum.rst:1122 +msgid "Using the following snippet for our examples::" +msgstr "" + +#: ../../howto/enum.rst:1124 +msgid "" +">>> class Color(IntFlag):\n" +"... BLACK = 0\n" +"... RED = 1\n" +"... GREEN = 2\n" +"... BLUE = 4\n" +"... PURPLE = RED | BLUE\n" +"... WHITE = RED | GREEN | BLUE\n" +"..." +msgstr "" +">>> class Color(IntFlag):\n" +"... BLACK = 0\n" +"... RED = 1\n" +"... GREEN = 2\n" +"... BLUE = 4\n" +"... PURPLE = RED | BLUE\n" +"... WHITE = RED | GREEN | BLUE\n" +"..." + +#: ../../howto/enum.rst:1133 +msgid "the following are true:" +msgstr "" + +#: ../../howto/enum.rst:1135 +msgid "single-bit flags are canonical" +msgstr "" + +#: ../../howto/enum.rst:1136 +msgid "multi-bit and zero-bit flags are aliases" +msgstr "" + +#: ../../howto/enum.rst:1137 +msgid "only canonical flags are returned during iteration::" +msgstr "" + +#: ../../howto/enum.rst:1139 +msgid "" +">>> list(Color.WHITE)\n" +"[, , ]" +msgstr "" +">>> list(Color.WHITE)\n" +"[, , ]" + +#: ../../howto/enum.rst:1142 +msgid "" +"negating a flag or flag set returns a new flag/flag set with the " +"corresponding positive integer value::" +msgstr "" + +#: ../../howto/enum.rst:1145 +msgid "" +">>> Color.BLUE\n" +"\n" +"\n" +">>> ~Color.BLUE\n" +"" +msgstr "" +">>> Color.BLUE\n" +"\n" +"\n" +">>> ~Color.BLUE\n" +"" + +#: ../../howto/enum.rst:1151 +msgid "names of pseudo-flags are constructed from their members' names::" +msgstr "" + +#: ../../howto/enum.rst:1153 +msgid "" +">>> (Color.RED | Color.GREEN).name\n" +"'RED|GREEN'\n" +"\n" +">>> class Perm(IntFlag):\n" +"... R = 4\n" +"... W = 2\n" +"... X = 1\n" +"...\n" +">>> (Perm.R & Perm.W).name is None # effectively Perm(0)\n" +"True" +msgstr "" +">>> (Color.RED | Color.GREEN).name\n" +"'RED|GREEN'\n" +"\n" +">>> class Perm(IntFlag):\n" +"... R = 4\n" +"... W = 2\n" +"... X = 1\n" +"...\n" +">>> (Perm.R & Perm.W).name is None # 效果為 Perm(0)\n" +"True" + +#: ../../howto/enum.rst:1164 +msgid "multi-bit flags, aka aliases, can be returned from operations::" +msgstr "" + +#: ../../howto/enum.rst:1166 +msgid "" +">>> Color.RED | Color.BLUE\n" +"\n" +"\n" +">>> Color(7) # or Color(-1)\n" +"\n" +"\n" +">>> Color(0)\n" +"" +msgstr "" +">>> Color.RED | Color.BLUE\n" +"\n" +"\n" +">>> Color(7) # 或 Color(-1)\n" +"\n" +"\n" +">>> Color(0)\n" +"" + +#: ../../howto/enum.rst:1175 +msgid "" +"membership / containment checking: zero-valued flags are always considered " +"to be contained::" +msgstr "" + +#: ../../howto/enum.rst:1178 +msgid "" +">>> Color.BLACK in Color.WHITE\n" +"True" +msgstr "" +">>> Color.BLACK in Color.WHITE\n" +"True" + +#: ../../howto/enum.rst:1181 +msgid "" +"otherwise, only if all bits of one flag are in the other flag will True be " +"returned::" +msgstr "" + +#: ../../howto/enum.rst:1184 +msgid "" +">>> Color.PURPLE in Color.WHITE\n" +"True\n" +"\n" +">>> Color.GREEN in Color.PURPLE\n" +"False" +msgstr "" +">>> Color.PURPLE in Color.WHITE\n" +"True\n" +"\n" +">>> Color.GREEN in Color.PURPLE\n" +"False" + +#: ../../howto/enum.rst:1190 +msgid "" +"There is a new boundary mechanism that controls how out-of-range / invalid " +"bits are handled: ``STRICT``, ``CONFORM``, ``EJECT``, and ``KEEP``:" +msgstr "" + +#: ../../howto/enum.rst:1193 +msgid "STRICT --> raises an exception when presented with invalid values" +msgstr "STRICT --> 當遇到無效值時引發例外" + +#: ../../howto/enum.rst:1194 +msgid "CONFORM --> discards any invalid bits" +msgstr "CONFORM --> 捨棄任何無效位元" + +#: ../../howto/enum.rst:1195 +msgid "EJECT --> lose Flag status and become a normal int with the given value" +msgstr "EJECT --> 失去 Flag 狀態並成為具有給定值的普通 int" + +#: ../../howto/enum.rst:1196 +msgid "KEEP --> keep the extra bits" +msgstr "KEEP --> 保留額外位元" + +#: ../../howto/enum.rst:1198 +msgid "keeps Flag status and extra bits" +msgstr "保留 Flag 狀態和額外位元" + +#: ../../howto/enum.rst:1199 +msgid "extra bits do not show up in iteration" +msgstr "" + +#: ../../howto/enum.rst:1200 +msgid "extra bits do show up in repr() and str()" +msgstr "" + +#: ../../howto/enum.rst:1202 +msgid "" +"The default for Flag is ``STRICT``, the default for ``IntFlag`` is " +"``EJECT``, and the default for ``_convert_`` is ``KEEP`` (see ``ssl." +"Options`` for an example of when ``KEEP`` is needed)." +msgstr "" + +#: ../../howto/enum.rst:1210 +msgid "How are Enums and Flags different?" +msgstr "Enums 和 Flags 有何不同？" + +#: ../../howto/enum.rst:1212 +msgid "" +"Enums have a custom metaclass that affects many aspects of both derived :" +"class:`Enum` classes and their instances (members)." +msgstr "" + +#: ../../howto/enum.rst:1217 +msgid "Enum Classes" +msgstr "Enum 類別" + +#: ../../howto/enum.rst:1219 +msgid "" +"The :class:`EnumType` metaclass is responsible for providing the :meth:" +"`~object.__contains__`, :meth:`~object.__dir__`, :meth:`~object.__iter__` " +"and other methods that allow one to do things with an :class:`Enum` class " +"that fail on a typical class, such as ``list(Color)`` or ``some_enum_var in " +"Color``. :class:`EnumType` is responsible for ensuring that various other " +"methods on the final :class:`Enum` class are correct (such as :meth:`~object." +"__new__`, :meth:`~object.__getnewargs__`, :meth:`~object.__str__` and :meth:" +"`~object.__repr__`)." +msgstr "" + +#: ../../howto/enum.rst:1228 +msgid "Flag Classes" +msgstr "Flag 類別" + +#: ../../howto/enum.rst:1230 +msgid "" +"Flags have an expanded view of aliasing: to be canonical, the value of a " +"flag needs to be a power-of-two value, and not a duplicate name. So, in " +"addition to the :class:`Enum` definition of alias, a flag with no value (a.k." +"a. ``0``) or with more than one power-of-two value (e.g. ``3``) is " +"considered an alias." +msgstr "" + +#: ../../howto/enum.rst:1236 +msgid "Enum Members (aka instances)" +msgstr "" + +#: ../../howto/enum.rst:1238 +msgid "" +"The most interesting thing about enum members is that they are singletons. :" +"class:`EnumType` creates them all while it is creating the enum class " +"itself, and then puts a custom :meth:`~object.__new__` in place to ensure " +"that no new ones are ever instantiated by returning only the existing member " +"instances." +msgstr "" + +#: ../../howto/enum.rst:1244 +msgid "Flag Members" +msgstr "Flag 成員" + +#: ../../howto/enum.rst:1246 +msgid "" +"Flag members can be iterated over just like the :class:`Flag` class, and " +"only the canonical members will be returned. For example::" +msgstr "" + +#: ../../howto/enum.rst:1249 +msgid "" +">>> list(Color)\n" +"[, , ]" +msgstr "" +">>> list(Color)\n" +"[, , ]" + +#: ../../howto/enum.rst:1252 +msgid "(Note that ``BLACK``, ``PURPLE``, and ``WHITE`` do not show up.)" +msgstr "" + +#: ../../howto/enum.rst:1254 +msgid "" +"Inverting a flag member returns the corresponding positive value, rather " +"than a negative value --- for example::" +msgstr "" + +#: ../../howto/enum.rst:1257 +msgid "" +">>> ~Color.RED\n" +"" +msgstr "" +">>> ~Color.RED\n" +"" + +#: ../../howto/enum.rst:1260 +msgid "" +"Flag members have a length corresponding to the number of power-of-two " +"values they contain. For example::" +msgstr "" + +#: ../../howto/enum.rst:1263 +msgid "" +">>> len(Color.PURPLE)\n" +"2" +msgstr "" +">>> len(Color.PURPLE)\n" +"2" + +#: ../../howto/enum.rst:1270 +msgid "Enum Cookbook" +msgstr "" + +#: ../../howto/enum.rst:1273 +msgid "" +"While :class:`Enum`, :class:`IntEnum`, :class:`StrEnum`, :class:`Flag`, and :" +"class:`IntFlag` are expected to cover the majority of use-cases, they cannot " +"cover them all. Here are recipes for some different types of enumerations " +"that can be used directly, or as examples for creating one's own." +msgstr "" + +#: ../../howto/enum.rst:1280 +msgid "Omitting values" +msgstr "省略值" + +#: ../../howto/enum.rst:1282 +msgid "" +"In many use-cases, one doesn't care what the actual value of an enumeration " +"is. There are several ways to define this type of simple enumeration:" +msgstr "" + +#: ../../howto/enum.rst:1285 +msgid "use instances of :class:`auto` for the value" +msgstr "" + +#: ../../howto/enum.rst:1286 +msgid "use instances of :class:`object` as the value" +msgstr "" + +#: ../../howto/enum.rst:1287 +msgid "use a descriptive string as the value" +msgstr "" + +#: ../../howto/enum.rst:1288 +msgid "" +"use a tuple as the value and a custom :meth:`~object.__new__` to replace the " +"tuple with an :class:`int` value" +msgstr "" + +#: ../../howto/enum.rst:1291 +msgid "" +"Using any of these methods signifies to the user that these values are not " +"important, and also enables one to add, remove, or reorder members without " +"having to renumber the remaining members." +msgstr "" + +#: ../../howto/enum.rst:1297 +msgid "Using :class:`auto`" +msgstr "使用 :class:`auto`" + +#: ../../howto/enum.rst:1299 +msgid "Using :class:`auto` would look like::" +msgstr "使用 :class:`auto` 會像這樣： ::" + +#: ../../howto/enum.rst:1301 +msgid "" +">>> class Color(Enum):\n" +"... RED = auto()\n" +"... BLUE = auto()\n" +"... GREEN = auto()\n" +"...\n" +">>> Color.GREEN\n" +"" +msgstr "" +">>> class Color(Enum):\n" +"... RED = auto()\n" +"... BLUE = auto()\n" +"... GREEN = auto()\n" +"...\n" +">>> Color.GREEN\n" +"" + +#: ../../howto/enum.rst:1311 +msgid "Using :class:`object`" +msgstr "使用 :class:`object`" + +#: ../../howto/enum.rst:1313 +msgid "Using :class:`object` would look like::" +msgstr "使用 :class:`object` 會像這樣： ::" + +#: ../../howto/enum.rst:1315 +msgid "" +">>> class Color(Enum):\n" +"... RED = object()\n" +"... GREEN = object()\n" +"... BLUE = object()\n" +"...\n" +">>> Color.GREEN\n" +">" +msgstr "" +">>> class Color(Enum):\n" +"... RED = object()\n" +"... GREEN = object()\n" +"... BLUE = object()\n" +"...\n" +">>> Color.GREEN\n" +">" + +#: ../../howto/enum.rst:1323 +msgid "" +"This is also a good example of why you might want to write your own :meth:" +"`~object.__repr__`::" +msgstr "" + +#: ../../howto/enum.rst:1326 +msgid "" +">>> class Color(Enum):\n" +"... RED = object()\n" +"... GREEN = object()\n" +"... BLUE = object()\n" +"... def __repr__(self):\n" +"... return \"<%s.%s>\" % (self.__class__.__name__, self._name_)\n" +"...\n" +">>> Color.GREEN\n" +"" +msgstr "" +">>> class Color(Enum):\n" +"... RED = object()\n" +"... GREEN = object()\n" +"... BLUE = object()\n" +"... def __repr__(self):\n" +"... return \"<%s.%s>\" % (self.__class__.__name__, self._name_)\n" +"...\n" +">>> Color.GREEN\n" +"" + +#: ../../howto/enum.rst:1339 +msgid "Using a descriptive string" +msgstr "" + +#: ../../howto/enum.rst:1341 +msgid "Using a string as the value would look like::" +msgstr "" + +#: ../../howto/enum.rst:1343 +msgid "" +">>> class Color(Enum):\n" +"... RED = 'stop'\n" +"... GREEN = 'go'\n" +"... BLUE = 'too fast!'\n" +"...\n" +">>> Color.GREEN\n" +"" +msgstr "" +">>> class Color(Enum):\n" +"... RED = 'stop'\n" +"... GREEN = 'go'\n" +"... BLUE = 'too fast!'\n" +"...\n" +">>> Color.GREEN\n" +"" + +#: ../../howto/enum.rst:1353 +msgid "Using a custom :meth:`~object.__new__`" +msgstr "使用自訂的 :meth:`~object.__new__`" + +#: ../../howto/enum.rst:1355 +msgid "Using an auto-numbering :meth:`~object.__new__` would look like::" +msgstr "" + +#: ../../howto/enum.rst:1357 +msgid "" +">>> class AutoNumber(Enum):\n" +"... def __new__(cls):\n" +"... value = len(cls.__members__) + 1\n" +"... obj = object.__new__(cls)\n" +"... obj._value_ = value\n" +"... return obj\n" +"...\n" +">>> class Color(AutoNumber):\n" +"... RED = ()\n" +"... GREEN = ()\n" +"... BLUE = ()\n" +"...\n" +">>> Color.GREEN\n" +"" +msgstr "" +">>> class AutoNumber(Enum):\n" +"... def __new__(cls):\n" +"... value = len(cls.__members__) + 1\n" +"... obj = object.__new__(cls)\n" +"... obj._value_ = value\n" +"... return obj\n" +"...\n" +">>> class Color(AutoNumber):\n" +"... RED = ()\n" +"... GREEN = ()\n" +"... BLUE = ()\n" +"...\n" +">>> Color.GREEN\n" +"" + +#: ../../howto/enum.rst:1372 +msgid "" +"To make a more general purpose ``AutoNumber``, add ``*args`` to the " +"signature::" +msgstr "" + +#: ../../howto/enum.rst:1374 +msgid "" +">>> class AutoNumber(Enum):\n" +"... def __new__(cls, *args): # this is the only change from above\n" +"... value = len(cls.__members__) + 1\n" +"... obj = object.__new__(cls)\n" +"... obj._value_ = value\n" +"... return obj\n" +"..." +msgstr "" +">>> class AutoNumber(Enum):\n" +"... def __new__(cls, *args): # 這是和上面相比唯一的變更\n" +"... value = len(cls.__members__) + 1\n" +"... obj = object.__new__(cls)\n" +"... obj._value_ = value\n" +"... return obj\n" +"..." + +#: ../../howto/enum.rst:1382 +msgid "" +"Then when you inherit from ``AutoNumber`` you can write your own " +"``__init__`` to handle any extra arguments::" +msgstr "" + +#: ../../howto/enum.rst:1385 +msgid "" +">>> class Swatch(AutoNumber):\n" +"... def __init__(self, pantone='unknown'):\n" +"... self.pantone = pantone\n" +"... AUBURN = '3497'\n" +"... SEA_GREEN = '1246'\n" +"... BLEACHED_CORAL = () # New color, no Pantone code yet!\n" +"...\n" +">>> Swatch.SEA_GREEN\n" +"\n" +">>> Swatch.SEA_GREEN.pantone\n" +"'1246'\n" +">>> Swatch.BLEACHED_CORAL.pantone\n" +"'unknown'" +msgstr "" + +#: ../../howto/enum.rst:1401 +msgid "" +"The :meth:`~object.__new__` method, if defined, is used during creation of " +"the Enum members; it is then replaced by Enum's :meth:`~object.__new__` " +"which is used after class creation for lookup of existing members." +msgstr "" + +#: ../../howto/enum.rst:1407 +msgid "" +"*Do not* call ``super().__new__()``, as the lookup-only ``__new__`` is the " +"one that is found; instead, use the data type directly -- e.g.::" +msgstr "" + +#: ../../howto/enum.rst:1410 +msgid "obj = int.__new__(cls, value)" +msgstr "obj = int.__new__(cls, value)" + +#: ../../howto/enum.rst:1414 +msgid "OrderedEnum" +msgstr "OrderedEnum" + +#: ../../howto/enum.rst:1416 +msgid "" +"An ordered enumeration that is not based on :class:`IntEnum` and so " +"maintains the normal :class:`Enum` invariants (such as not being comparable " +"to other enumerations)::" +msgstr "" + +#: ../../howto/enum.rst:1420 +msgid "" +">>> class OrderedEnum(Enum):\n" +"... def __ge__(self, other):\n" +"... if self.__class__ is other.__class__:\n" +"... return self.value >= other.value\n" +"... return NotImplemented\n" +"... def __gt__(self, other):\n" +"... if self.__class__ is other.__class__:\n" +"... return self.value > other.value\n" +"... return NotImplemented\n" +"... def __le__(self, other):\n" +"... if self.__class__ is other.__class__:\n" +"... return self.value <= other.value\n" +"... return NotImplemented\n" +"... def __lt__(self, other):\n" +"... if self.__class__ is other.__class__:\n" +"... return self.value < other.value\n" +"... return NotImplemented\n" +"...\n" +">>> class Grade(OrderedEnum):\n" +"... A = 5\n" +"... B = 4\n" +"... C = 3\n" +"... D = 2\n" +"... F = 1\n" +"...\n" +">>> Grade.C < Grade.A\n" +"True" +msgstr "" +">>> class OrderedEnum(Enum):\n" +"... def __ge__(self, other):\n" +"... if self.__class__ is other.__class__:\n" +"... return self.value >= other.value\n" +"... return NotImplemented\n" +"... def __gt__(self, other):\n" +"... if self.__class__ is other.__class__:\n" +"... return self.value > other.value\n" +"... return NotImplemented\n" +"... def __le__(self, other):\n" +"... if self.__class__ is other.__class__:\n" +"... return self.value <= other.value\n" +"... return NotImplemented\n" +"... def __lt__(self, other):\n" +"... if self.__class__ is other.__class__:\n" +"... return self.value < other.value\n" +"... return NotImplemented\n" +"...\n" +">>> class Grade(OrderedEnum):\n" +"... A = 5\n" +"... B = 4\n" +"... C = 3\n" +"... D = 2\n" +"... F = 1\n" +"...\n" +">>> Grade.C < Grade.A\n" +"True" + +#: ../../howto/enum.rst:1450 +msgid "DuplicateFreeEnum" +msgstr "DuplicateFreeEnum" + +#: ../../howto/enum.rst:1452 +msgid "" +"Raises an error if a duplicate member value is found instead of creating an " +"alias::" +msgstr "" + +#: ../../howto/enum.rst:1455 +msgid "" +">>> class DuplicateFreeEnum(Enum):\n" +"... def __init__(self, *args):\n" +"... cls = self.__class__\n" +"... if any(self.value == e.value for e in cls):\n" +"... a = self.name\n" +"... e = cls(self.value).name\n" +"... raise ValueError(\n" +"... \"aliases not allowed in DuplicateFreeEnum: %r --> " +"%r\"\n" +"... % (a, e))\n" +"...\n" +">>> class Color(DuplicateFreeEnum):\n" +"... RED = 1\n" +"... GREEN = 2\n" +"... BLUE = 3\n" +"... GRENE = 2\n" +"...\n" +"Traceback (most recent call last):\n" +" ...\n" +"ValueError: aliases not allowed in DuplicateFreeEnum: 'GRENE' --> 'GREEN'" +msgstr "" +">>> class DuplicateFreeEnum(Enum):\n" +"... def __init__(self, *args):\n" +"... cls = self.__class__\n" +"... if any(self.value == e.value for e in cls):\n" +"... a = self.name\n" +"... e = cls(self.value).name\n" +"... raise ValueError(\n" +"... \"aliases not allowed in DuplicateFreeEnum: %r --> " +"%r\"\n" +"... % (a, e))\n" +"...\n" +">>> class Color(DuplicateFreeEnum):\n" +"... RED = 1\n" +"... GREEN = 2\n" +"... BLUE = 3\n" +"... GRENE = 2\n" +"...\n" +"Traceback (most recent call last):\n" +" ...\n" +"ValueError: aliases not allowed in DuplicateFreeEnum: 'GRENE' --> 'GREEN'" + +#: ../../howto/enum.rst:1477 +msgid "" +"This is a useful example for subclassing Enum to add or change other " +"behaviors as well as disallowing aliases. If the only desired change is " +"disallowing aliases, the :func:`unique` decorator can be used instead." +msgstr "" + +#: ../../howto/enum.rst:1483 +msgid "MultiValueEnum" +msgstr "MultiValueEnum" + +#: ../../howto/enum.rst:1485 +msgid "Supports having more than one value per member::" +msgstr "" + +#: ../../howto/enum.rst:1487 +msgid "" +">>> class MultiValueEnum(Enum):\n" +"... def __new__(cls, value, *values):\n" +"... self = object.__new__(cls)\n" +"... self._value_ = value\n" +"... for v in values:\n" +"... self._add_value_alias_(v)\n" +"... return self\n" +"...\n" +">>> class DType(MultiValueEnum):\n" +"... float32 = 'f', 8\n" +"... double64 = 'd', 9\n" +"...\n" +">>> DType('f')\n" +"\n" +">>> DType(9)\n" +"" +msgstr "" +">>> class MultiValueEnum(Enum):\n" +"... def __new__(cls, value, *values):\n" +"... self = object.__new__(cls)\n" +"... self._value_ = value\n" +"... for v in values:\n" +"... self._add_value_alias_(v)\n" +"... return self\n" +"...\n" +">>> class DType(MultiValueEnum):\n" +"... float32 = 'f', 8\n" +"... double64 = 'd', 9\n" +"...\n" +">>> DType('f')\n" +"\n" +">>> DType(9)\n" +"" + +#: ../../howto/enum.rst:1506 +msgid "Planet" +msgstr "" + +#: ../../howto/enum.rst:1508 +msgid "" +"If :meth:`~object.__new__` or :meth:`~object.__init__` is defined, the value " +"of the enum member will be passed to those methods::" +msgstr "" + +#: ../../howto/enum.rst:1511 +msgid "" +">>> class Planet(Enum):\n" +"... MERCURY = (3.303e+23, 2.4397e6)\n" +"... VENUS = (4.869e+24, 6.0518e6)\n" +"... EARTH = (5.976e+24, 6.37814e6)\n" +"... MARS = (6.421e+23, 3.3972e6)\n" +"... JUPITER = (1.9e+27, 7.1492e7)\n" +"... SATURN = (5.688e+26, 6.0268e7)\n" +"... URANUS = (8.686e+25, 2.5559e7)\n" +"... NEPTUNE = (1.024e+26, 2.4746e7)\n" +"... def __init__(self, mass, radius):\n" +"... self.mass = mass # in kilograms\n" +"... self.radius = radius # in meters\n" +"... @property\n" +"... def surface_gravity(self):\n" +"... # universal gravitational constant (m3 kg-1 s-2)\n" +"... G = 6.67300E-11\n" +"... return G * self.mass / (self.radius * self.radius)\n" +"...\n" +">>> Planet.EARTH.value\n" +"(5.976e+24, 6378140.0)\n" +">>> Planet.EARTH.surface_gravity\n" +"9.802652743337129" +msgstr "" +">>> class Planet(Enum):\n" +"... MERCURY = (3.303e+23, 2.4397e6)\n" +"... VENUS = (4.869e+24, 6.0518e6)\n" +"... EARTH = (5.976e+24, 6.37814e6)\n" +"... MARS = (6.421e+23, 3.3972e6)\n" +"... JUPITER = (1.9e+27, 7.1492e7)\n" +"... SATURN = (5.688e+26, 6.0268e7)\n" +"... URANUS = (8.686e+25, 2.5559e7)\n" +"... NEPTUNE = (1.024e+26, 2.4746e7)\n" +"... def __init__(self, mass, radius):\n" +"... self.mass = mass # 以公斤表示\n" +"... self.radius = radius # 以公尺表示\n" +"... @property\n" +"... def surface_gravity(self):\n" +"... # 萬有引力常數 (m3 kg-1 s-2)\n" +"... G = 6.67300E-11\n" +"... return G * self.mass / (self.radius * self.radius)\n" +"...\n" +">>> Planet.EARTH.value\n" +"(5.976e+24, 6378140.0)\n" +">>> Planet.EARTH.surface_gravity\n" +"9.802652743337129" + +#: ../../howto/enum.rst:1537 +msgid "TimePeriod" +msgstr "" + +#: ../../howto/enum.rst:1539 +msgid "An example to show the :attr:`~Enum._ignore_` attribute in use::" +msgstr "" + +#: ../../howto/enum.rst:1541 +msgid "" +">>> from datetime import timedelta\n" +">>> class Period(timedelta, Enum):\n" +"... \"different lengths of time\"\n" +"... _ignore_ = 'Period i'\n" +"... Period = vars()\n" +"... for i in range(367):\n" +"... Period['day_%d' % i] = i\n" +"...\n" +">>> list(Period)[:2]\n" +"[, ]\n" +">>> list(Period)[-2:]\n" +"[, ]" +msgstr "" +">>> from datetime import timedelta\n" +">>> class Period(timedelta, Enum):\n" +"... \"不同長度的時間\"\n" +"... _ignore_ = 'Period i'\n" +"... Period = vars()\n" +"... for i in range(367):\n" +"... Period['day_%d' % i] = i\n" +"...\n" +">>> list(Period)[:2]\n" +"[, ]\n" +">>> list(Period)[-2:]\n" +"[, ]" + +#: ../../howto/enum.rst:1558 +msgid "Subclassing EnumType" +msgstr "子類別化 EnumType" + +#: ../../howto/enum.rst:1560 +msgid "" +"While most enum needs can be met by customizing :class:`Enum` subclasses, " +"either with class decorators or custom functions, :class:`EnumType` can be " +"subclassed to provide a different Enum experience." +msgstr "" diff --git a/howto/free-threading-extensions.po b/howto/free-threading-extensions.po index fbb9971737..c630c80fab 100644 --- a/howto/free-threading-extensions.po +++ b/howto/free-threading-extensions.po @@ -1,723 +1,723 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -#, fuzzy -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-07 00:14+0000\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \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" - -#: ../../howto/free-threading-extensions.rst:7 -msgid "C API Extension Support for Free Threading" -msgstr "支援自由執行緒的 C API 擴充" - -#: ../../howto/free-threading-extensions.rst:9 -msgid "" -"Starting with the 3.13 release, CPython has support for running with the :" -"term:`global interpreter lock` (GIL) disabled in a configuration called :" -"term:`free threading`. This document describes how to adapt C API " -"extensions to support free threading." -msgstr "" - -#: ../../howto/free-threading-extensions.rst:16 -msgid "Identifying the Free-Threaded Build in C" -msgstr "" - -#: ../../howto/free-threading-extensions.rst:18 -msgid "" -"The CPython C API exposes the ``Py_GIL_DISABLED`` macro: in the free-" -"threaded build it's defined to ``1``, and in the regular build it's not " -"defined. You can use it to enable code that only runs under the free-" -"threaded build::" -msgstr "" - -#: ../../howto/free-threading-extensions.rst:22 -msgid "" -"#ifdef Py_GIL_DISABLED\n" -"/* code that only runs in the free-threaded build */\n" -"#endif" -msgstr "" - -#: ../../howto/free-threading-extensions.rst:28 -msgid "" -"On Windows, this macro is not defined automatically, but must be specified " -"to the compiler when building. The :func:`sysconfig.get_config_var` function " -"can be used to determine whether the current running interpreter had the " -"macro defined." -msgstr "" - -#: ../../howto/free-threading-extensions.rst:35 -msgid "Module Initialization" -msgstr "模組初始化" - -#: ../../howto/free-threading-extensions.rst:37 -msgid "" -"Extension modules need to explicitly indicate that they support running with " -"the GIL disabled; otherwise importing the extension will raise a warning and " -"enable the GIL at runtime." -msgstr "" - -#: ../../howto/free-threading-extensions.rst:41 -msgid "" -"There are two ways to indicate that an extension module supports running " -"with the GIL disabled depending on whether the extension uses multi-phase or " -"single-phase initialization." -msgstr "" - -#: ../../howto/free-threading-extensions.rst:46 -msgid "Multi-Phase Initialization" -msgstr "" - -#: ../../howto/free-threading-extensions.rst:48 -msgid "" -"Extensions that use multi-phase initialization (i.e., :c:func:" -"`PyModuleDef_Init`) should add a :c:data:`Py_mod_gil` slot in the module " -"definition. If your extension supports older versions of CPython, you " -"should guard the slot with a :c:data:`PY_VERSION_HEX` check." -msgstr "" - -#: ../../howto/free-threading-extensions.rst:55 -msgid "" -"static struct PyModuleDef_Slot module_slots[] = {\n" -" ...\n" -"#if PY_VERSION_HEX >= 0x030D0000\n" -" {Py_mod_gil, Py_MOD_GIL_NOT_USED},\n" -"#endif\n" -" {0, NULL}\n" -"};\n" -"\n" -"static struct PyModuleDef moduledef = {\n" -" PyModuleDef_HEAD_INIT,\n" -" .m_slots = module_slots,\n" -" ...\n" -"};" -msgstr "" -"static struct PyModuleDef_Slot module_slots[] = {\n" -" ...\n" -"#if PY_VERSION_HEX >= 0x030D0000\n" -" {Py_mod_gil, Py_MOD_GIL_NOT_USED},\n" -"#endif\n" -" {0, NULL}\n" -"};\n" -"\n" -"static struct PyModuleDef moduledef = {\n" -" PyModuleDef_HEAD_INIT,\n" -" .m_slots = module_slots,\n" -" ...\n" -"};" - -#: ../../howto/free-threading-extensions.rst:71 -msgid "Single-Phase Initialization" -msgstr "單一階段初始化 (Single-Phase Initialization)" - -#: ../../howto/free-threading-extensions.rst:73 -msgid "" -"Extensions that use single-phase initialization (i.e., :c:func:" -"`PyModule_Create`) should call :c:func:`PyUnstable_Module_SetGIL` to " -"indicate that they support running with the GIL disabled. The function is " -"only defined in the free-threaded build, so you should guard the call with " -"``#ifdef Py_GIL_DISABLED`` to avoid compilation errors in the regular build." -msgstr "" - -#: ../../howto/free-threading-extensions.rst:81 -msgid "" -"static struct PyModuleDef moduledef = {\n" -" PyModuleDef_HEAD_INIT,\n" -" ...\n" -"};\n" -"\n" -"PyMODINIT_FUNC\n" -"PyInit_mymodule(void)\n" -"{\n" -" PyObject *m = PyModule_Create(&moduledef);\n" -" if (m == NULL) {\n" -" return NULL;\n" -" }\n" -"#ifdef Py_GIL_DISABLED\n" -" PyUnstable_Module_SetGIL(m, Py_MOD_GIL_NOT_USED);\n" -"#endif\n" -" return m;\n" -"}" -msgstr "" -"static struct PyModuleDef moduledef = {\n" -" PyModuleDef_HEAD_INIT,\n" -" ...\n" -"};\n" -"\n" -"PyMODINIT_FUNC\n" -"PyInit_mymodule(void)\n" -"{\n" -" PyObject *m = PyModule_Create(&moduledef);\n" -" if (m == NULL) {\n" -" return NULL;\n" -" }\n" -"#ifdef Py_GIL_DISABLED\n" -" PyUnstable_Module_SetGIL(m, Py_MOD_GIL_NOT_USED);\n" -"#endif\n" -" return m;\n" -"}" - -#: ../../howto/free-threading-extensions.rst:101 -msgid "General API Guidelines" -msgstr "" - -#: ../../howto/free-threading-extensions.rst:103 -msgid "Most of the C API is thread-safe, but there are some exceptions." -msgstr "" - -#: ../../howto/free-threading-extensions.rst:105 -msgid "" -"**Struct Fields**: Accessing fields in Python C API objects or structs " -"directly is not thread-safe if the field may be concurrently modified." -msgstr "" - -#: ../../howto/free-threading-extensions.rst:107 -msgid "" -"**Macros**: Accessor macros like :c:macro:`PyList_GET_ITEM`, :c:macro:" -"`PyList_SET_ITEM`, and macros like :c:macro:`PySequence_Fast_GET_SIZE` that " -"use the object returned by :c:func:`PySequence_Fast` do not perform any " -"error checking or locking. These macros are not thread-safe if the container " -"object may be modified concurrently." -msgstr "" - -#: ../../howto/free-threading-extensions.rst:113 -msgid "" -"**Borrowed References**: C API functions that return :term:`borrowed " -"references ` may not be thread-safe if the containing " -"object is modified concurrently. See the section on :ref:`borrowed " -"references ` for more information." -msgstr "" - -#: ../../howto/free-threading-extensions.rst:120 -msgid "Container Thread Safety" -msgstr "容器執行緒安全性" - -#: ../../howto/free-threading-extensions.rst:122 -msgid "" -"Containers like :c:struct:`PyListObject`, :c:struct:`PyDictObject`, and :c:" -"struct:`PySetObject` perform internal locking in the free-threaded build. " -"For example, the :c:func:`PyList_Append` will lock the list before appending " -"an item." -msgstr "" - -#: ../../howto/free-threading-extensions.rst:130 -msgid "``PyDict_Next``" -msgstr "``PyDict_Next``" - -#: ../../howto/free-threading-extensions.rst:132 -msgid "" -"A notable exception is :c:func:`PyDict_Next`, which does not lock the " -"dictionary. You should use :c:macro:`Py_BEGIN_CRITICAL_SECTION` to protect " -"the dictionary while iterating over it if the dictionary may be concurrently " -"modified::" -msgstr "" - -#: ../../howto/free-threading-extensions.rst:137 -msgid "" -"Py_BEGIN_CRITICAL_SECTION(dict);\n" -"PyObject *key, *value;\n" -"Py_ssize_t pos = 0;\n" -"while (PyDict_Next(dict, &pos, &key, &value)) {\n" -" ...\n" -"}\n" -"Py_END_CRITICAL_SECTION();" -msgstr "" -"Py_BEGIN_CRITICAL_SECTION(dict);\n" -"PyObject *key, *value;\n" -"Py_ssize_t pos = 0;\n" -"while (PyDict_Next(dict, &pos, &key, &value)) {\n" -" ...\n" -"}\n" -"Py_END_CRITICAL_SECTION();" - -#: ../../howto/free-threading-extensions.rst:147 -msgid "Borrowed References" -msgstr "借用參照" - -#: ../../howto/free-threading-extensions.rst:151 -msgid "" -"Some C API functions return :term:`borrowed references `. These APIs are not thread-safe if the containing object is " -"modified concurrently. For example, it's not safe to use :c:func:" -"`PyList_GetItem` if the list may be modified concurrently." -msgstr "" - -#: ../../howto/free-threading-extensions.rst:156 -msgid "" -"The following table lists some borrowed reference APIs and their " -"replacements that return :term:`strong references `." -msgstr "" - -#: ../../howto/free-threading-extensions.rst:160 -msgid "Borrowed reference API" -msgstr "借用參照 API" - -#: ../../howto/free-threading-extensions.rst:160 -msgid "Strong reference API" -msgstr "強參照 API" - -#: ../../howto/free-threading-extensions.rst:162 -msgid ":c:func:`PyList_GetItem`" -msgstr ":c:func:`PyList_GetItem`" - -#: ../../howto/free-threading-extensions.rst:162 -#: ../../howto/free-threading-extensions.rst:164 -msgid ":c:func:`PyList_GetItemRef`" -msgstr ":c:func:`PyList_GetItemRef`" - -#: ../../howto/free-threading-extensions.rst:164 -msgid ":c:func:`PyList_GET_ITEM`" -msgstr ":c:func:`PyList_GET_ITEM`" - -#: ../../howto/free-threading-extensions.rst:166 -msgid ":c:func:`PyDict_GetItem`" -msgstr ":c:func:`PyDict_GetItem`" - -#: ../../howto/free-threading-extensions.rst:166 -#: ../../howto/free-threading-extensions.rst:168 -msgid ":c:func:`PyDict_GetItemRef`" -msgstr ":c:func:`PyDict_GetItemRef`" - -#: ../../howto/free-threading-extensions.rst:168 -msgid ":c:func:`PyDict_GetItemWithError`" -msgstr ":c:func:`PyDict_GetItemWithError`" - -#: ../../howto/free-threading-extensions.rst:170 -msgid ":c:func:`PyDict_GetItemString`" -msgstr ":c:func:`PyDict_GetItemString`" - -#: ../../howto/free-threading-extensions.rst:170 -msgid ":c:func:`PyDict_GetItemStringRef`" -msgstr ":c:func:`PyDict_GetItemStringRef`" - -#: ../../howto/free-threading-extensions.rst:172 -msgid ":c:func:`PyDict_SetDefault`" -msgstr ":c:func:`PyDict_SetDefault`" - -#: ../../howto/free-threading-extensions.rst:172 -msgid ":c:func:`PyDict_SetDefaultRef`" -msgstr ":c:func:`PyDict_SetDefaultRef`" - -#: ../../howto/free-threading-extensions.rst:174 -msgid ":c:func:`PyDict_Next`" -msgstr ":c:func:`PyDict_Next`" - -#: ../../howto/free-threading-extensions.rst:174 -msgid "none (see :ref:`PyDict_Next`)" -msgstr "" - -#: ../../howto/free-threading-extensions.rst:176 -msgid ":c:func:`PyWeakref_GetObject`" -msgstr ":c:func:`PyWeakref_GetObject`" - -#: ../../howto/free-threading-extensions.rst:176 -#: ../../howto/free-threading-extensions.rst:178 -msgid ":c:func:`PyWeakref_GetRef`" -msgstr ":c:func:`PyWeakref_GetRef`" - -#: ../../howto/free-threading-extensions.rst:178 -msgid ":c:func:`PyWeakref_GET_OBJECT`" -msgstr ":c:func:`PyWeakref_GET_OBJECT`" - -#: ../../howto/free-threading-extensions.rst:180 -msgid ":c:func:`PyImport_AddModule`" -msgstr ":c:func:`PyImport_AddModule`" - -#: ../../howto/free-threading-extensions.rst:180 -msgid ":c:func:`PyImport_AddModuleRef`" -msgstr ":c:func:`PyImport_AddModuleRef`" - -#: ../../howto/free-threading-extensions.rst:182 -msgid ":c:func:`PyCell_GET`" -msgstr ":c:func:`PyCell_GET`" - -#: ../../howto/free-threading-extensions.rst:182 -msgid ":c:func:`PyCell_Get`" -msgstr ":c:func:`PyCell_Get`" - -#: ../../howto/free-threading-extensions.rst:185 -msgid "" -"Not all APIs that return borrowed references are problematic. For example, :" -"c:func:`PyTuple_GetItem` is safe because tuples are immutable. Similarly, " -"not all uses of the above APIs are problematic. For example, :c:func:" -"`PyDict_GetItem` is often used for parsing keyword argument dictionaries in " -"function calls; those keyword argument dictionaries are effectively private " -"(not accessible by other threads), so using borrowed references in that " -"context is safe." -msgstr "" - -#: ../../howto/free-threading-extensions.rst:193 -msgid "" -"Some of these functions were added in Python 3.13. You can use the " -"`pythoncapi-compat `_ package " -"to provide implementations of these functions for older Python versions." -msgstr "" - -#: ../../howto/free-threading-extensions.rst:201 -msgid "Memory Allocation APIs" -msgstr "" - -#: ../../howto/free-threading-extensions.rst:203 -msgid "" -"Python's memory management C API provides functions in three different :ref:" -"`allocation domains `: \"raw\", \"mem\", and \"object\". " -"For thread-safety, the free-threaded build requires that only Python objects " -"are allocated using the object domain, and that all Python objects are " -"allocated using that domain. This differs from the prior Python versions, " -"where this was only a best practice and not a hard requirement." -msgstr "" - -#: ../../howto/free-threading-extensions.rst:212 -msgid "" -"Search for uses of :c:func:`PyObject_Malloc` in your extension and check " -"that the allocated memory is used for Python objects. Use :c:func:" -"`PyMem_Malloc` to allocate buffers instead of :c:func:`PyObject_Malloc`." -msgstr "" - -#: ../../howto/free-threading-extensions.rst:219 -msgid "Thread State and GIL APIs" -msgstr "" - -#: ../../howto/free-threading-extensions.rst:221 -msgid "" -"Python provides a set of functions and macros to manage thread state and the " -"GIL, such as:" -msgstr "" - -#: ../../howto/free-threading-extensions.rst:224 -msgid ":c:func:`PyGILState_Ensure` and :c:func:`PyGILState_Release`" -msgstr ":c:func:`PyGILState_Ensure` 和 :c:func:`PyGILState_Release`" - -#: ../../howto/free-threading-extensions.rst:225 -msgid ":c:func:`PyEval_SaveThread` and :c:func:`PyEval_RestoreThread`" -msgstr ":c:func:`PyEval_SaveThread` 和 :c:func:`PyEval_RestoreThread`" - -#: ../../howto/free-threading-extensions.rst:226 -msgid ":c:macro:`Py_BEGIN_ALLOW_THREADS` and :c:macro:`Py_END_ALLOW_THREADS`" -msgstr ":c:macro:`Py_BEGIN_ALLOW_THREADS` 和 :c:macro:`Py_END_ALLOW_THREADS`" - -#: ../../howto/free-threading-extensions.rst:228 -msgid "" -"These functions should still be used in the free-threaded build to manage " -"thread state even when the :term:`GIL` is disabled. For example, if you " -"create a thread outside of Python, you must call :c:func:`PyGILState_Ensure` " -"before calling into the Python API to ensure that the thread has a valid " -"Python thread state." -msgstr "" - -#: ../../howto/free-threading-extensions.rst:234 -msgid "" -"You should continue to call :c:func:`PyEval_SaveThread` or :c:macro:" -"`Py_BEGIN_ALLOW_THREADS` around blocking operations, such as I/O or lock " -"acquisitions, to allow other threads to run the :term:`cyclic garbage " -"collector `." -msgstr "" - -#: ../../howto/free-threading-extensions.rst:241 -msgid "Protecting Internal Extension State" -msgstr "" - -#: ../../howto/free-threading-extensions.rst:243 -msgid "" -"Your extension may have internal state that was previously protected by the " -"GIL. You may need to add locking to protect this state. The approach will " -"depend on your extension, but some common patterns include:" -msgstr "" - -#: ../../howto/free-threading-extensions.rst:247 -msgid "" -"**Caches**: global caches are a common source of shared state. Consider " -"using a lock to protect the cache or disabling it in the free-threaded build " -"if the cache is not critical for performance." -msgstr "" - -#: ../../howto/free-threading-extensions.rst:250 -msgid "" -"**Global State**: global state may need to be protected by a lock or moved " -"to thread local storage. C11 and C++11 provide the ``thread_local`` or " -"``_Thread_local`` for `thread-local storage `_." -msgstr "" - -#: ../../howto/free-threading-extensions.rst:257 -msgid "Critical Sections" -msgstr "" - -#: ../../howto/free-threading-extensions.rst:261 -msgid "" -"In the free-threaded build, CPython provides a mechanism called \"critical " -"sections\" to protect data that would otherwise be protected by the GIL. " -"While extension authors may not interact with the internal critical section " -"implementation directly, understanding their behavior is crucial when using " -"certain C API functions or managing shared state in the free-threaded build." -msgstr "" - -#: ../../howto/free-threading-extensions.rst:268 -msgid "What Are Critical Sections?" -msgstr "" - -#: ../../howto/free-threading-extensions.rst:270 -msgid "" -"Conceptually, critical sections act as a deadlock avoidance layer built on " -"top of simple mutexes. Each thread maintains a stack of active critical " -"sections. When a thread needs to acquire a lock associated with a critical " -"section (e.g., implicitly when calling a thread-safe C API function like :c:" -"func:`PyDict_SetItem`, or explicitly using macros), it attempts to acquire " -"the underlying mutex." -msgstr "" - -#: ../../howto/free-threading-extensions.rst:278 -msgid "Using Critical Sections" -msgstr "" - -#: ../../howto/free-threading-extensions.rst:280 -msgid "The primary APIs for using critical sections are:" -msgstr "" - -#: ../../howto/free-threading-extensions.rst:282 -msgid "" -":c:macro:`Py_BEGIN_CRITICAL_SECTION` and :c:macro:`Py_END_CRITICAL_SECTION` " -"- For locking a single object" -msgstr "" - -#: ../../howto/free-threading-extensions.rst:285 -msgid "" -":c:macro:`Py_BEGIN_CRITICAL_SECTION2` and :c:macro:" -"`Py_END_CRITICAL_SECTION2` - For locking two objects simultaneously" -msgstr "" - -#: ../../howto/free-threading-extensions.rst:288 -msgid "" -"These macros must be used in matching pairs and must appear in the same C " -"scope, since they establish a new local scope. These macros are no-ops in " -"non-free-threaded builds, so they can be safely added to code that needs to " -"support both build types." -msgstr "" - -#: ../../howto/free-threading-extensions.rst:293 -msgid "" -"A common use of a critical section would be to lock an object while " -"accessing an internal attribute of it. For example, if an extension type " -"has an internal count field, you could use a critical section while reading " -"or writing that field::" -msgstr "" - -#: ../../howto/free-threading-extensions.rst:298 -msgid "" -"// read the count, returns new reference to internal count value\n" -"PyObject *result;\n" -"Py_BEGIN_CRITICAL_SECTION(obj);\n" -"result = Py_NewRef(obj->count);\n" -"Py_END_CRITICAL_SECTION();\n" -"return result;\n" -"\n" -"// write the count, consumes reference from new_count\n" -"Py_BEGIN_CRITICAL_SECTION(obj);\n" -"obj->count = new_count;\n" -"Py_END_CRITICAL_SECTION();" -msgstr "" - -#: ../../howto/free-threading-extensions.rst:312 -msgid "How Critical Sections Work" -msgstr "" - -#: ../../howto/free-threading-extensions.rst:314 -msgid "" -"Unlike traditional locks, critical sections do not guarantee exclusive " -"access throughout their entire duration. If a thread would block while " -"holding a critical section (e.g., by acquiring another lock or performing I/" -"O), the critical section is temporarily suspended—all locks are released—and " -"then resumed when the blocking operation completes." -msgstr "" - -#: ../../howto/free-threading-extensions.rst:320 -msgid "" -"This behavior is similar to what happens with the GIL when a thread makes a " -"blocking call. The key differences are:" -msgstr "" - -#: ../../howto/free-threading-extensions.rst:323 -msgid "Critical sections operate on a per-object basis rather than globally" -msgstr "" - -#: ../../howto/free-threading-extensions.rst:325 -msgid "" -"Critical sections follow a stack discipline within each thread (the " -"\"begin\" and \"end\" macros enforce this since they must be paired and " -"within the same scope)" -msgstr "" - -#: ../../howto/free-threading-extensions.rst:328 -msgid "" -"Critical sections automatically release and reacquire locks around potential " -"blocking operations" -msgstr "" - -#: ../../howto/free-threading-extensions.rst:332 -msgid "Deadlock Avoidance" -msgstr "" - -#: ../../howto/free-threading-extensions.rst:334 -msgid "Critical sections help avoid deadlocks in two ways:" -msgstr "" - -#: ../../howto/free-threading-extensions.rst:336 -msgid "" -"If a thread tries to acquire a lock that's already held by another thread, " -"it first suspends all of its active critical sections, temporarily releasing " -"their locks" -msgstr "" - -#: ../../howto/free-threading-extensions.rst:340 -msgid "" -"When the blocking operation completes, only the top-most critical section is " -"reacquired first" -msgstr "" - -#: ../../howto/free-threading-extensions.rst:343 -msgid "" -"This means you cannot rely on nested critical sections to lock multiple " -"objects at once, as the inner critical section may suspend the outer ones. " -"Instead, use :c:macro:`Py_BEGIN_CRITICAL_SECTION2` to lock two objects " -"simultaneously." -msgstr "" - -#: ../../howto/free-threading-extensions.rst:347 -msgid "" -"Note that the locks described above are only :c:type:`PyMutex` based locks. " -"The critical section implementation does not know about or affect other " -"locking mechanisms that might be in use, like POSIX mutexes. Also note that " -"while blocking on any :c:type:`PyMutex` causes the critical sections to be " -"suspended, only the mutexes that are part of the critical sections are " -"released. If :c:type:`PyMutex` is used without a critical section, it will " -"not be released and therefore does not get the same deadlock avoidance." -msgstr "" - -#: ../../howto/free-threading-extensions.rst:356 -msgid "Important Considerations" -msgstr "" - -#: ../../howto/free-threading-extensions.rst:358 -msgid "" -"Critical sections may temporarily release their locks, allowing other " -"threads to modify the protected data. Be careful about making assumptions " -"about the state of the data after operations that might block." -msgstr "" - -#: ../../howto/free-threading-extensions.rst:362 -msgid "" -"Because locks can be temporarily released (suspended), entering a critical " -"section does not guarantee exclusive access to the protected resource " -"throughout the section's duration. If code within a critical section calls " -"another function that blocks (e.g., acquires another lock, performs blocking " -"I/O), all locks held by the thread via critical sections will be released. " -"This is similar to how the GIL can be released during blocking calls." -msgstr "" - -#: ../../howto/free-threading-extensions.rst:369 -msgid "" -"Only the lock(s) associated with the most recently entered (top-most) " -"critical section are guaranteed to be held at any given time. Locks for " -"outer, nested critical sections might have been suspended." -msgstr "" - -#: ../../howto/free-threading-extensions.rst:373 -msgid "" -"You can lock at most two objects simultaneously with these APIs. If you need " -"to lock more objects, you'll need to restructure your code." -msgstr "" - -#: ../../howto/free-threading-extensions.rst:376 -msgid "" -"While critical sections will not deadlock if you attempt to lock the same " -"object twice, they are less efficient than purpose-built reentrant locks for " -"this use case." -msgstr "" - -#: ../../howto/free-threading-extensions.rst:380 -msgid "" -"When using :c:macro:`Py_BEGIN_CRITICAL_SECTION2`, the order of the objects " -"doesn't affect correctness (the implementation handles deadlock avoidance), " -"but it's good practice to always lock objects in a consistent order." -msgstr "" - -#: ../../howto/free-threading-extensions.rst:384 -msgid "" -"Remember that the critical section macros are primarily for protecting " -"access to *Python objects* that might be involved in internal CPython " -"operations susceptible to the deadlock scenarios described above. For " -"protecting purely internal extension state, standard mutexes or other " -"synchronization primitives might be more appropriate." -msgstr "" - -#: ../../howto/free-threading-extensions.rst:392 -msgid "Building Extensions for the Free-Threaded Build" -msgstr "" - -#: ../../howto/free-threading-extensions.rst:394 -msgid "" -"C API extensions need to be built specifically for the free-threaded build. " -"The wheels, shared libraries, and binaries are indicated by a ``t`` suffix." -msgstr "" - -#: ../../howto/free-threading-extensions.rst:397 -msgid "" -"`pypa/manylinux `_ supports the free-" -"threaded build, with the ``t`` suffix, such as ``python3.13t``." -msgstr "" - -#: ../../howto/free-threading-extensions.rst:399 -msgid "" -"`pypa/cibuildwheel `_ supports the " -"free-threaded build on Python 3.13 and 3.14. On Python 3.14, free-threaded " -"wheels will be built by default. On Python 3.13, you will need to set " -"`CIBW_ENABLE to cpython-freethreading `_." -msgstr "" - -#: ../../howto/free-threading-extensions.rst:405 -msgid "Limited C API and Stable ABI" -msgstr "" - -#: ../../howto/free-threading-extensions.rst:407 -msgid "" -"The free-threaded build does not currently support the :ref:`Limited C API " -"` or the stable ABI. If you use `setuptools `_ to build your extension and " -"currently set ``py_limited_api=True`` you can use ``py_limited_api=not " -"sysconfig.get_config_var(\"Py_GIL_DISABLED\")`` to opt out of the limited " -"API when building with the free-threaded build." -msgstr "" - -#: ../../howto/free-threading-extensions.rst:415 -msgid "" -"You will need to build separate wheels specifically for the free-threaded " -"build. If you currently use the stable ABI, you can continue to build a " -"single wheel for multiple non-free-threaded Python versions." -msgstr "" - -#: ../../howto/free-threading-extensions.rst:421 -msgid "Windows" -msgstr "Windows" - -#: ../../howto/free-threading-extensions.rst:423 -msgid "" -"Due to a limitation of the official Windows installer, you will need to " -"manually define ``Py_GIL_DISABLED=1`` when building extensions from source." -msgstr "" - -#: ../../howto/free-threading-extensions.rst:428 -msgid "" -"`Porting Extension Modules to Support Free-Threading `_: A community-maintained porting guide for " -"extension authors." -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-07 00:14+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \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" + +#: ../../howto/free-threading-extensions.rst:7 +msgid "C API Extension Support for Free Threading" +msgstr "支援自由執行緒的 C API 擴充" + +#: ../../howto/free-threading-extensions.rst:9 +msgid "" +"Starting with the 3.13 release, CPython has support for running with the :" +"term:`global interpreter lock` (GIL) disabled in a configuration called :" +"term:`free threading`. This document describes how to adapt C API " +"extensions to support free threading." +msgstr "" + +#: ../../howto/free-threading-extensions.rst:16 +msgid "Identifying the Free-Threaded Build in C" +msgstr "" + +#: ../../howto/free-threading-extensions.rst:18 +msgid "" +"The CPython C API exposes the ``Py_GIL_DISABLED`` macro: in the free-" +"threaded build it's defined to ``1``, and in the regular build it's not " +"defined. You can use it to enable code that only runs under the free-" +"threaded build::" +msgstr "" + +#: ../../howto/free-threading-extensions.rst:22 +msgid "" +"#ifdef Py_GIL_DISABLED\n" +"/* code that only runs in the free-threaded build */\n" +"#endif" +msgstr "" + +#: ../../howto/free-threading-extensions.rst:28 +msgid "" +"On Windows, this macro is not defined automatically, but must be specified " +"to the compiler when building. The :func:`sysconfig.get_config_var` function " +"can be used to determine whether the current running interpreter had the " +"macro defined." +msgstr "" + +#: ../../howto/free-threading-extensions.rst:35 +msgid "Module Initialization" +msgstr "模組初始化" + +#: ../../howto/free-threading-extensions.rst:37 +msgid "" +"Extension modules need to explicitly indicate that they support running with " +"the GIL disabled; otherwise importing the extension will raise a warning and " +"enable the GIL at runtime." +msgstr "" + +#: ../../howto/free-threading-extensions.rst:41 +msgid "" +"There are two ways to indicate that an extension module supports running " +"with the GIL disabled depending on whether the extension uses multi-phase or " +"single-phase initialization." +msgstr "" + +#: ../../howto/free-threading-extensions.rst:46 +msgid "Multi-Phase Initialization" +msgstr "" + +#: ../../howto/free-threading-extensions.rst:48 +msgid "" +"Extensions that use multi-phase initialization (i.e., :c:func:" +"`PyModuleDef_Init`) should add a :c:data:`Py_mod_gil` slot in the module " +"definition. If your extension supports older versions of CPython, you " +"should guard the slot with a :c:data:`PY_VERSION_HEX` check." +msgstr "" + +#: ../../howto/free-threading-extensions.rst:55 +msgid "" +"static struct PyModuleDef_Slot module_slots[] = {\n" +" ...\n" +"#if PY_VERSION_HEX >= 0x030D0000\n" +" {Py_mod_gil, Py_MOD_GIL_NOT_USED},\n" +"#endif\n" +" {0, NULL}\n" +"};\n" +"\n" +"static struct PyModuleDef moduledef = {\n" +" PyModuleDef_HEAD_INIT,\n" +" .m_slots = module_slots,\n" +" ...\n" +"};" +msgstr "" +"static struct PyModuleDef_Slot module_slots[] = {\n" +" ...\n" +"#if PY_VERSION_HEX >= 0x030D0000\n" +" {Py_mod_gil, Py_MOD_GIL_NOT_USED},\n" +"#endif\n" +" {0, NULL}\n" +"};\n" +"\n" +"static struct PyModuleDef moduledef = {\n" +" PyModuleDef_HEAD_INIT,\n" +" .m_slots = module_slots,\n" +" ...\n" +"};" + +#: ../../howto/free-threading-extensions.rst:71 +msgid "Single-Phase Initialization" +msgstr "單一階段初始化 (Single-Phase Initialization)" + +#: ../../howto/free-threading-extensions.rst:73 +msgid "" +"Extensions that use single-phase initialization (i.e., :c:func:" +"`PyModule_Create`) should call :c:func:`PyUnstable_Module_SetGIL` to " +"indicate that they support running with the GIL disabled. The function is " +"only defined in the free-threaded build, so you should guard the call with " +"``#ifdef Py_GIL_DISABLED`` to avoid compilation errors in the regular build." +msgstr "" + +#: ../../howto/free-threading-extensions.rst:81 +msgid "" +"static struct PyModuleDef moduledef = {\n" +" PyModuleDef_HEAD_INIT,\n" +" ...\n" +"};\n" +"\n" +"PyMODINIT_FUNC\n" +"PyInit_mymodule(void)\n" +"{\n" +" PyObject *m = PyModule_Create(&moduledef);\n" +" if (m == NULL) {\n" +" return NULL;\n" +" }\n" +"#ifdef Py_GIL_DISABLED\n" +" PyUnstable_Module_SetGIL(m, Py_MOD_GIL_NOT_USED);\n" +"#endif\n" +" return m;\n" +"}" +msgstr "" +"static struct PyModuleDef moduledef = {\n" +" PyModuleDef_HEAD_INIT,\n" +" ...\n" +"};\n" +"\n" +"PyMODINIT_FUNC\n" +"PyInit_mymodule(void)\n" +"{\n" +" PyObject *m = PyModule_Create(&moduledef);\n" +" if (m == NULL) {\n" +" return NULL;\n" +" }\n" +"#ifdef Py_GIL_DISABLED\n" +" PyUnstable_Module_SetGIL(m, Py_MOD_GIL_NOT_USED);\n" +"#endif\n" +" return m;\n" +"}" + +#: ../../howto/free-threading-extensions.rst:101 +msgid "General API Guidelines" +msgstr "" + +#: ../../howto/free-threading-extensions.rst:103 +msgid "Most of the C API is thread-safe, but there are some exceptions." +msgstr "" + +#: ../../howto/free-threading-extensions.rst:105 +msgid "" +"**Struct Fields**: Accessing fields in Python C API objects or structs " +"directly is not thread-safe if the field may be concurrently modified." +msgstr "" + +#: ../../howto/free-threading-extensions.rst:107 +msgid "" +"**Macros**: Accessor macros like :c:macro:`PyList_GET_ITEM`, :c:macro:" +"`PyList_SET_ITEM`, and macros like :c:macro:`PySequence_Fast_GET_SIZE` that " +"use the object returned by :c:func:`PySequence_Fast` do not perform any " +"error checking or locking. These macros are not thread-safe if the container " +"object may be modified concurrently." +msgstr "" + +#: ../../howto/free-threading-extensions.rst:113 +msgid "" +"**Borrowed References**: C API functions that return :term:`borrowed " +"references ` may not be thread-safe if the containing " +"object is modified concurrently. See the section on :ref:`borrowed " +"references ` for more information." +msgstr "" + +#: ../../howto/free-threading-extensions.rst:120 +msgid "Container Thread Safety" +msgstr "容器執行緒安全性" + +#: ../../howto/free-threading-extensions.rst:122 +msgid "" +"Containers like :c:struct:`PyListObject`, :c:struct:`PyDictObject`, and :c:" +"struct:`PySetObject` perform internal locking in the free-threaded build. " +"For example, the :c:func:`PyList_Append` will lock the list before appending " +"an item." +msgstr "" + +#: ../../howto/free-threading-extensions.rst:130 +msgid "``PyDict_Next``" +msgstr "``PyDict_Next``" + +#: ../../howto/free-threading-extensions.rst:132 +msgid "" +"A notable exception is :c:func:`PyDict_Next`, which does not lock the " +"dictionary. You should use :c:macro:`Py_BEGIN_CRITICAL_SECTION` to protect " +"the dictionary while iterating over it if the dictionary may be concurrently " +"modified::" +msgstr "" + +#: ../../howto/free-threading-extensions.rst:137 +msgid "" +"Py_BEGIN_CRITICAL_SECTION(dict);\n" +"PyObject *key, *value;\n" +"Py_ssize_t pos = 0;\n" +"while (PyDict_Next(dict, &pos, &key, &value)) {\n" +" ...\n" +"}\n" +"Py_END_CRITICAL_SECTION();" +msgstr "" +"Py_BEGIN_CRITICAL_SECTION(dict);\n" +"PyObject *key, *value;\n" +"Py_ssize_t pos = 0;\n" +"while (PyDict_Next(dict, &pos, &key, &value)) {\n" +" ...\n" +"}\n" +"Py_END_CRITICAL_SECTION();" + +#: ../../howto/free-threading-extensions.rst:147 +msgid "Borrowed References" +msgstr "借用參照" + +#: ../../howto/free-threading-extensions.rst:151 +msgid "" +"Some C API functions return :term:`borrowed references `. These APIs are not thread-safe if the containing object is " +"modified concurrently. For example, it's not safe to use :c:func:" +"`PyList_GetItem` if the list may be modified concurrently." +msgstr "" + +#: ../../howto/free-threading-extensions.rst:156 +msgid "" +"The following table lists some borrowed reference APIs and their " +"replacements that return :term:`strong references `." +msgstr "" + +#: ../../howto/free-threading-extensions.rst:160 +msgid "Borrowed reference API" +msgstr "借用參照 API" + +#: ../../howto/free-threading-extensions.rst:160 +msgid "Strong reference API" +msgstr "強參照 API" + +#: ../../howto/free-threading-extensions.rst:162 +msgid ":c:func:`PyList_GetItem`" +msgstr ":c:func:`PyList_GetItem`" + +#: ../../howto/free-threading-extensions.rst:162 +#: ../../howto/free-threading-extensions.rst:164 +msgid ":c:func:`PyList_GetItemRef`" +msgstr ":c:func:`PyList_GetItemRef`" + +#: ../../howto/free-threading-extensions.rst:164 +msgid ":c:func:`PyList_GET_ITEM`" +msgstr ":c:func:`PyList_GET_ITEM`" + +#: ../../howto/free-threading-extensions.rst:166 +msgid ":c:func:`PyDict_GetItem`" +msgstr ":c:func:`PyDict_GetItem`" + +#: ../../howto/free-threading-extensions.rst:166 +#: ../../howto/free-threading-extensions.rst:168 +msgid ":c:func:`PyDict_GetItemRef`" +msgstr ":c:func:`PyDict_GetItemRef`" + +#: ../../howto/free-threading-extensions.rst:168 +msgid ":c:func:`PyDict_GetItemWithError`" +msgstr ":c:func:`PyDict_GetItemWithError`" + +#: ../../howto/free-threading-extensions.rst:170 +msgid ":c:func:`PyDict_GetItemString`" +msgstr ":c:func:`PyDict_GetItemString`" + +#: ../../howto/free-threading-extensions.rst:170 +msgid ":c:func:`PyDict_GetItemStringRef`" +msgstr ":c:func:`PyDict_GetItemStringRef`" + +#: ../../howto/free-threading-extensions.rst:172 +msgid ":c:func:`PyDict_SetDefault`" +msgstr ":c:func:`PyDict_SetDefault`" + +#: ../../howto/free-threading-extensions.rst:172 +msgid ":c:func:`PyDict_SetDefaultRef`" +msgstr ":c:func:`PyDict_SetDefaultRef`" + +#: ../../howto/free-threading-extensions.rst:174 +msgid ":c:func:`PyDict_Next`" +msgstr ":c:func:`PyDict_Next`" + +#: ../../howto/free-threading-extensions.rst:174 +msgid "none (see :ref:`PyDict_Next`)" +msgstr "" + +#: ../../howto/free-threading-extensions.rst:176 +msgid ":c:func:`PyWeakref_GetObject`" +msgstr ":c:func:`PyWeakref_GetObject`" + +#: ../../howto/free-threading-extensions.rst:176 +#: ../../howto/free-threading-extensions.rst:178 +msgid ":c:func:`PyWeakref_GetRef`" +msgstr ":c:func:`PyWeakref_GetRef`" + +#: ../../howto/free-threading-extensions.rst:178 +msgid ":c:func:`PyWeakref_GET_OBJECT`" +msgstr ":c:func:`PyWeakref_GET_OBJECT`" + +#: ../../howto/free-threading-extensions.rst:180 +msgid ":c:func:`PyImport_AddModule`" +msgstr ":c:func:`PyImport_AddModule`" + +#: ../../howto/free-threading-extensions.rst:180 +msgid ":c:func:`PyImport_AddModuleRef`" +msgstr ":c:func:`PyImport_AddModuleRef`" + +#: ../../howto/free-threading-extensions.rst:182 +msgid ":c:func:`PyCell_GET`" +msgstr ":c:func:`PyCell_GET`" + +#: ../../howto/free-threading-extensions.rst:182 +msgid ":c:func:`PyCell_Get`" +msgstr ":c:func:`PyCell_Get`" + +#: ../../howto/free-threading-extensions.rst:185 +msgid "" +"Not all APIs that return borrowed references are problematic. For example, :" +"c:func:`PyTuple_GetItem` is safe because tuples are immutable. Similarly, " +"not all uses of the above APIs are problematic. For example, :c:func:" +"`PyDict_GetItem` is often used for parsing keyword argument dictionaries in " +"function calls; those keyword argument dictionaries are effectively private " +"(not accessible by other threads), so using borrowed references in that " +"context is safe." +msgstr "" + +#: ../../howto/free-threading-extensions.rst:193 +msgid "" +"Some of these functions were added in Python 3.13. You can use the " +"`pythoncapi-compat `_ package " +"to provide implementations of these functions for older Python versions." +msgstr "" + +#: ../../howto/free-threading-extensions.rst:201 +msgid "Memory Allocation APIs" +msgstr "" + +#: ../../howto/free-threading-extensions.rst:203 +msgid "" +"Python's memory management C API provides functions in three different :ref:" +"`allocation domains `: \"raw\", \"mem\", and \"object\". " +"For thread-safety, the free-threaded build requires that only Python objects " +"are allocated using the object domain, and that all Python objects are " +"allocated using that domain. This differs from the prior Python versions, " +"where this was only a best practice and not a hard requirement." +msgstr "" + +#: ../../howto/free-threading-extensions.rst:212 +msgid "" +"Search for uses of :c:func:`PyObject_Malloc` in your extension and check " +"that the allocated memory is used for Python objects. Use :c:func:" +"`PyMem_Malloc` to allocate buffers instead of :c:func:`PyObject_Malloc`." +msgstr "" + +#: ../../howto/free-threading-extensions.rst:219 +msgid "Thread State and GIL APIs" +msgstr "" + +#: ../../howto/free-threading-extensions.rst:221 +msgid "" +"Python provides a set of functions and macros to manage thread state and the " +"GIL, such as:" +msgstr "" + +#: ../../howto/free-threading-extensions.rst:224 +msgid ":c:func:`PyGILState_Ensure` and :c:func:`PyGILState_Release`" +msgstr ":c:func:`PyGILState_Ensure` 和 :c:func:`PyGILState_Release`" + +#: ../../howto/free-threading-extensions.rst:225 +msgid ":c:func:`PyEval_SaveThread` and :c:func:`PyEval_RestoreThread`" +msgstr ":c:func:`PyEval_SaveThread` 和 :c:func:`PyEval_RestoreThread`" + +#: ../../howto/free-threading-extensions.rst:226 +msgid ":c:macro:`Py_BEGIN_ALLOW_THREADS` and :c:macro:`Py_END_ALLOW_THREADS`" +msgstr ":c:macro:`Py_BEGIN_ALLOW_THREADS` 和 :c:macro:`Py_END_ALLOW_THREADS`" + +#: ../../howto/free-threading-extensions.rst:228 +msgid "" +"These functions should still be used in the free-threaded build to manage " +"thread state even when the :term:`GIL` is disabled. For example, if you " +"create a thread outside of Python, you must call :c:func:`PyGILState_Ensure` " +"before calling into the Python API to ensure that the thread has a valid " +"Python thread state." +msgstr "" + +#: ../../howto/free-threading-extensions.rst:234 +msgid "" +"You should continue to call :c:func:`PyEval_SaveThread` or :c:macro:" +"`Py_BEGIN_ALLOW_THREADS` around blocking operations, such as I/O or lock " +"acquisitions, to allow other threads to run the :term:`cyclic garbage " +"collector `." +msgstr "" + +#: ../../howto/free-threading-extensions.rst:241 +msgid "Protecting Internal Extension State" +msgstr "" + +#: ../../howto/free-threading-extensions.rst:243 +msgid "" +"Your extension may have internal state that was previously protected by the " +"GIL. You may need to add locking to protect this state. The approach will " +"depend on your extension, but some common patterns include:" +msgstr "" + +#: ../../howto/free-threading-extensions.rst:247 +msgid "" +"**Caches**: global caches are a common source of shared state. Consider " +"using a lock to protect the cache or disabling it in the free-threaded build " +"if the cache is not critical for performance." +msgstr "" + +#: ../../howto/free-threading-extensions.rst:250 +msgid "" +"**Global State**: global state may need to be protected by a lock or moved " +"to thread local storage. C11 and C++11 provide the ``thread_local`` or " +"``_Thread_local`` for `thread-local storage `_." +msgstr "" + +#: ../../howto/free-threading-extensions.rst:257 +msgid "Critical Sections" +msgstr "" + +#: ../../howto/free-threading-extensions.rst:261 +msgid "" +"In the free-threaded build, CPython provides a mechanism called \"critical " +"sections\" to protect data that would otherwise be protected by the GIL. " +"While extension authors may not interact with the internal critical section " +"implementation directly, understanding their behavior is crucial when using " +"certain C API functions or managing shared state in the free-threaded build." +msgstr "" + +#: ../../howto/free-threading-extensions.rst:268 +msgid "What Are Critical Sections?" +msgstr "" + +#: ../../howto/free-threading-extensions.rst:270 +msgid "" +"Conceptually, critical sections act as a deadlock avoidance layer built on " +"top of simple mutexes. Each thread maintains a stack of active critical " +"sections. When a thread needs to acquire a lock associated with a critical " +"section (e.g., implicitly when calling a thread-safe C API function like :c:" +"func:`PyDict_SetItem`, or explicitly using macros), it attempts to acquire " +"the underlying mutex." +msgstr "" + +#: ../../howto/free-threading-extensions.rst:278 +msgid "Using Critical Sections" +msgstr "" + +#: ../../howto/free-threading-extensions.rst:280 +msgid "The primary APIs for using critical sections are:" +msgstr "" + +#: ../../howto/free-threading-extensions.rst:282 +msgid "" +":c:macro:`Py_BEGIN_CRITICAL_SECTION` and :c:macro:`Py_END_CRITICAL_SECTION` " +"- For locking a single object" +msgstr "" + +#: ../../howto/free-threading-extensions.rst:285 +msgid "" +":c:macro:`Py_BEGIN_CRITICAL_SECTION2` and :c:macro:" +"`Py_END_CRITICAL_SECTION2` - For locking two objects simultaneously" +msgstr "" + +#: ../../howto/free-threading-extensions.rst:288 +msgid "" +"These macros must be used in matching pairs and must appear in the same C " +"scope, since they establish a new local scope. These macros are no-ops in " +"non-free-threaded builds, so they can be safely added to code that needs to " +"support both build types." +msgstr "" + +#: ../../howto/free-threading-extensions.rst:293 +msgid "" +"A common use of a critical section would be to lock an object while " +"accessing an internal attribute of it. For example, if an extension type " +"has an internal count field, you could use a critical section while reading " +"or writing that field::" +msgstr "" + +#: ../../howto/free-threading-extensions.rst:298 +msgid "" +"// read the count, returns new reference to internal count value\n" +"PyObject *result;\n" +"Py_BEGIN_CRITICAL_SECTION(obj);\n" +"result = Py_NewRef(obj->count);\n" +"Py_END_CRITICAL_SECTION();\n" +"return result;\n" +"\n" +"// write the count, consumes reference from new_count\n" +"Py_BEGIN_CRITICAL_SECTION(obj);\n" +"obj->count = new_count;\n" +"Py_END_CRITICAL_SECTION();" +msgstr "" + +#: ../../howto/free-threading-extensions.rst:312 +msgid "How Critical Sections Work" +msgstr "" + +#: ../../howto/free-threading-extensions.rst:314 +msgid "" +"Unlike traditional locks, critical sections do not guarantee exclusive " +"access throughout their entire duration. If a thread would block while " +"holding a critical section (e.g., by acquiring another lock or performing I/" +"O), the critical section is temporarily suspended—all locks are released—and " +"then resumed when the blocking operation completes." +msgstr "" + +#: ../../howto/free-threading-extensions.rst:320 +msgid "" +"This behavior is similar to what happens with the GIL when a thread makes a " +"blocking call. The key differences are:" +msgstr "" + +#: ../../howto/free-threading-extensions.rst:323 +msgid "Critical sections operate on a per-object basis rather than globally" +msgstr "" + +#: ../../howto/free-threading-extensions.rst:325 +msgid "" +"Critical sections follow a stack discipline within each thread (the " +"\"begin\" and \"end\" macros enforce this since they must be paired and " +"within the same scope)" +msgstr "" + +#: ../../howto/free-threading-extensions.rst:328 +msgid "" +"Critical sections automatically release and reacquire locks around potential " +"blocking operations" +msgstr "" + +#: ../../howto/free-threading-extensions.rst:332 +msgid "Deadlock Avoidance" +msgstr "" + +#: ../../howto/free-threading-extensions.rst:334 +msgid "Critical sections help avoid deadlocks in two ways:" +msgstr "" + +#: ../../howto/free-threading-extensions.rst:336 +msgid "" +"If a thread tries to acquire a lock that's already held by another thread, " +"it first suspends all of its active critical sections, temporarily releasing " +"their locks" +msgstr "" + +#: ../../howto/free-threading-extensions.rst:340 +msgid "" +"When the blocking operation completes, only the top-most critical section is " +"reacquired first" +msgstr "" + +#: ../../howto/free-threading-extensions.rst:343 +msgid "" +"This means you cannot rely on nested critical sections to lock multiple " +"objects at once, as the inner critical section may suspend the outer ones. " +"Instead, use :c:macro:`Py_BEGIN_CRITICAL_SECTION2` to lock two objects " +"simultaneously." +msgstr "" + +#: ../../howto/free-threading-extensions.rst:347 +msgid "" +"Note that the locks described above are only :c:type:`PyMutex` based locks. " +"The critical section implementation does not know about or affect other " +"locking mechanisms that might be in use, like POSIX mutexes. Also note that " +"while blocking on any :c:type:`PyMutex` causes the critical sections to be " +"suspended, only the mutexes that are part of the critical sections are " +"released. If :c:type:`PyMutex` is used without a critical section, it will " +"not be released and therefore does not get the same deadlock avoidance." +msgstr "" + +#: ../../howto/free-threading-extensions.rst:356 +msgid "Important Considerations" +msgstr "" + +#: ../../howto/free-threading-extensions.rst:358 +msgid "" +"Critical sections may temporarily release their locks, allowing other " +"threads to modify the protected data. Be careful about making assumptions " +"about the state of the data after operations that might block." +msgstr "" + +#: ../../howto/free-threading-extensions.rst:362 +msgid "" +"Because locks can be temporarily released (suspended), entering a critical " +"section does not guarantee exclusive access to the protected resource " +"throughout the section's duration. If code within a critical section calls " +"another function that blocks (e.g., acquires another lock, performs blocking " +"I/O), all locks held by the thread via critical sections will be released. " +"This is similar to how the GIL can be released during blocking calls." +msgstr "" + +#: ../../howto/free-threading-extensions.rst:369 +msgid "" +"Only the lock(s) associated with the most recently entered (top-most) " +"critical section are guaranteed to be held at any given time. Locks for " +"outer, nested critical sections might have been suspended." +msgstr "" + +#: ../../howto/free-threading-extensions.rst:373 +msgid "" +"You can lock at most two objects simultaneously with these APIs. If you need " +"to lock more objects, you'll need to restructure your code." +msgstr "" + +#: ../../howto/free-threading-extensions.rst:376 +msgid "" +"While critical sections will not deadlock if you attempt to lock the same " +"object twice, they are less efficient than purpose-built reentrant locks for " +"this use case." +msgstr "" + +#: ../../howto/free-threading-extensions.rst:380 +msgid "" +"When using :c:macro:`Py_BEGIN_CRITICAL_SECTION2`, the order of the objects " +"doesn't affect correctness (the implementation handles deadlock avoidance), " +"but it's good practice to always lock objects in a consistent order." +msgstr "" + +#: ../../howto/free-threading-extensions.rst:384 +msgid "" +"Remember that the critical section macros are primarily for protecting " +"access to *Python objects* that might be involved in internal CPython " +"operations susceptible to the deadlock scenarios described above. For " +"protecting purely internal extension state, standard mutexes or other " +"synchronization primitives might be more appropriate." +msgstr "" + +#: ../../howto/free-threading-extensions.rst:392 +msgid "Building Extensions for the Free-Threaded Build" +msgstr "" + +#: ../../howto/free-threading-extensions.rst:394 +msgid "" +"C API extensions need to be built specifically for the free-threaded build. " +"The wheels, shared libraries, and binaries are indicated by a ``t`` suffix." +msgstr "" + +#: ../../howto/free-threading-extensions.rst:397 +msgid "" +"`pypa/manylinux `_ supports the free-" +"threaded build, with the ``t`` suffix, such as ``python3.13t``." +msgstr "" + +#: ../../howto/free-threading-extensions.rst:399 +msgid "" +"`pypa/cibuildwheel `_ supports the " +"free-threaded build on Python 3.13 and 3.14. On Python 3.14, free-threaded " +"wheels will be built by default. On Python 3.13, you will need to set " +"`CIBW_ENABLE to cpython-freethreading `_." +msgstr "" + +#: ../../howto/free-threading-extensions.rst:405 +msgid "Limited C API and Stable ABI" +msgstr "" + +#: ../../howto/free-threading-extensions.rst:407 +msgid "" +"The free-threaded build does not currently support the :ref:`Limited C API " +"` or the stable ABI. If you use `setuptools `_ to build your extension and " +"currently set ``py_limited_api=True`` you can use ``py_limited_api=not " +"sysconfig.get_config_var(\"Py_GIL_DISABLED\")`` to opt out of the limited " +"API when building with the free-threaded build." +msgstr "" + +#: ../../howto/free-threading-extensions.rst:415 +msgid "" +"You will need to build separate wheels specifically for the free-threaded " +"build. If you currently use the stable ABI, you can continue to build a " +"single wheel for multiple non-free-threaded Python versions." +msgstr "" + +#: ../../howto/free-threading-extensions.rst:421 +msgid "Windows" +msgstr "Windows" + +#: ../../howto/free-threading-extensions.rst:423 +msgid "" +"Due to a limitation of the official Windows installer, you will need to " +"manually define ``Py_GIL_DISABLED=1`` when building extensions from source." +msgstr "" + +#: ../../howto/free-threading-extensions.rst:428 +msgid "" +"`Porting Extension Modules to Support Free-Threading `_: A community-maintained porting guide for " +"extension authors." +msgstr "" diff --git a/howto/free-threading-python.po b/howto/free-threading-python.po index 8ecf25ae55..0a0cd78328 100644 --- a/howto/free-threading-python.po +++ b/howto/free-threading-python.po @@ -1,261 +1,261 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# FIRST AUTHOR , YEAR. -# -#, fuzzy -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-12-03 00:14+0000\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \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" - -#: ../../howto/free-threading-python.rst:5 -msgid "Python support for free threading" -msgstr "Python 自由執行緒的支援" - -#: ../../howto/free-threading-python.rst:7 -msgid "" -"Starting with the 3.13 release, CPython has support for a build of Python " -"called :term:`free threading` where the :term:`global interpreter lock` " -"(GIL) is disabled. Free-threaded execution allows for full utilization of " -"the available processing power by running threads in parallel on available " -"CPU cores. While not all software will benefit from this automatically, " -"programs designed with threading in mind will run faster on multi-core " -"hardware." -msgstr "" - -#: ../../howto/free-threading-python.rst:14 -msgid "" -"Some third-party packages, in particular ones with an :term:`extension " -"module`, may not be ready for use in a free-threaded build, and will re-" -"enable the :term:`GIL`." -msgstr "" - -#: ../../howto/free-threading-python.rst:18 -msgid "" -"This document describes the implications of free threading for Python code. " -"See :ref:`freethreading-extensions-howto` for information on how to write C " -"extensions that support the free-threaded build." -msgstr "" - -#: ../../howto/free-threading-python.rst:24 -msgid "" -":pep:`703` – Making the Global Interpreter Lock Optional in CPython for an " -"overall description of free-threaded Python." -msgstr "" - -#: ../../howto/free-threading-python.rst:29 -msgid "Installation" -msgstr "安裝" - -#: ../../howto/free-threading-python.rst:31 -msgid "" -"Starting with Python 3.13, the official macOS and Windows installers " -"optionally support installing free-threaded Python binaries. The installers " -"are available at https://www.python.org/downloads/." -msgstr "" - -#: ../../howto/free-threading-python.rst:35 -msgid "" -"For information on other platforms, see the `Installing a Free-Threaded " -"Python `_, a " -"community-maintained installation guide for installing free-threaded Python." -msgstr "" - -#: ../../howto/free-threading-python.rst:39 -msgid "" -"When building CPython from source, the :option:`--disable-gil` configure " -"option should be used to build a free-threaded Python interpreter." -msgstr "" - -#: ../../howto/free-threading-python.rst:44 -msgid "Identifying free-threaded Python" -msgstr "" - -#: ../../howto/free-threading-python.rst:46 -msgid "" -"To check if the current interpreter supports free-threading, :option:`python " -"-VV <-V>` and :data:`sys.version` contain \"free-threading build\". The new :" -"func:`sys._is_gil_enabled` function can be used to check whether the GIL is " -"actually disabled in the running process." -msgstr "" - -#: ../../howto/free-threading-python.rst:51 -msgid "" -"The ``sysconfig.get_config_var(\"Py_GIL_DISABLED\")`` configuration variable " -"can be used to determine whether the build supports free threading. If the " -"variable is set to ``1``, then the build supports free threading. This is " -"the recommended mechanism for decisions related to the build configuration." -msgstr "" - -#: ../../howto/free-threading-python.rst:58 -msgid "The global interpreter lock in free-threaded Python" -msgstr "" - -#: ../../howto/free-threading-python.rst:60 -msgid "" -"Free-threaded builds of CPython support optionally running with the GIL " -"enabled at runtime using the environment variable :envvar:`PYTHON_GIL` or " -"the command-line option :option:`-X gil`." -msgstr "" - -#: ../../howto/free-threading-python.rst:64 -msgid "" -"The GIL may also automatically be enabled when importing a C-API extension " -"module that is not explicitly marked as supporting free threading. A " -"warning will be printed in this case." -msgstr "" - -#: ../../howto/free-threading-python.rst:68 -msgid "" -"In addition to individual package documentation, the following websites " -"track the status of popular packages support for free threading:" -msgstr "" - -#: ../../howto/free-threading-python.rst:71 -msgid "https://py-free-threading.github.io/tracking/" -msgstr "https://py-free-threading.github.io/tracking/" - -#: ../../howto/free-threading-python.rst:72 -msgid "https://hugovk.github.io/free-threaded-wheels/" -msgstr "https://hugovk.github.io/free-threaded-wheels/" - -#: ../../howto/free-threading-python.rst:76 -msgid "Thread safety" -msgstr "執行緒安全" - -#: ../../howto/free-threading-python.rst:78 -msgid "" -"The free-threaded build of CPython aims to provide similar thread-safety " -"behavior at the Python level to the default GIL-enabled build. Built-in " -"types like :class:`dict`, :class:`list`, and :class:`set` use internal locks " -"to protect against concurrent modifications in ways that behave similarly to " -"the GIL. However, Python has not historically guaranteed specific behavior " -"for concurrent modifications to these built-in types, so this should be " -"treated as a description of the current implementation, not a guarantee of " -"current or future behavior." -msgstr "" - -#: ../../howto/free-threading-python.rst:89 -msgid "" -"It's recommended to use the :class:`threading.Lock` or other synchronization " -"primitives instead of relying on the internal locks of built-in types, when " -"possible." -msgstr "" - -#: ../../howto/free-threading-python.rst:95 -msgid "Known limitations" -msgstr "已知限制" - -#: ../../howto/free-threading-python.rst:97 -msgid "" -"This section describes known limitations of the free-threaded CPython build." -msgstr "" - -#: ../../howto/free-threading-python.rst:100 -msgid "Immortalization" -msgstr "不滅化 (Immortalization)" - -#: ../../howto/free-threading-python.rst:102 -msgid "" -"In the free-threaded build, some objects are :term:`immortal`. Immortal " -"objects are not deallocated and have reference counts that are never " -"modified. This is done to avoid reference count contention that would " -"prevent efficient multi-threaded scaling." -msgstr "" - -#: ../../howto/free-threading-python.rst:107 -msgid "As of the 3.14 release, immortalization is limited to:" -msgstr "" - -#: ../../howto/free-threading-python.rst:109 -msgid "" -"Code constants: numeric literals, string literals, and tuple literals " -"composed of other constants." -msgstr "" - -#: ../../howto/free-threading-python.rst:111 -msgid "Strings interned by :func:`sys.intern`." -msgstr "" - -#: ../../howto/free-threading-python.rst:115 -msgid "Frame objects" -msgstr "" - -#: ../../howto/free-threading-python.rst:117 -msgid "" -"It is not safe to access :attr:`frame.f_locals` from a :ref:`frame ` object if that frame is currently executing in another thread, and " -"doing so may crash the interpreter." -msgstr "" - -#: ../../howto/free-threading-python.rst:123 -msgid "Iterators" -msgstr "疊代器" - -#: ../../howto/free-threading-python.rst:125 -msgid "" -"It is generally not thread-safe to access the same iterator object from " -"multiple threads concurrently, and threads may see duplicate or missing " -"elements." -msgstr "" - -#: ../../howto/free-threading-python.rst:131 -msgid "Single-threaded performance" -msgstr "單執行緒效能" - -#: ../../howto/free-threading-python.rst:133 -msgid "" -"The free-threaded build has additional overhead when executing Python code " -"compared to the default GIL-enabled build. The amount of overhead depends " -"on the workload and hardware. On the pyperformance benchmark suite, the " -"average overhead ranges from about 1% on macOS aarch64 to 8% on x86-64 Linux " -"systems." -msgstr "" - -#: ../../howto/free-threading-python.rst:141 -msgid "Behavioral changes" -msgstr "" - -#: ../../howto/free-threading-python.rst:143 -msgid "" -"This section describes CPython behavioural changes with the free-threaded " -"build." -msgstr "" - -#: ../../howto/free-threading-python.rst:148 -msgid "Context variables" -msgstr "" - -#: ../../howto/free-threading-python.rst:150 -msgid "" -"In the free-threaded build, the flag :data:`~sys.flags." -"thread_inherit_context` is set to true by default which causes threads " -"created with :class:`threading.Thread` to start with a copy of the :class:" -"`~contextvars.Context()` of the caller of :meth:`~threading.Thread.start`. " -"In the default GIL-enabled build, the flag defaults to false so threads " -"start with an empty :class:`~contextvars.Context()`." -msgstr "" - -#: ../../howto/free-threading-python.rst:160 -msgid "Warning filters" -msgstr "" - -#: ../../howto/free-threading-python.rst:162 -msgid "" -"In the free-threaded build, the flag :data:`~sys.flags." -"context_aware_warnings` is set to true by default. In the default GIL-" -"enabled build, the flag defaults to false. If the flag is true then the :" -"class:`warnings.catch_warnings` context manager uses a context variable for " -"warning filters. If the flag is false then :class:`~warnings." -"catch_warnings` modifies the global filters list, which is not thread-safe. " -"See the :mod:`warnings` module for more details." -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-12-03 00:14+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \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" + +#: ../../howto/free-threading-python.rst:5 +msgid "Python support for free threading" +msgstr "Python 自由執行緒的支援" + +#: ../../howto/free-threading-python.rst:7 +msgid "" +"Starting with the 3.13 release, CPython has support for a build of Python " +"called :term:`free threading` where the :term:`global interpreter lock` " +"(GIL) is disabled. Free-threaded execution allows for full utilization of " +"the available processing power by running threads in parallel on available " +"CPU cores. While not all software will benefit from this automatically, " +"programs designed with threading in mind will run faster on multi-core " +"hardware." +msgstr "" + +#: ../../howto/free-threading-python.rst:14 +msgid "" +"Some third-party packages, in particular ones with an :term:`extension " +"module`, may not be ready for use in a free-threaded build, and will re-" +"enable the :term:`GIL`." +msgstr "" + +#: ../../howto/free-threading-python.rst:18 +msgid "" +"This document describes the implications of free threading for Python code. " +"See :ref:`freethreading-extensions-howto` for information on how to write C " +"extensions that support the free-threaded build." +msgstr "" + +#: ../../howto/free-threading-python.rst:24 +msgid "" +":pep:`703` – Making the Global Interpreter Lock Optional in CPython for an " +"overall description of free-threaded Python." +msgstr "" + +#: ../../howto/free-threading-python.rst:29 +msgid "Installation" +msgstr "安裝" + +#: ../../howto/free-threading-python.rst:31 +msgid "" +"Starting with Python 3.13, the official macOS and Windows installers " +"optionally support installing free-threaded Python binaries. The installers " +"are available at https://www.python.org/downloads/." +msgstr "" + +#: ../../howto/free-threading-python.rst:35 +msgid "" +"For information on other platforms, see the `Installing a Free-Threaded " +"Python `_, a " +"community-maintained installation guide for installing free-threaded Python." +msgstr "" + +#: ../../howto/free-threading-python.rst:39 +msgid "" +"When building CPython from source, the :option:`--disable-gil` configure " +"option should be used to build a free-threaded Python interpreter." +msgstr "" + +#: ../../howto/free-threading-python.rst:44 +msgid "Identifying free-threaded Python" +msgstr "" + +#: ../../howto/free-threading-python.rst:46 +msgid "" +"To check if the current interpreter supports free-threading, :option:`python " +"-VV <-V>` and :data:`sys.version` contain \"free-threading build\". The new :" +"func:`sys._is_gil_enabled` function can be used to check whether the GIL is " +"actually disabled in the running process." +msgstr "" + +#: ../../howto/free-threading-python.rst:51 +msgid "" +"The ``sysconfig.get_config_var(\"Py_GIL_DISABLED\")`` configuration variable " +"can be used to determine whether the build supports free threading. If the " +"variable is set to ``1``, then the build supports free threading. This is " +"the recommended mechanism for decisions related to the build configuration." +msgstr "" + +#: ../../howto/free-threading-python.rst:58 +msgid "The global interpreter lock in free-threaded Python" +msgstr "" + +#: ../../howto/free-threading-python.rst:60 +msgid "" +"Free-threaded builds of CPython support optionally running with the GIL " +"enabled at runtime using the environment variable :envvar:`PYTHON_GIL` or " +"the command-line option :option:`-X gil`." +msgstr "" + +#: ../../howto/free-threading-python.rst:64 +msgid "" +"The GIL may also automatically be enabled when importing a C-API extension " +"module that is not explicitly marked as supporting free threading. A " +"warning will be printed in this case." +msgstr "" + +#: ../../howto/free-threading-python.rst:68 +msgid "" +"In addition to individual package documentation, the following websites " +"track the status of popular packages support for free threading:" +msgstr "" + +#: ../../howto/free-threading-python.rst:71 +msgid "https://py-free-threading.github.io/tracking/" +msgstr "https://py-free-threading.github.io/tracking/" + +#: ../../howto/free-threading-python.rst:72 +msgid "https://hugovk.github.io/free-threaded-wheels/" +msgstr "https://hugovk.github.io/free-threaded-wheels/" + +#: ../../howto/free-threading-python.rst:76 +msgid "Thread safety" +msgstr "執行緒安全" + +#: ../../howto/free-threading-python.rst:78 +msgid "" +"The free-threaded build of CPython aims to provide similar thread-safety " +"behavior at the Python level to the default GIL-enabled build. Built-in " +"types like :class:`dict`, :class:`list`, and :class:`set` use internal locks " +"to protect against concurrent modifications in ways that behave similarly to " +"the GIL. However, Python has not historically guaranteed specific behavior " +"for concurrent modifications to these built-in types, so this should be " +"treated as a description of the current implementation, not a guarantee of " +"current or future behavior." +msgstr "" + +#: ../../howto/free-threading-python.rst:89 +msgid "" +"It's recommended to use the :class:`threading.Lock` or other synchronization " +"primitives instead of relying on the internal locks of built-in types, when " +"possible." +msgstr "" + +#: ../../howto/free-threading-python.rst:95 +msgid "Known limitations" +msgstr "已知限制" + +#: ../../howto/free-threading-python.rst:97 +msgid "" +"This section describes known limitations of the free-threaded CPython build." +msgstr "" + +#: ../../howto/free-threading-python.rst:100 +msgid "Immortalization" +msgstr "不滅化 (Immortalization)" + +#: ../../howto/free-threading-python.rst:102 +msgid "" +"In the free-threaded build, some objects are :term:`immortal`. Immortal " +"objects are not deallocated and have reference counts that are never " +"modified. This is done to avoid reference count contention that would " +"prevent efficient multi-threaded scaling." +msgstr "" + +#: ../../howto/free-threading-python.rst:107 +msgid "As of the 3.14 release, immortalization is limited to:" +msgstr "" + +#: ../../howto/free-threading-python.rst:109 +msgid "" +"Code constants: numeric literals, string literals, and tuple literals " +"composed of other constants." +msgstr "" + +#: ../../howto/free-threading-python.rst:111 +msgid "Strings interned by :func:`sys.intern`." +msgstr "" + +#: ../../howto/free-threading-python.rst:115 +msgid "Frame objects" +msgstr "" + +#: ../../howto/free-threading-python.rst:117 +msgid "" +"It is not safe to access :attr:`frame.f_locals` from a :ref:`frame ` object if that frame is currently executing in another thread, and " +"doing so may crash the interpreter." +msgstr "" + +#: ../../howto/free-threading-python.rst:123 +msgid "Iterators" +msgstr "疊代器" + +#: ../../howto/free-threading-python.rst:125 +msgid "" +"It is generally not thread-safe to access the same iterator object from " +"multiple threads concurrently, and threads may see duplicate or missing " +"elements." +msgstr "" + +#: ../../howto/free-threading-python.rst:131 +msgid "Single-threaded performance" +msgstr "單執行緒效能" + +#: ../../howto/free-threading-python.rst:133 +msgid "" +"The free-threaded build has additional overhead when executing Python code " +"compared to the default GIL-enabled build. The amount of overhead depends " +"on the workload and hardware. On the pyperformance benchmark suite, the " +"average overhead ranges from about 1% on macOS aarch64 to 8% on x86-64 Linux " +"systems." +msgstr "" + +#: ../../howto/free-threading-python.rst:141 +msgid "Behavioral changes" +msgstr "" + +#: ../../howto/free-threading-python.rst:143 +msgid "" +"This section describes CPython behavioural changes with the free-threaded " +"build." +msgstr "" + +#: ../../howto/free-threading-python.rst:148 +msgid "Context variables" +msgstr "" + +#: ../../howto/free-threading-python.rst:150 +msgid "" +"In the free-threaded build, the flag :data:`~sys.flags." +"thread_inherit_context` is set to true by default which causes threads " +"created with :class:`threading.Thread` to start with a copy of the :class:" +"`~contextvars.Context()` of the caller of :meth:`~threading.Thread.start`. " +"In the default GIL-enabled build, the flag defaults to false so threads " +"start with an empty :class:`~contextvars.Context()`." +msgstr "" + +#: ../../howto/free-threading-python.rst:160 +msgid "Warning filters" +msgstr "" + +#: ../../howto/free-threading-python.rst:162 +msgid "" +"In the free-threaded build, the flag :data:`~sys.flags." +"context_aware_warnings` is set to true by default. In the default GIL-" +"enabled build, the flag defaults to false. If the flag is true then the :" +"class:`warnings.catch_warnings` context manager uses a context variable for " +"warning filters. If the flag is false then :class:`~warnings." +"catch_warnings` modifies the global filters list, which is not thread-safe. " +"See the :mod:`warnings` module for more details." +msgstr "" diff --git a/howto/functional.po b/howto/functional.po index 8e186ab544..3b2bac03c3 100644 --- a/howto/functional.po +++ b/howto/functional.po @@ -1,2054 +1,2054 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Leon H., 2017 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-30 00:16+0000\n" -"PO-Revision-Date: 2018-05-23 14:36+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" - -#: ../../howto/functional.rst:5 -msgid "Functional Programming HOWTO" -msgstr "函式程式設計 HOWTO" - -#: ../../howto/functional.rst:0 -msgid "Author" -msgstr "作者" - -#: ../../howto/functional.rst:7 -msgid "\\A. M. Kuchling" -msgstr "\\A. M. Kuchling" - -#: ../../howto/functional.rst:0 -msgid "Release" -msgstr "發佈版本" - -#: ../../howto/functional.rst:8 -msgid "0.32" -msgstr "0.32" - -#: ../../howto/functional.rst:10 -msgid "" -"In this document, we'll take a tour of Python's features suitable for " -"implementing programs in a functional style. After an introduction to the " -"concepts of functional programming, we'll look at language features such as :" -"term:`iterator`\\s and :term:`generator`\\s and relevant library modules " -"such as :mod:`itertools` and :mod:`functools`." -msgstr "" - -#: ../../howto/functional.rst:18 -msgid "Introduction" -msgstr "簡介" - -#: ../../howto/functional.rst:20 -msgid "" -"This section explains the basic concept of functional programming; if you're " -"just interested in learning about Python language features, skip to the next " -"section on :ref:`functional-howto-iterators`." -msgstr "" - -#: ../../howto/functional.rst:24 -msgid "" -"Programming languages support decomposing problems in several different ways:" -msgstr "" - -#: ../../howto/functional.rst:26 -msgid "" -"Most programming languages are **procedural**: programs are lists of " -"instructions that tell the computer what to do with the program's input. C, " -"Pascal, and even Unix shells are procedural languages." -msgstr "" - -#: ../../howto/functional.rst:30 -msgid "" -"In **declarative** languages, you write a specification that describes the " -"problem to be solved, and the language implementation figures out how to " -"perform the computation efficiently. SQL is the declarative language you're " -"most likely to be familiar with; a SQL query describes the data set you want " -"to retrieve, and the SQL engine decides whether to scan tables or use " -"indexes, which subclauses should be performed first, etc." -msgstr "" - -#: ../../howto/functional.rst:37 -msgid "" -"**Object-oriented** programs manipulate collections of objects. Objects " -"have internal state and support methods that query or modify this internal " -"state in some way. Smalltalk and Java are object-oriented languages. C++ " -"and Python are languages that support object-oriented programming, but don't " -"force the use of object-oriented features." -msgstr "" - -#: ../../howto/functional.rst:43 -msgid "" -"**Functional** programming decomposes a problem into a set of functions. " -"Ideally, functions only take inputs and produce outputs, and don't have any " -"internal state that affects the output produced for a given input. Well-" -"known functional languages include the ML family (Standard ML, OCaml, and " -"other variants) and Haskell." -msgstr "" - -#: ../../howto/functional.rst:49 -msgid "" -"The designers of some computer languages choose to emphasize one particular " -"approach to programming. This often makes it difficult to write programs " -"that use a different approach. Other languages are multi-paradigm languages " -"that support several different approaches. Lisp, C++, and Python are multi-" -"paradigm; you can write programs or libraries that are largely procedural, " -"object-oriented, or functional in all of these languages. In a large " -"program, different sections might be written using different approaches; the " -"GUI might be object-oriented while the processing logic is procedural or " -"functional, for example." -msgstr "" - -#: ../../howto/functional.rst:60 -msgid "" -"In a functional program, input flows through a set of functions. Each " -"function operates on its input and produces some output. Functional style " -"discourages functions with side effects that modify internal state or make " -"other changes that aren't visible in the function's return value. Functions " -"that have no side effects at all are called **purely functional**. Avoiding " -"side effects means not using data structures that get updated as a program " -"runs; every function's output must only depend on its input." -msgstr "" - -#: ../../howto/functional.rst:68 -msgid "" -"Some languages are very strict about purity and don't even have assignment " -"statements such as ``a=3`` or ``c = a + b``, but it's difficult to avoid all " -"side effects, such as printing to the screen or writing to a disk file. " -"Another example is a call to the :func:`print` or :func:`time.sleep` " -"function, neither of which returns a useful value. Both are called only for " -"their side effects of sending some text to the screen or pausing execution " -"for a second." -msgstr "" - -#: ../../howto/functional.rst:75 -msgid "" -"Python programs written in functional style usually won't go to the extreme " -"of avoiding all I/O or all assignments; instead, they'll provide a " -"functional-appearing interface but will use non-functional features " -"internally. For example, the implementation of a function will still use " -"assignments to local variables, but won't modify global variables or have " -"other side effects." -msgstr "" - -#: ../../howto/functional.rst:81 -msgid "" -"Functional programming can be considered the opposite of object-oriented " -"programming. Objects are little capsules containing some internal state " -"along with a collection of method calls that let you modify this state, and " -"programs consist of making the right set of state changes. Functional " -"programming wants to avoid state changes as much as possible and works with " -"data flowing between functions. In Python you might combine the two " -"approaches by writing functions that take and return instances representing " -"objects in your application (e-mail messages, transactions, etc.)." -msgstr "" - -#: ../../howto/functional.rst:90 -msgid "" -"Functional design may seem like an odd constraint to work under. Why should " -"you avoid objects and side effects? There are theoretical and practical " -"advantages to the functional style:" -msgstr "" - -#: ../../howto/functional.rst:94 -msgid "Formal provability." -msgstr "形式可證明性 (Formal provability)。" - -#: ../../howto/functional.rst:95 -msgid "Modularity." -msgstr "模組化 (Modularity)。" - -#: ../../howto/functional.rst:96 -msgid "Composability." -msgstr "可組合性 (Composability)。" - -#: ../../howto/functional.rst:97 -msgid "Ease of debugging and testing." -msgstr "容易除錯與測試。" - -#: ../../howto/functional.rst:101 -msgid "Formal provability" -msgstr "形式可證明性" - -#: ../../howto/functional.rst:103 -msgid "" -"A theoretical benefit is that it's easier to construct a mathematical proof " -"that a functional program is correct." -msgstr "" - -#: ../../howto/functional.rst:106 -msgid "" -"For a long time researchers have been interested in finding ways to " -"mathematically prove programs correct. This is different from testing a " -"program on numerous inputs and concluding that its output is usually " -"correct, or reading a program's source code and concluding that the code " -"looks right; the goal is instead a rigorous proof that a program produces " -"the right result for all possible inputs." -msgstr "" - -#: ../../howto/functional.rst:113 -msgid "" -"The technique used to prove programs correct is to write down " -"**invariants**, properties of the input data and of the program's variables " -"that are always true. For each line of code, you then show that if " -"invariants X and Y are true **before** the line is executed, the slightly " -"different invariants X' and Y' are true **after** the line is executed. " -"This continues until you reach the end of the program, at which point the " -"invariants should match the desired conditions on the program's output." -msgstr "" - -#: ../../howto/functional.rst:121 -msgid "" -"Functional programming's avoidance of assignments arose because assignments " -"are difficult to handle with this technique; assignments can break " -"invariants that were true before the assignment without producing any new " -"invariants that can be propagated onward." -msgstr "" - -#: ../../howto/functional.rst:126 -msgid "" -"Unfortunately, proving programs correct is largely impractical and not " -"relevant to Python software. Even trivial programs require proofs that are " -"several pages long; the proof of correctness for a moderately complicated " -"program would be enormous, and few or none of the programs you use daily " -"(the Python interpreter, your XML parser, your web browser) could be proven " -"correct. Even if you wrote down or generated a proof, there would then be " -"the question of verifying the proof; maybe there's an error in it, and you " -"wrongly believe you've proved the program correct." -msgstr "" - -#: ../../howto/functional.rst:137 -msgid "Modularity" -msgstr "模組化" - -#: ../../howto/functional.rst:139 -msgid "" -"A more practical benefit of functional programming is that it forces you to " -"break apart your problem into small pieces. Programs are more modular as a " -"result. It's easier to specify and write a small function that does one " -"thing than a large function that performs a complicated transformation. " -"Small functions are also easier to read and to check for errors." -msgstr "" - -#: ../../howto/functional.rst:147 -msgid "Ease of debugging and testing" -msgstr "容易除錯與測試" - -#: ../../howto/functional.rst:149 -msgid "Testing and debugging a functional-style program is easier." -msgstr "" - -#: ../../howto/functional.rst:151 -msgid "" -"Debugging is simplified because functions are generally small and clearly " -"specified. When a program doesn't work, each function is an interface point " -"where you can check that the data are correct. You can look at the " -"intermediate inputs and outputs to quickly isolate the function that's " -"responsible for a bug." -msgstr "" - -#: ../../howto/functional.rst:156 -msgid "" -"Testing is easier because each function is a potential subject for a unit " -"test. Functions don't depend on system state that needs to be replicated " -"before running a test; instead you only have to synthesize the right input " -"and then check that the output matches expectations." -msgstr "" - -#: ../../howto/functional.rst:163 -msgid "Composability" -msgstr "可組合性" - -#: ../../howto/functional.rst:165 -msgid "" -"As you work on a functional-style program, you'll write a number of " -"functions with varying inputs and outputs. Some of these functions will be " -"unavoidably specialized to a particular application, but others will be " -"useful in a wide variety of programs. For example, a function that takes a " -"directory path and returns all the XML files in the directory, or a function " -"that takes a filename and returns its contents, can be applied to many " -"different situations." -msgstr "" - -#: ../../howto/functional.rst:172 -msgid "" -"Over time you'll form a personal library of utilities. Often you'll " -"assemble new programs by arranging existing functions in a new configuration " -"and writing a few functions specialized for the current task." -msgstr "" - -#: ../../howto/functional.rst:180 -msgid "Iterators" -msgstr "疊代器" - -#: ../../howto/functional.rst:182 -msgid "" -"I'll start by looking at a Python language feature that's an important " -"foundation for writing functional-style programs: iterators." -msgstr "" - -#: ../../howto/functional.rst:185 -msgid "" -"An iterator is an object representing a stream of data; this object returns " -"the data one element at a time. A Python iterator must support a method " -"called :meth:`~iterator.__next__` that takes no arguments and always returns " -"the next element of the stream. If there are no more elements in the " -"stream, :meth:`~iterator.__next__` must raise the :exc:`StopIteration` " -"exception. Iterators don't have to be finite, though; it's perfectly " -"reasonable to write an iterator that produces an infinite stream of data." -msgstr "" - -#: ../../howto/functional.rst:193 -msgid "" -"The built-in :func:`iter` function takes an arbitrary object and tries to " -"return an iterator that will return the object's contents or elements, " -"raising :exc:`TypeError` if the object doesn't support iteration. Several " -"of Python's built-in data types support iteration, the most common being " -"lists and dictionaries. An object is called :term:`iterable` if you can get " -"an iterator for it." -msgstr "" - -#: ../../howto/functional.rst:200 -msgid "You can experiment with the iteration interface manually:" -msgstr "" - -#: ../../howto/functional.rst:218 -msgid "" -"Python expects iterable objects in several different contexts, the most " -"important being the :keyword:`for` statement. In the statement ``for X in " -"Y``, Y must be an iterator or some object for which :func:`iter` can create " -"an iterator. These two statements are equivalent::" -msgstr "" - -#: ../../howto/functional.rst:224 -msgid "" -"for i in iter(obj):\n" -" print(i)\n" -"\n" -"for i in obj:\n" -" print(i)" -msgstr "" -"for i in iter(obj):\n" -" print(i)\n" -"\n" -"for i in obj:\n" -" print(i)" - -#: ../../howto/functional.rst:230 -msgid "" -"Iterators can be materialized as lists or tuples by using the :func:`list` " -"or :func:`tuple` constructor functions:" -msgstr "" - -#: ../../howto/functional.rst:239 -msgid "" -"Sequence unpacking also supports iterators: if you know an iterator will " -"return N elements, you can unpack them into an N-tuple:" -msgstr "" - -#: ../../howto/functional.rst:248 -msgid "" -"Built-in functions such as :func:`max` and :func:`min` can take a single " -"iterator argument and will return the largest or smallest element. The " -"``\"in\"`` and ``\"not in\"`` operators also support iterators: ``X in " -"iterator`` is true if X is found in the stream returned by the iterator. " -"You'll run into obvious problems if the iterator is infinite; :func:`max`, :" -"func:`min` will never return, and if the element X never appears in the " -"stream, the ``\"in\"`` and ``\"not in\"`` operators won't return either." -msgstr "" - -#: ../../howto/functional.rst:256 -msgid "" -"Note that you can only go forward in an iterator; there's no way to get the " -"previous element, reset the iterator, or make a copy of it. Iterator " -"objects can optionally provide these additional capabilities, but the " -"iterator protocol only specifies the :meth:`~iterator.__next__` method. " -"Functions may therefore consume all of the iterator's output, and if you " -"need to do something different with the same stream, you'll have to create a " -"new iterator." -msgstr "" - -#: ../../howto/functional.rst:266 -msgid "Data Types That Support Iterators" -msgstr "" - -#: ../../howto/functional.rst:268 -msgid "" -"We've already seen how lists and tuples support iterators. In fact, any " -"Python sequence type, such as strings, will automatically support creation " -"of an iterator." -msgstr "" - -#: ../../howto/functional.rst:272 -msgid "" -"Calling :func:`iter` on a dictionary returns an iterator that will loop over " -"the dictionary's keys::" -msgstr "" - -#: ../../howto/functional.rst:275 -msgid "" -">>> m = {'Jan': 1, 'Feb': 2, 'Mar': 3, 'Apr': 4, 'May': 5, 'Jun': 6,\n" -"... 'Jul': 7, 'Aug': 8, 'Sep': 9, 'Oct': 10, 'Nov': 11, 'Dec': 12}\n" -">>> for key in m:\n" -"... print(key, m[key])\n" -"Jan 1\n" -"Feb 2\n" -"Mar 3\n" -"Apr 4\n" -"May 5\n" -"Jun 6\n" -"Jul 7\n" -"Aug 8\n" -"Sep 9\n" -"Oct 10\n" -"Nov 11\n" -"Dec 12" -msgstr "" -">>> m = {'Jan': 1, 'Feb': 2, 'Mar': 3, 'Apr': 4, 'May': 5, 'Jun': 6,\n" -"... 'Jul': 7, 'Aug': 8, 'Sep': 9, 'Oct': 10, 'Nov': 11, 'Dec': 12}\n" -">>> for key in m:\n" -"... print(key, m[key])\n" -"Jan 1\n" -"Feb 2\n" -"Mar 3\n" -"Apr 4\n" -"May 5\n" -"Jun 6\n" -"Jul 7\n" -"Aug 8\n" -"Sep 9\n" -"Oct 10\n" -"Nov 11\n" -"Dec 12" - -#: ../../howto/functional.rst:292 -msgid "" -"Note that starting with Python 3.7, dictionary iteration order is guaranteed " -"to be the same as the insertion order. In earlier versions, the behaviour " -"was unspecified and could vary between implementations." -msgstr "" - -#: ../../howto/functional.rst:296 -msgid "" -"Applying :func:`iter` to a dictionary always loops over the keys, but " -"dictionaries have methods that return other iterators. If you want to " -"iterate over values or key/value pairs, you can explicitly call the :meth:" -"`~dict.values` or :meth:`~dict.items` methods to get an appropriate iterator." -msgstr "" - -#: ../../howto/functional.rst:302 -msgid "" -"The :func:`dict` constructor can accept an iterator that returns a finite " -"stream of ``(key, value)`` tuples:" -msgstr "" - -#: ../../howto/functional.rst:309 -msgid "" -"Files also support iteration by calling the :meth:`~io.TextIOBase.readline` " -"method until there are no more lines in the file. This means you can read " -"each line of a file like this::" -msgstr "" - -#: ../../howto/functional.rst:313 -msgid "" -"for line in file:\n" -" # do something for each line\n" -" ..." -msgstr "" - -#: ../../howto/functional.rst:317 -msgid "" -"Sets can take their contents from an iterable and let you iterate over the " -"set's elements::" -msgstr "" - -#: ../../howto/functional.rst:320 -msgid "" -">>> S = {2, 3, 5, 7, 11, 13}\n" -">>> for i in S:\n" -"... print(i)\n" -"2\n" -"3\n" -"5\n" -"7\n" -"11\n" -"13" -msgstr "" -">>> S = {2, 3, 5, 7, 11, 13}\n" -">>> for i in S:\n" -"... print(i)\n" -"2\n" -"3\n" -"5\n" -"7\n" -"11\n" -"13" - -#: ../../howto/functional.rst:333 -msgid "Generator expressions and list comprehensions" -msgstr "產生器運算式與串列綜合運算式" - -#: ../../howto/functional.rst:335 -msgid "" -"Two common operations on an iterator's output are 1) performing some " -"operation for every element, 2) selecting a subset of elements that meet " -"some condition. For example, given a list of strings, you might want to " -"strip off trailing whitespace from each line or extract all the strings " -"containing a given substring." -msgstr "" - -#: ../../howto/functional.rst:341 -msgid "" -"List comprehensions and generator expressions (short form: \"listcomps\" and " -"\"genexps\") are a concise notation for such operations, borrowed from the " -"functional programming language Haskell (https://www.haskell.org/). You can " -"strip all the whitespace from a stream of strings with the following code::" -msgstr "" - -#: ../../howto/functional.rst:346 -msgid "" -">>> line_list = [' line 1\\n', 'line 2 \\n', ' \\n', '']\n" -"\n" -">>> # Generator expression -- returns iterator\n" -">>> stripped_iter = (line.strip() for line in line_list)\n" -"\n" -">>> # List comprehension -- returns list\n" -">>> stripped_list = [line.strip() for line in line_list]" -msgstr "" -">>> line_list = [' line 1\\n', 'line 2 \\n', ' \\n', '']\n" -"\n" -">>> # 產生器運算式 -- 回傳疊代器\n" -">>> stripped_iter = (line.strip() for line in line_list)\n" -"\n" -">>> # 串列綜合運算式 -- 回傳串列\n" -">>> stripped_list = [line.strip() for line in line_list]" - -#: ../../howto/functional.rst:354 -msgid "" -"You can select only certain elements by adding an ``\"if\"`` condition::" -msgstr "" - -#: ../../howto/functional.rst:356 -msgid "" -">>> stripped_list = [line.strip() for line in line_list\n" -"... if line != \"\"]" -msgstr "" -">>> stripped_list = [line.strip() for line in line_list\n" -"... if line != \"\"]" - -#: ../../howto/functional.rst:359 -msgid "" -"With a list comprehension, you get back a Python list; ``stripped_list`` is " -"a list containing the resulting lines, not an iterator. Generator " -"expressions return an iterator that computes the values as necessary, not " -"needing to materialize all the values at once. This means that list " -"comprehensions aren't useful if you're working with iterators that return an " -"infinite stream or a very large amount of data. Generator expressions are " -"preferable in these situations." -msgstr "" - -#: ../../howto/functional.rst:366 -msgid "" -"Generator expressions are surrounded by parentheses (\"()\") and list " -"comprehensions are surrounded by square brackets (\"[]\"). Generator " -"expressions have the form::" -msgstr "" - -#: ../../howto/functional.rst:370 -msgid "" -"( expression for expr in sequence1\n" -" if condition1\n" -" for expr2 in sequence2\n" -" if condition2\n" -" for expr3 in sequence3\n" -" ...\n" -" if condition3\n" -" for exprN in sequenceN\n" -" if conditionN )" -msgstr "" -"( expression for expr in sequence1\n" -" if condition1\n" -" for expr2 in sequence2\n" -" if condition2\n" -" for expr3 in sequence3\n" -" ...\n" -" if condition3\n" -" for exprN in sequenceN\n" -" if conditionN )" - -#: ../../howto/functional.rst:380 -msgid "" -"Again, for a list comprehension only the outside brackets are different " -"(square brackets instead of parentheses)." -msgstr "" - -#: ../../howto/functional.rst:383 -msgid "" -"The elements of the generated output will be the successive values of " -"``expression``. The ``if`` clauses are all optional; if present, " -"``expression`` is only evaluated and added to the result when ``condition`` " -"is true." -msgstr "" - -#: ../../howto/functional.rst:387 -msgid "" -"Generator expressions always have to be written inside parentheses, but the " -"parentheses signalling a function call also count. If you want to create an " -"iterator that will be immediately passed to a function you can write::" -msgstr "" - -#: ../../howto/functional.rst:391 -msgid "obj_total = sum(obj.count for obj in list_all_objects())" -msgstr "obj_total = sum(obj.count for obj in list_all_objects())" - -#: ../../howto/functional.rst:393 -msgid "" -"The ``for...in`` clauses contain the sequences to be iterated over. The " -"sequences do not have to be the same length, because they are iterated over " -"from left to right, **not** in parallel. For each element in ``sequence1``, " -"``sequence2`` is looped over from the beginning. ``sequence3`` is then " -"looped over for each resulting pair of elements from ``sequence1`` and " -"``sequence2``." -msgstr "" - -#: ../../howto/functional.rst:399 -msgid "" -"To put it another way, a list comprehension or generator expression is " -"equivalent to the following Python code::" -msgstr "" - -#: ../../howto/functional.rst:402 -msgid "" -"for expr1 in sequence1:\n" -" if not (condition1):\n" -" continue # Skip this element\n" -" for expr2 in sequence2:\n" -" if not (condition2):\n" -" continue # Skip this element\n" -" ...\n" -" for exprN in sequenceN:\n" -" if not (conditionN):\n" -" continue # Skip this element\n" -"\n" -" # Output the value of\n" -" # the expression." -msgstr "" - -#: ../../howto/functional.rst:416 -msgid "" -"This means that when there are multiple ``for...in`` clauses but no ``if`` " -"clauses, the length of the resulting output will be equal to the product of " -"the lengths of all the sequences. If you have two lists of length 3, the " -"output list is 9 elements long:" -msgstr "" - -#: ../../howto/functional.rst:428 -msgid "" -"To avoid introducing an ambiguity into Python's grammar, if ``expression`` " -"is creating a tuple, it must be surrounded with parentheses. The first list " -"comprehension below is a syntax error, while the second one is correct::" -msgstr "" - -#: ../../howto/functional.rst:432 -msgid "" -"# Syntax error\n" -"[x, y for x in seq1 for y in seq2]\n" -"# Correct\n" -"[(x, y) for x in seq1 for y in seq2]" -msgstr "" -"# 語法錯誤\n" -"[x, y for x in seq1 for y in seq2]\n" -"# 正確\n" -"[(x, y) for x in seq1 for y in seq2]" - -#: ../../howto/functional.rst:439 -msgid "Generators" -msgstr "產生器" - -#: ../../howto/functional.rst:441 -msgid "" -"Generators are a special class of functions that simplify the task of " -"writing iterators. Regular functions compute a value and return it, but " -"generators return an iterator that returns a stream of values." -msgstr "" - -#: ../../howto/functional.rst:445 -msgid "" -"You're doubtless familiar with how regular function calls work in Python or " -"C. When you call a function, it gets a private namespace where its local " -"variables are created. When the function reaches a ``return`` statement, " -"the local variables are destroyed and the value is returned to the caller. " -"A later call to the same function creates a new private namespace and a " -"fresh set of local variables. But, what if the local variables weren't " -"thrown away on exiting a function? What if you could later resume the " -"function where it left off? This is what generators provide; they can be " -"thought of as resumable functions." -msgstr "" - -#: ../../howto/functional.rst:454 -msgid "Here's the simplest example of a generator function:" -msgstr "以下是最簡單的產生器函式範例：" - -#: ../../howto/functional.rst:460 -msgid "" -"Any function containing a :keyword:`yield` keyword is a generator function; " -"this is detected by Python's :term:`bytecode` compiler which compiles the " -"function specially as a result." -msgstr "" - -#: ../../howto/functional.rst:464 -msgid "" -"When you call a generator function, it doesn't return a single value; " -"instead it returns a generator object that supports the iterator protocol. " -"On executing the ``yield`` expression, the generator outputs the value of " -"``i``, similar to a ``return`` statement. The big difference between " -"``yield`` and a ``return`` statement is that on reaching a ``yield`` the " -"generator's state of execution is suspended and local variables are " -"preserved. On the next call to the generator's :meth:`~generator.__next__` " -"method, the function will resume executing." -msgstr "" - -#: ../../howto/functional.rst:473 -msgid "Here's a sample usage of the ``generate_ints()`` generator:" -msgstr "以下是 ``generate_ints()`` 產生器的使用範例：" - -#: ../../howto/functional.rst:490 -msgid "" -"You could equally write ``for i in generate_ints(5)``, or ``a, b, c = " -"generate_ints(3)``." -msgstr "" - -#: ../../howto/functional.rst:493 -msgid "" -"Inside a generator function, ``return value`` causes " -"``StopIteration(value)`` to be raised from the :meth:`~generator.__next__` " -"method. Once this happens, or the bottom of the function is reached, the " -"procession of values ends and the generator cannot yield any further values." -msgstr "" - -#: ../../howto/functional.rst:498 -msgid "" -"You could achieve the effect of generators manually by writing your own " -"class and storing all the local variables of the generator as instance " -"variables. For example, returning a list of integers could be done by " -"setting ``self.count`` to 0, and having the :meth:`~iterator.__next__` " -"method increment ``self.count`` and return it. However, for a moderately " -"complicated generator, writing a corresponding class can be much messier." -msgstr "" - -#: ../../howto/functional.rst:506 -msgid "" -"The test suite included with Python's library, :source:`Lib/test/" -"test_generators.py`, contains a number of more interesting examples. Here's " -"one generator that implements an in-order traversal of a tree using " -"generators recursively. ::" -msgstr "" - -#: ../../howto/functional.rst:511 -msgid "" -"# A recursive generator that generates Tree leaves in in-order.\n" -"def inorder(t):\n" -" if t:\n" -" for x in inorder(t.left):\n" -" yield x\n" -"\n" -" yield t.label\n" -"\n" -" for x in inorder(t.right):\n" -" yield x" -msgstr "" - -#: ../../howto/functional.rst:522 -msgid "" -"Two other examples in ``test_generators.py`` produce solutions for the N-" -"Queens problem (placing N queens on an NxN chess board so that no queen " -"threatens another) and the Knight's Tour (finding a route that takes a " -"knight to every square of an NxN chessboard without visiting any square " -"twice)." -msgstr "" - -#: ../../howto/functional.rst:530 -msgid "Passing values into a generator" -msgstr "" - -#: ../../howto/functional.rst:532 -msgid "" -"In Python 2.4 and earlier, generators only produced output. Once a " -"generator's code was invoked to create an iterator, there was no way to pass " -"any new information into the function when its execution is resumed. You " -"could hack together this ability by making the generator look at a global " -"variable or by passing in some mutable object that callers then modify, but " -"these approaches are messy." -msgstr "" - -#: ../../howto/functional.rst:539 -msgid "" -"In Python 2.5 there's a simple way to pass values into a generator. :keyword:" -"`yield` became an expression, returning a value that can be assigned to a " -"variable or otherwise operated on::" -msgstr "" - -#: ../../howto/functional.rst:543 -msgid "val = (yield i)" -msgstr "val = (yield i)" - -#: ../../howto/functional.rst:545 -msgid "" -"I recommend that you **always** put parentheses around a ``yield`` " -"expression when you're doing something with the returned value, as in the " -"above example. The parentheses aren't always necessary, but it's easier to " -"always add them instead of having to remember when they're needed." -msgstr "" - -#: ../../howto/functional.rst:550 -msgid "" -"(:pep:`342` explains the exact rules, which are that a ``yield``-expression " -"must always be parenthesized except when it occurs at the top-level " -"expression on the right-hand side of an assignment. This means you can " -"write ``val = yield i`` but have to use parentheses when there's an " -"operation, as in ``val = (yield i) + 12``.)" -msgstr "" - -#: ../../howto/functional.rst:556 -msgid "" -"Values are sent into a generator by calling its :meth:`send(value) " -"` method. This method resumes the generator's code and the " -"``yield`` expression returns the specified value. If the regular :meth:" -"`~generator.__next__` method is called, the ``yield`` returns ``None``." -msgstr "" - -#: ../../howto/functional.rst:561 -msgid "" -"Here's a simple counter that increments by 1 and allows changing the value " -"of the internal counter." -msgstr "" - -#: ../../howto/functional.rst:564 -msgid "" -"def counter(maximum):\n" -" i = 0\n" -" while i < maximum:\n" -" val = (yield i)\n" -" # If value provided, change counter\n" -" if val is not None:\n" -" i = val\n" -" else:\n" -" i += 1" -msgstr "" -"def counter(maximum):\n" -" i = 0\n" -" while i < maximum:\n" -" val = (yield i)\n" -" # 如有提供值則改變計數器\n" -" if val is not None:\n" -" i = val\n" -" else:\n" -" i += 1" - -#: ../../howto/functional.rst:576 -msgid "And here's an example of changing the counter:" -msgstr "" - -#: ../../howto/functional.rst:593 -msgid "" -"Because ``yield`` will often be returning ``None``, you should always check " -"for this case. Don't just use its value in expressions unless you're sure " -"that the :meth:`~generator.send` method will be the only method used to " -"resume your generator function." -msgstr "" - -#: ../../howto/functional.rst:598 -msgid "" -"In addition to :meth:`~generator.send`, there are two other methods on " -"generators:" -msgstr "" - -#: ../../howto/functional.rst:601 -msgid "" -":meth:`throw(value) ` is used to raise an exception inside " -"the generator; the exception is raised by the ``yield`` expression where the " -"generator's execution is paused." -msgstr "" - -#: ../../howto/functional.rst:605 -msgid "" -":meth:`~generator.close` sends a :exc:`GeneratorExit` exception to the " -"generator to terminate the iteration. On receiving this exception, the " -"generator's code must either raise :exc:`GeneratorExit` or :exc:" -"`StopIteration`; catching the exception and doing anything else is illegal " -"and will trigger a :exc:`RuntimeError`. :meth:`~generator.close` will also " -"be called by Python's garbage collector when the generator is garbage-" -"collected." -msgstr "" - -#: ../../howto/functional.rst:613 -msgid "" -"If you need to run cleanup code when a :exc:`GeneratorExit` occurs, I " -"suggest using a ``try: ... finally:`` suite instead of catching :exc:" -"`GeneratorExit`." -msgstr "" - -#: ../../howto/functional.rst:616 -msgid "" -"The cumulative effect of these changes is to turn generators from one-way " -"producers of information into both producers and consumers." -msgstr "" - -#: ../../howto/functional.rst:619 -msgid "" -"Generators also become **coroutines**, a more generalized form of " -"subroutines. Subroutines are entered at one point and exited at another " -"point (the top of the function, and a ``return`` statement), but coroutines " -"can be entered, exited, and resumed at many different points (the ``yield`` " -"statements)." -msgstr "" - -#: ../../howto/functional.rst:626 -msgid "Built-in functions" -msgstr "內建函式" - -#: ../../howto/functional.rst:628 -msgid "" -"Let's look in more detail at built-in functions often used with iterators." -msgstr "" - -#: ../../howto/functional.rst:630 -msgid "" -"Two of Python's built-in functions, :func:`map` and :func:`filter` duplicate " -"the features of generator expressions:" -msgstr "" - -#: ../../howto/functional.rst:633 -msgid "" -":func:`map(f, iterA, iterB, ...) ` returns an iterator over the sequence" -msgstr ":func:`map(f, iterA, iterB, ...) ` 回傳一個元素為序列的疊代器" - -#: ../../howto/functional.rst:634 -msgid "" -"``f(iterA[0], iterB[0]), f(iterA[1], iterB[1]), f(iterA[2], iterB[2]), ...``." -msgstr "" -"``f(iterA[0], iterB[0]), f(iterA[1], iterB[1]), f(iterA[2], iterB[2]), ..." -"``。" - -#: ../../howto/functional.rst:644 -msgid "You can of course achieve the same effect with a list comprehension." -msgstr "" - -#: ../../howto/functional.rst:646 -msgid "" -":func:`filter(predicate, iter) ` returns an iterator over all the " -"sequence elements that meet a certain condition, and is similarly duplicated " -"by list comprehensions. A **predicate** is a function that returns the " -"truth value of some condition; for use with :func:`filter`, the predicate " -"must take a single value." -msgstr "" - -#: ../../howto/functional.rst:659 -msgid "This can also be written as a list comprehension:" -msgstr "" - -#: ../../howto/functional.rst:665 -msgid "" -":func:`enumerate(iter, start=0) ` counts off the elements in the " -"iterable returning 2-tuples containing the count (from *start*) and each " -"element. ::" -msgstr "" - -#: ../../howto/functional.rst:669 -msgid "" -">>> for item in enumerate(['subject', 'verb', 'object']):\n" -"... print(item)\n" -"(0, 'subject')\n" -"(1, 'verb')\n" -"(2, 'object')" -msgstr "" -">>> for item in enumerate(['subject', 'verb', 'object']):\n" -"... print(item)\n" -"(0, 'subject')\n" -"(1, 'verb')\n" -"(2, 'object')" - -#: ../../howto/functional.rst:675 -msgid "" -":func:`enumerate` is often used when looping through a list and recording " -"the indexes at which certain conditions are met::" -msgstr "" - -#: ../../howto/functional.rst:678 -msgid "" -"f = open('data.txt', 'r')\n" -"for i, line in enumerate(f):\n" -" if line.strip() == '':\n" -" print('Blank line at line #%i' % i)" -msgstr "" -"f = open('data.txt', 'r')\n" -"for i, line in enumerate(f):\n" -" if line.strip() == '':\n" -" print('Blank line at line #%i' % i)" - -#: ../../howto/functional.rst:683 -msgid "" -":func:`sorted(iterable, key=None, reverse=False) ` collects all the " -"elements of the iterable into a list, sorts the list, and returns the sorted " -"result. The *key* and *reverse* arguments are passed through to the " -"constructed list's :meth:`~list.sort` method. ::" -msgstr "" - -#: ../../howto/functional.rst:688 -msgid "" -">>> import random\n" -">>> # Generate 8 random numbers between [0, 10000)\n" -">>> rand_list = random.sample(range(10000), 8)\n" -">>> rand_list\n" -"[769, 7953, 9828, 6431, 8442, 9878, 6213, 2207]\n" -">>> sorted(rand_list)\n" -"[769, 2207, 6213, 6431, 7953, 8442, 9828, 9878]\n" -">>> sorted(rand_list, reverse=True)\n" -"[9878, 9828, 8442, 7953, 6431, 6213, 2207, 769]" -msgstr "" -">>> import random\n" -">>> # 產生 8 個範圍在 [0, 10000) 的隨機數字\n" -">>> rand_list = random.sample(range(10000), 8)\n" -">>> rand_list\n" -"[769, 7953, 9828, 6431, 8442, 9878, 6213, 2207]\n" -">>> sorted(rand_list)\n" -"[769, 2207, 6213, 6431, 7953, 8442, 9828, 9878]\n" -">>> sorted(rand_list, reverse=True)\n" -"[9878, 9828, 8442, 7953, 6431, 6213, 2207, 769]" - -#: ../../howto/functional.rst:698 -msgid "" -"(For a more detailed discussion of sorting, see the :ref:`sortinghowto`.)" -msgstr "" - -#: ../../howto/functional.rst:701 -msgid "" -"The :func:`any(iter) ` and :func:`all(iter) ` built-ins look at " -"the truth values of an iterable's contents. :func:`any` returns ``True`` if " -"any element in the iterable is a true value, and :func:`all` returns " -"``True`` if all of the elements are true values:" -msgstr "" - -#: ../../howto/functional.rst:720 -msgid "" -":func:`zip(iterA, iterB, ...) ` takes one element from each iterable " -"and returns them in a tuple::" -msgstr "" - -#: ../../howto/functional.rst:723 -msgid "" -"zip(['a', 'b', 'c'], (1, 2, 3)) =>\n" -" ('a', 1), ('b', 2), ('c', 3)" -msgstr "" -"zip(['a', 'b', 'c'], (1, 2, 3)) =>\n" -" ('a', 1), ('b', 2), ('c', 3)" - -#: ../../howto/functional.rst:726 -msgid "" -"It doesn't construct an in-memory list and exhaust all the input iterators " -"before returning; instead tuples are constructed and returned only if " -"they're requested. (The technical term for this behaviour is `lazy " -"evaluation `__.)" -msgstr "" - -#: ../../howto/functional.rst:731 -msgid "" -"This iterator is intended to be used with iterables that are all of the same " -"length. If the iterables are of different lengths, the resulting stream " -"will be the same length as the shortest iterable. ::" -msgstr "" - -#: ../../howto/functional.rst:735 -msgid "" -"zip(['a', 'b'], (1, 2, 3)) =>\n" -" ('a', 1), ('b', 2)" -msgstr "" -"zip(['a', 'b'], (1, 2, 3)) =>\n" -" ('a', 1), ('b', 2)" - -#: ../../howto/functional.rst:738 -msgid "" -"You should avoid doing this, though, because an element may be taken from " -"the longer iterators and discarded. This means you can't go on to use the " -"iterators further because you risk skipping a discarded element." -msgstr "" - -#: ../../howto/functional.rst:744 -msgid "The itertools module" -msgstr "itertools 模組" - -#: ../../howto/functional.rst:746 -msgid "" -"The :mod:`itertools` module contains a number of commonly used iterators as " -"well as functions for combining several iterators. This section will " -"introduce the module's contents by showing small examples." -msgstr "" - -#: ../../howto/functional.rst:750 -msgid "The module's functions fall into a few broad classes:" -msgstr "" - -#: ../../howto/functional.rst:752 -msgid "Functions that create a new iterator based on an existing iterator." -msgstr "" - -#: ../../howto/functional.rst:753 -msgid "Functions for treating an iterator's elements as function arguments." -msgstr "" - -#: ../../howto/functional.rst:754 -msgid "Functions for selecting portions of an iterator's output." -msgstr "" - -#: ../../howto/functional.rst:755 -msgid "A function for grouping an iterator's output." -msgstr "" - -#: ../../howto/functional.rst:758 -msgid "Creating new iterators" -msgstr "建立新的疊代器" - -#: ../../howto/functional.rst:760 -msgid "" -":func:`itertools.count(start, step) ` returns an infinite " -"stream of evenly spaced values. You can optionally supply the starting " -"number, which defaults to 0, and the interval between numbers, which " -"defaults to 1::" -msgstr "" - -#: ../../howto/functional.rst:764 -msgid "" -"itertools.count() =>\n" -" 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, ...\n" -"itertools.count(10) =>\n" -" 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, ...\n" -"itertools.count(10, 5) =>\n" -" 10, 15, 20, 25, 30, 35, 40, 45, 50, 55, ..." -msgstr "" -"itertools.count() =>\n" -" 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, ...\n" -"itertools.count(10) =>\n" -" 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, ...\n" -"itertools.count(10, 5) =>\n" -" 10, 15, 20, 25, 30, 35, 40, 45, 50, 55, ..." - -#: ../../howto/functional.rst:771 -msgid "" -":func:`itertools.cycle(iter) ` saves a copy of the contents " -"of a provided iterable and returns a new iterator that returns its elements " -"from first to last. The new iterator will repeat these elements " -"infinitely. ::" -msgstr "" - -#: ../../howto/functional.rst:775 -msgid "" -"itertools.cycle([1, 2, 3, 4, 5]) =>\n" -" 1, 2, 3, 4, 5, 1, 2, 3, 4, 5, ..." -msgstr "" -"itertools.cycle([1, 2, 3, 4, 5]) =>\n" -" 1, 2, 3, 4, 5, 1, 2, 3, 4, 5, ..." - -#: ../../howto/functional.rst:778 -msgid "" -":func:`itertools.repeat(elem, [n]) ` returns the provided " -"element *n* times, or returns the element endlessly if *n* is not " -"provided. ::" -msgstr "" - -#: ../../howto/functional.rst:781 -msgid "" -"itertools.repeat('abc') =>\n" -" abc, abc, abc, abc, abc, abc, abc, abc, abc, abc, ...\n" -"itertools.repeat('abc', 5) =>\n" -" abc, abc, abc, abc, abc" -msgstr "" -"itertools.repeat('abc') =>\n" -" abc, abc, abc, abc, abc, abc, abc, abc, abc, abc, ...\n" -"itertools.repeat('abc', 5) =>\n" -" abc, abc, abc, abc, abc" - -#: ../../howto/functional.rst:786 -msgid "" -":func:`itertools.chain(iterA, iterB, ...) ` takes an " -"arbitrary number of iterables as input, and returns all the elements of the " -"first iterator, then all the elements of the second, and so on, until all of " -"the iterables have been exhausted. ::" -msgstr "" - -#: ../../howto/functional.rst:791 -msgid "" -"itertools.chain(['a', 'b', 'c'], (1, 2, 3)) =>\n" -" a, b, c, 1, 2, 3" -msgstr "" -"itertools.chain(['a', 'b', 'c'], (1, 2, 3)) =>\n" -" a, b, c, 1, 2, 3" - -#: ../../howto/functional.rst:794 -msgid "" -":func:`itertools.islice(iter, [start], stop, [step]) ` " -"returns a stream that's a slice of the iterator. With a single *stop* " -"argument, it will return the first *stop* elements. If you supply a " -"starting index, you'll get *stop-start* elements, and if you supply a value " -"for *step*, elements will be skipped accordingly. Unlike Python's string " -"and list slicing, you can't use negative values for *start*, *stop*, or " -"*step*. ::" -msgstr "" - -#: ../../howto/functional.rst:801 -msgid "" -"itertools.islice(range(10), 8) =>\n" -" 0, 1, 2, 3, 4, 5, 6, 7\n" -"itertools.islice(range(10), 2, 8) =>\n" -" 2, 3, 4, 5, 6, 7\n" -"itertools.islice(range(10), 2, 8, 2) =>\n" -" 2, 4, 6" -msgstr "" -"itertools.islice(range(10), 8) =>\n" -" 0, 1, 2, 3, 4, 5, 6, 7\n" -"itertools.islice(range(10), 2, 8) =>\n" -" 2, 3, 4, 5, 6, 7\n" -"itertools.islice(range(10), 2, 8, 2) =>\n" -" 2, 4, 6" - -#: ../../howto/functional.rst:808 -msgid "" -":func:`itertools.tee(iter, [n]) ` replicates an iterator; it " -"returns *n* independent iterators that will all return the contents of the " -"source iterator. If you don't supply a value for *n*, the default is 2. " -"Replicating iterators requires saving some of the contents of the source " -"iterator, so this can consume significant memory if the iterator is large " -"and one of the new iterators is consumed more than the others. ::" -msgstr "" - -#: ../../howto/functional.rst:816 -msgid "" -"itertools.tee( itertools.count() ) =>\n" -" iterA, iterB\n" -"\n" -"where iterA ->\n" -" 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, ...\n" -"\n" -"and iterB ->\n" -" 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, ..." -msgstr "" -"itertools.tee( itertools.count() ) =>\n" -" iterA, iterB\n" -"\n" -"where iterA ->\n" -" 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, ...\n" -"\n" -"and iterB ->\n" -" 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, ..." - -#: ../../howto/functional.rst:827 -msgid "Calling functions on elements" -msgstr "" - -#: ../../howto/functional.rst:829 -msgid "" -"The :mod:`operator` module contains a set of functions corresponding to " -"Python's operators. Some examples are :func:`operator.add(a, b) ` (adds two values), :func:`operator.ne(a, b) ` (same as " -"``a != b``), and :func:`operator.attrgetter('id') ` " -"(returns a callable that fetches the ``.id`` attribute)." -msgstr "" - -#: ../../howto/functional.rst:835 -msgid "" -":func:`itertools.starmap(func, iter) ` assumes that the " -"iterable will return a stream of tuples, and calls *func* using these tuples " -"as the arguments::" -msgstr "" - -#: ../../howto/functional.rst:839 -msgid "" -"itertools.starmap(os.path.join,\n" -" [('/bin', 'python'), ('/usr', 'bin', 'java'),\n" -" ('/usr', 'bin', 'perl'), ('/usr', 'bin', 'ruby')])\n" -"=>\n" -" /bin/python, /usr/bin/java, /usr/bin/perl, /usr/bin/ruby" -msgstr "" -"itertools.starmap(os.path.join,\n" -" [('/bin', 'python'), ('/usr', 'bin', 'java'),\n" -" ('/usr', 'bin', 'perl'), ('/usr', 'bin', 'ruby')])\n" -"=>\n" -" /bin/python, /usr/bin/java, /usr/bin/perl, /usr/bin/ruby" - -#: ../../howto/functional.rst:847 -msgid "Selecting elements" -msgstr "" - -#: ../../howto/functional.rst:849 -msgid "" -"Another group of functions chooses a subset of an iterator's elements based " -"on a predicate." -msgstr "" - -#: ../../howto/functional.rst:852 -msgid "" -":func:`itertools.filterfalse(predicate, iter) ` is " -"the opposite of :func:`filter`, returning all elements for which the " -"predicate returns false::" -msgstr "" - -#: ../../howto/functional.rst:856 -msgid "" -"itertools.filterfalse(is_even, itertools.count()) =>\n" -" 1, 3, 5, 7, 9, 11, 13, 15, ..." -msgstr "" -"itertools.filterfalse(is_even, itertools.count()) =>\n" -" 1, 3, 5, 7, 9, 11, 13, 15, ..." - -#: ../../howto/functional.rst:859 -msgid "" -":func:`itertools.takewhile(predicate, iter) ` returns " -"elements for as long as the predicate returns true. Once the predicate " -"returns false, the iterator will signal the end of its results. ::" -msgstr "" - -#: ../../howto/functional.rst:863 -msgid "" -"def less_than_10(x):\n" -" return x < 10\n" -"\n" -"itertools.takewhile(less_than_10, itertools.count()) =>\n" -" 0, 1, 2, 3, 4, 5, 6, 7, 8, 9\n" -"\n" -"itertools.takewhile(is_even, itertools.count()) =>\n" -" 0" -msgstr "" -"def less_than_10(x):\n" -" return x < 10\n" -"\n" -"itertools.takewhile(less_than_10, itertools.count()) =>\n" -" 0, 1, 2, 3, 4, 5, 6, 7, 8, 9\n" -"\n" -"itertools.takewhile(is_even, itertools.count()) =>\n" -" 0" - -#: ../../howto/functional.rst:872 -msgid "" -":func:`itertools.dropwhile(predicate, iter) ` discards " -"elements while the predicate returns true, and then returns the rest of the " -"iterable's results. ::" -msgstr "" - -#: ../../howto/functional.rst:876 -msgid "" -"itertools.dropwhile(less_than_10, itertools.count()) =>\n" -" 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, ...\n" -"\n" -"itertools.dropwhile(is_even, itertools.count()) =>\n" -" 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, ..." -msgstr "" -"itertools.dropwhile(less_than_10, itertools.count()) =>\n" -" 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, ...\n" -"\n" -"itertools.dropwhile(is_even, itertools.count()) =>\n" -" 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, ..." - -#: ../../howto/functional.rst:882 -msgid "" -":func:`itertools.compress(data, selectors) ` takes two " -"iterators and returns only those elements of *data* for which the " -"corresponding element of *selectors* is true, stopping whenever either one " -"is exhausted::" -msgstr "" - -#: ../../howto/functional.rst:886 -msgid "" -"itertools.compress([1, 2, 3, 4, 5], [True, True, False, False, True]) =>\n" -" 1, 2, 5" -msgstr "" -"itertools.compress([1, 2, 3, 4, 5], [True, True, False, False, True]) =>\n" -" 1, 2, 5" - -#: ../../howto/functional.rst:891 -msgid "Combinatoric functions" -msgstr "" - -#: ../../howto/functional.rst:893 -msgid "" -"The :func:`itertools.combinations(iterable, r) ` " -"returns an iterator giving all possible *r*-tuple combinations of the " -"elements contained in *iterable*. ::" -msgstr "" - -#: ../../howto/functional.rst:897 -msgid "" -"itertools.combinations([1, 2, 3, 4, 5], 2) =>\n" -" (1, 2), (1, 3), (1, 4), (1, 5),\n" -" (2, 3), (2, 4), (2, 5),\n" -" (3, 4), (3, 5),\n" -" (4, 5)\n" -"\n" -"itertools.combinations([1, 2, 3, 4, 5], 3) =>\n" -" (1, 2, 3), (1, 2, 4), (1, 2, 5), (1, 3, 4), (1, 3, 5), (1, 4, 5),\n" -" (2, 3, 4), (2, 3, 5), (2, 4, 5),\n" -" (3, 4, 5)" -msgstr "" -"itertools.combinations([1, 2, 3, 4, 5], 2) =>\n" -" (1, 2), (1, 3), (1, 4), (1, 5),\n" -" (2, 3), (2, 4), (2, 5),\n" -" (3, 4), (3, 5),\n" -" (4, 5)\n" -"\n" -"itertools.combinations([1, 2, 3, 4, 5], 3) =>\n" -" (1, 2, 3), (1, 2, 4), (1, 2, 5), (1, 3, 4), (1, 3, 5), (1, 4, 5),\n" -" (2, 3, 4), (2, 3, 5), (2, 4, 5),\n" -" (3, 4, 5)" - -#: ../../howto/functional.rst:908 -msgid "" -"The elements within each tuple remain in the same order as *iterable* " -"returned them. For example, the number 1 is always before 2, 3, 4, or 5 in " -"the examples above. A similar function, :func:`itertools." -"permutations(iterable, r=None) `, removes this " -"constraint on the order, returning all possible arrangements of length *r*::" -msgstr "" - -#: ../../howto/functional.rst:915 -msgid "" -"itertools.permutations([1, 2, 3, 4, 5], 2) =>\n" -" (1, 2), (1, 3), (1, 4), (1, 5),\n" -" (2, 1), (2, 3), (2, 4), (2, 5),\n" -" (3, 1), (3, 2), (3, 4), (3, 5),\n" -" (4, 1), (4, 2), (4, 3), (4, 5),\n" -" (5, 1), (5, 2), (5, 3), (5, 4)\n" -"\n" -"itertools.permutations([1, 2, 3, 4, 5]) =>\n" -" (1, 2, 3, 4, 5), (1, 2, 3, 5, 4), (1, 2, 4, 3, 5),\n" -" ...\n" -" (5, 4, 3, 2, 1)" -msgstr "" -"itertools.permutations([1, 2, 3, 4, 5], 2) =>\n" -" (1, 2), (1, 3), (1, 4), (1, 5),\n" -" (2, 1), (2, 3), (2, 4), (2, 5),\n" -" (3, 1), (3, 2), (3, 4), (3, 5),\n" -" (4, 1), (4, 2), (4, 3), (4, 5),\n" -" (5, 1), (5, 2), (5, 3), (5, 4)\n" -"\n" -"itertools.permutations([1, 2, 3, 4, 5]) =>\n" -" (1, 2, 3, 4, 5), (1, 2, 3, 5, 4), (1, 2, 4, 3, 5),\n" -" ...\n" -" (5, 4, 3, 2, 1)" - -#: ../../howto/functional.rst:927 -msgid "" -"If you don't supply a value for *r* the length of the iterable is used, " -"meaning that all the elements are permuted." -msgstr "" - -#: ../../howto/functional.rst:930 -msgid "" -"Note that these functions produce all of the possible combinations by " -"position and don't require that the contents of *iterable* are unique::" -msgstr "" - -#: ../../howto/functional.rst:933 -msgid "" -"itertools.permutations('aba', 3) =>\n" -" ('a', 'b', 'a'), ('a', 'a', 'b'), ('b', 'a', 'a'),\n" -" ('b', 'a', 'a'), ('a', 'a', 'b'), ('a', 'b', 'a')" -msgstr "" -"itertools.permutations('aba', 3) =>\n" -" ('a', 'b', 'a'), ('a', 'a', 'b'), ('b', 'a', 'a'),\n" -" ('b', 'a', 'a'), ('a', 'a', 'b'), ('a', 'b', 'a')" - -#: ../../howto/functional.rst:937 -msgid "" -"The identical tuple ``('a', 'a', 'b')`` occurs twice, but the two 'a' " -"strings came from different positions." -msgstr "" - -#: ../../howto/functional.rst:940 -msgid "" -"The :func:`itertools.combinations_with_replacement(iterable, r) ` function relaxes a different constraint: " -"elements can be repeated within a single tuple. Conceptually an element is " -"selected for the first position of each tuple and then is replaced before " -"the second element is selected. ::" -msgstr "" - -#: ../../howto/functional.rst:946 -msgid "" -"itertools.combinations_with_replacement([1, 2, 3, 4, 5], 2) =>\n" -" (1, 1), (1, 2), (1, 3), (1, 4), (1, 5),\n" -" (2, 2), (2, 3), (2, 4), (2, 5),\n" -" (3, 3), (3, 4), (3, 5),\n" -" (4, 4), (4, 5),\n" -" (5, 5)" -msgstr "" -"itertools.combinations_with_replacement([1, 2, 3, 4, 5], 2) =>\n" -" (1, 1), (1, 2), (1, 3), (1, 4), (1, 5),\n" -" (2, 2), (2, 3), (2, 4), (2, 5),\n" -" (3, 3), (3, 4), (3, 5),\n" -" (4, 4), (4, 5),\n" -" (5, 5)" - -#: ../../howto/functional.rst:955 -msgid "Grouping elements" -msgstr "" - -#: ../../howto/functional.rst:957 -msgid "" -"The last function I'll discuss, :func:`itertools.groupby(iter, " -"key_func=None) `, is the most complicated. " -"``key_func(elem)`` is a function that can compute a key value for each " -"element returned by the iterable. If you don't supply a key function, the " -"key is simply each element itself." -msgstr "" - -#: ../../howto/functional.rst:962 -msgid "" -":func:`~itertools.groupby` collects all the consecutive elements from the " -"underlying iterable that have the same key value, and returns a stream of 2-" -"tuples containing a key value and an iterator for the elements with that key." -msgstr "" - -#: ../../howto/functional.rst:968 -msgid "" -"city_list = [('Decatur', 'AL'), ('Huntsville', 'AL'), ('Selma', 'AL'),\n" -" ('Anchorage', 'AK'), ('Nome', 'AK'),\n" -" ('Flagstaff', 'AZ'), ('Phoenix', 'AZ'), ('Tucson', 'AZ'),\n" -" ...\n" -" ]\n" -"\n" -"def get_state(city_state):\n" -" return city_state[1]\n" -"\n" -"itertools.groupby(city_list, get_state) =>\n" -" ('AL', iterator-1),\n" -" ('AK', iterator-2),\n" -" ('AZ', iterator-3), ...\n" -"\n" -"where\n" -"iterator-1 =>\n" -" ('Decatur', 'AL'), ('Huntsville', 'AL'), ('Selma', 'AL')\n" -"iterator-2 =>\n" -" ('Anchorage', 'AK'), ('Nome', 'AK')\n" -"iterator-3 =>\n" -" ('Flagstaff', 'AZ'), ('Phoenix', 'AZ'), ('Tucson', 'AZ')" -msgstr "" -"city_list = [('Decatur', 'AL'), ('Huntsville', 'AL'), ('Selma', 'AL'),\n" -" ('Anchorage', 'AK'), ('Nome', 'AK'),\n" -" ('Flagstaff', 'AZ'), ('Phoenix', 'AZ'), ('Tucson', 'AZ'),\n" -" ...\n" -" ]\n" -"\n" -"def get_state(city_state):\n" -" return city_state[1]\n" -"\n" -"itertools.groupby(city_list, get_state) =>\n" -" ('AL', iterator-1),\n" -" ('AK', iterator-2),\n" -" ('AZ', iterator-3), ...\n" -"\n" -"where\n" -"iterator-1 =>\n" -" ('Decatur', 'AL'), ('Huntsville', 'AL'), ('Selma', 'AL')\n" -"iterator-2 =>\n" -" ('Anchorage', 'AK'), ('Nome', 'AK')\n" -"iterator-3 =>\n" -" ('Flagstaff', 'AZ'), ('Phoenix', 'AZ'), ('Tucson', 'AZ')" - -#: ../../howto/functional.rst:990 -msgid "" -":func:`~itertools.groupby` assumes that the underlying iterable's contents " -"will already be sorted based on the key. Note that the returned iterators " -"also use the underlying iterable, so you have to consume the results of " -"iterator-1 before requesting iterator-2 and its corresponding key." -msgstr "" - -#: ../../howto/functional.rst:997 -msgid "The functools module" -msgstr "functools 模組" - -#: ../../howto/functional.rst:999 -msgid "" -"The :mod:`functools` module contains some higher-order functions. A **higher-" -"order function** takes one or more functions as input and returns a new " -"function. The most useful tool in this module is the :func:`functools." -"partial` function." -msgstr "" - -#: ../../howto/functional.rst:1004 -msgid "" -"For programs written in a functional style, you'll sometimes want to " -"construct variants of existing functions that have some of the parameters " -"filled in. Consider a Python function ``f(a, b, c)``; you may wish to create " -"a new function ``g(b, c)`` that's equivalent to ``f(1, b, c)``; you're " -"filling in a value for one of ``f()``'s parameters. This is called " -"\"partial function application\"." -msgstr "" - -#: ../../howto/functional.rst:1010 -msgid "" -"The constructor for :func:`~functools.partial` takes the arguments " -"``(function, arg1, arg2, ..., kwarg1=value1, kwarg2=value2)``. The " -"resulting object is callable, so you can just call it to invoke ``function`` " -"with the filled-in arguments." -msgstr "" - -#: ../../howto/functional.rst:1015 -msgid "Here's a small but realistic example::" -msgstr "以下是個很小但實際的範例： ::" - -#: ../../howto/functional.rst:1017 -msgid "" -"import functools\n" -"\n" -"def log(message, subsystem):\n" -" \"\"\"Write the contents of 'message' to the specified subsystem.\"\"\"\n" -" print('%s: %s' % (subsystem, message))\n" -" ...\n" -"\n" -"server_log = functools.partial(log, subsystem='server')\n" -"server_log('Unable to open socket')" -msgstr "" - -#: ../../howto/functional.rst:1027 -msgid "" -":func:`functools.reduce(func, iter, [initial_value]) ` " -"cumulatively performs an operation on all the iterable's elements and, " -"therefore, can't be applied to infinite iterables. *func* must be a function " -"that takes two elements and returns a single value. :func:`functools." -"reduce` takes the first two elements A and B returned by the iterator and " -"calculates ``func(A, B)``. It then requests the third element, C, " -"calculates ``func(func(A, B), C)``, combines this result with the fourth " -"element returned, and continues until the iterable is exhausted. If the " -"iterable returns no values at all, a :exc:`TypeError` exception is raised. " -"If the initial value is supplied, it's used as a starting point and " -"``func(initial_value, A)`` is the first calculation. ::" -msgstr "" - -#: ../../howto/functional.rst:1039 -msgid "" -">>> import operator, functools\n" -">>> functools.reduce(operator.concat, ['A', 'BB', 'C'])\n" -"'ABBC'\n" -">>> functools.reduce(operator.concat, [])\n" -"Traceback (most recent call last):\n" -" ...\n" -"TypeError: reduce() of empty sequence with no initial value\n" -">>> functools.reduce(operator.mul, [1, 2, 3], 1)\n" -"6\n" -">>> functools.reduce(operator.mul, [], 1)\n" -"1" -msgstr "" -">>> import operator, functools\n" -">>> functools.reduce(operator.concat, ['A', 'BB', 'C'])\n" -"'ABBC'\n" -">>> functools.reduce(operator.concat, [])\n" -"Traceback (most recent call last):\n" -" ...\n" -"TypeError: reduce() of empty sequence with no initial value\n" -">>> functools.reduce(operator.mul, [1, 2, 3], 1)\n" -"6\n" -">>> functools.reduce(operator.mul, [], 1)\n" -"1" - -#: ../../howto/functional.rst:1051 -msgid "" -"If you use :func:`operator.add` with :func:`functools.reduce`, you'll add up " -"all the elements of the iterable. This case is so common that there's a " -"special built-in called :func:`sum` to compute it:" -msgstr "" - -#: ../../howto/functional.rst:1063 -msgid "" -"For many uses of :func:`functools.reduce`, though, it can be clearer to just " -"write the obvious :keyword:`for` loop::" -msgstr "" - -#: ../../howto/functional.rst:1066 -msgid "" -"import functools\n" -"# Instead of:\n" -"product = functools.reduce(operator.mul, [1, 2, 3], 1)\n" -"\n" -"# You can write:\n" -"product = 1\n" -"for i in [1, 2, 3]:\n" -" product *= i" -msgstr "" - -#: ../../howto/functional.rst:1075 -msgid "" -"A related function is :func:`itertools.accumulate(iterable, func=operator." -"add) `. It performs the same calculation, but instead " -"of returning only the final result, :func:`~itertools.accumulate` returns an " -"iterator that also yields each partial result::" -msgstr "" - -#: ../../howto/functional.rst:1080 -msgid "" -"itertools.accumulate([1, 2, 3, 4, 5]) =>\n" -" 1, 3, 6, 10, 15\n" -"\n" -"itertools.accumulate([1, 2, 3, 4, 5], operator.mul) =>\n" -" 1, 2, 6, 24, 120" -msgstr "" -"itertools.accumulate([1, 2, 3, 4, 5]) =>\n" -" 1, 3, 6, 10, 15\n" -"\n" -"itertools.accumulate([1, 2, 3, 4, 5], operator.mul) =>\n" -" 1, 2, 6, 24, 120" - -#: ../../howto/functional.rst:1088 -msgid "The operator module" -msgstr "operator 模組" - -#: ../../howto/functional.rst:1090 -msgid "" -"The :mod:`operator` module was mentioned earlier. It contains a set of " -"functions corresponding to Python's operators. These functions are often " -"useful in functional-style code because they save you from writing trivial " -"functions that perform a single operation." -msgstr "" - -#: ../../howto/functional.rst:1095 -msgid "Some of the functions in this module are:" -msgstr "" - -#: ../../howto/functional.rst:1097 -msgid "" -"Math operations: ``add()``, ``sub()``, ``mul()``, ``floordiv()``, " -"``abs()``, ..." -msgstr "" -"數學運算：``add()``、``sub()``、``mul()``、``floordiv()``、``abs()``..." - -#: ../../howto/functional.rst:1098 -msgid "Logical operations: ``not_()``, ``truth()``." -msgstr "" - -#: ../../howto/functional.rst:1099 -msgid "Bitwise operations: ``and_()``, ``or_()``, ``invert()``." -msgstr "" - -#: ../../howto/functional.rst:1100 -msgid "" -"Comparisons: ``eq()``, ``ne()``, ``lt()``, ``le()``, ``gt()``, and ``ge()``." -msgstr "" - -#: ../../howto/functional.rst:1101 -msgid "Object identity: ``is_()``, ``is_not()``." -msgstr "" - -#: ../../howto/functional.rst:1103 -msgid "Consult the operator module's documentation for a complete list." -msgstr "" - -#: ../../howto/functional.rst:1107 -msgid "Small functions and the lambda expression" -msgstr "" - -#: ../../howto/functional.rst:1109 -msgid "" -"When writing functional-style programs, you'll often need little functions " -"that act as predicates or that combine elements in some way." -msgstr "" - -#: ../../howto/functional.rst:1112 -msgid "" -"If there's a Python built-in or a module function that's suitable, you don't " -"need to define a new function at all::" -msgstr "" - -#: ../../howto/functional.rst:1115 -msgid "" -"stripped_lines = [line.strip() for line in lines]\n" -"existing_files = filter(os.path.exists, file_list)" -msgstr "" -"stripped_lines = [line.strip() for line in lines]\n" -"existing_files = filter(os.path.exists, file_list)" - -#: ../../howto/functional.rst:1118 -msgid "" -"If the function you need doesn't exist, you need to write it. One way to " -"write small functions is to use the :keyword:`lambda` expression. " -"``lambda`` takes a number of parameters and an expression combining these " -"parameters, and creates an anonymous function that returns the value of the " -"expression::" -msgstr "" - -#: ../../howto/functional.rst:1123 -msgid "" -"adder = lambda x, y: x+y\n" -"\n" -"print_assign = lambda name, value: name + '=' + str(value)" -msgstr "" -"adder = lambda x, y: x+y\n" -"\n" -"print_assign = lambda name, value: name + '=' + str(value)" - -#: ../../howto/functional.rst:1127 -msgid "" -"An alternative is to just use the ``def`` statement and define a function in " -"the usual way::" -msgstr "" - -#: ../../howto/functional.rst:1130 -msgid "" -"def adder(x, y):\n" -" return x + y\n" -"\n" -"def print_assign(name, value):\n" -" return name + '=' + str(value)" -msgstr "" -"def adder(x, y):\n" -" return x + y\n" -"\n" -"def print_assign(name, value):\n" -" return name + '=' + str(value)" - -#: ../../howto/functional.rst:1136 -msgid "" -"Which alternative is preferable? That's a style question; my usual course " -"is to avoid using ``lambda``." -msgstr "" - -#: ../../howto/functional.rst:1139 -msgid "" -"One reason for my preference is that ``lambda`` is quite limited in the " -"functions it can define. The result has to be computable as a single " -"expression, which means you can't have multiway ``if... elif... else`` " -"comparisons or ``try... except`` statements. If you try to do too much in a " -"``lambda`` statement, you'll end up with an overly complicated expression " -"that's hard to read. Quick, what's the following code doing? ::" -msgstr "" - -#: ../../howto/functional.rst:1146 -msgid "" -"import functools\n" -"total = functools.reduce(lambda a, b: (0, a[1] + b[1]), items)[1]" -msgstr "" -"import functools\n" -"total = functools.reduce(lambda a, b: (0, a[1] + b[1]), items)[1]" - -#: ../../howto/functional.rst:1149 -msgid "" -"You can figure it out, but it takes time to disentangle the expression to " -"figure out what's going on. Using a short nested ``def`` statements makes " -"things a little bit better::" -msgstr "" - -#: ../../howto/functional.rst:1153 -msgid "" -"import functools\n" -"def combine(a, b):\n" -" return 0, a[1] + b[1]\n" -"\n" -"total = functools.reduce(combine, items)[1]" -msgstr "" -"import functools\n" -"def combine(a, b):\n" -" return 0, a[1] + b[1]\n" -"\n" -"total = functools.reduce(combine, items)[1]" - -#: ../../howto/functional.rst:1159 -msgid "But it would be best of all if I had simply used a ``for`` loop::" -msgstr "" - -#: ../../howto/functional.rst:1161 -msgid "" -"total = 0\n" -"for a, b in items:\n" -" total += b" -msgstr "" -"total = 0\n" -"for a, b in items:\n" -" total += b" - -#: ../../howto/functional.rst:1165 -msgid "Or the :func:`sum` built-in and a generator expression::" -msgstr "" - -#: ../../howto/functional.rst:1167 -msgid "total = sum(b for a, b in items)" -msgstr "total = sum(b for a, b in items)" - -#: ../../howto/functional.rst:1169 -msgid "" -"Many uses of :func:`functools.reduce` are clearer when written as ``for`` " -"loops." -msgstr "" - -#: ../../howto/functional.rst:1171 -msgid "" -"Fredrik Lundh once suggested the following set of rules for refactoring uses " -"of ``lambda``:" -msgstr "" - -#: ../../howto/functional.rst:1174 -msgid "Write a lambda function." -msgstr "" - -#: ../../howto/functional.rst:1175 -msgid "Write a comment explaining what the heck that lambda does." -msgstr "" - -#: ../../howto/functional.rst:1176 -msgid "" -"Study the comment for a while, and think of a name that captures the essence " -"of the comment." -msgstr "" - -#: ../../howto/functional.rst:1178 -msgid "Convert the lambda to a def statement, using that name." -msgstr "" - -#: ../../howto/functional.rst:1179 -msgid "Remove the comment." -msgstr "" - -#: ../../howto/functional.rst:1181 -msgid "" -"I really like these rules, but you're free to disagree about whether this " -"lambda-free style is better." -msgstr "" - -#: ../../howto/functional.rst:1186 -msgid "Revision History and Acknowledgements" -msgstr "" - -#: ../../howto/functional.rst:1188 -msgid "" -"The author would like to thank the following people for offering " -"suggestions, corrections and assistance with various drafts of this article: " -"Ian Bicking, Nick Coghlan, Nick Efford, Raymond Hettinger, Jim Jewett, Mike " -"Krell, Leandro Lameiro, Jussi Salmela, Collin Winter, Blake Winton." -msgstr "" - -#: ../../howto/functional.rst:1193 -msgid "Version 0.1: posted June 30 2006." -msgstr "" - -#: ../../howto/functional.rst:1195 -msgid "Version 0.11: posted July 1 2006. Typo fixes." -msgstr "" - -#: ../../howto/functional.rst:1197 -msgid "" -"Version 0.2: posted July 10 2006. Merged genexp and listcomp sections into " -"one. Typo fixes." -msgstr "" - -#: ../../howto/functional.rst:1200 -msgid "" -"Version 0.21: Added more references suggested on the tutor mailing list." -msgstr "" - -#: ../../howto/functional.rst:1202 -msgid "" -"Version 0.30: Adds a section on the ``functional`` module written by Collin " -"Winter; adds short section on the operator module; a few other edits." -msgstr "" - -#: ../../howto/functional.rst:1207 -msgid "References" -msgstr "" - -#: ../../howto/functional.rst:1210 -msgid "General" -msgstr "" - -#: ../../howto/functional.rst:1212 -msgid "" -"**Structure and Interpretation of Computer Programs**, by Harold Abelson and " -"Gerald Jay Sussman with Julie Sussman. The book can be found at https://" -"mitpress.mit.edu/sicp. In this classic textbook of computer science, " -"chapters 2 and 3 discuss the use of sequences and streams to organize the " -"data flow inside a program. The book uses Scheme for its examples, but many " -"of the design approaches described in these chapters are applicable to " -"functional-style Python code." -msgstr "" - -#: ../../howto/functional.rst:1220 -msgid "" -"https://defmacro.org/2006/06/19/fp.html: A general introduction to " -"functional programming that uses Java examples and has a lengthy historical " -"introduction." -msgstr "" - -#: ../../howto/functional.rst:1223 -msgid "" -"https://en.wikipedia.org/wiki/Functional_programming: General Wikipedia " -"entry describing functional programming." -msgstr "" - -#: ../../howto/functional.rst:1226 -msgid "https://en.wikipedia.org/wiki/Coroutine: Entry for coroutines." -msgstr "https://en.wikipedia.org/wiki/Coroutine: 協程 (coroutines) 的條目。" - -#: ../../howto/functional.rst:1228 -msgid "" -"https://en.wikipedia.org/wiki/Partial_application: Entry for the concept of " -"partial function application." -msgstr "" -"https://en.wikipedia.org/wiki/Partial_application: 偏函式 (partial " -"application) 概念的條目。" - -#: ../../howto/functional.rst:1230 -msgid "" -"https://en.wikipedia.org/wiki/Currying: Entry for the concept of currying." -msgstr "https://en.wikipedia.org/wiki/Currying: currying 概念的條目。" - -#: ../../howto/functional.rst:1233 -msgid "Python-specific" -msgstr "Python 特有的" - -#: ../../howto/functional.rst:1235 -msgid "" -"https://gnosis.cx/TPiP/: The first chapter of David Mertz's book :title-" -"reference:`Text Processing in Python` discusses functional programming for " -"text processing, in the section titled \"Utilizing Higher-Order Functions in " -"Text Processing\"." -msgstr "" - -#: ../../howto/functional.rst:1240 -msgid "" -"Mertz also wrote a 3-part series of articles on functional programming for " -"IBM's DeveloperWorks site; see `part 1 `__, `part 2 `__, and " -"`part 3 `__," -msgstr "" - -#: ../../howto/functional.rst:1248 -msgid "Python documentation" -msgstr "Python 說明文件" - -#: ../../howto/functional.rst:1250 -msgid "Documentation for the :mod:`itertools` module." -msgstr ":mod:`itertools` 模組的說明文件。" - -#: ../../howto/functional.rst:1252 -msgid "Documentation for the :mod:`functools` module." -msgstr ":mod:`functools` 模組的說明文件。" - -#: ../../howto/functional.rst:1254 -msgid "Documentation for the :mod:`operator` module." -msgstr ":mod:`operator` 模組的說明文件。" - -#: ../../howto/functional.rst:1256 -msgid ":pep:`289`: \"Generator Expressions\"" -msgstr ":pep:`289`：「產生器運算式 (Generator Expressions)」" - -#: ../../howto/functional.rst:1258 -msgid "" -":pep:`342`: \"Coroutines via Enhanced Generators\" describes the new " -"generator features in Python 2.5." -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Leon H., 2017 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-30 00:16+0000\n" +"PO-Revision-Date: 2018-05-23 14:36+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" + +#: ../../howto/functional.rst:5 +msgid "Functional Programming HOWTO" +msgstr "函式程式設計 HOWTO" + +#: ../../howto/functional.rst:0 +msgid "Author" +msgstr "作者" + +#: ../../howto/functional.rst:7 +msgid "\\A. M. Kuchling" +msgstr "\\A. M. Kuchling" + +#: ../../howto/functional.rst:0 +msgid "Release" +msgstr "發佈版本" + +#: ../../howto/functional.rst:8 +msgid "0.32" +msgstr "0.32" + +#: ../../howto/functional.rst:10 +msgid "" +"In this document, we'll take a tour of Python's features suitable for " +"implementing programs in a functional style. After an introduction to the " +"concepts of functional programming, we'll look at language features such as :" +"term:`iterator`\\s and :term:`generator`\\s and relevant library modules " +"such as :mod:`itertools` and :mod:`functools`." +msgstr "" + +#: ../../howto/functional.rst:18 +msgid "Introduction" +msgstr "簡介" + +#: ../../howto/functional.rst:20 +msgid "" +"This section explains the basic concept of functional programming; if you're " +"just interested in learning about Python language features, skip to the next " +"section on :ref:`functional-howto-iterators`." +msgstr "" + +#: ../../howto/functional.rst:24 +msgid "" +"Programming languages support decomposing problems in several different ways:" +msgstr "" + +#: ../../howto/functional.rst:26 +msgid "" +"Most programming languages are **procedural**: programs are lists of " +"instructions that tell the computer what to do with the program's input. C, " +"Pascal, and even Unix shells are procedural languages." +msgstr "" + +#: ../../howto/functional.rst:30 +msgid "" +"In **declarative** languages, you write a specification that describes the " +"problem to be solved, and the language implementation figures out how to " +"perform the computation efficiently. SQL is the declarative language you're " +"most likely to be familiar with; a SQL query describes the data set you want " +"to retrieve, and the SQL engine decides whether to scan tables or use " +"indexes, which subclauses should be performed first, etc." +msgstr "" + +#: ../../howto/functional.rst:37 +msgid "" +"**Object-oriented** programs manipulate collections of objects. Objects " +"have internal state and support methods that query or modify this internal " +"state in some way. Smalltalk and Java are object-oriented languages. C++ " +"and Python are languages that support object-oriented programming, but don't " +"force the use of object-oriented features." +msgstr "" + +#: ../../howto/functional.rst:43 +msgid "" +"**Functional** programming decomposes a problem into a set of functions. " +"Ideally, functions only take inputs and produce outputs, and don't have any " +"internal state that affects the output produced for a given input. Well-" +"known functional languages include the ML family (Standard ML, OCaml, and " +"other variants) and Haskell." +msgstr "" + +#: ../../howto/functional.rst:49 +msgid "" +"The designers of some computer languages choose to emphasize one particular " +"approach to programming. This often makes it difficult to write programs " +"that use a different approach. Other languages are multi-paradigm languages " +"that support several different approaches. Lisp, C++, and Python are multi-" +"paradigm; you can write programs or libraries that are largely procedural, " +"object-oriented, or functional in all of these languages. In a large " +"program, different sections might be written using different approaches; the " +"GUI might be object-oriented while the processing logic is procedural or " +"functional, for example." +msgstr "" + +#: ../../howto/functional.rst:60 +msgid "" +"In a functional program, input flows through a set of functions. Each " +"function operates on its input and produces some output. Functional style " +"discourages functions with side effects that modify internal state or make " +"other changes that aren't visible in the function's return value. Functions " +"that have no side effects at all are called **purely functional**. Avoiding " +"side effects means not using data structures that get updated as a program " +"runs; every function's output must only depend on its input." +msgstr "" + +#: ../../howto/functional.rst:68 +msgid "" +"Some languages are very strict about purity and don't even have assignment " +"statements such as ``a=3`` or ``c = a + b``, but it's difficult to avoid all " +"side effects, such as printing to the screen or writing to a disk file. " +"Another example is a call to the :func:`print` or :func:`time.sleep` " +"function, neither of which returns a useful value. Both are called only for " +"their side effects of sending some text to the screen or pausing execution " +"for a second." +msgstr "" + +#: ../../howto/functional.rst:75 +msgid "" +"Python programs written in functional style usually won't go to the extreme " +"of avoiding all I/O or all assignments; instead, they'll provide a " +"functional-appearing interface but will use non-functional features " +"internally. For example, the implementation of a function will still use " +"assignments to local variables, but won't modify global variables or have " +"other side effects." +msgstr "" + +#: ../../howto/functional.rst:81 +msgid "" +"Functional programming can be considered the opposite of object-oriented " +"programming. Objects are little capsules containing some internal state " +"along with a collection of method calls that let you modify this state, and " +"programs consist of making the right set of state changes. Functional " +"programming wants to avoid state changes as much as possible and works with " +"data flowing between functions. In Python you might combine the two " +"approaches by writing functions that take and return instances representing " +"objects in your application (e-mail messages, transactions, etc.)." +msgstr "" + +#: ../../howto/functional.rst:90 +msgid "" +"Functional design may seem like an odd constraint to work under. Why should " +"you avoid objects and side effects? There are theoretical and practical " +"advantages to the functional style:" +msgstr "" + +#: ../../howto/functional.rst:94 +msgid "Formal provability." +msgstr "形式可證明性 (Formal provability)。" + +#: ../../howto/functional.rst:95 +msgid "Modularity." +msgstr "模組化 (Modularity)。" + +#: ../../howto/functional.rst:96 +msgid "Composability." +msgstr "可組合性 (Composability)。" + +#: ../../howto/functional.rst:97 +msgid "Ease of debugging and testing." +msgstr "容易除錯與測試。" + +#: ../../howto/functional.rst:101 +msgid "Formal provability" +msgstr "形式可證明性" + +#: ../../howto/functional.rst:103 +msgid "" +"A theoretical benefit is that it's easier to construct a mathematical proof " +"that a functional program is correct." +msgstr "" + +#: ../../howto/functional.rst:106 +msgid "" +"For a long time researchers have been interested in finding ways to " +"mathematically prove programs correct. This is different from testing a " +"program on numerous inputs and concluding that its output is usually " +"correct, or reading a program's source code and concluding that the code " +"looks right; the goal is instead a rigorous proof that a program produces " +"the right result for all possible inputs." +msgstr "" + +#: ../../howto/functional.rst:113 +msgid "" +"The technique used to prove programs correct is to write down " +"**invariants**, properties of the input data and of the program's variables " +"that are always true. For each line of code, you then show that if " +"invariants X and Y are true **before** the line is executed, the slightly " +"different invariants X' and Y' are true **after** the line is executed. " +"This continues until you reach the end of the program, at which point the " +"invariants should match the desired conditions on the program's output." +msgstr "" + +#: ../../howto/functional.rst:121 +msgid "" +"Functional programming's avoidance of assignments arose because assignments " +"are difficult to handle with this technique; assignments can break " +"invariants that were true before the assignment without producing any new " +"invariants that can be propagated onward." +msgstr "" + +#: ../../howto/functional.rst:126 +msgid "" +"Unfortunately, proving programs correct is largely impractical and not " +"relevant to Python software. Even trivial programs require proofs that are " +"several pages long; the proof of correctness for a moderately complicated " +"program would be enormous, and few or none of the programs you use daily " +"(the Python interpreter, your XML parser, your web browser) could be proven " +"correct. Even if you wrote down or generated a proof, there would then be " +"the question of verifying the proof; maybe there's an error in it, and you " +"wrongly believe you've proved the program correct." +msgstr "" + +#: ../../howto/functional.rst:137 +msgid "Modularity" +msgstr "模組化" + +#: ../../howto/functional.rst:139 +msgid "" +"A more practical benefit of functional programming is that it forces you to " +"break apart your problem into small pieces. Programs are more modular as a " +"result. It's easier to specify and write a small function that does one " +"thing than a large function that performs a complicated transformation. " +"Small functions are also easier to read and to check for errors." +msgstr "" + +#: ../../howto/functional.rst:147 +msgid "Ease of debugging and testing" +msgstr "容易除錯與測試" + +#: ../../howto/functional.rst:149 +msgid "Testing and debugging a functional-style program is easier." +msgstr "" + +#: ../../howto/functional.rst:151 +msgid "" +"Debugging is simplified because functions are generally small and clearly " +"specified. When a program doesn't work, each function is an interface point " +"where you can check that the data are correct. You can look at the " +"intermediate inputs and outputs to quickly isolate the function that's " +"responsible for a bug." +msgstr "" + +#: ../../howto/functional.rst:156 +msgid "" +"Testing is easier because each function is a potential subject for a unit " +"test. Functions don't depend on system state that needs to be replicated " +"before running a test; instead you only have to synthesize the right input " +"and then check that the output matches expectations." +msgstr "" + +#: ../../howto/functional.rst:163 +msgid "Composability" +msgstr "可組合性" + +#: ../../howto/functional.rst:165 +msgid "" +"As you work on a functional-style program, you'll write a number of " +"functions with varying inputs and outputs. Some of these functions will be " +"unavoidably specialized to a particular application, but others will be " +"useful in a wide variety of programs. For example, a function that takes a " +"directory path and returns all the XML files in the directory, or a function " +"that takes a filename and returns its contents, can be applied to many " +"different situations." +msgstr "" + +#: ../../howto/functional.rst:172 +msgid "" +"Over time you'll form a personal library of utilities. Often you'll " +"assemble new programs by arranging existing functions in a new configuration " +"and writing a few functions specialized for the current task." +msgstr "" + +#: ../../howto/functional.rst:180 +msgid "Iterators" +msgstr "疊代器" + +#: ../../howto/functional.rst:182 +msgid "" +"I'll start by looking at a Python language feature that's an important " +"foundation for writing functional-style programs: iterators." +msgstr "" + +#: ../../howto/functional.rst:185 +msgid "" +"An iterator is an object representing a stream of data; this object returns " +"the data one element at a time. A Python iterator must support a method " +"called :meth:`~iterator.__next__` that takes no arguments and always returns " +"the next element of the stream. If there are no more elements in the " +"stream, :meth:`~iterator.__next__` must raise the :exc:`StopIteration` " +"exception. Iterators don't have to be finite, though; it's perfectly " +"reasonable to write an iterator that produces an infinite stream of data." +msgstr "" + +#: ../../howto/functional.rst:193 +msgid "" +"The built-in :func:`iter` function takes an arbitrary object and tries to " +"return an iterator that will return the object's contents or elements, " +"raising :exc:`TypeError` if the object doesn't support iteration. Several " +"of Python's built-in data types support iteration, the most common being " +"lists and dictionaries. An object is called :term:`iterable` if you can get " +"an iterator for it." +msgstr "" + +#: ../../howto/functional.rst:200 +msgid "You can experiment with the iteration interface manually:" +msgstr "" + +#: ../../howto/functional.rst:218 +msgid "" +"Python expects iterable objects in several different contexts, the most " +"important being the :keyword:`for` statement. In the statement ``for X in " +"Y``, Y must be an iterator or some object for which :func:`iter` can create " +"an iterator. These two statements are equivalent::" +msgstr "" + +#: ../../howto/functional.rst:224 +msgid "" +"for i in iter(obj):\n" +" print(i)\n" +"\n" +"for i in obj:\n" +" print(i)" +msgstr "" +"for i in iter(obj):\n" +" print(i)\n" +"\n" +"for i in obj:\n" +" print(i)" + +#: ../../howto/functional.rst:230 +msgid "" +"Iterators can be materialized as lists or tuples by using the :func:`list` " +"or :func:`tuple` constructor functions:" +msgstr "" + +#: ../../howto/functional.rst:239 +msgid "" +"Sequence unpacking also supports iterators: if you know an iterator will " +"return N elements, you can unpack them into an N-tuple:" +msgstr "" + +#: ../../howto/functional.rst:248 +msgid "" +"Built-in functions such as :func:`max` and :func:`min` can take a single " +"iterator argument and will return the largest or smallest element. The " +"``\"in\"`` and ``\"not in\"`` operators also support iterators: ``X in " +"iterator`` is true if X is found in the stream returned by the iterator. " +"You'll run into obvious problems if the iterator is infinite; :func:`max`, :" +"func:`min` will never return, and if the element X never appears in the " +"stream, the ``\"in\"`` and ``\"not in\"`` operators won't return either." +msgstr "" + +#: ../../howto/functional.rst:256 +msgid "" +"Note that you can only go forward in an iterator; there's no way to get the " +"previous element, reset the iterator, or make a copy of it. Iterator " +"objects can optionally provide these additional capabilities, but the " +"iterator protocol only specifies the :meth:`~iterator.__next__` method. " +"Functions may therefore consume all of the iterator's output, and if you " +"need to do something different with the same stream, you'll have to create a " +"new iterator." +msgstr "" + +#: ../../howto/functional.rst:266 +msgid "Data Types That Support Iterators" +msgstr "" + +#: ../../howto/functional.rst:268 +msgid "" +"We've already seen how lists and tuples support iterators. In fact, any " +"Python sequence type, such as strings, will automatically support creation " +"of an iterator." +msgstr "" + +#: ../../howto/functional.rst:272 +msgid "" +"Calling :func:`iter` on a dictionary returns an iterator that will loop over " +"the dictionary's keys::" +msgstr "" + +#: ../../howto/functional.rst:275 +msgid "" +">>> m = {'Jan': 1, 'Feb': 2, 'Mar': 3, 'Apr': 4, 'May': 5, 'Jun': 6,\n" +"... 'Jul': 7, 'Aug': 8, 'Sep': 9, 'Oct': 10, 'Nov': 11, 'Dec': 12}\n" +">>> for key in m:\n" +"... print(key, m[key])\n" +"Jan 1\n" +"Feb 2\n" +"Mar 3\n" +"Apr 4\n" +"May 5\n" +"Jun 6\n" +"Jul 7\n" +"Aug 8\n" +"Sep 9\n" +"Oct 10\n" +"Nov 11\n" +"Dec 12" +msgstr "" +">>> m = {'Jan': 1, 'Feb': 2, 'Mar': 3, 'Apr': 4, 'May': 5, 'Jun': 6,\n" +"... 'Jul': 7, 'Aug': 8, 'Sep': 9, 'Oct': 10, 'Nov': 11, 'Dec': 12}\n" +">>> for key in m:\n" +"... print(key, m[key])\n" +"Jan 1\n" +"Feb 2\n" +"Mar 3\n" +"Apr 4\n" +"May 5\n" +"Jun 6\n" +"Jul 7\n" +"Aug 8\n" +"Sep 9\n" +"Oct 10\n" +"Nov 11\n" +"Dec 12" + +#: ../../howto/functional.rst:292 +msgid "" +"Note that starting with Python 3.7, dictionary iteration order is guaranteed " +"to be the same as the insertion order. In earlier versions, the behaviour " +"was unspecified and could vary between implementations." +msgstr "" + +#: ../../howto/functional.rst:296 +msgid "" +"Applying :func:`iter` to a dictionary always loops over the keys, but " +"dictionaries have methods that return other iterators. If you want to " +"iterate over values or key/value pairs, you can explicitly call the :meth:" +"`~dict.values` or :meth:`~dict.items` methods to get an appropriate iterator." +msgstr "" + +#: ../../howto/functional.rst:302 +msgid "" +"The :func:`dict` constructor can accept an iterator that returns a finite " +"stream of ``(key, value)`` tuples:" +msgstr "" + +#: ../../howto/functional.rst:309 +msgid "" +"Files also support iteration by calling the :meth:`~io.TextIOBase.readline` " +"method until there are no more lines in the file. This means you can read " +"each line of a file like this::" +msgstr "" + +#: ../../howto/functional.rst:313 +msgid "" +"for line in file:\n" +" # do something for each line\n" +" ..." +msgstr "" + +#: ../../howto/functional.rst:317 +msgid "" +"Sets can take their contents from an iterable and let you iterate over the " +"set's elements::" +msgstr "" + +#: ../../howto/functional.rst:320 +msgid "" +">>> S = {2, 3, 5, 7, 11, 13}\n" +">>> for i in S:\n" +"... print(i)\n" +"2\n" +"3\n" +"5\n" +"7\n" +"11\n" +"13" +msgstr "" +">>> S = {2, 3, 5, 7, 11, 13}\n" +">>> for i in S:\n" +"... print(i)\n" +"2\n" +"3\n" +"5\n" +"7\n" +"11\n" +"13" + +#: ../../howto/functional.rst:333 +msgid "Generator expressions and list comprehensions" +msgstr "產生器運算式與串列綜合運算式" + +#: ../../howto/functional.rst:335 +msgid "" +"Two common operations on an iterator's output are 1) performing some " +"operation for every element, 2) selecting a subset of elements that meet " +"some condition. For example, given a list of strings, you might want to " +"strip off trailing whitespace from each line or extract all the strings " +"containing a given substring." +msgstr "" + +#: ../../howto/functional.rst:341 +msgid "" +"List comprehensions and generator expressions (short form: \"listcomps\" and " +"\"genexps\") are a concise notation for such operations, borrowed from the " +"functional programming language Haskell (https://www.haskell.org/). You can " +"strip all the whitespace from a stream of strings with the following code::" +msgstr "" + +#: ../../howto/functional.rst:346 +msgid "" +">>> line_list = [' line 1\\n', 'line 2 \\n', ' \\n', '']\n" +"\n" +">>> # Generator expression -- returns iterator\n" +">>> stripped_iter = (line.strip() for line in line_list)\n" +"\n" +">>> # List comprehension -- returns list\n" +">>> stripped_list = [line.strip() for line in line_list]" +msgstr "" +">>> line_list = [' line 1\\n', 'line 2 \\n', ' \\n', '']\n" +"\n" +">>> # 產生器運算式 -- 回傳疊代器\n" +">>> stripped_iter = (line.strip() for line in line_list)\n" +"\n" +">>> # 串列綜合運算式 -- 回傳串列\n" +">>> stripped_list = [line.strip() for line in line_list]" + +#: ../../howto/functional.rst:354 +msgid "" +"You can select only certain elements by adding an ``\"if\"`` condition::" +msgstr "" + +#: ../../howto/functional.rst:356 +msgid "" +">>> stripped_list = [line.strip() for line in line_list\n" +"... if line != \"\"]" +msgstr "" +">>> stripped_list = [line.strip() for line in line_list\n" +"... if line != \"\"]" + +#: ../../howto/functional.rst:359 +msgid "" +"With a list comprehension, you get back a Python list; ``stripped_list`` is " +"a list containing the resulting lines, not an iterator. Generator " +"expressions return an iterator that computes the values as necessary, not " +"needing to materialize all the values at once. This means that list " +"comprehensions aren't useful if you're working with iterators that return an " +"infinite stream or a very large amount of data. Generator expressions are " +"preferable in these situations." +msgstr "" + +#: ../../howto/functional.rst:366 +msgid "" +"Generator expressions are surrounded by parentheses (\"()\") and list " +"comprehensions are surrounded by square brackets (\"[]\"). Generator " +"expressions have the form::" +msgstr "" + +#: ../../howto/functional.rst:370 +msgid "" +"( expression for expr in sequence1\n" +" if condition1\n" +" for expr2 in sequence2\n" +" if condition2\n" +" for expr3 in sequence3\n" +" ...\n" +" if condition3\n" +" for exprN in sequenceN\n" +" if conditionN )" +msgstr "" +"( expression for expr in sequence1\n" +" if condition1\n" +" for expr2 in sequence2\n" +" if condition2\n" +" for expr3 in sequence3\n" +" ...\n" +" if condition3\n" +" for exprN in sequenceN\n" +" if conditionN )" + +#: ../../howto/functional.rst:380 +msgid "" +"Again, for a list comprehension only the outside brackets are different " +"(square brackets instead of parentheses)." +msgstr "" + +#: ../../howto/functional.rst:383 +msgid "" +"The elements of the generated output will be the successive values of " +"``expression``. The ``if`` clauses are all optional; if present, " +"``expression`` is only evaluated and added to the result when ``condition`` " +"is true." +msgstr "" + +#: ../../howto/functional.rst:387 +msgid "" +"Generator expressions always have to be written inside parentheses, but the " +"parentheses signalling a function call also count. If you want to create an " +"iterator that will be immediately passed to a function you can write::" +msgstr "" + +#: ../../howto/functional.rst:391 +msgid "obj_total = sum(obj.count for obj in list_all_objects())" +msgstr "obj_total = sum(obj.count for obj in list_all_objects())" + +#: ../../howto/functional.rst:393 +msgid "" +"The ``for...in`` clauses contain the sequences to be iterated over. The " +"sequences do not have to be the same length, because they are iterated over " +"from left to right, **not** in parallel. For each element in ``sequence1``, " +"``sequence2`` is looped over from the beginning. ``sequence3`` is then " +"looped over for each resulting pair of elements from ``sequence1`` and " +"``sequence2``." +msgstr "" + +#: ../../howto/functional.rst:399 +msgid "" +"To put it another way, a list comprehension or generator expression is " +"equivalent to the following Python code::" +msgstr "" + +#: ../../howto/functional.rst:402 +msgid "" +"for expr1 in sequence1:\n" +" if not (condition1):\n" +" continue # Skip this element\n" +" for expr2 in sequence2:\n" +" if not (condition2):\n" +" continue # Skip this element\n" +" ...\n" +" for exprN in sequenceN:\n" +" if not (conditionN):\n" +" continue # Skip this element\n" +"\n" +" # Output the value of\n" +" # the expression." +msgstr "" + +#: ../../howto/functional.rst:416 +msgid "" +"This means that when there are multiple ``for...in`` clauses but no ``if`` " +"clauses, the length of the resulting output will be equal to the product of " +"the lengths of all the sequences. If you have two lists of length 3, the " +"output list is 9 elements long:" +msgstr "" + +#: ../../howto/functional.rst:428 +msgid "" +"To avoid introducing an ambiguity into Python's grammar, if ``expression`` " +"is creating a tuple, it must be surrounded with parentheses. The first list " +"comprehension below is a syntax error, while the second one is correct::" +msgstr "" + +#: ../../howto/functional.rst:432 +msgid "" +"# Syntax error\n" +"[x, y for x in seq1 for y in seq2]\n" +"# Correct\n" +"[(x, y) for x in seq1 for y in seq2]" +msgstr "" +"# 語法錯誤\n" +"[x, y for x in seq1 for y in seq2]\n" +"# 正確\n" +"[(x, y) for x in seq1 for y in seq2]" + +#: ../../howto/functional.rst:439 +msgid "Generators" +msgstr "產生器" + +#: ../../howto/functional.rst:441 +msgid "" +"Generators are a special class of functions that simplify the task of " +"writing iterators. Regular functions compute a value and return it, but " +"generators return an iterator that returns a stream of values." +msgstr "" + +#: ../../howto/functional.rst:445 +msgid "" +"You're doubtless familiar with how regular function calls work in Python or " +"C. When you call a function, it gets a private namespace where its local " +"variables are created. When the function reaches a ``return`` statement, " +"the local variables are destroyed and the value is returned to the caller. " +"A later call to the same function creates a new private namespace and a " +"fresh set of local variables. But, what if the local variables weren't " +"thrown away on exiting a function? What if you could later resume the " +"function where it left off? This is what generators provide; they can be " +"thought of as resumable functions." +msgstr "" + +#: ../../howto/functional.rst:454 +msgid "Here's the simplest example of a generator function:" +msgstr "以下是最簡單的產生器函式範例：" + +#: ../../howto/functional.rst:460 +msgid "" +"Any function containing a :keyword:`yield` keyword is a generator function; " +"this is detected by Python's :term:`bytecode` compiler which compiles the " +"function specially as a result." +msgstr "" + +#: ../../howto/functional.rst:464 +msgid "" +"When you call a generator function, it doesn't return a single value; " +"instead it returns a generator object that supports the iterator protocol. " +"On executing the ``yield`` expression, the generator outputs the value of " +"``i``, similar to a ``return`` statement. The big difference between " +"``yield`` and a ``return`` statement is that on reaching a ``yield`` the " +"generator's state of execution is suspended and local variables are " +"preserved. On the next call to the generator's :meth:`~generator.__next__` " +"method, the function will resume executing." +msgstr "" + +#: ../../howto/functional.rst:473 +msgid "Here's a sample usage of the ``generate_ints()`` generator:" +msgstr "以下是 ``generate_ints()`` 產生器的使用範例：" + +#: ../../howto/functional.rst:490 +msgid "" +"You could equally write ``for i in generate_ints(5)``, or ``a, b, c = " +"generate_ints(3)``." +msgstr "" + +#: ../../howto/functional.rst:493 +msgid "" +"Inside a generator function, ``return value`` causes " +"``StopIteration(value)`` to be raised from the :meth:`~generator.__next__` " +"method. Once this happens, or the bottom of the function is reached, the " +"procession of values ends and the generator cannot yield any further values." +msgstr "" + +#: ../../howto/functional.rst:498 +msgid "" +"You could achieve the effect of generators manually by writing your own " +"class and storing all the local variables of the generator as instance " +"variables. For example, returning a list of integers could be done by " +"setting ``self.count`` to 0, and having the :meth:`~iterator.__next__` " +"method increment ``self.count`` and return it. However, for a moderately " +"complicated generator, writing a corresponding class can be much messier." +msgstr "" + +#: ../../howto/functional.rst:506 +msgid "" +"The test suite included with Python's library, :source:`Lib/test/" +"test_generators.py`, contains a number of more interesting examples. Here's " +"one generator that implements an in-order traversal of a tree using " +"generators recursively. ::" +msgstr "" + +#: ../../howto/functional.rst:511 +msgid "" +"# A recursive generator that generates Tree leaves in in-order.\n" +"def inorder(t):\n" +" if t:\n" +" for x in inorder(t.left):\n" +" yield x\n" +"\n" +" yield t.label\n" +"\n" +" for x in inorder(t.right):\n" +" yield x" +msgstr "" + +#: ../../howto/functional.rst:522 +msgid "" +"Two other examples in ``test_generators.py`` produce solutions for the N-" +"Queens problem (placing N queens on an NxN chess board so that no queen " +"threatens another) and the Knight's Tour (finding a route that takes a " +"knight to every square of an NxN chessboard without visiting any square " +"twice)." +msgstr "" + +#: ../../howto/functional.rst:530 +msgid "Passing values into a generator" +msgstr "" + +#: ../../howto/functional.rst:532 +msgid "" +"In Python 2.4 and earlier, generators only produced output. Once a " +"generator's code was invoked to create an iterator, there was no way to pass " +"any new information into the function when its execution is resumed. You " +"could hack together this ability by making the generator look at a global " +"variable or by passing in some mutable object that callers then modify, but " +"these approaches are messy." +msgstr "" + +#: ../../howto/functional.rst:539 +msgid "" +"In Python 2.5 there's a simple way to pass values into a generator. :keyword:" +"`yield` became an expression, returning a value that can be assigned to a " +"variable or otherwise operated on::" +msgstr "" + +#: ../../howto/functional.rst:543 +msgid "val = (yield i)" +msgstr "val = (yield i)" + +#: ../../howto/functional.rst:545 +msgid "" +"I recommend that you **always** put parentheses around a ``yield`` " +"expression when you're doing something with the returned value, as in the " +"above example. The parentheses aren't always necessary, but it's easier to " +"always add them instead of having to remember when they're needed." +msgstr "" + +#: ../../howto/functional.rst:550 +msgid "" +"(:pep:`342` explains the exact rules, which are that a ``yield``-expression " +"must always be parenthesized except when it occurs at the top-level " +"expression on the right-hand side of an assignment. This means you can " +"write ``val = yield i`` but have to use parentheses when there's an " +"operation, as in ``val = (yield i) + 12``.)" +msgstr "" + +#: ../../howto/functional.rst:556 +msgid "" +"Values are sent into a generator by calling its :meth:`send(value) " +"` method. This method resumes the generator's code and the " +"``yield`` expression returns the specified value. If the regular :meth:" +"`~generator.__next__` method is called, the ``yield`` returns ``None``." +msgstr "" + +#: ../../howto/functional.rst:561 +msgid "" +"Here's a simple counter that increments by 1 and allows changing the value " +"of the internal counter." +msgstr "" + +#: ../../howto/functional.rst:564 +msgid "" +"def counter(maximum):\n" +" i = 0\n" +" while i < maximum:\n" +" val = (yield i)\n" +" # If value provided, change counter\n" +" if val is not None:\n" +" i = val\n" +" else:\n" +" i += 1" +msgstr "" +"def counter(maximum):\n" +" i = 0\n" +" while i < maximum:\n" +" val = (yield i)\n" +" # 如有提供值則改變計數器\n" +" if val is not None:\n" +" i = val\n" +" else:\n" +" i += 1" + +#: ../../howto/functional.rst:576 +msgid "And here's an example of changing the counter:" +msgstr "" + +#: ../../howto/functional.rst:593 +msgid "" +"Because ``yield`` will often be returning ``None``, you should always check " +"for this case. Don't just use its value in expressions unless you're sure " +"that the :meth:`~generator.send` method will be the only method used to " +"resume your generator function." +msgstr "" + +#: ../../howto/functional.rst:598 +msgid "" +"In addition to :meth:`~generator.send`, there are two other methods on " +"generators:" +msgstr "" + +#: ../../howto/functional.rst:601 +msgid "" +":meth:`throw(value) ` is used to raise an exception inside " +"the generator; the exception is raised by the ``yield`` expression where the " +"generator's execution is paused." +msgstr "" + +#: ../../howto/functional.rst:605 +msgid "" +":meth:`~generator.close` sends a :exc:`GeneratorExit` exception to the " +"generator to terminate the iteration. On receiving this exception, the " +"generator's code must either raise :exc:`GeneratorExit` or :exc:" +"`StopIteration`; catching the exception and doing anything else is illegal " +"and will trigger a :exc:`RuntimeError`. :meth:`~generator.close` will also " +"be called by Python's garbage collector when the generator is garbage-" +"collected." +msgstr "" + +#: ../../howto/functional.rst:613 +msgid "" +"If you need to run cleanup code when a :exc:`GeneratorExit` occurs, I " +"suggest using a ``try: ... finally:`` suite instead of catching :exc:" +"`GeneratorExit`." +msgstr "" + +#: ../../howto/functional.rst:616 +msgid "" +"The cumulative effect of these changes is to turn generators from one-way " +"producers of information into both producers and consumers." +msgstr "" + +#: ../../howto/functional.rst:619 +msgid "" +"Generators also become **coroutines**, a more generalized form of " +"subroutines. Subroutines are entered at one point and exited at another " +"point (the top of the function, and a ``return`` statement), but coroutines " +"can be entered, exited, and resumed at many different points (the ``yield`` " +"statements)." +msgstr "" + +#: ../../howto/functional.rst:626 +msgid "Built-in functions" +msgstr "內建函式" + +#: ../../howto/functional.rst:628 +msgid "" +"Let's look in more detail at built-in functions often used with iterators." +msgstr "" + +#: ../../howto/functional.rst:630 +msgid "" +"Two of Python's built-in functions, :func:`map` and :func:`filter` duplicate " +"the features of generator expressions:" +msgstr "" + +#: ../../howto/functional.rst:633 +msgid "" +":func:`map(f, iterA, iterB, ...) ` returns an iterator over the sequence" +msgstr ":func:`map(f, iterA, iterB, ...) ` 回傳一個元素為序列的疊代器" + +#: ../../howto/functional.rst:634 +msgid "" +"``f(iterA[0], iterB[0]), f(iterA[1], iterB[1]), f(iterA[2], iterB[2]), ...``." +msgstr "" +"``f(iterA[0], iterB[0]), f(iterA[1], iterB[1]), f(iterA[2], iterB[2]), ..." +"``。" + +#: ../../howto/functional.rst:644 +msgid "You can of course achieve the same effect with a list comprehension." +msgstr "" + +#: ../../howto/functional.rst:646 +msgid "" +":func:`filter(predicate, iter) ` returns an iterator over all the " +"sequence elements that meet a certain condition, and is similarly duplicated " +"by list comprehensions. A **predicate** is a function that returns the " +"truth value of some condition; for use with :func:`filter`, the predicate " +"must take a single value." +msgstr "" + +#: ../../howto/functional.rst:659 +msgid "This can also be written as a list comprehension:" +msgstr "" + +#: ../../howto/functional.rst:665 +msgid "" +":func:`enumerate(iter, start=0) ` counts off the elements in the " +"iterable returning 2-tuples containing the count (from *start*) and each " +"element. ::" +msgstr "" + +#: ../../howto/functional.rst:669 +msgid "" +">>> for item in enumerate(['subject', 'verb', 'object']):\n" +"... print(item)\n" +"(0, 'subject')\n" +"(1, 'verb')\n" +"(2, 'object')" +msgstr "" +">>> for item in enumerate(['subject', 'verb', 'object']):\n" +"... print(item)\n" +"(0, 'subject')\n" +"(1, 'verb')\n" +"(2, 'object')" + +#: ../../howto/functional.rst:675 +msgid "" +":func:`enumerate` is often used when looping through a list and recording " +"the indexes at which certain conditions are met::" +msgstr "" + +#: ../../howto/functional.rst:678 +msgid "" +"f = open('data.txt', 'r')\n" +"for i, line in enumerate(f):\n" +" if line.strip() == '':\n" +" print('Blank line at line #%i' % i)" +msgstr "" +"f = open('data.txt', 'r')\n" +"for i, line in enumerate(f):\n" +" if line.strip() == '':\n" +" print('Blank line at line #%i' % i)" + +#: ../../howto/functional.rst:683 +msgid "" +":func:`sorted(iterable, key=None, reverse=False) ` collects all the " +"elements of the iterable into a list, sorts the list, and returns the sorted " +"result. The *key* and *reverse* arguments are passed through to the " +"constructed list's :meth:`~list.sort` method. ::" +msgstr "" + +#: ../../howto/functional.rst:688 +msgid "" +">>> import random\n" +">>> # Generate 8 random numbers between [0, 10000)\n" +">>> rand_list = random.sample(range(10000), 8)\n" +">>> rand_list\n" +"[769, 7953, 9828, 6431, 8442, 9878, 6213, 2207]\n" +">>> sorted(rand_list)\n" +"[769, 2207, 6213, 6431, 7953, 8442, 9828, 9878]\n" +">>> sorted(rand_list, reverse=True)\n" +"[9878, 9828, 8442, 7953, 6431, 6213, 2207, 769]" +msgstr "" +">>> import random\n" +">>> # 產生 8 個範圍在 [0, 10000) 的隨機數字\n" +">>> rand_list = random.sample(range(10000), 8)\n" +">>> rand_list\n" +"[769, 7953, 9828, 6431, 8442, 9878, 6213, 2207]\n" +">>> sorted(rand_list)\n" +"[769, 2207, 6213, 6431, 7953, 8442, 9828, 9878]\n" +">>> sorted(rand_list, reverse=True)\n" +"[9878, 9828, 8442, 7953, 6431, 6213, 2207, 769]" + +#: ../../howto/functional.rst:698 +msgid "" +"(For a more detailed discussion of sorting, see the :ref:`sortinghowto`.)" +msgstr "" + +#: ../../howto/functional.rst:701 +msgid "" +"The :func:`any(iter) ` and :func:`all(iter) ` built-ins look at " +"the truth values of an iterable's contents. :func:`any` returns ``True`` if " +"any element in the iterable is a true value, and :func:`all` returns " +"``True`` if all of the elements are true values:" +msgstr "" + +#: ../../howto/functional.rst:720 +msgid "" +":func:`zip(iterA, iterB, ...) ` takes one element from each iterable " +"and returns them in a tuple::" +msgstr "" + +#: ../../howto/functional.rst:723 +msgid "" +"zip(['a', 'b', 'c'], (1, 2, 3)) =>\n" +" ('a', 1), ('b', 2), ('c', 3)" +msgstr "" +"zip(['a', 'b', 'c'], (1, 2, 3)) =>\n" +" ('a', 1), ('b', 2), ('c', 3)" + +#: ../../howto/functional.rst:726 +msgid "" +"It doesn't construct an in-memory list and exhaust all the input iterators " +"before returning; instead tuples are constructed and returned only if " +"they're requested. (The technical term for this behaviour is `lazy " +"evaluation `__.)" +msgstr "" + +#: ../../howto/functional.rst:731 +msgid "" +"This iterator is intended to be used with iterables that are all of the same " +"length. If the iterables are of different lengths, the resulting stream " +"will be the same length as the shortest iterable. ::" +msgstr "" + +#: ../../howto/functional.rst:735 +msgid "" +"zip(['a', 'b'], (1, 2, 3)) =>\n" +" ('a', 1), ('b', 2)" +msgstr "" +"zip(['a', 'b'], (1, 2, 3)) =>\n" +" ('a', 1), ('b', 2)" + +#: ../../howto/functional.rst:738 +msgid "" +"You should avoid doing this, though, because an element may be taken from " +"the longer iterators and discarded. This means you can't go on to use the " +"iterators further because you risk skipping a discarded element." +msgstr "" + +#: ../../howto/functional.rst:744 +msgid "The itertools module" +msgstr "itertools 模組" + +#: ../../howto/functional.rst:746 +msgid "" +"The :mod:`itertools` module contains a number of commonly used iterators as " +"well as functions for combining several iterators. This section will " +"introduce the module's contents by showing small examples." +msgstr "" + +#: ../../howto/functional.rst:750 +msgid "The module's functions fall into a few broad classes:" +msgstr "" + +#: ../../howto/functional.rst:752 +msgid "Functions that create a new iterator based on an existing iterator." +msgstr "" + +#: ../../howto/functional.rst:753 +msgid "Functions for treating an iterator's elements as function arguments." +msgstr "" + +#: ../../howto/functional.rst:754 +msgid "Functions for selecting portions of an iterator's output." +msgstr "" + +#: ../../howto/functional.rst:755 +msgid "A function for grouping an iterator's output." +msgstr "" + +#: ../../howto/functional.rst:758 +msgid "Creating new iterators" +msgstr "建立新的疊代器" + +#: ../../howto/functional.rst:760 +msgid "" +":func:`itertools.count(start, step) ` returns an infinite " +"stream of evenly spaced values. You can optionally supply the starting " +"number, which defaults to 0, and the interval between numbers, which " +"defaults to 1::" +msgstr "" + +#: ../../howto/functional.rst:764 +msgid "" +"itertools.count() =>\n" +" 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, ...\n" +"itertools.count(10) =>\n" +" 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, ...\n" +"itertools.count(10, 5) =>\n" +" 10, 15, 20, 25, 30, 35, 40, 45, 50, 55, ..." +msgstr "" +"itertools.count() =>\n" +" 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, ...\n" +"itertools.count(10) =>\n" +" 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, ...\n" +"itertools.count(10, 5) =>\n" +" 10, 15, 20, 25, 30, 35, 40, 45, 50, 55, ..." + +#: ../../howto/functional.rst:771 +msgid "" +":func:`itertools.cycle(iter) ` saves a copy of the contents " +"of a provided iterable and returns a new iterator that returns its elements " +"from first to last. The new iterator will repeat these elements " +"infinitely. ::" +msgstr "" + +#: ../../howto/functional.rst:775 +msgid "" +"itertools.cycle([1, 2, 3, 4, 5]) =>\n" +" 1, 2, 3, 4, 5, 1, 2, 3, 4, 5, ..." +msgstr "" +"itertools.cycle([1, 2, 3, 4, 5]) =>\n" +" 1, 2, 3, 4, 5, 1, 2, 3, 4, 5, ..." + +#: ../../howto/functional.rst:778 +msgid "" +":func:`itertools.repeat(elem, [n]) ` returns the provided " +"element *n* times, or returns the element endlessly if *n* is not " +"provided. ::" +msgstr "" + +#: ../../howto/functional.rst:781 +msgid "" +"itertools.repeat('abc') =>\n" +" abc, abc, abc, abc, abc, abc, abc, abc, abc, abc, ...\n" +"itertools.repeat('abc', 5) =>\n" +" abc, abc, abc, abc, abc" +msgstr "" +"itertools.repeat('abc') =>\n" +" abc, abc, abc, abc, abc, abc, abc, abc, abc, abc, ...\n" +"itertools.repeat('abc', 5) =>\n" +" abc, abc, abc, abc, abc" + +#: ../../howto/functional.rst:786 +msgid "" +":func:`itertools.chain(iterA, iterB, ...) ` takes an " +"arbitrary number of iterables as input, and returns all the elements of the " +"first iterator, then all the elements of the second, and so on, until all of " +"the iterables have been exhausted. ::" +msgstr "" + +#: ../../howto/functional.rst:791 +msgid "" +"itertools.chain(['a', 'b', 'c'], (1, 2, 3)) =>\n" +" a, b, c, 1, 2, 3" +msgstr "" +"itertools.chain(['a', 'b', 'c'], (1, 2, 3)) =>\n" +" a, b, c, 1, 2, 3" + +#: ../../howto/functional.rst:794 +msgid "" +":func:`itertools.islice(iter, [start], stop, [step]) ` " +"returns a stream that's a slice of the iterator. With a single *stop* " +"argument, it will return the first *stop* elements. If you supply a " +"starting index, you'll get *stop-start* elements, and if you supply a value " +"for *step*, elements will be skipped accordingly. Unlike Python's string " +"and list slicing, you can't use negative values for *start*, *stop*, or " +"*step*. ::" +msgstr "" + +#: ../../howto/functional.rst:801 +msgid "" +"itertools.islice(range(10), 8) =>\n" +" 0, 1, 2, 3, 4, 5, 6, 7\n" +"itertools.islice(range(10), 2, 8) =>\n" +" 2, 3, 4, 5, 6, 7\n" +"itertools.islice(range(10), 2, 8, 2) =>\n" +" 2, 4, 6" +msgstr "" +"itertools.islice(range(10), 8) =>\n" +" 0, 1, 2, 3, 4, 5, 6, 7\n" +"itertools.islice(range(10), 2, 8) =>\n" +" 2, 3, 4, 5, 6, 7\n" +"itertools.islice(range(10), 2, 8, 2) =>\n" +" 2, 4, 6" + +#: ../../howto/functional.rst:808 +msgid "" +":func:`itertools.tee(iter, [n]) ` replicates an iterator; it " +"returns *n* independent iterators that will all return the contents of the " +"source iterator. If you don't supply a value for *n*, the default is 2. " +"Replicating iterators requires saving some of the contents of the source " +"iterator, so this can consume significant memory if the iterator is large " +"and one of the new iterators is consumed more than the others. ::" +msgstr "" + +#: ../../howto/functional.rst:816 +msgid "" +"itertools.tee( itertools.count() ) =>\n" +" iterA, iterB\n" +"\n" +"where iterA ->\n" +" 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, ...\n" +"\n" +"and iterB ->\n" +" 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, ..." +msgstr "" +"itertools.tee( itertools.count() ) =>\n" +" iterA, iterB\n" +"\n" +"where iterA ->\n" +" 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, ...\n" +"\n" +"and iterB ->\n" +" 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, ..." + +#: ../../howto/functional.rst:827 +msgid "Calling functions on elements" +msgstr "" + +#: ../../howto/functional.rst:829 +msgid "" +"The :mod:`operator` module contains a set of functions corresponding to " +"Python's operators. Some examples are :func:`operator.add(a, b) ` (adds two values), :func:`operator.ne(a, b) ` (same as " +"``a != b``), and :func:`operator.attrgetter('id') ` " +"(returns a callable that fetches the ``.id`` attribute)." +msgstr "" + +#: ../../howto/functional.rst:835 +msgid "" +":func:`itertools.starmap(func, iter) ` assumes that the " +"iterable will return a stream of tuples, and calls *func* using these tuples " +"as the arguments::" +msgstr "" + +#: ../../howto/functional.rst:839 +msgid "" +"itertools.starmap(os.path.join,\n" +" [('/bin', 'python'), ('/usr', 'bin', 'java'),\n" +" ('/usr', 'bin', 'perl'), ('/usr', 'bin', 'ruby')])\n" +"=>\n" +" /bin/python, /usr/bin/java, /usr/bin/perl, /usr/bin/ruby" +msgstr "" +"itertools.starmap(os.path.join,\n" +" [('/bin', 'python'), ('/usr', 'bin', 'java'),\n" +" ('/usr', 'bin', 'perl'), ('/usr', 'bin', 'ruby')])\n" +"=>\n" +" /bin/python, /usr/bin/java, /usr/bin/perl, /usr/bin/ruby" + +#: ../../howto/functional.rst:847 +msgid "Selecting elements" +msgstr "" + +#: ../../howto/functional.rst:849 +msgid "" +"Another group of functions chooses a subset of an iterator's elements based " +"on a predicate." +msgstr "" + +#: ../../howto/functional.rst:852 +msgid "" +":func:`itertools.filterfalse(predicate, iter) ` is " +"the opposite of :func:`filter`, returning all elements for which the " +"predicate returns false::" +msgstr "" + +#: ../../howto/functional.rst:856 +msgid "" +"itertools.filterfalse(is_even, itertools.count()) =>\n" +" 1, 3, 5, 7, 9, 11, 13, 15, ..." +msgstr "" +"itertools.filterfalse(is_even, itertools.count()) =>\n" +" 1, 3, 5, 7, 9, 11, 13, 15, ..." + +#: ../../howto/functional.rst:859 +msgid "" +":func:`itertools.takewhile(predicate, iter) ` returns " +"elements for as long as the predicate returns true. Once the predicate " +"returns false, the iterator will signal the end of its results. ::" +msgstr "" + +#: ../../howto/functional.rst:863 +msgid "" +"def less_than_10(x):\n" +" return x < 10\n" +"\n" +"itertools.takewhile(less_than_10, itertools.count()) =>\n" +" 0, 1, 2, 3, 4, 5, 6, 7, 8, 9\n" +"\n" +"itertools.takewhile(is_even, itertools.count()) =>\n" +" 0" +msgstr "" +"def less_than_10(x):\n" +" return x < 10\n" +"\n" +"itertools.takewhile(less_than_10, itertools.count()) =>\n" +" 0, 1, 2, 3, 4, 5, 6, 7, 8, 9\n" +"\n" +"itertools.takewhile(is_even, itertools.count()) =>\n" +" 0" + +#: ../../howto/functional.rst:872 +msgid "" +":func:`itertools.dropwhile(predicate, iter) ` discards " +"elements while the predicate returns true, and then returns the rest of the " +"iterable's results. ::" +msgstr "" + +#: ../../howto/functional.rst:876 +msgid "" +"itertools.dropwhile(less_than_10, itertools.count()) =>\n" +" 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, ...\n" +"\n" +"itertools.dropwhile(is_even, itertools.count()) =>\n" +" 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, ..." +msgstr "" +"itertools.dropwhile(less_than_10, itertools.count()) =>\n" +" 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, ...\n" +"\n" +"itertools.dropwhile(is_even, itertools.count()) =>\n" +" 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, ..." + +#: ../../howto/functional.rst:882 +msgid "" +":func:`itertools.compress(data, selectors) ` takes two " +"iterators and returns only those elements of *data* for which the " +"corresponding element of *selectors* is true, stopping whenever either one " +"is exhausted::" +msgstr "" + +#: ../../howto/functional.rst:886 +msgid "" +"itertools.compress([1, 2, 3, 4, 5], [True, True, False, False, True]) =>\n" +" 1, 2, 5" +msgstr "" +"itertools.compress([1, 2, 3, 4, 5], [True, True, False, False, True]) =>\n" +" 1, 2, 5" + +#: ../../howto/functional.rst:891 +msgid "Combinatoric functions" +msgstr "" + +#: ../../howto/functional.rst:893 +msgid "" +"The :func:`itertools.combinations(iterable, r) ` " +"returns an iterator giving all possible *r*-tuple combinations of the " +"elements contained in *iterable*. ::" +msgstr "" + +#: ../../howto/functional.rst:897 +msgid "" +"itertools.combinations([1, 2, 3, 4, 5], 2) =>\n" +" (1, 2), (1, 3), (1, 4), (1, 5),\n" +" (2, 3), (2, 4), (2, 5),\n" +" (3, 4), (3, 5),\n" +" (4, 5)\n" +"\n" +"itertools.combinations([1, 2, 3, 4, 5], 3) =>\n" +" (1, 2, 3), (1, 2, 4), (1, 2, 5), (1, 3, 4), (1, 3, 5), (1, 4, 5),\n" +" (2, 3, 4), (2, 3, 5), (2, 4, 5),\n" +" (3, 4, 5)" +msgstr "" +"itertools.combinations([1, 2, 3, 4, 5], 2) =>\n" +" (1, 2), (1, 3), (1, 4), (1, 5),\n" +" (2, 3), (2, 4), (2, 5),\n" +" (3, 4), (3, 5),\n" +" (4, 5)\n" +"\n" +"itertools.combinations([1, 2, 3, 4, 5], 3) =>\n" +" (1, 2, 3), (1, 2, 4), (1, 2, 5), (1, 3, 4), (1, 3, 5), (1, 4, 5),\n" +" (2, 3, 4), (2, 3, 5), (2, 4, 5),\n" +" (3, 4, 5)" + +#: ../../howto/functional.rst:908 +msgid "" +"The elements within each tuple remain in the same order as *iterable* " +"returned them. For example, the number 1 is always before 2, 3, 4, or 5 in " +"the examples above. A similar function, :func:`itertools." +"permutations(iterable, r=None) `, removes this " +"constraint on the order, returning all possible arrangements of length *r*::" +msgstr "" + +#: ../../howto/functional.rst:915 +msgid "" +"itertools.permutations([1, 2, 3, 4, 5], 2) =>\n" +" (1, 2), (1, 3), (1, 4), (1, 5),\n" +" (2, 1), (2, 3), (2, 4), (2, 5),\n" +" (3, 1), (3, 2), (3, 4), (3, 5),\n" +" (4, 1), (4, 2), (4, 3), (4, 5),\n" +" (5, 1), (5, 2), (5, 3), (5, 4)\n" +"\n" +"itertools.permutations([1, 2, 3, 4, 5]) =>\n" +" (1, 2, 3, 4, 5), (1, 2, 3, 5, 4), (1, 2, 4, 3, 5),\n" +" ...\n" +" (5, 4, 3, 2, 1)" +msgstr "" +"itertools.permutations([1, 2, 3, 4, 5], 2) =>\n" +" (1, 2), (1, 3), (1, 4), (1, 5),\n" +" (2, 1), (2, 3), (2, 4), (2, 5),\n" +" (3, 1), (3, 2), (3, 4), (3, 5),\n" +" (4, 1), (4, 2), (4, 3), (4, 5),\n" +" (5, 1), (5, 2), (5, 3), (5, 4)\n" +"\n" +"itertools.permutations([1, 2, 3, 4, 5]) =>\n" +" (1, 2, 3, 4, 5), (1, 2, 3, 5, 4), (1, 2, 4, 3, 5),\n" +" ...\n" +" (5, 4, 3, 2, 1)" + +#: ../../howto/functional.rst:927 +msgid "" +"If you don't supply a value for *r* the length of the iterable is used, " +"meaning that all the elements are permuted." +msgstr "" + +#: ../../howto/functional.rst:930 +msgid "" +"Note that these functions produce all of the possible combinations by " +"position and don't require that the contents of *iterable* are unique::" +msgstr "" + +#: ../../howto/functional.rst:933 +msgid "" +"itertools.permutations('aba', 3) =>\n" +" ('a', 'b', 'a'), ('a', 'a', 'b'), ('b', 'a', 'a'),\n" +" ('b', 'a', 'a'), ('a', 'a', 'b'), ('a', 'b', 'a')" +msgstr "" +"itertools.permutations('aba', 3) =>\n" +" ('a', 'b', 'a'), ('a', 'a', 'b'), ('b', 'a', 'a'),\n" +" ('b', 'a', 'a'), ('a', 'a', 'b'), ('a', 'b', 'a')" + +#: ../../howto/functional.rst:937 +msgid "" +"The identical tuple ``('a', 'a', 'b')`` occurs twice, but the two 'a' " +"strings came from different positions." +msgstr "" + +#: ../../howto/functional.rst:940 +msgid "" +"The :func:`itertools.combinations_with_replacement(iterable, r) ` function relaxes a different constraint: " +"elements can be repeated within a single tuple. Conceptually an element is " +"selected for the first position of each tuple and then is replaced before " +"the second element is selected. ::" +msgstr "" + +#: ../../howto/functional.rst:946 +msgid "" +"itertools.combinations_with_replacement([1, 2, 3, 4, 5], 2) =>\n" +" (1, 1), (1, 2), (1, 3), (1, 4), (1, 5),\n" +" (2, 2), (2, 3), (2, 4), (2, 5),\n" +" (3, 3), (3, 4), (3, 5),\n" +" (4, 4), (4, 5),\n" +" (5, 5)" +msgstr "" +"itertools.combinations_with_replacement([1, 2, 3, 4, 5], 2) =>\n" +" (1, 1), (1, 2), (1, 3), (1, 4), (1, 5),\n" +" (2, 2), (2, 3), (2, 4), (2, 5),\n" +" (3, 3), (3, 4), (3, 5),\n" +" (4, 4), (4, 5),\n" +" (5, 5)" + +#: ../../howto/functional.rst:955 +msgid "Grouping elements" +msgstr "" + +#: ../../howto/functional.rst:957 +msgid "" +"The last function I'll discuss, :func:`itertools.groupby(iter, " +"key_func=None) `, is the most complicated. " +"``key_func(elem)`` is a function that can compute a key value for each " +"element returned by the iterable. If you don't supply a key function, the " +"key is simply each element itself." +msgstr "" + +#: ../../howto/functional.rst:962 +msgid "" +":func:`~itertools.groupby` collects all the consecutive elements from the " +"underlying iterable that have the same key value, and returns a stream of 2-" +"tuples containing a key value and an iterator for the elements with that key." +msgstr "" + +#: ../../howto/functional.rst:968 +msgid "" +"city_list = [('Decatur', 'AL'), ('Huntsville', 'AL'), ('Selma', 'AL'),\n" +" ('Anchorage', 'AK'), ('Nome', 'AK'),\n" +" ('Flagstaff', 'AZ'), ('Phoenix', 'AZ'), ('Tucson', 'AZ'),\n" +" ...\n" +" ]\n" +"\n" +"def get_state(city_state):\n" +" return city_state[1]\n" +"\n" +"itertools.groupby(city_list, get_state) =>\n" +" ('AL', iterator-1),\n" +" ('AK', iterator-2),\n" +" ('AZ', iterator-3), ...\n" +"\n" +"where\n" +"iterator-1 =>\n" +" ('Decatur', 'AL'), ('Huntsville', 'AL'), ('Selma', 'AL')\n" +"iterator-2 =>\n" +" ('Anchorage', 'AK'), ('Nome', 'AK')\n" +"iterator-3 =>\n" +" ('Flagstaff', 'AZ'), ('Phoenix', 'AZ'), ('Tucson', 'AZ')" +msgstr "" +"city_list = [('Decatur', 'AL'), ('Huntsville', 'AL'), ('Selma', 'AL'),\n" +" ('Anchorage', 'AK'), ('Nome', 'AK'),\n" +" ('Flagstaff', 'AZ'), ('Phoenix', 'AZ'), ('Tucson', 'AZ'),\n" +" ...\n" +" ]\n" +"\n" +"def get_state(city_state):\n" +" return city_state[1]\n" +"\n" +"itertools.groupby(city_list, get_state) =>\n" +" ('AL', iterator-1),\n" +" ('AK', iterator-2),\n" +" ('AZ', iterator-3), ...\n" +"\n" +"where\n" +"iterator-1 =>\n" +" ('Decatur', 'AL'), ('Huntsville', 'AL'), ('Selma', 'AL')\n" +"iterator-2 =>\n" +" ('Anchorage', 'AK'), ('Nome', 'AK')\n" +"iterator-3 =>\n" +" ('Flagstaff', 'AZ'), ('Phoenix', 'AZ'), ('Tucson', 'AZ')" + +#: ../../howto/functional.rst:990 +msgid "" +":func:`~itertools.groupby` assumes that the underlying iterable's contents " +"will already be sorted based on the key. Note that the returned iterators " +"also use the underlying iterable, so you have to consume the results of " +"iterator-1 before requesting iterator-2 and its corresponding key." +msgstr "" + +#: ../../howto/functional.rst:997 +msgid "The functools module" +msgstr "functools 模組" + +#: ../../howto/functional.rst:999 +msgid "" +"The :mod:`functools` module contains some higher-order functions. A **higher-" +"order function** takes one or more functions as input and returns a new " +"function. The most useful tool in this module is the :func:`functools." +"partial` function." +msgstr "" + +#: ../../howto/functional.rst:1004 +msgid "" +"For programs written in a functional style, you'll sometimes want to " +"construct variants of existing functions that have some of the parameters " +"filled in. Consider a Python function ``f(a, b, c)``; you may wish to create " +"a new function ``g(b, c)`` that's equivalent to ``f(1, b, c)``; you're " +"filling in a value for one of ``f()``'s parameters. This is called " +"\"partial function application\"." +msgstr "" + +#: ../../howto/functional.rst:1010 +msgid "" +"The constructor for :func:`~functools.partial` takes the arguments " +"``(function, arg1, arg2, ..., kwarg1=value1, kwarg2=value2)``. The " +"resulting object is callable, so you can just call it to invoke ``function`` " +"with the filled-in arguments." +msgstr "" + +#: ../../howto/functional.rst:1015 +msgid "Here's a small but realistic example::" +msgstr "以下是個很小但實際的範例： ::" + +#: ../../howto/functional.rst:1017 +msgid "" +"import functools\n" +"\n" +"def log(message, subsystem):\n" +" \"\"\"Write the contents of 'message' to the specified subsystem.\"\"\"\n" +" print('%s: %s' % (subsystem, message))\n" +" ...\n" +"\n" +"server_log = functools.partial(log, subsystem='server')\n" +"server_log('Unable to open socket')" +msgstr "" + +#: ../../howto/functional.rst:1027 +msgid "" +":func:`functools.reduce(func, iter, [initial_value]) ` " +"cumulatively performs an operation on all the iterable's elements and, " +"therefore, can't be applied to infinite iterables. *func* must be a function " +"that takes two elements and returns a single value. :func:`functools." +"reduce` takes the first two elements A and B returned by the iterator and " +"calculates ``func(A, B)``. It then requests the third element, C, " +"calculates ``func(func(A, B), C)``, combines this result with the fourth " +"element returned, and continues until the iterable is exhausted. If the " +"iterable returns no values at all, a :exc:`TypeError` exception is raised. " +"If the initial value is supplied, it's used as a starting point and " +"``func(initial_value, A)`` is the first calculation. ::" +msgstr "" + +#: ../../howto/functional.rst:1039 +msgid "" +">>> import operator, functools\n" +">>> functools.reduce(operator.concat, ['A', 'BB', 'C'])\n" +"'ABBC'\n" +">>> functools.reduce(operator.concat, [])\n" +"Traceback (most recent call last):\n" +" ...\n" +"TypeError: reduce() of empty sequence with no initial value\n" +">>> functools.reduce(operator.mul, [1, 2, 3], 1)\n" +"6\n" +">>> functools.reduce(operator.mul, [], 1)\n" +"1" +msgstr "" +">>> import operator, functools\n" +">>> functools.reduce(operator.concat, ['A', 'BB', 'C'])\n" +"'ABBC'\n" +">>> functools.reduce(operator.concat, [])\n" +"Traceback (most recent call last):\n" +" ...\n" +"TypeError: reduce() of empty sequence with no initial value\n" +">>> functools.reduce(operator.mul, [1, 2, 3], 1)\n" +"6\n" +">>> functools.reduce(operator.mul, [], 1)\n" +"1" + +#: ../../howto/functional.rst:1051 +msgid "" +"If you use :func:`operator.add` with :func:`functools.reduce`, you'll add up " +"all the elements of the iterable. This case is so common that there's a " +"special built-in called :func:`sum` to compute it:" +msgstr "" + +#: ../../howto/functional.rst:1063 +msgid "" +"For many uses of :func:`functools.reduce`, though, it can be clearer to just " +"write the obvious :keyword:`for` loop::" +msgstr "" + +#: ../../howto/functional.rst:1066 +msgid "" +"import functools\n" +"# Instead of:\n" +"product = functools.reduce(operator.mul, [1, 2, 3], 1)\n" +"\n" +"# You can write:\n" +"product = 1\n" +"for i in [1, 2, 3]:\n" +" product *= i" +msgstr "" + +#: ../../howto/functional.rst:1075 +msgid "" +"A related function is :func:`itertools.accumulate(iterable, func=operator." +"add) `. It performs the same calculation, but instead " +"of returning only the final result, :func:`~itertools.accumulate` returns an " +"iterator that also yields each partial result::" +msgstr "" + +#: ../../howto/functional.rst:1080 +msgid "" +"itertools.accumulate([1, 2, 3, 4, 5]) =>\n" +" 1, 3, 6, 10, 15\n" +"\n" +"itertools.accumulate([1, 2, 3, 4, 5], operator.mul) =>\n" +" 1, 2, 6, 24, 120" +msgstr "" +"itertools.accumulate([1, 2, 3, 4, 5]) =>\n" +" 1, 3, 6, 10, 15\n" +"\n" +"itertools.accumulate([1, 2, 3, 4, 5], operator.mul) =>\n" +" 1, 2, 6, 24, 120" + +#: ../../howto/functional.rst:1088 +msgid "The operator module" +msgstr "operator 模組" + +#: ../../howto/functional.rst:1090 +msgid "" +"The :mod:`operator` module was mentioned earlier. It contains a set of " +"functions corresponding to Python's operators. These functions are often " +"useful in functional-style code because they save you from writing trivial " +"functions that perform a single operation." +msgstr "" + +#: ../../howto/functional.rst:1095 +msgid "Some of the functions in this module are:" +msgstr "" + +#: ../../howto/functional.rst:1097 +msgid "" +"Math operations: ``add()``, ``sub()``, ``mul()``, ``floordiv()``, " +"``abs()``, ..." +msgstr "" +"數學運算：``add()``、``sub()``、``mul()``、``floordiv()``、``abs()``..." + +#: ../../howto/functional.rst:1098 +msgid "Logical operations: ``not_()``, ``truth()``." +msgstr "" + +#: ../../howto/functional.rst:1099 +msgid "Bitwise operations: ``and_()``, ``or_()``, ``invert()``." +msgstr "" + +#: ../../howto/functional.rst:1100 +msgid "" +"Comparisons: ``eq()``, ``ne()``, ``lt()``, ``le()``, ``gt()``, and ``ge()``." +msgstr "" + +#: ../../howto/functional.rst:1101 +msgid "Object identity: ``is_()``, ``is_not()``." +msgstr "" + +#: ../../howto/functional.rst:1103 +msgid "Consult the operator module's documentation for a complete list." +msgstr "" + +#: ../../howto/functional.rst:1107 +msgid "Small functions and the lambda expression" +msgstr "" + +#: ../../howto/functional.rst:1109 +msgid "" +"When writing functional-style programs, you'll often need little functions " +"that act as predicates or that combine elements in some way." +msgstr "" + +#: ../../howto/functional.rst:1112 +msgid "" +"If there's a Python built-in or a module function that's suitable, you don't " +"need to define a new function at all::" +msgstr "" + +#: ../../howto/functional.rst:1115 +msgid "" +"stripped_lines = [line.strip() for line in lines]\n" +"existing_files = filter(os.path.exists, file_list)" +msgstr "" +"stripped_lines = [line.strip() for line in lines]\n" +"existing_files = filter(os.path.exists, file_list)" + +#: ../../howto/functional.rst:1118 +msgid "" +"If the function you need doesn't exist, you need to write it. One way to " +"write small functions is to use the :keyword:`lambda` expression. " +"``lambda`` takes a number of parameters and an expression combining these " +"parameters, and creates an anonymous function that returns the value of the " +"expression::" +msgstr "" + +#: ../../howto/functional.rst:1123 +msgid "" +"adder = lambda x, y: x+y\n" +"\n" +"print_assign = lambda name, value: name + '=' + str(value)" +msgstr "" +"adder = lambda x, y: x+y\n" +"\n" +"print_assign = lambda name, value: name + '=' + str(value)" + +#: ../../howto/functional.rst:1127 +msgid "" +"An alternative is to just use the ``def`` statement and define a function in " +"the usual way::" +msgstr "" + +#: ../../howto/functional.rst:1130 +msgid "" +"def adder(x, y):\n" +" return x + y\n" +"\n" +"def print_assign(name, value):\n" +" return name + '=' + str(value)" +msgstr "" +"def adder(x, y):\n" +" return x + y\n" +"\n" +"def print_assign(name, value):\n" +" return name + '=' + str(value)" + +#: ../../howto/functional.rst:1136 +msgid "" +"Which alternative is preferable? That's a style question; my usual course " +"is to avoid using ``lambda``." +msgstr "" + +#: ../../howto/functional.rst:1139 +msgid "" +"One reason for my preference is that ``lambda`` is quite limited in the " +"functions it can define. The result has to be computable as a single " +"expression, which means you can't have multiway ``if... elif... else`` " +"comparisons or ``try... except`` statements. If you try to do too much in a " +"``lambda`` statement, you'll end up with an overly complicated expression " +"that's hard to read. Quick, what's the following code doing? ::" +msgstr "" + +#: ../../howto/functional.rst:1146 +msgid "" +"import functools\n" +"total = functools.reduce(lambda a, b: (0, a[1] + b[1]), items)[1]" +msgstr "" +"import functools\n" +"total = functools.reduce(lambda a, b: (0, a[1] + b[1]), items)[1]" + +#: ../../howto/functional.rst:1149 +msgid "" +"You can figure it out, but it takes time to disentangle the expression to " +"figure out what's going on. Using a short nested ``def`` statements makes " +"things a little bit better::" +msgstr "" + +#: ../../howto/functional.rst:1153 +msgid "" +"import functools\n" +"def combine(a, b):\n" +" return 0, a[1] + b[1]\n" +"\n" +"total = functools.reduce(combine, items)[1]" +msgstr "" +"import functools\n" +"def combine(a, b):\n" +" return 0, a[1] + b[1]\n" +"\n" +"total = functools.reduce(combine, items)[1]" + +#: ../../howto/functional.rst:1159 +msgid "But it would be best of all if I had simply used a ``for`` loop::" +msgstr "" + +#: ../../howto/functional.rst:1161 +msgid "" +"total = 0\n" +"for a, b in items:\n" +" total += b" +msgstr "" +"total = 0\n" +"for a, b in items:\n" +" total += b" + +#: ../../howto/functional.rst:1165 +msgid "Or the :func:`sum` built-in and a generator expression::" +msgstr "" + +#: ../../howto/functional.rst:1167 +msgid "total = sum(b for a, b in items)" +msgstr "total = sum(b for a, b in items)" + +#: ../../howto/functional.rst:1169 +msgid "" +"Many uses of :func:`functools.reduce` are clearer when written as ``for`` " +"loops." +msgstr "" + +#: ../../howto/functional.rst:1171 +msgid "" +"Fredrik Lundh once suggested the following set of rules for refactoring uses " +"of ``lambda``:" +msgstr "" + +#: ../../howto/functional.rst:1174 +msgid "Write a lambda function." +msgstr "" + +#: ../../howto/functional.rst:1175 +msgid "Write a comment explaining what the heck that lambda does." +msgstr "" + +#: ../../howto/functional.rst:1176 +msgid "" +"Study the comment for a while, and think of a name that captures the essence " +"of the comment." +msgstr "" + +#: ../../howto/functional.rst:1178 +msgid "Convert the lambda to a def statement, using that name." +msgstr "" + +#: ../../howto/functional.rst:1179 +msgid "Remove the comment." +msgstr "" + +#: ../../howto/functional.rst:1181 +msgid "" +"I really like these rules, but you're free to disagree about whether this " +"lambda-free style is better." +msgstr "" + +#: ../../howto/functional.rst:1186 +msgid "Revision History and Acknowledgements" +msgstr "" + +#: ../../howto/functional.rst:1188 +msgid "" +"The author would like to thank the following people for offering " +"suggestions, corrections and assistance with various drafts of this article: " +"Ian Bicking, Nick Coghlan, Nick Efford, Raymond Hettinger, Jim Jewett, Mike " +"Krell, Leandro Lameiro, Jussi Salmela, Collin Winter, Blake Winton." +msgstr "" + +#: ../../howto/functional.rst:1193 +msgid "Version 0.1: posted June 30 2006." +msgstr "" + +#: ../../howto/functional.rst:1195 +msgid "Version 0.11: posted July 1 2006. Typo fixes." +msgstr "" + +#: ../../howto/functional.rst:1197 +msgid "" +"Version 0.2: posted July 10 2006. Merged genexp and listcomp sections into " +"one. Typo fixes." +msgstr "" + +#: ../../howto/functional.rst:1200 +msgid "" +"Version 0.21: Added more references suggested on the tutor mailing list." +msgstr "" + +#: ../../howto/functional.rst:1202 +msgid "" +"Version 0.30: Adds a section on the ``functional`` module written by Collin " +"Winter; adds short section on the operator module; a few other edits." +msgstr "" + +#: ../../howto/functional.rst:1207 +msgid "References" +msgstr "" + +#: ../../howto/functional.rst:1210 +msgid "General" +msgstr "" + +#: ../../howto/functional.rst:1212 +msgid "" +"**Structure and Interpretation of Computer Programs**, by Harold Abelson and " +"Gerald Jay Sussman with Julie Sussman. The book can be found at https://" +"mitpress.mit.edu/sicp. In this classic textbook of computer science, " +"chapters 2 and 3 discuss the use of sequences and streams to organize the " +"data flow inside a program. The book uses Scheme for its examples, but many " +"of the design approaches described in these chapters are applicable to " +"functional-style Python code." +msgstr "" + +#: ../../howto/functional.rst:1220 +msgid "" +"https://defmacro.org/2006/06/19/fp.html: A general introduction to " +"functional programming that uses Java examples and has a lengthy historical " +"introduction." +msgstr "" + +#: ../../howto/functional.rst:1223 +msgid "" +"https://en.wikipedia.org/wiki/Functional_programming: General Wikipedia " +"entry describing functional programming." +msgstr "" + +#: ../../howto/functional.rst:1226 +msgid "https://en.wikipedia.org/wiki/Coroutine: Entry for coroutines." +msgstr "https://en.wikipedia.org/wiki/Coroutine: 協程 (coroutines) 的條目。" + +#: ../../howto/functional.rst:1228 +msgid "" +"https://en.wikipedia.org/wiki/Partial_application: Entry for the concept of " +"partial function application." +msgstr "" +"https://en.wikipedia.org/wiki/Partial_application: 偏函式 (partial " +"application) 概念的條目。" + +#: ../../howto/functional.rst:1230 +msgid "" +"https://en.wikipedia.org/wiki/Currying: Entry for the concept of currying." +msgstr "https://en.wikipedia.org/wiki/Currying: currying 概念的條目。" + +#: ../../howto/functional.rst:1233 +msgid "Python-specific" +msgstr "Python 特有的" + +#: ../../howto/functional.rst:1235 +msgid "" +"https://gnosis.cx/TPiP/: The first chapter of David Mertz's book :title-" +"reference:`Text Processing in Python` discusses functional programming for " +"text processing, in the section titled \"Utilizing Higher-Order Functions in " +"Text Processing\"." +msgstr "" + +#: ../../howto/functional.rst:1240 +msgid "" +"Mertz also wrote a 3-part series of articles on functional programming for " +"IBM's DeveloperWorks site; see `part 1 `__, `part 2 `__, and " +"`part 3 `__," +msgstr "" + +#: ../../howto/functional.rst:1248 +msgid "Python documentation" +msgstr "Python 說明文件" + +#: ../../howto/functional.rst:1250 +msgid "Documentation for the :mod:`itertools` module." +msgstr ":mod:`itertools` 模組的說明文件。" + +#: ../../howto/functional.rst:1252 +msgid "Documentation for the :mod:`functools` module." +msgstr ":mod:`functools` 模組的說明文件。" + +#: ../../howto/functional.rst:1254 +msgid "Documentation for the :mod:`operator` module." +msgstr ":mod:`operator` 模組的說明文件。" + +#: ../../howto/functional.rst:1256 +msgid ":pep:`289`: \"Generator Expressions\"" +msgstr ":pep:`289`：「產生器運算式 (Generator Expressions)」" + +#: ../../howto/functional.rst:1258 +msgid "" +":pep:`342`: \"Coroutines via Enhanced Generators\" describes the new " +"generator features in Python 2.5." +msgstr "" diff --git a/howto/gdb_helpers.po b/howto/gdb_helpers.po index 76983819c8..d24e0228ae 100644 --- a/howto/gdb_helpers.po +++ b/howto/gdb_helpers.po @@ -1,1162 +1,1162 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Matt Wang , 2024 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-12-06 00:14+0000\n" -"PO-Revision-Date: 2024-05-11 14:42+0800\n" -"Last-Translator: Matt Wang \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" - -#: ../../howto/gdb_helpers.rst:5 -msgid "Debugging C API extensions and CPython Internals with GDB" -msgstr "使用 GDB 來為 C API 擴充功能和 CPython 內部偵錯" - -#: ../../howto/gdb_helpers.rst:9 -msgid "" -"This document explains how the Python GDB extension, ``python-gdb.py``, can " -"be used with the GDB debugger to debug CPython extensions and the CPython " -"interpreter itself." -msgstr "" -"本文件解釋如何將 Python GDB 擴充功能 ``python-gdb.py`` 與 GDB 偵錯器一起使用" -"來為 CPython 擴充功能和 CPython 直譯器本身偵錯。" - -#: ../../howto/gdb_helpers.rst:13 -msgid "" -"When debugging low-level problems such as crashes or deadlocks, a low-level " -"debugger, such as GDB, is useful to diagnose and correct the issue. By " -"default, GDB (or any of its front-ends) doesn't support high-level " -"information specific to the CPython interpreter." -msgstr "" -"在為崩潰或死鎖等低階問題幀錯時，低階偵錯器（例如 GDB）對於診斷和修正問題非常" -"有用。預設情況下，GDB（或其任何前端）不支援特定於 CPython 直譯器的高階資訊。" - -#: ../../howto/gdb_helpers.rst:18 -msgid "" -"The ``python-gdb.py`` extension adds CPython interpreter information to GDB. " -"The extension helps introspect the stack of currently executing Python " -"functions. Given a Python object represented by a :c:expr:`PyObject *` " -"pointer, the extension surfaces the type and value of the object." -msgstr "" -"``python-gdb.py`` 擴充功能將 CPython 直譯器資訊新增至 GDB。此擴充有助於內省 " -"(introspect) 目前執行的 Python 函式的堆疊。給定一個由 :c:expr:`PyObject *` 指" -"標表示的 Python 物件，擴充功能會顯示該物件的型別和值。" - -#: ../../howto/gdb_helpers.rst:23 -msgid "" -"Developers who are working on CPython extensions or tinkering with parts of " -"CPython that are written in C can use this document to learn how to use the " -"``python-gdb.py`` extension with GDB." -msgstr "" -"正在開發 CPython 擴充功能或修補用 C 編寫之 CPython 部分的開發人員可以使用本文" -"件來學習如何將 ``python-gdb.py`` 擴充功能與 GDB 一起使用。" - -#: ../../howto/gdb_helpers.rst:29 -msgid "" -"This document assumes that you are familiar with the basics of GDB and the " -"CPython C API. It consolidates guidance from the `devguide `_ and the `Python wiki `_." -msgstr "" -"本文件假設你熟悉 GDB 和 CPython C API 的基礎知識。它整合了 `devguide " -"`_ 和 `Python wiki `_ 的指引。" - -#: ../../howto/gdb_helpers.rst:36 -msgid "Prerequisites" -msgstr "先決條件" - -#: ../../howto/gdb_helpers.rst:38 -msgid "You need to have:" -msgstr "你需要有：" - -#: ../../howto/gdb_helpers.rst:40 -msgid "" -"GDB 7 or later. (For earlier versions of GDB, see ``Misc/gdbinit`` in the " -"sources of Python 3.11 or earlier.)" -msgstr "" -"GDB 7 或更之後的版本。（對於早期版本的 GDB，請參閱 Python 3.11 或更早版本的原" -"始程式碼中的 ``Misc/gdbinit``。）" - -#: ../../howto/gdb_helpers.rst:42 -msgid "" -"GDB-compatible debugging information for Python and any extension you are " -"debugging." -msgstr "對 Python 和你在偵錯的任何擴充功能來說的與 GDB 相容的偵錯資訊。" - -#: ../../howto/gdb_helpers.rst:44 -msgid "The ``python-gdb.py`` extension." -msgstr "``python-gdb.py`` 擴充。" - -#: ../../howto/gdb_helpers.rst:46 -msgid "" -"The extension is built with Python, but might be distributed separately or " -"not at all. Below, we include tips for a few common systems as examples. " -"Note that even if the instructions match your system, they might be outdated." -msgstr "" -"該擴充功能是用 Python 建置的，但可能會單獨發布或根本不發布。以下我們將一些常" -"見系統的提示作為範例。請注意，即使說明與你的系統匹配，它們也可能已過時。" - -#: ../../howto/gdb_helpers.rst:52 -msgid "Setup with Python built from source" -msgstr "使用從原始碼建置的 Python 進行設定" - -#: ../../howto/gdb_helpers.rst:54 -msgid "" -"When you build CPython from source, debugging information should be " -"available, and the build should add a ``python-gdb.py`` file to the root " -"directory of your repository." -msgstr "" -"當你從原始程式碼建立 CPython 時，偵錯資訊應該可用，並且建置應該將 ``python-" -"gdb.py`` 檔案新增至儲存庫的根目錄中。" - -#: ../../howto/gdb_helpers.rst:58 -msgid "" -"To activate support, you must add the directory containing ``python-gdb.py`` " -"to GDB's \"auto-load-safe-path\". If you haven't done this, recent versions " -"of GDB will print out a warning with instructions on how to do this." -msgstr "" -"若要啟用支援，你必須將包含 ``python-gdb.py`` 的目錄新增至 GDB 的 \"auto-load-" -"safe-path\"。如果你還沒有這樣做，最新版本的 GDB 將列印警告，其中包含有關如何" -"執行此操作的說明。" - -#: ../../howto/gdb_helpers.rst:65 -msgid "" -"If you do not see instructions for your version of GDB, put this in your " -"configuration file (``~/.gdbinit`` or ``~/.config/gdb/gdbinit``)::" -msgstr "" -"如果你沒有看到適合你的 GDB 版本的說明，請將其放入你的設定檔中（``~/." -"gdbinit`` 或 ``~/.config/gdb/gdbinit``）：" - -#: ../../howto/gdb_helpers.rst:68 -msgid "add-auto-load-safe-path /path/to/cpython" -msgstr "add-auto-load-safe-path /path/to/cpython" - -#: ../../howto/gdb_helpers.rst:70 -msgid "You can also add multiple paths, separated by ``:``." -msgstr "你也可以新增多個路徑，要以 ``:`` 分隔。" - -#: ../../howto/gdb_helpers.rst:74 -msgid "Setup for Python from a Linux distro" -msgstr "從 Linux 發行版設定 Python" - -#: ../../howto/gdb_helpers.rst:76 -msgid "" -"Most Linux systems provide debug information for the system Python in a " -"package called ``python-debuginfo``, ``python-dbg`` or similar. For example:" -msgstr "" -"大多數 Linux 系統在名為 ``python-debuginfo``、``python-dbg`` 或類似的套件中提" -"供系統 Python 的偵錯資訊。例如：" - -#: ../../howto/gdb_helpers.rst:80 -msgid "Fedora:" -msgstr "Fedora：" - -#: ../../howto/gdb_helpers.rst:82 -msgid "" -"sudo dnf install gdb\n" -"sudo dnf debuginfo-install python3" -msgstr "" -"sudo dnf install gdb\n" -"sudo dnf debuginfo-install python3" - -#: ../../howto/gdb_helpers.rst:87 -msgid "Ubuntu:" -msgstr "Ubuntu：" - -#: ../../howto/gdb_helpers.rst:89 -msgid "sudo apt install gdb python3-dbg" -msgstr "sudo apt install gdb python3-dbg" - -#: ../../howto/gdb_helpers.rst:93 -msgid "" -"On several recent Linux systems, GDB can download debugging symbols " -"automatically using *debuginfod*. However, this will not install the " -"``python-gdb.py`` extension; you generally do need to install the debug info " -"package separately." -msgstr "" -"在最近的幾個 Linux 系統上，GDB 可以使用 *debuginfod* 自動下載偵錯符號。但是這" -"不會安裝 ``python-gdb.py`` 擴充功能；你通常需要另外安裝偵錯資訊套件。" - -#: ../../howto/gdb_helpers.rst:100 -msgid "Using the Debug build and Development mode" -msgstr "使用偵錯建置與使用開發模式" - -#: ../../howto/gdb_helpers.rst:102 -msgid "For easier debugging, you might want to:" -msgstr "為了更輕鬆地進行偵錯，你可能需要：" - -#: ../../howto/gdb_helpers.rst:104 -msgid "" -"Use a :ref:`debug build ` of Python. (When building from " -"source, use ``configure --with-pydebug``. On Linux distros, install and run " -"a package like ``python-debug`` or ``python-dbg``, if available.)" -msgstr "" -"使用 Python 的\\ :ref:`偵錯建置 `。（從原始碼建置時，請使用 " -"``configure --with-pydebug``。在 Linux 發行版上，安裝並執行諸如 ``python-" -"debug`` 或 ``python-dbg`` 之類的套件（如果可用））。" - -#: ../../howto/gdb_helpers.rst:107 -msgid "Use the runtime :ref:`development mode ` (``-X dev``)." -msgstr "使用 runtime :ref:`開發模式 ` (``-X dev``)。" - -#: ../../howto/gdb_helpers.rst:109 -msgid "" -"Both enable extra assertions and disable some optimizations. Sometimes this " -"hides the bug you are trying to find, but in most cases they make the " -"process easier." -msgstr "" -"兩者都啟用額外的斷言 (assertion) 並停用一些最佳化。有時這會隱藏你試圖想尋找的" -"錯誤，但在大多數情況下，它們會使過程變得更容易。" - -#: ../../howto/gdb_helpers.rst:115 -msgid "Using the ``python-gdb`` extension" -msgstr "使用 ``python-gdb`` 擴充功能" - -#: ../../howto/gdb_helpers.rst:117 -msgid "" -"When the extension is loaded, it provides two main features: pretty printers " -"for Python values, and additional commands." -msgstr "載入擴充功能後，它提供兩個主要功能：Python 值的漂亮列印器和附加命令。" - -#: ../../howto/gdb_helpers.rst:121 -msgid "Pretty-printers" -msgstr "漂亮列印器" - -#: ../../howto/gdb_helpers.rst:123 -msgid "" -"This is what a GDB backtrace looks like (truncated) when this extension is " -"enabled::" -msgstr "這是啟用此擴充功能時 GDB 回溯 (backtrace) 的樣子（有被截斷）：" - -#: ../../howto/gdb_helpers.rst:126 -msgid "" -"#0 0x000000000041a6b1 in PyObject_Malloc (nbytes=Cannot access memory at " -"address 0x7fffff7fefe8\n" -") at Objects/obmalloc.c:748\n" -"#1 0x000000000041b7c0 in _PyObject_DebugMallocApi (id=111 'o', nbytes=24) " -"at Objects/obmalloc.c:1445\n" -"#2 0x000000000041b717 in _PyObject_DebugMalloc (nbytes=24) at Objects/" -"obmalloc.c:1412\n" -"#3 0x000000000044060a in _PyUnicode_New (length=11) at Objects/" -"unicodeobject.c:346\n" -"#4 0x00000000004466aa in PyUnicodeUCS2_DecodeUTF8Stateful (s=0x5c2b8d " -"\"__lltrace__\", size=11, errors=0x0, consumed=\n" -" 0x0) at Objects/unicodeobject.c:2531\n" -"#5 0x0000000000446647 in PyUnicodeUCS2_DecodeUTF8 (s=0x5c2b8d " -"\"__lltrace__\", size=11, errors=0x0)\n" -" at Objects/unicodeobject.c:2495\n" -"#6 0x0000000000440d1b in PyUnicodeUCS2_FromStringAndSize (u=0x5c2b8d " -"\"__lltrace__\", size=11)\n" -" at Objects/unicodeobject.c:551\n" -"#7 0x0000000000440d94 in PyUnicodeUCS2_FromString (u=0x5c2b8d " -"\"__lltrace__\") at Objects/unicodeobject.c:569\n" -"#8 0x0000000000584abd in PyDict_GetItemString (v=\n" -" {'Yuck': , '__builtins__': , '__file__': 'Lib/test/crashers/nasty_eq_vs_dict.py', " -"'__package__': None, 'y': , 'dict': {0: 0, 1: " -"1, 2: 2, 3: 3}, '__cached__': None, '__name__': '__main__', 'z': , '__doc__': None}, key=\n" -" 0x5c2b8d \"__lltrace__\") at Objects/dictobject.c:2171" -msgstr "" -"#0 0x000000000041a6b1 in PyObject_Malloc (nbytes=Cannot access memory at " -"address 0x7fffff7fefe8\n" -") at Objects/obmalloc.c:748\n" -"#1 0x000000000041b7c0 in _PyObject_DebugMallocApi (id=111 'o', nbytes=24) " -"at Objects/obmalloc.c:1445\n" -"#2 0x000000000041b717 in _PyObject_DebugMalloc (nbytes=24) at Objects/" -"obmalloc.c:1412\n" -"#3 0x000000000044060a in _PyUnicode_New (length=11) at Objects/" -"unicodeobject.c:346\n" -"#4 0x00000000004466aa in PyUnicodeUCS2_DecodeUTF8Stateful (s=0x5c2b8d " -"\"__lltrace__\", size=11, errors=0x0, consumed=\n" -" 0x0) at Objects/unicodeobject.c:2531\n" -"#5 0x0000000000446647 in PyUnicodeUCS2_DecodeUTF8 (s=0x5c2b8d " -"\"__lltrace__\", size=11, errors=0x0)\n" -" at Objects/unicodeobject.c:2495\n" -"#6 0x0000000000440d1b in PyUnicodeUCS2_FromStringAndSize (u=0x5c2b8d " -"\"__lltrace__\", size=11)\n" -" at Objects/unicodeobject.c:551\n" -"#7 0x0000000000440d94 in PyUnicodeUCS2_FromString (u=0x5c2b8d " -"\"__lltrace__\") at Objects/unicodeobject.c:569\n" -"#8 0x0000000000584abd in PyDict_GetItemString (v=\n" -" {'Yuck': , '__builtins__': , '__file__': 'Lib/test/crashers/nasty_eq_vs_dict.py', " -"'__package__': None, 'y': , 'dict': {0: 0, 1: " -"1, 2: 2, 3: 3}, '__cached__': None, '__name__': '__main__', 'z': , '__doc__': None}, key=\n" -" 0x5c2b8d \"__lltrace__\") at Objects/dictobject.c:2171" - -#: ../../howto/gdb_helpers.rst:142 -msgid "" -"Notice how the dictionary argument to ``PyDict_GetItemString`` is displayed " -"as its ``repr()``, rather than an opaque ``PyObject *`` pointer." -msgstr "" -"請注意 ``PyDict_GetItemString`` 的字典引數如何顯示為其 ``repr()``，而不是不透" -"明的 ``PyObject *`` 指標。" - -#: ../../howto/gdb_helpers.rst:145 -msgid "" -"The extension works by supplying a custom printing routine for values of " -"type ``PyObject *``. If you need to access lower-level details of an " -"object, then cast the value to a pointer of the appropriate type. For " -"example::" -msgstr "" -"該擴充功能透過為 ``PyObject *`` 型別的值提供自訂列印例程來運作。如果需要存取" -"物件較低階的詳細資訊，請將值轉換為適當型別的指標。例如： ::" - -#: ../../howto/gdb_helpers.rst:149 -msgid "" -"(gdb) p globals\n" -"$1 = {'__builtins__': , '__name__':\n" -"'__main__', 'ctypes': , '__doc__': None,\n" -"'__package__': None}\n" -"\n" -"(gdb) p *(PyDictObject*)globals\n" -"$2 = {ob_refcnt = 3, ob_type = 0x3dbdf85820, ma_fill = 5, ma_used = 5,\n" -"ma_mask = 7, ma_table = 0x63d0f8, ma_lookup = 0x3dbdc7ea70\n" -", ma_smalltable = {{me_hash = 7065186196740147912,\n" -"me_key = '__builtins__', me_value = },\n" -"{me_hash = -368181376027291943, me_key = '__name__',\n" -"me_value ='__main__'}, {me_hash = 0, me_key = 0x0, me_value = 0x0},\n" -"{me_hash = 0, me_key = 0x0, me_value = 0x0},\n" -"{me_hash = -9177857982131165996, me_key = 'ctypes',\n" -"me_value = },\n" -"{me_hash = -8518757509529533123, me_key = '__doc__', me_value = None},\n" -"{me_hash = 0, me_key = 0x0, me_value = 0x0}, {\n" -" me_hash = 6614918939584953775, me_key = '__package__', me_value = None}}}" -msgstr "" -"(gdb) p globals\n" -"$1 = {'__builtins__': , '__name__':\n" -"'__main__', 'ctypes': , '__doc__': None,\n" -"'__package__': None}\n" -"\n" -"(gdb) p *(PyDictObject*)globals\n" -"$2 = {ob_refcnt = 3, ob_type = 0x3dbdf85820, ma_fill = 5, ma_used = 5,\n" -"ma_mask = 7, ma_table = 0x63d0f8, ma_lookup = 0x3dbdc7ea70\n" -", ma_smalltable = {{me_hash = 7065186196740147912,\n" -"me_key = '__builtins__', me_value = },\n" -"{me_hash = -368181376027291943, me_key = '__name__',\n" -"me_value ='__main__'}, {me_hash = 0, me_key = 0x0, me_value = 0x0},\n" -"{me_hash = 0, me_key = 0x0, me_value = 0x0},\n" -"{me_hash = -9177857982131165996, me_key = 'ctypes',\n" -"me_value = },\n" -"{me_hash = -8518757509529533123, me_key = '__doc__', me_value = None},\n" -"{me_hash = 0, me_key = 0x0, me_value = 0x0}, {\n" -" me_hash = 6614918939584953775, me_key = '__package__', me_value = None}}}" - -#: ../../howto/gdb_helpers.rst:168 -msgid "" -"Note that the pretty-printers do not actually call ``repr()``. For basic " -"types, they try to match its result closely." -msgstr "" -"請注意，漂亮列印器其實並不呼叫 ``repr()``。對於基本型別，他們嘗試緊密匹配其結" -"果。" - -#: ../../howto/gdb_helpers.rst:171 -msgid "" -"An area that can be confusing is that the custom printer for some types look " -"a lot like GDB's built-in printer for standard types. For example, the " -"pretty-printer for a Python ``int`` (:c:expr:`PyLongObject *`) gives a " -"representation that is not distinguishable from one of a regular machine-" -"level integer::" -msgstr "" -"一個可能令人困惑的地方是，某些型別的自訂列印器看起來很像 GDB 標準類型的內建列" -"印器。例如，Python ``int`` (:c:expr:`PyLongObject *`) 的漂亮列印器給出的表示" -"法無法與常規機器層級整數之其一區分： ::" - -#: ../../howto/gdb_helpers.rst:177 -msgid "" -"(gdb) p some_machine_integer\n" -"$3 = 42\n" -"\n" -"(gdb) p some_python_integer\n" -"$4 = 42" -msgstr "" -"(gdb) p some_machine_integer\n" -"$3 = 42\n" -"\n" -"(gdb) p some_python_integer\n" -"$4 = 42" - -#: ../../howto/gdb_helpers.rst:183 -msgid "" -"The internal structure can be revealed with a cast to :c:expr:`PyLongObject " -"*`::" -msgstr "可以透過轉換 (cast) 為 :c:expr:`PyLongObject *` 來揭示內部結構： ::" - -#: ../../howto/gdb_helpers.rst:185 -msgid "" -"(gdb) p *(PyLongObject*)some_python_integer\n" -"$5 = {ob_base = {ob_base = {ob_refcnt = 8, ob_type = 0x3dad39f5e0}, ob_size " -"= 1},\n" -"ob_digit = {42}}" -msgstr "" -"(gdb) p *(PyLongObject*)some_python_integer\n" -"$5 = {ob_base = {ob_base = {ob_refcnt = 8, ob_type = 0x3dad39f5e0}, ob_size " -"= 1},\n" -"ob_digit = {42}}" - -#: ../../howto/gdb_helpers.rst:189 -msgid "" -"A similar confusion can arise with the ``str`` type, where the output looks " -"a lot like gdb's built-in printer for ``char *``::" -msgstr "" -"使用 ``str`` 型別時也可能會出現類似的困惑，其中的輸出看起來很像對於 ``char " -"*`` 的 gdb 內建列印器 ： ::" - -#: ../../howto/gdb_helpers.rst:192 -msgid "" -"(gdb) p ptr_to_python_str\n" -"$6 = '__builtins__'" -msgstr "" -"(gdb) p ptr_to_python_str\n" -"$6 = '__builtins__'" - -#: ../../howto/gdb_helpers.rst:195 -msgid "" -"The pretty-printer for ``str`` instances defaults to using single-quotes (as " -"does Python's ``repr`` for strings) whereas the standard printer for ``char " -"*`` values uses double-quotes and contains a hexadecimal address::" -msgstr "" -"``str`` 實例的漂亮列印器預設使用單引號（Python 的 ``repr`` 對於字串也是如" -"此），而 ``char *`` 值的標準列印器使用雙引號並包含十六進位位址： ::" - -#: ../../howto/gdb_helpers.rst:199 -msgid "" -"(gdb) p ptr_to_char_star\n" -"$7 = 0x6d72c0 \"hello world\"" -msgstr "" -"(gdb) p ptr_to_char_star\n" -"$7 = 0x6d72c0 \"hello world\"" - -#: ../../howto/gdb_helpers.rst:202 -msgid "" -"Again, the implementation details can be revealed with a cast to :c:expr:" -"`PyUnicodeObject *`::" -msgstr "同樣，可以透過轉換為 :c:expr:`PyUnicodeObject *` 來揭示實作細節： ::" - -#: ../../howto/gdb_helpers.rst:205 -msgid "" -"(gdb) p *(PyUnicodeObject*)$6\n" -"$8 = {ob_base = {ob_refcnt = 33, ob_type = 0x3dad3a95a0}, length = 12,\n" -"str = 0x7ffff2128500, hash = 7065186196740147912, state = 1, defenc = 0x0}" -msgstr "" -"(gdb) p *(PyUnicodeObject*)$6\n" -"$8 = {ob_base = {ob_refcnt = 33, ob_type = 0x3dad3a95a0}, length = 12,\n" -"str = 0x7ffff2128500, hash = 7065186196740147912, state = 1, defenc = 0x0}" - -#: ../../howto/gdb_helpers.rst:210 -msgid "``py-list``" -msgstr "``py-list``" - -#: ../../howto/gdb_helpers.rst:212 -msgid "" -"The extension adds a ``py-list`` command, which lists the Python source code " -"(if any) for the current frame in the selected thread. The current line is " -"marked with a \">\"::" -msgstr "" -"該擴充功能新增了一個 ``py-list`` 命令，該命令列出了所選執行緒中目前 frame 的 " -"Python 原始程式碼（如果有）。目前的列會標有 \">\"： ::" - -#: ../../howto/gdb_helpers.rst:216 -msgid "" -"(gdb) py-list\n" -" 901 if options.profile:\n" -" 902 options.profile = False\n" -" 903 profile_me()\n" -" 904 return\n" -" 905\n" -">906 u = UI()\n" -" 907 if not u.quit:\n" -" 908 try:\n" -" 909 gtk.main()\n" -" 910 except KeyboardInterrupt:\n" -" 911 # properly quit on a keyboard interrupt..." -msgstr "" -"(gdb) py-list\n" -" 901 if options.profile:\n" -" 902 options.profile = False\n" -" 903 profile_me()\n" -" 904 return\n" -" 905\n" -">906 u = UI()\n" -" 907 if not u.quit:\n" -" 908 try:\n" -" 909 gtk.main()\n" -" 910 except KeyboardInterrupt:\n" -" 911 # properly quit on a keyboard interrupt..." - -#: ../../howto/gdb_helpers.rst:229 -msgid "" -"Use ``py-list START`` to list at a different line number within the Python " -"source, and ``py-list START,END`` to list a specific range of lines within " -"the Python source." -msgstr "" -"使用 ``py-list START`` 列出 Python 原始碼中不同的列號，使用 ``py-list START," -"END`` 列出 Python 原始碼中特定範圍的列。" - -#: ../../howto/gdb_helpers.rst:234 -msgid "``py-up`` and ``py-down``" -msgstr "``py-up`` 和 ``py-down``" - -#: ../../howto/gdb_helpers.rst:236 -msgid "" -"The ``py-up`` and ``py-down`` commands are analogous to GDB's regular ``up`` " -"and ``down`` commands, but try to move at the level of CPython frames, " -"rather than C frames." -msgstr "" -"``py-up`` 和 ``py-down`` 命令類似於 GDB 的常規 ``up`` 和 ``down`` 命令，但嘗" -"試在 CPython frame 層級移動，而不是 C frame。" - -#: ../../howto/gdb_helpers.rst:240 -msgid "" -"GDB is not always able to read the relevant frame information, depending on " -"the optimization level with which CPython was compiled. Internally, the " -"commands look for C frames that are executing the default frame evaluation " -"function (that is, the core bytecode interpreter loop within CPython) and " -"look up the value of the related ``PyFrameObject *``." -msgstr "" -"GDB 並不總是能夠讀取相關的 frame 資訊，這取決於編譯 CPython 的最佳化等級。在" -"內部，這些指令會尋找正在執行預設 frame 計算 (evaluation) 函式（即 CPython 中" -"迴圈的核心位元組碼直譯器）的 C frame，並尋找相關 ``PyFrameObject *`` 的值。" - -#: ../../howto/gdb_helpers.rst:246 -msgid "They emit the frame number (at the C level) within the thread." -msgstr "它們在執行緒內發出（於 C 層級的）frame 編號。" - -#: ../../howto/gdb_helpers.rst:248 ../../howto/gdb_helpers.rst:320 -msgid "For example::" -msgstr "例如： ::" - -#: ../../howto/gdb_helpers.rst:250 -msgid "" -"(gdb) py-up\n" -"#37 Frame 0x9420b04, for file /usr/lib/python2.6/site-packages/\n" -"gnome_sudoku/main.py, line 906, in start_game ()\n" -" u = UI()\n" -"(gdb) py-up\n" -"#40 Frame 0x948e82c, for file /usr/lib/python2.6/site-packages/\n" -"gnome_sudoku/gnome_sudoku.py, line 22, in start_game(main=)\n" -" main.start_game()\n" -"(gdb) py-up\n" -"Unable to find an older python frame" -msgstr "" -"(gdb) py-up\n" -"#37 Frame 0x9420b04, for file /usr/lib/python2.6/site-packages/\n" -"gnome_sudoku/main.py, line 906, in start_game ()\n" -" u = UI()\n" -"(gdb) py-up\n" -"#40 Frame 0x948e82c, for file /usr/lib/python2.6/site-packages/\n" -"gnome_sudoku/gnome_sudoku.py, line 22, in start_game(main=)\n" -" main.start_game()\n" -"(gdb) py-up\n" -"Unable to find an older python frame" - -#: ../../howto/gdb_helpers.rst:261 -msgid "so we're at the top of the Python stack." -msgstr "所以現在我們處於 Python 堆疊的頂端。" - -#: ../../howto/gdb_helpers.rst:263 -msgid "" -"The frame numbers correspond to those displayed by GDB's standard " -"``backtrace`` command. The command skips C frames which are not executing " -"Python code." -msgstr "" -"frame 編號與 GDB 標準 ``backtrace`` 指令顯示的 frame 編號相對應。此指令會跳過" -"不執行 Python 程式碼的 C frame。" - -#: ../../howto/gdb_helpers.rst:267 -msgid "Going back down::" -msgstr "回到下面： ::" - -#: ../../howto/gdb_helpers.rst:269 -msgid "" -"(gdb) py-down\n" -"#37 Frame 0x9420b04, for file /usr/lib/python2.6/site-packages/gnome_sudoku/" -"main.py, line 906, in start_game ()\n" -" u = UI()\n" -"(gdb) py-down\n" -"#34 (unable to read python frame information)\n" -"(gdb) py-down\n" -"#23 (unable to read python frame information)\n" -"(gdb) py-down\n" -"#19 (unable to read python frame information)\n" -"(gdb) py-down\n" -"#14 Frame 0x99262ac, for file /usr/lib/python2.6/site-packages/gnome_sudoku/" -"game_selector.py, line 201, in run_swallowed_dialog " -"(self=, puzzle=None, saved_games=[{'gsd.auto_fills': 0, 'tracking': {}, " -"'trackers': {}, 'notes': [], 'saved_at': 1270084485, 'game': '7 8 0 0 0 0 0 " -"5 6 0 0 9 0 8 0 1 0 0 0 4 6 0 0 0 0 7 0 6 5 0 0 0 4 7 9 2 0 0 0 9 0 1 0 0 0 " -"3 9 7 6 0 0 0 1 8 0 6 0 0 0 0 2 8 0 0 0 5 0 4 0 6 0 0 2 1 0 0 0 0 0 4 5\\n7 " -"8 0 0 0 0 0 5 6 0 0 9 0 8 0 1 0 0 0 4 6 0 0 0 0 7 0 6 5 1 8 3 4 7 9 2 0 0 0 " -"9 0 1 0 0 0 3 9 7 6 0 0 0 1 8 0 6 0 0 0 0 2 8 0 0 0 5 0 4 0 6 0 0 2 1 0 0 0 " -"0 0 4 5', 'gsd.impossible_hints': 0, 'timer.__absolute_start_time__': , 'gsd.hints': 0, 'timer.active_time': , 'timer.total_time': }], dialog=, saved_game_model=, sudoku_maker=, main_page=0) " -"at remote 0x98fa6e4>, d=)\n" -" gtk.main()\n" -"(gdb) py-down\n" -"#8 (unable to read python frame information)\n" -"(gdb) py-down\n" -"Unable to find a newer python frame" -msgstr "" -"(gdb) py-down\n" -"#37 Frame 0x9420b04, for file /usr/lib/python2.6/site-packages/gnome_sudoku/" -"main.py, line 906, in start_game ()\n" -" u = UI()\n" -"(gdb) py-down\n" -"#34 (unable to read python frame information)\n" -"(gdb) py-down\n" -"#23 (unable to read python frame information)\n" -"(gdb) py-down\n" -"#19 (unable to read python frame information)\n" -"(gdb) py-down\n" -"#14 Frame 0x99262ac, for file /usr/lib/python2.6/site-packages/gnome_sudoku/" -"game_selector.py, line 201, in run_swallowed_dialog " -"(self=, puzzle=None, saved_games=[{'gsd.auto_fills': 0, 'tracking': {}, " -"'trackers': {}, 'notes': [], 'saved_at': 1270084485, 'game': '7 8 0 0 0 0 0 " -"5 6 0 0 9 0 8 0 1 0 0 0 4 6 0 0 0 0 7 0 6 5 0 0 0 4 7 9 2 0 0 0 9 0 1 0 0 0 " -"3 9 7 6 0 0 0 1 8 0 6 0 0 0 0 2 8 0 0 0 5 0 4 0 6 0 0 2 1 0 0 0 0 0 4 5\\n7 " -"8 0 0 0 0 0 5 6 0 0 9 0 8 0 1 0 0 0 4 6 0 0 0 0 7 0 6 5 1 8 3 4 7 9 2 0 0 0 " -"9 0 1 0 0 0 3 9 7 6 0 0 0 1 8 0 6 0 0 0 0 2 8 0 0 0 5 0 4 0 6 0 0 2 1 0 0 0 " -"0 0 4 5', 'gsd.impossible_hints': 0, 'timer.__absolute_start_time__': , 'gsd.hints': 0, 'timer.active_time': , 'timer.total_time': }], dialog=, saved_game_model=, sudoku_maker=, main_page=0) " -"at remote 0x98fa6e4>, d=)\n" -" gtk.main()\n" -"(gdb) py-down\n" -"#8 (unable to read python frame information)\n" -"(gdb) py-down\n" -"Unable to find a newer python frame" - -#: ../../howto/gdb_helpers.rst:289 -msgid "and we're at the bottom of the Python stack." -msgstr "我們現在處於 Python 堆疊的底部。" - -#: ../../howto/gdb_helpers.rst:291 -msgid "" -"Note that in Python 3.12 and newer, the same C stack frame can be used for " -"multiple Python stack frames. This means that ``py-up`` and ``py-down`` may " -"move multiple Python frames at once. For example::" -msgstr "" -"請注意，在 Python 3.12 及更高版本中，同一個 C 堆疊 frame 可用於多個 Python 堆" -"疊 frame。這意味著 ``py-up`` 和 ``py-down`` 可以一次移動多個 Python frame。例" -"如： ::" - -#: ../../howto/gdb_helpers.rst:295 -msgid "" -"(gdb) py-up\n" -"#6 Frame 0x7ffff7fb62b0, for file /tmp/rec.py, line 5, in recursive_function " -"(n=0)\n" -" time.sleep(5)\n" -"#6 Frame 0x7ffff7fb6240, for file /tmp/rec.py, line 7, in recursive_function " -"(n=1)\n" -" recursive_function(n-1)\n" -"#6 Frame 0x7ffff7fb61d0, for file /tmp/rec.py, line 7, in recursive_function " -"(n=2)\n" -" recursive_function(n-1)\n" -"#6 Frame 0x7ffff7fb6160, for file /tmp/rec.py, line 7, in recursive_function " -"(n=3)\n" -" recursive_function(n-1)\n" -"#6 Frame 0x7ffff7fb60f0, for file /tmp/rec.py, line 7, in recursive_function " -"(n=4)\n" -" recursive_function(n-1)\n" -"#6 Frame 0x7ffff7fb6080, for file /tmp/rec.py, line 7, in recursive_function " -"(n=5)\n" -" recursive_function(n-1)\n" -"#6 Frame 0x7ffff7fb6020, for file /tmp/rec.py, line 9, in ()\n" -" recursive_function(5)\n" -"(gdb) py-up\n" -"Unable to find an older python frame" -msgstr "" -"(gdb) py-up\n" -"#6 Frame 0x7ffff7fb62b0, for file /tmp/rec.py, line 5, in recursive_function " -"(n=0)\n" -" time.sleep(5)\n" -"#6 Frame 0x7ffff7fb6240, for file /tmp/rec.py, line 7, in recursive_function " -"(n=1)\n" -" recursive_function(n-1)\n" -"#6 Frame 0x7ffff7fb61d0, for file /tmp/rec.py, line 7, in recursive_function " -"(n=2)\n" -" recursive_function(n-1)\n" -"#6 Frame 0x7ffff7fb6160, for file /tmp/rec.py, line 7, in recursive_function " -"(n=3)\n" -" recursive_function(n-1)\n" -"#6 Frame 0x7ffff7fb60f0, for file /tmp/rec.py, line 7, in recursive_function " -"(n=4)\n" -" recursive_function(n-1)\n" -"#6 Frame 0x7ffff7fb6080, for file /tmp/rec.py, line 7, in recursive_function " -"(n=5)\n" -" recursive_function(n-1)\n" -"#6 Frame 0x7ffff7fb6020, for file /tmp/rec.py, line 9, in ()\n" -" recursive_function(5)\n" -"(gdb) py-up\n" -"Unable to find an older python frame" - -#: ../../howto/gdb_helpers.rst:315 -msgid "``py-bt``" -msgstr "``py-bt``" - -#: ../../howto/gdb_helpers.rst:317 -msgid "" -"The ``py-bt`` command attempts to display a Python-level backtrace of the " -"current thread." -msgstr "``py-bt`` 指令嘗試顯示目前執行緒的 Python 層級回溯。" - -#: ../../howto/gdb_helpers.rst:322 -msgid "" -"(gdb) py-bt\n" -"#8 (unable to read python frame information)\n" -"#11 Frame 0x9aead74, for file /usr/lib/python2.6/site-packages/gnome_sudoku/" -"dialog_swallower.py, line 48, in run_dialog " -"(self=, main_page=0) " -"at remote 0x98fa6e4>, d=)\n" -" gtk.main()\n" -"#14 Frame 0x99262ac, for file /usr/lib/python2.6/site-packages/gnome_sudoku/" -"game_selector.py, line 201, in run_swallowed_dialog " -"(self=, puzzle=None, saved_games=[{'gsd.auto_fills': 0, 'tracking': {}, " -"'trackers': {}, 'notes': [], 'saved_at': 1270084485, 'game': '7 8 0 0 0 0 0 " -"5 6 0 0 9 0 8 0 1 0 0 0 4 6 0 0 0 0 7 0 6 5 0 0 0 4 7 9 2 0 0 0 9 0 1 0 0 0 " -"3 9 7 6 0 0 0 1 8 0 6 0 0 0 0 2 8 0 0 0 5 0 4 0 6 0 0 2 1 0 0 0 0 0 4 5\\n7 " -"8 0 0 0 0 0 5 6 0 0 9 0 8 0 1 0 0 0 4 6 0 0 0 0 7 0 6 5 1 8 3 4 7 9 2 0 0 0 " -"9 0 1 0 0 0 3 9 7 6 0 0 0 1 8 0 6 0 0 0 0 2 8 0 0 0 5 0 4 0 6 0 0 2 1 0 0 0 " -"0 0 4 5', 'gsd.impossible_hints': 0, 'timer.__absolute_start_time__': , 'gsd.hints': 0, 'timer.active_time': , 'timer.total_time': }], dialog=, saved_game_model=, sudoku_maker=)\n" -" main.start_game()" -msgstr "" -"(gdb) py-bt\n" -"#8 (unable to read python frame information)\n" -"#11 Frame 0x9aead74, for file /usr/lib/python2.6/site-packages/gnome_sudoku/" -"dialog_swallower.py, line 48, in run_dialog " -"(self=, main_page=0) " -"at remote 0x98fa6e4>, d=)\n" -" gtk.main()\n" -"#14 Frame 0x99262ac, for file /usr/lib/python2.6/site-packages/gnome_sudoku/" -"game_selector.py, line 201, in run_swallowed_dialog " -"(self=, puzzle=None, saved_games=[{'gsd.auto_fills': 0, 'tracking': {}, " -"'trackers': {}, 'notes': [], 'saved_at': 1270084485, 'game': '7 8 0 0 0 0 0 " -"5 6 0 0 9 0 8 0 1 0 0 0 4 6 0 0 0 0 7 0 6 5 0 0 0 4 7 9 2 0 0 0 9 0 1 0 0 0 " -"3 9 7 6 0 0 0 1 8 0 6 0 0 0 0 2 8 0 0 0 5 0 4 0 6 0 0 2 1 0 0 0 0 0 4 5\\n7 " -"8 0 0 0 0 0 5 6 0 0 9 0 8 0 1 0 0 0 4 6 0 0 0 0 7 0 6 5 1 8 3 4 7 9 2 0 0 0 " -"9 0 1 0 0 0 3 9 7 6 0 0 0 1 8 0 6 0 0 0 0 2 8 0 0 0 5 0 4 0 6 0 0 2 1 0 0 0 " -"0 0 4 5', 'gsd.impossible_hints': 0, 'timer.__absolute_start_time__': , 'gsd.hints': 0, 'timer.active_time': , 'timer.total_time': }], dialog=, saved_game_model=, sudoku_maker=)\n" -" main.start_game()" - -#: ../../howto/gdb_helpers.rst:336 -msgid "" -"The frame numbers correspond to those displayed by GDB's standard " -"``backtrace`` command." -msgstr " frame 編號與 GDB 標準 ``backtrace`` 指令顯示的 frame 編號相對應。" - -#: ../../howto/gdb_helpers.rst:340 -msgid "``py-print``" -msgstr "``py-print``" - -#: ../../howto/gdb_helpers.rst:342 -msgid "" -"The ``py-print`` command looks up a Python name and tries to print it. It " -"looks in locals within the current thread, then globals, then finally " -"builtins::" -msgstr "" -"``py-print`` 命令查找 Python 名稱並嘗試列印它。它在目前執行緒中尋找局部變數，" -"然後是全域變數，最後是內建變數： ::" - -#: ../../howto/gdb_helpers.rst:346 -msgid "" -"(gdb) py-print self\n" -"local 'self' = ,\n" -"main_page=0) at remote 0x98fa6e4>\n" -"(gdb) py-print __name__\n" -"global '__name__' = 'gnome_sudoku.dialog_swallower'\n" -"(gdb) py-print len\n" -"builtin 'len' = \n" -"(gdb) py-print scarlet_pimpernel\n" -"'scarlet_pimpernel' not found" -msgstr "" -"(gdb) py-print self\n" -"local 'self' = ,\n" -"main_page=0) at remote 0x98fa6e4>\n" -"(gdb) py-print __name__\n" -"global '__name__' = 'gnome_sudoku.dialog_swallower'\n" -"(gdb) py-print len\n" -"builtin 'len' = \n" -"(gdb) py-print scarlet_pimpernel\n" -"'scarlet_pimpernel' not found" - -#: ../../howto/gdb_helpers.rst:356 -msgid "" -"If the current C frame corresponds to multiple Python frames, ``py-print`` " -"only considers the first one." -msgstr "如果目前 C frame 對應多個 Python frame，則 ``py-print`` 僅考慮第一個。" - -#: ../../howto/gdb_helpers.rst:360 -msgid "``py-locals``" -msgstr "``py-locals``" - -#: ../../howto/gdb_helpers.rst:362 -msgid "" -"The ``py-locals`` command looks up all Python locals within the current " -"Python frame in the selected thread, and prints their representations::" -msgstr "" -"``py-locals`` 命令尋找所選執行緒中目前 Python frame 內的所有 Python 局部變" -"數，並列印它們的表示： ::" - -#: ../../howto/gdb_helpers.rst:365 -msgid "" -"(gdb) py-locals\n" -"self = ,\n" -"main_page=0) at remote 0x98fa6e4>\n" -"d = " -msgstr "" -"(gdb) py-locals\n" -"self = ,\n" -"main_page=0) at remote 0x98fa6e4>\n" -"d = " - -#: ../../howto/gdb_helpers.rst:370 -msgid "" -"If the current C frame corresponds to multiple Python frames, locals from " -"all of them will be shown::" -msgstr "" -"如果目前 C frame 對應於多個 Python frame，則會顯示所有這些 frame 的局部變數：" - -#: ../../howto/gdb_helpers.rst:373 -msgid "" -"(gdb) py-locals\n" -"Locals for recursive_function\n" -"n = 0\n" -"Locals for recursive_function\n" -"n = 1\n" -"Locals for recursive_function\n" -"n = 2\n" -"Locals for recursive_function\n" -"n = 3\n" -"Locals for recursive_function\n" -"n = 4\n" -"Locals for recursive_function\n" -"n = 5\n" -"Locals for " -msgstr "" -"(gdb) py-locals\n" -"Locals for recursive_function\n" -"n = 0\n" -"Locals for recursive_function\n" -"n = 1\n" -"Locals for recursive_function\n" -"n = 2\n" -"Locals for recursive_function\n" -"n = 3\n" -"Locals for recursive_function\n" -"n = 4\n" -"Locals for recursive_function\n" -"n = 5\n" -"Locals for " - -#: ../../howto/gdb_helpers.rst:390 -msgid "Use with GDB commands" -msgstr "與 GDB 指令一起使用" - -#: ../../howto/gdb_helpers.rst:392 -msgid "" -"The extension commands complement GDB's built-in commands. For example, you " -"can use a frame numbers shown by ``py-bt`` with the ``frame`` command to go " -"a specific frame within the selected thread, like this::" -msgstr "" -"擴充命令補充了 GDB 的內建命令。例如，你可以將 ``py-bt`` 顯示的 frame 編號與 " -"``frame`` 命令一同使用來跳到所選執行緒中的特定 frame，如下所示： ::" - -#: ../../howto/gdb_helpers.rst:396 -msgid "" -"(gdb) py-bt\n" -"(output snipped)\n" -"#68 Frame 0xaa4560, for file Lib/test/regrtest.py, line 1548, in " -"()\n" -" main()\n" -"(gdb) frame 68\n" -"#68 0x00000000004cd1e6 in PyEval_EvalFrameEx (f=Frame 0xaa4560, for file Lib/" -"test/regrtest.py, line 1548, in (), throwflag=0) at Python/ceval." -"c:2665\n" -"2665 x = call_function(&sp, oparg);\n" -"(gdb) py-list\n" -"1543 # Run the tests in a context manager that temporary changes the " -"CWD to a\n" -"1544 # temporary and writable directory. If it's not possible to " -"create or\n" -"1545 # change the CWD, the original CWD will be used. The original " -"CWD is\n" -"1546 # available from test_support.SAVEDCWD.\n" -"1547 with test_support.temp_cwd(TESTCWD, quiet=True):\n" -">1548 main()" -msgstr "" -"(gdb) py-bt\n" -"(output snipped)\n" -"#68 Frame 0xaa4560, for file Lib/test/regrtest.py, line 1548, in " -"()\n" -" main()\n" -"(gdb) frame 68\n" -"#68 0x00000000004cd1e6 in PyEval_EvalFrameEx (f=Frame 0xaa4560, for file Lib/" -"test/regrtest.py, line 1548, in (), throwflag=0) at Python/ceval." -"c:2665\n" -"2665 x = call_function(&sp, oparg);\n" -"(gdb) py-list\n" -"1543 # 在暫時改變 CWD 到一個臨時且可寫入的目錄的\n" -"1544 # 情境管理器中運行測試。\n" -"1545 # 如果無法建立或更改 CWD，則使用原始的 CWD。\n" -"1546 # 原始 CWD 可從 test_support.SAVEDCWD 獲得。\n" -"1547 with test_support.temp_cwd(TESTCWD, quiet=True):\n" -">1548 main()" - -#: ../../howto/gdb_helpers.rst:411 -msgid "" -"The ``info threads`` command will give you a list of the threads within the " -"process, and you can use the ``thread`` command to select a different one::" -msgstr "" -"``info threads`` 命令將為你提供行程內的執行緒串列，你可以使用 ``thread`` 命令" -"選擇不同的執行緒： ::" - -#: ../../howto/gdb_helpers.rst:414 -msgid "" -"(gdb) info threads\n" -" 105 Thread 0x7fffefa18710 (LWP 10260) sem_wait () at ../nptl/sysdeps/unix/" -"sysv/linux/x86_64/sem_wait.S:86\n" -" 104 Thread 0x7fffdf5fe710 (LWP 10259) sem_wait () at ../nptl/sysdeps/unix/" -"sysv/linux/x86_64/sem_wait.S:86\n" -"* 1 Thread 0x7ffff7fe2700 (LWP 10145) 0x00000038e46d73e3 in select () at ../" -"sysdeps/unix/syscall-template.S:82" -msgstr "" -"(gdb) info threads\n" -" 105 Thread 0x7fffefa18710 (LWP 10260) sem_wait () at ../nptl/sysdeps/unix/" -"sysv/linux/x86_64/sem_wait.S:86\n" -" 104 Thread 0x7fffdf5fe710 (LWP 10259) sem_wait () at ../nptl/sysdeps/unix/" -"sysv/linux/x86_64/sem_wait.S:86\n" -"* 1 Thread 0x7ffff7fe2700 (LWP 10145) 0x00000038e46d73e3 in select () at ../" -"sysdeps/unix/syscall-template.S:82" - -#: ../../howto/gdb_helpers.rst:419 -msgid "" -"You can use ``thread apply all COMMAND`` or (``t a a COMMAND`` for short) to " -"run a command on all threads. With ``py-bt``, this lets you see what every " -"thread is doing at the Python level::" -msgstr "" -"你可以使用 ``thread apply all COMMAND``\\ （或簡短地用 ``t a a COMMAND``）在" -"所有執行緒上執行命令。使用 ``py-bt`` 你可以看到每個執行緒在 Python 層級正在做" -"什麼： ::" - -#: ../../howto/gdb_helpers.rst:423 -msgid "" -"(gdb) t a a py-bt\n" -"\n" -"Thread 105 (Thread 0x7fffefa18710 (LWP 10260)):\n" -"#5 Frame 0x7fffd00019d0, for file /home/david/coding/python-svn/Lib/" -"threading.py, line 155, in _acquire_restore " -"(self=<_RLock(_Verbose__verbose=False, _RLock__owner=140737354016512, " -"_RLock__block=, _RLock__count=1) at remote " -"0xd7ff40>, count_owner=(1, 140737213728528), count=1, " -"owner=140737213728528)\n" -" self.__block.acquire()\n" -"#8 Frame 0x7fffac001640, for file /home/david/coding/python-svn/Lib/" -"threading.py, line 269, in wait " -"(self=<_Condition(_Condition__lock=<_RLock(_Verbose__verbose=False, " -"_RLock__owner=140737354016512, _RLock__block=, _RLock__count=1) at remote 0xd7ff40>, acquire=, _is_owned=, " -"_release_save=, release=, _acquire_restore=, " -"_Verbose__verbose=False, _Condition__waiters=[]) at remote 0xd7fd10>, " -"timeout=None, waiter=, saved_state=(1, " -"140737213728528))\n" -" self._acquire_restore(saved_state)\n" -"#12 Frame 0x7fffb8001a10, for file /home/david/coding/python-svn/Lib/test/" -"lock_tests.py, line 348, in f ()\n" -" cond.wait()\n" -"#16 Frame 0x7fffb8001c40, for file /home/david/coding/python-svn/Lib/test/" -"lock_tests.py, line 37, in task (tid=140737213728528)\n" -" f()\n" -"\n" -"Thread 104 (Thread 0x7fffdf5fe710 (LWP 10259)):\n" -"#5 Frame 0x7fffe4001580, for file /home/david/coding/python-svn/Lib/" -"threading.py, line 155, in _acquire_restore " -"(self=<_RLock(_Verbose__verbose=False, _RLock__owner=140737354016512, " -"_RLock__block=, _RLock__count=1) at remote " -"0xd7ff40>, count_owner=(1, 140736940992272), count=1, " -"owner=140736940992272)\n" -" self.__block.acquire()\n" -"#8 Frame 0x7fffc8002090, for file /home/david/coding/python-svn/Lib/" -"threading.py, line 269, in wait " -"(self=<_Condition(_Condition__lock=<_RLock(_Verbose__verbose=False, " -"_RLock__owner=140737354016512, _RLock__block=, _RLock__count=1) at remote 0xd7ff40>, acquire=, _is_owned=, " -"_release_save=, release=, _acquire_restore=, " -"_Verbose__verbose=False, _Condition__waiters=[]) at remote 0xd7fd10>, " -"timeout=None, waiter=, saved_state=(1, " -"140736940992272))\n" -" self._acquire_restore(saved_state)\n" -"#12 Frame 0x7fffac001c90, for file /home/david/coding/python-svn/Lib/test/" -"lock_tests.py, line 348, in f ()\n" -" cond.wait()\n" -"#16 Frame 0x7fffac0011c0, for file /home/david/coding/python-svn/Lib/test/" -"lock_tests.py, line 37, in task (tid=140736940992272)\n" -" f()\n" -"\n" -"Thread 1 (Thread 0x7ffff7fe2700 (LWP 10145)):\n" -"#5 Frame 0xcb5380, for file /home/david/coding/python-svn/Lib/test/" -"lock_tests.py, line 16, in _wait ()\n" -" time.sleep(0.01)\n" -"#8 Frame 0x7fffd00024a0, for file /home/david/coding/python-svn/Lib/test/" -"lock_tests.py, line 378, in _check_notify " -"(self=, skipped=[], _mirrorOutput=False, testsRun=39, " -"buffer=False, _original_stderr=, " -"_stdout_buffer=, " -"_stderr_buffer=, " -"_moduleSetUpFailed=False, expectedFailures=[], errors=[], " -"_previousTestClass=, unexpectedSuccesses=[], " -"failures=[], shouldStop=False, failfast=False) at remote 0xc185a0>, " -"_threads=(0,), _cleanups=[], _type_equality_funcs={: , : " -", : " -", : " -", , _RLock__count=1) at remote " -"0xd7ff40>, count_owner=(1, 140737213728528), count=1, " -"owner=140737213728528)\n" -" self.__block.acquire()\n" -"#8 Frame 0x7fffac001640, for file /home/david/coding/python-svn/Lib/" -"threading.py, line 269, in wait " -"(self=<_Condition(_Condition__lock=<_RLock(_Verbose__verbose=False, " -"_RLock__owner=140737354016512, _RLock__block=, _RLock__count=1) at remote 0xd7ff40>, acquire=, _is_owned=, " -"_release_save=, release=, _acquire_restore=, " -"_Verbose__verbose=False, _Condition__waiters=[]) at remote 0xd7fd10>, " -"timeout=None, waiter=, saved_state=(1, " -"140737213728528))\n" -" self._acquire_restore(saved_state)\n" -"#12 Frame 0x7fffb8001a10, for file /home/david/coding/python-svn/Lib/test/" -"lock_tests.py, line 348, in f ()\n" -" cond.wait()\n" -"#16 Frame 0x7fffb8001c40, for file /home/david/coding/python-svn/Lib/test/" -"lock_tests.py, line 37, in task (tid=140737213728528)\n" -" f()\n" -"\n" -"Thread 104 (Thread 0x7fffdf5fe710 (LWP 10259)):\n" -"#5 Frame 0x7fffe4001580, for file /home/david/coding/python-svn/Lib/" -"threading.py, line 155, in _acquire_restore " -"(self=<_RLock(_Verbose__verbose=False, _RLock__owner=140737354016512, " -"_RLock__block=, _RLock__count=1) at remote " -"0xd7ff40>, count_owner=(1, 140736940992272), count=1, " -"owner=140736940992272)\n" -" self.__block.acquire()\n" -"#8 Frame 0x7fffc8002090, for file /home/david/coding/python-svn/Lib/" -"threading.py, line 269, in wait " -"(self=<_Condition(_Condition__lock=<_RLock(_Verbose__verbose=False, " -"_RLock__owner=140737354016512, _RLock__block=, _RLock__count=1) at remote 0xd7ff40>, acquire=, _is_owned=, " -"_release_save=, release=, _acquire_restore=, " -"_Verbose__verbose=False, _Condition__waiters=[]) at remote 0xd7fd10>, " -"timeout=None, waiter=, saved_state=(1, " -"140736940992272))\n" -" self._acquire_restore(saved_state)\n" -"#12 Frame 0x7fffac001c90, for file /home/david/coding/python-svn/Lib/test/" -"lock_tests.py, line 348, in f ()\n" -" cond.wait()\n" -"#16 Frame 0x7fffac0011c0, for file /home/david/coding/python-svn/Lib/test/" -"lock_tests.py, line 37, in task (tid=140736940992272)\n" -" f()\n" -"\n" -"Thread 1 (Thread 0x7ffff7fe2700 (LWP 10145)):\n" -"#5 Frame 0xcb5380, for file /home/david/coding/python-svn/Lib/test/" -"lock_tests.py, line 16, in _wait ()\n" -" time.sleep(0.01)\n" -"#8 Frame 0x7fffd00024a0, for file /home/david/coding/python-svn/Lib/test/" -"lock_tests.py, line 378, in _check_notify " -"(self=, skipped=[], _mirrorOutput=False, testsRun=39, " -"buffer=False, _original_stderr=, " -"_stdout_buffer=, " -"_stderr_buffer=, " -"_moduleSetUpFailed=False, expectedFailures=[], errors=[], " -"_previousTestClass=, unexpectedSuccesses=[], " -"failures=[], shouldStop=False, failfast=False) at remote 0xc185a0>, " -"_threads=(0,), _cleanups=[], _type_equality_funcs={: , : " -", : " -", : " -", , 2024 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-12-06 00:14+0000\n" +"PO-Revision-Date: 2024-05-11 14:42+0800\n" +"Last-Translator: Matt Wang \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" + +#: ../../howto/gdb_helpers.rst:5 +msgid "Debugging C API extensions and CPython Internals with GDB" +msgstr "使用 GDB 來為 C API 擴充功能和 CPython 內部偵錯" + +#: ../../howto/gdb_helpers.rst:9 +msgid "" +"This document explains how the Python GDB extension, ``python-gdb.py``, can " +"be used with the GDB debugger to debug CPython extensions and the CPython " +"interpreter itself." +msgstr "" +"本文件解釋如何將 Python GDB 擴充功能 ``python-gdb.py`` 與 GDB 偵錯器一起使用" +"來為 CPython 擴充功能和 CPython 直譯器本身偵錯。" + +#: ../../howto/gdb_helpers.rst:13 +msgid "" +"When debugging low-level problems such as crashes or deadlocks, a low-level " +"debugger, such as GDB, is useful to diagnose and correct the issue. By " +"default, GDB (or any of its front-ends) doesn't support high-level " +"information specific to the CPython interpreter." +msgstr "" +"在為崩潰或死鎖等低階問題幀錯時，低階偵錯器（例如 GDB）對於診斷和修正問題非常" +"有用。預設情況下，GDB（或其任何前端）不支援特定於 CPython 直譯器的高階資訊。" + +#: ../../howto/gdb_helpers.rst:18 +msgid "" +"The ``python-gdb.py`` extension adds CPython interpreter information to GDB. " +"The extension helps introspect the stack of currently executing Python " +"functions. Given a Python object represented by a :c:expr:`PyObject *` " +"pointer, the extension surfaces the type and value of the object." +msgstr "" +"``python-gdb.py`` 擴充功能將 CPython 直譯器資訊新增至 GDB。此擴充有助於內省 " +"(introspect) 目前執行的 Python 函式的堆疊。給定一個由 :c:expr:`PyObject *` 指" +"標表示的 Python 物件，擴充功能會顯示該物件的型別和值。" + +#: ../../howto/gdb_helpers.rst:23 +msgid "" +"Developers who are working on CPython extensions or tinkering with parts of " +"CPython that are written in C can use this document to learn how to use the " +"``python-gdb.py`` extension with GDB." +msgstr "" +"正在開發 CPython 擴充功能或修補用 C 編寫之 CPython 部分的開發人員可以使用本文" +"件來學習如何將 ``python-gdb.py`` 擴充功能與 GDB 一起使用。" + +#: ../../howto/gdb_helpers.rst:29 +msgid "" +"This document assumes that you are familiar with the basics of GDB and the " +"CPython C API. It consolidates guidance from the `devguide `_ and the `Python wiki `_." +msgstr "" +"本文件假設你熟悉 GDB 和 CPython C API 的基礎知識。它整合了 `devguide " +"`_ 和 `Python wiki `_ 的指引。" + +#: ../../howto/gdb_helpers.rst:36 +msgid "Prerequisites" +msgstr "先決條件" + +#: ../../howto/gdb_helpers.rst:38 +msgid "You need to have:" +msgstr "你需要有：" + +#: ../../howto/gdb_helpers.rst:40 +msgid "" +"GDB 7 or later. (For earlier versions of GDB, see ``Misc/gdbinit`` in the " +"sources of Python 3.11 or earlier.)" +msgstr "" +"GDB 7 或更之後的版本。（對於早期版本的 GDB，請參閱 Python 3.11 或更早版本的原" +"始程式碼中的 ``Misc/gdbinit``。）" + +#: ../../howto/gdb_helpers.rst:42 +msgid "" +"GDB-compatible debugging information for Python and any extension you are " +"debugging." +msgstr "對 Python 和你在偵錯的任何擴充功能來說的與 GDB 相容的偵錯資訊。" + +#: ../../howto/gdb_helpers.rst:44 +msgid "The ``python-gdb.py`` extension." +msgstr "``python-gdb.py`` 擴充。" + +#: ../../howto/gdb_helpers.rst:46 +msgid "" +"The extension is built with Python, but might be distributed separately or " +"not at all. Below, we include tips for a few common systems as examples. " +"Note that even if the instructions match your system, they might be outdated." +msgstr "" +"該擴充功能是用 Python 建置的，但可能會單獨發布或根本不發布。以下我們將一些常" +"見系統的提示作為範例。請注意，即使說明與你的系統匹配，它們也可能已過時。" + +#: ../../howto/gdb_helpers.rst:52 +msgid "Setup with Python built from source" +msgstr "使用從原始碼建置的 Python 進行設定" + +#: ../../howto/gdb_helpers.rst:54 +msgid "" +"When you build CPython from source, debugging information should be " +"available, and the build should add a ``python-gdb.py`` file to the root " +"directory of your repository." +msgstr "" +"當你從原始程式碼建立 CPython 時，偵錯資訊應該可用，並且建置應該將 ``python-" +"gdb.py`` 檔案新增至儲存庫的根目錄中。" + +#: ../../howto/gdb_helpers.rst:58 +msgid "" +"To activate support, you must add the directory containing ``python-gdb.py`` " +"to GDB's \"auto-load-safe-path\". If you haven't done this, recent versions " +"of GDB will print out a warning with instructions on how to do this." +msgstr "" +"若要啟用支援，你必須將包含 ``python-gdb.py`` 的目錄新增至 GDB 的 \"auto-load-" +"safe-path\"。如果你還沒有這樣做，最新版本的 GDB 將列印警告，其中包含有關如何" +"執行此操作的說明。" + +#: ../../howto/gdb_helpers.rst:65 +msgid "" +"If you do not see instructions for your version of GDB, put this in your " +"configuration file (``~/.gdbinit`` or ``~/.config/gdb/gdbinit``)::" +msgstr "" +"如果你沒有看到適合你的 GDB 版本的說明，請將其放入你的設定檔中（``~/." +"gdbinit`` 或 ``~/.config/gdb/gdbinit``）：" + +#: ../../howto/gdb_helpers.rst:68 +msgid "add-auto-load-safe-path /path/to/cpython" +msgstr "add-auto-load-safe-path /path/to/cpython" + +#: ../../howto/gdb_helpers.rst:70 +msgid "You can also add multiple paths, separated by ``:``." +msgstr "你也可以新增多個路徑，要以 ``:`` 分隔。" + +#: ../../howto/gdb_helpers.rst:74 +msgid "Setup for Python from a Linux distro" +msgstr "從 Linux 發行版設定 Python" + +#: ../../howto/gdb_helpers.rst:76 +msgid "" +"Most Linux systems provide debug information for the system Python in a " +"package called ``python-debuginfo``, ``python-dbg`` or similar. For example:" +msgstr "" +"大多數 Linux 系統在名為 ``python-debuginfo``、``python-dbg`` 或類似的套件中提" +"供系統 Python 的偵錯資訊。例如：" + +#: ../../howto/gdb_helpers.rst:80 +msgid "Fedora:" +msgstr "Fedora：" + +#: ../../howto/gdb_helpers.rst:82 +msgid "" +"sudo dnf install gdb\n" +"sudo dnf debuginfo-install python3" +msgstr "" +"sudo dnf install gdb\n" +"sudo dnf debuginfo-install python3" + +#: ../../howto/gdb_helpers.rst:87 +msgid "Ubuntu:" +msgstr "Ubuntu：" + +#: ../../howto/gdb_helpers.rst:89 +msgid "sudo apt install gdb python3-dbg" +msgstr "sudo apt install gdb python3-dbg" + +#: ../../howto/gdb_helpers.rst:93 +msgid "" +"On several recent Linux systems, GDB can download debugging symbols " +"automatically using *debuginfod*. However, this will not install the " +"``python-gdb.py`` extension; you generally do need to install the debug info " +"package separately." +msgstr "" +"在最近的幾個 Linux 系統上，GDB 可以使用 *debuginfod* 自動下載偵錯符號。但是這" +"不會安裝 ``python-gdb.py`` 擴充功能；你通常需要另外安裝偵錯資訊套件。" + +#: ../../howto/gdb_helpers.rst:100 +msgid "Using the Debug build and Development mode" +msgstr "使用偵錯建置與使用開發模式" + +#: ../../howto/gdb_helpers.rst:102 +msgid "For easier debugging, you might want to:" +msgstr "為了更輕鬆地進行偵錯，你可能需要：" + +#: ../../howto/gdb_helpers.rst:104 +msgid "" +"Use a :ref:`debug build ` of Python. (When building from " +"source, use ``configure --with-pydebug``. On Linux distros, install and run " +"a package like ``python-debug`` or ``python-dbg``, if available.)" +msgstr "" +"使用 Python 的\\ :ref:`偵錯建置 `。（從原始碼建置時，請使用 " +"``configure --with-pydebug``。在 Linux 發行版上，安裝並執行諸如 ``python-" +"debug`` 或 ``python-dbg`` 之類的套件（如果可用））。" + +#: ../../howto/gdb_helpers.rst:107 +msgid "Use the runtime :ref:`development mode ` (``-X dev``)." +msgstr "使用 runtime :ref:`開發模式 ` (``-X dev``)。" + +#: ../../howto/gdb_helpers.rst:109 +msgid "" +"Both enable extra assertions and disable some optimizations. Sometimes this " +"hides the bug you are trying to find, but in most cases they make the " +"process easier." +msgstr "" +"兩者都啟用額外的斷言 (assertion) 並停用一些最佳化。有時這會隱藏你試圖想尋找的" +"錯誤，但在大多數情況下，它們會使過程變得更容易。" + +#: ../../howto/gdb_helpers.rst:115 +msgid "Using the ``python-gdb`` extension" +msgstr "使用 ``python-gdb`` 擴充功能" + +#: ../../howto/gdb_helpers.rst:117 +msgid "" +"When the extension is loaded, it provides two main features: pretty printers " +"for Python values, and additional commands." +msgstr "載入擴充功能後，它提供兩個主要功能：Python 值的漂亮列印器和附加命令。" + +#: ../../howto/gdb_helpers.rst:121 +msgid "Pretty-printers" +msgstr "漂亮列印器" + +#: ../../howto/gdb_helpers.rst:123 +msgid "" +"This is what a GDB backtrace looks like (truncated) when this extension is " +"enabled::" +msgstr "這是啟用此擴充功能時 GDB 回溯 (backtrace) 的樣子（有被截斷）：" + +#: ../../howto/gdb_helpers.rst:126 +msgid "" +"#0 0x000000000041a6b1 in PyObject_Malloc (nbytes=Cannot access memory at " +"address 0x7fffff7fefe8\n" +") at Objects/obmalloc.c:748\n" +"#1 0x000000000041b7c0 in _PyObject_DebugMallocApi (id=111 'o', nbytes=24) " +"at Objects/obmalloc.c:1445\n" +"#2 0x000000000041b717 in _PyObject_DebugMalloc (nbytes=24) at Objects/" +"obmalloc.c:1412\n" +"#3 0x000000000044060a in _PyUnicode_New (length=11) at Objects/" +"unicodeobject.c:346\n" +"#4 0x00000000004466aa in PyUnicodeUCS2_DecodeUTF8Stateful (s=0x5c2b8d " +"\"__lltrace__\", size=11, errors=0x0, consumed=\n" +" 0x0) at Objects/unicodeobject.c:2531\n" +"#5 0x0000000000446647 in PyUnicodeUCS2_DecodeUTF8 (s=0x5c2b8d " +"\"__lltrace__\", size=11, errors=0x0)\n" +" at Objects/unicodeobject.c:2495\n" +"#6 0x0000000000440d1b in PyUnicodeUCS2_FromStringAndSize (u=0x5c2b8d " +"\"__lltrace__\", size=11)\n" +" at Objects/unicodeobject.c:551\n" +"#7 0x0000000000440d94 in PyUnicodeUCS2_FromString (u=0x5c2b8d " +"\"__lltrace__\") at Objects/unicodeobject.c:569\n" +"#8 0x0000000000584abd in PyDict_GetItemString (v=\n" +" {'Yuck': , '__builtins__': , '__file__': 'Lib/test/crashers/nasty_eq_vs_dict.py', " +"'__package__': None, 'y': , 'dict': {0: 0, 1: " +"1, 2: 2, 3: 3}, '__cached__': None, '__name__': '__main__', 'z': , '__doc__': None}, key=\n" +" 0x5c2b8d \"__lltrace__\") at Objects/dictobject.c:2171" +msgstr "" +"#0 0x000000000041a6b1 in PyObject_Malloc (nbytes=Cannot access memory at " +"address 0x7fffff7fefe8\n" +") at Objects/obmalloc.c:748\n" +"#1 0x000000000041b7c0 in _PyObject_DebugMallocApi (id=111 'o', nbytes=24) " +"at Objects/obmalloc.c:1445\n" +"#2 0x000000000041b717 in _PyObject_DebugMalloc (nbytes=24) at Objects/" +"obmalloc.c:1412\n" +"#3 0x000000000044060a in _PyUnicode_New (length=11) at Objects/" +"unicodeobject.c:346\n" +"#4 0x00000000004466aa in PyUnicodeUCS2_DecodeUTF8Stateful (s=0x5c2b8d " +"\"__lltrace__\", size=11, errors=0x0, consumed=\n" +" 0x0) at Objects/unicodeobject.c:2531\n" +"#5 0x0000000000446647 in PyUnicodeUCS2_DecodeUTF8 (s=0x5c2b8d " +"\"__lltrace__\", size=11, errors=0x0)\n" +" at Objects/unicodeobject.c:2495\n" +"#6 0x0000000000440d1b in PyUnicodeUCS2_FromStringAndSize (u=0x5c2b8d " +"\"__lltrace__\", size=11)\n" +" at Objects/unicodeobject.c:551\n" +"#7 0x0000000000440d94 in PyUnicodeUCS2_FromString (u=0x5c2b8d " +"\"__lltrace__\") at Objects/unicodeobject.c:569\n" +"#8 0x0000000000584abd in PyDict_GetItemString (v=\n" +" {'Yuck': , '__builtins__': , '__file__': 'Lib/test/crashers/nasty_eq_vs_dict.py', " +"'__package__': None, 'y': , 'dict': {0: 0, 1: " +"1, 2: 2, 3: 3}, '__cached__': None, '__name__': '__main__', 'z': , '__doc__': None}, key=\n" +" 0x5c2b8d \"__lltrace__\") at Objects/dictobject.c:2171" + +#: ../../howto/gdb_helpers.rst:142 +msgid "" +"Notice how the dictionary argument to ``PyDict_GetItemString`` is displayed " +"as its ``repr()``, rather than an opaque ``PyObject *`` pointer." +msgstr "" +"請注意 ``PyDict_GetItemString`` 的字典引數如何顯示為其 ``repr()``，而不是不透" +"明的 ``PyObject *`` 指標。" + +#: ../../howto/gdb_helpers.rst:145 +msgid "" +"The extension works by supplying a custom printing routine for values of " +"type ``PyObject *``. If you need to access lower-level details of an " +"object, then cast the value to a pointer of the appropriate type. For " +"example::" +msgstr "" +"該擴充功能透過為 ``PyObject *`` 型別的值提供自訂列印例程來運作。如果需要存取" +"物件較低階的詳細資訊，請將值轉換為適當型別的指標。例如： ::" + +#: ../../howto/gdb_helpers.rst:149 +msgid "" +"(gdb) p globals\n" +"$1 = {'__builtins__': , '__name__':\n" +"'__main__', 'ctypes': , '__doc__': None,\n" +"'__package__': None}\n" +"\n" +"(gdb) p *(PyDictObject*)globals\n" +"$2 = {ob_refcnt = 3, ob_type = 0x3dbdf85820, ma_fill = 5, ma_used = 5,\n" +"ma_mask = 7, ma_table = 0x63d0f8, ma_lookup = 0x3dbdc7ea70\n" +", ma_smalltable = {{me_hash = 7065186196740147912,\n" +"me_key = '__builtins__', me_value = },\n" +"{me_hash = -368181376027291943, me_key = '__name__',\n" +"me_value ='__main__'}, {me_hash = 0, me_key = 0x0, me_value = 0x0},\n" +"{me_hash = 0, me_key = 0x0, me_value = 0x0},\n" +"{me_hash = -9177857982131165996, me_key = 'ctypes',\n" +"me_value = },\n" +"{me_hash = -8518757509529533123, me_key = '__doc__', me_value = None},\n" +"{me_hash = 0, me_key = 0x0, me_value = 0x0}, {\n" +" me_hash = 6614918939584953775, me_key = '__package__', me_value = None}}}" +msgstr "" +"(gdb) p globals\n" +"$1 = {'__builtins__': , '__name__':\n" +"'__main__', 'ctypes': , '__doc__': None,\n" +"'__package__': None}\n" +"\n" +"(gdb) p *(PyDictObject*)globals\n" +"$2 = {ob_refcnt = 3, ob_type = 0x3dbdf85820, ma_fill = 5, ma_used = 5,\n" +"ma_mask = 7, ma_table = 0x63d0f8, ma_lookup = 0x3dbdc7ea70\n" +", ma_smalltable = {{me_hash = 7065186196740147912,\n" +"me_key = '__builtins__', me_value = },\n" +"{me_hash = -368181376027291943, me_key = '__name__',\n" +"me_value ='__main__'}, {me_hash = 0, me_key = 0x0, me_value = 0x0},\n" +"{me_hash = 0, me_key = 0x0, me_value = 0x0},\n" +"{me_hash = -9177857982131165996, me_key = 'ctypes',\n" +"me_value = },\n" +"{me_hash = -8518757509529533123, me_key = '__doc__', me_value = None},\n" +"{me_hash = 0, me_key = 0x0, me_value = 0x0}, {\n" +" me_hash = 6614918939584953775, me_key = '__package__', me_value = None}}}" + +#: ../../howto/gdb_helpers.rst:168 +msgid "" +"Note that the pretty-printers do not actually call ``repr()``. For basic " +"types, they try to match its result closely." +msgstr "" +"請注意，漂亮列印器其實並不呼叫 ``repr()``。對於基本型別，他們嘗試緊密匹配其結" +"果。" + +#: ../../howto/gdb_helpers.rst:171 +msgid "" +"An area that can be confusing is that the custom printer for some types look " +"a lot like GDB's built-in printer for standard types. For example, the " +"pretty-printer for a Python ``int`` (:c:expr:`PyLongObject *`) gives a " +"representation that is not distinguishable from one of a regular machine-" +"level integer::" +msgstr "" +"一個可能令人困惑的地方是，某些型別的自訂列印器看起來很像 GDB 標準類型的內建列" +"印器。例如，Python ``int`` (:c:expr:`PyLongObject *`) 的漂亮列印器給出的表示" +"法無法與常規機器層級整數之其一區分： ::" + +#: ../../howto/gdb_helpers.rst:177 +msgid "" +"(gdb) p some_machine_integer\n" +"$3 = 42\n" +"\n" +"(gdb) p some_python_integer\n" +"$4 = 42" +msgstr "" +"(gdb) p some_machine_integer\n" +"$3 = 42\n" +"\n" +"(gdb) p some_python_integer\n" +"$4 = 42" + +#: ../../howto/gdb_helpers.rst:183 +msgid "" +"The internal structure can be revealed with a cast to :c:expr:`PyLongObject " +"*`::" +msgstr "可以透過轉換 (cast) 為 :c:expr:`PyLongObject *` 來揭示內部結構： ::" + +#: ../../howto/gdb_helpers.rst:185 +msgid "" +"(gdb) p *(PyLongObject*)some_python_integer\n" +"$5 = {ob_base = {ob_base = {ob_refcnt = 8, ob_type = 0x3dad39f5e0}, ob_size " +"= 1},\n" +"ob_digit = {42}}" +msgstr "" +"(gdb) p *(PyLongObject*)some_python_integer\n" +"$5 = {ob_base = {ob_base = {ob_refcnt = 8, ob_type = 0x3dad39f5e0}, ob_size " +"= 1},\n" +"ob_digit = {42}}" + +#: ../../howto/gdb_helpers.rst:189 +msgid "" +"A similar confusion can arise with the ``str`` type, where the output looks " +"a lot like gdb's built-in printer for ``char *``::" +msgstr "" +"使用 ``str`` 型別時也可能會出現類似的困惑，其中的輸出看起來很像對於 ``char " +"*`` 的 gdb 內建列印器 ： ::" + +#: ../../howto/gdb_helpers.rst:192 +msgid "" +"(gdb) p ptr_to_python_str\n" +"$6 = '__builtins__'" +msgstr "" +"(gdb) p ptr_to_python_str\n" +"$6 = '__builtins__'" + +#: ../../howto/gdb_helpers.rst:195 +msgid "" +"The pretty-printer for ``str`` instances defaults to using single-quotes (as " +"does Python's ``repr`` for strings) whereas the standard printer for ``char " +"*`` values uses double-quotes and contains a hexadecimal address::" +msgstr "" +"``str`` 實例的漂亮列印器預設使用單引號（Python 的 ``repr`` 對於字串也是如" +"此），而 ``char *`` 值的標準列印器使用雙引號並包含十六進位位址： ::" + +#: ../../howto/gdb_helpers.rst:199 +msgid "" +"(gdb) p ptr_to_char_star\n" +"$7 = 0x6d72c0 \"hello world\"" +msgstr "" +"(gdb) p ptr_to_char_star\n" +"$7 = 0x6d72c0 \"hello world\"" + +#: ../../howto/gdb_helpers.rst:202 +msgid "" +"Again, the implementation details can be revealed with a cast to :c:expr:" +"`PyUnicodeObject *`::" +msgstr "同樣，可以透過轉換為 :c:expr:`PyUnicodeObject *` 來揭示實作細節： ::" + +#: ../../howto/gdb_helpers.rst:205 +msgid "" +"(gdb) p *(PyUnicodeObject*)$6\n" +"$8 = {ob_base = {ob_refcnt = 33, ob_type = 0x3dad3a95a0}, length = 12,\n" +"str = 0x7ffff2128500, hash = 7065186196740147912, state = 1, defenc = 0x0}" +msgstr "" +"(gdb) p *(PyUnicodeObject*)$6\n" +"$8 = {ob_base = {ob_refcnt = 33, ob_type = 0x3dad3a95a0}, length = 12,\n" +"str = 0x7ffff2128500, hash = 7065186196740147912, state = 1, defenc = 0x0}" + +#: ../../howto/gdb_helpers.rst:210 +msgid "``py-list``" +msgstr "``py-list``" + +#: ../../howto/gdb_helpers.rst:212 +msgid "" +"The extension adds a ``py-list`` command, which lists the Python source code " +"(if any) for the current frame in the selected thread. The current line is " +"marked with a \">\"::" +msgstr "" +"該擴充功能新增了一個 ``py-list`` 命令，該命令列出了所選執行緒中目前 frame 的 " +"Python 原始程式碼（如果有）。目前的列會標有 \">\"： ::" + +#: ../../howto/gdb_helpers.rst:216 +msgid "" +"(gdb) py-list\n" +" 901 if options.profile:\n" +" 902 options.profile = False\n" +" 903 profile_me()\n" +" 904 return\n" +" 905\n" +">906 u = UI()\n" +" 907 if not u.quit:\n" +" 908 try:\n" +" 909 gtk.main()\n" +" 910 except KeyboardInterrupt:\n" +" 911 # properly quit on a keyboard interrupt..." +msgstr "" +"(gdb) py-list\n" +" 901 if options.profile:\n" +" 902 options.profile = False\n" +" 903 profile_me()\n" +" 904 return\n" +" 905\n" +">906 u = UI()\n" +" 907 if not u.quit:\n" +" 908 try:\n" +" 909 gtk.main()\n" +" 910 except KeyboardInterrupt:\n" +" 911 # properly quit on a keyboard interrupt..." + +#: ../../howto/gdb_helpers.rst:229 +msgid "" +"Use ``py-list START`` to list at a different line number within the Python " +"source, and ``py-list START,END`` to list a specific range of lines within " +"the Python source." +msgstr "" +"使用 ``py-list START`` 列出 Python 原始碼中不同的列號，使用 ``py-list START," +"END`` 列出 Python 原始碼中特定範圍的列。" + +#: ../../howto/gdb_helpers.rst:234 +msgid "``py-up`` and ``py-down``" +msgstr "``py-up`` 和 ``py-down``" + +#: ../../howto/gdb_helpers.rst:236 +msgid "" +"The ``py-up`` and ``py-down`` commands are analogous to GDB's regular ``up`` " +"and ``down`` commands, but try to move at the level of CPython frames, " +"rather than C frames." +msgstr "" +"``py-up`` 和 ``py-down`` 命令類似於 GDB 的常規 ``up`` 和 ``down`` 命令，但嘗" +"試在 CPython frame 層級移動，而不是 C frame。" + +#: ../../howto/gdb_helpers.rst:240 +msgid "" +"GDB is not always able to read the relevant frame information, depending on " +"the optimization level with which CPython was compiled. Internally, the " +"commands look for C frames that are executing the default frame evaluation " +"function (that is, the core bytecode interpreter loop within CPython) and " +"look up the value of the related ``PyFrameObject *``." +msgstr "" +"GDB 並不總是能夠讀取相關的 frame 資訊，這取決於編譯 CPython 的最佳化等級。在" +"內部，這些指令會尋找正在執行預設 frame 計算 (evaluation) 函式（即 CPython 中" +"迴圈的核心位元組碼直譯器）的 C frame，並尋找相關 ``PyFrameObject *`` 的值。" + +#: ../../howto/gdb_helpers.rst:246 +msgid "They emit the frame number (at the C level) within the thread." +msgstr "它們在執行緒內發出（於 C 層級的）frame 編號。" + +#: ../../howto/gdb_helpers.rst:248 ../../howto/gdb_helpers.rst:320 +msgid "For example::" +msgstr "例如： ::" + +#: ../../howto/gdb_helpers.rst:250 +msgid "" +"(gdb) py-up\n" +"#37 Frame 0x9420b04, for file /usr/lib/python2.6/site-packages/\n" +"gnome_sudoku/main.py, line 906, in start_game ()\n" +" u = UI()\n" +"(gdb) py-up\n" +"#40 Frame 0x948e82c, for file /usr/lib/python2.6/site-packages/\n" +"gnome_sudoku/gnome_sudoku.py, line 22, in start_game(main=)\n" +" main.start_game()\n" +"(gdb) py-up\n" +"Unable to find an older python frame" +msgstr "" +"(gdb) py-up\n" +"#37 Frame 0x9420b04, for file /usr/lib/python2.6/site-packages/\n" +"gnome_sudoku/main.py, line 906, in start_game ()\n" +" u = UI()\n" +"(gdb) py-up\n" +"#40 Frame 0x948e82c, for file /usr/lib/python2.6/site-packages/\n" +"gnome_sudoku/gnome_sudoku.py, line 22, in start_game(main=)\n" +" main.start_game()\n" +"(gdb) py-up\n" +"Unable to find an older python frame" + +#: ../../howto/gdb_helpers.rst:261 +msgid "so we're at the top of the Python stack." +msgstr "所以現在我們處於 Python 堆疊的頂端。" + +#: ../../howto/gdb_helpers.rst:263 +msgid "" +"The frame numbers correspond to those displayed by GDB's standard " +"``backtrace`` command. The command skips C frames which are not executing " +"Python code." +msgstr "" +"frame 編號與 GDB 標準 ``backtrace`` 指令顯示的 frame 編號相對應。此指令會跳過" +"不執行 Python 程式碼的 C frame。" + +#: ../../howto/gdb_helpers.rst:267 +msgid "Going back down::" +msgstr "回到下面： ::" + +#: ../../howto/gdb_helpers.rst:269 +msgid "" +"(gdb) py-down\n" +"#37 Frame 0x9420b04, for file /usr/lib/python2.6/site-packages/gnome_sudoku/" +"main.py, line 906, in start_game ()\n" +" u = UI()\n" +"(gdb) py-down\n" +"#34 (unable to read python frame information)\n" +"(gdb) py-down\n" +"#23 (unable to read python frame information)\n" +"(gdb) py-down\n" +"#19 (unable to read python frame information)\n" +"(gdb) py-down\n" +"#14 Frame 0x99262ac, for file /usr/lib/python2.6/site-packages/gnome_sudoku/" +"game_selector.py, line 201, in run_swallowed_dialog " +"(self=, puzzle=None, saved_games=[{'gsd.auto_fills': 0, 'tracking': {}, " +"'trackers': {}, 'notes': [], 'saved_at': 1270084485, 'game': '7 8 0 0 0 0 0 " +"5 6 0 0 9 0 8 0 1 0 0 0 4 6 0 0 0 0 7 0 6 5 0 0 0 4 7 9 2 0 0 0 9 0 1 0 0 0 " +"3 9 7 6 0 0 0 1 8 0 6 0 0 0 0 2 8 0 0 0 5 0 4 0 6 0 0 2 1 0 0 0 0 0 4 5\\n7 " +"8 0 0 0 0 0 5 6 0 0 9 0 8 0 1 0 0 0 4 6 0 0 0 0 7 0 6 5 1 8 3 4 7 9 2 0 0 0 " +"9 0 1 0 0 0 3 9 7 6 0 0 0 1 8 0 6 0 0 0 0 2 8 0 0 0 5 0 4 0 6 0 0 2 1 0 0 0 " +"0 0 4 5', 'gsd.impossible_hints': 0, 'timer.__absolute_start_time__': , 'gsd.hints': 0, 'timer.active_time': , 'timer.total_time': }], dialog=, saved_game_model=, sudoku_maker=, main_page=0) " +"at remote 0x98fa6e4>, d=)\n" +" gtk.main()\n" +"(gdb) py-down\n" +"#8 (unable to read python frame information)\n" +"(gdb) py-down\n" +"Unable to find a newer python frame" +msgstr "" +"(gdb) py-down\n" +"#37 Frame 0x9420b04, for file /usr/lib/python2.6/site-packages/gnome_sudoku/" +"main.py, line 906, in start_game ()\n" +" u = UI()\n" +"(gdb) py-down\n" +"#34 (unable to read python frame information)\n" +"(gdb) py-down\n" +"#23 (unable to read python frame information)\n" +"(gdb) py-down\n" +"#19 (unable to read python frame information)\n" +"(gdb) py-down\n" +"#14 Frame 0x99262ac, for file /usr/lib/python2.6/site-packages/gnome_sudoku/" +"game_selector.py, line 201, in run_swallowed_dialog " +"(self=, puzzle=None, saved_games=[{'gsd.auto_fills': 0, 'tracking': {}, " +"'trackers': {}, 'notes': [], 'saved_at': 1270084485, 'game': '7 8 0 0 0 0 0 " +"5 6 0 0 9 0 8 0 1 0 0 0 4 6 0 0 0 0 7 0 6 5 0 0 0 4 7 9 2 0 0 0 9 0 1 0 0 0 " +"3 9 7 6 0 0 0 1 8 0 6 0 0 0 0 2 8 0 0 0 5 0 4 0 6 0 0 2 1 0 0 0 0 0 4 5\\n7 " +"8 0 0 0 0 0 5 6 0 0 9 0 8 0 1 0 0 0 4 6 0 0 0 0 7 0 6 5 1 8 3 4 7 9 2 0 0 0 " +"9 0 1 0 0 0 3 9 7 6 0 0 0 1 8 0 6 0 0 0 0 2 8 0 0 0 5 0 4 0 6 0 0 2 1 0 0 0 " +"0 0 4 5', 'gsd.impossible_hints': 0, 'timer.__absolute_start_time__': , 'gsd.hints': 0, 'timer.active_time': , 'timer.total_time': }], dialog=, saved_game_model=, sudoku_maker=, main_page=0) " +"at remote 0x98fa6e4>, d=)\n" +" gtk.main()\n" +"(gdb) py-down\n" +"#8 (unable to read python frame information)\n" +"(gdb) py-down\n" +"Unable to find a newer python frame" + +#: ../../howto/gdb_helpers.rst:289 +msgid "and we're at the bottom of the Python stack." +msgstr "我們現在處於 Python 堆疊的底部。" + +#: ../../howto/gdb_helpers.rst:291 +msgid "" +"Note that in Python 3.12 and newer, the same C stack frame can be used for " +"multiple Python stack frames. This means that ``py-up`` and ``py-down`` may " +"move multiple Python frames at once. For example::" +msgstr "" +"請注意，在 Python 3.12 及更高版本中，同一個 C 堆疊 frame 可用於多個 Python 堆" +"疊 frame。這意味著 ``py-up`` 和 ``py-down`` 可以一次移動多個 Python frame。例" +"如： ::" + +#: ../../howto/gdb_helpers.rst:295 +msgid "" +"(gdb) py-up\n" +"#6 Frame 0x7ffff7fb62b0, for file /tmp/rec.py, line 5, in recursive_function " +"(n=0)\n" +" time.sleep(5)\n" +"#6 Frame 0x7ffff7fb6240, for file /tmp/rec.py, line 7, in recursive_function " +"(n=1)\n" +" recursive_function(n-1)\n" +"#6 Frame 0x7ffff7fb61d0, for file /tmp/rec.py, line 7, in recursive_function " +"(n=2)\n" +" recursive_function(n-1)\n" +"#6 Frame 0x7ffff7fb6160, for file /tmp/rec.py, line 7, in recursive_function " +"(n=3)\n" +" recursive_function(n-1)\n" +"#6 Frame 0x7ffff7fb60f0, for file /tmp/rec.py, line 7, in recursive_function " +"(n=4)\n" +" recursive_function(n-1)\n" +"#6 Frame 0x7ffff7fb6080, for file /tmp/rec.py, line 7, in recursive_function " +"(n=5)\n" +" recursive_function(n-1)\n" +"#6 Frame 0x7ffff7fb6020, for file /tmp/rec.py, line 9, in ()\n" +" recursive_function(5)\n" +"(gdb) py-up\n" +"Unable to find an older python frame" +msgstr "" +"(gdb) py-up\n" +"#6 Frame 0x7ffff7fb62b0, for file /tmp/rec.py, line 5, in recursive_function " +"(n=0)\n" +" time.sleep(5)\n" +"#6 Frame 0x7ffff7fb6240, for file /tmp/rec.py, line 7, in recursive_function " +"(n=1)\n" +" recursive_function(n-1)\n" +"#6 Frame 0x7ffff7fb61d0, for file /tmp/rec.py, line 7, in recursive_function " +"(n=2)\n" +" recursive_function(n-1)\n" +"#6 Frame 0x7ffff7fb6160, for file /tmp/rec.py, line 7, in recursive_function " +"(n=3)\n" +" recursive_function(n-1)\n" +"#6 Frame 0x7ffff7fb60f0, for file /tmp/rec.py, line 7, in recursive_function " +"(n=4)\n" +" recursive_function(n-1)\n" +"#6 Frame 0x7ffff7fb6080, for file /tmp/rec.py, line 7, in recursive_function " +"(n=5)\n" +" recursive_function(n-1)\n" +"#6 Frame 0x7ffff7fb6020, for file /tmp/rec.py, line 9, in ()\n" +" recursive_function(5)\n" +"(gdb) py-up\n" +"Unable to find an older python frame" + +#: ../../howto/gdb_helpers.rst:315 +msgid "``py-bt``" +msgstr "``py-bt``" + +#: ../../howto/gdb_helpers.rst:317 +msgid "" +"The ``py-bt`` command attempts to display a Python-level backtrace of the " +"current thread." +msgstr "``py-bt`` 指令嘗試顯示目前執行緒的 Python 層級回溯。" + +#: ../../howto/gdb_helpers.rst:322 +msgid "" +"(gdb) py-bt\n" +"#8 (unable to read python frame information)\n" +"#11 Frame 0x9aead74, for file /usr/lib/python2.6/site-packages/gnome_sudoku/" +"dialog_swallower.py, line 48, in run_dialog " +"(self=, main_page=0) " +"at remote 0x98fa6e4>, d=)\n" +" gtk.main()\n" +"#14 Frame 0x99262ac, for file /usr/lib/python2.6/site-packages/gnome_sudoku/" +"game_selector.py, line 201, in run_swallowed_dialog " +"(self=, puzzle=None, saved_games=[{'gsd.auto_fills': 0, 'tracking': {}, " +"'trackers': {}, 'notes': [], 'saved_at': 1270084485, 'game': '7 8 0 0 0 0 0 " +"5 6 0 0 9 0 8 0 1 0 0 0 4 6 0 0 0 0 7 0 6 5 0 0 0 4 7 9 2 0 0 0 9 0 1 0 0 0 " +"3 9 7 6 0 0 0 1 8 0 6 0 0 0 0 2 8 0 0 0 5 0 4 0 6 0 0 2 1 0 0 0 0 0 4 5\\n7 " +"8 0 0 0 0 0 5 6 0 0 9 0 8 0 1 0 0 0 4 6 0 0 0 0 7 0 6 5 1 8 3 4 7 9 2 0 0 0 " +"9 0 1 0 0 0 3 9 7 6 0 0 0 1 8 0 6 0 0 0 0 2 8 0 0 0 5 0 4 0 6 0 0 2 1 0 0 0 " +"0 0 4 5', 'gsd.impossible_hints': 0, 'timer.__absolute_start_time__': , 'gsd.hints': 0, 'timer.active_time': , 'timer.total_time': }], dialog=, saved_game_model=, sudoku_maker=)\n" +" main.start_game()" +msgstr "" +"(gdb) py-bt\n" +"#8 (unable to read python frame information)\n" +"#11 Frame 0x9aead74, for file /usr/lib/python2.6/site-packages/gnome_sudoku/" +"dialog_swallower.py, line 48, in run_dialog " +"(self=, main_page=0) " +"at remote 0x98fa6e4>, d=)\n" +" gtk.main()\n" +"#14 Frame 0x99262ac, for file /usr/lib/python2.6/site-packages/gnome_sudoku/" +"game_selector.py, line 201, in run_swallowed_dialog " +"(self=, puzzle=None, saved_games=[{'gsd.auto_fills': 0, 'tracking': {}, " +"'trackers': {}, 'notes': [], 'saved_at': 1270084485, 'game': '7 8 0 0 0 0 0 " +"5 6 0 0 9 0 8 0 1 0 0 0 4 6 0 0 0 0 7 0 6 5 0 0 0 4 7 9 2 0 0 0 9 0 1 0 0 0 " +"3 9 7 6 0 0 0 1 8 0 6 0 0 0 0 2 8 0 0 0 5 0 4 0 6 0 0 2 1 0 0 0 0 0 4 5\\n7 " +"8 0 0 0 0 0 5 6 0 0 9 0 8 0 1 0 0 0 4 6 0 0 0 0 7 0 6 5 1 8 3 4 7 9 2 0 0 0 " +"9 0 1 0 0 0 3 9 7 6 0 0 0 1 8 0 6 0 0 0 0 2 8 0 0 0 5 0 4 0 6 0 0 2 1 0 0 0 " +"0 0 4 5', 'gsd.impossible_hints': 0, 'timer.__absolute_start_time__': , 'gsd.hints': 0, 'timer.active_time': , 'timer.total_time': }], dialog=, saved_game_model=, sudoku_maker=)\n" +" main.start_game()" + +#: ../../howto/gdb_helpers.rst:336 +msgid "" +"The frame numbers correspond to those displayed by GDB's standard " +"``backtrace`` command." +msgstr " frame 編號與 GDB 標準 ``backtrace`` 指令顯示的 frame 編號相對應。" + +#: ../../howto/gdb_helpers.rst:340 +msgid "``py-print``" +msgstr "``py-print``" + +#: ../../howto/gdb_helpers.rst:342 +msgid "" +"The ``py-print`` command looks up a Python name and tries to print it. It " +"looks in locals within the current thread, then globals, then finally " +"builtins::" +msgstr "" +"``py-print`` 命令查找 Python 名稱並嘗試列印它。它在目前執行緒中尋找局部變數，" +"然後是全域變數，最後是內建變數： ::" + +#: ../../howto/gdb_helpers.rst:346 +msgid "" +"(gdb) py-print self\n" +"local 'self' = ,\n" +"main_page=0) at remote 0x98fa6e4>\n" +"(gdb) py-print __name__\n" +"global '__name__' = 'gnome_sudoku.dialog_swallower'\n" +"(gdb) py-print len\n" +"builtin 'len' = \n" +"(gdb) py-print scarlet_pimpernel\n" +"'scarlet_pimpernel' not found" +msgstr "" +"(gdb) py-print self\n" +"local 'self' = ,\n" +"main_page=0) at remote 0x98fa6e4>\n" +"(gdb) py-print __name__\n" +"global '__name__' = 'gnome_sudoku.dialog_swallower'\n" +"(gdb) py-print len\n" +"builtin 'len' = \n" +"(gdb) py-print scarlet_pimpernel\n" +"'scarlet_pimpernel' not found" + +#: ../../howto/gdb_helpers.rst:356 +msgid "" +"If the current C frame corresponds to multiple Python frames, ``py-print`` " +"only considers the first one." +msgstr "如果目前 C frame 對應多個 Python frame，則 ``py-print`` 僅考慮第一個。" + +#: ../../howto/gdb_helpers.rst:360 +msgid "``py-locals``" +msgstr "``py-locals``" + +#: ../../howto/gdb_helpers.rst:362 +msgid "" +"The ``py-locals`` command looks up all Python locals within the current " +"Python frame in the selected thread, and prints their representations::" +msgstr "" +"``py-locals`` 命令尋找所選執行緒中目前 Python frame 內的所有 Python 局部變" +"數，並列印它們的表示： ::" + +#: ../../howto/gdb_helpers.rst:365 +msgid "" +"(gdb) py-locals\n" +"self = ,\n" +"main_page=0) at remote 0x98fa6e4>\n" +"d = " +msgstr "" +"(gdb) py-locals\n" +"self = ,\n" +"main_page=0) at remote 0x98fa6e4>\n" +"d = " + +#: ../../howto/gdb_helpers.rst:370 +msgid "" +"If the current C frame corresponds to multiple Python frames, locals from " +"all of them will be shown::" +msgstr "" +"如果目前 C frame 對應於多個 Python frame，則會顯示所有這些 frame 的局部變數：" + +#: ../../howto/gdb_helpers.rst:373 +msgid "" +"(gdb) py-locals\n" +"Locals for recursive_function\n" +"n = 0\n" +"Locals for recursive_function\n" +"n = 1\n" +"Locals for recursive_function\n" +"n = 2\n" +"Locals for recursive_function\n" +"n = 3\n" +"Locals for recursive_function\n" +"n = 4\n" +"Locals for recursive_function\n" +"n = 5\n" +"Locals for " +msgstr "" +"(gdb) py-locals\n" +"Locals for recursive_function\n" +"n = 0\n" +"Locals for recursive_function\n" +"n = 1\n" +"Locals for recursive_function\n" +"n = 2\n" +"Locals for recursive_function\n" +"n = 3\n" +"Locals for recursive_function\n" +"n = 4\n" +"Locals for recursive_function\n" +"n = 5\n" +"Locals for " + +#: ../../howto/gdb_helpers.rst:390 +msgid "Use with GDB commands" +msgstr "與 GDB 指令一起使用" + +#: ../../howto/gdb_helpers.rst:392 +msgid "" +"The extension commands complement GDB's built-in commands. For example, you " +"can use a frame numbers shown by ``py-bt`` with the ``frame`` command to go " +"a specific frame within the selected thread, like this::" +msgstr "" +"擴充命令補充了 GDB 的內建命令。例如，你可以將 ``py-bt`` 顯示的 frame 編號與 " +"``frame`` 命令一同使用來跳到所選執行緒中的特定 frame，如下所示： ::" + +#: ../../howto/gdb_helpers.rst:396 +msgid "" +"(gdb) py-bt\n" +"(output snipped)\n" +"#68 Frame 0xaa4560, for file Lib/test/regrtest.py, line 1548, in " +"()\n" +" main()\n" +"(gdb) frame 68\n" +"#68 0x00000000004cd1e6 in PyEval_EvalFrameEx (f=Frame 0xaa4560, for file Lib/" +"test/regrtest.py, line 1548, in (), throwflag=0) at Python/ceval." +"c:2665\n" +"2665 x = call_function(&sp, oparg);\n" +"(gdb) py-list\n" +"1543 # Run the tests in a context manager that temporary changes the " +"CWD to a\n" +"1544 # temporary and writable directory. If it's not possible to " +"create or\n" +"1545 # change the CWD, the original CWD will be used. The original " +"CWD is\n" +"1546 # available from test_support.SAVEDCWD.\n" +"1547 with test_support.temp_cwd(TESTCWD, quiet=True):\n" +">1548 main()" +msgstr "" +"(gdb) py-bt\n" +"(output snipped)\n" +"#68 Frame 0xaa4560, for file Lib/test/regrtest.py, line 1548, in " +"()\n" +" main()\n" +"(gdb) frame 68\n" +"#68 0x00000000004cd1e6 in PyEval_EvalFrameEx (f=Frame 0xaa4560, for file Lib/" +"test/regrtest.py, line 1548, in (), throwflag=0) at Python/ceval." +"c:2665\n" +"2665 x = call_function(&sp, oparg);\n" +"(gdb) py-list\n" +"1543 # 在暫時改變 CWD 到一個臨時且可寫入的目錄的\n" +"1544 # 情境管理器中運行測試。\n" +"1545 # 如果無法建立或更改 CWD，則使用原始的 CWD。\n" +"1546 # 原始 CWD 可從 test_support.SAVEDCWD 獲得。\n" +"1547 with test_support.temp_cwd(TESTCWD, quiet=True):\n" +">1548 main()" + +#: ../../howto/gdb_helpers.rst:411 +msgid "" +"The ``info threads`` command will give you a list of the threads within the " +"process, and you can use the ``thread`` command to select a different one::" +msgstr "" +"``info threads`` 命令將為你提供行程內的執行緒串列，你可以使用 ``thread`` 命令" +"選擇不同的執行緒： ::" + +#: ../../howto/gdb_helpers.rst:414 +msgid "" +"(gdb) info threads\n" +" 105 Thread 0x7fffefa18710 (LWP 10260) sem_wait () at ../nptl/sysdeps/unix/" +"sysv/linux/x86_64/sem_wait.S:86\n" +" 104 Thread 0x7fffdf5fe710 (LWP 10259) sem_wait () at ../nptl/sysdeps/unix/" +"sysv/linux/x86_64/sem_wait.S:86\n" +"* 1 Thread 0x7ffff7fe2700 (LWP 10145) 0x00000038e46d73e3 in select () at ../" +"sysdeps/unix/syscall-template.S:82" +msgstr "" +"(gdb) info threads\n" +" 105 Thread 0x7fffefa18710 (LWP 10260) sem_wait () at ../nptl/sysdeps/unix/" +"sysv/linux/x86_64/sem_wait.S:86\n" +" 104 Thread 0x7fffdf5fe710 (LWP 10259) sem_wait () at ../nptl/sysdeps/unix/" +"sysv/linux/x86_64/sem_wait.S:86\n" +"* 1 Thread 0x7ffff7fe2700 (LWP 10145) 0x00000038e46d73e3 in select () at ../" +"sysdeps/unix/syscall-template.S:82" + +#: ../../howto/gdb_helpers.rst:419 +msgid "" +"You can use ``thread apply all COMMAND`` or (``t a a COMMAND`` for short) to " +"run a command on all threads. With ``py-bt``, this lets you see what every " +"thread is doing at the Python level::" +msgstr "" +"你可以使用 ``thread apply all COMMAND``\\ （或簡短地用 ``t a a COMMAND``）在" +"所有執行緒上執行命令。使用 ``py-bt`` 你可以看到每個執行緒在 Python 層級正在做" +"什麼： ::" + +#: ../../howto/gdb_helpers.rst:423 +msgid "" +"(gdb) t a a py-bt\n" +"\n" +"Thread 105 (Thread 0x7fffefa18710 (LWP 10260)):\n" +"#5 Frame 0x7fffd00019d0, for file /home/david/coding/python-svn/Lib/" +"threading.py, line 155, in _acquire_restore " +"(self=<_RLock(_Verbose__verbose=False, _RLock__owner=140737354016512, " +"_RLock__block=, _RLock__count=1) at remote " +"0xd7ff40>, count_owner=(1, 140737213728528), count=1, " +"owner=140737213728528)\n" +" self.__block.acquire()\n" +"#8 Frame 0x7fffac001640, for file /home/david/coding/python-svn/Lib/" +"threading.py, line 269, in wait " +"(self=<_Condition(_Condition__lock=<_RLock(_Verbose__verbose=False, " +"_RLock__owner=140737354016512, _RLock__block=, _RLock__count=1) at remote 0xd7ff40>, acquire=, _is_owned=, " +"_release_save=, release=, _acquire_restore=, " +"_Verbose__verbose=False, _Condition__waiters=[]) at remote 0xd7fd10>, " +"timeout=None, waiter=, saved_state=(1, " +"140737213728528))\n" +" self._acquire_restore(saved_state)\n" +"#12 Frame 0x7fffb8001a10, for file /home/david/coding/python-svn/Lib/test/" +"lock_tests.py, line 348, in f ()\n" +" cond.wait()\n" +"#16 Frame 0x7fffb8001c40, for file /home/david/coding/python-svn/Lib/test/" +"lock_tests.py, line 37, in task (tid=140737213728528)\n" +" f()\n" +"\n" +"Thread 104 (Thread 0x7fffdf5fe710 (LWP 10259)):\n" +"#5 Frame 0x7fffe4001580, for file /home/david/coding/python-svn/Lib/" +"threading.py, line 155, in _acquire_restore " +"(self=<_RLock(_Verbose__verbose=False, _RLock__owner=140737354016512, " +"_RLock__block=, _RLock__count=1) at remote " +"0xd7ff40>, count_owner=(1, 140736940992272), count=1, " +"owner=140736940992272)\n" +" self.__block.acquire()\n" +"#8 Frame 0x7fffc8002090, for file /home/david/coding/python-svn/Lib/" +"threading.py, line 269, in wait " +"(self=<_Condition(_Condition__lock=<_RLock(_Verbose__verbose=False, " +"_RLock__owner=140737354016512, _RLock__block=, _RLock__count=1) at remote 0xd7ff40>, acquire=, _is_owned=, " +"_release_save=, release=, _acquire_restore=, " +"_Verbose__verbose=False, _Condition__waiters=[]) at remote 0xd7fd10>, " +"timeout=None, waiter=, saved_state=(1, " +"140736940992272))\n" +" self._acquire_restore(saved_state)\n" +"#12 Frame 0x7fffac001c90, for file /home/david/coding/python-svn/Lib/test/" +"lock_tests.py, line 348, in f ()\n" +" cond.wait()\n" +"#16 Frame 0x7fffac0011c0, for file /home/david/coding/python-svn/Lib/test/" +"lock_tests.py, line 37, in task (tid=140736940992272)\n" +" f()\n" +"\n" +"Thread 1 (Thread 0x7ffff7fe2700 (LWP 10145)):\n" +"#5 Frame 0xcb5380, for file /home/david/coding/python-svn/Lib/test/" +"lock_tests.py, line 16, in _wait ()\n" +" time.sleep(0.01)\n" +"#8 Frame 0x7fffd00024a0, for file /home/david/coding/python-svn/Lib/test/" +"lock_tests.py, line 378, in _check_notify " +"(self=, skipped=[], _mirrorOutput=False, testsRun=39, " +"buffer=False, _original_stderr=, " +"_stdout_buffer=, " +"_stderr_buffer=, " +"_moduleSetUpFailed=False, expectedFailures=[], errors=[], " +"_previousTestClass=, unexpectedSuccesses=[], " +"failures=[], shouldStop=False, failfast=False) at remote 0xc185a0>, " +"_threads=(0,), _cleanups=[], _type_equality_funcs={: , : " +", : " +", : " +", , _RLock__count=1) at remote " +"0xd7ff40>, count_owner=(1, 140737213728528), count=1, " +"owner=140737213728528)\n" +" self.__block.acquire()\n" +"#8 Frame 0x7fffac001640, for file /home/david/coding/python-svn/Lib/" +"threading.py, line 269, in wait " +"(self=<_Condition(_Condition__lock=<_RLock(_Verbose__verbose=False, " +"_RLock__owner=140737354016512, _RLock__block=, _RLock__count=1) at remote 0xd7ff40>, acquire=, _is_owned=, " +"_release_save=, release=, _acquire_restore=, " +"_Verbose__verbose=False, _Condition__waiters=[]) at remote 0xd7fd10>, " +"timeout=None, waiter=, saved_state=(1, " +"140737213728528))\n" +" self._acquire_restore(saved_state)\n" +"#12 Frame 0x7fffb8001a10, for file /home/david/coding/python-svn/Lib/test/" +"lock_tests.py, line 348, in f ()\n" +" cond.wait()\n" +"#16 Frame 0x7fffb8001c40, for file /home/david/coding/python-svn/Lib/test/" +"lock_tests.py, line 37, in task (tid=140737213728528)\n" +" f()\n" +"\n" +"Thread 104 (Thread 0x7fffdf5fe710 (LWP 10259)):\n" +"#5 Frame 0x7fffe4001580, for file /home/david/coding/python-svn/Lib/" +"threading.py, line 155, in _acquire_restore " +"(self=<_RLock(_Verbose__verbose=False, _RLock__owner=140737354016512, " +"_RLock__block=, _RLock__count=1) at remote " +"0xd7ff40>, count_owner=(1, 140736940992272), count=1, " +"owner=140736940992272)\n" +" self.__block.acquire()\n" +"#8 Frame 0x7fffc8002090, for file /home/david/coding/python-svn/Lib/" +"threading.py, line 269, in wait " +"(self=<_Condition(_Condition__lock=<_RLock(_Verbose__verbose=False, " +"_RLock__owner=140737354016512, _RLock__block=, _RLock__count=1) at remote 0xd7ff40>, acquire=, _is_owned=, " +"_release_save=, release=, _acquire_restore=, " +"_Verbose__verbose=False, _Condition__waiters=[]) at remote 0xd7fd10>, " +"timeout=None, waiter=, saved_state=(1, " +"140736940992272))\n" +" self._acquire_restore(saved_state)\n" +"#12 Frame 0x7fffac001c90, for file /home/david/coding/python-svn/Lib/test/" +"lock_tests.py, line 348, in f ()\n" +" cond.wait()\n" +"#16 Frame 0x7fffac0011c0, for file /home/david/coding/python-svn/Lib/test/" +"lock_tests.py, line 37, in task (tid=140736940992272)\n" +" f()\n" +"\n" +"Thread 1 (Thread 0x7ffff7fe2700 (LWP 10145)):\n" +"#5 Frame 0xcb5380, for file /home/david/coding/python-svn/Lib/test/" +"lock_tests.py, line 16, in _wait ()\n" +" time.sleep(0.01)\n" +"#8 Frame 0x7fffd00024a0, for file /home/david/coding/python-svn/Lib/test/" +"lock_tests.py, line 378, in _check_notify " +"(self=, skipped=[], _mirrorOutput=False, testsRun=39, " +"buffer=False, _original_stderr=, " +"_stdout_buffer=, " +"_stderr_buffer=, " +"_moduleSetUpFailed=False, expectedFailures=[], errors=[], " +"_previousTestClass=, unexpectedSuccesses=[], " +"failures=[], shouldStop=False, failfast=False) at remote 0xc185a0>, " +"_threads=(0,), _cleanups=[], _type_equality_funcs={: , : " +", : " +", : " +", , 2021 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: 2021-07-05 12:45+0800\n" -"Last-Translator: Liang-Bo Wang \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" -"X-Generator: Poedit 2.4.3\n" - -#: ../../howto/index.rst:5 -msgid "Python HOWTOs" -msgstr "Python 如何達成任務" - -#: ../../howto/index.rst:7 -msgid "" -"Python HOWTOs are documents that cover a specific topic in-depth. Modeled on " -"the Linux Documentation Project's HOWTO collection, this collection is an " -"effort to foster documentation that's more detailed than the Python Library " -"Reference." -msgstr "" -"「Python 如何達成任務 (HOWTOs)」是一系列的說明文件，其內容會深度地涵蓋某些特" -"定的主題。以 Linux 說明文件專案的 HOWTO 系列為模範，本系列的目標是提供比 " -"Python 函式庫參考手冊更實用的說明文件。" - -#: ../../howto/index.rst:42 -msgid "General:" -msgstr "一般：" - -#: ../../howto/index.rst:44 -msgid ":ref:`a-conceptual-overview-of-asyncio`" -msgstr ":ref:`a-conceptual-overview-of-asyncio`" - -#: ../../howto/index.rst:45 -msgid ":ref:`annotations-howto`" -msgstr ":ref:`annotations-howto`" - -#: ../../howto/index.rst:46 -msgid ":ref:`argparse-tutorial`" -msgstr ":ref:`argparse-tutorial`" - -#: ../../howto/index.rst:47 -msgid ":ref:`descriptorhowto`" -msgstr ":ref:`descriptorhowto`" - -#: ../../howto/index.rst:48 -msgid ":ref:`enum-howto`" -msgstr ":ref:`enum-howto`" - -#: ../../howto/index.rst:49 -msgid ":ref:`functional-howto`" -msgstr ":ref:`functional-howto`" - -#: ../../howto/index.rst:50 -msgid ":ref:`ipaddress-howto`" -msgstr ":ref:`ipaddress-howto`" - -#: ../../howto/index.rst:51 -msgid ":ref:`logging-howto`" -msgstr ":ref:`logging-howto`" - -#: ../../howto/index.rst:52 -msgid ":ref:`logging-cookbook`" -msgstr ":ref:`logging-cookbook`" - -#: ../../howto/index.rst:53 -msgid ":ref:`regex-howto`" -msgstr ":ref:`regex-howto`" - -#: ../../howto/index.rst:54 -msgid ":ref:`sortinghowto`" -msgstr ":ref:`sortinghowto`" - -#: ../../howto/index.rst:55 -msgid ":ref:`unicode-howto`" -msgstr ":ref:`unicode-howto`" - -#: ../../howto/index.rst:56 -msgid ":ref:`urllib-howto`" -msgstr ":ref:`urllib-howto`" - -#: ../../howto/index.rst:58 -msgid "Advanced development:" -msgstr "進階開發：" - -#: ../../howto/index.rst:60 -msgid ":ref:`curses-howto`" -msgstr ":ref:`curses-howto`" - -#: ../../howto/index.rst:61 -msgid ":ref:`freethreading-python-howto`" -msgstr ":ref:`freethreading-python-howto`" - -#: ../../howto/index.rst:62 -msgid ":ref:`freethreading-extensions-howto`" -msgstr ":ref:`freethreading-extensions-howto`" - -#: ../../howto/index.rst:63 -msgid ":ref:`isolating-extensions-howto`" -msgstr ":ref:`isolating-extensions-howto`" - -#: ../../howto/index.rst:64 -msgid ":ref:`python_2.3_mro`" -msgstr ":ref:`python_2.3_mro`" - -#: ../../howto/index.rst:65 -msgid ":ref:`socket-howto`" -msgstr ":ref:`socket-howto`" - -#: ../../howto/index.rst:66 -msgid ":ref:`timerfd-howto`" -msgstr ":ref:`timerfd-howto`" - -#: ../../howto/index.rst:67 -msgid ":ref:`cporting-howto`" -msgstr ":ref:`cporting-howto`" - -#: ../../howto/index.rst:69 -msgid "Debugging and profiling:" -msgstr "偵錯與效能分析：" - -#: ../../howto/index.rst:71 -msgid ":ref:`gdb`" -msgstr ":ref:`gdb`" - -#: ../../howto/index.rst:72 -msgid ":ref:`instrumentation`" -msgstr ":ref:`instrumentation`" - -#: ../../howto/index.rst:73 -msgid ":ref:`perf_profiling`" -msgstr ":ref:`perf_profiling`" - -#: ../../howto/index.rst:74 -msgid ":ref:`remote-debugging`" -msgstr ":ref:`remote-debugging`" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Steven Hsu , 2021 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: 2021-07-05 12:45+0800\n" +"Last-Translator: Liang-Bo Wang \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" +"X-Generator: Poedit 2.4.3\n" + +#: ../../howto/index.rst:5 +msgid "Python HOWTOs" +msgstr "Python 如何達成任務" + +#: ../../howto/index.rst:7 +msgid "" +"Python HOWTOs are documents that cover a specific topic in-depth. Modeled on " +"the Linux Documentation Project's HOWTO collection, this collection is an " +"effort to foster documentation that's more detailed than the Python Library " +"Reference." +msgstr "" +"「Python 如何達成任務 (HOWTOs)」是一系列的說明文件，其內容會深度地涵蓋某些特" +"定的主題。以 Linux 說明文件專案的 HOWTO 系列為模範，本系列的目標是提供比 " +"Python 函式庫參考手冊更實用的說明文件。" + +#: ../../howto/index.rst:42 +msgid "General:" +msgstr "一般：" + +#: ../../howto/index.rst:44 +msgid ":ref:`a-conceptual-overview-of-asyncio`" +msgstr ":ref:`a-conceptual-overview-of-asyncio`" + +#: ../../howto/index.rst:45 +msgid ":ref:`annotations-howto`" +msgstr ":ref:`annotations-howto`" + +#: ../../howto/index.rst:46 +msgid ":ref:`argparse-tutorial`" +msgstr ":ref:`argparse-tutorial`" + +#: ../../howto/index.rst:47 +msgid ":ref:`descriptorhowto`" +msgstr ":ref:`descriptorhowto`" + +#: ../../howto/index.rst:48 +msgid ":ref:`enum-howto`" +msgstr ":ref:`enum-howto`" + +#: ../../howto/index.rst:49 +msgid ":ref:`functional-howto`" +msgstr ":ref:`functional-howto`" + +#: ../../howto/index.rst:50 +msgid ":ref:`ipaddress-howto`" +msgstr ":ref:`ipaddress-howto`" + +#: ../../howto/index.rst:51 +msgid ":ref:`logging-howto`" +msgstr ":ref:`logging-howto`" + +#: ../../howto/index.rst:52 +msgid ":ref:`logging-cookbook`" +msgstr ":ref:`logging-cookbook`" + +#: ../../howto/index.rst:53 +msgid ":ref:`regex-howto`" +msgstr ":ref:`regex-howto`" + +#: ../../howto/index.rst:54 +msgid ":ref:`sortinghowto`" +msgstr ":ref:`sortinghowto`" + +#: ../../howto/index.rst:55 +msgid ":ref:`unicode-howto`" +msgstr ":ref:`unicode-howto`" + +#: ../../howto/index.rst:56 +msgid ":ref:`urllib-howto`" +msgstr ":ref:`urllib-howto`" + +#: ../../howto/index.rst:58 +msgid "Advanced development:" +msgstr "進階開發：" + +#: ../../howto/index.rst:60 +msgid ":ref:`curses-howto`" +msgstr ":ref:`curses-howto`" + +#: ../../howto/index.rst:61 +msgid ":ref:`freethreading-python-howto`" +msgstr ":ref:`freethreading-python-howto`" + +#: ../../howto/index.rst:62 +msgid ":ref:`freethreading-extensions-howto`" +msgstr ":ref:`freethreading-extensions-howto`" + +#: ../../howto/index.rst:63 +msgid ":ref:`isolating-extensions-howto`" +msgstr ":ref:`isolating-extensions-howto`" + +#: ../../howto/index.rst:64 +msgid ":ref:`python_2.3_mro`" +msgstr ":ref:`python_2.3_mro`" + +#: ../../howto/index.rst:65 +msgid ":ref:`socket-howto`" +msgstr ":ref:`socket-howto`" + +#: ../../howto/index.rst:66 +msgid ":ref:`timerfd-howto`" +msgstr ":ref:`timerfd-howto`" + +#: ../../howto/index.rst:67 +msgid ":ref:`cporting-howto`" +msgstr ":ref:`cporting-howto`" + +#: ../../howto/index.rst:69 +msgid "Debugging and profiling:" +msgstr "偵錯與效能分析：" + +#: ../../howto/index.rst:71 +msgid ":ref:`gdb`" +msgstr ":ref:`gdb`" + +#: ../../howto/index.rst:72 +msgid ":ref:`instrumentation`" +msgstr ":ref:`instrumentation`" + +#: ../../howto/index.rst:73 +msgid ":ref:`perf_profiling`" +msgstr ":ref:`perf_profiling`" + +#: ../../howto/index.rst:74 +msgid ":ref:`remote-debugging`" +msgstr ":ref:`remote-debugging`" diff --git a/howto/instrumentation.po b/howto/instrumentation.po index 961dac6817..c7c11d1af0 100644 --- a/howto/instrumentation.po +++ b/howto/instrumentation.po @@ -1,848 +1,848 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Matt Wang -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-04 00:15+0000\n" -"PO-Revision-Date: 2023-08-17 22:17+0800\n" -"Last-Translator: Matt Wang \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" -"X-Generator: Poedit 3.3.2\n" - -#: ../../howto/instrumentation.rst:7 -msgid "Instrumenting CPython with DTrace and SystemTap" -msgstr "使用 DTrace 和 SystemTap 檢測 CPython" - -#: ../../howto/instrumentation.rst:0 -msgid "author" -msgstr "作者" - -#: ../../howto/instrumentation.rst:9 -msgid "David Malcolm" -msgstr "David Malcolm" - -#: ../../howto/instrumentation.rst:10 -msgid "Łukasz Langa" -msgstr "Łukasz Langa" - -#: ../../howto/instrumentation.rst:12 -msgid "" -"DTrace and SystemTap are monitoring tools, each providing a way to inspect " -"what the processes on a computer system are doing. They both use domain-" -"specific languages allowing a user to write scripts which:" -msgstr "" -"DTrace 和 SystemTap 都是監測工具，各自都提供了一種檢查電腦系統之行程 " -"(process) 正在執行什麼操作的方法。它們都使用了領域限定 (domain-specific) 的語" -"言，允許使用者編寫以下腳本：" - -#: ../../howto/instrumentation.rst:16 -msgid "filter which processes are to be observed" -msgstr "過濾要觀察的行程" - -#: ../../howto/instrumentation.rst:17 -msgid "gather data from the processes of interest" -msgstr "收集來自感興趣之行程的資料" - -#: ../../howto/instrumentation.rst:18 -msgid "generate reports on the data" -msgstr "以這些資料產生報告" - -#: ../../howto/instrumentation.rst:20 -msgid "" -"As of Python 3.6, CPython can be built with embedded \"markers\", also known " -"as \"probes\", that can be observed by a DTrace or SystemTap script, making " -"it easier to monitor what the CPython processes on a system are doing." -msgstr "" -"從 Python 3.6 開始，CPython 可以使用嵌入式「標記 (marker)」（也稱為「探針 " -"(probe)」）建置，可以透過 DTrace 或 SystemTap 腳本進行觀察，從而更輕鬆地監視" -"系統之 CPython 行程正在執行的操作。" - -#: ../../howto/instrumentation.rst:27 -msgid "" -"DTrace markers are implementation details of the CPython interpreter. No " -"guarantees are made about probe compatibility between versions of CPython. " -"DTrace scripts can stop working or work incorrectly without warning when " -"changing CPython versions." -msgstr "" -"DTrace 標記是 CPython 直譯器的實作細節。不保證 CPython 版本之間的探針相容性。" -"更改 CPython 版本時，DTrace 腳本可能會停止運作或錯誤地運作，而不會發出警告。" - -#: ../../howto/instrumentation.rst:34 -msgid "Enabling the static markers" -msgstr "啟用靜態標記" - -#: ../../howto/instrumentation.rst:36 -msgid "" -"macOS comes with built-in support for DTrace. On Linux, in order to build " -"CPython with the embedded markers for SystemTap, the SystemTap development " -"tools must be installed." -msgstr "" -"macOS 內建了對 DTrace 的支援。在 Linux 上，為了建置帶有 SystemTap 嵌入標記的 " -"CPython，必須安裝 SystemTap 開發工具。" - -#: ../../howto/instrumentation.rst:40 -msgid "On a Linux machine, this can be done via::" -msgstr "在 Linux 機器上，這可以透過以下方式完成： ::" - -#: ../../howto/instrumentation.rst:42 -msgid "$ yum install systemtap-sdt-devel" -msgstr "$ yum install systemtap-sdt-devel" - -#: ../../howto/instrumentation.rst:44 -msgid "or::" -msgstr "或是： ::" - -#: ../../howto/instrumentation.rst:46 -msgid "$ sudo apt-get install systemtap-sdt-dev" -msgstr "$ sudo apt-get install systemtap-sdt-dev" - -#: ../../howto/instrumentation.rst:49 -msgid "" -"CPython must then be :option:`configured with the --with-dtrace option <--" -"with-dtrace>`:" -msgstr "" -"然後 CPython 必須使用\\ :option:`配置 --with-dtrace 選項 <--with-dtrace>`：" - -#: ../../howto/instrumentation.rst:52 -msgid "checking for --with-dtrace... yes" -msgstr "checking for --with-dtrace... yes" - -#: ../../howto/instrumentation.rst:56 -msgid "" -"On macOS, you can list available DTrace probes by running a Python process " -"in the background and listing all probes made available by the Python " -"provider::" -msgstr "" -"在 macOS 上，你可以透過在後台運行 Python 行程並列出 Python 發布者 (provider) " -"所提供的所有可用探針，以列出可用的 DTrace 探針： ::" - -#: ../../howto/instrumentation.rst:60 -msgid "" -"$ python3.6 -q &\n" -"$ sudo dtrace -l -P python$! # or: dtrace -l -m python3.6\n" -"\n" -" ID PROVIDER MODULE FUNCTION NAME\n" -"29564 python18035 python3.6 _PyEval_EvalFrameDefault " -"function-entry\n" -"29565 python18035 python3.6 dtrace_function_entry " -"function-entry\n" -"29566 python18035 python3.6 _PyEval_EvalFrameDefault " -"function-return\n" -"29567 python18035 python3.6 dtrace_function_return " -"function-return\n" -"29568 python18035 python3.6 collect gc-" -"done\n" -"29569 python18035 python3.6 collect gc-" -"start\n" -"29570 python18035 python3.6 _PyEval_EvalFrameDefault line\n" -"29571 python18035 python3.6 maybe_dtrace_line line" -msgstr "" -"$ python3.6 -q &\n" -"$ sudo dtrace -l -P python$! # 或 dtrace -l -m python3.6\n" -"\n" -" ID PROVIDER MODULE FUNCTION NAME\n" -"29564 python18035 python3.6 _PyEval_EvalFrameDefault " -"function-entry\n" -"29565 python18035 python3.6 dtrace_function_entry " -"function-entry\n" -"29566 python18035 python3.6 _PyEval_EvalFrameDefault " -"function-return\n" -"29567 python18035 python3.6 dtrace_function_return " -"function-return\n" -"29568 python18035 python3.6 collect gc-" -"done\n" -"29569 python18035 python3.6 collect gc-" -"start\n" -"29570 python18035 python3.6 _PyEval_EvalFrameDefault line\n" -"29571 python18035 python3.6 maybe_dtrace_line line" - -#: ../../howto/instrumentation.rst:73 -msgid "" -"On Linux, you can verify if the SystemTap static markers are present in the " -"built binary by seeing if it contains a \".note.stapsdt\" section." -msgstr "" -"在 Linux 上，你可以透過查看二進位建置檔案中是否包含 \".note.stapsdt\" 部分來" -"驗證 SystemTap 靜態標記是否存在。" - -#: ../../howto/instrumentation.rst:78 -msgid "" -"$ readelf -S ./python | grep .note.stapsdt\n" -"[30] .note.stapsdt NOTE 0000000000000000 00308d78" -msgstr "" -"$ readelf -S ./python | grep .note.stapsdt\n" -"[30] .note.stapsdt NOTE 0000000000000000 00308d78" - -#: ../../howto/instrumentation.rst:81 -msgid "" -"If you've built Python as a shared library (with the :option:`--enable-" -"shared` configure option), you need to look instead within the shared " -"library. For example::" -msgstr "" -"如果你已將 Python 建置為共享函式庫（使用 :option:`--enable-shared` 配置選" -"項），則需要在共享函式庫中查找。例如： ::" - -#: ../../howto/instrumentation.rst:85 -msgid "" -"$ readelf -S libpython3.3dm.so.1.0 | grep .note.stapsdt\n" -"[29] .note.stapsdt NOTE 0000000000000000 00365b68" -msgstr "" -"$ readelf -S libpython3.3dm.so.1.0 | grep .note.stapsdt\n" -"[29] .note.stapsdt NOTE 0000000000000000 00365b68" - -#: ../../howto/instrumentation.rst:88 -msgid "Sufficiently modern readelf can print the metadata::" -msgstr "足夠現代化的 readelf 可以印出元資料 (metadata)： ::" - -#: ../../howto/instrumentation.rst:90 -msgid "" -"$ readelf -n ./python\n" -"\n" -"Displaying notes found at file offset 0x00000254 with length 0x00000020:\n" -" Owner Data size Description\n" -" GNU 0x00000010 NT_GNU_ABI_TAG (ABI version " -"tag)\n" -" OS: Linux, ABI: 2.6.32\n" -"\n" -"Displaying notes found at file offset 0x00000274 with length 0x00000024:\n" -" Owner Data size Description\n" -" GNU 0x00000014 NT_GNU_BUILD_ID (unique build " -"ID bitstring)\n" -" Build ID: df924a2b08a7e89f6e11251d4602022977af2670\n" -"\n" -"Displaying notes found at file offset 0x002d6c30 with length 0x00000144:\n" -" Owner Data size Description\n" -" stapsdt 0x00000031 NT_STAPSDT (SystemTap probe " -"descriptors)\n" -" Provider: python\n" -" Name: gc__start\n" -" Location: 0x00000000004371c3, Base: 0x0000000000630ce2, Semaphore: " -"0x00000000008d6bf6\n" -" Arguments: -4@%ebx\n" -" stapsdt 0x00000030 NT_STAPSDT (SystemTap probe " -"descriptors)\n" -" Provider: python\n" -" Name: gc__done\n" -" Location: 0x00000000004374e1, Base: 0x0000000000630ce2, Semaphore: " -"0x00000000008d6bf8\n" -" Arguments: -8@%rax\n" -" stapsdt 0x00000045 NT_STAPSDT (SystemTap probe " -"descriptors)\n" -" Provider: python\n" -" Name: function__entry\n" -" Location: 0x000000000053db6c, Base: 0x0000000000630ce2, Semaphore: " -"0x00000000008d6be8\n" -" Arguments: 8@%rbp 8@%r12 -4@%eax\n" -" stapsdt 0x00000046 NT_STAPSDT (SystemTap probe " -"descriptors)\n" -" Provider: python\n" -" Name: function__return\n" -" Location: 0x000000000053dba8, Base: 0x0000000000630ce2, Semaphore: " -"0x00000000008d6bea\n" -" Arguments: 8@%rbp 8@%r12 -4@%eax" -msgstr "" -"$ readelf -n ./python\n" -"\n" -"Displaying notes found at file offset 0x00000254 with length 0x00000020:\n" -" Owner Data size Description\n" -" GNU 0x00000010 NT_GNU_ABI_TAG (ABI version " -"tag)\n" -" OS: Linux, ABI: 2.6.32\n" -"\n" -"Displaying notes found at file offset 0x00000274 with length 0x00000024:\n" -" Owner Data size Description\n" -" GNU 0x00000014 NT_GNU_BUILD_ID (unique build " -"ID bitstring)\n" -" Build ID: df924a2b08a7e89f6e11251d4602022977af2670\n" -"\n" -"Displaying notes found at file offset 0x002d6c30 with length 0x00000144:\n" -" Owner Data size Description\n" -" stapsdt 0x00000031 NT_STAPSDT (SystemTap probe " -"descriptors)\n" -" Provider: python\n" -" Name: gc__start\n" -" Location: 0x00000000004371c3, Base: 0x0000000000630ce2, Semaphore: " -"0x00000000008d6bf6\n" -" Arguments: -4@%ebx\n" -" stapsdt 0x00000030 NT_STAPSDT (SystemTap probe " -"descriptors)\n" -" Provider: python\n" -" Name: gc__done\n" -" Location: 0x00000000004374e1, Base: 0x0000000000630ce2, Semaphore: " -"0x00000000008d6bf8\n" -" Arguments: -8@%rax\n" -" stapsdt 0x00000045 NT_STAPSDT (SystemTap probe " -"descriptors)\n" -" Provider: python\n" -" Name: function__entry\n" -" Location: 0x000000000053db6c, Base: 0x0000000000630ce2, Semaphore: " -"0x00000000008d6be8\n" -" Arguments: 8@%rbp 8@%r12 -4@%eax\n" -" stapsdt 0x00000046 NT_STAPSDT (SystemTap probe " -"descriptors)\n" -" Provider: python\n" -" Name: function__return\n" -" Location: 0x000000000053dba8, Base: 0x0000000000630ce2, Semaphore: " -"0x00000000008d6bea\n" -" Arguments: 8@%rbp 8@%r12 -4@%eax" - -#: ../../howto/instrumentation.rst:125 -msgid "" -"The above metadata contains information for SystemTap describing how it can " -"patch strategically placed machine code instructions to enable the tracing " -"hooks used by a SystemTap script." -msgstr "" -"上述元資料包含 SystemTap 的資訊，描述了它如何修補策略性放置的機器碼指令以啟" -"用 SystemTap 腳本使用的追蹤 hook。" - -#: ../../howto/instrumentation.rst:131 -msgid "Static DTrace probes" -msgstr "靜態 DTrace 探針" - -#: ../../howto/instrumentation.rst:133 -msgid "" -"The following example DTrace script can be used to show the call/return " -"hierarchy of a Python script, only tracing within the invocation of a " -"function called \"start\". In other words, import-time function invocations " -"are not going to be listed:" -msgstr "" -"以下範例示範 DTrace 腳本可用於顯示 Python 腳本的呼叫/回傳階層結構，僅在名為 " -"\"start\" 的函式的呼叫內進行追蹤。換句話說，引入時的函式呼叫不會被列出：" - -#: ../../howto/instrumentation.rst:138 -msgid "" -"self int indent;\n" -"\n" -"python$target:::function-entry\n" -"/copyinstr(arg1) == \"start\"/\n" -"{\n" -" self->trace = 1;\n" -"}\n" -"\n" -"python$target:::function-entry\n" -"/self->trace/\n" -"{\n" -" printf(\"%d\\t%*s:\", timestamp, 15, probename);\n" -" printf(\"%*s\", self->indent, \"\");\n" -" printf(\"%s:%s:%d\\n\", basename(copyinstr(arg0)), copyinstr(arg1), " -"arg2);\n" -" self->indent++;\n" -"}\n" -"\n" -"python$target:::function-return\n" -"/self->trace/\n" -"{\n" -" self->indent--;\n" -" printf(\"%d\\t%*s:\", timestamp, 15, probename);\n" -" printf(\"%*s\", self->indent, \"\");\n" -" printf(\"%s:%s:%d\\n\", basename(copyinstr(arg0)), copyinstr(arg1), " -"arg2);\n" -"}\n" -"\n" -"python$target:::function-return\n" -"/copyinstr(arg1) == \"start\"/\n" -"{\n" -" self->trace = 0;\n" -"}" -msgstr "" -"self int indent;\n" -"\n" -"python$target:::function-entry\n" -"/copyinstr(arg1) == \"start\"/\n" -"{\n" -" self->trace = 1;\n" -"}\n" -"\n" -"python$target:::function-entry\n" -"/self->trace/\n" -"{\n" -" printf(\"%d\\t%*s:\", timestamp, 15, probename);\n" -" printf(\"%*s\", self->indent, \"\");\n" -" printf(\"%s:%s:%d\\n\", basename(copyinstr(arg0)), copyinstr(arg1), " -"arg2);\n" -" self->indent++;\n" -"}\n" -"\n" -"python$target:::function-return\n" -"/self->trace/\n" -"{\n" -" self->indent--;\n" -" printf(\"%d\\t%*s:\", timestamp, 15, probename);\n" -" printf(\"%*s\", self->indent, \"\");\n" -" printf(\"%s:%s:%d\\n\", basename(copyinstr(arg0)), copyinstr(arg1), " -"arg2);\n" -"}\n" -"\n" -"python$target:::function-return\n" -"/copyinstr(arg1) == \"start\"/\n" -"{\n" -" self->trace = 0;\n" -"}" - -#: ../../howto/instrumentation.rst:172 ../../howto/instrumentation.rst:230 -msgid "It can be invoked like this::" -msgstr "可以這樣呼叫： ::" - -#: ../../howto/instrumentation.rst:174 -msgid "$ sudo dtrace -q -s call_stack.d -c \"python3.6 script.py\"" -msgstr "$ sudo dtrace -q -s call_stack.d -c \"python3.6 script.py\"" - -#: ../../howto/instrumentation.rst:176 ../../howto/instrumentation.rst:236 -msgid "The output looks like this:" -msgstr "輸出如下所示：" - -#: ../../howto/instrumentation.rst:178 -msgid "" -"156641360502280 function-entry:call_stack.py:start:23\n" -"156641360518804 function-entry: call_stack.py:function_1:1\n" -"156641360532797 function-entry: call_stack.py:function_3:9\n" -"156641360546807 function-return: call_stack.py:function_3:10\n" -"156641360563367 function-return: call_stack.py:function_1:2\n" -"156641360578365 function-entry: call_stack.py:function_2:5\n" -"156641360591757 function-entry: call_stack.py:function_1:1\n" -"156641360605556 function-entry: call_stack.py:function_3:9\n" -"156641360617482 function-return: call_stack.py:function_3:10\n" -"156641360629814 function-return: call_stack.py:function_1:2\n" -"156641360642285 function-return: call_stack.py:function_2:6\n" -"156641360656770 function-entry: call_stack.py:function_3:9\n" -"156641360669707 function-return: call_stack.py:function_3:10\n" -"156641360687853 function-entry: call_stack.py:function_4:13\n" -"156641360700719 function-return: call_stack.py:function_4:14\n" -"156641360719640 function-entry: call_stack.py:function_5:18\n" -"156641360732567 function-return: call_stack.py:function_5:21\n" -"156641360747370 function-return:call_stack.py:start:28" -msgstr "" -"156641360502280 function-entry:call_stack.py:start:23\n" -"156641360518804 function-entry: call_stack.py:function_1:1\n" -"156641360532797 function-entry: call_stack.py:function_3:9\n" -"156641360546807 function-return: call_stack.py:function_3:10\n" -"156641360563367 function-return: call_stack.py:function_1:2\n" -"156641360578365 function-entry: call_stack.py:function_2:5\n" -"156641360591757 function-entry: call_stack.py:function_1:1\n" -"156641360605556 function-entry: call_stack.py:function_3:9\n" -"156641360617482 function-return: call_stack.py:function_3:10\n" -"156641360629814 function-return: call_stack.py:function_1:2\n" -"156641360642285 function-return: call_stack.py:function_2:6\n" -"156641360656770 function-entry: call_stack.py:function_3:9\n" -"156641360669707 function-return: call_stack.py:function_3:10\n" -"156641360687853 function-entry: call_stack.py:function_4:13\n" -"156641360700719 function-return: call_stack.py:function_4:14\n" -"156641360719640 function-entry: call_stack.py:function_5:18\n" -"156641360732567 function-return: call_stack.py:function_5:21\n" -"156641360747370 function-return:call_stack.py:start:28" - -#: ../../howto/instrumentation.rst:201 -msgid "Static SystemTap markers" -msgstr "靜態 SystemTap 標記" - -#: ../../howto/instrumentation.rst:203 -msgid "" -"The low-level way to use the SystemTap integration is to use the static " -"markers directly. This requires you to explicitly state the binary file " -"containing them." -msgstr "" -"使用 SystemTap 整合的低階方法是直接使用靜態標記。這會需要你明確聲明包含它們的" -"二進位檔案。" - -#: ../../howto/instrumentation.rst:207 -msgid "" -"For example, this SystemTap script can be used to show the call/return " -"hierarchy of a Python script:" -msgstr "例如，此 SystemTap 腳本可用於顯示 Python 腳本的呼叫/回傳階層結構：" - -#: ../../howto/instrumentation.rst:210 -msgid "" -"probe process(\"python\").mark(\"function__entry\") {\n" -" filename = user_string($arg1);\n" -" funcname = user_string($arg2);\n" -" lineno = $arg3;\n" -"\n" -" printf(\"%s => %s in %s:%d\\\\n\",\n" -" thread_indent(1), funcname, filename, lineno);\n" -"}\n" -"\n" -"probe process(\"python\").mark(\"function__return\") {\n" -" filename = user_string($arg1);\n" -" funcname = user_string($arg2);\n" -" lineno = $arg3;\n" -"\n" -" printf(\"%s <= %s in %s:%d\\\\n\",\n" -" thread_indent(-1), funcname, filename, lineno);\n" -"}" -msgstr "" -"probe process(\"python\").mark(\"function__entry\") {\n" -" filename = user_string($arg1);\n" -" funcname = user_string($arg2);\n" -" lineno = $arg3;\n" -"\n" -" printf(\"%s => %s in %s:%d\\\\n\",\n" -" thread_indent(1), funcname, filename, lineno);\n" -"}\n" -"\n" -"probe process(\"python\").mark(\"function__return\") {\n" -" filename = user_string($arg1);\n" -" funcname = user_string($arg2);\n" -" lineno = $arg3;\n" -"\n" -" printf(\"%s <= %s in %s:%d\\\\n\",\n" -" thread_indent(-1), funcname, filename, lineno);\n" -"}" - -#: ../../howto/instrumentation.rst:232 -msgid "" -"$ stap \\\n" -" show-call-hierarchy.stp \\\n" -" -c \"./python test.py\"" -msgstr "" -"$ stap \\\n" -" show-call-hierarchy.stp \\\n" -" -c \"./python test.py\"" - -#: ../../howto/instrumentation.rst:238 -msgid "" -"11408 python(8274): => __contains__ in Lib/_abcoll.py:362\n" -"11414 python(8274): => __getitem__ in Lib/os.py:425\n" -"11418 python(8274): => encode in Lib/os.py:490\n" -"11424 python(8274): <= encode in Lib/os.py:493\n" -"11428 python(8274): <= __getitem__ in Lib/os.py:426\n" -"11433 python(8274): <= __contains__ in Lib/_abcoll.py:366" -msgstr "" -"11408 python(8274): => __contains__ in Lib/_abcoll.py:362\n" -"11414 python(8274): => __getitem__ in Lib/os.py:425\n" -"11418 python(8274): => encode in Lib/os.py:490\n" -"11424 python(8274): <= encode in Lib/os.py:493\n" -"11428 python(8274): <= __getitem__ in Lib/os.py:426\n" -"11433 python(8274): <= __contains__ in Lib/_abcoll.py:366" - -#: ../../howto/instrumentation.rst:247 -msgid "where the columns are:" -msgstr "其中的行 (column) 是：" - -#: ../../howto/instrumentation.rst:249 -msgid "time in microseconds since start of script" -msgstr "自腳本開始以來的時間（以微秒為單位）" - -#: ../../howto/instrumentation.rst:250 -msgid "name of executable" -msgstr "可執行檔案的名稱" - -#: ../../howto/instrumentation.rst:251 -msgid "PID of process" -msgstr "行程的 PID" - -#: ../../howto/instrumentation.rst:253 -msgid "" -"and the remainder indicates the call/return hierarchy as the script executes." -msgstr "其餘部分表示腳本執行時的呼叫/回傳階層結構。" - -#: ../../howto/instrumentation.rst:255 -msgid "" -"For a :option:`--enable-shared` build of CPython, the markers are contained " -"within the libpython shared library, and the probe's dotted path needs to " -"reflect this. For example, this line from the above example:" -msgstr "" -"對於以 :option:`--enable-shared` 建置的 CPython，標記被包含在 libpython 共享" -"函式庫中，並且探針的帶點路徑 (dotted path) 需要反映這一點。例如，上面範例中的" -"這一列：" - -#: ../../howto/instrumentation.rst:259 -msgid "probe process(\"python\").mark(\"function__entry\") {" -msgstr "probe process(\"python\").mark(\"function__entry\") {" - -#: ../../howto/instrumentation.rst:263 -msgid "should instead read:" -msgstr "應該改為讀取：" - -#: ../../howto/instrumentation.rst:265 -msgid "" -"probe process(\"python\").library(\"libpython3.6dm.so.1.0\")." -"mark(\"function__entry\") {" -msgstr "" -"probe process(\"python\").library(\"libpython3.6dm.so.1.0\")." -"mark(\"function__entry\") {" - -#: ../../howto/instrumentation.rst:269 -msgid "(assuming a :ref:`debug build ` of CPython 3.6)" -msgstr "（假設 CPython 3.6 的\\ :ref:`除錯建置版本 `）" - -#: ../../howto/instrumentation.rst:275 -msgid "Available static markers" -msgstr "可用的靜態標記" - -#: ../../howto/instrumentation.rst:279 -msgid "" -"This marker indicates that execution of a Python function has begun. It is " -"only triggered for pure-Python (bytecode) functions." -msgstr "" -"該標記表示 Python 函式的執行已經開始。它僅針對純 Python（位元組碼）函式觸發。" - -#: ../../howto/instrumentation.rst:282 -msgid "" -"The filename, function name, and line number are provided back to the " -"tracing script as positional arguments, which must be accessed using " -"``$arg1``, ``$arg2``, ``$arg3``:" -msgstr "" -"檔案名稱、函式名稱和列號作為位置引數提供給追蹤腳本，必須使用 ``$arg1``、" -"``$arg2``、``$arg3`` 來存取：" - -#: ../../howto/instrumentation.rst:286 -msgid "" -"``$arg1`` : ``(const char *)`` filename, accessible using " -"``user_string($arg1)``" -msgstr "" -"``$arg1`` : ``(const char *)`` 檔案名稱，可使用 ``user_string($arg1)`` 存取" - -#: ../../howto/instrumentation.rst:288 -msgid "" -"``$arg2`` : ``(const char *)`` function name, accessible using " -"``user_string($arg2)``" -msgstr "" -"``$arg2`` ：``(const char *)`` 函式名稱，可使用 ``user_string($arg2)`` 存取" - -#: ../../howto/instrumentation.rst:291 -msgid "``$arg3`` : ``int`` line number" -msgstr "``$arg3`` : ``int`` 列號" - -#: ../../howto/instrumentation.rst:295 -msgid "" -"This marker is the converse of :c:func:`!function__entry`, and indicates " -"that execution of a Python function has ended (either via ``return``, or via " -"an exception). It is only triggered for pure-Python (bytecode) functions." -msgstr "" -"該標記與 :c:func:`!function__entry` 相反，表示 Python 函式的執行已結束（透過 " -"``return`` 或透過例外）。它僅針對純 Python（位元組碼）函式觸發。" - -#: ../../howto/instrumentation.rst:299 -msgid "The arguments are the same as for :c:func:`!function__entry`" -msgstr "引數與 :c:func:`!function__entry` 相同" - -#: ../../howto/instrumentation.rst:303 -msgid "" -"This marker indicates a Python line is about to be executed. It is the " -"equivalent of line-by-line tracing with a Python profiler. It is not " -"triggered within C functions." -msgstr "" -"該標記表示一列 Python 即將被執行。它相當於使用 Python 分析器來逐行追蹤。它不" -"在 C 函式內觸發。" - -#: ../../howto/instrumentation.rst:307 -msgid "The arguments are the same as for :c:func:`!function__entry`." -msgstr "引數與 :c:func:`!function__entry` 相同。" - -#: ../../howto/instrumentation.rst:311 -msgid "" -"Fires when the Python interpreter starts a garbage collection cycle. " -"``arg0`` is the generation to scan, like :func:`gc.collect`." -msgstr "" -"當 Python 直譯器開始垃圾回收 (garbage collection) 週期時觸發。``arg0`` 是要掃" -"描的一代 (generation)，如 :func:`gc.collect`。" - -#: ../../howto/instrumentation.rst:316 -msgid "" -"Fires when the Python interpreter finishes a garbage collection cycle. " -"``arg0`` is the number of collected objects." -msgstr "當 Python 直譯器完成垃圾回收週期時觸發。``arg0`` 是收集到的物件數量。" - -#: ../../howto/instrumentation.rst:321 -msgid "" -"Fires before :mod:`importlib` attempts to find and load the module. ``arg0`` " -"is the module name." -msgstr "在 :mod:`importlib` 嘗試查找並載入模組之前觸發。``arg0`` 是模組名稱。" - -#: ../../howto/instrumentation.rst:328 -msgid "" -"Fires after :mod:`importlib`'s find_and_load function is called. ``arg0`` is " -"the module name, ``arg1`` indicates if module was successfully loaded." -msgstr "" -"在呼叫 :mod:`importlib` 的 find_and_load 函式後觸發。 ``arg0`` 是模組名稱，" -"``arg1`` 代表模組是否已成功載入。" - -#: ../../howto/instrumentation.rst:337 -msgid "" -"Fires when :func:`sys.audit` or :c:func:`PySys_Audit` is called. ``arg0`` is " -"the event name as C string, ``arg1`` is a :c:type:`PyObject` pointer to a " -"tuple object." -msgstr "" -"當呼叫 :func:`sys.audit` 或 :c:func:`PySys_Audit` 時觸發。``arg0`` 是 C 字串" -"形式的事件名稱，``arg1`` 是指向元組 (tuple) 物件的 :c:type:`PyObject` 指標。" - -#: ../../howto/instrumentation.rst:345 -msgid "SystemTap Tapsets" -msgstr "SystemTap Tapsets" - -#: ../../howto/instrumentation.rst:347 -msgid "" -"The higher-level way to use the SystemTap integration is to use a " -"\"tapset\": SystemTap's equivalent of a library, which hides some of the " -"lower-level details of the static markers." -msgstr "" -"使用 SystemTap 整合的高階方法是使用 \"tapset\"：SystemTap 相當於一個函式庫，" -"它隱藏了靜態標記的一些低階詳細資訊。" - -#: ../../howto/instrumentation.rst:351 -msgid "Here is a tapset file, based on a non-shared build of CPython:" -msgstr "這是一個 tapset 檔案，是基於 CPython 的非共享建置版本：" - -#: ../../howto/instrumentation.rst:353 -msgid "" -"/*\n" -" Provide a higher-level wrapping around the function__entry and\n" -" function__return markers:\n" -" \\*/\n" -"probe python.function.entry = process(\"python\").mark(\"function__entry\")\n" -"{\n" -" filename = user_string($arg1);\n" -" funcname = user_string($arg2);\n" -" lineno = $arg3;\n" -" frameptr = $arg4\n" -"}\n" -"probe python.function.return = process(\"python\")." -"mark(\"function__return\")\n" -"{\n" -" filename = user_string($arg1);\n" -" funcname = user_string($arg2);\n" -" lineno = $arg3;\n" -" frameptr = $arg4\n" -"}" -msgstr "" -"/*\n" -" 提供一個更高階、在 function__entry 和 function__return 標記上的包裝：\n" -" \\*/\n" -"probe python.function.entry = process(\"python\").mark(\"function__entry\")\n" -"{\n" -" filename = user_string($arg1);\n" -" funcname = user_string($arg2);\n" -" lineno = $arg3;\n" -" frameptr = $arg4\n" -"}\n" -"probe python.function.return = process(\"python\")." -"mark(\"function__return\")\n" -"{\n" -" filename = user_string($arg1);\n" -" funcname = user_string($arg2);\n" -" lineno = $arg3;\n" -" frameptr = $arg4\n" -"}" - -#: ../../howto/instrumentation.rst:374 -msgid "" -"If this file is installed in SystemTap's tapset directory (e.g. ``/usr/share/" -"systemtap/tapset``), then these additional probepoints become available:" -msgstr "" -"如果此檔案是安裝在 SystemTap 的 tapset 目錄中（例如 ``/usr/share/systemtap/" -"tapset``），則這些額外的探測點將可被使用：" - -#: ../../howto/instrumentation.rst:380 -msgid "" -"This probe point indicates that execution of a Python function has begun. It " -"is only triggered for pure-Python (bytecode) functions." -msgstr "" -"該探測點表示 Python 函式的執行已經開始。它僅針對純 Python（位元組碼）函式觸" -"發。" - -#: ../../howto/instrumentation.rst:385 -msgid "" -"This probe point is the converse of ``python.function.return``, and " -"indicates that execution of a Python function has ended (either via " -"``return``, or via an exception). It is only triggered for pure-Python " -"(bytecode) functions." -msgstr "" -"這個探測點與 ``python.function.return`` 相反，表示 Python 函式的執行已經結束" -"（透過 ``return`` 或者透過例外）。它僅針對純 Python（位元組碼）函式觸發。" - -#: ../../howto/instrumentation.rst:392 -msgid "Examples" -msgstr "範例" - -#: ../../howto/instrumentation.rst:393 -msgid "" -"This SystemTap script uses the tapset above to more cleanly implement the " -"example given above of tracing the Python function-call hierarchy, without " -"needing to directly name the static markers:" -msgstr "" -"此 SystemTap 腳本使用上面的 tapset 來更清晰地實作上面給出的追蹤 Python 函式呼" -"叫階層結構的範例，而無需直接命名靜態標記：" - -#: ../../howto/instrumentation.rst:397 -msgid "" -"probe python.function.entry\n" -"{\n" -" printf(\"%s => %s in %s:%d\\n\",\n" -" thread_indent(1), funcname, filename, lineno);\n" -"}\n" -"\n" -"probe python.function.return\n" -"{\n" -" printf(\"%s <= %s in %s:%d\\n\",\n" -" thread_indent(-1), funcname, filename, lineno);\n" -"}" -msgstr "" -"probe python.function.entry\n" -"{\n" -" printf(\"%s => %s in %s:%d\\n\",\n" -" thread_indent(1), funcname, filename, lineno);\n" -"}\n" -"\n" -"probe python.function.return\n" -"{\n" -" printf(\"%s <= %s in %s:%d\\n\",\n" -" thread_indent(-1), funcname, filename, lineno);\n" -"}" - -#: ../../howto/instrumentation.rst:412 -msgid "" -"The following script uses the tapset above to provide a top-like view of all " -"running CPython code, showing the top 20 most frequently entered bytecode " -"frames, each second, across the whole system:" -msgstr "" -"以下腳本使用上面的 tapset 來提供所有正在運行之 CPython 程式碼的近乎最高層視" -"角，顯示整個系統中每秒最常被進入的 20 個位元組碼幀 (bytecode frame)：" - -#: ../../howto/instrumentation.rst:416 -msgid "" -"global fn_calls;\n" -"\n" -"probe python.function.entry\n" -"{\n" -" fn_calls[pid(), filename, funcname, lineno] += 1;\n" -"}\n" -"\n" -"probe timer.ms(1000) {\n" -" printf(\"\\033[2J\\033[1;1H\") /* clear screen \\*/\n" -" printf(\"%6s %80s %6s %30s %6s\\n\",\n" -" \"PID\", \"FILENAME\", \"LINE\", \"FUNCTION\", \"CALLS\")\n" -" foreach ([pid, filename, funcname, lineno] in fn_calls- limit 20) {\n" -" printf(\"%6d %80s %6d %30s %6d\\n\",\n" -" pid, filename, lineno, funcname,\n" -" fn_calls[pid, filename, funcname, lineno]);\n" -" }\n" -" delete fn_calls;\n" -"}" -msgstr "" -"global fn_calls;\n" -"\n" -"probe python.function.entry\n" -"{\n" -" fn_calls[pid(), filename, funcname, lineno] += 1;\n" -"}\n" -"\n" -"probe timer.ms(1000) {\n" -" printf(\"\\033[2J\\033[1;1H\") /* clear screen \\*/\n" -" printf(\"%6s %80s %6s %30s %6s\\n\",\n" -" \"PID\", \"FILENAME\", \"LINE\", \"FUNCTION\", \"CALLS\")\n" -" foreach ([pid, filename, funcname, lineno] in fn_calls- limit 20) {\n" -" printf(\"%6d %80s %6d %30s %6d\\n\",\n" -" pid, filename, lineno, funcname,\n" -" fn_calls[pid, filename, funcname, lineno]);\n" -" }\n" -" delete fn_calls;\n" -"}" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Matt Wang +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-04 00:15+0000\n" +"PO-Revision-Date: 2023-08-17 22:17+0800\n" +"Last-Translator: Matt Wang \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" +"X-Generator: Poedit 3.3.2\n" + +#: ../../howto/instrumentation.rst:7 +msgid "Instrumenting CPython with DTrace and SystemTap" +msgstr "使用 DTrace 和 SystemTap 檢測 CPython" + +#: ../../howto/instrumentation.rst:0 +msgid "author" +msgstr "作者" + +#: ../../howto/instrumentation.rst:9 +msgid "David Malcolm" +msgstr "David Malcolm" + +#: ../../howto/instrumentation.rst:10 +msgid "Łukasz Langa" +msgstr "Łukasz Langa" + +#: ../../howto/instrumentation.rst:12 +msgid "" +"DTrace and SystemTap are monitoring tools, each providing a way to inspect " +"what the processes on a computer system are doing. They both use domain-" +"specific languages allowing a user to write scripts which:" +msgstr "" +"DTrace 和 SystemTap 都是監測工具，各自都提供了一種檢查電腦系統之行程 " +"(process) 正在執行什麼操作的方法。它們都使用了領域限定 (domain-specific) 的語" +"言，允許使用者編寫以下腳本：" + +#: ../../howto/instrumentation.rst:16 +msgid "filter which processes are to be observed" +msgstr "過濾要觀察的行程" + +#: ../../howto/instrumentation.rst:17 +msgid "gather data from the processes of interest" +msgstr "收集來自感興趣之行程的資料" + +#: ../../howto/instrumentation.rst:18 +msgid "generate reports on the data" +msgstr "以這些資料產生報告" + +#: ../../howto/instrumentation.rst:20 +msgid "" +"As of Python 3.6, CPython can be built with embedded \"markers\", also known " +"as \"probes\", that can be observed by a DTrace or SystemTap script, making " +"it easier to monitor what the CPython processes on a system are doing." +msgstr "" +"從 Python 3.6 開始，CPython 可以使用嵌入式「標記 (marker)」（也稱為「探針 " +"(probe)」）建置，可以透過 DTrace 或 SystemTap 腳本進行觀察，從而更輕鬆地監視" +"系統之 CPython 行程正在執行的操作。" + +#: ../../howto/instrumentation.rst:27 +msgid "" +"DTrace markers are implementation details of the CPython interpreter. No " +"guarantees are made about probe compatibility between versions of CPython. " +"DTrace scripts can stop working or work incorrectly without warning when " +"changing CPython versions." +msgstr "" +"DTrace 標記是 CPython 直譯器的實作細節。不保證 CPython 版本之間的探針相容性。" +"更改 CPython 版本時，DTrace 腳本可能會停止運作或錯誤地運作，而不會發出警告。" + +#: ../../howto/instrumentation.rst:34 +msgid "Enabling the static markers" +msgstr "啟用靜態標記" + +#: ../../howto/instrumentation.rst:36 +msgid "" +"macOS comes with built-in support for DTrace. On Linux, in order to build " +"CPython with the embedded markers for SystemTap, the SystemTap development " +"tools must be installed." +msgstr "" +"macOS 內建了對 DTrace 的支援。在 Linux 上，為了建置帶有 SystemTap 嵌入標記的 " +"CPython，必須安裝 SystemTap 開發工具。" + +#: ../../howto/instrumentation.rst:40 +msgid "On a Linux machine, this can be done via::" +msgstr "在 Linux 機器上，這可以透過以下方式完成： ::" + +#: ../../howto/instrumentation.rst:42 +msgid "$ yum install systemtap-sdt-devel" +msgstr "$ yum install systemtap-sdt-devel" + +#: ../../howto/instrumentation.rst:44 +msgid "or::" +msgstr "或是： ::" + +#: ../../howto/instrumentation.rst:46 +msgid "$ sudo apt-get install systemtap-sdt-dev" +msgstr "$ sudo apt-get install systemtap-sdt-dev" + +#: ../../howto/instrumentation.rst:49 +msgid "" +"CPython must then be :option:`configured with the --with-dtrace option <--" +"with-dtrace>`:" +msgstr "" +"然後 CPython 必須使用\\ :option:`配置 --with-dtrace 選項 <--with-dtrace>`：" + +#: ../../howto/instrumentation.rst:52 +msgid "checking for --with-dtrace... yes" +msgstr "checking for --with-dtrace... yes" + +#: ../../howto/instrumentation.rst:56 +msgid "" +"On macOS, you can list available DTrace probes by running a Python process " +"in the background and listing all probes made available by the Python " +"provider::" +msgstr "" +"在 macOS 上，你可以透過在後台運行 Python 行程並列出 Python 發布者 (provider) " +"所提供的所有可用探針，以列出可用的 DTrace 探針： ::" + +#: ../../howto/instrumentation.rst:60 +msgid "" +"$ python3.6 -q &\n" +"$ sudo dtrace -l -P python$! # or: dtrace -l -m python3.6\n" +"\n" +" ID PROVIDER MODULE FUNCTION NAME\n" +"29564 python18035 python3.6 _PyEval_EvalFrameDefault " +"function-entry\n" +"29565 python18035 python3.6 dtrace_function_entry " +"function-entry\n" +"29566 python18035 python3.6 _PyEval_EvalFrameDefault " +"function-return\n" +"29567 python18035 python3.6 dtrace_function_return " +"function-return\n" +"29568 python18035 python3.6 collect gc-" +"done\n" +"29569 python18035 python3.6 collect gc-" +"start\n" +"29570 python18035 python3.6 _PyEval_EvalFrameDefault line\n" +"29571 python18035 python3.6 maybe_dtrace_line line" +msgstr "" +"$ python3.6 -q &\n" +"$ sudo dtrace -l -P python$! # 或 dtrace -l -m python3.6\n" +"\n" +" ID PROVIDER MODULE FUNCTION NAME\n" +"29564 python18035 python3.6 _PyEval_EvalFrameDefault " +"function-entry\n" +"29565 python18035 python3.6 dtrace_function_entry " +"function-entry\n" +"29566 python18035 python3.6 _PyEval_EvalFrameDefault " +"function-return\n" +"29567 python18035 python3.6 dtrace_function_return " +"function-return\n" +"29568 python18035 python3.6 collect gc-" +"done\n" +"29569 python18035 python3.6 collect gc-" +"start\n" +"29570 python18035 python3.6 _PyEval_EvalFrameDefault line\n" +"29571 python18035 python3.6 maybe_dtrace_line line" + +#: ../../howto/instrumentation.rst:73 +msgid "" +"On Linux, you can verify if the SystemTap static markers are present in the " +"built binary by seeing if it contains a \".note.stapsdt\" section." +msgstr "" +"在 Linux 上，你可以透過查看二進位建置檔案中是否包含 \".note.stapsdt\" 部分來" +"驗證 SystemTap 靜態標記是否存在。" + +#: ../../howto/instrumentation.rst:78 +msgid "" +"$ readelf -S ./python | grep .note.stapsdt\n" +"[30] .note.stapsdt NOTE 0000000000000000 00308d78" +msgstr "" +"$ readelf -S ./python | grep .note.stapsdt\n" +"[30] .note.stapsdt NOTE 0000000000000000 00308d78" + +#: ../../howto/instrumentation.rst:81 +msgid "" +"If you've built Python as a shared library (with the :option:`--enable-" +"shared` configure option), you need to look instead within the shared " +"library. For example::" +msgstr "" +"如果你已將 Python 建置為共享函式庫（使用 :option:`--enable-shared` 配置選" +"項），則需要在共享函式庫中查找。例如： ::" + +#: ../../howto/instrumentation.rst:85 +msgid "" +"$ readelf -S libpython3.3dm.so.1.0 | grep .note.stapsdt\n" +"[29] .note.stapsdt NOTE 0000000000000000 00365b68" +msgstr "" +"$ readelf -S libpython3.3dm.so.1.0 | grep .note.stapsdt\n" +"[29] .note.stapsdt NOTE 0000000000000000 00365b68" + +#: ../../howto/instrumentation.rst:88 +msgid "Sufficiently modern readelf can print the metadata::" +msgstr "足夠現代化的 readelf 可以印出元資料 (metadata)： ::" + +#: ../../howto/instrumentation.rst:90 +msgid "" +"$ readelf -n ./python\n" +"\n" +"Displaying notes found at file offset 0x00000254 with length 0x00000020:\n" +" Owner Data size Description\n" +" GNU 0x00000010 NT_GNU_ABI_TAG (ABI version " +"tag)\n" +" OS: Linux, ABI: 2.6.32\n" +"\n" +"Displaying notes found at file offset 0x00000274 with length 0x00000024:\n" +" Owner Data size Description\n" +" GNU 0x00000014 NT_GNU_BUILD_ID (unique build " +"ID bitstring)\n" +" Build ID: df924a2b08a7e89f6e11251d4602022977af2670\n" +"\n" +"Displaying notes found at file offset 0x002d6c30 with length 0x00000144:\n" +" Owner Data size Description\n" +" stapsdt 0x00000031 NT_STAPSDT (SystemTap probe " +"descriptors)\n" +" Provider: python\n" +" Name: gc__start\n" +" Location: 0x00000000004371c3, Base: 0x0000000000630ce2, Semaphore: " +"0x00000000008d6bf6\n" +" Arguments: -4@%ebx\n" +" stapsdt 0x00000030 NT_STAPSDT (SystemTap probe " +"descriptors)\n" +" Provider: python\n" +" Name: gc__done\n" +" Location: 0x00000000004374e1, Base: 0x0000000000630ce2, Semaphore: " +"0x00000000008d6bf8\n" +" Arguments: -8@%rax\n" +" stapsdt 0x00000045 NT_STAPSDT (SystemTap probe " +"descriptors)\n" +" Provider: python\n" +" Name: function__entry\n" +" Location: 0x000000000053db6c, Base: 0x0000000000630ce2, Semaphore: " +"0x00000000008d6be8\n" +" Arguments: 8@%rbp 8@%r12 -4@%eax\n" +" stapsdt 0x00000046 NT_STAPSDT (SystemTap probe " +"descriptors)\n" +" Provider: python\n" +" Name: function__return\n" +" Location: 0x000000000053dba8, Base: 0x0000000000630ce2, Semaphore: " +"0x00000000008d6bea\n" +" Arguments: 8@%rbp 8@%r12 -4@%eax" +msgstr "" +"$ readelf -n ./python\n" +"\n" +"Displaying notes found at file offset 0x00000254 with length 0x00000020:\n" +" Owner Data size Description\n" +" GNU 0x00000010 NT_GNU_ABI_TAG (ABI version " +"tag)\n" +" OS: Linux, ABI: 2.6.32\n" +"\n" +"Displaying notes found at file offset 0x00000274 with length 0x00000024:\n" +" Owner Data size Description\n" +" GNU 0x00000014 NT_GNU_BUILD_ID (unique build " +"ID bitstring)\n" +" Build ID: df924a2b08a7e89f6e11251d4602022977af2670\n" +"\n" +"Displaying notes found at file offset 0x002d6c30 with length 0x00000144:\n" +" Owner Data size Description\n" +" stapsdt 0x00000031 NT_STAPSDT (SystemTap probe " +"descriptors)\n" +" Provider: python\n" +" Name: gc__start\n" +" Location: 0x00000000004371c3, Base: 0x0000000000630ce2, Semaphore: " +"0x00000000008d6bf6\n" +" Arguments: -4@%ebx\n" +" stapsdt 0x00000030 NT_STAPSDT (SystemTap probe " +"descriptors)\n" +" Provider: python\n" +" Name: gc__done\n" +" Location: 0x00000000004374e1, Base: 0x0000000000630ce2, Semaphore: " +"0x00000000008d6bf8\n" +" Arguments: -8@%rax\n" +" stapsdt 0x00000045 NT_STAPSDT (SystemTap probe " +"descriptors)\n" +" Provider: python\n" +" Name: function__entry\n" +" Location: 0x000000000053db6c, Base: 0x0000000000630ce2, Semaphore: " +"0x00000000008d6be8\n" +" Arguments: 8@%rbp 8@%r12 -4@%eax\n" +" stapsdt 0x00000046 NT_STAPSDT (SystemTap probe " +"descriptors)\n" +" Provider: python\n" +" Name: function__return\n" +" Location: 0x000000000053dba8, Base: 0x0000000000630ce2, Semaphore: " +"0x00000000008d6bea\n" +" Arguments: 8@%rbp 8@%r12 -4@%eax" + +#: ../../howto/instrumentation.rst:125 +msgid "" +"The above metadata contains information for SystemTap describing how it can " +"patch strategically placed machine code instructions to enable the tracing " +"hooks used by a SystemTap script." +msgstr "" +"上述元資料包含 SystemTap 的資訊，描述了它如何修補策略性放置的機器碼指令以啟" +"用 SystemTap 腳本使用的追蹤 hook。" + +#: ../../howto/instrumentation.rst:131 +msgid "Static DTrace probes" +msgstr "靜態 DTrace 探針" + +#: ../../howto/instrumentation.rst:133 +msgid "" +"The following example DTrace script can be used to show the call/return " +"hierarchy of a Python script, only tracing within the invocation of a " +"function called \"start\". In other words, import-time function invocations " +"are not going to be listed:" +msgstr "" +"以下範例示範 DTrace 腳本可用於顯示 Python 腳本的呼叫/回傳階層結構，僅在名為 " +"\"start\" 的函式的呼叫內進行追蹤。換句話說，引入時的函式呼叫不會被列出：" + +#: ../../howto/instrumentation.rst:138 +msgid "" +"self int indent;\n" +"\n" +"python$target:::function-entry\n" +"/copyinstr(arg1) == \"start\"/\n" +"{\n" +" self->trace = 1;\n" +"}\n" +"\n" +"python$target:::function-entry\n" +"/self->trace/\n" +"{\n" +" printf(\"%d\\t%*s:\", timestamp, 15, probename);\n" +" printf(\"%*s\", self->indent, \"\");\n" +" printf(\"%s:%s:%d\\n\", basename(copyinstr(arg0)), copyinstr(arg1), " +"arg2);\n" +" self->indent++;\n" +"}\n" +"\n" +"python$target:::function-return\n" +"/self->trace/\n" +"{\n" +" self->indent--;\n" +" printf(\"%d\\t%*s:\", timestamp, 15, probename);\n" +" printf(\"%*s\", self->indent, \"\");\n" +" printf(\"%s:%s:%d\\n\", basename(copyinstr(arg0)), copyinstr(arg1), " +"arg2);\n" +"}\n" +"\n" +"python$target:::function-return\n" +"/copyinstr(arg1) == \"start\"/\n" +"{\n" +" self->trace = 0;\n" +"}" +msgstr "" +"self int indent;\n" +"\n" +"python$target:::function-entry\n" +"/copyinstr(arg1) == \"start\"/\n" +"{\n" +" self->trace = 1;\n" +"}\n" +"\n" +"python$target:::function-entry\n" +"/self->trace/\n" +"{\n" +" printf(\"%d\\t%*s:\", timestamp, 15, probename);\n" +" printf(\"%*s\", self->indent, \"\");\n" +" printf(\"%s:%s:%d\\n\", basename(copyinstr(arg0)), copyinstr(arg1), " +"arg2);\n" +" self->indent++;\n" +"}\n" +"\n" +"python$target:::function-return\n" +"/self->trace/\n" +"{\n" +" self->indent--;\n" +" printf(\"%d\\t%*s:\", timestamp, 15, probename);\n" +" printf(\"%*s\", self->indent, \"\");\n" +" printf(\"%s:%s:%d\\n\", basename(copyinstr(arg0)), copyinstr(arg1), " +"arg2);\n" +"}\n" +"\n" +"python$target:::function-return\n" +"/copyinstr(arg1) == \"start\"/\n" +"{\n" +" self->trace = 0;\n" +"}" + +#: ../../howto/instrumentation.rst:172 ../../howto/instrumentation.rst:230 +msgid "It can be invoked like this::" +msgstr "可以這樣呼叫： ::" + +#: ../../howto/instrumentation.rst:174 +msgid "$ sudo dtrace -q -s call_stack.d -c \"python3.6 script.py\"" +msgstr "$ sudo dtrace -q -s call_stack.d -c \"python3.6 script.py\"" + +#: ../../howto/instrumentation.rst:176 ../../howto/instrumentation.rst:236 +msgid "The output looks like this:" +msgstr "輸出如下所示：" + +#: ../../howto/instrumentation.rst:178 +msgid "" +"156641360502280 function-entry:call_stack.py:start:23\n" +"156641360518804 function-entry: call_stack.py:function_1:1\n" +"156641360532797 function-entry: call_stack.py:function_3:9\n" +"156641360546807 function-return: call_stack.py:function_3:10\n" +"156641360563367 function-return: call_stack.py:function_1:2\n" +"156641360578365 function-entry: call_stack.py:function_2:5\n" +"156641360591757 function-entry: call_stack.py:function_1:1\n" +"156641360605556 function-entry: call_stack.py:function_3:9\n" +"156641360617482 function-return: call_stack.py:function_3:10\n" +"156641360629814 function-return: call_stack.py:function_1:2\n" +"156641360642285 function-return: call_stack.py:function_2:6\n" +"156641360656770 function-entry: call_stack.py:function_3:9\n" +"156641360669707 function-return: call_stack.py:function_3:10\n" +"156641360687853 function-entry: call_stack.py:function_4:13\n" +"156641360700719 function-return: call_stack.py:function_4:14\n" +"156641360719640 function-entry: call_stack.py:function_5:18\n" +"156641360732567 function-return: call_stack.py:function_5:21\n" +"156641360747370 function-return:call_stack.py:start:28" +msgstr "" +"156641360502280 function-entry:call_stack.py:start:23\n" +"156641360518804 function-entry: call_stack.py:function_1:1\n" +"156641360532797 function-entry: call_stack.py:function_3:9\n" +"156641360546807 function-return: call_stack.py:function_3:10\n" +"156641360563367 function-return: call_stack.py:function_1:2\n" +"156641360578365 function-entry: call_stack.py:function_2:5\n" +"156641360591757 function-entry: call_stack.py:function_1:1\n" +"156641360605556 function-entry: call_stack.py:function_3:9\n" +"156641360617482 function-return: call_stack.py:function_3:10\n" +"156641360629814 function-return: call_stack.py:function_1:2\n" +"156641360642285 function-return: call_stack.py:function_2:6\n" +"156641360656770 function-entry: call_stack.py:function_3:9\n" +"156641360669707 function-return: call_stack.py:function_3:10\n" +"156641360687853 function-entry: call_stack.py:function_4:13\n" +"156641360700719 function-return: call_stack.py:function_4:14\n" +"156641360719640 function-entry: call_stack.py:function_5:18\n" +"156641360732567 function-return: call_stack.py:function_5:21\n" +"156641360747370 function-return:call_stack.py:start:28" + +#: ../../howto/instrumentation.rst:201 +msgid "Static SystemTap markers" +msgstr "靜態 SystemTap 標記" + +#: ../../howto/instrumentation.rst:203 +msgid "" +"The low-level way to use the SystemTap integration is to use the static " +"markers directly. This requires you to explicitly state the binary file " +"containing them." +msgstr "" +"使用 SystemTap 整合的低階方法是直接使用靜態標記。這會需要你明確聲明包含它們的" +"二進位檔案。" + +#: ../../howto/instrumentation.rst:207 +msgid "" +"For example, this SystemTap script can be used to show the call/return " +"hierarchy of a Python script:" +msgstr "例如，此 SystemTap 腳本可用於顯示 Python 腳本的呼叫/回傳階層結構：" + +#: ../../howto/instrumentation.rst:210 +msgid "" +"probe process(\"python\").mark(\"function__entry\") {\n" +" filename = user_string($arg1);\n" +" funcname = user_string($arg2);\n" +" lineno = $arg3;\n" +"\n" +" printf(\"%s => %s in %s:%d\\\\n\",\n" +" thread_indent(1), funcname, filename, lineno);\n" +"}\n" +"\n" +"probe process(\"python\").mark(\"function__return\") {\n" +" filename = user_string($arg1);\n" +" funcname = user_string($arg2);\n" +" lineno = $arg3;\n" +"\n" +" printf(\"%s <= %s in %s:%d\\\\n\",\n" +" thread_indent(-1), funcname, filename, lineno);\n" +"}" +msgstr "" +"probe process(\"python\").mark(\"function__entry\") {\n" +" filename = user_string($arg1);\n" +" funcname = user_string($arg2);\n" +" lineno = $arg3;\n" +"\n" +" printf(\"%s => %s in %s:%d\\\\n\",\n" +" thread_indent(1), funcname, filename, lineno);\n" +"}\n" +"\n" +"probe process(\"python\").mark(\"function__return\") {\n" +" filename = user_string($arg1);\n" +" funcname = user_string($arg2);\n" +" lineno = $arg3;\n" +"\n" +" printf(\"%s <= %s in %s:%d\\\\n\",\n" +" thread_indent(-1), funcname, filename, lineno);\n" +"}" + +#: ../../howto/instrumentation.rst:232 +msgid "" +"$ stap \\\n" +" show-call-hierarchy.stp \\\n" +" -c \"./python test.py\"" +msgstr "" +"$ stap \\\n" +" show-call-hierarchy.stp \\\n" +" -c \"./python test.py\"" + +#: ../../howto/instrumentation.rst:238 +msgid "" +"11408 python(8274): => __contains__ in Lib/_abcoll.py:362\n" +"11414 python(8274): => __getitem__ in Lib/os.py:425\n" +"11418 python(8274): => encode in Lib/os.py:490\n" +"11424 python(8274): <= encode in Lib/os.py:493\n" +"11428 python(8274): <= __getitem__ in Lib/os.py:426\n" +"11433 python(8274): <= __contains__ in Lib/_abcoll.py:366" +msgstr "" +"11408 python(8274): => __contains__ in Lib/_abcoll.py:362\n" +"11414 python(8274): => __getitem__ in Lib/os.py:425\n" +"11418 python(8274): => encode in Lib/os.py:490\n" +"11424 python(8274): <= encode in Lib/os.py:493\n" +"11428 python(8274): <= __getitem__ in Lib/os.py:426\n" +"11433 python(8274): <= __contains__ in Lib/_abcoll.py:366" + +#: ../../howto/instrumentation.rst:247 +msgid "where the columns are:" +msgstr "其中的行 (column) 是：" + +#: ../../howto/instrumentation.rst:249 +msgid "time in microseconds since start of script" +msgstr "自腳本開始以來的時間（以微秒為單位）" + +#: ../../howto/instrumentation.rst:250 +msgid "name of executable" +msgstr "可執行檔案的名稱" + +#: ../../howto/instrumentation.rst:251 +msgid "PID of process" +msgstr "行程的 PID" + +#: ../../howto/instrumentation.rst:253 +msgid "" +"and the remainder indicates the call/return hierarchy as the script executes." +msgstr "其餘部分表示腳本執行時的呼叫/回傳階層結構。" + +#: ../../howto/instrumentation.rst:255 +msgid "" +"For a :option:`--enable-shared` build of CPython, the markers are contained " +"within the libpython shared library, and the probe's dotted path needs to " +"reflect this. For example, this line from the above example:" +msgstr "" +"對於以 :option:`--enable-shared` 建置的 CPython，標記被包含在 libpython 共享" +"函式庫中，並且探針的帶點路徑 (dotted path) 需要反映這一點。例如，上面範例中的" +"這一列：" + +#: ../../howto/instrumentation.rst:259 +msgid "probe process(\"python\").mark(\"function__entry\") {" +msgstr "probe process(\"python\").mark(\"function__entry\") {" + +#: ../../howto/instrumentation.rst:263 +msgid "should instead read:" +msgstr "應該改為讀取：" + +#: ../../howto/instrumentation.rst:265 +msgid "" +"probe process(\"python\").library(\"libpython3.6dm.so.1.0\")." +"mark(\"function__entry\") {" +msgstr "" +"probe process(\"python\").library(\"libpython3.6dm.so.1.0\")." +"mark(\"function__entry\") {" + +#: ../../howto/instrumentation.rst:269 +msgid "(assuming a :ref:`debug build ` of CPython 3.6)" +msgstr "（假設 CPython 3.6 的\\ :ref:`除錯建置版本 `）" + +#: ../../howto/instrumentation.rst:275 +msgid "Available static markers" +msgstr "可用的靜態標記" + +#: ../../howto/instrumentation.rst:279 +msgid "" +"This marker indicates that execution of a Python function has begun. It is " +"only triggered for pure-Python (bytecode) functions." +msgstr "" +"該標記表示 Python 函式的執行已經開始。它僅針對純 Python（位元組碼）函式觸發。" + +#: ../../howto/instrumentation.rst:282 +msgid "" +"The filename, function name, and line number are provided back to the " +"tracing script as positional arguments, which must be accessed using " +"``$arg1``, ``$arg2``, ``$arg3``:" +msgstr "" +"檔案名稱、函式名稱和列號作為位置引數提供給追蹤腳本，必須使用 ``$arg1``、" +"``$arg2``、``$arg3`` 來存取：" + +#: ../../howto/instrumentation.rst:286 +msgid "" +"``$arg1`` : ``(const char *)`` filename, accessible using " +"``user_string($arg1)``" +msgstr "" +"``$arg1`` : ``(const char *)`` 檔案名稱，可使用 ``user_string($arg1)`` 存取" + +#: ../../howto/instrumentation.rst:288 +msgid "" +"``$arg2`` : ``(const char *)`` function name, accessible using " +"``user_string($arg2)``" +msgstr "" +"``$arg2`` ：``(const char *)`` 函式名稱，可使用 ``user_string($arg2)`` 存取" + +#: ../../howto/instrumentation.rst:291 +msgid "``$arg3`` : ``int`` line number" +msgstr "``$arg3`` : ``int`` 列號" + +#: ../../howto/instrumentation.rst:295 +msgid "" +"This marker is the converse of :c:func:`!function__entry`, and indicates " +"that execution of a Python function has ended (either via ``return``, or via " +"an exception). It is only triggered for pure-Python (bytecode) functions." +msgstr "" +"該標記與 :c:func:`!function__entry` 相反，表示 Python 函式的執行已結束（透過 " +"``return`` 或透過例外）。它僅針對純 Python（位元組碼）函式觸發。" + +#: ../../howto/instrumentation.rst:299 +msgid "The arguments are the same as for :c:func:`!function__entry`" +msgstr "引數與 :c:func:`!function__entry` 相同" + +#: ../../howto/instrumentation.rst:303 +msgid "" +"This marker indicates a Python line is about to be executed. It is the " +"equivalent of line-by-line tracing with a Python profiler. It is not " +"triggered within C functions." +msgstr "" +"該標記表示一列 Python 即將被執行。它相當於使用 Python 分析器來逐行追蹤。它不" +"在 C 函式內觸發。" + +#: ../../howto/instrumentation.rst:307 +msgid "The arguments are the same as for :c:func:`!function__entry`." +msgstr "引數與 :c:func:`!function__entry` 相同。" + +#: ../../howto/instrumentation.rst:311 +msgid "" +"Fires when the Python interpreter starts a garbage collection cycle. " +"``arg0`` is the generation to scan, like :func:`gc.collect`." +msgstr "" +"當 Python 直譯器開始垃圾回收 (garbage collection) 週期時觸發。``arg0`` 是要掃" +"描的一代 (generation)，如 :func:`gc.collect`。" + +#: ../../howto/instrumentation.rst:316 +msgid "" +"Fires when the Python interpreter finishes a garbage collection cycle. " +"``arg0`` is the number of collected objects." +msgstr "當 Python 直譯器完成垃圾回收週期時觸發。``arg0`` 是收集到的物件數量。" + +#: ../../howto/instrumentation.rst:321 +msgid "" +"Fires before :mod:`importlib` attempts to find and load the module. ``arg0`` " +"is the module name." +msgstr "在 :mod:`importlib` 嘗試查找並載入模組之前觸發。``arg0`` 是模組名稱。" + +#: ../../howto/instrumentation.rst:328 +msgid "" +"Fires after :mod:`importlib`'s find_and_load function is called. ``arg0`` is " +"the module name, ``arg1`` indicates if module was successfully loaded." +msgstr "" +"在呼叫 :mod:`importlib` 的 find_and_load 函式後觸發。 ``arg0`` 是模組名稱，" +"``arg1`` 代表模組是否已成功載入。" + +#: ../../howto/instrumentation.rst:337 +msgid "" +"Fires when :func:`sys.audit` or :c:func:`PySys_Audit` is called. ``arg0`` is " +"the event name as C string, ``arg1`` is a :c:type:`PyObject` pointer to a " +"tuple object." +msgstr "" +"當呼叫 :func:`sys.audit` 或 :c:func:`PySys_Audit` 時觸發。``arg0`` 是 C 字串" +"形式的事件名稱，``arg1`` 是指向元組 (tuple) 物件的 :c:type:`PyObject` 指標。" + +#: ../../howto/instrumentation.rst:345 +msgid "SystemTap Tapsets" +msgstr "SystemTap Tapsets" + +#: ../../howto/instrumentation.rst:347 +msgid "" +"The higher-level way to use the SystemTap integration is to use a " +"\"tapset\": SystemTap's equivalent of a library, which hides some of the " +"lower-level details of the static markers." +msgstr "" +"使用 SystemTap 整合的高階方法是使用 \"tapset\"：SystemTap 相當於一個函式庫，" +"它隱藏了靜態標記的一些低階詳細資訊。" + +#: ../../howto/instrumentation.rst:351 +msgid "Here is a tapset file, based on a non-shared build of CPython:" +msgstr "這是一個 tapset 檔案，是基於 CPython 的非共享建置版本：" + +#: ../../howto/instrumentation.rst:353 +msgid "" +"/*\n" +" Provide a higher-level wrapping around the function__entry and\n" +" function__return markers:\n" +" \\*/\n" +"probe python.function.entry = process(\"python\").mark(\"function__entry\")\n" +"{\n" +" filename = user_string($arg1);\n" +" funcname = user_string($arg2);\n" +" lineno = $arg3;\n" +" frameptr = $arg4\n" +"}\n" +"probe python.function.return = process(\"python\")." +"mark(\"function__return\")\n" +"{\n" +" filename = user_string($arg1);\n" +" funcname = user_string($arg2);\n" +" lineno = $arg3;\n" +" frameptr = $arg4\n" +"}" +msgstr "" +"/*\n" +" 提供一個更高階、在 function__entry 和 function__return 標記上的包裝：\n" +" \\*/\n" +"probe python.function.entry = process(\"python\").mark(\"function__entry\")\n" +"{\n" +" filename = user_string($arg1);\n" +" funcname = user_string($arg2);\n" +" lineno = $arg3;\n" +" frameptr = $arg4\n" +"}\n" +"probe python.function.return = process(\"python\")." +"mark(\"function__return\")\n" +"{\n" +" filename = user_string($arg1);\n" +" funcname = user_string($arg2);\n" +" lineno = $arg3;\n" +" frameptr = $arg4\n" +"}" + +#: ../../howto/instrumentation.rst:374 +msgid "" +"If this file is installed in SystemTap's tapset directory (e.g. ``/usr/share/" +"systemtap/tapset``), then these additional probepoints become available:" +msgstr "" +"如果此檔案是安裝在 SystemTap 的 tapset 目錄中（例如 ``/usr/share/systemtap/" +"tapset``），則這些額外的探測點將可被使用：" + +#: ../../howto/instrumentation.rst:380 +msgid "" +"This probe point indicates that execution of a Python function has begun. It " +"is only triggered for pure-Python (bytecode) functions." +msgstr "" +"該探測點表示 Python 函式的執行已經開始。它僅針對純 Python（位元組碼）函式觸" +"發。" + +#: ../../howto/instrumentation.rst:385 +msgid "" +"This probe point is the converse of ``python.function.return``, and " +"indicates that execution of a Python function has ended (either via " +"``return``, or via an exception). It is only triggered for pure-Python " +"(bytecode) functions." +msgstr "" +"這個探測點與 ``python.function.return`` 相反，表示 Python 函式的執行已經結束" +"（透過 ``return`` 或者透過例外）。它僅針對純 Python（位元組碼）函式觸發。" + +#: ../../howto/instrumentation.rst:392 +msgid "Examples" +msgstr "範例" + +#: ../../howto/instrumentation.rst:393 +msgid "" +"This SystemTap script uses the tapset above to more cleanly implement the " +"example given above of tracing the Python function-call hierarchy, without " +"needing to directly name the static markers:" +msgstr "" +"此 SystemTap 腳本使用上面的 tapset 來更清晰地實作上面給出的追蹤 Python 函式呼" +"叫階層結構的範例，而無需直接命名靜態標記：" + +#: ../../howto/instrumentation.rst:397 +msgid "" +"probe python.function.entry\n" +"{\n" +" printf(\"%s => %s in %s:%d\\n\",\n" +" thread_indent(1), funcname, filename, lineno);\n" +"}\n" +"\n" +"probe python.function.return\n" +"{\n" +" printf(\"%s <= %s in %s:%d\\n\",\n" +" thread_indent(-1), funcname, filename, lineno);\n" +"}" +msgstr "" +"probe python.function.entry\n" +"{\n" +" printf(\"%s => %s in %s:%d\\n\",\n" +" thread_indent(1), funcname, filename, lineno);\n" +"}\n" +"\n" +"probe python.function.return\n" +"{\n" +" printf(\"%s <= %s in %s:%d\\n\",\n" +" thread_indent(-1), funcname, filename, lineno);\n" +"}" + +#: ../../howto/instrumentation.rst:412 +msgid "" +"The following script uses the tapset above to provide a top-like view of all " +"running CPython code, showing the top 20 most frequently entered bytecode " +"frames, each second, across the whole system:" +msgstr "" +"以下腳本使用上面的 tapset 來提供所有正在運行之 CPython 程式碼的近乎最高層視" +"角，顯示整個系統中每秒最常被進入的 20 個位元組碼幀 (bytecode frame)：" + +#: ../../howto/instrumentation.rst:416 +msgid "" +"global fn_calls;\n" +"\n" +"probe python.function.entry\n" +"{\n" +" fn_calls[pid(), filename, funcname, lineno] += 1;\n" +"}\n" +"\n" +"probe timer.ms(1000) {\n" +" printf(\"\\033[2J\\033[1;1H\") /* clear screen \\*/\n" +" printf(\"%6s %80s %6s %30s %6s\\n\",\n" +" \"PID\", \"FILENAME\", \"LINE\", \"FUNCTION\", \"CALLS\")\n" +" foreach ([pid, filename, funcname, lineno] in fn_calls- limit 20) {\n" +" printf(\"%6d %80s %6d %30s %6d\\n\",\n" +" pid, filename, lineno, funcname,\n" +" fn_calls[pid, filename, funcname, lineno]);\n" +" }\n" +" delete fn_calls;\n" +"}" +msgstr "" +"global fn_calls;\n" +"\n" +"probe python.function.entry\n" +"{\n" +" fn_calls[pid(), filename, funcname, lineno] += 1;\n" +"}\n" +"\n" +"probe timer.ms(1000) {\n" +" printf(\"\\033[2J\\033[1;1H\") /* clear screen \\*/\n" +" printf(\"%6s %80s %6s %30s %6s\\n\",\n" +" \"PID\", \"FILENAME\", \"LINE\", \"FUNCTION\", \"CALLS\")\n" +" foreach ([pid, filename, funcname, lineno] in fn_calls- limit 20) {\n" +" printf(\"%6d %80s %6d %30s %6d\\n\",\n" +" pid, filename, lineno, funcname,\n" +" fn_calls[pid, filename, funcname, lineno]);\n" +" }\n" +" delete fn_calls;\n" +"}" diff --git a/howto/ipaddress.po b/howto/ipaddress.po index 060f61e22a..d702d27348 100644 --- a/howto/ipaddress.po +++ b/howto/ipaddress.po @@ -1,650 +1,650 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Leon H., 2017 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-12-01 00:17+0000\n" -"PO-Revision-Date: 2025-12-26 10:42-0500\n" -"Last-Translator: Chih-Chao Chang \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" -"X-Generator: Poedit 3.8\n" - -#: ../../howto/ipaddress.rst:9 -msgid "An introduction to the ipaddress module" -msgstr "ipaddress 模組介紹" - -#: ../../howto/ipaddress.rst:0 -msgid "author" -msgstr "作者" - -#: ../../howto/ipaddress.rst:11 -msgid "Peter Moody" -msgstr "Peter Moody" - -#: ../../howto/ipaddress.rst:12 -msgid "Nick Coghlan" -msgstr "Nick Coghlan" - -#: ../../howto/ipaddress.rst:14 -msgid "Overview" -msgstr "總攬" - -#: ../../howto/ipaddress.rst:16 -msgid "" -"This document aims to provide a gentle introduction to the :mod:`ipaddress` " -"module. It is aimed primarily at users that aren't already familiar with IP " -"networking terminology, but may also be useful to network engineers wanting " -"an overview of how :mod:`ipaddress` represents IP network addressing " -"concepts." -msgstr "" -"這份文件旨在為 :mod:`ipaddress` 模組提供一個初步介紹。文件主要針對那些不熟悉 " -"IP 網路術語的使用者，但對想要了解 :mod:`ipaddress` 模組如何表示 IP 網址概念的" -"網路工程師也可能有用。" - -#: ../../howto/ipaddress.rst:24 -msgid "Creating Address/Network/Interface objects" -msgstr "建立 Address/Network/Interface 物件" - -#: ../../howto/ipaddress.rst:26 -msgid "" -"Since :mod:`ipaddress` is a module for inspecting and manipulating IP " -"addresses, the first thing you'll want to do is create some objects. You " -"can use :mod:`ipaddress` to create objects from strings and integers." -msgstr "" -"由於 :mod:`ipaddress` 是一個用於檢查和操作 IP 位址的模組，你首先會想要做的事" -"情是建立一些物件。你可以使用 :mod:`ipaddress` 從字串和整數建立物件。" - -#: ../../howto/ipaddress.rst:32 -msgid "A Note on IP Versions" -msgstr "關於 IP 版本的說明" - -#: ../../howto/ipaddress.rst:34 -msgid "" -"For readers that aren't particularly familiar with IP addressing, it's " -"important to know that the Internet Protocol (IP) is currently in the " -"process of moving from version 4 of the protocol to version 6. This " -"transition is occurring largely because version 4 of the protocol doesn't " -"provide enough addresses to handle the needs of the whole world, especially " -"given the increasing number of devices with direct connections to the " -"internet." -msgstr "" -"對於不太熟悉 IP 位址的讀者來說，重要的是要知道網際網路協定 (Internet " -"Protocol, IP) 目前正在從協定的第 4 版過渡到第 6 版。這個轉換主要是因為協定的" -"第 4 版無法提供足夠的位址來處理全世界的需求，特別是考慮到直接連接到網際網路的" -"裝置數量不斷增加。" - -#: ../../howto/ipaddress.rst:41 -msgid "" -"Explaining the details of the differences between the two versions of the " -"protocol is beyond the scope of this introduction, but readers need to at " -"least be aware that these two versions exist, and it will sometimes be " -"necessary to force the use of one version or the other." -msgstr "" -"解釋這兩個版本協定之間差異的細節超出了本文介紹的範圍，但讀者至少需要知道這兩" -"個版本的存在，而且有時候會需要強制使用其中一個版本。" - -#: ../../howto/ipaddress.rst:48 -msgid "IP Host Addresses" -msgstr "IP 主機位址" - -#: ../../howto/ipaddress.rst:50 -msgid "" -"Addresses, often referred to as \"host addresses\" are the most basic unit " -"when working with IP addressing. The simplest way to create addresses is to " -"use the :func:`ipaddress.ip_address` factory function, which automatically " -"determines whether to create an IPv4 or IPv6 address based on the passed in " -"value:" -msgstr "" -"位址，通常被稱為「主機位址」，是處理 IP 位址時最基本的單位。建立位址最簡單的" -"方法是使用 :func:`ipaddress.ip_address` 工廠函式，它會根據傳入的值自動判斷要" -"建立 IPv4 還是 IPv6 位址：" - -#: ../../howto/ipaddress.rst:61 -msgid "" -"Addresses can also be created directly from integers. Values that will fit " -"within 32 bits are assumed to be IPv4 addresses::" -msgstr "" -"位址也可以直接從整數建立。符合 32 位元以內的值會被假定為 IPv4 位址： ::" - -#: ../../howto/ipaddress.rst:64 -msgid "" -">>> ipaddress.ip_address(3221225985)\n" -"IPv4Address('192.0.2.1')\n" -">>> ipaddress.ip_address(42540766411282592856903984951653826561)\n" -"IPv6Address('2001:db8::1')" -msgstr "" -">>> ipaddress.ip_address(3221225985)\n" -"IPv4Address('192.0.2.1')\n" -">>> ipaddress.ip_address(42540766411282592856903984951653826561)\n" -"IPv6Address('2001:db8::1')" - -#: ../../howto/ipaddress.rst:69 -msgid "" -"To force the use of IPv4 or IPv6 addresses, the relevant classes can be " -"invoked directly. This is particularly useful to force creation of IPv6 " -"addresses for small integers::" -msgstr "" -"要強制使用 IPv4 或 IPv6 位址，可以直接呼叫相關的類別。這對於強制為小整數建立 " -"IPv6 位址特別有用： ::" - -#: ../../howto/ipaddress.rst:73 -msgid "" -">>> ipaddress.ip_address(1)\n" -"IPv4Address('0.0.0.1')\n" -">>> ipaddress.IPv4Address(1)\n" -"IPv4Address('0.0.0.1')\n" -">>> ipaddress.IPv6Address(1)\n" -"IPv6Address('::1')" -msgstr "" -">>> ipaddress.ip_address(1)\n" -"IPv4Address('0.0.0.1')\n" -">>> ipaddress.IPv4Address(1)\n" -"IPv4Address('0.0.0.1')\n" -">>> ipaddress.IPv6Address(1)\n" -"IPv6Address('::1')" - -#: ../../howto/ipaddress.rst:82 -msgid "Defining Networks" -msgstr "定義網路" - -#: ../../howto/ipaddress.rst:84 -msgid "" -"Host addresses are usually grouped together into IP networks, so :mod:" -"`ipaddress` provides a way to create, inspect and manipulate network " -"definitions. IP network objects are constructed from strings that define the " -"range of host addresses that are part of that network. The simplest form for " -"that information is a \"network address/network prefix\" pair, where the " -"prefix defines the number of leading bits that are compared to determine " -"whether or not an address is part of the network and the network address " -"defines the expected value of those bits." -msgstr "" -"主機位址通常會被分組到 IP 網路中，因此 :mod:`ipaddress` 提供了一種建立、檢查" -"和操作網路定義的方法。IP 網路物件是從定義該網路所包含之主機位址範圍的字串建構" -"而成。這些資訊最簡單的形式是「網路位址/網路前綴」配對，其中前綴定義了用於比較" -"的前導位元數量，以判斷位址是否屬於該網路的一部分，而網路位址則定義了這些位元" -"的預期值。" - -#: ../../howto/ipaddress.rst:93 -msgid "" -"As for addresses, a factory function is provided that determines the correct " -"IP version automatically::" -msgstr "至於位址，提供了一個工廠函式可以自動判斷正確的 IP 版本： ::" - -#: ../../howto/ipaddress.rst:96 -msgid "" -">>> ipaddress.ip_network('192.0.2.0/24')\n" -"IPv4Network('192.0.2.0/24')\n" -">>> ipaddress.ip_network('2001:db8::0/96')\n" -"IPv6Network('2001:db8::/96')" -msgstr "" -">>> ipaddress.ip_network('192.0.2.0/24')\n" -"IPv4Network('192.0.2.0/24')\n" -">>> ipaddress.ip_network('2001:db8::0/96')\n" -"IPv6Network('2001:db8::/96')" - -#: ../../howto/ipaddress.rst:101 -msgid "" -"Network objects cannot have any host bits set. The practical effect of this " -"is that ``192.0.2.1/24`` does not describe a network. Such definitions are " -"referred to as interface objects since the ip-on-a-network notation is " -"commonly used to describe network interfaces of a computer on a given " -"network and are described further in the next section." -msgstr "" -"網路物件不能設定任何主機位元。這樣做的實際效果是 ``192.0.2.1/24`` 並不描述一個網" -"路。這類定義被稱為介面物件，因為 ip-on-a-network 標記法通常用於描述電腦在給定" -"網路上的網路介面，並將在下一節中進一步說明。" - -#: ../../howto/ipaddress.rst:107 -msgid "" -"By default, attempting to create a network object with host bits set will " -"result in :exc:`ValueError` being raised. To request that the additional " -"bits instead be coerced to zero, the flag ``strict=False`` can be passed to " -"the constructor::" -msgstr "" -"預設情況下，嘗試建立帶有主機位元設定的網路物件會導致引發 :exc:`ValueError`。" -"若要求將額外的位元強制轉換為零，可以在建構子中傳遞旗標 ``strict=False``： ::" - -#: ../../howto/ipaddress.rst:112 -msgid "" -">>> ipaddress.ip_network('192.0.2.1/24')\n" -"Traceback (most recent call last):\n" -" ...\n" -"ValueError: 192.0.2.1/24 has host bits set\n" -">>> ipaddress.ip_network('192.0.2.1/24', strict=False)\n" -"IPv4Network('192.0.2.0/24')" -msgstr "" -">>> ipaddress.ip_network('192.0.2.1/24')\n" -"Traceback (most recent call last):\n" -" ...\n" -"ValueError: 192.0.2.1/24 has host bits set\n" -">>> ipaddress.ip_network('192.0.2.1/24', strict=False)\n" -"IPv4Network('192.0.2.0/24')" - -#: ../../howto/ipaddress.rst:119 -msgid "" -"While the string form offers significantly more flexibility, networks can " -"also be defined with integers, just like host addresses. In this case, the " -"network is considered to contain only the single address identified by the " -"integer, so the network prefix includes the entire network address::" -msgstr "" -"雖然字串形式提供了更大的靈活性，但網路也可以像主機位址一樣使用整數來定義。在" -"這種情況下，網路被認為僅包含由該整數識別的單一位址，因此網路前綴包含了整個網" -"路位址： ::" - -#: ../../howto/ipaddress.rst:124 -msgid "" -">>> ipaddress.ip_network(3221225984)\n" -"IPv4Network('192.0.2.0/32')\n" -">>> ipaddress.ip_network(42540766411282592856903984951653826560)\n" -"IPv6Network('2001:db8::/128')" -msgstr "" -">>> ipaddress.ip_network(3221225984)\n" -"IPv4Network('192.0.2.0/32')\n" -">>> ipaddress.ip_network(42540766411282592856903984951653826560)\n" -"IPv6Network('2001:db8::/128')" - -#: ../../howto/ipaddress.rst:129 -msgid "" -"As with addresses, creation of a particular kind of network can be forced by " -"calling the class constructor directly instead of using the factory function." -msgstr "" -"與位址一樣，可以透過直接呼叫類別建構子而非使用工廠函式，來強制建立特定類型的" -"網路。" - -#: ../../howto/ipaddress.rst:135 -msgid "Host Interfaces" -msgstr "主機介面" - -#: ../../howto/ipaddress.rst:137 -msgid "" -"As mentioned just above, if you need to describe an address on a particular " -"network, neither the address nor the network classes are sufficient. " -"Notation like ``192.0.2.1/24`` is commonly used by network engineers and the " -"people who write tools for firewalls and routers as shorthand for \"the host " -"``192.0.2.1`` on the network ``192.0.2.0/24``\", Accordingly, :mod:" -"`ipaddress` provides a set of hybrid classes that associate an address with " -"a particular network. The interface for creation is identical to that for " -"defining network objects, except that the address portion isn't constrained " -"to being a network address." -msgstr "" -"如上所述，如果你需要描述特定網路上的位址，位址類別和網路類別都不足以滿足需" -"求。像 ``192.0.2.1/24`` 這樣的標記法通常被網路工程師以及編寫防火牆和路由器工" -"具的人用作「網路 ``192.0.2.0/24`` 上的主機 ``192.0.2.1``」的簡寫。因" -"此，:mod:`ipaddress` 提供了一組混合類別，將位址與特定網路關聯起來。建立介面的" -"方式與定義網路物件相同，只是位址部分不受限於必須是網路位址。" - -#: ../../howto/ipaddress.rst:152 -msgid "" -"Integer inputs are accepted (as with networks), and use of a particular IP " -"version can be forced by calling the relevant constructor directly." -msgstr "" -"可以接受整數輸入（如同網路一樣），並且可以透過直接呼叫相關的建構子來強制使用" -"特定的 IP 版本。" - -#: ../../howto/ipaddress.rst:157 -msgid "Inspecting Address/Network/Interface Objects" -msgstr "檢視 Address/Network/Interface 物件" - -#: ../../howto/ipaddress.rst:159 -msgid "" -"You've gone to the trouble of creating an IPv(4|6)(Address|Network|" -"Interface) object, so you probably want to get information about it. :mod:" -"`ipaddress` tries to make doing this easy and intuitive." -msgstr "" -"你費心建立了 IPv(4|6)(Address|Network|Interface) 物件，所以你可能想要取得關於" -"它的資訊。:mod:`ipaddress` 試圖讓這件事變得簡單且直觀。" - -#: ../../howto/ipaddress.rst:163 -msgid "Extracting the IP version::" -msgstr "提取 IP 版本： ::" - -#: ../../howto/ipaddress.rst:165 -msgid "" -">>> addr4 = ipaddress.ip_address('192.0.2.1')\n" -">>> addr6 = ipaddress.ip_address('2001:db8::1')\n" -">>> addr6.version\n" -"6\n" -">>> addr4.version\n" -"4" -msgstr "" -">>> addr4 = ipaddress.ip_address('192.0.2.1')\n" -">>> addr6 = ipaddress.ip_address('2001:db8::1')\n" -">>> addr6.version\n" -"6\n" -">>> addr4.version\n" -"4" - -#: ../../howto/ipaddress.rst:172 -msgid "Obtaining the network from an interface::" -msgstr "從介面取得網路： ::" - -#: ../../howto/ipaddress.rst:174 -msgid "" -">>> host4 = ipaddress.ip_interface('192.0.2.1/24')\n" -">>> host4.network\n" -"IPv4Network('192.0.2.0/24')\n" -">>> host6 = ipaddress.ip_interface('2001:db8::1/96')\n" -">>> host6.network\n" -"IPv6Network('2001:db8::/96')" -msgstr "" -">>> host4 = ipaddress.ip_interface('192.0.2.1/24')\n" -">>> host4.network\n" -"IPv4Network('192.0.2.0/24')\n" -">>> host6 = ipaddress.ip_interface('2001:db8::1/96')\n" -">>> host6.network\n" -"IPv6Network('2001:db8::/96')" - -#: ../../howto/ipaddress.rst:181 -msgid "Finding out how many individual addresses are in a network::" -msgstr "找出網路中有多少個別位址： ::" - -#: ../../howto/ipaddress.rst:183 -msgid "" -">>> net4 = ipaddress.ip_network('192.0.2.0/24')\n" -">>> net4.num_addresses\n" -"256\n" -">>> net6 = ipaddress.ip_network('2001:db8::0/96')\n" -">>> net6.num_addresses\n" -"4294967296" -msgstr "" -">>> net4 = ipaddress.ip_network('192.0.2.0/24')\n" -">>> net4.num_addresses\n" -"256\n" -">>> net6 = ipaddress.ip_network('2001:db8::0/96')\n" -">>> net6.num_addresses\n" -"4294967296" - -#: ../../howto/ipaddress.rst:190 -msgid "Iterating through the \"usable\" addresses on a network::" -msgstr "迭代網路上「可用的」位址： ::" - -#: ../../howto/ipaddress.rst:192 -msgid "" -">>> net4 = ipaddress.ip_network('192.0.2.0/24')\n" -">>> for x in net4.hosts():\n" -"... print(x)\n" -"192.0.2.1\n" -"192.0.2.2\n" -"192.0.2.3\n" -"192.0.2.4\n" -"...\n" -"192.0.2.252\n" -"192.0.2.253\n" -"192.0.2.254" -msgstr "" -">>> net4 = ipaddress.ip_network('192.0.2.0/24')\n" -">>> for x in net4.hosts():\n" -"... print(x)\n" -"192.0.2.1\n" -"192.0.2.2\n" -"192.0.2.3\n" -"192.0.2.4\n" -"...\n" -"192.0.2.252\n" -"192.0.2.253\n" -"192.0.2.254" - -#: ../../howto/ipaddress.rst:205 -msgid "" -"Obtaining the netmask (i.e. set bits corresponding to the network prefix) or " -"the hostmask (any bits that are not part of the netmask):" -msgstr "" -"取得網路遮罩（即對應於網路前綴的設定位元）或主機遮罩（任何不屬於網路遮罩的位" -"元）： ::" - -#: ../../howto/ipaddress.rst:220 -msgid "Exploding or compressing the address::" -msgstr "展開或壓縮位址： ::" - -#: ../../howto/ipaddress.rst:222 -msgid "" -">>> addr6.exploded\n" -"'2001:0db8:0000:0000:0000:0000:0000:0001'\n" -">>> addr6.compressed\n" -"'2001:db8::1'\n" -">>> net6.exploded\n" -"'2001:0db8:0000:0000:0000:0000:0000:0000/96'\n" -">>> net6.compressed\n" -"'2001:db8::/96'" -msgstr "" -">>> addr6.exploded\n" -"'2001:0db8:0000:0000:0000:0000:0000:0001'\n" -">>> addr6.compressed\n" -"'2001:db8::1'\n" -">>> net6.exploded\n" -"'2001:0db8:0000:0000:0000:0000:0000:0000/96'\n" -">>> net6.compressed\n" -"'2001:db8::/96'" - -#: ../../howto/ipaddress.rst:231 -msgid "" -"While IPv4 doesn't support explosion or compression, the associated objects " -"still provide the relevant properties so that version neutral code can " -"easily ensure the most concise or most verbose form is used for IPv6 " -"addresses while still correctly handling IPv4 addresses." -msgstr "" -"雖然 IPv4 不支援展開或壓縮，但相關的物件仍然提供了相關屬性，使得版本中立的程" -"式碼可以輕鬆地確保 IPv6 位址使用最簡潔或最詳細的形式，同時仍能正確處理 IPv4 " -"位址。" - -#: ../../howto/ipaddress.rst:238 -msgid "Networks as lists of Addresses" -msgstr "作為位址串列的網路" - -#: ../../howto/ipaddress.rst:240 -msgid "" -"It's sometimes useful to treat networks as lists. This means it is possible " -"to index them like this::" -msgstr "有時將網路視為串列是很有用的。這意味著可以像這樣對它們進行索引： ::" - -#: ../../howto/ipaddress.rst:243 -msgid "" -">>> net4[1]\n" -"IPv4Address('192.0.2.1')\n" -">>> net4[-1]\n" -"IPv4Address('192.0.2.255')\n" -">>> net6[1]\n" -"IPv6Address('2001:db8::1')\n" -">>> net6[-1]\n" -"IPv6Address('2001:db8::ffff:ffff')" -msgstr "" -">>> net4[1]\n" -"IPv4Address('192.0.2.1')\n" -">>> net4[-1]\n" -"IPv4Address('192.0.2.255')\n" -">>> net6[1]\n" -"IPv6Address('2001:db8::1')\n" -">>> net6[-1]\n" -"IPv6Address('2001:db8::ffff:ffff')" - -#: ../../howto/ipaddress.rst:253 -msgid "" -"It also means that network objects lend themselves to using the list " -"membership test syntax like this::" -msgstr "這也意味著網路物件適合使用串列成員測試語法，像這樣： ::" - -#: ../../howto/ipaddress.rst:256 -msgid "" -"if address in network:\n" -" # do something" -msgstr "" -"if address in network:\n" -" # 做某些事情" - -#: ../../howto/ipaddress.rst:259 -msgid "Containment testing is done efficiently based on the network prefix::" -msgstr "msgstr \"可以根據網路前綴有效率地檢查是否包含： ::\"" - -#: ../../howto/ipaddress.rst:261 -msgid "" -">>> addr4 = ipaddress.ip_address('192.0.2.1')\n" -">>> addr4 in ipaddress.ip_network('192.0.2.0/24')\n" -"True\n" -">>> addr4 in ipaddress.ip_network('192.0.3.0/24')\n" -"False" -msgstr "" -">>> addr4 = ipaddress.ip_address('192.0.2.1')\n" -">>> addr4 in ipaddress.ip_network('192.0.2.0/24')\n" -"True\n" -">>> addr4 in ipaddress.ip_network('192.0.3.0/24')\n" -"False" - -#: ../../howto/ipaddress.rst:269 -msgid "Comparisons" -msgstr "比較" - -#: ../../howto/ipaddress.rst:271 -msgid "" -":mod:`ipaddress` provides some simple, hopefully intuitive ways to compare " -"objects, where it makes sense::" -msgstr "" -":mod:`ipaddress` 提供了一些簡單且希望是直觀的方法來比較物件，只要這樣做有道" -"理： ::" - -#: ../../howto/ipaddress.rst:274 -msgid "" -">>> ipaddress.ip_address('192.0.2.1') < ipaddress.ip_address('192.0.2.2')\n" -"True" -msgstr "" -">>> ipaddress.ip_address('192.0.2.1') < ipaddress.ip_address('192.0.2.2')\n" -"True" - -#: ../../howto/ipaddress.rst:277 -msgid "" -"A :exc:`TypeError` exception is raised if you try to compare objects of " -"different versions or different types." -msgstr "如果你嘗試比較不同版本或不同類型的物件，會引發 :exc:`TypeError` 例外。" - -#: ../../howto/ipaddress.rst:282 -msgid "Using IP Addresses with other modules" -msgstr "與其他模組一起使用 IP 位址" - -#: ../../howto/ipaddress.rst:284 -msgid "" -"Other modules that use IP addresses (such as :mod:`socket`) usually won't " -"accept objects from this module directly. Instead, they must be coerced to " -"an integer or string that the other module will accept::" -msgstr "" -"其他使用 IP 位址的模組（例如 :mod:`socket`）通常不會直接接受來自此模組的物" -"件。相反地，它們必須被強制轉換為其他模組能接受的整數或字串： ::" - -#: ../../howto/ipaddress.rst:288 -msgid "" -">>> addr4 = ipaddress.ip_address('192.0.2.1')\n" -">>> str(addr4)\n" -"'192.0.2.1'\n" -">>> int(addr4)\n" -"3221225985" -msgstr "" -">>> addr4 = ipaddress.ip_address('192.0.2.1')\n" -">>> str(addr4)\n" -"'192.0.2.1'\n" -">>> int(addr4)\n" -"3221225985" - -#: ../../howto/ipaddress.rst:296 -msgid "Getting more detail when instance creation fails" -msgstr "在實例建立失敗時取得更多細節" - -#: ../../howto/ipaddress.rst:298 -msgid "" -"When creating address/network/interface objects using the version-agnostic " -"factory functions, any errors will be reported as :exc:`ValueError` with a " -"generic error message that simply says the passed in value was not " -"recognized as an object of that type. The lack of a specific error is " -"because it's necessary to know whether the value is *supposed* to be IPv4 or " -"IPv6 in order to provide more detail on why it has been rejected." -msgstr "" -"當使用版本無關的工廠函式建立位址/網路/介面物件時，任何錯誤都會" -"以 :exc:`ValueError` 回報，並附帶一個通用的錯誤訊息，簡單地說明傳入的值未被識" -"別為該類型的物件。缺乏具體錯誤的原因是，為了提供更多關於為何被拒絕的細節，需" -"要知道該值應該是 IPv4 還是 IPv6。" - -#: ../../howto/ipaddress.rst:305 -msgid "" -"To support use cases where it is useful to have access to this additional " -"detail, the individual class constructors actually raise the :exc:" -"`ValueError` subclasses :exc:`ipaddress.AddressValueError` and :exc:" -"`ipaddress.NetmaskValueError` to indicate exactly which part of the " -"definition failed to parse correctly." -msgstr "" -"為了支援需要存取這些額外細節的使用情境，個別類別建構子實際上會引" -"發 :exc:`ValueError` 的子類別 :exc:`ipaddress.AddressValueError` " -"和 :exc:`ipaddress.NetmaskValueError`，以明確指出定義的哪個部分無法正確解析。" - -#: ../../howto/ipaddress.rst:311 -msgid "" -"The error messages are significantly more detailed when using the class " -"constructors directly. For example::" -msgstr "當直接使用類別建構子時，錯誤訊息會詳細得多。例如： ::" - -#: ../../howto/ipaddress.rst:314 -msgid "" -">>> ipaddress.ip_address(\"192.168.0.256\")\n" -"Traceback (most recent call last):\n" -" ...\n" -"ValueError: '192.168.0.256' does not appear to be an IPv4 or IPv6 address\n" -">>> ipaddress.IPv4Address(\"192.168.0.256\")\n" -"Traceback (most recent call last):\n" -" ...\n" -"ipaddress.AddressValueError: Octet 256 (> 255) not permitted in " -"'192.168.0.256'\n" -"\n" -">>> ipaddress.ip_network(\"192.168.0.1/64\")\n" -"Traceback (most recent call last):\n" -" ...\n" -"ValueError: '192.168.0.1/64' does not appear to be an IPv4 or IPv6 network\n" -">>> ipaddress.IPv4Network(\"192.168.0.1/64\")\n" -"Traceback (most recent call last):\n" -" ...\n" -"ipaddress.NetmaskValueError: '64' is not a valid netmask" -msgstr "" -">>> ipaddress.ip_address(\"192.168.0.256\")\n" -"Traceback (most recent call last):\n" -" ...\n" -"ValueError: '192.168.0.256' does not appear to be an IPv4 or IPv6 address\n" -">>> ipaddress.IPv4Address(\"192.168.0.256\")\n" -"Traceback (most recent call last):\n" -" ...\n" -"ipaddress.AddressValueError: Octet 256 (> 255) not permitted in " -"'192.168.0.256'\n" -"\n" -">>> ipaddress.ip_network(\"192.168.0.1/64\")\n" -"Traceback (most recent call last):\n" -" ...\n" -"ValueError: '192.168.0.1/64' does not appear to be an IPv4 or IPv6 network\n" -">>> ipaddress.IPv4Network(\"192.168.0.1/64\")\n" -"Traceback (most recent call last):\n" -" ...\n" -"ipaddress.NetmaskValueError: '64' is not a valid netmask" - -#: ../../howto/ipaddress.rst:332 -msgid "" -"However, both of the module specific exceptions have :exc:`ValueError` as " -"their parent class, so if you're not concerned with the particular type of " -"error, you can still write code like the following::" -msgstr "" -"然而，這兩個模組特定的例外都以 :exc:`ValueError` 作為它們的父類別，因此如果你" -"不關心特定類型的錯誤，你仍然可以撰寫如下的程式碼： ::" - -#: ../../howto/ipaddress.rst:336 -msgid "" -"try:\n" -" network = ipaddress.IPv4Network(address)\n" -"except ValueError:\n" -" print('address/netmask is invalid for IPv4:', address)" -msgstr "" -"try:\n" -" network = ipaddress.IPv4Network(address)\n" -"except ValueError:\n" -" print('address/netmask is invalid for IPv4:', address)" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Leon H., 2017 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-12-01 00:17+0000\n" +"PO-Revision-Date: 2025-12-26 10:42-0500\n" +"Last-Translator: Chih-Chao Chang \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" +"X-Generator: Poedit 3.8\n" + +#: ../../howto/ipaddress.rst:9 +msgid "An introduction to the ipaddress module" +msgstr "ipaddress 模組介紹" + +#: ../../howto/ipaddress.rst:0 +msgid "author" +msgstr "作者" + +#: ../../howto/ipaddress.rst:11 +msgid "Peter Moody" +msgstr "Peter Moody" + +#: ../../howto/ipaddress.rst:12 +msgid "Nick Coghlan" +msgstr "Nick Coghlan" + +#: ../../howto/ipaddress.rst:14 +msgid "Overview" +msgstr "總攬" + +#: ../../howto/ipaddress.rst:16 +msgid "" +"This document aims to provide a gentle introduction to the :mod:`ipaddress` " +"module. It is aimed primarily at users that aren't already familiar with IP " +"networking terminology, but may also be useful to network engineers wanting " +"an overview of how :mod:`ipaddress` represents IP network addressing " +"concepts." +msgstr "" +"這份文件旨在為 :mod:`ipaddress` 模組提供一個初步介紹。文件主要針對那些不熟悉 " +"IP 網路術語的使用者，但對想要了解 :mod:`ipaddress` 模組如何表示 IP 網址概念的" +"網路工程師也可能有用。" + +#: ../../howto/ipaddress.rst:24 +msgid "Creating Address/Network/Interface objects" +msgstr "建立 Address/Network/Interface 物件" + +#: ../../howto/ipaddress.rst:26 +msgid "" +"Since :mod:`ipaddress` is a module for inspecting and manipulating IP " +"addresses, the first thing you'll want to do is create some objects. You " +"can use :mod:`ipaddress` to create objects from strings and integers." +msgstr "" +"由於 :mod:`ipaddress` 是一個用於檢查和操作 IP 位址的模組，你首先會想要做的事" +"情是建立一些物件。你可以使用 :mod:`ipaddress` 從字串和整數建立物件。" + +#: ../../howto/ipaddress.rst:32 +msgid "A Note on IP Versions" +msgstr "關於 IP 版本的說明" + +#: ../../howto/ipaddress.rst:34 +msgid "" +"For readers that aren't particularly familiar with IP addressing, it's " +"important to know that the Internet Protocol (IP) is currently in the " +"process of moving from version 4 of the protocol to version 6. This " +"transition is occurring largely because version 4 of the protocol doesn't " +"provide enough addresses to handle the needs of the whole world, especially " +"given the increasing number of devices with direct connections to the " +"internet." +msgstr "" +"對於不太熟悉 IP 位址的讀者來說，重要的是要知道網際網路協定 (Internet " +"Protocol, IP) 目前正在從協定的第 4 版過渡到第 6 版。這個轉換主要是因為協定的" +"第 4 版無法提供足夠的位址來處理全世界的需求，特別是考慮到直接連接到網際網路的" +"裝置數量不斷增加。" + +#: ../../howto/ipaddress.rst:41 +msgid "" +"Explaining the details of the differences between the two versions of the " +"protocol is beyond the scope of this introduction, but readers need to at " +"least be aware that these two versions exist, and it will sometimes be " +"necessary to force the use of one version or the other." +msgstr "" +"解釋這兩個版本協定之間差異的細節超出了本文介紹的範圍，但讀者至少需要知道這兩" +"個版本的存在，而且有時候會需要強制使用其中一個版本。" + +#: ../../howto/ipaddress.rst:48 +msgid "IP Host Addresses" +msgstr "IP 主機位址" + +#: ../../howto/ipaddress.rst:50 +msgid "" +"Addresses, often referred to as \"host addresses\" are the most basic unit " +"when working with IP addressing. The simplest way to create addresses is to " +"use the :func:`ipaddress.ip_address` factory function, which automatically " +"determines whether to create an IPv4 or IPv6 address based on the passed in " +"value:" +msgstr "" +"位址，通常被稱為「主機位址」，是處理 IP 位址時最基本的單位。建立位址最簡單的" +"方法是使用 :func:`ipaddress.ip_address` 工廠函式，它會根據傳入的值自動判斷要" +"建立 IPv4 還是 IPv6 位址：" + +#: ../../howto/ipaddress.rst:61 +msgid "" +"Addresses can also be created directly from integers. Values that will fit " +"within 32 bits are assumed to be IPv4 addresses::" +msgstr "" +"位址也可以直接從整數建立。符合 32 位元以內的值會被假定為 IPv4 位址： ::" + +#: ../../howto/ipaddress.rst:64 +msgid "" +">>> ipaddress.ip_address(3221225985)\n" +"IPv4Address('192.0.2.1')\n" +">>> ipaddress.ip_address(42540766411282592856903984951653826561)\n" +"IPv6Address('2001:db8::1')" +msgstr "" +">>> ipaddress.ip_address(3221225985)\n" +"IPv4Address('192.0.2.1')\n" +">>> ipaddress.ip_address(42540766411282592856903984951653826561)\n" +"IPv6Address('2001:db8::1')" + +#: ../../howto/ipaddress.rst:69 +msgid "" +"To force the use of IPv4 or IPv6 addresses, the relevant classes can be " +"invoked directly. This is particularly useful to force creation of IPv6 " +"addresses for small integers::" +msgstr "" +"要強制使用 IPv4 或 IPv6 位址，可以直接呼叫相關的類別。這對於強制為小整數建立 " +"IPv6 位址特別有用： ::" + +#: ../../howto/ipaddress.rst:73 +msgid "" +">>> ipaddress.ip_address(1)\n" +"IPv4Address('0.0.0.1')\n" +">>> ipaddress.IPv4Address(1)\n" +"IPv4Address('0.0.0.1')\n" +">>> ipaddress.IPv6Address(1)\n" +"IPv6Address('::1')" +msgstr "" +">>> ipaddress.ip_address(1)\n" +"IPv4Address('0.0.0.1')\n" +">>> ipaddress.IPv4Address(1)\n" +"IPv4Address('0.0.0.1')\n" +">>> ipaddress.IPv6Address(1)\n" +"IPv6Address('::1')" + +#: ../../howto/ipaddress.rst:82 +msgid "Defining Networks" +msgstr "定義網路" + +#: ../../howto/ipaddress.rst:84 +msgid "" +"Host addresses are usually grouped together into IP networks, so :mod:" +"`ipaddress` provides a way to create, inspect and manipulate network " +"definitions. IP network objects are constructed from strings that define the " +"range of host addresses that are part of that network. The simplest form for " +"that information is a \"network address/network prefix\" pair, where the " +"prefix defines the number of leading bits that are compared to determine " +"whether or not an address is part of the network and the network address " +"defines the expected value of those bits." +msgstr "" +"主機位址通常會被分組到 IP 網路中，因此 :mod:`ipaddress` 提供了一種建立、檢查" +"和操作網路定義的方法。IP 網路物件是從定義該網路所包含之主機位址範圍的字串建構" +"而成。這些資訊最簡單的形式是「網路位址/網路前綴」配對，其中前綴定義了用於比較" +"的前導位元數量，以判斷位址是否屬於該網路的一部分，而網路位址則定義了這些位元" +"的預期值。" + +#: ../../howto/ipaddress.rst:93 +msgid "" +"As for addresses, a factory function is provided that determines the correct " +"IP version automatically::" +msgstr "至於位址，提供了一個工廠函式可以自動判斷正確的 IP 版本： ::" + +#: ../../howto/ipaddress.rst:96 +msgid "" +">>> ipaddress.ip_network('192.0.2.0/24')\n" +"IPv4Network('192.0.2.0/24')\n" +">>> ipaddress.ip_network('2001:db8::0/96')\n" +"IPv6Network('2001:db8::/96')" +msgstr "" +">>> ipaddress.ip_network('192.0.2.0/24')\n" +"IPv4Network('192.0.2.0/24')\n" +">>> ipaddress.ip_network('2001:db8::0/96')\n" +"IPv6Network('2001:db8::/96')" + +#: ../../howto/ipaddress.rst:101 +msgid "" +"Network objects cannot have any host bits set. The practical effect of this " +"is that ``192.0.2.1/24`` does not describe a network. Such definitions are " +"referred to as interface objects since the ip-on-a-network notation is " +"commonly used to describe network interfaces of a computer on a given " +"network and are described further in the next section." +msgstr "" +"網路物件不能設定任何主機位元。這樣做的實際效果是 ``192.0.2.1/24`` 並不描述一個網" +"路。這類定義被稱為介面物件，因為 ip-on-a-network 標記法通常用於描述電腦在給定" +"網路上的網路介面，並將在下一節中進一步說明。" + +#: ../../howto/ipaddress.rst:107 +msgid "" +"By default, attempting to create a network object with host bits set will " +"result in :exc:`ValueError` being raised. To request that the additional " +"bits instead be coerced to zero, the flag ``strict=False`` can be passed to " +"the constructor::" +msgstr "" +"預設情況下，嘗試建立帶有主機位元設定的網路物件會導致引發 :exc:`ValueError`。" +"若要求將額外的位元強制轉換為零，可以在建構子中傳遞旗標 ``strict=False``： ::" + +#: ../../howto/ipaddress.rst:112 +msgid "" +">>> ipaddress.ip_network('192.0.2.1/24')\n" +"Traceback (most recent call last):\n" +" ...\n" +"ValueError: 192.0.2.1/24 has host bits set\n" +">>> ipaddress.ip_network('192.0.2.1/24', strict=False)\n" +"IPv4Network('192.0.2.0/24')" +msgstr "" +">>> ipaddress.ip_network('192.0.2.1/24')\n" +"Traceback (most recent call last):\n" +" ...\n" +"ValueError: 192.0.2.1/24 has host bits set\n" +">>> ipaddress.ip_network('192.0.2.1/24', strict=False)\n" +"IPv4Network('192.0.2.0/24')" + +#: ../../howto/ipaddress.rst:119 +msgid "" +"While the string form offers significantly more flexibility, networks can " +"also be defined with integers, just like host addresses. In this case, the " +"network is considered to contain only the single address identified by the " +"integer, so the network prefix includes the entire network address::" +msgstr "" +"雖然字串形式提供了更大的靈活性，但網路也可以像主機位址一樣使用整數來定義。在" +"這種情況下，網路被認為僅包含由該整數識別的單一位址，因此網路前綴包含了整個網" +"路位址： ::" + +#: ../../howto/ipaddress.rst:124 +msgid "" +">>> ipaddress.ip_network(3221225984)\n" +"IPv4Network('192.0.2.0/32')\n" +">>> ipaddress.ip_network(42540766411282592856903984951653826560)\n" +"IPv6Network('2001:db8::/128')" +msgstr "" +">>> ipaddress.ip_network(3221225984)\n" +"IPv4Network('192.0.2.0/32')\n" +">>> ipaddress.ip_network(42540766411282592856903984951653826560)\n" +"IPv6Network('2001:db8::/128')" + +#: ../../howto/ipaddress.rst:129 +msgid "" +"As with addresses, creation of a particular kind of network can be forced by " +"calling the class constructor directly instead of using the factory function." +msgstr "" +"與位址一樣，可以透過直接呼叫類別建構子而非使用工廠函式，來強制建立特定類型的" +"網路。" + +#: ../../howto/ipaddress.rst:135 +msgid "Host Interfaces" +msgstr "主機介面" + +#: ../../howto/ipaddress.rst:137 +msgid "" +"As mentioned just above, if you need to describe an address on a particular " +"network, neither the address nor the network classes are sufficient. " +"Notation like ``192.0.2.1/24`` is commonly used by network engineers and the " +"people who write tools for firewalls and routers as shorthand for \"the host " +"``192.0.2.1`` on the network ``192.0.2.0/24``\", Accordingly, :mod:" +"`ipaddress` provides a set of hybrid classes that associate an address with " +"a particular network. The interface for creation is identical to that for " +"defining network objects, except that the address portion isn't constrained " +"to being a network address." +msgstr "" +"如上所述，如果你需要描述特定網路上的位址，位址類別和網路類別都不足以滿足需" +"求。像 ``192.0.2.1/24`` 這樣的標記法通常被網路工程師以及編寫防火牆和路由器工" +"具的人用作「網路 ``192.0.2.0/24`` 上的主機 ``192.0.2.1``」的簡寫。因" +"此，:mod:`ipaddress` 提供了一組混合類別，將位址與特定網路關聯起來。建立介面的" +"方式與定義網路物件相同，只是位址部分不受限於必須是網路位址。" + +#: ../../howto/ipaddress.rst:152 +msgid "" +"Integer inputs are accepted (as with networks), and use of a particular IP " +"version can be forced by calling the relevant constructor directly." +msgstr "" +"可以接受整數輸入（如同網路一樣），並且可以透過直接呼叫相關的建構子來強制使用" +"特定的 IP 版本。" + +#: ../../howto/ipaddress.rst:157 +msgid "Inspecting Address/Network/Interface Objects" +msgstr "檢視 Address/Network/Interface 物件" + +#: ../../howto/ipaddress.rst:159 +msgid "" +"You've gone to the trouble of creating an IPv(4|6)(Address|Network|" +"Interface) object, so you probably want to get information about it. :mod:" +"`ipaddress` tries to make doing this easy and intuitive." +msgstr "" +"你費心建立了 IPv(4|6)(Address|Network|Interface) 物件，所以你可能想要取得關於" +"它的資訊。:mod:`ipaddress` 試圖讓這件事變得簡單且直觀。" + +#: ../../howto/ipaddress.rst:163 +msgid "Extracting the IP version::" +msgstr "提取 IP 版本： ::" + +#: ../../howto/ipaddress.rst:165 +msgid "" +">>> addr4 = ipaddress.ip_address('192.0.2.1')\n" +">>> addr6 = ipaddress.ip_address('2001:db8::1')\n" +">>> addr6.version\n" +"6\n" +">>> addr4.version\n" +"4" +msgstr "" +">>> addr4 = ipaddress.ip_address('192.0.2.1')\n" +">>> addr6 = ipaddress.ip_address('2001:db8::1')\n" +">>> addr6.version\n" +"6\n" +">>> addr4.version\n" +"4" + +#: ../../howto/ipaddress.rst:172 +msgid "Obtaining the network from an interface::" +msgstr "從介面取得網路： ::" + +#: ../../howto/ipaddress.rst:174 +msgid "" +">>> host4 = ipaddress.ip_interface('192.0.2.1/24')\n" +">>> host4.network\n" +"IPv4Network('192.0.2.0/24')\n" +">>> host6 = ipaddress.ip_interface('2001:db8::1/96')\n" +">>> host6.network\n" +"IPv6Network('2001:db8::/96')" +msgstr "" +">>> host4 = ipaddress.ip_interface('192.0.2.1/24')\n" +">>> host4.network\n" +"IPv4Network('192.0.2.0/24')\n" +">>> host6 = ipaddress.ip_interface('2001:db8::1/96')\n" +">>> host6.network\n" +"IPv6Network('2001:db8::/96')" + +#: ../../howto/ipaddress.rst:181 +msgid "Finding out how many individual addresses are in a network::" +msgstr "找出網路中有多少個別位址： ::" + +#: ../../howto/ipaddress.rst:183 +msgid "" +">>> net4 = ipaddress.ip_network('192.0.2.0/24')\n" +">>> net4.num_addresses\n" +"256\n" +">>> net6 = ipaddress.ip_network('2001:db8::0/96')\n" +">>> net6.num_addresses\n" +"4294967296" +msgstr "" +">>> net4 = ipaddress.ip_network('192.0.2.0/24')\n" +">>> net4.num_addresses\n" +"256\n" +">>> net6 = ipaddress.ip_network('2001:db8::0/96')\n" +">>> net6.num_addresses\n" +"4294967296" + +#: ../../howto/ipaddress.rst:190 +msgid "Iterating through the \"usable\" addresses on a network::" +msgstr "迭代網路上「可用的」位址： ::" + +#: ../../howto/ipaddress.rst:192 +msgid "" +">>> net4 = ipaddress.ip_network('192.0.2.0/24')\n" +">>> for x in net4.hosts():\n" +"... print(x)\n" +"192.0.2.1\n" +"192.0.2.2\n" +"192.0.2.3\n" +"192.0.2.4\n" +"...\n" +"192.0.2.252\n" +"192.0.2.253\n" +"192.0.2.254" +msgstr "" +">>> net4 = ipaddress.ip_network('192.0.2.0/24')\n" +">>> for x in net4.hosts():\n" +"... print(x)\n" +"192.0.2.1\n" +"192.0.2.2\n" +"192.0.2.3\n" +"192.0.2.4\n" +"...\n" +"192.0.2.252\n" +"192.0.2.253\n" +"192.0.2.254" + +#: ../../howto/ipaddress.rst:205 +msgid "" +"Obtaining the netmask (i.e. set bits corresponding to the network prefix) or " +"the hostmask (any bits that are not part of the netmask):" +msgstr "" +"取得網路遮罩（即對應於網路前綴的設定位元）或主機遮罩（任何不屬於網路遮罩的位" +"元）： ::" + +#: ../../howto/ipaddress.rst:220 +msgid "Exploding or compressing the address::" +msgstr "展開或壓縮位址： ::" + +#: ../../howto/ipaddress.rst:222 +msgid "" +">>> addr6.exploded\n" +"'2001:0db8:0000:0000:0000:0000:0000:0001'\n" +">>> addr6.compressed\n" +"'2001:db8::1'\n" +">>> net6.exploded\n" +"'2001:0db8:0000:0000:0000:0000:0000:0000/96'\n" +">>> net6.compressed\n" +"'2001:db8::/96'" +msgstr "" +">>> addr6.exploded\n" +"'2001:0db8:0000:0000:0000:0000:0000:0001'\n" +">>> addr6.compressed\n" +"'2001:db8::1'\n" +">>> net6.exploded\n" +"'2001:0db8:0000:0000:0000:0000:0000:0000/96'\n" +">>> net6.compressed\n" +"'2001:db8::/96'" + +#: ../../howto/ipaddress.rst:231 +msgid "" +"While IPv4 doesn't support explosion or compression, the associated objects " +"still provide the relevant properties so that version neutral code can " +"easily ensure the most concise or most verbose form is used for IPv6 " +"addresses while still correctly handling IPv4 addresses." +msgstr "" +"雖然 IPv4 不支援展開或壓縮，但相關的物件仍然提供了相關屬性，使得版本中立的程" +"式碼可以輕鬆地確保 IPv6 位址使用最簡潔或最詳細的形式，同時仍能正確處理 IPv4 " +"位址。" + +#: ../../howto/ipaddress.rst:238 +msgid "Networks as lists of Addresses" +msgstr "作為位址串列的網路" + +#: ../../howto/ipaddress.rst:240 +msgid "" +"It's sometimes useful to treat networks as lists. This means it is possible " +"to index them like this::" +msgstr "有時將網路視為串列是很有用的。這意味著可以像這樣對它們進行索引： ::" + +#: ../../howto/ipaddress.rst:243 +msgid "" +">>> net4[1]\n" +"IPv4Address('192.0.2.1')\n" +">>> net4[-1]\n" +"IPv4Address('192.0.2.255')\n" +">>> net6[1]\n" +"IPv6Address('2001:db8::1')\n" +">>> net6[-1]\n" +"IPv6Address('2001:db8::ffff:ffff')" +msgstr "" +">>> net4[1]\n" +"IPv4Address('192.0.2.1')\n" +">>> net4[-1]\n" +"IPv4Address('192.0.2.255')\n" +">>> net6[1]\n" +"IPv6Address('2001:db8::1')\n" +">>> net6[-1]\n" +"IPv6Address('2001:db8::ffff:ffff')" + +#: ../../howto/ipaddress.rst:253 +msgid "" +"It also means that network objects lend themselves to using the list " +"membership test syntax like this::" +msgstr "這也意味著網路物件適合使用串列成員測試語法，像這樣： ::" + +#: ../../howto/ipaddress.rst:256 +msgid "" +"if address in network:\n" +" # do something" +msgstr "" +"if address in network:\n" +" # 做某些事情" + +#: ../../howto/ipaddress.rst:259 +msgid "Containment testing is done efficiently based on the network prefix::" +msgstr "msgstr \"可以根據網路前綴有效率地檢查是否包含： ::\"" + +#: ../../howto/ipaddress.rst:261 +msgid "" +">>> addr4 = ipaddress.ip_address('192.0.2.1')\n" +">>> addr4 in ipaddress.ip_network('192.0.2.0/24')\n" +"True\n" +">>> addr4 in ipaddress.ip_network('192.0.3.0/24')\n" +"False" +msgstr "" +">>> addr4 = ipaddress.ip_address('192.0.2.1')\n" +">>> addr4 in ipaddress.ip_network('192.0.2.0/24')\n" +"True\n" +">>> addr4 in ipaddress.ip_network('192.0.3.0/24')\n" +"False" + +#: ../../howto/ipaddress.rst:269 +msgid "Comparisons" +msgstr "比較" + +#: ../../howto/ipaddress.rst:271 +msgid "" +":mod:`ipaddress` provides some simple, hopefully intuitive ways to compare " +"objects, where it makes sense::" +msgstr "" +":mod:`ipaddress` 提供了一些簡單且希望是直觀的方法來比較物件，只要這樣做有道" +"理： ::" + +#: ../../howto/ipaddress.rst:274 +msgid "" +">>> ipaddress.ip_address('192.0.2.1') < ipaddress.ip_address('192.0.2.2')\n" +"True" +msgstr "" +">>> ipaddress.ip_address('192.0.2.1') < ipaddress.ip_address('192.0.2.2')\n" +"True" + +#: ../../howto/ipaddress.rst:277 +msgid "" +"A :exc:`TypeError` exception is raised if you try to compare objects of " +"different versions or different types." +msgstr "如果你嘗試比較不同版本或不同類型的物件，會引發 :exc:`TypeError` 例外。" + +#: ../../howto/ipaddress.rst:282 +msgid "Using IP Addresses with other modules" +msgstr "與其他模組一起使用 IP 位址" + +#: ../../howto/ipaddress.rst:284 +msgid "" +"Other modules that use IP addresses (such as :mod:`socket`) usually won't " +"accept objects from this module directly. Instead, they must be coerced to " +"an integer or string that the other module will accept::" +msgstr "" +"其他使用 IP 位址的模組（例如 :mod:`socket`）通常不會直接接受來自此模組的物" +"件。相反地，它們必須被強制轉換為其他模組能接受的整數或字串： ::" + +#: ../../howto/ipaddress.rst:288 +msgid "" +">>> addr4 = ipaddress.ip_address('192.0.2.1')\n" +">>> str(addr4)\n" +"'192.0.2.1'\n" +">>> int(addr4)\n" +"3221225985" +msgstr "" +">>> addr4 = ipaddress.ip_address('192.0.2.1')\n" +">>> str(addr4)\n" +"'192.0.2.1'\n" +">>> int(addr4)\n" +"3221225985" + +#: ../../howto/ipaddress.rst:296 +msgid "Getting more detail when instance creation fails" +msgstr "在實例建立失敗時取得更多細節" + +#: ../../howto/ipaddress.rst:298 +msgid "" +"When creating address/network/interface objects using the version-agnostic " +"factory functions, any errors will be reported as :exc:`ValueError` with a " +"generic error message that simply says the passed in value was not " +"recognized as an object of that type. The lack of a specific error is " +"because it's necessary to know whether the value is *supposed* to be IPv4 or " +"IPv6 in order to provide more detail on why it has been rejected." +msgstr "" +"當使用版本無關的工廠函式建立位址/網路/介面物件時，任何錯誤都會" +"以 :exc:`ValueError` 回報，並附帶一個通用的錯誤訊息，簡單地說明傳入的值未被識" +"別為該類型的物件。缺乏具體錯誤的原因是，為了提供更多關於為何被拒絕的細節，需" +"要知道該值應該是 IPv4 還是 IPv6。" + +#: ../../howto/ipaddress.rst:305 +msgid "" +"To support use cases where it is useful to have access to this additional " +"detail, the individual class constructors actually raise the :exc:" +"`ValueError` subclasses :exc:`ipaddress.AddressValueError` and :exc:" +"`ipaddress.NetmaskValueError` to indicate exactly which part of the " +"definition failed to parse correctly." +msgstr "" +"為了支援需要存取這些額外細節的使用情境，個別類別建構子實際上會引" +"發 :exc:`ValueError` 的子類別 :exc:`ipaddress.AddressValueError` " +"和 :exc:`ipaddress.NetmaskValueError`，以明確指出定義的哪個部分無法正確解析。" + +#: ../../howto/ipaddress.rst:311 +msgid "" +"The error messages are significantly more detailed when using the class " +"constructors directly. For example::" +msgstr "當直接使用類別建構子時，錯誤訊息會詳細得多。例如： ::" + +#: ../../howto/ipaddress.rst:314 +msgid "" +">>> ipaddress.ip_address(\"192.168.0.256\")\n" +"Traceback (most recent call last):\n" +" ...\n" +"ValueError: '192.168.0.256' does not appear to be an IPv4 or IPv6 address\n" +">>> ipaddress.IPv4Address(\"192.168.0.256\")\n" +"Traceback (most recent call last):\n" +" ...\n" +"ipaddress.AddressValueError: Octet 256 (> 255) not permitted in " +"'192.168.0.256'\n" +"\n" +">>> ipaddress.ip_network(\"192.168.0.1/64\")\n" +"Traceback (most recent call last):\n" +" ...\n" +"ValueError: '192.168.0.1/64' does not appear to be an IPv4 or IPv6 network\n" +">>> ipaddress.IPv4Network(\"192.168.0.1/64\")\n" +"Traceback (most recent call last):\n" +" ...\n" +"ipaddress.NetmaskValueError: '64' is not a valid netmask" +msgstr "" +">>> ipaddress.ip_address(\"192.168.0.256\")\n" +"Traceback (most recent call last):\n" +" ...\n" +"ValueError: '192.168.0.256' does not appear to be an IPv4 or IPv6 address\n" +">>> ipaddress.IPv4Address(\"192.168.0.256\")\n" +"Traceback (most recent call last):\n" +" ...\n" +"ipaddress.AddressValueError: Octet 256 (> 255) not permitted in " +"'192.168.0.256'\n" +"\n" +">>> ipaddress.ip_network(\"192.168.0.1/64\")\n" +"Traceback (most recent call last):\n" +" ...\n" +"ValueError: '192.168.0.1/64' does not appear to be an IPv4 or IPv6 network\n" +">>> ipaddress.IPv4Network(\"192.168.0.1/64\")\n" +"Traceback (most recent call last):\n" +" ...\n" +"ipaddress.NetmaskValueError: '64' is not a valid netmask" + +#: ../../howto/ipaddress.rst:332 +msgid "" +"However, both of the module specific exceptions have :exc:`ValueError` as " +"their parent class, so if you're not concerned with the particular type of " +"error, you can still write code like the following::" +msgstr "" +"然而，這兩個模組特定的例外都以 :exc:`ValueError` 作為它們的父類別，因此如果你" +"不關心特定類型的錯誤，你仍然可以撰寫如下的程式碼： ::" + +#: ../../howto/ipaddress.rst:336 +msgid "" +"try:\n" +" network = ipaddress.IPv4Network(address)\n" +"except ValueError:\n" +" print('address/netmask is invalid for IPv4:', address)" +msgstr "" +"try:\n" +" network = ipaddress.IPv4Network(address)\n" +"except ValueError:\n" +" print('address/netmask is invalid for IPv4:', address)" diff --git a/howto/isolating-extensions.po b/howto/isolating-extensions.po index 2c5f99df61..dabfdbbfd3 100644 --- a/howto/isolating-extensions.po +++ b/howto/isolating-extensions.po @@ -1,978 +1,978 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# FIRST AUTHOR , YEAR. -# -#, fuzzy -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-12-01 00:17+0000\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \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" - -#: ../../howto/isolating-extensions.rst:7 -msgid "Isolating Extension Modules" -msgstr "隔離擴充模組" - -#: ../../howto/isolating-extensions.rst:9 -msgid "Abstract" -msgstr "摘要" - -#: ../../howto/isolating-extensions.rst:11 -msgid "" -"Traditionally, state belonging to Python extension modules was kept in C " -"``static`` variables, which have process-wide scope. This document describes " -"problems of such per-process state and shows a safer way: per-module state." -msgstr "" - -#: ../../howto/isolating-extensions.rst:16 -msgid "" -"The document also describes how to switch to per-module state where " -"possible. This transition involves allocating space for that state, " -"potentially switching from static types to heap types, and—perhaps most " -"importantly—accessing per-module state from code." -msgstr "" - -#: ../../howto/isolating-extensions.rst:23 -msgid "Who should read this" -msgstr "" - -#: ../../howto/isolating-extensions.rst:25 -msgid "" -"This guide is written for maintainers of :ref:`C-API ` " -"extensions who would like to make that extension safer to use in " -"applications where Python itself is used as a library." -msgstr "" - -#: ../../howto/isolating-extensions.rst:31 -msgid "Background" -msgstr "背景" - -#: ../../howto/isolating-extensions.rst:33 -msgid "" -"An *interpreter* is the context in which Python code runs. It contains " -"configuration (e.g. the import path) and runtime state (e.g. the set of " -"imported modules)." -msgstr "" - -#: ../../howto/isolating-extensions.rst:37 -msgid "" -"Python supports running multiple interpreters in one process. There are two " -"cases to think about—users may run interpreters:" -msgstr "" - -#: ../../howto/isolating-extensions.rst:40 -msgid "" -"in sequence, with several :c:func:`Py_InitializeEx`/:c:func:`Py_FinalizeEx` " -"cycles, and" -msgstr "" - -#: ../../howto/isolating-extensions.rst:42 -msgid "" -"in parallel, managing \"sub-interpreters\" using :c:func:" -"`Py_NewInterpreter`/:c:func:`Py_EndInterpreter`." -msgstr "" - -#: ../../howto/isolating-extensions.rst:45 -msgid "" -"Both cases (and combinations of them) would be most useful when embedding " -"Python within a library. Libraries generally shouldn't make assumptions " -"about the application that uses them, which include assuming a process-wide " -"\"main Python interpreter\"." -msgstr "" - -#: ../../howto/isolating-extensions.rst:50 -msgid "" -"Historically, Python extension modules don't handle this use case well. Many " -"extension modules (and even some stdlib modules) use *per-process* global " -"state, because C ``static`` variables are extremely easy to use. Thus, data " -"that should be specific to an interpreter ends up being shared between " -"interpreters. Unless the extension developer is careful, it is very easy to " -"introduce edge cases that lead to crashes when a module is loaded in more " -"than one interpreter in the same process." -msgstr "" - -#: ../../howto/isolating-extensions.rst:58 -msgid "" -"Unfortunately, *per-interpreter* state is not easy to achieve. Extension " -"authors tend to not keep multiple interpreters in mind when developing, and " -"it is currently cumbersome to test the behavior." -msgstr "" - -#: ../../howto/isolating-extensions.rst:63 -msgid "Enter Per-Module State" -msgstr "" - -#: ../../howto/isolating-extensions.rst:65 -msgid "" -"Instead of focusing on per-interpreter state, Python's C API is evolving to " -"better support the more granular *per-module* state. This means that C-level " -"data should be attached to a *module object*. Each interpreter creates its " -"own module object, keeping the data separate. For testing the isolation, " -"multiple module objects corresponding to a single extension can even be " -"loaded in a single interpreter." -msgstr "" - -#: ../../howto/isolating-extensions.rst:72 -msgid "" -"Per-module state provides an easy way to think about lifetime and resource " -"ownership: the extension module will initialize when a module object is " -"created, and clean up when it's freed. In this regard, a module is just like " -"any other :c:expr:`PyObject *`; there are no \"on interpreter shutdown\" " -"hooks to think—or forget—about." -msgstr "" - -#: ../../howto/isolating-extensions.rst:78 -msgid "" -"Note that there are use cases for different kinds of \"globals\": per-" -"process, per-interpreter, per-thread or per-task state. With per-module " -"state as the default, these are still possible, but you should treat them as " -"exceptional cases: if you need them, you should give them additional care " -"and testing. (Note that this guide does not cover them.)" -msgstr "" - -#: ../../howto/isolating-extensions.rst:87 -msgid "Isolated Module Objects" -msgstr "" - -#: ../../howto/isolating-extensions.rst:89 -msgid "" -"The key point to keep in mind when developing an extension module is that " -"several module objects can be created from a single shared library. For " -"example:" -msgstr "" - -#: ../../howto/isolating-extensions.rst:93 -msgid "" -">>> import sys\n" -">>> import binascii\n" -">>> old_binascii = binascii\n" -">>> del sys.modules['binascii']\n" -">>> import binascii # create a new module object\n" -">>> old_binascii == binascii\n" -"False" -msgstr "" -">>> import sys\n" -">>> import binascii\n" -">>> old_binascii = binascii\n" -">>> del sys.modules['binascii']\n" -">>> import binascii # 建立一個新的模組物件\n" -">>> old_binascii == binascii\n" -"False" - -#: ../../howto/isolating-extensions.rst:103 -msgid "" -"As a rule of thumb, the two modules should be completely independent. All " -"objects and state specific to the module should be encapsulated within the " -"module object, not shared with other module objects, and cleaned up when the " -"module object is deallocated. Since this just is a rule of thumb, exceptions " -"are possible (see `Managing Global State`_), but they will need more thought " -"and attention to edge cases." -msgstr "" - -#: ../../howto/isolating-extensions.rst:111 -msgid "" -"While some modules could do with less stringent restrictions, isolated " -"modules make it easier to set clear expectations and guidelines that work " -"across a variety of use cases." -msgstr "" - -#: ../../howto/isolating-extensions.rst:117 -msgid "Surprising Edge Cases" -msgstr "" - -#: ../../howto/isolating-extensions.rst:119 -msgid "" -"Note that isolated modules do create some surprising edge cases. Most " -"notably, each module object will typically not share its classes and " -"exceptions with other similar modules. Continuing from the `example above " -"`__, note that ``old_binascii.Error`` and " -"``binascii.Error`` are separate objects. In the following code, the " -"exception is *not* caught:" -msgstr "" - -#: ../../howto/isolating-extensions.rst:126 -msgid "" -">>> old_binascii.Error == binascii.Error\n" -"False\n" -">>> try:\n" -"... old_binascii.unhexlify(b'qwertyuiop')\n" -"... except binascii.Error:\n" -"... print('boo')\n" -"...\n" -"Traceback (most recent call last):\n" -" File \"\", line 2, in \n" -"binascii.Error: Non-hexadecimal digit found" -msgstr "" -">>> old_binascii.Error == binascii.Error\n" -"False\n" -">>> try:\n" -"... old_binascii.unhexlify(b'qwertyuiop')\n" -"... except binascii.Error:\n" -"... print('boo')\n" -"...\n" -"Traceback (most recent call last):\n" -" File \"\", line 2, in \n" -"binascii.Error: Non-hexadecimal digit found" - -#: ../../howto/isolating-extensions.rst:139 -msgid "" -"This is expected. Notice that pure-Python modules behave the same way: it is " -"a part of how Python works." -msgstr "" - -#: ../../howto/isolating-extensions.rst:142 -msgid "" -"The goal is to make extension modules safe at the C level, not to make hacks " -"behave intuitively. Mutating ``sys.modules`` \"manually\" counts as a hack." -msgstr "" - -#: ../../howto/isolating-extensions.rst:148 -msgid "Making Modules Safe with Multiple Interpreters" -msgstr "" - -#: ../../howto/isolating-extensions.rst:152 -msgid "Managing Global State" -msgstr "" - -#: ../../howto/isolating-extensions.rst:154 -msgid "" -"Sometimes, the state associated with a Python module is not specific to that " -"module, but to the entire process (or something else \"more global\" than a " -"module). For example:" -msgstr "" - -#: ../../howto/isolating-extensions.rst:158 -msgid "The ``readline`` module manages *the* terminal." -msgstr "" - -#: ../../howto/isolating-extensions.rst:159 -msgid "" -"A module running on a circuit board wants to control *the* on-board LED." -msgstr "" - -#: ../../howto/isolating-extensions.rst:162 -msgid "" -"In these cases, the Python module should provide *access* to the global " -"state, rather than *own* it. If possible, write the module so that multiple " -"copies of it can access the state independently (along with other libraries, " -"whether for Python or other languages). If that is not possible, consider " -"explicit locking." -msgstr "" - -#: ../../howto/isolating-extensions.rst:168 -msgid "" -"If it is necessary to use process-global state, the simplest way to avoid " -"issues with multiple interpreters is to explicitly prevent a module from " -"being loaded more than once per process—see :ref:`isolating-extensions-" -"optout`." -msgstr "" - -#: ../../howto/isolating-extensions.rst:175 -msgid "Managing Per-Module State" -msgstr "" - -#: ../../howto/isolating-extensions.rst:177 -msgid "" -"To use per-module state, use :ref:`multi-phase extension module " -"initialization `. This signals that your module " -"supports multiple interpreters correctly." -msgstr "" - -#: ../../howto/isolating-extensions.rst:181 -msgid "" -"Set ``PyModuleDef.m_size`` to a positive number to request that many bytes " -"of storage local to the module. Usually, this will be set to the size of " -"some module-specific ``struct``, which can store all of the module's C-level " -"state. In particular, it is where you should put pointers to classes " -"(including exceptions, but excluding static types) and settings (e.g. " -"``csv``'s :py:data:`~csv.field_size_limit`) which the C code needs to " -"function." -msgstr "" - -#: ../../howto/isolating-extensions.rst:190 -msgid "" -"Another option is to store state in the module's ``__dict__``, but you must " -"avoid crashing when users modify ``__dict__`` from Python code. This usually " -"means error- and type-checking at the C level, which is easy to get wrong " -"and hard to test sufficiently." -msgstr "" - -#: ../../howto/isolating-extensions.rst:195 -msgid "" -"However, if module state is not needed in C code, storing it in ``__dict__`` " -"only is a good idea." -msgstr "" - -#: ../../howto/isolating-extensions.rst:198 -msgid "" -"If the module state includes ``PyObject`` pointers, the module object must " -"hold references to those objects and implement the module-level hooks " -"``m_traverse``, ``m_clear`` and ``m_free``. These work like ``tp_traverse``, " -"``tp_clear`` and ``tp_free`` of a class. Adding them will require some work " -"and make the code longer; this is the price for modules which can be " -"unloaded cleanly." -msgstr "" - -#: ../../howto/isolating-extensions.rst:205 -msgid "" -"An example of a module with per-module state is currently available as " -"`xxlimited `__; example module initialization shown at the bottom of the file." -msgstr "" - -#: ../../howto/isolating-extensions.rst:213 -msgid "Opt-Out: Limiting to One Module Object per Process" -msgstr "" - -#: ../../howto/isolating-extensions.rst:215 -msgid "" -"A non-negative ``PyModuleDef.m_size`` signals that a module supports " -"multiple interpreters correctly. If this is not yet the case for your " -"module, you can explicitly make your module loadable only once per process. " -"For example::" -msgstr "" - -#: ../../howto/isolating-extensions.rst:220 -msgid "" -"// A process-wide flag\n" -"static int loaded = 0;\n" -"\n" -"// Mutex to provide thread safety (only needed for free-threaded Python)\n" -"static PyMutex modinit_mutex = {0};\n" -"\n" -"static int\n" -"exec_module(PyObject* module)\n" -"{\n" -" PyMutex_Lock(&modinit_mutex);\n" -" if (loaded) {\n" -" PyMutex_Unlock(&modinit_mutex);\n" -" PyErr_SetString(PyExc_ImportError,\n" -" \"cannot load module more than once per process\");\n" -" return -1;\n" -" }\n" -" loaded = 1;\n" -" PyMutex_Unlock(&modinit_mutex);\n" -" // ... rest of initialization\n" -"}" -msgstr "" - -#: ../../howto/isolating-extensions.rst:242 -msgid "" -"If your module's :c:member:`PyModuleDef.m_clear` function is able to prepare " -"for future re-initialization, it should clear the ``loaded`` flag. In this " -"case, your module won't support multiple instances existing *concurrently*, " -"but it will, for example, support being loaded after Python runtime shutdown " -"(:c:func:`Py_FinalizeEx`) and re-initialization (:c:func:`Py_Initialize`)." -msgstr "" - -#: ../../howto/isolating-extensions.rst:251 -msgid "Module State Access from Functions" -msgstr "" - -#: ../../howto/isolating-extensions.rst:253 -msgid "" -"Accessing the state from module-level functions is straightforward. " -"Functions get the module object as their first argument; for extracting the " -"state, you can use ``PyModule_GetState``::" -msgstr "" - -#: ../../howto/isolating-extensions.rst:257 -msgid "" -"static PyObject *\n" -"func(PyObject *module, PyObject *args)\n" -"{\n" -" my_struct *state = (my_struct*)PyModule_GetState(module);\n" -" if (state == NULL) {\n" -" return NULL;\n" -" }\n" -" // ... rest of logic\n" -"}" -msgstr "" - -#: ../../howto/isolating-extensions.rst:268 -msgid "" -"``PyModule_GetState`` may return ``NULL`` without setting an exception if " -"there is no module state, i.e. ``PyModuleDef.m_size`` was zero. In your own " -"module, you're in control of ``m_size``, so this is easy to prevent." -msgstr "" - -#: ../../howto/isolating-extensions.rst:275 -msgid "Heap Types" -msgstr "" - -#: ../../howto/isolating-extensions.rst:277 -msgid "" -"Traditionally, types defined in C code are *static*; that is, ``static " -"PyTypeObject`` structures defined directly in code and initialized using " -"``PyType_Ready()``." -msgstr "" - -#: ../../howto/isolating-extensions.rst:281 -msgid "" -"Such types are necessarily shared across the process. Sharing them between " -"module objects requires paying attention to any state they own or access. To " -"limit the possible issues, static types are immutable at the Python level: " -"for example, you can't set ``str.myattribute = 123``." -msgstr "" - -#: ../../howto/isolating-extensions.rst:287 -msgid "" -"Sharing truly immutable objects between interpreters is fine, as long as " -"they don't provide access to mutable objects. However, in CPython, every " -"Python object has a mutable implementation detail: the reference count. " -"Changes to the refcount are guarded by the GIL. Thus, code that shares any " -"Python objects across interpreters implicitly depends on CPython's current, " -"process-wide GIL." -msgstr "" - -#: ../../howto/isolating-extensions.rst:294 -msgid "" -"Because they are immutable and process-global, static types cannot access " -"\"their\" module state. If any method of such a type requires access to " -"module state, the type must be converted to a *heap-allocated type*, or " -"*heap type* for short. These correspond more closely to classes created by " -"Python's ``class`` statement." -msgstr "" - -#: ../../howto/isolating-extensions.rst:301 -msgid "For new modules, using heap types by default is a good rule of thumb." -msgstr "" - -#: ../../howto/isolating-extensions.rst:305 -msgid "Changing Static Types to Heap Types" -msgstr "" - -#: ../../howto/isolating-extensions.rst:307 -msgid "" -"Static types can be converted to heap types, but note that the heap type API " -"was not designed for \"lossless\" conversion from static types—that is, " -"creating a type that works exactly like a given static type. So, when " -"rewriting the class definition in a new API, you are likely to " -"unintentionally change a few details (e.g. pickleability or inherited " -"slots). Always test the details that are important to you." -msgstr "" - -#: ../../howto/isolating-extensions.rst:316 -msgid "" -"Watch out for the following two points in particular (but note that this is " -"not a comprehensive list):" -msgstr "" - -#: ../../howto/isolating-extensions.rst:319 -msgid "" -"Unlike static types, heap type objects are mutable by default. Use the :c:" -"macro:`Py_TPFLAGS_IMMUTABLETYPE` flag to prevent mutability." -msgstr "" - -#: ../../howto/isolating-extensions.rst:321 -msgid "" -"Heap types inherit :c:member:`~PyTypeObject.tp_new` by default, so it may " -"become possible to instantiate them from Python code. You can prevent this " -"with the :c:macro:`Py_TPFLAGS_DISALLOW_INSTANTIATION` flag." -msgstr "" - -#: ../../howto/isolating-extensions.rst:327 -msgid "Defining Heap Types" -msgstr "" - -#: ../../howto/isolating-extensions.rst:329 -msgid "" -"Heap types can be created by filling a :c:struct:`PyType_Spec` structure, a " -"description or \"blueprint\" of a class, and calling :c:func:" -"`PyType_FromModuleAndSpec` to construct a new class object." -msgstr "" - -#: ../../howto/isolating-extensions.rst:334 -msgid "" -"Other functions, like :c:func:`PyType_FromSpec`, can also create heap types, " -"but :c:func:`PyType_FromModuleAndSpec` associates the module with the class, " -"allowing access to the module state from methods." -msgstr "" - -#: ../../howto/isolating-extensions.rst:338 -msgid "" -"The class should generally be stored in *both* the module state (for safe " -"access from C) and the module's ``__dict__`` (for access from Python code)." -msgstr "" - -#: ../../howto/isolating-extensions.rst:344 -msgid "Garbage-Collection Protocol" -msgstr "" - -#: ../../howto/isolating-extensions.rst:346 -msgid "" -"Instances of heap types hold a reference to their type. This ensures that " -"the type isn't destroyed before all its instances are, but may result in " -"reference cycles that need to be broken by the garbage collector." -msgstr "" - -#: ../../howto/isolating-extensions.rst:351 -msgid "" -"To avoid memory leaks, instances of heap types must implement the garbage " -"collection protocol. That is, heap types should:" -msgstr "" - -#: ../../howto/isolating-extensions.rst:355 -msgid "Have the :c:macro:`Py_TPFLAGS_HAVE_GC` flag." -msgstr "" - -#: ../../howto/isolating-extensions.rst:356 -msgid "" -"Define a traverse function using :c:data:`Py_tp_traverse`, which visits the " -"type (e.g. using ``Py_VISIT(Py_TYPE(self))``)." -msgstr "" - -#: ../../howto/isolating-extensions.rst:359 -msgid "" -"Please refer to the documentation of :c:macro:`Py_TPFLAGS_HAVE_GC` and :c:" -"member:`~PyTypeObject.tp_traverse` for additional considerations." -msgstr "" - -#: ../../howto/isolating-extensions.rst:363 -msgid "" -"The API for defining heap types grew organically, leaving it somewhat " -"awkward to use in its current state. The following sections will guide you " -"through common issues." -msgstr "" - -#: ../../howto/isolating-extensions.rst:369 -msgid "``tp_traverse`` in Python 3.8 and lower" -msgstr "" - -#: ../../howto/isolating-extensions.rst:371 -msgid "" -"The requirement to visit the type from ``tp_traverse`` was added in Python " -"3.9. If you support Python 3.8 and lower, the traverse function must *not* " -"visit the type, so it must be more complicated::" -msgstr "" - -#: ../../howto/isolating-extensions.rst:375 -msgid "" -"static int my_traverse(PyObject *self, visitproc visit, void *arg)\n" -"{\n" -" if (Py_Version >= 0x03090000) {\n" -" Py_VISIT(Py_TYPE(self));\n" -" }\n" -" return 0;\n" -"}" -msgstr "" -"static int my_traverse(PyObject *self, visitproc visit, void *arg)\n" -"{\n" -" if (Py_Version >= 0x03090000) {\n" -" Py_VISIT(Py_TYPE(self));\n" -" }\n" -" return 0;\n" -"}" - -#: ../../howto/isolating-extensions.rst:383 -msgid "" -"Unfortunately, :c:data:`Py_Version` was only added in Python 3.11. As a " -"replacement, use:" -msgstr "" - -#: ../../howto/isolating-extensions.rst:386 -msgid ":c:macro:`PY_VERSION_HEX`, if not using the stable ABI, or" -msgstr "" - -#: ../../howto/isolating-extensions.rst:387 -msgid "" -":py:data:`sys.version_info` (via :c:func:`PySys_GetObject` and :c:func:" -"`PyArg_ParseTuple`)." -msgstr "" - -#: ../../howto/isolating-extensions.rst:392 -msgid "Delegating ``tp_traverse``" -msgstr "" - -#: ../../howto/isolating-extensions.rst:394 -msgid "" -"If your traverse function delegates to the :c:member:`~PyTypeObject." -"tp_traverse` of its base class (or another type), ensure that " -"``Py_TYPE(self)`` is visited only once. Note that only heap type are " -"expected to visit the type in ``tp_traverse``." -msgstr "" - -#: ../../howto/isolating-extensions.rst:399 -msgid "For example, if your traverse function includes::" -msgstr "" - -#: ../../howto/isolating-extensions.rst:401 -msgid "base->tp_traverse(self, visit, arg)" -msgstr "base->tp_traverse(self, visit, arg)" - -#: ../../howto/isolating-extensions.rst:403 -msgid "...and ``base`` may be a static type, then it should also include::" -msgstr "" - -#: ../../howto/isolating-extensions.rst:405 -msgid "" -"if (base->tp_flags & Py_TPFLAGS_HEAPTYPE) {\n" -" // a heap type's tp_traverse already visited Py_TYPE(self)\n" -"} else {\n" -" if (Py_Version >= 0x03090000) {\n" -" Py_VISIT(Py_TYPE(self));\n" -" }\n" -"}" -msgstr "" - -#: ../../howto/isolating-extensions.rst:413 -msgid "" -"It is not necessary to handle the type's reference count in :c:member:" -"`~PyTypeObject.tp_new` and :c:member:`~PyTypeObject.tp_clear`." -msgstr "" - -#: ../../howto/isolating-extensions.rst:418 -msgid "Defining ``tp_dealloc``" -msgstr "定義 ``tp_dealloc``" - -#: ../../howto/isolating-extensions.rst:420 -msgid "" -"If your type has a custom :c:member:`~PyTypeObject.tp_dealloc` function, it " -"needs to:" -msgstr "" - -#: ../../howto/isolating-extensions.rst:423 -msgid "" -"call :c:func:`PyObject_GC_UnTrack` before any fields are invalidated, and" -msgstr "" - -#: ../../howto/isolating-extensions.rst:424 -msgid "decrement the reference count of the type." -msgstr "" - -#: ../../howto/isolating-extensions.rst:426 -msgid "" -"To keep the type valid while ``tp_free`` is called, the type's refcount " -"needs to be decremented *after* the instance is deallocated. For example::" -msgstr "" - -#: ../../howto/isolating-extensions.rst:429 -msgid "" -"static void my_dealloc(PyObject *self)\n" -"{\n" -" PyObject_GC_UnTrack(self);\n" -" ...\n" -" PyTypeObject *type = Py_TYPE(self);\n" -" type->tp_free(self);\n" -" Py_DECREF(type);\n" -"}" -msgstr "" -"static void my_dealloc(PyObject *self)\n" -"{\n" -" PyObject_GC_UnTrack(self);\n" -" ...\n" -" PyTypeObject *type = Py_TYPE(self);\n" -" type->tp_free(self);\n" -" Py_DECREF(type);\n" -"}" - -#: ../../howto/isolating-extensions.rst:438 -msgid "" -"The default ``tp_dealloc`` function does this, so if your type does *not* " -"override ``tp_dealloc`` you don't need to add it." -msgstr "" - -#: ../../howto/isolating-extensions.rst:444 -msgid "Not overriding ``tp_free``" -msgstr "" - -#: ../../howto/isolating-extensions.rst:446 -msgid "" -"The :c:member:`~PyTypeObject.tp_free` slot of a heap type must be set to :c:" -"func:`PyObject_GC_Del`. This is the default; do not override it." -msgstr "" - -#: ../../howto/isolating-extensions.rst:452 -msgid "Avoiding ``PyObject_New``" -msgstr "避免使用 ``PyObject_New``" - -#: ../../howto/isolating-extensions.rst:454 -msgid "GC-tracked objects need to be allocated using GC-aware functions." -msgstr "" - -#: ../../howto/isolating-extensions.rst:456 -msgid "If you use :c:func:`PyObject_New` or :c:func:`PyObject_NewVar`:" -msgstr "" - -#: ../../howto/isolating-extensions.rst:458 -msgid "" -"Get and call type's :c:member:`~PyTypeObject.tp_alloc` slot, if possible. " -"That is, replace ``TYPE *o = PyObject_New(TYPE, typeobj)`` with::" -msgstr "" - -#: ../../howto/isolating-extensions.rst:461 -msgid "TYPE *o = typeobj->tp_alloc(typeobj, 0);" -msgstr "TYPE *o = typeobj->tp_alloc(typeobj, 0);" - -#: ../../howto/isolating-extensions.rst:463 -msgid "" -"Replace ``o = PyObject_NewVar(TYPE, typeobj, size)`` with the same, but use " -"size instead of the 0." -msgstr "" - -#: ../../howto/isolating-extensions.rst:466 -msgid "" -"If the above is not possible (e.g. inside a custom ``tp_alloc``), call :c:" -"func:`PyObject_GC_New` or :c:func:`PyObject_GC_NewVar`::" -msgstr "" - -#: ../../howto/isolating-extensions.rst:469 -msgid "" -"TYPE *o = PyObject_GC_New(TYPE, typeobj);\n" -"\n" -"TYPE *o = PyObject_GC_NewVar(TYPE, typeobj, size);" -msgstr "" -"TYPE *o = PyObject_GC_New(TYPE, typeobj);\n" -"\n" -"TYPE *o = PyObject_GC_NewVar(TYPE, typeobj, size);" - -#: ../../howto/isolating-extensions.rst:475 -msgid "Module State Access from Classes" -msgstr "" - -#: ../../howto/isolating-extensions.rst:477 -msgid "" -"If you have a type object defined with :c:func:`PyType_FromModuleAndSpec`, " -"you can call :c:func:`PyType_GetModule` to get the associated module, and " -"then :c:func:`PyModule_GetState` to get the module's state." -msgstr "" - -#: ../../howto/isolating-extensions.rst:481 -msgid "" -"To save a some tedious error-handling boilerplate code, you can combine " -"these two steps with :c:func:`PyType_GetModuleState`, resulting in::" -msgstr "" - -#: ../../howto/isolating-extensions.rst:484 -msgid "" -"my_struct *state = (my_struct*)PyType_GetModuleState(type);\n" -"if (state == NULL) {\n" -" return NULL;\n" -"}" -msgstr "" -"my_struct *state = (my_struct*)PyType_GetModuleState(type);\n" -"if (state == NULL) {\n" -" return NULL;\n" -"}" - -#: ../../howto/isolating-extensions.rst:491 -msgid "Module State Access from Regular Methods" -msgstr "" - -#: ../../howto/isolating-extensions.rst:493 -msgid "" -"Accessing the module-level state from methods of a class is somewhat more " -"complicated, but is possible thanks to API introduced in Python 3.9. To get " -"the state, you need to first get the *defining class*, and then get the " -"module state from it." -msgstr "" - -#: ../../howto/isolating-extensions.rst:498 -msgid "" -"The largest roadblock is getting *the class a method was defined in*, or " -"that method's \"defining class\" for short. The defining class can have a " -"reference to the module it is part of." -msgstr "" - -#: ../../howto/isolating-extensions.rst:502 -msgid "" -"Do not confuse the defining class with ``Py_TYPE(self)``. If the method is " -"called on a *subclass* of your type, ``Py_TYPE(self)`` will refer to that " -"subclass, which may be defined in different module than yours." -msgstr "" - -#: ../../howto/isolating-extensions.rst:507 -msgid "" -"The following Python code can illustrate the concept. ``Base." -"get_defining_class`` returns ``Base`` even if ``type(self) == Sub``:" -msgstr "" - -#: ../../howto/isolating-extensions.rst:511 -msgid "" -"class Base:\n" -" def get_type_of_self(self):\n" -" return type(self)\n" -"\n" -" def get_defining_class(self):\n" -" return __class__\n" -"\n" -"class Sub(Base):\n" -" pass" -msgstr "" -"class Base:\n" -" def get_type_of_self(self):\n" -" return type(self)\n" -"\n" -" def get_defining_class(self):\n" -" return __class__\n" -"\n" -"class Sub(Base):\n" -" pass" - -#: ../../howto/isolating-extensions.rst:523 -msgid "" -"For a method to get its \"defining class\", it must use the :ref:" -"`METH_METHOD | METH_FASTCALL | METH_KEYWORDS ` :c:type:`calling convention ` and the " -"corresponding :c:type:`PyCMethod` signature::" -msgstr "" - -#: ../../howto/isolating-extensions.rst:528 -msgid "" -"PyObject *PyCMethod(\n" -" PyObject *self, // object the method was called on\n" -" PyTypeObject *defining_class, // defining class\n" -" PyObject *const *args, // C array of arguments\n" -" Py_ssize_t nargs, // length of \"args\"\n" -" PyObject *kwnames) // NULL, or dict of keyword arguments" -msgstr "" - -#: ../../howto/isolating-extensions.rst:535 -msgid "" -"Once you have the defining class, call :c:func:`PyType_GetModuleState` to " -"get the state of its associated module." -msgstr "" - -#: ../../howto/isolating-extensions.rst:538 -msgid "For example::" -msgstr "舉例來說： ::" - -#: ../../howto/isolating-extensions.rst:540 -msgid "" -"static PyObject *\n" -"example_method(PyObject *self,\n" -" PyTypeObject *defining_class,\n" -" PyObject *const *args,\n" -" Py_ssize_t nargs,\n" -" PyObject *kwnames)\n" -"{\n" -" my_struct *state = (my_struct*)PyType_GetModuleState(defining_class);\n" -" if (state == NULL) {\n" -" return NULL;\n" -" }\n" -" ... // rest of logic\n" -"}\n" -"\n" -"PyDoc_STRVAR(example_method_doc, \"...\");\n" -"\n" -"static PyMethodDef my_methods[] = {\n" -" {\"example_method\",\n" -" (PyCFunction)(void(*)(void))example_method,\n" -" METH_METHOD|METH_FASTCALL|METH_KEYWORDS,\n" -" example_method_doc}\n" -" {NULL},\n" -"}" -msgstr "" - -#: ../../howto/isolating-extensions.rst:566 -msgid "Module State Access from Slot Methods, Getters and Setters" -msgstr "" - -#: ../../howto/isolating-extensions.rst:570 -msgid "This is new in Python 3.11." -msgstr "" - -#: ../../howto/isolating-extensions.rst:578 -msgid "" -"Slot methods—the fast C equivalents for special methods, such as :c:member:" -"`~PyNumberMethods.nb_add` for :py:attr:`~object.__add__` or :c:member:" -"`~PyTypeObject.tp_new` for initialization—have a very simple API that " -"doesn't allow passing in the defining class, unlike with :c:type:" -"`PyCMethod`. The same goes for getters and setters defined with :c:type:" -"`PyGetSetDef`." -msgstr "" - -#: ../../howto/isolating-extensions.rst:585 -msgid "" -"To access the module state in these cases, use the :c:func:" -"`PyType_GetModuleByDef` function, and pass in the module definition. Once " -"you have the module, call :c:func:`PyModule_GetState` to get the state::" -msgstr "" - -#: ../../howto/isolating-extensions.rst:590 -msgid "" -"PyObject *module = PyType_GetModuleByDef(Py_TYPE(self), &module_def);\n" -"my_struct *state = (my_struct*)PyModule_GetState(module);\n" -"if (state == NULL) {\n" -" return NULL;\n" -"}" -msgstr "" - -#: ../../howto/isolating-extensions.rst:596 -msgid "" -":c:func:`!PyType_GetModuleByDef` works by searching the :term:`method " -"resolution order` (i.e. all superclasses) for the first superclass that has " -"a corresponding module." -msgstr "" - -#: ../../howto/isolating-extensions.rst:602 -msgid "" -"In very exotic cases (inheritance chains spanning multiple modules created " -"from the same definition), :c:func:`!PyType_GetModuleByDef` might not return " -"the module of the true defining class. However, it will always return a " -"module with the same definition, ensuring a compatible C memory layout." -msgstr "" - -#: ../../howto/isolating-extensions.rst:610 -msgid "Lifetime of the Module State" -msgstr "" - -#: ../../howto/isolating-extensions.rst:612 -msgid "" -"When a module object is garbage-collected, its module state is freed. For " -"each pointer to (a part of) the module state, you must hold a reference to " -"the module object." -msgstr "" - -#: ../../howto/isolating-extensions.rst:616 -msgid "" -"Usually this is not an issue, because types created with :c:func:" -"`PyType_FromModuleAndSpec`, and their instances, hold a reference to the " -"module. However, you must be careful in reference counting when you " -"reference module state from other places, such as callbacks for external " -"libraries." -msgstr "" - -#: ../../howto/isolating-extensions.rst:625 -msgid "Open Issues" -msgstr "" - -#: ../../howto/isolating-extensions.rst:627 -msgid "Several issues around per-module state and heap types are still open." -msgstr "" - -#: ../../howto/isolating-extensions.rst:629 -msgid "" -"Discussions about improving the situation are best held on the `discuss " -"forum under c-api tag `__." -msgstr "" - -#: ../../howto/isolating-extensions.rst:633 -msgid "Per-Class Scope" -msgstr "" - -#: ../../howto/isolating-extensions.rst:635 -msgid "" -"It is currently (as of Python 3.11) not possible to attach state to " -"individual *types* without relying on CPython implementation details (which " -"may change in the future—perhaps, ironically, to allow a proper solution for " -"per-class scope)." -msgstr "" - -#: ../../howto/isolating-extensions.rst:642 -msgid "Lossless Conversion to Heap Types" -msgstr "" - -#: ../../howto/isolating-extensions.rst:644 -msgid "" -"The heap type API was not designed for \"lossless\" conversion from static " -"types; that is, creating a type that works exactly like a given static type." -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-12-01 00:17+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \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" + +#: ../../howto/isolating-extensions.rst:7 +msgid "Isolating Extension Modules" +msgstr "隔離擴充模組" + +#: ../../howto/isolating-extensions.rst:9 +msgid "Abstract" +msgstr "摘要" + +#: ../../howto/isolating-extensions.rst:11 +msgid "" +"Traditionally, state belonging to Python extension modules was kept in C " +"``static`` variables, which have process-wide scope. This document describes " +"problems of such per-process state and shows a safer way: per-module state." +msgstr "" + +#: ../../howto/isolating-extensions.rst:16 +msgid "" +"The document also describes how to switch to per-module state where " +"possible. This transition involves allocating space for that state, " +"potentially switching from static types to heap types, and—perhaps most " +"importantly—accessing per-module state from code." +msgstr "" + +#: ../../howto/isolating-extensions.rst:23 +msgid "Who should read this" +msgstr "" + +#: ../../howto/isolating-extensions.rst:25 +msgid "" +"This guide is written for maintainers of :ref:`C-API ` " +"extensions who would like to make that extension safer to use in " +"applications where Python itself is used as a library." +msgstr "" + +#: ../../howto/isolating-extensions.rst:31 +msgid "Background" +msgstr "背景" + +#: ../../howto/isolating-extensions.rst:33 +msgid "" +"An *interpreter* is the context in which Python code runs. It contains " +"configuration (e.g. the import path) and runtime state (e.g. the set of " +"imported modules)." +msgstr "" + +#: ../../howto/isolating-extensions.rst:37 +msgid "" +"Python supports running multiple interpreters in one process. There are two " +"cases to think about—users may run interpreters:" +msgstr "" + +#: ../../howto/isolating-extensions.rst:40 +msgid "" +"in sequence, with several :c:func:`Py_InitializeEx`/:c:func:`Py_FinalizeEx` " +"cycles, and" +msgstr "" + +#: ../../howto/isolating-extensions.rst:42 +msgid "" +"in parallel, managing \"sub-interpreters\" using :c:func:" +"`Py_NewInterpreter`/:c:func:`Py_EndInterpreter`." +msgstr "" + +#: ../../howto/isolating-extensions.rst:45 +msgid "" +"Both cases (and combinations of them) would be most useful when embedding " +"Python within a library. Libraries generally shouldn't make assumptions " +"about the application that uses them, which include assuming a process-wide " +"\"main Python interpreter\"." +msgstr "" + +#: ../../howto/isolating-extensions.rst:50 +msgid "" +"Historically, Python extension modules don't handle this use case well. Many " +"extension modules (and even some stdlib modules) use *per-process* global " +"state, because C ``static`` variables are extremely easy to use. Thus, data " +"that should be specific to an interpreter ends up being shared between " +"interpreters. Unless the extension developer is careful, it is very easy to " +"introduce edge cases that lead to crashes when a module is loaded in more " +"than one interpreter in the same process." +msgstr "" + +#: ../../howto/isolating-extensions.rst:58 +msgid "" +"Unfortunately, *per-interpreter* state is not easy to achieve. Extension " +"authors tend to not keep multiple interpreters in mind when developing, and " +"it is currently cumbersome to test the behavior." +msgstr "" + +#: ../../howto/isolating-extensions.rst:63 +msgid "Enter Per-Module State" +msgstr "" + +#: ../../howto/isolating-extensions.rst:65 +msgid "" +"Instead of focusing on per-interpreter state, Python's C API is evolving to " +"better support the more granular *per-module* state. This means that C-level " +"data should be attached to a *module object*. Each interpreter creates its " +"own module object, keeping the data separate. For testing the isolation, " +"multiple module objects corresponding to a single extension can even be " +"loaded in a single interpreter." +msgstr "" + +#: ../../howto/isolating-extensions.rst:72 +msgid "" +"Per-module state provides an easy way to think about lifetime and resource " +"ownership: the extension module will initialize when a module object is " +"created, and clean up when it's freed. In this regard, a module is just like " +"any other :c:expr:`PyObject *`; there are no \"on interpreter shutdown\" " +"hooks to think—or forget—about." +msgstr "" + +#: ../../howto/isolating-extensions.rst:78 +msgid "" +"Note that there are use cases for different kinds of \"globals\": per-" +"process, per-interpreter, per-thread or per-task state. With per-module " +"state as the default, these are still possible, but you should treat them as " +"exceptional cases: if you need them, you should give them additional care " +"and testing. (Note that this guide does not cover them.)" +msgstr "" + +#: ../../howto/isolating-extensions.rst:87 +msgid "Isolated Module Objects" +msgstr "" + +#: ../../howto/isolating-extensions.rst:89 +msgid "" +"The key point to keep in mind when developing an extension module is that " +"several module objects can be created from a single shared library. For " +"example:" +msgstr "" + +#: ../../howto/isolating-extensions.rst:93 +msgid "" +">>> import sys\n" +">>> import binascii\n" +">>> old_binascii = binascii\n" +">>> del sys.modules['binascii']\n" +">>> import binascii # create a new module object\n" +">>> old_binascii == binascii\n" +"False" +msgstr "" +">>> import sys\n" +">>> import binascii\n" +">>> old_binascii = binascii\n" +">>> del sys.modules['binascii']\n" +">>> import binascii # 建立一個新的模組物件\n" +">>> old_binascii == binascii\n" +"False" + +#: ../../howto/isolating-extensions.rst:103 +msgid "" +"As a rule of thumb, the two modules should be completely independent. All " +"objects and state specific to the module should be encapsulated within the " +"module object, not shared with other module objects, and cleaned up when the " +"module object is deallocated. Since this just is a rule of thumb, exceptions " +"are possible (see `Managing Global State`_), but they will need more thought " +"and attention to edge cases." +msgstr "" + +#: ../../howto/isolating-extensions.rst:111 +msgid "" +"While some modules could do with less stringent restrictions, isolated " +"modules make it easier to set clear expectations and guidelines that work " +"across a variety of use cases." +msgstr "" + +#: ../../howto/isolating-extensions.rst:117 +msgid "Surprising Edge Cases" +msgstr "" + +#: ../../howto/isolating-extensions.rst:119 +msgid "" +"Note that isolated modules do create some surprising edge cases. Most " +"notably, each module object will typically not share its classes and " +"exceptions with other similar modules. Continuing from the `example above " +"`__, note that ``old_binascii.Error`` and " +"``binascii.Error`` are separate objects. In the following code, the " +"exception is *not* caught:" +msgstr "" + +#: ../../howto/isolating-extensions.rst:126 +msgid "" +">>> old_binascii.Error == binascii.Error\n" +"False\n" +">>> try:\n" +"... old_binascii.unhexlify(b'qwertyuiop')\n" +"... except binascii.Error:\n" +"... print('boo')\n" +"...\n" +"Traceback (most recent call last):\n" +" File \"\", line 2, in \n" +"binascii.Error: Non-hexadecimal digit found" +msgstr "" +">>> old_binascii.Error == binascii.Error\n" +"False\n" +">>> try:\n" +"... old_binascii.unhexlify(b'qwertyuiop')\n" +"... except binascii.Error:\n" +"... print('boo')\n" +"...\n" +"Traceback (most recent call last):\n" +" File \"\", line 2, in \n" +"binascii.Error: Non-hexadecimal digit found" + +#: ../../howto/isolating-extensions.rst:139 +msgid "" +"This is expected. Notice that pure-Python modules behave the same way: it is " +"a part of how Python works." +msgstr "" + +#: ../../howto/isolating-extensions.rst:142 +msgid "" +"The goal is to make extension modules safe at the C level, not to make hacks " +"behave intuitively. Mutating ``sys.modules`` \"manually\" counts as a hack." +msgstr "" + +#: ../../howto/isolating-extensions.rst:148 +msgid "Making Modules Safe with Multiple Interpreters" +msgstr "" + +#: ../../howto/isolating-extensions.rst:152 +msgid "Managing Global State" +msgstr "" + +#: ../../howto/isolating-extensions.rst:154 +msgid "" +"Sometimes, the state associated with a Python module is not specific to that " +"module, but to the entire process (or something else \"more global\" than a " +"module). For example:" +msgstr "" + +#: ../../howto/isolating-extensions.rst:158 +msgid "The ``readline`` module manages *the* terminal." +msgstr "" + +#: ../../howto/isolating-extensions.rst:159 +msgid "" +"A module running on a circuit board wants to control *the* on-board LED." +msgstr "" + +#: ../../howto/isolating-extensions.rst:162 +msgid "" +"In these cases, the Python module should provide *access* to the global " +"state, rather than *own* it. If possible, write the module so that multiple " +"copies of it can access the state independently (along with other libraries, " +"whether for Python or other languages). If that is not possible, consider " +"explicit locking." +msgstr "" + +#: ../../howto/isolating-extensions.rst:168 +msgid "" +"If it is necessary to use process-global state, the simplest way to avoid " +"issues with multiple interpreters is to explicitly prevent a module from " +"being loaded more than once per process—see :ref:`isolating-extensions-" +"optout`." +msgstr "" + +#: ../../howto/isolating-extensions.rst:175 +msgid "Managing Per-Module State" +msgstr "" + +#: ../../howto/isolating-extensions.rst:177 +msgid "" +"To use per-module state, use :ref:`multi-phase extension module " +"initialization `. This signals that your module " +"supports multiple interpreters correctly." +msgstr "" + +#: ../../howto/isolating-extensions.rst:181 +msgid "" +"Set ``PyModuleDef.m_size`` to a positive number to request that many bytes " +"of storage local to the module. Usually, this will be set to the size of " +"some module-specific ``struct``, which can store all of the module's C-level " +"state. In particular, it is where you should put pointers to classes " +"(including exceptions, but excluding static types) and settings (e.g. " +"``csv``'s :py:data:`~csv.field_size_limit`) which the C code needs to " +"function." +msgstr "" + +#: ../../howto/isolating-extensions.rst:190 +msgid "" +"Another option is to store state in the module's ``__dict__``, but you must " +"avoid crashing when users modify ``__dict__`` from Python code. This usually " +"means error- and type-checking at the C level, which is easy to get wrong " +"and hard to test sufficiently." +msgstr "" + +#: ../../howto/isolating-extensions.rst:195 +msgid "" +"However, if module state is not needed in C code, storing it in ``__dict__`` " +"only is a good idea." +msgstr "" + +#: ../../howto/isolating-extensions.rst:198 +msgid "" +"If the module state includes ``PyObject`` pointers, the module object must " +"hold references to those objects and implement the module-level hooks " +"``m_traverse``, ``m_clear`` and ``m_free``. These work like ``tp_traverse``, " +"``tp_clear`` and ``tp_free`` of a class. Adding them will require some work " +"and make the code longer; this is the price for modules which can be " +"unloaded cleanly." +msgstr "" + +#: ../../howto/isolating-extensions.rst:205 +msgid "" +"An example of a module with per-module state is currently available as " +"`xxlimited `__; example module initialization shown at the bottom of the file." +msgstr "" + +#: ../../howto/isolating-extensions.rst:213 +msgid "Opt-Out: Limiting to One Module Object per Process" +msgstr "" + +#: ../../howto/isolating-extensions.rst:215 +msgid "" +"A non-negative ``PyModuleDef.m_size`` signals that a module supports " +"multiple interpreters correctly. If this is not yet the case for your " +"module, you can explicitly make your module loadable only once per process. " +"For example::" +msgstr "" + +#: ../../howto/isolating-extensions.rst:220 +msgid "" +"// A process-wide flag\n" +"static int loaded = 0;\n" +"\n" +"// Mutex to provide thread safety (only needed for free-threaded Python)\n" +"static PyMutex modinit_mutex = {0};\n" +"\n" +"static int\n" +"exec_module(PyObject* module)\n" +"{\n" +" PyMutex_Lock(&modinit_mutex);\n" +" if (loaded) {\n" +" PyMutex_Unlock(&modinit_mutex);\n" +" PyErr_SetString(PyExc_ImportError,\n" +" \"cannot load module more than once per process\");\n" +" return -1;\n" +" }\n" +" loaded = 1;\n" +" PyMutex_Unlock(&modinit_mutex);\n" +" // ... rest of initialization\n" +"}" +msgstr "" + +#: ../../howto/isolating-extensions.rst:242 +msgid "" +"If your module's :c:member:`PyModuleDef.m_clear` function is able to prepare " +"for future re-initialization, it should clear the ``loaded`` flag. In this " +"case, your module won't support multiple instances existing *concurrently*, " +"but it will, for example, support being loaded after Python runtime shutdown " +"(:c:func:`Py_FinalizeEx`) and re-initialization (:c:func:`Py_Initialize`)." +msgstr "" + +#: ../../howto/isolating-extensions.rst:251 +msgid "Module State Access from Functions" +msgstr "" + +#: ../../howto/isolating-extensions.rst:253 +msgid "" +"Accessing the state from module-level functions is straightforward. " +"Functions get the module object as their first argument; for extracting the " +"state, you can use ``PyModule_GetState``::" +msgstr "" + +#: ../../howto/isolating-extensions.rst:257 +msgid "" +"static PyObject *\n" +"func(PyObject *module, PyObject *args)\n" +"{\n" +" my_struct *state = (my_struct*)PyModule_GetState(module);\n" +" if (state == NULL) {\n" +" return NULL;\n" +" }\n" +" // ... rest of logic\n" +"}" +msgstr "" + +#: ../../howto/isolating-extensions.rst:268 +msgid "" +"``PyModule_GetState`` may return ``NULL`` without setting an exception if " +"there is no module state, i.e. ``PyModuleDef.m_size`` was zero. In your own " +"module, you're in control of ``m_size``, so this is easy to prevent." +msgstr "" + +#: ../../howto/isolating-extensions.rst:275 +msgid "Heap Types" +msgstr "" + +#: ../../howto/isolating-extensions.rst:277 +msgid "" +"Traditionally, types defined in C code are *static*; that is, ``static " +"PyTypeObject`` structures defined directly in code and initialized using " +"``PyType_Ready()``." +msgstr "" + +#: ../../howto/isolating-extensions.rst:281 +msgid "" +"Such types are necessarily shared across the process. Sharing them between " +"module objects requires paying attention to any state they own or access. To " +"limit the possible issues, static types are immutable at the Python level: " +"for example, you can't set ``str.myattribute = 123``." +msgstr "" + +#: ../../howto/isolating-extensions.rst:287 +msgid "" +"Sharing truly immutable objects between interpreters is fine, as long as " +"they don't provide access to mutable objects. However, in CPython, every " +"Python object has a mutable implementation detail: the reference count. " +"Changes to the refcount are guarded by the GIL. Thus, code that shares any " +"Python objects across interpreters implicitly depends on CPython's current, " +"process-wide GIL." +msgstr "" + +#: ../../howto/isolating-extensions.rst:294 +msgid "" +"Because they are immutable and process-global, static types cannot access " +"\"their\" module state. If any method of such a type requires access to " +"module state, the type must be converted to a *heap-allocated type*, or " +"*heap type* for short. These correspond more closely to classes created by " +"Python's ``class`` statement." +msgstr "" + +#: ../../howto/isolating-extensions.rst:301 +msgid "For new modules, using heap types by default is a good rule of thumb." +msgstr "" + +#: ../../howto/isolating-extensions.rst:305 +msgid "Changing Static Types to Heap Types" +msgstr "" + +#: ../../howto/isolating-extensions.rst:307 +msgid "" +"Static types can be converted to heap types, but note that the heap type API " +"was not designed for \"lossless\" conversion from static types—that is, " +"creating a type that works exactly like a given static type. So, when " +"rewriting the class definition in a new API, you are likely to " +"unintentionally change a few details (e.g. pickleability or inherited " +"slots). Always test the details that are important to you." +msgstr "" + +#: ../../howto/isolating-extensions.rst:316 +msgid "" +"Watch out for the following two points in particular (but note that this is " +"not a comprehensive list):" +msgstr "" + +#: ../../howto/isolating-extensions.rst:319 +msgid "" +"Unlike static types, heap type objects are mutable by default. Use the :c:" +"macro:`Py_TPFLAGS_IMMUTABLETYPE` flag to prevent mutability." +msgstr "" + +#: ../../howto/isolating-extensions.rst:321 +msgid "" +"Heap types inherit :c:member:`~PyTypeObject.tp_new` by default, so it may " +"become possible to instantiate them from Python code. You can prevent this " +"with the :c:macro:`Py_TPFLAGS_DISALLOW_INSTANTIATION` flag." +msgstr "" + +#: ../../howto/isolating-extensions.rst:327 +msgid "Defining Heap Types" +msgstr "" + +#: ../../howto/isolating-extensions.rst:329 +msgid "" +"Heap types can be created by filling a :c:struct:`PyType_Spec` structure, a " +"description or \"blueprint\" of a class, and calling :c:func:" +"`PyType_FromModuleAndSpec` to construct a new class object." +msgstr "" + +#: ../../howto/isolating-extensions.rst:334 +msgid "" +"Other functions, like :c:func:`PyType_FromSpec`, can also create heap types, " +"but :c:func:`PyType_FromModuleAndSpec` associates the module with the class, " +"allowing access to the module state from methods." +msgstr "" + +#: ../../howto/isolating-extensions.rst:338 +msgid "" +"The class should generally be stored in *both* the module state (for safe " +"access from C) and the module's ``__dict__`` (for access from Python code)." +msgstr "" + +#: ../../howto/isolating-extensions.rst:344 +msgid "Garbage-Collection Protocol" +msgstr "" + +#: ../../howto/isolating-extensions.rst:346 +msgid "" +"Instances of heap types hold a reference to their type. This ensures that " +"the type isn't destroyed before all its instances are, but may result in " +"reference cycles that need to be broken by the garbage collector." +msgstr "" + +#: ../../howto/isolating-extensions.rst:351 +msgid "" +"To avoid memory leaks, instances of heap types must implement the garbage " +"collection protocol. That is, heap types should:" +msgstr "" + +#: ../../howto/isolating-extensions.rst:355 +msgid "Have the :c:macro:`Py_TPFLAGS_HAVE_GC` flag." +msgstr "" + +#: ../../howto/isolating-extensions.rst:356 +msgid "" +"Define a traverse function using :c:data:`Py_tp_traverse`, which visits the " +"type (e.g. using ``Py_VISIT(Py_TYPE(self))``)." +msgstr "" + +#: ../../howto/isolating-extensions.rst:359 +msgid "" +"Please refer to the documentation of :c:macro:`Py_TPFLAGS_HAVE_GC` and :c:" +"member:`~PyTypeObject.tp_traverse` for additional considerations." +msgstr "" + +#: ../../howto/isolating-extensions.rst:363 +msgid "" +"The API for defining heap types grew organically, leaving it somewhat " +"awkward to use in its current state. The following sections will guide you " +"through common issues." +msgstr "" + +#: ../../howto/isolating-extensions.rst:369 +msgid "``tp_traverse`` in Python 3.8 and lower" +msgstr "" + +#: ../../howto/isolating-extensions.rst:371 +msgid "" +"The requirement to visit the type from ``tp_traverse`` was added in Python " +"3.9. If you support Python 3.8 and lower, the traverse function must *not* " +"visit the type, so it must be more complicated::" +msgstr "" + +#: ../../howto/isolating-extensions.rst:375 +msgid "" +"static int my_traverse(PyObject *self, visitproc visit, void *arg)\n" +"{\n" +" if (Py_Version >= 0x03090000) {\n" +" Py_VISIT(Py_TYPE(self));\n" +" }\n" +" return 0;\n" +"}" +msgstr "" +"static int my_traverse(PyObject *self, visitproc visit, void *arg)\n" +"{\n" +" if (Py_Version >= 0x03090000) {\n" +" Py_VISIT(Py_TYPE(self));\n" +" }\n" +" return 0;\n" +"}" + +#: ../../howto/isolating-extensions.rst:383 +msgid "" +"Unfortunately, :c:data:`Py_Version` was only added in Python 3.11. As a " +"replacement, use:" +msgstr "" + +#: ../../howto/isolating-extensions.rst:386 +msgid ":c:macro:`PY_VERSION_HEX`, if not using the stable ABI, or" +msgstr "" + +#: ../../howto/isolating-extensions.rst:387 +msgid "" +":py:data:`sys.version_info` (via :c:func:`PySys_GetObject` and :c:func:" +"`PyArg_ParseTuple`)." +msgstr "" + +#: ../../howto/isolating-extensions.rst:392 +msgid "Delegating ``tp_traverse``" +msgstr "" + +#: ../../howto/isolating-extensions.rst:394 +msgid "" +"If your traverse function delegates to the :c:member:`~PyTypeObject." +"tp_traverse` of its base class (or another type), ensure that " +"``Py_TYPE(self)`` is visited only once. Note that only heap type are " +"expected to visit the type in ``tp_traverse``." +msgstr "" + +#: ../../howto/isolating-extensions.rst:399 +msgid "For example, if your traverse function includes::" +msgstr "" + +#: ../../howto/isolating-extensions.rst:401 +msgid "base->tp_traverse(self, visit, arg)" +msgstr "base->tp_traverse(self, visit, arg)" + +#: ../../howto/isolating-extensions.rst:403 +msgid "...and ``base`` may be a static type, then it should also include::" +msgstr "" + +#: ../../howto/isolating-extensions.rst:405 +msgid "" +"if (base->tp_flags & Py_TPFLAGS_HEAPTYPE) {\n" +" // a heap type's tp_traverse already visited Py_TYPE(self)\n" +"} else {\n" +" if (Py_Version >= 0x03090000) {\n" +" Py_VISIT(Py_TYPE(self));\n" +" }\n" +"}" +msgstr "" + +#: ../../howto/isolating-extensions.rst:413 +msgid "" +"It is not necessary to handle the type's reference count in :c:member:" +"`~PyTypeObject.tp_new` and :c:member:`~PyTypeObject.tp_clear`." +msgstr "" + +#: ../../howto/isolating-extensions.rst:418 +msgid "Defining ``tp_dealloc``" +msgstr "定義 ``tp_dealloc``" + +#: ../../howto/isolating-extensions.rst:420 +msgid "" +"If your type has a custom :c:member:`~PyTypeObject.tp_dealloc` function, it " +"needs to:" +msgstr "" + +#: ../../howto/isolating-extensions.rst:423 +msgid "" +"call :c:func:`PyObject_GC_UnTrack` before any fields are invalidated, and" +msgstr "" + +#: ../../howto/isolating-extensions.rst:424 +msgid "decrement the reference count of the type." +msgstr "" + +#: ../../howto/isolating-extensions.rst:426 +msgid "" +"To keep the type valid while ``tp_free`` is called, the type's refcount " +"needs to be decremented *after* the instance is deallocated. For example::" +msgstr "" + +#: ../../howto/isolating-extensions.rst:429 +msgid "" +"static void my_dealloc(PyObject *self)\n" +"{\n" +" PyObject_GC_UnTrack(self);\n" +" ...\n" +" PyTypeObject *type = Py_TYPE(self);\n" +" type->tp_free(self);\n" +" Py_DECREF(type);\n" +"}" +msgstr "" +"static void my_dealloc(PyObject *self)\n" +"{\n" +" PyObject_GC_UnTrack(self);\n" +" ...\n" +" PyTypeObject *type = Py_TYPE(self);\n" +" type->tp_free(self);\n" +" Py_DECREF(type);\n" +"}" + +#: ../../howto/isolating-extensions.rst:438 +msgid "" +"The default ``tp_dealloc`` function does this, so if your type does *not* " +"override ``tp_dealloc`` you don't need to add it." +msgstr "" + +#: ../../howto/isolating-extensions.rst:444 +msgid "Not overriding ``tp_free``" +msgstr "" + +#: ../../howto/isolating-extensions.rst:446 +msgid "" +"The :c:member:`~PyTypeObject.tp_free` slot of a heap type must be set to :c:" +"func:`PyObject_GC_Del`. This is the default; do not override it." +msgstr "" + +#: ../../howto/isolating-extensions.rst:452 +msgid "Avoiding ``PyObject_New``" +msgstr "避免使用 ``PyObject_New``" + +#: ../../howto/isolating-extensions.rst:454 +msgid "GC-tracked objects need to be allocated using GC-aware functions." +msgstr "" + +#: ../../howto/isolating-extensions.rst:456 +msgid "If you use :c:func:`PyObject_New` or :c:func:`PyObject_NewVar`:" +msgstr "" + +#: ../../howto/isolating-extensions.rst:458 +msgid "" +"Get and call type's :c:member:`~PyTypeObject.tp_alloc` slot, if possible. " +"That is, replace ``TYPE *o = PyObject_New(TYPE, typeobj)`` with::" +msgstr "" + +#: ../../howto/isolating-extensions.rst:461 +msgid "TYPE *o = typeobj->tp_alloc(typeobj, 0);" +msgstr "TYPE *o = typeobj->tp_alloc(typeobj, 0);" + +#: ../../howto/isolating-extensions.rst:463 +msgid "" +"Replace ``o = PyObject_NewVar(TYPE, typeobj, size)`` with the same, but use " +"size instead of the 0." +msgstr "" + +#: ../../howto/isolating-extensions.rst:466 +msgid "" +"If the above is not possible (e.g. inside a custom ``tp_alloc``), call :c:" +"func:`PyObject_GC_New` or :c:func:`PyObject_GC_NewVar`::" +msgstr "" + +#: ../../howto/isolating-extensions.rst:469 +msgid "" +"TYPE *o = PyObject_GC_New(TYPE, typeobj);\n" +"\n" +"TYPE *o = PyObject_GC_NewVar(TYPE, typeobj, size);" +msgstr "" +"TYPE *o = PyObject_GC_New(TYPE, typeobj);\n" +"\n" +"TYPE *o = PyObject_GC_NewVar(TYPE, typeobj, size);" + +#: ../../howto/isolating-extensions.rst:475 +msgid "Module State Access from Classes" +msgstr "" + +#: ../../howto/isolating-extensions.rst:477 +msgid "" +"If you have a type object defined with :c:func:`PyType_FromModuleAndSpec`, " +"you can call :c:func:`PyType_GetModule` to get the associated module, and " +"then :c:func:`PyModule_GetState` to get the module's state." +msgstr "" + +#: ../../howto/isolating-extensions.rst:481 +msgid "" +"To save a some tedious error-handling boilerplate code, you can combine " +"these two steps with :c:func:`PyType_GetModuleState`, resulting in::" +msgstr "" + +#: ../../howto/isolating-extensions.rst:484 +msgid "" +"my_struct *state = (my_struct*)PyType_GetModuleState(type);\n" +"if (state == NULL) {\n" +" return NULL;\n" +"}" +msgstr "" +"my_struct *state = (my_struct*)PyType_GetModuleState(type);\n" +"if (state == NULL) {\n" +" return NULL;\n" +"}" + +#: ../../howto/isolating-extensions.rst:491 +msgid "Module State Access from Regular Methods" +msgstr "" + +#: ../../howto/isolating-extensions.rst:493 +msgid "" +"Accessing the module-level state from methods of a class is somewhat more " +"complicated, but is possible thanks to API introduced in Python 3.9. To get " +"the state, you need to first get the *defining class*, and then get the " +"module state from it." +msgstr "" + +#: ../../howto/isolating-extensions.rst:498 +msgid "" +"The largest roadblock is getting *the class a method was defined in*, or " +"that method's \"defining class\" for short. The defining class can have a " +"reference to the module it is part of." +msgstr "" + +#: ../../howto/isolating-extensions.rst:502 +msgid "" +"Do not confuse the defining class with ``Py_TYPE(self)``. If the method is " +"called on a *subclass* of your type, ``Py_TYPE(self)`` will refer to that " +"subclass, which may be defined in different module than yours." +msgstr "" + +#: ../../howto/isolating-extensions.rst:507 +msgid "" +"The following Python code can illustrate the concept. ``Base." +"get_defining_class`` returns ``Base`` even if ``type(self) == Sub``:" +msgstr "" + +#: ../../howto/isolating-extensions.rst:511 +msgid "" +"class Base:\n" +" def get_type_of_self(self):\n" +" return type(self)\n" +"\n" +" def get_defining_class(self):\n" +" return __class__\n" +"\n" +"class Sub(Base):\n" +" pass" +msgstr "" +"class Base:\n" +" def get_type_of_self(self):\n" +" return type(self)\n" +"\n" +" def get_defining_class(self):\n" +" return __class__\n" +"\n" +"class Sub(Base):\n" +" pass" + +#: ../../howto/isolating-extensions.rst:523 +msgid "" +"For a method to get its \"defining class\", it must use the :ref:" +"`METH_METHOD | METH_FASTCALL | METH_KEYWORDS ` :c:type:`calling convention ` and the " +"corresponding :c:type:`PyCMethod` signature::" +msgstr "" + +#: ../../howto/isolating-extensions.rst:528 +msgid "" +"PyObject *PyCMethod(\n" +" PyObject *self, // object the method was called on\n" +" PyTypeObject *defining_class, // defining class\n" +" PyObject *const *args, // C array of arguments\n" +" Py_ssize_t nargs, // length of \"args\"\n" +" PyObject *kwnames) // NULL, or dict of keyword arguments" +msgstr "" + +#: ../../howto/isolating-extensions.rst:535 +msgid "" +"Once you have the defining class, call :c:func:`PyType_GetModuleState` to " +"get the state of its associated module." +msgstr "" + +#: ../../howto/isolating-extensions.rst:538 +msgid "For example::" +msgstr "舉例來說： ::" + +#: ../../howto/isolating-extensions.rst:540 +msgid "" +"static PyObject *\n" +"example_method(PyObject *self,\n" +" PyTypeObject *defining_class,\n" +" PyObject *const *args,\n" +" Py_ssize_t nargs,\n" +" PyObject *kwnames)\n" +"{\n" +" my_struct *state = (my_struct*)PyType_GetModuleState(defining_class);\n" +" if (state == NULL) {\n" +" return NULL;\n" +" }\n" +" ... // rest of logic\n" +"}\n" +"\n" +"PyDoc_STRVAR(example_method_doc, \"...\");\n" +"\n" +"static PyMethodDef my_methods[] = {\n" +" {\"example_method\",\n" +" (PyCFunction)(void(*)(void))example_method,\n" +" METH_METHOD|METH_FASTCALL|METH_KEYWORDS,\n" +" example_method_doc}\n" +" {NULL},\n" +"}" +msgstr "" + +#: ../../howto/isolating-extensions.rst:566 +msgid "Module State Access from Slot Methods, Getters and Setters" +msgstr "" + +#: ../../howto/isolating-extensions.rst:570 +msgid "This is new in Python 3.11." +msgstr "" + +#: ../../howto/isolating-extensions.rst:578 +msgid "" +"Slot methods—the fast C equivalents for special methods, such as :c:member:" +"`~PyNumberMethods.nb_add` for :py:attr:`~object.__add__` or :c:member:" +"`~PyTypeObject.tp_new` for initialization—have a very simple API that " +"doesn't allow passing in the defining class, unlike with :c:type:" +"`PyCMethod`. The same goes for getters and setters defined with :c:type:" +"`PyGetSetDef`." +msgstr "" + +#: ../../howto/isolating-extensions.rst:585 +msgid "" +"To access the module state in these cases, use the :c:func:" +"`PyType_GetModuleByDef` function, and pass in the module definition. Once " +"you have the module, call :c:func:`PyModule_GetState` to get the state::" +msgstr "" + +#: ../../howto/isolating-extensions.rst:590 +msgid "" +"PyObject *module = PyType_GetModuleByDef(Py_TYPE(self), &module_def);\n" +"my_struct *state = (my_struct*)PyModule_GetState(module);\n" +"if (state == NULL) {\n" +" return NULL;\n" +"}" +msgstr "" + +#: ../../howto/isolating-extensions.rst:596 +msgid "" +":c:func:`!PyType_GetModuleByDef` works by searching the :term:`method " +"resolution order` (i.e. all superclasses) for the first superclass that has " +"a corresponding module." +msgstr "" + +#: ../../howto/isolating-extensions.rst:602 +msgid "" +"In very exotic cases (inheritance chains spanning multiple modules created " +"from the same definition), :c:func:`!PyType_GetModuleByDef` might not return " +"the module of the true defining class. However, it will always return a " +"module with the same definition, ensuring a compatible C memory layout." +msgstr "" + +#: ../../howto/isolating-extensions.rst:610 +msgid "Lifetime of the Module State" +msgstr "" + +#: ../../howto/isolating-extensions.rst:612 +msgid "" +"When a module object is garbage-collected, its module state is freed. For " +"each pointer to (a part of) the module state, you must hold a reference to " +"the module object." +msgstr "" + +#: ../../howto/isolating-extensions.rst:616 +msgid "" +"Usually this is not an issue, because types created with :c:func:" +"`PyType_FromModuleAndSpec`, and their instances, hold a reference to the " +"module. However, you must be careful in reference counting when you " +"reference module state from other places, such as callbacks for external " +"libraries." +msgstr "" + +#: ../../howto/isolating-extensions.rst:625 +msgid "Open Issues" +msgstr "" + +#: ../../howto/isolating-extensions.rst:627 +msgid "Several issues around per-module state and heap types are still open." +msgstr "" + +#: ../../howto/isolating-extensions.rst:629 +msgid "" +"Discussions about improving the situation are best held on the `discuss " +"forum under c-api tag `__." +msgstr "" + +#: ../../howto/isolating-extensions.rst:633 +msgid "Per-Class Scope" +msgstr "" + +#: ../../howto/isolating-extensions.rst:635 +msgid "" +"It is currently (as of Python 3.11) not possible to attach state to " +"individual *types* without relying on CPython implementation details (which " +"may change in the future—perhaps, ironically, to allow a proper solution for " +"per-class scope)." +msgstr "" + +#: ../../howto/isolating-extensions.rst:642 +msgid "Lossless Conversion to Heap Types" +msgstr "" + +#: ../../howto/isolating-extensions.rst:644 +msgid "" +"The heap type API was not designed for \"lossless\" conversion from static " +"types; that is, creating a type that works exactly like a given static type." +msgstr "" diff --git a/howto/logging-cookbook.po b/howto/logging-cookbook.po index e0640a56fc..f3c21c83d0 100644 --- a/howto/logging-cookbook.po +++ b/howto/logging-cookbook.po @@ -1,5858 +1,5858 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: 2018-05-23 14:36+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" - -#: ../../howto/logging-cookbook.rst:5 -msgid "Logging Cookbook" -msgstr "" - -#: ../../howto/logging-cookbook.rst:0 -msgid "Author" -msgstr "作者" - -#: ../../howto/logging-cookbook.rst:7 -msgid "Vinay Sajip " -msgstr "Vinay Sajip " - -#: ../../howto/logging-cookbook.rst:9 -msgid "" -"This page contains a number of recipes related to logging, which have been " -"found useful in the past. For links to tutorial and reference information, " -"please see :ref:`cookbook-ref-links`." -msgstr "" - -#: ../../howto/logging-cookbook.rst:16 -msgid "Using logging in multiple modules" -msgstr "" - -#: ../../howto/logging-cookbook.rst:18 -msgid "" -"Multiple calls to ``logging.getLogger('someLogger')`` return a reference to " -"the same logger object. This is true not only within the same module, but " -"also across modules as long as it is in the same Python interpreter " -"process. It is true for references to the same object; additionally, " -"application code can define and configure a parent logger in one module and " -"create (but not configure) a child logger in a separate module, and all " -"logger calls to the child will pass up to the parent. Here is a main " -"module::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:26 -msgid "" -"import logging\n" -"import auxiliary_module\n" -"\n" -"# create logger with 'spam_application'\n" -"logger = logging.getLogger('spam_application')\n" -"logger.setLevel(logging.DEBUG)\n" -"# create file handler which logs even debug messages\n" -"fh = logging.FileHandler('spam.log')\n" -"fh.setLevel(logging.DEBUG)\n" -"# create console handler with a higher log level\n" -"ch = logging.StreamHandler()\n" -"ch.setLevel(logging.ERROR)\n" -"# create formatter and add it to the handlers\n" -"formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %" -"(message)s')\n" -"fh.setFormatter(formatter)\n" -"ch.setFormatter(formatter)\n" -"# add the handlers to the logger\n" -"logger.addHandler(fh)\n" -"logger.addHandler(ch)\n" -"\n" -"logger.info('creating an instance of auxiliary_module.Auxiliary')\n" -"a = auxiliary_module.Auxiliary()\n" -"logger.info('created an instance of auxiliary_module.Auxiliary')\n" -"logger.info('calling auxiliary_module.Auxiliary.do_something')\n" -"a.do_something()\n" -"logger.info('finished auxiliary_module.Auxiliary.do_something')\n" -"logger.info('calling auxiliary_module.some_function()')\n" -"auxiliary_module.some_function()\n" -"logger.info('done with auxiliary_module.some_function()')" -msgstr "" - -#: ../../howto/logging-cookbook.rst:56 -msgid "Here is the auxiliary module::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:58 -msgid "" -"import logging\n" -"\n" -"# create logger\n" -"module_logger = logging.getLogger('spam_application.auxiliary')\n" -"\n" -"class Auxiliary:\n" -" def __init__(self):\n" -" self.logger = " -"logging.getLogger('spam_application.auxiliary.Auxiliary')\n" -" self.logger.info('creating an instance of Auxiliary')\n" -"\n" -" def do_something(self):\n" -" self.logger.info('doing something')\n" -" a = 1 + 1\n" -" self.logger.info('done doing something')\n" -"\n" -"def some_function():\n" -" module_logger.info('received a call to \"some_function\"')" -msgstr "" - -#: ../../howto/logging-cookbook.rst:76 -msgid "The output looks like this:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:78 -msgid "" -"2005-03-23 23:47:11,663 - spam_application - INFO -\n" -" creating an instance of auxiliary_module.Auxiliary\n" -"2005-03-23 23:47:11,665 - spam_application.auxiliary.Auxiliary - INFO -\n" -" creating an instance of Auxiliary\n" -"2005-03-23 23:47:11,665 - spam_application - INFO -\n" -" created an instance of auxiliary_module.Auxiliary\n" -"2005-03-23 23:47:11,668 - spam_application - INFO -\n" -" calling auxiliary_module.Auxiliary.do_something\n" -"2005-03-23 23:47:11,668 - spam_application.auxiliary.Auxiliary - INFO -\n" -" doing something\n" -"2005-03-23 23:47:11,669 - spam_application.auxiliary.Auxiliary - INFO -\n" -" done doing something\n" -"2005-03-23 23:47:11,670 - spam_application - INFO -\n" -" finished auxiliary_module.Auxiliary.do_something\n" -"2005-03-23 23:47:11,671 - spam_application - INFO -\n" -" calling auxiliary_module.some_function()\n" -"2005-03-23 23:47:11,672 - spam_application.auxiliary - INFO -\n" -" received a call to 'some_function'\n" -"2005-03-23 23:47:11,673 - spam_application - INFO -\n" -" done with auxiliary_module.some_function()" -msgstr "" - -#: ../../howto/logging-cookbook.rst:102 -msgid "Logging from multiple threads" -msgstr "" - -#: ../../howto/logging-cookbook.rst:104 -msgid "" -"Logging from multiple threads requires no special effort. The following " -"example shows logging from the main (initial) thread and another thread::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:107 -msgid "" -"import logging\n" -"import threading\n" -"import time\n" -"\n" -"def worker(arg):\n" -" while not arg['stop']:\n" -" logging.debug('Hi from myfunc')\n" -" time.sleep(0.5)\n" -"\n" -"def main():\n" -" logging.basicConfig(level=logging.DEBUG, format='%(relativeCreated)6d %" -"(threadName)s %(message)s')\n" -" info = {'stop': False}\n" -" thread = threading.Thread(target=worker, args=(info,))\n" -" thread.start()\n" -" while True:\n" -" try:\n" -" logging.debug('Hello from main')\n" -" time.sleep(0.75)\n" -" except KeyboardInterrupt:\n" -" info['stop'] = True\n" -" break\n" -" thread.join()\n" -"\n" -"if __name__ == '__main__':\n" -" main()" -msgstr "" - -#: ../../howto/logging-cookbook.rst:133 -msgid "When run, the script should print something like the following:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:135 -msgid "" -" 0 Thread-1 Hi from myfunc\n" -" 3 MainThread Hello from main\n" -" 505 Thread-1 Hi from myfunc\n" -" 755 MainThread Hello from main\n" -"1007 Thread-1 Hi from myfunc\n" -"1507 MainThread Hello from main\n" -"1508 Thread-1 Hi from myfunc\n" -"2010 Thread-1 Hi from myfunc\n" -"2258 MainThread Hello from main\n" -"2512 Thread-1 Hi from myfunc\n" -"3009 MainThread Hello from main\n" -"3013 Thread-1 Hi from myfunc\n" -"3515 Thread-1 Hi from myfunc\n" -"3761 MainThread Hello from main\n" -"4017 Thread-1 Hi from myfunc\n" -"4513 MainThread Hello from main\n" -"4518 Thread-1 Hi from myfunc" -msgstr "" - -#: ../../howto/logging-cookbook.rst:155 -msgid "" -"This shows the logging output interspersed as one might expect. This " -"approach works for more threads than shown here, of course." -msgstr "" - -#: ../../howto/logging-cookbook.rst:159 -msgid "Multiple handlers and formatters" -msgstr "" - -#: ../../howto/logging-cookbook.rst:161 -msgid "" -"Loggers are plain Python objects. The :meth:`~Logger.addHandler` method has " -"no minimum or maximum quota for the number of handlers you may add. " -"Sometimes it will be beneficial for an application to log all messages of " -"all severities to a text file while simultaneously logging errors or above " -"to the console. To set this up, simply configure the appropriate handlers. " -"The logging calls in the application code will remain unchanged. Here is a " -"slight modification to the previous simple module-based configuration " -"example::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:169 -msgid "" -"import logging\n" -"\n" -"logger = logging.getLogger('simple_example')\n" -"logger.setLevel(logging.DEBUG)\n" -"# create file handler which logs even debug messages\n" -"fh = logging.FileHandler('spam.log')\n" -"fh.setLevel(logging.DEBUG)\n" -"# create console handler with a higher log level\n" -"ch = logging.StreamHandler()\n" -"ch.setLevel(logging.ERROR)\n" -"# create formatter and add it to the handlers\n" -"formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %" -"(message)s')\n" -"ch.setFormatter(formatter)\n" -"fh.setFormatter(formatter)\n" -"# add the handlers to logger\n" -"logger.addHandler(ch)\n" -"logger.addHandler(fh)\n" -"\n" -"# 'application' code\n" -"logger.debug('debug message')\n" -"logger.info('info message')\n" -"logger.warning('warn message')\n" -"logger.error('error message')\n" -"logger.critical('critical message')" -msgstr "" - -#: ../../howto/logging-cookbook.rst:194 -msgid "" -"Notice that the 'application' code does not care about multiple handlers. " -"All that changed was the addition and configuration of a new handler named " -"*fh*." -msgstr "" - -#: ../../howto/logging-cookbook.rst:197 -msgid "" -"The ability to create new handlers with higher- or lower-severity filters " -"can be very helpful when writing and testing an application. Instead of " -"using many ``print`` statements for debugging, use ``logger.debug``: Unlike " -"the print statements, which you will have to delete or comment out later, " -"the logger.debug statements can remain intact in the source code and remain " -"dormant until you need them again. At that time, the only change that needs " -"to happen is to modify the severity level of the logger and/or handler to " -"debug." -msgstr "" - -#: ../../howto/logging-cookbook.rst:208 -msgid "Logging to multiple destinations" -msgstr "" - -#: ../../howto/logging-cookbook.rst:210 -msgid "" -"Let's say you want to log to console and file with different message formats " -"and in differing circumstances. Say you want to log messages with levels of " -"DEBUG and higher to file, and those messages at level INFO and higher to the " -"console. Let's also assume that the file should contain timestamps, but the " -"console messages should not. Here's how you can achieve this::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:216 -msgid "" -"import logging\n" -"\n" -"# set up logging to file - see previous section for more details\n" -"logging.basicConfig(level=logging.DEBUG,\n" -" format='%(asctime)s %(name)-12s %(levelname)-8s %" -"(message)s',\n" -" datefmt='%m-%d %H:%M',\n" -" filename='/tmp/myapp.log',\n" -" filemode='w')\n" -"# define a Handler which writes INFO messages or higher to the sys.stderr\n" -"console = logging.StreamHandler()\n" -"console.setLevel(logging.INFO)\n" -"# set a format which is simpler for console use\n" -"formatter = logging.Formatter('%(name)-12s: %(levelname)-8s %(message)s')\n" -"# tell the handler to use this format\n" -"console.setFormatter(formatter)\n" -"# add the handler to the root logger\n" -"logging.getLogger('').addHandler(console)\n" -"\n" -"# Now, we can log to the root logger, or any other logger. First the " -"root...\n" -"logging.info('Jackdaws love my big sphinx of quartz.')\n" -"\n" -"# Now, define a couple of other loggers which might represent areas in your\n" -"# application:\n" -"\n" -"logger1 = logging.getLogger('myapp.area1')\n" -"logger2 = logging.getLogger('myapp.area2')\n" -"\n" -"logger1.debug('Quick zephyrs blow, vexing daft Jim.')\n" -"logger1.info('How quickly daft jumping zebras vex.')\n" -"logger2.warning('Jail zesty vixen who grabbed pay from quack.')\n" -"logger2.error('The five boxing wizards jump quickly.')" -msgstr "" - -#: ../../howto/logging-cookbook.rst:248 -msgid "When you run this, on the console you will see" -msgstr "" - -#: ../../howto/logging-cookbook.rst:250 -msgid "" -"root : INFO Jackdaws love my big sphinx of quartz.\n" -"myapp.area1 : INFO How quickly daft jumping zebras vex.\n" -"myapp.area2 : WARNING Jail zesty vixen who grabbed pay from quack.\n" -"myapp.area2 : ERROR The five boxing wizards jump quickly." -msgstr "" - -#: ../../howto/logging-cookbook.rst:257 -msgid "and in the file you will see something like" -msgstr "" - -#: ../../howto/logging-cookbook.rst:259 -msgid "" -"10-22 22:19 root INFO Jackdaws love my big sphinx of quartz.\n" -"10-22 22:19 myapp.area1 DEBUG Quick zephyrs blow, vexing daft Jim.\n" -"10-22 22:19 myapp.area1 INFO How quickly daft jumping zebras vex.\n" -"10-22 22:19 myapp.area2 WARNING Jail zesty vixen who grabbed pay from " -"quack.\n" -"10-22 22:19 myapp.area2 ERROR The five boxing wizards jump quickly." -msgstr "" - -#: ../../howto/logging-cookbook.rst:267 -msgid "" -"As you can see, the DEBUG message only shows up in the file. The other " -"messages are sent to both destinations." -msgstr "" - -#: ../../howto/logging-cookbook.rst:270 -msgid "" -"This example uses console and file handlers, but you can use any number and " -"combination of handlers you choose." -msgstr "" - -#: ../../howto/logging-cookbook.rst:273 -msgid "" -"Note that the above choice of log filename ``/tmp/myapp.log`` implies use of " -"a standard location for temporary files on POSIX systems. On Windows, you " -"may need to choose a different directory name for the log - just ensure that " -"the directory exists and that you have the permissions to create and update " -"files in it." -msgstr "" - -#: ../../howto/logging-cookbook.rst:282 -msgid "Custom handling of levels" -msgstr "" - -#: ../../howto/logging-cookbook.rst:284 -msgid "" -"Sometimes, you might want to do something slightly different from the " -"standard handling of levels in handlers, where all levels above a threshold " -"get processed by a handler. To do this, you need to use filters. Let's look " -"at a scenario where you want to arrange things as follows:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:289 -msgid "Send messages of severity ``INFO`` and ``WARNING`` to ``sys.stdout``" -msgstr "" - -#: ../../howto/logging-cookbook.rst:290 -msgid "Send messages of severity ``ERROR`` and above to ``sys.stderr``" -msgstr "" - -#: ../../howto/logging-cookbook.rst:291 -msgid "Send messages of severity ``DEBUG`` and above to file ``app.log``" -msgstr "" - -#: ../../howto/logging-cookbook.rst:293 -msgid "Suppose you configure logging with the following JSON:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:295 -msgid "" -"{\n" -" \"version\": 1,\n" -" \"disable_existing_loggers\": false,\n" -" \"formatters\": {\n" -" \"simple\": {\n" -" \"format\": \"%(levelname)-8s - %(message)s\"\n" -" }\n" -" },\n" -" \"handlers\": {\n" -" \"stdout\": {\n" -" \"class\": \"logging.StreamHandler\",\n" -" \"level\": \"INFO\",\n" -" \"formatter\": \"simple\",\n" -" \"stream\": \"ext://sys.stdout\"\n" -" },\n" -" \"stderr\": {\n" -" \"class\": \"logging.StreamHandler\",\n" -" \"level\": \"ERROR\",\n" -" \"formatter\": \"simple\",\n" -" \"stream\": \"ext://sys.stderr\"\n" -" },\n" -" \"file\": {\n" -" \"class\": \"logging.FileHandler\",\n" -" \"formatter\": \"simple\",\n" -" \"filename\": \"app.log\",\n" -" \"mode\": \"w\"\n" -" }\n" -" },\n" -" \"root\": {\n" -" \"level\": \"DEBUG\",\n" -" \"handlers\": [\n" -" \"stderr\",\n" -" \"stdout\",\n" -" \"file\"\n" -" ]\n" -" }\n" -"}" -msgstr "" - -#: ../../howto/logging-cookbook.rst:335 -msgid "" -"This configuration does *almost* what we want, except that ``sys.stdout`` " -"would show messages of severity ``ERROR`` and only events of this severity " -"and higher will be tracked as well as ``INFO`` and ``WARNING`` messages. To " -"prevent this, we can set up a filter which excludes those messages and add " -"it to the relevant handler. This can be configured by adding a ``filters`` " -"section parallel to ``formatters`` and ``handlers``:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:341 -msgid "" -"{\n" -" \"filters\": {\n" -" \"warnings_and_below\": {\n" -" \"()\" : \"__main__.filter_maker\",\n" -" \"level\": \"WARNING\"\n" -" }\n" -" }\n" -"}" -msgstr "" - -#: ../../howto/logging-cookbook.rst:352 -msgid "and changing the section on the ``stdout`` handler to add it:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:354 -msgid "" -"{\n" -" \"stdout\": {\n" -" \"class\": \"logging.StreamHandler\",\n" -" \"level\": \"INFO\",\n" -" \"formatter\": \"simple\",\n" -" \"stream\": \"ext://sys.stdout\",\n" -" \"filters\": [\"warnings_and_below\"]\n" -" }\n" -"}" -msgstr "" - -#: ../../howto/logging-cookbook.rst:366 -msgid "" -"A filter is just a function, so we can define the ``filter_maker`` (a " -"factory function) as follows:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:369 -msgid "" -"def filter_maker(level):\n" -" level = getattr(logging, level)\n" -"\n" -" def filter(record):\n" -" return record.levelno <= level\n" -"\n" -" return filter" -msgstr "" -"def filter_maker(level):\n" -" level = getattr(logging, level)\n" -"\n" -" def filter(record):\n" -" return record.levelno <= level\n" -"\n" -" return filter" - -#: ../../howto/logging-cookbook.rst:379 -msgid "" -"This converts the string argument passed in to a numeric level, and returns " -"a function which only returns ``True`` if the level of the passed in record " -"is at or below the specified level. Note that in this example I have defined " -"the ``filter_maker`` in a test script ``main.py`` that I run from the " -"command line, so its module will be ``__main__`` - hence the " -"``__main__.filter_maker`` in the filter configuration. You will need to " -"change that if you define it in a different module." -msgstr "" - -#: ../../howto/logging-cookbook.rst:387 -msgid "With the filter added, we can run ``main.py``, which in full is:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:389 -msgid "" -"import json\n" -"import logging\n" -"import logging.config\n" -"\n" -"CONFIG = '''\n" -"{\n" -" \"version\": 1,\n" -" \"disable_existing_loggers\": false,\n" -" \"formatters\": {\n" -" \"simple\": {\n" -" \"format\": \"%(levelname)-8s - %(message)s\"\n" -" }\n" -" },\n" -" \"filters\": {\n" -" \"warnings_and_below\": {\n" -" \"()\" : \"__main__.filter_maker\",\n" -" \"level\": \"WARNING\"\n" -" }\n" -" },\n" -" \"handlers\": {\n" -" \"stdout\": {\n" -" \"class\": \"logging.StreamHandler\",\n" -" \"level\": \"INFO\",\n" -" \"formatter\": \"simple\",\n" -" \"stream\": \"ext://sys.stdout\",\n" -" \"filters\": [\"warnings_and_below\"]\n" -" },\n" -" \"stderr\": {\n" -" \"class\": \"logging.StreamHandler\",\n" -" \"level\": \"ERROR\",\n" -" \"formatter\": \"simple\",\n" -" \"stream\": \"ext://sys.stderr\"\n" -" },\n" -" \"file\": {\n" -" \"class\": \"logging.FileHandler\",\n" -" \"formatter\": \"simple\",\n" -" \"filename\": \"app.log\",\n" -" \"mode\": \"w\"\n" -" }\n" -" },\n" -" \"root\": {\n" -" \"level\": \"DEBUG\",\n" -" \"handlers\": [\n" -" \"stderr\",\n" -" \"stdout\",\n" -" \"file\"\n" -" ]\n" -" }\n" -"}\n" -"'''\n" -"\n" -"def filter_maker(level):\n" -" level = getattr(logging, level)\n" -"\n" -" def filter(record):\n" -" return record.levelno <= level\n" -"\n" -" return filter\n" -"\n" -"logging.config.dictConfig(json.loads(CONFIG))\n" -"logging.debug('A DEBUG message')\n" -"logging.info('An INFO message')\n" -"logging.warning('A WARNING message')\n" -"logging.error('An ERROR message')\n" -"logging.critical('A CRITICAL message')" -msgstr "" - -#: ../../howto/logging-cookbook.rst:457 -msgid "And after running it like this:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:459 -msgid "python main.py 2>stderr.log >stdout.log" -msgstr "" - -#: ../../howto/logging-cookbook.rst:463 -msgid "We can see the results are as expected:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:465 -msgid "" -"$ more *.log\n" -"::::::::::::::\n" -"app.log\n" -"::::::::::::::\n" -"DEBUG - A DEBUG message\n" -"INFO - An INFO message\n" -"WARNING - A WARNING message\n" -"ERROR - An ERROR message\n" -"CRITICAL - A CRITICAL message\n" -"::::::::::::::\n" -"stderr.log\n" -"::::::::::::::\n" -"ERROR - An ERROR message\n" -"CRITICAL - A CRITICAL message\n" -"::::::::::::::\n" -"stdout.log\n" -"::::::::::::::\n" -"INFO - An INFO message\n" -"WARNING - A WARNING message" -msgstr "" - -#: ../../howto/logging-cookbook.rst:489 -msgid "Configuration server example" -msgstr "" - -#: ../../howto/logging-cookbook.rst:491 -msgid "Here is an example of a module using the logging configuration server::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:493 -msgid "" -"import logging\n" -"import logging.config\n" -"import time\n" -"import os\n" -"\n" -"# read initial config file\n" -"logging.config.fileConfig('logging.conf')\n" -"\n" -"# create and start listener on port 9999\n" -"t = logging.config.listen(9999)\n" -"t.start()\n" -"\n" -"logger = logging.getLogger('simpleExample')\n" -"\n" -"try:\n" -" # loop through logging calls to see the difference\n" -" # new configurations make, until Ctrl+C is pressed\n" -" while True:\n" -" logger.debug('debug message')\n" -" logger.info('info message')\n" -" logger.warning('warn message')\n" -" logger.error('error message')\n" -" logger.critical('critical message')\n" -" time.sleep(5)\n" -"except KeyboardInterrupt:\n" -" # cleanup\n" -" logging.config.stopListening()\n" -" t.join()" -msgstr "" - -#: ../../howto/logging-cookbook.rst:522 -msgid "" -"And here is a script that takes a filename and sends that file to the " -"server, properly preceded with the binary-encoded length, as the new logging " -"configuration::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:526 -msgid "" -"#!/usr/bin/env python\n" -"import socket, sys, struct\n" -"\n" -"with open(sys.argv[1], 'rb') as f:\n" -" data_to_send = f.read()\n" -"\n" -"HOST = 'localhost'\n" -"PORT = 9999\n" -"s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)\n" -"print('connecting...')\n" -"s.connect((HOST, PORT))\n" -"print('sending config...')\n" -"s.send(struct.pack('>L', len(data_to_send)))\n" -"s.send(data_to_send)\n" -"s.close()\n" -"print('complete')" -msgstr "" -"#!/usr/bin/env python\n" -"import socket, sys, struct\n" -"\n" -"with open(sys.argv[1], 'rb') as f:\n" -" data_to_send = f.read()\n" -"\n" -"HOST = 'localhost'\n" -"PORT = 9999\n" -"s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)\n" -"print('connecting...')\n" -"s.connect((HOST, PORT))\n" -"print('sending config...')\n" -"s.send(struct.pack('>L', len(data_to_send)))\n" -"s.send(data_to_send)\n" -"s.close()\n" -"print('complete')" - -#: ../../howto/logging-cookbook.rst:547 -msgid "Dealing with handlers that block" -msgstr "" - -#: ../../howto/logging-cookbook.rst:551 -msgid "" -"Sometimes you have to get your logging handlers to do their work without " -"blocking the thread you're logging from. This is common in web applications, " -"though of course it also occurs in other scenarios." -msgstr "" - -#: ../../howto/logging-cookbook.rst:555 -msgid "" -"A common culprit which demonstrates sluggish behaviour is " -"the :class:`SMTPHandler`: sending emails can take a long time, for a number " -"of reasons outside the developer's control (for example, a poorly performing " -"mail or network infrastructure). But almost any network-based handler can " -"block: Even a :class:`SocketHandler` operation may do a DNS query under the " -"hood which is too slow (and this query can be deep in the socket library " -"code, below the Python layer, and outside your control)." -msgstr "" - -#: ../../howto/logging-cookbook.rst:563 -msgid "" -"One solution is to use a two-part approach. For the first part, attach only " -"a :class:`QueueHandler` to those loggers which are accessed from performance-" -"critical threads. They simply write to their queue, which can be sized to a " -"large enough capacity or initialized with no upper bound to their size. The " -"write to the queue will typically be accepted quickly, though you will " -"probably need to catch the :exc:`queue.Full` exception as a precaution in " -"your code. If you are a library developer who has performance-critical " -"threads in their code, be sure to document this (together with a suggestion " -"to attach only ``QueueHandlers`` to your loggers) for the benefit of other " -"developers who will use your code." -msgstr "" - -#: ../../howto/logging-cookbook.rst:574 -msgid "" -"The second part of the solution is :class:`QueueListener`, which has been " -"designed as the counterpart to :class:`QueueHandler`. " -"A :class:`QueueListener` is very simple: it's passed a queue and some " -"handlers, and it fires up an internal thread which listens to its queue for " -"LogRecords sent from ``QueueHandlers`` (or any other source of " -"``LogRecords``, for that matter). The ``LogRecords`` are removed from the " -"queue and passed to the handlers for processing." -msgstr "" - -#: ../../howto/logging-cookbook.rst:582 -msgid "" -"The advantage of having a separate :class:`QueueListener` class is that you " -"can use the same instance to service multiple ``QueueHandlers``. This is " -"more resource-friendly than, say, having threaded versions of the existing " -"handler classes, which would eat up one thread per handler for no particular " -"benefit." -msgstr "" - -#: ../../howto/logging-cookbook.rst:587 -msgid "An example of using these two classes follows (imports omitted)::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:589 -msgid "" -"que = queue.Queue(-1) # no limit on size\n" -"queue_handler = QueueHandler(que)\n" -"handler = logging.StreamHandler()\n" -"listener = QueueListener(que, handler)\n" -"root = logging.getLogger()\n" -"root.addHandler(queue_handler)\n" -"formatter = logging.Formatter('%(threadName)s: %(message)s')\n" -"handler.setFormatter(formatter)\n" -"listener.start()\n" -"# The log output will display the thread which generated\n" -"# the event (the main thread) rather than the internal\n" -"# thread which monitors the internal queue. This is what\n" -"# you want to happen.\n" -"root.warning('Look out!')\n" -"listener.stop()" -msgstr "" - -#: ../../howto/logging-cookbook.rst:605 -msgid "which, when run, will produce:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:607 -msgid "MainThread: Look out!" -msgstr "" - -#: ../../howto/logging-cookbook.rst:611 -msgid "" -"Although the earlier discussion wasn't specifically talking about async " -"code, but rather about slow logging handlers, it should be noted that when " -"logging from async code, network and even file handlers could lead to " -"problems (blocking the event loop) because some logging is done " -"from :mod:`asyncio` internals. It might be best, if any async code is used " -"in an application, to use the above approach for logging, so that any " -"blocking code runs only in the ``QueueListener`` thread." -msgstr "" - -#: ../../howto/logging-cookbook.rst:619 -msgid "" -"Prior to Python 3.5, the :class:`QueueListener` always passed every message " -"received from the queue to every handler it was initialized with. (This was " -"because it was assumed that level filtering was all done on the other side, " -"where the queue is filled.) From 3.5 onwards, this behaviour can be changed " -"by passing a keyword argument ``respect_handler_level=True`` to the " -"listener's constructor. When this is done, the listener compares the level " -"of each message with the handler's level, and only passes a message to a " -"handler if it's appropriate to do so." -msgstr "" - -#: ../../howto/logging-cookbook.rst:629 -msgid "" -"The :class:`QueueListener` can be started (and stopped) via " -"the :keyword:`with` statement. For example:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:633 -msgid "" -"with QueueListener(que, handler) as listener:\n" -" # The queue listener automatically starts\n" -" # when the 'with' block is entered.\n" -" pass\n" -"# The queue listener automatically stops once\n" -"# the 'with' block is exited." -msgstr "" - -#: ../../howto/logging-cookbook.rst:645 -msgid "Sending and receiving logging events across a network" -msgstr "" - -#: ../../howto/logging-cookbook.rst:647 -msgid "" -"Let's say you want to send logging events across a network, and handle them " -"at the receiving end. A simple way of doing this is attaching " -"a :class:`SocketHandler` instance to the root logger at the sending end::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:651 -msgid "" -"import logging, logging.handlers\n" -"\n" -"rootLogger = logging.getLogger('')\n" -"rootLogger.setLevel(logging.DEBUG)\n" -"socketHandler = logging.handlers.SocketHandler('localhost',\n" -" logging.handlers.DEFAULT_TCP_LOGGING_PORT)\n" -"# don't bother with a formatter, since a socket handler sends the event as\n" -"# an unformatted pickle\n" -"rootLogger.addHandler(socketHandler)\n" -"\n" -"# Now, we can log to the root logger, or any other logger. First the " -"root...\n" -"logging.info('Jackdaws love my big sphinx of quartz.')\n" -"\n" -"# Now, define a couple of other loggers which might represent areas in your\n" -"# application:\n" -"\n" -"logger1 = logging.getLogger('myapp.area1')\n" -"logger2 = logging.getLogger('myapp.area2')\n" -"\n" -"logger1.debug('Quick zephyrs blow, vexing daft Jim.')\n" -"logger1.info('How quickly daft jumping zebras vex.')\n" -"logger2.warning('Jail zesty vixen who grabbed pay from quack.')\n" -"logger2.error('The five boxing wizards jump quickly.')" -msgstr "" - -#: ../../howto/logging-cookbook.rst:675 -msgid "" -"At the receiving end, you can set up a receiver using " -"the :mod:`socketserver` module. Here is a basic working example::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:678 -msgid "" -"import pickle\n" -"import logging\n" -"import logging.handlers\n" -"import socketserver\n" -"import struct\n" -"\n" -"\n" -"class LogRecordStreamHandler(socketserver.StreamRequestHandler):\n" -" \"\"\"Handler for a streaming logging request.\n" -"\n" -" This basically logs the record using whatever logging policy is\n" -" configured locally.\n" -" \"\"\"\n" -"\n" -" def handle(self):\n" -" \"\"\"\n" -" Handle multiple requests - each expected to be a 4-byte length,\n" -" followed by the LogRecord in pickle format. Logs the record\n" -" according to whatever policy is configured locally.\n" -" \"\"\"\n" -" while True:\n" -" chunk = self.connection.recv(4)\n" -" if len(chunk) < 4:\n" -" break\n" -" slen = struct.unpack('>L', chunk)[0]\n" -" chunk = self.connection.recv(slen)\n" -" while len(chunk) < slen:\n" -" chunk = chunk + self.connection.recv(slen - len(chunk))\n" -" obj = self.unPickle(chunk)\n" -" record = logging.makeLogRecord(obj)\n" -" self.handleLogRecord(record)\n" -"\n" -" def unPickle(self, data):\n" -" return pickle.loads(data)\n" -"\n" -" def handleLogRecord(self, record):\n" -" # if a name is specified, we use the named logger rather than the " -"one\n" -" # implied by the record.\n" -" if self.server.logname is not None:\n" -" name = self.server.logname\n" -" else:\n" -" name = record.name\n" -" logger = logging.getLogger(name)\n" -" # N.B. EVERY record gets logged. This is because Logger.handle\n" -" # is normally called AFTER logger-level filtering. If you want\n" -" # to do filtering, do it at the client end to save wasting\n" -" # cycles and network bandwidth!\n" -" logger.handle(record)\n" -"\n" -"class LogRecordSocketReceiver(socketserver.ThreadingTCPServer):\n" -" \"\"\"\n" -" Simple TCP socket-based logging receiver suitable for testing.\n" -" \"\"\"\n" -"\n" -" allow_reuse_address = True\n" -"\n" -" def __init__(self, host='localhost',\n" -" port=logging.handlers.DEFAULT_TCP_LOGGING_PORT,\n" -" handler=LogRecordStreamHandler):\n" -" socketserver.ThreadingTCPServer.__init__(self, (host, port), " -"handler)\n" -" self.abort = 0\n" -" self.timeout = 1\n" -" self.logname = None\n" -"\n" -" def serve_until_stopped(self):\n" -" import select\n" -" abort = 0\n" -" while not abort:\n" -" rd, wr, ex = select.select([self.socket.fileno()],\n" -" [], [],\n" -" self.timeout)\n" -" if rd:\n" -" self.handle_request()\n" -" abort = self.abort\n" -"\n" -"def main():\n" -" logging.basicConfig(\n" -" format='%(relativeCreated)5d %(name)-15s %(levelname)-8s %" -"(message)s')\n" -" tcpserver = LogRecordSocketReceiver()\n" -" print('About to start TCP server...')\n" -" tcpserver.serve_until_stopped()\n" -"\n" -"if __name__ == '__main__':\n" -" main()" -msgstr "" - -#: ../../howto/logging-cookbook.rst:763 -msgid "" -"First run the server, and then the client. On the client side, nothing is " -"printed on the console; on the server side, you should see something like:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:766 -msgid "" -"About to start TCP server...\n" -" 59 root INFO Jackdaws love my big sphinx of quartz.\n" -" 59 myapp.area1 DEBUG Quick zephyrs blow, vexing daft Jim.\n" -" 69 myapp.area1 INFO How quickly daft jumping zebras vex.\n" -" 69 myapp.area2 WARNING Jail zesty vixen who grabbed pay from quack.\n" -" 69 myapp.area2 ERROR The five boxing wizards jump quickly." -msgstr "" - -#: ../../howto/logging-cookbook.rst:775 -msgid "" -"Note that there are some security issues with pickle in some scenarios. If " -"these affect you, you can use an alternative serialization scheme by " -"overriding the :meth:`~SocketHandler.makePickle` method and implementing " -"your alternative there, as well as adapting the above script to use your " -"alternative serialization." -msgstr "" - -#: ../../howto/logging-cookbook.rst:783 -msgid "Running a logging socket listener in production" -msgstr "" - -#: ../../howto/logging-cookbook.rst:787 -msgid "" -"To run a logging listener in production, you may need to use a process-" -"management tool such as `Supervisor `_. `Here is a " -"Gist `__ which provides the bare-bones files to run " -"the above functionality using Supervisor. It consists of the following files:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:794 -msgid "File" -msgstr "檔案" - -#: ../../howto/logging-cookbook.rst:794 -msgid "Purpose" -msgstr "目的" - -#: ../../howto/logging-cookbook.rst:796 -msgid ":file:`prepare.sh`" -msgstr ":file:`prepare.sh`" - -#: ../../howto/logging-cookbook.rst:796 -msgid "A Bash script to prepare the environment for testing" -msgstr "" - -#: ../../howto/logging-cookbook.rst:799 -msgid ":file:`supervisor.conf`" -msgstr ":file:`supervisor.conf`" - -#: ../../howto/logging-cookbook.rst:799 -msgid "" -"The Supervisor configuration file, which has entries for the listener and a " -"multi-process web application" -msgstr "" - -#: ../../howto/logging-cookbook.rst:803 -msgid ":file:`ensure_app.sh`" -msgstr ":file:`ensure_app.sh`" - -#: ../../howto/logging-cookbook.rst:803 -msgid "" -"A Bash script to ensure that Supervisor is running with the above " -"configuration" -msgstr "" - -#: ../../howto/logging-cookbook.rst:806 -msgid ":file:`log_listener.py`" -msgstr ":file:`log_listener.py`" - -#: ../../howto/logging-cookbook.rst:806 -msgid "" -"The socket listener program which receives log events and records them to a " -"file" -msgstr "" - -#: ../../howto/logging-cookbook.rst:809 -msgid ":file:`main.py`" -msgstr ":file:`main.py`" - -#: ../../howto/logging-cookbook.rst:809 -msgid "" -"A simple web application which performs logging via a socket connected to " -"the listener" -msgstr "" - -#: ../../howto/logging-cookbook.rst:812 -msgid ":file:`webapp.json`" -msgstr ":file:`webapp.json`" - -#: ../../howto/logging-cookbook.rst:812 -msgid "A JSON configuration file for the web application" -msgstr "" - -#: ../../howto/logging-cookbook.rst:814 -msgid ":file:`client.py`" -msgstr ":file:`client.py`" - -#: ../../howto/logging-cookbook.rst:814 -msgid "A Python script to exercise the web application" -msgstr "" - -#: ../../howto/logging-cookbook.rst:817 -msgid "" -"The web application uses `Gunicorn `_, which is a " -"popular web application server that starts multiple worker processes to " -"handle requests. This example setup shows how the workers can write to the " -"same log file without conflicting with one another --- they all go through " -"the socket listener." -msgstr "" - -#: ../../howto/logging-cookbook.rst:822 -msgid "To test these files, do the following in a POSIX environment:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:824 -msgid "" -"Download `the Gist `__ as a ZIP archive using " -"the :guilabel:`Download ZIP` button." -msgstr "" - -#: ../../howto/logging-cookbook.rst:827 -msgid "Unzip the above files from the archive into a scratch directory." -msgstr "" - -#: ../../howto/logging-cookbook.rst:829 -msgid "" -"In the scratch directory, run ``bash prepare.sh`` to get things ready. This " -"creates a :file:`run` subdirectory to contain Supervisor-related and log " -"files, and a :file:`venv` subdirectory to contain a virtual environment into " -"which ``bottle``, ``gunicorn`` and ``supervisor`` are installed." -msgstr "" - -#: ../../howto/logging-cookbook.rst:834 -msgid "" -"Run ``bash ensure_app.sh`` to ensure that Supervisor is running with the " -"above configuration." -msgstr "" - -#: ../../howto/logging-cookbook.rst:837 -msgid "" -"Run ``venv/bin/python client.py`` to exercise the web application, which " -"will lead to records being written to the log." -msgstr "" - -#: ../../howto/logging-cookbook.rst:840 -msgid "" -"Inspect the log files in the :file:`run` subdirectory. You should see the " -"most recent log lines in files matching the pattern :file:`app.log*`. They " -"won't be in any particular order, since they have been handled concurrently " -"by different worker processes in a non-deterministic way." -msgstr "" - -#: ../../howto/logging-cookbook.rst:845 -msgid "" -"You can shut down the listener and the web application by running ``venv/bin/" -"supervisorctl -c supervisor.conf shutdown``." -msgstr "" - -#: ../../howto/logging-cookbook.rst:848 -msgid "" -"You may need to tweak the configuration files in the unlikely event that the " -"configured ports clash with something else in your test environment." -msgstr "" - -#: ../../howto/logging-cookbook.rst:851 -msgid "" -"The default configuration uses a TCP socket on port 9020. You can use a Unix " -"Domain socket instead of a TCP socket by doing the following:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:854 -msgid "" -"In :file:`listener.json`, add a ``socket`` key with the path to the domain " -"socket you want to use. If this key is present, the listener listens on the " -"corresponding domain socket and not on a TCP socket (the ``port`` key is " -"ignored)." -msgstr "" - -#: ../../howto/logging-cookbook.rst:859 -msgid "" -"In :file:`webapp.json`, change the socket handler configuration dictionary " -"so that the ``host`` value is the path to the domain socket, and set the " -"``port`` value to ``null``." -msgstr "" - -#: ../../howto/logging-cookbook.rst:869 -msgid "Adding contextual information to your logging output" -msgstr "" - -#: ../../howto/logging-cookbook.rst:871 -msgid "" -"Sometimes you want logging output to contain contextual information in " -"addition to the parameters passed to the logging call. For example, in a " -"networked application, it may be desirable to log client-specific " -"information in the log (e.g. remote client's username, or IP address). " -"Although you could use the *extra* parameter to achieve this, it's not " -"always convenient to pass the information in this way. While it might be " -"tempting to create :class:`Logger` instances on a per-connection basis, this " -"is not a good idea because these instances are not garbage collected. While " -"this is not a problem in practice, when the number of :class:`Logger` " -"instances is dependent on the level of granularity you want to use in " -"logging an application, it could be hard to manage if the number " -"of :class:`Logger` instances becomes effectively unbounded." -msgstr "" - -#: ../../howto/logging-cookbook.rst:886 -msgid "Using LoggerAdapters to impart contextual information" -msgstr "" - -#: ../../howto/logging-cookbook.rst:888 -msgid "" -"An easy way in which you can pass contextual information to be output along " -"with logging event information is to use the :class:`LoggerAdapter` class. " -"This class is designed to look like a :class:`Logger`, so that you can " -"call :meth:`debug`, :meth:`info`, :meth:`warning`, :meth:`error`, :meth:`exception`, :meth:`critical` " -"and :meth:`log`. These methods have the same signatures as their " -"counterparts in :class:`Logger`, so you can use the two types of instances " -"interchangeably." -msgstr "" - -#: ../../howto/logging-cookbook.rst:896 -msgid "" -"When you create an instance of :class:`LoggerAdapter`, you pass it " -"a :class:`Logger` instance and a dict-like object which contains your " -"contextual information. When you call one of the logging methods on an " -"instance of :class:`LoggerAdapter`, it delegates the call to the underlying " -"instance of :class:`Logger` passed to its constructor, and arranges to pass " -"the contextual information in the delegated call. Here's a snippet from the " -"code of :class:`LoggerAdapter`::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:904 -msgid "" -"def debug(self, msg, /, *args, **kwargs):\n" -" \"\"\"\n" -" Delegate a debug call to the underlying logger, after adding\n" -" contextual information from this adapter instance.\n" -" \"\"\"\n" -" msg, kwargs = self.process(msg, kwargs)\n" -" self.logger.debug(msg, *args, **kwargs)" -msgstr "" - -#: ../../howto/logging-cookbook.rst:912 -msgid "" -"The :meth:`~LoggerAdapter.process` method of :class:`LoggerAdapter` is where " -"the contextual information is added to the logging output. It's passed the " -"message and keyword arguments of the logging call, and it passes back " -"(potentially) modified versions of these to use in the call to the " -"underlying logger. The default implementation of this method leaves the " -"message alone, but inserts an 'extra' key in the keyword argument whose " -"value is the dict-like object passed to the constructor. Of course, if you " -"had passed an 'extra' keyword argument in the call to the adapter, it will " -"be silently overwritten." -msgstr "" - -#: ../../howto/logging-cookbook.rst:921 -msgid "" -"The advantage of using 'extra' is that the values in the dict-like object " -"are merged into the :class:`LogRecord` instance's __dict__, allowing you to " -"use customized strings with your :class:`Formatter` instances which know " -"about the keys of the dict-like object. If you need a different method, e.g. " -"if you want to prepend or append the contextual information to the message " -"string, you just need to subclass :class:`LoggerAdapter` and " -"override :meth:`~LoggerAdapter.process` to do what you need. Here is a " -"simple example::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:929 -msgid "" -"class CustomAdapter(logging.LoggerAdapter):\n" -" \"\"\"\n" -" This example adapter expects the passed in dict-like object to have a\n" -" 'connid' key, whose value in brackets is prepended to the log message.\n" -" \"\"\"\n" -" def process(self, msg, kwargs):\n" -" return '[%s] %s' % (self.extra['connid'], msg), kwargs" -msgstr "" - -#: ../../howto/logging-cookbook.rst:937 -msgid "which you can use like this::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:939 -msgid "" -"logger = logging.getLogger(__name__)\n" -"adapter = CustomAdapter(logger, {'connid': some_conn_id})" -msgstr "" - -#: ../../howto/logging-cookbook.rst:942 -msgid "" -"Then any events that you log to the adapter will have the value of " -"``some_conn_id`` prepended to the log messages." -msgstr "" - -#: ../../howto/logging-cookbook.rst:946 -msgid "Using objects other than dicts to pass contextual information" -msgstr "" - -#: ../../howto/logging-cookbook.rst:948 -msgid "" -"You don't need to pass an actual dict to a :class:`LoggerAdapter` - you " -"could pass an instance of a class which implements ``__getitem__`` and " -"``__iter__`` so that it looks like a dict to logging. This would be useful " -"if you want to generate values dynamically (whereas the values in a dict " -"would be constant)." -msgstr "" - -#: ../../howto/logging-cookbook.rst:957 -msgid "Using Filters to impart contextual information" -msgstr "" - -#: ../../howto/logging-cookbook.rst:959 -msgid "" -"You can also add contextual information to log output using a user-" -"defined :class:`Filter`. ``Filter`` instances are allowed to modify the " -"``LogRecords`` passed to them, including adding additional attributes which " -"can then be output using a suitable format string, or if needed a " -"custom :class:`Formatter`." -msgstr "" - -#: ../../howto/logging-cookbook.rst:964 -msgid "" -"For example in a web application, the request being processed (or at least, " -"the interesting parts of it) can be stored in a threadlocal " -"(:class:`threading.local`) variable, and then accessed from a ``Filter`` to " -"add, say, information from the request - say, the remote IP address and " -"remote user's username - to the ``LogRecord``, using the attribute names " -"'ip' and 'user' as in the ``LoggerAdapter`` example above. In that case, the " -"same format string can be used to get similar output to that shown above. " -"Here's an example script::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:973 -msgid "" -"import logging\n" -"from random import choice\n" -"\n" -"class ContextFilter(logging.Filter):\n" -" \"\"\"\n" -" This is a filter which injects contextual information into the log.\n" -"\n" -" Rather than use actual contextual information, we just use random\n" -" data in this demo.\n" -" \"\"\"\n" -"\n" -" USERS = ['jim', 'fred', 'sheila']\n" -" IPS = ['123.231.231.123', '127.0.0.1', '192.168.0.1']\n" -"\n" -" def filter(self, record):\n" -"\n" -" record.ip = choice(ContextFilter.IPS)\n" -" record.user = choice(ContextFilter.USERS)\n" -" return True\n" -"\n" -"if __name__ == '__main__':\n" -" levels = (logging.DEBUG, logging.INFO, logging.WARNING, logging.ERROR, " -"logging.CRITICAL)\n" -" logging.basicConfig(level=logging.DEBUG,\n" -" format='%(asctime)-15s %(name)-5s %(levelname)-8s " -"IP: %(ip)-15s User: %(user)-8s %(message)s')\n" -" a1 = logging.getLogger('a.b.c')\n" -" a2 = logging.getLogger('d.e.f')\n" -"\n" -" f = ContextFilter()\n" -" a1.addFilter(f)\n" -" a2.addFilter(f)\n" -" a1.debug('A debug message')\n" -" a1.info('An info message with %s', 'some parameters')\n" -" for x in range(10):\n" -" lvl = choice(levels)\n" -" lvlname = logging.getLevelName(lvl)\n" -" a2.log(lvl, 'A message at %s level with %d %s', lvlname, 2, " -"'parameters')" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1010 -msgid "which, when run, produces something like:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1012 -msgid "" -"2010-09-06 22:38:15,292 a.b.c DEBUG IP: 123.231.231.123 User: fred A " -"debug message\n" -"2010-09-06 22:38:15,300 a.b.c INFO IP: 192.168.0.1 User: sheila An " -"info message with some parameters\n" -"2010-09-06 22:38:15,300 d.e.f CRITICAL IP: 127.0.0.1 User: sheila A " -"message at CRITICAL level with 2 parameters\n" -"2010-09-06 22:38:15,300 d.e.f ERROR IP: 127.0.0.1 User: jim A " -"message at ERROR level with 2 parameters\n" -"2010-09-06 22:38:15,300 d.e.f DEBUG IP: 127.0.0.1 User: sheila A " -"message at DEBUG level with 2 parameters\n" -"2010-09-06 22:38:15,300 d.e.f ERROR IP: 123.231.231.123 User: fred A " -"message at ERROR level with 2 parameters\n" -"2010-09-06 22:38:15,300 d.e.f CRITICAL IP: 192.168.0.1 User: jim A " -"message at CRITICAL level with 2 parameters\n" -"2010-09-06 22:38:15,300 d.e.f CRITICAL IP: 127.0.0.1 User: sheila A " -"message at CRITICAL level with 2 parameters\n" -"2010-09-06 22:38:15,300 d.e.f DEBUG IP: 192.168.0.1 User: jim A " -"message at DEBUG level with 2 parameters\n" -"2010-09-06 22:38:15,301 d.e.f ERROR IP: 127.0.0.1 User: sheila A " -"message at ERROR level with 2 parameters\n" -"2010-09-06 22:38:15,301 d.e.f DEBUG IP: 123.231.231.123 User: fred A " -"message at DEBUG level with 2 parameters\n" -"2010-09-06 22:38:15,301 d.e.f INFO IP: 123.231.231.123 User: fred A " -"message at INFO level with 2 parameters" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1028 -msgid "Use of ``contextvars``" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1030 -msgid "" -"Since Python 3.7, the :mod:`contextvars` module has provided context-local " -"storage which works for both :mod:`threading` and :mod:`asyncio` processing " -"needs. This type of storage may thus be generally preferable to thread-" -"locals. The following example shows how, in a multi-threaded environment, " -"logs can populated with contextual information such as, for example, request " -"attributes handled by web applications." -msgstr "" - -#: ../../howto/logging-cookbook.rst:1036 -msgid "" -"For the purposes of illustration, say that you have different web " -"applications, each independent of the other but running in the same Python " -"process and using a library common to them. How can each of these " -"applications have their own log, where all logging messages from the library " -"(and other request processing code) are directed to the appropriate " -"application's log file, while including in the log additional contextual " -"information such as client IP, HTTP request method and client username?" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1043 -msgid "Let's assume that the library can be simulated by the following code:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1045 -msgid "" -"# webapplib.py\n" -"import logging\n" -"import time\n" -"\n" -"logger = logging.getLogger(__name__)\n" -"\n" -"def useful():\n" -" # Just a representative event logged from the library\n" -" logger.debug('Hello from webapplib!')\n" -" # Just sleep for a bit so other threads get to run\n" -" time.sleep(0.01)" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1059 -msgid "" -"We can simulate the multiple web applications by means of two simple " -"classes, ``Request`` and ``WebApp``. These simulate how real threaded web " -"applications work - each request is handled by a thread:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1063 -msgid "" -"# main.py\n" -"import argparse\n" -"from contextvars import ContextVar\n" -"import logging\n" -"import os\n" -"from random import choice\n" -"import threading\n" -"import webapplib\n" -"\n" -"logger = logging.getLogger(__name__)\n" -"root = logging.getLogger()\n" -"root.setLevel(logging.DEBUG)\n" -"\n" -"class Request:\n" -" \"\"\"\n" -" A simple dummy request class which just holds dummy HTTP request " -"method,\n" -" client IP address and client username\n" -" \"\"\"\n" -" def __init__(self, method, ip, user):\n" -" self.method = method\n" -" self.ip = ip\n" -" self.user = user\n" -"\n" -"# A dummy set of requests which will be used in the simulation - we'll just " -"pick\n" -"# from this list randomly. Note that all GET requests are from " -"192.168.2.XXX\n" -"# addresses, whereas POST requests are from 192.16.3.XXX addresses. Three " -"users\n" -"# are represented in the sample requests.\n" -"\n" -"REQUESTS = [\n" -" Request('GET', '192.168.2.20', 'jim'),\n" -" Request('POST', '192.168.3.20', 'fred'),\n" -" Request('GET', '192.168.2.21', 'sheila'),\n" -" Request('POST', '192.168.3.21', 'jim'),\n" -" Request('GET', '192.168.2.22', 'fred'),\n" -" Request('POST', '192.168.3.22', 'sheila'),\n" -"]\n" -"\n" -"# Note that the format string includes references to request context " -"information\n" -"# such as HTTP method, client IP and username\n" -"\n" -"formatter = logging.Formatter('%(threadName)-11s %(appName)s %(name)-9s %" -"(user)-6s %(ip)s %(method)-4s %(message)s')\n" -"\n" -"# Create our context variables. These will be filled at the start of " -"request\n" -"# processing, and used in the logging that happens during that processing\n" -"\n" -"ctx_request = ContextVar('request')\n" -"ctx_appname = ContextVar('appname')\n" -"\n" -"class InjectingFilter(logging.Filter):\n" -" \"\"\"\n" -" A filter which injects context-specific information into logs and " -"ensures\n" -" that only information for a specific webapp is included in its log\n" -" \"\"\"\n" -" def __init__(self, app):\n" -" self.app = app\n" -"\n" -" def filter(self, record):\n" -" request = ctx_request.get()\n" -" record.method = request.method\n" -" record.ip = request.ip\n" -" record.user = request.user\n" -" record.appName = appName = ctx_appname.get()\n" -" return appName == self.app.name\n" -"\n" -"class WebApp:\n" -" \"\"\"\n" -" A dummy web application class which has its own handler and filter for " -"a\n" -" webapp-specific log.\n" -" \"\"\"\n" -" def __init__(self, name):\n" -" self.name = name\n" -" handler = logging.FileHandler(name + '.log', 'w')\n" -" f = InjectingFilter(self)\n" -" handler.setFormatter(formatter)\n" -" handler.addFilter(f)\n" -" root.addHandler(handler)\n" -" self.num_requests = 0\n" -"\n" -" def process_request(self, request):\n" -" \"\"\"\n" -" This is the dummy method for processing a request. It's called on a\n" -" different thread for every request. We store the context information " -"into\n" -" the context vars before doing anything else.\n" -" \"\"\"\n" -" ctx_request.set(request)\n" -" ctx_appname.set(self.name)\n" -" self.num_requests += 1\n" -" logger.debug('Request processing started')\n" -" webapplib.useful()\n" -" logger.debug('Request processing finished')\n" -"\n" -"def main():\n" -" fn = os.path.splitext(os.path.basename(__file__))[0]\n" -" adhf = argparse.ArgumentDefaultsHelpFormatter\n" -" ap = argparse.ArgumentParser(formatter_class=adhf, prog=fn,\n" -" description='Simulate a couple of web '\n" -" 'applications handling some '\n" -" 'requests, showing how request " -"'\n" -" 'context can be used to '\n" -" 'populate logs')\n" -" aa = ap.add_argument\n" -" aa('--count', '-c', type=int, default=100, help='How many requests to " -"simulate')\n" -" options = ap.parse_args()\n" -"\n" -" # Create the dummy webapps and put them in a list which we can use to " -"select\n" -" # from randomly\n" -" app1 = WebApp('app1')\n" -" app2 = WebApp('app2')\n" -" apps = [app1, app2]\n" -" threads = []\n" -" # Add a common handler which will capture all events\n" -" handler = logging.FileHandler('app.log', 'w')\n" -" handler.setFormatter(formatter)\n" -" root.addHandler(handler)\n" -"\n" -" # Generate calls to process requests\n" -" for i in range(options.count):\n" -" try:\n" -" # Pick an app at random and a request for it to process\n" -" app = choice(apps)\n" -" request = choice(REQUESTS)\n" -" # Process the request in its own thread\n" -" t = threading.Thread(target=app.process_request, " -"args=(request,))\n" -" threads.append(t)\n" -" t.start()\n" -" except KeyboardInterrupt:\n" -" break\n" -"\n" -" # Wait for the threads to terminate\n" -" for t in threads:\n" -" t.join()\n" -"\n" -" for app in apps:\n" -" print('%s processed %s requests' % (app.name, app.num_requests))\n" -"\n" -"if __name__ == '__main__':\n" -" main()" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1203 -msgid "" -"If you run the above, you should find that roughly half the requests go " -"into :file:`app1.log` and the rest into :file:`app2.log`, and the all the " -"requests are logged to :file:`app.log`. Each webapp-specific log will " -"contain only log entries for only that webapp, and the request information " -"will be displayed consistently in the log (i.e. the information in each " -"dummy request will always appear together in a log line). This is " -"illustrated by the following shell output:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1210 -msgid "" -"~/logging-contextual-webapp$ python main.py\n" -"app1 processed 51 requests\n" -"app2 processed 49 requests\n" -"~/logging-contextual-webapp$ wc -l *.log\n" -" 153 app1.log\n" -" 147 app2.log\n" -" 300 app.log\n" -" 600 total\n" -"~/logging-contextual-webapp$ head -3 app1.log\n" -"Thread-3 (process_request) app1 __main__ jim 192.168.3.21 POST Request " -"processing started\n" -"Thread-3 (process_request) app1 webapplib jim 192.168.3.21 POST Hello " -"from webapplib!\n" -"Thread-5 (process_request) app1 __main__ jim 192.168.3.21 POST Request " -"processing started\n" -"~/logging-contextual-webapp$ head -3 app2.log\n" -"Thread-1 (process_request) app2 __main__ sheila 192.168.2.21 GET Request " -"processing started\n" -"Thread-1 (process_request) app2 webapplib sheila 192.168.2.21 GET Hello " -"from webapplib!\n" -"Thread-2 (process_request) app2 __main__ jim 192.168.2.20 GET Request " -"processing started\n" -"~/logging-contextual-webapp$ head app.log\n" -"Thread-1 (process_request) app2 __main__ sheila 192.168.2.21 GET Request " -"processing started\n" -"Thread-1 (process_request) app2 webapplib sheila 192.168.2.21 GET Hello " -"from webapplib!\n" -"Thread-2 (process_request) app2 __main__ jim 192.168.2.20 GET Request " -"processing started\n" -"Thread-3 (process_request) app1 __main__ jim 192.168.3.21 POST Request " -"processing started\n" -"Thread-2 (process_request) app2 webapplib jim 192.168.2.20 GET Hello " -"from webapplib!\n" -"Thread-3 (process_request) app1 webapplib jim 192.168.3.21 POST Hello " -"from webapplib!\n" -"Thread-4 (process_request) app2 __main__ fred 192.168.2.22 GET Request " -"processing started\n" -"Thread-5 (process_request) app1 __main__ jim 192.168.3.21 POST Request " -"processing started\n" -"Thread-4 (process_request) app2 webapplib fred 192.168.2.22 GET Hello " -"from webapplib!\n" -"Thread-6 (process_request) app1 __main__ jim 192.168.3.21 POST Request " -"processing started\n" -"~/logging-contextual-webapp$ grep app1 app1.log | wc -l\n" -"153\n" -"~/logging-contextual-webapp$ grep app2 app2.log | wc -l\n" -"147\n" -"~/logging-contextual-webapp$ grep app1 app.log | wc -l\n" -"153\n" -"~/logging-contextual-webapp$ grep app2 app.log | wc -l\n" -"147" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1250 -msgid "Imparting contextual information in handlers" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1252 -msgid "" -"Each :class:`~Handler` has its own chain of filters. If you want to add " -"contextual information to a :class:`LogRecord` without leaking it to other " -"handlers, you can use a filter that returns a new :class:`~LogRecord` " -"instead of modifying it in-place, as shown in the following script::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1257 -msgid "" -"import copy\n" -"import logging\n" -"\n" -"def filter(record: logging.LogRecord):\n" -" record = copy.copy(record)\n" -" record.user = 'jim'\n" -" return record\n" -"\n" -"if __name__ == '__main__':\n" -" logger = logging.getLogger()\n" -" logger.setLevel(logging.INFO)\n" -" handler = logging.StreamHandler()\n" -" formatter = logging.Formatter('%(message)s from %(user)-8s')\n" -" handler.setFormatter(formatter)\n" -" handler.addFilter(filter)\n" -" logger.addHandler(handler)\n" -"\n" -" logger.info('A log message')" -msgstr "" -"import copy\n" -"import logging\n" -"\n" -"def filter(record: logging.LogRecord):\n" -" record = copy.copy(record)\n" -" record.user = 'jim'\n" -" return record\n" -"\n" -"if __name__ == '__main__':\n" -" logger = logging.getLogger()\n" -" logger.setLevel(logging.INFO)\n" -" handler = logging.StreamHandler()\n" -" formatter = logging.Formatter('%(message)s from %(user)-8s')\n" -" handler.setFormatter(formatter)\n" -" handler.addFilter(filter)\n" -" logger.addHandler(handler)\n" -"\n" -" logger.info('A log message')" - -#: ../../howto/logging-cookbook.rst:1279 -msgid "Logging to a single file from multiple processes" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1281 -msgid "" -"Although logging is thread-safe, and logging to a single file from multiple " -"threads in a single process *is* supported, logging to a single file from " -"*multiple processes* is *not* supported, because there is no standard way to " -"serialize access to a single file across multiple processes in Python. If " -"you need to log to a single file from multiple processes, one way of doing " -"this is to have all the processes log to a :class:`~handlers.SocketHandler`, " -"and have a separate process which implements a socket server which reads " -"from the socket and logs to file. (If you prefer, you can dedicate one " -"thread in one of the existing processes to perform this " -"function.) :ref:`This section ` documents this approach in " -"more detail and includes a working socket receiver which can be used as a " -"starting point for you to adapt in your own applications." -msgstr "" - -#: ../../howto/logging-cookbook.rst:1294 -msgid "" -"You could also write your own handler which uses " -"the :class:`~multiprocessing.Lock` class from the :mod:`multiprocessing` " -"module to serialize access to the file from your processes. The " -"stdlib :class:`FileHandler` and subclasses do not make use " -"of :mod:`multiprocessing`." -msgstr "" - -#: ../../howto/logging-cookbook.rst:1301 -msgid "" -"Alternatively, you can use a ``Queue`` and a :class:`QueueHandler` to send " -"all logging events to one of the processes in your multi-process " -"application. The following example script demonstrates how you can do this; " -"in the example a separate listener process listens for events sent by other " -"processes and logs them according to its own logging configuration. Although " -"the example only demonstrates one way of doing it (for example, you may want " -"to use a listener thread rather than a separate listener process -- the " -"implementation would be analogous) it does allow for completely different " -"logging configurations for the listener and the other processes in your " -"application, and can be used as the basis for code meeting your own specific " -"requirements::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1312 -msgid "" -"# You'll need these imports in your own code\n" -"import logging\n" -"import logging.handlers\n" -"import multiprocessing\n" -"\n" -"# Next two import lines for this demo only\n" -"from random import choice, random\n" -"import time\n" -"\n" -"#\n" -"# Because you'll want to define the logging configurations for listener and " -"workers, the\n" -"# listener and worker process functions take a configurer parameter which is " -"a callable\n" -"# for configuring logging for that process. These functions are also passed " -"the queue,\n" -"# which they use for communication.\n" -"#\n" -"# In practice, you can configure the listener however you want, but note " -"that in this\n" -"# simple example, the listener does not apply level or filter logic to " -"received records.\n" -"# In practice, you would probably want to do this logic in the worker " -"processes, to avoid\n" -"# sending events which would be filtered out between processes.\n" -"#\n" -"# The size of the rotated files is made small so you can see the results " -"easily.\n" -"def listener_configurer():\n" -" root = logging.getLogger()\n" -" h = logging.handlers.RotatingFileHandler('mptest.log', 'a', 300, 10)\n" -" f = logging.Formatter('%(asctime)s %(processName)-10s %(name)s %" -"(levelname)-8s %(message)s')\n" -" h.setFormatter(f)\n" -" root.addHandler(h)\n" -"\n" -"# This is the listener process top-level loop: wait for logging events\n" -"# (LogRecords)on the queue and handle them, quit when you get a None for a\n" -"# LogRecord.\n" -"def listener_process(queue, configurer):\n" -" configurer()\n" -" while True:\n" -" try:\n" -" record = queue.get()\n" -" if record is None: # We send this as a sentinel to tell the " -"listener to quit.\n" -" break\n" -" logger = logging.getLogger(record.name)\n" -" logger.handle(record) # No level or filter logic applied - just " -"do it!\n" -" except Exception:\n" -" import sys, traceback\n" -" print('Whoops! Problem:', file=sys.stderr)\n" -" traceback.print_exc(file=sys.stderr)\n" -"\n" -"# Arrays used for random selections in this demo\n" -"\n" -"LEVELS = [logging.DEBUG, logging.INFO, logging.WARNING,\n" -" logging.ERROR, logging.CRITICAL]\n" -"\n" -"LOGGERS = ['a.b.c', 'd.e.f']\n" -"\n" -"MESSAGES = [\n" -" 'Random message #1',\n" -" 'Random message #2',\n" -" 'Random message #3',\n" -"]\n" -"\n" -"# The worker configuration is done at the start of the worker process run.\n" -"# Note that on Windows you can't rely on fork semantics, so each process\n" -"# will run the logging configuration code when it starts.\n" -"def worker_configurer(queue):\n" -" h = logging.handlers.QueueHandler(queue) # Just the one handler needed\n" -" root = logging.getLogger()\n" -" root.addHandler(h)\n" -" # send all messages, for demo; no other level or filter logic applied.\n" -" root.setLevel(logging.DEBUG)\n" -"\n" -"# This is the worker process top-level loop, which just logs ten events " -"with\n" -"# random intervening delays before terminating.\n" -"# The print messages are just so you know it's doing something!\n" -"def worker_process(queue, configurer):\n" -" configurer(queue)\n" -" name = multiprocessing.current_process().name\n" -" print('Worker started: %s' % name)\n" -" for i in range(10):\n" -" time.sleep(random())\n" -" logger = logging.getLogger(choice(LOGGERS))\n" -" level = choice(LEVELS)\n" -" message = choice(MESSAGES)\n" -" logger.log(level, message)\n" -" print('Worker finished: %s' % name)\n" -"\n" -"# Here's where the demo gets orchestrated. Create the queue, create and " -"start\n" -"# the listener, create ten workers and start them, wait for them to finish,\n" -"# then send a None to the queue to tell the listener to finish.\n" -"def main():\n" -" queue = multiprocessing.Queue(-1)\n" -" listener = multiprocessing.Process(target=listener_process,\n" -" args=(queue, listener_configurer))\n" -" listener.start()\n" -" workers = []\n" -" for i in range(10):\n" -" worker = multiprocessing.Process(target=worker_process,\n" -" args=(queue, worker_configurer))\n" -" workers.append(worker)\n" -" worker.start()\n" -" for w in workers:\n" -" w.join()\n" -" queue.put_nowait(None)\n" -" listener.join()\n" -"\n" -"if __name__ == '__main__':\n" -" main()" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1417 -msgid "" -"A variant of the above script keeps the logging in the main process, in a " -"separate thread::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1420 -msgid "" -"import logging\n" -"import logging.config\n" -"import logging.handlers\n" -"from multiprocessing import Process, Queue\n" -"import random\n" -"import threading\n" -"import time\n" -"\n" -"def logger_thread(q):\n" -" while True:\n" -" record = q.get()\n" -" if record is None:\n" -" break\n" -" logger = logging.getLogger(record.name)\n" -" logger.handle(record)\n" -"\n" -"\n" -"def worker_process(q):\n" -" qh = logging.handlers.QueueHandler(q)\n" -" root = logging.getLogger()\n" -" root.setLevel(logging.DEBUG)\n" -" root.addHandler(qh)\n" -" levels = [logging.DEBUG, logging.INFO, logging.WARNING, logging.ERROR,\n" -" logging.CRITICAL]\n" -" loggers = ['foo', 'foo.bar', 'foo.bar.baz',\n" -" 'spam', 'spam.ham', 'spam.ham.eggs']\n" -" for i in range(100):\n" -" lvl = random.choice(levels)\n" -" logger = logging.getLogger(random.choice(loggers))\n" -" logger.log(lvl, 'Message no. %d', i)\n" -"\n" -"if __name__ == '__main__':\n" -" q = Queue()\n" -" d = {\n" -" 'version': 1,\n" -" 'formatters': {\n" -" 'detailed': {\n" -" 'class': 'logging.Formatter',\n" -" 'format': '%(asctime)s %(name)-15s %(levelname)-8s %" -"(processName)-10s %(message)s'\n" -" }\n" -" },\n" -" 'handlers': {\n" -" 'console': {\n" -" 'class': 'logging.StreamHandler',\n" -" 'level': 'INFO',\n" -" },\n" -" 'file': {\n" -" 'class': 'logging.FileHandler',\n" -" 'filename': 'mplog.log',\n" -" 'mode': 'w',\n" -" 'formatter': 'detailed',\n" -" },\n" -" 'foofile': {\n" -" 'class': 'logging.FileHandler',\n" -" 'filename': 'mplog-foo.log',\n" -" 'mode': 'w',\n" -" 'formatter': 'detailed',\n" -" },\n" -" 'errors': {\n" -" 'class': 'logging.FileHandler',\n" -" 'filename': 'mplog-errors.log',\n" -" 'mode': 'w',\n" -" 'level': 'ERROR',\n" -" 'formatter': 'detailed',\n" -" },\n" -" },\n" -" 'loggers': {\n" -" 'foo': {\n" -" 'handlers': ['foofile']\n" -" }\n" -" },\n" -" 'root': {\n" -" 'level': 'DEBUG',\n" -" 'handlers': ['console', 'file', 'errors']\n" -" },\n" -" }\n" -" workers = []\n" -" for i in range(5):\n" -" wp = Process(target=worker_process, name='worker %d' % (i + 1), " -"args=(q,))\n" -" workers.append(wp)\n" -" wp.start()\n" -" logging.config.dictConfig(d)\n" -" lp = threading.Thread(target=logger_thread, args=(q,))\n" -" lp.start()\n" -" # At this point, the main process could do some useful work of its own\n" -" # Once it's done that, it can wait for the workers to terminate...\n" -" for wp in workers:\n" -" wp.join()\n" -" # And now tell the logging thread to finish up, too\n" -" q.put(None)\n" -" lp.join()" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1512 -msgid "" -"This variant shows how you can e.g. apply configuration for particular " -"loggers - e.g. the ``foo`` logger has a special handler which stores all " -"events in the ``foo`` subsystem in a file ``mplog-foo.log``. This will be " -"used by the logging machinery in the main process (even though the logging " -"events are generated in the worker processes) to direct the messages to the " -"appropriate destinations." -msgstr "" - -#: ../../howto/logging-cookbook.rst:1519 -msgid "Using concurrent.futures.ProcessPoolExecutor" -msgstr "使用 concurrent.futures.ProcessPoolExecutor" - -#: ../../howto/logging-cookbook.rst:1521 -msgid "" -"If you want to use :class:`concurrent.futures.ProcessPoolExecutor` to start " -"your worker processes, you need to create the queue slightly differently. " -"Instead of" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1525 -msgid "queue = multiprocessing.Queue(-1)" -msgstr "queue = multiprocessing.Queue(-1)" - -#: ../../howto/logging-cookbook.rst:1529 -msgid "you should use" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1531 -msgid "" -"queue = multiprocessing.Manager().Queue(-1) # also works with the examples " -"above" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1535 -msgid "and you can then replace the worker creation from this::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1537 -msgid "" -"workers = []\n" -"for i in range(10):\n" -" worker = multiprocessing.Process(target=worker_process,\n" -" args=(queue, worker_configurer))\n" -" workers.append(worker)\n" -" worker.start()\n" -"for w in workers:\n" -" w.join()" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1546 -msgid "to this (remembering to first import :mod:`concurrent.futures`)::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1548 -msgid "" -"with concurrent.futures.ProcessPoolExecutor(max_workers=10) as executor:\n" -" for i in range(10):\n" -" executor.submit(worker_process, queue, worker_configurer)" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1553 -msgid "Deploying Web applications using Gunicorn and uWSGI" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1555 -msgid "" -"When deploying Web applications using `Gunicorn `_ or " -"`uWSGI `_ (or similar), " -"multiple worker processes are created to handle client requests. In such " -"environments, avoid creating file-based handlers directly in your web " -"application. Instead, use a :class:`SocketHandler` to log from the web " -"application to a listener in a separate process. This can be set up using a " -"process management tool such as Supervisor - see `Running a logging socket " -"listener in production`_ for more details." -msgstr "" - -#: ../../howto/logging-cookbook.rst:1565 -msgid "Using file rotation" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1570 -msgid "" -"Sometimes you want to let a log file grow to a certain size, then open a new " -"file and log to that. You may want to keep a certain number of these files, " -"and when that many files have been created, rotate the files so that the " -"number of files and the size of the files both remain bounded. For this " -"usage pattern, the logging package provides a :class:`RotatingFileHandler`::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1576 -msgid "" -"import glob\n" -"import logging\n" -"import logging.handlers\n" -"\n" -"LOG_FILENAME = 'logging_rotatingfile_example.out'\n" -"\n" -"# Set up a specific logger with our desired output level\n" -"my_logger = logging.getLogger('MyLogger')\n" -"my_logger.setLevel(logging.DEBUG)\n" -"\n" -"# Add the log message handler to the logger\n" -"handler = logging.handlers.RotatingFileHandler(\n" -" LOG_FILENAME, maxBytes=20, backupCount=5)\n" -"\n" -"my_logger.addHandler(handler)\n" -"\n" -"# Log some messages\n" -"for i in range(20):\n" -" my_logger.debug('i = %d' % i)\n" -"\n" -"# See what files are created\n" -"logfiles = glob.glob('%s*' % LOG_FILENAME)\n" -"\n" -"for filename in logfiles:\n" -" print(filename)" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1602 -msgid "" -"The result should be 6 separate files, each with part of the log history for " -"the application:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1605 -msgid "" -"logging_rotatingfile_example.out\n" -"logging_rotatingfile_example.out.1\n" -"logging_rotatingfile_example.out.2\n" -"logging_rotatingfile_example.out.3\n" -"logging_rotatingfile_example.out.4\n" -"logging_rotatingfile_example.out.5" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1614 -msgid "" -"The most current file is always :file:`logging_rotatingfile_example.out`, " -"and each time it reaches the size limit it is renamed with the suffix " -"``.1``. Each of the existing backup files is renamed to increment the suffix " -"(``.1`` becomes ``.2``, etc.) and the ``.6`` file is erased." -msgstr "" - -#: ../../howto/logging-cookbook.rst:1619 -msgid "" -"Obviously this example sets the log length much too small as an extreme " -"example. You would want to set *maxBytes* to an appropriate value." -msgstr "" - -#: ../../howto/logging-cookbook.rst:1627 -msgid "Use of alternative formatting styles" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1629 -msgid "" -"When logging was added to the Python standard library, the only way of " -"formatting messages with variable content was to use the %-formatting " -"method. Since then, Python has gained two new formatting " -"approaches: :class:`string.Template` (added in Python 2.4) " -"and :meth:`str.format` (added in Python 2.6)." -msgstr "" - -#: ../../howto/logging-cookbook.rst:1635 -msgid "" -"Logging (as of 3.2) provides improved support for these two additional " -"formatting styles. The :class:`Formatter` class been enhanced to take an " -"additional, optional keyword parameter named ``style``. This defaults to " -"``'%'``, but other possible values are ``'{'`` and ``'$'``, which correspond " -"to the other two formatting styles. Backwards compatibility is maintained by " -"default (as you would expect), but by explicitly specifying a style " -"parameter, you get the ability to specify format strings which work " -"with :meth:`str.format` or :class:`string.Template`. Here's an example " -"console session to show the possibilities:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1645 -msgid "" -">>> import logging\n" -">>> root = logging.getLogger()\n" -">>> root.setLevel(logging.DEBUG)\n" -">>> handler = logging.StreamHandler()\n" -">>> bf = logging.Formatter('{asctime} {name} {levelname:8s} {message}',\n" -"... style='{')\n" -">>> handler.setFormatter(bf)\n" -">>> root.addHandler(handler)\n" -">>> logger = logging.getLogger('foo.bar')\n" -">>> logger.debug('This is a DEBUG message')\n" -"2010-10-28 15:11:55,341 foo.bar DEBUG This is a DEBUG message\n" -">>> logger.critical('This is a CRITICAL message')\n" -"2010-10-28 15:12:11,526 foo.bar CRITICAL This is a CRITICAL message\n" -">>> df = logging.Formatter('$asctime $name ${levelname} $message',\n" -"... style='$')\n" -">>> handler.setFormatter(df)\n" -">>> logger.debug('This is a DEBUG message')\n" -"2010-10-28 15:13:06,924 foo.bar DEBUG This is a DEBUG message\n" -">>> logger.critical('This is a CRITICAL message')\n" -"2010-10-28 15:13:11,494 foo.bar CRITICAL This is a CRITICAL message\n" -">>>" -msgstr "" -">>> import logging\n" -">>> root = logging.getLogger()\n" -">>> root.setLevel(logging.DEBUG)\n" -">>> handler = logging.StreamHandler()\n" -">>> bf = logging.Formatter('{asctime} {name} {levelname:8s} {message}',\n" -"... style='{')\n" -">>> handler.setFormatter(bf)\n" -">>> root.addHandler(handler)\n" -">>> logger = logging.getLogger('foo.bar')\n" -">>> logger.debug('This is a DEBUG message')\n" -"2010-10-28 15:11:55,341 foo.bar DEBUG This is a DEBUG message\n" -">>> logger.critical('This is a CRITICAL message')\n" -"2010-10-28 15:12:11,526 foo.bar CRITICAL This is a CRITICAL message\n" -">>> df = logging.Formatter('$asctime $name ${levelname} $message',\n" -"... style='$')\n" -">>> handler.setFormatter(df)\n" -">>> logger.debug('This is a DEBUG message')\n" -"2010-10-28 15:13:06,924 foo.bar DEBUG This is a DEBUG message\n" -">>> logger.critical('This is a CRITICAL message')\n" -"2010-10-28 15:13:11,494 foo.bar CRITICAL This is a CRITICAL message\n" -">>>" - -#: ../../howto/logging-cookbook.rst:1669 -msgid "" -"Note that the formatting of logging messages for final output to logs is " -"completely independent of how an individual logging message is constructed. " -"That can still use %-formatting, as shown here::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1673 -msgid "" -">>> logger.error('This is an%s %s %s', 'other,', 'ERROR,', 'message')\n" -"2010-10-28 15:19:29,833 foo.bar ERROR This is another, ERROR, message\n" -">>>" -msgstr "" -">>> logger.error('This is an%s %s %s', 'other,', 'ERROR,', 'message')\n" -"2010-10-28 15:19:29,833 foo.bar ERROR This is another, ERROR, message\n" -">>>" - -#: ../../howto/logging-cookbook.rst:1677 -msgid "" -"Logging calls (``logger.debug()``, ``logger.info()`` etc.) only take " -"positional parameters for the actual logging message itself, with keyword " -"parameters used only for determining options for how to handle the actual " -"logging call (e.g. the ``exc_info`` keyword parameter to indicate that " -"traceback information should be logged, or the ``extra`` keyword parameter " -"to indicate additional contextual information to be added to the log). So " -"you cannot directly make logging calls using :meth:`str.format` " -"or :class:`string.Template` syntax, because internally the logging package " -"uses %-formatting to merge the format string and the variable arguments. " -"There would be no changing this while preserving backward compatibility, " -"since all logging calls which are out there in existing code will be using %-" -"format strings." -msgstr "" - -#: ../../howto/logging-cookbook.rst:1690 -msgid "" -"There is, however, a way that you can use {}- and $- formatting to construct " -"your individual log messages. Recall that for a message you can use an " -"arbitrary object as a message format string, and that the logging package " -"will call ``str()`` on that object to get the actual format string. Consider " -"the following two classes::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1696 ../../howto/logging-cookbook.rst:2784 -msgid "" -"class BraceMessage:\n" -" def __init__(self, fmt, /, *args, **kwargs):\n" -" self.fmt = fmt\n" -" self.args = args\n" -" self.kwargs = kwargs\n" -"\n" -" def __str__(self):\n" -" return self.fmt.format(*self.args, **self.kwargs)\n" -"\n" -"class DollarMessage:\n" -" def __init__(self, fmt, /, **kwargs):\n" -" self.fmt = fmt\n" -" self.kwargs = kwargs\n" -"\n" -" def __str__(self):\n" -" from string import Template\n" -" return Template(self.fmt).substitute(**self.kwargs)" -msgstr "" -"class BraceMessage:\n" -" def __init__(self, fmt, /, *args, **kwargs):\n" -" self.fmt = fmt\n" -" self.args = args\n" -" self.kwargs = kwargs\n" -"\n" -" def __str__(self):\n" -" return self.fmt.format(*self.args, **self.kwargs)\n" -"\n" -"class DollarMessage:\n" -" def __init__(self, fmt, /, **kwargs):\n" -" self.fmt = fmt\n" -" self.kwargs = kwargs\n" -"\n" -" def __str__(self):\n" -" from string import Template\n" -" return Template(self.fmt).substitute(**self.kwargs)" - -#: ../../howto/logging-cookbook.rst:1714 -msgid "" -"Either of these can be used in place of a format string, to allow {}- or $-" -"formatting to be used to build the actual \"message\" part which appears in " -"the formatted log output in place of \"%(message)s\" or \"{message}\" or " -"\"$message\". It's a little unwieldy to use the class names whenever you " -"want to log something, but it's quite palatable if you use an alias such as " -"__ (double underscore --- not to be confused with _, the single underscore " -"used as a synonym/alias for :func:`gettext.gettext` or its brethren)." -msgstr "" - -#: ../../howto/logging-cookbook.rst:1722 -msgid "" -"The above classes are not included in Python, though they're easy enough to " -"copy and paste into your own code. They can be used as follows (assuming " -"that they're declared in a module called ``wherever``):" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1726 -msgid "" -">>> from wherever import BraceMessage as __\n" -">>> print(__('Message with {0} {name}', 2, name='placeholders'))\n" -"Message with 2 placeholders\n" -">>> class Point: pass\n" -"...\n" -">>> p = Point()\n" -">>> p.x = 0.5\n" -">>> p.y = 0.5\n" -">>> print(__('Message with coordinates: ({point.x:.2f}, {point.y:.2f})',\n" -"... point=p))\n" -"Message with coordinates: (0.50, 0.50)\n" -">>> from wherever import DollarMessage as __\n" -">>> print(__('Message with $num $what', num=2, what='placeholders'))\n" -"Message with 2 placeholders\n" -">>>" -msgstr "" -">>> from wherever import BraceMessage as __\n" -">>> print(__('Message with {0} {name}', 2, name='placeholders'))\n" -"Message with 2 placeholders\n" -">>> class Point: pass\n" -"...\n" -">>> p = Point()\n" -">>> p.x = 0.5\n" -">>> p.y = 0.5\n" -">>> print(__('Message with coordinates: ({point.x:.2f}, {point.y:.2f})',\n" -"... point=p))\n" -"Message with coordinates: (0.50, 0.50)\n" -">>> from wherever import DollarMessage as __\n" -">>> print(__('Message with $num $what', num=2, what='placeholders'))\n" -"Message with 2 placeholders\n" -">>>" - -#: ../../howto/logging-cookbook.rst:1744 -msgid "" -"While the above examples use ``print()`` to show how the formatting works, " -"you would of course use ``logger.debug()`` or similar to actually log using " -"this approach." -msgstr "" - -#: ../../howto/logging-cookbook.rst:1748 -msgid "" -"One thing to note is that you pay no significant performance penalty with " -"this approach: the actual formatting happens not when you make the logging " -"call, but when (and if) the logged message is actually about to be output to " -"a log by a handler. So the only slightly unusual thing which might trip you " -"up is that the parentheses go around the format string and the arguments, " -"not just the format string. That's because the __ notation is just syntax " -"sugar for a constructor call to one of the :samp:`{XXX}Message` classes." -msgstr "" - -#: ../../howto/logging-cookbook.rst:1756 -msgid "" -"If you prefer, you can use a :class:`LoggerAdapter` to achieve a similar " -"effect to the above, as in the following example::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1759 -msgid "" -"import logging\n" -"\n" -"class Message:\n" -" def __init__(self, fmt, args):\n" -" self.fmt = fmt\n" -" self.args = args\n" -"\n" -" def __str__(self):\n" -" return self.fmt.format(*self.args)\n" -"\n" -"class StyleAdapter(logging.LoggerAdapter):\n" -" def log(self, level, msg, /, *args, stacklevel=1, **kwargs):\n" -" if self.isEnabledFor(level):\n" -" msg, kwargs = self.process(msg, kwargs)\n" -" self.logger.log(level, Message(msg, args), **kwargs,\n" -" stacklevel=stacklevel+1)\n" -"\n" -"logger = StyleAdapter(logging.getLogger(__name__))\n" -"\n" -"def main():\n" -" logger.debug('Hello, {}', 'world!')\n" -"\n" -"if __name__ == '__main__':\n" -" logging.basicConfig(level=logging.DEBUG)\n" -" main()" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1785 -msgid "" -"The above script should log the message ``Hello, world!`` when run with " -"Python 3.8 or later." -msgstr "" - -#: ../../howto/logging-cookbook.rst:1794 -msgid "Customizing ``LogRecord``" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1796 -msgid "" -"Every logging event is represented by a :class:`LogRecord` instance. When an " -"event is logged and not filtered out by a logger's level, " -"a :class:`LogRecord` is created, populated with information about the event " -"and then passed to the handlers for that logger (and its ancestors, up to " -"and including the logger where further propagation up the hierarchy is " -"disabled). Before Python 3.2, there were only two places where this creation " -"was done:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1803 -msgid "" -":meth:`Logger.makeRecord`, which is called in the normal process of logging " -"an event. This invoked :class:`LogRecord` directly to create an instance." -msgstr "" - -#: ../../howto/logging-cookbook.rst:1806 -msgid "" -":func:`makeLogRecord`, which is called with a dictionary containing " -"attributes to be added to the LogRecord. This is typically invoked when a " -"suitable dictionary has been received over the network (e.g. in pickle form " -"via a :class:`~handlers.SocketHandler`, or in JSON form via " -"an :class:`~handlers.HTTPHandler`)." -msgstr "" - -#: ../../howto/logging-cookbook.rst:1812 -msgid "" -"This has usually meant that if you need to do anything special with " -"a :class:`LogRecord`, you've had to do one of the following." -msgstr "" - -#: ../../howto/logging-cookbook.rst:1815 -msgid "" -"Create your own :class:`Logger` subclass, which " -"overrides :meth:`Logger.makeRecord`, and set it " -"using :func:`~logging.setLoggerClass` before any loggers that you care about " -"are instantiated." -msgstr "" - -#: ../../howto/logging-cookbook.rst:1818 -msgid "" -"Add a :class:`Filter` to a logger or handler, which does the necessary " -"special manipulation you need when its :meth:`~Filter.filter` method is " -"called." -msgstr "" - -#: ../../howto/logging-cookbook.rst:1822 -msgid "" -"The first approach would be a little unwieldy in the scenario where (say) " -"several different libraries wanted to do different things. Each would " -"attempt to set its own :class:`Logger` subclass, and the one which did this " -"last would win." -msgstr "" - -#: ../../howto/logging-cookbook.rst:1827 -msgid "" -"The second approach works reasonably well for many cases, but does not allow " -"you to e.g. use a specialized subclass of :class:`LogRecord`. Library " -"developers can set a suitable filter on their loggers, but they would have " -"to remember to do this every time they introduced a new logger (which they " -"would do simply by adding new packages or modules and doing ::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1833 -msgid "logger = logging.getLogger(__name__)" -msgstr "logger = logging.getLogger(__name__)" - -#: ../../howto/logging-cookbook.rst:1835 -msgid "" -"at module level). It's probably one too many things to think about. " -"Developers could also add the filter to a :class:`~logging.NullHandler` " -"attached to their top-level logger, but this would not be invoked if an " -"application developer attached a handler to a lower-level library logger --- " -"so output from that handler would not reflect the intentions of the library " -"developer." -msgstr "" - -#: ../../howto/logging-cookbook.rst:1841 -msgid "" -"In Python 3.2 and later, :class:`~logging.LogRecord` creation is done " -"through a factory, which you can specify. The factory is just a callable you " -"can set with :func:`~logging.setLogRecordFactory`, and interrogate " -"with :func:`~logging.getLogRecordFactory`. The factory is invoked with the " -"same signature as the :class:`~logging.LogRecord` constructor, " -"as :class:`LogRecord` is the default setting for the factory." -msgstr "" - -#: ../../howto/logging-cookbook.rst:1848 -msgid "" -"This approach allows a custom factory to control all aspects of LogRecord " -"creation. For example, you could return a subclass, or just add some " -"additional attributes to the record once created, using a pattern similar to " -"this::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1852 -msgid "" -"old_factory = logging.getLogRecordFactory()\n" -"\n" -"def record_factory(*args, **kwargs):\n" -" record = old_factory(*args, **kwargs)\n" -" record.custom_attribute = 0xdecafbad\n" -" return record\n" -"\n" -"logging.setLogRecordFactory(record_factory)" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1861 -msgid "" -"This pattern allows different libraries to chain factories together, and as " -"long as they don't overwrite each other's attributes or unintentionally " -"overwrite the attributes provided as standard, there should be no surprises. " -"However, it should be borne in mind that each link in the chain adds run-" -"time overhead to all logging operations, and the technique should only be " -"used when the use of a :class:`Filter` does not provide the desired result." -msgstr "" - -#: ../../howto/logging-cookbook.rst:1873 -msgid "Subclassing QueueHandler and QueueListener- a ZeroMQ example" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1876 ../../howto/logging-cookbook.rst:2009 -msgid "Subclass ``QueueHandler``" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1878 -msgid "" -"You can use a :class:`QueueHandler` subclass to send messages to other kinds " -"of queues, for example a ZeroMQ 'publish' socket. In the example below,the " -"socket is created separately and passed to the handler (as its 'queue')::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1882 -msgid "" -"import zmq # using pyzmq, the Python binding for ZeroMQ\n" -"import json # for serializing records portably\n" -"\n" -"ctx = zmq.Context()\n" -"sock = zmq.Socket(ctx, zmq.PUB) # or zmq.PUSH, or other suitable value\n" -"sock.bind('tcp://*:5556') # or wherever\n" -"\n" -"class ZeroMQSocketHandler(QueueHandler):\n" -" def enqueue(self, record):\n" -" self.queue.send_json(record.__dict__)\n" -"\n" -"\n" -"handler = ZeroMQSocketHandler(sock)" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1897 -msgid "" -"Of course there are other ways of organizing this, for example passing in " -"the data needed by the handler to create the socket::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1900 -msgid "" -"class ZeroMQSocketHandler(QueueHandler):\n" -" def __init__(self, uri, socktype=zmq.PUB, ctx=None):\n" -" self.ctx = ctx or zmq.Context()\n" -" socket = zmq.Socket(self.ctx, socktype)\n" -" socket.bind(uri)\n" -" super().__init__(socket)\n" -"\n" -" def enqueue(self, record):\n" -" self.queue.send_json(record.__dict__)\n" -"\n" -" def close(self):\n" -" self.queue.close()" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1915 ../../howto/logging-cookbook.rst:1945 -msgid "Subclass ``QueueListener``" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1917 -msgid "" -"You can also subclass :class:`QueueListener` to get messages from other " -"kinds of queues, for example a ZeroMQ 'subscribe' socket. Here's an example::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1920 -msgid "" -"class ZeroMQSocketListener(QueueListener):\n" -" def __init__(self, uri, /, *handlers, **kwargs):\n" -" self.ctx = kwargs.get('ctx') or zmq.Context()\n" -" socket = zmq.Socket(self.ctx, zmq.SUB)\n" -" socket.setsockopt_string(zmq.SUBSCRIBE, '') # subscribe to " -"everything\n" -" socket.connect(uri)\n" -" super().__init__(socket, *handlers, **kwargs)\n" -"\n" -" def dequeue(self):\n" -" msg = self.queue.recv_json()\n" -" return logging.makeLogRecord(msg)" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1935 -msgid "Subclassing QueueHandler and QueueListener- a ``pynng`` example" -msgstr "" - -#: ../../howto/logging-cookbook.rst:1937 -msgid "" -"In a similar way to the above section, we can implement a listener and " -"handler using :pypi:`pynng`, which is a Python binding to `NNG `_, billed as a spiritual successor to ZeroMQ. The " -"following snippets illustrate -- you can test them in an environment which " -"has ``pynng`` installed. Just for variety, we present the listener first." -msgstr "" - -#: ../../howto/logging-cookbook.rst:1947 -msgid "" -"# listener.py\n" -"import json\n" -"import logging\n" -"import logging.handlers\n" -"\n" -"import pynng\n" -"\n" -"DEFAULT_ADDR = \"tcp://localhost:13232\"\n" -"\n" -"interrupted = False\n" -"\n" -"class NNGSocketListener(logging.handlers.QueueListener):\n" -"\n" -" def __init__(self, uri, /, *handlers, **kwargs):\n" -" # Have a timeout for interruptability, and open a\n" -" # subscriber socket\n" -" socket = pynng.Sub0(listen=uri, recv_timeout=500)\n" -" # The b'' subscription matches all topics\n" -" topics = kwargs.pop('topics', None) or b''\n" -" socket.subscribe(topics)\n" -" # We treat the socket as a queue\n" -" super().__init__(socket, *handlers, **kwargs)\n" -"\n" -" def dequeue(self, block):\n" -" data = None\n" -" # Keep looping while not interrupted and no data received over the\n" -" # socket\n" -" while not interrupted:\n" -" try:\n" -" data = self.queue.recv(block=block)\n" -" break\n" -" except pynng.Timeout:\n" -" pass\n" -" except pynng.Closed: # sometimes happens when you hit Ctrl-C\n" -" break\n" -" if data is None:\n" -" return None\n" -" # Get the logging event sent from a publisher\n" -" event = json.loads(data.decode('utf-8'))\n" -" return logging.makeLogRecord(event)\n" -"\n" -" def enqueue_sentinel(self):\n" -" # Not used in this implementation, as the socket isn't really a\n" -" # queue\n" -" pass\n" -"\n" -"logging.getLogger('pynng').propagate = False\n" -"listener = NNGSocketListener(DEFAULT_ADDR, logging.StreamHandler(), " -"topics=b'')\n" -"listener.start()\n" -"print('Press Ctrl-C to stop.')\n" -"try:\n" -" while True:\n" -" pass\n" -"except KeyboardInterrupt:\n" -" interrupted = True\n" -"finally:\n" -" listener.stop()" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2013 -msgid "" -"# sender.py\n" -"import json\n" -"import logging\n" -"import logging.handlers\n" -"import time\n" -"import random\n" -"\n" -"import pynng\n" -"\n" -"DEFAULT_ADDR = \"tcp://localhost:13232\"\n" -"\n" -"class NNGSocketHandler(logging.handlers.QueueHandler):\n" -"\n" -" def __init__(self, uri):\n" -" socket = pynng.Pub0(dial=uri, send_timeout=500)\n" -" super().__init__(socket)\n" -"\n" -" def enqueue(self, record):\n" -" # Send the record as UTF-8 encoded JSON\n" -" d = dict(record.__dict__)\n" -" data = json.dumps(d)\n" -" self.queue.send(data.encode('utf-8'))\n" -"\n" -" def close(self):\n" -" self.queue.close()\n" -"\n" -"logging.getLogger('pynng').propagate = False\n" -"handler = NNGSocketHandler(DEFAULT_ADDR)\n" -"# Make sure the process ID is in the output\n" -"logging.basicConfig(level=logging.DEBUG,\n" -" handlers=[logging.StreamHandler(), handler],\n" -" format='%(levelname)-8s %(name)10s %(process)6s %" -"(message)s')\n" -"levels = (logging.DEBUG, logging.INFO, logging.WARNING, logging.ERROR,\n" -" logging.CRITICAL)\n" -"logger_names = ('myapp', 'myapp.lib1', 'myapp.lib2')\n" -"msgno = 1\n" -"while True:\n" -" # Just randomly select some loggers and levels and log away\n" -" level = random.choice(levels)\n" -" logger = logging.getLogger(random.choice(logger_names))\n" -" logger.log(level, 'Message no. %5d' % msgno)\n" -" msgno += 1\n" -" delay = random.random() * 2 + 0.5\n" -" time.sleep(delay)" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2060 -msgid "" -"You can run the above two snippets in separate command shells. If we run the " -"listener in one shell and run the sender in two separate shells, we should " -"see something like the following. In the first sender shell:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2064 -msgid "" -"$ python sender.py\n" -"DEBUG myapp 613 Message no. 1\n" -"WARNING myapp.lib2 613 Message no. 2\n" -"CRITICAL myapp.lib2 613 Message no. 3\n" -"WARNING myapp.lib2 613 Message no. 4\n" -"CRITICAL myapp.lib1 613 Message no. 5\n" -"DEBUG myapp 613 Message no. 6\n" -"CRITICAL myapp.lib1 613 Message no. 7\n" -"INFO myapp.lib1 613 Message no. 8\n" -"(and so on)" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2077 -msgid "In the second sender shell:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2079 -msgid "" -"$ python sender.py\n" -"INFO myapp.lib2 657 Message no. 1\n" -"CRITICAL myapp.lib2 657 Message no. 2\n" -"CRITICAL myapp 657 Message no. 3\n" -"CRITICAL myapp.lib1 657 Message no. 4\n" -"INFO myapp.lib1 657 Message no. 5\n" -"WARNING myapp.lib2 657 Message no. 6\n" -"CRITICAL myapp 657 Message no. 7\n" -"DEBUG myapp.lib1 657 Message no. 8\n" -"(and so on)" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2092 -msgid "In the listener shell:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2094 -msgid "" -"$ python listener.py\n" -"Press Ctrl-C to stop.\n" -"DEBUG myapp 613 Message no. 1\n" -"WARNING myapp.lib2 613 Message no. 2\n" -"INFO myapp.lib2 657 Message no. 1\n" -"CRITICAL myapp.lib2 613 Message no. 3\n" -"CRITICAL myapp.lib2 657 Message no. 2\n" -"CRITICAL myapp 657 Message no. 3\n" -"WARNING myapp.lib2 613 Message no. 4\n" -"CRITICAL myapp.lib1 613 Message no. 5\n" -"CRITICAL myapp.lib1 657 Message no. 4\n" -"INFO myapp.lib1 657 Message no. 5\n" -"DEBUG myapp 613 Message no. 6\n" -"WARNING myapp.lib2 657 Message no. 6\n" -"CRITICAL myapp 657 Message no. 7\n" -"CRITICAL myapp.lib1 613 Message no. 7\n" -"INFO myapp.lib1 613 Message no. 8\n" -"DEBUG myapp.lib1 657 Message no. 8\n" -"(and so on)" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2116 -msgid "" -"As you can see, the logging from the two sender processes is interleaved in " -"the listener's output." -msgstr "" - -#: ../../howto/logging-cookbook.rst:2121 -msgid "An example dictionary-based configuration" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2123 -msgid "" -"Below is an example of a logging configuration dictionary - it's taken from " -"the `documentation on the Django project `_. This dictionary is passed " -"to :func:`~config.dictConfig` to put the configuration into effect::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2127 -msgid "" -"LOGGING = {\n" -" 'version': 1,\n" -" 'disable_existing_loggers': False,\n" -" 'formatters': {\n" -" 'verbose': {\n" -" 'format': '{levelname} {asctime} {module} {process:d} {thread:d} " -"{message}',\n" -" 'style': '{',\n" -" },\n" -" 'simple': {\n" -" 'format': '{levelname} {message}',\n" -" 'style': '{',\n" -" },\n" -" },\n" -" 'filters': {\n" -" 'special': {\n" -" '()': 'project.logging.SpecialFilter',\n" -" 'foo': 'bar',\n" -" },\n" -" },\n" -" 'handlers': {\n" -" 'console': {\n" -" 'level': 'INFO',\n" -" 'class': 'logging.StreamHandler',\n" -" 'formatter': 'simple',\n" -" },\n" -" 'mail_admins': {\n" -" 'level': 'ERROR',\n" -" 'class': 'django.utils.log.AdminEmailHandler',\n" -" 'filters': ['special']\n" -" }\n" -" },\n" -" 'loggers': {\n" -" 'django': {\n" -" 'handlers': ['console'],\n" -" 'propagate': True,\n" -" },\n" -" 'django.request': {\n" -" 'handlers': ['mail_admins'],\n" -" 'level': 'ERROR',\n" -" 'propagate': False,\n" -" },\n" -" 'myproject.custom': {\n" -" 'handlers': ['console', 'mail_admins'],\n" -" 'level': 'INFO',\n" -" 'filters': ['special']\n" -" }\n" -" }\n" -"}" -msgstr "" -"LOGGING = {\n" -" 'version': 1,\n" -" 'disable_existing_loggers': False,\n" -" 'formatters': {\n" -" 'verbose': {\n" -" 'format': '{levelname} {asctime} {module} {process:d} {thread:d} " -"{message}',\n" -" 'style': '{',\n" -" },\n" -" 'simple': {\n" -" 'format': '{levelname} {message}',\n" -" 'style': '{',\n" -" },\n" -" },\n" -" 'filters': {\n" -" 'special': {\n" -" '()': 'project.logging.SpecialFilter',\n" -" 'foo': 'bar',\n" -" },\n" -" },\n" -" 'handlers': {\n" -" 'console': {\n" -" 'level': 'INFO',\n" -" 'class': 'logging.StreamHandler',\n" -" 'formatter': 'simple',\n" -" },\n" -" 'mail_admins': {\n" -" 'level': 'ERROR',\n" -" 'class': 'django.utils.log.AdminEmailHandler',\n" -" 'filters': ['special']\n" -" }\n" -" },\n" -" 'loggers': {\n" -" 'django': {\n" -" 'handlers': ['console'],\n" -" 'propagate': True,\n" -" },\n" -" 'django.request': {\n" -" 'handlers': ['mail_admins'],\n" -" 'level': 'ERROR',\n" -" 'propagate': False,\n" -" },\n" -" 'myproject.custom': {\n" -" 'handlers': ['console', 'mail_admins'],\n" -" 'level': 'INFO',\n" -" 'filters': ['special']\n" -" }\n" -" }\n" -"}" - -#: ../../howto/logging-cookbook.rst:2176 -msgid "" -"For more information about this configuration, you can see the `relevant " -"section `_ of the Django documentation." -msgstr "" - -#: ../../howto/logging-cookbook.rst:2183 -msgid "Using a rotator and namer to customize log rotation processing" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2185 -msgid "" -"An example of how you can define a namer and rotator is given in the " -"following runnable script, which shows gzip compression of the log file::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2188 -msgid "" -"import gzip\n" -"import logging\n" -"import logging.handlers\n" -"import os\n" -"import shutil\n" -"\n" -"def namer(name):\n" -" return name + \".gz\"\n" -"\n" -"def rotator(source, dest):\n" -" with open(source, 'rb') as f_in:\n" -" with gzip.open(dest, 'wb') as f_out:\n" -" shutil.copyfileobj(f_in, f_out)\n" -" os.remove(source)\n" -"\n" -"\n" -"rh = logging.handlers.RotatingFileHandler('rotated.log', maxBytes=128, " -"backupCount=5)\n" -"rh.rotator = rotator\n" -"rh.namer = namer\n" -"\n" -"root = logging.getLogger()\n" -"root.setLevel(logging.INFO)\n" -"root.addHandler(rh)\n" -"f = logging.Formatter('%(asctime)s %(message)s')\n" -"rh.setFormatter(f)\n" -"for i in range(1000):\n" -" root.info(f'Message no. {i + 1}')" -msgstr "" -"import gzip\n" -"import logging\n" -"import logging.handlers\n" -"import os\n" -"import shutil\n" -"\n" -"def namer(name):\n" -" return name + \".gz\"\n" -"\n" -"def rotator(source, dest):\n" -" with open(source, 'rb') as f_in:\n" -" with gzip.open(dest, 'wb') as f_out:\n" -" shutil.copyfileobj(f_in, f_out)\n" -" os.remove(source)\n" -"\n" -"\n" -"rh = logging.handlers.RotatingFileHandler('rotated.log', maxBytes=128, " -"backupCount=5)\n" -"rh.rotator = rotator\n" -"rh.namer = namer\n" -"\n" -"root = logging.getLogger()\n" -"root.setLevel(logging.INFO)\n" -"root.addHandler(rh)\n" -"f = logging.Formatter('%(asctime)s %(message)s')\n" -"rh.setFormatter(f)\n" -"for i in range(1000):\n" -" root.info(f'Message no. {i + 1}')" - -#: ../../howto/logging-cookbook.rst:2216 -msgid "" -"After running this, you will see six new files, five of which are compressed:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2218 -msgid "" -"$ ls rotated.log*\n" -"rotated.log rotated.log.2.gz rotated.log.4.gz\n" -"rotated.log.1.gz rotated.log.3.gz rotated.log.5.gz\n" -"$ zcat rotated.log.1.gz\n" -"2023-01-20 02:28:17,767 Message no. 996\n" -"2023-01-20 02:28:17,767 Message no. 997\n" -"2023-01-20 02:28:17,767 Message no. 998" -msgstr "" -"$ ls rotated.log*\n" -"rotated.log rotated.log.2.gz rotated.log.4.gz\n" -"rotated.log.1.gz rotated.log.3.gz rotated.log.5.gz\n" -"$ zcat rotated.log.1.gz\n" -"2023-01-20 02:28:17,767 Message no. 996\n" -"2023-01-20 02:28:17,767 Message no. 997\n" -"2023-01-20 02:28:17,767 Message no. 998" - -#: ../../howto/logging-cookbook.rst:2229 -msgid "A more elaborate multiprocessing example" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2231 -msgid "" -"The following working example shows how logging can be used with " -"multiprocessing using configuration files. The configurations are fairly " -"simple, but serve to illustrate how more complex ones could be implemented " -"in a real multiprocessing scenario." -msgstr "" - -#: ../../howto/logging-cookbook.rst:2236 -msgid "" -"In the example, the main process spawns a listener process and some worker " -"processes. Each of the main process, the listener and the workers have three " -"separate configurations (the workers all share the same configuration). We " -"can see logging in the main process, how the workers log to a QueueHandler " -"and how the listener implements a QueueListener and a more complex logging " -"configuration, and arranges to dispatch events received via the queue to the " -"handlers specified in the configuration. Note that these configurations are " -"purely illustrative, but you should be able to adapt this example to your " -"own scenario." -msgstr "" - -#: ../../howto/logging-cookbook.rst:2246 -msgid "" -"Here's the script - the docstrings and the comments hopefully explain how it " -"works::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2249 -msgid "" -"import logging\n" -"import logging.config\n" -"import logging.handlers\n" -"from multiprocessing import Process, Queue, Event, current_process\n" -"import os\n" -"import random\n" -"import time\n" -"\n" -"class MyHandler:\n" -" \"\"\"\n" -" A simple handler for logging events. It runs in the listener process " -"and\n" -" dispatches events to loggers based on the name in the received record,\n" -" which then get dispatched, by the logging system, to the handlers\n" -" configured for those loggers.\n" -" \"\"\"\n" -"\n" -" def handle(self, record):\n" -" if record.name == \"root\":\n" -" logger = logging.getLogger()\n" -" else:\n" -" logger = logging.getLogger(record.name)\n" -"\n" -" if logger.isEnabledFor(record.levelno):\n" -" # The process name is transformed just to show that it's the " -"listener\n" -" # doing the logging to files and console\n" -" record.processName = '%s (for %s)' % (current_process().name, " -"record.processName)\n" -" logger.handle(record)\n" -"\n" -"def listener_process(q, stop_event, config):\n" -" \"\"\"\n" -" This could be done in the main process, but is just done in a separate\n" -" process for illustrative purposes.\n" -"\n" -" This initialises logging according to the specified configuration,\n" -" starts the listener and waits for the main process to signal completion\n" -" via the event. The listener is then stopped, and the process exits.\n" -" \"\"\"\n" -" logging.config.dictConfig(config)\n" -" listener = logging.handlers.QueueListener(q, MyHandler())\n" -" listener.start()\n" -" if os.name == 'posix':\n" -" # On POSIX, the setup logger will have been configured in the\n" -" # parent process, but should have been disabled following the\n" -" # dictConfig call.\n" -" # On Windows, since fork isn't used, the setup logger won't\n" -" # exist in the child, so it would be created and the message\n" -" # would appear - hence the \"if posix\" clause.\n" -" logger = logging.getLogger('setup')\n" -" logger.critical('Should not appear, because of disabled " -"logger ...')\n" -" stop_event.wait()\n" -" listener.stop()\n" -"\n" -"def worker_process(config):\n" -" \"\"\"\n" -" A number of these are spawned for the purpose of illustration. In\n" -" practice, they could be a heterogeneous bunch of processes rather than\n" -" ones which are identical to each other.\n" -"\n" -" This initialises logging according to the specified configuration,\n" -" and logs a hundred messages with random levels to randomly selected\n" -" loggers.\n" -"\n" -" A small sleep is added to allow other processes a chance to run. This\n" -" is not strictly needed, but it mixes the output from the different\n" -" processes a bit more than if it's left out.\n" -" \"\"\"\n" -" logging.config.dictConfig(config)\n" -" levels = [logging.DEBUG, logging.INFO, logging.WARNING, logging.ERROR,\n" -" logging.CRITICAL]\n" -" loggers = ['foo', 'foo.bar', 'foo.bar.baz',\n" -" 'spam', 'spam.ham', 'spam.ham.eggs']\n" -" if os.name == 'posix':\n" -" # On POSIX, the setup logger will have been configured in the\n" -" # parent process, but should have been disabled following the\n" -" # dictConfig call.\n" -" # On Windows, since fork isn't used, the setup logger won't\n" -" # exist in the child, so it would be created and the message\n" -" # would appear - hence the \"if posix\" clause.\n" -" logger = logging.getLogger('setup')\n" -" logger.critical('Should not appear, because of disabled " -"logger ...')\n" -" for i in range(100):\n" -" lvl = random.choice(levels)\n" -" logger = logging.getLogger(random.choice(loggers))\n" -" logger.log(lvl, 'Message no. %d', i)\n" -" time.sleep(0.01)\n" -"\n" -"def main():\n" -" q = Queue()\n" -" # The main process gets a simple configuration which prints to the " -"console.\n" -" config_initial = {\n" -" 'version': 1,\n" -" 'handlers': {\n" -" 'console': {\n" -" 'class': 'logging.StreamHandler',\n" -" 'level': 'INFO'\n" -" }\n" -" },\n" -" 'root': {\n" -" 'handlers': ['console'],\n" -" 'level': 'DEBUG'\n" -" }\n" -" }\n" -" # The worker process configuration is just a QueueHandler attached to " -"the\n" -" # root logger, which allows all messages to be sent to the queue.\n" -" # We disable existing loggers to disable the \"setup\" logger used in " -"the\n" -" # parent process. This is needed on POSIX because the logger will\n" -" # be there in the child following a fork().\n" -" config_worker = {\n" -" 'version': 1,\n" -" 'disable_existing_loggers': True,\n" -" 'handlers': {\n" -" 'queue': {\n" -" 'class': 'logging.handlers.QueueHandler',\n" -" 'queue': q\n" -" }\n" -" },\n" -" 'root': {\n" -" 'handlers': ['queue'],\n" -" 'level': 'DEBUG'\n" -" }\n" -" }\n" -" # The listener process configuration shows that the full flexibility of\n" -" # logging configuration is available to dispatch events to handlers " -"however\n" -" # you want.\n" -" # We disable existing loggers to disable the \"setup\" logger used in " -"the\n" -" # parent process. This is needed on POSIX because the logger will\n" -" # be there in the child following a fork().\n" -" config_listener = {\n" -" 'version': 1,\n" -" 'disable_existing_loggers': True,\n" -" 'formatters': {\n" -" 'detailed': {\n" -" 'class': 'logging.Formatter',\n" -" 'format': '%(asctime)s %(name)-15s %(levelname)-8s %" -"(processName)-10s %(message)s'\n" -" },\n" -" 'simple': {\n" -" 'class': 'logging.Formatter',\n" -" 'format': '%(name)-15s %(levelname)-8s %(processName)-10s %" -"(message)s'\n" -" }\n" -" },\n" -" 'handlers': {\n" -" 'console': {\n" -" 'class': 'logging.StreamHandler',\n" -" 'formatter': 'simple',\n" -" 'level': 'INFO'\n" -" },\n" -" 'file': {\n" -" 'class': 'logging.FileHandler',\n" -" 'filename': 'mplog.log',\n" -" 'mode': 'w',\n" -" 'formatter': 'detailed'\n" -" },\n" -" 'foofile': {\n" -" 'class': 'logging.FileHandler',\n" -" 'filename': 'mplog-foo.log',\n" -" 'mode': 'w',\n" -" 'formatter': 'detailed'\n" -" },\n" -" 'errors': {\n" -" 'class': 'logging.FileHandler',\n" -" 'filename': 'mplog-errors.log',\n" -" 'mode': 'w',\n" -" 'formatter': 'detailed',\n" -" 'level': 'ERROR'\n" -" }\n" -" },\n" -" 'loggers': {\n" -" 'foo': {\n" -" 'handlers': ['foofile']\n" -" }\n" -" },\n" -" 'root': {\n" -" 'handlers': ['console', 'file', 'errors'],\n" -" 'level': 'DEBUG'\n" -" }\n" -" }\n" -" # Log some initial events, just to show that logging in the parent " -"works\n" -" # normally.\n" -" logging.config.dictConfig(config_initial)\n" -" logger = logging.getLogger('setup')\n" -" logger.info('About to create workers ...')\n" -" workers = []\n" -" for i in range(5):\n" -" wp = Process(target=worker_process, name='worker %d' % (i + 1),\n" -" args=(config_worker,))\n" -" workers.append(wp)\n" -" wp.start()\n" -" logger.info('Started worker: %s', wp.name)\n" -" logger.info('About to create listener ...')\n" -" stop_event = Event()\n" -" lp = Process(target=listener_process, name='listener',\n" -" args=(q, stop_event, config_listener))\n" -" lp.start()\n" -" logger.info('Started listener')\n" -" # We now hang around for the workers to finish their work.\n" -" for wp in workers:\n" -" wp.join()\n" -" # Workers all done, listening can now stop.\n" -" # Logging in the parent still works normally.\n" -" logger.info('Telling listener to stop ...')\n" -" stop_event.set()\n" -" lp.join()\n" -" logger.info('All done.')\n" -"\n" -"if __name__ == '__main__':\n" -" main()" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2458 -msgid "Inserting a BOM into messages sent to a SysLogHandler" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2460 -msgid "" -":rfc:`5424` requires that a Unicode message be sent to a syslog daemon as a " -"set of bytes which have the following structure: an optional pure-ASCII " -"component, followed by a UTF-8 Byte Order Mark (BOM), followed by Unicode " -"encoded using UTF-8. (See the :rfc:`relevant section of the specification " -"<5424#section-6>`.)" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2466 -msgid "" -"In Python 3.1, code was added to :class:`~logging.handlers.SysLogHandler` to " -"insert a BOM into the message, but unfortunately, it was implemented " -"incorrectly, with the BOM appearing at the beginning of the message and " -"hence not allowing any pure-ASCII component to appear before it." -msgstr "" - -#: ../../howto/logging-cookbook.rst:2472 -msgid "" -"As this behaviour is broken, the incorrect BOM insertion code is being " -"removed from Python 3.2.4 and later. However, it is not being replaced, and " -"if you want to produce :rfc:`5424`-compliant messages which include a BOM, " -"an optional pure-ASCII sequence before it and arbitrary Unicode after it, " -"encoded using UTF-8, then you need to do the following:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2478 -msgid "" -"Attach a :class:`~logging.Formatter` instance to " -"your :class:`~logging.handlers.SysLogHandler` instance, with a format string " -"such as::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2482 -msgid "'ASCII section\\ufeffUnicode section'" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2484 -msgid "" -"The Unicode code point U+FEFF, when encoded using UTF-8, will be encoded as " -"a UTF-8 BOM -- the byte-string ``b'\\xef\\xbb\\xbf'``." -msgstr "" - -#: ../../howto/logging-cookbook.rst:2487 -msgid "" -"Replace the ASCII section with whatever placeholders you like, but make sure " -"that the data that appears in there after substitution is always ASCII (that " -"way, it will remain unchanged after UTF-8 encoding)." -msgstr "" - -#: ../../howto/logging-cookbook.rst:2491 -msgid "" -"Replace the Unicode section with whatever placeholders you like; if the data " -"which appears there after substitution contains characters outside the ASCII " -"range, that's fine -- it will be encoded using UTF-8." -msgstr "" - -#: ../../howto/logging-cookbook.rst:2495 -msgid "" -"The formatted message *will* be encoded using UTF-8 encoding by " -"``SysLogHandler``. If you follow the above rules, you should be able to " -"produce :rfc:`5424`-compliant messages. If you don't, logging may not " -"complain, but your messages will not be RFC 5424-compliant, and your syslog " -"daemon may complain." -msgstr "" - -#: ../../howto/logging-cookbook.rst:2502 -msgid "Implementing structured logging" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2504 -msgid "" -"Although most logging messages are intended for reading by humans, and thus " -"not readily machine-parseable, there might be circumstances where you want " -"to output messages in a structured format which *is* capable of being parsed " -"by a program (without needing complex regular expressions to parse the log " -"message). This is straightforward to achieve using the logging package. " -"There are a number of ways in which this could be achieved, but the " -"following is a simple approach which uses JSON to serialise the event in a " -"machine-parseable manner::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2512 -msgid "" -"import json\n" -"import logging\n" -"\n" -"class StructuredMessage:\n" -" def __init__(self, message, /, **kwargs):\n" -" self.message = message\n" -" self.kwargs = kwargs\n" -"\n" -" def __str__(self):\n" -" return '%s >>> %s' % (self.message, json.dumps(self.kwargs))\n" -"\n" -"_ = StructuredMessage # optional, to improve readability\n" -"\n" -"logging.basicConfig(level=logging.INFO, format='%(message)s')\n" -"logging.info(_('message 1', foo='bar', bar='baz', num=123, fnum=123.456))" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2528 -msgid "If the above script is run, it prints:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2530 -msgid "" -"message 1 >>> {\"fnum\": 123.456, \"num\": 123, \"bar\": \"baz\", \"foo\": " -"\"bar\"}" -msgstr "" -"message 1 >>> {\"fnum\": 123.456, \"num\": 123, \"bar\": \"baz\", \"foo\": " -"\"bar\"}" - -#: ../../howto/logging-cookbook.rst:2534 ../../howto/logging-cookbook.rst:2576 -msgid "" -"Note that the order of items might be different according to the version of " -"Python used." -msgstr "" - -#: ../../howto/logging-cookbook.rst:2537 -msgid "" -"If you need more specialised processing, you can use a custom JSON encoder, " -"as in the following complete example::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2540 -msgid "" -"import json\n" -"import logging\n" -"\n" -"\n" -"class Encoder(json.JSONEncoder):\n" -" def default(self, o):\n" -" if isinstance(o, set):\n" -" return tuple(o)\n" -" elif isinstance(o, str):\n" -" return o.encode('unicode_escape').decode('ascii')\n" -" return super().default(o)\n" -"\n" -"class StructuredMessage:\n" -" def __init__(self, message, /, **kwargs):\n" -" self.message = message\n" -" self.kwargs = kwargs\n" -"\n" -" def __str__(self):\n" -" s = Encoder().encode(self.kwargs)\n" -" return '%s >>> %s' % (self.message, s)\n" -"\n" -"_ = StructuredMessage # optional, to improve readability\n" -"\n" -"def main():\n" -" logging.basicConfig(level=logging.INFO, format='%(message)s')\n" -" logging.info(_('message 1', set_value={1, 2, 3}, snowman='\\u2603'))\n" -"\n" -"if __name__ == '__main__':\n" -" main()" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2570 -msgid "When the above script is run, it prints:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2572 -msgid "message 1 >>> {\"snowman\": \"\\u2603\", \"set_value\": [1, 2, 3]}" -msgstr "message 1 >>> {\"snowman\": \"\\u2603\", \"set_value\": [1, 2, 3]}" - -#: ../../howto/logging-cookbook.rst:2585 -msgid "Customizing handlers with :func:`dictConfig`" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2587 -msgid "" -"There are times when you want to customize logging handlers in particular " -"ways, and if you use :func:`dictConfig` you may be able to do this without " -"subclassing. As an example, consider that you may want to set the ownership " -"of a log file. On POSIX, this is easily done using :func:`shutil.chown`, but " -"the file handlers in the stdlib don't offer built-in support. You can " -"customize handler creation using a plain function such as::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2594 -msgid "" -"def owned_file_handler(filename, mode='a', encoding=None, owner=None):\n" -" if owner:\n" -" if not os.path.exists(filename):\n" -" open(filename, 'a').close()\n" -" shutil.chown(filename, *owner)\n" -" return logging.FileHandler(filename, mode, encoding)" -msgstr "" -"def owned_file_handler(filename, mode='a', encoding=None, owner=None):\n" -" if owner:\n" -" if not os.path.exists(filename):\n" -" open(filename, 'a').close()\n" -" shutil.chown(filename, *owner)\n" -" return logging.FileHandler(filename, mode, encoding)" - -#: ../../howto/logging-cookbook.rst:2601 -msgid "" -"You can then specify, in a logging configuration passed " -"to :func:`dictConfig`, that a logging handler be created by calling this " -"function::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2604 -msgid "" -"LOGGING = {\n" -" 'version': 1,\n" -" 'disable_existing_loggers': False,\n" -" 'formatters': {\n" -" 'default': {\n" -" 'format': '%(asctime)s %(levelname)s %(name)s %(message)s'\n" -" },\n" -" },\n" -" 'handlers': {\n" -" 'file':{\n" -" # The values below are popped from this dictionary and\n" -" # used to create the handler, set the handler's level and\n" -" # its formatter.\n" -" '()': owned_file_handler,\n" -" 'level':'DEBUG',\n" -" 'formatter': 'default',\n" -" # The values below are passed to the handler creator callable\n" -" # as keyword arguments.\n" -" 'owner': ['pulse', 'pulse'],\n" -" 'filename': 'chowntest.log',\n" -" 'mode': 'w',\n" -" 'encoding': 'utf-8',\n" -" },\n" -" },\n" -" 'root': {\n" -" 'handlers': ['file'],\n" -" 'level': 'DEBUG',\n" -" },\n" -"}" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2634 -msgid "" -"In this example I am setting the ownership using the ``pulse`` user and " -"group, just for the purposes of illustration. Putting it together into a " -"working script, ``chowntest.py``::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2638 -msgid "" -"import logging, logging.config, os, shutil\n" -"\n" -"def owned_file_handler(filename, mode='a', encoding=None, owner=None):\n" -" if owner:\n" -" if not os.path.exists(filename):\n" -" open(filename, 'a').close()\n" -" shutil.chown(filename, *owner)\n" -" return logging.FileHandler(filename, mode, encoding)\n" -"\n" -"LOGGING = {\n" -" 'version': 1,\n" -" 'disable_existing_loggers': False,\n" -" 'formatters': {\n" -" 'default': {\n" -" 'format': '%(asctime)s %(levelname)s %(name)s %(message)s'\n" -" },\n" -" },\n" -" 'handlers': {\n" -" 'file':{\n" -" # The values below are popped from this dictionary and\n" -" # used to create the handler, set the handler's level and\n" -" # its formatter.\n" -" '()': owned_file_handler,\n" -" 'level':'DEBUG',\n" -" 'formatter': 'default',\n" -" # The values below are passed to the handler creator callable\n" -" # as keyword arguments.\n" -" 'owner': ['pulse', 'pulse'],\n" -" 'filename': 'chowntest.log',\n" -" 'mode': 'w',\n" -" 'encoding': 'utf-8',\n" -" },\n" -" },\n" -" 'root': {\n" -" 'handlers': ['file'],\n" -" 'level': 'DEBUG',\n" -" },\n" -"}\n" -"\n" -"logging.config.dictConfig(LOGGING)\n" -"logger = logging.getLogger('mylogger')\n" -"logger.debug('A debug message')" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2681 -msgid "To run this, you will probably need to run as ``root``:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2683 -msgid "" -"$ sudo python3.3 chowntest.py\n" -"$ cat chowntest.log\n" -"2013-11-05 09:34:51,128 DEBUG mylogger A debug message\n" -"$ ls -l chowntest.log\n" -"-rw-r--r-- 1 pulse pulse 55 2013-11-05 09:34 chowntest.log" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2691 -msgid "" -"Note that this example uses Python 3.3 because that's " -"where :func:`shutil.chown` makes an appearance. This approach should work " -"with any Python version that supports :func:`dictConfig` - namely, Python " -"2.7, 3.2 or later. With pre-3.3 versions, you would need to implement the " -"actual ownership change using e.g. :func:`os.chown`." -msgstr "" - -#: ../../howto/logging-cookbook.rst:2697 -msgid "" -"In practice, the handler-creating function may be in a utility module " -"somewhere in your project. Instead of the line in the configuration::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2700 -msgid "'()': owned_file_handler," -msgstr "'()': owned_file_handler," - -#: ../../howto/logging-cookbook.rst:2702 -msgid "you could use e.g.::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2704 -msgid "'()': 'ext://project.util.owned_file_handler'," -msgstr "'()': 'ext://project.util.owned_file_handler'," - -#: ../../howto/logging-cookbook.rst:2706 -msgid "" -"where ``project.util`` can be replaced with the actual name of the package " -"where the function resides. In the above working script, using ``'ext://" -"__main__.owned_file_handler'`` should work. Here, the actual callable is " -"resolved by :func:`dictConfig` from the ``ext://`` specification." -msgstr "" - -#: ../../howto/logging-cookbook.rst:2711 -msgid "" -"This example hopefully also points the way to how you could implement other " -"types of file change - e.g. setting specific POSIX permission bits - in the " -"same way, using :func:`os.chmod`." -msgstr "" - -#: ../../howto/logging-cookbook.rst:2715 -msgid "" -"Of course, the approach could also be extended to types of handler other " -"than a :class:`~logging.FileHandler` - for example, one of the rotating file " -"handlers, or a different type of handler altogether." -msgstr "" - -#: ../../howto/logging-cookbook.rst:2725 -msgid "Using particular formatting styles throughout your application" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2727 -msgid "" -"In Python 3.2, the :class:`~logging.Formatter` gained a ``style`` keyword " -"parameter which, while defaulting to ``%`` for backward compatibility, " -"allowed the specification of ``{`` or ``$`` to support the formatting " -"approaches supported by :meth:`str.format` and :class:`string.Template`. " -"Note that this governs the formatting of logging messages for final output " -"to logs, and is completely orthogonal to how an individual logging message " -"is constructed." -msgstr "" - -#: ../../howto/logging-cookbook.rst:2734 -msgid "" -"Logging calls (:meth:`~Logger.debug`, :meth:`~Logger.info` etc.) only take " -"positional parameters for the actual logging message itself, with keyword " -"parameters used only for determining options for how to handle the logging " -"call (e.g. the ``exc_info`` keyword parameter to indicate that traceback " -"information should be logged, or the ``extra`` keyword parameter to indicate " -"additional contextual information to be added to the log). So you cannot " -"directly make logging calls using :meth:`str.format` " -"or :class:`string.Template` syntax, because internally the logging package " -"uses %-formatting to merge the format string and the variable arguments. " -"There would be no changing this while preserving backward compatibility, " -"since all logging calls which are out there in existing code will be using %-" -"format strings." -msgstr "" - -#: ../../howto/logging-cookbook.rst:2746 -msgid "" -"There have been suggestions to associate format styles with specific " -"loggers, but that approach also runs into backward compatibility problems " -"because any existing code could be using a given logger name and using %-" -"formatting." -msgstr "" - -#: ../../howto/logging-cookbook.rst:2750 -msgid "" -"For logging to work interoperably between any third-party libraries and your " -"code, decisions about formatting need to be made at the level of the " -"individual logging call. This opens up a couple of ways in which alternative " -"formatting styles can be accommodated." -msgstr "" - -#: ../../howto/logging-cookbook.rst:2757 -msgid "Using LogRecord factories" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2759 -msgid "" -"In Python 3.2, along with the :class:`~logging.Formatter` changes mentioned " -"above, the logging package gained the ability to allow users to set their " -"own :class:`LogRecord` subclasses, using the :func:`setLogRecordFactory` " -"function. You can use this to set your own subclass of :class:`LogRecord`, " -"which does the Right Thing by overriding the :meth:`~LogRecord.getMessage` " -"method. The base class implementation of this method is where the ``msg % " -"args`` formatting happens, and where you can substitute your alternate " -"formatting; however, you should be careful to support all formatting styles " -"and allow %-formatting as the default, to ensure interoperability with other " -"code. Care should also be taken to call ``str(self.msg)``, just as the base " -"implementation does." -msgstr "" - -#: ../../howto/logging-cookbook.rst:2770 -msgid "" -"Refer to the reference documentation on :func:`setLogRecordFactory` " -"and :class:`LogRecord` for more information." -msgstr "" - -#: ../../howto/logging-cookbook.rst:2775 -msgid "Using custom message objects" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2777 -msgid "" -"There is another, perhaps simpler way that you can use {}- and $- formatting " -"to construct your individual log messages. You may recall " -"(from :ref:`arbitrary-object-messages`) that when logging you can use an " -"arbitrary object as a message format string, and that the logging package " -"will call :func:`str` on that object to get the actual format string. " -"Consider the following two classes::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2802 -msgid "" -"Either of these can be used in place of a format string, to allow {}- or $-" -"formatting to be used to build the actual \"message\" part which appears in " -"the formatted log output in place of “%(message)s” or “{message}” or " -"“$message”. If you find it a little unwieldy to use the class names whenever " -"you want to log something, you can make it more palatable if you use an " -"alias such as ``M`` or ``_`` for the message (or perhaps ``__``, if you are " -"using ``_`` for localization)." -msgstr "" - -#: ../../howto/logging-cookbook.rst:2810 -msgid "" -"Examples of this approach are given below. Firstly, formatting " -"with :meth:`str.format`::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2813 -msgid "" -">>> __ = BraceMessage\n" -">>> print(__('Message with {0} {1}', 2, 'placeholders'))\n" -"Message with 2 placeholders\n" -">>> class Point: pass\n" -"...\n" -">>> p = Point()\n" -">>> p.x = 0.5\n" -">>> p.y = 0.5\n" -">>> print(__('Message with coordinates: ({point.x:.2f}, {point.y:.2f})', " -"point=p))\n" -"Message with coordinates: (0.50, 0.50)" -msgstr "" -">>> __ = BraceMessage\n" -">>> print(__('Message with {0} {1}', 2, 'placeholders'))\n" -"Message with 2 placeholders\n" -">>> class Point: pass\n" -"...\n" -">>> p = Point()\n" -">>> p.x = 0.5\n" -">>> p.y = 0.5\n" -">>> print(__('Message with coordinates: ({point.x:.2f}, {point.y:.2f})', " -"point=p))\n" -"Message with coordinates: (0.50, 0.50)" - -#: ../../howto/logging-cookbook.rst:2824 -msgid "Secondly, formatting with :class:`string.Template`::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2826 -msgid "" -">>> __ = DollarMessage\n" -">>> print(__('Message with $num $what', num=2, what='placeholders'))\n" -"Message with 2 placeholders\n" -">>>" -msgstr "" -">>> __ = DollarMessage\n" -">>> print(__('Message with $num $what', num=2, what='placeholders'))\n" -"Message with 2 placeholders\n" -">>>" - -#: ../../howto/logging-cookbook.rst:2831 -msgid "" -"One thing to note is that you pay no significant performance penalty with " -"this approach: the actual formatting happens not when you make the logging " -"call, but when (and if) the logged message is actually about to be output to " -"a log by a handler. So the only slightly unusual thing which might trip you " -"up is that the parentheses go around the format string and the arguments, " -"not just the format string. That’s because the __ notation is just syntax " -"sugar for a constructor call to one of the :samp:`{XXX}Message` classes " -"shown above." -msgstr "" - -#: ../../howto/logging-cookbook.rst:2845 -msgid "Configuring filters with :func:`dictConfig`" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2847 -msgid "" -"You *can* configure filters using :func:`~logging.config.dictConfig`, though " -"it might not be obvious at first glance how to do it (hence this recipe). " -"Since :class:`~logging.Filter` is the only filter class included in the " -"standard library, and it is unlikely to cater to many requirements (it's " -"only there as a base class), you will typically need to define your " -"own :class:`~logging.Filter` subclass with an " -"overridden :meth:`~logging.Filter.filter` method. To do this, specify the " -"``()`` key in the configuration dictionary for the filter, specifying a " -"callable which will be used to create the filter (a class is the most " -"obvious, but you can provide any callable which returns " -"a :class:`~logging.Filter` instance). Here is a complete example::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2858 -msgid "" -"import logging\n" -"import logging.config\n" -"import sys\n" -"\n" -"class MyFilter(logging.Filter):\n" -" def __init__(self, param=None):\n" -" self.param = param\n" -"\n" -" def filter(self, record):\n" -" if self.param is None:\n" -" allow = True\n" -" else:\n" -" allow = self.param not in record.msg\n" -" if allow:\n" -" record.msg = 'changed: ' + record.msg\n" -" return allow\n" -"\n" -"LOGGING = {\n" -" 'version': 1,\n" -" 'filters': {\n" -" 'myfilter': {\n" -" '()': MyFilter,\n" -" 'param': 'noshow',\n" -" }\n" -" },\n" -" 'handlers': {\n" -" 'console': {\n" -" 'class': 'logging.StreamHandler',\n" -" 'filters': ['myfilter']\n" -" }\n" -" },\n" -" 'root': {\n" -" 'level': 'DEBUG',\n" -" 'handlers': ['console']\n" -" },\n" -"}\n" -"\n" -"if __name__ == '__main__':\n" -" logging.config.dictConfig(LOGGING)\n" -" logging.debug('hello')\n" -" logging.debug('hello - noshow')" -msgstr "" -"import logging\n" -"import logging.config\n" -"import sys\n" -"\n" -"class MyFilter(logging.Filter):\n" -" def __init__(self, param=None):\n" -" self.param = param\n" -"\n" -" def filter(self, record):\n" -" if self.param is None:\n" -" allow = True\n" -" else:\n" -" allow = self.param not in record.msg\n" -" if allow:\n" -" record.msg = 'changed: ' + record.msg\n" -" return allow\n" -"\n" -"LOGGING = {\n" -" 'version': 1,\n" -" 'filters': {\n" -" 'myfilter': {\n" -" '()': MyFilter,\n" -" 'param': 'noshow',\n" -" }\n" -" },\n" -" 'handlers': {\n" -" 'console': {\n" -" 'class': 'logging.StreamHandler',\n" -" 'filters': ['myfilter']\n" -" }\n" -" },\n" -" 'root': {\n" -" 'level': 'DEBUG',\n" -" 'handlers': ['console']\n" -" },\n" -"}\n" -"\n" -"if __name__ == '__main__':\n" -" logging.config.dictConfig(LOGGING)\n" -" logging.debug('hello')\n" -" logging.debug('hello - noshow')" - -#: ../../howto/logging-cookbook.rst:2900 -msgid "" -"This example shows how you can pass configuration data to the callable which " -"constructs the instance, in the form of keyword parameters. When run, the " -"above script will print:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2904 -msgid "changed: hello" -msgstr "changed: hello" - -#: ../../howto/logging-cookbook.rst:2908 -msgid "which shows that the filter is working as configured." -msgstr "" - -#: ../../howto/logging-cookbook.rst:2910 -msgid "A couple of extra points to note:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2912 -msgid "" -"If you can't refer to the callable directly in the configuration (e.g. if it " -"lives in a different module, and you can't import it directly where the " -"configuration dictionary is), you can use the form ``ext://...`` as " -"described in :ref:`logging-config-dict-externalobj`. For example, you could " -"have used the text ``'ext://__main__.MyFilter'`` instead of ``MyFilter`` in " -"the above example." -msgstr "" - -#: ../../howto/logging-cookbook.rst:2919 -msgid "" -"As well as for filters, this technique can also be used to configure custom " -"handlers and formatters. See :ref:`logging-config-dict-userdef` for more " -"information on how logging supports using user-defined objects in its " -"configuration, and see the other cookbook recipe :ref:`custom-handlers` " -"above." -msgstr "" - -#: ../../howto/logging-cookbook.rst:2928 -msgid "Customized exception formatting" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2930 -msgid "" -"There might be times when you want to do customized exception formatting - " -"for argument's sake, let's say you want exactly one line per logged event, " -"even when exception information is present. You can do this with a custom " -"formatter class, as shown in the following example::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2935 -msgid "" -"import logging\n" -"\n" -"class OneLineExceptionFormatter(logging.Formatter):\n" -" def formatException(self, exc_info):\n" -" \"\"\"\n" -" Format an exception so that it prints on a single line.\n" -" \"\"\"\n" -" result = super().formatException(exc_info)\n" -" return repr(result) # or format into one line however you want to\n" -"\n" -" def format(self, record):\n" -" s = super().format(record)\n" -" if record.exc_text:\n" -" s = s.replace('\\n', '') + '|'\n" -" return s\n" -"\n" -"def configure_logging():\n" -" fh = logging.FileHandler('output.txt', 'w')\n" -" f = OneLineExceptionFormatter('%(asctime)s|%(levelname)s|%(message)s|',\n" -" '%d/%m/%Y %H:%M:%S')\n" -" fh.setFormatter(f)\n" -" root = logging.getLogger()\n" -" root.setLevel(logging.DEBUG)\n" -" root.addHandler(fh)\n" -"\n" -"def main():\n" -" configure_logging()\n" -" logging.info('Sample message')\n" -" try:\n" -" x = 1 / 0\n" -" except ZeroDivisionError as e:\n" -" logging.exception('ZeroDivisionError: %s', e)\n" -"\n" -"if __name__ == '__main__':\n" -" main()" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2971 -msgid "When run, this produces a file with exactly two lines:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2973 -msgid "" -"28/01/2015 07:21:23|INFO|Sample message|\n" -"28/01/2015 07:21:23|ERROR|ZeroDivisionError: division by zero|'Traceback " -"(most recent call last):\\n File \"logtest7.py\", line 30, in main\\n x " -"= 1 / 0\\nZeroDivisionError: division by zero'|" -msgstr "" -"28/01/2015 07:21:23|INFO|Sample message|\n" -"28/01/2015 07:21:23|ERROR|ZeroDivisionError: division by zero|'Traceback " -"(most recent call last):\\n File \"logtest7.py\", line 30, in main\\n x " -"= 1 / 0\\nZeroDivisionError: division by zero'|" - -#: ../../howto/logging-cookbook.rst:2978 -msgid "" -"While the above treatment is simplistic, it points the way to how exception " -"information can be formatted to your liking. The :mod:`traceback` module may " -"be helpful for more specialized needs." -msgstr "" - -#: ../../howto/logging-cookbook.rst:2985 -msgid "Speaking logging messages" -msgstr "" - -#: ../../howto/logging-cookbook.rst:2987 -msgid "" -"There might be situations when it is desirable to have logging messages " -"rendered in an audible rather than a visible format. This is easy to do if " -"you have text-to-speech (TTS) functionality available in your system, even " -"if it doesn't have a Python binding. Most TTS systems have a command line " -"program you can run, and this can be invoked from a handler " -"using :mod:`subprocess`. It's assumed here that TTS command line programs " -"won't expect to interact with users or take a long time to complete, and " -"that the frequency of logged messages will be not so high as to swamp the " -"user with messages, and that it's acceptable to have the messages spoken one " -"at a time rather than concurrently, The example implementation below waits " -"for one message to be spoken before the next is processed, and this might " -"cause other handlers to be kept waiting. Here is a short example showing the " -"approach, which assumes that the ``espeak`` TTS package is available::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:3000 -msgid "" -"import logging\n" -"import subprocess\n" -"import sys\n" -"\n" -"class TTSHandler(logging.Handler):\n" -" def emit(self, record):\n" -" msg = self.format(record)\n" -" # Speak slowly in a female English voice\n" -" cmd = ['espeak', '-s150', '-ven+f3', msg]\n" -" p = subprocess.Popen(cmd, stdout=subprocess.PIPE,\n" -" stderr=subprocess.STDOUT)\n" -" # wait for the program to finish\n" -" p.communicate()\n" -"\n" -"def configure_logging():\n" -" h = TTSHandler()\n" -" root = logging.getLogger()\n" -" root.addHandler(h)\n" -" # the default formatter just returns the message\n" -" root.setLevel(logging.DEBUG)\n" -"\n" -"def main():\n" -" logging.info('Hello')\n" -" logging.debug('Goodbye')\n" -"\n" -"if __name__ == '__main__':\n" -" configure_logging()\n" -" sys.exit(main())" -msgstr "" - -#: ../../howto/logging-cookbook.rst:3029 -msgid "" -"When run, this script should say \"Hello\" and then \"Goodbye\" in a female " -"voice." -msgstr "" - -#: ../../howto/logging-cookbook.rst:3031 -msgid "" -"The above approach can, of course, be adapted to other TTS systems and even " -"other systems altogether which can process messages via external programs " -"run from a command line." -msgstr "" - -#: ../../howto/logging-cookbook.rst:3039 -msgid "Buffering logging messages and outputting them conditionally" -msgstr "" - -#: ../../howto/logging-cookbook.rst:3041 -msgid "" -"There might be situations where you want to log messages in a temporary area " -"and only output them if a certain condition occurs. For example, you may " -"want to start logging debug events in a function, and if the function " -"completes without errors, you don't want to clutter the log with the " -"collected debug information, but if there is an error, you want all the " -"debug information to be output as well as the error." -msgstr "" - -#: ../../howto/logging-cookbook.rst:3048 -msgid "" -"Here is an example which shows how you could do this using a decorator for " -"your functions where you want logging to behave this way. It makes use of " -"the :class:`logging.handlers.MemoryHandler`, which allows buffering of " -"logged events until some condition occurs, at which point the buffered " -"events are ``flushed`` - passed to another handler (the ``target`` handler) " -"for processing. By default, the ``MemoryHandler`` flushed when its buffer " -"gets filled up or an event whose level is greater than or equal to a " -"specified threshold is seen. You can use this recipe with a more specialised " -"subclass of ``MemoryHandler`` if you want custom flushing behavior." -msgstr "" - -#: ../../howto/logging-cookbook.rst:3058 -msgid "" -"The example script has a simple function, ``foo``, which just cycles through " -"all the logging levels, writing to ``sys.stderr`` to say what level it's " -"about to log at, and then actually logging a message at that level. You can " -"pass a parameter to ``foo`` which, if true, will log at ERROR and CRITICAL " -"levels - otherwise, it only logs at DEBUG, INFO and WARNING levels." -msgstr "" - -#: ../../howto/logging-cookbook.rst:3064 -msgid "" -"The script just arranges to decorate ``foo`` with a decorator which will do " -"the conditional logging that's required. The decorator takes a logger as a " -"parameter and attaches a memory handler for the duration of the call to the " -"decorated function. The decorator can be additionally parameterised using a " -"target handler, a level at which flushing should occur, and a capacity for " -"the buffer (number of records buffered). These default to " -"a :class:`~logging.StreamHandler` which writes to ``sys.stderr``, " -"``logging.ERROR`` and ``100`` respectively." -msgstr "" - -#: ../../howto/logging-cookbook.rst:3072 -msgid "Here's the script::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:3074 -msgid "" -"import logging\n" -"from logging.handlers import MemoryHandler\n" -"import sys\n" -"\n" -"logger = logging.getLogger(__name__)\n" -"logger.addHandler(logging.NullHandler())\n" -"\n" -"def log_if_errors(logger, target_handler=None, flush_level=None, " -"capacity=None):\n" -" if target_handler is None:\n" -" target_handler = logging.StreamHandler()\n" -" if flush_level is None:\n" -" flush_level = logging.ERROR\n" -" if capacity is None:\n" -" capacity = 100\n" -" handler = MemoryHandler(capacity, flushLevel=flush_level, " -"target=target_handler)\n" -"\n" -" def decorator(fn):\n" -" def wrapper(*args, **kwargs):\n" -" logger.addHandler(handler)\n" -" try:\n" -" return fn(*args, **kwargs)\n" -" except Exception:\n" -" logger.exception('call failed')\n" -" raise\n" -" finally:\n" -" super(MemoryHandler, handler).flush()\n" -" logger.removeHandler(handler)\n" -" return wrapper\n" -"\n" -" return decorator\n" -"\n" -"def write_line(s):\n" -" sys.stderr.write('%s\\n' % s)\n" -"\n" -"def foo(fail=False):\n" -" write_line('about to log at DEBUG ...')\n" -" logger.debug('Actually logged at DEBUG')\n" -" write_line('about to log at INFO ...')\n" -" logger.info('Actually logged at INFO')\n" -" write_line('about to log at WARNING ...')\n" -" logger.warning('Actually logged at WARNING')\n" -" if fail:\n" -" write_line('about to log at ERROR ...')\n" -" logger.error('Actually logged at ERROR')\n" -" write_line('about to log at CRITICAL ...')\n" -" logger.critical('Actually logged at CRITICAL')\n" -" return fail\n" -"\n" -"decorated_foo = log_if_errors(logger)(foo)\n" -"\n" -"if __name__ == '__main__':\n" -" logger.setLevel(logging.DEBUG)\n" -" write_line('Calling undecorated foo with False')\n" -" assert not foo(False)\n" -" write_line('Calling undecorated foo with True')\n" -" assert foo(True)\n" -" write_line('Calling decorated foo with False')\n" -" assert not decorated_foo(False)\n" -" write_line('Calling decorated foo with True')\n" -" assert decorated_foo(True)" -msgstr "" - -#: ../../howto/logging-cookbook.rst:3135 -msgid "When this script is run, the following output should be observed:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:3137 -msgid "" -"Calling undecorated foo with False\n" -"about to log at DEBUG ...\n" -"about to log at INFO ...\n" -"about to log at WARNING ...\n" -"Calling undecorated foo with True\n" -"about to log at DEBUG ...\n" -"about to log at INFO ...\n" -"about to log at WARNING ...\n" -"about to log at ERROR ...\n" -"about to log at CRITICAL ...\n" -"Calling decorated foo with False\n" -"about to log at DEBUG ...\n" -"about to log at INFO ...\n" -"about to log at WARNING ...\n" -"Calling decorated foo with True\n" -"about to log at DEBUG ...\n" -"about to log at INFO ...\n" -"about to log at WARNING ...\n" -"about to log at ERROR ...\n" -"Actually logged at DEBUG\n" -"Actually logged at INFO\n" -"Actually logged at WARNING\n" -"Actually logged at ERROR\n" -"about to log at CRITICAL ...\n" -"Actually logged at CRITICAL" -msgstr "" - -#: ../../howto/logging-cookbook.rst:3165 -msgid "" -"As you can see, actual logging output only occurs when an event is logged " -"whose severity is ERROR or greater, but in that case, any previous events at " -"lower severities are also logged." -msgstr "" - -#: ../../howto/logging-cookbook.rst:3169 -msgid "You can of course use the conventional means of decoration::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:3171 -msgid "" -"@log_if_errors(logger)\n" -"def foo(fail=False):\n" -" ..." -msgstr "" - -#: ../../howto/logging-cookbook.rst:3179 -msgid "Sending logging messages to email, with buffering" -msgstr "" - -#: ../../howto/logging-cookbook.rst:3181 -msgid "" -"To illustrate how you can send log messages via email, so that a set number " -"of messages are sent per email, you can " -"subclass :class:`~logging.handlers.BufferingHandler`. In the following " -"example, which you can adapt to suit your specific needs, a simple test " -"harness is provided which allows you to run the script with command line " -"arguments specifying what you typically need to send things via SMTP. (Run " -"the downloaded script with the ``-h`` argument to see the required and " -"optional arguments.)" -msgstr "" - -#: ../../howto/logging-cookbook.rst:3189 -msgid "" -"import logging\n" -"import logging.handlers\n" -"import smtplib\n" -"\n" -"class BufferingSMTPHandler(logging.handlers.BufferingHandler):\n" -" def __init__(self, mailhost, port, username, password, fromaddr, " -"toaddrs,\n" -" subject, capacity):\n" -" logging.handlers.BufferingHandler.__init__(self, capacity)\n" -" self.mailhost = mailhost\n" -" self.mailport = port\n" -" self.username = username\n" -" self.password = password\n" -" self.fromaddr = fromaddr\n" -" if isinstance(toaddrs, str):\n" -" toaddrs = [toaddrs]\n" -" self.toaddrs = toaddrs\n" -" self.subject = subject\n" -" self.setFormatter(logging.Formatter(\"%(asctime)s %(levelname)-5s %" -"(message)s\"))\n" -"\n" -" def flush(self):\n" -" if len(self.buffer) > 0:\n" -" try:\n" -" smtp = smtplib.SMTP(self.mailhost, self.mailport)\n" -" smtp.starttls()\n" -" smtp.login(self.username, self.password)\n" -" msg = \"From: %s\\r\\nTo: %s\\r\\nSubject: %s\\r\\n\\r\\n\" " -"% (self.fromaddr, ','.join(self.toaddrs), self.subject)\n" -" for record in self.buffer:\n" -" s = self.format(record)\n" -" msg = msg + s + \"\\r\\n\"\n" -" smtp.sendmail(self.fromaddr, self.toaddrs, msg)\n" -" smtp.quit()\n" -" except Exception:\n" -" if logging.raiseExceptions:\n" -" raise\n" -" self.buffer = []\n" -"\n" -"if __name__ == '__main__':\n" -" import argparse\n" -"\n" -" ap = argparse.ArgumentParser()\n" -" aa = ap.add_argument\n" -" aa('host', metavar='HOST', help='SMTP server')\n" -" aa('--port', '-p', type=int, default=587, help='SMTP port')\n" -" aa('user', metavar='USER', help='SMTP username')\n" -" aa('password', metavar='PASSWORD', help='SMTP password')\n" -" aa('to', metavar='TO', help='Addressee for emails')\n" -" aa('sender', metavar='SENDER', help='Sender email address')\n" -" aa('--subject', '-s',\n" -" default='Test Logging email from Python logging module (buffering)',\n" -" help='Subject of email')\n" -" options = ap.parse_args()\n" -" logger = logging.getLogger()\n" -" logger.setLevel(logging.DEBUG)\n" -" h = BufferingSMTPHandler(options.host, options.port, options.user,\n" -" options.password, options.sender,\n" -" options.to, options.subject, 10)\n" -" logger.addHandler(h)\n" -" for i in range(102):\n" -" logger.info(\"Info index = %d\", i)\n" -" h.flush()\n" -" h.close()" -msgstr "" - -#: ../../howto/logging-cookbook.rst:3253 -msgid "" -"If you run this script and your SMTP server is correctly set up, you should " -"find that it sends eleven emails to the addressee you specify. The first ten " -"emails will each have ten log messages, and the eleventh will have two " -"messages. That makes up 102 messages as specified in the script." -msgstr "" - -#: ../../howto/logging-cookbook.rst:3261 -msgid "Formatting times using UTC (GMT) via configuration" -msgstr "" - -#: ../../howto/logging-cookbook.rst:3263 -msgid "" -"Sometimes you want to format times using UTC, which can be done using a " -"class such as ``UTCFormatter``, shown below::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:3266 -msgid "" -"import logging\n" -"import time\n" -"\n" -"class UTCFormatter(logging.Formatter):\n" -" converter = time.gmtime" -msgstr "" -"import logging\n" -"import time\n" -"\n" -"class UTCFormatter(logging.Formatter):\n" -" converter = time.gmtime" - -#: ../../howto/logging-cookbook.rst:3272 -msgid "" -"and you can then use the ``UTCFormatter`` in your code instead " -"of :class:`~logging.Formatter`. If you want to do that via configuration, " -"you can use the :func:`~logging.config.dictConfig` API with an approach " -"illustrated by the following complete example::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:3277 -msgid "" -"import logging\n" -"import logging.config\n" -"import time\n" -"\n" -"class UTCFormatter(logging.Formatter):\n" -" converter = time.gmtime\n" -"\n" -"LOGGING = {\n" -" 'version': 1,\n" -" 'disable_existing_loggers': False,\n" -" 'formatters': {\n" -" 'utc': {\n" -" '()': UTCFormatter,\n" -" 'format': '%(asctime)s %(message)s',\n" -" },\n" -" 'local': {\n" -" 'format': '%(asctime)s %(message)s',\n" -" }\n" -" },\n" -" 'handlers': {\n" -" 'console1': {\n" -" 'class': 'logging.StreamHandler',\n" -" 'formatter': 'utc',\n" -" },\n" -" 'console2': {\n" -" 'class': 'logging.StreamHandler',\n" -" 'formatter': 'local',\n" -" },\n" -" },\n" -" 'root': {\n" -" 'handlers': ['console1', 'console2'],\n" -" }\n" -"}\n" -"\n" -"if __name__ == '__main__':\n" -" logging.config.dictConfig(LOGGING)\n" -" logging.warning('The local time is %s', time.asctime())" -msgstr "" -"import logging\n" -"import logging.config\n" -"import time\n" -"\n" -"class UTCFormatter(logging.Formatter):\n" -" converter = time.gmtime\n" -"\n" -"LOGGING = {\n" -" 'version': 1,\n" -" 'disable_existing_loggers': False,\n" -" 'formatters': {\n" -" 'utc': {\n" -" '()': UTCFormatter,\n" -" 'format': '%(asctime)s %(message)s',\n" -" },\n" -" 'local': {\n" -" 'format': '%(asctime)s %(message)s',\n" -" }\n" -" },\n" -" 'handlers': {\n" -" 'console1': {\n" -" 'class': 'logging.StreamHandler',\n" -" 'formatter': 'utc',\n" -" },\n" -" 'console2': {\n" -" 'class': 'logging.StreamHandler',\n" -" 'formatter': 'local',\n" -" },\n" -" },\n" -" 'root': {\n" -" 'handlers': ['console1', 'console2'],\n" -" }\n" -"}\n" -"\n" -"if __name__ == '__main__':\n" -" logging.config.dictConfig(LOGGING)\n" -" logging.warning('The local time is %s', time.asctime())" - -#: ../../howto/logging-cookbook.rst:3315 -msgid "When this script is run, it should print something like:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:3317 -msgid "" -"2015-10-17 12:53:29,501 The local time is Sat Oct 17 13:53:29 2015\n" -"2015-10-17 13:53:29,501 The local time is Sat Oct 17 13:53:29 2015" -msgstr "" -"2015-10-17 12:53:29,501 The local time is Sat Oct 17 13:53:29 2015\n" -"2015-10-17 13:53:29,501 The local time is Sat Oct 17 13:53:29 2015" - -#: ../../howto/logging-cookbook.rst:3322 -msgid "" -"showing how the time is formatted both as local time and UTC, one for each " -"handler." -msgstr "" - -#: ../../howto/logging-cookbook.rst:3329 -msgid "Using a context manager for selective logging" -msgstr "" - -#: ../../howto/logging-cookbook.rst:3331 -msgid "" -"There are times when it would be useful to temporarily change the logging " -"configuration and revert it back after doing something. For this, a context " -"manager is the most obvious way of saving and restoring the logging context. " -"Here is a simple example of such a context manager, which allows you to " -"optionally change the logging level and add a logging handler purely in the " -"scope of the context manager::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:3338 -msgid "" -"import logging\n" -"import sys\n" -"\n" -"class LoggingContext:\n" -" def __init__(self, logger, level=None, handler=None, close=True):\n" -" self.logger = logger\n" -" self.level = level\n" -" self.handler = handler\n" -" self.close = close\n" -"\n" -" def __enter__(self):\n" -" if self.level is not None:\n" -" self.old_level = self.logger.level\n" -" self.logger.setLevel(self.level)\n" -" if self.handler:\n" -" self.logger.addHandler(self.handler)\n" -"\n" -" def __exit__(self, et, ev, tb):\n" -" if self.level is not None:\n" -" self.logger.setLevel(self.old_level)\n" -" if self.handler:\n" -" self.logger.removeHandler(self.handler)\n" -" if self.handler and self.close:\n" -" self.handler.close()\n" -" # implicit return of None => don't swallow exceptions" -msgstr "" - -#: ../../howto/logging-cookbook.rst:3364 -msgid "" -"If you specify a level value, the logger's level is set to that value in the " -"scope of the with block covered by the context manager. If you specify a " -"handler, it is added to the logger on entry to the block and removed on exit " -"from the block. You can also ask the manager to close the handler for you on " -"block exit - you could do this if you don't need the handler any more." -msgstr "" - -#: ../../howto/logging-cookbook.rst:3370 -msgid "" -"To illustrate how it works, we can add the following block of code to the " -"above::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:3373 -msgid "" -"if __name__ == '__main__':\n" -" logger = logging.getLogger('foo')\n" -" logger.addHandler(logging.StreamHandler())\n" -" logger.setLevel(logging.INFO)\n" -" logger.info('1. This should appear just once on stderr.')\n" -" logger.debug('2. This should not appear.')\n" -" with LoggingContext(logger, level=logging.DEBUG):\n" -" logger.debug('3. This should appear once on stderr.')\n" -" logger.debug('4. This should not appear.')\n" -" h = logging.StreamHandler(sys.stdout)\n" -" with LoggingContext(logger, level=logging.DEBUG, handler=h, " -"close=True):\n" -" logger.debug('5. This should appear twice - once on stderr and once " -"on stdout.')\n" -" logger.info('6. This should appear just once on stderr.')\n" -" logger.debug('7. This should not appear.')" -msgstr "" -"if __name__ == '__main__':\n" -" logger = logging.getLogger('foo')\n" -" logger.addHandler(logging.StreamHandler())\n" -" logger.setLevel(logging.INFO)\n" -" logger.info('1. This should appear just once on stderr.')\n" -" logger.debug('2. This should not appear.')\n" -" with LoggingContext(logger, level=logging.DEBUG):\n" -" logger.debug('3. This should appear once on stderr.')\n" -" logger.debug('4. This should not appear.')\n" -" h = logging.StreamHandler(sys.stdout)\n" -" with LoggingContext(logger, level=logging.DEBUG, handler=h, " -"close=True):\n" -" logger.debug('5. This should appear twice - once on stderr and once " -"on stdout.')\n" -" logger.info('6. This should appear just once on stderr.')\n" -" logger.debug('7. This should not appear.')" - -#: ../../howto/logging-cookbook.rst:3388 -msgid "" -"We initially set the logger's level to ``INFO``, so message #1 appears and " -"message #2 doesn't. We then change the level to ``DEBUG`` temporarily in the " -"following ``with`` block, and so message #3 appears. After the block exits, " -"the logger's level is restored to ``INFO`` and so message #4 doesn't appear. " -"In the next ``with`` block, we set the level to ``DEBUG`` again but also add " -"a handler writing to ``sys.stdout``. Thus, message #5 appears twice on the " -"console (once via ``stderr`` and once via ``stdout``). After the ``with`` " -"statement's completion, the status is as it was before so message #6 appears " -"(like message #1) whereas message #7 doesn't (just like message #2)." -msgstr "" - -#: ../../howto/logging-cookbook.rst:3398 -msgid "If we run the resulting script, the result is as follows:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:3400 -msgid "" -"$ python logctx.py\n" -"1. This should appear just once on stderr.\n" -"3. This should appear once on stderr.\n" -"5. This should appear twice - once on stderr and once on stdout.\n" -"5. This should appear twice - once on stderr and once on stdout.\n" -"6. This should appear just once on stderr." -msgstr "" -"$ python logctx.py\n" -"1. This should appear just once on stderr.\n" -"3. This should appear once on stderr.\n" -"5. This should appear twice - once on stderr and once on stdout.\n" -"5. This should appear twice - once on stderr and once on stdout.\n" -"6. This should appear just once on stderr." - -#: ../../howto/logging-cookbook.rst:3409 -msgid "" -"If we run it again, but pipe ``stderr`` to ``/dev/null``, we see the " -"following, which is the only message written to ``stdout``:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:3412 -msgid "" -"$ python logctx.py 2>/dev/null\n" -"5. This should appear twice - once on stderr and once on stdout." -msgstr "" - -#: ../../howto/logging-cookbook.rst:3417 -msgid "Once again, but piping ``stdout`` to ``/dev/null``, we get:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:3419 -msgid "" -"$ python logctx.py >/dev/null\n" -"1. This should appear just once on stderr.\n" -"3. This should appear once on stderr.\n" -"5. This should appear twice - once on stderr and once on stdout.\n" -"6. This should appear just once on stderr." -msgstr "" -"$ python logctx.py >/dev/null\n" -"1. This should appear just once on stderr.\n" -"3. This should appear once on stderr.\n" -"5. This should appear twice - once on stderr and once on stdout.\n" -"6. This should appear just once on stderr." - -#: ../../howto/logging-cookbook.rst:3427 -msgid "" -"In this case, the message #5 printed to ``stdout`` doesn't appear, as " -"expected." -msgstr "" - -#: ../../howto/logging-cookbook.rst:3429 -msgid "" -"Of course, the approach described here can be generalised, for example to " -"attach logging filters temporarily. Note that the above code works in Python " -"2 as well as Python 3." -msgstr "" - -#: ../../howto/logging-cookbook.rst:3437 -msgid "A CLI application starter template" -msgstr "" - -#: ../../howto/logging-cookbook.rst:3439 -msgid "Here's an example which shows how you can:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:3441 -msgid "Use a logging level based on command-line arguments" -msgstr "" - -#: ../../howto/logging-cookbook.rst:3442 -msgid "" -"Dispatch to multiple subcommands in separate files, all logging at the same " -"level in a consistent way" -msgstr "" - -#: ../../howto/logging-cookbook.rst:3444 -msgid "Make use of simple, minimal configuration" -msgstr "" - -#: ../../howto/logging-cookbook.rst:3446 -msgid "" -"Suppose we have a command-line application whose job is to stop, start or " -"restart some services. This could be organised for the purposes of " -"illustration as a file ``app.py`` that is the main script for the " -"application, with individual commands implemented in ``start.py``, " -"``stop.py`` and ``restart.py``. Suppose further that we want to control the " -"verbosity of the application via a command-line argument, defaulting to " -"``logging.INFO``. Here's one way that ``app.py`` could be written::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:3454 -msgid "" -"import argparse\n" -"import importlib\n" -"import logging\n" -"import os\n" -"import sys\n" -"\n" -"def main(args=None):\n" -" scriptname = os.path.basename(__file__)\n" -" parser = argparse.ArgumentParser(scriptname)\n" -" levels = ('DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL')\n" -" parser.add_argument('--log-level', default='INFO', choices=levels)\n" -" subparsers = parser.add_subparsers(dest='command',\n" -" help='Available commands:')\n" -" start_cmd = subparsers.add_parser('start', help='Start a service')\n" -" start_cmd.add_argument('name', metavar='NAME',\n" -" help='Name of service to start')\n" -" stop_cmd = subparsers.add_parser('stop',\n" -" help='Stop one or more services')\n" -" stop_cmd.add_argument('names', metavar='NAME', nargs='+',\n" -" help='Name of service to stop')\n" -" restart_cmd = subparsers.add_parser('restart',\n" -" help='Restart one or more " -"services')\n" -" restart_cmd.add_argument('names', metavar='NAME', nargs='+',\n" -" help='Name of service to restart')\n" -" options = parser.parse_args()\n" -" # the code to dispatch commands could all be in this file. For the " -"purposes\n" -" # of illustration only, we implement each command in a separate module.\n" -" try:\n" -" mod = importlib.import_module(options.command)\n" -" cmd = getattr(mod, 'command')\n" -" except (ImportError, AttributeError):\n" -" print('Unable to find the code for command \\'%s\\'' % " -"options.command)\n" -" return 1\n" -" # Could get fancy here and load configuration from file or dictionary\n" -" logging.basicConfig(level=options.log_level,\n" -" format='%(levelname)s %(name)s %(message)s')\n" -" cmd(options)\n" -"\n" -"if __name__ == '__main__':\n" -" sys.exit(main())" -msgstr "" - -#: ../../howto/logging-cookbook.rst:3495 -msgid "" -"And the ``start``, ``stop`` and ``restart`` commands can be implemented in " -"separate modules, like so for starting::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:3498 -msgid "" -"# start.py\n" -"import logging\n" -"\n" -"logger = logging.getLogger(__name__)\n" -"\n" -"def command(options):\n" -" logger.debug('About to start %s', options.name)\n" -" # actually do the command processing here ...\n" -" logger.info('Started the \\'%s\\' service.', options.name)" -msgstr "" -"# start.py\n" -"import logging\n" -"\n" -"logger = logging.getLogger(__name__)\n" -"\n" -"def command(options):\n" -" logger.debug('About to start %s', options.name)\n" -" # 在這裡實際執行命令處理 ...\n" -" logger.info('Started the \\'%s\\' service.', options.name)" - -#: ../../howto/logging-cookbook.rst:3508 -msgid "and thus for stopping::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:3510 -msgid "" -"# stop.py\n" -"import logging\n" -"\n" -"logger = logging.getLogger(__name__)\n" -"\n" -"def command(options):\n" -" n = len(options.names)\n" -" if n == 1:\n" -" plural = ''\n" -" services = '\\'%s\\'' % options.names[0]\n" -" else:\n" -" plural = 's'\n" -" services = ', '.join('\\'%s\\'' % name for name in options.names)\n" -" i = services.rfind(', ')\n" -" services = services[:i] + ' and ' + services[i + 2:]\n" -" logger.debug('About to stop %s', services)\n" -" # actually do the command processing here ...\n" -" logger.info('Stopped the %s service%s.', services, plural)" -msgstr "" -"# stop.py\n" -"import logging\n" -"\n" -"logger = logging.getLogger(__name__)\n" -"\n" -"def command(options):\n" -" n = len(options.names)\n" -" if n == 1:\n" -" plural = ''\n" -" services = '\\'%s\\'' % options.names[0]\n" -" else:\n" -" plural = 's'\n" -" services = ', '.join('\\'%s\\'' % name for name in options.names)\n" -" i = services.rfind(', ')\n" -" services = services[:i] + ' and ' + services[i + 2:]\n" -" logger.debug('About to stop %s', services)\n" -" # 在這裡實際執行命令處理 ...\n" -" logger.info('Stopped the %s service%s.', services, plural)" - -#: ../../howto/logging-cookbook.rst:3529 -msgid "and similarly for restarting::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:3531 -msgid "" -"# restart.py\n" -"import logging\n" -"\n" -"logger = logging.getLogger(__name__)\n" -"\n" -"def command(options):\n" -" n = len(options.names)\n" -" if n == 1:\n" -" plural = ''\n" -" services = '\\'%s\\'' % options.names[0]\n" -" else:\n" -" plural = 's'\n" -" services = ', '.join('\\'%s\\'' % name for name in options.names)\n" -" i = services.rfind(', ')\n" -" services = services[:i] + ' and ' + services[i + 2:]\n" -" logger.debug('About to restart %s', services)\n" -" # actually do the command processing here ...\n" -" logger.info('Restarted the %s service%s.', services, plural)" -msgstr "" -"# restart.py\n" -"import logging\n" -"\n" -"logger = logging.getLogger(__name__)\n" -"\n" -"def command(options):\n" -" n = len(options.names)\n" -" if n == 1:\n" -" plural = ''\n" -" services = '\\'%s\\'' % options.names[0]\n" -" else:\n" -" plural = 's'\n" -" services = ', '.join('\\'%s\\'' % name for name in options.names)\n" -" i = services.rfind(', ')\n" -" services = services[:i] + ' and ' + services[i + 2:]\n" -" logger.debug('About to restart %s', services)\n" -" # 在這裡實際執行命令處理 ...\n" -" logger.info('Restarted the %s service%s.', services, plural)" - -#: ../../howto/logging-cookbook.rst:3550 -msgid "" -"If we run this application with the default log level, we get output like " -"this:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:3552 -msgid "" -"$ python app.py start foo\n" -"INFO start Started the 'foo' service.\n" -"\n" -"$ python app.py stop foo bar\n" -"INFO stop Stopped the 'foo' and 'bar' services.\n" -"\n" -"$ python app.py restart foo bar baz\n" -"INFO restart Restarted the 'foo', 'bar' and 'baz' services." -msgstr "" -"$ python app.py start foo\n" -"INFO start Started the 'foo' service.\n" -"\n" -"$ python app.py stop foo bar\n" -"INFO stop Stopped the 'foo' and 'bar' services.\n" -"\n" -"$ python app.py restart foo bar baz\n" -"INFO restart Restarted the 'foo', 'bar' and 'baz' services." - -#: ../../howto/logging-cookbook.rst:3563 -msgid "" -"The first word is the logging level, and the second word is the module or " -"package name of the place where the event was logged." -msgstr "" - -#: ../../howto/logging-cookbook.rst:3566 -msgid "" -"If we change the logging level, then we can change the information sent to " -"the log. For example, if we want more information:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:3569 -msgid "" -"$ python app.py --log-level DEBUG start foo\n" -"DEBUG start About to start foo\n" -"INFO start Started the 'foo' service.\n" -"\n" -"$ python app.py --log-level DEBUG stop foo bar\n" -"DEBUG stop About to stop 'foo' and 'bar'\n" -"INFO stop Stopped the 'foo' and 'bar' services.\n" -"\n" -"$ python app.py --log-level DEBUG restart foo bar baz\n" -"DEBUG restart About to restart 'foo', 'bar' and 'baz'\n" -"INFO restart Restarted the 'foo', 'bar' and 'baz' services." -msgstr "" -"$ python app.py --log-level DEBUG start foo\n" -"DEBUG start About to start foo\n" -"INFO start Started the 'foo' service.\n" -"\n" -"$ python app.py --log-level DEBUG stop foo bar\n" -"DEBUG stop About to stop 'foo' and 'bar'\n" -"INFO stop Stopped the 'foo' and 'bar' services.\n" -"\n" -"$ python app.py --log-level DEBUG restart foo bar baz\n" -"DEBUG restart About to restart 'foo', 'bar' and 'baz'\n" -"INFO restart Restarted the 'foo', 'bar' and 'baz' services." - -#: ../../howto/logging-cookbook.rst:3583 -msgid "And if we want less:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:3585 -msgid "" -"$ python app.py --log-level WARNING start foo\n" -"$ python app.py --log-level WARNING stop foo bar\n" -"$ python app.py --log-level WARNING restart foo bar baz" -msgstr "" -"$ python app.py --log-level WARNING start foo\n" -"$ python app.py --log-level WARNING stop foo bar\n" -"$ python app.py --log-level WARNING restart foo bar baz" - -#: ../../howto/logging-cookbook.rst:3591 -msgid "" -"In this case, the commands don't print anything to the console, since " -"nothing at ``WARNING`` level or above is logged by them." -msgstr "" - -#: ../../howto/logging-cookbook.rst:3597 -msgid "A Qt GUI for logging" -msgstr "" - -#: ../../howto/logging-cookbook.rst:3599 -msgid "" -"A question that comes up from time to time is about how to log to a GUI " -"application. The `Qt `_ framework is a popular cross-" -"platform UI framework with Python bindings using :pypi:`PySide2` " -"or :pypi:`PyQt5` libraries." -msgstr "" - -#: ../../howto/logging-cookbook.rst:3604 -msgid "" -"The following example shows how to log to a Qt GUI. This introduces a simple " -"``QtHandler`` class which takes a callable, which should be a slot in the " -"main thread that does GUI updates. A worker thread is also created to show " -"how you can log to the GUI from both the UI itself (via a button for manual " -"logging) as well as a worker thread doing work in the background (here, just " -"logging messages at random levels with random short delays in between)." -msgstr "" - -#: ../../howto/logging-cookbook.rst:3611 -msgid "" -"The worker thread is implemented using Qt's ``QThread`` class rather than " -"the :mod:`threading` module, as there are circumstances where one has to use " -"``QThread``, which offers better integration with other ``Qt`` components." -msgstr "" - -#: ../../howto/logging-cookbook.rst:3615 -msgid "" -"The code should work with recent releases of any of ``PySide6``, ``PyQt6``, " -"``PySide2`` or ``PyQt5``. You should be able to adapt the approach to " -"earlier versions of Qt. Please refer to the comments in the code snippet for " -"more detailed information." -msgstr "" - -#: ../../howto/logging-cookbook.rst:3620 -msgid "" -"import datetime\n" -"import logging\n" -"import random\n" -"import sys\n" -"import time\n" -"\n" -"# Deal with minor differences between different Qt packages\n" -"try:\n" -" from PySide6 import QtCore, QtGui, QtWidgets\n" -" Signal = QtCore.Signal\n" -" Slot = QtCore.Slot\n" -"except ImportError:\n" -" try:\n" -" from PyQt6 import QtCore, QtGui, QtWidgets\n" -" Signal = QtCore.pyqtSignal\n" -" Slot = QtCore.pyqtSlot\n" -" except ImportError:\n" -" try:\n" -" from PySide2 import QtCore, QtGui, QtWidgets\n" -" Signal = QtCore.Signal\n" -" Slot = QtCore.Slot\n" -" except ImportError:\n" -" from PyQt5 import QtCore, QtGui, QtWidgets\n" -" Signal = QtCore.pyqtSignal\n" -" Slot = QtCore.pyqtSlot\n" -"\n" -"logger = logging.getLogger(__name__)\n" -"\n" -"\n" -"#\n" -"# Signals need to be contained in a QObject or subclass in order to be " -"correctly\n" -"# initialized.\n" -"#\n" -"class Signaller(QtCore.QObject):\n" -" signal = Signal(str, logging.LogRecord)\n" -"\n" -"#\n" -"# Output to a Qt GUI is only supposed to happen on the main thread. So, " -"this\n" -"# handler is designed to take a slot function which is set up to run in the " -"main\n" -"# thread. In this example, the function takes a string argument which is a\n" -"# formatted log message, and the log record which generated it. The " -"formatted\n" -"# string is just a convenience - you could format a string for output any " -"way\n" -"# you like in the slot function itself.\n" -"#\n" -"# You specify the slot function to do whatever GUI updates you want. The " -"handler\n" -"# doesn't know or care about specific UI elements.\n" -"#\n" -"class QtHandler(logging.Handler):\n" -" def __init__(self, slotfunc, *args, **kwargs):\n" -" super().__init__(*args, **kwargs)\n" -" self.signaller = Signaller()\n" -" self.signaller.signal.connect(slotfunc)\n" -"\n" -" def emit(self, record):\n" -" s = self.format(record)\n" -" self.signaller.signal.emit(s, record)\n" -"\n" -"#\n" -"# This example uses QThreads, which means that the threads at the Python " -"level\n" -"# are named something like \"Dummy-1\". The function below gets the Qt name " -"of the\n" -"# current thread.\n" -"#\n" -"def ctname():\n" -" return QtCore.QThread.currentThread().objectName()\n" -"\n" -"\n" -"#\n" -"# Used to generate random levels for logging.\n" -"#\n" -"LEVELS = (logging.DEBUG, logging.INFO, logging.WARNING, logging.ERROR,\n" -" logging.CRITICAL)\n" -"\n" -"#\n" -"# This worker class represents work that is done in a thread separate to " -"the\n" -"# main thread. The way the thread is kicked off to do work is via a button " -"press\n" -"# that connects to a slot in the worker.\n" -"#\n" -"# Because the default threadName value in the LogRecord isn't much use, we " -"add\n" -"# a qThreadName which contains the QThread name as computed above, and pass " -"that\n" -"# value in an \"extra\" dictionary which is used to update the LogRecord " -"with the\n" -"# QThread name.\n" -"#\n" -"# This example worker just outputs messages sequentially, interspersed with\n" -"# random delays of the order of a few seconds.\n" -"#\n" -"class Worker(QtCore.QObject):\n" -" @Slot()\n" -" def start(self):\n" -" extra = {'qThreadName': ctname() }\n" -" logger.debug('Started work', extra=extra)\n" -" i = 1\n" -" # Let the thread run until interrupted. This allows reasonably " -"clean\n" -" # thread termination.\n" -" while not QtCore.QThread.currentThread().isInterruptionRequested():\n" -" delay = 0.5 + random.random() * 2\n" -" time.sleep(delay)\n" -" try:\n" -" if random.random() < 0.1:\n" -" raise ValueError('Exception raised: %d' % i)\n" -" else:\n" -" level = random.choice(LEVELS)\n" -" logger.log(level, 'Message after delay of %3.1f: %d', " -"delay, i, extra=extra)\n" -" except ValueError as e:\n" -" logger.exception('Failed: %s', e, extra=extra)\n" -" i += 1\n" -"\n" -"#\n" -"# Implement a simple UI for this cookbook example. This contains:\n" -"#\n" -"# * A read-only text edit window which holds formatted log messages\n" -"# * A button to start work and log stuff in a separate thread\n" -"# * A button to log something from the main thread\n" -"# * A button to clear the log window\n" -"#\n" -"class Window(QtWidgets.QWidget):\n" -"\n" -" COLORS = {\n" -" logging.DEBUG: 'black',\n" -" logging.INFO: 'blue',\n" -" logging.WARNING: 'orange',\n" -" logging.ERROR: 'red',\n" -" logging.CRITICAL: 'purple',\n" -" }\n" -"\n" -" def __init__(self, app):\n" -" super().__init__()\n" -" self.app = app\n" -" self.textedit = te = QtWidgets.QPlainTextEdit(self)\n" -" # Set whatever the default monospace font is for the platform\n" -" f = QtGui.QFont('nosuchfont')\n" -" if hasattr(f, 'Monospace'):\n" -" f.setStyleHint(f.Monospace)\n" -" else:\n" -" f.setStyleHint(f.StyleHint.Monospace) # for Qt6\n" -" te.setFont(f)\n" -" te.setReadOnly(True)\n" -" PB = QtWidgets.QPushButton\n" -" self.work_button = PB('Start background work', self)\n" -" self.log_button = PB('Log a message at a random level', self)\n" -" self.clear_button = PB('Clear log window', self)\n" -" self.handler = h = QtHandler(self.update_status)\n" -" # Remember to use qThreadName rather than threadName in the format " -"string.\n" -" fs = '%(asctime)s %(qThreadName)-12s %(levelname)-8s %(message)s'\n" -" formatter = logging.Formatter(fs)\n" -" h.setFormatter(formatter)\n" -" logger.addHandler(h)\n" -" # Set up to terminate the QThread when we exit\n" -" app.aboutToQuit.connect(self.force_quit)\n" -"\n" -" # Lay out all the widgets\n" -" layout = QtWidgets.QVBoxLayout(self)\n" -" layout.addWidget(te)\n" -" layout.addWidget(self.work_button)\n" -" layout.addWidget(self.log_button)\n" -" layout.addWidget(self.clear_button)\n" -" self.setFixedSize(900, 400)\n" -"\n" -" # Connect the non-worker slots and signals\n" -" self.log_button.clicked.connect(self.manual_update)\n" -" self.clear_button.clicked.connect(self.clear_display)\n" -"\n" -" # Start a new worker thread and connect the slots for the worker\n" -" self.start_thread()\n" -" self.work_button.clicked.connect(self.worker.start)\n" -" # Once started, the button should be disabled\n" -" self.work_button.clicked.connect(lambda : " -"self.work_button.setEnabled(False))\n" -"\n" -" def start_thread(self):\n" -" self.worker = Worker()\n" -" self.worker_thread = QtCore.QThread()\n" -" self.worker.setObjectName('Worker')\n" -" self.worker_thread.setObjectName('WorkerThread') # for qThreadName\n" -" self.worker.moveToThread(self.worker_thread)\n" -" # This will start an event loop in the worker thread\n" -" self.worker_thread.start()\n" -"\n" -" def kill_thread(self):\n" -" # Just tell the worker to stop, then tell it to quit and wait for " -"that\n" -" # to happen\n" -" self.worker_thread.requestInterruption()\n" -" if self.worker_thread.isRunning():\n" -" self.worker_thread.quit()\n" -" self.worker_thread.wait()\n" -" else:\n" -" print('worker has already exited.')\n" -"\n" -" def force_quit(self):\n" -" # For use when the window is closed\n" -" if self.worker_thread.isRunning():\n" -" self.kill_thread()\n" -"\n" -" # The functions below update the UI and run in the main thread because\n" -" # that's where the slots are set up\n" -"\n" -" @Slot(str, logging.LogRecord)\n" -" def update_status(self, status, record):\n" -" color = self.COLORS.get(record.levelno, 'black')\n" -" s = '
%s
' % (color, status)\n" -" self.textedit.appendHtml(s)\n" -"\n" -" @Slot()\n" -" def manual_update(self):\n" -" # This function uses the formatted message passed in, but also uses\n" -" # information from the record to format the message in an " -"appropriate\n" -" # color according to its severity (level).\n" -" level = random.choice(LEVELS)\n" -" extra = {'qThreadName': ctname() }\n" -" logger.log(level, 'Manually logged!', extra=extra)\n" -"\n" -" @Slot()\n" -" def clear_display(self):\n" -" self.textedit.clear()\n" -"\n" -"\n" -"def main():\n" -" QtCore.QThread.currentThread().setObjectName('MainThread')\n" -" logging.getLogger().setLevel(logging.DEBUG)\n" -" app = QtWidgets.QApplication(sys.argv)\n" -" example = Window(app)\n" -" example.show()\n" -" if hasattr(app, 'exec'):\n" -" rc = app.exec()\n" -" else:\n" -" rc = app.exec_()\n" -" sys.exit(rc)\n" -"\n" -"if __name__=='__main__':\n" -" main()" -msgstr "" - -#: ../../howto/logging-cookbook.rst:3852 -msgid "Logging to syslog with RFC5424 support" -msgstr "" - -#: ../../howto/logging-cookbook.rst:3854 -msgid "" -"Although :rfc:`5424` dates from 2009, most syslog servers are configured by " -"default to use the older :rfc:`3164`, which hails from 2001. When " -"``logging`` was added to Python in 2003, it supported the earlier (and only " -"existing) protocol at the time. Since RFC5424 came out, as there has not " -"been widespread deployment of it in syslog servers, " -"the :class:`~logging.handlers.SysLogHandler` functionality has not been " -"updated." -msgstr "" - -#: ../../howto/logging-cookbook.rst:3861 -msgid "" -"RFC 5424 contains some useful features such as support for structured data, " -"and if you need to be able to log to a syslog server with support for it, " -"you can do so with a subclassed handler which looks something like this::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:3865 -msgid "" -"import datetime\n" -"import logging.handlers\n" -"import re\n" -"import socket\n" -"import time\n" -"\n" -"class SysLogHandler5424(logging.handlers.SysLogHandler):\n" -"\n" -" tz_offset = re.compile(r'([+-]\\d{2})(\\d{2})$')\n" -" escaped = re.compile(r'([\\]\"\\\\])')\n" -"\n" -" def __init__(self, *args, **kwargs):\n" -" self.msgid = kwargs.pop('msgid', None)\n" -" self.appname = kwargs.pop('appname', None)\n" -" super().__init__(*args, **kwargs)\n" -"\n" -" def format(self, record):\n" -" version = 1\n" -" asctime = " -"datetime.datetime.fromtimestamp(record.created).isoformat()\n" -" m = self.tz_offset.match(time.strftime('%z'))\n" -" has_offset = False\n" -" if m and time.timezone:\n" -" hrs, mins = m.groups()\n" -" if int(hrs) or int(mins):\n" -" has_offset = True\n" -" if not has_offset:\n" -" asctime += 'Z'\n" -" else:\n" -" asctime += f'{hrs}:{mins}'\n" -" try:\n" -" hostname = socket.gethostname()\n" -" except Exception:\n" -" hostname = '-'\n" -" appname = self.appname or '-'\n" -" procid = record.process\n" -" msgid = '-'\n" -" msg = super().format(record)\n" -" sdata = '-'\n" -" if hasattr(record, 'structured_data'):\n" -" sd = record.structured_data\n" -" # This should be a dict where the keys are SD-ID and the value " -"is a\n" -" # dict mapping PARAM-NAME to PARAM-VALUE (refer to the RFC for " -"what these\n" -" # mean)\n" -" # There's no error checking here - it's purely for illustration, " -"and you\n" -" # can adapt this code for use in production environments\n" -" parts = []\n" -"\n" -" def replacer(m):\n" -" g = m.groups()\n" -" return '\\\\' + g[0]\n" -"\n" -" for sdid, dv in sd.items():\n" -" part = f'[{sdid}'\n" -" for k, v in dv.items():\n" -" s = str(v)\n" -" s = self.escaped.sub(replacer, s)\n" -" part += f' {k}=\"{s}\"'\n" -" part += ']'\n" -" parts.append(part)\n" -" sdata = ''.join(parts)\n" -" return f'{version} {asctime} {hostname} {appname} {procid} {msgid} " -"{sdata} {msg}'" -msgstr "" - -#: ../../howto/logging-cookbook.rst:3927 -msgid "" -"You'll need to be familiar with RFC 5424 to fully understand the above code, " -"and it may be that you have slightly different needs (e.g. for how you pass " -"structural data to the log). Nevertheless, the above should be adaptable to " -"your speciric needs. With the above handler, you'd pass structured data " -"using something like this::" -msgstr "" - -#: ../../howto/logging-cookbook.rst:3932 -msgid "" -"sd = {\n" -" 'foo@12345': {'bar': 'baz', 'baz': 'bozz', 'fizz': r'buzz'},\n" -" 'foo@54321': {'rab': 'baz', 'zab': 'bozz', 'zzif': r'buzz'}\n" -"}\n" -"extra = {'structured_data': sd}\n" -"i = 1\n" -"logger.debug('Message %d', i, extra=extra)" -msgstr "" -"sd = {\n" -" 'foo@12345': {'bar': 'baz', 'baz': 'bozz', 'fizz': r'buzz'},\n" -" 'foo@54321': {'rab': 'baz', 'zab': 'bozz', 'zzif': r'buzz'}\n" -"}\n" -"extra = {'structured_data': sd}\n" -"i = 1\n" -"logger.debug('Message %d', i, extra=extra)" - -#: ../../howto/logging-cookbook.rst:3941 -msgid "How to treat a logger like an output stream" -msgstr "" - -#: ../../howto/logging-cookbook.rst:3943 -msgid "" -"Sometimes, you need to interface to a third-party API which expects a file-" -"like object to write to, but you want to direct the API's output to a " -"logger. You can do this using a class which wraps a logger with a file-like " -"API. Here's a short script illustrating such a class:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:3948 -msgid "" -"import logging\n" -"\n" -"class LoggerWriter:\n" -" def __init__(self, logger, level):\n" -" self.logger = logger\n" -" self.level = level\n" -"\n" -" def write(self, message):\n" -" if message != '\\n': # avoid printing bare newlines, if you like\n" -" self.logger.log(self.level, message)\n" -"\n" -" def flush(self):\n" -" # doesn't actually do anything, but might be expected of a file-" -"like\n" -" # object - so optional depending on your situation\n" -" pass\n" -"\n" -" def close(self):\n" -" # doesn't actually do anything, but might be expected of a file-" -"like\n" -" # object - so optional depending on your situation. You might want\n" -" # to set a flag so that later calls to write raise an exception\n" -" pass\n" -"\n" -"def main():\n" -" logging.basicConfig(level=logging.DEBUG)\n" -" logger = logging.getLogger('demo')\n" -" info_fp = LoggerWriter(logger, logging.INFO)\n" -" debug_fp = LoggerWriter(logger, logging.DEBUG)\n" -" print('An INFO message', file=info_fp)\n" -" print('A DEBUG message', file=debug_fp)\n" -"\n" -"if __name__ == \"__main__\":\n" -" main()" -msgstr "" - -#: ../../howto/logging-cookbook.rst:3983 -msgid "When this script is run, it prints" -msgstr "" - -#: ../../howto/logging-cookbook.rst:3985 -msgid "" -"INFO:demo:An INFO message\n" -"DEBUG:demo:A DEBUG message" -msgstr "" -"INFO:demo:An INFO message\n" -"DEBUG:demo:A DEBUG message" - -#: ../../howto/logging-cookbook.rst:3990 -msgid "" -"You could also use ``LoggerWriter`` to redirect ``sys.stdout`` and " -"``sys.stderr`` by doing something like this:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:3993 -msgid "" -"import sys\n" -"\n" -"sys.stdout = LoggerWriter(logger, logging.INFO)\n" -"sys.stderr = LoggerWriter(logger, logging.WARNING)" -msgstr "" -"import sys\n" -"\n" -"sys.stdout = LoggerWriter(logger, logging.INFO)\n" -"sys.stderr = LoggerWriter(logger, logging.WARNING)" - -#: ../../howto/logging-cookbook.rst:4000 -msgid "" -"You should do this *after* configuring logging for your needs. In the above " -"example, the :func:`~logging.basicConfig` call does this (using the " -"``sys.stderr`` value *before* it is overwritten by a ``LoggerWriter`` " -"instance). Then, you'd get this kind of result:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:4005 -msgid "" -">>> print('Foo')\n" -"INFO:demo:Foo\n" -">>> print('Bar', file=sys.stderr)\n" -"WARNING:demo:Bar\n" -">>>" -msgstr "" -">>> print('Foo')\n" -"INFO:demo:Foo\n" -">>> print('Bar', file=sys.stderr)\n" -"WARNING:demo:Bar\n" -">>>" - -#: ../../howto/logging-cookbook.rst:4013 -msgid "" -"Of course, the examples above show output according to the format used " -"by :func:`~logging.basicConfig`, but you can use a different formatter when " -"you configure logging." -msgstr "" - -#: ../../howto/logging-cookbook.rst:4017 -msgid "" -"Note that with the above scheme, you are somewhat at the mercy of buffering " -"and the sequence of write calls which you are intercepting. For example, " -"with the definition of ``LoggerWriter`` above, if you have the snippet" -msgstr "" - -#: ../../howto/logging-cookbook.rst:4021 -msgid "" -"sys.stderr = LoggerWriter(logger, logging.WARNING)\n" -"1 / 0" -msgstr "" -"sys.stderr = LoggerWriter(logger, logging.WARNING)\n" -"1 / 0" - -#: ../../howto/logging-cookbook.rst:4026 -msgid "then running the script results in" -msgstr "" - -#: ../../howto/logging-cookbook.rst:4028 -msgid "" -"WARNING:demo:Traceback (most recent call last):\n" -"\n" -"WARNING:demo: File \"/home/runner/cookbook-loggerwriter/test.py\", line 53, " -"in \n" -"\n" -"WARNING:demo:\n" -"WARNING:demo:main()\n" -"WARNING:demo: File \"/home/runner/cookbook-loggerwriter/test.py\", line 49, " -"in main\n" -"\n" -"WARNING:demo:\n" -"WARNING:demo:1 / 0\n" -"WARNING:demo:ZeroDivisionError\n" -"WARNING:demo::\n" -"WARNING:demo:division by zero" -msgstr "" -"WARNING:demo:Traceback (most recent call last):\n" -"\n" -"WARNING:demo: File \"/home/runner/cookbook-loggerwriter/test.py\", line 53, " -"in \n" -"\n" -"WARNING:demo:\n" -"WARNING:demo:main()\n" -"WARNING:demo: File \"/home/runner/cookbook-loggerwriter/test.py\", line 49, " -"in main\n" -"\n" -"WARNING:demo:\n" -"WARNING:demo:1 / 0\n" -"WARNING:demo:ZeroDivisionError\n" -"WARNING:demo::\n" -"WARNING:demo:division by zero" - -#: ../../howto/logging-cookbook.rst:4044 -msgid "" -"As you can see, this output isn't ideal. That's because the underlying code " -"which writes to ``sys.stderr`` makes multiple writes, each of which results " -"in a separate logged line (for example, the last three lines above). To get " -"around this problem, you need to buffer things and only output log lines " -"when newlines are seen. Let's use a slightly better implementation of " -"``LoggerWriter``:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:4050 -msgid "" -"class BufferingLoggerWriter(LoggerWriter):\n" -" def __init__(self, logger, level):\n" -" super().__init__(logger, level)\n" -" self.buffer = ''\n" -"\n" -" def write(self, message):\n" -" if '\\n' not in message:\n" -" self.buffer += message\n" -" else:\n" -" parts = message.split('\\n')\n" -" if self.buffer:\n" -" s = self.buffer + parts.pop(0)\n" -" self.logger.log(self.level, s)\n" -" self.buffer = parts.pop()\n" -" for part in parts:\n" -" self.logger.log(self.level, part)" -msgstr "" -"class BufferingLoggerWriter(LoggerWriter):\n" -" def __init__(self, logger, level):\n" -" super().__init__(logger, level)\n" -" self.buffer = ''\n" -"\n" -" def write(self, message):\n" -" if '\\n' not in message:\n" -" self.buffer += message\n" -" else:\n" -" parts = message.split('\\n')\n" -" if self.buffer:\n" -" s = self.buffer + parts.pop(0)\n" -" self.logger.log(self.level, s)\n" -" self.buffer = parts.pop()\n" -" for part in parts:\n" -" self.logger.log(self.level, part)" - -#: ../../howto/logging-cookbook.rst:4069 -msgid "" -"This just buffers up stuff until a newline is seen, and then logs complete " -"lines. With this approach, you get better output:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:4072 -msgid "" -"WARNING:demo:Traceback (most recent call last):\n" -"WARNING:demo: File \"/home/runner/cookbook-loggerwriter/main.py\", line 55, " -"in \n" -"WARNING:demo: main()\n" -"WARNING:demo: File \"/home/runner/cookbook-loggerwriter/main.py\", line 52, " -"in main\n" -"WARNING:demo: 1/0\n" -"WARNING:demo:ZeroDivisionError: division by zero" -msgstr "" -"WARNING:demo:Traceback (most recent call last):\n" -"WARNING:demo: File \"/home/runner/cookbook-loggerwriter/main.py\", line 55, " -"in \n" -"WARNING:demo: main()\n" -"WARNING:demo: File \"/home/runner/cookbook-loggerwriter/main.py\", line 52, " -"in main\n" -"WARNING:demo: 1/0\n" -"WARNING:demo:ZeroDivisionError: division by zero" - -#: ../../howto/logging-cookbook.rst:4082 -msgid "How to uniformly handle newlines in logging output" -msgstr "" - -#: ../../howto/logging-cookbook.rst:4084 -msgid "" -"Usually, messages that are logged (say to console or file) consist of a " -"single line of text. However, sometimes there is a need to handle messages " -"with multiple lines - whether because a logging format string contains " -"newlines, or logged data contains newlines. If you want to handle such " -"messages uniformly, so that each line in the logged message appears " -"uniformly formatted as if it was logged separately, you can do this using a " -"handler mixin, as in the following snippet:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:4092 -msgid "" -"# Assume this is in a module mymixins.py\n" -"import copy\n" -"\n" -"class MultilineMixin:\n" -" def emit(self, record):\n" -" s = record.getMessage()\n" -" if '\\n' not in s:\n" -" super().emit(record)\n" -" else:\n" -" lines = s.splitlines()\n" -" rec = copy.copy(record)\n" -" rec.args = None\n" -" for line in lines:\n" -" rec.msg = line\n" -" super().emit(rec)" -msgstr "" - -#: ../../howto/logging-cookbook.rst:4110 -msgid "You can use the mixin as in the following script:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:4112 -msgid "" -"import logging\n" -"\n" -"from mymixins import MultilineMixin\n" -"\n" -"logger = logging.getLogger(__name__)\n" -"\n" -"class StreamHandler(MultilineMixin, logging.StreamHandler):\n" -" pass\n" -"\n" -"if __name__ == '__main__':\n" -" logging.basicConfig(level=logging.DEBUG, format='%(asctime)s %" -"(levelname)-9s %(message)s',\n" -" handlers = [StreamHandler()])\n" -" logger.debug('Single line')\n" -" logger.debug('Multiple lines:\\nfool me once ...')\n" -" logger.debug('Another single line')\n" -" logger.debug('Multiple lines:\\n%s', 'fool me ...\\ncan\\'t get fooled " -"again')" -msgstr "" -"import logging\n" -"\n" -"from mymixins import MultilineMixin\n" -"\n" -"logger = logging.getLogger(__name__)\n" -"\n" -"class StreamHandler(MultilineMixin, logging.StreamHandler):\n" -" pass\n" -"\n" -"if __name__ == '__main__':\n" -" logging.basicConfig(level=logging.DEBUG, format='%(asctime)s %" -"(levelname)-9s %(message)s',\n" -" handlers = [StreamHandler()])\n" -" logger.debug('Single line')\n" -" logger.debug('Multiple lines:\\nfool me once ...')\n" -" logger.debug('Another single line')\n" -" logger.debug('Multiple lines:\\n%s', 'fool me ...\\ncan\\'t get fooled " -"again')" - -#: ../../howto/logging-cookbook.rst:4131 -msgid "The script, when run, prints something like:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:4133 -msgid "" -"2025-07-02 13:54:47,234 DEBUG Single line\n" -"2025-07-02 13:54:47,234 DEBUG Multiple lines:\n" -"2025-07-02 13:54:47,234 DEBUG fool me once ...\n" -"2025-07-02 13:54:47,234 DEBUG Another single line\n" -"2025-07-02 13:54:47,234 DEBUG Multiple lines:\n" -"2025-07-02 13:54:47,234 DEBUG fool me ...\n" -"2025-07-02 13:54:47,234 DEBUG can't get fooled again" -msgstr "" -"2025-07-02 13:54:47,234 DEBUG Single line\n" -"2025-07-02 13:54:47,234 DEBUG Multiple lines:\n" -"2025-07-02 13:54:47,234 DEBUG fool me once ...\n" -"2025-07-02 13:54:47,234 DEBUG Another single line\n" -"2025-07-02 13:54:47,234 DEBUG Multiple lines:\n" -"2025-07-02 13:54:47,234 DEBUG fool me ...\n" -"2025-07-02 13:54:47,234 DEBUG can't get fooled again" - -#: ../../howto/logging-cookbook.rst:4143 -msgid "" -"If, on the other hand, you are concerned about `log injection `_, you can use a formatter " -"which escapes newlines, as per the following example:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:4147 -msgid "" -"import logging\n" -"\n" -"logger = logging.getLogger(__name__)\n" -"\n" -"class EscapingFormatter(logging.Formatter):\n" -" def format(self, record):\n" -" s = super().format(record)\n" -" return s.replace('\\n', r'\\n')\n" -"\n" -"if __name__ == '__main__':\n" -" h = logging.StreamHandler()\n" -" h.setFormatter(EscapingFormatter('%(asctime)s %(levelname)-9s %" -"(message)s'))\n" -" logging.basicConfig(level=logging.DEBUG, handlers = [h])\n" -" logger.debug('Single line')\n" -" logger.debug('Multiple lines:\\nfool me once ...')\n" -" logger.debug('Another single line')\n" -" logger.debug('Multiple lines:\\n%s', 'fool me ...\\ncan\\'t get fooled " -"again')" -msgstr "" -"import logging\n" -"\n" -"logger = logging.getLogger(__name__)\n" -"\n" -"class EscapingFormatter(logging.Formatter):\n" -" def format(self, record):\n" -" s = super().format(record)\n" -" return s.replace('\\n', r'\\n')\n" -"\n" -"if __name__ == '__main__':\n" -" h = logging.StreamHandler()\n" -" h.setFormatter(EscapingFormatter('%(asctime)s %(levelname)-9s %" -"(message)s'))\n" -" logging.basicConfig(level=logging.DEBUG, handlers = [h])\n" -" logger.debug('Single line')\n" -" logger.debug('Multiple lines:\\nfool me once ...')\n" -" logger.debug('Another single line')\n" -" logger.debug('Multiple lines:\\n%s', 'fool me ...\\ncan\\'t get fooled " -"again')" - -#: ../../howto/logging-cookbook.rst:4167 -msgid "" -"You can, of course, use whatever escaping scheme makes the most sense for " -"you. The script, when run, should produce output like this:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:4170 -msgid "" -"2025-07-09 06:47:33,783 DEBUG Single line\n" -"2025-07-09 06:47:33,783 DEBUG Multiple lines:\\nfool me once ...\n" -"2025-07-09 06:47:33,783 DEBUG Another single line\n" -"2025-07-09 06:47:33,783 DEBUG Multiple lines:\\nfool me ...\\ncan't get " -"fooled again" -msgstr "" -"2025-07-09 06:47:33,783 DEBUG Single line\n" -"2025-07-09 06:47:33,783 DEBUG Multiple lines:\\nfool me once ...\n" -"2025-07-09 06:47:33,783 DEBUG Another single line\n" -"2025-07-09 06:47:33,783 DEBUG Multiple lines:\\nfool me ...\\ncan't get " -"fooled again" - -#: ../../howto/logging-cookbook.rst:4177 -msgid "" -"Escaping behaviour can't be the stdlib default , as it would break backwards " -"compatibility." -msgstr "" - -#: ../../howto/logging-cookbook.rst:4183 -msgid "Patterns to avoid" -msgstr "" - -#: ../../howto/logging-cookbook.rst:4185 -msgid "" -"Although the preceding sections have described ways of doing things you " -"might need to do or deal with, it is worth mentioning some usage patterns " -"which are *unhelpful*, and which should therefore be avoided in most cases. " -"The following sections are in no particular order." -msgstr "" - -#: ../../howto/logging-cookbook.rst:4191 -msgid "Opening the same log file multiple times" -msgstr "" - -#: ../../howto/logging-cookbook.rst:4193 -msgid "" -"On Windows, you will generally not be able to open the same file multiple " -"times as this will lead to a \"file is in use by another process\" error. " -"However, on POSIX platforms you'll not get any errors if you open the same " -"file multiple times. This could be done accidentally, for example by:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:4198 -msgid "" -"Adding a file handler more than once which references the same file (e.g. by " -"a copy/paste/forget-to-change error)." -msgstr "" - -#: ../../howto/logging-cookbook.rst:4201 -msgid "" -"Opening two files that look different, as they have different names, but are " -"the same because one is a symbolic link to the other." -msgstr "" - -#: ../../howto/logging-cookbook.rst:4204 -msgid "" -"Forking a process, following which both parent and child have a reference to " -"the same file. This might be through use of the :mod:`multiprocessing` " -"module, for example." -msgstr "" - -#: ../../howto/logging-cookbook.rst:4208 -msgid "" -"Opening a file multiple times might *appear* to work most of the time, but " -"can lead to a number of problems in practice:" -msgstr "" - -#: ../../howto/logging-cookbook.rst:4211 -msgid "" -"Logging output can be garbled because multiple threads or processes try to " -"write to the same file. Although logging guards against concurrent use of " -"the same handler instance by multiple threads, there is no such protection " -"if concurrent writes are attempted by two different threads using two " -"different handler instances which happen to point to the same file." -msgstr "" - -#: ../../howto/logging-cookbook.rst:4217 -msgid "" -"An attempt to delete a file (e.g. during file rotation) silently fails, " -"because there is another reference pointing to it. This can lead to " -"confusion and wasted debugging time - log entries end up in unexpected " -"places, or are lost altogether. Or a file that was supposed to be moved " -"remains in place, and grows in size unexpectedly despite size-based rotation " -"being supposedly in place." -msgstr "" - -#: ../../howto/logging-cookbook.rst:4224 -msgid "" -"Use the techniques outlined in :ref:`multiple-processes` to circumvent such " -"issues." -msgstr "" - -#: ../../howto/logging-cookbook.rst:4228 -msgid "Using loggers as attributes in a class or passing them as parameters" -msgstr "" - -#: ../../howto/logging-cookbook.rst:4230 -msgid "" -"While there might be unusual cases where you'll need to do this, in general " -"there is no point because loggers are singletons. Code can always access a " -"given logger instance by name using ``logging.getLogger(name)``, so passing " -"instances around and holding them as instance attributes is pointless. Note " -"that in other languages such as Java and C#, loggers are often static class " -"attributes. However, this pattern doesn't make sense in Python, where the " -"module (and not the class) is the unit of software decomposition." -msgstr "" - -#: ../../howto/logging-cookbook.rst:4239 -msgid "" -"Adding handlers other than :class:`~logging.NullHandler` to a logger in a " -"library" -msgstr "" - -#: ../../howto/logging-cookbook.rst:4241 -msgid "" -"Configuring logging by adding handlers, formatters and filters is the " -"responsibility of the application developer, not the library developer. If " -"you are maintaining a library, ensure that you don't add handlers to any of " -"your loggers other than a :class:`~logging.NullHandler` instance." -msgstr "" - -#: ../../howto/logging-cookbook.rst:4247 -msgid "Creating a lot of loggers" -msgstr "" - -#: ../../howto/logging-cookbook.rst:4249 -msgid "" -"Loggers are singletons that are never freed during a script execution, and " -"so creating lots of loggers will use up memory which can't then be freed. " -"Rather than create a logger per e.g. file processed or network connection " -"made, use the :ref:`existing mechanisms ` for passing " -"contextual information into your logs and restrict the loggers created to " -"those describing areas within your application (generally modules, but " -"occasionally slightly more fine-grained than that)." -msgstr "" - -#: ../../howto/logging-cookbook.rst:4260 -msgid "Other resources" -msgstr "其他資源" - -#: ../../howto/logging-cookbook.rst:4264 -msgid "Module :mod:`logging`" -msgstr ":mod:`logging` 模組" - -#: ../../howto/logging-cookbook.rst:4265 -msgid "API reference for the logging module." -msgstr "" - -#: ../../howto/logging-cookbook.rst:4267 -msgid "Module :mod:`logging.config`" -msgstr ":mod:`logging.config` 模組" - -#: ../../howto/logging-cookbook.rst:4268 -msgid "Configuration API for the logging module." -msgstr "" - -#: ../../howto/logging-cookbook.rst:4270 -msgid "Module :mod:`logging.handlers`" -msgstr ":mod:`logging.handlers` 模組" - -#: ../../howto/logging-cookbook.rst:4271 -msgid "Useful handlers included with the logging module." -msgstr "" - -#: ../../howto/logging-cookbook.rst:4273 -msgid ":ref:`Basic Tutorial `" -msgstr ":ref:`基礎教學 `" - -#: ../../howto/logging-cookbook.rst:4275 -msgid ":ref:`Advanced Tutorial `" -msgstr ":ref:`進階教學 `" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: 2018-05-23 14:36+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" + +#: ../../howto/logging-cookbook.rst:5 +msgid "Logging Cookbook" +msgstr "" + +#: ../../howto/logging-cookbook.rst:0 +msgid "Author" +msgstr "作者" + +#: ../../howto/logging-cookbook.rst:7 +msgid "Vinay Sajip " +msgstr "Vinay Sajip " + +#: ../../howto/logging-cookbook.rst:9 +msgid "" +"This page contains a number of recipes related to logging, which have been " +"found useful in the past. For links to tutorial and reference information, " +"please see :ref:`cookbook-ref-links`." +msgstr "" + +#: ../../howto/logging-cookbook.rst:16 +msgid "Using logging in multiple modules" +msgstr "" + +#: ../../howto/logging-cookbook.rst:18 +msgid "" +"Multiple calls to ``logging.getLogger('someLogger')`` return a reference to " +"the same logger object. This is true not only within the same module, but " +"also across modules as long as it is in the same Python interpreter " +"process. It is true for references to the same object; additionally, " +"application code can define and configure a parent logger in one module and " +"create (but not configure) a child logger in a separate module, and all " +"logger calls to the child will pass up to the parent. Here is a main " +"module::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:26 +msgid "" +"import logging\n" +"import auxiliary_module\n" +"\n" +"# create logger with 'spam_application'\n" +"logger = logging.getLogger('spam_application')\n" +"logger.setLevel(logging.DEBUG)\n" +"# create file handler which logs even debug messages\n" +"fh = logging.FileHandler('spam.log')\n" +"fh.setLevel(logging.DEBUG)\n" +"# create console handler with a higher log level\n" +"ch = logging.StreamHandler()\n" +"ch.setLevel(logging.ERROR)\n" +"# create formatter and add it to the handlers\n" +"formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %" +"(message)s')\n" +"fh.setFormatter(formatter)\n" +"ch.setFormatter(formatter)\n" +"# add the handlers to the logger\n" +"logger.addHandler(fh)\n" +"logger.addHandler(ch)\n" +"\n" +"logger.info('creating an instance of auxiliary_module.Auxiliary')\n" +"a = auxiliary_module.Auxiliary()\n" +"logger.info('created an instance of auxiliary_module.Auxiliary')\n" +"logger.info('calling auxiliary_module.Auxiliary.do_something')\n" +"a.do_something()\n" +"logger.info('finished auxiliary_module.Auxiliary.do_something')\n" +"logger.info('calling auxiliary_module.some_function()')\n" +"auxiliary_module.some_function()\n" +"logger.info('done with auxiliary_module.some_function()')" +msgstr "" + +#: ../../howto/logging-cookbook.rst:56 +msgid "Here is the auxiliary module::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:58 +msgid "" +"import logging\n" +"\n" +"# create logger\n" +"module_logger = logging.getLogger('spam_application.auxiliary')\n" +"\n" +"class Auxiliary:\n" +" def __init__(self):\n" +" self.logger = " +"logging.getLogger('spam_application.auxiliary.Auxiliary')\n" +" self.logger.info('creating an instance of Auxiliary')\n" +"\n" +" def do_something(self):\n" +" self.logger.info('doing something')\n" +" a = 1 + 1\n" +" self.logger.info('done doing something')\n" +"\n" +"def some_function():\n" +" module_logger.info('received a call to \"some_function\"')" +msgstr "" + +#: ../../howto/logging-cookbook.rst:76 +msgid "The output looks like this:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:78 +msgid "" +"2005-03-23 23:47:11,663 - spam_application - INFO -\n" +" creating an instance of auxiliary_module.Auxiliary\n" +"2005-03-23 23:47:11,665 - spam_application.auxiliary.Auxiliary - INFO -\n" +" creating an instance of Auxiliary\n" +"2005-03-23 23:47:11,665 - spam_application - INFO -\n" +" created an instance of auxiliary_module.Auxiliary\n" +"2005-03-23 23:47:11,668 - spam_application - INFO -\n" +" calling auxiliary_module.Auxiliary.do_something\n" +"2005-03-23 23:47:11,668 - spam_application.auxiliary.Auxiliary - INFO -\n" +" doing something\n" +"2005-03-23 23:47:11,669 - spam_application.auxiliary.Auxiliary - INFO -\n" +" done doing something\n" +"2005-03-23 23:47:11,670 - spam_application - INFO -\n" +" finished auxiliary_module.Auxiliary.do_something\n" +"2005-03-23 23:47:11,671 - spam_application - INFO -\n" +" calling auxiliary_module.some_function()\n" +"2005-03-23 23:47:11,672 - spam_application.auxiliary - INFO -\n" +" received a call to 'some_function'\n" +"2005-03-23 23:47:11,673 - spam_application - INFO -\n" +" done with auxiliary_module.some_function()" +msgstr "" + +#: ../../howto/logging-cookbook.rst:102 +msgid "Logging from multiple threads" +msgstr "" + +#: ../../howto/logging-cookbook.rst:104 +msgid "" +"Logging from multiple threads requires no special effort. The following " +"example shows logging from the main (initial) thread and another thread::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:107 +msgid "" +"import logging\n" +"import threading\n" +"import time\n" +"\n" +"def worker(arg):\n" +" while not arg['stop']:\n" +" logging.debug('Hi from myfunc')\n" +" time.sleep(0.5)\n" +"\n" +"def main():\n" +" logging.basicConfig(level=logging.DEBUG, format='%(relativeCreated)6d %" +"(threadName)s %(message)s')\n" +" info = {'stop': False}\n" +" thread = threading.Thread(target=worker, args=(info,))\n" +" thread.start()\n" +" while True:\n" +" try:\n" +" logging.debug('Hello from main')\n" +" time.sleep(0.75)\n" +" except KeyboardInterrupt:\n" +" info['stop'] = True\n" +" break\n" +" thread.join()\n" +"\n" +"if __name__ == '__main__':\n" +" main()" +msgstr "" + +#: ../../howto/logging-cookbook.rst:133 +msgid "When run, the script should print something like the following:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:135 +msgid "" +" 0 Thread-1 Hi from myfunc\n" +" 3 MainThread Hello from main\n" +" 505 Thread-1 Hi from myfunc\n" +" 755 MainThread Hello from main\n" +"1007 Thread-1 Hi from myfunc\n" +"1507 MainThread Hello from main\n" +"1508 Thread-1 Hi from myfunc\n" +"2010 Thread-1 Hi from myfunc\n" +"2258 MainThread Hello from main\n" +"2512 Thread-1 Hi from myfunc\n" +"3009 MainThread Hello from main\n" +"3013 Thread-1 Hi from myfunc\n" +"3515 Thread-1 Hi from myfunc\n" +"3761 MainThread Hello from main\n" +"4017 Thread-1 Hi from myfunc\n" +"4513 MainThread Hello from main\n" +"4518 Thread-1 Hi from myfunc" +msgstr "" + +#: ../../howto/logging-cookbook.rst:155 +msgid "" +"This shows the logging output interspersed as one might expect. This " +"approach works for more threads than shown here, of course." +msgstr "" + +#: ../../howto/logging-cookbook.rst:159 +msgid "Multiple handlers and formatters" +msgstr "" + +#: ../../howto/logging-cookbook.rst:161 +msgid "" +"Loggers are plain Python objects. The :meth:`~Logger.addHandler` method has " +"no minimum or maximum quota for the number of handlers you may add. " +"Sometimes it will be beneficial for an application to log all messages of " +"all severities to a text file while simultaneously logging errors or above " +"to the console. To set this up, simply configure the appropriate handlers. " +"The logging calls in the application code will remain unchanged. Here is a " +"slight modification to the previous simple module-based configuration " +"example::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:169 +msgid "" +"import logging\n" +"\n" +"logger = logging.getLogger('simple_example')\n" +"logger.setLevel(logging.DEBUG)\n" +"# create file handler which logs even debug messages\n" +"fh = logging.FileHandler('spam.log')\n" +"fh.setLevel(logging.DEBUG)\n" +"# create console handler with a higher log level\n" +"ch = logging.StreamHandler()\n" +"ch.setLevel(logging.ERROR)\n" +"# create formatter and add it to the handlers\n" +"formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %" +"(message)s')\n" +"ch.setFormatter(formatter)\n" +"fh.setFormatter(formatter)\n" +"# add the handlers to logger\n" +"logger.addHandler(ch)\n" +"logger.addHandler(fh)\n" +"\n" +"# 'application' code\n" +"logger.debug('debug message')\n" +"logger.info('info message')\n" +"logger.warning('warn message')\n" +"logger.error('error message')\n" +"logger.critical('critical message')" +msgstr "" + +#: ../../howto/logging-cookbook.rst:194 +msgid "" +"Notice that the 'application' code does not care about multiple handlers. " +"All that changed was the addition and configuration of a new handler named " +"*fh*." +msgstr "" + +#: ../../howto/logging-cookbook.rst:197 +msgid "" +"The ability to create new handlers with higher- or lower-severity filters " +"can be very helpful when writing and testing an application. Instead of " +"using many ``print`` statements for debugging, use ``logger.debug``: Unlike " +"the print statements, which you will have to delete or comment out later, " +"the logger.debug statements can remain intact in the source code and remain " +"dormant until you need them again. At that time, the only change that needs " +"to happen is to modify the severity level of the logger and/or handler to " +"debug." +msgstr "" + +#: ../../howto/logging-cookbook.rst:208 +msgid "Logging to multiple destinations" +msgstr "" + +#: ../../howto/logging-cookbook.rst:210 +msgid "" +"Let's say you want to log to console and file with different message formats " +"and in differing circumstances. Say you want to log messages with levels of " +"DEBUG and higher to file, and those messages at level INFO and higher to the " +"console. Let's also assume that the file should contain timestamps, but the " +"console messages should not. Here's how you can achieve this::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:216 +msgid "" +"import logging\n" +"\n" +"# set up logging to file - see previous section for more details\n" +"logging.basicConfig(level=logging.DEBUG,\n" +" format='%(asctime)s %(name)-12s %(levelname)-8s %" +"(message)s',\n" +" datefmt='%m-%d %H:%M',\n" +" filename='/tmp/myapp.log',\n" +" filemode='w')\n" +"# define a Handler which writes INFO messages or higher to the sys.stderr\n" +"console = logging.StreamHandler()\n" +"console.setLevel(logging.INFO)\n" +"# set a format which is simpler for console use\n" +"formatter = logging.Formatter('%(name)-12s: %(levelname)-8s %(message)s')\n" +"# tell the handler to use this format\n" +"console.setFormatter(formatter)\n" +"# add the handler to the root logger\n" +"logging.getLogger('').addHandler(console)\n" +"\n" +"# Now, we can log to the root logger, or any other logger. First the " +"root...\n" +"logging.info('Jackdaws love my big sphinx of quartz.')\n" +"\n" +"# Now, define a couple of other loggers which might represent areas in your\n" +"# application:\n" +"\n" +"logger1 = logging.getLogger('myapp.area1')\n" +"logger2 = logging.getLogger('myapp.area2')\n" +"\n" +"logger1.debug('Quick zephyrs blow, vexing daft Jim.')\n" +"logger1.info('How quickly daft jumping zebras vex.')\n" +"logger2.warning('Jail zesty vixen who grabbed pay from quack.')\n" +"logger2.error('The five boxing wizards jump quickly.')" +msgstr "" + +#: ../../howto/logging-cookbook.rst:248 +msgid "When you run this, on the console you will see" +msgstr "" + +#: ../../howto/logging-cookbook.rst:250 +msgid "" +"root : INFO Jackdaws love my big sphinx of quartz.\n" +"myapp.area1 : INFO How quickly daft jumping zebras vex.\n" +"myapp.area2 : WARNING Jail zesty vixen who grabbed pay from quack.\n" +"myapp.area2 : ERROR The five boxing wizards jump quickly." +msgstr "" + +#: ../../howto/logging-cookbook.rst:257 +msgid "and in the file you will see something like" +msgstr "" + +#: ../../howto/logging-cookbook.rst:259 +msgid "" +"10-22 22:19 root INFO Jackdaws love my big sphinx of quartz.\n" +"10-22 22:19 myapp.area1 DEBUG Quick zephyrs blow, vexing daft Jim.\n" +"10-22 22:19 myapp.area1 INFO How quickly daft jumping zebras vex.\n" +"10-22 22:19 myapp.area2 WARNING Jail zesty vixen who grabbed pay from " +"quack.\n" +"10-22 22:19 myapp.area2 ERROR The five boxing wizards jump quickly." +msgstr "" + +#: ../../howto/logging-cookbook.rst:267 +msgid "" +"As you can see, the DEBUG message only shows up in the file. The other " +"messages are sent to both destinations." +msgstr "" + +#: ../../howto/logging-cookbook.rst:270 +msgid "" +"This example uses console and file handlers, but you can use any number and " +"combination of handlers you choose." +msgstr "" + +#: ../../howto/logging-cookbook.rst:273 +msgid "" +"Note that the above choice of log filename ``/tmp/myapp.log`` implies use of " +"a standard location for temporary files on POSIX systems. On Windows, you " +"may need to choose a different directory name for the log - just ensure that " +"the directory exists and that you have the permissions to create and update " +"files in it." +msgstr "" + +#: ../../howto/logging-cookbook.rst:282 +msgid "Custom handling of levels" +msgstr "" + +#: ../../howto/logging-cookbook.rst:284 +msgid "" +"Sometimes, you might want to do something slightly different from the " +"standard handling of levels in handlers, where all levels above a threshold " +"get processed by a handler. To do this, you need to use filters. Let's look " +"at a scenario where you want to arrange things as follows:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:289 +msgid "Send messages of severity ``INFO`` and ``WARNING`` to ``sys.stdout``" +msgstr "" + +#: ../../howto/logging-cookbook.rst:290 +msgid "Send messages of severity ``ERROR`` and above to ``sys.stderr``" +msgstr "" + +#: ../../howto/logging-cookbook.rst:291 +msgid "Send messages of severity ``DEBUG`` and above to file ``app.log``" +msgstr "" + +#: ../../howto/logging-cookbook.rst:293 +msgid "Suppose you configure logging with the following JSON:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:295 +msgid "" +"{\n" +" \"version\": 1,\n" +" \"disable_existing_loggers\": false,\n" +" \"formatters\": {\n" +" \"simple\": {\n" +" \"format\": \"%(levelname)-8s - %(message)s\"\n" +" }\n" +" },\n" +" \"handlers\": {\n" +" \"stdout\": {\n" +" \"class\": \"logging.StreamHandler\",\n" +" \"level\": \"INFO\",\n" +" \"formatter\": \"simple\",\n" +" \"stream\": \"ext://sys.stdout\"\n" +" },\n" +" \"stderr\": {\n" +" \"class\": \"logging.StreamHandler\",\n" +" \"level\": \"ERROR\",\n" +" \"formatter\": \"simple\",\n" +" \"stream\": \"ext://sys.stderr\"\n" +" },\n" +" \"file\": {\n" +" \"class\": \"logging.FileHandler\",\n" +" \"formatter\": \"simple\",\n" +" \"filename\": \"app.log\",\n" +" \"mode\": \"w\"\n" +" }\n" +" },\n" +" \"root\": {\n" +" \"level\": \"DEBUG\",\n" +" \"handlers\": [\n" +" \"stderr\",\n" +" \"stdout\",\n" +" \"file\"\n" +" ]\n" +" }\n" +"}" +msgstr "" + +#: ../../howto/logging-cookbook.rst:335 +msgid "" +"This configuration does *almost* what we want, except that ``sys.stdout`` " +"would show messages of severity ``ERROR`` and only events of this severity " +"and higher will be tracked as well as ``INFO`` and ``WARNING`` messages. To " +"prevent this, we can set up a filter which excludes those messages and add " +"it to the relevant handler. This can be configured by adding a ``filters`` " +"section parallel to ``formatters`` and ``handlers``:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:341 +msgid "" +"{\n" +" \"filters\": {\n" +" \"warnings_and_below\": {\n" +" \"()\" : \"__main__.filter_maker\",\n" +" \"level\": \"WARNING\"\n" +" }\n" +" }\n" +"}" +msgstr "" + +#: ../../howto/logging-cookbook.rst:352 +msgid "and changing the section on the ``stdout`` handler to add it:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:354 +msgid "" +"{\n" +" \"stdout\": {\n" +" \"class\": \"logging.StreamHandler\",\n" +" \"level\": \"INFO\",\n" +" \"formatter\": \"simple\",\n" +" \"stream\": \"ext://sys.stdout\",\n" +" \"filters\": [\"warnings_and_below\"]\n" +" }\n" +"}" +msgstr "" + +#: ../../howto/logging-cookbook.rst:366 +msgid "" +"A filter is just a function, so we can define the ``filter_maker`` (a " +"factory function) as follows:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:369 +msgid "" +"def filter_maker(level):\n" +" level = getattr(logging, level)\n" +"\n" +" def filter(record):\n" +" return record.levelno <= level\n" +"\n" +" return filter" +msgstr "" +"def filter_maker(level):\n" +" level = getattr(logging, level)\n" +"\n" +" def filter(record):\n" +" return record.levelno <= level\n" +"\n" +" return filter" + +#: ../../howto/logging-cookbook.rst:379 +msgid "" +"This converts the string argument passed in to a numeric level, and returns " +"a function which only returns ``True`` if the level of the passed in record " +"is at or below the specified level. Note that in this example I have defined " +"the ``filter_maker`` in a test script ``main.py`` that I run from the " +"command line, so its module will be ``__main__`` - hence the " +"``__main__.filter_maker`` in the filter configuration. You will need to " +"change that if you define it in a different module." +msgstr "" + +#: ../../howto/logging-cookbook.rst:387 +msgid "With the filter added, we can run ``main.py``, which in full is:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:389 +msgid "" +"import json\n" +"import logging\n" +"import logging.config\n" +"\n" +"CONFIG = '''\n" +"{\n" +" \"version\": 1,\n" +" \"disable_existing_loggers\": false,\n" +" \"formatters\": {\n" +" \"simple\": {\n" +" \"format\": \"%(levelname)-8s - %(message)s\"\n" +" }\n" +" },\n" +" \"filters\": {\n" +" \"warnings_and_below\": {\n" +" \"()\" : \"__main__.filter_maker\",\n" +" \"level\": \"WARNING\"\n" +" }\n" +" },\n" +" \"handlers\": {\n" +" \"stdout\": {\n" +" \"class\": \"logging.StreamHandler\",\n" +" \"level\": \"INFO\",\n" +" \"formatter\": \"simple\",\n" +" \"stream\": \"ext://sys.stdout\",\n" +" \"filters\": [\"warnings_and_below\"]\n" +" },\n" +" \"stderr\": {\n" +" \"class\": \"logging.StreamHandler\",\n" +" \"level\": \"ERROR\",\n" +" \"formatter\": \"simple\",\n" +" \"stream\": \"ext://sys.stderr\"\n" +" },\n" +" \"file\": {\n" +" \"class\": \"logging.FileHandler\",\n" +" \"formatter\": \"simple\",\n" +" \"filename\": \"app.log\",\n" +" \"mode\": \"w\"\n" +" }\n" +" },\n" +" \"root\": {\n" +" \"level\": \"DEBUG\",\n" +" \"handlers\": [\n" +" \"stderr\",\n" +" \"stdout\",\n" +" \"file\"\n" +" ]\n" +" }\n" +"}\n" +"'''\n" +"\n" +"def filter_maker(level):\n" +" level = getattr(logging, level)\n" +"\n" +" def filter(record):\n" +" return record.levelno <= level\n" +"\n" +" return filter\n" +"\n" +"logging.config.dictConfig(json.loads(CONFIG))\n" +"logging.debug('A DEBUG message')\n" +"logging.info('An INFO message')\n" +"logging.warning('A WARNING message')\n" +"logging.error('An ERROR message')\n" +"logging.critical('A CRITICAL message')" +msgstr "" + +#: ../../howto/logging-cookbook.rst:457 +msgid "And after running it like this:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:459 +msgid "python main.py 2>stderr.log >stdout.log" +msgstr "" + +#: ../../howto/logging-cookbook.rst:463 +msgid "We can see the results are as expected:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:465 +msgid "" +"$ more *.log\n" +"::::::::::::::\n" +"app.log\n" +"::::::::::::::\n" +"DEBUG - A DEBUG message\n" +"INFO - An INFO message\n" +"WARNING - A WARNING message\n" +"ERROR - An ERROR message\n" +"CRITICAL - A CRITICAL message\n" +"::::::::::::::\n" +"stderr.log\n" +"::::::::::::::\n" +"ERROR - An ERROR message\n" +"CRITICAL - A CRITICAL message\n" +"::::::::::::::\n" +"stdout.log\n" +"::::::::::::::\n" +"INFO - An INFO message\n" +"WARNING - A WARNING message" +msgstr "" + +#: ../../howto/logging-cookbook.rst:489 +msgid "Configuration server example" +msgstr "" + +#: ../../howto/logging-cookbook.rst:491 +msgid "Here is an example of a module using the logging configuration server::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:493 +msgid "" +"import logging\n" +"import logging.config\n" +"import time\n" +"import os\n" +"\n" +"# read initial config file\n" +"logging.config.fileConfig('logging.conf')\n" +"\n" +"# create and start listener on port 9999\n" +"t = logging.config.listen(9999)\n" +"t.start()\n" +"\n" +"logger = logging.getLogger('simpleExample')\n" +"\n" +"try:\n" +" # loop through logging calls to see the difference\n" +" # new configurations make, until Ctrl+C is pressed\n" +" while True:\n" +" logger.debug('debug message')\n" +" logger.info('info message')\n" +" logger.warning('warn message')\n" +" logger.error('error message')\n" +" logger.critical('critical message')\n" +" time.sleep(5)\n" +"except KeyboardInterrupt:\n" +" # cleanup\n" +" logging.config.stopListening()\n" +" t.join()" +msgstr "" + +#: ../../howto/logging-cookbook.rst:522 +msgid "" +"And here is a script that takes a filename and sends that file to the " +"server, properly preceded with the binary-encoded length, as the new logging " +"configuration::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:526 +msgid "" +"#!/usr/bin/env python\n" +"import socket, sys, struct\n" +"\n" +"with open(sys.argv[1], 'rb') as f:\n" +" data_to_send = f.read()\n" +"\n" +"HOST = 'localhost'\n" +"PORT = 9999\n" +"s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)\n" +"print('connecting...')\n" +"s.connect((HOST, PORT))\n" +"print('sending config...')\n" +"s.send(struct.pack('>L', len(data_to_send)))\n" +"s.send(data_to_send)\n" +"s.close()\n" +"print('complete')" +msgstr "" +"#!/usr/bin/env python\n" +"import socket, sys, struct\n" +"\n" +"with open(sys.argv[1], 'rb') as f:\n" +" data_to_send = f.read()\n" +"\n" +"HOST = 'localhost'\n" +"PORT = 9999\n" +"s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)\n" +"print('connecting...')\n" +"s.connect((HOST, PORT))\n" +"print('sending config...')\n" +"s.send(struct.pack('>L', len(data_to_send)))\n" +"s.send(data_to_send)\n" +"s.close()\n" +"print('complete')" + +#: ../../howto/logging-cookbook.rst:547 +msgid "Dealing with handlers that block" +msgstr "" + +#: ../../howto/logging-cookbook.rst:551 +msgid "" +"Sometimes you have to get your logging handlers to do their work without " +"blocking the thread you're logging from. This is common in web applications, " +"though of course it also occurs in other scenarios." +msgstr "" + +#: ../../howto/logging-cookbook.rst:555 +msgid "" +"A common culprit which demonstrates sluggish behaviour is " +"the :class:`SMTPHandler`: sending emails can take a long time, for a number " +"of reasons outside the developer's control (for example, a poorly performing " +"mail or network infrastructure). But almost any network-based handler can " +"block: Even a :class:`SocketHandler` operation may do a DNS query under the " +"hood which is too slow (and this query can be deep in the socket library " +"code, below the Python layer, and outside your control)." +msgstr "" + +#: ../../howto/logging-cookbook.rst:563 +msgid "" +"One solution is to use a two-part approach. For the first part, attach only " +"a :class:`QueueHandler` to those loggers which are accessed from performance-" +"critical threads. They simply write to their queue, which can be sized to a " +"large enough capacity or initialized with no upper bound to their size. The " +"write to the queue will typically be accepted quickly, though you will " +"probably need to catch the :exc:`queue.Full` exception as a precaution in " +"your code. If you are a library developer who has performance-critical " +"threads in their code, be sure to document this (together with a suggestion " +"to attach only ``QueueHandlers`` to your loggers) for the benefit of other " +"developers who will use your code." +msgstr "" + +#: ../../howto/logging-cookbook.rst:574 +msgid "" +"The second part of the solution is :class:`QueueListener`, which has been " +"designed as the counterpart to :class:`QueueHandler`. " +"A :class:`QueueListener` is very simple: it's passed a queue and some " +"handlers, and it fires up an internal thread which listens to its queue for " +"LogRecords sent from ``QueueHandlers`` (or any other source of " +"``LogRecords``, for that matter). The ``LogRecords`` are removed from the " +"queue and passed to the handlers for processing." +msgstr "" + +#: ../../howto/logging-cookbook.rst:582 +msgid "" +"The advantage of having a separate :class:`QueueListener` class is that you " +"can use the same instance to service multiple ``QueueHandlers``. This is " +"more resource-friendly than, say, having threaded versions of the existing " +"handler classes, which would eat up one thread per handler for no particular " +"benefit." +msgstr "" + +#: ../../howto/logging-cookbook.rst:587 +msgid "An example of using these two classes follows (imports omitted)::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:589 +msgid "" +"que = queue.Queue(-1) # no limit on size\n" +"queue_handler = QueueHandler(que)\n" +"handler = logging.StreamHandler()\n" +"listener = QueueListener(que, handler)\n" +"root = logging.getLogger()\n" +"root.addHandler(queue_handler)\n" +"formatter = logging.Formatter('%(threadName)s: %(message)s')\n" +"handler.setFormatter(formatter)\n" +"listener.start()\n" +"# The log output will display the thread which generated\n" +"# the event (the main thread) rather than the internal\n" +"# thread which monitors the internal queue. This is what\n" +"# you want to happen.\n" +"root.warning('Look out!')\n" +"listener.stop()" +msgstr "" + +#: ../../howto/logging-cookbook.rst:605 +msgid "which, when run, will produce:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:607 +msgid "MainThread: Look out!" +msgstr "" + +#: ../../howto/logging-cookbook.rst:611 +msgid "" +"Although the earlier discussion wasn't specifically talking about async " +"code, but rather about slow logging handlers, it should be noted that when " +"logging from async code, network and even file handlers could lead to " +"problems (blocking the event loop) because some logging is done " +"from :mod:`asyncio` internals. It might be best, if any async code is used " +"in an application, to use the above approach for logging, so that any " +"blocking code runs only in the ``QueueListener`` thread." +msgstr "" + +#: ../../howto/logging-cookbook.rst:619 +msgid "" +"Prior to Python 3.5, the :class:`QueueListener` always passed every message " +"received from the queue to every handler it was initialized with. (This was " +"because it was assumed that level filtering was all done on the other side, " +"where the queue is filled.) From 3.5 onwards, this behaviour can be changed " +"by passing a keyword argument ``respect_handler_level=True`` to the " +"listener's constructor. When this is done, the listener compares the level " +"of each message with the handler's level, and only passes a message to a " +"handler if it's appropriate to do so." +msgstr "" + +#: ../../howto/logging-cookbook.rst:629 +msgid "" +"The :class:`QueueListener` can be started (and stopped) via " +"the :keyword:`with` statement. For example:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:633 +msgid "" +"with QueueListener(que, handler) as listener:\n" +" # The queue listener automatically starts\n" +" # when the 'with' block is entered.\n" +" pass\n" +"# The queue listener automatically stops once\n" +"# the 'with' block is exited." +msgstr "" + +#: ../../howto/logging-cookbook.rst:645 +msgid "Sending and receiving logging events across a network" +msgstr "" + +#: ../../howto/logging-cookbook.rst:647 +msgid "" +"Let's say you want to send logging events across a network, and handle them " +"at the receiving end. A simple way of doing this is attaching " +"a :class:`SocketHandler` instance to the root logger at the sending end::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:651 +msgid "" +"import logging, logging.handlers\n" +"\n" +"rootLogger = logging.getLogger('')\n" +"rootLogger.setLevel(logging.DEBUG)\n" +"socketHandler = logging.handlers.SocketHandler('localhost',\n" +" logging.handlers.DEFAULT_TCP_LOGGING_PORT)\n" +"# don't bother with a formatter, since a socket handler sends the event as\n" +"# an unformatted pickle\n" +"rootLogger.addHandler(socketHandler)\n" +"\n" +"# Now, we can log to the root logger, or any other logger. First the " +"root...\n" +"logging.info('Jackdaws love my big sphinx of quartz.')\n" +"\n" +"# Now, define a couple of other loggers which might represent areas in your\n" +"# application:\n" +"\n" +"logger1 = logging.getLogger('myapp.area1')\n" +"logger2 = logging.getLogger('myapp.area2')\n" +"\n" +"logger1.debug('Quick zephyrs blow, vexing daft Jim.')\n" +"logger1.info('How quickly daft jumping zebras vex.')\n" +"logger2.warning('Jail zesty vixen who grabbed pay from quack.')\n" +"logger2.error('The five boxing wizards jump quickly.')" +msgstr "" + +#: ../../howto/logging-cookbook.rst:675 +msgid "" +"At the receiving end, you can set up a receiver using " +"the :mod:`socketserver` module. Here is a basic working example::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:678 +msgid "" +"import pickle\n" +"import logging\n" +"import logging.handlers\n" +"import socketserver\n" +"import struct\n" +"\n" +"\n" +"class LogRecordStreamHandler(socketserver.StreamRequestHandler):\n" +" \"\"\"Handler for a streaming logging request.\n" +"\n" +" This basically logs the record using whatever logging policy is\n" +" configured locally.\n" +" \"\"\"\n" +"\n" +" def handle(self):\n" +" \"\"\"\n" +" Handle multiple requests - each expected to be a 4-byte length,\n" +" followed by the LogRecord in pickle format. Logs the record\n" +" according to whatever policy is configured locally.\n" +" \"\"\"\n" +" while True:\n" +" chunk = self.connection.recv(4)\n" +" if len(chunk) < 4:\n" +" break\n" +" slen = struct.unpack('>L', chunk)[0]\n" +" chunk = self.connection.recv(slen)\n" +" while len(chunk) < slen:\n" +" chunk = chunk + self.connection.recv(slen - len(chunk))\n" +" obj = self.unPickle(chunk)\n" +" record = logging.makeLogRecord(obj)\n" +" self.handleLogRecord(record)\n" +"\n" +" def unPickle(self, data):\n" +" return pickle.loads(data)\n" +"\n" +" def handleLogRecord(self, record):\n" +" # if a name is specified, we use the named logger rather than the " +"one\n" +" # implied by the record.\n" +" if self.server.logname is not None:\n" +" name = self.server.logname\n" +" else:\n" +" name = record.name\n" +" logger = logging.getLogger(name)\n" +" # N.B. EVERY record gets logged. This is because Logger.handle\n" +" # is normally called AFTER logger-level filtering. If you want\n" +" # to do filtering, do it at the client end to save wasting\n" +" # cycles and network bandwidth!\n" +" logger.handle(record)\n" +"\n" +"class LogRecordSocketReceiver(socketserver.ThreadingTCPServer):\n" +" \"\"\"\n" +" Simple TCP socket-based logging receiver suitable for testing.\n" +" \"\"\"\n" +"\n" +" allow_reuse_address = True\n" +"\n" +" def __init__(self, host='localhost',\n" +" port=logging.handlers.DEFAULT_TCP_LOGGING_PORT,\n" +" handler=LogRecordStreamHandler):\n" +" socketserver.ThreadingTCPServer.__init__(self, (host, port), " +"handler)\n" +" self.abort = 0\n" +" self.timeout = 1\n" +" self.logname = None\n" +"\n" +" def serve_until_stopped(self):\n" +" import select\n" +" abort = 0\n" +" while not abort:\n" +" rd, wr, ex = select.select([self.socket.fileno()],\n" +" [], [],\n" +" self.timeout)\n" +" if rd:\n" +" self.handle_request()\n" +" abort = self.abort\n" +"\n" +"def main():\n" +" logging.basicConfig(\n" +" format='%(relativeCreated)5d %(name)-15s %(levelname)-8s %" +"(message)s')\n" +" tcpserver = LogRecordSocketReceiver()\n" +" print('About to start TCP server...')\n" +" tcpserver.serve_until_stopped()\n" +"\n" +"if __name__ == '__main__':\n" +" main()" +msgstr "" + +#: ../../howto/logging-cookbook.rst:763 +msgid "" +"First run the server, and then the client. On the client side, nothing is " +"printed on the console; on the server side, you should see something like:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:766 +msgid "" +"About to start TCP server...\n" +" 59 root INFO Jackdaws love my big sphinx of quartz.\n" +" 59 myapp.area1 DEBUG Quick zephyrs blow, vexing daft Jim.\n" +" 69 myapp.area1 INFO How quickly daft jumping zebras vex.\n" +" 69 myapp.area2 WARNING Jail zesty vixen who grabbed pay from quack.\n" +" 69 myapp.area2 ERROR The five boxing wizards jump quickly." +msgstr "" + +#: ../../howto/logging-cookbook.rst:775 +msgid "" +"Note that there are some security issues with pickle in some scenarios. If " +"these affect you, you can use an alternative serialization scheme by " +"overriding the :meth:`~SocketHandler.makePickle` method and implementing " +"your alternative there, as well as adapting the above script to use your " +"alternative serialization." +msgstr "" + +#: ../../howto/logging-cookbook.rst:783 +msgid "Running a logging socket listener in production" +msgstr "" + +#: ../../howto/logging-cookbook.rst:787 +msgid "" +"To run a logging listener in production, you may need to use a process-" +"management tool such as `Supervisor `_. `Here is a " +"Gist `__ which provides the bare-bones files to run " +"the above functionality using Supervisor. It consists of the following files:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:794 +msgid "File" +msgstr "檔案" + +#: ../../howto/logging-cookbook.rst:794 +msgid "Purpose" +msgstr "目的" + +#: ../../howto/logging-cookbook.rst:796 +msgid ":file:`prepare.sh`" +msgstr ":file:`prepare.sh`" + +#: ../../howto/logging-cookbook.rst:796 +msgid "A Bash script to prepare the environment for testing" +msgstr "" + +#: ../../howto/logging-cookbook.rst:799 +msgid ":file:`supervisor.conf`" +msgstr ":file:`supervisor.conf`" + +#: ../../howto/logging-cookbook.rst:799 +msgid "" +"The Supervisor configuration file, which has entries for the listener and a " +"multi-process web application" +msgstr "" + +#: ../../howto/logging-cookbook.rst:803 +msgid ":file:`ensure_app.sh`" +msgstr ":file:`ensure_app.sh`" + +#: ../../howto/logging-cookbook.rst:803 +msgid "" +"A Bash script to ensure that Supervisor is running with the above " +"configuration" +msgstr "" + +#: ../../howto/logging-cookbook.rst:806 +msgid ":file:`log_listener.py`" +msgstr ":file:`log_listener.py`" + +#: ../../howto/logging-cookbook.rst:806 +msgid "" +"The socket listener program which receives log events and records them to a " +"file" +msgstr "" + +#: ../../howto/logging-cookbook.rst:809 +msgid ":file:`main.py`" +msgstr ":file:`main.py`" + +#: ../../howto/logging-cookbook.rst:809 +msgid "" +"A simple web application which performs logging via a socket connected to " +"the listener" +msgstr "" + +#: ../../howto/logging-cookbook.rst:812 +msgid ":file:`webapp.json`" +msgstr ":file:`webapp.json`" + +#: ../../howto/logging-cookbook.rst:812 +msgid "A JSON configuration file for the web application" +msgstr "" + +#: ../../howto/logging-cookbook.rst:814 +msgid ":file:`client.py`" +msgstr ":file:`client.py`" + +#: ../../howto/logging-cookbook.rst:814 +msgid "A Python script to exercise the web application" +msgstr "" + +#: ../../howto/logging-cookbook.rst:817 +msgid "" +"The web application uses `Gunicorn `_, which is a " +"popular web application server that starts multiple worker processes to " +"handle requests. This example setup shows how the workers can write to the " +"same log file without conflicting with one another --- they all go through " +"the socket listener." +msgstr "" + +#: ../../howto/logging-cookbook.rst:822 +msgid "To test these files, do the following in a POSIX environment:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:824 +msgid "" +"Download `the Gist `__ as a ZIP archive using " +"the :guilabel:`Download ZIP` button." +msgstr "" + +#: ../../howto/logging-cookbook.rst:827 +msgid "Unzip the above files from the archive into a scratch directory." +msgstr "" + +#: ../../howto/logging-cookbook.rst:829 +msgid "" +"In the scratch directory, run ``bash prepare.sh`` to get things ready. This " +"creates a :file:`run` subdirectory to contain Supervisor-related and log " +"files, and a :file:`venv` subdirectory to contain a virtual environment into " +"which ``bottle``, ``gunicorn`` and ``supervisor`` are installed." +msgstr "" + +#: ../../howto/logging-cookbook.rst:834 +msgid "" +"Run ``bash ensure_app.sh`` to ensure that Supervisor is running with the " +"above configuration." +msgstr "" + +#: ../../howto/logging-cookbook.rst:837 +msgid "" +"Run ``venv/bin/python client.py`` to exercise the web application, which " +"will lead to records being written to the log." +msgstr "" + +#: ../../howto/logging-cookbook.rst:840 +msgid "" +"Inspect the log files in the :file:`run` subdirectory. You should see the " +"most recent log lines in files matching the pattern :file:`app.log*`. They " +"won't be in any particular order, since they have been handled concurrently " +"by different worker processes in a non-deterministic way." +msgstr "" + +#: ../../howto/logging-cookbook.rst:845 +msgid "" +"You can shut down the listener and the web application by running ``venv/bin/" +"supervisorctl -c supervisor.conf shutdown``." +msgstr "" + +#: ../../howto/logging-cookbook.rst:848 +msgid "" +"You may need to tweak the configuration files in the unlikely event that the " +"configured ports clash with something else in your test environment." +msgstr "" + +#: ../../howto/logging-cookbook.rst:851 +msgid "" +"The default configuration uses a TCP socket on port 9020. You can use a Unix " +"Domain socket instead of a TCP socket by doing the following:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:854 +msgid "" +"In :file:`listener.json`, add a ``socket`` key with the path to the domain " +"socket you want to use. If this key is present, the listener listens on the " +"corresponding domain socket and not on a TCP socket (the ``port`` key is " +"ignored)." +msgstr "" + +#: ../../howto/logging-cookbook.rst:859 +msgid "" +"In :file:`webapp.json`, change the socket handler configuration dictionary " +"so that the ``host`` value is the path to the domain socket, and set the " +"``port`` value to ``null``." +msgstr "" + +#: ../../howto/logging-cookbook.rst:869 +msgid "Adding contextual information to your logging output" +msgstr "" + +#: ../../howto/logging-cookbook.rst:871 +msgid "" +"Sometimes you want logging output to contain contextual information in " +"addition to the parameters passed to the logging call. For example, in a " +"networked application, it may be desirable to log client-specific " +"information in the log (e.g. remote client's username, or IP address). " +"Although you could use the *extra* parameter to achieve this, it's not " +"always convenient to pass the information in this way. While it might be " +"tempting to create :class:`Logger` instances on a per-connection basis, this " +"is not a good idea because these instances are not garbage collected. While " +"this is not a problem in practice, when the number of :class:`Logger` " +"instances is dependent on the level of granularity you want to use in " +"logging an application, it could be hard to manage if the number " +"of :class:`Logger` instances becomes effectively unbounded." +msgstr "" + +#: ../../howto/logging-cookbook.rst:886 +msgid "Using LoggerAdapters to impart contextual information" +msgstr "" + +#: ../../howto/logging-cookbook.rst:888 +msgid "" +"An easy way in which you can pass contextual information to be output along " +"with logging event information is to use the :class:`LoggerAdapter` class. " +"This class is designed to look like a :class:`Logger`, so that you can " +"call :meth:`debug`, :meth:`info`, :meth:`warning`, :meth:`error`, :meth:`exception`, :meth:`critical` " +"and :meth:`log`. These methods have the same signatures as their " +"counterparts in :class:`Logger`, so you can use the two types of instances " +"interchangeably." +msgstr "" + +#: ../../howto/logging-cookbook.rst:896 +msgid "" +"When you create an instance of :class:`LoggerAdapter`, you pass it " +"a :class:`Logger` instance and a dict-like object which contains your " +"contextual information. When you call one of the logging methods on an " +"instance of :class:`LoggerAdapter`, it delegates the call to the underlying " +"instance of :class:`Logger` passed to its constructor, and arranges to pass " +"the contextual information in the delegated call. Here's a snippet from the " +"code of :class:`LoggerAdapter`::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:904 +msgid "" +"def debug(self, msg, /, *args, **kwargs):\n" +" \"\"\"\n" +" Delegate a debug call to the underlying logger, after adding\n" +" contextual information from this adapter instance.\n" +" \"\"\"\n" +" msg, kwargs = self.process(msg, kwargs)\n" +" self.logger.debug(msg, *args, **kwargs)" +msgstr "" + +#: ../../howto/logging-cookbook.rst:912 +msgid "" +"The :meth:`~LoggerAdapter.process` method of :class:`LoggerAdapter` is where " +"the contextual information is added to the logging output. It's passed the " +"message and keyword arguments of the logging call, and it passes back " +"(potentially) modified versions of these to use in the call to the " +"underlying logger. The default implementation of this method leaves the " +"message alone, but inserts an 'extra' key in the keyword argument whose " +"value is the dict-like object passed to the constructor. Of course, if you " +"had passed an 'extra' keyword argument in the call to the adapter, it will " +"be silently overwritten." +msgstr "" + +#: ../../howto/logging-cookbook.rst:921 +msgid "" +"The advantage of using 'extra' is that the values in the dict-like object " +"are merged into the :class:`LogRecord` instance's __dict__, allowing you to " +"use customized strings with your :class:`Formatter` instances which know " +"about the keys of the dict-like object. If you need a different method, e.g. " +"if you want to prepend or append the contextual information to the message " +"string, you just need to subclass :class:`LoggerAdapter` and " +"override :meth:`~LoggerAdapter.process` to do what you need. Here is a " +"simple example::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:929 +msgid "" +"class CustomAdapter(logging.LoggerAdapter):\n" +" \"\"\"\n" +" This example adapter expects the passed in dict-like object to have a\n" +" 'connid' key, whose value in brackets is prepended to the log message.\n" +" \"\"\"\n" +" def process(self, msg, kwargs):\n" +" return '[%s] %s' % (self.extra['connid'], msg), kwargs" +msgstr "" + +#: ../../howto/logging-cookbook.rst:937 +msgid "which you can use like this::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:939 +msgid "" +"logger = logging.getLogger(__name__)\n" +"adapter = CustomAdapter(logger, {'connid': some_conn_id})" +msgstr "" + +#: ../../howto/logging-cookbook.rst:942 +msgid "" +"Then any events that you log to the adapter will have the value of " +"``some_conn_id`` prepended to the log messages." +msgstr "" + +#: ../../howto/logging-cookbook.rst:946 +msgid "Using objects other than dicts to pass contextual information" +msgstr "" + +#: ../../howto/logging-cookbook.rst:948 +msgid "" +"You don't need to pass an actual dict to a :class:`LoggerAdapter` - you " +"could pass an instance of a class which implements ``__getitem__`` and " +"``__iter__`` so that it looks like a dict to logging. This would be useful " +"if you want to generate values dynamically (whereas the values in a dict " +"would be constant)." +msgstr "" + +#: ../../howto/logging-cookbook.rst:957 +msgid "Using Filters to impart contextual information" +msgstr "" + +#: ../../howto/logging-cookbook.rst:959 +msgid "" +"You can also add contextual information to log output using a user-" +"defined :class:`Filter`. ``Filter`` instances are allowed to modify the " +"``LogRecords`` passed to them, including adding additional attributes which " +"can then be output using a suitable format string, or if needed a " +"custom :class:`Formatter`." +msgstr "" + +#: ../../howto/logging-cookbook.rst:964 +msgid "" +"For example in a web application, the request being processed (or at least, " +"the interesting parts of it) can be stored in a threadlocal " +"(:class:`threading.local`) variable, and then accessed from a ``Filter`` to " +"add, say, information from the request - say, the remote IP address and " +"remote user's username - to the ``LogRecord``, using the attribute names " +"'ip' and 'user' as in the ``LoggerAdapter`` example above. In that case, the " +"same format string can be used to get similar output to that shown above. " +"Here's an example script::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:973 +msgid "" +"import logging\n" +"from random import choice\n" +"\n" +"class ContextFilter(logging.Filter):\n" +" \"\"\"\n" +" This is a filter which injects contextual information into the log.\n" +"\n" +" Rather than use actual contextual information, we just use random\n" +" data in this demo.\n" +" \"\"\"\n" +"\n" +" USERS = ['jim', 'fred', 'sheila']\n" +" IPS = ['123.231.231.123', '127.0.0.1', '192.168.0.1']\n" +"\n" +" def filter(self, record):\n" +"\n" +" record.ip = choice(ContextFilter.IPS)\n" +" record.user = choice(ContextFilter.USERS)\n" +" return True\n" +"\n" +"if __name__ == '__main__':\n" +" levels = (logging.DEBUG, logging.INFO, logging.WARNING, logging.ERROR, " +"logging.CRITICAL)\n" +" logging.basicConfig(level=logging.DEBUG,\n" +" format='%(asctime)-15s %(name)-5s %(levelname)-8s " +"IP: %(ip)-15s User: %(user)-8s %(message)s')\n" +" a1 = logging.getLogger('a.b.c')\n" +" a2 = logging.getLogger('d.e.f')\n" +"\n" +" f = ContextFilter()\n" +" a1.addFilter(f)\n" +" a2.addFilter(f)\n" +" a1.debug('A debug message')\n" +" a1.info('An info message with %s', 'some parameters')\n" +" for x in range(10):\n" +" lvl = choice(levels)\n" +" lvlname = logging.getLevelName(lvl)\n" +" a2.log(lvl, 'A message at %s level with %d %s', lvlname, 2, " +"'parameters')" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1010 +msgid "which, when run, produces something like:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1012 +msgid "" +"2010-09-06 22:38:15,292 a.b.c DEBUG IP: 123.231.231.123 User: fred A " +"debug message\n" +"2010-09-06 22:38:15,300 a.b.c INFO IP: 192.168.0.1 User: sheila An " +"info message with some parameters\n" +"2010-09-06 22:38:15,300 d.e.f CRITICAL IP: 127.0.0.1 User: sheila A " +"message at CRITICAL level with 2 parameters\n" +"2010-09-06 22:38:15,300 d.e.f ERROR IP: 127.0.0.1 User: jim A " +"message at ERROR level with 2 parameters\n" +"2010-09-06 22:38:15,300 d.e.f DEBUG IP: 127.0.0.1 User: sheila A " +"message at DEBUG level with 2 parameters\n" +"2010-09-06 22:38:15,300 d.e.f ERROR IP: 123.231.231.123 User: fred A " +"message at ERROR level with 2 parameters\n" +"2010-09-06 22:38:15,300 d.e.f CRITICAL IP: 192.168.0.1 User: jim A " +"message at CRITICAL level with 2 parameters\n" +"2010-09-06 22:38:15,300 d.e.f CRITICAL IP: 127.0.0.1 User: sheila A " +"message at CRITICAL level with 2 parameters\n" +"2010-09-06 22:38:15,300 d.e.f DEBUG IP: 192.168.0.1 User: jim A " +"message at DEBUG level with 2 parameters\n" +"2010-09-06 22:38:15,301 d.e.f ERROR IP: 127.0.0.1 User: sheila A " +"message at ERROR level with 2 parameters\n" +"2010-09-06 22:38:15,301 d.e.f DEBUG IP: 123.231.231.123 User: fred A " +"message at DEBUG level with 2 parameters\n" +"2010-09-06 22:38:15,301 d.e.f INFO IP: 123.231.231.123 User: fred A " +"message at INFO level with 2 parameters" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1028 +msgid "Use of ``contextvars``" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1030 +msgid "" +"Since Python 3.7, the :mod:`contextvars` module has provided context-local " +"storage which works for both :mod:`threading` and :mod:`asyncio` processing " +"needs. This type of storage may thus be generally preferable to thread-" +"locals. The following example shows how, in a multi-threaded environment, " +"logs can populated with contextual information such as, for example, request " +"attributes handled by web applications." +msgstr "" + +#: ../../howto/logging-cookbook.rst:1036 +msgid "" +"For the purposes of illustration, say that you have different web " +"applications, each independent of the other but running in the same Python " +"process and using a library common to them. How can each of these " +"applications have their own log, where all logging messages from the library " +"(and other request processing code) are directed to the appropriate " +"application's log file, while including in the log additional contextual " +"information such as client IP, HTTP request method and client username?" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1043 +msgid "Let's assume that the library can be simulated by the following code:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1045 +msgid "" +"# webapplib.py\n" +"import logging\n" +"import time\n" +"\n" +"logger = logging.getLogger(__name__)\n" +"\n" +"def useful():\n" +" # Just a representative event logged from the library\n" +" logger.debug('Hello from webapplib!')\n" +" # Just sleep for a bit so other threads get to run\n" +" time.sleep(0.01)" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1059 +msgid "" +"We can simulate the multiple web applications by means of two simple " +"classes, ``Request`` and ``WebApp``. These simulate how real threaded web " +"applications work - each request is handled by a thread:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1063 +msgid "" +"# main.py\n" +"import argparse\n" +"from contextvars import ContextVar\n" +"import logging\n" +"import os\n" +"from random import choice\n" +"import threading\n" +"import webapplib\n" +"\n" +"logger = logging.getLogger(__name__)\n" +"root = logging.getLogger()\n" +"root.setLevel(logging.DEBUG)\n" +"\n" +"class Request:\n" +" \"\"\"\n" +" A simple dummy request class which just holds dummy HTTP request " +"method,\n" +" client IP address and client username\n" +" \"\"\"\n" +" def __init__(self, method, ip, user):\n" +" self.method = method\n" +" self.ip = ip\n" +" self.user = user\n" +"\n" +"# A dummy set of requests which will be used in the simulation - we'll just " +"pick\n" +"# from this list randomly. Note that all GET requests are from " +"192.168.2.XXX\n" +"# addresses, whereas POST requests are from 192.16.3.XXX addresses. Three " +"users\n" +"# are represented in the sample requests.\n" +"\n" +"REQUESTS = [\n" +" Request('GET', '192.168.2.20', 'jim'),\n" +" Request('POST', '192.168.3.20', 'fred'),\n" +" Request('GET', '192.168.2.21', 'sheila'),\n" +" Request('POST', '192.168.3.21', 'jim'),\n" +" Request('GET', '192.168.2.22', 'fred'),\n" +" Request('POST', '192.168.3.22', 'sheila'),\n" +"]\n" +"\n" +"# Note that the format string includes references to request context " +"information\n" +"# such as HTTP method, client IP and username\n" +"\n" +"formatter = logging.Formatter('%(threadName)-11s %(appName)s %(name)-9s %" +"(user)-6s %(ip)s %(method)-4s %(message)s')\n" +"\n" +"# Create our context variables. These will be filled at the start of " +"request\n" +"# processing, and used in the logging that happens during that processing\n" +"\n" +"ctx_request = ContextVar('request')\n" +"ctx_appname = ContextVar('appname')\n" +"\n" +"class InjectingFilter(logging.Filter):\n" +" \"\"\"\n" +" A filter which injects context-specific information into logs and " +"ensures\n" +" that only information for a specific webapp is included in its log\n" +" \"\"\"\n" +" def __init__(self, app):\n" +" self.app = app\n" +"\n" +" def filter(self, record):\n" +" request = ctx_request.get()\n" +" record.method = request.method\n" +" record.ip = request.ip\n" +" record.user = request.user\n" +" record.appName = appName = ctx_appname.get()\n" +" return appName == self.app.name\n" +"\n" +"class WebApp:\n" +" \"\"\"\n" +" A dummy web application class which has its own handler and filter for " +"a\n" +" webapp-specific log.\n" +" \"\"\"\n" +" def __init__(self, name):\n" +" self.name = name\n" +" handler = logging.FileHandler(name + '.log', 'w')\n" +" f = InjectingFilter(self)\n" +" handler.setFormatter(formatter)\n" +" handler.addFilter(f)\n" +" root.addHandler(handler)\n" +" self.num_requests = 0\n" +"\n" +" def process_request(self, request):\n" +" \"\"\"\n" +" This is the dummy method for processing a request. It's called on a\n" +" different thread for every request. We store the context information " +"into\n" +" the context vars before doing anything else.\n" +" \"\"\"\n" +" ctx_request.set(request)\n" +" ctx_appname.set(self.name)\n" +" self.num_requests += 1\n" +" logger.debug('Request processing started')\n" +" webapplib.useful()\n" +" logger.debug('Request processing finished')\n" +"\n" +"def main():\n" +" fn = os.path.splitext(os.path.basename(__file__))[0]\n" +" adhf = argparse.ArgumentDefaultsHelpFormatter\n" +" ap = argparse.ArgumentParser(formatter_class=adhf, prog=fn,\n" +" description='Simulate a couple of web '\n" +" 'applications handling some '\n" +" 'requests, showing how request " +"'\n" +" 'context can be used to '\n" +" 'populate logs')\n" +" aa = ap.add_argument\n" +" aa('--count', '-c', type=int, default=100, help='How many requests to " +"simulate')\n" +" options = ap.parse_args()\n" +"\n" +" # Create the dummy webapps and put them in a list which we can use to " +"select\n" +" # from randomly\n" +" app1 = WebApp('app1')\n" +" app2 = WebApp('app2')\n" +" apps = [app1, app2]\n" +" threads = []\n" +" # Add a common handler which will capture all events\n" +" handler = logging.FileHandler('app.log', 'w')\n" +" handler.setFormatter(formatter)\n" +" root.addHandler(handler)\n" +"\n" +" # Generate calls to process requests\n" +" for i in range(options.count):\n" +" try:\n" +" # Pick an app at random and a request for it to process\n" +" app = choice(apps)\n" +" request = choice(REQUESTS)\n" +" # Process the request in its own thread\n" +" t = threading.Thread(target=app.process_request, " +"args=(request,))\n" +" threads.append(t)\n" +" t.start()\n" +" except KeyboardInterrupt:\n" +" break\n" +"\n" +" # Wait for the threads to terminate\n" +" for t in threads:\n" +" t.join()\n" +"\n" +" for app in apps:\n" +" print('%s processed %s requests' % (app.name, app.num_requests))\n" +"\n" +"if __name__ == '__main__':\n" +" main()" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1203 +msgid "" +"If you run the above, you should find that roughly half the requests go " +"into :file:`app1.log` and the rest into :file:`app2.log`, and the all the " +"requests are logged to :file:`app.log`. Each webapp-specific log will " +"contain only log entries for only that webapp, and the request information " +"will be displayed consistently in the log (i.e. the information in each " +"dummy request will always appear together in a log line). This is " +"illustrated by the following shell output:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1210 +msgid "" +"~/logging-contextual-webapp$ python main.py\n" +"app1 processed 51 requests\n" +"app2 processed 49 requests\n" +"~/logging-contextual-webapp$ wc -l *.log\n" +" 153 app1.log\n" +" 147 app2.log\n" +" 300 app.log\n" +" 600 total\n" +"~/logging-contextual-webapp$ head -3 app1.log\n" +"Thread-3 (process_request) app1 __main__ jim 192.168.3.21 POST Request " +"processing started\n" +"Thread-3 (process_request) app1 webapplib jim 192.168.3.21 POST Hello " +"from webapplib!\n" +"Thread-5 (process_request) app1 __main__ jim 192.168.3.21 POST Request " +"processing started\n" +"~/logging-contextual-webapp$ head -3 app2.log\n" +"Thread-1 (process_request) app2 __main__ sheila 192.168.2.21 GET Request " +"processing started\n" +"Thread-1 (process_request) app2 webapplib sheila 192.168.2.21 GET Hello " +"from webapplib!\n" +"Thread-2 (process_request) app2 __main__ jim 192.168.2.20 GET Request " +"processing started\n" +"~/logging-contextual-webapp$ head app.log\n" +"Thread-1 (process_request) app2 __main__ sheila 192.168.2.21 GET Request " +"processing started\n" +"Thread-1 (process_request) app2 webapplib sheila 192.168.2.21 GET Hello " +"from webapplib!\n" +"Thread-2 (process_request) app2 __main__ jim 192.168.2.20 GET Request " +"processing started\n" +"Thread-3 (process_request) app1 __main__ jim 192.168.3.21 POST Request " +"processing started\n" +"Thread-2 (process_request) app2 webapplib jim 192.168.2.20 GET Hello " +"from webapplib!\n" +"Thread-3 (process_request) app1 webapplib jim 192.168.3.21 POST Hello " +"from webapplib!\n" +"Thread-4 (process_request) app2 __main__ fred 192.168.2.22 GET Request " +"processing started\n" +"Thread-5 (process_request) app1 __main__ jim 192.168.3.21 POST Request " +"processing started\n" +"Thread-4 (process_request) app2 webapplib fred 192.168.2.22 GET Hello " +"from webapplib!\n" +"Thread-6 (process_request) app1 __main__ jim 192.168.3.21 POST Request " +"processing started\n" +"~/logging-contextual-webapp$ grep app1 app1.log | wc -l\n" +"153\n" +"~/logging-contextual-webapp$ grep app2 app2.log | wc -l\n" +"147\n" +"~/logging-contextual-webapp$ grep app1 app.log | wc -l\n" +"153\n" +"~/logging-contextual-webapp$ grep app2 app.log | wc -l\n" +"147" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1250 +msgid "Imparting contextual information in handlers" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1252 +msgid "" +"Each :class:`~Handler` has its own chain of filters. If you want to add " +"contextual information to a :class:`LogRecord` without leaking it to other " +"handlers, you can use a filter that returns a new :class:`~LogRecord` " +"instead of modifying it in-place, as shown in the following script::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1257 +msgid "" +"import copy\n" +"import logging\n" +"\n" +"def filter(record: logging.LogRecord):\n" +" record = copy.copy(record)\n" +" record.user = 'jim'\n" +" return record\n" +"\n" +"if __name__ == '__main__':\n" +" logger = logging.getLogger()\n" +" logger.setLevel(logging.INFO)\n" +" handler = logging.StreamHandler()\n" +" formatter = logging.Formatter('%(message)s from %(user)-8s')\n" +" handler.setFormatter(formatter)\n" +" handler.addFilter(filter)\n" +" logger.addHandler(handler)\n" +"\n" +" logger.info('A log message')" +msgstr "" +"import copy\n" +"import logging\n" +"\n" +"def filter(record: logging.LogRecord):\n" +" record = copy.copy(record)\n" +" record.user = 'jim'\n" +" return record\n" +"\n" +"if __name__ == '__main__':\n" +" logger = logging.getLogger()\n" +" logger.setLevel(logging.INFO)\n" +" handler = logging.StreamHandler()\n" +" formatter = logging.Formatter('%(message)s from %(user)-8s')\n" +" handler.setFormatter(formatter)\n" +" handler.addFilter(filter)\n" +" logger.addHandler(handler)\n" +"\n" +" logger.info('A log message')" + +#: ../../howto/logging-cookbook.rst:1279 +msgid "Logging to a single file from multiple processes" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1281 +msgid "" +"Although logging is thread-safe, and logging to a single file from multiple " +"threads in a single process *is* supported, logging to a single file from " +"*multiple processes* is *not* supported, because there is no standard way to " +"serialize access to a single file across multiple processes in Python. If " +"you need to log to a single file from multiple processes, one way of doing " +"this is to have all the processes log to a :class:`~handlers.SocketHandler`, " +"and have a separate process which implements a socket server which reads " +"from the socket and logs to file. (If you prefer, you can dedicate one " +"thread in one of the existing processes to perform this " +"function.) :ref:`This section ` documents this approach in " +"more detail and includes a working socket receiver which can be used as a " +"starting point for you to adapt in your own applications." +msgstr "" + +#: ../../howto/logging-cookbook.rst:1294 +msgid "" +"You could also write your own handler which uses " +"the :class:`~multiprocessing.Lock` class from the :mod:`multiprocessing` " +"module to serialize access to the file from your processes. The " +"stdlib :class:`FileHandler` and subclasses do not make use " +"of :mod:`multiprocessing`." +msgstr "" + +#: ../../howto/logging-cookbook.rst:1301 +msgid "" +"Alternatively, you can use a ``Queue`` and a :class:`QueueHandler` to send " +"all logging events to one of the processes in your multi-process " +"application. The following example script demonstrates how you can do this; " +"in the example a separate listener process listens for events sent by other " +"processes and logs them according to its own logging configuration. Although " +"the example only demonstrates one way of doing it (for example, you may want " +"to use a listener thread rather than a separate listener process -- the " +"implementation would be analogous) it does allow for completely different " +"logging configurations for the listener and the other processes in your " +"application, and can be used as the basis for code meeting your own specific " +"requirements::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1312 +msgid "" +"# You'll need these imports in your own code\n" +"import logging\n" +"import logging.handlers\n" +"import multiprocessing\n" +"\n" +"# Next two import lines for this demo only\n" +"from random import choice, random\n" +"import time\n" +"\n" +"#\n" +"# Because you'll want to define the logging configurations for listener and " +"workers, the\n" +"# listener and worker process functions take a configurer parameter which is " +"a callable\n" +"# for configuring logging for that process. These functions are also passed " +"the queue,\n" +"# which they use for communication.\n" +"#\n" +"# In practice, you can configure the listener however you want, but note " +"that in this\n" +"# simple example, the listener does not apply level or filter logic to " +"received records.\n" +"# In practice, you would probably want to do this logic in the worker " +"processes, to avoid\n" +"# sending events which would be filtered out between processes.\n" +"#\n" +"# The size of the rotated files is made small so you can see the results " +"easily.\n" +"def listener_configurer():\n" +" root = logging.getLogger()\n" +" h = logging.handlers.RotatingFileHandler('mptest.log', 'a', 300, 10)\n" +" f = logging.Formatter('%(asctime)s %(processName)-10s %(name)s %" +"(levelname)-8s %(message)s')\n" +" h.setFormatter(f)\n" +" root.addHandler(h)\n" +"\n" +"# This is the listener process top-level loop: wait for logging events\n" +"# (LogRecords)on the queue and handle them, quit when you get a None for a\n" +"# LogRecord.\n" +"def listener_process(queue, configurer):\n" +" configurer()\n" +" while True:\n" +" try:\n" +" record = queue.get()\n" +" if record is None: # We send this as a sentinel to tell the " +"listener to quit.\n" +" break\n" +" logger = logging.getLogger(record.name)\n" +" logger.handle(record) # No level or filter logic applied - just " +"do it!\n" +" except Exception:\n" +" import sys, traceback\n" +" print('Whoops! Problem:', file=sys.stderr)\n" +" traceback.print_exc(file=sys.stderr)\n" +"\n" +"# Arrays used for random selections in this demo\n" +"\n" +"LEVELS = [logging.DEBUG, logging.INFO, logging.WARNING,\n" +" logging.ERROR, logging.CRITICAL]\n" +"\n" +"LOGGERS = ['a.b.c', 'd.e.f']\n" +"\n" +"MESSAGES = [\n" +" 'Random message #1',\n" +" 'Random message #2',\n" +" 'Random message #3',\n" +"]\n" +"\n" +"# The worker configuration is done at the start of the worker process run.\n" +"# Note that on Windows you can't rely on fork semantics, so each process\n" +"# will run the logging configuration code when it starts.\n" +"def worker_configurer(queue):\n" +" h = logging.handlers.QueueHandler(queue) # Just the one handler needed\n" +" root = logging.getLogger()\n" +" root.addHandler(h)\n" +" # send all messages, for demo; no other level or filter logic applied.\n" +" root.setLevel(logging.DEBUG)\n" +"\n" +"# This is the worker process top-level loop, which just logs ten events " +"with\n" +"# random intervening delays before terminating.\n" +"# The print messages are just so you know it's doing something!\n" +"def worker_process(queue, configurer):\n" +" configurer(queue)\n" +" name = multiprocessing.current_process().name\n" +" print('Worker started: %s' % name)\n" +" for i in range(10):\n" +" time.sleep(random())\n" +" logger = logging.getLogger(choice(LOGGERS))\n" +" level = choice(LEVELS)\n" +" message = choice(MESSAGES)\n" +" logger.log(level, message)\n" +" print('Worker finished: %s' % name)\n" +"\n" +"# Here's where the demo gets orchestrated. Create the queue, create and " +"start\n" +"# the listener, create ten workers and start them, wait for them to finish,\n" +"# then send a None to the queue to tell the listener to finish.\n" +"def main():\n" +" queue = multiprocessing.Queue(-1)\n" +" listener = multiprocessing.Process(target=listener_process,\n" +" args=(queue, listener_configurer))\n" +" listener.start()\n" +" workers = []\n" +" for i in range(10):\n" +" worker = multiprocessing.Process(target=worker_process,\n" +" args=(queue, worker_configurer))\n" +" workers.append(worker)\n" +" worker.start()\n" +" for w in workers:\n" +" w.join()\n" +" queue.put_nowait(None)\n" +" listener.join()\n" +"\n" +"if __name__ == '__main__':\n" +" main()" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1417 +msgid "" +"A variant of the above script keeps the logging in the main process, in a " +"separate thread::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1420 +msgid "" +"import logging\n" +"import logging.config\n" +"import logging.handlers\n" +"from multiprocessing import Process, Queue\n" +"import random\n" +"import threading\n" +"import time\n" +"\n" +"def logger_thread(q):\n" +" while True:\n" +" record = q.get()\n" +" if record is None:\n" +" break\n" +" logger = logging.getLogger(record.name)\n" +" logger.handle(record)\n" +"\n" +"\n" +"def worker_process(q):\n" +" qh = logging.handlers.QueueHandler(q)\n" +" root = logging.getLogger()\n" +" root.setLevel(logging.DEBUG)\n" +" root.addHandler(qh)\n" +" levels = [logging.DEBUG, logging.INFO, logging.WARNING, logging.ERROR,\n" +" logging.CRITICAL]\n" +" loggers = ['foo', 'foo.bar', 'foo.bar.baz',\n" +" 'spam', 'spam.ham', 'spam.ham.eggs']\n" +" for i in range(100):\n" +" lvl = random.choice(levels)\n" +" logger = logging.getLogger(random.choice(loggers))\n" +" logger.log(lvl, 'Message no. %d', i)\n" +"\n" +"if __name__ == '__main__':\n" +" q = Queue()\n" +" d = {\n" +" 'version': 1,\n" +" 'formatters': {\n" +" 'detailed': {\n" +" 'class': 'logging.Formatter',\n" +" 'format': '%(asctime)s %(name)-15s %(levelname)-8s %" +"(processName)-10s %(message)s'\n" +" }\n" +" },\n" +" 'handlers': {\n" +" 'console': {\n" +" 'class': 'logging.StreamHandler',\n" +" 'level': 'INFO',\n" +" },\n" +" 'file': {\n" +" 'class': 'logging.FileHandler',\n" +" 'filename': 'mplog.log',\n" +" 'mode': 'w',\n" +" 'formatter': 'detailed',\n" +" },\n" +" 'foofile': {\n" +" 'class': 'logging.FileHandler',\n" +" 'filename': 'mplog-foo.log',\n" +" 'mode': 'w',\n" +" 'formatter': 'detailed',\n" +" },\n" +" 'errors': {\n" +" 'class': 'logging.FileHandler',\n" +" 'filename': 'mplog-errors.log',\n" +" 'mode': 'w',\n" +" 'level': 'ERROR',\n" +" 'formatter': 'detailed',\n" +" },\n" +" },\n" +" 'loggers': {\n" +" 'foo': {\n" +" 'handlers': ['foofile']\n" +" }\n" +" },\n" +" 'root': {\n" +" 'level': 'DEBUG',\n" +" 'handlers': ['console', 'file', 'errors']\n" +" },\n" +" }\n" +" workers = []\n" +" for i in range(5):\n" +" wp = Process(target=worker_process, name='worker %d' % (i + 1), " +"args=(q,))\n" +" workers.append(wp)\n" +" wp.start()\n" +" logging.config.dictConfig(d)\n" +" lp = threading.Thread(target=logger_thread, args=(q,))\n" +" lp.start()\n" +" # At this point, the main process could do some useful work of its own\n" +" # Once it's done that, it can wait for the workers to terminate...\n" +" for wp in workers:\n" +" wp.join()\n" +" # And now tell the logging thread to finish up, too\n" +" q.put(None)\n" +" lp.join()" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1512 +msgid "" +"This variant shows how you can e.g. apply configuration for particular " +"loggers - e.g. the ``foo`` logger has a special handler which stores all " +"events in the ``foo`` subsystem in a file ``mplog-foo.log``. This will be " +"used by the logging machinery in the main process (even though the logging " +"events are generated in the worker processes) to direct the messages to the " +"appropriate destinations." +msgstr "" + +#: ../../howto/logging-cookbook.rst:1519 +msgid "Using concurrent.futures.ProcessPoolExecutor" +msgstr "使用 concurrent.futures.ProcessPoolExecutor" + +#: ../../howto/logging-cookbook.rst:1521 +msgid "" +"If you want to use :class:`concurrent.futures.ProcessPoolExecutor` to start " +"your worker processes, you need to create the queue slightly differently. " +"Instead of" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1525 +msgid "queue = multiprocessing.Queue(-1)" +msgstr "queue = multiprocessing.Queue(-1)" + +#: ../../howto/logging-cookbook.rst:1529 +msgid "you should use" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1531 +msgid "" +"queue = multiprocessing.Manager().Queue(-1) # also works with the examples " +"above" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1535 +msgid "and you can then replace the worker creation from this::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1537 +msgid "" +"workers = []\n" +"for i in range(10):\n" +" worker = multiprocessing.Process(target=worker_process,\n" +" args=(queue, worker_configurer))\n" +" workers.append(worker)\n" +" worker.start()\n" +"for w in workers:\n" +" w.join()" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1546 +msgid "to this (remembering to first import :mod:`concurrent.futures`)::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1548 +msgid "" +"with concurrent.futures.ProcessPoolExecutor(max_workers=10) as executor:\n" +" for i in range(10):\n" +" executor.submit(worker_process, queue, worker_configurer)" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1553 +msgid "Deploying Web applications using Gunicorn and uWSGI" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1555 +msgid "" +"When deploying Web applications using `Gunicorn `_ or " +"`uWSGI `_ (or similar), " +"multiple worker processes are created to handle client requests. In such " +"environments, avoid creating file-based handlers directly in your web " +"application. Instead, use a :class:`SocketHandler` to log from the web " +"application to a listener in a separate process. This can be set up using a " +"process management tool such as Supervisor - see `Running a logging socket " +"listener in production`_ for more details." +msgstr "" + +#: ../../howto/logging-cookbook.rst:1565 +msgid "Using file rotation" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1570 +msgid "" +"Sometimes you want to let a log file grow to a certain size, then open a new " +"file and log to that. You may want to keep a certain number of these files, " +"and when that many files have been created, rotate the files so that the " +"number of files and the size of the files both remain bounded. For this " +"usage pattern, the logging package provides a :class:`RotatingFileHandler`::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1576 +msgid "" +"import glob\n" +"import logging\n" +"import logging.handlers\n" +"\n" +"LOG_FILENAME = 'logging_rotatingfile_example.out'\n" +"\n" +"# Set up a specific logger with our desired output level\n" +"my_logger = logging.getLogger('MyLogger')\n" +"my_logger.setLevel(logging.DEBUG)\n" +"\n" +"# Add the log message handler to the logger\n" +"handler = logging.handlers.RotatingFileHandler(\n" +" LOG_FILENAME, maxBytes=20, backupCount=5)\n" +"\n" +"my_logger.addHandler(handler)\n" +"\n" +"# Log some messages\n" +"for i in range(20):\n" +" my_logger.debug('i = %d' % i)\n" +"\n" +"# See what files are created\n" +"logfiles = glob.glob('%s*' % LOG_FILENAME)\n" +"\n" +"for filename in logfiles:\n" +" print(filename)" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1602 +msgid "" +"The result should be 6 separate files, each with part of the log history for " +"the application:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1605 +msgid "" +"logging_rotatingfile_example.out\n" +"logging_rotatingfile_example.out.1\n" +"logging_rotatingfile_example.out.2\n" +"logging_rotatingfile_example.out.3\n" +"logging_rotatingfile_example.out.4\n" +"logging_rotatingfile_example.out.5" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1614 +msgid "" +"The most current file is always :file:`logging_rotatingfile_example.out`, " +"and each time it reaches the size limit it is renamed with the suffix " +"``.1``. Each of the existing backup files is renamed to increment the suffix " +"(``.1`` becomes ``.2``, etc.) and the ``.6`` file is erased." +msgstr "" + +#: ../../howto/logging-cookbook.rst:1619 +msgid "" +"Obviously this example sets the log length much too small as an extreme " +"example. You would want to set *maxBytes* to an appropriate value." +msgstr "" + +#: ../../howto/logging-cookbook.rst:1627 +msgid "Use of alternative formatting styles" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1629 +msgid "" +"When logging was added to the Python standard library, the only way of " +"formatting messages with variable content was to use the %-formatting " +"method. Since then, Python has gained two new formatting " +"approaches: :class:`string.Template` (added in Python 2.4) " +"and :meth:`str.format` (added in Python 2.6)." +msgstr "" + +#: ../../howto/logging-cookbook.rst:1635 +msgid "" +"Logging (as of 3.2) provides improved support for these two additional " +"formatting styles. The :class:`Formatter` class been enhanced to take an " +"additional, optional keyword parameter named ``style``. This defaults to " +"``'%'``, but other possible values are ``'{'`` and ``'$'``, which correspond " +"to the other two formatting styles. Backwards compatibility is maintained by " +"default (as you would expect), but by explicitly specifying a style " +"parameter, you get the ability to specify format strings which work " +"with :meth:`str.format` or :class:`string.Template`. Here's an example " +"console session to show the possibilities:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1645 +msgid "" +">>> import logging\n" +">>> root = logging.getLogger()\n" +">>> root.setLevel(logging.DEBUG)\n" +">>> handler = logging.StreamHandler()\n" +">>> bf = logging.Formatter('{asctime} {name} {levelname:8s} {message}',\n" +"... style='{')\n" +">>> handler.setFormatter(bf)\n" +">>> root.addHandler(handler)\n" +">>> logger = logging.getLogger('foo.bar')\n" +">>> logger.debug('This is a DEBUG message')\n" +"2010-10-28 15:11:55,341 foo.bar DEBUG This is a DEBUG message\n" +">>> logger.critical('This is a CRITICAL message')\n" +"2010-10-28 15:12:11,526 foo.bar CRITICAL This is a CRITICAL message\n" +">>> df = logging.Formatter('$asctime $name ${levelname} $message',\n" +"... style='$')\n" +">>> handler.setFormatter(df)\n" +">>> logger.debug('This is a DEBUG message')\n" +"2010-10-28 15:13:06,924 foo.bar DEBUG This is a DEBUG message\n" +">>> logger.critical('This is a CRITICAL message')\n" +"2010-10-28 15:13:11,494 foo.bar CRITICAL This is a CRITICAL message\n" +">>>" +msgstr "" +">>> import logging\n" +">>> root = logging.getLogger()\n" +">>> root.setLevel(logging.DEBUG)\n" +">>> handler = logging.StreamHandler()\n" +">>> bf = logging.Formatter('{asctime} {name} {levelname:8s} {message}',\n" +"... style='{')\n" +">>> handler.setFormatter(bf)\n" +">>> root.addHandler(handler)\n" +">>> logger = logging.getLogger('foo.bar')\n" +">>> logger.debug('This is a DEBUG message')\n" +"2010-10-28 15:11:55,341 foo.bar DEBUG This is a DEBUG message\n" +">>> logger.critical('This is a CRITICAL message')\n" +"2010-10-28 15:12:11,526 foo.bar CRITICAL This is a CRITICAL message\n" +">>> df = logging.Formatter('$asctime $name ${levelname} $message',\n" +"... style='$')\n" +">>> handler.setFormatter(df)\n" +">>> logger.debug('This is a DEBUG message')\n" +"2010-10-28 15:13:06,924 foo.bar DEBUG This is a DEBUG message\n" +">>> logger.critical('This is a CRITICAL message')\n" +"2010-10-28 15:13:11,494 foo.bar CRITICAL This is a CRITICAL message\n" +">>>" + +#: ../../howto/logging-cookbook.rst:1669 +msgid "" +"Note that the formatting of logging messages for final output to logs is " +"completely independent of how an individual logging message is constructed. " +"That can still use %-formatting, as shown here::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1673 +msgid "" +">>> logger.error('This is an%s %s %s', 'other,', 'ERROR,', 'message')\n" +"2010-10-28 15:19:29,833 foo.bar ERROR This is another, ERROR, message\n" +">>>" +msgstr "" +">>> logger.error('This is an%s %s %s', 'other,', 'ERROR,', 'message')\n" +"2010-10-28 15:19:29,833 foo.bar ERROR This is another, ERROR, message\n" +">>>" + +#: ../../howto/logging-cookbook.rst:1677 +msgid "" +"Logging calls (``logger.debug()``, ``logger.info()`` etc.) only take " +"positional parameters for the actual logging message itself, with keyword " +"parameters used only for determining options for how to handle the actual " +"logging call (e.g. the ``exc_info`` keyword parameter to indicate that " +"traceback information should be logged, or the ``extra`` keyword parameter " +"to indicate additional contextual information to be added to the log). So " +"you cannot directly make logging calls using :meth:`str.format` " +"or :class:`string.Template` syntax, because internally the logging package " +"uses %-formatting to merge the format string and the variable arguments. " +"There would be no changing this while preserving backward compatibility, " +"since all logging calls which are out there in existing code will be using %-" +"format strings." +msgstr "" + +#: ../../howto/logging-cookbook.rst:1690 +msgid "" +"There is, however, a way that you can use {}- and $- formatting to construct " +"your individual log messages. Recall that for a message you can use an " +"arbitrary object as a message format string, and that the logging package " +"will call ``str()`` on that object to get the actual format string. Consider " +"the following two classes::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1696 ../../howto/logging-cookbook.rst:2784 +msgid "" +"class BraceMessage:\n" +" def __init__(self, fmt, /, *args, **kwargs):\n" +" self.fmt = fmt\n" +" self.args = args\n" +" self.kwargs = kwargs\n" +"\n" +" def __str__(self):\n" +" return self.fmt.format(*self.args, **self.kwargs)\n" +"\n" +"class DollarMessage:\n" +" def __init__(self, fmt, /, **kwargs):\n" +" self.fmt = fmt\n" +" self.kwargs = kwargs\n" +"\n" +" def __str__(self):\n" +" from string import Template\n" +" return Template(self.fmt).substitute(**self.kwargs)" +msgstr "" +"class BraceMessage:\n" +" def __init__(self, fmt, /, *args, **kwargs):\n" +" self.fmt = fmt\n" +" self.args = args\n" +" self.kwargs = kwargs\n" +"\n" +" def __str__(self):\n" +" return self.fmt.format(*self.args, **self.kwargs)\n" +"\n" +"class DollarMessage:\n" +" def __init__(self, fmt, /, **kwargs):\n" +" self.fmt = fmt\n" +" self.kwargs = kwargs\n" +"\n" +" def __str__(self):\n" +" from string import Template\n" +" return Template(self.fmt).substitute(**self.kwargs)" + +#: ../../howto/logging-cookbook.rst:1714 +msgid "" +"Either of these can be used in place of a format string, to allow {}- or $-" +"formatting to be used to build the actual \"message\" part which appears in " +"the formatted log output in place of \"%(message)s\" or \"{message}\" or " +"\"$message\". It's a little unwieldy to use the class names whenever you " +"want to log something, but it's quite palatable if you use an alias such as " +"__ (double underscore --- not to be confused with _, the single underscore " +"used as a synonym/alias for :func:`gettext.gettext` or its brethren)." +msgstr "" + +#: ../../howto/logging-cookbook.rst:1722 +msgid "" +"The above classes are not included in Python, though they're easy enough to " +"copy and paste into your own code. They can be used as follows (assuming " +"that they're declared in a module called ``wherever``):" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1726 +msgid "" +">>> from wherever import BraceMessage as __\n" +">>> print(__('Message with {0} {name}', 2, name='placeholders'))\n" +"Message with 2 placeholders\n" +">>> class Point: pass\n" +"...\n" +">>> p = Point()\n" +">>> p.x = 0.5\n" +">>> p.y = 0.5\n" +">>> print(__('Message with coordinates: ({point.x:.2f}, {point.y:.2f})',\n" +"... point=p))\n" +"Message with coordinates: (0.50, 0.50)\n" +">>> from wherever import DollarMessage as __\n" +">>> print(__('Message with $num $what', num=2, what='placeholders'))\n" +"Message with 2 placeholders\n" +">>>" +msgstr "" +">>> from wherever import BraceMessage as __\n" +">>> print(__('Message with {0} {name}', 2, name='placeholders'))\n" +"Message with 2 placeholders\n" +">>> class Point: pass\n" +"...\n" +">>> p = Point()\n" +">>> p.x = 0.5\n" +">>> p.y = 0.5\n" +">>> print(__('Message with coordinates: ({point.x:.2f}, {point.y:.2f})',\n" +"... point=p))\n" +"Message with coordinates: (0.50, 0.50)\n" +">>> from wherever import DollarMessage as __\n" +">>> print(__('Message with $num $what', num=2, what='placeholders'))\n" +"Message with 2 placeholders\n" +">>>" + +#: ../../howto/logging-cookbook.rst:1744 +msgid "" +"While the above examples use ``print()`` to show how the formatting works, " +"you would of course use ``logger.debug()`` or similar to actually log using " +"this approach." +msgstr "" + +#: ../../howto/logging-cookbook.rst:1748 +msgid "" +"One thing to note is that you pay no significant performance penalty with " +"this approach: the actual formatting happens not when you make the logging " +"call, but when (and if) the logged message is actually about to be output to " +"a log by a handler. So the only slightly unusual thing which might trip you " +"up is that the parentheses go around the format string and the arguments, " +"not just the format string. That's because the __ notation is just syntax " +"sugar for a constructor call to one of the :samp:`{XXX}Message` classes." +msgstr "" + +#: ../../howto/logging-cookbook.rst:1756 +msgid "" +"If you prefer, you can use a :class:`LoggerAdapter` to achieve a similar " +"effect to the above, as in the following example::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1759 +msgid "" +"import logging\n" +"\n" +"class Message:\n" +" def __init__(self, fmt, args):\n" +" self.fmt = fmt\n" +" self.args = args\n" +"\n" +" def __str__(self):\n" +" return self.fmt.format(*self.args)\n" +"\n" +"class StyleAdapter(logging.LoggerAdapter):\n" +" def log(self, level, msg, /, *args, stacklevel=1, **kwargs):\n" +" if self.isEnabledFor(level):\n" +" msg, kwargs = self.process(msg, kwargs)\n" +" self.logger.log(level, Message(msg, args), **kwargs,\n" +" stacklevel=stacklevel+1)\n" +"\n" +"logger = StyleAdapter(logging.getLogger(__name__))\n" +"\n" +"def main():\n" +" logger.debug('Hello, {}', 'world!')\n" +"\n" +"if __name__ == '__main__':\n" +" logging.basicConfig(level=logging.DEBUG)\n" +" main()" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1785 +msgid "" +"The above script should log the message ``Hello, world!`` when run with " +"Python 3.8 or later." +msgstr "" + +#: ../../howto/logging-cookbook.rst:1794 +msgid "Customizing ``LogRecord``" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1796 +msgid "" +"Every logging event is represented by a :class:`LogRecord` instance. When an " +"event is logged and not filtered out by a logger's level, " +"a :class:`LogRecord` is created, populated with information about the event " +"and then passed to the handlers for that logger (and its ancestors, up to " +"and including the logger where further propagation up the hierarchy is " +"disabled). Before Python 3.2, there were only two places where this creation " +"was done:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1803 +msgid "" +":meth:`Logger.makeRecord`, which is called in the normal process of logging " +"an event. This invoked :class:`LogRecord` directly to create an instance." +msgstr "" + +#: ../../howto/logging-cookbook.rst:1806 +msgid "" +":func:`makeLogRecord`, which is called with a dictionary containing " +"attributes to be added to the LogRecord. This is typically invoked when a " +"suitable dictionary has been received over the network (e.g. in pickle form " +"via a :class:`~handlers.SocketHandler`, or in JSON form via " +"an :class:`~handlers.HTTPHandler`)." +msgstr "" + +#: ../../howto/logging-cookbook.rst:1812 +msgid "" +"This has usually meant that if you need to do anything special with " +"a :class:`LogRecord`, you've had to do one of the following." +msgstr "" + +#: ../../howto/logging-cookbook.rst:1815 +msgid "" +"Create your own :class:`Logger` subclass, which " +"overrides :meth:`Logger.makeRecord`, and set it " +"using :func:`~logging.setLoggerClass` before any loggers that you care about " +"are instantiated." +msgstr "" + +#: ../../howto/logging-cookbook.rst:1818 +msgid "" +"Add a :class:`Filter` to a logger or handler, which does the necessary " +"special manipulation you need when its :meth:`~Filter.filter` method is " +"called." +msgstr "" + +#: ../../howto/logging-cookbook.rst:1822 +msgid "" +"The first approach would be a little unwieldy in the scenario where (say) " +"several different libraries wanted to do different things. Each would " +"attempt to set its own :class:`Logger` subclass, and the one which did this " +"last would win." +msgstr "" + +#: ../../howto/logging-cookbook.rst:1827 +msgid "" +"The second approach works reasonably well for many cases, but does not allow " +"you to e.g. use a specialized subclass of :class:`LogRecord`. Library " +"developers can set a suitable filter on their loggers, but they would have " +"to remember to do this every time they introduced a new logger (which they " +"would do simply by adding new packages or modules and doing ::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1833 +msgid "logger = logging.getLogger(__name__)" +msgstr "logger = logging.getLogger(__name__)" + +#: ../../howto/logging-cookbook.rst:1835 +msgid "" +"at module level). It's probably one too many things to think about. " +"Developers could also add the filter to a :class:`~logging.NullHandler` " +"attached to their top-level logger, but this would not be invoked if an " +"application developer attached a handler to a lower-level library logger --- " +"so output from that handler would not reflect the intentions of the library " +"developer." +msgstr "" + +#: ../../howto/logging-cookbook.rst:1841 +msgid "" +"In Python 3.2 and later, :class:`~logging.LogRecord` creation is done " +"through a factory, which you can specify. The factory is just a callable you " +"can set with :func:`~logging.setLogRecordFactory`, and interrogate " +"with :func:`~logging.getLogRecordFactory`. The factory is invoked with the " +"same signature as the :class:`~logging.LogRecord` constructor, " +"as :class:`LogRecord` is the default setting for the factory." +msgstr "" + +#: ../../howto/logging-cookbook.rst:1848 +msgid "" +"This approach allows a custom factory to control all aspects of LogRecord " +"creation. For example, you could return a subclass, or just add some " +"additional attributes to the record once created, using a pattern similar to " +"this::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1852 +msgid "" +"old_factory = logging.getLogRecordFactory()\n" +"\n" +"def record_factory(*args, **kwargs):\n" +" record = old_factory(*args, **kwargs)\n" +" record.custom_attribute = 0xdecafbad\n" +" return record\n" +"\n" +"logging.setLogRecordFactory(record_factory)" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1861 +msgid "" +"This pattern allows different libraries to chain factories together, and as " +"long as they don't overwrite each other's attributes or unintentionally " +"overwrite the attributes provided as standard, there should be no surprises. " +"However, it should be borne in mind that each link in the chain adds run-" +"time overhead to all logging operations, and the technique should only be " +"used when the use of a :class:`Filter` does not provide the desired result." +msgstr "" + +#: ../../howto/logging-cookbook.rst:1873 +msgid "Subclassing QueueHandler and QueueListener- a ZeroMQ example" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1876 ../../howto/logging-cookbook.rst:2009 +msgid "Subclass ``QueueHandler``" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1878 +msgid "" +"You can use a :class:`QueueHandler` subclass to send messages to other kinds " +"of queues, for example a ZeroMQ 'publish' socket. In the example below,the " +"socket is created separately and passed to the handler (as its 'queue')::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1882 +msgid "" +"import zmq # using pyzmq, the Python binding for ZeroMQ\n" +"import json # for serializing records portably\n" +"\n" +"ctx = zmq.Context()\n" +"sock = zmq.Socket(ctx, zmq.PUB) # or zmq.PUSH, or other suitable value\n" +"sock.bind('tcp://*:5556') # or wherever\n" +"\n" +"class ZeroMQSocketHandler(QueueHandler):\n" +" def enqueue(self, record):\n" +" self.queue.send_json(record.__dict__)\n" +"\n" +"\n" +"handler = ZeroMQSocketHandler(sock)" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1897 +msgid "" +"Of course there are other ways of organizing this, for example passing in " +"the data needed by the handler to create the socket::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1900 +msgid "" +"class ZeroMQSocketHandler(QueueHandler):\n" +" def __init__(self, uri, socktype=zmq.PUB, ctx=None):\n" +" self.ctx = ctx or zmq.Context()\n" +" socket = zmq.Socket(self.ctx, socktype)\n" +" socket.bind(uri)\n" +" super().__init__(socket)\n" +"\n" +" def enqueue(self, record):\n" +" self.queue.send_json(record.__dict__)\n" +"\n" +" def close(self):\n" +" self.queue.close()" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1915 ../../howto/logging-cookbook.rst:1945 +msgid "Subclass ``QueueListener``" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1917 +msgid "" +"You can also subclass :class:`QueueListener` to get messages from other " +"kinds of queues, for example a ZeroMQ 'subscribe' socket. Here's an example::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1920 +msgid "" +"class ZeroMQSocketListener(QueueListener):\n" +" def __init__(self, uri, /, *handlers, **kwargs):\n" +" self.ctx = kwargs.get('ctx') or zmq.Context()\n" +" socket = zmq.Socket(self.ctx, zmq.SUB)\n" +" socket.setsockopt_string(zmq.SUBSCRIBE, '') # subscribe to " +"everything\n" +" socket.connect(uri)\n" +" super().__init__(socket, *handlers, **kwargs)\n" +"\n" +" def dequeue(self):\n" +" msg = self.queue.recv_json()\n" +" return logging.makeLogRecord(msg)" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1935 +msgid "Subclassing QueueHandler and QueueListener- a ``pynng`` example" +msgstr "" + +#: ../../howto/logging-cookbook.rst:1937 +msgid "" +"In a similar way to the above section, we can implement a listener and " +"handler using :pypi:`pynng`, which is a Python binding to `NNG `_, billed as a spiritual successor to ZeroMQ. The " +"following snippets illustrate -- you can test them in an environment which " +"has ``pynng`` installed. Just for variety, we present the listener first." +msgstr "" + +#: ../../howto/logging-cookbook.rst:1947 +msgid "" +"# listener.py\n" +"import json\n" +"import logging\n" +"import logging.handlers\n" +"\n" +"import pynng\n" +"\n" +"DEFAULT_ADDR = \"tcp://localhost:13232\"\n" +"\n" +"interrupted = False\n" +"\n" +"class NNGSocketListener(logging.handlers.QueueListener):\n" +"\n" +" def __init__(self, uri, /, *handlers, **kwargs):\n" +" # Have a timeout for interruptability, and open a\n" +" # subscriber socket\n" +" socket = pynng.Sub0(listen=uri, recv_timeout=500)\n" +" # The b'' subscription matches all topics\n" +" topics = kwargs.pop('topics', None) or b''\n" +" socket.subscribe(topics)\n" +" # We treat the socket as a queue\n" +" super().__init__(socket, *handlers, **kwargs)\n" +"\n" +" def dequeue(self, block):\n" +" data = None\n" +" # Keep looping while not interrupted and no data received over the\n" +" # socket\n" +" while not interrupted:\n" +" try:\n" +" data = self.queue.recv(block=block)\n" +" break\n" +" except pynng.Timeout:\n" +" pass\n" +" except pynng.Closed: # sometimes happens when you hit Ctrl-C\n" +" break\n" +" if data is None:\n" +" return None\n" +" # Get the logging event sent from a publisher\n" +" event = json.loads(data.decode('utf-8'))\n" +" return logging.makeLogRecord(event)\n" +"\n" +" def enqueue_sentinel(self):\n" +" # Not used in this implementation, as the socket isn't really a\n" +" # queue\n" +" pass\n" +"\n" +"logging.getLogger('pynng').propagate = False\n" +"listener = NNGSocketListener(DEFAULT_ADDR, logging.StreamHandler(), " +"topics=b'')\n" +"listener.start()\n" +"print('Press Ctrl-C to stop.')\n" +"try:\n" +" while True:\n" +" pass\n" +"except KeyboardInterrupt:\n" +" interrupted = True\n" +"finally:\n" +" listener.stop()" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2013 +msgid "" +"# sender.py\n" +"import json\n" +"import logging\n" +"import logging.handlers\n" +"import time\n" +"import random\n" +"\n" +"import pynng\n" +"\n" +"DEFAULT_ADDR = \"tcp://localhost:13232\"\n" +"\n" +"class NNGSocketHandler(logging.handlers.QueueHandler):\n" +"\n" +" def __init__(self, uri):\n" +" socket = pynng.Pub0(dial=uri, send_timeout=500)\n" +" super().__init__(socket)\n" +"\n" +" def enqueue(self, record):\n" +" # Send the record as UTF-8 encoded JSON\n" +" d = dict(record.__dict__)\n" +" data = json.dumps(d)\n" +" self.queue.send(data.encode('utf-8'))\n" +"\n" +" def close(self):\n" +" self.queue.close()\n" +"\n" +"logging.getLogger('pynng').propagate = False\n" +"handler = NNGSocketHandler(DEFAULT_ADDR)\n" +"# Make sure the process ID is in the output\n" +"logging.basicConfig(level=logging.DEBUG,\n" +" handlers=[logging.StreamHandler(), handler],\n" +" format='%(levelname)-8s %(name)10s %(process)6s %" +"(message)s')\n" +"levels = (logging.DEBUG, logging.INFO, logging.WARNING, logging.ERROR,\n" +" logging.CRITICAL)\n" +"logger_names = ('myapp', 'myapp.lib1', 'myapp.lib2')\n" +"msgno = 1\n" +"while True:\n" +" # Just randomly select some loggers and levels and log away\n" +" level = random.choice(levels)\n" +" logger = logging.getLogger(random.choice(logger_names))\n" +" logger.log(level, 'Message no. %5d' % msgno)\n" +" msgno += 1\n" +" delay = random.random() * 2 + 0.5\n" +" time.sleep(delay)" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2060 +msgid "" +"You can run the above two snippets in separate command shells. If we run the " +"listener in one shell and run the sender in two separate shells, we should " +"see something like the following. In the first sender shell:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2064 +msgid "" +"$ python sender.py\n" +"DEBUG myapp 613 Message no. 1\n" +"WARNING myapp.lib2 613 Message no. 2\n" +"CRITICAL myapp.lib2 613 Message no. 3\n" +"WARNING myapp.lib2 613 Message no. 4\n" +"CRITICAL myapp.lib1 613 Message no. 5\n" +"DEBUG myapp 613 Message no. 6\n" +"CRITICAL myapp.lib1 613 Message no. 7\n" +"INFO myapp.lib1 613 Message no. 8\n" +"(and so on)" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2077 +msgid "In the second sender shell:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2079 +msgid "" +"$ python sender.py\n" +"INFO myapp.lib2 657 Message no. 1\n" +"CRITICAL myapp.lib2 657 Message no. 2\n" +"CRITICAL myapp 657 Message no. 3\n" +"CRITICAL myapp.lib1 657 Message no. 4\n" +"INFO myapp.lib1 657 Message no. 5\n" +"WARNING myapp.lib2 657 Message no. 6\n" +"CRITICAL myapp 657 Message no. 7\n" +"DEBUG myapp.lib1 657 Message no. 8\n" +"(and so on)" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2092 +msgid "In the listener shell:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2094 +msgid "" +"$ python listener.py\n" +"Press Ctrl-C to stop.\n" +"DEBUG myapp 613 Message no. 1\n" +"WARNING myapp.lib2 613 Message no. 2\n" +"INFO myapp.lib2 657 Message no. 1\n" +"CRITICAL myapp.lib2 613 Message no. 3\n" +"CRITICAL myapp.lib2 657 Message no. 2\n" +"CRITICAL myapp 657 Message no. 3\n" +"WARNING myapp.lib2 613 Message no. 4\n" +"CRITICAL myapp.lib1 613 Message no. 5\n" +"CRITICAL myapp.lib1 657 Message no. 4\n" +"INFO myapp.lib1 657 Message no. 5\n" +"DEBUG myapp 613 Message no. 6\n" +"WARNING myapp.lib2 657 Message no. 6\n" +"CRITICAL myapp 657 Message no. 7\n" +"CRITICAL myapp.lib1 613 Message no. 7\n" +"INFO myapp.lib1 613 Message no. 8\n" +"DEBUG myapp.lib1 657 Message no. 8\n" +"(and so on)" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2116 +msgid "" +"As you can see, the logging from the two sender processes is interleaved in " +"the listener's output." +msgstr "" + +#: ../../howto/logging-cookbook.rst:2121 +msgid "An example dictionary-based configuration" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2123 +msgid "" +"Below is an example of a logging configuration dictionary - it's taken from " +"the `documentation on the Django project `_. This dictionary is passed " +"to :func:`~config.dictConfig` to put the configuration into effect::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2127 +msgid "" +"LOGGING = {\n" +" 'version': 1,\n" +" 'disable_existing_loggers': False,\n" +" 'formatters': {\n" +" 'verbose': {\n" +" 'format': '{levelname} {asctime} {module} {process:d} {thread:d} " +"{message}',\n" +" 'style': '{',\n" +" },\n" +" 'simple': {\n" +" 'format': '{levelname} {message}',\n" +" 'style': '{',\n" +" },\n" +" },\n" +" 'filters': {\n" +" 'special': {\n" +" '()': 'project.logging.SpecialFilter',\n" +" 'foo': 'bar',\n" +" },\n" +" },\n" +" 'handlers': {\n" +" 'console': {\n" +" 'level': 'INFO',\n" +" 'class': 'logging.StreamHandler',\n" +" 'formatter': 'simple',\n" +" },\n" +" 'mail_admins': {\n" +" 'level': 'ERROR',\n" +" 'class': 'django.utils.log.AdminEmailHandler',\n" +" 'filters': ['special']\n" +" }\n" +" },\n" +" 'loggers': {\n" +" 'django': {\n" +" 'handlers': ['console'],\n" +" 'propagate': True,\n" +" },\n" +" 'django.request': {\n" +" 'handlers': ['mail_admins'],\n" +" 'level': 'ERROR',\n" +" 'propagate': False,\n" +" },\n" +" 'myproject.custom': {\n" +" 'handlers': ['console', 'mail_admins'],\n" +" 'level': 'INFO',\n" +" 'filters': ['special']\n" +" }\n" +" }\n" +"}" +msgstr "" +"LOGGING = {\n" +" 'version': 1,\n" +" 'disable_existing_loggers': False,\n" +" 'formatters': {\n" +" 'verbose': {\n" +" 'format': '{levelname} {asctime} {module} {process:d} {thread:d} " +"{message}',\n" +" 'style': '{',\n" +" },\n" +" 'simple': {\n" +" 'format': '{levelname} {message}',\n" +" 'style': '{',\n" +" },\n" +" },\n" +" 'filters': {\n" +" 'special': {\n" +" '()': 'project.logging.SpecialFilter',\n" +" 'foo': 'bar',\n" +" },\n" +" },\n" +" 'handlers': {\n" +" 'console': {\n" +" 'level': 'INFO',\n" +" 'class': 'logging.StreamHandler',\n" +" 'formatter': 'simple',\n" +" },\n" +" 'mail_admins': {\n" +" 'level': 'ERROR',\n" +" 'class': 'django.utils.log.AdminEmailHandler',\n" +" 'filters': ['special']\n" +" }\n" +" },\n" +" 'loggers': {\n" +" 'django': {\n" +" 'handlers': ['console'],\n" +" 'propagate': True,\n" +" },\n" +" 'django.request': {\n" +" 'handlers': ['mail_admins'],\n" +" 'level': 'ERROR',\n" +" 'propagate': False,\n" +" },\n" +" 'myproject.custom': {\n" +" 'handlers': ['console', 'mail_admins'],\n" +" 'level': 'INFO',\n" +" 'filters': ['special']\n" +" }\n" +" }\n" +"}" + +#: ../../howto/logging-cookbook.rst:2176 +msgid "" +"For more information about this configuration, you can see the `relevant " +"section `_ of the Django documentation." +msgstr "" + +#: ../../howto/logging-cookbook.rst:2183 +msgid "Using a rotator and namer to customize log rotation processing" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2185 +msgid "" +"An example of how you can define a namer and rotator is given in the " +"following runnable script, which shows gzip compression of the log file::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2188 +msgid "" +"import gzip\n" +"import logging\n" +"import logging.handlers\n" +"import os\n" +"import shutil\n" +"\n" +"def namer(name):\n" +" return name + \".gz\"\n" +"\n" +"def rotator(source, dest):\n" +" with open(source, 'rb') as f_in:\n" +" with gzip.open(dest, 'wb') as f_out:\n" +" shutil.copyfileobj(f_in, f_out)\n" +" os.remove(source)\n" +"\n" +"\n" +"rh = logging.handlers.RotatingFileHandler('rotated.log', maxBytes=128, " +"backupCount=5)\n" +"rh.rotator = rotator\n" +"rh.namer = namer\n" +"\n" +"root = logging.getLogger()\n" +"root.setLevel(logging.INFO)\n" +"root.addHandler(rh)\n" +"f = logging.Formatter('%(asctime)s %(message)s')\n" +"rh.setFormatter(f)\n" +"for i in range(1000):\n" +" root.info(f'Message no. {i + 1}')" +msgstr "" +"import gzip\n" +"import logging\n" +"import logging.handlers\n" +"import os\n" +"import shutil\n" +"\n" +"def namer(name):\n" +" return name + \".gz\"\n" +"\n" +"def rotator(source, dest):\n" +" with open(source, 'rb') as f_in:\n" +" with gzip.open(dest, 'wb') as f_out:\n" +" shutil.copyfileobj(f_in, f_out)\n" +" os.remove(source)\n" +"\n" +"\n" +"rh = logging.handlers.RotatingFileHandler('rotated.log', maxBytes=128, " +"backupCount=5)\n" +"rh.rotator = rotator\n" +"rh.namer = namer\n" +"\n" +"root = logging.getLogger()\n" +"root.setLevel(logging.INFO)\n" +"root.addHandler(rh)\n" +"f = logging.Formatter('%(asctime)s %(message)s')\n" +"rh.setFormatter(f)\n" +"for i in range(1000):\n" +" root.info(f'Message no. {i + 1}')" + +#: ../../howto/logging-cookbook.rst:2216 +msgid "" +"After running this, you will see six new files, five of which are compressed:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2218 +msgid "" +"$ ls rotated.log*\n" +"rotated.log rotated.log.2.gz rotated.log.4.gz\n" +"rotated.log.1.gz rotated.log.3.gz rotated.log.5.gz\n" +"$ zcat rotated.log.1.gz\n" +"2023-01-20 02:28:17,767 Message no. 996\n" +"2023-01-20 02:28:17,767 Message no. 997\n" +"2023-01-20 02:28:17,767 Message no. 998" +msgstr "" +"$ ls rotated.log*\n" +"rotated.log rotated.log.2.gz rotated.log.4.gz\n" +"rotated.log.1.gz rotated.log.3.gz rotated.log.5.gz\n" +"$ zcat rotated.log.1.gz\n" +"2023-01-20 02:28:17,767 Message no. 996\n" +"2023-01-20 02:28:17,767 Message no. 997\n" +"2023-01-20 02:28:17,767 Message no. 998" + +#: ../../howto/logging-cookbook.rst:2229 +msgid "A more elaborate multiprocessing example" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2231 +msgid "" +"The following working example shows how logging can be used with " +"multiprocessing using configuration files. The configurations are fairly " +"simple, but serve to illustrate how more complex ones could be implemented " +"in a real multiprocessing scenario." +msgstr "" + +#: ../../howto/logging-cookbook.rst:2236 +msgid "" +"In the example, the main process spawns a listener process and some worker " +"processes. Each of the main process, the listener and the workers have three " +"separate configurations (the workers all share the same configuration). We " +"can see logging in the main process, how the workers log to a QueueHandler " +"and how the listener implements a QueueListener and a more complex logging " +"configuration, and arranges to dispatch events received via the queue to the " +"handlers specified in the configuration. Note that these configurations are " +"purely illustrative, but you should be able to adapt this example to your " +"own scenario." +msgstr "" + +#: ../../howto/logging-cookbook.rst:2246 +msgid "" +"Here's the script - the docstrings and the comments hopefully explain how it " +"works::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2249 +msgid "" +"import logging\n" +"import logging.config\n" +"import logging.handlers\n" +"from multiprocessing import Process, Queue, Event, current_process\n" +"import os\n" +"import random\n" +"import time\n" +"\n" +"class MyHandler:\n" +" \"\"\"\n" +" A simple handler for logging events. It runs in the listener process " +"and\n" +" dispatches events to loggers based on the name in the received record,\n" +" which then get dispatched, by the logging system, to the handlers\n" +" configured for those loggers.\n" +" \"\"\"\n" +"\n" +" def handle(self, record):\n" +" if record.name == \"root\":\n" +" logger = logging.getLogger()\n" +" else:\n" +" logger = logging.getLogger(record.name)\n" +"\n" +" if logger.isEnabledFor(record.levelno):\n" +" # The process name is transformed just to show that it's the " +"listener\n" +" # doing the logging to files and console\n" +" record.processName = '%s (for %s)' % (current_process().name, " +"record.processName)\n" +" logger.handle(record)\n" +"\n" +"def listener_process(q, stop_event, config):\n" +" \"\"\"\n" +" This could be done in the main process, but is just done in a separate\n" +" process for illustrative purposes.\n" +"\n" +" This initialises logging according to the specified configuration,\n" +" starts the listener and waits for the main process to signal completion\n" +" via the event. The listener is then stopped, and the process exits.\n" +" \"\"\"\n" +" logging.config.dictConfig(config)\n" +" listener = logging.handlers.QueueListener(q, MyHandler())\n" +" listener.start()\n" +" if os.name == 'posix':\n" +" # On POSIX, the setup logger will have been configured in the\n" +" # parent process, but should have been disabled following the\n" +" # dictConfig call.\n" +" # On Windows, since fork isn't used, the setup logger won't\n" +" # exist in the child, so it would be created and the message\n" +" # would appear - hence the \"if posix\" clause.\n" +" logger = logging.getLogger('setup')\n" +" logger.critical('Should not appear, because of disabled " +"logger ...')\n" +" stop_event.wait()\n" +" listener.stop()\n" +"\n" +"def worker_process(config):\n" +" \"\"\"\n" +" A number of these are spawned for the purpose of illustration. In\n" +" practice, they could be a heterogeneous bunch of processes rather than\n" +" ones which are identical to each other.\n" +"\n" +" This initialises logging according to the specified configuration,\n" +" and logs a hundred messages with random levels to randomly selected\n" +" loggers.\n" +"\n" +" A small sleep is added to allow other processes a chance to run. This\n" +" is not strictly needed, but it mixes the output from the different\n" +" processes a bit more than if it's left out.\n" +" \"\"\"\n" +" logging.config.dictConfig(config)\n" +" levels = [logging.DEBUG, logging.INFO, logging.WARNING, logging.ERROR,\n" +" logging.CRITICAL]\n" +" loggers = ['foo', 'foo.bar', 'foo.bar.baz',\n" +" 'spam', 'spam.ham', 'spam.ham.eggs']\n" +" if os.name == 'posix':\n" +" # On POSIX, the setup logger will have been configured in the\n" +" # parent process, but should have been disabled following the\n" +" # dictConfig call.\n" +" # On Windows, since fork isn't used, the setup logger won't\n" +" # exist in the child, so it would be created and the message\n" +" # would appear - hence the \"if posix\" clause.\n" +" logger = logging.getLogger('setup')\n" +" logger.critical('Should not appear, because of disabled " +"logger ...')\n" +" for i in range(100):\n" +" lvl = random.choice(levels)\n" +" logger = logging.getLogger(random.choice(loggers))\n" +" logger.log(lvl, 'Message no. %d', i)\n" +" time.sleep(0.01)\n" +"\n" +"def main():\n" +" q = Queue()\n" +" # The main process gets a simple configuration which prints to the " +"console.\n" +" config_initial = {\n" +" 'version': 1,\n" +" 'handlers': {\n" +" 'console': {\n" +" 'class': 'logging.StreamHandler',\n" +" 'level': 'INFO'\n" +" }\n" +" },\n" +" 'root': {\n" +" 'handlers': ['console'],\n" +" 'level': 'DEBUG'\n" +" }\n" +" }\n" +" # The worker process configuration is just a QueueHandler attached to " +"the\n" +" # root logger, which allows all messages to be sent to the queue.\n" +" # We disable existing loggers to disable the \"setup\" logger used in " +"the\n" +" # parent process. This is needed on POSIX because the logger will\n" +" # be there in the child following a fork().\n" +" config_worker = {\n" +" 'version': 1,\n" +" 'disable_existing_loggers': True,\n" +" 'handlers': {\n" +" 'queue': {\n" +" 'class': 'logging.handlers.QueueHandler',\n" +" 'queue': q\n" +" }\n" +" },\n" +" 'root': {\n" +" 'handlers': ['queue'],\n" +" 'level': 'DEBUG'\n" +" }\n" +" }\n" +" # The listener process configuration shows that the full flexibility of\n" +" # logging configuration is available to dispatch events to handlers " +"however\n" +" # you want.\n" +" # We disable existing loggers to disable the \"setup\" logger used in " +"the\n" +" # parent process. This is needed on POSIX because the logger will\n" +" # be there in the child following a fork().\n" +" config_listener = {\n" +" 'version': 1,\n" +" 'disable_existing_loggers': True,\n" +" 'formatters': {\n" +" 'detailed': {\n" +" 'class': 'logging.Formatter',\n" +" 'format': '%(asctime)s %(name)-15s %(levelname)-8s %" +"(processName)-10s %(message)s'\n" +" },\n" +" 'simple': {\n" +" 'class': 'logging.Formatter',\n" +" 'format': '%(name)-15s %(levelname)-8s %(processName)-10s %" +"(message)s'\n" +" }\n" +" },\n" +" 'handlers': {\n" +" 'console': {\n" +" 'class': 'logging.StreamHandler',\n" +" 'formatter': 'simple',\n" +" 'level': 'INFO'\n" +" },\n" +" 'file': {\n" +" 'class': 'logging.FileHandler',\n" +" 'filename': 'mplog.log',\n" +" 'mode': 'w',\n" +" 'formatter': 'detailed'\n" +" },\n" +" 'foofile': {\n" +" 'class': 'logging.FileHandler',\n" +" 'filename': 'mplog-foo.log',\n" +" 'mode': 'w',\n" +" 'formatter': 'detailed'\n" +" },\n" +" 'errors': {\n" +" 'class': 'logging.FileHandler',\n" +" 'filename': 'mplog-errors.log',\n" +" 'mode': 'w',\n" +" 'formatter': 'detailed',\n" +" 'level': 'ERROR'\n" +" }\n" +" },\n" +" 'loggers': {\n" +" 'foo': {\n" +" 'handlers': ['foofile']\n" +" }\n" +" },\n" +" 'root': {\n" +" 'handlers': ['console', 'file', 'errors'],\n" +" 'level': 'DEBUG'\n" +" }\n" +" }\n" +" # Log some initial events, just to show that logging in the parent " +"works\n" +" # normally.\n" +" logging.config.dictConfig(config_initial)\n" +" logger = logging.getLogger('setup')\n" +" logger.info('About to create workers ...')\n" +" workers = []\n" +" for i in range(5):\n" +" wp = Process(target=worker_process, name='worker %d' % (i + 1),\n" +" args=(config_worker,))\n" +" workers.append(wp)\n" +" wp.start()\n" +" logger.info('Started worker: %s', wp.name)\n" +" logger.info('About to create listener ...')\n" +" stop_event = Event()\n" +" lp = Process(target=listener_process, name='listener',\n" +" args=(q, stop_event, config_listener))\n" +" lp.start()\n" +" logger.info('Started listener')\n" +" # We now hang around for the workers to finish their work.\n" +" for wp in workers:\n" +" wp.join()\n" +" # Workers all done, listening can now stop.\n" +" # Logging in the parent still works normally.\n" +" logger.info('Telling listener to stop ...')\n" +" stop_event.set()\n" +" lp.join()\n" +" logger.info('All done.')\n" +"\n" +"if __name__ == '__main__':\n" +" main()" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2458 +msgid "Inserting a BOM into messages sent to a SysLogHandler" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2460 +msgid "" +":rfc:`5424` requires that a Unicode message be sent to a syslog daemon as a " +"set of bytes which have the following structure: an optional pure-ASCII " +"component, followed by a UTF-8 Byte Order Mark (BOM), followed by Unicode " +"encoded using UTF-8. (See the :rfc:`relevant section of the specification " +"<5424#section-6>`.)" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2466 +msgid "" +"In Python 3.1, code was added to :class:`~logging.handlers.SysLogHandler` to " +"insert a BOM into the message, but unfortunately, it was implemented " +"incorrectly, with the BOM appearing at the beginning of the message and " +"hence not allowing any pure-ASCII component to appear before it." +msgstr "" + +#: ../../howto/logging-cookbook.rst:2472 +msgid "" +"As this behaviour is broken, the incorrect BOM insertion code is being " +"removed from Python 3.2.4 and later. However, it is not being replaced, and " +"if you want to produce :rfc:`5424`-compliant messages which include a BOM, " +"an optional pure-ASCII sequence before it and arbitrary Unicode after it, " +"encoded using UTF-8, then you need to do the following:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2478 +msgid "" +"Attach a :class:`~logging.Formatter` instance to " +"your :class:`~logging.handlers.SysLogHandler` instance, with a format string " +"such as::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2482 +msgid "'ASCII section\\ufeffUnicode section'" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2484 +msgid "" +"The Unicode code point U+FEFF, when encoded using UTF-8, will be encoded as " +"a UTF-8 BOM -- the byte-string ``b'\\xef\\xbb\\xbf'``." +msgstr "" + +#: ../../howto/logging-cookbook.rst:2487 +msgid "" +"Replace the ASCII section with whatever placeholders you like, but make sure " +"that the data that appears in there after substitution is always ASCII (that " +"way, it will remain unchanged after UTF-8 encoding)." +msgstr "" + +#: ../../howto/logging-cookbook.rst:2491 +msgid "" +"Replace the Unicode section with whatever placeholders you like; if the data " +"which appears there after substitution contains characters outside the ASCII " +"range, that's fine -- it will be encoded using UTF-8." +msgstr "" + +#: ../../howto/logging-cookbook.rst:2495 +msgid "" +"The formatted message *will* be encoded using UTF-8 encoding by " +"``SysLogHandler``. If you follow the above rules, you should be able to " +"produce :rfc:`5424`-compliant messages. If you don't, logging may not " +"complain, but your messages will not be RFC 5424-compliant, and your syslog " +"daemon may complain." +msgstr "" + +#: ../../howto/logging-cookbook.rst:2502 +msgid "Implementing structured logging" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2504 +msgid "" +"Although most logging messages are intended for reading by humans, and thus " +"not readily machine-parseable, there might be circumstances where you want " +"to output messages in a structured format which *is* capable of being parsed " +"by a program (without needing complex regular expressions to parse the log " +"message). This is straightforward to achieve using the logging package. " +"There are a number of ways in which this could be achieved, but the " +"following is a simple approach which uses JSON to serialise the event in a " +"machine-parseable manner::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2512 +msgid "" +"import json\n" +"import logging\n" +"\n" +"class StructuredMessage:\n" +" def __init__(self, message, /, **kwargs):\n" +" self.message = message\n" +" self.kwargs = kwargs\n" +"\n" +" def __str__(self):\n" +" return '%s >>> %s' % (self.message, json.dumps(self.kwargs))\n" +"\n" +"_ = StructuredMessage # optional, to improve readability\n" +"\n" +"logging.basicConfig(level=logging.INFO, format='%(message)s')\n" +"logging.info(_('message 1', foo='bar', bar='baz', num=123, fnum=123.456))" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2528 +msgid "If the above script is run, it prints:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2530 +msgid "" +"message 1 >>> {\"fnum\": 123.456, \"num\": 123, \"bar\": \"baz\", \"foo\": " +"\"bar\"}" +msgstr "" +"message 1 >>> {\"fnum\": 123.456, \"num\": 123, \"bar\": \"baz\", \"foo\": " +"\"bar\"}" + +#: ../../howto/logging-cookbook.rst:2534 ../../howto/logging-cookbook.rst:2576 +msgid "" +"Note that the order of items might be different according to the version of " +"Python used." +msgstr "" + +#: ../../howto/logging-cookbook.rst:2537 +msgid "" +"If you need more specialised processing, you can use a custom JSON encoder, " +"as in the following complete example::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2540 +msgid "" +"import json\n" +"import logging\n" +"\n" +"\n" +"class Encoder(json.JSONEncoder):\n" +" def default(self, o):\n" +" if isinstance(o, set):\n" +" return tuple(o)\n" +" elif isinstance(o, str):\n" +" return o.encode('unicode_escape').decode('ascii')\n" +" return super().default(o)\n" +"\n" +"class StructuredMessage:\n" +" def __init__(self, message, /, **kwargs):\n" +" self.message = message\n" +" self.kwargs = kwargs\n" +"\n" +" def __str__(self):\n" +" s = Encoder().encode(self.kwargs)\n" +" return '%s >>> %s' % (self.message, s)\n" +"\n" +"_ = StructuredMessage # optional, to improve readability\n" +"\n" +"def main():\n" +" logging.basicConfig(level=logging.INFO, format='%(message)s')\n" +" logging.info(_('message 1', set_value={1, 2, 3}, snowman='\\u2603'))\n" +"\n" +"if __name__ == '__main__':\n" +" main()" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2570 +msgid "When the above script is run, it prints:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2572 +msgid "message 1 >>> {\"snowman\": \"\\u2603\", \"set_value\": [1, 2, 3]}" +msgstr "message 1 >>> {\"snowman\": \"\\u2603\", \"set_value\": [1, 2, 3]}" + +#: ../../howto/logging-cookbook.rst:2585 +msgid "Customizing handlers with :func:`dictConfig`" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2587 +msgid "" +"There are times when you want to customize logging handlers in particular " +"ways, and if you use :func:`dictConfig` you may be able to do this without " +"subclassing. As an example, consider that you may want to set the ownership " +"of a log file. On POSIX, this is easily done using :func:`shutil.chown`, but " +"the file handlers in the stdlib don't offer built-in support. You can " +"customize handler creation using a plain function such as::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2594 +msgid "" +"def owned_file_handler(filename, mode='a', encoding=None, owner=None):\n" +" if owner:\n" +" if not os.path.exists(filename):\n" +" open(filename, 'a').close()\n" +" shutil.chown(filename, *owner)\n" +" return logging.FileHandler(filename, mode, encoding)" +msgstr "" +"def owned_file_handler(filename, mode='a', encoding=None, owner=None):\n" +" if owner:\n" +" if not os.path.exists(filename):\n" +" open(filename, 'a').close()\n" +" shutil.chown(filename, *owner)\n" +" return logging.FileHandler(filename, mode, encoding)" + +#: ../../howto/logging-cookbook.rst:2601 +msgid "" +"You can then specify, in a logging configuration passed " +"to :func:`dictConfig`, that a logging handler be created by calling this " +"function::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2604 +msgid "" +"LOGGING = {\n" +" 'version': 1,\n" +" 'disable_existing_loggers': False,\n" +" 'formatters': {\n" +" 'default': {\n" +" 'format': '%(asctime)s %(levelname)s %(name)s %(message)s'\n" +" },\n" +" },\n" +" 'handlers': {\n" +" 'file':{\n" +" # The values below are popped from this dictionary and\n" +" # used to create the handler, set the handler's level and\n" +" # its formatter.\n" +" '()': owned_file_handler,\n" +" 'level':'DEBUG',\n" +" 'formatter': 'default',\n" +" # The values below are passed to the handler creator callable\n" +" # as keyword arguments.\n" +" 'owner': ['pulse', 'pulse'],\n" +" 'filename': 'chowntest.log',\n" +" 'mode': 'w',\n" +" 'encoding': 'utf-8',\n" +" },\n" +" },\n" +" 'root': {\n" +" 'handlers': ['file'],\n" +" 'level': 'DEBUG',\n" +" },\n" +"}" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2634 +msgid "" +"In this example I am setting the ownership using the ``pulse`` user and " +"group, just for the purposes of illustration. Putting it together into a " +"working script, ``chowntest.py``::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2638 +msgid "" +"import logging, logging.config, os, shutil\n" +"\n" +"def owned_file_handler(filename, mode='a', encoding=None, owner=None):\n" +" if owner:\n" +" if not os.path.exists(filename):\n" +" open(filename, 'a').close()\n" +" shutil.chown(filename, *owner)\n" +" return logging.FileHandler(filename, mode, encoding)\n" +"\n" +"LOGGING = {\n" +" 'version': 1,\n" +" 'disable_existing_loggers': False,\n" +" 'formatters': {\n" +" 'default': {\n" +" 'format': '%(asctime)s %(levelname)s %(name)s %(message)s'\n" +" },\n" +" },\n" +" 'handlers': {\n" +" 'file':{\n" +" # The values below are popped from this dictionary and\n" +" # used to create the handler, set the handler's level and\n" +" # its formatter.\n" +" '()': owned_file_handler,\n" +" 'level':'DEBUG',\n" +" 'formatter': 'default',\n" +" # The values below are passed to the handler creator callable\n" +" # as keyword arguments.\n" +" 'owner': ['pulse', 'pulse'],\n" +" 'filename': 'chowntest.log',\n" +" 'mode': 'w',\n" +" 'encoding': 'utf-8',\n" +" },\n" +" },\n" +" 'root': {\n" +" 'handlers': ['file'],\n" +" 'level': 'DEBUG',\n" +" },\n" +"}\n" +"\n" +"logging.config.dictConfig(LOGGING)\n" +"logger = logging.getLogger('mylogger')\n" +"logger.debug('A debug message')" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2681 +msgid "To run this, you will probably need to run as ``root``:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2683 +msgid "" +"$ sudo python3.3 chowntest.py\n" +"$ cat chowntest.log\n" +"2013-11-05 09:34:51,128 DEBUG mylogger A debug message\n" +"$ ls -l chowntest.log\n" +"-rw-r--r-- 1 pulse pulse 55 2013-11-05 09:34 chowntest.log" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2691 +msgid "" +"Note that this example uses Python 3.3 because that's " +"where :func:`shutil.chown` makes an appearance. This approach should work " +"with any Python version that supports :func:`dictConfig` - namely, Python " +"2.7, 3.2 or later. With pre-3.3 versions, you would need to implement the " +"actual ownership change using e.g. :func:`os.chown`." +msgstr "" + +#: ../../howto/logging-cookbook.rst:2697 +msgid "" +"In practice, the handler-creating function may be in a utility module " +"somewhere in your project. Instead of the line in the configuration::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2700 +msgid "'()': owned_file_handler," +msgstr "'()': owned_file_handler," + +#: ../../howto/logging-cookbook.rst:2702 +msgid "you could use e.g.::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2704 +msgid "'()': 'ext://project.util.owned_file_handler'," +msgstr "'()': 'ext://project.util.owned_file_handler'," + +#: ../../howto/logging-cookbook.rst:2706 +msgid "" +"where ``project.util`` can be replaced with the actual name of the package " +"where the function resides. In the above working script, using ``'ext://" +"__main__.owned_file_handler'`` should work. Here, the actual callable is " +"resolved by :func:`dictConfig` from the ``ext://`` specification." +msgstr "" + +#: ../../howto/logging-cookbook.rst:2711 +msgid "" +"This example hopefully also points the way to how you could implement other " +"types of file change - e.g. setting specific POSIX permission bits - in the " +"same way, using :func:`os.chmod`." +msgstr "" + +#: ../../howto/logging-cookbook.rst:2715 +msgid "" +"Of course, the approach could also be extended to types of handler other " +"than a :class:`~logging.FileHandler` - for example, one of the rotating file " +"handlers, or a different type of handler altogether." +msgstr "" + +#: ../../howto/logging-cookbook.rst:2725 +msgid "Using particular formatting styles throughout your application" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2727 +msgid "" +"In Python 3.2, the :class:`~logging.Formatter` gained a ``style`` keyword " +"parameter which, while defaulting to ``%`` for backward compatibility, " +"allowed the specification of ``{`` or ``$`` to support the formatting " +"approaches supported by :meth:`str.format` and :class:`string.Template`. " +"Note that this governs the formatting of logging messages for final output " +"to logs, and is completely orthogonal to how an individual logging message " +"is constructed." +msgstr "" + +#: ../../howto/logging-cookbook.rst:2734 +msgid "" +"Logging calls (:meth:`~Logger.debug`, :meth:`~Logger.info` etc.) only take " +"positional parameters for the actual logging message itself, with keyword " +"parameters used only for determining options for how to handle the logging " +"call (e.g. the ``exc_info`` keyword parameter to indicate that traceback " +"information should be logged, or the ``extra`` keyword parameter to indicate " +"additional contextual information to be added to the log). So you cannot " +"directly make logging calls using :meth:`str.format` " +"or :class:`string.Template` syntax, because internally the logging package " +"uses %-formatting to merge the format string and the variable arguments. " +"There would be no changing this while preserving backward compatibility, " +"since all logging calls which are out there in existing code will be using %-" +"format strings." +msgstr "" + +#: ../../howto/logging-cookbook.rst:2746 +msgid "" +"There have been suggestions to associate format styles with specific " +"loggers, but that approach also runs into backward compatibility problems " +"because any existing code could be using a given logger name and using %-" +"formatting." +msgstr "" + +#: ../../howto/logging-cookbook.rst:2750 +msgid "" +"For logging to work interoperably between any third-party libraries and your " +"code, decisions about formatting need to be made at the level of the " +"individual logging call. This opens up a couple of ways in which alternative " +"formatting styles can be accommodated." +msgstr "" + +#: ../../howto/logging-cookbook.rst:2757 +msgid "Using LogRecord factories" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2759 +msgid "" +"In Python 3.2, along with the :class:`~logging.Formatter` changes mentioned " +"above, the logging package gained the ability to allow users to set their " +"own :class:`LogRecord` subclasses, using the :func:`setLogRecordFactory` " +"function. You can use this to set your own subclass of :class:`LogRecord`, " +"which does the Right Thing by overriding the :meth:`~LogRecord.getMessage` " +"method. The base class implementation of this method is where the ``msg % " +"args`` formatting happens, and where you can substitute your alternate " +"formatting; however, you should be careful to support all formatting styles " +"and allow %-formatting as the default, to ensure interoperability with other " +"code. Care should also be taken to call ``str(self.msg)``, just as the base " +"implementation does." +msgstr "" + +#: ../../howto/logging-cookbook.rst:2770 +msgid "" +"Refer to the reference documentation on :func:`setLogRecordFactory` " +"and :class:`LogRecord` for more information." +msgstr "" + +#: ../../howto/logging-cookbook.rst:2775 +msgid "Using custom message objects" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2777 +msgid "" +"There is another, perhaps simpler way that you can use {}- and $- formatting " +"to construct your individual log messages. You may recall " +"(from :ref:`arbitrary-object-messages`) that when logging you can use an " +"arbitrary object as a message format string, and that the logging package " +"will call :func:`str` on that object to get the actual format string. " +"Consider the following two classes::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2802 +msgid "" +"Either of these can be used in place of a format string, to allow {}- or $-" +"formatting to be used to build the actual \"message\" part which appears in " +"the formatted log output in place of “%(message)s” or “{message}” or " +"“$message”. If you find it a little unwieldy to use the class names whenever " +"you want to log something, you can make it more palatable if you use an " +"alias such as ``M`` or ``_`` for the message (or perhaps ``__``, if you are " +"using ``_`` for localization)." +msgstr "" + +#: ../../howto/logging-cookbook.rst:2810 +msgid "" +"Examples of this approach are given below. Firstly, formatting " +"with :meth:`str.format`::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2813 +msgid "" +">>> __ = BraceMessage\n" +">>> print(__('Message with {0} {1}', 2, 'placeholders'))\n" +"Message with 2 placeholders\n" +">>> class Point: pass\n" +"...\n" +">>> p = Point()\n" +">>> p.x = 0.5\n" +">>> p.y = 0.5\n" +">>> print(__('Message with coordinates: ({point.x:.2f}, {point.y:.2f})', " +"point=p))\n" +"Message with coordinates: (0.50, 0.50)" +msgstr "" +">>> __ = BraceMessage\n" +">>> print(__('Message with {0} {1}', 2, 'placeholders'))\n" +"Message with 2 placeholders\n" +">>> class Point: pass\n" +"...\n" +">>> p = Point()\n" +">>> p.x = 0.5\n" +">>> p.y = 0.5\n" +">>> print(__('Message with coordinates: ({point.x:.2f}, {point.y:.2f})', " +"point=p))\n" +"Message with coordinates: (0.50, 0.50)" + +#: ../../howto/logging-cookbook.rst:2824 +msgid "Secondly, formatting with :class:`string.Template`::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2826 +msgid "" +">>> __ = DollarMessage\n" +">>> print(__('Message with $num $what', num=2, what='placeholders'))\n" +"Message with 2 placeholders\n" +">>>" +msgstr "" +">>> __ = DollarMessage\n" +">>> print(__('Message with $num $what', num=2, what='placeholders'))\n" +"Message with 2 placeholders\n" +">>>" + +#: ../../howto/logging-cookbook.rst:2831 +msgid "" +"One thing to note is that you pay no significant performance penalty with " +"this approach: the actual formatting happens not when you make the logging " +"call, but when (and if) the logged message is actually about to be output to " +"a log by a handler. So the only slightly unusual thing which might trip you " +"up is that the parentheses go around the format string and the arguments, " +"not just the format string. That’s because the __ notation is just syntax " +"sugar for a constructor call to one of the :samp:`{XXX}Message` classes " +"shown above." +msgstr "" + +#: ../../howto/logging-cookbook.rst:2845 +msgid "Configuring filters with :func:`dictConfig`" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2847 +msgid "" +"You *can* configure filters using :func:`~logging.config.dictConfig`, though " +"it might not be obvious at first glance how to do it (hence this recipe). " +"Since :class:`~logging.Filter` is the only filter class included in the " +"standard library, and it is unlikely to cater to many requirements (it's " +"only there as a base class), you will typically need to define your " +"own :class:`~logging.Filter` subclass with an " +"overridden :meth:`~logging.Filter.filter` method. To do this, specify the " +"``()`` key in the configuration dictionary for the filter, specifying a " +"callable which will be used to create the filter (a class is the most " +"obvious, but you can provide any callable which returns " +"a :class:`~logging.Filter` instance). Here is a complete example::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2858 +msgid "" +"import logging\n" +"import logging.config\n" +"import sys\n" +"\n" +"class MyFilter(logging.Filter):\n" +" def __init__(self, param=None):\n" +" self.param = param\n" +"\n" +" def filter(self, record):\n" +" if self.param is None:\n" +" allow = True\n" +" else:\n" +" allow = self.param not in record.msg\n" +" if allow:\n" +" record.msg = 'changed: ' + record.msg\n" +" return allow\n" +"\n" +"LOGGING = {\n" +" 'version': 1,\n" +" 'filters': {\n" +" 'myfilter': {\n" +" '()': MyFilter,\n" +" 'param': 'noshow',\n" +" }\n" +" },\n" +" 'handlers': {\n" +" 'console': {\n" +" 'class': 'logging.StreamHandler',\n" +" 'filters': ['myfilter']\n" +" }\n" +" },\n" +" 'root': {\n" +" 'level': 'DEBUG',\n" +" 'handlers': ['console']\n" +" },\n" +"}\n" +"\n" +"if __name__ == '__main__':\n" +" logging.config.dictConfig(LOGGING)\n" +" logging.debug('hello')\n" +" logging.debug('hello - noshow')" +msgstr "" +"import logging\n" +"import logging.config\n" +"import sys\n" +"\n" +"class MyFilter(logging.Filter):\n" +" def __init__(self, param=None):\n" +" self.param = param\n" +"\n" +" def filter(self, record):\n" +" if self.param is None:\n" +" allow = True\n" +" else:\n" +" allow = self.param not in record.msg\n" +" if allow:\n" +" record.msg = 'changed: ' + record.msg\n" +" return allow\n" +"\n" +"LOGGING = {\n" +" 'version': 1,\n" +" 'filters': {\n" +" 'myfilter': {\n" +" '()': MyFilter,\n" +" 'param': 'noshow',\n" +" }\n" +" },\n" +" 'handlers': {\n" +" 'console': {\n" +" 'class': 'logging.StreamHandler',\n" +" 'filters': ['myfilter']\n" +" }\n" +" },\n" +" 'root': {\n" +" 'level': 'DEBUG',\n" +" 'handlers': ['console']\n" +" },\n" +"}\n" +"\n" +"if __name__ == '__main__':\n" +" logging.config.dictConfig(LOGGING)\n" +" logging.debug('hello')\n" +" logging.debug('hello - noshow')" + +#: ../../howto/logging-cookbook.rst:2900 +msgid "" +"This example shows how you can pass configuration data to the callable which " +"constructs the instance, in the form of keyword parameters. When run, the " +"above script will print:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2904 +msgid "changed: hello" +msgstr "changed: hello" + +#: ../../howto/logging-cookbook.rst:2908 +msgid "which shows that the filter is working as configured." +msgstr "" + +#: ../../howto/logging-cookbook.rst:2910 +msgid "A couple of extra points to note:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2912 +msgid "" +"If you can't refer to the callable directly in the configuration (e.g. if it " +"lives in a different module, and you can't import it directly where the " +"configuration dictionary is), you can use the form ``ext://...`` as " +"described in :ref:`logging-config-dict-externalobj`. For example, you could " +"have used the text ``'ext://__main__.MyFilter'`` instead of ``MyFilter`` in " +"the above example." +msgstr "" + +#: ../../howto/logging-cookbook.rst:2919 +msgid "" +"As well as for filters, this technique can also be used to configure custom " +"handlers and formatters. See :ref:`logging-config-dict-userdef` for more " +"information on how logging supports using user-defined objects in its " +"configuration, and see the other cookbook recipe :ref:`custom-handlers` " +"above." +msgstr "" + +#: ../../howto/logging-cookbook.rst:2928 +msgid "Customized exception formatting" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2930 +msgid "" +"There might be times when you want to do customized exception formatting - " +"for argument's sake, let's say you want exactly one line per logged event, " +"even when exception information is present. You can do this with a custom " +"formatter class, as shown in the following example::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2935 +msgid "" +"import logging\n" +"\n" +"class OneLineExceptionFormatter(logging.Formatter):\n" +" def formatException(self, exc_info):\n" +" \"\"\"\n" +" Format an exception so that it prints on a single line.\n" +" \"\"\"\n" +" result = super().formatException(exc_info)\n" +" return repr(result) # or format into one line however you want to\n" +"\n" +" def format(self, record):\n" +" s = super().format(record)\n" +" if record.exc_text:\n" +" s = s.replace('\\n', '') + '|'\n" +" return s\n" +"\n" +"def configure_logging():\n" +" fh = logging.FileHandler('output.txt', 'w')\n" +" f = OneLineExceptionFormatter('%(asctime)s|%(levelname)s|%(message)s|',\n" +" '%d/%m/%Y %H:%M:%S')\n" +" fh.setFormatter(f)\n" +" root = logging.getLogger()\n" +" root.setLevel(logging.DEBUG)\n" +" root.addHandler(fh)\n" +"\n" +"def main():\n" +" configure_logging()\n" +" logging.info('Sample message')\n" +" try:\n" +" x = 1 / 0\n" +" except ZeroDivisionError as e:\n" +" logging.exception('ZeroDivisionError: %s', e)\n" +"\n" +"if __name__ == '__main__':\n" +" main()" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2971 +msgid "When run, this produces a file with exactly two lines:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2973 +msgid "" +"28/01/2015 07:21:23|INFO|Sample message|\n" +"28/01/2015 07:21:23|ERROR|ZeroDivisionError: division by zero|'Traceback " +"(most recent call last):\\n File \"logtest7.py\", line 30, in main\\n x " +"= 1 / 0\\nZeroDivisionError: division by zero'|" +msgstr "" +"28/01/2015 07:21:23|INFO|Sample message|\n" +"28/01/2015 07:21:23|ERROR|ZeroDivisionError: division by zero|'Traceback " +"(most recent call last):\\n File \"logtest7.py\", line 30, in main\\n x " +"= 1 / 0\\nZeroDivisionError: division by zero'|" + +#: ../../howto/logging-cookbook.rst:2978 +msgid "" +"While the above treatment is simplistic, it points the way to how exception " +"information can be formatted to your liking. The :mod:`traceback` module may " +"be helpful for more specialized needs." +msgstr "" + +#: ../../howto/logging-cookbook.rst:2985 +msgid "Speaking logging messages" +msgstr "" + +#: ../../howto/logging-cookbook.rst:2987 +msgid "" +"There might be situations when it is desirable to have logging messages " +"rendered in an audible rather than a visible format. This is easy to do if " +"you have text-to-speech (TTS) functionality available in your system, even " +"if it doesn't have a Python binding. Most TTS systems have a command line " +"program you can run, and this can be invoked from a handler " +"using :mod:`subprocess`. It's assumed here that TTS command line programs " +"won't expect to interact with users or take a long time to complete, and " +"that the frequency of logged messages will be not so high as to swamp the " +"user with messages, and that it's acceptable to have the messages spoken one " +"at a time rather than concurrently, The example implementation below waits " +"for one message to be spoken before the next is processed, and this might " +"cause other handlers to be kept waiting. Here is a short example showing the " +"approach, which assumes that the ``espeak`` TTS package is available::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3000 +msgid "" +"import logging\n" +"import subprocess\n" +"import sys\n" +"\n" +"class TTSHandler(logging.Handler):\n" +" def emit(self, record):\n" +" msg = self.format(record)\n" +" # Speak slowly in a female English voice\n" +" cmd = ['espeak', '-s150', '-ven+f3', msg]\n" +" p = subprocess.Popen(cmd, stdout=subprocess.PIPE,\n" +" stderr=subprocess.STDOUT)\n" +" # wait for the program to finish\n" +" p.communicate()\n" +"\n" +"def configure_logging():\n" +" h = TTSHandler()\n" +" root = logging.getLogger()\n" +" root.addHandler(h)\n" +" # the default formatter just returns the message\n" +" root.setLevel(logging.DEBUG)\n" +"\n" +"def main():\n" +" logging.info('Hello')\n" +" logging.debug('Goodbye')\n" +"\n" +"if __name__ == '__main__':\n" +" configure_logging()\n" +" sys.exit(main())" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3029 +msgid "" +"When run, this script should say \"Hello\" and then \"Goodbye\" in a female " +"voice." +msgstr "" + +#: ../../howto/logging-cookbook.rst:3031 +msgid "" +"The above approach can, of course, be adapted to other TTS systems and even " +"other systems altogether which can process messages via external programs " +"run from a command line." +msgstr "" + +#: ../../howto/logging-cookbook.rst:3039 +msgid "Buffering logging messages and outputting them conditionally" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3041 +msgid "" +"There might be situations where you want to log messages in a temporary area " +"and only output them if a certain condition occurs. For example, you may " +"want to start logging debug events in a function, and if the function " +"completes without errors, you don't want to clutter the log with the " +"collected debug information, but if there is an error, you want all the " +"debug information to be output as well as the error." +msgstr "" + +#: ../../howto/logging-cookbook.rst:3048 +msgid "" +"Here is an example which shows how you could do this using a decorator for " +"your functions where you want logging to behave this way. It makes use of " +"the :class:`logging.handlers.MemoryHandler`, which allows buffering of " +"logged events until some condition occurs, at which point the buffered " +"events are ``flushed`` - passed to another handler (the ``target`` handler) " +"for processing. By default, the ``MemoryHandler`` flushed when its buffer " +"gets filled up or an event whose level is greater than or equal to a " +"specified threshold is seen. You can use this recipe with a more specialised " +"subclass of ``MemoryHandler`` if you want custom flushing behavior." +msgstr "" + +#: ../../howto/logging-cookbook.rst:3058 +msgid "" +"The example script has a simple function, ``foo``, which just cycles through " +"all the logging levels, writing to ``sys.stderr`` to say what level it's " +"about to log at, and then actually logging a message at that level. You can " +"pass a parameter to ``foo`` which, if true, will log at ERROR and CRITICAL " +"levels - otherwise, it only logs at DEBUG, INFO and WARNING levels." +msgstr "" + +#: ../../howto/logging-cookbook.rst:3064 +msgid "" +"The script just arranges to decorate ``foo`` with a decorator which will do " +"the conditional logging that's required. The decorator takes a logger as a " +"parameter and attaches a memory handler for the duration of the call to the " +"decorated function. The decorator can be additionally parameterised using a " +"target handler, a level at which flushing should occur, and a capacity for " +"the buffer (number of records buffered). These default to " +"a :class:`~logging.StreamHandler` which writes to ``sys.stderr``, " +"``logging.ERROR`` and ``100`` respectively." +msgstr "" + +#: ../../howto/logging-cookbook.rst:3072 +msgid "Here's the script::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3074 +msgid "" +"import logging\n" +"from logging.handlers import MemoryHandler\n" +"import sys\n" +"\n" +"logger = logging.getLogger(__name__)\n" +"logger.addHandler(logging.NullHandler())\n" +"\n" +"def log_if_errors(logger, target_handler=None, flush_level=None, " +"capacity=None):\n" +" if target_handler is None:\n" +" target_handler = logging.StreamHandler()\n" +" if flush_level is None:\n" +" flush_level = logging.ERROR\n" +" if capacity is None:\n" +" capacity = 100\n" +" handler = MemoryHandler(capacity, flushLevel=flush_level, " +"target=target_handler)\n" +"\n" +" def decorator(fn):\n" +" def wrapper(*args, **kwargs):\n" +" logger.addHandler(handler)\n" +" try:\n" +" return fn(*args, **kwargs)\n" +" except Exception:\n" +" logger.exception('call failed')\n" +" raise\n" +" finally:\n" +" super(MemoryHandler, handler).flush()\n" +" logger.removeHandler(handler)\n" +" return wrapper\n" +"\n" +" return decorator\n" +"\n" +"def write_line(s):\n" +" sys.stderr.write('%s\\n' % s)\n" +"\n" +"def foo(fail=False):\n" +" write_line('about to log at DEBUG ...')\n" +" logger.debug('Actually logged at DEBUG')\n" +" write_line('about to log at INFO ...')\n" +" logger.info('Actually logged at INFO')\n" +" write_line('about to log at WARNING ...')\n" +" logger.warning('Actually logged at WARNING')\n" +" if fail:\n" +" write_line('about to log at ERROR ...')\n" +" logger.error('Actually logged at ERROR')\n" +" write_line('about to log at CRITICAL ...')\n" +" logger.critical('Actually logged at CRITICAL')\n" +" return fail\n" +"\n" +"decorated_foo = log_if_errors(logger)(foo)\n" +"\n" +"if __name__ == '__main__':\n" +" logger.setLevel(logging.DEBUG)\n" +" write_line('Calling undecorated foo with False')\n" +" assert not foo(False)\n" +" write_line('Calling undecorated foo with True')\n" +" assert foo(True)\n" +" write_line('Calling decorated foo with False')\n" +" assert not decorated_foo(False)\n" +" write_line('Calling decorated foo with True')\n" +" assert decorated_foo(True)" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3135 +msgid "When this script is run, the following output should be observed:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3137 +msgid "" +"Calling undecorated foo with False\n" +"about to log at DEBUG ...\n" +"about to log at INFO ...\n" +"about to log at WARNING ...\n" +"Calling undecorated foo with True\n" +"about to log at DEBUG ...\n" +"about to log at INFO ...\n" +"about to log at WARNING ...\n" +"about to log at ERROR ...\n" +"about to log at CRITICAL ...\n" +"Calling decorated foo with False\n" +"about to log at DEBUG ...\n" +"about to log at INFO ...\n" +"about to log at WARNING ...\n" +"Calling decorated foo with True\n" +"about to log at DEBUG ...\n" +"about to log at INFO ...\n" +"about to log at WARNING ...\n" +"about to log at ERROR ...\n" +"Actually logged at DEBUG\n" +"Actually logged at INFO\n" +"Actually logged at WARNING\n" +"Actually logged at ERROR\n" +"about to log at CRITICAL ...\n" +"Actually logged at CRITICAL" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3165 +msgid "" +"As you can see, actual logging output only occurs when an event is logged " +"whose severity is ERROR or greater, but in that case, any previous events at " +"lower severities are also logged." +msgstr "" + +#: ../../howto/logging-cookbook.rst:3169 +msgid "You can of course use the conventional means of decoration::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3171 +msgid "" +"@log_if_errors(logger)\n" +"def foo(fail=False):\n" +" ..." +msgstr "" + +#: ../../howto/logging-cookbook.rst:3179 +msgid "Sending logging messages to email, with buffering" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3181 +msgid "" +"To illustrate how you can send log messages via email, so that a set number " +"of messages are sent per email, you can " +"subclass :class:`~logging.handlers.BufferingHandler`. In the following " +"example, which you can adapt to suit your specific needs, a simple test " +"harness is provided which allows you to run the script with command line " +"arguments specifying what you typically need to send things via SMTP. (Run " +"the downloaded script with the ``-h`` argument to see the required and " +"optional arguments.)" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3189 +msgid "" +"import logging\n" +"import logging.handlers\n" +"import smtplib\n" +"\n" +"class BufferingSMTPHandler(logging.handlers.BufferingHandler):\n" +" def __init__(self, mailhost, port, username, password, fromaddr, " +"toaddrs,\n" +" subject, capacity):\n" +" logging.handlers.BufferingHandler.__init__(self, capacity)\n" +" self.mailhost = mailhost\n" +" self.mailport = port\n" +" self.username = username\n" +" self.password = password\n" +" self.fromaddr = fromaddr\n" +" if isinstance(toaddrs, str):\n" +" toaddrs = [toaddrs]\n" +" self.toaddrs = toaddrs\n" +" self.subject = subject\n" +" self.setFormatter(logging.Formatter(\"%(asctime)s %(levelname)-5s %" +"(message)s\"))\n" +"\n" +" def flush(self):\n" +" if len(self.buffer) > 0:\n" +" try:\n" +" smtp = smtplib.SMTP(self.mailhost, self.mailport)\n" +" smtp.starttls()\n" +" smtp.login(self.username, self.password)\n" +" msg = \"From: %s\\r\\nTo: %s\\r\\nSubject: %s\\r\\n\\r\\n\" " +"% (self.fromaddr, ','.join(self.toaddrs), self.subject)\n" +" for record in self.buffer:\n" +" s = self.format(record)\n" +" msg = msg + s + \"\\r\\n\"\n" +" smtp.sendmail(self.fromaddr, self.toaddrs, msg)\n" +" smtp.quit()\n" +" except Exception:\n" +" if logging.raiseExceptions:\n" +" raise\n" +" self.buffer = []\n" +"\n" +"if __name__ == '__main__':\n" +" import argparse\n" +"\n" +" ap = argparse.ArgumentParser()\n" +" aa = ap.add_argument\n" +" aa('host', metavar='HOST', help='SMTP server')\n" +" aa('--port', '-p', type=int, default=587, help='SMTP port')\n" +" aa('user', metavar='USER', help='SMTP username')\n" +" aa('password', metavar='PASSWORD', help='SMTP password')\n" +" aa('to', metavar='TO', help='Addressee for emails')\n" +" aa('sender', metavar='SENDER', help='Sender email address')\n" +" aa('--subject', '-s',\n" +" default='Test Logging email from Python logging module (buffering)',\n" +" help='Subject of email')\n" +" options = ap.parse_args()\n" +" logger = logging.getLogger()\n" +" logger.setLevel(logging.DEBUG)\n" +" h = BufferingSMTPHandler(options.host, options.port, options.user,\n" +" options.password, options.sender,\n" +" options.to, options.subject, 10)\n" +" logger.addHandler(h)\n" +" for i in range(102):\n" +" logger.info(\"Info index = %d\", i)\n" +" h.flush()\n" +" h.close()" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3253 +msgid "" +"If you run this script and your SMTP server is correctly set up, you should " +"find that it sends eleven emails to the addressee you specify. The first ten " +"emails will each have ten log messages, and the eleventh will have two " +"messages. That makes up 102 messages as specified in the script." +msgstr "" + +#: ../../howto/logging-cookbook.rst:3261 +msgid "Formatting times using UTC (GMT) via configuration" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3263 +msgid "" +"Sometimes you want to format times using UTC, which can be done using a " +"class such as ``UTCFormatter``, shown below::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3266 +msgid "" +"import logging\n" +"import time\n" +"\n" +"class UTCFormatter(logging.Formatter):\n" +" converter = time.gmtime" +msgstr "" +"import logging\n" +"import time\n" +"\n" +"class UTCFormatter(logging.Formatter):\n" +" converter = time.gmtime" + +#: ../../howto/logging-cookbook.rst:3272 +msgid "" +"and you can then use the ``UTCFormatter`` in your code instead " +"of :class:`~logging.Formatter`. If you want to do that via configuration, " +"you can use the :func:`~logging.config.dictConfig` API with an approach " +"illustrated by the following complete example::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3277 +msgid "" +"import logging\n" +"import logging.config\n" +"import time\n" +"\n" +"class UTCFormatter(logging.Formatter):\n" +" converter = time.gmtime\n" +"\n" +"LOGGING = {\n" +" 'version': 1,\n" +" 'disable_existing_loggers': False,\n" +" 'formatters': {\n" +" 'utc': {\n" +" '()': UTCFormatter,\n" +" 'format': '%(asctime)s %(message)s',\n" +" },\n" +" 'local': {\n" +" 'format': '%(asctime)s %(message)s',\n" +" }\n" +" },\n" +" 'handlers': {\n" +" 'console1': {\n" +" 'class': 'logging.StreamHandler',\n" +" 'formatter': 'utc',\n" +" },\n" +" 'console2': {\n" +" 'class': 'logging.StreamHandler',\n" +" 'formatter': 'local',\n" +" },\n" +" },\n" +" 'root': {\n" +" 'handlers': ['console1', 'console2'],\n" +" }\n" +"}\n" +"\n" +"if __name__ == '__main__':\n" +" logging.config.dictConfig(LOGGING)\n" +" logging.warning('The local time is %s', time.asctime())" +msgstr "" +"import logging\n" +"import logging.config\n" +"import time\n" +"\n" +"class UTCFormatter(logging.Formatter):\n" +" converter = time.gmtime\n" +"\n" +"LOGGING = {\n" +" 'version': 1,\n" +" 'disable_existing_loggers': False,\n" +" 'formatters': {\n" +" 'utc': {\n" +" '()': UTCFormatter,\n" +" 'format': '%(asctime)s %(message)s',\n" +" },\n" +" 'local': {\n" +" 'format': '%(asctime)s %(message)s',\n" +" }\n" +" },\n" +" 'handlers': {\n" +" 'console1': {\n" +" 'class': 'logging.StreamHandler',\n" +" 'formatter': 'utc',\n" +" },\n" +" 'console2': {\n" +" 'class': 'logging.StreamHandler',\n" +" 'formatter': 'local',\n" +" },\n" +" },\n" +" 'root': {\n" +" 'handlers': ['console1', 'console2'],\n" +" }\n" +"}\n" +"\n" +"if __name__ == '__main__':\n" +" logging.config.dictConfig(LOGGING)\n" +" logging.warning('The local time is %s', time.asctime())" + +#: ../../howto/logging-cookbook.rst:3315 +msgid "When this script is run, it should print something like:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3317 +msgid "" +"2015-10-17 12:53:29,501 The local time is Sat Oct 17 13:53:29 2015\n" +"2015-10-17 13:53:29,501 The local time is Sat Oct 17 13:53:29 2015" +msgstr "" +"2015-10-17 12:53:29,501 The local time is Sat Oct 17 13:53:29 2015\n" +"2015-10-17 13:53:29,501 The local time is Sat Oct 17 13:53:29 2015" + +#: ../../howto/logging-cookbook.rst:3322 +msgid "" +"showing how the time is formatted both as local time and UTC, one for each " +"handler." +msgstr "" + +#: ../../howto/logging-cookbook.rst:3329 +msgid "Using a context manager for selective logging" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3331 +msgid "" +"There are times when it would be useful to temporarily change the logging " +"configuration and revert it back after doing something. For this, a context " +"manager is the most obvious way of saving and restoring the logging context. " +"Here is a simple example of such a context manager, which allows you to " +"optionally change the logging level and add a logging handler purely in the " +"scope of the context manager::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3338 +msgid "" +"import logging\n" +"import sys\n" +"\n" +"class LoggingContext:\n" +" def __init__(self, logger, level=None, handler=None, close=True):\n" +" self.logger = logger\n" +" self.level = level\n" +" self.handler = handler\n" +" self.close = close\n" +"\n" +" def __enter__(self):\n" +" if self.level is not None:\n" +" self.old_level = self.logger.level\n" +" self.logger.setLevel(self.level)\n" +" if self.handler:\n" +" self.logger.addHandler(self.handler)\n" +"\n" +" def __exit__(self, et, ev, tb):\n" +" if self.level is not None:\n" +" self.logger.setLevel(self.old_level)\n" +" if self.handler:\n" +" self.logger.removeHandler(self.handler)\n" +" if self.handler and self.close:\n" +" self.handler.close()\n" +" # implicit return of None => don't swallow exceptions" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3364 +msgid "" +"If you specify a level value, the logger's level is set to that value in the " +"scope of the with block covered by the context manager. If you specify a " +"handler, it is added to the logger on entry to the block and removed on exit " +"from the block. You can also ask the manager to close the handler for you on " +"block exit - you could do this if you don't need the handler any more." +msgstr "" + +#: ../../howto/logging-cookbook.rst:3370 +msgid "" +"To illustrate how it works, we can add the following block of code to the " +"above::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3373 +msgid "" +"if __name__ == '__main__':\n" +" logger = logging.getLogger('foo')\n" +" logger.addHandler(logging.StreamHandler())\n" +" logger.setLevel(logging.INFO)\n" +" logger.info('1. This should appear just once on stderr.')\n" +" logger.debug('2. This should not appear.')\n" +" with LoggingContext(logger, level=logging.DEBUG):\n" +" logger.debug('3. This should appear once on stderr.')\n" +" logger.debug('4. This should not appear.')\n" +" h = logging.StreamHandler(sys.stdout)\n" +" with LoggingContext(logger, level=logging.DEBUG, handler=h, " +"close=True):\n" +" logger.debug('5. This should appear twice - once on stderr and once " +"on stdout.')\n" +" logger.info('6. This should appear just once on stderr.')\n" +" logger.debug('7. This should not appear.')" +msgstr "" +"if __name__ == '__main__':\n" +" logger = logging.getLogger('foo')\n" +" logger.addHandler(logging.StreamHandler())\n" +" logger.setLevel(logging.INFO)\n" +" logger.info('1. This should appear just once on stderr.')\n" +" logger.debug('2. This should not appear.')\n" +" with LoggingContext(logger, level=logging.DEBUG):\n" +" logger.debug('3. This should appear once on stderr.')\n" +" logger.debug('4. This should not appear.')\n" +" h = logging.StreamHandler(sys.stdout)\n" +" with LoggingContext(logger, level=logging.DEBUG, handler=h, " +"close=True):\n" +" logger.debug('5. This should appear twice - once on stderr and once " +"on stdout.')\n" +" logger.info('6. This should appear just once on stderr.')\n" +" logger.debug('7. This should not appear.')" + +#: ../../howto/logging-cookbook.rst:3388 +msgid "" +"We initially set the logger's level to ``INFO``, so message #1 appears and " +"message #2 doesn't. We then change the level to ``DEBUG`` temporarily in the " +"following ``with`` block, and so message #3 appears. After the block exits, " +"the logger's level is restored to ``INFO`` and so message #4 doesn't appear. " +"In the next ``with`` block, we set the level to ``DEBUG`` again but also add " +"a handler writing to ``sys.stdout``. Thus, message #5 appears twice on the " +"console (once via ``stderr`` and once via ``stdout``). After the ``with`` " +"statement's completion, the status is as it was before so message #6 appears " +"(like message #1) whereas message #7 doesn't (just like message #2)." +msgstr "" + +#: ../../howto/logging-cookbook.rst:3398 +msgid "If we run the resulting script, the result is as follows:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3400 +msgid "" +"$ python logctx.py\n" +"1. This should appear just once on stderr.\n" +"3. This should appear once on stderr.\n" +"5. This should appear twice - once on stderr and once on stdout.\n" +"5. This should appear twice - once on stderr and once on stdout.\n" +"6. This should appear just once on stderr." +msgstr "" +"$ python logctx.py\n" +"1. This should appear just once on stderr.\n" +"3. This should appear once on stderr.\n" +"5. This should appear twice - once on stderr and once on stdout.\n" +"5. This should appear twice - once on stderr and once on stdout.\n" +"6. This should appear just once on stderr." + +#: ../../howto/logging-cookbook.rst:3409 +msgid "" +"If we run it again, but pipe ``stderr`` to ``/dev/null``, we see the " +"following, which is the only message written to ``stdout``:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3412 +msgid "" +"$ python logctx.py 2>/dev/null\n" +"5. This should appear twice - once on stderr and once on stdout." +msgstr "" + +#: ../../howto/logging-cookbook.rst:3417 +msgid "Once again, but piping ``stdout`` to ``/dev/null``, we get:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3419 +msgid "" +"$ python logctx.py >/dev/null\n" +"1. This should appear just once on stderr.\n" +"3. This should appear once on stderr.\n" +"5. This should appear twice - once on stderr and once on stdout.\n" +"6. This should appear just once on stderr." +msgstr "" +"$ python logctx.py >/dev/null\n" +"1. This should appear just once on stderr.\n" +"3. This should appear once on stderr.\n" +"5. This should appear twice - once on stderr and once on stdout.\n" +"6. This should appear just once on stderr." + +#: ../../howto/logging-cookbook.rst:3427 +msgid "" +"In this case, the message #5 printed to ``stdout`` doesn't appear, as " +"expected." +msgstr "" + +#: ../../howto/logging-cookbook.rst:3429 +msgid "" +"Of course, the approach described here can be generalised, for example to " +"attach logging filters temporarily. Note that the above code works in Python " +"2 as well as Python 3." +msgstr "" + +#: ../../howto/logging-cookbook.rst:3437 +msgid "A CLI application starter template" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3439 +msgid "Here's an example which shows how you can:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3441 +msgid "Use a logging level based on command-line arguments" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3442 +msgid "" +"Dispatch to multiple subcommands in separate files, all logging at the same " +"level in a consistent way" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3444 +msgid "Make use of simple, minimal configuration" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3446 +msgid "" +"Suppose we have a command-line application whose job is to stop, start or " +"restart some services. This could be organised for the purposes of " +"illustration as a file ``app.py`` that is the main script for the " +"application, with individual commands implemented in ``start.py``, " +"``stop.py`` and ``restart.py``. Suppose further that we want to control the " +"verbosity of the application via a command-line argument, defaulting to " +"``logging.INFO``. Here's one way that ``app.py`` could be written::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3454 +msgid "" +"import argparse\n" +"import importlib\n" +"import logging\n" +"import os\n" +"import sys\n" +"\n" +"def main(args=None):\n" +" scriptname = os.path.basename(__file__)\n" +" parser = argparse.ArgumentParser(scriptname)\n" +" levels = ('DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL')\n" +" parser.add_argument('--log-level', default='INFO', choices=levels)\n" +" subparsers = parser.add_subparsers(dest='command',\n" +" help='Available commands:')\n" +" start_cmd = subparsers.add_parser('start', help='Start a service')\n" +" start_cmd.add_argument('name', metavar='NAME',\n" +" help='Name of service to start')\n" +" stop_cmd = subparsers.add_parser('stop',\n" +" help='Stop one or more services')\n" +" stop_cmd.add_argument('names', metavar='NAME', nargs='+',\n" +" help='Name of service to stop')\n" +" restart_cmd = subparsers.add_parser('restart',\n" +" help='Restart one or more " +"services')\n" +" restart_cmd.add_argument('names', metavar='NAME', nargs='+',\n" +" help='Name of service to restart')\n" +" options = parser.parse_args()\n" +" # the code to dispatch commands could all be in this file. For the " +"purposes\n" +" # of illustration only, we implement each command in a separate module.\n" +" try:\n" +" mod = importlib.import_module(options.command)\n" +" cmd = getattr(mod, 'command')\n" +" except (ImportError, AttributeError):\n" +" print('Unable to find the code for command \\'%s\\'' % " +"options.command)\n" +" return 1\n" +" # Could get fancy here and load configuration from file or dictionary\n" +" logging.basicConfig(level=options.log_level,\n" +" format='%(levelname)s %(name)s %(message)s')\n" +" cmd(options)\n" +"\n" +"if __name__ == '__main__':\n" +" sys.exit(main())" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3495 +msgid "" +"And the ``start``, ``stop`` and ``restart`` commands can be implemented in " +"separate modules, like so for starting::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3498 +msgid "" +"# start.py\n" +"import logging\n" +"\n" +"logger = logging.getLogger(__name__)\n" +"\n" +"def command(options):\n" +" logger.debug('About to start %s', options.name)\n" +" # actually do the command processing here ...\n" +" logger.info('Started the \\'%s\\' service.', options.name)" +msgstr "" +"# start.py\n" +"import logging\n" +"\n" +"logger = logging.getLogger(__name__)\n" +"\n" +"def command(options):\n" +" logger.debug('About to start %s', options.name)\n" +" # 在這裡實際執行命令處理 ...\n" +" logger.info('Started the \\'%s\\' service.', options.name)" + +#: ../../howto/logging-cookbook.rst:3508 +msgid "and thus for stopping::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3510 +msgid "" +"# stop.py\n" +"import logging\n" +"\n" +"logger = logging.getLogger(__name__)\n" +"\n" +"def command(options):\n" +" n = len(options.names)\n" +" if n == 1:\n" +" plural = ''\n" +" services = '\\'%s\\'' % options.names[0]\n" +" else:\n" +" plural = 's'\n" +" services = ', '.join('\\'%s\\'' % name for name in options.names)\n" +" i = services.rfind(', ')\n" +" services = services[:i] + ' and ' + services[i + 2:]\n" +" logger.debug('About to stop %s', services)\n" +" # actually do the command processing here ...\n" +" logger.info('Stopped the %s service%s.', services, plural)" +msgstr "" +"# stop.py\n" +"import logging\n" +"\n" +"logger = logging.getLogger(__name__)\n" +"\n" +"def command(options):\n" +" n = len(options.names)\n" +" if n == 1:\n" +" plural = ''\n" +" services = '\\'%s\\'' % options.names[0]\n" +" else:\n" +" plural = 's'\n" +" services = ', '.join('\\'%s\\'' % name for name in options.names)\n" +" i = services.rfind(', ')\n" +" services = services[:i] + ' and ' + services[i + 2:]\n" +" logger.debug('About to stop %s', services)\n" +" # 在這裡實際執行命令處理 ...\n" +" logger.info('Stopped the %s service%s.', services, plural)" + +#: ../../howto/logging-cookbook.rst:3529 +msgid "and similarly for restarting::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3531 +msgid "" +"# restart.py\n" +"import logging\n" +"\n" +"logger = logging.getLogger(__name__)\n" +"\n" +"def command(options):\n" +" n = len(options.names)\n" +" if n == 1:\n" +" plural = ''\n" +" services = '\\'%s\\'' % options.names[0]\n" +" else:\n" +" plural = 's'\n" +" services = ', '.join('\\'%s\\'' % name for name in options.names)\n" +" i = services.rfind(', ')\n" +" services = services[:i] + ' and ' + services[i + 2:]\n" +" logger.debug('About to restart %s', services)\n" +" # actually do the command processing here ...\n" +" logger.info('Restarted the %s service%s.', services, plural)" +msgstr "" +"# restart.py\n" +"import logging\n" +"\n" +"logger = logging.getLogger(__name__)\n" +"\n" +"def command(options):\n" +" n = len(options.names)\n" +" if n == 1:\n" +" plural = ''\n" +" services = '\\'%s\\'' % options.names[0]\n" +" else:\n" +" plural = 's'\n" +" services = ', '.join('\\'%s\\'' % name for name in options.names)\n" +" i = services.rfind(', ')\n" +" services = services[:i] + ' and ' + services[i + 2:]\n" +" logger.debug('About to restart %s', services)\n" +" # 在這裡實際執行命令處理 ...\n" +" logger.info('Restarted the %s service%s.', services, plural)" + +#: ../../howto/logging-cookbook.rst:3550 +msgid "" +"If we run this application with the default log level, we get output like " +"this:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3552 +msgid "" +"$ python app.py start foo\n" +"INFO start Started the 'foo' service.\n" +"\n" +"$ python app.py stop foo bar\n" +"INFO stop Stopped the 'foo' and 'bar' services.\n" +"\n" +"$ python app.py restart foo bar baz\n" +"INFO restart Restarted the 'foo', 'bar' and 'baz' services." +msgstr "" +"$ python app.py start foo\n" +"INFO start Started the 'foo' service.\n" +"\n" +"$ python app.py stop foo bar\n" +"INFO stop Stopped the 'foo' and 'bar' services.\n" +"\n" +"$ python app.py restart foo bar baz\n" +"INFO restart Restarted the 'foo', 'bar' and 'baz' services." + +#: ../../howto/logging-cookbook.rst:3563 +msgid "" +"The first word is the logging level, and the second word is the module or " +"package name of the place where the event was logged." +msgstr "" + +#: ../../howto/logging-cookbook.rst:3566 +msgid "" +"If we change the logging level, then we can change the information sent to " +"the log. For example, if we want more information:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3569 +msgid "" +"$ python app.py --log-level DEBUG start foo\n" +"DEBUG start About to start foo\n" +"INFO start Started the 'foo' service.\n" +"\n" +"$ python app.py --log-level DEBUG stop foo bar\n" +"DEBUG stop About to stop 'foo' and 'bar'\n" +"INFO stop Stopped the 'foo' and 'bar' services.\n" +"\n" +"$ python app.py --log-level DEBUG restart foo bar baz\n" +"DEBUG restart About to restart 'foo', 'bar' and 'baz'\n" +"INFO restart Restarted the 'foo', 'bar' and 'baz' services." +msgstr "" +"$ python app.py --log-level DEBUG start foo\n" +"DEBUG start About to start foo\n" +"INFO start Started the 'foo' service.\n" +"\n" +"$ python app.py --log-level DEBUG stop foo bar\n" +"DEBUG stop About to stop 'foo' and 'bar'\n" +"INFO stop Stopped the 'foo' and 'bar' services.\n" +"\n" +"$ python app.py --log-level DEBUG restart foo bar baz\n" +"DEBUG restart About to restart 'foo', 'bar' and 'baz'\n" +"INFO restart Restarted the 'foo', 'bar' and 'baz' services." + +#: ../../howto/logging-cookbook.rst:3583 +msgid "And if we want less:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3585 +msgid "" +"$ python app.py --log-level WARNING start foo\n" +"$ python app.py --log-level WARNING stop foo bar\n" +"$ python app.py --log-level WARNING restart foo bar baz" +msgstr "" +"$ python app.py --log-level WARNING start foo\n" +"$ python app.py --log-level WARNING stop foo bar\n" +"$ python app.py --log-level WARNING restart foo bar baz" + +#: ../../howto/logging-cookbook.rst:3591 +msgid "" +"In this case, the commands don't print anything to the console, since " +"nothing at ``WARNING`` level or above is logged by them." +msgstr "" + +#: ../../howto/logging-cookbook.rst:3597 +msgid "A Qt GUI for logging" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3599 +msgid "" +"A question that comes up from time to time is about how to log to a GUI " +"application. The `Qt `_ framework is a popular cross-" +"platform UI framework with Python bindings using :pypi:`PySide2` " +"or :pypi:`PyQt5` libraries." +msgstr "" + +#: ../../howto/logging-cookbook.rst:3604 +msgid "" +"The following example shows how to log to a Qt GUI. This introduces a simple " +"``QtHandler`` class which takes a callable, which should be a slot in the " +"main thread that does GUI updates. A worker thread is also created to show " +"how you can log to the GUI from both the UI itself (via a button for manual " +"logging) as well as a worker thread doing work in the background (here, just " +"logging messages at random levels with random short delays in between)." +msgstr "" + +#: ../../howto/logging-cookbook.rst:3611 +msgid "" +"The worker thread is implemented using Qt's ``QThread`` class rather than " +"the :mod:`threading` module, as there are circumstances where one has to use " +"``QThread``, which offers better integration with other ``Qt`` components." +msgstr "" + +#: ../../howto/logging-cookbook.rst:3615 +msgid "" +"The code should work with recent releases of any of ``PySide6``, ``PyQt6``, " +"``PySide2`` or ``PyQt5``. You should be able to adapt the approach to " +"earlier versions of Qt. Please refer to the comments in the code snippet for " +"more detailed information." +msgstr "" + +#: ../../howto/logging-cookbook.rst:3620 +msgid "" +"import datetime\n" +"import logging\n" +"import random\n" +"import sys\n" +"import time\n" +"\n" +"# Deal with minor differences between different Qt packages\n" +"try:\n" +" from PySide6 import QtCore, QtGui, QtWidgets\n" +" Signal = QtCore.Signal\n" +" Slot = QtCore.Slot\n" +"except ImportError:\n" +" try:\n" +" from PyQt6 import QtCore, QtGui, QtWidgets\n" +" Signal = QtCore.pyqtSignal\n" +" Slot = QtCore.pyqtSlot\n" +" except ImportError:\n" +" try:\n" +" from PySide2 import QtCore, QtGui, QtWidgets\n" +" Signal = QtCore.Signal\n" +" Slot = QtCore.Slot\n" +" except ImportError:\n" +" from PyQt5 import QtCore, QtGui, QtWidgets\n" +" Signal = QtCore.pyqtSignal\n" +" Slot = QtCore.pyqtSlot\n" +"\n" +"logger = logging.getLogger(__name__)\n" +"\n" +"\n" +"#\n" +"# Signals need to be contained in a QObject or subclass in order to be " +"correctly\n" +"# initialized.\n" +"#\n" +"class Signaller(QtCore.QObject):\n" +" signal = Signal(str, logging.LogRecord)\n" +"\n" +"#\n" +"# Output to a Qt GUI is only supposed to happen on the main thread. So, " +"this\n" +"# handler is designed to take a slot function which is set up to run in the " +"main\n" +"# thread. In this example, the function takes a string argument which is a\n" +"# formatted log message, and the log record which generated it. The " +"formatted\n" +"# string is just a convenience - you could format a string for output any " +"way\n" +"# you like in the slot function itself.\n" +"#\n" +"# You specify the slot function to do whatever GUI updates you want. The " +"handler\n" +"# doesn't know or care about specific UI elements.\n" +"#\n" +"class QtHandler(logging.Handler):\n" +" def __init__(self, slotfunc, *args, **kwargs):\n" +" super().__init__(*args, **kwargs)\n" +" self.signaller = Signaller()\n" +" self.signaller.signal.connect(slotfunc)\n" +"\n" +" def emit(self, record):\n" +" s = self.format(record)\n" +" self.signaller.signal.emit(s, record)\n" +"\n" +"#\n" +"# This example uses QThreads, which means that the threads at the Python " +"level\n" +"# are named something like \"Dummy-1\". The function below gets the Qt name " +"of the\n" +"# current thread.\n" +"#\n" +"def ctname():\n" +" return QtCore.QThread.currentThread().objectName()\n" +"\n" +"\n" +"#\n" +"# Used to generate random levels for logging.\n" +"#\n" +"LEVELS = (logging.DEBUG, logging.INFO, logging.WARNING, logging.ERROR,\n" +" logging.CRITICAL)\n" +"\n" +"#\n" +"# This worker class represents work that is done in a thread separate to " +"the\n" +"# main thread. The way the thread is kicked off to do work is via a button " +"press\n" +"# that connects to a slot in the worker.\n" +"#\n" +"# Because the default threadName value in the LogRecord isn't much use, we " +"add\n" +"# a qThreadName which contains the QThread name as computed above, and pass " +"that\n" +"# value in an \"extra\" dictionary which is used to update the LogRecord " +"with the\n" +"# QThread name.\n" +"#\n" +"# This example worker just outputs messages sequentially, interspersed with\n" +"# random delays of the order of a few seconds.\n" +"#\n" +"class Worker(QtCore.QObject):\n" +" @Slot()\n" +" def start(self):\n" +" extra = {'qThreadName': ctname() }\n" +" logger.debug('Started work', extra=extra)\n" +" i = 1\n" +" # Let the thread run until interrupted. This allows reasonably " +"clean\n" +" # thread termination.\n" +" while not QtCore.QThread.currentThread().isInterruptionRequested():\n" +" delay = 0.5 + random.random() * 2\n" +" time.sleep(delay)\n" +" try:\n" +" if random.random() < 0.1:\n" +" raise ValueError('Exception raised: %d' % i)\n" +" else:\n" +" level = random.choice(LEVELS)\n" +" logger.log(level, 'Message after delay of %3.1f: %d', " +"delay, i, extra=extra)\n" +" except ValueError as e:\n" +" logger.exception('Failed: %s', e, extra=extra)\n" +" i += 1\n" +"\n" +"#\n" +"# Implement a simple UI for this cookbook example. This contains:\n" +"#\n" +"# * A read-only text edit window which holds formatted log messages\n" +"# * A button to start work and log stuff in a separate thread\n" +"# * A button to log something from the main thread\n" +"# * A button to clear the log window\n" +"#\n" +"class Window(QtWidgets.QWidget):\n" +"\n" +" COLORS = {\n" +" logging.DEBUG: 'black',\n" +" logging.INFO: 'blue',\n" +" logging.WARNING: 'orange',\n" +" logging.ERROR: 'red',\n" +" logging.CRITICAL: 'purple',\n" +" }\n" +"\n" +" def __init__(self, app):\n" +" super().__init__()\n" +" self.app = app\n" +" self.textedit = te = QtWidgets.QPlainTextEdit(self)\n" +" # Set whatever the default monospace font is for the platform\n" +" f = QtGui.QFont('nosuchfont')\n" +" if hasattr(f, 'Monospace'):\n" +" f.setStyleHint(f.Monospace)\n" +" else:\n" +" f.setStyleHint(f.StyleHint.Monospace) # for Qt6\n" +" te.setFont(f)\n" +" te.setReadOnly(True)\n" +" PB = QtWidgets.QPushButton\n" +" self.work_button = PB('Start background work', self)\n" +" self.log_button = PB('Log a message at a random level', self)\n" +" self.clear_button = PB('Clear log window', self)\n" +" self.handler = h = QtHandler(self.update_status)\n" +" # Remember to use qThreadName rather than threadName in the format " +"string.\n" +" fs = '%(asctime)s %(qThreadName)-12s %(levelname)-8s %(message)s'\n" +" formatter = logging.Formatter(fs)\n" +" h.setFormatter(formatter)\n" +" logger.addHandler(h)\n" +" # Set up to terminate the QThread when we exit\n" +" app.aboutToQuit.connect(self.force_quit)\n" +"\n" +" # Lay out all the widgets\n" +" layout = QtWidgets.QVBoxLayout(self)\n" +" layout.addWidget(te)\n" +" layout.addWidget(self.work_button)\n" +" layout.addWidget(self.log_button)\n" +" layout.addWidget(self.clear_button)\n" +" self.setFixedSize(900, 400)\n" +"\n" +" # Connect the non-worker slots and signals\n" +" self.log_button.clicked.connect(self.manual_update)\n" +" self.clear_button.clicked.connect(self.clear_display)\n" +"\n" +" # Start a new worker thread and connect the slots for the worker\n" +" self.start_thread()\n" +" self.work_button.clicked.connect(self.worker.start)\n" +" # Once started, the button should be disabled\n" +" self.work_button.clicked.connect(lambda : " +"self.work_button.setEnabled(False))\n" +"\n" +" def start_thread(self):\n" +" self.worker = Worker()\n" +" self.worker_thread = QtCore.QThread()\n" +" self.worker.setObjectName('Worker')\n" +" self.worker_thread.setObjectName('WorkerThread') # for qThreadName\n" +" self.worker.moveToThread(self.worker_thread)\n" +" # This will start an event loop in the worker thread\n" +" self.worker_thread.start()\n" +"\n" +" def kill_thread(self):\n" +" # Just tell the worker to stop, then tell it to quit and wait for " +"that\n" +" # to happen\n" +" self.worker_thread.requestInterruption()\n" +" if self.worker_thread.isRunning():\n" +" self.worker_thread.quit()\n" +" self.worker_thread.wait()\n" +" else:\n" +" print('worker has already exited.')\n" +"\n" +" def force_quit(self):\n" +" # For use when the window is closed\n" +" if self.worker_thread.isRunning():\n" +" self.kill_thread()\n" +"\n" +" # The functions below update the UI and run in the main thread because\n" +" # that's where the slots are set up\n" +"\n" +" @Slot(str, logging.LogRecord)\n" +" def update_status(self, status, record):\n" +" color = self.COLORS.get(record.levelno, 'black')\n" +" s = '
%s
' % (color, status)\n" +" self.textedit.appendHtml(s)\n" +"\n" +" @Slot()\n" +" def manual_update(self):\n" +" # This function uses the formatted message passed in, but also uses\n" +" # information from the record to format the message in an " +"appropriate\n" +" # color according to its severity (level).\n" +" level = random.choice(LEVELS)\n" +" extra = {'qThreadName': ctname() }\n" +" logger.log(level, 'Manually logged!', extra=extra)\n" +"\n" +" @Slot()\n" +" def clear_display(self):\n" +" self.textedit.clear()\n" +"\n" +"\n" +"def main():\n" +" QtCore.QThread.currentThread().setObjectName('MainThread')\n" +" logging.getLogger().setLevel(logging.DEBUG)\n" +" app = QtWidgets.QApplication(sys.argv)\n" +" example = Window(app)\n" +" example.show()\n" +" if hasattr(app, 'exec'):\n" +" rc = app.exec()\n" +" else:\n" +" rc = app.exec_()\n" +" sys.exit(rc)\n" +"\n" +"if __name__=='__main__':\n" +" main()" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3852 +msgid "Logging to syslog with RFC5424 support" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3854 +msgid "" +"Although :rfc:`5424` dates from 2009, most syslog servers are configured by " +"default to use the older :rfc:`3164`, which hails from 2001. When " +"``logging`` was added to Python in 2003, it supported the earlier (and only " +"existing) protocol at the time. Since RFC5424 came out, as there has not " +"been widespread deployment of it in syslog servers, " +"the :class:`~logging.handlers.SysLogHandler` functionality has not been " +"updated." +msgstr "" + +#: ../../howto/logging-cookbook.rst:3861 +msgid "" +"RFC 5424 contains some useful features such as support for structured data, " +"and if you need to be able to log to a syslog server with support for it, " +"you can do so with a subclassed handler which looks something like this::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3865 +msgid "" +"import datetime\n" +"import logging.handlers\n" +"import re\n" +"import socket\n" +"import time\n" +"\n" +"class SysLogHandler5424(logging.handlers.SysLogHandler):\n" +"\n" +" tz_offset = re.compile(r'([+-]\\d{2})(\\d{2})$')\n" +" escaped = re.compile(r'([\\]\"\\\\])')\n" +"\n" +" def __init__(self, *args, **kwargs):\n" +" self.msgid = kwargs.pop('msgid', None)\n" +" self.appname = kwargs.pop('appname', None)\n" +" super().__init__(*args, **kwargs)\n" +"\n" +" def format(self, record):\n" +" version = 1\n" +" asctime = " +"datetime.datetime.fromtimestamp(record.created).isoformat()\n" +" m = self.tz_offset.match(time.strftime('%z'))\n" +" has_offset = False\n" +" if m and time.timezone:\n" +" hrs, mins = m.groups()\n" +" if int(hrs) or int(mins):\n" +" has_offset = True\n" +" if not has_offset:\n" +" asctime += 'Z'\n" +" else:\n" +" asctime += f'{hrs}:{mins}'\n" +" try:\n" +" hostname = socket.gethostname()\n" +" except Exception:\n" +" hostname = '-'\n" +" appname = self.appname or '-'\n" +" procid = record.process\n" +" msgid = '-'\n" +" msg = super().format(record)\n" +" sdata = '-'\n" +" if hasattr(record, 'structured_data'):\n" +" sd = record.structured_data\n" +" # This should be a dict where the keys are SD-ID and the value " +"is a\n" +" # dict mapping PARAM-NAME to PARAM-VALUE (refer to the RFC for " +"what these\n" +" # mean)\n" +" # There's no error checking here - it's purely for illustration, " +"and you\n" +" # can adapt this code for use in production environments\n" +" parts = []\n" +"\n" +" def replacer(m):\n" +" g = m.groups()\n" +" return '\\\\' + g[0]\n" +"\n" +" for sdid, dv in sd.items():\n" +" part = f'[{sdid}'\n" +" for k, v in dv.items():\n" +" s = str(v)\n" +" s = self.escaped.sub(replacer, s)\n" +" part += f' {k}=\"{s}\"'\n" +" part += ']'\n" +" parts.append(part)\n" +" sdata = ''.join(parts)\n" +" return f'{version} {asctime} {hostname} {appname} {procid} {msgid} " +"{sdata} {msg}'" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3927 +msgid "" +"You'll need to be familiar with RFC 5424 to fully understand the above code, " +"and it may be that you have slightly different needs (e.g. for how you pass " +"structural data to the log). Nevertheless, the above should be adaptable to " +"your speciric needs. With the above handler, you'd pass structured data " +"using something like this::" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3932 +msgid "" +"sd = {\n" +" 'foo@12345': {'bar': 'baz', 'baz': 'bozz', 'fizz': r'buzz'},\n" +" 'foo@54321': {'rab': 'baz', 'zab': 'bozz', 'zzif': r'buzz'}\n" +"}\n" +"extra = {'structured_data': sd}\n" +"i = 1\n" +"logger.debug('Message %d', i, extra=extra)" +msgstr "" +"sd = {\n" +" 'foo@12345': {'bar': 'baz', 'baz': 'bozz', 'fizz': r'buzz'},\n" +" 'foo@54321': {'rab': 'baz', 'zab': 'bozz', 'zzif': r'buzz'}\n" +"}\n" +"extra = {'structured_data': sd}\n" +"i = 1\n" +"logger.debug('Message %d', i, extra=extra)" + +#: ../../howto/logging-cookbook.rst:3941 +msgid "How to treat a logger like an output stream" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3943 +msgid "" +"Sometimes, you need to interface to a third-party API which expects a file-" +"like object to write to, but you want to direct the API's output to a " +"logger. You can do this using a class which wraps a logger with a file-like " +"API. Here's a short script illustrating such a class:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3948 +msgid "" +"import logging\n" +"\n" +"class LoggerWriter:\n" +" def __init__(self, logger, level):\n" +" self.logger = logger\n" +" self.level = level\n" +"\n" +" def write(self, message):\n" +" if message != '\\n': # avoid printing bare newlines, if you like\n" +" self.logger.log(self.level, message)\n" +"\n" +" def flush(self):\n" +" # doesn't actually do anything, but might be expected of a file-" +"like\n" +" # object - so optional depending on your situation\n" +" pass\n" +"\n" +" def close(self):\n" +" # doesn't actually do anything, but might be expected of a file-" +"like\n" +" # object - so optional depending on your situation. You might want\n" +" # to set a flag so that later calls to write raise an exception\n" +" pass\n" +"\n" +"def main():\n" +" logging.basicConfig(level=logging.DEBUG)\n" +" logger = logging.getLogger('demo')\n" +" info_fp = LoggerWriter(logger, logging.INFO)\n" +" debug_fp = LoggerWriter(logger, logging.DEBUG)\n" +" print('An INFO message', file=info_fp)\n" +" print('A DEBUG message', file=debug_fp)\n" +"\n" +"if __name__ == \"__main__\":\n" +" main()" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3983 +msgid "When this script is run, it prints" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3985 +msgid "" +"INFO:demo:An INFO message\n" +"DEBUG:demo:A DEBUG message" +msgstr "" +"INFO:demo:An INFO message\n" +"DEBUG:demo:A DEBUG message" + +#: ../../howto/logging-cookbook.rst:3990 +msgid "" +"You could also use ``LoggerWriter`` to redirect ``sys.stdout`` and " +"``sys.stderr`` by doing something like this:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3993 +msgid "" +"import sys\n" +"\n" +"sys.stdout = LoggerWriter(logger, logging.INFO)\n" +"sys.stderr = LoggerWriter(logger, logging.WARNING)" +msgstr "" +"import sys\n" +"\n" +"sys.stdout = LoggerWriter(logger, logging.INFO)\n" +"sys.stderr = LoggerWriter(logger, logging.WARNING)" + +#: ../../howto/logging-cookbook.rst:4000 +msgid "" +"You should do this *after* configuring logging for your needs. In the above " +"example, the :func:`~logging.basicConfig` call does this (using the " +"``sys.stderr`` value *before* it is overwritten by a ``LoggerWriter`` " +"instance). Then, you'd get this kind of result:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:4005 +msgid "" +">>> print('Foo')\n" +"INFO:demo:Foo\n" +">>> print('Bar', file=sys.stderr)\n" +"WARNING:demo:Bar\n" +">>>" +msgstr "" +">>> print('Foo')\n" +"INFO:demo:Foo\n" +">>> print('Bar', file=sys.stderr)\n" +"WARNING:demo:Bar\n" +">>>" + +#: ../../howto/logging-cookbook.rst:4013 +msgid "" +"Of course, the examples above show output according to the format used " +"by :func:`~logging.basicConfig`, but you can use a different formatter when " +"you configure logging." +msgstr "" + +#: ../../howto/logging-cookbook.rst:4017 +msgid "" +"Note that with the above scheme, you are somewhat at the mercy of buffering " +"and the sequence of write calls which you are intercepting. For example, " +"with the definition of ``LoggerWriter`` above, if you have the snippet" +msgstr "" + +#: ../../howto/logging-cookbook.rst:4021 +msgid "" +"sys.stderr = LoggerWriter(logger, logging.WARNING)\n" +"1 / 0" +msgstr "" +"sys.stderr = LoggerWriter(logger, logging.WARNING)\n" +"1 / 0" + +#: ../../howto/logging-cookbook.rst:4026 +msgid "then running the script results in" +msgstr "" + +#: ../../howto/logging-cookbook.rst:4028 +msgid "" +"WARNING:demo:Traceback (most recent call last):\n" +"\n" +"WARNING:demo: File \"/home/runner/cookbook-loggerwriter/test.py\", line 53, " +"in \n" +"\n" +"WARNING:demo:\n" +"WARNING:demo:main()\n" +"WARNING:demo: File \"/home/runner/cookbook-loggerwriter/test.py\", line 49, " +"in main\n" +"\n" +"WARNING:demo:\n" +"WARNING:demo:1 / 0\n" +"WARNING:demo:ZeroDivisionError\n" +"WARNING:demo::\n" +"WARNING:demo:division by zero" +msgstr "" +"WARNING:demo:Traceback (most recent call last):\n" +"\n" +"WARNING:demo: File \"/home/runner/cookbook-loggerwriter/test.py\", line 53, " +"in \n" +"\n" +"WARNING:demo:\n" +"WARNING:demo:main()\n" +"WARNING:demo: File \"/home/runner/cookbook-loggerwriter/test.py\", line 49, " +"in main\n" +"\n" +"WARNING:demo:\n" +"WARNING:demo:1 / 0\n" +"WARNING:demo:ZeroDivisionError\n" +"WARNING:demo::\n" +"WARNING:demo:division by zero" + +#: ../../howto/logging-cookbook.rst:4044 +msgid "" +"As you can see, this output isn't ideal. That's because the underlying code " +"which writes to ``sys.stderr`` makes multiple writes, each of which results " +"in a separate logged line (for example, the last three lines above). To get " +"around this problem, you need to buffer things and only output log lines " +"when newlines are seen. Let's use a slightly better implementation of " +"``LoggerWriter``:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:4050 +msgid "" +"class BufferingLoggerWriter(LoggerWriter):\n" +" def __init__(self, logger, level):\n" +" super().__init__(logger, level)\n" +" self.buffer = ''\n" +"\n" +" def write(self, message):\n" +" if '\\n' not in message:\n" +" self.buffer += message\n" +" else:\n" +" parts = message.split('\\n')\n" +" if self.buffer:\n" +" s = self.buffer + parts.pop(0)\n" +" self.logger.log(self.level, s)\n" +" self.buffer = parts.pop()\n" +" for part in parts:\n" +" self.logger.log(self.level, part)" +msgstr "" +"class BufferingLoggerWriter(LoggerWriter):\n" +" def __init__(self, logger, level):\n" +" super().__init__(logger, level)\n" +" self.buffer = ''\n" +"\n" +" def write(self, message):\n" +" if '\\n' not in message:\n" +" self.buffer += message\n" +" else:\n" +" parts = message.split('\\n')\n" +" if self.buffer:\n" +" s = self.buffer + parts.pop(0)\n" +" self.logger.log(self.level, s)\n" +" self.buffer = parts.pop()\n" +" for part in parts:\n" +" self.logger.log(self.level, part)" + +#: ../../howto/logging-cookbook.rst:4069 +msgid "" +"This just buffers up stuff until a newline is seen, and then logs complete " +"lines. With this approach, you get better output:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:4072 +msgid "" +"WARNING:demo:Traceback (most recent call last):\n" +"WARNING:demo: File \"/home/runner/cookbook-loggerwriter/main.py\", line 55, " +"in \n" +"WARNING:demo: main()\n" +"WARNING:demo: File \"/home/runner/cookbook-loggerwriter/main.py\", line 52, " +"in main\n" +"WARNING:demo: 1/0\n" +"WARNING:demo:ZeroDivisionError: division by zero" +msgstr "" +"WARNING:demo:Traceback (most recent call last):\n" +"WARNING:demo: File \"/home/runner/cookbook-loggerwriter/main.py\", line 55, " +"in \n" +"WARNING:demo: main()\n" +"WARNING:demo: File \"/home/runner/cookbook-loggerwriter/main.py\", line 52, " +"in main\n" +"WARNING:demo: 1/0\n" +"WARNING:demo:ZeroDivisionError: division by zero" + +#: ../../howto/logging-cookbook.rst:4082 +msgid "How to uniformly handle newlines in logging output" +msgstr "" + +#: ../../howto/logging-cookbook.rst:4084 +msgid "" +"Usually, messages that are logged (say to console or file) consist of a " +"single line of text. However, sometimes there is a need to handle messages " +"with multiple lines - whether because a logging format string contains " +"newlines, or logged data contains newlines. If you want to handle such " +"messages uniformly, so that each line in the logged message appears " +"uniformly formatted as if it was logged separately, you can do this using a " +"handler mixin, as in the following snippet:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:4092 +msgid "" +"# Assume this is in a module mymixins.py\n" +"import copy\n" +"\n" +"class MultilineMixin:\n" +" def emit(self, record):\n" +" s = record.getMessage()\n" +" if '\\n' not in s:\n" +" super().emit(record)\n" +" else:\n" +" lines = s.splitlines()\n" +" rec = copy.copy(record)\n" +" rec.args = None\n" +" for line in lines:\n" +" rec.msg = line\n" +" super().emit(rec)" +msgstr "" + +#: ../../howto/logging-cookbook.rst:4110 +msgid "You can use the mixin as in the following script:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:4112 +msgid "" +"import logging\n" +"\n" +"from mymixins import MultilineMixin\n" +"\n" +"logger = logging.getLogger(__name__)\n" +"\n" +"class StreamHandler(MultilineMixin, logging.StreamHandler):\n" +" pass\n" +"\n" +"if __name__ == '__main__':\n" +" logging.basicConfig(level=logging.DEBUG, format='%(asctime)s %" +"(levelname)-9s %(message)s',\n" +" handlers = [StreamHandler()])\n" +" logger.debug('Single line')\n" +" logger.debug('Multiple lines:\\nfool me once ...')\n" +" logger.debug('Another single line')\n" +" logger.debug('Multiple lines:\\n%s', 'fool me ...\\ncan\\'t get fooled " +"again')" +msgstr "" +"import logging\n" +"\n" +"from mymixins import MultilineMixin\n" +"\n" +"logger = logging.getLogger(__name__)\n" +"\n" +"class StreamHandler(MultilineMixin, logging.StreamHandler):\n" +" pass\n" +"\n" +"if __name__ == '__main__':\n" +" logging.basicConfig(level=logging.DEBUG, format='%(asctime)s %" +"(levelname)-9s %(message)s',\n" +" handlers = [StreamHandler()])\n" +" logger.debug('Single line')\n" +" logger.debug('Multiple lines:\\nfool me once ...')\n" +" logger.debug('Another single line')\n" +" logger.debug('Multiple lines:\\n%s', 'fool me ...\\ncan\\'t get fooled " +"again')" + +#: ../../howto/logging-cookbook.rst:4131 +msgid "The script, when run, prints something like:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:4133 +msgid "" +"2025-07-02 13:54:47,234 DEBUG Single line\n" +"2025-07-02 13:54:47,234 DEBUG Multiple lines:\n" +"2025-07-02 13:54:47,234 DEBUG fool me once ...\n" +"2025-07-02 13:54:47,234 DEBUG Another single line\n" +"2025-07-02 13:54:47,234 DEBUG Multiple lines:\n" +"2025-07-02 13:54:47,234 DEBUG fool me ...\n" +"2025-07-02 13:54:47,234 DEBUG can't get fooled again" +msgstr "" +"2025-07-02 13:54:47,234 DEBUG Single line\n" +"2025-07-02 13:54:47,234 DEBUG Multiple lines:\n" +"2025-07-02 13:54:47,234 DEBUG fool me once ...\n" +"2025-07-02 13:54:47,234 DEBUG Another single line\n" +"2025-07-02 13:54:47,234 DEBUG Multiple lines:\n" +"2025-07-02 13:54:47,234 DEBUG fool me ...\n" +"2025-07-02 13:54:47,234 DEBUG can't get fooled again" + +#: ../../howto/logging-cookbook.rst:4143 +msgid "" +"If, on the other hand, you are concerned about `log injection `_, you can use a formatter " +"which escapes newlines, as per the following example:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:4147 +msgid "" +"import logging\n" +"\n" +"logger = logging.getLogger(__name__)\n" +"\n" +"class EscapingFormatter(logging.Formatter):\n" +" def format(self, record):\n" +" s = super().format(record)\n" +" return s.replace('\\n', r'\\n')\n" +"\n" +"if __name__ == '__main__':\n" +" h = logging.StreamHandler()\n" +" h.setFormatter(EscapingFormatter('%(asctime)s %(levelname)-9s %" +"(message)s'))\n" +" logging.basicConfig(level=logging.DEBUG, handlers = [h])\n" +" logger.debug('Single line')\n" +" logger.debug('Multiple lines:\\nfool me once ...')\n" +" logger.debug('Another single line')\n" +" logger.debug('Multiple lines:\\n%s', 'fool me ...\\ncan\\'t get fooled " +"again')" +msgstr "" +"import logging\n" +"\n" +"logger = logging.getLogger(__name__)\n" +"\n" +"class EscapingFormatter(logging.Formatter):\n" +" def format(self, record):\n" +" s = super().format(record)\n" +" return s.replace('\\n', r'\\n')\n" +"\n" +"if __name__ == '__main__':\n" +" h = logging.StreamHandler()\n" +" h.setFormatter(EscapingFormatter('%(asctime)s %(levelname)-9s %" +"(message)s'))\n" +" logging.basicConfig(level=logging.DEBUG, handlers = [h])\n" +" logger.debug('Single line')\n" +" logger.debug('Multiple lines:\\nfool me once ...')\n" +" logger.debug('Another single line')\n" +" logger.debug('Multiple lines:\\n%s', 'fool me ...\\ncan\\'t get fooled " +"again')" + +#: ../../howto/logging-cookbook.rst:4167 +msgid "" +"You can, of course, use whatever escaping scheme makes the most sense for " +"you. The script, when run, should produce output like this:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:4170 +msgid "" +"2025-07-09 06:47:33,783 DEBUG Single line\n" +"2025-07-09 06:47:33,783 DEBUG Multiple lines:\\nfool me once ...\n" +"2025-07-09 06:47:33,783 DEBUG Another single line\n" +"2025-07-09 06:47:33,783 DEBUG Multiple lines:\\nfool me ...\\ncan't get " +"fooled again" +msgstr "" +"2025-07-09 06:47:33,783 DEBUG Single line\n" +"2025-07-09 06:47:33,783 DEBUG Multiple lines:\\nfool me once ...\n" +"2025-07-09 06:47:33,783 DEBUG Another single line\n" +"2025-07-09 06:47:33,783 DEBUG Multiple lines:\\nfool me ...\\ncan't get " +"fooled again" + +#: ../../howto/logging-cookbook.rst:4177 +msgid "" +"Escaping behaviour can't be the stdlib default , as it would break backwards " +"compatibility." +msgstr "" + +#: ../../howto/logging-cookbook.rst:4183 +msgid "Patterns to avoid" +msgstr "" + +#: ../../howto/logging-cookbook.rst:4185 +msgid "" +"Although the preceding sections have described ways of doing things you " +"might need to do or deal with, it is worth mentioning some usage patterns " +"which are *unhelpful*, and which should therefore be avoided in most cases. " +"The following sections are in no particular order." +msgstr "" + +#: ../../howto/logging-cookbook.rst:4191 +msgid "Opening the same log file multiple times" +msgstr "" + +#: ../../howto/logging-cookbook.rst:4193 +msgid "" +"On Windows, you will generally not be able to open the same file multiple " +"times as this will lead to a \"file is in use by another process\" error. " +"However, on POSIX platforms you'll not get any errors if you open the same " +"file multiple times. This could be done accidentally, for example by:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:4198 +msgid "" +"Adding a file handler more than once which references the same file (e.g. by " +"a copy/paste/forget-to-change error)." +msgstr "" + +#: ../../howto/logging-cookbook.rst:4201 +msgid "" +"Opening two files that look different, as they have different names, but are " +"the same because one is a symbolic link to the other." +msgstr "" + +#: ../../howto/logging-cookbook.rst:4204 +msgid "" +"Forking a process, following which both parent and child have a reference to " +"the same file. This might be through use of the :mod:`multiprocessing` " +"module, for example." +msgstr "" + +#: ../../howto/logging-cookbook.rst:4208 +msgid "" +"Opening a file multiple times might *appear* to work most of the time, but " +"can lead to a number of problems in practice:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:4211 +msgid "" +"Logging output can be garbled because multiple threads or processes try to " +"write to the same file. Although logging guards against concurrent use of " +"the same handler instance by multiple threads, there is no such protection " +"if concurrent writes are attempted by two different threads using two " +"different handler instances which happen to point to the same file." +msgstr "" + +#: ../../howto/logging-cookbook.rst:4217 +msgid "" +"An attempt to delete a file (e.g. during file rotation) silently fails, " +"because there is another reference pointing to it. This can lead to " +"confusion and wasted debugging time - log entries end up in unexpected " +"places, or are lost altogether. Or a file that was supposed to be moved " +"remains in place, and grows in size unexpectedly despite size-based rotation " +"being supposedly in place." +msgstr "" + +#: ../../howto/logging-cookbook.rst:4224 +msgid "" +"Use the techniques outlined in :ref:`multiple-processes` to circumvent such " +"issues." +msgstr "" + +#: ../../howto/logging-cookbook.rst:4228 +msgid "Using loggers as attributes in a class or passing them as parameters" +msgstr "" + +#: ../../howto/logging-cookbook.rst:4230 +msgid "" +"While there might be unusual cases where you'll need to do this, in general " +"there is no point because loggers are singletons. Code can always access a " +"given logger instance by name using ``logging.getLogger(name)``, so passing " +"instances around and holding them as instance attributes is pointless. Note " +"that in other languages such as Java and C#, loggers are often static class " +"attributes. However, this pattern doesn't make sense in Python, where the " +"module (and not the class) is the unit of software decomposition." +msgstr "" + +#: ../../howto/logging-cookbook.rst:4239 +msgid "" +"Adding handlers other than :class:`~logging.NullHandler` to a logger in a " +"library" +msgstr "" + +#: ../../howto/logging-cookbook.rst:4241 +msgid "" +"Configuring logging by adding handlers, formatters and filters is the " +"responsibility of the application developer, not the library developer. If " +"you are maintaining a library, ensure that you don't add handlers to any of " +"your loggers other than a :class:`~logging.NullHandler` instance." +msgstr "" + +#: ../../howto/logging-cookbook.rst:4247 +msgid "Creating a lot of loggers" +msgstr "" + +#: ../../howto/logging-cookbook.rst:4249 +msgid "" +"Loggers are singletons that are never freed during a script execution, and " +"so creating lots of loggers will use up memory which can't then be freed. " +"Rather than create a logger per e.g. file processed or network connection " +"made, use the :ref:`existing mechanisms ` for passing " +"contextual information into your logs and restrict the loggers created to " +"those describing areas within your application (generally modules, but " +"occasionally slightly more fine-grained than that)." +msgstr "" + +#: ../../howto/logging-cookbook.rst:4260 +msgid "Other resources" +msgstr "其他資源" + +#: ../../howto/logging-cookbook.rst:4264 +msgid "Module :mod:`logging`" +msgstr ":mod:`logging` 模組" + +#: ../../howto/logging-cookbook.rst:4265 +msgid "API reference for the logging module." +msgstr "" + +#: ../../howto/logging-cookbook.rst:4267 +msgid "Module :mod:`logging.config`" +msgstr ":mod:`logging.config` 模組" + +#: ../../howto/logging-cookbook.rst:4268 +msgid "Configuration API for the logging module." +msgstr "" + +#: ../../howto/logging-cookbook.rst:4270 +msgid "Module :mod:`logging.handlers`" +msgstr ":mod:`logging.handlers` 模組" + +#: ../../howto/logging-cookbook.rst:4271 +msgid "Useful handlers included with the logging module." +msgstr "" + +#: ../../howto/logging-cookbook.rst:4273 +msgid ":ref:`Basic Tutorial `" +msgstr ":ref:`基礎教學 `" + +#: ../../howto/logging-cookbook.rst:4275 +msgid ":ref:`Advanced Tutorial `" +msgstr ":ref:`進階教學 `" diff --git a/howto/logging.po b/howto/logging.po index 9337a55f28..702bd15048 100644 --- a/howto/logging.po +++ b/howto/logging.po @@ -1,1743 +1,1743 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# 文俊 高 , 2016 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: 2018-05-23 14:36+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" - -#: ../../howto/logging.rst:5 -msgid "Logging HOWTO" -msgstr "如何使用 Logging 模組" - -#: ../../howto/logging.rst:0 -msgid "Author" -msgstr "作者" - -#: ../../howto/logging.rst:7 -msgid "Vinay Sajip " -msgstr "Vinay Sajip " - -#: ../../howto/logging.rst:13 -msgid "" -"This page contains tutorial information. For links to reference information " -"and a logging cookbook, please see :ref:`tutorial-ref-links`." -msgstr "" - -#: ../../howto/logging.rst:17 -msgid "Basic Logging Tutorial" -msgstr "基礎 Logging 指南" - -#: ../../howto/logging.rst:19 -msgid "" -"Logging is a means of tracking events that happen when some software runs. " -"The software's developer adds logging calls to their code to indicate that " -"certain events have occurred. An event is described by a descriptive message " -"which can optionally contain variable data (i.e. data that is potentially " -"different for each occurrence of the event). Events also have an importance " -"which the developer ascribes to the event; the importance can also be called " -"the *level* or *severity*." -msgstr "" -"軟體執行時，追蹤有什麼事件發生的動作稱為 Logging。軟體開發者會使用 Logging 這" -"樣的機制是因為想知道在運行過程中是否有特定的事件發生。事件會被一段訊息所描" -"述。這段訊息可能包含一些因為此事件發生而改變的資料。開發者也可以指派事件的重" -"要程度，重要程度有時候也會被稱作 *程度* 或是 *嚴重性* 。" - -#: ../../howto/logging.rst:28 -msgid "When to use logging" -msgstr "什麼時候使用 logging" - -#: ../../howto/logging.rst:30 -msgid "" -"You can access logging functionality by creating a logger via ``logger = " -"getLogger(__name__)``, and then calling the " -"logger's :meth:`~Logger.debug`, :meth:`~Logger.info`, :meth:`~Logger.warning`, :meth:`~Logger.error` " -"and :meth:`~Logger.critical` methods. To determine when to use logging, and " -"to see which logger methods to use when, see the table below. It states, for " -"each of a set of common tasks, the best tool to use for that task." -msgstr "" - -#: ../../howto/logging.rst:38 -msgid "Task you want to perform" -msgstr "" - -#: ../../howto/logging.rst:38 -msgid "The best tool for the task" -msgstr "" - -#: ../../howto/logging.rst:40 -msgid "" -"Display console output for ordinary usage of a command line script or program" -msgstr "" - -#: ../../howto/logging.rst:40 -msgid ":func:`print`" -msgstr ":func:`print`" - -#: ../../howto/logging.rst:44 -msgid "" -"Report events that occur during normal operation of a program (e.g. for " -"status monitoring or fault investigation)" -msgstr "" - -#: ../../howto/logging.rst:44 -msgid "" -"A logger's :meth:`~Logger.info` (or :meth:`~Logger.debug` method for very " -"detailed output for diagnostic purposes)" -msgstr "" - -#: ../../howto/logging.rst:49 -msgid "Issue a warning regarding a particular runtime event" -msgstr "" - -#: ../../howto/logging.rst:49 -msgid "" -":func:`warnings.warn` in library code if the issue is avoidable and the " -"client application should be modified to eliminate the warning" -msgstr "" - -#: ../../howto/logging.rst:54 -msgid "" -"A logger's :meth:`~Logger.warning` method if there is nothing the client " -"application can do about the situation, but the event should still be noted" -msgstr "" - -#: ../../howto/logging.rst:60 -msgid "Report an error regarding a particular runtime event" -msgstr "" - -#: ../../howto/logging.rst:60 -msgid "Raise an exception" -msgstr "引發一個例外" - -#: ../../howto/logging.rst:63 -msgid "" -"Report suppression of an error without raising an exception (e.g. error " -"handler in a long-running server process)" -msgstr "" - -#: ../../howto/logging.rst:63 -msgid "" -"A logger's :meth:`~Logger.error`, :meth:`~Logger.exception` " -"or :meth:`~Logger.critical` method as appropriate for the specific error and " -"application domain" -msgstr "" - -#: ../../howto/logging.rst:70 -msgid "" -"The logger methods are named after the level or severity of the events they " -"are used to track. The standard levels and their applicability are described " -"below (in increasing order of severity):" -msgstr "" - -#: ../../howto/logging.rst:77 ../../howto/logging.rst:875 -msgid "Level" -msgstr "" - -#: ../../howto/logging.rst:77 -msgid "When it's used" -msgstr "" - -#: ../../howto/logging.rst:79 ../../howto/logging.rst:885 -msgid "``DEBUG``" -msgstr "``DEBUG``" - -#: ../../howto/logging.rst:79 -msgid "" -"Detailed information, typically of interest only when diagnosing problems." -msgstr "" - -#: ../../howto/logging.rst:82 ../../howto/logging.rst:883 -msgid "``INFO``" -msgstr "``INFO``" - -#: ../../howto/logging.rst:82 -msgid "Confirmation that things are working as expected." -msgstr "" - -#: ../../howto/logging.rst:85 ../../howto/logging.rst:881 -msgid "``WARNING``" -msgstr "``WARNING``" - -#: ../../howto/logging.rst:85 -msgid "" -"An indication that something unexpected happened, or indicative of some " -"problem in the near future (e.g. 'disk space low'). The software is still " -"working as expected." -msgstr "" - -#: ../../howto/logging.rst:90 ../../howto/logging.rst:879 -msgid "``ERROR``" -msgstr "``ERROR``" - -#: ../../howto/logging.rst:90 -msgid "" -"Due to a more serious problem, the software has not been able to perform " -"some function." -msgstr "" - -#: ../../howto/logging.rst:93 ../../howto/logging.rst:877 -msgid "``CRITICAL``" -msgstr "``CRITICAL``" - -#: ../../howto/logging.rst:93 -msgid "" -"A serious error, indicating that the program itself may be unable to " -"continue running." -msgstr "" - -#: ../../howto/logging.rst:97 -msgid "" -"The default level is ``WARNING``, which means that only events of this " -"severity and higher will be tracked, unless the logging package is " -"configured to do otherwise." -msgstr "" - -#: ../../howto/logging.rst:100 -msgid "" -"Events that are tracked can be handled in different ways. The simplest way " -"of handling tracked events is to print them to the console. Another common " -"way is to write them to a disk file." -msgstr "" - -#: ../../howto/logging.rst:108 -msgid "A simple example" -msgstr "一個簡單範例" - -#: ../../howto/logging.rst:110 -msgid "A very simple example is::" -msgstr "一個非常簡單的例子是： ::" - -#: ../../howto/logging.rst:112 -msgid "" -"import logging\n" -"logging.warning('Watch out!') # will print a message to the console\n" -"logging.info('I told you so') # will not print anything" -msgstr "" -"import logging\n" -"logging.warning('Watch out!') # 將會印出訊息至控制台\n" -"logging.info('I told you so') # 不會印出任何東西" - -#: ../../howto/logging.rst:116 -msgid "If you type these lines into a script and run it, you'll see:" -msgstr "" - -#: ../../howto/logging.rst:118 -msgid "WARNING:root:Watch out!" -msgstr "WARNING:root:Watch out!" - -#: ../../howto/logging.rst:122 -msgid "" -"printed out on the console. The ``INFO`` message doesn't appear because the " -"default level is ``WARNING``. The printed message includes the indication of " -"the level and the description of the event provided in the logging call, " -"i.e. 'Watch out!'. The actual output can be formatted quite flexibly if you " -"need that; formatting options will also be explained later." -msgstr "" - -#: ../../howto/logging.rst:128 -msgid "" -"Notice that in this example, we use functions directly on the ``logging`` " -"module, like ``logging.debug``, rather than creating a logger and calling " -"functions on it. These functions operate on the root logger, but can be " -"useful as they will call :func:`~logging.basicConfig` for you if it has not " -"been called yet, like in this example. In larger programs you'll usually " -"want to control the logging configuration explicitly however - so for that " -"reason as well as others, it's better to create loggers and call their " -"methods." -msgstr "" - -#: ../../howto/logging.rst:137 -msgid "Logging to a file" -msgstr "" - -#: ../../howto/logging.rst:139 -msgid "" -"A very common situation is that of recording logging events in a file, so " -"let's look at that next. Be sure to try the following in a newly started " -"Python interpreter, and don't just continue from the session described " -"above::" -msgstr "" - -#: ../../howto/logging.rst:143 -msgid "" -"import logging\n" -"logger = logging.getLogger(__name__)\n" -"logging.basicConfig(filename='example.log', encoding='utf-8', " -"level=logging.DEBUG)\n" -"logger.debug('This message should go to the log file')\n" -"logger.info('So should this')\n" -"logger.warning('And this, too')\n" -"logger.error('And non-ASCII stuff, too, like Øresund and Malmö')" -msgstr "" -"import logging\n" -"logger = logging.getLogger(__name__)\n" -"logging.basicConfig(filename='example.log', encoding='utf-8', " -"level=logging.DEBUG)\n" -"logger.debug('This message should go to the log file')\n" -"logger.info('So should this')\n" -"logger.warning('And this, too')\n" -"logger.error('And non-ASCII stuff, too, like Øresund and Malmö')" - -#: ../../howto/logging.rst:151 -msgid "" -"The *encoding* argument was added. In earlier Python versions, or if not " -"specified, the encoding used is the default value used by :func:`open`. " -"While not shown in the above example, an *errors* argument can also now be " -"passed, which determines how encoding errors are handled. For available " -"values and the default, see the documentation for :func:`open`." -msgstr "" - -#: ../../howto/logging.rst:158 -msgid "" -"And now if we open the file and look at what we have, we should find the log " -"messages:" -msgstr "" - -#: ../../howto/logging.rst:161 -msgid "" -"DEBUG:__main__:This message should go to the log file\n" -"INFO:__main__:So should this\n" -"WARNING:__main__:And this, too\n" -"ERROR:__main__:And non-ASCII stuff, too, like Øresund and Malmö" -msgstr "" - -#: ../../howto/logging.rst:168 -msgid "" -"This example also shows how you can set the logging level which acts as the " -"threshold for tracking. In this case, because we set the threshold to " -"``DEBUG``, all of the messages were printed." -msgstr "" - -#: ../../howto/logging.rst:172 -msgid "" -"If you want to set the logging level from a command-line option such as:" -msgstr "" - -#: ../../howto/logging.rst:174 -msgid "--log=INFO" -msgstr "--log=INFO" - -#: ../../howto/logging.rst:178 -msgid "" -"and you have the value of the parameter passed for ``--log`` in some " -"variable *loglevel*, you can use::" -msgstr "" - -#: ../../howto/logging.rst:181 -msgid "getattr(logging, loglevel.upper())" -msgstr "getattr(logging, loglevel.upper())" - -#: ../../howto/logging.rst:183 -msgid "" -"to get the value which you'll pass to :func:`basicConfig` via the *level* " -"argument. You may want to error check any user input value, perhaps as in " -"the following example::" -msgstr "" - -#: ../../howto/logging.rst:187 -msgid "" -"# assuming loglevel is bound to the string value obtained from the\n" -"# command line argument. Convert to upper case to allow the user to\n" -"# specify --log=DEBUG or --log=debug\n" -"numeric_level = getattr(logging, loglevel.upper(), None)\n" -"if not isinstance(numeric_level, int):\n" -" raise ValueError('Invalid log level: %s' % loglevel)\n" -"logging.basicConfig(level=numeric_level, ...)" -msgstr "" - -#: ../../howto/logging.rst:195 -msgid "" -"The call to :func:`basicConfig` should come *before* any calls to a logger's " -"methods such as :meth:`~Logger.debug`, :meth:`~Logger.info`, etc. Otherwise, " -"that logging event may not be handled in the desired manner." -msgstr "" - -#: ../../howto/logging.rst:199 -msgid "" -"If you run the above script several times, the messages from successive runs " -"are appended to the file *example.log*. If you want each run to start " -"afresh, not remembering the messages from earlier runs, you can specify the " -"*filemode* argument, by changing the call in the above example to::" -msgstr "" - -#: ../../howto/logging.rst:204 -msgid "" -"logging.basicConfig(filename='example.log', filemode='w', " -"level=logging.DEBUG)" -msgstr "" -"logging.basicConfig(filename='example.log', filemode='w', " -"level=logging.DEBUG)" - -#: ../../howto/logging.rst:206 -msgid "" -"The output will be the same as before, but the log file is no longer " -"appended to, so the messages from earlier runs are lost." -msgstr "" - -#: ../../howto/logging.rst:211 -msgid "Logging variable data" -msgstr "" - -#: ../../howto/logging.rst:213 -msgid "" -"To log variable data, use a format string for the event description message " -"and append the variable data as arguments. For example::" -msgstr "" - -#: ../../howto/logging.rst:216 -msgid "" -"import logging\n" -"logging.warning('%s before you %s', 'Look', 'leap!')" -msgstr "" -"import logging\n" -"logging.warning('%s before you %s', 'Look', 'leap!')" - -#: ../../howto/logging.rst:219 -msgid "will display:" -msgstr "" - -#: ../../howto/logging.rst:221 -msgid "WARNING:root:Look before you leap!" -msgstr "WARNING:root:Look before you leap!" - -#: ../../howto/logging.rst:225 -msgid "" -"As you can see, merging of variable data into the event description message " -"uses the old, %-style of string formatting. This is for backwards " -"compatibility: the logging package pre-dates newer formatting options such " -"as :meth:`str.format` and :class:`string.Template`. These newer formatting " -"options *are* supported, but exploring them is outside the scope of this " -"tutorial: see :ref:`formatting-styles` for more information." -msgstr "" - -#: ../../howto/logging.rst:234 -msgid "Changing the format of displayed messages" -msgstr "" - -#: ../../howto/logging.rst:236 -msgid "" -"To change the format which is used to display messages, you need to specify " -"the format you want to use::" -msgstr "" - -#: ../../howto/logging.rst:239 -msgid "" -"import logging\n" -"logging.basicConfig(format='%(levelname)s:%(message)s', " -"level=logging.DEBUG)\n" -"logging.debug('This message should appear on the console')\n" -"logging.info('So should this')\n" -"logging.warning('And this, too')" -msgstr "" -"import logging\n" -"logging.basicConfig(format='%(levelname)s:%(message)s', " -"level=logging.DEBUG)\n" -"logging.debug('This message should appear on the console')\n" -"logging.info('So should this')\n" -"logging.warning('And this, too')" - -#: ../../howto/logging.rst:245 -msgid "which would print:" -msgstr "" - -#: ../../howto/logging.rst:247 -msgid "" -"DEBUG:This message should appear on the console\n" -"INFO:So should this\n" -"WARNING:And this, too" -msgstr "" - -#: ../../howto/logging.rst:253 -msgid "" -"Notice that the 'root' which appeared in earlier examples has disappeared. " -"For a full set of things that can appear in format strings, you can refer to " -"the documentation for :ref:`logrecord-attributes`, but for simple usage, you " -"just need the *levelname* (severity), *message* (event description, " -"including variable data) and perhaps to display when the event occurred. " -"This is described in the next section." -msgstr "" - -#: ../../howto/logging.rst:262 -msgid "Displaying the date/time in messages" -msgstr "" - -#: ../../howto/logging.rst:264 -msgid "" -"To display the date and time of an event, you would place '%(asctime)s' in " -"your format string::" -msgstr "" - -#: ../../howto/logging.rst:267 -msgid "" -"import logging\n" -"logging.basicConfig(format='%(asctime)s %(message)s')\n" -"logging.warning('is when this event was logged.')" -msgstr "" -"import logging\n" -"logging.basicConfig(format='%(asctime)s %(message)s')\n" -"logging.warning('is when this event was logged.')" - -#: ../../howto/logging.rst:271 -msgid "which should print something like this:" -msgstr "" - -#: ../../howto/logging.rst:273 -msgid "2010-12-12 11:41:42,612 is when this event was logged." -msgstr "" - -#: ../../howto/logging.rst:277 -msgid "" -"The default format for date/time display (shown above) is like ISO8601 " -"or :rfc:`3339`. If you need more control over the formatting of the date/" -"time, provide a *datefmt* argument to ``basicConfig``, as in this example::" -msgstr "" - -#: ../../howto/logging.rst:281 -msgid "" -"import logging\n" -"logging.basicConfig(format='%(asctime)s %(message)s', datefmt='%m/%d/%Y %I:" -"%M:%S %p')\n" -"logging.warning('is when this event was logged.')" -msgstr "" -"import logging\n" -"logging.basicConfig(format='%(asctime)s %(message)s', datefmt='%m/%d/%Y %I:" -"%M:%S %p')\n" -"logging.warning('is when this event was logged.')" - -#: ../../howto/logging.rst:285 -msgid "which would display something like this:" -msgstr "" - -#: ../../howto/logging.rst:287 -msgid "12/12/2010 11:46:36 AM is when this event was logged." -msgstr "" - -#: ../../howto/logging.rst:291 -msgid "" -"The format of the *datefmt* argument is the same as supported " -"by :func:`time.strftime`." -msgstr "" - -#: ../../howto/logging.rst:296 -msgid "Next Steps" -msgstr "" - -#: ../../howto/logging.rst:298 -msgid "" -"That concludes the basic tutorial. It should be enough to get you up and " -"running with logging. There's a lot more that the logging package offers, " -"but to get the best out of it, you'll need to invest a little more of your " -"time in reading the following sections. If you're ready for that, grab some " -"of your favourite beverage and carry on." -msgstr "" - -#: ../../howto/logging.rst:304 -msgid "" -"If your logging needs are simple, then use the above examples to incorporate " -"logging into your own scripts, and if you run into problems or don't " -"understand something, please post a question in the Help category of the " -"`Python discussion forum `_ and you " -"should receive help before too long." -msgstr "" - -#: ../../howto/logging.rst:310 -msgid "" -"Still here? You can carry on reading the next few sections, which provide a " -"slightly more advanced/in-depth tutorial than the basic one above. After " -"that, you can take a look at the :ref:`logging-cookbook`." -msgstr "" - -#: ../../howto/logging.rst:318 -msgid "Advanced Logging Tutorial" -msgstr "" - -#: ../../howto/logging.rst:320 -msgid "" -"The logging library takes a modular approach and offers several categories " -"of components: loggers, handlers, filters, and formatters." -msgstr "" - -#: ../../howto/logging.rst:323 -msgid "Loggers expose the interface that application code directly uses." -msgstr "" - -#: ../../howto/logging.rst:324 -msgid "" -"Handlers send the log records (created by loggers) to the appropriate " -"destination." -msgstr "" - -#: ../../howto/logging.rst:326 -msgid "" -"Filters provide a finer grained facility for determining which log records " -"to output." -msgstr "" - -#: ../../howto/logging.rst:328 -msgid "Formatters specify the layout of log records in the final output." -msgstr "" - -#: ../../howto/logging.rst:330 -msgid "" -"Log event information is passed between loggers, handlers, filters and " -"formatters in a :class:`LogRecord` instance." -msgstr "" - -#: ../../howto/logging.rst:333 -msgid "" -"Logging is performed by calling methods on instances of the :class:`Logger` " -"class (hereafter called :dfn:`loggers`). Each instance has a name, and they " -"are conceptually arranged in a namespace hierarchy using dots (periods) as " -"separators. For example, a logger named 'scan' is the parent of loggers " -"'scan.text', 'scan.html' and 'scan.pdf'. Logger names can be anything you " -"want, and indicate the area of an application in which a logged message " -"originates." -msgstr "" - -#: ../../howto/logging.rst:340 -msgid "" -"A good convention to use when naming loggers is to use a module-level " -"logger, in each module which uses logging, named as follows::" -msgstr "" - -#: ../../howto/logging.rst:343 -msgid "logger = logging.getLogger(__name__)" -msgstr "logger = logging.getLogger(__name__)" - -#: ../../howto/logging.rst:345 -msgid "" -"This means that logger names track the package/module hierarchy, and it's " -"intuitively obvious where events are logged just from the logger name." -msgstr "" - -#: ../../howto/logging.rst:348 -msgid "" -"The root of the hierarchy of loggers is called the root logger. That's the " -"logger used by the " -"functions :func:`debug`, :func:`info`, :func:`warning`, :func:`error` " -"and :func:`critical`, which just call the same-named method of the root " -"logger. The functions and the methods have the same signatures. The root " -"logger's name is printed as 'root' in the logged output." -msgstr "" - -#: ../../howto/logging.rst:354 -msgid "" -"It is, of course, possible to log messages to different destinations. " -"Support is included in the package for writing log messages to files, HTTP " -"GET/POST locations, email via SMTP, generic sockets, queues, or OS-specific " -"logging mechanisms such as syslog or the Windows NT event log. Destinations " -"are served by :dfn:`handler` classes. You can create your own log " -"destination class if you have special requirements not met by any of the " -"built-in handler classes." -msgstr "" - -#: ../../howto/logging.rst:361 -msgid "" -"By default, no destination is set for any logging messages. You can specify " -"a destination (such as console or file) by using :func:`basicConfig` as in " -"the tutorial examples. If you call the " -"functions :func:`debug`, :func:`info`, :func:`warning`, :func:`error` " -"and :func:`critical`, they will check to see if no destination is set; and " -"if one is not set, they will set a destination of the console " -"(``sys.stderr``) and a default format for the displayed message before " -"delegating to the root logger to do the actual message output." -msgstr "" - -#: ../../howto/logging.rst:369 -msgid "The default format set by :func:`basicConfig` for messages is:" -msgstr "" - -#: ../../howto/logging.rst:371 -msgid "severity:logger name:message" -msgstr "severity:logger name:message" - -#: ../../howto/logging.rst:375 -msgid "" -"You can change this by passing a format string to :func:`basicConfig` with " -"the *format* keyword argument. For all options regarding how a format string " -"is constructed, see :ref:`formatter-objects`." -msgstr "" - -#: ../../howto/logging.rst:380 -msgid "Logging Flow" -msgstr "" - -#: ../../howto/logging.rst:382 -msgid "" -"The flow of log event information in loggers and handlers is illustrated in " -"the following diagram." -msgstr "" - -#: ../../howto/logging.rst:433 -msgid "Loggers" -msgstr "" - -#: ../../howto/logging.rst:435 -msgid "" -":class:`Logger` objects have a threefold job. First, they expose several " -"methods to application code so that applications can log messages at " -"runtime. Second, logger objects determine which log messages to act upon " -"based upon severity (the default filtering facility) or filter objects. " -"Third, logger objects pass along relevant log messages to all interested log " -"handlers." -msgstr "" - -#: ../../howto/logging.rst:441 -msgid "" -"The most widely used methods on logger objects fall into two categories: " -"configuration and message sending." -msgstr "" - -#: ../../howto/logging.rst:444 -msgid "These are the most common configuration methods:" -msgstr "" - -#: ../../howto/logging.rst:446 -msgid "" -":meth:`Logger.setLevel` specifies the lowest-severity log message a logger " -"will handle, where debug is the lowest built-in severity level and critical " -"is the highest built-in severity. For example, if the severity level is " -"INFO, the logger will handle only INFO, WARNING, ERROR, and CRITICAL " -"messages and will ignore DEBUG messages." -msgstr "" - -#: ../../howto/logging.rst:452 -msgid "" -":meth:`Logger.addHandler` and :meth:`Logger.removeHandler` add and remove " -"handler objects from the logger object. Handlers are covered in more detail " -"in :ref:`handler-basic`." -msgstr "" - -#: ../../howto/logging.rst:456 -msgid "" -":meth:`Logger.addFilter` and :meth:`Logger.removeFilter` add and remove " -"filter objects from the logger object. Filters are covered in more detail " -"in :ref:`filter`." -msgstr "" - -#: ../../howto/logging.rst:460 -msgid "" -"You don't need to always call these methods on every logger you create. See " -"the last two paragraphs in this section." -msgstr "" - -#: ../../howto/logging.rst:463 -msgid "" -"With the logger object configured, the following methods create log messages:" -msgstr "" - -#: ../../howto/logging.rst:465 -msgid "" -":meth:`Logger.debug`, :meth:`Logger.info`, :meth:`Logger.warning`, :meth:`Logger.error`, " -"and :meth:`Logger.critical` all create log records with a message and a " -"level that corresponds to their respective method names. The message is " -"actually a format string, which may contain the standard string substitution " -"syntax of ``%s``, ``%d``, ``%f``, and so on. The rest of their arguments is " -"a list of objects that correspond with the substitution fields in the " -"message. With regard to ``**kwargs``, the logging methods care only about a " -"keyword of ``exc_info`` and use it to determine whether to log exception " -"information." -msgstr "" - -#: ../../howto/logging.rst:475 -msgid "" -":meth:`Logger.exception` creates a log message similar " -"to :meth:`Logger.error`. The difference is that :meth:`Logger.exception` " -"dumps a stack trace along with it. Call this method only from an exception " -"handler." -msgstr "" - -#: ../../howto/logging.rst:479 -msgid "" -":meth:`Logger.log` takes a log level as an explicit argument. This is a " -"little more verbose for logging messages than using the log level " -"convenience methods listed above, but this is how to log at custom log " -"levels." -msgstr "" - -#: ../../howto/logging.rst:483 -msgid "" -":func:`getLogger` returns a reference to a logger instance with the " -"specified name if it is provided, or ``root`` if not. The names are period-" -"separated hierarchical structures. Multiple calls to :func:`getLogger` with " -"the same name will return a reference to the same logger object. Loggers " -"that are further down in the hierarchical list are children of loggers " -"higher up in the list. For example, given a logger with a name of ``foo``, " -"loggers with names of ``foo.bar``, ``foo.bar.baz``, and ``foo.bam`` are all " -"descendants of ``foo``." -msgstr "" - -#: ../../howto/logging.rst:491 -msgid "" -"Loggers have a concept of *effective level*. If a level is not explicitly " -"set on a logger, the level of its parent is used instead as its effective " -"level. If the parent has no explicit level set, *its* parent is examined, " -"and so on - all ancestors are searched until an explicitly set level is " -"found. The root logger always has an explicit level set (``WARNING`` by " -"default). When deciding whether to process an event, the effective level of " -"the logger is used to determine whether the event is passed to the logger's " -"handlers." -msgstr "" - -#: ../../howto/logging.rst:499 -msgid "" -"Child loggers propagate messages up to the handlers associated with their " -"ancestor loggers. Because of this, it is unnecessary to define and configure " -"handlers for all the loggers an application uses. It is sufficient to " -"configure handlers for a top-level logger and create child loggers as " -"needed. (You can, however, turn off propagation by setting the *propagate* " -"attribute of a logger to ``False``.)" -msgstr "" - -#: ../../howto/logging.rst:510 -msgid "Handlers" -msgstr "" - -#: ../../howto/logging.rst:512 -msgid "" -":class:`~logging.Handler` objects are responsible for dispatching the " -"appropriate log messages (based on the log messages' severity) to the " -"handler's specified destination. :class:`Logger` objects can add zero or " -"more handler objects to themselves with an :meth:`~Logger.addHandler` " -"method. As an example scenario, an application may want to send all log " -"messages to a log file, all log messages of error or higher to stdout, and " -"all messages of critical to an email address. This scenario requires three " -"individual handlers where each handler is responsible for sending messages " -"of a specific severity to a specific location." -msgstr "" - -#: ../../howto/logging.rst:522 -msgid "" -"The standard library includes quite a few handler types (see :ref:`useful-" -"handlers`); the tutorials use mainly :class:`StreamHandler` " -"and :class:`FileHandler` in its examples." -msgstr "" - -#: ../../howto/logging.rst:526 -msgid "" -"There are very few methods in a handler for application developers to " -"concern themselves with. The only handler methods that seem relevant for " -"application developers who are using the built-in handler objects (that is, " -"not creating custom handlers) are the following configuration methods:" -msgstr "" - -#: ../../howto/logging.rst:531 -msgid "" -"The :meth:`~Handler.setLevel` method, just as in logger objects, specifies " -"the lowest severity that will be dispatched to the appropriate destination. " -"Why are there two :meth:`~Handler.setLevel` methods? The level set in the " -"logger determines which severity of messages it will pass to its handlers. " -"The level set in each handler determines which messages that handler will " -"send on." -msgstr "" - -#: ../../howto/logging.rst:537 -msgid "" -":meth:`~Handler.setFormatter` selects a Formatter object for this handler to " -"use." -msgstr "" - -#: ../../howto/logging.rst:540 -msgid "" -":meth:`~Handler.addFilter` and :meth:`~Handler.removeFilter` respectively " -"configure and deconfigure filter objects on handlers." -msgstr "" - -#: ../../howto/logging.rst:543 -msgid "" -"Application code should not directly instantiate and use instances " -"of :class:`Handler`. Instead, the :class:`Handler` class is a base class " -"that defines the interface that all handlers should have and establishes " -"some default behavior that child classes can use (or override)." -msgstr "" - -#: ../../howto/logging.rst:550 -msgid "Formatters" -msgstr "" - -#: ../../howto/logging.rst:552 -msgid "" -"Formatter objects configure the final order, structure, and contents of the " -"log message. Unlike the base :class:`logging.Handler` class, application " -"code may instantiate formatter classes, although you could likely subclass " -"the formatter if your application needs special behavior. The constructor " -"takes three optional arguments -- a message format string, a date format " -"string and a style indicator." -msgstr "" - -#: ../../howto/logging.rst:561 -msgid "" -"If there is no message format string, the default is to use the raw " -"message. If there is no date format string, the default date format is:" -msgstr "" - -#: ../../howto/logging.rst:564 -msgid "%Y-%m-%d %H:%M:%S" -msgstr "%Y-%m-%d %H:%M:%S" - -#: ../../howto/logging.rst:568 -msgid "" -"with the milliseconds tacked on at the end. The ``style`` is one of ``'%'``, " -"``'{'``, or ``'$'``. If one of these is not specified, then ``'%'`` will be " -"used." -msgstr "" - -#: ../../howto/logging.rst:571 -msgid "" -"If the ``style`` is ``'%'``, the message format string uses ``%()s`` styled string substitution; the possible keys are documented " -"in :ref:`logrecord-attributes`. If the style is ``'{'``, the message format " -"string is assumed to be compatible with :meth:`str.format` (using keyword " -"arguments), while if the style is ``'$'`` then the message format string " -"should conform to what is expected by :meth:`string.Template.substitute`." -msgstr "" - -#: ../../howto/logging.rst:578 -msgid "Added the ``style`` parameter." -msgstr "新增 ``style`` 參數。" - -#: ../../howto/logging.rst:581 -msgid "" -"The following message format string will log the time in a human-readable " -"format, the severity of the message, and the contents of the message, in " -"that order::" -msgstr "" - -#: ../../howto/logging.rst:585 -msgid "'%(asctime)s - %(levelname)s - %(message)s'" -msgstr "" - -#: ../../howto/logging.rst:587 -msgid "" -"Formatters use a user-configurable function to convert the creation time of " -"a record to a tuple. By default, :func:`time.localtime` is used; to change " -"this for a particular formatter instance, set the ``converter`` attribute of " -"the instance to a function with the same signature as :func:`time.localtime` " -"or :func:`time.gmtime`. To change it for all formatters, for example if you " -"want all logging times to be shown in GMT, set the ``converter`` attribute " -"in the Formatter class (to ``time.gmtime`` for GMT display)." -msgstr "" - -#: ../../howto/logging.rst:597 -msgid "Configuring Logging" -msgstr "" - -#: ../../howto/logging.rst:601 -msgid "Programmers can configure logging in three ways:" -msgstr "" - -#: ../../howto/logging.rst:603 -msgid "" -"Creating loggers, handlers, and formatters explicitly using Python code that " -"calls the configuration methods listed above." -msgstr "" - -#: ../../howto/logging.rst:605 -msgid "" -"Creating a logging config file and reading it using the :func:`fileConfig` " -"function." -msgstr "" - -#: ../../howto/logging.rst:607 -msgid "" -"Creating a dictionary of configuration information and passing it to " -"the :func:`dictConfig` function." -msgstr "" - -#: ../../howto/logging.rst:610 -msgid "" -"For the reference documentation on the last two options, see :ref:`logging-" -"config-api`. The following example configures a very simple logger, a " -"console handler, and a simple formatter using Python code::" -msgstr "" - -#: ../../howto/logging.rst:614 -msgid "" -"import logging\n" -"\n" -"# create logger\n" -"logger = logging.getLogger('simple_example')\n" -"logger.setLevel(logging.DEBUG)\n" -"\n" -"# create console handler and set level to debug\n" -"ch = logging.StreamHandler()\n" -"ch.setLevel(logging.DEBUG)\n" -"\n" -"# create formatter\n" -"formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %" -"(message)s')\n" -"\n" -"# add formatter to ch\n" -"ch.setFormatter(formatter)\n" -"\n" -"# add ch to logger\n" -"logger.addHandler(ch)\n" -"\n" -"# 'application' code\n" -"logger.debug('debug message')\n" -"logger.info('info message')\n" -"logger.warning('warn message')\n" -"logger.error('error message')\n" -"logger.critical('critical message')" -msgstr "" - -#: ../../howto/logging.rst:640 -msgid "" -"Running this module from the command line produces the following output:" -msgstr "" - -#: ../../howto/logging.rst:642 -msgid "" -"$ python simple_logging_module.py\n" -"2005-03-19 15:10:26,618 - simple_example - DEBUG - debug message\n" -"2005-03-19 15:10:26,620 - simple_example - INFO - info message\n" -"2005-03-19 15:10:26,695 - simple_example - WARNING - warn message\n" -"2005-03-19 15:10:26,697 - simple_example - ERROR - error message\n" -"2005-03-19 15:10:26,773 - simple_example - CRITICAL - critical message" -msgstr "" - -#: ../../howto/logging.rst:651 -msgid "" -"The following Python module creates a logger, handler, and formatter nearly " -"identical to those in the example listed above, with the only difference " -"being the names of the objects::" -msgstr "" - -#: ../../howto/logging.rst:655 -msgid "" -"import logging\n" -"import logging.config\n" -"\n" -"logging.config.fileConfig('logging.conf')\n" -"\n" -"# create logger\n" -"logger = logging.getLogger('simpleExample')\n" -"\n" -"# 'application' code\n" -"logger.debug('debug message')\n" -"logger.info('info message')\n" -"logger.warning('warn message')\n" -"logger.error('error message')\n" -"logger.critical('critical message')" -msgstr "" - -#: ../../howto/logging.rst:670 -msgid "Here is the logging.conf file:" -msgstr "" - -#: ../../howto/logging.rst:672 -msgid "" -"[loggers]\n" -"keys=root,simpleExample\n" -"\n" -"[handlers]\n" -"keys=consoleHandler\n" -"\n" -"[formatters]\n" -"keys=simpleFormatter\n" -"\n" -"[logger_root]\n" -"level=DEBUG\n" -"handlers=consoleHandler\n" -"\n" -"[logger_simpleExample]\n" -"level=DEBUG\n" -"handlers=consoleHandler\n" -"qualname=simpleExample\n" -"propagate=0\n" -"\n" -"[handler_consoleHandler]\n" -"class=StreamHandler\n" -"level=DEBUG\n" -"formatter=simpleFormatter\n" -"args=(sys.stdout,)\n" -"\n" -"[formatter_simpleFormatter]\n" -"format=%(asctime)s - %(name)s - %(levelname)s - %(message)s" -msgstr "" - -#: ../../howto/logging.rst:702 -msgid "" -"The output is nearly identical to that of the non-config-file-based example:" -msgstr "" - -#: ../../howto/logging.rst:704 -msgid "" -"$ python simple_logging_config.py\n" -"2005-03-19 15:38:55,977 - simpleExample - DEBUG - debug message\n" -"2005-03-19 15:38:55,979 - simpleExample - INFO - info message\n" -"2005-03-19 15:38:56,054 - simpleExample - WARNING - warn message\n" -"2005-03-19 15:38:56,055 - simpleExample - ERROR - error message\n" -"2005-03-19 15:38:56,130 - simpleExample - CRITICAL - critical message" -msgstr "" - -#: ../../howto/logging.rst:713 -msgid "" -"You can see that the config file approach has a few advantages over the " -"Python code approach, mainly separation of configuration and code and the " -"ability of noncoders to easily modify the logging properties." -msgstr "" - -#: ../../howto/logging.rst:717 -msgid "" -"The :func:`fileConfig` function takes a default parameter, " -"``disable_existing_loggers``, which defaults to ``True`` for reasons of " -"backward compatibility. This may or may not be what you want, since it will " -"cause any non-root loggers existing before the :func:`fileConfig` call to be " -"disabled unless they (or an ancestor) are explicitly named in the " -"configuration. Please refer to the reference documentation for more " -"information, and specify ``False`` for this parameter if you wish." -msgstr "" - -#: ../../howto/logging.rst:725 -msgid "" -"The dictionary passed to :func:`dictConfig` can also specify a Boolean value " -"with key ``disable_existing_loggers``, which if not specified explicitly in " -"the dictionary also defaults to being interpreted as ``True``. This leads to " -"the logger-disabling behaviour described above, which may not be what you " -"want - in which case, provide the key explicitly with a value of ``False``." -msgstr "" - -#: ../../howto/logging.rst:735 -msgid "" -"Note that the class names referenced in config files need to be either " -"relative to the logging module, or absolute values which can be resolved " -"using normal import mechanisms. Thus, you could use " -"either :class:`~logging.handlers.WatchedFileHandler` (relative to the " -"logging module) or ``mypackage.mymodule.MyHandler`` (for a class defined in " -"package ``mypackage`` and module ``mymodule``, where ``mypackage`` is " -"available on the Python import path)." -msgstr "" - -#: ../../howto/logging.rst:743 -msgid "" -"In Python 3.2, a new means of configuring logging has been introduced, using " -"dictionaries to hold configuration information. This provides a superset of " -"the functionality of the config-file-based approach outlined above, and is " -"the recommended configuration method for new applications and deployments. " -"Because a Python dictionary is used to hold configuration information, and " -"since you can populate that dictionary using different means, you have more " -"options for configuration. For example, you can use a configuration file in " -"JSON format, or, if you have access to YAML processing functionality, a file " -"in YAML format, to populate the configuration dictionary. Or, of course, you " -"can construct the dictionary in Python code, receive it in pickled form over " -"a socket, or use whatever approach makes sense for your application." -msgstr "" - -#: ../../howto/logging.rst:755 -msgid "" -"Here's an example of the same configuration as above, in YAML format for the " -"new dictionary-based approach:" -msgstr "" - -#: ../../howto/logging.rst:758 -msgid "" -"version: 1\n" -"formatters:\n" -" simple:\n" -" format: '%(asctime)s - %(name)s - %(levelname)s - %(message)s'\n" -"handlers:\n" -" console:\n" -" class: logging.StreamHandler\n" -" level: DEBUG\n" -" formatter: simple\n" -" stream: ext://sys.stdout\n" -"loggers:\n" -" simpleExample:\n" -" level: DEBUG\n" -" handlers: [console]\n" -" propagate: no\n" -"root:\n" -" level: DEBUG\n" -" handlers: [console]" -msgstr "" - -#: ../../howto/logging.rst:779 -msgid "" -"For more information about logging using a dictionary, see :ref:`logging-" -"config-api`." -msgstr "" - -#: ../../howto/logging.rst:783 -msgid "What happens if no configuration is provided" -msgstr "" - -#: ../../howto/logging.rst:785 -msgid "" -"If no logging configuration is provided, it is possible to have a situation " -"where a logging event needs to be output, but no handlers can be found to " -"output the event." -msgstr "" - -#: ../../howto/logging.rst:789 -msgid "" -"The event is output using a 'handler of last resort', stored " -"in :data:`lastResort`. This internal handler is not associated with any " -"logger, and acts like a :class:`~logging.StreamHandler` which writes the " -"event description message to the current value of ``sys.stderr`` (therefore " -"respecting any redirections which may be in effect). No formatting is done " -"on the message - just the bare event description message is printed. The " -"handler's level is set to ``WARNING``, so all events at this and greater " -"severities will be output." -msgstr "" - -#: ../../howto/logging.rst:800 -msgid "For versions of Python prior to 3.2, the behaviour is as follows:" -msgstr "" - -#: ../../howto/logging.rst:802 -msgid "" -"If :data:`raiseExceptions` is ``False`` (production mode), the event is " -"silently dropped." -msgstr "" - -#: ../../howto/logging.rst:805 -msgid "" -"If :data:`raiseExceptions` is ``True`` (development mode), a message 'No " -"handlers could be found for logger X.Y.Z' is printed once." -msgstr "" - -#: ../../howto/logging.rst:808 -msgid "" -"To obtain the pre-3.2 behaviour, :data:`lastResort` can be set to ``None``." -msgstr "" - -#: ../../howto/logging.rst:814 -msgid "Configuring Logging for a Library" -msgstr "" - -#: ../../howto/logging.rst:816 -msgid "" -"When developing a library which uses logging, you should take care to " -"document how the library uses logging - for example, the names of loggers " -"used. Some consideration also needs to be given to its logging " -"configuration. If the using application does not use logging, and library " -"code makes logging calls, then (as described in the previous section) events " -"of severity ``WARNING`` and greater will be printed to ``sys.stderr``. This " -"is regarded as the best default behaviour." -msgstr "" - -#: ../../howto/logging.rst:824 -msgid "" -"If for some reason you *don't* want these messages printed in the absence of " -"any logging configuration, you can attach a do-nothing handler to the top-" -"level logger for your library. This avoids the message being printed, since " -"a handler will always be found for the library's events: it just doesn't " -"produce any output. If the library user configures logging for application " -"use, presumably that configuration will add some handlers, and if levels are " -"suitably configured then logging calls made in library code will send output " -"to those handlers, as normal." -msgstr "" - -#: ../../howto/logging.rst:833 -msgid "" -"A do-nothing handler is included in the logging " -"package: :class:`~logging.NullHandler` (since Python 3.1). An instance of " -"this handler could be added to the top-level logger of the logging namespace " -"used by the library (*if* you want to prevent your library's logged events " -"being output to ``sys.stderr`` in the absence of logging configuration). If " -"all logging by a library *foo* is done using loggers with names matching " -"'foo.x', 'foo.x.y', etc. then the code::" -msgstr "" - -#: ../../howto/logging.rst:841 -msgid "" -"import logging\n" -"logging.getLogger('foo').addHandler(logging.NullHandler())" -msgstr "" -"import logging\n" -"logging.getLogger('foo').addHandler(logging.NullHandler())" - -#: ../../howto/logging.rst:844 -msgid "" -"should have the desired effect. If an organisation produces a number of " -"libraries, then the logger name specified can be 'orgname.foo' rather than " -"just 'foo'." -msgstr "" - -#: ../../howto/logging.rst:848 -msgid "" -"It is strongly advised that you *do not log to the root logger* in your " -"library. Instead, use a logger with a unique and easily identifiable name, " -"such as the ``__name__`` for your library's top-level package or module. " -"Logging to the root logger will make it difficult or impossible for the " -"application developer to configure the logging verbosity or handlers of your " -"library as they wish." -msgstr "" - -#: ../../howto/logging.rst:855 -msgid "" -"It is strongly advised that you *do not add any handlers other " -"than* :class:`~logging.NullHandler` *to your library's loggers*. This is " -"because the configuration of handlers is the prerogative of the application " -"developer who uses your library. The application developer knows their " -"target audience and what handlers are most appropriate for their " -"application: if you add handlers 'under the hood', you might well interfere " -"with their ability to carry out unit tests and deliver logs which suit their " -"requirements." -msgstr "" - -#: ../../howto/logging.rst:866 -msgid "Logging Levels" -msgstr "" - -#: ../../howto/logging.rst:868 -msgid "" -"The numeric values of logging levels are given in the following table. These " -"are primarily of interest if you want to define your own levels, and need " -"them to have specific values relative to the predefined levels. If you " -"define a level with the same numeric value, it overwrites the predefined " -"value; the predefined name is lost." -msgstr "" - -#: ../../howto/logging.rst:875 -msgid "Numeric value" -msgstr "" - -#: ../../howto/logging.rst:877 -msgid "50" -msgstr "50" - -#: ../../howto/logging.rst:879 -msgid "40" -msgstr "40" - -#: ../../howto/logging.rst:881 -msgid "30" -msgstr "30" - -#: ../../howto/logging.rst:883 -msgid "20" -msgstr "20" - -#: ../../howto/logging.rst:885 -msgid "10" -msgstr "10" - -#: ../../howto/logging.rst:887 -msgid "``NOTSET``" -msgstr "``NOTSET``" - -#: ../../howto/logging.rst:887 -msgid "0" -msgstr "0" - -#: ../../howto/logging.rst:890 -msgid "" -"Levels can also be associated with loggers, being set either by the " -"developer or through loading a saved logging configuration. When a logging " -"method is called on a logger, the logger compares its own level with the " -"level associated with the method call. If the logger's level is higher than " -"the method call's, no logging message is actually generated. This is the " -"basic mechanism controlling the verbosity of logging output." -msgstr "" - -#: ../../howto/logging.rst:897 -msgid "" -"Logging messages are encoded as instances of the :class:`~logging.LogRecord` " -"class. When a logger decides to actually log an event, " -"a :class:`~logging.LogRecord` instance is created from the logging message." -msgstr "" - -#: ../../howto/logging.rst:901 -msgid "" -"Logging messages are subjected to a dispatch mechanism through the use " -"of :dfn:`handlers`, which are instances of subclasses of " -"the :class:`Handler` class. Handlers are responsible for ensuring that a " -"logged message (in the form of a :class:`LogRecord`) ends up in a particular " -"location (or set of locations) which is useful for the target audience for " -"that message (such as end users, support desk staff, system administrators, " -"developers). Handlers are passed :class:`LogRecord` instances intended for " -"particular destinations. Each logger can have zero, one or more handlers " -"associated with it (via the :meth:`~Logger.addHandler` method " -"of :class:`Logger`). In addition to any handlers directly associated with a " -"logger, *all handlers associated with all ancestors of the logger* are " -"called to dispatch the message (unless the *propagate* flag for a logger is " -"set to a false value, at which point the passing to ancestor handlers stops)." -msgstr "" - -#: ../../howto/logging.rst:915 -msgid "" -"Just as for loggers, handlers can have levels associated with them. A " -"handler's level acts as a filter in the same way as a logger's level does. " -"If a handler decides to actually dispatch an event, " -"the :meth:`~Handler.emit` method is used to send the message to its " -"destination. Most user-defined subclasses of :class:`Handler` will need to " -"override this :meth:`~Handler.emit`." -msgstr "" - -#: ../../howto/logging.rst:924 -msgid "Custom Levels" -msgstr "" - -#: ../../howto/logging.rst:926 -msgid "" -"Defining your own levels is possible, but should not be necessary, as the " -"existing levels have been chosen on the basis of practical experience. " -"However, if you are convinced that you need custom levels, great care should " -"be exercised when doing this, and it is possibly *a very bad idea to define " -"custom levels if you are developing a library*. That's because if multiple " -"library authors all define their own custom levels, there is a chance that " -"the logging output from such multiple libraries used together will be " -"difficult for the using developer to control and/or interpret, because a " -"given numeric value might mean different things for different libraries." -msgstr "" - -#: ../../howto/logging.rst:939 -msgid "Useful Handlers" -msgstr "" - -#: ../../howto/logging.rst:941 -msgid "" -"In addition to the base :class:`Handler` class, many useful subclasses are " -"provided:" -msgstr "" - -#: ../../howto/logging.rst:944 -msgid "" -":class:`StreamHandler` instances send messages to streams (file-like " -"objects)." -msgstr "" - -#: ../../howto/logging.rst:947 -msgid ":class:`FileHandler` instances send messages to disk files." -msgstr "" - -#: ../../howto/logging.rst:949 -msgid "" -":class:`~handlers.BaseRotatingHandler` is the base class for handlers that " -"rotate log files at a certain point. It is not meant to be instantiated " -"directly. Instead, use :class:`~handlers.RotatingFileHandler` " -"or :class:`~handlers.TimedRotatingFileHandler`." -msgstr "" - -#: ../../howto/logging.rst:954 -msgid "" -":class:`~handlers.RotatingFileHandler` instances send messages to disk " -"files, with support for maximum log file sizes and log file rotation." -msgstr "" - -#: ../../howto/logging.rst:957 -msgid "" -":class:`~handlers.TimedRotatingFileHandler` instances send messages to disk " -"files, rotating the log file at certain timed intervals." -msgstr "" - -#: ../../howto/logging.rst:960 -msgid "" -":class:`~handlers.SocketHandler` instances send messages to TCP/IP sockets. " -"Since 3.4, Unix domain sockets are also supported." -msgstr "" - -#: ../../howto/logging.rst:963 -msgid "" -":class:`~handlers.DatagramHandler` instances send messages to UDP sockets. " -"Since 3.4, Unix domain sockets are also supported." -msgstr "" - -#: ../../howto/logging.rst:966 -msgid "" -":class:`~handlers.SMTPHandler` instances send messages to a designated email " -"address." -msgstr "" - -#: ../../howto/logging.rst:969 -msgid "" -":class:`~handlers.SysLogHandler` instances send messages to a Unix syslog " -"daemon, possibly on a remote machine." -msgstr "" - -#: ../../howto/logging.rst:972 -msgid "" -":class:`~handlers.NTEventLogHandler` instances send messages to a Windows NT/" -"2000/XP event log." -msgstr "" - -#: ../../howto/logging.rst:975 -msgid "" -":class:`~handlers.MemoryHandler` instances send messages to a buffer in " -"memory, which is flushed whenever specific criteria are met." -msgstr "" - -#: ../../howto/logging.rst:978 -msgid "" -":class:`~handlers.HTTPHandler` instances send messages to an HTTP server " -"using either ``GET`` or ``POST`` semantics." -msgstr "" - -#: ../../howto/logging.rst:981 -msgid "" -":class:`~handlers.WatchedFileHandler` instances watch the file they are " -"logging to. If the file changes, it is closed and reopened using the file " -"name. This handler is only useful on Unix-like systems; Windows does not " -"support the underlying mechanism used." -msgstr "" - -#: ../../howto/logging.rst:986 -msgid "" -":class:`~handlers.QueueHandler` instances send messages to a queue, such as " -"those implemented in the :mod:`queue` or :mod:`multiprocessing` modules." -msgstr "" - -#: ../../howto/logging.rst:989 -msgid "" -":class:`NullHandler` instances do nothing with error messages. They are used " -"by library developers who want to use logging, but want to avoid the 'No " -"handlers could be found for logger *XXX*' message which can be displayed if " -"the library user has not configured logging. See :ref:`library-config` for " -"more information." -msgstr "" - -#: ../../howto/logging.rst:995 -msgid "The :class:`NullHandler` class." -msgstr "" - -#: ../../howto/logging.rst:998 -msgid "The :class:`~handlers.QueueHandler` class." -msgstr "" - -#: ../../howto/logging.rst:1001 -msgid "" -"The :class:`NullHandler`, :class:`StreamHandler` and :class:`FileHandler` " -"classes are defined in the core logging package. The other handlers are " -"defined in a sub-module, :mod:`logging.handlers`. (There is also another sub-" -"module, :mod:`logging.config`, for configuration functionality.)" -msgstr "" - -#: ../../howto/logging.rst:1006 -msgid "" -"Logged messages are formatted for presentation through instances of " -"the :class:`Formatter` class. They are initialized with a format string " -"suitable for use with the % operator and a dictionary." -msgstr "" - -#: ../../howto/logging.rst:1010 -msgid "" -"For formatting multiple messages in a batch, instances " -"of :class:`BufferingFormatter` can be used. In addition to the format string " -"(which is applied to each message in the batch), there is provision for " -"header and trailer format strings." -msgstr "" - -#: ../../howto/logging.rst:1015 -msgid "" -"When filtering based on logger level and/or handler level is not enough, " -"instances of :class:`Filter` can be added to both :class:`Logger` " -"and :class:`Handler` instances (through their :meth:`~Handler.addFilter` " -"method). Before deciding to process a message further, both loggers and " -"handlers consult all their filters for permission. If any filter returns a " -"false value, the message is not processed further." -msgstr "" - -#: ../../howto/logging.rst:1022 -msgid "" -"The basic :class:`Filter` functionality allows filtering by specific logger " -"name. If this feature is used, messages sent to the named logger and its " -"children are allowed through the filter, and all others dropped." -msgstr "" - -#: ../../howto/logging.rst:1030 -msgid "Exceptions raised during logging" -msgstr "" - -#: ../../howto/logging.rst:1032 -msgid "" -"The logging package is designed to swallow exceptions which occur while " -"logging in production. This is so that errors which occur while handling " -"logging events - such as logging misconfiguration, network or other similar " -"errors - do not cause the application using logging to terminate prematurely." -msgstr "" - -#: ../../howto/logging.rst:1037 -msgid "" -":class:`SystemExit` and :class:`KeyboardInterrupt` exceptions are never " -"swallowed. Other exceptions which occur during the :meth:`~Handler.emit` " -"method of a :class:`Handler` subclass are passed to " -"its :meth:`~Handler.handleError` method." -msgstr "" - -#: ../../howto/logging.rst:1042 -msgid "" -"The default implementation of :meth:`~Handler.handleError` " -"in :class:`Handler` checks to see if a module-level " -"variable, :data:`raiseExceptions`, is set. If set, a traceback is printed " -"to :data:`sys.stderr`. If not set, the exception is swallowed." -msgstr "" - -#: ../../howto/logging.rst:1048 -msgid "" -"The default value of :data:`raiseExceptions` is ``True``. This is because " -"during development, you typically want to be notified of any exceptions that " -"occur. It's advised that you set :data:`raiseExceptions` to ``False`` for " -"production usage." -msgstr "" - -#: ../../howto/logging.rst:1058 -msgid "Using arbitrary objects as messages" -msgstr "" - -#: ../../howto/logging.rst:1060 -msgid "" -"In the preceding sections and examples, it has been assumed that the message " -"passed when logging the event is a string. However, this is not the only " -"possibility. You can pass an arbitrary object as a message, and " -"its :meth:`~object.__str__` method will be called when the logging system " -"needs to convert it to a string representation. In fact, if you want to, you " -"can avoid computing a string representation altogether - for example, " -"the :class:`~handlers.SocketHandler` emits an event by pickling it and " -"sending it over the wire." -msgstr "" - -#: ../../howto/logging.rst:1071 -msgid "Optimization" -msgstr "最佳化" - -#: ../../howto/logging.rst:1073 -msgid "" -"Formatting of message arguments is deferred until it cannot be avoided. " -"However, computing the arguments passed to the logging method can also be " -"expensive, and you may want to avoid doing it if the logger will just throw " -"away your event. To decide what to do, you can call " -"the :meth:`~Logger.isEnabledFor` method which takes a level argument and " -"returns true if the event would be created by the Logger for that level of " -"call. You can write code like this::" -msgstr "" - -#: ../../howto/logging.rst:1081 -msgid "" -"if logger.isEnabledFor(logging.DEBUG):\n" -" logger.debug('Message with %s, %s', expensive_func1(),\n" -" expensive_func2())" -msgstr "" - -#: ../../howto/logging.rst:1085 -msgid "" -"so that if the logger's threshold is set above ``DEBUG``, the calls to " -"``expensive_func1`` and ``expensive_func2`` are never made." -msgstr "" - -#: ../../howto/logging.rst:1088 -msgid "" -"In some cases, :meth:`~Logger.isEnabledFor` can itself be more expensive " -"than you'd like (e.g. for deeply nested loggers where an explicit level is " -"only set high up in the logger hierarchy). In such cases (or if you want to " -"avoid calling a method in tight loops), you can cache the result of a call " -"to :meth:`~Logger.isEnabledFor` in a local or instance variable, and use " -"that instead of calling the method each time. Such a cached value would only " -"need to be recomputed when the logging configuration changes dynamically " -"while the application is running (which is not all that common)." -msgstr "" - -#: ../../howto/logging.rst:1097 -msgid "" -"There are other optimizations which can be made for specific applications " -"which need more precise control over what logging information is collected. " -"Here's a list of things you can do to avoid processing during logging which " -"you don't need:" -msgstr "" - -#: ../../howto/logging.rst:1103 -msgid "What you don't want to collect" -msgstr "" - -#: ../../howto/logging.rst:1103 -msgid "How to avoid collecting it" -msgstr "" - -#: ../../howto/logging.rst:1105 -msgid "Information about where calls were made from." -msgstr "" - -#: ../../howto/logging.rst:1105 -msgid "" -"Set ``logging._srcfile`` to ``None``. This avoids " -"calling :func:`sys._getframe`, which may help to speed up your code in " -"environments like PyPy (which can't speed up code that " -"uses :func:`sys._getframe`)." -msgstr "" - -#: ../../howto/logging.rst:1111 -msgid "Threading information." -msgstr "" - -#: ../../howto/logging.rst:1111 -msgid "Set ``logging.logThreads`` to ``False``." -msgstr "將 ``logging.logThreads`` 設為 ``False``。" - -#: ../../howto/logging.rst:1113 -msgid "Current process ID (:func:`os.getpid`)" -msgstr "目前的行程 ID (:func:`os.getpid`)" - -#: ../../howto/logging.rst:1113 -msgid "Set ``logging.logProcesses`` to ``False``." -msgstr "將 ``logging.logProcesses`` 設為 ``False``。" - -#: ../../howto/logging.rst:1115 -msgid "" -"Current process name when using ``multiprocessing`` to manage multiple " -"processes." -msgstr "" - -#: ../../howto/logging.rst:1115 -msgid "Set ``logging.logMultiprocessing`` to ``False``." -msgstr "將 ``logging.logMultiprocessing`` 設為 ``False``。" - -#: ../../howto/logging.rst:1118 -msgid "Current :class:`asyncio.Task` name when using ``asyncio``." -msgstr "" - -#: ../../howto/logging.rst:1118 -msgid "Set ``logging.logAsyncioTasks`` to ``False``." -msgstr "將 ``logging.logAsyncioTasks`` 設為 ``False``。" - -#: ../../howto/logging.rst:1122 -msgid "" -"Also note that the core logging module only includes the basic handlers. If " -"you don't import :mod:`logging.handlers` and :mod:`logging.config`, they " -"won't take up any memory." -msgstr "" - -#: ../../howto/logging.rst:1129 -msgid "Other resources" -msgstr "其他資源" - -#: ../../howto/logging.rst:1133 -msgid "Module :mod:`logging`" -msgstr ":mod:`logging` 模組" - -#: ../../howto/logging.rst:1134 -msgid "API reference for the logging module." -msgstr "" - -#: ../../howto/logging.rst:1136 -msgid "Module :mod:`logging.config`" -msgstr ":mod:`logging.config` 模組" - -#: ../../howto/logging.rst:1137 -msgid "Configuration API for the logging module." -msgstr "" - -#: ../../howto/logging.rst:1139 -msgid "Module :mod:`logging.handlers`" -msgstr ":mod:`logging.handlers` 模組" - -#: ../../howto/logging.rst:1140 -msgid "Useful handlers included with the logging module." -msgstr "" - -#: ../../howto/logging.rst:1142 -msgid ":ref:`A logging cookbook `" -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# 文俊 高 , 2016 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: 2018-05-23 14:36+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" + +#: ../../howto/logging.rst:5 +msgid "Logging HOWTO" +msgstr "如何使用 Logging 模組" + +#: ../../howto/logging.rst:0 +msgid "Author" +msgstr "作者" + +#: ../../howto/logging.rst:7 +msgid "Vinay Sajip " +msgstr "Vinay Sajip " + +#: ../../howto/logging.rst:13 +msgid "" +"This page contains tutorial information. For links to reference information " +"and a logging cookbook, please see :ref:`tutorial-ref-links`." +msgstr "" + +#: ../../howto/logging.rst:17 +msgid "Basic Logging Tutorial" +msgstr "基礎 Logging 指南" + +#: ../../howto/logging.rst:19 +msgid "" +"Logging is a means of tracking events that happen when some software runs. " +"The software's developer adds logging calls to their code to indicate that " +"certain events have occurred. An event is described by a descriptive message " +"which can optionally contain variable data (i.e. data that is potentially " +"different for each occurrence of the event). Events also have an importance " +"which the developer ascribes to the event; the importance can also be called " +"the *level* or *severity*." +msgstr "" +"軟體執行時，追蹤有什麼事件發生的動作稱為 Logging。軟體開發者會使用 Logging 這" +"樣的機制是因為想知道在運行過程中是否有特定的事件發生。事件會被一段訊息所描" +"述。這段訊息可能包含一些因為此事件發生而改變的資料。開發者也可以指派事件的重" +"要程度，重要程度有時候也會被稱作 *程度* 或是 *嚴重性* 。" + +#: ../../howto/logging.rst:28 +msgid "When to use logging" +msgstr "什麼時候使用 logging" + +#: ../../howto/logging.rst:30 +msgid "" +"You can access logging functionality by creating a logger via ``logger = " +"getLogger(__name__)``, and then calling the " +"logger's :meth:`~Logger.debug`, :meth:`~Logger.info`, :meth:`~Logger.warning`, :meth:`~Logger.error` " +"and :meth:`~Logger.critical` methods. To determine when to use logging, and " +"to see which logger methods to use when, see the table below. It states, for " +"each of a set of common tasks, the best tool to use for that task." +msgstr "" + +#: ../../howto/logging.rst:38 +msgid "Task you want to perform" +msgstr "" + +#: ../../howto/logging.rst:38 +msgid "The best tool for the task" +msgstr "" + +#: ../../howto/logging.rst:40 +msgid "" +"Display console output for ordinary usage of a command line script or program" +msgstr "" + +#: ../../howto/logging.rst:40 +msgid ":func:`print`" +msgstr ":func:`print`" + +#: ../../howto/logging.rst:44 +msgid "" +"Report events that occur during normal operation of a program (e.g. for " +"status monitoring or fault investigation)" +msgstr "" + +#: ../../howto/logging.rst:44 +msgid "" +"A logger's :meth:`~Logger.info` (or :meth:`~Logger.debug` method for very " +"detailed output for diagnostic purposes)" +msgstr "" + +#: ../../howto/logging.rst:49 +msgid "Issue a warning regarding a particular runtime event" +msgstr "" + +#: ../../howto/logging.rst:49 +msgid "" +":func:`warnings.warn` in library code if the issue is avoidable and the " +"client application should be modified to eliminate the warning" +msgstr "" + +#: ../../howto/logging.rst:54 +msgid "" +"A logger's :meth:`~Logger.warning` method if there is nothing the client " +"application can do about the situation, but the event should still be noted" +msgstr "" + +#: ../../howto/logging.rst:60 +msgid "Report an error regarding a particular runtime event" +msgstr "" + +#: ../../howto/logging.rst:60 +msgid "Raise an exception" +msgstr "引發一個例外" + +#: ../../howto/logging.rst:63 +msgid "" +"Report suppression of an error without raising an exception (e.g. error " +"handler in a long-running server process)" +msgstr "" + +#: ../../howto/logging.rst:63 +msgid "" +"A logger's :meth:`~Logger.error`, :meth:`~Logger.exception` " +"or :meth:`~Logger.critical` method as appropriate for the specific error and " +"application domain" +msgstr "" + +#: ../../howto/logging.rst:70 +msgid "" +"The logger methods are named after the level or severity of the events they " +"are used to track. The standard levels and their applicability are described " +"below (in increasing order of severity):" +msgstr "" + +#: ../../howto/logging.rst:77 ../../howto/logging.rst:875 +msgid "Level" +msgstr "" + +#: ../../howto/logging.rst:77 +msgid "When it's used" +msgstr "" + +#: ../../howto/logging.rst:79 ../../howto/logging.rst:885 +msgid "``DEBUG``" +msgstr "``DEBUG``" + +#: ../../howto/logging.rst:79 +msgid "" +"Detailed information, typically of interest only when diagnosing problems." +msgstr "" + +#: ../../howto/logging.rst:82 ../../howto/logging.rst:883 +msgid "``INFO``" +msgstr "``INFO``" + +#: ../../howto/logging.rst:82 +msgid "Confirmation that things are working as expected." +msgstr "" + +#: ../../howto/logging.rst:85 ../../howto/logging.rst:881 +msgid "``WARNING``" +msgstr "``WARNING``" + +#: ../../howto/logging.rst:85 +msgid "" +"An indication that something unexpected happened, or indicative of some " +"problem in the near future (e.g. 'disk space low'). The software is still " +"working as expected." +msgstr "" + +#: ../../howto/logging.rst:90 ../../howto/logging.rst:879 +msgid "``ERROR``" +msgstr "``ERROR``" + +#: ../../howto/logging.rst:90 +msgid "" +"Due to a more serious problem, the software has not been able to perform " +"some function." +msgstr "" + +#: ../../howto/logging.rst:93 ../../howto/logging.rst:877 +msgid "``CRITICAL``" +msgstr "``CRITICAL``" + +#: ../../howto/logging.rst:93 +msgid "" +"A serious error, indicating that the program itself may be unable to " +"continue running." +msgstr "" + +#: ../../howto/logging.rst:97 +msgid "" +"The default level is ``WARNING``, which means that only events of this " +"severity and higher will be tracked, unless the logging package is " +"configured to do otherwise." +msgstr "" + +#: ../../howto/logging.rst:100 +msgid "" +"Events that are tracked can be handled in different ways. The simplest way " +"of handling tracked events is to print them to the console. Another common " +"way is to write them to a disk file." +msgstr "" + +#: ../../howto/logging.rst:108 +msgid "A simple example" +msgstr "一個簡單範例" + +#: ../../howto/logging.rst:110 +msgid "A very simple example is::" +msgstr "一個非常簡單的例子是： ::" + +#: ../../howto/logging.rst:112 +msgid "" +"import logging\n" +"logging.warning('Watch out!') # will print a message to the console\n" +"logging.info('I told you so') # will not print anything" +msgstr "" +"import logging\n" +"logging.warning('Watch out!') # 將會印出訊息至控制台\n" +"logging.info('I told you so') # 不會印出任何東西" + +#: ../../howto/logging.rst:116 +msgid "If you type these lines into a script and run it, you'll see:" +msgstr "" + +#: ../../howto/logging.rst:118 +msgid "WARNING:root:Watch out!" +msgstr "WARNING:root:Watch out!" + +#: ../../howto/logging.rst:122 +msgid "" +"printed out on the console. The ``INFO`` message doesn't appear because the " +"default level is ``WARNING``. The printed message includes the indication of " +"the level and the description of the event provided in the logging call, " +"i.e. 'Watch out!'. The actual output can be formatted quite flexibly if you " +"need that; formatting options will also be explained later." +msgstr "" + +#: ../../howto/logging.rst:128 +msgid "" +"Notice that in this example, we use functions directly on the ``logging`` " +"module, like ``logging.debug``, rather than creating a logger and calling " +"functions on it. These functions operate on the root logger, but can be " +"useful as they will call :func:`~logging.basicConfig` for you if it has not " +"been called yet, like in this example. In larger programs you'll usually " +"want to control the logging configuration explicitly however - so for that " +"reason as well as others, it's better to create loggers and call their " +"methods." +msgstr "" + +#: ../../howto/logging.rst:137 +msgid "Logging to a file" +msgstr "" + +#: ../../howto/logging.rst:139 +msgid "" +"A very common situation is that of recording logging events in a file, so " +"let's look at that next. Be sure to try the following in a newly started " +"Python interpreter, and don't just continue from the session described " +"above::" +msgstr "" + +#: ../../howto/logging.rst:143 +msgid "" +"import logging\n" +"logger = logging.getLogger(__name__)\n" +"logging.basicConfig(filename='example.log', encoding='utf-8', " +"level=logging.DEBUG)\n" +"logger.debug('This message should go to the log file')\n" +"logger.info('So should this')\n" +"logger.warning('And this, too')\n" +"logger.error('And non-ASCII stuff, too, like Øresund and Malmö')" +msgstr "" +"import logging\n" +"logger = logging.getLogger(__name__)\n" +"logging.basicConfig(filename='example.log', encoding='utf-8', " +"level=logging.DEBUG)\n" +"logger.debug('This message should go to the log file')\n" +"logger.info('So should this')\n" +"logger.warning('And this, too')\n" +"logger.error('And non-ASCII stuff, too, like Øresund and Malmö')" + +#: ../../howto/logging.rst:151 +msgid "" +"The *encoding* argument was added. In earlier Python versions, or if not " +"specified, the encoding used is the default value used by :func:`open`. " +"While not shown in the above example, an *errors* argument can also now be " +"passed, which determines how encoding errors are handled. For available " +"values and the default, see the documentation for :func:`open`." +msgstr "" + +#: ../../howto/logging.rst:158 +msgid "" +"And now if we open the file and look at what we have, we should find the log " +"messages:" +msgstr "" + +#: ../../howto/logging.rst:161 +msgid "" +"DEBUG:__main__:This message should go to the log file\n" +"INFO:__main__:So should this\n" +"WARNING:__main__:And this, too\n" +"ERROR:__main__:And non-ASCII stuff, too, like Øresund and Malmö" +msgstr "" + +#: ../../howto/logging.rst:168 +msgid "" +"This example also shows how you can set the logging level which acts as the " +"threshold for tracking. In this case, because we set the threshold to " +"``DEBUG``, all of the messages were printed." +msgstr "" + +#: ../../howto/logging.rst:172 +msgid "" +"If you want to set the logging level from a command-line option such as:" +msgstr "" + +#: ../../howto/logging.rst:174 +msgid "--log=INFO" +msgstr "--log=INFO" + +#: ../../howto/logging.rst:178 +msgid "" +"and you have the value of the parameter passed for ``--log`` in some " +"variable *loglevel*, you can use::" +msgstr "" + +#: ../../howto/logging.rst:181 +msgid "getattr(logging, loglevel.upper())" +msgstr "getattr(logging, loglevel.upper())" + +#: ../../howto/logging.rst:183 +msgid "" +"to get the value which you'll pass to :func:`basicConfig` via the *level* " +"argument. You may want to error check any user input value, perhaps as in " +"the following example::" +msgstr "" + +#: ../../howto/logging.rst:187 +msgid "" +"# assuming loglevel is bound to the string value obtained from the\n" +"# command line argument. Convert to upper case to allow the user to\n" +"# specify --log=DEBUG or --log=debug\n" +"numeric_level = getattr(logging, loglevel.upper(), None)\n" +"if not isinstance(numeric_level, int):\n" +" raise ValueError('Invalid log level: %s' % loglevel)\n" +"logging.basicConfig(level=numeric_level, ...)" +msgstr "" + +#: ../../howto/logging.rst:195 +msgid "" +"The call to :func:`basicConfig` should come *before* any calls to a logger's " +"methods such as :meth:`~Logger.debug`, :meth:`~Logger.info`, etc. Otherwise, " +"that logging event may not be handled in the desired manner." +msgstr "" + +#: ../../howto/logging.rst:199 +msgid "" +"If you run the above script several times, the messages from successive runs " +"are appended to the file *example.log*. If you want each run to start " +"afresh, not remembering the messages from earlier runs, you can specify the " +"*filemode* argument, by changing the call in the above example to::" +msgstr "" + +#: ../../howto/logging.rst:204 +msgid "" +"logging.basicConfig(filename='example.log', filemode='w', " +"level=logging.DEBUG)" +msgstr "" +"logging.basicConfig(filename='example.log', filemode='w', " +"level=logging.DEBUG)" + +#: ../../howto/logging.rst:206 +msgid "" +"The output will be the same as before, but the log file is no longer " +"appended to, so the messages from earlier runs are lost." +msgstr "" + +#: ../../howto/logging.rst:211 +msgid "Logging variable data" +msgstr "" + +#: ../../howto/logging.rst:213 +msgid "" +"To log variable data, use a format string for the event description message " +"and append the variable data as arguments. For example::" +msgstr "" + +#: ../../howto/logging.rst:216 +msgid "" +"import logging\n" +"logging.warning('%s before you %s', 'Look', 'leap!')" +msgstr "" +"import logging\n" +"logging.warning('%s before you %s', 'Look', 'leap!')" + +#: ../../howto/logging.rst:219 +msgid "will display:" +msgstr "" + +#: ../../howto/logging.rst:221 +msgid "WARNING:root:Look before you leap!" +msgstr "WARNING:root:Look before you leap!" + +#: ../../howto/logging.rst:225 +msgid "" +"As you can see, merging of variable data into the event description message " +"uses the old, %-style of string formatting. This is for backwards " +"compatibility: the logging package pre-dates newer formatting options such " +"as :meth:`str.format` and :class:`string.Template`. These newer formatting " +"options *are* supported, but exploring them is outside the scope of this " +"tutorial: see :ref:`formatting-styles` for more information." +msgstr "" + +#: ../../howto/logging.rst:234 +msgid "Changing the format of displayed messages" +msgstr "" + +#: ../../howto/logging.rst:236 +msgid "" +"To change the format which is used to display messages, you need to specify " +"the format you want to use::" +msgstr "" + +#: ../../howto/logging.rst:239 +msgid "" +"import logging\n" +"logging.basicConfig(format='%(levelname)s:%(message)s', " +"level=logging.DEBUG)\n" +"logging.debug('This message should appear on the console')\n" +"logging.info('So should this')\n" +"logging.warning('And this, too')" +msgstr "" +"import logging\n" +"logging.basicConfig(format='%(levelname)s:%(message)s', " +"level=logging.DEBUG)\n" +"logging.debug('This message should appear on the console')\n" +"logging.info('So should this')\n" +"logging.warning('And this, too')" + +#: ../../howto/logging.rst:245 +msgid "which would print:" +msgstr "" + +#: ../../howto/logging.rst:247 +msgid "" +"DEBUG:This message should appear on the console\n" +"INFO:So should this\n" +"WARNING:And this, too" +msgstr "" + +#: ../../howto/logging.rst:253 +msgid "" +"Notice that the 'root' which appeared in earlier examples has disappeared. " +"For a full set of things that can appear in format strings, you can refer to " +"the documentation for :ref:`logrecord-attributes`, but for simple usage, you " +"just need the *levelname* (severity), *message* (event description, " +"including variable data) and perhaps to display when the event occurred. " +"This is described in the next section." +msgstr "" + +#: ../../howto/logging.rst:262 +msgid "Displaying the date/time in messages" +msgstr "" + +#: ../../howto/logging.rst:264 +msgid "" +"To display the date and time of an event, you would place '%(asctime)s' in " +"your format string::" +msgstr "" + +#: ../../howto/logging.rst:267 +msgid "" +"import logging\n" +"logging.basicConfig(format='%(asctime)s %(message)s')\n" +"logging.warning('is when this event was logged.')" +msgstr "" +"import logging\n" +"logging.basicConfig(format='%(asctime)s %(message)s')\n" +"logging.warning('is when this event was logged.')" + +#: ../../howto/logging.rst:271 +msgid "which should print something like this:" +msgstr "" + +#: ../../howto/logging.rst:273 +msgid "2010-12-12 11:41:42,612 is when this event was logged." +msgstr "" + +#: ../../howto/logging.rst:277 +msgid "" +"The default format for date/time display (shown above) is like ISO8601 " +"or :rfc:`3339`. If you need more control over the formatting of the date/" +"time, provide a *datefmt* argument to ``basicConfig``, as in this example::" +msgstr "" + +#: ../../howto/logging.rst:281 +msgid "" +"import logging\n" +"logging.basicConfig(format='%(asctime)s %(message)s', datefmt='%m/%d/%Y %I:" +"%M:%S %p')\n" +"logging.warning('is when this event was logged.')" +msgstr "" +"import logging\n" +"logging.basicConfig(format='%(asctime)s %(message)s', datefmt='%m/%d/%Y %I:" +"%M:%S %p')\n" +"logging.warning('is when this event was logged.')" + +#: ../../howto/logging.rst:285 +msgid "which would display something like this:" +msgstr "" + +#: ../../howto/logging.rst:287 +msgid "12/12/2010 11:46:36 AM is when this event was logged." +msgstr "" + +#: ../../howto/logging.rst:291 +msgid "" +"The format of the *datefmt* argument is the same as supported " +"by :func:`time.strftime`." +msgstr "" + +#: ../../howto/logging.rst:296 +msgid "Next Steps" +msgstr "" + +#: ../../howto/logging.rst:298 +msgid "" +"That concludes the basic tutorial. It should be enough to get you up and " +"running with logging. There's a lot more that the logging package offers, " +"but to get the best out of it, you'll need to invest a little more of your " +"time in reading the following sections. If you're ready for that, grab some " +"of your favourite beverage and carry on." +msgstr "" + +#: ../../howto/logging.rst:304 +msgid "" +"If your logging needs are simple, then use the above examples to incorporate " +"logging into your own scripts, and if you run into problems or don't " +"understand something, please post a question in the Help category of the " +"`Python discussion forum `_ and you " +"should receive help before too long." +msgstr "" + +#: ../../howto/logging.rst:310 +msgid "" +"Still here? You can carry on reading the next few sections, which provide a " +"slightly more advanced/in-depth tutorial than the basic one above. After " +"that, you can take a look at the :ref:`logging-cookbook`." +msgstr "" + +#: ../../howto/logging.rst:318 +msgid "Advanced Logging Tutorial" +msgstr "" + +#: ../../howto/logging.rst:320 +msgid "" +"The logging library takes a modular approach and offers several categories " +"of components: loggers, handlers, filters, and formatters." +msgstr "" + +#: ../../howto/logging.rst:323 +msgid "Loggers expose the interface that application code directly uses." +msgstr "" + +#: ../../howto/logging.rst:324 +msgid "" +"Handlers send the log records (created by loggers) to the appropriate " +"destination." +msgstr "" + +#: ../../howto/logging.rst:326 +msgid "" +"Filters provide a finer grained facility for determining which log records " +"to output." +msgstr "" + +#: ../../howto/logging.rst:328 +msgid "Formatters specify the layout of log records in the final output." +msgstr "" + +#: ../../howto/logging.rst:330 +msgid "" +"Log event information is passed between loggers, handlers, filters and " +"formatters in a :class:`LogRecord` instance." +msgstr "" + +#: ../../howto/logging.rst:333 +msgid "" +"Logging is performed by calling methods on instances of the :class:`Logger` " +"class (hereafter called :dfn:`loggers`). Each instance has a name, and they " +"are conceptually arranged in a namespace hierarchy using dots (periods) as " +"separators. For example, a logger named 'scan' is the parent of loggers " +"'scan.text', 'scan.html' and 'scan.pdf'. Logger names can be anything you " +"want, and indicate the area of an application in which a logged message " +"originates." +msgstr "" + +#: ../../howto/logging.rst:340 +msgid "" +"A good convention to use when naming loggers is to use a module-level " +"logger, in each module which uses logging, named as follows::" +msgstr "" + +#: ../../howto/logging.rst:343 +msgid "logger = logging.getLogger(__name__)" +msgstr "logger = logging.getLogger(__name__)" + +#: ../../howto/logging.rst:345 +msgid "" +"This means that logger names track the package/module hierarchy, and it's " +"intuitively obvious where events are logged just from the logger name." +msgstr "" + +#: ../../howto/logging.rst:348 +msgid "" +"The root of the hierarchy of loggers is called the root logger. That's the " +"logger used by the " +"functions :func:`debug`, :func:`info`, :func:`warning`, :func:`error` " +"and :func:`critical`, which just call the same-named method of the root " +"logger. The functions and the methods have the same signatures. The root " +"logger's name is printed as 'root' in the logged output." +msgstr "" + +#: ../../howto/logging.rst:354 +msgid "" +"It is, of course, possible to log messages to different destinations. " +"Support is included in the package for writing log messages to files, HTTP " +"GET/POST locations, email via SMTP, generic sockets, queues, or OS-specific " +"logging mechanisms such as syslog or the Windows NT event log. Destinations " +"are served by :dfn:`handler` classes. You can create your own log " +"destination class if you have special requirements not met by any of the " +"built-in handler classes." +msgstr "" + +#: ../../howto/logging.rst:361 +msgid "" +"By default, no destination is set for any logging messages. You can specify " +"a destination (such as console or file) by using :func:`basicConfig` as in " +"the tutorial examples. If you call the " +"functions :func:`debug`, :func:`info`, :func:`warning`, :func:`error` " +"and :func:`critical`, they will check to see if no destination is set; and " +"if one is not set, they will set a destination of the console " +"(``sys.stderr``) and a default format for the displayed message before " +"delegating to the root logger to do the actual message output." +msgstr "" + +#: ../../howto/logging.rst:369 +msgid "The default format set by :func:`basicConfig` for messages is:" +msgstr "" + +#: ../../howto/logging.rst:371 +msgid "severity:logger name:message" +msgstr "severity:logger name:message" + +#: ../../howto/logging.rst:375 +msgid "" +"You can change this by passing a format string to :func:`basicConfig` with " +"the *format* keyword argument. For all options regarding how a format string " +"is constructed, see :ref:`formatter-objects`." +msgstr "" + +#: ../../howto/logging.rst:380 +msgid "Logging Flow" +msgstr "" + +#: ../../howto/logging.rst:382 +msgid "" +"The flow of log event information in loggers and handlers is illustrated in " +"the following diagram." +msgstr "" + +#: ../../howto/logging.rst:433 +msgid "Loggers" +msgstr "" + +#: ../../howto/logging.rst:435 +msgid "" +":class:`Logger` objects have a threefold job. First, they expose several " +"methods to application code so that applications can log messages at " +"runtime. Second, logger objects determine which log messages to act upon " +"based upon severity (the default filtering facility) or filter objects. " +"Third, logger objects pass along relevant log messages to all interested log " +"handlers." +msgstr "" + +#: ../../howto/logging.rst:441 +msgid "" +"The most widely used methods on logger objects fall into two categories: " +"configuration and message sending." +msgstr "" + +#: ../../howto/logging.rst:444 +msgid "These are the most common configuration methods:" +msgstr "" + +#: ../../howto/logging.rst:446 +msgid "" +":meth:`Logger.setLevel` specifies the lowest-severity log message a logger " +"will handle, where debug is the lowest built-in severity level and critical " +"is the highest built-in severity. For example, if the severity level is " +"INFO, the logger will handle only INFO, WARNING, ERROR, and CRITICAL " +"messages and will ignore DEBUG messages." +msgstr "" + +#: ../../howto/logging.rst:452 +msgid "" +":meth:`Logger.addHandler` and :meth:`Logger.removeHandler` add and remove " +"handler objects from the logger object. Handlers are covered in more detail " +"in :ref:`handler-basic`." +msgstr "" + +#: ../../howto/logging.rst:456 +msgid "" +":meth:`Logger.addFilter` and :meth:`Logger.removeFilter` add and remove " +"filter objects from the logger object. Filters are covered in more detail " +"in :ref:`filter`." +msgstr "" + +#: ../../howto/logging.rst:460 +msgid "" +"You don't need to always call these methods on every logger you create. See " +"the last two paragraphs in this section." +msgstr "" + +#: ../../howto/logging.rst:463 +msgid "" +"With the logger object configured, the following methods create log messages:" +msgstr "" + +#: ../../howto/logging.rst:465 +msgid "" +":meth:`Logger.debug`, :meth:`Logger.info`, :meth:`Logger.warning`, :meth:`Logger.error`, " +"and :meth:`Logger.critical` all create log records with a message and a " +"level that corresponds to their respective method names. The message is " +"actually a format string, which may contain the standard string substitution " +"syntax of ``%s``, ``%d``, ``%f``, and so on. The rest of their arguments is " +"a list of objects that correspond with the substitution fields in the " +"message. With regard to ``**kwargs``, the logging methods care only about a " +"keyword of ``exc_info`` and use it to determine whether to log exception " +"information." +msgstr "" + +#: ../../howto/logging.rst:475 +msgid "" +":meth:`Logger.exception` creates a log message similar " +"to :meth:`Logger.error`. The difference is that :meth:`Logger.exception` " +"dumps a stack trace along with it. Call this method only from an exception " +"handler." +msgstr "" + +#: ../../howto/logging.rst:479 +msgid "" +":meth:`Logger.log` takes a log level as an explicit argument. This is a " +"little more verbose for logging messages than using the log level " +"convenience methods listed above, but this is how to log at custom log " +"levels." +msgstr "" + +#: ../../howto/logging.rst:483 +msgid "" +":func:`getLogger` returns a reference to a logger instance with the " +"specified name if it is provided, or ``root`` if not. The names are period-" +"separated hierarchical structures. Multiple calls to :func:`getLogger` with " +"the same name will return a reference to the same logger object. Loggers " +"that are further down in the hierarchical list are children of loggers " +"higher up in the list. For example, given a logger with a name of ``foo``, " +"loggers with names of ``foo.bar``, ``foo.bar.baz``, and ``foo.bam`` are all " +"descendants of ``foo``." +msgstr "" + +#: ../../howto/logging.rst:491 +msgid "" +"Loggers have a concept of *effective level*. If a level is not explicitly " +"set on a logger, the level of its parent is used instead as its effective " +"level. If the parent has no explicit level set, *its* parent is examined, " +"and so on - all ancestors are searched until an explicitly set level is " +"found. The root logger always has an explicit level set (``WARNING`` by " +"default). When deciding whether to process an event, the effective level of " +"the logger is used to determine whether the event is passed to the logger's " +"handlers." +msgstr "" + +#: ../../howto/logging.rst:499 +msgid "" +"Child loggers propagate messages up to the handlers associated with their " +"ancestor loggers. Because of this, it is unnecessary to define and configure " +"handlers for all the loggers an application uses. It is sufficient to " +"configure handlers for a top-level logger and create child loggers as " +"needed. (You can, however, turn off propagation by setting the *propagate* " +"attribute of a logger to ``False``.)" +msgstr "" + +#: ../../howto/logging.rst:510 +msgid "Handlers" +msgstr "" + +#: ../../howto/logging.rst:512 +msgid "" +":class:`~logging.Handler` objects are responsible for dispatching the " +"appropriate log messages (based on the log messages' severity) to the " +"handler's specified destination. :class:`Logger` objects can add zero or " +"more handler objects to themselves with an :meth:`~Logger.addHandler` " +"method. As an example scenario, an application may want to send all log " +"messages to a log file, all log messages of error or higher to stdout, and " +"all messages of critical to an email address. This scenario requires three " +"individual handlers where each handler is responsible for sending messages " +"of a specific severity to a specific location." +msgstr "" + +#: ../../howto/logging.rst:522 +msgid "" +"The standard library includes quite a few handler types (see :ref:`useful-" +"handlers`); the tutorials use mainly :class:`StreamHandler` " +"and :class:`FileHandler` in its examples." +msgstr "" + +#: ../../howto/logging.rst:526 +msgid "" +"There are very few methods in a handler for application developers to " +"concern themselves with. The only handler methods that seem relevant for " +"application developers who are using the built-in handler objects (that is, " +"not creating custom handlers) are the following configuration methods:" +msgstr "" + +#: ../../howto/logging.rst:531 +msgid "" +"The :meth:`~Handler.setLevel` method, just as in logger objects, specifies " +"the lowest severity that will be dispatched to the appropriate destination. " +"Why are there two :meth:`~Handler.setLevel` methods? The level set in the " +"logger determines which severity of messages it will pass to its handlers. " +"The level set in each handler determines which messages that handler will " +"send on." +msgstr "" + +#: ../../howto/logging.rst:537 +msgid "" +":meth:`~Handler.setFormatter` selects a Formatter object for this handler to " +"use." +msgstr "" + +#: ../../howto/logging.rst:540 +msgid "" +":meth:`~Handler.addFilter` and :meth:`~Handler.removeFilter` respectively " +"configure and deconfigure filter objects on handlers." +msgstr "" + +#: ../../howto/logging.rst:543 +msgid "" +"Application code should not directly instantiate and use instances " +"of :class:`Handler`. Instead, the :class:`Handler` class is a base class " +"that defines the interface that all handlers should have and establishes " +"some default behavior that child classes can use (or override)." +msgstr "" + +#: ../../howto/logging.rst:550 +msgid "Formatters" +msgstr "" + +#: ../../howto/logging.rst:552 +msgid "" +"Formatter objects configure the final order, structure, and contents of the " +"log message. Unlike the base :class:`logging.Handler` class, application " +"code may instantiate formatter classes, although you could likely subclass " +"the formatter if your application needs special behavior. The constructor " +"takes three optional arguments -- a message format string, a date format " +"string and a style indicator." +msgstr "" + +#: ../../howto/logging.rst:561 +msgid "" +"If there is no message format string, the default is to use the raw " +"message. If there is no date format string, the default date format is:" +msgstr "" + +#: ../../howto/logging.rst:564 +msgid "%Y-%m-%d %H:%M:%S" +msgstr "%Y-%m-%d %H:%M:%S" + +#: ../../howto/logging.rst:568 +msgid "" +"with the milliseconds tacked on at the end. The ``style`` is one of ``'%'``, " +"``'{'``, or ``'$'``. If one of these is not specified, then ``'%'`` will be " +"used." +msgstr "" + +#: ../../howto/logging.rst:571 +msgid "" +"If the ``style`` is ``'%'``, the message format string uses ``%()s`` styled string substitution; the possible keys are documented " +"in :ref:`logrecord-attributes`. If the style is ``'{'``, the message format " +"string is assumed to be compatible with :meth:`str.format` (using keyword " +"arguments), while if the style is ``'$'`` then the message format string " +"should conform to what is expected by :meth:`string.Template.substitute`." +msgstr "" + +#: ../../howto/logging.rst:578 +msgid "Added the ``style`` parameter." +msgstr "新增 ``style`` 參數。" + +#: ../../howto/logging.rst:581 +msgid "" +"The following message format string will log the time in a human-readable " +"format, the severity of the message, and the contents of the message, in " +"that order::" +msgstr "" + +#: ../../howto/logging.rst:585 +msgid "'%(asctime)s - %(levelname)s - %(message)s'" +msgstr "" + +#: ../../howto/logging.rst:587 +msgid "" +"Formatters use a user-configurable function to convert the creation time of " +"a record to a tuple. By default, :func:`time.localtime` is used; to change " +"this for a particular formatter instance, set the ``converter`` attribute of " +"the instance to a function with the same signature as :func:`time.localtime` " +"or :func:`time.gmtime`. To change it for all formatters, for example if you " +"want all logging times to be shown in GMT, set the ``converter`` attribute " +"in the Formatter class (to ``time.gmtime`` for GMT display)." +msgstr "" + +#: ../../howto/logging.rst:597 +msgid "Configuring Logging" +msgstr "" + +#: ../../howto/logging.rst:601 +msgid "Programmers can configure logging in three ways:" +msgstr "" + +#: ../../howto/logging.rst:603 +msgid "" +"Creating loggers, handlers, and formatters explicitly using Python code that " +"calls the configuration methods listed above." +msgstr "" + +#: ../../howto/logging.rst:605 +msgid "" +"Creating a logging config file and reading it using the :func:`fileConfig` " +"function." +msgstr "" + +#: ../../howto/logging.rst:607 +msgid "" +"Creating a dictionary of configuration information and passing it to " +"the :func:`dictConfig` function." +msgstr "" + +#: ../../howto/logging.rst:610 +msgid "" +"For the reference documentation on the last two options, see :ref:`logging-" +"config-api`. The following example configures a very simple logger, a " +"console handler, and a simple formatter using Python code::" +msgstr "" + +#: ../../howto/logging.rst:614 +msgid "" +"import logging\n" +"\n" +"# create logger\n" +"logger = logging.getLogger('simple_example')\n" +"logger.setLevel(logging.DEBUG)\n" +"\n" +"# create console handler and set level to debug\n" +"ch = logging.StreamHandler()\n" +"ch.setLevel(logging.DEBUG)\n" +"\n" +"# create formatter\n" +"formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %" +"(message)s')\n" +"\n" +"# add formatter to ch\n" +"ch.setFormatter(formatter)\n" +"\n" +"# add ch to logger\n" +"logger.addHandler(ch)\n" +"\n" +"# 'application' code\n" +"logger.debug('debug message')\n" +"logger.info('info message')\n" +"logger.warning('warn message')\n" +"logger.error('error message')\n" +"logger.critical('critical message')" +msgstr "" + +#: ../../howto/logging.rst:640 +msgid "" +"Running this module from the command line produces the following output:" +msgstr "" + +#: ../../howto/logging.rst:642 +msgid "" +"$ python simple_logging_module.py\n" +"2005-03-19 15:10:26,618 - simple_example - DEBUG - debug message\n" +"2005-03-19 15:10:26,620 - simple_example - INFO - info message\n" +"2005-03-19 15:10:26,695 - simple_example - WARNING - warn message\n" +"2005-03-19 15:10:26,697 - simple_example - ERROR - error message\n" +"2005-03-19 15:10:26,773 - simple_example - CRITICAL - critical message" +msgstr "" + +#: ../../howto/logging.rst:651 +msgid "" +"The following Python module creates a logger, handler, and formatter nearly " +"identical to those in the example listed above, with the only difference " +"being the names of the objects::" +msgstr "" + +#: ../../howto/logging.rst:655 +msgid "" +"import logging\n" +"import logging.config\n" +"\n" +"logging.config.fileConfig('logging.conf')\n" +"\n" +"# create logger\n" +"logger = logging.getLogger('simpleExample')\n" +"\n" +"# 'application' code\n" +"logger.debug('debug message')\n" +"logger.info('info message')\n" +"logger.warning('warn message')\n" +"logger.error('error message')\n" +"logger.critical('critical message')" +msgstr "" + +#: ../../howto/logging.rst:670 +msgid "Here is the logging.conf file:" +msgstr "" + +#: ../../howto/logging.rst:672 +msgid "" +"[loggers]\n" +"keys=root,simpleExample\n" +"\n" +"[handlers]\n" +"keys=consoleHandler\n" +"\n" +"[formatters]\n" +"keys=simpleFormatter\n" +"\n" +"[logger_root]\n" +"level=DEBUG\n" +"handlers=consoleHandler\n" +"\n" +"[logger_simpleExample]\n" +"level=DEBUG\n" +"handlers=consoleHandler\n" +"qualname=simpleExample\n" +"propagate=0\n" +"\n" +"[handler_consoleHandler]\n" +"class=StreamHandler\n" +"level=DEBUG\n" +"formatter=simpleFormatter\n" +"args=(sys.stdout,)\n" +"\n" +"[formatter_simpleFormatter]\n" +"format=%(asctime)s - %(name)s - %(levelname)s - %(message)s" +msgstr "" + +#: ../../howto/logging.rst:702 +msgid "" +"The output is nearly identical to that of the non-config-file-based example:" +msgstr "" + +#: ../../howto/logging.rst:704 +msgid "" +"$ python simple_logging_config.py\n" +"2005-03-19 15:38:55,977 - simpleExample - DEBUG - debug message\n" +"2005-03-19 15:38:55,979 - simpleExample - INFO - info message\n" +"2005-03-19 15:38:56,054 - simpleExample - WARNING - warn message\n" +"2005-03-19 15:38:56,055 - simpleExample - ERROR - error message\n" +"2005-03-19 15:38:56,130 - simpleExample - CRITICAL - critical message" +msgstr "" + +#: ../../howto/logging.rst:713 +msgid "" +"You can see that the config file approach has a few advantages over the " +"Python code approach, mainly separation of configuration and code and the " +"ability of noncoders to easily modify the logging properties." +msgstr "" + +#: ../../howto/logging.rst:717 +msgid "" +"The :func:`fileConfig` function takes a default parameter, " +"``disable_existing_loggers``, which defaults to ``True`` for reasons of " +"backward compatibility. This may or may not be what you want, since it will " +"cause any non-root loggers existing before the :func:`fileConfig` call to be " +"disabled unless they (or an ancestor) are explicitly named in the " +"configuration. Please refer to the reference documentation for more " +"information, and specify ``False`` for this parameter if you wish." +msgstr "" + +#: ../../howto/logging.rst:725 +msgid "" +"The dictionary passed to :func:`dictConfig` can also specify a Boolean value " +"with key ``disable_existing_loggers``, which if not specified explicitly in " +"the dictionary also defaults to being interpreted as ``True``. This leads to " +"the logger-disabling behaviour described above, which may not be what you " +"want - in which case, provide the key explicitly with a value of ``False``." +msgstr "" + +#: ../../howto/logging.rst:735 +msgid "" +"Note that the class names referenced in config files need to be either " +"relative to the logging module, or absolute values which can be resolved " +"using normal import mechanisms. Thus, you could use " +"either :class:`~logging.handlers.WatchedFileHandler` (relative to the " +"logging module) or ``mypackage.mymodule.MyHandler`` (for a class defined in " +"package ``mypackage`` and module ``mymodule``, where ``mypackage`` is " +"available on the Python import path)." +msgstr "" + +#: ../../howto/logging.rst:743 +msgid "" +"In Python 3.2, a new means of configuring logging has been introduced, using " +"dictionaries to hold configuration information. This provides a superset of " +"the functionality of the config-file-based approach outlined above, and is " +"the recommended configuration method for new applications and deployments. " +"Because a Python dictionary is used to hold configuration information, and " +"since you can populate that dictionary using different means, you have more " +"options for configuration. For example, you can use a configuration file in " +"JSON format, or, if you have access to YAML processing functionality, a file " +"in YAML format, to populate the configuration dictionary. Or, of course, you " +"can construct the dictionary in Python code, receive it in pickled form over " +"a socket, or use whatever approach makes sense for your application." +msgstr "" + +#: ../../howto/logging.rst:755 +msgid "" +"Here's an example of the same configuration as above, in YAML format for the " +"new dictionary-based approach:" +msgstr "" + +#: ../../howto/logging.rst:758 +msgid "" +"version: 1\n" +"formatters:\n" +" simple:\n" +" format: '%(asctime)s - %(name)s - %(levelname)s - %(message)s'\n" +"handlers:\n" +" console:\n" +" class: logging.StreamHandler\n" +" level: DEBUG\n" +" formatter: simple\n" +" stream: ext://sys.stdout\n" +"loggers:\n" +" simpleExample:\n" +" level: DEBUG\n" +" handlers: [console]\n" +" propagate: no\n" +"root:\n" +" level: DEBUG\n" +" handlers: [console]" +msgstr "" + +#: ../../howto/logging.rst:779 +msgid "" +"For more information about logging using a dictionary, see :ref:`logging-" +"config-api`." +msgstr "" + +#: ../../howto/logging.rst:783 +msgid "What happens if no configuration is provided" +msgstr "" + +#: ../../howto/logging.rst:785 +msgid "" +"If no logging configuration is provided, it is possible to have a situation " +"where a logging event needs to be output, but no handlers can be found to " +"output the event." +msgstr "" + +#: ../../howto/logging.rst:789 +msgid "" +"The event is output using a 'handler of last resort', stored " +"in :data:`lastResort`. This internal handler is not associated with any " +"logger, and acts like a :class:`~logging.StreamHandler` which writes the " +"event description message to the current value of ``sys.stderr`` (therefore " +"respecting any redirections which may be in effect). No formatting is done " +"on the message - just the bare event description message is printed. The " +"handler's level is set to ``WARNING``, so all events at this and greater " +"severities will be output." +msgstr "" + +#: ../../howto/logging.rst:800 +msgid "For versions of Python prior to 3.2, the behaviour is as follows:" +msgstr "" + +#: ../../howto/logging.rst:802 +msgid "" +"If :data:`raiseExceptions` is ``False`` (production mode), the event is " +"silently dropped." +msgstr "" + +#: ../../howto/logging.rst:805 +msgid "" +"If :data:`raiseExceptions` is ``True`` (development mode), a message 'No " +"handlers could be found for logger X.Y.Z' is printed once." +msgstr "" + +#: ../../howto/logging.rst:808 +msgid "" +"To obtain the pre-3.2 behaviour, :data:`lastResort` can be set to ``None``." +msgstr "" + +#: ../../howto/logging.rst:814 +msgid "Configuring Logging for a Library" +msgstr "" + +#: ../../howto/logging.rst:816 +msgid "" +"When developing a library which uses logging, you should take care to " +"document how the library uses logging - for example, the names of loggers " +"used. Some consideration also needs to be given to its logging " +"configuration. If the using application does not use logging, and library " +"code makes logging calls, then (as described in the previous section) events " +"of severity ``WARNING`` and greater will be printed to ``sys.stderr``. This " +"is regarded as the best default behaviour." +msgstr "" + +#: ../../howto/logging.rst:824 +msgid "" +"If for some reason you *don't* want these messages printed in the absence of " +"any logging configuration, you can attach a do-nothing handler to the top-" +"level logger for your library. This avoids the message being printed, since " +"a handler will always be found for the library's events: it just doesn't " +"produce any output. If the library user configures logging for application " +"use, presumably that configuration will add some handlers, and if levels are " +"suitably configured then logging calls made in library code will send output " +"to those handlers, as normal." +msgstr "" + +#: ../../howto/logging.rst:833 +msgid "" +"A do-nothing handler is included in the logging " +"package: :class:`~logging.NullHandler` (since Python 3.1). An instance of " +"this handler could be added to the top-level logger of the logging namespace " +"used by the library (*if* you want to prevent your library's logged events " +"being output to ``sys.stderr`` in the absence of logging configuration). If " +"all logging by a library *foo* is done using loggers with names matching " +"'foo.x', 'foo.x.y', etc. then the code::" +msgstr "" + +#: ../../howto/logging.rst:841 +msgid "" +"import logging\n" +"logging.getLogger('foo').addHandler(logging.NullHandler())" +msgstr "" +"import logging\n" +"logging.getLogger('foo').addHandler(logging.NullHandler())" + +#: ../../howto/logging.rst:844 +msgid "" +"should have the desired effect. If an organisation produces a number of " +"libraries, then the logger name specified can be 'orgname.foo' rather than " +"just 'foo'." +msgstr "" + +#: ../../howto/logging.rst:848 +msgid "" +"It is strongly advised that you *do not log to the root logger* in your " +"library. Instead, use a logger with a unique and easily identifiable name, " +"such as the ``__name__`` for your library's top-level package or module. " +"Logging to the root logger will make it difficult or impossible for the " +"application developer to configure the logging verbosity or handlers of your " +"library as they wish." +msgstr "" + +#: ../../howto/logging.rst:855 +msgid "" +"It is strongly advised that you *do not add any handlers other " +"than* :class:`~logging.NullHandler` *to your library's loggers*. This is " +"because the configuration of handlers is the prerogative of the application " +"developer who uses your library. The application developer knows their " +"target audience and what handlers are most appropriate for their " +"application: if you add handlers 'under the hood', you might well interfere " +"with their ability to carry out unit tests and deliver logs which suit their " +"requirements." +msgstr "" + +#: ../../howto/logging.rst:866 +msgid "Logging Levels" +msgstr "" + +#: ../../howto/logging.rst:868 +msgid "" +"The numeric values of logging levels are given in the following table. These " +"are primarily of interest if you want to define your own levels, and need " +"them to have specific values relative to the predefined levels. If you " +"define a level with the same numeric value, it overwrites the predefined " +"value; the predefined name is lost." +msgstr "" + +#: ../../howto/logging.rst:875 +msgid "Numeric value" +msgstr "" + +#: ../../howto/logging.rst:877 +msgid "50" +msgstr "50" + +#: ../../howto/logging.rst:879 +msgid "40" +msgstr "40" + +#: ../../howto/logging.rst:881 +msgid "30" +msgstr "30" + +#: ../../howto/logging.rst:883 +msgid "20" +msgstr "20" + +#: ../../howto/logging.rst:885 +msgid "10" +msgstr "10" + +#: ../../howto/logging.rst:887 +msgid "``NOTSET``" +msgstr "``NOTSET``" + +#: ../../howto/logging.rst:887 +msgid "0" +msgstr "0" + +#: ../../howto/logging.rst:890 +msgid "" +"Levels can also be associated with loggers, being set either by the " +"developer or through loading a saved logging configuration. When a logging " +"method is called on a logger, the logger compares its own level with the " +"level associated with the method call. If the logger's level is higher than " +"the method call's, no logging message is actually generated. This is the " +"basic mechanism controlling the verbosity of logging output." +msgstr "" + +#: ../../howto/logging.rst:897 +msgid "" +"Logging messages are encoded as instances of the :class:`~logging.LogRecord` " +"class. When a logger decides to actually log an event, " +"a :class:`~logging.LogRecord` instance is created from the logging message." +msgstr "" + +#: ../../howto/logging.rst:901 +msgid "" +"Logging messages are subjected to a dispatch mechanism through the use " +"of :dfn:`handlers`, which are instances of subclasses of " +"the :class:`Handler` class. Handlers are responsible for ensuring that a " +"logged message (in the form of a :class:`LogRecord`) ends up in a particular " +"location (or set of locations) which is useful for the target audience for " +"that message (such as end users, support desk staff, system administrators, " +"developers). Handlers are passed :class:`LogRecord` instances intended for " +"particular destinations. Each logger can have zero, one or more handlers " +"associated with it (via the :meth:`~Logger.addHandler` method " +"of :class:`Logger`). In addition to any handlers directly associated with a " +"logger, *all handlers associated with all ancestors of the logger* are " +"called to dispatch the message (unless the *propagate* flag for a logger is " +"set to a false value, at which point the passing to ancestor handlers stops)." +msgstr "" + +#: ../../howto/logging.rst:915 +msgid "" +"Just as for loggers, handlers can have levels associated with them. A " +"handler's level acts as a filter in the same way as a logger's level does. " +"If a handler decides to actually dispatch an event, " +"the :meth:`~Handler.emit` method is used to send the message to its " +"destination. Most user-defined subclasses of :class:`Handler` will need to " +"override this :meth:`~Handler.emit`." +msgstr "" + +#: ../../howto/logging.rst:924 +msgid "Custom Levels" +msgstr "" + +#: ../../howto/logging.rst:926 +msgid "" +"Defining your own levels is possible, but should not be necessary, as the " +"existing levels have been chosen on the basis of practical experience. " +"However, if you are convinced that you need custom levels, great care should " +"be exercised when doing this, and it is possibly *a very bad idea to define " +"custom levels if you are developing a library*. That's because if multiple " +"library authors all define their own custom levels, there is a chance that " +"the logging output from such multiple libraries used together will be " +"difficult for the using developer to control and/or interpret, because a " +"given numeric value might mean different things for different libraries." +msgstr "" + +#: ../../howto/logging.rst:939 +msgid "Useful Handlers" +msgstr "" + +#: ../../howto/logging.rst:941 +msgid "" +"In addition to the base :class:`Handler` class, many useful subclasses are " +"provided:" +msgstr "" + +#: ../../howto/logging.rst:944 +msgid "" +":class:`StreamHandler` instances send messages to streams (file-like " +"objects)." +msgstr "" + +#: ../../howto/logging.rst:947 +msgid ":class:`FileHandler` instances send messages to disk files." +msgstr "" + +#: ../../howto/logging.rst:949 +msgid "" +":class:`~handlers.BaseRotatingHandler` is the base class for handlers that " +"rotate log files at a certain point. It is not meant to be instantiated " +"directly. Instead, use :class:`~handlers.RotatingFileHandler` " +"or :class:`~handlers.TimedRotatingFileHandler`." +msgstr "" + +#: ../../howto/logging.rst:954 +msgid "" +":class:`~handlers.RotatingFileHandler` instances send messages to disk " +"files, with support for maximum log file sizes and log file rotation." +msgstr "" + +#: ../../howto/logging.rst:957 +msgid "" +":class:`~handlers.TimedRotatingFileHandler` instances send messages to disk " +"files, rotating the log file at certain timed intervals." +msgstr "" + +#: ../../howto/logging.rst:960 +msgid "" +":class:`~handlers.SocketHandler` instances send messages to TCP/IP sockets. " +"Since 3.4, Unix domain sockets are also supported." +msgstr "" + +#: ../../howto/logging.rst:963 +msgid "" +":class:`~handlers.DatagramHandler` instances send messages to UDP sockets. " +"Since 3.4, Unix domain sockets are also supported." +msgstr "" + +#: ../../howto/logging.rst:966 +msgid "" +":class:`~handlers.SMTPHandler` instances send messages to a designated email " +"address." +msgstr "" + +#: ../../howto/logging.rst:969 +msgid "" +":class:`~handlers.SysLogHandler` instances send messages to a Unix syslog " +"daemon, possibly on a remote machine." +msgstr "" + +#: ../../howto/logging.rst:972 +msgid "" +":class:`~handlers.NTEventLogHandler` instances send messages to a Windows NT/" +"2000/XP event log." +msgstr "" + +#: ../../howto/logging.rst:975 +msgid "" +":class:`~handlers.MemoryHandler` instances send messages to a buffer in " +"memory, which is flushed whenever specific criteria are met." +msgstr "" + +#: ../../howto/logging.rst:978 +msgid "" +":class:`~handlers.HTTPHandler` instances send messages to an HTTP server " +"using either ``GET`` or ``POST`` semantics." +msgstr "" + +#: ../../howto/logging.rst:981 +msgid "" +":class:`~handlers.WatchedFileHandler` instances watch the file they are " +"logging to. If the file changes, it is closed and reopened using the file " +"name. This handler is only useful on Unix-like systems; Windows does not " +"support the underlying mechanism used." +msgstr "" + +#: ../../howto/logging.rst:986 +msgid "" +":class:`~handlers.QueueHandler` instances send messages to a queue, such as " +"those implemented in the :mod:`queue` or :mod:`multiprocessing` modules." +msgstr "" + +#: ../../howto/logging.rst:989 +msgid "" +":class:`NullHandler` instances do nothing with error messages. They are used " +"by library developers who want to use logging, but want to avoid the 'No " +"handlers could be found for logger *XXX*' message which can be displayed if " +"the library user has not configured logging. See :ref:`library-config` for " +"more information." +msgstr "" + +#: ../../howto/logging.rst:995 +msgid "The :class:`NullHandler` class." +msgstr "" + +#: ../../howto/logging.rst:998 +msgid "The :class:`~handlers.QueueHandler` class." +msgstr "" + +#: ../../howto/logging.rst:1001 +msgid "" +"The :class:`NullHandler`, :class:`StreamHandler` and :class:`FileHandler` " +"classes are defined in the core logging package. The other handlers are " +"defined in a sub-module, :mod:`logging.handlers`. (There is also another sub-" +"module, :mod:`logging.config`, for configuration functionality.)" +msgstr "" + +#: ../../howto/logging.rst:1006 +msgid "" +"Logged messages are formatted for presentation through instances of " +"the :class:`Formatter` class. They are initialized with a format string " +"suitable for use with the % operator and a dictionary." +msgstr "" + +#: ../../howto/logging.rst:1010 +msgid "" +"For formatting multiple messages in a batch, instances " +"of :class:`BufferingFormatter` can be used. In addition to the format string " +"(which is applied to each message in the batch), there is provision for " +"header and trailer format strings." +msgstr "" + +#: ../../howto/logging.rst:1015 +msgid "" +"When filtering based on logger level and/or handler level is not enough, " +"instances of :class:`Filter` can be added to both :class:`Logger` " +"and :class:`Handler` instances (through their :meth:`~Handler.addFilter` " +"method). Before deciding to process a message further, both loggers and " +"handlers consult all their filters for permission. If any filter returns a " +"false value, the message is not processed further." +msgstr "" + +#: ../../howto/logging.rst:1022 +msgid "" +"The basic :class:`Filter` functionality allows filtering by specific logger " +"name. If this feature is used, messages sent to the named logger and its " +"children are allowed through the filter, and all others dropped." +msgstr "" + +#: ../../howto/logging.rst:1030 +msgid "Exceptions raised during logging" +msgstr "" + +#: ../../howto/logging.rst:1032 +msgid "" +"The logging package is designed to swallow exceptions which occur while " +"logging in production. This is so that errors which occur while handling " +"logging events - such as logging misconfiguration, network or other similar " +"errors - do not cause the application using logging to terminate prematurely." +msgstr "" + +#: ../../howto/logging.rst:1037 +msgid "" +":class:`SystemExit` and :class:`KeyboardInterrupt` exceptions are never " +"swallowed. Other exceptions which occur during the :meth:`~Handler.emit` " +"method of a :class:`Handler` subclass are passed to " +"its :meth:`~Handler.handleError` method." +msgstr "" + +#: ../../howto/logging.rst:1042 +msgid "" +"The default implementation of :meth:`~Handler.handleError` " +"in :class:`Handler` checks to see if a module-level " +"variable, :data:`raiseExceptions`, is set. If set, a traceback is printed " +"to :data:`sys.stderr`. If not set, the exception is swallowed." +msgstr "" + +#: ../../howto/logging.rst:1048 +msgid "" +"The default value of :data:`raiseExceptions` is ``True``. This is because " +"during development, you typically want to be notified of any exceptions that " +"occur. It's advised that you set :data:`raiseExceptions` to ``False`` for " +"production usage." +msgstr "" + +#: ../../howto/logging.rst:1058 +msgid "Using arbitrary objects as messages" +msgstr "" + +#: ../../howto/logging.rst:1060 +msgid "" +"In the preceding sections and examples, it has been assumed that the message " +"passed when logging the event is a string. However, this is not the only " +"possibility. You can pass an arbitrary object as a message, and " +"its :meth:`~object.__str__` method will be called when the logging system " +"needs to convert it to a string representation. In fact, if you want to, you " +"can avoid computing a string representation altogether - for example, " +"the :class:`~handlers.SocketHandler` emits an event by pickling it and " +"sending it over the wire." +msgstr "" + +#: ../../howto/logging.rst:1071 +msgid "Optimization" +msgstr "最佳化" + +#: ../../howto/logging.rst:1073 +msgid "" +"Formatting of message arguments is deferred until it cannot be avoided. " +"However, computing the arguments passed to the logging method can also be " +"expensive, and you may want to avoid doing it if the logger will just throw " +"away your event. To decide what to do, you can call " +"the :meth:`~Logger.isEnabledFor` method which takes a level argument and " +"returns true if the event would be created by the Logger for that level of " +"call. You can write code like this::" +msgstr "" + +#: ../../howto/logging.rst:1081 +msgid "" +"if logger.isEnabledFor(logging.DEBUG):\n" +" logger.debug('Message with %s, %s', expensive_func1(),\n" +" expensive_func2())" +msgstr "" + +#: ../../howto/logging.rst:1085 +msgid "" +"so that if the logger's threshold is set above ``DEBUG``, the calls to " +"``expensive_func1`` and ``expensive_func2`` are never made." +msgstr "" + +#: ../../howto/logging.rst:1088 +msgid "" +"In some cases, :meth:`~Logger.isEnabledFor` can itself be more expensive " +"than you'd like (e.g. for deeply nested loggers where an explicit level is " +"only set high up in the logger hierarchy). In such cases (or if you want to " +"avoid calling a method in tight loops), you can cache the result of a call " +"to :meth:`~Logger.isEnabledFor` in a local or instance variable, and use " +"that instead of calling the method each time. Such a cached value would only " +"need to be recomputed when the logging configuration changes dynamically " +"while the application is running (which is not all that common)." +msgstr "" + +#: ../../howto/logging.rst:1097 +msgid "" +"There are other optimizations which can be made for specific applications " +"which need more precise control over what logging information is collected. " +"Here's a list of things you can do to avoid processing during logging which " +"you don't need:" +msgstr "" + +#: ../../howto/logging.rst:1103 +msgid "What you don't want to collect" +msgstr "" + +#: ../../howto/logging.rst:1103 +msgid "How to avoid collecting it" +msgstr "" + +#: ../../howto/logging.rst:1105 +msgid "Information about where calls were made from." +msgstr "" + +#: ../../howto/logging.rst:1105 +msgid "" +"Set ``logging._srcfile`` to ``None``. This avoids " +"calling :func:`sys._getframe`, which may help to speed up your code in " +"environments like PyPy (which can't speed up code that " +"uses :func:`sys._getframe`)." +msgstr "" + +#: ../../howto/logging.rst:1111 +msgid "Threading information." +msgstr "" + +#: ../../howto/logging.rst:1111 +msgid "Set ``logging.logThreads`` to ``False``." +msgstr "將 ``logging.logThreads`` 設為 ``False``。" + +#: ../../howto/logging.rst:1113 +msgid "Current process ID (:func:`os.getpid`)" +msgstr "目前的行程 ID (:func:`os.getpid`)" + +#: ../../howto/logging.rst:1113 +msgid "Set ``logging.logProcesses`` to ``False``." +msgstr "將 ``logging.logProcesses`` 設為 ``False``。" + +#: ../../howto/logging.rst:1115 +msgid "" +"Current process name when using ``multiprocessing`` to manage multiple " +"processes." +msgstr "" + +#: ../../howto/logging.rst:1115 +msgid "Set ``logging.logMultiprocessing`` to ``False``." +msgstr "將 ``logging.logMultiprocessing`` 設為 ``False``。" + +#: ../../howto/logging.rst:1118 +msgid "Current :class:`asyncio.Task` name when using ``asyncio``." +msgstr "" + +#: ../../howto/logging.rst:1118 +msgid "Set ``logging.logAsyncioTasks`` to ``False``." +msgstr "將 ``logging.logAsyncioTasks`` 設為 ``False``。" + +#: ../../howto/logging.rst:1122 +msgid "" +"Also note that the core logging module only includes the basic handlers. If " +"you don't import :mod:`logging.handlers` and :mod:`logging.config`, they " +"won't take up any memory." +msgstr "" + +#: ../../howto/logging.rst:1129 +msgid "Other resources" +msgstr "其他資源" + +#: ../../howto/logging.rst:1133 +msgid "Module :mod:`logging`" +msgstr ":mod:`logging` 模組" + +#: ../../howto/logging.rst:1134 +msgid "API reference for the logging module." +msgstr "" + +#: ../../howto/logging.rst:1136 +msgid "Module :mod:`logging.config`" +msgstr ":mod:`logging.config` 模組" + +#: ../../howto/logging.rst:1137 +msgid "Configuration API for the logging module." +msgstr "" + +#: ../../howto/logging.rst:1139 +msgid "Module :mod:`logging.handlers`" +msgstr ":mod:`logging.handlers` 模組" + +#: ../../howto/logging.rst:1140 +msgid "Useful handlers included with the logging module." +msgstr "" + +#: ../../howto/logging.rst:1142 +msgid ":ref:`A logging cookbook `" +msgstr "" diff --git a/howto/mro.po b/howto/mro.po index a480b153b7..854f06332c 100644 --- a/howto/mro.po +++ b/howto/mro.po @@ -1,1222 +1,1222 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# FIRST AUTHOR , YEAR. -# -#, fuzzy -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-01-22 00:13+0000\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \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" - -#: ../../howto/mro.rst:4 -msgid "The Python 2.3 Method Resolution Order" -msgstr "Python 2.3 方法解析順序" - -#: ../../howto/mro.rst:8 -msgid "" -"This is a historical document, provided as an appendix to the official " -"documentation. The Method Resolution Order discussed here was *introduced* " -"in Python 2.3, but it is still used in later versions -- including Python 3." -msgstr "" -"這是一份歷史文件，作為正式文件的附錄提供。此處討論的方法解析順序 (Method " -"Resolution Order) 是在 Python 2.3 中 *引入* 的，但仍在後續版本中使用，包" -"括 Python 3。" - -#: ../../howto/mro.rst:13 -msgid "By `Michele Simionato `__." -msgstr "作者：`Michele Simionato `__。" - -#: ../../howto/mro.rst:0 -msgid "Abstract" -msgstr "摘要" - -#: ../../howto/mro.rst:17 -msgid "" -"*This document is intended for Python programmers who want to understand the " -"C3 Method Resolution Order used in Python 2.3. Although it is not intended " -"for newbies, it is quite pedagogical with many worked out examples. I am " -"not aware of other publicly available documents with the same scope, " -"therefore it should be useful.*" -msgstr "" -"*此文件適用於想要了解 Python 2.3 中使用的 C3 方法解析順序的 Python 程式設計" -"師。雖然它不是為初學者準備的，但透過許多實際範例進行教學。我沒找到其他具有相" -"同範圍的公開文件，因此這應該很有用。*" - -#: ../../howto/mro.rst:23 -msgid "Disclaimer:" -msgstr "免責聲明：" - -#: ../../howto/mro.rst:25 -msgid "" -"*I donate this document to the Python Software Foundation, under the Python " -"2.3 license. As usual in these circumstances, I warn the reader that what " -"follows* should *be correct, but I don't give any warranty. Use it at your " -"own risk and peril!*" -msgstr "" -"*我根據 Python 2.3 授權條款將此文件捐贈給 Python 軟體基金會。如同往常，我警告" -"讀者，以下內容 *應該* 是正確的，但我不提供任何保證。使用時風險自負！*" - -#: ../../howto/mro.rst:30 -msgid "Acknowledgments:" -msgstr "致謝：" - -#: ../../howto/mro.rst:32 -msgid "" -"*All the people of the Python mailing list who sent me their support. Paul " -"Foley who pointed out various imprecisions and made me to add the part on " -"local precedence ordering. David Goodger for help with the formatting in " -"reStructuredText. David Mertz for help with the editing. Finally, Guido van " -"Rossum who enthusiastically added this document to the official Python 2.3 " -"home-page.*" -msgstr "" -"*感謝 Python 郵件列表中所有給予我支持的人。Paul Foley 指出了各種不精確之處，並" -"促使我加入了區域優先順序（local precedence ordering）的部分。David Goodger 協" -"助 reStructuredText 的格式化。David Mertz 協助編輯。最後，Guido van Rossum 熱" -"情地將此文件加入到 Python 2.3 官方首頁。*" - -#: ../../howto/mro.rst:40 -msgid "The beginning" -msgstr "開端" - -#: ../../howto/mro.rst:42 -msgid "*Felix qui potuit rerum cognoscere causas* -- Virgilius" -msgstr "*Felix qui potuit rerum cognoscere causas* -- Virgilius" - -#: ../../howto/mro.rst:44 -msgid "" -"Everything started with a post by Samuele Pedroni to the Python development " -"mailing list [#]_. In his post, Samuele showed that the Python 2.2 method " -"resolution order is not monotonic and he proposed to replace it with the C3 " -"method resolution order. Guido agreed with his arguments and therefore now " -"Python 2.3 uses C3. The C3 method itself has nothing to do with Python, " -"since it was invented by people working on Dylan and it is described in a " -"paper intended for lispers [#]_. The present paper gives a (hopefully) " -"readable discussion of the C3 algorithm for Pythonistas who want to " -"understand the reasons for the change." -msgstr "" -"一切始於 Samuele Pedroni 向 Python 開發郵件列表發表的貼文 [#]_。在他的貼文" -"中，Samuele 指出 Python 2.2 的方法解析順序不具單調性（monotonic），並提議以 " -"C3 方法解析順序來取代。Guido 同意他的論點，因此 Python 2.3 現在使用 C3。C3 方" -"法本身與 Python 無關，因為它是由研究 Dylan 語言的人所發明，並在一篇針對 Lisp " -"程式設計師的論文 [#]_ 中描述。本文為想要了解此變更原因的 Python 程式設計師提" -"供了 C3 演算法（希望是）易讀的討論。" - -#: ../../howto/mro.rst:55 -msgid "" -"First of all, let me point out that what I am going to say only applies to " -"the *new style classes* introduced in Python 2.2: *classic classes* " -"maintain their old method resolution order, depth first and then left to " -"right. Therefore, there is no breaking of old code for classic classes; and " -"even if in principle there could be breaking of code for Python 2.2 new " -"style classes, in practice the cases in which the C3 resolution order " -"differs from the Python 2.2 method resolution order are so rare that no real " -"breaking of code is expected. Therefore:" -msgstr "" -"首先讓我指出，我要說的僅適用於 Python 2.2 中引入的 *新式類別（new style " -"classes）*：*經典類別（classic classes）* 維持其舊有的方法解析順序，即深度" -"優先然後由左至右。因此，經典類別的舊程式碼不會受到影響；即使原則上 Python 2.2 " -"新式類別的程式碼可能會受影響，但實際上 C3 解析順序與 Python 2.2 方法解析順序不" -"同的情況極為罕見，因此預期不會真正破壞程式碼。因此：" - -#: ../../howto/mro.rst:64 -msgid "*Don't be scared!*" -msgstr "*別怕！*" - -#: ../../howto/mro.rst:66 -msgid "" -"Moreover, unless you make strong use of multiple inheritance and you have " -"non-trivial hierarchies, you don't need to understand the C3 algorithm, and " -"you can easily skip this paper. On the other hand, if you really want to " -"know how multiple inheritance works, then this paper is for you. The good " -"news is that things are not as complicated as you might expect." -msgstr "" -"此外，除非你大量使用多重繼承且有複雜的類別階層，否則你無需了解 C3 演算法，可" -"以輕鬆跳過本文。另一方面，如果你真的想知道多重繼承如何運作，那麼本文就是為你" -"準備的。好消息是，事情並不像你想像的那樣複雜。" - -#: ../../howto/mro.rst:73 -msgid "Let me begin with some basic definitions." -msgstr "讓我從一些基本定義開始。" - -#: ../../howto/mro.rst:75 -msgid "" -"Given a class C in a complicated multiple inheritance hierarchy, it is a non-" -"trivial task to specify the order in which methods are overridden, i.e. to " -"specify the order of the ancestors of C." -msgstr "" -"給定複雜多重繼承階層中的類別 C，要指定方法被覆寫（override）的順序並非易事，" -"也就是要指定 C 的祖先順序。" - -#: ../../howto/mro.rst:79 -msgid "" -"The list of the ancestors of a class C, including the class itself, ordered " -"from the nearest ancestor to the furthest, is called the class precedence " -"list or the *linearization* of C." -msgstr "" -"類別 C 的祖先串列（包含類別本身），從最近的祖先到最遠的祖先排序，稱為類別優先" -"串列（class precedence list）或 C 的\\ *線性化（linearization）*。" - -#: ../../howto/mro.rst:83 -msgid "" -"The *Method Resolution Order* (MRO) is the set of rules that construct the " -"linearization. In the Python literature, the idiom \"the MRO of C\" is also " -"used as a synonymous for the linearization of the class C." -msgstr "" -"*方法解析順序 (Method Resolution Order, MRO)* 是建構線性化的一組規則。在 " -"Python 文獻中，習慣用語「C 的 MRO」也是 C 類別線性化的同義詞。" - -#: ../../howto/mro.rst:88 -msgid "" -"For instance, in the case of single inheritance hierarchy, if C is a " -"subclass of C1, and C1 is a subclass of C2, then the linearization of C is " -"simply the list [C, C1 , C2]. However, with multiple inheritance " -"hierarchies, the construction of the linearization is more cumbersome, since " -"it is more difficult to construct a linearization that respects *local " -"precedence ordering* and *monotonicity*." -msgstr "" -"例如，在單一繼承階層的情況下，如果 C 是 C1 的子類別，而 C1 是 C2 的子類別，那" -"麼 C 的線性化就是串列 [C, C1, C2]。然而，在多重繼承階層中，線性化的建構更加複" -"雜，因為要建構一個遵守\\ *區域優先順序（local precedence ordering）* 和\\ *" -"單調性（monotonicity）* 的線性化更加困難。" - -#: ../../howto/mro.rst:96 -msgid "" -"I will discuss the local precedence ordering later, but I can give the " -"definition of monotonicity here. A MRO is monotonic when the following is " -"true: *if C1 precedes C2 in the linearization of C, then C1 precedes C2 in " -"the linearization of any subclass of C*. Otherwise, the innocuous operation " -"of deriving a new class could change the resolution order of methods, " -"potentially introducing very subtle bugs. Examples where this happens will " -"be shown later." -msgstr "" -"我將在稍後討論區域優先順序，但可以在此給出單調性的定義。當以下條件為真時，" -"MRO 具有單調性：*如果 C1 在 C 的線性化中先於 C2，那麼 C1 在 C 的任何子類別的" -"線性化中也先於 C2*。否則，衍生新類別這個看似無害的操作可能會改變方法的解析順" -"序，進而引入非常微妙的錯誤。稍後將展示發生這種情況的範例。" - -#: ../../howto/mro.rst:104 -msgid "" -"Not all classes admit a linearization. There are cases, in complicated " -"hierarchies, where it is not possible to derive a class such that its " -"linearization respects all the desired properties." -msgstr "" -"並非所有類別都能進行線性化。在複雜的階層結構中，有些情況下無法衍生出一個類別，" -"使其線性化遵守所有所需的屬性。" - -#: ../../howto/mro.rst:108 -msgid "Here I give an example of this situation. Consider the hierarchy" -msgstr "以下是這種情況的範例。考慮以下階層結構" - -#: ../../howto/mro.rst:116 -msgid "" -"which can be represented with the following inheritance graph, where I have " -"denoted with O the ``object`` class, which is the beginning of any hierarchy " -"for new style classes:" -msgstr "" -"可以用以下繼承圖來表示，其中我用 O 標示 ``object`` 類別，這是新式類別的任何階" -"層結構的起點：" - -#: ../../howto/mro.rst:120 -msgid "" -" -----------\n" -"| |\n" -"| O |\n" -"| / \\ |\n" -" - X Y /\n" -" | / | /\n" -" | / |/\n" -" A B\n" -" \\ /\n" -" ?" -msgstr "" -" -----------\n" -"| |\n" -"| O |\n" -"| / \\ |\n" -" - X Y /\n" -" | / | /\n" -" | / |/\n" -" A B\n" -" \\ /\n" -" ?" - -#: ../../howto/mro.rst:133 -msgid "" -"In this case, it is not possible to derive a new class C from A and B, since " -"X precedes Y in A, but Y precedes X in B, therefore the method resolution " -"order would be ambiguous in C." -msgstr "" -"在這種情況下，不可能從 A 和 B 衍生出新的類別 C，因為 X 在 A 中先於 Y，但 Y 在 " -"B 中先於 X，因此 C 的方法解析順序會產生歧義。" - -#: ../../howto/mro.rst:137 -msgid "" -"Python 2.3 raises an exception in this situation (TypeError: MRO conflict " -"among bases Y, X) forbidding the naive programmer from creating ambiguous " -"hierarchies. Python 2.2 instead does not raise an exception, but chooses an " -"*ad hoc* ordering (CABXYO in this case)." -msgstr "" -"Python 2.3 在這種情況下會引發例外（TypeError: MRO conflict among bases Y, X），" -"防止程式設計師建立有歧義的階層結構。Python 2.2 則不會引發例外，而是選擇 *ad " -"hoc* 順序（在這種情況下為 CABXYO）。" - -#: ../../howto/mro.rst:143 -msgid "The C3 Method Resolution Order" -msgstr "C3 方法解析順序" - -#: ../../howto/mro.rst:145 -msgid "" -"Let me introduce a few simple notations which will be useful for the " -"following discussion. I will use the shortcut notation::" -msgstr "讓我介紹一些簡單的符號標示法，這對以下討論很有用。我將使用簡寫符號： ::" - -#: ../../howto/mro.rst:148 -msgid "C1 C2 ... CN" -msgstr "C1 C2 ... CN" - -#: ../../howto/mro.rst:150 -msgid "to indicate the list of classes [C1, C2, ... , CN]." -msgstr "用來表示類別串列 [C1, C2, ... , CN]。" - -#: ../../howto/mro.rst:152 -msgid "The *head* of the list is its first element::" -msgstr "串列的 *head*\\ （頭部）是其第一個元素： ::" - -#: ../../howto/mro.rst:154 -msgid "head = C1" -msgstr "head = C1" - -#: ../../howto/mro.rst:156 -msgid "whereas the *tail* is the rest of the list::" -msgstr "而 *tail*\\ （尾部）是串列的其餘部分： ::" - -#: ../../howto/mro.rst:158 -msgid "tail = C2 ... CN." -msgstr "tail = C2 ... CN." - -#: ../../howto/mro.rst:160 -msgid "I shall also use the notation::" -msgstr "我還將使用以下符號： ::" - -#: ../../howto/mro.rst:162 -msgid "C + (C1 C2 ... CN) = C C1 C2 ... CN" -msgstr "C + (C1 C2 ... CN) = C C1 C2 ... CN" - -#: ../../howto/mro.rst:164 -msgid "to denote the sum of the lists [C] + [C1, C2, ... ,CN]." -msgstr "標示串列的和 [C] + [C1, C2, ..., CN]。" - -#: ../../howto/mro.rst:166 -msgid "Now I can explain how the MRO works in Python 2.3." -msgstr "現在我就可以繼續解釋 MRO 在 Python 2.3 中的運作方式。" - -#: ../../howto/mro.rst:168 -msgid "" -"Consider a class C in a multiple inheritance hierarchy, with C inheriting " -"from the base classes B1, B2, ... , BN. We want to compute the " -"linearization L[C] of the class C. The rule is the following:" -msgstr "" -"考慮多重繼承階層結構中的類別 C，C 從基底類別 B1、B2、...、BN 繼承。我們想計算" -"類別 C 的線性化 L[C]。規則如下：" - -#: ../../howto/mro.rst:173 -msgid "" -"*the linearization of C is the sum of C plus the merge of the linearizations " -"of the parents and the list of the parents.*" -msgstr "*C 的線性化是 C 加上父類別線性化的合併以及父類別串列的和。*" - -#: ../../howto/mro.rst:176 -msgid "In symbolic notation::" -msgstr "用符號標示： ::" - -#: ../../howto/mro.rst:178 -msgid "L[C(B1 ... BN)] = C + merge(L[B1] ... L[BN], B1 ... BN)" -msgstr "L[C(B1 ... BN)] = C + merge(L[B1] ... L[BN], B1 ... BN)" - -#: ../../howto/mro.rst:180 -msgid "" -"In particular, if C is the ``object`` class, which has no parents, the " -"linearization is trivial::" -msgstr "" -"特別是如果 C 是沒有父類別的 ``object`` 類別，那麼線性化是簡單的：" - -#: ../../howto/mro.rst:183 -msgid "L[object] = object." -msgstr "L[object] = object." - -#: ../../howto/mro.rst:185 -msgid "" -"However, in general one has to compute the merge according to the following " -"prescription:" -msgstr "然而，一般來說必須根據以下規則來計算合併：" - -#: ../../howto/mro.rst:188 -msgid "" -"*take the head of the first list, i.e L[B1][0]; if this head is not in the " -"tail of any of the other lists, then add it to the linearization of C and " -"remove it from the lists in the merge, otherwise look at the head of the " -"next list and take it, if it is a good head. Then repeat the operation " -"until all the class are removed or it is impossible to find good heads. In " -"this case, it is impossible to construct the merge, Python 2.3 will refuse " -"to create the class C and will raise an exception.*" -msgstr "" -"*取第一個串列的頭部，即 L[B1][0]；如果此頭部不在其他任何串列的尾部中，那麼將" -"它加入到 C 的線性化中，並從合併中的所有串列移除它；否則查看下一個串列的頭部，" -"如果它是一個好的頭部就取它。然後重複此操作，直到所有類別都被移除或無法找到好的" -"頭部。在後面這種情況下，無法建構合併，Python 2.3 將拒絕建立類別 C 並引發例外。*" - -#: ../../howto/mro.rst:197 -msgid "" -"This prescription ensures that the merge operation *preserves* the ordering, " -"if the ordering can be preserved. On the other hand, if the order cannot be " -"preserved (as in the example of serious order disagreement discussed above) " -"then the merge cannot be computed." -msgstr "" -"此規則確保合併操作\\ *保留*\\ 順序（如果順序可以被保留）。另一方面，如果無法保" -"留順序（如上面討論的嚴重順序分歧的範例），則無法計算合併。" - -#: ../../howto/mro.rst:202 -msgid "" -"The computation of the merge is trivial if C has only one parent (single " -"inheritance); in this case::" -msgstr "" -"如果 C 只有一個父類別（單一繼承），則合併的計算是微不足道的。在這種情況" -"下： ::" - -#: ../../howto/mro.rst:205 -msgid "L[C(B)] = C + merge(L[B],B) = C + L[B]" -msgstr "L[C(B)] = C + merge(L[B],B) = C + L[B]" - -#: ../../howto/mro.rst:207 -msgid "" -"However, in the case of multiple inheritance things are more cumbersome and " -"I don't expect you can understand the rule without a couple of examples ;-)" -msgstr "" -"但是，在多重繼承的情況下，事情更加複雜，我不指望你能在沒有幾個範例的情況下理解這個規則 ;-)" - -#: ../../howto/mro.rst:212 -msgid "Examples" -msgstr "範例" - -#: ../../howto/mro.rst:214 -msgid "First example. Consider the following hierarchy:" -msgstr "第一個例子，請參考以下階層結構：" - -#: ../../howto/mro.rst:224 -msgid "In this case the inheritance graph can be drawn as:" -msgstr "在這種情況下，繼承圖可以繪製為：" - -#: ../../howto/mro.rst:226 -msgid "" -" 6\n" -" ---\n" -"Level 3 | O | (more general)\n" -" / --- \\\n" -" / | \\ |\n" -" / | \\ |\n" -" / | \\ |\n" -" --- --- --- |\n" -"Level 2 3 | D | 4| E | | F | 5 |\n" -" --- --- --- |\n" -" \\ \\ _ / | |\n" -" \\ / \\ _ | |\n" -" \\ / \\ | |\n" -" --- --- |\n" -"Level 1 1 | B | | C | 2 |\n" -" --- --- |\n" -" \\ / |\n" -" \\ / \\ /\n" -" ---\n" -"Level 0 0 | A | (more specialized)\n" -" ---" -msgstr "" -" 6\n" -" ---\n" -"Level 3 | O | （更廣泛）\n" -" / --- \\\n" -" / | \\ |\n" -" / | \\ |\n" -" / | \\ |\n" -" --- --- --- |\n" -"Level 2 3 | D | 4| E | | F | 5 |\n" -" --- --- --- |\n" -" \\ \\ _ / | |\n" -" \\ / \\ _ | |\n" -" \\ / \\ | |\n" -" --- --- |\n" -"Level 1 1 | B | | C | 2 |\n" -" --- --- |\n" -" \\ / |\n" -" \\ / \\ /\n" -" ---\n" -"Level 0 0 | A | （更專精）\n" -" ---" - -#: ../../howto/mro.rst:251 -msgid "The linearizations of O,D,E and F are trivial::" -msgstr "O、D、E 和 F 的線性化很簡單： ::" - -#: ../../howto/mro.rst:253 -msgid "" -"L[O] = O\n" -"L[D] = D O\n" -"L[E] = E O\n" -"L[F] = F O" -msgstr "" -"L[O] = O\n" -"L[D] = D O\n" -"L[E] = E O\n" -"L[F] = F O" - -#: ../../howto/mro.rst:258 -msgid "The linearization of B can be computed as::" -msgstr "B 的線性化可以計算為： ::" - -#: ../../howto/mro.rst:260 -msgid "L[B] = B + merge(DO, EO, DE)" -msgstr "L[B] = B + merge(DO, EO, DE)" - -#: ../../howto/mro.rst:262 -msgid "" -"We see that D is a good head, therefore we take it and we are reduced to " -"compute ``merge(O,EO,E)``. Now O is not a good head, since it is in the " -"tail of the sequence EO. In this case the rule says that we have to skip to " -"the next sequence. Then we see that E is a good head; we take it and we are " -"reduced to compute ``merge(O,O)`` which gives O. Therefore::" -msgstr "" -"我們看到 D 是一個好的頭部，因此我們取它，並將其簡化為 ``merge(O,EO,E)``。現" -"在 O 不是一個好的頭部，因為它位於序列 EO 的尾部。在這種情況下，規則說我們必須" -"跳到下一個序列。然後我們看到 E 是一個好的頭部；我們取它，並簡化為計算 " -"``merge(O, O)`` 得出 O。因此： ::" - -#: ../../howto/mro.rst:268 -msgid "L[B] = B D E O" -msgstr "L[B] = B D E O" - -#: ../../howto/mro.rst:270 -msgid "Using the same procedure one finds::" -msgstr "使用相同的程序可以發現： ::" - -#: ../../howto/mro.rst:272 -msgid "" -"L[C] = C + merge(DO,FO,DF)\n" -" = C + D + merge(O,FO,F)\n" -" = C + D + F + merge(O,O)\n" -" = C D F O" -msgstr "" -"L[C] = C + merge(DO,FO,DF)\n" -" = C + D + merge(O,FO,F)\n" -" = C + D + F + merge(O,O)\n" -" = C D F O" - -#: ../../howto/mro.rst:277 -msgid "Now we can compute::" -msgstr "現在我們可以計算出： ::" - -#: ../../howto/mro.rst:279 -msgid "" -"L[A] = A + merge(BDEO,CDFO,BC)\n" -" = A + B + merge(DEO,CDFO,C)\n" -" = A + B + C + merge(DEO,DFO)\n" -" = A + B + C + D + merge(EO,FO)\n" -" = A + B + C + D + E + merge(O,FO)\n" -" = A + B + C + D + E + F + merge(O,O)\n" -" = A B C D E F O" -msgstr "" -"L[A] = A + merge(BDEO,CDFO,BC)\n" -" = A + B + merge(DEO,CDFO,C)\n" -" = A + B + C + merge(DEO,DFO)\n" -" = A + B + C + D + merge(EO,FO)\n" -" = A + B + C + D + E + merge(O,FO)\n" -" = A + B + C + D + E + F + merge(O,O)\n" -" = A B C D E F O" - -#: ../../howto/mro.rst:287 -msgid "" -"In this example, the linearization is ordered in a pretty nice way according " -"to the inheritance level, in the sense that lower levels (i.e. more " -"specialized classes) have higher precedence (see the inheritance graph). " -"However, this is not the general case." -msgstr "" -"在此範例中，線性化是根據繼承層級以相當不錯的方式排序的，因為較低層級（即更專" -"精的類別）具有更高的優先級（請參見繼承圖）。但是這不是一般情況。" - -#: ../../howto/mro.rst:292 -msgid "" -"I leave as an exercise for the reader to compute the linearization for my " -"second example:" -msgstr "第二個範例的線性化之計算我留給讀者當作練習：" - -#: ../../howto/mro.rst:303 -msgid "" -"The only difference with the previous example is the change B(D,E) --> " -"B(E,D); however even such a little modification completely changes the " -"ordering of the hierarchy:" -msgstr "" -"與上一個範例的唯一區別是 B(D,E) --> B(E,D) 的變化；但是即使是這樣小小的修改，也完" -"全改變了階層結構的順序：" - -#: ../../howto/mro.rst:307 -msgid "" -" 6\n" -" ---\n" -"Level 3 | O |\n" -" / --- \\\n" -" / | \\\n" -" / | \\\n" -" / | \\\n" -" --- --- ---\n" -"Level 2 2 | E | 4 | D | | F | 5\n" -" --- --- ---\n" -" \\ / \\ /\n" -" \\ / \\ /\n" -" \\ / \\ /\n" -" --- ---\n" -"Level 1 1 | B | | C | 3\n" -" --- ---\n" -" \\ /\n" -" \\ /\n" -" ---\n" -"Level 0 0 | A |\n" -" ---" -msgstr "" -" 6\n" -" ---\n" -"Level 3 | O |\n" -" / --- \\\n" -" / | \\\n" -" / | \\\n" -" / | \\\n" -" --- --- ---\n" -"Level 2 2 | E | 4 | D | | F | 5\n" -" --- --- ---\n" -" \\ / \\ /\n" -" \\ / \\ /\n" -" \\ / \\ /\n" -" --- ---\n" -"Level 1 1 | B | | C | 3\n" -" --- ---\n" -" \\ /\n" -" \\ /\n" -" ---\n" -"Level 0 0 | A |\n" -" ---" - -#: ../../howto/mro.rst:332 -msgid "" -"Notice that the class E, which is in the second level of the hierarchy, " -"precedes the class C, which is in the first level of the hierarchy, i.e. E " -"is more specialized than C, even if it is in a higher level." -msgstr "" -"請注意，階層結構的第二層中的類別 E，先於階層結構第一層的類別 C，即 E 比 C 更" -"專精，即使它處於更高層。" - -#: ../../howto/mro.rst:336 -msgid "" -"A lazy programmer can obtain the MRO directly from Python 2.2, since in this " -"case it coincides with the Python 2.3 linearization. It is enough to invoke " -"the :meth:`~type.mro` method of class A:" -msgstr "" -"懶惰的程式設計師可以直接從 Python 2.2 取得 MRO，因為在這種情況下，它與 " -"Python 2.3 線性化一致。呼叫類別 A 的 :meth:`~type.mro` 方法就足夠了：" - -#: ../../howto/mro.rst:345 -msgid "" -"Finally, let me consider the example discussed in the first section, " -"involving a serious order disagreement. In this case, it is straightforward " -"to compute the linearizations of O, X, Y, A and B:" -msgstr "" -"最後，讓我考慮第一部分中討論的範例，涉及嚴重的順序分歧。在這種情況下，計算 " -"O、X、Y、A 和 B 的線性化是很簡單的：" - -#: ../../howto/mro.rst:349 -msgid "" -"L[O] = 0\n" -"L[X] = X O\n" -"L[Y] = Y O\n" -"L[A] = A X Y O\n" -"L[B] = B Y X O" -msgstr "" -"L[O] = 0\n" -"L[X] = X O\n" -"L[Y] = Y O\n" -"L[A] = A X Y O\n" -"L[B] = B Y X O" - -#: ../../howto/mro.rst:357 -msgid "" -"However, it is impossible to compute the linearization for a class C that " -"inherits from A and B::" -msgstr "但是，我們不可能計算出從 A 和 B 繼承的類別 C 的線性化： ::" - -#: ../../howto/mro.rst:360 -msgid "" -"L[C] = C + merge(AXYO, BYXO, AB)\n" -" = C + A + merge(XYO, BYXO, B)\n" -" = C + A + B + merge(XYO, YXO)" -msgstr "" -"L[C] = C + merge(AXYO, BYXO, AB)\n" -" = C + A + merge(XYO, BYXO, B)\n" -" = C + A + B + merge(XYO, YXO)" - -#: ../../howto/mro.rst:364 -msgid "" -"At this point we cannot merge the lists XYO and YXO, since X is in the tail " -"of YXO whereas Y is in the tail of XYO: therefore there are no good heads " -"and the C3 algorithm stops. Python 2.3 raises an error and refuses to " -"create the class C." -msgstr "" -"在這一點上，我們無法合併串列 XYO 和 YXO，因為 X 位於 YXO 的尾部，而 Y 則位於 " -"XYO 的尾部：因此，沒有好的頭部，C3 演算法停止。Python 2.3 會引發錯誤而拒絕建" -"立類別 C。" - -#: ../../howto/mro.rst:370 -msgid "Bad Method Resolution Orders" -msgstr "不良的方法解析順序" - -#: ../../howto/mro.rst:372 -msgid "" -"A MRO is *bad* when it breaks such fundamental properties as local " -"precedence ordering and monotonicity. In this section, I will show that " -"both the MRO for classic classes and the MRO for new style classes in Python " -"2.2 are bad." -msgstr "" -"當 MRO 打破諸如區域優先順序和單調性之類的基本屬性時，MRO 是\\ *不良*\\ 的。在本節" -"中，我將證明經典類別的 MRO 和 Python 2.2 的新式類別的 MRO 都是不好的。" - -#: ../../howto/mro.rst:377 -msgid "" -"It is easier to start with the local precedence ordering. Consider the " -"following example:" -msgstr "從區域優先順序開始更容易。考慮以下範例：" - -#: ../../howto/mro.rst:384 -msgid "with inheritance diagram" -msgstr "包含繼承圖" - -#: ../../howto/mro.rst:386 -msgid "" -" O\n" -" |\n" -"(buy spam) F\n" -" | \\\n" -" | E (buy eggs)\n" -" | /\n" -" G\n" -"\n" -" (buy eggs or spam ?)" -msgstr "" -" O\n" -" |\n" -"(buy spam) F\n" -" | \\\n" -" | E (buy eggs)\n" -" | /\n" -" G\n" -"\n" -" (buy eggs or spam ?)" - -#: ../../howto/mro.rst:399 -msgid "" -"We see that class G inherits from F and E, with F *before* E: therefore we " -"would expect the attribute *G.remember2buy* to be inherited by " -"*F.remember2buy* and not by *E.remember2buy*: nevertheless Python 2.2 gives" -msgstr "" -"我們看到類別 G 從 F 和 E 繼承，F 在 E *之前*：因此，我們希望屬性 " -"*G.remember2buy* 被 *F.remember2buy* 繼承，而不是 *E.remember2buy*：儘管如" -"此，Python 2.2 給出" - -#: ../../howto/mro.rst:407 -msgid "" -"This is a breaking of local precedence ordering since the order in the local " -"precedence list, i.e. the list of the parents of G, is not preserved in the " -"Python 2.2 linearization of G::" -msgstr "" -"這是區域優先順序的破壞，因為區域優先串列中的順序，即 G 的父類別串列，在 " -"Python 2.2 的 G 的線性化中不被保留：" - -#: ../../howto/mro.rst:411 -msgid "L[G,P22]= G E F object # F *follows* E" -msgstr "L[G,P22]= G E F object # F *跟隨* E" - -#: ../../howto/mro.rst:413 -msgid "" -"One could argue that the reason why F follows E in the Python 2.2 " -"linearization is that F is less specialized than E, since F is the " -"superclass of E; nevertheless the breaking of local precedence ordering is " -"quite non-intuitive and error prone. This is particularly true since it is " -"a different from old style classes:" -msgstr "" -"有人可能會說，F 在 Python 2.2 線性化中跟隨 E 的原因是 F 比 E 特化程度較低，" -"因為 F 是 E 的超類別；然而，局部優先順序的破壞非常不直覺且容易出錯。尤其如" -"此，因為它與舊式類別不同：" - -#: ../../howto/mro.rst:425 -msgid "" -"In this case the MRO is GFEF and the local precedence ordering is preserved." -msgstr "在這種情況下，MRO 是 GFEF 並且保留區域優先順序。" - -#: ../../howto/mro.rst:428 -msgid "" -"As a general rule, hierarchies such as the previous one should be avoided, " -"since it is unclear if F should override E or vice-versa. Python 2.3 solves " -"the ambiguity by raising an exception in the creation of class G, " -"effectively stopping the programmer from generating ambiguous hierarchies. " -"The reason for that is that the C3 algorithm fails when the merge::" -msgstr "" -"通常應避免諸如上一個等階層結構，因為尚不清楚 F 是否應覆蓋 E 或反過來。 " -"Python 2.3 透過在建立類別 G 時引發例外來解決歧義，從而有效地阻止程式設計師產" -"生模棱兩可的階層結構。原因是當這樣合併時 C3 演算法會失敗： ::" - -#: ../../howto/mro.rst:435 -msgid "merge(FO,EFO,FE)" -msgstr "merge(FO,EFO,FE)" - -#: ../../howto/mro.rst:437 -msgid "" -"cannot be computed, because F is in the tail of EFO and E is in the tail of " -"FE." -msgstr "無法計算，因為 F 在 EFO 的尾部，而 E 在 FE 的尾部。" - -#: ../../howto/mro.rst:440 -msgid "" -"The real solution is to design a non-ambiguous hierarchy, i.e. to derive G " -"from E and F (the more specific first) and not from F and E; in this case " -"the MRO is GEF without any doubt." -msgstr "" -"真正的解決方案是設計一個非歧義的階層結構，即源自 E 和 F（更具體的第一）而不" -"是 F 和 E；在這種情況下，MRO 毫無疑問是 GEF。" - -#: ../../howto/mro.rst:444 -msgid "" -" O\n" -" |\n" -" F (spam)\n" -" / |\n" -"(eggs) E |\n" -" \\ |\n" -" G\n" -" (eggs, no doubt)" -msgstr "" -" O\n" -" |\n" -" F (spam)\n" -" / |\n" -"(eggs) E |\n" -" \\ |\n" -" G\n" -" (eggs, no doubt)" - -#: ../../howto/mro.rst:456 -msgid "" -"Python 2.3 forces the programmer to write good hierarchies (or, at least, " -"less error-prone ones)." -msgstr "Python 2.3 迫使程式設計師要編寫良好（或至少較不易於出錯）的階層結構。" - -#: ../../howto/mro.rst:459 -msgid "" -"On a related note, let me point out that the Python 2.3 algorithm is smart " -"enough to recognize obvious mistakes, as the duplication of classes in the " -"list of parents:" -msgstr "" -"與之相關的是，我指出 Python 2.3 演算法足夠聰明，可以識別出明顯的錯誤，例" -"如父類別串列中類別的重複：" - -#: ../../howto/mro.rst:469 -msgid "" -"Python 2.2 (both for classic classes and new style classes) in this " -"situation, would not raise any exception." -msgstr "" -"在這種情況下，Python 2.2（無論是經典類別還是新式類別）不會引發任何例外。" - -#: ../../howto/mro.rst:472 -msgid "" -"Finally, I would like to point out two lessons we have learned from this " -"example:" -msgstr "最後，我想指出我們從這個範例中學到的兩個教訓：" - -#: ../../howto/mro.rst:475 -msgid "" -"despite the name, the MRO determines the resolution order of attributes, not " -"only of methods;" -msgstr "儘管名稱如此，但不僅是方法的解析順序，MRO 也決定了屬性的解析順序；" - -#: ../../howto/mro.rst:478 -msgid "" -"the default food for Pythonistas is spam ! (but you already knew that ;-)" -msgstr "Pythonistas 的預設食物是 spam！（但是你已經知道 ;-)" - -#: ../../howto/mro.rst:481 -msgid "" -"Having discussed the issue of local precedence ordering, let me now consider " -"the issue of monotonicity. My goal is to show that neither the MRO for " -"classic classes nor that for Python 2.2 new style classes is monotonic." -msgstr "" -"在討論了區域優先順序的問題之後，現在讓我考慮單調性問題。我的目標是表明經典類" -"別的 MRO 或 Python 2.2 新式類別都不是單調的。" - -#: ../../howto/mro.rst:486 -msgid "" -"To prove that the MRO for classic classes is non-monotonic is rather " -"trivial, it is enough to look at the diamond diagram:" -msgstr "為了證明經典類別的 MRO 是非單調的，查看鑽石圖就足夠了：" - -#: ../../howto/mro.rst:489 -msgid "" -" C\n" -" / \\\n" -" / \\\n" -"A B\n" -" \\ /\n" -" \\ /\n" -" D" -msgstr "" -" C\n" -" / \\\n" -" / \\\n" -"A B\n" -" \\ /\n" -" \\ /\n" -" D" - -#: ../../howto/mro.rst:500 -msgid "One easily discerns the inconsistency::" -msgstr "可以很容易地辨別出這種不一致：" - -#: ../../howto/mro.rst:502 -msgid "" -"L[B,P21] = B C # B precedes C : B's methods win\n" -"L[D,P21] = D A C B C # B follows C : C's methods win!" -msgstr "" -"L[B,P21] = B C # B 優先於 C：B 的方法勝出\n" -"L[D,P21] = D A C B C # B 跟隨 C：C 的方法勝出！" - -#: ../../howto/mro.rst:505 -msgid "" -"On the other hand, there are no problems with the Python 2.2 and 2.3 MROs, " -"they give both::" -msgstr "另一方面，Python 2.2 和 2.3 MRO 沒有問題，它們兩個都給出了： ::" - -#: ../../howto/mro.rst:508 -msgid "L[D] = D A B C" -msgstr "L[D] = D A B C" - -#: ../../howto/mro.rst:510 -msgid "" -"Guido points out in his essay [#]_ that the classic MRO is not so bad in " -"practice, since one can typically avoids diamonds for classic classes. But " -"all new style classes inherit from ``object``, therefore diamonds are " -"unavoidable and inconsistencies shows up in every multiple inheritance graph." -msgstr "" -"Guido 在他的文章 [#]_ 中指出，經典的 MRO 在實踐中還不錯，因為通常可以避開經典" -"類別的鑽石圖。但是所有新式類別都從 ``object`` 繼承，因此鑽石圖是不可避免的，" -"並且在每個多重繼承圖中都出現了不一致之處。" - -#: ../../howto/mro.rst:516 -msgid "" -"The MRO of Python 2.2 makes breaking monotonicity difficult, but not " -"impossible. The following example, originally provided by Samuele Pedroni, " -"shows that the MRO of Python 2.2 is non-monotonic:" -msgstr "" -"Python 2.2 的 MRO 讓打破單調性變得困難，但並非不可能。以下最初由 Samuele " -"Pedroni 提供的範例展示 Python 2.2 的 MRO 是非單調的：" - -#: ../../howto/mro.rst:530 -msgid "" -"Here are the linearizations according to the C3 MRO (the reader should " -"verify these linearizations as an exercise and draw the inheritance " -"diagram ;-) ::" -msgstr "" -"以下是根據 C3 MRO 的線性化（讀者應練習驗證這些線性化並繪製繼承" -"圖 ;-) ： ::" - -#: ../../howto/mro.rst:534 -msgid "" -"L[A] = A O\n" -"L[B] = B O\n" -"L[C] = C O\n" -"L[D] = D O\n" -"L[E] = E O\n" -"L[K1]= K1 A B C O\n" -"L[K2]= K2 D B E O\n" -"L[K3]= K3 D A O\n" -"L[Z] = Z K1 K2 K3 D A B C E O" -msgstr "" -"L[A] = A O\n" -"L[B] = B O\n" -"L[C] = C O\n" -"L[D] = D O\n" -"L[E] = E O\n" -"L[K1]= K1 A B C O\n" -"L[K2]= K2 D B E O\n" -"L[K3]= K3 D A O\n" -"L[Z] = Z K1 K2 K3 D A B C E O" - -#: ../../howto/mro.rst:544 -msgid "" -"Python 2.2 gives exactly the same linearizations for A, B, C, D, E, K1, K2 " -"and K3, but a different linearization for Z::" -msgstr "" -"Python 2.2 給出了 A、B、C、D、E、K1、K2 和 K3 完全相同的線性化，但是 Z 的線性" -"化卻不同： ::" - -#: ../../howto/mro.rst:547 -msgid "L[Z,P22] = Z K1 K3 A K2 D B C E O" -msgstr "L[Z,P22] = Z K1 K3 A K2 D B C E O" - -#: ../../howto/mro.rst:549 -msgid "" -"It is clear that this linearization is *wrong*, since A comes before D " -"whereas in the linearization of K3 A comes *after* D. In other words, in K3 " -"methods derived by D override methods derived by A, but in Z, which still is " -"a subclass of K3, methods derived by A override methods derived by D! This " -"is a violation of monotonicity. Moreover, the Python 2.2 linearization of Z " -"is also inconsistent with local precedence ordering, since the local " -"precedence list of the class Z is [K1, K2, K3] (K2 precedes K3), whereas in " -"the linearization of Z K2 *follows* K3. These problems explain why the 2.2 " -"rule has been dismissed in favor of the C3 rule." -msgstr "" -"顯然，這種線性化是\\ *錯誤*\\ 的，因為 A 在 D 之前，而在 K3 的線性化中，A 在 " -"D *之後*。換句話說，在 K3 中由 D 衍生的方法會覆寫由 A 衍生的方法，但在 Z 中" -"（它仍然是 K3 的子類別），由 A 衍生的方法卻覆寫由 D 衍生的方法！這是對單調性" -"的違反。此外，Z 的 Python 2.2 線性化也與局部優先順序不一致，因為類別 Z 的局部" -"優先串列是 [K1, K2, K3]（K2 先於 K3），但在 Z 的線性化中 K2 *跟隨* K3。這些問" -"題解釋了為什麼 2.2 規則被摒棄而採用 C3 規則。" - -#: ../../howto/mro.rst:561 -msgid "The end" -msgstr "結語" - -#: ../../howto/mro.rst:563 -msgid "" -"This section is for the impatient reader, who skipped all the previous " -"sections and jumped immediately to the end. This section is for the lazy " -"programmer too, who didn't want to exercise her/his brain. Finally, it is " -"for the programmer with some hubris, otherwise s/he would not be reading a " -"paper on the C3 method resolution order in multiple inheritance " -"hierarchies ;-) These three virtues taken all together (and *not* " -"separately) deserve a prize: the prize is a short Python 2.2 script that " -"allows you to compute the 2.3 MRO without risk to your brain. Simply change " -"the last line to play with the various examples I have discussed in this " -"paper.::" -msgstr "" -"本節適用於那些不耐煩、所有先前部分都跳過並直接滑到最後的讀者，也適" -"用於懶得鍛鍊大腦的程式設計師。最後，這也是針對一些自負的程式" -"設計師，不然她/他也不會想閱讀有關多重繼承階層中 C3 方法解析順序的文章；-)" -"擁有這三種美德（注意是同時擁有，不是分開）就值得獲得獎品：獎品是一個簡短的 Python 2.2 腳" -"本，可以幫你計算 2.3 MRO 而不用傷腦筋。只需更改最後一行就可以試跑我在本" -"文中討論的各種範例。 ::" - -#: ../../howto/mro.rst:574 -msgid "" -"#\n" -"\n" -"\"\"\"C3 algorithm by Samuele Pedroni (with readability enhanced by me)." -"\"\"\"\n" -"\n" -"class __metaclass__(type):\n" -" \"All classes are metamagically modified to be nicely printed\"\n" -" __repr__ = lambda cls: cls.__name__\n" -"\n" -"class ex_2:\n" -" \"Serious order disagreement\" #From Guido\n" -" class O: pass\n" -" class X(O): pass\n" -" class Y(O): pass\n" -" class A(X,Y): pass\n" -" class B(Y,X): pass\n" -" try:\n" -" class Z(A,B): pass #creates Z(A,B) in Python 2.2\n" -" except TypeError:\n" -" pass # Z(A,B) cannot be created in Python 2.3\n" -"\n" -"class ex_5:\n" -" \"My first example\"\n" -" class O: pass\n" -" class F(O): pass\n" -" class E(O): pass\n" -" class D(O): pass\n" -" class C(D,F): pass\n" -" class B(D,E): pass\n" -" class A(B,C): pass\n" -"\n" -"class ex_6:\n" -" \"My second example\"\n" -" class O: pass\n" -" class F(O): pass\n" -" class E(O): pass\n" -" class D(O): pass\n" -" class C(D,F): pass\n" -" class B(E,D): pass\n" -" class A(B,C): pass\n" -"\n" -"class ex_9:\n" -" \"Difference between Python 2.2 MRO and C3\" #From Samuele\n" -" class O: pass\n" -" class A(O): pass\n" -" class B(O): pass\n" -" class C(O): pass\n" -" class D(O): pass\n" -" class E(O): pass\n" -" class K1(A,B,C): pass\n" -" class K2(D,B,E): pass\n" -" class K3(D,A): pass\n" -" class Z(K1,K2,K3): pass\n" -"\n" -"def merge(seqs):\n" -" print '\\n\\nCPL[%s]=%s' % (seqs[0][0],seqs),\n" -" res = []; i=0\n" -" while 1:\n" -" nonemptyseqs=[seq for seq in seqs if seq]\n" -" if not nonemptyseqs: return res\n" -" i+=1; print '\\n',i,'round: candidates...',\n" -" for seq in nonemptyseqs: # find merge candidates among seq heads\n" -" cand = seq[0]; print ' ',cand,\n" -" nothead=[s for s in nonemptyseqs if cand in s[1:]]\n" -" if nothead: cand=None #reject candidate\n" -" else: break\n" -" if not cand: raise \"Inconsistent hierarchy\"\n" -" res.append(cand)\n" -" for seq in nonemptyseqs: # remove cand\n" -" if seq[0] == cand: del seq[0]\n" -"\n" -"def mro(C):\n" -" \"Compute the class precedence list (mro) according to C3\"\n" -" return merge([[C]]+map(mro,C.__bases__)+[list(C.__bases__)])\n" -"\n" -"def print_mro(C):\n" -" print '\\nMRO[%s]=%s' % (C,mro(C))\n" -" print '\\nP22 MRO[%s]=%s' % (C,C.mro())\n" -"\n" -"print_mro(ex_9.Z)\n" -"\n" -"#" -msgstr "" -"#\n" -"\n" -"\"\"\"Samuele Pedroni 撰寫的 C3 演算法（由我改善了可讀性）。\"\"\"\n" -"\n" -"class __metaclass__(type):\n" -" \"所有類別都會被神奇地修改以便美觀地列印\"\n" -" __repr__ = lambda cls: cls.__name__\n" -"\n" -"class ex_2:\n" -" \"嚴重的順序分歧\" # 來自 Guido\n" -" class O: pass\n" -" class X(O): pass\n" -" class Y(O): pass\n" -" class A(X,Y): pass\n" -" class B(Y,X): pass\n" -" try:\n" -" class Z(A,B): pass # 在 Python 2.2 中會建立 Z(A,B)\n" -" except TypeError:\n" -" pass # 在 Python 2.3 中無法建立 Z(A,B)\n" -"\n" -"class ex_5:\n" -" \"我的第一個範例\"\n" -" class O: pass\n" -" class F(O): pass\n" -" class E(O): pass\n" -" class D(O): pass\n" -" class C(D,F): pass\n" -" class B(D,E): pass\n" -" class A(B,C): pass\n" -"\n" -"class ex_6:\n" -" \"我的第二個範例\"\n" -" class O: pass\n" -" class F(O): pass\n" -" class E(O): pass\n" -" class D(O): pass\n" -" class C(D,F): pass\n" -" class B(E,D): pass\n" -" class A(B,C): pass\n" -"\n" -"class ex_9:\n" -" \"Python 2.2 MRO 與 C3 的差異\" # 來自 Samuele\n" -" class O: pass\n" -" class A(O): pass\n" -" class B(O): pass\n" -" class C(O): pass\n" -" class D(O): pass\n" -" class E(O): pass\n" -" class K1(A,B,C): pass\n" -" class K2(D,B,E): pass\n" -" class K3(D,A): pass\n" -" class Z(K1,K2,K3): pass\n" -"\n" -"def merge(seqs):\n" -" print '\\n\\nCPL[%s]=%s' % (seqs[0][0],seqs),\n" -" res = []; i=0\n" -" while 1:\n" -" nonemptyseqs=[seq for seq in seqs if seq]\n" -" if not nonemptyseqs: return res\n" -" i+=1; print '\\n',i,'round: candidates...',\n" -" for seq in nonemptyseqs: # 在序列頭部中尋找合併候選者\n" -" cand = seq[0]; print ' ',cand,\n" -" nothead=[s for s in nonemptyseqs if cand in s[1:]]\n" -" if nothead: cand=None # 拒絕候選者\n" -" else: break\n" -" if not cand: raise \"不一致的階層結構\"\n" -" res.append(cand)\n" -" for seq in nonemptyseqs: # 移除候選者\n" -" if seq[0] == cand: del seq[0]\n" -"\n" -"def mro(C):\n" -" \"根據 C3 計算類別優先串列 (mro)\"\n" -" return merge([[C]]+map(mro,C.__bases__)+[list(C.__bases__)])\n" -"\n" -"def print_mro(C):\n" -" print '\\nMRO[%s]=%s' % (C,mro(C))\n" -" print '\\nP22 MRO[%s]=%s' % (C,C.mro())\n" -"\n" -"print_mro(ex_9.Z)\n" -"\n" -"#" - -#: ../../howto/mro.rst:656 -msgid "That's all folks," -msgstr "就這樣，各位，" - -#: ../../howto/mro.rst:658 -msgid "enjoy !" -msgstr "祝使用愉快！" - -#: ../../howto/mro.rst:662 -msgid "Resources" -msgstr "資源" - -#: ../../howto/mro.rst:664 -msgid "" -"The thread on python-dev started by Samuele Pedroni: https://mail.python.org/" -"pipermail/python-dev/2002-October/029035.html" -msgstr "" -"Samuele Pedroni 發起的 python-dev 主題討論：https://mail.python.org/" -"pipermail/python-dev/2002-October/029035.html" - -#: ../../howto/mro.rst:667 -msgid "" -"The paper *A Monotonic Superclass Linearization for Dylan*: https://doi.org/" -"10.1145/236337.236343" -msgstr "" -"論文 *A Monotonic Superclass Linearization for Dylan*: https://doi.org/" -"10.1145/236337.236343" - -#: ../../howto/mro.rst:670 -msgid "" -"Guido van Rossum's essay, *Unifying types and classes in Python 2.2*: " -"https://web.archive.org/web/20140210194412/http://www.python.org/download/" -"releases/2.2.2/descrintro" -msgstr "" -"Guido van Rossum 的文章 *Unifying types and classes in Python 2.2*：https://" -"web.archive.org/web/20140210194412/http://www.python.org/download/releases/" -"2.2.2/descrintro" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-01-22 00:13+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \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" + +#: ../../howto/mro.rst:4 +msgid "The Python 2.3 Method Resolution Order" +msgstr "Python 2.3 方法解析順序" + +#: ../../howto/mro.rst:8 +msgid "" +"This is a historical document, provided as an appendix to the official " +"documentation. The Method Resolution Order discussed here was *introduced* " +"in Python 2.3, but it is still used in later versions -- including Python 3." +msgstr "" +"這是一份歷史文件，作為正式文件的附錄提供。此處討論的方法解析順序 (Method " +"Resolution Order) 是在 Python 2.3 中 *引入* 的，但仍在後續版本中使用，包" +"括 Python 3。" + +#: ../../howto/mro.rst:13 +msgid "By `Michele Simionato `__." +msgstr "作者：`Michele Simionato `__。" + +#: ../../howto/mro.rst:0 +msgid "Abstract" +msgstr "摘要" + +#: ../../howto/mro.rst:17 +msgid "" +"*This document is intended for Python programmers who want to understand the " +"C3 Method Resolution Order used in Python 2.3. Although it is not intended " +"for newbies, it is quite pedagogical with many worked out examples. I am " +"not aware of other publicly available documents with the same scope, " +"therefore it should be useful.*" +msgstr "" +"*此文件適用於想要了解 Python 2.3 中使用的 C3 方法解析順序的 Python 程式設計" +"師。雖然它不是為初學者準備的，但透過許多實際範例進行教學。我沒找到其他具有相" +"同範圍的公開文件，因此這應該很有用。*" + +#: ../../howto/mro.rst:23 +msgid "Disclaimer:" +msgstr "免責聲明：" + +#: ../../howto/mro.rst:25 +msgid "" +"*I donate this document to the Python Software Foundation, under the Python " +"2.3 license. As usual in these circumstances, I warn the reader that what " +"follows* should *be correct, but I don't give any warranty. Use it at your " +"own risk and peril!*" +msgstr "" +"*我根據 Python 2.3 授權條款將此文件捐贈給 Python 軟體基金會。如同往常，我警告" +"讀者，以下內容 *應該* 是正確的，但我不提供任何保證。使用時風險自負！*" + +#: ../../howto/mro.rst:30 +msgid "Acknowledgments:" +msgstr "致謝：" + +#: ../../howto/mro.rst:32 +msgid "" +"*All the people of the Python mailing list who sent me their support. Paul " +"Foley who pointed out various imprecisions and made me to add the part on " +"local precedence ordering. David Goodger for help with the formatting in " +"reStructuredText. David Mertz for help with the editing. Finally, Guido van " +"Rossum who enthusiastically added this document to the official Python 2.3 " +"home-page.*" +msgstr "" +"*感謝 Python 郵件列表中所有給予我支持的人。Paul Foley 指出了各種不精確之處，並" +"促使我加入了區域優先順序（local precedence ordering）的部分。David Goodger 協" +"助 reStructuredText 的格式化。David Mertz 協助編輯。最後，Guido van Rossum 熱" +"情地將此文件加入到 Python 2.3 官方首頁。*" + +#: ../../howto/mro.rst:40 +msgid "The beginning" +msgstr "開端" + +#: ../../howto/mro.rst:42 +msgid "*Felix qui potuit rerum cognoscere causas* -- Virgilius" +msgstr "*Felix qui potuit rerum cognoscere causas* -- Virgilius" + +#: ../../howto/mro.rst:44 +msgid "" +"Everything started with a post by Samuele Pedroni to the Python development " +"mailing list [#]_. In his post, Samuele showed that the Python 2.2 method " +"resolution order is not monotonic and he proposed to replace it with the C3 " +"method resolution order. Guido agreed with his arguments and therefore now " +"Python 2.3 uses C3. The C3 method itself has nothing to do with Python, " +"since it was invented by people working on Dylan and it is described in a " +"paper intended for lispers [#]_. The present paper gives a (hopefully) " +"readable discussion of the C3 algorithm for Pythonistas who want to " +"understand the reasons for the change." +msgstr "" +"一切始於 Samuele Pedroni 向 Python 開發郵件列表發表的貼文 [#]_。在他的貼文" +"中，Samuele 指出 Python 2.2 的方法解析順序不具單調性（monotonic），並提議以 " +"C3 方法解析順序來取代。Guido 同意他的論點，因此 Python 2.3 現在使用 C3。C3 方" +"法本身與 Python 無關，因為它是由研究 Dylan 語言的人所發明，並在一篇針對 Lisp " +"程式設計師的論文 [#]_ 中描述。本文為想要了解此變更原因的 Python 程式設計師提" +"供了 C3 演算法（希望是）易讀的討論。" + +#: ../../howto/mro.rst:55 +msgid "" +"First of all, let me point out that what I am going to say only applies to " +"the *new style classes* introduced in Python 2.2: *classic classes* " +"maintain their old method resolution order, depth first and then left to " +"right. Therefore, there is no breaking of old code for classic classes; and " +"even if in principle there could be breaking of code for Python 2.2 new " +"style classes, in practice the cases in which the C3 resolution order " +"differs from the Python 2.2 method resolution order are so rare that no real " +"breaking of code is expected. Therefore:" +msgstr "" +"首先讓我指出，我要說的僅適用於 Python 2.2 中引入的 *新式類別（new style " +"classes）*：*經典類別（classic classes）* 維持其舊有的方法解析順序，即深度" +"優先然後由左至右。因此，經典類別的舊程式碼不會受到影響；即使原則上 Python 2.2 " +"新式類別的程式碼可能會受影響，但實際上 C3 解析順序與 Python 2.2 方法解析順序不" +"同的情況極為罕見，因此預期不會真正破壞程式碼。因此：" + +#: ../../howto/mro.rst:64 +msgid "*Don't be scared!*" +msgstr "*別怕！*" + +#: ../../howto/mro.rst:66 +msgid "" +"Moreover, unless you make strong use of multiple inheritance and you have " +"non-trivial hierarchies, you don't need to understand the C3 algorithm, and " +"you can easily skip this paper. On the other hand, if you really want to " +"know how multiple inheritance works, then this paper is for you. The good " +"news is that things are not as complicated as you might expect." +msgstr "" +"此外，除非你大量使用多重繼承且有複雜的類別階層，否則你無需了解 C3 演算法，可" +"以輕鬆跳過本文。另一方面，如果你真的想知道多重繼承如何運作，那麼本文就是為你" +"準備的。好消息是，事情並不像你想像的那樣複雜。" + +#: ../../howto/mro.rst:73 +msgid "Let me begin with some basic definitions." +msgstr "讓我從一些基本定義開始。" + +#: ../../howto/mro.rst:75 +msgid "" +"Given a class C in a complicated multiple inheritance hierarchy, it is a non-" +"trivial task to specify the order in which methods are overridden, i.e. to " +"specify the order of the ancestors of C." +msgstr "" +"給定複雜多重繼承階層中的類別 C，要指定方法被覆寫（override）的順序並非易事，" +"也就是要指定 C 的祖先順序。" + +#: ../../howto/mro.rst:79 +msgid "" +"The list of the ancestors of a class C, including the class itself, ordered " +"from the nearest ancestor to the furthest, is called the class precedence " +"list or the *linearization* of C." +msgstr "" +"類別 C 的祖先串列（包含類別本身），從最近的祖先到最遠的祖先排序，稱為類別優先" +"串列（class precedence list）或 C 的\\ *線性化（linearization）*。" + +#: ../../howto/mro.rst:83 +msgid "" +"The *Method Resolution Order* (MRO) is the set of rules that construct the " +"linearization. In the Python literature, the idiom \"the MRO of C\" is also " +"used as a synonymous for the linearization of the class C." +msgstr "" +"*方法解析順序 (Method Resolution Order, MRO)* 是建構線性化的一組規則。在 " +"Python 文獻中，習慣用語「C 的 MRO」也是 C 類別線性化的同義詞。" + +#: ../../howto/mro.rst:88 +msgid "" +"For instance, in the case of single inheritance hierarchy, if C is a " +"subclass of C1, and C1 is a subclass of C2, then the linearization of C is " +"simply the list [C, C1 , C2]. However, with multiple inheritance " +"hierarchies, the construction of the linearization is more cumbersome, since " +"it is more difficult to construct a linearization that respects *local " +"precedence ordering* and *monotonicity*." +msgstr "" +"例如，在單一繼承階層的情況下，如果 C 是 C1 的子類別，而 C1 是 C2 的子類別，那" +"麼 C 的線性化就是串列 [C, C1, C2]。然而，在多重繼承階層中，線性化的建構更加複" +"雜，因為要建構一個遵守\\ *區域優先順序（local precedence ordering）* 和\\ *" +"單調性（monotonicity）* 的線性化更加困難。" + +#: ../../howto/mro.rst:96 +msgid "" +"I will discuss the local precedence ordering later, but I can give the " +"definition of monotonicity here. A MRO is monotonic when the following is " +"true: *if C1 precedes C2 in the linearization of C, then C1 precedes C2 in " +"the linearization of any subclass of C*. Otherwise, the innocuous operation " +"of deriving a new class could change the resolution order of methods, " +"potentially introducing very subtle bugs. Examples where this happens will " +"be shown later." +msgstr "" +"我將在稍後討論區域優先順序，但可以在此給出單調性的定義。當以下條件為真時，" +"MRO 具有單調性：*如果 C1 在 C 的線性化中先於 C2，那麼 C1 在 C 的任何子類別的" +"線性化中也先於 C2*。否則，衍生新類別這個看似無害的操作可能會改變方法的解析順" +"序，進而引入非常微妙的錯誤。稍後將展示發生這種情況的範例。" + +#: ../../howto/mro.rst:104 +msgid "" +"Not all classes admit a linearization. There are cases, in complicated " +"hierarchies, where it is not possible to derive a class such that its " +"linearization respects all the desired properties." +msgstr "" +"並非所有類別都能進行線性化。在複雜的階層結構中，有些情況下無法衍生出一個類別，" +"使其線性化遵守所有所需的屬性。" + +#: ../../howto/mro.rst:108 +msgid "Here I give an example of this situation. Consider the hierarchy" +msgstr "以下是這種情況的範例。考慮以下階層結構" + +#: ../../howto/mro.rst:116 +msgid "" +"which can be represented with the following inheritance graph, where I have " +"denoted with O the ``object`` class, which is the beginning of any hierarchy " +"for new style classes:" +msgstr "" +"可以用以下繼承圖來表示，其中我用 O 標示 ``object`` 類別，這是新式類別的任何階" +"層結構的起點：" + +#: ../../howto/mro.rst:120 +msgid "" +" -----------\n" +"| |\n" +"| O |\n" +"| / \\ |\n" +" - X Y /\n" +" | / | /\n" +" | / |/\n" +" A B\n" +" \\ /\n" +" ?" +msgstr "" +" -----------\n" +"| |\n" +"| O |\n" +"| / \\ |\n" +" - X Y /\n" +" | / | /\n" +" | / |/\n" +" A B\n" +" \\ /\n" +" ?" + +#: ../../howto/mro.rst:133 +msgid "" +"In this case, it is not possible to derive a new class C from A and B, since " +"X precedes Y in A, but Y precedes X in B, therefore the method resolution " +"order would be ambiguous in C." +msgstr "" +"在這種情況下，不可能從 A 和 B 衍生出新的類別 C，因為 X 在 A 中先於 Y，但 Y 在 " +"B 中先於 X，因此 C 的方法解析順序會產生歧義。" + +#: ../../howto/mro.rst:137 +msgid "" +"Python 2.3 raises an exception in this situation (TypeError: MRO conflict " +"among bases Y, X) forbidding the naive programmer from creating ambiguous " +"hierarchies. Python 2.2 instead does not raise an exception, but chooses an " +"*ad hoc* ordering (CABXYO in this case)." +msgstr "" +"Python 2.3 在這種情況下會引發例外（TypeError: MRO conflict among bases Y, X），" +"防止程式設計師建立有歧義的階層結構。Python 2.2 則不會引發例外，而是選擇 *ad " +"hoc* 順序（在這種情況下為 CABXYO）。" + +#: ../../howto/mro.rst:143 +msgid "The C3 Method Resolution Order" +msgstr "C3 方法解析順序" + +#: ../../howto/mro.rst:145 +msgid "" +"Let me introduce a few simple notations which will be useful for the " +"following discussion. I will use the shortcut notation::" +msgstr "讓我介紹一些簡單的符號標示法，這對以下討論很有用。我將使用簡寫符號： ::" + +#: ../../howto/mro.rst:148 +msgid "C1 C2 ... CN" +msgstr "C1 C2 ... CN" + +#: ../../howto/mro.rst:150 +msgid "to indicate the list of classes [C1, C2, ... , CN]." +msgstr "用來表示類別串列 [C1, C2, ... , CN]。" + +#: ../../howto/mro.rst:152 +msgid "The *head* of the list is its first element::" +msgstr "串列的 *head*\\ （頭部）是其第一個元素： ::" + +#: ../../howto/mro.rst:154 +msgid "head = C1" +msgstr "head = C1" + +#: ../../howto/mro.rst:156 +msgid "whereas the *tail* is the rest of the list::" +msgstr "而 *tail*\\ （尾部）是串列的其餘部分： ::" + +#: ../../howto/mro.rst:158 +msgid "tail = C2 ... CN." +msgstr "tail = C2 ... CN." + +#: ../../howto/mro.rst:160 +msgid "I shall also use the notation::" +msgstr "我還將使用以下符號： ::" + +#: ../../howto/mro.rst:162 +msgid "C + (C1 C2 ... CN) = C C1 C2 ... CN" +msgstr "C + (C1 C2 ... CN) = C C1 C2 ... CN" + +#: ../../howto/mro.rst:164 +msgid "to denote the sum of the lists [C] + [C1, C2, ... ,CN]." +msgstr "標示串列的和 [C] + [C1, C2, ..., CN]。" + +#: ../../howto/mro.rst:166 +msgid "Now I can explain how the MRO works in Python 2.3." +msgstr "現在我就可以繼續解釋 MRO 在 Python 2.3 中的運作方式。" + +#: ../../howto/mro.rst:168 +msgid "" +"Consider a class C in a multiple inheritance hierarchy, with C inheriting " +"from the base classes B1, B2, ... , BN. We want to compute the " +"linearization L[C] of the class C. The rule is the following:" +msgstr "" +"考慮多重繼承階層結構中的類別 C，C 從基底類別 B1、B2、...、BN 繼承。我們想計算" +"類別 C 的線性化 L[C]。規則如下：" + +#: ../../howto/mro.rst:173 +msgid "" +"*the linearization of C is the sum of C plus the merge of the linearizations " +"of the parents and the list of the parents.*" +msgstr "*C 的線性化是 C 加上父類別線性化的合併以及父類別串列的和。*" + +#: ../../howto/mro.rst:176 +msgid "In symbolic notation::" +msgstr "用符號標示： ::" + +#: ../../howto/mro.rst:178 +msgid "L[C(B1 ... BN)] = C + merge(L[B1] ... L[BN], B1 ... BN)" +msgstr "L[C(B1 ... BN)] = C + merge(L[B1] ... L[BN], B1 ... BN)" + +#: ../../howto/mro.rst:180 +msgid "" +"In particular, if C is the ``object`` class, which has no parents, the " +"linearization is trivial::" +msgstr "" +"特別是如果 C 是沒有父類別的 ``object`` 類別，那麼線性化是簡單的：" + +#: ../../howto/mro.rst:183 +msgid "L[object] = object." +msgstr "L[object] = object." + +#: ../../howto/mro.rst:185 +msgid "" +"However, in general one has to compute the merge according to the following " +"prescription:" +msgstr "然而，一般來說必須根據以下規則來計算合併：" + +#: ../../howto/mro.rst:188 +msgid "" +"*take the head of the first list, i.e L[B1][0]; if this head is not in the " +"tail of any of the other lists, then add it to the linearization of C and " +"remove it from the lists in the merge, otherwise look at the head of the " +"next list and take it, if it is a good head. Then repeat the operation " +"until all the class are removed or it is impossible to find good heads. In " +"this case, it is impossible to construct the merge, Python 2.3 will refuse " +"to create the class C and will raise an exception.*" +msgstr "" +"*取第一個串列的頭部，即 L[B1][0]；如果此頭部不在其他任何串列的尾部中，那麼將" +"它加入到 C 的線性化中，並從合併中的所有串列移除它；否則查看下一個串列的頭部，" +"如果它是一個好的頭部就取它。然後重複此操作，直到所有類別都被移除或無法找到好的" +"頭部。在後面這種情況下，無法建構合併，Python 2.3 將拒絕建立類別 C 並引發例外。*" + +#: ../../howto/mro.rst:197 +msgid "" +"This prescription ensures that the merge operation *preserves* the ordering, " +"if the ordering can be preserved. On the other hand, if the order cannot be " +"preserved (as in the example of serious order disagreement discussed above) " +"then the merge cannot be computed." +msgstr "" +"此規則確保合併操作\\ *保留*\\ 順序（如果順序可以被保留）。另一方面，如果無法保" +"留順序（如上面討論的嚴重順序分歧的範例），則無法計算合併。" + +#: ../../howto/mro.rst:202 +msgid "" +"The computation of the merge is trivial if C has only one parent (single " +"inheritance); in this case::" +msgstr "" +"如果 C 只有一個父類別（單一繼承），則合併的計算是微不足道的。在這種情況" +"下： ::" + +#: ../../howto/mro.rst:205 +msgid "L[C(B)] = C + merge(L[B],B) = C + L[B]" +msgstr "L[C(B)] = C + merge(L[B],B) = C + L[B]" + +#: ../../howto/mro.rst:207 +msgid "" +"However, in the case of multiple inheritance things are more cumbersome and " +"I don't expect you can understand the rule without a couple of examples ;-)" +msgstr "" +"但是，在多重繼承的情況下，事情更加複雜，我不指望你能在沒有幾個範例的情況下理解這個規則 ;-)" + +#: ../../howto/mro.rst:212 +msgid "Examples" +msgstr "範例" + +#: ../../howto/mro.rst:214 +msgid "First example. Consider the following hierarchy:" +msgstr "第一個例子，請參考以下階層結構：" + +#: ../../howto/mro.rst:224 +msgid "In this case the inheritance graph can be drawn as:" +msgstr "在這種情況下，繼承圖可以繪製為：" + +#: ../../howto/mro.rst:226 +msgid "" +" 6\n" +" ---\n" +"Level 3 | O | (more general)\n" +" / --- \\\n" +" / | \\ |\n" +" / | \\ |\n" +" / | \\ |\n" +" --- --- --- |\n" +"Level 2 3 | D | 4| E | | F | 5 |\n" +" --- --- --- |\n" +" \\ \\ _ / | |\n" +" \\ / \\ _ | |\n" +" \\ / \\ | |\n" +" --- --- |\n" +"Level 1 1 | B | | C | 2 |\n" +" --- --- |\n" +" \\ / |\n" +" \\ / \\ /\n" +" ---\n" +"Level 0 0 | A | (more specialized)\n" +" ---" +msgstr "" +" 6\n" +" ---\n" +"Level 3 | O | （更廣泛）\n" +" / --- \\\n" +" / | \\ |\n" +" / | \\ |\n" +" / | \\ |\n" +" --- --- --- |\n" +"Level 2 3 | D | 4| E | | F | 5 |\n" +" --- --- --- |\n" +" \\ \\ _ / | |\n" +" \\ / \\ _ | |\n" +" \\ / \\ | |\n" +" --- --- |\n" +"Level 1 1 | B | | C | 2 |\n" +" --- --- |\n" +" \\ / |\n" +" \\ / \\ /\n" +" ---\n" +"Level 0 0 | A | （更專精）\n" +" ---" + +#: ../../howto/mro.rst:251 +msgid "The linearizations of O,D,E and F are trivial::" +msgstr "O、D、E 和 F 的線性化很簡單： ::" + +#: ../../howto/mro.rst:253 +msgid "" +"L[O] = O\n" +"L[D] = D O\n" +"L[E] = E O\n" +"L[F] = F O" +msgstr "" +"L[O] = O\n" +"L[D] = D O\n" +"L[E] = E O\n" +"L[F] = F O" + +#: ../../howto/mro.rst:258 +msgid "The linearization of B can be computed as::" +msgstr "B 的線性化可以計算為： ::" + +#: ../../howto/mro.rst:260 +msgid "L[B] = B + merge(DO, EO, DE)" +msgstr "L[B] = B + merge(DO, EO, DE)" + +#: ../../howto/mro.rst:262 +msgid "" +"We see that D is a good head, therefore we take it and we are reduced to " +"compute ``merge(O,EO,E)``. Now O is not a good head, since it is in the " +"tail of the sequence EO. In this case the rule says that we have to skip to " +"the next sequence. Then we see that E is a good head; we take it and we are " +"reduced to compute ``merge(O,O)`` which gives O. Therefore::" +msgstr "" +"我們看到 D 是一個好的頭部，因此我們取它，並將其簡化為 ``merge(O,EO,E)``。現" +"在 O 不是一個好的頭部，因為它位於序列 EO 的尾部。在這種情況下，規則說我們必須" +"跳到下一個序列。然後我們看到 E 是一個好的頭部；我們取它，並簡化為計算 " +"``merge(O, O)`` 得出 O。因此： ::" + +#: ../../howto/mro.rst:268 +msgid "L[B] = B D E O" +msgstr "L[B] = B D E O" + +#: ../../howto/mro.rst:270 +msgid "Using the same procedure one finds::" +msgstr "使用相同的程序可以發現： ::" + +#: ../../howto/mro.rst:272 +msgid "" +"L[C] = C + merge(DO,FO,DF)\n" +" = C + D + merge(O,FO,F)\n" +" = C + D + F + merge(O,O)\n" +" = C D F O" +msgstr "" +"L[C] = C + merge(DO,FO,DF)\n" +" = C + D + merge(O,FO,F)\n" +" = C + D + F + merge(O,O)\n" +" = C D F O" + +#: ../../howto/mro.rst:277 +msgid "Now we can compute::" +msgstr "現在我們可以計算出： ::" + +#: ../../howto/mro.rst:279 +msgid "" +"L[A] = A + merge(BDEO,CDFO,BC)\n" +" = A + B + merge(DEO,CDFO,C)\n" +" = A + B + C + merge(DEO,DFO)\n" +" = A + B + C + D + merge(EO,FO)\n" +" = A + B + C + D + E + merge(O,FO)\n" +" = A + B + C + D + E + F + merge(O,O)\n" +" = A B C D E F O" +msgstr "" +"L[A] = A + merge(BDEO,CDFO,BC)\n" +" = A + B + merge(DEO,CDFO,C)\n" +" = A + B + C + merge(DEO,DFO)\n" +" = A + B + C + D + merge(EO,FO)\n" +" = A + B + C + D + E + merge(O,FO)\n" +" = A + B + C + D + E + F + merge(O,O)\n" +" = A B C D E F O" + +#: ../../howto/mro.rst:287 +msgid "" +"In this example, the linearization is ordered in a pretty nice way according " +"to the inheritance level, in the sense that lower levels (i.e. more " +"specialized classes) have higher precedence (see the inheritance graph). " +"However, this is not the general case." +msgstr "" +"在此範例中，線性化是根據繼承層級以相當不錯的方式排序的，因為較低層級（即更專" +"精的類別）具有更高的優先級（請參見繼承圖）。但是這不是一般情況。" + +#: ../../howto/mro.rst:292 +msgid "" +"I leave as an exercise for the reader to compute the linearization for my " +"second example:" +msgstr "第二個範例的線性化之計算我留給讀者當作練習：" + +#: ../../howto/mro.rst:303 +msgid "" +"The only difference with the previous example is the change B(D,E) --> " +"B(E,D); however even such a little modification completely changes the " +"ordering of the hierarchy:" +msgstr "" +"與上一個範例的唯一區別是 B(D,E) --> B(E,D) 的變化；但是即使是這樣小小的修改，也完" +"全改變了階層結構的順序：" + +#: ../../howto/mro.rst:307 +msgid "" +" 6\n" +" ---\n" +"Level 3 | O |\n" +" / --- \\\n" +" / | \\\n" +" / | \\\n" +" / | \\\n" +" --- --- ---\n" +"Level 2 2 | E | 4 | D | | F | 5\n" +" --- --- ---\n" +" \\ / \\ /\n" +" \\ / \\ /\n" +" \\ / \\ /\n" +" --- ---\n" +"Level 1 1 | B | | C | 3\n" +" --- ---\n" +" \\ /\n" +" \\ /\n" +" ---\n" +"Level 0 0 | A |\n" +" ---" +msgstr "" +" 6\n" +" ---\n" +"Level 3 | O |\n" +" / --- \\\n" +" / | \\\n" +" / | \\\n" +" / | \\\n" +" --- --- ---\n" +"Level 2 2 | E | 4 | D | | F | 5\n" +" --- --- ---\n" +" \\ / \\ /\n" +" \\ / \\ /\n" +" \\ / \\ /\n" +" --- ---\n" +"Level 1 1 | B | | C | 3\n" +" --- ---\n" +" \\ /\n" +" \\ /\n" +" ---\n" +"Level 0 0 | A |\n" +" ---" + +#: ../../howto/mro.rst:332 +msgid "" +"Notice that the class E, which is in the second level of the hierarchy, " +"precedes the class C, which is in the first level of the hierarchy, i.e. E " +"is more specialized than C, even if it is in a higher level." +msgstr "" +"請注意，階層結構的第二層中的類別 E，先於階層結構第一層的類別 C，即 E 比 C 更" +"專精，即使它處於更高層。" + +#: ../../howto/mro.rst:336 +msgid "" +"A lazy programmer can obtain the MRO directly from Python 2.2, since in this " +"case it coincides with the Python 2.3 linearization. It is enough to invoke " +"the :meth:`~type.mro` method of class A:" +msgstr "" +"懶惰的程式設計師可以直接從 Python 2.2 取得 MRO，因為在這種情況下，它與 " +"Python 2.3 線性化一致。呼叫類別 A 的 :meth:`~type.mro` 方法就足夠了：" + +#: ../../howto/mro.rst:345 +msgid "" +"Finally, let me consider the example discussed in the first section, " +"involving a serious order disagreement. In this case, it is straightforward " +"to compute the linearizations of O, X, Y, A and B:" +msgstr "" +"最後，讓我考慮第一部分中討論的範例，涉及嚴重的順序分歧。在這種情況下，計算 " +"O、X、Y、A 和 B 的線性化是很簡單的：" + +#: ../../howto/mro.rst:349 +msgid "" +"L[O] = 0\n" +"L[X] = X O\n" +"L[Y] = Y O\n" +"L[A] = A X Y O\n" +"L[B] = B Y X O" +msgstr "" +"L[O] = 0\n" +"L[X] = X O\n" +"L[Y] = Y O\n" +"L[A] = A X Y O\n" +"L[B] = B Y X O" + +#: ../../howto/mro.rst:357 +msgid "" +"However, it is impossible to compute the linearization for a class C that " +"inherits from A and B::" +msgstr "但是，我們不可能計算出從 A 和 B 繼承的類別 C 的線性化： ::" + +#: ../../howto/mro.rst:360 +msgid "" +"L[C] = C + merge(AXYO, BYXO, AB)\n" +" = C + A + merge(XYO, BYXO, B)\n" +" = C + A + B + merge(XYO, YXO)" +msgstr "" +"L[C] = C + merge(AXYO, BYXO, AB)\n" +" = C + A + merge(XYO, BYXO, B)\n" +" = C + A + B + merge(XYO, YXO)" + +#: ../../howto/mro.rst:364 +msgid "" +"At this point we cannot merge the lists XYO and YXO, since X is in the tail " +"of YXO whereas Y is in the tail of XYO: therefore there are no good heads " +"and the C3 algorithm stops. Python 2.3 raises an error and refuses to " +"create the class C." +msgstr "" +"在這一點上，我們無法合併串列 XYO 和 YXO，因為 X 位於 YXO 的尾部，而 Y 則位於 " +"XYO 的尾部：因此，沒有好的頭部，C3 演算法停止。Python 2.3 會引發錯誤而拒絕建" +"立類別 C。" + +#: ../../howto/mro.rst:370 +msgid "Bad Method Resolution Orders" +msgstr "不良的方法解析順序" + +#: ../../howto/mro.rst:372 +msgid "" +"A MRO is *bad* when it breaks such fundamental properties as local " +"precedence ordering and monotonicity. In this section, I will show that " +"both the MRO for classic classes and the MRO for new style classes in Python " +"2.2 are bad." +msgstr "" +"當 MRO 打破諸如區域優先順序和單調性之類的基本屬性時，MRO 是\\ *不良*\\ 的。在本節" +"中，我將證明經典類別的 MRO 和 Python 2.2 的新式類別的 MRO 都是不好的。" + +#: ../../howto/mro.rst:377 +msgid "" +"It is easier to start with the local precedence ordering. Consider the " +"following example:" +msgstr "從區域優先順序開始更容易。考慮以下範例：" + +#: ../../howto/mro.rst:384 +msgid "with inheritance diagram" +msgstr "包含繼承圖" + +#: ../../howto/mro.rst:386 +msgid "" +" O\n" +" |\n" +"(buy spam) F\n" +" | \\\n" +" | E (buy eggs)\n" +" | /\n" +" G\n" +"\n" +" (buy eggs or spam ?)" +msgstr "" +" O\n" +" |\n" +"(buy spam) F\n" +" | \\\n" +" | E (buy eggs)\n" +" | /\n" +" G\n" +"\n" +" (buy eggs or spam ?)" + +#: ../../howto/mro.rst:399 +msgid "" +"We see that class G inherits from F and E, with F *before* E: therefore we " +"would expect the attribute *G.remember2buy* to be inherited by " +"*F.remember2buy* and not by *E.remember2buy*: nevertheless Python 2.2 gives" +msgstr "" +"我們看到類別 G 從 F 和 E 繼承，F 在 E *之前*：因此，我們希望屬性 " +"*G.remember2buy* 被 *F.remember2buy* 繼承，而不是 *E.remember2buy*：儘管如" +"此，Python 2.2 給出" + +#: ../../howto/mro.rst:407 +msgid "" +"This is a breaking of local precedence ordering since the order in the local " +"precedence list, i.e. the list of the parents of G, is not preserved in the " +"Python 2.2 linearization of G::" +msgstr "" +"這是區域優先順序的破壞，因為區域優先串列中的順序，即 G 的父類別串列，在 " +"Python 2.2 的 G 的線性化中不被保留：" + +#: ../../howto/mro.rst:411 +msgid "L[G,P22]= G E F object # F *follows* E" +msgstr "L[G,P22]= G E F object # F *跟隨* E" + +#: ../../howto/mro.rst:413 +msgid "" +"One could argue that the reason why F follows E in the Python 2.2 " +"linearization is that F is less specialized than E, since F is the " +"superclass of E; nevertheless the breaking of local precedence ordering is " +"quite non-intuitive and error prone. This is particularly true since it is " +"a different from old style classes:" +msgstr "" +"有人可能會說，F 在 Python 2.2 線性化中跟隨 E 的原因是 F 比 E 特化程度較低，" +"因為 F 是 E 的超類別；然而，局部優先順序的破壞非常不直覺且容易出錯。尤其如" +"此，因為它與舊式類別不同：" + +#: ../../howto/mro.rst:425 +msgid "" +"In this case the MRO is GFEF and the local precedence ordering is preserved." +msgstr "在這種情況下，MRO 是 GFEF 並且保留區域優先順序。" + +#: ../../howto/mro.rst:428 +msgid "" +"As a general rule, hierarchies such as the previous one should be avoided, " +"since it is unclear if F should override E or vice-versa. Python 2.3 solves " +"the ambiguity by raising an exception in the creation of class G, " +"effectively stopping the programmer from generating ambiguous hierarchies. " +"The reason for that is that the C3 algorithm fails when the merge::" +msgstr "" +"通常應避免諸如上一個等階層結構，因為尚不清楚 F 是否應覆蓋 E 或反過來。 " +"Python 2.3 透過在建立類別 G 時引發例外來解決歧義，從而有效地阻止程式設計師產" +"生模棱兩可的階層結構。原因是當這樣合併時 C3 演算法會失敗： ::" + +#: ../../howto/mro.rst:435 +msgid "merge(FO,EFO,FE)" +msgstr "merge(FO,EFO,FE)" + +#: ../../howto/mro.rst:437 +msgid "" +"cannot be computed, because F is in the tail of EFO and E is in the tail of " +"FE." +msgstr "無法計算，因為 F 在 EFO 的尾部，而 E 在 FE 的尾部。" + +#: ../../howto/mro.rst:440 +msgid "" +"The real solution is to design a non-ambiguous hierarchy, i.e. to derive G " +"from E and F (the more specific first) and not from F and E; in this case " +"the MRO is GEF without any doubt." +msgstr "" +"真正的解決方案是設計一個非歧義的階層結構，即源自 E 和 F（更具體的第一）而不" +"是 F 和 E；在這種情況下，MRO 毫無疑問是 GEF。" + +#: ../../howto/mro.rst:444 +msgid "" +" O\n" +" |\n" +" F (spam)\n" +" / |\n" +"(eggs) E |\n" +" \\ |\n" +" G\n" +" (eggs, no doubt)" +msgstr "" +" O\n" +" |\n" +" F (spam)\n" +" / |\n" +"(eggs) E |\n" +" \\ |\n" +" G\n" +" (eggs, no doubt)" + +#: ../../howto/mro.rst:456 +msgid "" +"Python 2.3 forces the programmer to write good hierarchies (or, at least, " +"less error-prone ones)." +msgstr "Python 2.3 迫使程式設計師要編寫良好（或至少較不易於出錯）的階層結構。" + +#: ../../howto/mro.rst:459 +msgid "" +"On a related note, let me point out that the Python 2.3 algorithm is smart " +"enough to recognize obvious mistakes, as the duplication of classes in the " +"list of parents:" +msgstr "" +"與之相關的是，我指出 Python 2.3 演算法足夠聰明，可以識別出明顯的錯誤，例" +"如父類別串列中類別的重複：" + +#: ../../howto/mro.rst:469 +msgid "" +"Python 2.2 (both for classic classes and new style classes) in this " +"situation, would not raise any exception." +msgstr "" +"在這種情況下，Python 2.2（無論是經典類別還是新式類別）不會引發任何例外。" + +#: ../../howto/mro.rst:472 +msgid "" +"Finally, I would like to point out two lessons we have learned from this " +"example:" +msgstr "最後，我想指出我們從這個範例中學到的兩個教訓：" + +#: ../../howto/mro.rst:475 +msgid "" +"despite the name, the MRO determines the resolution order of attributes, not " +"only of methods;" +msgstr "儘管名稱如此，但不僅是方法的解析順序，MRO 也決定了屬性的解析順序；" + +#: ../../howto/mro.rst:478 +msgid "" +"the default food for Pythonistas is spam ! (but you already knew that ;-)" +msgstr "Pythonistas 的預設食物是 spam！（但是你已經知道 ;-)" + +#: ../../howto/mro.rst:481 +msgid "" +"Having discussed the issue of local precedence ordering, let me now consider " +"the issue of monotonicity. My goal is to show that neither the MRO for " +"classic classes nor that for Python 2.2 new style classes is monotonic." +msgstr "" +"在討論了區域優先順序的問題之後，現在讓我考慮單調性問題。我的目標是表明經典類" +"別的 MRO 或 Python 2.2 新式類別都不是單調的。" + +#: ../../howto/mro.rst:486 +msgid "" +"To prove that the MRO for classic classes is non-monotonic is rather " +"trivial, it is enough to look at the diamond diagram:" +msgstr "為了證明經典類別的 MRO 是非單調的，查看鑽石圖就足夠了：" + +#: ../../howto/mro.rst:489 +msgid "" +" C\n" +" / \\\n" +" / \\\n" +"A B\n" +" \\ /\n" +" \\ /\n" +" D" +msgstr "" +" C\n" +" / \\\n" +" / \\\n" +"A B\n" +" \\ /\n" +" \\ /\n" +" D" + +#: ../../howto/mro.rst:500 +msgid "One easily discerns the inconsistency::" +msgstr "可以很容易地辨別出這種不一致：" + +#: ../../howto/mro.rst:502 +msgid "" +"L[B,P21] = B C # B precedes C : B's methods win\n" +"L[D,P21] = D A C B C # B follows C : C's methods win!" +msgstr "" +"L[B,P21] = B C # B 優先於 C：B 的方法勝出\n" +"L[D,P21] = D A C B C # B 跟隨 C：C 的方法勝出！" + +#: ../../howto/mro.rst:505 +msgid "" +"On the other hand, there are no problems with the Python 2.2 and 2.3 MROs, " +"they give both::" +msgstr "另一方面，Python 2.2 和 2.3 MRO 沒有問題，它們兩個都給出了： ::" + +#: ../../howto/mro.rst:508 +msgid "L[D] = D A B C" +msgstr "L[D] = D A B C" + +#: ../../howto/mro.rst:510 +msgid "" +"Guido points out in his essay [#]_ that the classic MRO is not so bad in " +"practice, since one can typically avoids diamonds for classic classes. But " +"all new style classes inherit from ``object``, therefore diamonds are " +"unavoidable and inconsistencies shows up in every multiple inheritance graph." +msgstr "" +"Guido 在他的文章 [#]_ 中指出，經典的 MRO 在實踐中還不錯，因為通常可以避開經典" +"類別的鑽石圖。但是所有新式類別都從 ``object`` 繼承，因此鑽石圖是不可避免的，" +"並且在每個多重繼承圖中都出現了不一致之處。" + +#: ../../howto/mro.rst:516 +msgid "" +"The MRO of Python 2.2 makes breaking monotonicity difficult, but not " +"impossible. The following example, originally provided by Samuele Pedroni, " +"shows that the MRO of Python 2.2 is non-monotonic:" +msgstr "" +"Python 2.2 的 MRO 讓打破單調性變得困難，但並非不可能。以下最初由 Samuele " +"Pedroni 提供的範例展示 Python 2.2 的 MRO 是非單調的：" + +#: ../../howto/mro.rst:530 +msgid "" +"Here are the linearizations according to the C3 MRO (the reader should " +"verify these linearizations as an exercise and draw the inheritance " +"diagram ;-) ::" +msgstr "" +"以下是根據 C3 MRO 的線性化（讀者應練習驗證這些線性化並繪製繼承" +"圖 ;-) ： ::" + +#: ../../howto/mro.rst:534 +msgid "" +"L[A] = A O\n" +"L[B] = B O\n" +"L[C] = C O\n" +"L[D] = D O\n" +"L[E] = E O\n" +"L[K1]= K1 A B C O\n" +"L[K2]= K2 D B E O\n" +"L[K3]= K3 D A O\n" +"L[Z] = Z K1 K2 K3 D A B C E O" +msgstr "" +"L[A] = A O\n" +"L[B] = B O\n" +"L[C] = C O\n" +"L[D] = D O\n" +"L[E] = E O\n" +"L[K1]= K1 A B C O\n" +"L[K2]= K2 D B E O\n" +"L[K3]= K3 D A O\n" +"L[Z] = Z K1 K2 K3 D A B C E O" + +#: ../../howto/mro.rst:544 +msgid "" +"Python 2.2 gives exactly the same linearizations for A, B, C, D, E, K1, K2 " +"and K3, but a different linearization for Z::" +msgstr "" +"Python 2.2 給出了 A、B、C、D、E、K1、K2 和 K3 完全相同的線性化，但是 Z 的線性" +"化卻不同： ::" + +#: ../../howto/mro.rst:547 +msgid "L[Z,P22] = Z K1 K3 A K2 D B C E O" +msgstr "L[Z,P22] = Z K1 K3 A K2 D B C E O" + +#: ../../howto/mro.rst:549 +msgid "" +"It is clear that this linearization is *wrong*, since A comes before D " +"whereas in the linearization of K3 A comes *after* D. In other words, in K3 " +"methods derived by D override methods derived by A, but in Z, which still is " +"a subclass of K3, methods derived by A override methods derived by D! This " +"is a violation of monotonicity. Moreover, the Python 2.2 linearization of Z " +"is also inconsistent with local precedence ordering, since the local " +"precedence list of the class Z is [K1, K2, K3] (K2 precedes K3), whereas in " +"the linearization of Z K2 *follows* K3. These problems explain why the 2.2 " +"rule has been dismissed in favor of the C3 rule." +msgstr "" +"顯然，這種線性化是\\ *錯誤*\\ 的，因為 A 在 D 之前，而在 K3 的線性化中，A 在 " +"D *之後*。換句話說，在 K3 中由 D 衍生的方法會覆寫由 A 衍生的方法，但在 Z 中" +"（它仍然是 K3 的子類別），由 A 衍生的方法卻覆寫由 D 衍生的方法！這是對單調性" +"的違反。此外，Z 的 Python 2.2 線性化也與局部優先順序不一致，因為類別 Z 的局部" +"優先串列是 [K1, K2, K3]（K2 先於 K3），但在 Z 的線性化中 K2 *跟隨* K3。這些問" +"題解釋了為什麼 2.2 規則被摒棄而採用 C3 規則。" + +#: ../../howto/mro.rst:561 +msgid "The end" +msgstr "結語" + +#: ../../howto/mro.rst:563 +msgid "" +"This section is for the impatient reader, who skipped all the previous " +"sections and jumped immediately to the end. This section is for the lazy " +"programmer too, who didn't want to exercise her/his brain. Finally, it is " +"for the programmer with some hubris, otherwise s/he would not be reading a " +"paper on the C3 method resolution order in multiple inheritance " +"hierarchies ;-) These three virtues taken all together (and *not* " +"separately) deserve a prize: the prize is a short Python 2.2 script that " +"allows you to compute the 2.3 MRO without risk to your brain. Simply change " +"the last line to play with the various examples I have discussed in this " +"paper.::" +msgstr "" +"本節適用於那些不耐煩、所有先前部分都跳過並直接滑到最後的讀者，也適" +"用於懶得鍛鍊大腦的程式設計師。最後，這也是針對一些自負的程式" +"設計師，不然她/他也不會想閱讀有關多重繼承階層中 C3 方法解析順序的文章；-)" +"擁有這三種美德（注意是同時擁有，不是分開）就值得獲得獎品：獎品是一個簡短的 Python 2.2 腳" +"本，可以幫你計算 2.3 MRO 而不用傷腦筋。只需更改最後一行就可以試跑我在本" +"文中討論的各種範例。 ::" + +#: ../../howto/mro.rst:574 +msgid "" +"#\n" +"\n" +"\"\"\"C3 algorithm by Samuele Pedroni (with readability enhanced by me)." +"\"\"\"\n" +"\n" +"class __metaclass__(type):\n" +" \"All classes are metamagically modified to be nicely printed\"\n" +" __repr__ = lambda cls: cls.__name__\n" +"\n" +"class ex_2:\n" +" \"Serious order disagreement\" #From Guido\n" +" class O: pass\n" +" class X(O): pass\n" +" class Y(O): pass\n" +" class A(X,Y): pass\n" +" class B(Y,X): pass\n" +" try:\n" +" class Z(A,B): pass #creates Z(A,B) in Python 2.2\n" +" except TypeError:\n" +" pass # Z(A,B) cannot be created in Python 2.3\n" +"\n" +"class ex_5:\n" +" \"My first example\"\n" +" class O: pass\n" +" class F(O): pass\n" +" class E(O): pass\n" +" class D(O): pass\n" +" class C(D,F): pass\n" +" class B(D,E): pass\n" +" class A(B,C): pass\n" +"\n" +"class ex_6:\n" +" \"My second example\"\n" +" class O: pass\n" +" class F(O): pass\n" +" class E(O): pass\n" +" class D(O): pass\n" +" class C(D,F): pass\n" +" class B(E,D): pass\n" +" class A(B,C): pass\n" +"\n" +"class ex_9:\n" +" \"Difference between Python 2.2 MRO and C3\" #From Samuele\n" +" class O: pass\n" +" class A(O): pass\n" +" class B(O): pass\n" +" class C(O): pass\n" +" class D(O): pass\n" +" class E(O): pass\n" +" class K1(A,B,C): pass\n" +" class K2(D,B,E): pass\n" +" class K3(D,A): pass\n" +" class Z(K1,K2,K3): pass\n" +"\n" +"def merge(seqs):\n" +" print '\\n\\nCPL[%s]=%s' % (seqs[0][0],seqs),\n" +" res = []; i=0\n" +" while 1:\n" +" nonemptyseqs=[seq for seq in seqs if seq]\n" +" if not nonemptyseqs: return res\n" +" i+=1; print '\\n',i,'round: candidates...',\n" +" for seq in nonemptyseqs: # find merge candidates among seq heads\n" +" cand = seq[0]; print ' ',cand,\n" +" nothead=[s for s in nonemptyseqs if cand in s[1:]]\n" +" if nothead: cand=None #reject candidate\n" +" else: break\n" +" if not cand: raise \"Inconsistent hierarchy\"\n" +" res.append(cand)\n" +" for seq in nonemptyseqs: # remove cand\n" +" if seq[0] == cand: del seq[0]\n" +"\n" +"def mro(C):\n" +" \"Compute the class precedence list (mro) according to C3\"\n" +" return merge([[C]]+map(mro,C.__bases__)+[list(C.__bases__)])\n" +"\n" +"def print_mro(C):\n" +" print '\\nMRO[%s]=%s' % (C,mro(C))\n" +" print '\\nP22 MRO[%s]=%s' % (C,C.mro())\n" +"\n" +"print_mro(ex_9.Z)\n" +"\n" +"#" +msgstr "" +"#\n" +"\n" +"\"\"\"Samuele Pedroni 撰寫的 C3 演算法（由我改善了可讀性）。\"\"\"\n" +"\n" +"class __metaclass__(type):\n" +" \"所有類別都會被神奇地修改以便美觀地列印\"\n" +" __repr__ = lambda cls: cls.__name__\n" +"\n" +"class ex_2:\n" +" \"嚴重的順序分歧\" # 來自 Guido\n" +" class O: pass\n" +" class X(O): pass\n" +" class Y(O): pass\n" +" class A(X,Y): pass\n" +" class B(Y,X): pass\n" +" try:\n" +" class Z(A,B): pass # 在 Python 2.2 中會建立 Z(A,B)\n" +" except TypeError:\n" +" pass # 在 Python 2.3 中無法建立 Z(A,B)\n" +"\n" +"class ex_5:\n" +" \"我的第一個範例\"\n" +" class O: pass\n" +" class F(O): pass\n" +" class E(O): pass\n" +" class D(O): pass\n" +" class C(D,F): pass\n" +" class B(D,E): pass\n" +" class A(B,C): pass\n" +"\n" +"class ex_6:\n" +" \"我的第二個範例\"\n" +" class O: pass\n" +" class F(O): pass\n" +" class E(O): pass\n" +" class D(O): pass\n" +" class C(D,F): pass\n" +" class B(E,D): pass\n" +" class A(B,C): pass\n" +"\n" +"class ex_9:\n" +" \"Python 2.2 MRO 與 C3 的差異\" # 來自 Samuele\n" +" class O: pass\n" +" class A(O): pass\n" +" class B(O): pass\n" +" class C(O): pass\n" +" class D(O): pass\n" +" class E(O): pass\n" +" class K1(A,B,C): pass\n" +" class K2(D,B,E): pass\n" +" class K3(D,A): pass\n" +" class Z(K1,K2,K3): pass\n" +"\n" +"def merge(seqs):\n" +" print '\\n\\nCPL[%s]=%s' % (seqs[0][0],seqs),\n" +" res = []; i=0\n" +" while 1:\n" +" nonemptyseqs=[seq for seq in seqs if seq]\n" +" if not nonemptyseqs: return res\n" +" i+=1; print '\\n',i,'round: candidates...',\n" +" for seq in nonemptyseqs: # 在序列頭部中尋找合併候選者\n" +" cand = seq[0]; print ' ',cand,\n" +" nothead=[s for s in nonemptyseqs if cand in s[1:]]\n" +" if nothead: cand=None # 拒絕候選者\n" +" else: break\n" +" if not cand: raise \"不一致的階層結構\"\n" +" res.append(cand)\n" +" for seq in nonemptyseqs: # 移除候選者\n" +" if seq[0] == cand: del seq[0]\n" +"\n" +"def mro(C):\n" +" \"根據 C3 計算類別優先串列 (mro)\"\n" +" return merge([[C]]+map(mro,C.__bases__)+[list(C.__bases__)])\n" +"\n" +"def print_mro(C):\n" +" print '\\nMRO[%s]=%s' % (C,mro(C))\n" +" print '\\nP22 MRO[%s]=%s' % (C,C.mro())\n" +"\n" +"print_mro(ex_9.Z)\n" +"\n" +"#" + +#: ../../howto/mro.rst:656 +msgid "That's all folks," +msgstr "就這樣，各位，" + +#: ../../howto/mro.rst:658 +msgid "enjoy !" +msgstr "祝使用愉快！" + +#: ../../howto/mro.rst:662 +msgid "Resources" +msgstr "資源" + +#: ../../howto/mro.rst:664 +msgid "" +"The thread on python-dev started by Samuele Pedroni: https://mail.python.org/" +"pipermail/python-dev/2002-October/029035.html" +msgstr "" +"Samuele Pedroni 發起的 python-dev 主題討論：https://mail.python.org/" +"pipermail/python-dev/2002-October/029035.html" + +#: ../../howto/mro.rst:667 +msgid "" +"The paper *A Monotonic Superclass Linearization for Dylan*: https://doi.org/" +"10.1145/236337.236343" +msgstr "" +"論文 *A Monotonic Superclass Linearization for Dylan*: https://doi.org/" +"10.1145/236337.236343" + +#: ../../howto/mro.rst:670 +msgid "" +"Guido van Rossum's essay, *Unifying types and classes in Python 2.2*: " +"https://web.archive.org/web/20140210194412/http://www.python.org/download/" +"releases/2.2.2/descrintro" +msgstr "" +"Guido van Rossum 的文章 *Unifying types and classes in Python 2.2*：https://" +"web.archive.org/web/20140210194412/http://www.python.org/download/releases/" +"2.2.2/descrintro" diff --git a/howto/perf_profiling.po b/howto/perf_profiling.po index d606afed56..473dd4abe3 100644 --- a/howto/perf_profiling.po +++ b/howto/perf_profiling.po @@ -1,631 +1,631 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Matt Wang , 2023 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-04-19 00:14+0000\n" -"PO-Revision-Date: 2023-12-09 17:39+0800\n" -"Last-Translator: Matt Wang \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" - -#: ../../howto/perf_profiling.rst:7 -msgid "Python support for the Linux ``perf`` profiler" -msgstr "Python 對 Linux ``perf`` 分析器的支援" - -#: ../../howto/perf_profiling.rst:0 -msgid "author" -msgstr "作者" - -#: ../../howto/perf_profiling.rst:9 -msgid "Pablo Galindo" -msgstr "Pablo Galindo" - -#: ../../howto/perf_profiling.rst:11 -msgid "" -"`The Linux perf profiler `_ is a very powerful " -"tool that allows you to profile and obtain information about the performance " -"of your application. ``perf`` also has a very vibrant ecosystem of tools " -"that aid with the analysis of the data that it produces." -msgstr "" -"`Linux 性能分析器 (Linux perf profiler) `_ 是一" -"個非常強大的工具，可讓你分析並取得有關應用程式的性能資訊。``perf`` 還擁有一個" -"非常活躍的工具生態系統，有助於分析其生成的資料。" - -#: ../../howto/perf_profiling.rst:17 -msgid "" -"The main problem with using the ``perf`` profiler with Python applications " -"is that ``perf`` only gets information about native symbols, that is, the " -"names of functions and procedures written in C. This means that the names " -"and file names of Python functions in your code will not appear in the " -"output of ``perf``." -msgstr "" -"在 Python 應用程式中使用 ``perf`` 分析器的主要問題是 ``perf`` 僅取得有關原生" -"符號的資訊，即用 C 編寫的函式和程式的名稱。這表示程式碼中的 Python 函式名稱和" -"檔案名稱不會出現在 ``perf`` 的輸出中。" - -#: ../../howto/perf_profiling.rst:22 -msgid "" -"Since Python 3.12, the interpreter can run in a special mode that allows " -"Python functions to appear in the output of the ``perf`` profiler. When this " -"mode is enabled, the interpreter will interpose a small piece of code " -"compiled on the fly before the execution of every Python function and it " -"will teach ``perf`` the relationship between this piece of code and the " -"associated Python function using :doc:`perf map files <../c-api/perfmaps>`." -msgstr "" -"從 Python 3.12 開始，直譯器可以在特殊模式下執行，該模式允許 Python 函式出現" -"在 ``perf`` 分析器的輸出中。啟用此模式後，直譯器將在執行每個 Python 函式之前" -"插入 (interpose) 一小段動態編譯的程式碼，並使用 :doc:`perf map 檔案 <../c-" -"api/perfmaps>`\\ 來告訴 ``perf`` 這段程式碼與相關聯的 Python 函式間的關係。" - -#: ../../howto/perf_profiling.rst:31 -msgid "" -"Support for the ``perf`` profiler is currently only available for Linux on " -"select architectures. Check the output of the ``configure`` build step or " -"check the output of ``python -m sysconfig | grep HAVE_PERF_TRAMPOLINE`` to " -"see if your system is supported." -msgstr "" -"目前對 ``perf`` 分析器的支援僅適用於 Linux 的特定架構上。檢查 ``configure`` " -"建構步驟的輸出或檢查 ``python -m sysconfig | grep HAVE_PERF_TRAMPOLINE`` 的輸" -"出來查看你的系統是否支援。" - -#: ../../howto/perf_profiling.rst:36 -msgid "For example, consider the following script:" -msgstr "例如，參考以下腳本：" - -#: ../../howto/perf_profiling.rst:38 -msgid "" -"def foo(n):\n" -" result = 0\n" -" for _ in range(n):\n" -" result += 1\n" -" return result\n" -"\n" -"def bar(n):\n" -" foo(n)\n" -"\n" -"def baz(n):\n" -" bar(n)\n" -"\n" -"if __name__ == \"__main__\":\n" -" baz(1000000)" -msgstr "" -"def foo(n):\n" -" result = 0\n" -" for _ in range(n):\n" -" result += 1\n" -" return result\n" -"\n" -"def bar(n):\n" -" foo(n)\n" -"\n" -"def baz(n):\n" -" bar(n)\n" -"\n" -"if __name__ == \"__main__\":\n" -" baz(1000000)" - -#: ../../howto/perf_profiling.rst:55 -msgid "We can run ``perf`` to sample CPU stack traces at 9999 hertz::" -msgstr "我們可以執行 ``perf`` 以 9999 赫茲取樣 CPU 堆疊追蹤 (stack trace)： ::" - -#: ../../howto/perf_profiling.rst:57 -msgid "$ perf record -F 9999 -g -o perf.data python my_script.py" -msgstr "$ perf record -F 9999 -g -o perf.data python my_script.py" - -#: ../../howto/perf_profiling.rst:59 -msgid "Then we can use ``perf report`` to analyze the data:" -msgstr "然後我們可以使用 ``perf report`` 來分析資料：" - -#: ../../howto/perf_profiling.rst:61 -msgid "" -"$ perf report --stdio -n -g\n" -"\n" -"# Children Self Samples Command Shared Object Symbol\n" -"# ........ ........ ............ .......... .................. ..........................................\n" -"#\n" -" 91.08% 0.00% 0 python.exe python.exe [.] " -"_start\n" -" |\n" -" ---_start\n" -" |\n" -" --90.71%--__libc_start_main\n" -" Py_BytesMain\n" -" |\n" -" |--56.88%--pymain_run_python.constprop.0\n" -" | |\n" -" | |--56.13%--_PyRun_AnyFileObject\n" -" | | _PyRun_SimpleFileObject\n" -" | | |\n" -" | | |--55.02%--run_mod\n" -" | | | |\n" -" | | | --54.65%--" -"PyEval_EvalCode\n" -" | | | " -"_PyEval_EvalFrameDefault\n" -" | | | " -"PyObject_Vectorcall\n" -" | | | " -"_PyEval_Vector\n" -" | | | " -"_PyEval_EvalFrameDefault\n" -" | | | " -"PyObject_Vectorcall\n" -" | | | " -"_PyEval_Vector\n" -" | | | " -"_PyEval_EvalFrameDefault\n" -" | | | " -"PyObject_Vectorcall\n" -" | | | " -"_PyEval_Vector\n" -" | | | |\n" -" | | | " -"|--51.67%--_PyEval_EvalFrameDefault\n" -" | | | " -"| |\n" -" | | | " -"| |--11.52%--_PyLong_Add\n" -" | | | " -"| | |\n" -" | | | " -"| | |--2.97%--_PyObject_Malloc\n" -"..." -msgstr "" -"$ perf report --stdio -n -g\n" -"\n" -"# Children Self Samples Command Shared Object Symbol\n" -"# ........ ........ ............ .......... .................. ..........................................\n" -"#\n" -" 91.08% 0.00% 0 python.exe python.exe [.] " -"_start\n" -" |\n" -" ---_start\n" -" |\n" -" --90.71%--__libc_start_main\n" -" Py_BytesMain\n" -" |\n" -" |--56.88%--pymain_run_python.constprop.0\n" -" | |\n" -" | |--56.13%--_PyRun_AnyFileObject\n" -" | | _PyRun_SimpleFileObject\n" -" | | |\n" -" | | |--55.02%--run_mod\n" -" | | | |\n" -" | | | --54.65%--" -"PyEval_EvalCode\n" -" | | | " -"_PyEval_EvalFrameDefault\n" -" | | | " -"PyObject_Vectorcall\n" -" | | | " -"_PyEval_Vector\n" -" | | | " -"_PyEval_EvalFrameDefault\n" -" | | | " -"PyObject_Vectorcall\n" -" | | | " -"_PyEval_Vector\n" -" | | | " -"_PyEval_EvalFrameDefault\n" -" | | | " -"PyObject_Vectorcall\n" -" | | | " -"_PyEval_Vector\n" -" | | | |\n" -" | | | " -"|--51.67%--_PyEval_EvalFrameDefault\n" -" | | | " -"| |\n" -" | | | " -"| |--11.52%--_PyLong_Add\n" -" | | | " -"| | |\n" -" | | | " -"| | |--2.97%--_PyObject_Malloc\n" -"..." - -#: ../../howto/perf_profiling.rst:100 -msgid "" -"As you can see, the Python functions are not shown in the output, only " -"``_PyEval_EvalFrameDefault`` (the function that evaluates the Python " -"bytecode) shows up. Unfortunately that's not very useful because all Python " -"functions use the same C function to evaluate bytecode so we cannot know " -"which Python function corresponds to which bytecode-evaluating function." -msgstr "" -"如你所見，Python 函式未顯示在輸出中，僅顯示 ``_Py_Eval_EvalFrameDefault`` " -"（為 Python 位元組碼 (bytecode) 求值的函式）。不幸的是，這不是很有用，因為所" -"有 Python 函式都使用相同的 C 函式來替位元組碼求值，因此我們無法知道哪個 " -"Python 函式是對應於哪個位元組碼計算函式。" - -#: ../../howto/perf_profiling.rst:105 -msgid "" -"Instead, if we run the same experiment with ``perf`` support enabled we get:" -msgstr "" -"作為替代，如果我們在啟用 ``perf`` 支援的情況下執行相同的實驗，我們會得到：" - -#: ../../howto/perf_profiling.rst:107 -msgid "" -"$ perf report --stdio -n -g\n" -"\n" -"# Children Self Samples Command Shared Object Symbol\n" -"# ........ ........ ............ .......... .................. .....................................................................\n" -"#\n" -" 90.58% 0.36% 1 python.exe python.exe [.] " -"_start\n" -" |\n" -" ---_start\n" -" |\n" -" --89.86%--__libc_start_main\n" -" Py_BytesMain\n" -" |\n" -" |--55.43%--pymain_run_python.constprop.0\n" -" | |\n" -" | |--54.71%--_PyRun_AnyFileObject\n" -" | | _PyRun_SimpleFileObject\n" -" | | |\n" -" | | |--53.62%--run_mod\n" -" | | | |\n" -" | | | --53.26%--" -"PyEval_EvalCode\n" -" | | | py::" -":/src/script.py\n" -" | | | " -"_PyEval_EvalFrameDefault\n" -" | | | " -"PyObject_Vectorcall\n" -" | | | " -"_PyEval_Vector\n" -" | | | py::baz:/" -"src/script.py\n" -" | | | " -"_PyEval_EvalFrameDefault\n" -" | | | " -"PyObject_Vectorcall\n" -" | | | " -"_PyEval_Vector\n" -" | | | py::bar:/" -"src/script.py\n" -" | | | " -"_PyEval_EvalFrameDefault\n" -" | | | " -"PyObject_Vectorcall\n" -" | | | " -"_PyEval_Vector\n" -" | | | py::foo:/" -"src/script.py\n" -" | | | |\n" -" | | | " -"|--51.81%--_PyEval_EvalFrameDefault\n" -" | | | " -"| |\n" -" | | | " -"| |--13.77%--_PyLong_Add\n" -" | | | " -"| | |\n" -" | | | " -"| | |--3.26%--_PyObject_Malloc" -msgstr "" -"$ perf report --stdio -n -g\n" -"\n" -"# Children Self Samples Command Shared Object Symbol\n" -"# ........ ........ ............ .......... .................. .....................................................................\n" -"#\n" -" 90.58% 0.36% 1 python.exe python.exe [.] " -"_start\n" -" |\n" -" ---_start\n" -" |\n" -" --89.86%--__libc_start_main\n" -" Py_BytesMain\n" -" |\n" -" |--55.43%--pymain_run_python.constprop.0\n" -" | |\n" -" | |--54.71%--_PyRun_AnyFileObject\n" -" | | _PyRun_SimpleFileObject\n" -" | | |\n" -" | | |--53.62%--run_mod\n" -" | | | |\n" -" | | | --53.26%--" -"PyEval_EvalCode\n" -" | | | py::" -":/src/script.py\n" -" | | | " -"_PyEval_EvalFrameDefault\n" -" | | | " -"PyObject_Vectorcall\n" -" | | | " -"_PyEval_Vector\n" -" | | | py::baz:/" -"src/script.py\n" -" | | | " -"_PyEval_EvalFrameDefault\n" -" | | | " -"PyObject_Vectorcall\n" -" | | | " -"_PyEval_Vector\n" -" | | | py::bar:/" -"src/script.py\n" -" | | | " -"_PyEval_EvalFrameDefault\n" -" | | | " -"PyObject_Vectorcall\n" -" | | | " -"_PyEval_Vector\n" -" | | | py::foo:/" -"src/script.py\n" -" | | | |\n" -" | | | " -"|--51.81%--_PyEval_EvalFrameDefault\n" -" | | | " -"| |\n" -" | | | " -"| |--13.77%--_PyLong_Add\n" -" | | | " -"| | |\n" -" | | | " -"| | |--3.26%--_PyObject_Malloc" - -#: ../../howto/perf_profiling.rst:152 -msgid "How to enable ``perf`` profiling support" -msgstr "如何啟用 ``perf`` 分析支援" - -#: ../../howto/perf_profiling.rst:154 -msgid "" -"``perf`` profiling support can be enabled either from the start using the " -"environment variable :envvar:`PYTHONPERFSUPPORT` or the :option:`-X perf <-" -"X>` option, or dynamically using :func:`sys.activate_stack_trampoline` " -"and :func:`sys.deactivate_stack_trampoline`." -msgstr "" -"要啟用 ``perf`` 分析支援，可以在一開始就使用環境變" -"數 :envvar:`PYTHONPERFSUPPORT` 或使用 :option:`-X perf <-X>` 選項，也可以使" -"用 :func:`sys.activate_stack_trampoline` " -"和 :func:`sys.deactivate_stack_trampoline` 來動態啟用。" - -#: ../../howto/perf_profiling.rst:160 -msgid "" -"The :mod:`!sys` functions take precedence over the :option:`!-X` option, " -"the :option:`!-X` option takes precedence over the environment variable." -msgstr "" -":mod:`!sys` 函式優先於 :option:`!-X` 選項、:option:`!-X` 選項優先於環境變數。" - -#: ../../howto/perf_profiling.rst:163 -msgid "Example, using the environment variable::" -msgstr "例如，使用環境變數： ::" - -#: ../../howto/perf_profiling.rst:165 -msgid "" -"$ PYTHONPERFSUPPORT=1 perf record -F 9999 -g -o perf.data python " -"my_script.py\n" -"$ perf report -g -i perf.data" -msgstr "" -"$ PYTHONPERFSUPPORT=1 perf record -F 9999 -g -o perf.data python " -"my_script.py\n" -"$ perf report -g -i perf.data" - -#: ../../howto/perf_profiling.rst:168 -msgid "Example, using the :option:`!-X` option::" -msgstr "例如，使用 :option:`!-X` 選項： ::" - -#: ../../howto/perf_profiling.rst:170 -msgid "" -"$ perf record -F 9999 -g -o perf.data python -X perf my_script.py\n" -"$ perf report -g -i perf.data" -msgstr "" -"$ perf record -F 9999 -g -o perf.data python -X perf my_script.py\n" -"$ perf report -g -i perf.data" - -#: ../../howto/perf_profiling.rst:173 -msgid "Example, using the :mod:`sys` APIs in file :file:`example.py`:" -msgstr "例如，在 :file:`example.py` 檔案中使用 :mod:`sys` API：" - -#: ../../howto/perf_profiling.rst:175 -msgid "" -"import sys\n" -"\n" -"sys.activate_stack_trampoline(\"perf\")\n" -"do_profiled_stuff()\n" -"sys.deactivate_stack_trampoline()\n" -"\n" -"non_profiled_stuff()" -msgstr "" -"import sys\n" -"\n" -"sys.activate_stack_trampoline(\"perf\")\n" -"do_profiled_stuff()\n" -"sys.deactivate_stack_trampoline()\n" -"\n" -"non_profiled_stuff()" - -#: ../../howto/perf_profiling.rst:185 -msgid "...then::" -msgstr "...然後： ::" - -#: ../../howto/perf_profiling.rst:187 -msgid "" -"$ perf record -F 9999 -g -o perf.data python ./example.py\n" -"$ perf report -g -i perf.data" -msgstr "" -"$ perf record -F 9999 -g -o perf.data python ./example.py\n" -"$ perf report -g -i perf.data" - -#: ../../howto/perf_profiling.rst:192 -msgid "How to obtain the best results" -msgstr "如何獲得最佳結果" - -#: ../../howto/perf_profiling.rst:194 -msgid "" -"For best results, Python should be compiled with ``CFLAGS=\"-fno-omit-frame-" -"pointer -mno-omit-leaf-frame-pointer\"`` as this allows profilers to unwind " -"using only the frame pointer and not on DWARF debug information. This is " -"because as the code that is interposed to allow ``perf`` support is " -"dynamically generated it doesn't have any DWARF debugging information " -"available." -msgstr "" -"為了獲得最佳結果，應使用 ``CFLAGS=\"-fno-omit-frame-pointer -mno-omit-leaf-" -"frame-pointer\"`` 來進行 Python 編譯，因為這能允許分析器僅使用 frame 指標而不" -"是 DWARF 除錯資訊來解析 (unwind)。這是因為，由於插入以允許 ``perf`` 支援的程" -"式碼是動態生成的，因此它沒有任何可用的 DWARF 除錯資訊。" - -#: ../../howto/perf_profiling.rst:201 -msgid "" -"You can check if your system has been compiled with this flag by running::" -msgstr "你可以透過執行以下指令來檢查你的系統是否已使用此旗標進行編譯： ::" - -#: ../../howto/perf_profiling.rst:203 -msgid "$ python -m sysconfig | grep 'no-omit-frame-pointer'" -msgstr "$ python -m sysconfig | grep 'no-omit-frame-pointer'" - -#: ../../howto/perf_profiling.rst:205 -msgid "" -"If you don't see any output it means that your interpreter has not been " -"compiled with frame pointers and therefore it may not be able to show Python " -"functions in the output of ``perf``." -msgstr "" -"如果你沒有看到任何輸出，則表示你的直譯器尚未使用 frame 指標進行編譯，因此它可" -"能無法在 ``perf`` 的輸出中顯示 Python 函式。" - -#: ../../howto/perf_profiling.rst:211 -msgid "How to work without frame pointers" -msgstr "" - -#: ../../howto/perf_profiling.rst:213 -msgid "" -"If you are working with a Python interpreter that has been compiled without " -"frame pointers, you can still use the ``perf`` profiler, but the overhead " -"will be a bit higher because Python needs to generate unwinding information " -"for every Python function call on the fly. Additionally, ``perf`` will take " -"more time to process the data because it will need to use the DWARF " -"debugging information to unwind the stack and this is a slow process." -msgstr "" - -#: ../../howto/perf_profiling.rst:220 -msgid "" -"To enable this mode, you can use the environment " -"variable :envvar:`PYTHON_PERF_JIT_SUPPORT` or the :option:`-X perf_jit <-X>` " -"option, which will enable the JIT mode for the ``perf`` profiler." -msgstr "" - -#: ../../howto/perf_profiling.rst:226 -msgid "" -"Due to a bug in the ``perf`` tool, only ``perf`` versions higher than v6.8 " -"will work with the JIT mode. The fix was also backported to the v6.7.2 " -"version of the tool." -msgstr "" - -#: ../../howto/perf_profiling.rst:230 -msgid "" -"Note that when checking the version of the ``perf`` tool (which can be done " -"by running ``perf version``) you must take into account that some distros " -"add some custom version numbers including a ``-`` character. This means " -"that ``perf 6.7-3`` is not necessarily ``perf 6.7.3``." -msgstr "" - -#: ../../howto/perf_profiling.rst:235 -msgid "" -"When using the perf JIT mode, you need an extra step before you can run " -"``perf report``. You need to call the ``perf inject`` command to inject the " -"JIT information into the ``perf.data`` file.::" -msgstr "" - -#: ../../howto/perf_profiling.rst:239 -msgid "" -"$ perf record -F 9999 -g -k 1 --call-graph dwarf -o perf.data python " -"-Xperf_jit my_script.py\n" -"$ perf inject -i perf.data --jit --output perf.jit.data\n" -"$ perf report -g -i perf.jit.data" -msgstr "" -"$ perf record -F 9999 -g -k 1 --call-graph dwarf -o perf.data python " -"-Xperf_jit my_script.py\n" -"$ perf inject -i perf.data --jit --output perf.jit.data\n" -"$ perf report -g -i perf.jit.data" - -#: ../../howto/perf_profiling.rst:243 -msgid "or using the environment variable::" -msgstr "或使用環境變數： ::" - -#: ../../howto/perf_profiling.rst:245 -msgid "" -"$ PYTHON_PERF_JIT_SUPPORT=1 perf record -F 9999 -g --call-graph dwarf -o " -"perf.data python my_script.py\n" -"$ perf inject -i perf.data --jit --output perf.jit.data\n" -"$ perf report -g -i perf.jit.data" -msgstr "" -"$ PYTHON_PERF_JIT_SUPPORT=1 perf record -F 9999 -g --call-graph dwarf -o " -"perf.data python my_script.py\n" -"$ perf inject -i perf.data --jit --output perf.jit.data\n" -"$ perf report -g -i perf.jit.data" - -#: ../../howto/perf_profiling.rst:249 -msgid "" -"``perf inject --jit`` command will read ``perf.data``, automatically pick up " -"the perf dump file that Python creates (in ``/tmp/perf-$PID.dump``), and " -"then create ``perf.jit.data`` which merges all the JIT information together. " -"It should also create a lot of ``jitted-XXXX-N.so`` files in the current " -"directory which are ELF images for all the JIT trampolines that were created " -"by Python." -msgstr "" - -#: ../../howto/perf_profiling.rst:257 -msgid "" -"When using ``--call-graph dwarf``, the ``perf`` tool will take snapshots of " -"the stack of the process being profiled and save the information in the " -"``perf.data`` file. By default, the size of the stack dump is 8192 bytes, " -"but you can change the size by passing it after a comma like ``--call-graph " -"dwarf,16384``." -msgstr "" - -#: ../../howto/perf_profiling.rst:263 -msgid "" -"The size of the stack dump is important because if the size is too small " -"``perf`` will not be able to unwind the stack and the output will be " -"incomplete. On the other hand, if the size is too big, then ``perf`` won't " -"be able to sample the process as frequently as it would like as the overhead " -"will be higher." -msgstr "" - -#: ../../howto/perf_profiling.rst:269 -msgid "" -"The stack size is particularly important when profiling Python code compiled " -"with low optimization levels (like ``-O0``), as these builds tend to have " -"larger stack frames. If you are compiling Python with ``-O0`` and not seeing " -"Python functions in your profiling output, try increasing the stack dump " -"size to 65528 bytes (the maximum)::" -msgstr "" - -#: ../../howto/perf_profiling.rst:275 -msgid "" -"$ perf record -F 9999 -g -k 1 --call-graph dwarf,65528 -o perf.data python " -"-Xperf_jit my_script.py" -msgstr "" -"$ perf record -F 9999 -g -k 1 --call-graph dwarf,65528 -o perf.data python " -"-Xperf_jit my_script.py" - -#: ../../howto/perf_profiling.rst:277 -msgid "Different compilation flags can significantly impact stack sizes:" -msgstr "" - -#: ../../howto/perf_profiling.rst:279 -msgid "" -"Builds with ``-O0`` typically have much larger stack frames than those with " -"``-O1`` or higher" -msgstr "" - -#: ../../howto/perf_profiling.rst:280 -msgid "" -"Adding optimizations (``-O1``, ``-O2``, etc.) typically reduces stack size" -msgstr "" - -#: ../../howto/perf_profiling.rst:281 -msgid "" -"Frame pointers (``-fno-omit-frame-pointer``) generally provide more reliable " -"stack unwinding" -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Matt Wang , 2023 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-04-19 00:14+0000\n" +"PO-Revision-Date: 2023-12-09 17:39+0800\n" +"Last-Translator: Matt Wang \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" + +#: ../../howto/perf_profiling.rst:7 +msgid "Python support for the Linux ``perf`` profiler" +msgstr "Python 對 Linux ``perf`` 分析器的支援" + +#: ../../howto/perf_profiling.rst:0 +msgid "author" +msgstr "作者" + +#: ../../howto/perf_profiling.rst:9 +msgid "Pablo Galindo" +msgstr "Pablo Galindo" + +#: ../../howto/perf_profiling.rst:11 +msgid "" +"`The Linux perf profiler `_ is a very powerful " +"tool that allows you to profile and obtain information about the performance " +"of your application. ``perf`` also has a very vibrant ecosystem of tools " +"that aid with the analysis of the data that it produces." +msgstr "" +"`Linux 性能分析器 (Linux perf profiler) `_ 是一" +"個非常強大的工具，可讓你分析並取得有關應用程式的性能資訊。``perf`` 還擁有一個" +"非常活躍的工具生態系統，有助於分析其生成的資料。" + +#: ../../howto/perf_profiling.rst:17 +msgid "" +"The main problem with using the ``perf`` profiler with Python applications " +"is that ``perf`` only gets information about native symbols, that is, the " +"names of functions and procedures written in C. This means that the names " +"and file names of Python functions in your code will not appear in the " +"output of ``perf``." +msgstr "" +"在 Python 應用程式中使用 ``perf`` 分析器的主要問題是 ``perf`` 僅取得有關原生" +"符號的資訊，即用 C 編寫的函式和程式的名稱。這表示程式碼中的 Python 函式名稱和" +"檔案名稱不會出現在 ``perf`` 的輸出中。" + +#: ../../howto/perf_profiling.rst:22 +msgid "" +"Since Python 3.12, the interpreter can run in a special mode that allows " +"Python functions to appear in the output of the ``perf`` profiler. When this " +"mode is enabled, the interpreter will interpose a small piece of code " +"compiled on the fly before the execution of every Python function and it " +"will teach ``perf`` the relationship between this piece of code and the " +"associated Python function using :doc:`perf map files <../c-api/perfmaps>`." +msgstr "" +"從 Python 3.12 開始，直譯器可以在特殊模式下執行，該模式允許 Python 函式出現" +"在 ``perf`` 分析器的輸出中。啟用此模式後，直譯器將在執行每個 Python 函式之前" +"插入 (interpose) 一小段動態編譯的程式碼，並使用 :doc:`perf map 檔案 <../c-" +"api/perfmaps>`\\ 來告訴 ``perf`` 這段程式碼與相關聯的 Python 函式間的關係。" + +#: ../../howto/perf_profiling.rst:31 +msgid "" +"Support for the ``perf`` profiler is currently only available for Linux on " +"select architectures. Check the output of the ``configure`` build step or " +"check the output of ``python -m sysconfig | grep HAVE_PERF_TRAMPOLINE`` to " +"see if your system is supported." +msgstr "" +"目前對 ``perf`` 分析器的支援僅適用於 Linux 的特定架構上。檢查 ``configure`` " +"建構步驟的輸出或檢查 ``python -m sysconfig | grep HAVE_PERF_TRAMPOLINE`` 的輸" +"出來查看你的系統是否支援。" + +#: ../../howto/perf_profiling.rst:36 +msgid "For example, consider the following script:" +msgstr "例如，參考以下腳本：" + +#: ../../howto/perf_profiling.rst:38 +msgid "" +"def foo(n):\n" +" result = 0\n" +" for _ in range(n):\n" +" result += 1\n" +" return result\n" +"\n" +"def bar(n):\n" +" foo(n)\n" +"\n" +"def baz(n):\n" +" bar(n)\n" +"\n" +"if __name__ == \"__main__\":\n" +" baz(1000000)" +msgstr "" +"def foo(n):\n" +" result = 0\n" +" for _ in range(n):\n" +" result += 1\n" +" return result\n" +"\n" +"def bar(n):\n" +" foo(n)\n" +"\n" +"def baz(n):\n" +" bar(n)\n" +"\n" +"if __name__ == \"__main__\":\n" +" baz(1000000)" + +#: ../../howto/perf_profiling.rst:55 +msgid "We can run ``perf`` to sample CPU stack traces at 9999 hertz::" +msgstr "我們可以執行 ``perf`` 以 9999 赫茲取樣 CPU 堆疊追蹤 (stack trace)： ::" + +#: ../../howto/perf_profiling.rst:57 +msgid "$ perf record -F 9999 -g -o perf.data python my_script.py" +msgstr "$ perf record -F 9999 -g -o perf.data python my_script.py" + +#: ../../howto/perf_profiling.rst:59 +msgid "Then we can use ``perf report`` to analyze the data:" +msgstr "然後我們可以使用 ``perf report`` 來分析資料：" + +#: ../../howto/perf_profiling.rst:61 +msgid "" +"$ perf report --stdio -n -g\n" +"\n" +"# Children Self Samples Command Shared Object Symbol\n" +"# ........ ........ ............ .......... .................. ..........................................\n" +"#\n" +" 91.08% 0.00% 0 python.exe python.exe [.] " +"_start\n" +" |\n" +" ---_start\n" +" |\n" +" --90.71%--__libc_start_main\n" +" Py_BytesMain\n" +" |\n" +" |--56.88%--pymain_run_python.constprop.0\n" +" | |\n" +" | |--56.13%--_PyRun_AnyFileObject\n" +" | | _PyRun_SimpleFileObject\n" +" | | |\n" +" | | |--55.02%--run_mod\n" +" | | | |\n" +" | | | --54.65%--" +"PyEval_EvalCode\n" +" | | | " +"_PyEval_EvalFrameDefault\n" +" | | | " +"PyObject_Vectorcall\n" +" | | | " +"_PyEval_Vector\n" +" | | | " +"_PyEval_EvalFrameDefault\n" +" | | | " +"PyObject_Vectorcall\n" +" | | | " +"_PyEval_Vector\n" +" | | | " +"_PyEval_EvalFrameDefault\n" +" | | | " +"PyObject_Vectorcall\n" +" | | | " +"_PyEval_Vector\n" +" | | | |\n" +" | | | " +"|--51.67%--_PyEval_EvalFrameDefault\n" +" | | | " +"| |\n" +" | | | " +"| |--11.52%--_PyLong_Add\n" +" | | | " +"| | |\n" +" | | | " +"| | |--2.97%--_PyObject_Malloc\n" +"..." +msgstr "" +"$ perf report --stdio -n -g\n" +"\n" +"# Children Self Samples Command Shared Object Symbol\n" +"# ........ ........ ............ .......... .................. ..........................................\n" +"#\n" +" 91.08% 0.00% 0 python.exe python.exe [.] " +"_start\n" +" |\n" +" ---_start\n" +" |\n" +" --90.71%--__libc_start_main\n" +" Py_BytesMain\n" +" |\n" +" |--56.88%--pymain_run_python.constprop.0\n" +" | |\n" +" | |--56.13%--_PyRun_AnyFileObject\n" +" | | _PyRun_SimpleFileObject\n" +" | | |\n" +" | | |--55.02%--run_mod\n" +" | | | |\n" +" | | | --54.65%--" +"PyEval_EvalCode\n" +" | | | " +"_PyEval_EvalFrameDefault\n" +" | | | " +"PyObject_Vectorcall\n" +" | | | " +"_PyEval_Vector\n" +" | | | " +"_PyEval_EvalFrameDefault\n" +" | | | " +"PyObject_Vectorcall\n" +" | | | " +"_PyEval_Vector\n" +" | | | " +"_PyEval_EvalFrameDefault\n" +" | | | " +"PyObject_Vectorcall\n" +" | | | " +"_PyEval_Vector\n" +" | | | |\n" +" | | | " +"|--51.67%--_PyEval_EvalFrameDefault\n" +" | | | " +"| |\n" +" | | | " +"| |--11.52%--_PyLong_Add\n" +" | | | " +"| | |\n" +" | | | " +"| | |--2.97%--_PyObject_Malloc\n" +"..." + +#: ../../howto/perf_profiling.rst:100 +msgid "" +"As you can see, the Python functions are not shown in the output, only " +"``_PyEval_EvalFrameDefault`` (the function that evaluates the Python " +"bytecode) shows up. Unfortunately that's not very useful because all Python " +"functions use the same C function to evaluate bytecode so we cannot know " +"which Python function corresponds to which bytecode-evaluating function." +msgstr "" +"如你所見，Python 函式未顯示在輸出中，僅顯示 ``_Py_Eval_EvalFrameDefault`` " +"（為 Python 位元組碼 (bytecode) 求值的函式）。不幸的是，這不是很有用，因為所" +"有 Python 函式都使用相同的 C 函式來替位元組碼求值，因此我們無法知道哪個 " +"Python 函式是對應於哪個位元組碼計算函式。" + +#: ../../howto/perf_profiling.rst:105 +msgid "" +"Instead, if we run the same experiment with ``perf`` support enabled we get:" +msgstr "" +"作為替代，如果我們在啟用 ``perf`` 支援的情況下執行相同的實驗，我們會得到：" + +#: ../../howto/perf_profiling.rst:107 +msgid "" +"$ perf report --stdio -n -g\n" +"\n" +"# Children Self Samples Command Shared Object Symbol\n" +"# ........ ........ ............ .......... .................. .....................................................................\n" +"#\n" +" 90.58% 0.36% 1 python.exe python.exe [.] " +"_start\n" +" |\n" +" ---_start\n" +" |\n" +" --89.86%--__libc_start_main\n" +" Py_BytesMain\n" +" |\n" +" |--55.43%--pymain_run_python.constprop.0\n" +" | |\n" +" | |--54.71%--_PyRun_AnyFileObject\n" +" | | _PyRun_SimpleFileObject\n" +" | | |\n" +" | | |--53.62%--run_mod\n" +" | | | |\n" +" | | | --53.26%--" +"PyEval_EvalCode\n" +" | | | py::" +":/src/script.py\n" +" | | | " +"_PyEval_EvalFrameDefault\n" +" | | | " +"PyObject_Vectorcall\n" +" | | | " +"_PyEval_Vector\n" +" | | | py::baz:/" +"src/script.py\n" +" | | | " +"_PyEval_EvalFrameDefault\n" +" | | | " +"PyObject_Vectorcall\n" +" | | | " +"_PyEval_Vector\n" +" | | | py::bar:/" +"src/script.py\n" +" | | | " +"_PyEval_EvalFrameDefault\n" +" | | | " +"PyObject_Vectorcall\n" +" | | | " +"_PyEval_Vector\n" +" | | | py::foo:/" +"src/script.py\n" +" | | | |\n" +" | | | " +"|--51.81%--_PyEval_EvalFrameDefault\n" +" | | | " +"| |\n" +" | | | " +"| |--13.77%--_PyLong_Add\n" +" | | | " +"| | |\n" +" | | | " +"| | |--3.26%--_PyObject_Malloc" +msgstr "" +"$ perf report --stdio -n -g\n" +"\n" +"# Children Self Samples Command Shared Object Symbol\n" +"# ........ ........ ............ .......... .................. .....................................................................\n" +"#\n" +" 90.58% 0.36% 1 python.exe python.exe [.] " +"_start\n" +" |\n" +" ---_start\n" +" |\n" +" --89.86%--__libc_start_main\n" +" Py_BytesMain\n" +" |\n" +" |--55.43%--pymain_run_python.constprop.0\n" +" | |\n" +" | |--54.71%--_PyRun_AnyFileObject\n" +" | | _PyRun_SimpleFileObject\n" +" | | |\n" +" | | |--53.62%--run_mod\n" +" | | | |\n" +" | | | --53.26%--" +"PyEval_EvalCode\n" +" | | | py::" +":/src/script.py\n" +" | | | " +"_PyEval_EvalFrameDefault\n" +" | | | " +"PyObject_Vectorcall\n" +" | | | " +"_PyEval_Vector\n" +" | | | py::baz:/" +"src/script.py\n" +" | | | " +"_PyEval_EvalFrameDefault\n" +" | | | " +"PyObject_Vectorcall\n" +" | | | " +"_PyEval_Vector\n" +" | | | py::bar:/" +"src/script.py\n" +" | | | " +"_PyEval_EvalFrameDefault\n" +" | | | " +"PyObject_Vectorcall\n" +" | | | " +"_PyEval_Vector\n" +" | | | py::foo:/" +"src/script.py\n" +" | | | |\n" +" | | | " +"|--51.81%--_PyEval_EvalFrameDefault\n" +" | | | " +"| |\n" +" | | | " +"| |--13.77%--_PyLong_Add\n" +" | | | " +"| | |\n" +" | | | " +"| | |--3.26%--_PyObject_Malloc" + +#: ../../howto/perf_profiling.rst:152 +msgid "How to enable ``perf`` profiling support" +msgstr "如何啟用 ``perf`` 分析支援" + +#: ../../howto/perf_profiling.rst:154 +msgid "" +"``perf`` profiling support can be enabled either from the start using the " +"environment variable :envvar:`PYTHONPERFSUPPORT` or the :option:`-X perf <-" +"X>` option, or dynamically using :func:`sys.activate_stack_trampoline` " +"and :func:`sys.deactivate_stack_trampoline`." +msgstr "" +"要啟用 ``perf`` 分析支援，可以在一開始就使用環境變" +"數 :envvar:`PYTHONPERFSUPPORT` 或使用 :option:`-X perf <-X>` 選項，也可以使" +"用 :func:`sys.activate_stack_trampoline` " +"和 :func:`sys.deactivate_stack_trampoline` 來動態啟用。" + +#: ../../howto/perf_profiling.rst:160 +msgid "" +"The :mod:`!sys` functions take precedence over the :option:`!-X` option, " +"the :option:`!-X` option takes precedence over the environment variable." +msgstr "" +":mod:`!sys` 函式優先於 :option:`!-X` 選項、:option:`!-X` 選項優先於環境變數。" + +#: ../../howto/perf_profiling.rst:163 +msgid "Example, using the environment variable::" +msgstr "例如，使用環境變數： ::" + +#: ../../howto/perf_profiling.rst:165 +msgid "" +"$ PYTHONPERFSUPPORT=1 perf record -F 9999 -g -o perf.data python " +"my_script.py\n" +"$ perf report -g -i perf.data" +msgstr "" +"$ PYTHONPERFSUPPORT=1 perf record -F 9999 -g -o perf.data python " +"my_script.py\n" +"$ perf report -g -i perf.data" + +#: ../../howto/perf_profiling.rst:168 +msgid "Example, using the :option:`!-X` option::" +msgstr "例如，使用 :option:`!-X` 選項： ::" + +#: ../../howto/perf_profiling.rst:170 +msgid "" +"$ perf record -F 9999 -g -o perf.data python -X perf my_script.py\n" +"$ perf report -g -i perf.data" +msgstr "" +"$ perf record -F 9999 -g -o perf.data python -X perf my_script.py\n" +"$ perf report -g -i perf.data" + +#: ../../howto/perf_profiling.rst:173 +msgid "Example, using the :mod:`sys` APIs in file :file:`example.py`:" +msgstr "例如，在 :file:`example.py` 檔案中使用 :mod:`sys` API：" + +#: ../../howto/perf_profiling.rst:175 +msgid "" +"import sys\n" +"\n" +"sys.activate_stack_trampoline(\"perf\")\n" +"do_profiled_stuff()\n" +"sys.deactivate_stack_trampoline()\n" +"\n" +"non_profiled_stuff()" +msgstr "" +"import sys\n" +"\n" +"sys.activate_stack_trampoline(\"perf\")\n" +"do_profiled_stuff()\n" +"sys.deactivate_stack_trampoline()\n" +"\n" +"non_profiled_stuff()" + +#: ../../howto/perf_profiling.rst:185 +msgid "...then::" +msgstr "...然後： ::" + +#: ../../howto/perf_profiling.rst:187 +msgid "" +"$ perf record -F 9999 -g -o perf.data python ./example.py\n" +"$ perf report -g -i perf.data" +msgstr "" +"$ perf record -F 9999 -g -o perf.data python ./example.py\n" +"$ perf report -g -i perf.data" + +#: ../../howto/perf_profiling.rst:192 +msgid "How to obtain the best results" +msgstr "如何獲得最佳結果" + +#: ../../howto/perf_profiling.rst:194 +msgid "" +"For best results, Python should be compiled with ``CFLAGS=\"-fno-omit-frame-" +"pointer -mno-omit-leaf-frame-pointer\"`` as this allows profilers to unwind " +"using only the frame pointer and not on DWARF debug information. This is " +"because as the code that is interposed to allow ``perf`` support is " +"dynamically generated it doesn't have any DWARF debugging information " +"available." +msgstr "" +"為了獲得最佳結果，應使用 ``CFLAGS=\"-fno-omit-frame-pointer -mno-omit-leaf-" +"frame-pointer\"`` 來進行 Python 編譯，因為這能允許分析器僅使用 frame 指標而不" +"是 DWARF 除錯資訊來解析 (unwind)。這是因為，由於插入以允許 ``perf`` 支援的程" +"式碼是動態生成的，因此它沒有任何可用的 DWARF 除錯資訊。" + +#: ../../howto/perf_profiling.rst:201 +msgid "" +"You can check if your system has been compiled with this flag by running::" +msgstr "你可以透過執行以下指令來檢查你的系統是否已使用此旗標進行編譯： ::" + +#: ../../howto/perf_profiling.rst:203 +msgid "$ python -m sysconfig | grep 'no-omit-frame-pointer'" +msgstr "$ python -m sysconfig | grep 'no-omit-frame-pointer'" + +#: ../../howto/perf_profiling.rst:205 +msgid "" +"If you don't see any output it means that your interpreter has not been " +"compiled with frame pointers and therefore it may not be able to show Python " +"functions in the output of ``perf``." +msgstr "" +"如果你沒有看到任何輸出，則表示你的直譯器尚未使用 frame 指標進行編譯，因此它可" +"能無法在 ``perf`` 的輸出中顯示 Python 函式。" + +#: ../../howto/perf_profiling.rst:211 +msgid "How to work without frame pointers" +msgstr "" + +#: ../../howto/perf_profiling.rst:213 +msgid "" +"If you are working with a Python interpreter that has been compiled without " +"frame pointers, you can still use the ``perf`` profiler, but the overhead " +"will be a bit higher because Python needs to generate unwinding information " +"for every Python function call on the fly. Additionally, ``perf`` will take " +"more time to process the data because it will need to use the DWARF " +"debugging information to unwind the stack and this is a slow process." +msgstr "" + +#: ../../howto/perf_profiling.rst:220 +msgid "" +"To enable this mode, you can use the environment " +"variable :envvar:`PYTHON_PERF_JIT_SUPPORT` or the :option:`-X perf_jit <-X>` " +"option, which will enable the JIT mode for the ``perf`` profiler." +msgstr "" + +#: ../../howto/perf_profiling.rst:226 +msgid "" +"Due to a bug in the ``perf`` tool, only ``perf`` versions higher than v6.8 " +"will work with the JIT mode. The fix was also backported to the v6.7.2 " +"version of the tool." +msgstr "" + +#: ../../howto/perf_profiling.rst:230 +msgid "" +"Note that when checking the version of the ``perf`` tool (which can be done " +"by running ``perf version``) you must take into account that some distros " +"add some custom version numbers including a ``-`` character. This means " +"that ``perf 6.7-3`` is not necessarily ``perf 6.7.3``." +msgstr "" + +#: ../../howto/perf_profiling.rst:235 +msgid "" +"When using the perf JIT mode, you need an extra step before you can run " +"``perf report``. You need to call the ``perf inject`` command to inject the " +"JIT information into the ``perf.data`` file.::" +msgstr "" + +#: ../../howto/perf_profiling.rst:239 +msgid "" +"$ perf record -F 9999 -g -k 1 --call-graph dwarf -o perf.data python " +"-Xperf_jit my_script.py\n" +"$ perf inject -i perf.data --jit --output perf.jit.data\n" +"$ perf report -g -i perf.jit.data" +msgstr "" +"$ perf record -F 9999 -g -k 1 --call-graph dwarf -o perf.data python " +"-Xperf_jit my_script.py\n" +"$ perf inject -i perf.data --jit --output perf.jit.data\n" +"$ perf report -g -i perf.jit.data" + +#: ../../howto/perf_profiling.rst:243 +msgid "or using the environment variable::" +msgstr "或使用環境變數： ::" + +#: ../../howto/perf_profiling.rst:245 +msgid "" +"$ PYTHON_PERF_JIT_SUPPORT=1 perf record -F 9999 -g --call-graph dwarf -o " +"perf.data python my_script.py\n" +"$ perf inject -i perf.data --jit --output perf.jit.data\n" +"$ perf report -g -i perf.jit.data" +msgstr "" +"$ PYTHON_PERF_JIT_SUPPORT=1 perf record -F 9999 -g --call-graph dwarf -o " +"perf.data python my_script.py\n" +"$ perf inject -i perf.data --jit --output perf.jit.data\n" +"$ perf report -g -i perf.jit.data" + +#: ../../howto/perf_profiling.rst:249 +msgid "" +"``perf inject --jit`` command will read ``perf.data``, automatically pick up " +"the perf dump file that Python creates (in ``/tmp/perf-$PID.dump``), and " +"then create ``perf.jit.data`` which merges all the JIT information together. " +"It should also create a lot of ``jitted-XXXX-N.so`` files in the current " +"directory which are ELF images for all the JIT trampolines that were created " +"by Python." +msgstr "" + +#: ../../howto/perf_profiling.rst:257 +msgid "" +"When using ``--call-graph dwarf``, the ``perf`` tool will take snapshots of " +"the stack of the process being profiled and save the information in the " +"``perf.data`` file. By default, the size of the stack dump is 8192 bytes, " +"but you can change the size by passing it after a comma like ``--call-graph " +"dwarf,16384``." +msgstr "" + +#: ../../howto/perf_profiling.rst:263 +msgid "" +"The size of the stack dump is important because if the size is too small " +"``perf`` will not be able to unwind the stack and the output will be " +"incomplete. On the other hand, if the size is too big, then ``perf`` won't " +"be able to sample the process as frequently as it would like as the overhead " +"will be higher." +msgstr "" + +#: ../../howto/perf_profiling.rst:269 +msgid "" +"The stack size is particularly important when profiling Python code compiled " +"with low optimization levels (like ``-O0``), as these builds tend to have " +"larger stack frames. If you are compiling Python with ``-O0`` and not seeing " +"Python functions in your profiling output, try increasing the stack dump " +"size to 65528 bytes (the maximum)::" +msgstr "" + +#: ../../howto/perf_profiling.rst:275 +msgid "" +"$ perf record -F 9999 -g -k 1 --call-graph dwarf,65528 -o perf.data python " +"-Xperf_jit my_script.py" +msgstr "" +"$ perf record -F 9999 -g -k 1 --call-graph dwarf,65528 -o perf.data python " +"-Xperf_jit my_script.py" + +#: ../../howto/perf_profiling.rst:277 +msgid "Different compilation flags can significantly impact stack sizes:" +msgstr "" + +#: ../../howto/perf_profiling.rst:279 +msgid "" +"Builds with ``-O0`` typically have much larger stack frames than those with " +"``-O1`` or higher" +msgstr "" + +#: ../../howto/perf_profiling.rst:280 +msgid "" +"Adding optimizations (``-O1``, ``-O2``, etc.) typically reduces stack size" +msgstr "" + +#: ../../howto/perf_profiling.rst:281 +msgid "" +"Frame pointers (``-fno-omit-frame-pointer``) generally provide more reliable " +"stack unwinding" +msgstr "" diff --git a/howto/pyporting.po b/howto/pyporting.po index 7220c627b3..196b10e286 100644 --- a/howto/pyporting.po +++ b/howto/pyporting.po @@ -1,85 +1,85 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# jerrychen , 2016 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-05-31 00:03+0000\n" -"PO-Revision-Date: 2018-05-23 14:37+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" - -#: ../../howto/pyporting.rst:7 -msgid "How to port Python 2 Code to Python 3" -msgstr "如何將 Python 2 的程式碼移植到 Python 3" - -#: ../../howto/pyporting.rst:0 -msgid "author" -msgstr "作者" - -#: ../../howto/pyporting.rst:9 -msgid "Brett Cannon" -msgstr "Brett Cannon" - -#: ../../howto/pyporting.rst:11 -msgid "" -"Python 2 reached its official end-of-life at the start of 2020. This means " -"that no new bug reports, fixes, or changes will be made to Python 2 - it's " -"no longer supported: see :pep:`373` and `status of Python versions `_." -msgstr "" - -#: ../../howto/pyporting.rst:16 -msgid "" -"If you are looking to port an extension module instead of pure Python code, " -"please see :ref:`cporting-howto`." -msgstr "" - -#: ../../howto/pyporting.rst:19 -msgid "" -"The archived python-porting_ mailing list may contain some useful guidance." -msgstr "" - -#: ../../howto/pyporting.rst:21 -msgid "" -"Since Python 3.11 the original porting guide was discontinued. You can find " -"the old guide in the `archive `_." -msgstr "" - -#: ../../howto/pyporting.rst:27 -msgid "Third-party guides" -msgstr "" - -#: ../../howto/pyporting.rst:29 -msgid "There are also multiple third-party guides that might be useful:" -msgstr "" - -#: ../../howto/pyporting.rst:31 -msgid "`Guide by Fedora `_" -msgstr "" - -#: ../../howto/pyporting.rst:32 -msgid "`PyCon 2020 tutorial `_" -msgstr "" - -#: ../../howto/pyporting.rst:33 -msgid "" -"`Guide by DigitalOcean `_" -msgstr "" - -#: ../../howto/pyporting.rst:34 -msgid "" -"`Guide by ActiveState `_" -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# jerrychen , 2016 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-05-31 00:03+0000\n" +"PO-Revision-Date: 2018-05-23 14:37+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" + +#: ../../howto/pyporting.rst:7 +msgid "How to port Python 2 Code to Python 3" +msgstr "如何將 Python 2 的程式碼移植到 Python 3" + +#: ../../howto/pyporting.rst:0 +msgid "author" +msgstr "作者" + +#: ../../howto/pyporting.rst:9 +msgid "Brett Cannon" +msgstr "Brett Cannon" + +#: ../../howto/pyporting.rst:11 +msgid "" +"Python 2 reached its official end-of-life at the start of 2020. This means " +"that no new bug reports, fixes, or changes will be made to Python 2 - it's " +"no longer supported: see :pep:`373` and `status of Python versions `_." +msgstr "" + +#: ../../howto/pyporting.rst:16 +msgid "" +"If you are looking to port an extension module instead of pure Python code, " +"please see :ref:`cporting-howto`." +msgstr "" + +#: ../../howto/pyporting.rst:19 +msgid "" +"The archived python-porting_ mailing list may contain some useful guidance." +msgstr "" + +#: ../../howto/pyporting.rst:21 +msgid "" +"Since Python 3.11 the original porting guide was discontinued. You can find " +"the old guide in the `archive `_." +msgstr "" + +#: ../../howto/pyporting.rst:27 +msgid "Third-party guides" +msgstr "" + +#: ../../howto/pyporting.rst:29 +msgid "There are also multiple third-party guides that might be useful:" +msgstr "" + +#: ../../howto/pyporting.rst:31 +msgid "`Guide by Fedora `_" +msgstr "" + +#: ../../howto/pyporting.rst:32 +msgid "`PyCon 2020 tutorial `_" +msgstr "" + +#: ../../howto/pyporting.rst:33 +msgid "" +"`Guide by DigitalOcean `_" +msgstr "" + +#: ../../howto/pyporting.rst:34 +msgid "" +"`Guide by ActiveState `_" +msgstr "" diff --git a/howto/regex.po b/howto/regex.po index 02a25aaf4d..47287e58c8 100644 --- a/howto/regex.po +++ b/howto/regex.po @@ -1,2474 +1,2474 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Albin Sun , 2015 -# Kai-han Chang , 2015 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-12-01 00:17+0000\n" -"PO-Revision-Date: 2018-05-23 14:37+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" - -#: ../../howto/regex.rst:5 -msgid "Regular Expression HOWTO" -msgstr "如何使用正規表示式" - -#: ../../howto/regex.rst:0 -msgid "Author" -msgstr "作者" - -#: ../../howto/regex.rst:7 -msgid "A.M. Kuchling " -msgstr "A.M. Kuchling " - -#: ../../howto/regex.rst:16 -msgid "Abstract" -msgstr "摘要" - -#: ../../howto/regex.rst:18 -msgid "" -"This document is an introductory tutorial to using regular expressions in " -"Python with the :mod:`re` module. It provides a gentler introduction than " -"the corresponding section in the Library Reference." -msgstr "" -"此文件為如何在 Python 中使用 :mod:`re` 模組來撰寫正規表示式的入門指導。進階使" -"用及參考文件請見函式庫參考一章。" - -#: ../../howto/regex.rst:24 -msgid "Introduction" -msgstr "簡介" - -#: ../../howto/regex.rst:26 -msgid "" -"Regular expressions (called REs, or regexes, or regex patterns) are " -"essentially a tiny, highly specialized programming language embedded inside " -"Python and made available through the :mod:`re` module. Using this little " -"language, you specify the rules for the set of possible strings that you " -"want to match; this set might contain English sentences, or e-mail " -"addresses, or TeX commands, or anything you like. You can then ask " -"questions such as \"Does this string match the pattern?\", or \"Is there a " -"match for the pattern anywhere in this string?\". You can also use REs to " -"modify a string or to split it apart in various ways." -msgstr "" -"正規表示式 (也稱為 REs、regexes 或 regex patterns) 是一個輕量且高專業化的程式" -"語言。在 Python 中可透過內建的 :mod:`re` 模組直接使用。你可以使用此輕量化的" -"語言針對想要匹配的一組字串撰寫規則，這組字串可能包含了英語句子、e-mail 地址、" -"TeX 命令或任何東西。你可以檢查如「這組字串是否匹配這個規則？」或「這組字串中" -"是否有任一處匹配這個規則？」。除此之外，你也可以使用 REs 來修改或是切割字串。" - -#: ../../howto/regex.rst:35 -msgid "" -"Regular expression patterns are compiled into a series of bytecodes which " -"are then executed by a matching engine written in C. For advanced use, it " -"may be necessary to pay careful attention to how the engine will execute a " -"given RE, and write the RE in a certain way in order to produce bytecode " -"that runs faster. Optimization isn't covered in this document, because it " -"requires that you have a good understanding of the matching engine's " -"internals." -msgstr "" - -#: ../../howto/regex.rst:42 -msgid "" -"The regular expression language is relatively small and restricted, so not " -"all possible string processing tasks can be done using regular expressions. " -"There are also tasks that *can* be done with regular expressions, but the " -"expressions turn out to be very complicated. In these cases, you may be " -"better off writing Python code to do the processing; while Python code will " -"be slower than an elaborate regular expression, it will also probably be " -"more understandable." -msgstr "" - -#: ../../howto/regex.rst:51 -msgid "Simple Patterns" -msgstr "" - -#: ../../howto/regex.rst:53 -msgid "" -"We'll start by learning about the simplest possible regular expressions. " -"Since regular expressions are used to operate on strings, we'll begin with " -"the most common task: matching characters." -msgstr "" - -#: ../../howto/regex.rst:57 -msgid "" -"For a detailed explanation of the computer science underlying regular " -"expressions (deterministic and non-deterministic finite automata), you can " -"refer to almost any textbook on writing compilers." -msgstr "" - -#: ../../howto/regex.rst:63 -msgid "Matching Characters" -msgstr "" - -#: ../../howto/regex.rst:65 -msgid "" -"Most letters and characters will simply match themselves. For example, the " -"regular expression ``test`` will match the string ``test`` exactly. (You " -"can enable a case-insensitive mode that would let this RE match ``Test`` or " -"``TEST`` as well; more about this later.)" -msgstr "" - -#: ../../howto/regex.rst:70 -msgid "" -"There are exceptions to this rule; some characters are special :dfn:" -"`metacharacters`, and don't match themselves. Instead, they signal that " -"some out-of-the-ordinary thing should be matched, or they affect other " -"portions of the RE by repeating them or changing their meaning. Much of " -"this document is devoted to discussing various metacharacters and what they " -"do." -msgstr "" - -#: ../../howto/regex.rst:76 -msgid "" -"Here's a complete list of the metacharacters; their meanings will be " -"discussed in the rest of this HOWTO." -msgstr "" - -#: ../../howto/regex.rst:79 -msgid ". ^ $ * + ? { } [ ] \\ | ( )" -msgstr ". ^ $ * + ? { } [ ] \\ | ( )" - -#: ../../howto/regex.rst:83 -msgid "" -"The first metacharacters we'll look at are ``[`` and ``]``. They're used for " -"specifying a character class, which is a set of characters that you wish to " -"match. Characters can be listed individually, or a range of characters can " -"be indicated by giving two characters and separating them by a ``'-'``. For " -"example, ``[abc]`` will match any of the characters ``a``, ``b``, or ``c``; " -"this is the same as ``[a-c]``, which uses a range to express the same set of " -"characters. If you wanted to match only lowercase letters, your RE would be " -"``[a-z]``." -msgstr "" - -#: ../../howto/regex.rst:92 -msgid "" -"Metacharacters (except ``\\``) are not active inside classes. For example, " -"``[akm$]`` will match any of the characters ``'a'``, ``'k'``, ``'m'``, or " -"``'$'``; ``'$'`` is usually a metacharacter, but inside a character class " -"it's stripped of its special nature." -msgstr "" - -#: ../../howto/regex.rst:97 -msgid "" -"You can match the characters not listed within the class by :dfn:" -"`complementing` the set. This is indicated by including a ``'^'`` as the " -"first character of the class. For example, ``[^5]`` will match any character " -"except ``'5'``. If the caret appears elsewhere in a character class, it " -"does not have special meaning. For example: ``[5^]`` will match either a " -"``'5'`` or a ``'^'``." -msgstr "" - -#: ../../howto/regex.rst:103 -msgid "" -"Perhaps the most important metacharacter is the backslash, ``\\``. As in " -"Python string literals, the backslash can be followed by various characters " -"to signal various special sequences. It's also used to escape all the " -"metacharacters so you can still match them in patterns; for example, if you " -"need to match a ``[`` or ``\\``, you can precede them with a backslash to " -"remove their special meaning: ``\\[`` or ``\\\\``." -msgstr "" - -#: ../../howto/regex.rst:110 -msgid "" -"Some of the special sequences beginning with ``'\\'`` represent predefined " -"sets of characters that are often useful, such as the set of digits, the set " -"of letters, or the set of anything that isn't whitespace." -msgstr "" - -#: ../../howto/regex.rst:115 -msgid "" -"Let's take an example: ``\\w`` matches any alphanumeric character. If the " -"regex pattern is expressed in bytes, this is equivalent to the class ``[a-zA-" -"Z0-9_]``. If the regex pattern is a string, ``\\w`` will match all the " -"characters marked as letters in the Unicode database provided by the :mod:" -"`unicodedata` module. You can use the more restricted definition of ``\\w`` " -"in a string pattern by supplying the :const:`re.ASCII` flag when compiling " -"the regular expression." -msgstr "" - -#: ../../howto/regex.rst:123 -msgid "" -"The following list of special sequences isn't complete. For a complete list " -"of sequences and expanded class definitions for Unicode string patterns, see " -"the last part of :ref:`Regular Expression Syntax ` in the " -"Standard Library reference. In general, the Unicode versions match any " -"character that's in the appropriate category in the Unicode database." -msgstr "" - -#: ../../howto/regex.rst:130 -msgid "``\\d``" -msgstr "``\\d``" - -#: ../../howto/regex.rst:131 -msgid "Matches any decimal digit; this is equivalent to the class ``[0-9]``." -msgstr "" - -#: ../../howto/regex.rst:133 -msgid "``\\D``" -msgstr "``\\D``" - -#: ../../howto/regex.rst:134 -msgid "" -"Matches any non-digit character; this is equivalent to the class ``[^0-9]``." -msgstr "" - -#: ../../howto/regex.rst:136 -msgid "``\\s``" -msgstr "``\\s``" - -#: ../../howto/regex.rst:137 -msgid "" -"Matches any whitespace character; this is equivalent to the class " -"``[ \\t\\n\\r\\f\\v]``." -msgstr "" - -#: ../../howto/regex.rst:140 -msgid "``\\S``" -msgstr "``\\S``" - -#: ../../howto/regex.rst:141 -msgid "" -"Matches any non-whitespace character; this is equivalent to the class ``[^ " -"\\t\\n\\r\\f\\v]``." -msgstr "" - -#: ../../howto/regex.rst:144 -msgid "``\\w``" -msgstr "``\\w``" - -#: ../../howto/regex.rst:145 -msgid "" -"Matches any alphanumeric character; this is equivalent to the class ``[a-zA-" -"Z0-9_]``." -msgstr "" - -#: ../../howto/regex.rst:148 -msgid "``\\W``" -msgstr "``\\W``" - -#: ../../howto/regex.rst:149 -msgid "" -"Matches any non-alphanumeric character; this is equivalent to the class " -"``[^a-zA-Z0-9_]``." -msgstr "" - -#: ../../howto/regex.rst:152 -msgid "" -"These sequences can be included inside a character class. For example, " -"``[\\s,.]`` is a character class that will match any whitespace character, " -"or ``','`` or ``'.'``." -msgstr "" - -#: ../../howto/regex.rst:156 -msgid "" -"The final metacharacter in this section is ``.``. It matches anything " -"except a newline character, and there's an alternate mode (:const:`re." -"DOTALL`) where it will match even a newline. ``.`` is often used where you " -"want to match \"any character\"." -msgstr "" - -#: ../../howto/regex.rst:163 -msgid "Repeating Things" -msgstr "" - -#: ../../howto/regex.rst:165 -msgid "" -"Being able to match varying sets of characters is the first thing regular " -"expressions can do that isn't already possible with the methods available on " -"strings. However, if that was the only additional capability of regexes, " -"they wouldn't be much of an advance. Another capability is that you can " -"specify that portions of the RE must be repeated a certain number of times." -msgstr "" - -#: ../../howto/regex.rst:171 -msgid "" -"The first metacharacter for repeating things that we'll look at is ``*``. " -"``*`` doesn't match the literal character ``'*'``; instead, it specifies " -"that the previous character can be matched zero or more times, instead of " -"exactly once." -msgstr "" - -#: ../../howto/regex.rst:175 -msgid "" -"For example, ``ca*t`` will match ``'ct'`` (0 ``'a'`` characters), ``'cat'`` " -"(1 ``'a'``), ``'caaat'`` (3 ``'a'`` characters), and so forth." -msgstr "" - -#: ../../howto/regex.rst:178 -msgid "" -"Repetitions such as ``*`` are :dfn:`greedy`; when repeating a RE, the " -"matching engine will try to repeat it as many times as possible. If later " -"portions of the pattern don't match, the matching engine will then back up " -"and try again with fewer repetitions." -msgstr "" - -#: ../../howto/regex.rst:183 -msgid "" -"A step-by-step example will make this more obvious. Let's consider the " -"expression ``a[bcd]*b``. This matches the letter ``'a'``, zero or more " -"letters from the class ``[bcd]``, and finally ends with a ``'b'``. Now " -"imagine matching this RE against the string ``'abcbd'``." -msgstr "" - -#: ../../howto/regex.rst:189 -msgid "Step" -msgstr "" - -#: ../../howto/regex.rst:189 -msgid "Matched" -msgstr "" - -#: ../../howto/regex.rst:189 -msgid "Explanation" -msgstr "" - -#: ../../howto/regex.rst:191 -msgid "1" -msgstr "1" - -#: ../../howto/regex.rst:191 -msgid "``a``" -msgstr "``a``" - -#: ../../howto/regex.rst:191 -msgid "The ``a`` in the RE matches." -msgstr "" - -#: ../../howto/regex.rst:193 -msgid "2" -msgstr "2" - -#: ../../howto/regex.rst:193 -msgid "``abcbd``" -msgstr "``abcbd``" - -#: ../../howto/regex.rst:193 -msgid "" -"The engine matches ``[bcd]*``, going as far as it can, which is to the end " -"of the string." -msgstr "" - -#: ../../howto/regex.rst:197 -msgid "3" -msgstr "3" - -#: ../../howto/regex.rst:197 ../../howto/regex.rst:205 -msgid "*Failure*" -msgstr "" - -#: ../../howto/regex.rst:197 -msgid "" -"The engine tries to match ``b``, but the current position is at the end of " -"the string, so it fails." -msgstr "" - -#: ../../howto/regex.rst:202 -msgid "4" -msgstr "4" - -#: ../../howto/regex.rst:202 ../../howto/regex.rst:213 -msgid "``abcb``" -msgstr "``abcb``" - -#: ../../howto/regex.rst:202 -msgid "Back up, so that ``[bcd]*`` matches one less character." -msgstr "" - -#: ../../howto/regex.rst:205 -msgid "5" -msgstr "5" - -#: ../../howto/regex.rst:205 -msgid "" -"Try ``b`` again, but the current position is at the last character, which is " -"a ``'d'``." -msgstr "" - -#: ../../howto/regex.rst:209 ../../howto/regex.rst:213 -msgid "6" -msgstr "6" - -#: ../../howto/regex.rst:209 -msgid "``abc``" -msgstr "``abc``" - -#: ../../howto/regex.rst:209 -msgid "Back up again, so that ``[bcd]*`` is only matching ``bc``." -msgstr "" - -#: ../../howto/regex.rst:213 -msgid "" -"Try ``b`` again. This time the character at the current position is " -"``'b'``, so it succeeds." -msgstr "" - -#: ../../howto/regex.rst:219 -msgid "" -"The end of the RE has now been reached, and it has matched ``'abcb'``. This " -"demonstrates how the matching engine goes as far as it can at first, and if " -"no match is found it will then progressively back up and retry the rest of " -"the RE again and again. It will back up until it has tried zero matches for " -"``[bcd]*``, and if that subsequently fails, the engine will conclude that " -"the string doesn't match the RE at all." -msgstr "" - -#: ../../howto/regex.rst:226 -msgid "" -"Another repeating metacharacter is ``+``, which matches one or more times. " -"Pay careful attention to the difference between ``*`` and ``+``; ``*`` " -"matches *zero* or more times, so whatever's being repeated may not be " -"present at all, while ``+`` requires at least *one* occurrence. To use a " -"similar example, ``ca+t`` will match ``'cat'`` (1 ``'a'``), ``'caaat'`` (3 " -"``'a'``\\ s), but won't match ``'ct'``." -msgstr "" - -#: ../../howto/regex.rst:233 -msgid "" -"There are two more repeating operators or quantifiers. The question mark " -"character, ``?``, matches either once or zero times; you can think of it as " -"marking something as being optional. For example, ``home-?brew`` matches " -"either ``'homebrew'`` or ``'home-brew'``." -msgstr "" - -#: ../../howto/regex.rst:238 -msgid "" -"The most complicated quantifier is ``{m,n}``, where *m* and *n* are decimal " -"integers. This quantifier means there must be at least *m* repetitions, and " -"at most *n*. For example, ``a/{1,3}b`` will match ``'a/b'``, ``'a//b'``, " -"and ``'a///b'``. It won't match ``'ab'``, which has no slashes, or ``'a////" -"b'``, which has four." -msgstr "" - -#: ../../howto/regex.rst:244 -msgid "" -"You can omit either *m* or *n*; in that case, a reasonable value is assumed " -"for the missing value. Omitting *m* is interpreted as a lower limit of 0, " -"while omitting *n* results in an upper bound of infinity." -msgstr "" - -#: ../../howto/regex.rst:248 -msgid "" -"The simplest case ``{m}`` matches the preceding item exactly *m* times. For " -"example, ``a/{2}b`` will only match ``'a//b'``." -msgstr "" - -#: ../../howto/regex.rst:251 -msgid "" -"Readers of a reductionist bent may notice that the three other quantifiers " -"can all be expressed using this notation. ``{0,}`` is the same as ``*``, " -"``{1,}`` is equivalent to ``+``, and ``{0,1}`` is the same as ``?``. It's " -"better to use ``*``, ``+``, or ``?`` when you can, simply because they're " -"shorter and easier to read." -msgstr "" - -#: ../../howto/regex.rst:259 -msgid "Using Regular Expressions" -msgstr "" - -#: ../../howto/regex.rst:261 -msgid "" -"Now that we've looked at some simple regular expressions, how do we actually " -"use them in Python? The :mod:`re` module provides an interface to the " -"regular expression engine, allowing you to compile REs into objects and then " -"perform matches with them." -msgstr "" - -#: ../../howto/regex.rst:268 -msgid "Compiling Regular Expressions" -msgstr "" - -#: ../../howto/regex.rst:270 -msgid "" -"Regular expressions are compiled into pattern objects, which have methods " -"for various operations such as searching for pattern matches or performing " -"string substitutions. ::" -msgstr "" - -#: ../../howto/regex.rst:274 -msgid "" -">>> import re\n" -">>> p = re.compile('ab*')\n" -">>> p\n" -"re.compile('ab*')" -msgstr "" -">>> import re\n" -">>> p = re.compile('ab*')\n" -">>> p\n" -"re.compile('ab*')" - -#: ../../howto/regex.rst:279 -msgid "" -":func:`re.compile` also accepts an optional *flags* argument, used to enable " -"various special features and syntax variations. We'll go over the available " -"settings later, but for now a single example will do::" -msgstr "" - -#: ../../howto/regex.rst:283 -msgid ">>> p = re.compile('ab*', re.IGNORECASE)" -msgstr ">>> p = re.compile('ab*', re.IGNORECASE)" - -#: ../../howto/regex.rst:285 -msgid "" -"The RE is passed to :func:`re.compile` as a string. REs are handled as " -"strings because regular expressions aren't part of the core Python language, " -"and no special syntax was created for expressing them. (There are " -"applications that don't need REs at all, so there's no need to bloat the " -"language specification by including them.) Instead, the :mod:`re` module is " -"simply a C extension module included with Python, just like the :mod:" -"`socket` or :mod:`zlib` modules." -msgstr "" - -#: ../../howto/regex.rst:292 -msgid "" -"Putting REs in strings keeps the Python language simpler, but has one " -"disadvantage which is the topic of the next section." -msgstr "" - -#: ../../howto/regex.rst:299 -msgid "The Backslash Plague" -msgstr "" - -#: ../../howto/regex.rst:301 -msgid "" -"As stated earlier, regular expressions use the backslash character " -"(``'\\'``) to indicate special forms or to allow special characters to be " -"used without invoking their special meaning. This conflicts with Python's " -"usage of the same character for the same purpose in string literals." -msgstr "" - -#: ../../howto/regex.rst:306 -msgid "" -"Let's say you want to write a RE that matches the string ``\\section``, " -"which might be found in a LaTeX file. To figure out what to write in the " -"program code, start with the desired string to be matched. Next, you must " -"escape any backslashes and other metacharacters by preceding them with a " -"backslash, resulting in the string ``\\\\section``. The resulting string " -"that must be passed to :func:`re.compile` must be ``\\\\section``. However, " -"to express this as a Python string literal, both backslashes must be escaped " -"*again*." -msgstr "" - -#: ../../howto/regex.rst:315 -msgid "Characters" -msgstr "" - -#: ../../howto/regex.rst:315 -msgid "Stage" -msgstr "" - -#: ../../howto/regex.rst:317 -msgid "``\\section``" -msgstr "``\\section``" - -#: ../../howto/regex.rst:317 -msgid "Text string to be matched" -msgstr "" - -#: ../../howto/regex.rst:319 -msgid "``\\\\section``" -msgstr "``\\\\section``" - -#: ../../howto/regex.rst:319 -msgid "Escaped backslash for :func:`re.compile`" -msgstr "" - -#: ../../howto/regex.rst:321 ../../howto/regex.rst:348 -msgid "``\"\\\\\\\\section\"``" -msgstr "``\"\\\\\\\\section\"``" - -#: ../../howto/regex.rst:321 -msgid "Escaped backslashes for a string literal" -msgstr "" - -#: ../../howto/regex.rst:324 -msgid "" -"In short, to match a literal backslash, one has to write ``'\\\\\\\\'`` as " -"the RE string, because the regular expression must be ``\\\\``, and each " -"backslash must be expressed as ``\\\\`` inside a regular Python string " -"literal. In REs that feature backslashes repeatedly, this leads to lots of " -"repeated backslashes and makes the resulting strings difficult to understand." -msgstr "" - -#: ../../howto/regex.rst:330 -msgid "" -"The solution is to use Python's raw string notation for regular expressions; " -"backslashes are not handled in any special way in a string literal prefixed " -"with ``'r'``, so ``r\"\\n\"`` is a two-character string containing ``'\\'`` " -"and ``'n'``, while ``\"\\n\"`` is a one-character string containing a " -"newline. Regular expressions will often be written in Python code using this " -"raw string notation." -msgstr "" - -#: ../../howto/regex.rst:336 -msgid "" -"In addition, special escape sequences that are valid in regular expressions, " -"but not valid as Python string literals, now result in a :exc:" -"`DeprecationWarning` and will eventually become a :exc:`SyntaxError`, which " -"means the sequences will be invalid if raw string notation or escaping the " -"backslashes isn't used." -msgstr "" - -#: ../../howto/regex.rst:344 -msgid "Regular String" -msgstr "" - -#: ../../howto/regex.rst:344 -msgid "Raw string" -msgstr "" - -#: ../../howto/regex.rst:346 -msgid "``\"ab*\"``" -msgstr "``\"ab*\"``" - -#: ../../howto/regex.rst:346 -msgid "``r\"ab*\"``" -msgstr "``r\"ab*\"``" - -#: ../../howto/regex.rst:348 -msgid "``r\"\\\\section\"``" -msgstr "``r\"\\\\section\"``" - -#: ../../howto/regex.rst:350 -msgid "``\"\\\\w+\\\\s+\\\\1\"``" -msgstr "``\"\\\\w+\\\\s+\\\\1\"``" - -#: ../../howto/regex.rst:350 -msgid "``r\"\\w+\\s+\\1\"``" -msgstr "``r\"\\w+\\s+\\1\"``" - -#: ../../howto/regex.rst:355 -msgid "Performing Matches" -msgstr "" - -#: ../../howto/regex.rst:357 -msgid "" -"Once you have an object representing a compiled regular expression, what do " -"you do with it? Pattern objects have several methods and attributes. Only " -"the most significant ones will be covered here; consult the :mod:`re` docs " -"for a complete listing." -msgstr "" - -#: ../../howto/regex.rst:363 ../../howto/regex.rst:417 -#: ../../howto/regex.rst:1072 -msgid "Method/Attribute" -msgstr "方法/屬性" - -#: ../../howto/regex.rst:363 ../../howto/regex.rst:417 -#: ../../howto/regex.rst:1072 -msgid "Purpose" -msgstr "" - -#: ../../howto/regex.rst:365 -msgid "``match()``" -msgstr "``match()``" - -#: ../../howto/regex.rst:365 -msgid "Determine if the RE matches at the beginning of the string." -msgstr "" - -#: ../../howto/regex.rst:368 -msgid "``search()``" -msgstr "``search()``" - -#: ../../howto/regex.rst:368 -msgid "Scan through a string, looking for any location where this RE matches." -msgstr "" - -#: ../../howto/regex.rst:371 -msgid "``findall()``" -msgstr "``findall()``" - -#: ../../howto/regex.rst:371 -msgid "Find all substrings where the RE matches, and returns them as a list." -msgstr "" - -#: ../../howto/regex.rst:374 -msgid "``finditer()``" -msgstr "``finditer()``" - -#: ../../howto/regex.rst:374 -msgid "" -"Find all substrings where the RE matches, and returns them as an :term:" -"`iterator`." -msgstr "" - -#: ../../howto/regex.rst:378 -msgid "" -":meth:`~re.Pattern.match` and :meth:`~re.Pattern.search` return ``None`` if " -"no match can be found. If they're successful, a :ref:`match object ` instance is returned, containing information about the match: " -"where it starts and ends, the substring it matched, and more." -msgstr "" - -#: ../../howto/regex.rst:383 -msgid "" -"You can learn about this by interactively experimenting with the :mod:`re` " -"module." -msgstr "" - -#: ../../howto/regex.rst:386 -msgid "" -"This HOWTO uses the standard Python interpreter for its examples. First, run " -"the Python interpreter, import the :mod:`re` module, and compile a RE::" -msgstr "" - -#: ../../howto/regex.rst:389 -msgid "" -">>> import re\n" -">>> p = re.compile('[a-z]+')\n" -">>> p\n" -"re.compile('[a-z]+')" -msgstr "" -">>> import re\n" -">>> p = re.compile('[a-z]+')\n" -">>> p\n" -"re.compile('[a-z]+')" - -#: ../../howto/regex.rst:394 -msgid "" -"Now, you can try matching various strings against the RE ``[a-z]+``. An " -"empty string shouldn't match at all, since ``+`` means 'one or more " -"repetitions'. :meth:`~re.Pattern.match` should return ``None`` in this case, " -"which will cause the interpreter to print no output. You can explicitly " -"print the result of :meth:`!match` to make this clear. ::" -msgstr "" - -#: ../../howto/regex.rst:400 -msgid "" -">>> p.match(\"\")\n" -">>> print(p.match(\"\"))\n" -"None" -msgstr "" -">>> p.match(\"\")\n" -">>> print(p.match(\"\"))\n" -"None" - -#: ../../howto/regex.rst:404 -msgid "" -"Now, let's try it on a string that it should match, such as ``tempo``. In " -"this case, :meth:`~re.Pattern.match` will return a :ref:`match object `, so you should store the result in a variable for later use. ::" -msgstr "" - -#: ../../howto/regex.rst:408 -msgid "" -">>> m = p.match('tempo')\n" -">>> m\n" -"" -msgstr "" -">>> m = p.match('tempo')\n" -">>> m\n" -"" - -#: ../../howto/regex.rst:412 -msgid "" -"Now you can query the :ref:`match object ` for information " -"about the matching string. Match object instances also have several methods " -"and attributes; the most important ones are:" -msgstr "" - -#: ../../howto/regex.rst:419 -msgid "``group()``" -msgstr "``group()``" - -#: ../../howto/regex.rst:419 -msgid "Return the string matched by the RE" -msgstr "" - -#: ../../howto/regex.rst:421 -msgid "``start()``" -msgstr "``start()``" - -#: ../../howto/regex.rst:421 -msgid "Return the starting position of the match" -msgstr "" - -#: ../../howto/regex.rst:423 -msgid "``end()``" -msgstr "``end()``" - -#: ../../howto/regex.rst:423 -msgid "Return the ending position of the match" -msgstr "" - -#: ../../howto/regex.rst:425 -msgid "``span()``" -msgstr "``span()``" - -#: ../../howto/regex.rst:425 -msgid "Return a tuple containing the (start, end) positions of the match" -msgstr "" - -#: ../../howto/regex.rst:429 -msgid "Trying these methods will soon clarify their meaning::" -msgstr "" - -#: ../../howto/regex.rst:431 -msgid "" -">>> m.group()\n" -"'tempo'\n" -">>> m.start(), m.end()\n" -"(0, 5)\n" -">>> m.span()\n" -"(0, 5)" -msgstr "" -">>> m.group()\n" -"'tempo'\n" -">>> m.start(), m.end()\n" -"(0, 5)\n" -">>> m.span()\n" -"(0, 5)" - -#: ../../howto/regex.rst:438 -msgid "" -":meth:`~re.Match.group` returns the substring that was matched by the RE. :" -"meth:`~re.Match.start` and :meth:`~re.Match.end` return the starting and " -"ending index of the match. :meth:`~re.Match.span` returns both start and end " -"indexes in a single tuple. Since the :meth:`~re.Pattern.match` method only " -"checks if the RE matches at the start of a string, :meth:`!start` will " -"always be zero. However, the :meth:`~re.Pattern.search` method of patterns " -"scans through the string, so the match may not start at zero in that " -"case. ::" -msgstr "" - -#: ../../howto/regex.rst:446 -msgid "" -">>> print(p.match('::: message'))\n" -"None\n" -">>> m = p.search('::: message'); print(m)\n" -"\n" -">>> m.group()\n" -"'message'\n" -">>> m.span()\n" -"(4, 11)" -msgstr "" -">>> print(p.match('::: message'))\n" -"None\n" -">>> m = p.search('::: message'); print(m)\n" -"\n" -">>> m.group()\n" -"'message'\n" -">>> m.span()\n" -"(4, 11)" - -#: ../../howto/regex.rst:455 -msgid "" -"In actual programs, the most common style is to store the :ref:`match object " -"` in a variable, and then check if it was ``None``. This " -"usually looks like::" -msgstr "" - -#: ../../howto/regex.rst:459 -msgid "" -"p = re.compile( ... )\n" -"m = p.match( 'string goes here' )\n" -"if m:\n" -" print('Match found: ', m.group())\n" -"else:\n" -" print('No match')" -msgstr "" -"p = re.compile( ... )\n" -"m = p.match( 'string goes here' )\n" -"if m:\n" -" print('Match found: ', m.group())\n" -"else:\n" -" print('No match')" - -#: ../../howto/regex.rst:466 -msgid "" -"Two pattern methods return all of the matches for a pattern. :meth:`~re." -"Pattern.findall` returns a list of matching strings::" -msgstr "" - -#: ../../howto/regex.rst:469 -msgid "" -">>> p = re.compile(r'\\d+')\n" -">>> p.findall('12 drummers drumming, 11 pipers piping, 10 lords a-leaping')\n" -"['12', '11', '10']" -msgstr "" -">>> p = re.compile(r'\\d+')\n" -">>> p.findall('12 drummers drumming, 11 pipers piping, 10 lords a-leaping')\n" -"['12', '11', '10']" - -#: ../../howto/regex.rst:473 -msgid "" -"The ``r`` prefix, making the literal a raw string literal, is needed in this " -"example because escape sequences in a normal \"cooked\" string literal that " -"are not recognized by Python, as opposed to regular expressions, now result " -"in a :exc:`DeprecationWarning` and will eventually become a :exc:" -"`SyntaxError`. See :ref:`the-backslash-plague`." -msgstr "" - -#: ../../howto/regex.rst:479 -msgid "" -":meth:`~re.Pattern.findall` has to create the entire list before it can be " -"returned as the result. The :meth:`~re.Pattern.finditer` method returns a " -"sequence of :ref:`match object ` instances as an :term:" -"`iterator`::" -msgstr "" - -#: ../../howto/regex.rst:483 -msgid "" -">>> iterator = p.finditer('12 drummers drumming, 11 ... 10 ...')\n" -">>> iterator\n" -"\n" -">>> for match in iterator:\n" -"... print(match.span())\n" -"...\n" -"(0, 2)\n" -"(22, 24)\n" -"(29, 31)" -msgstr "" -">>> iterator = p.finditer('12 drummers drumming, 11 ... 10 ...')\n" -">>> iterator\n" -"\n" -">>> for match in iterator:\n" -"... print(match.span())\n" -"...\n" -"(0, 2)\n" -"(22, 24)\n" -"(29, 31)" - -#: ../../howto/regex.rst:495 -msgid "Module-Level Functions" -msgstr "模組層級函式" - -#: ../../howto/regex.rst:497 -msgid "" -"You don't have to create a pattern object and call its methods; the :mod:" -"`re` module also provides top-level functions called :func:`~re.match`, :" -"func:`~re.search`, :func:`~re.findall`, :func:`~re.sub`, and so forth. " -"These functions take the same arguments as the corresponding pattern method " -"with the RE string added as the first argument, and still return either " -"``None`` or a :ref:`match object ` instance. ::" -msgstr "" - -#: ../../howto/regex.rst:504 -msgid "" -">>> print(re.match(r'From\\s+', 'Fromage amk'))\n" -"None\n" -">>> re.match(r'From\\s+', 'From amk Thu May 14 19:12:10 1998')\n" -"" -msgstr "" -">>> print(re.match(r'From\\s+', 'Fromage amk'))\n" -"None\n" -">>> re.match(r'From\\s+', 'From amk Thu May 14 19:12:10 1998')\n" -"" - -#: ../../howto/regex.rst:509 -msgid "" -"Under the hood, these functions simply create a pattern object for you and " -"call the appropriate method on it. They also store the compiled object in a " -"cache, so future calls using the same RE won't need to parse the pattern " -"again and again." -msgstr "" - -#: ../../howto/regex.rst:514 -msgid "" -"Should you use these module-level functions, or should you get the pattern " -"and call its methods yourself? If you're accessing a regex within a loop, " -"pre-compiling it will save a few function calls. Outside of loops, there's " -"not much difference thanks to the internal cache." -msgstr "" - -#: ../../howto/regex.rst:522 -msgid "Compilation Flags" -msgstr "" - -#: ../../howto/regex.rst:526 -msgid "" -"Compilation flags let you modify some aspects of how regular expressions " -"work. Flags are available in the :mod:`re` module under two names, a long " -"name such as :const:`IGNORECASE` and a short, one-letter form such as :const:" -"`I`. (If you're familiar with Perl's pattern modifiers, the one-letter " -"forms use the same letters; the short form of :const:`re.VERBOSE` is :const:" -"`re.X`, for example.) Multiple flags can be specified by bitwise OR-ing " -"them; ``re.I | re.M`` sets both the :const:`I` and :const:`M` flags, for " -"example." -msgstr "" - -#: ../../howto/regex.rst:534 -msgid "" -"Here's a table of the available flags, followed by a more detailed " -"explanation of each one." -msgstr "" - -#: ../../howto/regex.rst:538 -msgid "Flag" -msgstr "旗標" - -#: ../../howto/regex.rst:538 -msgid "Meaning" -msgstr "含義" - -#: ../../howto/regex.rst:540 -msgid ":const:`ASCII`, :const:`A`" -msgstr ":const:`ASCII`, :const:`A`" - -#: ../../howto/regex.rst:540 -msgid "" -"Makes several escapes like ``\\w``, ``\\b``, ``\\s`` and ``\\d`` match only " -"on ASCII characters with the respective property." -msgstr "" - -#: ../../howto/regex.rst:544 -msgid ":const:`DOTALL`, :const:`S`" -msgstr ":const:`DOTALL`, :const:`S`" - -#: ../../howto/regex.rst:544 -msgid "Make ``.`` match any character, including newlines." -msgstr "" - -#: ../../howto/regex.rst:547 -msgid ":const:`IGNORECASE`, :const:`I`" -msgstr ":const:`IGNORECASE`, :const:`I`" - -#: ../../howto/regex.rst:547 -msgid "Do case-insensitive matches." -msgstr "" - -#: ../../howto/regex.rst:549 -msgid ":const:`LOCALE`, :const:`L`" -msgstr ":const:`LOCALE`, :const:`L`" - -#: ../../howto/regex.rst:549 -msgid "Do a locale-aware match." -msgstr "" - -#: ../../howto/regex.rst:551 -msgid ":const:`MULTILINE`, :const:`M`" -msgstr ":const:`MULTILINE`, :const:`M`" - -#: ../../howto/regex.rst:551 -msgid "Multi-line matching, affecting ``^`` and ``$``." -msgstr "" - -#: ../../howto/regex.rst:554 -msgid ":const:`VERBOSE`, :const:`X` (for 'extended')" -msgstr "" - -#: ../../howto/regex.rst:554 -msgid "" -"Enable verbose REs, which can be organized more cleanly and understandably." -msgstr "" - -#: ../../howto/regex.rst:563 -msgid "" -"Perform case-insensitive matching; character class and literal strings will " -"match letters by ignoring case. For example, ``[A-Z]`` will match lowercase " -"letters, too. Full Unicode matching also works unless the :const:`ASCII` " -"flag is used to disable non-ASCII matches. When the Unicode patterns ``[a-" -"z]`` or ``[A-Z]`` are used in combination with the :const:`IGNORECASE` flag, " -"they will match the 52 ASCII letters and 4 additional non-ASCII letters: " -"'İ' (U+0130, Latin capital letter I with dot above), 'ı' (U+0131, Latin " -"small letter dotless i), 'ſ' (U+017F, Latin small letter long s) and " -"'K' (U+212A, Kelvin sign). ``Spam`` will match ``'Spam'``, ``'spam'``, " -"``'spAM'``, or ``'ſpam'`` (the latter is matched only in Unicode mode). This " -"lowercasing doesn't take the current locale into account; it will if you " -"also set the :const:`LOCALE` flag." -msgstr "" - -#: ../../howto/regex.rst:581 -msgid "" -"Make ``\\w``, ``\\W``, ``\\b``, ``\\B`` and case-insensitive matching " -"dependent on the current locale instead of the Unicode database." -msgstr "" - -#: ../../howto/regex.rst:584 -msgid "" -"Locales are a feature of the C library intended to help in writing programs " -"that take account of language differences. For example, if you're " -"processing encoded French text, you'd want to be able to write ``\\w+`` to " -"match words, but ``\\w`` only matches the character class ``[A-Za-z]`` in " -"bytes patterns; it won't match bytes corresponding to ``é`` or ``ç``. If " -"your system is configured properly and a French locale is selected, certain " -"C functions will tell the program that the byte corresponding to ``é`` " -"should also be considered a letter. Setting the :const:`LOCALE` flag when " -"compiling a regular expression will cause the resulting compiled object to " -"use these C functions for ``\\w``; this is slower, but also enables ``\\w+`` " -"to match French words as you'd expect. The use of this flag is discouraged " -"in Python 3 as the locale mechanism is very unreliable, it only handles one " -"\"culture\" at a time, and it only works with 8-bit locales. Unicode " -"matching is already enabled by default in Python 3 for Unicode (str) " -"patterns, and it is able to handle different locales/languages." -msgstr "" - -#: ../../howto/regex.rst:606 -msgid "" -"(``^`` and ``$`` haven't been explained yet; they'll be introduced in " -"section :ref:`more-metacharacters`.)" -msgstr "" - -#: ../../howto/regex.rst:609 -msgid "" -"Usually ``^`` matches only at the beginning of the string, and ``$`` matches " -"only at the end of the string and immediately before the newline (if any) at " -"the end of the string. When this flag is specified, ``^`` matches at the " -"beginning of the string and at the beginning of each line within the string, " -"immediately following each newline. Similarly, the ``$`` metacharacter " -"matches either at the end of the string and at the end of each line " -"(immediately preceding each newline)." -msgstr "" - -#: ../../howto/regex.rst:622 -msgid "" -"Makes the ``'.'`` special character match any character at all, including a " -"newline; without this flag, ``'.'`` will match anything *except* a newline." -msgstr "" - -#: ../../howto/regex.rst:630 -msgid "" -"Make ``\\w``, ``\\W``, ``\\b``, ``\\B``, ``\\s`` and ``\\S`` perform ASCII-" -"only matching instead of full Unicode matching. This is only meaningful for " -"Unicode patterns, and is ignored for byte patterns." -msgstr "" - -#: ../../howto/regex.rst:639 -msgid "" -"This flag allows you to write regular expressions that are more readable by " -"granting you more flexibility in how you can format them. When this flag " -"has been specified, whitespace within the RE string is ignored, except when " -"the whitespace is in a character class or preceded by an unescaped " -"backslash; this lets you organize and indent the RE more clearly. This flag " -"also lets you put comments within a RE that will be ignored by the engine; " -"comments are marked by a ``'#'`` that's neither in a character class or " -"preceded by an unescaped backslash." -msgstr "" - -#: ../../howto/regex.rst:648 -msgid "" -"For example, here's a RE that uses :const:`re.VERBOSE`; see how much easier " -"it is to read? ::" -msgstr "" - -#: ../../howto/regex.rst:651 -msgid "" -"charref = re.compile(r\"\"\"\n" -" &[#] # Start of a numeric entity reference\n" -" (\n" -" 0[0-7]+ # Octal form\n" -" | [0-9]+ # Decimal form\n" -" | x[0-9a-fA-F]+ # Hexadecimal form\n" -" )\n" -" ; # Trailing semicolon\n" -"\"\"\", re.VERBOSE)" -msgstr "" - -#: ../../howto/regex.rst:661 -msgid "Without the verbose setting, the RE would look like this::" -msgstr "" - -#: ../../howto/regex.rst:663 -msgid "" -"charref = re.compile(\"&#(0[0-7]+\"\n" -" \"|[0-9]+\"\n" -" \"|x[0-9a-fA-F]+);\")" -msgstr "" -"charref = re.compile(\"&#(0[0-7]+\"\n" -" \"|[0-9]+\"\n" -" \"|x[0-9a-fA-F]+);\")" - -#: ../../howto/regex.rst:667 -msgid "" -"In the above example, Python's automatic concatenation of string literals " -"has been used to break up the RE into smaller pieces, but it's still more " -"difficult to understand than the version using :const:`re.VERBOSE`." -msgstr "" - -#: ../../howto/regex.rst:673 -msgid "More Pattern Power" -msgstr "" - -#: ../../howto/regex.rst:675 -msgid "" -"So far we've only covered a part of the features of regular expressions. In " -"this section, we'll cover some new metacharacters, and how to use groups to " -"retrieve portions of the text that was matched." -msgstr "" - -#: ../../howto/regex.rst:683 -msgid "More Metacharacters" -msgstr "" - -#: ../../howto/regex.rst:685 -msgid "" -"There are some metacharacters that we haven't covered yet. Most of them " -"will be covered in this section." -msgstr "" - -#: ../../howto/regex.rst:688 -msgid "" -"Some of the remaining metacharacters to be discussed are :dfn:`zero-width " -"assertions`. They don't cause the engine to advance through the string; " -"instead, they consume no characters at all, and simply succeed or fail. For " -"example, ``\\b`` is an assertion that the current position is located at a " -"word boundary; the position isn't changed by the ``\\b`` at all. This means " -"that zero-width assertions should never be repeated, because if they match " -"once at a given location, they can obviously be matched an infinite number " -"of times." -msgstr "" - -#: ../../howto/regex.rst:696 -msgid "``|``" -msgstr "``|``" - -#: ../../howto/regex.rst:697 -msgid "" -"Alternation, or the \"or\" operator. If *A* and *B* are regular " -"expressions, ``A|B`` will match any string that matches either *A* or *B*. " -"``|`` has very low precedence in order to make it work reasonably when " -"you're alternating multi-character strings. ``Crow|Servo`` will match either " -"``'Crow'`` or ``'Servo'``, not ``'Cro'``, a ``'w'`` or an ``'S'``, and " -"``'ervo'``." -msgstr "" - -#: ../../howto/regex.rst:703 -msgid "" -"To match a literal ``'|'``, use ``\\|``, or enclose it inside a character " -"class, as in ``[|]``." -msgstr "" - -#: ../../howto/regex.rst:706 -msgid "``^``" -msgstr "``^``" - -#: ../../howto/regex.rst:707 -msgid "" -"Matches at the beginning of lines. Unless the :const:`MULTILINE` flag has " -"been set, this will only match at the beginning of the string. In :const:" -"`MULTILINE` mode, this also matches immediately after each newline within " -"the string." -msgstr "" - -#: ../../howto/regex.rst:711 -msgid "" -"For example, if you wish to match the word ``From`` only at the beginning of " -"a line, the RE to use is ``^From``. ::" -msgstr "" - -#: ../../howto/regex.rst:714 -msgid "" -">>> print(re.search('^From', 'From Here to Eternity'))\n" -"\n" -">>> print(re.search('^From', 'Reciting From Memory'))\n" -"None" -msgstr "" -">>> print(re.search('^From', 'From Here to Eternity'))\n" -"\n" -">>> print(re.search('^From', 'Reciting From Memory'))\n" -"None" - -#: ../../howto/regex.rst:719 -msgid "To match a literal ``'^'``, use ``\\^``." -msgstr "" - -#: ../../howto/regex.rst:721 -msgid "``$``" -msgstr "``$``" - -#: ../../howto/regex.rst:722 -msgid "" -"Matches at the end of a line, which is defined as either the end of the " -"string, or any location followed by a newline character. ::" -msgstr "" - -#: ../../howto/regex.rst:725 -msgid "" -">>> print(re.search('}$', '{block}'))\n" -"\n" -">>> print(re.search('}$', '{block} '))\n" -"None\n" -">>> print(re.search('}$', '{block}\\n'))\n" -"" -msgstr "" -">>> print(re.search('}$', '{block}'))\n" -"\n" -">>> print(re.search('}$', '{block} '))\n" -"None\n" -">>> print(re.search('}$', '{block}\\n'))\n" -"" - -#: ../../howto/regex.rst:732 -msgid "" -"To match a literal ``'$'``, use ``\\$`` or enclose it inside a character " -"class, as in ``[$]``." -msgstr "" - -#: ../../howto/regex.rst:735 -msgid "``\\A``" -msgstr "``\\A``" - -#: ../../howto/regex.rst:736 -msgid "" -"Matches only at the start of the string. When not in :const:`MULTILINE` " -"mode, ``\\A`` and ``^`` are effectively the same. In :const:`MULTILINE` " -"mode, they're different: ``\\A`` still matches only at the beginning of the " -"string, but ``^`` may match at any location inside the string that follows a " -"newline character." -msgstr "" - -#: ../../howto/regex.rst:741 -msgid "``\\z``" -msgstr "``\\z``" - -#: ../../howto/regex.rst:742 -msgid "Matches only at the end of the string." -msgstr "" - -#: ../../howto/regex.rst:744 -msgid "``\\Z``" -msgstr "``\\Z``" - -#: ../../howto/regex.rst:745 -msgid "The same as ``\\z``. For compatibility with old Python versions." -msgstr "" - -#: ../../howto/regex.rst:747 -msgid "``\\b``" -msgstr "``\\b``" - -#: ../../howto/regex.rst:748 -msgid "" -"Word boundary. This is a zero-width assertion that matches only at the " -"beginning or end of a word. A word is defined as a sequence of alphanumeric " -"characters, so the end of a word is indicated by whitespace or a non-" -"alphanumeric character." -msgstr "" - -#: ../../howto/regex.rst:753 -msgid "" -"The following example matches ``class`` only when it's a complete word; it " -"won't match when it's contained inside another word. ::" -msgstr "" - -#: ../../howto/regex.rst:756 -msgid "" -">>> p = re.compile(r'\\bclass\\b')\n" -">>> print(p.search('no class at all'))\n" -"\n" -">>> print(p.search('the declassified algorithm'))\n" -"None\n" -">>> print(p.search('one subclass is'))\n" -"None" -msgstr "" -">>> p = re.compile(r'\\bclass\\b')\n" -">>> print(p.search('no class at all'))\n" -"\n" -">>> print(p.search('the declassified algorithm'))\n" -"None\n" -">>> print(p.search('one subclass is'))\n" -"None" - -#: ../../howto/regex.rst:764 -msgid "" -"There are two subtleties you should remember when using this special " -"sequence. First, this is the worst collision between Python's string " -"literals and regular expression sequences. In Python's string literals, " -"``\\b`` is the backspace character, ASCII value 8. If you're not using raw " -"strings, then Python will convert the ``\\b`` to a backspace, and your RE " -"won't match as you expect it to. The following example looks the same as our " -"previous RE, but omits the ``'r'`` in front of the RE string. ::" -msgstr "" - -#: ../../howto/regex.rst:772 -msgid "" -">>> p = re.compile('\\bclass\\b')\n" -">>> print(p.search('no class at all'))\n" -"None\n" -">>> print(p.search('\\b' + 'class' + '\\b'))\n" -"" -msgstr "" -">>> p = re.compile('\\bclass\\b')\n" -">>> print(p.search('no class at all'))\n" -"None\n" -">>> print(p.search('\\b' + 'class' + '\\b'))\n" -"" - -#: ../../howto/regex.rst:778 -msgid "" -"Second, inside a character class, where there's no use for this assertion, " -"``\\b`` represents the backspace character, for compatibility with Python's " -"string literals." -msgstr "" - -#: ../../howto/regex.rst:782 -msgid "``\\B``" -msgstr "``\\B``" - -#: ../../howto/regex.rst:783 -msgid "" -"Another zero-width assertion, this is the opposite of ``\\b``, only matching " -"when the current position is not at a word boundary." -msgstr "" - -#: ../../howto/regex.rst:788 -msgid "Grouping" -msgstr "" - -#: ../../howto/regex.rst:790 -msgid "" -"Frequently you need to obtain more information than just whether the RE " -"matched or not. Regular expressions are often used to dissect strings by " -"writing a RE divided into several subgroups which match different components " -"of interest. For example, an RFC-822 header line is divided into a header " -"name and a value, separated by a ``':'``, like this:" -msgstr "" - -#: ../../howto/regex.rst:796 -msgid "" -"From: author@example.com\n" -"User-Agent: Thunderbird 1.5.0.9 (X11/20061227)\n" -"MIME-Version: 1.0\n" -"To: editor@example.com" -msgstr "" -"From: author@example.com\n" -"User-Agent: Thunderbird 1.5.0.9 (X11/20061227)\n" -"MIME-Version: 1.0\n" -"To: editor@example.com" - -#: ../../howto/regex.rst:803 -msgid "" -"This can be handled by writing a regular expression which matches an entire " -"header line, and has one group which matches the header name, and another " -"group which matches the header's value." -msgstr "" - -#: ../../howto/regex.rst:807 -msgid "" -"Groups are marked by the ``'('``, ``')'`` metacharacters. ``'('`` and " -"``')'`` have much the same meaning as they do in mathematical expressions; " -"they group together the expressions contained inside them, and you can " -"repeat the contents of a group with a quantifier, such as ``*``, ``+``, ``?" -"``, or ``{m,n}``. For example, ``(ab)*`` will match zero or more " -"repetitions of ``ab``. ::" -msgstr "" - -#: ../../howto/regex.rst:814 -msgid "" -">>> p = re.compile('(ab)*')\n" -">>> print(p.match('ababababab').span())\n" -"(0, 10)" -msgstr "" -">>> p = re.compile('(ab)*')\n" -">>> print(p.match('ababababab').span())\n" -"(0, 10)" - -#: ../../howto/regex.rst:818 -msgid "" -"Groups indicated with ``'('``, ``')'`` also capture the starting and ending " -"index of the text that they match; this can be retrieved by passing an " -"argument to :meth:`~re.Match.group`, :meth:`~re.Match.start`, :meth:`~re." -"Match.end`, and :meth:`~re.Match.span`. Groups are numbered starting with " -"0. Group 0 is always present; it's the whole RE, so :ref:`match object " -"` methods all have group 0 as their default argument. Later " -"we'll see how to express groups that don't capture the span of text that " -"they match. ::" -msgstr "" - -#: ../../howto/regex.rst:827 -msgid "" -">>> p = re.compile('(a)b')\n" -">>> m = p.match('ab')\n" -">>> m.group()\n" -"'ab'\n" -">>> m.group(0)\n" -"'ab'" -msgstr "" -">>> p = re.compile('(a)b')\n" -">>> m = p.match('ab')\n" -">>> m.group()\n" -"'ab'\n" -">>> m.group(0)\n" -"'ab'" - -#: ../../howto/regex.rst:834 -msgid "" -"Subgroups are numbered from left to right, from 1 upward. Groups can be " -"nested; to determine the number, just count the opening parenthesis " -"characters, going from left to right. ::" -msgstr "" - -#: ../../howto/regex.rst:838 -msgid "" -">>> p = re.compile('(a(b)c)d')\n" -">>> m = p.match('abcd')\n" -">>> m.group(0)\n" -"'abcd'\n" -">>> m.group(1)\n" -"'abc'\n" -">>> m.group(2)\n" -"'b'" -msgstr "" -">>> p = re.compile('(a(b)c)d')\n" -">>> m = p.match('abcd')\n" -">>> m.group(0)\n" -"'abcd'\n" -">>> m.group(1)\n" -"'abc'\n" -">>> m.group(2)\n" -"'b'" - -#: ../../howto/regex.rst:847 -msgid "" -":meth:`~re.Match.group` can be passed multiple group numbers at a time, in " -"which case it will return a tuple containing the corresponding values for " -"those groups. ::" -msgstr "" - -#: ../../howto/regex.rst:850 -msgid "" -">>> m.group(2,1,2)\n" -"('b', 'abc', 'b')" -msgstr "" -">>> m.group(2,1,2)\n" -"('b', 'abc', 'b')" - -#: ../../howto/regex.rst:853 -msgid "" -"The :meth:`~re.Match.groups` method returns a tuple containing the strings " -"for all the subgroups, from 1 up to however many there are. ::" -msgstr "" - -#: ../../howto/regex.rst:856 -msgid "" -">>> m.groups()\n" -"('abc', 'b')" -msgstr "" -">>> m.groups()\n" -"('abc', 'b')" - -#: ../../howto/regex.rst:859 -msgid "" -"Backreferences in a pattern allow you to specify that the contents of an " -"earlier capturing group must also be found at the current location in the " -"string. For example, ``\\1`` will succeed if the exact contents of group 1 " -"can be found at the current position, and fails otherwise. Remember that " -"Python's string literals also use a backslash followed by numbers to allow " -"including arbitrary characters in a string, so be sure to use a raw string " -"when incorporating backreferences in a RE." -msgstr "" - -#: ../../howto/regex.rst:867 -msgid "For example, the following RE detects doubled words in a string. ::" -msgstr "" - -#: ../../howto/regex.rst:869 -msgid "" -">>> p = re.compile(r'\\b(\\w+)\\s+\\1\\b')\n" -">>> p.search('Paris in the the spring').group()\n" -"'the the'" -msgstr "" -">>> p = re.compile(r'\\b(\\w+)\\s+\\1\\b')\n" -">>> p.search('Paris in the the spring').group()\n" -"'the the'" - -#: ../../howto/regex.rst:873 -msgid "" -"Backreferences like this aren't often useful for just searching through a " -"string --- there are few text formats which repeat data in this way --- but " -"you'll soon find out that they're *very* useful when performing string " -"substitutions." -msgstr "" - -#: ../../howto/regex.rst:879 -msgid "Non-capturing and Named Groups" -msgstr "" - -#: ../../howto/regex.rst:881 -msgid "" -"Elaborate REs may use many groups, both to capture substrings of interest, " -"and to group and structure the RE itself. In complex REs, it becomes " -"difficult to keep track of the group numbers. There are two features which " -"help with this problem. Both of them use a common syntax for regular " -"expression extensions, so we'll look at that first." -msgstr "" - -#: ../../howto/regex.rst:887 -msgid "" -"Perl 5 is well known for its powerful additions to standard regular " -"expressions. For these new features the Perl developers couldn't choose new " -"single-keystroke metacharacters or new special sequences beginning with " -"``\\`` without making Perl's regular expressions confusingly different from " -"standard REs. If they chose ``&`` as a new metacharacter, for example, old " -"expressions would be assuming that ``&`` was a regular character and " -"wouldn't have escaped it by writing ``\\&`` or ``[&]``." -msgstr "" - -#: ../../howto/regex.rst:894 -msgid "" -"The solution chosen by the Perl developers was to use ``(?...)`` as the " -"extension syntax. ``?`` immediately after a parenthesis was a syntax error " -"because the ``?`` would have nothing to repeat, so this didn't introduce any " -"compatibility problems. The characters immediately after the ``?`` " -"indicate what extension is being used, so ``(?=foo)`` is one thing (a " -"positive lookahead assertion) and ``(?:foo)`` is something else (a non-" -"capturing group containing the subexpression ``foo``)." -msgstr "" - -#: ../../howto/regex.rst:902 -msgid "" -"Python supports several of Perl's extensions and adds an extension syntax to " -"Perl's extension syntax. If the first character after the question mark is " -"a ``P``, you know that it's an extension that's specific to Python." -msgstr "" - -#: ../../howto/regex.rst:907 -msgid "" -"Now that we've looked at the general extension syntax, we can return to the " -"features that simplify working with groups in complex REs." -msgstr "" - -#: ../../howto/regex.rst:910 -msgid "" -"Sometimes you'll want to use a group to denote a part of a regular " -"expression, but aren't interested in retrieving the group's contents. You " -"can make this fact explicit by using a non-capturing group: ``(?:...)``, " -"where you can replace the ``...`` with any other regular expression. ::" -msgstr "" - -#: ../../howto/regex.rst:915 -msgid "" -">>> m = re.match(\"([abc])+\", \"abc\")\n" -">>> m.groups()\n" -"('c',)\n" -">>> m = re.match(\"(?:[abc])+\", \"abc\")\n" -">>> m.groups()\n" -"()" -msgstr "" -">>> m = re.match(\"([abc])+\", \"abc\")\n" -">>> m.groups()\n" -"('c',)\n" -">>> m = re.match(\"(?:[abc])+\", \"abc\")\n" -">>> m.groups()\n" -"()" - -#: ../../howto/regex.rst:922 -msgid "" -"Except for the fact that you can't retrieve the contents of what the group " -"matched, a non-capturing group behaves exactly the same as a capturing " -"group; you can put anything inside it, repeat it with a repetition " -"metacharacter such as ``*``, and nest it within other groups (capturing or " -"non-capturing). ``(?:...)`` is particularly useful when modifying an " -"existing pattern, since you can add new groups without changing how all the " -"other groups are numbered. It should be mentioned that there's no " -"performance difference in searching between capturing and non-capturing " -"groups; neither form is any faster than the other." -msgstr "" - -#: ../../howto/regex.rst:931 -msgid "" -"A more significant feature is named groups: instead of referring to them by " -"numbers, groups can be referenced by a name." -msgstr "" - -#: ../../howto/regex.rst:934 -msgid "" -"The syntax for a named group is one of the Python-specific extensions: ``(?" -"P...)``. *name* is, obviously, the name of the group. Named groups " -"behave exactly like capturing groups, and additionally associate a name with " -"a group. The :ref:`match object ` methods that deal with " -"capturing groups all accept either integers that refer to the group by " -"number or strings that contain the desired group's name. Named groups are " -"still given numbers, so you can retrieve information about a group in two " -"ways::" -msgstr "" - -#: ../../howto/regex.rst:942 -msgid "" -">>> p = re.compile(r'(?P\\b\\w+\\b)')\n" -">>> m = p.search( '(((( Lots of punctuation )))' )\n" -">>> m.group('word')\n" -"'Lots'\n" -">>> m.group(1)\n" -"'Lots'" -msgstr "" -">>> p = re.compile(r'(?P\\b\\w+\\b)')\n" -">>> m = p.search( '(((( Lots of punctuation )))' )\n" -">>> m.group('word')\n" -"'Lots'\n" -">>> m.group(1)\n" -"'Lots'" - -#: ../../howto/regex.rst:949 -msgid "" -"Additionally, you can retrieve named groups as a dictionary with :meth:`~re." -"Match.groupdict`::" -msgstr "" - -#: ../../howto/regex.rst:952 -msgid "" -">>> m = re.match(r'(?P\\w+) (?P\\w+)', 'Jane Doe')\n" -">>> m.groupdict()\n" -"{'first': 'Jane', 'last': 'Doe'}" -msgstr "" -">>> m = re.match(r'(?P\\w+) (?P\\w+)', 'Jane Doe')\n" -">>> m.groupdict()\n" -"{'first': 'Jane', 'last': 'Doe'}" - -#: ../../howto/regex.rst:956 -msgid "" -"Named groups are handy because they let you use easily remembered names, " -"instead of having to remember numbers. Here's an example RE from the :mod:" -"`imaplib` module::" -msgstr "" - -#: ../../howto/regex.rst:960 -msgid "" -"InternalDate = re.compile(r'INTERNALDATE \"'\n" -" r'(?P[ 123][0-9])-(?P[A-Z][a-z][a-z])-'\n" -" r'(?P[0-9][0-9][0-9][0-9])'\n" -" r' (?P[0-9][0-9]):(?P[0-9][0-9]):(?P[0-9][0-9])'\n" -" r' (?P[-+])(?P[0-9][0-9])(?P[0-9][0-9])'\n" -" r'\"')" -msgstr "" -"InternalDate = re.compile(r'INTERNALDATE \"'\n" -" r'(?P[ 123][0-9])-(?P[A-Z][a-z][a-z])-'\n" -" r'(?P[0-9][0-9][0-9][0-9])'\n" -" r' (?P[0-9][0-9]):(?P[0-9][0-9]):(?P[0-9][0-9])'\n" -" r' (?P[-+])(?P[0-9][0-9])(?P[0-9][0-9])'\n" -" r'\"')" - -#: ../../howto/regex.rst:967 -msgid "" -"It's obviously much easier to retrieve ``m.group('zonem')``, instead of " -"having to remember to retrieve group 9." -msgstr "" - -#: ../../howto/regex.rst:970 -msgid "" -"The syntax for backreferences in an expression such as ``(...)\\1`` refers " -"to the number of the group. There's naturally a variant that uses the group " -"name instead of the number. This is another Python extension: ``(?P=name)`` " -"indicates that the contents of the group called *name* should again be " -"matched at the current point. The regular expression for finding doubled " -"words, ``\\b(\\w+)\\s+\\1\\b`` can also be written as ``\\b(?" -"P\\w+)\\s+(?P=word)\\b``::" -msgstr "" - -#: ../../howto/regex.rst:977 -msgid "" -">>> p = re.compile(r'\\b(?P\\w+)\\s+(?P=word)\\b')\n" -">>> p.search('Paris in the the spring').group()\n" -"'the the'" -msgstr "" -">>> p = re.compile(r'\\b(?P\\w+)\\s+(?P=word)\\b')\n" -">>> p.search('Paris in the the spring').group()\n" -"'the the'" - -#: ../../howto/regex.rst:983 -msgid "Lookahead Assertions" -msgstr "" - -#: ../../howto/regex.rst:985 -msgid "" -"Another zero-width assertion is the lookahead assertion. Lookahead " -"assertions are available in both positive and negative form, and look like " -"this:" -msgstr "" - -#: ../../howto/regex.rst:988 -msgid "``(?=...)``" -msgstr "``(?=...)``" - -#: ../../howto/regex.rst:989 -msgid "" -"Positive lookahead assertion. This succeeds if the contained regular " -"expression, represented here by ``...``, successfully matches at the current " -"location, and fails otherwise. But, once the contained expression has been " -"tried, the matching engine doesn't advance at all; the rest of the pattern " -"is tried right where the assertion started." -msgstr "" - -#: ../../howto/regex.rst:995 -msgid "``(?!...)``" -msgstr "``(?!...)``" - -#: ../../howto/regex.rst:996 -msgid "" -"Negative lookahead assertion. This is the opposite of the positive " -"assertion; it succeeds if the contained expression *doesn't* match at the " -"current position in the string." -msgstr "" - -#: ../../howto/regex.rst:1000 -msgid "" -"To make this concrete, let's look at a case where a lookahead is useful. " -"Consider a simple pattern to match a filename and split it apart into a base " -"name and an extension, separated by a ``.``. For example, in ``news.rc``, " -"``news`` is the base name, and ``rc`` is the filename's extension." -msgstr "" - -#: ../../howto/regex.rst:1005 -msgid "The pattern to match this is quite simple:" -msgstr "" - -#: ../../howto/regex.rst:1007 -msgid "``.*[.].*$``" -msgstr "``.*[.].*$``" - -#: ../../howto/regex.rst:1009 -msgid "" -"Notice that the ``.`` needs to be treated specially because it's a " -"metacharacter, so it's inside a character class to only match that specific " -"character. Also notice the trailing ``$``; this is added to ensure that all " -"the rest of the string must be included in the extension. This regular " -"expression matches ``foo.bar`` and ``autoexec.bat`` and ``sendmail.cf`` and " -"``printers.conf``." -msgstr "" - -#: ../../howto/regex.rst:1016 -msgid "" -"Now, consider complicating the problem a bit; what if you want to match " -"filenames where the extension is not ``bat``? Some incorrect attempts:" -msgstr "" - -#: ../../howto/regex.rst:1019 -msgid "``.*[.][^b].*$``" -msgstr "``.*[.][^b].*$``" - -#: ../../howto/regex.rst:1021 -msgid "" -"The first attempt above tries to exclude ``bat`` by requiring that the first " -"character of the extension is not a ``b``. This is wrong, because the " -"pattern also doesn't match ``foo.bar``." -msgstr "" - -#: ../../howto/regex.rst:1025 -msgid "``.*[.]([^b]..|.[^a].|..[^t])$``" -msgstr "``.*[.]([^b]..|.[^a].|..[^t])$``" - -#: ../../howto/regex.rst:1027 -msgid "" -"The expression gets messier when you try to patch up the first solution by " -"requiring one of the following cases to match: the first character of the " -"extension isn't ``b``; the second character isn't ``a``; or the third " -"character isn't ``t``. This accepts ``foo.bar`` and rejects ``autoexec." -"bat``, but it requires a three-letter extension and won't accept a filename " -"with a two-letter extension such as ``sendmail.cf``. We'll complicate the " -"pattern again in an effort to fix it." -msgstr "" - -#: ../../howto/regex.rst:1035 -msgid "``.*[.]([^b].?.?|.[^a]?.?|..?[^t]?)$``" -msgstr "``.*[.]([^b].?.?|.[^a]?.?|..?[^t]?)$``" - -#: ../../howto/regex.rst:1037 -msgid "" -"In the third attempt, the second and third letters are all made optional in " -"order to allow matching extensions shorter than three characters, such as " -"``sendmail.cf``." -msgstr "" - -#: ../../howto/regex.rst:1041 -msgid "" -"The pattern's getting really complicated now, which makes it hard to read " -"and understand. Worse, if the problem changes and you want to exclude both " -"``bat`` and ``exe`` as extensions, the pattern would get even more " -"complicated and confusing." -msgstr "" - -#: ../../howto/regex.rst:1046 -msgid "A negative lookahead cuts through all this confusion:" -msgstr "" - -#: ../../howto/regex.rst:1048 -msgid "``.*[.](?!bat$)[^.]*$``" -msgstr "``.*[.](?!bat$)[^.]*$``" - -#: ../../howto/regex.rst:1050 -msgid "" -"The negative lookahead means: if the expression ``bat`` doesn't match at " -"this point, try the rest of the pattern; if ``bat$`` does match, the whole " -"pattern will fail. The trailing ``$`` is required to ensure that something " -"like ``sample.batch``, where the extension only starts with ``bat``, will be " -"allowed. The ``[^.]*`` makes sure that the pattern works when there are " -"multiple dots in the filename." -msgstr "" - -#: ../../howto/regex.rst:1057 -msgid "" -"Excluding another filename extension is now easy; simply add it as an " -"alternative inside the assertion. The following pattern excludes filenames " -"that end in either ``bat`` or ``exe``:" -msgstr "" - -#: ../../howto/regex.rst:1061 -msgid "``.*[.](?!bat$|exe$)[^.]*$``" -msgstr "``.*[.](?!bat$|exe$)[^.]*$``" - -#: ../../howto/regex.rst:1065 -msgid "Modifying Strings" -msgstr "" - -#: ../../howto/regex.rst:1067 -msgid "" -"Up to this point, we've simply performed searches against a static string. " -"Regular expressions are also commonly used to modify strings in various " -"ways, using the following pattern methods:" -msgstr "" - -#: ../../howto/regex.rst:1074 -msgid "``split()``" -msgstr "``split()``" - -#: ../../howto/regex.rst:1074 -msgid "Split the string into a list, splitting it wherever the RE matches" -msgstr "" - -#: ../../howto/regex.rst:1077 -msgid "``sub()``" -msgstr "``sub()``" - -#: ../../howto/regex.rst:1077 -msgid "" -"Find all substrings where the RE matches, and replace them with a different " -"string" -msgstr "" - -#: ../../howto/regex.rst:1080 -msgid "``subn()``" -msgstr "``subn()``" - -#: ../../howto/regex.rst:1080 -msgid "" -"Does the same thing as :meth:`!sub`, but returns the new string and the " -"number of replacements" -msgstr "" - -#: ../../howto/regex.rst:1087 -msgid "Splitting Strings" -msgstr "" - -#: ../../howto/regex.rst:1089 -msgid "" -"The :meth:`~re.Pattern.split` method of a pattern splits a string apart " -"wherever the RE matches, returning a list of the pieces. It's similar to " -"the :meth:`~str.split` method of strings but provides much more generality " -"in the delimiters that you can split by; string :meth:`!split` only supports " -"splitting by whitespace or by a fixed string. As you'd expect, there's a " -"module-level :func:`re.split` function, too." -msgstr "" - -#: ../../howto/regex.rst:1100 -msgid "" -"Split *string* by the matches of the regular expression. If capturing " -"parentheses are used in the RE, then their contents will also be returned as " -"part of the resulting list. If *maxsplit* is nonzero, at most *maxsplit* " -"splits are performed." -msgstr "" - -#: ../../howto/regex.rst:1105 -msgid "" -"You can limit the number of splits made, by passing a value for *maxsplit*. " -"When *maxsplit* is nonzero, at most *maxsplit* splits will be made, and the " -"remainder of the string is returned as the final element of the list. In " -"the following example, the delimiter is any sequence of non-alphanumeric " -"characters. ::" -msgstr "" - -#: ../../howto/regex.rst:1111 -msgid "" -">>> p = re.compile(r'\\W+')\n" -">>> p.split('This is a test, short and sweet, of split().')\n" -"['This', 'is', 'a', 'test', 'short', 'and', 'sweet', 'of', 'split', '']\n" -">>> p.split('This is a test, short and sweet, of split().', 3)\n" -"['This', 'is', 'a', 'test, short and sweet, of split().']" -msgstr "" -">>> p = re.compile(r'\\W+')\n" -">>> p.split('This is a test, short and sweet, of split().')\n" -"['This', 'is', 'a', 'test', 'short', 'and', 'sweet', 'of', 'split', '']\n" -">>> p.split('This is a test, short and sweet, of split().', 3)\n" -"['This', 'is', 'a', 'test, short and sweet, of split().']" - -#: ../../howto/regex.rst:1117 -msgid "" -"Sometimes you're not only interested in what the text between delimiters is, " -"but also need to know what the delimiter was. If capturing parentheses are " -"used in the RE, then their values are also returned as part of the list. " -"Compare the following calls::" -msgstr "" - -#: ../../howto/regex.rst:1122 -msgid "" -">>> p = re.compile(r'\\W+')\n" -">>> p2 = re.compile(r'(\\W+)')\n" -">>> p.split('This... is a test.')\n" -"['This', 'is', 'a', 'test', '']\n" -">>> p2.split('This... is a test.')\n" -"['This', '... ', 'is', ' ', 'a', ' ', 'test', '.', '']" -msgstr "" -">>> p = re.compile(r'\\W+')\n" -">>> p2 = re.compile(r'(\\W+)')\n" -">>> p.split('This... is a test.')\n" -"['This', 'is', 'a', 'test', '']\n" -">>> p2.split('This... is a test.')\n" -"['This', '... ', 'is', ' ', 'a', ' ', 'test', '.', '']" - -#: ../../howto/regex.rst:1129 -msgid "" -"The module-level function :func:`re.split` adds the RE to be used as the " -"first argument, but is otherwise the same. ::" -msgstr "" - -#: ../../howto/regex.rst:1132 -msgid "" -">>> re.split(r'[\\W]+', 'Words, words, words.')\n" -"['Words', 'words', 'words', '']\n" -">>> re.split(r'([\\W]+)', 'Words, words, words.')\n" -"['Words', ', ', 'words', ', ', 'words', '.', '']\n" -">>> re.split(r'[\\W]+', 'Words, words, words.', 1)\n" -"['Words', 'words, words.']" -msgstr "" -">>> re.split(r'[\\W]+', 'Words, words, words.')\n" -"['Words', 'words', 'words', '']\n" -">>> re.split(r'([\\W]+)', 'Words, words, words.')\n" -"['Words', ', ', 'words', ', ', 'words', '.', '']\n" -">>> re.split(r'[\\W]+', 'Words, words, words.', 1)\n" -"['Words', 'words, words.']" - -#: ../../howto/regex.rst:1141 -msgid "Search and Replace" -msgstr "" - -#: ../../howto/regex.rst:1143 -msgid "" -"Another common task is to find all the matches for a pattern, and replace " -"them with a different string. The :meth:`~re.Pattern.sub` method takes a " -"replacement value, which can be either a string or a function, and the " -"string to be processed." -msgstr "" - -#: ../../howto/regex.rst:1150 -msgid "" -"Returns the string obtained by replacing the leftmost non-overlapping " -"occurrences of the RE in *string* by the replacement *replacement*. If the " -"pattern isn't found, *string* is returned unchanged." -msgstr "" - -#: ../../howto/regex.rst:1154 -msgid "" -"The optional argument *count* is the maximum number of pattern occurrences " -"to be replaced; *count* must be a non-negative integer. The default value " -"of 0 means to replace all occurrences." -msgstr "" - -#: ../../howto/regex.rst:1158 -msgid "" -"Here's a simple example of using the :meth:`~re.Pattern.sub` method. It " -"replaces colour names with the word ``colour``::" -msgstr "" - -#: ../../howto/regex.rst:1161 -msgid "" -">>> p = re.compile('(blue|white|red)')\n" -">>> p.sub('colour', 'blue socks and red shoes')\n" -"'colour socks and colour shoes'\n" -">>> p.sub('colour', 'blue socks and red shoes', count=1)\n" -"'colour socks and red shoes'" -msgstr "" -">>> p = re.compile('(blue|white|red)')\n" -">>> p.sub('colour', 'blue socks and red shoes')\n" -"'colour socks and colour shoes'\n" -">>> p.sub('colour', 'blue socks and red shoes', count=1)\n" -"'colour socks and red shoes'" - -#: ../../howto/regex.rst:1167 -msgid "" -"The :meth:`~re.Pattern.subn` method does the same work, but returns a 2-" -"tuple containing the new string value and the number of replacements that " -"were performed::" -msgstr "" - -#: ../../howto/regex.rst:1170 -msgid "" -">>> p = re.compile('(blue|white|red)')\n" -">>> p.subn('colour', 'blue socks and red shoes')\n" -"('colour socks and colour shoes', 2)\n" -">>> p.subn('colour', 'no colours at all')\n" -"('no colours at all', 0)" -msgstr "" -">>> p = re.compile('(blue|white|red)')\n" -">>> p.subn('colour', 'blue socks and red shoes')\n" -"('colour socks and colour shoes', 2)\n" -">>> p.subn('colour', 'no colours at all')\n" -"('no colours at all', 0)" - -#: ../../howto/regex.rst:1176 -msgid "" -"Empty matches are replaced only when they're not adjacent to a previous " -"empty match. ::" -msgstr "" - -#: ../../howto/regex.rst:1179 -msgid "" -">>> p = re.compile('x*')\n" -">>> p.sub('-', 'abxd')\n" -"'-a-b--d-'" -msgstr "" -">>> p = re.compile('x*')\n" -">>> p.sub('-', 'abxd')\n" -"'-a-b--d-'" - -#: ../../howto/regex.rst:1183 -msgid "" -"If *replacement* is a string, any backslash escapes in it are processed. " -"That is, ``\\n`` is converted to a single newline character, ``\\r`` is " -"converted to a carriage return, and so forth. Unknown escapes such as " -"``\\&`` are left alone. Backreferences, such as ``\\6``, are replaced with " -"the substring matched by the corresponding group in the RE. This lets you " -"incorporate portions of the original text in the resulting replacement " -"string." -msgstr "" - -#: ../../howto/regex.rst:1190 -msgid "" -"This example matches the word ``section`` followed by a string enclosed in " -"``{``, ``}``, and changes ``section`` to ``subsection``::" -msgstr "" - -#: ../../howto/regex.rst:1193 -msgid "" -">>> p = re.compile('section{ ( [^}]* ) }', re.VERBOSE)\n" -">>> p.sub(r'subsection{\\1}','section{First} section{second}')\n" -"'subsection{First} subsection{second}'" -msgstr "" -">>> p = re.compile('section{ ( [^}]* ) }', re.VERBOSE)\n" -">>> p.sub(r'subsection{\\1}','section{First} section{second}')\n" -"'subsection{First} subsection{second}'" - -#: ../../howto/regex.rst:1197 -msgid "" -"There's also a syntax for referring to named groups as defined by the ``(?" -"P...)`` syntax. ``\\g`` will use the substring matched by the " -"group named ``name``, and ``\\g`` uses the corresponding group " -"number. ``\\g<2>`` is therefore equivalent to ``\\2``, but isn't ambiguous " -"in a replacement string such as ``\\g<2>0``. (``\\20`` would be interpreted " -"as a reference to group 20, not a reference to group 2 followed by the " -"literal character ``'0'``.) The following substitutions are all equivalent, " -"but use all three variations of the replacement string. ::" -msgstr "" - -#: ../../howto/regex.rst:1206 -msgid "" -">>> p = re.compile('section{ (?P [^}]* ) }', re.VERBOSE)\n" -">>> p.sub(r'subsection{\\1}','section{First}')\n" -"'subsection{First}'\n" -">>> p.sub(r'subsection{\\g<1>}','section{First}')\n" -"'subsection{First}'\n" -">>> p.sub(r'subsection{\\g}','section{First}')\n" -"'subsection{First}'" -msgstr "" -">>> p = re.compile('section{ (?P [^}]* ) }', re.VERBOSE)\n" -">>> p.sub(r'subsection{\\1}','section{First}')\n" -"'subsection{First}'\n" -">>> p.sub(r'subsection{\\g<1>}','section{First}')\n" -"'subsection{First}'\n" -">>> p.sub(r'subsection{\\g}','section{First}')\n" -"'subsection{First}'" - -#: ../../howto/regex.rst:1214 -msgid "" -"*replacement* can also be a function, which gives you even more control. If " -"*replacement* is a function, the function is called for every non-" -"overlapping occurrence of *pattern*. On each call, the function is passed " -"a :ref:`match object ` argument for the match and can use " -"this information to compute the desired replacement string and return it." -msgstr "" - -#: ../../howto/regex.rst:1220 -msgid "" -"In the following example, the replacement function translates decimals into " -"hexadecimal::" -msgstr "" - -#: ../../howto/regex.rst:1223 -msgid "" -">>> def hexrepl(match):\n" -"... \"Return the hex string for a decimal number\"\n" -"... value = int(match.group())\n" -"... return hex(value)\n" -"...\n" -">>> p = re.compile(r'\\d+')\n" -">>> p.sub(hexrepl, 'Call 65490 for printing, 49152 for user code.')\n" -"'Call 0xffd2 for printing, 0xc000 for user code.'" -msgstr "" - -#: ../../howto/regex.rst:1232 -msgid "" -"When using the module-level :func:`re.sub` function, the pattern is passed " -"as the first argument. The pattern may be provided as an object or as a " -"string; if you need to specify regular expression flags, you must either use " -"a pattern object as the first parameter, or use embedded modifiers in the " -"pattern string, e.g. ``sub(\"(?i)b+\", \"x\", \"bbbb BBBB\")`` returns ``'x " -"x'``." -msgstr "" - -#: ../../howto/regex.rst:1240 -msgid "Common Problems" -msgstr "" - -#: ../../howto/regex.rst:1242 -msgid "" -"Regular expressions are a powerful tool for some applications, but in some " -"ways their behaviour isn't intuitive and at times they don't behave the way " -"you may expect them to. This section will point out some of the most common " -"pitfalls." -msgstr "" - -#: ../../howto/regex.rst:1248 -msgid "Use String Methods" -msgstr "" - -#: ../../howto/regex.rst:1250 -msgid "" -"Sometimes using the :mod:`re` module is a mistake. If you're matching a " -"fixed string, or a single character class, and you're not using any :mod:" -"`re` features such as the :const:`~re.IGNORECASE` flag, then the full power " -"of regular expressions may not be required. Strings have several methods for " -"performing operations with fixed strings and they're usually much faster, " -"because the implementation is a single small C loop that's been optimized " -"for the purpose, instead of the large, more generalized regular expression " -"engine." -msgstr "" - -#: ../../howto/regex.rst:1258 -msgid "" -"One example might be replacing a single fixed string with another one; for " -"example, you might replace ``word`` with ``deed``. :func:`re.sub` seems " -"like the function to use for this, but consider the :meth:`~str.replace` " -"method. Note that :meth:`!replace` will also replace ``word`` inside words, " -"turning ``swordfish`` into ``sdeedfish``, but the naive RE ``word`` would " -"have done that, too. (To avoid performing the substitution on parts of " -"words, the pattern would have to be ``\\bword\\b``, in order to require that " -"``word`` have a word boundary on either side. This takes the job beyond :" -"meth:`!replace`'s abilities.)" -msgstr "" - -#: ../../howto/regex.rst:1267 -msgid "" -"Another common task is deleting every occurrence of a single character from " -"a string or replacing it with another single character. You might do this " -"with something like ``re.sub('\\n', ' ', S)``, but :meth:`~str.translate` is " -"capable of doing both tasks and will be faster than any regular expression " -"operation can be." -msgstr "" - -#: ../../howto/regex.rst:1273 -msgid "" -"In short, before turning to the :mod:`re` module, consider whether your " -"problem can be solved with a faster and simpler string method." -msgstr "" - -#: ../../howto/regex.rst:1278 -msgid "match() versus search()" -msgstr "" - -#: ../../howto/regex.rst:1280 -msgid "" -"The :func:`~re.match` function only checks if the RE matches at the " -"beginning of the string while :func:`~re.search` will scan forward through " -"the string for a match. It's important to keep this distinction in mind. " -"Remember, :func:`!match` will only report a successful match which will " -"start at 0; if the match wouldn't start at zero, :func:`!match` will *not* " -"report it. ::" -msgstr "" - -#: ../../howto/regex.rst:1286 -msgid "" -">>> print(re.match('super', 'superstition').span())\n" -"(0, 5)\n" -">>> print(re.match('super', 'insuperable'))\n" -"None" -msgstr "" -">>> print(re.match('super', 'superstition').span())\n" -"(0, 5)\n" -">>> print(re.match('super', 'insuperable'))\n" -"None" - -#: ../../howto/regex.rst:1291 -msgid "" -"On the other hand, :func:`~re.search` will scan forward through the string, " -"reporting the first match it finds. ::" -msgstr "" - -#: ../../howto/regex.rst:1294 -msgid "" -">>> print(re.search('super', 'superstition').span())\n" -"(0, 5)\n" -">>> print(re.search('super', 'insuperable').span())\n" -"(2, 7)" -msgstr "" -">>> print(re.search('super', 'superstition').span())\n" -"(0, 5)\n" -">>> print(re.search('super', 'insuperable').span())\n" -"(2, 7)" - -#: ../../howto/regex.rst:1299 -msgid "" -"Sometimes you'll be tempted to keep using :func:`re.match`, and just add ``." -"*`` to the front of your RE. Resist this temptation and use :func:`re." -"search` instead. The regular expression compiler does some analysis of REs " -"in order to speed up the process of looking for a match. One such analysis " -"figures out what the first character of a match must be; for example, a " -"pattern starting with ``Crow`` must match starting with a ``'C'``. The " -"analysis lets the engine quickly scan through the string looking for the " -"starting character, only trying the full match if a ``'C'`` is found." -msgstr "" - -#: ../../howto/regex.rst:1308 -msgid "" -"Adding ``.*`` defeats this optimization, requiring scanning to the end of " -"the string and then backtracking to find a match for the rest of the RE. " -"Use :func:`re.search` instead." -msgstr "" - -#: ../../howto/regex.rst:1314 -msgid "Greedy versus Non-Greedy" -msgstr "" - -#: ../../howto/regex.rst:1316 -msgid "" -"When repeating a regular expression, as in ``a*``, the resulting action is " -"to consume as much of the pattern as possible. This fact often bites you " -"when you're trying to match a pair of balanced delimiters, such as the angle " -"brackets surrounding an HTML tag. The naive pattern for matching a single " -"HTML tag doesn't work because of the greedy nature of ``.*``. ::" -msgstr "" - -#: ../../howto/regex.rst:1322 -msgid "" -">>> s = 'Title'\n" -">>> len(s)\n" -"32\n" -">>> print(re.match('<.*>', s).span())\n" -"(0, 32)\n" -">>> print(re.match('<.*>', s).group())\n" -"Title" -msgstr "" -">>> s = 'Title'\n" -">>> len(s)\n" -"32\n" -">>> print(re.match('<.*>', s).span())\n" -"(0, 32)\n" -">>> print(re.match('<.*>', s).group())\n" -"Title" - -#: ../../howto/regex.rst:1330 -msgid "" -"The RE matches the ``'<'`` in ``''``, and the ``.*`` consumes the rest " -"of the string. There's still more left in the RE, though, and the ``>`` " -"can't match at the end of the string, so the regular expression engine has " -"to backtrack character by character until it finds a match for the ``>``. " -"The final match extends from the ``'<'`` in ``''`` to the ``'>'`` in " -"``''``, which isn't what you want." -msgstr "" - -#: ../../howto/regex.rst:1337 -msgid "" -"In this case, the solution is to use the non-greedy quantifiers ``*?``, ``+?" -"``, ``??``, or ``{m,n}?``, which match as *little* text as possible. In the " -"above example, the ``'>'`` is tried immediately after the first ``'<'`` " -"matches, and when it fails, the engine advances a character at a time, " -"retrying the ``'>'`` at every step. This produces just the right result::" -msgstr "" - -#: ../../howto/regex.rst:1343 -msgid "" -">>> print(re.match('<.*?>', s).group())\n" -"" -msgstr "" -">>> print(re.match('<.*?>', s).group())\n" -"" - -#: ../../howto/regex.rst:1346 -msgid "" -"(Note that parsing HTML or XML with regular expressions is painful. Quick-" -"and-dirty patterns will handle common cases, but HTML and XML have special " -"cases that will break the obvious regular expression; by the time you've " -"written a regular expression that handles all of the possible cases, the " -"patterns will be *very* complicated. Use an HTML or XML parser module for " -"such tasks.)" -msgstr "" - -#: ../../howto/regex.rst:1354 -msgid "Using re.VERBOSE" -msgstr "" - -#: ../../howto/regex.rst:1356 -msgid "" -"By now you've probably noticed that regular expressions are a very compact " -"notation, but they're not terribly readable. REs of moderate complexity can " -"become lengthy collections of backslashes, parentheses, and metacharacters, " -"making them difficult to read and understand." -msgstr "" - -#: ../../howto/regex.rst:1361 -msgid "" -"For such REs, specifying the :const:`re.VERBOSE` flag when compiling the " -"regular expression can be helpful, because it allows you to format the " -"regular expression more clearly." -msgstr "" - -#: ../../howto/regex.rst:1365 -msgid "" -"The ``re.VERBOSE`` flag has several effects. Whitespace in the regular " -"expression that *isn't* inside a character class is ignored. This means " -"that an expression such as ``dog | cat`` is equivalent to the less readable " -"``dog|cat``, but ``[a b]`` will still match the characters ``'a'``, ``'b'``, " -"or a space. In addition, you can also put comments inside a RE; comments " -"extend from a ``#`` character to the next newline. When used with triple-" -"quoted strings, this enables REs to be formatted more neatly::" -msgstr "" - -#: ../../howto/regex.rst:1373 -msgid "" -"pat = re.compile(r\"\"\"\n" -" \\s* # Skip leading whitespace\n" -" (?P
[^:]+) # Header name\n" -" \\s* : # Whitespace, and a colon\n" -" (?P.*?) # The header's value -- *? used to\n" -" # lose the following trailing whitespace\n" -" \\s*$ # Trailing whitespace to end-of-line\n" -"\"\"\", re.VERBOSE)" -msgstr "" - -#: ../../howto/regex.rst:1382 -msgid "This is far more readable than::" -msgstr "" - -#: ../../howto/regex.rst:1384 -msgid "pat = re.compile(r\"\\s*(?P
[^:]+)\\s*:(?P.*?)\\s*$\")" -msgstr "pat = re.compile(r\"\\s*(?P
[^:]+)\\s*:(?P.*?)\\s*$\")" - -#: ../../howto/regex.rst:1388 -msgid "Feedback" -msgstr "" - -#: ../../howto/regex.rst:1390 -msgid "" -"Regular expressions are a complicated topic. Did this document help you " -"understand them? Were there parts that were unclear, or Problems you " -"encountered that weren't covered here? If so, please send suggestions for " -"improvements to the author." -msgstr "" - -#: ../../howto/regex.rst:1395 -msgid "" -"The most complete book on regular expressions is almost certainly Jeffrey " -"Friedl's Mastering Regular Expressions, published by O'Reilly. " -"Unfortunately, it exclusively concentrates on Perl and Java's flavours of " -"regular expressions, and doesn't contain any Python material at all, so it " -"won't be useful as a reference for programming in Python. (The first " -"edition covered Python's now-removed :mod:`!regex` module, which won't help " -"you much.) Consider checking it out from your library." -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Albin Sun , 2015 +# Kai-han Chang , 2015 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-12-01 00:17+0000\n" +"PO-Revision-Date: 2018-05-23 14:37+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" + +#: ../../howto/regex.rst:5 +msgid "Regular Expression HOWTO" +msgstr "如何使用正規表示式" + +#: ../../howto/regex.rst:0 +msgid "Author" +msgstr "作者" + +#: ../../howto/regex.rst:7 +msgid "A.M. Kuchling " +msgstr "A.M. Kuchling " + +#: ../../howto/regex.rst:16 +msgid "Abstract" +msgstr "摘要" + +#: ../../howto/regex.rst:18 +msgid "" +"This document is an introductory tutorial to using regular expressions in " +"Python with the :mod:`re` module. It provides a gentler introduction than " +"the corresponding section in the Library Reference." +msgstr "" +"此文件為如何在 Python 中使用 :mod:`re` 模組來撰寫正規表示式的入門指導。進階使" +"用及參考文件請見函式庫參考一章。" + +#: ../../howto/regex.rst:24 +msgid "Introduction" +msgstr "簡介" + +#: ../../howto/regex.rst:26 +msgid "" +"Regular expressions (called REs, or regexes, or regex patterns) are " +"essentially a tiny, highly specialized programming language embedded inside " +"Python and made available through the :mod:`re` module. Using this little " +"language, you specify the rules for the set of possible strings that you " +"want to match; this set might contain English sentences, or e-mail " +"addresses, or TeX commands, or anything you like. You can then ask " +"questions such as \"Does this string match the pattern?\", or \"Is there a " +"match for the pattern anywhere in this string?\". You can also use REs to " +"modify a string or to split it apart in various ways." +msgstr "" +"正規表示式 (也稱為 REs、regexes 或 regex patterns) 是一個輕量且高專業化的程式" +"語言。在 Python 中可透過內建的 :mod:`re` 模組直接使用。你可以使用此輕量化的" +"語言針對想要匹配的一組字串撰寫規則，這組字串可能包含了英語句子、e-mail 地址、" +"TeX 命令或任何東西。你可以檢查如「這組字串是否匹配這個規則？」或「這組字串中" +"是否有任一處匹配這個規則？」。除此之外，你也可以使用 REs 來修改或是切割字串。" + +#: ../../howto/regex.rst:35 +msgid "" +"Regular expression patterns are compiled into a series of bytecodes which " +"are then executed by a matching engine written in C. For advanced use, it " +"may be necessary to pay careful attention to how the engine will execute a " +"given RE, and write the RE in a certain way in order to produce bytecode " +"that runs faster. Optimization isn't covered in this document, because it " +"requires that you have a good understanding of the matching engine's " +"internals." +msgstr "" + +#: ../../howto/regex.rst:42 +msgid "" +"The regular expression language is relatively small and restricted, so not " +"all possible string processing tasks can be done using regular expressions. " +"There are also tasks that *can* be done with regular expressions, but the " +"expressions turn out to be very complicated. In these cases, you may be " +"better off writing Python code to do the processing; while Python code will " +"be slower than an elaborate regular expression, it will also probably be " +"more understandable." +msgstr "" + +#: ../../howto/regex.rst:51 +msgid "Simple Patterns" +msgstr "" + +#: ../../howto/regex.rst:53 +msgid "" +"We'll start by learning about the simplest possible regular expressions. " +"Since regular expressions are used to operate on strings, we'll begin with " +"the most common task: matching characters." +msgstr "" + +#: ../../howto/regex.rst:57 +msgid "" +"For a detailed explanation of the computer science underlying regular " +"expressions (deterministic and non-deterministic finite automata), you can " +"refer to almost any textbook on writing compilers." +msgstr "" + +#: ../../howto/regex.rst:63 +msgid "Matching Characters" +msgstr "" + +#: ../../howto/regex.rst:65 +msgid "" +"Most letters and characters will simply match themselves. For example, the " +"regular expression ``test`` will match the string ``test`` exactly. (You " +"can enable a case-insensitive mode that would let this RE match ``Test`` or " +"``TEST`` as well; more about this later.)" +msgstr "" + +#: ../../howto/regex.rst:70 +msgid "" +"There are exceptions to this rule; some characters are special :dfn:" +"`metacharacters`, and don't match themselves. Instead, they signal that " +"some out-of-the-ordinary thing should be matched, or they affect other " +"portions of the RE by repeating them or changing their meaning. Much of " +"this document is devoted to discussing various metacharacters and what they " +"do." +msgstr "" + +#: ../../howto/regex.rst:76 +msgid "" +"Here's a complete list of the metacharacters; their meanings will be " +"discussed in the rest of this HOWTO." +msgstr "" + +#: ../../howto/regex.rst:79 +msgid ". ^ $ * + ? { } [ ] \\ | ( )" +msgstr ". ^ $ * + ? { } [ ] \\ | ( )" + +#: ../../howto/regex.rst:83 +msgid "" +"The first metacharacters we'll look at are ``[`` and ``]``. They're used for " +"specifying a character class, which is a set of characters that you wish to " +"match. Characters can be listed individually, or a range of characters can " +"be indicated by giving two characters and separating them by a ``'-'``. For " +"example, ``[abc]`` will match any of the characters ``a``, ``b``, or ``c``; " +"this is the same as ``[a-c]``, which uses a range to express the same set of " +"characters. If you wanted to match only lowercase letters, your RE would be " +"``[a-z]``." +msgstr "" + +#: ../../howto/regex.rst:92 +msgid "" +"Metacharacters (except ``\\``) are not active inside classes. For example, " +"``[akm$]`` will match any of the characters ``'a'``, ``'k'``, ``'m'``, or " +"``'$'``; ``'$'`` is usually a metacharacter, but inside a character class " +"it's stripped of its special nature." +msgstr "" + +#: ../../howto/regex.rst:97 +msgid "" +"You can match the characters not listed within the class by :dfn:" +"`complementing` the set. This is indicated by including a ``'^'`` as the " +"first character of the class. For example, ``[^5]`` will match any character " +"except ``'5'``. If the caret appears elsewhere in a character class, it " +"does not have special meaning. For example: ``[5^]`` will match either a " +"``'5'`` or a ``'^'``." +msgstr "" + +#: ../../howto/regex.rst:103 +msgid "" +"Perhaps the most important metacharacter is the backslash, ``\\``. As in " +"Python string literals, the backslash can be followed by various characters " +"to signal various special sequences. It's also used to escape all the " +"metacharacters so you can still match them in patterns; for example, if you " +"need to match a ``[`` or ``\\``, you can precede them with a backslash to " +"remove their special meaning: ``\\[`` or ``\\\\``." +msgstr "" + +#: ../../howto/regex.rst:110 +msgid "" +"Some of the special sequences beginning with ``'\\'`` represent predefined " +"sets of characters that are often useful, such as the set of digits, the set " +"of letters, or the set of anything that isn't whitespace." +msgstr "" + +#: ../../howto/regex.rst:115 +msgid "" +"Let's take an example: ``\\w`` matches any alphanumeric character. If the " +"regex pattern is expressed in bytes, this is equivalent to the class ``[a-zA-" +"Z0-9_]``. If the regex pattern is a string, ``\\w`` will match all the " +"characters marked as letters in the Unicode database provided by the :mod:" +"`unicodedata` module. You can use the more restricted definition of ``\\w`` " +"in a string pattern by supplying the :const:`re.ASCII` flag when compiling " +"the regular expression." +msgstr "" + +#: ../../howto/regex.rst:123 +msgid "" +"The following list of special sequences isn't complete. For a complete list " +"of sequences and expanded class definitions for Unicode string patterns, see " +"the last part of :ref:`Regular Expression Syntax ` in the " +"Standard Library reference. In general, the Unicode versions match any " +"character that's in the appropriate category in the Unicode database." +msgstr "" + +#: ../../howto/regex.rst:130 +msgid "``\\d``" +msgstr "``\\d``" + +#: ../../howto/regex.rst:131 +msgid "Matches any decimal digit; this is equivalent to the class ``[0-9]``." +msgstr "" + +#: ../../howto/regex.rst:133 +msgid "``\\D``" +msgstr "``\\D``" + +#: ../../howto/regex.rst:134 +msgid "" +"Matches any non-digit character; this is equivalent to the class ``[^0-9]``." +msgstr "" + +#: ../../howto/regex.rst:136 +msgid "``\\s``" +msgstr "``\\s``" + +#: ../../howto/regex.rst:137 +msgid "" +"Matches any whitespace character; this is equivalent to the class " +"``[ \\t\\n\\r\\f\\v]``." +msgstr "" + +#: ../../howto/regex.rst:140 +msgid "``\\S``" +msgstr "``\\S``" + +#: ../../howto/regex.rst:141 +msgid "" +"Matches any non-whitespace character; this is equivalent to the class ``[^ " +"\\t\\n\\r\\f\\v]``." +msgstr "" + +#: ../../howto/regex.rst:144 +msgid "``\\w``" +msgstr "``\\w``" + +#: ../../howto/regex.rst:145 +msgid "" +"Matches any alphanumeric character; this is equivalent to the class ``[a-zA-" +"Z0-9_]``." +msgstr "" + +#: ../../howto/regex.rst:148 +msgid "``\\W``" +msgstr "``\\W``" + +#: ../../howto/regex.rst:149 +msgid "" +"Matches any non-alphanumeric character; this is equivalent to the class " +"``[^a-zA-Z0-9_]``." +msgstr "" + +#: ../../howto/regex.rst:152 +msgid "" +"These sequences can be included inside a character class. For example, " +"``[\\s,.]`` is a character class that will match any whitespace character, " +"or ``','`` or ``'.'``." +msgstr "" + +#: ../../howto/regex.rst:156 +msgid "" +"The final metacharacter in this section is ``.``. It matches anything " +"except a newline character, and there's an alternate mode (:const:`re." +"DOTALL`) where it will match even a newline. ``.`` is often used where you " +"want to match \"any character\"." +msgstr "" + +#: ../../howto/regex.rst:163 +msgid "Repeating Things" +msgstr "" + +#: ../../howto/regex.rst:165 +msgid "" +"Being able to match varying sets of characters is the first thing regular " +"expressions can do that isn't already possible with the methods available on " +"strings. However, if that was the only additional capability of regexes, " +"they wouldn't be much of an advance. Another capability is that you can " +"specify that portions of the RE must be repeated a certain number of times." +msgstr "" + +#: ../../howto/regex.rst:171 +msgid "" +"The first metacharacter for repeating things that we'll look at is ``*``. " +"``*`` doesn't match the literal character ``'*'``; instead, it specifies " +"that the previous character can be matched zero or more times, instead of " +"exactly once." +msgstr "" + +#: ../../howto/regex.rst:175 +msgid "" +"For example, ``ca*t`` will match ``'ct'`` (0 ``'a'`` characters), ``'cat'`` " +"(1 ``'a'``), ``'caaat'`` (3 ``'a'`` characters), and so forth." +msgstr "" + +#: ../../howto/regex.rst:178 +msgid "" +"Repetitions such as ``*`` are :dfn:`greedy`; when repeating a RE, the " +"matching engine will try to repeat it as many times as possible. If later " +"portions of the pattern don't match, the matching engine will then back up " +"and try again with fewer repetitions." +msgstr "" + +#: ../../howto/regex.rst:183 +msgid "" +"A step-by-step example will make this more obvious. Let's consider the " +"expression ``a[bcd]*b``. This matches the letter ``'a'``, zero or more " +"letters from the class ``[bcd]``, and finally ends with a ``'b'``. Now " +"imagine matching this RE against the string ``'abcbd'``." +msgstr "" + +#: ../../howto/regex.rst:189 +msgid "Step" +msgstr "" + +#: ../../howto/regex.rst:189 +msgid "Matched" +msgstr "" + +#: ../../howto/regex.rst:189 +msgid "Explanation" +msgstr "" + +#: ../../howto/regex.rst:191 +msgid "1" +msgstr "1" + +#: ../../howto/regex.rst:191 +msgid "``a``" +msgstr "``a``" + +#: ../../howto/regex.rst:191 +msgid "The ``a`` in the RE matches." +msgstr "" + +#: ../../howto/regex.rst:193 +msgid "2" +msgstr "2" + +#: ../../howto/regex.rst:193 +msgid "``abcbd``" +msgstr "``abcbd``" + +#: ../../howto/regex.rst:193 +msgid "" +"The engine matches ``[bcd]*``, going as far as it can, which is to the end " +"of the string." +msgstr "" + +#: ../../howto/regex.rst:197 +msgid "3" +msgstr "3" + +#: ../../howto/regex.rst:197 ../../howto/regex.rst:205 +msgid "*Failure*" +msgstr "" + +#: ../../howto/regex.rst:197 +msgid "" +"The engine tries to match ``b``, but the current position is at the end of " +"the string, so it fails." +msgstr "" + +#: ../../howto/regex.rst:202 +msgid "4" +msgstr "4" + +#: ../../howto/regex.rst:202 ../../howto/regex.rst:213 +msgid "``abcb``" +msgstr "``abcb``" + +#: ../../howto/regex.rst:202 +msgid "Back up, so that ``[bcd]*`` matches one less character." +msgstr "" + +#: ../../howto/regex.rst:205 +msgid "5" +msgstr "5" + +#: ../../howto/regex.rst:205 +msgid "" +"Try ``b`` again, but the current position is at the last character, which is " +"a ``'d'``." +msgstr "" + +#: ../../howto/regex.rst:209 ../../howto/regex.rst:213 +msgid "6" +msgstr "6" + +#: ../../howto/regex.rst:209 +msgid "``abc``" +msgstr "``abc``" + +#: ../../howto/regex.rst:209 +msgid "Back up again, so that ``[bcd]*`` is only matching ``bc``." +msgstr "" + +#: ../../howto/regex.rst:213 +msgid "" +"Try ``b`` again. This time the character at the current position is " +"``'b'``, so it succeeds." +msgstr "" + +#: ../../howto/regex.rst:219 +msgid "" +"The end of the RE has now been reached, and it has matched ``'abcb'``. This " +"demonstrates how the matching engine goes as far as it can at first, and if " +"no match is found it will then progressively back up and retry the rest of " +"the RE again and again. It will back up until it has tried zero matches for " +"``[bcd]*``, and if that subsequently fails, the engine will conclude that " +"the string doesn't match the RE at all." +msgstr "" + +#: ../../howto/regex.rst:226 +msgid "" +"Another repeating metacharacter is ``+``, which matches one or more times. " +"Pay careful attention to the difference between ``*`` and ``+``; ``*`` " +"matches *zero* or more times, so whatever's being repeated may not be " +"present at all, while ``+`` requires at least *one* occurrence. To use a " +"similar example, ``ca+t`` will match ``'cat'`` (1 ``'a'``), ``'caaat'`` (3 " +"``'a'``\\ s), but won't match ``'ct'``." +msgstr "" + +#: ../../howto/regex.rst:233 +msgid "" +"There are two more repeating operators or quantifiers. The question mark " +"character, ``?``, matches either once or zero times; you can think of it as " +"marking something as being optional. For example, ``home-?brew`` matches " +"either ``'homebrew'`` or ``'home-brew'``." +msgstr "" + +#: ../../howto/regex.rst:238 +msgid "" +"The most complicated quantifier is ``{m,n}``, where *m* and *n* are decimal " +"integers. This quantifier means there must be at least *m* repetitions, and " +"at most *n*. For example, ``a/{1,3}b`` will match ``'a/b'``, ``'a//b'``, " +"and ``'a///b'``. It won't match ``'ab'``, which has no slashes, or ``'a////" +"b'``, which has four." +msgstr "" + +#: ../../howto/regex.rst:244 +msgid "" +"You can omit either *m* or *n*; in that case, a reasonable value is assumed " +"for the missing value. Omitting *m* is interpreted as a lower limit of 0, " +"while omitting *n* results in an upper bound of infinity." +msgstr "" + +#: ../../howto/regex.rst:248 +msgid "" +"The simplest case ``{m}`` matches the preceding item exactly *m* times. For " +"example, ``a/{2}b`` will only match ``'a//b'``." +msgstr "" + +#: ../../howto/regex.rst:251 +msgid "" +"Readers of a reductionist bent may notice that the three other quantifiers " +"can all be expressed using this notation. ``{0,}`` is the same as ``*``, " +"``{1,}`` is equivalent to ``+``, and ``{0,1}`` is the same as ``?``. It's " +"better to use ``*``, ``+``, or ``?`` when you can, simply because they're " +"shorter and easier to read." +msgstr "" + +#: ../../howto/regex.rst:259 +msgid "Using Regular Expressions" +msgstr "" + +#: ../../howto/regex.rst:261 +msgid "" +"Now that we've looked at some simple regular expressions, how do we actually " +"use them in Python? The :mod:`re` module provides an interface to the " +"regular expression engine, allowing you to compile REs into objects and then " +"perform matches with them." +msgstr "" + +#: ../../howto/regex.rst:268 +msgid "Compiling Regular Expressions" +msgstr "" + +#: ../../howto/regex.rst:270 +msgid "" +"Regular expressions are compiled into pattern objects, which have methods " +"for various operations such as searching for pattern matches or performing " +"string substitutions. ::" +msgstr "" + +#: ../../howto/regex.rst:274 +msgid "" +">>> import re\n" +">>> p = re.compile('ab*')\n" +">>> p\n" +"re.compile('ab*')" +msgstr "" +">>> import re\n" +">>> p = re.compile('ab*')\n" +">>> p\n" +"re.compile('ab*')" + +#: ../../howto/regex.rst:279 +msgid "" +":func:`re.compile` also accepts an optional *flags* argument, used to enable " +"various special features and syntax variations. We'll go over the available " +"settings later, but for now a single example will do::" +msgstr "" + +#: ../../howto/regex.rst:283 +msgid ">>> p = re.compile('ab*', re.IGNORECASE)" +msgstr ">>> p = re.compile('ab*', re.IGNORECASE)" + +#: ../../howto/regex.rst:285 +msgid "" +"The RE is passed to :func:`re.compile` as a string. REs are handled as " +"strings because regular expressions aren't part of the core Python language, " +"and no special syntax was created for expressing them. (There are " +"applications that don't need REs at all, so there's no need to bloat the " +"language specification by including them.) Instead, the :mod:`re` module is " +"simply a C extension module included with Python, just like the :mod:" +"`socket` or :mod:`zlib` modules." +msgstr "" + +#: ../../howto/regex.rst:292 +msgid "" +"Putting REs in strings keeps the Python language simpler, but has one " +"disadvantage which is the topic of the next section." +msgstr "" + +#: ../../howto/regex.rst:299 +msgid "The Backslash Plague" +msgstr "" + +#: ../../howto/regex.rst:301 +msgid "" +"As stated earlier, regular expressions use the backslash character " +"(``'\\'``) to indicate special forms or to allow special characters to be " +"used without invoking their special meaning. This conflicts with Python's " +"usage of the same character for the same purpose in string literals." +msgstr "" + +#: ../../howto/regex.rst:306 +msgid "" +"Let's say you want to write a RE that matches the string ``\\section``, " +"which might be found in a LaTeX file. To figure out what to write in the " +"program code, start with the desired string to be matched. Next, you must " +"escape any backslashes and other metacharacters by preceding them with a " +"backslash, resulting in the string ``\\\\section``. The resulting string " +"that must be passed to :func:`re.compile` must be ``\\\\section``. However, " +"to express this as a Python string literal, both backslashes must be escaped " +"*again*." +msgstr "" + +#: ../../howto/regex.rst:315 +msgid "Characters" +msgstr "" + +#: ../../howto/regex.rst:315 +msgid "Stage" +msgstr "" + +#: ../../howto/regex.rst:317 +msgid "``\\section``" +msgstr "``\\section``" + +#: ../../howto/regex.rst:317 +msgid "Text string to be matched" +msgstr "" + +#: ../../howto/regex.rst:319 +msgid "``\\\\section``" +msgstr "``\\\\section``" + +#: ../../howto/regex.rst:319 +msgid "Escaped backslash for :func:`re.compile`" +msgstr "" + +#: ../../howto/regex.rst:321 ../../howto/regex.rst:348 +msgid "``\"\\\\\\\\section\"``" +msgstr "``\"\\\\\\\\section\"``" + +#: ../../howto/regex.rst:321 +msgid "Escaped backslashes for a string literal" +msgstr "" + +#: ../../howto/regex.rst:324 +msgid "" +"In short, to match a literal backslash, one has to write ``'\\\\\\\\'`` as " +"the RE string, because the regular expression must be ``\\\\``, and each " +"backslash must be expressed as ``\\\\`` inside a regular Python string " +"literal. In REs that feature backslashes repeatedly, this leads to lots of " +"repeated backslashes and makes the resulting strings difficult to understand." +msgstr "" + +#: ../../howto/regex.rst:330 +msgid "" +"The solution is to use Python's raw string notation for regular expressions; " +"backslashes are not handled in any special way in a string literal prefixed " +"with ``'r'``, so ``r\"\\n\"`` is a two-character string containing ``'\\'`` " +"and ``'n'``, while ``\"\\n\"`` is a one-character string containing a " +"newline. Regular expressions will often be written in Python code using this " +"raw string notation." +msgstr "" + +#: ../../howto/regex.rst:336 +msgid "" +"In addition, special escape sequences that are valid in regular expressions, " +"but not valid as Python string literals, now result in a :exc:" +"`DeprecationWarning` and will eventually become a :exc:`SyntaxError`, which " +"means the sequences will be invalid if raw string notation or escaping the " +"backslashes isn't used." +msgstr "" + +#: ../../howto/regex.rst:344 +msgid "Regular String" +msgstr "" + +#: ../../howto/regex.rst:344 +msgid "Raw string" +msgstr "" + +#: ../../howto/regex.rst:346 +msgid "``\"ab*\"``" +msgstr "``\"ab*\"``" + +#: ../../howto/regex.rst:346 +msgid "``r\"ab*\"``" +msgstr "``r\"ab*\"``" + +#: ../../howto/regex.rst:348 +msgid "``r\"\\\\section\"``" +msgstr "``r\"\\\\section\"``" + +#: ../../howto/regex.rst:350 +msgid "``\"\\\\w+\\\\s+\\\\1\"``" +msgstr "``\"\\\\w+\\\\s+\\\\1\"``" + +#: ../../howto/regex.rst:350 +msgid "``r\"\\w+\\s+\\1\"``" +msgstr "``r\"\\w+\\s+\\1\"``" + +#: ../../howto/regex.rst:355 +msgid "Performing Matches" +msgstr "" + +#: ../../howto/regex.rst:357 +msgid "" +"Once you have an object representing a compiled regular expression, what do " +"you do with it? Pattern objects have several methods and attributes. Only " +"the most significant ones will be covered here; consult the :mod:`re` docs " +"for a complete listing." +msgstr "" + +#: ../../howto/regex.rst:363 ../../howto/regex.rst:417 +#: ../../howto/regex.rst:1072 +msgid "Method/Attribute" +msgstr "方法/屬性" + +#: ../../howto/regex.rst:363 ../../howto/regex.rst:417 +#: ../../howto/regex.rst:1072 +msgid "Purpose" +msgstr "" + +#: ../../howto/regex.rst:365 +msgid "``match()``" +msgstr "``match()``" + +#: ../../howto/regex.rst:365 +msgid "Determine if the RE matches at the beginning of the string." +msgstr "" + +#: ../../howto/regex.rst:368 +msgid "``search()``" +msgstr "``search()``" + +#: ../../howto/regex.rst:368 +msgid "Scan through a string, looking for any location where this RE matches." +msgstr "" + +#: ../../howto/regex.rst:371 +msgid "``findall()``" +msgstr "``findall()``" + +#: ../../howto/regex.rst:371 +msgid "Find all substrings where the RE matches, and returns them as a list." +msgstr "" + +#: ../../howto/regex.rst:374 +msgid "``finditer()``" +msgstr "``finditer()``" + +#: ../../howto/regex.rst:374 +msgid "" +"Find all substrings where the RE matches, and returns them as an :term:" +"`iterator`." +msgstr "" + +#: ../../howto/regex.rst:378 +msgid "" +":meth:`~re.Pattern.match` and :meth:`~re.Pattern.search` return ``None`` if " +"no match can be found. If they're successful, a :ref:`match object ` instance is returned, containing information about the match: " +"where it starts and ends, the substring it matched, and more." +msgstr "" + +#: ../../howto/regex.rst:383 +msgid "" +"You can learn about this by interactively experimenting with the :mod:`re` " +"module." +msgstr "" + +#: ../../howto/regex.rst:386 +msgid "" +"This HOWTO uses the standard Python interpreter for its examples. First, run " +"the Python interpreter, import the :mod:`re` module, and compile a RE::" +msgstr "" + +#: ../../howto/regex.rst:389 +msgid "" +">>> import re\n" +">>> p = re.compile('[a-z]+')\n" +">>> p\n" +"re.compile('[a-z]+')" +msgstr "" +">>> import re\n" +">>> p = re.compile('[a-z]+')\n" +">>> p\n" +"re.compile('[a-z]+')" + +#: ../../howto/regex.rst:394 +msgid "" +"Now, you can try matching various strings against the RE ``[a-z]+``. An " +"empty string shouldn't match at all, since ``+`` means 'one or more " +"repetitions'. :meth:`~re.Pattern.match` should return ``None`` in this case, " +"which will cause the interpreter to print no output. You can explicitly " +"print the result of :meth:`!match` to make this clear. ::" +msgstr "" + +#: ../../howto/regex.rst:400 +msgid "" +">>> p.match(\"\")\n" +">>> print(p.match(\"\"))\n" +"None" +msgstr "" +">>> p.match(\"\")\n" +">>> print(p.match(\"\"))\n" +"None" + +#: ../../howto/regex.rst:404 +msgid "" +"Now, let's try it on a string that it should match, such as ``tempo``. In " +"this case, :meth:`~re.Pattern.match` will return a :ref:`match object `, so you should store the result in a variable for later use. ::" +msgstr "" + +#: ../../howto/regex.rst:408 +msgid "" +">>> m = p.match('tempo')\n" +">>> m\n" +"" +msgstr "" +">>> m = p.match('tempo')\n" +">>> m\n" +"" + +#: ../../howto/regex.rst:412 +msgid "" +"Now you can query the :ref:`match object ` for information " +"about the matching string. Match object instances also have several methods " +"and attributes; the most important ones are:" +msgstr "" + +#: ../../howto/regex.rst:419 +msgid "``group()``" +msgstr "``group()``" + +#: ../../howto/regex.rst:419 +msgid "Return the string matched by the RE" +msgstr "" + +#: ../../howto/regex.rst:421 +msgid "``start()``" +msgstr "``start()``" + +#: ../../howto/regex.rst:421 +msgid "Return the starting position of the match" +msgstr "" + +#: ../../howto/regex.rst:423 +msgid "``end()``" +msgstr "``end()``" + +#: ../../howto/regex.rst:423 +msgid "Return the ending position of the match" +msgstr "" + +#: ../../howto/regex.rst:425 +msgid "``span()``" +msgstr "``span()``" + +#: ../../howto/regex.rst:425 +msgid "Return a tuple containing the (start, end) positions of the match" +msgstr "" + +#: ../../howto/regex.rst:429 +msgid "Trying these methods will soon clarify their meaning::" +msgstr "" + +#: ../../howto/regex.rst:431 +msgid "" +">>> m.group()\n" +"'tempo'\n" +">>> m.start(), m.end()\n" +"(0, 5)\n" +">>> m.span()\n" +"(0, 5)" +msgstr "" +">>> m.group()\n" +"'tempo'\n" +">>> m.start(), m.end()\n" +"(0, 5)\n" +">>> m.span()\n" +"(0, 5)" + +#: ../../howto/regex.rst:438 +msgid "" +":meth:`~re.Match.group` returns the substring that was matched by the RE. :" +"meth:`~re.Match.start` and :meth:`~re.Match.end` return the starting and " +"ending index of the match. :meth:`~re.Match.span` returns both start and end " +"indexes in a single tuple. Since the :meth:`~re.Pattern.match` method only " +"checks if the RE matches at the start of a string, :meth:`!start` will " +"always be zero. However, the :meth:`~re.Pattern.search` method of patterns " +"scans through the string, so the match may not start at zero in that " +"case. ::" +msgstr "" + +#: ../../howto/regex.rst:446 +msgid "" +">>> print(p.match('::: message'))\n" +"None\n" +">>> m = p.search('::: message'); print(m)\n" +"\n" +">>> m.group()\n" +"'message'\n" +">>> m.span()\n" +"(4, 11)" +msgstr "" +">>> print(p.match('::: message'))\n" +"None\n" +">>> m = p.search('::: message'); print(m)\n" +"\n" +">>> m.group()\n" +"'message'\n" +">>> m.span()\n" +"(4, 11)" + +#: ../../howto/regex.rst:455 +msgid "" +"In actual programs, the most common style is to store the :ref:`match object " +"` in a variable, and then check if it was ``None``. This " +"usually looks like::" +msgstr "" + +#: ../../howto/regex.rst:459 +msgid "" +"p = re.compile( ... )\n" +"m = p.match( 'string goes here' )\n" +"if m:\n" +" print('Match found: ', m.group())\n" +"else:\n" +" print('No match')" +msgstr "" +"p = re.compile( ... )\n" +"m = p.match( 'string goes here' )\n" +"if m:\n" +" print('Match found: ', m.group())\n" +"else:\n" +" print('No match')" + +#: ../../howto/regex.rst:466 +msgid "" +"Two pattern methods return all of the matches for a pattern. :meth:`~re." +"Pattern.findall` returns a list of matching strings::" +msgstr "" + +#: ../../howto/regex.rst:469 +msgid "" +">>> p = re.compile(r'\\d+')\n" +">>> p.findall('12 drummers drumming, 11 pipers piping, 10 lords a-leaping')\n" +"['12', '11', '10']" +msgstr "" +">>> p = re.compile(r'\\d+')\n" +">>> p.findall('12 drummers drumming, 11 pipers piping, 10 lords a-leaping')\n" +"['12', '11', '10']" + +#: ../../howto/regex.rst:473 +msgid "" +"The ``r`` prefix, making the literal a raw string literal, is needed in this " +"example because escape sequences in a normal \"cooked\" string literal that " +"are not recognized by Python, as opposed to regular expressions, now result " +"in a :exc:`DeprecationWarning` and will eventually become a :exc:" +"`SyntaxError`. See :ref:`the-backslash-plague`." +msgstr "" + +#: ../../howto/regex.rst:479 +msgid "" +":meth:`~re.Pattern.findall` has to create the entire list before it can be " +"returned as the result. The :meth:`~re.Pattern.finditer` method returns a " +"sequence of :ref:`match object ` instances as an :term:" +"`iterator`::" +msgstr "" + +#: ../../howto/regex.rst:483 +msgid "" +">>> iterator = p.finditer('12 drummers drumming, 11 ... 10 ...')\n" +">>> iterator\n" +"\n" +">>> for match in iterator:\n" +"... print(match.span())\n" +"...\n" +"(0, 2)\n" +"(22, 24)\n" +"(29, 31)" +msgstr "" +">>> iterator = p.finditer('12 drummers drumming, 11 ... 10 ...')\n" +">>> iterator\n" +"\n" +">>> for match in iterator:\n" +"... print(match.span())\n" +"...\n" +"(0, 2)\n" +"(22, 24)\n" +"(29, 31)" + +#: ../../howto/regex.rst:495 +msgid "Module-Level Functions" +msgstr "模組層級函式" + +#: ../../howto/regex.rst:497 +msgid "" +"You don't have to create a pattern object and call its methods; the :mod:" +"`re` module also provides top-level functions called :func:`~re.match`, :" +"func:`~re.search`, :func:`~re.findall`, :func:`~re.sub`, and so forth. " +"These functions take the same arguments as the corresponding pattern method " +"with the RE string added as the first argument, and still return either " +"``None`` or a :ref:`match object ` instance. ::" +msgstr "" + +#: ../../howto/regex.rst:504 +msgid "" +">>> print(re.match(r'From\\s+', 'Fromage amk'))\n" +"None\n" +">>> re.match(r'From\\s+', 'From amk Thu May 14 19:12:10 1998')\n" +"" +msgstr "" +">>> print(re.match(r'From\\s+', 'Fromage amk'))\n" +"None\n" +">>> re.match(r'From\\s+', 'From amk Thu May 14 19:12:10 1998')\n" +"" + +#: ../../howto/regex.rst:509 +msgid "" +"Under the hood, these functions simply create a pattern object for you and " +"call the appropriate method on it. They also store the compiled object in a " +"cache, so future calls using the same RE won't need to parse the pattern " +"again and again." +msgstr "" + +#: ../../howto/regex.rst:514 +msgid "" +"Should you use these module-level functions, or should you get the pattern " +"and call its methods yourself? If you're accessing a regex within a loop, " +"pre-compiling it will save a few function calls. Outside of loops, there's " +"not much difference thanks to the internal cache." +msgstr "" + +#: ../../howto/regex.rst:522 +msgid "Compilation Flags" +msgstr "" + +#: ../../howto/regex.rst:526 +msgid "" +"Compilation flags let you modify some aspects of how regular expressions " +"work. Flags are available in the :mod:`re` module under two names, a long " +"name such as :const:`IGNORECASE` and a short, one-letter form such as :const:" +"`I`. (If you're familiar with Perl's pattern modifiers, the one-letter " +"forms use the same letters; the short form of :const:`re.VERBOSE` is :const:" +"`re.X`, for example.) Multiple flags can be specified by bitwise OR-ing " +"them; ``re.I | re.M`` sets both the :const:`I` and :const:`M` flags, for " +"example." +msgstr "" + +#: ../../howto/regex.rst:534 +msgid "" +"Here's a table of the available flags, followed by a more detailed " +"explanation of each one." +msgstr "" + +#: ../../howto/regex.rst:538 +msgid "Flag" +msgstr "旗標" + +#: ../../howto/regex.rst:538 +msgid "Meaning" +msgstr "含義" + +#: ../../howto/regex.rst:540 +msgid ":const:`ASCII`, :const:`A`" +msgstr ":const:`ASCII`, :const:`A`" + +#: ../../howto/regex.rst:540 +msgid "" +"Makes several escapes like ``\\w``, ``\\b``, ``\\s`` and ``\\d`` match only " +"on ASCII characters with the respective property." +msgstr "" + +#: ../../howto/regex.rst:544 +msgid ":const:`DOTALL`, :const:`S`" +msgstr ":const:`DOTALL`, :const:`S`" + +#: ../../howto/regex.rst:544 +msgid "Make ``.`` match any character, including newlines." +msgstr "" + +#: ../../howto/regex.rst:547 +msgid ":const:`IGNORECASE`, :const:`I`" +msgstr ":const:`IGNORECASE`, :const:`I`" + +#: ../../howto/regex.rst:547 +msgid "Do case-insensitive matches." +msgstr "" + +#: ../../howto/regex.rst:549 +msgid ":const:`LOCALE`, :const:`L`" +msgstr ":const:`LOCALE`, :const:`L`" + +#: ../../howto/regex.rst:549 +msgid "Do a locale-aware match." +msgstr "" + +#: ../../howto/regex.rst:551 +msgid ":const:`MULTILINE`, :const:`M`" +msgstr ":const:`MULTILINE`, :const:`M`" + +#: ../../howto/regex.rst:551 +msgid "Multi-line matching, affecting ``^`` and ``$``." +msgstr "" + +#: ../../howto/regex.rst:554 +msgid ":const:`VERBOSE`, :const:`X` (for 'extended')" +msgstr "" + +#: ../../howto/regex.rst:554 +msgid "" +"Enable verbose REs, which can be organized more cleanly and understandably." +msgstr "" + +#: ../../howto/regex.rst:563 +msgid "" +"Perform case-insensitive matching; character class and literal strings will " +"match letters by ignoring case. For example, ``[A-Z]`` will match lowercase " +"letters, too. Full Unicode matching also works unless the :const:`ASCII` " +"flag is used to disable non-ASCII matches. When the Unicode patterns ``[a-" +"z]`` or ``[A-Z]`` are used in combination with the :const:`IGNORECASE` flag, " +"they will match the 52 ASCII letters and 4 additional non-ASCII letters: " +"'İ' (U+0130, Latin capital letter I with dot above), 'ı' (U+0131, Latin " +"small letter dotless i), 'ſ' (U+017F, Latin small letter long s) and " +"'K' (U+212A, Kelvin sign). ``Spam`` will match ``'Spam'``, ``'spam'``, " +"``'spAM'``, or ``'ſpam'`` (the latter is matched only in Unicode mode). This " +"lowercasing doesn't take the current locale into account; it will if you " +"also set the :const:`LOCALE` flag." +msgstr "" + +#: ../../howto/regex.rst:581 +msgid "" +"Make ``\\w``, ``\\W``, ``\\b``, ``\\B`` and case-insensitive matching " +"dependent on the current locale instead of the Unicode database." +msgstr "" + +#: ../../howto/regex.rst:584 +msgid "" +"Locales are a feature of the C library intended to help in writing programs " +"that take account of language differences. For example, if you're " +"processing encoded French text, you'd want to be able to write ``\\w+`` to " +"match words, but ``\\w`` only matches the character class ``[A-Za-z]`` in " +"bytes patterns; it won't match bytes corresponding to ``é`` or ``ç``. If " +"your system is configured properly and a French locale is selected, certain " +"C functions will tell the program that the byte corresponding to ``é`` " +"should also be considered a letter. Setting the :const:`LOCALE` flag when " +"compiling a regular expression will cause the resulting compiled object to " +"use these C functions for ``\\w``; this is slower, but also enables ``\\w+`` " +"to match French words as you'd expect. The use of this flag is discouraged " +"in Python 3 as the locale mechanism is very unreliable, it only handles one " +"\"culture\" at a time, and it only works with 8-bit locales. Unicode " +"matching is already enabled by default in Python 3 for Unicode (str) " +"patterns, and it is able to handle different locales/languages." +msgstr "" + +#: ../../howto/regex.rst:606 +msgid "" +"(``^`` and ``$`` haven't been explained yet; they'll be introduced in " +"section :ref:`more-metacharacters`.)" +msgstr "" + +#: ../../howto/regex.rst:609 +msgid "" +"Usually ``^`` matches only at the beginning of the string, and ``$`` matches " +"only at the end of the string and immediately before the newline (if any) at " +"the end of the string. When this flag is specified, ``^`` matches at the " +"beginning of the string and at the beginning of each line within the string, " +"immediately following each newline. Similarly, the ``$`` metacharacter " +"matches either at the end of the string and at the end of each line " +"(immediately preceding each newline)." +msgstr "" + +#: ../../howto/regex.rst:622 +msgid "" +"Makes the ``'.'`` special character match any character at all, including a " +"newline; without this flag, ``'.'`` will match anything *except* a newline." +msgstr "" + +#: ../../howto/regex.rst:630 +msgid "" +"Make ``\\w``, ``\\W``, ``\\b``, ``\\B``, ``\\s`` and ``\\S`` perform ASCII-" +"only matching instead of full Unicode matching. This is only meaningful for " +"Unicode patterns, and is ignored for byte patterns." +msgstr "" + +#: ../../howto/regex.rst:639 +msgid "" +"This flag allows you to write regular expressions that are more readable by " +"granting you more flexibility in how you can format them. When this flag " +"has been specified, whitespace within the RE string is ignored, except when " +"the whitespace is in a character class or preceded by an unescaped " +"backslash; this lets you organize and indent the RE more clearly. This flag " +"also lets you put comments within a RE that will be ignored by the engine; " +"comments are marked by a ``'#'`` that's neither in a character class or " +"preceded by an unescaped backslash." +msgstr "" + +#: ../../howto/regex.rst:648 +msgid "" +"For example, here's a RE that uses :const:`re.VERBOSE`; see how much easier " +"it is to read? ::" +msgstr "" + +#: ../../howto/regex.rst:651 +msgid "" +"charref = re.compile(r\"\"\"\n" +" &[#] # Start of a numeric entity reference\n" +" (\n" +" 0[0-7]+ # Octal form\n" +" | [0-9]+ # Decimal form\n" +" | x[0-9a-fA-F]+ # Hexadecimal form\n" +" )\n" +" ; # Trailing semicolon\n" +"\"\"\", re.VERBOSE)" +msgstr "" + +#: ../../howto/regex.rst:661 +msgid "Without the verbose setting, the RE would look like this::" +msgstr "" + +#: ../../howto/regex.rst:663 +msgid "" +"charref = re.compile(\"&#(0[0-7]+\"\n" +" \"|[0-9]+\"\n" +" \"|x[0-9a-fA-F]+);\")" +msgstr "" +"charref = re.compile(\"&#(0[0-7]+\"\n" +" \"|[0-9]+\"\n" +" \"|x[0-9a-fA-F]+);\")" + +#: ../../howto/regex.rst:667 +msgid "" +"In the above example, Python's automatic concatenation of string literals " +"has been used to break up the RE into smaller pieces, but it's still more " +"difficult to understand than the version using :const:`re.VERBOSE`." +msgstr "" + +#: ../../howto/regex.rst:673 +msgid "More Pattern Power" +msgstr "" + +#: ../../howto/regex.rst:675 +msgid "" +"So far we've only covered a part of the features of regular expressions. In " +"this section, we'll cover some new metacharacters, and how to use groups to " +"retrieve portions of the text that was matched." +msgstr "" + +#: ../../howto/regex.rst:683 +msgid "More Metacharacters" +msgstr "" + +#: ../../howto/regex.rst:685 +msgid "" +"There are some metacharacters that we haven't covered yet. Most of them " +"will be covered in this section." +msgstr "" + +#: ../../howto/regex.rst:688 +msgid "" +"Some of the remaining metacharacters to be discussed are :dfn:`zero-width " +"assertions`. They don't cause the engine to advance through the string; " +"instead, they consume no characters at all, and simply succeed or fail. For " +"example, ``\\b`` is an assertion that the current position is located at a " +"word boundary; the position isn't changed by the ``\\b`` at all. This means " +"that zero-width assertions should never be repeated, because if they match " +"once at a given location, they can obviously be matched an infinite number " +"of times." +msgstr "" + +#: ../../howto/regex.rst:696 +msgid "``|``" +msgstr "``|``" + +#: ../../howto/regex.rst:697 +msgid "" +"Alternation, or the \"or\" operator. If *A* and *B* are regular " +"expressions, ``A|B`` will match any string that matches either *A* or *B*. " +"``|`` has very low precedence in order to make it work reasonably when " +"you're alternating multi-character strings. ``Crow|Servo`` will match either " +"``'Crow'`` or ``'Servo'``, not ``'Cro'``, a ``'w'`` or an ``'S'``, and " +"``'ervo'``." +msgstr "" + +#: ../../howto/regex.rst:703 +msgid "" +"To match a literal ``'|'``, use ``\\|``, or enclose it inside a character " +"class, as in ``[|]``." +msgstr "" + +#: ../../howto/regex.rst:706 +msgid "``^``" +msgstr "``^``" + +#: ../../howto/regex.rst:707 +msgid "" +"Matches at the beginning of lines. Unless the :const:`MULTILINE` flag has " +"been set, this will only match at the beginning of the string. In :const:" +"`MULTILINE` mode, this also matches immediately after each newline within " +"the string." +msgstr "" + +#: ../../howto/regex.rst:711 +msgid "" +"For example, if you wish to match the word ``From`` only at the beginning of " +"a line, the RE to use is ``^From``. ::" +msgstr "" + +#: ../../howto/regex.rst:714 +msgid "" +">>> print(re.search('^From', 'From Here to Eternity'))\n" +"\n" +">>> print(re.search('^From', 'Reciting From Memory'))\n" +"None" +msgstr "" +">>> print(re.search('^From', 'From Here to Eternity'))\n" +"\n" +">>> print(re.search('^From', 'Reciting From Memory'))\n" +"None" + +#: ../../howto/regex.rst:719 +msgid "To match a literal ``'^'``, use ``\\^``." +msgstr "" + +#: ../../howto/regex.rst:721 +msgid "``$``" +msgstr "``$``" + +#: ../../howto/regex.rst:722 +msgid "" +"Matches at the end of a line, which is defined as either the end of the " +"string, or any location followed by a newline character. ::" +msgstr "" + +#: ../../howto/regex.rst:725 +msgid "" +">>> print(re.search('}$', '{block}'))\n" +"\n" +">>> print(re.search('}$', '{block} '))\n" +"None\n" +">>> print(re.search('}$', '{block}\\n'))\n" +"" +msgstr "" +">>> print(re.search('}$', '{block}'))\n" +"\n" +">>> print(re.search('}$', '{block} '))\n" +"None\n" +">>> print(re.search('}$', '{block}\\n'))\n" +"" + +#: ../../howto/regex.rst:732 +msgid "" +"To match a literal ``'$'``, use ``\\$`` or enclose it inside a character " +"class, as in ``[$]``." +msgstr "" + +#: ../../howto/regex.rst:735 +msgid "``\\A``" +msgstr "``\\A``" + +#: ../../howto/regex.rst:736 +msgid "" +"Matches only at the start of the string. When not in :const:`MULTILINE` " +"mode, ``\\A`` and ``^`` are effectively the same. In :const:`MULTILINE` " +"mode, they're different: ``\\A`` still matches only at the beginning of the " +"string, but ``^`` may match at any location inside the string that follows a " +"newline character." +msgstr "" + +#: ../../howto/regex.rst:741 +msgid "``\\z``" +msgstr "``\\z``" + +#: ../../howto/regex.rst:742 +msgid "Matches only at the end of the string." +msgstr "" + +#: ../../howto/regex.rst:744 +msgid "``\\Z``" +msgstr "``\\Z``" + +#: ../../howto/regex.rst:745 +msgid "The same as ``\\z``. For compatibility with old Python versions." +msgstr "" + +#: ../../howto/regex.rst:747 +msgid "``\\b``" +msgstr "``\\b``" + +#: ../../howto/regex.rst:748 +msgid "" +"Word boundary. This is a zero-width assertion that matches only at the " +"beginning or end of a word. A word is defined as a sequence of alphanumeric " +"characters, so the end of a word is indicated by whitespace or a non-" +"alphanumeric character." +msgstr "" + +#: ../../howto/regex.rst:753 +msgid "" +"The following example matches ``class`` only when it's a complete word; it " +"won't match when it's contained inside another word. ::" +msgstr "" + +#: ../../howto/regex.rst:756 +msgid "" +">>> p = re.compile(r'\\bclass\\b')\n" +">>> print(p.search('no class at all'))\n" +"\n" +">>> print(p.search('the declassified algorithm'))\n" +"None\n" +">>> print(p.search('one subclass is'))\n" +"None" +msgstr "" +">>> p = re.compile(r'\\bclass\\b')\n" +">>> print(p.search('no class at all'))\n" +"\n" +">>> print(p.search('the declassified algorithm'))\n" +"None\n" +">>> print(p.search('one subclass is'))\n" +"None" + +#: ../../howto/regex.rst:764 +msgid "" +"There are two subtleties you should remember when using this special " +"sequence. First, this is the worst collision between Python's string " +"literals and regular expression sequences. In Python's string literals, " +"``\\b`` is the backspace character, ASCII value 8. If you're not using raw " +"strings, then Python will convert the ``\\b`` to a backspace, and your RE " +"won't match as you expect it to. The following example looks the same as our " +"previous RE, but omits the ``'r'`` in front of the RE string. ::" +msgstr "" + +#: ../../howto/regex.rst:772 +msgid "" +">>> p = re.compile('\\bclass\\b')\n" +">>> print(p.search('no class at all'))\n" +"None\n" +">>> print(p.search('\\b' + 'class' + '\\b'))\n" +"" +msgstr "" +">>> p = re.compile('\\bclass\\b')\n" +">>> print(p.search('no class at all'))\n" +"None\n" +">>> print(p.search('\\b' + 'class' + '\\b'))\n" +"" + +#: ../../howto/regex.rst:778 +msgid "" +"Second, inside a character class, where there's no use for this assertion, " +"``\\b`` represents the backspace character, for compatibility with Python's " +"string literals." +msgstr "" + +#: ../../howto/regex.rst:782 +msgid "``\\B``" +msgstr "``\\B``" + +#: ../../howto/regex.rst:783 +msgid "" +"Another zero-width assertion, this is the opposite of ``\\b``, only matching " +"when the current position is not at a word boundary." +msgstr "" + +#: ../../howto/regex.rst:788 +msgid "Grouping" +msgstr "" + +#: ../../howto/regex.rst:790 +msgid "" +"Frequently you need to obtain more information than just whether the RE " +"matched or not. Regular expressions are often used to dissect strings by " +"writing a RE divided into several subgroups which match different components " +"of interest. For example, an RFC-822 header line is divided into a header " +"name and a value, separated by a ``':'``, like this:" +msgstr "" + +#: ../../howto/regex.rst:796 +msgid "" +"From: author@example.com\n" +"User-Agent: Thunderbird 1.5.0.9 (X11/20061227)\n" +"MIME-Version: 1.0\n" +"To: editor@example.com" +msgstr "" +"From: author@example.com\n" +"User-Agent: Thunderbird 1.5.0.9 (X11/20061227)\n" +"MIME-Version: 1.0\n" +"To: editor@example.com" + +#: ../../howto/regex.rst:803 +msgid "" +"This can be handled by writing a regular expression which matches an entire " +"header line, and has one group which matches the header name, and another " +"group which matches the header's value." +msgstr "" + +#: ../../howto/regex.rst:807 +msgid "" +"Groups are marked by the ``'('``, ``')'`` metacharacters. ``'('`` and " +"``')'`` have much the same meaning as they do in mathematical expressions; " +"they group together the expressions contained inside them, and you can " +"repeat the contents of a group with a quantifier, such as ``*``, ``+``, ``?" +"``, or ``{m,n}``. For example, ``(ab)*`` will match zero or more " +"repetitions of ``ab``. ::" +msgstr "" + +#: ../../howto/regex.rst:814 +msgid "" +">>> p = re.compile('(ab)*')\n" +">>> print(p.match('ababababab').span())\n" +"(0, 10)" +msgstr "" +">>> p = re.compile('(ab)*')\n" +">>> print(p.match('ababababab').span())\n" +"(0, 10)" + +#: ../../howto/regex.rst:818 +msgid "" +"Groups indicated with ``'('``, ``')'`` also capture the starting and ending " +"index of the text that they match; this can be retrieved by passing an " +"argument to :meth:`~re.Match.group`, :meth:`~re.Match.start`, :meth:`~re." +"Match.end`, and :meth:`~re.Match.span`. Groups are numbered starting with " +"0. Group 0 is always present; it's the whole RE, so :ref:`match object " +"` methods all have group 0 as their default argument. Later " +"we'll see how to express groups that don't capture the span of text that " +"they match. ::" +msgstr "" + +#: ../../howto/regex.rst:827 +msgid "" +">>> p = re.compile('(a)b')\n" +">>> m = p.match('ab')\n" +">>> m.group()\n" +"'ab'\n" +">>> m.group(0)\n" +"'ab'" +msgstr "" +">>> p = re.compile('(a)b')\n" +">>> m = p.match('ab')\n" +">>> m.group()\n" +"'ab'\n" +">>> m.group(0)\n" +"'ab'" + +#: ../../howto/regex.rst:834 +msgid "" +"Subgroups are numbered from left to right, from 1 upward. Groups can be " +"nested; to determine the number, just count the opening parenthesis " +"characters, going from left to right. ::" +msgstr "" + +#: ../../howto/regex.rst:838 +msgid "" +">>> p = re.compile('(a(b)c)d')\n" +">>> m = p.match('abcd')\n" +">>> m.group(0)\n" +"'abcd'\n" +">>> m.group(1)\n" +"'abc'\n" +">>> m.group(2)\n" +"'b'" +msgstr "" +">>> p = re.compile('(a(b)c)d')\n" +">>> m = p.match('abcd')\n" +">>> m.group(0)\n" +"'abcd'\n" +">>> m.group(1)\n" +"'abc'\n" +">>> m.group(2)\n" +"'b'" + +#: ../../howto/regex.rst:847 +msgid "" +":meth:`~re.Match.group` can be passed multiple group numbers at a time, in " +"which case it will return a tuple containing the corresponding values for " +"those groups. ::" +msgstr "" + +#: ../../howto/regex.rst:850 +msgid "" +">>> m.group(2,1,2)\n" +"('b', 'abc', 'b')" +msgstr "" +">>> m.group(2,1,2)\n" +"('b', 'abc', 'b')" + +#: ../../howto/regex.rst:853 +msgid "" +"The :meth:`~re.Match.groups` method returns a tuple containing the strings " +"for all the subgroups, from 1 up to however many there are. ::" +msgstr "" + +#: ../../howto/regex.rst:856 +msgid "" +">>> m.groups()\n" +"('abc', 'b')" +msgstr "" +">>> m.groups()\n" +"('abc', 'b')" + +#: ../../howto/regex.rst:859 +msgid "" +"Backreferences in a pattern allow you to specify that the contents of an " +"earlier capturing group must also be found at the current location in the " +"string. For example, ``\\1`` will succeed if the exact contents of group 1 " +"can be found at the current position, and fails otherwise. Remember that " +"Python's string literals also use a backslash followed by numbers to allow " +"including arbitrary characters in a string, so be sure to use a raw string " +"when incorporating backreferences in a RE." +msgstr "" + +#: ../../howto/regex.rst:867 +msgid "For example, the following RE detects doubled words in a string. ::" +msgstr "" + +#: ../../howto/regex.rst:869 +msgid "" +">>> p = re.compile(r'\\b(\\w+)\\s+\\1\\b')\n" +">>> p.search('Paris in the the spring').group()\n" +"'the the'" +msgstr "" +">>> p = re.compile(r'\\b(\\w+)\\s+\\1\\b')\n" +">>> p.search('Paris in the the spring').group()\n" +"'the the'" + +#: ../../howto/regex.rst:873 +msgid "" +"Backreferences like this aren't often useful for just searching through a " +"string --- there are few text formats which repeat data in this way --- but " +"you'll soon find out that they're *very* useful when performing string " +"substitutions." +msgstr "" + +#: ../../howto/regex.rst:879 +msgid "Non-capturing and Named Groups" +msgstr "" + +#: ../../howto/regex.rst:881 +msgid "" +"Elaborate REs may use many groups, both to capture substrings of interest, " +"and to group and structure the RE itself. In complex REs, it becomes " +"difficult to keep track of the group numbers. There are two features which " +"help with this problem. Both of them use a common syntax for regular " +"expression extensions, so we'll look at that first." +msgstr "" + +#: ../../howto/regex.rst:887 +msgid "" +"Perl 5 is well known for its powerful additions to standard regular " +"expressions. For these new features the Perl developers couldn't choose new " +"single-keystroke metacharacters or new special sequences beginning with " +"``\\`` without making Perl's regular expressions confusingly different from " +"standard REs. If they chose ``&`` as a new metacharacter, for example, old " +"expressions would be assuming that ``&`` was a regular character and " +"wouldn't have escaped it by writing ``\\&`` or ``[&]``." +msgstr "" + +#: ../../howto/regex.rst:894 +msgid "" +"The solution chosen by the Perl developers was to use ``(?...)`` as the " +"extension syntax. ``?`` immediately after a parenthesis was a syntax error " +"because the ``?`` would have nothing to repeat, so this didn't introduce any " +"compatibility problems. The characters immediately after the ``?`` " +"indicate what extension is being used, so ``(?=foo)`` is one thing (a " +"positive lookahead assertion) and ``(?:foo)`` is something else (a non-" +"capturing group containing the subexpression ``foo``)." +msgstr "" + +#: ../../howto/regex.rst:902 +msgid "" +"Python supports several of Perl's extensions and adds an extension syntax to " +"Perl's extension syntax. If the first character after the question mark is " +"a ``P``, you know that it's an extension that's specific to Python." +msgstr "" + +#: ../../howto/regex.rst:907 +msgid "" +"Now that we've looked at the general extension syntax, we can return to the " +"features that simplify working with groups in complex REs." +msgstr "" + +#: ../../howto/regex.rst:910 +msgid "" +"Sometimes you'll want to use a group to denote a part of a regular " +"expression, but aren't interested in retrieving the group's contents. You " +"can make this fact explicit by using a non-capturing group: ``(?:...)``, " +"where you can replace the ``...`` with any other regular expression. ::" +msgstr "" + +#: ../../howto/regex.rst:915 +msgid "" +">>> m = re.match(\"([abc])+\", \"abc\")\n" +">>> m.groups()\n" +"('c',)\n" +">>> m = re.match(\"(?:[abc])+\", \"abc\")\n" +">>> m.groups()\n" +"()" +msgstr "" +">>> m = re.match(\"([abc])+\", \"abc\")\n" +">>> m.groups()\n" +"('c',)\n" +">>> m = re.match(\"(?:[abc])+\", \"abc\")\n" +">>> m.groups()\n" +"()" + +#: ../../howto/regex.rst:922 +msgid "" +"Except for the fact that you can't retrieve the contents of what the group " +"matched, a non-capturing group behaves exactly the same as a capturing " +"group; you can put anything inside it, repeat it with a repetition " +"metacharacter such as ``*``, and nest it within other groups (capturing or " +"non-capturing). ``(?:...)`` is particularly useful when modifying an " +"existing pattern, since you can add new groups without changing how all the " +"other groups are numbered. It should be mentioned that there's no " +"performance difference in searching between capturing and non-capturing " +"groups; neither form is any faster than the other." +msgstr "" + +#: ../../howto/regex.rst:931 +msgid "" +"A more significant feature is named groups: instead of referring to them by " +"numbers, groups can be referenced by a name." +msgstr "" + +#: ../../howto/regex.rst:934 +msgid "" +"The syntax for a named group is one of the Python-specific extensions: ``(?" +"P...)``. *name* is, obviously, the name of the group. Named groups " +"behave exactly like capturing groups, and additionally associate a name with " +"a group. The :ref:`match object ` methods that deal with " +"capturing groups all accept either integers that refer to the group by " +"number or strings that contain the desired group's name. Named groups are " +"still given numbers, so you can retrieve information about a group in two " +"ways::" +msgstr "" + +#: ../../howto/regex.rst:942 +msgid "" +">>> p = re.compile(r'(?P\\b\\w+\\b)')\n" +">>> m = p.search( '(((( Lots of punctuation )))' )\n" +">>> m.group('word')\n" +"'Lots'\n" +">>> m.group(1)\n" +"'Lots'" +msgstr "" +">>> p = re.compile(r'(?P\\b\\w+\\b)')\n" +">>> m = p.search( '(((( Lots of punctuation )))' )\n" +">>> m.group('word')\n" +"'Lots'\n" +">>> m.group(1)\n" +"'Lots'" + +#: ../../howto/regex.rst:949 +msgid "" +"Additionally, you can retrieve named groups as a dictionary with :meth:`~re." +"Match.groupdict`::" +msgstr "" + +#: ../../howto/regex.rst:952 +msgid "" +">>> m = re.match(r'(?P\\w+) (?P\\w+)', 'Jane Doe')\n" +">>> m.groupdict()\n" +"{'first': 'Jane', 'last': 'Doe'}" +msgstr "" +">>> m = re.match(r'(?P\\w+) (?P\\w+)', 'Jane Doe')\n" +">>> m.groupdict()\n" +"{'first': 'Jane', 'last': 'Doe'}" + +#: ../../howto/regex.rst:956 +msgid "" +"Named groups are handy because they let you use easily remembered names, " +"instead of having to remember numbers. Here's an example RE from the :mod:" +"`imaplib` module::" +msgstr "" + +#: ../../howto/regex.rst:960 +msgid "" +"InternalDate = re.compile(r'INTERNALDATE \"'\n" +" r'(?P[ 123][0-9])-(?P[A-Z][a-z][a-z])-'\n" +" r'(?P[0-9][0-9][0-9][0-9])'\n" +" r' (?P[0-9][0-9]):(?P[0-9][0-9]):(?P[0-9][0-9])'\n" +" r' (?P[-+])(?P[0-9][0-9])(?P[0-9][0-9])'\n" +" r'\"')" +msgstr "" +"InternalDate = re.compile(r'INTERNALDATE \"'\n" +" r'(?P[ 123][0-9])-(?P[A-Z][a-z][a-z])-'\n" +" r'(?P[0-9][0-9][0-9][0-9])'\n" +" r' (?P[0-9][0-9]):(?P[0-9][0-9]):(?P[0-9][0-9])'\n" +" r' (?P[-+])(?P[0-9][0-9])(?P[0-9][0-9])'\n" +" r'\"')" + +#: ../../howto/regex.rst:967 +msgid "" +"It's obviously much easier to retrieve ``m.group('zonem')``, instead of " +"having to remember to retrieve group 9." +msgstr "" + +#: ../../howto/regex.rst:970 +msgid "" +"The syntax for backreferences in an expression such as ``(...)\\1`` refers " +"to the number of the group. There's naturally a variant that uses the group " +"name instead of the number. This is another Python extension: ``(?P=name)`` " +"indicates that the contents of the group called *name* should again be " +"matched at the current point. The regular expression for finding doubled " +"words, ``\\b(\\w+)\\s+\\1\\b`` can also be written as ``\\b(?" +"P\\w+)\\s+(?P=word)\\b``::" +msgstr "" + +#: ../../howto/regex.rst:977 +msgid "" +">>> p = re.compile(r'\\b(?P\\w+)\\s+(?P=word)\\b')\n" +">>> p.search('Paris in the the spring').group()\n" +"'the the'" +msgstr "" +">>> p = re.compile(r'\\b(?P\\w+)\\s+(?P=word)\\b')\n" +">>> p.search('Paris in the the spring').group()\n" +"'the the'" + +#: ../../howto/regex.rst:983 +msgid "Lookahead Assertions" +msgstr "" + +#: ../../howto/regex.rst:985 +msgid "" +"Another zero-width assertion is the lookahead assertion. Lookahead " +"assertions are available in both positive and negative form, and look like " +"this:" +msgstr "" + +#: ../../howto/regex.rst:988 +msgid "``(?=...)``" +msgstr "``(?=...)``" + +#: ../../howto/regex.rst:989 +msgid "" +"Positive lookahead assertion. This succeeds if the contained regular " +"expression, represented here by ``...``, successfully matches at the current " +"location, and fails otherwise. But, once the contained expression has been " +"tried, the matching engine doesn't advance at all; the rest of the pattern " +"is tried right where the assertion started." +msgstr "" + +#: ../../howto/regex.rst:995 +msgid "``(?!...)``" +msgstr "``(?!...)``" + +#: ../../howto/regex.rst:996 +msgid "" +"Negative lookahead assertion. This is the opposite of the positive " +"assertion; it succeeds if the contained expression *doesn't* match at the " +"current position in the string." +msgstr "" + +#: ../../howto/regex.rst:1000 +msgid "" +"To make this concrete, let's look at a case where a lookahead is useful. " +"Consider a simple pattern to match a filename and split it apart into a base " +"name and an extension, separated by a ``.``. For example, in ``news.rc``, " +"``news`` is the base name, and ``rc`` is the filename's extension." +msgstr "" + +#: ../../howto/regex.rst:1005 +msgid "The pattern to match this is quite simple:" +msgstr "" + +#: ../../howto/regex.rst:1007 +msgid "``.*[.].*$``" +msgstr "``.*[.].*$``" + +#: ../../howto/regex.rst:1009 +msgid "" +"Notice that the ``.`` needs to be treated specially because it's a " +"metacharacter, so it's inside a character class to only match that specific " +"character. Also notice the trailing ``$``; this is added to ensure that all " +"the rest of the string must be included in the extension. This regular " +"expression matches ``foo.bar`` and ``autoexec.bat`` and ``sendmail.cf`` and " +"``printers.conf``." +msgstr "" + +#: ../../howto/regex.rst:1016 +msgid "" +"Now, consider complicating the problem a bit; what if you want to match " +"filenames where the extension is not ``bat``? Some incorrect attempts:" +msgstr "" + +#: ../../howto/regex.rst:1019 +msgid "``.*[.][^b].*$``" +msgstr "``.*[.][^b].*$``" + +#: ../../howto/regex.rst:1021 +msgid "" +"The first attempt above tries to exclude ``bat`` by requiring that the first " +"character of the extension is not a ``b``. This is wrong, because the " +"pattern also doesn't match ``foo.bar``." +msgstr "" + +#: ../../howto/regex.rst:1025 +msgid "``.*[.]([^b]..|.[^a].|..[^t])$``" +msgstr "``.*[.]([^b]..|.[^a].|..[^t])$``" + +#: ../../howto/regex.rst:1027 +msgid "" +"The expression gets messier when you try to patch up the first solution by " +"requiring one of the following cases to match: the first character of the " +"extension isn't ``b``; the second character isn't ``a``; or the third " +"character isn't ``t``. This accepts ``foo.bar`` and rejects ``autoexec." +"bat``, but it requires a three-letter extension and won't accept a filename " +"with a two-letter extension such as ``sendmail.cf``. We'll complicate the " +"pattern again in an effort to fix it." +msgstr "" + +#: ../../howto/regex.rst:1035 +msgid "``.*[.]([^b].?.?|.[^a]?.?|..?[^t]?)$``" +msgstr "``.*[.]([^b].?.?|.[^a]?.?|..?[^t]?)$``" + +#: ../../howto/regex.rst:1037 +msgid "" +"In the third attempt, the second and third letters are all made optional in " +"order to allow matching extensions shorter than three characters, such as " +"``sendmail.cf``." +msgstr "" + +#: ../../howto/regex.rst:1041 +msgid "" +"The pattern's getting really complicated now, which makes it hard to read " +"and understand. Worse, if the problem changes and you want to exclude both " +"``bat`` and ``exe`` as extensions, the pattern would get even more " +"complicated and confusing." +msgstr "" + +#: ../../howto/regex.rst:1046 +msgid "A negative lookahead cuts through all this confusion:" +msgstr "" + +#: ../../howto/regex.rst:1048 +msgid "``.*[.](?!bat$)[^.]*$``" +msgstr "``.*[.](?!bat$)[^.]*$``" + +#: ../../howto/regex.rst:1050 +msgid "" +"The negative lookahead means: if the expression ``bat`` doesn't match at " +"this point, try the rest of the pattern; if ``bat$`` does match, the whole " +"pattern will fail. The trailing ``$`` is required to ensure that something " +"like ``sample.batch``, where the extension only starts with ``bat``, will be " +"allowed. The ``[^.]*`` makes sure that the pattern works when there are " +"multiple dots in the filename." +msgstr "" + +#: ../../howto/regex.rst:1057 +msgid "" +"Excluding another filename extension is now easy; simply add it as an " +"alternative inside the assertion. The following pattern excludes filenames " +"that end in either ``bat`` or ``exe``:" +msgstr "" + +#: ../../howto/regex.rst:1061 +msgid "``.*[.](?!bat$|exe$)[^.]*$``" +msgstr "``.*[.](?!bat$|exe$)[^.]*$``" + +#: ../../howto/regex.rst:1065 +msgid "Modifying Strings" +msgstr "" + +#: ../../howto/regex.rst:1067 +msgid "" +"Up to this point, we've simply performed searches against a static string. " +"Regular expressions are also commonly used to modify strings in various " +"ways, using the following pattern methods:" +msgstr "" + +#: ../../howto/regex.rst:1074 +msgid "``split()``" +msgstr "``split()``" + +#: ../../howto/regex.rst:1074 +msgid "Split the string into a list, splitting it wherever the RE matches" +msgstr "" + +#: ../../howto/regex.rst:1077 +msgid "``sub()``" +msgstr "``sub()``" + +#: ../../howto/regex.rst:1077 +msgid "" +"Find all substrings where the RE matches, and replace them with a different " +"string" +msgstr "" + +#: ../../howto/regex.rst:1080 +msgid "``subn()``" +msgstr "``subn()``" + +#: ../../howto/regex.rst:1080 +msgid "" +"Does the same thing as :meth:`!sub`, but returns the new string and the " +"number of replacements" +msgstr "" + +#: ../../howto/regex.rst:1087 +msgid "Splitting Strings" +msgstr "" + +#: ../../howto/regex.rst:1089 +msgid "" +"The :meth:`~re.Pattern.split` method of a pattern splits a string apart " +"wherever the RE matches, returning a list of the pieces. It's similar to " +"the :meth:`~str.split` method of strings but provides much more generality " +"in the delimiters that you can split by; string :meth:`!split` only supports " +"splitting by whitespace or by a fixed string. As you'd expect, there's a " +"module-level :func:`re.split` function, too." +msgstr "" + +#: ../../howto/regex.rst:1100 +msgid "" +"Split *string* by the matches of the regular expression. If capturing " +"parentheses are used in the RE, then their contents will also be returned as " +"part of the resulting list. If *maxsplit* is nonzero, at most *maxsplit* " +"splits are performed." +msgstr "" + +#: ../../howto/regex.rst:1105 +msgid "" +"You can limit the number of splits made, by passing a value for *maxsplit*. " +"When *maxsplit* is nonzero, at most *maxsplit* splits will be made, and the " +"remainder of the string is returned as the final element of the list. In " +"the following example, the delimiter is any sequence of non-alphanumeric " +"characters. ::" +msgstr "" + +#: ../../howto/regex.rst:1111 +msgid "" +">>> p = re.compile(r'\\W+')\n" +">>> p.split('This is a test, short and sweet, of split().')\n" +"['This', 'is', 'a', 'test', 'short', 'and', 'sweet', 'of', 'split', '']\n" +">>> p.split('This is a test, short and sweet, of split().', 3)\n" +"['This', 'is', 'a', 'test, short and sweet, of split().']" +msgstr "" +">>> p = re.compile(r'\\W+')\n" +">>> p.split('This is a test, short and sweet, of split().')\n" +"['This', 'is', 'a', 'test', 'short', 'and', 'sweet', 'of', 'split', '']\n" +">>> p.split('This is a test, short and sweet, of split().', 3)\n" +"['This', 'is', 'a', 'test, short and sweet, of split().']" + +#: ../../howto/regex.rst:1117 +msgid "" +"Sometimes you're not only interested in what the text between delimiters is, " +"but also need to know what the delimiter was. If capturing parentheses are " +"used in the RE, then their values are also returned as part of the list. " +"Compare the following calls::" +msgstr "" + +#: ../../howto/regex.rst:1122 +msgid "" +">>> p = re.compile(r'\\W+')\n" +">>> p2 = re.compile(r'(\\W+)')\n" +">>> p.split('This... is a test.')\n" +"['This', 'is', 'a', 'test', '']\n" +">>> p2.split('This... is a test.')\n" +"['This', '... ', 'is', ' ', 'a', ' ', 'test', '.', '']" +msgstr "" +">>> p = re.compile(r'\\W+')\n" +">>> p2 = re.compile(r'(\\W+)')\n" +">>> p.split('This... is a test.')\n" +"['This', 'is', 'a', 'test', '']\n" +">>> p2.split('This... is a test.')\n" +"['This', '... ', 'is', ' ', 'a', ' ', 'test', '.', '']" + +#: ../../howto/regex.rst:1129 +msgid "" +"The module-level function :func:`re.split` adds the RE to be used as the " +"first argument, but is otherwise the same. ::" +msgstr "" + +#: ../../howto/regex.rst:1132 +msgid "" +">>> re.split(r'[\\W]+', 'Words, words, words.')\n" +"['Words', 'words', 'words', '']\n" +">>> re.split(r'([\\W]+)', 'Words, words, words.')\n" +"['Words', ', ', 'words', ', ', 'words', '.', '']\n" +">>> re.split(r'[\\W]+', 'Words, words, words.', 1)\n" +"['Words', 'words, words.']" +msgstr "" +">>> re.split(r'[\\W]+', 'Words, words, words.')\n" +"['Words', 'words', 'words', '']\n" +">>> re.split(r'([\\W]+)', 'Words, words, words.')\n" +"['Words', ', ', 'words', ', ', 'words', '.', '']\n" +">>> re.split(r'[\\W]+', 'Words, words, words.', 1)\n" +"['Words', 'words, words.']" + +#: ../../howto/regex.rst:1141 +msgid "Search and Replace" +msgstr "" + +#: ../../howto/regex.rst:1143 +msgid "" +"Another common task is to find all the matches for a pattern, and replace " +"them with a different string. The :meth:`~re.Pattern.sub` method takes a " +"replacement value, which can be either a string or a function, and the " +"string to be processed." +msgstr "" + +#: ../../howto/regex.rst:1150 +msgid "" +"Returns the string obtained by replacing the leftmost non-overlapping " +"occurrences of the RE in *string* by the replacement *replacement*. If the " +"pattern isn't found, *string* is returned unchanged." +msgstr "" + +#: ../../howto/regex.rst:1154 +msgid "" +"The optional argument *count* is the maximum number of pattern occurrences " +"to be replaced; *count* must be a non-negative integer. The default value " +"of 0 means to replace all occurrences." +msgstr "" + +#: ../../howto/regex.rst:1158 +msgid "" +"Here's a simple example of using the :meth:`~re.Pattern.sub` method. It " +"replaces colour names with the word ``colour``::" +msgstr "" + +#: ../../howto/regex.rst:1161 +msgid "" +">>> p = re.compile('(blue|white|red)')\n" +">>> p.sub('colour', 'blue socks and red shoes')\n" +"'colour socks and colour shoes'\n" +">>> p.sub('colour', 'blue socks and red shoes', count=1)\n" +"'colour socks and red shoes'" +msgstr "" +">>> p = re.compile('(blue|white|red)')\n" +">>> p.sub('colour', 'blue socks and red shoes')\n" +"'colour socks and colour shoes'\n" +">>> p.sub('colour', 'blue socks and red shoes', count=1)\n" +"'colour socks and red shoes'" + +#: ../../howto/regex.rst:1167 +msgid "" +"The :meth:`~re.Pattern.subn` method does the same work, but returns a 2-" +"tuple containing the new string value and the number of replacements that " +"were performed::" +msgstr "" + +#: ../../howto/regex.rst:1170 +msgid "" +">>> p = re.compile('(blue|white|red)')\n" +">>> p.subn('colour', 'blue socks and red shoes')\n" +"('colour socks and colour shoes', 2)\n" +">>> p.subn('colour', 'no colours at all')\n" +"('no colours at all', 0)" +msgstr "" +">>> p = re.compile('(blue|white|red)')\n" +">>> p.subn('colour', 'blue socks and red shoes')\n" +"('colour socks and colour shoes', 2)\n" +">>> p.subn('colour', 'no colours at all')\n" +"('no colours at all', 0)" + +#: ../../howto/regex.rst:1176 +msgid "" +"Empty matches are replaced only when they're not adjacent to a previous " +"empty match. ::" +msgstr "" + +#: ../../howto/regex.rst:1179 +msgid "" +">>> p = re.compile('x*')\n" +">>> p.sub('-', 'abxd')\n" +"'-a-b--d-'" +msgstr "" +">>> p = re.compile('x*')\n" +">>> p.sub('-', 'abxd')\n" +"'-a-b--d-'" + +#: ../../howto/regex.rst:1183 +msgid "" +"If *replacement* is a string, any backslash escapes in it are processed. " +"That is, ``\\n`` is converted to a single newline character, ``\\r`` is " +"converted to a carriage return, and so forth. Unknown escapes such as " +"``\\&`` are left alone. Backreferences, such as ``\\6``, are replaced with " +"the substring matched by the corresponding group in the RE. This lets you " +"incorporate portions of the original text in the resulting replacement " +"string." +msgstr "" + +#: ../../howto/regex.rst:1190 +msgid "" +"This example matches the word ``section`` followed by a string enclosed in " +"``{``, ``}``, and changes ``section`` to ``subsection``::" +msgstr "" + +#: ../../howto/regex.rst:1193 +msgid "" +">>> p = re.compile('section{ ( [^}]* ) }', re.VERBOSE)\n" +">>> p.sub(r'subsection{\\1}','section{First} section{second}')\n" +"'subsection{First} subsection{second}'" +msgstr "" +">>> p = re.compile('section{ ( [^}]* ) }', re.VERBOSE)\n" +">>> p.sub(r'subsection{\\1}','section{First} section{second}')\n" +"'subsection{First} subsection{second}'" + +#: ../../howto/regex.rst:1197 +msgid "" +"There's also a syntax for referring to named groups as defined by the ``(?" +"P...)`` syntax. ``\\g`` will use the substring matched by the " +"group named ``name``, and ``\\g`` uses the corresponding group " +"number. ``\\g<2>`` is therefore equivalent to ``\\2``, but isn't ambiguous " +"in a replacement string such as ``\\g<2>0``. (``\\20`` would be interpreted " +"as a reference to group 20, not a reference to group 2 followed by the " +"literal character ``'0'``.) The following substitutions are all equivalent, " +"but use all three variations of the replacement string. ::" +msgstr "" + +#: ../../howto/regex.rst:1206 +msgid "" +">>> p = re.compile('section{ (?P [^}]* ) }', re.VERBOSE)\n" +">>> p.sub(r'subsection{\\1}','section{First}')\n" +"'subsection{First}'\n" +">>> p.sub(r'subsection{\\g<1>}','section{First}')\n" +"'subsection{First}'\n" +">>> p.sub(r'subsection{\\g}','section{First}')\n" +"'subsection{First}'" +msgstr "" +">>> p = re.compile('section{ (?P [^}]* ) }', re.VERBOSE)\n" +">>> p.sub(r'subsection{\\1}','section{First}')\n" +"'subsection{First}'\n" +">>> p.sub(r'subsection{\\g<1>}','section{First}')\n" +"'subsection{First}'\n" +">>> p.sub(r'subsection{\\g}','section{First}')\n" +"'subsection{First}'" + +#: ../../howto/regex.rst:1214 +msgid "" +"*replacement* can also be a function, which gives you even more control. If " +"*replacement* is a function, the function is called for every non-" +"overlapping occurrence of *pattern*. On each call, the function is passed " +"a :ref:`match object ` argument for the match and can use " +"this information to compute the desired replacement string and return it." +msgstr "" + +#: ../../howto/regex.rst:1220 +msgid "" +"In the following example, the replacement function translates decimals into " +"hexadecimal::" +msgstr "" + +#: ../../howto/regex.rst:1223 +msgid "" +">>> def hexrepl(match):\n" +"... \"Return the hex string for a decimal number\"\n" +"... value = int(match.group())\n" +"... return hex(value)\n" +"...\n" +">>> p = re.compile(r'\\d+')\n" +">>> p.sub(hexrepl, 'Call 65490 for printing, 49152 for user code.')\n" +"'Call 0xffd2 for printing, 0xc000 for user code.'" +msgstr "" + +#: ../../howto/regex.rst:1232 +msgid "" +"When using the module-level :func:`re.sub` function, the pattern is passed " +"as the first argument. The pattern may be provided as an object or as a " +"string; if you need to specify regular expression flags, you must either use " +"a pattern object as the first parameter, or use embedded modifiers in the " +"pattern string, e.g. ``sub(\"(?i)b+\", \"x\", \"bbbb BBBB\")`` returns ``'x " +"x'``." +msgstr "" + +#: ../../howto/regex.rst:1240 +msgid "Common Problems" +msgstr "" + +#: ../../howto/regex.rst:1242 +msgid "" +"Regular expressions are a powerful tool for some applications, but in some " +"ways their behaviour isn't intuitive and at times they don't behave the way " +"you may expect them to. This section will point out some of the most common " +"pitfalls." +msgstr "" + +#: ../../howto/regex.rst:1248 +msgid "Use String Methods" +msgstr "" + +#: ../../howto/regex.rst:1250 +msgid "" +"Sometimes using the :mod:`re` module is a mistake. If you're matching a " +"fixed string, or a single character class, and you're not using any :mod:" +"`re` features such as the :const:`~re.IGNORECASE` flag, then the full power " +"of regular expressions may not be required. Strings have several methods for " +"performing operations with fixed strings and they're usually much faster, " +"because the implementation is a single small C loop that's been optimized " +"for the purpose, instead of the large, more generalized regular expression " +"engine." +msgstr "" + +#: ../../howto/regex.rst:1258 +msgid "" +"One example might be replacing a single fixed string with another one; for " +"example, you might replace ``word`` with ``deed``. :func:`re.sub` seems " +"like the function to use for this, but consider the :meth:`~str.replace` " +"method. Note that :meth:`!replace` will also replace ``word`` inside words, " +"turning ``swordfish`` into ``sdeedfish``, but the naive RE ``word`` would " +"have done that, too. (To avoid performing the substitution on parts of " +"words, the pattern would have to be ``\\bword\\b``, in order to require that " +"``word`` have a word boundary on either side. This takes the job beyond :" +"meth:`!replace`'s abilities.)" +msgstr "" + +#: ../../howto/regex.rst:1267 +msgid "" +"Another common task is deleting every occurrence of a single character from " +"a string or replacing it with another single character. You might do this " +"with something like ``re.sub('\\n', ' ', S)``, but :meth:`~str.translate` is " +"capable of doing both tasks and will be faster than any regular expression " +"operation can be." +msgstr "" + +#: ../../howto/regex.rst:1273 +msgid "" +"In short, before turning to the :mod:`re` module, consider whether your " +"problem can be solved with a faster and simpler string method." +msgstr "" + +#: ../../howto/regex.rst:1278 +msgid "match() versus search()" +msgstr "" + +#: ../../howto/regex.rst:1280 +msgid "" +"The :func:`~re.match` function only checks if the RE matches at the " +"beginning of the string while :func:`~re.search` will scan forward through " +"the string for a match. It's important to keep this distinction in mind. " +"Remember, :func:`!match` will only report a successful match which will " +"start at 0; if the match wouldn't start at zero, :func:`!match` will *not* " +"report it. ::" +msgstr "" + +#: ../../howto/regex.rst:1286 +msgid "" +">>> print(re.match('super', 'superstition').span())\n" +"(0, 5)\n" +">>> print(re.match('super', 'insuperable'))\n" +"None" +msgstr "" +">>> print(re.match('super', 'superstition').span())\n" +"(0, 5)\n" +">>> print(re.match('super', 'insuperable'))\n" +"None" + +#: ../../howto/regex.rst:1291 +msgid "" +"On the other hand, :func:`~re.search` will scan forward through the string, " +"reporting the first match it finds. ::" +msgstr "" + +#: ../../howto/regex.rst:1294 +msgid "" +">>> print(re.search('super', 'superstition').span())\n" +"(0, 5)\n" +">>> print(re.search('super', 'insuperable').span())\n" +"(2, 7)" +msgstr "" +">>> print(re.search('super', 'superstition').span())\n" +"(0, 5)\n" +">>> print(re.search('super', 'insuperable').span())\n" +"(2, 7)" + +#: ../../howto/regex.rst:1299 +msgid "" +"Sometimes you'll be tempted to keep using :func:`re.match`, and just add ``." +"*`` to the front of your RE. Resist this temptation and use :func:`re." +"search` instead. The regular expression compiler does some analysis of REs " +"in order to speed up the process of looking for a match. One such analysis " +"figures out what the first character of a match must be; for example, a " +"pattern starting with ``Crow`` must match starting with a ``'C'``. The " +"analysis lets the engine quickly scan through the string looking for the " +"starting character, only trying the full match if a ``'C'`` is found." +msgstr "" + +#: ../../howto/regex.rst:1308 +msgid "" +"Adding ``.*`` defeats this optimization, requiring scanning to the end of " +"the string and then backtracking to find a match for the rest of the RE. " +"Use :func:`re.search` instead." +msgstr "" + +#: ../../howto/regex.rst:1314 +msgid "Greedy versus Non-Greedy" +msgstr "" + +#: ../../howto/regex.rst:1316 +msgid "" +"When repeating a regular expression, as in ``a*``, the resulting action is " +"to consume as much of the pattern as possible. This fact often bites you " +"when you're trying to match a pair of balanced delimiters, such as the angle " +"brackets surrounding an HTML tag. The naive pattern for matching a single " +"HTML tag doesn't work because of the greedy nature of ``.*``. ::" +msgstr "" + +#: ../../howto/regex.rst:1322 +msgid "" +">>> s = 'Title'\n" +">>> len(s)\n" +"32\n" +">>> print(re.match('<.*>', s).span())\n" +"(0, 32)\n" +">>> print(re.match('<.*>', s).group())\n" +"Title" +msgstr "" +">>> s = 'Title'\n" +">>> len(s)\n" +"32\n" +">>> print(re.match('<.*>', s).span())\n" +"(0, 32)\n" +">>> print(re.match('<.*>', s).group())\n" +"Title" + +#: ../../howto/regex.rst:1330 +msgid "" +"The RE matches the ``'<'`` in ``''``, and the ``.*`` consumes the rest " +"of the string. There's still more left in the RE, though, and the ``>`` " +"can't match at the end of the string, so the regular expression engine has " +"to backtrack character by character until it finds a match for the ``>``. " +"The final match extends from the ``'<'`` in ``''`` to the ``'>'`` in " +"``''``, which isn't what you want." +msgstr "" + +#: ../../howto/regex.rst:1337 +msgid "" +"In this case, the solution is to use the non-greedy quantifiers ``*?``, ``+?" +"``, ``??``, or ``{m,n}?``, which match as *little* text as possible. In the " +"above example, the ``'>'`` is tried immediately after the first ``'<'`` " +"matches, and when it fails, the engine advances a character at a time, " +"retrying the ``'>'`` at every step. This produces just the right result::" +msgstr "" + +#: ../../howto/regex.rst:1343 +msgid "" +">>> print(re.match('<.*?>', s).group())\n" +"" +msgstr "" +">>> print(re.match('<.*?>', s).group())\n" +"" + +#: ../../howto/regex.rst:1346 +msgid "" +"(Note that parsing HTML or XML with regular expressions is painful. Quick-" +"and-dirty patterns will handle common cases, but HTML and XML have special " +"cases that will break the obvious regular expression; by the time you've " +"written a regular expression that handles all of the possible cases, the " +"patterns will be *very* complicated. Use an HTML or XML parser module for " +"such tasks.)" +msgstr "" + +#: ../../howto/regex.rst:1354 +msgid "Using re.VERBOSE" +msgstr "" + +#: ../../howto/regex.rst:1356 +msgid "" +"By now you've probably noticed that regular expressions are a very compact " +"notation, but they're not terribly readable. REs of moderate complexity can " +"become lengthy collections of backslashes, parentheses, and metacharacters, " +"making them difficult to read and understand." +msgstr "" + +#: ../../howto/regex.rst:1361 +msgid "" +"For such REs, specifying the :const:`re.VERBOSE` flag when compiling the " +"regular expression can be helpful, because it allows you to format the " +"regular expression more clearly." +msgstr "" + +#: ../../howto/regex.rst:1365 +msgid "" +"The ``re.VERBOSE`` flag has several effects. Whitespace in the regular " +"expression that *isn't* inside a character class is ignored. This means " +"that an expression such as ``dog | cat`` is equivalent to the less readable " +"``dog|cat``, but ``[a b]`` will still match the characters ``'a'``, ``'b'``, " +"or a space. In addition, you can also put comments inside a RE; comments " +"extend from a ``#`` character to the next newline. When used with triple-" +"quoted strings, this enables REs to be formatted more neatly::" +msgstr "" + +#: ../../howto/regex.rst:1373 +msgid "" +"pat = re.compile(r\"\"\"\n" +" \\s* # Skip leading whitespace\n" +" (?P
[^:]+) # Header name\n" +" \\s* : # Whitespace, and a colon\n" +" (?P.*?) # The header's value -- *? used to\n" +" # lose the following trailing whitespace\n" +" \\s*$ # Trailing whitespace to end-of-line\n" +"\"\"\", re.VERBOSE)" +msgstr "" + +#: ../../howto/regex.rst:1382 +msgid "This is far more readable than::" +msgstr "" + +#: ../../howto/regex.rst:1384 +msgid "pat = re.compile(r\"\\s*(?P
[^:]+)\\s*:(?P.*?)\\s*$\")" +msgstr "pat = re.compile(r\"\\s*(?P
[^:]+)\\s*:(?P.*?)\\s*$\")" + +#: ../../howto/regex.rst:1388 +msgid "Feedback" +msgstr "" + +#: ../../howto/regex.rst:1390 +msgid "" +"Regular expressions are a complicated topic. Did this document help you " +"understand them? Were there parts that were unclear, or Problems you " +"encountered that weren't covered here? If so, please send suggestions for " +"improvements to the author." +msgstr "" + +#: ../../howto/regex.rst:1395 +msgid "" +"The most complete book on regular expressions is almost certainly Jeffrey " +"Friedl's Mastering Regular Expressions, published by O'Reilly. " +"Unfortunately, it exclusively concentrates on Perl and Java's flavours of " +"regular expressions, and doesn't contain any Python material at all, so it " +"won't be useful as a reference for programming in Python. (The first " +"edition covered Python's now-removed :mod:`!regex` module, which won't help " +"you much.) Consider checking it out from your library." +msgstr "" diff --git a/howto/remote_debugging.po b/howto/remote_debugging.po index 8025a6dee7..80233b9087 100644 --- a/howto/remote_debugging.po +++ b/howto/remote_debugging.po @@ -1,1265 +1,1265 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# FIRST AUTHOR , YEAR. -# -#, fuzzy -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-13 00:14+0000\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language-Team: LANGUAGE \n" -"Language: zh_TW\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=UTF-8\n" -"Content-Transfer-Encoding: 8bit\n" - -#: ../../howto/remote_debugging.rst:4 -msgid "Remote debugging attachment protocol" -msgstr "遠端偵錯附加協定" - -#: ../../howto/remote_debugging.rst:6 -msgid "" -"This protocol enables external tools to attach to a running CPython process " -"and execute Python code remotely." -msgstr "此協定使外部工具能夠附加到正在執行的 CPython 行程並遠端執行 Python 程式碼。" - -#: ../../howto/remote_debugging.rst:9 -msgid "" -"Most platforms require elevated privileges to attach to another Python " -"process." -msgstr "大多數平台上都會需要更高的權限才能附加到另一個 Python 行程。" - -#: ../../howto/remote_debugging.rst:14 -msgid "Permission requirements" -msgstr "權限需求" - -#: ../../howto/remote_debugging.rst:16 -msgid "" -"Attaching to a running Python process for remote debugging requires elevated " -"privileges on most platforms. The specific requirements and troubleshooting " -"steps depend on your operating system:" -msgstr "" -"在大多數平台上，附加到正在執行的 Python 行程進行遠端偵錯需要更高的權限。具體要求和疑難排" -"解步驟會取決於你的作業系統：" - -#: ../../howto/remote_debugging.rst:21 -msgid "Linux" -msgstr "Linux" - -#: ../../howto/remote_debugging.rst:22 -msgid "" -"The tracer process must have the ``CAP_SYS_PTRACE`` capability or equivalent " -"privileges. You can only trace processes you own and can signal. Tracing may " -"fail if the process is already being traced, or if it is running with set-" -"user-ID or set-group-ID. Security modules like Yama may further restrict " -"tracing." -msgstr "" -"執行追蹤的行程 (tracer process) 必須具有 ``CAP_SYS_PTRACE`` 功能或同等權限。" -"你只能追蹤你擁有且可以發送訊號的行程。如果行程已經被追蹤，或者它以 set-user-ID 或 " -"set-group-ID 執行，則追蹤可能會失敗。像 Yama 這樣的安全模組可能會進一步限制追蹤。" - -#: ../../howto/remote_debugging.rst:28 -msgid "To temporarily relax ptrace restrictions (until reboot), run:" -msgstr "要暫時放寬 ptrace 限制（直到重新開機），請執行：" - -#: ../../howto/remote_debugging.rst:30 -msgid "``echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope``" -msgstr "``echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope``" - -#: ../../howto/remote_debugging.rst:34 -msgid "" -"Disabling ``ptrace_scope`` reduces system hardening and should only be done " -"in trusted environments." -msgstr "停用 ``ptrace_scope`` 會降低系統安全性，應僅在受信任的環境中執行此操作。" - -#: ../../howto/remote_debugging.rst:37 -msgid "" -"If running inside a container, use ``--cap-add=SYS_PTRACE`` or ``--" -"privileged``, and run as root if needed." -msgstr "" -"如果在容器內執行，請使用 ``--cap-add=SYS_PTRACE`` 或 ``--privileged``，" -"並在需要時以 root 身分執行。" - -#: ../../howto/remote_debugging.rst:40 -msgid "Try re-running the command with elevated privileges:" -msgstr "嘗試使用提升後的權限重新執行命令：" - -#: ../../howto/remote_debugging.rst:42 -msgid "``sudo -E !!``" -msgstr "``sudo -E !!``" - -#: ../../howto/remote_debugging.rst:46 -msgid "macOS" -msgstr "macOS" - -#: ../../howto/remote_debugging.rst:47 -msgid "" -"To attach to another process, you typically need to run your debugging tool " -"with elevated privileges. This can be done by using ``sudo`` or running as " -"root." -msgstr "" -"要附加到另一個行程，你通常需要以提升過的權限來執行偵錯工具。這可以透過使用 ``sudo`` " -"或以 root 身分執行來完成。" - -#: ../../howto/remote_debugging.rst:51 -msgid "" -"Even when attaching to processes you own, macOS may block debugging unless " -"the debugger is run with root privileges due to system security restrictions." -msgstr "" -"即使附加到你擁有的行程，macOS 也可能會阻止偵錯，除非偵錯器以 root 權限執行，這是由於系統安全限制。" - -#: ../../howto/remote_debugging.rst:56 -msgid "Windows" -msgstr "Windows" - -#: ../../howto/remote_debugging.rst:57 -msgid "" -"To attach to another process, you usually need to run your debugging tool " -"with administrative privileges. Start the command prompt or terminal as " -"Administrator." -msgstr "" -"要附加到另一個行程，你通常需要以系統管理員權限執行偵錯工具。以系統管理員身分啟動命令提示字元或終端機。" - -#: ../../howto/remote_debugging.rst:61 -msgid "" -"Some processes may still be inaccessible even with Administrator rights, " -"unless you have the ``SeDebugPrivilege`` privilege enabled." -msgstr "即使具有系統管理員權限，某些行程仍可能無法存取，除非你啟用了 ``SeDebugPrivilege`` 權限。" - -#: ../../howto/remote_debugging.rst:64 -msgid "" -"To resolve file or folder access issues, adjust the security permissions:" -msgstr "要解決檔案或資料夾存取問題，請調整安全權限：" - -#: ../../howto/remote_debugging.rst:66 -msgid "Right-click the file or folder and select **Properties**." -msgstr "右鍵點擊檔案或資料夾並選擇 **Properties**。" - -#: ../../howto/remote_debugging.rst:67 -msgid "Go to the **Security** tab to view users and groups with access." -msgstr "前往 **Security** 分頁以檢視具有存取權限的使用者和群組。" - -#: ../../howto/remote_debugging.rst:68 -msgid "Click **Edit** to modify permissions." -msgstr "點擊 **Edit** 以修改權限。" - -#: ../../howto/remote_debugging.rst:69 -msgid "Select your user account." -msgstr "選擇你的使用者帳戶。" - -#: ../../howto/remote_debugging.rst:70 -msgid "In **Permissions**, check **Read** or **Full control** as needed." -msgstr "在 **Permissions** 中，視需要勾選 **Read** 或 **Full control**。" - -#: ../../howto/remote_debugging.rst:71 -msgid "Click **Apply**, then **OK** to confirm." -msgstr "點擊 **Apply**，然後點擊 **OK** 來確認。" - -#: ../../howto/remote_debugging.rst:76 -msgid "" -"Ensure you've satisfied all :ref:`permission-requirements` before proceeding." -msgstr "在繼續之前，請確保你已滿足所有 :ref:`permission-requirements`。" - -#: ../../howto/remote_debugging.rst:78 -msgid "" -"This section describes the low-level protocol that enables external tools to " -"inject and execute a Python script within a running CPython process." -msgstr "本節描述了低階協定，使外部工具能夠在正在執行的 CPython 行程中注入並執行 Python 腳本。" - -#: ../../howto/remote_debugging.rst:81 -msgid "" -"This mechanism forms the basis of the :func:`sys.remote_exec` function, " -"which instructs a remote Python process to execute a ``.py`` file. However, " -"this section does not document the usage of that function. Instead, it " -"provides a detailed explanation of the underlying protocol, which takes as " -"input the ``pid`` of a target Python process and the path to a Python source " -"file to be executed. This information supports independent reimplementation " -"of the protocol, regardless of programming language." -msgstr "" -"此機制構成了 :func:`sys.remote_exec` 函式的基礎，該函式指示遠端 Python 行程執行 ``.py`` " -"檔案。但本節不記錄該函式的用法，而是提供底層協定的詳細說明，該協定以目標 Python 行程的 " -"``pid`` 和要執行的 Python 原始檔路徑作為輸入。此資訊支援該協定的獨立重新實作，無論使用何種程式語言。" - -#: ../../howto/remote_debugging.rst:91 -msgid "" -"The execution of the injected script depends on the interpreter reaching a " -"safe evaluation point. As a result, execution may be delayed depending on " -"the runtime state of the target process." -msgstr "" -"注入腳本的執行取決於直譯器是否到達安全執行點 (safe evaluation point)。因此，執行可能會根據" -"目標行程的 runtime 狀態而延遲。" - -#: ../../howto/remote_debugging.rst:95 -msgid "" -"Once injected, the script is executed by the interpreter within the target " -"process the next time a safe evaluation point is reached. This approach " -"enables remote execution capabilities without modifying the behavior or " -"structure of the running Python application." -msgstr "" -"一旦注入，腳本將在下次到達安全執行點時會由目標行程內的直譯器執行。這種方法使遠端執行功能成為可能，" -"而不需修改正在執行的 Python 應用程式的行為或結構。" - -#: ../../howto/remote_debugging.rst:100 -msgid "" -"Subsequent sections provide a step-by-step description of the protocol, " -"including techniques for locating interpreter structures in memory, safely " -"accessing internal fields, and triggering code execution. Platform-specific " -"variations are noted where applicable, and example implementations are " -"included to clarify each operation." -msgstr "" -"後續章節提供了協定的逐步描述，包括在記憶體中定位直譯器結構、安全存取內部欄位以及觸發程式碼執行的技術。" -"在適用的情況下會註明平台特有的變化，並包含範例實作以闡明每個操作。" - -#: ../../howto/remote_debugging.rst:107 -msgid "Locating the PyRuntime structure" -msgstr "定位 PyRuntime 結構" - -#: ../../howto/remote_debugging.rst:109 -msgid "" -"CPython places the ``PyRuntime`` structure in a dedicated binary section to " -"help external tools find it at runtime. The name and format of this section " -"vary by platform. For example, ``.PyRuntime`` is used on ELF systems, and " -"``__DATA,__PyRuntime`` is used on macOS. Tools can find the offset of this " -"structure by examining the binary on disk." -msgstr "" -"CPython 將 ``PyRuntime`` 結構放置在專用的二進位區段（section）中，以幫助外部工具在 " -"runtime 找到它。此區段的名稱和格式因平台而異。例如，ELF 系統使用 ``.PyRuntime``、macOS " -"使用 ``__DATA,__PyRuntime``。工具可以透過檢查磁碟上的二進位檔案來找到此結構的偏移量。" - -#: ../../howto/remote_debugging.rst:115 -msgid "" -"The ``PyRuntime`` structure contains CPython’s global interpreter state and " -"provides access to other internal data, including the list of interpreters, " -"thread states, and debugger support fields." -msgstr "" -"``PyRuntime`` 結構包含 CPython 的全域直譯器狀態，並可存取其他內部資料，" -"包括直譯器清單、執行緒狀態和偵錯器支援欄位。" - -#: ../../howto/remote_debugging.rst:119 -msgid "" -"To work with a remote Python process, a debugger must first find the memory " -"address of the ``PyRuntime`` structure in the target process. This address " -"can’t be hardcoded or calculated from a symbol name, because it depends on " -"where the operating system loaded the binary." -msgstr "" -"要與遠端 Python 行程協作，偵錯器必須首先找到目標行程中 ``PyRuntime`` 結構的記憶體位址。" -"此位址無法寫死或從符號名稱計算出，因為它取決於作業系統載入二進位檔案的位置。" - -#: ../../howto/remote_debugging.rst:124 -msgid "" -"The method for finding ``PyRuntime`` depends on the platform, but the steps " -"are the same in general:" -msgstr "尋找 ``PyRuntime`` 的方法取決於平台，但步驟大致相同：" - -#: ../../howto/remote_debugging.rst:127 -msgid "" -"Find the base address where the Python binary or shared library was loaded " -"in the target process." -msgstr "找到目標行程中 Python 二進位檔案或共享函式庫被載入的基底位址。" - -#: ../../howto/remote_debugging.rst:129 -msgid "" -"Use the on-disk binary to locate the offset of the ``.PyRuntime`` section." -msgstr "使用磁碟上的二進位檔案來定位 ``.PyRuntime`` 區段的偏移量。" - -#: ../../howto/remote_debugging.rst:130 -msgid "" -"Add the section offset to the base address to compute the address in memory." -msgstr "將區段偏移量加到基底位址以計算記憶體中的位址。" - -#: ../../howto/remote_debugging.rst:132 -msgid "" -"The sections below explain how to do this on each supported platform and " -"include example code." -msgstr "以下各節說明如何在每個支援的平台上執行此操作，並包含範例程式碼。" - -#: ../../howto/remote_debugging.rst:136 -msgid "Linux (ELF)" -msgstr "Linux (ELF)" - -#: ../../howto/remote_debugging.rst:137 -msgid "To find the ``PyRuntime`` structure on Linux:" -msgstr "在 Linux 上尋找 ``PyRuntime`` 結構：" - -#: ../../howto/remote_debugging.rst:139 -msgid "" -"Read the process’s memory map (for example, ``/proc//maps``) to find " -"the address where the Python executable or ``libpython`` was loaded." -msgstr "" -"讀取行程的記憶體對映（例如 ``/proc//maps``）以找到 Python 可執行檔位址或 " -"``libpython`` 被載入的位址。" - -#: ../../howto/remote_debugging.rst:141 -msgid "" -"Parse the ELF section headers in the binary to get the offset of the ``." -"PyRuntime`` section." -msgstr "剖析二進位檔案中的 ELF 區段標頭以取得 ``.PyRuntime`` 區段的偏移量。" - -#: ../../howto/remote_debugging.rst:143 -msgid "" -"Add that offset to the base address from step 1 to get the memory address of " -"``PyRuntime``." -msgstr "將該偏移量加到步驟 1 的基底位址以取得 ``PyRuntime`` 的記憶體位址。" - -#: ../../howto/remote_debugging.rst:146 ../../howto/remote_debugging.rst:208 -#: ../../howto/remote_debugging.rst:278 ../../howto/remote_debugging.rst:547 -msgid "The following is an example implementation::" -msgstr "以下是一個範例實作： ::" - -#: ../../howto/remote_debugging.rst:148 -msgid "" -"def find_py_runtime_linux(pid: int) -> int:\n" -" # Step 1: Try to find the Python executable in memory\n" -" binary_path, base_address = find_mapped_binary(\n" -" pid, name_contains=\"python\"\n" -" )\n" -"\n" -" # Step 2: Fallback to shared library if executable is not found\n" -" if binary_path is None:\n" -" binary_path, base_address = find_mapped_binary(\n" -" pid, name_contains=\"libpython\"\n" -" )\n" -"\n" -" # Step 3: Parse ELF headers to get .PyRuntime section offset\n" -" section_offset = parse_elf_section_offset(\n" -" binary_path, \".PyRuntime\"\n" -" )\n" -"\n" -" # Step 4: Compute PyRuntime address in memory\n" -" return base_address + section_offset" -msgstr "" -"def find_py_runtime_linux(pid: int) -> int:\n" -" # 步驟 1：嘗試在記憶體中找到 Python 可執行檔\n" -" binary_path, base_address = find_mapped_binary(\n" -" pid, name_contains=\"python\"\n" -" )\n" -"\n" -" # 步驟 2：如果找不到可執行檔，則改用共享函式庫\n" -" if binary_path is None:\n" -" binary_path, base_address = find_mapped_binary(\n" -" pid, name_contains=\"libpython\"\n" -" )\n" -"\n" -" # 步驟 3：剖析 ELF 標頭以取得 .PyRuntime 區段偏移量\n" -" section_offset = parse_elf_section_offset(\n" -" binary_path, \".PyRuntime\"\n" -" )\n" -"\n" -" # 步驟 4：計算 PyRuntime 在記憶體中的位址\n" -" return base_address + section_offset" - -#: ../../howto/remote_debugging.rst:169 -msgid "" -"On Linux systems, there are two main approaches to read memory from another " -"process. The first is through the ``/proc`` filesystem, specifically by " -"reading from ``/proc/[pid]/mem`` which provides direct access to the " -"process's memory. This requires appropriate permissions - either being the " -"same user as the target process or having root access. The second approach " -"is using the ``process_vm_readv()`` system call which provides a more " -"efficient way to copy memory between processes. While ptrace's " -"``PTRACE_PEEKTEXT`` operation can also be used to read memory, it is " -"significantly slower as it only reads one word at a time and requires " -"multiple context switches between the tracer and tracee processes." -msgstr "" -"在 Linux 系統上，有兩種主要方法可以從另一個行程讀取記憶體。第一種是透過 ``/proc`` " -"檔案系統，特別是從 ``/proc/[pid]/mem`` 讀取，這提供了對行程記憶體的直接存取。這需要" -"適當的權限 - 要麼與目標行程是同一使用者，要麼就要擁有 root 存取權限。第二種方法是使用 " -"``process_vm_readv()`` 系統呼叫，它提供了在行程之間複製記憶體的更有效方式。雖然 ptrace " -"的 ``PTRACE_PEEKTEXT`` 操作也可以用來讀取記憶體，但它明顯較慢，因為它一次只讀取一個字，" -"並且需要追蹤器和被追蹤行程之間的多次情境切換。" - -#: ../../howto/remote_debugging.rst:180 -msgid "" -"For parsing ELF sections, the process involves reading and interpreting the " -"ELF file format structures from the binary file on disk. The ELF header " -"contains a pointer to the section header table. Each section header contains " -"metadata about a section including its name (stored in a separate string " -"table), offset, and size. To find a specific section like .PyRuntime, you " -"need to walk through these headers and match the section name. The section " -"header then provides the offset where that section exists in the file, which " -"can be used to calculate its runtime address when the binary is loaded into " -"memory." -msgstr "" -"對於剖析 ELF 區段，該過程涉及從磁碟上的二進位檔案讀取並解釋 ELF 檔案格式結構。ELF" -"標頭包含指向區段標頭表的指標。每個區段標頭包含關於區段的中介資料，包括其名稱（儲存在單獨" -"的字串表中）、偏移量和大小。要找到像 .PyRuntime 這樣的特定區段，你需要遍歷這些標頭並匹" -"配區段名稱。然後區段標頭會提供該區段在檔案中存在的偏移量，當二進位檔案載入到記憶體時，" -"可以用它來計算 runtime 位址。" - -#: ../../howto/remote_debugging.rst:189 -msgid "" -"You can read more about the ELF file format in the `ELF specification " -"`_." -msgstr "" -"你可以在 `ELF 規範 `_\\ " -"中閱讀更多關於 ELF 檔案格式的資訊。" - -#: ../../howto/remote_debugging.rst:194 -msgid "macOS (Mach-O)" -msgstr "macOS (Mach-O)" - -#: ../../howto/remote_debugging.rst:195 -msgid "To find the ``PyRuntime`` structure on macOS:" -msgstr "在 macOS 上找 ``PyRuntime`` 結構：" - -#: ../../howto/remote_debugging.rst:197 -msgid "" -"Call ``task_for_pid()`` to get the ``mach_port_t`` task port for the target " -"process. This handle is needed to read memory using APIs like " -"``mach_vm_read_overwrite`` and ``mach_vm_region``." -msgstr "" -"呼叫 ``task_for_pid()`` 以取得目標行程的 ``mach_port_t`` 任務埠 (task port)。" -"此控制代碼 (handle) 用於使用像 ``mach_vm_read_overwrite`` 和 ``mach_vm_region`` " -"這樣的 API 來讀取記憶體。" - -#: ../../howto/remote_debugging.rst:200 -msgid "" -"Scan the memory regions to find the one containing the Python executable or " -"``libpython``." -msgstr "掃描記憶體區域以找到包含 Python 可執行檔或 ``libpython`` 的區域。" - -#: ../../howto/remote_debugging.rst:202 -msgid "" -"Load the binary file from disk and parse the Mach-O headers to find the " -"section named ``PyRuntime`` in the ``__DATA`` segment. On macOS, symbol " -"names are automatically prefixed with an underscore, so the ``PyRuntime`` " -"symbol appears as ``_PyRuntime`` in the symbol table, but the section name " -"is not affected." -msgstr "" -"從磁碟載入二進位檔案並剖析 Mach-O 標頭以找到 ``__DATA`` 程式段（segment）中名為 " -"``PyRuntime`` 的區段。在 macOS 上，符號名稱會自動加上底線前綴，因此 ``PyRuntime`` " -"符號在符號表中顯示為 ``_PyRuntime``，但區段名稱不受影響。" - -#: ../../howto/remote_debugging.rst:210 -msgid "" -"def find_py_runtime_macos(pid: int) -> int:\n" -" # Step 1: Get access to the process's memory\n" -" handle = get_memory_access_handle(pid)\n" -"\n" -" # Step 2: Try to find the Python executable in memory\n" -" binary_path, base_address = find_mapped_binary(\n" -" handle, name_contains=\"python\"\n" -" )\n" -"\n" -" # Step 3: Fallback to libpython if the executable is not found\n" -" if binary_path is None:\n" -" binary_path, base_address = find_mapped_binary(\n" -" handle, name_contains=\"libpython\"\n" -" )\n" -"\n" -" # Step 4: Parse Mach-O headers to get __DATA,__PyRuntime section offset\n" -" section_offset = parse_macho_section_offset(\n" -" binary_path, \"__DATA\", \"__PyRuntime\"\n" -" )\n" -"\n" -" # Step 5: Compute the PyRuntime address in memory\n" -" return base_address + section_offset" -msgstr "" -"def find_py_runtime_macos(pid: int) -> int:\n" -" # 步驟 1：取得對行程記憶體的存取權限\n" -" handle = get_memory_access_handle(pid)\n" -"\n" -" # 步驟 2：嘗試在記憶體中找到 Python 可執行檔\n" -" binary_path, base_address = find_mapped_binary(\n" -" handle, name_contains=\"python\"\n" -" )\n" -"\n" -" # 步驟 3：如果找不到可執行檔，則改用 libpython\n" -" if binary_path is None:\n" -" binary_path, base_address = find_mapped_binary(\n" -" handle, name_contains=\"libpython\"\n" -" )\n" -"\n" -" # 步驟 4：剖析 Mach-O 標頭以取得 __DATA,__PyRuntime 區段偏移量\n" -" section_offset = parse_macho_section_offset(\n" -" binary_path, \"__DATA\", \"__PyRuntime\"\n" -" )\n" -"\n" -" # 步驟 5：計算 PyRuntime 在記憶體中的位址\n" -" return base_address + section_offset" - -#: ../../howto/remote_debugging.rst:233 -msgid "" -"On macOS, accessing another process's memory requires using Mach-O specific " -"APIs and file formats. The first step is obtaining a ``task_port`` handle " -"via ``task_for_pid()``, which provides access to the target process's memory " -"space. This handle enables memory operations through APIs like " -"``mach_vm_read_overwrite()``." -msgstr "" -"在 macOS 上，存取另一個行程的記憶體需要使用 Mach-O 特定的 API 和檔案格式。第一步是透過 " -"``task_for_pid()`` 取得 ``task_port`` 控制代碼，它提供對目標行程記憶體空間的存取。" -"此控制代碼透過像 ``mach_vm_read_overwrite()`` 這樣的 API 啟用記憶體操作。" - -#: ../../howto/remote_debugging.rst:239 -msgid "" -"The process memory can be examined using ``mach_vm_region()`` to scan " -"through the virtual memory space, while ``proc_regionfilename()`` helps " -"identify which binary files are loaded at each memory region. When the " -"Python binary or library is found, its Mach-O headers need to be parsed to " -"locate the ``PyRuntime`` structure." -msgstr "" -"可以使用 ``mach_vm_region()`` 掃描虛擬記憶體空間來檢查行程記憶體，而 ``proc_regionfilename()`` " -"幫助識別在每個記憶體區域載入了哪些二進位檔案。當找到 Python 二進位檔案或函式庫時，需要剖析其 Mach-O " -"標頭以定位 ``PyRuntime`` 結構。" - -#: ../../howto/remote_debugging.rst:244 -msgid "" -"The Mach-O format organizes code and data into segments and sections. The " -"``PyRuntime`` structure lives in a section named ``__PyRuntime`` within the " -"``__DATA`` segment. The actual runtime address calculation involves finding " -"the ``__TEXT`` segment which serves as the binary's base address, then " -"locating the ``__DATA`` segment containing our target section. The final " -"address is computed by combining the base address with the appropriate " -"section offsets from the Mach-O headers." -msgstr "" -"Mach-O 格式將程式碼和資料組織成程式段和區段。``PyRuntime`` 結構位於 ``__DATA`` 程式段內名" -"為 ``__PyRuntime`` 的區段中。實際的 runtime 位址計算涉及找到作為二進位檔案基底位址的 ``__TEXT`` " -"程式段，然後定位包含我們目標區段的 ``__DATA`` 程式段。最終位址是透過將基底位址與來自 Mach-O " -"標頭的適當區段偏移量組合來計算的。" - -#: ../../howto/remote_debugging.rst:252 -msgid "" -"Note that accessing another process's memory on macOS typically requires " -"elevated privileges - either root access or special security entitlements " -"granted to the debugging process." -msgstr "" -"請注意，在 macOS 上存取另一個行程的記憶體通常需要提升過後的權限 - " -"要麼是 root 存取權限，要麼是授予偵錯行程的特殊安全授權。" - -#: ../../howto/remote_debugging.rst:258 -msgid "Windows (PE)" -msgstr "Windows (PE)" - -#: ../../howto/remote_debugging.rst:259 -msgid "To find the ``PyRuntime`` structure on Windows:" -msgstr "在 Windows 上找 ``PyRuntime`` 結構：" - -#: ../../howto/remote_debugging.rst:261 -msgid "" -"Use the ToolHelp API to enumerate all modules loaded in the target process. " -"This is done using functions such as `CreateToolhelp32Snapshot `_, `Module32First `_, and " -"`Module32Next `_." -msgstr "" -"使用 ToolHelp API 來列舉目標行程中載入的所有模組。這是使用諸如 `CreateToolhelp32Snapshot " -"`_、`Module32First `_ 和 " -"`Module32Next `_ 等函式來完成的。" - -#: ../../howto/remote_debugging.rst:268 -msgid "" -"Identify the module corresponding to :file:`python.exe` or :file:`python{XY}." -"dll`, where ``X`` and ``Y`` are the major and minor version numbers of the " -"Python version, and record its base address." -msgstr "" -"識別對應於 :file:`python.exe` 或 :file:`python{XY}.dll` 的模組，其中 ``X`` 和 ``Y`` 是" -"Python 版本的主要和次要版本號，並記錄其基底位址。" - -#: ../../howto/remote_debugging.rst:271 -msgid "" -"Locate the ``PyRuntim`` section. Due to the PE format's 8-character limit on " -"section names (defined as ``IMAGE_SIZEOF_SHORT_NAME``), the original name " -"``PyRuntime`` is truncated. This section contains the ``PyRuntime`` " -"structure." -msgstr "" -"定位 ``PyRuntim`` 區段。由於 PE 格式對區段名稱有 8 個字元的限制（定義為 " -"``IMAGE_SIZEOF_SHORT_NAME``），所以原始名稱 ``PyRuntime`` 會被截斷。此區段包含 " -"``PyRuntime`` 結構。" - -#: ../../howto/remote_debugging.rst:275 -msgid "" -"Retrieve the section’s relative virtual address (RVA) and add it to the base " -"address of the module." -msgstr "檢索區段的相對虛擬位址 (RVA, relative virtual address) 並將其加到模組的基底位址。" - -#: ../../howto/remote_debugging.rst:280 -msgid "" -"def find_py_runtime_windows(pid: int) -> int:\n" -" # Step 1: Try to find the Python executable in memory\n" -" binary_path, base_address = find_loaded_module(\n" -" pid, name_contains=\"python\"\n" -" )\n" -"\n" -" # Step 2: Fallback to shared pythonXY.dll if the executable is not\n" -" # found\n" -" if binary_path is None:\n" -" binary_path, base_address = find_loaded_module(\n" -" pid, name_contains=\"python3\"\n" -" )\n" -"\n" -" # Step 3: Parse PE section headers to get the RVA of the PyRuntime\n" -" # section. The section name appears as \"PyRuntim\" due to the\n" -" # 8-character limit defined by the PE format (IMAGE_SIZEOF_SHORT_NAME).\n" -" section_rva = parse_pe_section_offset(binary_path, \"PyRuntim\")\n" -"\n" -" # Step 4: Compute PyRuntime address in memory\n" -" return base_address + section_rva" -msgstr "" -"def find_py_runtime_windows(pid: int) -> int:\n" -" # 步驟 1：嘗試在記憶體中找到 Python 可執行檔\n" -" binary_path, base_address = find_loaded_module(\n" -" pid, name_contains=\"python\"\n" -" )\n" -"\n" -" # 步驟 2：如果找不到可執行檔，則改用共享函式庫 pythonXY.dll\n" -" if binary_path is None:\n" -" binary_path, base_address = find_loaded_module(\n" -" pid, name_contains=\"python3\"\n" -" )\n" -"\n" -" # 步驟 3：剖析 PE 區段標頭以取得 PyRuntime 區段的 RVA。\n" -" # 由於 PE 格式 (IMAGE_SIZEOF_SHORT_NAME) 有8 字元的限制，\n" -" # 區段名稱顯示為 \"PyRuntim\"。\n" -" section_rva = parse_pe_section_offset(binary_path, \"PyRuntim\")\n" -"\n" -" # 步驟 4：計算 PyRuntime 在記憶體中的位址\n" -" return base_address + section_rva" - -#: ../../howto/remote_debugging.rst:302 -msgid "" -"On Windows, accessing another process's memory requires using the Windows " -"API functions like ``CreateToolhelp32Snapshot()`` and ``Module32First()/" -"Module32Next()`` to enumerate loaded modules. The ``OpenProcess()`` function " -"provides a handle to access the target process's memory space, enabling " -"memory operations through ``ReadProcessMemory()``." -msgstr "" -"在 Windows 上，存取另一個行程的記憶體需要使用像 ``CreateToolhelp32Snapshot()`` 和 " -"``Module32First()/Module32Next()`` 這樣的 Windows API 函式來列舉載入的模組。" -"``OpenProcess()`` 函式提供一個控制代碼來存取目標行程的記憶體空間，並透過 " -"``ReadProcessMemory()`` 啟用記憶體操作。" - -#: ../../howto/remote_debugging.rst:308 -msgid "" -"The process memory can be examined by enumerating loaded modules to find the " -"Python binary or DLL. When found, its PE headers need to be parsed to locate " -"the ``PyRuntime`` structure." -msgstr "" -"可以透過列舉載入的模組來檢查行程記憶體，以找到 Python 二進位檔案或 DLL。找到後，需要剖析其 PE " -"標頭以定位 ``PyRuntime`` 結構。" - -#: ../../howto/remote_debugging.rst:312 -msgid "" -"The PE format organizes code and data into sections. The ``PyRuntime`` " -"structure lives in a section named \"PyRuntim\" (truncated from " -"\"PyRuntime\" due to PE's 8-character name limit). The actual runtime " -"address calculation involves finding the module's base address from the " -"module entry, then locating our target section in the PE headers. The final " -"address is computed by combining the base address with the section's virtual " -"address from the PE section headers." -msgstr "" -"PE 格式將程式碼和資料組織成區段。``PyRuntime`` 結構位於名為 \"PyRuntim\" " -"的區段中（由於 PE 的 8 字元名稱限制，從 \"PyRuntime\" 截斷）。實際的 runtime " -"位址計算涉及從模組項目中找到模組的基底位址，然後在 PE 標頭中定位我們的目標區段。" -"最終位址是透過將基底位址與 PE 區段標頭中的區段虛擬位址組合來計算的。" - -#: ../../howto/remote_debugging.rst:319 -msgid "" -"Note that accessing another process's memory on Windows typically requires " -"appropriate privileges - either administrative access or the " -"``SeDebugPrivilege`` privilege granted to the debugging process." -msgstr "" -"請注意，在 Windows 上存取另一個行程的記憶體通常需要適當的權限 - 要麼是系統管理員存取權限" -"，要麼是授予偵錯行程的 ``SeDebugPrivilege`` 權限。" - -#: ../../howto/remote_debugging.rst:325 -msgid "Reading _Py_DebugOffsets" -msgstr "讀取 _Py_DebugOffsets" - -#: ../../howto/remote_debugging.rst:327 -msgid "" -"Once the address of the ``PyRuntime`` structure has been determined, the " -"next step is to read the ``_Py_DebugOffsets`` structure located at the " -"beginning of the ``PyRuntime`` block." -msgstr "" -"一旦確定了 ``PyRuntime`` 結構的位址，下一步就是讀取位於 ``PyRuntime`` 區塊開頭的 " -"``_Py_DebugOffsets`` 結構。" - -#: ../../howto/remote_debugging.rst:331 -msgid "" -"This structure provides version-specific field offsets that are needed to " -"safely read interpreter and thread state memory. These offsets vary between " -"CPython versions and must be checked before use to ensure they are " -"compatible." -msgstr "" -"此結構提供了安全讀取直譯器和執行緒狀態記憶體所需的版本特定欄位偏移量。這些偏移量在不同的 CPython " -"版本之間有所不同，必須在使用前檢查以確保它們相容。" - -#: ../../howto/remote_debugging.rst:335 -msgid "To read and check the debug offsets, follow these steps:" -msgstr "要讀取並檢查偵錯偏移量，請按照以下步驟操作：" - -#: ../../howto/remote_debugging.rst:337 -msgid "" -"Read memory from the target process starting at the ``PyRuntime`` address, " -"covering the same number of bytes as the ``_Py_DebugOffsets`` structure. " -"This structure is located at the very start of the ``PyRuntime`` memory " -"block. Its layout is defined in CPython’s internal headers and stays the " -"same within a given minor version, but may change in major versions." -msgstr "" -"從目標行程中的 ``PyRuntime`` 位址開始讀取記憶體，涵蓋與 ``_Py_DebugOffsets`` 結構相同的位元組數。" -"此結構位於 ``PyRuntime`` 記憶體區塊的最開始處。" -"其佈局 (layout) 在 CPython 的內部標頭中定義，並在給定的次要版本中維持不變，但在主要版本中可能會更改。" - -#: ../../howto/remote_debugging.rst:343 -msgid "Check that the structure contains valid data:" -msgstr "檢查結構是否包含有效資料：" - -#: ../../howto/remote_debugging.rst:345 -msgid "The ``cookie`` field must match the expected debug marker." -msgstr "``cookie`` 欄位必須匹配預期的偵錯標記。" - -#: ../../howto/remote_debugging.rst:346 -msgid "" -"The ``version`` field must match the version of the Python interpreter used " -"by the debugger." -msgstr "``version`` 欄位必須匹配偵錯器使用的 Python 直譯器版本。" - -#: ../../howto/remote_debugging.rst:348 -msgid "" -"If either the debugger or the target process is using a pre-release version " -"(for example, an alpha, beta, or release candidate), the versions must match " -"exactly." -msgstr "如果偵錯器或目標行程使用的是預發行版本（例如 alpha、beta 或候選版本），版本必須完全匹配。" - -#: ../../howto/remote_debugging.rst:351 -msgid "" -"The ``free_threaded`` field must have the same value in both the debugger " -"and the target process." -msgstr "``free_threaded`` 欄位在偵錯器和目標行程中必須具有相同的值。" - -#: ../../howto/remote_debugging.rst:354 -msgid "" -"If the structure is valid, the offsets it contains can be used to locate " -"fields in memory. If any check fails, the debugger should stop the operation " -"to avoid reading memory in the wrong format." -msgstr "" -"如果結構有效，其中包含的偏移量可用於定位記憶體中的欄位。如果任何檢查失敗，偵錯器應停止操作" -"以避免以錯誤的格式讀取記憶體。" - -#: ../../howto/remote_debugging.rst:358 -msgid "" -"The following is an example implementation that reads and checks " -"``_Py_DebugOffsets``::" -msgstr "以下是一個讀取並檢查 ``_Py_DebugOffsets`` 的範例實作： ::" - -#: ../../howto/remote_debugging.rst:361 -msgid "" -"def read_debug_offsets(pid: int, py_runtime_addr: int) -> DebugOffsets:\n" -" # Step 1: Read memory from the target process at the PyRuntime address\n" -" data = read_process_memory(\n" -" pid, address=py_runtime_addr, size=DEBUG_OFFSETS_SIZE\n" -" )\n" -"\n" -" # Step 2: Deserialize the raw bytes into a _Py_DebugOffsets structure\n" -" debug_offsets = parse_debug_offsets(data)\n" -"\n" -" # Step 3: Validate the contents of the structure\n" -" if debug_offsets.cookie != EXPECTED_COOKIE:\n" -" raise RuntimeError(\"Invalid or missing debug cookie\")\n" -" if debug_offsets.version != LOCAL_PYTHON_VERSION:\n" -" raise RuntimeError(\n" -" \"Mismatch between caller and target Python versions\"\n" -" )\n" -" if debug_offsets.free_threaded != LOCAL_FREE_THREADED:\n" -" raise RuntimeError(\"Mismatch in free-threaded configuration\")\n" -"\n" -" return debug_offsets" -msgstr "" -"def read_debug_offsets(pid: int, py_runtime_addr: int) -> DebugOffsets:\n" -" # 步驟 1：在 PyRuntime 位址從目標行程讀取記憶體\n" -" data = read_process_memory(\n" -" pid, address=py_runtime_addr, size=DEBUG_OFFSETS_SIZE\n" -" )\n" -"\n" -" # 步驟 2：將原始位元組反序列化為 _Py_DebugOffsets 結構\n" -" debug_offsets = parse_debug_offsets(data)\n" -"\n" -" # 步驟 3：驗證結構的內容\n" -" if debug_offsets.cookie != EXPECTED_COOKIE:\n" -" raise RuntimeError(\"Invalid or missing debug cookie\")\n" -" if debug_offsets.version != LOCAL_PYTHON_VERSION:\n" -" raise RuntimeError(\n" -" \"Mismatch between caller and target Python versions\"\n" -" )\n" -" if debug_offsets.free_threaded != LOCAL_FREE_THREADED:\n" -" raise RuntimeError(\"Mismatch in free-threaded configuration\")\n" -"\n" -" return debug_offsets" - -#: ../../howto/remote_debugging.rst:386 -msgid "**Process suspension recommended**" -msgstr "**建議暫停行程**" - -#: ../../howto/remote_debugging.rst:388 -msgid "" -"To avoid race conditions and ensure memory consistency, it is strongly " -"recommended that the target process be suspended before performing any " -"operations that read or write internal interpreter state. The Python runtime " -"may concurrently mutate interpreter data structures—such as creating or " -"destroying threads—during normal execution. This can result in invalid " -"memory reads or writes." -msgstr "" -"為了避免競態條件 (race conditions) 並確保記憶體一致性，強烈建議在執行任何讀取或寫入" -"內部直譯器狀態的操作之前暫停目標行程。Python runtime 可能在正常執行期間同時變更直譯器" -"資料結構 - 例如建立或銷毀執行緒。這可能導致無效的記憶體讀取或寫入。" - -#: ../../howto/remote_debugging.rst:395 -msgid "" -"A debugger may suspend execution by attaching to the process with ``ptrace`` " -"or by sending a ``SIGSTOP`` signal. Execution should only be resumed after " -"debugger-side memory operations are complete." -msgstr "" -"偵錯器可以透過使用 ``ptrace`` 附加到行程或發送 ``SIGSTOP`` 訊號來暫停執行。只有在偵錯器" -"端的記憶體操作完成後才應恢復執行。" - -#: ../../howto/remote_debugging.rst:401 -msgid "" -"Some tools, such as profilers or sampling-based debuggers, may operate on a " -"running process without suspension. In such cases, tools must be explicitly " -"designed to handle partially updated or inconsistent memory. For most " -"debugger implementations, suspending the process remains the safest and most " -"robust approach." -msgstr "" -"一些工具，例如分析器 (profilers) 或基於取樣的偵錯器，可能在不暫停的情況下對正在執行的行程" -"進行操作。在這種情況下，工具必須明確設計為能夠處理部分更新或不一致的記憶體。對於大多數偵錯器" -"實作來說，暫停行程仍然是最安全可靠的方法。" - -#: ../../howto/remote_debugging.rst:409 -msgid "Locating the interpreter and thread state" -msgstr "定位直譯器和執行緒狀態" - -#: ../../howto/remote_debugging.rst:411 -msgid "" -"Before code can be injected and executed in a remote Python process, the " -"debugger must choose a thread in which to schedule execution. This is " -"necessary because the control fields used to perform remote code injection " -"are located in the ``_PyRemoteDebuggerSupport`` structure, which is embedded " -"in a ``PyThreadState`` object. These fields are modified by the debugger to " -"request execution of injected scripts." -msgstr "" -"在可以於遠端 Python 行程中注入並執行程式碼之前，偵錯器必須選擇一個用於排程執行的執行緒。" -"這是必要的，因為用於執行遠端程式碼注入的控制欄位位於 ``_PyRemoteDebuggerSupport`` " -"結構中，該結構嵌入在 ``PyThreadState`` 物件中。偵錯器會修改這些欄位以請求執行注入的腳本。" - -#: ../../howto/remote_debugging.rst:418 -msgid "" -"The ``PyThreadState`` structure represents a thread running inside a Python " -"interpreter. It maintains the thread’s evaluation context and contains the " -"fields required for debugger coordination. Locating a valid " -"``PyThreadState`` is therefore a key prerequisite for triggering execution " -"remotely." -msgstr "" -"``PyThreadState`` 結構代表在 Python 直譯器內執行的執行緒。它維護執行緒的求值情境 " -"(evaluation context)，並包含偵錯器協調所需的欄位。因此，定位有效的 ``PyThreadState`` " -"是遠端觸發執行的關鍵前提。" - -#: ../../howto/remote_debugging.rst:423 -msgid "" -"A thread is typically selected based on its role or ID. In most cases, the " -"main thread is used, but some tools may target a specific thread by its " -"native thread ID. Once the target thread is chosen, the debugger must locate " -"both the interpreter and the associated thread state structures in memory." -msgstr "" -"通常根據執行緒的角色或 ID 來選擇執行緒。在大多數情況下會使用主執行緒，但某些工具可能會透過其原生執行緒 ID " -"來定位特定執行緒。一旦選擇了目標執行緒，偵錯器必須在記憶體中定位直譯器和相關的執行緒狀態結構。" - -#: ../../howto/remote_debugging.rst:428 -msgid "The relevant internal structures are defined as follows:" -msgstr "相關的內部結構定義如下：" - -#: ../../howto/remote_debugging.rst:430 -msgid "" -"``PyInterpreterState`` represents an isolated Python interpreter instance. " -"Each interpreter maintains its own set of imported modules, built-in state, " -"and thread state list. Although most Python applications use a single " -"interpreter, CPython supports multiple interpreters in the same process." -msgstr "" -"``PyInterpreterState`` 代表一個隔離的 Python 直譯器實例。每個直譯器維護自己的一組" -"已引入模組、內建狀態和執行緒狀態串列。雖然大多數 Python 應用程式使用單一直譯器，但 CPython " -"支援在同一行程中使用多個直譯器。" - -#: ../../howto/remote_debugging.rst:435 -msgid "" -"``PyThreadState`` represents a thread running within an interpreter. It " -"contains execution state and the control fields used by the debugger." -msgstr "``PyThreadState`` 代表在直譯器內運行的執行緒。它包含執行狀態和偵錯器使用的控制欄位。" - -#: ../../howto/remote_debugging.rst:438 -msgid "To locate a thread:" -msgstr "要定位執行緒：" - -#: ../../howto/remote_debugging.rst:440 -msgid "" -"Use the offset ``runtime_state.interpreters_head`` to obtain the address of " -"the first interpreter in the ``PyRuntime`` structure. This is the entry " -"point to the linked list of active interpreters." -msgstr "" -"使用偏移量 ``runtime_state.interpreters_head`` 來取得 ``PyRuntime`` " -"結構中第一個直譯器的位址。這是活動直譯器鏈結串列的進入點。" - -#: ../../howto/remote_debugging.rst:444 -msgid "" -"Use the offset ``interpreter_state.threads_main`` to access the main thread " -"state associated with the selected interpreter. This is typically the most " -"reliable thread to target." -msgstr "" -"使用偏移量 ``interpreter_state.threads_main`` 來存取與所選直譯器相關的主執行緒狀態。" -"這通常是最可靠的目標執行緒。" - -#: ../../howto/remote_debugging.rst:448 -msgid "" -"Optionally, use the offset ``interpreter_state.threads_head`` to iterate " -"through the linked list of all thread states. Each ``PyThreadState`` " -"structure contains a ``native_thread_id`` field, which may be compared to a " -"target thread ID to find a specific thread." -msgstr "" -"可選地使用偏移量 ``interpreter_state.threads_head`` 來遍歷所有執行緒狀態的鏈結串列。每個 " -"``PyThreadState`` 結構包含一個 ``native_thread_id`` 欄位，可以將其與目標執行緒 ID 進行比" -"較以找到特定執行緒。" - -#: ../../howto/remote_debugging.rst:453 -msgid "" -"Once a valid ``PyThreadState`` has been found, its address can be used in " -"later steps of the protocol, such as writing debugger control fields and " -"scheduling execution." -msgstr "" -"一旦找到有效的 ``PyThreadState``，其位址可以在協定的後續步驟中使用，例如寫入偵錯器控制欄位" -"和排程執行。" - -#: ../../howto/remote_debugging.rst:457 -msgid "" -"The following is an example implementation that locates the main thread " -"state::" -msgstr "以下是一個定位主執行緒狀態的範例實作： ::" - -#: ../../howto/remote_debugging.rst:459 -msgid "" -"def find_main_thread_state(\n" -" pid: int, py_runtime_addr: int, debug_offsets: DebugOffsets,\n" -") -> int:\n" -" # Step 1: Read interpreters_head from PyRuntime\n" -" interp_head_ptr = (\n" -" py_runtime_addr + debug_offsets.runtime_state.interpreters_head\n" -" )\n" -" interp_addr = read_pointer(pid, interp_head_ptr)\n" -" if interp_addr == 0:\n" -" raise RuntimeError(\"No interpreter found in the target process\")\n" -"\n" -" # Step 2: Read the threads_main pointer from the interpreter\n" -" threads_main_ptr = (\n" -" interp_addr + debug_offsets.interpreter_state.threads_main\n" -" )\n" -" thread_state_addr = read_pointer(pid, threads_main_ptr)\n" -" if thread_state_addr == 0:\n" -" raise RuntimeError(\"Main thread state is not available\")\n" -"\n" -" return thread_state_addr" -msgstr "" -"def find_main_thread_state(\n" -" pid: int, py_runtime_addr: int, debug_offsets: DebugOffsets,\n" -") -> int:\n" -" # 步驟 1：從 PyRuntime 讀取 interpreters_head\n" -" interp_head_ptr = (\n" -" py_runtime_addr + debug_offsets.runtime_state.interpreters_head\n" -" )\n" -" interp_addr = read_pointer(pid, interp_head_ptr)\n" -" if interp_addr == 0:\n" -" raise RuntimeError(\"No interpreter found in the target process\")\n" -"\n" -" # 步驟 2：從直譯器讀取 threads_main 指標\n" -" threads_main_ptr = (\n" -" interp_addr + debug_offsets.interpreter_state.threads_main\n" -" )\n" -" thread_state_addr = read_pointer(pid, threads_main_ptr)\n" -" if thread_state_addr == 0:\n" -" raise RuntimeError(\"Main thread state is not available\")\n" -"\n" -" return thread_state_addr" - -#: ../../howto/remote_debugging.rst:480 -msgid "" -"The following example demonstrates how to locate a thread by its native " -"thread ID::" -msgstr "以下範例示範如何透過原生執行緒 ID 來定位執行緒： ::" - -#: ../../howto/remote_debugging.rst:483 -msgid "" -"def find_thread_by_id(\n" -" pid: int,\n" -" interp_addr: int,\n" -" debug_offsets: DebugOffsets,\n" -" target_tid: int,\n" -") -> int:\n" -" # Start at threads_head and walk the linked list\n" -" thread_ptr = read_pointer(\n" -" pid,\n" -" interp_addr + debug_offsets.interpreter_state.threads_head\n" -" )\n" -"\n" -" while thread_ptr:\n" -" native_tid_ptr = (\n" -" thread_ptr + debug_offsets.thread_state.native_thread_id\n" -" )\n" -" native_tid = read_int(pid, native_tid_ptr)\n" -" if native_tid == target_tid:\n" -" return thread_ptr\n" -" thread_ptr = read_pointer(\n" -" pid,\n" -" thread_ptr + debug_offsets.thread_state.next\n" -" )\n" -"\n" -" raise RuntimeError(\"Thread with the given ID was not found\")" -msgstr "" -"def find_thread_by_id(\n" -" pid: int,\n" -" interp_addr: int,\n" -" debug_offsets: DebugOffsets,\n" -" target_tid: int,\n" -") -> int:\n" -" # 從 threads_head 開始並遍歷鏈結串列\n" -" thread_ptr = read_pointer(\n" -" pid,\n" -" interp_addr + debug_offsets.interpreter_state.threads_head\n" -" )\n" -"\n" -" while thread_ptr:\n" -" native_tid_ptr = (\n" -" thread_ptr + debug_offsets.thread_state.native_thread_id\n" -" )\n" -" native_tid = read_int(pid, native_tid_ptr)\n" -" if native_tid == target_tid:\n" -" return thread_ptr\n" -" thread_ptr = read_pointer(\n" -" pid,\n" -" thread_ptr + debug_offsets.thread_state.next\n" -" )\n" -"\n" -" raise RuntimeError(\"Thread with the given ID was not found\")" - -#: ../../howto/remote_debugging.rst:510 -msgid "" -"Once a valid thread state has been located, the debugger can proceed with " -"modifying its control fields and scheduling execution, as described in the " -"next section." -msgstr "一旦定位到有效的執行緒狀態，偵錯器就可以繼續修改其控制欄位並排程執行，如下一節所述。" - -#: ../../howto/remote_debugging.rst:515 -msgid "Writing control information" -msgstr "寫入控制資訊" - -#: ../../howto/remote_debugging.rst:517 -msgid "" -"Once a valid ``PyThreadState`` structure has been identified, the debugger " -"may modify control fields within it to schedule the execution of a specified " -"Python script. These control fields are checked periodically by the " -"interpreter, and when set correctly, they trigger the execution of remote " -"code at a safe point in the evaluation loop." -msgstr "" -"一旦識別出有效的 ``PyThreadState`` 結構，偵錯器就可以修改其中的控制欄位以排程執行指定的 Python " -"腳本。直譯器會定期檢查這些控制欄位，當正確設定時，它們會在求值迴圈中的安全點觸發遠端程式碼的執行。" - -#: ../../howto/remote_debugging.rst:523 -msgid "" -"Each ``PyThreadState`` contains a ``_PyRemoteDebuggerSupport`` structure " -"used for communication between the debugger and the interpreter. The " -"locations of its fields are defined by the ``_Py_DebugOffsets`` structure " -"and include the following:" -msgstr "" -"每個 ``PyThreadState`` 都包含一個 ``_PyRemoteDebuggerSupport`` 結構，" -"能用於偵錯器和直譯器之間的通訊。其欄位的位置由 ``_Py_DebugOffsets`` 結構定義，包括以下內容：" - -#: ../../howto/remote_debugging.rst:528 -msgid "" -"``debugger_script_path``: A fixed-size buffer that holds the full path to a " -"Python source file (``.py``). This file must be accessible and readable by " -"the target process when execution is triggered." -msgstr "" -"``debugger_script_path``：一個固定大小的緩衝區，用於保存 Python " -"原始檔（``.py``）的完整路徑。觸發執行時，目標行程必須能夠存取和讀取此檔案。" - -#: ../../howto/remote_debugging.rst:532 -msgid "" -"``debugger_pending_call``: An integer flag. Setting this to ``1`` tells the " -"interpreter that a script is ready to be executed." -msgstr "``debugger_pending_call``：一個整數旗標。將其設定為 ``1`` 會告訴直譯器腳本已準備好執行。" - -#: ../../howto/remote_debugging.rst:535 -msgid "" -"``eval_breaker``: A field checked by the interpreter during execution. " -"Setting bit 5 (``_PY_EVAL_PLEASE_STOP_BIT``, value ``1U << 5``) in this " -"field causes the interpreter to pause and check for debugger activity." -msgstr "" -"``eval_breaker``：直譯器在執行期間檢查的欄位。在此欄位中設定位元 5（``_PY_EVAL_PLEASE_STOP_BIT``，值 " -"``1U << 5``）會導致直譯器暫停並檢查偵錯器活動。" - -#: ../../howto/remote_debugging.rst:539 -msgid "" -"To complete the injection, the debugger must perform the following steps:" -msgstr "要完成注入，偵錯器必須執行以下步驟：" - -#: ../../howto/remote_debugging.rst:541 -msgid "Write the full script path into the ``debugger_script_path`` buffer." -msgstr "將完整的腳本路徑寫入 ``debugger_script_path`` 緩衝區。" - -#: ../../howto/remote_debugging.rst:542 -msgid "Set ``debugger_pending_call`` to ``1``." -msgstr "將 ``debugger_pending_call`` 設定為 ``1``。" - -#: ../../howto/remote_debugging.rst:543 -msgid "" -"Read the current value of ``eval_breaker``, set bit 5 " -"(``_PY_EVAL_PLEASE_STOP_BIT``), and write the updated value back. This " -"signals the interpreter to check for debugger activity." -msgstr "" -"讀取 ``eval_breaker`` 目前的值，設定位元 5（``_PY_EVAL_PLEASE_STOP_BIT``）" -"並將更新後的值寫回。這會向直譯器發出檢查偵錯器活動的訊號。" - -#: ../../howto/remote_debugging.rst:549 -msgid "" -"def inject_script(\n" -" pid: int,\n" -" thread_state_addr: int,\n" -" debug_offsets: DebugOffsets,\n" -" script_path: str\n" -") -> None:\n" -" # Compute the base offset of _PyRemoteDebuggerSupport\n" -" support_base = (\n" -" thread_state_addr +\n" -" debug_offsets.debugger_support.remote_debugger_support\n" -" )\n" -"\n" -" # Step 1: Write the script path into debugger_script_path\n" -" script_path_ptr = (\n" -" support_base +\n" -" debug_offsets.debugger_support.debugger_script_path\n" -" )\n" -" write_string(pid, script_path_ptr, script_path)\n" -"\n" -" # Step 2: Set debugger_pending_call to 1\n" -" pending_ptr = (\n" -" support_base +\n" -" debug_offsets.debugger_support.debugger_pending_call\n" -" )\n" -" write_int(pid, pending_ptr, 1)\n" -"\n" -" # Step 3: Set _PY_EVAL_PLEASE_STOP_BIT (bit 5, value 1 << 5) in\n" -" # eval_breaker\n" -" eval_breaker_ptr = (\n" -" thread_state_addr +\n" -" debug_offsets.debugger_support.eval_breaker\n" -" )\n" -" breaker = read_int(pid, eval_breaker_ptr)\n" -" breaker |= (1 << 5)\n" -" write_int(pid, eval_breaker_ptr, breaker)" -msgstr "" -"def inject_script(\n" -" pid: int,\n" -" thread_state_addr: int,\n" -" debug_offsets: DebugOffsets,\n" -" script_path: str\n" -") -> None:\n" -" # 計算 _PyRemoteDebuggerSupport 的基底偏移量\n" -" support_base = (\n" -" thread_state_addr +\n" -" debug_offsets.debugger_support.remote_debugger_support\n" -" )\n" -"\n" -" # 步驟 1：將腳本路徑寫入 debugger_script_path\n" -" script_path_ptr = (\n" -" support_base +\n" -" debug_offsets.debugger_support.debugger_script_path\n" -" )\n" -" write_string(pid, script_path_ptr, script_path)\n" -"\n" -" # 步驟 2：將 debugger_pending_call 設定為 1\n" -" pending_ptr = (\n" -" support_base +\n" -" debug_offsets.debugger_support.debugger_pending_call\n" -" )\n" -" write_int(pid, pending_ptr, 1)\n" -"\n" -" # 步驟 3：在 eval_breaker 中設定 _PY_EVAL_PLEASE_STOP_BIT（位元 5，值為 1 << 5）\n" -" eval_breaker_ptr = (\n" -" thread_state_addr +\n" -" debug_offsets.debugger_support.eval_breaker\n" -" )\n" -" breaker = read_int(pid, eval_breaker_ptr)\n" -" breaker |= (1 << 5)\n" -" write_int(pid, eval_breaker_ptr, breaker)" - -#: ../../howto/remote_debugging.rst:586 -msgid "" -"Once these fields are set, the debugger may resume the process (if it was " -"suspended). The interpreter will process the request at the next safe " -"evaluation point, load the script from disk, and execute it." -msgstr "" -"一旦設定了這些欄位，偵錯器就可以恢復行程（如果它先被暫停了）。直譯器將在下一個安全執行點" -"處理請求、從磁碟載入腳本並執行它。" - -#: ../../howto/remote_debugging.rst:590 -msgid "" -"It is the responsibility of the debugger to ensure that the script file " -"remains present and accessible to the target process during execution." -msgstr "偵錯器有責任確保腳本檔案在執行期間仍然存在且可供目標行程存取。" - -#: ../../howto/remote_debugging.rst:595 -msgid "" -"Script execution is asynchronous. The script file cannot be deleted " -"immediately after injection. The debugger should wait until the injected " -"script has produced an observable effect before removing the file. This " -"effect depends on what the script is designed to do. For example, a debugger " -"might wait until the remote process connects back to a socket before " -"removing the script. Once such an effect is observed, it is safe to assume " -"the file is no longer needed." -msgstr "" -"腳本執行是非同步的。注入後不能立即刪除腳本檔案。偵錯器應等到注入的腳本產生可觀察的效果後再" -"刪除檔案。此效果取決於腳本被設計要執行的操作。例如，偵錯器可能會等到遠端行程連回通訊端後再刪" -"除腳本。一旦觀察到這種效果，就可以安全地假設不再需要該檔案。" - -#: ../../howto/remote_debugging.rst:604 -msgid "Summary" -msgstr "摘要" - -#: ../../howto/remote_debugging.rst:606 -msgid "To inject and execute a Python script in a remote process:" -msgstr "要在遠端行程中注入並執行 Python 腳本：" - -#: ../../howto/remote_debugging.rst:608 -msgid "Locate the ``PyRuntime`` structure in the target process’s memory." -msgstr "在目標行程的記憶體中定位 ``PyRuntime`` 結構。" - -#: ../../howto/remote_debugging.rst:609 -msgid "" -"Read and validate the ``_Py_DebugOffsets`` structure at the beginning of " -"``PyRuntime``." -msgstr "讀取並驗證 ``PyRuntime`` 開頭的 ``_Py_DebugOffsets`` 結構。" - -#: ../../howto/remote_debugging.rst:611 -msgid "Use the offsets to locate a valid ``PyThreadState``." -msgstr "使用偏移量來定位有效的 ``PyThreadState``。" - -#: ../../howto/remote_debugging.rst:612 -msgid "Write the path to a Python script into ``debugger_script_path``." -msgstr "將 Python 腳本的路徑寫入 ``debugger_script_path``。" - -#: ../../howto/remote_debugging.rst:613 -msgid "Set the ``debugger_pending_call`` flag to ``1``." -msgstr "將 ``debugger_pending_call`` 旗標設定為 ``1``。" - -#: ../../howto/remote_debugging.rst:614 -msgid "Set ``_PY_EVAL_PLEASE_STOP_BIT`` in the ``eval_breaker`` field." -msgstr "在 ``eval_breaker`` 欄位中設定 ``_PY_EVAL_PLEASE_STOP_BIT``。" - -#: ../../howto/remote_debugging.rst:615 -msgid "" -"Resume the process (if suspended). The script will execute at the next safe " -"evaluation point." -msgstr "恢復行程（如果已暫停）。腳本將在下一個安全執行點執行。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-13 00:14+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"Language: zh_TW\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../howto/remote_debugging.rst:4 +msgid "Remote debugging attachment protocol" +msgstr "遠端偵錯附加協定" + +#: ../../howto/remote_debugging.rst:6 +msgid "" +"This protocol enables external tools to attach to a running CPython process " +"and execute Python code remotely." +msgstr "此協定使外部工具能夠附加到正在執行的 CPython 行程並遠端執行 Python 程式碼。" + +#: ../../howto/remote_debugging.rst:9 +msgid "" +"Most platforms require elevated privileges to attach to another Python " +"process." +msgstr "大多數平台上都會需要更高的權限才能附加到另一個 Python 行程。" + +#: ../../howto/remote_debugging.rst:14 +msgid "Permission requirements" +msgstr "權限需求" + +#: ../../howto/remote_debugging.rst:16 +msgid "" +"Attaching to a running Python process for remote debugging requires elevated " +"privileges on most platforms. The specific requirements and troubleshooting " +"steps depend on your operating system:" +msgstr "" +"在大多數平台上，附加到正在執行的 Python 行程進行遠端偵錯需要更高的權限。具體要求和疑難排" +"解步驟會取決於你的作業系統：" + +#: ../../howto/remote_debugging.rst:21 +msgid "Linux" +msgstr "Linux" + +#: ../../howto/remote_debugging.rst:22 +msgid "" +"The tracer process must have the ``CAP_SYS_PTRACE`` capability or equivalent " +"privileges. You can only trace processes you own and can signal. Tracing may " +"fail if the process is already being traced, or if it is running with set-" +"user-ID or set-group-ID. Security modules like Yama may further restrict " +"tracing." +msgstr "" +"執行追蹤的行程 (tracer process) 必須具有 ``CAP_SYS_PTRACE`` 功能或同等權限。" +"你只能追蹤你擁有且可以發送訊號的行程。如果行程已經被追蹤，或者它以 set-user-ID 或 " +"set-group-ID 執行，則追蹤可能會失敗。像 Yama 這樣的安全模組可能會進一步限制追蹤。" + +#: ../../howto/remote_debugging.rst:28 +msgid "To temporarily relax ptrace restrictions (until reboot), run:" +msgstr "要暫時放寬 ptrace 限制（直到重新開機），請執行：" + +#: ../../howto/remote_debugging.rst:30 +msgid "``echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope``" +msgstr "``echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope``" + +#: ../../howto/remote_debugging.rst:34 +msgid "" +"Disabling ``ptrace_scope`` reduces system hardening and should only be done " +"in trusted environments." +msgstr "停用 ``ptrace_scope`` 會降低系統安全性，應僅在受信任的環境中執行此操作。" + +#: ../../howto/remote_debugging.rst:37 +msgid "" +"If running inside a container, use ``--cap-add=SYS_PTRACE`` or ``--" +"privileged``, and run as root if needed." +msgstr "" +"如果在容器內執行，請使用 ``--cap-add=SYS_PTRACE`` 或 ``--privileged``，" +"並在需要時以 root 身分執行。" + +#: ../../howto/remote_debugging.rst:40 +msgid "Try re-running the command with elevated privileges:" +msgstr "嘗試使用提升後的權限重新執行命令：" + +#: ../../howto/remote_debugging.rst:42 +msgid "``sudo -E !!``" +msgstr "``sudo -E !!``" + +#: ../../howto/remote_debugging.rst:46 +msgid "macOS" +msgstr "macOS" + +#: ../../howto/remote_debugging.rst:47 +msgid "" +"To attach to another process, you typically need to run your debugging tool " +"with elevated privileges. This can be done by using ``sudo`` or running as " +"root." +msgstr "" +"要附加到另一個行程，你通常需要以提升過的權限來執行偵錯工具。這可以透過使用 ``sudo`` " +"或以 root 身分執行來完成。" + +#: ../../howto/remote_debugging.rst:51 +msgid "" +"Even when attaching to processes you own, macOS may block debugging unless " +"the debugger is run with root privileges due to system security restrictions." +msgstr "" +"即使附加到你擁有的行程，macOS 也可能會阻止偵錯，除非偵錯器以 root 權限執行，這是由於系統安全限制。" + +#: ../../howto/remote_debugging.rst:56 +msgid "Windows" +msgstr "Windows" + +#: ../../howto/remote_debugging.rst:57 +msgid "" +"To attach to another process, you usually need to run your debugging tool " +"with administrative privileges. Start the command prompt or terminal as " +"Administrator." +msgstr "" +"要附加到另一個行程，你通常需要以系統管理員權限執行偵錯工具。以系統管理員身分啟動命令提示字元或終端機。" + +#: ../../howto/remote_debugging.rst:61 +msgid "" +"Some processes may still be inaccessible even with Administrator rights, " +"unless you have the ``SeDebugPrivilege`` privilege enabled." +msgstr "即使具有系統管理員權限，某些行程仍可能無法存取，除非你啟用了 ``SeDebugPrivilege`` 權限。" + +#: ../../howto/remote_debugging.rst:64 +msgid "" +"To resolve file or folder access issues, adjust the security permissions:" +msgstr "要解決檔案或資料夾存取問題，請調整安全權限：" + +#: ../../howto/remote_debugging.rst:66 +msgid "Right-click the file or folder and select **Properties**." +msgstr "右鍵點擊檔案或資料夾並選擇 **Properties**。" + +#: ../../howto/remote_debugging.rst:67 +msgid "Go to the **Security** tab to view users and groups with access." +msgstr "前往 **Security** 分頁以檢視具有存取權限的使用者和群組。" + +#: ../../howto/remote_debugging.rst:68 +msgid "Click **Edit** to modify permissions." +msgstr "點擊 **Edit** 以修改權限。" + +#: ../../howto/remote_debugging.rst:69 +msgid "Select your user account." +msgstr "選擇你的使用者帳戶。" + +#: ../../howto/remote_debugging.rst:70 +msgid "In **Permissions**, check **Read** or **Full control** as needed." +msgstr "在 **Permissions** 中，視需要勾選 **Read** 或 **Full control**。" + +#: ../../howto/remote_debugging.rst:71 +msgid "Click **Apply**, then **OK** to confirm." +msgstr "點擊 **Apply**，然後點擊 **OK** 來確認。" + +#: ../../howto/remote_debugging.rst:76 +msgid "" +"Ensure you've satisfied all :ref:`permission-requirements` before proceeding." +msgstr "在繼續之前，請確保你已滿足所有 :ref:`permission-requirements`。" + +#: ../../howto/remote_debugging.rst:78 +msgid "" +"This section describes the low-level protocol that enables external tools to " +"inject and execute a Python script within a running CPython process." +msgstr "本節描述了低階協定，使外部工具能夠在正在執行的 CPython 行程中注入並執行 Python 腳本。" + +#: ../../howto/remote_debugging.rst:81 +msgid "" +"This mechanism forms the basis of the :func:`sys.remote_exec` function, " +"which instructs a remote Python process to execute a ``.py`` file. However, " +"this section does not document the usage of that function. Instead, it " +"provides a detailed explanation of the underlying protocol, which takes as " +"input the ``pid`` of a target Python process and the path to a Python source " +"file to be executed. This information supports independent reimplementation " +"of the protocol, regardless of programming language." +msgstr "" +"此機制構成了 :func:`sys.remote_exec` 函式的基礎，該函式指示遠端 Python 行程執行 ``.py`` " +"檔案。但本節不記錄該函式的用法，而是提供底層協定的詳細說明，該協定以目標 Python 行程的 " +"``pid`` 和要執行的 Python 原始檔路徑作為輸入。此資訊支援該協定的獨立重新實作，無論使用何種程式語言。" + +#: ../../howto/remote_debugging.rst:91 +msgid "" +"The execution of the injected script depends on the interpreter reaching a " +"safe evaluation point. As a result, execution may be delayed depending on " +"the runtime state of the target process." +msgstr "" +"注入腳本的執行取決於直譯器是否到達安全執行點 (safe evaluation point)。因此，執行可能會根據" +"目標行程的 runtime 狀態而延遲。" + +#: ../../howto/remote_debugging.rst:95 +msgid "" +"Once injected, the script is executed by the interpreter within the target " +"process the next time a safe evaluation point is reached. This approach " +"enables remote execution capabilities without modifying the behavior or " +"structure of the running Python application." +msgstr "" +"一旦注入，腳本將在下次到達安全執行點時會由目標行程內的直譯器執行。這種方法使遠端執行功能成為可能，" +"而不需修改正在執行的 Python 應用程式的行為或結構。" + +#: ../../howto/remote_debugging.rst:100 +msgid "" +"Subsequent sections provide a step-by-step description of the protocol, " +"including techniques for locating interpreter structures in memory, safely " +"accessing internal fields, and triggering code execution. Platform-specific " +"variations are noted where applicable, and example implementations are " +"included to clarify each operation." +msgstr "" +"後續章節提供了協定的逐步描述，包括在記憶體中定位直譯器結構、安全存取內部欄位以及觸發程式碼執行的技術。" +"在適用的情況下會註明平台特有的變化，並包含範例實作以闡明每個操作。" + +#: ../../howto/remote_debugging.rst:107 +msgid "Locating the PyRuntime structure" +msgstr "定位 PyRuntime 結構" + +#: ../../howto/remote_debugging.rst:109 +msgid "" +"CPython places the ``PyRuntime`` structure in a dedicated binary section to " +"help external tools find it at runtime. The name and format of this section " +"vary by platform. For example, ``.PyRuntime`` is used on ELF systems, and " +"``__DATA,__PyRuntime`` is used on macOS. Tools can find the offset of this " +"structure by examining the binary on disk." +msgstr "" +"CPython 將 ``PyRuntime`` 結構放置在專用的二進位區段（section）中，以幫助外部工具在 " +"runtime 找到它。此區段的名稱和格式因平台而異。例如，ELF 系統使用 ``.PyRuntime``、macOS " +"使用 ``__DATA,__PyRuntime``。工具可以透過檢查磁碟上的二進位檔案來找到此結構的偏移量。" + +#: ../../howto/remote_debugging.rst:115 +msgid "" +"The ``PyRuntime`` structure contains CPython’s global interpreter state and " +"provides access to other internal data, including the list of interpreters, " +"thread states, and debugger support fields." +msgstr "" +"``PyRuntime`` 結構包含 CPython 的全域直譯器狀態，並可存取其他內部資料，" +"包括直譯器清單、執行緒狀態和偵錯器支援欄位。" + +#: ../../howto/remote_debugging.rst:119 +msgid "" +"To work with a remote Python process, a debugger must first find the memory " +"address of the ``PyRuntime`` structure in the target process. This address " +"can’t be hardcoded or calculated from a symbol name, because it depends on " +"where the operating system loaded the binary." +msgstr "" +"要與遠端 Python 行程協作，偵錯器必須首先找到目標行程中 ``PyRuntime`` 結構的記憶體位址。" +"此位址無法寫死或從符號名稱計算出，因為它取決於作業系統載入二進位檔案的位置。" + +#: ../../howto/remote_debugging.rst:124 +msgid "" +"The method for finding ``PyRuntime`` depends on the platform, but the steps " +"are the same in general:" +msgstr "尋找 ``PyRuntime`` 的方法取決於平台，但步驟大致相同：" + +#: ../../howto/remote_debugging.rst:127 +msgid "" +"Find the base address where the Python binary or shared library was loaded " +"in the target process." +msgstr "找到目標行程中 Python 二進位檔案或共享函式庫被載入的基底位址。" + +#: ../../howto/remote_debugging.rst:129 +msgid "" +"Use the on-disk binary to locate the offset of the ``.PyRuntime`` section." +msgstr "使用磁碟上的二進位檔案來定位 ``.PyRuntime`` 區段的偏移量。" + +#: ../../howto/remote_debugging.rst:130 +msgid "" +"Add the section offset to the base address to compute the address in memory." +msgstr "將區段偏移量加到基底位址以計算記憶體中的位址。" + +#: ../../howto/remote_debugging.rst:132 +msgid "" +"The sections below explain how to do this on each supported platform and " +"include example code." +msgstr "以下各節說明如何在每個支援的平台上執行此操作，並包含範例程式碼。" + +#: ../../howto/remote_debugging.rst:136 +msgid "Linux (ELF)" +msgstr "Linux (ELF)" + +#: ../../howto/remote_debugging.rst:137 +msgid "To find the ``PyRuntime`` structure on Linux:" +msgstr "在 Linux 上尋找 ``PyRuntime`` 結構：" + +#: ../../howto/remote_debugging.rst:139 +msgid "" +"Read the process’s memory map (for example, ``/proc//maps``) to find " +"the address where the Python executable or ``libpython`` was loaded." +msgstr "" +"讀取行程的記憶體對映（例如 ``/proc//maps``）以找到 Python 可執行檔位址或 " +"``libpython`` 被載入的位址。" + +#: ../../howto/remote_debugging.rst:141 +msgid "" +"Parse the ELF section headers in the binary to get the offset of the ``." +"PyRuntime`` section." +msgstr "剖析二進位檔案中的 ELF 區段標頭以取得 ``.PyRuntime`` 區段的偏移量。" + +#: ../../howto/remote_debugging.rst:143 +msgid "" +"Add that offset to the base address from step 1 to get the memory address of " +"``PyRuntime``." +msgstr "將該偏移量加到步驟 1 的基底位址以取得 ``PyRuntime`` 的記憶體位址。" + +#: ../../howto/remote_debugging.rst:146 ../../howto/remote_debugging.rst:208 +#: ../../howto/remote_debugging.rst:278 ../../howto/remote_debugging.rst:547 +msgid "The following is an example implementation::" +msgstr "以下是一個範例實作： ::" + +#: ../../howto/remote_debugging.rst:148 +msgid "" +"def find_py_runtime_linux(pid: int) -> int:\n" +" # Step 1: Try to find the Python executable in memory\n" +" binary_path, base_address = find_mapped_binary(\n" +" pid, name_contains=\"python\"\n" +" )\n" +"\n" +" # Step 2: Fallback to shared library if executable is not found\n" +" if binary_path is None:\n" +" binary_path, base_address = find_mapped_binary(\n" +" pid, name_contains=\"libpython\"\n" +" )\n" +"\n" +" # Step 3: Parse ELF headers to get .PyRuntime section offset\n" +" section_offset = parse_elf_section_offset(\n" +" binary_path, \".PyRuntime\"\n" +" )\n" +"\n" +" # Step 4: Compute PyRuntime address in memory\n" +" return base_address + section_offset" +msgstr "" +"def find_py_runtime_linux(pid: int) -> int:\n" +" # 步驟 1：嘗試在記憶體中找到 Python 可執行檔\n" +" binary_path, base_address = find_mapped_binary(\n" +" pid, name_contains=\"python\"\n" +" )\n" +"\n" +" # 步驟 2：如果找不到可執行檔，則改用共享函式庫\n" +" if binary_path is None:\n" +" binary_path, base_address = find_mapped_binary(\n" +" pid, name_contains=\"libpython\"\n" +" )\n" +"\n" +" # 步驟 3：剖析 ELF 標頭以取得 .PyRuntime 區段偏移量\n" +" section_offset = parse_elf_section_offset(\n" +" binary_path, \".PyRuntime\"\n" +" )\n" +"\n" +" # 步驟 4：計算 PyRuntime 在記憶體中的位址\n" +" return base_address + section_offset" + +#: ../../howto/remote_debugging.rst:169 +msgid "" +"On Linux systems, there are two main approaches to read memory from another " +"process. The first is through the ``/proc`` filesystem, specifically by " +"reading from ``/proc/[pid]/mem`` which provides direct access to the " +"process's memory. This requires appropriate permissions - either being the " +"same user as the target process or having root access. The second approach " +"is using the ``process_vm_readv()`` system call which provides a more " +"efficient way to copy memory between processes. While ptrace's " +"``PTRACE_PEEKTEXT`` operation can also be used to read memory, it is " +"significantly slower as it only reads one word at a time and requires " +"multiple context switches between the tracer and tracee processes." +msgstr "" +"在 Linux 系統上，有兩種主要方法可以從另一個行程讀取記憶體。第一種是透過 ``/proc`` " +"檔案系統，特別是從 ``/proc/[pid]/mem`` 讀取，這提供了對行程記憶體的直接存取。這需要" +"適當的權限 - 要麼與目標行程是同一使用者，要麼就要擁有 root 存取權限。第二種方法是使用 " +"``process_vm_readv()`` 系統呼叫，它提供了在行程之間複製記憶體的更有效方式。雖然 ptrace " +"的 ``PTRACE_PEEKTEXT`` 操作也可以用來讀取記憶體，但它明顯較慢，因為它一次只讀取一個字，" +"並且需要追蹤器和被追蹤行程之間的多次情境切換。" + +#: ../../howto/remote_debugging.rst:180 +msgid "" +"For parsing ELF sections, the process involves reading and interpreting the " +"ELF file format structures from the binary file on disk. The ELF header " +"contains a pointer to the section header table. Each section header contains " +"metadata about a section including its name (stored in a separate string " +"table), offset, and size. To find a specific section like .PyRuntime, you " +"need to walk through these headers and match the section name. The section " +"header then provides the offset where that section exists in the file, which " +"can be used to calculate its runtime address when the binary is loaded into " +"memory." +msgstr "" +"對於剖析 ELF 區段，該過程涉及從磁碟上的二進位檔案讀取並解釋 ELF 檔案格式結構。ELF" +"標頭包含指向區段標頭表的指標。每個區段標頭包含關於區段的中介資料，包括其名稱（儲存在單獨" +"的字串表中）、偏移量和大小。要找到像 .PyRuntime 這樣的特定區段，你需要遍歷這些標頭並匹" +"配區段名稱。然後區段標頭會提供該區段在檔案中存在的偏移量，當二進位檔案載入到記憶體時，" +"可以用它來計算 runtime 位址。" + +#: ../../howto/remote_debugging.rst:189 +msgid "" +"You can read more about the ELF file format in the `ELF specification " +"`_." +msgstr "" +"你可以在 `ELF 規範 `_\\ " +"中閱讀更多關於 ELF 檔案格式的資訊。" + +#: ../../howto/remote_debugging.rst:194 +msgid "macOS (Mach-O)" +msgstr "macOS (Mach-O)" + +#: ../../howto/remote_debugging.rst:195 +msgid "To find the ``PyRuntime`` structure on macOS:" +msgstr "在 macOS 上找 ``PyRuntime`` 結構：" + +#: ../../howto/remote_debugging.rst:197 +msgid "" +"Call ``task_for_pid()`` to get the ``mach_port_t`` task port for the target " +"process. This handle is needed to read memory using APIs like " +"``mach_vm_read_overwrite`` and ``mach_vm_region``." +msgstr "" +"呼叫 ``task_for_pid()`` 以取得目標行程的 ``mach_port_t`` 任務埠 (task port)。" +"此控制代碼 (handle) 用於使用像 ``mach_vm_read_overwrite`` 和 ``mach_vm_region`` " +"這樣的 API 來讀取記憶體。" + +#: ../../howto/remote_debugging.rst:200 +msgid "" +"Scan the memory regions to find the one containing the Python executable or " +"``libpython``." +msgstr "掃描記憶體區域以找到包含 Python 可執行檔或 ``libpython`` 的區域。" + +#: ../../howto/remote_debugging.rst:202 +msgid "" +"Load the binary file from disk and parse the Mach-O headers to find the " +"section named ``PyRuntime`` in the ``__DATA`` segment. On macOS, symbol " +"names are automatically prefixed with an underscore, so the ``PyRuntime`` " +"symbol appears as ``_PyRuntime`` in the symbol table, but the section name " +"is not affected." +msgstr "" +"從磁碟載入二進位檔案並剖析 Mach-O 標頭以找到 ``__DATA`` 程式段（segment）中名為 " +"``PyRuntime`` 的區段。在 macOS 上，符號名稱會自動加上底線前綴，因此 ``PyRuntime`` " +"符號在符號表中顯示為 ``_PyRuntime``，但區段名稱不受影響。" + +#: ../../howto/remote_debugging.rst:210 +msgid "" +"def find_py_runtime_macos(pid: int) -> int:\n" +" # Step 1: Get access to the process's memory\n" +" handle = get_memory_access_handle(pid)\n" +"\n" +" # Step 2: Try to find the Python executable in memory\n" +" binary_path, base_address = find_mapped_binary(\n" +" handle, name_contains=\"python\"\n" +" )\n" +"\n" +" # Step 3: Fallback to libpython if the executable is not found\n" +" if binary_path is None:\n" +" binary_path, base_address = find_mapped_binary(\n" +" handle, name_contains=\"libpython\"\n" +" )\n" +"\n" +" # Step 4: Parse Mach-O headers to get __DATA,__PyRuntime section offset\n" +" section_offset = parse_macho_section_offset(\n" +" binary_path, \"__DATA\", \"__PyRuntime\"\n" +" )\n" +"\n" +" # Step 5: Compute the PyRuntime address in memory\n" +" return base_address + section_offset" +msgstr "" +"def find_py_runtime_macos(pid: int) -> int:\n" +" # 步驟 1：取得對行程記憶體的存取權限\n" +" handle = get_memory_access_handle(pid)\n" +"\n" +" # 步驟 2：嘗試在記憶體中找到 Python 可執行檔\n" +" binary_path, base_address = find_mapped_binary(\n" +" handle, name_contains=\"python\"\n" +" )\n" +"\n" +" # 步驟 3：如果找不到可執行檔，則改用 libpython\n" +" if binary_path is None:\n" +" binary_path, base_address = find_mapped_binary(\n" +" handle, name_contains=\"libpython\"\n" +" )\n" +"\n" +" # 步驟 4：剖析 Mach-O 標頭以取得 __DATA,__PyRuntime 區段偏移量\n" +" section_offset = parse_macho_section_offset(\n" +" binary_path, \"__DATA\", \"__PyRuntime\"\n" +" )\n" +"\n" +" # 步驟 5：計算 PyRuntime 在記憶體中的位址\n" +" return base_address + section_offset" + +#: ../../howto/remote_debugging.rst:233 +msgid "" +"On macOS, accessing another process's memory requires using Mach-O specific " +"APIs and file formats. The first step is obtaining a ``task_port`` handle " +"via ``task_for_pid()``, which provides access to the target process's memory " +"space. This handle enables memory operations through APIs like " +"``mach_vm_read_overwrite()``." +msgstr "" +"在 macOS 上，存取另一個行程的記憶體需要使用 Mach-O 特定的 API 和檔案格式。第一步是透過 " +"``task_for_pid()`` 取得 ``task_port`` 控制代碼，它提供對目標行程記憶體空間的存取。" +"此控制代碼透過像 ``mach_vm_read_overwrite()`` 這樣的 API 啟用記憶體操作。" + +#: ../../howto/remote_debugging.rst:239 +msgid "" +"The process memory can be examined using ``mach_vm_region()`` to scan " +"through the virtual memory space, while ``proc_regionfilename()`` helps " +"identify which binary files are loaded at each memory region. When the " +"Python binary or library is found, its Mach-O headers need to be parsed to " +"locate the ``PyRuntime`` structure." +msgstr "" +"可以使用 ``mach_vm_region()`` 掃描虛擬記憶體空間來檢查行程記憶體，而 ``proc_regionfilename()`` " +"幫助識別在每個記憶體區域載入了哪些二進位檔案。當找到 Python 二進位檔案或函式庫時，需要剖析其 Mach-O " +"標頭以定位 ``PyRuntime`` 結構。" + +#: ../../howto/remote_debugging.rst:244 +msgid "" +"The Mach-O format organizes code and data into segments and sections. The " +"``PyRuntime`` structure lives in a section named ``__PyRuntime`` within the " +"``__DATA`` segment. The actual runtime address calculation involves finding " +"the ``__TEXT`` segment which serves as the binary's base address, then " +"locating the ``__DATA`` segment containing our target section. The final " +"address is computed by combining the base address with the appropriate " +"section offsets from the Mach-O headers." +msgstr "" +"Mach-O 格式將程式碼和資料組織成程式段和區段。``PyRuntime`` 結構位於 ``__DATA`` 程式段內名" +"為 ``__PyRuntime`` 的區段中。實際的 runtime 位址計算涉及找到作為二進位檔案基底位址的 ``__TEXT`` " +"程式段，然後定位包含我們目標區段的 ``__DATA`` 程式段。最終位址是透過將基底位址與來自 Mach-O " +"標頭的適當區段偏移量組合來計算的。" + +#: ../../howto/remote_debugging.rst:252 +msgid "" +"Note that accessing another process's memory on macOS typically requires " +"elevated privileges - either root access or special security entitlements " +"granted to the debugging process." +msgstr "" +"請注意，在 macOS 上存取另一個行程的記憶體通常需要提升過後的權限 - " +"要麼是 root 存取權限，要麼是授予偵錯行程的特殊安全授權。" + +#: ../../howto/remote_debugging.rst:258 +msgid "Windows (PE)" +msgstr "Windows (PE)" + +#: ../../howto/remote_debugging.rst:259 +msgid "To find the ``PyRuntime`` structure on Windows:" +msgstr "在 Windows 上找 ``PyRuntime`` 結構：" + +#: ../../howto/remote_debugging.rst:261 +msgid "" +"Use the ToolHelp API to enumerate all modules loaded in the target process. " +"This is done using functions such as `CreateToolhelp32Snapshot `_, `Module32First `_, and " +"`Module32Next `_." +msgstr "" +"使用 ToolHelp API 來列舉目標行程中載入的所有模組。這是使用諸如 `CreateToolhelp32Snapshot " +"`_、`Module32First `_ 和 " +"`Module32Next `_ 等函式來完成的。" + +#: ../../howto/remote_debugging.rst:268 +msgid "" +"Identify the module corresponding to :file:`python.exe` or :file:`python{XY}." +"dll`, where ``X`` and ``Y`` are the major and minor version numbers of the " +"Python version, and record its base address." +msgstr "" +"識別對應於 :file:`python.exe` 或 :file:`python{XY}.dll` 的模組，其中 ``X`` 和 ``Y`` 是" +"Python 版本的主要和次要版本號，並記錄其基底位址。" + +#: ../../howto/remote_debugging.rst:271 +msgid "" +"Locate the ``PyRuntim`` section. Due to the PE format's 8-character limit on " +"section names (defined as ``IMAGE_SIZEOF_SHORT_NAME``), the original name " +"``PyRuntime`` is truncated. This section contains the ``PyRuntime`` " +"structure." +msgstr "" +"定位 ``PyRuntim`` 區段。由於 PE 格式對區段名稱有 8 個字元的限制（定義為 " +"``IMAGE_SIZEOF_SHORT_NAME``），所以原始名稱 ``PyRuntime`` 會被截斷。此區段包含 " +"``PyRuntime`` 結構。" + +#: ../../howto/remote_debugging.rst:275 +msgid "" +"Retrieve the section’s relative virtual address (RVA) and add it to the base " +"address of the module." +msgstr "檢索區段的相對虛擬位址 (RVA, relative virtual address) 並將其加到模組的基底位址。" + +#: ../../howto/remote_debugging.rst:280 +msgid "" +"def find_py_runtime_windows(pid: int) -> int:\n" +" # Step 1: Try to find the Python executable in memory\n" +" binary_path, base_address = find_loaded_module(\n" +" pid, name_contains=\"python\"\n" +" )\n" +"\n" +" # Step 2: Fallback to shared pythonXY.dll if the executable is not\n" +" # found\n" +" if binary_path is None:\n" +" binary_path, base_address = find_loaded_module(\n" +" pid, name_contains=\"python3\"\n" +" )\n" +"\n" +" # Step 3: Parse PE section headers to get the RVA of the PyRuntime\n" +" # section. The section name appears as \"PyRuntim\" due to the\n" +" # 8-character limit defined by the PE format (IMAGE_SIZEOF_SHORT_NAME).\n" +" section_rva = parse_pe_section_offset(binary_path, \"PyRuntim\")\n" +"\n" +" # Step 4: Compute PyRuntime address in memory\n" +" return base_address + section_rva" +msgstr "" +"def find_py_runtime_windows(pid: int) -> int:\n" +" # 步驟 1：嘗試在記憶體中找到 Python 可執行檔\n" +" binary_path, base_address = find_loaded_module(\n" +" pid, name_contains=\"python\"\n" +" )\n" +"\n" +" # 步驟 2：如果找不到可執行檔，則改用共享函式庫 pythonXY.dll\n" +" if binary_path is None:\n" +" binary_path, base_address = find_loaded_module(\n" +" pid, name_contains=\"python3\"\n" +" )\n" +"\n" +" # 步驟 3：剖析 PE 區段標頭以取得 PyRuntime 區段的 RVA。\n" +" # 由於 PE 格式 (IMAGE_SIZEOF_SHORT_NAME) 有8 字元的限制，\n" +" # 區段名稱顯示為 \"PyRuntim\"。\n" +" section_rva = parse_pe_section_offset(binary_path, \"PyRuntim\")\n" +"\n" +" # 步驟 4：計算 PyRuntime 在記憶體中的位址\n" +" return base_address + section_rva" + +#: ../../howto/remote_debugging.rst:302 +msgid "" +"On Windows, accessing another process's memory requires using the Windows " +"API functions like ``CreateToolhelp32Snapshot()`` and ``Module32First()/" +"Module32Next()`` to enumerate loaded modules. The ``OpenProcess()`` function " +"provides a handle to access the target process's memory space, enabling " +"memory operations through ``ReadProcessMemory()``." +msgstr "" +"在 Windows 上，存取另一個行程的記憶體需要使用像 ``CreateToolhelp32Snapshot()`` 和 " +"``Module32First()/Module32Next()`` 這樣的 Windows API 函式來列舉載入的模組。" +"``OpenProcess()`` 函式提供一個控制代碼來存取目標行程的記憶體空間，並透過 " +"``ReadProcessMemory()`` 啟用記憶體操作。" + +#: ../../howto/remote_debugging.rst:308 +msgid "" +"The process memory can be examined by enumerating loaded modules to find the " +"Python binary or DLL. When found, its PE headers need to be parsed to locate " +"the ``PyRuntime`` structure." +msgstr "" +"可以透過列舉載入的模組來檢查行程記憶體，以找到 Python 二進位檔案或 DLL。找到後，需要剖析其 PE " +"標頭以定位 ``PyRuntime`` 結構。" + +#: ../../howto/remote_debugging.rst:312 +msgid "" +"The PE format organizes code and data into sections. The ``PyRuntime`` " +"structure lives in a section named \"PyRuntim\" (truncated from " +"\"PyRuntime\" due to PE's 8-character name limit). The actual runtime " +"address calculation involves finding the module's base address from the " +"module entry, then locating our target section in the PE headers. The final " +"address is computed by combining the base address with the section's virtual " +"address from the PE section headers." +msgstr "" +"PE 格式將程式碼和資料組織成區段。``PyRuntime`` 結構位於名為 \"PyRuntim\" " +"的區段中（由於 PE 的 8 字元名稱限制，從 \"PyRuntime\" 截斷）。實際的 runtime " +"位址計算涉及從模組項目中找到模組的基底位址，然後在 PE 標頭中定位我們的目標區段。" +"最終位址是透過將基底位址與 PE 區段標頭中的區段虛擬位址組合來計算的。" + +#: ../../howto/remote_debugging.rst:319 +msgid "" +"Note that accessing another process's memory on Windows typically requires " +"appropriate privileges - either administrative access or the " +"``SeDebugPrivilege`` privilege granted to the debugging process." +msgstr "" +"請注意，在 Windows 上存取另一個行程的記憶體通常需要適當的權限 - 要麼是系統管理員存取權限" +"，要麼是授予偵錯行程的 ``SeDebugPrivilege`` 權限。" + +#: ../../howto/remote_debugging.rst:325 +msgid "Reading _Py_DebugOffsets" +msgstr "讀取 _Py_DebugOffsets" + +#: ../../howto/remote_debugging.rst:327 +msgid "" +"Once the address of the ``PyRuntime`` structure has been determined, the " +"next step is to read the ``_Py_DebugOffsets`` structure located at the " +"beginning of the ``PyRuntime`` block." +msgstr "" +"一旦確定了 ``PyRuntime`` 結構的位址，下一步就是讀取位於 ``PyRuntime`` 區塊開頭的 " +"``_Py_DebugOffsets`` 結構。" + +#: ../../howto/remote_debugging.rst:331 +msgid "" +"This structure provides version-specific field offsets that are needed to " +"safely read interpreter and thread state memory. These offsets vary between " +"CPython versions and must be checked before use to ensure they are " +"compatible." +msgstr "" +"此結構提供了安全讀取直譯器和執行緒狀態記憶體所需的版本特定欄位偏移量。這些偏移量在不同的 CPython " +"版本之間有所不同，必須在使用前檢查以確保它們相容。" + +#: ../../howto/remote_debugging.rst:335 +msgid "To read and check the debug offsets, follow these steps:" +msgstr "要讀取並檢查偵錯偏移量，請按照以下步驟操作：" + +#: ../../howto/remote_debugging.rst:337 +msgid "" +"Read memory from the target process starting at the ``PyRuntime`` address, " +"covering the same number of bytes as the ``_Py_DebugOffsets`` structure. " +"This structure is located at the very start of the ``PyRuntime`` memory " +"block. Its layout is defined in CPython’s internal headers and stays the " +"same within a given minor version, but may change in major versions." +msgstr "" +"從目標行程中的 ``PyRuntime`` 位址開始讀取記憶體，涵蓋與 ``_Py_DebugOffsets`` 結構相同的位元組數。" +"此結構位於 ``PyRuntime`` 記憶體區塊的最開始處。" +"其佈局 (layout) 在 CPython 的內部標頭中定義，並在給定的次要版本中維持不變，但在主要版本中可能會更改。" + +#: ../../howto/remote_debugging.rst:343 +msgid "Check that the structure contains valid data:" +msgstr "檢查結構是否包含有效資料：" + +#: ../../howto/remote_debugging.rst:345 +msgid "The ``cookie`` field must match the expected debug marker." +msgstr "``cookie`` 欄位必須匹配預期的偵錯標記。" + +#: ../../howto/remote_debugging.rst:346 +msgid "" +"The ``version`` field must match the version of the Python interpreter used " +"by the debugger." +msgstr "``version`` 欄位必須匹配偵錯器使用的 Python 直譯器版本。" + +#: ../../howto/remote_debugging.rst:348 +msgid "" +"If either the debugger or the target process is using a pre-release version " +"(for example, an alpha, beta, or release candidate), the versions must match " +"exactly." +msgstr "如果偵錯器或目標行程使用的是預發行版本（例如 alpha、beta 或候選版本），版本必須完全匹配。" + +#: ../../howto/remote_debugging.rst:351 +msgid "" +"The ``free_threaded`` field must have the same value in both the debugger " +"and the target process." +msgstr "``free_threaded`` 欄位在偵錯器和目標行程中必須具有相同的值。" + +#: ../../howto/remote_debugging.rst:354 +msgid "" +"If the structure is valid, the offsets it contains can be used to locate " +"fields in memory. If any check fails, the debugger should stop the operation " +"to avoid reading memory in the wrong format." +msgstr "" +"如果結構有效，其中包含的偏移量可用於定位記憶體中的欄位。如果任何檢查失敗，偵錯器應停止操作" +"以避免以錯誤的格式讀取記憶體。" + +#: ../../howto/remote_debugging.rst:358 +msgid "" +"The following is an example implementation that reads and checks " +"``_Py_DebugOffsets``::" +msgstr "以下是一個讀取並檢查 ``_Py_DebugOffsets`` 的範例實作： ::" + +#: ../../howto/remote_debugging.rst:361 +msgid "" +"def read_debug_offsets(pid: int, py_runtime_addr: int) -> DebugOffsets:\n" +" # Step 1: Read memory from the target process at the PyRuntime address\n" +" data = read_process_memory(\n" +" pid, address=py_runtime_addr, size=DEBUG_OFFSETS_SIZE\n" +" )\n" +"\n" +" # Step 2: Deserialize the raw bytes into a _Py_DebugOffsets structure\n" +" debug_offsets = parse_debug_offsets(data)\n" +"\n" +" # Step 3: Validate the contents of the structure\n" +" if debug_offsets.cookie != EXPECTED_COOKIE:\n" +" raise RuntimeError(\"Invalid or missing debug cookie\")\n" +" if debug_offsets.version != LOCAL_PYTHON_VERSION:\n" +" raise RuntimeError(\n" +" \"Mismatch between caller and target Python versions\"\n" +" )\n" +" if debug_offsets.free_threaded != LOCAL_FREE_THREADED:\n" +" raise RuntimeError(\"Mismatch in free-threaded configuration\")\n" +"\n" +" return debug_offsets" +msgstr "" +"def read_debug_offsets(pid: int, py_runtime_addr: int) -> DebugOffsets:\n" +" # 步驟 1：在 PyRuntime 位址從目標行程讀取記憶體\n" +" data = read_process_memory(\n" +" pid, address=py_runtime_addr, size=DEBUG_OFFSETS_SIZE\n" +" )\n" +"\n" +" # 步驟 2：將原始位元組反序列化為 _Py_DebugOffsets 結構\n" +" debug_offsets = parse_debug_offsets(data)\n" +"\n" +" # 步驟 3：驗證結構的內容\n" +" if debug_offsets.cookie != EXPECTED_COOKIE:\n" +" raise RuntimeError(\"Invalid or missing debug cookie\")\n" +" if debug_offsets.version != LOCAL_PYTHON_VERSION:\n" +" raise RuntimeError(\n" +" \"Mismatch between caller and target Python versions\"\n" +" )\n" +" if debug_offsets.free_threaded != LOCAL_FREE_THREADED:\n" +" raise RuntimeError(\"Mismatch in free-threaded configuration\")\n" +"\n" +" return debug_offsets" + +#: ../../howto/remote_debugging.rst:386 +msgid "**Process suspension recommended**" +msgstr "**建議暫停行程**" + +#: ../../howto/remote_debugging.rst:388 +msgid "" +"To avoid race conditions and ensure memory consistency, it is strongly " +"recommended that the target process be suspended before performing any " +"operations that read or write internal interpreter state. The Python runtime " +"may concurrently mutate interpreter data structures—such as creating or " +"destroying threads—during normal execution. This can result in invalid " +"memory reads or writes." +msgstr "" +"為了避免競態條件 (race conditions) 並確保記憶體一致性，強烈建議在執行任何讀取或寫入" +"內部直譯器狀態的操作之前暫停目標行程。Python runtime 可能在正常執行期間同時變更直譯器" +"資料結構 - 例如建立或銷毀執行緒。這可能導致無效的記憶體讀取或寫入。" + +#: ../../howto/remote_debugging.rst:395 +msgid "" +"A debugger may suspend execution by attaching to the process with ``ptrace`` " +"or by sending a ``SIGSTOP`` signal. Execution should only be resumed after " +"debugger-side memory operations are complete." +msgstr "" +"偵錯器可以透過使用 ``ptrace`` 附加到行程或發送 ``SIGSTOP`` 訊號來暫停執行。只有在偵錯器" +"端的記憶體操作完成後才應恢復執行。" + +#: ../../howto/remote_debugging.rst:401 +msgid "" +"Some tools, such as profilers or sampling-based debuggers, may operate on a " +"running process without suspension. In such cases, tools must be explicitly " +"designed to handle partially updated or inconsistent memory. For most " +"debugger implementations, suspending the process remains the safest and most " +"robust approach." +msgstr "" +"一些工具，例如分析器 (profilers) 或基於取樣的偵錯器，可能在不暫停的情況下對正在執行的行程" +"進行操作。在這種情況下，工具必須明確設計為能夠處理部分更新或不一致的記憶體。對於大多數偵錯器" +"實作來說，暫停行程仍然是最安全可靠的方法。" + +#: ../../howto/remote_debugging.rst:409 +msgid "Locating the interpreter and thread state" +msgstr "定位直譯器和執行緒狀態" + +#: ../../howto/remote_debugging.rst:411 +msgid "" +"Before code can be injected and executed in a remote Python process, the " +"debugger must choose a thread in which to schedule execution. This is " +"necessary because the control fields used to perform remote code injection " +"are located in the ``_PyRemoteDebuggerSupport`` structure, which is embedded " +"in a ``PyThreadState`` object. These fields are modified by the debugger to " +"request execution of injected scripts." +msgstr "" +"在可以於遠端 Python 行程中注入並執行程式碼之前，偵錯器必須選擇一個用於排程執行的執行緒。" +"這是必要的，因為用於執行遠端程式碼注入的控制欄位位於 ``_PyRemoteDebuggerSupport`` " +"結構中，該結構嵌入在 ``PyThreadState`` 物件中。偵錯器會修改這些欄位以請求執行注入的腳本。" + +#: ../../howto/remote_debugging.rst:418 +msgid "" +"The ``PyThreadState`` structure represents a thread running inside a Python " +"interpreter. It maintains the thread’s evaluation context and contains the " +"fields required for debugger coordination. Locating a valid " +"``PyThreadState`` is therefore a key prerequisite for triggering execution " +"remotely." +msgstr "" +"``PyThreadState`` 結構代表在 Python 直譯器內執行的執行緒。它維護執行緒的求值情境 " +"(evaluation context)，並包含偵錯器協調所需的欄位。因此，定位有效的 ``PyThreadState`` " +"是遠端觸發執行的關鍵前提。" + +#: ../../howto/remote_debugging.rst:423 +msgid "" +"A thread is typically selected based on its role or ID. In most cases, the " +"main thread is used, but some tools may target a specific thread by its " +"native thread ID. Once the target thread is chosen, the debugger must locate " +"both the interpreter and the associated thread state structures in memory." +msgstr "" +"通常根據執行緒的角色或 ID 來選擇執行緒。在大多數情況下會使用主執行緒，但某些工具可能會透過其原生執行緒 ID " +"來定位特定執行緒。一旦選擇了目標執行緒，偵錯器必須在記憶體中定位直譯器和相關的執行緒狀態結構。" + +#: ../../howto/remote_debugging.rst:428 +msgid "The relevant internal structures are defined as follows:" +msgstr "相關的內部結構定義如下：" + +#: ../../howto/remote_debugging.rst:430 +msgid "" +"``PyInterpreterState`` represents an isolated Python interpreter instance. " +"Each interpreter maintains its own set of imported modules, built-in state, " +"and thread state list. Although most Python applications use a single " +"interpreter, CPython supports multiple interpreters in the same process." +msgstr "" +"``PyInterpreterState`` 代表一個隔離的 Python 直譯器實例。每個直譯器維護自己的一組" +"已引入模組、內建狀態和執行緒狀態串列。雖然大多數 Python 應用程式使用單一直譯器，但 CPython " +"支援在同一行程中使用多個直譯器。" + +#: ../../howto/remote_debugging.rst:435 +msgid "" +"``PyThreadState`` represents a thread running within an interpreter. It " +"contains execution state and the control fields used by the debugger." +msgstr "``PyThreadState`` 代表在直譯器內運行的執行緒。它包含執行狀態和偵錯器使用的控制欄位。" + +#: ../../howto/remote_debugging.rst:438 +msgid "To locate a thread:" +msgstr "要定位執行緒：" + +#: ../../howto/remote_debugging.rst:440 +msgid "" +"Use the offset ``runtime_state.interpreters_head`` to obtain the address of " +"the first interpreter in the ``PyRuntime`` structure. This is the entry " +"point to the linked list of active interpreters." +msgstr "" +"使用偏移量 ``runtime_state.interpreters_head`` 來取得 ``PyRuntime`` " +"結構中第一個直譯器的位址。這是活動直譯器鏈結串列的進入點。" + +#: ../../howto/remote_debugging.rst:444 +msgid "" +"Use the offset ``interpreter_state.threads_main`` to access the main thread " +"state associated with the selected interpreter. This is typically the most " +"reliable thread to target." +msgstr "" +"使用偏移量 ``interpreter_state.threads_main`` 來存取與所選直譯器相關的主執行緒狀態。" +"這通常是最可靠的目標執行緒。" + +#: ../../howto/remote_debugging.rst:448 +msgid "" +"Optionally, use the offset ``interpreter_state.threads_head`` to iterate " +"through the linked list of all thread states. Each ``PyThreadState`` " +"structure contains a ``native_thread_id`` field, which may be compared to a " +"target thread ID to find a specific thread." +msgstr "" +"可選地使用偏移量 ``interpreter_state.threads_head`` 來遍歷所有執行緒狀態的鏈結串列。每個 " +"``PyThreadState`` 結構包含一個 ``native_thread_id`` 欄位，可以將其與目標執行緒 ID 進行比" +"較以找到特定執行緒。" + +#: ../../howto/remote_debugging.rst:453 +msgid "" +"Once a valid ``PyThreadState`` has been found, its address can be used in " +"later steps of the protocol, such as writing debugger control fields and " +"scheduling execution." +msgstr "" +"一旦找到有效的 ``PyThreadState``，其位址可以在協定的後續步驟中使用，例如寫入偵錯器控制欄位" +"和排程執行。" + +#: ../../howto/remote_debugging.rst:457 +msgid "" +"The following is an example implementation that locates the main thread " +"state::" +msgstr "以下是一個定位主執行緒狀態的範例實作： ::" + +#: ../../howto/remote_debugging.rst:459 +msgid "" +"def find_main_thread_state(\n" +" pid: int, py_runtime_addr: int, debug_offsets: DebugOffsets,\n" +") -> int:\n" +" # Step 1: Read interpreters_head from PyRuntime\n" +" interp_head_ptr = (\n" +" py_runtime_addr + debug_offsets.runtime_state.interpreters_head\n" +" )\n" +" interp_addr = read_pointer(pid, interp_head_ptr)\n" +" if interp_addr == 0:\n" +" raise RuntimeError(\"No interpreter found in the target process\")\n" +"\n" +" # Step 2: Read the threads_main pointer from the interpreter\n" +" threads_main_ptr = (\n" +" interp_addr + debug_offsets.interpreter_state.threads_main\n" +" )\n" +" thread_state_addr = read_pointer(pid, threads_main_ptr)\n" +" if thread_state_addr == 0:\n" +" raise RuntimeError(\"Main thread state is not available\")\n" +"\n" +" return thread_state_addr" +msgstr "" +"def find_main_thread_state(\n" +" pid: int, py_runtime_addr: int, debug_offsets: DebugOffsets,\n" +") -> int:\n" +" # 步驟 1：從 PyRuntime 讀取 interpreters_head\n" +" interp_head_ptr = (\n" +" py_runtime_addr + debug_offsets.runtime_state.interpreters_head\n" +" )\n" +" interp_addr = read_pointer(pid, interp_head_ptr)\n" +" if interp_addr == 0:\n" +" raise RuntimeError(\"No interpreter found in the target process\")\n" +"\n" +" # 步驟 2：從直譯器讀取 threads_main 指標\n" +" threads_main_ptr = (\n" +" interp_addr + debug_offsets.interpreter_state.threads_main\n" +" )\n" +" thread_state_addr = read_pointer(pid, threads_main_ptr)\n" +" if thread_state_addr == 0:\n" +" raise RuntimeError(\"Main thread state is not available\")\n" +"\n" +" return thread_state_addr" + +#: ../../howto/remote_debugging.rst:480 +msgid "" +"The following example demonstrates how to locate a thread by its native " +"thread ID::" +msgstr "以下範例示範如何透過原生執行緒 ID 來定位執行緒： ::" + +#: ../../howto/remote_debugging.rst:483 +msgid "" +"def find_thread_by_id(\n" +" pid: int,\n" +" interp_addr: int,\n" +" debug_offsets: DebugOffsets,\n" +" target_tid: int,\n" +") -> int:\n" +" # Start at threads_head and walk the linked list\n" +" thread_ptr = read_pointer(\n" +" pid,\n" +" interp_addr + debug_offsets.interpreter_state.threads_head\n" +" )\n" +"\n" +" while thread_ptr:\n" +" native_tid_ptr = (\n" +" thread_ptr + debug_offsets.thread_state.native_thread_id\n" +" )\n" +" native_tid = read_int(pid, native_tid_ptr)\n" +" if native_tid == target_tid:\n" +" return thread_ptr\n" +" thread_ptr = read_pointer(\n" +" pid,\n" +" thread_ptr + debug_offsets.thread_state.next\n" +" )\n" +"\n" +" raise RuntimeError(\"Thread with the given ID was not found\")" +msgstr "" +"def find_thread_by_id(\n" +" pid: int,\n" +" interp_addr: int,\n" +" debug_offsets: DebugOffsets,\n" +" target_tid: int,\n" +") -> int:\n" +" # 從 threads_head 開始並遍歷鏈結串列\n" +" thread_ptr = read_pointer(\n" +" pid,\n" +" interp_addr + debug_offsets.interpreter_state.threads_head\n" +" )\n" +"\n" +" while thread_ptr:\n" +" native_tid_ptr = (\n" +" thread_ptr + debug_offsets.thread_state.native_thread_id\n" +" )\n" +" native_tid = read_int(pid, native_tid_ptr)\n" +" if native_tid == target_tid:\n" +" return thread_ptr\n" +" thread_ptr = read_pointer(\n" +" pid,\n" +" thread_ptr + debug_offsets.thread_state.next\n" +" )\n" +"\n" +" raise RuntimeError(\"Thread with the given ID was not found\")" + +#: ../../howto/remote_debugging.rst:510 +msgid "" +"Once a valid thread state has been located, the debugger can proceed with " +"modifying its control fields and scheduling execution, as described in the " +"next section." +msgstr "一旦定位到有效的執行緒狀態，偵錯器就可以繼續修改其控制欄位並排程執行，如下一節所述。" + +#: ../../howto/remote_debugging.rst:515 +msgid "Writing control information" +msgstr "寫入控制資訊" + +#: ../../howto/remote_debugging.rst:517 +msgid "" +"Once a valid ``PyThreadState`` structure has been identified, the debugger " +"may modify control fields within it to schedule the execution of a specified " +"Python script. These control fields are checked periodically by the " +"interpreter, and when set correctly, they trigger the execution of remote " +"code at a safe point in the evaluation loop." +msgstr "" +"一旦識別出有效的 ``PyThreadState`` 結構，偵錯器就可以修改其中的控制欄位以排程執行指定的 Python " +"腳本。直譯器會定期檢查這些控制欄位，當正確設定時，它們會在求值迴圈中的安全點觸發遠端程式碼的執行。" + +#: ../../howto/remote_debugging.rst:523 +msgid "" +"Each ``PyThreadState`` contains a ``_PyRemoteDebuggerSupport`` structure " +"used for communication between the debugger and the interpreter. The " +"locations of its fields are defined by the ``_Py_DebugOffsets`` structure " +"and include the following:" +msgstr "" +"每個 ``PyThreadState`` 都包含一個 ``_PyRemoteDebuggerSupport`` 結構，" +"能用於偵錯器和直譯器之間的通訊。其欄位的位置由 ``_Py_DebugOffsets`` 結構定義，包括以下內容：" + +#: ../../howto/remote_debugging.rst:528 +msgid "" +"``debugger_script_path``: A fixed-size buffer that holds the full path to a " +"Python source file (``.py``). This file must be accessible and readable by " +"the target process when execution is triggered." +msgstr "" +"``debugger_script_path``：一個固定大小的緩衝區，用於保存 Python " +"原始檔（``.py``）的完整路徑。觸發執行時，目標行程必須能夠存取和讀取此檔案。" + +#: ../../howto/remote_debugging.rst:532 +msgid "" +"``debugger_pending_call``: An integer flag. Setting this to ``1`` tells the " +"interpreter that a script is ready to be executed." +msgstr "``debugger_pending_call``：一個整數旗標。將其設定為 ``1`` 會告訴直譯器腳本已準備好執行。" + +#: ../../howto/remote_debugging.rst:535 +msgid "" +"``eval_breaker``: A field checked by the interpreter during execution. " +"Setting bit 5 (``_PY_EVAL_PLEASE_STOP_BIT``, value ``1U << 5``) in this " +"field causes the interpreter to pause and check for debugger activity." +msgstr "" +"``eval_breaker``：直譯器在執行期間檢查的欄位。在此欄位中設定位元 5（``_PY_EVAL_PLEASE_STOP_BIT``，值 " +"``1U << 5``）會導致直譯器暫停並檢查偵錯器活動。" + +#: ../../howto/remote_debugging.rst:539 +msgid "" +"To complete the injection, the debugger must perform the following steps:" +msgstr "要完成注入，偵錯器必須執行以下步驟：" + +#: ../../howto/remote_debugging.rst:541 +msgid "Write the full script path into the ``debugger_script_path`` buffer." +msgstr "將完整的腳本路徑寫入 ``debugger_script_path`` 緩衝區。" + +#: ../../howto/remote_debugging.rst:542 +msgid "Set ``debugger_pending_call`` to ``1``." +msgstr "將 ``debugger_pending_call`` 設定為 ``1``。" + +#: ../../howto/remote_debugging.rst:543 +msgid "" +"Read the current value of ``eval_breaker``, set bit 5 " +"(``_PY_EVAL_PLEASE_STOP_BIT``), and write the updated value back. This " +"signals the interpreter to check for debugger activity." +msgstr "" +"讀取 ``eval_breaker`` 目前的值，設定位元 5（``_PY_EVAL_PLEASE_STOP_BIT``）" +"並將更新後的值寫回。這會向直譯器發出檢查偵錯器活動的訊號。" + +#: ../../howto/remote_debugging.rst:549 +msgid "" +"def inject_script(\n" +" pid: int,\n" +" thread_state_addr: int,\n" +" debug_offsets: DebugOffsets,\n" +" script_path: str\n" +") -> None:\n" +" # Compute the base offset of _PyRemoteDebuggerSupport\n" +" support_base = (\n" +" thread_state_addr +\n" +" debug_offsets.debugger_support.remote_debugger_support\n" +" )\n" +"\n" +" # Step 1: Write the script path into debugger_script_path\n" +" script_path_ptr = (\n" +" support_base +\n" +" debug_offsets.debugger_support.debugger_script_path\n" +" )\n" +" write_string(pid, script_path_ptr, script_path)\n" +"\n" +" # Step 2: Set debugger_pending_call to 1\n" +" pending_ptr = (\n" +" support_base +\n" +" debug_offsets.debugger_support.debugger_pending_call\n" +" )\n" +" write_int(pid, pending_ptr, 1)\n" +"\n" +" # Step 3: Set _PY_EVAL_PLEASE_STOP_BIT (bit 5, value 1 << 5) in\n" +" # eval_breaker\n" +" eval_breaker_ptr = (\n" +" thread_state_addr +\n" +" debug_offsets.debugger_support.eval_breaker\n" +" )\n" +" breaker = read_int(pid, eval_breaker_ptr)\n" +" breaker |= (1 << 5)\n" +" write_int(pid, eval_breaker_ptr, breaker)" +msgstr "" +"def inject_script(\n" +" pid: int,\n" +" thread_state_addr: int,\n" +" debug_offsets: DebugOffsets,\n" +" script_path: str\n" +") -> None:\n" +" # 計算 _PyRemoteDebuggerSupport 的基底偏移量\n" +" support_base = (\n" +" thread_state_addr +\n" +" debug_offsets.debugger_support.remote_debugger_support\n" +" )\n" +"\n" +" # 步驟 1：將腳本路徑寫入 debugger_script_path\n" +" script_path_ptr = (\n" +" support_base +\n" +" debug_offsets.debugger_support.debugger_script_path\n" +" )\n" +" write_string(pid, script_path_ptr, script_path)\n" +"\n" +" # 步驟 2：將 debugger_pending_call 設定為 1\n" +" pending_ptr = (\n" +" support_base +\n" +" debug_offsets.debugger_support.debugger_pending_call\n" +" )\n" +" write_int(pid, pending_ptr, 1)\n" +"\n" +" # 步驟 3：在 eval_breaker 中設定 _PY_EVAL_PLEASE_STOP_BIT（位元 5，值為 1 << 5）\n" +" eval_breaker_ptr = (\n" +" thread_state_addr +\n" +" debug_offsets.debugger_support.eval_breaker\n" +" )\n" +" breaker = read_int(pid, eval_breaker_ptr)\n" +" breaker |= (1 << 5)\n" +" write_int(pid, eval_breaker_ptr, breaker)" + +#: ../../howto/remote_debugging.rst:586 +msgid "" +"Once these fields are set, the debugger may resume the process (if it was " +"suspended). The interpreter will process the request at the next safe " +"evaluation point, load the script from disk, and execute it." +msgstr "" +"一旦設定了這些欄位，偵錯器就可以恢復行程（如果它先被暫停了）。直譯器將在下一個安全執行點" +"處理請求、從磁碟載入腳本並執行它。" + +#: ../../howto/remote_debugging.rst:590 +msgid "" +"It is the responsibility of the debugger to ensure that the script file " +"remains present and accessible to the target process during execution." +msgstr "偵錯器有責任確保腳本檔案在執行期間仍然存在且可供目標行程存取。" + +#: ../../howto/remote_debugging.rst:595 +msgid "" +"Script execution is asynchronous. The script file cannot be deleted " +"immediately after injection. The debugger should wait until the injected " +"script has produced an observable effect before removing the file. This " +"effect depends on what the script is designed to do. For example, a debugger " +"might wait until the remote process connects back to a socket before " +"removing the script. Once such an effect is observed, it is safe to assume " +"the file is no longer needed." +msgstr "" +"腳本執行是非同步的。注入後不能立即刪除腳本檔案。偵錯器應等到注入的腳本產生可觀察的效果後再" +"刪除檔案。此效果取決於腳本被設計要執行的操作。例如，偵錯器可能會等到遠端行程連回通訊端後再刪" +"除腳本。一旦觀察到這種效果，就可以安全地假設不再需要該檔案。" + +#: ../../howto/remote_debugging.rst:604 +msgid "Summary" +msgstr "摘要" + +#: ../../howto/remote_debugging.rst:606 +msgid "To inject and execute a Python script in a remote process:" +msgstr "要在遠端行程中注入並執行 Python 腳本：" + +#: ../../howto/remote_debugging.rst:608 +msgid "Locate the ``PyRuntime`` structure in the target process’s memory." +msgstr "在目標行程的記憶體中定位 ``PyRuntime`` 結構。" + +#: ../../howto/remote_debugging.rst:609 +msgid "" +"Read and validate the ``_Py_DebugOffsets`` structure at the beginning of " +"``PyRuntime``." +msgstr "讀取並驗證 ``PyRuntime`` 開頭的 ``_Py_DebugOffsets`` 結構。" + +#: ../../howto/remote_debugging.rst:611 +msgid "Use the offsets to locate a valid ``PyThreadState``." +msgstr "使用偏移量來定位有效的 ``PyThreadState``。" + +#: ../../howto/remote_debugging.rst:612 +msgid "Write the path to a Python script into ``debugger_script_path``." +msgstr "將 Python 腳本的路徑寫入 ``debugger_script_path``。" + +#: ../../howto/remote_debugging.rst:613 +msgid "Set the ``debugger_pending_call`` flag to ``1``." +msgstr "將 ``debugger_pending_call`` 旗標設定為 ``1``。" + +#: ../../howto/remote_debugging.rst:614 +msgid "Set ``_PY_EVAL_PLEASE_STOP_BIT`` in the ``eval_breaker`` field." +msgstr "在 ``eval_breaker`` 欄位中設定 ``_PY_EVAL_PLEASE_STOP_BIT``。" + +#: ../../howto/remote_debugging.rst:615 +msgid "" +"Resume the process (if suspended). The script will execute at the next safe " +"evaluation point." +msgstr "恢復行程（如果已暫停）。腳本將在下一個安全執行點執行。" diff --git a/howto/sockets.po b/howto/sockets.po index 11ec58c7e6..a81d8f9098 100644 --- a/howto/sockets.po +++ b/howto/sockets.po @@ -1,755 +1,755 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-12-01 00:17+0000\n" -"PO-Revision-Date: 2023-08-12 15:16+0800\n" -"Last-Translator: Jay \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" -"X-Generator: Poedit 3.3.2\n" - -#: ../../howto/sockets.rst:5 -msgid "Socket Programming HOWTO" -msgstr "Socket 程式設計指南" - -#: ../../howto/sockets.rst:0 -msgid "Author" -msgstr "作者" - -#: ../../howto/sockets.rst:7 -msgid "Gordon McMillan" -msgstr "Gordon McMillan" - -#: ../../howto/sockets.rst:10 -msgid "Abstract" -msgstr "摘要" - -#: ../../howto/sockets.rst:12 -msgid "" -"Sockets are used nearly everywhere, but are one of the most severely " -"misunderstood technologies around. This is a 10,000 foot overview of " -"sockets. It's not really a tutorial - you'll still have work to do in " -"getting things operational. It doesn't cover the fine points (and there are " -"a lot of them), but I hope it will give you enough background to begin using " -"them decently." -msgstr "" -"Sockets 在各處都被廣泛使用，但卻是一項被誤解最嚴重的技術之一。這是一篇對 " -"sockets 的概論介紹。這並不是一個完整的教學指南 - 你還需要做許多準備才能讓 " -"sockets 正常運作。這篇文章也沒有包含細節（其中有非常多的細節），但我希望這篇" -"文章能夠讓你有足夠的背景知識，以便開始正確的使用 sockets 程式設計。" - -#: ../../howto/sockets.rst:20 -msgid "Sockets" -msgstr "Sockets" - -#: ../../howto/sockets.rst:22 -msgid "" -"I'm only going to talk about INET (i.e. IPv4) sockets, but they account for " -"at least 99% of the sockets in use. And I'll only talk about STREAM (i.e. " -"TCP) sockets - unless you really know what you're doing (in which case this " -"HOWTO isn't for you!), you'll get better behavior and performance from a " -"STREAM socket than anything else. I will try to clear up the mystery of what " -"a socket is, as well as some hints on how to work with blocking and non-" -"blocking sockets. But I'll start by talking about blocking sockets. You'll " -"need to know how they work before dealing with non-blocking sockets." -msgstr "" -"我只會討論關於 INET（例如：IPv4）的 sockets，但它們涵蓋了幾乎 99% 的 sockets " -"使用場景。而我也將僅討論關於 STREAM（比如：TCP）類型的 sockets - 除非你真的知" -"道你在做什麼（在這種情況下，這份指南可能不適合你），使用 STREAM 類型的 " -"socket 會獲得比其他 sockets 類型更好的表現和性能。我將會嘗試解釋 socket 是什" -"麼，以及如何使用阻塞 (blocking) 和非阻塞 (non-blocking) sockets 的一些建議。" -"但首先我會先談論阻塞 sockets。在處理非阻塞 sockets 之前，你需要了解它們的工作" -"原理。" - -#: ../../howto/sockets.rst:31 -msgid "" -"Part of the trouble with understanding these things is that \"socket\" can " -"mean a number of subtly different things, depending on context. So first, " -"let's make a distinction between a \"client\" socket - an endpoint of a " -"conversation, and a \"server\" socket, which is more like a switchboard " -"operator. The client application (your browser, for example) uses \"client\" " -"sockets exclusively; the web server it's talking to uses both \"server\" " -"sockets and \"client\" sockets." -msgstr "" -"要理解這些東西的困難點之一在於 \"scoket\" 可以代表多種具有些微差異的東西，這" -"主要取決於上下文。所以首先，讓我們先區分「用戶端 (client)」socket 和「伺服器" -"端 (server)」socket 的差別，「用戶端」socket 表示通訊的一端，「伺服器端」" -"socket 更像是一個電話總機接線員。用戶端應用程式（例如：你的瀏覽器）只能使用" -"「用戶端」socket; 它所連接的網路伺服器則同時使用「伺服器端」socket 和 「用戶" -"端」socket 來進行通訊。" - -#: ../../howto/sockets.rst:40 -msgid "History" -msgstr "歷史" - -#: ../../howto/sockets.rst:42 -msgid "" -"Of the various forms of :abbr:`IPC (Inter Process Communication)`, sockets " -"are by far the most popular. On any given platform, there are likely to be " -"other forms of IPC that are faster, but for cross-platform communication, " -"sockets are about the only game in town." -msgstr "" -"在各種形式的 :abbr:`IPC (Inter Process Communication)` 中，sockets 是最受歡迎" -"的。在任何特定的平台上，可能會存在其他更快速的 IPC 形式，但對於跨平台通訊來" -"說，sockets 是唯一的選擇。" - -#: ../../howto/sockets.rst:47 -msgid "" -"They were invented in Berkeley as part of the BSD flavor of Unix. They " -"spread like wildfire with the internet. With good reason --- the combination " -"of sockets with INET makes talking to arbitrary machines around the world " -"unbelievably easy (at least compared to other schemes)." -msgstr "" -"Sockets 作為 Unix 的 BSD 分支的一部分在 Berkeley 被發明出來。它們隨著網際網路" -"的普及而迅速蔓延開來。這是有很好的理由 — sockets 和 INET 的結合讓世界各地任何" -"的機器之間的通訊變得非常簡單（至少與其它方案相比是如此）。" - -#: ../../howto/sockets.rst:54 -msgid "Creating a Socket" -msgstr "建立一個 Socket" - -#: ../../howto/sockets.rst:56 -msgid "" -"Roughly speaking, when you clicked on the link that brought you to this " -"page, your browser did something like the following::" -msgstr "" -"大致上來說，當你點擊了帶你來到這個頁面的連結時，你的瀏覽器做了以下的操作： ::" - -#: ../../howto/sockets.rst:59 -msgid "" -"# create an INET, STREAMing socket\n" -"s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)\n" -"# now connect to the web server on port 80 - the normal http port\n" -"s.connect((\"www.python.org\", 80))" -msgstr "" - -#: ../../howto/sockets.rst:64 -msgid "" -"When the ``connect`` completes, the socket ``s`` can be used to send in a " -"request for the text of the page. The same socket will read the reply, and " -"then be destroyed. That's right, destroyed. Client sockets are normally only " -"used for one exchange (or a small set of sequential exchanges)." -msgstr "" -"當 ``connect`` 完成時，這個 socket ``s`` 可以用來發送請求來取得頁面的文本。同" -"一個 socket 也會讀取回傳值，然後再被銷毀。是的，會被銷毀。用戶端 socket 通常" -"只用來做一次交換（或是一小組連續交換）。" - -#: ../../howto/sockets.rst:70 -msgid "" -"What happens in the web server is a bit more complex. First, the web server " -"creates a \"server socket\"::" -msgstr "" -"網路伺服器 (web server) 的運作就稍微複雜一點。首先，網路伺服器會建立一個「伺" -"服器端 socket」： ::" - -#: ../../howto/sockets.rst:73 -msgid "" -"# create an INET, STREAMing socket\n" -"serversocket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)\n" -"# bind the socket to a public host, and a well-known port\n" -"serversocket.bind((socket.gethostname(), 80))\n" -"# become a server socket\n" -"serversocket.listen(5)" -msgstr "" - -#: ../../howto/sockets.rst:80 -msgid "" -"A couple things to notice: we used ``socket.gethostname()`` so that the " -"socket would be visible to the outside world. If we had used ``s." -"bind(('localhost', 80))`` or ``s.bind(('127.0.0.1', 80))`` we would still " -"have a \"server\" socket, but one that was only visible within the same " -"machine. ``s.bind(('', 80))`` specifies that the socket is reachable by any " -"address the machine happens to have." -msgstr "" -"有幾件事需要注意：我們使用了 ``socket.gethostname()``，這樣 socket 才能對外部" -"網路可見。如果我們使用了 ``s.bind(('localhost', 80))`` 或 ``s." -"bind(('127.0.0.1', 80))``，我們會得到一個「伺服器端」socket，但是只能在同一台" -"機器內可見。``s.bind(('', 80))`` 指定 socket 可以透過機器的任何地址存取。" - -#: ../../howto/sockets.rst:87 -msgid "" -"A second thing to note: low number ports are usually reserved for \"well " -"known\" services (HTTP, SNMP etc). If you're playing around, use a nice high " -"number (4 digits)." -msgstr "" -"第二個要注意的是：數字小的連接埠 (port) 通常保留給「廣為人知的」服務（HTTP、" -"SNMP等）。如果你只是想執行程式，可以使用一個數字較大的連接埠（4 位數字）。" - -#: ../../howto/sockets.rst:91 -msgid "" -"Finally, the argument to ``listen`` tells the socket library that we want it " -"to queue up as many as 5 connect requests (the normal max) before refusing " -"outside connections. If the rest of the code is written properly, that " -"should be plenty." -msgstr "" -"最後，``listen`` 引數告訴 socket 函式庫 (library)，我們希望在佇列 (queue) 中" -"累積達 5 個（正常的最大值）連線請求後再拒絕外部連線。如果其餘的程式碼編寫正" -"確，這應該足夠了。" - -#: ../../howto/sockets.rst:95 -msgid "" -"Now that we have a \"server\" socket, listening on port 80, we can enter the " -"mainloop of the web server::" -msgstr "" -"現在我們有一個監聽 80 連接埠的「伺服器端」socket 了，我們可以進入網路伺服器的" -"主迴圈了： ::" - -#: ../../howto/sockets.rst:98 -msgid "" -"while True:\n" -" # accept connections from outside\n" -" (clientsocket, address) = serversocket.accept()\n" -" # now do something with the clientsocket\n" -" # in this case, we'll pretend this is a threaded server\n" -" ct = make_client_thread(clientsocket)\n" -" ct.start()" -msgstr "" - -#: ../../howto/sockets.rst:106 -msgid "" -"There's actually 3 general ways in which this loop could work - dispatching " -"a thread to handle ``clientsocket``, create a new process to handle " -"``clientsocket``, or restructure this app to use non-blocking sockets, and " -"multiplex between our \"server\" socket and any active ``clientsocket``\\ s " -"using ``select``. More about that later. The important thing to understand " -"now is this: this is *all* a \"server\" socket does. It doesn't send any " -"data. It doesn't receive any data. It just produces \"client\" sockets. Each " -"``clientsocket`` is created in response to some *other* \"client\" socket " -"doing a ``connect()`` to the host and port we're bound to. As soon as we've " -"created that ``clientsocket``, we go back to listening for more connections. " -"The two \"clients\" are free to chat it up - they are using some dynamically " -"allocated port which will be recycled when the conversation ends." -msgstr "" -"事實上，有三種方法可以讓這個迴圈運作 - 分配一個執行緒 (thread) 來處理 " -"``clientsocket`` 、建立一個新行程 (process) 來處理 ``clientsocket``，或者將這" -"個程式重新改寫成使用非阻塞 socket，並使用 ``select`` 在我們的「伺服器端」" -"socket 和任何有效的 ``clientsocket`` 之間進行多工處理。稍後將會更詳細的介紹。" -"現在最重要的是理解：這就是「伺服器端」socket 做的\\ *所有* \\事情。它不會發送" -"任何資料、也不接收任何資料，它只會建立「伺服器端」socket。每個 " -"``clientsocket`` 都是為了回應某些\\ *其他* \\ ``connect()`` 到我們綁定的主機" -"上的「用戶端」socket。一但 ``clientsocket`` 建立完成，就會繼續監聽更多的連線" -"請求。兩個「用戶端」可以隨意的通訊 - 它們使用的是一些動態分配的連接埠，會在通" -"訊結束的時候被回收並重新利用。" - -#: ../../howto/sockets.rst:121 -msgid "IPC" -msgstr "IPC" - -#: ../../howto/sockets.rst:123 -msgid "" -"If you need fast IPC between two processes on one machine, you should look " -"into pipes or shared memory. If you do decide to use AF_INET sockets, bind " -"the \"server\" socket to ``'localhost'``. On most platforms, this will take " -"a shortcut around a couple of layers of network code and be quite a bit " -"faster." -msgstr "" -"如果你需要在一台機器上的兩個行程間進行快速的行程間通訊 (IPC)，你應該考慮使用" -"管道 (pipes) 或共享記憶體 (shared memory)。如果你確定要使用 AF_INET sockets，" -"請將「伺服器端」socket 綁定到 ``'localhost'``。在大多數平台上，這樣將會繞過幾" -"個網路程式碼層，並且速度會更快一些。" - -#: ../../howto/sockets.rst:129 -msgid "" -"The :mod:`multiprocessing` integrates cross-platform IPC into a higher-level " -"API." -msgstr ":mod:`multiprocessing` 將跨平台行程間通訊整合到更高層的 API 中。" - -#: ../../howto/sockets.rst:134 -msgid "Using a Socket" -msgstr "使用一個 Socket" - -#: ../../howto/sockets.rst:136 -msgid "" -"The first thing to note, is that the web browser's \"client\" socket and the " -"web server's \"client\" socket are identical beasts. That is, this is a " -"\"peer to peer\" conversation. Or to put it another way, *as the designer, " -"you will have to decide what the rules of etiquette are for a conversation*. " -"Normally, the ``connect``\\ ing socket starts the conversation, by sending " -"in a request, or perhaps a signon. But that's a design decision - it's not a " -"rule of sockets." -msgstr "" -"首先需要注意，網頁瀏覽器的「用戶端」socket 和網路伺服器的「用戶端」socket 是" -"非常類似的。也就是說，這是一個「點對點 (peer to peer)」的通訊方式，或者也可以" -"說\\ *作為設計者，你必須決定通訊的規則*。通常情況下，``connect`` 的 socket 會" -"透過發送一個請求或者信號來開始一次通訊。但這屬於設計決策，而不是 socket 的規" -"則。" - -#: ../../howto/sockets.rst:143 -msgid "" -"Now there are two sets of verbs to use for communication. You can use " -"``send`` and ``recv``, or you can transform your client socket into a file-" -"like beast and use ``read`` and ``write``. The latter is the way Java " -"presents its sockets. I'm not going to talk about it here, except to warn " -"you that you need to use ``flush`` on sockets. These are buffered \"files\", " -"and a common mistake is to ``write`` something, and then ``read`` for a " -"reply. Without a ``flush`` in there, you may wait forever for the reply, " -"because the request may still be in your output buffer." -msgstr "" -"現在有兩組可供通訊使用的動詞。你可以使用 ``send`` 和 ``recv``，或者可以將用戶" -"端 socket 轉換成類似檔案的形式，並使用 ``read`` 和 ``write``。後者是 Java 中" -"呈現 socket 的方式。我不打算在這裡討論它，只是提醒你需要在 socket 上使用 " -"``flush``。這些是緩衝的「檔案」，一個常見的錯誤是使用 ``write`` 寫入某些內" -"容，然後直接 ``read`` 回覆。如果不使用 ``flush``，你可能會一直等待這個回覆，" -"因為請求可能還在你的輸出緩衝中。" - -#: ../../howto/sockets.rst:152 -msgid "" -"Now we come to the major stumbling block of sockets - ``send`` and ``recv`` " -"operate on the network buffers. They do not necessarily handle all the bytes " -"you hand them (or expect from them), because their major focus is handling " -"the network buffers. In general, they return when the associated network " -"buffers have been filled (``send``) or emptied (``recv``). They then tell " -"you how many bytes they handled. It is *your* responsibility to call them " -"again until your message has been completely dealt with." -msgstr "" -"現在我們來到 sockets 的主要障礙 - ``send`` 和 ``recv`` 操作的是網路緩衝區。他" -"們不一定會處理你提供給它們的所有位元組（或者是你期望它處理的位元組），因為它" -"們主要的重點是處理網路緩衝區。一般來說，它們會在關聯的網路衝區已滿 " -"(``send``) 或已清空 (``recv``) 時回傳，然後告訴你它們處理了多少位元組。*你* " -"\\的責任是一直呼叫它們直到你所有的訊息處理完成。" - -#: ../../howto/sockets.rst:160 -msgid "" -"When a ``recv`` returns 0 bytes, it means the other side has closed (or is " -"in the process of closing) the connection. You will not receive any more " -"data on this connection. Ever. You may be able to send data successfully; " -"I'll talk more about this later." -msgstr "" -"當 ``recv`` 回傳「零位元組 (0 bytes)」時，就表示另一端已經關閉（或著正在關" -"閉）連線。你再也不能從這個連線上取得任何資料了。你可能還是可以成功發送資料；" -"我稍後會對此進行更詳細的解釋。" - -#: ../../howto/sockets.rst:165 -msgid "" -"A protocol like HTTP uses a socket for only one transfer. The client sends a " -"request, then reads a reply. That's it. The socket is discarded. This means " -"that a client can detect the end of the reply by receiving 0 bytes." -msgstr "" -"像 HTTP 這樣的協定只使用一個 socket 進行一次傳輸，用戶端發送一個請求，然後讀" -"取一個回覆。就這樣，然後這個 socket 就會被銷毀。這表示者用戶端可以透過接收" -"「零位元組」來檢測回覆的結束。" - -#: ../../howto/sockets.rst:169 -msgid "" -"But if you plan to reuse your socket for further transfers, you need to " -"realize that *there is no* :abbr:`EOT (End of Transfer)` *on a socket.* I " -"repeat: if a socket ``send`` or ``recv`` returns after handling 0 bytes, the " -"connection has been broken. If the connection has *not* been broken, you " -"may wait on a ``recv`` forever, because the socket will *not* tell you that " -"there's nothing more to read (for now). Now if you think about that a bit, " -"you'll come to realize a fundamental truth of sockets: *messages must either " -"be fixed length* (yuck), *or be delimited* (shrug), *or indicate how long " -"they are* (much better), *or end by shutting down the connection*. The " -"choice is entirely yours, (but some ways are righter than others)." -msgstr "" -"但是如果你打算在之後的傳輸中重新利用 socket 的話，你需要明白\\ *socket 中是不" -"存在* \\ :abbr:`EOT （傳輸結束）`。重申一次：如果一個 socket 的 ``send`` 或 " -"``recv`` 處理了「零位元組」後回傳，表示連線已經斷開。如果連線\\ *沒有* \\斷" -"開，你可能會永遠處於等待 ``recv`` 的狀態，因為（就目前來說）socket *不會* " -"\\告訴你沒有更多資料可以讀取了。現在，如果你稍微思考一下，你就會意識到 " -"socket 的一個基本事實：*訊息要麼是一個固定的長度（不好的做法），要麼是可以被" -"分隔的（普通的做法），要麼是指定其長度（更好地做法），要麼透過關閉連線來結" -"束。*\\ 完全由你來決定要使用哪種方式（但有些方法比其他方法來的更好）。" - -#: ../../howto/sockets.rst:180 -msgid "" -"Assuming you don't want to end the connection, the simplest solution is a " -"fixed length message::" -msgstr "假設你不想結束連線，最簡單的方式就是使用固定長度的訊息： ::" - -#: ../../howto/sockets.rst:183 -msgid "" -"class MySocket:\n" -" \"\"\"demonstration class only\n" -" - coded for clarity, not efficiency\n" -" \"\"\"\n" -"\n" -" def __init__(self, sock=None):\n" -" if sock is None:\n" -" self.sock = socket.socket(\n" -" socket.AF_INET, socket.SOCK_STREAM)\n" -" else:\n" -" self.sock = sock\n" -"\n" -" def connect(self, host, port):\n" -" self.sock.connect((host, port))\n" -"\n" -" def mysend(self, msg):\n" -" totalsent = 0\n" -" while totalsent < MSGLEN:\n" -" sent = self.sock.send(msg[totalsent:])\n" -" if sent == 0:\n" -" raise RuntimeError(\"socket connection broken\")\n" -" totalsent = totalsent + sent\n" -"\n" -" def myreceive(self):\n" -" chunks = []\n" -" bytes_recd = 0\n" -" while bytes_recd < MSGLEN:\n" -" chunk = self.sock.recv(min(MSGLEN - bytes_recd, 2048))\n" -" if chunk == b'':\n" -" raise RuntimeError(\"socket connection broken\")\n" -" chunks.append(chunk)\n" -" bytes_recd = bytes_recd + len(chunk)\n" -" return b''.join(chunks)" -msgstr "" - -#: ../../howto/sockets.rst:217 -msgid "" -"The sending code here is usable for almost any messaging scheme - in Python " -"you send strings, and you can use ``len()`` to determine its length (even if " -"it has embedded ``\\0`` characters). It's mostly the receiving code that " -"gets more complex. (And in C, it's not much worse, except you can't use " -"``strlen`` if the message has embedded ``\\0``\\ s.)" -msgstr "" -"發送部分的程式碼幾乎可用於任何訊息的傳送方式 - 在 Python 中你發送一個字串，可" -"以用 ``len()`` 來確認他的長度（即使字串包含了 ``\\0`` 字元）。在這裡，主要是" -"接收的程式碼變得更複雜一些。（在 C 語言中，情況沒有變得更糟，只是如果訊息中包" -"含了 ``\\0`` 字元，你就不能使用 ``strlen`` 函式。）" - -#: ../../howto/sockets.rst:223 -msgid "" -"The easiest enhancement is to make the first character of the message an " -"indicator of message type, and have the type determine the length. Now you " -"have two ``recv``\\ s - the first to get (at least) that first character so " -"you can look up the length, and the second in a loop to get the rest. If you " -"decide to go the delimited route, you'll be receiving in some arbitrary " -"chunk size, (4096 or 8192 is frequently a good match for network buffer " -"sizes), and scanning what you've received for a delimiter." -msgstr "" -"最簡單的改進方法是將訊息的第一個字元表示訊息的類型，並根據訊息的類型來決定訊" -"息的長度。現在你需要使用兩次 ``recv`` - 第一次用於接收（至少）第一個字元來得" -"知長度，第二次用於在迴圈中接收剩下的訊息。如果你決定使用分隔符號的方式，你將" -"會以某個任意的區塊大小進行接收（4096 或 8192 通常是網路緩衝區大小的良好選" -"擇），並在收到的內容中掃描分隔符號。" - -#: ../../howto/sockets.rst:231 -msgid "" -"One complication to be aware of: if your conversational protocol allows " -"multiple messages to be sent back to back (without some kind of reply), and " -"you pass ``recv`` an arbitrary chunk size, you may end up reading the start " -"of a following message. You'll need to put that aside and hold onto it, " -"until it's needed." -msgstr "" -"需要注意的一個複雜情況是，如果你的通訊協定允許連續發送多個訊息（沒有任何回" -"應），並且你傳遞給 ``recv`` 函式一個任意的區塊大小，最後有可能讀取到下一條訊" -"息的開頭。你需要將其放在一旁並保留下來，直到需要使用的時候。" - -#: ../../howto/sockets.rst:237 -msgid "" -"Prefixing the message with its length (say, as 5 numeric characters) gets " -"more complex, because (believe it or not), you may not get all 5 characters " -"in one ``recv``. In playing around, you'll get away with it; but in high " -"network loads, your code will very quickly break unless you use two ``recv`` " -"loops - the first to determine the length, the second to get the data part " -"of the message. Nasty. This is also when you'll discover that ``send`` does " -"not always manage to get rid of everything in one pass. And despite having " -"read this, you will eventually get bit by it!" -msgstr "" -"使用長度作為訊息的前綴（例如，使用 5 個數字字元表示）會變得更複雜，因為（信不" -"信由你）你可能無法在一次 ``recv`` 中獲得所有 5 個字元。在一般使用下，可能不會" -"有這個狀況，但在高負載的網路下，除非使用兩個 ``recv`` （第一個用於確定長度，" -"第二個用於取得訊息的資料部分），否則你的程式碼很快就會出現錯誤。這令人非常頭" -"痛。同樣的情況也會讓你發現 ``send`` 並不總能在一次傳輸中完全清除所有內容。儘" -"管已經閱讀了這篇文章，但最終還是無法解決！" - -#: ../../howto/sockets.rst:246 -msgid "" -"In the interests of space, building your character, (and preserving my " -"competitive position), these enhancements are left as an exercise for the " -"reader. Lets move on to cleaning up." -msgstr "" -"為了節省篇幅、培養你的技能（並保持我的競爭優勢），這些改進方法留給讀者自行練" -"習。現在讓我們開始進行清理工作。" - -#: ../../howto/sockets.rst:252 -msgid "Binary Data" -msgstr "二進位資料" - -#: ../../howto/sockets.rst:254 -msgid "" -"It is perfectly possible to send binary data over a socket. The major " -"problem is that not all machines use the same formats for binary data. For " -"example, `network byte order `_ is big-endian, with the most significant byte " -"first, so a 16 bit integer with the value ``1`` would be the two hex bytes " -"``00 01``. However, most common processors (x86/AMD64, ARM, RISC-V), are " -"little-endian, with the least significant byte first - that same ``1`` would " -"be ``01 00``." -msgstr "" -"使用 socket 傳輸二進位資料完全是可行的。最主要的問題在於不同機器使用不同的二" -"進位資料格式。例如，`網路二進位順序 `_ 採用的是「大端序 big-endian」，所以一個值為 ``1`` " -"的 16 位元整數會表示成兩個 16 進位的位元組 ``00 01``。然而大多數常見的處理器 " -"(x86/AMD64，ARM，RISC-V) 採用的是「小端序 little-endian」，所以相同的 ``1`` " -"會被表示成 ``01 00``。（譯者注：將一個多位數的低位放在較小的位址處，高位放在" -"較大的位址處，則稱小端序；反之則稱大端序。）" - -#: ../../howto/sockets.rst:262 -msgid "" -"Socket libraries have calls for converting 16 and 32 bit integers - ``ntohl, " -"htonl, ntohs, htons`` where \"n\" means *network* and \"h\" means *host*, " -"\"s\" means *short* and \"l\" means *long*. Where network order is host " -"order, these do nothing, but where the machine is byte-reversed, these swap " -"the bytes around appropriately." -msgstr "" -"Socket 函式庫提供了用於轉換 16 位元和 32 位元整數的函式 - ``ntohl, htonl, " -"ntohs, htons``，其中 \"n\" 表示 *network*，\"h\" 表示 *host*，\"s\" 表示 " -"*short*，\"l\" 表示 *long*。當網路的位元組順序和主機位元組順序相同時，這些函" -"式不會做任何操作，但當主機的位元組順序相反時，這些函式會適當的交換位元組順" -"序。" - -#: ../../howto/sockets.rst:268 -msgid "" -"In these days of 64-bit machines, the ASCII representation of binary data is " -"frequently smaller than the binary representation. That's because a " -"surprising amount of the time, most integers have the value 0, or maybe 1. " -"The string ``\"0\"`` would be two bytes, while a full 64-bit integer would " -"be 8. Of course, this doesn't fit well with fixed-length messages. " -"Decisions, decisions." -msgstr "" -"在現今的 64 位元機器中，二進位資料的 ASCII 表示通常會比二進位表示要小，這是因" -"為在很多情況下，大多數整數的值為 0 或者 1。例如，字串形式的 ``\"0\"`` 是兩個" -"位元組，而完整的 64 位元整數則是 8 個位元組。當然，這對固定長度的訊息來說不太" -"適合，需要自行決定。" - -#: ../../howto/sockets.rst:277 -msgid "Disconnecting" -msgstr "結束連線" - -#: ../../howto/sockets.rst:279 -msgid "" -"Strictly speaking, you're supposed to use ``shutdown`` on a socket before " -"you ``close`` it. The ``shutdown`` is an advisory to the socket at the " -"other end. Depending on the argument you pass it, it can mean \"I'm not " -"going to send anymore, but I'll still listen\", or \"I'm not listening, good " -"riddance!\". Most socket libraries, however, are so used to programmers " -"neglecting to use this piece of etiquette that normally a ``close`` is the " -"same as ``shutdown(); close()``. So in most situations, an explicit " -"``shutdown`` is not needed." -msgstr "" -"嚴格來說，在關閉 socket 前，你應該使用 ``shutdown`` 函式。``shutdown`` 函式是" -"發送給 socket 另一端的一個提醒。根據你傳遞的引數，它可以表示「我不會再發送任" -"何訊息了，但我仍然會持續監聽」，或者是「我不會再繼續監聽了，真讚！」。然而，" -"大多數的 socket 函式庫或程式設計師都習慣忽略這種禮節，因為通常情況下 " -"``close`` 跟 ``shutdown(); close()`` 是一樣的。所以在大多數情況下，不需要再特" -"地使用 ``shutdown`` 了。" - -#: ../../howto/sockets.rst:287 -msgid "" -"One way to use ``shutdown`` effectively is in an HTTP-like exchange. The " -"client sends a request and then does a ``shutdown(1)``. This tells the " -"server \"This client is done sending, but can still receive.\" The server " -"can detect \"EOF\" by a receive of 0 bytes. It can assume it has the " -"complete request. The server sends a reply. If the ``send`` completes " -"successfully then, indeed, the client was still receiving." -msgstr "" -"有效使用 ``shutdown`` 的一種方式是在類似 HTTP 的交換中，用戶端發送請求後，然" -"後使用 ``shutdown(1)``。這告訴伺服器「這個用戶端已經發送完成，但仍可以接" -"收」。伺服器可以透過接收「零位元組」來檢測 \"EOF\"。這樣它就可以確定已經接收" -"到完整的請求。伺服器發送回覆，如果 ``send`` 成功完成，那麼用戶端確實在持續接" -"收。" - -#: ../../howto/sockets.rst:294 -msgid "" -"Python takes the automatic shutdown a step further, and says that when a " -"socket is garbage collected, it will automatically do a ``close`` if it's " -"needed. But relying on this is a very bad habit. If your socket just " -"disappears without doing a ``close``, the socket at the other end may hang " -"indefinitely, thinking you're just being slow. *Please* ``close`` your " -"sockets when you're done." -msgstr "" -"Python 更進一步地採取自動關閉的步驟，並且當 socket 被垃圾回收機制回收時，如果" -"需要的話，他會自動執行 ``close``。但依賴這個機制是一個非常不好的習慣，如果你" -"的 socket 在沒有 ``close`` 的情況下消失了，那麼另一端的 socket 可能會認為你只" -"是慢了一步，而無期限的等待。*請務必* \\在使用完畢後使用 ``close`` 關閉你的 " -"sockets。" - -#: ../../howto/sockets.rst:302 -msgid "When Sockets Die" -msgstr "Sockets 何時銷毀" - -#: ../../howto/sockets.rst:304 -msgid "" -"Probably the worst thing about using blocking sockets is what happens when " -"the other side comes down hard (without doing a ``close``). Your socket is " -"likely to hang. TCP is a reliable protocol, and it will wait a long, long " -"time before giving up on a connection. If you're using threads, the entire " -"thread is essentially dead. There's not much you can do about it. As long as " -"you aren't doing something dumb, like holding a lock while doing a blocking " -"read, the thread isn't really consuming much in the way of resources. Do " -"*not* try to kill the thread - part of the reason that threads are more " -"efficient than processes is that they avoid the overhead associated with the " -"automatic recycling of resources. In other words, if you do manage to kill " -"the thread, your whole process is likely to be screwed up." -msgstr "" -"使用阻塞式 socket 最糟糕的地方可能是在另一端突然強制關閉（未執行 ``close``）" -"的情況下會發生什麼？你的 socket 很可能會處於阻塞狀態。TCP 是一種可靠的協定，" -"它在放棄連線之前會等待很長很長的時間。如果你正在使用執行緒，整個執行緒基本上" -"已經無法使用。在這方面，你無法做太多事情。只要你不做一些愚蠢的事情，比如在執" -"行阻塞式讀取時持有一個鎖，那麼執行緒並不會消耗太多資源。*不要*\\ 試圖終止執行" -"緒 - 執行緒比行程更有效的部分原因是它們避免了與自動回收資源相關的開銷。換句話" -"說，如果你確實設法終止了執行緒，整個行程可能會出現問題。" - -#: ../../howto/sockets.rst:318 -msgid "Non-blocking Sockets" -msgstr "非阻塞的 Sockets" - -#: ../../howto/sockets.rst:320 -msgid "" -"If you've understood the preceding, you already know most of what you need " -"to know about the mechanics of using sockets. You'll still use the same " -"calls, in much the same ways. It's just that, if you do it right, your app " -"will be almost inside-out." -msgstr "" -"如果你已經理解了前面的內容，你已經知道了大部分關於使用 sockets 的機制的所需知" -"識，你仍然會以非常相似的方式使用相同的函式。就這樣而已，如果你做的對，你的程" -"式就會是近乎完美的。" - -#: ../../howto/sockets.rst:325 -msgid "" -"In Python, you use ``socket.setblocking(False)`` to make it non-blocking. In " -"C, it's more complex, (for one thing, you'll need to choose between the BSD " -"flavor ``O_NONBLOCK`` and the almost indistinguishable POSIX flavor " -"``O_NDELAY``, which is completely different from ``TCP_NODELAY``), but it's " -"the exact same idea. You do this after creating the socket, but before using " -"it. (Actually, if you're nuts, you can switch back and forth.)" -msgstr "" -"在 Python 中可以使用 ``socket.setblocking(False)`` 來設定為非阻塞。在 C 的作" -"法更為複雜（例如，你需要在 BSD 風格的 ``O_NONBLOCK`` 和幾乎沒有區別的 POSIX " -"風格的 ``O_NDELAY`` 之間做出選擇，這與 ``TCP_NODELAY`` 完全不同），但基本思想" -"是一樣的，你要在建立 socket 後但在使用它之前執行此操作。（實際上，如果你願意" -"的話，你甚至可以來回切換。）" - -#: ../../howto/sockets.rst:332 -msgid "" -"The major mechanical difference is that ``send``, ``recv``, ``connect`` and " -"``accept`` can return without having done anything. You have (of course) a " -"number of choices. You can check return code and error codes and generally " -"drive yourself crazy. If you don't believe me, try it sometime. Your app " -"will grow large, buggy and suck CPU. So let's skip the brain-dead solutions " -"and do it right." -msgstr "" -"主要的機制差異在於 ``send``、``recv``、``connect`` 和 ``accept`` 可能在沒有執" -"行任何操作的情況下就回傳了。你當然有多種選擇。你可以檢查回傳值和錯誤代碼，但" -"這些操作通常會讓自己抓狂。如果你不相信我，不妨試試看。你的應用程式會變得臃" -"腫、錯誤百出，並且占用 CPU。所以，讓我們跳過無腦的解決方案，使用正確的方式。" - -#: ../../howto/sockets.rst:339 -msgid "Use ``select``." -msgstr "使用 ``select``。" - -#: ../../howto/sockets.rst:341 -msgid "" -"In C, coding ``select`` is fairly complex. In Python, it's a piece of cake, " -"but it's close enough to the C version that if you understand ``select`` in " -"Python, you'll have little trouble with it in C::" -msgstr "" -"在 C 中，編寫 ``select`` 是非常複雜的，但在 Python 中，這很簡單，並與 C 的版" -"本非常類似，如果你理解了 Python 中的 ``select``，在 C 中處理它時也不會有太大" -"的困難： ::" - -#: ../../howto/sockets.rst:345 -msgid "" -"ready_to_read, ready_to_write, in_error = \\\n" -" select.select(\n" -" potential_readers,\n" -" potential_writers,\n" -" potential_errs,\n" -" timeout)" -msgstr "" -"ready_to_read, ready_to_write, in_error = \\\n" -" select.select(\n" -" potential_readers,\n" -" potential_writers,\n" -" potential_errs,\n" -" timeout)" - -#: ../../howto/sockets.rst:352 -msgid "" -"You pass ``select`` three lists: the first contains all sockets that you " -"might want to try reading; the second all the sockets you might want to try " -"writing to, and the last (normally left empty) those that you want to check " -"for errors. You should note that a socket can go into more than one list. " -"The ``select`` call is blocking, but you can give it a timeout. This is " -"generally a sensible thing to do - give it a nice long timeout (say a " -"minute) unless you have good reason to do otherwise." -msgstr "" -"你傳遞給 ``select`` 三個列表：第一個列表包含你可能想要嘗試讀取的所有 " -"sockets；第二個包含所有你可能想要嘗試寫入的 sockets，最後一個（通常為空）包含" -"你想要檢查錯誤的 sockets。你應該注意，一個 socket 可以同時存在於多個列表中。" -"``select`` 呼叫是阻塞的，但你可以設置超時。通常這是一個明智的做法 - 除非有充" -"分的理由，否則給它一個很長的超時（比如一分鐘）。" - -#: ../../howto/sockets.rst:360 -msgid "" -"In return, you will get three lists. They contain the sockets that are " -"actually readable, writable and in error. Each of these lists is a subset " -"(possibly empty) of the corresponding list you passed in." -msgstr "" -"作為回傳，你將獲得三個列表。它們包含實際上可讀取、可寫入和出錯的 sockets。這" -"些列表中的每一個都是你傳入的相應列表的子集（可能為空）。" - -#: ../../howto/sockets.rst:364 -msgid "" -"If a socket is in the output readable list, you can be as-close-to-certain-" -"as-we-ever-get-in-this-business that a ``recv`` on that socket will return " -"*something*. Same idea for the writable list. You'll be able to send " -"*something*. Maybe not all you want to, but *something* is better than " -"nothing. (Actually, any reasonably healthy socket will return as writable - " -"it just means outbound network buffer space is available.)" -msgstr "" -"如果一個 socket 在輸出的可讀列表中，你可以幾乎確定，在這個業務中我們能夠得到" -"的最接近確定的事情是，對該 socket 的 ``recv`` 呼叫將會回傳一些\\ *內容*。對於" -"可寫列表，也是同樣的想法。你將能夠發送一些 *內容*。也許不是全部，但\\ *一些內" -"容*\\ 總比什麼都沒有好。（實際上，任何比較正常的 socket 都會以可寫的方式回傳 " -"- 這只是意味者「外送網路 (outbound network)」的緩衝空間是可用的。）" - -#: ../../howto/sockets.rst:371 -msgid "" -"If you have a \"server\" socket, put it in the potential_readers list. If it " -"comes out in the readable list, your ``accept`` will (almost certainly) " -"work. If you have created a new socket to ``connect`` to someone else, put " -"it in the potential_writers list. If it shows up in the writable list, you " -"have a decent chance that it has connected." -msgstr "" -"如果你有一個「伺服器端」socket，請將其放在 potential_readers 列表中，如果它在" -"可讀列表中出現，你的 ``accept`` 呼叫（幾乎可以確定）會成功。如果你建立了一個" -"新的 socket 去 ``connect`` 到其他地方，請將它放在 potential_writers 列表中，" -"如果它在可寫列表中出現，那麼他有可能已經連接上了。" - -#: ../../howto/sockets.rst:377 -msgid "" -"Actually, ``select`` can be handy even with blocking sockets. It's one way " -"of determining whether you will block - the socket returns as readable when " -"there's something in the buffers. However, this still doesn't help with the " -"problem of determining whether the other end is done, or just busy with " -"something else." -msgstr "" -"實際上，即使是使用阻塞式 socket 的情況下，``select`` 也很方便。這是一種判斷是" -"否會被阻塞的方法之一 - 當緩衝區中有某些內容時， socket 會回傳為可讀。然而，這" -"仍然無法解決判斷另一端是否完成，或者只是忙於其他事情的問題。" - -#: ../../howto/sockets.rst:382 -msgid "" -"**Portability alert**: On Unix, ``select`` works both with the sockets and " -"files. Don't try this on Windows. On Windows, ``select`` works with sockets " -"only. Also note that in C, many of the more advanced socket options are done " -"differently on Windows. In fact, on Windows I usually use threads (which " -"work very, very well) with my sockets." -msgstr "" -"**可移植性警告**：在 Unix 上，``select`` 同時適用於 sockets 和文件。但請不要" -"在 Windows 上嘗試這麼做，在 Windows 上，``select`` 只適用於 sockets。同時，請" -"注意，在 C 語言中，許多更進階的 socket 選項在 Windows 上有不同的實現方式。實" -"際上，在 Windows 上，我通常會使用執行緒（這非常，非常有效）與我的 sockets 一" -"起使用。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-12-01 00:17+0000\n" +"PO-Revision-Date: 2023-08-12 15:16+0800\n" +"Last-Translator: Jay \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" +"X-Generator: Poedit 3.3.2\n" + +#: ../../howto/sockets.rst:5 +msgid "Socket Programming HOWTO" +msgstr "Socket 程式設計指南" + +#: ../../howto/sockets.rst:0 +msgid "Author" +msgstr "作者" + +#: ../../howto/sockets.rst:7 +msgid "Gordon McMillan" +msgstr "Gordon McMillan" + +#: ../../howto/sockets.rst:10 +msgid "Abstract" +msgstr "摘要" + +#: ../../howto/sockets.rst:12 +msgid "" +"Sockets are used nearly everywhere, but are one of the most severely " +"misunderstood technologies around. This is a 10,000 foot overview of " +"sockets. It's not really a tutorial - you'll still have work to do in " +"getting things operational. It doesn't cover the fine points (and there are " +"a lot of them), but I hope it will give you enough background to begin using " +"them decently." +msgstr "" +"Sockets 在各處都被廣泛使用，但卻是一項被誤解最嚴重的技術之一。這是一篇對 " +"sockets 的概論介紹。這並不是一個完整的教學指南 - 你還需要做許多準備才能讓 " +"sockets 正常運作。這篇文章也沒有包含細節（其中有非常多的細節），但我希望這篇" +"文章能夠讓你有足夠的背景知識，以便開始正確的使用 sockets 程式設計。" + +#: ../../howto/sockets.rst:20 +msgid "Sockets" +msgstr "Sockets" + +#: ../../howto/sockets.rst:22 +msgid "" +"I'm only going to talk about INET (i.e. IPv4) sockets, but they account for " +"at least 99% of the sockets in use. And I'll only talk about STREAM (i.e. " +"TCP) sockets - unless you really know what you're doing (in which case this " +"HOWTO isn't for you!), you'll get better behavior and performance from a " +"STREAM socket than anything else. I will try to clear up the mystery of what " +"a socket is, as well as some hints on how to work with blocking and non-" +"blocking sockets. But I'll start by talking about blocking sockets. You'll " +"need to know how they work before dealing with non-blocking sockets." +msgstr "" +"我只會討論關於 INET（例如：IPv4）的 sockets，但它們涵蓋了幾乎 99% 的 sockets " +"使用場景。而我也將僅討論關於 STREAM（比如：TCP）類型的 sockets - 除非你真的知" +"道你在做什麼（在這種情況下，這份指南可能不適合你），使用 STREAM 類型的 " +"socket 會獲得比其他 sockets 類型更好的表現和性能。我將會嘗試解釋 socket 是什" +"麼，以及如何使用阻塞 (blocking) 和非阻塞 (non-blocking) sockets 的一些建議。" +"但首先我會先談論阻塞 sockets。在處理非阻塞 sockets 之前，你需要了解它們的工作" +"原理。" + +#: ../../howto/sockets.rst:31 +msgid "" +"Part of the trouble with understanding these things is that \"socket\" can " +"mean a number of subtly different things, depending on context. So first, " +"let's make a distinction between a \"client\" socket - an endpoint of a " +"conversation, and a \"server\" socket, which is more like a switchboard " +"operator. The client application (your browser, for example) uses \"client\" " +"sockets exclusively; the web server it's talking to uses both \"server\" " +"sockets and \"client\" sockets." +msgstr "" +"要理解這些東西的困難點之一在於 \"scoket\" 可以代表多種具有些微差異的東西，這" +"主要取決於上下文。所以首先，讓我們先區分「用戶端 (client)」socket 和「伺服器" +"端 (server)」socket 的差別，「用戶端」socket 表示通訊的一端，「伺服器端」" +"socket 更像是一個電話總機接線員。用戶端應用程式（例如：你的瀏覽器）只能使用" +"「用戶端」socket; 它所連接的網路伺服器則同時使用「伺服器端」socket 和 「用戶" +"端」socket 來進行通訊。" + +#: ../../howto/sockets.rst:40 +msgid "History" +msgstr "歷史" + +#: ../../howto/sockets.rst:42 +msgid "" +"Of the various forms of :abbr:`IPC (Inter Process Communication)`, sockets " +"are by far the most popular. On any given platform, there are likely to be " +"other forms of IPC that are faster, but for cross-platform communication, " +"sockets are about the only game in town." +msgstr "" +"在各種形式的 :abbr:`IPC (Inter Process Communication)` 中，sockets 是最受歡迎" +"的。在任何特定的平台上，可能會存在其他更快速的 IPC 形式，但對於跨平台通訊來" +"說，sockets 是唯一的選擇。" + +#: ../../howto/sockets.rst:47 +msgid "" +"They were invented in Berkeley as part of the BSD flavor of Unix. They " +"spread like wildfire with the internet. With good reason --- the combination " +"of sockets with INET makes talking to arbitrary machines around the world " +"unbelievably easy (at least compared to other schemes)." +msgstr "" +"Sockets 作為 Unix 的 BSD 分支的一部分在 Berkeley 被發明出來。它們隨著網際網路" +"的普及而迅速蔓延開來。這是有很好的理由 — sockets 和 INET 的結合讓世界各地任何" +"的機器之間的通訊變得非常簡單（至少與其它方案相比是如此）。" + +#: ../../howto/sockets.rst:54 +msgid "Creating a Socket" +msgstr "建立一個 Socket" + +#: ../../howto/sockets.rst:56 +msgid "" +"Roughly speaking, when you clicked on the link that brought you to this " +"page, your browser did something like the following::" +msgstr "" +"大致上來說，當你點擊了帶你來到這個頁面的連結時，你的瀏覽器做了以下的操作： ::" + +#: ../../howto/sockets.rst:59 +msgid "" +"# create an INET, STREAMing socket\n" +"s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)\n" +"# now connect to the web server on port 80 - the normal http port\n" +"s.connect((\"www.python.org\", 80))" +msgstr "" + +#: ../../howto/sockets.rst:64 +msgid "" +"When the ``connect`` completes, the socket ``s`` can be used to send in a " +"request for the text of the page. The same socket will read the reply, and " +"then be destroyed. That's right, destroyed. Client sockets are normally only " +"used for one exchange (or a small set of sequential exchanges)." +msgstr "" +"當 ``connect`` 完成時，這個 socket ``s`` 可以用來發送請求來取得頁面的文本。同" +"一個 socket 也會讀取回傳值，然後再被銷毀。是的，會被銷毀。用戶端 socket 通常" +"只用來做一次交換（或是一小組連續交換）。" + +#: ../../howto/sockets.rst:70 +msgid "" +"What happens in the web server is a bit more complex. First, the web server " +"creates a \"server socket\"::" +msgstr "" +"網路伺服器 (web server) 的運作就稍微複雜一點。首先，網路伺服器會建立一個「伺" +"服器端 socket」： ::" + +#: ../../howto/sockets.rst:73 +msgid "" +"# create an INET, STREAMing socket\n" +"serversocket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)\n" +"# bind the socket to a public host, and a well-known port\n" +"serversocket.bind((socket.gethostname(), 80))\n" +"# become a server socket\n" +"serversocket.listen(5)" +msgstr "" + +#: ../../howto/sockets.rst:80 +msgid "" +"A couple things to notice: we used ``socket.gethostname()`` so that the " +"socket would be visible to the outside world. If we had used ``s." +"bind(('localhost', 80))`` or ``s.bind(('127.0.0.1', 80))`` we would still " +"have a \"server\" socket, but one that was only visible within the same " +"machine. ``s.bind(('', 80))`` specifies that the socket is reachable by any " +"address the machine happens to have." +msgstr "" +"有幾件事需要注意：我們使用了 ``socket.gethostname()``，這樣 socket 才能對外部" +"網路可見。如果我們使用了 ``s.bind(('localhost', 80))`` 或 ``s." +"bind(('127.0.0.1', 80))``，我們會得到一個「伺服器端」socket，但是只能在同一台" +"機器內可見。``s.bind(('', 80))`` 指定 socket 可以透過機器的任何地址存取。" + +#: ../../howto/sockets.rst:87 +msgid "" +"A second thing to note: low number ports are usually reserved for \"well " +"known\" services (HTTP, SNMP etc). If you're playing around, use a nice high " +"number (4 digits)." +msgstr "" +"第二個要注意的是：數字小的連接埠 (port) 通常保留給「廣為人知的」服務（HTTP、" +"SNMP等）。如果你只是想執行程式，可以使用一個數字較大的連接埠（4 位數字）。" + +#: ../../howto/sockets.rst:91 +msgid "" +"Finally, the argument to ``listen`` tells the socket library that we want it " +"to queue up as many as 5 connect requests (the normal max) before refusing " +"outside connections. If the rest of the code is written properly, that " +"should be plenty." +msgstr "" +"最後，``listen`` 引數告訴 socket 函式庫 (library)，我們希望在佇列 (queue) 中" +"累積達 5 個（正常的最大值）連線請求後再拒絕外部連線。如果其餘的程式碼編寫正" +"確，這應該足夠了。" + +#: ../../howto/sockets.rst:95 +msgid "" +"Now that we have a \"server\" socket, listening on port 80, we can enter the " +"mainloop of the web server::" +msgstr "" +"現在我們有一個監聽 80 連接埠的「伺服器端」socket 了，我們可以進入網路伺服器的" +"主迴圈了： ::" + +#: ../../howto/sockets.rst:98 +msgid "" +"while True:\n" +" # accept connections from outside\n" +" (clientsocket, address) = serversocket.accept()\n" +" # now do something with the clientsocket\n" +" # in this case, we'll pretend this is a threaded server\n" +" ct = make_client_thread(clientsocket)\n" +" ct.start()" +msgstr "" + +#: ../../howto/sockets.rst:106 +msgid "" +"There's actually 3 general ways in which this loop could work - dispatching " +"a thread to handle ``clientsocket``, create a new process to handle " +"``clientsocket``, or restructure this app to use non-blocking sockets, and " +"multiplex between our \"server\" socket and any active ``clientsocket``\\ s " +"using ``select``. More about that later. The important thing to understand " +"now is this: this is *all* a \"server\" socket does. It doesn't send any " +"data. It doesn't receive any data. It just produces \"client\" sockets. Each " +"``clientsocket`` is created in response to some *other* \"client\" socket " +"doing a ``connect()`` to the host and port we're bound to. As soon as we've " +"created that ``clientsocket``, we go back to listening for more connections. " +"The two \"clients\" are free to chat it up - they are using some dynamically " +"allocated port which will be recycled when the conversation ends." +msgstr "" +"事實上，有三種方法可以讓這個迴圈運作 - 分配一個執行緒 (thread) 來處理 " +"``clientsocket`` 、建立一個新行程 (process) 來處理 ``clientsocket``，或者將這" +"個程式重新改寫成使用非阻塞 socket，並使用 ``select`` 在我們的「伺服器端」" +"socket 和任何有效的 ``clientsocket`` 之間進行多工處理。稍後將會更詳細的介紹。" +"現在最重要的是理解：這就是「伺服器端」socket 做的\\ *所有* \\事情。它不會發送" +"任何資料、也不接收任何資料，它只會建立「伺服器端」socket。每個 " +"``clientsocket`` 都是為了回應某些\\ *其他* \\ ``connect()`` 到我們綁定的主機" +"上的「用戶端」socket。一但 ``clientsocket`` 建立完成，就會繼續監聽更多的連線" +"請求。兩個「用戶端」可以隨意的通訊 - 它們使用的是一些動態分配的連接埠，會在通" +"訊結束的時候被回收並重新利用。" + +#: ../../howto/sockets.rst:121 +msgid "IPC" +msgstr "IPC" + +#: ../../howto/sockets.rst:123 +msgid "" +"If you need fast IPC between two processes on one machine, you should look " +"into pipes or shared memory. If you do decide to use AF_INET sockets, bind " +"the \"server\" socket to ``'localhost'``. On most platforms, this will take " +"a shortcut around a couple of layers of network code and be quite a bit " +"faster." +msgstr "" +"如果你需要在一台機器上的兩個行程間進行快速的行程間通訊 (IPC)，你應該考慮使用" +"管道 (pipes) 或共享記憶體 (shared memory)。如果你確定要使用 AF_INET sockets，" +"請將「伺服器端」socket 綁定到 ``'localhost'``。在大多數平台上，這樣將會繞過幾" +"個網路程式碼層，並且速度會更快一些。" + +#: ../../howto/sockets.rst:129 +msgid "" +"The :mod:`multiprocessing` integrates cross-platform IPC into a higher-level " +"API." +msgstr ":mod:`multiprocessing` 將跨平台行程間通訊整合到更高層的 API 中。" + +#: ../../howto/sockets.rst:134 +msgid "Using a Socket" +msgstr "使用一個 Socket" + +#: ../../howto/sockets.rst:136 +msgid "" +"The first thing to note, is that the web browser's \"client\" socket and the " +"web server's \"client\" socket are identical beasts. That is, this is a " +"\"peer to peer\" conversation. Or to put it another way, *as the designer, " +"you will have to decide what the rules of etiquette are for a conversation*. " +"Normally, the ``connect``\\ ing socket starts the conversation, by sending " +"in a request, or perhaps a signon. But that's a design decision - it's not a " +"rule of sockets." +msgstr "" +"首先需要注意，網頁瀏覽器的「用戶端」socket 和網路伺服器的「用戶端」socket 是" +"非常類似的。也就是說，這是一個「點對點 (peer to peer)」的通訊方式，或者也可以" +"說\\ *作為設計者，你必須決定通訊的規則*。通常情況下，``connect`` 的 socket 會" +"透過發送一個請求或者信號來開始一次通訊。但這屬於設計決策，而不是 socket 的規" +"則。" + +#: ../../howto/sockets.rst:143 +msgid "" +"Now there are two sets of verbs to use for communication. You can use " +"``send`` and ``recv``, or you can transform your client socket into a file-" +"like beast and use ``read`` and ``write``. The latter is the way Java " +"presents its sockets. I'm not going to talk about it here, except to warn " +"you that you need to use ``flush`` on sockets. These are buffered \"files\", " +"and a common mistake is to ``write`` something, and then ``read`` for a " +"reply. Without a ``flush`` in there, you may wait forever for the reply, " +"because the request may still be in your output buffer." +msgstr "" +"現在有兩組可供通訊使用的動詞。你可以使用 ``send`` 和 ``recv``，或者可以將用戶" +"端 socket 轉換成類似檔案的形式，並使用 ``read`` 和 ``write``。後者是 Java 中" +"呈現 socket 的方式。我不打算在這裡討論它，只是提醒你需要在 socket 上使用 " +"``flush``。這些是緩衝的「檔案」，一個常見的錯誤是使用 ``write`` 寫入某些內" +"容，然後直接 ``read`` 回覆。如果不使用 ``flush``，你可能會一直等待這個回覆，" +"因為請求可能還在你的輸出緩衝中。" + +#: ../../howto/sockets.rst:152 +msgid "" +"Now we come to the major stumbling block of sockets - ``send`` and ``recv`` " +"operate on the network buffers. They do not necessarily handle all the bytes " +"you hand them (or expect from them), because their major focus is handling " +"the network buffers. In general, they return when the associated network " +"buffers have been filled (``send``) or emptied (``recv``). They then tell " +"you how many bytes they handled. It is *your* responsibility to call them " +"again until your message has been completely dealt with." +msgstr "" +"現在我們來到 sockets 的主要障礙 - ``send`` 和 ``recv`` 操作的是網路緩衝區。他" +"們不一定會處理你提供給它們的所有位元組（或者是你期望它處理的位元組），因為它" +"們主要的重點是處理網路緩衝區。一般來說，它們會在關聯的網路衝區已滿 " +"(``send``) 或已清空 (``recv``) 時回傳，然後告訴你它們處理了多少位元組。*你* " +"\\的責任是一直呼叫它們直到你所有的訊息處理完成。" + +#: ../../howto/sockets.rst:160 +msgid "" +"When a ``recv`` returns 0 bytes, it means the other side has closed (or is " +"in the process of closing) the connection. You will not receive any more " +"data on this connection. Ever. You may be able to send data successfully; " +"I'll talk more about this later." +msgstr "" +"當 ``recv`` 回傳「零位元組 (0 bytes)」時，就表示另一端已經關閉（或著正在關" +"閉）連線。你再也不能從這個連線上取得任何資料了。你可能還是可以成功發送資料；" +"我稍後會對此進行更詳細的解釋。" + +#: ../../howto/sockets.rst:165 +msgid "" +"A protocol like HTTP uses a socket for only one transfer. The client sends a " +"request, then reads a reply. That's it. The socket is discarded. This means " +"that a client can detect the end of the reply by receiving 0 bytes." +msgstr "" +"像 HTTP 這樣的協定只使用一個 socket 進行一次傳輸，用戶端發送一個請求，然後讀" +"取一個回覆。就這樣，然後這個 socket 就會被銷毀。這表示者用戶端可以透過接收" +"「零位元組」來檢測回覆的結束。" + +#: ../../howto/sockets.rst:169 +msgid "" +"But if you plan to reuse your socket for further transfers, you need to " +"realize that *there is no* :abbr:`EOT (End of Transfer)` *on a socket.* I " +"repeat: if a socket ``send`` or ``recv`` returns after handling 0 bytes, the " +"connection has been broken. If the connection has *not* been broken, you " +"may wait on a ``recv`` forever, because the socket will *not* tell you that " +"there's nothing more to read (for now). Now if you think about that a bit, " +"you'll come to realize a fundamental truth of sockets: *messages must either " +"be fixed length* (yuck), *or be delimited* (shrug), *or indicate how long " +"they are* (much better), *or end by shutting down the connection*. The " +"choice is entirely yours, (but some ways are righter than others)." +msgstr "" +"但是如果你打算在之後的傳輸中重新利用 socket 的話，你需要明白\\ *socket 中是不" +"存在* \\ :abbr:`EOT （傳輸結束）`。重申一次：如果一個 socket 的 ``send`` 或 " +"``recv`` 處理了「零位元組」後回傳，表示連線已經斷開。如果連線\\ *沒有* \\斷" +"開，你可能會永遠處於等待 ``recv`` 的狀態，因為（就目前來說）socket *不會* " +"\\告訴你沒有更多資料可以讀取了。現在，如果你稍微思考一下，你就會意識到 " +"socket 的一個基本事實：*訊息要麼是一個固定的長度（不好的做法），要麼是可以被" +"分隔的（普通的做法），要麼是指定其長度（更好地做法），要麼透過關閉連線來結" +"束。*\\ 完全由你來決定要使用哪種方式（但有些方法比其他方法來的更好）。" + +#: ../../howto/sockets.rst:180 +msgid "" +"Assuming you don't want to end the connection, the simplest solution is a " +"fixed length message::" +msgstr "假設你不想結束連線，最簡單的方式就是使用固定長度的訊息： ::" + +#: ../../howto/sockets.rst:183 +msgid "" +"class MySocket:\n" +" \"\"\"demonstration class only\n" +" - coded for clarity, not efficiency\n" +" \"\"\"\n" +"\n" +" def __init__(self, sock=None):\n" +" if sock is None:\n" +" self.sock = socket.socket(\n" +" socket.AF_INET, socket.SOCK_STREAM)\n" +" else:\n" +" self.sock = sock\n" +"\n" +" def connect(self, host, port):\n" +" self.sock.connect((host, port))\n" +"\n" +" def mysend(self, msg):\n" +" totalsent = 0\n" +" while totalsent < MSGLEN:\n" +" sent = self.sock.send(msg[totalsent:])\n" +" if sent == 0:\n" +" raise RuntimeError(\"socket connection broken\")\n" +" totalsent = totalsent + sent\n" +"\n" +" def myreceive(self):\n" +" chunks = []\n" +" bytes_recd = 0\n" +" while bytes_recd < MSGLEN:\n" +" chunk = self.sock.recv(min(MSGLEN - bytes_recd, 2048))\n" +" if chunk == b'':\n" +" raise RuntimeError(\"socket connection broken\")\n" +" chunks.append(chunk)\n" +" bytes_recd = bytes_recd + len(chunk)\n" +" return b''.join(chunks)" +msgstr "" + +#: ../../howto/sockets.rst:217 +msgid "" +"The sending code here is usable for almost any messaging scheme - in Python " +"you send strings, and you can use ``len()`` to determine its length (even if " +"it has embedded ``\\0`` characters). It's mostly the receiving code that " +"gets more complex. (And in C, it's not much worse, except you can't use " +"``strlen`` if the message has embedded ``\\0``\\ s.)" +msgstr "" +"發送部分的程式碼幾乎可用於任何訊息的傳送方式 - 在 Python 中你發送一個字串，可" +"以用 ``len()`` 來確認他的長度（即使字串包含了 ``\\0`` 字元）。在這裡，主要是" +"接收的程式碼變得更複雜一些。（在 C 語言中，情況沒有變得更糟，只是如果訊息中包" +"含了 ``\\0`` 字元，你就不能使用 ``strlen`` 函式。）" + +#: ../../howto/sockets.rst:223 +msgid "" +"The easiest enhancement is to make the first character of the message an " +"indicator of message type, and have the type determine the length. Now you " +"have two ``recv``\\ s - the first to get (at least) that first character so " +"you can look up the length, and the second in a loop to get the rest. If you " +"decide to go the delimited route, you'll be receiving in some arbitrary " +"chunk size, (4096 or 8192 is frequently a good match for network buffer " +"sizes), and scanning what you've received for a delimiter." +msgstr "" +"最簡單的改進方法是將訊息的第一個字元表示訊息的類型，並根據訊息的類型來決定訊" +"息的長度。現在你需要使用兩次 ``recv`` - 第一次用於接收（至少）第一個字元來得" +"知長度，第二次用於在迴圈中接收剩下的訊息。如果你決定使用分隔符號的方式，你將" +"會以某個任意的區塊大小進行接收（4096 或 8192 通常是網路緩衝區大小的良好選" +"擇），並在收到的內容中掃描分隔符號。" + +#: ../../howto/sockets.rst:231 +msgid "" +"One complication to be aware of: if your conversational protocol allows " +"multiple messages to be sent back to back (without some kind of reply), and " +"you pass ``recv`` an arbitrary chunk size, you may end up reading the start " +"of a following message. You'll need to put that aside and hold onto it, " +"until it's needed." +msgstr "" +"需要注意的一個複雜情況是，如果你的通訊協定允許連續發送多個訊息（沒有任何回" +"應），並且你傳遞給 ``recv`` 函式一個任意的區塊大小，最後有可能讀取到下一條訊" +"息的開頭。你需要將其放在一旁並保留下來，直到需要使用的時候。" + +#: ../../howto/sockets.rst:237 +msgid "" +"Prefixing the message with its length (say, as 5 numeric characters) gets " +"more complex, because (believe it or not), you may not get all 5 characters " +"in one ``recv``. In playing around, you'll get away with it; but in high " +"network loads, your code will very quickly break unless you use two ``recv`` " +"loops - the first to determine the length, the second to get the data part " +"of the message. Nasty. This is also when you'll discover that ``send`` does " +"not always manage to get rid of everything in one pass. And despite having " +"read this, you will eventually get bit by it!" +msgstr "" +"使用長度作為訊息的前綴（例如，使用 5 個數字字元表示）會變得更複雜，因為（信不" +"信由你）你可能無法在一次 ``recv`` 中獲得所有 5 個字元。在一般使用下，可能不會" +"有這個狀況，但在高負載的網路下，除非使用兩個 ``recv`` （第一個用於確定長度，" +"第二個用於取得訊息的資料部分），否則你的程式碼很快就會出現錯誤。這令人非常頭" +"痛。同樣的情況也會讓你發現 ``send`` 並不總能在一次傳輸中完全清除所有內容。儘" +"管已經閱讀了這篇文章，但最終還是無法解決！" + +#: ../../howto/sockets.rst:246 +msgid "" +"In the interests of space, building your character, (and preserving my " +"competitive position), these enhancements are left as an exercise for the " +"reader. Lets move on to cleaning up." +msgstr "" +"為了節省篇幅、培養你的技能（並保持我的競爭優勢），這些改進方法留給讀者自行練" +"習。現在讓我們開始進行清理工作。" + +#: ../../howto/sockets.rst:252 +msgid "Binary Data" +msgstr "二進位資料" + +#: ../../howto/sockets.rst:254 +msgid "" +"It is perfectly possible to send binary data over a socket. The major " +"problem is that not all machines use the same formats for binary data. For " +"example, `network byte order `_ is big-endian, with the most significant byte " +"first, so a 16 bit integer with the value ``1`` would be the two hex bytes " +"``00 01``. However, most common processors (x86/AMD64, ARM, RISC-V), are " +"little-endian, with the least significant byte first - that same ``1`` would " +"be ``01 00``." +msgstr "" +"使用 socket 傳輸二進位資料完全是可行的。最主要的問題在於不同機器使用不同的二" +"進位資料格式。例如，`網路二進位順序 `_ 採用的是「大端序 big-endian」，所以一個值為 ``1`` " +"的 16 位元整數會表示成兩個 16 進位的位元組 ``00 01``。然而大多數常見的處理器 " +"(x86/AMD64，ARM，RISC-V) 採用的是「小端序 little-endian」，所以相同的 ``1`` " +"會被表示成 ``01 00``。（譯者注：將一個多位數的低位放在較小的位址處，高位放在" +"較大的位址處，則稱小端序；反之則稱大端序。）" + +#: ../../howto/sockets.rst:262 +msgid "" +"Socket libraries have calls for converting 16 and 32 bit integers - ``ntohl, " +"htonl, ntohs, htons`` where \"n\" means *network* and \"h\" means *host*, " +"\"s\" means *short* and \"l\" means *long*. Where network order is host " +"order, these do nothing, but where the machine is byte-reversed, these swap " +"the bytes around appropriately." +msgstr "" +"Socket 函式庫提供了用於轉換 16 位元和 32 位元整數的函式 - ``ntohl, htonl, " +"ntohs, htons``，其中 \"n\" 表示 *network*，\"h\" 表示 *host*，\"s\" 表示 " +"*short*，\"l\" 表示 *long*。當網路的位元組順序和主機位元組順序相同時，這些函" +"式不會做任何操作，但當主機的位元組順序相反時，這些函式會適當的交換位元組順" +"序。" + +#: ../../howto/sockets.rst:268 +msgid "" +"In these days of 64-bit machines, the ASCII representation of binary data is " +"frequently smaller than the binary representation. That's because a " +"surprising amount of the time, most integers have the value 0, or maybe 1. " +"The string ``\"0\"`` would be two bytes, while a full 64-bit integer would " +"be 8. Of course, this doesn't fit well with fixed-length messages. " +"Decisions, decisions." +msgstr "" +"在現今的 64 位元機器中，二進位資料的 ASCII 表示通常會比二進位表示要小，這是因" +"為在很多情況下，大多數整數的值為 0 或者 1。例如，字串形式的 ``\"0\"`` 是兩個" +"位元組，而完整的 64 位元整數則是 8 個位元組。當然，這對固定長度的訊息來說不太" +"適合，需要自行決定。" + +#: ../../howto/sockets.rst:277 +msgid "Disconnecting" +msgstr "結束連線" + +#: ../../howto/sockets.rst:279 +msgid "" +"Strictly speaking, you're supposed to use ``shutdown`` on a socket before " +"you ``close`` it. The ``shutdown`` is an advisory to the socket at the " +"other end. Depending on the argument you pass it, it can mean \"I'm not " +"going to send anymore, but I'll still listen\", or \"I'm not listening, good " +"riddance!\". Most socket libraries, however, are so used to programmers " +"neglecting to use this piece of etiquette that normally a ``close`` is the " +"same as ``shutdown(); close()``. So in most situations, an explicit " +"``shutdown`` is not needed." +msgstr "" +"嚴格來說，在關閉 socket 前，你應該使用 ``shutdown`` 函式。``shutdown`` 函式是" +"發送給 socket 另一端的一個提醒。根據你傳遞的引數，它可以表示「我不會再發送任" +"何訊息了，但我仍然會持續監聽」，或者是「我不會再繼續監聽了，真讚！」。然而，" +"大多數的 socket 函式庫或程式設計師都習慣忽略這種禮節，因為通常情況下 " +"``close`` 跟 ``shutdown(); close()`` 是一樣的。所以在大多數情況下，不需要再特" +"地使用 ``shutdown`` 了。" + +#: ../../howto/sockets.rst:287 +msgid "" +"One way to use ``shutdown`` effectively is in an HTTP-like exchange. The " +"client sends a request and then does a ``shutdown(1)``. This tells the " +"server \"This client is done sending, but can still receive.\" The server " +"can detect \"EOF\" by a receive of 0 bytes. It can assume it has the " +"complete request. The server sends a reply. If the ``send`` completes " +"successfully then, indeed, the client was still receiving." +msgstr "" +"有效使用 ``shutdown`` 的一種方式是在類似 HTTP 的交換中，用戶端發送請求後，然" +"後使用 ``shutdown(1)``。這告訴伺服器「這個用戶端已經發送完成，但仍可以接" +"收」。伺服器可以透過接收「零位元組」來檢測 \"EOF\"。這樣它就可以確定已經接收" +"到完整的請求。伺服器發送回覆，如果 ``send`` 成功完成，那麼用戶端確實在持續接" +"收。" + +#: ../../howto/sockets.rst:294 +msgid "" +"Python takes the automatic shutdown a step further, and says that when a " +"socket is garbage collected, it will automatically do a ``close`` if it's " +"needed. But relying on this is a very bad habit. If your socket just " +"disappears without doing a ``close``, the socket at the other end may hang " +"indefinitely, thinking you're just being slow. *Please* ``close`` your " +"sockets when you're done." +msgstr "" +"Python 更進一步地採取自動關閉的步驟，並且當 socket 被垃圾回收機制回收時，如果" +"需要的話，他會自動執行 ``close``。但依賴這個機制是一個非常不好的習慣，如果你" +"的 socket 在沒有 ``close`` 的情況下消失了，那麼另一端的 socket 可能會認為你只" +"是慢了一步，而無期限的等待。*請務必* \\在使用完畢後使用 ``close`` 關閉你的 " +"sockets。" + +#: ../../howto/sockets.rst:302 +msgid "When Sockets Die" +msgstr "Sockets 何時銷毀" + +#: ../../howto/sockets.rst:304 +msgid "" +"Probably the worst thing about using blocking sockets is what happens when " +"the other side comes down hard (without doing a ``close``). Your socket is " +"likely to hang. TCP is a reliable protocol, and it will wait a long, long " +"time before giving up on a connection. If you're using threads, the entire " +"thread is essentially dead. There's not much you can do about it. As long as " +"you aren't doing something dumb, like holding a lock while doing a blocking " +"read, the thread isn't really consuming much in the way of resources. Do " +"*not* try to kill the thread - part of the reason that threads are more " +"efficient than processes is that they avoid the overhead associated with the " +"automatic recycling of resources. In other words, if you do manage to kill " +"the thread, your whole process is likely to be screwed up." +msgstr "" +"使用阻塞式 socket 最糟糕的地方可能是在另一端突然強制關閉（未執行 ``close``）" +"的情況下會發生什麼？你的 socket 很可能會處於阻塞狀態。TCP 是一種可靠的協定，" +"它在放棄連線之前會等待很長很長的時間。如果你正在使用執行緒，整個執行緒基本上" +"已經無法使用。在這方面，你無法做太多事情。只要你不做一些愚蠢的事情，比如在執" +"行阻塞式讀取時持有一個鎖，那麼執行緒並不會消耗太多資源。*不要*\\ 試圖終止執行" +"緒 - 執行緒比行程更有效的部分原因是它們避免了與自動回收資源相關的開銷。換句話" +"說，如果你確實設法終止了執行緒，整個行程可能會出現問題。" + +#: ../../howto/sockets.rst:318 +msgid "Non-blocking Sockets" +msgstr "非阻塞的 Sockets" + +#: ../../howto/sockets.rst:320 +msgid "" +"If you've understood the preceding, you already know most of what you need " +"to know about the mechanics of using sockets. You'll still use the same " +"calls, in much the same ways. It's just that, if you do it right, your app " +"will be almost inside-out." +msgstr "" +"如果你已經理解了前面的內容，你已經知道了大部分關於使用 sockets 的機制的所需知" +"識，你仍然會以非常相似的方式使用相同的函式。就這樣而已，如果你做的對，你的程" +"式就會是近乎完美的。" + +#: ../../howto/sockets.rst:325 +msgid "" +"In Python, you use ``socket.setblocking(False)`` to make it non-blocking. In " +"C, it's more complex, (for one thing, you'll need to choose between the BSD " +"flavor ``O_NONBLOCK`` and the almost indistinguishable POSIX flavor " +"``O_NDELAY``, which is completely different from ``TCP_NODELAY``), but it's " +"the exact same idea. You do this after creating the socket, but before using " +"it. (Actually, if you're nuts, you can switch back and forth.)" +msgstr "" +"在 Python 中可以使用 ``socket.setblocking(False)`` 來設定為非阻塞。在 C 的作" +"法更為複雜（例如，你需要在 BSD 風格的 ``O_NONBLOCK`` 和幾乎沒有區別的 POSIX " +"風格的 ``O_NDELAY`` 之間做出選擇，這與 ``TCP_NODELAY`` 完全不同），但基本思想" +"是一樣的，你要在建立 socket 後但在使用它之前執行此操作。（實際上，如果你願意" +"的話，你甚至可以來回切換。）" + +#: ../../howto/sockets.rst:332 +msgid "" +"The major mechanical difference is that ``send``, ``recv``, ``connect`` and " +"``accept`` can return without having done anything. You have (of course) a " +"number of choices. You can check return code and error codes and generally " +"drive yourself crazy. If you don't believe me, try it sometime. Your app " +"will grow large, buggy and suck CPU. So let's skip the brain-dead solutions " +"and do it right." +msgstr "" +"主要的機制差異在於 ``send``、``recv``、``connect`` 和 ``accept`` 可能在沒有執" +"行任何操作的情況下就回傳了。你當然有多種選擇。你可以檢查回傳值和錯誤代碼，但" +"這些操作通常會讓自己抓狂。如果你不相信我，不妨試試看。你的應用程式會變得臃" +"腫、錯誤百出，並且占用 CPU。所以，讓我們跳過無腦的解決方案，使用正確的方式。" + +#: ../../howto/sockets.rst:339 +msgid "Use ``select``." +msgstr "使用 ``select``。" + +#: ../../howto/sockets.rst:341 +msgid "" +"In C, coding ``select`` is fairly complex. In Python, it's a piece of cake, " +"but it's close enough to the C version that if you understand ``select`` in " +"Python, you'll have little trouble with it in C::" +msgstr "" +"在 C 中，編寫 ``select`` 是非常複雜的，但在 Python 中，這很簡單，並與 C 的版" +"本非常類似，如果你理解了 Python 中的 ``select``，在 C 中處理它時也不會有太大" +"的困難： ::" + +#: ../../howto/sockets.rst:345 +msgid "" +"ready_to_read, ready_to_write, in_error = \\\n" +" select.select(\n" +" potential_readers,\n" +" potential_writers,\n" +" potential_errs,\n" +" timeout)" +msgstr "" +"ready_to_read, ready_to_write, in_error = \\\n" +" select.select(\n" +" potential_readers,\n" +" potential_writers,\n" +" potential_errs,\n" +" timeout)" + +#: ../../howto/sockets.rst:352 +msgid "" +"You pass ``select`` three lists: the first contains all sockets that you " +"might want to try reading; the second all the sockets you might want to try " +"writing to, and the last (normally left empty) those that you want to check " +"for errors. You should note that a socket can go into more than one list. " +"The ``select`` call is blocking, but you can give it a timeout. This is " +"generally a sensible thing to do - give it a nice long timeout (say a " +"minute) unless you have good reason to do otherwise." +msgstr "" +"你傳遞給 ``select`` 三個列表：第一個列表包含你可能想要嘗試讀取的所有 " +"sockets；第二個包含所有你可能想要嘗試寫入的 sockets，最後一個（通常為空）包含" +"你想要檢查錯誤的 sockets。你應該注意，一個 socket 可以同時存在於多個列表中。" +"``select`` 呼叫是阻塞的，但你可以設置超時。通常這是一個明智的做法 - 除非有充" +"分的理由，否則給它一個很長的超時（比如一分鐘）。" + +#: ../../howto/sockets.rst:360 +msgid "" +"In return, you will get three lists. They contain the sockets that are " +"actually readable, writable and in error. Each of these lists is a subset " +"(possibly empty) of the corresponding list you passed in." +msgstr "" +"作為回傳，你將獲得三個列表。它們包含實際上可讀取、可寫入和出錯的 sockets。這" +"些列表中的每一個都是你傳入的相應列表的子集（可能為空）。" + +#: ../../howto/sockets.rst:364 +msgid "" +"If a socket is in the output readable list, you can be as-close-to-certain-" +"as-we-ever-get-in-this-business that a ``recv`` on that socket will return " +"*something*. Same idea for the writable list. You'll be able to send " +"*something*. Maybe not all you want to, but *something* is better than " +"nothing. (Actually, any reasonably healthy socket will return as writable - " +"it just means outbound network buffer space is available.)" +msgstr "" +"如果一個 socket 在輸出的可讀列表中，你可以幾乎確定，在這個業務中我們能夠得到" +"的最接近確定的事情是，對該 socket 的 ``recv`` 呼叫將會回傳一些\\ *內容*。對於" +"可寫列表，也是同樣的想法。你將能夠發送一些 *內容*。也許不是全部，但\\ *一些內" +"容*\\ 總比什麼都沒有好。（實際上，任何比較正常的 socket 都會以可寫的方式回傳 " +"- 這只是意味者「外送網路 (outbound network)」的緩衝空間是可用的。）" + +#: ../../howto/sockets.rst:371 +msgid "" +"If you have a \"server\" socket, put it in the potential_readers list. If it " +"comes out in the readable list, your ``accept`` will (almost certainly) " +"work. If you have created a new socket to ``connect`` to someone else, put " +"it in the potential_writers list. If it shows up in the writable list, you " +"have a decent chance that it has connected." +msgstr "" +"如果你有一個「伺服器端」socket，請將其放在 potential_readers 列表中，如果它在" +"可讀列表中出現，你的 ``accept`` 呼叫（幾乎可以確定）會成功。如果你建立了一個" +"新的 socket 去 ``connect`` 到其他地方，請將它放在 potential_writers 列表中，" +"如果它在可寫列表中出現，那麼他有可能已經連接上了。" + +#: ../../howto/sockets.rst:377 +msgid "" +"Actually, ``select`` can be handy even with blocking sockets. It's one way " +"of determining whether you will block - the socket returns as readable when " +"there's something in the buffers. However, this still doesn't help with the " +"problem of determining whether the other end is done, or just busy with " +"something else." +msgstr "" +"實際上，即使是使用阻塞式 socket 的情況下，``select`` 也很方便。這是一種判斷是" +"否會被阻塞的方法之一 - 當緩衝區中有某些內容時， socket 會回傳為可讀。然而，這" +"仍然無法解決判斷另一端是否完成，或者只是忙於其他事情的問題。" + +#: ../../howto/sockets.rst:382 +msgid "" +"**Portability alert**: On Unix, ``select`` works both with the sockets and " +"files. Don't try this on Windows. On Windows, ``select`` works with sockets " +"only. Also note that in C, many of the more advanced socket options are done " +"differently on Windows. In fact, on Windows I usually use threads (which " +"work very, very well) with my sockets." +msgstr "" +"**可移植性警告**：在 Unix 上，``select`` 同時適用於 sockets 和文件。但請不要" +"在 Windows 上嘗試這麼做，在 Windows 上，``select`` 只適用於 sockets。同時，請" +"注意，在 C 語言中，許多更進階的 socket 選項在 Windows 上有不同的實現方式。實" +"際上，在 Windows 上，我通常會使用執行緒（這非常，非常有效）與我的 sockets 一" +"起使用。" diff --git a/howto/sorting.po b/howto/sorting.po index 7455a8b96f..fd75f88202 100644 --- a/howto/sorting.po +++ b/howto/sorting.po @@ -1,830 +1,830 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Ching-Lung Chuang, 2015 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: 2024-12-20 19:16+0800\n" -"Last-Translator: Li-Hung Wang \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" -"X-Generator: Poedit 3.4.2\n" - -#: ../../howto/sorting.rst:4 -msgid "Sorting Techniques" -msgstr "排序技法" - -#: ../../howto/sorting.rst:0 -msgid "Author" -msgstr "作者" - -#: ../../howto/sorting.rst:6 -msgid "Andrew Dalke and Raymond Hettinger" -msgstr "Andrew Dalke 和 Raymond Hettinger" - -#: ../../howto/sorting.rst:9 -msgid "" -"Python lists have a built-in :meth:`list.sort` method that modifies the list " -"in-place. There is also a :func:`sorted` built-in function that builds a " -"new sorted list from an iterable." -msgstr "" -"Python 的串列有一個內建的 :meth:`list.sort` 方法可以原地 (in-place) 排序該串" -"列，也有一個內建的 :func:`sorted` 函式可以排序可疊代物件 (iterable) 並建立一" -"個新的排序好的串列。" - -#: ../../howto/sorting.rst:13 -msgid "" -"In this document, we explore the various techniques for sorting data using " -"Python." -msgstr "在這份文件裡，我們探索使用 Python 排序資料的各種方法。" - -#: ../../howto/sorting.rst:17 -msgid "Sorting Basics" -msgstr "基礎排序" - -#: ../../howto/sorting.rst:19 -msgid "" -"A simple ascending sort is very easy: just call the :func:`sorted` function. " -"It returns a new sorted list:" -msgstr "" -"單純的升冪排序很容易做到：只要呼叫 :func:`sorted` 函式，它會回傳一個新的串" -"列：" - -#: ../../howto/sorting.rst:22 -msgid "" -">>> sorted([5, 2, 3, 1, 4])\n" -"[1, 2, 3, 4, 5]" -msgstr "" -">>> sorted([5, 2, 3, 1, 4])\n" -"[1, 2, 3, 4, 5]" - -#: ../../howto/sorting.rst:27 -msgid "" -"You can also use the :meth:`list.sort` method. It modifies the list in-place " -"(and returns ``None`` to avoid confusion). Usually it's less convenient " -"than :func:`sorted` - but if you don't need the original list, it's slightly " -"more efficient." -msgstr "" -"你也可以使用 :meth:`list.sort` 方法，它會原地排序串列（並回傳 ``None`` 以避免" -"混淆）。它通常會比 :func:`sorted` 來得不方便——但如果你不需要保留原始串列的" -"話，它會稍微有效率一點。" - -#: ../../howto/sorting.rst:32 -msgid "" -">>> a = [5, 2, 3, 1, 4]\n" -">>> a.sort()\n" -">>> a\n" -"[1, 2, 3, 4, 5]" -msgstr "" -">>> a = [5, 2, 3, 1, 4]\n" -">>> a.sort()\n" -">>> a\n" -"[1, 2, 3, 4, 5]" - -#: ../../howto/sorting.rst:39 -msgid "" -"Another difference is that the :meth:`list.sort` method is only defined for " -"lists. In contrast, the :func:`sorted` function accepts any iterable." -msgstr "" -"另一個差異是 :meth:`list.sort` 方法只有定義在串列上，而 :func:`sorted` 函式可" -"以接受任何可疊代物件。" - -#: ../../howto/sorting.rst:42 -msgid "" -">>> sorted({1: 'D', 2: 'B', 3: 'B', 4: 'E', 5: 'A'})\n" -"[1, 2, 3, 4, 5]" -msgstr "" -">>> sorted({1: 'D', 2: 'B', 3: 'B', 4: 'E', 5: 'A'})\n" -"[1, 2, 3, 4, 5]" - -#: ../../howto/sorting.rst:48 -msgid "Key Functions" -msgstr "鍵函式 (key functions)" - -#: ../../howto/sorting.rst:50 -msgid "" -"The :meth:`list.sort` method and the " -"functions :func:`sorted`, :func:`min`, :func:`max`, :func:`heapq.nsmallest`, " -"and :func:`heapq.nlargest` have a *key* parameter to specify a function (or " -"other callable) to be called on each list element prior to making " -"comparisons." -msgstr "" -":meth:`list.sort` 方法和 :func:`sorted`、:func:`min`、:func:`max`、:func:`heapq.nsmallest` 及" -" :func:`heapq.nlargest` 函式都有一個參數 *key* 可以指定一個函式（或其" -"它可呼叫物件 (callable)），其會在每個串列元素做比較前被呼叫。" - -#: ../../howto/sorting.rst:56 -msgid "" -"For example, here's a case-insensitive string comparison " -"using :meth:`str.casefold`:" -msgstr "例如使用 :meth:`str.casefold` 來做不區分大小寫的字串比對：" - -#: ../../howto/sorting.rst:59 -msgid "" -">>> sorted(\"This is a test string from Andrew\".split(), key=str.casefold)\n" -"['a', 'Andrew', 'from', 'is', 'string', 'test', 'This']" -msgstr "" -">>> sorted(\"This is a test string from Andrew\".split(), key=str.casefold)\n" -"['a', 'Andrew', 'from', 'is', 'string', 'test', 'This']" - -#: ../../howto/sorting.rst:64 -msgid "" -"The value of the *key* parameter should be a function (or other callable) " -"that takes a single argument and returns a key to use for sorting purposes. " -"This technique is fast because the key function is called exactly once for " -"each input record." -msgstr "" -"參數 *key* 的值必須是一個函式（或其它可呼叫物件），且這個函式接受單一引數並回" -"傳一個用來排序的鍵。因為對每個輸入來說鍵函式只會被呼叫一次，所以這個做法是快" -"速的。" - -#: ../../howto/sorting.rst:69 -msgid "" -"A common pattern is to sort complex objects using some of the object's " -"indices as keys. For example:" -msgstr "" -"一個常見的模式是在排序複雜物件的時候使用一部分物件的索引值當作鍵，例如：" - -#: ../../howto/sorting.rst:72 -msgid "" -">>> student_tuples = [\n" -"... ('john', 'A', 15),\n" -"... ('jane', 'B', 12),\n" -"... ('dave', 'B', 10),\n" -"... ]\n" -">>> sorted(student_tuples, key=lambda student: student[2]) # sort by age\n" -"[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]" -msgstr "" -">>> student_tuples = [\n" -"... ('john', 'A', 15),\n" -"... ('jane', 'B', 12),\n" -"... ('dave', 'B', 10),\n" -"... ]\n" -">>> sorted(student_tuples, key=lambda student: student[2]) # 依照年齡排序\n" -"[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]" - -#: ../../howto/sorting.rst:82 -msgid "" -"The same technique works for objects with named attributes. For example:" -msgstr "相同的做法也適用在有命名屬性的物件，例如：" - -#: ../../howto/sorting.rst:84 -msgid "" -">>> class Student:\n" -"... def __init__(self, name, grade, age):\n" -"... self.name = name\n" -"... self.grade = grade\n" -"... self.age = age\n" -"... def __repr__(self):\n" -"... return repr((self.name, self.grade, self.age))\n" -"\n" -">>> student_objects = [\n" -"... Student('john', 'A', 15),\n" -"... Student('jane', 'B', 12),\n" -"... Student('dave', 'B', 10),\n" -"... ]\n" -">>> sorted(student_objects, key=lambda student: student.age) # sort by " -"age\n" -"[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]" -msgstr "" -">>> class Student:\n" -"... def __init__(self, name, grade, age):\n" -"... self.name = name\n" -"... self.grade = grade\n" -"... self.age = age\n" -"... def __repr__(self):\n" -"... return repr((self.name, self.grade, self.age))\n" -"\n" -">>> student_objects = [\n" -"... Student('john', 'A', 15),\n" -"... Student('jane', 'B', 12),\n" -"... Student('dave', 'B', 10),\n" -"... ]\n" -">>> sorted(student_objects, key=lambda student: student.age) # 依照年齡排" -"序\n" -"[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]" - -#: ../../howto/sorting.rst:102 -msgid "" -"Objects with named attributes can be made by a regular class as shown above, " -"or they can be instances of :class:`~dataclasses.dataclass` or " -"a :term:`named tuple`." -msgstr "" -"具有命名屬性的物件可以如上方的方式使用一個常規的類別建立，或是他們可以" -"是 :class:`~dataclasses.dataclass` 的實例或是一個 :term:`named tuple`。" - -#: ../../howto/sorting.rst:107 -msgid "Operator Module Functions and Partial Function Evaluation" -msgstr "Operator 模組函式以及部份函式 (partial function) 評估" - -#: ../../howto/sorting.rst:109 -msgid "" -"The :term:`key function` patterns shown above are very common, so Python " -"provides convenience functions to make accessor functions easier and faster. " -"The :mod:`operator` module " -"has :func:`~operator.itemgetter`, :func:`~operator.attrgetter`, and " -"a :func:`~operator.methodcaller` function." -msgstr "" -"上述的\\ :term:`鍵函式 `\\ 模式非常常見，所以 Python 提供了方便" -"的函式讓物件存取更簡單且快速。:mod:`operator` 模組裡" -"有 :func:`~operator.itemgetter`、:func:`~operator.attrgetter` " -"及 :func:`~operator.methodcaller` 函式可以使用。" - -#: ../../howto/sorting.rst:114 -msgid "Using those functions, the above examples become simpler and faster:" -msgstr "使用這些函式讓上面的範例變得更簡單且快速：" - -#: ../../howto/sorting.rst:116 -msgid "" -">>> from operator import itemgetter, attrgetter\n" -"\n" -">>> sorted(student_tuples, key=itemgetter(2))\n" -"[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]\n" -"\n" -">>> sorted(student_objects, key=attrgetter('age'))\n" -"[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]" -msgstr "" -">>> from operator import itemgetter, attrgetter\n" -"\n" -">>> sorted(student_tuples, key=itemgetter(2))\n" -"[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]\n" -"\n" -">>> sorted(student_objects, key=attrgetter('age'))\n" -"[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]" - -#: ../../howto/sorting.rst:126 -msgid "" -"The operator module functions allow multiple levels of sorting. For example, " -"to sort by *grade* then by *age*:" -msgstr "" -"operator 模組的函式允許多層的排序，例如先用 *grade* 排序再用 *age* 排序：" - -#: ../../howto/sorting.rst:129 -msgid "" -">>> sorted(student_tuples, key=itemgetter(1,2))\n" -"[('john', 'A', 15), ('dave', 'B', 10), ('jane', 'B', 12)]\n" -"\n" -">>> sorted(student_objects, key=attrgetter('grade', 'age'))\n" -"[('john', 'A', 15), ('dave', 'B', 10), ('jane', 'B', 12)]" -msgstr "" -">>> sorted(student_tuples, key=itemgetter(1,2))\n" -"[('john', 'A', 15), ('dave', 'B', 10), ('jane', 'B', 12)]\n" -"\n" -">>> sorted(student_objects, key=attrgetter('grade', 'age'))\n" -"[('john', 'A', 15), ('dave', 'B', 10), ('jane', 'B', 12)]" - -#: ../../howto/sorting.rst:137 -msgid "" -"The :mod:`functools` module provides another helpful tool for making key-" -"functions. The :func:`~functools.partial` function can reduce the `arity " -"`_ of a multi-argument function making " -"it suitable for use as a key-function." -msgstr "" -"模組 :mod:`functools` 提供了另一個製作鍵函式的好用工" -"具。:func:`~functools.partial` 函式可以減少多引數函式的\\ `引數數目 `_，使其更適合作為鍵函式使用。" - -#: ../../howto/sorting.rst:142 -msgid "" -">>> from functools import partial\n" -">>> from unicodedata import normalize\n" -"\n" -">>> names = 'Zoë Åbjørn Núñez Élana Zeke Abe Nubia Eloise'.split()\n" -"\n" -">>> sorted(names, key=partial(normalize, 'NFD'))\n" -"['Abe', 'Åbjørn', 'Eloise', 'Élana', 'Nubia', 'Núñez', 'Zeke', 'Zoë']\n" -"\n" -">>> sorted(names, key=partial(normalize, 'NFC'))\n" -"['Abe', 'Eloise', 'Nubia', 'Núñez', 'Zeke', 'Zoë', 'Åbjørn', 'Élana']" -msgstr "" -">>> from functools import partial\n" -">>> from unicodedata import normalize\n" -"\n" -">>> names = 'Zoë Åbjørn Núñez Élana Zeke Abe Nubia Eloise'.split()\n" -"\n" -">>> sorted(names, key=partial(normalize, 'NFD'))\n" -"['Abe', 'Åbjørn', 'Eloise', 'Élana', 'Nubia', 'Núñez', 'Zeke', 'Zoë']\n" -"\n" -">>> sorted(names, key=partial(normalize, 'NFC'))\n" -"['Abe', 'Eloise', 'Nubia', 'Núñez', 'Zeke', 'Zoë', 'Åbjørn', 'Élana']" - -#: ../../howto/sorting.rst:156 -msgid "Ascending and Descending" -msgstr "升冪與降冪" - -#: ../../howto/sorting.rst:158 -msgid "" -"Both :meth:`list.sort` and :func:`sorted` accept a *reverse* parameter with " -"a boolean value. This is used to flag descending sorts. For example, to get " -"the student data in reverse *age* order:" -msgstr "" -":meth:`list.sort` 和 :func:`sorted` 都有一個 boolean 參數 *reverse* 用來表示" -"是否要降冪排序。例如將學生資料依據 *age* 做降冪排序：" - -#: ../../howto/sorting.rst:162 -msgid "" -">>> sorted(student_tuples, key=itemgetter(2), reverse=True)\n" -"[('john', 'A', 15), ('jane', 'B', 12), ('dave', 'B', 10)]\n" -"\n" -">>> sorted(student_objects, key=attrgetter('age'), reverse=True)\n" -"[('john', 'A', 15), ('jane', 'B', 12), ('dave', 'B', 10)]" -msgstr "" -">>> sorted(student_tuples, key=itemgetter(2), reverse=True)\n" -"[('john', 'A', 15), ('jane', 'B', 12), ('dave', 'B', 10)]\n" -"\n" -">>> sorted(student_objects, key=attrgetter('age'), reverse=True)\n" -"[('john', 'A', 15), ('jane', 'B', 12), ('dave', 'B', 10)]" - -#: ../../howto/sorting.rst:171 -msgid "Sort Stability and Complex Sorts" -msgstr "排序穩定性與複合排序" - -#: ../../howto/sorting.rst:173 -msgid "" -"Sorts are guaranteed to be `stable `_\\. That means that when multiple records have " -"the same key, their original order is preserved." -msgstr "" -"排序保證是\\ `穩定的 `_，意思是當有多筆資料有相同的鍵，它們會維持原來" -"的順序。" - -#: ../../howto/sorting.rst:177 -msgid "" -">>> data = [('red', 1), ('blue', 1), ('red', 2), ('blue', 2)]\n" -">>> sorted(data, key=itemgetter(0))\n" -"[('blue', 1), ('blue', 2), ('red', 1), ('red', 2)]" -msgstr "" -">>> data = [('red', 1), ('blue', 1), ('red', 2), ('blue', 2)]\n" -">>> sorted(data, key=itemgetter(0))\n" -"[('blue', 1), ('blue', 2), ('red', 1), ('red', 2)]" - -#: ../../howto/sorting.rst:183 -msgid "" -"Notice how the two records for *blue* retain their original order so that " -"``('blue', 1)`` is guaranteed to precede ``('blue', 2)``." -msgstr "" -"可以注意到有兩筆資料的鍵都是 *blue*，它們會維持本來的順序，即 ``('blue', " -"1)`` 保證在 ``('blue', 2)`` 前面。" - -#: ../../howto/sorting.rst:186 -msgid "" -"This wonderful property lets you build complex sorts in a series of sorting " -"steps. For example, to sort the student data by descending *grade* and then " -"ascending *age*, do the *age* sort first and then sort again using *grade*:" -msgstr "" -"這個美妙的特性讓你可以用一連串的排序來作出複合排序。例如對學生資料用 *grade* " -"做降冪排序再用 *age* 做升冪排序，你可以先用 *age* 排序一遍再用 *grade* 排序一" -"遍：" - -#: ../../howto/sorting.rst:190 -msgid "" -">>> s = sorted(student_objects, key=attrgetter('age')) # sort on " -"secondary key\n" -">>> sorted(s, key=attrgetter('grade'), reverse=True) # now sort on " -"primary key, descending\n" -"[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]" -msgstr "" -">>> s = sorted(student_objects, key=attrgetter('age')) # 依照次要鍵排序\n" -">>> sorted(s, key=attrgetter('grade'), reverse=True) # 現在依照主要鍵降" -"冪排序\n" -"[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]" - -#: ../../howto/sorting.rst:196 -msgid "" -"This can be abstracted out into a wrapper function that can take a list and " -"tuples of field and order to sort them on multiple passes." -msgstr "" -"這可以抽出一個包裝函式 (wrapper function)，接受一個串列及多個欄位及升降冪的元" -"組為引數，來對這個串列排序多遍。" - -#: ../../howto/sorting.rst:199 -msgid "" -">>> def multisort(xs, specs):\n" -"... for key, reverse in reversed(specs):\n" -"... xs.sort(key=attrgetter(key), reverse=reverse)\n" -"... return xs\n" -"\n" -">>> multisort(list(student_objects), (('grade', True), ('age', False)))\n" -"[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]" -msgstr "" -">>> def multisort(xs, specs):\n" -"... for key, reverse in reversed(specs):\n" -"... xs.sort(key=attrgetter(key), reverse=reverse)\n" -"... return xs\n" -"\n" -">>> multisort(list(student_objects), (('grade', True), ('age', False)))\n" -"[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]" - -#: ../../howto/sorting.rst:209 -msgid "" -"The `Timsort `_ algorithm used in " -"Python does multiple sorts efficiently because it can take advantage of any " -"ordering already present in a dataset." -msgstr "" -"Python 裡使用的 `Timsort `_ 演算法，因" -"為能利用資料集裡已經有的順序，可以有效率地做多次排序。" - -#: ../../howto/sorting.rst:214 -msgid "Decorate-Sort-Undecorate" -msgstr "裝飾-排序-移除裝飾 (decorate-sort-undecorate)" - -#: ../../howto/sorting.rst:216 -msgid "This idiom is called Decorate-Sort-Undecorate after its three steps:" -msgstr "這個用語的來源是因為它做了以下三件事情：" - -#: ../../howto/sorting.rst:218 -msgid "" -"First, the initial list is decorated with new values that control the sort " -"order." -msgstr "首先，原始串列會裝飾 (decorated) 上新的值用來控制排序的順序。" - -#: ../../howto/sorting.rst:220 -msgid "Second, the decorated list is sorted." -msgstr "接下來，排序裝飾過的串列。" - -#: ../../howto/sorting.rst:222 -msgid "" -"Finally, the decorations are removed, creating a list that contains only the " -"initial values in the new order." -msgstr "最後，裝飾會被移除，並以新的順序產生一個只包含原始值的串列。" - -#: ../../howto/sorting.rst:225 -msgid "" -"For example, to sort the student data by *grade* using the DSU approach:" -msgstr "例如用上面說的方式來以 *grade* 排序學生資料：" - -#: ../../howto/sorting.rst:227 -msgid "" -">>> decorated = [(student.grade, i, student) for i, student in " -"enumerate(student_objects)]\n" -">>> decorated.sort()\n" -">>> [student for grade, i, student in decorated] # undecorate\n" -"[('john', 'A', 15), ('jane', 'B', 12), ('dave', 'B', 10)]" -msgstr "" -">>> decorated = [(student.grade, i, student) for i, student in " -"enumerate(student_objects)]\n" -">>> decorated.sort()\n" -">>> [student for grade, i, student in decorated] # 移除裝飾\n" -"[('john', 'A', 15), ('jane', 'B', 12), ('dave', 'B', 10)]" - -#: ../../howto/sorting.rst:234 -msgid "" -"This idiom works because tuples are compared lexicographically; the first " -"items are compared; if they are the same then the second items are compared, " -"and so on." -msgstr "" -"這個方式會有效是因為元組是依照字典順序 (lexicographically) 來比較，先比較第一" -"個項目，如果一樣再比較第二個項目，並依此類推。" - -#: ../../howto/sorting.rst:238 -msgid "" -"It is not strictly necessary in all cases to include the index *i* in the " -"decorated list, but including it gives two benefits:" -msgstr "" -"在所有情況下都把索引 *i* 加入已裝飾的串列並不是絕對需要的，但這樣做會有兩個好" -"處：" - -#: ../../howto/sorting.rst:241 -msgid "" -"The sort is stable -- if two items have the same key, their order will be " -"preserved in the sorted list." -msgstr "" -"排序會是穩定的 -- 如果兩個項目有相同的鍵，它們在排序好的串列中會保持原來的順" -"序。" - -#: ../../howto/sorting.rst:244 -msgid "" -"The original items do not have to be comparable because the ordering of the " -"decorated tuples will be determined by at most the first two items. So for " -"example the original list could contain complex numbers which cannot be " -"sorted directly." -msgstr "" -"原始項目不需要是可以比較的，因為最多只會用到前兩個項目就能決定裝飾過的元組的" -"順序。例如原始串列可以包含不能直接用來排序的複數。" - -#: ../../howto/sorting.rst:249 -msgid "" -"Another name for this idiom is `Schwartzian transform `_\\, after Randal L. Schwartz, " -"who popularized it among Perl programmers." -msgstr "" -"這個用語的另一個名字是 `Schwartzian transform `_，是由於 Randal L. Schwartz 讓這個方法在 Perl 程式設" -"計師間普及。" - -#: ../../howto/sorting.rst:253 -msgid "" -"Now that Python sorting provides key-functions, this technique is not often " -"needed." -msgstr "而因為 Python 的排序提供了鍵函式，已經不太需要用到這個方法了。" - -#: ../../howto/sorting.rst:256 -msgid "Comparison Functions" -msgstr "比較函式 (comparison functions)" - -#: ../../howto/sorting.rst:258 -msgid "" -"Unlike key functions that return an absolute value for sorting, a comparison " -"function computes the relative ordering for two inputs." -msgstr "不像鍵函式回傳一個用來排序的值，比較函式計算兩個輸入間的相對順序。" - -#: ../../howto/sorting.rst:261 -msgid "" -"For example, a `balance scale `_ compares two samples giving a " -"relative ordering: lighter, equal, or heavier. Likewise, a comparison " -"function such as ``cmp(a, b)`` will return a negative value for less-than, " -"zero if the inputs are equal, or a positive value for greater-than." -msgstr "" -"例如\\ `天秤 `_\\ 比較兩邊樣本並給出相對的順序：較輕、相同或較" -"重。同樣地，像是 ``cmp(a, b)`` 這樣的比較函式會回傳負數代表小於、0 代表輸入相" -"同或正數代表大於。" - -#: ../../howto/sorting.rst:268 -msgid "" -"It is common to encounter comparison functions when translating algorithms " -"from other languages. Also, some libraries provide comparison functions as " -"part of their API. For example, :func:`locale.strcoll` is a comparison " -"function." -msgstr "" -"當從其它語言翻譯演算法的時候常看到比較函式。有些函式庫也會提供比較函式作為其 " -"API 的一部份，例如 :func:`locale.strcoll` 就是一個比較函式。" - -#: ../../howto/sorting.rst:272 -msgid "" -"To accommodate those situations, Python " -"provides :class:`functools.cmp_to_key` to wrap the comparison function to " -"make it usable as a key function::" -msgstr "" -"為了滿足這些情境，Python 提供 :class:`functools.cmp_to_key` 來包裝比較函式，" -"讓其可以當作鍵函式來使用： ::" - -#: ../../howto/sorting.rst:276 -msgid "sorted(words, key=cmp_to_key(strcoll)) # locale-aware sort order" -msgstr "sorted(words, key=cmp_to_key(strcoll)) # 理解語系的排序順序" - -#: ../../howto/sorting.rst:279 -msgid "Strategies For Unorderable Types and Values" -msgstr "" - -#: ../../howto/sorting.rst:281 -msgid "" -"A number of type and value issues can arise when sorting. Here are some " -"strategies that can help:" -msgstr "" - -#: ../../howto/sorting.rst:284 -msgid "Convert non-comparable input types to strings prior to sorting:" -msgstr "" - -#: ../../howto/sorting.rst:286 -msgid "" -">>> data = ['twelve', '11', 10]\n" -">>> sorted(map(str, data))\n" -"['10', '11', 'twelve']" -msgstr "" -">>> data = ['twelve', '11', 10]\n" -">>> sorted(map(str, data))\n" -"['10', '11', 'twelve']" - -#: ../../howto/sorting.rst:292 -msgid "" -"This is needed because most cross-type comparisons raise a :exc:`TypeError`." -msgstr "" - -#: ../../howto/sorting.rst:295 -msgid "Remove special values prior to sorting:" -msgstr "" - -#: ../../howto/sorting.rst:297 -msgid "" -">>> from math import isnan\n" -">>> from itertools import filterfalse\n" -">>> data = [3.3, float('nan'), 1.1, 2.2]\n" -">>> sorted(filterfalse(isnan, data))\n" -"[1.1, 2.2, 3.3]" -msgstr "" -">>> from math import isnan\n" -">>> from itertools import filterfalse\n" -">>> data = [3.3, float('nan'), 1.1, 2.2]\n" -">>> sorted(filterfalse(isnan, data))\n" -"[1.1, 2.2, 3.3]" - -#: ../../howto/sorting.rst:305 -msgid "" -"This is needed because the `IEEE-754 standard `_ specifies that, \"Every NaN shall compare unordered with " -"everything, including itself.\"" -msgstr "" - -#: ../../howto/sorting.rst:309 -msgid "Likewise, ``None`` can be stripped from datasets as well:" -msgstr "" - -#: ../../howto/sorting.rst:311 -msgid "" -">>> data = [3.3, None, 1.1, 2.2]\n" -">>> sorted(x for x in data if x is not None)\n" -"[1.1, 2.2, 3.3]" -msgstr "" -">>> data = [3.3, None, 1.1, 2.2]\n" -">>> sorted(x for x in data if x is not None)\n" -"[1.1, 2.2, 3.3]" - -#: ../../howto/sorting.rst:317 -msgid "This is needed because ``None`` is not comparable to other types." -msgstr "" - -#: ../../howto/sorting.rst:319 -msgid "Convert mapping types into sorted item lists before sorting:" -msgstr "" - -#: ../../howto/sorting.rst:321 -msgid "" -">>> data = [{'a': 1}, {'b': 2}]\n" -">>> sorted(data, key=lambda d: sorted(d.items()))\n" -"[{'a': 1}, {'b': 2}]" -msgstr "" -">>> data = [{'a': 1}, {'b': 2}]\n" -">>> sorted(data, key=lambda d: sorted(d.items()))\n" -"[{'a': 1}, {'b': 2}]" - -#: ../../howto/sorting.rst:327 -msgid "" -"This is needed because dict-to-dict comparisons raise a :exc:`TypeError`." -msgstr "" - -#: ../../howto/sorting.rst:330 -msgid "Convert set types into sorted lists before sorting:" -msgstr "" - -#: ../../howto/sorting.rst:332 -msgid "" -">>> data = [{'a', 'b', 'c'}, {'b', 'c', 'd'}]\n" -">>> sorted(map(sorted, data))\n" -"[['a', 'b', 'c'], ['b', 'c', 'd']]" -msgstr "" -">>> data = [{'a', 'b', 'c'}, {'b', 'c', 'd'}]\n" -">>> sorted(map(sorted, data))\n" -"[['a', 'b', 'c'], ['b', 'c', 'd']]" - -#: ../../howto/sorting.rst:338 -msgid "" -"This is needed because the elements contained in set types do not have a " -"deterministic order. For example, ``list({'a', 'b'})`` may produce either " -"``['a', 'b']`` or ``['b', 'a']``." -msgstr "" - -#: ../../howto/sorting.rst:343 -msgid "Odds and Ends" -msgstr "雜項說明" - -#: ../../howto/sorting.rst:345 -msgid "" -"For locale aware sorting, use :func:`locale.strxfrm` for a key function " -"or :func:`locale.strcoll` for a comparison function. This is necessary " -"because \"alphabetical\" sort orderings can vary across cultures even if the " -"underlying alphabet is the same." -msgstr "" -"要處理能理解本地語系 (locale aware) 的排序可以使用 :func:`locale.strxfrm` 當" -"作鍵函式，或 :func:`locale.strcoll` 當作比較函式。這樣做是必要的，因為在不同" -"文化中就算是相同的字母，按「字母順序」排序的結果也各不相同。" - -#: ../../howto/sorting.rst:350 -msgid "" -"The *reverse* parameter still maintains sort stability (so that records with " -"equal keys retain the original order). Interestingly, that effect can be " -"simulated without the parameter by using the builtin :func:`reversed` " -"function twice:" -msgstr "" -"*reverse* 參數依然會維持排序穩定性（即有相同鍵的資料會保持原來順序）。有趣的" -"是，不加這個參數也可以模擬這個效果，只要使用內建的 :func:`reversed` 函式兩" -"次：" - -#: ../../howto/sorting.rst:355 -msgid "" -">>> data = [('red', 1), ('blue', 1), ('red', 2), ('blue', 2)]\n" -">>> standard_way = sorted(data, key=itemgetter(0), reverse=True)\n" -">>> double_reversed = list(reversed(sorted(reversed(data), " -"key=itemgetter(0))))\n" -">>> assert standard_way == double_reversed\n" -">>> standard_way\n" -"[('red', 1), ('red', 2), ('blue', 1), ('blue', 2)]" -msgstr "" -">>> data = [('red', 1), ('blue', 1), ('red', 2), ('blue', 2)]\n" -">>> standard_way = sorted(data, key=itemgetter(0), reverse=True)\n" -">>> double_reversed = list(reversed(sorted(reversed(data), " -"key=itemgetter(0))))\n" -">>> assert standard_way == double_reversed\n" -">>> standard_way\n" -"[('red', 1), ('red', 2), ('blue', 1), ('blue', 2)]" - -#: ../../howto/sorting.rst:364 -msgid "" -"The sort routines use ``<`` when making comparisons between two objects. So, " -"it is easy to add a standard sort order to a class by defining " -"an :meth:`~object.__lt__` method:" -msgstr "" -"排序時會使用 ``<`` 來比較兩個物件，因此要在類別裡面加入排序順序比較規則是簡單" -"的，只要透過定義 :meth:`~object.__lt__` 方法：" - -#: ../../howto/sorting.rst:368 -msgid "" -">>> Student.__lt__ = lambda self, other: self.age < other.age\n" -">>> sorted(student_objects)\n" -"[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]" -msgstr "" -">>> Student.__lt__ = lambda self, other: self.age < other.age\n" -">>> sorted(student_objects)\n" -"[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]" - -#: ../../howto/sorting.rst:374 -msgid "" -"However, note that ``<`` can fall back to using :meth:`~object.__gt__` " -"if :meth:`~object.__lt__` is not implemented (see :func:`object.__lt__` for " -"details on the mechanics). To avoid surprises, :pep:`8` recommends that all " -"six comparison methods be implemented. The :func:`~functools.total_ordering` " -"decorator is provided to make that task easier." -msgstr "" -"然而，請注意，當 :meth:`~object.__lt__` 沒有被實作時，``<`` 可以回退 (fall " -"back) 使用 :meth:`~object.__gt__`\\ （有關技術上的細節資訊請" -"看 :func:`object.__lt__` ）。為了避免意外發生，:pep:`8` 建議所有六種的比較函" -"式都需要被實作。裝飾器 :func:`~functools.total_ordering` 被提供用來讓任務更為" -"簡單。" - -#: ../../howto/sorting.rst:381 -msgid "" -"Key functions need not depend directly on the objects being sorted. A key " -"function can also access external resources. For instance, if the student " -"grades are stored in a dictionary, they can be used to sort a separate list " -"of student names:" -msgstr "" -"鍵函式不需要直接依賴用來排序的物件。鍵函式也可以存取外部資源，例如如果學生成" -"績儲存在字典裡，它可以用來排序一個單獨的學生姓名串列：" - -#: ../../howto/sorting.rst:386 -msgid "" -">>> students = ['dave', 'john', 'jane']\n" -">>> newgrades = {'john': 'F', 'jane':'A', 'dave': 'C'}\n" -">>> sorted(students, key=newgrades.__getitem__)\n" -"['jane', 'dave', 'john']" -msgstr "" -">>> students = ['dave', 'john', 'jane']\n" -">>> newgrades = {'john': 'F', 'jane':'A', 'dave': 'C'}\n" -">>> sorted(students, key=newgrades.__getitem__)\n" -"['jane', 'dave', 'john']" - -#: ../../howto/sorting.rst:394 -msgid "Partial Sorts" -msgstr "部份排序" - -#: ../../howto/sorting.rst:396 -msgid "" -"Some applications require only some of the data to be ordered. The standard " -"library provides several tools that do less work than a full sort:" -msgstr "" -"有些應用程式只需要排序部份的資料。基礎函式庫提供相較做完整排序更為輕鬆的多項" -"工具：" - -#: ../../howto/sorting.rst:399 -msgid "" -":func:`min` and :func:`max` return the smallest and largest values, " -"respectively. These functions make a single pass over the input data and " -"require almost no auxiliary memory." -msgstr "" -":func:`min` 以及 :func:`max` 會分別回傳最小值及最大值。這些函式會將輸入資料進" -"行一次傳遞且幾乎無須輔助記憶體。" - -#: ../../howto/sorting.rst:403 -msgid "" -":func:`heapq.nsmallest` and :func:`heapq.nlargest` return the *n* smallest " -"and largest values, respectively. These functions make a single pass over " -"the data keeping only *n* elements in memory at a time. For values of *n* " -"that are small relative to the number of inputs, these functions make far " -"fewer comparisons than a full sort." -msgstr "" -":func:`heapq.nsmallest` 以及 :func:`heapq.nlargest` 會分別回傳 *n* 個最小值及" -"最大值。這些函式會將資料進行一次傳遞且一次只會保留 *n* 個元素在記憶體中。對於" -"相對於輸入數量較小的 *n* 個值，這些函式進行的比較比完整排序要少得多。" - -#: ../../howto/sorting.rst:409 -msgid "" -":func:`heapq.heappush` and :func:`heapq.heappop` create and maintain a " -"partially sorted arrangement of data that keeps the smallest element at " -"position ``0``. These functions are suitable for implementing priority " -"queues which are commonly used for task scheduling." -msgstr "" -":func:`heapq.heappush` 和 :func:`heapq.heappop` 會建立並維持一個部份排序的資" -"料排列，將最小的元素保持在位置 ``0``。這些函式適合用來實作常用於任務排程的優" -"先佇列。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Ching-Lung Chuang, 2015 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: 2024-12-20 19:16+0800\n" +"Last-Translator: Li-Hung Wang \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" +"X-Generator: Poedit 3.4.2\n" + +#: ../../howto/sorting.rst:4 +msgid "Sorting Techniques" +msgstr "排序技法" + +#: ../../howto/sorting.rst:0 +msgid "Author" +msgstr "作者" + +#: ../../howto/sorting.rst:6 +msgid "Andrew Dalke and Raymond Hettinger" +msgstr "Andrew Dalke 和 Raymond Hettinger" + +#: ../../howto/sorting.rst:9 +msgid "" +"Python lists have a built-in :meth:`list.sort` method that modifies the list " +"in-place. There is also a :func:`sorted` built-in function that builds a " +"new sorted list from an iterable." +msgstr "" +"Python 的串列有一個內建的 :meth:`list.sort` 方法可以原地 (in-place) 排序該串" +"列，也有一個內建的 :func:`sorted` 函式可以排序可疊代物件 (iterable) 並建立一" +"個新的排序好的串列。" + +#: ../../howto/sorting.rst:13 +msgid "" +"In this document, we explore the various techniques for sorting data using " +"Python." +msgstr "在這份文件裡，我們探索使用 Python 排序資料的各種方法。" + +#: ../../howto/sorting.rst:17 +msgid "Sorting Basics" +msgstr "基礎排序" + +#: ../../howto/sorting.rst:19 +msgid "" +"A simple ascending sort is very easy: just call the :func:`sorted` function. " +"It returns a new sorted list:" +msgstr "" +"單純的升冪排序很容易做到：只要呼叫 :func:`sorted` 函式，它會回傳一個新的串" +"列：" + +#: ../../howto/sorting.rst:22 +msgid "" +">>> sorted([5, 2, 3, 1, 4])\n" +"[1, 2, 3, 4, 5]" +msgstr "" +">>> sorted([5, 2, 3, 1, 4])\n" +"[1, 2, 3, 4, 5]" + +#: ../../howto/sorting.rst:27 +msgid "" +"You can also use the :meth:`list.sort` method. It modifies the list in-place " +"(and returns ``None`` to avoid confusion). Usually it's less convenient " +"than :func:`sorted` - but if you don't need the original list, it's slightly " +"more efficient." +msgstr "" +"你也可以使用 :meth:`list.sort` 方法，它會原地排序串列（並回傳 ``None`` 以避免" +"混淆）。它通常會比 :func:`sorted` 來得不方便——但如果你不需要保留原始串列的" +"話，它會稍微有效率一點。" + +#: ../../howto/sorting.rst:32 +msgid "" +">>> a = [5, 2, 3, 1, 4]\n" +">>> a.sort()\n" +">>> a\n" +"[1, 2, 3, 4, 5]" +msgstr "" +">>> a = [5, 2, 3, 1, 4]\n" +">>> a.sort()\n" +">>> a\n" +"[1, 2, 3, 4, 5]" + +#: ../../howto/sorting.rst:39 +msgid "" +"Another difference is that the :meth:`list.sort` method is only defined for " +"lists. In contrast, the :func:`sorted` function accepts any iterable." +msgstr "" +"另一個差異是 :meth:`list.sort` 方法只有定義在串列上，而 :func:`sorted` 函式可" +"以接受任何可疊代物件。" + +#: ../../howto/sorting.rst:42 +msgid "" +">>> sorted({1: 'D', 2: 'B', 3: 'B', 4: 'E', 5: 'A'})\n" +"[1, 2, 3, 4, 5]" +msgstr "" +">>> sorted({1: 'D', 2: 'B', 3: 'B', 4: 'E', 5: 'A'})\n" +"[1, 2, 3, 4, 5]" + +#: ../../howto/sorting.rst:48 +msgid "Key Functions" +msgstr "鍵函式 (key functions)" + +#: ../../howto/sorting.rst:50 +msgid "" +"The :meth:`list.sort` method and the " +"functions :func:`sorted`, :func:`min`, :func:`max`, :func:`heapq.nsmallest`, " +"and :func:`heapq.nlargest` have a *key* parameter to specify a function (or " +"other callable) to be called on each list element prior to making " +"comparisons." +msgstr "" +":meth:`list.sort` 方法和 :func:`sorted`、:func:`min`、:func:`max`、:func:`heapq.nsmallest` 及" +" :func:`heapq.nlargest` 函式都有一個參數 *key* 可以指定一個函式（或其" +"它可呼叫物件 (callable)），其會在每個串列元素做比較前被呼叫。" + +#: ../../howto/sorting.rst:56 +msgid "" +"For example, here's a case-insensitive string comparison " +"using :meth:`str.casefold`:" +msgstr "例如使用 :meth:`str.casefold` 來做不區分大小寫的字串比對：" + +#: ../../howto/sorting.rst:59 +msgid "" +">>> sorted(\"This is a test string from Andrew\".split(), key=str.casefold)\n" +"['a', 'Andrew', 'from', 'is', 'string', 'test', 'This']" +msgstr "" +">>> sorted(\"This is a test string from Andrew\".split(), key=str.casefold)\n" +"['a', 'Andrew', 'from', 'is', 'string', 'test', 'This']" + +#: ../../howto/sorting.rst:64 +msgid "" +"The value of the *key* parameter should be a function (or other callable) " +"that takes a single argument and returns a key to use for sorting purposes. " +"This technique is fast because the key function is called exactly once for " +"each input record." +msgstr "" +"參數 *key* 的值必須是一個函式（或其它可呼叫物件），且這個函式接受單一引數並回" +"傳一個用來排序的鍵。因為對每個輸入來說鍵函式只會被呼叫一次，所以這個做法是快" +"速的。" + +#: ../../howto/sorting.rst:69 +msgid "" +"A common pattern is to sort complex objects using some of the object's " +"indices as keys. For example:" +msgstr "" +"一個常見的模式是在排序複雜物件的時候使用一部分物件的索引值當作鍵，例如：" + +#: ../../howto/sorting.rst:72 +msgid "" +">>> student_tuples = [\n" +"... ('john', 'A', 15),\n" +"... ('jane', 'B', 12),\n" +"... ('dave', 'B', 10),\n" +"... ]\n" +">>> sorted(student_tuples, key=lambda student: student[2]) # sort by age\n" +"[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]" +msgstr "" +">>> student_tuples = [\n" +"... ('john', 'A', 15),\n" +"... ('jane', 'B', 12),\n" +"... ('dave', 'B', 10),\n" +"... ]\n" +">>> sorted(student_tuples, key=lambda student: student[2]) # 依照年齡排序\n" +"[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]" + +#: ../../howto/sorting.rst:82 +msgid "" +"The same technique works for objects with named attributes. For example:" +msgstr "相同的做法也適用在有命名屬性的物件，例如：" + +#: ../../howto/sorting.rst:84 +msgid "" +">>> class Student:\n" +"... def __init__(self, name, grade, age):\n" +"... self.name = name\n" +"... self.grade = grade\n" +"... self.age = age\n" +"... def __repr__(self):\n" +"... return repr((self.name, self.grade, self.age))\n" +"\n" +">>> student_objects = [\n" +"... Student('john', 'A', 15),\n" +"... Student('jane', 'B', 12),\n" +"... Student('dave', 'B', 10),\n" +"... ]\n" +">>> sorted(student_objects, key=lambda student: student.age) # sort by " +"age\n" +"[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]" +msgstr "" +">>> class Student:\n" +"... def __init__(self, name, grade, age):\n" +"... self.name = name\n" +"... self.grade = grade\n" +"... self.age = age\n" +"... def __repr__(self):\n" +"... return repr((self.name, self.grade, self.age))\n" +"\n" +">>> student_objects = [\n" +"... Student('john', 'A', 15),\n" +"... Student('jane', 'B', 12),\n" +"... Student('dave', 'B', 10),\n" +"... ]\n" +">>> sorted(student_objects, key=lambda student: student.age) # 依照年齡排" +"序\n" +"[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]" + +#: ../../howto/sorting.rst:102 +msgid "" +"Objects with named attributes can be made by a regular class as shown above, " +"or they can be instances of :class:`~dataclasses.dataclass` or " +"a :term:`named tuple`." +msgstr "" +"具有命名屬性的物件可以如上方的方式使用一個常規的類別建立，或是他們可以" +"是 :class:`~dataclasses.dataclass` 的實例或是一個 :term:`named tuple`。" + +#: ../../howto/sorting.rst:107 +msgid "Operator Module Functions and Partial Function Evaluation" +msgstr "Operator 模組函式以及部份函式 (partial function) 評估" + +#: ../../howto/sorting.rst:109 +msgid "" +"The :term:`key function` patterns shown above are very common, so Python " +"provides convenience functions to make accessor functions easier and faster. " +"The :mod:`operator` module " +"has :func:`~operator.itemgetter`, :func:`~operator.attrgetter`, and " +"a :func:`~operator.methodcaller` function." +msgstr "" +"上述的\\ :term:`鍵函式 `\\ 模式非常常見，所以 Python 提供了方便" +"的函式讓物件存取更簡單且快速。:mod:`operator` 模組裡" +"有 :func:`~operator.itemgetter`、:func:`~operator.attrgetter` " +"及 :func:`~operator.methodcaller` 函式可以使用。" + +#: ../../howto/sorting.rst:114 +msgid "Using those functions, the above examples become simpler and faster:" +msgstr "使用這些函式讓上面的範例變得更簡單且快速：" + +#: ../../howto/sorting.rst:116 +msgid "" +">>> from operator import itemgetter, attrgetter\n" +"\n" +">>> sorted(student_tuples, key=itemgetter(2))\n" +"[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]\n" +"\n" +">>> sorted(student_objects, key=attrgetter('age'))\n" +"[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]" +msgstr "" +">>> from operator import itemgetter, attrgetter\n" +"\n" +">>> sorted(student_tuples, key=itemgetter(2))\n" +"[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]\n" +"\n" +">>> sorted(student_objects, key=attrgetter('age'))\n" +"[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]" + +#: ../../howto/sorting.rst:126 +msgid "" +"The operator module functions allow multiple levels of sorting. For example, " +"to sort by *grade* then by *age*:" +msgstr "" +"operator 模組的函式允許多層的排序，例如先用 *grade* 排序再用 *age* 排序：" + +#: ../../howto/sorting.rst:129 +msgid "" +">>> sorted(student_tuples, key=itemgetter(1,2))\n" +"[('john', 'A', 15), ('dave', 'B', 10), ('jane', 'B', 12)]\n" +"\n" +">>> sorted(student_objects, key=attrgetter('grade', 'age'))\n" +"[('john', 'A', 15), ('dave', 'B', 10), ('jane', 'B', 12)]" +msgstr "" +">>> sorted(student_tuples, key=itemgetter(1,2))\n" +"[('john', 'A', 15), ('dave', 'B', 10), ('jane', 'B', 12)]\n" +"\n" +">>> sorted(student_objects, key=attrgetter('grade', 'age'))\n" +"[('john', 'A', 15), ('dave', 'B', 10), ('jane', 'B', 12)]" + +#: ../../howto/sorting.rst:137 +msgid "" +"The :mod:`functools` module provides another helpful tool for making key-" +"functions. The :func:`~functools.partial` function can reduce the `arity " +"`_ of a multi-argument function making " +"it suitable for use as a key-function." +msgstr "" +"模組 :mod:`functools` 提供了另一個製作鍵函式的好用工" +"具。:func:`~functools.partial` 函式可以減少多引數函式的\\ `引數數目 `_，使其更適合作為鍵函式使用。" + +#: ../../howto/sorting.rst:142 +msgid "" +">>> from functools import partial\n" +">>> from unicodedata import normalize\n" +"\n" +">>> names = 'Zoë Åbjørn Núñez Élana Zeke Abe Nubia Eloise'.split()\n" +"\n" +">>> sorted(names, key=partial(normalize, 'NFD'))\n" +"['Abe', 'Åbjørn', 'Eloise', 'Élana', 'Nubia', 'Núñez', 'Zeke', 'Zoë']\n" +"\n" +">>> sorted(names, key=partial(normalize, 'NFC'))\n" +"['Abe', 'Eloise', 'Nubia', 'Núñez', 'Zeke', 'Zoë', 'Åbjørn', 'Élana']" +msgstr "" +">>> from functools import partial\n" +">>> from unicodedata import normalize\n" +"\n" +">>> names = 'Zoë Åbjørn Núñez Élana Zeke Abe Nubia Eloise'.split()\n" +"\n" +">>> sorted(names, key=partial(normalize, 'NFD'))\n" +"['Abe', 'Åbjørn', 'Eloise', 'Élana', 'Nubia', 'Núñez', 'Zeke', 'Zoë']\n" +"\n" +">>> sorted(names, key=partial(normalize, 'NFC'))\n" +"['Abe', 'Eloise', 'Nubia', 'Núñez', 'Zeke', 'Zoë', 'Åbjørn', 'Élana']" + +#: ../../howto/sorting.rst:156 +msgid "Ascending and Descending" +msgstr "升冪與降冪" + +#: ../../howto/sorting.rst:158 +msgid "" +"Both :meth:`list.sort` and :func:`sorted` accept a *reverse* parameter with " +"a boolean value. This is used to flag descending sorts. For example, to get " +"the student data in reverse *age* order:" +msgstr "" +":meth:`list.sort` 和 :func:`sorted` 都有一個 boolean 參數 *reverse* 用來表示" +"是否要降冪排序。例如將學生資料依據 *age* 做降冪排序：" + +#: ../../howto/sorting.rst:162 +msgid "" +">>> sorted(student_tuples, key=itemgetter(2), reverse=True)\n" +"[('john', 'A', 15), ('jane', 'B', 12), ('dave', 'B', 10)]\n" +"\n" +">>> sorted(student_objects, key=attrgetter('age'), reverse=True)\n" +"[('john', 'A', 15), ('jane', 'B', 12), ('dave', 'B', 10)]" +msgstr "" +">>> sorted(student_tuples, key=itemgetter(2), reverse=True)\n" +"[('john', 'A', 15), ('jane', 'B', 12), ('dave', 'B', 10)]\n" +"\n" +">>> sorted(student_objects, key=attrgetter('age'), reverse=True)\n" +"[('john', 'A', 15), ('jane', 'B', 12), ('dave', 'B', 10)]" + +#: ../../howto/sorting.rst:171 +msgid "Sort Stability and Complex Sorts" +msgstr "排序穩定性與複合排序" + +#: ../../howto/sorting.rst:173 +msgid "" +"Sorts are guaranteed to be `stable `_\\. That means that when multiple records have " +"the same key, their original order is preserved." +msgstr "" +"排序保證是\\ `穩定的 `_，意思是當有多筆資料有相同的鍵，它們會維持原來" +"的順序。" + +#: ../../howto/sorting.rst:177 +msgid "" +">>> data = [('red', 1), ('blue', 1), ('red', 2), ('blue', 2)]\n" +">>> sorted(data, key=itemgetter(0))\n" +"[('blue', 1), ('blue', 2), ('red', 1), ('red', 2)]" +msgstr "" +">>> data = [('red', 1), ('blue', 1), ('red', 2), ('blue', 2)]\n" +">>> sorted(data, key=itemgetter(0))\n" +"[('blue', 1), ('blue', 2), ('red', 1), ('red', 2)]" + +#: ../../howto/sorting.rst:183 +msgid "" +"Notice how the two records for *blue* retain their original order so that " +"``('blue', 1)`` is guaranteed to precede ``('blue', 2)``." +msgstr "" +"可以注意到有兩筆資料的鍵都是 *blue*，它們會維持本來的順序，即 ``('blue', " +"1)`` 保證在 ``('blue', 2)`` 前面。" + +#: ../../howto/sorting.rst:186 +msgid "" +"This wonderful property lets you build complex sorts in a series of sorting " +"steps. For example, to sort the student data by descending *grade* and then " +"ascending *age*, do the *age* sort first and then sort again using *grade*:" +msgstr "" +"這個美妙的特性讓你可以用一連串的排序來作出複合排序。例如對學生資料用 *grade* " +"做降冪排序再用 *age* 做升冪排序，你可以先用 *age* 排序一遍再用 *grade* 排序一" +"遍：" + +#: ../../howto/sorting.rst:190 +msgid "" +">>> s = sorted(student_objects, key=attrgetter('age')) # sort on " +"secondary key\n" +">>> sorted(s, key=attrgetter('grade'), reverse=True) # now sort on " +"primary key, descending\n" +"[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]" +msgstr "" +">>> s = sorted(student_objects, key=attrgetter('age')) # 依照次要鍵排序\n" +">>> sorted(s, key=attrgetter('grade'), reverse=True) # 現在依照主要鍵降" +"冪排序\n" +"[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]" + +#: ../../howto/sorting.rst:196 +msgid "" +"This can be abstracted out into a wrapper function that can take a list and " +"tuples of field and order to sort them on multiple passes." +msgstr "" +"這可以抽出一個包裝函式 (wrapper function)，接受一個串列及多個欄位及升降冪的元" +"組為引數，來對這個串列排序多遍。" + +#: ../../howto/sorting.rst:199 +msgid "" +">>> def multisort(xs, specs):\n" +"... for key, reverse in reversed(specs):\n" +"... xs.sort(key=attrgetter(key), reverse=reverse)\n" +"... return xs\n" +"\n" +">>> multisort(list(student_objects), (('grade', True), ('age', False)))\n" +"[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]" +msgstr "" +">>> def multisort(xs, specs):\n" +"... for key, reverse in reversed(specs):\n" +"... xs.sort(key=attrgetter(key), reverse=reverse)\n" +"... return xs\n" +"\n" +">>> multisort(list(student_objects), (('grade', True), ('age', False)))\n" +"[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]" + +#: ../../howto/sorting.rst:209 +msgid "" +"The `Timsort `_ algorithm used in " +"Python does multiple sorts efficiently because it can take advantage of any " +"ordering already present in a dataset." +msgstr "" +"Python 裡使用的 `Timsort `_ 演算法，因" +"為能利用資料集裡已經有的順序，可以有效率地做多次排序。" + +#: ../../howto/sorting.rst:214 +msgid "Decorate-Sort-Undecorate" +msgstr "裝飾-排序-移除裝飾 (decorate-sort-undecorate)" + +#: ../../howto/sorting.rst:216 +msgid "This idiom is called Decorate-Sort-Undecorate after its three steps:" +msgstr "這個用語的來源是因為它做了以下三件事情：" + +#: ../../howto/sorting.rst:218 +msgid "" +"First, the initial list is decorated with new values that control the sort " +"order." +msgstr "首先，原始串列會裝飾 (decorated) 上新的值用來控制排序的順序。" + +#: ../../howto/sorting.rst:220 +msgid "Second, the decorated list is sorted." +msgstr "接下來，排序裝飾過的串列。" + +#: ../../howto/sorting.rst:222 +msgid "" +"Finally, the decorations are removed, creating a list that contains only the " +"initial values in the new order." +msgstr "最後，裝飾會被移除，並以新的順序產生一個只包含原始值的串列。" + +#: ../../howto/sorting.rst:225 +msgid "" +"For example, to sort the student data by *grade* using the DSU approach:" +msgstr "例如用上面說的方式來以 *grade* 排序學生資料：" + +#: ../../howto/sorting.rst:227 +msgid "" +">>> decorated = [(student.grade, i, student) for i, student in " +"enumerate(student_objects)]\n" +">>> decorated.sort()\n" +">>> [student for grade, i, student in decorated] # undecorate\n" +"[('john', 'A', 15), ('jane', 'B', 12), ('dave', 'B', 10)]" +msgstr "" +">>> decorated = [(student.grade, i, student) for i, student in " +"enumerate(student_objects)]\n" +">>> decorated.sort()\n" +">>> [student for grade, i, student in decorated] # 移除裝飾\n" +"[('john', 'A', 15), ('jane', 'B', 12), ('dave', 'B', 10)]" + +#: ../../howto/sorting.rst:234 +msgid "" +"This idiom works because tuples are compared lexicographically; the first " +"items are compared; if they are the same then the second items are compared, " +"and so on." +msgstr "" +"這個方式會有效是因為元組是依照字典順序 (lexicographically) 來比較，先比較第一" +"個項目，如果一樣再比較第二個項目，並依此類推。" + +#: ../../howto/sorting.rst:238 +msgid "" +"It is not strictly necessary in all cases to include the index *i* in the " +"decorated list, but including it gives two benefits:" +msgstr "" +"在所有情況下都把索引 *i* 加入已裝飾的串列並不是絕對需要的，但這樣做會有兩個好" +"處：" + +#: ../../howto/sorting.rst:241 +msgid "" +"The sort is stable -- if two items have the same key, their order will be " +"preserved in the sorted list." +msgstr "" +"排序會是穩定的 -- 如果兩個項目有相同的鍵，它們在排序好的串列中會保持原來的順" +"序。" + +#: ../../howto/sorting.rst:244 +msgid "" +"The original items do not have to be comparable because the ordering of the " +"decorated tuples will be determined by at most the first two items. So for " +"example the original list could contain complex numbers which cannot be " +"sorted directly." +msgstr "" +"原始項目不需要是可以比較的，因為最多只會用到前兩個項目就能決定裝飾過的元組的" +"順序。例如原始串列可以包含不能直接用來排序的複數。" + +#: ../../howto/sorting.rst:249 +msgid "" +"Another name for this idiom is `Schwartzian transform `_\\, after Randal L. Schwartz, " +"who popularized it among Perl programmers." +msgstr "" +"這個用語的另一個名字是 `Schwartzian transform `_，是由於 Randal L. Schwartz 讓這個方法在 Perl 程式設" +"計師間普及。" + +#: ../../howto/sorting.rst:253 +msgid "" +"Now that Python sorting provides key-functions, this technique is not often " +"needed." +msgstr "而因為 Python 的排序提供了鍵函式，已經不太需要用到這個方法了。" + +#: ../../howto/sorting.rst:256 +msgid "Comparison Functions" +msgstr "比較函式 (comparison functions)" + +#: ../../howto/sorting.rst:258 +msgid "" +"Unlike key functions that return an absolute value for sorting, a comparison " +"function computes the relative ordering for two inputs." +msgstr "不像鍵函式回傳一個用來排序的值，比較函式計算兩個輸入間的相對順序。" + +#: ../../howto/sorting.rst:261 +msgid "" +"For example, a `balance scale `_ compares two samples giving a " +"relative ordering: lighter, equal, or heavier. Likewise, a comparison " +"function such as ``cmp(a, b)`` will return a negative value for less-than, " +"zero if the inputs are equal, or a positive value for greater-than." +msgstr "" +"例如\\ `天秤 `_\\ 比較兩邊樣本並給出相對的順序：較輕、相同或較" +"重。同樣地，像是 ``cmp(a, b)`` 這樣的比較函式會回傳負數代表小於、0 代表輸入相" +"同或正數代表大於。" + +#: ../../howto/sorting.rst:268 +msgid "" +"It is common to encounter comparison functions when translating algorithms " +"from other languages. Also, some libraries provide comparison functions as " +"part of their API. For example, :func:`locale.strcoll` is a comparison " +"function." +msgstr "" +"當從其它語言翻譯演算法的時候常看到比較函式。有些函式庫也會提供比較函式作為其 " +"API 的一部份，例如 :func:`locale.strcoll` 就是一個比較函式。" + +#: ../../howto/sorting.rst:272 +msgid "" +"To accommodate those situations, Python " +"provides :class:`functools.cmp_to_key` to wrap the comparison function to " +"make it usable as a key function::" +msgstr "" +"為了滿足這些情境，Python 提供 :class:`functools.cmp_to_key` 來包裝比較函式，" +"讓其可以當作鍵函式來使用： ::" + +#: ../../howto/sorting.rst:276 +msgid "sorted(words, key=cmp_to_key(strcoll)) # locale-aware sort order" +msgstr "sorted(words, key=cmp_to_key(strcoll)) # 理解語系的排序順序" + +#: ../../howto/sorting.rst:279 +msgid "Strategies For Unorderable Types and Values" +msgstr "" + +#: ../../howto/sorting.rst:281 +msgid "" +"A number of type and value issues can arise when sorting. Here are some " +"strategies that can help:" +msgstr "" + +#: ../../howto/sorting.rst:284 +msgid "Convert non-comparable input types to strings prior to sorting:" +msgstr "" + +#: ../../howto/sorting.rst:286 +msgid "" +">>> data = ['twelve', '11', 10]\n" +">>> sorted(map(str, data))\n" +"['10', '11', 'twelve']" +msgstr "" +">>> data = ['twelve', '11', 10]\n" +">>> sorted(map(str, data))\n" +"['10', '11', 'twelve']" + +#: ../../howto/sorting.rst:292 +msgid "" +"This is needed because most cross-type comparisons raise a :exc:`TypeError`." +msgstr "" + +#: ../../howto/sorting.rst:295 +msgid "Remove special values prior to sorting:" +msgstr "" + +#: ../../howto/sorting.rst:297 +msgid "" +">>> from math import isnan\n" +">>> from itertools import filterfalse\n" +">>> data = [3.3, float('nan'), 1.1, 2.2]\n" +">>> sorted(filterfalse(isnan, data))\n" +"[1.1, 2.2, 3.3]" +msgstr "" +">>> from math import isnan\n" +">>> from itertools import filterfalse\n" +">>> data = [3.3, float('nan'), 1.1, 2.2]\n" +">>> sorted(filterfalse(isnan, data))\n" +"[1.1, 2.2, 3.3]" + +#: ../../howto/sorting.rst:305 +msgid "" +"This is needed because the `IEEE-754 standard `_ specifies that, \"Every NaN shall compare unordered with " +"everything, including itself.\"" +msgstr "" + +#: ../../howto/sorting.rst:309 +msgid "Likewise, ``None`` can be stripped from datasets as well:" +msgstr "" + +#: ../../howto/sorting.rst:311 +msgid "" +">>> data = [3.3, None, 1.1, 2.2]\n" +">>> sorted(x for x in data if x is not None)\n" +"[1.1, 2.2, 3.3]" +msgstr "" +">>> data = [3.3, None, 1.1, 2.2]\n" +">>> sorted(x for x in data if x is not None)\n" +"[1.1, 2.2, 3.3]" + +#: ../../howto/sorting.rst:317 +msgid "This is needed because ``None`` is not comparable to other types." +msgstr "" + +#: ../../howto/sorting.rst:319 +msgid "Convert mapping types into sorted item lists before sorting:" +msgstr "" + +#: ../../howto/sorting.rst:321 +msgid "" +">>> data = [{'a': 1}, {'b': 2}]\n" +">>> sorted(data, key=lambda d: sorted(d.items()))\n" +"[{'a': 1}, {'b': 2}]" +msgstr "" +">>> data = [{'a': 1}, {'b': 2}]\n" +">>> sorted(data, key=lambda d: sorted(d.items()))\n" +"[{'a': 1}, {'b': 2}]" + +#: ../../howto/sorting.rst:327 +msgid "" +"This is needed because dict-to-dict comparisons raise a :exc:`TypeError`." +msgstr "" + +#: ../../howto/sorting.rst:330 +msgid "Convert set types into sorted lists before sorting:" +msgstr "" + +#: ../../howto/sorting.rst:332 +msgid "" +">>> data = [{'a', 'b', 'c'}, {'b', 'c', 'd'}]\n" +">>> sorted(map(sorted, data))\n" +"[['a', 'b', 'c'], ['b', 'c', 'd']]" +msgstr "" +">>> data = [{'a', 'b', 'c'}, {'b', 'c', 'd'}]\n" +">>> sorted(map(sorted, data))\n" +"[['a', 'b', 'c'], ['b', 'c', 'd']]" + +#: ../../howto/sorting.rst:338 +msgid "" +"This is needed because the elements contained in set types do not have a " +"deterministic order. For example, ``list({'a', 'b'})`` may produce either " +"``['a', 'b']`` or ``['b', 'a']``." +msgstr "" + +#: ../../howto/sorting.rst:343 +msgid "Odds and Ends" +msgstr "雜項說明" + +#: ../../howto/sorting.rst:345 +msgid "" +"For locale aware sorting, use :func:`locale.strxfrm` for a key function " +"or :func:`locale.strcoll` for a comparison function. This is necessary " +"because \"alphabetical\" sort orderings can vary across cultures even if the " +"underlying alphabet is the same." +msgstr "" +"要處理能理解本地語系 (locale aware) 的排序可以使用 :func:`locale.strxfrm` 當" +"作鍵函式，或 :func:`locale.strcoll` 當作比較函式。這樣做是必要的，因為在不同" +"文化中就算是相同的字母，按「字母順序」排序的結果也各不相同。" + +#: ../../howto/sorting.rst:350 +msgid "" +"The *reverse* parameter still maintains sort stability (so that records with " +"equal keys retain the original order). Interestingly, that effect can be " +"simulated without the parameter by using the builtin :func:`reversed` " +"function twice:" +msgstr "" +"*reverse* 參數依然會維持排序穩定性（即有相同鍵的資料會保持原來順序）。有趣的" +"是，不加這個參數也可以模擬這個效果，只要使用內建的 :func:`reversed` 函式兩" +"次：" + +#: ../../howto/sorting.rst:355 +msgid "" +">>> data = [('red', 1), ('blue', 1), ('red', 2), ('blue', 2)]\n" +">>> standard_way = sorted(data, key=itemgetter(0), reverse=True)\n" +">>> double_reversed = list(reversed(sorted(reversed(data), " +"key=itemgetter(0))))\n" +">>> assert standard_way == double_reversed\n" +">>> standard_way\n" +"[('red', 1), ('red', 2), ('blue', 1), ('blue', 2)]" +msgstr "" +">>> data = [('red', 1), ('blue', 1), ('red', 2), ('blue', 2)]\n" +">>> standard_way = sorted(data, key=itemgetter(0), reverse=True)\n" +">>> double_reversed = list(reversed(sorted(reversed(data), " +"key=itemgetter(0))))\n" +">>> assert standard_way == double_reversed\n" +">>> standard_way\n" +"[('red', 1), ('red', 2), ('blue', 1), ('blue', 2)]" + +#: ../../howto/sorting.rst:364 +msgid "" +"The sort routines use ``<`` when making comparisons between two objects. So, " +"it is easy to add a standard sort order to a class by defining " +"an :meth:`~object.__lt__` method:" +msgstr "" +"排序時會使用 ``<`` 來比較兩個物件，因此要在類別裡面加入排序順序比較規則是簡單" +"的，只要透過定義 :meth:`~object.__lt__` 方法：" + +#: ../../howto/sorting.rst:368 +msgid "" +">>> Student.__lt__ = lambda self, other: self.age < other.age\n" +">>> sorted(student_objects)\n" +"[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]" +msgstr "" +">>> Student.__lt__ = lambda self, other: self.age < other.age\n" +">>> sorted(student_objects)\n" +"[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]" + +#: ../../howto/sorting.rst:374 +msgid "" +"However, note that ``<`` can fall back to using :meth:`~object.__gt__` " +"if :meth:`~object.__lt__` is not implemented (see :func:`object.__lt__` for " +"details on the mechanics). To avoid surprises, :pep:`8` recommends that all " +"six comparison methods be implemented. The :func:`~functools.total_ordering` " +"decorator is provided to make that task easier." +msgstr "" +"然而，請注意，當 :meth:`~object.__lt__` 沒有被實作時，``<`` 可以回退 (fall " +"back) 使用 :meth:`~object.__gt__`\\ （有關技術上的細節資訊請" +"看 :func:`object.__lt__` ）。為了避免意外發生，:pep:`8` 建議所有六種的比較函" +"式都需要被實作。裝飾器 :func:`~functools.total_ordering` 被提供用來讓任務更為" +"簡單。" + +#: ../../howto/sorting.rst:381 +msgid "" +"Key functions need not depend directly on the objects being sorted. A key " +"function can also access external resources. For instance, if the student " +"grades are stored in a dictionary, they can be used to sort a separate list " +"of student names:" +msgstr "" +"鍵函式不需要直接依賴用來排序的物件。鍵函式也可以存取外部資源，例如如果學生成" +"績儲存在字典裡，它可以用來排序一個單獨的學生姓名串列：" + +#: ../../howto/sorting.rst:386 +msgid "" +">>> students = ['dave', 'john', 'jane']\n" +">>> newgrades = {'john': 'F', 'jane':'A', 'dave': 'C'}\n" +">>> sorted(students, key=newgrades.__getitem__)\n" +"['jane', 'dave', 'john']" +msgstr "" +">>> students = ['dave', 'john', 'jane']\n" +">>> newgrades = {'john': 'F', 'jane':'A', 'dave': 'C'}\n" +">>> sorted(students, key=newgrades.__getitem__)\n" +"['jane', 'dave', 'john']" + +#: ../../howto/sorting.rst:394 +msgid "Partial Sorts" +msgstr "部份排序" + +#: ../../howto/sorting.rst:396 +msgid "" +"Some applications require only some of the data to be ordered. The standard " +"library provides several tools that do less work than a full sort:" +msgstr "" +"有些應用程式只需要排序部份的資料。基礎函式庫提供相較做完整排序更為輕鬆的多項" +"工具：" + +#: ../../howto/sorting.rst:399 +msgid "" +":func:`min` and :func:`max` return the smallest and largest values, " +"respectively. These functions make a single pass over the input data and " +"require almost no auxiliary memory." +msgstr "" +":func:`min` 以及 :func:`max` 會分別回傳最小值及最大值。這些函式會將輸入資料進" +"行一次傳遞且幾乎無須輔助記憶體。" + +#: ../../howto/sorting.rst:403 +msgid "" +":func:`heapq.nsmallest` and :func:`heapq.nlargest` return the *n* smallest " +"and largest values, respectively. These functions make a single pass over " +"the data keeping only *n* elements in memory at a time. For values of *n* " +"that are small relative to the number of inputs, these functions make far " +"fewer comparisons than a full sort." +msgstr "" +":func:`heapq.nsmallest` 以及 :func:`heapq.nlargest` 會分別回傳 *n* 個最小值及" +"最大值。這些函式會將資料進行一次傳遞且一次只會保留 *n* 個元素在記憶體中。對於" +"相對於輸入數量較小的 *n* 個值，這些函式進行的比較比完整排序要少得多。" + +#: ../../howto/sorting.rst:409 +msgid "" +":func:`heapq.heappush` and :func:`heapq.heappop` create and maintain a " +"partially sorted arrangement of data that keeps the smallest element at " +"position ``0``. These functions are suitable for implementing priority " +"queues which are commonly used for task scheduling." +msgstr "" +":func:`heapq.heappush` 和 :func:`heapq.heappop` 會建立並維持一個部份排序的資" +"料排列，將最小的元素保持在位置 ``0``。這些函式適合用來實作常用於任務排程的優" +"先佇列。" diff --git a/howto/timerfd.po b/howto/timerfd.po index cc60b1f951..f9bb1afdb4 100644 --- a/howto/timerfd.po +++ b/howto/timerfd.po @@ -1,488 +1,488 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# Translators: -# GitHub Copilot, 2025 -# -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-09-23 07:52+0800\n" -"PO-Revision-Date: 2024-12-19 10:00+0000\n" -"Last-Translator: GitHub Copilot\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" - -#: ../../howto/timerfd.rst:5 -msgid "timer file descriptor HOWTO" -msgstr "計時器檔案描述器 (timerfd) 指南" - -#: ../../howto/timerfd.rst:0 -msgid "Release" -msgstr "發佈版本" - -#: ../../howto/timerfd.rst:7 -msgid "1.13" -msgstr "1.13" - -#: ../../howto/timerfd.rst:9 -msgid "" -"This HOWTO discusses Python's support for the linux timer file descriptor." -msgstr "此篇指南探討 Python 對 Linux 計時器檔案描述器的支援。" - -#: ../../howto/timerfd.rst:13 -msgid "Examples" -msgstr "範例" - -#: ../../howto/timerfd.rst:15 -msgid "" -"The following example shows how to use a timer file descriptor to execute a " -"function twice a second:" -msgstr "以下範例顯示如何使用計時器檔案描述器來每秒執行函式兩次：" - -#: ../../howto/timerfd.rst:18 -msgid "" -"# Practical scripts should use really use a non-blocking timer,\n" -"# we use a blocking timer here for simplicity.\n" -"import os, time\n" -"\n" -"# Create the timer file descriptor\n" -"fd = os.timerfd_create(time.CLOCK_REALTIME)\n" -"\n" -"# Start the timer in 1 second, with an interval of half a second\n" -"os.timerfd_settime(fd, initial=1, interval=0.5)\n" -"\n" -"try:\n" -" # Process timer events four times.\n" -" for _ in range(4):\n" -" # read() will block until the timer expires\n" -" _ = os.read(fd, 8)\n" -" print(\"Timer expired\")\n" -"finally:\n" -" # Remember to close the timer file descriptor!\n" -" os.close(fd)" -msgstr "" -"# 實際腳本應該使用非阻塞計時器，\n" -"# 在這裡為了簡單起見我們使用阻塞計時器。\n" -"import os, time\n" -"\n" -"# 建立計時器檔案描述器\n" -"fd = os.timerfd_create(time.CLOCK_REALTIME)\n" -"\n" -"# 在 1 秒後開始計時器，間隔為半秒\n" -"os.timerfd_settime(fd, initial=1, interval=0.5)\n" -"\n" -"try:\n" -" # 處理計時器事件四次。\n" -" for _ in range(4):\n" -" # read() 會阻塞直到計時器到期\n" -" _ = os.read(fd, 8)\n" -" print(\"Timer expired\")\n" -"finally:\n" -" # 記得關閉計時器檔案描述器！\n" -" os.close(fd)" - -#: ../../howto/timerfd.rst:40 -msgid "" -"To avoid the precision loss caused by the :class:`float` type, timer file " -"descriptors allow specifying initial expiration and interval in integer " -"nanoseconds with ``_ns`` variants of the functions." -msgstr "" -"為了避免由 :class:`float` 型別造成的精度損失，計時器檔案描述器允許使用函式的 " -"``_ns`` 變體以整數奈秒為單位指定初始到期時間和間隔。" - -#: ../../howto/timerfd.rst:44 -msgid "" -"This example shows how :func:`~select.epoll` can be used with timer file " -"descriptors to wait until the file descriptor is ready for reading:" -msgstr "" -"此範例展示如何將 :func:`~select.epoll` 與計時器檔案描述器一起使用，" -"用於等待檔案描述器直到它準備好讀取：" - -#: ../../howto/timerfd.rst:47 -msgid "" -"import os, time, select, socket, sys\n" -"\n" -"# Create an epoll object\n" -"ep = select.epoll()\n" -"\n" -"# In this example, use loopback address to send \"stop\" command to the " -"server.\n" -"#\n" -"# $ telnet 127.0.0.1 1234\n" -"# Trying 127.0.0.1...\n" -"# Connected to 127.0.0.1.\n" -"# Escape character is '^]'.\n" -"# stop\n" -"# Connection closed by foreign host.\n" -"#\n" -"sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)\n" -"sock.bind((\"127.0.0.1\", 1234))\n" -"sock.setblocking(False)\n" -"sock.listen(1)\n" -"ep.register(sock, select.EPOLLIN)\n" -"\n" -"# Create timer file descriptors in non-blocking mode.\n" -"num = 3\n" -"fds = []\n" -"for _ in range(num):\n" -" fd = os.timerfd_create(time.CLOCK_REALTIME, flags=os.TFD_NONBLOCK)\n" -" fds.append(fd)\n" -" # Register the timer file descriptor for read events\n" -" ep.register(fd, select.EPOLLIN)\n" -"\n" -"# Start the timer with os.timerfd_settime_ns() in nanoseconds.\n" -"# Timer 1 fires every 0.25 seconds; timer 2 every 0.5 seconds; etc\n" -"for i, fd in enumerate(fds, start=1):\n" -" one_sec_in_nsec = 10**9\n" -" i = i * one_sec_in_nsec\n" -" os.timerfd_settime_ns(fd, initial=i//4, interval=i//4)\n" -"\n" -"timeout = 3\n" -"try:\n" -" conn = None\n" -" is_active = True\n" -" while is_active:\n" -" # Wait for the timer to expire for 3 seconds.\n" -" # epoll.poll() returns a list of (fd, event) pairs.\n" -" # fd is a file descriptor.\n" -" # sock and conn[=returned value of socket.accept()] are socket " -"objects, not file descriptors.\n" -" # So use sock.fileno() and conn.fileno() to get the file " -"descriptors.\n" -" events = ep.poll(timeout)\n" -"\n" -" # If more than one timer file descriptors are ready for reading at " -"once,\n" -" # epoll.poll() returns a list of (fd, event) pairs.\n" -" #\n" -" # In this example settings,\n" -" # 1st timer fires every 0.25 seconds in 0.25 seconds. (0.25, 0.5, " -"0.75, 1.0, ...)\n" -" # 2nd timer every 0.5 seconds in 0.5 seconds. (0.5, 1.0, 1.5, " -"2.0, ...)\n" -" # 3rd timer every 0.75 seconds in 0.75 seconds. (0.75, 1.5, 2.25, " -"3.0, ...)\n" -" #\n" -" # In 0.25 seconds, only 1st timer fires.\n" -" # In 0.5 seconds, 1st timer and 2nd timer fires at once.\n" -" # In 0.75 seconds, 1st timer and 3rd timer fires at once.\n" -" # In 1.5 seconds, 1st timer, 2nd timer and 3rd timer fires at " -"once.\n" -" #\n" -" # If a timer file descriptor is signaled more than once since\n" -" # the last os.read() call, os.read() returns the number of signaled\n" -" # as host order of class bytes.\n" -" print(f\"Signaled events={events}\")\n" -" for fd, event in events:\n" -" if event & select.EPOLLIN:\n" -" if fd == sock.fileno():\n" -" # Check if there is a connection request.\n" -" print(f\"Accepting connection {fd}\")\n" -" conn, addr = sock.accept()\n" -" conn.setblocking(False)\n" -" print(f\"Accepted connection {conn} from {addr}\")\n" -" ep.register(conn, select.EPOLLIN)\n" -" elif conn and fd == conn.fileno():\n" -" # Check if there is data to read.\n" -" print(f\"Reading data {fd}\")\n" -" data = conn.recv(1024)\n" -" if data:\n" -" # You should catch UnicodeDecodeError exception for " -"safety.\n" -" cmd = data.decode()\n" -" if cmd.startswith(\"stop\"):\n" -" print(f\"Stopping server\")\n" -" is_active = False\n" -" else:\n" -" print(f\"Unknown command: {cmd}\")\n" -" else:\n" -" # No more data, close connection\n" -" print(f\"Closing connection {fd}\")\n" -" ep.unregister(conn)\n" -" conn.close()\n" -" conn = None\n" -" elif fd in fds:\n" -" print(f\"Reading timer {fd}\")\n" -" count = int.from_bytes(os.read(fd, 8), byteorder=sys." -"byteorder)\n" -" print(f\"Timer {fds.index(fd) + 1} expired {count} " -"times\")\n" -" else:\n" -" print(f\"Unknown file descriptor {fd}\")\n" -"finally:\n" -" for fd in fds:\n" -" ep.unregister(fd)\n" -" os.close(fd)\n" -" ep.close()" -msgstr "" -"import os, time, select, socket, sys\n" -"\n" -"# 建立 epoll 物件\n" -"ep = select.epoll()\n" -"\n" -"# 在此範例中，使用回送位址 (loopback address) 向伺服器發送 \"stop\" 命令。\n" -"#\n" -"# $ telnet 127.0.0.1 1234\n" -"# Trying 127.0.0.1...\n" -"# Connected to 127.0.0.1.\n" -"# Escape character is '^]'.\n" -"# stop\n" -"# Connection closed by foreign host.\n" -"#\n" -"sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)\n" -"sock.bind((\"127.0.0.1\", 1234))\n" -"sock.setblocking(False)\n" -"sock.listen(1)\n" -"ep.register(sock, select.EPOLLIN)\n" -"\n" -"# 以非阻塞模式建立計時器檔案描述器。\n" -"num = 3\n" -"fds = []\n" -"for _ in range(num):\n" -" fd = os.timerfd_create(time.CLOCK_REALTIME, flags=os.TFD_NONBLOCK)\n" -" fds.append(fd)\n" -" # 為讀取事件註冊計時器檔案描述器\n" -" ep.register(fd, select.EPOLLIN)\n" -"\n" -"# 使用 os.timerfd_settime_ns() 以奈秒為單位啟動計時器。\n" -"# 計時器 1 每 0.25 秒觸發一次；計時器 2 每 0.5 秒觸發一次；以此類推\n" -"for i, fd in enumerate(fds, start=1):\n" -" one_sec_in_nsec = 10**9\n" -" i = i * one_sec_in_nsec\n" -" os.timerfd_settime_ns(fd, initial=i//4, interval=i//4)\n" -"\n" -"timeout = 3\n" -"try:\n" -" conn = None\n" -" is_active = True\n" -" while is_active:\n" -" # 等待計時器在 3 秒內到期。\n" -" # epoll.poll() 回傳一個 (fd, event) 配對的串列。\n" -" # fd 是檔案描述器。\n" -" # sock 和 conn[=socket.accept() 的回傳值] 是 socket 物件，不是檔案描述器。\n" -" # 所以要使用 sock.fileno() 和 conn.fileno() 來取得檔案描述器。\n" -" events = ep.poll(timeout)\n" -"\n" -" # 如果同時有多個計時器檔案描述器準備好讀取，\n" -" # epoll.poll() 會回傳一個 (fd, event) 配對的串列。\n" -" #\n" -" # 在此範例設定中，\n" -" # 第 1 個計時器在 0.25 秒內每 0.25 秒觸發一次。(0.25, 0.5, 0.75, 1.0, ...)\n" -" # 第 2 個計時器在 0.5 秒內每 0.5 秒觸發一次。(0.5, 1.0, 1.5, 2.0, ...)\n" -" # 第 3 個計時器在 0.75 秒內每 0.75 秒觸發一次。(0.75, 1.5, 2.25, 3.0, ...)\n" -" #\n" -" # 在 0.25 秒時，只有第 1 個計時器觸發。\n" -" # 在 0.5 秒時，第 1 個計時器和第 2 個計時器同時觸發。\n" -" # 在 0.75 秒時，第 1 個計時器和第 3 個計時器同時觸發。\n" -" # 在 1.5 秒時，第 1、2、3 個計時器同時觸發。\n" -" #\n" -" # 如果計時器檔案描述器自上次 os.read() 呼叫以來被觸發多次，\n" -" # os.read() 會以主機類別位元組順序回傳被觸發次數。\n" -" print(f\"Signaled events={events}\")\n" -" for fd, event in events:\n" -" if event & select.EPOLLIN:\n" -" if fd == sock.fileno():\n" -" # 檢查是否有連線請求。\n" -" print(f\"Accepting connection {fd}\")\n" -" conn, addr = sock.accept()\n" -" conn.setblocking(False)\n" -" print(f\"Accepted connection {conn} from {addr}\")\n" -" ep.register(conn, select.EPOLLIN)\n" -" elif conn and fd == conn.fileno():\n" -" # 檢查是否有資料要讀取。\n" -" print(f\"Reading data {fd}\")\n" -" data = conn.recv(1024)\n" -" if data:\n" -" # 為了安全起見，你應該捕獲 UnicodeDecodeError 例外。\n" -" cmd = data.decode()\n" -" if cmd.startswith(\"stop\"):\n" -" print(f\"Stopping server\")\n" -" is_active = False\n" -" else:\n" -" print(f\"Unknown command: {cmd}\")\n" -" else:\n" -" # 沒有更多資料，關閉連線\n" -" print(f\"Closing connection {fd}\")\n" -" ep.unregister(conn)\n" -" conn.close()\n" -" conn = None\n" -" elif fd in fds:\n" -" print(f\"Reading timer {fd}\")\n" -" count = int.from_bytes(os.read(fd, 8), byteorder=sys." -"byteorder)\n" -" print(f\"Timer {fds.index(fd) + 1} expired {count} " -"times\")\n" -" else:\n" -" print(f\"Unknown file descriptor {fd}\")\n" -"finally:\n" -" for fd in fds:\n" -" ep.unregister(fd)\n" -" os.close(fd)\n" -" ep.close()" - -#: ../../howto/timerfd.rst:153 -msgid "" -"This example shows how :func:`~select.select` can be used with timer file " -"descriptors to wait until the file descriptor is ready for reading:" -msgstr "" -"此範例展示如何將 :func:`~select.select` 與計時器檔案描述器一起使用，" -"用於等待檔案描述器直到它準備好讀取：" - -#: ../../howto/timerfd.rst:156 -msgid "" -"import os, time, select, socket, sys\n" -"\n" -"# In this example, use loopback address to send \"stop\" command to the " -"server.\n" -"#\n" -"# $ telnet 127.0.0.1 1234\n" -"# Trying 127.0.0.1...\n" -"# Connected to 127.0.0.1.\n" -"# Escape character is '^]'.\n" -"# stop\n" -"# Connection closed by foreign host.\n" -"#\n" -"sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)\n" -"sock.bind((\"127.0.0.1\", 1234))\n" -"sock.setblocking(False)\n" -"sock.listen(1)\n" -"\n" -"# Create timer file descriptors in non-blocking mode.\n" -"num = 3\n" -"fds = [os.timerfd_create(time.CLOCK_REALTIME, flags=os.TFD_NONBLOCK)\n" -" for _ in range(num)]\n" -"select_fds = fds + [sock]\n" -"\n" -"# Start the timers with os.timerfd_settime() in seconds.\n" -"# Timer 1 fires every 0.25 seconds; timer 2 every 0.5 seconds; etc\n" -"for i, fd in enumerate(fds, start=1):\n" -" os.timerfd_settime(fd, initial=i/4, interval=i/4)\n" -"\n" -"timeout = 3\n" -"try:\n" -" conn = None\n" -" is_active = True\n" -" while is_active:\n" -" # Wait for the timer to expire for 3 seconds.\n" -" # select.select() returns a list of file descriptors or objects.\n" -" rfd, wfd, xfd = select.select(select_fds, select_fds, select_fds, " -"timeout)\n" -" for fd in rfd:\n" -" if fd == sock:\n" -" # Check if there is a connection request.\n" -" print(f\"Accepting connection {fd}\")\n" -" conn, addr = sock.accept()\n" -" conn.setblocking(False)\n" -" print(f\"Accepted connection {conn} from {addr}\")\n" -" select_fds.append(conn)\n" -" elif conn and fd == conn:\n" -" # Check if there is data to read.\n" -" print(f\"Reading data {fd}\")\n" -" data = conn.recv(1024)\n" -" if data:\n" -" # You should catch UnicodeDecodeError exception for " -"safety.\n" -" cmd = data.decode()\n" -" if cmd.startswith(\"stop\"):\n" -" print(f\"Stopping server\")\n" -" is_active = False\n" -" else:\n" -" print(f\"Unknown command: {cmd}\")\n" -" else:\n" -" # No more data, close connection\n" -" print(f\"Closing connection {fd}\")\n" -" select_fds.remove(conn)\n" -" conn.close()\n" -" conn = None\n" -" elif fd in fds:\n" -" print(f\"Reading timer {fd}\")\n" -" count = int.from_bytes(os.read(fd, 8), byteorder=sys." -"byteorder)\n" -" print(f\"Timer {fds.index(fd) + 1} expired {count} times\")\n" -" else:\n" -" print(f\"Unknown file descriptor {fd}\")\n" -"finally:\n" -" for fd in fds:\n" -" os.close(fd)\n" -" sock.close()\n" -" sock = None" -msgstr "" -"import os, time, select, socket, sys\n" -"\n" -"# 在此範例中，使用回送位址向伺服器發送 \"stop\" 命令。\n" -"#\n" -"# $ telnet 127.0.0.1 1234\n" -"# Trying 127.0.0.1...\n" -"# Connected to 127.0.0.1.\n" -"# Escape character is '^]'.\n" -"# stop\n" -"# Connection closed by foreign host.\n" -"#\n" -"sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)\n" -"sock.bind((\"127.0.0.1\", 1234))\n" -"sock.setblocking(False)\n" -"sock.listen(1)\n" -"\n" -"# 以非阻塞模式建立計時器檔案描述器。\n" -"num = 3\n" -"fds = [os.timerfd_create(time.CLOCK_REALTIME, flags=os.TFD_NONBLOCK)\n" -" for _ in range(num)]\n" -"select_fds = fds + [sock]\n" -"\n" -"# 使用 os.timerfd_settime() 以秒為單位啟動計時器。\n" -"# 計時器 1 每 0.25 秒觸發一次；計時器 2 每 0.5 秒觸發一次；以此類推\n" -"for i, fd in enumerate(fds, start=1):\n" -" os.timerfd_settime(fd, initial=i/4, interval=i/4)\n" -"\n" -"timeout = 3\n" -"try:\n" -" conn = None\n" -" is_active = True\n" -" while is_active:\n" -" # 等待計時器在 3 秒內到期。\n" -" # select.select() 回傳檔案描述器或物件的串列。\n" -" rfd, wfd, xfd = select.select(select_fds, select_fds, select_fds, " -"timeout)\n" -" for fd in rfd:\n" -" if fd == sock:\n" -" # 檢查是否有連線請求。\n" -" print(f\"Accepting connection {fd}\")\n" -" conn, addr = sock.accept()\n" -" conn.setblocking(False)\n" -" print(f\"Accepted connection {conn} from {addr}\")\n" -" select_fds.append(conn)\n" -" elif conn and fd == conn:\n" -" # 檢查是否有資料要讀取。\n" -" print(f\"Reading data {fd}\")\n" -" data = conn.recv(1024)\n" -" if data:\n" -" # 為了安全起見，你應該捕獲 UnicodeDecodeError 例外。\n" -" cmd = data.decode()\n" -" if cmd.startswith(\"stop\"):\n" -" print(f\"Stopping server\")\n" -" is_active = False\n" -" else:\n" -" print(f\"Unknown command: {cmd}\")\n" -" else:\n" -" # 沒有更多資料，關閉連線\n" -" print(f\"Closing connection {fd}\")\n" -" select_fds.remove(conn)\n" -" conn.close()\n" -" conn = None\n" -" elif fd in fds:\n" -" print(f\"Reading timer {fd}\")\n" -" count = int.from_bytes(os.read(fd, 8), byteorder=sys." -"byteorder)\n" -" print(f\"Timer {fds.index(fd) + 1} expired {count} times\")\n" -" else:\n" -" print(f\"Unknown file descriptor {fd}\")\n" -"finally:\n" -" for fd in fds:\n" -" os.close(fd)\n" -" sock.close()\n" -" sock = None" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# Translators: +# GitHub Copilot, 2025 +# +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-09-23 07:52+0800\n" +"PO-Revision-Date: 2024-12-19 10:00+0000\n" +"Last-Translator: GitHub Copilot\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" + +#: ../../howto/timerfd.rst:5 +msgid "timer file descriptor HOWTO" +msgstr "計時器檔案描述器 (timerfd) 指南" + +#: ../../howto/timerfd.rst:0 +msgid "Release" +msgstr "發佈版本" + +#: ../../howto/timerfd.rst:7 +msgid "1.13" +msgstr "1.13" + +#: ../../howto/timerfd.rst:9 +msgid "" +"This HOWTO discusses Python's support for the linux timer file descriptor." +msgstr "此篇指南探討 Python 對 Linux 計時器檔案描述器的支援。" + +#: ../../howto/timerfd.rst:13 +msgid "Examples" +msgstr "範例" + +#: ../../howto/timerfd.rst:15 +msgid "" +"The following example shows how to use a timer file descriptor to execute a " +"function twice a second:" +msgstr "以下範例顯示如何使用計時器檔案描述器來每秒執行函式兩次：" + +#: ../../howto/timerfd.rst:18 +msgid "" +"# Practical scripts should use really use a non-blocking timer,\n" +"# we use a blocking timer here for simplicity.\n" +"import os, time\n" +"\n" +"# Create the timer file descriptor\n" +"fd = os.timerfd_create(time.CLOCK_REALTIME)\n" +"\n" +"# Start the timer in 1 second, with an interval of half a second\n" +"os.timerfd_settime(fd, initial=1, interval=0.5)\n" +"\n" +"try:\n" +" # Process timer events four times.\n" +" for _ in range(4):\n" +" # read() will block until the timer expires\n" +" _ = os.read(fd, 8)\n" +" print(\"Timer expired\")\n" +"finally:\n" +" # Remember to close the timer file descriptor!\n" +" os.close(fd)" +msgstr "" +"# 實際腳本應該使用非阻塞計時器，\n" +"# 在這裡為了簡單起見我們使用阻塞計時器。\n" +"import os, time\n" +"\n" +"# 建立計時器檔案描述器\n" +"fd = os.timerfd_create(time.CLOCK_REALTIME)\n" +"\n" +"# 在 1 秒後開始計時器，間隔為半秒\n" +"os.timerfd_settime(fd, initial=1, interval=0.5)\n" +"\n" +"try:\n" +" # 處理計時器事件四次。\n" +" for _ in range(4):\n" +" # read() 會阻塞直到計時器到期\n" +" _ = os.read(fd, 8)\n" +" print(\"Timer expired\")\n" +"finally:\n" +" # 記得關閉計時器檔案描述器！\n" +" os.close(fd)" + +#: ../../howto/timerfd.rst:40 +msgid "" +"To avoid the precision loss caused by the :class:`float` type, timer file " +"descriptors allow specifying initial expiration and interval in integer " +"nanoseconds with ``_ns`` variants of the functions." +msgstr "" +"為了避免由 :class:`float` 型別造成的精度損失，計時器檔案描述器允許使用函式的 " +"``_ns`` 變體以整數奈秒為單位指定初始到期時間和間隔。" + +#: ../../howto/timerfd.rst:44 +msgid "" +"This example shows how :func:`~select.epoll` can be used with timer file " +"descriptors to wait until the file descriptor is ready for reading:" +msgstr "" +"此範例展示如何將 :func:`~select.epoll` 與計時器檔案描述器一起使用，" +"用於等待檔案描述器直到它準備好讀取：" + +#: ../../howto/timerfd.rst:47 +msgid "" +"import os, time, select, socket, sys\n" +"\n" +"# Create an epoll object\n" +"ep = select.epoll()\n" +"\n" +"# In this example, use loopback address to send \"stop\" command to the " +"server.\n" +"#\n" +"# $ telnet 127.0.0.1 1234\n" +"# Trying 127.0.0.1...\n" +"# Connected to 127.0.0.1.\n" +"# Escape character is '^]'.\n" +"# stop\n" +"# Connection closed by foreign host.\n" +"#\n" +"sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)\n" +"sock.bind((\"127.0.0.1\", 1234))\n" +"sock.setblocking(False)\n" +"sock.listen(1)\n" +"ep.register(sock, select.EPOLLIN)\n" +"\n" +"# Create timer file descriptors in non-blocking mode.\n" +"num = 3\n" +"fds = []\n" +"for _ in range(num):\n" +" fd = os.timerfd_create(time.CLOCK_REALTIME, flags=os.TFD_NONBLOCK)\n" +" fds.append(fd)\n" +" # Register the timer file descriptor for read events\n" +" ep.register(fd, select.EPOLLIN)\n" +"\n" +"# Start the timer with os.timerfd_settime_ns() in nanoseconds.\n" +"# Timer 1 fires every 0.25 seconds; timer 2 every 0.5 seconds; etc\n" +"for i, fd in enumerate(fds, start=1):\n" +" one_sec_in_nsec = 10**9\n" +" i = i * one_sec_in_nsec\n" +" os.timerfd_settime_ns(fd, initial=i//4, interval=i//4)\n" +"\n" +"timeout = 3\n" +"try:\n" +" conn = None\n" +" is_active = True\n" +" while is_active:\n" +" # Wait for the timer to expire for 3 seconds.\n" +" # epoll.poll() returns a list of (fd, event) pairs.\n" +" # fd is a file descriptor.\n" +" # sock and conn[=returned value of socket.accept()] are socket " +"objects, not file descriptors.\n" +" # So use sock.fileno() and conn.fileno() to get the file " +"descriptors.\n" +" events = ep.poll(timeout)\n" +"\n" +" # If more than one timer file descriptors are ready for reading at " +"once,\n" +" # epoll.poll() returns a list of (fd, event) pairs.\n" +" #\n" +" # In this example settings,\n" +" # 1st timer fires every 0.25 seconds in 0.25 seconds. (0.25, 0.5, " +"0.75, 1.0, ...)\n" +" # 2nd timer every 0.5 seconds in 0.5 seconds. (0.5, 1.0, 1.5, " +"2.0, ...)\n" +" # 3rd timer every 0.75 seconds in 0.75 seconds. (0.75, 1.5, 2.25, " +"3.0, ...)\n" +" #\n" +" # In 0.25 seconds, only 1st timer fires.\n" +" # In 0.5 seconds, 1st timer and 2nd timer fires at once.\n" +" # In 0.75 seconds, 1st timer and 3rd timer fires at once.\n" +" # In 1.5 seconds, 1st timer, 2nd timer and 3rd timer fires at " +"once.\n" +" #\n" +" # If a timer file descriptor is signaled more than once since\n" +" # the last os.read() call, os.read() returns the number of signaled\n" +" # as host order of class bytes.\n" +" print(f\"Signaled events={events}\")\n" +" for fd, event in events:\n" +" if event & select.EPOLLIN:\n" +" if fd == sock.fileno():\n" +" # Check if there is a connection request.\n" +" print(f\"Accepting connection {fd}\")\n" +" conn, addr = sock.accept()\n" +" conn.setblocking(False)\n" +" print(f\"Accepted connection {conn} from {addr}\")\n" +" ep.register(conn, select.EPOLLIN)\n" +" elif conn and fd == conn.fileno():\n" +" # Check if there is data to read.\n" +" print(f\"Reading data {fd}\")\n" +" data = conn.recv(1024)\n" +" if data:\n" +" # You should catch UnicodeDecodeError exception for " +"safety.\n" +" cmd = data.decode()\n" +" if cmd.startswith(\"stop\"):\n" +" print(f\"Stopping server\")\n" +" is_active = False\n" +" else:\n" +" print(f\"Unknown command: {cmd}\")\n" +" else:\n" +" # No more data, close connection\n" +" print(f\"Closing connection {fd}\")\n" +" ep.unregister(conn)\n" +" conn.close()\n" +" conn = None\n" +" elif fd in fds:\n" +" print(f\"Reading timer {fd}\")\n" +" count = int.from_bytes(os.read(fd, 8), byteorder=sys." +"byteorder)\n" +" print(f\"Timer {fds.index(fd) + 1} expired {count} " +"times\")\n" +" else:\n" +" print(f\"Unknown file descriptor {fd}\")\n" +"finally:\n" +" for fd in fds:\n" +" ep.unregister(fd)\n" +" os.close(fd)\n" +" ep.close()" +msgstr "" +"import os, time, select, socket, sys\n" +"\n" +"# 建立 epoll 物件\n" +"ep = select.epoll()\n" +"\n" +"# 在此範例中，使用回送位址 (loopback address) 向伺服器發送 \"stop\" 命令。\n" +"#\n" +"# $ telnet 127.0.0.1 1234\n" +"# Trying 127.0.0.1...\n" +"# Connected to 127.0.0.1.\n" +"# Escape character is '^]'.\n" +"# stop\n" +"# Connection closed by foreign host.\n" +"#\n" +"sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)\n" +"sock.bind((\"127.0.0.1\", 1234))\n" +"sock.setblocking(False)\n" +"sock.listen(1)\n" +"ep.register(sock, select.EPOLLIN)\n" +"\n" +"# 以非阻塞模式建立計時器檔案描述器。\n" +"num = 3\n" +"fds = []\n" +"for _ in range(num):\n" +" fd = os.timerfd_create(time.CLOCK_REALTIME, flags=os.TFD_NONBLOCK)\n" +" fds.append(fd)\n" +" # 為讀取事件註冊計時器檔案描述器\n" +" ep.register(fd, select.EPOLLIN)\n" +"\n" +"# 使用 os.timerfd_settime_ns() 以奈秒為單位啟動計時器。\n" +"# 計時器 1 每 0.25 秒觸發一次；計時器 2 每 0.5 秒觸發一次；以此類推\n" +"for i, fd in enumerate(fds, start=1):\n" +" one_sec_in_nsec = 10**9\n" +" i = i * one_sec_in_nsec\n" +" os.timerfd_settime_ns(fd, initial=i//4, interval=i//4)\n" +"\n" +"timeout = 3\n" +"try:\n" +" conn = None\n" +" is_active = True\n" +" while is_active:\n" +" # 等待計時器在 3 秒內到期。\n" +" # epoll.poll() 回傳一個 (fd, event) 配對的串列。\n" +" # fd 是檔案描述器。\n" +" # sock 和 conn[=socket.accept() 的回傳值] 是 socket 物件，不是檔案描述器。\n" +" # 所以要使用 sock.fileno() 和 conn.fileno() 來取得檔案描述器。\n" +" events = ep.poll(timeout)\n" +"\n" +" # 如果同時有多個計時器檔案描述器準備好讀取，\n" +" # epoll.poll() 會回傳一個 (fd, event) 配對的串列。\n" +" #\n" +" # 在此範例設定中，\n" +" # 第 1 個計時器在 0.25 秒內每 0.25 秒觸發一次。(0.25, 0.5, 0.75, 1.0, ...)\n" +" # 第 2 個計時器在 0.5 秒內每 0.5 秒觸發一次。(0.5, 1.0, 1.5, 2.0, ...)\n" +" # 第 3 個計時器在 0.75 秒內每 0.75 秒觸發一次。(0.75, 1.5, 2.25, 3.0, ...)\n" +" #\n" +" # 在 0.25 秒時，只有第 1 個計時器觸發。\n" +" # 在 0.5 秒時，第 1 個計時器和第 2 個計時器同時觸發。\n" +" # 在 0.75 秒時，第 1 個計時器和第 3 個計時器同時觸發。\n" +" # 在 1.5 秒時，第 1、2、3 個計時器同時觸發。\n" +" #\n" +" # 如果計時器檔案描述器自上次 os.read() 呼叫以來被觸發多次，\n" +" # os.read() 會以主機類別位元組順序回傳被觸發次數。\n" +" print(f\"Signaled events={events}\")\n" +" for fd, event in events:\n" +" if event & select.EPOLLIN:\n" +" if fd == sock.fileno():\n" +" # 檢查是否有連線請求。\n" +" print(f\"Accepting connection {fd}\")\n" +" conn, addr = sock.accept()\n" +" conn.setblocking(False)\n" +" print(f\"Accepted connection {conn} from {addr}\")\n" +" ep.register(conn, select.EPOLLIN)\n" +" elif conn and fd == conn.fileno():\n" +" # 檢查是否有資料要讀取。\n" +" print(f\"Reading data {fd}\")\n" +" data = conn.recv(1024)\n" +" if data:\n" +" # 為了安全起見，你應該捕獲 UnicodeDecodeError 例外。\n" +" cmd = data.decode()\n" +" if cmd.startswith(\"stop\"):\n" +" print(f\"Stopping server\")\n" +" is_active = False\n" +" else:\n" +" print(f\"Unknown command: {cmd}\")\n" +" else:\n" +" # 沒有更多資料，關閉連線\n" +" print(f\"Closing connection {fd}\")\n" +" ep.unregister(conn)\n" +" conn.close()\n" +" conn = None\n" +" elif fd in fds:\n" +" print(f\"Reading timer {fd}\")\n" +" count = int.from_bytes(os.read(fd, 8), byteorder=sys." +"byteorder)\n" +" print(f\"Timer {fds.index(fd) + 1} expired {count} " +"times\")\n" +" else:\n" +" print(f\"Unknown file descriptor {fd}\")\n" +"finally:\n" +" for fd in fds:\n" +" ep.unregister(fd)\n" +" os.close(fd)\n" +" ep.close()" + +#: ../../howto/timerfd.rst:153 +msgid "" +"This example shows how :func:`~select.select` can be used with timer file " +"descriptors to wait until the file descriptor is ready for reading:" +msgstr "" +"此範例展示如何將 :func:`~select.select` 與計時器檔案描述器一起使用，" +"用於等待檔案描述器直到它準備好讀取：" + +#: ../../howto/timerfd.rst:156 +msgid "" +"import os, time, select, socket, sys\n" +"\n" +"# In this example, use loopback address to send \"stop\" command to the " +"server.\n" +"#\n" +"# $ telnet 127.0.0.1 1234\n" +"# Trying 127.0.0.1...\n" +"# Connected to 127.0.0.1.\n" +"# Escape character is '^]'.\n" +"# stop\n" +"# Connection closed by foreign host.\n" +"#\n" +"sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)\n" +"sock.bind((\"127.0.0.1\", 1234))\n" +"sock.setblocking(False)\n" +"sock.listen(1)\n" +"\n" +"# Create timer file descriptors in non-blocking mode.\n" +"num = 3\n" +"fds = [os.timerfd_create(time.CLOCK_REALTIME, flags=os.TFD_NONBLOCK)\n" +" for _ in range(num)]\n" +"select_fds = fds + [sock]\n" +"\n" +"# Start the timers with os.timerfd_settime() in seconds.\n" +"# Timer 1 fires every 0.25 seconds; timer 2 every 0.5 seconds; etc\n" +"for i, fd in enumerate(fds, start=1):\n" +" os.timerfd_settime(fd, initial=i/4, interval=i/4)\n" +"\n" +"timeout = 3\n" +"try:\n" +" conn = None\n" +" is_active = True\n" +" while is_active:\n" +" # Wait for the timer to expire for 3 seconds.\n" +" # select.select() returns a list of file descriptors or objects.\n" +" rfd, wfd, xfd = select.select(select_fds, select_fds, select_fds, " +"timeout)\n" +" for fd in rfd:\n" +" if fd == sock:\n" +" # Check if there is a connection request.\n" +" print(f\"Accepting connection {fd}\")\n" +" conn, addr = sock.accept()\n" +" conn.setblocking(False)\n" +" print(f\"Accepted connection {conn} from {addr}\")\n" +" select_fds.append(conn)\n" +" elif conn and fd == conn:\n" +" # Check if there is data to read.\n" +" print(f\"Reading data {fd}\")\n" +" data = conn.recv(1024)\n" +" if data:\n" +" # You should catch UnicodeDecodeError exception for " +"safety.\n" +" cmd = data.decode()\n" +" if cmd.startswith(\"stop\"):\n" +" print(f\"Stopping server\")\n" +" is_active = False\n" +" else:\n" +" print(f\"Unknown command: {cmd}\")\n" +" else:\n" +" # No more data, close connection\n" +" print(f\"Closing connection {fd}\")\n" +" select_fds.remove(conn)\n" +" conn.close()\n" +" conn = None\n" +" elif fd in fds:\n" +" print(f\"Reading timer {fd}\")\n" +" count = int.from_bytes(os.read(fd, 8), byteorder=sys." +"byteorder)\n" +" print(f\"Timer {fds.index(fd) + 1} expired {count} times\")\n" +" else:\n" +" print(f\"Unknown file descriptor {fd}\")\n" +"finally:\n" +" for fd in fds:\n" +" os.close(fd)\n" +" sock.close()\n" +" sock = None" +msgstr "" +"import os, time, select, socket, sys\n" +"\n" +"# 在此範例中，使用回送位址向伺服器發送 \"stop\" 命令。\n" +"#\n" +"# $ telnet 127.0.0.1 1234\n" +"# Trying 127.0.0.1...\n" +"# Connected to 127.0.0.1.\n" +"# Escape character is '^]'.\n" +"# stop\n" +"# Connection closed by foreign host.\n" +"#\n" +"sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)\n" +"sock.bind((\"127.0.0.1\", 1234))\n" +"sock.setblocking(False)\n" +"sock.listen(1)\n" +"\n" +"# 以非阻塞模式建立計時器檔案描述器。\n" +"num = 3\n" +"fds = [os.timerfd_create(time.CLOCK_REALTIME, flags=os.TFD_NONBLOCK)\n" +" for _ in range(num)]\n" +"select_fds = fds + [sock]\n" +"\n" +"# 使用 os.timerfd_settime() 以秒為單位啟動計時器。\n" +"# 計時器 1 每 0.25 秒觸發一次；計時器 2 每 0.5 秒觸發一次；以此類推\n" +"for i, fd in enumerate(fds, start=1):\n" +" os.timerfd_settime(fd, initial=i/4, interval=i/4)\n" +"\n" +"timeout = 3\n" +"try:\n" +" conn = None\n" +" is_active = True\n" +" while is_active:\n" +" # 等待計時器在 3 秒內到期。\n" +" # select.select() 回傳檔案描述器或物件的串列。\n" +" rfd, wfd, xfd = select.select(select_fds, select_fds, select_fds, " +"timeout)\n" +" for fd in rfd:\n" +" if fd == sock:\n" +" # 檢查是否有連線請求。\n" +" print(f\"Accepting connection {fd}\")\n" +" conn, addr = sock.accept()\n" +" conn.setblocking(False)\n" +" print(f\"Accepted connection {conn} from {addr}\")\n" +" select_fds.append(conn)\n" +" elif conn and fd == conn:\n" +" # 檢查是否有資料要讀取。\n" +" print(f\"Reading data {fd}\")\n" +" data = conn.recv(1024)\n" +" if data:\n" +" # 為了安全起見，你應該捕獲 UnicodeDecodeError 例外。\n" +" cmd = data.decode()\n" +" if cmd.startswith(\"stop\"):\n" +" print(f\"Stopping server\")\n" +" is_active = False\n" +" else:\n" +" print(f\"Unknown command: {cmd}\")\n" +" else:\n" +" # 沒有更多資料，關閉連線\n" +" print(f\"Closing connection {fd}\")\n" +" select_fds.remove(conn)\n" +" conn.close()\n" +" conn = None\n" +" elif fd in fds:\n" +" print(f\"Reading timer {fd}\")\n" +" count = int.from_bytes(os.read(fd, 8), byteorder=sys." +"byteorder)\n" +" print(f\"Timer {fds.index(fd) + 1} expired {count} times\")\n" +" else:\n" +" print(f\"Unknown file descriptor {fd}\")\n" +"finally:\n" +" for fd in fds:\n" +" os.close(fd)\n" +" sock.close()\n" +" sock = None" diff --git a/howto/unicode.po b/howto/unicode.po index 2a9e35df0e..1eb1018730 100644 --- a/howto/unicode.po +++ b/howto/unicode.po @@ -1,1263 +1,1263 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-25 00:13+0000\n" -"PO-Revision-Date: 2018-05-23 14:37+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" - -#: ../../howto/unicode.rst:5 -msgid "Unicode HOWTO" -msgstr "" - -#: ../../howto/unicode.rst:0 -msgid "Release" -msgstr "發佈版本" - -#: ../../howto/unicode.rst:7 -msgid "1.12" -msgstr "1.12" - -#: ../../howto/unicode.rst:9 -msgid "" -"This HOWTO discusses Python's support for the Unicode specification for " -"representing textual data, and explains various problems that people " -"commonly encounter when trying to work with Unicode." -msgstr "" - -#: ../../howto/unicode.rst:15 -msgid "Introduction to Unicode" -msgstr "" - -#: ../../howto/unicode.rst:18 -msgid "Definitions" -msgstr "定義" - -#: ../../howto/unicode.rst:20 -msgid "" -"Today's programs need to be able to handle a wide variety of characters. " -"Applications are often internationalized to display messages and output in a " -"variety of user-selectable languages; the same program might need to output " -"an error message in English, French, Japanese, Hebrew, or Russian. Web " -"content can be written in any of these languages and can also include a " -"variety of emoji symbols. Python's string type uses the Unicode Standard for " -"representing characters, which lets Python programs work with all these " -"different possible characters." -msgstr "" - -#: ../../howto/unicode.rst:30 -msgid "" -"Unicode (https://www.unicode.org/) is a specification that aims to list " -"every character used by human languages and give each character its own " -"unique code. The Unicode specifications are continually revised and updated " -"to add new languages and symbols." -msgstr "" - -#: ../../howto/unicode.rst:35 -msgid "" -"A **character** is the smallest possible component of a text. 'A', 'B', " -"'C', etc., are all different characters. So are 'È' and 'Í'. Characters " -"vary depending on the language or context you're talking about. For " -"example, there's a character for \"Roman Numeral One\", 'Ⅰ', that's separate " -"from the uppercase letter 'I'. They'll usually look the same, but these are " -"two different characters that have different meanings." -msgstr "" - -#: ../../howto/unicode.rst:42 -msgid "" -"The Unicode standard describes how characters are represented by **code " -"points**. A code point value is an integer in the range 0 to 0x10FFFF " -"(about 1.1 million values, the `actual number assigned `_ is less than that). In the standard and in " -"this document, a code point is written using the notation ``U+265E`` to mean " -"the character with value ``0x265e`` (9,822 in decimal)." -msgstr "" - -#: ../../howto/unicode.rst:50 -msgid "" -"The Unicode standard contains a lot of tables listing characters and their " -"corresponding code points:" -msgstr "" - -#: ../../howto/unicode.rst:53 -msgid "" -"0061 'a'; LATIN SMALL LETTER A\n" -"0062 'b'; LATIN SMALL LETTER B\n" -"0063 'c'; LATIN SMALL LETTER C\n" -"...\n" -"007B '{'; LEFT CURLY BRACKET\n" -"...\n" -"2167 'Ⅷ'; ROMAN NUMERAL EIGHT\n" -"2168 'Ⅸ'; ROMAN NUMERAL NINE\n" -"...\n" -"265E '♞'; BLACK CHESS KNIGHT\n" -"265F '♟'; BLACK CHESS PAWN\n" -"...\n" -"1F600 '😀'; GRINNING FACE\n" -"1F609 '😉'; WINKING FACE\n" -"..." -msgstr "" -"0061 'a'; LATIN SMALL LETTER A\n" -"0062 'b'; LATIN SMALL LETTER B\n" -"0063 'c'; LATIN SMALL LETTER C\n" -"...\n" -"007B '{'; LEFT CURLY BRACKET\n" -"...\n" -"2167 'Ⅷ'; ROMAN NUMERAL EIGHT\n" -"2168 'Ⅸ'; ROMAN NUMERAL NINE\n" -"...\n" -"265E '♞'; BLACK CHESS KNIGHT\n" -"265F '♟'; BLACK CHESS PAWN\n" -"...\n" -"1F600 '😀'; GRINNING FACE\n" -"1F609 '😉'; WINKING FACE\n" -"..." - -#: ../../howto/unicode.rst:71 -msgid "" -"Strictly, these definitions imply that it's meaningless to say 'this is " -"character ``U+265E``'. ``U+265E`` is a code point, which represents some " -"particular character; in this case, it represents the character 'BLACK CHESS " -"KNIGHT', '♞'. In informal contexts, this distinction between code points " -"and characters will sometimes be forgotten." -msgstr "" - -#: ../../howto/unicode.rst:78 -msgid "" -"A character is represented on a screen or on paper by a set of graphical " -"elements that's called a **glyph**. The glyph for an uppercase A, for " -"example, is two diagonal strokes and a horizontal stroke, though the exact " -"details will depend on the font being used. Most Python code doesn't need " -"to worry about glyphs; figuring out the correct glyph to display is " -"generally the job of a GUI toolkit or a terminal's font renderer." -msgstr "" - -#: ../../howto/unicode.rst:87 -msgid "Encodings" -msgstr "" - -#: ../../howto/unicode.rst:89 -msgid "" -"To summarize the previous section: a Unicode string is a sequence of code " -"points, which are numbers from 0 through ``0x10FFFF`` (1,114,111 decimal). " -"This sequence of code points needs to be represented in memory as a set of " -"**code units**, and **code units** are then mapped to 8-bit bytes. The " -"rules for translating a Unicode string into a sequence of bytes are called a " -"**character encoding**, or just an **encoding**." -msgstr "" - -#: ../../howto/unicode.rst:97 -msgid "" -"The first encoding you might think of is using 32-bit integers as the code " -"unit, and then using the CPU's representation of 32-bit integers. In this " -"representation, the string \"Python\" might look like this:" -msgstr "" - -#: ../../howto/unicode.rst:101 -msgid "" -" P y t h o n\n" -"0x50 00 00 00 79 00 00 00 74 00 00 00 68 00 00 00 6f 00 00 00 6e 00 00 00\n" -" 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23" -msgstr "" -" P y t h o n\n" -"0x50 00 00 00 79 00 00 00 74 00 00 00 68 00 00 00 6f 00 00 00 6e 00 00 00\n" -" 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23" - -#: ../../howto/unicode.rst:107 -msgid "" -"This representation is straightforward but using it presents a number of " -"problems." -msgstr "" - -#: ../../howto/unicode.rst:110 -msgid "It's not portable; different processors order the bytes differently." -msgstr "" - -#: ../../howto/unicode.rst:112 -msgid "" -"It's very wasteful of space. In most texts, the majority of the code points " -"are less than 127, or less than 255, so a lot of space is occupied by " -"``0x00`` bytes. The above string takes 24 bytes compared to the 6 bytes " -"needed for an ASCII representation. Increased RAM usage doesn't matter too " -"much (desktop computers have gigabytes of RAM, and strings aren't usually " -"that large), but expanding our usage of disk and network bandwidth by a " -"factor of 4 is intolerable." -msgstr "" - -#: ../../howto/unicode.rst:120 -msgid "" -"It's not compatible with existing C functions such as ``strlen()``, so a new " -"family of wide string functions would need to be used." -msgstr "" - -#: ../../howto/unicode.rst:123 -msgid "" -"Therefore this encoding isn't used very much, and people instead choose " -"other encodings that are more efficient and convenient, such as UTF-8." -msgstr "" - -#: ../../howto/unicode.rst:126 -msgid "" -"UTF-8 is one of the most commonly used encodings, and Python often defaults " -"to using it. UTF stands for \"Unicode Transformation Format\", and the '8' " -"means that 8-bit values are used in the encoding. (There are also UTF-16 " -"and UTF-32 encodings, but they are less frequently used than UTF-8.) UTF-8 " -"uses the following rules:" -msgstr "" - -#: ../../howto/unicode.rst:132 -msgid "" -"If the code point is < 128, it's represented by the corresponding byte value." -msgstr "" - -#: ../../howto/unicode.rst:133 -msgid "" -"If the code point is >= 128, it's turned into a sequence of two, three, or " -"four bytes, where each byte of the sequence is between 128 and 255." -msgstr "" - -#: ../../howto/unicode.rst:136 -msgid "UTF-8 has several convenient properties:" -msgstr "" - -#: ../../howto/unicode.rst:138 -msgid "It can handle any Unicode code point." -msgstr "" - -#: ../../howto/unicode.rst:139 -msgid "" -"A Unicode string is turned into a sequence of bytes that contains embedded " -"zero bytes only where they represent the null character (U+0000). This means " -"that UTF-8 strings can be processed by C functions such as ``strcpy()`` and " -"sent through protocols that can't handle zero bytes for anything other than " -"end-of-string markers." -msgstr "" - -#: ../../howto/unicode.rst:144 -msgid "A string of ASCII text is also valid UTF-8 text." -msgstr "" - -#: ../../howto/unicode.rst:145 -msgid "" -"UTF-8 is fairly compact; the majority of commonly used characters can be " -"represented with one or two bytes." -msgstr "" - -#: ../../howto/unicode.rst:147 -msgid "" -"If bytes are corrupted or lost, it's possible to determine the start of the " -"next UTF-8-encoded code point and resynchronize. It's also unlikely that " -"random 8-bit data will look like valid UTF-8." -msgstr "" - -#: ../../howto/unicode.rst:150 -msgid "" -"UTF-8 is a byte oriented encoding. The encoding specifies that each " -"character is represented by a specific sequence of one or more bytes. This " -"avoids the byte-ordering issues that can occur with integer and word " -"oriented encodings, like UTF-16 and UTF-32, where the sequence of bytes " -"varies depending on the hardware on which the string was encoded." -msgstr "" - -#: ../../howto/unicode.rst:158 ../../howto/unicode.rst:516 -#: ../../howto/unicode.rst:737 -msgid "References" -msgstr "" - -#: ../../howto/unicode.rst:160 -msgid "" -"The `Unicode Consortium site `_ has character " -"charts, a glossary, and PDF versions of the Unicode specification. Be " -"prepared for some difficult reading. `A chronology `_ of the origin and development of Unicode is also available on " -"the site." -msgstr "" - -#: ../../howto/unicode.rst:165 -msgid "" -"On the Computerphile Youtube channel, Tom Scott briefly `discusses the " -"history of Unicode and UTF-8 `_ " -"(9 minutes 36 seconds)." -msgstr "" - -#: ../../howto/unicode.rst:169 -msgid "" -"To help understand the standard, Jukka Korpela has written `an introductory " -"guide `_ to reading the Unicode " -"character tables." -msgstr "" - -#: ../../howto/unicode.rst:173 -msgid "" -"Another `good introductory article `_ was " -"written by Joel Spolsky. If this introduction didn't make things clear to " -"you, you should try reading this alternate article before continuing." -msgstr "" - -#: ../../howto/unicode.rst:178 -msgid "" -"Wikipedia entries are often helpful; see the entries for \"`character " -"encoding `_\" and `UTF-8 " -"`_, for example." -msgstr "" - -#: ../../howto/unicode.rst:184 -msgid "Python's Unicode Support" -msgstr "" - -#: ../../howto/unicode.rst:186 -msgid "" -"Now that you've learned the rudiments of Unicode, we can look at Python's " -"Unicode features." -msgstr "" - -#: ../../howto/unicode.rst:190 -msgid "The String Type" -msgstr "" - -#: ../../howto/unicode.rst:192 -msgid "" -"Since Python 3.0, the language's :class:`str` type contains Unicode " -"characters, meaning any string created using ``\"unicode rocks!\"``, " -"``'unicode rocks!'``, or the triple-quoted string syntax is stored as " -"Unicode." -msgstr "" - -#: ../../howto/unicode.rst:196 -msgid "" -"The default encoding for Python source code is UTF-8, so you can simply " -"include a Unicode character in a string literal::" -msgstr "" - -#: ../../howto/unicode.rst:199 -msgid "" -"try:\n" -" with open('/tmp/input.txt', 'r') as f:\n" -" ...\n" -"except OSError:\n" -" # 'File not found' error message.\n" -" print(\"Fichier non trouvé\")" -msgstr "" - -#: ../../howto/unicode.rst:206 -msgid "" -"Side note: Python 3 also supports using Unicode characters in identifiers::" -msgstr "" - -#: ../../howto/unicode.rst:208 -msgid "" -"répertoire = \"/tmp/records.log\"\n" -"with open(répertoire, \"w\") as f:\n" -" f.write(\"test\\n\")" -msgstr "" -"répertoire = \"/tmp/records.log\"\n" -"with open(répertoire, \"w\") as f:\n" -" f.write(\"test\\n\")" - -#: ../../howto/unicode.rst:212 -msgid "" -"If you can't enter a particular character in your editor or want to keep the " -"source code ASCII-only for some reason, you can also use escape sequences in " -"string literals. (Depending on your system, you may see the actual capital-" -"delta glyph instead of a \\u escape.) ::" -msgstr "" - -#: ../../howto/unicode.rst:217 -msgid "" -">>> \"\\N{GREEK CAPITAL LETTER DELTA}\" # Using the character name\n" -"'\\u0394'\n" -">>> \"\\u0394\" # Using a 16-bit hex value\n" -"'\\u0394'\n" -">>> \"\\U00000394\" # Using a 32-bit hex value\n" -"'\\u0394'" -msgstr "" - -#: ../../howto/unicode.rst:224 -msgid "" -"In addition, one can create a string using the :func:`~bytes.decode` method " -"of :class:`bytes`. This method takes an *encoding* argument, such as " -"``UTF-8``, and optionally an *errors* argument." -msgstr "" - -#: ../../howto/unicode.rst:228 -msgid "" -"The *errors* argument specifies the response when the input string can't be " -"converted according to the encoding's rules. Legal values for this argument " -"are ``'strict'`` (raise a :exc:`UnicodeDecodeError` exception), " -"``'replace'`` (use ``U+FFFD``, ``REPLACEMENT CHARACTER``), ``'ignore'`` " -"(just leave the character out of the Unicode result), or " -"``'backslashreplace'`` (inserts a ``\\xNN`` escape sequence). The following " -"examples show the differences::" -msgstr "" - -#: ../../howto/unicode.rst:236 -msgid "" -">>> b'\\x80abc'.decode(\"utf-8\", \"strict\")\n" -"Traceback (most recent call last):\n" -" ...\n" -"UnicodeDecodeError: 'utf-8' codec can't decode byte 0x80 in position 0:\n" -" invalid start byte\n" -">>> b'\\x80abc'.decode(\"utf-8\", \"replace\")\n" -"'\\ufffdabc'\n" -">>> b'\\x80abc'.decode(\"utf-8\", \"backslashreplace\")\n" -"'\\\\x80abc'\n" -">>> b'\\x80abc'.decode(\"utf-8\", \"ignore\")\n" -"'abc'" -msgstr "" -">>> b'\\x80abc'.decode(\"utf-8\", \"strict\")\n" -"Traceback (most recent call last):\n" -" ...\n" -"UnicodeDecodeError: 'utf-8' codec can't decode byte 0x80 in position 0:\n" -" invalid start byte\n" -">>> b'\\x80abc'.decode(\"utf-8\", \"replace\")\n" -"'\\ufffdabc'\n" -">>> b'\\x80abc'.decode(\"utf-8\", \"backslashreplace\")\n" -"'\\\\x80abc'\n" -">>> b'\\x80abc'.decode(\"utf-8\", \"ignore\")\n" -"'abc'" - -#: ../../howto/unicode.rst:248 -msgid "" -"Encodings are specified as strings containing the encoding's name. Python " -"comes with roughly 100 different encodings; see the Python Library Reference " -"at :ref:`standard-encodings` for a list. Some encodings have multiple " -"names; for example, ``'latin-1'``, ``'iso_8859_1'`` and ``'8859``' are all " -"synonyms for the same encoding." -msgstr "" - -#: ../../howto/unicode.rst:254 -msgid "" -"One-character Unicode strings can also be created with the :func:`chr` built-" -"in function, which takes integers and returns a Unicode string of length 1 " -"that contains the corresponding code point. The reverse operation is the " -"built-in :func:`ord` function that takes a one-character Unicode string and " -"returns the code point value::" -msgstr "" - -#: ../../howto/unicode.rst:260 -msgid "" -">>> chr(57344)\n" -"'\\ue000'\n" -">>> ord('\\ue000')\n" -"57344" -msgstr "" -">>> chr(57344)\n" -"'\\ue000'\n" -">>> ord('\\ue000')\n" -"57344" - -#: ../../howto/unicode.rst:266 -msgid "Converting to Bytes" -msgstr "" - -#: ../../howto/unicode.rst:268 -msgid "" -"The opposite method of :meth:`bytes.decode` is :meth:`str.encode`, which " -"returns a :class:`bytes` representation of the Unicode string, encoded in " -"the requested *encoding*." -msgstr "" - -#: ../../howto/unicode.rst:272 -msgid "" -"The *errors* parameter is the same as the parameter of the :meth:`~bytes." -"decode` method but supports a few more possible handlers. As well as " -"``'strict'``, ``'ignore'``, and ``'replace'`` (which in this case inserts a " -"question mark instead of the unencodable character), there is also " -"``'xmlcharrefreplace'`` (inserts an XML character reference), " -"``backslashreplace`` (inserts a ``\\uNNNN`` escape sequence) and " -"``namereplace`` (inserts a ``\\N{...}`` escape sequence)." -msgstr "" - -#: ../../howto/unicode.rst:280 -msgid "The following example shows the different results::" -msgstr "" - -#: ../../howto/unicode.rst:282 -msgid "" -">>> u = chr(40960) + 'abcd' + chr(1972)\n" -">>> u.encode('utf-8')\n" -"b'\\xea\\x80\\x80abcd\\xde\\xb4'\n" -">>> u.encode('ascii')\n" -"Traceback (most recent call last):\n" -" ...\n" -"UnicodeEncodeError: 'ascii' codec can't encode character '\\ua000' in\n" -" position 0: ordinal not in range(128)\n" -">>> u.encode('ascii', 'ignore')\n" -"b'abcd'\n" -">>> u.encode('ascii', 'replace')\n" -"b'?abcd?'\n" -">>> u.encode('ascii', 'xmlcharrefreplace')\n" -"b'ꀀabcd޴'\n" -">>> u.encode('ascii', 'backslashreplace')\n" -"b'\\\\ua000abcd\\\\u07b4'\n" -">>> u.encode('ascii', 'namereplace')\n" -"b'\\\\N{YI SYLLABLE IT}abcd\\\\u07b4'" -msgstr "" -">>> u = chr(40960) + 'abcd' + chr(1972)\n" -">>> u.encode('utf-8')\n" -"b'\\xea\\x80\\x80abcd\\xde\\xb4'\n" -">>> u.encode('ascii')\n" -"Traceback (most recent call last):\n" -" ...\n" -"UnicodeEncodeError: 'ascii' codec can't encode character '\\ua000' in\n" -" position 0: ordinal not in range(128)\n" -">>> u.encode('ascii', 'ignore')\n" -"b'abcd'\n" -">>> u.encode('ascii', 'replace')\n" -"b'?abcd?'\n" -">>> u.encode('ascii', 'xmlcharrefreplace')\n" -"b'ꀀabcd޴'\n" -">>> u.encode('ascii', 'backslashreplace')\n" -"b'\\\\ua000abcd\\\\u07b4'\n" -">>> u.encode('ascii', 'namereplace')\n" -"b'\\\\N{YI SYLLABLE IT}abcd\\\\u07b4'" - -#: ../../howto/unicode.rst:301 -msgid "" -"The low-level routines for registering and accessing the available encodings " -"are found in the :mod:`codecs` module. Implementing new encodings also " -"requires understanding the :mod:`codecs` module. However, the encoding and " -"decoding functions returned by this module are usually more low-level than " -"is comfortable, and writing new encodings is a specialized task, so the " -"module won't be covered in this HOWTO." -msgstr "" - -#: ../../howto/unicode.rst:310 -msgid "Unicode Literals in Python Source Code" -msgstr "" - -#: ../../howto/unicode.rst:312 -msgid "" -"In Python source code, specific Unicode code points can be written using the " -"``\\u`` escape sequence, which is followed by four hex digits giving the " -"code point. The ``\\U`` escape sequence is similar, but expects eight hex " -"digits, not four::" -msgstr "" - -#: ../../howto/unicode.rst:317 -msgid "" -">>> s = \"a\\xac\\u1234\\u20ac\\U00008000\"\n" -"... # ^^^^ two-digit hex escape\n" -"... # ^^^^^^ four-digit Unicode escape\n" -"... # ^^^^^^^^^^ eight-digit Unicode escape\n" -">>> [ord(c) for c in s]\n" -"[97, 172, 4660, 8364, 32768]" -msgstr "" -">>> s = \"a\\xac\\u1234\\u20ac\\U00008000\"\n" -"... # ^^^^ two-digit hex escape\n" -"... # ^^^^^^ four-digit Unicode escape\n" -"... # ^^^^^^^^^^ eight-digit Unicode escape\n" -">>> [ord(c) for c in s]\n" -"[97, 172, 4660, 8364, 32768]" - -#: ../../howto/unicode.rst:324 -msgid "" -"Using escape sequences for code points greater than 127 is fine in small " -"doses, but becomes an annoyance if you're using many accented characters, as " -"you would in a program with messages in French or some other accent-using " -"language. You can also assemble strings using the :func:`chr` built-in " -"function, but this is even more tedious." -msgstr "" - -#: ../../howto/unicode.rst:330 -msgid "" -"Ideally, you'd want to be able to write literals in your language's natural " -"encoding. You could then edit Python source code with your favorite editor " -"which would display the accented characters naturally, and have the right " -"characters used at runtime." -msgstr "" - -#: ../../howto/unicode.rst:335 -msgid "" -"Python supports writing source code in UTF-8 by default, but you can use " -"almost any encoding if you declare the encoding being used. This is done by " -"including a special comment as either the first or second line of the source " -"file::" -msgstr "" - -#: ../../howto/unicode.rst:339 -msgid "" -"#!/usr/bin/env python\n" -"# -*- coding: latin-1 -*-\n" -"\n" -"u = 'abcdé'\n" -"print(ord(u[-1]))" -msgstr "" -"#!/usr/bin/env python\n" -"# -*- coding: latin-1 -*-\n" -"\n" -"u = 'abcdé'\n" -"print(ord(u[-1]))" - -#: ../../howto/unicode.rst:345 -msgid "" -"The syntax is inspired by Emacs's notation for specifying variables local to " -"a file. Emacs supports many different variables, but Python only supports " -"'coding'. The ``-*-`` symbols indicate to Emacs that the comment is " -"special; they have no significance to Python but are a convention. Python " -"looks for ``coding: name`` or ``coding=name`` in the comment." -msgstr "" - -#: ../../howto/unicode.rst:351 -msgid "" -"If you don't include such a comment, the default encoding used will be UTF-8 " -"as already mentioned. See also :pep:`263` for more information." -msgstr "" - -#: ../../howto/unicode.rst:358 -msgid "Unicode Properties" -msgstr "" - -#: ../../howto/unicode.rst:360 -msgid "" -"The Unicode specification includes a database of information about code " -"points. For each defined code point, the information includes the " -"character's name, its category, the numeric value if applicable (for " -"characters representing numeric concepts such as the Roman numerals, " -"fractions such as one-third and four-fifths, etc.). There are also display-" -"related properties, such as how to use the code point in bidirectional text." -msgstr "" - -#: ../../howto/unicode.rst:368 -msgid "" -"The following program displays some information about several characters, " -"and prints the numeric value of one particular character::" -msgstr "" - -#: ../../howto/unicode.rst:371 -msgid "" -"import unicodedata\n" -"\n" -"u = chr(233) + chr(0x0bf2) + chr(3972) + chr(6000) + chr(13231)\n" -"\n" -"for i, c in enumerate(u):\n" -" print(i, '%04x' % ord(c), unicodedata.category(c), end=\" \")\n" -" print(unicodedata.name(c))\n" -"\n" -"# Get numeric value of second character\n" -"print(unicodedata.numeric(u[1]))" -msgstr "" - -#: ../../howto/unicode.rst:382 -msgid "When run, this prints:" -msgstr "" - -#: ../../howto/unicode.rst:384 -msgid "" -"0 00e9 Ll LATIN SMALL LETTER E WITH ACUTE\n" -"1 0bf2 No TAMIL NUMBER ONE THOUSAND\n" -"2 0f84 Mn TIBETAN MARK HALANTA\n" -"3 1770 Lo TAGBANWA LETTER SA\n" -"4 33af So SQUARE RAD OVER S SQUARED\n" -"1000.0" -msgstr "" -"0 00e9 Ll LATIN SMALL LETTER E WITH ACUTE\n" -"1 0bf2 No TAMIL NUMBER ONE THOUSAND\n" -"2 0f84 Mn TIBETAN MARK HALANTA\n" -"3 1770 Lo TAGBANWA LETTER SA\n" -"4 33af So SQUARE RAD OVER S SQUARED\n" -"1000.0" - -#: ../../howto/unicode.rst:393 -msgid "" -"The category codes are abbreviations describing the nature of the character. " -"These are grouped into categories such as \"Letter\", \"Number\", " -"\"Punctuation\", or \"Symbol\", which in turn are broken up into " -"subcategories. To take the codes from the above output, ``'Ll'`` means " -"'Letter, lowercase', ``'No'`` means \"Number, other\", ``'Mn'`` is \"Mark, " -"nonspacing\", and ``'So'`` is \"Symbol, other\". See `the General Category " -"Values section of the Unicode Character Database documentation `_ for a list of category " -"codes." -msgstr "" - -#: ../../howto/unicode.rst:404 -msgid "Comparing Strings" -msgstr "" - -#: ../../howto/unicode.rst:406 -msgid "" -"Unicode adds some complication to comparing strings, because the same set of " -"characters can be represented by different sequences of code points. For " -"example, a letter like 'ê' can be represented as a single code point U+00EA, " -"or as U+0065 U+0302, which is the code point for 'e' followed by a code " -"point for 'COMBINING CIRCUMFLEX ACCENT'. These will produce the same output " -"when printed, but one is a string of length 1 and the other is of length 2." -msgstr "" - -#: ../../howto/unicode.rst:414 -msgid "" -"One tool for a case-insensitive comparison is the :meth:`~str.casefold` " -"string method that converts a string to a case-insensitive form following an " -"algorithm described by the Unicode Standard. This algorithm has special " -"handling for characters such as the German letter 'ß' (code point U+00DF), " -"which becomes the pair of lowercase letters 'ss'." -msgstr "" - -#: ../../howto/unicode.rst:423 -msgid "" -">>> street = 'Gürzenichstraße'\n" -">>> street.casefold()\n" -"'gürzenichstrasse'" -msgstr "" -">>> street = 'Gürzenichstraße'\n" -">>> street.casefold()\n" -"'gürzenichstrasse'" - -#: ../../howto/unicode.rst:427 -msgid "" -"A second tool is the :mod:`unicodedata` module's :func:`~unicodedata." -"normalize` function that converts strings to one of several normal forms, " -"where letters followed by a combining character are replaced with single " -"characters. :func:`~unicodedata.normalize` can be used to perform string " -"comparisons that won't falsely report inequality if two strings use " -"combining characters differently:" -msgstr "" - -#: ../../howto/unicode.rst:436 -msgid "" -"import unicodedata\n" -"\n" -"def compare_strs(s1, s2):\n" -" def NFD(s):\n" -" return unicodedata.normalize('NFD', s)\n" -"\n" -" return NFD(s1) == NFD(s2)\n" -"\n" -"single_char = 'ê'\n" -"multiple_chars = '\\N{LATIN SMALL LETTER E}\\N{COMBINING CIRCUMFLEX " -"ACCENT}'\n" -"print('length of first string=', len(single_char))\n" -"print('length of second string=', len(multiple_chars))\n" -"print(compare_strs(single_char, multiple_chars))" -msgstr "" -"import unicodedata\n" -"\n" -"def compare_strs(s1, s2):\n" -" def NFD(s):\n" -" return unicodedata.normalize('NFD', s)\n" -"\n" -" return NFD(s1) == NFD(s2)\n" -"\n" -"single_char = 'ê'\n" -"multiple_chars = '\\N{LATIN SMALL LETTER E}\\N{COMBINING CIRCUMFLEX " -"ACCENT}'\n" -"print('length of first string=', len(single_char))\n" -"print('length of second string=', len(multiple_chars))\n" -"print(compare_strs(single_char, multiple_chars))" - -#: ../../howto/unicode.rst:450 -msgid "When run, this outputs:" -msgstr "" - -#: ../../howto/unicode.rst:452 -msgid "" -"$ python compare-strs.py\n" -"length of first string= 1\n" -"length of second string= 2\n" -"True" -msgstr "" -"$ python compare-strs.py\n" -"length of first string= 1\n" -"length of second string= 2\n" -"True" - -#: ../../howto/unicode.rst:459 -msgid "" -"The first argument to the :func:`~unicodedata.normalize` function is a " -"string giving the desired normalization form, which can be one of 'NFC', " -"'NFKC', 'NFD', and 'NFKD'." -msgstr "" - -#: ../../howto/unicode.rst:463 -msgid "The Unicode Standard also specifies how to do caseless comparisons::" -msgstr "" - -#: ../../howto/unicode.rst:465 -msgid "" -"import unicodedata\n" -"\n" -"def compare_caseless(s1, s2):\n" -" def NFD(s):\n" -" return unicodedata.normalize('NFD', s)\n" -"\n" -" return NFD(NFD(s1).casefold()) == NFD(NFD(s2).casefold())\n" -"\n" -"# Example usage\n" -"single_char = 'ê'\n" -"multiple_chars = '\\N{LATIN CAPITAL LETTER E}\\N{COMBINING CIRCUMFLEX " -"ACCENT}'\n" -"\n" -"print(compare_caseless(single_char, multiple_chars))" -msgstr "" - -#: ../../howto/unicode.rst:479 -msgid "" -"This will print ``True``. (Why is :func:`!NFD` invoked twice? Because " -"there are a few characters that make :meth:`~str.casefold` return a non-" -"normalized string, so the result needs to be normalized again. See section " -"3.13 of the Unicode Standard for a discussion and an example.)" -msgstr "" - -#: ../../howto/unicode.rst:486 -msgid "Unicode Regular Expressions" -msgstr "" - -#: ../../howto/unicode.rst:488 -msgid "" -"The regular expressions supported by the :mod:`re` module can be provided " -"either as bytes or strings. Some of the special character sequences such as " -"``\\d`` and ``\\w`` have different meanings depending on whether the pattern " -"is supplied as bytes or a string. For example, ``\\d`` will match the " -"characters ``[0-9]`` in bytes but in strings will match any character that's " -"in the ``'Nd'`` category." -msgstr "" - -#: ../../howto/unicode.rst:495 -msgid "" -"The string in this example has the number 57 written in both Thai and Arabic " -"numerals::" -msgstr "" - -#: ../../howto/unicode.rst:498 -msgid "" -"import re\n" -"p = re.compile(r'\\d+')\n" -"\n" -"s = \"Over \\u0e55\\u0e57 57 flavours\"\n" -"m = p.search(s)\n" -"print(repr(m.group()))" -msgstr "" -"import re\n" -"p = re.compile(r'\\d+')\n" -"\n" -"s = \"Over \\u0e55\\u0e57 57 flavours\"\n" -"m = p.search(s)\n" -"print(repr(m.group()))" - -#: ../../howto/unicode.rst:505 -msgid "" -"When executed, ``\\d+`` will match the Thai numerals and print them out. If " -"you supply the :const:`re.ASCII` flag to :func:`~re.compile`, ``\\d+`` will " -"match the substring \"57\" instead." -msgstr "" - -#: ../../howto/unicode.rst:509 -msgid "" -"Similarly, ``\\w`` matches a wide variety of Unicode characters but only " -"``[a-zA-Z0-9_]`` in bytes or if :const:`re.ASCII` is supplied, and ``\\s`` " -"will match either Unicode whitespace characters or ``[ \\t\\n\\r\\f\\v]``." -msgstr "" - -#: ../../howto/unicode.rst:520 -msgid "Some good alternative discussions of Python's Unicode support are:" -msgstr "" - -#: ../../howto/unicode.rst:522 -msgid "" -"`Processing Text Files in Python 3 `_, by Nick Coghlan." -msgstr "" - -#: ../../howto/unicode.rst:523 -msgid "" -"`Pragmatic Unicode `_, a PyCon " -"2012 presentation by Ned Batchelder." -msgstr "" - -#: ../../howto/unicode.rst:525 -msgid "" -"The :class:`str` type is described in the Python library reference at :ref:" -"`textseq`." -msgstr "" - -#: ../../howto/unicode.rst:528 -msgid "The documentation for the :mod:`unicodedata` module." -msgstr ":mod:`unicodedata` 模組的文件。" - -#: ../../howto/unicode.rst:530 -msgid "The documentation for the :mod:`codecs` module." -msgstr ":mod:`codecs` 模組的文件。" - -#: ../../howto/unicode.rst:532 -msgid "" -"Marc-André Lemburg gave `a presentation titled \"Python and Unicode\" (PDF " -"slides) `_ at " -"EuroPython 2002. The slides are an excellent overview of the design of " -"Python 2's Unicode features (where the Unicode string type is called " -"``unicode`` and literals start with ``u``)." -msgstr "" - -#: ../../howto/unicode.rst:540 -msgid "Reading and Writing Unicode Data" -msgstr "" - -#: ../../howto/unicode.rst:542 -msgid "" -"Once you've written some code that works with Unicode data, the next problem " -"is input/output. How do you get Unicode strings into your program, and how " -"do you convert Unicode into a form suitable for storage or transmission?" -msgstr "" - -#: ../../howto/unicode.rst:546 -msgid "" -"It's possible that you may not need to do anything depending on your input " -"sources and output destinations; you should check whether the libraries used " -"in your application support Unicode natively. XML parsers often return " -"Unicode data, for example. Many relational databases also support Unicode-" -"valued columns and can return Unicode values from an SQL query." -msgstr "" - -#: ../../howto/unicode.rst:552 -msgid "" -"Unicode data is usually converted to a particular encoding before it gets " -"written to disk or sent over a socket. It's possible to do all the work " -"yourself: open a file, read an 8-bit bytes object from it, and convert the " -"bytes with ``bytes.decode(encoding)``. However, the manual approach is not " -"recommended." -msgstr "" - -#: ../../howto/unicode.rst:557 -msgid "" -"One problem is the multi-byte nature of encodings; one Unicode character can " -"be represented by several bytes. If you want to read the file in arbitrary-" -"sized chunks (say, 1024 or 4096 bytes), you need to write error-handling " -"code to catch the case where only part of the bytes encoding a single " -"Unicode character are read at the end of a chunk. One solution would be to " -"read the entire file into memory and then perform the decoding, but that " -"prevents you from working with files that are extremely large; if you need " -"to read a 2 GiB file, you need 2 GiB of RAM. (More, really, since for at " -"least a moment you'd need to have both the encoded string and its Unicode " -"version in memory.)" -msgstr "" - -#: ../../howto/unicode.rst:567 -msgid "" -"The solution would be to use the low-level decoding interface to catch the " -"case of partial coding sequences. The work of implementing this has already " -"been done for you: the built-in :func:`open` function can return a file-like " -"object that assumes the file's contents are in a specified encoding and " -"accepts Unicode parameters for methods such as :meth:`~io.TextIOBase.read` " -"and :meth:`~io.TextIOBase.write`. This works through :func:`open`\\'s " -"*encoding* and *errors* parameters which are interpreted just like those in :" -"meth:`str.encode` and :meth:`bytes.decode`." -msgstr "" - -#: ../../howto/unicode.rst:576 -msgid "Reading Unicode from a file is therefore simple::" -msgstr "" - -#: ../../howto/unicode.rst:578 -msgid "" -"with open('unicode.txt', encoding='utf-8') as f:\n" -" for line in f:\n" -" print(repr(line))" -msgstr "" -"with open('unicode.txt', encoding='utf-8') as f:\n" -" for line in f:\n" -" print(repr(line))" - -#: ../../howto/unicode.rst:582 -msgid "" -"It's also possible to open files in update mode, allowing both reading and " -"writing::" -msgstr "" - -#: ../../howto/unicode.rst:585 -msgid "" -"with open('test', encoding='utf-8', mode='w+') as f:\n" -" f.write('\\u4500 blah blah blah\\n')\n" -" f.seek(0)\n" -" print(repr(f.readline()[:1]))" -msgstr "" -"with open('test', encoding='utf-8', mode='w+') as f:\n" -" f.write('\\u4500 blah blah blah\\n')\n" -" f.seek(0)\n" -" print(repr(f.readline()[:1]))" - -#: ../../howto/unicode.rst:590 -msgid "" -"The Unicode character ``U+FEFF`` is used as a byte-order mark (BOM), and is " -"often written as the first character of a file in order to assist with " -"autodetection of the file's byte ordering. Some encodings, such as UTF-16, " -"expect a BOM to be present at the start of a file; when such an encoding is " -"used, the BOM will be automatically written as the first character and will " -"be silently dropped when the file is read. There are variants of these " -"encodings, such as 'utf-16-le' and 'utf-16-be' for little-endian and big-" -"endian encodings, that specify one particular byte ordering and don't skip " -"the BOM." -msgstr "" - -#: ../../howto/unicode.rst:599 -msgid "" -"In some areas, it is also convention to use a \"BOM\" at the start of UTF-8 " -"encoded files; the name is misleading since UTF-8 is not byte-order " -"dependent. The mark simply announces that the file is encoded in UTF-8. For " -"reading such files, use the 'utf-8-sig' codec to automatically skip the mark " -"if present." -msgstr "" - -#: ../../howto/unicode.rst:606 -msgid "Unicode filenames" -msgstr "" - -#: ../../howto/unicode.rst:608 -msgid "" -"Most of the operating systems in common use today support filenames that " -"contain arbitrary Unicode characters. Usually this is implemented by " -"converting the Unicode string into some encoding that varies depending on " -"the system. Today Python is converging on using UTF-8: Python on MacOS has " -"used UTF-8 for several versions, and Python 3.6 switched to using UTF-8 on " -"Windows as well. On Unix systems, there will only be a :term:`filesystem " -"encoding `. if you've set the " -"``LANG`` or ``LC_CTYPE`` environment variables; if you haven't, the default " -"encoding is again UTF-8." -msgstr "" - -#: ../../howto/unicode.rst:618 -msgid "" -"The :func:`sys.getfilesystemencoding` function returns the encoding to use " -"on your current system, in case you want to do the encoding manually, but " -"there's not much reason to bother. When opening a file for reading or " -"writing, you can usually just provide the Unicode string as the filename, " -"and it will be automatically converted to the right encoding for you::" -msgstr "" - -#: ../../howto/unicode.rst:624 -msgid "" -"filename = 'filename\\u4500abc'\n" -"with open(filename, 'w') as f:\n" -" f.write('blah\\n')" -msgstr "" -"filename = 'filename\\u4500abc'\n" -"with open(filename, 'w') as f:\n" -" f.write('blah\\n')" - -#: ../../howto/unicode.rst:628 -msgid "" -"Functions in the :mod:`os` module such as :func:`os.stat` will also accept " -"Unicode filenames." -msgstr "" - -#: ../../howto/unicode.rst:631 -msgid "" -"The :func:`os.listdir` function returns filenames, which raises an issue: " -"should it return the Unicode version of filenames, or should it return bytes " -"containing the encoded versions? :func:`os.listdir` can do both, depending " -"on whether you provided the directory path as bytes or a Unicode string. If " -"you pass a Unicode string as the path, filenames will be decoded using the " -"filesystem's encoding and a list of Unicode strings will be returned, while " -"passing a byte path will return the filenames as bytes. For example, " -"assuming the default :term:`filesystem encoding ` is UTF-8, running the following program::" -msgstr "" - -#: ../../howto/unicode.rst:641 -msgid "" -"fn = 'filename\\u4500abc'\n" -"f = open(fn, 'w')\n" -"f.close()\n" -"\n" -"import os\n" -"print(os.listdir(b'.'))\n" -"print(os.listdir('.'))" -msgstr "" -"fn = 'filename\\u4500abc'\n" -"f = open(fn, 'w')\n" -"f.close()\n" -"\n" -"import os\n" -"print(os.listdir(b'.'))\n" -"print(os.listdir('.'))" - -#: ../../howto/unicode.rst:649 -msgid "will produce the following output:" -msgstr "" - -#: ../../howto/unicode.rst:651 -msgid "" -"$ python listdir-test.py\n" -"[b'filename\\xe4\\x94\\x80abc', ...]\n" -"['filename\\u4500abc', ...]" -msgstr "" -"$ python listdir-test.py\n" -"[b'filename\\xe4\\x94\\x80abc', ...]\n" -"['filename\\u4500abc', ...]" - -#: ../../howto/unicode.rst:657 -msgid "" -"The first list contains UTF-8-encoded filenames, and the second list " -"contains the Unicode versions." -msgstr "" - -#: ../../howto/unicode.rst:660 -msgid "" -"Note that on most occasions, you should can just stick with using Unicode " -"with these APIs. The bytes APIs should only be used on systems where " -"undecodable file names can be present; that's pretty much only Unix systems " -"now." -msgstr "" - -#: ../../howto/unicode.rst:667 -msgid "Tips for Writing Unicode-aware Programs" -msgstr "" - -#: ../../howto/unicode.rst:669 -msgid "" -"This section provides some suggestions on writing software that deals with " -"Unicode." -msgstr "" - -#: ../../howto/unicode.rst:672 -msgid "The most important tip is:" -msgstr "" - -#: ../../howto/unicode.rst:674 -msgid "" -"Software should only work with Unicode strings internally, decoding the " -"input data as soon as possible and encoding the output only at the end." -msgstr "" - -#: ../../howto/unicode.rst:677 -msgid "" -"If you attempt to write processing functions that accept both Unicode and " -"byte strings, you will find your program vulnerable to bugs wherever you " -"combine the two different kinds of strings. There is no automatic encoding " -"or decoding: if you do e.g. ``str + bytes``, a :exc:`TypeError` will be " -"raised." -msgstr "" - -#: ../../howto/unicode.rst:682 -msgid "" -"When using data coming from a web browser or some other untrusted source, a " -"common technique is to check for illegal characters in a string before using " -"the string in a generated command line or storing it in a database. If " -"you're doing this, be careful to check the decoded string, not the encoded " -"bytes data; some encodings may have interesting properties, such as not " -"being bijective or not being fully ASCII-compatible. This is especially " -"true if the input data also specifies the encoding, since the attacker can " -"then choose a clever way to hide malicious text in the encoded bytestream." -msgstr "" - -#: ../../howto/unicode.rst:693 -msgid "Converting Between File Encodings" -msgstr "" - -#: ../../howto/unicode.rst:695 -msgid "" -"The :class:`~codecs.StreamRecoder` class can transparently convert between " -"encodings, taking a stream that returns data in encoding #1 and behaving " -"like a stream returning data in encoding #2." -msgstr "" - -#: ../../howto/unicode.rst:699 -msgid "" -"For example, if you have an input file *f* that's in Latin-1, you can wrap " -"it with a :class:`~codecs.StreamRecoder` to return bytes encoded in UTF-8::" -msgstr "" - -#: ../../howto/unicode.rst:703 -msgid "" -"new_f = codecs.StreamRecoder(f,\n" -" # en/decoder: used by read() to encode its results and\n" -" # by write() to decode its input.\n" -" codecs.getencoder('utf-8'), codecs.getdecoder('utf-8'),\n" -"\n" -" # reader/writer: used to read and write to the stream.\n" -" codecs.getreader('latin-1'), codecs.getwriter('latin-1') )" -msgstr "" - -#: ../../howto/unicode.rst:713 -msgid "Files in an Unknown Encoding" -msgstr "" - -#: ../../howto/unicode.rst:715 -msgid "" -"What can you do if you need to make a change to a file, but don't know the " -"file's encoding? If you know the encoding is ASCII-compatible and only want " -"to examine or modify the ASCII parts, you can open the file with the " -"``surrogateescape`` error handler::" -msgstr "" - -#: ../../howto/unicode.rst:720 -msgid "" -"with open(fname, 'r', encoding=\"ascii\", errors=\"surrogateescape\") as f:\n" -" data = f.read()\n" -"\n" -"# make changes to the string 'data'\n" -"\n" -"with open(fname + '.new', 'w',\n" -" encoding=\"ascii\", errors=\"surrogateescape\") as f:\n" -" f.write(data)" -msgstr "" -"with open(fname, 'r', encoding=\"ascii\", errors=\"surrogateescape\") as f:\n" -" data = f.read()\n" -"\n" -"# make changes to the string 'data'\n" -"\n" -"with open(fname + '.new', 'w',\n" -" encoding=\"ascii\", errors=\"surrogateescape\") as f:\n" -" f.write(data)" - -#: ../../howto/unicode.rst:729 -msgid "" -"The ``surrogateescape`` error handler will decode any non-ASCII bytes as " -"code points in a special range running from U+DC80 to U+DCFF. These code " -"points will then turn back into the same bytes when the ``surrogateescape`` " -"error handler is used to encode the data and write it back out." -msgstr "" - -#: ../../howto/unicode.rst:739 -msgid "" -"One section of `Mastering Python 3 Input/Output `_, a PyCon 2010 talk by David " -"Beazley, discusses text processing and binary data handling." -msgstr "" - -#: ../../howto/unicode.rst:743 -msgid "" -"The `PDF slides for Marc-André Lemburg's presentation \"Writing Unicode-" -"aware Applications in Python\" `_ discuss questions of " -"character encodings as well as how to internationalize and localize an " -"application. These slides cover Python 2.x only." -msgstr "" - -#: ../../howto/unicode.rst:749 -msgid "" -"`The Guts of Unicode in Python `_ is a PyCon 2013 talk by Benjamin Peterson that " -"discusses the internal Unicode representation in Python 3.3." -msgstr "" - -#: ../../howto/unicode.rst:756 -msgid "Acknowledgements" -msgstr "致謝" - -#: ../../howto/unicode.rst:758 -msgid "" -"The initial draft of this document was written by Andrew Kuchling. It has " -"since been revised further by Alexander Belopolsky, Georg Brandl, Andrew " -"Kuchling, and Ezio Melotti." -msgstr "" - -#: ../../howto/unicode.rst:762 -msgid "" -"Thanks to the following people who have noted errors or offered suggestions " -"on this article: Éric Araujo, Nicholas Bastin, Nick Coghlan, Marius " -"Gedminas, Kent Johnson, Ken Krugler, Marc-André Lemburg, Martin von Löwis, " -"Terry J. Reedy, Serhiy Storchaka, Eryk Sun, Chad Whitacre, Graham Wideman." -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-25 00:13+0000\n" +"PO-Revision-Date: 2018-05-23 14:37+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" + +#: ../../howto/unicode.rst:5 +msgid "Unicode HOWTO" +msgstr "" + +#: ../../howto/unicode.rst:0 +msgid "Release" +msgstr "發佈版本" + +#: ../../howto/unicode.rst:7 +msgid "1.12" +msgstr "1.12" + +#: ../../howto/unicode.rst:9 +msgid "" +"This HOWTO discusses Python's support for the Unicode specification for " +"representing textual data, and explains various problems that people " +"commonly encounter when trying to work with Unicode." +msgstr "" + +#: ../../howto/unicode.rst:15 +msgid "Introduction to Unicode" +msgstr "" + +#: ../../howto/unicode.rst:18 +msgid "Definitions" +msgstr "定義" + +#: ../../howto/unicode.rst:20 +msgid "" +"Today's programs need to be able to handle a wide variety of characters. " +"Applications are often internationalized to display messages and output in a " +"variety of user-selectable languages; the same program might need to output " +"an error message in English, French, Japanese, Hebrew, or Russian. Web " +"content can be written in any of these languages and can also include a " +"variety of emoji symbols. Python's string type uses the Unicode Standard for " +"representing characters, which lets Python programs work with all these " +"different possible characters." +msgstr "" + +#: ../../howto/unicode.rst:30 +msgid "" +"Unicode (https://www.unicode.org/) is a specification that aims to list " +"every character used by human languages and give each character its own " +"unique code. The Unicode specifications are continually revised and updated " +"to add new languages and symbols." +msgstr "" + +#: ../../howto/unicode.rst:35 +msgid "" +"A **character** is the smallest possible component of a text. 'A', 'B', " +"'C', etc., are all different characters. So are 'È' and 'Í'. Characters " +"vary depending on the language or context you're talking about. For " +"example, there's a character for \"Roman Numeral One\", 'Ⅰ', that's separate " +"from the uppercase letter 'I'. They'll usually look the same, but these are " +"two different characters that have different meanings." +msgstr "" + +#: ../../howto/unicode.rst:42 +msgid "" +"The Unicode standard describes how characters are represented by **code " +"points**. A code point value is an integer in the range 0 to 0x10FFFF " +"(about 1.1 million values, the `actual number assigned `_ is less than that). In the standard and in " +"this document, a code point is written using the notation ``U+265E`` to mean " +"the character with value ``0x265e`` (9,822 in decimal)." +msgstr "" + +#: ../../howto/unicode.rst:50 +msgid "" +"The Unicode standard contains a lot of tables listing characters and their " +"corresponding code points:" +msgstr "" + +#: ../../howto/unicode.rst:53 +msgid "" +"0061 'a'; LATIN SMALL LETTER A\n" +"0062 'b'; LATIN SMALL LETTER B\n" +"0063 'c'; LATIN SMALL LETTER C\n" +"...\n" +"007B '{'; LEFT CURLY BRACKET\n" +"...\n" +"2167 'Ⅷ'; ROMAN NUMERAL EIGHT\n" +"2168 'Ⅸ'; ROMAN NUMERAL NINE\n" +"...\n" +"265E '♞'; BLACK CHESS KNIGHT\n" +"265F '♟'; BLACK CHESS PAWN\n" +"...\n" +"1F600 '😀'; GRINNING FACE\n" +"1F609 '😉'; WINKING FACE\n" +"..." +msgstr "" +"0061 'a'; LATIN SMALL LETTER A\n" +"0062 'b'; LATIN SMALL LETTER B\n" +"0063 'c'; LATIN SMALL LETTER C\n" +"...\n" +"007B '{'; LEFT CURLY BRACKET\n" +"...\n" +"2167 'Ⅷ'; ROMAN NUMERAL EIGHT\n" +"2168 'Ⅸ'; ROMAN NUMERAL NINE\n" +"...\n" +"265E '♞'; BLACK CHESS KNIGHT\n" +"265F '♟'; BLACK CHESS PAWN\n" +"...\n" +"1F600 '😀'; GRINNING FACE\n" +"1F609 '😉'; WINKING FACE\n" +"..." + +#: ../../howto/unicode.rst:71 +msgid "" +"Strictly, these definitions imply that it's meaningless to say 'this is " +"character ``U+265E``'. ``U+265E`` is a code point, which represents some " +"particular character; in this case, it represents the character 'BLACK CHESS " +"KNIGHT', '♞'. In informal contexts, this distinction between code points " +"and characters will sometimes be forgotten." +msgstr "" + +#: ../../howto/unicode.rst:78 +msgid "" +"A character is represented on a screen or on paper by a set of graphical " +"elements that's called a **glyph**. The glyph for an uppercase A, for " +"example, is two diagonal strokes and a horizontal stroke, though the exact " +"details will depend on the font being used. Most Python code doesn't need " +"to worry about glyphs; figuring out the correct glyph to display is " +"generally the job of a GUI toolkit or a terminal's font renderer." +msgstr "" + +#: ../../howto/unicode.rst:87 +msgid "Encodings" +msgstr "" + +#: ../../howto/unicode.rst:89 +msgid "" +"To summarize the previous section: a Unicode string is a sequence of code " +"points, which are numbers from 0 through ``0x10FFFF`` (1,114,111 decimal). " +"This sequence of code points needs to be represented in memory as a set of " +"**code units**, and **code units** are then mapped to 8-bit bytes. The " +"rules for translating a Unicode string into a sequence of bytes are called a " +"**character encoding**, or just an **encoding**." +msgstr "" + +#: ../../howto/unicode.rst:97 +msgid "" +"The first encoding you might think of is using 32-bit integers as the code " +"unit, and then using the CPU's representation of 32-bit integers. In this " +"representation, the string \"Python\" might look like this:" +msgstr "" + +#: ../../howto/unicode.rst:101 +msgid "" +" P y t h o n\n" +"0x50 00 00 00 79 00 00 00 74 00 00 00 68 00 00 00 6f 00 00 00 6e 00 00 00\n" +" 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23" +msgstr "" +" P y t h o n\n" +"0x50 00 00 00 79 00 00 00 74 00 00 00 68 00 00 00 6f 00 00 00 6e 00 00 00\n" +" 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23" + +#: ../../howto/unicode.rst:107 +msgid "" +"This representation is straightforward but using it presents a number of " +"problems." +msgstr "" + +#: ../../howto/unicode.rst:110 +msgid "It's not portable; different processors order the bytes differently." +msgstr "" + +#: ../../howto/unicode.rst:112 +msgid "" +"It's very wasteful of space. In most texts, the majority of the code points " +"are less than 127, or less than 255, so a lot of space is occupied by " +"``0x00`` bytes. The above string takes 24 bytes compared to the 6 bytes " +"needed for an ASCII representation. Increased RAM usage doesn't matter too " +"much (desktop computers have gigabytes of RAM, and strings aren't usually " +"that large), but expanding our usage of disk and network bandwidth by a " +"factor of 4 is intolerable." +msgstr "" + +#: ../../howto/unicode.rst:120 +msgid "" +"It's not compatible with existing C functions such as ``strlen()``, so a new " +"family of wide string functions would need to be used." +msgstr "" + +#: ../../howto/unicode.rst:123 +msgid "" +"Therefore this encoding isn't used very much, and people instead choose " +"other encodings that are more efficient and convenient, such as UTF-8." +msgstr "" + +#: ../../howto/unicode.rst:126 +msgid "" +"UTF-8 is one of the most commonly used encodings, and Python often defaults " +"to using it. UTF stands for \"Unicode Transformation Format\", and the '8' " +"means that 8-bit values are used in the encoding. (There are also UTF-16 " +"and UTF-32 encodings, but they are less frequently used than UTF-8.) UTF-8 " +"uses the following rules:" +msgstr "" + +#: ../../howto/unicode.rst:132 +msgid "" +"If the code point is < 128, it's represented by the corresponding byte value." +msgstr "" + +#: ../../howto/unicode.rst:133 +msgid "" +"If the code point is >= 128, it's turned into a sequence of two, three, or " +"four bytes, where each byte of the sequence is between 128 and 255." +msgstr "" + +#: ../../howto/unicode.rst:136 +msgid "UTF-8 has several convenient properties:" +msgstr "" + +#: ../../howto/unicode.rst:138 +msgid "It can handle any Unicode code point." +msgstr "" + +#: ../../howto/unicode.rst:139 +msgid "" +"A Unicode string is turned into a sequence of bytes that contains embedded " +"zero bytes only where they represent the null character (U+0000). This means " +"that UTF-8 strings can be processed by C functions such as ``strcpy()`` and " +"sent through protocols that can't handle zero bytes for anything other than " +"end-of-string markers." +msgstr "" + +#: ../../howto/unicode.rst:144 +msgid "A string of ASCII text is also valid UTF-8 text." +msgstr "" + +#: ../../howto/unicode.rst:145 +msgid "" +"UTF-8 is fairly compact; the majority of commonly used characters can be " +"represented with one or two bytes." +msgstr "" + +#: ../../howto/unicode.rst:147 +msgid "" +"If bytes are corrupted or lost, it's possible to determine the start of the " +"next UTF-8-encoded code point and resynchronize. It's also unlikely that " +"random 8-bit data will look like valid UTF-8." +msgstr "" + +#: ../../howto/unicode.rst:150 +msgid "" +"UTF-8 is a byte oriented encoding. The encoding specifies that each " +"character is represented by a specific sequence of one or more bytes. This " +"avoids the byte-ordering issues that can occur with integer and word " +"oriented encodings, like UTF-16 and UTF-32, where the sequence of bytes " +"varies depending on the hardware on which the string was encoded." +msgstr "" + +#: ../../howto/unicode.rst:158 ../../howto/unicode.rst:516 +#: ../../howto/unicode.rst:737 +msgid "References" +msgstr "" + +#: ../../howto/unicode.rst:160 +msgid "" +"The `Unicode Consortium site `_ has character " +"charts, a glossary, and PDF versions of the Unicode specification. Be " +"prepared for some difficult reading. `A chronology `_ of the origin and development of Unicode is also available on " +"the site." +msgstr "" + +#: ../../howto/unicode.rst:165 +msgid "" +"On the Computerphile Youtube channel, Tom Scott briefly `discusses the " +"history of Unicode and UTF-8 `_ " +"(9 minutes 36 seconds)." +msgstr "" + +#: ../../howto/unicode.rst:169 +msgid "" +"To help understand the standard, Jukka Korpela has written `an introductory " +"guide `_ to reading the Unicode " +"character tables." +msgstr "" + +#: ../../howto/unicode.rst:173 +msgid "" +"Another `good introductory article `_ was " +"written by Joel Spolsky. If this introduction didn't make things clear to " +"you, you should try reading this alternate article before continuing." +msgstr "" + +#: ../../howto/unicode.rst:178 +msgid "" +"Wikipedia entries are often helpful; see the entries for \"`character " +"encoding `_\" and `UTF-8 " +"`_, for example." +msgstr "" + +#: ../../howto/unicode.rst:184 +msgid "Python's Unicode Support" +msgstr "" + +#: ../../howto/unicode.rst:186 +msgid "" +"Now that you've learned the rudiments of Unicode, we can look at Python's " +"Unicode features." +msgstr "" + +#: ../../howto/unicode.rst:190 +msgid "The String Type" +msgstr "" + +#: ../../howto/unicode.rst:192 +msgid "" +"Since Python 3.0, the language's :class:`str` type contains Unicode " +"characters, meaning any string created using ``\"unicode rocks!\"``, " +"``'unicode rocks!'``, or the triple-quoted string syntax is stored as " +"Unicode." +msgstr "" + +#: ../../howto/unicode.rst:196 +msgid "" +"The default encoding for Python source code is UTF-8, so you can simply " +"include a Unicode character in a string literal::" +msgstr "" + +#: ../../howto/unicode.rst:199 +msgid "" +"try:\n" +" with open('/tmp/input.txt', 'r') as f:\n" +" ...\n" +"except OSError:\n" +" # 'File not found' error message.\n" +" print(\"Fichier non trouvé\")" +msgstr "" + +#: ../../howto/unicode.rst:206 +msgid "" +"Side note: Python 3 also supports using Unicode characters in identifiers::" +msgstr "" + +#: ../../howto/unicode.rst:208 +msgid "" +"répertoire = \"/tmp/records.log\"\n" +"with open(répertoire, \"w\") as f:\n" +" f.write(\"test\\n\")" +msgstr "" +"répertoire = \"/tmp/records.log\"\n" +"with open(répertoire, \"w\") as f:\n" +" f.write(\"test\\n\")" + +#: ../../howto/unicode.rst:212 +msgid "" +"If you can't enter a particular character in your editor or want to keep the " +"source code ASCII-only for some reason, you can also use escape sequences in " +"string literals. (Depending on your system, you may see the actual capital-" +"delta glyph instead of a \\u escape.) ::" +msgstr "" + +#: ../../howto/unicode.rst:217 +msgid "" +">>> \"\\N{GREEK CAPITAL LETTER DELTA}\" # Using the character name\n" +"'\\u0394'\n" +">>> \"\\u0394\" # Using a 16-bit hex value\n" +"'\\u0394'\n" +">>> \"\\U00000394\" # Using a 32-bit hex value\n" +"'\\u0394'" +msgstr "" + +#: ../../howto/unicode.rst:224 +msgid "" +"In addition, one can create a string using the :func:`~bytes.decode` method " +"of :class:`bytes`. This method takes an *encoding* argument, such as " +"``UTF-8``, and optionally an *errors* argument." +msgstr "" + +#: ../../howto/unicode.rst:228 +msgid "" +"The *errors* argument specifies the response when the input string can't be " +"converted according to the encoding's rules. Legal values for this argument " +"are ``'strict'`` (raise a :exc:`UnicodeDecodeError` exception), " +"``'replace'`` (use ``U+FFFD``, ``REPLACEMENT CHARACTER``), ``'ignore'`` " +"(just leave the character out of the Unicode result), or " +"``'backslashreplace'`` (inserts a ``\\xNN`` escape sequence). The following " +"examples show the differences::" +msgstr "" + +#: ../../howto/unicode.rst:236 +msgid "" +">>> b'\\x80abc'.decode(\"utf-8\", \"strict\")\n" +"Traceback (most recent call last):\n" +" ...\n" +"UnicodeDecodeError: 'utf-8' codec can't decode byte 0x80 in position 0:\n" +" invalid start byte\n" +">>> b'\\x80abc'.decode(\"utf-8\", \"replace\")\n" +"'\\ufffdabc'\n" +">>> b'\\x80abc'.decode(\"utf-8\", \"backslashreplace\")\n" +"'\\\\x80abc'\n" +">>> b'\\x80abc'.decode(\"utf-8\", \"ignore\")\n" +"'abc'" +msgstr "" +">>> b'\\x80abc'.decode(\"utf-8\", \"strict\")\n" +"Traceback (most recent call last):\n" +" ...\n" +"UnicodeDecodeError: 'utf-8' codec can't decode byte 0x80 in position 0:\n" +" invalid start byte\n" +">>> b'\\x80abc'.decode(\"utf-8\", \"replace\")\n" +"'\\ufffdabc'\n" +">>> b'\\x80abc'.decode(\"utf-8\", \"backslashreplace\")\n" +"'\\\\x80abc'\n" +">>> b'\\x80abc'.decode(\"utf-8\", \"ignore\")\n" +"'abc'" + +#: ../../howto/unicode.rst:248 +msgid "" +"Encodings are specified as strings containing the encoding's name. Python " +"comes with roughly 100 different encodings; see the Python Library Reference " +"at :ref:`standard-encodings` for a list. Some encodings have multiple " +"names; for example, ``'latin-1'``, ``'iso_8859_1'`` and ``'8859``' are all " +"synonyms for the same encoding." +msgstr "" + +#: ../../howto/unicode.rst:254 +msgid "" +"One-character Unicode strings can also be created with the :func:`chr` built-" +"in function, which takes integers and returns a Unicode string of length 1 " +"that contains the corresponding code point. The reverse operation is the " +"built-in :func:`ord` function that takes a one-character Unicode string and " +"returns the code point value::" +msgstr "" + +#: ../../howto/unicode.rst:260 +msgid "" +">>> chr(57344)\n" +"'\\ue000'\n" +">>> ord('\\ue000')\n" +"57344" +msgstr "" +">>> chr(57344)\n" +"'\\ue000'\n" +">>> ord('\\ue000')\n" +"57344" + +#: ../../howto/unicode.rst:266 +msgid "Converting to Bytes" +msgstr "" + +#: ../../howto/unicode.rst:268 +msgid "" +"The opposite method of :meth:`bytes.decode` is :meth:`str.encode`, which " +"returns a :class:`bytes` representation of the Unicode string, encoded in " +"the requested *encoding*." +msgstr "" + +#: ../../howto/unicode.rst:272 +msgid "" +"The *errors* parameter is the same as the parameter of the :meth:`~bytes." +"decode` method but supports a few more possible handlers. As well as " +"``'strict'``, ``'ignore'``, and ``'replace'`` (which in this case inserts a " +"question mark instead of the unencodable character), there is also " +"``'xmlcharrefreplace'`` (inserts an XML character reference), " +"``backslashreplace`` (inserts a ``\\uNNNN`` escape sequence) and " +"``namereplace`` (inserts a ``\\N{...}`` escape sequence)." +msgstr "" + +#: ../../howto/unicode.rst:280 +msgid "The following example shows the different results::" +msgstr "" + +#: ../../howto/unicode.rst:282 +msgid "" +">>> u = chr(40960) + 'abcd' + chr(1972)\n" +">>> u.encode('utf-8')\n" +"b'\\xea\\x80\\x80abcd\\xde\\xb4'\n" +">>> u.encode('ascii')\n" +"Traceback (most recent call last):\n" +" ...\n" +"UnicodeEncodeError: 'ascii' codec can't encode character '\\ua000' in\n" +" position 0: ordinal not in range(128)\n" +">>> u.encode('ascii', 'ignore')\n" +"b'abcd'\n" +">>> u.encode('ascii', 'replace')\n" +"b'?abcd?'\n" +">>> u.encode('ascii', 'xmlcharrefreplace')\n" +"b'ꀀabcd޴'\n" +">>> u.encode('ascii', 'backslashreplace')\n" +"b'\\\\ua000abcd\\\\u07b4'\n" +">>> u.encode('ascii', 'namereplace')\n" +"b'\\\\N{YI SYLLABLE IT}abcd\\\\u07b4'" +msgstr "" +">>> u = chr(40960) + 'abcd' + chr(1972)\n" +">>> u.encode('utf-8')\n" +"b'\\xea\\x80\\x80abcd\\xde\\xb4'\n" +">>> u.encode('ascii')\n" +"Traceback (most recent call last):\n" +" ...\n" +"UnicodeEncodeError: 'ascii' codec can't encode character '\\ua000' in\n" +" position 0: ordinal not in range(128)\n" +">>> u.encode('ascii', 'ignore')\n" +"b'abcd'\n" +">>> u.encode('ascii', 'replace')\n" +"b'?abcd?'\n" +">>> u.encode('ascii', 'xmlcharrefreplace')\n" +"b'ꀀabcd޴'\n" +">>> u.encode('ascii', 'backslashreplace')\n" +"b'\\\\ua000abcd\\\\u07b4'\n" +">>> u.encode('ascii', 'namereplace')\n" +"b'\\\\N{YI SYLLABLE IT}abcd\\\\u07b4'" + +#: ../../howto/unicode.rst:301 +msgid "" +"The low-level routines for registering and accessing the available encodings " +"are found in the :mod:`codecs` module. Implementing new encodings also " +"requires understanding the :mod:`codecs` module. However, the encoding and " +"decoding functions returned by this module are usually more low-level than " +"is comfortable, and writing new encodings is a specialized task, so the " +"module won't be covered in this HOWTO." +msgstr "" + +#: ../../howto/unicode.rst:310 +msgid "Unicode Literals in Python Source Code" +msgstr "" + +#: ../../howto/unicode.rst:312 +msgid "" +"In Python source code, specific Unicode code points can be written using the " +"``\\u`` escape sequence, which is followed by four hex digits giving the " +"code point. The ``\\U`` escape sequence is similar, but expects eight hex " +"digits, not four::" +msgstr "" + +#: ../../howto/unicode.rst:317 +msgid "" +">>> s = \"a\\xac\\u1234\\u20ac\\U00008000\"\n" +"... # ^^^^ two-digit hex escape\n" +"... # ^^^^^^ four-digit Unicode escape\n" +"... # ^^^^^^^^^^ eight-digit Unicode escape\n" +">>> [ord(c) for c in s]\n" +"[97, 172, 4660, 8364, 32768]" +msgstr "" +">>> s = \"a\\xac\\u1234\\u20ac\\U00008000\"\n" +"... # ^^^^ two-digit hex escape\n" +"... # ^^^^^^ four-digit Unicode escape\n" +"... # ^^^^^^^^^^ eight-digit Unicode escape\n" +">>> [ord(c) for c in s]\n" +"[97, 172, 4660, 8364, 32768]" + +#: ../../howto/unicode.rst:324 +msgid "" +"Using escape sequences for code points greater than 127 is fine in small " +"doses, but becomes an annoyance if you're using many accented characters, as " +"you would in a program with messages in French or some other accent-using " +"language. You can also assemble strings using the :func:`chr` built-in " +"function, but this is even more tedious." +msgstr "" + +#: ../../howto/unicode.rst:330 +msgid "" +"Ideally, you'd want to be able to write literals in your language's natural " +"encoding. You could then edit Python source code with your favorite editor " +"which would display the accented characters naturally, and have the right " +"characters used at runtime." +msgstr "" + +#: ../../howto/unicode.rst:335 +msgid "" +"Python supports writing source code in UTF-8 by default, but you can use " +"almost any encoding if you declare the encoding being used. This is done by " +"including a special comment as either the first or second line of the source " +"file::" +msgstr "" + +#: ../../howto/unicode.rst:339 +msgid "" +"#!/usr/bin/env python\n" +"# -*- coding: latin-1 -*-\n" +"\n" +"u = 'abcdé'\n" +"print(ord(u[-1]))" +msgstr "" +"#!/usr/bin/env python\n" +"# -*- coding: latin-1 -*-\n" +"\n" +"u = 'abcdé'\n" +"print(ord(u[-1]))" + +#: ../../howto/unicode.rst:345 +msgid "" +"The syntax is inspired by Emacs's notation for specifying variables local to " +"a file. Emacs supports many different variables, but Python only supports " +"'coding'. The ``-*-`` symbols indicate to Emacs that the comment is " +"special; they have no significance to Python but are a convention. Python " +"looks for ``coding: name`` or ``coding=name`` in the comment." +msgstr "" + +#: ../../howto/unicode.rst:351 +msgid "" +"If you don't include such a comment, the default encoding used will be UTF-8 " +"as already mentioned. See also :pep:`263` for more information." +msgstr "" + +#: ../../howto/unicode.rst:358 +msgid "Unicode Properties" +msgstr "" + +#: ../../howto/unicode.rst:360 +msgid "" +"The Unicode specification includes a database of information about code " +"points. For each defined code point, the information includes the " +"character's name, its category, the numeric value if applicable (for " +"characters representing numeric concepts such as the Roman numerals, " +"fractions such as one-third and four-fifths, etc.). There are also display-" +"related properties, such as how to use the code point in bidirectional text." +msgstr "" + +#: ../../howto/unicode.rst:368 +msgid "" +"The following program displays some information about several characters, " +"and prints the numeric value of one particular character::" +msgstr "" + +#: ../../howto/unicode.rst:371 +msgid "" +"import unicodedata\n" +"\n" +"u = chr(233) + chr(0x0bf2) + chr(3972) + chr(6000) + chr(13231)\n" +"\n" +"for i, c in enumerate(u):\n" +" print(i, '%04x' % ord(c), unicodedata.category(c), end=\" \")\n" +" print(unicodedata.name(c))\n" +"\n" +"# Get numeric value of second character\n" +"print(unicodedata.numeric(u[1]))" +msgstr "" + +#: ../../howto/unicode.rst:382 +msgid "When run, this prints:" +msgstr "" + +#: ../../howto/unicode.rst:384 +msgid "" +"0 00e9 Ll LATIN SMALL LETTER E WITH ACUTE\n" +"1 0bf2 No TAMIL NUMBER ONE THOUSAND\n" +"2 0f84 Mn TIBETAN MARK HALANTA\n" +"3 1770 Lo TAGBANWA LETTER SA\n" +"4 33af So SQUARE RAD OVER S SQUARED\n" +"1000.0" +msgstr "" +"0 00e9 Ll LATIN SMALL LETTER E WITH ACUTE\n" +"1 0bf2 No TAMIL NUMBER ONE THOUSAND\n" +"2 0f84 Mn TIBETAN MARK HALANTA\n" +"3 1770 Lo TAGBANWA LETTER SA\n" +"4 33af So SQUARE RAD OVER S SQUARED\n" +"1000.0" + +#: ../../howto/unicode.rst:393 +msgid "" +"The category codes are abbreviations describing the nature of the character. " +"These are grouped into categories such as \"Letter\", \"Number\", " +"\"Punctuation\", or \"Symbol\", which in turn are broken up into " +"subcategories. To take the codes from the above output, ``'Ll'`` means " +"'Letter, lowercase', ``'No'`` means \"Number, other\", ``'Mn'`` is \"Mark, " +"nonspacing\", and ``'So'`` is \"Symbol, other\". See `the General Category " +"Values section of the Unicode Character Database documentation `_ for a list of category " +"codes." +msgstr "" + +#: ../../howto/unicode.rst:404 +msgid "Comparing Strings" +msgstr "" + +#: ../../howto/unicode.rst:406 +msgid "" +"Unicode adds some complication to comparing strings, because the same set of " +"characters can be represented by different sequences of code points. For " +"example, a letter like 'ê' can be represented as a single code point U+00EA, " +"or as U+0065 U+0302, which is the code point for 'e' followed by a code " +"point for 'COMBINING CIRCUMFLEX ACCENT'. These will produce the same output " +"when printed, but one is a string of length 1 and the other is of length 2." +msgstr "" + +#: ../../howto/unicode.rst:414 +msgid "" +"One tool for a case-insensitive comparison is the :meth:`~str.casefold` " +"string method that converts a string to a case-insensitive form following an " +"algorithm described by the Unicode Standard. This algorithm has special " +"handling for characters such as the German letter 'ß' (code point U+00DF), " +"which becomes the pair of lowercase letters 'ss'." +msgstr "" + +#: ../../howto/unicode.rst:423 +msgid "" +">>> street = 'Gürzenichstraße'\n" +">>> street.casefold()\n" +"'gürzenichstrasse'" +msgstr "" +">>> street = 'Gürzenichstraße'\n" +">>> street.casefold()\n" +"'gürzenichstrasse'" + +#: ../../howto/unicode.rst:427 +msgid "" +"A second tool is the :mod:`unicodedata` module's :func:`~unicodedata." +"normalize` function that converts strings to one of several normal forms, " +"where letters followed by a combining character are replaced with single " +"characters. :func:`~unicodedata.normalize` can be used to perform string " +"comparisons that won't falsely report inequality if two strings use " +"combining characters differently:" +msgstr "" + +#: ../../howto/unicode.rst:436 +msgid "" +"import unicodedata\n" +"\n" +"def compare_strs(s1, s2):\n" +" def NFD(s):\n" +" return unicodedata.normalize('NFD', s)\n" +"\n" +" return NFD(s1) == NFD(s2)\n" +"\n" +"single_char = 'ê'\n" +"multiple_chars = '\\N{LATIN SMALL LETTER E}\\N{COMBINING CIRCUMFLEX " +"ACCENT}'\n" +"print('length of first string=', len(single_char))\n" +"print('length of second string=', len(multiple_chars))\n" +"print(compare_strs(single_char, multiple_chars))" +msgstr "" +"import unicodedata\n" +"\n" +"def compare_strs(s1, s2):\n" +" def NFD(s):\n" +" return unicodedata.normalize('NFD', s)\n" +"\n" +" return NFD(s1) == NFD(s2)\n" +"\n" +"single_char = 'ê'\n" +"multiple_chars = '\\N{LATIN SMALL LETTER E}\\N{COMBINING CIRCUMFLEX " +"ACCENT}'\n" +"print('length of first string=', len(single_char))\n" +"print('length of second string=', len(multiple_chars))\n" +"print(compare_strs(single_char, multiple_chars))" + +#: ../../howto/unicode.rst:450 +msgid "When run, this outputs:" +msgstr "" + +#: ../../howto/unicode.rst:452 +msgid "" +"$ python compare-strs.py\n" +"length of first string= 1\n" +"length of second string= 2\n" +"True" +msgstr "" +"$ python compare-strs.py\n" +"length of first string= 1\n" +"length of second string= 2\n" +"True" + +#: ../../howto/unicode.rst:459 +msgid "" +"The first argument to the :func:`~unicodedata.normalize` function is a " +"string giving the desired normalization form, which can be one of 'NFC', " +"'NFKC', 'NFD', and 'NFKD'." +msgstr "" + +#: ../../howto/unicode.rst:463 +msgid "The Unicode Standard also specifies how to do caseless comparisons::" +msgstr "" + +#: ../../howto/unicode.rst:465 +msgid "" +"import unicodedata\n" +"\n" +"def compare_caseless(s1, s2):\n" +" def NFD(s):\n" +" return unicodedata.normalize('NFD', s)\n" +"\n" +" return NFD(NFD(s1).casefold()) == NFD(NFD(s2).casefold())\n" +"\n" +"# Example usage\n" +"single_char = 'ê'\n" +"multiple_chars = '\\N{LATIN CAPITAL LETTER E}\\N{COMBINING CIRCUMFLEX " +"ACCENT}'\n" +"\n" +"print(compare_caseless(single_char, multiple_chars))" +msgstr "" + +#: ../../howto/unicode.rst:479 +msgid "" +"This will print ``True``. (Why is :func:`!NFD` invoked twice? Because " +"there are a few characters that make :meth:`~str.casefold` return a non-" +"normalized string, so the result needs to be normalized again. See section " +"3.13 of the Unicode Standard for a discussion and an example.)" +msgstr "" + +#: ../../howto/unicode.rst:486 +msgid "Unicode Regular Expressions" +msgstr "" + +#: ../../howto/unicode.rst:488 +msgid "" +"The regular expressions supported by the :mod:`re` module can be provided " +"either as bytes or strings. Some of the special character sequences such as " +"``\\d`` and ``\\w`` have different meanings depending on whether the pattern " +"is supplied as bytes or a string. For example, ``\\d`` will match the " +"characters ``[0-9]`` in bytes but in strings will match any character that's " +"in the ``'Nd'`` category." +msgstr "" + +#: ../../howto/unicode.rst:495 +msgid "" +"The string in this example has the number 57 written in both Thai and Arabic " +"numerals::" +msgstr "" + +#: ../../howto/unicode.rst:498 +msgid "" +"import re\n" +"p = re.compile(r'\\d+')\n" +"\n" +"s = \"Over \\u0e55\\u0e57 57 flavours\"\n" +"m = p.search(s)\n" +"print(repr(m.group()))" +msgstr "" +"import re\n" +"p = re.compile(r'\\d+')\n" +"\n" +"s = \"Over \\u0e55\\u0e57 57 flavours\"\n" +"m = p.search(s)\n" +"print(repr(m.group()))" + +#: ../../howto/unicode.rst:505 +msgid "" +"When executed, ``\\d+`` will match the Thai numerals and print them out. If " +"you supply the :const:`re.ASCII` flag to :func:`~re.compile`, ``\\d+`` will " +"match the substring \"57\" instead." +msgstr "" + +#: ../../howto/unicode.rst:509 +msgid "" +"Similarly, ``\\w`` matches a wide variety of Unicode characters but only " +"``[a-zA-Z0-9_]`` in bytes or if :const:`re.ASCII` is supplied, and ``\\s`` " +"will match either Unicode whitespace characters or ``[ \\t\\n\\r\\f\\v]``." +msgstr "" + +#: ../../howto/unicode.rst:520 +msgid "Some good alternative discussions of Python's Unicode support are:" +msgstr "" + +#: ../../howto/unicode.rst:522 +msgid "" +"`Processing Text Files in Python 3 `_, by Nick Coghlan." +msgstr "" + +#: ../../howto/unicode.rst:523 +msgid "" +"`Pragmatic Unicode `_, a PyCon " +"2012 presentation by Ned Batchelder." +msgstr "" + +#: ../../howto/unicode.rst:525 +msgid "" +"The :class:`str` type is described in the Python library reference at :ref:" +"`textseq`." +msgstr "" + +#: ../../howto/unicode.rst:528 +msgid "The documentation for the :mod:`unicodedata` module." +msgstr ":mod:`unicodedata` 模組的文件。" + +#: ../../howto/unicode.rst:530 +msgid "The documentation for the :mod:`codecs` module." +msgstr ":mod:`codecs` 模組的文件。" + +#: ../../howto/unicode.rst:532 +msgid "" +"Marc-André Lemburg gave `a presentation titled \"Python and Unicode\" (PDF " +"slides) `_ at " +"EuroPython 2002. The slides are an excellent overview of the design of " +"Python 2's Unicode features (where the Unicode string type is called " +"``unicode`` and literals start with ``u``)." +msgstr "" + +#: ../../howto/unicode.rst:540 +msgid "Reading and Writing Unicode Data" +msgstr "" + +#: ../../howto/unicode.rst:542 +msgid "" +"Once you've written some code that works with Unicode data, the next problem " +"is input/output. How do you get Unicode strings into your program, and how " +"do you convert Unicode into a form suitable for storage or transmission?" +msgstr "" + +#: ../../howto/unicode.rst:546 +msgid "" +"It's possible that you may not need to do anything depending on your input " +"sources and output destinations; you should check whether the libraries used " +"in your application support Unicode natively. XML parsers often return " +"Unicode data, for example. Many relational databases also support Unicode-" +"valued columns and can return Unicode values from an SQL query." +msgstr "" + +#: ../../howto/unicode.rst:552 +msgid "" +"Unicode data is usually converted to a particular encoding before it gets " +"written to disk or sent over a socket. It's possible to do all the work " +"yourself: open a file, read an 8-bit bytes object from it, and convert the " +"bytes with ``bytes.decode(encoding)``. However, the manual approach is not " +"recommended." +msgstr "" + +#: ../../howto/unicode.rst:557 +msgid "" +"One problem is the multi-byte nature of encodings; one Unicode character can " +"be represented by several bytes. If you want to read the file in arbitrary-" +"sized chunks (say, 1024 or 4096 bytes), you need to write error-handling " +"code to catch the case where only part of the bytes encoding a single " +"Unicode character are read at the end of a chunk. One solution would be to " +"read the entire file into memory and then perform the decoding, but that " +"prevents you from working with files that are extremely large; if you need " +"to read a 2 GiB file, you need 2 GiB of RAM. (More, really, since for at " +"least a moment you'd need to have both the encoded string and its Unicode " +"version in memory.)" +msgstr "" + +#: ../../howto/unicode.rst:567 +msgid "" +"The solution would be to use the low-level decoding interface to catch the " +"case of partial coding sequences. The work of implementing this has already " +"been done for you: the built-in :func:`open` function can return a file-like " +"object that assumes the file's contents are in a specified encoding and " +"accepts Unicode parameters for methods such as :meth:`~io.TextIOBase.read` " +"and :meth:`~io.TextIOBase.write`. This works through :func:`open`\\'s " +"*encoding* and *errors* parameters which are interpreted just like those in :" +"meth:`str.encode` and :meth:`bytes.decode`." +msgstr "" + +#: ../../howto/unicode.rst:576 +msgid "Reading Unicode from a file is therefore simple::" +msgstr "" + +#: ../../howto/unicode.rst:578 +msgid "" +"with open('unicode.txt', encoding='utf-8') as f:\n" +" for line in f:\n" +" print(repr(line))" +msgstr "" +"with open('unicode.txt', encoding='utf-8') as f:\n" +" for line in f:\n" +" print(repr(line))" + +#: ../../howto/unicode.rst:582 +msgid "" +"It's also possible to open files in update mode, allowing both reading and " +"writing::" +msgstr "" + +#: ../../howto/unicode.rst:585 +msgid "" +"with open('test', encoding='utf-8', mode='w+') as f:\n" +" f.write('\\u4500 blah blah blah\\n')\n" +" f.seek(0)\n" +" print(repr(f.readline()[:1]))" +msgstr "" +"with open('test', encoding='utf-8', mode='w+') as f:\n" +" f.write('\\u4500 blah blah blah\\n')\n" +" f.seek(0)\n" +" print(repr(f.readline()[:1]))" + +#: ../../howto/unicode.rst:590 +msgid "" +"The Unicode character ``U+FEFF`` is used as a byte-order mark (BOM), and is " +"often written as the first character of a file in order to assist with " +"autodetection of the file's byte ordering. Some encodings, such as UTF-16, " +"expect a BOM to be present at the start of a file; when such an encoding is " +"used, the BOM will be automatically written as the first character and will " +"be silently dropped when the file is read. There are variants of these " +"encodings, such as 'utf-16-le' and 'utf-16-be' for little-endian and big-" +"endian encodings, that specify one particular byte ordering and don't skip " +"the BOM." +msgstr "" + +#: ../../howto/unicode.rst:599 +msgid "" +"In some areas, it is also convention to use a \"BOM\" at the start of UTF-8 " +"encoded files; the name is misleading since UTF-8 is not byte-order " +"dependent. The mark simply announces that the file is encoded in UTF-8. For " +"reading such files, use the 'utf-8-sig' codec to automatically skip the mark " +"if present." +msgstr "" + +#: ../../howto/unicode.rst:606 +msgid "Unicode filenames" +msgstr "" + +#: ../../howto/unicode.rst:608 +msgid "" +"Most of the operating systems in common use today support filenames that " +"contain arbitrary Unicode characters. Usually this is implemented by " +"converting the Unicode string into some encoding that varies depending on " +"the system. Today Python is converging on using UTF-8: Python on MacOS has " +"used UTF-8 for several versions, and Python 3.6 switched to using UTF-8 on " +"Windows as well. On Unix systems, there will only be a :term:`filesystem " +"encoding `. if you've set the " +"``LANG`` or ``LC_CTYPE`` environment variables; if you haven't, the default " +"encoding is again UTF-8." +msgstr "" + +#: ../../howto/unicode.rst:618 +msgid "" +"The :func:`sys.getfilesystemencoding` function returns the encoding to use " +"on your current system, in case you want to do the encoding manually, but " +"there's not much reason to bother. When opening a file for reading or " +"writing, you can usually just provide the Unicode string as the filename, " +"and it will be automatically converted to the right encoding for you::" +msgstr "" + +#: ../../howto/unicode.rst:624 +msgid "" +"filename = 'filename\\u4500abc'\n" +"with open(filename, 'w') as f:\n" +" f.write('blah\\n')" +msgstr "" +"filename = 'filename\\u4500abc'\n" +"with open(filename, 'w') as f:\n" +" f.write('blah\\n')" + +#: ../../howto/unicode.rst:628 +msgid "" +"Functions in the :mod:`os` module such as :func:`os.stat` will also accept " +"Unicode filenames." +msgstr "" + +#: ../../howto/unicode.rst:631 +msgid "" +"The :func:`os.listdir` function returns filenames, which raises an issue: " +"should it return the Unicode version of filenames, or should it return bytes " +"containing the encoded versions? :func:`os.listdir` can do both, depending " +"on whether you provided the directory path as bytes or a Unicode string. If " +"you pass a Unicode string as the path, filenames will be decoded using the " +"filesystem's encoding and a list of Unicode strings will be returned, while " +"passing a byte path will return the filenames as bytes. For example, " +"assuming the default :term:`filesystem encoding ` is UTF-8, running the following program::" +msgstr "" + +#: ../../howto/unicode.rst:641 +msgid "" +"fn = 'filename\\u4500abc'\n" +"f = open(fn, 'w')\n" +"f.close()\n" +"\n" +"import os\n" +"print(os.listdir(b'.'))\n" +"print(os.listdir('.'))" +msgstr "" +"fn = 'filename\\u4500abc'\n" +"f = open(fn, 'w')\n" +"f.close()\n" +"\n" +"import os\n" +"print(os.listdir(b'.'))\n" +"print(os.listdir('.'))" + +#: ../../howto/unicode.rst:649 +msgid "will produce the following output:" +msgstr "" + +#: ../../howto/unicode.rst:651 +msgid "" +"$ python listdir-test.py\n" +"[b'filename\\xe4\\x94\\x80abc', ...]\n" +"['filename\\u4500abc', ...]" +msgstr "" +"$ python listdir-test.py\n" +"[b'filename\\xe4\\x94\\x80abc', ...]\n" +"['filename\\u4500abc', ...]" + +#: ../../howto/unicode.rst:657 +msgid "" +"The first list contains UTF-8-encoded filenames, and the second list " +"contains the Unicode versions." +msgstr "" + +#: ../../howto/unicode.rst:660 +msgid "" +"Note that on most occasions, you should can just stick with using Unicode " +"with these APIs. The bytes APIs should only be used on systems where " +"undecodable file names can be present; that's pretty much only Unix systems " +"now." +msgstr "" + +#: ../../howto/unicode.rst:667 +msgid "Tips for Writing Unicode-aware Programs" +msgstr "" + +#: ../../howto/unicode.rst:669 +msgid "" +"This section provides some suggestions on writing software that deals with " +"Unicode." +msgstr "" + +#: ../../howto/unicode.rst:672 +msgid "The most important tip is:" +msgstr "" + +#: ../../howto/unicode.rst:674 +msgid "" +"Software should only work with Unicode strings internally, decoding the " +"input data as soon as possible and encoding the output only at the end." +msgstr "" + +#: ../../howto/unicode.rst:677 +msgid "" +"If you attempt to write processing functions that accept both Unicode and " +"byte strings, you will find your program vulnerable to bugs wherever you " +"combine the two different kinds of strings. There is no automatic encoding " +"or decoding: if you do e.g. ``str + bytes``, a :exc:`TypeError` will be " +"raised." +msgstr "" + +#: ../../howto/unicode.rst:682 +msgid "" +"When using data coming from a web browser or some other untrusted source, a " +"common technique is to check for illegal characters in a string before using " +"the string in a generated command line or storing it in a database. If " +"you're doing this, be careful to check the decoded string, not the encoded " +"bytes data; some encodings may have interesting properties, such as not " +"being bijective or not being fully ASCII-compatible. This is especially " +"true if the input data also specifies the encoding, since the attacker can " +"then choose a clever way to hide malicious text in the encoded bytestream." +msgstr "" + +#: ../../howto/unicode.rst:693 +msgid "Converting Between File Encodings" +msgstr "" + +#: ../../howto/unicode.rst:695 +msgid "" +"The :class:`~codecs.StreamRecoder` class can transparently convert between " +"encodings, taking a stream that returns data in encoding #1 and behaving " +"like a stream returning data in encoding #2." +msgstr "" + +#: ../../howto/unicode.rst:699 +msgid "" +"For example, if you have an input file *f* that's in Latin-1, you can wrap " +"it with a :class:`~codecs.StreamRecoder` to return bytes encoded in UTF-8::" +msgstr "" + +#: ../../howto/unicode.rst:703 +msgid "" +"new_f = codecs.StreamRecoder(f,\n" +" # en/decoder: used by read() to encode its results and\n" +" # by write() to decode its input.\n" +" codecs.getencoder('utf-8'), codecs.getdecoder('utf-8'),\n" +"\n" +" # reader/writer: used to read and write to the stream.\n" +" codecs.getreader('latin-1'), codecs.getwriter('latin-1') )" +msgstr "" + +#: ../../howto/unicode.rst:713 +msgid "Files in an Unknown Encoding" +msgstr "" + +#: ../../howto/unicode.rst:715 +msgid "" +"What can you do if you need to make a change to a file, but don't know the " +"file's encoding? If you know the encoding is ASCII-compatible and only want " +"to examine or modify the ASCII parts, you can open the file with the " +"``surrogateescape`` error handler::" +msgstr "" + +#: ../../howto/unicode.rst:720 +msgid "" +"with open(fname, 'r', encoding=\"ascii\", errors=\"surrogateescape\") as f:\n" +" data = f.read()\n" +"\n" +"# make changes to the string 'data'\n" +"\n" +"with open(fname + '.new', 'w',\n" +" encoding=\"ascii\", errors=\"surrogateescape\") as f:\n" +" f.write(data)" +msgstr "" +"with open(fname, 'r', encoding=\"ascii\", errors=\"surrogateescape\") as f:\n" +" data = f.read()\n" +"\n" +"# make changes to the string 'data'\n" +"\n" +"with open(fname + '.new', 'w',\n" +" encoding=\"ascii\", errors=\"surrogateescape\") as f:\n" +" f.write(data)" + +#: ../../howto/unicode.rst:729 +msgid "" +"The ``surrogateescape`` error handler will decode any non-ASCII bytes as " +"code points in a special range running from U+DC80 to U+DCFF. These code " +"points will then turn back into the same bytes when the ``surrogateescape`` " +"error handler is used to encode the data and write it back out." +msgstr "" + +#: ../../howto/unicode.rst:739 +msgid "" +"One section of `Mastering Python 3 Input/Output `_, a PyCon 2010 talk by David " +"Beazley, discusses text processing and binary data handling." +msgstr "" + +#: ../../howto/unicode.rst:743 +msgid "" +"The `PDF slides for Marc-André Lemburg's presentation \"Writing Unicode-" +"aware Applications in Python\" `_ discuss questions of " +"character encodings as well as how to internationalize and localize an " +"application. These slides cover Python 2.x only." +msgstr "" + +#: ../../howto/unicode.rst:749 +msgid "" +"`The Guts of Unicode in Python `_ is a PyCon 2013 talk by Benjamin Peterson that " +"discusses the internal Unicode representation in Python 3.3." +msgstr "" + +#: ../../howto/unicode.rst:756 +msgid "Acknowledgements" +msgstr "致謝" + +#: ../../howto/unicode.rst:758 +msgid "" +"The initial draft of this document was written by Andrew Kuchling. It has " +"since been revised further by Alexander Belopolsky, Georg Brandl, Andrew " +"Kuchling, and Ezio Melotti." +msgstr "" + +#: ../../howto/unicode.rst:762 +msgid "" +"Thanks to the following people who have noted errors or offered suggestions " +"on this article: Éric Araujo, Nicholas Bastin, Nick Coghlan, Marius " +"Gedminas, Kent Johnson, Ken Krugler, Marc-André Lemburg, Martin von Löwis, " +"Terry J. Reedy, Serhiy Storchaka, Eryk Sun, Chad Whitacre, Graham Wideman." +msgstr "" diff --git a/howto/urllib2.po b/howto/urllib2.po index 540848cedb..05d8a60819 100644 --- a/howto/urllib2.po +++ b/howto/urllib2.po @@ -1,901 +1,901 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Phate , 2015 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-12-01 00:17+0000\n" -"PO-Revision-Date: 2022-06-27 09:36+0800\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" -"X-Generator: Poedit 3.1\n" - -#: ../../howto/urllib2.rst:5 -msgid "HOWTO Fetch Internet Resources Using The urllib Package" -msgstr "如何使用 urllib 套件取得網路資源" - -#: ../../howto/urllib2.rst:0 -msgid "Author" -msgstr "作者" - -#: ../../howto/urllib2.rst:7 -msgid "`Michael Foord `_" -msgstr "`Michael Foord `_" - -#: ../../howto/urllib2.rst:11 -msgid "Introduction" -msgstr "簡介" - -#: ../../howto/urllib2.rst:13 -msgid "Related Articles" -msgstr "" - -#: ../../howto/urllib2.rst:15 -msgid "" -"You may also find useful the following article on fetching web resources " -"with Python:" -msgstr "以下這些與 Python 有關的文章說不定能幫到你::" - -#: ../../howto/urllib2.rst:18 -msgid "" -"`Basic Authentication `__" -msgstr "" -"`Basic Authentication `__" - -#: ../../howto/urllib2.rst:20 -msgid "A tutorial on *Basic Authentication*, with examples in Python." -msgstr "以 Python 為例的 *Basic Authentication* 教學。" - -#: ../../howto/urllib2.rst:22 -msgid "" -"**urllib.request** is a Python module for fetching URLs (Uniform Resource " -"Locators). It offers a very simple interface, in the form of the *urlopen* " -"function. This is capable of fetching URLs using a variety of different " -"protocols. It also offers a slightly more complex interface for handling " -"common situations - like basic authentication, cookies, proxies and so on. " -"These are provided by objects called handlers and openers." -msgstr "" -"**urllib.request** 是一個用來從 URLs (Uniform Resource Locators) 取得資料的" -"Python模組。它提供一個了非常簡單的介面能接受多種不同的協定，*urlopen* 函式。" -"也提供了較複雜的介面用於處理一些常見的狀況，例如：基本的 authentication、" -"cookies、proxies 等等，這些都可以由 handler 或 opener 物件操作。" - -#: ../../howto/urllib2.rst:29 -msgid "" -"urllib.request supports fetching URLs for many \"URL schemes\" (identified " -"by the string before the ``\":\"`` in URL - for example ``\"ftp\"`` is the " -"URL scheme of ``\"ftp://python.org/\"``) using their associated network " -"protocols (e.g. FTP, HTTP). This tutorial focuses on the most common case, " -"HTTP." -msgstr "" - -#: ../../howto/urllib2.rst:34 -msgid "" -"For straightforward situations *urlopen* is very easy to use. But as soon as " -"you encounter errors or non-trivial cases when opening HTTP URLs, you will " -"need some understanding of the HyperText Transfer Protocol. The most " -"comprehensive and authoritative reference to HTTP is :rfc:`2616`. This is a " -"technical document and not intended to be easy to read. This HOWTO aims to " -"illustrate using *urllib*, with enough detail about HTTP to help you " -"through. It is not intended to replace the :mod:`urllib.request` docs, but " -"is supplementary to them." -msgstr "" -"一般情形下 *urlopen* 是非常容易使用的，但當你遇到錯誤或者較複雜的情況下，你可" -"能需要對超文本協定 (HyperText Transfer Protocol) 有一定的了解。最完整且具參考" -"價值的是 :rfc:`2616`，不過它是一份技術文件並不容易閱讀，以下的教學會提供足夠" -"的 HTTP 知識來幫助你使用 *urllib*。這份教學並非要取代 :mod:`urllib.request` " -"這份文件，你還是會需要它。" - -#: ../../howto/urllib2.rst:44 -msgid "Fetching URLs" -msgstr "從 URL 取得資源" - -#: ../../howto/urllib2.rst:46 -msgid "The simplest way to use urllib.request is as follows::" -msgstr "以下是使用 urllib.request 最簡單的方法::" - -#: ../../howto/urllib2.rst:48 -msgid "" -"import urllib.request\n" -"with urllib.request.urlopen('http://python.org/') as response:\n" -" html = response.read()" -msgstr "" -"import urllib.request\n" -"with urllib.request.urlopen('http://python.org/') as response:\n" -" html = response.read()" - -#: ../../howto/urllib2.rst:52 -msgid "" -"If you wish to retrieve a resource via URL and store it in a temporary " -"location, you can do so via the :func:`shutil.copyfileobj` and :func:" -"`tempfile.NamedTemporaryFile` functions::" -msgstr "" - -#: ../../howto/urllib2.rst:56 -msgid "" -"import shutil\n" -"import tempfile\n" -"import urllib.request\n" -"\n" -"with urllib.request.urlopen('http://python.org/') as response:\n" -" with tempfile.NamedTemporaryFile(delete=False) as tmp_file:\n" -" shutil.copyfileobj(response, tmp_file)\n" -"\n" -"with open(tmp_file.name) as html:\n" -" pass" -msgstr "" -"import shutil\n" -"import tempfile\n" -"import urllib.request\n" -"\n" -"with urllib.request.urlopen('http://python.org/') as response:\n" -" with tempfile.NamedTemporaryFile(delete=False) as tmp_file:\n" -" shutil.copyfileobj(response, tmp_file)\n" -"\n" -"with open(tmp_file.name) as html:\n" -" pass" - -#: ../../howto/urllib2.rst:67 -msgid "" -"Many uses of urllib will be that simple (note that instead of an 'http:' URL " -"we could have used a URL starting with 'ftp:', 'file:', etc.). However, " -"it's the purpose of this tutorial to explain the more complicated cases, " -"concentrating on HTTP." -msgstr "" - -#: ../../howto/urllib2.rst:72 -msgid "" -"HTTP is based on requests and responses - the client makes requests and " -"servers send responses. urllib.request mirrors this with a ``Request`` " -"object which represents the HTTP request you are making. In its simplest " -"form you create a Request object that specifies the URL you want to fetch. " -"Calling ``urlopen`` with this Request object returns a response object for " -"the URL requested. This response is a file-like object, which means you can " -"for example call ``.read()`` on the response::" -msgstr "" - -#: ../../howto/urllib2.rst:80 -msgid "" -"import urllib.request\n" -"\n" -"req = urllib.request.Request('http://python.org/')\n" -"with urllib.request.urlopen(req) as response:\n" -" the_page = response.read()" -msgstr "" -"import urllib.request\n" -"\n" -"req = urllib.request.Request('http://python.org/')\n" -"with urllib.request.urlopen(req) as response:\n" -" the_page = response.read()" - -#: ../../howto/urllib2.rst:86 -msgid "" -"Note that urllib.request makes use of the same Request interface to handle " -"all URL schemes. For example, you can make an FTP request like so::" -msgstr "" - -#: ../../howto/urllib2.rst:89 -msgid "req = urllib.request.Request('ftp://example.com/')" -msgstr "req = urllib.request.Request('ftp://example.com/')" - -#: ../../howto/urllib2.rst:91 -msgid "" -"In the case of HTTP, there are two extra things that Request objects allow " -"you to do: First, you can pass data to be sent to the server. Second, you " -"can pass extra information (\"metadata\") *about* the data or about the " -"request itself, to the server - this information is sent as HTTP " -"\"headers\". Let's look at each of these in turn." -msgstr "" - -#: ../../howto/urllib2.rst:98 -msgid "Data" -msgstr "" - -#: ../../howto/urllib2.rst:100 -msgid "" -"Sometimes you want to send data to a URL (often the URL will refer to a CGI " -"(Common Gateway Interface) script or other web application). With HTTP, this " -"is often done using what's known as a **POST** request. This is often what " -"your browser does when you submit a HTML form that you filled in on the web. " -"Not all POSTs have to come from forms: you can use a POST to transmit " -"arbitrary data to your own application. In the common case of HTML forms, " -"the data needs to be encoded in a standard way, and then passed to the " -"Request object as the ``data`` argument. The encoding is done using a " -"function from the :mod:`urllib.parse` library. ::" -msgstr "" - -#: ../../howto/urllib2.rst:110 -msgid "" -"import urllib.parse\n" -"import urllib.request\n" -"\n" -"url = 'http://www.someserver.com/cgi-bin/register.cgi'\n" -"values = {'name' : 'Michael Foord',\n" -" 'location' : 'Northampton',\n" -" 'language' : 'Python' }\n" -"\n" -"data = urllib.parse.urlencode(values)\n" -"data = data.encode('ascii') # data should be bytes\n" -"req = urllib.request.Request(url, data)\n" -"with urllib.request.urlopen(req) as response:\n" -" the_page = response.read()" -msgstr "" -"import urllib.parse\n" -"import urllib.request\n" -"\n" -"url = 'http://www.someserver.com/cgi-bin/register.cgi'\n" -"values = {'name' : 'Michael Foord',\n" -" 'location' : 'Northampton',\n" -" 'language' : 'Python' }\n" -"\n" -"data = urllib.parse.urlencode(values)\n" -"data = data.encode('ascii') # data should be bytes\n" -"req = urllib.request.Request(url, data)\n" -"with urllib.request.urlopen(req) as response:\n" -" the_page = response.read()" - -#: ../../howto/urllib2.rst:124 -msgid "" -"Note that other encodings are sometimes required (e.g. for file upload from " -"HTML forms - see `HTML Specification, Form Submission `_ for more details)." -msgstr "" - -#: ../../howto/urllib2.rst:129 -msgid "" -"If you do not pass the ``data`` argument, urllib uses a **GET** request. One " -"way in which GET and POST requests differ is that POST requests often have " -"\"side-effects\": they change the state of the system in some way (for " -"example by placing an order with the website for a hundredweight of tinned " -"spam to be delivered to your door). Though the HTTP standard makes it clear " -"that POSTs are intended to *always* cause side-effects, and GET requests " -"*never* to cause side-effects, nothing prevents a GET request from having " -"side-effects, nor a POST requests from having no side-effects. Data can also " -"be passed in an HTTP GET request by encoding it in the URL itself." -msgstr "" - -#: ../../howto/urllib2.rst:139 -msgid "This is done as follows::" -msgstr "" - -#: ../../howto/urllib2.rst:141 -msgid "" -">>> import urllib.request\n" -">>> import urllib.parse\n" -">>> data = {}\n" -">>> data['name'] = 'Somebody Here'\n" -">>> data['location'] = 'Northampton'\n" -">>> data['language'] = 'Python'\n" -">>> url_values = urllib.parse.urlencode(data)\n" -">>> print(url_values) # The order may differ from below.\n" -"name=Somebody+Here&language=Python&location=Northampton\n" -">>> url = 'http://www.example.com/example.cgi'\n" -">>> full_url = url + '?' + url_values\n" -">>> data = urllib.request.urlopen(full_url)" -msgstr "" -">>> import urllib.request\n" -">>> import urllib.parse\n" -">>> data = {}\n" -">>> data['name'] = 'Somebody Here'\n" -">>> data['location'] = 'Northampton'\n" -">>> data['language'] = 'Python'\n" -">>> url_values = urllib.parse.urlencode(data)\n" -">>> print(url_values) # The order may differ from below.\n" -"name=Somebody+Here&language=Python&location=Northampton\n" -">>> url = 'http://www.example.com/example.cgi'\n" -">>> full_url = url + '?' + url_values\n" -">>> data = urllib.request.urlopen(full_url)" - -#: ../../howto/urllib2.rst:154 -msgid "" -"Notice that the full URL is created by adding a ``?`` to the URL, followed " -"by the encoded values." -msgstr "" - -#: ../../howto/urllib2.rst:158 -msgid "Headers" -msgstr "" - -#: ../../howto/urllib2.rst:160 -msgid "" -"We'll discuss here one particular HTTP header, to illustrate how to add " -"headers to your HTTP request." -msgstr "" - -#: ../../howto/urllib2.rst:163 -msgid "" -"Some websites [#]_ dislike being browsed by programs, or send different " -"versions to different browsers [#]_. By default urllib identifies itself as " -"``Python-urllib/x.y`` (where ``x`` and ``y`` are the major and minor version " -"numbers of the Python release, e.g. ``Python-urllib/2.5``), which may " -"confuse the site, or just plain not work. The way a browser identifies " -"itself is through the ``User-Agent`` header [#]_. When you create a Request " -"object you can pass a dictionary of headers in. The following example makes " -"the same request as above, but identifies itself as a version of Internet " -"Explorer [#]_. ::" -msgstr "" - -#: ../../howto/urllib2.rst:174 -msgid "" -"import urllib.parse\n" -"import urllib.request\n" -"\n" -"url = 'http://www.someserver.com/cgi-bin/register.cgi'\n" -"user_agent = 'Mozilla/5.0 (Windows NT 6.1; Win64; x64)'\n" -"values = {'name': 'Michael Foord',\n" -" 'location': 'Northampton',\n" -" 'language': 'Python' }\n" -"headers = {'User-Agent': user_agent}\n" -"\n" -"data = urllib.parse.urlencode(values)\n" -"data = data.encode('ascii')\n" -"req = urllib.request.Request(url, data, headers)\n" -"with urllib.request.urlopen(req) as response:\n" -" the_page = response.read()" -msgstr "" -"import urllib.parse\n" -"import urllib.request\n" -"\n" -"url = 'http://www.someserver.com/cgi-bin/register.cgi'\n" -"user_agent = 'Mozilla/5.0 (Windows NT 6.1; Win64; x64)'\n" -"values = {'name': 'Michael Foord',\n" -" 'location': 'Northampton',\n" -" 'language': 'Python' }\n" -"headers = {'User-Agent': user_agent}\n" -"\n" -"data = urllib.parse.urlencode(values)\n" -"data = data.encode('ascii')\n" -"req = urllib.request.Request(url, data, headers)\n" -"with urllib.request.urlopen(req) as response:\n" -" the_page = response.read()" - -#: ../../howto/urllib2.rst:190 -msgid "" -"The response also has two useful methods. See the section on `info and " -"geturl`_ which comes after we have a look at what happens when things go " -"wrong." -msgstr "" - -#: ../../howto/urllib2.rst:195 -msgid "Handling Exceptions" -msgstr "" - -#: ../../howto/urllib2.rst:197 -msgid "" -"*urlopen* raises :exc:`~urllib.error.URLError` when it cannot handle a " -"response (though as usual with Python APIs, built-in exceptions such as :exc:" -"`ValueError`, :exc:`TypeError` etc. may also be raised)." -msgstr "" - -#: ../../howto/urllib2.rst:201 -msgid "" -":exc:`~urllib.error.HTTPError` is the subclass of :exc:`~urllib.error." -"URLError` raised in the specific case of HTTP URLs." -msgstr "" - -#: ../../howto/urllib2.rst:204 -msgid "The exception classes are exported from the :mod:`urllib.error` module." -msgstr "" - -#: ../../howto/urllib2.rst:207 -msgid "URLError" -msgstr "URLError" - -#: ../../howto/urllib2.rst:209 -msgid "" -"Often, URLError is raised because there is no network connection (no route " -"to the specified server), or the specified server doesn't exist. In this " -"case, the exception raised will have a 'reason' attribute, which is a tuple " -"containing an error code and a text error message." -msgstr "" - -#: ../../howto/urllib2.rst:214 -msgid "e.g. ::" -msgstr "例如： ::" - -#: ../../howto/urllib2.rst:216 -msgid "" -">>> req = urllib.request.Request('http://www.pretend_server.org')\n" -">>> try: urllib.request.urlopen(req)\n" -"... except urllib.error.URLError as e:\n" -"... print(e.reason)\n" -"...\n" -"(4, 'getaddrinfo failed')" -msgstr "" -">>> req = urllib.request.Request('http://www.pretend_server.org')\n" -">>> try: urllib.request.urlopen(req)\n" -"... except urllib.error.URLError as e:\n" -"... print(e.reason)\n" -"...\n" -"(4, 'getaddrinfo failed')" - -#: ../../howto/urllib2.rst:225 -msgid "HTTPError" -msgstr "HTTPError" - -#: ../../howto/urllib2.rst:227 -msgid "" -"Every HTTP response from the server contains a numeric \"status code\". " -"Sometimes the status code indicates that the server is unable to fulfil the " -"request. The default handlers will handle some of these responses for you " -"(for example, if the response is a \"redirection\" that requests the client " -"fetch the document from a different URL, urllib will handle that for you). " -"For those it can't handle, urlopen will raise an :exc:`~urllib.error." -"HTTPError`. Typical errors include '404' (page not found), '403' (request " -"forbidden), and '401' (authentication required)." -msgstr "" - -#: ../../howto/urllib2.rst:235 -msgid "" -"See section 10 of :rfc:`2616` for a reference on all the HTTP error codes." -msgstr "" - -#: ../../howto/urllib2.rst:237 -msgid "" -"The :exc:`~urllib.error.HTTPError` instance raised will have an integer " -"'code' attribute, which corresponds to the error sent by the server." -msgstr "" - -#: ../../howto/urllib2.rst:241 -msgid "Error Codes" -msgstr "" - -#: ../../howto/urllib2.rst:243 -msgid "" -"Because the default handlers handle redirects (codes in the 300 range), and " -"codes in the 100--299 range indicate success, you will usually only see " -"error codes in the 400--599 range." -msgstr "" - -#: ../../howto/urllib2.rst:247 -msgid "" -":attr:`http.server.BaseHTTPRequestHandler.responses` is a useful dictionary " -"of response codes that shows all the response codes used by :rfc:`2616`. An " -"excerpt from the dictionary is shown below ::" -msgstr "" - -#: ../../howto/urllib2.rst:251 -msgid "" -"responses = {\n" -" ...\n" -" : ('OK', 'Request fulfilled, document follows'),\n" -" ...\n" -" : ('Forbidden',\n" -" 'Request forbidden -- authorization will " -"'\n" -" 'not help'),\n" -" : ('Not Found',\n" -" 'Nothing matches the given URI'),\n" -" ...\n" -" : (\"I'm a Teapot\",\n" -" 'Server refuses to brew coffee because " -"'\n" -" 'it is a teapot'),\n" -" ...\n" -" : ('Service Unavailable',\n" -" 'The server cannot process the " -"'\n" -" 'request due to a high load'),\n" -" ...\n" -" }" -msgstr "" - -#: ../../howto/urllib2.rst:271 -msgid "" -"When an error is raised the server responds by returning an HTTP error code " -"*and* an error page. You can use the :exc:`~urllib.error.HTTPError` instance " -"as a response on the page returned. This means that as well as the code " -"attribute, it also has read, geturl, and info, methods as returned by the " -"``urllib.response`` module::" -msgstr "" - -#: ../../howto/urllib2.rst:276 -msgid "" -">>> req = urllib.request.Request('http://www.python.org/fish.html')\n" -">>> try:\n" -"... urllib.request.urlopen(req)\n" -"... except urllib.error.HTTPError as e:\n" -"... print(e.code)\n" -"... print(e.read())\n" -"...\n" -"404\n" -"b'\\n\\n\\nPage Not Found\\n\n" -" ..." -msgstr "" -">>> req = urllib.request.Request('http://www.python.org/fish.html')\n" -">>> try:\n" -"... urllib.request.urlopen(req)\n" -"... except urllib.error.HTTPError as e:\n" -"... print(e.code)\n" -"... print(e.read())\n" -"...\n" -"404\n" -"b'\\n\\n\\nPage Not Found\\n\n" -" ..." - -#: ../../howto/urllib2.rst:291 -msgid "Wrapping it Up" -msgstr "" - -#: ../../howto/urllib2.rst:293 -msgid "" -"So if you want to be prepared for :exc:`~urllib.error.HTTPError` *or* :exc:" -"`~urllib.error.URLError` there are two basic approaches. I prefer the second " -"approach." -msgstr "" - -#: ../../howto/urllib2.rst:297 -msgid "Number 1" -msgstr "" - -#: ../../howto/urllib2.rst:302 -msgid "" -"from urllib.request import Request, urlopen\n" -"from urllib.error import URLError, HTTPError\n" -"req = Request(someurl)\n" -"try:\n" -" response = urlopen(req)\n" -"except HTTPError as e:\n" -" print('The server couldn\\'t fulfill the request.')\n" -" print('Error code: ', e.code)\n" -"except URLError as e:\n" -" print('We failed to reach a server.')\n" -" print('Reason: ', e.reason)\n" -"else:\n" -" # everything is fine" -msgstr "" - -#: ../../howto/urllib2.rst:319 -msgid "" -"The ``except HTTPError`` *must* come first, otherwise ``except URLError`` " -"will *also* catch an :exc:`~urllib.error.HTTPError`." -msgstr "" - -#: ../../howto/urllib2.rst:323 -msgid "Number 2" -msgstr "" - -#: ../../howto/urllib2.rst:327 -msgid "" -"from urllib.request import Request, urlopen\n" -"from urllib.error import URLError\n" -"req = Request(someurl)\n" -"try:\n" -" response = urlopen(req)\n" -"except URLError as e:\n" -" if hasattr(e, 'reason'):\n" -" print('We failed to reach a server.')\n" -" print('Reason: ', e.reason)\n" -" elif hasattr(e, 'code'):\n" -" print('The server couldn\\'t fulfill the request.')\n" -" print('Error code: ', e.code)\n" -"else:\n" -" # everything is fine" -msgstr "" - -#: ../../howto/urllib2.rst:344 -msgid "info and geturl" -msgstr "" - -#: ../../howto/urllib2.rst:346 -msgid "" -"The response returned by urlopen (or the :exc:`~urllib.error.HTTPError` " -"instance) has two useful methods :meth:`!info` and :meth:`!geturl` and is " -"defined in the module :mod:`urllib.response`." -msgstr "" - -#: ../../howto/urllib2.rst:350 -msgid "" -"**geturl** - this returns the real URL of the page fetched. This is useful " -"because ``urlopen`` (or the opener object used) may have followed a " -"redirect. The URL of the page fetched may not be the same as the URL " -"requested." -msgstr "" - -#: ../../howto/urllib2.rst:354 -msgid "" -"**info** - this returns a dictionary-like object that describes the page " -"fetched, particularly the headers sent by the server. It is currently an :" -"class:`http.client.HTTPMessage` instance." -msgstr "" - -#: ../../howto/urllib2.rst:358 -msgid "" -"Typical headers include 'Content-length', 'Content-type', and so on. See the " -"`Quick Reference to HTTP Headers `_ for a " -"useful listing of HTTP headers with brief explanations of their meaning and " -"use." -msgstr "" - -#: ../../howto/urllib2.rst:365 -msgid "Openers and Handlers" -msgstr "" - -#: ../../howto/urllib2.rst:367 -msgid "" -"When you fetch a URL you use an opener (an instance of the perhaps " -"confusingly named :class:`urllib.request.OpenerDirector`). Normally we have " -"been using the default opener - via ``urlopen`` - but you can create custom " -"openers. Openers use handlers. All the \"heavy lifting\" is done by the " -"handlers. Each handler knows how to open URLs for a particular URL scheme " -"(http, ftp, etc.), or how to handle an aspect of URL opening, for example " -"HTTP redirections or HTTP cookies." -msgstr "" - -#: ../../howto/urllib2.rst:375 -msgid "" -"You will want to create openers if you want to fetch URLs with specific " -"handlers installed, for example to get an opener that handles cookies, or to " -"get an opener that does not handle redirections." -msgstr "" - -#: ../../howto/urllib2.rst:379 -msgid "" -"To create an opener, instantiate an ``OpenerDirector``, and then call ``." -"add_handler(some_handler_instance)`` repeatedly." -msgstr "" - -#: ../../howto/urllib2.rst:382 -msgid "" -"Alternatively, you can use ``build_opener``, which is a convenience function " -"for creating opener objects with a single function call. ``build_opener`` " -"adds several handlers by default, but provides a quick way to add more and/" -"or override the default handlers." -msgstr "" - -#: ../../howto/urllib2.rst:387 -msgid "" -"Other sorts of handlers you might want to can handle proxies, " -"authentication, and other common but slightly specialised situations." -msgstr "" - -#: ../../howto/urllib2.rst:390 -msgid "" -"``install_opener`` can be used to make an ``opener`` object the (global) " -"default opener. This means that calls to ``urlopen`` will use the opener you " -"have installed." -msgstr "" - -#: ../../howto/urllib2.rst:394 -msgid "" -"Opener objects have an ``open`` method, which can be called directly to " -"fetch urls in the same way as the ``urlopen`` function: there's no need to " -"call ``install_opener``, except as a convenience." -msgstr "" - -#: ../../howto/urllib2.rst:400 -msgid "Basic Authentication" -msgstr "" - -#: ../../howto/urllib2.rst:402 -msgid "" -"To illustrate creating and installing a handler we will use the " -"``HTTPBasicAuthHandler``. For a more detailed discussion of this subject -- " -"including an explanation of how Basic Authentication works - see the `Basic " -"Authentication Tutorial `__." -msgstr "" - -#: ../../howto/urllib2.rst:408 -msgid "" -"When authentication is required, the server sends a header (as well as the " -"401 error code) requesting authentication. This specifies the " -"authentication scheme and a 'realm'. The header looks like: ``WWW-" -"Authenticate: SCHEME realm=\"REALM\"``." -msgstr "" - -#: ../../howto/urllib2.rst:413 -msgid "e.g." -msgstr "例如" - -#: ../../howto/urllib2.rst:415 -msgid "WWW-Authenticate: Basic realm=\"cPanel Users\"" -msgstr "WWW-Authenticate: Basic realm=\"cPanel Users\"" - -#: ../../howto/urllib2.rst:420 -msgid "" -"The client should then retry the request with the appropriate name and " -"password for the realm included as a header in the request. This is 'basic " -"authentication'. In order to simplify this process we can create an instance " -"of ``HTTPBasicAuthHandler`` and an opener to use this handler." -msgstr "" - -#: ../../howto/urllib2.rst:425 -msgid "" -"The ``HTTPBasicAuthHandler`` uses an object called a password manager to " -"handle the mapping of URLs and realms to passwords and usernames. If you " -"know what the realm is (from the authentication header sent by the server), " -"then you can use a ``HTTPPasswordMgr``. Frequently one doesn't care what the " -"realm is. In that case, it is convenient to use " -"``HTTPPasswordMgrWithDefaultRealm``. This allows you to specify a default " -"username and password for a URL. This will be supplied in the absence of you " -"providing an alternative combination for a specific realm. We indicate this " -"by providing ``None`` as the realm argument to the ``add_password`` method." -msgstr "" - -#: ../../howto/urllib2.rst:435 -msgid "" -"The top-level URL is the first URL that requires authentication. URLs " -"\"deeper\" than the URL you pass to .add_password() will also match. ::" -msgstr "" - -#: ../../howto/urllib2.rst:438 -msgid "" -"# create a password manager\n" -"password_mgr = urllib.request.HTTPPasswordMgrWithDefaultRealm()\n" -"\n" -"# Add the username and password.\n" -"# If we knew the realm, we could use it instead of None.\n" -"top_level_url = \"http://example.com/foo/\"\n" -"password_mgr.add_password(None, top_level_url, username, password)\n" -"\n" -"handler = urllib.request.HTTPBasicAuthHandler(password_mgr)\n" -"\n" -"# create \"opener\" (OpenerDirector instance)\n" -"opener = urllib.request.build_opener(handler)\n" -"\n" -"# use the opener to fetch a URL\n" -"opener.open(a_url)\n" -"\n" -"# Install the opener.\n" -"# Now all calls to urllib.request.urlopen use our opener.\n" -"urllib.request.install_opener(opener)" -msgstr "" - -#: ../../howto/urllib2.rst:460 -msgid "" -"In the above example we only supplied our ``HTTPBasicAuthHandler`` to " -"``build_opener``. By default openers have the handlers for normal situations " -"-- ``ProxyHandler`` (if a proxy setting such as an :envvar:`!http_proxy` " -"environment variable is set), ``UnknownHandler``, ``HTTPHandler``, " -"``HTTPDefaultErrorHandler``, ``HTTPRedirectHandler``, ``FTPHandler``, " -"``FileHandler``, ``DataHandler``, ``HTTPErrorProcessor``." -msgstr "" - -#: ../../howto/urllib2.rst:467 -msgid "" -"``top_level_url`` is in fact *either* a full URL (including the 'http:' " -"scheme component and the hostname and optionally the port number) e.g. " -"``\"http://example.com/\"`` *or* an \"authority\" (i.e. the hostname, " -"optionally including the port number) e.g. ``\"example.com\"`` or " -"``\"example.com:8080\"`` (the latter example includes a port number). The " -"authority, if present, must NOT contain the \"userinfo\" component - for " -"example ``\"joe:password@example.com\"`` is not correct." -msgstr "" - -#: ../../howto/urllib2.rst:477 -msgid "Proxies" -msgstr "" - -#: ../../howto/urllib2.rst:479 -msgid "" -"**urllib** will auto-detect your proxy settings and use those. This is " -"through the ``ProxyHandler``, which is part of the normal handler chain when " -"a proxy setting is detected. Normally that's a good thing, but there are " -"occasions when it may not be helpful [#]_. One way to do this is to setup " -"our own ``ProxyHandler``, with no proxies defined. This is done using " -"similar steps to setting up a `Basic Authentication`_ handler: ::" -msgstr "" - -#: ../../howto/urllib2.rst:486 -msgid "" -">>> proxy_support = urllib.request.ProxyHandler({})\n" -">>> opener = urllib.request.build_opener(proxy_support)\n" -">>> urllib.request.install_opener(opener)" -msgstr "" -">>> proxy_support = urllib.request.ProxyHandler({})\n" -">>> opener = urllib.request.build_opener(proxy_support)\n" -">>> urllib.request.install_opener(opener)" - -#: ../../howto/urllib2.rst:492 -msgid "" -"Currently ``urllib.request`` *does not* support fetching of ``https`` " -"locations through a proxy. However, this can be enabled by extending urllib." -"request as shown in the recipe [#]_." -msgstr "" - -#: ../../howto/urllib2.rst:498 -msgid "" -"``HTTP_PROXY`` will be ignored if a variable ``REQUEST_METHOD`` is set; see " -"the documentation on :func:`~urllib.request.getproxies`." -msgstr "" - -#: ../../howto/urllib2.rst:503 -msgid "Sockets and Layers" -msgstr "" - -#: ../../howto/urllib2.rst:505 -msgid "" -"The Python support for fetching resources from the web is layered. urllib " -"uses the :mod:`http.client` library, which in turn uses the socket library." -msgstr "" - -#: ../../howto/urllib2.rst:508 -msgid "" -"As of Python 2.3 you can specify how long a socket should wait for a " -"response before timing out. This can be useful in applications which have to " -"fetch web pages. By default the socket module has *no timeout* and can hang. " -"Currently, the socket timeout is not exposed at the http.client or urllib." -"request levels. However, you can set the default timeout globally for all " -"sockets using ::" -msgstr "" - -#: ../../howto/urllib2.rst:514 -msgid "" -"import socket\n" -"import urllib.request\n" -"\n" -"# timeout in seconds\n" -"timeout = 10\n" -"socket.setdefaulttimeout(timeout)\n" -"\n" -"# this call to urllib.request.urlopen now uses the default timeout\n" -"# we have set in the socket module\n" -"req = urllib.request.Request('http://www.voidspace.org.uk')\n" -"response = urllib.request.urlopen(req)" -msgstr "" - -#: ../../howto/urllib2.rst:531 -msgid "Footnotes" -msgstr "註腳" - -#: ../../howto/urllib2.rst:533 -msgid "This document was reviewed and revised by John Lee." -msgstr "" - -#: ../../howto/urllib2.rst:535 -msgid "Google for example." -msgstr "" - -#: ../../howto/urllib2.rst:536 -msgid "" -"Browser sniffing is a very bad practice for website design - building sites " -"using web standards is much more sensible. Unfortunately a lot of sites " -"still send different versions to different browsers." -msgstr "" - -#: ../../howto/urllib2.rst:539 -msgid "" -"The user agent for MSIE 6 is *'Mozilla/4.0 (compatible; MSIE 6.0; Windows NT " -"5.1; SV1; .NET CLR 1.1.4322)'*" -msgstr "" - -#: ../../howto/urllib2.rst:541 -msgid "" -"For details of more HTTP request headers, see `Quick Reference to HTTP " -"Headers`_." -msgstr "" - -#: ../../howto/urllib2.rst:543 -msgid "" -"In my case I have to use a proxy to access the internet at work. If you " -"attempt to fetch *localhost* URLs through this proxy it blocks them. IE is " -"set to use the proxy, which urllib picks up on. In order to test scripts " -"with a localhost server, I have to prevent urllib from using the proxy." -msgstr "" - -#: ../../howto/urllib2.rst:548 -msgid "" -"urllib opener for SSL proxy (CONNECT method): `ASPN Cookbook Recipe `_." -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Phate , 2015 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-12-01 00:17+0000\n" +"PO-Revision-Date: 2022-06-27 09:36+0800\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" +"X-Generator: Poedit 3.1\n" + +#: ../../howto/urllib2.rst:5 +msgid "HOWTO Fetch Internet Resources Using The urllib Package" +msgstr "如何使用 urllib 套件取得網路資源" + +#: ../../howto/urllib2.rst:0 +msgid "Author" +msgstr "作者" + +#: ../../howto/urllib2.rst:7 +msgid "`Michael Foord `_" +msgstr "`Michael Foord `_" + +#: ../../howto/urllib2.rst:11 +msgid "Introduction" +msgstr "簡介" + +#: ../../howto/urllib2.rst:13 +msgid "Related Articles" +msgstr "" + +#: ../../howto/urllib2.rst:15 +msgid "" +"You may also find useful the following article on fetching web resources " +"with Python:" +msgstr "以下這些與 Python 有關的文章說不定能幫到你::" + +#: ../../howto/urllib2.rst:18 +msgid "" +"`Basic Authentication `__" +msgstr "" +"`Basic Authentication `__" + +#: ../../howto/urllib2.rst:20 +msgid "A tutorial on *Basic Authentication*, with examples in Python." +msgstr "以 Python 為例的 *Basic Authentication* 教學。" + +#: ../../howto/urllib2.rst:22 +msgid "" +"**urllib.request** is a Python module for fetching URLs (Uniform Resource " +"Locators). It offers a very simple interface, in the form of the *urlopen* " +"function. This is capable of fetching URLs using a variety of different " +"protocols. It also offers a slightly more complex interface for handling " +"common situations - like basic authentication, cookies, proxies and so on. " +"These are provided by objects called handlers and openers." +msgstr "" +"**urllib.request** 是一個用來從 URLs (Uniform Resource Locators) 取得資料的" +"Python模組。它提供一個了非常簡單的介面能接受多種不同的協定，*urlopen* 函式。" +"也提供了較複雜的介面用於處理一些常見的狀況，例如：基本的 authentication、" +"cookies、proxies 等等，這些都可以由 handler 或 opener 物件操作。" + +#: ../../howto/urllib2.rst:29 +msgid "" +"urllib.request supports fetching URLs for many \"URL schemes\" (identified " +"by the string before the ``\":\"`` in URL - for example ``\"ftp\"`` is the " +"URL scheme of ``\"ftp://python.org/\"``) using their associated network " +"protocols (e.g. FTP, HTTP). This tutorial focuses on the most common case, " +"HTTP." +msgstr "" + +#: ../../howto/urllib2.rst:34 +msgid "" +"For straightforward situations *urlopen* is very easy to use. But as soon as " +"you encounter errors or non-trivial cases when opening HTTP URLs, you will " +"need some understanding of the HyperText Transfer Protocol. The most " +"comprehensive and authoritative reference to HTTP is :rfc:`2616`. This is a " +"technical document and not intended to be easy to read. This HOWTO aims to " +"illustrate using *urllib*, with enough detail about HTTP to help you " +"through. It is not intended to replace the :mod:`urllib.request` docs, but " +"is supplementary to them." +msgstr "" +"一般情形下 *urlopen* 是非常容易使用的，但當你遇到錯誤或者較複雜的情況下，你可" +"能需要對超文本協定 (HyperText Transfer Protocol) 有一定的了解。最完整且具參考" +"價值的是 :rfc:`2616`，不過它是一份技術文件並不容易閱讀，以下的教學會提供足夠" +"的 HTTP 知識來幫助你使用 *urllib*。這份教學並非要取代 :mod:`urllib.request` " +"這份文件，你還是會需要它。" + +#: ../../howto/urllib2.rst:44 +msgid "Fetching URLs" +msgstr "從 URL 取得資源" + +#: ../../howto/urllib2.rst:46 +msgid "The simplest way to use urllib.request is as follows::" +msgstr "以下是使用 urllib.request 最簡單的方法::" + +#: ../../howto/urllib2.rst:48 +msgid "" +"import urllib.request\n" +"with urllib.request.urlopen('http://python.org/') as response:\n" +" html = response.read()" +msgstr "" +"import urllib.request\n" +"with urllib.request.urlopen('http://python.org/') as response:\n" +" html = response.read()" + +#: ../../howto/urllib2.rst:52 +msgid "" +"If you wish to retrieve a resource via URL and store it in a temporary " +"location, you can do so via the :func:`shutil.copyfileobj` and :func:" +"`tempfile.NamedTemporaryFile` functions::" +msgstr "" + +#: ../../howto/urllib2.rst:56 +msgid "" +"import shutil\n" +"import tempfile\n" +"import urllib.request\n" +"\n" +"with urllib.request.urlopen('http://python.org/') as response:\n" +" with tempfile.NamedTemporaryFile(delete=False) as tmp_file:\n" +" shutil.copyfileobj(response, tmp_file)\n" +"\n" +"with open(tmp_file.name) as html:\n" +" pass" +msgstr "" +"import shutil\n" +"import tempfile\n" +"import urllib.request\n" +"\n" +"with urllib.request.urlopen('http://python.org/') as response:\n" +" with tempfile.NamedTemporaryFile(delete=False) as tmp_file:\n" +" shutil.copyfileobj(response, tmp_file)\n" +"\n" +"with open(tmp_file.name) as html:\n" +" pass" + +#: ../../howto/urllib2.rst:67 +msgid "" +"Many uses of urllib will be that simple (note that instead of an 'http:' URL " +"we could have used a URL starting with 'ftp:', 'file:', etc.). However, " +"it's the purpose of this tutorial to explain the more complicated cases, " +"concentrating on HTTP." +msgstr "" + +#: ../../howto/urllib2.rst:72 +msgid "" +"HTTP is based on requests and responses - the client makes requests and " +"servers send responses. urllib.request mirrors this with a ``Request`` " +"object which represents the HTTP request you are making. In its simplest " +"form you create a Request object that specifies the URL you want to fetch. " +"Calling ``urlopen`` with this Request object returns a response object for " +"the URL requested. This response is a file-like object, which means you can " +"for example call ``.read()`` on the response::" +msgstr "" + +#: ../../howto/urllib2.rst:80 +msgid "" +"import urllib.request\n" +"\n" +"req = urllib.request.Request('http://python.org/')\n" +"with urllib.request.urlopen(req) as response:\n" +" the_page = response.read()" +msgstr "" +"import urllib.request\n" +"\n" +"req = urllib.request.Request('http://python.org/')\n" +"with urllib.request.urlopen(req) as response:\n" +" the_page = response.read()" + +#: ../../howto/urllib2.rst:86 +msgid "" +"Note that urllib.request makes use of the same Request interface to handle " +"all URL schemes. For example, you can make an FTP request like so::" +msgstr "" + +#: ../../howto/urllib2.rst:89 +msgid "req = urllib.request.Request('ftp://example.com/')" +msgstr "req = urllib.request.Request('ftp://example.com/')" + +#: ../../howto/urllib2.rst:91 +msgid "" +"In the case of HTTP, there are two extra things that Request objects allow " +"you to do: First, you can pass data to be sent to the server. Second, you " +"can pass extra information (\"metadata\") *about* the data or about the " +"request itself, to the server - this information is sent as HTTP " +"\"headers\". Let's look at each of these in turn." +msgstr "" + +#: ../../howto/urllib2.rst:98 +msgid "Data" +msgstr "" + +#: ../../howto/urllib2.rst:100 +msgid "" +"Sometimes you want to send data to a URL (often the URL will refer to a CGI " +"(Common Gateway Interface) script or other web application). With HTTP, this " +"is often done using what's known as a **POST** request. This is often what " +"your browser does when you submit a HTML form that you filled in on the web. " +"Not all POSTs have to come from forms: you can use a POST to transmit " +"arbitrary data to your own application. In the common case of HTML forms, " +"the data needs to be encoded in a standard way, and then passed to the " +"Request object as the ``data`` argument. The encoding is done using a " +"function from the :mod:`urllib.parse` library. ::" +msgstr "" + +#: ../../howto/urllib2.rst:110 +msgid "" +"import urllib.parse\n" +"import urllib.request\n" +"\n" +"url = 'http://www.someserver.com/cgi-bin/register.cgi'\n" +"values = {'name' : 'Michael Foord',\n" +" 'location' : 'Northampton',\n" +" 'language' : 'Python' }\n" +"\n" +"data = urllib.parse.urlencode(values)\n" +"data = data.encode('ascii') # data should be bytes\n" +"req = urllib.request.Request(url, data)\n" +"with urllib.request.urlopen(req) as response:\n" +" the_page = response.read()" +msgstr "" +"import urllib.parse\n" +"import urllib.request\n" +"\n" +"url = 'http://www.someserver.com/cgi-bin/register.cgi'\n" +"values = {'name' : 'Michael Foord',\n" +" 'location' : 'Northampton',\n" +" 'language' : 'Python' }\n" +"\n" +"data = urllib.parse.urlencode(values)\n" +"data = data.encode('ascii') # data should be bytes\n" +"req = urllib.request.Request(url, data)\n" +"with urllib.request.urlopen(req) as response:\n" +" the_page = response.read()" + +#: ../../howto/urllib2.rst:124 +msgid "" +"Note that other encodings are sometimes required (e.g. for file upload from " +"HTML forms - see `HTML Specification, Form Submission `_ for more details)." +msgstr "" + +#: ../../howto/urllib2.rst:129 +msgid "" +"If you do not pass the ``data`` argument, urllib uses a **GET** request. One " +"way in which GET and POST requests differ is that POST requests often have " +"\"side-effects\": they change the state of the system in some way (for " +"example by placing an order with the website for a hundredweight of tinned " +"spam to be delivered to your door). Though the HTTP standard makes it clear " +"that POSTs are intended to *always* cause side-effects, and GET requests " +"*never* to cause side-effects, nothing prevents a GET request from having " +"side-effects, nor a POST requests from having no side-effects. Data can also " +"be passed in an HTTP GET request by encoding it in the URL itself." +msgstr "" + +#: ../../howto/urllib2.rst:139 +msgid "This is done as follows::" +msgstr "" + +#: ../../howto/urllib2.rst:141 +msgid "" +">>> import urllib.request\n" +">>> import urllib.parse\n" +">>> data = {}\n" +">>> data['name'] = 'Somebody Here'\n" +">>> data['location'] = 'Northampton'\n" +">>> data['language'] = 'Python'\n" +">>> url_values = urllib.parse.urlencode(data)\n" +">>> print(url_values) # The order may differ from below.\n" +"name=Somebody+Here&language=Python&location=Northampton\n" +">>> url = 'http://www.example.com/example.cgi'\n" +">>> full_url = url + '?' + url_values\n" +">>> data = urllib.request.urlopen(full_url)" +msgstr "" +">>> import urllib.request\n" +">>> import urllib.parse\n" +">>> data = {}\n" +">>> data['name'] = 'Somebody Here'\n" +">>> data['location'] = 'Northampton'\n" +">>> data['language'] = 'Python'\n" +">>> url_values = urllib.parse.urlencode(data)\n" +">>> print(url_values) # The order may differ from below.\n" +"name=Somebody+Here&language=Python&location=Northampton\n" +">>> url = 'http://www.example.com/example.cgi'\n" +">>> full_url = url + '?' + url_values\n" +">>> data = urllib.request.urlopen(full_url)" + +#: ../../howto/urllib2.rst:154 +msgid "" +"Notice that the full URL is created by adding a ``?`` to the URL, followed " +"by the encoded values." +msgstr "" + +#: ../../howto/urllib2.rst:158 +msgid "Headers" +msgstr "" + +#: ../../howto/urllib2.rst:160 +msgid "" +"We'll discuss here one particular HTTP header, to illustrate how to add " +"headers to your HTTP request." +msgstr "" + +#: ../../howto/urllib2.rst:163 +msgid "" +"Some websites [#]_ dislike being browsed by programs, or send different " +"versions to different browsers [#]_. By default urllib identifies itself as " +"``Python-urllib/x.y`` (where ``x`` and ``y`` are the major and minor version " +"numbers of the Python release, e.g. ``Python-urllib/2.5``), which may " +"confuse the site, or just plain not work. The way a browser identifies " +"itself is through the ``User-Agent`` header [#]_. When you create a Request " +"object you can pass a dictionary of headers in. The following example makes " +"the same request as above, but identifies itself as a version of Internet " +"Explorer [#]_. ::" +msgstr "" + +#: ../../howto/urllib2.rst:174 +msgid "" +"import urllib.parse\n" +"import urllib.request\n" +"\n" +"url = 'http://www.someserver.com/cgi-bin/register.cgi'\n" +"user_agent = 'Mozilla/5.0 (Windows NT 6.1; Win64; x64)'\n" +"values = {'name': 'Michael Foord',\n" +" 'location': 'Northampton',\n" +" 'language': 'Python' }\n" +"headers = {'User-Agent': user_agent}\n" +"\n" +"data = urllib.parse.urlencode(values)\n" +"data = data.encode('ascii')\n" +"req = urllib.request.Request(url, data, headers)\n" +"with urllib.request.urlopen(req) as response:\n" +" the_page = response.read()" +msgstr "" +"import urllib.parse\n" +"import urllib.request\n" +"\n" +"url = 'http://www.someserver.com/cgi-bin/register.cgi'\n" +"user_agent = 'Mozilla/5.0 (Windows NT 6.1; Win64; x64)'\n" +"values = {'name': 'Michael Foord',\n" +" 'location': 'Northampton',\n" +" 'language': 'Python' }\n" +"headers = {'User-Agent': user_agent}\n" +"\n" +"data = urllib.parse.urlencode(values)\n" +"data = data.encode('ascii')\n" +"req = urllib.request.Request(url, data, headers)\n" +"with urllib.request.urlopen(req) as response:\n" +" the_page = response.read()" + +#: ../../howto/urllib2.rst:190 +msgid "" +"The response also has two useful methods. See the section on `info and " +"geturl`_ which comes after we have a look at what happens when things go " +"wrong." +msgstr "" + +#: ../../howto/urllib2.rst:195 +msgid "Handling Exceptions" +msgstr "" + +#: ../../howto/urllib2.rst:197 +msgid "" +"*urlopen* raises :exc:`~urllib.error.URLError` when it cannot handle a " +"response (though as usual with Python APIs, built-in exceptions such as :exc:" +"`ValueError`, :exc:`TypeError` etc. may also be raised)." +msgstr "" + +#: ../../howto/urllib2.rst:201 +msgid "" +":exc:`~urllib.error.HTTPError` is the subclass of :exc:`~urllib.error." +"URLError` raised in the specific case of HTTP URLs." +msgstr "" + +#: ../../howto/urllib2.rst:204 +msgid "The exception classes are exported from the :mod:`urllib.error` module." +msgstr "" + +#: ../../howto/urllib2.rst:207 +msgid "URLError" +msgstr "URLError" + +#: ../../howto/urllib2.rst:209 +msgid "" +"Often, URLError is raised because there is no network connection (no route " +"to the specified server), or the specified server doesn't exist. In this " +"case, the exception raised will have a 'reason' attribute, which is a tuple " +"containing an error code and a text error message." +msgstr "" + +#: ../../howto/urllib2.rst:214 +msgid "e.g. ::" +msgstr "例如： ::" + +#: ../../howto/urllib2.rst:216 +msgid "" +">>> req = urllib.request.Request('http://www.pretend_server.org')\n" +">>> try: urllib.request.urlopen(req)\n" +"... except urllib.error.URLError as e:\n" +"... print(e.reason)\n" +"...\n" +"(4, 'getaddrinfo failed')" +msgstr "" +">>> req = urllib.request.Request('http://www.pretend_server.org')\n" +">>> try: urllib.request.urlopen(req)\n" +"... except urllib.error.URLError as e:\n" +"... print(e.reason)\n" +"...\n" +"(4, 'getaddrinfo failed')" + +#: ../../howto/urllib2.rst:225 +msgid "HTTPError" +msgstr "HTTPError" + +#: ../../howto/urllib2.rst:227 +msgid "" +"Every HTTP response from the server contains a numeric \"status code\". " +"Sometimes the status code indicates that the server is unable to fulfil the " +"request. The default handlers will handle some of these responses for you " +"(for example, if the response is a \"redirection\" that requests the client " +"fetch the document from a different URL, urllib will handle that for you). " +"For those it can't handle, urlopen will raise an :exc:`~urllib.error." +"HTTPError`. Typical errors include '404' (page not found), '403' (request " +"forbidden), and '401' (authentication required)." +msgstr "" + +#: ../../howto/urllib2.rst:235 +msgid "" +"See section 10 of :rfc:`2616` for a reference on all the HTTP error codes." +msgstr "" + +#: ../../howto/urllib2.rst:237 +msgid "" +"The :exc:`~urllib.error.HTTPError` instance raised will have an integer " +"'code' attribute, which corresponds to the error sent by the server." +msgstr "" + +#: ../../howto/urllib2.rst:241 +msgid "Error Codes" +msgstr "" + +#: ../../howto/urllib2.rst:243 +msgid "" +"Because the default handlers handle redirects (codes in the 300 range), and " +"codes in the 100--299 range indicate success, you will usually only see " +"error codes in the 400--599 range." +msgstr "" + +#: ../../howto/urllib2.rst:247 +msgid "" +":attr:`http.server.BaseHTTPRequestHandler.responses` is a useful dictionary " +"of response codes that shows all the response codes used by :rfc:`2616`. An " +"excerpt from the dictionary is shown below ::" +msgstr "" + +#: ../../howto/urllib2.rst:251 +msgid "" +"responses = {\n" +" ...\n" +" : ('OK', 'Request fulfilled, document follows'),\n" +" ...\n" +" : ('Forbidden',\n" +" 'Request forbidden -- authorization will " +"'\n" +" 'not help'),\n" +" : ('Not Found',\n" +" 'Nothing matches the given URI'),\n" +" ...\n" +" : (\"I'm a Teapot\",\n" +" 'Server refuses to brew coffee because " +"'\n" +" 'it is a teapot'),\n" +" ...\n" +" : ('Service Unavailable',\n" +" 'The server cannot process the " +"'\n" +" 'request due to a high load'),\n" +" ...\n" +" }" +msgstr "" + +#: ../../howto/urllib2.rst:271 +msgid "" +"When an error is raised the server responds by returning an HTTP error code " +"*and* an error page. You can use the :exc:`~urllib.error.HTTPError` instance " +"as a response on the page returned. This means that as well as the code " +"attribute, it also has read, geturl, and info, methods as returned by the " +"``urllib.response`` module::" +msgstr "" + +#: ../../howto/urllib2.rst:276 +msgid "" +">>> req = urllib.request.Request('http://www.python.org/fish.html')\n" +">>> try:\n" +"... urllib.request.urlopen(req)\n" +"... except urllib.error.HTTPError as e:\n" +"... print(e.code)\n" +"... print(e.read())\n" +"...\n" +"404\n" +"b'\\n\\n\\nPage Not Found\\n\n" +" ..." +msgstr "" +">>> req = urllib.request.Request('http://www.python.org/fish.html')\n" +">>> try:\n" +"... urllib.request.urlopen(req)\n" +"... except urllib.error.HTTPError as e:\n" +"... print(e.code)\n" +"... print(e.read())\n" +"...\n" +"404\n" +"b'\\n\\n\\nPage Not Found\\n\n" +" ..." + +#: ../../howto/urllib2.rst:291 +msgid "Wrapping it Up" +msgstr "" + +#: ../../howto/urllib2.rst:293 +msgid "" +"So if you want to be prepared for :exc:`~urllib.error.HTTPError` *or* :exc:" +"`~urllib.error.URLError` there are two basic approaches. I prefer the second " +"approach." +msgstr "" + +#: ../../howto/urllib2.rst:297 +msgid "Number 1" +msgstr "" + +#: ../../howto/urllib2.rst:302 +msgid "" +"from urllib.request import Request, urlopen\n" +"from urllib.error import URLError, HTTPError\n" +"req = Request(someurl)\n" +"try:\n" +" response = urlopen(req)\n" +"except HTTPError as e:\n" +" print('The server couldn\\'t fulfill the request.')\n" +" print('Error code: ', e.code)\n" +"except URLError as e:\n" +" print('We failed to reach a server.')\n" +" print('Reason: ', e.reason)\n" +"else:\n" +" # everything is fine" +msgstr "" + +#: ../../howto/urllib2.rst:319 +msgid "" +"The ``except HTTPError`` *must* come first, otherwise ``except URLError`` " +"will *also* catch an :exc:`~urllib.error.HTTPError`." +msgstr "" + +#: ../../howto/urllib2.rst:323 +msgid "Number 2" +msgstr "" + +#: ../../howto/urllib2.rst:327 +msgid "" +"from urllib.request import Request, urlopen\n" +"from urllib.error import URLError\n" +"req = Request(someurl)\n" +"try:\n" +" response = urlopen(req)\n" +"except URLError as e:\n" +" if hasattr(e, 'reason'):\n" +" print('We failed to reach a server.')\n" +" print('Reason: ', e.reason)\n" +" elif hasattr(e, 'code'):\n" +" print('The server couldn\\'t fulfill the request.')\n" +" print('Error code: ', e.code)\n" +"else:\n" +" # everything is fine" +msgstr "" + +#: ../../howto/urllib2.rst:344 +msgid "info and geturl" +msgstr "" + +#: ../../howto/urllib2.rst:346 +msgid "" +"The response returned by urlopen (or the :exc:`~urllib.error.HTTPError` " +"instance) has two useful methods :meth:`!info` and :meth:`!geturl` and is " +"defined in the module :mod:`urllib.response`." +msgstr "" + +#: ../../howto/urllib2.rst:350 +msgid "" +"**geturl** - this returns the real URL of the page fetched. This is useful " +"because ``urlopen`` (or the opener object used) may have followed a " +"redirect. The URL of the page fetched may not be the same as the URL " +"requested." +msgstr "" + +#: ../../howto/urllib2.rst:354 +msgid "" +"**info** - this returns a dictionary-like object that describes the page " +"fetched, particularly the headers sent by the server. It is currently an :" +"class:`http.client.HTTPMessage` instance." +msgstr "" + +#: ../../howto/urllib2.rst:358 +msgid "" +"Typical headers include 'Content-length', 'Content-type', and so on. See the " +"`Quick Reference to HTTP Headers `_ for a " +"useful listing of HTTP headers with brief explanations of their meaning and " +"use." +msgstr "" + +#: ../../howto/urllib2.rst:365 +msgid "Openers and Handlers" +msgstr "" + +#: ../../howto/urllib2.rst:367 +msgid "" +"When you fetch a URL you use an opener (an instance of the perhaps " +"confusingly named :class:`urllib.request.OpenerDirector`). Normally we have " +"been using the default opener - via ``urlopen`` - but you can create custom " +"openers. Openers use handlers. All the \"heavy lifting\" is done by the " +"handlers. Each handler knows how to open URLs for a particular URL scheme " +"(http, ftp, etc.), or how to handle an aspect of URL opening, for example " +"HTTP redirections or HTTP cookies." +msgstr "" + +#: ../../howto/urllib2.rst:375 +msgid "" +"You will want to create openers if you want to fetch URLs with specific " +"handlers installed, for example to get an opener that handles cookies, or to " +"get an opener that does not handle redirections." +msgstr "" + +#: ../../howto/urllib2.rst:379 +msgid "" +"To create an opener, instantiate an ``OpenerDirector``, and then call ``." +"add_handler(some_handler_instance)`` repeatedly." +msgstr "" + +#: ../../howto/urllib2.rst:382 +msgid "" +"Alternatively, you can use ``build_opener``, which is a convenience function " +"for creating opener objects with a single function call. ``build_opener`` " +"adds several handlers by default, but provides a quick way to add more and/" +"or override the default handlers." +msgstr "" + +#: ../../howto/urllib2.rst:387 +msgid "" +"Other sorts of handlers you might want to can handle proxies, " +"authentication, and other common but slightly specialised situations." +msgstr "" + +#: ../../howto/urllib2.rst:390 +msgid "" +"``install_opener`` can be used to make an ``opener`` object the (global) " +"default opener. This means that calls to ``urlopen`` will use the opener you " +"have installed." +msgstr "" + +#: ../../howto/urllib2.rst:394 +msgid "" +"Opener objects have an ``open`` method, which can be called directly to " +"fetch urls in the same way as the ``urlopen`` function: there's no need to " +"call ``install_opener``, except as a convenience." +msgstr "" + +#: ../../howto/urllib2.rst:400 +msgid "Basic Authentication" +msgstr "" + +#: ../../howto/urllib2.rst:402 +msgid "" +"To illustrate creating and installing a handler we will use the " +"``HTTPBasicAuthHandler``. For a more detailed discussion of this subject -- " +"including an explanation of how Basic Authentication works - see the `Basic " +"Authentication Tutorial `__." +msgstr "" + +#: ../../howto/urllib2.rst:408 +msgid "" +"When authentication is required, the server sends a header (as well as the " +"401 error code) requesting authentication. This specifies the " +"authentication scheme and a 'realm'. The header looks like: ``WWW-" +"Authenticate: SCHEME realm=\"REALM\"``." +msgstr "" + +#: ../../howto/urllib2.rst:413 +msgid "e.g." +msgstr "例如" + +#: ../../howto/urllib2.rst:415 +msgid "WWW-Authenticate: Basic realm=\"cPanel Users\"" +msgstr "WWW-Authenticate: Basic realm=\"cPanel Users\"" + +#: ../../howto/urllib2.rst:420 +msgid "" +"The client should then retry the request with the appropriate name and " +"password for the realm included as a header in the request. This is 'basic " +"authentication'. In order to simplify this process we can create an instance " +"of ``HTTPBasicAuthHandler`` and an opener to use this handler." +msgstr "" + +#: ../../howto/urllib2.rst:425 +msgid "" +"The ``HTTPBasicAuthHandler`` uses an object called a password manager to " +"handle the mapping of URLs and realms to passwords and usernames. If you " +"know what the realm is (from the authentication header sent by the server), " +"then you can use a ``HTTPPasswordMgr``. Frequently one doesn't care what the " +"realm is. In that case, it is convenient to use " +"``HTTPPasswordMgrWithDefaultRealm``. This allows you to specify a default " +"username and password for a URL. This will be supplied in the absence of you " +"providing an alternative combination for a specific realm. We indicate this " +"by providing ``None`` as the realm argument to the ``add_password`` method." +msgstr "" + +#: ../../howto/urllib2.rst:435 +msgid "" +"The top-level URL is the first URL that requires authentication. URLs " +"\"deeper\" than the URL you pass to .add_password() will also match. ::" +msgstr "" + +#: ../../howto/urllib2.rst:438 +msgid "" +"# create a password manager\n" +"password_mgr = urllib.request.HTTPPasswordMgrWithDefaultRealm()\n" +"\n" +"# Add the username and password.\n" +"# If we knew the realm, we could use it instead of None.\n" +"top_level_url = \"http://example.com/foo/\"\n" +"password_mgr.add_password(None, top_level_url, username, password)\n" +"\n" +"handler = urllib.request.HTTPBasicAuthHandler(password_mgr)\n" +"\n" +"# create \"opener\" (OpenerDirector instance)\n" +"opener = urllib.request.build_opener(handler)\n" +"\n" +"# use the opener to fetch a URL\n" +"opener.open(a_url)\n" +"\n" +"# Install the opener.\n" +"# Now all calls to urllib.request.urlopen use our opener.\n" +"urllib.request.install_opener(opener)" +msgstr "" + +#: ../../howto/urllib2.rst:460 +msgid "" +"In the above example we only supplied our ``HTTPBasicAuthHandler`` to " +"``build_opener``. By default openers have the handlers for normal situations " +"-- ``ProxyHandler`` (if a proxy setting such as an :envvar:`!http_proxy` " +"environment variable is set), ``UnknownHandler``, ``HTTPHandler``, " +"``HTTPDefaultErrorHandler``, ``HTTPRedirectHandler``, ``FTPHandler``, " +"``FileHandler``, ``DataHandler``, ``HTTPErrorProcessor``." +msgstr "" + +#: ../../howto/urllib2.rst:467 +msgid "" +"``top_level_url`` is in fact *either* a full URL (including the 'http:' " +"scheme component and the hostname and optionally the port number) e.g. " +"``\"http://example.com/\"`` *or* an \"authority\" (i.e. the hostname, " +"optionally including the port number) e.g. ``\"example.com\"`` or " +"``\"example.com:8080\"`` (the latter example includes a port number). The " +"authority, if present, must NOT contain the \"userinfo\" component - for " +"example ``\"joe:password@example.com\"`` is not correct." +msgstr "" + +#: ../../howto/urllib2.rst:477 +msgid "Proxies" +msgstr "" + +#: ../../howto/urllib2.rst:479 +msgid "" +"**urllib** will auto-detect your proxy settings and use those. This is " +"through the ``ProxyHandler``, which is part of the normal handler chain when " +"a proxy setting is detected. Normally that's a good thing, but there are " +"occasions when it may not be helpful [#]_. One way to do this is to setup " +"our own ``ProxyHandler``, with no proxies defined. This is done using " +"similar steps to setting up a `Basic Authentication`_ handler: ::" +msgstr "" + +#: ../../howto/urllib2.rst:486 +msgid "" +">>> proxy_support = urllib.request.ProxyHandler({})\n" +">>> opener = urllib.request.build_opener(proxy_support)\n" +">>> urllib.request.install_opener(opener)" +msgstr "" +">>> proxy_support = urllib.request.ProxyHandler({})\n" +">>> opener = urllib.request.build_opener(proxy_support)\n" +">>> urllib.request.install_opener(opener)" + +#: ../../howto/urllib2.rst:492 +msgid "" +"Currently ``urllib.request`` *does not* support fetching of ``https`` " +"locations through a proxy. However, this can be enabled by extending urllib." +"request as shown in the recipe [#]_." +msgstr "" + +#: ../../howto/urllib2.rst:498 +msgid "" +"``HTTP_PROXY`` will be ignored if a variable ``REQUEST_METHOD`` is set; see " +"the documentation on :func:`~urllib.request.getproxies`." +msgstr "" + +#: ../../howto/urllib2.rst:503 +msgid "Sockets and Layers" +msgstr "" + +#: ../../howto/urllib2.rst:505 +msgid "" +"The Python support for fetching resources from the web is layered. urllib " +"uses the :mod:`http.client` library, which in turn uses the socket library." +msgstr "" + +#: ../../howto/urllib2.rst:508 +msgid "" +"As of Python 2.3 you can specify how long a socket should wait for a " +"response before timing out. This can be useful in applications which have to " +"fetch web pages. By default the socket module has *no timeout* and can hang. " +"Currently, the socket timeout is not exposed at the http.client or urllib." +"request levels. However, you can set the default timeout globally for all " +"sockets using ::" +msgstr "" + +#: ../../howto/urllib2.rst:514 +msgid "" +"import socket\n" +"import urllib.request\n" +"\n" +"# timeout in seconds\n" +"timeout = 10\n" +"socket.setdefaulttimeout(timeout)\n" +"\n" +"# this call to urllib.request.urlopen now uses the default timeout\n" +"# we have set in the socket module\n" +"req = urllib.request.Request('http://www.voidspace.org.uk')\n" +"response = urllib.request.urlopen(req)" +msgstr "" + +#: ../../howto/urllib2.rst:531 +msgid "Footnotes" +msgstr "註腳" + +#: ../../howto/urllib2.rst:533 +msgid "This document was reviewed and revised by John Lee." +msgstr "" + +#: ../../howto/urllib2.rst:535 +msgid "Google for example." +msgstr "" + +#: ../../howto/urllib2.rst:536 +msgid "" +"Browser sniffing is a very bad practice for website design - building sites " +"using web standards is much more sensible. Unfortunately a lot of sites " +"still send different versions to different browsers." +msgstr "" + +#: ../../howto/urllib2.rst:539 +msgid "" +"The user agent for MSIE 6 is *'Mozilla/4.0 (compatible; MSIE 6.0; Windows NT " +"5.1; SV1; .NET CLR 1.1.4322)'*" +msgstr "" + +#: ../../howto/urllib2.rst:541 +msgid "" +"For details of more HTTP request headers, see `Quick Reference to HTTP " +"Headers`_." +msgstr "" + +#: ../../howto/urllib2.rst:543 +msgid "" +"In my case I have to use a proxy to access the internet at work. If you " +"attempt to fetch *localhost* URLs through this proxy it blocks them. IE is " +"set to use the proxy, which urllib picks up on. In order to test scripts " +"with a localhost server, I have to prevent urllib from using the proxy." +msgstr "" + +#: ../../howto/urllib2.rst:548 +msgid "" +"urllib opener for SSL proxy (CONNECT method): `ASPN Cookbook Recipe `_." +msgstr "" diff --git a/installing/index.po b/installing/index.po index cef15e95ed..afb8d28ab4 100644 --- a/installing/index.po +++ b/installing/index.po @@ -1,468 +1,468 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Leon H., 2017 -# 豆豆 (Tommy Lin) , 2017 -# Steven Hsu , 2021 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-09-03 11:11+0800\n" -"PO-Revision-Date: 2022-06-27 09:37+0800\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" -"X-Generator: Poedit 3.1\n" - -#: ../../installing/index.rst:7 -msgid "Installing Python Modules" -msgstr "安裝 Python 模組" - -#: ../../installing/index.rst:0 -msgid "Email" -msgstr "電子郵件" - -#: ../../installing/index.rst:9 -msgid "distutils-sig@python.org" -msgstr "distutils-sig@python.org" - -#: ../../installing/index.rst:11 -msgid "" -"As a popular open source development project, Python has an active " -"supporting community of contributors and users that also make their software " -"available for other Python developers to use under open source license terms." -msgstr "" -"作為一個普及的開源開發專案，Python 有一個活躍的支持社群，由其貢獻者及使用者組" -"成，而他們也讓他們的軟體可被其他 Python 開發者在開源授權條款下使用。" - -#: ../../installing/index.rst:15 -msgid "" -"This allows Python users to share and collaborate effectively, benefiting " -"from the solutions others have already created to common (and sometimes even " -"rare!) problems, as well as potentially contributing their own solutions to " -"the common pool." -msgstr "" -"這樣可以讓 Python 使用者們有效地共享和合作，並受益於其他人對常見（有時甚至是" -"罕見）的問題已經建立的解決方案，更可以在公用社群中潛在地貢獻他們自己的解決方" -"案。" - -#: ../../installing/index.rst:20 -msgid "" -"This guide covers the installation part of the process. For a guide to " -"creating and sharing your own Python projects, refer to the `Python " -"packaging user guide`_." -msgstr "" -"這份指南涵蓋了上述過程中的安裝部分。如果是要建立及分享你自己的 Python 專案，" -"請參考 `Python packaging user guide`_。" - -#: ../../installing/index.rst:28 -msgid "" -"For corporate and other institutional users, be aware that many " -"organisations have their own policies around using and contributing to open " -"source software. Please take such policies into account when making use of " -"the distribution and installation tools provided with Python." -msgstr "" -"對於企業和其他機構的使用者，要注意到，許多組織對於使用和貢獻開源軟體都有自己" -"的政策。在開始使用配備 Python 的發布及安裝工具時，請將那些政策納入考量。" - -#: ../../installing/index.rst:35 -msgid "Key terms" -msgstr "關鍵術語" - -#: ../../installing/index.rst:37 -msgid "" -"``pip`` is the preferred installer program. Starting with Python 3.4, it is " -"included by default with the Python binary installers." -msgstr "" -"``pip`` 是首選的安裝程式。從 Python 3.4 開始，它被預設包含在 Python 二進制安" -"裝程式中。" - -#: ../../installing/index.rst:39 -msgid "" -"A *virtual environment* is a semi-isolated Python environment that allows " -"packages to be installed for use by a particular application, rather than " -"being installed system wide." -msgstr "" -"*virtual environment（虛擬環境）*\\ 是一種半隔離的 Python 環境，可以為某個特" -"定應用程式安裝其所需的套件，而不用在整個系統上安裝它們。" - -#: ../../installing/index.rst:42 -msgid "" -"``venv`` is the standard tool for creating virtual environments, and has " -"been part of Python since Python 3.3. Starting with Python 3.4, it defaults " -"to installing ``pip`` into all created virtual environments." -msgstr "" -"``venv`` 是建立虛擬環境的標準工具，它從 Python 3.3 開始成為 Python 的一部分。" -"從 Python 3.4 開始，它會預設地安裝 ``pip`` 到所有被建立的虛擬環境。" - -#: ../../installing/index.rst:45 -msgid "" -"``virtualenv`` is a third party alternative (and predecessor) to ``venv``. " -"It allows virtual environments to be used on versions of Python prior to " -"3.4, which either don't provide ``venv`` at all, or aren't able to " -"automatically install ``pip`` into created environments." -msgstr "" -"``virtualenv`` 是 ``venv`` 的一個第三方替代方案（及其前身）。它使虛擬環境可以" -"在 Python 3.4 之前的版本被使用，那些版本要不是根本沒提供 ``venv``，就是無法自" -"動安裝 ``pip`` 到所建立的環境中。" - -#: ../../installing/index.rst:49 -msgid "" -"The `Python Package Index `__ is a public repository of " -"open source licensed packages made available for use by other Python users." -msgstr "" -"`Python 套件索引 (Python Package Index) `__ 是開源授權套件" -"的一個公共儲存庫，其中的套件皆可被其他 Python 使用者所使用。" - -#: ../../installing/index.rst:52 -msgid "" -"the `Python Packaging Authority `__ is the group of " -"developers and documentation authors responsible for the maintenance and " -"evolution of the standard packaging tools and the associated metadata and " -"file format standards. They maintain a variety of tools, documentation, and " -"issue trackers on `GitHub `__." -msgstr "" -"`Python 封裝管理站 (Python Packaging Authority) `__ 是" -"一個由開發者和說明文件作者組成的團隊，負責維護及改進標準封裝工具，以及相關的" -"元資料 (metadata) 和檔案格式標準。他們在 `GitHub `__ 平台上維護各種工具、說明文件及問題追蹤系統。" - -#: ../../installing/index.rst:58 -msgid "" -"``distutils`` is the original build and distribution system first added to " -"the Python standard library in 1998. While direct use of ``distutils`` is " -"being phased out, it still laid the foundation for the current packaging and " -"distribution infrastructure, and it not only remains part of the standard " -"library, but its name lives on in other ways (such as the name of the " -"mailing list used to coordinate Python packaging standards development)." -msgstr "" -"``distutils`` 是最早的建置和發布系統，於 1998 年首次被加入 Python 標準函式" -"庫。雖然直接使用 ``distutils`` 的方式已經被逐步淘汰，它仍然是現今封裝和發布的" -"基礎結構根基，而且它不僅仍然是標準函式庫的一部分，它的名稱也以其他的方式存活" -"著（例如：用於協調 Python 封裝標準開發的郵寄清單就是以它命名）。" - -#: ../../installing/index.rst:66 -msgid "" -"The use of ``venv`` is now recommended for creating virtual environments." -msgstr "對於建立虛擬環境，現在推薦使用 ``venv``。" - -#: ../../installing/index.rst:71 -msgid "" -"`Python Packaging User Guide: Creating and using virtual environments " -"`__" -msgstr "" -"`Python 封裝使用者指南：建立和使用虛擬環境 `__" - -#: ../../installing/index.rst:76 -msgid "Basic usage" -msgstr "基本用法" - -#: ../../installing/index.rst:78 -msgid "" -"The standard packaging tools are all designed to be used from the command " -"line." -msgstr "標準封裝工具皆是以能從命令列使用的方式被設計的。" - -#: ../../installing/index.rst:81 -msgid "" -"The following command will install the latest version of a module and its " -"dependencies from the Python Package Index::" -msgstr "" -"以下指令將從 Python 套件索引安裝一個模組的最新版本及其依賴套件 " -"(dependencies)： ::" - -#: ../../installing/index.rst:84 -msgid "python -m pip install SomePackage" -msgstr "python -m pip install SomePackage" - -#: ../../installing/index.rst:88 -msgid "" -"For POSIX users (including macOS and Linux users), the examples in this " -"guide assume the use of a :term:`virtual environment`." -msgstr "" -"對於 POSIX 使用者（包括 macOS 和 Linux 使用者），本指南中的範例皆假設有使用 :" -"term:`virtual environment`。" - -#: ../../installing/index.rst:91 -msgid "" -"For Windows users, the examples in this guide assume that the option to " -"adjust the system PATH environment variable was selected when installing " -"Python." -msgstr "" -"對於 Windows 使用者，本指南中的範例皆假設在安裝 Python 時，「可調整系統 PATH " -"環境變數」的選項已被選取。" - -#: ../../installing/index.rst:95 -msgid "" -"It's also possible to specify an exact or minimum version directly on the " -"command line. When using comparator operators such as ``>``, ``<`` or some " -"other special character which get interpreted by shell, the package name and " -"the version should be enclosed within double quotes::" -msgstr "" -"在命令列中直接指定一個明確的或最小的版本也是可行的。當使用像是 ``>``、``<`` " -"的比較運算子，或某些可被 shell 所解釋的其他特殊字元時，套件名稱與版本編號應該" -"要放在雙引號內： ::" - -#: ../../installing/index.rst:100 -msgid "" -"python -m pip install SomePackage==1.0.4 # specific version\n" -"python -m pip install \"SomePackage>=1.0.4\" # minimum version" -msgstr "" -"python -m pip install SomePackage==1.0.4 # 明確版本\n" -"python -m pip install \"SomePackage>=1.0.4\" # 最小版本" - -#: ../../installing/index.rst:103 -msgid "" -"Normally, if a suitable module is already installed, attempting to install " -"it again will have no effect. Upgrading existing modules must be requested " -"explicitly::" -msgstr "" -"通常，如果一個合適的模組已被安裝，嘗試再次安裝它將不會有任何效果。要升級現有" -"的模組就必須明確地請求： ::" - -#: ../../installing/index.rst:107 -msgid "python -m pip install --upgrade SomePackage" -msgstr "python -m pip install --upgrade SomePackage" - -#: ../../installing/index.rst:109 -msgid "" -"More information and resources regarding ``pip`` and its capabilities can be " -"found in the `Python Packaging User Guide `__." -msgstr "" -"關於 ``pip`` 及其能力的更多資訊和資源，可以在 `Python 封裝使用者指南 " -"`__\\ 中找到。" - -#: ../../installing/index.rst:112 -msgid "" -"Creation of virtual environments is done through the :mod:`venv` module. " -"Installing packages into an active virtual environment uses the commands " -"shown above." -msgstr "" -"虛擬環境的建立是使用 :mod:`venv` 模組來完成。要在一個已啟用的虛擬環境中安裝套" -"件，可使用前面展示的指令。" - -#: ../../installing/index.rst:118 -msgid "" -"`Python Packaging User Guide: Installing Python Distribution Packages " -"`__" -msgstr "" -"`Python 封裝使用者指南：安裝 Python 發布套件 `__" - -#: ../../installing/index.rst:123 -msgid "How do I ...?" -msgstr "我該如何...？" - -#: ../../installing/index.rst:125 -msgid "These are quick answers or links for some common tasks." -msgstr "接下來是關於一些常見任務的快速解答或連結。" - -#: ../../installing/index.rst:128 -msgid "... install ``pip`` in versions of Python prior to Python 3.4?" -msgstr "...在 Python 3.4 之前的 Python 版本中安裝 ``pip``？" - -#: ../../installing/index.rst:130 -msgid "" -"Python only started bundling ``pip`` with Python 3.4. For earlier versions, " -"``pip`` needs to be \"bootstrapped\" as described in the Python Packaging " -"User Guide." -msgstr "" -"Python 是從 Python 3.4 才開始綁定 ``pip`` 的。對於更早的版本，``pip`` 需要被" -"「自助安裝 (bootstrapped)」，請參考 Python 封裝使用者指南中的說明。" - -#: ../../installing/index.rst:136 -msgid "" -"`Python Packaging User Guide: Requirements for Installing Packages `__" -msgstr "" -"`Python 封裝使用者指南：安裝套件的需求 `__" - -#: ../../installing/index.rst:143 -msgid "... install packages just for the current user?" -msgstr "...只為目前的使用者安裝套件？" - -#: ../../installing/index.rst:145 -msgid "" -"Passing the ``--user`` option to ``python -m pip install`` will install a " -"package just for the current user, rather than for all users of the system." -msgstr "" -"把 ``--user`` 選項傳給 ``python -m pip install``，這樣將會只為目前使用者而非" -"系統的所有使用者安裝套件。" - -#: ../../installing/index.rst:150 -msgid "... install scientific Python packages?" -msgstr "...安裝科學的 Python 套件？" - -#: ../../installing/index.rst:152 -msgid "" -"A number of scientific Python packages have complex binary dependencies, and " -"aren't currently easy to install using ``pip`` directly. At this point in " -"time, it will often be easier for users to install these packages by `other " -"means `__ rather than attempting to " -"install them with ``pip``." -msgstr "" -"許多科學類 Python 套件都有複雜的二進制依賴套件，且目前不太容易直接使用 " -"``pip`` 安裝。目前為止，使用\\ `其他方法 `__\\ 而非嘗試用 ``pip`` 來安裝它們，對使用者來說通常會更簡單。" - -#: ../../installing/index.rst:160 -msgid "" -"`Python Packaging User Guide: Installing Scientific Packages `__" -msgstr "" -"`Python 封裝使用者指南：安裝科學套件 `__" - -#: ../../installing/index.rst:165 -msgid "... work with multiple versions of Python installed in parallel?" -msgstr "...平行安裝多個 Python 版本並使用它們？" - -#: ../../installing/index.rst:167 -msgid "" -"On Linux, macOS, and other POSIX systems, use the versioned Python commands " -"in combination with the ``-m`` switch to run the appropriate copy of " -"``pip``::" -msgstr "" -"在 Linux、macOS 以及其他 POSIX 系統中，使用帶有版本編號的 Python 指令並結合 " -"``-m`` 開關參數 (switch)，來運行 ``pip`` 的適當副本： ::" - -#: ../../installing/index.rst:171 -msgid "" -"python2 -m pip install SomePackage # default Python 2\n" -"python2.7 -m pip install SomePackage # specifically Python 2.7\n" -"python3 -m pip install SomePackage # default Python 3\n" -"python3.4 -m pip install SomePackage # specifically Python 3.4" -msgstr "" -"python2 -m pip install SomePackage # 預設 Python 2\n" -"python2.7 -m pip install SomePackage # 指定 Python 2.7\n" -"python3 -m pip install SomePackage # 預設 Python 3\n" -"python3.4 -m pip install SomePackage # 指定 Python 3.4" - -#: ../../installing/index.rst:176 -msgid "Appropriately versioned ``pip`` commands may also be available." -msgstr "使用帶有合適版本編號的 ``pip`` 指令，也是可行的。" - -#: ../../installing/index.rst:178 -msgid "" -"On Windows, use the ``py`` Python launcher in combination with the ``-m`` " -"switch::" -msgstr "" -"在 Windows 中，使用 Python 啟動指令 ``py`` 並結合 ``-m`` 開關參數 " -"(switch)： ::" - -#: ../../installing/index.rst:181 -msgid "" -"py -2 -m pip install SomePackage # default Python 2\n" -"py -2.7 -m pip install SomePackage # specifically Python 2.7\n" -"py -3 -m pip install SomePackage # default Python 3\n" -"py -3.4 -m pip install SomePackage # specifically Python 3.4" -msgstr "" -"py -2 -m pip install SomePackage # 預設 Python 2\n" -"py -2.7 -m pip install SomePackage # 指定 Python 2.7\n" -"py -3 -m pip install SomePackage # 預設 Python 3\n" -"py -3.4 -m pip install SomePackage # 指定 Python 3.4" - -#: ../../installing/index.rst:195 -msgid "Common installation issues" -msgstr "常見的安裝問題" - -#: ../../installing/index.rst:198 -msgid "Installing into the system Python on Linux" -msgstr "在 Linux 上安裝套件至系統 Python" - -#: ../../installing/index.rst:200 -msgid "" -"On Linux systems, a Python installation will typically be included as part " -"of the distribution. Installing into this Python installation requires root " -"access to the system, and may interfere with the operation of the system " -"package manager and other components of the system if a component is " -"unexpectedly upgraded using ``pip``." -msgstr "" -"在 Linux 系統，Python 的某個安裝版本通常會被內含在 Linux 的發行版中。要安裝套" -"件到這個 Python 版本上需要系統的 root 權限，並且可能會干擾到系統套件管理器的" -"運作。如果其他系統組件非預期地以 ``pip`` 被升級，也會干擾這些組件的運作。" - -#: ../../installing/index.rst:206 -msgid "" -"On such systems, it is often better to use a virtual environment or a per-" -"user installation when installing packages with ``pip``." -msgstr "" -"在這樣的系統上，以 ``pip`` 安裝套件時，通常較好的方式是使用虛擬環境，或以個別" -"使用者安裝。" - -#: ../../installing/index.rst:211 -msgid "Pip not installed" -msgstr "未安裝 pip" - -#: ../../installing/index.rst:213 -msgid "" -"It is possible that ``pip`` does not get installed by default. One potential " -"fix is::" -msgstr "``pip`` 沒有預設被安裝也是有可能的。一個潛在的解法是： ::" - -#: ../../installing/index.rst:215 -msgid "python -m ensurepip --default-pip" -msgstr "python -m ensurepip --default-pip" - -#: ../../installing/index.rst:217 -msgid "" -"There are also additional resources for `installing pip. `__" -msgstr "" -"這裡還有其他關於\\ `安裝 pip `__\\ 的資源。" - -#: ../../installing/index.rst:222 -msgid "Installing binary extensions" -msgstr "安裝二進制擴充 (binary extension)" - -#: ../../installing/index.rst:224 -msgid "" -"Python has typically relied heavily on source based distribution, with end " -"users being expected to compile extension modules from source as part of the " -"installation process." -msgstr "" -"Python 基本上相當倚賴以原始碼為基礎的發布方式，也會期望使用者在安裝過程的某個" -"階段，從原始碼來編譯擴充模組。" - -#: ../../installing/index.rst:228 -msgid "" -"With the introduction of support for the binary ``wheel`` format, and the " -"ability to publish wheels for at least Windows and macOS through the Python " -"Package Index, this problem is expected to diminish over time, as users are " -"more regularly able to install pre-built extensions rather than needing to " -"build them themselves." -msgstr "" -"隨著引入對二進制 ``wheel`` 格式的支援，以及透過 Python 套件索引能夠至少在 " -"Windows 和 macOS 發布 wheel 檔案，這個問題預期將會逐漸消失，因為使用者將能夠" -"更頻繁地安裝預建置 (pre-built) 的擴充，而不再需要自己建置它們。" - -#: ../../installing/index.rst:234 -msgid "" -"Some of the solutions for installing `scientific software `__ that are not yet available as pre-built ``wheel`` " -"files may also help with obtaining other binary extensions without needing " -"to build them locally." -msgstr "" -"有一些解決方案，可用來安裝那些還無法以預建置的 ``wheel`` 檔案被使用的\\ `科學" -"軟體 `__，這些方案也有助於取得其他的二" -"進制擴充，且無需在本機對它們進行建置。" - -#: ../../installing/index.rst:241 -msgid "" -"`Python Packaging User Guide: Binary Extensions `__" -msgstr "" -"`Python 封裝使用者指南：二進制擴充 `__" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Leon H., 2017 +# 豆豆 (Tommy Lin) , 2017 +# Steven Hsu , 2021 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-09-03 11:11+0800\n" +"PO-Revision-Date: 2022-06-27 09:37+0800\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" +"X-Generator: Poedit 3.1\n" + +#: ../../installing/index.rst:7 +msgid "Installing Python Modules" +msgstr "安裝 Python 模組" + +#: ../../installing/index.rst:0 +msgid "Email" +msgstr "電子郵件" + +#: ../../installing/index.rst:9 +msgid "distutils-sig@python.org" +msgstr "distutils-sig@python.org" + +#: ../../installing/index.rst:11 +msgid "" +"As a popular open source development project, Python has an active " +"supporting community of contributors and users that also make their software " +"available for other Python developers to use under open source license terms." +msgstr "" +"作為一個普及的開源開發專案，Python 有一個活躍的支持社群，由其貢獻者及使用者組" +"成，而他們也讓他們的軟體可被其他 Python 開發者在開源授權條款下使用。" + +#: ../../installing/index.rst:15 +msgid "" +"This allows Python users to share and collaborate effectively, benefiting " +"from the solutions others have already created to common (and sometimes even " +"rare!) problems, as well as potentially contributing their own solutions to " +"the common pool." +msgstr "" +"這樣可以讓 Python 使用者們有效地共享和合作，並受益於其他人對常見（有時甚至是" +"罕見）的問題已經建立的解決方案，更可以在公用社群中潛在地貢獻他們自己的解決方" +"案。" + +#: ../../installing/index.rst:20 +msgid "" +"This guide covers the installation part of the process. For a guide to " +"creating and sharing your own Python projects, refer to the `Python " +"packaging user guide`_." +msgstr "" +"這份指南涵蓋了上述過程中的安裝部分。如果是要建立及分享你自己的 Python 專案，" +"請參考 `Python packaging user guide`_。" + +#: ../../installing/index.rst:28 +msgid "" +"For corporate and other institutional users, be aware that many " +"organisations have their own policies around using and contributing to open " +"source software. Please take such policies into account when making use of " +"the distribution and installation tools provided with Python." +msgstr "" +"對於企業和其他機構的使用者，要注意到，許多組織對於使用和貢獻開源軟體都有自己" +"的政策。在開始使用配備 Python 的發布及安裝工具時，請將那些政策納入考量。" + +#: ../../installing/index.rst:35 +msgid "Key terms" +msgstr "關鍵術語" + +#: ../../installing/index.rst:37 +msgid "" +"``pip`` is the preferred installer program. Starting with Python 3.4, it is " +"included by default with the Python binary installers." +msgstr "" +"``pip`` 是首選的安裝程式。從 Python 3.4 開始，它被預設包含在 Python 二進制安" +"裝程式中。" + +#: ../../installing/index.rst:39 +msgid "" +"A *virtual environment* is a semi-isolated Python environment that allows " +"packages to be installed for use by a particular application, rather than " +"being installed system wide." +msgstr "" +"*virtual environment（虛擬環境）*\\ 是一種半隔離的 Python 環境，可以為某個特" +"定應用程式安裝其所需的套件，而不用在整個系統上安裝它們。" + +#: ../../installing/index.rst:42 +msgid "" +"``venv`` is the standard tool for creating virtual environments, and has " +"been part of Python since Python 3.3. Starting with Python 3.4, it defaults " +"to installing ``pip`` into all created virtual environments." +msgstr "" +"``venv`` 是建立虛擬環境的標準工具，它從 Python 3.3 開始成為 Python 的一部分。" +"從 Python 3.4 開始，它會預設地安裝 ``pip`` 到所有被建立的虛擬環境。" + +#: ../../installing/index.rst:45 +msgid "" +"``virtualenv`` is a third party alternative (and predecessor) to ``venv``. " +"It allows virtual environments to be used on versions of Python prior to " +"3.4, which either don't provide ``venv`` at all, or aren't able to " +"automatically install ``pip`` into created environments." +msgstr "" +"``virtualenv`` 是 ``venv`` 的一個第三方替代方案（及其前身）。它使虛擬環境可以" +"在 Python 3.4 之前的版本被使用，那些版本要不是根本沒提供 ``venv``，就是無法自" +"動安裝 ``pip`` 到所建立的環境中。" + +#: ../../installing/index.rst:49 +msgid "" +"The `Python Package Index `__ is a public repository of " +"open source licensed packages made available for use by other Python users." +msgstr "" +"`Python 套件索引 (Python Package Index) `__ 是開源授權套件" +"的一個公共儲存庫，其中的套件皆可被其他 Python 使用者所使用。" + +#: ../../installing/index.rst:52 +msgid "" +"the `Python Packaging Authority `__ is the group of " +"developers and documentation authors responsible for the maintenance and " +"evolution of the standard packaging tools and the associated metadata and " +"file format standards. They maintain a variety of tools, documentation, and " +"issue trackers on `GitHub `__." +msgstr "" +"`Python 封裝管理站 (Python Packaging Authority) `__ 是" +"一個由開發者和說明文件作者組成的團隊，負責維護及改進標準封裝工具，以及相關的" +"元資料 (metadata) 和檔案格式標準。他們在 `GitHub `__ 平台上維護各種工具、說明文件及問題追蹤系統。" + +#: ../../installing/index.rst:58 +msgid "" +"``distutils`` is the original build and distribution system first added to " +"the Python standard library in 1998. While direct use of ``distutils`` is " +"being phased out, it still laid the foundation for the current packaging and " +"distribution infrastructure, and it not only remains part of the standard " +"library, but its name lives on in other ways (such as the name of the " +"mailing list used to coordinate Python packaging standards development)." +msgstr "" +"``distutils`` 是最早的建置和發布系統，於 1998 年首次被加入 Python 標準函式" +"庫。雖然直接使用 ``distutils`` 的方式已經被逐步淘汰，它仍然是現今封裝和發布的" +"基礎結構根基，而且它不僅仍然是標準函式庫的一部分，它的名稱也以其他的方式存活" +"著（例如：用於協調 Python 封裝標準開發的郵寄清單就是以它命名）。" + +#: ../../installing/index.rst:66 +msgid "" +"The use of ``venv`` is now recommended for creating virtual environments." +msgstr "對於建立虛擬環境，現在推薦使用 ``venv``。" + +#: ../../installing/index.rst:71 +msgid "" +"`Python Packaging User Guide: Creating and using virtual environments " +"`__" +msgstr "" +"`Python 封裝使用者指南：建立和使用虛擬環境 `__" + +#: ../../installing/index.rst:76 +msgid "Basic usage" +msgstr "基本用法" + +#: ../../installing/index.rst:78 +msgid "" +"The standard packaging tools are all designed to be used from the command " +"line." +msgstr "標準封裝工具皆是以能從命令列使用的方式被設計的。" + +#: ../../installing/index.rst:81 +msgid "" +"The following command will install the latest version of a module and its " +"dependencies from the Python Package Index::" +msgstr "" +"以下指令將從 Python 套件索引安裝一個模組的最新版本及其依賴套件 " +"(dependencies)： ::" + +#: ../../installing/index.rst:84 +msgid "python -m pip install SomePackage" +msgstr "python -m pip install SomePackage" + +#: ../../installing/index.rst:88 +msgid "" +"For POSIX users (including macOS and Linux users), the examples in this " +"guide assume the use of a :term:`virtual environment`." +msgstr "" +"對於 POSIX 使用者（包括 macOS 和 Linux 使用者），本指南中的範例皆假設有使用 :" +"term:`virtual environment`。" + +#: ../../installing/index.rst:91 +msgid "" +"For Windows users, the examples in this guide assume that the option to " +"adjust the system PATH environment variable was selected when installing " +"Python." +msgstr "" +"對於 Windows 使用者，本指南中的範例皆假設在安裝 Python 時，「可調整系統 PATH " +"環境變數」的選項已被選取。" + +#: ../../installing/index.rst:95 +msgid "" +"It's also possible to specify an exact or minimum version directly on the " +"command line. When using comparator operators such as ``>``, ``<`` or some " +"other special character which get interpreted by shell, the package name and " +"the version should be enclosed within double quotes::" +msgstr "" +"在命令列中直接指定一個明確的或最小的版本也是可行的。當使用像是 ``>``、``<`` " +"的比較運算子，或某些可被 shell 所解釋的其他特殊字元時，套件名稱與版本編號應該" +"要放在雙引號內： ::" + +#: ../../installing/index.rst:100 +msgid "" +"python -m pip install SomePackage==1.0.4 # specific version\n" +"python -m pip install \"SomePackage>=1.0.4\" # minimum version" +msgstr "" +"python -m pip install SomePackage==1.0.4 # 明確版本\n" +"python -m pip install \"SomePackage>=1.0.4\" # 最小版本" + +#: ../../installing/index.rst:103 +msgid "" +"Normally, if a suitable module is already installed, attempting to install " +"it again will have no effect. Upgrading existing modules must be requested " +"explicitly::" +msgstr "" +"通常，如果一個合適的模組已被安裝，嘗試再次安裝它將不會有任何效果。要升級現有" +"的模組就必須明確地請求： ::" + +#: ../../installing/index.rst:107 +msgid "python -m pip install --upgrade SomePackage" +msgstr "python -m pip install --upgrade SomePackage" + +#: ../../installing/index.rst:109 +msgid "" +"More information and resources regarding ``pip`` and its capabilities can be " +"found in the `Python Packaging User Guide `__." +msgstr "" +"關於 ``pip`` 及其能力的更多資訊和資源，可以在 `Python 封裝使用者指南 " +"`__\\ 中找到。" + +#: ../../installing/index.rst:112 +msgid "" +"Creation of virtual environments is done through the :mod:`venv` module. " +"Installing packages into an active virtual environment uses the commands " +"shown above." +msgstr "" +"虛擬環境的建立是使用 :mod:`venv` 模組來完成。要在一個已啟用的虛擬環境中安裝套" +"件，可使用前面展示的指令。" + +#: ../../installing/index.rst:118 +msgid "" +"`Python Packaging User Guide: Installing Python Distribution Packages " +"`__" +msgstr "" +"`Python 封裝使用者指南：安裝 Python 發布套件 `__" + +#: ../../installing/index.rst:123 +msgid "How do I ...?" +msgstr "我該如何...？" + +#: ../../installing/index.rst:125 +msgid "These are quick answers or links for some common tasks." +msgstr "接下來是關於一些常見任務的快速解答或連結。" + +#: ../../installing/index.rst:128 +msgid "... install ``pip`` in versions of Python prior to Python 3.4?" +msgstr "...在 Python 3.4 之前的 Python 版本中安裝 ``pip``？" + +#: ../../installing/index.rst:130 +msgid "" +"Python only started bundling ``pip`` with Python 3.4. For earlier versions, " +"``pip`` needs to be \"bootstrapped\" as described in the Python Packaging " +"User Guide." +msgstr "" +"Python 是從 Python 3.4 才開始綁定 ``pip`` 的。對於更早的版本，``pip`` 需要被" +"「自助安裝 (bootstrapped)」，請參考 Python 封裝使用者指南中的說明。" + +#: ../../installing/index.rst:136 +msgid "" +"`Python Packaging User Guide: Requirements for Installing Packages `__" +msgstr "" +"`Python 封裝使用者指南：安裝套件的需求 `__" + +#: ../../installing/index.rst:143 +msgid "... install packages just for the current user?" +msgstr "...只為目前的使用者安裝套件？" + +#: ../../installing/index.rst:145 +msgid "" +"Passing the ``--user`` option to ``python -m pip install`` will install a " +"package just for the current user, rather than for all users of the system." +msgstr "" +"把 ``--user`` 選項傳給 ``python -m pip install``，這樣將會只為目前使用者而非" +"系統的所有使用者安裝套件。" + +#: ../../installing/index.rst:150 +msgid "... install scientific Python packages?" +msgstr "...安裝科學的 Python 套件？" + +#: ../../installing/index.rst:152 +msgid "" +"A number of scientific Python packages have complex binary dependencies, and " +"aren't currently easy to install using ``pip`` directly. At this point in " +"time, it will often be easier for users to install these packages by `other " +"means `__ rather than attempting to " +"install them with ``pip``." +msgstr "" +"許多科學類 Python 套件都有複雜的二進制依賴套件，且目前不太容易直接使用 " +"``pip`` 安裝。目前為止，使用\\ `其他方法 `__\\ 而非嘗試用 ``pip`` 來安裝它們，對使用者來說通常會更簡單。" + +#: ../../installing/index.rst:160 +msgid "" +"`Python Packaging User Guide: Installing Scientific Packages `__" +msgstr "" +"`Python 封裝使用者指南：安裝科學套件 `__" + +#: ../../installing/index.rst:165 +msgid "... work with multiple versions of Python installed in parallel?" +msgstr "...平行安裝多個 Python 版本並使用它們？" + +#: ../../installing/index.rst:167 +msgid "" +"On Linux, macOS, and other POSIX systems, use the versioned Python commands " +"in combination with the ``-m`` switch to run the appropriate copy of " +"``pip``::" +msgstr "" +"在 Linux、macOS 以及其他 POSIX 系統中，使用帶有版本編號的 Python 指令並結合 " +"``-m`` 開關參數 (switch)，來運行 ``pip`` 的適當副本： ::" + +#: ../../installing/index.rst:171 +msgid "" +"python2 -m pip install SomePackage # default Python 2\n" +"python2.7 -m pip install SomePackage # specifically Python 2.7\n" +"python3 -m pip install SomePackage # default Python 3\n" +"python3.4 -m pip install SomePackage # specifically Python 3.4" +msgstr "" +"python2 -m pip install SomePackage # 預設 Python 2\n" +"python2.7 -m pip install SomePackage # 指定 Python 2.7\n" +"python3 -m pip install SomePackage # 預設 Python 3\n" +"python3.4 -m pip install SomePackage # 指定 Python 3.4" + +#: ../../installing/index.rst:176 +msgid "Appropriately versioned ``pip`` commands may also be available." +msgstr "使用帶有合適版本編號的 ``pip`` 指令，也是可行的。" + +#: ../../installing/index.rst:178 +msgid "" +"On Windows, use the ``py`` Python launcher in combination with the ``-m`` " +"switch::" +msgstr "" +"在 Windows 中，使用 Python 啟動指令 ``py`` 並結合 ``-m`` 開關參數 " +"(switch)： ::" + +#: ../../installing/index.rst:181 +msgid "" +"py -2 -m pip install SomePackage # default Python 2\n" +"py -2.7 -m pip install SomePackage # specifically Python 2.7\n" +"py -3 -m pip install SomePackage # default Python 3\n" +"py -3.4 -m pip install SomePackage # specifically Python 3.4" +msgstr "" +"py -2 -m pip install SomePackage # 預設 Python 2\n" +"py -2.7 -m pip install SomePackage # 指定 Python 2.7\n" +"py -3 -m pip install SomePackage # 預設 Python 3\n" +"py -3.4 -m pip install SomePackage # 指定 Python 3.4" + +#: ../../installing/index.rst:195 +msgid "Common installation issues" +msgstr "常見的安裝問題" + +#: ../../installing/index.rst:198 +msgid "Installing into the system Python on Linux" +msgstr "在 Linux 上安裝套件至系統 Python" + +#: ../../installing/index.rst:200 +msgid "" +"On Linux systems, a Python installation will typically be included as part " +"of the distribution. Installing into this Python installation requires root " +"access to the system, and may interfere with the operation of the system " +"package manager and other components of the system if a component is " +"unexpectedly upgraded using ``pip``." +msgstr "" +"在 Linux 系統，Python 的某個安裝版本通常會被內含在 Linux 的發行版中。要安裝套" +"件到這個 Python 版本上需要系統的 root 權限，並且可能會干擾到系統套件管理器的" +"運作。如果其他系統組件非預期地以 ``pip`` 被升級，也會干擾這些組件的運作。" + +#: ../../installing/index.rst:206 +msgid "" +"On such systems, it is often better to use a virtual environment or a per-" +"user installation when installing packages with ``pip``." +msgstr "" +"在這樣的系統上，以 ``pip`` 安裝套件時，通常較好的方式是使用虛擬環境，或以個別" +"使用者安裝。" + +#: ../../installing/index.rst:211 +msgid "Pip not installed" +msgstr "未安裝 pip" + +#: ../../installing/index.rst:213 +msgid "" +"It is possible that ``pip`` does not get installed by default. One potential " +"fix is::" +msgstr "``pip`` 沒有預設被安裝也是有可能的。一個潛在的解法是： ::" + +#: ../../installing/index.rst:215 +msgid "python -m ensurepip --default-pip" +msgstr "python -m ensurepip --default-pip" + +#: ../../installing/index.rst:217 +msgid "" +"There are also additional resources for `installing pip. `__" +msgstr "" +"這裡還有其他關於\\ `安裝 pip `__\\ 的資源。" + +#: ../../installing/index.rst:222 +msgid "Installing binary extensions" +msgstr "安裝二進制擴充 (binary extension)" + +#: ../../installing/index.rst:224 +msgid "" +"Python has typically relied heavily on source based distribution, with end " +"users being expected to compile extension modules from source as part of the " +"installation process." +msgstr "" +"Python 基本上相當倚賴以原始碼為基礎的發布方式，也會期望使用者在安裝過程的某個" +"階段，從原始碼來編譯擴充模組。" + +#: ../../installing/index.rst:228 +msgid "" +"With the introduction of support for the binary ``wheel`` format, and the " +"ability to publish wheels for at least Windows and macOS through the Python " +"Package Index, this problem is expected to diminish over time, as users are " +"more regularly able to install pre-built extensions rather than needing to " +"build them themselves." +msgstr "" +"隨著引入對二進制 ``wheel`` 格式的支援，以及透過 Python 套件索引能夠至少在 " +"Windows 和 macOS 發布 wheel 檔案，這個問題預期將會逐漸消失，因為使用者將能夠" +"更頻繁地安裝預建置 (pre-built) 的擴充，而不再需要自己建置它們。" + +#: ../../installing/index.rst:234 +msgid "" +"Some of the solutions for installing `scientific software `__ that are not yet available as pre-built ``wheel`` " +"files may also help with obtaining other binary extensions without needing " +"to build them locally." +msgstr "" +"有一些解決方案，可用來安裝那些還無法以預建置的 ``wheel`` 檔案被使用的\\ `科學" +"軟體 `__，這些方案也有助於取得其他的二" +"進制擴充，且無需在本機對它們進行建置。" + +#: ../../installing/index.rst:241 +msgid "" +"`Python Packaging User Guide: Binary Extensions `__" +msgstr "" +"`Python 封裝使用者指南：二進制擴充 `__" diff --git a/library/__future__.po b/library/__future__.po index 02cef9a695..a7b0a8fd0f 100644 --- a/library/__future__.po +++ b/library/__future__.po @@ -1,336 +1,336 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Matt Wang , 2023-2024 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: 2024-02-06 02:12+0000\n" -"Last-Translator: Matt Wang \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/__future__.rst:2 -msgid ":mod:`!__future__` --- Future statement definitions" -msgstr ":mod:`!__future__` --- Future 陳述式定義" - -#: ../../library/__future__.rst:7 -msgid "**Source code:** :source:`Lib/__future__.py`" -msgstr "**原始碼：**\\ :source:`Lib/__future__.py`" - -#: ../../library/__future__.rst:11 -msgid "" -"Imports of the form ``from __future__ import feature`` are " -"called :ref:`future statements `. These are special-cased by the " -"Python compiler to allow the use of new Python features in modules " -"containing the future statement before the release in which the feature " -"becomes standard." -msgstr "" -"``from __future__ import feature`` 形式的引入被稱為 :ref:`future 陳述式 " -"`。這些是 Python 編譯器的特殊情況，允許在該功能成為標準版本之前在包" -"含 future 陳述式的模組中使用新的 Python 功能。" - -#: ../../library/__future__.rst:16 -msgid "" -"While these future statements are given additional special meaning by the " -"Python compiler, they are still executed like any other import statement and " -"the :mod:`__future__` exists and is handled by the import system the same " -"way any other Python module would be. This design serves three purposes:" -msgstr "" -"雖然這些 future 陳述式被 Python 編譯器賦予了額外的特殊意義，但它們仍然像任何" -"其他 import 陳述式一樣執行，且 :mod:`__future__` 由引入系統以和任何其他 " -"Python 模組相同的方式處理。這個設計有三個目的：" - -#: ../../library/__future__.rst:21 -msgid "" -"To avoid confusing existing tools that analyze import statements and expect " -"to find the modules they're importing." -msgstr "為了避免混淆分析引入陳述式並預期要找到它們正在引入之模組的現有工具。" - -#: ../../library/__future__.rst:24 -msgid "" -"To document when incompatible changes were introduced, and when they will be " -"--- or were --- made mandatory. This is a form of executable documentation, " -"and can be inspected programmatically via importing :mod:`__future__` and " -"examining its contents." -msgstr "" -"記錄何時出現不相容的變更，以及何時開始強制執行這些變更。這是一種可執行文件的" -"形式，可以透過引入 :mod:`__future__` 並檢查其內容以程式化的方式進行檢查。" - -#: ../../library/__future__.rst:29 -msgid "" -"To ensure that :ref:`future statements ` run under releases prior to " -"Python 2.1 at least yield runtime exceptions (the import " -"of :mod:`__future__` will fail, because there was no module of that name " -"prior to 2.1)." -msgstr "" -"確保 :ref:`future 陳述式 `\\ 在 Python 2.1 之前的版本中運行至少會產" -"生 runtime 例外（\\ :mod:`__future__` 的引入將會失敗，因為 2.1 之前沒有該名稱" -"的模組）。" - -#: ../../library/__future__.rst:34 -msgid "Module Contents" -msgstr "模組內容" - -#: ../../library/__future__.rst:36 -msgid "" -"No feature description will ever be deleted from :mod:`__future__`. Since " -"its introduction in Python 2.1 the following features have found their way " -"into the language using this mechanism:" -msgstr "" -"不會從 :mod:`__future__` 中刪除任何功能描述。自從在 Python 2.1 中引入以來，以" -"下功能已透過這種機制引入到該語言中：" - -#: ../../library/__future__.rst:45 -msgid "feature" -msgstr "功能" - -#: ../../library/__future__.rst:46 -msgid "optional in" -msgstr "可選的版本" - -#: ../../library/__future__.rst:47 -msgid "mandatory in" -msgstr "強制性的版本" - -#: ../../library/__future__.rst:48 -msgid "effect" -msgstr "影響" - -#: ../../library/__future__.rst:50 -msgid "2.1.0b1" -msgstr "2.1.0b1" - -#: ../../library/__future__.rst:51 -msgid "2.2" -msgstr "2.2" - -#: ../../library/__future__.rst:52 -msgid ":pep:`227`: *Statically Nested Scopes*" -msgstr ":pep:`227`: *靜態巢狀作用域 (Statically Nested Scopes)*" - -#: ../../library/__future__.rst:54 -msgid "2.2.0a1" -msgstr "2.2.0a1" - -#: ../../library/__future__.rst:55 -msgid "2.3" -msgstr "2.3" - -#: ../../library/__future__.rst:56 -msgid ":pep:`255`: *Simple Generators*" -msgstr ":pep:`255`: *簡單產生器 (Simple Generators)*" - -#: ../../library/__future__.rst:58 -msgid "2.2.0a2" -msgstr "2.2.0a2" - -#: ../../library/__future__.rst:59 ../../library/__future__.rst:63 -#: ../../library/__future__.rst:71 ../../library/__future__.rst:75 -msgid "3.0" -msgstr "3.0" - -#: ../../library/__future__.rst:60 -msgid ":pep:`238`: *Changing the Division Operator*" -msgstr ":pep:`238`: *更改除法運算子 (Changing the Division Operator)*" - -#: ../../library/__future__.rst:62 ../../library/__future__.rst:66 -msgid "2.5.0a1" -msgstr "2.5.0a1" - -#: ../../library/__future__.rst:64 -msgid ":pep:`328`: *Imports: Multi-Line and Absolute/Relative*" -msgstr "" -":pep:`328`: *引入：多列與絕對/相對 (Imports: Multi-Line and Absolute/" -"Relative)*" - -#: ../../library/__future__.rst:67 -msgid "2.6" -msgstr "2.6" - -#: ../../library/__future__.rst:68 -msgid ":pep:`343`: *The “with” Statement*" -msgstr ":pep:`343`: *\"with\" 陳述式 (The \"with\" Statement)*" - -#: ../../library/__future__.rst:70 ../../library/__future__.rst:74 -msgid "2.6.0a2" -msgstr "2.6.0a2" - -#: ../../library/__future__.rst:72 -msgid ":pep:`3105`: *Make print a function*" -msgstr ":pep:`3105`: *使 print 成為一個函式 (Make print a function)*" - -#: ../../library/__future__.rst:76 -msgid ":pep:`3112`: *Bytes literals in Python 3000*" -msgstr "" -":pep:`3112`: *Python 3000 中的位元組字面值 (Bytes literals in Python 3000)*" - -#: ../../library/__future__.rst:78 -msgid "3.5.0b1" -msgstr "3.5.0b1" - -#: ../../library/__future__.rst:79 -msgid "3.7" -msgstr "3.7" - -#: ../../library/__future__.rst:80 -msgid ":pep:`479`: *StopIteration handling inside generators*" -msgstr "" -":pep:`479`: *產生器內部的 StopIteration 處理 (StopIteration handling inside " -"generators)*" - -#: ../../library/__future__.rst:82 -msgid "3.7.0b1" -msgstr "3.7.0b1" - -#: ../../library/__future__.rst:83 -msgid "Never [1]_" -msgstr "從未 [1]_" - -#: ../../library/__future__.rst:84 -msgid "" -":pep:`563`: *Postponed evaluation of annotations*, :pep:`649`: *Deferred " -"evaluation of annotations using descriptors*" -msgstr "" -":pep:`563`: *註釋的延後求值 (Postponed evaluation of annotations)*、:pep:" -"`649`: *使用描述器延遲求值註釋 (Deferred evaluation of annotations using " -"descriptors)*" - -#: ../../library/__future__.rst:93 -msgid "Each statement in :file:`__future__.py` is of the form::" -msgstr ":file:`__future__.py` 中的每個陳述式的形式如下： ::" - -#: ../../library/__future__.rst:95 -msgid "" -"FeatureName = _Feature(OptionalRelease, MandatoryRelease,\n" -" CompilerFlag)" -msgstr "" -"FeatureName = _Feature(OptionalRelease, MandatoryRelease,\n" -" CompilerFlag)" - -#: ../../library/__future__.rst:98 -msgid "" -"where, normally, *OptionalRelease* is less than *MandatoryRelease*, and both " -"are 5-tuples of the same form as :data:`sys.version_info`::" -msgstr "" -"通常，*OptionalRelease* 會小於 *MandatoryRelease*，且兩者都是" -"與 :data:`sys.version_info` 形式相同的 5 元組 (5-tuple)： ::" - -#: ../../library/__future__.rst:101 -msgid "" -"(PY_MAJOR_VERSION, # the 2 in 2.1.0a3; an int\n" -" PY_MINOR_VERSION, # the 1; an int\n" -" PY_MICRO_VERSION, # the 0; an int\n" -" PY_RELEASE_LEVEL, # \"alpha\", \"beta\", \"candidate\" or \"final\"; " -"string\n" -" PY_RELEASE_SERIAL # the 3; an int\n" -")" -msgstr "" -"(PY_MAJOR_VERSION, # 2.1.0a3 裡面的 2；為一整數\n" -" PY_MINOR_VERSION, # 1；為一整數\n" -" PY_MICRO_VERSION, # 0；為一整數\n" -" PY_RELEASE_LEVEL, # \"alpha\"、\"beta\"、\"candidate\" 或 \"final\"; ；為一" -"字串\n" -" PY_RELEASE_SERIAL # 3；為一整數\n" -")" - -#: ../../library/__future__.rst:110 -msgid "" -"*OptionalRelease* records the first release in which the feature was " -"accepted." -msgstr "*OptionalRelease* 記錄該功能首次發布時的 Python 版本。" - -#: ../../library/__future__.rst:114 -msgid "" -"In the case of a *MandatoryRelease* that has not yet occurred, " -"*MandatoryRelease* predicts the release in which the feature will become " -"part of the language." -msgstr "" -"如果 *MandatoryRelease* 尚未發布，*MandatoryRelease* 會預測該功能將成為該語言" -"一部分的版本。" - -#: ../../library/__future__.rst:118 -msgid "" -"Else *MandatoryRelease* records when the feature became part of the " -"language; in releases at or after that, modules no longer need a future " -"statement to use the feature in question, but may continue to use such " -"imports." -msgstr "" -"否則 *MandatoryRelease* 會記錄該功能是何時成為語言的一部分；在該版本或之後的" -"版本中，模組不再需要 future 聲明來使用相關功能，但可以繼續使用此種引入方式。" - -#: ../../library/__future__.rst:122 -msgid "" -"*MandatoryRelease* may also be ``None``, meaning that a planned feature got " -"dropped or that it is not yet decided." -msgstr "" -"*MandatoryRelease* 也可能是 ``None``，這意味著計劃中的功能被丟棄或者仍未決" -"定。" - -#: ../../library/__future__.rst:127 -msgid "" -"*CompilerFlag* is the (bitfield) flag that should be passed in the fourth " -"argument to the built-in function :func:`compile` to enable the feature in " -"dynamically compiled code. This flag is stored in " -"the :attr:`_Feature.compiler_flag` attribute on :class:`_Feature` instances." -msgstr "" -"*CompilerFlag* 是（位元欄位 (bitfield)）旗標，應在第四個引數中傳遞給內建函" -"式 :func:`compile` 以在動態編譯的程式碼中啟用該功能。此旗標儲存" -"在 :class:`_Feature` 實例上的 :attr:`_Feature.compiler_flag` 屬性中。" - -#: ../../library/__future__.rst:133 -msgid "" -"``from __future__ import annotations`` was previously scheduled to become " -"mandatory in Python 3.10, but the change was delayed and ultimately " -"canceled. This feature will eventually be deprecated and removed. " -"See :pep:`649` and :pep:`749`." -msgstr "" -"``from __future__ import annotations`` 原本預定在 Python 3.10 中成為強制性功" -"能，但該變更被延後並最終取消。此功能最終將被棄用並移除。請參閱 :pep:`649` " -"和 :pep:`749`。" - -#: ../../library/__future__.rst:141 -msgid ":ref:`future`" -msgstr ":ref:`future`" - -#: ../../library/__future__.rst:142 -msgid "How the compiler treats future imports." -msgstr "編譯器如何處理 future 引入。" - -#: ../../library/__future__.rst:144 -msgid ":pep:`236` - Back to the __future__" -msgstr ":pep:`236` - 回到 __future__" - -#: ../../library/__future__.rst:145 -msgid "The original proposal for the __future__ mechanism." -msgstr "__future__ 機制的原始提案。" - -#~ msgid ":pep:`563`: *Postponed evaluation of annotations*" -#~ msgstr "" -#~ ":pep:`563`: *推遲對註釋的求值 (Postponed evaluation of annotations)*" - -#~ msgid "" -#~ "``from __future__ import annotations`` was previously scheduled to become " -#~ "mandatory in Python 3.10, but the Python Steering Council twice decided " -#~ "to delay the change (`announcement for Python 3.10 `__; `announcement for Python 3.11 " -#~ "`__). No final decision has been made " -#~ "yet. See also :pep:`563` and :pep:`649`." -#~ msgstr "" -#~ "之前原本計劃在 Python 3.10 中強制使用 ``from __future__ import " -#~ "annotations``，但 Python 指導委員會 (Python Steering Council) 兩次決議推遲" -#~ "這一變動（`Python 3.10 的公告 `__；" -#~ "`Python 3.11 的公告 `__）。目前還尚未" -#~ "做出決定。另請參閱 :pep:`563` 和 :pep:`649`。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Matt Wang , 2023-2024 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: 2024-02-06 02:12+0000\n" +"Last-Translator: Matt Wang \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/__future__.rst:2 +msgid ":mod:`!__future__` --- Future statement definitions" +msgstr ":mod:`!__future__` --- Future 陳述式定義" + +#: ../../library/__future__.rst:7 +msgid "**Source code:** :source:`Lib/__future__.py`" +msgstr "**原始碼：**\\ :source:`Lib/__future__.py`" + +#: ../../library/__future__.rst:11 +msgid "" +"Imports of the form ``from __future__ import feature`` are " +"called :ref:`future statements `. These are special-cased by the " +"Python compiler to allow the use of new Python features in modules " +"containing the future statement before the release in which the feature " +"becomes standard." +msgstr "" +"``from __future__ import feature`` 形式的引入被稱為 :ref:`future 陳述式 " +"`。這些是 Python 編譯器的特殊情況，允許在該功能成為標準版本之前在包" +"含 future 陳述式的模組中使用新的 Python 功能。" + +#: ../../library/__future__.rst:16 +msgid "" +"While these future statements are given additional special meaning by the " +"Python compiler, they are still executed like any other import statement and " +"the :mod:`__future__` exists and is handled by the import system the same " +"way any other Python module would be. This design serves three purposes:" +msgstr "" +"雖然這些 future 陳述式被 Python 編譯器賦予了額外的特殊意義，但它們仍然像任何" +"其他 import 陳述式一樣執行，且 :mod:`__future__` 由引入系統以和任何其他 " +"Python 模組相同的方式處理。這個設計有三個目的：" + +#: ../../library/__future__.rst:21 +msgid "" +"To avoid confusing existing tools that analyze import statements and expect " +"to find the modules they're importing." +msgstr "為了避免混淆分析引入陳述式並預期要找到它們正在引入之模組的現有工具。" + +#: ../../library/__future__.rst:24 +msgid "" +"To document when incompatible changes were introduced, and when they will be " +"--- or were --- made mandatory. This is a form of executable documentation, " +"and can be inspected programmatically via importing :mod:`__future__` and " +"examining its contents." +msgstr "" +"記錄何時出現不相容的變更，以及何時開始強制執行這些變更。這是一種可執行文件的" +"形式，可以透過引入 :mod:`__future__` 並檢查其內容以程式化的方式進行檢查。" + +#: ../../library/__future__.rst:29 +msgid "" +"To ensure that :ref:`future statements ` run under releases prior to " +"Python 2.1 at least yield runtime exceptions (the import " +"of :mod:`__future__` will fail, because there was no module of that name " +"prior to 2.1)." +msgstr "" +"確保 :ref:`future 陳述式 `\\ 在 Python 2.1 之前的版本中運行至少會產" +"生 runtime 例外（\\ :mod:`__future__` 的引入將會失敗，因為 2.1 之前沒有該名稱" +"的模組）。" + +#: ../../library/__future__.rst:34 +msgid "Module Contents" +msgstr "模組內容" + +#: ../../library/__future__.rst:36 +msgid "" +"No feature description will ever be deleted from :mod:`__future__`. Since " +"its introduction in Python 2.1 the following features have found their way " +"into the language using this mechanism:" +msgstr "" +"不會從 :mod:`__future__` 中刪除任何功能描述。自從在 Python 2.1 中引入以來，以" +"下功能已透過這種機制引入到該語言中：" + +#: ../../library/__future__.rst:45 +msgid "feature" +msgstr "功能" + +#: ../../library/__future__.rst:46 +msgid "optional in" +msgstr "可選的版本" + +#: ../../library/__future__.rst:47 +msgid "mandatory in" +msgstr "強制性的版本" + +#: ../../library/__future__.rst:48 +msgid "effect" +msgstr "影響" + +#: ../../library/__future__.rst:50 +msgid "2.1.0b1" +msgstr "2.1.0b1" + +#: ../../library/__future__.rst:51 +msgid "2.2" +msgstr "2.2" + +#: ../../library/__future__.rst:52 +msgid ":pep:`227`: *Statically Nested Scopes*" +msgstr ":pep:`227`: *靜態巢狀作用域 (Statically Nested Scopes)*" + +#: ../../library/__future__.rst:54 +msgid "2.2.0a1" +msgstr "2.2.0a1" + +#: ../../library/__future__.rst:55 +msgid "2.3" +msgstr "2.3" + +#: ../../library/__future__.rst:56 +msgid ":pep:`255`: *Simple Generators*" +msgstr ":pep:`255`: *簡單產生器 (Simple Generators)*" + +#: ../../library/__future__.rst:58 +msgid "2.2.0a2" +msgstr "2.2.0a2" + +#: ../../library/__future__.rst:59 ../../library/__future__.rst:63 +#: ../../library/__future__.rst:71 ../../library/__future__.rst:75 +msgid "3.0" +msgstr "3.0" + +#: ../../library/__future__.rst:60 +msgid ":pep:`238`: *Changing the Division Operator*" +msgstr ":pep:`238`: *更改除法運算子 (Changing the Division Operator)*" + +#: ../../library/__future__.rst:62 ../../library/__future__.rst:66 +msgid "2.5.0a1" +msgstr "2.5.0a1" + +#: ../../library/__future__.rst:64 +msgid ":pep:`328`: *Imports: Multi-Line and Absolute/Relative*" +msgstr "" +":pep:`328`: *引入：多列與絕對/相對 (Imports: Multi-Line and Absolute/" +"Relative)*" + +#: ../../library/__future__.rst:67 +msgid "2.6" +msgstr "2.6" + +#: ../../library/__future__.rst:68 +msgid ":pep:`343`: *The “with” Statement*" +msgstr ":pep:`343`: *\"with\" 陳述式 (The \"with\" Statement)*" + +#: ../../library/__future__.rst:70 ../../library/__future__.rst:74 +msgid "2.6.0a2" +msgstr "2.6.0a2" + +#: ../../library/__future__.rst:72 +msgid ":pep:`3105`: *Make print a function*" +msgstr ":pep:`3105`: *使 print 成為一個函式 (Make print a function)*" + +#: ../../library/__future__.rst:76 +msgid ":pep:`3112`: *Bytes literals in Python 3000*" +msgstr "" +":pep:`3112`: *Python 3000 中的位元組字面值 (Bytes literals in Python 3000)*" + +#: ../../library/__future__.rst:78 +msgid "3.5.0b1" +msgstr "3.5.0b1" + +#: ../../library/__future__.rst:79 +msgid "3.7" +msgstr "3.7" + +#: ../../library/__future__.rst:80 +msgid ":pep:`479`: *StopIteration handling inside generators*" +msgstr "" +":pep:`479`: *產生器內部的 StopIteration 處理 (StopIteration handling inside " +"generators)*" + +#: ../../library/__future__.rst:82 +msgid "3.7.0b1" +msgstr "3.7.0b1" + +#: ../../library/__future__.rst:83 +msgid "Never [1]_" +msgstr "從未 [1]_" + +#: ../../library/__future__.rst:84 +msgid "" +":pep:`563`: *Postponed evaluation of annotations*, :pep:`649`: *Deferred " +"evaluation of annotations using descriptors*" +msgstr "" +":pep:`563`: *註釋的延後求值 (Postponed evaluation of annotations)*、:pep:" +"`649`: *使用描述器延遲求值註釋 (Deferred evaluation of annotations using " +"descriptors)*" + +#: ../../library/__future__.rst:93 +msgid "Each statement in :file:`__future__.py` is of the form::" +msgstr ":file:`__future__.py` 中的每個陳述式的形式如下： ::" + +#: ../../library/__future__.rst:95 +msgid "" +"FeatureName = _Feature(OptionalRelease, MandatoryRelease,\n" +" CompilerFlag)" +msgstr "" +"FeatureName = _Feature(OptionalRelease, MandatoryRelease,\n" +" CompilerFlag)" + +#: ../../library/__future__.rst:98 +msgid "" +"where, normally, *OptionalRelease* is less than *MandatoryRelease*, and both " +"are 5-tuples of the same form as :data:`sys.version_info`::" +msgstr "" +"通常，*OptionalRelease* 會小於 *MandatoryRelease*，且兩者都是" +"與 :data:`sys.version_info` 形式相同的 5 元組 (5-tuple)： ::" + +#: ../../library/__future__.rst:101 +msgid "" +"(PY_MAJOR_VERSION, # the 2 in 2.1.0a3; an int\n" +" PY_MINOR_VERSION, # the 1; an int\n" +" PY_MICRO_VERSION, # the 0; an int\n" +" PY_RELEASE_LEVEL, # \"alpha\", \"beta\", \"candidate\" or \"final\"; " +"string\n" +" PY_RELEASE_SERIAL # the 3; an int\n" +")" +msgstr "" +"(PY_MAJOR_VERSION, # 2.1.0a3 裡面的 2；為一整數\n" +" PY_MINOR_VERSION, # 1；為一整數\n" +" PY_MICRO_VERSION, # 0；為一整數\n" +" PY_RELEASE_LEVEL, # \"alpha\"、\"beta\"、\"candidate\" 或 \"final\"; ；為一" +"字串\n" +" PY_RELEASE_SERIAL # 3；為一整數\n" +")" + +#: ../../library/__future__.rst:110 +msgid "" +"*OptionalRelease* records the first release in which the feature was " +"accepted." +msgstr "*OptionalRelease* 記錄該功能首次發布時的 Python 版本。" + +#: ../../library/__future__.rst:114 +msgid "" +"In the case of a *MandatoryRelease* that has not yet occurred, " +"*MandatoryRelease* predicts the release in which the feature will become " +"part of the language." +msgstr "" +"如果 *MandatoryRelease* 尚未發布，*MandatoryRelease* 會預測該功能將成為該語言" +"一部分的版本。" + +#: ../../library/__future__.rst:118 +msgid "" +"Else *MandatoryRelease* records when the feature became part of the " +"language; in releases at or after that, modules no longer need a future " +"statement to use the feature in question, but may continue to use such " +"imports." +msgstr "" +"否則 *MandatoryRelease* 會記錄該功能是何時成為語言的一部分；在該版本或之後的" +"版本中，模組不再需要 future 聲明來使用相關功能，但可以繼續使用此種引入方式。" + +#: ../../library/__future__.rst:122 +msgid "" +"*MandatoryRelease* may also be ``None``, meaning that a planned feature got " +"dropped or that it is not yet decided." +msgstr "" +"*MandatoryRelease* 也可能是 ``None``，這意味著計劃中的功能被丟棄或者仍未決" +"定。" + +#: ../../library/__future__.rst:127 +msgid "" +"*CompilerFlag* is the (bitfield) flag that should be passed in the fourth " +"argument to the built-in function :func:`compile` to enable the feature in " +"dynamically compiled code. This flag is stored in " +"the :attr:`_Feature.compiler_flag` attribute on :class:`_Feature` instances." +msgstr "" +"*CompilerFlag* 是（位元欄位 (bitfield)）旗標，應在第四個引數中傳遞給內建函" +"式 :func:`compile` 以在動態編譯的程式碼中啟用該功能。此旗標儲存" +"在 :class:`_Feature` 實例上的 :attr:`_Feature.compiler_flag` 屬性中。" + +#: ../../library/__future__.rst:133 +msgid "" +"``from __future__ import annotations`` was previously scheduled to become " +"mandatory in Python 3.10, but the change was delayed and ultimately " +"canceled. This feature will eventually be deprecated and removed. " +"See :pep:`649` and :pep:`749`." +msgstr "" +"``from __future__ import annotations`` 原本預定在 Python 3.10 中成為強制性功" +"能，但該變更被延後並最終取消。此功能最終將被棄用並移除。請參閱 :pep:`649` " +"和 :pep:`749`。" + +#: ../../library/__future__.rst:141 +msgid ":ref:`future`" +msgstr ":ref:`future`" + +#: ../../library/__future__.rst:142 +msgid "How the compiler treats future imports." +msgstr "編譯器如何處理 future 引入。" + +#: ../../library/__future__.rst:144 +msgid ":pep:`236` - Back to the __future__" +msgstr ":pep:`236` - 回到 __future__" + +#: ../../library/__future__.rst:145 +msgid "The original proposal for the __future__ mechanism." +msgstr "__future__ 機制的原始提案。" + +#~ msgid ":pep:`563`: *Postponed evaluation of annotations*" +#~ msgstr "" +#~ ":pep:`563`: *推遲對註釋的求值 (Postponed evaluation of annotations)*" + +#~ msgid "" +#~ "``from __future__ import annotations`` was previously scheduled to become " +#~ "mandatory in Python 3.10, but the Python Steering Council twice decided " +#~ "to delay the change (`announcement for Python 3.10 `__; `announcement for Python 3.11 " +#~ "`__). No final decision has been made " +#~ "yet. See also :pep:`563` and :pep:`649`." +#~ msgstr "" +#~ "之前原本計劃在 Python 3.10 中強制使用 ``from __future__ import " +#~ "annotations``，但 Python 指導委員會 (Python Steering Council) 兩次決議推遲" +#~ "這一變動（`Python 3.10 的公告 `__；" +#~ "`Python 3.11 的公告 `__）。目前還尚未" +#~ "做出決定。另請參閱 :pep:`563` 和 :pep:`649`。" diff --git a/library/__main__.po b/library/__main__.po index 684307463a..5b0715eab3 100644 --- a/library/__main__.po +++ b/library/__main__.po @@ -1,711 +1,711 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: 2023-12-21 14:49+0800\n" -"Last-Translator: Liang-Bo Wang \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" -"X-Generator: Poedit 3.4\n" - -#: ../../library/__main__.rst:2 -msgid ":mod:`!__main__` --- Top-level code environment" -msgstr ":mod:`!__main__` --- 頂層程式碼環境" - -#: ../../library/__main__.rst:10 -msgid "" -"In Python, the special name ``__main__`` is used for two important " -"constructs:" -msgstr "在 Python 中，特殊名稱 ``__main__`` 用於兩個重要的建構：" - -#: ../../library/__main__.rst:12 -msgid "" -"the name of the top-level environment of the program, which can be checked " -"using the ``__name__ == '__main__'`` expression; and" -msgstr "" -"程式頂層環境的名稱，可以使用 ``__name__ == '__main__'`` 運算式進行檢查；和" - -#: ../../library/__main__.rst:14 -msgid "the ``__main__.py`` file in Python packages." -msgstr "在 Python 套件中的 ``__main__.py`` 檔案。" - -#: ../../library/__main__.rst:16 -msgid "" -"Both of these mechanisms are related to Python modules; how users interact " -"with them and how they interact with each other. They are explained in " -"detail below. If you're new to Python modules, see the tutorial " -"section :ref:`tut-modules` for an introduction." -msgstr "" -"這兩種機制都與 Python 模組有關；使用者如何與它們互動以及它們如何彼此互動。下" -"面會詳細解釋它們。如果你不熟悉 Python 模組，請參閱教學章節 :ref:`tut-" -"modules` 的介紹。" - -#: ../../library/__main__.rst:25 -msgid "``__name__ == '__main__'``" -msgstr "``__name__ == '__main__'``" - -#: ../../library/__main__.rst:27 -msgid "" -"When a Python module or package is imported, ``__name__`` is set to the " -"module's name. Usually, this is the name of the Python file itself without " -"the ``.py`` extension::" -msgstr "" -"當引入 Python 模組或套件時，``__name__`` 設定為模組的名稱。通常來說，這是 " -"Python 檔案本身的名稱，且不含 .py 副檔名： ::" - -#: ../../library/__main__.rst:31 -msgid "" -">>> import configparser\n" -">>> configparser.__name__\n" -"'configparser'" -msgstr "" -">>> import configparser\n" -">>> configparser.__name__\n" -"'configparser'" - -#: ../../library/__main__.rst:35 -msgid "" -"If the file is part of a package, ``__name__`` will also include the parent " -"package's path::" -msgstr "" -"如果檔案是套件的一部分，則 ``__name__`` 也會包含父套件 (parent package) 的路" -"徑： ::" - -#: ../../library/__main__.rst:38 -msgid "" -">>> from concurrent.futures import process\n" -">>> process.__name__\n" -"'concurrent.futures.process'" -msgstr "" -">>> from concurrent.futures import process\n" -">>> process.__name__\n" -"'concurrent.futures.process'" - -#: ../../library/__main__.rst:42 -msgid "" -"However, if the module is executed in the top-level code environment, its " -"``__name__`` is set to the string ``'__main__'``." -msgstr "" -"但是，如果模組在頂層程式碼環境中執行，則其 ``__name__`` 將被設定為字串 " -"``'__main__'``。" - -#: ../../library/__main__.rst:46 -msgid "What is the \"top-level code environment\"?" -msgstr "什麼是「頂層程式碼環境」？" - -#: ../../library/__main__.rst:48 -msgid "" -"``__main__`` is the name of the environment where top-level code is run. " -"\"Top-level code\" is the first user-specified Python module that starts " -"running. It's \"top-level\" because it imports all other modules that the " -"program needs. Sometimes \"top-level code\" is called an *entry point* to " -"the application." -msgstr "" -"``__main__`` 是執行頂層程式碼的環境名稱。「頂層程式碼」是使用者指定且第一個開" -"始運作的 Python 模組。它是「頂層」的原因是因為它引入程式所需的所有其他模組。" -"有時「頂層程式碼」被稱為應用程式的\\ *入口點*。" - -#: ../../library/__main__.rst:53 -msgid "The top-level code environment can be:" -msgstr "頂層程式碼環境可以是：" - -#: ../../library/__main__.rst:55 -msgid "the scope of an interactive prompt::" -msgstr "互動式提示字元的作用域： ::" - -#: ../../library/__main__.rst:57 -msgid "" -">>> __name__\n" -"'__main__'" -msgstr "" -">>> __name__\n" -"'__main__'" - -#: ../../library/__main__.rst:60 -msgid "the Python module passed to the Python interpreter as a file argument:" -msgstr "將 Python 模組作為檔案引數傳遞給 Python 直譯器：" - -#: ../../library/__main__.rst:62 -msgid "" -"$ python helloworld.py\n" -"Hello, world!" -msgstr "" -"$ python helloworld.py\n" -"Hello, world!" - -#: ../../library/__main__.rst:67 -msgid "" -"the Python module or package passed to the Python interpreter with " -"the :option:`-m` argument:" -msgstr "使用 :option:`-m` 引數傳遞給 Python 直譯器的 Python 模組或套件：" - -#: ../../library/__main__.rst:70 -msgid "" -"$ python -m tarfile\n" -"usage: tarfile.py [-h] [-v] (...)" -msgstr "" -"$ python -m tarfile\n" -"usage: tarfile.py [-h] [-v] (...)" - -#: ../../library/__main__.rst:75 -msgid "Python code read by the Python interpreter from standard input:" -msgstr "Python 直譯器從標準輸入讀取 Python 程式碼：" - -#: ../../library/__main__.rst:77 -msgid "" -"$ echo \"import this\" | python\n" -"The Zen of Python, by Tim Peters\n" -"\n" -"Beautiful is better than ugly.\n" -"Explicit is better than implicit.\n" -"..." -msgstr "" -"$ echo \"import this\" | python\n" -"The Zen of Python, by Tim Peters\n" -"\n" -"Beautiful is better than ugly.\n" -"Explicit is better than implicit.\n" -"..." - -#: ../../library/__main__.rst:86 -msgid "" -"Python code passed to the Python interpreter with the :option:`-c` argument:" -msgstr "使用 :option:`-c` 引數傳遞給 Python 直譯器的 Python 程式碼：" - -#: ../../library/__main__.rst:88 -msgid "" -"$ python -c \"import this\"\n" -"The Zen of Python, by Tim Peters\n" -"\n" -"Beautiful is better than ugly.\n" -"Explicit is better than implicit.\n" -"..." -msgstr "" -"$ python -c \"import this\"\n" -"The Zen of Python, by Tim Peters\n" -"\n" -"Beautiful is better than ugly.\n" -"Explicit is better than implicit.\n" -"..." - -#: ../../library/__main__.rst:97 -msgid "" -"In each of these situations, the top-level module's ``__name__`` is set to " -"``'__main__'``." -msgstr "在這些情況下，頂層模組的 ``__name__`` 都會設定為 ``'__main__'``。" - -#: ../../library/__main__.rst:100 -msgid "" -"As a result, a module can discover whether or not it is running in the top-" -"level environment by checking its own ``__name__``, which allows a common " -"idiom for conditionally executing code when the module is not initialized " -"from an import statement::" -msgstr "" -"因此，模組可以透過檢查自己的 ``__name__`` 來發現它是否在頂層環境中執行，這允" -"許當模組未從 import 陳述式初始化時，使用常見的慣用語法 (idiom) 來有條件地執行" -"程式碼： ::" - -#: ../../library/__main__.rst:105 -msgid "" -"if __name__ == '__main__':\n" -" # Execute when the module is not initialized from an import statement.\n" -" ..." -msgstr "" - -#: ../../library/__main__.rst:111 -msgid "" -"For a more detailed look at how ``__name__`` is set in all situations, see " -"the tutorial section :ref:`tut-modules`." -msgstr "" -"若要更詳細地了解如何在所有情況下設定 ``__name__``，請參閱教學章節 :ref:`tut-" -"modules`。" - -#: ../../library/__main__.rst:116 ../../library/__main__.rst:239 -msgid "Idiomatic Usage" -msgstr "慣用 (Idiomatic) 用法" - -#: ../../library/__main__.rst:118 -msgid "" -"Some modules contain code that is intended for script use only, like parsing " -"command-line arguments or fetching data from standard input. If a module " -"like this was imported from a different module, for example to unit test it, " -"the script code would unintentionally execute as well." -msgstr "" -"某些模組包含僅供腳本使用的程式碼，例如剖析命令列引數或從標準輸入取得資料。如" -"果從不同的模組匯入這樣的模組（例如對其進行單元測試 (unit test)），則腳本程式" -"碼也會無意間執行。" - -#: ../../library/__main__.rst:123 -msgid "" -"This is where using the ``if __name__ == '__main__'`` code block comes in " -"handy. Code within this block won't run unless the module is executed in the " -"top-level environment." -msgstr "" -"這就是使用 ``if __name__ == '__main__'`` 程式碼區塊派上用場的地方。除非該模組" -"在頂層環境中執行，否則此區塊中的程式碼不會執行。" - -#: ../../library/__main__.rst:127 -msgid "" -"Putting as few statements as possible in the block below ``if __name__ == " -"'__main__'`` can improve code clarity and correctness. Most often, a " -"function named ``main`` encapsulates the program's primary behavior::" -msgstr "" -"在 ``if __name__ == '__main__'`` 下面的區塊中放置盡可能少的陳述式可以提高程式" -"碼的清晰度和正確性。大多數情況下，名為 ``main`` 的函式封裝 (encapsulate) 了程" -"式的主要行為： ::" - -#: ../../library/__main__.rst:131 -msgid "" -"# echo.py\n" -"\n" -"import shlex\n" -"import sys\n" -"\n" -"def echo(phrase: str) -> None:\n" -" \"\"\"A dummy wrapper around print.\"\"\"\n" -" # for demonstration purposes, you can imagine that there is some\n" -" # valuable and reusable logic inside this function\n" -" print(phrase)\n" -"\n" -"def main() -> int:\n" -" \"\"\"Echo the input arguments to standard output\"\"\"\n" -" phrase = shlex.join(sys.argv)\n" -" echo(phrase)\n" -" return 0\n" -"\n" -"if __name__ == '__main__':\n" -" sys.exit(main()) # next section explains the use of sys.exit" -msgstr "" - -#: ../../library/__main__.rst:151 -msgid "" -"Note that if the module didn't encapsulate code inside the ``main`` function " -"but instead put it directly within the ``if __name__ == '__main__'`` block, " -"the ``phrase`` variable would be global to the entire module. This is error-" -"prone as other functions within the module could be unintentionally using " -"the global variable instead of a local name. A ``main`` function solves " -"this problem." -msgstr "" -"請注意，如果模組沒有將程式碼封裝在 ``main`` 函式中，而是直接將其放在 ``if " -"__name__ == '__main__'`` 區塊中，則 ``phrase`` 變數對於整個模組來說將是全域" -"的。這很容易出錯，因為模組中的其他函式可能會無意中使用此全域變數而不是區域變" -"數。``main`` 函式解決了這個問題。" - -#: ../../library/__main__.rst:158 -msgid "" -"Using a ``main`` function has the added benefit of the ``echo`` function " -"itself being isolated and importable elsewhere. When ``echo.py`` is " -"imported, the ``echo`` and ``main`` functions will be defined, but neither " -"of them will be called, because ``__name__ != '__main__'``." -msgstr "" -"使用 ``main`` 函式還有一個額外的好處，``echo`` 函式本身是隔離的 (isolated) 並" -"且可以在其他地方引入。當引入 ``echo.py`` 時，``echo`` 和 ``main`` 函式將被定" -"義，但它們都不會被呼叫，因為 ``__name__ != '__main__'``。" - -#: ../../library/__main__.rst:165 -msgid "Packaging Considerations" -msgstr "打包時須考慮的事情" - -#: ../../library/__main__.rst:167 -msgid "" -"``main`` functions are often used to create command-line tools by specifying " -"them as entry points for console scripts. When this is done, `pip `_ inserts the function call into a template script, where the " -"return value of ``main`` is passed into :func:`sys.exit`. For example::" -msgstr "" -"``main`` 函式通常用於透過將它們指定為控制台腳本的入口點來建立命令列工具。完成" -"後，`pip `_ 將函式呼叫插入到模板腳本中，其中 ``main`` " -"的回傳值被傳遞到 :func:`sys.exit` 中。例如： ::" - -#: ../../library/__main__.rst:173 -msgid "sys.exit(main())" -msgstr "sys.exit(main())" - -#: ../../library/__main__.rst:175 -msgid "" -"Since the call to ``main`` is wrapped in :func:`sys.exit`, the expectation " -"is that your function will return some value acceptable as an input " -"to :func:`sys.exit`; typically, an integer or ``None`` (which is implicitly " -"returned if your function does not have a return statement)." -msgstr "" -"由於對 ``main`` 的呼叫包含在 :func:`sys.exit` 中，因此期望你的函式將傳回一些" -"可接受作為 :func:`sys.exit` 輸入的值；通常來說，會是一個整數或 ``None``\\（如" -"果你的函式沒有 return 陳述式，則相當於回傳此值）。" - -#: ../../library/__main__.rst:180 -msgid "" -"By proactively following this convention ourselves, our module will have the " -"same behavior when run directly (i.e. ``python echo.py``) as it will have if " -"we later package it as a console script entry-point in a pip-installable " -"package." -msgstr "" -"透過我們自己主動遵循這個慣例，我們的模組在直接執行時（即 ``python echo.py``）" -"的行為，將和我們稍後將其打包為 pip 可安裝套件中的控制台腳本入口點相同。" - -#: ../../library/__main__.rst:185 -msgid "" -"In particular, be careful about returning strings from your ``main`` " -"function. :func:`sys.exit` will interpret a string argument as a failure " -"message, so your program will have an exit code of ``1``, indicating " -"failure, and the string will be written to :data:`sys.stderr`. The " -"``echo.py`` example from earlier exemplifies using the ``sys.exit(main())`` " -"convention." -msgstr "" -"特別是，要謹慎處理從 ``main`` 函式回傳字串。:func:`sys.exit` 會將字串引數直譯" -"為失敗訊息，因此你的程式將有一個表示失敗的結束代碼 ``1``，並且該字串將被寫" -"入 :data:`sys.stderr`。前面的 ``echo.py`` 範例使用慣例的 " -"``sys.exit(main())`` 進行示範。" - -#: ../../library/__main__.rst:193 -msgid "" -"`Python Packaging User Guide `_ contains a " -"collection of tutorials and references on how to distribute and install " -"Python packages with modern tools." -msgstr "" -"`Python 打包使用者指南 `_\\ 包含一系列如何使用" -"現代工具發行和安裝 Python 套件的教學和參考資料。" - -#: ../../library/__main__.rst:199 -msgid "``__main__.py`` in Python Packages" -msgstr "Python 套件中的 ``__main__.py``" - -#: ../../library/__main__.rst:201 -msgid "" -"If you are not familiar with Python packages, see section :ref:`tut-" -"packages` of the tutorial. Most commonly, the ``__main__.py`` file is used " -"to provide a command-line interface for a package. Consider the following " -"hypothetical package, \"bandclass\":" -msgstr "" -"如果你不熟悉 Python 套件，請參閱 :ref:`tut-packages` 的教學章節。最常見的是，" -"``__main__.py`` 檔案用於為套件提供命令列介面。假設下面有虛構的套件 " -"\"bandclass\"：" - -#: ../../library/__main__.rst:206 -msgid "" -"bandclass\n" -" ├── __init__.py\n" -" ├── __main__.py\n" -" └── student.py" -msgstr "" -"bandclass\n" -" ├── __init__.py\n" -" ├── __main__.py\n" -" └── student.py" - -#: ../../library/__main__.rst:213 -msgid "" -"``__main__.py`` will be executed when the package itself is invoked directly " -"from the command line using the :option:`-m` flag. For example:" -msgstr "" -"當使用 :option:`-m` 旗標 (flag) 直接從命令列呼叫套件本身時，將執行 " -"``__main__.py``。例如：" - -#: ../../library/__main__.rst:216 -msgid "$ python -m bandclass" -msgstr "$ python -m bandclass" - -#: ../../library/__main__.rst:220 -msgid "" -"This command will cause ``__main__.py`` to run. How you utilize this " -"mechanism will depend on the nature of the package you are writing, but in " -"this hypothetical case, it might make sense to allow the teacher to search " -"for students::" -msgstr "" -"該命令將導致 ``__main__.py`` 執行。如何利用此機制將取決於你正在編寫的套件的性" -"質，但在這種虛構的情況下，允許教師搜尋學生可能是有意義的： ::" - -#: ../../library/__main__.rst:225 -msgid "" -"# bandclass/__main__.py\n" -"\n" -"import sys\n" -"from .student import search_students\n" -"\n" -"student_name = sys.argv[1] if len(sys.argv) >= 2 else ''\n" -"print(f'Found student: {search_students(student_name)}')" -msgstr "" -"# bandclass/__main__.py\n" -"\n" -"import sys\n" -"from .student import search_students\n" -"\n" -"student_name = sys.argv[1] if len(sys.argv) >= 2 else ''\n" -"print(f'Found student: {search_students(student_name)}')" - -#: ../../library/__main__.rst:233 -msgid "" -"Note that ``from .student import search_students`` is an example of a " -"relative import. This import style can be used when referencing modules " -"within a package. For more details, see :ref:`intra-package-references` in " -"the :ref:`tut-modules` section of the tutorial." -msgstr "" -"請注意，``from .student import search_students`` 是相對引入的範例。在引用套件" -"內的模組時，可以使用此引入樣式。有關更多詳細資訊，請參閱 :ref:`tut-modules` " -"教學章節中的 :ref:`intra-package-references`。" - -#: ../../library/__main__.rst:241 -msgid "" -"The content of ``__main__.py`` typically isn't fenced with an ``if __name__ " -"== '__main__'`` block. Instead, those files are kept short and import " -"functions to execute from other modules. Those other modules can then be " -"easily unit-tested and are properly reusable." -msgstr "" -"``__main__.py`` 的內容通常不會被 ``if __name__ == '__main__'`` 區塊包圍。相反" -"的，這些檔案保持簡短並引入其他模組的函式來執行。那些其他模組就可以輕鬆地進行" -"單元測試並且可以正確地重複使用。" - -#: ../../library/__main__.rst:246 -msgid "" -"If used, an ``if __name__ == '__main__'`` block will still work as expected " -"for a ``__main__.py`` file within a package, because its ``__name__`` " -"attribute will include the package's path if imported::" -msgstr "" -"如果在套件裡面的 ``__main__.py`` 檔案使用 ``if __name__ == '__main__'`` 區" -"塊，它依然會如預期般地運作。因為當引入套件，其 ``__name__`` 屬性將會包含套件" -"的路徑： ::" - -#: ../../library/__main__.rst:250 -msgid "" -">>> import asyncio.__main__\n" -">>> asyncio.__main__.__name__\n" -"'asyncio.__main__'" -msgstr "" -">>> import asyncio.__main__\n" -">>> asyncio.__main__.__name__\n" -"'asyncio.__main__'" - -#: ../../library/__main__.rst:254 -msgid "" -"This won't work for ``__main__.py`` files in the root directory of a " -"``.zip`` file though. Hence, for consistency, a minimal ``__main__.py`` " -"without a ``__name__`` check is preferred." -msgstr "" -"但這對於 ``.zip`` 檔案根目錄中的 ``__main__.py`` 檔案不起作用。因此，為了保持" -"一致性，最小的、沒有 ``__name__`` 檢查的 ``__main__.py`` 會是首選。" - -#: ../../library/__main__.rst:260 -msgid "" -"See :mod:`venv` for an example of a package with a minimal ``__main__.py`` " -"in the standard library. It doesn't contain a ``if __name__ == '__main__'`` " -"block. You can invoke it with ``python -m venv [directory]``." -msgstr "" -"請參閱 :mod:`venv` 作為標準函式庫中具有最小 ``__main__.py`` 的套件為範例。它" -"不包含 ``if __name__ == '__main__'`` 區塊。你可以使用 ``python -m venv " -"[directory]`` 來呼叫它。" - -#: ../../library/__main__.rst:264 -msgid "" -"See :mod:`runpy` for more details on the :option:`-m` flag to the " -"interpreter executable." -msgstr "" -"請參閱 :mod:`runpy` 取得有關直譯器可執行檔的 :option:`-m` 旗標的更多詳細資" -"訊。" - -#: ../../library/__main__.rst:267 -msgid "" -"See :mod:`zipapp` for how to run applications packaged as *.zip* files. In " -"this case Python looks for a ``__main__.py`` file in the root directory of " -"the archive." -msgstr "" -"請參閱 :mod:`zipapp` 了解如何執行打包成 *.zip* 檔案的應用程式。在這種情況下，" -"Python 會在封存檔案的根目錄中尋找 ``__main__.py`` 檔案。" - -#: ../../library/__main__.rst:274 -msgid "``import __main__``" -msgstr "``import __main__``" - -#: ../../library/__main__.rst:276 -msgid "" -"Regardless of which module a Python program was started with, other modules " -"running within that same program can import the top-level environment's " -"scope (:term:`namespace`) by importing the ``__main__`` module. This " -"doesn't import a ``__main__.py`` file but rather whichever module that " -"received the special name ``'__main__'``." -msgstr "" -"無論 Python 程式是從哪個模組啟動的，在同一程式中執行的其他模組都可以透過匯入 " -"``__main__`` 模組來引入頂層環境的作用域 (:term:`namespace`)。這不會引入 " -"``__main__.py`` 檔案，而是引入接收特殊名稱 ``'__main__'`` 的模組。" - -#: ../../library/__main__.rst:282 -msgid "Here is an example module that consumes the ``__main__`` namespace::" -msgstr "這是一個使用 ``__main__`` 命名空間的範例模組：" - -#: ../../library/__main__.rst:284 -msgid "" -"# namely.py\n" -"\n" -"import __main__\n" -"\n" -"def did_user_define_their_name():\n" -" return 'my_name' in dir(__main__)\n" -"\n" -"def print_user_name():\n" -" if not did_user_define_their_name():\n" -" raise ValueError('Define the variable `my_name`!')\n" -"\n" -" print(__main__.my_name)" -msgstr "" -"# namely.py\n" -"\n" -"import __main__\n" -"\n" -"def did_user_define_their_name():\n" -" return 'my_name' in dir(__main__)\n" -"\n" -"def print_user_name():\n" -" if not did_user_define_their_name():\n" -" raise ValueError('Define the variable `my_name`!')\n" -"\n" -" print(__main__.my_name)" - -#: ../../library/__main__.rst:297 -msgid "Example usage of this module could be as follows::" -msgstr "該模組的範例用法如下： ::" - -#: ../../library/__main__.rst:299 -msgid "" -"# start.py\n" -"\n" -"import sys\n" -"\n" -"from namely import print_user_name\n" -"\n" -"# my_name = \"Dinsdale\"\n" -"\n" -"def main():\n" -" try:\n" -" print_user_name()\n" -" except ValueError as ve:\n" -" return str(ve)\n" -"\n" -"if __name__ == \"__main__\":\n" -" sys.exit(main())" -msgstr "" -"# start.py\n" -"\n" -"import sys\n" -"\n" -"from namely import print_user_name\n" -"\n" -"# my_name = \"Dinsdale\"\n" -"\n" -"def main():\n" -" try:\n" -" print_user_name()\n" -" except ValueError as ve:\n" -" return str(ve)\n" -"\n" -"if __name__ == \"__main__\":\n" -" sys.exit(main())" - -#: ../../library/__main__.rst:316 -msgid "Now, if we started our program, the result would look like this:" -msgstr "現在，如果我們啟動程式，結果將如下所示：" - -#: ../../library/__main__.rst:318 -msgid "" -"$ python start.py\n" -"Define the variable `my_name`!" -msgstr "" -"$ python start.py\n" -"Define the variable `my_name`!" - -#: ../../library/__main__.rst:323 -msgid "" -"The exit code of the program would be 1, indicating an error. Uncommenting " -"the line with ``my_name = \"Dinsdale\"`` fixes the program and now it exits " -"with status code 0, indicating success:" -msgstr "" -"程式的結束代碼將為 1，表示出現錯誤。取消註解 ``my_name = \"Dinsdale\"`` 而修" -"復程式後，現在它以狀態碼 0 結束，表示成功：" - -#: ../../library/__main__.rst:327 -msgid "" -"$ python start.py\n" -"Dinsdale" -msgstr "" -"$ python start.py\n" -"Dinsdale" - -#: ../../library/__main__.rst:332 -msgid "" -"Note that importing ``__main__`` doesn't cause any issues with " -"unintentionally running top-level code meant for script use which is put in " -"the ``if __name__ == \"__main__\"`` block of the ``start`` module. Why does " -"this work?" -msgstr "" -"請注意，引入 ``__main__`` 並不會因為不經意地執行放在 ``start`` 模組中 ``if " -"__name__ == \"__main__\"`` 區塊的頂層程式碼（本來是給腳本使用的）而造成任何問" -"題。為什麼這樣做會如預期運作？" - -#: ../../library/__main__.rst:336 -msgid "" -"Python inserts an empty ``__main__`` module in :data:`sys.modules` at " -"interpreter startup, and populates it by running top-level code. In our " -"example this is the ``start`` module which runs line by line and imports " -"``namely``. In turn, ``namely`` imports ``__main__`` (which is really " -"``start``). That's an import cycle! Fortunately, since the partially " -"populated ``__main__`` module is present in :data:`sys.modules`, Python " -"passes that to ``namely``. See :ref:`Special considerations for __main__ " -"` in the import system's reference for details on how " -"this works." -msgstr "" -"當 Python 直譯器啟動時，會在 :data:`sys.modules` 中插入一個空的 ``__main__`` " -"模組，並透過執行頂層程式碼來填充它。在我們的範例中，這是 ``start`` 模組，它將" -"逐行執行並引入 ``namely``。接著，``namely`` 引入 ``__main__``\\ （其實是 " -"``start``）。這就是一個引入循環！幸運的是，由於部分填充的 ``__main__`` 模組存" -"在於 :data:`sys.modules` 中，Python 將其傳遞給 ``namely``。請參閱引入系統參考" -"文件中的\\ :ref:`關於 __main__ 的特別考量 `\\ 了解其工作" -"原理的詳細資訊。" - -#: ../../library/__main__.rst:345 -msgid "" -"The Python REPL is another example of a \"top-level environment\", so " -"anything defined in the REPL becomes part of the ``__main__`` scope::" -msgstr "" -"Python REPL 是「頂層環境」的另一個範例，因此 REPL 中定義的任何內容都成為 作域" -"的一部分： ::" - -#: ../../library/__main__.rst:348 -msgid "" -">>> import namely\n" -">>> namely.did_user_define_their_name()\n" -"False\n" -">>> namely.print_user_name()\n" -"Traceback (most recent call last):\n" -"...\n" -"ValueError: Define the variable `my_name`!\n" -">>> my_name = 'Jabberwocky'\n" -">>> namely.did_user_define_their_name()\n" -"True\n" -">>> namely.print_user_name()\n" -"Jabberwocky" -msgstr "" -">>> import namely\n" -">>> namely.did_user_define_their_name()\n" -"False\n" -">>> namely.print_user_name()\n" -"Traceback (most recent call last):\n" -"...\n" -"ValueError: Define the variable `my_name`!\n" -">>> my_name = 'Jabberwocky'\n" -">>> namely.did_user_define_their_name()\n" -"True\n" -">>> namely.print_user_name()\n" -"Jabberwocky" - -#: ../../library/__main__.rst:361 -msgid "" -"The ``__main__`` scope is used in the implementation of :mod:`pdb` " -"and :mod:`rlcompleter`." -msgstr "``__main__`` 作用域用於 :mod:`pdb` 和 :mod:`rlcompleter` 的實作。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: 2023-12-21 14:49+0800\n" +"Last-Translator: Liang-Bo Wang \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" +"X-Generator: Poedit 3.4\n" + +#: ../../library/__main__.rst:2 +msgid ":mod:`!__main__` --- Top-level code environment" +msgstr ":mod:`!__main__` --- 頂層程式碼環境" + +#: ../../library/__main__.rst:10 +msgid "" +"In Python, the special name ``__main__`` is used for two important " +"constructs:" +msgstr "在 Python 中，特殊名稱 ``__main__`` 用於兩個重要的建構：" + +#: ../../library/__main__.rst:12 +msgid "" +"the name of the top-level environment of the program, which can be checked " +"using the ``__name__ == '__main__'`` expression; and" +msgstr "" +"程式頂層環境的名稱，可以使用 ``__name__ == '__main__'`` 運算式進行檢查；和" + +#: ../../library/__main__.rst:14 +msgid "the ``__main__.py`` file in Python packages." +msgstr "在 Python 套件中的 ``__main__.py`` 檔案。" + +#: ../../library/__main__.rst:16 +msgid "" +"Both of these mechanisms are related to Python modules; how users interact " +"with them and how they interact with each other. They are explained in " +"detail below. If you're new to Python modules, see the tutorial " +"section :ref:`tut-modules` for an introduction." +msgstr "" +"這兩種機制都與 Python 模組有關；使用者如何與它們互動以及它們如何彼此互動。下" +"面會詳細解釋它們。如果你不熟悉 Python 模組，請參閱教學章節 :ref:`tut-" +"modules` 的介紹。" + +#: ../../library/__main__.rst:25 +msgid "``__name__ == '__main__'``" +msgstr "``__name__ == '__main__'``" + +#: ../../library/__main__.rst:27 +msgid "" +"When a Python module or package is imported, ``__name__`` is set to the " +"module's name. Usually, this is the name of the Python file itself without " +"the ``.py`` extension::" +msgstr "" +"當引入 Python 模組或套件時，``__name__`` 設定為模組的名稱。通常來說，這是 " +"Python 檔案本身的名稱，且不含 .py 副檔名： ::" + +#: ../../library/__main__.rst:31 +msgid "" +">>> import configparser\n" +">>> configparser.__name__\n" +"'configparser'" +msgstr "" +">>> import configparser\n" +">>> configparser.__name__\n" +"'configparser'" + +#: ../../library/__main__.rst:35 +msgid "" +"If the file is part of a package, ``__name__`` will also include the parent " +"package's path::" +msgstr "" +"如果檔案是套件的一部分，則 ``__name__`` 也會包含父套件 (parent package) 的路" +"徑： ::" + +#: ../../library/__main__.rst:38 +msgid "" +">>> from concurrent.futures import process\n" +">>> process.__name__\n" +"'concurrent.futures.process'" +msgstr "" +">>> from concurrent.futures import process\n" +">>> process.__name__\n" +"'concurrent.futures.process'" + +#: ../../library/__main__.rst:42 +msgid "" +"However, if the module is executed in the top-level code environment, its " +"``__name__`` is set to the string ``'__main__'``." +msgstr "" +"但是，如果模組在頂層程式碼環境中執行，則其 ``__name__`` 將被設定為字串 " +"``'__main__'``。" + +#: ../../library/__main__.rst:46 +msgid "What is the \"top-level code environment\"?" +msgstr "什麼是「頂層程式碼環境」？" + +#: ../../library/__main__.rst:48 +msgid "" +"``__main__`` is the name of the environment where top-level code is run. " +"\"Top-level code\" is the first user-specified Python module that starts " +"running. It's \"top-level\" because it imports all other modules that the " +"program needs. Sometimes \"top-level code\" is called an *entry point* to " +"the application." +msgstr "" +"``__main__`` 是執行頂層程式碼的環境名稱。「頂層程式碼」是使用者指定且第一個開" +"始運作的 Python 模組。它是「頂層」的原因是因為它引入程式所需的所有其他模組。" +"有時「頂層程式碼」被稱為應用程式的\\ *入口點*。" + +#: ../../library/__main__.rst:53 +msgid "The top-level code environment can be:" +msgstr "頂層程式碼環境可以是：" + +#: ../../library/__main__.rst:55 +msgid "the scope of an interactive prompt::" +msgstr "互動式提示字元的作用域： ::" + +#: ../../library/__main__.rst:57 +msgid "" +">>> __name__\n" +"'__main__'" +msgstr "" +">>> __name__\n" +"'__main__'" + +#: ../../library/__main__.rst:60 +msgid "the Python module passed to the Python interpreter as a file argument:" +msgstr "將 Python 模組作為檔案引數傳遞給 Python 直譯器：" + +#: ../../library/__main__.rst:62 +msgid "" +"$ python helloworld.py\n" +"Hello, world!" +msgstr "" +"$ python helloworld.py\n" +"Hello, world!" + +#: ../../library/__main__.rst:67 +msgid "" +"the Python module or package passed to the Python interpreter with " +"the :option:`-m` argument:" +msgstr "使用 :option:`-m` 引數傳遞給 Python 直譯器的 Python 模組或套件：" + +#: ../../library/__main__.rst:70 +msgid "" +"$ python -m tarfile\n" +"usage: tarfile.py [-h] [-v] (...)" +msgstr "" +"$ python -m tarfile\n" +"usage: tarfile.py [-h] [-v] (...)" + +#: ../../library/__main__.rst:75 +msgid "Python code read by the Python interpreter from standard input:" +msgstr "Python 直譯器從標準輸入讀取 Python 程式碼：" + +#: ../../library/__main__.rst:77 +msgid "" +"$ echo \"import this\" | python\n" +"The Zen of Python, by Tim Peters\n" +"\n" +"Beautiful is better than ugly.\n" +"Explicit is better than implicit.\n" +"..." +msgstr "" +"$ echo \"import this\" | python\n" +"The Zen of Python, by Tim Peters\n" +"\n" +"Beautiful is better than ugly.\n" +"Explicit is better than implicit.\n" +"..." + +#: ../../library/__main__.rst:86 +msgid "" +"Python code passed to the Python interpreter with the :option:`-c` argument:" +msgstr "使用 :option:`-c` 引數傳遞給 Python 直譯器的 Python 程式碼：" + +#: ../../library/__main__.rst:88 +msgid "" +"$ python -c \"import this\"\n" +"The Zen of Python, by Tim Peters\n" +"\n" +"Beautiful is better than ugly.\n" +"Explicit is better than implicit.\n" +"..." +msgstr "" +"$ python -c \"import this\"\n" +"The Zen of Python, by Tim Peters\n" +"\n" +"Beautiful is better than ugly.\n" +"Explicit is better than implicit.\n" +"..." + +#: ../../library/__main__.rst:97 +msgid "" +"In each of these situations, the top-level module's ``__name__`` is set to " +"``'__main__'``." +msgstr "在這些情況下，頂層模組的 ``__name__`` 都會設定為 ``'__main__'``。" + +#: ../../library/__main__.rst:100 +msgid "" +"As a result, a module can discover whether or not it is running in the top-" +"level environment by checking its own ``__name__``, which allows a common " +"idiom for conditionally executing code when the module is not initialized " +"from an import statement::" +msgstr "" +"因此，模組可以透過檢查自己的 ``__name__`` 來發現它是否在頂層環境中執行，這允" +"許當模組未從 import 陳述式初始化時，使用常見的慣用語法 (idiom) 來有條件地執行" +"程式碼： ::" + +#: ../../library/__main__.rst:105 +msgid "" +"if __name__ == '__main__':\n" +" # Execute when the module is not initialized from an import statement.\n" +" ..." +msgstr "" + +#: ../../library/__main__.rst:111 +msgid "" +"For a more detailed look at how ``__name__`` is set in all situations, see " +"the tutorial section :ref:`tut-modules`." +msgstr "" +"若要更詳細地了解如何在所有情況下設定 ``__name__``，請參閱教學章節 :ref:`tut-" +"modules`。" + +#: ../../library/__main__.rst:116 ../../library/__main__.rst:239 +msgid "Idiomatic Usage" +msgstr "慣用 (Idiomatic) 用法" + +#: ../../library/__main__.rst:118 +msgid "" +"Some modules contain code that is intended for script use only, like parsing " +"command-line arguments or fetching data from standard input. If a module " +"like this was imported from a different module, for example to unit test it, " +"the script code would unintentionally execute as well." +msgstr "" +"某些模組包含僅供腳本使用的程式碼，例如剖析命令列引數或從標準輸入取得資料。如" +"果從不同的模組匯入這樣的模組（例如對其進行單元測試 (unit test)），則腳本程式" +"碼也會無意間執行。" + +#: ../../library/__main__.rst:123 +msgid "" +"This is where using the ``if __name__ == '__main__'`` code block comes in " +"handy. Code within this block won't run unless the module is executed in the " +"top-level environment." +msgstr "" +"這就是使用 ``if __name__ == '__main__'`` 程式碼區塊派上用場的地方。除非該模組" +"在頂層環境中執行，否則此區塊中的程式碼不會執行。" + +#: ../../library/__main__.rst:127 +msgid "" +"Putting as few statements as possible in the block below ``if __name__ == " +"'__main__'`` can improve code clarity and correctness. Most often, a " +"function named ``main`` encapsulates the program's primary behavior::" +msgstr "" +"在 ``if __name__ == '__main__'`` 下面的區塊中放置盡可能少的陳述式可以提高程式" +"碼的清晰度和正確性。大多數情況下，名為 ``main`` 的函式封裝 (encapsulate) 了程" +"式的主要行為： ::" + +#: ../../library/__main__.rst:131 +msgid "" +"# echo.py\n" +"\n" +"import shlex\n" +"import sys\n" +"\n" +"def echo(phrase: str) -> None:\n" +" \"\"\"A dummy wrapper around print.\"\"\"\n" +" # for demonstration purposes, you can imagine that there is some\n" +" # valuable and reusable logic inside this function\n" +" print(phrase)\n" +"\n" +"def main() -> int:\n" +" \"\"\"Echo the input arguments to standard output\"\"\"\n" +" phrase = shlex.join(sys.argv)\n" +" echo(phrase)\n" +" return 0\n" +"\n" +"if __name__ == '__main__':\n" +" sys.exit(main()) # next section explains the use of sys.exit" +msgstr "" + +#: ../../library/__main__.rst:151 +msgid "" +"Note that if the module didn't encapsulate code inside the ``main`` function " +"but instead put it directly within the ``if __name__ == '__main__'`` block, " +"the ``phrase`` variable would be global to the entire module. This is error-" +"prone as other functions within the module could be unintentionally using " +"the global variable instead of a local name. A ``main`` function solves " +"this problem." +msgstr "" +"請注意，如果模組沒有將程式碼封裝在 ``main`` 函式中，而是直接將其放在 ``if " +"__name__ == '__main__'`` 區塊中，則 ``phrase`` 變數對於整個模組來說將是全域" +"的。這很容易出錯，因為模組中的其他函式可能會無意中使用此全域變數而不是區域變" +"數。``main`` 函式解決了這個問題。" + +#: ../../library/__main__.rst:158 +msgid "" +"Using a ``main`` function has the added benefit of the ``echo`` function " +"itself being isolated and importable elsewhere. When ``echo.py`` is " +"imported, the ``echo`` and ``main`` functions will be defined, but neither " +"of them will be called, because ``__name__ != '__main__'``." +msgstr "" +"使用 ``main`` 函式還有一個額外的好處，``echo`` 函式本身是隔離的 (isolated) 並" +"且可以在其他地方引入。當引入 ``echo.py`` 時，``echo`` 和 ``main`` 函式將被定" +"義，但它們都不會被呼叫，因為 ``__name__ != '__main__'``。" + +#: ../../library/__main__.rst:165 +msgid "Packaging Considerations" +msgstr "打包時須考慮的事情" + +#: ../../library/__main__.rst:167 +msgid "" +"``main`` functions are often used to create command-line tools by specifying " +"them as entry points for console scripts. When this is done, `pip `_ inserts the function call into a template script, where the " +"return value of ``main`` is passed into :func:`sys.exit`. For example::" +msgstr "" +"``main`` 函式通常用於透過將它們指定為控制台腳本的入口點來建立命令列工具。完成" +"後，`pip `_ 將函式呼叫插入到模板腳本中，其中 ``main`` " +"的回傳值被傳遞到 :func:`sys.exit` 中。例如： ::" + +#: ../../library/__main__.rst:173 +msgid "sys.exit(main())" +msgstr "sys.exit(main())" + +#: ../../library/__main__.rst:175 +msgid "" +"Since the call to ``main`` is wrapped in :func:`sys.exit`, the expectation " +"is that your function will return some value acceptable as an input " +"to :func:`sys.exit`; typically, an integer or ``None`` (which is implicitly " +"returned if your function does not have a return statement)." +msgstr "" +"由於對 ``main`` 的呼叫包含在 :func:`sys.exit` 中，因此期望你的函式將傳回一些" +"可接受作為 :func:`sys.exit` 輸入的值；通常來說，會是一個整數或 ``None``\\（如" +"果你的函式沒有 return 陳述式，則相當於回傳此值）。" + +#: ../../library/__main__.rst:180 +msgid "" +"By proactively following this convention ourselves, our module will have the " +"same behavior when run directly (i.e. ``python echo.py``) as it will have if " +"we later package it as a console script entry-point in a pip-installable " +"package." +msgstr "" +"透過我們自己主動遵循這個慣例，我們的模組在直接執行時（即 ``python echo.py``）" +"的行為，將和我們稍後將其打包為 pip 可安裝套件中的控制台腳本入口點相同。" + +#: ../../library/__main__.rst:185 +msgid "" +"In particular, be careful about returning strings from your ``main`` " +"function. :func:`sys.exit` will interpret a string argument as a failure " +"message, so your program will have an exit code of ``1``, indicating " +"failure, and the string will be written to :data:`sys.stderr`. The " +"``echo.py`` example from earlier exemplifies using the ``sys.exit(main())`` " +"convention." +msgstr "" +"特別是，要謹慎處理從 ``main`` 函式回傳字串。:func:`sys.exit` 會將字串引數直譯" +"為失敗訊息，因此你的程式將有一個表示失敗的結束代碼 ``1``，並且該字串將被寫" +"入 :data:`sys.stderr`。前面的 ``echo.py`` 範例使用慣例的 " +"``sys.exit(main())`` 進行示範。" + +#: ../../library/__main__.rst:193 +msgid "" +"`Python Packaging User Guide `_ contains a " +"collection of tutorials and references on how to distribute and install " +"Python packages with modern tools." +msgstr "" +"`Python 打包使用者指南 `_\\ 包含一系列如何使用" +"現代工具發行和安裝 Python 套件的教學和參考資料。" + +#: ../../library/__main__.rst:199 +msgid "``__main__.py`` in Python Packages" +msgstr "Python 套件中的 ``__main__.py``" + +#: ../../library/__main__.rst:201 +msgid "" +"If you are not familiar with Python packages, see section :ref:`tut-" +"packages` of the tutorial. Most commonly, the ``__main__.py`` file is used " +"to provide a command-line interface for a package. Consider the following " +"hypothetical package, \"bandclass\":" +msgstr "" +"如果你不熟悉 Python 套件，請參閱 :ref:`tut-packages` 的教學章節。最常見的是，" +"``__main__.py`` 檔案用於為套件提供命令列介面。假設下面有虛構的套件 " +"\"bandclass\"：" + +#: ../../library/__main__.rst:206 +msgid "" +"bandclass\n" +" ├── __init__.py\n" +" ├── __main__.py\n" +" └── student.py" +msgstr "" +"bandclass\n" +" ├── __init__.py\n" +" ├── __main__.py\n" +" └── student.py" + +#: ../../library/__main__.rst:213 +msgid "" +"``__main__.py`` will be executed when the package itself is invoked directly " +"from the command line using the :option:`-m` flag. For example:" +msgstr "" +"當使用 :option:`-m` 旗標 (flag) 直接從命令列呼叫套件本身時，將執行 " +"``__main__.py``。例如：" + +#: ../../library/__main__.rst:216 +msgid "$ python -m bandclass" +msgstr "$ python -m bandclass" + +#: ../../library/__main__.rst:220 +msgid "" +"This command will cause ``__main__.py`` to run. How you utilize this " +"mechanism will depend on the nature of the package you are writing, but in " +"this hypothetical case, it might make sense to allow the teacher to search " +"for students::" +msgstr "" +"該命令將導致 ``__main__.py`` 執行。如何利用此機制將取決於你正在編寫的套件的性" +"質，但在這種虛構的情況下，允許教師搜尋學生可能是有意義的： ::" + +#: ../../library/__main__.rst:225 +msgid "" +"# bandclass/__main__.py\n" +"\n" +"import sys\n" +"from .student import search_students\n" +"\n" +"student_name = sys.argv[1] if len(sys.argv) >= 2 else ''\n" +"print(f'Found student: {search_students(student_name)}')" +msgstr "" +"# bandclass/__main__.py\n" +"\n" +"import sys\n" +"from .student import search_students\n" +"\n" +"student_name = sys.argv[1] if len(sys.argv) >= 2 else ''\n" +"print(f'Found student: {search_students(student_name)}')" + +#: ../../library/__main__.rst:233 +msgid "" +"Note that ``from .student import search_students`` is an example of a " +"relative import. This import style can be used when referencing modules " +"within a package. For more details, see :ref:`intra-package-references` in " +"the :ref:`tut-modules` section of the tutorial." +msgstr "" +"請注意，``from .student import search_students`` 是相對引入的範例。在引用套件" +"內的模組時，可以使用此引入樣式。有關更多詳細資訊，請參閱 :ref:`tut-modules` " +"教學章節中的 :ref:`intra-package-references`。" + +#: ../../library/__main__.rst:241 +msgid "" +"The content of ``__main__.py`` typically isn't fenced with an ``if __name__ " +"== '__main__'`` block. Instead, those files are kept short and import " +"functions to execute from other modules. Those other modules can then be " +"easily unit-tested and are properly reusable." +msgstr "" +"``__main__.py`` 的內容通常不會被 ``if __name__ == '__main__'`` 區塊包圍。相反" +"的，這些檔案保持簡短並引入其他模組的函式來執行。那些其他模組就可以輕鬆地進行" +"單元測試並且可以正確地重複使用。" + +#: ../../library/__main__.rst:246 +msgid "" +"If used, an ``if __name__ == '__main__'`` block will still work as expected " +"for a ``__main__.py`` file within a package, because its ``__name__`` " +"attribute will include the package's path if imported::" +msgstr "" +"如果在套件裡面的 ``__main__.py`` 檔案使用 ``if __name__ == '__main__'`` 區" +"塊，它依然會如預期般地運作。因為當引入套件，其 ``__name__`` 屬性將會包含套件" +"的路徑： ::" + +#: ../../library/__main__.rst:250 +msgid "" +">>> import asyncio.__main__\n" +">>> asyncio.__main__.__name__\n" +"'asyncio.__main__'" +msgstr "" +">>> import asyncio.__main__\n" +">>> asyncio.__main__.__name__\n" +"'asyncio.__main__'" + +#: ../../library/__main__.rst:254 +msgid "" +"This won't work for ``__main__.py`` files in the root directory of a " +"``.zip`` file though. Hence, for consistency, a minimal ``__main__.py`` " +"without a ``__name__`` check is preferred." +msgstr "" +"但這對於 ``.zip`` 檔案根目錄中的 ``__main__.py`` 檔案不起作用。因此，為了保持" +"一致性，最小的、沒有 ``__name__`` 檢查的 ``__main__.py`` 會是首選。" + +#: ../../library/__main__.rst:260 +msgid "" +"See :mod:`venv` for an example of a package with a minimal ``__main__.py`` " +"in the standard library. It doesn't contain a ``if __name__ == '__main__'`` " +"block. You can invoke it with ``python -m venv [directory]``." +msgstr "" +"請參閱 :mod:`venv` 作為標準函式庫中具有最小 ``__main__.py`` 的套件為範例。它" +"不包含 ``if __name__ == '__main__'`` 區塊。你可以使用 ``python -m venv " +"[directory]`` 來呼叫它。" + +#: ../../library/__main__.rst:264 +msgid "" +"See :mod:`runpy` for more details on the :option:`-m` flag to the " +"interpreter executable." +msgstr "" +"請參閱 :mod:`runpy` 取得有關直譯器可執行檔的 :option:`-m` 旗標的更多詳細資" +"訊。" + +#: ../../library/__main__.rst:267 +msgid "" +"See :mod:`zipapp` for how to run applications packaged as *.zip* files. In " +"this case Python looks for a ``__main__.py`` file in the root directory of " +"the archive." +msgstr "" +"請參閱 :mod:`zipapp` 了解如何執行打包成 *.zip* 檔案的應用程式。在這種情況下，" +"Python 會在封存檔案的根目錄中尋找 ``__main__.py`` 檔案。" + +#: ../../library/__main__.rst:274 +msgid "``import __main__``" +msgstr "``import __main__``" + +#: ../../library/__main__.rst:276 +msgid "" +"Regardless of which module a Python program was started with, other modules " +"running within that same program can import the top-level environment's " +"scope (:term:`namespace`) by importing the ``__main__`` module. This " +"doesn't import a ``__main__.py`` file but rather whichever module that " +"received the special name ``'__main__'``." +msgstr "" +"無論 Python 程式是從哪個模組啟動的，在同一程式中執行的其他模組都可以透過匯入 " +"``__main__`` 模組來引入頂層環境的作用域 (:term:`namespace`)。這不會引入 " +"``__main__.py`` 檔案，而是引入接收特殊名稱 ``'__main__'`` 的模組。" + +#: ../../library/__main__.rst:282 +msgid "Here is an example module that consumes the ``__main__`` namespace::" +msgstr "這是一個使用 ``__main__`` 命名空間的範例模組：" + +#: ../../library/__main__.rst:284 +msgid "" +"# namely.py\n" +"\n" +"import __main__\n" +"\n" +"def did_user_define_their_name():\n" +" return 'my_name' in dir(__main__)\n" +"\n" +"def print_user_name():\n" +" if not did_user_define_their_name():\n" +" raise ValueError('Define the variable `my_name`!')\n" +"\n" +" print(__main__.my_name)" +msgstr "" +"# namely.py\n" +"\n" +"import __main__\n" +"\n" +"def did_user_define_their_name():\n" +" return 'my_name' in dir(__main__)\n" +"\n" +"def print_user_name():\n" +" if not did_user_define_their_name():\n" +" raise ValueError('Define the variable `my_name`!')\n" +"\n" +" print(__main__.my_name)" + +#: ../../library/__main__.rst:297 +msgid "Example usage of this module could be as follows::" +msgstr "該模組的範例用法如下： ::" + +#: ../../library/__main__.rst:299 +msgid "" +"# start.py\n" +"\n" +"import sys\n" +"\n" +"from namely import print_user_name\n" +"\n" +"# my_name = \"Dinsdale\"\n" +"\n" +"def main():\n" +" try:\n" +" print_user_name()\n" +" except ValueError as ve:\n" +" return str(ve)\n" +"\n" +"if __name__ == \"__main__\":\n" +" sys.exit(main())" +msgstr "" +"# start.py\n" +"\n" +"import sys\n" +"\n" +"from namely import print_user_name\n" +"\n" +"# my_name = \"Dinsdale\"\n" +"\n" +"def main():\n" +" try:\n" +" print_user_name()\n" +" except ValueError as ve:\n" +" return str(ve)\n" +"\n" +"if __name__ == \"__main__\":\n" +" sys.exit(main())" + +#: ../../library/__main__.rst:316 +msgid "Now, if we started our program, the result would look like this:" +msgstr "現在，如果我們啟動程式，結果將如下所示：" + +#: ../../library/__main__.rst:318 +msgid "" +"$ python start.py\n" +"Define the variable `my_name`!" +msgstr "" +"$ python start.py\n" +"Define the variable `my_name`!" + +#: ../../library/__main__.rst:323 +msgid "" +"The exit code of the program would be 1, indicating an error. Uncommenting " +"the line with ``my_name = \"Dinsdale\"`` fixes the program and now it exits " +"with status code 0, indicating success:" +msgstr "" +"程式的結束代碼將為 1，表示出現錯誤。取消註解 ``my_name = \"Dinsdale\"`` 而修" +"復程式後，現在它以狀態碼 0 結束，表示成功：" + +#: ../../library/__main__.rst:327 +msgid "" +"$ python start.py\n" +"Dinsdale" +msgstr "" +"$ python start.py\n" +"Dinsdale" + +#: ../../library/__main__.rst:332 +msgid "" +"Note that importing ``__main__`` doesn't cause any issues with " +"unintentionally running top-level code meant for script use which is put in " +"the ``if __name__ == \"__main__\"`` block of the ``start`` module. Why does " +"this work?" +msgstr "" +"請注意，引入 ``__main__`` 並不會因為不經意地執行放在 ``start`` 模組中 ``if " +"__name__ == \"__main__\"`` 區塊的頂層程式碼（本來是給腳本使用的）而造成任何問" +"題。為什麼這樣做會如預期運作？" + +#: ../../library/__main__.rst:336 +msgid "" +"Python inserts an empty ``__main__`` module in :data:`sys.modules` at " +"interpreter startup, and populates it by running top-level code. In our " +"example this is the ``start`` module which runs line by line and imports " +"``namely``. In turn, ``namely`` imports ``__main__`` (which is really " +"``start``). That's an import cycle! Fortunately, since the partially " +"populated ``__main__`` module is present in :data:`sys.modules`, Python " +"passes that to ``namely``. See :ref:`Special considerations for __main__ " +"` in the import system's reference for details on how " +"this works." +msgstr "" +"當 Python 直譯器啟動時，會在 :data:`sys.modules` 中插入一個空的 ``__main__`` " +"模組，並透過執行頂層程式碼來填充它。在我們的範例中，這是 ``start`` 模組，它將" +"逐行執行並引入 ``namely``。接著，``namely`` 引入 ``__main__``\\ （其實是 " +"``start``）。這就是一個引入循環！幸運的是，由於部分填充的 ``__main__`` 模組存" +"在於 :data:`sys.modules` 中，Python 將其傳遞給 ``namely``。請參閱引入系統參考" +"文件中的\\ :ref:`關於 __main__ 的特別考量 `\\ 了解其工作" +"原理的詳細資訊。" + +#: ../../library/__main__.rst:345 +msgid "" +"The Python REPL is another example of a \"top-level environment\", so " +"anything defined in the REPL becomes part of the ``__main__`` scope::" +msgstr "" +"Python REPL 是「頂層環境」的另一個範例，因此 REPL 中定義的任何內容都成為 作域" +"的一部分： ::" + +#: ../../library/__main__.rst:348 +msgid "" +">>> import namely\n" +">>> namely.did_user_define_their_name()\n" +"False\n" +">>> namely.print_user_name()\n" +"Traceback (most recent call last):\n" +"...\n" +"ValueError: Define the variable `my_name`!\n" +">>> my_name = 'Jabberwocky'\n" +">>> namely.did_user_define_their_name()\n" +"True\n" +">>> namely.print_user_name()\n" +"Jabberwocky" +msgstr "" +">>> import namely\n" +">>> namely.did_user_define_their_name()\n" +"False\n" +">>> namely.print_user_name()\n" +"Traceback (most recent call last):\n" +"...\n" +"ValueError: Define the variable `my_name`!\n" +">>> my_name = 'Jabberwocky'\n" +">>> namely.did_user_define_their_name()\n" +"True\n" +">>> namely.print_user_name()\n" +"Jabberwocky" + +#: ../../library/__main__.rst:361 +msgid "" +"The ``__main__`` scope is used in the implementation of :mod:`pdb` " +"and :mod:`rlcompleter`." +msgstr "``__main__`` 作用域用於 :mod:`pdb` 和 :mod:`rlcompleter` 的實作。" diff --git a/library/_thread.po b/library/_thread.po index 400222e8c2..876c7ad724 100644 --- a/library/_thread.po +++ b/library/_thread.po @@ -1,388 +1,388 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: 2015-12-09 17:51+0000\n" -"Last-Translator: Liang-Bo Wang \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/_thread.rst:2 -msgid ":mod:`!_thread` --- Low-level threading API" -msgstr ":mod:`!_thread` --- 低階執行緒 API" - -#: ../../library/_thread.rst:15 -msgid "" -"This module provides low-level primitives for working with multiple threads " -"(also called :dfn:`light-weight processes` or :dfn:`tasks`) --- multiple " -"threads of control sharing their global data space. For synchronization, " -"simple locks (also called :dfn:`mutexes` or :dfn:`binary semaphores`) are " -"provided. The :mod:`threading` module provides an easier to use and higher-" -"level threading API built on top of this module." -msgstr "" -"這個模組提供了與多個執行緒（也稱為:dfn:`輕量級行程` 或 :dfn: `任務`）一起工作" -"的低階原始物件 --- 多個控制執行緒分享其全域資料空間。為了處理同步問題，也提供" -"了簡單的鎖 (lock) 機制（也稱為:dfn:`互斥鎖` 或 :dfn:`二進位號誌" -"`）。 :mod:`threading` 模組提供了一個建立在這個模組之上的更易於使用和高階的執" -"行緒 API。" - -#: ../../library/_thread.rst:26 -msgid "This module used to be optional, it is now always available." -msgstr "這個模組之前是可選擇性的，但現在已經是可用的。" - -#: ../../library/_thread.rst:29 -msgid "This module defines the following constants and functions:" -msgstr "這個模組定義了以下的常數和函式：" - -#: ../../library/_thread.rst:33 -msgid "Raised on thread-specific errors." -msgstr "在執行緒相關的錯誤發生時引發。" - -#: ../../library/_thread.rst:35 -msgid "This is now a synonym of the built-in :exc:`RuntimeError`." -msgstr "現在是內建例外 :exc:`RuntimeError` 的別名。" - -#: ../../library/_thread.rst:41 -msgid "This is the type of lock objects." -msgstr "這是鎖物件的型別。" - -#: ../../library/_thread.rst:46 -msgid "" -"Start a new thread and return its identifier. The thread executes the " -"function *function* with the argument list *args* (which must be a tuple). " -"The optional *kwargs* argument specifies a dictionary of keyword arguments." -msgstr "" -"開始一個新的執行緒並回傳其識別字 (identifier) 。該執行緒執行帶有引數列表 " -"*args*\\ （必須是一個 tuple（元組））的函式 *function*。可選的 *kwargs* 引數指定" -"一個關鍵字引數的字典。" - -#: ../../library/_thread.rst:50 -msgid "When the function returns, the thread silently exits." -msgstr "當函式回傳時，執行緒會靜默退出。" - -#: ../../library/_thread.rst:52 -msgid "" -"When the function terminates with an unhandled " -"exception, :func:`sys.unraisablehook` is called to handle the exception. The " -"*object* attribute of the hook argument is *function*. By default, a stack " -"trace is printed and then the thread exits (but other threads continue to " -"run)." -msgstr "" -"當函式因未處理的例外終止時，將呼叫 :func:`sys.unraisablehook` 來處理該例外。" -"鉤子引數的 *object* 屬性是 *function*。預設情況下，會列印堆疊跟蹤，然後執行緒" -"退出（但其他執行緒會繼續運行）。" - -#: ../../library/_thread.rst:57 -msgid "" -"When the function raises a :exc:`SystemExit` exception, it is silently " -"ignored." -msgstr "當函式引發 :exc:`SystemExit` 例外時，它會被靜默忽略。" - -#: ../../library/_thread.rst:60 -msgid "" -"Raises an :ref:`auditing event ` ``_thread.start_new_thread`` with " -"arguments ``function``, ``args``, ``kwargs``." -msgstr "" -"引發一個 :ref:`稽核事件 ` ``_thread.start_new_thread``，帶有引數 " -"``function``、``args`` 和 ``kwargs``。" - -#: ../../library/_thread.rst:62 -msgid ":func:`sys.unraisablehook` is now used to handle unhandled exceptions." -msgstr "現在使用 :func:`sys.unraisablehook` 來處理未處理的例外。" - -#: ../../library/_thread.rst:68 -msgid "" -"Simulate the effect of a signal arriving in the main thread. A thread can " -"use this function to interrupt the main thread, though there is no guarantee " -"that the interruption will happen immediately." -msgstr "" -"模擬一個訊號到達主執行緒的效果。執行緒可以使用此函式來中斷主執行緒，但無法保" -"證中斷會立即發生。" - -#: ../../library/_thread.rst:72 -msgid "" -"If given, *signum* is the number of the signal to simulate. If *signum* is " -"not given, :const:`signal.SIGINT` is simulated." -msgstr "" -"如果提供了 *signum*，則模擬指定的訊號編號。如果未提供 *signum*，則模" -"擬 :const:`signal.SIGINT` 訊號。" - -#: ../../library/_thread.rst:75 -msgid "" -"If the given signal isn't handled by Python (it was set " -"to :const:`signal.SIG_DFL` or :const:`signal.SIG_IGN`), this function does " -"nothing." -msgstr "" -"如果給定的訊號在 Python 中未被處理（即設置為 :const:`signal.SIG_DFL` " -"或 :const:`signal.SIG_IGN`），此函式不做任何操作。" - -#: ../../library/_thread.rst:79 -msgid "The *signum* argument is added to customize the signal number." -msgstr "新增了 *signum* 引數以自訂訊號編號。" - -#: ../../library/_thread.rst:83 -msgid "" -"This does not emit the corresponding signal but schedules a call to the " -"associated handler (if it exists). If you want to truly emit the signal, " -"use :func:`signal.raise_signal`." -msgstr "" -"這並不會發出對應的訊號，而是安排呼叫相應的處理器（如果存在的話）。如果你想真" -"正發出訊號，請使用 :func:`signal.raise_signal`。" - -#: ../../library/_thread.rst:90 -msgid "" -"Raise the :exc:`SystemExit` exception. When not caught, this will cause the " -"thread to exit silently." -msgstr "引發 :exc:`SystemExit` 例外。當未捕獲時，將導致執行緒靜默退出。" - -#: ../../library/_thread.rst:104 -msgid "" -"Return a new lock object. Methods of locks are described below. The lock " -"is initially unlocked." -msgstr "回傳一個新的鎖物件。鎖物件的方法如下所述。初始狀況下鎖是解鎖狀態。" - -#: ../../library/_thread.rst:110 -msgid "" -"Return the 'thread identifier' of the current thread. This is a nonzero " -"integer. Its value has no direct meaning; it is intended as a magic cookie " -"to be used e.g. to index a dictionary of thread-specific data. Thread " -"identifiers may be recycled when a thread exits and another thread is " -"created." -msgstr "" -"回傳目前執行緒的「執行緒識別字」。這是一個非零的整數。它的值沒有直接的含義；" -"它被用作一個 magic cookie，例如用於索引特定於執行緒的資料的字典。當執行緒退出" -"並建立另一個執行緒時，執行緒識別字可能會被重複使用。" - -#: ../../library/_thread.rst:118 -msgid "" -"Return the native integral Thread ID of the current thread assigned by the " -"kernel. This is a non-negative integer. Its value may be used to uniquely " -"identify this particular thread system-wide (until the thread terminates, " -"after which the value may be recycled by the OS)." -msgstr "" -"回傳由核心 (kernel) 分配的目前執行緒的原生整數執行緒 ID。這是一個非負整數。它" -"的值可用於在整個系統中唯一標識此特定執行緒（直到執行緒終止後，該值可能被操作" -"系統重新使用）。" - -#: ../../library/_thread.rst:123 ../../library/_thread.rst:148 -msgid "Availability" -msgstr "可用性" - -#: ../../library/_thread.rst:127 -msgid "Added support for GNU/kFreeBSD." -msgstr "新增了對 GNU/kFreeBSD 的支援。" - -#: ../../library/_thread.rst:133 -msgid "" -"Return the thread stack size used when creating new threads. The optional " -"*size* argument specifies the stack size to be used for subsequently created " -"threads, and must be 0 (use platform or configured default) or a positive " -"integer value of at least 32,768 (32 KiB). If *size* is not specified, 0 is " -"used. If changing the thread stack size is unsupported, " -"a :exc:`RuntimeError` is raised. If the specified stack size is invalid, " -"a :exc:`ValueError` is raised and the stack size is unmodified. 32 KiB is " -"currently the minimum supported stack size value to guarantee sufficient " -"stack space for the interpreter itself. Note that some platforms may have " -"particular restrictions on values for the stack size, such as requiring a " -"minimum stack size > 32 KiB or requiring allocation in multiples of the " -"system memory page size - platform documentation should be referred to for " -"more information (4 KiB pages are common; using multiples of 4096 for the " -"stack size is the suggested approach in the absence of more specific " -"information)." -msgstr "" -"回傳在建立新執行緒時使用的執行緒堆疊大小。可選的 *size* 引數指定了隨後建立的" -"執行緒要使用的堆疊大小，必須是 0（使用平台或配置的預設值）或至少 32,768（32 " -"KiB）的正整數值。如果未指定 *size*，則使用 0。如果不支援更改執行緒堆疊大小，" -"則會引發 :exc:`RuntimeError` 錯誤。如果指定的堆疊大小無效，則會引" -"發 :exc:`ValueError` 錯誤，並且堆疊大小不會被修改。目前，32 KiB 是保證直譯器" -"本身具有足夠堆疊空間所支援的最小堆疊大小值。請注意，某些平台對於堆疊大小的值" -"可能有特定的限制，例如要求最小堆疊大小 > 32 KiB，或要求按系統記憶體頁面大小的" -"倍數進行分配。應參考平台文件以取得更多訊息（4 KiB 頁面是比較普遍的；在缺乏更" -"具體訊息的情況下，建議使用 4096 的倍數作為堆疊大小）。" - -#: ../../library/_thread.rst:150 -msgid "Unix platforms with POSIX threads support." -msgstr "Unix 平台上支援 POSIX 執行緒。" - -#: ../../library/_thread.rst:155 -msgid "" -"The maximum value allowed for the *timeout* parameter of :meth:`Lock.acquire " -"`. Specifying a timeout greater than this value will " -"raise an :exc:`OverflowError`." -msgstr "" -":meth:`Lock.acquire ` 的 *timeout* 參數所允許的最大" -"值。指定超過此值的 timeout 將引發 :exc:`OverflowError` 錯誤。" - -#: ../../library/_thread.rst:162 -msgid "Lock objects have the following methods:" -msgstr "鎖物件具有以下方法：" - -#: ../../library/_thread.rst:167 -msgid "" -"Without any optional argument, this method acquires the lock " -"unconditionally, if necessary waiting until it is released by another thread " -"(only one thread at a time can acquire a lock --- that's their reason for " -"existence)." -msgstr "" -"沒有任何可選引數時，此方法無條件地取得鎖，必要時會等待直到被另一個執行緒釋放" -"（一次只能有一個執行緒取得鎖 --- 這正是鎖存在的原因）。" - -#: ../../library/_thread.rst:171 -msgid "" -"If the *blocking* argument is present, the action depends on its value: if " -"it is false, the lock is only acquired if it can be acquired immediately " -"without waiting, while if it is true, the lock is acquired unconditionally " -"as above." -msgstr "" -"如果存在 *blocking* 引數，則根據其值執行操作：如果為 False，只有在可以立即獲" -"取鎖而無需等待的情況下才取得鎖，而如果為 True，則像上面一樣無條件地取得鎖。" - -#: ../../library/_thread.rst:176 -msgid "" -"If the floating-point *timeout* argument is present and positive, it " -"specifies the maximum wait time in seconds before returning. A negative " -"*timeout* argument specifies an unbounded wait. You cannot specify a " -"*timeout* if *blocking* is false." -msgstr "" -"如果存在浮點數的 *timeout* 引數且為正值，則它指定了在回傳之前的最大等待時間" -"（以秒為單位）。如果 *timeout* 引數為負值，則表示等待時間會無限期地等待。如" -"果 *blocking* 為 False，則你無法指定 *timeout*。" - -#: ../../library/_thread.rst:181 -msgid "" -"The return value is ``True`` if the lock is acquired successfully, ``False`` " -"if not." -msgstr "如果成功取得鎖，回傳值為 ``True``，否則為 ``False``。" - -#: ../../library/_thread.rst:184 -msgid "The *timeout* parameter is new." -msgstr "新增的 *timeout* 參數。" - -#: ../../library/_thread.rst:187 -msgid "Lock acquires can now be interrupted by signals on POSIX." -msgstr "現在取得鎖的操作可以被 POSIX 訊號中斷。" - -#: ../../library/_thread.rst:190 -msgid "Lock acquires can now be interrupted by signals on Windows." -msgstr "" - -#: ../../library/_thread.rst:196 -msgid "" -"Releases the lock. The lock must have been acquired earlier, but not " -"necessarily by the same thread." -msgstr "釋放鎖。鎖必須先前被取得，但不一定是由同一個執行緒取得的。" - -#: ../../library/_thread.rst:202 -msgid "" -"Return the status of the lock: ``True`` if it has been acquired by some " -"thread, ``False`` if not." -msgstr "" -"回傳鎖的狀態：如果鎖已被某個執行緒取得，則回傳 ``True``，否則回傳 ``False``。" - -#: ../../library/_thread.rst:205 -msgid "" -"In addition to these methods, lock objects can also be used via " -"the :keyword:`with` statement, e.g.::" -msgstr "除了這些方法之外，鎖物件還可以透過 :keyword:`with` 語句來使用，例如：" - -#: ../../library/_thread.rst:208 -msgid "" -"import _thread\n" -"\n" -"a_lock = _thread.allocate_lock()\n" -"\n" -"with a_lock:\n" -" print(\"a_lock is locked while this executes\")" -msgstr "" -"import _thread\n" -"\n" -"a_lock = _thread.allocate_lock()\n" -"\n" -"with a_lock:\n" -" print(\"a_lock 在執行這裡時被鎖定\")" - -#: ../../library/_thread.rst:215 -msgid "**Caveats:**" -msgstr "**注意事項：**" - -#: ../../library/_thread.rst:219 -msgid "" -"Interrupts always go to the main thread (the :exc:`KeyboardInterrupt` " -"exception will be received by that thread.)" -msgstr "中斷總會跳到主執行緒（該執行緒將接收 :exc:`KeyboardInterrupt` 例外。）" - -#: ../../library/_thread.rst:222 -msgid "" -"Calling :func:`sys.exit` or raising the :exc:`SystemExit` exception is " -"equivalent to calling :func:`_thread.exit`." -msgstr "" -"呼叫 :func:`sys.exit` 函式或引發 :exc:`SystemExit` 例外等同於呼" -"叫 :func:`_thread.exit` 函式。" - -#: ../../library/_thread.rst:225 -msgid "" -"When the main thread exits, it is system defined whether the other threads " -"survive. On most systems, they are killed without " -"executing :keyword:`try` ... :keyword:`finally` clauses or executing object " -"destructors." -msgstr "" -"當主執行緒退出時，其他執行緒是否保留是由系統決定的。在大多數系統上，它們將被" -"終止，而不會執行 :keyword:`try` ... :keyword:`finally` 子句或執行物件的解構函" -"式。" - -#: ../../library/_thread.rst:7 -msgid "light-weight processes" -msgstr "light-weight processes（輕量級行程）" - -#: ../../library/_thread.rst:7 -msgid "processes, light-weight" -msgstr "processes, light-weight（行程，輕量級）" - -#: ../../library/_thread.rst:7 -msgid "binary semaphores" -msgstr "binary semaphores（二進位號誌）" - -#: ../../library/_thread.rst:7 -msgid "semaphores, binary" -msgstr "semaphores, binary（號誌，二進位）" - -#: ../../library/_thread.rst:22 -msgid "pthreads" -msgstr "pthreads" - -#: ../../library/_thread.rst:22 -msgid "threads" -msgstr "threads（執行緒）" - -#: ../../library/_thread.rst:22 -msgid "POSIX" -msgstr "POSIX" - -#: ../../library/_thread.rst:217 -msgid "module" -msgstr "module（模組）" - -#: ../../library/_thread.rst:217 -msgid "signal" -msgstr "signal（訊號）" - -#~ msgid "" -#~ "It is platform-dependent whether the :meth:`~threading.Lock.acquire` " -#~ "method on a lock can be interrupted (so that the :exc:`KeyboardInterrupt` " -#~ "exception will happen immediately, rather than only after the lock has " -#~ "been acquired or the operation has timed out). It can be interrupted on " -#~ "POSIX, but not on Windows." -#~ msgstr "" -#~ "鎖的 :meth:`~threading.Lock.acquire` 方法是否可以中斷（如此一" -#~ "來 :exc:`KeyboardInterrupt` 例外會立即發生，而不是僅在取得鎖或操作逾時後）" -#~ "是取決於平台的。在 POSIX 上可以中斷，但在 Windows 上則不行。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: 2015-12-09 17:51+0000\n" +"Last-Translator: Liang-Bo Wang \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/_thread.rst:2 +msgid ":mod:`!_thread` --- Low-level threading API" +msgstr ":mod:`!_thread` --- 低階執行緒 API" + +#: ../../library/_thread.rst:15 +msgid "" +"This module provides low-level primitives for working with multiple threads " +"(also called :dfn:`light-weight processes` or :dfn:`tasks`) --- multiple " +"threads of control sharing their global data space. For synchronization, " +"simple locks (also called :dfn:`mutexes` or :dfn:`binary semaphores`) are " +"provided. The :mod:`threading` module provides an easier to use and higher-" +"level threading API built on top of this module." +msgstr "" +"這個模組提供了與多個執行緒（也稱為:dfn:`輕量級行程` 或 :dfn: `任務`）一起工作" +"的低階原始物件 --- 多個控制執行緒分享其全域資料空間。為了處理同步問題，也提供" +"了簡單的鎖 (lock) 機制（也稱為:dfn:`互斥鎖` 或 :dfn:`二進位號誌" +"`）。 :mod:`threading` 模組提供了一個建立在這個模組之上的更易於使用和高階的執" +"行緒 API。" + +#: ../../library/_thread.rst:26 +msgid "This module used to be optional, it is now always available." +msgstr "這個模組之前是可選擇性的，但現在已經是可用的。" + +#: ../../library/_thread.rst:29 +msgid "This module defines the following constants and functions:" +msgstr "這個模組定義了以下的常數和函式：" + +#: ../../library/_thread.rst:33 +msgid "Raised on thread-specific errors." +msgstr "在執行緒相關的錯誤發生時引發。" + +#: ../../library/_thread.rst:35 +msgid "This is now a synonym of the built-in :exc:`RuntimeError`." +msgstr "現在是內建例外 :exc:`RuntimeError` 的別名。" + +#: ../../library/_thread.rst:41 +msgid "This is the type of lock objects." +msgstr "這是鎖物件的型別。" + +#: ../../library/_thread.rst:46 +msgid "" +"Start a new thread and return its identifier. The thread executes the " +"function *function* with the argument list *args* (which must be a tuple). " +"The optional *kwargs* argument specifies a dictionary of keyword arguments." +msgstr "" +"開始一個新的執行緒並回傳其識別字 (identifier) 。該執行緒執行帶有引數列表 " +"*args*\\ （必須是一個 tuple（元組））的函式 *function*。可選的 *kwargs* 引數指定" +"一個關鍵字引數的字典。" + +#: ../../library/_thread.rst:50 +msgid "When the function returns, the thread silently exits." +msgstr "當函式回傳時，執行緒會靜默退出。" + +#: ../../library/_thread.rst:52 +msgid "" +"When the function terminates with an unhandled " +"exception, :func:`sys.unraisablehook` is called to handle the exception. The " +"*object* attribute of the hook argument is *function*. By default, a stack " +"trace is printed and then the thread exits (but other threads continue to " +"run)." +msgstr "" +"當函式因未處理的例外終止時，將呼叫 :func:`sys.unraisablehook` 來處理該例外。" +"鉤子引數的 *object* 屬性是 *function*。預設情況下，會列印堆疊跟蹤，然後執行緒" +"退出（但其他執行緒會繼續運行）。" + +#: ../../library/_thread.rst:57 +msgid "" +"When the function raises a :exc:`SystemExit` exception, it is silently " +"ignored." +msgstr "當函式引發 :exc:`SystemExit` 例外時，它會被靜默忽略。" + +#: ../../library/_thread.rst:60 +msgid "" +"Raises an :ref:`auditing event ` ``_thread.start_new_thread`` with " +"arguments ``function``, ``args``, ``kwargs``." +msgstr "" +"引發一個 :ref:`稽核事件 ` ``_thread.start_new_thread``，帶有引數 " +"``function``、``args`` 和 ``kwargs``。" + +#: ../../library/_thread.rst:62 +msgid ":func:`sys.unraisablehook` is now used to handle unhandled exceptions." +msgstr "現在使用 :func:`sys.unraisablehook` 來處理未處理的例外。" + +#: ../../library/_thread.rst:68 +msgid "" +"Simulate the effect of a signal arriving in the main thread. A thread can " +"use this function to interrupt the main thread, though there is no guarantee " +"that the interruption will happen immediately." +msgstr "" +"模擬一個訊號到達主執行緒的效果。執行緒可以使用此函式來中斷主執行緒，但無法保" +"證中斷會立即發生。" + +#: ../../library/_thread.rst:72 +msgid "" +"If given, *signum* is the number of the signal to simulate. If *signum* is " +"not given, :const:`signal.SIGINT` is simulated." +msgstr "" +"如果提供了 *signum*，則模擬指定的訊號編號。如果未提供 *signum*，則模" +"擬 :const:`signal.SIGINT` 訊號。" + +#: ../../library/_thread.rst:75 +msgid "" +"If the given signal isn't handled by Python (it was set " +"to :const:`signal.SIG_DFL` or :const:`signal.SIG_IGN`), this function does " +"nothing." +msgstr "" +"如果給定的訊號在 Python 中未被處理（即設置為 :const:`signal.SIG_DFL` " +"或 :const:`signal.SIG_IGN`），此函式不做任何操作。" + +#: ../../library/_thread.rst:79 +msgid "The *signum* argument is added to customize the signal number." +msgstr "新增了 *signum* 引數以自訂訊號編號。" + +#: ../../library/_thread.rst:83 +msgid "" +"This does not emit the corresponding signal but schedules a call to the " +"associated handler (if it exists). If you want to truly emit the signal, " +"use :func:`signal.raise_signal`." +msgstr "" +"這並不會發出對應的訊號，而是安排呼叫相應的處理器（如果存在的話）。如果你想真" +"正發出訊號，請使用 :func:`signal.raise_signal`。" + +#: ../../library/_thread.rst:90 +msgid "" +"Raise the :exc:`SystemExit` exception. When not caught, this will cause the " +"thread to exit silently." +msgstr "引發 :exc:`SystemExit` 例外。當未捕獲時，將導致執行緒靜默退出。" + +#: ../../library/_thread.rst:104 +msgid "" +"Return a new lock object. Methods of locks are described below. The lock " +"is initially unlocked." +msgstr "回傳一個新的鎖物件。鎖物件的方法如下所述。初始狀況下鎖是解鎖狀態。" + +#: ../../library/_thread.rst:110 +msgid "" +"Return the 'thread identifier' of the current thread. This is a nonzero " +"integer. Its value has no direct meaning; it is intended as a magic cookie " +"to be used e.g. to index a dictionary of thread-specific data. Thread " +"identifiers may be recycled when a thread exits and another thread is " +"created." +msgstr "" +"回傳目前執行緒的「執行緒識別字」。這是一個非零的整數。它的值沒有直接的含義；" +"它被用作一個 magic cookie，例如用於索引特定於執行緒的資料的字典。當執行緒退出" +"並建立另一個執行緒時，執行緒識別字可能會被重複使用。" + +#: ../../library/_thread.rst:118 +msgid "" +"Return the native integral Thread ID of the current thread assigned by the " +"kernel. This is a non-negative integer. Its value may be used to uniquely " +"identify this particular thread system-wide (until the thread terminates, " +"after which the value may be recycled by the OS)." +msgstr "" +"回傳由核心 (kernel) 分配的目前執行緒的原生整數執行緒 ID。這是一個非負整數。它" +"的值可用於在整個系統中唯一標識此特定執行緒（直到執行緒終止後，該值可能被操作" +"系統重新使用）。" + +#: ../../library/_thread.rst:123 ../../library/_thread.rst:148 +msgid "Availability" +msgstr "可用性" + +#: ../../library/_thread.rst:127 +msgid "Added support for GNU/kFreeBSD." +msgstr "新增了對 GNU/kFreeBSD 的支援。" + +#: ../../library/_thread.rst:133 +msgid "" +"Return the thread stack size used when creating new threads. The optional " +"*size* argument specifies the stack size to be used for subsequently created " +"threads, and must be 0 (use platform or configured default) or a positive " +"integer value of at least 32,768 (32 KiB). If *size* is not specified, 0 is " +"used. If changing the thread stack size is unsupported, " +"a :exc:`RuntimeError` is raised. If the specified stack size is invalid, " +"a :exc:`ValueError` is raised and the stack size is unmodified. 32 KiB is " +"currently the minimum supported stack size value to guarantee sufficient " +"stack space for the interpreter itself. Note that some platforms may have " +"particular restrictions on values for the stack size, such as requiring a " +"minimum stack size > 32 KiB or requiring allocation in multiples of the " +"system memory page size - platform documentation should be referred to for " +"more information (4 KiB pages are common; using multiples of 4096 for the " +"stack size is the suggested approach in the absence of more specific " +"information)." +msgstr "" +"回傳在建立新執行緒時使用的執行緒堆疊大小。可選的 *size* 引數指定了隨後建立的" +"執行緒要使用的堆疊大小，必須是 0（使用平台或配置的預設值）或至少 32,768（32 " +"KiB）的正整數值。如果未指定 *size*，則使用 0。如果不支援更改執行緒堆疊大小，" +"則會引發 :exc:`RuntimeError` 錯誤。如果指定的堆疊大小無效，則會引" +"發 :exc:`ValueError` 錯誤，並且堆疊大小不會被修改。目前，32 KiB 是保證直譯器" +"本身具有足夠堆疊空間所支援的最小堆疊大小值。請注意，某些平台對於堆疊大小的值" +"可能有特定的限制，例如要求最小堆疊大小 > 32 KiB，或要求按系統記憶體頁面大小的" +"倍數進行分配。應參考平台文件以取得更多訊息（4 KiB 頁面是比較普遍的；在缺乏更" +"具體訊息的情況下，建議使用 4096 的倍數作為堆疊大小）。" + +#: ../../library/_thread.rst:150 +msgid "Unix platforms with POSIX threads support." +msgstr "Unix 平台上支援 POSIX 執行緒。" + +#: ../../library/_thread.rst:155 +msgid "" +"The maximum value allowed for the *timeout* parameter of :meth:`Lock.acquire " +"`. Specifying a timeout greater than this value will " +"raise an :exc:`OverflowError`." +msgstr "" +":meth:`Lock.acquire ` 的 *timeout* 參數所允許的最大" +"值。指定超過此值的 timeout 將引發 :exc:`OverflowError` 錯誤。" + +#: ../../library/_thread.rst:162 +msgid "Lock objects have the following methods:" +msgstr "鎖物件具有以下方法：" + +#: ../../library/_thread.rst:167 +msgid "" +"Without any optional argument, this method acquires the lock " +"unconditionally, if necessary waiting until it is released by another thread " +"(only one thread at a time can acquire a lock --- that's their reason for " +"existence)." +msgstr "" +"沒有任何可選引數時，此方法無條件地取得鎖，必要時會等待直到被另一個執行緒釋放" +"（一次只能有一個執行緒取得鎖 --- 這正是鎖存在的原因）。" + +#: ../../library/_thread.rst:171 +msgid "" +"If the *blocking* argument is present, the action depends on its value: if " +"it is false, the lock is only acquired if it can be acquired immediately " +"without waiting, while if it is true, the lock is acquired unconditionally " +"as above." +msgstr "" +"如果存在 *blocking* 引數，則根據其值執行操作：如果為 False，只有在可以立即獲" +"取鎖而無需等待的情況下才取得鎖，而如果為 True，則像上面一樣無條件地取得鎖。" + +#: ../../library/_thread.rst:176 +msgid "" +"If the floating-point *timeout* argument is present and positive, it " +"specifies the maximum wait time in seconds before returning. A negative " +"*timeout* argument specifies an unbounded wait. You cannot specify a " +"*timeout* if *blocking* is false." +msgstr "" +"如果存在浮點數的 *timeout* 引數且為正值，則它指定了在回傳之前的最大等待時間" +"（以秒為單位）。如果 *timeout* 引數為負值，則表示等待時間會無限期地等待。如" +"果 *blocking* 為 False，則你無法指定 *timeout*。" + +#: ../../library/_thread.rst:181 +msgid "" +"The return value is ``True`` if the lock is acquired successfully, ``False`` " +"if not." +msgstr "如果成功取得鎖，回傳值為 ``True``，否則為 ``False``。" + +#: ../../library/_thread.rst:184 +msgid "The *timeout* parameter is new." +msgstr "新增的 *timeout* 參數。" + +#: ../../library/_thread.rst:187 +msgid "Lock acquires can now be interrupted by signals on POSIX." +msgstr "現在取得鎖的操作可以被 POSIX 訊號中斷。" + +#: ../../library/_thread.rst:190 +msgid "Lock acquires can now be interrupted by signals on Windows." +msgstr "" + +#: ../../library/_thread.rst:196 +msgid "" +"Releases the lock. The lock must have been acquired earlier, but not " +"necessarily by the same thread." +msgstr "釋放鎖。鎖必須先前被取得，但不一定是由同一個執行緒取得的。" + +#: ../../library/_thread.rst:202 +msgid "" +"Return the status of the lock: ``True`` if it has been acquired by some " +"thread, ``False`` if not." +msgstr "" +"回傳鎖的狀態：如果鎖已被某個執行緒取得，則回傳 ``True``，否則回傳 ``False``。" + +#: ../../library/_thread.rst:205 +msgid "" +"In addition to these methods, lock objects can also be used via " +"the :keyword:`with` statement, e.g.::" +msgstr "除了這些方法之外，鎖物件還可以透過 :keyword:`with` 語句來使用，例如：" + +#: ../../library/_thread.rst:208 +msgid "" +"import _thread\n" +"\n" +"a_lock = _thread.allocate_lock()\n" +"\n" +"with a_lock:\n" +" print(\"a_lock is locked while this executes\")" +msgstr "" +"import _thread\n" +"\n" +"a_lock = _thread.allocate_lock()\n" +"\n" +"with a_lock:\n" +" print(\"a_lock 在執行這裡時被鎖定\")" + +#: ../../library/_thread.rst:215 +msgid "**Caveats:**" +msgstr "**注意事項：**" + +#: ../../library/_thread.rst:219 +msgid "" +"Interrupts always go to the main thread (the :exc:`KeyboardInterrupt` " +"exception will be received by that thread.)" +msgstr "中斷總會跳到主執行緒（該執行緒將接收 :exc:`KeyboardInterrupt` 例外。）" + +#: ../../library/_thread.rst:222 +msgid "" +"Calling :func:`sys.exit` or raising the :exc:`SystemExit` exception is " +"equivalent to calling :func:`_thread.exit`." +msgstr "" +"呼叫 :func:`sys.exit` 函式或引發 :exc:`SystemExit` 例外等同於呼" +"叫 :func:`_thread.exit` 函式。" + +#: ../../library/_thread.rst:225 +msgid "" +"When the main thread exits, it is system defined whether the other threads " +"survive. On most systems, they are killed without " +"executing :keyword:`try` ... :keyword:`finally` clauses or executing object " +"destructors." +msgstr "" +"當主執行緒退出時，其他執行緒是否保留是由系統決定的。在大多數系統上，它們將被" +"終止，而不會執行 :keyword:`try` ... :keyword:`finally` 子句或執行物件的解構函" +"式。" + +#: ../../library/_thread.rst:7 +msgid "light-weight processes" +msgstr "light-weight processes（輕量級行程）" + +#: ../../library/_thread.rst:7 +msgid "processes, light-weight" +msgstr "processes, light-weight（行程，輕量級）" + +#: ../../library/_thread.rst:7 +msgid "binary semaphores" +msgstr "binary semaphores（二進位號誌）" + +#: ../../library/_thread.rst:7 +msgid "semaphores, binary" +msgstr "semaphores, binary（號誌，二進位）" + +#: ../../library/_thread.rst:22 +msgid "pthreads" +msgstr "pthreads" + +#: ../../library/_thread.rst:22 +msgid "threads" +msgstr "threads（執行緒）" + +#: ../../library/_thread.rst:22 +msgid "POSIX" +msgstr "POSIX" + +#: ../../library/_thread.rst:217 +msgid "module" +msgstr "module（模組）" + +#: ../../library/_thread.rst:217 +msgid "signal" +msgstr "signal（訊號）" + +#~ msgid "" +#~ "It is platform-dependent whether the :meth:`~threading.Lock.acquire` " +#~ "method on a lock can be interrupted (so that the :exc:`KeyboardInterrupt` " +#~ "exception will happen immediately, rather than only after the lock has " +#~ "been acquired or the operation has timed out). It can be interrupted on " +#~ "POSIX, but not on Windows." +#~ msgstr "" +#~ "鎖的 :meth:`~threading.Lock.acquire` 方法是否可以中斷（如此一" +#~ "來 :exc:`KeyboardInterrupt` 例外會立即發生，而不是僅在取得鎖或操作逾時後）" +#~ "是取決於平台的。在 POSIX 上可以中斷，但在 Windows 上則不行。" diff --git a/library/abc.po b/library/abc.po index 8d089e4686..35ed80e81b 100644 --- a/library/abc.po +++ b/library/abc.po @@ -1,679 +1,679 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Adrian Liaw , 2018 -# Matt Wang , 2022 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-02-27 00:15+0000\n" -"PO-Revision-Date: 2022-11-16 03:29+0800\n" -"Last-Translator: Matt Wang \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" -"X-Generator: Poedit 3.2\n" - -#: ../../library/abc.rst:2 -msgid ":mod:`!abc` --- Abstract Base Classes" -msgstr ":mod:`!abc` --- 抽象基底類別" - -#: ../../library/abc.rst:11 -msgid "**Source code:** :source:`Lib/abc.py`" -msgstr "**原始碼：**\\ :source:`Lib/abc.py`" - -#: ../../library/abc.rst:15 -msgid "" -"This module provides the infrastructure for defining :term:`abstract base " -"classes ` (ABCs) in Python, as outlined in :pep:`3119`; " -"see the PEP for why this was added to Python. (See also :pep:`3141` and " -"the :mod:`numbers` module regarding a type hierarchy for numbers based on " -"ABCs.)" -msgstr "" -"如同在 :pep:`3119` 中所述，該模組提供了在 Python 中定義\\ :term:`抽象基底類" -"別 ` (ABC) 的基礎元件；若想瞭解為什麼需要在 Python 中增" -"加這個模組，請見 PEP 文件。（也請見 :pep:`3141` 以及 :mod:`numbers` 模組以瞭" -"解基於 ABC 的數字型別階層關係。）" - -#: ../../library/abc.rst:20 -msgid "" -"The :mod:`collections` module has some concrete classes that derive from " -"ABCs; these can, of course, be further derived. In addition, " -"the :mod:`collections.abc` submodule has some ABCs that can be used to test " -"whether a class or instance provides a particular interface, for example, if " -"it is :term:`hashable` or if it is a :term:`mapping`." -msgstr "" -":mod:`collections` 模組中有一些衍生自 ABC 的具體類別；當然這些類別還可以進一" -"步衍生出其他類別。此外，:mod:`collections.abc` 子模組中有一些 ABC 可被用於測" -"試一個類別或實例是否提供特定介面，例如它是否\\ :term:`可雜湊 (hashable) " -"` 或它是否為\\ :term:`對映 `。" - -#: ../../library/abc.rst:27 -msgid "" -"This module provides the metaclass :class:`ABCMeta` for defining ABCs and a " -"helper class :class:`ABC` to alternatively define ABCs through inheritance:" -msgstr "" -"該模組提供了一個用來定義 ABC 的元類別 (metaclass) :class:`ABCMeta` 和另一個以" -"繼承的方式定義 ABC 的工具類別 :class:`ABC`：" - -#: ../../library/abc.rst:32 -msgid "" -"A helper class that has :class:`ABCMeta` as its metaclass. With this class, " -"an abstract base class can be created by simply deriving from :class:`!ABC` " -"avoiding sometimes confusing metaclass usage, for example::" -msgstr "" -"一個使用 :class:`ABCMeta` 作為元類別的工具類別。抽象基底類別可以透過" -"自 :class:`!ABC` 衍生而建立，這就避免了在某些情況下會令人混淆的元類別用法，用" -"法如以下範例： ::" - -#: ../../library/abc.rst:36 -msgid "" -"from abc import ABC\n" -"\n" -"class MyABC(ABC):\n" -" pass" -msgstr "" -"from abc import ABC\n" -"\n" -"class MyABC(ABC):\n" -" pass" - -#: ../../library/abc.rst:41 -msgid "" -"Note that the type of :class:`!ABC` is still :class:`ABCMeta`, therefore " -"inheriting from :class:`!ABC` requires the usual precautions regarding " -"metaclass usage, as multiple inheritance may lead to metaclass conflicts. " -"One may also define an abstract base class by passing the metaclass keyword " -"and using :class:`!ABCMeta` directly, for example::" -msgstr "" -"注意 :class:`!ABC` 的型別仍然是 :class:`ABCMeta`，因此繼承 :class:`!ABC` 仍然" -"需要關注使用元類別的注意事項，如多重繼承可能會導致元類別衝突。當然你也可以傳" -"入元類別關鍵字並直接使用 :class:`!ABCMeta` 來定義一個抽象基底類別，例如： ::" - -#: ../../library/abc.rst:47 -msgid "" -"from abc import ABCMeta\n" -"\n" -"class MyABC(metaclass=ABCMeta):\n" -" pass" -msgstr "" -"from abc import ABCMeta\n" -"\n" -"class MyABC(metaclass=ABCMeta):\n" -" pass" - -#: ../../library/abc.rst:57 -msgid "Metaclass for defining Abstract Base Classes (ABCs)." -msgstr "用於定義抽象基底類別（ABC）的元類別。" - -#: ../../library/abc.rst:59 -msgid "" -"Use this metaclass to create an ABC. An ABC can be subclassed directly, and " -"then acts as a mix-in class. You can also register unrelated concrete " -"classes (even built-in classes) and unrelated ABCs as \"virtual subclasses\" " -"-- these and their descendants will be considered subclasses of the " -"registering ABC by the built-in :func:`issubclass` function, but the " -"registering ABC won't show up in their MRO (Method Resolution Order) nor " -"will method implementations defined by the registering ABC be callable (not " -"even via :func:`super`). [#]_" -msgstr "" -"使用該元類別以建立一個 ABC。一個 ABC 可以像 mix-in 類別一樣直接被子類別繼承。" -"你也可以將不相關的具體類別（甚至是內建類別）和 ABC 註冊為「虛擬子類別 " -"(virtual subclass)」 —— 這些類別以及它們的子類別會被內建函" -"式 :func:`issubclass` 識別為已註冊 ABC 的子類別，但是該 ABC 不會出現在其 MRO" -"（Method Resolution Order，方法解析順序）中，由該 ABC 所定義的方法實作也不可" -"呼叫（即使透過 :func:`super` 呼叫也不行）。[#]_" - -#: ../../library/abc.rst:68 -msgid "" -"Classes created with a metaclass of :class:`!ABCMeta` have the following " -"method:" -msgstr "使用 :class:`!ABCMeta` 作為元類別建立的類別含有以下的方法：" - -#: ../../library/abc.rst:72 -msgid "" -"Register *subclass* as a \"virtual subclass\" of this ABC. For example::" -msgstr "將\\ *子類別*\\ 註冊為該 ABC 的「抽象子類別」，例如： ::" - -#: ../../library/abc.rst:75 -msgid "" -"from abc import ABC\n" -"\n" -"class MyABC(ABC):\n" -" pass\n" -"\n" -"MyABC.register(tuple)\n" -"\n" -"assert issubclass(tuple, MyABC)\n" -"assert isinstance((), MyABC)" -msgstr "" -"from abc import ABC\n" -"\n" -"class MyABC(ABC):\n" -" pass\n" -"\n" -"MyABC.register(tuple)\n" -"\n" -"assert issubclass(tuple, MyABC)\n" -"assert isinstance((), MyABC)" - -#: ../../library/abc.rst:85 -msgid "Returns the registered subclass, to allow usage as a class decorator." -msgstr "回傳已註冊的子類別，使其能夠作為類別裝飾器。" - -#: ../../library/abc.rst:88 -msgid "" -"To detect calls to :meth:`!register`, you can use " -"the :func:`get_cache_token` function." -msgstr "" -"你可以使用 :func:`get_cache_token` 函式來檢測對 :meth:`!register` 的呼叫。" - -#: ../../library/abc.rst:92 -msgid "You can also override this method in an abstract base class:" -msgstr "你也可以覆寫 (override) 虛擬基底類別中的這個方法：" - -#: ../../library/abc.rst:96 -msgid "(Must be defined as a class method.)" -msgstr "（必須定義為類別方法。）" - -#: ../../library/abc.rst:98 -msgid "" -"Check whether *subclass* is considered a subclass of this ABC. This means " -"that you can customize the behavior of :func:`issubclass` further without " -"the need to call :meth:`register` on every class you want to consider a " -"subclass of the ABC. (This class method is called from " -"the :meth:`~type.__subclasscheck__` method of the ABC.)" -msgstr "" -"檢查 *subclass* 是否該被認為是該 ABC 的子類別，也就是說你可以直接自" -"訂 :func:`issubclass` 的行為，而不用對於那些你希望定義為該 ABC 的子類別的類別" -"都個別呼叫 :meth:`register` 方法。（這個類別方法是在 ABC " -"的 :meth:`~type.__subclasscheck__` 方法中呼叫。）" - -#: ../../library/abc.rst:104 -msgid "" -"This method should return ``True``, ``False`` or :data:`NotImplemented`. If " -"it returns ``True``, the *subclass* is considered a subclass of this ABC. If " -"it returns ``False``, the *subclass* is not considered a subclass of this " -"ABC, even if it would normally be one. If it returns :data:`!" -"NotImplemented`, the subclass check is continued with the usual mechanism." -msgstr "" -"此方法必須回傳 ``True``、``False`` 或是 :data:`NotImplemented`。如果回傳 " -"``True``，*subclass* 就會被認為是這個 ABC 的子類別。如果回傳 ``False``，" -"*subclass* 就會被判定並非該 ABC 的子類別，即便正常情況應如此。如果回" -"傳 :data:`!NotImplemented`，子類別檢查會按照正常機制繼續執行。" - -#: ../../library/abc.rst:114 -msgid "" -"For a demonstration of these concepts, look at this example ABC definition::" -msgstr "為了對這些概念做一演示，請見以下定義 ABC 的範例： ::" - -#: ../../library/abc.rst:116 -msgid "" -"class Foo:\n" -" def __getitem__(self, index):\n" -" ...\n" -" def __len__(self):\n" -" ...\n" -" def get_iterator(self):\n" -" return iter(self)\n" -"\n" -"class MyIterable(ABC):\n" -"\n" -" @abstractmethod\n" -" def __iter__(self):\n" -" while False:\n" -" yield None\n" -"\n" -" def get_iterator(self):\n" -" return self.__iter__()\n" -"\n" -" @classmethod\n" -" def __subclasshook__(cls, C):\n" -" if cls is MyIterable:\n" -" if any(\"__iter__\" in B.__dict__ for B in C.__mro__):\n" -" return True\n" -" return NotImplemented\n" -"\n" -"MyIterable.register(Foo)" -msgstr "" -"class Foo:\n" -" def __getitem__(self, index):\n" -" ...\n" -" def __len__(self):\n" -" ...\n" -" def get_iterator(self):\n" -" return iter(self)\n" -"\n" -"class MyIterable(ABC):\n" -"\n" -" @abstractmethod\n" -" def __iter__(self):\n" -" while False:\n" -" yield None\n" -"\n" -" def get_iterator(self):\n" -" return self.__iter__()\n" -"\n" -" @classmethod\n" -" def __subclasshook__(cls, C):\n" -" if cls is MyIterable:\n" -" if any(\"__iter__\" in B.__dict__ for B in C.__mro__):\n" -" return True\n" -" return NotImplemented\n" -"\n" -"MyIterable.register(Foo)" - -#: ../../library/abc.rst:143 -msgid "" -"The ABC ``MyIterable`` defines the standard iterable " -"method, :meth:`~object.__iter__`, as an abstract method. The implementation " -"given here can still be called from subclasses. The :meth:`!get_iterator` " -"method is also part of the ``MyIterable`` abstract base class, but it does " -"not have to be overridden in non-abstract derived classes." -msgstr "" -"ABC ``MyIterable`` 定義了作為抽象方法的一個標準疊代方" -"法 :meth:`~object.__iter__`。這裡給定的實作仍可在子類別中被呼叫。:meth:`!" -"get_iterator` 方法也是 ``MyIterable`` 抽象基底類別的一部分，但它不必被非抽象" -"衍生類別覆寫。" - -#: ../../library/abc.rst:149 -msgid "" -"The :meth:`__subclasshook__` class method defined here says that any class " -"that has an :meth:`~object.__iter__` method in its :attr:`~object.__dict__` " -"(or in that of one of its base classes, accessed via " -"the :attr:`~type.__mro__` list) is considered a ``MyIterable`` too." -msgstr "" -"這裡定義的 :meth:`__subclasshook__` 類別方法說明任何在" -"其 :attr:`~object.__dict__` (或在其透過 :attr:`~type.__mro__` 列表存取的基底" -"類別) 中具有 :meth:`~object.__iter__` 方法的類別也都會被視為 ``MyIterable``。" - -#: ../../library/abc.rst:154 -msgid "" -"Finally, the last line makes ``Foo`` a virtual subclass of ``MyIterable``, " -"even though it does not define an :meth:`~object.__iter__` method (it uses " -"the old-style iterable protocol, defined in terms of :meth:`~object.__len__` " -"and :meth:`~object.__getitem__`). Note that this will not make " -"``get_iterator`` available as a method of ``Foo``, so it is provided " -"separately." -msgstr "" -"最後，即使 ``Foo`` 沒有定義 :meth:`~object.__iter__` 方法（它使用了" -"以 :meth:`~object.__len__` 和 :meth:`~object.__getitem__` 所定義的舊式可疊代" -"物件協定），最末一行使其成為 ``MyIterable`` 的一個虛擬子類別。請注意這不會使 " -"``get_iterator`` 成為 ``Foo`` 的一個可用方法，所以它是需要被另外提供的。" - -#: ../../library/abc.rst:163 -msgid "The :mod:`!abc` module also provides the following decorator:" -msgstr ":mod:`!abc` 模組也提供了這些裝飾器：" - -#: ../../library/abc.rst:167 -msgid "A decorator indicating abstract methods." -msgstr "用於表示抽象方法的裝飾器。" - -#: ../../library/abc.rst:169 -msgid "" -"Using this decorator requires that the class's metaclass is :class:`ABCMeta` " -"or is derived from it. A class that has a metaclass derived from :class:`!" -"ABCMeta` cannot be instantiated unless all of its abstract methods and " -"properties are overridden. The abstract methods can be called using any of " -"the normal 'super' call mechanisms. :func:`!abstractmethod` may be used to " -"declare abstract methods for properties and descriptors." -msgstr "" -"類別的元類別是 :class:`ABCMeta` 或是從該類別衍生才能使用此裝飾器。一個具有衍" -"生自 :class:`!ABCMeta` 之元類別的類別不可以被實例化，除非它全部的抽象方法和特" -"性均已被覆寫。抽象方法可透過任何一般的 'super' 呼叫機制來呼叫。:func:`!" -"abstractmethod` 可被用於為特性和描述器宣告的抽象方法。" - -#: ../../library/abc.rst:176 -msgid "" -"Dynamically adding abstract methods to a class, or attempting to modify the " -"abstraction status of a method or class once it is created, are only " -"supported using the :func:`update_abstractmethods` function. The :func:`!" -"abstractmethod` only affects subclasses derived using regular inheritance; " -"\"virtual subclasses\" registered with the ABC's :meth:`~ABCMeta.register` " -"method are not affected." -msgstr "" -"僅在使用 :func:`update_abstractmethods` 函式時，才能夠動態地為一個類別新增抽" -"象方法，或者嘗試在方法或類別被建立後修改其抽象狀態。:func:`!abstractmethod` " -"只會影響使用常規繼承所衍生出的子類別；透過 ABC 的 :meth:`~ABCMeta.register` " -"方法註冊的「虛擬子類別」不會受到影響。" - -#: ../../library/abc.rst:183 -msgid "" -"When :func:`!abstractmethod` is applied in combination with other method " -"descriptors, it should be applied as the innermost decorator, as shown in " -"the following usage examples::" -msgstr "" -"當 :func:`!abstractmethod` 與其他方法描述器 (method descriptor) 配合應用時，" -"它應被當最內層的裝飾器，如以下用法範例所示： ::" - -#: ../../library/abc.rst:187 -msgid "" -"class C(ABC):\n" -" @abstractmethod\n" -" def my_abstract_method(self, arg1):\n" -" ...\n" -" @classmethod\n" -" @abstractmethod\n" -" def my_abstract_classmethod(cls, arg2):\n" -" ...\n" -" @staticmethod\n" -" @abstractmethod\n" -" def my_abstract_staticmethod(arg3):\n" -" ...\n" -"\n" -" @property\n" -" @abstractmethod\n" -" def my_abstract_property(self):\n" -" ...\n" -" @my_abstract_property.setter\n" -" @abstractmethod\n" -" def my_abstract_property(self, val):\n" -" ...\n" -"\n" -" @abstractmethod\n" -" def _get_x(self):\n" -" ...\n" -" @abstractmethod\n" -" def _set_x(self, val):\n" -" ...\n" -" x = property(_get_x, _set_x)" -msgstr "" -"class C(ABC):\n" -" @abstractmethod\n" -" def my_abstract_method(self, arg1):\n" -" ...\n" -" @classmethod\n" -" @abstractmethod\n" -" def my_abstract_classmethod(cls, arg2):\n" -" ...\n" -" @staticmethod\n" -" @abstractmethod\n" -" def my_abstract_staticmethod(arg3):\n" -" ...\n" -"\n" -" @property\n" -" @abstractmethod\n" -" def my_abstract_property(self):\n" -" ...\n" -" @my_abstract_property.setter\n" -" @abstractmethod\n" -" def my_abstract_property(self, val):\n" -" ...\n" -"\n" -" @abstractmethod\n" -" def _get_x(self):\n" -" ...\n" -" @abstractmethod\n" -" def _set_x(self, val):\n" -" ...\n" -" x = property(_get_x, _set_x)" - -#: ../../library/abc.rst:217 -msgid "" -"In order to correctly interoperate with the abstract base class machinery, " -"the descriptor must identify itself as abstract using :attr:`!" -"__isabstractmethod__`. In general, this attribute should be ``True`` if any " -"of the methods used to compose the descriptor are abstract. For example, " -"Python's built-in :class:`property` does the equivalent of::" -msgstr "" -"為了能正確地與 ABC 機制實作相互操作，描述器必須使用 :attr:`!" -"__isabstractmethod__` 將自身標識為抽象的。一般來說，如果被用於組成描述器的任" -"一方法是抽象的，則此屬性應當為 ``True``。 例如，Python 的內" -"建 :class:`property` 所做的就等價於： ::" - -#: ../../library/abc.rst:223 -msgid "" -"class Descriptor:\n" -" ...\n" -" @property\n" -" def __isabstractmethod__(self):\n" -" return any(getattr(f, '__isabstractmethod__', False) for\n" -" f in (self._fget, self._fset, self._fdel))" -msgstr "" -"class Descriptor:\n" -" ...\n" -" @property\n" -" def __isabstractmethod__(self):\n" -" return any(getattr(f, '__isabstractmethod__', False) for\n" -" f in (self._fget, self._fset, self._fdel))" - -#: ../../library/abc.rst:232 -msgid "" -"Unlike Java abstract methods, these abstract methods may have an " -"implementation. This implementation can be called via the :func:`super` " -"mechanism from the class that overrides it. This could be useful as an end-" -"point for a super-call in a framework that uses cooperative multiple-" -"inheritance." -msgstr "" -"不同於 Java 抽象方法，這些抽象方法可能具有一個實作。這個實作可在覆寫它的類別" -"上透過 :func:`super` 機制來呼叫。這在使用協作多重繼承 (cooperative multiple-" -"inheritance) 的框架中，可以被用作 super 呼叫的一個端點 (end-point)。" - -#: ../../library/abc.rst:239 -msgid "The :mod:`!abc` module also supports the following legacy decorators:" -msgstr ":mod:`!abc` 模組還支援下列舊式裝飾器：" - -#: ../../library/abc.rst:244 -msgid "" -"It is now possible to use :class:`classmethod` with :func:`abstractmethod`, " -"making this decorator redundant." -msgstr "" -"現在可以讓 :class:`classmethod` 配合 :func:`abstractmethod` 使用，使得此裝飾" -"器變得冗餘。" - -#: ../../library/abc.rst:248 -msgid "" -"A subclass of the built-in :func:`classmethod`, indicating an abstract " -"classmethod. Otherwise it is similar to :func:`abstractmethod`." -msgstr "" -"內建 :func:`classmethod` 的子類別，表示為一個抽象類別方法。在其他方面它都類似" -"於 :func:`abstractmethod`。" - -#: ../../library/abc.rst:251 -msgid "" -"This special case is deprecated, as the :func:`classmethod` decorator is now " -"correctly identified as abstract when applied to an abstract method::" -msgstr "" -"這個特例已被棄用，因為現在當 :func:`classmethod` 裝飾器應用於抽象方法時已會被" -"正確地標識為是抽象的： ::" - -#: ../../library/abc.rst:255 -msgid "" -"class C(ABC):\n" -" @classmethod\n" -" @abstractmethod\n" -" def my_abstract_classmethod(cls, arg):\n" -" ..." -msgstr "" -"class C(ABC):\n" -" @classmethod\n" -" @abstractmethod\n" -" def my_abstract_classmethod(cls, arg):\n" -" ..." - -#: ../../library/abc.rst:265 -msgid "" -"It is now possible to use :class:`staticmethod` with :func:`abstractmethod`, " -"making this decorator redundant." -msgstr "" -"現在可以讓 :class:`staticmethod` 配合 :func:`abstractmethod` 使用，使得此裝飾" -"器變得冗餘。" - -#: ../../library/abc.rst:269 -msgid "" -"A subclass of the built-in :func:`staticmethod`, indicating an abstract " -"staticmethod. Otherwise it is similar to :func:`abstractmethod`." -msgstr "" -"內建 :func:`staticmethod` 的子類別，表示為一個抽象靜態方法。在其他方面它都類" -"似於 :func:`abstractmethod`。" - -#: ../../library/abc.rst:272 -msgid "" -"This special case is deprecated, as the :func:`staticmethod` decorator is " -"now correctly identified as abstract when applied to an abstract method::" -msgstr "" -"這個特例已被棄用，因為現在當 :func:`staticmethod` 裝飾器應用於抽象方法時已會" -"被正確地標識為是抽象的： ::" - -#: ../../library/abc.rst:276 -msgid "" -"class C(ABC):\n" -" @staticmethod\n" -" @abstractmethod\n" -" def my_abstract_staticmethod(arg):\n" -" ..." -msgstr "" -"class C(ABC):\n" -" @staticmethod\n" -" @abstractmethod\n" -" def my_abstract_staticmethod(arg):\n" -" ..." - -#: ../../library/abc.rst:285 -msgid "" -"It is now possible to " -"use :class:`property`, :meth:`property.getter`, :meth:`property.setter` " -"and :meth:`property.deleter` with :func:`abstractmethod`, making this " -"decorator redundant." -msgstr "" -"現在可以" -"讓 :class:`property`、:meth:`property.getter`、:meth:`property.setter` " -"和 :meth:`property.deleter` 配合 :func:`abstractmethod` 使用，使得此裝飾器變" -"得冗餘。" - -#: ../../library/abc.rst:290 -msgid "" -"A subclass of the built-in :func:`property`, indicating an abstract property." -msgstr "內建 :func:`property` 的子類別，表示為一個抽象特性。" - -#: ../../library/abc.rst:293 -msgid "" -"This special case is deprecated, as the :func:`property` decorator is now " -"correctly identified as abstract when applied to an abstract method::" -msgstr "" -"這個特例已被棄用，因為現在當 :func:`property` 裝飾器應用於抽象方法時已會被正" -"確地標識為是抽象的： ::" - -#: ../../library/abc.rst:297 -msgid "" -"class C(ABC):\n" -" @property\n" -" @abstractmethod\n" -" def my_abstract_property(self):\n" -" ..." -msgstr "" -"class C(ABC):\n" -" @property\n" -" @abstractmethod\n" -" def my_abstract_property(self):\n" -" ..." - -#: ../../library/abc.rst:303 -msgid "" -"The above example defines a read-only property; you can also define a read-" -"write abstract property by appropriately marking one or more of the " -"underlying methods as abstract::" -msgstr "" -"上面的例子定義了一個唯讀特性；你也可以透過適當地將一個或多個底層方法標記為抽" -"象的來定義可讀寫的抽象特性： ::" - -#: ../../library/abc.rst:307 -msgid "" -"class C(ABC):\n" -" @property\n" -" def x(self):\n" -" ...\n" -"\n" -" @x.setter\n" -" @abstractmethod\n" -" def x(self, val):\n" -" ..." -msgstr "" -"class C(ABC):\n" -" @property\n" -" def x(self):\n" -" ...\n" -"\n" -" @x.setter\n" -" @abstractmethod\n" -" def x(self, val):\n" -" ..." - -#: ../../library/abc.rst:317 -msgid "" -"If only some components are abstract, only those components need to be " -"updated to create a concrete property in a subclass::" -msgstr "" -"如果只有某些元件是抽象的，則只需更新那些元件即可在子類別中建立具體的特性： ::" - -#: ../../library/abc.rst:320 -msgid "" -"class D(C):\n" -" @C.x.setter\n" -" def x(self, val):\n" -" ..." -msgstr "" -"class D(C):\n" -" @C.x.setter\n" -" def x(self, val):\n" -" ..." - -#: ../../library/abc.rst:326 -msgid "The :mod:`!abc` module also provides the following functions:" -msgstr ":mod:`!abc` 模組也提供了這些函式：" - -#: ../../library/abc.rst:330 -msgid "Returns the current abstract base class cache token." -msgstr "回傳目前 ABC 快取令牌 (cache token)。" - -#: ../../library/abc.rst:332 -msgid "" -"The token is an opaque object (that supports equality testing) identifying " -"the current version of the abstract base class cache for virtual subclasses. " -"The token changes with every call to :meth:`ABCMeta.register` on any ABC." -msgstr "" -"此令牌是一個（支援相等性測試的）不透明物件 (opaque object)，用於為虛擬子類別" -"標識抽象基底類別快取的目前版本。此令牌會在任何 ABC 上每次呼" -"叫 :meth:`ABCMeta.register` 時發生更改。" - -#: ../../library/abc.rst:340 -msgid "" -"A function to recalculate an abstract class's abstraction status. This " -"function should be called if a class's abstract methods have been " -"implemented or changed after it was created. Usually, this function should " -"be called from within a class decorator." -msgstr "" -"重新計算一個抽象類別之抽象狀態的函式。如果一個類別的抽象方法在建立後被實作或" -"被修改，則應當呼叫此函式。通常此函式應在一個類別裝飾器內部被呼叫。" - -#: ../../library/abc.rst:345 -msgid "Returns *cls*, to allow usage as a class decorator." -msgstr "回傳 *cls*，使其能夠用作為類別的裝飾器。" - -#: ../../library/abc.rst:347 -msgid "If *cls* is not an instance of :class:`ABCMeta`, does nothing." -msgstr "如果 *cls* 不是 :class:`ABCMeta` 的實例則不做任何操作。" - -#: ../../library/abc.rst:351 -msgid "" -"This function assumes that *cls*'s superclasses are already updated. It does " -"not update any subclasses." -msgstr "" -"此函式會假定 *cls* 的超類別 (superclass) 已經被更新。它不會更新任何子類別。" - -#: ../../library/abc.rst:357 -msgid "Footnotes" -msgstr "註腳" - -#: ../../library/abc.rst:358 -msgid "" -"C++ programmers should note that Python's virtual base class concept is not " -"the same as C++'s." -msgstr "" -"C++ 程式設計師需要注意到 Python 中虛擬基底類別的概念和 C++ 中的並不相同。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Adrian Liaw , 2018 +# Matt Wang , 2022 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-02-27 00:15+0000\n" +"PO-Revision-Date: 2022-11-16 03:29+0800\n" +"Last-Translator: Matt Wang \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" +"X-Generator: Poedit 3.2\n" + +#: ../../library/abc.rst:2 +msgid ":mod:`!abc` --- Abstract Base Classes" +msgstr ":mod:`!abc` --- 抽象基底類別" + +#: ../../library/abc.rst:11 +msgid "**Source code:** :source:`Lib/abc.py`" +msgstr "**原始碼：**\\ :source:`Lib/abc.py`" + +#: ../../library/abc.rst:15 +msgid "" +"This module provides the infrastructure for defining :term:`abstract base " +"classes ` (ABCs) in Python, as outlined in :pep:`3119`; " +"see the PEP for why this was added to Python. (See also :pep:`3141` and " +"the :mod:`numbers` module regarding a type hierarchy for numbers based on " +"ABCs.)" +msgstr "" +"如同在 :pep:`3119` 中所述，該模組提供了在 Python 中定義\\ :term:`抽象基底類" +"別 ` (ABC) 的基礎元件；若想瞭解為什麼需要在 Python 中增" +"加這個模組，請見 PEP 文件。（也請見 :pep:`3141` 以及 :mod:`numbers` 模組以瞭" +"解基於 ABC 的數字型別階層關係。）" + +#: ../../library/abc.rst:20 +msgid "" +"The :mod:`collections` module has some concrete classes that derive from " +"ABCs; these can, of course, be further derived. In addition, " +"the :mod:`collections.abc` submodule has some ABCs that can be used to test " +"whether a class or instance provides a particular interface, for example, if " +"it is :term:`hashable` or if it is a :term:`mapping`." +msgstr "" +":mod:`collections` 模組中有一些衍生自 ABC 的具體類別；當然這些類別還可以進一" +"步衍生出其他類別。此外，:mod:`collections.abc` 子模組中有一些 ABC 可被用於測" +"試一個類別或實例是否提供特定介面，例如它是否\\ :term:`可雜湊 (hashable) " +"` 或它是否為\\ :term:`對映 `。" + +#: ../../library/abc.rst:27 +msgid "" +"This module provides the metaclass :class:`ABCMeta` for defining ABCs and a " +"helper class :class:`ABC` to alternatively define ABCs through inheritance:" +msgstr "" +"該模組提供了一個用來定義 ABC 的元類別 (metaclass) :class:`ABCMeta` 和另一個以" +"繼承的方式定義 ABC 的工具類別 :class:`ABC`：" + +#: ../../library/abc.rst:32 +msgid "" +"A helper class that has :class:`ABCMeta` as its metaclass. With this class, " +"an abstract base class can be created by simply deriving from :class:`!ABC` " +"avoiding sometimes confusing metaclass usage, for example::" +msgstr "" +"一個使用 :class:`ABCMeta` 作為元類別的工具類別。抽象基底類別可以透過" +"自 :class:`!ABC` 衍生而建立，這就避免了在某些情況下會令人混淆的元類別用法，用" +"法如以下範例： ::" + +#: ../../library/abc.rst:36 +msgid "" +"from abc import ABC\n" +"\n" +"class MyABC(ABC):\n" +" pass" +msgstr "" +"from abc import ABC\n" +"\n" +"class MyABC(ABC):\n" +" pass" + +#: ../../library/abc.rst:41 +msgid "" +"Note that the type of :class:`!ABC` is still :class:`ABCMeta`, therefore " +"inheriting from :class:`!ABC` requires the usual precautions regarding " +"metaclass usage, as multiple inheritance may lead to metaclass conflicts. " +"One may also define an abstract base class by passing the metaclass keyword " +"and using :class:`!ABCMeta` directly, for example::" +msgstr "" +"注意 :class:`!ABC` 的型別仍然是 :class:`ABCMeta`，因此繼承 :class:`!ABC` 仍然" +"需要關注使用元類別的注意事項，如多重繼承可能會導致元類別衝突。當然你也可以傳" +"入元類別關鍵字並直接使用 :class:`!ABCMeta` 來定義一個抽象基底類別，例如： ::" + +#: ../../library/abc.rst:47 +msgid "" +"from abc import ABCMeta\n" +"\n" +"class MyABC(metaclass=ABCMeta):\n" +" pass" +msgstr "" +"from abc import ABCMeta\n" +"\n" +"class MyABC(metaclass=ABCMeta):\n" +" pass" + +#: ../../library/abc.rst:57 +msgid "Metaclass for defining Abstract Base Classes (ABCs)." +msgstr "用於定義抽象基底類別（ABC）的元類別。" + +#: ../../library/abc.rst:59 +msgid "" +"Use this metaclass to create an ABC. An ABC can be subclassed directly, and " +"then acts as a mix-in class. You can also register unrelated concrete " +"classes (even built-in classes) and unrelated ABCs as \"virtual subclasses\" " +"-- these and their descendants will be considered subclasses of the " +"registering ABC by the built-in :func:`issubclass` function, but the " +"registering ABC won't show up in their MRO (Method Resolution Order) nor " +"will method implementations defined by the registering ABC be callable (not " +"even via :func:`super`). [#]_" +msgstr "" +"使用該元類別以建立一個 ABC。一個 ABC 可以像 mix-in 類別一樣直接被子類別繼承。" +"你也可以將不相關的具體類別（甚至是內建類別）和 ABC 註冊為「虛擬子類別 " +"(virtual subclass)」 —— 這些類別以及它們的子類別會被內建函" +"式 :func:`issubclass` 識別為已註冊 ABC 的子類別，但是該 ABC 不會出現在其 MRO" +"（Method Resolution Order，方法解析順序）中，由該 ABC 所定義的方法實作也不可" +"呼叫（即使透過 :func:`super` 呼叫也不行）。[#]_" + +#: ../../library/abc.rst:68 +msgid "" +"Classes created with a metaclass of :class:`!ABCMeta` have the following " +"method:" +msgstr "使用 :class:`!ABCMeta` 作為元類別建立的類別含有以下的方法：" + +#: ../../library/abc.rst:72 +msgid "" +"Register *subclass* as a \"virtual subclass\" of this ABC. For example::" +msgstr "將\\ *子類別*\\ 註冊為該 ABC 的「抽象子類別」，例如： ::" + +#: ../../library/abc.rst:75 +msgid "" +"from abc import ABC\n" +"\n" +"class MyABC(ABC):\n" +" pass\n" +"\n" +"MyABC.register(tuple)\n" +"\n" +"assert issubclass(tuple, MyABC)\n" +"assert isinstance((), MyABC)" +msgstr "" +"from abc import ABC\n" +"\n" +"class MyABC(ABC):\n" +" pass\n" +"\n" +"MyABC.register(tuple)\n" +"\n" +"assert issubclass(tuple, MyABC)\n" +"assert isinstance((), MyABC)" + +#: ../../library/abc.rst:85 +msgid "Returns the registered subclass, to allow usage as a class decorator." +msgstr "回傳已註冊的子類別，使其能夠作為類別裝飾器。" + +#: ../../library/abc.rst:88 +msgid "" +"To detect calls to :meth:`!register`, you can use " +"the :func:`get_cache_token` function." +msgstr "" +"你可以使用 :func:`get_cache_token` 函式來檢測對 :meth:`!register` 的呼叫。" + +#: ../../library/abc.rst:92 +msgid "You can also override this method in an abstract base class:" +msgstr "你也可以覆寫 (override) 虛擬基底類別中的這個方法：" + +#: ../../library/abc.rst:96 +msgid "(Must be defined as a class method.)" +msgstr "（必須定義為類別方法。）" + +#: ../../library/abc.rst:98 +msgid "" +"Check whether *subclass* is considered a subclass of this ABC. This means " +"that you can customize the behavior of :func:`issubclass` further without " +"the need to call :meth:`register` on every class you want to consider a " +"subclass of the ABC. (This class method is called from " +"the :meth:`~type.__subclasscheck__` method of the ABC.)" +msgstr "" +"檢查 *subclass* 是否該被認為是該 ABC 的子類別，也就是說你可以直接自" +"訂 :func:`issubclass` 的行為，而不用對於那些你希望定義為該 ABC 的子類別的類別" +"都個別呼叫 :meth:`register` 方法。（這個類別方法是在 ABC " +"的 :meth:`~type.__subclasscheck__` 方法中呼叫。）" + +#: ../../library/abc.rst:104 +msgid "" +"This method should return ``True``, ``False`` or :data:`NotImplemented`. If " +"it returns ``True``, the *subclass* is considered a subclass of this ABC. If " +"it returns ``False``, the *subclass* is not considered a subclass of this " +"ABC, even if it would normally be one. If it returns :data:`!" +"NotImplemented`, the subclass check is continued with the usual mechanism." +msgstr "" +"此方法必須回傳 ``True``、``False`` 或是 :data:`NotImplemented`。如果回傳 " +"``True``，*subclass* 就會被認為是這個 ABC 的子類別。如果回傳 ``False``，" +"*subclass* 就會被判定並非該 ABC 的子類別，即便正常情況應如此。如果回" +"傳 :data:`!NotImplemented`，子類別檢查會按照正常機制繼續執行。" + +#: ../../library/abc.rst:114 +msgid "" +"For a demonstration of these concepts, look at this example ABC definition::" +msgstr "為了對這些概念做一演示，請見以下定義 ABC 的範例： ::" + +#: ../../library/abc.rst:116 +msgid "" +"class Foo:\n" +" def __getitem__(self, index):\n" +" ...\n" +" def __len__(self):\n" +" ...\n" +" def get_iterator(self):\n" +" return iter(self)\n" +"\n" +"class MyIterable(ABC):\n" +"\n" +" @abstractmethod\n" +" def __iter__(self):\n" +" while False:\n" +" yield None\n" +"\n" +" def get_iterator(self):\n" +" return self.__iter__()\n" +"\n" +" @classmethod\n" +" def __subclasshook__(cls, C):\n" +" if cls is MyIterable:\n" +" if any(\"__iter__\" in B.__dict__ for B in C.__mro__):\n" +" return True\n" +" return NotImplemented\n" +"\n" +"MyIterable.register(Foo)" +msgstr "" +"class Foo:\n" +" def __getitem__(self, index):\n" +" ...\n" +" def __len__(self):\n" +" ...\n" +" def get_iterator(self):\n" +" return iter(self)\n" +"\n" +"class MyIterable(ABC):\n" +"\n" +" @abstractmethod\n" +" def __iter__(self):\n" +" while False:\n" +" yield None\n" +"\n" +" def get_iterator(self):\n" +" return self.__iter__()\n" +"\n" +" @classmethod\n" +" def __subclasshook__(cls, C):\n" +" if cls is MyIterable:\n" +" if any(\"__iter__\" in B.__dict__ for B in C.__mro__):\n" +" return True\n" +" return NotImplemented\n" +"\n" +"MyIterable.register(Foo)" + +#: ../../library/abc.rst:143 +msgid "" +"The ABC ``MyIterable`` defines the standard iterable " +"method, :meth:`~object.__iter__`, as an abstract method. The implementation " +"given here can still be called from subclasses. The :meth:`!get_iterator` " +"method is also part of the ``MyIterable`` abstract base class, but it does " +"not have to be overridden in non-abstract derived classes." +msgstr "" +"ABC ``MyIterable`` 定義了作為抽象方法的一個標準疊代方" +"法 :meth:`~object.__iter__`。這裡給定的實作仍可在子類別中被呼叫。:meth:`!" +"get_iterator` 方法也是 ``MyIterable`` 抽象基底類別的一部分，但它不必被非抽象" +"衍生類別覆寫。" + +#: ../../library/abc.rst:149 +msgid "" +"The :meth:`__subclasshook__` class method defined here says that any class " +"that has an :meth:`~object.__iter__` method in its :attr:`~object.__dict__` " +"(or in that of one of its base classes, accessed via " +"the :attr:`~type.__mro__` list) is considered a ``MyIterable`` too." +msgstr "" +"這裡定義的 :meth:`__subclasshook__` 類別方法說明任何在" +"其 :attr:`~object.__dict__` (或在其透過 :attr:`~type.__mro__` 列表存取的基底" +"類別) 中具有 :meth:`~object.__iter__` 方法的類別也都會被視為 ``MyIterable``。" + +#: ../../library/abc.rst:154 +msgid "" +"Finally, the last line makes ``Foo`` a virtual subclass of ``MyIterable``, " +"even though it does not define an :meth:`~object.__iter__` method (it uses " +"the old-style iterable protocol, defined in terms of :meth:`~object.__len__` " +"and :meth:`~object.__getitem__`). Note that this will not make " +"``get_iterator`` available as a method of ``Foo``, so it is provided " +"separately." +msgstr "" +"最後，即使 ``Foo`` 沒有定義 :meth:`~object.__iter__` 方法（它使用了" +"以 :meth:`~object.__len__` 和 :meth:`~object.__getitem__` 所定義的舊式可疊代" +"物件協定），最末一行使其成為 ``MyIterable`` 的一個虛擬子類別。請注意這不會使 " +"``get_iterator`` 成為 ``Foo`` 的一個可用方法，所以它是需要被另外提供的。" + +#: ../../library/abc.rst:163 +msgid "The :mod:`!abc` module also provides the following decorator:" +msgstr ":mod:`!abc` 模組也提供了這些裝飾器：" + +#: ../../library/abc.rst:167 +msgid "A decorator indicating abstract methods." +msgstr "用於表示抽象方法的裝飾器。" + +#: ../../library/abc.rst:169 +msgid "" +"Using this decorator requires that the class's metaclass is :class:`ABCMeta` " +"or is derived from it. A class that has a metaclass derived from :class:`!" +"ABCMeta` cannot be instantiated unless all of its abstract methods and " +"properties are overridden. The abstract methods can be called using any of " +"the normal 'super' call mechanisms. :func:`!abstractmethod` may be used to " +"declare abstract methods for properties and descriptors." +msgstr "" +"類別的元類別是 :class:`ABCMeta` 或是從該類別衍生才能使用此裝飾器。一個具有衍" +"生自 :class:`!ABCMeta` 之元類別的類別不可以被實例化，除非它全部的抽象方法和特" +"性均已被覆寫。抽象方法可透過任何一般的 'super' 呼叫機制來呼叫。:func:`!" +"abstractmethod` 可被用於為特性和描述器宣告的抽象方法。" + +#: ../../library/abc.rst:176 +msgid "" +"Dynamically adding abstract methods to a class, or attempting to modify the " +"abstraction status of a method or class once it is created, are only " +"supported using the :func:`update_abstractmethods` function. The :func:`!" +"abstractmethod` only affects subclasses derived using regular inheritance; " +"\"virtual subclasses\" registered with the ABC's :meth:`~ABCMeta.register` " +"method are not affected." +msgstr "" +"僅在使用 :func:`update_abstractmethods` 函式時，才能夠動態地為一個類別新增抽" +"象方法，或者嘗試在方法或類別被建立後修改其抽象狀態。:func:`!abstractmethod` " +"只會影響使用常規繼承所衍生出的子類別；透過 ABC 的 :meth:`~ABCMeta.register` " +"方法註冊的「虛擬子類別」不會受到影響。" + +#: ../../library/abc.rst:183 +msgid "" +"When :func:`!abstractmethod` is applied in combination with other method " +"descriptors, it should be applied as the innermost decorator, as shown in " +"the following usage examples::" +msgstr "" +"當 :func:`!abstractmethod` 與其他方法描述器 (method descriptor) 配合應用時，" +"它應被當最內層的裝飾器，如以下用法範例所示： ::" + +#: ../../library/abc.rst:187 +msgid "" +"class C(ABC):\n" +" @abstractmethod\n" +" def my_abstract_method(self, arg1):\n" +" ...\n" +" @classmethod\n" +" @abstractmethod\n" +" def my_abstract_classmethod(cls, arg2):\n" +" ...\n" +" @staticmethod\n" +" @abstractmethod\n" +" def my_abstract_staticmethod(arg3):\n" +" ...\n" +"\n" +" @property\n" +" @abstractmethod\n" +" def my_abstract_property(self):\n" +" ...\n" +" @my_abstract_property.setter\n" +" @abstractmethod\n" +" def my_abstract_property(self, val):\n" +" ...\n" +"\n" +" @abstractmethod\n" +" def _get_x(self):\n" +" ...\n" +" @abstractmethod\n" +" def _set_x(self, val):\n" +" ...\n" +" x = property(_get_x, _set_x)" +msgstr "" +"class C(ABC):\n" +" @abstractmethod\n" +" def my_abstract_method(self, arg1):\n" +" ...\n" +" @classmethod\n" +" @abstractmethod\n" +" def my_abstract_classmethod(cls, arg2):\n" +" ...\n" +" @staticmethod\n" +" @abstractmethod\n" +" def my_abstract_staticmethod(arg3):\n" +" ...\n" +"\n" +" @property\n" +" @abstractmethod\n" +" def my_abstract_property(self):\n" +" ...\n" +" @my_abstract_property.setter\n" +" @abstractmethod\n" +" def my_abstract_property(self, val):\n" +" ...\n" +"\n" +" @abstractmethod\n" +" def _get_x(self):\n" +" ...\n" +" @abstractmethod\n" +" def _set_x(self, val):\n" +" ...\n" +" x = property(_get_x, _set_x)" + +#: ../../library/abc.rst:217 +msgid "" +"In order to correctly interoperate with the abstract base class machinery, " +"the descriptor must identify itself as abstract using :attr:`!" +"__isabstractmethod__`. In general, this attribute should be ``True`` if any " +"of the methods used to compose the descriptor are abstract. For example, " +"Python's built-in :class:`property` does the equivalent of::" +msgstr "" +"為了能正確地與 ABC 機制實作相互操作，描述器必須使用 :attr:`!" +"__isabstractmethod__` 將自身標識為抽象的。一般來說，如果被用於組成描述器的任" +"一方法是抽象的，則此屬性應當為 ``True``。 例如，Python 的內" +"建 :class:`property` 所做的就等價於： ::" + +#: ../../library/abc.rst:223 +msgid "" +"class Descriptor:\n" +" ...\n" +" @property\n" +" def __isabstractmethod__(self):\n" +" return any(getattr(f, '__isabstractmethod__', False) for\n" +" f in (self._fget, self._fset, self._fdel))" +msgstr "" +"class Descriptor:\n" +" ...\n" +" @property\n" +" def __isabstractmethod__(self):\n" +" return any(getattr(f, '__isabstractmethod__', False) for\n" +" f in (self._fget, self._fset, self._fdel))" + +#: ../../library/abc.rst:232 +msgid "" +"Unlike Java abstract methods, these abstract methods may have an " +"implementation. This implementation can be called via the :func:`super` " +"mechanism from the class that overrides it. This could be useful as an end-" +"point for a super-call in a framework that uses cooperative multiple-" +"inheritance." +msgstr "" +"不同於 Java 抽象方法，這些抽象方法可能具有一個實作。這個實作可在覆寫它的類別" +"上透過 :func:`super` 機制來呼叫。這在使用協作多重繼承 (cooperative multiple-" +"inheritance) 的框架中，可以被用作 super 呼叫的一個端點 (end-point)。" + +#: ../../library/abc.rst:239 +msgid "The :mod:`!abc` module also supports the following legacy decorators:" +msgstr ":mod:`!abc` 模組還支援下列舊式裝飾器：" + +#: ../../library/abc.rst:244 +msgid "" +"It is now possible to use :class:`classmethod` with :func:`abstractmethod`, " +"making this decorator redundant." +msgstr "" +"現在可以讓 :class:`classmethod` 配合 :func:`abstractmethod` 使用，使得此裝飾" +"器變得冗餘。" + +#: ../../library/abc.rst:248 +msgid "" +"A subclass of the built-in :func:`classmethod`, indicating an abstract " +"classmethod. Otherwise it is similar to :func:`abstractmethod`." +msgstr "" +"內建 :func:`classmethod` 的子類別，表示為一個抽象類別方法。在其他方面它都類似" +"於 :func:`abstractmethod`。" + +#: ../../library/abc.rst:251 +msgid "" +"This special case is deprecated, as the :func:`classmethod` decorator is now " +"correctly identified as abstract when applied to an abstract method::" +msgstr "" +"這個特例已被棄用，因為現在當 :func:`classmethod` 裝飾器應用於抽象方法時已會被" +"正確地標識為是抽象的： ::" + +#: ../../library/abc.rst:255 +msgid "" +"class C(ABC):\n" +" @classmethod\n" +" @abstractmethod\n" +" def my_abstract_classmethod(cls, arg):\n" +" ..." +msgstr "" +"class C(ABC):\n" +" @classmethod\n" +" @abstractmethod\n" +" def my_abstract_classmethod(cls, arg):\n" +" ..." + +#: ../../library/abc.rst:265 +msgid "" +"It is now possible to use :class:`staticmethod` with :func:`abstractmethod`, " +"making this decorator redundant." +msgstr "" +"現在可以讓 :class:`staticmethod` 配合 :func:`abstractmethod` 使用，使得此裝飾" +"器變得冗餘。" + +#: ../../library/abc.rst:269 +msgid "" +"A subclass of the built-in :func:`staticmethod`, indicating an abstract " +"staticmethod. Otherwise it is similar to :func:`abstractmethod`." +msgstr "" +"內建 :func:`staticmethod` 的子類別，表示為一個抽象靜態方法。在其他方面它都類" +"似於 :func:`abstractmethod`。" + +#: ../../library/abc.rst:272 +msgid "" +"This special case is deprecated, as the :func:`staticmethod` decorator is " +"now correctly identified as abstract when applied to an abstract method::" +msgstr "" +"這個特例已被棄用，因為現在當 :func:`staticmethod` 裝飾器應用於抽象方法時已會" +"被正確地標識為是抽象的： ::" + +#: ../../library/abc.rst:276 +msgid "" +"class C(ABC):\n" +" @staticmethod\n" +" @abstractmethod\n" +" def my_abstract_staticmethod(arg):\n" +" ..." +msgstr "" +"class C(ABC):\n" +" @staticmethod\n" +" @abstractmethod\n" +" def my_abstract_staticmethod(arg):\n" +" ..." + +#: ../../library/abc.rst:285 +msgid "" +"It is now possible to " +"use :class:`property`, :meth:`property.getter`, :meth:`property.setter` " +"and :meth:`property.deleter` with :func:`abstractmethod`, making this " +"decorator redundant." +msgstr "" +"現在可以" +"讓 :class:`property`、:meth:`property.getter`、:meth:`property.setter` " +"和 :meth:`property.deleter` 配合 :func:`abstractmethod` 使用，使得此裝飾器變" +"得冗餘。" + +#: ../../library/abc.rst:290 +msgid "" +"A subclass of the built-in :func:`property`, indicating an abstract property." +msgstr "內建 :func:`property` 的子類別，表示為一個抽象特性。" + +#: ../../library/abc.rst:293 +msgid "" +"This special case is deprecated, as the :func:`property` decorator is now " +"correctly identified as abstract when applied to an abstract method::" +msgstr "" +"這個特例已被棄用，因為現在當 :func:`property` 裝飾器應用於抽象方法時已會被正" +"確地標識為是抽象的： ::" + +#: ../../library/abc.rst:297 +msgid "" +"class C(ABC):\n" +" @property\n" +" @abstractmethod\n" +" def my_abstract_property(self):\n" +" ..." +msgstr "" +"class C(ABC):\n" +" @property\n" +" @abstractmethod\n" +" def my_abstract_property(self):\n" +" ..." + +#: ../../library/abc.rst:303 +msgid "" +"The above example defines a read-only property; you can also define a read-" +"write abstract property by appropriately marking one or more of the " +"underlying methods as abstract::" +msgstr "" +"上面的例子定義了一個唯讀特性；你也可以透過適當地將一個或多個底層方法標記為抽" +"象的來定義可讀寫的抽象特性： ::" + +#: ../../library/abc.rst:307 +msgid "" +"class C(ABC):\n" +" @property\n" +" def x(self):\n" +" ...\n" +"\n" +" @x.setter\n" +" @abstractmethod\n" +" def x(self, val):\n" +" ..." +msgstr "" +"class C(ABC):\n" +" @property\n" +" def x(self):\n" +" ...\n" +"\n" +" @x.setter\n" +" @abstractmethod\n" +" def x(self, val):\n" +" ..." + +#: ../../library/abc.rst:317 +msgid "" +"If only some components are abstract, only those components need to be " +"updated to create a concrete property in a subclass::" +msgstr "" +"如果只有某些元件是抽象的，則只需更新那些元件即可在子類別中建立具體的特性： ::" + +#: ../../library/abc.rst:320 +msgid "" +"class D(C):\n" +" @C.x.setter\n" +" def x(self, val):\n" +" ..." +msgstr "" +"class D(C):\n" +" @C.x.setter\n" +" def x(self, val):\n" +" ..." + +#: ../../library/abc.rst:326 +msgid "The :mod:`!abc` module also provides the following functions:" +msgstr ":mod:`!abc` 模組也提供了這些函式：" + +#: ../../library/abc.rst:330 +msgid "Returns the current abstract base class cache token." +msgstr "回傳目前 ABC 快取令牌 (cache token)。" + +#: ../../library/abc.rst:332 +msgid "" +"The token is an opaque object (that supports equality testing) identifying " +"the current version of the abstract base class cache for virtual subclasses. " +"The token changes with every call to :meth:`ABCMeta.register` on any ABC." +msgstr "" +"此令牌是一個（支援相等性測試的）不透明物件 (opaque object)，用於為虛擬子類別" +"標識抽象基底類別快取的目前版本。此令牌會在任何 ABC 上每次呼" +"叫 :meth:`ABCMeta.register` 時發生更改。" + +#: ../../library/abc.rst:340 +msgid "" +"A function to recalculate an abstract class's abstraction status. This " +"function should be called if a class's abstract methods have been " +"implemented or changed after it was created. Usually, this function should " +"be called from within a class decorator." +msgstr "" +"重新計算一個抽象類別之抽象狀態的函式。如果一個類別的抽象方法在建立後被實作或" +"被修改，則應當呼叫此函式。通常此函式應在一個類別裝飾器內部被呼叫。" + +#: ../../library/abc.rst:345 +msgid "Returns *cls*, to allow usage as a class decorator." +msgstr "回傳 *cls*，使其能夠用作為類別的裝飾器。" + +#: ../../library/abc.rst:347 +msgid "If *cls* is not an instance of :class:`ABCMeta`, does nothing." +msgstr "如果 *cls* 不是 :class:`ABCMeta` 的實例則不做任何操作。" + +#: ../../library/abc.rst:351 +msgid "" +"This function assumes that *cls*'s superclasses are already updated. It does " +"not update any subclasses." +msgstr "" +"此函式會假定 *cls* 的超類別 (superclass) 已經被更新。它不會更新任何子類別。" + +#: ../../library/abc.rst:357 +msgid "Footnotes" +msgstr "註腳" + +#: ../../library/abc.rst:358 +msgid "" +"C++ programmers should note that Python's virtual base class concept is not " +"the same as C++'s." +msgstr "" +"C++ 程式設計師需要注意到 Python 中虛擬基底類別的概念和 C++ 中的並不相同。" diff --git a/library/aifc.po b/library/aifc.po index a9e6d77460..84bc76b237 100644 --- a/library/aifc.po +++ b/library/aifc.po @@ -1,39 +1,39 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -#, fuzzy -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-11-18 00:15+0000\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" -"tw)\n" -"Language: zh_TW\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=UTF-8\n" -"Content-Transfer-Encoding: 8bit\n" - -#: ../../library/aifc.rst:2 -msgid ":mod:`!aifc` --- Read and write AIFF and AIFC files" -msgstr ":mod:`!aifc` --- 讀寫 AIFF 與 AIFC 檔案" - -#: ../../library/aifc.rst:10 -msgid "" -"This module is no longer part of the Python standard library. It was :ref:" -"`removed in Python 3.13 ` after being deprecated in " -"Python 3.11. The removal was decided in :pep:`594`." -msgstr "" -"這個模組已不再是 Python 標準函式庫的一部分。它在 Python 3.11 中被棄用，並\\ :" -"ref:`已在 Python 3.13 中被移除 `。它的移除是在 :pep:" -"`594` 中決定的。" - -#: ../../library/aifc.rst:14 -msgid "" -"The last version of Python that provided the :mod:`!aifc` module was `Python " -"3.12 `_." -msgstr "" -"最後提供 :mod:`!aifc` 模組的 Python 版本是 `Python 3.12 `_。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-11-18 00:15+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" +"tw)\n" +"Language: zh_TW\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../library/aifc.rst:2 +msgid ":mod:`!aifc` --- Read and write AIFF and AIFC files" +msgstr ":mod:`!aifc` --- 讀寫 AIFF 與 AIFC 檔案" + +#: ../../library/aifc.rst:10 +msgid "" +"This module is no longer part of the Python standard library. It was :ref:" +"`removed in Python 3.13 ` after being deprecated in " +"Python 3.11. The removal was decided in :pep:`594`." +msgstr "" +"這個模組已不再是 Python 標準函式庫的一部分。它在 Python 3.11 中被棄用，並\\ :" +"ref:`已在 Python 3.13 中被移除 `。它的移除是在 :pep:" +"`594` 中決定的。" + +#: ../../library/aifc.rst:14 +msgid "" +"The last version of Python that provided the :mod:`!aifc` module was `Python " +"3.12 `_." +msgstr "" +"最後提供 :mod:`!aifc` 模組的 Python 版本是 `Python 3.12 `_。" diff --git a/library/allos.po b/library/allos.po index eb96940124..f2a4b8a403 100644 --- a/library/allos.po +++ b/library/allos.po @@ -1,36 +1,36 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Matt Wang , 2022 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2018-06-26 18:54+0800\n" -"PO-Revision-Date: 2022-02-15 17:54+0800\n" -"Last-Translator: Matt Wang \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" -"X-Generator: Poedit 3.0.1\n" - -#: ../../library/allos.rst:5 -msgid "Generic Operating System Services" -msgstr "通用作業系統服務" - -#: ../../library/allos.rst:7 -msgid "" -"The modules described in this chapter provide interfaces to operating system " -"features that are available on (almost) all operating systems, such as files " -"and a clock. The interfaces are generally modeled after the Unix or C " -"interfaces, but they are available on most other systems as well. Here's an " -"overview:" -msgstr "" -"此章節所描述的模組 (module) 提供了作業系統特性的使用介面，例如檔案與時鐘，" -"（幾乎）在所有作業系統上皆能使用。這些介面通常是參考 Unix 或 C 的介面來實作，" -"不過在其他大多數系統上也能使用。以下為概述：" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Matt Wang , 2022 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2018-06-26 18:54+0800\n" +"PO-Revision-Date: 2022-02-15 17:54+0800\n" +"Last-Translator: Matt Wang \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" +"X-Generator: Poedit 3.0.1\n" + +#: ../../library/allos.rst:5 +msgid "Generic Operating System Services" +msgstr "通用作業系統服務" + +#: ../../library/allos.rst:7 +msgid "" +"The modules described in this chapter provide interfaces to operating system " +"features that are available on (almost) all operating systems, such as files " +"and a clock. The interfaces are generally modeled after the Unix or C " +"interfaces, but they are available on most other systems as well. Here's an " +"overview:" +msgstr "" +"此章節所描述的模組 (module) 提供了作業系統特性的使用介面，例如檔案與時鐘，" +"（幾乎）在所有作業系統上皆能使用。這些介面通常是參考 Unix 或 C 的介面來實作，" +"不過在其他大多數系統上也能使用。以下為概述：" diff --git a/library/annotationlib.po b/library/annotationlib.po index 1ec686c8a7..2a45f54721 100644 --- a/library/annotationlib.po +++ b/library/annotationlib.po @@ -1,1029 +1,1029 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# FIRST AUTHOR , YEAR. -# -#, fuzzy -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-10-22 00:14+0000\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language-Team: LANGUAGE \n" -"Language: zh_TW\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=UTF-8\n" -"Content-Transfer-Encoding: 8bit\n" - -#: ../../library/annotationlib.rst:2 -msgid ":mod:`!annotationlib` --- Functionality for introspecting annotations" -msgstr ":mod:`!annotationlib` --- 用於自我檢查註釋的功能" - -#: ../../library/annotationlib.rst:9 -msgid "**Source code:** :source:`Lib/annotationlib.py`" -msgstr "**原始碼：** :source:`Lib/annotationlib.py`" - -#: ../../library/annotationlib.rst:18 -msgid "" -"The :mod:`!annotationlib` module provides tools for introspecting :term:" -"`annotations ` on modules, classes, and functions." -msgstr "" - -#: ../../library/annotationlib.rst:21 -msgid "" -"Annotations are :ref:`lazily evaluated ` and often contain " -"forward references to objects that are not yet defined when the annotation " -"is created. This module provides a set of low-level tools that can be used " -"to retrieve annotations in a reliable way, even in the presence of forward " -"references and other edge cases." -msgstr "" - -#: ../../library/annotationlib.rst:26 -msgid "" -"This module supports retrieving annotations in three main formats (see :" -"class:`Format`), each of which works best for different use cases:" -msgstr "" - -#: ../../library/annotationlib.rst:29 -msgid "" -":attr:`~Format.VALUE` evaluates the annotations and returns their value. " -"This is most straightforward to work with, but it may raise errors, for " -"example if the annotations contain references to undefined names." -msgstr "" - -#: ../../library/annotationlib.rst:32 -msgid "" -":attr:`~Format.FORWARDREF` returns :class:`ForwardRef` objects for " -"annotations that cannot be resolved, allowing you to inspect the annotations " -"without evaluating them. This is useful when you need to work with " -"annotations that may contain unresolved forward references." -msgstr "" - -#: ../../library/annotationlib.rst:36 -msgid "" -":attr:`~Format.STRING` returns the annotations as a string, similar to how " -"it would appear in the source file. This is useful for documentation " -"generators that want to display annotations in a readable way." -msgstr "" - -#: ../../library/annotationlib.rst:40 -msgid "" -"The :func:`get_annotations` function is the main entry point for retrieving " -"annotations. Given a function, class, or module, it returns an annotations " -"dictionary in the requested format. This module also provides functionality " -"for working directly with the :term:`annotate function` that is used to " -"evaluate annotations, such as :func:`get_annotate_from_class_namespace` and :" -"func:`call_annotate_function`, as well as the :func:`call_evaluate_function` " -"function for working with :term:`evaluate functions `." -msgstr "" - -#: ../../library/annotationlib.rst:51 -msgid "" -"Most functionality in this module can execute arbitrary code; see :ref:`the " -"security section ` for more information." -msgstr "" - -#: ../../library/annotationlib.rst:56 -msgid "" -":pep:`649` proposed the current model for how annotations work in Python." -msgstr "" - -#: ../../library/annotationlib.rst:58 -msgid "" -":pep:`749` expanded on various aspects of :pep:`649` and introduced the :mod:" -"`!annotationlib` module." -msgstr "" - -#: ../../library/annotationlib.rst:61 -msgid "" -":ref:`annotations-howto` provides best practices for working with " -"annotations." -msgstr "" - -#: ../../library/annotationlib.rst:64 -msgid "" -":pypi:`typing-extensions` provides a backport of :func:`get_annotations` " -"that works on earlier versions of Python." -msgstr "" - -#: ../../library/annotationlib.rst:68 -msgid "Annotation semantics" -msgstr "" - -#: ../../library/annotationlib.rst:70 -msgid "" -"The way annotations are evaluated has changed over the history of Python 3, " -"and currently still depends on a :ref:`future import `. There have " -"been execution models for annotations:" -msgstr "" - -#: ../../library/annotationlib.rst:74 -msgid "" -"*Stock semantics* (default in Python 3.0 through 3.13; see :pep:`3107` and :" -"pep:`526`): Annotations are evaluated eagerly, as they are encountered in " -"the source code." -msgstr "" - -#: ../../library/annotationlib.rst:77 -msgid "" -"*Stringified annotations* (used with ``from __future__ import annotations`` " -"in Python 3.7 and newer; see :pep:`563`): Annotations are stored as strings " -"only." -msgstr "" - -#: ../../library/annotationlib.rst:80 -msgid "" -"*Deferred evaluation* (default in Python 3.14 and newer; see :pep:`649` and :" -"pep:`749`): Annotations are evaluated lazily, only when they are accessed." -msgstr "" - -#: ../../library/annotationlib.rst:83 -msgid "As an example, consider the following program::" -msgstr "" - -#: ../../library/annotationlib.rst:85 -msgid "" -"def func(a: Cls) -> None:\n" -" print(a)\n" -"\n" -"class Cls: pass\n" -"\n" -"print(func.__annotations__)" -msgstr "" -"def func(a: Cls) -> None:\n" -" print(a)\n" -"\n" -"class Cls: pass\n" -"\n" -"print(func.__annotations__)" - -#: ../../library/annotationlib.rst:92 -msgid "This will behave as follows:" -msgstr "這會有以下行為：" - -#: ../../library/annotationlib.rst:94 -msgid "" -"Under stock semantics (Python 3.13 and earlier), it will throw a :exc:" -"`NameError` at the line where ``func`` is defined, because ``Cls`` is an " -"undefined name at that point." -msgstr "" - -#: ../../library/annotationlib.rst:97 -msgid "" -"Under stringified annotations (if ``from __future__ import annotations`` is " -"used), it will print ``{'a': 'Cls', 'return': 'None'}``." -msgstr "" - -#: ../../library/annotationlib.rst:99 -msgid "" -"Under deferred evaluation (Python 3.14 and later), it will print ``{'a': " -", 'return': None}``." -msgstr "" - -#: ../../library/annotationlib.rst:102 -msgid "" -"Stock semantics were used when function annotations were first introduced in " -"Python 3.0 (by :pep:`3107`) because this was the simplest, most obvious way " -"to implement annotations. The same execution model was used when variable " -"annotations were introduced in Python 3.6 (by :pep:`526`). However, stock " -"semantics caused problems when using annotations as type hints, such as a " -"need to refer to names that are not yet defined when the annotation is " -"encountered. In addition, there were performance problems with executing " -"annotations at module import time. Therefore, in Python 3.7, :pep:`563` " -"introduced the ability to store annotations as strings using the ``from " -"__future__ import annotations`` syntax. The plan at the time was to " -"eventually make this behavior the default, but a problem appeared: " -"stringified annotations are more difficult to process for those who " -"introspect annotations at runtime. An alternative proposal, :pep:`649`, " -"introduced the third execution model, deferred evaluation, and was " -"implemented in Python 3.14. Stringified annotations are still used if ``from " -"__future__ import annotations`` is present, but this behavior will " -"eventually be removed." -msgstr "" - -#: ../../library/annotationlib.rst:121 -msgid "Classes" -msgstr "" - -#: ../../library/annotationlib.rst:125 -msgid "" -"An :class:`~enum.IntEnum` describing the formats in which annotations can be " -"returned. Members of the enum, or their equivalent integer values, can be " -"passed to :func:`get_annotations` and other functions in this module, as " -"well as to :attr:`~object.__annotate__` functions." -msgstr "" - -#: ../../library/annotationlib.rst:133 -msgid "Values are the result of evaluating the annotation expressions." -msgstr "" - -#: ../../library/annotationlib.rst:138 -msgid "" -"Special value used to signal that an annotate function is being evaluated in " -"a special environment with fake globals. When passed this value, annotate " -"functions should either return the same value as for the :attr:`Format." -"VALUE` format, or raise :exc:`NotImplementedError` to signal that they do " -"not support execution in this environment. This format is only used " -"internally and should not be passed to the functions in this module." -msgstr "" - -#: ../../library/annotationlib.rst:149 -msgid "" -"Values are real annotation values (as per :attr:`Format.VALUE` format) for " -"defined values, and :class:`ForwardRef` proxies for undefined values. Real " -"objects may contain references to :class:`ForwardRef` proxy objects." -msgstr "" - -#: ../../library/annotationlib.rst:157 -msgid "" -"Values are the text string of the annotation as it appears in the source " -"code, up to modifications including, but not restricted to, whitespace " -"normalizations and constant values optimizations." -msgstr "" - -#: ../../library/annotationlib.rst:161 -msgid "" -"The exact values of these strings may change in future versions of Python." -msgstr "" - -#: ../../library/annotationlib.rst:167 -msgid "A proxy object for forward references in annotations." -msgstr "" - -#: ../../library/annotationlib.rst:169 -msgid "" -"Instances of this class are returned when the :attr:`~Format.FORWARDREF` " -"format is used and annotations contain a name that cannot be resolved. This " -"can happen when a forward reference is used in an annotation, such as when a " -"class is referenced before it is defined." -msgstr "" - -#: ../../library/annotationlib.rst:176 -msgid "" -"A string containing the code that was evaluated to produce the :class:" -"`~ForwardRef`. The string may not be exactly equivalent to the original " -"source." -msgstr "" - -#: ../../library/annotationlib.rst:182 -msgid "Evaluate the forward reference, returning its value." -msgstr "" - -#: ../../library/annotationlib.rst:184 -msgid "" -"If the *format* argument is :attr:`~Format.VALUE` (the default), this method " -"may throw an exception, such as :exc:`NameError`, if the forward reference " -"refers to a name that cannot be resolved. The arguments to this method can " -"be used to provide bindings for names that would otherwise be undefined. If " -"the *format* argument is :attr:`~Format.FORWARDREF`, the method will never " -"throw an exception, but may return a :class:`~ForwardRef` instance. For " -"example, if the forward reference object contains the code " -"``list[undefined]``, where ``undefined`` is a name that is not defined, " -"evaluating it with the :attr:`~Format.FORWARDREF` format will return " -"``list[ForwardRef('undefined')]``. If the *format* argument is :attr:" -"`~Format.STRING`, the method will return :attr:`~ForwardRef.__forward_arg__`." -msgstr "" - -#: ../../library/annotationlib.rst:196 -msgid "" -"The *owner* parameter provides the preferred mechanism for passing scope " -"information to this method. The owner of a :class:`~ForwardRef` is the " -"object that contains the annotation from which the :class:`~ForwardRef` " -"derives, such as a module object, type object, or function object." -msgstr "" - -#: ../../library/annotationlib.rst:201 -msgid "" -"The *globals*, *locals*, and *type_params* parameters provide a more precise " -"mechanism for influencing the names that are available when the :class:" -"`~ForwardRef` is evaluated. *globals* and *locals* are passed to :func:" -"`eval`, representing the global and local namespaces in which the name is " -"evaluated. The *type_params* parameter is relevant for objects created using " -"the native syntax for :ref:`generic classes ` and :ref:" -"`functions `. It is a tuple of :ref:`type parameters " -"` that are in scope while the forward reference is being " -"evaluated. For example, if evaluating a :class:`~ForwardRef` retrieved from " -"an annotation found in the class namespace of a generic class ``C``, " -"*type_params* should be set to ``C.__type_params__``." -msgstr "" - -#: ../../library/annotationlib.rst:212 -msgid "" -":class:`~ForwardRef` instances returned by :func:`get_annotations` retain " -"references to information about the scope they originated from, so calling " -"this method with no further arguments may be sufficient to evaluate such " -"objects. :class:`~ForwardRef` instances created by other means may not have " -"any information about their scope, so passing arguments to this method may " -"be necessary to evaluate them successfully." -msgstr "" - -#: ../../library/annotationlib.rst:219 -msgid "" -"If no *owner*, *globals*, *locals*, or *type_params* are provided and the :" -"class:`~ForwardRef` does not contain information about its origin, empty " -"globals and locals dictionaries are used." -msgstr "" - -#: ../../library/annotationlib.rst:227 -msgid "Functions" -msgstr "" - -#: ../../library/annotationlib.rst:231 -msgid "" -"Convert an annotations dict containing runtime values to a dict containing " -"only strings. If the values are not already strings, they are converted " -"using :func:`type_repr`. This is meant as a helper for user-provided " -"annotate functions that support the :attr:`~Format.STRING` format but do not " -"have access to the code creating the annotations." -msgstr "" - -#: ../../library/annotationlib.rst:238 -msgid "" -"For example, this is used to implement the :attr:`~Format.STRING` for :class:" -"`typing.TypedDict` classes created through the functional syntax:" -msgstr "" - -#: ../../library/annotationlib.rst:241 -msgid "" -">>> from typing import TypedDict\n" -">>> Movie = TypedDict(\"movie\", {\"name\": str, \"year\": int})\n" -">>> get_annotations(Movie, format=Format.STRING)\n" -"{'name': 'str', 'year': 'int'}" -msgstr "" -">>> from typing import TypedDict\n" -">>> Movie = TypedDict(\"movie\", {\"name\": str, \"year\": int})\n" -">>> get_annotations(Movie, format=Format.STRING)\n" -"{'name': 'str', 'year': 'int'}" - -#: ../../library/annotationlib.rst:252 -msgid "" -"Call the :term:`annotate function` *annotate* with the given *format*, a " -"member of the :class:`Format` enum, and return the annotations dictionary " -"produced by the function." -msgstr "" - -#: ../../library/annotationlib.rst:256 -msgid "" -"This helper function is required because annotate functions generated by the " -"compiler for functions, classes, and modules only support the :attr:`~Format." -"VALUE` format when called directly. To support other formats, this function " -"calls the annotate function in a special environment that allows it to " -"produce annotations in the other formats. This is a useful building block " -"when implementing functionality that needs to partially evaluate annotations " -"while a class is being constructed." -msgstr "" - -#: ../../library/annotationlib.rst:265 -msgid "" -"*owner* is the object that owns the annotation function, usually a function, " -"class, or module. If provided, it is used in the :attr:`~Format.FORWARDREF` " -"format to produce a :class:`ForwardRef` object that carries more information." -msgstr "" - -#: ../../library/annotationlib.rst:272 -msgid "" -":PEP:`PEP 649 <649#the-stringizer-and-the-fake-globals-environment>` " -"contains an explanation of the implementation technique used by this " -"function." -msgstr "" - -#: ../../library/annotationlib.rst:280 -msgid "" -"Call the :term:`evaluate function` *evaluate* with the given *format*, a " -"member of the :class:`Format` enum, and return the value produced by the " -"function. This is similar to :func:`call_annotate_function`, but the latter " -"always returns a dictionary mapping strings to annotations, while this " -"function returns a single value." -msgstr "" - -#: ../../library/annotationlib.rst:286 -msgid "" -"This is intended for use with the evaluate functions generated for lazily " -"evaluated elements related to type aliases and type parameters:" -msgstr "" - -#: ../../library/annotationlib.rst:289 -msgid ":meth:`typing.TypeAliasType.evaluate_value`, the value of type aliases" -msgstr "" - -#: ../../library/annotationlib.rst:290 -msgid ":meth:`typing.TypeVar.evaluate_bound`, the bound of type variables" -msgstr "" - -#: ../../library/annotationlib.rst:291 -msgid "" -":meth:`typing.TypeVar.evaluate_constraints`, the constraints of type " -"variables" -msgstr "" - -#: ../../library/annotationlib.rst:293 -msgid "" -":meth:`typing.TypeVar.evaluate_default`, the default value of type variables" -msgstr "" - -#: ../../library/annotationlib.rst:295 -msgid "" -":meth:`typing.ParamSpec.evaluate_default`, the default value of parameter " -"specifications" -msgstr "" - -#: ../../library/annotationlib.rst:297 -msgid "" -":meth:`typing.TypeVarTuple.evaluate_default`, the default value of type " -"variable tuples" -msgstr "" - -#: ../../library/annotationlib.rst:300 -msgid "" -"*owner* is the object that owns the evaluate function, such as the type " -"alias or type variable object." -msgstr "" - -#: ../../library/annotationlib.rst:303 -msgid "" -"*format* can be used to control the format in which the value is returned:" -msgstr "" - -#: ../../library/annotationlib.rst:305 -msgid "" -">>> type Alias = undefined\n" -">>> call_evaluate_function(Alias.evaluate_value, Format.VALUE)\n" -"Traceback (most recent call last):\n" -"...\n" -"NameError: name 'undefined' is not defined\n" -">>> call_evaluate_function(Alias.evaluate_value, Format.FORWARDREF)\n" -"ForwardRef('undefined')\n" -">>> call_evaluate_function(Alias.evaluate_value, Format.STRING)\n" -"'undefined'" -msgstr "" - -#: ../../library/annotationlib.rst:321 -msgid "" -"Retrieve the :term:`annotate function` from a class namespace dictionary " -"*namespace*. Return :const:`!None` if the namespace does not contain an " -"annotate function. This is primarily useful before the class has been fully " -"created (e.g., in a metaclass); after the class exists, the annotate " -"function can be retrieved with ``cls.__annotate__``. See :ref:`below " -"` for an example using this function in a metaclass." -msgstr "" - -#: ../../library/annotationlib.rst:331 -msgid "Compute the annotations dict for an object." -msgstr "" - -#: ../../library/annotationlib.rst:333 -msgid "" -"*obj* may be a callable, class, module, or other object with :attr:`~object." -"__annotate__` or :attr:`~object.__annotations__` attributes. Passing any " -"other object raises :exc:`TypeError`." -msgstr "" - -#: ../../library/annotationlib.rst:337 -msgid "" -"The *format* parameter controls the format in which annotations are " -"returned, and must be a member of the :class:`Format` enum or its integer " -"equivalent. The different formats work as follows:" -msgstr "" - -#: ../../library/annotationlib.rst:341 -msgid "" -"VALUE: :attr:`!object.__annotations__` is tried first; if that does not " -"exist, the :attr:`!object.__annotate__` function is called if it exists." -msgstr "" - -#: ../../library/annotationlib.rst:344 -msgid "" -"FORWARDREF: If :attr:`!object.__annotations__` exists and can be evaluated " -"successfully, it is used; otherwise, the :attr:`!object.__annotate__` " -"function is called. If it does not exist either, :attr:`!object." -"__annotations__` is tried again and any error from accessing it is re-raised." -msgstr "" - -#: ../../library/annotationlib.rst:349 -msgid "" -"When calling :attr:`!object.__annotate__` it is first called with :attr:" -"`~Format.FORWARDREF`. If this is not implemented, it will then check if :" -"attr:`~Format.VALUE_WITH_FAKE_GLOBALS` is supported and use that in the fake " -"globals environment. If neither of these formats are supported, it will fall " -"back to using :attr:`~Format.VALUE`. If :attr:`~Format.VALUE` fails, the " -"error from this call will be raised." -msgstr "" - -#: ../../library/annotationlib.rst:355 -msgid "" -"STRING: If :attr:`!object.__annotate__` exists, it is called first; " -"otherwise, :attr:`!object.__annotations__` is used and stringified using :" -"func:`annotations_to_string`." -msgstr "" - -#: ../../library/annotationlib.rst:359 -msgid "" -"When calling :attr:`!object.__annotate__` it is first called with :attr:" -"`~Format.STRING`. If this is not implemented, it will then check if :attr:" -"`~Format.VALUE_WITH_FAKE_GLOBALS` is supported and use that in the fake " -"globals environment. If neither of these formats are supported, it will fall " -"back to using :attr:`~Format.VALUE` with the result converted using :func:" -"`annotations_to_string`. If :attr:`~Format.VALUE` fails, the error from this " -"call will be raised." -msgstr "" - -#: ../../library/annotationlib.rst:366 -msgid "" -"Returns a dict. :func:`!get_annotations` returns a new dict every time it's " -"called; calling it twice on the same object will return two different but " -"equivalent dicts." -msgstr "" - -#: ../../library/annotationlib.rst:370 -msgid "This function handles several details for you:" -msgstr "" - -#: ../../library/annotationlib.rst:372 -msgid "" -"If *eval_str* is true, values of type :class:`!str` will be un-stringized " -"using :func:`eval`. This is intended for use with stringized annotations " -"(``from __future__ import annotations``). It is an error to set *eval_str* " -"to true with formats other than :attr:`Format.VALUE`." -msgstr "" - -#: ../../library/annotationlib.rst:377 -msgid "" -"If *obj* doesn't have an annotations dict, returns an empty dict. (Functions " -"and methods always have an annotations dict; classes, modules, and other " -"types of callables may not.)" -msgstr "" - -#: ../../library/annotationlib.rst:381 -msgid "" -"Ignores inherited annotations on classes, as well as annotations on " -"metaclasses. If a class doesn't have its own annotations dict, returns an " -"empty dict." -msgstr "" - -#: ../../library/annotationlib.rst:384 -msgid "" -"All accesses to object members and dict values are done using ``getattr()`` " -"and ``dict.get()`` for safety." -msgstr "" - -#: ../../library/annotationlib.rst:387 -msgid "" -"*eval_str* controls whether or not values of type :class:`!str` are replaced " -"with the result of calling :func:`eval` on those values:" -msgstr "" - -#: ../../library/annotationlib.rst:390 -msgid "" -"If eval_str is true, :func:`eval` is called on values of type :class:`!str`. " -"(Note that :func:`!get_annotations` doesn't catch exceptions; if :func:" -"`eval` raises an exception, it will unwind the stack past the :func:`!" -"get_annotations` call.)" -msgstr "" - -#: ../../library/annotationlib.rst:394 -msgid "" -"If *eval_str* is false (the default), values of type :class:`!str` are " -"unchanged." -msgstr "" - -#: ../../library/annotationlib.rst:397 -msgid "" -"*globals* and *locals* are passed in to :func:`eval`; see the documentation " -"for :func:`eval` for more information. If *globals* or *locals* is :const:`!" -"None`, this function may replace that value with a context-specific default, " -"contingent on ``type(obj)``:" -msgstr "" - -#: ../../library/annotationlib.rst:402 -msgid "If *obj* is a module, *globals* defaults to ``obj.__dict__``." -msgstr "如果 *obj* 是模組，則 *globals* 預設為 ``obj.__dict__``。" - -#: ../../library/annotationlib.rst:403 -msgid "" -"If *obj* is a class, *globals* defaults to ``sys.modules[obj.__module__]." -"__dict__`` and *locals* defaults to the *obj* class namespace." -msgstr "" - -#: ../../library/annotationlib.rst:406 -msgid "" -"If *obj* is a callable, *globals* defaults to :attr:`obj.__globals__ " -"`, although if *obj* is a wrapped function (using :" -"func:`functools.update_wrapper`) or a :class:`functools.partial` object, it " -"is unwrapped until a non-wrapped function is found." -msgstr "" - -#: ../../library/annotationlib.rst:412 -msgid "" -"Calling :func:`!get_annotations` is best practice for accessing the " -"annotations dict of any object. See :ref:`annotations-howto` for more " -"information on annotations best practices." -msgstr "" - -#: ../../library/annotationlib.rst:416 -msgid "" -">>> def f(a: int, b: str) -> float:\n" -"... pass\n" -">>> get_annotations(f)\n" -"{'a': , 'b': , 'return': }" -msgstr "" -">>> def f(a: int, b: str) -> float:\n" -"... pass\n" -">>> get_annotations(f)\n" -"{'a': , 'b': , 'return': }" - -#: ../../library/annotationlib.rst:427 -msgid "" -"Convert an arbitrary Python value to a format suitable for use by the :attr:" -"`~Format.STRING` format. This calls :func:`repr` for most objects, but has " -"special handling for some objects, such as type objects." -msgstr "" - -#: ../../library/annotationlib.rst:431 -msgid "" -"This is meant as a helper for user-provided annotate functions that support " -"the :attr:`~Format.STRING` format but do not have access to the code " -"creating the annotations. It can also be used to provide a user-friendly " -"string representation for other objects that contain values that are " -"commonly encountered in annotations." -msgstr "" - -#: ../../library/annotationlib.rst:441 -msgid "Recipes" -msgstr "" - -#: ../../library/annotationlib.rst:446 -msgid "Using annotations in a metaclass" -msgstr "" - -#: ../../library/annotationlib.rst:448 -msgid "" -"A :ref:`metaclass ` may want to inspect or even modify the " -"annotations in a class body during class creation. Doing so requires " -"retrieving annotations from the class namespace dictionary. For classes " -"created with ``from __future__ import annotations``, the annotations will be " -"in the ``__annotations__`` key of the dictionary. For other classes with " -"annotations, :func:`get_annotate_from_class_namespace` can be used to get " -"the annotate function, and :func:`call_annotate_function` can be used to " -"call it and retrieve the annotations. Using the :attr:`~Format.FORWARDREF` " -"format will usually be best, because this allows the annotations to refer to " -"names that cannot yet be resolved when the class is created." -msgstr "" - -#: ../../library/annotationlib.rst:459 -msgid "" -"To modify the annotations, it is best to create a wrapper annotate function " -"that calls the original annotate function, makes any necessary adjustments, " -"and returns the result." -msgstr "" - -#: ../../library/annotationlib.rst:463 -msgid "" -"Below is an example of a metaclass that filters out all :class:`typing." -"ClassVar` annotations from the class and puts them in a separate attribute:" -msgstr "" - -#: ../../library/annotationlib.rst:466 -msgid "" -"import annotationlib\n" -"import typing\n" -"\n" -"class ClassVarSeparator(type):\n" -" def __new__(mcls, name, bases, ns):\n" -" if \"__annotations__\" in ns: # from __future__ import annotations\n" -" annotations = ns[\"__annotations__\"]\n" -" classvar_keys = {\n" -" key for key, value in annotations.items()\n" -" # Use string comparison for simplicity; a more robust solution\n" -" # could use annotationlib.ForwardRef.evaluate\n" -" if value.startswith(\"ClassVar\")\n" -" }\n" -" classvars = {key: annotations[key] for key in classvar_keys}\n" -" ns[\"__annotations__\"] = {\n" -" key: value for key, value in annotations.items()\n" -" if key not in classvar_keys\n" -" }\n" -" wrapped_annotate = None\n" -" elif annotate := annotationlib.get_annotate_from_class_namespace(ns):\n" -" annotations = annotationlib.call_annotate_function(\n" -" annotate, format=annotationlib.Format.FORWARDREF\n" -" )\n" -" classvar_keys = {\n" -" key for key, value in annotations.items()\n" -" if typing.get_origin(value) is typing.ClassVar\n" -" }\n" -" classvars = {key: annotations[key] for key in classvar_keys}\n" -"\n" -" def wrapped_annotate(format):\n" -" annos = annotationlib.call_annotate_function(annotate, format, " -"owner=typ)\n" -" return {key: value for key, value in annos.items() if key not in " -"classvar_keys}\n" -"\n" -" else: # no annotations\n" -" classvars = {}\n" -" wrapped_annotate = None\n" -" typ = super().__new__(mcls, name, bases, ns)\n" -"\n" -" if wrapped_annotate is not None:\n" -" # Wrap the original __annotate__ with a wrapper that removes " -"ClassVars\n" -" typ.__annotate__ = wrapped_annotate\n" -" typ.classvars = classvars # Store the ClassVars in a separate " -"attribute\n" -" return typ" -msgstr "" - -#: ../../library/annotationlib.rst:514 -msgid "Limitations of the ``STRING`` format" -msgstr "``STRING`` 格式的限制" - -#: ../../library/annotationlib.rst:516 -msgid "" -"The :attr:`~Format.STRING` format is meant to approximate the source code of " -"the annotation, but the implementation strategy used means that it is not " -"always possible to recover the exact source code." -msgstr "" - -#: ../../library/annotationlib.rst:520 -msgid "" -"First, the stringifier of course cannot recover any information that is not " -"present in the compiled code, including comments, whitespace, " -"parenthesization, and operations that get simplified by the compiler." -msgstr "" - -#: ../../library/annotationlib.rst:524 -msgid "" -"Second, the stringifier can intercept almost all operations that involve " -"names looked up in some scope, but it cannot intercept operations that " -"operate fully on constants. As a corollary, this also means it is not safe " -"to request the ``STRING`` format on untrusted code: Python is powerful " -"enough that it is possible to achieve arbitrary code execution even with no " -"access to any globals or builtins. For example:" -msgstr "" - -#: ../../library/annotationlib.rst:530 -msgid "" -">>> def f(x: (1).__class__.__base__.__subclasses__()[-1].__init__." -"__builtins__[\"print\"](\"Hello world\")): pass\n" -"...\n" -">>> annotationlib.get_annotations(f, format=annotationlib.Format.STRING)\n" -"Hello world\n" -"{'x': 'None'}" -msgstr "" -">>> def f(x: (1).__class__.__base__.__subclasses__()[-1].__init__." -"__builtins__[\"print\"](\"Hello world\")): pass\n" -"...\n" -">>> annotationlib.get_annotations(f, format=annotationlib.Format.STRING)\n" -"Hello world\n" -"{'x': 'None'}" - -#: ../../library/annotationlib.rst:539 -msgid "" -"This particular example works as of the time of writing, but it relies on " -"implementation details and is not guaranteed to work in the future." -msgstr "" - -#: ../../library/annotationlib.rst:542 -msgid "" -"Among the different kinds of expressions that exist in Python, as " -"represented by the :mod:`ast` module, some expressions are supported, " -"meaning that the ``STRING`` format can generally recover the original source " -"code; others are unsupported, meaning that they may result in incorrect " -"output or an error." -msgstr "" - -#: ../../library/annotationlib.rst:547 -msgid "The following are supported (sometimes with caveats):" -msgstr "" - -#: ../../library/annotationlib.rst:549 -msgid ":class:`ast.BinOp`" -msgstr ":class:`ast.BinOp`" - -#: ../../library/annotationlib.rst:550 -msgid ":class:`ast.UnaryOp`" -msgstr ":class:`ast.UnaryOp`" - -#: ../../library/annotationlib.rst:552 -msgid "" -":class:`ast.Invert` (``~``), :class:`ast.UAdd` (``+``), and :class:`ast." -"USub` (``-``) are supported" -msgstr "" -":class:`ast.Invert` (``~``)、:class:`ast.UAdd` (``+``) 和 :class:`ast.USub` (``-``) 有被支援" - -#: ../../library/annotationlib.rst:553 -msgid ":class:`ast.Not` (``not``) is not supported" -msgstr ":class:`ast.Not` (``not``) 並不被支援" - -#: ../../library/annotationlib.rst:555 -msgid ":class:`ast.Dict` (except when using ``**`` unpacking)" -msgstr ":class:`ast.Dict`\\ （除了使用 ``**`` 解包的情況）" - -#: ../../library/annotationlib.rst:556 -msgid ":class:`ast.Set`" -msgstr ":class:`ast.Set`" - -#: ../../library/annotationlib.rst:557 -msgid ":class:`ast.Compare`" -msgstr ":class:`ast.Compare`" - -#: ../../library/annotationlib.rst:559 -msgid ":class:`ast.Eq` and :class:`ast.NotEq` are supported" -msgstr ":class:`ast.Eq` 和 :class:`ast.NotEq` 有被支援" - -#: ../../library/annotationlib.rst:560 -msgid "" -":class:`ast.Lt`, :class:`ast.LtE`, :class:`ast.Gt`, and :class:`ast.GtE` are " -"supported, but the operand may be flipped" -msgstr "" - -#: ../../library/annotationlib.rst:561 -msgid "" -":class:`ast.Is`, :class:`ast.IsNot`, :class:`ast.In`, and :class:`ast.NotIn` " -"are not supported" -msgstr "" - -#: ../../library/annotationlib.rst:563 -msgid ":class:`ast.Call` (except when using ``**`` unpacking)" -msgstr "" - -#: ../../library/annotationlib.rst:564 -msgid "" -":class:`ast.Constant` (though not the exact representation of the constant; " -"for example, escape sequences in strings are lost; hexadecimal numbers are " -"converted to decimal)" -msgstr "" - -#: ../../library/annotationlib.rst:566 -msgid ":class:`ast.Attribute` (assuming the value is not a constant)" -msgstr "" - -#: ../../library/annotationlib.rst:567 -msgid ":class:`ast.Subscript` (assuming the value is not a constant)" -msgstr "" - -#: ../../library/annotationlib.rst:568 -msgid ":class:`ast.Starred` (``*`` unpacking)" -msgstr "" - -#: ../../library/annotationlib.rst:569 -msgid ":class:`ast.Name`" -msgstr ":class:`ast.Name`" - -#: ../../library/annotationlib.rst:570 -msgid ":class:`ast.List`" -msgstr ":class:`ast.List`" - -#: ../../library/annotationlib.rst:571 -msgid ":class:`ast.Tuple`" -msgstr ":class:`ast.Tuple`" - -#: ../../library/annotationlib.rst:572 -msgid ":class:`ast.Slice`" -msgstr ":class:`ast.Slice`" - -#: ../../library/annotationlib.rst:574 -msgid "" -"The following are unsupported, but throw an informative error when " -"encountered by the stringifier:" -msgstr "" - -#: ../../library/annotationlib.rst:577 -msgid "" -":class:`ast.FormattedValue` (f-strings; error is not detected if conversion " -"specifiers like ``!r`` are used)" -msgstr "" - -#: ../../library/annotationlib.rst:579 -msgid ":class:`ast.JoinedStr` (f-strings)" -msgstr ":class:`ast.JoinedStr`\\ （f 字串）" - -#: ../../library/annotationlib.rst:581 -msgid "The following are unsupported and result in incorrect output:" -msgstr "以下是不支援的，並且會導致不正確的輸出：" - -#: ../../library/annotationlib.rst:583 -msgid ":class:`ast.BoolOp` (``and`` and ``or``)" -msgstr ":class:`ast.BoolOp`\\ （``and`` 和 ``or``）" - -#: ../../library/annotationlib.rst:584 -msgid ":class:`ast.IfExp`" -msgstr ":class:`ast.IfExp`" - -#: ../../library/annotationlib.rst:585 -msgid ":class:`ast.Lambda`" -msgstr ":class:`ast.Lambda`" - -#: ../../library/annotationlib.rst:586 -msgid ":class:`ast.ListComp`" -msgstr ":class:`ast.ListComp`" - -#: ../../library/annotationlib.rst:587 -msgid ":class:`ast.SetComp`" -msgstr ":class:`ast.SetComp`" - -#: ../../library/annotationlib.rst:588 -msgid ":class:`ast.DictComp`" -msgstr ":class:`ast.DictComp`" - -#: ../../library/annotationlib.rst:589 -msgid ":class:`ast.GeneratorExp`" -msgstr ":class:`ast.GeneratorExp`" - -#: ../../library/annotationlib.rst:591 -msgid "" -"The following are disallowed in annotation scopes and therefore not relevant:" -msgstr "" - -#: ../../library/annotationlib.rst:593 -msgid ":class:`ast.NamedExpr` (``:=``)" -msgstr ":class:`ast.NamedExpr` (``:=``)" - -#: ../../library/annotationlib.rst:594 -msgid ":class:`ast.Await`" -msgstr ":class:`ast.Await`" - -#: ../../library/annotationlib.rst:595 -msgid ":class:`ast.Yield`" -msgstr ":class:`ast.Yield`" - -#: ../../library/annotationlib.rst:596 -msgid ":class:`ast.YieldFrom`" -msgstr ":class:`ast.YieldFrom`" - -#: ../../library/annotationlib.rst:600 -msgid "Limitations of the ``FORWARDREF`` format" -msgstr "``FORWARDREF`` 格式的限制" - -#: ../../library/annotationlib.rst:602 -msgid "" -"The :attr:`~Format.FORWARDREF` format aims to produce real values as much as " -"possible, with anything that cannot be resolved replaced with :class:" -"`ForwardRef` objects. It is affected by broadly the same Limitations as the :" -"attr:`~Format.STRING` format: annotations that perform operations on " -"literals or that use unsupported expression types may raise exceptions when " -"evaluated using the :attr:`~Format.FORWARDREF` format." -msgstr "" - -#: ../../library/annotationlib.rst:609 -msgid "Below are a few examples of the behavior with unsupported expressions:" -msgstr "" - -#: ../../library/annotationlib.rst:611 -msgid "" -">>> from annotationlib import get_annotations, Format\n" -">>> def zerodiv(x: 1 / 0): ...\n" -">>> get_annotations(zerodiv, format=Format.STRING)\n" -"Traceback (most recent call last):\n" -" ...\n" -"ZeroDivisionError: division by zero\n" -">>> get_annotations(zerodiv, format=Format.FORWARDREF)\n" -"Traceback (most recent call last):\n" -" ...\n" -"ZeroDivisionError: division by zero\n" -">>> def ifexp(x: 1 if y else 0): ...\n" -">>> get_annotations(ifexp, format=Format.STRING)\n" -"{'x': '1'}" -msgstr "" -">>> from annotationlib import get_annotations, Format\n" -">>> def zerodiv(x: 1 / 0): ...\n" -">>> get_annotations(zerodiv, format=Format.STRING)\n" -"Traceback (most recent call last):\n" -" ...\n" -"ZeroDivisionError: division by zero\n" -">>> get_annotations(zerodiv, format=Format.FORWARDREF)\n" -"Traceback (most recent call last):\n" -" ...\n" -"ZeroDivisionError: division by zero\n" -">>> def ifexp(x: 1 if y else 0): ...\n" -">>> get_annotations(ifexp, format=Format.STRING)\n" -"{'x': '1'}" - -#: ../../library/annotationlib.rst:630 -msgid "Security implications of introspecting annotations" -msgstr "" - -#: ../../library/annotationlib.rst:632 -msgid "" -"Much of the functionality in this module involves executing code related to " -"annotations, which can then do arbitrary things. For example, :func:" -"`get_annotations` may call an arbitrary :term:`annotate function`, and :meth:" -"`ForwardRef.evaluate` may call :func:`eval` on an arbitrary string. Code " -"contained in an annotation might make arbitrary system calls, enter an " -"infinite loop, or perform any other operation. This is also true for any " -"access of the :attr:`~object.__annotations__` attribute, and for various " -"functions in the :mod:`typing` module that work with annotations, such as :" -"func:`typing.get_type_hints`." -msgstr "" - -#: ../../library/annotationlib.rst:641 -msgid "" -"Any security issue arising from this also applies immediately after " -"importing code that may contain untrusted annotations: importing code can " -"always cause arbitrary operations to be performed. However, it is unsafe to " -"accept strings or other input from an untrusted source and pass them to any " -"of the APIs for introspecting annotations, for example by editing an " -"``__annotations__`` dictionary or directly creating a :class:`ForwardRef` " -"object." -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-10-22 00:14+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"Language: zh_TW\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../library/annotationlib.rst:2 +msgid ":mod:`!annotationlib` --- Functionality for introspecting annotations" +msgstr ":mod:`!annotationlib` --- 用於自我檢查註釋的功能" + +#: ../../library/annotationlib.rst:9 +msgid "**Source code:** :source:`Lib/annotationlib.py`" +msgstr "**原始碼：** :source:`Lib/annotationlib.py`" + +#: ../../library/annotationlib.rst:18 +msgid "" +"The :mod:`!annotationlib` module provides tools for introspecting :term:" +"`annotations ` on modules, classes, and functions." +msgstr "" + +#: ../../library/annotationlib.rst:21 +msgid "" +"Annotations are :ref:`lazily evaluated ` and often contain " +"forward references to objects that are not yet defined when the annotation " +"is created. This module provides a set of low-level tools that can be used " +"to retrieve annotations in a reliable way, even in the presence of forward " +"references and other edge cases." +msgstr "" + +#: ../../library/annotationlib.rst:26 +msgid "" +"This module supports retrieving annotations in three main formats (see :" +"class:`Format`), each of which works best for different use cases:" +msgstr "" + +#: ../../library/annotationlib.rst:29 +msgid "" +":attr:`~Format.VALUE` evaluates the annotations and returns their value. " +"This is most straightforward to work with, but it may raise errors, for " +"example if the annotations contain references to undefined names." +msgstr "" + +#: ../../library/annotationlib.rst:32 +msgid "" +":attr:`~Format.FORWARDREF` returns :class:`ForwardRef` objects for " +"annotations that cannot be resolved, allowing you to inspect the annotations " +"without evaluating them. This is useful when you need to work with " +"annotations that may contain unresolved forward references." +msgstr "" + +#: ../../library/annotationlib.rst:36 +msgid "" +":attr:`~Format.STRING` returns the annotations as a string, similar to how " +"it would appear in the source file. This is useful for documentation " +"generators that want to display annotations in a readable way." +msgstr "" + +#: ../../library/annotationlib.rst:40 +msgid "" +"The :func:`get_annotations` function is the main entry point for retrieving " +"annotations. Given a function, class, or module, it returns an annotations " +"dictionary in the requested format. This module also provides functionality " +"for working directly with the :term:`annotate function` that is used to " +"evaluate annotations, such as :func:`get_annotate_from_class_namespace` and :" +"func:`call_annotate_function`, as well as the :func:`call_evaluate_function` " +"function for working with :term:`evaluate functions `." +msgstr "" + +#: ../../library/annotationlib.rst:51 +msgid "" +"Most functionality in this module can execute arbitrary code; see :ref:`the " +"security section ` for more information." +msgstr "" + +#: ../../library/annotationlib.rst:56 +msgid "" +":pep:`649` proposed the current model for how annotations work in Python." +msgstr "" + +#: ../../library/annotationlib.rst:58 +msgid "" +":pep:`749` expanded on various aspects of :pep:`649` and introduced the :mod:" +"`!annotationlib` module." +msgstr "" + +#: ../../library/annotationlib.rst:61 +msgid "" +":ref:`annotations-howto` provides best practices for working with " +"annotations." +msgstr "" + +#: ../../library/annotationlib.rst:64 +msgid "" +":pypi:`typing-extensions` provides a backport of :func:`get_annotations` " +"that works on earlier versions of Python." +msgstr "" + +#: ../../library/annotationlib.rst:68 +msgid "Annotation semantics" +msgstr "" + +#: ../../library/annotationlib.rst:70 +msgid "" +"The way annotations are evaluated has changed over the history of Python 3, " +"and currently still depends on a :ref:`future import `. There have " +"been execution models for annotations:" +msgstr "" + +#: ../../library/annotationlib.rst:74 +msgid "" +"*Stock semantics* (default in Python 3.0 through 3.13; see :pep:`3107` and :" +"pep:`526`): Annotations are evaluated eagerly, as they are encountered in " +"the source code." +msgstr "" + +#: ../../library/annotationlib.rst:77 +msgid "" +"*Stringified annotations* (used with ``from __future__ import annotations`` " +"in Python 3.7 and newer; see :pep:`563`): Annotations are stored as strings " +"only." +msgstr "" + +#: ../../library/annotationlib.rst:80 +msgid "" +"*Deferred evaluation* (default in Python 3.14 and newer; see :pep:`649` and :" +"pep:`749`): Annotations are evaluated lazily, only when they are accessed." +msgstr "" + +#: ../../library/annotationlib.rst:83 +msgid "As an example, consider the following program::" +msgstr "" + +#: ../../library/annotationlib.rst:85 +msgid "" +"def func(a: Cls) -> None:\n" +" print(a)\n" +"\n" +"class Cls: pass\n" +"\n" +"print(func.__annotations__)" +msgstr "" +"def func(a: Cls) -> None:\n" +" print(a)\n" +"\n" +"class Cls: pass\n" +"\n" +"print(func.__annotations__)" + +#: ../../library/annotationlib.rst:92 +msgid "This will behave as follows:" +msgstr "這會有以下行為：" + +#: ../../library/annotationlib.rst:94 +msgid "" +"Under stock semantics (Python 3.13 and earlier), it will throw a :exc:" +"`NameError` at the line where ``func`` is defined, because ``Cls`` is an " +"undefined name at that point." +msgstr "" + +#: ../../library/annotationlib.rst:97 +msgid "" +"Under stringified annotations (if ``from __future__ import annotations`` is " +"used), it will print ``{'a': 'Cls', 'return': 'None'}``." +msgstr "" + +#: ../../library/annotationlib.rst:99 +msgid "" +"Under deferred evaluation (Python 3.14 and later), it will print ``{'a': " +", 'return': None}``." +msgstr "" + +#: ../../library/annotationlib.rst:102 +msgid "" +"Stock semantics were used when function annotations were first introduced in " +"Python 3.0 (by :pep:`3107`) because this was the simplest, most obvious way " +"to implement annotations. The same execution model was used when variable " +"annotations were introduced in Python 3.6 (by :pep:`526`). However, stock " +"semantics caused problems when using annotations as type hints, such as a " +"need to refer to names that are not yet defined when the annotation is " +"encountered. In addition, there were performance problems with executing " +"annotations at module import time. Therefore, in Python 3.7, :pep:`563` " +"introduced the ability to store annotations as strings using the ``from " +"__future__ import annotations`` syntax. The plan at the time was to " +"eventually make this behavior the default, but a problem appeared: " +"stringified annotations are more difficult to process for those who " +"introspect annotations at runtime. An alternative proposal, :pep:`649`, " +"introduced the third execution model, deferred evaluation, and was " +"implemented in Python 3.14. Stringified annotations are still used if ``from " +"__future__ import annotations`` is present, but this behavior will " +"eventually be removed." +msgstr "" + +#: ../../library/annotationlib.rst:121 +msgid "Classes" +msgstr "" + +#: ../../library/annotationlib.rst:125 +msgid "" +"An :class:`~enum.IntEnum` describing the formats in which annotations can be " +"returned. Members of the enum, or their equivalent integer values, can be " +"passed to :func:`get_annotations` and other functions in this module, as " +"well as to :attr:`~object.__annotate__` functions." +msgstr "" + +#: ../../library/annotationlib.rst:133 +msgid "Values are the result of evaluating the annotation expressions." +msgstr "" + +#: ../../library/annotationlib.rst:138 +msgid "" +"Special value used to signal that an annotate function is being evaluated in " +"a special environment with fake globals. When passed this value, annotate " +"functions should either return the same value as for the :attr:`Format." +"VALUE` format, or raise :exc:`NotImplementedError` to signal that they do " +"not support execution in this environment. This format is only used " +"internally and should not be passed to the functions in this module." +msgstr "" + +#: ../../library/annotationlib.rst:149 +msgid "" +"Values are real annotation values (as per :attr:`Format.VALUE` format) for " +"defined values, and :class:`ForwardRef` proxies for undefined values. Real " +"objects may contain references to :class:`ForwardRef` proxy objects." +msgstr "" + +#: ../../library/annotationlib.rst:157 +msgid "" +"Values are the text string of the annotation as it appears in the source " +"code, up to modifications including, but not restricted to, whitespace " +"normalizations and constant values optimizations." +msgstr "" + +#: ../../library/annotationlib.rst:161 +msgid "" +"The exact values of these strings may change in future versions of Python." +msgstr "" + +#: ../../library/annotationlib.rst:167 +msgid "A proxy object for forward references in annotations." +msgstr "" + +#: ../../library/annotationlib.rst:169 +msgid "" +"Instances of this class are returned when the :attr:`~Format.FORWARDREF` " +"format is used and annotations contain a name that cannot be resolved. This " +"can happen when a forward reference is used in an annotation, such as when a " +"class is referenced before it is defined." +msgstr "" + +#: ../../library/annotationlib.rst:176 +msgid "" +"A string containing the code that was evaluated to produce the :class:" +"`~ForwardRef`. The string may not be exactly equivalent to the original " +"source." +msgstr "" + +#: ../../library/annotationlib.rst:182 +msgid "Evaluate the forward reference, returning its value." +msgstr "" + +#: ../../library/annotationlib.rst:184 +msgid "" +"If the *format* argument is :attr:`~Format.VALUE` (the default), this method " +"may throw an exception, such as :exc:`NameError`, if the forward reference " +"refers to a name that cannot be resolved. The arguments to this method can " +"be used to provide bindings for names that would otherwise be undefined. If " +"the *format* argument is :attr:`~Format.FORWARDREF`, the method will never " +"throw an exception, but may return a :class:`~ForwardRef` instance. For " +"example, if the forward reference object contains the code " +"``list[undefined]``, where ``undefined`` is a name that is not defined, " +"evaluating it with the :attr:`~Format.FORWARDREF` format will return " +"``list[ForwardRef('undefined')]``. If the *format* argument is :attr:" +"`~Format.STRING`, the method will return :attr:`~ForwardRef.__forward_arg__`." +msgstr "" + +#: ../../library/annotationlib.rst:196 +msgid "" +"The *owner* parameter provides the preferred mechanism for passing scope " +"information to this method. The owner of a :class:`~ForwardRef` is the " +"object that contains the annotation from which the :class:`~ForwardRef` " +"derives, such as a module object, type object, or function object." +msgstr "" + +#: ../../library/annotationlib.rst:201 +msgid "" +"The *globals*, *locals*, and *type_params* parameters provide a more precise " +"mechanism for influencing the names that are available when the :class:" +"`~ForwardRef` is evaluated. *globals* and *locals* are passed to :func:" +"`eval`, representing the global and local namespaces in which the name is " +"evaluated. The *type_params* parameter is relevant for objects created using " +"the native syntax for :ref:`generic classes ` and :ref:" +"`functions `. It is a tuple of :ref:`type parameters " +"` that are in scope while the forward reference is being " +"evaluated. For example, if evaluating a :class:`~ForwardRef` retrieved from " +"an annotation found in the class namespace of a generic class ``C``, " +"*type_params* should be set to ``C.__type_params__``." +msgstr "" + +#: ../../library/annotationlib.rst:212 +msgid "" +":class:`~ForwardRef` instances returned by :func:`get_annotations` retain " +"references to information about the scope they originated from, so calling " +"this method with no further arguments may be sufficient to evaluate such " +"objects. :class:`~ForwardRef` instances created by other means may not have " +"any information about their scope, so passing arguments to this method may " +"be necessary to evaluate them successfully." +msgstr "" + +#: ../../library/annotationlib.rst:219 +msgid "" +"If no *owner*, *globals*, *locals*, or *type_params* are provided and the :" +"class:`~ForwardRef` does not contain information about its origin, empty " +"globals and locals dictionaries are used." +msgstr "" + +#: ../../library/annotationlib.rst:227 +msgid "Functions" +msgstr "" + +#: ../../library/annotationlib.rst:231 +msgid "" +"Convert an annotations dict containing runtime values to a dict containing " +"only strings. If the values are not already strings, they are converted " +"using :func:`type_repr`. This is meant as a helper for user-provided " +"annotate functions that support the :attr:`~Format.STRING` format but do not " +"have access to the code creating the annotations." +msgstr "" + +#: ../../library/annotationlib.rst:238 +msgid "" +"For example, this is used to implement the :attr:`~Format.STRING` for :class:" +"`typing.TypedDict` classes created through the functional syntax:" +msgstr "" + +#: ../../library/annotationlib.rst:241 +msgid "" +">>> from typing import TypedDict\n" +">>> Movie = TypedDict(\"movie\", {\"name\": str, \"year\": int})\n" +">>> get_annotations(Movie, format=Format.STRING)\n" +"{'name': 'str', 'year': 'int'}" +msgstr "" +">>> from typing import TypedDict\n" +">>> Movie = TypedDict(\"movie\", {\"name\": str, \"year\": int})\n" +">>> get_annotations(Movie, format=Format.STRING)\n" +"{'name': 'str', 'year': 'int'}" + +#: ../../library/annotationlib.rst:252 +msgid "" +"Call the :term:`annotate function` *annotate* with the given *format*, a " +"member of the :class:`Format` enum, and return the annotations dictionary " +"produced by the function." +msgstr "" + +#: ../../library/annotationlib.rst:256 +msgid "" +"This helper function is required because annotate functions generated by the " +"compiler for functions, classes, and modules only support the :attr:`~Format." +"VALUE` format when called directly. To support other formats, this function " +"calls the annotate function in a special environment that allows it to " +"produce annotations in the other formats. This is a useful building block " +"when implementing functionality that needs to partially evaluate annotations " +"while a class is being constructed." +msgstr "" + +#: ../../library/annotationlib.rst:265 +msgid "" +"*owner* is the object that owns the annotation function, usually a function, " +"class, or module. If provided, it is used in the :attr:`~Format.FORWARDREF` " +"format to produce a :class:`ForwardRef` object that carries more information." +msgstr "" + +#: ../../library/annotationlib.rst:272 +msgid "" +":PEP:`PEP 649 <649#the-stringizer-and-the-fake-globals-environment>` " +"contains an explanation of the implementation technique used by this " +"function." +msgstr "" + +#: ../../library/annotationlib.rst:280 +msgid "" +"Call the :term:`evaluate function` *evaluate* with the given *format*, a " +"member of the :class:`Format` enum, and return the value produced by the " +"function. This is similar to :func:`call_annotate_function`, but the latter " +"always returns a dictionary mapping strings to annotations, while this " +"function returns a single value." +msgstr "" + +#: ../../library/annotationlib.rst:286 +msgid "" +"This is intended for use with the evaluate functions generated for lazily " +"evaluated elements related to type aliases and type parameters:" +msgstr "" + +#: ../../library/annotationlib.rst:289 +msgid ":meth:`typing.TypeAliasType.evaluate_value`, the value of type aliases" +msgstr "" + +#: ../../library/annotationlib.rst:290 +msgid ":meth:`typing.TypeVar.evaluate_bound`, the bound of type variables" +msgstr "" + +#: ../../library/annotationlib.rst:291 +msgid "" +":meth:`typing.TypeVar.evaluate_constraints`, the constraints of type " +"variables" +msgstr "" + +#: ../../library/annotationlib.rst:293 +msgid "" +":meth:`typing.TypeVar.evaluate_default`, the default value of type variables" +msgstr "" + +#: ../../library/annotationlib.rst:295 +msgid "" +":meth:`typing.ParamSpec.evaluate_default`, the default value of parameter " +"specifications" +msgstr "" + +#: ../../library/annotationlib.rst:297 +msgid "" +":meth:`typing.TypeVarTuple.evaluate_default`, the default value of type " +"variable tuples" +msgstr "" + +#: ../../library/annotationlib.rst:300 +msgid "" +"*owner* is the object that owns the evaluate function, such as the type " +"alias or type variable object." +msgstr "" + +#: ../../library/annotationlib.rst:303 +msgid "" +"*format* can be used to control the format in which the value is returned:" +msgstr "" + +#: ../../library/annotationlib.rst:305 +msgid "" +">>> type Alias = undefined\n" +">>> call_evaluate_function(Alias.evaluate_value, Format.VALUE)\n" +"Traceback (most recent call last):\n" +"...\n" +"NameError: name 'undefined' is not defined\n" +">>> call_evaluate_function(Alias.evaluate_value, Format.FORWARDREF)\n" +"ForwardRef('undefined')\n" +">>> call_evaluate_function(Alias.evaluate_value, Format.STRING)\n" +"'undefined'" +msgstr "" + +#: ../../library/annotationlib.rst:321 +msgid "" +"Retrieve the :term:`annotate function` from a class namespace dictionary " +"*namespace*. Return :const:`!None` if the namespace does not contain an " +"annotate function. This is primarily useful before the class has been fully " +"created (e.g., in a metaclass); after the class exists, the annotate " +"function can be retrieved with ``cls.__annotate__``. See :ref:`below " +"` for an example using this function in a metaclass." +msgstr "" + +#: ../../library/annotationlib.rst:331 +msgid "Compute the annotations dict for an object." +msgstr "" + +#: ../../library/annotationlib.rst:333 +msgid "" +"*obj* may be a callable, class, module, or other object with :attr:`~object." +"__annotate__` or :attr:`~object.__annotations__` attributes. Passing any " +"other object raises :exc:`TypeError`." +msgstr "" + +#: ../../library/annotationlib.rst:337 +msgid "" +"The *format* parameter controls the format in which annotations are " +"returned, and must be a member of the :class:`Format` enum or its integer " +"equivalent. The different formats work as follows:" +msgstr "" + +#: ../../library/annotationlib.rst:341 +msgid "" +"VALUE: :attr:`!object.__annotations__` is tried first; if that does not " +"exist, the :attr:`!object.__annotate__` function is called if it exists." +msgstr "" + +#: ../../library/annotationlib.rst:344 +msgid "" +"FORWARDREF: If :attr:`!object.__annotations__` exists and can be evaluated " +"successfully, it is used; otherwise, the :attr:`!object.__annotate__` " +"function is called. If it does not exist either, :attr:`!object." +"__annotations__` is tried again and any error from accessing it is re-raised." +msgstr "" + +#: ../../library/annotationlib.rst:349 +msgid "" +"When calling :attr:`!object.__annotate__` it is first called with :attr:" +"`~Format.FORWARDREF`. If this is not implemented, it will then check if :" +"attr:`~Format.VALUE_WITH_FAKE_GLOBALS` is supported and use that in the fake " +"globals environment. If neither of these formats are supported, it will fall " +"back to using :attr:`~Format.VALUE`. If :attr:`~Format.VALUE` fails, the " +"error from this call will be raised." +msgstr "" + +#: ../../library/annotationlib.rst:355 +msgid "" +"STRING: If :attr:`!object.__annotate__` exists, it is called first; " +"otherwise, :attr:`!object.__annotations__` is used and stringified using :" +"func:`annotations_to_string`." +msgstr "" + +#: ../../library/annotationlib.rst:359 +msgid "" +"When calling :attr:`!object.__annotate__` it is first called with :attr:" +"`~Format.STRING`. If this is not implemented, it will then check if :attr:" +"`~Format.VALUE_WITH_FAKE_GLOBALS` is supported and use that in the fake " +"globals environment. If neither of these formats are supported, it will fall " +"back to using :attr:`~Format.VALUE` with the result converted using :func:" +"`annotations_to_string`. If :attr:`~Format.VALUE` fails, the error from this " +"call will be raised." +msgstr "" + +#: ../../library/annotationlib.rst:366 +msgid "" +"Returns a dict. :func:`!get_annotations` returns a new dict every time it's " +"called; calling it twice on the same object will return two different but " +"equivalent dicts." +msgstr "" + +#: ../../library/annotationlib.rst:370 +msgid "This function handles several details for you:" +msgstr "" + +#: ../../library/annotationlib.rst:372 +msgid "" +"If *eval_str* is true, values of type :class:`!str` will be un-stringized " +"using :func:`eval`. This is intended for use with stringized annotations " +"(``from __future__ import annotations``). It is an error to set *eval_str* " +"to true with formats other than :attr:`Format.VALUE`." +msgstr "" + +#: ../../library/annotationlib.rst:377 +msgid "" +"If *obj* doesn't have an annotations dict, returns an empty dict. (Functions " +"and methods always have an annotations dict; classes, modules, and other " +"types of callables may not.)" +msgstr "" + +#: ../../library/annotationlib.rst:381 +msgid "" +"Ignores inherited annotations on classes, as well as annotations on " +"metaclasses. If a class doesn't have its own annotations dict, returns an " +"empty dict." +msgstr "" + +#: ../../library/annotationlib.rst:384 +msgid "" +"All accesses to object members and dict values are done using ``getattr()`` " +"and ``dict.get()`` for safety." +msgstr "" + +#: ../../library/annotationlib.rst:387 +msgid "" +"*eval_str* controls whether or not values of type :class:`!str` are replaced " +"with the result of calling :func:`eval` on those values:" +msgstr "" + +#: ../../library/annotationlib.rst:390 +msgid "" +"If eval_str is true, :func:`eval` is called on values of type :class:`!str`. " +"(Note that :func:`!get_annotations` doesn't catch exceptions; if :func:" +"`eval` raises an exception, it will unwind the stack past the :func:`!" +"get_annotations` call.)" +msgstr "" + +#: ../../library/annotationlib.rst:394 +msgid "" +"If *eval_str* is false (the default), values of type :class:`!str` are " +"unchanged." +msgstr "" + +#: ../../library/annotationlib.rst:397 +msgid "" +"*globals* and *locals* are passed in to :func:`eval`; see the documentation " +"for :func:`eval` for more information. If *globals* or *locals* is :const:`!" +"None`, this function may replace that value with a context-specific default, " +"contingent on ``type(obj)``:" +msgstr "" + +#: ../../library/annotationlib.rst:402 +msgid "If *obj* is a module, *globals* defaults to ``obj.__dict__``." +msgstr "如果 *obj* 是模組，則 *globals* 預設為 ``obj.__dict__``。" + +#: ../../library/annotationlib.rst:403 +msgid "" +"If *obj* is a class, *globals* defaults to ``sys.modules[obj.__module__]." +"__dict__`` and *locals* defaults to the *obj* class namespace." +msgstr "" + +#: ../../library/annotationlib.rst:406 +msgid "" +"If *obj* is a callable, *globals* defaults to :attr:`obj.__globals__ " +"`, although if *obj* is a wrapped function (using :" +"func:`functools.update_wrapper`) or a :class:`functools.partial` object, it " +"is unwrapped until a non-wrapped function is found." +msgstr "" + +#: ../../library/annotationlib.rst:412 +msgid "" +"Calling :func:`!get_annotations` is best practice for accessing the " +"annotations dict of any object. See :ref:`annotations-howto` for more " +"information on annotations best practices." +msgstr "" + +#: ../../library/annotationlib.rst:416 +msgid "" +">>> def f(a: int, b: str) -> float:\n" +"... pass\n" +">>> get_annotations(f)\n" +"{'a': , 'b': , 'return': }" +msgstr "" +">>> def f(a: int, b: str) -> float:\n" +"... pass\n" +">>> get_annotations(f)\n" +"{'a': , 'b': , 'return': }" + +#: ../../library/annotationlib.rst:427 +msgid "" +"Convert an arbitrary Python value to a format suitable for use by the :attr:" +"`~Format.STRING` format. This calls :func:`repr` for most objects, but has " +"special handling for some objects, such as type objects." +msgstr "" + +#: ../../library/annotationlib.rst:431 +msgid "" +"This is meant as a helper for user-provided annotate functions that support " +"the :attr:`~Format.STRING` format but do not have access to the code " +"creating the annotations. It can also be used to provide a user-friendly " +"string representation for other objects that contain values that are " +"commonly encountered in annotations." +msgstr "" + +#: ../../library/annotationlib.rst:441 +msgid "Recipes" +msgstr "" + +#: ../../library/annotationlib.rst:446 +msgid "Using annotations in a metaclass" +msgstr "" + +#: ../../library/annotationlib.rst:448 +msgid "" +"A :ref:`metaclass ` may want to inspect or even modify the " +"annotations in a class body during class creation. Doing so requires " +"retrieving annotations from the class namespace dictionary. For classes " +"created with ``from __future__ import annotations``, the annotations will be " +"in the ``__annotations__`` key of the dictionary. For other classes with " +"annotations, :func:`get_annotate_from_class_namespace` can be used to get " +"the annotate function, and :func:`call_annotate_function` can be used to " +"call it and retrieve the annotations. Using the :attr:`~Format.FORWARDREF` " +"format will usually be best, because this allows the annotations to refer to " +"names that cannot yet be resolved when the class is created." +msgstr "" + +#: ../../library/annotationlib.rst:459 +msgid "" +"To modify the annotations, it is best to create a wrapper annotate function " +"that calls the original annotate function, makes any necessary adjustments, " +"and returns the result." +msgstr "" + +#: ../../library/annotationlib.rst:463 +msgid "" +"Below is an example of a metaclass that filters out all :class:`typing." +"ClassVar` annotations from the class and puts them in a separate attribute:" +msgstr "" + +#: ../../library/annotationlib.rst:466 +msgid "" +"import annotationlib\n" +"import typing\n" +"\n" +"class ClassVarSeparator(type):\n" +" def __new__(mcls, name, bases, ns):\n" +" if \"__annotations__\" in ns: # from __future__ import annotations\n" +" annotations = ns[\"__annotations__\"]\n" +" classvar_keys = {\n" +" key for key, value in annotations.items()\n" +" # Use string comparison for simplicity; a more robust solution\n" +" # could use annotationlib.ForwardRef.evaluate\n" +" if value.startswith(\"ClassVar\")\n" +" }\n" +" classvars = {key: annotations[key] for key in classvar_keys}\n" +" ns[\"__annotations__\"] = {\n" +" key: value for key, value in annotations.items()\n" +" if key not in classvar_keys\n" +" }\n" +" wrapped_annotate = None\n" +" elif annotate := annotationlib.get_annotate_from_class_namespace(ns):\n" +" annotations = annotationlib.call_annotate_function(\n" +" annotate, format=annotationlib.Format.FORWARDREF\n" +" )\n" +" classvar_keys = {\n" +" key for key, value in annotations.items()\n" +" if typing.get_origin(value) is typing.ClassVar\n" +" }\n" +" classvars = {key: annotations[key] for key in classvar_keys}\n" +"\n" +" def wrapped_annotate(format):\n" +" annos = annotationlib.call_annotate_function(annotate, format, " +"owner=typ)\n" +" return {key: value for key, value in annos.items() if key not in " +"classvar_keys}\n" +"\n" +" else: # no annotations\n" +" classvars = {}\n" +" wrapped_annotate = None\n" +" typ = super().__new__(mcls, name, bases, ns)\n" +"\n" +" if wrapped_annotate is not None:\n" +" # Wrap the original __annotate__ with a wrapper that removes " +"ClassVars\n" +" typ.__annotate__ = wrapped_annotate\n" +" typ.classvars = classvars # Store the ClassVars in a separate " +"attribute\n" +" return typ" +msgstr "" + +#: ../../library/annotationlib.rst:514 +msgid "Limitations of the ``STRING`` format" +msgstr "``STRING`` 格式的限制" + +#: ../../library/annotationlib.rst:516 +msgid "" +"The :attr:`~Format.STRING` format is meant to approximate the source code of " +"the annotation, but the implementation strategy used means that it is not " +"always possible to recover the exact source code." +msgstr "" + +#: ../../library/annotationlib.rst:520 +msgid "" +"First, the stringifier of course cannot recover any information that is not " +"present in the compiled code, including comments, whitespace, " +"parenthesization, and operations that get simplified by the compiler." +msgstr "" + +#: ../../library/annotationlib.rst:524 +msgid "" +"Second, the stringifier can intercept almost all operations that involve " +"names looked up in some scope, but it cannot intercept operations that " +"operate fully on constants. As a corollary, this also means it is not safe " +"to request the ``STRING`` format on untrusted code: Python is powerful " +"enough that it is possible to achieve arbitrary code execution even with no " +"access to any globals or builtins. For example:" +msgstr "" + +#: ../../library/annotationlib.rst:530 +msgid "" +">>> def f(x: (1).__class__.__base__.__subclasses__()[-1].__init__." +"__builtins__[\"print\"](\"Hello world\")): pass\n" +"...\n" +">>> annotationlib.get_annotations(f, format=annotationlib.Format.STRING)\n" +"Hello world\n" +"{'x': 'None'}" +msgstr "" +">>> def f(x: (1).__class__.__base__.__subclasses__()[-1].__init__." +"__builtins__[\"print\"](\"Hello world\")): pass\n" +"...\n" +">>> annotationlib.get_annotations(f, format=annotationlib.Format.STRING)\n" +"Hello world\n" +"{'x': 'None'}" + +#: ../../library/annotationlib.rst:539 +msgid "" +"This particular example works as of the time of writing, but it relies on " +"implementation details and is not guaranteed to work in the future." +msgstr "" + +#: ../../library/annotationlib.rst:542 +msgid "" +"Among the different kinds of expressions that exist in Python, as " +"represented by the :mod:`ast` module, some expressions are supported, " +"meaning that the ``STRING`` format can generally recover the original source " +"code; others are unsupported, meaning that they may result in incorrect " +"output or an error." +msgstr "" + +#: ../../library/annotationlib.rst:547 +msgid "The following are supported (sometimes with caveats):" +msgstr "" + +#: ../../library/annotationlib.rst:549 +msgid ":class:`ast.BinOp`" +msgstr ":class:`ast.BinOp`" + +#: ../../library/annotationlib.rst:550 +msgid ":class:`ast.UnaryOp`" +msgstr ":class:`ast.UnaryOp`" + +#: ../../library/annotationlib.rst:552 +msgid "" +":class:`ast.Invert` (``~``), :class:`ast.UAdd` (``+``), and :class:`ast." +"USub` (``-``) are supported" +msgstr "" +":class:`ast.Invert` (``~``)、:class:`ast.UAdd` (``+``) 和 :class:`ast.USub` (``-``) 有被支援" + +#: ../../library/annotationlib.rst:553 +msgid ":class:`ast.Not` (``not``) is not supported" +msgstr ":class:`ast.Not` (``not``) 並不被支援" + +#: ../../library/annotationlib.rst:555 +msgid ":class:`ast.Dict` (except when using ``**`` unpacking)" +msgstr ":class:`ast.Dict`\\ （除了使用 ``**`` 解包的情況）" + +#: ../../library/annotationlib.rst:556 +msgid ":class:`ast.Set`" +msgstr ":class:`ast.Set`" + +#: ../../library/annotationlib.rst:557 +msgid ":class:`ast.Compare`" +msgstr ":class:`ast.Compare`" + +#: ../../library/annotationlib.rst:559 +msgid ":class:`ast.Eq` and :class:`ast.NotEq` are supported" +msgstr ":class:`ast.Eq` 和 :class:`ast.NotEq` 有被支援" + +#: ../../library/annotationlib.rst:560 +msgid "" +":class:`ast.Lt`, :class:`ast.LtE`, :class:`ast.Gt`, and :class:`ast.GtE` are " +"supported, but the operand may be flipped" +msgstr "" + +#: ../../library/annotationlib.rst:561 +msgid "" +":class:`ast.Is`, :class:`ast.IsNot`, :class:`ast.In`, and :class:`ast.NotIn` " +"are not supported" +msgstr "" + +#: ../../library/annotationlib.rst:563 +msgid ":class:`ast.Call` (except when using ``**`` unpacking)" +msgstr "" + +#: ../../library/annotationlib.rst:564 +msgid "" +":class:`ast.Constant` (though not the exact representation of the constant; " +"for example, escape sequences in strings are lost; hexadecimal numbers are " +"converted to decimal)" +msgstr "" + +#: ../../library/annotationlib.rst:566 +msgid ":class:`ast.Attribute` (assuming the value is not a constant)" +msgstr "" + +#: ../../library/annotationlib.rst:567 +msgid ":class:`ast.Subscript` (assuming the value is not a constant)" +msgstr "" + +#: ../../library/annotationlib.rst:568 +msgid ":class:`ast.Starred` (``*`` unpacking)" +msgstr "" + +#: ../../library/annotationlib.rst:569 +msgid ":class:`ast.Name`" +msgstr ":class:`ast.Name`" + +#: ../../library/annotationlib.rst:570 +msgid ":class:`ast.List`" +msgstr ":class:`ast.List`" + +#: ../../library/annotationlib.rst:571 +msgid ":class:`ast.Tuple`" +msgstr ":class:`ast.Tuple`" + +#: ../../library/annotationlib.rst:572 +msgid ":class:`ast.Slice`" +msgstr ":class:`ast.Slice`" + +#: ../../library/annotationlib.rst:574 +msgid "" +"The following are unsupported, but throw an informative error when " +"encountered by the stringifier:" +msgstr "" + +#: ../../library/annotationlib.rst:577 +msgid "" +":class:`ast.FormattedValue` (f-strings; error is not detected if conversion " +"specifiers like ``!r`` are used)" +msgstr "" + +#: ../../library/annotationlib.rst:579 +msgid ":class:`ast.JoinedStr` (f-strings)" +msgstr ":class:`ast.JoinedStr`\\ （f 字串）" + +#: ../../library/annotationlib.rst:581 +msgid "The following are unsupported and result in incorrect output:" +msgstr "以下是不支援的，並且會導致不正確的輸出：" + +#: ../../library/annotationlib.rst:583 +msgid ":class:`ast.BoolOp` (``and`` and ``or``)" +msgstr ":class:`ast.BoolOp`\\ （``and`` 和 ``or``）" + +#: ../../library/annotationlib.rst:584 +msgid ":class:`ast.IfExp`" +msgstr ":class:`ast.IfExp`" + +#: ../../library/annotationlib.rst:585 +msgid ":class:`ast.Lambda`" +msgstr ":class:`ast.Lambda`" + +#: ../../library/annotationlib.rst:586 +msgid ":class:`ast.ListComp`" +msgstr ":class:`ast.ListComp`" + +#: ../../library/annotationlib.rst:587 +msgid ":class:`ast.SetComp`" +msgstr ":class:`ast.SetComp`" + +#: ../../library/annotationlib.rst:588 +msgid ":class:`ast.DictComp`" +msgstr ":class:`ast.DictComp`" + +#: ../../library/annotationlib.rst:589 +msgid ":class:`ast.GeneratorExp`" +msgstr ":class:`ast.GeneratorExp`" + +#: ../../library/annotationlib.rst:591 +msgid "" +"The following are disallowed in annotation scopes and therefore not relevant:" +msgstr "" + +#: ../../library/annotationlib.rst:593 +msgid ":class:`ast.NamedExpr` (``:=``)" +msgstr ":class:`ast.NamedExpr` (``:=``)" + +#: ../../library/annotationlib.rst:594 +msgid ":class:`ast.Await`" +msgstr ":class:`ast.Await`" + +#: ../../library/annotationlib.rst:595 +msgid ":class:`ast.Yield`" +msgstr ":class:`ast.Yield`" + +#: ../../library/annotationlib.rst:596 +msgid ":class:`ast.YieldFrom`" +msgstr ":class:`ast.YieldFrom`" + +#: ../../library/annotationlib.rst:600 +msgid "Limitations of the ``FORWARDREF`` format" +msgstr "``FORWARDREF`` 格式的限制" + +#: ../../library/annotationlib.rst:602 +msgid "" +"The :attr:`~Format.FORWARDREF` format aims to produce real values as much as " +"possible, with anything that cannot be resolved replaced with :class:" +"`ForwardRef` objects. It is affected by broadly the same Limitations as the :" +"attr:`~Format.STRING` format: annotations that perform operations on " +"literals or that use unsupported expression types may raise exceptions when " +"evaluated using the :attr:`~Format.FORWARDREF` format." +msgstr "" + +#: ../../library/annotationlib.rst:609 +msgid "Below are a few examples of the behavior with unsupported expressions:" +msgstr "" + +#: ../../library/annotationlib.rst:611 +msgid "" +">>> from annotationlib import get_annotations, Format\n" +">>> def zerodiv(x: 1 / 0): ...\n" +">>> get_annotations(zerodiv, format=Format.STRING)\n" +"Traceback (most recent call last):\n" +" ...\n" +"ZeroDivisionError: division by zero\n" +">>> get_annotations(zerodiv, format=Format.FORWARDREF)\n" +"Traceback (most recent call last):\n" +" ...\n" +"ZeroDivisionError: division by zero\n" +">>> def ifexp(x: 1 if y else 0): ...\n" +">>> get_annotations(ifexp, format=Format.STRING)\n" +"{'x': '1'}" +msgstr "" +">>> from annotationlib import get_annotations, Format\n" +">>> def zerodiv(x: 1 / 0): ...\n" +">>> get_annotations(zerodiv, format=Format.STRING)\n" +"Traceback (most recent call last):\n" +" ...\n" +"ZeroDivisionError: division by zero\n" +">>> get_annotations(zerodiv, format=Format.FORWARDREF)\n" +"Traceback (most recent call last):\n" +" ...\n" +"ZeroDivisionError: division by zero\n" +">>> def ifexp(x: 1 if y else 0): ...\n" +">>> get_annotations(ifexp, format=Format.STRING)\n" +"{'x': '1'}" + +#: ../../library/annotationlib.rst:630 +msgid "Security implications of introspecting annotations" +msgstr "" + +#: ../../library/annotationlib.rst:632 +msgid "" +"Much of the functionality in this module involves executing code related to " +"annotations, which can then do arbitrary things. For example, :func:" +"`get_annotations` may call an arbitrary :term:`annotate function`, and :meth:" +"`ForwardRef.evaluate` may call :func:`eval` on an arbitrary string. Code " +"contained in an annotation might make arbitrary system calls, enter an " +"infinite loop, or perform any other operation. This is also true for any " +"access of the :attr:`~object.__annotations__` attribute, and for various " +"functions in the :mod:`typing` module that work with annotations, such as :" +"func:`typing.get_type_hints`." +msgstr "" + +#: ../../library/annotationlib.rst:641 +msgid "" +"Any security issue arising from this also applies immediately after " +"importing code that may contain untrusted annotations: importing code can " +"always cause arbitrary operations to be performed. However, it is unsafe to " +"accept strings or other input from an untrusted source and pass them to any " +"of the APIs for introspecting annotations, for example by editing an " +"``__annotations__`` dictionary or directly creating a :class:`ForwardRef` " +"object." +msgstr "" diff --git a/library/archiving.po b/library/archiving.po index 2051ce20cc..19f7504090 100644 --- a/library/archiving.po +++ b/library/archiving.po @@ -1,35 +1,35 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Leon H., 2017 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: 2023-02-18 14:22+0800\n" -"Last-Translator: Leon H.\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" -"X-Generator: Poedit 3.2.2\n" - -#: ../../library/archiving.rst:5 -msgid "Data Compression and Archiving" -msgstr "資料壓縮與保存" - -#: ../../library/archiving.rst:7 -msgid "" -"The modules described in this chapter support data compression with the " -"zlib, gzip, bzip2, lzma, and zstd algorithms, and the creation of ZIP- and " -"tar-format archives. See also :ref:`archiving-operations` provided by " -"the :mod:`shutil` module." -msgstr "" -"本章中描述的模組支援使用 zlib、gzip、bzip2、lzma 和 zstd 演算法進行資料壓縮，以及" -"建立 ZIP 和 tar 格式的存檔。另請參閱 :mod:`shutil` 模組提供的 :ref:`archiving-" -"operations`。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Leon H., 2017 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: 2023-02-18 14:22+0800\n" +"Last-Translator: Leon H.\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" +"X-Generator: Poedit 3.2.2\n" + +#: ../../library/archiving.rst:5 +msgid "Data Compression and Archiving" +msgstr "資料壓縮與保存" + +#: ../../library/archiving.rst:7 +msgid "" +"The modules described in this chapter support data compression with the " +"zlib, gzip, bzip2, lzma, and zstd algorithms, and the creation of ZIP- and " +"tar-format archives. See also :ref:`archiving-operations` provided by " +"the :mod:`shutil` module." +msgstr "" +"本章中描述的模組支援使用 zlib、gzip、bzip2、lzma 和 zstd 演算法進行資料壓縮，以及" +"建立 ZIP 和 tar 格式的存檔。另請參閱 :mod:`shutil` 模組提供的 :ref:`archiving-" +"operations`。" diff --git a/library/argparse.po b/library/argparse.po index f83d138744..e851eb6a61 100644 --- a/library/argparse.po +++ b/library/argparse.po @@ -1,3915 +1,3915 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2026-01-07 00:14+0000\n" -"PO-Revision-Date: 2018-05-23 14:38+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/argparse.rst:2 -msgid "" -":mod:`!argparse` --- Parser for command-line options, arguments and " -"subcommands" -msgstr ":mod:`!argparse` --- 命令列選項、引數和子命令的剖析器" - -#: ../../library/argparse.rst:12 -msgid "**Source code:** :source:`Lib/argparse.py`" -msgstr "**原始碼：**\\ :source:`Lib/argparse.py`" - -#: ../../library/argparse.rst:16 -msgid "" -"While :mod:`argparse` is the default recommended standard library module for " -"implementing basic command line applications, authors with more exacting " -"requirements for exactly how their command line applications behave may find " -"it doesn't provide the necessary level of control. Refer to :ref:`choosing-" -"an-argument-parser` for alternatives to consider when ``argparse`` doesn't " -"support behaviors that the application requires (such as entirely disabling " -"support for interspersed options and positional arguments, or accepting " -"option parameter values that start with ``-`` even when they correspond to " -"another defined option)." -msgstr "" - -#: ../../library/argparse.rst:28 -msgid "Tutorial" -msgstr "教學" - -#: ../../library/argparse.rst:30 -msgid "" -"This page contains the API reference information. For a more gentle " -"introduction to Python command-line parsing, have a look at the :ref:" -"`argparse tutorial `." -msgstr "" - -#: ../../library/argparse.rst:34 -msgid "" -"The :mod:`!argparse` module makes it easy to write user-friendly command-" -"line interfaces. The program defines what arguments it requires, and :mod:`!" -"argparse` will figure out how to parse those out of :data:`sys.argv`. The :" -"mod:`!argparse` module also automatically generates help and usage " -"messages. The module will also issue errors when users give the program " -"invalid arguments." -msgstr "" - -#: ../../library/argparse.rst:40 -msgid "" -"The :mod:`!argparse` module's support for command-line interfaces is built " -"around an instance of :class:`argparse.ArgumentParser`. It is a container " -"for argument specifications and has options that apply to the parser as " -"whole::" -msgstr "" - -#: ../../library/argparse.rst:44 -msgid "" -"parser = argparse.ArgumentParser(\n" -" prog='ProgramName',\n" -" description='What the program does',\n" -" epilog='Text at the bottom of help')" -msgstr "" -"parser = argparse.ArgumentParser(\n" -" prog='ProgramName',\n" -" description='What the program does',\n" -" epilog='Text at the bottom of help')" - -#: ../../library/argparse.rst:49 -msgid "" -"The :meth:`ArgumentParser.add_argument` method attaches individual argument " -"specifications to the parser. It supports positional arguments, options " -"that accept values, and on/off flags::" -msgstr "" - -#: ../../library/argparse.rst:53 -msgid "" -"parser.add_argument('filename') # positional argument\n" -"parser.add_argument('-c', '--count') # option that takes a value\n" -"parser.add_argument('-v', '--verbose',\n" -" action='store_true') # on/off flag" -msgstr "" -"parser.add_argument('filename') # 位置引數\n" -"parser.add_argument('-c', '--count') # 接收一個值的選項\n" -"parser.add_argument('-v', '--verbose',\n" -" action='store_true') # 開關旗標" - -#: ../../library/argparse.rst:58 -msgid "" -"The :meth:`ArgumentParser.parse_args` method runs the parser and places the " -"extracted data in a :class:`argparse.Namespace` object::" -msgstr "" - -#: ../../library/argparse.rst:61 -msgid "" -"args = parser.parse_args()\n" -"print(args.filename, args.count, args.verbose)" -msgstr "" -"args = parser.parse_args()\n" -"print(args.filename, args.count, args.verbose)" - -#: ../../library/argparse.rst:65 -msgid "" -"If you're looking for a guide about how to upgrade :mod:`optparse` code to :" -"mod:`!argparse`, see :ref:`Upgrading Optparse Code `." -msgstr "" - -#: ../../library/argparse.rst:69 -msgid "ArgumentParser objects" -msgstr "ArgumentParser 物件" - -#: ../../library/argparse.rst:79 -msgid "" -"Create a new :class:`ArgumentParser` object. All parameters should be passed " -"as keyword arguments. Each parameter has its own more detailed description " -"below, but in short they are:" -msgstr "" - -#: ../../library/argparse.rst:83 -msgid "" -"prog_ - The name of the program (default: generated from the ``__main__`` " -"module attributes and ``sys.argv[0]``)" -msgstr "" -"prog_ - 程式的名稱（預設值：從 ``__main__`` 模組屬性和 ``sys.argv[0]`` 產生）" - -#: ../../library/argparse.rst:86 -msgid "" -"usage_ - The string describing the program usage (default: generated from " -"arguments added to parser)" -msgstr "usage_ - 描述程式用法的字串（預設值：從新增到剖析器的引數產生）" - -#: ../../library/argparse.rst:89 -msgid "" -"description_ - Text to display before the argument help (by default, no text)" -msgstr "description_ - 引數說明之前要顯示的文字（預設值：無文字）" - -#: ../../library/argparse.rst:92 -msgid "epilog_ - Text to display after the argument help (by default, no text)" -msgstr "epilog_ - 引數說明之後要顯示的文字（預設值：無文字）" - -#: ../../library/argparse.rst:94 -msgid "" -"parents_ - A list of :class:`ArgumentParser` objects whose arguments should " -"also be included" -msgstr "parents_ - 一個 :class:`ArgumentParser` 物件的串列，其引數也應該被包含" - -#: ../../library/argparse.rst:97 -msgid "formatter_class_ - A class for customizing the help output" -msgstr "formatter_class_ - 用於自訂說明輸出的類別" - -#: ../../library/argparse.rst:99 -msgid "" -"prefix_chars_ - The set of characters that prefix optional arguments " -"(default: '-')" -msgstr "prefix_chars_ - 前綴可選引數的字元集合（預設值：'-'）" - -#: ../../library/argparse.rst:102 -msgid "" -"fromfile_prefix_chars_ - The set of characters that prefix files from which " -"additional arguments should be read (default: ``None``)" -msgstr "" - -#: ../../library/argparse.rst:105 -msgid "" -"argument_default_ - The global default value for arguments (default: " -"``None``)" -msgstr "" - -#: ../../library/argparse.rst:108 -msgid "" -"conflict_handler_ - The strategy for resolving conflicting optionals " -"(usually unnecessary)" -msgstr "" - -#: ../../library/argparse.rst:111 -msgid "" -"add_help_ - Add a ``-h/--help`` option to the parser (default: ``True``)" -msgstr "" - -#: ../../library/argparse.rst:113 -msgid "" -"allow_abbrev_ - Allows long options to be abbreviated if the abbreviation is " -"unambiguous (default: ``True``)" -msgstr "" - -#: ../../library/argparse.rst:116 -msgid "" -"exit_on_error_ - Determines whether or not :class:`!ArgumentParser` exits " -"with error info when an error occurs. (default: ``True``)" -msgstr "" - -#: ../../library/argparse.rst:119 -msgid "" -"suggest_on_error_ - Enables suggestions for mistyped argument choices and " -"subparser names (default: ``False``)" -msgstr "" - -#: ../../library/argparse.rst:122 -msgid "color_ - Allow color output (default: ``True``)" -msgstr "" - -#: ../../library/argparse.rst:124 -msgid "*allow_abbrev* parameter was added." -msgstr "新增 *allow_abbrev* 參數。" - -#: ../../library/argparse.rst:127 -msgid "" -"In previous versions, *allow_abbrev* also disabled grouping of short flags " -"such as ``-vv`` to mean ``-v -v``." -msgstr "" - -#: ../../library/argparse.rst:131 -msgid "*exit_on_error* parameter was added." -msgstr "新增 *exit_on_error* 參數。" - -#: ../../library/argparse.rst:134 -msgid "*suggest_on_error* and *color* parameters were added." -msgstr "新增 *suggest_on_error* 和 *color* 參數。" - -#: ../../library/argparse.rst:137 ../../library/argparse.rst:696 -msgid "The following sections describe how each of these are used." -msgstr "" - -#: ../../library/argparse.rst:143 -msgid "prog" -msgstr "prog" - -#: ../../library/argparse.rst:146 -msgid "" -"By default, :class:`ArgumentParser` calculates the name of the program to " -"display in help messages depending on the way the Python interpreter was run:" -msgstr "" - -#: ../../library/argparse.rst:149 -msgid "" -"The :func:`base name ` of ``sys.argv[0]`` if a file was " -"passed as argument." -msgstr "" - -#: ../../library/argparse.rst:151 -msgid "" -"The Python interpreter name followed by ``sys.argv[0]`` if a directory or a " -"zipfile was passed as argument." -msgstr "" - -#: ../../library/argparse.rst:153 -msgid "" -"The Python interpreter name followed by ``-m`` followed by the module or " -"package name if the :option:`-m` option was used." -msgstr "" - -#: ../../library/argparse.rst:156 -msgid "" -"This default is almost always desirable because it will make the help " -"messages match the string that was used to invoke the program on the command " -"line. However, to change this default behavior, another value can be " -"supplied using the ``prog=`` argument to :class:`ArgumentParser`::" -msgstr "" - -#: ../../library/argparse.rst:161 -msgid "" -">>> parser = argparse.ArgumentParser(prog='myprogram')\n" -">>> parser.print_help()\n" -"usage: myprogram [-h]\n" -"\n" -"options:\n" -" -h, --help show this help message and exit" -msgstr "" -">>> parser = argparse.ArgumentParser(prog='myprogram')\n" -">>> parser.print_help()\n" -"usage: myprogram [-h]\n" -"\n" -"options:\n" -" -h, --help show this help message and exit" - -#: ../../library/argparse.rst:168 -msgid "" -"Note that the program name, whether determined from ``sys.argv[0]``, from " -"the ``__main__`` module attributes or from the ``prog=`` argument, is " -"available to help messages using the ``%(prog)s`` format specifier." -msgstr "" - -#: ../../library/argparse.rst:175 -msgid "" -">>> parser = argparse.ArgumentParser(prog='myprogram')\n" -">>> parser.add_argument('--foo', help='foo of the %(prog)s program')\n" -">>> parser.print_help()\n" -"usage: myprogram [-h] [--foo FOO]\n" -"\n" -"options:\n" -" -h, --help show this help message and exit\n" -" --foo FOO foo of the myprogram program" -msgstr "" -">>> parser = argparse.ArgumentParser(prog='myprogram')\n" -">>> parser.add_argument('--foo', help='foo of the %(prog)s program')\n" -">>> parser.print_help()\n" -"usage: myprogram [-h] [--foo FOO]\n" -"\n" -"options:\n" -" -h, --help show this help message and exit\n" -" --foo FOO foo of the myprogram program" - -#: ../../library/argparse.rst:184 -msgid "" -"The default ``prog`` value now reflects how ``__main__`` was actually " -"executed, rather than always being ``os.path.basename(sys.argv[0])``." -msgstr "" - -#: ../../library/argparse.rst:189 -msgid "usage" -msgstr "usage" - -#: ../../library/argparse.rst:191 -msgid "" -"By default, :class:`ArgumentParser` calculates the usage message from the " -"arguments it contains. The default message can be overridden with the " -"``usage=`` keyword argument::" -msgstr "" - -#: ../../library/argparse.rst:195 -msgid "" -">>> parser = argparse.ArgumentParser(prog='PROG', usage='%(prog)s " -"[options]')\n" -">>> parser.add_argument('--foo', nargs='?', help='foo help')\n" -">>> parser.add_argument('bar', nargs='+', help='bar help')\n" -">>> parser.print_help()\n" -"usage: PROG [options]\n" -"\n" -"positional arguments:\n" -" bar bar help\n" -"\n" -"options:\n" -" -h, --help show this help message and exit\n" -" --foo [FOO] foo help" -msgstr "" -">>> parser = argparse.ArgumentParser(prog='PROG', usage='%(prog)s " -"[options]')\n" -">>> parser.add_argument('--foo', nargs='?', help='foo help')\n" -">>> parser.add_argument('bar', nargs='+', help='bar help')\n" -">>> parser.print_help()\n" -"usage: PROG [options]\n" -"\n" -"positional arguments:\n" -" bar bar help\n" -"\n" -"options:\n" -" -h, --help show this help message and exit\n" -" --foo [FOO] foo help" - -#: ../../library/argparse.rst:208 -msgid "" -"The ``%(prog)s`` format specifier is available to fill in the program name " -"in your usage messages." -msgstr "" - -#: ../../library/argparse.rst:211 -msgid "" -"When a custom usage message is specified for the main parser, you may also " -"want to consider passing the ``prog`` argument to :meth:`~ArgumentParser." -"add_subparsers` or the ``prog`` and the ``usage`` arguments to :meth:" -"`~_SubParsersAction.add_parser`, to ensure consistent command prefixes and " -"usage information across subparsers." -msgstr "" - -#: ../../library/argparse.rst:221 -msgid "description" -msgstr "description" - -#: ../../library/argparse.rst:223 -msgid "" -"Most calls to the :class:`ArgumentParser` constructor will use the " -"``description=`` keyword argument. This argument gives a brief description " -"of what the program does and how it works. In help messages, the " -"description is displayed between the command-line usage string and the help " -"messages for the various arguments." -msgstr "" - -#: ../../library/argparse.rst:229 -msgid "" -"By default, the description will be line-wrapped so that it fits within the " -"given space. To change this behavior, see the formatter_class_ argument." -msgstr "" - -#: ../../library/argparse.rst:234 -msgid "epilog" -msgstr "epilog" - -#: ../../library/argparse.rst:236 -msgid "" -"Some programs like to display additional description of the program after " -"the description of the arguments. Such text can be specified using the " -"``epilog=`` argument to :class:`ArgumentParser`::" -msgstr "" - -#: ../../library/argparse.rst:240 -msgid "" -">>> parser = argparse.ArgumentParser(\n" -"... description='A foo that bars',\n" -"... epilog=\"And that's how you'd foo a bar\")\n" -">>> parser.print_help()\n" -"usage: argparse.py [-h]\n" -"\n" -"A foo that bars\n" -"\n" -"options:\n" -" -h, --help show this help message and exit\n" -"\n" -"And that's how you'd foo a bar" -msgstr "" -">>> parser = argparse.ArgumentParser(\n" -"... description='A foo that bars',\n" -"... epilog=\"And that's how you'd foo a bar\")\n" -">>> parser.print_help()\n" -"usage: argparse.py [-h]\n" -"\n" -"A foo that bars\n" -"\n" -"options:\n" -" -h, --help show this help message and exit\n" -"\n" -"And that's how you'd foo a bar" - -#: ../../library/argparse.rst:253 -msgid "" -"As with the description_ argument, the ``epilog=`` text is by default line-" -"wrapped, but this behavior can be adjusted with the formatter_class_ " -"argument to :class:`ArgumentParser`." -msgstr "" - -#: ../../library/argparse.rst:259 -msgid "parents" -msgstr "parents" - -#: ../../library/argparse.rst:261 -msgid "" -"Sometimes, several parsers share a common set of arguments. Rather than " -"repeating the definitions of these arguments, a single parser with all the " -"shared arguments and passed to ``parents=`` argument to :class:" -"`ArgumentParser` can be used. The ``parents=`` argument takes a list of :" -"class:`ArgumentParser` objects, collects all the positional and optional " -"actions from them, and adds these actions to the :class:`ArgumentParser` " -"object being constructed::" -msgstr "" - -#: ../../library/argparse.rst:268 -msgid "" -">>> parent_parser = argparse.ArgumentParser(add_help=False)\n" -">>> parent_parser.add_argument('--parent', type=int)\n" -"\n" -">>> foo_parser = argparse.ArgumentParser(parents=[parent_parser])\n" -">>> foo_parser.add_argument('foo')\n" -">>> foo_parser.parse_args(['--parent', '2', 'XXX'])\n" -"Namespace(foo='XXX', parent=2)\n" -"\n" -">>> bar_parser = argparse.ArgumentParser(parents=[parent_parser])\n" -">>> bar_parser.add_argument('--bar')\n" -">>> bar_parser.parse_args(['--bar', 'YYY'])\n" -"Namespace(bar='YYY', parent=None)" -msgstr "" -">>> parent_parser = argparse.ArgumentParser(add_help=False)\n" -">>> parent_parser.add_argument('--parent', type=int)\n" -"\n" -">>> foo_parser = argparse.ArgumentParser(parents=[parent_parser])\n" -">>> foo_parser.add_argument('foo')\n" -">>> foo_parser.parse_args(['--parent', '2', 'XXX'])\n" -"Namespace(foo='XXX', parent=2)\n" -"\n" -">>> bar_parser = argparse.ArgumentParser(parents=[parent_parser])\n" -">>> bar_parser.add_argument('--bar')\n" -">>> bar_parser.parse_args(['--bar', 'YYY'])\n" -"Namespace(bar='YYY', parent=None)" - -#: ../../library/argparse.rst:281 -msgid "" -"Note that most parent parsers will specify ``add_help=False``. Otherwise, " -"the :class:`ArgumentParser` will see two ``-h/--help`` options (one in the " -"parent and one in the child) and raise an error." -msgstr "" - -#: ../../library/argparse.rst:286 -msgid "" -"You must fully initialize the parsers before passing them via ``parents=``. " -"If you change the parent parsers after the child parser, those changes will " -"not be reflected in the child." -msgstr "" - -#: ../../library/argparse.rst:294 -msgid "formatter_class" -msgstr "formatter_class" - -#: ../../library/argparse.rst:296 -msgid "" -":class:`ArgumentParser` objects allow the help formatting to be customized " -"by specifying an alternate formatting class. Currently, there are four such " -"classes:" -msgstr "" - -#: ../../library/argparse.rst:305 -msgid "" -":class:`RawDescriptionHelpFormatter` and :class:`RawTextHelpFormatter` give " -"more control over how textual descriptions are displayed. By default, :class:" -"`ArgumentParser` objects line-wrap the description_ and epilog_ texts in " -"command-line help messages::" -msgstr "" - -#: ../../library/argparse.rst:310 -msgid "" -">>> parser = argparse.ArgumentParser(\n" -"... prog='PROG',\n" -"... description='''this description\n" -"... was indented weird\n" -"... but that is okay''',\n" -"... epilog='''\n" -"... likewise for this epilog whose whitespace will\n" -"... be cleaned up and whose words will be wrapped\n" -"... across a couple lines''')\n" -">>> parser.print_help()\n" -"usage: PROG [-h]\n" -"\n" -"this description was indented weird but that is okay\n" -"\n" -"options:\n" -" -h, --help show this help message and exit\n" -"\n" -"likewise for this epilog whose whitespace will be cleaned up and whose " -"words\n" -"will be wrapped across a couple lines" -msgstr "" -">>> parser = argparse.ArgumentParser(\n" -"... prog='PROG',\n" -"... description='''this description\n" -"... was indented weird\n" -"... but that is okay''',\n" -"... epilog='''\n" -"... likewise for this epilog whose whitespace will\n" -"... be cleaned up and whose words will be wrapped\n" -"... across a couple lines''')\n" -">>> parser.print_help()\n" -"usage: PROG [-h]\n" -"\n" -"this description was indented weird but that is okay\n" -"\n" -"options:\n" -" -h, --help show this help message and exit\n" -"\n" -"likewise for this epilog whose whitespace will be cleaned up and whose " -"words\n" -"will be wrapped across a couple lines" - -#: ../../library/argparse.rst:330 -msgid "" -"Passing :class:`RawDescriptionHelpFormatter` as ``formatter_class=`` " -"indicates that description_ and epilog_ are already correctly formatted and " -"should not be line-wrapped::" -msgstr "" - -#: ../../library/argparse.rst:334 -msgid "" -">>> parser = argparse.ArgumentParser(\n" -"... prog='PROG',\n" -"... formatter_class=argparse.RawDescriptionHelpFormatter,\n" -"... description=textwrap.dedent('''\\\n" -"... Please do not mess up this text!\n" -"... --------------------------------\n" -"... I have indented it\n" -"... exactly the way\n" -"... I want it\n" -"... '''))\n" -">>> parser.print_help()\n" -"usage: PROG [-h]\n" -"\n" -"Please do not mess up this text!\n" -"--------------------------------\n" -" I have indented it\n" -" exactly the way\n" -" I want it\n" -"\n" -"options:\n" -" -h, --help show this help message and exit" -msgstr "" -">>> parser = argparse.ArgumentParser(\n" -"... prog='PROG',\n" -"... formatter_class=argparse.RawDescriptionHelpFormatter,\n" -"... description=textwrap.dedent('''\\\n" -"... Please do not mess up this text!\n" -"... --------------------------------\n" -"... I have indented it\n" -"... exactly the way\n" -"... I want it\n" -"... '''))\n" -">>> parser.print_help()\n" -"usage: PROG [-h]\n" -"\n" -"Please do not mess up this text!\n" -"--------------------------------\n" -" I have indented it\n" -" exactly the way\n" -" I want it\n" -"\n" -"options:\n" -" -h, --help show this help message and exit" - -#: ../../library/argparse.rst:356 -msgid "" -":class:`RawTextHelpFormatter` maintains whitespace for all sorts of help " -"text, including argument descriptions. However, multiple newlines are " -"replaced with one. If you wish to preserve multiple blank lines, add spaces " -"between the newlines." -msgstr "" - -#: ../../library/argparse.rst:361 -msgid "" -":class:`ArgumentDefaultsHelpFormatter` automatically adds information about " -"default values to each of the argument help messages::" -msgstr "" - -#: ../../library/argparse.rst:364 -msgid "" -">>> parser = argparse.ArgumentParser(\n" -"... prog='PROG',\n" -"... formatter_class=argparse.ArgumentDefaultsHelpFormatter)\n" -">>> parser.add_argument('--foo', type=int, default=42, help='FOO!')\n" -">>> parser.add_argument('bar', nargs='*', default=[1, 2, 3], help='BAR!')\n" -">>> parser.print_help()\n" -"usage: PROG [-h] [--foo FOO] [bar ...]\n" -"\n" -"positional arguments:\n" -" bar BAR! (default: [1, 2, 3])\n" -"\n" -"options:\n" -" -h, --help show this help message and exit\n" -" --foo FOO FOO! (default: 42)" -msgstr "" -">>> parser = argparse.ArgumentParser(\n" -"... prog='PROG',\n" -"... formatter_class=argparse.ArgumentDefaultsHelpFormatter)\n" -">>> parser.add_argument('--foo', type=int, default=42, help='FOO!')\n" -">>> parser.add_argument('bar', nargs='*', default=[1, 2, 3], help='BAR!')\n" -">>> parser.print_help()\n" -"usage: PROG [-h] [--foo FOO] [bar ...]\n" -"\n" -"positional arguments:\n" -" bar BAR! (default: [1, 2, 3])\n" -"\n" -"options:\n" -" -h, --help show this help message and exit\n" -" --foo FOO FOO! (default: 42)" - -#: ../../library/argparse.rst:379 -msgid "" -":class:`MetavarTypeHelpFormatter` uses the name of the type_ argument for " -"each argument as the display name for its values (rather than using the " -"dest_ as the regular formatter does)::" -msgstr "" - -#: ../../library/argparse.rst:383 -msgid "" -">>> parser = argparse.ArgumentParser(\n" -"... prog='PROG',\n" -"... formatter_class=argparse.MetavarTypeHelpFormatter)\n" -">>> parser.add_argument('--foo', type=int)\n" -">>> parser.add_argument('bar', type=float)\n" -">>> parser.print_help()\n" -"usage: PROG [-h] [--foo int] float\n" -"\n" -"positional arguments:\n" -" float\n" -"\n" -"options:\n" -" -h, --help show this help message and exit\n" -" --foo int" -msgstr "" -">>> parser = argparse.ArgumentParser(\n" -"... prog='PROG',\n" -"... formatter_class=argparse.MetavarTypeHelpFormatter)\n" -">>> parser.add_argument('--foo', type=int)\n" -">>> parser.add_argument('bar', type=float)\n" -">>> parser.print_help()\n" -"usage: PROG [-h] [--foo int] float\n" -"\n" -"positional arguments:\n" -" float\n" -"\n" -"options:\n" -" -h, --help show this help message and exit\n" -" --foo int" - -#: ../../library/argparse.rst:400 -msgid "prefix_chars" -msgstr "prefix_chars" - -#: ../../library/argparse.rst:402 -msgid "" -"Most command-line options will use ``-`` as the prefix, e.g. ``-f/--foo``. " -"Parsers that need to support different or additional prefix characters, e.g. " -"for options like ``+f`` or ``/foo``, may specify them using the " -"``prefix_chars=`` argument to the :class:`ArgumentParser` constructor::" -msgstr "" - -#: ../../library/argparse.rst:408 -msgid "" -">>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='-+')\n" -">>> parser.add_argument('+f')\n" -">>> parser.add_argument('++bar')\n" -">>> parser.parse_args('+f X ++bar Y'.split())\n" -"Namespace(bar='Y', f='X')" -msgstr "" -">>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='-+')\n" -">>> parser.add_argument('+f')\n" -">>> parser.add_argument('++bar')\n" -">>> parser.parse_args('+f X ++bar Y'.split())\n" -"Namespace(bar='Y', f='X')" - -#: ../../library/argparse.rst:414 -msgid "" -"The ``prefix_chars=`` argument defaults to ``'-'``. Supplying a set of " -"characters that does not include ``-`` will cause ``-f/--foo`` options to be " -"disallowed." -msgstr "" - -#: ../../library/argparse.rst:420 -msgid "fromfile_prefix_chars" -msgstr "fromfile_prefix_chars" - -#: ../../library/argparse.rst:422 -msgid "" -"Sometimes, when dealing with a particularly long argument list, it may make " -"sense to keep the list of arguments in a file rather than typing it out at " -"the command line. If the ``fromfile_prefix_chars=`` argument is given to " -"the :class:`ArgumentParser` constructor, then arguments that start with any " -"of the specified characters will be treated as files, and will be replaced " -"by the arguments they contain. For example::" -msgstr "" - -#: ../../library/argparse.rst:429 -msgid "" -">>> with open('args.txt', 'w', encoding=sys.getfilesystemencoding()) as fp:\n" -"... fp.write('-f\\nbar')\n" -"...\n" -">>> parser = argparse.ArgumentParser(fromfile_prefix_chars='@')\n" -">>> parser.add_argument('-f')\n" -">>> parser.parse_args(['-f', 'foo', '@args.txt'])\n" -"Namespace(f='bar')" -msgstr "" -">>> with open('args.txt', 'w', encoding=sys.getfilesystemencoding()) as fp:\n" -"... fp.write('-f\\nbar')\n" -"...\n" -">>> parser = argparse.ArgumentParser(fromfile_prefix_chars='@')\n" -">>> parser.add_argument('-f')\n" -">>> parser.parse_args(['-f', 'foo', '@args.txt'])\n" -"Namespace(f='bar')" - -#: ../../library/argparse.rst:437 -msgid "" -"Arguments read from a file must be one per line by default (but see also :" -"meth:`~ArgumentParser.convert_arg_line_to_args`) and are treated as if they " -"were in the same place as the original file referencing argument on the " -"command line. So in the example above, the expression ``['-f', 'foo', " -"'@args.txt']`` is considered equivalent to the expression ``['-f', 'foo', '-" -"f', 'bar']``." -msgstr "" - -#: ../../library/argparse.rst:445 -msgid "" -"Empty lines are treated as empty strings (``''``), which are allowed as " -"values but not as arguments. Empty lines that are read as arguments will " -"result in an \"unrecognized arguments\" error." -msgstr "" - -#: ../../library/argparse.rst:449 -msgid "" -":class:`ArgumentParser` uses :term:`filesystem encoding and error handler` " -"to read the file containing arguments." -msgstr "" - -#: ../../library/argparse.rst:452 -msgid "" -"The ``fromfile_prefix_chars=`` argument defaults to ``None``, meaning that " -"arguments will never be treated as file references." -msgstr "" - -#: ../../library/argparse.rst:455 -msgid "" -":class:`ArgumentParser` changed encoding and errors to read arguments files " -"from default (e.g. :func:`locale.getpreferredencoding(False) ` and ``\"strict\"``) to the :term:`filesystem encoding " -"and error handler`. Arguments file should be encoded in UTF-8 instead of " -"ANSI Codepage on Windows." -msgstr "" - -#: ../../library/argparse.rst:463 -msgid "argument_default" -msgstr "argument_default" - -#: ../../library/argparse.rst:465 -msgid "" -"Generally, argument defaults are specified either by passing a default to :" -"meth:`~ArgumentParser.add_argument` or by calling the :meth:`~ArgumentParser." -"set_defaults` methods with a specific set of name-value pairs. Sometimes " -"however, it may be useful to specify a single parser-wide default for " -"arguments. This can be accomplished by passing the ``argument_default=`` " -"keyword argument to :class:`ArgumentParser`. For example, to globally " -"suppress attribute creation on :meth:`~ArgumentParser.parse_args` calls, we " -"supply ``argument_default=SUPPRESS``::" -msgstr "" - -#: ../../library/argparse.rst:474 -msgid "" -">>> parser = argparse.ArgumentParser(argument_default=argparse.SUPPRESS)\n" -">>> parser.add_argument('--foo')\n" -">>> parser.add_argument('bar', nargs='?')\n" -">>> parser.parse_args(['--foo', '1', 'BAR'])\n" -"Namespace(bar='BAR', foo='1')\n" -">>> parser.parse_args([])\n" -"Namespace()" -msgstr "" -">>> parser = argparse.ArgumentParser(argument_default=argparse.SUPPRESS)\n" -">>> parser.add_argument('--foo')\n" -">>> parser.add_argument('bar', nargs='?')\n" -">>> parser.parse_args(['--foo', '1', 'BAR'])\n" -"Namespace(bar='BAR', foo='1')\n" -">>> parser.parse_args([])\n" -"Namespace()" - -#: ../../library/argparse.rst:485 -msgid "allow_abbrev" -msgstr "allow_abbrev" - -#: ../../library/argparse.rst:487 -msgid "" -"Normally, when you pass an argument list to the :meth:`~ArgumentParser." -"parse_args` method of an :class:`ArgumentParser`, it :ref:`recognizes " -"abbreviations ` of long options." -msgstr "" - -#: ../../library/argparse.rst:491 -msgid "This feature can be disabled by setting ``allow_abbrev`` to ``False``::" -msgstr "" - -#: ../../library/argparse.rst:493 -msgid "" -">>> parser = argparse.ArgumentParser(prog='PROG', allow_abbrev=False)\n" -">>> parser.add_argument('--foobar', action='store_true')\n" -">>> parser.add_argument('--foonley', action='store_false')\n" -">>> parser.parse_args(['--foon'])\n" -"usage: PROG [-h] [--foobar] [--foonley]\n" -"PROG: error: unrecognized arguments: --foon" -msgstr "" -">>> parser = argparse.ArgumentParser(prog='PROG', allow_abbrev=False)\n" -">>> parser.add_argument('--foobar', action='store_true')\n" -">>> parser.add_argument('--foonley', action='store_false')\n" -">>> parser.parse_args(['--foon'])\n" -"usage: PROG [-h] [--foobar] [--foonley]\n" -"PROG: error: unrecognized arguments: --foon" - -#: ../../library/argparse.rst:504 -msgid "conflict_handler" -msgstr "conflict_handler" - -#: ../../library/argparse.rst:506 -msgid "" -":class:`ArgumentParser` objects do not allow two actions with the same " -"option string. By default, :class:`ArgumentParser` objects raise an " -"exception if an attempt is made to create an argument with an option string " -"that is already in use::" -msgstr "" - -#: ../../library/argparse.rst:511 -msgid "" -">>> parser = argparse.ArgumentParser(prog='PROG')\n" -">>> parser.add_argument('-f', '--foo', help='old foo help')\n" -">>> parser.add_argument('--foo', help='new foo help')\n" -"Traceback (most recent call last):\n" -" ..\n" -"ArgumentError: argument --foo: conflicting option string(s): --foo" -msgstr "" -">>> parser = argparse.ArgumentParser(prog='PROG')\n" -">>> parser.add_argument('-f', '--foo', help='old foo help')\n" -">>> parser.add_argument('--foo', help='new foo help')\n" -"Traceback (most recent call last):\n" -" ..\n" -"ArgumentError: argument --foo: conflicting option string(s): --foo" - -#: ../../library/argparse.rst:518 -msgid "" -"Sometimes (e.g. when using parents_) it may be useful to simply override any " -"older arguments with the same option string. To get this behavior, the " -"value ``'resolve'`` can be supplied to the ``conflict_handler=`` argument " -"of :class:`ArgumentParser`::" -msgstr "" - -#: ../../library/argparse.rst:523 -msgid "" -">>> parser = argparse.ArgumentParser(prog='PROG', " -"conflict_handler='resolve')\n" -">>> parser.add_argument('-f', '--foo', help='old foo help')\n" -">>> parser.add_argument('--foo', help='new foo help')\n" -">>> parser.print_help()\n" -"usage: PROG [-h] [-f FOO] [--foo FOO]\n" -"\n" -"options:\n" -" -h, --help show this help message and exit\n" -" -f FOO old foo help\n" -" --foo FOO new foo help" -msgstr "" -">>> parser = argparse.ArgumentParser(prog='PROG', " -"conflict_handler='resolve')\n" -">>> parser.add_argument('-f', '--foo', help='old foo help')\n" -">>> parser.add_argument('--foo', help='new foo help')\n" -">>> parser.print_help()\n" -"usage: PROG [-h] [-f FOO] [--foo FOO]\n" -"\n" -"options:\n" -" -h, --help show this help message and exit\n" -" -f FOO old foo help\n" -" --foo FOO new foo help" - -#: ../../library/argparse.rst:534 -msgid "" -"Note that :class:`ArgumentParser` objects only remove an action if all of " -"its option strings are overridden. So, in the example above, the old ``-f/--" -"foo`` action is retained as the ``-f`` action, because only the ``--foo`` " -"option string was overridden." -msgstr "" - -#: ../../library/argparse.rst:541 -msgid "add_help" -msgstr "add_help" - -#: ../../library/argparse.rst:543 -msgid "" -"By default, :class:`ArgumentParser` objects add an option which simply " -"displays the parser's help message. If ``-h`` or ``--help`` is supplied at " -"the command line, the :class:`!ArgumentParser` help will be printed." -msgstr "" - -#: ../../library/argparse.rst:547 -msgid "" -"Occasionally, it may be useful to disable the addition of this help option. " -"This can be achieved by passing ``False`` as the ``add_help=`` argument to :" -"class:`ArgumentParser`::" -msgstr "" - -#: ../../library/argparse.rst:551 -msgid "" -">>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)\n" -">>> parser.add_argument('--foo', help='foo help')\n" -">>> parser.print_help()\n" -"usage: PROG [--foo FOO]\n" -"\n" -"options:\n" -" --foo FOO foo help" -msgstr "" -">>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)\n" -">>> parser.add_argument('--foo', help='foo help')\n" -">>> parser.print_help()\n" -"usage: PROG [--foo FOO]\n" -"\n" -"options:\n" -" --foo FOO foo help" - -#: ../../library/argparse.rst:559 -msgid "" -"The help option is typically ``-h/--help``. The exception to this is if the " -"``prefix_chars=`` is specified and does not include ``-``, in which case ``-" -"h`` and ``--help`` are not valid options. In this case, the first character " -"in ``prefix_chars`` is used to prefix the help options::" -msgstr "" - -#: ../../library/argparse.rst:565 -msgid "" -">>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='+/')\n" -">>> parser.print_help()\n" -"usage: PROG [+h]\n" -"\n" -"options:\n" -" +h, ++help show this help message and exit" -msgstr "" -">>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='+/')\n" -">>> parser.print_help()\n" -"usage: PROG [+h]\n" -"\n" -"options:\n" -" +h, ++help show this help message and exit" - -#: ../../library/argparse.rst:574 -msgid "exit_on_error" -msgstr "exit_on_error" - -#: ../../library/argparse.rst:576 -msgid "" -"Normally, when you pass an invalid argument list to the :meth:" -"`~ArgumentParser.parse_args` method of an :class:`ArgumentParser`, it will " -"print a *message* to :data:`sys.stderr` and exit with a status code of 2." -msgstr "" - -#: ../../library/argparse.rst:580 -msgid "" -"If the user would like to catch errors manually, the feature can be enabled " -"by setting ``exit_on_error`` to ``False``::" -msgstr "" - -#: ../../library/argparse.rst:583 -msgid "" -">>> parser = argparse.ArgumentParser(exit_on_error=False)\n" -">>> parser.add_argument('--integers', type=int)\n" -"_StoreAction(option_strings=['--integers'], dest='integers', nargs=None, " -"const=None, default=None, type=, choices=None, help=None, " -"metavar=None)\n" -">>> try:\n" -"... parser.parse_args('--integers a'.split())\n" -"... except argparse.ArgumentError:\n" -"... print('Catching an argumentError')\n" -"...\n" -"Catching an argumentError" -msgstr "" -">>> parser = argparse.ArgumentParser(exit_on_error=False)\n" -">>> parser.add_argument('--integers', type=int)\n" -"_StoreAction(option_strings=['--integers'], dest='integers', nargs=None, " -"const=None, default=None, type=, choices=None, help=None, " -"metavar=None)\n" -">>> try:\n" -"... parser.parse_args('--integers a'.split())\n" -"... except argparse.ArgumentError:\n" -"... print('Catching an argumentError')\n" -"...\n" -"Catching an argumentError" - -#: ../../library/argparse.rst:596 -msgid "suggest_on_error" -msgstr "suggest_on_error" - -#: ../../library/argparse.rst:598 -msgid "" -"By default, when a user passes an invalid argument choice or subparser " -"name, :class:`ArgumentParser` will exit with error info and list the " -"permissible argument choices (if specified) or subparser names as part of " -"the error message." -msgstr "" - -#: ../../library/argparse.rst:602 -msgid "" -"If the user would like to enable suggestions for mistyped argument choices " -"and subparser names, the feature can be enabled by setting " -"``suggest_on_error`` to ``True``. Note that this only applies for arguments " -"when the choices specified are strings::" -msgstr "" - -#: ../../library/argparse.rst:607 -msgid "" -">>> parser = argparse.ArgumentParser(description='Process some integers.',\n" -" suggest_on_error=True)\n" -">>> parser.add_argument('--action', choices=['sum', 'max'])\n" -">>> parser.add_argument('integers', metavar='N', type=int, nargs='+',\n" -"... help='an integer for the accumulator')\n" -">>> parser.parse_args(['--action', 'sumn', 1, 2, 3])\n" -"tester.py: error: argument --action: invalid choice: 'sumn', maybe you meant " -"'sum'? (choose from 'sum', 'max')" -msgstr "" -">>> parser = argparse.ArgumentParser(description='Process some integers.',\n" -" suggest_on_error=True)\n" -">>> parser.add_argument('--action', choices=['sum', 'max'])\n" -">>> parser.add_argument('integers', metavar='N', type=int, nargs='+',\n" -"... help='an integer for the accumulator')\n" -">>> parser.parse_args(['--action', 'sumn', 1, 2, 3])\n" -"tester.py: error: argument --action: invalid choice: 'sumn', maybe you meant " -"'sum'? (choose from 'sum', 'max')" - -#: ../../library/argparse.rst:615 -msgid "" -"If you're writing code that needs to be compatible with older Python " -"versions and want to opportunistically use ``suggest_on_error`` when it's " -"available, you can set it as an attribute after initializing the parser " -"instead of using the keyword argument::" -msgstr "" - -#: ../../library/argparse.rst:620 -msgid "" -">>> parser = argparse.ArgumentParser(description='Process some integers.')\n" -">>> parser.suggest_on_error = True" -msgstr "" -">>> parser = argparse.ArgumentParser(description='Process some integers.')\n" -">>> parser.suggest_on_error = True" - -#: ../../library/argparse.rst:627 -msgid "color" -msgstr "" - -#: ../../library/argparse.rst:629 -msgid "" -"By default, the help message is printed in color using `ANSI escape " -"sequences `__. If you want " -"plain text help messages, you can disable this :ref:`in your local " -"environment `, or in the argument parser itself " -"by setting ``color`` to ``False``::" -msgstr "" - -#: ../../library/argparse.rst:635 -msgid "" -">>> parser = argparse.ArgumentParser(description='Process some integers.',\n" -"... color=False)\n" -">>> parser.add_argument('--action', choices=['sum', 'max'])\n" -">>> parser.add_argument('integers', metavar='N', type=int, nargs='+',\n" -"... help='an integer for the accumulator')\n" -">>> parser.parse_args(['--help'])" -msgstr "" -">>> parser = argparse.ArgumentParser(description='Process some integers.',\n" -"... color=False)\n" -">>> parser.add_argument('--action', choices=['sum', 'max'])\n" -">>> parser.add_argument('integers', metavar='N', type=int, nargs='+',\n" -"... help='an integer for the accumulator')\n" -">>> parser.parse_args(['--help'])" - -#: ../../library/argparse.rst:642 -msgid "" -"Note that when ``color=True``, colored output depends on both environment " -"variables and terminal capabilities. However, if ``color=False``, colored " -"output is always disabled, even if environment variables like " -"``FORCE_COLOR`` are set." -msgstr "" - -#: ../../library/argparse.rst:649 -msgid "" -"Error messages will include color codes when redirecting stderr to a file. " -"To avoid this, set the |NO_COLOR|_ or :envvar:`PYTHON_COLORS` environment " -"variable (for example, ``NO_COLOR=1 python script.py 2> errors.txt``)." -msgstr "" - -#: ../../library/argparse.rst:658 -msgid "The add_argument() method" -msgstr "add_argument() 方法" - -#: ../../library/argparse.rst:664 -msgid "" -"Define how a single command-line argument should be parsed. Each parameter " -"has its own more detailed description below, but in short they are:" -msgstr "" - -#: ../../library/argparse.rst:667 -msgid "" -"`name or flags`_ - Either a name or a list of option strings, e.g. ``'foo'`` " -"or ``'-f', '--foo'``." -msgstr "" - -#: ../../library/argparse.rst:670 -msgid "" -"action_ - The basic type of action to be taken when this argument is " -"encountered at the command line." -msgstr "" - -#: ../../library/argparse.rst:673 -msgid "nargs_ - The number of command-line arguments that should be consumed." -msgstr "" - -#: ../../library/argparse.rst:675 -msgid "" -"const_ - A constant value required by some action_ and nargs_ selections." -msgstr "" - -#: ../../library/argparse.rst:677 -msgid "" -"default_ - The value produced if the argument is absent from the command " -"line and if it is absent from the namespace object." -msgstr "" - -#: ../../library/argparse.rst:680 -msgid "" -"type_ - The type to which the command-line argument should be converted." -msgstr "" - -#: ../../library/argparse.rst:682 -msgid "choices_ - A sequence of the allowable values for the argument." -msgstr "" - -#: ../../library/argparse.rst:684 -msgid "" -"required_ - Whether or not the command-line option may be omitted (optionals " -"only)." -msgstr "" - -#: ../../library/argparse.rst:687 -msgid "help_ - A brief description of what the argument does." -msgstr "" - -#: ../../library/argparse.rst:689 -msgid "metavar_ - A name for the argument in usage messages." -msgstr "" - -#: ../../library/argparse.rst:691 -msgid "" -"dest_ - The name of the attribute to be added to the object returned by :" -"meth:`parse_args`." -msgstr "" - -#: ../../library/argparse.rst:694 -msgid "deprecated_ - Whether or not use of the argument is deprecated." -msgstr "" - -#: ../../library/argparse.rst:702 -msgid "name or flags" -msgstr "name or flags" - -#: ../../library/argparse.rst:704 -msgid "" -"The :meth:`~ArgumentParser.add_argument` method must know whether an " -"optional argument, like ``-f`` or ``--foo``, or a positional argument, like " -"a list of filenames, is expected. The first arguments passed to :meth:" -"`~ArgumentParser.add_argument` must therefore be either a series of flags, " -"or a simple argument name." -msgstr "" - -#: ../../library/argparse.rst:710 -msgid "For example, an optional argument could be created like::" -msgstr "" - -#: ../../library/argparse.rst:712 -msgid ">>> parser.add_argument('-f', '--foo')" -msgstr ">>> parser.add_argument('-f', '--foo')" - -#: ../../library/argparse.rst:714 -msgid "while a positional argument could be created like::" -msgstr "" - -#: ../../library/argparse.rst:716 -msgid ">>> parser.add_argument('bar')" -msgstr ">>> parser.add_argument('bar')" - -#: ../../library/argparse.rst:718 -msgid "" -"When :meth:`~ArgumentParser.parse_args` is called, optional arguments will " -"be identified by the ``-`` prefix, and the remaining arguments will be " -"assumed to be positional::" -msgstr "" - -#: ../../library/argparse.rst:722 -msgid "" -">>> parser = argparse.ArgumentParser(prog='PROG')\n" -">>> parser.add_argument('-f', '--foo')\n" -">>> parser.add_argument('bar')\n" -">>> parser.parse_args(['BAR'])\n" -"Namespace(bar='BAR', foo=None)\n" -">>> parser.parse_args(['BAR', '--foo', 'FOO'])\n" -"Namespace(bar='BAR', foo='FOO')\n" -">>> parser.parse_args(['--foo', 'FOO'])\n" -"usage: PROG [-h] [-f FOO] bar\n" -"PROG: error: the following arguments are required: bar" -msgstr "" -">>> parser = argparse.ArgumentParser(prog='PROG')\n" -">>> parser.add_argument('-f', '--foo')\n" -">>> parser.add_argument('bar')\n" -">>> parser.parse_args(['BAR'])\n" -"Namespace(bar='BAR', foo=None)\n" -">>> parser.parse_args(['BAR', '--foo', 'FOO'])\n" -"Namespace(bar='BAR', foo='FOO')\n" -">>> parser.parse_args(['--foo', 'FOO'])\n" -"usage: PROG [-h] [-f FOO] bar\n" -"PROG: error: the following arguments are required: bar" - -#: ../../library/argparse.rst:733 -msgid "" -"By default, :mod:`!argparse` automatically handles the internal naming and " -"display names of arguments, simplifying the process without requiring " -"additional configuration. As such, you do not need to specify the dest_ and " -"metavar_ parameters. The dest_ parameter defaults to the argument name with " -"underscores ``_`` replacing hyphens ``-`` . The metavar_ parameter defaults " -"to the upper-cased name. For example::" -msgstr "" - -#: ../../library/argparse.rst:741 -msgid "" -">>> parser = argparse.ArgumentParser(prog='PROG')\n" -">>> parser.add_argument('--foo-bar')\n" -">>> parser.parse_args(['--foo-bar', 'FOO-BAR'])\n" -"Namespace(foo_bar='FOO-BAR')\n" -">>> parser.print_help()\n" -"usage: [-h] [--foo-bar FOO-BAR]\n" -"\n" -"optional arguments:\n" -" -h, --help show this help message and exit\n" -" --foo-bar FOO-BAR" -msgstr "" -">>> parser = argparse.ArgumentParser(prog='PROG')\n" -">>> parser.add_argument('--foo-bar')\n" -">>> parser.parse_args(['--foo-bar', 'FOO-BAR'])\n" -"Namespace(foo_bar='FOO-BAR')\n" -">>> parser.print_help()\n" -"usage: [-h] [--foo-bar FOO-BAR]\n" -"\n" -"optional arguments:\n" -" -h, --help show this help message and exit\n" -" --foo-bar FOO-BAR" - -#: ../../library/argparse.rst:756 -msgid "action" -msgstr "action" - -#: ../../library/argparse.rst:758 -msgid "" -":class:`ArgumentParser` objects associate command-line arguments with " -"actions. These actions can do just about anything with the command-line " -"arguments associated with them, though most actions simply add an attribute " -"to the object returned by :meth:`~ArgumentParser.parse_args`. The " -"``action`` keyword argument specifies how the command-line arguments should " -"be handled. The supplied actions are:" -msgstr "" - -#: ../../library/argparse.rst:764 -msgid "" -"``'store'`` - This just stores the argument's value. This is the default " -"action." -msgstr "" - -#: ../../library/argparse.rst:767 -msgid "" -"``'store_const'`` - This stores the value specified by the const_ keyword " -"argument; note that the const_ keyword argument defaults to ``None``. The " -"``'store_const'`` action is most commonly used with optional arguments that " -"specify some sort of flag. For example::" -msgstr "" - -#: ../../library/argparse.rst:772 -msgid "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('--foo', action='store_const', const=42)\n" -">>> parser.parse_args(['--foo'])\n" -"Namespace(foo=42)" -msgstr "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('--foo', action='store_const', const=42)\n" -">>> parser.parse_args(['--foo'])\n" -"Namespace(foo=42)" - -#: ../../library/argparse.rst:777 -msgid "" -"``'store_true'`` and ``'store_false'`` - These are special cases of " -"``'store_const'`` that respectively store the values ``True`` and ``False`` " -"with default values of ``False`` and ``True``::" -msgstr "" - -#: ../../library/argparse.rst:782 -msgid "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('--foo', action='store_true')\n" -">>> parser.add_argument('--bar', action='store_false')\n" -">>> parser.add_argument('--baz', action='store_false')\n" -">>> parser.parse_args('--foo --bar'.split())\n" -"Namespace(foo=True, bar=False, baz=True)" -msgstr "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('--foo', action='store_true')\n" -">>> parser.add_argument('--bar', action='store_false')\n" -">>> parser.add_argument('--baz', action='store_false')\n" -">>> parser.parse_args('--foo --bar'.split())\n" -"Namespace(foo=True, bar=False, baz=True)" - -#: ../../library/argparse.rst:789 -msgid "" -"``'append'`` - This appends each argument value to a list. It is useful for " -"allowing an option to be specified multiple times. If the default value is a " -"non-empty list, the parsed value will start with the default list's elements " -"and any values from the command line will be appended after those default " -"values. Example usage::" -msgstr "" - -#: ../../library/argparse.rst:795 -msgid "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('--foo', action='append', default=['0'])\n" -">>> parser.parse_args('--foo 1 --foo 2'.split())\n" -"Namespace(foo=['0', '1', '2'])" -msgstr "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('--foo', action='append', default=['0'])\n" -">>> parser.parse_args('--foo 1 --foo 2'.split())\n" -"Namespace(foo=['0', '1', '2'])" - -#: ../../library/argparse.rst:800 -msgid "" -"``'append_const'`` - This appends the value specified by the const_ keyword " -"argument to a list; note that the const_ keyword argument defaults to " -"``None``. The ``'append_const'`` action is typically useful when multiple " -"arguments need to store constants to the same list. For example::" -msgstr "" - -#: ../../library/argparse.rst:806 -msgid "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('--str', dest='types', action='append_const', " -"const=str)\n" -">>> parser.add_argument('--int', dest='types', action='append_const', " -"const=int)\n" -">>> parser.parse_args('--str --int'.split())\n" -"Namespace(types=[, ])" -msgstr "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('--str', dest='types', action='append_const', " -"const=str)\n" -">>> parser.add_argument('--int', dest='types', action='append_const', " -"const=int)\n" -">>> parser.parse_args('--str --int'.split())\n" -"Namespace(types=[, ])" - -#: ../../library/argparse.rst:812 -msgid "" -"``'extend'`` - This appends each item from a multi-value argument to a list. " -"The ``'extend'`` action is typically used with the nargs_ keyword argument " -"value ``'+'`` or ``'*'``. Note that when nargs_ is ``None`` (the default) or " -"``'?'``, each character of the argument string will be appended to the list. " -"Example usage::" -msgstr "" - -#: ../../library/argparse.rst:820 -msgid "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument(\"--foo\", action=\"extend\", nargs=\"+\", " -"type=str)\n" -">>> parser.parse_args([\"--foo\", \"f1\", \"--foo\", \"f2\", \"f3\", " -"\"f4\"])\n" -"Namespace(foo=['f1', 'f2', 'f3', 'f4'])" -msgstr "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument(\"--foo\", action=\"extend\", nargs=\"+\", " -"type=str)\n" -">>> parser.parse_args([\"--foo\", \"f1\", \"--foo\", \"f2\", \"f3\", " -"\"f4\"])\n" -"Namespace(foo=['f1', 'f2', 'f3', 'f4'])" - -#: ../../library/argparse.rst:827 -msgid "" -"``'count'`` - This counts the number of times an argument occurs. For " -"example, this is useful for increasing verbosity levels::" -msgstr "" - -#: ../../library/argparse.rst:830 -msgid "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('--verbose', '-v', action='count', default=0)\n" -">>> parser.parse_args(['-vvv'])\n" -"Namespace(verbose=3)" -msgstr "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('--verbose', '-v', action='count', default=0)\n" -">>> parser.parse_args(['-vvv'])\n" -"Namespace(verbose=3)" - -#: ../../library/argparse.rst:835 -msgid "Note, the *default* will be ``None`` unless explicitly set to *0*." -msgstr "" - -#: ../../library/argparse.rst:837 -msgid "" -"``'help'`` - This prints a complete help message for all the options in the " -"current parser and then exits. By default a help action is automatically " -"added to the parser. See :class:`ArgumentParser` for details of how the " -"output is created." -msgstr "" - -#: ../../library/argparse.rst:842 -msgid "" -"``'version'`` - This expects a ``version=`` keyword argument in the :meth:" -"`~ArgumentParser.add_argument` call, and prints version information and " -"exits when invoked::" -msgstr "" - -#: ../../library/argparse.rst:846 -msgid "" -">>> import argparse\n" -">>> parser = argparse.ArgumentParser(prog='PROG')\n" -">>> parser.add_argument('--version', action='version', version='%(prog)s " -"2.0')\n" -">>> parser.parse_args(['--version'])\n" -"PROG 2.0" -msgstr "" -">>> import argparse\n" -">>> parser = argparse.ArgumentParser(prog='PROG')\n" -">>> parser.add_argument('--version', action='version', version='%(prog)s " -"2.0')\n" -">>> parser.parse_args(['--version'])\n" -"PROG 2.0" - -#: ../../library/argparse.rst:852 -msgid "" -"You may also specify an arbitrary action by passing an :class:`Action` " -"subclass (e.g. :class:`BooleanOptionalAction`) or other object that " -"implements the same interface. Only actions that consume command-line " -"arguments (e.g. ``'store'``, ``'append'``, ``'extend'``, or custom actions " -"with non-zero ``nargs``) can be used with positional arguments." -msgstr "" -"你也可以傳遞一個 :class:`Action` 子類別（例如 :class:" -"`BooleanOptionalAction`）或實作相同介面的其他物件。只有會消耗命令列引數的 " -"action（例如 ``'store'``、``'append'``、``'extend'`` 或 ``nargs`` 不為零的自" -"定義 action）可以被用於位置引數。" - -#: ../../library/argparse.rst:858 -msgid "" -"The recommended way to create a custom action is to extend :class:`Action`, " -"overriding the :meth:`!__call__` method and optionally the :meth:`!__init__` " -"and :meth:`!format_usage` methods. You can also register custom actions " -"using the :meth:`~ArgumentParser.register` method and reference them by " -"their registered name." -msgstr "" - -#: ../../library/argparse.rst:863 -msgid "An example of a custom action::" -msgstr "自訂 action 的範例： ::" - -#: ../../library/argparse.rst:865 -msgid "" -">>> class FooAction(argparse.Action):\n" -"... def __init__(self, option_strings, dest, nargs=None, **kwargs):\n" -"... if nargs is not None:\n" -"... raise ValueError(\"nargs not allowed\")\n" -"... super().__init__(option_strings, dest, **kwargs)\n" -"... def __call__(self, parser, namespace, values, option_string=None):\n" -"... print('%r %r %r' % (namespace, values, option_string))\n" -"... setattr(namespace, self.dest, values)\n" -"...\n" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('--foo', action=FooAction)\n" -">>> parser.add_argument('bar', action=FooAction)\n" -">>> args = parser.parse_args('1 --foo 2'.split())\n" -"Namespace(bar=None, foo=None) '1' None\n" -"Namespace(bar='1', foo=None) '2' '--foo'\n" -">>> args\n" -"Namespace(bar='1', foo='2')" -msgstr "" -">>> class FooAction(argparse.Action):\n" -"... def __init__(self, option_strings, dest, nargs=None, **kwargs):\n" -"... if nargs is not None:\n" -"... raise ValueError(\"nargs not allowed\")\n" -"... super().__init__(option_strings, dest, **kwargs)\n" -"... def __call__(self, parser, namespace, values, option_string=None):\n" -"... print('%r %r %r' % (namespace, values, option_string))\n" -"... setattr(namespace, self.dest, values)\n" -"...\n" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('--foo', action=FooAction)\n" -">>> parser.add_argument('bar', action=FooAction)\n" -">>> args = parser.parse_args('1 --foo 2'.split())\n" -"Namespace(bar=None, foo=None) '1' None\n" -"Namespace(bar='1', foo=None) '2' '--foo'\n" -">>> args\n" -"Namespace(bar='1', foo='2')" - -#: ../../library/argparse.rst:883 -msgid "For more details, see :class:`Action`." -msgstr "更多詳情請見 :class:`Action`。" - -#: ../../library/argparse.rst:889 -msgid "nargs" -msgstr "nargs" - -#: ../../library/argparse.rst:891 -msgid "" -":class:`ArgumentParser` objects usually associate a single command-line " -"argument with a single action to be taken. The ``nargs`` keyword argument " -"associates a different number of command-line arguments with a single " -"action. See also :ref:`specifying-ambiguous-arguments`. The supported values " -"are:" -msgstr "" - -#: ../../library/argparse.rst:896 -msgid "" -"``N`` (an integer). ``N`` arguments from the command line will be gathered " -"together into a list. For example::" -msgstr "" - -#: ../../library/argparse.rst:899 -msgid "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('--foo', nargs=2)\n" -">>> parser.add_argument('bar', nargs=1)\n" -">>> parser.parse_args('c --foo a b'.split())\n" -"Namespace(bar=['c'], foo=['a', 'b'])" -msgstr "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('--foo', nargs=2)\n" -">>> parser.add_argument('bar', nargs=1)\n" -">>> parser.parse_args('c --foo a b'.split())\n" -"Namespace(bar=['c'], foo=['a', 'b'])" - -#: ../../library/argparse.rst:905 -msgid "" -"Note that ``nargs=1`` produces a list of one item. This is different from " -"the default, in which the item is produced by itself." -msgstr "" - -#: ../../library/argparse.rst:910 -msgid "" -"``'?'``. One argument will be consumed from the command line if possible, " -"and produced as a single item. If no command-line argument is present, the " -"value from default_ will be produced. Note that for optional arguments, " -"there is an additional case - the option string is present but not followed " -"by a command-line argument. In this case the value from const_ will be " -"produced. Some examples to illustrate this::" -msgstr "" - -#: ../../library/argparse.rst:917 -msgid "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('--foo', nargs='?', const='c', default='d')\n" -">>> parser.add_argument('bar', nargs='?', default='d')\n" -">>> parser.parse_args(['XX', '--foo', 'YY'])\n" -"Namespace(bar='XX', foo='YY')\n" -">>> parser.parse_args(['XX', '--foo'])\n" -"Namespace(bar='XX', foo='c')\n" -">>> parser.parse_args([])\n" -"Namespace(bar='d', foo='d')" -msgstr "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('--foo', nargs='?', const='c', default='d')\n" -">>> parser.add_argument('bar', nargs='?', default='d')\n" -">>> parser.parse_args(['XX', '--foo', 'YY'])\n" -"Namespace(bar='XX', foo='YY')\n" -">>> parser.parse_args(['XX', '--foo'])\n" -"Namespace(bar='XX', foo='c')\n" -">>> parser.parse_args([])\n" -"Namespace(bar='d', foo='d')" - -#: ../../library/argparse.rst:927 -msgid "" -"One of the more common uses of ``nargs='?'`` is to allow optional input and " -"output files::" -msgstr "" - -#: ../../library/argparse.rst:930 -msgid "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('infile', nargs='?')\n" -">>> parser.add_argument('outfile', nargs='?')\n" -">>> parser.parse_args(['input.txt', 'output.txt'])\n" -"Namespace(infile='input.txt', outfile='output.txt')\n" -">>> parser.parse_args(['input.txt'])\n" -"Namespace(infile='input.txt', outfile=None)\n" -">>> parser.parse_args([])\n" -"Namespace(infile=None, outfile=None)" -msgstr "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('infile', nargs='?')\n" -">>> parser.add_argument('outfile', nargs='?')\n" -">>> parser.parse_args(['input.txt', 'output.txt'])\n" -"Namespace(infile='input.txt', outfile='output.txt')\n" -">>> parser.parse_args(['input.txt'])\n" -"Namespace(infile='input.txt', outfile=None)\n" -">>> parser.parse_args([])\n" -"Namespace(infile=None, outfile=None)" - -#: ../../library/argparse.rst:942 -msgid "" -"``'*'``. All command-line arguments present are gathered into a list. Note " -"that it generally doesn't make much sense to have more than one positional " -"argument with ``nargs='*'``, but multiple optional arguments with " -"``nargs='*'`` is possible. For example::" -msgstr "" - -#: ../../library/argparse.rst:947 -msgid "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('--foo', nargs='*')\n" -">>> parser.add_argument('--bar', nargs='*')\n" -">>> parser.add_argument('baz', nargs='*')\n" -">>> parser.parse_args('a b --foo x y --bar 1 2'.split())\n" -"Namespace(bar=['1', '2'], baz=['a', 'b'], foo=['x', 'y'])" -msgstr "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('--foo', nargs='*')\n" -">>> parser.add_argument('--bar', nargs='*')\n" -">>> parser.add_argument('baz', nargs='*')\n" -">>> parser.parse_args('a b --foo x y --bar 1 2'.split())\n" -"Namespace(bar=['1', '2'], baz=['a', 'b'], foo=['x', 'y'])" - -#: ../../library/argparse.rst:956 -msgid "" -"``'+'``. Just like ``'*'``, all command-line arguments present are gathered " -"into a list. Additionally, an error message will be generated if there " -"wasn't at least one command-line argument present. For example::" -msgstr "" - -#: ../../library/argparse.rst:960 -msgid "" -">>> parser = argparse.ArgumentParser(prog='PROG')\n" -">>> parser.add_argument('foo', nargs='+')\n" -">>> parser.parse_args(['a', 'b'])\n" -"Namespace(foo=['a', 'b'])\n" -">>> parser.parse_args([])\n" -"usage: PROG [-h] foo [foo ...]\n" -"PROG: error: the following arguments are required: foo" -msgstr "" -">>> parser = argparse.ArgumentParser(prog='PROG')\n" -">>> parser.add_argument('foo', nargs='+')\n" -">>> parser.parse_args(['a', 'b'])\n" -"Namespace(foo=['a', 'b'])\n" -">>> parser.parse_args([])\n" -"usage: PROG [-h] foo [foo ...]\n" -"PROG: error: the following arguments are required: foo" - -#: ../../library/argparse.rst:968 -msgid "" -"If the ``nargs`` keyword argument is not provided, the number of arguments " -"consumed is determined by the action_. Generally this means a single " -"command-line argument will be consumed and a single item (not a list) will " -"be produced. Actions that do not consume command-line arguments (e.g. " -"``'store_const'``) set ``nargs=0``." -msgstr "" - -#: ../../library/argparse.rst:978 -msgid "const" -msgstr "const" - -#: ../../library/argparse.rst:980 -msgid "" -"The ``const`` argument of :meth:`~ArgumentParser.add_argument` is used to " -"hold constant values that are not read from the command line but are " -"required for the various :class:`ArgumentParser` actions. The two most " -"common uses of it are:" -msgstr "" - -#: ../../library/argparse.rst:984 -msgid "" -"When :meth:`~ArgumentParser.add_argument` is called with " -"``action='store_const'`` or ``action='append_const'``. These actions add " -"the ``const`` value to one of the attributes of the object returned by :meth:" -"`~ArgumentParser.parse_args`. See the action_ description for examples. If " -"``const`` is not provided to :meth:`~ArgumentParser.add_argument`, it will " -"receive a default value of ``None``." -msgstr "" - -#: ../../library/argparse.rst:992 -msgid "" -"When :meth:`~ArgumentParser.add_argument` is called with option strings " -"(like ``-f`` or ``--foo``) and ``nargs='?'``. This creates an optional " -"argument that can be followed by zero or one command-line arguments. When " -"parsing the command line, if the option string is encountered with no " -"command-line argument following it, the value from ``const`` will be used. " -"See the nargs_ description for examples." -msgstr "" - -#: ../../library/argparse.rst:999 -msgid "" -"``const=None`` by default, including when ``action='append_const'`` or " -"``action='store_const'``." -msgstr "" - -#: ../../library/argparse.rst:1006 -msgid "default" -msgstr "default" - -#: ../../library/argparse.rst:1008 -msgid "" -"All optional arguments and some positional arguments may be omitted at the " -"command line. The ``default`` keyword argument of :meth:`~ArgumentParser." -"add_argument`, whose value defaults to ``None``, specifies what value should " -"be used if the command-line argument is not present. For optional arguments, " -"the ``default`` value is used when the option string was not present at the " -"command line::" -msgstr "" - -#: ../../library/argparse.rst:1015 -msgid "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('--foo', default=42)\n" -">>> parser.parse_args(['--foo', '2'])\n" -"Namespace(foo='2')\n" -">>> parser.parse_args([])\n" -"Namespace(foo=42)" -msgstr "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('--foo', default=42)\n" -">>> parser.parse_args(['--foo', '2'])\n" -"Namespace(foo='2')\n" -">>> parser.parse_args([])\n" -"Namespace(foo=42)" - -#: ../../library/argparse.rst:1022 -msgid "" -"If the target namespace already has an attribute set, the action *default* " -"will not overwrite it::" -msgstr "" - -#: ../../library/argparse.rst:1025 -msgid "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('--foo', default=42)\n" -">>> parser.parse_args([], namespace=argparse.Namespace(foo=101))\n" -"Namespace(foo=101)" -msgstr "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('--foo', default=42)\n" -">>> parser.parse_args([], namespace=argparse.Namespace(foo=101))\n" -"Namespace(foo=101)" - -#: ../../library/argparse.rst:1030 -msgid "" -"If the ``default`` value is a string, the parser parses the value as if it " -"were a command-line argument. In particular, the parser applies any type_ " -"conversion argument, if provided, before setting the attribute on the :class:" -"`Namespace` return value. Otherwise, the parser uses the value as is::" -msgstr "" - -#: ../../library/argparse.rst:1035 -msgid "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('--length', default='10', type=int)\n" -">>> parser.add_argument('--width', default=10.5, type=int)\n" -">>> parser.parse_args()\n" -"Namespace(length=10, width=10.5)" -msgstr "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('--length', default='10', type=int)\n" -">>> parser.add_argument('--width', default=10.5, type=int)\n" -">>> parser.parse_args()\n" -"Namespace(length=10, width=10.5)" - -#: ../../library/argparse.rst:1041 -msgid "" -"For positional arguments with nargs_ equal to ``?`` or ``*``, the " -"``default`` value is used when no command-line argument was present::" -msgstr "" - -#: ../../library/argparse.rst:1044 -msgid "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('foo', nargs='?', default=42)\n" -">>> parser.parse_args(['a'])\n" -"Namespace(foo='a')\n" -">>> parser.parse_args([])\n" -"Namespace(foo=42)" -msgstr "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('foo', nargs='?', default=42)\n" -">>> parser.parse_args(['a'])\n" -"Namespace(foo='a')\n" -">>> parser.parse_args([])\n" -"Namespace(foo=42)" - -#: ../../library/argparse.rst:1051 -msgid "" -"For required_ arguments, the ``default`` value is ignored. For example, this " -"applies to positional arguments with nargs_ values other than ``?`` or " -"``*``, or optional arguments marked as ``required=True``." -msgstr "" - -#: ../../library/argparse.rst:1055 -msgid "" -"Providing ``default=argparse.SUPPRESS`` causes no attribute to be added if " -"the command-line argument was not present::" -msgstr "" - -#: ../../library/argparse.rst:1058 -msgid "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('--foo', default=argparse.SUPPRESS)\n" -">>> parser.parse_args([])\n" -"Namespace()\n" -">>> parser.parse_args(['--foo', '1'])\n" -"Namespace(foo='1')" -msgstr "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('--foo', default=argparse.SUPPRESS)\n" -">>> parser.parse_args([])\n" -"Namespace()\n" -">>> parser.parse_args(['--foo', '1'])\n" -"Namespace(foo='1')" - -#: ../../library/argparse.rst:1069 -msgid "type" -msgstr "type" - -#: ../../library/argparse.rst:1071 -msgid "" -"By default, the parser reads command-line arguments in as simple strings. " -"However, quite often the command-line string should instead be interpreted " -"as another type, such as a :class:`float` or :class:`int`. The ``type`` " -"keyword for :meth:`~ArgumentParser.add_argument` allows any necessary type-" -"checking and type conversions to be performed." -msgstr "" - -#: ../../library/argparse.rst:1077 -msgid "" -"If the type_ keyword is used with the default_ keyword, the type converter " -"is only applied if the default is a string." -msgstr "" - -#: ../../library/argparse.rst:1080 -msgid "" -"The argument to ``type`` can be a callable that accepts a single string or " -"the name of a registered type (see :meth:`~ArgumentParser.register`) If the " -"function raises :exc:`ArgumentTypeError`, :exc:`TypeError`, or :exc:" -"`ValueError`, the exception is caught and a nicely formatted error message " -"is displayed. Other exception types are not handled." -msgstr "" - -#: ../../library/argparse.rst:1086 -msgid "Common built-in types and functions can be used as type converters:" -msgstr "" - -#: ../../library/argparse.rst:1088 -msgid "" -"import argparse\n" -"import pathlib\n" -"\n" -"parser = argparse.ArgumentParser()\n" -"parser.add_argument('count', type=int)\n" -"parser.add_argument('distance', type=float)\n" -"parser.add_argument('street', type=ascii)\n" -"parser.add_argument('code_point', type=ord)\n" -"parser.add_argument('datapath', type=pathlib.Path)" -msgstr "" -"import argparse\n" -"import pathlib\n" -"\n" -"parser = argparse.ArgumentParser()\n" -"parser.add_argument('count', type=int)\n" -"parser.add_argument('distance', type=float)\n" -"parser.add_argument('street', type=ascii)\n" -"parser.add_argument('code_point', type=ord)\n" -"parser.add_argument('datapath', type=pathlib.Path)" - -#: ../../library/argparse.rst:1100 -msgid "User defined functions can be used as well:" -msgstr "" - -#: ../../library/argparse.rst:1102 -msgid "" -">>> def hyphenated(string):\n" -"... return '-'.join([word[:4] for word in string.casefold().split()])\n" -"...\n" -">>> parser = argparse.ArgumentParser()\n" -">>> _ = parser.add_argument('short_title', type=hyphenated)\n" -">>> parser.parse_args(['\"The Tale of Two Cities\"'])\n" -"Namespace(short_title='\"the-tale-of-two-citi')" -msgstr "" -">>> def hyphenated(string):\n" -"... return '-'.join([word[:4] for word in string.casefold().split()])\n" -"...\n" -">>> parser = argparse.ArgumentParser()\n" -">>> _ = parser.add_argument('short_title', type=hyphenated)\n" -">>> parser.parse_args(['\"The Tale of Two Cities\"'])\n" -"Namespace(short_title='\"the-tale-of-two-citi')" - -#: ../../library/argparse.rst:1112 -msgid "" -"The :func:`bool` function is not recommended as a type converter. All it " -"does is convert empty strings to ``False`` and non-empty strings to " -"``True``. This is usually not what is desired." -msgstr "" - -#: ../../library/argparse.rst:1116 -msgid "" -"In general, the ``type`` keyword is a convenience that should only be used " -"for simple conversions that can only raise one of the three supported " -"exceptions. Anything with more interesting error-handling or resource " -"management should be done downstream after the arguments are parsed." -msgstr "" - -#: ../../library/argparse.rst:1121 -msgid "" -"For example, JSON or YAML conversions have complex error cases that require " -"better reporting than can be given by the ``type`` keyword. A :exc:`~json." -"JSONDecodeError` would not be well formatted and a :exc:`FileNotFoundError` " -"exception would not be handled at all." -msgstr "" - -#: ../../library/argparse.rst:1126 -msgid "" -"Even :class:`~argparse.FileType` has its limitations for use with the " -"``type`` keyword. If one argument uses :class:`~argparse.FileType` and then " -"a subsequent argument fails, an error is reported but the file is not " -"automatically closed. In this case, it would be better to wait until after " -"the parser has run and then use the :keyword:`with`-statement to manage the " -"files." -msgstr "" - -#: ../../library/argparse.rst:1133 -msgid "" -"For type checkers that simply check against a fixed set of values, consider " -"using the choices_ keyword instead." -msgstr "" - -#: ../../library/argparse.rst:1140 -msgid "choices" -msgstr "choices" - -#: ../../library/argparse.rst:1142 -msgid "" -"Some command-line arguments should be selected from a restricted set of " -"values. These can be handled by passing a sequence object as the *choices* " -"keyword argument to :meth:`~ArgumentParser.add_argument`. When the command " -"line is parsed, argument values will be checked, and an error message will " -"be displayed if the argument was not one of the acceptable values::" -msgstr "" - -#: ../../library/argparse.rst:1148 -msgid "" -">>> parser = argparse.ArgumentParser(prog='game.py')\n" -">>> parser.add_argument('move', choices=['rock', 'paper', 'scissors'])\n" -">>> parser.parse_args(['rock'])\n" -"Namespace(move='rock')\n" -">>> parser.parse_args(['fire'])\n" -"usage: game.py [-h] {rock,paper,scissors}\n" -"game.py: error: argument move: invalid choice: 'fire' (choose from 'rock',\n" -"'paper', 'scissors')" -msgstr "" -">>> parser = argparse.ArgumentParser(prog='game.py')\n" -">>> parser.add_argument('move', choices=['rock', 'paper', 'scissors'])\n" -">>> parser.parse_args(['rock'])\n" -"Namespace(move='rock')\n" -">>> parser.parse_args(['fire'])\n" -"usage: game.py [-h] {rock,paper,scissors}\n" -"game.py: error: argument move: invalid choice: 'fire' (choose from 'rock',\n" -"'paper', 'scissors')" - -#: ../../library/argparse.rst:1157 -msgid "" -"Any sequence can be passed as the *choices* value, so :class:`list` " -"objects, :class:`tuple` objects, and custom sequences are all supported." -msgstr "" - -#: ../../library/argparse.rst:1160 -msgid "" -"Use of :class:`enum.Enum` is not recommended because it is difficult to " -"control its appearance in usage, help, and error messages." -msgstr "" - -#: ../../library/argparse.rst:1163 -msgid "" -"Note that *choices* are checked after any type_ conversions have been " -"performed, so objects in *choices* should match the type_ specified. This " -"can make *choices* appear unfamiliar in usage, help, or error messages." -msgstr "" - -#: ../../library/argparse.rst:1168 -msgid "" -"To keep *choices* user-friendly, consider a custom type wrapper that " -"converts and formats values, or omit type_ and handle conversion in your " -"application code." -msgstr "" - -#: ../../library/argparse.rst:1172 -msgid "" -"Formatted choices override the default *metavar* which is normally derived " -"from *dest*. This is usually what you want because the user never sees the " -"*dest* parameter. If this display isn't desirable (perhaps because there " -"are many choices), just specify an explicit metavar_." -msgstr "" - -#: ../../library/argparse.rst:1181 -msgid "required" -msgstr "required" - -#: ../../library/argparse.rst:1183 -msgid "" -"In general, the :mod:`!argparse` module assumes that flags like ``-f`` and " -"``--bar`` indicate *optional* arguments, which can always be omitted at the " -"command line. To make an option *required*, ``True`` can be specified for " -"the ``required=`` keyword argument to :meth:`~ArgumentParser.add_argument`::" -msgstr "" - -#: ../../library/argparse.rst:1188 -msgid "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('--foo', required=True)\n" -">>> parser.parse_args(['--foo', 'BAR'])\n" -"Namespace(foo='BAR')\n" -">>> parser.parse_args([])\n" -"usage: [-h] --foo FOO\n" -": error: the following arguments are required: --foo" -msgstr "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('--foo', required=True)\n" -">>> parser.parse_args(['--foo', 'BAR'])\n" -"Namespace(foo='BAR')\n" -">>> parser.parse_args([])\n" -"usage: [-h] --foo FOO\n" -": error: the following arguments are required: --foo" - -#: ../../library/argparse.rst:1196 -msgid "" -"As the example shows, if an option is marked as ``required``, :meth:" -"`~ArgumentParser.parse_args` will report an error if that option is not " -"present at the command line." -msgstr "" - -#: ../../library/argparse.rst:1202 -msgid "" -"Required options are generally considered bad form because users expect " -"*options* to be *optional*, and thus they should be avoided when possible." -msgstr "" - -#: ../../library/argparse.rst:1209 -msgid "help" -msgstr "help" - -#: ../../library/argparse.rst:1211 -msgid "" -"The ``help`` value is a string containing a brief description of the " -"argument. When a user requests help (usually by using ``-h`` or ``--help`` " -"at the command line), these ``help`` descriptions will be displayed with " -"each argument." -msgstr "" - -#: ../../library/argparse.rst:1216 -msgid "" -"The ``help`` strings can include various format specifiers to avoid " -"repetition of things like the program name or the argument default_. The " -"available specifiers include the program name, ``%(prog)s`` and most keyword " -"arguments to :meth:`~ArgumentParser.add_argument`, e.g. ``%(default)s``, " -"``%(type)s``, etc.::" -msgstr "" - -#: ../../library/argparse.rst:1221 -msgid "" -">>> parser = argparse.ArgumentParser(prog='frobble')\n" -">>> parser.add_argument('bar', nargs='?', type=int, default=42,\n" -"... help='the bar to %(prog)s (default: %(default)s)')\n" -">>> parser.print_help()\n" -"usage: frobble [-h] [bar]\n" -"\n" -"positional arguments:\n" -" bar the bar to frobble (default: 42)\n" -"\n" -"options:\n" -" -h, --help show this help message and exit" -msgstr "" -">>> parser = argparse.ArgumentParser(prog='frobble')\n" -">>> parser.add_argument('bar', nargs='?', type=int, default=42,\n" -"... help='the bar to %(prog)s (default: %(default)s)')\n" -">>> parser.print_help()\n" -"usage: frobble [-h] [bar]\n" -"\n" -"positional arguments:\n" -" bar the bar to frobble (default: 42)\n" -"\n" -"options:\n" -" -h, --help show this help message and exit" - -#: ../../library/argparse.rst:1233 -msgid "" -"As the help string supports %-formatting, if you want a literal ``%`` to " -"appear in the help string, you must escape it as ``%%``." -msgstr "" - -#: ../../library/argparse.rst:1236 -msgid "" -":mod:`!argparse` supports silencing the help entry for certain options, by " -"setting the ``help`` value to ``argparse.SUPPRESS``::" -msgstr "" - -#: ../../library/argparse.rst:1239 -msgid "" -">>> parser = argparse.ArgumentParser(prog='frobble')\n" -">>> parser.add_argument('--foo', help=argparse.SUPPRESS)\n" -">>> parser.print_help()\n" -"usage: frobble [-h]\n" -"\n" -"options:\n" -" -h, --help show this help message and exit" -msgstr "" -">>> parser = argparse.ArgumentParser(prog='frobble')\n" -">>> parser.add_argument('--foo', help=argparse.SUPPRESS)\n" -">>> parser.print_help()\n" -"usage: frobble [-h]\n" -"\n" -"options:\n" -" -h, --help show this help message and exit" - -#: ../../library/argparse.rst:1251 -msgid "metavar" -msgstr "metavar" - -#: ../../library/argparse.rst:1253 -msgid "" -"When :class:`ArgumentParser` generates help messages, it needs some way to " -"refer to each expected argument. By default, :class:`!ArgumentParser` " -"objects use the dest_ value as the \"name\" of each object. By default, for " -"positional argument actions, the dest_ value is used directly, and for " -"optional argument actions, the dest_ value is uppercased. So, a single " -"positional argument with ``dest='bar'`` will be referred to as ``bar``. A " -"single optional argument ``--foo`` that should be followed by a single " -"command-line argument will be referred to as ``FOO``. An example::" -msgstr "" - -#: ../../library/argparse.rst:1262 -msgid "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('--foo')\n" -">>> parser.add_argument('bar')\n" -">>> parser.parse_args('X --foo Y'.split())\n" -"Namespace(bar='X', foo='Y')\n" -">>> parser.print_help()\n" -"usage: [-h] [--foo FOO] bar\n" -"\n" -"positional arguments:\n" -" bar\n" -"\n" -"options:\n" -" -h, --help show this help message and exit\n" -" --foo FOO" -msgstr "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('--foo')\n" -">>> parser.add_argument('bar')\n" -">>> parser.parse_args('X --foo Y'.split())\n" -"Namespace(bar='X', foo='Y')\n" -">>> parser.print_help()\n" -"usage: [-h] [--foo FOO] bar\n" -"\n" -"positional arguments:\n" -" bar\n" -"\n" -"options:\n" -" -h, --help show this help message and exit\n" -" --foo FOO" - -#: ../../library/argparse.rst:1277 -msgid "An alternative name can be specified with ``metavar``::" -msgstr "" - -#: ../../library/argparse.rst:1279 -msgid "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('--foo', metavar='YYY')\n" -">>> parser.add_argument('bar', metavar='XXX')\n" -">>> parser.parse_args('X --foo Y'.split())\n" -"Namespace(bar='X', foo='Y')\n" -">>> parser.print_help()\n" -"usage: [-h] [--foo YYY] XXX\n" -"\n" -"positional arguments:\n" -" XXX\n" -"\n" -"options:\n" -" -h, --help show this help message and exit\n" -" --foo YYY" -msgstr "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('--foo', metavar='YYY')\n" -">>> parser.add_argument('bar', metavar='XXX')\n" -">>> parser.parse_args('X --foo Y'.split())\n" -"Namespace(bar='X', foo='Y')\n" -">>> parser.print_help()\n" -"usage: [-h] [--foo YYY] XXX\n" -"\n" -"positional arguments:\n" -" XXX\n" -"\n" -"options:\n" -" -h, --help show this help message and exit\n" -" --foo YYY" - -#: ../../library/argparse.rst:1294 -msgid "" -"Note that ``metavar`` only changes the *displayed* name - the name of the " -"attribute on the :meth:`~ArgumentParser.parse_args` object is still " -"determined by the dest_ value." -msgstr "" - -#: ../../library/argparse.rst:1298 -msgid "" -"Different values of ``nargs`` may cause the metavar to be used multiple " -"times. Providing a tuple to ``metavar`` specifies a different display for " -"each of the arguments::" -msgstr "" - -#: ../../library/argparse.rst:1302 -msgid "" -">>> parser = argparse.ArgumentParser(prog='PROG')\n" -">>> parser.add_argument('-x', nargs=2)\n" -">>> parser.add_argument('--foo', nargs=2, metavar=('bar', 'baz'))\n" -">>> parser.print_help()\n" -"usage: PROG [-h] [-x X X] [--foo bar baz]\n" -"\n" -"options:\n" -" -h, --help show this help message and exit\n" -" -x X X\n" -" --foo bar baz" -msgstr "" -">>> parser = argparse.ArgumentParser(prog='PROG')\n" -">>> parser.add_argument('-x', nargs=2)\n" -">>> parser.add_argument('--foo', nargs=2, metavar=('bar', 'baz'))\n" -">>> parser.print_help()\n" -"usage: PROG [-h] [-x X X] [--foo bar baz]\n" -"\n" -"options:\n" -" -h, --help show this help message and exit\n" -" -x X X\n" -" --foo bar baz" - -#: ../../library/argparse.rst:1317 -msgid "dest" -msgstr "dest" - -#: ../../library/argparse.rst:1319 -msgid "" -"Most :class:`ArgumentParser` actions add some value as an attribute of the " -"object returned by :meth:`~ArgumentParser.parse_args`. The name of this " -"attribute is determined by the ``dest`` keyword argument of :meth:" -"`~ArgumentParser.add_argument`. For positional argument actions, ``dest`` " -"is normally supplied as the first argument to :meth:`~ArgumentParser." -"add_argument`::" -msgstr "" - -#: ../../library/argparse.rst:1326 -msgid "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('bar')\n" -">>> parser.parse_args(['XXX'])\n" -"Namespace(bar='XXX')" -msgstr "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('bar')\n" -">>> parser.parse_args(['XXX'])\n" -"Namespace(bar='XXX')" - -#: ../../library/argparse.rst:1331 -msgid "" -"For optional argument actions, the value of ``dest`` is normally inferred " -"from the option strings. :class:`ArgumentParser` generates the value of " -"``dest`` by taking the first long option string and stripping away the " -"initial ``--`` string. If no long option strings were supplied, ``dest`` " -"will be derived from the first short option string by stripping the initial " -"``-`` character. Any internal ``-`` characters will be converted to ``_`` " -"characters to make sure the string is a valid attribute name. The examples " -"below illustrate this behavior::" -msgstr "" - -#: ../../library/argparse.rst:1340 -msgid "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('-f', '--foo-bar', '--foo')\n" -">>> parser.add_argument('-x', '-y')\n" -">>> parser.parse_args('-f 1 -x 2'.split())\n" -"Namespace(foo_bar='1', x='2')\n" -">>> parser.parse_args('--foo 1 -y 2'.split())\n" -"Namespace(foo_bar='1', x='2')" -msgstr "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('-f', '--foo-bar', '--foo')\n" -">>> parser.add_argument('-x', '-y')\n" -">>> parser.parse_args('-f 1 -x 2'.split())\n" -"Namespace(foo_bar='1', x='2')\n" -">>> parser.parse_args('--foo 1 -y 2'.split())\n" -"Namespace(foo_bar='1', x='2')" - -#: ../../library/argparse.rst:1348 -msgid "``dest`` allows a custom attribute name to be provided::" -msgstr "" - -#: ../../library/argparse.rst:1350 -msgid "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('--foo', dest='bar')\n" -">>> parser.parse_args('--foo XXX'.split())\n" -"Namespace(bar='XXX')" -msgstr "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('--foo', dest='bar')\n" -">>> parser.parse_args('--foo XXX'.split())\n" -"Namespace(bar='XXX')" - -#: ../../library/argparse.rst:1359 -msgid "deprecated" -msgstr "deprecated" - -#: ../../library/argparse.rst:1361 -msgid "" -"During a project's lifetime, some arguments may need to be removed from the " -"command line. Before removing them, you should inform your users that the " -"arguments are deprecated and will be removed. The ``deprecated`` keyword " -"argument of :meth:`~ArgumentParser.add_argument`, which defaults to " -"``False``, specifies if the argument is deprecated and will be removed in " -"the future. For arguments, if ``deprecated`` is ``True``, then a warning " -"will be printed to :data:`sys.stderr` when the argument is used::" -msgstr "" - -#: ../../library/argparse.rst:1371 -msgid "" -">>> import argparse\n" -">>> parser = argparse.ArgumentParser(prog='snake.py')\n" -">>> parser.add_argument('--legs', default=0, type=int, deprecated=True)\n" -">>> parser.parse_args([])\n" -"Namespace(legs=0)\n" -">>> parser.parse_args(['--legs', '4'])\n" -"snake.py: warning: option '--legs' is deprecated\n" -"Namespace(legs=4)" -msgstr "" -">>> import argparse\n" -">>> parser = argparse.ArgumentParser(prog='snake.py')\n" -">>> parser.add_argument('--legs', default=0, type=int, deprecated=True)\n" -">>> parser.parse_args([])\n" -"Namespace(legs=0)\n" -">>> parser.parse_args(['--legs', '4'])\n" -"snake.py: warning: option '--legs' is deprecated\n" -"Namespace(legs=4)" - -#: ../../library/argparse.rst:1384 -msgid "Action classes" -msgstr "Action 類別" - -#: ../../library/argparse.rst:1386 -msgid "" -":class:`!Action` classes implement the Action API, a callable which returns " -"a callable which processes arguments from the command-line. Any object which " -"follows this API may be passed as the ``action`` parameter to :meth:" -"`~ArgumentParser.add_argument`." -msgstr "" - -#: ../../library/argparse.rst:1395 -msgid "" -":class:`!Action` objects are used by an :class:`ArgumentParser` to represent " -"the information needed to parse a single argument from one or more strings " -"from the command line. The :class:`!Action` class must accept the two " -"positional arguments plus any keyword arguments passed to :meth:" -"`ArgumentParser.add_argument` except for the ``action`` itself." -msgstr "" - -#: ../../library/argparse.rst:1401 -msgid "" -"Instances of :class:`!Action` (or return value of any callable to the " -"``action`` parameter) should have attributes :attr:`!dest`, :attr:`!" -"option_strings`, :attr:`!default`, :attr:`!type`, :attr:`!required`, :attr:`!" -"help`, etc. defined. The easiest way to ensure these attributes are defined " -"is to call :meth:`!Action.__init__`." -msgstr "" - -#: ../../library/argparse.rst:1409 -msgid "" -":class:`!Action` instances should be callable, so subclasses must override " -"the :meth:`!__call__` method, which should accept four parameters:" -msgstr "" - -#: ../../library/argparse.rst:1412 -msgid "" -"*parser* - The :class:`ArgumentParser` object which contains this action." -msgstr "" - -#: ../../library/argparse.rst:1414 -msgid "" -"*namespace* - The :class:`Namespace` object that will be returned by :meth:" -"`~ArgumentParser.parse_args`. Most actions add an attribute to this object " -"using :func:`setattr`." -msgstr "" - -#: ../../library/argparse.rst:1418 -msgid "" -"*values* - The associated command-line arguments, with any type conversions " -"applied. Type conversions are specified with the type_ keyword argument to :" -"meth:`~ArgumentParser.add_argument`." -msgstr "" - -#: ../../library/argparse.rst:1422 -msgid "" -"*option_string* - The option string that was used to invoke this action. The " -"``option_string`` argument is optional, and will be absent if the action is " -"associated with a positional argument." -msgstr "" - -#: ../../library/argparse.rst:1426 -msgid "" -"The :meth:`!__call__` method may perform arbitrary actions, but will " -"typically set attributes on the ``namespace`` based on ``dest`` and " -"``values``." -msgstr "" - -#: ../../library/argparse.rst:1431 -msgid "" -":class:`!Action` subclasses can define a :meth:`!format_usage` method that " -"takes no argument and return a string which will be used when printing the " -"usage of the program. If such method is not provided, a sensible default " -"will be used." -msgstr "" - -#: ../../library/argparse.rst:1437 -msgid "" -"A subclass of :class:`Action` for handling boolean flags with positive and " -"negative options. Adding a single argument such as ``--foo`` automatically " -"creates both ``--foo`` and ``--no-foo`` options, storing ``True`` and " -"``False`` respectively::" -msgstr "" - -#: ../../library/argparse.rst:1442 -msgid "" -">>> import argparse\n" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('--foo', action=argparse.BooleanOptionalAction)\n" -">>> parser.parse_args(['--no-foo'])\n" -"Namespace(foo=False)" -msgstr "" -">>> import argparse\n" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('--foo', action=argparse.BooleanOptionalAction)\n" -">>> parser.parse_args(['--no-foo'])\n" -"Namespace(foo=False)" - -#: ../../library/argparse.rst:1452 -msgid "The parse_args() method" -msgstr "parse_args() 方法" - -#: ../../library/argparse.rst:1456 -msgid "" -"Convert argument strings to objects and assign them as attributes of the " -"namespace. Return the populated namespace." -msgstr "" - -#: ../../library/argparse.rst:1459 -msgid "" -"Previous calls to :meth:`add_argument` determine exactly what objects are " -"created and how they are assigned. See the documentation for :meth:`!" -"add_argument` for details." -msgstr "" - -#: ../../library/argparse.rst:1463 -msgid "" -"args_ - List of strings to parse. The default is taken from :data:`sys." -"argv`." -msgstr "" - -#: ../../library/argparse.rst:1466 -msgid "" -"namespace_ - An object to take the attributes. The default is a new empty :" -"class:`Namespace` object." -msgstr "" - -#: ../../library/argparse.rst:1471 -msgid "Option value syntax" -msgstr "" - -#: ../../library/argparse.rst:1473 -msgid "" -"The :meth:`~ArgumentParser.parse_args` method supports several ways of " -"specifying the value of an option (if it takes one). In the simplest case, " -"the option and its value are passed as two separate arguments::" -msgstr "" - -#: ../../library/argparse.rst:1477 -msgid "" -">>> parser = argparse.ArgumentParser(prog='PROG')\n" -">>> parser.add_argument('-x')\n" -">>> parser.add_argument('--foo')\n" -">>> parser.parse_args(['-x', 'X'])\n" -"Namespace(foo=None, x='X')\n" -">>> parser.parse_args(['--foo', 'FOO'])\n" -"Namespace(foo='FOO', x=None)" -msgstr "" -">>> parser = argparse.ArgumentParser(prog='PROG')\n" -">>> parser.add_argument('-x')\n" -">>> parser.add_argument('--foo')\n" -">>> parser.parse_args(['-x', 'X'])\n" -"Namespace(foo=None, x='X')\n" -">>> parser.parse_args(['--foo', 'FOO'])\n" -"Namespace(foo='FOO', x=None)" - -#: ../../library/argparse.rst:1485 -msgid "" -"For long options (options with names longer than a single character), the " -"option and value can also be passed as a single command-line argument, using " -"``=`` to separate them::" -msgstr "" - -#: ../../library/argparse.rst:1489 -msgid "" -">>> parser.parse_args(['--foo=FOO'])\n" -"Namespace(foo='FOO', x=None)" -msgstr "" -">>> parser.parse_args(['--foo=FOO'])\n" -"Namespace(foo='FOO', x=None)" - -#: ../../library/argparse.rst:1492 -msgid "" -"For short options (options only one character long), the option and its " -"value can be concatenated::" -msgstr "" - -#: ../../library/argparse.rst:1495 -msgid "" -">>> parser.parse_args(['-xX'])\n" -"Namespace(foo=None, x='X')" -msgstr "" -">>> parser.parse_args(['-xX'])\n" -"Namespace(foo=None, x='X')" - -#: ../../library/argparse.rst:1498 -msgid "" -"Several short options can be joined together, using only a single ``-`` " -"prefix, as long as only the last option (or none of them) requires a value::" -msgstr "" - -#: ../../library/argparse.rst:1501 -msgid "" -">>> parser = argparse.ArgumentParser(prog='PROG')\n" -">>> parser.add_argument('-x', action='store_true')\n" -">>> parser.add_argument('-y', action='store_true')\n" -">>> parser.add_argument('-z')\n" -">>> parser.parse_args(['-xyzZ'])\n" -"Namespace(x=True, y=True, z='Z')" -msgstr "" -">>> parser = argparse.ArgumentParser(prog='PROG')\n" -">>> parser.add_argument('-x', action='store_true')\n" -">>> parser.add_argument('-y', action='store_true')\n" -">>> parser.add_argument('-z')\n" -">>> parser.parse_args(['-xyzZ'])\n" -"Namespace(x=True, y=True, z='Z')" - -#: ../../library/argparse.rst:1510 -msgid "Invalid arguments" -msgstr "無效引數" - -#: ../../library/argparse.rst:1512 -msgid "" -"While parsing the command line, :meth:`~ArgumentParser.parse_args` checks " -"for a variety of errors, including ambiguous options, invalid types, invalid " -"options, wrong number of positional arguments, etc. When it encounters such " -"an error, it exits and prints the error along with a usage message::" -msgstr "" - -#: ../../library/argparse.rst:1517 -msgid "" -">>> parser = argparse.ArgumentParser(prog='PROG')\n" -">>> parser.add_argument('--foo', type=int)\n" -">>> parser.add_argument('bar', nargs='?')\n" -"\n" -">>> # invalid type\n" -">>> parser.parse_args(['--foo', 'spam'])\n" -"usage: PROG [-h] [--foo FOO] [bar]\n" -"PROG: error: argument --foo: invalid int value: 'spam'\n" -"\n" -">>> # invalid option\n" -">>> parser.parse_args(['--bar'])\n" -"usage: PROG [-h] [--foo FOO] [bar]\n" -"PROG: error: no such option: --bar\n" -"\n" -">>> # wrong number of arguments\n" -">>> parser.parse_args(['spam', 'badger'])\n" -"usage: PROG [-h] [--foo FOO] [bar]\n" -"PROG: error: extra arguments found: badger" -msgstr "" -">>> parser = argparse.ArgumentParser(prog='PROG')\n" -">>> parser.add_argument('--foo', type=int)\n" -">>> parser.add_argument('bar', nargs='?')\n" -"\n" -">>> # 無效型別\n" -">>> parser.parse_args(['--foo', 'spam'])\n" -"usage: PROG [-h] [--foo FOO] [bar]\n" -"PROG: error: argument --foo: invalid int value: 'spam'\n" -"\n" -">>> # 無效選項\n" -">>> parser.parse_args(['--bar'])\n" -"usage: PROG [-h] [--foo FOO] [bar]\n" -"PROG: error: no such option: --bar\n" -"\n" -">>> # 錯誤引數數量\n" -">>> parser.parse_args(['spam', 'badger'])\n" -"usage: PROG [-h] [--foo FOO] [bar]\n" -"PROG: error: extra arguments found: badger" - -#: ../../library/argparse.rst:1538 -msgid "Arguments containing ``-``" -msgstr "包含 ``-`` 的引數" - -#: ../../library/argparse.rst:1540 -msgid "" -"The :meth:`~ArgumentParser.parse_args` method attempts to give errors " -"whenever the user has clearly made a mistake, but some situations are " -"inherently ambiguous. For example, the command-line argument ``-1`` could " -"either be an attempt to specify an option or an attempt to provide a " -"positional argument. The :meth:`~ArgumentParser.parse_args` method is " -"cautious here: positional arguments may only begin with ``-`` if they look " -"like negative numbers and there are no options in the parser that look like " -"negative numbers::" -msgstr "" - -#: ../../library/argparse.rst:1548 -msgid "" -">>> parser = argparse.ArgumentParser(prog='PROG')\n" -">>> parser.add_argument('-x')\n" -">>> parser.add_argument('foo', nargs='?')\n" -"\n" -">>> # no negative number options, so -1 is a positional argument\n" -">>> parser.parse_args(['-x', '-1'])\n" -"Namespace(foo=None, x='-1')\n" -"\n" -">>> # no negative number options, so -1 and -5 are positional arguments\n" -">>> parser.parse_args(['-x', '-1', '-5'])\n" -"Namespace(foo='-5', x='-1')\n" -"\n" -">>> parser = argparse.ArgumentParser(prog='PROG')\n" -">>> parser.add_argument('-1', dest='one')\n" -">>> parser.add_argument('foo', nargs='?')\n" -"\n" -">>> # negative number options present, so -1 is an option\n" -">>> parser.parse_args(['-1', 'X'])\n" -"Namespace(foo=None, one='X')\n" -"\n" -">>> # negative number options present, so -2 is an option\n" -">>> parser.parse_args(['-2'])\n" -"usage: PROG [-h] [-1 ONE] [foo]\n" -"PROG: error: no such option: -2\n" -"\n" -">>> # negative number options present, so both -1s are options\n" -">>> parser.parse_args(['-1', '-1'])\n" -"usage: PROG [-h] [-1 ONE] [foo]\n" -"PROG: error: argument -1: expected one argument" -msgstr "" - -#: ../../library/argparse.rst:1578 -msgid "" -"If you have positional arguments that must begin with ``-`` and don't look " -"like negative numbers, you can insert the pseudo-argument ``'--'`` which " -"tells :meth:`~ArgumentParser.parse_args` that everything after that is a " -"positional argument::" -msgstr "" - -#: ../../library/argparse.rst:1583 -msgid "" -">>> parser.parse_args(['--', '-f'])\n" -"Namespace(foo='-f', one=None)" -msgstr "" -">>> parser.parse_args(['--', '-f'])\n" -"Namespace(foo='-f', one=None)" - -#: ../../library/argparse.rst:1586 -msgid "" -"See also :ref:`the argparse howto on ambiguous arguments ` for more details." -msgstr "" - -#: ../../library/argparse.rst:1592 -msgid "Argument abbreviations (prefix matching)" -msgstr "引數縮寫 (前綴匹配)" - -#: ../../library/argparse.rst:1594 -msgid "" -"The :meth:`~ArgumentParser.parse_args` method :ref:`by default " -"` allows long options to be abbreviated to a prefix, if the " -"abbreviation is unambiguous (the prefix matches a unique option)::" -msgstr "" - -#: ../../library/argparse.rst:1598 -msgid "" -">>> parser = argparse.ArgumentParser(prog='PROG')\n" -">>> parser.add_argument('-bacon')\n" -">>> parser.add_argument('-badger')\n" -">>> parser.parse_args('-bac MMM'.split())\n" -"Namespace(bacon='MMM', badger=None)\n" -">>> parser.parse_args('-bad WOOD'.split())\n" -"Namespace(bacon=None, badger='WOOD')\n" -">>> parser.parse_args('-ba BA'.split())\n" -"usage: PROG [-h] [-bacon BACON] [-badger BADGER]\n" -"PROG: error: ambiguous option: -ba could match -badger, -bacon" -msgstr "" -">>> parser = argparse.ArgumentParser(prog='PROG')\n" -">>> parser.add_argument('-bacon')\n" -">>> parser.add_argument('-badger')\n" -">>> parser.parse_args('-bac MMM'.split())\n" -"Namespace(bacon='MMM', badger=None)\n" -">>> parser.parse_args('-bad WOOD'.split())\n" -"Namespace(bacon=None, badger='WOOD')\n" -">>> parser.parse_args('-ba BA'.split())\n" -"usage: PROG [-h] [-bacon BACON] [-badger BADGER]\n" -"PROG: error: ambiguous option: -ba could match -badger, -bacon" - -#: ../../library/argparse.rst:1609 -msgid "" -"An error is produced for arguments that could produce more than one options. " -"This feature can be disabled by setting :ref:`allow_abbrev` to ``False``." -msgstr "" - -#: ../../library/argparse.rst:1615 -msgid "Beyond ``sys.argv``" -msgstr "``sys.argv`` 之外" - -#: ../../library/argparse.rst:1617 -msgid "" -"Sometimes it may be useful to have an :class:`ArgumentParser` parse " -"arguments other than those of :data:`sys.argv`. This can be accomplished by " -"passing a list of strings to :meth:`~ArgumentParser.parse_args`. This is " -"useful for testing at the interactive prompt::" -msgstr "" - -#: ../../library/argparse.rst:1622 -msgid "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument(\n" -"... 'integers', metavar='int', type=int, choices=range(10),\n" -"... nargs='+', help='an integer in the range 0..9')\n" -">>> parser.add_argument(\n" -"... '--sum', dest='accumulate', action='store_const', const=sum,\n" -"... default=max, help='sum the integers (default: find the max)')\n" -">>> parser.parse_args(['1', '2', '3', '4'])\n" -"Namespace(accumulate=, integers=[1, 2, 3, 4])\n" -">>> parser.parse_args(['1', '2', '3', '4', '--sum'])\n" -"Namespace(accumulate=, integers=[1, 2, 3, 4])" -msgstr "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument(\n" -"... 'integers', metavar='int', type=int, choices=range(10),\n" -"... nargs='+', help='an integer in the range 0..9')\n" -">>> parser.add_argument(\n" -"... '--sum', dest='accumulate', action='store_const', const=sum,\n" -"... default=max, help='sum the integers (default: find the max)')\n" -">>> parser.parse_args(['1', '2', '3', '4'])\n" -"Namespace(accumulate=, integers=[1, 2, 3, 4])\n" -">>> parser.parse_args(['1', '2', '3', '4', '--sum'])\n" -"Namespace(accumulate=, integers=[1, 2, 3, 4])" - -#: ../../library/argparse.rst:1637 -msgid "The Namespace object" -msgstr "命名空間物件" - -#: ../../library/argparse.rst:1641 -msgid "" -"Simple class used by default by :meth:`~ArgumentParser.parse_args` to create " -"an object holding attributes and return it." -msgstr "" - -#: ../../library/argparse.rst:1644 -msgid "" -"This class is deliberately simple, just an :class:`object` subclass with a " -"readable string representation. If you prefer to have dict-like view of the " -"attributes, you can use the standard Python idiom, :func:`vars`::" -msgstr "" - -#: ../../library/argparse.rst:1648 -msgid "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('--foo')\n" -">>> args = parser.parse_args(['--foo', 'BAR'])\n" -">>> vars(args)\n" -"{'foo': 'BAR'}" -msgstr "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('--foo')\n" -">>> args = parser.parse_args(['--foo', 'BAR'])\n" -">>> vars(args)\n" -"{'foo': 'BAR'}" - -#: ../../library/argparse.rst:1654 -msgid "" -"It may also be useful to have an :class:`ArgumentParser` assign attributes " -"to an already existing object, rather than a new :class:`Namespace` object. " -"This can be achieved by specifying the ``namespace=`` keyword argument::" -msgstr "" - -#: ../../library/argparse.rst:1658 -msgid "" -">>> class C:\n" -"... pass\n" -"...\n" -">>> c = C()\n" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('--foo')\n" -">>> parser.parse_args(args=['--foo', 'BAR'], namespace=c)\n" -">>> c.foo\n" -"'BAR'" -msgstr "" -">>> class C:\n" -"... pass\n" -"...\n" -">>> c = C()\n" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('--foo')\n" -">>> parser.parse_args(args=['--foo', 'BAR'], namespace=c)\n" -">>> c.foo\n" -"'BAR'" - -#: ../../library/argparse.rst:1670 -msgid "Other utilities" -msgstr "" - -#: ../../library/argparse.rst:1673 -msgid "Subcommands" -msgstr "子命令" - -#: ../../library/argparse.rst:1680 -msgid "" -"Many programs split up their functionality into a number of subcommands, for " -"example, the ``svn`` program can invoke subcommands like ``svn checkout``, " -"``svn update``, and ``svn commit``. Splitting up functionality this way can " -"be a particularly good idea when a program performs several different " -"functions which require different kinds of command-line arguments. :class:" -"`ArgumentParser` supports the creation of such subcommands with the :meth:`!" -"add_subparsers` method. The :meth:`!add_subparsers` method is normally " -"called with no arguments and returns a special action object. This object " -"has a single method, :meth:`~_SubParsersAction.add_parser`, which takes a " -"command name and any :class:`!ArgumentParser` constructor arguments, and " -"returns an :class:`!ArgumentParser` object that can be modified as usual." -msgstr "" - -#: ../../library/argparse.rst:1692 -msgid "Description of parameters:" -msgstr "參數的解釋：" - -#: ../../library/argparse.rst:1694 -msgid "" -"*title* - title for the sub-parser group in help output; by default " -"\"subcommands\" if description is provided, otherwise uses title for " -"positional arguments" -msgstr "" - -#: ../../library/argparse.rst:1698 -msgid "" -"*description* - description for the sub-parser group in help output, by " -"default ``None``" -msgstr "" - -#: ../../library/argparse.rst:1701 -msgid "" -"*prog* - usage information that will be displayed with subcommand help, by " -"default the name of the program and any positional arguments before the " -"subparser argument" -msgstr "" - -#: ../../library/argparse.rst:1705 -msgid "" -"*parser_class* - class which will be used to create sub-parser instances, by " -"default the class of the current parser (e.g. :class:`ArgumentParser`)" -msgstr "" - -#: ../../library/argparse.rst:1708 -msgid "" -"action_ - the basic type of action to be taken when this argument is " -"encountered at the command line" -msgstr "" - -#: ../../library/argparse.rst:1711 -msgid "" -"dest_ - name of the attribute under which subcommand name will be stored; by " -"default ``None`` and no value is stored" -msgstr "" - -#: ../../library/argparse.rst:1714 -msgid "" -"required_ - Whether or not a subcommand must be provided, by default " -"``False`` (added in 3.7)" -msgstr "" - -#: ../../library/argparse.rst:1717 -msgid "help_ - help for sub-parser group in help output, by default ``None``" -msgstr "" - -#: ../../library/argparse.rst:1719 -msgid "" -"metavar_ - string presenting available subcommands in help; by default it is " -"``None`` and presents subcommands in form {cmd1, cmd2, ..}" -msgstr "" - -#: ../../library/argparse.rst:1722 -msgid "Some example usage::" -msgstr "一些使用範例： ::" - -#: ../../library/argparse.rst:1724 -msgid "" -">>> # create the top-level parser\n" -">>> parser = argparse.ArgumentParser(prog='PROG')\n" -">>> parser.add_argument('--foo', action='store_true', help='foo help')\n" -">>> subparsers = parser.add_subparsers(help='subcommand help')\n" -">>>\n" -">>> # create the parser for the \"a\" command\n" -">>> parser_a = subparsers.add_parser('a', help='a help')\n" -">>> parser_a.add_argument('bar', type=int, help='bar help')\n" -">>>\n" -">>> # create the parser for the \"b\" command\n" -">>> parser_b = subparsers.add_parser('b', help='b help')\n" -">>> parser_b.add_argument('--baz', choices=('X', 'Y', 'Z'), help='baz " -"help')\n" -">>>\n" -">>> # parse some argument lists\n" -">>> parser.parse_args(['a', '12'])\n" -"Namespace(bar=12, foo=False)\n" -">>> parser.parse_args(['--foo', 'b', '--baz', 'Z'])\n" -"Namespace(baz='Z', foo=True)" -msgstr "" - -#: ../../library/argparse.rst:1743 -msgid "" -"Note that the object returned by :meth:`parse_args` will only contain " -"attributes for the main parser and the subparser that was selected by the " -"command line (and not any other subparsers). So in the example above, when " -"the ``a`` command is specified, only the ``foo`` and ``bar`` attributes are " -"present, and when the ``b`` command is specified, only the ``foo`` and " -"``baz`` attributes are present." -msgstr "" - -#: ../../library/argparse.rst:1750 -msgid "" -"Similarly, when a help message is requested from a subparser, only the help " -"for that particular parser will be printed. The help message will not " -"include parent parser or sibling parser messages. (A help message for each " -"subparser command, however, can be given by supplying the ``help=`` argument " -"to :meth:`~_SubParsersAction.add_parser` as above.)" -msgstr "" - -#: ../../library/argparse.rst:1758 -msgid "" -">>> parser.parse_args(['--help'])\n" -"usage: PROG [-h] [--foo] {a,b} ...\n" -"\n" -"positional arguments:\n" -" {a,b} subcommand help\n" -" a a help\n" -" b b help\n" -"\n" -"options:\n" -" -h, --help show this help message and exit\n" -" --foo foo help\n" -"\n" -">>> parser.parse_args(['a', '--help'])\n" -"usage: PROG a [-h] bar\n" -"\n" -"positional arguments:\n" -" bar bar help\n" -"\n" -"options:\n" -" -h, --help show this help message and exit\n" -"\n" -">>> parser.parse_args(['b', '--help'])\n" -"usage: PROG b [-h] [--baz {X,Y,Z}]\n" -"\n" -"options:\n" -" -h, --help show this help message and exit\n" -" --baz {X,Y,Z} baz help" -msgstr "" -">>> parser.parse_args(['--help'])\n" -"usage: PROG [-h] [--foo] {a,b} ...\n" -"\n" -"positional arguments:\n" -" {a,b} subcommand help\n" -" a a help\n" -" b b help\n" -"\n" -"options:\n" -" -h, --help show this help message and exit\n" -" --foo foo help\n" -"\n" -">>> parser.parse_args(['a', '--help'])\n" -"usage: PROG a [-h] bar\n" -"\n" -"positional arguments:\n" -" bar bar help\n" -"\n" -"options:\n" -" -h, --help show this help message and exit\n" -"\n" -">>> parser.parse_args(['b', '--help'])\n" -"usage: PROG b [-h] [--baz {X,Y,Z}]\n" -"\n" -"options:\n" -" -h, --help show this help message and exit\n" -" --baz {X,Y,Z} baz help" - -#: ../../library/argparse.rst:1786 -msgid "" -"The :meth:`add_subparsers` method also supports ``title`` and " -"``description`` keyword arguments. When either is present, the subparser's " -"commands will appear in their own group in the help output. For example::" -msgstr "" - -#: ../../library/argparse.rst:1790 -msgid "" -">>> parser = argparse.ArgumentParser()\n" -">>> subparsers = parser.add_subparsers(title='subcommands',\n" -"... description='valid subcommands',\n" -"... help='additional help')\n" -">>> subparsers.add_parser('foo')\n" -">>> subparsers.add_parser('bar')\n" -">>> parser.parse_args(['-h'])\n" -"usage: [-h] {foo,bar} ...\n" -"\n" -"options:\n" -" -h, --help show this help message and exit\n" -"\n" -"subcommands:\n" -" valid subcommands\n" -"\n" -" {foo,bar} additional help" -msgstr "" -">>> parser = argparse.ArgumentParser()\n" -">>> subparsers = parser.add_subparsers(title='subcommands',\n" -"... description='valid subcommands',\n" -"... help='additional help')\n" -">>> subparsers.add_parser('foo')\n" -">>> subparsers.add_parser('bar')\n" -">>> parser.parse_args(['-h'])\n" -"usage: [-h] {foo,bar} ...\n" -"\n" -"options:\n" -" -h, --help show this help message and exit\n" -"\n" -"subcommands:\n" -" valid subcommands\n" -"\n" -" {foo,bar} additional help" - -#: ../../library/argparse.rst:1807 -msgid "" -"Furthermore, :meth:`~_SubParsersAction.add_parser` supports an additional " -"*aliases* argument, which allows multiple strings to refer to the same " -"subparser. This example, like ``svn``, aliases ``co`` as a shorthand for " -"``checkout``::" -msgstr "" - -#: ../../library/argparse.rst:1812 -msgid "" -">>> parser = argparse.ArgumentParser()\n" -">>> subparsers = parser.add_subparsers()\n" -">>> checkout = subparsers.add_parser('checkout', aliases=['co'])\n" -">>> checkout.add_argument('foo')\n" -">>> parser.parse_args(['co', 'bar'])\n" -"Namespace(foo='bar')" -msgstr "" -">>> parser = argparse.ArgumentParser()\n" -">>> subparsers = parser.add_subparsers()\n" -">>> checkout = subparsers.add_parser('checkout', aliases=['co'])\n" -">>> checkout.add_argument('foo')\n" -">>> parser.parse_args(['co', 'bar'])\n" -"Namespace(foo='bar')" - -#: ../../library/argparse.rst:1819 -msgid "" -":meth:`~_SubParsersAction.add_parser` supports also an additional " -"*deprecated* argument, which allows to deprecate the subparser." -msgstr "" - -#: ../../library/argparse.rst:1833 -msgid "" -"One particularly effective way of handling subcommands is to combine the use " -"of the :meth:`add_subparsers` method with calls to :meth:`set_defaults` so " -"that each subparser knows which Python function it should execute. For " -"example::" -msgstr "" - -#: ../../library/argparse.rst:1838 -msgid "" -">>> # subcommand functions\n" -">>> def foo(args):\n" -"... print(args.x * args.y)\n" -"...\n" -">>> def bar(args):\n" -"... print('((%s))' % args.z)\n" -"...\n" -">>> # create the top-level parser\n" -">>> parser = argparse.ArgumentParser()\n" -">>> subparsers = parser.add_subparsers(required=True)\n" -">>>\n" -">>> # create the parser for the \"foo\" command\n" -">>> parser_foo = subparsers.add_parser('foo')\n" -">>> parser_foo.add_argument('-x', type=int, default=1)\n" -">>> parser_foo.add_argument('y', type=float)\n" -">>> parser_foo.set_defaults(func=foo)\n" -">>>\n" -">>> # create the parser for the \"bar\" command\n" -">>> parser_bar = subparsers.add_parser('bar')\n" -">>> parser_bar.add_argument('z')\n" -">>> parser_bar.set_defaults(func=bar)\n" -">>>\n" -">>> # parse the args and call whatever function was selected\n" -">>> args = parser.parse_args('foo 1 -x 2'.split())\n" -">>> args.func(args)\n" -"2.0\n" -">>>\n" -">>> # parse the args and call whatever function was selected\n" -">>> args = parser.parse_args('bar XYZYX'.split())\n" -">>> args.func(args)\n" -"((XYZYX))" -msgstr "" - -#: ../../library/argparse.rst:1870 -msgid "" -"This way, you can let :meth:`parse_args` do the job of calling the " -"appropriate function after argument parsing is complete. Associating " -"functions with actions like this is typically the easiest way to handle the " -"different actions for each of your subparsers. However, if it is necessary " -"to check the name of the subparser that was invoked, the ``dest`` keyword " -"argument to the :meth:`add_subparsers` call will work::" -msgstr "" - -#: ../../library/argparse.rst:1877 -msgid "" -">>> parser = argparse.ArgumentParser()\n" -">>> subparsers = parser.add_subparsers(dest='subparser_name')\n" -">>> subparser1 = subparsers.add_parser('1')\n" -">>> subparser1.add_argument('-x')\n" -">>> subparser2 = subparsers.add_parser('2')\n" -">>> subparser2.add_argument('y')\n" -">>> parser.parse_args(['2', 'frobble'])\n" -"Namespace(subparser_name='2', y='frobble')" -msgstr "" -">>> parser = argparse.ArgumentParser()\n" -">>> subparsers = parser.add_subparsers(dest='subparser_name')\n" -">>> subparser1 = subparsers.add_parser('1')\n" -">>> subparser1.add_argument('-x')\n" -">>> subparser2 = subparsers.add_parser('2')\n" -">>> subparser2.add_argument('y')\n" -">>> parser.parse_args(['2', 'frobble'])\n" -"Namespace(subparser_name='2', y='frobble')" - -#: ../../library/argparse.rst:1886 -msgid "New *required* keyword-only parameter." -msgstr "" - -#: ../../library/argparse.rst:1889 -msgid "" -"Subparser's *prog* is no longer affected by a custom usage message in the " -"main parser." -msgstr "" - -#: ../../library/argparse.rst:1895 -msgid "FileType objects" -msgstr "FileType 物件" - -#: ../../library/argparse.rst:1899 -msgid "" -"The :class:`FileType` factory creates objects that can be passed to the type " -"argument of :meth:`ArgumentParser.add_argument`. Arguments that have :class:" -"`FileType` objects as their type will open command-line arguments as files " -"with the requested modes, buffer sizes, encodings and error handling (see " -"the :func:`open` function for more details)::" -msgstr "" - -#: ../../library/argparse.rst:1905 -msgid "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('--raw', type=argparse.FileType('wb', 0))\n" -">>> parser.add_argument('out', type=argparse.FileType('w', " -"encoding='UTF-8'))\n" -">>> parser.parse_args(['--raw', 'raw.dat', 'file.txt'])\n" -"Namespace(out=<_io.TextIOWrapper name='file.txt' mode='w' encoding='UTF-8'>, " -"raw=<_io.FileIO name='raw.dat' mode='wb'>)" -msgstr "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('--raw', type=argparse.FileType('wb', 0))\n" -">>> parser.add_argument('out', type=argparse.FileType('w', " -"encoding='UTF-8'))\n" -">>> parser.parse_args(['--raw', 'raw.dat', 'file.txt'])\n" -"Namespace(out=<_io.TextIOWrapper name='file.txt' mode='w' encoding='UTF-8'>, " -"raw=<_io.FileIO name='raw.dat' mode='wb'>)" - -#: ../../library/argparse.rst:1911 -msgid "" -"FileType objects understand the pseudo-argument ``'-'`` and automatically " -"convert this into :data:`sys.stdin` for readable :class:`FileType` objects " -"and :data:`sys.stdout` for writable :class:`FileType` objects::" -msgstr "" - -#: ../../library/argparse.rst:1915 -msgid "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('infile', type=argparse.FileType('r'))\n" -">>> parser.parse_args(['-'])\n" -"Namespace(infile=<_io.TextIOWrapper name='' encoding='UTF-8'>)" -msgstr "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('infile', type=argparse.FileType('r'))\n" -">>> parser.parse_args(['-'])\n" -"Namespace(infile=<_io.TextIOWrapper name='' encoding='UTF-8'>)" - -#: ../../library/argparse.rst:1922 -msgid "" -"If one argument uses *FileType* and then a subsequent argument fails, an " -"error is reported but the file is not automatically closed. This can also " -"clobber the output files. In this case, it would be better to wait until " -"after the parser has run and then use the :keyword:`with`-statement to " -"manage the files." -msgstr "" - -#: ../../library/argparse.rst:1928 -msgid "Added the *encodings* and *errors* parameters." -msgstr "" - -#: ../../library/argparse.rst:1935 -msgid "Argument groups" -msgstr "" - -#: ../../library/argparse.rst:1940 -msgid "" -"By default, :class:`ArgumentParser` groups command-line arguments into " -"\"positional arguments\" and \"options\" when displaying help messages. When " -"there is a better conceptual grouping of arguments than this default one, " -"appropriate groups can be created using the :meth:`!add_argument_group` " -"method::" -msgstr "" - -#: ../../library/argparse.rst:1946 -msgid "" -">>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)\n" -">>> group = parser.add_argument_group('group')\n" -">>> group.add_argument('--foo', help='foo help')\n" -">>> group.add_argument('bar', help='bar help')\n" -">>> parser.print_help()\n" -"usage: PROG [--foo FOO] bar\n" -"\n" -"group:\n" -" bar bar help\n" -" --foo FOO foo help" -msgstr "" -">>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)\n" -">>> group = parser.add_argument_group('group')\n" -">>> group.add_argument('--foo', help='foo help')\n" -">>> group.add_argument('bar', help='bar help')\n" -">>> parser.print_help()\n" -"usage: PROG [--foo FOO] bar\n" -"\n" -"group:\n" -" bar bar help\n" -" --foo FOO foo help" - -#: ../../library/argparse.rst:1957 -msgid "" -"The :meth:`add_argument_group` method returns an argument group object which " -"has an :meth:`~ArgumentParser.add_argument` method just like a regular :" -"class:`ArgumentParser`. When an argument is added to the group, the parser " -"treats it just like a normal argument, but displays the argument in a " -"separate group for help messages. The :meth:`!add_argument_group` method " -"accepts *title* and *description* arguments which can be used to customize " -"this display::" -msgstr "" - -#: ../../library/argparse.rst:1965 -msgid "" -">>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)\n" -">>> group1 = parser.add_argument_group('group1', 'group1 description')\n" -">>> group1.add_argument('foo', help='foo help')\n" -">>> group2 = parser.add_argument_group('group2', 'group2 description')\n" -">>> group2.add_argument('--bar', help='bar help')\n" -">>> parser.print_help()\n" -"usage: PROG [--bar BAR] foo\n" -"\n" -"group1:\n" -" group1 description\n" -"\n" -" foo foo help\n" -"\n" -"group2:\n" -" group2 description\n" -"\n" -" --bar BAR bar help" -msgstr "" -">>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)\n" -">>> group1 = parser.add_argument_group('group1', 'group1 description')\n" -">>> group1.add_argument('foo', help='foo help')\n" -">>> group2 = parser.add_argument_group('group2', 'group2 description')\n" -">>> group2.add_argument('--bar', help='bar help')\n" -">>> parser.print_help()\n" -"usage: PROG [--bar BAR] foo\n" -"\n" -"group1:\n" -" group1 description\n" -"\n" -" foo foo help\n" -"\n" -"group2:\n" -" group2 description\n" -"\n" -" --bar BAR bar help" - -#: ../../library/argparse.rst:1983 -msgid "" -"The optional, keyword-only parameters argument_default_ and " -"conflict_handler_ allow for finer-grained control of the behavior of the " -"argument group. These parameters have the same meaning as in the :class:" -"`ArgumentParser` constructor, but apply specifically to the argument group " -"rather than the entire parser." -msgstr "" - -#: ../../library/argparse.rst:1988 -msgid "" -"Note that any arguments not in your user-defined groups will end up back in " -"the usual \"positional arguments\" and \"optional arguments\" sections." -msgstr "" - -#: ../../library/argparse.rst:1991 -msgid "" -"Calling :meth:`add_argument_group` on an argument group now raises an " -"exception. This nesting was never supported, often failed to work correctly, " -"and was unintentionally exposed through inheritance." -msgstr "" - -#: ../../library/argparse.rst:1996 -msgid "Passing prefix_chars_ to :meth:`add_argument_group` is now deprecated." -msgstr "" - -#: ../../library/argparse.rst:2002 -msgid "Mutual exclusion" -msgstr "" - -#: ../../library/argparse.rst:2006 -msgid "" -"Create a mutually exclusive group. :mod:`!argparse` will make sure that only " -"one of the arguments in the mutually exclusive group was present on the " -"command line::" -msgstr "" - -#: ../../library/argparse.rst:2010 -msgid "" -">>> parser = argparse.ArgumentParser(prog='PROG')\n" -">>> group = parser.add_mutually_exclusive_group()\n" -">>> group.add_argument('--foo', action='store_true')\n" -">>> group.add_argument('--bar', action='store_false')\n" -">>> parser.parse_args(['--foo'])\n" -"Namespace(bar=True, foo=True)\n" -">>> parser.parse_args(['--bar'])\n" -"Namespace(bar=False, foo=False)\n" -">>> parser.parse_args(['--foo', '--bar'])\n" -"usage: PROG [-h] [--foo | --bar]\n" -"PROG: error: argument --bar: not allowed with argument --foo" -msgstr "" -">>> parser = argparse.ArgumentParser(prog='PROG')\n" -">>> group = parser.add_mutually_exclusive_group()\n" -">>> group.add_argument('--foo', action='store_true')\n" -">>> group.add_argument('--bar', action='store_false')\n" -">>> parser.parse_args(['--foo'])\n" -"Namespace(bar=True, foo=True)\n" -">>> parser.parse_args(['--bar'])\n" -"Namespace(bar=False, foo=False)\n" -">>> parser.parse_args(['--foo', '--bar'])\n" -"usage: PROG [-h] [--foo | --bar]\n" -"PROG: error: argument --bar: not allowed with argument --foo" - -#: ../../library/argparse.rst:2022 -msgid "" -"The :meth:`add_mutually_exclusive_group` method also accepts a *required* " -"argument, to indicate that at least one of the mutually exclusive arguments " -"is required::" -msgstr "" - -#: ../../library/argparse.rst:2026 -msgid "" -">>> parser = argparse.ArgumentParser(prog='PROG')\n" -">>> group = parser.add_mutually_exclusive_group(required=True)\n" -">>> group.add_argument('--foo', action='store_true')\n" -">>> group.add_argument('--bar', action='store_false')\n" -">>> parser.parse_args([])\n" -"usage: PROG [-h] (--foo | --bar)\n" -"PROG: error: one of the arguments --foo --bar is required" -msgstr "" -">>> parser = argparse.ArgumentParser(prog='PROG')\n" -">>> group = parser.add_mutually_exclusive_group(required=True)\n" -">>> group.add_argument('--foo', action='store_true')\n" -">>> group.add_argument('--bar', action='store_false')\n" -">>> parser.parse_args([])\n" -"usage: PROG [-h] (--foo | --bar)\n" -"PROG: error: one of the arguments --foo --bar is required" - -#: ../../library/argparse.rst:2034 -msgid "" -"Note that currently mutually exclusive argument groups do not support the " -"*title* and *description* arguments of :meth:`~ArgumentParser." -"add_argument_group`. However, a mutually exclusive group can be added to an " -"argument group that has a title and description. For example::" -msgstr "" - -#: ../../library/argparse.rst:2040 -msgid "" -">>> parser = argparse.ArgumentParser(prog='PROG')\n" -">>> group = parser.add_argument_group('Group title', 'Group description')\n" -">>> exclusive_group = group.add_mutually_exclusive_group(required=True)\n" -">>> exclusive_group.add_argument('--foo', help='foo help')\n" -">>> exclusive_group.add_argument('--bar', help='bar help')\n" -">>> parser.print_help()\n" -"usage: PROG [-h] (--foo FOO | --bar BAR)\n" -"\n" -"options:\n" -" -h, --help show this help message and exit\n" -"\n" -"Group title:\n" -" Group description\n" -"\n" -" --foo FOO foo help\n" -" --bar BAR bar help" -msgstr "" -">>> parser = argparse.ArgumentParser(prog='PROG')\n" -">>> group = parser.add_argument_group('Group title', 'Group description')\n" -">>> exclusive_group = group.add_mutually_exclusive_group(required=True)\n" -">>> exclusive_group.add_argument('--foo', help='foo help')\n" -">>> exclusive_group.add_argument('--bar', help='bar help')\n" -">>> parser.print_help()\n" -"usage: PROG [-h] (--foo FOO | --bar BAR)\n" -"\n" -"options:\n" -" -h, --help show this help message and exit\n" -"\n" -"Group title:\n" -" Group description\n" -"\n" -" --foo FOO foo help\n" -" --bar BAR bar help" - -#: ../../library/argparse.rst:2057 -msgid "" -"Calling :meth:`add_argument_group` or :meth:`add_mutually_exclusive_group` " -"on a mutually exclusive group now raises an exception. This nesting was " -"never supported, often failed to work correctly, and was unintentionally " -"exposed through inheritance." -msgstr "" - -#: ../../library/argparse.rst:2065 -msgid "Parser defaults" -msgstr "" - -#: ../../library/argparse.rst:2069 -msgid "" -"Most of the time, the attributes of the object returned by :meth:" -"`parse_args` will be fully determined by inspecting the command-line " -"arguments and the argument actions. :meth:`set_defaults` allows some " -"additional attributes that are determined without any inspection of the " -"command line to be added::" -msgstr "" - -#: ../../library/argparse.rst:2075 -msgid "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('foo', type=int)\n" -">>> parser.set_defaults(bar=42, baz='badger')\n" -">>> parser.parse_args(['736'])\n" -"Namespace(bar=42, baz='badger', foo=736)" -msgstr "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('foo', type=int)\n" -">>> parser.set_defaults(bar=42, baz='badger')\n" -">>> parser.parse_args(['736'])\n" -"Namespace(bar=42, baz='badger', foo=736)" - -#: ../../library/argparse.rst:2081 -msgid "" -"Note that defaults can be set at both the parser level using :meth:" -"`set_defaults` and at the argument level using :meth:`add_argument`. If both " -"are called for the same argument, the last default set for an argument is " -"used::" -msgstr "" - -#: ../../library/argparse.rst:2085 -msgid "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('--foo', default='bar')\n" -">>> parser.set_defaults(foo='spam')\n" -">>> parser.parse_args([])\n" -"Namespace(foo='spam')" -msgstr "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('--foo', default='bar')\n" -">>> parser.set_defaults(foo='spam')\n" -">>> parser.parse_args([])\n" -"Namespace(foo='spam')" - -#: ../../library/argparse.rst:2091 -msgid "" -"Parser-level defaults can be particularly useful when working with multiple " -"parsers. See the :meth:`~ArgumentParser.add_subparsers` method for an " -"example of this type." -msgstr "" - -#: ../../library/argparse.rst:2097 -msgid "" -"Get the default value for a namespace attribute, as set by either :meth:" -"`~ArgumentParser.add_argument` or by :meth:`~ArgumentParser.set_defaults`::" -msgstr "" - -#: ../../library/argparse.rst:2101 -msgid "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('--foo', default='badger')\n" -">>> parser.get_default('foo')\n" -"'badger'" -msgstr "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('--foo', default='badger')\n" -">>> parser.get_default('foo')\n" -"'badger'" - -#: ../../library/argparse.rst:2108 -msgid "Printing help" -msgstr "印出幫助訊息" - -#: ../../library/argparse.rst:2110 -msgid "" -"In most typical applications, :meth:`~ArgumentParser.parse_args` will take " -"care of formatting and printing any usage or error messages. However, " -"several formatting methods are available:" -msgstr "" - -#: ../../library/argparse.rst:2116 -msgid "" -"Print a brief description of how the :class:`ArgumentParser` should be " -"invoked on the command line. If *file* is ``None``, :data:`sys.stdout` is " -"assumed." -msgstr "" - -#: ../../library/argparse.rst:2122 -msgid "" -"Print a help message, including the program usage and information about the " -"arguments registered with the :class:`ArgumentParser`. If *file* is " -"``None``, :data:`sys.stdout` is assumed." -msgstr "" - -#: ../../library/argparse.rst:2126 -msgid "" -"There are also variants of these methods that simply return a string instead " -"of printing it:" -msgstr "" - -#: ../../library/argparse.rst:2131 -msgid "" -"Return a string containing a brief description of how the :class:" -"`ArgumentParser` should be invoked on the command line." -msgstr "" - -#: ../../library/argparse.rst:2136 -msgid "" -"Return a string containing a help message, including the program usage and " -"information about the arguments registered with the :class:`ArgumentParser`." -msgstr "" - -#: ../../library/argparse.rst:2141 -msgid "Partial parsing" -msgstr "" - -#: ../../library/argparse.rst:2145 -msgid "" -"Sometimes a script only needs to handle a specific set of command-line " -"arguments, leaving any unrecognized arguments for another script or program. " -"In these cases, the :meth:`~ArgumentParser.parse_known_args` method can be " -"useful." -msgstr "" - -#: ../../library/argparse.rst:2150 -msgid "" -"This method works similarly to :meth:`~ArgumentParser.parse_args`, but it " -"does not raise an error for extra, unrecognized arguments. Instead, it " -"parses the known arguments and returns a two item tuple that contains the " -"populated namespace and the list of any unrecognized arguments." -msgstr "" - -#: ../../library/argparse.rst:2157 -msgid "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('--foo', action='store_true')\n" -">>> parser.add_argument('bar')\n" -">>> parser.parse_known_args(['--foo', '--badger', 'BAR', 'spam'])\n" -"(Namespace(bar='BAR', foo=True), ['--badger', 'spam'])" -msgstr "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('--foo', action='store_true')\n" -">>> parser.add_argument('bar')\n" -">>> parser.parse_known_args(['--foo', '--badger', 'BAR', 'spam'])\n" -"(Namespace(bar='BAR', foo=True), ['--badger', 'spam'])" - -#: ../../library/argparse.rst:2164 -msgid "" -":ref:`Prefix matching ` rules apply to :meth:" -"`~ArgumentParser.parse_known_args`. The parser may consume an option even if " -"it's just a prefix of one of its known options, instead of leaving it in the " -"remaining arguments list." -msgstr "" - -#: ../../library/argparse.rst:2171 -msgid "Customizing file parsing" -msgstr "" - -#: ../../library/argparse.rst:2175 -msgid "" -"Arguments that are read from a file (see the *fromfile_prefix_chars* keyword " -"argument to the :class:`ArgumentParser` constructor) are read one argument " -"per line. :meth:`convert_arg_line_to_args` can be overridden for fancier " -"reading." -msgstr "" - -#: ../../library/argparse.rst:2180 -msgid "" -"This method takes a single argument *arg_line* which is a string read from " -"the argument file. It returns a list of arguments parsed from this string. " -"The method is called once per line read from the argument file, in order." -msgstr "" - -#: ../../library/argparse.rst:2184 -msgid "" -"A useful override of this method is one that treats each space-separated " -"word as an argument. The following example demonstrates how to do this::" -msgstr "" - -#: ../../library/argparse.rst:2187 -msgid "" -"class MyArgumentParser(argparse.ArgumentParser):\n" -" def convert_arg_line_to_args(self, arg_line):\n" -" return arg_line.split()" -msgstr "" -"class MyArgumentParser(argparse.ArgumentParser):\n" -" def convert_arg_line_to_args(self, arg_line):\n" -" return arg_line.split()" - -#: ../../library/argparse.rst:2193 -msgid "Exiting methods" -msgstr "" - -#: ../../library/argparse.rst:2197 -msgid "" -"This method terminates the program, exiting with the specified *status* and, " -"if given, it prints a *message* to :data:`sys.stderr` before that. The user " -"can override this method to handle these steps differently::" -msgstr "" - -#: ../../library/argparse.rst:2201 -msgid "" -"class ErrorCatchingArgumentParser(argparse.ArgumentParser):\n" -" def exit(self, status=0, message=None):\n" -" if status:\n" -" raise Exception(f'Exiting because of an error: {message}')\n" -" exit(status)" -msgstr "" -"class ErrorCatchingArgumentParser(argparse.ArgumentParser):\n" -" def exit(self, status=0, message=None):\n" -" if status:\n" -" raise Exception(f'Exiting because of an error: {message}')\n" -" exit(status)" - -#: ../../library/argparse.rst:2209 -msgid "" -"This method prints a usage message, including the *message*, to :data:`sys." -"stderr` and terminates the program with a status code of 2." -msgstr "" - -#: ../../library/argparse.rst:2214 -msgid "Intermixed parsing" -msgstr "" - -#: ../../library/argparse.rst:2219 -msgid "" -"A number of Unix commands allow the user to intermix optional arguments with " -"positional arguments. The :meth:`~ArgumentParser.parse_intermixed_args` " -"and :meth:`~ArgumentParser.parse_known_intermixed_args` methods support this " -"parsing style." -msgstr "" - -#: ../../library/argparse.rst:2224 -msgid "" -"These parsers do not support all the :mod:`!argparse` features, and will " -"raise exceptions if unsupported features are used. In particular, " -"subparsers, and mutually exclusive groups that include both optionals and " -"positionals are not supported." -msgstr "" - -#: ../../library/argparse.rst:2229 -msgid "" -"The following example shows the difference between :meth:`~ArgumentParser." -"parse_known_args` and :meth:`~ArgumentParser.parse_intermixed_args`: the " -"former returns ``['2', '3']`` as unparsed arguments, while the latter " -"collects all the positionals into ``rest``. ::" -msgstr "" - -#: ../../library/argparse.rst:2235 -msgid "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('--foo')\n" -">>> parser.add_argument('cmd')\n" -">>> parser.add_argument('rest', nargs='*', type=int)\n" -">>> parser.parse_known_args('doit 1 --foo bar 2 3'.split())\n" -"(Namespace(cmd='doit', foo='bar', rest=[1]), ['2', '3'])\n" -">>> parser.parse_intermixed_args('doit 1 --foo bar 2 3'.split())\n" -"Namespace(cmd='doit', foo='bar', rest=[1, 2, 3])" -msgstr "" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.add_argument('--foo')\n" -">>> parser.add_argument('cmd')\n" -">>> parser.add_argument('rest', nargs='*', type=int)\n" -">>> parser.parse_known_args('doit 1 --foo bar 2 3'.split())\n" -"(Namespace(cmd='doit', foo='bar', rest=[1]), ['2', '3'])\n" -">>> parser.parse_intermixed_args('doit 1 --foo bar 2 3'.split())\n" -"Namespace(cmd='doit', foo='bar', rest=[1, 2, 3])" - -#: ../../library/argparse.rst:2244 -msgid "" -":meth:`~ArgumentParser.parse_known_intermixed_args` returns a two item tuple " -"containing the populated namespace and the list of remaining argument " -"strings. :meth:`~ArgumentParser.parse_intermixed_args` raises an error if " -"there are any remaining unparsed argument strings." -msgstr "" - -#: ../../library/argparse.rst:2253 -msgid "Registering custom types or actions" -msgstr "" - -#: ../../library/argparse.rst:2257 -msgid "" -"Sometimes it's desirable to use a custom string in error messages to provide " -"more user-friendly output. In these cases, :meth:`!register` can be used to " -"register custom actions or types with a parser and allow you to reference " -"the type by their registered name instead of their callable name." -msgstr "" - -#: ../../library/argparse.rst:2262 -msgid "" -"The :meth:`!register` method accepts three arguments - a *registry_name*, " -"specifying the internal registry where the object will be stored (e.g., " -"``action``, ``type``), *value*, which is the key under which the object will " -"be registered, and object, the callable to be registered." -msgstr "" - -#: ../../library/argparse.rst:2267 -msgid "" -"The following example shows how to register a custom type with a parser::" -msgstr "" - -#: ../../library/argparse.rst:2269 -msgid "" -">>> import argparse\n" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.register('type', 'hexadecimal integer', lambda s: int(s, 16))\n" -">>> parser.add_argument('--foo', type='hexadecimal integer')\n" -"_StoreAction(option_strings=['--foo'], dest='foo', nargs=None, const=None, " -"default=None, type='hexadecimal integer', choices=None, required=False, " -"help=None, metavar=None, deprecated=False)\n" -">>> parser.parse_args(['--foo', '0xFA'])\n" -"Namespace(foo=250)\n" -">>> parser.parse_args(['--foo', '1.2'])\n" -"usage: PROG [-h] [--foo FOO]\n" -"PROG: error: argument --foo: invalid 'hexadecimal integer' value: '1.2'" -msgstr "" -">>> import argparse\n" -">>> parser = argparse.ArgumentParser()\n" -">>> parser.register('type', 'hexadecimal integer', lambda s: int(s, 16))\n" -">>> parser.add_argument('--foo', type='hexadecimal integer')\n" -"_StoreAction(option_strings=['--foo'], dest='foo', nargs=None, const=None, " -"default=None, type='hexadecimal integer', choices=None, required=False, " -"help=None, metavar=None, deprecated=False)\n" -">>> parser.parse_args(['--foo', '0xFA'])\n" -"Namespace(foo=250)\n" -">>> parser.parse_args(['--foo', '1.2'])\n" -"usage: PROG [-h] [--foo FOO]\n" -"PROG: error: argument --foo: invalid 'hexadecimal integer' value: '1.2'" - -#: ../../library/argparse.rst:2281 -msgid "Exceptions" -msgstr "例外" - -#: ../../library/argparse.rst:2285 -msgid "An error from creating or using an argument (optional or positional)." -msgstr "" - -#: ../../library/argparse.rst:2287 -msgid "" -"The string value of this exception is the message, augmented with " -"information about the argument that caused it." -msgstr "" - -#: ../../library/argparse.rst:2292 -msgid "" -"Raised when something goes wrong converting a command line string to a type." -msgstr "" - -#: ../../library/argparse.rst:2296 -msgid "Guides and Tutorials" -msgstr "" - -#: ../../library/argparse.rst:908 -msgid "? (question mark)" -msgstr "? （問號）" - -#: ../../library/argparse.rst:908 ../../library/argparse.rst:940 -#: ../../library/argparse.rst:954 -msgid "in argparse module" -msgstr "於 argparse 模組中" - -#: ../../library/argparse.rst:940 -msgid "* (asterisk)" -msgstr "* （星號）" - -#: ../../library/argparse.rst:954 -msgid "+ (plus)" -msgstr "+ （加號）" - -#~ msgid "" -#~ ">>> parser = argparse.ArgumentParser()\n" -#~ ">>> parser.add_argument('infile', nargs='?', type=argparse." -#~ "FileType('r'),\n" -#~ "... default=sys.stdin)\n" -#~ ">>> parser.add_argument('outfile', nargs='?', type=argparse." -#~ "FileType('w'),\n" -#~ "... default=sys.stdout)\n" -#~ ">>> parser.parse_args(['input.txt', 'output.txt'])\n" -#~ "Namespace(infile=<_io.TextIOWrapper name='input.txt' encoding='UTF-8'>,\n" -#~ " outfile=<_io.TextIOWrapper name='output.txt' " -#~ "encoding='UTF-8'>)\n" -#~ ">>> parser.parse_args([])\n" -#~ "Namespace(infile=<_io.TextIOWrapper name='' encoding='UTF-8'>,\n" -#~ " outfile=<_io.TextIOWrapper name='' encoding='UTF-8'>)" -#~ msgstr "" -#~ ">>> parser = argparse.ArgumentParser()\n" -#~ ">>> parser.add_argument('infile', nargs='?', type=argparse." -#~ "FileType('r'),\n" -#~ "... default=sys.stdin)\n" -#~ ">>> parser.add_argument('outfile', nargs='?', type=argparse." -#~ "FileType('w'),\n" -#~ "... default=sys.stdout)\n" -#~ ">>> parser.parse_args(['input.txt', 'output.txt'])\n" -#~ "Namespace(infile=<_io.TextIOWrapper name='input.txt' encoding='UTF-8'>,\n" -#~ " outfile=<_io.TextIOWrapper name='output.txt' " -#~ "encoding='UTF-8'>)\n" -#~ ">>> parser.parse_args([])\n" -#~ "Namespace(infile=<_io.TextIOWrapper name='' encoding='UTF-8'>,\n" -#~ " outfile=<_io.TextIOWrapper name='' encoding='UTF-8'>)" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-01-07 00:14+0000\n" +"PO-Revision-Date: 2018-05-23 14:38+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/argparse.rst:2 +msgid "" +":mod:`!argparse` --- Parser for command-line options, arguments and " +"subcommands" +msgstr ":mod:`!argparse` --- 命令列選項、引數和子命令的剖析器" + +#: ../../library/argparse.rst:12 +msgid "**Source code:** :source:`Lib/argparse.py`" +msgstr "**原始碼：**\\ :source:`Lib/argparse.py`" + +#: ../../library/argparse.rst:16 +msgid "" +"While :mod:`argparse` is the default recommended standard library module for " +"implementing basic command line applications, authors with more exacting " +"requirements for exactly how their command line applications behave may find " +"it doesn't provide the necessary level of control. Refer to :ref:`choosing-" +"an-argument-parser` for alternatives to consider when ``argparse`` doesn't " +"support behaviors that the application requires (such as entirely disabling " +"support for interspersed options and positional arguments, or accepting " +"option parameter values that start with ``-`` even when they correspond to " +"another defined option)." +msgstr "" + +#: ../../library/argparse.rst:28 +msgid "Tutorial" +msgstr "教學" + +#: ../../library/argparse.rst:30 +msgid "" +"This page contains the API reference information. For a more gentle " +"introduction to Python command-line parsing, have a look at the :ref:" +"`argparse tutorial `." +msgstr "" + +#: ../../library/argparse.rst:34 +msgid "" +"The :mod:`!argparse` module makes it easy to write user-friendly command-" +"line interfaces. The program defines what arguments it requires, and :mod:`!" +"argparse` will figure out how to parse those out of :data:`sys.argv`. The :" +"mod:`!argparse` module also automatically generates help and usage " +"messages. The module will also issue errors when users give the program " +"invalid arguments." +msgstr "" + +#: ../../library/argparse.rst:40 +msgid "" +"The :mod:`!argparse` module's support for command-line interfaces is built " +"around an instance of :class:`argparse.ArgumentParser`. It is a container " +"for argument specifications and has options that apply to the parser as " +"whole::" +msgstr "" + +#: ../../library/argparse.rst:44 +msgid "" +"parser = argparse.ArgumentParser(\n" +" prog='ProgramName',\n" +" description='What the program does',\n" +" epilog='Text at the bottom of help')" +msgstr "" +"parser = argparse.ArgumentParser(\n" +" prog='ProgramName',\n" +" description='What the program does',\n" +" epilog='Text at the bottom of help')" + +#: ../../library/argparse.rst:49 +msgid "" +"The :meth:`ArgumentParser.add_argument` method attaches individual argument " +"specifications to the parser. It supports positional arguments, options " +"that accept values, and on/off flags::" +msgstr "" + +#: ../../library/argparse.rst:53 +msgid "" +"parser.add_argument('filename') # positional argument\n" +"parser.add_argument('-c', '--count') # option that takes a value\n" +"parser.add_argument('-v', '--verbose',\n" +" action='store_true') # on/off flag" +msgstr "" +"parser.add_argument('filename') # 位置引數\n" +"parser.add_argument('-c', '--count') # 接收一個值的選項\n" +"parser.add_argument('-v', '--verbose',\n" +" action='store_true') # 開關旗標" + +#: ../../library/argparse.rst:58 +msgid "" +"The :meth:`ArgumentParser.parse_args` method runs the parser and places the " +"extracted data in a :class:`argparse.Namespace` object::" +msgstr "" + +#: ../../library/argparse.rst:61 +msgid "" +"args = parser.parse_args()\n" +"print(args.filename, args.count, args.verbose)" +msgstr "" +"args = parser.parse_args()\n" +"print(args.filename, args.count, args.verbose)" + +#: ../../library/argparse.rst:65 +msgid "" +"If you're looking for a guide about how to upgrade :mod:`optparse` code to :" +"mod:`!argparse`, see :ref:`Upgrading Optparse Code `." +msgstr "" + +#: ../../library/argparse.rst:69 +msgid "ArgumentParser objects" +msgstr "ArgumentParser 物件" + +#: ../../library/argparse.rst:79 +msgid "" +"Create a new :class:`ArgumentParser` object. All parameters should be passed " +"as keyword arguments. Each parameter has its own more detailed description " +"below, but in short they are:" +msgstr "" + +#: ../../library/argparse.rst:83 +msgid "" +"prog_ - The name of the program (default: generated from the ``__main__`` " +"module attributes and ``sys.argv[0]``)" +msgstr "" +"prog_ - 程式的名稱（預設值：從 ``__main__`` 模組屬性和 ``sys.argv[0]`` 產生）" + +#: ../../library/argparse.rst:86 +msgid "" +"usage_ - The string describing the program usage (default: generated from " +"arguments added to parser)" +msgstr "usage_ - 描述程式用法的字串（預設值：從新增到剖析器的引數產生）" + +#: ../../library/argparse.rst:89 +msgid "" +"description_ - Text to display before the argument help (by default, no text)" +msgstr "description_ - 引數說明之前要顯示的文字（預設值：無文字）" + +#: ../../library/argparse.rst:92 +msgid "epilog_ - Text to display after the argument help (by default, no text)" +msgstr "epilog_ - 引數說明之後要顯示的文字（預設值：無文字）" + +#: ../../library/argparse.rst:94 +msgid "" +"parents_ - A list of :class:`ArgumentParser` objects whose arguments should " +"also be included" +msgstr "parents_ - 一個 :class:`ArgumentParser` 物件的串列，其引數也應該被包含" + +#: ../../library/argparse.rst:97 +msgid "formatter_class_ - A class for customizing the help output" +msgstr "formatter_class_ - 用於自訂說明輸出的類別" + +#: ../../library/argparse.rst:99 +msgid "" +"prefix_chars_ - The set of characters that prefix optional arguments " +"(default: '-')" +msgstr "prefix_chars_ - 前綴可選引數的字元集合（預設值：'-'）" + +#: ../../library/argparse.rst:102 +msgid "" +"fromfile_prefix_chars_ - The set of characters that prefix files from which " +"additional arguments should be read (default: ``None``)" +msgstr "" + +#: ../../library/argparse.rst:105 +msgid "" +"argument_default_ - The global default value for arguments (default: " +"``None``)" +msgstr "" + +#: ../../library/argparse.rst:108 +msgid "" +"conflict_handler_ - The strategy for resolving conflicting optionals " +"(usually unnecessary)" +msgstr "" + +#: ../../library/argparse.rst:111 +msgid "" +"add_help_ - Add a ``-h/--help`` option to the parser (default: ``True``)" +msgstr "" + +#: ../../library/argparse.rst:113 +msgid "" +"allow_abbrev_ - Allows long options to be abbreviated if the abbreviation is " +"unambiguous (default: ``True``)" +msgstr "" + +#: ../../library/argparse.rst:116 +msgid "" +"exit_on_error_ - Determines whether or not :class:`!ArgumentParser` exits " +"with error info when an error occurs. (default: ``True``)" +msgstr "" + +#: ../../library/argparse.rst:119 +msgid "" +"suggest_on_error_ - Enables suggestions for mistyped argument choices and " +"subparser names (default: ``False``)" +msgstr "" + +#: ../../library/argparse.rst:122 +msgid "color_ - Allow color output (default: ``True``)" +msgstr "" + +#: ../../library/argparse.rst:124 +msgid "*allow_abbrev* parameter was added." +msgstr "新增 *allow_abbrev* 參數。" + +#: ../../library/argparse.rst:127 +msgid "" +"In previous versions, *allow_abbrev* also disabled grouping of short flags " +"such as ``-vv`` to mean ``-v -v``." +msgstr "" + +#: ../../library/argparse.rst:131 +msgid "*exit_on_error* parameter was added." +msgstr "新增 *exit_on_error* 參數。" + +#: ../../library/argparse.rst:134 +msgid "*suggest_on_error* and *color* parameters were added." +msgstr "新增 *suggest_on_error* 和 *color* 參數。" + +#: ../../library/argparse.rst:137 ../../library/argparse.rst:696 +msgid "The following sections describe how each of these are used." +msgstr "" + +#: ../../library/argparse.rst:143 +msgid "prog" +msgstr "prog" + +#: ../../library/argparse.rst:146 +msgid "" +"By default, :class:`ArgumentParser` calculates the name of the program to " +"display in help messages depending on the way the Python interpreter was run:" +msgstr "" + +#: ../../library/argparse.rst:149 +msgid "" +"The :func:`base name ` of ``sys.argv[0]`` if a file was " +"passed as argument." +msgstr "" + +#: ../../library/argparse.rst:151 +msgid "" +"The Python interpreter name followed by ``sys.argv[0]`` if a directory or a " +"zipfile was passed as argument." +msgstr "" + +#: ../../library/argparse.rst:153 +msgid "" +"The Python interpreter name followed by ``-m`` followed by the module or " +"package name if the :option:`-m` option was used." +msgstr "" + +#: ../../library/argparse.rst:156 +msgid "" +"This default is almost always desirable because it will make the help " +"messages match the string that was used to invoke the program on the command " +"line. However, to change this default behavior, another value can be " +"supplied using the ``prog=`` argument to :class:`ArgumentParser`::" +msgstr "" + +#: ../../library/argparse.rst:161 +msgid "" +">>> parser = argparse.ArgumentParser(prog='myprogram')\n" +">>> parser.print_help()\n" +"usage: myprogram [-h]\n" +"\n" +"options:\n" +" -h, --help show this help message and exit" +msgstr "" +">>> parser = argparse.ArgumentParser(prog='myprogram')\n" +">>> parser.print_help()\n" +"usage: myprogram [-h]\n" +"\n" +"options:\n" +" -h, --help show this help message and exit" + +#: ../../library/argparse.rst:168 +msgid "" +"Note that the program name, whether determined from ``sys.argv[0]``, from " +"the ``__main__`` module attributes or from the ``prog=`` argument, is " +"available to help messages using the ``%(prog)s`` format specifier." +msgstr "" + +#: ../../library/argparse.rst:175 +msgid "" +">>> parser = argparse.ArgumentParser(prog='myprogram')\n" +">>> parser.add_argument('--foo', help='foo of the %(prog)s program')\n" +">>> parser.print_help()\n" +"usage: myprogram [-h] [--foo FOO]\n" +"\n" +"options:\n" +" -h, --help show this help message and exit\n" +" --foo FOO foo of the myprogram program" +msgstr "" +">>> parser = argparse.ArgumentParser(prog='myprogram')\n" +">>> parser.add_argument('--foo', help='foo of the %(prog)s program')\n" +">>> parser.print_help()\n" +"usage: myprogram [-h] [--foo FOO]\n" +"\n" +"options:\n" +" -h, --help show this help message and exit\n" +" --foo FOO foo of the myprogram program" + +#: ../../library/argparse.rst:184 +msgid "" +"The default ``prog`` value now reflects how ``__main__`` was actually " +"executed, rather than always being ``os.path.basename(sys.argv[0])``." +msgstr "" + +#: ../../library/argparse.rst:189 +msgid "usage" +msgstr "usage" + +#: ../../library/argparse.rst:191 +msgid "" +"By default, :class:`ArgumentParser` calculates the usage message from the " +"arguments it contains. The default message can be overridden with the " +"``usage=`` keyword argument::" +msgstr "" + +#: ../../library/argparse.rst:195 +msgid "" +">>> parser = argparse.ArgumentParser(prog='PROG', usage='%(prog)s " +"[options]')\n" +">>> parser.add_argument('--foo', nargs='?', help='foo help')\n" +">>> parser.add_argument('bar', nargs='+', help='bar help')\n" +">>> parser.print_help()\n" +"usage: PROG [options]\n" +"\n" +"positional arguments:\n" +" bar bar help\n" +"\n" +"options:\n" +" -h, --help show this help message and exit\n" +" --foo [FOO] foo help" +msgstr "" +">>> parser = argparse.ArgumentParser(prog='PROG', usage='%(prog)s " +"[options]')\n" +">>> parser.add_argument('--foo', nargs='?', help='foo help')\n" +">>> parser.add_argument('bar', nargs='+', help='bar help')\n" +">>> parser.print_help()\n" +"usage: PROG [options]\n" +"\n" +"positional arguments:\n" +" bar bar help\n" +"\n" +"options:\n" +" -h, --help show this help message and exit\n" +" --foo [FOO] foo help" + +#: ../../library/argparse.rst:208 +msgid "" +"The ``%(prog)s`` format specifier is available to fill in the program name " +"in your usage messages." +msgstr "" + +#: ../../library/argparse.rst:211 +msgid "" +"When a custom usage message is specified for the main parser, you may also " +"want to consider passing the ``prog`` argument to :meth:`~ArgumentParser." +"add_subparsers` or the ``prog`` and the ``usage`` arguments to :meth:" +"`~_SubParsersAction.add_parser`, to ensure consistent command prefixes and " +"usage information across subparsers." +msgstr "" + +#: ../../library/argparse.rst:221 +msgid "description" +msgstr "description" + +#: ../../library/argparse.rst:223 +msgid "" +"Most calls to the :class:`ArgumentParser` constructor will use the " +"``description=`` keyword argument. This argument gives a brief description " +"of what the program does and how it works. In help messages, the " +"description is displayed between the command-line usage string and the help " +"messages for the various arguments." +msgstr "" + +#: ../../library/argparse.rst:229 +msgid "" +"By default, the description will be line-wrapped so that it fits within the " +"given space. To change this behavior, see the formatter_class_ argument." +msgstr "" + +#: ../../library/argparse.rst:234 +msgid "epilog" +msgstr "epilog" + +#: ../../library/argparse.rst:236 +msgid "" +"Some programs like to display additional description of the program after " +"the description of the arguments. Such text can be specified using the " +"``epilog=`` argument to :class:`ArgumentParser`::" +msgstr "" + +#: ../../library/argparse.rst:240 +msgid "" +">>> parser = argparse.ArgumentParser(\n" +"... description='A foo that bars',\n" +"... epilog=\"And that's how you'd foo a bar\")\n" +">>> parser.print_help()\n" +"usage: argparse.py [-h]\n" +"\n" +"A foo that bars\n" +"\n" +"options:\n" +" -h, --help show this help message and exit\n" +"\n" +"And that's how you'd foo a bar" +msgstr "" +">>> parser = argparse.ArgumentParser(\n" +"... description='A foo that bars',\n" +"... epilog=\"And that's how you'd foo a bar\")\n" +">>> parser.print_help()\n" +"usage: argparse.py [-h]\n" +"\n" +"A foo that bars\n" +"\n" +"options:\n" +" -h, --help show this help message and exit\n" +"\n" +"And that's how you'd foo a bar" + +#: ../../library/argparse.rst:253 +msgid "" +"As with the description_ argument, the ``epilog=`` text is by default line-" +"wrapped, but this behavior can be adjusted with the formatter_class_ " +"argument to :class:`ArgumentParser`." +msgstr "" + +#: ../../library/argparse.rst:259 +msgid "parents" +msgstr "parents" + +#: ../../library/argparse.rst:261 +msgid "" +"Sometimes, several parsers share a common set of arguments. Rather than " +"repeating the definitions of these arguments, a single parser with all the " +"shared arguments and passed to ``parents=`` argument to :class:" +"`ArgumentParser` can be used. The ``parents=`` argument takes a list of :" +"class:`ArgumentParser` objects, collects all the positional and optional " +"actions from them, and adds these actions to the :class:`ArgumentParser` " +"object being constructed::" +msgstr "" + +#: ../../library/argparse.rst:268 +msgid "" +">>> parent_parser = argparse.ArgumentParser(add_help=False)\n" +">>> parent_parser.add_argument('--parent', type=int)\n" +"\n" +">>> foo_parser = argparse.ArgumentParser(parents=[parent_parser])\n" +">>> foo_parser.add_argument('foo')\n" +">>> foo_parser.parse_args(['--parent', '2', 'XXX'])\n" +"Namespace(foo='XXX', parent=2)\n" +"\n" +">>> bar_parser = argparse.ArgumentParser(parents=[parent_parser])\n" +">>> bar_parser.add_argument('--bar')\n" +">>> bar_parser.parse_args(['--bar', 'YYY'])\n" +"Namespace(bar='YYY', parent=None)" +msgstr "" +">>> parent_parser = argparse.ArgumentParser(add_help=False)\n" +">>> parent_parser.add_argument('--parent', type=int)\n" +"\n" +">>> foo_parser = argparse.ArgumentParser(parents=[parent_parser])\n" +">>> foo_parser.add_argument('foo')\n" +">>> foo_parser.parse_args(['--parent', '2', 'XXX'])\n" +"Namespace(foo='XXX', parent=2)\n" +"\n" +">>> bar_parser = argparse.ArgumentParser(parents=[parent_parser])\n" +">>> bar_parser.add_argument('--bar')\n" +">>> bar_parser.parse_args(['--bar', 'YYY'])\n" +"Namespace(bar='YYY', parent=None)" + +#: ../../library/argparse.rst:281 +msgid "" +"Note that most parent parsers will specify ``add_help=False``. Otherwise, " +"the :class:`ArgumentParser` will see two ``-h/--help`` options (one in the " +"parent and one in the child) and raise an error." +msgstr "" + +#: ../../library/argparse.rst:286 +msgid "" +"You must fully initialize the parsers before passing them via ``parents=``. " +"If you change the parent parsers after the child parser, those changes will " +"not be reflected in the child." +msgstr "" + +#: ../../library/argparse.rst:294 +msgid "formatter_class" +msgstr "formatter_class" + +#: ../../library/argparse.rst:296 +msgid "" +":class:`ArgumentParser` objects allow the help formatting to be customized " +"by specifying an alternate formatting class. Currently, there are four such " +"classes:" +msgstr "" + +#: ../../library/argparse.rst:305 +msgid "" +":class:`RawDescriptionHelpFormatter` and :class:`RawTextHelpFormatter` give " +"more control over how textual descriptions are displayed. By default, :class:" +"`ArgumentParser` objects line-wrap the description_ and epilog_ texts in " +"command-line help messages::" +msgstr "" + +#: ../../library/argparse.rst:310 +msgid "" +">>> parser = argparse.ArgumentParser(\n" +"... prog='PROG',\n" +"... description='''this description\n" +"... was indented weird\n" +"... but that is okay''',\n" +"... epilog='''\n" +"... likewise for this epilog whose whitespace will\n" +"... be cleaned up and whose words will be wrapped\n" +"... across a couple lines''')\n" +">>> parser.print_help()\n" +"usage: PROG [-h]\n" +"\n" +"this description was indented weird but that is okay\n" +"\n" +"options:\n" +" -h, --help show this help message and exit\n" +"\n" +"likewise for this epilog whose whitespace will be cleaned up and whose " +"words\n" +"will be wrapped across a couple lines" +msgstr "" +">>> parser = argparse.ArgumentParser(\n" +"... prog='PROG',\n" +"... description='''this description\n" +"... was indented weird\n" +"... but that is okay''',\n" +"... epilog='''\n" +"... likewise for this epilog whose whitespace will\n" +"... be cleaned up and whose words will be wrapped\n" +"... across a couple lines''')\n" +">>> parser.print_help()\n" +"usage: PROG [-h]\n" +"\n" +"this description was indented weird but that is okay\n" +"\n" +"options:\n" +" -h, --help show this help message and exit\n" +"\n" +"likewise for this epilog whose whitespace will be cleaned up and whose " +"words\n" +"will be wrapped across a couple lines" + +#: ../../library/argparse.rst:330 +msgid "" +"Passing :class:`RawDescriptionHelpFormatter` as ``formatter_class=`` " +"indicates that description_ and epilog_ are already correctly formatted and " +"should not be line-wrapped::" +msgstr "" + +#: ../../library/argparse.rst:334 +msgid "" +">>> parser = argparse.ArgumentParser(\n" +"... prog='PROG',\n" +"... formatter_class=argparse.RawDescriptionHelpFormatter,\n" +"... description=textwrap.dedent('''\\\n" +"... Please do not mess up this text!\n" +"... --------------------------------\n" +"... I have indented it\n" +"... exactly the way\n" +"... I want it\n" +"... '''))\n" +">>> parser.print_help()\n" +"usage: PROG [-h]\n" +"\n" +"Please do not mess up this text!\n" +"--------------------------------\n" +" I have indented it\n" +" exactly the way\n" +" I want it\n" +"\n" +"options:\n" +" -h, --help show this help message and exit" +msgstr "" +">>> parser = argparse.ArgumentParser(\n" +"... prog='PROG',\n" +"... formatter_class=argparse.RawDescriptionHelpFormatter,\n" +"... description=textwrap.dedent('''\\\n" +"... Please do not mess up this text!\n" +"... --------------------------------\n" +"... I have indented it\n" +"... exactly the way\n" +"... I want it\n" +"... '''))\n" +">>> parser.print_help()\n" +"usage: PROG [-h]\n" +"\n" +"Please do not mess up this text!\n" +"--------------------------------\n" +" I have indented it\n" +" exactly the way\n" +" I want it\n" +"\n" +"options:\n" +" -h, --help show this help message and exit" + +#: ../../library/argparse.rst:356 +msgid "" +":class:`RawTextHelpFormatter` maintains whitespace for all sorts of help " +"text, including argument descriptions. However, multiple newlines are " +"replaced with one. If you wish to preserve multiple blank lines, add spaces " +"between the newlines." +msgstr "" + +#: ../../library/argparse.rst:361 +msgid "" +":class:`ArgumentDefaultsHelpFormatter` automatically adds information about " +"default values to each of the argument help messages::" +msgstr "" + +#: ../../library/argparse.rst:364 +msgid "" +">>> parser = argparse.ArgumentParser(\n" +"... prog='PROG',\n" +"... formatter_class=argparse.ArgumentDefaultsHelpFormatter)\n" +">>> parser.add_argument('--foo', type=int, default=42, help='FOO!')\n" +">>> parser.add_argument('bar', nargs='*', default=[1, 2, 3], help='BAR!')\n" +">>> parser.print_help()\n" +"usage: PROG [-h] [--foo FOO] [bar ...]\n" +"\n" +"positional arguments:\n" +" bar BAR! (default: [1, 2, 3])\n" +"\n" +"options:\n" +" -h, --help show this help message and exit\n" +" --foo FOO FOO! (default: 42)" +msgstr "" +">>> parser = argparse.ArgumentParser(\n" +"... prog='PROG',\n" +"... formatter_class=argparse.ArgumentDefaultsHelpFormatter)\n" +">>> parser.add_argument('--foo', type=int, default=42, help='FOO!')\n" +">>> parser.add_argument('bar', nargs='*', default=[1, 2, 3], help='BAR!')\n" +">>> parser.print_help()\n" +"usage: PROG [-h] [--foo FOO] [bar ...]\n" +"\n" +"positional arguments:\n" +" bar BAR! (default: [1, 2, 3])\n" +"\n" +"options:\n" +" -h, --help show this help message and exit\n" +" --foo FOO FOO! (default: 42)" + +#: ../../library/argparse.rst:379 +msgid "" +":class:`MetavarTypeHelpFormatter` uses the name of the type_ argument for " +"each argument as the display name for its values (rather than using the " +"dest_ as the regular formatter does)::" +msgstr "" + +#: ../../library/argparse.rst:383 +msgid "" +">>> parser = argparse.ArgumentParser(\n" +"... prog='PROG',\n" +"... formatter_class=argparse.MetavarTypeHelpFormatter)\n" +">>> parser.add_argument('--foo', type=int)\n" +">>> parser.add_argument('bar', type=float)\n" +">>> parser.print_help()\n" +"usage: PROG [-h] [--foo int] float\n" +"\n" +"positional arguments:\n" +" float\n" +"\n" +"options:\n" +" -h, --help show this help message and exit\n" +" --foo int" +msgstr "" +">>> parser = argparse.ArgumentParser(\n" +"... prog='PROG',\n" +"... formatter_class=argparse.MetavarTypeHelpFormatter)\n" +">>> parser.add_argument('--foo', type=int)\n" +">>> parser.add_argument('bar', type=float)\n" +">>> parser.print_help()\n" +"usage: PROG [-h] [--foo int] float\n" +"\n" +"positional arguments:\n" +" float\n" +"\n" +"options:\n" +" -h, --help show this help message and exit\n" +" --foo int" + +#: ../../library/argparse.rst:400 +msgid "prefix_chars" +msgstr "prefix_chars" + +#: ../../library/argparse.rst:402 +msgid "" +"Most command-line options will use ``-`` as the prefix, e.g. ``-f/--foo``. " +"Parsers that need to support different or additional prefix characters, e.g. " +"for options like ``+f`` or ``/foo``, may specify them using the " +"``prefix_chars=`` argument to the :class:`ArgumentParser` constructor::" +msgstr "" + +#: ../../library/argparse.rst:408 +msgid "" +">>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='-+')\n" +">>> parser.add_argument('+f')\n" +">>> parser.add_argument('++bar')\n" +">>> parser.parse_args('+f X ++bar Y'.split())\n" +"Namespace(bar='Y', f='X')" +msgstr "" +">>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='-+')\n" +">>> parser.add_argument('+f')\n" +">>> parser.add_argument('++bar')\n" +">>> parser.parse_args('+f X ++bar Y'.split())\n" +"Namespace(bar='Y', f='X')" + +#: ../../library/argparse.rst:414 +msgid "" +"The ``prefix_chars=`` argument defaults to ``'-'``. Supplying a set of " +"characters that does not include ``-`` will cause ``-f/--foo`` options to be " +"disallowed." +msgstr "" + +#: ../../library/argparse.rst:420 +msgid "fromfile_prefix_chars" +msgstr "fromfile_prefix_chars" + +#: ../../library/argparse.rst:422 +msgid "" +"Sometimes, when dealing with a particularly long argument list, it may make " +"sense to keep the list of arguments in a file rather than typing it out at " +"the command line. If the ``fromfile_prefix_chars=`` argument is given to " +"the :class:`ArgumentParser` constructor, then arguments that start with any " +"of the specified characters will be treated as files, and will be replaced " +"by the arguments they contain. For example::" +msgstr "" + +#: ../../library/argparse.rst:429 +msgid "" +">>> with open('args.txt', 'w', encoding=sys.getfilesystemencoding()) as fp:\n" +"... fp.write('-f\\nbar')\n" +"...\n" +">>> parser = argparse.ArgumentParser(fromfile_prefix_chars='@')\n" +">>> parser.add_argument('-f')\n" +">>> parser.parse_args(['-f', 'foo', '@args.txt'])\n" +"Namespace(f='bar')" +msgstr "" +">>> with open('args.txt', 'w', encoding=sys.getfilesystemencoding()) as fp:\n" +"... fp.write('-f\\nbar')\n" +"...\n" +">>> parser = argparse.ArgumentParser(fromfile_prefix_chars='@')\n" +">>> parser.add_argument('-f')\n" +">>> parser.parse_args(['-f', 'foo', '@args.txt'])\n" +"Namespace(f='bar')" + +#: ../../library/argparse.rst:437 +msgid "" +"Arguments read from a file must be one per line by default (but see also :" +"meth:`~ArgumentParser.convert_arg_line_to_args`) and are treated as if they " +"were in the same place as the original file referencing argument on the " +"command line. So in the example above, the expression ``['-f', 'foo', " +"'@args.txt']`` is considered equivalent to the expression ``['-f', 'foo', '-" +"f', 'bar']``." +msgstr "" + +#: ../../library/argparse.rst:445 +msgid "" +"Empty lines are treated as empty strings (``''``), which are allowed as " +"values but not as arguments. Empty lines that are read as arguments will " +"result in an \"unrecognized arguments\" error." +msgstr "" + +#: ../../library/argparse.rst:449 +msgid "" +":class:`ArgumentParser` uses :term:`filesystem encoding and error handler` " +"to read the file containing arguments." +msgstr "" + +#: ../../library/argparse.rst:452 +msgid "" +"The ``fromfile_prefix_chars=`` argument defaults to ``None``, meaning that " +"arguments will never be treated as file references." +msgstr "" + +#: ../../library/argparse.rst:455 +msgid "" +":class:`ArgumentParser` changed encoding and errors to read arguments files " +"from default (e.g. :func:`locale.getpreferredencoding(False) ` and ``\"strict\"``) to the :term:`filesystem encoding " +"and error handler`. Arguments file should be encoded in UTF-8 instead of " +"ANSI Codepage on Windows." +msgstr "" + +#: ../../library/argparse.rst:463 +msgid "argument_default" +msgstr "argument_default" + +#: ../../library/argparse.rst:465 +msgid "" +"Generally, argument defaults are specified either by passing a default to :" +"meth:`~ArgumentParser.add_argument` or by calling the :meth:`~ArgumentParser." +"set_defaults` methods with a specific set of name-value pairs. Sometimes " +"however, it may be useful to specify a single parser-wide default for " +"arguments. This can be accomplished by passing the ``argument_default=`` " +"keyword argument to :class:`ArgumentParser`. For example, to globally " +"suppress attribute creation on :meth:`~ArgumentParser.parse_args` calls, we " +"supply ``argument_default=SUPPRESS``::" +msgstr "" + +#: ../../library/argparse.rst:474 +msgid "" +">>> parser = argparse.ArgumentParser(argument_default=argparse.SUPPRESS)\n" +">>> parser.add_argument('--foo')\n" +">>> parser.add_argument('bar', nargs='?')\n" +">>> parser.parse_args(['--foo', '1', 'BAR'])\n" +"Namespace(bar='BAR', foo='1')\n" +">>> parser.parse_args([])\n" +"Namespace()" +msgstr "" +">>> parser = argparse.ArgumentParser(argument_default=argparse.SUPPRESS)\n" +">>> parser.add_argument('--foo')\n" +">>> parser.add_argument('bar', nargs='?')\n" +">>> parser.parse_args(['--foo', '1', 'BAR'])\n" +"Namespace(bar='BAR', foo='1')\n" +">>> parser.parse_args([])\n" +"Namespace()" + +#: ../../library/argparse.rst:485 +msgid "allow_abbrev" +msgstr "allow_abbrev" + +#: ../../library/argparse.rst:487 +msgid "" +"Normally, when you pass an argument list to the :meth:`~ArgumentParser." +"parse_args` method of an :class:`ArgumentParser`, it :ref:`recognizes " +"abbreviations ` of long options." +msgstr "" + +#: ../../library/argparse.rst:491 +msgid "This feature can be disabled by setting ``allow_abbrev`` to ``False``::" +msgstr "" + +#: ../../library/argparse.rst:493 +msgid "" +">>> parser = argparse.ArgumentParser(prog='PROG', allow_abbrev=False)\n" +">>> parser.add_argument('--foobar', action='store_true')\n" +">>> parser.add_argument('--foonley', action='store_false')\n" +">>> parser.parse_args(['--foon'])\n" +"usage: PROG [-h] [--foobar] [--foonley]\n" +"PROG: error: unrecognized arguments: --foon" +msgstr "" +">>> parser = argparse.ArgumentParser(prog='PROG', allow_abbrev=False)\n" +">>> parser.add_argument('--foobar', action='store_true')\n" +">>> parser.add_argument('--foonley', action='store_false')\n" +">>> parser.parse_args(['--foon'])\n" +"usage: PROG [-h] [--foobar] [--foonley]\n" +"PROG: error: unrecognized arguments: --foon" + +#: ../../library/argparse.rst:504 +msgid "conflict_handler" +msgstr "conflict_handler" + +#: ../../library/argparse.rst:506 +msgid "" +":class:`ArgumentParser` objects do not allow two actions with the same " +"option string. By default, :class:`ArgumentParser` objects raise an " +"exception if an attempt is made to create an argument with an option string " +"that is already in use::" +msgstr "" + +#: ../../library/argparse.rst:511 +msgid "" +">>> parser = argparse.ArgumentParser(prog='PROG')\n" +">>> parser.add_argument('-f', '--foo', help='old foo help')\n" +">>> parser.add_argument('--foo', help='new foo help')\n" +"Traceback (most recent call last):\n" +" ..\n" +"ArgumentError: argument --foo: conflicting option string(s): --foo" +msgstr "" +">>> parser = argparse.ArgumentParser(prog='PROG')\n" +">>> parser.add_argument('-f', '--foo', help='old foo help')\n" +">>> parser.add_argument('--foo', help='new foo help')\n" +"Traceback (most recent call last):\n" +" ..\n" +"ArgumentError: argument --foo: conflicting option string(s): --foo" + +#: ../../library/argparse.rst:518 +msgid "" +"Sometimes (e.g. when using parents_) it may be useful to simply override any " +"older arguments with the same option string. To get this behavior, the " +"value ``'resolve'`` can be supplied to the ``conflict_handler=`` argument " +"of :class:`ArgumentParser`::" +msgstr "" + +#: ../../library/argparse.rst:523 +msgid "" +">>> parser = argparse.ArgumentParser(prog='PROG', " +"conflict_handler='resolve')\n" +">>> parser.add_argument('-f', '--foo', help='old foo help')\n" +">>> parser.add_argument('--foo', help='new foo help')\n" +">>> parser.print_help()\n" +"usage: PROG [-h] [-f FOO] [--foo FOO]\n" +"\n" +"options:\n" +" -h, --help show this help message and exit\n" +" -f FOO old foo help\n" +" --foo FOO new foo help" +msgstr "" +">>> parser = argparse.ArgumentParser(prog='PROG', " +"conflict_handler='resolve')\n" +">>> parser.add_argument('-f', '--foo', help='old foo help')\n" +">>> parser.add_argument('--foo', help='new foo help')\n" +">>> parser.print_help()\n" +"usage: PROG [-h] [-f FOO] [--foo FOO]\n" +"\n" +"options:\n" +" -h, --help show this help message and exit\n" +" -f FOO old foo help\n" +" --foo FOO new foo help" + +#: ../../library/argparse.rst:534 +msgid "" +"Note that :class:`ArgumentParser` objects only remove an action if all of " +"its option strings are overridden. So, in the example above, the old ``-f/--" +"foo`` action is retained as the ``-f`` action, because only the ``--foo`` " +"option string was overridden." +msgstr "" + +#: ../../library/argparse.rst:541 +msgid "add_help" +msgstr "add_help" + +#: ../../library/argparse.rst:543 +msgid "" +"By default, :class:`ArgumentParser` objects add an option which simply " +"displays the parser's help message. If ``-h`` or ``--help`` is supplied at " +"the command line, the :class:`!ArgumentParser` help will be printed." +msgstr "" + +#: ../../library/argparse.rst:547 +msgid "" +"Occasionally, it may be useful to disable the addition of this help option. " +"This can be achieved by passing ``False`` as the ``add_help=`` argument to :" +"class:`ArgumentParser`::" +msgstr "" + +#: ../../library/argparse.rst:551 +msgid "" +">>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)\n" +">>> parser.add_argument('--foo', help='foo help')\n" +">>> parser.print_help()\n" +"usage: PROG [--foo FOO]\n" +"\n" +"options:\n" +" --foo FOO foo help" +msgstr "" +">>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)\n" +">>> parser.add_argument('--foo', help='foo help')\n" +">>> parser.print_help()\n" +"usage: PROG [--foo FOO]\n" +"\n" +"options:\n" +" --foo FOO foo help" + +#: ../../library/argparse.rst:559 +msgid "" +"The help option is typically ``-h/--help``. The exception to this is if the " +"``prefix_chars=`` is specified and does not include ``-``, in which case ``-" +"h`` and ``--help`` are not valid options. In this case, the first character " +"in ``prefix_chars`` is used to prefix the help options::" +msgstr "" + +#: ../../library/argparse.rst:565 +msgid "" +">>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='+/')\n" +">>> parser.print_help()\n" +"usage: PROG [+h]\n" +"\n" +"options:\n" +" +h, ++help show this help message and exit" +msgstr "" +">>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='+/')\n" +">>> parser.print_help()\n" +"usage: PROG [+h]\n" +"\n" +"options:\n" +" +h, ++help show this help message and exit" + +#: ../../library/argparse.rst:574 +msgid "exit_on_error" +msgstr "exit_on_error" + +#: ../../library/argparse.rst:576 +msgid "" +"Normally, when you pass an invalid argument list to the :meth:" +"`~ArgumentParser.parse_args` method of an :class:`ArgumentParser`, it will " +"print a *message* to :data:`sys.stderr` and exit with a status code of 2." +msgstr "" + +#: ../../library/argparse.rst:580 +msgid "" +"If the user would like to catch errors manually, the feature can be enabled " +"by setting ``exit_on_error`` to ``False``::" +msgstr "" + +#: ../../library/argparse.rst:583 +msgid "" +">>> parser = argparse.ArgumentParser(exit_on_error=False)\n" +">>> parser.add_argument('--integers', type=int)\n" +"_StoreAction(option_strings=['--integers'], dest='integers', nargs=None, " +"const=None, default=None, type=, choices=None, help=None, " +"metavar=None)\n" +">>> try:\n" +"... parser.parse_args('--integers a'.split())\n" +"... except argparse.ArgumentError:\n" +"... print('Catching an argumentError')\n" +"...\n" +"Catching an argumentError" +msgstr "" +">>> parser = argparse.ArgumentParser(exit_on_error=False)\n" +">>> parser.add_argument('--integers', type=int)\n" +"_StoreAction(option_strings=['--integers'], dest='integers', nargs=None, " +"const=None, default=None, type=, choices=None, help=None, " +"metavar=None)\n" +">>> try:\n" +"... parser.parse_args('--integers a'.split())\n" +"... except argparse.ArgumentError:\n" +"... print('Catching an argumentError')\n" +"...\n" +"Catching an argumentError" + +#: ../../library/argparse.rst:596 +msgid "suggest_on_error" +msgstr "suggest_on_error" + +#: ../../library/argparse.rst:598 +msgid "" +"By default, when a user passes an invalid argument choice or subparser " +"name, :class:`ArgumentParser` will exit with error info and list the " +"permissible argument choices (if specified) or subparser names as part of " +"the error message." +msgstr "" + +#: ../../library/argparse.rst:602 +msgid "" +"If the user would like to enable suggestions for mistyped argument choices " +"and subparser names, the feature can be enabled by setting " +"``suggest_on_error`` to ``True``. Note that this only applies for arguments " +"when the choices specified are strings::" +msgstr "" + +#: ../../library/argparse.rst:607 +msgid "" +">>> parser = argparse.ArgumentParser(description='Process some integers.',\n" +" suggest_on_error=True)\n" +">>> parser.add_argument('--action', choices=['sum', 'max'])\n" +">>> parser.add_argument('integers', metavar='N', type=int, nargs='+',\n" +"... help='an integer for the accumulator')\n" +">>> parser.parse_args(['--action', 'sumn', 1, 2, 3])\n" +"tester.py: error: argument --action: invalid choice: 'sumn', maybe you meant " +"'sum'? (choose from 'sum', 'max')" +msgstr "" +">>> parser = argparse.ArgumentParser(description='Process some integers.',\n" +" suggest_on_error=True)\n" +">>> parser.add_argument('--action', choices=['sum', 'max'])\n" +">>> parser.add_argument('integers', metavar='N', type=int, nargs='+',\n" +"... help='an integer for the accumulator')\n" +">>> parser.parse_args(['--action', 'sumn', 1, 2, 3])\n" +"tester.py: error: argument --action: invalid choice: 'sumn', maybe you meant " +"'sum'? (choose from 'sum', 'max')" + +#: ../../library/argparse.rst:615 +msgid "" +"If you're writing code that needs to be compatible with older Python " +"versions and want to opportunistically use ``suggest_on_error`` when it's " +"available, you can set it as an attribute after initializing the parser " +"instead of using the keyword argument::" +msgstr "" + +#: ../../library/argparse.rst:620 +msgid "" +">>> parser = argparse.ArgumentParser(description='Process some integers.')\n" +">>> parser.suggest_on_error = True" +msgstr "" +">>> parser = argparse.ArgumentParser(description='Process some integers.')\n" +">>> parser.suggest_on_error = True" + +#: ../../library/argparse.rst:627 +msgid "color" +msgstr "" + +#: ../../library/argparse.rst:629 +msgid "" +"By default, the help message is printed in color using `ANSI escape " +"sequences `__. If you want " +"plain text help messages, you can disable this :ref:`in your local " +"environment `, or in the argument parser itself " +"by setting ``color`` to ``False``::" +msgstr "" + +#: ../../library/argparse.rst:635 +msgid "" +">>> parser = argparse.ArgumentParser(description='Process some integers.',\n" +"... color=False)\n" +">>> parser.add_argument('--action', choices=['sum', 'max'])\n" +">>> parser.add_argument('integers', metavar='N', type=int, nargs='+',\n" +"... help='an integer for the accumulator')\n" +">>> parser.parse_args(['--help'])" +msgstr "" +">>> parser = argparse.ArgumentParser(description='Process some integers.',\n" +"... color=False)\n" +">>> parser.add_argument('--action', choices=['sum', 'max'])\n" +">>> parser.add_argument('integers', metavar='N', type=int, nargs='+',\n" +"... help='an integer for the accumulator')\n" +">>> parser.parse_args(['--help'])" + +#: ../../library/argparse.rst:642 +msgid "" +"Note that when ``color=True``, colored output depends on both environment " +"variables and terminal capabilities. However, if ``color=False``, colored " +"output is always disabled, even if environment variables like " +"``FORCE_COLOR`` are set." +msgstr "" + +#: ../../library/argparse.rst:649 +msgid "" +"Error messages will include color codes when redirecting stderr to a file. " +"To avoid this, set the |NO_COLOR|_ or :envvar:`PYTHON_COLORS` environment " +"variable (for example, ``NO_COLOR=1 python script.py 2> errors.txt``)." +msgstr "" + +#: ../../library/argparse.rst:658 +msgid "The add_argument() method" +msgstr "add_argument() 方法" + +#: ../../library/argparse.rst:664 +msgid "" +"Define how a single command-line argument should be parsed. Each parameter " +"has its own more detailed description below, but in short they are:" +msgstr "" + +#: ../../library/argparse.rst:667 +msgid "" +"`name or flags`_ - Either a name or a list of option strings, e.g. ``'foo'`` " +"or ``'-f', '--foo'``." +msgstr "" + +#: ../../library/argparse.rst:670 +msgid "" +"action_ - The basic type of action to be taken when this argument is " +"encountered at the command line." +msgstr "" + +#: ../../library/argparse.rst:673 +msgid "nargs_ - The number of command-line arguments that should be consumed." +msgstr "" + +#: ../../library/argparse.rst:675 +msgid "" +"const_ - A constant value required by some action_ and nargs_ selections." +msgstr "" + +#: ../../library/argparse.rst:677 +msgid "" +"default_ - The value produced if the argument is absent from the command " +"line and if it is absent from the namespace object." +msgstr "" + +#: ../../library/argparse.rst:680 +msgid "" +"type_ - The type to which the command-line argument should be converted." +msgstr "" + +#: ../../library/argparse.rst:682 +msgid "choices_ - A sequence of the allowable values for the argument." +msgstr "" + +#: ../../library/argparse.rst:684 +msgid "" +"required_ - Whether or not the command-line option may be omitted (optionals " +"only)." +msgstr "" + +#: ../../library/argparse.rst:687 +msgid "help_ - A brief description of what the argument does." +msgstr "" + +#: ../../library/argparse.rst:689 +msgid "metavar_ - A name for the argument in usage messages." +msgstr "" + +#: ../../library/argparse.rst:691 +msgid "" +"dest_ - The name of the attribute to be added to the object returned by :" +"meth:`parse_args`." +msgstr "" + +#: ../../library/argparse.rst:694 +msgid "deprecated_ - Whether or not use of the argument is deprecated." +msgstr "" + +#: ../../library/argparse.rst:702 +msgid "name or flags" +msgstr "name or flags" + +#: ../../library/argparse.rst:704 +msgid "" +"The :meth:`~ArgumentParser.add_argument` method must know whether an " +"optional argument, like ``-f`` or ``--foo``, or a positional argument, like " +"a list of filenames, is expected. The first arguments passed to :meth:" +"`~ArgumentParser.add_argument` must therefore be either a series of flags, " +"or a simple argument name." +msgstr "" + +#: ../../library/argparse.rst:710 +msgid "For example, an optional argument could be created like::" +msgstr "" + +#: ../../library/argparse.rst:712 +msgid ">>> parser.add_argument('-f', '--foo')" +msgstr ">>> parser.add_argument('-f', '--foo')" + +#: ../../library/argparse.rst:714 +msgid "while a positional argument could be created like::" +msgstr "" + +#: ../../library/argparse.rst:716 +msgid ">>> parser.add_argument('bar')" +msgstr ">>> parser.add_argument('bar')" + +#: ../../library/argparse.rst:718 +msgid "" +"When :meth:`~ArgumentParser.parse_args` is called, optional arguments will " +"be identified by the ``-`` prefix, and the remaining arguments will be " +"assumed to be positional::" +msgstr "" + +#: ../../library/argparse.rst:722 +msgid "" +">>> parser = argparse.ArgumentParser(prog='PROG')\n" +">>> parser.add_argument('-f', '--foo')\n" +">>> parser.add_argument('bar')\n" +">>> parser.parse_args(['BAR'])\n" +"Namespace(bar='BAR', foo=None)\n" +">>> parser.parse_args(['BAR', '--foo', 'FOO'])\n" +"Namespace(bar='BAR', foo='FOO')\n" +">>> parser.parse_args(['--foo', 'FOO'])\n" +"usage: PROG [-h] [-f FOO] bar\n" +"PROG: error: the following arguments are required: bar" +msgstr "" +">>> parser = argparse.ArgumentParser(prog='PROG')\n" +">>> parser.add_argument('-f', '--foo')\n" +">>> parser.add_argument('bar')\n" +">>> parser.parse_args(['BAR'])\n" +"Namespace(bar='BAR', foo=None)\n" +">>> parser.parse_args(['BAR', '--foo', 'FOO'])\n" +"Namespace(bar='BAR', foo='FOO')\n" +">>> parser.parse_args(['--foo', 'FOO'])\n" +"usage: PROG [-h] [-f FOO] bar\n" +"PROG: error: the following arguments are required: bar" + +#: ../../library/argparse.rst:733 +msgid "" +"By default, :mod:`!argparse` automatically handles the internal naming and " +"display names of arguments, simplifying the process without requiring " +"additional configuration. As such, you do not need to specify the dest_ and " +"metavar_ parameters. The dest_ parameter defaults to the argument name with " +"underscores ``_`` replacing hyphens ``-`` . The metavar_ parameter defaults " +"to the upper-cased name. For example::" +msgstr "" + +#: ../../library/argparse.rst:741 +msgid "" +">>> parser = argparse.ArgumentParser(prog='PROG')\n" +">>> parser.add_argument('--foo-bar')\n" +">>> parser.parse_args(['--foo-bar', 'FOO-BAR'])\n" +"Namespace(foo_bar='FOO-BAR')\n" +">>> parser.print_help()\n" +"usage: [-h] [--foo-bar FOO-BAR]\n" +"\n" +"optional arguments:\n" +" -h, --help show this help message and exit\n" +" --foo-bar FOO-BAR" +msgstr "" +">>> parser = argparse.ArgumentParser(prog='PROG')\n" +">>> parser.add_argument('--foo-bar')\n" +">>> parser.parse_args(['--foo-bar', 'FOO-BAR'])\n" +"Namespace(foo_bar='FOO-BAR')\n" +">>> parser.print_help()\n" +"usage: [-h] [--foo-bar FOO-BAR]\n" +"\n" +"optional arguments:\n" +" -h, --help show this help message and exit\n" +" --foo-bar FOO-BAR" + +#: ../../library/argparse.rst:756 +msgid "action" +msgstr "action" + +#: ../../library/argparse.rst:758 +msgid "" +":class:`ArgumentParser` objects associate command-line arguments with " +"actions. These actions can do just about anything with the command-line " +"arguments associated with them, though most actions simply add an attribute " +"to the object returned by :meth:`~ArgumentParser.parse_args`. The " +"``action`` keyword argument specifies how the command-line arguments should " +"be handled. The supplied actions are:" +msgstr "" + +#: ../../library/argparse.rst:764 +msgid "" +"``'store'`` - This just stores the argument's value. This is the default " +"action." +msgstr "" + +#: ../../library/argparse.rst:767 +msgid "" +"``'store_const'`` - This stores the value specified by the const_ keyword " +"argument; note that the const_ keyword argument defaults to ``None``. The " +"``'store_const'`` action is most commonly used with optional arguments that " +"specify some sort of flag. For example::" +msgstr "" + +#: ../../library/argparse.rst:772 +msgid "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('--foo', action='store_const', const=42)\n" +">>> parser.parse_args(['--foo'])\n" +"Namespace(foo=42)" +msgstr "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('--foo', action='store_const', const=42)\n" +">>> parser.parse_args(['--foo'])\n" +"Namespace(foo=42)" + +#: ../../library/argparse.rst:777 +msgid "" +"``'store_true'`` and ``'store_false'`` - These are special cases of " +"``'store_const'`` that respectively store the values ``True`` and ``False`` " +"with default values of ``False`` and ``True``::" +msgstr "" + +#: ../../library/argparse.rst:782 +msgid "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('--foo', action='store_true')\n" +">>> parser.add_argument('--bar', action='store_false')\n" +">>> parser.add_argument('--baz', action='store_false')\n" +">>> parser.parse_args('--foo --bar'.split())\n" +"Namespace(foo=True, bar=False, baz=True)" +msgstr "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('--foo', action='store_true')\n" +">>> parser.add_argument('--bar', action='store_false')\n" +">>> parser.add_argument('--baz', action='store_false')\n" +">>> parser.parse_args('--foo --bar'.split())\n" +"Namespace(foo=True, bar=False, baz=True)" + +#: ../../library/argparse.rst:789 +msgid "" +"``'append'`` - This appends each argument value to a list. It is useful for " +"allowing an option to be specified multiple times. If the default value is a " +"non-empty list, the parsed value will start with the default list's elements " +"and any values from the command line will be appended after those default " +"values. Example usage::" +msgstr "" + +#: ../../library/argparse.rst:795 +msgid "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('--foo', action='append', default=['0'])\n" +">>> parser.parse_args('--foo 1 --foo 2'.split())\n" +"Namespace(foo=['0', '1', '2'])" +msgstr "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('--foo', action='append', default=['0'])\n" +">>> parser.parse_args('--foo 1 --foo 2'.split())\n" +"Namespace(foo=['0', '1', '2'])" + +#: ../../library/argparse.rst:800 +msgid "" +"``'append_const'`` - This appends the value specified by the const_ keyword " +"argument to a list; note that the const_ keyword argument defaults to " +"``None``. The ``'append_const'`` action is typically useful when multiple " +"arguments need to store constants to the same list. For example::" +msgstr "" + +#: ../../library/argparse.rst:806 +msgid "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('--str', dest='types', action='append_const', " +"const=str)\n" +">>> parser.add_argument('--int', dest='types', action='append_const', " +"const=int)\n" +">>> parser.parse_args('--str --int'.split())\n" +"Namespace(types=[, ])" +msgstr "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('--str', dest='types', action='append_const', " +"const=str)\n" +">>> parser.add_argument('--int', dest='types', action='append_const', " +"const=int)\n" +">>> parser.parse_args('--str --int'.split())\n" +"Namespace(types=[, ])" + +#: ../../library/argparse.rst:812 +msgid "" +"``'extend'`` - This appends each item from a multi-value argument to a list. " +"The ``'extend'`` action is typically used with the nargs_ keyword argument " +"value ``'+'`` or ``'*'``. Note that when nargs_ is ``None`` (the default) or " +"``'?'``, each character of the argument string will be appended to the list. " +"Example usage::" +msgstr "" + +#: ../../library/argparse.rst:820 +msgid "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument(\"--foo\", action=\"extend\", nargs=\"+\", " +"type=str)\n" +">>> parser.parse_args([\"--foo\", \"f1\", \"--foo\", \"f2\", \"f3\", " +"\"f4\"])\n" +"Namespace(foo=['f1', 'f2', 'f3', 'f4'])" +msgstr "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument(\"--foo\", action=\"extend\", nargs=\"+\", " +"type=str)\n" +">>> parser.parse_args([\"--foo\", \"f1\", \"--foo\", \"f2\", \"f3\", " +"\"f4\"])\n" +"Namespace(foo=['f1', 'f2', 'f3', 'f4'])" + +#: ../../library/argparse.rst:827 +msgid "" +"``'count'`` - This counts the number of times an argument occurs. For " +"example, this is useful for increasing verbosity levels::" +msgstr "" + +#: ../../library/argparse.rst:830 +msgid "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('--verbose', '-v', action='count', default=0)\n" +">>> parser.parse_args(['-vvv'])\n" +"Namespace(verbose=3)" +msgstr "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('--verbose', '-v', action='count', default=0)\n" +">>> parser.parse_args(['-vvv'])\n" +"Namespace(verbose=3)" + +#: ../../library/argparse.rst:835 +msgid "Note, the *default* will be ``None`` unless explicitly set to *0*." +msgstr "" + +#: ../../library/argparse.rst:837 +msgid "" +"``'help'`` - This prints a complete help message for all the options in the " +"current parser and then exits. By default a help action is automatically " +"added to the parser. See :class:`ArgumentParser` for details of how the " +"output is created." +msgstr "" + +#: ../../library/argparse.rst:842 +msgid "" +"``'version'`` - This expects a ``version=`` keyword argument in the :meth:" +"`~ArgumentParser.add_argument` call, and prints version information and " +"exits when invoked::" +msgstr "" + +#: ../../library/argparse.rst:846 +msgid "" +">>> import argparse\n" +">>> parser = argparse.ArgumentParser(prog='PROG')\n" +">>> parser.add_argument('--version', action='version', version='%(prog)s " +"2.0')\n" +">>> parser.parse_args(['--version'])\n" +"PROG 2.0" +msgstr "" +">>> import argparse\n" +">>> parser = argparse.ArgumentParser(prog='PROG')\n" +">>> parser.add_argument('--version', action='version', version='%(prog)s " +"2.0')\n" +">>> parser.parse_args(['--version'])\n" +"PROG 2.0" + +#: ../../library/argparse.rst:852 +msgid "" +"You may also specify an arbitrary action by passing an :class:`Action` " +"subclass (e.g. :class:`BooleanOptionalAction`) or other object that " +"implements the same interface. Only actions that consume command-line " +"arguments (e.g. ``'store'``, ``'append'``, ``'extend'``, or custom actions " +"with non-zero ``nargs``) can be used with positional arguments." +msgstr "" +"你也可以傳遞一個 :class:`Action` 子類別（例如 :class:" +"`BooleanOptionalAction`）或實作相同介面的其他物件。只有會消耗命令列引數的 " +"action（例如 ``'store'``、``'append'``、``'extend'`` 或 ``nargs`` 不為零的自" +"定義 action）可以被用於位置引數。" + +#: ../../library/argparse.rst:858 +msgid "" +"The recommended way to create a custom action is to extend :class:`Action`, " +"overriding the :meth:`!__call__` method and optionally the :meth:`!__init__` " +"and :meth:`!format_usage` methods. You can also register custom actions " +"using the :meth:`~ArgumentParser.register` method and reference them by " +"their registered name." +msgstr "" + +#: ../../library/argparse.rst:863 +msgid "An example of a custom action::" +msgstr "自訂 action 的範例： ::" + +#: ../../library/argparse.rst:865 +msgid "" +">>> class FooAction(argparse.Action):\n" +"... def __init__(self, option_strings, dest, nargs=None, **kwargs):\n" +"... if nargs is not None:\n" +"... raise ValueError(\"nargs not allowed\")\n" +"... super().__init__(option_strings, dest, **kwargs)\n" +"... def __call__(self, parser, namespace, values, option_string=None):\n" +"... print('%r %r %r' % (namespace, values, option_string))\n" +"... setattr(namespace, self.dest, values)\n" +"...\n" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('--foo', action=FooAction)\n" +">>> parser.add_argument('bar', action=FooAction)\n" +">>> args = parser.parse_args('1 --foo 2'.split())\n" +"Namespace(bar=None, foo=None) '1' None\n" +"Namespace(bar='1', foo=None) '2' '--foo'\n" +">>> args\n" +"Namespace(bar='1', foo='2')" +msgstr "" +">>> class FooAction(argparse.Action):\n" +"... def __init__(self, option_strings, dest, nargs=None, **kwargs):\n" +"... if nargs is not None:\n" +"... raise ValueError(\"nargs not allowed\")\n" +"... super().__init__(option_strings, dest, **kwargs)\n" +"... def __call__(self, parser, namespace, values, option_string=None):\n" +"... print('%r %r %r' % (namespace, values, option_string))\n" +"... setattr(namespace, self.dest, values)\n" +"...\n" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('--foo', action=FooAction)\n" +">>> parser.add_argument('bar', action=FooAction)\n" +">>> args = parser.parse_args('1 --foo 2'.split())\n" +"Namespace(bar=None, foo=None) '1' None\n" +"Namespace(bar='1', foo=None) '2' '--foo'\n" +">>> args\n" +"Namespace(bar='1', foo='2')" + +#: ../../library/argparse.rst:883 +msgid "For more details, see :class:`Action`." +msgstr "更多詳情請見 :class:`Action`。" + +#: ../../library/argparse.rst:889 +msgid "nargs" +msgstr "nargs" + +#: ../../library/argparse.rst:891 +msgid "" +":class:`ArgumentParser` objects usually associate a single command-line " +"argument with a single action to be taken. The ``nargs`` keyword argument " +"associates a different number of command-line arguments with a single " +"action. See also :ref:`specifying-ambiguous-arguments`. The supported values " +"are:" +msgstr "" + +#: ../../library/argparse.rst:896 +msgid "" +"``N`` (an integer). ``N`` arguments from the command line will be gathered " +"together into a list. For example::" +msgstr "" + +#: ../../library/argparse.rst:899 +msgid "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('--foo', nargs=2)\n" +">>> parser.add_argument('bar', nargs=1)\n" +">>> parser.parse_args('c --foo a b'.split())\n" +"Namespace(bar=['c'], foo=['a', 'b'])" +msgstr "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('--foo', nargs=2)\n" +">>> parser.add_argument('bar', nargs=1)\n" +">>> parser.parse_args('c --foo a b'.split())\n" +"Namespace(bar=['c'], foo=['a', 'b'])" + +#: ../../library/argparse.rst:905 +msgid "" +"Note that ``nargs=1`` produces a list of one item. This is different from " +"the default, in which the item is produced by itself." +msgstr "" + +#: ../../library/argparse.rst:910 +msgid "" +"``'?'``. One argument will be consumed from the command line if possible, " +"and produced as a single item. If no command-line argument is present, the " +"value from default_ will be produced. Note that for optional arguments, " +"there is an additional case - the option string is present but not followed " +"by a command-line argument. In this case the value from const_ will be " +"produced. Some examples to illustrate this::" +msgstr "" + +#: ../../library/argparse.rst:917 +msgid "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('--foo', nargs='?', const='c', default='d')\n" +">>> parser.add_argument('bar', nargs='?', default='d')\n" +">>> parser.parse_args(['XX', '--foo', 'YY'])\n" +"Namespace(bar='XX', foo='YY')\n" +">>> parser.parse_args(['XX', '--foo'])\n" +"Namespace(bar='XX', foo='c')\n" +">>> parser.parse_args([])\n" +"Namespace(bar='d', foo='d')" +msgstr "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('--foo', nargs='?', const='c', default='d')\n" +">>> parser.add_argument('bar', nargs='?', default='d')\n" +">>> parser.parse_args(['XX', '--foo', 'YY'])\n" +"Namespace(bar='XX', foo='YY')\n" +">>> parser.parse_args(['XX', '--foo'])\n" +"Namespace(bar='XX', foo='c')\n" +">>> parser.parse_args([])\n" +"Namespace(bar='d', foo='d')" + +#: ../../library/argparse.rst:927 +msgid "" +"One of the more common uses of ``nargs='?'`` is to allow optional input and " +"output files::" +msgstr "" + +#: ../../library/argparse.rst:930 +msgid "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('infile', nargs='?')\n" +">>> parser.add_argument('outfile', nargs='?')\n" +">>> parser.parse_args(['input.txt', 'output.txt'])\n" +"Namespace(infile='input.txt', outfile='output.txt')\n" +">>> parser.parse_args(['input.txt'])\n" +"Namespace(infile='input.txt', outfile=None)\n" +">>> parser.parse_args([])\n" +"Namespace(infile=None, outfile=None)" +msgstr "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('infile', nargs='?')\n" +">>> parser.add_argument('outfile', nargs='?')\n" +">>> parser.parse_args(['input.txt', 'output.txt'])\n" +"Namespace(infile='input.txt', outfile='output.txt')\n" +">>> parser.parse_args(['input.txt'])\n" +"Namespace(infile='input.txt', outfile=None)\n" +">>> parser.parse_args([])\n" +"Namespace(infile=None, outfile=None)" + +#: ../../library/argparse.rst:942 +msgid "" +"``'*'``. All command-line arguments present are gathered into a list. Note " +"that it generally doesn't make much sense to have more than one positional " +"argument with ``nargs='*'``, but multiple optional arguments with " +"``nargs='*'`` is possible. For example::" +msgstr "" + +#: ../../library/argparse.rst:947 +msgid "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('--foo', nargs='*')\n" +">>> parser.add_argument('--bar', nargs='*')\n" +">>> parser.add_argument('baz', nargs='*')\n" +">>> parser.parse_args('a b --foo x y --bar 1 2'.split())\n" +"Namespace(bar=['1', '2'], baz=['a', 'b'], foo=['x', 'y'])" +msgstr "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('--foo', nargs='*')\n" +">>> parser.add_argument('--bar', nargs='*')\n" +">>> parser.add_argument('baz', nargs='*')\n" +">>> parser.parse_args('a b --foo x y --bar 1 2'.split())\n" +"Namespace(bar=['1', '2'], baz=['a', 'b'], foo=['x', 'y'])" + +#: ../../library/argparse.rst:956 +msgid "" +"``'+'``. Just like ``'*'``, all command-line arguments present are gathered " +"into a list. Additionally, an error message will be generated if there " +"wasn't at least one command-line argument present. For example::" +msgstr "" + +#: ../../library/argparse.rst:960 +msgid "" +">>> parser = argparse.ArgumentParser(prog='PROG')\n" +">>> parser.add_argument('foo', nargs='+')\n" +">>> parser.parse_args(['a', 'b'])\n" +"Namespace(foo=['a', 'b'])\n" +">>> parser.parse_args([])\n" +"usage: PROG [-h] foo [foo ...]\n" +"PROG: error: the following arguments are required: foo" +msgstr "" +">>> parser = argparse.ArgumentParser(prog='PROG')\n" +">>> parser.add_argument('foo', nargs='+')\n" +">>> parser.parse_args(['a', 'b'])\n" +"Namespace(foo=['a', 'b'])\n" +">>> parser.parse_args([])\n" +"usage: PROG [-h] foo [foo ...]\n" +"PROG: error: the following arguments are required: foo" + +#: ../../library/argparse.rst:968 +msgid "" +"If the ``nargs`` keyword argument is not provided, the number of arguments " +"consumed is determined by the action_. Generally this means a single " +"command-line argument will be consumed and a single item (not a list) will " +"be produced. Actions that do not consume command-line arguments (e.g. " +"``'store_const'``) set ``nargs=0``." +msgstr "" + +#: ../../library/argparse.rst:978 +msgid "const" +msgstr "const" + +#: ../../library/argparse.rst:980 +msgid "" +"The ``const`` argument of :meth:`~ArgumentParser.add_argument` is used to " +"hold constant values that are not read from the command line but are " +"required for the various :class:`ArgumentParser` actions. The two most " +"common uses of it are:" +msgstr "" + +#: ../../library/argparse.rst:984 +msgid "" +"When :meth:`~ArgumentParser.add_argument` is called with " +"``action='store_const'`` or ``action='append_const'``. These actions add " +"the ``const`` value to one of the attributes of the object returned by :meth:" +"`~ArgumentParser.parse_args`. See the action_ description for examples. If " +"``const`` is not provided to :meth:`~ArgumentParser.add_argument`, it will " +"receive a default value of ``None``." +msgstr "" + +#: ../../library/argparse.rst:992 +msgid "" +"When :meth:`~ArgumentParser.add_argument` is called with option strings " +"(like ``-f`` or ``--foo``) and ``nargs='?'``. This creates an optional " +"argument that can be followed by zero or one command-line arguments. When " +"parsing the command line, if the option string is encountered with no " +"command-line argument following it, the value from ``const`` will be used. " +"See the nargs_ description for examples." +msgstr "" + +#: ../../library/argparse.rst:999 +msgid "" +"``const=None`` by default, including when ``action='append_const'`` or " +"``action='store_const'``." +msgstr "" + +#: ../../library/argparse.rst:1006 +msgid "default" +msgstr "default" + +#: ../../library/argparse.rst:1008 +msgid "" +"All optional arguments and some positional arguments may be omitted at the " +"command line. The ``default`` keyword argument of :meth:`~ArgumentParser." +"add_argument`, whose value defaults to ``None``, specifies what value should " +"be used if the command-line argument is not present. For optional arguments, " +"the ``default`` value is used when the option string was not present at the " +"command line::" +msgstr "" + +#: ../../library/argparse.rst:1015 +msgid "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('--foo', default=42)\n" +">>> parser.parse_args(['--foo', '2'])\n" +"Namespace(foo='2')\n" +">>> parser.parse_args([])\n" +"Namespace(foo=42)" +msgstr "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('--foo', default=42)\n" +">>> parser.parse_args(['--foo', '2'])\n" +"Namespace(foo='2')\n" +">>> parser.parse_args([])\n" +"Namespace(foo=42)" + +#: ../../library/argparse.rst:1022 +msgid "" +"If the target namespace already has an attribute set, the action *default* " +"will not overwrite it::" +msgstr "" + +#: ../../library/argparse.rst:1025 +msgid "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('--foo', default=42)\n" +">>> parser.parse_args([], namespace=argparse.Namespace(foo=101))\n" +"Namespace(foo=101)" +msgstr "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('--foo', default=42)\n" +">>> parser.parse_args([], namespace=argparse.Namespace(foo=101))\n" +"Namespace(foo=101)" + +#: ../../library/argparse.rst:1030 +msgid "" +"If the ``default`` value is a string, the parser parses the value as if it " +"were a command-line argument. In particular, the parser applies any type_ " +"conversion argument, if provided, before setting the attribute on the :class:" +"`Namespace` return value. Otherwise, the parser uses the value as is::" +msgstr "" + +#: ../../library/argparse.rst:1035 +msgid "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('--length', default='10', type=int)\n" +">>> parser.add_argument('--width', default=10.5, type=int)\n" +">>> parser.parse_args()\n" +"Namespace(length=10, width=10.5)" +msgstr "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('--length', default='10', type=int)\n" +">>> parser.add_argument('--width', default=10.5, type=int)\n" +">>> parser.parse_args()\n" +"Namespace(length=10, width=10.5)" + +#: ../../library/argparse.rst:1041 +msgid "" +"For positional arguments with nargs_ equal to ``?`` or ``*``, the " +"``default`` value is used when no command-line argument was present::" +msgstr "" + +#: ../../library/argparse.rst:1044 +msgid "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('foo', nargs='?', default=42)\n" +">>> parser.parse_args(['a'])\n" +"Namespace(foo='a')\n" +">>> parser.parse_args([])\n" +"Namespace(foo=42)" +msgstr "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('foo', nargs='?', default=42)\n" +">>> parser.parse_args(['a'])\n" +"Namespace(foo='a')\n" +">>> parser.parse_args([])\n" +"Namespace(foo=42)" + +#: ../../library/argparse.rst:1051 +msgid "" +"For required_ arguments, the ``default`` value is ignored. For example, this " +"applies to positional arguments with nargs_ values other than ``?`` or " +"``*``, or optional arguments marked as ``required=True``." +msgstr "" + +#: ../../library/argparse.rst:1055 +msgid "" +"Providing ``default=argparse.SUPPRESS`` causes no attribute to be added if " +"the command-line argument was not present::" +msgstr "" + +#: ../../library/argparse.rst:1058 +msgid "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('--foo', default=argparse.SUPPRESS)\n" +">>> parser.parse_args([])\n" +"Namespace()\n" +">>> parser.parse_args(['--foo', '1'])\n" +"Namespace(foo='1')" +msgstr "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('--foo', default=argparse.SUPPRESS)\n" +">>> parser.parse_args([])\n" +"Namespace()\n" +">>> parser.parse_args(['--foo', '1'])\n" +"Namespace(foo='1')" + +#: ../../library/argparse.rst:1069 +msgid "type" +msgstr "type" + +#: ../../library/argparse.rst:1071 +msgid "" +"By default, the parser reads command-line arguments in as simple strings. " +"However, quite often the command-line string should instead be interpreted " +"as another type, such as a :class:`float` or :class:`int`. The ``type`` " +"keyword for :meth:`~ArgumentParser.add_argument` allows any necessary type-" +"checking and type conversions to be performed." +msgstr "" + +#: ../../library/argparse.rst:1077 +msgid "" +"If the type_ keyword is used with the default_ keyword, the type converter " +"is only applied if the default is a string." +msgstr "" + +#: ../../library/argparse.rst:1080 +msgid "" +"The argument to ``type`` can be a callable that accepts a single string or " +"the name of a registered type (see :meth:`~ArgumentParser.register`) If the " +"function raises :exc:`ArgumentTypeError`, :exc:`TypeError`, or :exc:" +"`ValueError`, the exception is caught and a nicely formatted error message " +"is displayed. Other exception types are not handled." +msgstr "" + +#: ../../library/argparse.rst:1086 +msgid "Common built-in types and functions can be used as type converters:" +msgstr "" + +#: ../../library/argparse.rst:1088 +msgid "" +"import argparse\n" +"import pathlib\n" +"\n" +"parser = argparse.ArgumentParser()\n" +"parser.add_argument('count', type=int)\n" +"parser.add_argument('distance', type=float)\n" +"parser.add_argument('street', type=ascii)\n" +"parser.add_argument('code_point', type=ord)\n" +"parser.add_argument('datapath', type=pathlib.Path)" +msgstr "" +"import argparse\n" +"import pathlib\n" +"\n" +"parser = argparse.ArgumentParser()\n" +"parser.add_argument('count', type=int)\n" +"parser.add_argument('distance', type=float)\n" +"parser.add_argument('street', type=ascii)\n" +"parser.add_argument('code_point', type=ord)\n" +"parser.add_argument('datapath', type=pathlib.Path)" + +#: ../../library/argparse.rst:1100 +msgid "User defined functions can be used as well:" +msgstr "" + +#: ../../library/argparse.rst:1102 +msgid "" +">>> def hyphenated(string):\n" +"... return '-'.join([word[:4] for word in string.casefold().split()])\n" +"...\n" +">>> parser = argparse.ArgumentParser()\n" +">>> _ = parser.add_argument('short_title', type=hyphenated)\n" +">>> parser.parse_args(['\"The Tale of Two Cities\"'])\n" +"Namespace(short_title='\"the-tale-of-two-citi')" +msgstr "" +">>> def hyphenated(string):\n" +"... return '-'.join([word[:4] for word in string.casefold().split()])\n" +"...\n" +">>> parser = argparse.ArgumentParser()\n" +">>> _ = parser.add_argument('short_title', type=hyphenated)\n" +">>> parser.parse_args(['\"The Tale of Two Cities\"'])\n" +"Namespace(short_title='\"the-tale-of-two-citi')" + +#: ../../library/argparse.rst:1112 +msgid "" +"The :func:`bool` function is not recommended as a type converter. All it " +"does is convert empty strings to ``False`` and non-empty strings to " +"``True``. This is usually not what is desired." +msgstr "" + +#: ../../library/argparse.rst:1116 +msgid "" +"In general, the ``type`` keyword is a convenience that should only be used " +"for simple conversions that can only raise one of the three supported " +"exceptions. Anything with more interesting error-handling or resource " +"management should be done downstream after the arguments are parsed." +msgstr "" + +#: ../../library/argparse.rst:1121 +msgid "" +"For example, JSON or YAML conversions have complex error cases that require " +"better reporting than can be given by the ``type`` keyword. A :exc:`~json." +"JSONDecodeError` would not be well formatted and a :exc:`FileNotFoundError` " +"exception would not be handled at all." +msgstr "" + +#: ../../library/argparse.rst:1126 +msgid "" +"Even :class:`~argparse.FileType` has its limitations for use with the " +"``type`` keyword. If one argument uses :class:`~argparse.FileType` and then " +"a subsequent argument fails, an error is reported but the file is not " +"automatically closed. In this case, it would be better to wait until after " +"the parser has run and then use the :keyword:`with`-statement to manage the " +"files." +msgstr "" + +#: ../../library/argparse.rst:1133 +msgid "" +"For type checkers that simply check against a fixed set of values, consider " +"using the choices_ keyword instead." +msgstr "" + +#: ../../library/argparse.rst:1140 +msgid "choices" +msgstr "choices" + +#: ../../library/argparse.rst:1142 +msgid "" +"Some command-line arguments should be selected from a restricted set of " +"values. These can be handled by passing a sequence object as the *choices* " +"keyword argument to :meth:`~ArgumentParser.add_argument`. When the command " +"line is parsed, argument values will be checked, and an error message will " +"be displayed if the argument was not one of the acceptable values::" +msgstr "" + +#: ../../library/argparse.rst:1148 +msgid "" +">>> parser = argparse.ArgumentParser(prog='game.py')\n" +">>> parser.add_argument('move', choices=['rock', 'paper', 'scissors'])\n" +">>> parser.parse_args(['rock'])\n" +"Namespace(move='rock')\n" +">>> parser.parse_args(['fire'])\n" +"usage: game.py [-h] {rock,paper,scissors}\n" +"game.py: error: argument move: invalid choice: 'fire' (choose from 'rock',\n" +"'paper', 'scissors')" +msgstr "" +">>> parser = argparse.ArgumentParser(prog='game.py')\n" +">>> parser.add_argument('move', choices=['rock', 'paper', 'scissors'])\n" +">>> parser.parse_args(['rock'])\n" +"Namespace(move='rock')\n" +">>> parser.parse_args(['fire'])\n" +"usage: game.py [-h] {rock,paper,scissors}\n" +"game.py: error: argument move: invalid choice: 'fire' (choose from 'rock',\n" +"'paper', 'scissors')" + +#: ../../library/argparse.rst:1157 +msgid "" +"Any sequence can be passed as the *choices* value, so :class:`list` " +"objects, :class:`tuple` objects, and custom sequences are all supported." +msgstr "" + +#: ../../library/argparse.rst:1160 +msgid "" +"Use of :class:`enum.Enum` is not recommended because it is difficult to " +"control its appearance in usage, help, and error messages." +msgstr "" + +#: ../../library/argparse.rst:1163 +msgid "" +"Note that *choices* are checked after any type_ conversions have been " +"performed, so objects in *choices* should match the type_ specified. This " +"can make *choices* appear unfamiliar in usage, help, or error messages." +msgstr "" + +#: ../../library/argparse.rst:1168 +msgid "" +"To keep *choices* user-friendly, consider a custom type wrapper that " +"converts and formats values, or omit type_ and handle conversion in your " +"application code." +msgstr "" + +#: ../../library/argparse.rst:1172 +msgid "" +"Formatted choices override the default *metavar* which is normally derived " +"from *dest*. This is usually what you want because the user never sees the " +"*dest* parameter. If this display isn't desirable (perhaps because there " +"are many choices), just specify an explicit metavar_." +msgstr "" + +#: ../../library/argparse.rst:1181 +msgid "required" +msgstr "required" + +#: ../../library/argparse.rst:1183 +msgid "" +"In general, the :mod:`!argparse` module assumes that flags like ``-f`` and " +"``--bar`` indicate *optional* arguments, which can always be omitted at the " +"command line. To make an option *required*, ``True`` can be specified for " +"the ``required=`` keyword argument to :meth:`~ArgumentParser.add_argument`::" +msgstr "" + +#: ../../library/argparse.rst:1188 +msgid "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('--foo', required=True)\n" +">>> parser.parse_args(['--foo', 'BAR'])\n" +"Namespace(foo='BAR')\n" +">>> parser.parse_args([])\n" +"usage: [-h] --foo FOO\n" +": error: the following arguments are required: --foo" +msgstr "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('--foo', required=True)\n" +">>> parser.parse_args(['--foo', 'BAR'])\n" +"Namespace(foo='BAR')\n" +">>> parser.parse_args([])\n" +"usage: [-h] --foo FOO\n" +": error: the following arguments are required: --foo" + +#: ../../library/argparse.rst:1196 +msgid "" +"As the example shows, if an option is marked as ``required``, :meth:" +"`~ArgumentParser.parse_args` will report an error if that option is not " +"present at the command line." +msgstr "" + +#: ../../library/argparse.rst:1202 +msgid "" +"Required options are generally considered bad form because users expect " +"*options* to be *optional*, and thus they should be avoided when possible." +msgstr "" + +#: ../../library/argparse.rst:1209 +msgid "help" +msgstr "help" + +#: ../../library/argparse.rst:1211 +msgid "" +"The ``help`` value is a string containing a brief description of the " +"argument. When a user requests help (usually by using ``-h`` or ``--help`` " +"at the command line), these ``help`` descriptions will be displayed with " +"each argument." +msgstr "" + +#: ../../library/argparse.rst:1216 +msgid "" +"The ``help`` strings can include various format specifiers to avoid " +"repetition of things like the program name or the argument default_. The " +"available specifiers include the program name, ``%(prog)s`` and most keyword " +"arguments to :meth:`~ArgumentParser.add_argument`, e.g. ``%(default)s``, " +"``%(type)s``, etc.::" +msgstr "" + +#: ../../library/argparse.rst:1221 +msgid "" +">>> parser = argparse.ArgumentParser(prog='frobble')\n" +">>> parser.add_argument('bar', nargs='?', type=int, default=42,\n" +"... help='the bar to %(prog)s (default: %(default)s)')\n" +">>> parser.print_help()\n" +"usage: frobble [-h] [bar]\n" +"\n" +"positional arguments:\n" +" bar the bar to frobble (default: 42)\n" +"\n" +"options:\n" +" -h, --help show this help message and exit" +msgstr "" +">>> parser = argparse.ArgumentParser(prog='frobble')\n" +">>> parser.add_argument('bar', nargs='?', type=int, default=42,\n" +"... help='the bar to %(prog)s (default: %(default)s)')\n" +">>> parser.print_help()\n" +"usage: frobble [-h] [bar]\n" +"\n" +"positional arguments:\n" +" bar the bar to frobble (default: 42)\n" +"\n" +"options:\n" +" -h, --help show this help message and exit" + +#: ../../library/argparse.rst:1233 +msgid "" +"As the help string supports %-formatting, if you want a literal ``%`` to " +"appear in the help string, you must escape it as ``%%``." +msgstr "" + +#: ../../library/argparse.rst:1236 +msgid "" +":mod:`!argparse` supports silencing the help entry for certain options, by " +"setting the ``help`` value to ``argparse.SUPPRESS``::" +msgstr "" + +#: ../../library/argparse.rst:1239 +msgid "" +">>> parser = argparse.ArgumentParser(prog='frobble')\n" +">>> parser.add_argument('--foo', help=argparse.SUPPRESS)\n" +">>> parser.print_help()\n" +"usage: frobble [-h]\n" +"\n" +"options:\n" +" -h, --help show this help message and exit" +msgstr "" +">>> parser = argparse.ArgumentParser(prog='frobble')\n" +">>> parser.add_argument('--foo', help=argparse.SUPPRESS)\n" +">>> parser.print_help()\n" +"usage: frobble [-h]\n" +"\n" +"options:\n" +" -h, --help show this help message and exit" + +#: ../../library/argparse.rst:1251 +msgid "metavar" +msgstr "metavar" + +#: ../../library/argparse.rst:1253 +msgid "" +"When :class:`ArgumentParser` generates help messages, it needs some way to " +"refer to each expected argument. By default, :class:`!ArgumentParser` " +"objects use the dest_ value as the \"name\" of each object. By default, for " +"positional argument actions, the dest_ value is used directly, and for " +"optional argument actions, the dest_ value is uppercased. So, a single " +"positional argument with ``dest='bar'`` will be referred to as ``bar``. A " +"single optional argument ``--foo`` that should be followed by a single " +"command-line argument will be referred to as ``FOO``. An example::" +msgstr "" + +#: ../../library/argparse.rst:1262 +msgid "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('--foo')\n" +">>> parser.add_argument('bar')\n" +">>> parser.parse_args('X --foo Y'.split())\n" +"Namespace(bar='X', foo='Y')\n" +">>> parser.print_help()\n" +"usage: [-h] [--foo FOO] bar\n" +"\n" +"positional arguments:\n" +" bar\n" +"\n" +"options:\n" +" -h, --help show this help message and exit\n" +" --foo FOO" +msgstr "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('--foo')\n" +">>> parser.add_argument('bar')\n" +">>> parser.parse_args('X --foo Y'.split())\n" +"Namespace(bar='X', foo='Y')\n" +">>> parser.print_help()\n" +"usage: [-h] [--foo FOO] bar\n" +"\n" +"positional arguments:\n" +" bar\n" +"\n" +"options:\n" +" -h, --help show this help message and exit\n" +" --foo FOO" + +#: ../../library/argparse.rst:1277 +msgid "An alternative name can be specified with ``metavar``::" +msgstr "" + +#: ../../library/argparse.rst:1279 +msgid "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('--foo', metavar='YYY')\n" +">>> parser.add_argument('bar', metavar='XXX')\n" +">>> parser.parse_args('X --foo Y'.split())\n" +"Namespace(bar='X', foo='Y')\n" +">>> parser.print_help()\n" +"usage: [-h] [--foo YYY] XXX\n" +"\n" +"positional arguments:\n" +" XXX\n" +"\n" +"options:\n" +" -h, --help show this help message and exit\n" +" --foo YYY" +msgstr "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('--foo', metavar='YYY')\n" +">>> parser.add_argument('bar', metavar='XXX')\n" +">>> parser.parse_args('X --foo Y'.split())\n" +"Namespace(bar='X', foo='Y')\n" +">>> parser.print_help()\n" +"usage: [-h] [--foo YYY] XXX\n" +"\n" +"positional arguments:\n" +" XXX\n" +"\n" +"options:\n" +" -h, --help show this help message and exit\n" +" --foo YYY" + +#: ../../library/argparse.rst:1294 +msgid "" +"Note that ``metavar`` only changes the *displayed* name - the name of the " +"attribute on the :meth:`~ArgumentParser.parse_args` object is still " +"determined by the dest_ value." +msgstr "" + +#: ../../library/argparse.rst:1298 +msgid "" +"Different values of ``nargs`` may cause the metavar to be used multiple " +"times. Providing a tuple to ``metavar`` specifies a different display for " +"each of the arguments::" +msgstr "" + +#: ../../library/argparse.rst:1302 +msgid "" +">>> parser = argparse.ArgumentParser(prog='PROG')\n" +">>> parser.add_argument('-x', nargs=2)\n" +">>> parser.add_argument('--foo', nargs=2, metavar=('bar', 'baz'))\n" +">>> parser.print_help()\n" +"usage: PROG [-h] [-x X X] [--foo bar baz]\n" +"\n" +"options:\n" +" -h, --help show this help message and exit\n" +" -x X X\n" +" --foo bar baz" +msgstr "" +">>> parser = argparse.ArgumentParser(prog='PROG')\n" +">>> parser.add_argument('-x', nargs=2)\n" +">>> parser.add_argument('--foo', nargs=2, metavar=('bar', 'baz'))\n" +">>> parser.print_help()\n" +"usage: PROG [-h] [-x X X] [--foo bar baz]\n" +"\n" +"options:\n" +" -h, --help show this help message and exit\n" +" -x X X\n" +" --foo bar baz" + +#: ../../library/argparse.rst:1317 +msgid "dest" +msgstr "dest" + +#: ../../library/argparse.rst:1319 +msgid "" +"Most :class:`ArgumentParser` actions add some value as an attribute of the " +"object returned by :meth:`~ArgumentParser.parse_args`. The name of this " +"attribute is determined by the ``dest`` keyword argument of :meth:" +"`~ArgumentParser.add_argument`. For positional argument actions, ``dest`` " +"is normally supplied as the first argument to :meth:`~ArgumentParser." +"add_argument`::" +msgstr "" + +#: ../../library/argparse.rst:1326 +msgid "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('bar')\n" +">>> parser.parse_args(['XXX'])\n" +"Namespace(bar='XXX')" +msgstr "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('bar')\n" +">>> parser.parse_args(['XXX'])\n" +"Namespace(bar='XXX')" + +#: ../../library/argparse.rst:1331 +msgid "" +"For optional argument actions, the value of ``dest`` is normally inferred " +"from the option strings. :class:`ArgumentParser` generates the value of " +"``dest`` by taking the first long option string and stripping away the " +"initial ``--`` string. If no long option strings were supplied, ``dest`` " +"will be derived from the first short option string by stripping the initial " +"``-`` character. Any internal ``-`` characters will be converted to ``_`` " +"characters to make sure the string is a valid attribute name. The examples " +"below illustrate this behavior::" +msgstr "" + +#: ../../library/argparse.rst:1340 +msgid "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('-f', '--foo-bar', '--foo')\n" +">>> parser.add_argument('-x', '-y')\n" +">>> parser.parse_args('-f 1 -x 2'.split())\n" +"Namespace(foo_bar='1', x='2')\n" +">>> parser.parse_args('--foo 1 -y 2'.split())\n" +"Namespace(foo_bar='1', x='2')" +msgstr "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('-f', '--foo-bar', '--foo')\n" +">>> parser.add_argument('-x', '-y')\n" +">>> parser.parse_args('-f 1 -x 2'.split())\n" +"Namespace(foo_bar='1', x='2')\n" +">>> parser.parse_args('--foo 1 -y 2'.split())\n" +"Namespace(foo_bar='1', x='2')" + +#: ../../library/argparse.rst:1348 +msgid "``dest`` allows a custom attribute name to be provided::" +msgstr "" + +#: ../../library/argparse.rst:1350 +msgid "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('--foo', dest='bar')\n" +">>> parser.parse_args('--foo XXX'.split())\n" +"Namespace(bar='XXX')" +msgstr "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('--foo', dest='bar')\n" +">>> parser.parse_args('--foo XXX'.split())\n" +"Namespace(bar='XXX')" + +#: ../../library/argparse.rst:1359 +msgid "deprecated" +msgstr "deprecated" + +#: ../../library/argparse.rst:1361 +msgid "" +"During a project's lifetime, some arguments may need to be removed from the " +"command line. Before removing them, you should inform your users that the " +"arguments are deprecated and will be removed. The ``deprecated`` keyword " +"argument of :meth:`~ArgumentParser.add_argument`, which defaults to " +"``False``, specifies if the argument is deprecated and will be removed in " +"the future. For arguments, if ``deprecated`` is ``True``, then a warning " +"will be printed to :data:`sys.stderr` when the argument is used::" +msgstr "" + +#: ../../library/argparse.rst:1371 +msgid "" +">>> import argparse\n" +">>> parser = argparse.ArgumentParser(prog='snake.py')\n" +">>> parser.add_argument('--legs', default=0, type=int, deprecated=True)\n" +">>> parser.parse_args([])\n" +"Namespace(legs=0)\n" +">>> parser.parse_args(['--legs', '4'])\n" +"snake.py: warning: option '--legs' is deprecated\n" +"Namespace(legs=4)" +msgstr "" +">>> import argparse\n" +">>> parser = argparse.ArgumentParser(prog='snake.py')\n" +">>> parser.add_argument('--legs', default=0, type=int, deprecated=True)\n" +">>> parser.parse_args([])\n" +"Namespace(legs=0)\n" +">>> parser.parse_args(['--legs', '4'])\n" +"snake.py: warning: option '--legs' is deprecated\n" +"Namespace(legs=4)" + +#: ../../library/argparse.rst:1384 +msgid "Action classes" +msgstr "Action 類別" + +#: ../../library/argparse.rst:1386 +msgid "" +":class:`!Action` classes implement the Action API, a callable which returns " +"a callable which processes arguments from the command-line. Any object which " +"follows this API may be passed as the ``action`` parameter to :meth:" +"`~ArgumentParser.add_argument`." +msgstr "" + +#: ../../library/argparse.rst:1395 +msgid "" +":class:`!Action` objects are used by an :class:`ArgumentParser` to represent " +"the information needed to parse a single argument from one or more strings " +"from the command line. The :class:`!Action` class must accept the two " +"positional arguments plus any keyword arguments passed to :meth:" +"`ArgumentParser.add_argument` except for the ``action`` itself." +msgstr "" + +#: ../../library/argparse.rst:1401 +msgid "" +"Instances of :class:`!Action` (or return value of any callable to the " +"``action`` parameter) should have attributes :attr:`!dest`, :attr:`!" +"option_strings`, :attr:`!default`, :attr:`!type`, :attr:`!required`, :attr:`!" +"help`, etc. defined. The easiest way to ensure these attributes are defined " +"is to call :meth:`!Action.__init__`." +msgstr "" + +#: ../../library/argparse.rst:1409 +msgid "" +":class:`!Action` instances should be callable, so subclasses must override " +"the :meth:`!__call__` method, which should accept four parameters:" +msgstr "" + +#: ../../library/argparse.rst:1412 +msgid "" +"*parser* - The :class:`ArgumentParser` object which contains this action." +msgstr "" + +#: ../../library/argparse.rst:1414 +msgid "" +"*namespace* - The :class:`Namespace` object that will be returned by :meth:" +"`~ArgumentParser.parse_args`. Most actions add an attribute to this object " +"using :func:`setattr`." +msgstr "" + +#: ../../library/argparse.rst:1418 +msgid "" +"*values* - The associated command-line arguments, with any type conversions " +"applied. Type conversions are specified with the type_ keyword argument to :" +"meth:`~ArgumentParser.add_argument`." +msgstr "" + +#: ../../library/argparse.rst:1422 +msgid "" +"*option_string* - The option string that was used to invoke this action. The " +"``option_string`` argument is optional, and will be absent if the action is " +"associated with a positional argument." +msgstr "" + +#: ../../library/argparse.rst:1426 +msgid "" +"The :meth:`!__call__` method may perform arbitrary actions, but will " +"typically set attributes on the ``namespace`` based on ``dest`` and " +"``values``." +msgstr "" + +#: ../../library/argparse.rst:1431 +msgid "" +":class:`!Action` subclasses can define a :meth:`!format_usage` method that " +"takes no argument and return a string which will be used when printing the " +"usage of the program. If such method is not provided, a sensible default " +"will be used." +msgstr "" + +#: ../../library/argparse.rst:1437 +msgid "" +"A subclass of :class:`Action` for handling boolean flags with positive and " +"negative options. Adding a single argument such as ``--foo`` automatically " +"creates both ``--foo`` and ``--no-foo`` options, storing ``True`` and " +"``False`` respectively::" +msgstr "" + +#: ../../library/argparse.rst:1442 +msgid "" +">>> import argparse\n" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('--foo', action=argparse.BooleanOptionalAction)\n" +">>> parser.parse_args(['--no-foo'])\n" +"Namespace(foo=False)" +msgstr "" +">>> import argparse\n" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('--foo', action=argparse.BooleanOptionalAction)\n" +">>> parser.parse_args(['--no-foo'])\n" +"Namespace(foo=False)" + +#: ../../library/argparse.rst:1452 +msgid "The parse_args() method" +msgstr "parse_args() 方法" + +#: ../../library/argparse.rst:1456 +msgid "" +"Convert argument strings to objects and assign them as attributes of the " +"namespace. Return the populated namespace." +msgstr "" + +#: ../../library/argparse.rst:1459 +msgid "" +"Previous calls to :meth:`add_argument` determine exactly what objects are " +"created and how they are assigned. See the documentation for :meth:`!" +"add_argument` for details." +msgstr "" + +#: ../../library/argparse.rst:1463 +msgid "" +"args_ - List of strings to parse. The default is taken from :data:`sys." +"argv`." +msgstr "" + +#: ../../library/argparse.rst:1466 +msgid "" +"namespace_ - An object to take the attributes. The default is a new empty :" +"class:`Namespace` object." +msgstr "" + +#: ../../library/argparse.rst:1471 +msgid "Option value syntax" +msgstr "" + +#: ../../library/argparse.rst:1473 +msgid "" +"The :meth:`~ArgumentParser.parse_args` method supports several ways of " +"specifying the value of an option (if it takes one). In the simplest case, " +"the option and its value are passed as two separate arguments::" +msgstr "" + +#: ../../library/argparse.rst:1477 +msgid "" +">>> parser = argparse.ArgumentParser(prog='PROG')\n" +">>> parser.add_argument('-x')\n" +">>> parser.add_argument('--foo')\n" +">>> parser.parse_args(['-x', 'X'])\n" +"Namespace(foo=None, x='X')\n" +">>> parser.parse_args(['--foo', 'FOO'])\n" +"Namespace(foo='FOO', x=None)" +msgstr "" +">>> parser = argparse.ArgumentParser(prog='PROG')\n" +">>> parser.add_argument('-x')\n" +">>> parser.add_argument('--foo')\n" +">>> parser.parse_args(['-x', 'X'])\n" +"Namespace(foo=None, x='X')\n" +">>> parser.parse_args(['--foo', 'FOO'])\n" +"Namespace(foo='FOO', x=None)" + +#: ../../library/argparse.rst:1485 +msgid "" +"For long options (options with names longer than a single character), the " +"option and value can also be passed as a single command-line argument, using " +"``=`` to separate them::" +msgstr "" + +#: ../../library/argparse.rst:1489 +msgid "" +">>> parser.parse_args(['--foo=FOO'])\n" +"Namespace(foo='FOO', x=None)" +msgstr "" +">>> parser.parse_args(['--foo=FOO'])\n" +"Namespace(foo='FOO', x=None)" + +#: ../../library/argparse.rst:1492 +msgid "" +"For short options (options only one character long), the option and its " +"value can be concatenated::" +msgstr "" + +#: ../../library/argparse.rst:1495 +msgid "" +">>> parser.parse_args(['-xX'])\n" +"Namespace(foo=None, x='X')" +msgstr "" +">>> parser.parse_args(['-xX'])\n" +"Namespace(foo=None, x='X')" + +#: ../../library/argparse.rst:1498 +msgid "" +"Several short options can be joined together, using only a single ``-`` " +"prefix, as long as only the last option (or none of them) requires a value::" +msgstr "" + +#: ../../library/argparse.rst:1501 +msgid "" +">>> parser = argparse.ArgumentParser(prog='PROG')\n" +">>> parser.add_argument('-x', action='store_true')\n" +">>> parser.add_argument('-y', action='store_true')\n" +">>> parser.add_argument('-z')\n" +">>> parser.parse_args(['-xyzZ'])\n" +"Namespace(x=True, y=True, z='Z')" +msgstr "" +">>> parser = argparse.ArgumentParser(prog='PROG')\n" +">>> parser.add_argument('-x', action='store_true')\n" +">>> parser.add_argument('-y', action='store_true')\n" +">>> parser.add_argument('-z')\n" +">>> parser.parse_args(['-xyzZ'])\n" +"Namespace(x=True, y=True, z='Z')" + +#: ../../library/argparse.rst:1510 +msgid "Invalid arguments" +msgstr "無效引數" + +#: ../../library/argparse.rst:1512 +msgid "" +"While parsing the command line, :meth:`~ArgumentParser.parse_args` checks " +"for a variety of errors, including ambiguous options, invalid types, invalid " +"options, wrong number of positional arguments, etc. When it encounters such " +"an error, it exits and prints the error along with a usage message::" +msgstr "" + +#: ../../library/argparse.rst:1517 +msgid "" +">>> parser = argparse.ArgumentParser(prog='PROG')\n" +">>> parser.add_argument('--foo', type=int)\n" +">>> parser.add_argument('bar', nargs='?')\n" +"\n" +">>> # invalid type\n" +">>> parser.parse_args(['--foo', 'spam'])\n" +"usage: PROG [-h] [--foo FOO] [bar]\n" +"PROG: error: argument --foo: invalid int value: 'spam'\n" +"\n" +">>> # invalid option\n" +">>> parser.parse_args(['--bar'])\n" +"usage: PROG [-h] [--foo FOO] [bar]\n" +"PROG: error: no such option: --bar\n" +"\n" +">>> # wrong number of arguments\n" +">>> parser.parse_args(['spam', 'badger'])\n" +"usage: PROG [-h] [--foo FOO] [bar]\n" +"PROG: error: extra arguments found: badger" +msgstr "" +">>> parser = argparse.ArgumentParser(prog='PROG')\n" +">>> parser.add_argument('--foo', type=int)\n" +">>> parser.add_argument('bar', nargs='?')\n" +"\n" +">>> # 無效型別\n" +">>> parser.parse_args(['--foo', 'spam'])\n" +"usage: PROG [-h] [--foo FOO] [bar]\n" +"PROG: error: argument --foo: invalid int value: 'spam'\n" +"\n" +">>> # 無效選項\n" +">>> parser.parse_args(['--bar'])\n" +"usage: PROG [-h] [--foo FOO] [bar]\n" +"PROG: error: no such option: --bar\n" +"\n" +">>> # 錯誤引數數量\n" +">>> parser.parse_args(['spam', 'badger'])\n" +"usage: PROG [-h] [--foo FOO] [bar]\n" +"PROG: error: extra arguments found: badger" + +#: ../../library/argparse.rst:1538 +msgid "Arguments containing ``-``" +msgstr "包含 ``-`` 的引數" + +#: ../../library/argparse.rst:1540 +msgid "" +"The :meth:`~ArgumentParser.parse_args` method attempts to give errors " +"whenever the user has clearly made a mistake, but some situations are " +"inherently ambiguous. For example, the command-line argument ``-1`` could " +"either be an attempt to specify an option or an attempt to provide a " +"positional argument. The :meth:`~ArgumentParser.parse_args` method is " +"cautious here: positional arguments may only begin with ``-`` if they look " +"like negative numbers and there are no options in the parser that look like " +"negative numbers::" +msgstr "" + +#: ../../library/argparse.rst:1548 +msgid "" +">>> parser = argparse.ArgumentParser(prog='PROG')\n" +">>> parser.add_argument('-x')\n" +">>> parser.add_argument('foo', nargs='?')\n" +"\n" +">>> # no negative number options, so -1 is a positional argument\n" +">>> parser.parse_args(['-x', '-1'])\n" +"Namespace(foo=None, x='-1')\n" +"\n" +">>> # no negative number options, so -1 and -5 are positional arguments\n" +">>> parser.parse_args(['-x', '-1', '-5'])\n" +"Namespace(foo='-5', x='-1')\n" +"\n" +">>> parser = argparse.ArgumentParser(prog='PROG')\n" +">>> parser.add_argument('-1', dest='one')\n" +">>> parser.add_argument('foo', nargs='?')\n" +"\n" +">>> # negative number options present, so -1 is an option\n" +">>> parser.parse_args(['-1', 'X'])\n" +"Namespace(foo=None, one='X')\n" +"\n" +">>> # negative number options present, so -2 is an option\n" +">>> parser.parse_args(['-2'])\n" +"usage: PROG [-h] [-1 ONE] [foo]\n" +"PROG: error: no such option: -2\n" +"\n" +">>> # negative number options present, so both -1s are options\n" +">>> parser.parse_args(['-1', '-1'])\n" +"usage: PROG [-h] [-1 ONE] [foo]\n" +"PROG: error: argument -1: expected one argument" +msgstr "" + +#: ../../library/argparse.rst:1578 +msgid "" +"If you have positional arguments that must begin with ``-`` and don't look " +"like negative numbers, you can insert the pseudo-argument ``'--'`` which " +"tells :meth:`~ArgumentParser.parse_args` that everything after that is a " +"positional argument::" +msgstr "" + +#: ../../library/argparse.rst:1583 +msgid "" +">>> parser.parse_args(['--', '-f'])\n" +"Namespace(foo='-f', one=None)" +msgstr "" +">>> parser.parse_args(['--', '-f'])\n" +"Namespace(foo='-f', one=None)" + +#: ../../library/argparse.rst:1586 +msgid "" +"See also :ref:`the argparse howto on ambiguous arguments ` for more details." +msgstr "" + +#: ../../library/argparse.rst:1592 +msgid "Argument abbreviations (prefix matching)" +msgstr "引數縮寫 (前綴匹配)" + +#: ../../library/argparse.rst:1594 +msgid "" +"The :meth:`~ArgumentParser.parse_args` method :ref:`by default " +"` allows long options to be abbreviated to a prefix, if the " +"abbreviation is unambiguous (the prefix matches a unique option)::" +msgstr "" + +#: ../../library/argparse.rst:1598 +msgid "" +">>> parser = argparse.ArgumentParser(prog='PROG')\n" +">>> parser.add_argument('-bacon')\n" +">>> parser.add_argument('-badger')\n" +">>> parser.parse_args('-bac MMM'.split())\n" +"Namespace(bacon='MMM', badger=None)\n" +">>> parser.parse_args('-bad WOOD'.split())\n" +"Namespace(bacon=None, badger='WOOD')\n" +">>> parser.parse_args('-ba BA'.split())\n" +"usage: PROG [-h] [-bacon BACON] [-badger BADGER]\n" +"PROG: error: ambiguous option: -ba could match -badger, -bacon" +msgstr "" +">>> parser = argparse.ArgumentParser(prog='PROG')\n" +">>> parser.add_argument('-bacon')\n" +">>> parser.add_argument('-badger')\n" +">>> parser.parse_args('-bac MMM'.split())\n" +"Namespace(bacon='MMM', badger=None)\n" +">>> parser.parse_args('-bad WOOD'.split())\n" +"Namespace(bacon=None, badger='WOOD')\n" +">>> parser.parse_args('-ba BA'.split())\n" +"usage: PROG [-h] [-bacon BACON] [-badger BADGER]\n" +"PROG: error: ambiguous option: -ba could match -badger, -bacon" + +#: ../../library/argparse.rst:1609 +msgid "" +"An error is produced for arguments that could produce more than one options. " +"This feature can be disabled by setting :ref:`allow_abbrev` to ``False``." +msgstr "" + +#: ../../library/argparse.rst:1615 +msgid "Beyond ``sys.argv``" +msgstr "``sys.argv`` 之外" + +#: ../../library/argparse.rst:1617 +msgid "" +"Sometimes it may be useful to have an :class:`ArgumentParser` parse " +"arguments other than those of :data:`sys.argv`. This can be accomplished by " +"passing a list of strings to :meth:`~ArgumentParser.parse_args`. This is " +"useful for testing at the interactive prompt::" +msgstr "" + +#: ../../library/argparse.rst:1622 +msgid "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument(\n" +"... 'integers', metavar='int', type=int, choices=range(10),\n" +"... nargs='+', help='an integer in the range 0..9')\n" +">>> parser.add_argument(\n" +"... '--sum', dest='accumulate', action='store_const', const=sum,\n" +"... default=max, help='sum the integers (default: find the max)')\n" +">>> parser.parse_args(['1', '2', '3', '4'])\n" +"Namespace(accumulate=, integers=[1, 2, 3, 4])\n" +">>> parser.parse_args(['1', '2', '3', '4', '--sum'])\n" +"Namespace(accumulate=, integers=[1, 2, 3, 4])" +msgstr "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument(\n" +"... 'integers', metavar='int', type=int, choices=range(10),\n" +"... nargs='+', help='an integer in the range 0..9')\n" +">>> parser.add_argument(\n" +"... '--sum', dest='accumulate', action='store_const', const=sum,\n" +"... default=max, help='sum the integers (default: find the max)')\n" +">>> parser.parse_args(['1', '2', '3', '4'])\n" +"Namespace(accumulate=, integers=[1, 2, 3, 4])\n" +">>> parser.parse_args(['1', '2', '3', '4', '--sum'])\n" +"Namespace(accumulate=, integers=[1, 2, 3, 4])" + +#: ../../library/argparse.rst:1637 +msgid "The Namespace object" +msgstr "命名空間物件" + +#: ../../library/argparse.rst:1641 +msgid "" +"Simple class used by default by :meth:`~ArgumentParser.parse_args` to create " +"an object holding attributes and return it." +msgstr "" + +#: ../../library/argparse.rst:1644 +msgid "" +"This class is deliberately simple, just an :class:`object` subclass with a " +"readable string representation. If you prefer to have dict-like view of the " +"attributes, you can use the standard Python idiom, :func:`vars`::" +msgstr "" + +#: ../../library/argparse.rst:1648 +msgid "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('--foo')\n" +">>> args = parser.parse_args(['--foo', 'BAR'])\n" +">>> vars(args)\n" +"{'foo': 'BAR'}" +msgstr "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('--foo')\n" +">>> args = parser.parse_args(['--foo', 'BAR'])\n" +">>> vars(args)\n" +"{'foo': 'BAR'}" + +#: ../../library/argparse.rst:1654 +msgid "" +"It may also be useful to have an :class:`ArgumentParser` assign attributes " +"to an already existing object, rather than a new :class:`Namespace` object. " +"This can be achieved by specifying the ``namespace=`` keyword argument::" +msgstr "" + +#: ../../library/argparse.rst:1658 +msgid "" +">>> class C:\n" +"... pass\n" +"...\n" +">>> c = C()\n" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('--foo')\n" +">>> parser.parse_args(args=['--foo', 'BAR'], namespace=c)\n" +">>> c.foo\n" +"'BAR'" +msgstr "" +">>> class C:\n" +"... pass\n" +"...\n" +">>> c = C()\n" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('--foo')\n" +">>> parser.parse_args(args=['--foo', 'BAR'], namespace=c)\n" +">>> c.foo\n" +"'BAR'" + +#: ../../library/argparse.rst:1670 +msgid "Other utilities" +msgstr "" + +#: ../../library/argparse.rst:1673 +msgid "Subcommands" +msgstr "子命令" + +#: ../../library/argparse.rst:1680 +msgid "" +"Many programs split up their functionality into a number of subcommands, for " +"example, the ``svn`` program can invoke subcommands like ``svn checkout``, " +"``svn update``, and ``svn commit``. Splitting up functionality this way can " +"be a particularly good idea when a program performs several different " +"functions which require different kinds of command-line arguments. :class:" +"`ArgumentParser` supports the creation of such subcommands with the :meth:`!" +"add_subparsers` method. The :meth:`!add_subparsers` method is normally " +"called with no arguments and returns a special action object. This object " +"has a single method, :meth:`~_SubParsersAction.add_parser`, which takes a " +"command name and any :class:`!ArgumentParser` constructor arguments, and " +"returns an :class:`!ArgumentParser` object that can be modified as usual." +msgstr "" + +#: ../../library/argparse.rst:1692 +msgid "Description of parameters:" +msgstr "參數的解釋：" + +#: ../../library/argparse.rst:1694 +msgid "" +"*title* - title for the sub-parser group in help output; by default " +"\"subcommands\" if description is provided, otherwise uses title for " +"positional arguments" +msgstr "" + +#: ../../library/argparse.rst:1698 +msgid "" +"*description* - description for the sub-parser group in help output, by " +"default ``None``" +msgstr "" + +#: ../../library/argparse.rst:1701 +msgid "" +"*prog* - usage information that will be displayed with subcommand help, by " +"default the name of the program and any positional arguments before the " +"subparser argument" +msgstr "" + +#: ../../library/argparse.rst:1705 +msgid "" +"*parser_class* - class which will be used to create sub-parser instances, by " +"default the class of the current parser (e.g. :class:`ArgumentParser`)" +msgstr "" + +#: ../../library/argparse.rst:1708 +msgid "" +"action_ - the basic type of action to be taken when this argument is " +"encountered at the command line" +msgstr "" + +#: ../../library/argparse.rst:1711 +msgid "" +"dest_ - name of the attribute under which subcommand name will be stored; by " +"default ``None`` and no value is stored" +msgstr "" + +#: ../../library/argparse.rst:1714 +msgid "" +"required_ - Whether or not a subcommand must be provided, by default " +"``False`` (added in 3.7)" +msgstr "" + +#: ../../library/argparse.rst:1717 +msgid "help_ - help for sub-parser group in help output, by default ``None``" +msgstr "" + +#: ../../library/argparse.rst:1719 +msgid "" +"metavar_ - string presenting available subcommands in help; by default it is " +"``None`` and presents subcommands in form {cmd1, cmd2, ..}" +msgstr "" + +#: ../../library/argparse.rst:1722 +msgid "Some example usage::" +msgstr "一些使用範例： ::" + +#: ../../library/argparse.rst:1724 +msgid "" +">>> # create the top-level parser\n" +">>> parser = argparse.ArgumentParser(prog='PROG')\n" +">>> parser.add_argument('--foo', action='store_true', help='foo help')\n" +">>> subparsers = parser.add_subparsers(help='subcommand help')\n" +">>>\n" +">>> # create the parser for the \"a\" command\n" +">>> parser_a = subparsers.add_parser('a', help='a help')\n" +">>> parser_a.add_argument('bar', type=int, help='bar help')\n" +">>>\n" +">>> # create the parser for the \"b\" command\n" +">>> parser_b = subparsers.add_parser('b', help='b help')\n" +">>> parser_b.add_argument('--baz', choices=('X', 'Y', 'Z'), help='baz " +"help')\n" +">>>\n" +">>> # parse some argument lists\n" +">>> parser.parse_args(['a', '12'])\n" +"Namespace(bar=12, foo=False)\n" +">>> parser.parse_args(['--foo', 'b', '--baz', 'Z'])\n" +"Namespace(baz='Z', foo=True)" +msgstr "" + +#: ../../library/argparse.rst:1743 +msgid "" +"Note that the object returned by :meth:`parse_args` will only contain " +"attributes for the main parser and the subparser that was selected by the " +"command line (and not any other subparsers). So in the example above, when " +"the ``a`` command is specified, only the ``foo`` and ``bar`` attributes are " +"present, and when the ``b`` command is specified, only the ``foo`` and " +"``baz`` attributes are present." +msgstr "" + +#: ../../library/argparse.rst:1750 +msgid "" +"Similarly, when a help message is requested from a subparser, only the help " +"for that particular parser will be printed. The help message will not " +"include parent parser or sibling parser messages. (A help message for each " +"subparser command, however, can be given by supplying the ``help=`` argument " +"to :meth:`~_SubParsersAction.add_parser` as above.)" +msgstr "" + +#: ../../library/argparse.rst:1758 +msgid "" +">>> parser.parse_args(['--help'])\n" +"usage: PROG [-h] [--foo] {a,b} ...\n" +"\n" +"positional arguments:\n" +" {a,b} subcommand help\n" +" a a help\n" +" b b help\n" +"\n" +"options:\n" +" -h, --help show this help message and exit\n" +" --foo foo help\n" +"\n" +">>> parser.parse_args(['a', '--help'])\n" +"usage: PROG a [-h] bar\n" +"\n" +"positional arguments:\n" +" bar bar help\n" +"\n" +"options:\n" +" -h, --help show this help message and exit\n" +"\n" +">>> parser.parse_args(['b', '--help'])\n" +"usage: PROG b [-h] [--baz {X,Y,Z}]\n" +"\n" +"options:\n" +" -h, --help show this help message and exit\n" +" --baz {X,Y,Z} baz help" +msgstr "" +">>> parser.parse_args(['--help'])\n" +"usage: PROG [-h] [--foo] {a,b} ...\n" +"\n" +"positional arguments:\n" +" {a,b} subcommand help\n" +" a a help\n" +" b b help\n" +"\n" +"options:\n" +" -h, --help show this help message and exit\n" +" --foo foo help\n" +"\n" +">>> parser.parse_args(['a', '--help'])\n" +"usage: PROG a [-h] bar\n" +"\n" +"positional arguments:\n" +" bar bar help\n" +"\n" +"options:\n" +" -h, --help show this help message and exit\n" +"\n" +">>> parser.parse_args(['b', '--help'])\n" +"usage: PROG b [-h] [--baz {X,Y,Z}]\n" +"\n" +"options:\n" +" -h, --help show this help message and exit\n" +" --baz {X,Y,Z} baz help" + +#: ../../library/argparse.rst:1786 +msgid "" +"The :meth:`add_subparsers` method also supports ``title`` and " +"``description`` keyword arguments. When either is present, the subparser's " +"commands will appear in their own group in the help output. For example::" +msgstr "" + +#: ../../library/argparse.rst:1790 +msgid "" +">>> parser = argparse.ArgumentParser()\n" +">>> subparsers = parser.add_subparsers(title='subcommands',\n" +"... description='valid subcommands',\n" +"... help='additional help')\n" +">>> subparsers.add_parser('foo')\n" +">>> subparsers.add_parser('bar')\n" +">>> parser.parse_args(['-h'])\n" +"usage: [-h] {foo,bar} ...\n" +"\n" +"options:\n" +" -h, --help show this help message and exit\n" +"\n" +"subcommands:\n" +" valid subcommands\n" +"\n" +" {foo,bar} additional help" +msgstr "" +">>> parser = argparse.ArgumentParser()\n" +">>> subparsers = parser.add_subparsers(title='subcommands',\n" +"... description='valid subcommands',\n" +"... help='additional help')\n" +">>> subparsers.add_parser('foo')\n" +">>> subparsers.add_parser('bar')\n" +">>> parser.parse_args(['-h'])\n" +"usage: [-h] {foo,bar} ...\n" +"\n" +"options:\n" +" -h, --help show this help message and exit\n" +"\n" +"subcommands:\n" +" valid subcommands\n" +"\n" +" {foo,bar} additional help" + +#: ../../library/argparse.rst:1807 +msgid "" +"Furthermore, :meth:`~_SubParsersAction.add_parser` supports an additional " +"*aliases* argument, which allows multiple strings to refer to the same " +"subparser. This example, like ``svn``, aliases ``co`` as a shorthand for " +"``checkout``::" +msgstr "" + +#: ../../library/argparse.rst:1812 +msgid "" +">>> parser = argparse.ArgumentParser()\n" +">>> subparsers = parser.add_subparsers()\n" +">>> checkout = subparsers.add_parser('checkout', aliases=['co'])\n" +">>> checkout.add_argument('foo')\n" +">>> parser.parse_args(['co', 'bar'])\n" +"Namespace(foo='bar')" +msgstr "" +">>> parser = argparse.ArgumentParser()\n" +">>> subparsers = parser.add_subparsers()\n" +">>> checkout = subparsers.add_parser('checkout', aliases=['co'])\n" +">>> checkout.add_argument('foo')\n" +">>> parser.parse_args(['co', 'bar'])\n" +"Namespace(foo='bar')" + +#: ../../library/argparse.rst:1819 +msgid "" +":meth:`~_SubParsersAction.add_parser` supports also an additional " +"*deprecated* argument, which allows to deprecate the subparser." +msgstr "" + +#: ../../library/argparse.rst:1833 +msgid "" +"One particularly effective way of handling subcommands is to combine the use " +"of the :meth:`add_subparsers` method with calls to :meth:`set_defaults` so " +"that each subparser knows which Python function it should execute. For " +"example::" +msgstr "" + +#: ../../library/argparse.rst:1838 +msgid "" +">>> # subcommand functions\n" +">>> def foo(args):\n" +"... print(args.x * args.y)\n" +"...\n" +">>> def bar(args):\n" +"... print('((%s))' % args.z)\n" +"...\n" +">>> # create the top-level parser\n" +">>> parser = argparse.ArgumentParser()\n" +">>> subparsers = parser.add_subparsers(required=True)\n" +">>>\n" +">>> # create the parser for the \"foo\" command\n" +">>> parser_foo = subparsers.add_parser('foo')\n" +">>> parser_foo.add_argument('-x', type=int, default=1)\n" +">>> parser_foo.add_argument('y', type=float)\n" +">>> parser_foo.set_defaults(func=foo)\n" +">>>\n" +">>> # create the parser for the \"bar\" command\n" +">>> parser_bar = subparsers.add_parser('bar')\n" +">>> parser_bar.add_argument('z')\n" +">>> parser_bar.set_defaults(func=bar)\n" +">>>\n" +">>> # parse the args and call whatever function was selected\n" +">>> args = parser.parse_args('foo 1 -x 2'.split())\n" +">>> args.func(args)\n" +"2.0\n" +">>>\n" +">>> # parse the args and call whatever function was selected\n" +">>> args = parser.parse_args('bar XYZYX'.split())\n" +">>> args.func(args)\n" +"((XYZYX))" +msgstr "" + +#: ../../library/argparse.rst:1870 +msgid "" +"This way, you can let :meth:`parse_args` do the job of calling the " +"appropriate function after argument parsing is complete. Associating " +"functions with actions like this is typically the easiest way to handle the " +"different actions for each of your subparsers. However, if it is necessary " +"to check the name of the subparser that was invoked, the ``dest`` keyword " +"argument to the :meth:`add_subparsers` call will work::" +msgstr "" + +#: ../../library/argparse.rst:1877 +msgid "" +">>> parser = argparse.ArgumentParser()\n" +">>> subparsers = parser.add_subparsers(dest='subparser_name')\n" +">>> subparser1 = subparsers.add_parser('1')\n" +">>> subparser1.add_argument('-x')\n" +">>> subparser2 = subparsers.add_parser('2')\n" +">>> subparser2.add_argument('y')\n" +">>> parser.parse_args(['2', 'frobble'])\n" +"Namespace(subparser_name='2', y='frobble')" +msgstr "" +">>> parser = argparse.ArgumentParser()\n" +">>> subparsers = parser.add_subparsers(dest='subparser_name')\n" +">>> subparser1 = subparsers.add_parser('1')\n" +">>> subparser1.add_argument('-x')\n" +">>> subparser2 = subparsers.add_parser('2')\n" +">>> subparser2.add_argument('y')\n" +">>> parser.parse_args(['2', 'frobble'])\n" +"Namespace(subparser_name='2', y='frobble')" + +#: ../../library/argparse.rst:1886 +msgid "New *required* keyword-only parameter." +msgstr "" + +#: ../../library/argparse.rst:1889 +msgid "" +"Subparser's *prog* is no longer affected by a custom usage message in the " +"main parser." +msgstr "" + +#: ../../library/argparse.rst:1895 +msgid "FileType objects" +msgstr "FileType 物件" + +#: ../../library/argparse.rst:1899 +msgid "" +"The :class:`FileType` factory creates objects that can be passed to the type " +"argument of :meth:`ArgumentParser.add_argument`. Arguments that have :class:" +"`FileType` objects as their type will open command-line arguments as files " +"with the requested modes, buffer sizes, encodings and error handling (see " +"the :func:`open` function for more details)::" +msgstr "" + +#: ../../library/argparse.rst:1905 +msgid "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('--raw', type=argparse.FileType('wb', 0))\n" +">>> parser.add_argument('out', type=argparse.FileType('w', " +"encoding='UTF-8'))\n" +">>> parser.parse_args(['--raw', 'raw.dat', 'file.txt'])\n" +"Namespace(out=<_io.TextIOWrapper name='file.txt' mode='w' encoding='UTF-8'>, " +"raw=<_io.FileIO name='raw.dat' mode='wb'>)" +msgstr "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('--raw', type=argparse.FileType('wb', 0))\n" +">>> parser.add_argument('out', type=argparse.FileType('w', " +"encoding='UTF-8'))\n" +">>> parser.parse_args(['--raw', 'raw.dat', 'file.txt'])\n" +"Namespace(out=<_io.TextIOWrapper name='file.txt' mode='w' encoding='UTF-8'>, " +"raw=<_io.FileIO name='raw.dat' mode='wb'>)" + +#: ../../library/argparse.rst:1911 +msgid "" +"FileType objects understand the pseudo-argument ``'-'`` and automatically " +"convert this into :data:`sys.stdin` for readable :class:`FileType` objects " +"and :data:`sys.stdout` for writable :class:`FileType` objects::" +msgstr "" + +#: ../../library/argparse.rst:1915 +msgid "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('infile', type=argparse.FileType('r'))\n" +">>> parser.parse_args(['-'])\n" +"Namespace(infile=<_io.TextIOWrapper name='' encoding='UTF-8'>)" +msgstr "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('infile', type=argparse.FileType('r'))\n" +">>> parser.parse_args(['-'])\n" +"Namespace(infile=<_io.TextIOWrapper name='' encoding='UTF-8'>)" + +#: ../../library/argparse.rst:1922 +msgid "" +"If one argument uses *FileType* and then a subsequent argument fails, an " +"error is reported but the file is not automatically closed. This can also " +"clobber the output files. In this case, it would be better to wait until " +"after the parser has run and then use the :keyword:`with`-statement to " +"manage the files." +msgstr "" + +#: ../../library/argparse.rst:1928 +msgid "Added the *encodings* and *errors* parameters." +msgstr "" + +#: ../../library/argparse.rst:1935 +msgid "Argument groups" +msgstr "" + +#: ../../library/argparse.rst:1940 +msgid "" +"By default, :class:`ArgumentParser` groups command-line arguments into " +"\"positional arguments\" and \"options\" when displaying help messages. When " +"there is a better conceptual grouping of arguments than this default one, " +"appropriate groups can be created using the :meth:`!add_argument_group` " +"method::" +msgstr "" + +#: ../../library/argparse.rst:1946 +msgid "" +">>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)\n" +">>> group = parser.add_argument_group('group')\n" +">>> group.add_argument('--foo', help='foo help')\n" +">>> group.add_argument('bar', help='bar help')\n" +">>> parser.print_help()\n" +"usage: PROG [--foo FOO] bar\n" +"\n" +"group:\n" +" bar bar help\n" +" --foo FOO foo help" +msgstr "" +">>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)\n" +">>> group = parser.add_argument_group('group')\n" +">>> group.add_argument('--foo', help='foo help')\n" +">>> group.add_argument('bar', help='bar help')\n" +">>> parser.print_help()\n" +"usage: PROG [--foo FOO] bar\n" +"\n" +"group:\n" +" bar bar help\n" +" --foo FOO foo help" + +#: ../../library/argparse.rst:1957 +msgid "" +"The :meth:`add_argument_group` method returns an argument group object which " +"has an :meth:`~ArgumentParser.add_argument` method just like a regular :" +"class:`ArgumentParser`. When an argument is added to the group, the parser " +"treats it just like a normal argument, but displays the argument in a " +"separate group for help messages. The :meth:`!add_argument_group` method " +"accepts *title* and *description* arguments which can be used to customize " +"this display::" +msgstr "" + +#: ../../library/argparse.rst:1965 +msgid "" +">>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)\n" +">>> group1 = parser.add_argument_group('group1', 'group1 description')\n" +">>> group1.add_argument('foo', help='foo help')\n" +">>> group2 = parser.add_argument_group('group2', 'group2 description')\n" +">>> group2.add_argument('--bar', help='bar help')\n" +">>> parser.print_help()\n" +"usage: PROG [--bar BAR] foo\n" +"\n" +"group1:\n" +" group1 description\n" +"\n" +" foo foo help\n" +"\n" +"group2:\n" +" group2 description\n" +"\n" +" --bar BAR bar help" +msgstr "" +">>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)\n" +">>> group1 = parser.add_argument_group('group1', 'group1 description')\n" +">>> group1.add_argument('foo', help='foo help')\n" +">>> group2 = parser.add_argument_group('group2', 'group2 description')\n" +">>> group2.add_argument('--bar', help='bar help')\n" +">>> parser.print_help()\n" +"usage: PROG [--bar BAR] foo\n" +"\n" +"group1:\n" +" group1 description\n" +"\n" +" foo foo help\n" +"\n" +"group2:\n" +" group2 description\n" +"\n" +" --bar BAR bar help" + +#: ../../library/argparse.rst:1983 +msgid "" +"The optional, keyword-only parameters argument_default_ and " +"conflict_handler_ allow for finer-grained control of the behavior of the " +"argument group. These parameters have the same meaning as in the :class:" +"`ArgumentParser` constructor, but apply specifically to the argument group " +"rather than the entire parser." +msgstr "" + +#: ../../library/argparse.rst:1988 +msgid "" +"Note that any arguments not in your user-defined groups will end up back in " +"the usual \"positional arguments\" and \"optional arguments\" sections." +msgstr "" + +#: ../../library/argparse.rst:1991 +msgid "" +"Calling :meth:`add_argument_group` on an argument group now raises an " +"exception. This nesting was never supported, often failed to work correctly, " +"and was unintentionally exposed through inheritance." +msgstr "" + +#: ../../library/argparse.rst:1996 +msgid "Passing prefix_chars_ to :meth:`add_argument_group` is now deprecated." +msgstr "" + +#: ../../library/argparse.rst:2002 +msgid "Mutual exclusion" +msgstr "" + +#: ../../library/argparse.rst:2006 +msgid "" +"Create a mutually exclusive group. :mod:`!argparse` will make sure that only " +"one of the arguments in the mutually exclusive group was present on the " +"command line::" +msgstr "" + +#: ../../library/argparse.rst:2010 +msgid "" +">>> parser = argparse.ArgumentParser(prog='PROG')\n" +">>> group = parser.add_mutually_exclusive_group()\n" +">>> group.add_argument('--foo', action='store_true')\n" +">>> group.add_argument('--bar', action='store_false')\n" +">>> parser.parse_args(['--foo'])\n" +"Namespace(bar=True, foo=True)\n" +">>> parser.parse_args(['--bar'])\n" +"Namespace(bar=False, foo=False)\n" +">>> parser.parse_args(['--foo', '--bar'])\n" +"usage: PROG [-h] [--foo | --bar]\n" +"PROG: error: argument --bar: not allowed with argument --foo" +msgstr "" +">>> parser = argparse.ArgumentParser(prog='PROG')\n" +">>> group = parser.add_mutually_exclusive_group()\n" +">>> group.add_argument('--foo', action='store_true')\n" +">>> group.add_argument('--bar', action='store_false')\n" +">>> parser.parse_args(['--foo'])\n" +"Namespace(bar=True, foo=True)\n" +">>> parser.parse_args(['--bar'])\n" +"Namespace(bar=False, foo=False)\n" +">>> parser.parse_args(['--foo', '--bar'])\n" +"usage: PROG [-h] [--foo | --bar]\n" +"PROG: error: argument --bar: not allowed with argument --foo" + +#: ../../library/argparse.rst:2022 +msgid "" +"The :meth:`add_mutually_exclusive_group` method also accepts a *required* " +"argument, to indicate that at least one of the mutually exclusive arguments " +"is required::" +msgstr "" + +#: ../../library/argparse.rst:2026 +msgid "" +">>> parser = argparse.ArgumentParser(prog='PROG')\n" +">>> group = parser.add_mutually_exclusive_group(required=True)\n" +">>> group.add_argument('--foo', action='store_true')\n" +">>> group.add_argument('--bar', action='store_false')\n" +">>> parser.parse_args([])\n" +"usage: PROG [-h] (--foo | --bar)\n" +"PROG: error: one of the arguments --foo --bar is required" +msgstr "" +">>> parser = argparse.ArgumentParser(prog='PROG')\n" +">>> group = parser.add_mutually_exclusive_group(required=True)\n" +">>> group.add_argument('--foo', action='store_true')\n" +">>> group.add_argument('--bar', action='store_false')\n" +">>> parser.parse_args([])\n" +"usage: PROG [-h] (--foo | --bar)\n" +"PROG: error: one of the arguments --foo --bar is required" + +#: ../../library/argparse.rst:2034 +msgid "" +"Note that currently mutually exclusive argument groups do not support the " +"*title* and *description* arguments of :meth:`~ArgumentParser." +"add_argument_group`. However, a mutually exclusive group can be added to an " +"argument group that has a title and description. For example::" +msgstr "" + +#: ../../library/argparse.rst:2040 +msgid "" +">>> parser = argparse.ArgumentParser(prog='PROG')\n" +">>> group = parser.add_argument_group('Group title', 'Group description')\n" +">>> exclusive_group = group.add_mutually_exclusive_group(required=True)\n" +">>> exclusive_group.add_argument('--foo', help='foo help')\n" +">>> exclusive_group.add_argument('--bar', help='bar help')\n" +">>> parser.print_help()\n" +"usage: PROG [-h] (--foo FOO | --bar BAR)\n" +"\n" +"options:\n" +" -h, --help show this help message and exit\n" +"\n" +"Group title:\n" +" Group description\n" +"\n" +" --foo FOO foo help\n" +" --bar BAR bar help" +msgstr "" +">>> parser = argparse.ArgumentParser(prog='PROG')\n" +">>> group = parser.add_argument_group('Group title', 'Group description')\n" +">>> exclusive_group = group.add_mutually_exclusive_group(required=True)\n" +">>> exclusive_group.add_argument('--foo', help='foo help')\n" +">>> exclusive_group.add_argument('--bar', help='bar help')\n" +">>> parser.print_help()\n" +"usage: PROG [-h] (--foo FOO | --bar BAR)\n" +"\n" +"options:\n" +" -h, --help show this help message and exit\n" +"\n" +"Group title:\n" +" Group description\n" +"\n" +" --foo FOO foo help\n" +" --bar BAR bar help" + +#: ../../library/argparse.rst:2057 +msgid "" +"Calling :meth:`add_argument_group` or :meth:`add_mutually_exclusive_group` " +"on a mutually exclusive group now raises an exception. This nesting was " +"never supported, often failed to work correctly, and was unintentionally " +"exposed through inheritance." +msgstr "" + +#: ../../library/argparse.rst:2065 +msgid "Parser defaults" +msgstr "" + +#: ../../library/argparse.rst:2069 +msgid "" +"Most of the time, the attributes of the object returned by :meth:" +"`parse_args` will be fully determined by inspecting the command-line " +"arguments and the argument actions. :meth:`set_defaults` allows some " +"additional attributes that are determined without any inspection of the " +"command line to be added::" +msgstr "" + +#: ../../library/argparse.rst:2075 +msgid "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('foo', type=int)\n" +">>> parser.set_defaults(bar=42, baz='badger')\n" +">>> parser.parse_args(['736'])\n" +"Namespace(bar=42, baz='badger', foo=736)" +msgstr "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('foo', type=int)\n" +">>> parser.set_defaults(bar=42, baz='badger')\n" +">>> parser.parse_args(['736'])\n" +"Namespace(bar=42, baz='badger', foo=736)" + +#: ../../library/argparse.rst:2081 +msgid "" +"Note that defaults can be set at both the parser level using :meth:" +"`set_defaults` and at the argument level using :meth:`add_argument`. If both " +"are called for the same argument, the last default set for an argument is " +"used::" +msgstr "" + +#: ../../library/argparse.rst:2085 +msgid "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('--foo', default='bar')\n" +">>> parser.set_defaults(foo='spam')\n" +">>> parser.parse_args([])\n" +"Namespace(foo='spam')" +msgstr "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('--foo', default='bar')\n" +">>> parser.set_defaults(foo='spam')\n" +">>> parser.parse_args([])\n" +"Namespace(foo='spam')" + +#: ../../library/argparse.rst:2091 +msgid "" +"Parser-level defaults can be particularly useful when working with multiple " +"parsers. See the :meth:`~ArgumentParser.add_subparsers` method for an " +"example of this type." +msgstr "" + +#: ../../library/argparse.rst:2097 +msgid "" +"Get the default value for a namespace attribute, as set by either :meth:" +"`~ArgumentParser.add_argument` or by :meth:`~ArgumentParser.set_defaults`::" +msgstr "" + +#: ../../library/argparse.rst:2101 +msgid "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('--foo', default='badger')\n" +">>> parser.get_default('foo')\n" +"'badger'" +msgstr "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('--foo', default='badger')\n" +">>> parser.get_default('foo')\n" +"'badger'" + +#: ../../library/argparse.rst:2108 +msgid "Printing help" +msgstr "印出幫助訊息" + +#: ../../library/argparse.rst:2110 +msgid "" +"In most typical applications, :meth:`~ArgumentParser.parse_args` will take " +"care of formatting and printing any usage or error messages. However, " +"several formatting methods are available:" +msgstr "" + +#: ../../library/argparse.rst:2116 +msgid "" +"Print a brief description of how the :class:`ArgumentParser` should be " +"invoked on the command line. If *file* is ``None``, :data:`sys.stdout` is " +"assumed." +msgstr "" + +#: ../../library/argparse.rst:2122 +msgid "" +"Print a help message, including the program usage and information about the " +"arguments registered with the :class:`ArgumentParser`. If *file* is " +"``None``, :data:`sys.stdout` is assumed." +msgstr "" + +#: ../../library/argparse.rst:2126 +msgid "" +"There are also variants of these methods that simply return a string instead " +"of printing it:" +msgstr "" + +#: ../../library/argparse.rst:2131 +msgid "" +"Return a string containing a brief description of how the :class:" +"`ArgumentParser` should be invoked on the command line." +msgstr "" + +#: ../../library/argparse.rst:2136 +msgid "" +"Return a string containing a help message, including the program usage and " +"information about the arguments registered with the :class:`ArgumentParser`." +msgstr "" + +#: ../../library/argparse.rst:2141 +msgid "Partial parsing" +msgstr "" + +#: ../../library/argparse.rst:2145 +msgid "" +"Sometimes a script only needs to handle a specific set of command-line " +"arguments, leaving any unrecognized arguments for another script or program. " +"In these cases, the :meth:`~ArgumentParser.parse_known_args` method can be " +"useful." +msgstr "" + +#: ../../library/argparse.rst:2150 +msgid "" +"This method works similarly to :meth:`~ArgumentParser.parse_args`, but it " +"does not raise an error for extra, unrecognized arguments. Instead, it " +"parses the known arguments and returns a two item tuple that contains the " +"populated namespace and the list of any unrecognized arguments." +msgstr "" + +#: ../../library/argparse.rst:2157 +msgid "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('--foo', action='store_true')\n" +">>> parser.add_argument('bar')\n" +">>> parser.parse_known_args(['--foo', '--badger', 'BAR', 'spam'])\n" +"(Namespace(bar='BAR', foo=True), ['--badger', 'spam'])" +msgstr "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('--foo', action='store_true')\n" +">>> parser.add_argument('bar')\n" +">>> parser.parse_known_args(['--foo', '--badger', 'BAR', 'spam'])\n" +"(Namespace(bar='BAR', foo=True), ['--badger', 'spam'])" + +#: ../../library/argparse.rst:2164 +msgid "" +":ref:`Prefix matching ` rules apply to :meth:" +"`~ArgumentParser.parse_known_args`. The parser may consume an option even if " +"it's just a prefix of one of its known options, instead of leaving it in the " +"remaining arguments list." +msgstr "" + +#: ../../library/argparse.rst:2171 +msgid "Customizing file parsing" +msgstr "" + +#: ../../library/argparse.rst:2175 +msgid "" +"Arguments that are read from a file (see the *fromfile_prefix_chars* keyword " +"argument to the :class:`ArgumentParser` constructor) are read one argument " +"per line. :meth:`convert_arg_line_to_args` can be overridden for fancier " +"reading." +msgstr "" + +#: ../../library/argparse.rst:2180 +msgid "" +"This method takes a single argument *arg_line* which is a string read from " +"the argument file. It returns a list of arguments parsed from this string. " +"The method is called once per line read from the argument file, in order." +msgstr "" + +#: ../../library/argparse.rst:2184 +msgid "" +"A useful override of this method is one that treats each space-separated " +"word as an argument. The following example demonstrates how to do this::" +msgstr "" + +#: ../../library/argparse.rst:2187 +msgid "" +"class MyArgumentParser(argparse.ArgumentParser):\n" +" def convert_arg_line_to_args(self, arg_line):\n" +" return arg_line.split()" +msgstr "" +"class MyArgumentParser(argparse.ArgumentParser):\n" +" def convert_arg_line_to_args(self, arg_line):\n" +" return arg_line.split()" + +#: ../../library/argparse.rst:2193 +msgid "Exiting methods" +msgstr "" + +#: ../../library/argparse.rst:2197 +msgid "" +"This method terminates the program, exiting with the specified *status* and, " +"if given, it prints a *message* to :data:`sys.stderr` before that. The user " +"can override this method to handle these steps differently::" +msgstr "" + +#: ../../library/argparse.rst:2201 +msgid "" +"class ErrorCatchingArgumentParser(argparse.ArgumentParser):\n" +" def exit(self, status=0, message=None):\n" +" if status:\n" +" raise Exception(f'Exiting because of an error: {message}')\n" +" exit(status)" +msgstr "" +"class ErrorCatchingArgumentParser(argparse.ArgumentParser):\n" +" def exit(self, status=0, message=None):\n" +" if status:\n" +" raise Exception(f'Exiting because of an error: {message}')\n" +" exit(status)" + +#: ../../library/argparse.rst:2209 +msgid "" +"This method prints a usage message, including the *message*, to :data:`sys." +"stderr` and terminates the program with a status code of 2." +msgstr "" + +#: ../../library/argparse.rst:2214 +msgid "Intermixed parsing" +msgstr "" + +#: ../../library/argparse.rst:2219 +msgid "" +"A number of Unix commands allow the user to intermix optional arguments with " +"positional arguments. The :meth:`~ArgumentParser.parse_intermixed_args` " +"and :meth:`~ArgumentParser.parse_known_intermixed_args` methods support this " +"parsing style." +msgstr "" + +#: ../../library/argparse.rst:2224 +msgid "" +"These parsers do not support all the :mod:`!argparse` features, and will " +"raise exceptions if unsupported features are used. In particular, " +"subparsers, and mutually exclusive groups that include both optionals and " +"positionals are not supported." +msgstr "" + +#: ../../library/argparse.rst:2229 +msgid "" +"The following example shows the difference between :meth:`~ArgumentParser." +"parse_known_args` and :meth:`~ArgumentParser.parse_intermixed_args`: the " +"former returns ``['2', '3']`` as unparsed arguments, while the latter " +"collects all the positionals into ``rest``. ::" +msgstr "" + +#: ../../library/argparse.rst:2235 +msgid "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('--foo')\n" +">>> parser.add_argument('cmd')\n" +">>> parser.add_argument('rest', nargs='*', type=int)\n" +">>> parser.parse_known_args('doit 1 --foo bar 2 3'.split())\n" +"(Namespace(cmd='doit', foo='bar', rest=[1]), ['2', '3'])\n" +">>> parser.parse_intermixed_args('doit 1 --foo bar 2 3'.split())\n" +"Namespace(cmd='doit', foo='bar', rest=[1, 2, 3])" +msgstr "" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.add_argument('--foo')\n" +">>> parser.add_argument('cmd')\n" +">>> parser.add_argument('rest', nargs='*', type=int)\n" +">>> parser.parse_known_args('doit 1 --foo bar 2 3'.split())\n" +"(Namespace(cmd='doit', foo='bar', rest=[1]), ['2', '3'])\n" +">>> parser.parse_intermixed_args('doit 1 --foo bar 2 3'.split())\n" +"Namespace(cmd='doit', foo='bar', rest=[1, 2, 3])" + +#: ../../library/argparse.rst:2244 +msgid "" +":meth:`~ArgumentParser.parse_known_intermixed_args` returns a two item tuple " +"containing the populated namespace and the list of remaining argument " +"strings. :meth:`~ArgumentParser.parse_intermixed_args` raises an error if " +"there are any remaining unparsed argument strings." +msgstr "" + +#: ../../library/argparse.rst:2253 +msgid "Registering custom types or actions" +msgstr "" + +#: ../../library/argparse.rst:2257 +msgid "" +"Sometimes it's desirable to use a custom string in error messages to provide " +"more user-friendly output. In these cases, :meth:`!register` can be used to " +"register custom actions or types with a parser and allow you to reference " +"the type by their registered name instead of their callable name." +msgstr "" + +#: ../../library/argparse.rst:2262 +msgid "" +"The :meth:`!register` method accepts three arguments - a *registry_name*, " +"specifying the internal registry where the object will be stored (e.g., " +"``action``, ``type``), *value*, which is the key under which the object will " +"be registered, and object, the callable to be registered." +msgstr "" + +#: ../../library/argparse.rst:2267 +msgid "" +"The following example shows how to register a custom type with a parser::" +msgstr "" + +#: ../../library/argparse.rst:2269 +msgid "" +">>> import argparse\n" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.register('type', 'hexadecimal integer', lambda s: int(s, 16))\n" +">>> parser.add_argument('--foo', type='hexadecimal integer')\n" +"_StoreAction(option_strings=['--foo'], dest='foo', nargs=None, const=None, " +"default=None, type='hexadecimal integer', choices=None, required=False, " +"help=None, metavar=None, deprecated=False)\n" +">>> parser.parse_args(['--foo', '0xFA'])\n" +"Namespace(foo=250)\n" +">>> parser.parse_args(['--foo', '1.2'])\n" +"usage: PROG [-h] [--foo FOO]\n" +"PROG: error: argument --foo: invalid 'hexadecimal integer' value: '1.2'" +msgstr "" +">>> import argparse\n" +">>> parser = argparse.ArgumentParser()\n" +">>> parser.register('type', 'hexadecimal integer', lambda s: int(s, 16))\n" +">>> parser.add_argument('--foo', type='hexadecimal integer')\n" +"_StoreAction(option_strings=['--foo'], dest='foo', nargs=None, const=None, " +"default=None, type='hexadecimal integer', choices=None, required=False, " +"help=None, metavar=None, deprecated=False)\n" +">>> parser.parse_args(['--foo', '0xFA'])\n" +"Namespace(foo=250)\n" +">>> parser.parse_args(['--foo', '1.2'])\n" +"usage: PROG [-h] [--foo FOO]\n" +"PROG: error: argument --foo: invalid 'hexadecimal integer' value: '1.2'" + +#: ../../library/argparse.rst:2281 +msgid "Exceptions" +msgstr "例外" + +#: ../../library/argparse.rst:2285 +msgid "An error from creating or using an argument (optional or positional)." +msgstr "" + +#: ../../library/argparse.rst:2287 +msgid "" +"The string value of this exception is the message, augmented with " +"information about the argument that caused it." +msgstr "" + +#: ../../library/argparse.rst:2292 +msgid "" +"Raised when something goes wrong converting a command line string to a type." +msgstr "" + +#: ../../library/argparse.rst:2296 +msgid "Guides and Tutorials" +msgstr "" + +#: ../../library/argparse.rst:908 +msgid "? (question mark)" +msgstr "? （問號）" + +#: ../../library/argparse.rst:908 ../../library/argparse.rst:940 +#: ../../library/argparse.rst:954 +msgid "in argparse module" +msgstr "於 argparse 模組中" + +#: ../../library/argparse.rst:940 +msgid "* (asterisk)" +msgstr "* （星號）" + +#: ../../library/argparse.rst:954 +msgid "+ (plus)" +msgstr "+ （加號）" + +#~ msgid "" +#~ ">>> parser = argparse.ArgumentParser()\n" +#~ ">>> parser.add_argument('infile', nargs='?', type=argparse." +#~ "FileType('r'),\n" +#~ "... default=sys.stdin)\n" +#~ ">>> parser.add_argument('outfile', nargs='?', type=argparse." +#~ "FileType('w'),\n" +#~ "... default=sys.stdout)\n" +#~ ">>> parser.parse_args(['input.txt', 'output.txt'])\n" +#~ "Namespace(infile=<_io.TextIOWrapper name='input.txt' encoding='UTF-8'>,\n" +#~ " outfile=<_io.TextIOWrapper name='output.txt' " +#~ "encoding='UTF-8'>)\n" +#~ ">>> parser.parse_args([])\n" +#~ "Namespace(infile=<_io.TextIOWrapper name='' encoding='UTF-8'>,\n" +#~ " outfile=<_io.TextIOWrapper name='' encoding='UTF-8'>)" +#~ msgstr "" +#~ ">>> parser = argparse.ArgumentParser()\n" +#~ ">>> parser.add_argument('infile', nargs='?', type=argparse." +#~ "FileType('r'),\n" +#~ "... default=sys.stdin)\n" +#~ ">>> parser.add_argument('outfile', nargs='?', type=argparse." +#~ "FileType('w'),\n" +#~ "... default=sys.stdout)\n" +#~ ">>> parser.parse_args(['input.txt', 'output.txt'])\n" +#~ "Namespace(infile=<_io.TextIOWrapper name='input.txt' encoding='UTF-8'>,\n" +#~ " outfile=<_io.TextIOWrapper name='output.txt' " +#~ "encoding='UTF-8'>)\n" +#~ ">>> parser.parse_args([])\n" +#~ "Namespace(infile=<_io.TextIOWrapper name='' encoding='UTF-8'>,\n" +#~ " outfile=<_io.TextIOWrapper name='' encoding='UTF-8'>)" diff --git a/library/array.po b/library/array.po index 45919f3bb9..8ceb0213f0 100644 --- a/library/array.po +++ b/library/array.po @@ -1,540 +1,540 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Liang-Bo Wang , 2016 -# 周 忠毅 , 2016 -# Adrian Liaw , 2018 -# Benson Chen , 2021 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2026-01-12 00:16+0000\n" -"PO-Revision-Date: 2021-11-23 18:40+0800\n" -"Last-Translator: Benson Chen \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" -"X-Generator: Poedit 3.0\n" - -#: ../../library/array.rst:2 -msgid ":mod:`!array` --- Efficient arrays of numeric values" -msgstr ":mod:`!array` --- 高效率的數值型陣列" - -#: ../../library/array.rst:11 -msgid "" -"This module defines an object type which can compactly represent an array of " -"basic values: characters, integers, floating-point numbers. Arrays are " -"mutable :term:`sequence` types and behave very much like lists, except that " -"the type of objects stored in them is constrained. The type is specified at " -"object creation time by using a :dfn:`type code`, which is a single " -"character. The following type codes are defined:" -msgstr "" -"這個模組定義了一個物件型別，可以簡潔的表達一個包含基本數值的陣列：字元、整" -"數、浮點數。陣列是一個非常類似 list（串列）的\\ :term:`序列 `\\ 型別，除了陣" -"列會限制儲存的物件型別。在建立陣列時可以使用一個字元的 :dfn:`type code` 來指定儲存的資料" -"型別。以下為有被定義的 type codes：" - -#: ../../library/array.rst:19 -msgid "Type code" -msgstr "Type code" - -#: ../../library/array.rst:19 -msgid "C Type" -msgstr "C Type" - -#: ../../library/array.rst:19 -msgid "Python Type" -msgstr "Python Type" - -#: ../../library/array.rst:19 -msgid "Minimum size in bytes" -msgstr "所需的最小位元組 (bytes)" - -#: ../../library/array.rst:19 -msgid "Notes" -msgstr "註解" - -#: ../../library/array.rst:21 -msgid "``'b'``" -msgstr "``'b'``" - -#: ../../library/array.rst:21 -msgid "signed char" -msgstr "signed char" - -#: ../../library/array.rst:21 ../../library/array.rst:23 -#: ../../library/array.rst:29 ../../library/array.rst:31 -#: ../../library/array.rst:33 ../../library/array.rst:35 -#: ../../library/array.rst:37 ../../library/array.rst:39 -#: ../../library/array.rst:41 ../../library/array.rst:43 -msgid "int" -msgstr "int" - -#: ../../library/array.rst:21 ../../library/array.rst:23 -msgid "1" -msgstr "1" - -#: ../../library/array.rst:23 -msgid "``'B'``" -msgstr "``'B'``" - -#: ../../library/array.rst:23 -msgid "unsigned char" -msgstr "unsigned char" - -#: ../../library/array.rst:25 -msgid "``'u'``" -msgstr "``'u'``" - -#: ../../library/array.rst:25 -msgid "wchar_t" -msgstr "wchar_t" - -#: ../../library/array.rst:25 ../../library/array.rst:27 -msgid "Unicode character" -msgstr "Unicode character" - -#: ../../library/array.rst:25 ../../library/array.rst:29 -#: ../../library/array.rst:31 ../../library/array.rst:33 -#: ../../library/array.rst:35 -msgid "2" -msgstr "2" - -#: ../../library/array.rst:25 -msgid "\\(1)" -msgstr "\\(1)" - -#: ../../library/array.rst:27 -msgid "``'w'``" -msgstr "``'w'``" - -#: ../../library/array.rst:27 -msgid "Py_UCS4" -msgstr "Py_UCS4" - -#: ../../library/array.rst:27 ../../library/array.rst:37 -#: ../../library/array.rst:39 ../../library/array.rst:45 -msgid "4" -msgstr "4" - -#: ../../library/array.rst:27 -msgid "\\(2)" -msgstr "\\(2)" - -#: ../../library/array.rst:29 -msgid "``'h'``" -msgstr "``'h'``" - -#: ../../library/array.rst:29 -msgid "signed short" -msgstr "signed short" - -#: ../../library/array.rst:31 -msgid "``'H'``" -msgstr "``'H'``" - -#: ../../library/array.rst:31 -msgid "unsigned short" -msgstr "unsigned short" - -#: ../../library/array.rst:33 -msgid "``'i'``" -msgstr "``'i'``" - -#: ../../library/array.rst:33 -msgid "signed int" -msgstr "signed int" - -#: ../../library/array.rst:35 -msgid "``'I'``" -msgstr "``'I'``" - -#: ../../library/array.rst:35 -msgid "unsigned int" -msgstr "unsigned int" - -#: ../../library/array.rst:37 -msgid "``'l'``" -msgstr "``'l'``" - -#: ../../library/array.rst:37 -msgid "signed long" -msgstr "signed long" - -#: ../../library/array.rst:39 -msgid "``'L'``" -msgstr "``'L'``" - -#: ../../library/array.rst:39 -msgid "unsigned long" -msgstr "unsigned long" - -#: ../../library/array.rst:41 -msgid "``'q'``" -msgstr "``'q'``" - -#: ../../library/array.rst:41 -msgid "signed long long" -msgstr "signed long long" - -#: ../../library/array.rst:41 ../../library/array.rst:43 -#: ../../library/array.rst:47 -msgid "8" -msgstr "8" - -#: ../../library/array.rst:43 -msgid "``'Q'``" -msgstr "``'Q'``" - -#: ../../library/array.rst:43 -msgid "unsigned long long" -msgstr "unsigned long long" - -#: ../../library/array.rst:45 -msgid "``'f'``" -msgstr "``'f'``" - -#: ../../library/array.rst:45 ../../library/array.rst:47 -msgid "float" -msgstr "float" - -#: ../../library/array.rst:47 -msgid "``'d'``" -msgstr "``'d'``" - -#: ../../library/array.rst:47 -msgid "double" -msgstr "double" - -#: ../../library/array.rst:50 -msgid "Notes:" -msgstr "註解：" - -#: ../../library/array.rst:53 -msgid "It can be 16 bits or 32 bits depending on the platform." -msgstr "根據平台的不同，它有可能是 16 位元或者 32 位元。" - -#: ../../library/array.rst:55 -msgid "" -"``array('u')`` now uses :c:type:`wchar_t` as C type instead of deprecated " -"``Py_UNICODE``. This change doesn't affect its behavior because " -"``Py_UNICODE`` is alias of :c:type:`wchar_t` since Python 3.3." -msgstr "" -"目前 ``array('u')`` 使用 :c:type:`wchar_t` 取代已棄用的 ``Py_UNICODE`` 作為 " -"C type。這個異動並沒有影響到它的作用，因為自從 Python 3.3 開始 " -"``Py_UNICODE`` 即為 :c:type:`wchar_t` 的別名。" - -#: ../../library/array.rst:60 -msgid "Please migrate to ``'w'`` typecode." -msgstr "請改用 ``'w'`` typecode。" - -#: ../../library/array.rst:67 -msgid "" -"The actual representation of values is determined by the machine " -"architecture (strictly speaking, by the C implementation). The actual size " -"can be accessed through the :attr:`array.itemsize` attribute." -msgstr "" -"實際上數值的表示方法是被機器的架構所決定（更精準地說，被 C 的實作方法決定）。" -"實際的大小可以透過 :attr:`array.itemsize` 屬性存取。" - -#: ../../library/array.rst:71 -msgid "The module defines the following item:" -msgstr "這個模組定義了以下項目：" - -#: ../../library/array.rst:76 -msgid "A string with all available type codes." -msgstr "一個包含所有可用的 type codes 的字串。" - -#: ../../library/array.rst:79 -msgid "The module defines the following type:" -msgstr "這個模組定義了下方的型別：" - -#: ../../library/array.rst:84 -msgid "" -"A new array whose items are restricted by *typecode*, and initialized from " -"the optional *initializer* value, which must be a :class:`bytes` or :class:" -"`bytearray` object, a Unicode string, or iterable over elements of the " -"appropriate type." -msgstr "" -"一個新的陣列中的元素被 *typecode* 限制，並由選用的 *initializer* 參數初始化，" -"*initializer* 必須是一個 :class:`bytes` 或 :class:`bytearray` 物件、一個 " -"Unicode 字串或包含適當型別元素的可疊代物件 (iterable)。" - -#: ../../library/array.rst:89 -msgid "" -"If given a :class:`bytes` or :class:`bytearray` object, the initializer is " -"passed to the new array's :meth:`frombytes` method; if given a Unicode " -"string, the initializer is passed to the :meth:`fromunicode` method; " -"otherwise, the initializer's iterator is passed to the :meth:`extend` method " -"to add initial items to the array." -msgstr "" -"如果給定的是一個 :class:`bytes` 或 :class:`bytearray` 物件，新的陣列初始化時" -"會傳入 :meth:`frombytes` 方法；如為 Unicode 字串則會傳入 :meth:`fromunicode` " -"方法；其他情況時， 一個 initializer 的可疊代物件將被傳入 :meth:`extend` 方法" -"之中來將初始項目新增至陣列。" - -#: ../../library/array.rst:96 -msgid "" -"Array objects support the ordinary :ref:`mutable ` :term:" -"`sequence` operations of indexing, slicing, concatenation, and " -"multiplication. When using slice assignment, the assigned value must be an " -"array object with the same type code; in all other cases, :exc:`TypeError` " -"is raised. Array objects also implement the buffer interface, and may be " -"used wherever :term:`bytes-like objects ` are supported." -msgstr "" -"陣列支援常見的\\ :ref:`可變 `\\ :term:" -"`序列 `\\ 操作，包含索引 (indexing)、切片 (slicing)、串接 " -"(concatenation)、相乘 (multiplication) 等。當使用切片進行賦值時，賦值的陣列必" -"須具備相同的 type code，其他型別的數值將導致 :exc:`TypeError`。陣列同時也實作" -"了緩衝區介面，可以在任何支援 :term:`bytes-like objects ` " -"的地方使用。" - -#: ../../library/array.rst:102 -msgid "" -"Raises an :ref:`auditing event ` ``array.__new__`` with arguments " -"``typecode``, ``initializer``." -msgstr "" -"引發\\ :ref:`稽核事件 (auditing event) ` ``array.__new__`` 並附帶引" -"數 ``typecode``、``initializer``。" - -#: ../../library/array.rst:107 -msgid "The typecode character used to create the array." -msgstr "typecode 字元被用在建立陣列時。" - -#: ../../library/array.rst:112 -msgid "The length in bytes of one array item in the internal representation." -msgstr "陣列當中的一個元素在內部需要的位元組長度。" - -#: ../../library/array.rst:117 -msgid "Append a new item with value *x* to the end of the array." -msgstr "新增一個元素 *x* 到陣列的最尾端。" - -#: ../../library/array.rst:122 -msgid "" -"Return a tuple ``(address, length)`` giving the current memory address and " -"the length in elements of the buffer used to hold array's contents. The " -"size of the memory buffer in bytes can be computed as ``array.buffer_info()" -"[1] * array.itemsize``. This is occasionally useful when working with low-" -"level (and inherently unsafe) I/O interfaces that require memory addresses, " -"such as certain :c:func:`!ioctl` operations. The returned numbers are valid " -"as long as the array exists and no length-changing operations are applied to " -"it." -msgstr "" -"回傳一個 tuple ``(address, length)`` 表示目前的記憶體位置和陣列儲存元素的緩衝" -"區記憶體長度。緩衝區的長度單位是位元組，並可以用 ``array.buffer_info()[1] * " -"array.itemsize`` 計算得到。這偶爾會在底層操作需要記憶體位置的輸出輸入時很有" -"用，例如 :c:func:`!ioctl` 指令。只要陣列存在且沒有使用任何更改長度的操作時，" -"回傳的數值就有效。" - -#: ../../library/array.rst:132 -msgid "" -"When using array objects from code written in C or C++ (the only way to " -"effectively make use of this information), it makes more sense to use the " -"buffer interface supported by array objects. This method is maintained for " -"backward compatibility and should be avoided in new code. The buffer " -"interface is documented in :ref:`bufferobjects`." -msgstr "" -"當使用來自 C 或 C++ 程式碼（這是唯一使得這個資訊有效的途徑）的陣列物件時，更" -"適當的做法是使用陣列物件支援的緩衝區介面。這個方法維護了向後兼容性，並應該在" -"新的程式碼中避免。關於緩衝區介面的文件在\\ :ref:`bufferobjects`。" - -#: ../../library/array.rst:141 -msgid "" -"\"Byteswap\" all items of the array. This is only supported for values " -"which are 1, 2, 4, or 8 bytes in size; for other types of values, :exc:" -"`RuntimeError` is raised. It is useful when reading data from a file " -"written on a machine with a different byte order." -msgstr "" -"\"Byteswap\" 所有陣列中的物件。這只有支援物件長度為 1、2、4 或 8 位元組的陣" -"列，其他型別的值會導致 :exc:`RuntimeError`。這在從機器讀取位元順序不同的檔案" -"時很有用。" - -#: ../../library/array.rst:149 -msgid "Return the number of occurrences of *x* in the array." -msgstr "回傳 *x* 在陣列中出現了幾次。" - -#: ../../library/array.rst:154 -msgid "" -"Append items from *iterable* to the end of the array. If *iterable* is " -"another array, it must have *exactly* the same type code; if not, :exc:" -"`TypeError` will be raised. If *iterable* is not an array, it must be " -"iterable and its elements must be the right type to be appended to the array." -msgstr "" -"從 *iterable* 中新增元素到陣列的尾端，如果 *iterable* 是另一個陣列，它必須有" -"完全相同的 type code，如果不同會導致 :exc:`TypeError`。如果 *iterable* 不是一" -"個陣列，它必須可以被疊代 (iterable) 且其中的元素必須是可以被加入陣列中的正確" -"型別。" - -#: ../../library/array.rst:162 -msgid "" -"Appends items from the :term:`bytes-like object`, interpreting its content " -"as an array of machine values (as if it had been read from a file using the :" -"meth:`fromfile` method)." -msgstr "" -"從 :term:`bytes-like object` 中新增元素。讀取時會將其內容當作一個機器數值組成" -"的陣列（就像從檔案中使用 :meth:`fromfile` 方法讀出的資料）。" - -#: ../../library/array.rst:166 -msgid ":meth:`!fromstring` is renamed to :meth:`frombytes` for clarity." -msgstr "將 :meth:`!fromstring` 更名為 :meth:`frombytes`，使其更加清晰易懂。" - -#: ../../library/array.rst:172 -msgid "" -"Read *n* items (as machine values) from the :term:`file object` *f* and " -"append them to the end of the array. If less than *n* items are available, :" -"exc:`EOFError` is raised, but the items that were available are still " -"inserted into the array." -msgstr "" -"從 :term:`file object` *f* 讀取 *n* 個元素（作為機器數值），接著將這些元素加" -"入陣列的最尾端。如果只有少於 *n* 個有效的元素會導致 :exc:`EOFError`，但有效的" -"元素仍然會被加入陣列中。" - -#: ../../library/array.rst:180 -msgid "" -"Append items from the list. This is equivalent to ``for x in list: a." -"append(x)`` except that if there is a type error, the array is unchanged." -msgstr "" -"從 list 中新增元素。這等價於 ``for x in list: a.append(x)``，除了有型別錯誤產" -"生時，陣列會保持原狀不會被更改。" - -#: ../../library/array.rst:186 -msgid "" -"Extends this array with data from the given Unicode string. The array must " -"have type code ``'u'`` or ``'w'``; otherwise a :exc:`ValueError` is raised. " -"Use ``array.frombytes(unicodestring.encode(enc))`` to append Unicode data to " -"an array of some other type." -msgstr "" -"用給定的 Unicode 字串擴展這個陣列。陣列的 type code 必須是 ``u`` 或 ``'w'``；" -"其他的型別會導致 :exc:`ValueError` 被引發。使用 ``array." -"frombytes(unicodestring.encode(enc))`` 來新增 Unicode 資料到一個其他型別的陣" -"列。" - -#: ../../library/array.rst:194 -msgid "" -"Return the smallest *i* such that *i* is the index of the first occurrence " -"of *x* in the array. The optional arguments *start* and *stop* can be " -"specified to search for *x* within a subsection of the array. Raise :exc:" -"`ValueError` if *x* is not found." -msgstr "" -"回傳 *i* 的最小數值，使得 *i* 成為陣列之中第一次出現 *x* 的索引。選擇性的引" -"數 *start* 及 *stop* 則可以被用來在指定的陣列空間中搜尋 *x*。如果 *x* 不存在" -"將導致 :exc:`ValueError`。" - -#: ../../library/array.rst:199 -msgid "Added optional *start* and *stop* parameters." -msgstr "新增選擇性的參數 *start* 及 *stop*。" - -#: ../../library/array.rst:205 -msgid "" -"Insert a new item with value *x* in the array before position *i*. Negative " -"values are treated as being relative to the end of the array." -msgstr "在位置 *i* 之前插入一個元素 *x*。負數的索引值會從陣列尾端開始數。" - -#: ../../library/array.rst:211 -msgid "" -"Removes the item with the index *i* from the array and returns it. The " -"optional argument defaults to ``-1``, so that by default the last item is " -"removed and returned." -msgstr "" -"移除並回傳陣列索引值 *i* 的元素。選擇性的引數 *i* 預設為 ``-1``，所以預設會刪" -"除並回傳最後一個元素。" - -#: ../../library/array.rst:218 -msgid "Remove the first occurrence of *x* from the array." -msgstr "從陣列中刪除第一個出現的 *x*。" - -#: ../../library/array.rst:223 -msgid "Remove all elements from the array." -msgstr "從陣列中刪除所有元素。" - -#: ../../library/array.rst:230 -msgid "Reverse the order of the items in the array." -msgstr "反轉陣列中元素的順序。" - -#: ../../library/array.rst:235 -msgid "" -"Convert the array to an array of machine values and return the bytes " -"representation (the same sequence of bytes that would be written to a file " -"by the :meth:`tofile` method.)" -msgstr "" -"將陣列轉為另一個機器數值組成的陣列並回傳它的位元組表示（跟用 :meth:`tofile` " -"方法寫入檔案時的位元序列相同）。" - -#: ../../library/array.rst:239 -msgid ":meth:`!tostring` is renamed to :meth:`tobytes` for clarity." -msgstr "為了明確性，過去的 :meth:`!tostring` 已更名為 :meth:`tobytes`。" - -#: ../../library/array.rst:245 -msgid "Write all items (as machine values) to the :term:`file object` *f*." -msgstr "將所有元素（作為機器數值）寫入 :term:`file object` *f*。" - -#: ../../library/array.rst:250 -msgid "Convert the array to an ordinary list with the same items." -msgstr "不更改元素，將陣列轉為一般的 list。" - -#: ../../library/array.rst:255 -msgid "" -"Convert the array to a Unicode string. The array must have a type ``'u'`` " -"or ``'w'``; otherwise a :exc:`ValueError` is raised. Use ``array.tobytes()." -"decode(enc)`` to obtain a Unicode string from an array of some other type." -msgstr "" -"將陣列轉為一個 Unicode 字串。陣列的型別必須為 ``u`` 或 ``'w'``；其他型別的陣" -"列會引發 :exc:`ValueError`。請使用 ``array.tobytes().decode(enc)`` 來為其他型" -"別的陣列轉為 Unicode 字串。" - -#: ../../library/array.rst:260 -msgid "" -"The string representation of array objects has the form ``array(typecode, " -"initializer)``. The *initializer* is omitted if the array is empty, " -"otherwise it is a Unicode string if the *typecode* is ``'u'`` or ``'w'``, " -"otherwise it is a list of numbers. The string representation is guaranteed " -"to be able to be converted back to an array with the same type and value " -"using :func:`eval`, so long as the :class:`~array.array` class has been " -"imported using ``from array import array``. Variables ``inf`` and ``nan`` " -"must also be defined if it contains corresponding floating-point values. " -"Examples::" -msgstr "" -"陣列物件的字串表示形式為 ``array(typecode, initializer)``。若為空陣列則參數 " -"*initializer* 被省略，若 *typecode* 是 ``'u'`` 或 ``'w'`` 將被表示為 Unicode " -"字串，其他情況則被表示為由數字組成的 list。只要 :class:`~array.array` class" -"（類別）透過 ``from array import array`` 的方式引入，便能確保該字串表示能透" -"過 :func:`eval` 轉換回一個擁有相同型別及數值的陣列。如果它包含相應的浮點值，" -"``inf`` 和 ``nan`` 也必須被定義。範例： ::" - -#: ../../library/array.rst:272 -msgid "" -"array('l')\n" -"array('w', 'hello \\u2641')\n" -"array('l', [1, 2, 3, 4, 5])\n" -"array('d', [1.0, 2.0, 3.14, -inf, nan])" -msgstr "" -"array('l')\n" -"array('w', 'hello \\u2641')\n" -"array('l', [1, 2, 3, 4, 5])\n" -"array('d', [1.0, 2.0, 3.14, -inf, nan])" - -#: ../../library/array.rst:280 -msgid "Module :mod:`struct`" -msgstr ":mod:`struct` 模組" - -#: ../../library/array.rst:281 -msgid "Packing and unpacking of heterogeneous binary data." -msgstr "將包含不同資料類型的二進位資料包裝與解開包裝。" - -#: ../../library/array.rst:283 -msgid "`NumPy `_" -msgstr "`NumPy `_" - -#: ../../library/array.rst:284 -msgid "The NumPy package defines another array type." -msgstr "NumPy 套件定義了另一個陣列型別" - -#: ../../library/array.rst:7 -msgid "arrays" -msgstr "arrays（陣列）" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Liang-Bo Wang , 2016 +# 周 忠毅 , 2016 +# Adrian Liaw , 2018 +# Benson Chen , 2021 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-01-12 00:16+0000\n" +"PO-Revision-Date: 2021-11-23 18:40+0800\n" +"Last-Translator: Benson Chen \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" +"X-Generator: Poedit 3.0\n" + +#: ../../library/array.rst:2 +msgid ":mod:`!array` --- Efficient arrays of numeric values" +msgstr ":mod:`!array` --- 高效率的數值型陣列" + +#: ../../library/array.rst:11 +msgid "" +"This module defines an object type which can compactly represent an array of " +"basic values: characters, integers, floating-point numbers. Arrays are " +"mutable :term:`sequence` types and behave very much like lists, except that " +"the type of objects stored in them is constrained. The type is specified at " +"object creation time by using a :dfn:`type code`, which is a single " +"character. The following type codes are defined:" +msgstr "" +"這個模組定義了一個物件型別，可以簡潔的表達一個包含基本數值的陣列：字元、整" +"數、浮點數。陣列是一個非常類似 list（串列）的\\ :term:`序列 `\\ 型別，除了陣" +"列會限制儲存的物件型別。在建立陣列時可以使用一個字元的 :dfn:`type code` 來指定儲存的資料" +"型別。以下為有被定義的 type codes：" + +#: ../../library/array.rst:19 +msgid "Type code" +msgstr "Type code" + +#: ../../library/array.rst:19 +msgid "C Type" +msgstr "C Type" + +#: ../../library/array.rst:19 +msgid "Python Type" +msgstr "Python Type" + +#: ../../library/array.rst:19 +msgid "Minimum size in bytes" +msgstr "所需的最小位元組 (bytes)" + +#: ../../library/array.rst:19 +msgid "Notes" +msgstr "註解" + +#: ../../library/array.rst:21 +msgid "``'b'``" +msgstr "``'b'``" + +#: ../../library/array.rst:21 +msgid "signed char" +msgstr "signed char" + +#: ../../library/array.rst:21 ../../library/array.rst:23 +#: ../../library/array.rst:29 ../../library/array.rst:31 +#: ../../library/array.rst:33 ../../library/array.rst:35 +#: ../../library/array.rst:37 ../../library/array.rst:39 +#: ../../library/array.rst:41 ../../library/array.rst:43 +msgid "int" +msgstr "int" + +#: ../../library/array.rst:21 ../../library/array.rst:23 +msgid "1" +msgstr "1" + +#: ../../library/array.rst:23 +msgid "``'B'``" +msgstr "``'B'``" + +#: ../../library/array.rst:23 +msgid "unsigned char" +msgstr "unsigned char" + +#: ../../library/array.rst:25 +msgid "``'u'``" +msgstr "``'u'``" + +#: ../../library/array.rst:25 +msgid "wchar_t" +msgstr "wchar_t" + +#: ../../library/array.rst:25 ../../library/array.rst:27 +msgid "Unicode character" +msgstr "Unicode character" + +#: ../../library/array.rst:25 ../../library/array.rst:29 +#: ../../library/array.rst:31 ../../library/array.rst:33 +#: ../../library/array.rst:35 +msgid "2" +msgstr "2" + +#: ../../library/array.rst:25 +msgid "\\(1)" +msgstr "\\(1)" + +#: ../../library/array.rst:27 +msgid "``'w'``" +msgstr "``'w'``" + +#: ../../library/array.rst:27 +msgid "Py_UCS4" +msgstr "Py_UCS4" + +#: ../../library/array.rst:27 ../../library/array.rst:37 +#: ../../library/array.rst:39 ../../library/array.rst:45 +msgid "4" +msgstr "4" + +#: ../../library/array.rst:27 +msgid "\\(2)" +msgstr "\\(2)" + +#: ../../library/array.rst:29 +msgid "``'h'``" +msgstr "``'h'``" + +#: ../../library/array.rst:29 +msgid "signed short" +msgstr "signed short" + +#: ../../library/array.rst:31 +msgid "``'H'``" +msgstr "``'H'``" + +#: ../../library/array.rst:31 +msgid "unsigned short" +msgstr "unsigned short" + +#: ../../library/array.rst:33 +msgid "``'i'``" +msgstr "``'i'``" + +#: ../../library/array.rst:33 +msgid "signed int" +msgstr "signed int" + +#: ../../library/array.rst:35 +msgid "``'I'``" +msgstr "``'I'``" + +#: ../../library/array.rst:35 +msgid "unsigned int" +msgstr "unsigned int" + +#: ../../library/array.rst:37 +msgid "``'l'``" +msgstr "``'l'``" + +#: ../../library/array.rst:37 +msgid "signed long" +msgstr "signed long" + +#: ../../library/array.rst:39 +msgid "``'L'``" +msgstr "``'L'``" + +#: ../../library/array.rst:39 +msgid "unsigned long" +msgstr "unsigned long" + +#: ../../library/array.rst:41 +msgid "``'q'``" +msgstr "``'q'``" + +#: ../../library/array.rst:41 +msgid "signed long long" +msgstr "signed long long" + +#: ../../library/array.rst:41 ../../library/array.rst:43 +#: ../../library/array.rst:47 +msgid "8" +msgstr "8" + +#: ../../library/array.rst:43 +msgid "``'Q'``" +msgstr "``'Q'``" + +#: ../../library/array.rst:43 +msgid "unsigned long long" +msgstr "unsigned long long" + +#: ../../library/array.rst:45 +msgid "``'f'``" +msgstr "``'f'``" + +#: ../../library/array.rst:45 ../../library/array.rst:47 +msgid "float" +msgstr "float" + +#: ../../library/array.rst:47 +msgid "``'d'``" +msgstr "``'d'``" + +#: ../../library/array.rst:47 +msgid "double" +msgstr "double" + +#: ../../library/array.rst:50 +msgid "Notes:" +msgstr "註解：" + +#: ../../library/array.rst:53 +msgid "It can be 16 bits or 32 bits depending on the platform." +msgstr "根據平台的不同，它有可能是 16 位元或者 32 位元。" + +#: ../../library/array.rst:55 +msgid "" +"``array('u')`` now uses :c:type:`wchar_t` as C type instead of deprecated " +"``Py_UNICODE``. This change doesn't affect its behavior because " +"``Py_UNICODE`` is alias of :c:type:`wchar_t` since Python 3.3." +msgstr "" +"目前 ``array('u')`` 使用 :c:type:`wchar_t` 取代已棄用的 ``Py_UNICODE`` 作為 " +"C type。這個異動並沒有影響到它的作用，因為自從 Python 3.3 開始 " +"``Py_UNICODE`` 即為 :c:type:`wchar_t` 的別名。" + +#: ../../library/array.rst:60 +msgid "Please migrate to ``'w'`` typecode." +msgstr "請改用 ``'w'`` typecode。" + +#: ../../library/array.rst:67 +msgid "" +"The actual representation of values is determined by the machine " +"architecture (strictly speaking, by the C implementation). The actual size " +"can be accessed through the :attr:`array.itemsize` attribute." +msgstr "" +"實際上數值的表示方法是被機器的架構所決定（更精準地說，被 C 的實作方法決定）。" +"實際的大小可以透過 :attr:`array.itemsize` 屬性存取。" + +#: ../../library/array.rst:71 +msgid "The module defines the following item:" +msgstr "這個模組定義了以下項目：" + +#: ../../library/array.rst:76 +msgid "A string with all available type codes." +msgstr "一個包含所有可用的 type codes 的字串。" + +#: ../../library/array.rst:79 +msgid "The module defines the following type:" +msgstr "這個模組定義了下方的型別：" + +#: ../../library/array.rst:84 +msgid "" +"A new array whose items are restricted by *typecode*, and initialized from " +"the optional *initializer* value, which must be a :class:`bytes` or :class:" +"`bytearray` object, a Unicode string, or iterable over elements of the " +"appropriate type." +msgstr "" +"一個新的陣列中的元素被 *typecode* 限制，並由選用的 *initializer* 參數初始化，" +"*initializer* 必須是一個 :class:`bytes` 或 :class:`bytearray` 物件、一個 " +"Unicode 字串或包含適當型別元素的可疊代物件 (iterable)。" + +#: ../../library/array.rst:89 +msgid "" +"If given a :class:`bytes` or :class:`bytearray` object, the initializer is " +"passed to the new array's :meth:`frombytes` method; if given a Unicode " +"string, the initializer is passed to the :meth:`fromunicode` method; " +"otherwise, the initializer's iterator is passed to the :meth:`extend` method " +"to add initial items to the array." +msgstr "" +"如果給定的是一個 :class:`bytes` 或 :class:`bytearray` 物件，新的陣列初始化時" +"會傳入 :meth:`frombytes` 方法；如為 Unicode 字串則會傳入 :meth:`fromunicode` " +"方法；其他情況時， 一個 initializer 的可疊代物件將被傳入 :meth:`extend` 方法" +"之中來將初始項目新增至陣列。" + +#: ../../library/array.rst:96 +msgid "" +"Array objects support the ordinary :ref:`mutable ` :term:" +"`sequence` operations of indexing, slicing, concatenation, and " +"multiplication. When using slice assignment, the assigned value must be an " +"array object with the same type code; in all other cases, :exc:`TypeError` " +"is raised. Array objects also implement the buffer interface, and may be " +"used wherever :term:`bytes-like objects ` are supported." +msgstr "" +"陣列支援常見的\\ :ref:`可變 `\\ :term:" +"`序列 `\\ 操作，包含索引 (indexing)、切片 (slicing)、串接 " +"(concatenation)、相乘 (multiplication) 等。當使用切片進行賦值時，賦值的陣列必" +"須具備相同的 type code，其他型別的數值將導致 :exc:`TypeError`。陣列同時也實作" +"了緩衝區介面，可以在任何支援 :term:`bytes-like objects ` " +"的地方使用。" + +#: ../../library/array.rst:102 +msgid "" +"Raises an :ref:`auditing event ` ``array.__new__`` with arguments " +"``typecode``, ``initializer``." +msgstr "" +"引發\\ :ref:`稽核事件 (auditing event) ` ``array.__new__`` 並附帶引" +"數 ``typecode``、``initializer``。" + +#: ../../library/array.rst:107 +msgid "The typecode character used to create the array." +msgstr "typecode 字元被用在建立陣列時。" + +#: ../../library/array.rst:112 +msgid "The length in bytes of one array item in the internal representation." +msgstr "陣列當中的一個元素在內部需要的位元組長度。" + +#: ../../library/array.rst:117 +msgid "Append a new item with value *x* to the end of the array." +msgstr "新增一個元素 *x* 到陣列的最尾端。" + +#: ../../library/array.rst:122 +msgid "" +"Return a tuple ``(address, length)`` giving the current memory address and " +"the length in elements of the buffer used to hold array's contents. The " +"size of the memory buffer in bytes can be computed as ``array.buffer_info()" +"[1] * array.itemsize``. This is occasionally useful when working with low-" +"level (and inherently unsafe) I/O interfaces that require memory addresses, " +"such as certain :c:func:`!ioctl` operations. The returned numbers are valid " +"as long as the array exists and no length-changing operations are applied to " +"it." +msgstr "" +"回傳一個 tuple ``(address, length)`` 表示目前的記憶體位置和陣列儲存元素的緩衝" +"區記憶體長度。緩衝區的長度單位是位元組，並可以用 ``array.buffer_info()[1] * " +"array.itemsize`` 計算得到。這偶爾會在底層操作需要記憶體位置的輸出輸入時很有" +"用，例如 :c:func:`!ioctl` 指令。只要陣列存在且沒有使用任何更改長度的操作時，" +"回傳的數值就有效。" + +#: ../../library/array.rst:132 +msgid "" +"When using array objects from code written in C or C++ (the only way to " +"effectively make use of this information), it makes more sense to use the " +"buffer interface supported by array objects. This method is maintained for " +"backward compatibility and should be avoided in new code. The buffer " +"interface is documented in :ref:`bufferobjects`." +msgstr "" +"當使用來自 C 或 C++ 程式碼（這是唯一使得這個資訊有效的途徑）的陣列物件時，更" +"適當的做法是使用陣列物件支援的緩衝區介面。這個方法維護了向後兼容性，並應該在" +"新的程式碼中避免。關於緩衝區介面的文件在\\ :ref:`bufferobjects`。" + +#: ../../library/array.rst:141 +msgid "" +"\"Byteswap\" all items of the array. This is only supported for values " +"which are 1, 2, 4, or 8 bytes in size; for other types of values, :exc:" +"`RuntimeError` is raised. It is useful when reading data from a file " +"written on a machine with a different byte order." +msgstr "" +"\"Byteswap\" 所有陣列中的物件。這只有支援物件長度為 1、2、4 或 8 位元組的陣" +"列，其他型別的值會導致 :exc:`RuntimeError`。這在從機器讀取位元順序不同的檔案" +"時很有用。" + +#: ../../library/array.rst:149 +msgid "Return the number of occurrences of *x* in the array." +msgstr "回傳 *x* 在陣列中出現了幾次。" + +#: ../../library/array.rst:154 +msgid "" +"Append items from *iterable* to the end of the array. If *iterable* is " +"another array, it must have *exactly* the same type code; if not, :exc:" +"`TypeError` will be raised. If *iterable* is not an array, it must be " +"iterable and its elements must be the right type to be appended to the array." +msgstr "" +"從 *iterable* 中新增元素到陣列的尾端，如果 *iterable* 是另一個陣列，它必須有" +"完全相同的 type code，如果不同會導致 :exc:`TypeError`。如果 *iterable* 不是一" +"個陣列，它必須可以被疊代 (iterable) 且其中的元素必須是可以被加入陣列中的正確" +"型別。" + +#: ../../library/array.rst:162 +msgid "" +"Appends items from the :term:`bytes-like object`, interpreting its content " +"as an array of machine values (as if it had been read from a file using the :" +"meth:`fromfile` method)." +msgstr "" +"從 :term:`bytes-like object` 中新增元素。讀取時會將其內容當作一個機器數值組成" +"的陣列（就像從檔案中使用 :meth:`fromfile` 方法讀出的資料）。" + +#: ../../library/array.rst:166 +msgid ":meth:`!fromstring` is renamed to :meth:`frombytes` for clarity." +msgstr "將 :meth:`!fromstring` 更名為 :meth:`frombytes`，使其更加清晰易懂。" + +#: ../../library/array.rst:172 +msgid "" +"Read *n* items (as machine values) from the :term:`file object` *f* and " +"append them to the end of the array. If less than *n* items are available, :" +"exc:`EOFError` is raised, but the items that were available are still " +"inserted into the array." +msgstr "" +"從 :term:`file object` *f* 讀取 *n* 個元素（作為機器數值），接著將這些元素加" +"入陣列的最尾端。如果只有少於 *n* 個有效的元素會導致 :exc:`EOFError`，但有效的" +"元素仍然會被加入陣列中。" + +#: ../../library/array.rst:180 +msgid "" +"Append items from the list. This is equivalent to ``for x in list: a." +"append(x)`` except that if there is a type error, the array is unchanged." +msgstr "" +"從 list 中新增元素。這等價於 ``for x in list: a.append(x)``，除了有型別錯誤產" +"生時，陣列會保持原狀不會被更改。" + +#: ../../library/array.rst:186 +msgid "" +"Extends this array with data from the given Unicode string. The array must " +"have type code ``'u'`` or ``'w'``; otherwise a :exc:`ValueError` is raised. " +"Use ``array.frombytes(unicodestring.encode(enc))`` to append Unicode data to " +"an array of some other type." +msgstr "" +"用給定的 Unicode 字串擴展這個陣列。陣列的 type code 必須是 ``u`` 或 ``'w'``；" +"其他的型別會導致 :exc:`ValueError` 被引發。使用 ``array." +"frombytes(unicodestring.encode(enc))`` 來新增 Unicode 資料到一個其他型別的陣" +"列。" + +#: ../../library/array.rst:194 +msgid "" +"Return the smallest *i* such that *i* is the index of the first occurrence " +"of *x* in the array. The optional arguments *start* and *stop* can be " +"specified to search for *x* within a subsection of the array. Raise :exc:" +"`ValueError` if *x* is not found." +msgstr "" +"回傳 *i* 的最小數值，使得 *i* 成為陣列之中第一次出現 *x* 的索引。選擇性的引" +"數 *start* 及 *stop* 則可以被用來在指定的陣列空間中搜尋 *x*。如果 *x* 不存在" +"將導致 :exc:`ValueError`。" + +#: ../../library/array.rst:199 +msgid "Added optional *start* and *stop* parameters." +msgstr "新增選擇性的參數 *start* 及 *stop*。" + +#: ../../library/array.rst:205 +msgid "" +"Insert a new item with value *x* in the array before position *i*. Negative " +"values are treated as being relative to the end of the array." +msgstr "在位置 *i* 之前插入一個元素 *x*。負數的索引值會從陣列尾端開始數。" + +#: ../../library/array.rst:211 +msgid "" +"Removes the item with the index *i* from the array and returns it. The " +"optional argument defaults to ``-1``, so that by default the last item is " +"removed and returned." +msgstr "" +"移除並回傳陣列索引值 *i* 的元素。選擇性的引數 *i* 預設為 ``-1``，所以預設會刪" +"除並回傳最後一個元素。" + +#: ../../library/array.rst:218 +msgid "Remove the first occurrence of *x* from the array." +msgstr "從陣列中刪除第一個出現的 *x*。" + +#: ../../library/array.rst:223 +msgid "Remove all elements from the array." +msgstr "從陣列中刪除所有元素。" + +#: ../../library/array.rst:230 +msgid "Reverse the order of the items in the array." +msgstr "反轉陣列中元素的順序。" + +#: ../../library/array.rst:235 +msgid "" +"Convert the array to an array of machine values and return the bytes " +"representation (the same sequence of bytes that would be written to a file " +"by the :meth:`tofile` method.)" +msgstr "" +"將陣列轉為另一個機器數值組成的陣列並回傳它的位元組表示（跟用 :meth:`tofile` " +"方法寫入檔案時的位元序列相同）。" + +#: ../../library/array.rst:239 +msgid ":meth:`!tostring` is renamed to :meth:`tobytes` for clarity." +msgstr "為了明確性，過去的 :meth:`!tostring` 已更名為 :meth:`tobytes`。" + +#: ../../library/array.rst:245 +msgid "Write all items (as machine values) to the :term:`file object` *f*." +msgstr "將所有元素（作為機器數值）寫入 :term:`file object` *f*。" + +#: ../../library/array.rst:250 +msgid "Convert the array to an ordinary list with the same items." +msgstr "不更改元素，將陣列轉為一般的 list。" + +#: ../../library/array.rst:255 +msgid "" +"Convert the array to a Unicode string. The array must have a type ``'u'`` " +"or ``'w'``; otherwise a :exc:`ValueError` is raised. Use ``array.tobytes()." +"decode(enc)`` to obtain a Unicode string from an array of some other type." +msgstr "" +"將陣列轉為一個 Unicode 字串。陣列的型別必須為 ``u`` 或 ``'w'``；其他型別的陣" +"列會引發 :exc:`ValueError`。請使用 ``array.tobytes().decode(enc)`` 來為其他型" +"別的陣列轉為 Unicode 字串。" + +#: ../../library/array.rst:260 +msgid "" +"The string representation of array objects has the form ``array(typecode, " +"initializer)``. The *initializer* is omitted if the array is empty, " +"otherwise it is a Unicode string if the *typecode* is ``'u'`` or ``'w'``, " +"otherwise it is a list of numbers. The string representation is guaranteed " +"to be able to be converted back to an array with the same type and value " +"using :func:`eval`, so long as the :class:`~array.array` class has been " +"imported using ``from array import array``. Variables ``inf`` and ``nan`` " +"must also be defined if it contains corresponding floating-point values. " +"Examples::" +msgstr "" +"陣列物件的字串表示形式為 ``array(typecode, initializer)``。若為空陣列則參數 " +"*initializer* 被省略，若 *typecode* 是 ``'u'`` 或 ``'w'`` 將被表示為 Unicode " +"字串，其他情況則被表示為由數字組成的 list。只要 :class:`~array.array` class" +"（類別）透過 ``from array import array`` 的方式引入，便能確保該字串表示能透" +"過 :func:`eval` 轉換回一個擁有相同型別及數值的陣列。如果它包含相應的浮點值，" +"``inf`` 和 ``nan`` 也必須被定義。範例： ::" + +#: ../../library/array.rst:272 +msgid "" +"array('l')\n" +"array('w', 'hello \\u2641')\n" +"array('l', [1, 2, 3, 4, 5])\n" +"array('d', [1.0, 2.0, 3.14, -inf, nan])" +msgstr "" +"array('l')\n" +"array('w', 'hello \\u2641')\n" +"array('l', [1, 2, 3, 4, 5])\n" +"array('d', [1.0, 2.0, 3.14, -inf, nan])" + +#: ../../library/array.rst:280 +msgid "Module :mod:`struct`" +msgstr ":mod:`struct` 模組" + +#: ../../library/array.rst:281 +msgid "Packing and unpacking of heterogeneous binary data." +msgstr "將包含不同資料類型的二進位資料包裝與解開包裝。" + +#: ../../library/array.rst:283 +msgid "`NumPy `_" +msgstr "`NumPy `_" + +#: ../../library/array.rst:284 +msgid "The NumPy package defines another array type." +msgstr "NumPy 套件定義了另一個陣列型別" + +#: ../../library/array.rst:7 +msgid "arrays" +msgstr "arrays（陣列）" diff --git a/library/ast.po b/library/ast.po index 7e4692bb7c..6e214a8bba 100644 --- a/library/ast.po +++ b/library/ast.po @@ -1,4655 +1,4655 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-12-30 00:15+0000\n" -"PO-Revision-Date: 2018-05-23 14:38+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/ast.rst:2 -msgid ":mod:`!ast` --- Abstract syntax trees" -msgstr ":mod:`!ast` --- 抽象語法樹 (Abstract Syntax Trees)" - -#: ../../library/ast.rst:14 -msgid "**Source code:** :source:`Lib/ast.py`" -msgstr "**原始碼：**\\ :source:`Lib/ast.py`" - -#: ../../library/ast.rst:18 -msgid "" -"The :mod:`ast` module helps Python applications to process trees of the " -"Python abstract syntax grammar. The abstract syntax itself might change " -"with each Python release; this module helps to find out programmatically " -"what the current grammar looks like." -msgstr "" -":mod:`ast` 模組可以幫助 Python 應用程式處理 Python 抽象語法文法 (abstract " -"syntax grammar) 樹狀資料結構。抽象語法本身可能會隨著每個 Python 版本發布而改" -"變；此模組有助於以程式化的方式來得知目前文法的面貌。" - -#: ../../library/ast.rst:23 -msgid "" -"An abstract syntax tree can be generated by passing :data:`ast." -"PyCF_ONLY_AST` as a flag to the :func:`compile` built-in function, or using " -"the :func:`parse` helper provided in this module. The result will be a tree " -"of objects whose classes all inherit from :class:`ast.AST`. An abstract " -"syntax tree can be compiled into a Python code object using the built-in :" -"func:`compile` function." -msgstr "" -"要生成抽象語法樹，可以透過將 :data:`ast.PyCF_ONLY_AST` 作為旗標傳遞給內建函" -"式 :func:`compile` 或使用此模組所提供的 :func:`parse` 輔助函式。結果將會是一" -"個物件的樹，其類別都繼承自 :class:`ast.AST`。可以使用內建的 :func:`compile` " -"函式將抽象語法樹編譯成 Python 程式碼物件。" - -#: ../../library/ast.rst:33 -msgid "Abstract grammar" -msgstr "抽象文法 (Abstract Grammar)" - -#: ../../library/ast.rst:35 -msgid "The abstract grammar is currently defined as follows:" -msgstr "抽象文法目前定義如下：" - -#: ../../library/ast.rst:37 -msgid "" -"-- ASDL's 4 builtin types are:\n" -"-- identifier, int, string, constant\n" -"\n" -"module Python\n" -"{\n" -" mod = Module(stmt* body, type_ignore* type_ignores)\n" -" | Interactive(stmt* body)\n" -" | Expression(expr body)\n" -" | FunctionType(expr* argtypes, expr returns)\n" -"\n" -" stmt = FunctionDef(identifier name, arguments args,\n" -" stmt* body, expr* decorator_list, expr? returns,\n" -" string? type_comment, type_param* type_params)\n" -" | AsyncFunctionDef(identifier name, arguments args,\n" -" stmt* body, expr* decorator_list, expr? " -"returns,\n" -" string? type_comment, type_param* type_params)\n" -"\n" -" | ClassDef(identifier name,\n" -" expr* bases,\n" -" keyword* keywords,\n" -" stmt* body,\n" -" expr* decorator_list,\n" -" type_param* type_params)\n" -" | Return(expr? value)\n" -"\n" -" | Delete(expr* targets)\n" -" | Assign(expr* targets, expr value, string? type_comment)\n" -" | TypeAlias(expr name, type_param* type_params, expr value)\n" -" | AugAssign(expr target, operator op, expr value)\n" -" -- 'simple' indicates that we annotate simple name without parens\n" -" | AnnAssign(expr target, expr annotation, expr? value, int " -"simple)\n" -"\n" -" -- use 'orelse' because else is a keyword in target languages\n" -" | For(expr target, expr iter, stmt* body, stmt* orelse, string? " -"type_comment)\n" -" | AsyncFor(expr target, expr iter, stmt* body, stmt* orelse, " -"string? type_comment)\n" -" | While(expr test, stmt* body, stmt* orelse)\n" -" | If(expr test, stmt* body, stmt* orelse)\n" -" | With(withitem* items, stmt* body, string? type_comment)\n" -" | AsyncWith(withitem* items, stmt* body, string? type_comment)\n" -"\n" -" | Match(expr subject, match_case* cases)\n" -"\n" -" | Raise(expr? exc, expr? cause)\n" -" | Try(stmt* body, excepthandler* handlers, stmt* orelse, stmt* " -"finalbody)\n" -" | TryStar(stmt* body, excepthandler* handlers, stmt* orelse, stmt* " -"finalbody)\n" -" | Assert(expr test, expr? msg)\n" -"\n" -" | Import(alias* names)\n" -" | ImportFrom(identifier? module, alias* names, int? level)\n" -"\n" -" | Global(identifier* names)\n" -" | Nonlocal(identifier* names)\n" -" | Expr(expr value)\n" -" | Pass | Break | Continue\n" -"\n" -" -- col_offset is the byte offset in the utf8 string the parser " -"uses\n" -" attributes (int lineno, int col_offset, int? end_lineno, int? " -"end_col_offset)\n" -"\n" -" -- BoolOp() can use left & right?\n" -" expr = BoolOp(boolop op, expr* values)\n" -" | NamedExpr(expr target, expr value)\n" -" | BinOp(expr left, operator op, expr right)\n" -" | UnaryOp(unaryop op, expr operand)\n" -" | Lambda(arguments args, expr body)\n" -" | IfExp(expr test, expr body, expr orelse)\n" -" | Dict(expr?* keys, expr* values)\n" -" | Set(expr* elts)\n" -" | ListComp(expr elt, comprehension* generators)\n" -" | SetComp(expr elt, comprehension* generators)\n" -" | DictComp(expr key, expr value, comprehension* generators)\n" -" | GeneratorExp(expr elt, comprehension* generators)\n" -" -- the grammar constrains where yield expressions can occur\n" -" | Await(expr value)\n" -" | Yield(expr? value)\n" -" | YieldFrom(expr value)\n" -" -- need sequences for compare to distinguish between\n" -" -- x < 4 < 3 and (x < 4) < 3\n" -" | Compare(expr left, cmpop* ops, expr* comparators)\n" -" | Call(expr func, expr* args, keyword* keywords)\n" -" | FormattedValue(expr value, int conversion, expr? format_spec)\n" -" | Interpolation(expr value, constant str, int conversion, expr? " -"format_spec)\n" -" | JoinedStr(expr* values)\n" -" | TemplateStr(expr* values)\n" -" | Constant(constant value, string? kind)\n" -"\n" -" -- the following expression can appear in assignment context\n" -" | Attribute(expr value, identifier attr, expr_context ctx)\n" -" | Subscript(expr value, expr slice, expr_context ctx)\n" -" | Starred(expr value, expr_context ctx)\n" -" | Name(identifier id, expr_context ctx)\n" -" | List(expr* elts, expr_context ctx)\n" -" | Tuple(expr* elts, expr_context ctx)\n" -"\n" -" -- can appear only in Subscript\n" -" | Slice(expr? lower, expr? upper, expr? step)\n" -"\n" -" -- col_offset is the byte offset in the utf8 string the parser " -"uses\n" -" attributes (int lineno, int col_offset, int? end_lineno, int? " -"end_col_offset)\n" -"\n" -" expr_context = Load | Store | Del\n" -"\n" -" boolop = And | Or\n" -"\n" -" operator = Add | Sub | Mult | MatMult | Div | Mod | Pow | LShift\n" -" | RShift | BitOr | BitXor | BitAnd | FloorDiv\n" -"\n" -" unaryop = Invert | Not | UAdd | USub\n" -"\n" -" cmpop = Eq | NotEq | Lt | LtE | Gt | GtE | Is | IsNot | In | NotIn\n" -"\n" -" comprehension = (expr target, expr iter, expr* ifs, int is_async)\n" -"\n" -" excepthandler = ExceptHandler(expr? type, identifier? name, stmt* body)\n" -" attributes (int lineno, int col_offset, int? end_lineno, " -"int? end_col_offset)\n" -"\n" -" arguments = (arg* posonlyargs, arg* args, arg? vararg, arg* kwonlyargs,\n" -" expr?* kw_defaults, arg? kwarg, expr* defaults)\n" -"\n" -" arg = (identifier arg, expr? annotation, string? type_comment)\n" -" attributes (int lineno, int col_offset, int? end_lineno, int? " -"end_col_offset)\n" -"\n" -" -- keyword arguments supplied to call (NULL identifier for **kwargs)\n" -" keyword = (identifier? arg, expr value)\n" -" attributes (int lineno, int col_offset, int? end_lineno, int? " -"end_col_offset)\n" -"\n" -" -- import name with optional 'as' alias.\n" -" alias = (identifier name, identifier? asname)\n" -" attributes (int lineno, int col_offset, int? end_lineno, int? " -"end_col_offset)\n" -"\n" -" withitem = (expr context_expr, expr? optional_vars)\n" -"\n" -" match_case = (pattern pattern, expr? guard, stmt* body)\n" -"\n" -" pattern = MatchValue(expr value)\n" -" | MatchSingleton(constant value)\n" -" | MatchSequence(pattern* patterns)\n" -" | MatchMapping(expr* keys, pattern* patterns, identifier? rest)\n" -" | MatchClass(expr cls, pattern* patterns, identifier* kwd_attrs, " -"pattern* kwd_patterns)\n" -"\n" -" | MatchStar(identifier? name)\n" -" -- The optional \"rest\" MatchMapping parameter handles " -"capturing extra mapping keys\n" -"\n" -" | MatchAs(pattern? pattern, identifier? name)\n" -" | MatchOr(pattern* patterns)\n" -"\n" -" attributes (int lineno, int col_offset, int end_lineno, int " -"end_col_offset)\n" -"\n" -" type_ignore = TypeIgnore(int lineno, string tag)\n" -"\n" -" type_param = TypeVar(identifier name, expr? bound, expr? default_value)\n" -" | ParamSpec(identifier name, expr? default_value)\n" -" | TypeVarTuple(identifier name, expr? default_value)\n" -" attributes (int lineno, int col_offset, int end_lineno, int " -"end_col_offset)\n" -"}\n" -msgstr "" - -#: ../../library/ast.rst:42 -msgid "Node classes" -msgstr "節點 (Node) 類別" - -#: ../../library/ast.rst:46 -msgid "" -"This is the base of all AST node classes. The actual node classes are " -"derived from the :file:`Parser/Python.asdl` file, which is reproduced :ref:" -"`above `. They are defined in the :mod:`!_ast` C module " -"and re-exported in :mod:`ast`." -msgstr "" -"這是所有 AST 節點類別的基礎。實際的節點類別是衍生自 :file:`Parser/Python." -"asdl` 檔案，該檔案在\\ :ref:`上方 ` 重現。它們被定義於 :" -"mod:`!_ast` 的 C 模組中，並於 :mod:`ast` 中重新匯出。" - -#: ../../library/ast.rst:51 -msgid "" -"There is one class defined for each left-hand side symbol in the abstract " -"grammar (for example, :class:`ast.stmt` or :class:`ast.expr`). In addition, " -"there is one class defined for each constructor on the right-hand side; " -"these classes inherit from the classes for the left-hand side trees. For " -"example, :class:`ast.BinOp` inherits from :class:`ast.expr`. For production " -"rules with alternatives (aka \"sums\"), the left-hand side class is " -"abstract: only instances of specific constructor nodes are ever created." -msgstr "" -"抽象文法中為每個左側符號定義了一個類別（例如 :class:`ast.stmt` 或 :class:" -"`ast.expr`）。此外，也為每個右側的建構函式 (constructor) 定義了一個類別；這些" -"類別繼承自左側樹的類別。例如，:class:`ast.BinOp` 繼承自 :class:`ast.expr`。對" -"於具有替代方案（即為「和 (sums)」）的生產規則，左側類別是抽象的：僅有特定建構" -"函式節點的實例會被建立。" - -#: ../../library/ast.rst:64 -msgid "" -"Each concrete class has an attribute :attr:`!_fields` which gives the names " -"of all child nodes." -msgstr "每個具體類別都有一個屬性 :attr:`!_fields`，它會給出所有子節點的名稱。" - -#: ../../library/ast.rst:67 -msgid "" -"Each instance of a concrete class has one attribute for each child node, of " -"the type as defined in the grammar. For example, :class:`ast.BinOp` " -"instances have an attribute :attr:`left` of type :class:`ast.expr`." -msgstr "" -"具體類別的每個實例對於每個子節點都有一個屬性，其型別如文法中所定義。例如，:" -"class:`ast.BinOp` 實例具有型別為 :class:`ast.expr` 的屬性 :attr:`left`。" - -#: ../../library/ast.rst:71 -msgid "" -"If these attributes are marked as optional in the grammar (using a question " -"mark), the value might be ``None``. If the attributes can have zero-or-more " -"values (marked with an asterisk), the values are represented as Python " -"lists. All possible attributes must be present and have valid values when " -"compiling an AST with :func:`compile`." -msgstr "" -"如果這些屬性在文法中被標記為可選（使用問號），則該值可能為 ``None``。如果屬性" -"可以有零個或多個值（用星號標記），則這些值將表示為 Python 串列。使用 :func:" -"`compile` 編譯 AST 時，所有可能的屬性都必須存在並且具有有效值。" - -#: ../../library/ast.rst:79 -msgid "" -"The :attr:`!_field_types` attribute on each concrete class is a dictionary " -"mapping field names (as also listed in :attr:`_fields`) to their types." -msgstr "" -"每個具體類別上的 :attr:`!_field_types` 屬性是將欄位名稱（也在 :attr:" -"`_fields` 中列出）對映到其型別的字典。" - -#: ../../library/ast.rst:82 -msgid "" -">>> ast.TypeVar._field_types\n" -"{'name': , 'bound': ast.expr | None, 'default_value': ast.expr " -"| None}" -msgstr "" -">>> ast.TypeVar._field_types\n" -"{'name': , 'bound': ast.expr | None, 'default_value': ast.expr " -"| None}" - -#: ../../library/ast.rst:94 -msgid "" -"Instances of :class:`ast.expr` and :class:`ast.stmt` subclasses have :attr:" -"`lineno`, :attr:`col_offset`, :attr:`end_lineno`, and :attr:`end_col_offset` " -"attributes. The :attr:`lineno` and :attr:`end_lineno` are the first and " -"last line numbers of source text span (1-indexed so the first line is line " -"1) and the :attr:`col_offset` and :attr:`end_col_offset` are the " -"corresponding UTF-8 byte offsets of the first and last tokens that generated " -"the node. The UTF-8 offset is recorded because the parser uses UTF-8 " -"internally." -msgstr "" -":class:`ast.expr` 和 :class:`ast.stmt` 子類別的實例具有 :attr:`lineno`、:" -"attr:`col_offset`、:attr:`end_lineno` 和 :attr:`end_col_offset` 屬性。:attr:" -"`lineno` 和 :attr:`end_lineno` 是原始文本跨度 (source text span) 的第一個和最" -"後一個列號（1-indexed，因此第一列號是 1）以及 :attr:`col_offset` 和 :attr:" -"`end_col_offset` 是生成節點的第一個和最後一個標記對應的 UTF-8 位元組偏移量。" -"會記錄 UTF-8 偏移量是因為剖析器 (parser) 內部使用 UTF-8。" - -#: ../../library/ast.rst:103 -msgid "" -"Note that the end positions are not required by the compiler and are " -"therefore optional. The end offset is *after* the last symbol, for example " -"one can get the source segment of a one-line expression node using " -"``source_line[node.col_offset : node.end_col_offset]``." -msgstr "" -"請注意，編譯器並不需要結束位置，因此其為可選的。結束偏移量在最後一個符號\\ *" -"之後*，例如可以使用 ``source_line[node.col_offset : node.end_col_offset]`` 來" -"取得單列運算式節點 (expression node) 的原始片段。" - -#: ../../library/ast.rst:108 -msgid "" -"The constructor of a class :class:`ast.T` parses its arguments as follows:" -msgstr ":class:`ast.T` 類別的建構函式按以下方式剖析其引數：" - -#: ../../library/ast.rst:110 -msgid "" -"If there are positional arguments, there must be as many as there are items " -"in :attr:`T._fields`; they will be assigned as attributes of these names." -msgstr "" -"如果有位置引數，則必須與 :attr:`T._fields` 中的項目一樣多；它們將被賦値為這些" -"名稱的屬性。" - -#: ../../library/ast.rst:112 -msgid "" -"If there are keyword arguments, they will set the attributes of the same " -"names to the given values." -msgstr "如果有關鍵字引數，它們會將相同名稱的屬性設定為給定值。" - -#: ../../library/ast.rst:115 -msgid "" -"For example, to create and populate an :class:`ast.UnaryOp` node, you could " -"use ::" -msgstr "" -"例如，要建立並填充 (populate) :class:`ast.UnaryOp` 節點，你可以使用： ::" - -#: ../../library/ast.rst:118 -msgid "" -"node = ast.UnaryOp(ast.USub(), ast.Constant(5, lineno=0, col_offset=0),\n" -" lineno=0, col_offset=0)" -msgstr "" -"node = ast.UnaryOp(ast.USub(), ast.Constant(5, lineno=0, col_offset=0),\n" -" lineno=0, col_offset=0)" - -#: ../../library/ast.rst:121 -msgid "" -"If a field that is optional in the grammar is omitted from the constructor, " -"it defaults to ``None``. If a list field is omitted, it defaults to the " -"empty list. If a field of type :class:`!ast.expr_context` is omitted, it " -"defaults to :class:`Load() `. If any other field is omitted, a :" -"exc:`DeprecationWarning` is raised and the AST node will not have this " -"field. In Python 3.15, this condition will raise an error." -msgstr "" -"如果建構函式中省略了文法中可選的欄位，則它預設為 ``None``。如果省略串列欄位，" -"則預設為空串列。如果省略 :class:`!ast.expr_context` 型別的欄位，則預設為 :" -"class:`Load() `。如果省略任何其他欄位，則會引發 :exc:" -"`DeprecationWarning`，且 AST 節點將沒有此欄位。在 Python 3.15 中，這種情況會" -"引發錯誤。" - -#: ../../library/ast.rst:130 -msgid "Class :class:`ast.Constant` is now used for all constants." -msgstr ":class:`ast.Constant` 類別現在用於所有常數。" - -#: ../../library/ast.rst:134 -msgid "" -"Simple indices are represented by their value, extended slices are " -"represented as tuples." -msgstr "以它們的值表示簡單索引，擴充切片 (slice) 則以元組 (tuple) 表示。" - -#: ../../library/ast.rst:139 -msgid "" -"The :meth:`~object.__repr__` output of :class:`~ast.AST` nodes includes the " -"values of the node fields." -msgstr ":class:`~ast.AST` 節點的 :meth:`~object.__repr__` 輸出包含節點欄位的值。" - -#: ../../library/ast.rst:144 -msgid "" -"Previous versions of Python provided the AST classes :class:`!ast.Num`, :" -"class:`!ast.Str`, :class:`!ast.Bytes`, :class:`!ast.NameConstant` and :class:" -"`!ast.Ellipsis`, which were deprecated in Python 3.8. These classes were " -"removed in Python 3.14, and their functionality has been replaced with :" -"class:`ast.Constant`." -msgstr "" -"過去的 Python 版本提供了 AST 類別 :class:`!ast.Num`、:class:`!ast.Str`、:" -"class:`!ast.Bytes`、:class:`!ast.NameConstant` 和 :class:`!ast.Ellipsis`，這" -"些類別在 Python 3.8 中已被棄用。這些類別在 Python 3.14 中被移除，其功能已被 :" -"class:`ast.Constant` 取代。" - -#: ../../library/ast.rst:152 -msgid "" -"Old classes :class:`!ast.Index` and :class:`!ast.ExtSlice` are still " -"available, but they will be removed in future Python releases. In the " -"meantime, instantiating them will return an instance of a different class." -msgstr "" -"舊的類別 :class:`!ast.Index` 和 :class:`!ast.ExtSlice` 仍然可用，但它們將在未" -"來的 Python 版本中刪除。同時，實例化它們會回傳不同類別的實例。" - -#: ../../library/ast.rst:159 -msgid "" -"Previous versions of Python allowed the creation of AST nodes that were " -"missing required fields. Similarly, AST node constructors allowed arbitrary " -"keyword arguments that were set as attributes of the AST node, even if they " -"did not match any of the fields of the AST node. This behavior is deprecated " -"and will be removed in Python 3.15." -msgstr "" -"先前版本的 Python 允許建立缺少必填欄位的 AST 節點。同樣地，AST 節點建構函式允" -"許將任意關鍵字引數設為 AST 節點的屬性，即使它們與 AST 節點的任何欄位都不匹" -"配。此行為已被棄用，並將在 Python 3.15 中刪除。" - -#: ../../library/ast.rst:166 -msgid "" -"The descriptions of the specific node classes displayed here were initially " -"adapted from the fantastic `Green Tree Snakes `__ project and all its contributors." -msgstr "" -"這裡顯示的特定節點類別的描述最初是從出色的 `Green Tree Snakes `__ 專案和所有貢獻者那裡改編而來" -"的。" - -#: ../../library/ast.rst:175 -msgid "Root nodes" -msgstr "根節點" - -#: ../../library/ast.rst:179 -msgid "" -"A Python module, as with :ref:`file input `. Node type generated " -"by :func:`ast.parse` in the default ``\"exec\"`` *mode*." -msgstr "" -"一個 Python 模組，與\\ :ref:`檔案輸入 ` 一樣。由 :func:`ast." -"parse` 在預設的 ``\"exec\"`` *mode* 下生成的節點型別。" - -#: ../../library/ast.rst:182 -msgid "``body`` is a :class:`list` of the module's :ref:`ast-statements`." -msgstr "``body`` 是模組的\\ :ref:`ast-statements` 的一個 :class:`list`。" - -#: ../../library/ast.rst:184 -msgid "" -"``type_ignores`` is a :class:`list` of the module's type ignore comments; " -"see :func:`ast.parse` for more details." -msgstr "" -"``type_ignores`` 是模組的忽略型別註解的 :class:`list`；有關更多詳細資訊，請參" -"閱 :func:`ast.parse`。" - -#: ../../library/ast.rst:187 -msgid "" -">>> print(ast.dump(ast.parse('x = 1'), indent=4))\n" -"Module(\n" -" body=[\n" -" Assign(\n" -" targets=[\n" -" Name(id='x', ctx=Store())],\n" -" value=Constant(value=1))])" -msgstr "" -">>> print(ast.dump(ast.parse('x = 1'), indent=4))\n" -"Module(\n" -" body=[\n" -" Assign(\n" -" targets=[\n" -" Name(id='x', ctx=Store())],\n" -" value=Constant(value=1))])" - -#: ../../library/ast.rst:200 -msgid "" -"A single Python :ref:`expression input `. Node type " -"generated by :func:`ast.parse` when *mode* is ``\"eval\"``." -msgstr "" -"單個 Python :ref:`運算式輸入 `。當 *mode* 是 ``\"eval\"`` " -"時節點型別由 :func:`ast.parse` 生成。" - -#: ../../library/ast.rst:203 -msgid "" -"``body`` is a single node, one of the :ref:`expression types `." -msgstr "" -"``body`` 是單個節點，是\\ :ref:`運算式型別 `\\ 的其中之一。" - -#: ../../library/ast.rst:206 ../../library/ast.rst:276 -msgid "" -">>> print(ast.dump(ast.parse('123', mode='eval'), indent=4))\n" -"Expression(\n" -" body=Constant(value=123))" -msgstr "" -">>> print(ast.dump(ast.parse('123', mode='eval'), indent=4))\n" -"Expression(\n" -" body=Constant(value=123))" - -#: ../../library/ast.rst:215 -msgid "" -"A single :ref:`interactive input `, like in :ref:`tut-interac`. " -"Node type generated by :func:`ast.parse` when *mode* is ``\"single\"``." -msgstr "" -"單個\\ :ref:`互動式輸入 `，和\\ :ref:`tut-interac`\\ 中所述的相" -"似。當 *mode* 是 ``\"single\"`` 時節點型別由 :func:`ast.parse` 生成。" - -#: ../../library/ast.rst:218 -msgid "``body`` is a :class:`list` of :ref:`statement nodes `." -msgstr "" -"``body`` 是\\ :ref:`陳述式節點 (statement nodes) ` 的 :class:" -"`list`。" - -#: ../../library/ast.rst:220 -msgid "" -">>> print(ast.dump(ast.parse('x = 1; y = 2', mode='single'), indent=4))\n" -"Interactive(\n" -" body=[\n" -" Assign(\n" -" targets=[\n" -" Name(id='x', ctx=Store())],\n" -" value=Constant(value=1)),\n" -" Assign(\n" -" targets=[\n" -" Name(id='y', ctx=Store())],\n" -" value=Constant(value=2))])" -msgstr "" -">>> print(ast.dump(ast.parse('x = 1; y = 2', mode='single'), indent=4))\n" -"Interactive(\n" -" body=[\n" -" Assign(\n" -" targets=[\n" -" Name(id='x', ctx=Store())],\n" -" value=Constant(value=1)),\n" -" Assign(\n" -" targets=[\n" -" Name(id='y', ctx=Store())],\n" -" value=Constant(value=2))])" - -#: ../../library/ast.rst:237 -msgid "" -"A representation of an old-style type comments for functions, as Python " -"versions prior to 3.5 didn't support :pep:`484` annotations. Node type " -"generated by :func:`ast.parse` when *mode* is ``\"func_type\"``." -msgstr "" -"函式的舊式型別註解的表示法，因為 3.5 之前的 Python 版本不支援 :pep:`484` 註" -"釋。當 *mode* 是 ``\"func_type\"`` 時節點型別由 :func:`ast.parse` 生成。" - -#: ../../library/ast.rst:241 -msgid "Such type comments would look like this::" -msgstr "這種型別的註解看起來像這樣： ::" - -#: ../../library/ast.rst:243 -msgid "" -"def sum_two_number(a, b):\n" -" # type: (int, int) -> int\n" -" return a + b" -msgstr "" -"def sum_two_number(a, b):\n" -" # type: (int, int) -> int\n" -" return a + b" - -#: ../../library/ast.rst:247 -msgid "" -"``argtypes`` is a :class:`list` of :ref:`expression nodes `." -msgstr "" -"``argtypes`` 是\\ :ref:`運算式節點 `\\ 的 :class:`list`。" - -#: ../../library/ast.rst:249 -msgid "``returns`` is a single :ref:`expression node `." -msgstr "``returns`` 是單個\\ :ref:`運算式節點 `。" - -#: ../../library/ast.rst:251 -msgid "" -">>> print(ast.dump(ast.parse('(int, str) -> List[int]', mode='func_type'), " -"indent=4))\n" -"FunctionType(\n" -" argtypes=[\n" -" Name(id='int', ctx=Load()),\n" -" Name(id='str', ctx=Load())],\n" -" returns=Subscript(\n" -" value=Name(id='List', ctx=Load()),\n" -" slice=Name(id='int', ctx=Load()),\n" -" ctx=Load()))" -msgstr "" -">>> print(ast.dump(ast.parse('(int, str) -> List[int]', mode='func_type'), " -"indent=4))\n" -"FunctionType(\n" -" argtypes=[\n" -" Name(id='int', ctx=Load()),\n" -" Name(id='str', ctx=Load())],\n" -" returns=Subscript(\n" -" value=Name(id='List', ctx=Load()),\n" -" slice=Name(id='int', ctx=Load()),\n" -" ctx=Load()))" - -#: ../../library/ast.rst:267 -msgid "Literals" -msgstr "文本 (Literals)" - -#: ../../library/ast.rst:271 -msgid "" -"A constant value. The ``value`` attribute of the ``Constant`` literal " -"contains the Python object it represents. The values represented can be " -"instances of :class:`str`, :class:`bytes`, :class:`int`, :class:`float`, :" -"class:`complex`, and :class:`bool`, and the constants :data:`None` and :data:" -"`Ellipsis`." -msgstr "" -"一個常數值。``Constant`` 文本的 ``value`` 屬性包含它所代表的 Python 物件。表" -"示的值可以是 :class:`str`、:class:`bytes`、:class:`int`、:class:`float`、:" -"class:`complex` 和 :class:`bool` 的實例，以及常數 :data:`None` 和 :data:" -"`Ellipsis`。" - -#: ../../library/ast.rst:285 -msgid "" -"Node representing a single formatting field in an f-string. If the string " -"contains a single formatting field and nothing else the node can be isolated " -"otherwise it appears in :class:`JoinedStr`." -msgstr "" -"表示 f 字串 (f-string) 中的單個格式化欄位的節點。如果字串包含單個格式欄位並且" -"沒有其他內容，則可以隔離 (isolate) 該節點，否則它將出現在 :class:`JoinedStr` " -"中。" - -#: ../../library/ast.rst:289 -msgid "" -"``value`` is any expression node (such as a literal, a variable, or a " -"function call)." -msgstr "``value`` 為任何運算式節點（例如文字、變數或函式呼叫）。" - -#: ../../library/ast.rst:291 ../../library/ast.rst:373 -msgid "``conversion`` is an integer:" -msgstr "``conversion`` 是一個整數：" - -#: ../../library/ast.rst:293 -msgid "-1: no formatting" -msgstr "-1: 無格式化" - -#: ../../library/ast.rst:294 -msgid "97 (``ord('a')``): ``!a`` :func:`ASCII ` formatting" -msgstr "97 (``ord('a')``)：``！a`` :func:`ASCII ` 格式化" - -#: ../../library/ast.rst:295 -msgid "114 (``ord('r')``): ``!r`` :func:`repr` formatting" -msgstr "114 (``ord('r')``)：``!r`` :func:`repr` 格式化" - -#: ../../library/ast.rst:296 -msgid "115 (``ord('s')``): ``!s`` :func:`string ` formatting" -msgstr "115 (``ord('s')``)：``!s`` :func:`string ` 格式化" - -#: ../../library/ast.rst:298 -msgid "" -"``format_spec`` is a :class:`JoinedStr` node representing the formatting of " -"the value, or ``None`` if no format was specified. Both ``conversion`` and " -"``format_spec`` can be set at the same time." -msgstr "" -"``format_spec`` 是一個 :class:`JoinedStr` 節點，表示值的格式，若未指定格式則" -"為 ``None``。``conversion`` 和 ``format_spec`` 可以同時設定。" - -#: ../../library/ast.rst:305 -msgid "" -"An f-string, comprising a series of :class:`FormattedValue` and :class:" -"`Constant` nodes." -msgstr "" -"一個 f 字串，包含一系列 :class:`FormattedValue` 和 :class:`Constant` 節點。" - -#: ../../library/ast.rst:308 -msgid "" -">>> print(ast.dump(ast.parse('f\"sin({a}) is {sin(a):.3}\"', mode='eval'), " -"indent=4))\n" -"Expression(\n" -" body=JoinedStr(\n" -" values=[\n" -" Constant(value='sin('),\n" -" FormattedValue(\n" -" value=Name(id='a', ctx=Load()),\n" -" conversion=-1),\n" -" Constant(value=') is '),\n" -" FormattedValue(\n" -" value=Call(\n" -" func=Name(id='sin', ctx=Load()),\n" -" args=[\n" -" Name(id='a', ctx=Load())]),\n" -" conversion=-1,\n" -" format_spec=JoinedStr(\n" -" values=[\n" -" Constant(value='.3')]))]))" -msgstr "" -">>> print(ast.dump(ast.parse('f\"sin({a}) is {sin(a):.3}\"', mode='eval'), " -"indent=4))\n" -"Expression(\n" -" body=JoinedStr(\n" -" values=[\n" -" Constant(value='sin('),\n" -" FormattedValue(\n" -" value=Name(id='a', ctx=Load()),\n" -" conversion=-1),\n" -" Constant(value=') is '),\n" -" FormattedValue(\n" -" value=Call(\n" -" func=Name(id='sin', ctx=Load()),\n" -" args=[\n" -" Name(id='a', ctx=Load())]),\n" -" conversion=-1,\n" -" format_spec=JoinedStr(\n" -" values=[\n" -" Constant(value='.3')]))]))" - -#: ../../library/ast.rst:334 -msgid "" -"Node representing a template string literal, comprising a series of :class:" -"`Interpolation` and :class:`Constant` nodes. These nodes may be any order, " -"and do not need to be interleaved." -msgstr "" -"表示模板字串字面值的節點，由一系列 :class:`Interpolation` 和 :class:" -"`Constant` 節點組成。這些節點可以是任意順序，不需要交錯排列。" - -#: ../../library/ast.rst:338 -msgid "" -">>> expr = ast.parse('t\"{name} finished {place:ordinal}\"', mode='eval')\n" -">>> print(ast.dump(expr, indent=4))\n" -"Expression(\n" -" body=TemplateStr(\n" -" values=[\n" -" Interpolation(\n" -" value=Name(id='name', ctx=Load()),\n" -" str='name',\n" -" conversion=-1),\n" -" Constant(value=' finished '),\n" -" Interpolation(\n" -" value=Name(id='place', ctx=Load()),\n" -" str='place',\n" -" conversion=-1,\n" -" format_spec=JoinedStr(\n" -" values=[\n" -" Constant(value='ordinal')]))]))" -msgstr "" -">>> expr = ast.parse('t\"{name} finished {place:ordinal}\"', mode='eval')\n" -">>> print(ast.dump(expr, indent=4))\n" -"Expression(\n" -" body=TemplateStr(\n" -" values=[\n" -" Interpolation(\n" -" value=Name(id='name', ctx=Load()),\n" -" str='name',\n" -" conversion=-1),\n" -" Constant(value=' finished '),\n" -" Interpolation(\n" -" value=Name(id='place', ctx=Load()),\n" -" str='place',\n" -" conversion=-1,\n" -" format_spec=JoinedStr(\n" -" values=[\n" -" Constant(value='ordinal')]))]))" - -#: ../../library/ast.rst:362 -msgid "" -"Node representing a single interpolation field in a template string literal." -msgstr "表示模板字串字面值中單一插值欄位的節點。" - -#: ../../library/ast.rst:364 -msgid "" -"``value`` is any expression node (such as a literal, a variable, or a " -"function call). This has the same meaning as ``FormattedValue.value``." -msgstr "" -"``value`` 為任何運算式節點（例如文字、變數或函式呼叫）。這和 " -"``FormattedValue.value`` 的意思相同。" - -#: ../../library/ast.rst:367 -msgid "" -"``str`` is a constant containing the text of the interpolation expression." -msgstr "``str`` 是一個包含插值運算式文字的常數。" - -#: ../../library/ast.rst:369 -msgid "" -"If ``str`` is set to ``None``, then ``value`` is used to generate code when " -"calling :func:`ast.unparse`. This no longer guarantees that the generated " -"code is identical to the original and is intended for code generation." -msgstr "" -"如果 ``str`` 被設為 ``None``，則在呼叫 :func:`ast.unparse` 時會使用 " -"``value`` 來產生程式碼。這不再保證產生的程式碼與原始程式碼相同，且適用於程式碼" -"產生。" - -#: ../../library/ast.rst:375 -msgid "-1: no conversion" -msgstr "-1：無規範" - -#: ../../library/ast.rst:376 -msgid "97 (``ord('a')``): ``!a`` :func:`ASCII ` conversion" -msgstr "97 (``ord('a')``)：``!a`` :func:`ASCII ` 轉換" - -#: ../../library/ast.rst:377 -msgid "114 (``ord('r')``): ``!r`` :func:`repr` conversion" -msgstr "114 (``ord('r')``)：``!r`` :func:`repr` 轉換" - -#: ../../library/ast.rst:378 -msgid "115 (``ord('s')``): ``!s`` :func:`string ` conversion" -msgstr "115 (``ord('s')``)：``!s`` :func:`string ` 轉換" - -#: ../../library/ast.rst:380 -msgid "This has the same meaning as ``FormattedValue.conversion``." -msgstr "這與 ``FormattedValue.conversion`` 的意思相同。" - -#: ../../library/ast.rst:381 -msgid "" -"``format_spec`` is a :class:`JoinedStr` node representing the formatting of " -"the value, or ``None`` if no format was specified. Both ``conversion`` and " -"``format_spec`` can be set at the same time. This has the same meaning as " -"``FormattedValue.format_spec``." -msgstr "" -"``format_spec`` 是一個 :class:`JoinedStr` 節點，表示值的格式，若未指定格式則" -"為 ``None``。``conversion`` 和 ``format_spec`` 可以同時設定。這與 " -"``FormattedValue.format_spec`` 的意思相同。" - -#: ../../library/ast.rst:390 -msgid "" -"A list or tuple. ``elts`` holds a list of nodes representing the elements. " -"``ctx`` is :class:`Store` if the container is an assignment target (i.e. " -"``(x,y)=something``), and :class:`Load` otherwise." -msgstr "" -"串列或元組。``elts`` 保存表示元素的節點串列。如果容器是賦值目標（即 ``(x," -"y)=something`` ），則 ``ctx`` 是 :class:`Store`，否則是 :class:`Load`。" - -#: ../../library/ast.rst:394 -msgid "" -">>> print(ast.dump(ast.parse('[1, 2, 3]', mode='eval'), indent=4))\n" -"Expression(\n" -" body=List(\n" -" elts=[\n" -" Constant(value=1),\n" -" Constant(value=2),\n" -" Constant(value=3)],\n" -" ctx=Load()))\n" -">>> print(ast.dump(ast.parse('(1, 2, 3)', mode='eval'), indent=4))\n" -"Expression(\n" -" body=Tuple(\n" -" elts=[\n" -" Constant(value=1),\n" -" Constant(value=2),\n" -" Constant(value=3)],\n" -" ctx=Load()))" -msgstr "" -">>> print(ast.dump(ast.parse('[1, 2, 3]', mode='eval'), indent=4))\n" -"Expression(\n" -" body=List(\n" -" elts=[\n" -" Constant(value=1),\n" -" Constant(value=2),\n" -" Constant(value=3)],\n" -" ctx=Load()))\n" -">>> print(ast.dump(ast.parse('(1, 2, 3)', mode='eval'), indent=4))\n" -"Expression(\n" -" body=Tuple(\n" -" elts=[\n" -" Constant(value=1),\n" -" Constant(value=2),\n" -" Constant(value=3)],\n" -" ctx=Load()))" - -#: ../../library/ast.rst:416 -msgid "A set. ``elts`` holds a list of nodes representing the set's elements." -msgstr "一個集合。``elts`` 保存表示集合之元素的節點串列。" - -#: ../../library/ast.rst:418 -msgid "" -">>> print(ast.dump(ast.parse('{1, 2, 3}', mode='eval'), indent=4))\n" -"Expression(\n" -" body=Set(\n" -" elts=[\n" -" Constant(value=1),\n" -" Constant(value=2),\n" -" Constant(value=3)]))" -msgstr "" -">>> print(ast.dump(ast.parse('{1, 2, 3}', mode='eval'), indent=4))\n" -"Expression(\n" -" body=Set(\n" -" elts=[\n" -" Constant(value=1),\n" -" Constant(value=2),\n" -" Constant(value=3)]))" - -#: ../../library/ast.rst:431 -msgid "" -"A dictionary. ``keys`` and ``values`` hold lists of nodes representing the " -"keys and the values respectively, in matching order (what would be returned " -"when calling :code:`dictionary.keys()` and :code:`dictionary.values()`)." -msgstr "" -"一個字典 (dictionary)。``keys`` 和 ``values`` 分別按匹配順序保存表示鍵和值的" -"節點串列（為呼叫 :code:`dictionary.keys()` 和 :code:`dictionary.values()` 時" -"將回傳的內容）。" - -#: ../../library/ast.rst:435 -msgid "" -"When doing dictionary unpacking using dictionary literals the expression to " -"be expanded goes in the ``values`` list, with a ``None`` at the " -"corresponding position in ``keys``." -msgstr "" -"當使用字典文本進行字典解包 (unpack) 時，要擴充的運算式位於 ``values`` 串列" -"中，在 ``keys`` 中的相應位置有一個 ``None``。" - -#: ../../library/ast.rst:439 -msgid "" -">>> print(ast.dump(ast.parse('{\"a\":1, **d}', mode='eval'), indent=4))\n" -"Expression(\n" -" body=Dict(\n" -" keys=[\n" -" Constant(value='a'),\n" -" None],\n" -" values=[\n" -" Constant(value=1),\n" -" Name(id='d', ctx=Load())]))" -msgstr "" -">>> print(ast.dump(ast.parse('{\"a\":1, **d}', mode='eval'), indent=4))\n" -"Expression(\n" -" body=Dict(\n" -" keys=[\n" -" Constant(value='a'),\n" -" None],\n" -" values=[\n" -" Constant(value=1),\n" -" Name(id='d', ctx=Load())]))" - -#: ../../library/ast.rst:453 -msgid "Variables" -msgstr "變數" - -#: ../../library/ast.rst:457 -msgid "" -"A variable name. ``id`` holds the name as a string, and ``ctx`` is one of " -"the following types." -msgstr "一個變數名稱。``id`` 將名稱以字串形式保存，且 ``ctx`` 是以下型別之一。" - -#: ../../library/ast.rst:465 -msgid "" -"Variable references can be used to load the value of a variable, to assign a " -"new value to it, or to delete it. Variable references are given a context to " -"distinguish these cases." -msgstr "" -"變數參照可用於載入變數的值、為其分配新值或刪除它。變數參照被賦予情境 " -"(context) 來區分這些情況。" - -#: ../../library/ast.rst:469 -msgid "" -">>> print(ast.dump(ast.parse('a'), indent=4))\n" -"Module(\n" -" body=[\n" -" Expr(\n" -" value=Name(id='a', ctx=Load()))])\n" -"\n" -">>> print(ast.dump(ast.parse('a = 1'), indent=4))\n" -"Module(\n" -" body=[\n" -" Assign(\n" -" targets=[\n" -" Name(id='a', ctx=Store())],\n" -" value=Constant(value=1))])\n" -"\n" -">>> print(ast.dump(ast.parse('del a'), indent=4))\n" -"Module(\n" -" body=[\n" -" Delete(\n" -" targets=[\n" -" Name(id='a', ctx=Del())])])" -msgstr "" -">>> print(ast.dump(ast.parse('a'), indent=4))\n" -"Module(\n" -" body=[\n" -" Expr(\n" -" value=Name(id='a', ctx=Load()))])\n" -"\n" -">>> print(ast.dump(ast.parse('a = 1'), indent=4))\n" -"Module(\n" -" body=[\n" -" Assign(\n" -" targets=[\n" -" Name(id='a', ctx=Store())],\n" -" value=Constant(value=1))])\n" -"\n" -">>> print(ast.dump(ast.parse('del a'), indent=4))\n" -"Module(\n" -" body=[\n" -" Delete(\n" -" targets=[\n" -" Name(id='a', ctx=Del())])])" - -#: ../../library/ast.rst:495 -msgid "" -"A ``*var`` variable reference. ``value`` holds the variable, typically a :" -"class:`Name` node. This type must be used when building a :class:`Call` node " -"with ``*args``." -msgstr "" -"一個 ``*var`` 變數參照。``value`` 保存變數，通常是一個 :class:`Name` 節點。在" -"使用 ``*args`` 建置 :class:`Call` 節點時必須使用此型別。" - -#: ../../library/ast.rst:499 -msgid "" -">>> print(ast.dump(ast.parse('a, *b = it'), indent=4))\n" -"Module(\n" -" body=[\n" -" Assign(\n" -" targets=[\n" -" Tuple(\n" -" elts=[\n" -" Name(id='a', ctx=Store()),\n" -" Starred(\n" -" value=Name(id='b', ctx=Store()),\n" -" ctx=Store())],\n" -" ctx=Store())],\n" -" value=Name(id='it', ctx=Load()))])" -msgstr "" -">>> print(ast.dump(ast.parse('a, *b = it'), indent=4))\n" -"Module(\n" -" body=[\n" -" Assign(\n" -" targets=[\n" -" Tuple(\n" -" elts=[\n" -" Name(id='a', ctx=Store()),\n" -" Starred(\n" -" value=Name(id='b', ctx=Store()),\n" -" ctx=Store())],\n" -" ctx=Store())],\n" -" value=Name(id='it', ctx=Load()))])" - -#: ../../library/ast.rst:519 -msgid "Expressions" -msgstr "運算式" - -#: ../../library/ast.rst:523 -msgid "" -"When an expression, such as a function call, appears as a statement by " -"itself with its return value not used or stored, it is wrapped in this " -"container. ``value`` holds one of the other nodes in this section, a :class:" -"`Constant`, a :class:`Name`, a :class:`Lambda`, a :class:`Yield` or :class:" -"`YieldFrom` node." -msgstr "" -"當運算式（例如函式呼叫）本身作為陳述式出現且未使用或儲存其回傳值時，它將被包" -"裝在此容器中。``value`` 保存此區段 (section) 中的一個其他節點：:class:" -"`Constant`、:class:`Name`、:class:`Lambda`、:class:`Yield` 或 :class:" -"`YieldFrom`" - -#: ../../library/ast.rst:528 -msgid "" -">>> print(ast.dump(ast.parse('-a'), indent=4))\n" -"Module(\n" -" body=[\n" -" Expr(\n" -" value=UnaryOp(\n" -" op=USub(),\n" -" operand=Name(id='a', ctx=Load())))])" -msgstr "" -">>> print(ast.dump(ast.parse('-a'), indent=4))\n" -"Module(\n" -" body=[\n" -" Expr(\n" -" value=UnaryOp(\n" -" op=USub(),\n" -" operand=Name(id='a', ctx=Load())))])" - -#: ../../library/ast.rst:541 -msgid "" -"A unary operation. ``op`` is the operator, and ``operand`` any expression " -"node." -msgstr "" -"一元運算 (unary operation)。``op`` 是運算子，``operand`` 是任何運算式節點。" - -#: ../../library/ast.rst:550 -msgid "" -"Unary operator tokens. :class:`Not` is the ``not`` keyword, :class:`Invert` " -"is the ``~`` operator." -msgstr "" -"一元運算子標記。 :class:`Not` 是 ``not`` 關鍵字、:class:`Invert` 是 ``~`` 運" -"算子。" - -#: ../../library/ast.rst:553 -msgid "" -">>> print(ast.dump(ast.parse('not x', mode='eval'), indent=4))\n" -"Expression(\n" -" body=UnaryOp(\n" -" op=Not(),\n" -" operand=Name(id='x', ctx=Load())))" -msgstr "" -">>> print(ast.dump(ast.parse('not x', mode='eval'), indent=4))\n" -"Expression(\n" -" body=UnaryOp(\n" -" op=Not(),\n" -" operand=Name(id='x', ctx=Load())))" - -#: ../../library/ast.rst:564 -msgid "" -"A binary operation (like addition or division). ``op`` is the operator, and " -"``left`` and ``right`` are any expression nodes." -msgstr "" -"二元運算 (binary operation)（如加法或除法）。 ``op`` 是運算子、``left`` 和 " -"``right`` 是任意運算式節點。" - -#: ../../library/ast.rst:567 -msgid "" -">>> print(ast.dump(ast.parse('x + y', mode='eval'), indent=4))\n" -"Expression(\n" -" body=BinOp(\n" -" left=Name(id='x', ctx=Load()),\n" -" op=Add(),\n" -" right=Name(id='y', ctx=Load())))" -msgstr "" -">>> print(ast.dump(ast.parse('x + y', mode='eval'), indent=4))\n" -"Expression(\n" -" body=BinOp(\n" -" left=Name(id='x', ctx=Load()),\n" -" op=Add(),\n" -" right=Name(id='y', ctx=Load())))" - -#: ../../library/ast.rst:591 -msgid "Binary operator tokens." -msgstr "二元運算子 token。" - -#: ../../library/ast.rst:596 -msgid "" -"A boolean operation, 'or' or 'and'. ``op`` is :class:`Or` or :class:`And`. " -"``values`` are the values involved. Consecutive operations with the same " -"operator, such as ``a or b or c``, are collapsed into one node with several " -"values." -msgstr "" -"布林運算 'or' 或 'and'。``op`` 是 :class:`Or` 或 :class:`And`。``values`` 是" -"有所涉及的值。使用同一運算子的連續操作（例如 ``a or b or c``）會被折疊為具有" -"多個值的一個節點。" - -#: ../../library/ast.rst:601 -msgid "This doesn't include ``not``, which is a :class:`UnaryOp`." -msgstr "這不包括 ``not``，它是一個 :class:`UnaryOp`。" - -#: ../../library/ast.rst:603 -msgid "" -">>> print(ast.dump(ast.parse('x or y', mode='eval'), indent=4))\n" -"Expression(\n" -" body=BoolOp(\n" -" op=Or(),\n" -" values=[\n" -" Name(id='x', ctx=Load()),\n" -" Name(id='y', ctx=Load())]))" -msgstr "" -">>> print(ast.dump(ast.parse('x or y', mode='eval'), indent=4))\n" -"Expression(\n" -" body=BoolOp(\n" -" op=Or(),\n" -" values=[\n" -" Name(id='x', ctx=Load()),\n" -" Name(id='y', ctx=Load())]))" - -#: ../../library/ast.rst:617 -msgid "Boolean operator tokens." -msgstr "布林運算子 token。" - -#: ../../library/ast.rst:622 -msgid "" -"A comparison of two or more values. ``left`` is the first value in the " -"comparison, ``ops`` the list of operators, and ``comparators`` the list of " -"values after the first element in the comparison." -msgstr "" -"兩個或多個值的比較。``left`` 是比較中的第一個值、``ops`` 是運算子串列、" -"``comparators`` 是要比較的第一個元素之後值的串列。" - -#: ../../library/ast.rst:626 -msgid "" -">>> print(ast.dump(ast.parse('1 <= a < 10', mode='eval'), indent=4))\n" -"Expression(\n" -" body=Compare(\n" -" left=Constant(value=1),\n" -" ops=[\n" -" LtE(),\n" -" Lt()],\n" -" comparators=[\n" -" Name(id='a', ctx=Load()),\n" -" Constant(value=10)]))" -msgstr "" -">>> print(ast.dump(ast.parse('1 <= a < 10', mode='eval'), indent=4))\n" -"Expression(\n" -" body=Compare(\n" -" left=Constant(value=1),\n" -" ops=[\n" -" LtE(),\n" -" Lt()],\n" -" comparators=[\n" -" Name(id='a', ctx=Load()),\n" -" Constant(value=10)]))" - -#: ../../library/ast.rst:651 -msgid "Comparison operator tokens." -msgstr "比較運算子 token。" - -#: ../../library/ast.rst:656 -msgid "" -"A function call. ``func`` is the function, which will often be a :class:" -"`Name` or :class:`Attribute` object. Of the arguments:" -msgstr "" -"一個函式呼叫。``func`` 是該函式，通常是一個 :class:`Name` 或 :class:" -"`Attribute` 物件。而在引數中：" - -#: ../../library/ast.rst:659 -msgid "``args`` holds a list of the arguments passed by position." -msgstr "``args`` 保存按位置傳遞的引數串列。" - -#: ../../library/ast.rst:660 -msgid "" -"``keywords`` holds a list of :class:`.keyword` objects representing " -"arguments passed by keyword." -msgstr "" -"``keywords`` 保存一個 :class:`.keyword` 物件串列，表示透過關鍵字傳遞的引數。" - -#: ../../library/ast.rst:663 -msgid "" -"The ``args`` and ``keywords`` arguments are optional and default to empty " -"lists." -msgstr "``args`` 和 ``keywords`` 引數是可選的，預設為空串列。" - -#: ../../library/ast.rst:665 -msgid "" -">>> print(ast.dump(ast.parse('func(a, b=c, *d, **e)', mode='eval'), " -"indent=4))\n" -"Expression(\n" -" body=Call(\n" -" func=Name(id='func', ctx=Load()),\n" -" args=[\n" -" Name(id='a', ctx=Load()),\n" -" Starred(\n" -" value=Name(id='d', ctx=Load()),\n" -" ctx=Load())],\n" -" keywords=[\n" -" keyword(\n" -" arg='b',\n" -" value=Name(id='c', ctx=Load())),\n" -" keyword(\n" -" value=Name(id='e', ctx=Load()))]))" -msgstr "" -">>> print(ast.dump(ast.parse('func(a, b=c, *d, **e)', mode='eval'), " -"indent=4))\n" -"Expression(\n" -" body=Call(\n" -" func=Name(id='func', ctx=Load()),\n" -" args=[\n" -" Name(id='a', ctx=Load()),\n" -" Starred(\n" -" value=Name(id='d', ctx=Load()),\n" -" ctx=Load())],\n" -" keywords=[\n" -" keyword(\n" -" arg='b',\n" -" value=Name(id='c', ctx=Load())),\n" -" keyword(\n" -" value=Name(id='e', ctx=Load()))]))" - -#: ../../library/ast.rst:686 -msgid "" -"A keyword argument to a function call or class definition. ``arg`` is a raw " -"string of the parameter name, ``value`` is a node to pass in." -msgstr "" -"函式呼叫或類別定義的關鍵字引數。``arg`` 是參數名稱的原始字串，``value`` 是要" -"傳入的節點。" - -#: ../../library/ast.rst:692 -msgid "" -"An expression such as ``a if b else c``. Each field holds a single node, so " -"in the following example, all three are :class:`Name` nodes." -msgstr "" -"像是 ``a if b else c`` 之類的運算式。每個欄位都保存一個節點，因此在以下範例" -"中，所有三個都是 :class:`Name` 節點。" - -#: ../../library/ast.rst:695 -msgid "" -">>> print(ast.dump(ast.parse('a if b else c', mode='eval'), indent=4))\n" -"Expression(\n" -" body=IfExp(\n" -" test=Name(id='b', ctx=Load()),\n" -" body=Name(id='a', ctx=Load()),\n" -" orelse=Name(id='c', ctx=Load())))" -msgstr "" -">>> print(ast.dump(ast.parse('a if b else c', mode='eval'), indent=4))\n" -"Expression(\n" -" body=IfExp(\n" -" test=Name(id='b', ctx=Load()),\n" -" body=Name(id='a', ctx=Load()),\n" -" orelse=Name(id='c', ctx=Load())))" - -#: ../../library/ast.rst:707 -msgid "" -"Attribute access, e.g. ``d.keys``. ``value`` is a node, typically a :class:" -"`Name`. ``attr`` is a bare string giving the name of the attribute, and " -"``ctx`` is :class:`Load`, :class:`Store` or :class:`Del` according to how " -"the attribute is acted on." -msgstr "" -"屬性的存取，例如 ``d.keys``。``value`` 是一個節點，通常是一個 :class:`Name`。" -"``attr`` 是一個屬性名稱的字串，``ctx`` 根據屬性的作用方式可能是 :class:" -"`Load`、:class:`Store` 或 :class:`Del`。" - -#: ../../library/ast.rst:712 -msgid "" -">>> print(ast.dump(ast.parse('snake.colour', mode='eval'), indent=4))\n" -"Expression(\n" -" body=Attribute(\n" -" value=Name(id='snake', ctx=Load()),\n" -" attr='colour',\n" -" ctx=Load()))" -msgstr "" -">>> print(ast.dump(ast.parse('snake.colour', mode='eval'), indent=4))\n" -"Expression(\n" -" body=Attribute(\n" -" value=Name(id='snake', ctx=Load()),\n" -" attr='colour',\n" -" ctx=Load()))" - -#: ../../library/ast.rst:724 -msgid "" -"A named expression. This AST node is produced by the assignment expressions " -"operator (also known as the walrus operator). As opposed to the :class:" -"`Assign` node in which the first argument can be multiple nodes, in this " -"case both ``target`` and ``value`` must be single nodes." -msgstr "" -"一個附名運算式 (named expression)。該 AST 節點由賦值運算式運算子（也稱為海象" -"運算子）產生。相對於 :class:`Assign` 節點之第一個引數可為多個節點，在這種情況" -"下 ``target`` 和 ``value`` 都必須是單個節點。" - -#: ../../library/ast.rst:729 -msgid "" -">>> print(ast.dump(ast.parse('(x := 4)', mode='eval'), indent=4))\n" -"Expression(\n" -" body=NamedExpr(\n" -" target=Name(id='x', ctx=Store()),\n" -" value=Constant(value=4)))" -msgstr "" -">>> print(ast.dump(ast.parse('(x := 4)', mode='eval'), indent=4))\n" -"Expression(\n" -" body=NamedExpr(\n" -" target=Name(id='x', ctx=Store()),\n" -" value=Constant(value=4)))" - -#: ../../library/ast.rst:740 -msgid "Subscripting" -msgstr "下標 (Subscripting)" - -#: ../../library/ast.rst:744 -msgid "" -"A subscript, such as ``l[1]``. ``value`` is the subscripted object (usually " -"sequence or mapping). ``slice`` is an index, slice or key. It can be a :" -"class:`Tuple` and contain a :class:`Slice`. ``ctx`` is :class:`Load`, :class:" -"`Store` or :class:`Del` according to the action performed with the subscript." -msgstr "" -"一個下標，例如 ``l[1]``。``value`` 是下標物件（通常是序列或對映）。``slice`` " -"是索引、切片或鍵。它可以是一個 :class:`Tuple` 並包含一個 :class:`Slice`。根據" -"下標執行的操作不同，``ctx`` 可以是 :class:`Load`、:class:`Store` 或 :class:" -"`Del`。" - -#: ../../library/ast.rst:750 -msgid "" -">>> print(ast.dump(ast.parse('l[1:2, 3]', mode='eval'), indent=4))\n" -"Expression(\n" -" body=Subscript(\n" -" value=Name(id='l', ctx=Load()),\n" -" slice=Tuple(\n" -" elts=[\n" -" Slice(\n" -" lower=Constant(value=1),\n" -" upper=Constant(value=2)),\n" -" Constant(value=3)],\n" -" ctx=Load()),\n" -" ctx=Load()))" -msgstr "" -">>> print(ast.dump(ast.parse('l[1:2, 3]', mode='eval'), indent=4))\n" -"Expression(\n" -" body=Subscript(\n" -" value=Name(id='l', ctx=Load()),\n" -" slice=Tuple(\n" -" elts=[\n" -" Slice(\n" -" lower=Constant(value=1),\n" -" upper=Constant(value=2)),\n" -" Constant(value=3)],\n" -" ctx=Load()),\n" -" ctx=Load()))" - -#: ../../library/ast.rst:768 -msgid "" -"Regular slicing (on the form ``lower:upper`` or ``lower:upper:step``). Can " -"occur only inside the *slice* field of :class:`Subscript`, either directly " -"or as an element of :class:`Tuple`." -msgstr "" -"常規切片（形式為 ``lower:upper`` 或 ``lower:upper:step``）。只能直接或者或者" -"作為 :class:`Tuple` 的元素出現在 :class:`Subscript` 的 *slice* 欄位內。" - -#: ../../library/ast.rst:772 -msgid "" -">>> print(ast.dump(ast.parse('l[1:2]', mode='eval'), indent=4))\n" -"Expression(\n" -" body=Subscript(\n" -" value=Name(id='l', ctx=Load()),\n" -" slice=Slice(\n" -" lower=Constant(value=1),\n" -" upper=Constant(value=2)),\n" -" ctx=Load()))" -msgstr "" -">>> print(ast.dump(ast.parse('l[1:2]', mode='eval'), indent=4))\n" -"Expression(\n" -" body=Subscript(\n" -" value=Name(id='l', ctx=Load()),\n" -" slice=Slice(\n" -" lower=Constant(value=1),\n" -" upper=Constant(value=2)),\n" -" ctx=Load()))" - -#: ../../library/ast.rst:785 -msgid "Comprehensions" -msgstr "綜合運算式 (comprehensions)" - -#: ../../library/ast.rst:792 -msgid "" -"List and set comprehensions, generator expressions, and dictionary " -"comprehensions. ``elt`` (or ``key`` and ``value``) is a single node " -"representing the part that will be evaluated for each item." -msgstr "" -"串列和集合綜合運算、生成器運算式和字典綜合運算。``elt``\\ （或 ``key`` 和 " -"``value``）是單個節點，表示各個項目會被求值 (evaluate) 的部分。" - -#: ../../library/ast.rst:796 -msgid "``generators`` is a list of :class:`comprehension` nodes." -msgstr "``generators`` 是一個 :class:`comprehension` 節點的串列。" - -#: ../../library/ast.rst:798 -msgid "" -">>> print(ast.dump(\n" -"... ast.parse('[x for x in numbers]', mode='eval'),\n" -"... indent=4,\n" -"... ))\n" -"Expression(\n" -" body=ListComp(\n" -" elt=Name(id='x', ctx=Load()),\n" -" generators=[\n" -" comprehension(\n" -" target=Name(id='x', ctx=Store()),\n" -" iter=Name(id='numbers', ctx=Load()),\n" -" is_async=0)]))\n" -">>> print(ast.dump(\n" -"... ast.parse('{x: x**2 for x in numbers}', mode='eval'),\n" -"... indent=4,\n" -"... ))\n" -"Expression(\n" -" body=DictComp(\n" -" key=Name(id='x', ctx=Load()),\n" -" value=BinOp(\n" -" left=Name(id='x', ctx=Load()),\n" -" op=Pow(),\n" -" right=Constant(value=2)),\n" -" generators=[\n" -" comprehension(\n" -" target=Name(id='x', ctx=Store()),\n" -" iter=Name(id='numbers', ctx=Load()),\n" -" is_async=0)]))\n" -">>> print(ast.dump(\n" -"... ast.parse('{x for x in numbers}', mode='eval'),\n" -"... indent=4,\n" -"... ))\n" -"Expression(\n" -" body=SetComp(\n" -" elt=Name(id='x', ctx=Load()),\n" -" generators=[\n" -" comprehension(\n" -" target=Name(id='x', ctx=Store()),\n" -" iter=Name(id='numbers', ctx=Load()),\n" -" is_async=0)]))" -msgstr "" -">>> print(ast.dump(\n" -"... ast.parse('[x for x in numbers]', mode='eval'),\n" -"... indent=4,\n" -"... ))\n" -"Expression(\n" -" body=ListComp(\n" -" elt=Name(id='x', ctx=Load()),\n" -" generators=[\n" -" comprehension(\n" -" target=Name(id='x', ctx=Store()),\n" -" iter=Name(id='numbers', ctx=Load()),\n" -" is_async=0)]))\n" -">>> print(ast.dump(\n" -"... ast.parse('{x: x**2 for x in numbers}', mode='eval'),\n" -"... indent=4,\n" -"... ))\n" -"Expression(\n" -" body=DictComp(\n" -" key=Name(id='x', ctx=Load()),\n" -" value=BinOp(\n" -" left=Name(id='x', ctx=Load()),\n" -" op=Pow(),\n" -" right=Constant(value=2)),\n" -" generators=[\n" -" comprehension(\n" -" target=Name(id='x', ctx=Store()),\n" -" iter=Name(id='numbers', ctx=Load()),\n" -" is_async=0)]))\n" -">>> print(ast.dump(\n" -"... ast.parse('{x for x in numbers}', mode='eval'),\n" -"... indent=4,\n" -"... ))\n" -"Expression(\n" -" body=SetComp(\n" -" elt=Name(id='x', ctx=Load()),\n" -" generators=[\n" -" comprehension(\n" -" target=Name(id='x', ctx=Store()),\n" -" iter=Name(id='numbers', ctx=Load()),\n" -" is_async=0)]))" - -#: ../../library/ast.rst:844 -msgid "" -"One ``for`` clause in a comprehension. ``target`` is the reference to use " -"for each element - typically a :class:`Name` or :class:`Tuple` node. " -"``iter`` is the object to iterate over. ``ifs`` is a list of test " -"expressions: each ``for`` clause can have multiple ``ifs``." -msgstr "" -"綜合運算中的一個 ``for`` 子句。``target`` 是用於每個元素的參照 - 通常是 :" -"class:`Name` 或 :class:`Tuple` 節點。``iter`` 是要疊代的物件。``ifs`` 是測試" -"運算式的串列：每個 ``for`` 子句可以有多個 ``ifs``。" - -#: ../../library/ast.rst:849 -msgid "" -"``is_async`` indicates a comprehension is asynchronous (using an ``async " -"for`` instead of ``for``). The value is an integer (0 or 1)." -msgstr "" -"``is_async`` 表示綜合運算式是非同步的（使用 ``async for`` 而不是 ``for`` ）。" -"該值為整數（0 或 1）。" - -#: ../../library/ast.rst:852 -msgid "" -">>> print(ast.dump(ast.parse('[ord(c) for line in file for c in line]', " -"mode='eval'),\n" -"... indent=4)) # Multiple comprehensions in one.\n" -"Expression(\n" -" body=ListComp(\n" -" elt=Call(\n" -" func=Name(id='ord', ctx=Load()),\n" -" args=[\n" -" Name(id='c', ctx=Load())]),\n" -" generators=[\n" -" comprehension(\n" -" target=Name(id='line', ctx=Store()),\n" -" iter=Name(id='file', ctx=Load()),\n" -" is_async=0),\n" -" comprehension(\n" -" target=Name(id='c', ctx=Store()),\n" -" iter=Name(id='line', ctx=Load()),\n" -" is_async=0)]))\n" -"\n" -">>> print(ast.dump(ast.parse('(n**2 for n in it if n>5 if n<10)', " -"mode='eval'),\n" -"... indent=4)) # generator comprehension\n" -"Expression(\n" -" body=GeneratorExp(\n" -" elt=BinOp(\n" -" left=Name(id='n', ctx=Load()),\n" -" op=Pow(),\n" -" right=Constant(value=2)),\n" -" generators=[\n" -" comprehension(\n" -" target=Name(id='n', ctx=Store()),\n" -" iter=Name(id='it', ctx=Load()),\n" -" ifs=[\n" -" Compare(\n" -" left=Name(id='n', ctx=Load()),\n" -" ops=[\n" -" Gt()],\n" -" comparators=[\n" -" Constant(value=5)]),\n" -" Compare(\n" -" left=Name(id='n', ctx=Load()),\n" -" ops=[\n" -" Lt()],\n" -" comparators=[\n" -" Constant(value=10)])],\n" -" is_async=0)]))\n" -"\n" -">>> print(ast.dump(ast.parse('[i async for i in soc]', mode='eval'),\n" -"... indent=4)) # Async comprehension\n" -"Expression(\n" -" body=ListComp(\n" -" elt=Name(id='i', ctx=Load()),\n" -" generators=[\n" -" comprehension(\n" -" target=Name(id='i', ctx=Store()),\n" -" iter=Name(id='soc', ctx=Load()),\n" -" is_async=1)]))" -msgstr "" -">>> print(ast.dump(ast.parse('[ord(c) for line in file for c in line]', " -"mode='eval'),\n" -"... indent=4)) # Multiple comprehensions in one.\n" -"Expression(\n" -" body=ListComp(\n" -" elt=Call(\n" -" func=Name(id='ord', ctx=Load()),\n" -" args=[\n" -" Name(id='c', ctx=Load())]),\n" -" generators=[\n" -" comprehension(\n" -" target=Name(id='line', ctx=Store()),\n" -" iter=Name(id='file', ctx=Load()),\n" -" is_async=0),\n" -" comprehension(\n" -" target=Name(id='c', ctx=Store()),\n" -" iter=Name(id='line', ctx=Load()),\n" -" is_async=0)]))\n" -"\n" -">>> print(ast.dump(ast.parse('(n**2 for n in it if n>5 if n<10)', " -"mode='eval'),\n" -"... indent=4)) # generator comprehension\n" -"Expression(\n" -" body=GeneratorExp(\n" -" elt=BinOp(\n" -" left=Name(id='n', ctx=Load()),\n" -" op=Pow(),\n" -" right=Constant(value=2)),\n" -" generators=[\n" -" comprehension(\n" -" target=Name(id='n', ctx=Store()),\n" -" iter=Name(id='it', ctx=Load()),\n" -" ifs=[\n" -" Compare(\n" -" left=Name(id='n', ctx=Load()),\n" -" ops=[\n" -" Gt()],\n" -" comparators=[\n" -" Constant(value=5)]),\n" -" Compare(\n" -" left=Name(id='n', ctx=Load()),\n" -" ops=[\n" -" Lt()],\n" -" comparators=[\n" -" Constant(value=10)])],\n" -" is_async=0)]))\n" -"\n" -">>> print(ast.dump(ast.parse('[i async for i in soc]', mode='eval'),\n" -"... indent=4)) # Async comprehension\n" -"Expression(\n" -" body=ListComp(\n" -" elt=Name(id='i', ctx=Load()),\n" -" generators=[\n" -" comprehension(\n" -" target=Name(id='i', ctx=Store()),\n" -" iter=Name(id='soc', ctx=Load()),\n" -" is_async=1)]))" - -#: ../../library/ast.rst:914 -msgid "Statements" -msgstr "陳述式" - -#: ../../library/ast.rst:918 -msgid "" -"An assignment. ``targets`` is a list of nodes, and ``value`` is a single " -"node." -msgstr "一個賦值。``targets`` 是節點串列，``value`` 是單個節點。" - -#: ../../library/ast.rst:920 -msgid "" -"Multiple nodes in ``targets`` represents assigning the same value to each. " -"Unpacking is represented by putting a :class:`Tuple` or :class:`List` within " -"``targets``." -msgstr "" -"``targets`` 中的多個節點表示為每個節點分配相同的值。解包是透過在 ``targets`` " -"中放置一個 :class:`Tuple` 或 :class:`List` 來表示的。" - -#: ../../library/ast.rst:926 ../../library/ast.rst:1221 -#: ../../library/ast.rst:1415 ../../library/ast.rst:1981 -msgid "" -"``type_comment`` is an optional string with the type annotation as a comment." -msgstr "``type_comment`` 是一個可選字串，其中的註解為型別註釋。" - -#: ../../library/ast.rst:928 -msgid "" -">>> print(ast.dump(ast.parse('a = b = 1'), indent=4)) # Multiple assignment\n" -"Module(\n" -" body=[\n" -" Assign(\n" -" targets=[\n" -" Name(id='a', ctx=Store()),\n" -" Name(id='b', ctx=Store())],\n" -" value=Constant(value=1))])\n" -"\n" -">>> print(ast.dump(ast.parse('a,b = c'), indent=4)) # Unpacking\n" -"Module(\n" -" body=[\n" -" Assign(\n" -" targets=[\n" -" Tuple(\n" -" elts=[\n" -" Name(id='a', ctx=Store()),\n" -" Name(id='b', ctx=Store())],\n" -" ctx=Store())],\n" -" value=Name(id='c', ctx=Load()))])" -msgstr "" -">>> print(ast.dump(ast.parse('a = b = 1'), indent=4)) # Multiple assignment\n" -"Module(\n" -" body=[\n" -" Assign(\n" -" targets=[\n" -" Name(id='a', ctx=Store()),\n" -" Name(id='b', ctx=Store())],\n" -" value=Constant(value=1))])\n" -"\n" -">>> print(ast.dump(ast.parse('a,b = c'), indent=4)) # Unpacking\n" -"Module(\n" -" body=[\n" -" Assign(\n" -" targets=[\n" -" Tuple(\n" -" elts=[\n" -" Name(id='a', ctx=Store()),\n" -" Name(id='b', ctx=Store())],\n" -" ctx=Store())],\n" -" value=Name(id='c', ctx=Load()))])" - -#: ../../library/ast.rst:954 -msgid "" -"An assignment with a type annotation. ``target`` is a single node and can be " -"a :class:`Name`, an :class:`Attribute` or a :class:`Subscript`. " -"``annotation`` is the annotation, such as a :class:`Constant` or :class:" -"`Name` node. ``value`` is a single optional node." -msgstr "" -"帶有型別註釋的賦值。``target`` 是單個節點，可以是 :class:`Name`、:class:" -"`Attribute` 或 :class:`Subscript`。``annotation`` 是註釋，例如 :class:" -"`Constant` 或 :class:`Name` 節點。``value`` 是單個可選節點。" - -#: ../../library/ast.rst:959 -msgid "" -"``simple`` is always either 0 (indicating a \"complex\" target) or 1 " -"(indicating a \"simple\" target). A \"simple\" target consists solely of a :" -"class:`Name` node that does not appear between parentheses; all other " -"targets are considered complex. Only simple targets appear in the :attr:" -"`~object.__annotations__` dictionary of modules and classes." -msgstr "" -"``simple`` 總會是 0（表示一個「複雜」目標）或 1（表示一個「簡單」目標）。一個" -"「簡單」目標僅包含一個 :class:`Name` 節點，且不出現在括號之間；所有其他目標都" -"被視為是複雜的。只有簡單目標會出現在模組和類別的 :attr:`~object." -"__annotations__` 字典中。" - -#: ../../library/ast.rst:965 -msgid "" -">>> print(ast.dump(ast.parse('c: int'), indent=4))\n" -"Module(\n" -" body=[\n" -" AnnAssign(\n" -" target=Name(id='c', ctx=Store()),\n" -" annotation=Name(id='int', ctx=Load()),\n" -" simple=1)])\n" -"\n" -">>> print(ast.dump(ast.parse('(a): int = 1'), indent=4)) # Annotation with " -"parenthesis\n" -"Module(\n" -" body=[\n" -" AnnAssign(\n" -" target=Name(id='a', ctx=Store()),\n" -" annotation=Name(id='int', ctx=Load()),\n" -" value=Constant(value=1),\n" -" simple=0)])\n" -"\n" -">>> print(ast.dump(ast.parse('a.b: int'), indent=4)) # Attribute annotation\n" -"Module(\n" -" body=[\n" -" AnnAssign(\n" -" target=Attribute(\n" -" value=Name(id='a', ctx=Load()),\n" -" attr='b',\n" -" ctx=Store()),\n" -" annotation=Name(id='int', ctx=Load()),\n" -" simple=0)])\n" -"\n" -">>> print(ast.dump(ast.parse('a[1]: int'), indent=4)) # Subscript " -"annotation\n" -"Module(\n" -" body=[\n" -" AnnAssign(\n" -" target=Subscript(\n" -" value=Name(id='a', ctx=Load()),\n" -" slice=Constant(value=1),\n" -" ctx=Store()),\n" -" annotation=Name(id='int', ctx=Load()),\n" -" simple=0)])" -msgstr "" -">>> print(ast.dump(ast.parse('c: int'), indent=4))\n" -"Module(\n" -" body=[\n" -" AnnAssign(\n" -" target=Name(id='c', ctx=Store()),\n" -" annotation=Name(id='int', ctx=Load()),\n" -" simple=1)])\n" -"\n" -">>> print(ast.dump(ast.parse('(a): int = 1'), indent=4)) # Annotation with " -"parenthesis\n" -"Module(\n" -" body=[\n" -" AnnAssign(\n" -" target=Name(id='a', ctx=Store()),\n" -" annotation=Name(id='int', ctx=Load()),\n" -" value=Constant(value=1),\n" -" simple=0)])\n" -"\n" -">>> print(ast.dump(ast.parse('a.b: int'), indent=4)) # Attribute annotation\n" -"Module(\n" -" body=[\n" -" AnnAssign(\n" -" target=Attribute(\n" -" value=Name(id='a', ctx=Load()),\n" -" attr='b',\n" -" ctx=Store()),\n" -" annotation=Name(id='int', ctx=Load()),\n" -" simple=0)])\n" -"\n" -">>> print(ast.dump(ast.parse('a[1]: int'), indent=4)) # Subscript " -"annotation\n" -"Module(\n" -" body=[\n" -" AnnAssign(\n" -" target=Subscript(\n" -" value=Name(id='a', ctx=Load()),\n" -" slice=Constant(value=1),\n" -" ctx=Store()),\n" -" annotation=Name(id='int', ctx=Load()),\n" -" simple=0)])" - -#: ../../library/ast.rst:1009 -msgid "" -"Augmented assignment, such as ``a += 1``. In the following example, " -"``target`` is a :class:`Name` node for ``x`` (with the :class:`Store` " -"context), ``op`` is :class:`Add`, and ``value`` is a :class:`Constant` with " -"value for 1." -msgstr "" -"增加賦值 (augmented assignment)，例如 ``a += 1``。在下面的範例中，``target`` " -"是 ``x`` 的 :class:`Name` 節點（帶有 :class:`Store` 情境），``op`` 是 :class:" -"`Add`，``value`` 是一個值為 1 的 :class:`Constant`。" - -#: ../../library/ast.rst:1014 -msgid "" -"The ``target`` attribute cannot be of class :class:`Tuple` or :class:`List`, " -"unlike the targets of :class:`Assign`." -msgstr "" -"與 :class:`Assign` 的目標不同，``target`` 屬性不能屬於 :class:`Tuple` 或 :" -"class:`List` 類別。" - -#: ../../library/ast.rst:1017 -msgid "" -">>> print(ast.dump(ast.parse('x += 2'), indent=4))\n" -"Module(\n" -" body=[\n" -" AugAssign(\n" -" target=Name(id='x', ctx=Store()),\n" -" op=Add(),\n" -" value=Constant(value=2))])" -msgstr "" -">>> print(ast.dump(ast.parse('x += 2'), indent=4))\n" -"Module(\n" -" body=[\n" -" AugAssign(\n" -" target=Name(id='x', ctx=Store()),\n" -" op=Add(),\n" -" value=Constant(value=2))])" - -#: ../../library/ast.rst:1030 -msgid "" -"A ``raise`` statement. ``exc`` is the exception object to be raised, " -"normally a :class:`Call` or :class:`Name`, or ``None`` for a standalone " -"``raise``. ``cause`` is the optional part for ``y`` in ``raise x from y``." -msgstr "" -"一個 ``raise`` 陳述式。``exc`` 是要引發的例外物件，通常是 :class:`Call` 或 :" -"class:`Name`，若是獨立的 ``raise`` 則為 ``None``。``cause`` 是 ``raise x " -"from y`` 中的可選部分 ``y``。" - -#: ../../library/ast.rst:1034 -msgid "" -">>> print(ast.dump(ast.parse('raise x from y'), indent=4))\n" -"Module(\n" -" body=[\n" -" Raise(\n" -" exc=Name(id='x', ctx=Load()),\n" -" cause=Name(id='y', ctx=Load()))])" -msgstr "" -">>> print(ast.dump(ast.parse('raise x from y'), indent=4))\n" -"Module(\n" -" body=[\n" -" Raise(\n" -" exc=Name(id='x', ctx=Load()),\n" -" cause=Name(id='y', ctx=Load()))])" - -#: ../../library/ast.rst:1046 -msgid "" -"An assertion. ``test`` holds the condition, such as a :class:`Compare` node. " -"``msg`` holds the failure message." -msgstr "" -"一個斷言 (assertion)。``test`` 保存條件，例如 :class:`Compare` 節點。``msg`` " -"保存失敗訊息。" - -#: ../../library/ast.rst:1049 -msgid "" -">>> print(ast.dump(ast.parse('assert x,y'), indent=4))\n" -"Module(\n" -" body=[\n" -" Assert(\n" -" test=Name(id='x', ctx=Load()),\n" -" msg=Name(id='y', ctx=Load()))])" -msgstr "" -">>> print(ast.dump(ast.parse('assert x,y'), indent=4))\n" -"Module(\n" -" body=[\n" -" Assert(\n" -" test=Name(id='x', ctx=Load()),\n" -" msg=Name(id='y', ctx=Load()))])" - -#: ../../library/ast.rst:1061 -msgid "" -"Represents a ``del`` statement. ``targets`` is a list of nodes, such as :" -"class:`Name`, :class:`Attribute` or :class:`Subscript` nodes." -msgstr "" -"代表一個 ``del`` 陳述式。``targets`` 是節點串列，例如 :class:`Name`、:class:" -"`Attribute` 或 :class:`Subscript` 節點。" - -#: ../../library/ast.rst:1064 -msgid "" -">>> print(ast.dump(ast.parse('del x,y,z'), indent=4))\n" -"Module(\n" -" body=[\n" -" Delete(\n" -" targets=[\n" -" Name(id='x', ctx=Del()),\n" -" Name(id='y', ctx=Del()),\n" -" Name(id='z', ctx=Del())])])" -msgstr "" -">>> print(ast.dump(ast.parse('del x,y,z'), indent=4))\n" -"Module(\n" -" body=[\n" -" Delete(\n" -" targets=[\n" -" Name(id='x', ctx=Del()),\n" -" Name(id='y', ctx=Del()),\n" -" Name(id='z', ctx=Del())])])" - -#: ../../library/ast.rst:1078 -msgid "A ``pass`` statement." -msgstr "一個 ``pass`` 陳述式。" - -#: ../../library/ast.rst:1080 -msgid "" -">>> print(ast.dump(ast.parse('pass'), indent=4))\n" -"Module(\n" -" body=[\n" -" Pass()])" -msgstr "" -">>> print(ast.dump(ast.parse('pass'), indent=4))\n" -"Module(\n" -" body=[\n" -" Pass()])" - -#: ../../library/ast.rst:1090 -msgid "" -"A :ref:`type alias ` created through the :keyword:`type` " -"statement. ``name`` is the name of the alias, ``type_params`` is a list of :" -"ref:`type parameters `, and ``value`` is the value of the " -"type alias." -msgstr "" -"透過 :keyword:`type` 陳述式建立的\\ :ref:`型別別名 (type alias) `。``name`` 是別名的名稱、``type_params`` 是\\ :ref:`型別參數 (type " -"parameter) ` 的串列、``value`` 是型別別名的值。" - -#: ../../library/ast.rst:1095 -msgid "" -">>> print(ast.dump(ast.parse('type Alias = int'), indent=4))\n" -"Module(\n" -" body=[\n" -" TypeAlias(\n" -" name=Name(id='Alias', ctx=Store()),\n" -" value=Name(id='int', ctx=Load()))])" -msgstr "" -">>> print(ast.dump(ast.parse('type Alias = int'), indent=4))\n" -"Module(\n" -" body=[\n" -" TypeAlias(\n" -" name=Name(id='Alias', ctx=Store()),\n" -" value=Name(id='int', ctx=Load()))])" - -#: ../../library/ast.rst:1106 -msgid "" -"Other statements which are only applicable inside functions or loops are " -"described in other sections." -msgstr "其他僅適用於函式或迴圈內部的陳述式將在其他部分中描述。" - -#: ../../library/ast.rst:1110 -msgid "Imports" -msgstr "引入 (imports)" - -#: ../../library/ast.rst:1114 -msgid "An import statement. ``names`` is a list of :class:`alias` nodes." -msgstr "一個 import 陳述式。``names`` 是 :class:`alias` 節點的串列。" - -#: ../../library/ast.rst:1116 -msgid "" -">>> print(ast.dump(ast.parse('import x,y,z'), indent=4))\n" -"Module(\n" -" body=[\n" -" Import(\n" -" names=[\n" -" alias(name='x'),\n" -" alias(name='y'),\n" -" alias(name='z')])])" -msgstr "" -">>> print(ast.dump(ast.parse('import x,y,z'), indent=4))\n" -"Module(\n" -" body=[\n" -" Import(\n" -" names=[\n" -" alias(name='x'),\n" -" alias(name='y'),\n" -" alias(name='z')])])" - -#: ../../library/ast.rst:1130 -msgid "" -"Represents ``from x import y``. ``module`` is a raw string of the 'from' " -"name, without any leading dots, or ``None`` for statements such as ``from . " -"import foo``. ``level`` is an integer holding the level of the relative " -"import (0 means absolute import)." -msgstr "" -"代表 ``from x import y``。``module`` 是 'from' 名稱的原始字串，前面沒有任何的" -"點 (dot)，或者對於諸如 ``from . import foo`` 之類的陳述式則為 ``None``。" -"``level`` 是一個整數，保存相對引入的級別（0 表示絕對引入）。" - -#: ../../library/ast.rst:1135 -msgid "" -">>> print(ast.dump(ast.parse('from y import x,y,z'), indent=4))\n" -"Module(\n" -" body=[\n" -" ImportFrom(\n" -" module='y',\n" -" names=[\n" -" alias(name='x'),\n" -" alias(name='y'),\n" -" alias(name='z')],\n" -" level=0)])" -msgstr "" -">>> print(ast.dump(ast.parse('from y import x,y,z'), indent=4))\n" -"Module(\n" -" body=[\n" -" ImportFrom(\n" -" module='y',\n" -" names=[\n" -" alias(name='x'),\n" -" alias(name='y'),\n" -" alias(name='z')],\n" -" level=0)])" - -#: ../../library/ast.rst:1151 -msgid "" -"Both parameters are raw strings of the names. ``asname`` can be ``None`` if " -"the regular name is to be used." -msgstr "" -"這兩個參數都是名稱的原始字串。如果要使用常規名稱，``asname`` 可以為 " -"``None``。" - -#: ../../library/ast.rst:1154 -msgid "" -">>> print(ast.dump(ast.parse('from ..foo.bar import a as b, c'), indent=4))\n" -"Module(\n" -" body=[\n" -" ImportFrom(\n" -" module='foo.bar',\n" -" names=[\n" -" alias(name='a', asname='b'),\n" -" alias(name='c')],\n" -" level=2)])" -msgstr "" -">>> print(ast.dump(ast.parse('from ..foo.bar import a as b, c'), indent=4))\n" -"Module(\n" -" body=[\n" -" ImportFrom(\n" -" module='foo.bar',\n" -" names=[\n" -" alias(name='a', asname='b'),\n" -" alias(name='c')],\n" -" level=2)])" - -#: ../../library/ast.rst:1167 -msgid "Control flow" -msgstr "流程控制" - -#: ../../library/ast.rst:1170 -msgid "" -"Optional clauses such as ``else`` are stored as an empty list if they're not " -"present." -msgstr "諸如 ``else`` 之類的可選子句如果不存在，則將被儲存為空串列。" - -#: ../../library/ast.rst:1175 -msgid "" -"An ``if`` statement. ``test`` holds a single node, such as a :class:" -"`Compare` node. ``body`` and ``orelse`` each hold a list of nodes." -msgstr "" -"一個 ``if`` 陳述式。``test`` 保存單個節點，例如 :class:`Compare` 節點。" -"``body`` 和 ``orelse`` 各自保存一個節點串列。" - -#: ../../library/ast.rst:1178 -msgid "" -"``elif`` clauses don't have a special representation in the AST, but rather " -"appear as extra :class:`If` nodes within the ``orelse`` section of the " -"previous one." -msgstr "" -"``elif`` 子句在 AST 中沒有特殊表示，而是在前一個子句的 ``orelse`` 部分中作為" -"額外的 :class:`If` 節點出現。" - -#: ../../library/ast.rst:1182 -msgid "" -">>> print(ast.dump(ast.parse(\"\"\"\n" -"... if x:\n" -"... ...\n" -"... elif y:\n" -"... ...\n" -"... else:\n" -"... ...\n" -"... \"\"\"), indent=4))\n" -"Module(\n" -" body=[\n" -" If(\n" -" test=Name(id='x', ctx=Load()),\n" -" body=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))],\n" -" orelse=[\n" -" If(\n" -" test=Name(id='y', ctx=Load()),\n" -" body=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))],\n" -" orelse=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))])])])" -msgstr "" -">>> print(ast.dump(ast.parse(\"\"\"\n" -"... if x:\n" -"... ...\n" -"... elif y:\n" -"... ...\n" -"... else:\n" -"... ...\n" -"... \"\"\"), indent=4))\n" -"Module(\n" -" body=[\n" -" If(\n" -" test=Name(id='x', ctx=Load()),\n" -" body=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))],\n" -" orelse=[\n" -" If(\n" -" test=Name(id='y', ctx=Load()),\n" -" body=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))],\n" -" orelse=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))])])])" - -#: ../../library/ast.rst:1212 -msgid "" -"A ``for`` loop. ``target`` holds the variable(s) the loop assigns to, as a " -"single :class:`Name`, :class:`Tuple`, :class:`List`, :class:`Attribute` or :" -"class:`Subscript` node. ``iter`` holds the item to be looped over, again as " -"a single node. ``body`` and ``orelse`` contain lists of nodes to execute. " -"Those in ``orelse`` are executed if the loop finishes normally, rather than " -"via a ``break`` statement." -msgstr "" -"一個 ``for`` 迴圈。 ``target`` 保存迴圈賦予的變數，為單個 :class:`Name`、:" -"class:`Tuple`、:class:`List`、:class:`Attribute` 或 :class:`Subscript` 節點。" -"``iter`` 保存要迴圈跑過的項目，也為單個節點。``body`` 和 ``orelse`` 包含要執" -"行的節點串列。如果迴圈正常完成，則執行 ``orelse`` 中的內容，而不是透過 " -"``break`` 陳述式執行。" - -#: ../../library/ast.rst:1223 -msgid "" -">>> print(ast.dump(ast.parse(\"\"\"\n" -"... for x in y:\n" -"... ...\n" -"... else:\n" -"... ...\n" -"... \"\"\"), indent=4))\n" -"Module(\n" -" body=[\n" -" For(\n" -" target=Name(id='x', ctx=Store()),\n" -" iter=Name(id='y', ctx=Load()),\n" -" body=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))],\n" -" orelse=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))])])" -msgstr "" -">>> print(ast.dump(ast.parse(\"\"\"\n" -"... for x in y:\n" -"... ...\n" -"... else:\n" -"... ...\n" -"... \"\"\"), indent=4))\n" -"Module(\n" -" body=[\n" -" For(\n" -" target=Name(id='x', ctx=Store()),\n" -" iter=Name(id='y', ctx=Load()),\n" -" body=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))],\n" -" orelse=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))])])" - -#: ../../library/ast.rst:1246 -msgid "" -"A ``while`` loop. ``test`` holds the condition, such as a :class:`Compare` " -"node." -msgstr "一個 ``while`` 迴圈。``test`` 保存條件，例如 :class:`Compare` 節點。" - -#: ../../library/ast.rst:1249 -msgid "" -">>> print(ast.dump(ast.parse(\"\"\"\n" -"... while x:\n" -"... ...\n" -"... else:\n" -"... ...\n" -"... \"\"\"), indent=4))\n" -"Module(\n" -" body=[\n" -" While(\n" -" test=Name(id='x', ctx=Load()),\n" -" body=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))],\n" -" orelse=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))])])" -msgstr "" -">>> print(ast.dump(ast.parse(\"\"\"\n" -"... while x:\n" -"... ...\n" -"... else:\n" -"... ...\n" -"... \"\"\"), indent=4))\n" -"Module(\n" -" body=[\n" -" While(\n" -" test=Name(id='x', ctx=Load()),\n" -" body=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))],\n" -" orelse=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))])])" - -#: ../../library/ast.rst:1272 -msgid "The ``break`` and ``continue`` statements." -msgstr "``break`` 和 ``continue`` 陳述式。" - -#: ../../library/ast.rst:1274 -msgid "" -">>> print(ast.dump(ast.parse(\"\"\"\\\n" -"... for a in b:\n" -"... if a > 5:\n" -"... break\n" -"... else:\n" -"... continue\n" -"...\n" -"... \"\"\"), indent=4))\n" -"Module(\n" -" body=[\n" -" For(\n" -" target=Name(id='a', ctx=Store()),\n" -" iter=Name(id='b', ctx=Load()),\n" -" body=[\n" -" If(\n" -" test=Compare(\n" -" left=Name(id='a', ctx=Load()),\n" -" ops=[\n" -" Gt()],\n" -" comparators=[\n" -" Constant(value=5)]),\n" -" body=[\n" -" Break()],\n" -" orelse=[\n" -" Continue()])])])" -msgstr "" -">>> print(ast.dump(ast.parse(\"\"\"\\\n" -"... for a in b:\n" -"... if a > 5:\n" -"... break\n" -"... else:\n" -"... continue\n" -"...\n" -"... \"\"\"), indent=4))\n" -"Module(\n" -" body=[\n" -" For(\n" -" target=Name(id='a', ctx=Store()),\n" -" iter=Name(id='b', ctx=Load()),\n" -" body=[\n" -" If(\n" -" test=Compare(\n" -" left=Name(id='a', ctx=Load()),\n" -" ops=[\n" -" Gt()],\n" -" comparators=[\n" -" Constant(value=5)]),\n" -" body=[\n" -" Break()],\n" -" orelse=[\n" -" Continue()])])])" - -#: ../../library/ast.rst:1305 -msgid "" -"``try`` blocks. All attributes are list of nodes to execute, except for " -"``handlers``, which is a list of :class:`ExceptHandler` nodes." -msgstr "" -"``try`` 區塊。除 ``handlers`` 是 :class:`ExceptHandler` 節點的串列外，其他所" -"有屬性都是要執行之節點的串列。" - -#: ../../library/ast.rst:1308 -msgid "" -">>> print(ast.dump(ast.parse(\"\"\"\n" -"... try:\n" -"... ...\n" -"... except Exception:\n" -"... ...\n" -"... except OtherException as e:\n" -"... ...\n" -"... else:\n" -"... ...\n" -"... finally:\n" -"... ...\n" -"... \"\"\"), indent=4))\n" -"Module(\n" -" body=[\n" -" Try(\n" -" body=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))],\n" -" handlers=[\n" -" ExceptHandler(\n" -" type=Name(id='Exception', ctx=Load()),\n" -" body=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))]),\n" -" ExceptHandler(\n" -" type=Name(id='OtherException', ctx=Load()),\n" -" name='e',\n" -" body=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))])],\n" -" orelse=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))],\n" -" finalbody=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))])])" -msgstr "" -">>> print(ast.dump(ast.parse(\"\"\"\n" -"... try:\n" -"... ...\n" -"... except Exception:\n" -"... ...\n" -"... except OtherException as e:\n" -"... ...\n" -"... else:\n" -"... ...\n" -"... finally:\n" -"... ...\n" -"... \"\"\"), indent=4))\n" -"Module(\n" -" body=[\n" -" Try(\n" -" body=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))],\n" -" handlers=[\n" -" ExceptHandler(\n" -" type=Name(id='Exception', ctx=Load()),\n" -" body=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))]),\n" -" ExceptHandler(\n" -" type=Name(id='OtherException', ctx=Load()),\n" -" name='e',\n" -" body=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))])],\n" -" orelse=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))],\n" -" finalbody=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))])])" - -#: ../../library/ast.rst:1350 -msgid "" -"``try`` blocks which are followed by ``except*`` clauses. The attributes are " -"the same as for :class:`Try` but the :class:`ExceptHandler` nodes in " -"``handlers`` are interpreted as ``except*`` blocks rather then ``except``." -msgstr "" -"``try`` 區塊，後面跟著 ``except*`` 子句。這些屬性與 :class:`Try` 相同，但是 " -"``handlers`` 中的 :class:`ExceptHandler` 節點被直譯 (interpret) 為 " -"``except*`` 區塊而不是 ``except``。" - -#: ../../library/ast.rst:1354 -msgid "" -">>> print(ast.dump(ast.parse(\"\"\"\n" -"... try:\n" -"... ...\n" -"... except* Exception:\n" -"... ...\n" -"... \"\"\"), indent=4))\n" -"Module(\n" -" body=[\n" -" TryStar(\n" -" body=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))],\n" -" handlers=[\n" -" ExceptHandler(\n" -" type=Name(id='Exception', ctx=Load()),\n" -" body=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))])])])" -msgstr "" -">>> print(ast.dump(ast.parse(\"\"\"\n" -"... try:\n" -"... ...\n" -"... except* Exception:\n" -"... ...\n" -"... \"\"\"), indent=4))\n" -"Module(\n" -" body=[\n" -" TryStar(\n" -" body=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))],\n" -" handlers=[\n" -" ExceptHandler(\n" -" type=Name(id='Exception', ctx=Load()),\n" -" body=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))])])])" - -#: ../../library/ast.rst:1379 -msgid "" -"A single ``except`` clause. ``type`` is the exception type it will match, " -"typically a :class:`Name` node (or ``None`` for a catch-all ``except:`` " -"clause). ``name`` is a raw string for the name to hold the exception, or " -"``None`` if the clause doesn't have ``as foo``. ``body`` is a list of nodes." -msgstr "" -"單個 ``except`` 子句。``type`` 是會被匹配的例外型別，通常是一個 :class:" -"`Name` 節點（或者 ``None`` 表示會捕捉到所有例外的 ``except:`` 子句）。" -"``name`` 是用於保存例外的名稱之原始字串，如果子句沒有 ``as foo`` ，則為 " -"``None``。``body`` 是節點串列。" - -#: ../../library/ast.rst:1384 -msgid "" -">>> print(ast.dump(ast.parse(\"\"\"\\\n" -"... try:\n" -"... a + 1\n" -"... except TypeError:\n" -"... pass\n" -"... \"\"\"), indent=4))\n" -"Module(\n" -" body=[\n" -" Try(\n" -" body=[\n" -" Expr(\n" -" value=BinOp(\n" -" left=Name(id='a', ctx=Load()),\n" -" op=Add(),\n" -" right=Constant(value=1)))],\n" -" handlers=[\n" -" ExceptHandler(\n" -" type=Name(id='TypeError', ctx=Load()),\n" -" body=[\n" -" Pass()])])])" -msgstr "" -">>> print(ast.dump(ast.parse(\"\"\"\\\n" -"... try:\n" -"... a + 1\n" -"... except TypeError:\n" -"... pass\n" -"... \"\"\"), indent=4))\n" -"Module(\n" -" body=[\n" -" Try(\n" -" body=[\n" -" Expr(\n" -" value=BinOp(\n" -" left=Name(id='a', ctx=Load()),\n" -" op=Add(),\n" -" right=Constant(value=1)))],\n" -" handlers=[\n" -" ExceptHandler(\n" -" type=Name(id='TypeError', ctx=Load()),\n" -" body=[\n" -" Pass()])])])" - -#: ../../library/ast.rst:1410 -msgid "" -"A ``with`` block. ``items`` is a list of :class:`withitem` nodes " -"representing the context managers, and ``body`` is the indented block inside " -"the context." -msgstr "" -"一個 ``with`` 區塊。``items`` 是表示情境管理器的 :class:`withitem` 節點串列，" -"``body`` 是情境內的縮進區塊。" - -#: ../../library/ast.rst:1420 -msgid "" -"A single context manager in a ``with`` block. ``context_expr`` is the " -"context manager, often a :class:`Call` node. ``optional_vars`` is a :class:" -"`Name`, :class:`Tuple` or :class:`List` for the ``as foo`` part, or ``None`` " -"if that isn't used." -msgstr "" -"``with`` 區塊中的單個情境管理器。``context_expr`` 是情境管理器，通常是一個 :" -"class:`Call` 節點。``Optional_vars`` 是 ``as foo`` 部分的 :class:`Name`、:" -"class:`Tuple` 或 :class:`List`，或者如果不使用則為 ``None`` 。" - -#: ../../library/ast.rst:1425 -msgid "" -">>> print(ast.dump(ast.parse(\"\"\"\\\n" -"... with a as b, c as d:\n" -"... something(b, d)\n" -"... \"\"\"), indent=4))\n" -"Module(\n" -" body=[\n" -" With(\n" -" items=[\n" -" withitem(\n" -" context_expr=Name(id='a', ctx=Load()),\n" -" optional_vars=Name(id='b', ctx=Store())),\n" -" withitem(\n" -" context_expr=Name(id='c', ctx=Load()),\n" -" optional_vars=Name(id='d', ctx=Store()))],\n" -" body=[\n" -" Expr(\n" -" value=Call(\n" -" func=Name(id='something', ctx=Load()),\n" -" args=[\n" -" Name(id='b', ctx=Load()),\n" -" Name(id='d', ctx=Load())]))])])" -msgstr "" -">>> print(ast.dump(ast.parse(\"\"\"\\\n" -"... with a as b, c as d:\n" -"... something(b, d)\n" -"... \"\"\"), indent=4))\n" -"Module(\n" -" body=[\n" -" With(\n" -" items=[\n" -" withitem(\n" -" context_expr=Name(id='a', ctx=Load()),\n" -" optional_vars=Name(id='b', ctx=Store())),\n" -" withitem(\n" -" context_expr=Name(id='c', ctx=Load()),\n" -" optional_vars=Name(id='d', ctx=Store()))],\n" -" body=[\n" -" Expr(\n" -" value=Call(\n" -" func=Name(id='something', ctx=Load()),\n" -" args=[\n" -" Name(id='b', ctx=Load()),\n" -" Name(id='d', ctx=Load())]))])])" - -#: ../../library/ast.rst:1451 -msgid "Pattern matching" -msgstr "模式匹配 (pattern matching)" - -#: ../../library/ast.rst:1456 -msgid "" -"A ``match`` statement. ``subject`` holds the subject of the match (the " -"object that is being matched against the cases) and ``cases`` contains an " -"iterable of :class:`match_case` nodes with the different cases." -msgstr "" -"一個 ``match`` 陳述式。``subject`` 保存匹配的主題（與案例匹配的物件），" -"``cases`` 包含具有不同案例的 :class:`match_case` 節點的可疊代物件。" - -#: ../../library/ast.rst:1464 -msgid "" -"A single case pattern in a ``match`` statement. ``pattern`` contains the " -"match pattern that the subject will be matched against. Note that the :class:" -"`AST` nodes produced for patterns differ from those produced for " -"expressions, even when they share the same syntax." -msgstr "" -"``match`` 陳述式中的單個案例模式。``pattern`` 包含主題將與之匹配的匹配模式。" -"請注意，為模式生成的 :class:`AST` 節點與為運算式生成的節點不同，即使它們共享" -"相同的語法。" - -#: ../../library/ast.rst:1469 -msgid "" -"The ``guard`` attribute contains an expression that will be evaluated if the " -"pattern matches the subject." -msgstr "``guard`` 屬性包含一個運算式，如果模式與主題匹配，則將對該運算式求值。" - -#: ../../library/ast.rst:1472 -msgid "" -"``body`` contains a list of nodes to execute if the pattern matches and the " -"result of evaluating the guard expression is true." -msgstr "" -"``body`` 包含一個節點串列，如果模式匹配並且為防護運算式 (guard expression) 的" -"求值 (evaluate) 結果為真，則會執行該節點串列。" - -#: ../../library/ast.rst:1475 -msgid "" -">>> print(ast.dump(ast.parse(\"\"\"\n" -"... match x:\n" -"... case [x] if x>0:\n" -"... ...\n" -"... case tuple():\n" -"... ...\n" -"... \"\"\"), indent=4))\n" -"Module(\n" -" body=[\n" -" Match(\n" -" subject=Name(id='x', ctx=Load()),\n" -" cases=[\n" -" match_case(\n" -" pattern=MatchSequence(\n" -" patterns=[\n" -" MatchAs(name='x')]),\n" -" guard=Compare(\n" -" left=Name(id='x', ctx=Load()),\n" -" ops=[\n" -" Gt()],\n" -" comparators=[\n" -" Constant(value=0)]),\n" -" body=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))]),\n" -" match_case(\n" -" pattern=MatchClass(\n" -" cls=Name(id='tuple', ctx=Load())),\n" -" body=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))])])])" -msgstr "" -">>> print(ast.dump(ast.parse(\"\"\"\n" -"... match x:\n" -"... case [x] if x>0:\n" -"... ...\n" -"... case tuple():\n" -"... ...\n" -"... \"\"\"), indent=4))\n" -"Module(\n" -" body=[\n" -" Match(\n" -" subject=Name(id='x', ctx=Load()),\n" -" cases=[\n" -" match_case(\n" -" pattern=MatchSequence(\n" -" patterns=[\n" -" MatchAs(name='x')]),\n" -" guard=Compare(\n" -" left=Name(id='x', ctx=Load()),\n" -" ops=[\n" -" Gt()],\n" -" comparators=[\n" -" Constant(value=0)]),\n" -" body=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))]),\n" -" match_case(\n" -" pattern=MatchClass(\n" -" cls=Name(id='tuple', ctx=Load())),\n" -" body=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))])])])" - -#: ../../library/ast.rst:1513 -msgid "" -"A match literal or value pattern that compares by equality. ``value`` is an " -"expression node. Permitted value nodes are restricted as described in the " -"match statement documentation. This pattern succeeds if the match subject is " -"equal to the evaluated value." -msgstr "" -"以相等性進行比較的匹配文本或值的模式。``value`` 是一個運算式節點。允許值節點" -"受到匹配陳述式文件中所述的限制。如果匹配主題等於求出值，則此模式成功。" - -#: ../../library/ast.rst:1518 -msgid "" -">>> print(ast.dump(ast.parse(\"\"\"\n" -"... match x:\n" -"... case \"Relevant\":\n" -"... ...\n" -"... \"\"\"), indent=4))\n" -"Module(\n" -" body=[\n" -" Match(\n" -" subject=Name(id='x', ctx=Load()),\n" -" cases=[\n" -" match_case(\n" -" pattern=MatchValue(\n" -" value=Constant(value='Relevant')),\n" -" body=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))])])])" -msgstr "" -">>> print(ast.dump(ast.parse(\"\"\"\n" -"... match x:\n" -"... case \"Relevant\":\n" -"... ...\n" -"... \"\"\"), indent=4))\n" -"Module(\n" -" body=[\n" -" Match(\n" -" subject=Name(id='x', ctx=Load()),\n" -" cases=[\n" -" match_case(\n" -" pattern=MatchValue(\n" -" value=Constant(value='Relevant')),\n" -" body=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))])])])" - -#: ../../library/ast.rst:1541 -msgid "" -"A match literal pattern that compares by identity. ``value`` is the " -"singleton to be compared against: ``None``, ``True``, or ``False``. This " -"pattern succeeds if the match subject is the given constant." -msgstr "" -"按識別性 (identity) 進行比較的匹配文本模式。``value`` 是要與 ``None``、" -"``True`` 或 ``False`` 進行比較的單例 (singleton)。如果匹配主題是給定的常數，" -"則此模式成功。" - -#: ../../library/ast.rst:1545 -msgid "" -">>> print(ast.dump(ast.parse(\"\"\"\n" -"... match x:\n" -"... case None:\n" -"... ...\n" -"... \"\"\"), indent=4))\n" -"Module(\n" -" body=[\n" -" Match(\n" -" subject=Name(id='x', ctx=Load()),\n" -" cases=[\n" -" match_case(\n" -" pattern=MatchSingleton(value=None),\n" -" body=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))])])])" -msgstr "" -">>> print(ast.dump(ast.parse(\"\"\"\n" -"... match x:\n" -"... case None:\n" -"... ...\n" -"... \"\"\"), indent=4))\n" -"Module(\n" -" body=[\n" -" Match(\n" -" subject=Name(id='x', ctx=Load()),\n" -" cases=[\n" -" match_case(\n" -" pattern=MatchSingleton(value=None),\n" -" body=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))])])])" - -#: ../../library/ast.rst:1567 -msgid "" -"A match sequence pattern. ``patterns`` contains the patterns to be matched " -"against the subject elements if the subject is a sequence. Matches a " -"variable length sequence if one of the subpatterns is a ``MatchStar`` node, " -"otherwise matches a fixed length sequence." -msgstr "" -"匹配序列模式。如果主題是一個序列，``patterns`` 包含與主題元素匹配的模式。如果" -"子模式之一是 ``MatchStar`` 節點，則匹配可變長度序列，否則匹配固定長度序列。" - -#: ../../library/ast.rst:1572 -msgid "" -">>> print(ast.dump(ast.parse(\"\"\"\n" -"... match x:\n" -"... case [1, 2]:\n" -"... ...\n" -"... \"\"\"), indent=4))\n" -"Module(\n" -" body=[\n" -" Match(\n" -" subject=Name(id='x', ctx=Load()),\n" -" cases=[\n" -" match_case(\n" -" pattern=MatchSequence(\n" -" patterns=[\n" -" MatchValue(\n" -" value=Constant(value=1)),\n" -" MatchValue(\n" -" value=Constant(value=2))]),\n" -" body=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))])])])" -msgstr "" -">>> print(ast.dump(ast.parse(\"\"\"\n" -"... match x:\n" -"... case [1, 2]:\n" -"... ...\n" -"... \"\"\"), indent=4))\n" -"Module(\n" -" body=[\n" -" Match(\n" -" subject=Name(id='x', ctx=Load()),\n" -" cases=[\n" -" match_case(\n" -" pattern=MatchSequence(\n" -" patterns=[\n" -" MatchValue(\n" -" value=Constant(value=1)),\n" -" MatchValue(\n" -" value=Constant(value=2))]),\n" -" body=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))])])])" - -#: ../../library/ast.rst:1599 -msgid "" -"Matches the rest of the sequence in a variable length match sequence " -"pattern. If ``name`` is not ``None``, a list containing the remaining " -"sequence elements is bound to that name if the overall sequence pattern is " -"successful." -msgstr "" -"以可變長度匹配序列模式匹配序列的其餘部分。如果 ``name`` 不是 ``None``，則如果" -"整體序列模式成功，則包含其餘序列元素的串列將綁定到該名稱。" - -#: ../../library/ast.rst:1603 -msgid "" -">>> print(ast.dump(ast.parse(\"\"\"\n" -"... match x:\n" -"... case [1, 2, *rest]:\n" -"... ...\n" -"... case [*_]:\n" -"... ...\n" -"... \"\"\"), indent=4))\n" -"Module(\n" -" body=[\n" -" Match(\n" -" subject=Name(id='x', ctx=Load()),\n" -" cases=[\n" -" match_case(\n" -" pattern=MatchSequence(\n" -" patterns=[\n" -" MatchValue(\n" -" value=Constant(value=1)),\n" -" MatchValue(\n" -" value=Constant(value=2)),\n" -" MatchStar(name='rest')]),\n" -" body=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))]),\n" -" match_case(\n" -" pattern=MatchSequence(\n" -" patterns=[\n" -" MatchStar()]),\n" -" body=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))])])])" -msgstr "" -">>> print(ast.dump(ast.parse(\"\"\"\n" -"... match x:\n" -"... case [1, 2, *rest]:\n" -"... ...\n" -"... case [*_]:\n" -"... ...\n" -"... \"\"\"), indent=4))\n" -"Module(\n" -" body=[\n" -" Match(\n" -" subject=Name(id='x', ctx=Load()),\n" -" cases=[\n" -" match_case(\n" -" pattern=MatchSequence(\n" -" patterns=[\n" -" MatchValue(\n" -" value=Constant(value=1)),\n" -" MatchValue(\n" -" value=Constant(value=2)),\n" -" MatchStar(name='rest')]),\n" -" body=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))]),\n" -" match_case(\n" -" pattern=MatchSequence(\n" -" patterns=[\n" -" MatchStar()]),\n" -" body=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))])])])" - -#: ../../library/ast.rst:1640 -msgid "" -"A match mapping pattern. ``keys`` is a sequence of expression nodes. " -"``patterns`` is a corresponding sequence of pattern nodes. ``rest`` is an " -"optional name that can be specified to capture the remaining mapping " -"elements. Permitted key expressions are restricted as described in the match " -"statement documentation." -msgstr "" -"匹配對映模式。``keys`` 是運算式節點的序列。``patterns`` 是相應的模式節點序" -"列。``rest`` 是一個可選名稱，可以指定它來捕獲剩餘的對映元素。允許的鍵運算式受" -"到匹配陳述式文件中所述的限制。" - -#: ../../library/ast.rst:1646 -msgid "" -"This pattern succeeds if the subject is a mapping, all evaluated key " -"expressions are present in the mapping, and the value corresponding to each " -"key matches the corresponding subpattern. If ``rest`` is not ``None``, a " -"dict containing the remaining mapping elements is bound to that name if the " -"overall mapping pattern is successful." -msgstr "" -"如果主題是對映，所有求值出的鍵運算式都存在於對映中，並且與每個鍵對應的值與相" -"應的子模式匹配，則此模式成功。如果 ``rest`` 不是 ``None``，則如果整體對映模式" -"成功，則包含其餘對映元素的字典將綁定到該名稱。" - -#: ../../library/ast.rst:1652 -msgid "" -">>> print(ast.dump(ast.parse(\"\"\"\n" -"... match x:\n" -"... case {1: _, 2: _}:\n" -"... ...\n" -"... case {**rest}:\n" -"... ...\n" -"... \"\"\"), indent=4))\n" -"Module(\n" -" body=[\n" -" Match(\n" -" subject=Name(id='x', ctx=Load()),\n" -" cases=[\n" -" match_case(\n" -" pattern=MatchMapping(\n" -" keys=[\n" -" Constant(value=1),\n" -" Constant(value=2)],\n" -" patterns=[\n" -" MatchAs(),\n" -" MatchAs()]),\n" -" body=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))]),\n" -" match_case(\n" -" pattern=MatchMapping(rest='rest'),\n" -" body=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))])])])" -msgstr "" -">>> print(ast.dump(ast.parse(\"\"\"\n" -"... match x:\n" -"... case {1: _, 2: _}:\n" -"... ...\n" -"... case {**rest}:\n" -"... ...\n" -"... \"\"\"), indent=4))\n" -"Module(\n" -" body=[\n" -" Match(\n" -" subject=Name(id='x', ctx=Load()),\n" -" cases=[\n" -" match_case(\n" -" pattern=MatchMapping(\n" -" keys=[\n" -" Constant(value=1),\n" -" Constant(value=2)],\n" -" patterns=[\n" -" MatchAs(),\n" -" MatchAs()]),\n" -" body=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))]),\n" -" match_case(\n" -" pattern=MatchMapping(rest='rest'),\n" -" body=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))])])])" - -#: ../../library/ast.rst:1687 -msgid "" -"A match class pattern. ``cls`` is an expression giving the nominal class to " -"be matched. ``patterns`` is a sequence of pattern nodes to be matched " -"against the class defined sequence of pattern matching attributes. " -"``kwd_attrs`` is a sequence of additional attributes to be matched " -"(specified as keyword arguments in the class pattern), ``kwd_patterns`` are " -"the corresponding patterns (specified as keyword values in the class " -"pattern)." -msgstr "" -"匹配類別模式。``cls`` 是一個給定要匹配的名義類別 (nominal class) 的運算式。" -"``patterns`` 是要與類別定義的模式匹配屬性序列進行匹配的模式節點序列。" -"``kwd_attrs`` 是要匹配的附加屬性序列（在類別模式中指定為關鍵字引數），" -"``kwd_patterns`` 是相應的模式（在類別模式中指定為關鍵字的值）。" - -#: ../../library/ast.rst:1694 -msgid "" -"This pattern succeeds if the subject is an instance of the nominated class, " -"all positional patterns match the corresponding class-defined attributes, " -"and any specified keyword attributes match their corresponding pattern." -msgstr "" -"如果主題是指定類別的實例，所有位置模式都與相應的類別定義屬性匹配，並且任何指" -"定的關鍵字屬性與其相應模式匹配，則此模式成功。" - -#: ../../library/ast.rst:1698 -msgid "" -"Note: classes may define a property that returns self in order to match a " -"pattern node against the instance being matched. Several builtin types are " -"also matched that way, as described in the match statement documentation." -msgstr "" -"注意：類別可以定義一個回傳 self 的特性 (property)，以便將模式節點與正在匹配的" -"實例進行匹配。一些內建型別也以這種方式匹配，如同匹配陳述式文件中所述。" - -#: ../../library/ast.rst:1702 -msgid "" -">>> print(ast.dump(ast.parse(\"\"\"\n" -"... match x:\n" -"... case Point2D(0, 0):\n" -"... ...\n" -"... case Point3D(x=0, y=0, z=0):\n" -"... ...\n" -"... \"\"\"), indent=4))\n" -"Module(\n" -" body=[\n" -" Match(\n" -" subject=Name(id='x', ctx=Load()),\n" -" cases=[\n" -" match_case(\n" -" pattern=MatchClass(\n" -" cls=Name(id='Point2D', ctx=Load()),\n" -" patterns=[\n" -" MatchValue(\n" -" value=Constant(value=0)),\n" -" MatchValue(\n" -" value=Constant(value=0))]),\n" -" body=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))]),\n" -" match_case(\n" -" pattern=MatchClass(\n" -" cls=Name(id='Point3D', ctx=Load()),\n" -" kwd_attrs=[\n" -" 'x',\n" -" 'y',\n" -" 'z'],\n" -" kwd_patterns=[\n" -" MatchValue(\n" -" value=Constant(value=0)),\n" -" MatchValue(\n" -" value=Constant(value=0)),\n" -" MatchValue(\n" -" value=Constant(value=0))]),\n" -" body=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))])])])" -msgstr "" -">>> print(ast.dump(ast.parse(\"\"\"\n" -"... match x:\n" -"... case Point2D(0, 0):\n" -"... ...\n" -"... case Point3D(x=0, y=0, z=0):\n" -"... ...\n" -"... \"\"\"), indent=4))\n" -"Module(\n" -" body=[\n" -" Match(\n" -" subject=Name(id='x', ctx=Load()),\n" -" cases=[\n" -" match_case(\n" -" pattern=MatchClass(\n" -" cls=Name(id='Point2D', ctx=Load()),\n" -" patterns=[\n" -" MatchValue(\n" -" value=Constant(value=0)),\n" -" MatchValue(\n" -" value=Constant(value=0))]),\n" -" body=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))]),\n" -" match_case(\n" -" pattern=MatchClass(\n" -" cls=Name(id='Point3D', ctx=Load()),\n" -" kwd_attrs=[\n" -" 'x',\n" -" 'y',\n" -" 'z'],\n" -" kwd_patterns=[\n" -" MatchValue(\n" -" value=Constant(value=0)),\n" -" MatchValue(\n" -" value=Constant(value=0)),\n" -" MatchValue(\n" -" value=Constant(value=0))]),\n" -" body=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))])])])" - -#: ../../library/ast.rst:1749 -msgid "" -"A match \"as-pattern\", capture pattern or wildcard pattern. ``pattern`` " -"contains the match pattern that the subject will be matched against. If the " -"pattern is ``None``, the node represents a capture pattern (i.e a bare name) " -"and will always succeed." -msgstr "" -"匹配的 「as 模式 (as-pattern)」，為捕獲模式 (capture pattern) 或通配模式 " -"(wildcard pattern)。``pattern`` 包含主題將與之匹配的匹配模式。如果模式為 " -"``None``，則該節點代表捕獲模式（即裸名 (bare name)）並且始終會成功。" - -#: ../../library/ast.rst:1754 -msgid "" -"The ``name`` attribute contains the name that will be bound if the pattern " -"is successful. If ``name`` is ``None``, ``pattern`` must also be ``None`` " -"and the node represents the wildcard pattern." -msgstr "" -"``name`` 屬性包含模式成功時將綁定的名稱。如果 ``name`` 為 ``None``，則 " -"``pattern`` 也必須為 ``None``，並且節點代表通配模式。" - -#: ../../library/ast.rst:1758 -msgid "" -">>> print(ast.dump(ast.parse(\"\"\"\n" -"... match x:\n" -"... case [x] as y:\n" -"... ...\n" -"... case _:\n" -"... ...\n" -"... \"\"\"), indent=4))\n" -"Module(\n" -" body=[\n" -" Match(\n" -" subject=Name(id='x', ctx=Load()),\n" -" cases=[\n" -" match_case(\n" -" pattern=MatchAs(\n" -" pattern=MatchSequence(\n" -" patterns=[\n" -" MatchAs(name='x')]),\n" -" name='y'),\n" -" body=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))]),\n" -" match_case(\n" -" pattern=MatchAs(),\n" -" body=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))])])])" -msgstr "" -">>> print(ast.dump(ast.parse(\"\"\"\n" -"... match x:\n" -"... case [x] as y:\n" -"... ...\n" -"... case _:\n" -"... ...\n" -"... \"\"\"), indent=4))\n" -"Module(\n" -" body=[\n" -" Match(\n" -" subject=Name(id='x', ctx=Load()),\n" -" cases=[\n" -" match_case(\n" -" pattern=MatchAs(\n" -" pattern=MatchSequence(\n" -" patterns=[\n" -" MatchAs(name='x')]),\n" -" name='y'),\n" -" body=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))]),\n" -" match_case(\n" -" pattern=MatchAs(),\n" -" body=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))])])])" - -#: ../../library/ast.rst:1791 -msgid "" -"A match \"or-pattern\". An or-pattern matches each of its subpatterns in " -"turn to the subject, until one succeeds. The or-pattern is then deemed to " -"succeed. If none of the subpatterns succeed the or-pattern fails. The " -"``patterns`` attribute contains a list of match pattern nodes that will be " -"matched against the subject." -msgstr "" -"匹配的 「or 模式 (or-pattern)」。 or 模式依次將其每個子模式與主題進行匹配，直" -"到成功為止，然後 or 模式就會被認為是成功的。如果沒有一個子模式成功，則 or 模" -"式將失敗。 ``patterns`` 屬性包含將與主題進行匹配的匹配模式節點串列。" - -#: ../../library/ast.rst:1797 -msgid "" -">>> print(ast.dump(ast.parse(\"\"\"\n" -"... match x:\n" -"... case [x] | (y):\n" -"... ...\n" -"... \"\"\"), indent=4))\n" -"Module(\n" -" body=[\n" -" Match(\n" -" subject=Name(id='x', ctx=Load()),\n" -" cases=[\n" -" match_case(\n" -" pattern=MatchOr(\n" -" patterns=[\n" -" MatchSequence(\n" -" patterns=[\n" -" MatchAs(name='x')]),\n" -" MatchAs(name='y')]),\n" -" body=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))])])])" -msgstr "" -">>> print(ast.dump(ast.parse(\"\"\"\n" -"... match x:\n" -"... case [x] | (y):\n" -"... ...\n" -"... \"\"\"), indent=4))\n" -"Module(\n" -" body=[\n" -" Match(\n" -" subject=Name(id='x', ctx=Load()),\n" -" cases=[\n" -" match_case(\n" -" pattern=MatchOr(\n" -" patterns=[\n" -" MatchSequence(\n" -" patterns=[\n" -" MatchAs(name='x')]),\n" -" MatchAs(name='y')]),\n" -" body=[\n" -" Expr(\n" -" value=Constant(value=Ellipsis))])])])" - -#: ../../library/ast.rst:1824 -msgid "Type annotations" -msgstr "型別註釋" - -#: ../../library/ast.rst:1828 -msgid "" -"A ``# type: ignore`` comment located at *lineno*. *tag* is the optional tag " -"specified by the form ``# type: ignore ``." -msgstr "" -"位於 *lineno* 的 ``# type: ignore`` 註解。*tag* 是以 " -"``# type: ignore `` 形式指定的可選標籤。" - -#: ../../library/ast.rst:1831 -msgid "" -">>> print(ast.dump(ast.parse('x = 1 # type: ignore', type_comments=True), " -"indent=4))\n" -"Module(\n" -" body=[\n" -" Assign(\n" -" targets=[\n" -" Name(id='x', ctx=Store())],\n" -" value=Constant(value=1))],\n" -" type_ignores=[\n" -" TypeIgnore(lineno=1, tag='')])\n" -">>> print(ast.dump(ast.parse('x: bool = 1 # type: ignore[assignment]', " -"type_comments=True), indent=4))\n" -"Module(\n" -" body=[\n" -" AnnAssign(\n" -" target=Name(id='x', ctx=Store()),\n" -" annotation=Name(id='bool', ctx=Load()),\n" -" value=Constant(value=1),\n" -" simple=1)],\n" -" type_ignores=[\n" -" TypeIgnore(lineno=1, tag='[assignment]')])" -msgstr "" -">>> print(ast.dump(ast.parse('x = 1 # type: ignore', type_comments=True), " -"indent=4))\n" -"Module(\n" -" body=[\n" -" Assign(\n" -" targets=[\n" -" Name(id='x', ctx=Store())],\n" -" value=Constant(value=1))],\n" -" type_ignores=[\n" -" TypeIgnore(lineno=1, tag='')])\n" -">>> print(ast.dump(ast.parse('x: bool = 1 # type: ignore[assignment]', " -"type_comments=True), indent=4))\n" -"Module(\n" -" body=[\n" -" AnnAssign(\n" -" target=Name(id='x', ctx=Store()),\n" -" annotation=Name(id='bool', ctx=Load()),\n" -" value=Constant(value=1),\n" -" simple=1)],\n" -" type_ignores=[\n" -" TypeIgnore(lineno=1, tag='[assignment]')])" - -#: ../../library/ast.rst:1854 -msgid "" -":class:`!TypeIgnore` nodes are not generated when the *type_comments* " -"parameter is set to ``False`` (default). See :func:`ast.parse` for more " -"details." -msgstr "" -"當 *type_comments* 參數設為 ``False``\\ （預設值）時，不會產生 " -":class:`!TypeIgnore` 節點。更多細節請參閱 :func:`ast.parse`。" - -#: ../../library/ast.rst:1862 -msgid "Type parameters" -msgstr "型別參數 (type parameters)" - -#: ../../library/ast.rst:1864 -msgid "" -":ref:`Type parameters ` can exist on classes, functions, and " -"type aliases." -msgstr ":ref:`型別參數 `\\ 可以存在於類別、函式和型別別名上。" - -#: ../../library/ast.rst:1869 -msgid "" -"A :class:`typing.TypeVar`. ``name`` is the name of the type variable. " -"``bound`` is the bound or constraints, if any. If ``bound`` is a :class:" -"`Tuple`, it represents constraints; otherwise it represents the bound. " -"``default_value`` is the default value; if the :class:`!TypeVar` has no " -"default, this attribute will be set to ``None``." -msgstr "" -"一個 :class:`typing.TypeVar`。``name`` 是型別變數的名稱。``bound`` 是（如果有" -"存在的）界限 (bound) 或約束 (constraint)。如果 ``bound`` 是一個 :class:" -"`Tuple`，它代表約束；否則它代表界限。``default_value`` 為預設值；如果 :class:" -"`!TypeVar` 沒有預設值，那此屬性會被設為 ``None``。" - -#: ../../library/ast.rst:1875 -msgid "" -">>> print(ast.dump(ast.parse(\"type Alias[T: int = bool] = list[T]\"), " -"indent=4))\n" -"Module(\n" -" body=[\n" -" TypeAlias(\n" -" name=Name(id='Alias', ctx=Store()),\n" -" type_params=[\n" -" TypeVar(\n" -" name='T',\n" -" bound=Name(id='int', ctx=Load()),\n" -" default_value=Name(id='bool', ctx=Load()))],\n" -" value=Subscript(\n" -" value=Name(id='list', ctx=Load()),\n" -" slice=Name(id='T', ctx=Load()),\n" -" ctx=Load()))])" -msgstr "" -">>> print(ast.dump(ast.parse(\"type Alias[T: int = bool] = list[T]\"), " -"indent=4))\n" -"Module(\n" -" body=[\n" -" TypeAlias(\n" -" name=Name(id='Alias', ctx=Store()),\n" -" type_params=[\n" -" TypeVar(\n" -" name='T',\n" -" bound=Name(id='int', ctx=Load()),\n" -" default_value=Name(id='bool', ctx=Load()))],\n" -" value=Subscript(\n" -" value=Name(id='list', ctx=Load()),\n" -" slice=Name(id='T', ctx=Load()),\n" -" ctx=Load()))])" - -#: ../../library/ast.rst:1894 ../../library/ast.rst:1929 -#: ../../library/ast.rst:1961 -msgid "Added the *default_value* parameter." -msgstr "新增 *default_value* 參數。" - -#: ../../library/ast.rst:1899 -msgid "" -"A :class:`typing.ParamSpec`. ``name`` is the name of the parameter " -"specification. ``default_value`` is the default value; if the :class:`!" -"ParamSpec` has no default, this attribute will be set to ``None``." -msgstr "" -"一個 :class:`typing.ParamSpec`。``name`` 是參數規範的名稱。``default_value`` " -"是預設值；如果 :class:`!ParamSpec` 沒有預設值，則該屬性將設定為 ``None``。" - -#: ../../library/ast.rst:1903 -msgid "" -">>> print(ast.dump(ast.parse(\"type Alias[**P = [int, str]] = Callable[P, " -"int]\"), indent=4))\n" -"Module(\n" -" body=[\n" -" TypeAlias(\n" -" name=Name(id='Alias', ctx=Store()),\n" -" type_params=[\n" -" ParamSpec(\n" -" name='P',\n" -" default_value=List(\n" -" elts=[\n" -" Name(id='int', ctx=Load()),\n" -" Name(id='str', ctx=Load())],\n" -" ctx=Load()))],\n" -" value=Subscript(\n" -" value=Name(id='Callable', ctx=Load()),\n" -" slice=Tuple(\n" -" elts=[\n" -" Name(id='P', ctx=Load()),\n" -" Name(id='int', ctx=Load())],\n" -" ctx=Load()),\n" -" ctx=Load()))])" -msgstr "" -">>> print(ast.dump(ast.parse(\"type Alias[**P = [int, str]] = Callable[P, " -"int]\"), indent=4))\n" -"Module(\n" -" body=[\n" -" TypeAlias(\n" -" name=Name(id='Alias', ctx=Store()),\n" -" type_params=[\n" -" ParamSpec(\n" -" name='P',\n" -" default_value=List(\n" -" elts=[\n" -" Name(id='int', ctx=Load()),\n" -" Name(id='str', ctx=Load())],\n" -" ctx=Load()))],\n" -" value=Subscript(\n" -" value=Name(id='Callable', ctx=Load()),\n" -" slice=Tuple(\n" -" elts=[\n" -" Name(id='P', ctx=Load()),\n" -" Name(id='int', ctx=Load())],\n" -" ctx=Load()),\n" -" ctx=Load()))])" - -#: ../../library/ast.rst:1934 -msgid "" -"A :class:`typing.TypeVarTuple`. ``name`` is the name of the type variable " -"tuple. ``default_value`` is the default value; if the :class:`!TypeVarTuple` " -"has no default, this attribute will be set to ``None``." -msgstr "" -"一個 :class:`typing.TypeVarTuple`。``name`` 是型別變數元組的名稱。" -"``default_value`` 為預設值；如果 :class:`!TypeVarTuple` 沒有預設值，那此屬性" -"會被設為 ``None``。" - -#: ../../library/ast.rst:1938 -msgid "" -">>> print(ast.dump(ast.parse(\"type Alias[*Ts = ()] = tuple[*Ts]\"), " -"indent=4))\n" -"Module(\n" -" body=[\n" -" TypeAlias(\n" -" name=Name(id='Alias', ctx=Store()),\n" -" type_params=[\n" -" TypeVarTuple(\n" -" name='Ts',\n" -" default_value=Tuple(ctx=Load()))],\n" -" value=Subscript(\n" -" value=Name(id='tuple', ctx=Load()),\n" -" slice=Tuple(\n" -" elts=[\n" -" Starred(\n" -" value=Name(id='Ts', ctx=Load()),\n" -" ctx=Load())],\n" -" ctx=Load()),\n" -" ctx=Load()))])" -msgstr "" -">>> print(ast.dump(ast.parse(\"type Alias[*Ts = ()] = tuple[*Ts]\"), " -"indent=4))\n" -"Module(\n" -" body=[\n" -" TypeAlias(\n" -" name=Name(id='Alias', ctx=Store()),\n" -" type_params=[\n" -" TypeVarTuple(\n" -" name='Ts',\n" -" default_value=Tuple(ctx=Load()))],\n" -" value=Subscript(\n" -" value=Name(id='tuple', ctx=Load()),\n" -" slice=Tuple(\n" -" elts=[\n" -" Starred(\n" -" value=Name(id='Ts', ctx=Load()),\n" -" ctx=Load())],\n" -" ctx=Load()),\n" -" ctx=Load()))])" - -#: ../../library/ast.rst:1965 -msgid "Function and class definitions" -msgstr "函式和類別定義" - -#: ../../library/ast.rst:1969 -msgid "A function definition." -msgstr "一個函式定義。" - -#: ../../library/ast.rst:1971 -msgid "``name`` is a raw string of the function name." -msgstr "``name`` 是函式名稱的原始字串。" - -#: ../../library/ast.rst:1972 -msgid "``args`` is an :class:`arguments` node." -msgstr "``args`` 是一個 :class:`arguments` 節點。" - -#: ../../library/ast.rst:1973 -msgid "``body`` is the list of nodes inside the function." -msgstr "``body`` 是函式內節點的串列。" - -#: ../../library/ast.rst:1974 -msgid "" -"``decorator_list`` is the list of decorators to be applied, stored outermost " -"first (i.e. the first in the list will be applied last)." -msgstr "" -"``decorator_list`` 是要應用的裝飾器串列，在最外層者會被儲存在首位（即串列中首" -"位將會是最後一個被應用的那個）。" - -#: ../../library/ast.rst:1976 -msgid "``returns`` is the return annotation." -msgstr "``returns`` 是回傳註釋。" - -#: ../../library/ast.rst:1977 ../../library/ast.rst:2140 -msgid "``type_params`` is a list of :ref:`type parameters `." -msgstr "``type_params`` 是\\ :ref:`型別參數 `\\ 的串列。" - -#: ../../library/ast.rst:1983 ../../library/ast.rst:2167 -#: ../../library/ast.rst:2178 -msgid "Added ``type_params``." -msgstr "新增了 ``type_params``。" - -#: ../../library/ast.rst:1989 -msgid "" -"``lambda`` is a minimal function definition that can be used inside an " -"expression. Unlike :class:`FunctionDef`, ``body`` holds a single node." -msgstr "" -"``lambda`` 是可以在運算式內使用的最小函式定義。與 :class:`FunctionDef` 不同，" -"``body`` 保存單個節點。" - -#: ../../library/ast.rst:1992 -msgid "" -">>> print(ast.dump(ast.parse('lambda x,y: ...'), indent=4))\n" -"Module(\n" -" body=[\n" -" Expr(\n" -" value=Lambda(\n" -" args=arguments(\n" -" args=[\n" -" arg(arg='x'),\n" -" arg(arg='y')]),\n" -" body=Constant(value=Ellipsis)))])" -msgstr "" -">>> print(ast.dump(ast.parse('lambda x,y: ...'), indent=4))\n" -"Module(\n" -" body=[\n" -" Expr(\n" -" value=Lambda(\n" -" args=arguments(\n" -" args=[\n" -" arg(arg='x'),\n" -" arg(arg='y')]),\n" -" body=Constant(value=Ellipsis)))])" - -#: ../../library/ast.rst:2008 -msgid "The arguments for a function." -msgstr "函式的引數。" - -#: ../../library/ast.rst:2010 -msgid "" -"``posonlyargs``, ``args`` and ``kwonlyargs`` are lists of :class:`arg` nodes." -msgstr "" -"``posonlyargs``、``args`` 和 ``kwonlyargs`` 是 :class:`arg` 節點的串列。" - -#: ../../library/ast.rst:2011 -msgid "" -"``vararg`` and ``kwarg`` are single :class:`arg` nodes, referring to the " -"``*args, **kwargs`` parameters." -msgstr "" -"``vararg`` 和 ``kwarg`` 是單個 :class:`arg` 節點，指的是 ``*args, **kwargs`` " -"參數。" - -#: ../../library/ast.rst:2013 -msgid "" -"``kw_defaults`` is a list of default values for keyword-only arguments. If " -"one is ``None``, the corresponding argument is required." -msgstr "" -"``kw_defaults`` 是僅限關鍵字引數的預設值串列。如果其中某個為 ``None``，則相應" -"參數就會是必要的。" - -#: ../../library/ast.rst:2015 -msgid "" -"``defaults`` is a list of default values for arguments that can be passed " -"positionally. If there are fewer defaults, they correspond to the last n " -"arguments." -msgstr "" -"``defaults`` 是可以按位置傳遞的引數的預設值串列。如果預設值較少，則它們對應於" -"最後 n 個引數。" - -#: ../../library/ast.rst:2022 -msgid "" -"A single argument in a list. ``arg`` is a raw string of the argument name; " -"``annotation`` is its annotation, such as a :class:`Name` node." -msgstr "" -"串列中的單個引數。``arg`` 是引數名稱的原始字串，``annotation`` 是它的註釋，例" -"如 :class:`Name` 節點。" - -#: ../../library/ast.rst:2027 -msgid "" -"``type_comment`` is an optional string with the type annotation as a comment" -msgstr "``type_comment`` 是一個可選字串，其註解為型別註釋" - -#: ../../library/ast.rst:2029 -msgid "" -">>> print(ast.dump(ast.parse(\"\"\"\\\n" -"... @decorator1\n" -"... @decorator2\n" -"... def f(a: 'annotation', b=1, c=2, *d, e, f=3, **g) -> 'return " -"annotation':\n" -"... pass\n" -"... \"\"\"), indent=4))\n" -"Module(\n" -" body=[\n" -" FunctionDef(\n" -" name='f',\n" -" args=arguments(\n" -" args=[\n" -" arg(\n" -" arg='a',\n" -" annotation=Constant(value='annotation')),\n" -" arg(arg='b'),\n" -" arg(arg='c')],\n" -" vararg=arg(arg='d'),\n" -" kwonlyargs=[\n" -" arg(arg='e'),\n" -" arg(arg='f')],\n" -" kw_defaults=[\n" -" None,\n" -" Constant(value=3)],\n" -" kwarg=arg(arg='g'),\n" -" defaults=[\n" -" Constant(value=1),\n" -" Constant(value=2)]),\n" -" body=[\n" -" Pass()],\n" -" decorator_list=[\n" -" Name(id='decorator1', ctx=Load()),\n" -" Name(id='decorator2', ctx=Load())],\n" -" returns=Constant(value='return annotation'))])" -msgstr "" -">>> print(ast.dump(ast.parse(\"\"\"\\\n" -"... @decorator1\n" -"... @decorator2\n" -"... def f(a: 'annotation', b=1, c=2, *d, e, f=3, **g) -> 'return " -"annotation':\n" -"... pass\n" -"... \"\"\"), indent=4))\n" -"Module(\n" -" body=[\n" -" FunctionDef(\n" -" name='f',\n" -" args=arguments(\n" -" args=[\n" -" arg(\n" -" arg='a',\n" -" annotation=Constant(value='annotation')),\n" -" arg(arg='b'),\n" -" arg(arg='c')],\n" -" vararg=arg(arg='d'),\n" -" kwonlyargs=[\n" -" arg(arg='e'),\n" -" arg(arg='f')],\n" -" kw_defaults=[\n" -" None,\n" -" Constant(value=3)],\n" -" kwarg=arg(arg='g'),\n" -" defaults=[\n" -" Constant(value=1),\n" -" Constant(value=2)]),\n" -" body=[\n" -" Pass()],\n" -" decorator_list=[\n" -" Name(id='decorator1', ctx=Load()),\n" -" Name(id='decorator2', ctx=Load())],\n" -" returns=Constant(value='return annotation'))])" - -#: ../../library/ast.rst:2069 -msgid "A ``return`` statement." -msgstr "一個 ``return`` 陳述式。" - -#: ../../library/ast.rst:2071 -msgid "" -">>> print(ast.dump(ast.parse('return 4'), indent=4))\n" -"Module(\n" -" body=[\n" -" Return(\n" -" value=Constant(value=4))])" -msgstr "" -">>> print(ast.dump(ast.parse('return 4'), indent=4))\n" -"Module(\n" -" body=[\n" -" Return(\n" -" value=Constant(value=4))])" - -#: ../../library/ast.rst:2083 -msgid "" -"A ``yield`` or ``yield from`` expression. Because these are expressions, " -"they must be wrapped in an :class:`Expr` node if the value sent back is not " -"used." -msgstr "" -"一個 ``yield`` 或 ``yield from`` 運算式。因為這些是運算式，所以如果不使用發送" -"回來的值，則必須將它們包裝在 :class:`Expr` 節點中。" - -#: ../../library/ast.rst:2086 -msgid "" -">>> print(ast.dump(ast.parse('yield x'), indent=4))\n" -"Module(\n" -" body=[\n" -" Expr(\n" -" value=Yield(\n" -" value=Name(id='x', ctx=Load())))])\n" -"\n" -">>> print(ast.dump(ast.parse('yield from x'), indent=4))\n" -"Module(\n" -" body=[\n" -" Expr(\n" -" value=YieldFrom(\n" -" value=Name(id='x', ctx=Load())))])" -msgstr "" -">>> print(ast.dump(ast.parse('yield x'), indent=4))\n" -"Module(\n" -" body=[\n" -" Expr(\n" -" value=Yield(\n" -" value=Name(id='x', ctx=Load())))])\n" -"\n" -">>> print(ast.dump(ast.parse('yield from x'), indent=4))\n" -"Module(\n" -" body=[\n" -" Expr(\n" -" value=YieldFrom(\n" -" value=Name(id='x', ctx=Load())))])" - -#: ../../library/ast.rst:2106 -msgid "" -"``global`` and ``nonlocal`` statements. ``names`` is a list of raw strings." -msgstr "``global`` 和 ``nonlocal`` 陳述式。``names`` 是原始字串的串列。" - -#: ../../library/ast.rst:2108 -msgid "" -">>> print(ast.dump(ast.parse('global x,y,z'), indent=4))\n" -"Module(\n" -" body=[\n" -" Global(\n" -" names=[\n" -" 'x',\n" -" 'y',\n" -" 'z'])])\n" -"\n" -">>> print(ast.dump(ast.parse('nonlocal x,y,z'), indent=4))\n" -"Module(\n" -" body=[\n" -" Nonlocal(\n" -" names=[\n" -" 'x',\n" -" 'y',\n" -" 'z'])])" -msgstr "" -">>> print(ast.dump(ast.parse('global x,y,z'), indent=4))\n" -"Module(\n" -" body=[\n" -" Global(\n" -" names=[\n" -" 'x',\n" -" 'y',\n" -" 'z'])])\n" -"\n" -">>> print(ast.dump(ast.parse('nonlocal x,y,z'), indent=4))\n" -"Module(\n" -" body=[\n" -" Nonlocal(\n" -" names=[\n" -" 'x',\n" -" 'y',\n" -" 'z'])])" - -#: ../../library/ast.rst:2131 -msgid "A class definition." -msgstr "一個類別定義。" - -#: ../../library/ast.rst:2133 -msgid "``name`` is a raw string for the class name" -msgstr "``name`` 是類別名稱的原始字串" - -#: ../../library/ast.rst:2134 -msgid "``bases`` is a list of nodes for explicitly specified base classes." -msgstr "``bases`` 是被顯式指定的基底類別節點串列。" - -#: ../../library/ast.rst:2135 -msgid "" -"``keywords`` is a list of :class:`.keyword` nodes, principally for " -"'metaclass'. Other keywords will be passed to the metaclass, as per :pep:" -"`3115`." -msgstr "" -"``keywords`` 是一個 :class:`.keyword` 節點的串列，主要用於 'metaclass'（元類" -"別）。如 :pep:`3115` 所述，其他關鍵字將被傳遞到 metaclass。" - -#: ../../library/ast.rst:2137 -msgid "" -"``body`` is a list of nodes representing the code within the class " -"definition." -msgstr "``body`` 是表示類別定義中程式碼的節點串列。" - -#: ../../library/ast.rst:2139 -msgid "``decorator_list`` is a list of nodes, as in :class:`FunctionDef`." -msgstr "``decorator_list`` 是一個節點串列，如 :class:`FunctionDef` 中所示。" - -#: ../../library/ast.rst:2142 -msgid "" -">>> print(ast.dump(ast.parse(\"\"\"\\\n" -"... @decorator1\n" -"... @decorator2\n" -"... class Foo(base1, base2, metaclass=meta):\n" -"... pass\n" -"... \"\"\"), indent=4))\n" -"Module(\n" -" body=[\n" -" ClassDef(\n" -" name='Foo',\n" -" bases=[\n" -" Name(id='base1', ctx=Load()),\n" -" Name(id='base2', ctx=Load())],\n" -" keywords=[\n" -" keyword(\n" -" arg='metaclass',\n" -" value=Name(id='meta', ctx=Load()))],\n" -" body=[\n" -" Pass()],\n" -" decorator_list=[\n" -" Name(id='decorator1', ctx=Load()),\n" -" Name(id='decorator2', ctx=Load())])])" -msgstr "" -">>> print(ast.dump(ast.parse(\"\"\"\\\n" -"... @decorator1\n" -"... @decorator2\n" -"... class Foo(base1, base2, metaclass=meta):\n" -"... pass\n" -"... \"\"\"), indent=4))\n" -"Module(\n" -" body=[\n" -" ClassDef(\n" -" name='Foo',\n" -" bases=[\n" -" Name(id='base1', ctx=Load()),\n" -" Name(id='base2', ctx=Load())],\n" -" keywords=[\n" -" keyword(\n" -" arg='metaclass',\n" -" value=Name(id='meta', ctx=Load()))],\n" -" body=[\n" -" Pass()],\n" -" decorator_list=[\n" -" Name(id='decorator1', ctx=Load()),\n" -" Name(id='decorator2', ctx=Load())])])" - -#: ../../library/ast.rst:2171 -msgid "Async and await" -msgstr "async 和 await" - -#: ../../library/ast.rst:2175 -msgid "" -"An ``async def`` function definition. Has the same fields as :class:" -"`FunctionDef`." -msgstr "一個 ``async def`` 函式定義。與 :class:`FunctionDef` 具有相同的欄位。" - -#: ../../library/ast.rst:2184 -msgid "" -"An ``await`` expression. ``value`` is what it waits for. Only valid in the " -"body of an :class:`AsyncFunctionDef`." -msgstr "" -"一個 ``await`` 運算式。``value`` 是它等待的東西。僅在 :class:" -"`AsyncFunctionDef` 主體 (body) 中有效。" - -#: ../../library/ast.rst:2187 -msgid "" -">>> print(ast.dump(ast.parse(\"\"\"\\\n" -"... async def f():\n" -"... await other_func()\n" -"... \"\"\"), indent=4))\n" -"Module(\n" -" body=[\n" -" AsyncFunctionDef(\n" -" name='f',\n" -" args=arguments(),\n" -" body=[\n" -" Expr(\n" -" value=Await(\n" -" value=Call(\n" -" func=Name(id='other_func', ctx=Load()))))])])" -msgstr "" -">>> print(ast.dump(ast.parse(\"\"\"\\\n" -"... async def f():\n" -"... await other_func()\n" -"... \"\"\"), indent=4))\n" -"Module(\n" -" body=[\n" -" AsyncFunctionDef(\n" -" name='f',\n" -" args=arguments(),\n" -" body=[\n" -" Expr(\n" -" value=Await(\n" -" value=Call(\n" -" func=Name(id='other_func', ctx=Load()))))])])" - -#: ../../library/ast.rst:2208 -msgid "" -"``async for`` loops and ``async with`` context managers. They have the same " -"fields as :class:`For` and :class:`With`, respectively. Only valid in the " -"body of an :class:`AsyncFunctionDef`." -msgstr "" -"``async for`` 迴圈和 ``async with`` 情境管理器。它們分別具有與 :class:`For` " -"和 :class:`With` 相同的欄位。僅在 :class:`AsyncFunctionDef` 主體中有效。" - -#: ../../library/ast.rst:2213 -msgid "" -"When a string is parsed by :func:`ast.parse`, operator nodes (subclasses of :" -"class:`ast.operator`, :class:`ast.unaryop`, :class:`ast.cmpop`, :class:`ast." -"boolop` and :class:`ast.expr_context`) on the returned tree will be " -"singletons. Changes to one will be reflected in all other occurrences of the " -"same value (for example, :class:`ast.Add`)." -msgstr "" -"當字串被 :func:`ast.parse` 剖析時，回傳樹的運算子節點（:class:`ast." -"operator`、:class:`ast.unaryop`、:class:`ast.cmpop`、:class:`ast.boolop` 和 :" -"class:`ast.expr_context` 的子類別）將是單例。對其中之一的更改將反映在所有其他" -"出現的相同值中（例如 :class:`ast.Add`）。" - -#: ../../library/ast.rst:2221 -msgid ":mod:`ast` helpers" -msgstr ":mod:`ast` 輔助程式" - -#: ../../library/ast.rst:2223 -msgid "" -"Apart from the node classes, the :mod:`ast` module defines these utility " -"functions and classes for traversing abstract syntax trees:" -msgstr "" -"除了節點類別之外，:mod:`ast` 模組還定義了這些用於遍歷 (traverse) 抽象語法樹的" -"實用函式和類別：" - -#: ../../library/ast.rst:2228 -msgid "" -"Parse the source into an AST node. Equivalent to ``compile(source, " -"filename, mode, flags=FLAGS_VALUE, optimize=optimize)``, where " -"``FLAGS_VALUE`` is ``ast.PyCF_ONLY_AST`` if ``optimize <= 0`` and ``ast." -"PyCF_OPTIMIZED_AST`` otherwise." -msgstr "" -"將原始碼剖析為 AST 節點，相當於 ``compile(source, filename, mode, " -"flags=FLAGS_VALUE, optimize=optimize)``，其中 ``FLAGS_VALUE`` 在 ``optimize " -"<= 0`` 時為 ``ast.PyCF_ONLY_AST``，否則為 ``ast.PyCF_OPTIMIZED_AST``。" - -#: ../../library/ast.rst:2233 -msgid "" -"If ``type_comments=True`` is given, the parser is modified to check and " -"return type comments as specified by :pep:`484` and :pep:`526`. This is " -"equivalent to adding :data:`ast.PyCF_TYPE_COMMENTS` to the flags passed to :" -"func:`compile`. This will report syntax errors for misplaced type " -"comments. Without this flag, type comments will be ignored, and the " -"``type_comment`` field on selected AST nodes will always be ``None``. In " -"addition, the locations of ``# type: ignore`` comments will be returned as " -"the ``type_ignores`` attribute of :class:`Module` (otherwise it is always an " -"empty list)." -msgstr "" -"如果給定 ``type_comments=True``，剖析器將被修改為檢查並回傳 :pep:`484` 和 :" -"pep:`526` 指定的型別註釋。這相當於將 :data:`ast.PyCF_TYPE_COMMENTS` 新增到傳" -"遞給 :func:`compile` 的旗標中。這將報告錯誤型別註釋的語法錯誤。如果沒有此旗" -"標，型別註釋將被忽略，並且所選 AST 節點上的 ``type_comment`` 欄位將始終為 " -"``None``。此外，``# type: ignore`` 註釋的位置將作為 :class:`Module` 的 " -"``type_ignores`` 屬性回傳（否則它始終是一個空串列）。" - -#: ../../library/ast.rst:2243 -msgid "" -"In addition, if ``mode`` is ``'func_type'``, the input syntax is modified to " -"correspond to :pep:`484` \"signature type comments\", e.g. ``(str, int) -> " -"List[str]``." -msgstr "" -"此外，如果 ``mode`` 是 ``'func_type'``，則輸入語法將會依據 :pep:`484`\\ 「簽" -"名型別註解 (signature type comments)」而被修改，例如 ``(str, int) -> " -"List[str]``。" - -#: ../../library/ast.rst:2247 -msgid "" -"Setting ``feature_version`` to a tuple ``(major, minor)`` will result in a " -"\"best-effort\" attempt to parse using that Python version's grammar. For " -"example, setting ``feature_version=(3, 9)`` will attempt to disallow parsing " -"of :keyword:`match` statements. Currently ``major`` must equal to ``3``. The " -"lowest supported version is ``(3, 7)`` (and this may increase in future " -"Python versions); the highest is ``sys.version_info[0:2]``. \"Best-effort\" " -"attempt means there is no guarantee that the parse (or success of the parse) " -"is the same as when run on the Python version corresponding to " -"``feature_version``." -msgstr "" -"將 ``feature_version`` 設定為元組 ``(major, minor)`` 將「盡可能」嘗試使用該 " -"Python 版本的文法進行剖析。目前 ``major`` 必須等於 ``3``。例如，設定 " -"``feature_version=(3, 9)`` 將嘗試禁止剖析 :keyword:`match` 陳述式。目前 " -"``major`` 必須為 ``3``、支援的最低版本為 ``(3, 7)``\\ （這在未來的 Python 版" -"本中可能會增加）；最高的是 ``sys.version_info[0:2]``。「盡可能」嘗試意味著不" -"能保證剖析（或剖析的成功）與在與 ``feature_version`` 對應的 Python 版本上運行" -"時相同。" - -#: ../../library/ast.rst:2257 -msgid "" -"If source contains a null character (``\\0``), :exc:`ValueError` is raised." -msgstr "如果來源包含 null 字元 (``\\0``)，則會引發 :exc:`ValueError`。" - -#: ../../library/ast.rst:2260 -msgid "" -"Note that successfully parsing source code into an AST object doesn't " -"guarantee that the source code provided is valid Python code that can be " -"executed as the compilation step can raise further :exc:`SyntaxError` " -"exceptions. For instance, the source ``return 42`` generates a valid AST " -"node for a return statement, but it cannot be compiled alone (it needs to be " -"inside a function node)." -msgstr "" -"請注意，成功將原始碼剖析為 AST 物件並不能保證提供的原始碼是可以執行的有效 " -"Python 程式碼，因為編譯步驟可能會引發進一步的 :exc:`SyntaxError` 例外。例如，" -"原始的 ``return 42`` 為 return 陳述式生成一個有效的 AST 節點，但它不能單獨編" -"譯（它需要位於函式節點內）。" - -#: ../../library/ast.rst:2267 -msgid "" -"In particular, :func:`ast.parse` won't do any scoping checks, which the " -"compilation step does." -msgstr "" -"特別是 :func:`ast.parse` 不會執行任何範圍檢查，而編譯步驟才會執行此操作。" - -#: ../../library/ast.rst:2271 -msgid "" -"It is possible to crash the Python interpreter with a sufficiently large/" -"complex string due to stack depth limitations in Python's AST compiler." -msgstr "" -"由於 Python AST 編譯器中的堆疊 (stack) 深度限制，太大或太複雜的字串可能會導" -"致 Python 直譯器崩潰。" - -#: ../../library/ast.rst:2275 -msgid "Added ``type_comments``, ``mode='func_type'`` and ``feature_version``." -msgstr "新增 ``type_comments``、``mode='func_type'`` 與 ``feature_version``。" - -#: ../../library/ast.rst:2278 -msgid "" -"The minimum supported version for ``feature_version`` is now ``(3, 7)``. The " -"``optimize`` argument was added." -msgstr "" -"``feature_version`` 的最低支援版本現在是 ``(3, 7)``。新增了 ``optimize`` 引" -"數。" - -#: ../../library/ast.rst:2285 -msgid "" -"Unparse an :class:`ast.AST` object and generate a string with code that " -"would produce an equivalent :class:`ast.AST` object if parsed back with :" -"func:`ast.parse`." -msgstr "" -"反剖析 :class:`ast.AST` 物件並生成一個帶有程式碼的字串，如果使用 :func:`ast." -"parse` 剖析回來，該程式碼將生成等效的 :class:`ast.AST` 物件。" - -#: ../../library/ast.rst:2290 -msgid "" -"The produced code string will not necessarily be equal to the original code " -"that generated the :class:`ast.AST` object (without any compiler " -"optimizations, such as constant tuples/frozensets)." -msgstr "" -"生成的程式碼字串不一定等於生成 :class:`ast.AST` 物件的原始程式碼（沒有任何編" -"譯器最佳化，例如常數元組/凍結集合）。" - -#: ../../library/ast.rst:2295 -msgid "" -"Trying to unparse a highly complex expression would result with :exc:" -"`RecursionError`." -msgstr "嘗試剖析高度複雜的運算式會導致 :exc:`RecursionError`。" - -#: ../../library/ast.rst:2303 -msgid "" -"Evaluate an expression node or a string containing only a Python literal or " -"container display. The string or node provided may only consist of the " -"following Python literal structures: strings, bytes, numbers, tuples, lists, " -"dicts, sets, booleans, ``None`` and ``Ellipsis``." -msgstr "" -"為僅包含 Python 文本或容器之顯示的運算式節點或字串來求值。提供的字串或節點只" -"能包含以下 Python 文本結構：字串、位元組、數字、元組、串列、字典、集合、布林" -"值、``None`` 和 ``Ellipsis``。" - -#: ../../library/ast.rst:2308 -msgid "" -"This can be used for evaluating strings containing Python values without the " -"need to parse the values oneself. It is not capable of evaluating " -"arbitrarily complex expressions, for example involving operators or indexing." -msgstr "" -"這可用於為包含 Python 值的字串求值，而無需自己剖析這些值。它無法計算任意複雜" -"的運算式，例如涉及運算子或索引。" - -#: ../../library/ast.rst:2313 -msgid "" -"This function had been documented as \"safe\" in the past without defining " -"what that meant. That was misleading. This is specifically designed not to " -"execute Python code, unlike the more general :func:`eval`. There is no " -"namespace, no name lookups, or ability to call out. But it is not free from " -"attack: A relatively small input can lead to memory exhaustion or to C stack " -"exhaustion, crashing the process. There is also the possibility for " -"excessive CPU consumption denial of service on some inputs. Calling it on " -"untrusted data is thus not recommended." -msgstr "" -"該函式過去被記錄為「安全」，但沒有定義其含義，這有點誤導讀者，它是特別設計為" -"不去執行 Python 程式碼，與更通用的 :func:`eval` 不同。沒有命名空間、沒有名稱" -"查找、也沒有呼叫的能力。但它也不能免受攻擊：相對較小的輸入可能會導致記憶體耗" -"盡或 C 堆疊耗盡，從而導致行程崩潰。某些輸入也可能會出現 CPU 消耗過多而導致拒" -"絕服務的情況。因此不建議在不受信任的資料上呼叫它。" - -#: ../../library/ast.rst:2323 -msgid "" -"It is possible to crash the Python interpreter due to stack depth " -"limitations in Python's AST compiler." -msgstr "由於 Python AST 編譯器的堆疊深度限制，Python 直譯器可能會崩潰。" - -#: ../../library/ast.rst:2326 -msgid "" -"It can raise :exc:`ValueError`, :exc:`TypeError`, :exc:`SyntaxError`, :exc:" -"`MemoryError` and :exc:`RecursionError` depending on the malformed input." -msgstr "" -"它可能會引發 :exc:`ValueError`、:exc:`TypeError`、:exc:`SyntaxError`、:exc:" -"`MemoryError` 和 :exc:`RecursionError`，具體取決於格式錯誤的輸入。" - -#: ../../library/ast.rst:2330 -msgid "Now allows bytes and set literals." -msgstr "現在允許位元組和集合文本 (set literal)。" - -#: ../../library/ast.rst:2333 -msgid "Now supports creating empty sets with ``'set()'``." -msgstr "現在支援使用 ``'set()'`` 建立空集合。" - -#: ../../library/ast.rst:2336 -msgid "For string inputs, leading spaces and tabs are now stripped." -msgstr "對於字串輸入，前導空格和定位字元 (tab) 現在已被去除。" - -#: ../../library/ast.rst:2342 -msgid "" -"Return the docstring of the given *node* (which must be a :class:" -"`FunctionDef`, :class:`AsyncFunctionDef`, :class:`ClassDef`, or :class:" -"`Module` node), or ``None`` if it has no docstring. If *clean* is true, " -"clean up the docstring's indentation with :func:`inspect.cleandoc`." -msgstr "" -"回傳給定 *node* 的文件字串 (docstring)（必須是 :class:`FunctionDef`、:class:" -"`AsyncFunctionDef`、:class:`ClassDef` 或 :class:`Module` 節點）或如果它沒有文" -"件字串則為 ``None``。如果 *clean* 為 true，則使用 :func:`inspect.cleandoc` 清" -"理文件字串的縮排。" - -#: ../../library/ast.rst:2348 -msgid ":class:`AsyncFunctionDef` is now supported." -msgstr "目前已支援 :class:`AsyncFunctionDef`。" - -#: ../../library/ast.rst:2354 -msgid "" -"Get source code segment of the *source* that generated *node*. If some " -"location information (:attr:`~ast.AST.lineno`, :attr:`~ast.AST.end_lineno`, :" -"attr:`~ast.AST.col_offset`, or :attr:`~ast.AST.end_col_offset`) is missing, " -"return ``None``." -msgstr "" -"取得生成 *node* 的 *source* 的原始碼片段。如果某些位置資訊（:attr:`~ast.AST." -"lineno`、:attr:`~ast.AST.end_lineno`、:attr:`~ast.AST.col_offset` 或 :attr:" -"`~ast.AST.end_col_offset`）遺漏，則回傳 ``None``。" - -#: ../../library/ast.rst:2358 -msgid "" -"If *padded* is ``True``, the first line of a multi-line statement will be " -"padded with spaces to match its original position." -msgstr "" -"如果 *padded* 為 ``True``，則多列陳述式的第一列將用空格填充 (padded) 以匹配其" -"原始位置。" - -#: ../../library/ast.rst:2366 -msgid "" -"When you compile a node tree with :func:`compile`, the compiler expects :" -"attr:`~ast.AST.lineno` and :attr:`~ast.AST.col_offset` attributes for every " -"node that supports them. This is rather tedious to fill in for generated " -"nodes, so this helper adds these attributes recursively where not already " -"set, by setting them to the values of the parent node. It works recursively " -"starting at *node*." -msgstr "" -"當你使用 :func:`compile` 編譯節點樹時，對於每個有支援 :attr:`~ast.AST." -"lineno` 和 :attr:`~ast.AST.col_offset` 屬性之節點，編譯器預期他們的這些屬性都" -"要存在。填入生成的節點相當繁瑣，因此該輔助工具透過將這些屬性設定為父節點的" -"值，在尚未設定的地方遞迴地新增這些屬性。它從 *node* 開始遞迴地作用。" - -#: ../../library/ast.rst:2375 -msgid "" -"Increment the line number and end line number of each node in the tree " -"starting at *node* by *n*. This is useful to \"move code\" to a different " -"location in a file." -msgstr "" -"將樹中從 *node* 開始的每個節點的列號和結束列號增加 *n*。這對於「移動程式碼」" -"到檔案中的不同位置很有用。" - -#: ../../library/ast.rst:2382 -msgid "" -"Copy source location (:attr:`~ast.AST.lineno`, :attr:`~ast.AST.col_offset`, :" -"attr:`~ast.AST.end_lineno`, and :attr:`~ast.AST.end_col_offset`) from " -"*old_node* to *new_node* if possible, and return *new_node*." -msgstr "" -"如果可行，將原始位置（:attr:`~ast.AST.lineno`、:attr:`~ast.AST.col_offset`、:" -"attr:`~ast.AST.end_lineno` 和 :attr:`~ast.AST.end_col_offset` ）從 " -"*old_node* 複製到 *new_node*，並回傳 *new_node* 。" - -#: ../../library/ast.rst:2389 -msgid "" -"Yield a tuple of ``(fieldname, value)`` for each field in ``node._fields`` " -"that is present on *node*." -msgstr "" -"為 *node* 上存在的 ``node._fields`` 中的每個欄位生成一個 ``(fieldname, " -"value)`` 元組。" - -#: ../../library/ast.rst:2395 -msgid "" -"Yield all direct child nodes of *node*, that is, all fields that are nodes " -"and all items of fields that are lists of nodes." -msgstr "" -"生成 *node* 的所有直接子節點，即作為節點的所有欄位以及作為節點串列欄位的所有" -"項目。" - -#: ../../library/ast.rst:2401 -msgid "" -"Recursively yield all descendant nodes in the tree starting at *node* " -"(including *node* itself), in no specified order. This is useful if you " -"only want to modify nodes in place and don't care about the context." -msgstr "" -"遞迴地生成樹中從 *node* 開始的所有後代節點（包括 *node* 本身），不按指定順" -"序。如果你只想就地修改節點而不關心情境，這非常有用。" - -#: ../../library/ast.rst:2408 -msgid "" -"A node visitor base class that walks the abstract syntax tree and calls a " -"visitor function for every node found. This function may return a value " -"which is forwarded by the :meth:`visit` method." -msgstr "" -"節點瀏覽者基底類別，它遍歷抽象語法樹並為找到的每個節點呼叫瀏覽者函式。該函式" -"可能會回傳一個由 :meth:`visit` 方法轉發的值。" - -#: ../../library/ast.rst:2412 -msgid "" -"This class is meant to be subclassed, with the subclass adding visitor " -"methods." -msgstr "這個類別應該被子類別化，子類別新增瀏覽者方法。" - -#: ../../library/ast.rst:2417 -msgid "" -"Visit a node. The default implementation calls the method called :samp:" -"`self.visit_{classname}` where *classname* is the name of the node class, " -"or :meth:`generic_visit` if that method doesn't exist." -msgstr "" -"瀏覽一個節點。預設實作呼叫名為 :samp:`self.visit_{classname}` 的方法，其中 " -"*classname* 是節點類別的名稱，或者在該方法不存在時呼叫 :meth:" -"`generic_visit`。" - -#: ../../library/ast.rst:2423 -msgid "This visitor calls :meth:`visit` on all children of the node." -msgstr "該瀏覽者對該節點的所有子節點呼叫 :meth:`visit`。" - -#: ../../library/ast.rst:2425 -msgid "" -"Note that child nodes of nodes that have a custom visitor method won't be " -"visited unless the visitor calls :meth:`generic_visit` or visits them itself." -msgstr "" -"請注意，除非瀏覽者呼叫 :meth:`generic_visit` 或瀏覽它們本身，否則不會瀏覽具有" -"自訂瀏覽者方法的節點之子節點。" - -#: ../../library/ast.rst:2431 -msgid "Handles all constant nodes." -msgstr "處理所有常數節點。" - -#: ../../library/ast.rst:2433 -msgid "" -"Don't use the :class:`NodeVisitor` if you want to apply changes to nodes " -"during traversal. For this a special visitor exists (:class:" -"`NodeTransformer`) that allows modifications." -msgstr "" -"如果你想在遍歷期間將變更應用 (apply) 於節點，請不要使用 :class:" -"`NodeVisitor`。為此，有個允許修改的特殊遍歷瀏覽者工具 :class:" -"`NodeTransformer`。" - -#: ../../library/ast.rst:2439 -msgid "" -"Methods :meth:`!visit_Num`, :meth:`!visit_Str`, :meth:`!visit_Bytes`, :meth:" -"`!visit_NameConstant` and :meth:`!visit_Ellipsis` will not be called in " -"Python 3.14+. Add the :meth:`visit_Constant` method instead to handle all " -"constant nodes." -msgstr "" -":meth:`!visit_Num`、:meth:`!visit_Str`、:meth:`!visit_Bytes`、:meth:`!" -"visit_NameConstant` 和 :meth:`!visit_Ellipsis` 方法在 Python 3.14+ 中將不會被" -"呼叫。請改為新增 :meth:`visit_Constant` 方法來處理所有常數節點。" - -#: ../../library/ast.rst:2447 -msgid "" -"A :class:`NodeVisitor` subclass that walks the abstract syntax tree and " -"allows modification of nodes." -msgstr "一個 :class:`NodeVisitor` 子類別，它會遍歷抽象語法樹並允許修改節點。" - -#: ../../library/ast.rst:2450 -msgid "" -"The :class:`NodeTransformer` will walk the AST and use the return value of " -"the visitor methods to replace or remove the old node. If the return value " -"of the visitor method is ``None``, the node will be removed from its " -"location, otherwise it is replaced with the return value. The return value " -"may be the original node in which case no replacement takes place." -msgstr "" -":class:`NodeTransformer` 將遍歷 AST 並使用瀏覽者方法的回傳值來替換或刪除舊節" -"點。如果瀏覽者方法的回傳值為 ``None``，則該節點將從其位置中刪除，否則將被替換" -"為回傳值。回傳值可能是原始節點，在這種情況下不會發生替換。" - -#: ../../library/ast.rst:2456 -msgid "" -"Here is an example transformer that rewrites all occurrences of name lookups " -"(``foo``) to ``data['foo']``::" -msgstr "" -"下面是一個示範用的 transformer，它將查找所有出現名稱 (``foo``) 並改寫為 " -"``data['foo']``： ::" - -#: ../../library/ast.rst:2459 -msgid "" -"class RewriteName(NodeTransformer):\n" -"\n" -" def visit_Name(self, node):\n" -" return Subscript(\n" -" value=Name(id='data', ctx=Load()),\n" -" slice=Constant(value=node.id),\n" -" ctx=node.ctx\n" -" )" -msgstr "" -"class RewriteName(NodeTransformer):\n" -"\n" -" def visit_Name(self, node):\n" -" return Subscript(\n" -" value=Name(id='data', ctx=Load()),\n" -" slice=Constant(value=node.id),\n" -" ctx=node.ctx\n" -" )" - -#: ../../library/ast.rst:2468 -msgid "" -"Keep in mind that if the node you're operating on has child nodes you must " -"either transform the child nodes yourself or call the :meth:`~ast." -"NodeVisitor.generic_visit` method for the node first." -msgstr "" -"請記住，如果你正在操作的節點有子節點，你必須自己轉換子節點或先呼叫該節點的 :" -"meth:`~ast.NodeVisitor.generic_visit` 方法。" - -#: ../../library/ast.rst:2472 -msgid "" -"For nodes that were part of a collection of statements (that applies to all " -"statement nodes), the visitor may also return a list of nodes rather than " -"just a single node." -msgstr "" -"對於屬於陳述式總集 (collection) 一部分的節點（適用於所有陳述式節點），瀏覽者" -"還可以回傳節點串列，而不僅僅是單個節點。" - -#: ../../library/ast.rst:2476 -msgid "" -"If :class:`NodeTransformer` introduces new nodes (that weren't part of " -"original tree) without giving them location information (such as :attr:`~ast." -"AST.lineno`), :func:`fix_missing_locations` should be called with the new " -"sub-tree to recalculate the location information::" -msgstr "" -"如果 :class:`NodeTransformer` 引進了新節點（不屬於原始樹的一部分），但沒有給" -"它們提供位置資訊（例如 :attr:`~ast.AST.lineno`），則應使用新的子樹呼叫 :func:" -"`fix_missing_locations` 以重新計算位置資訊： ::" - -#: ../../library/ast.rst:2481 -msgid "" -"tree = ast.parse('foo', mode='eval')\n" -"new_tree = fix_missing_locations(RewriteName().visit(tree))" -msgstr "" -"tree = ast.parse('foo', mode='eval')\n" -"new_tree = fix_missing_locations(RewriteName().visit(tree))" - -#: ../../library/ast.rst:2484 -msgid "Usually you use the transformer like this::" -msgstr "你通常會像這樣使用 transformer： ::" - -#: ../../library/ast.rst:2486 -msgid "node = YourTransformer().visit(node)" -msgstr "node = YourTransformer().visit(node)" - -#: ../../library/ast.rst:2491 -msgid "" -"Return a formatted dump of the tree in *node*. This is mainly useful for " -"debugging purposes. If *annotate_fields* is true (by default), the returned " -"string will show the names and the values for fields. If *annotate_fields* " -"is false, the result string will be more compact by omitting unambiguous " -"field names. Attributes such as line numbers and column offsets are not " -"dumped by default. If this is wanted, *include_attributes* can be set to " -"true." -msgstr "" -"回傳 *node* 中樹的格式化傾印 (formatted dump)，這主要用於除錯。如果 " -"*annotate_fields* 為 true（為預設值），則回傳的字串將顯示欄位的名稱和值。如" -"果 *annotate_fields* 為 false，則透過省略明確的欄位名稱，結果字串將更加縮減簡" -"潔。預設情況下，不會傾印列號和行偏移量等屬性。如果需要，可以設定 " -"*include_attributes* 為 true。" - -#: ../../library/ast.rst:2499 -msgid "" -"If *indent* is a non-negative integer or string, then the tree will be " -"pretty-printed with that indent level. An indent level of 0, negative, or " -"``\"\"`` will only insert newlines. ``None`` (the default) selects the " -"single line representation. Using a positive integer indent indents that " -"many spaces per level. If *indent* is a string (such as ``\"\\t\"``), that " -"string is used to indent each level." -msgstr "" -"如果 *indent* 是非負整數或字串，那麼樹將使用該縮排級別來做漂亮印出 (pretty-" -"print)。縮排級別 0、負數或 ``\"\"`` 只會插入換列符號 (newlines)。``None``\\ " -"（預設值）代表選擇單列表示。使用正整數縮排可以在每個級別縮排相同數量的空格。" -"如果 *indent* 是一個字串（例如 ``\"\\t\"``），則該字串用於縮排每個級別。" - -#: ../../library/ast.rst:2506 -msgid "" -"If *show_empty* is false (the default), optional empty lists will be omitted " -"from the output. Optional ``None`` values are always omitted." -msgstr "" -"如果 *show_empty* 為 false（預設值），則輸出中將省略可選的空串列。可選的 " -"``None`` 值總是會被省略。" - -#: ../../library/ast.rst:2510 -msgid "Added the *indent* option." -msgstr "新增 *indent* 選項。" - -#: ../../library/ast.rst:2513 -msgid "Added the *show_empty* option." -msgstr "新增 *show_empty* 選項。" - -#: ../../library/ast.rst:2516 -msgid "" -">>> print(ast.dump(ast.parse(\"\"\"\\\n" -"... async def f():\n" -"... await other_func()\n" -"... \"\"\"), indent=4, show_empty=True))\n" -"Module(\n" -" body=[\n" -" AsyncFunctionDef(\n" -" name='f',\n" -" args=arguments(\n" -" posonlyargs=[],\n" -" args=[],\n" -" kwonlyargs=[],\n" -" kw_defaults=[],\n" -" defaults=[]),\n" -" body=[\n" -" Expr(\n" -" value=Await(\n" -" value=Call(\n" -" func=Name(id='other_func', ctx=Load()),\n" -" args=[],\n" -" keywords=[])))],\n" -" decorator_list=[],\n" -" type_params=[])],\n" -" type_ignores=[])" -msgstr "" -">>> print(ast.dump(ast.parse(\"\"\"\\\n" -"... async def f():\n" -"... await other_func()\n" -"... \"\"\"), indent=4, show_empty=True))\n" -"Module(\n" -" body=[\n" -" AsyncFunctionDef(\n" -" name='f',\n" -" args=arguments(\n" -" posonlyargs=[],\n" -" args=[],\n" -" kwonlyargs=[],\n" -" kw_defaults=[],\n" -" defaults=[]),\n" -" body=[\n" -" Expr(\n" -" value=Await(\n" -" value=Call(\n" -" func=Name(id='other_func', ctx=Load()),\n" -" args=[],\n" -" keywords=[])))],\n" -" decorator_list=[],\n" -" type_params=[])],\n" -" type_ignores=[])" - -#: ../../library/ast.rst:2547 -msgid "Compiler flags" -msgstr "編譯器旗標" - -#: ../../library/ast.rst:2549 -msgid "" -"The following flags may be passed to :func:`compile` in order to change " -"effects on the compilation of a program:" -msgstr "可以將以下旗標傳遞給 :func:`compile` 以變更對程式的編譯效果：" - -#: ../../library/ast.rst:2554 -msgid "" -"Enables support for top-level ``await``, ``async for``, ``async with`` and " -"async comprehensions." -msgstr "" -"啟用對最高階 ``await``、``async for``、``async with`` 和非同步綜合運算的支" -"援。" - -#: ../../library/ast.rst:2561 -msgid "" -"Generates and returns an abstract syntax tree instead of returning a " -"compiled code object." -msgstr "生成並回傳抽象語法樹，而不是回傳已編譯的程式碼物件。" - -#: ../../library/ast.rst:2566 -msgid "" -"The returned AST is optimized according to the *optimize* argument in :func:" -"`compile` or :func:`ast.parse`." -msgstr "" -"回傳的 AST 會根據 :func:`compile` 或 :func:`ast.parse` 中的 *optimize* 引數進" -"行最佳化。" - -#: ../../library/ast.rst:2573 -msgid "" -"Enables support for :pep:`484` and :pep:`526` style type comments (``# type: " -"``, ``# type: ignore ``)." -msgstr "" -"啟用對 :pep:`484` 和 :pep:`526` 樣式型別註釋的支援 (``# type: ``, ``# " -"type: ignore ``)。" - -#: ../../library/ast.rst:2581 -msgid "Recursively compares two ASTs." -msgstr "遞迴比較兩個 AST。" - -#: ../../library/ast.rst:2583 -msgid "" -"*compare_attributes* affects whether AST attributes are considered in the " -"comparison. If *compare_attributes* is ``False`` (default), then attributes " -"are ignored. Otherwise they must all be equal. This option is useful to " -"check whether the ASTs are structurally equal but differ in whitespace or " -"similar details. Attributes include line numbers and column offsets." -msgstr "" -"*compare_attributes* 會影響比較時是否考慮 AST 屬性。如果 *compare_attributes* " -"為 ``False``\\ （預設值），則忽略屬性。否則所有屬性都必須相等。此選項用於檢查 " -"AST 在結構上是否相等，但在空白或類似細節上有所不同。屬性包括列號和行偏移量。" - -#: ../../library/ast.rst:2596 -msgid "Command-line usage" -msgstr "命令列用法" - -#: ../../library/ast.rst:2600 -msgid "" -"The :mod:`ast` module can be executed as a script from the command line. It " -"is as simple as:" -msgstr ":mod:`ast` 模組可以作為腳本從命令列執行，可以像這樣簡單地做到：" - -#: ../../library/ast.rst:2603 -msgid "python -m ast [-m ] [-a] [infile]" -msgstr "python -m ast [-m ] [-a] [infile]" - -#: ../../library/ast.rst:2607 -msgid "The following options are accepted:" -msgstr "以下選項可被接受：" - -#: ../../library/ast.rst:2613 -msgid "Show the help message and exit." -msgstr "顯示幫助訊息並退出。" - -#: ../../library/ast.rst:2618 -msgid "" -"Specify what kind of code must be compiled, like the *mode* argument in :" -"func:`parse`." -msgstr "指定必須編譯哪種類型的程式碼，像是 :func:`parse` 中的 *mode* 引數。" - -#: ../../library/ast.rst:2623 -msgid "Don't parse type comments." -msgstr "不要剖析型別註解。" - -#: ../../library/ast.rst:2627 -msgid "Include attributes such as line numbers and column offsets." -msgstr "包括列號和行偏移量等屬性。" - -#: ../../library/ast.rst:2632 -msgid "Indentation of nodes in AST (number of spaces)." -msgstr "AST 中節點的縮進（空格數）。" - -#: ../../library/ast.rst:2636 -msgid "" -"Python version in the format 3.x (for example, 3.10). Defaults to the " -"current version of the interpreter." -msgstr "以 3.x 格式表示的 Python 版本（例如 3.10）。預設為直譯器的目前版本。" - -#: ../../library/ast.rst:2644 -msgid "Optimization level for parser. Defaults to no optimization." -msgstr "剖析器的最佳化層級。預設為不進行最佳化。" - -#: ../../library/ast.rst:2650 -msgid "" -"Show empty lists and fields that are ``None``. Defaults to not showing empty " -"objects." -msgstr "顯示空串列和值為 ``None`` 的欄位。預設為不顯示空物件。" - -#: ../../library/ast.rst:2656 -msgid "" -"If :file:`infile` is specified its contents are parsed to AST and dumped to " -"stdout. Otherwise, the content is read from stdin." -msgstr "" -"如果指定了 :file:`infile`，則其內容將被剖析為 AST 並傾印 (dump) 到 stdout。否" -"則會從 stdin 讀取內容。" - -#: ../../library/ast.rst:2662 -msgid "" -"`Green Tree Snakes `_, an external " -"documentation resource, has good details on working with Python ASTs." -msgstr "" -"`Green Tree Snakes `_ 是一個外部文件" -"資源，提供了有關使用 Python AST 的詳細資訊。" - -#: ../../library/ast.rst:2665 -msgid "" -"`ASTTokens `_ " -"annotates Python ASTs with the positions of tokens and text in the source " -"code that generated them. This is helpful for tools that make source code " -"transformations." -msgstr "" -"`ASTTokens `_ 使" -"用生成它們的原始碼中的標記和文本的位置來註釋 Python AST。這對於進行原始碼轉換" -"的工具很有幫助。" - -#: ../../library/ast.rst:2670 -msgid "" -"`leoAst.py `_ unifies the token-based and parse-tree-based views of python programs " -"by inserting two-way links between tokens and ast nodes." -msgstr "" -"`leoAst.py `_ 透過在 token 和 ast 節點之間插入雙向鏈結，統一了 python 程式的基於 " -"token 和基於剖析樹的視圖。" - -#: ../../library/ast.rst:2675 -msgid "" -"`LibCST `_ parses code as a Concrete Syntax " -"Tree that looks like an ast tree and keeps all formatting details. It's " -"useful for building automated refactoring (codemod) applications and linters." -msgstr "" -"`LibCST `_ 將程式碼剖析為具體語法樹 " -"(Concrete Syntax Tree)，看起來像 ast 樹並保留所有格式詳細資訊。它對於建置自動" -"重構 (codemod) 應用程式和 linter 非常有用。" - -#: ../../library/ast.rst:2680 -msgid "" -"`Parso `_ is a Python parser that supports " -"error recovery and round-trip parsing for different Python versions (in " -"multiple Python versions). Parso is also able to list multiple syntax errors " -"in your Python file." -msgstr "" -"`Parso `_ 是一個 Python 剖析器，支援不同 " -"Python 版本的錯誤復原和往返剖析。Parso 還能夠列出 Python 檔案中的多個語法錯" -"誤。" - -#: ../../library/ast.rst:59 -msgid "? (question mark)" -msgstr "? （問號）" - -#: ../../library/ast.rst:59 ../../library/ast.rst:60 -msgid "in AST grammar" -msgstr "於 AST 文法中" - -#: ../../library/ast.rst:60 -msgid "* (asterisk)" -msgstr "* （星號）" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-12-30 00:15+0000\n" +"PO-Revision-Date: 2018-05-23 14:38+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/ast.rst:2 +msgid ":mod:`!ast` --- Abstract syntax trees" +msgstr ":mod:`!ast` --- 抽象語法樹 (Abstract Syntax Trees)" + +#: ../../library/ast.rst:14 +msgid "**Source code:** :source:`Lib/ast.py`" +msgstr "**原始碼：**\\ :source:`Lib/ast.py`" + +#: ../../library/ast.rst:18 +msgid "" +"The :mod:`ast` module helps Python applications to process trees of the " +"Python abstract syntax grammar. The abstract syntax itself might change " +"with each Python release; this module helps to find out programmatically " +"what the current grammar looks like." +msgstr "" +":mod:`ast` 模組可以幫助 Python 應用程式處理 Python 抽象語法文法 (abstract " +"syntax grammar) 樹狀資料結構。抽象語法本身可能會隨著每個 Python 版本發布而改" +"變；此模組有助於以程式化的方式來得知目前文法的面貌。" + +#: ../../library/ast.rst:23 +msgid "" +"An abstract syntax tree can be generated by passing :data:`ast." +"PyCF_ONLY_AST` as a flag to the :func:`compile` built-in function, or using " +"the :func:`parse` helper provided in this module. The result will be a tree " +"of objects whose classes all inherit from :class:`ast.AST`. An abstract " +"syntax tree can be compiled into a Python code object using the built-in :" +"func:`compile` function." +msgstr "" +"要生成抽象語法樹，可以透過將 :data:`ast.PyCF_ONLY_AST` 作為旗標傳遞給內建函" +"式 :func:`compile` 或使用此模組所提供的 :func:`parse` 輔助函式。結果將會是一" +"個物件的樹，其類別都繼承自 :class:`ast.AST`。可以使用內建的 :func:`compile` " +"函式將抽象語法樹編譯成 Python 程式碼物件。" + +#: ../../library/ast.rst:33 +msgid "Abstract grammar" +msgstr "抽象文法 (Abstract Grammar)" + +#: ../../library/ast.rst:35 +msgid "The abstract grammar is currently defined as follows:" +msgstr "抽象文法目前定義如下：" + +#: ../../library/ast.rst:37 +msgid "" +"-- ASDL's 4 builtin types are:\n" +"-- identifier, int, string, constant\n" +"\n" +"module Python\n" +"{\n" +" mod = Module(stmt* body, type_ignore* type_ignores)\n" +" | Interactive(stmt* body)\n" +" | Expression(expr body)\n" +" | FunctionType(expr* argtypes, expr returns)\n" +"\n" +" stmt = FunctionDef(identifier name, arguments args,\n" +" stmt* body, expr* decorator_list, expr? returns,\n" +" string? type_comment, type_param* type_params)\n" +" | AsyncFunctionDef(identifier name, arguments args,\n" +" stmt* body, expr* decorator_list, expr? " +"returns,\n" +" string? type_comment, type_param* type_params)\n" +"\n" +" | ClassDef(identifier name,\n" +" expr* bases,\n" +" keyword* keywords,\n" +" stmt* body,\n" +" expr* decorator_list,\n" +" type_param* type_params)\n" +" | Return(expr? value)\n" +"\n" +" | Delete(expr* targets)\n" +" | Assign(expr* targets, expr value, string? type_comment)\n" +" | TypeAlias(expr name, type_param* type_params, expr value)\n" +" | AugAssign(expr target, operator op, expr value)\n" +" -- 'simple' indicates that we annotate simple name without parens\n" +" | AnnAssign(expr target, expr annotation, expr? value, int " +"simple)\n" +"\n" +" -- use 'orelse' because else is a keyword in target languages\n" +" | For(expr target, expr iter, stmt* body, stmt* orelse, string? " +"type_comment)\n" +" | AsyncFor(expr target, expr iter, stmt* body, stmt* orelse, " +"string? type_comment)\n" +" | While(expr test, stmt* body, stmt* orelse)\n" +" | If(expr test, stmt* body, stmt* orelse)\n" +" | With(withitem* items, stmt* body, string? type_comment)\n" +" | AsyncWith(withitem* items, stmt* body, string? type_comment)\n" +"\n" +" | Match(expr subject, match_case* cases)\n" +"\n" +" | Raise(expr? exc, expr? cause)\n" +" | Try(stmt* body, excepthandler* handlers, stmt* orelse, stmt* " +"finalbody)\n" +" | TryStar(stmt* body, excepthandler* handlers, stmt* orelse, stmt* " +"finalbody)\n" +" | Assert(expr test, expr? msg)\n" +"\n" +" | Import(alias* names)\n" +" | ImportFrom(identifier? module, alias* names, int? level)\n" +"\n" +" | Global(identifier* names)\n" +" | Nonlocal(identifier* names)\n" +" | Expr(expr value)\n" +" | Pass | Break | Continue\n" +"\n" +" -- col_offset is the byte offset in the utf8 string the parser " +"uses\n" +" attributes (int lineno, int col_offset, int? end_lineno, int? " +"end_col_offset)\n" +"\n" +" -- BoolOp() can use left & right?\n" +" expr = BoolOp(boolop op, expr* values)\n" +" | NamedExpr(expr target, expr value)\n" +" | BinOp(expr left, operator op, expr right)\n" +" | UnaryOp(unaryop op, expr operand)\n" +" | Lambda(arguments args, expr body)\n" +" | IfExp(expr test, expr body, expr orelse)\n" +" | Dict(expr?* keys, expr* values)\n" +" | Set(expr* elts)\n" +" | ListComp(expr elt, comprehension* generators)\n" +" | SetComp(expr elt, comprehension* generators)\n" +" | DictComp(expr key, expr value, comprehension* generators)\n" +" | GeneratorExp(expr elt, comprehension* generators)\n" +" -- the grammar constrains where yield expressions can occur\n" +" | Await(expr value)\n" +" | Yield(expr? value)\n" +" | YieldFrom(expr value)\n" +" -- need sequences for compare to distinguish between\n" +" -- x < 4 < 3 and (x < 4) < 3\n" +" | Compare(expr left, cmpop* ops, expr* comparators)\n" +" | Call(expr func, expr* args, keyword* keywords)\n" +" | FormattedValue(expr value, int conversion, expr? format_spec)\n" +" | Interpolation(expr value, constant str, int conversion, expr? " +"format_spec)\n" +" | JoinedStr(expr* values)\n" +" | TemplateStr(expr* values)\n" +" | Constant(constant value, string? kind)\n" +"\n" +" -- the following expression can appear in assignment context\n" +" | Attribute(expr value, identifier attr, expr_context ctx)\n" +" | Subscript(expr value, expr slice, expr_context ctx)\n" +" | Starred(expr value, expr_context ctx)\n" +" | Name(identifier id, expr_context ctx)\n" +" | List(expr* elts, expr_context ctx)\n" +" | Tuple(expr* elts, expr_context ctx)\n" +"\n" +" -- can appear only in Subscript\n" +" | Slice(expr? lower, expr? upper, expr? step)\n" +"\n" +" -- col_offset is the byte offset in the utf8 string the parser " +"uses\n" +" attributes (int lineno, int col_offset, int? end_lineno, int? " +"end_col_offset)\n" +"\n" +" expr_context = Load | Store | Del\n" +"\n" +" boolop = And | Or\n" +"\n" +" operator = Add | Sub | Mult | MatMult | Div | Mod | Pow | LShift\n" +" | RShift | BitOr | BitXor | BitAnd | FloorDiv\n" +"\n" +" unaryop = Invert | Not | UAdd | USub\n" +"\n" +" cmpop = Eq | NotEq | Lt | LtE | Gt | GtE | Is | IsNot | In | NotIn\n" +"\n" +" comprehension = (expr target, expr iter, expr* ifs, int is_async)\n" +"\n" +" excepthandler = ExceptHandler(expr? type, identifier? name, stmt* body)\n" +" attributes (int lineno, int col_offset, int? end_lineno, " +"int? end_col_offset)\n" +"\n" +" arguments = (arg* posonlyargs, arg* args, arg? vararg, arg* kwonlyargs,\n" +" expr?* kw_defaults, arg? kwarg, expr* defaults)\n" +"\n" +" arg = (identifier arg, expr? annotation, string? type_comment)\n" +" attributes (int lineno, int col_offset, int? end_lineno, int? " +"end_col_offset)\n" +"\n" +" -- keyword arguments supplied to call (NULL identifier for **kwargs)\n" +" keyword = (identifier? arg, expr value)\n" +" attributes (int lineno, int col_offset, int? end_lineno, int? " +"end_col_offset)\n" +"\n" +" -- import name with optional 'as' alias.\n" +" alias = (identifier name, identifier? asname)\n" +" attributes (int lineno, int col_offset, int? end_lineno, int? " +"end_col_offset)\n" +"\n" +" withitem = (expr context_expr, expr? optional_vars)\n" +"\n" +" match_case = (pattern pattern, expr? guard, stmt* body)\n" +"\n" +" pattern = MatchValue(expr value)\n" +" | MatchSingleton(constant value)\n" +" | MatchSequence(pattern* patterns)\n" +" | MatchMapping(expr* keys, pattern* patterns, identifier? rest)\n" +" | MatchClass(expr cls, pattern* patterns, identifier* kwd_attrs, " +"pattern* kwd_patterns)\n" +"\n" +" | MatchStar(identifier? name)\n" +" -- The optional \"rest\" MatchMapping parameter handles " +"capturing extra mapping keys\n" +"\n" +" | MatchAs(pattern? pattern, identifier? name)\n" +" | MatchOr(pattern* patterns)\n" +"\n" +" attributes (int lineno, int col_offset, int end_lineno, int " +"end_col_offset)\n" +"\n" +" type_ignore = TypeIgnore(int lineno, string tag)\n" +"\n" +" type_param = TypeVar(identifier name, expr? bound, expr? default_value)\n" +" | ParamSpec(identifier name, expr? default_value)\n" +" | TypeVarTuple(identifier name, expr? default_value)\n" +" attributes (int lineno, int col_offset, int end_lineno, int " +"end_col_offset)\n" +"}\n" +msgstr "" + +#: ../../library/ast.rst:42 +msgid "Node classes" +msgstr "節點 (Node) 類別" + +#: ../../library/ast.rst:46 +msgid "" +"This is the base of all AST node classes. The actual node classes are " +"derived from the :file:`Parser/Python.asdl` file, which is reproduced :ref:" +"`above `. They are defined in the :mod:`!_ast` C module " +"and re-exported in :mod:`ast`." +msgstr "" +"這是所有 AST 節點類別的基礎。實際的節點類別是衍生自 :file:`Parser/Python." +"asdl` 檔案，該檔案在\\ :ref:`上方 ` 重現。它們被定義於 :" +"mod:`!_ast` 的 C 模組中，並於 :mod:`ast` 中重新匯出。" + +#: ../../library/ast.rst:51 +msgid "" +"There is one class defined for each left-hand side symbol in the abstract " +"grammar (for example, :class:`ast.stmt` or :class:`ast.expr`). In addition, " +"there is one class defined for each constructor on the right-hand side; " +"these classes inherit from the classes for the left-hand side trees. For " +"example, :class:`ast.BinOp` inherits from :class:`ast.expr`. For production " +"rules with alternatives (aka \"sums\"), the left-hand side class is " +"abstract: only instances of specific constructor nodes are ever created." +msgstr "" +"抽象文法中為每個左側符號定義了一個類別（例如 :class:`ast.stmt` 或 :class:" +"`ast.expr`）。此外，也為每個右側的建構函式 (constructor) 定義了一個類別；這些" +"類別繼承自左側樹的類別。例如，:class:`ast.BinOp` 繼承自 :class:`ast.expr`。對" +"於具有替代方案（即為「和 (sums)」）的生產規則，左側類別是抽象的：僅有特定建構" +"函式節點的實例會被建立。" + +#: ../../library/ast.rst:64 +msgid "" +"Each concrete class has an attribute :attr:`!_fields` which gives the names " +"of all child nodes." +msgstr "每個具體類別都有一個屬性 :attr:`!_fields`，它會給出所有子節點的名稱。" + +#: ../../library/ast.rst:67 +msgid "" +"Each instance of a concrete class has one attribute for each child node, of " +"the type as defined in the grammar. For example, :class:`ast.BinOp` " +"instances have an attribute :attr:`left` of type :class:`ast.expr`." +msgstr "" +"具體類別的每個實例對於每個子節點都有一個屬性，其型別如文法中所定義。例如，:" +"class:`ast.BinOp` 實例具有型別為 :class:`ast.expr` 的屬性 :attr:`left`。" + +#: ../../library/ast.rst:71 +msgid "" +"If these attributes are marked as optional in the grammar (using a question " +"mark), the value might be ``None``. If the attributes can have zero-or-more " +"values (marked with an asterisk), the values are represented as Python " +"lists. All possible attributes must be present and have valid values when " +"compiling an AST with :func:`compile`." +msgstr "" +"如果這些屬性在文法中被標記為可選（使用問號），則該值可能為 ``None``。如果屬性" +"可以有零個或多個值（用星號標記），則這些值將表示為 Python 串列。使用 :func:" +"`compile` 編譯 AST 時，所有可能的屬性都必須存在並且具有有效值。" + +#: ../../library/ast.rst:79 +msgid "" +"The :attr:`!_field_types` attribute on each concrete class is a dictionary " +"mapping field names (as also listed in :attr:`_fields`) to their types." +msgstr "" +"每個具體類別上的 :attr:`!_field_types` 屬性是將欄位名稱（也在 :attr:" +"`_fields` 中列出）對映到其型別的字典。" + +#: ../../library/ast.rst:82 +msgid "" +">>> ast.TypeVar._field_types\n" +"{'name': , 'bound': ast.expr | None, 'default_value': ast.expr " +"| None}" +msgstr "" +">>> ast.TypeVar._field_types\n" +"{'name': , 'bound': ast.expr | None, 'default_value': ast.expr " +"| None}" + +#: ../../library/ast.rst:94 +msgid "" +"Instances of :class:`ast.expr` and :class:`ast.stmt` subclasses have :attr:" +"`lineno`, :attr:`col_offset`, :attr:`end_lineno`, and :attr:`end_col_offset` " +"attributes. The :attr:`lineno` and :attr:`end_lineno` are the first and " +"last line numbers of source text span (1-indexed so the first line is line " +"1) and the :attr:`col_offset` and :attr:`end_col_offset` are the " +"corresponding UTF-8 byte offsets of the first and last tokens that generated " +"the node. The UTF-8 offset is recorded because the parser uses UTF-8 " +"internally." +msgstr "" +":class:`ast.expr` 和 :class:`ast.stmt` 子類別的實例具有 :attr:`lineno`、:" +"attr:`col_offset`、:attr:`end_lineno` 和 :attr:`end_col_offset` 屬性。:attr:" +"`lineno` 和 :attr:`end_lineno` 是原始文本跨度 (source text span) 的第一個和最" +"後一個列號（1-indexed，因此第一列號是 1）以及 :attr:`col_offset` 和 :attr:" +"`end_col_offset` 是生成節點的第一個和最後一個標記對應的 UTF-8 位元組偏移量。" +"會記錄 UTF-8 偏移量是因為剖析器 (parser) 內部使用 UTF-8。" + +#: ../../library/ast.rst:103 +msgid "" +"Note that the end positions are not required by the compiler and are " +"therefore optional. The end offset is *after* the last symbol, for example " +"one can get the source segment of a one-line expression node using " +"``source_line[node.col_offset : node.end_col_offset]``." +msgstr "" +"請注意，編譯器並不需要結束位置，因此其為可選的。結束偏移量在最後一個符號\\ *" +"之後*，例如可以使用 ``source_line[node.col_offset : node.end_col_offset]`` 來" +"取得單列運算式節點 (expression node) 的原始片段。" + +#: ../../library/ast.rst:108 +msgid "" +"The constructor of a class :class:`ast.T` parses its arguments as follows:" +msgstr ":class:`ast.T` 類別的建構函式按以下方式剖析其引數：" + +#: ../../library/ast.rst:110 +msgid "" +"If there are positional arguments, there must be as many as there are items " +"in :attr:`T._fields`; they will be assigned as attributes of these names." +msgstr "" +"如果有位置引數，則必須與 :attr:`T._fields` 中的項目一樣多；它們將被賦値為這些" +"名稱的屬性。" + +#: ../../library/ast.rst:112 +msgid "" +"If there are keyword arguments, they will set the attributes of the same " +"names to the given values." +msgstr "如果有關鍵字引數，它們會將相同名稱的屬性設定為給定值。" + +#: ../../library/ast.rst:115 +msgid "" +"For example, to create and populate an :class:`ast.UnaryOp` node, you could " +"use ::" +msgstr "" +"例如，要建立並填充 (populate) :class:`ast.UnaryOp` 節點，你可以使用： ::" + +#: ../../library/ast.rst:118 +msgid "" +"node = ast.UnaryOp(ast.USub(), ast.Constant(5, lineno=0, col_offset=0),\n" +" lineno=0, col_offset=0)" +msgstr "" +"node = ast.UnaryOp(ast.USub(), ast.Constant(5, lineno=0, col_offset=0),\n" +" lineno=0, col_offset=0)" + +#: ../../library/ast.rst:121 +msgid "" +"If a field that is optional in the grammar is omitted from the constructor, " +"it defaults to ``None``. If a list field is omitted, it defaults to the " +"empty list. If a field of type :class:`!ast.expr_context` is omitted, it " +"defaults to :class:`Load() `. If any other field is omitted, a :" +"exc:`DeprecationWarning` is raised and the AST node will not have this " +"field. In Python 3.15, this condition will raise an error." +msgstr "" +"如果建構函式中省略了文法中可選的欄位，則它預設為 ``None``。如果省略串列欄位，" +"則預設為空串列。如果省略 :class:`!ast.expr_context` 型別的欄位，則預設為 :" +"class:`Load() `。如果省略任何其他欄位，則會引發 :exc:" +"`DeprecationWarning`，且 AST 節點將沒有此欄位。在 Python 3.15 中，這種情況會" +"引發錯誤。" + +#: ../../library/ast.rst:130 +msgid "Class :class:`ast.Constant` is now used for all constants." +msgstr ":class:`ast.Constant` 類別現在用於所有常數。" + +#: ../../library/ast.rst:134 +msgid "" +"Simple indices are represented by their value, extended slices are " +"represented as tuples." +msgstr "以它們的值表示簡單索引，擴充切片 (slice) 則以元組 (tuple) 表示。" + +#: ../../library/ast.rst:139 +msgid "" +"The :meth:`~object.__repr__` output of :class:`~ast.AST` nodes includes the " +"values of the node fields." +msgstr ":class:`~ast.AST` 節點的 :meth:`~object.__repr__` 輸出包含節點欄位的值。" + +#: ../../library/ast.rst:144 +msgid "" +"Previous versions of Python provided the AST classes :class:`!ast.Num`, :" +"class:`!ast.Str`, :class:`!ast.Bytes`, :class:`!ast.NameConstant` and :class:" +"`!ast.Ellipsis`, which were deprecated in Python 3.8. These classes were " +"removed in Python 3.14, and their functionality has been replaced with :" +"class:`ast.Constant`." +msgstr "" +"過去的 Python 版本提供了 AST 類別 :class:`!ast.Num`、:class:`!ast.Str`、:" +"class:`!ast.Bytes`、:class:`!ast.NameConstant` 和 :class:`!ast.Ellipsis`，這" +"些類別在 Python 3.8 中已被棄用。這些類別在 Python 3.14 中被移除，其功能已被 :" +"class:`ast.Constant` 取代。" + +#: ../../library/ast.rst:152 +msgid "" +"Old classes :class:`!ast.Index` and :class:`!ast.ExtSlice` are still " +"available, but they will be removed in future Python releases. In the " +"meantime, instantiating them will return an instance of a different class." +msgstr "" +"舊的類別 :class:`!ast.Index` 和 :class:`!ast.ExtSlice` 仍然可用，但它們將在未" +"來的 Python 版本中刪除。同時，實例化它們會回傳不同類別的實例。" + +#: ../../library/ast.rst:159 +msgid "" +"Previous versions of Python allowed the creation of AST nodes that were " +"missing required fields. Similarly, AST node constructors allowed arbitrary " +"keyword arguments that were set as attributes of the AST node, even if they " +"did not match any of the fields of the AST node. This behavior is deprecated " +"and will be removed in Python 3.15." +msgstr "" +"先前版本的 Python 允許建立缺少必填欄位的 AST 節點。同樣地，AST 節點建構函式允" +"許將任意關鍵字引數設為 AST 節點的屬性，即使它們與 AST 節點的任何欄位都不匹" +"配。此行為已被棄用，並將在 Python 3.15 中刪除。" + +#: ../../library/ast.rst:166 +msgid "" +"The descriptions of the specific node classes displayed here were initially " +"adapted from the fantastic `Green Tree Snakes `__ project and all its contributors." +msgstr "" +"這裡顯示的特定節點類別的描述最初是從出色的 `Green Tree Snakes `__ 專案和所有貢獻者那裡改編而來" +"的。" + +#: ../../library/ast.rst:175 +msgid "Root nodes" +msgstr "根節點" + +#: ../../library/ast.rst:179 +msgid "" +"A Python module, as with :ref:`file input `. Node type generated " +"by :func:`ast.parse` in the default ``\"exec\"`` *mode*." +msgstr "" +"一個 Python 模組，與\\ :ref:`檔案輸入 ` 一樣。由 :func:`ast." +"parse` 在預設的 ``\"exec\"`` *mode* 下生成的節點型別。" + +#: ../../library/ast.rst:182 +msgid "``body`` is a :class:`list` of the module's :ref:`ast-statements`." +msgstr "``body`` 是模組的\\ :ref:`ast-statements` 的一個 :class:`list`。" + +#: ../../library/ast.rst:184 +msgid "" +"``type_ignores`` is a :class:`list` of the module's type ignore comments; " +"see :func:`ast.parse` for more details." +msgstr "" +"``type_ignores`` 是模組的忽略型別註解的 :class:`list`；有關更多詳細資訊，請參" +"閱 :func:`ast.parse`。" + +#: ../../library/ast.rst:187 +msgid "" +">>> print(ast.dump(ast.parse('x = 1'), indent=4))\n" +"Module(\n" +" body=[\n" +" Assign(\n" +" targets=[\n" +" Name(id='x', ctx=Store())],\n" +" value=Constant(value=1))])" +msgstr "" +">>> print(ast.dump(ast.parse('x = 1'), indent=4))\n" +"Module(\n" +" body=[\n" +" Assign(\n" +" targets=[\n" +" Name(id='x', ctx=Store())],\n" +" value=Constant(value=1))])" + +#: ../../library/ast.rst:200 +msgid "" +"A single Python :ref:`expression input `. Node type " +"generated by :func:`ast.parse` when *mode* is ``\"eval\"``." +msgstr "" +"單個 Python :ref:`運算式輸入 `。當 *mode* 是 ``\"eval\"`` " +"時節點型別由 :func:`ast.parse` 生成。" + +#: ../../library/ast.rst:203 +msgid "" +"``body`` is a single node, one of the :ref:`expression types `." +msgstr "" +"``body`` 是單個節點，是\\ :ref:`運算式型別 `\\ 的其中之一。" + +#: ../../library/ast.rst:206 ../../library/ast.rst:276 +msgid "" +">>> print(ast.dump(ast.parse('123', mode='eval'), indent=4))\n" +"Expression(\n" +" body=Constant(value=123))" +msgstr "" +">>> print(ast.dump(ast.parse('123', mode='eval'), indent=4))\n" +"Expression(\n" +" body=Constant(value=123))" + +#: ../../library/ast.rst:215 +msgid "" +"A single :ref:`interactive input `, like in :ref:`tut-interac`. " +"Node type generated by :func:`ast.parse` when *mode* is ``\"single\"``." +msgstr "" +"單個\\ :ref:`互動式輸入 `，和\\ :ref:`tut-interac`\\ 中所述的相" +"似。當 *mode* 是 ``\"single\"`` 時節點型別由 :func:`ast.parse` 生成。" + +#: ../../library/ast.rst:218 +msgid "``body`` is a :class:`list` of :ref:`statement nodes `." +msgstr "" +"``body`` 是\\ :ref:`陳述式節點 (statement nodes) ` 的 :class:" +"`list`。" + +#: ../../library/ast.rst:220 +msgid "" +">>> print(ast.dump(ast.parse('x = 1; y = 2', mode='single'), indent=4))\n" +"Interactive(\n" +" body=[\n" +" Assign(\n" +" targets=[\n" +" Name(id='x', ctx=Store())],\n" +" value=Constant(value=1)),\n" +" Assign(\n" +" targets=[\n" +" Name(id='y', ctx=Store())],\n" +" value=Constant(value=2))])" +msgstr "" +">>> print(ast.dump(ast.parse('x = 1; y = 2', mode='single'), indent=4))\n" +"Interactive(\n" +" body=[\n" +" Assign(\n" +" targets=[\n" +" Name(id='x', ctx=Store())],\n" +" value=Constant(value=1)),\n" +" Assign(\n" +" targets=[\n" +" Name(id='y', ctx=Store())],\n" +" value=Constant(value=2))])" + +#: ../../library/ast.rst:237 +msgid "" +"A representation of an old-style type comments for functions, as Python " +"versions prior to 3.5 didn't support :pep:`484` annotations. Node type " +"generated by :func:`ast.parse` when *mode* is ``\"func_type\"``." +msgstr "" +"函式的舊式型別註解的表示法，因為 3.5 之前的 Python 版本不支援 :pep:`484` 註" +"釋。當 *mode* 是 ``\"func_type\"`` 時節點型別由 :func:`ast.parse` 生成。" + +#: ../../library/ast.rst:241 +msgid "Such type comments would look like this::" +msgstr "這種型別的註解看起來像這樣： ::" + +#: ../../library/ast.rst:243 +msgid "" +"def sum_two_number(a, b):\n" +" # type: (int, int) -> int\n" +" return a + b" +msgstr "" +"def sum_two_number(a, b):\n" +" # type: (int, int) -> int\n" +" return a + b" + +#: ../../library/ast.rst:247 +msgid "" +"``argtypes`` is a :class:`list` of :ref:`expression nodes `." +msgstr "" +"``argtypes`` 是\\ :ref:`運算式節點 `\\ 的 :class:`list`。" + +#: ../../library/ast.rst:249 +msgid "``returns`` is a single :ref:`expression node `." +msgstr "``returns`` 是單個\\ :ref:`運算式節點 `。" + +#: ../../library/ast.rst:251 +msgid "" +">>> print(ast.dump(ast.parse('(int, str) -> List[int]', mode='func_type'), " +"indent=4))\n" +"FunctionType(\n" +" argtypes=[\n" +" Name(id='int', ctx=Load()),\n" +" Name(id='str', ctx=Load())],\n" +" returns=Subscript(\n" +" value=Name(id='List', ctx=Load()),\n" +" slice=Name(id='int', ctx=Load()),\n" +" ctx=Load()))" +msgstr "" +">>> print(ast.dump(ast.parse('(int, str) -> List[int]', mode='func_type'), " +"indent=4))\n" +"FunctionType(\n" +" argtypes=[\n" +" Name(id='int', ctx=Load()),\n" +" Name(id='str', ctx=Load())],\n" +" returns=Subscript(\n" +" value=Name(id='List', ctx=Load()),\n" +" slice=Name(id='int', ctx=Load()),\n" +" ctx=Load()))" + +#: ../../library/ast.rst:267 +msgid "Literals" +msgstr "文本 (Literals)" + +#: ../../library/ast.rst:271 +msgid "" +"A constant value. The ``value`` attribute of the ``Constant`` literal " +"contains the Python object it represents. The values represented can be " +"instances of :class:`str`, :class:`bytes`, :class:`int`, :class:`float`, :" +"class:`complex`, and :class:`bool`, and the constants :data:`None` and :data:" +"`Ellipsis`." +msgstr "" +"一個常數值。``Constant`` 文本的 ``value`` 屬性包含它所代表的 Python 物件。表" +"示的值可以是 :class:`str`、:class:`bytes`、:class:`int`、:class:`float`、:" +"class:`complex` 和 :class:`bool` 的實例，以及常數 :data:`None` 和 :data:" +"`Ellipsis`。" + +#: ../../library/ast.rst:285 +msgid "" +"Node representing a single formatting field in an f-string. If the string " +"contains a single formatting field and nothing else the node can be isolated " +"otherwise it appears in :class:`JoinedStr`." +msgstr "" +"表示 f 字串 (f-string) 中的單個格式化欄位的節點。如果字串包含單個格式欄位並且" +"沒有其他內容，則可以隔離 (isolate) 該節點，否則它將出現在 :class:`JoinedStr` " +"中。" + +#: ../../library/ast.rst:289 +msgid "" +"``value`` is any expression node (such as a literal, a variable, or a " +"function call)." +msgstr "``value`` 為任何運算式節點（例如文字、變數或函式呼叫）。" + +#: ../../library/ast.rst:291 ../../library/ast.rst:373 +msgid "``conversion`` is an integer:" +msgstr "``conversion`` 是一個整數：" + +#: ../../library/ast.rst:293 +msgid "-1: no formatting" +msgstr "-1: 無格式化" + +#: ../../library/ast.rst:294 +msgid "97 (``ord('a')``): ``!a`` :func:`ASCII ` formatting" +msgstr "97 (``ord('a')``)：``！a`` :func:`ASCII ` 格式化" + +#: ../../library/ast.rst:295 +msgid "114 (``ord('r')``): ``!r`` :func:`repr` formatting" +msgstr "114 (``ord('r')``)：``!r`` :func:`repr` 格式化" + +#: ../../library/ast.rst:296 +msgid "115 (``ord('s')``): ``!s`` :func:`string ` formatting" +msgstr "115 (``ord('s')``)：``!s`` :func:`string ` 格式化" + +#: ../../library/ast.rst:298 +msgid "" +"``format_spec`` is a :class:`JoinedStr` node representing the formatting of " +"the value, or ``None`` if no format was specified. Both ``conversion`` and " +"``format_spec`` can be set at the same time." +msgstr "" +"``format_spec`` 是一個 :class:`JoinedStr` 節點，表示值的格式，若未指定格式則" +"為 ``None``。``conversion`` 和 ``format_spec`` 可以同時設定。" + +#: ../../library/ast.rst:305 +msgid "" +"An f-string, comprising a series of :class:`FormattedValue` and :class:" +"`Constant` nodes." +msgstr "" +"一個 f 字串，包含一系列 :class:`FormattedValue` 和 :class:`Constant` 節點。" + +#: ../../library/ast.rst:308 +msgid "" +">>> print(ast.dump(ast.parse('f\"sin({a}) is {sin(a):.3}\"', mode='eval'), " +"indent=4))\n" +"Expression(\n" +" body=JoinedStr(\n" +" values=[\n" +" Constant(value='sin('),\n" +" FormattedValue(\n" +" value=Name(id='a', ctx=Load()),\n" +" conversion=-1),\n" +" Constant(value=') is '),\n" +" FormattedValue(\n" +" value=Call(\n" +" func=Name(id='sin', ctx=Load()),\n" +" args=[\n" +" Name(id='a', ctx=Load())]),\n" +" conversion=-1,\n" +" format_spec=JoinedStr(\n" +" values=[\n" +" Constant(value='.3')]))]))" +msgstr "" +">>> print(ast.dump(ast.parse('f\"sin({a}) is {sin(a):.3}\"', mode='eval'), " +"indent=4))\n" +"Expression(\n" +" body=JoinedStr(\n" +" values=[\n" +" Constant(value='sin('),\n" +" FormattedValue(\n" +" value=Name(id='a', ctx=Load()),\n" +" conversion=-1),\n" +" Constant(value=') is '),\n" +" FormattedValue(\n" +" value=Call(\n" +" func=Name(id='sin', ctx=Load()),\n" +" args=[\n" +" Name(id='a', ctx=Load())]),\n" +" conversion=-1,\n" +" format_spec=JoinedStr(\n" +" values=[\n" +" Constant(value='.3')]))]))" + +#: ../../library/ast.rst:334 +msgid "" +"Node representing a template string literal, comprising a series of :class:" +"`Interpolation` and :class:`Constant` nodes. These nodes may be any order, " +"and do not need to be interleaved." +msgstr "" +"表示模板字串字面值的節點，由一系列 :class:`Interpolation` 和 :class:" +"`Constant` 節點組成。這些節點可以是任意順序，不需要交錯排列。" + +#: ../../library/ast.rst:338 +msgid "" +">>> expr = ast.parse('t\"{name} finished {place:ordinal}\"', mode='eval')\n" +">>> print(ast.dump(expr, indent=4))\n" +"Expression(\n" +" body=TemplateStr(\n" +" values=[\n" +" Interpolation(\n" +" value=Name(id='name', ctx=Load()),\n" +" str='name',\n" +" conversion=-1),\n" +" Constant(value=' finished '),\n" +" Interpolation(\n" +" value=Name(id='place', ctx=Load()),\n" +" str='place',\n" +" conversion=-1,\n" +" format_spec=JoinedStr(\n" +" values=[\n" +" Constant(value='ordinal')]))]))" +msgstr "" +">>> expr = ast.parse('t\"{name} finished {place:ordinal}\"', mode='eval')\n" +">>> print(ast.dump(expr, indent=4))\n" +"Expression(\n" +" body=TemplateStr(\n" +" values=[\n" +" Interpolation(\n" +" value=Name(id='name', ctx=Load()),\n" +" str='name',\n" +" conversion=-1),\n" +" Constant(value=' finished '),\n" +" Interpolation(\n" +" value=Name(id='place', ctx=Load()),\n" +" str='place',\n" +" conversion=-1,\n" +" format_spec=JoinedStr(\n" +" values=[\n" +" Constant(value='ordinal')]))]))" + +#: ../../library/ast.rst:362 +msgid "" +"Node representing a single interpolation field in a template string literal." +msgstr "表示模板字串字面值中單一插值欄位的節點。" + +#: ../../library/ast.rst:364 +msgid "" +"``value`` is any expression node (such as a literal, a variable, or a " +"function call). This has the same meaning as ``FormattedValue.value``." +msgstr "" +"``value`` 為任何運算式節點（例如文字、變數或函式呼叫）。這和 " +"``FormattedValue.value`` 的意思相同。" + +#: ../../library/ast.rst:367 +msgid "" +"``str`` is a constant containing the text of the interpolation expression." +msgstr "``str`` 是一個包含插值運算式文字的常數。" + +#: ../../library/ast.rst:369 +msgid "" +"If ``str`` is set to ``None``, then ``value`` is used to generate code when " +"calling :func:`ast.unparse`. This no longer guarantees that the generated " +"code is identical to the original and is intended for code generation." +msgstr "" +"如果 ``str`` 被設為 ``None``，則在呼叫 :func:`ast.unparse` 時會使用 " +"``value`` 來產生程式碼。這不再保證產生的程式碼與原始程式碼相同，且適用於程式碼" +"產生。" + +#: ../../library/ast.rst:375 +msgid "-1: no conversion" +msgstr "-1：無規範" + +#: ../../library/ast.rst:376 +msgid "97 (``ord('a')``): ``!a`` :func:`ASCII ` conversion" +msgstr "97 (``ord('a')``)：``!a`` :func:`ASCII ` 轉換" + +#: ../../library/ast.rst:377 +msgid "114 (``ord('r')``): ``!r`` :func:`repr` conversion" +msgstr "114 (``ord('r')``)：``!r`` :func:`repr` 轉換" + +#: ../../library/ast.rst:378 +msgid "115 (``ord('s')``): ``!s`` :func:`string ` conversion" +msgstr "115 (``ord('s')``)：``!s`` :func:`string ` 轉換" + +#: ../../library/ast.rst:380 +msgid "This has the same meaning as ``FormattedValue.conversion``." +msgstr "這與 ``FormattedValue.conversion`` 的意思相同。" + +#: ../../library/ast.rst:381 +msgid "" +"``format_spec`` is a :class:`JoinedStr` node representing the formatting of " +"the value, or ``None`` if no format was specified. Both ``conversion`` and " +"``format_spec`` can be set at the same time. This has the same meaning as " +"``FormattedValue.format_spec``." +msgstr "" +"``format_spec`` 是一個 :class:`JoinedStr` 節點，表示值的格式，若未指定格式則" +"為 ``None``。``conversion`` 和 ``format_spec`` 可以同時設定。這與 " +"``FormattedValue.format_spec`` 的意思相同。" + +#: ../../library/ast.rst:390 +msgid "" +"A list or tuple. ``elts`` holds a list of nodes representing the elements. " +"``ctx`` is :class:`Store` if the container is an assignment target (i.e. " +"``(x,y)=something``), and :class:`Load` otherwise." +msgstr "" +"串列或元組。``elts`` 保存表示元素的節點串列。如果容器是賦值目標（即 ``(x," +"y)=something`` ），則 ``ctx`` 是 :class:`Store`，否則是 :class:`Load`。" + +#: ../../library/ast.rst:394 +msgid "" +">>> print(ast.dump(ast.parse('[1, 2, 3]', mode='eval'), indent=4))\n" +"Expression(\n" +" body=List(\n" +" elts=[\n" +" Constant(value=1),\n" +" Constant(value=2),\n" +" Constant(value=3)],\n" +" ctx=Load()))\n" +">>> print(ast.dump(ast.parse('(1, 2, 3)', mode='eval'), indent=4))\n" +"Expression(\n" +" body=Tuple(\n" +" elts=[\n" +" Constant(value=1),\n" +" Constant(value=2),\n" +" Constant(value=3)],\n" +" ctx=Load()))" +msgstr "" +">>> print(ast.dump(ast.parse('[1, 2, 3]', mode='eval'), indent=4))\n" +"Expression(\n" +" body=List(\n" +" elts=[\n" +" Constant(value=1),\n" +" Constant(value=2),\n" +" Constant(value=3)],\n" +" ctx=Load()))\n" +">>> print(ast.dump(ast.parse('(1, 2, 3)', mode='eval'), indent=4))\n" +"Expression(\n" +" body=Tuple(\n" +" elts=[\n" +" Constant(value=1),\n" +" Constant(value=2),\n" +" Constant(value=3)],\n" +" ctx=Load()))" + +#: ../../library/ast.rst:416 +msgid "A set. ``elts`` holds a list of nodes representing the set's elements." +msgstr "一個集合。``elts`` 保存表示集合之元素的節點串列。" + +#: ../../library/ast.rst:418 +msgid "" +">>> print(ast.dump(ast.parse('{1, 2, 3}', mode='eval'), indent=4))\n" +"Expression(\n" +" body=Set(\n" +" elts=[\n" +" Constant(value=1),\n" +" Constant(value=2),\n" +" Constant(value=3)]))" +msgstr "" +">>> print(ast.dump(ast.parse('{1, 2, 3}', mode='eval'), indent=4))\n" +"Expression(\n" +" body=Set(\n" +" elts=[\n" +" Constant(value=1),\n" +" Constant(value=2),\n" +" Constant(value=3)]))" + +#: ../../library/ast.rst:431 +msgid "" +"A dictionary. ``keys`` and ``values`` hold lists of nodes representing the " +"keys and the values respectively, in matching order (what would be returned " +"when calling :code:`dictionary.keys()` and :code:`dictionary.values()`)." +msgstr "" +"一個字典 (dictionary)。``keys`` 和 ``values`` 分別按匹配順序保存表示鍵和值的" +"節點串列（為呼叫 :code:`dictionary.keys()` 和 :code:`dictionary.values()` 時" +"將回傳的內容）。" + +#: ../../library/ast.rst:435 +msgid "" +"When doing dictionary unpacking using dictionary literals the expression to " +"be expanded goes in the ``values`` list, with a ``None`` at the " +"corresponding position in ``keys``." +msgstr "" +"當使用字典文本進行字典解包 (unpack) 時，要擴充的運算式位於 ``values`` 串列" +"中，在 ``keys`` 中的相應位置有一個 ``None``。" + +#: ../../library/ast.rst:439 +msgid "" +">>> print(ast.dump(ast.parse('{\"a\":1, **d}', mode='eval'), indent=4))\n" +"Expression(\n" +" body=Dict(\n" +" keys=[\n" +" Constant(value='a'),\n" +" None],\n" +" values=[\n" +" Constant(value=1),\n" +" Name(id='d', ctx=Load())]))" +msgstr "" +">>> print(ast.dump(ast.parse('{\"a\":1, **d}', mode='eval'), indent=4))\n" +"Expression(\n" +" body=Dict(\n" +" keys=[\n" +" Constant(value='a'),\n" +" None],\n" +" values=[\n" +" Constant(value=1),\n" +" Name(id='d', ctx=Load())]))" + +#: ../../library/ast.rst:453 +msgid "Variables" +msgstr "變數" + +#: ../../library/ast.rst:457 +msgid "" +"A variable name. ``id`` holds the name as a string, and ``ctx`` is one of " +"the following types." +msgstr "一個變數名稱。``id`` 將名稱以字串形式保存，且 ``ctx`` 是以下型別之一。" + +#: ../../library/ast.rst:465 +msgid "" +"Variable references can be used to load the value of a variable, to assign a " +"new value to it, or to delete it. Variable references are given a context to " +"distinguish these cases." +msgstr "" +"變數參照可用於載入變數的值、為其分配新值或刪除它。變數參照被賦予情境 " +"(context) 來區分這些情況。" + +#: ../../library/ast.rst:469 +msgid "" +">>> print(ast.dump(ast.parse('a'), indent=4))\n" +"Module(\n" +" body=[\n" +" Expr(\n" +" value=Name(id='a', ctx=Load()))])\n" +"\n" +">>> print(ast.dump(ast.parse('a = 1'), indent=4))\n" +"Module(\n" +" body=[\n" +" Assign(\n" +" targets=[\n" +" Name(id='a', ctx=Store())],\n" +" value=Constant(value=1))])\n" +"\n" +">>> print(ast.dump(ast.parse('del a'), indent=4))\n" +"Module(\n" +" body=[\n" +" Delete(\n" +" targets=[\n" +" Name(id='a', ctx=Del())])])" +msgstr "" +">>> print(ast.dump(ast.parse('a'), indent=4))\n" +"Module(\n" +" body=[\n" +" Expr(\n" +" value=Name(id='a', ctx=Load()))])\n" +"\n" +">>> print(ast.dump(ast.parse('a = 1'), indent=4))\n" +"Module(\n" +" body=[\n" +" Assign(\n" +" targets=[\n" +" Name(id='a', ctx=Store())],\n" +" value=Constant(value=1))])\n" +"\n" +">>> print(ast.dump(ast.parse('del a'), indent=4))\n" +"Module(\n" +" body=[\n" +" Delete(\n" +" targets=[\n" +" Name(id='a', ctx=Del())])])" + +#: ../../library/ast.rst:495 +msgid "" +"A ``*var`` variable reference. ``value`` holds the variable, typically a :" +"class:`Name` node. This type must be used when building a :class:`Call` node " +"with ``*args``." +msgstr "" +"一個 ``*var`` 變數參照。``value`` 保存變數，通常是一個 :class:`Name` 節點。在" +"使用 ``*args`` 建置 :class:`Call` 節點時必須使用此型別。" + +#: ../../library/ast.rst:499 +msgid "" +">>> print(ast.dump(ast.parse('a, *b = it'), indent=4))\n" +"Module(\n" +" body=[\n" +" Assign(\n" +" targets=[\n" +" Tuple(\n" +" elts=[\n" +" Name(id='a', ctx=Store()),\n" +" Starred(\n" +" value=Name(id='b', ctx=Store()),\n" +" ctx=Store())],\n" +" ctx=Store())],\n" +" value=Name(id='it', ctx=Load()))])" +msgstr "" +">>> print(ast.dump(ast.parse('a, *b = it'), indent=4))\n" +"Module(\n" +" body=[\n" +" Assign(\n" +" targets=[\n" +" Tuple(\n" +" elts=[\n" +" Name(id='a', ctx=Store()),\n" +" Starred(\n" +" value=Name(id='b', ctx=Store()),\n" +" ctx=Store())],\n" +" ctx=Store())],\n" +" value=Name(id='it', ctx=Load()))])" + +#: ../../library/ast.rst:519 +msgid "Expressions" +msgstr "運算式" + +#: ../../library/ast.rst:523 +msgid "" +"When an expression, such as a function call, appears as a statement by " +"itself with its return value not used or stored, it is wrapped in this " +"container. ``value`` holds one of the other nodes in this section, a :class:" +"`Constant`, a :class:`Name`, a :class:`Lambda`, a :class:`Yield` or :class:" +"`YieldFrom` node." +msgstr "" +"當運算式（例如函式呼叫）本身作為陳述式出現且未使用或儲存其回傳值時，它將被包" +"裝在此容器中。``value`` 保存此區段 (section) 中的一個其他節點：:class:" +"`Constant`、:class:`Name`、:class:`Lambda`、:class:`Yield` 或 :class:" +"`YieldFrom`" + +#: ../../library/ast.rst:528 +msgid "" +">>> print(ast.dump(ast.parse('-a'), indent=4))\n" +"Module(\n" +" body=[\n" +" Expr(\n" +" value=UnaryOp(\n" +" op=USub(),\n" +" operand=Name(id='a', ctx=Load())))])" +msgstr "" +">>> print(ast.dump(ast.parse('-a'), indent=4))\n" +"Module(\n" +" body=[\n" +" Expr(\n" +" value=UnaryOp(\n" +" op=USub(),\n" +" operand=Name(id='a', ctx=Load())))])" + +#: ../../library/ast.rst:541 +msgid "" +"A unary operation. ``op`` is the operator, and ``operand`` any expression " +"node." +msgstr "" +"一元運算 (unary operation)。``op`` 是運算子，``operand`` 是任何運算式節點。" + +#: ../../library/ast.rst:550 +msgid "" +"Unary operator tokens. :class:`Not` is the ``not`` keyword, :class:`Invert` " +"is the ``~`` operator." +msgstr "" +"一元運算子標記。 :class:`Not` 是 ``not`` 關鍵字、:class:`Invert` 是 ``~`` 運" +"算子。" + +#: ../../library/ast.rst:553 +msgid "" +">>> print(ast.dump(ast.parse('not x', mode='eval'), indent=4))\n" +"Expression(\n" +" body=UnaryOp(\n" +" op=Not(),\n" +" operand=Name(id='x', ctx=Load())))" +msgstr "" +">>> print(ast.dump(ast.parse('not x', mode='eval'), indent=4))\n" +"Expression(\n" +" body=UnaryOp(\n" +" op=Not(),\n" +" operand=Name(id='x', ctx=Load())))" + +#: ../../library/ast.rst:564 +msgid "" +"A binary operation (like addition or division). ``op`` is the operator, and " +"``left`` and ``right`` are any expression nodes." +msgstr "" +"二元運算 (binary operation)（如加法或除法）。 ``op`` 是運算子、``left`` 和 " +"``right`` 是任意運算式節點。" + +#: ../../library/ast.rst:567 +msgid "" +">>> print(ast.dump(ast.parse('x + y', mode='eval'), indent=4))\n" +"Expression(\n" +" body=BinOp(\n" +" left=Name(id='x', ctx=Load()),\n" +" op=Add(),\n" +" right=Name(id='y', ctx=Load())))" +msgstr "" +">>> print(ast.dump(ast.parse('x + y', mode='eval'), indent=4))\n" +"Expression(\n" +" body=BinOp(\n" +" left=Name(id='x', ctx=Load()),\n" +" op=Add(),\n" +" right=Name(id='y', ctx=Load())))" + +#: ../../library/ast.rst:591 +msgid "Binary operator tokens." +msgstr "二元運算子 token。" + +#: ../../library/ast.rst:596 +msgid "" +"A boolean operation, 'or' or 'and'. ``op`` is :class:`Or` or :class:`And`. " +"``values`` are the values involved. Consecutive operations with the same " +"operator, such as ``a or b or c``, are collapsed into one node with several " +"values." +msgstr "" +"布林運算 'or' 或 'and'。``op`` 是 :class:`Or` 或 :class:`And`。``values`` 是" +"有所涉及的值。使用同一運算子的連續操作（例如 ``a or b or c``）會被折疊為具有" +"多個值的一個節點。" + +#: ../../library/ast.rst:601 +msgid "This doesn't include ``not``, which is a :class:`UnaryOp`." +msgstr "這不包括 ``not``，它是一個 :class:`UnaryOp`。" + +#: ../../library/ast.rst:603 +msgid "" +">>> print(ast.dump(ast.parse('x or y', mode='eval'), indent=4))\n" +"Expression(\n" +" body=BoolOp(\n" +" op=Or(),\n" +" values=[\n" +" Name(id='x', ctx=Load()),\n" +" Name(id='y', ctx=Load())]))" +msgstr "" +">>> print(ast.dump(ast.parse('x or y', mode='eval'), indent=4))\n" +"Expression(\n" +" body=BoolOp(\n" +" op=Or(),\n" +" values=[\n" +" Name(id='x', ctx=Load()),\n" +" Name(id='y', ctx=Load())]))" + +#: ../../library/ast.rst:617 +msgid "Boolean operator tokens." +msgstr "布林運算子 token。" + +#: ../../library/ast.rst:622 +msgid "" +"A comparison of two or more values. ``left`` is the first value in the " +"comparison, ``ops`` the list of operators, and ``comparators`` the list of " +"values after the first element in the comparison." +msgstr "" +"兩個或多個值的比較。``left`` 是比較中的第一個值、``ops`` 是運算子串列、" +"``comparators`` 是要比較的第一個元素之後值的串列。" + +#: ../../library/ast.rst:626 +msgid "" +">>> print(ast.dump(ast.parse('1 <= a < 10', mode='eval'), indent=4))\n" +"Expression(\n" +" body=Compare(\n" +" left=Constant(value=1),\n" +" ops=[\n" +" LtE(),\n" +" Lt()],\n" +" comparators=[\n" +" Name(id='a', ctx=Load()),\n" +" Constant(value=10)]))" +msgstr "" +">>> print(ast.dump(ast.parse('1 <= a < 10', mode='eval'), indent=4))\n" +"Expression(\n" +" body=Compare(\n" +" left=Constant(value=1),\n" +" ops=[\n" +" LtE(),\n" +" Lt()],\n" +" comparators=[\n" +" Name(id='a', ctx=Load()),\n" +" Constant(value=10)]))" + +#: ../../library/ast.rst:651 +msgid "Comparison operator tokens." +msgstr "比較運算子 token。" + +#: ../../library/ast.rst:656 +msgid "" +"A function call. ``func`` is the function, which will often be a :class:" +"`Name` or :class:`Attribute` object. Of the arguments:" +msgstr "" +"一個函式呼叫。``func`` 是該函式，通常是一個 :class:`Name` 或 :class:" +"`Attribute` 物件。而在引數中：" + +#: ../../library/ast.rst:659 +msgid "``args`` holds a list of the arguments passed by position." +msgstr "``args`` 保存按位置傳遞的引數串列。" + +#: ../../library/ast.rst:660 +msgid "" +"``keywords`` holds a list of :class:`.keyword` objects representing " +"arguments passed by keyword." +msgstr "" +"``keywords`` 保存一個 :class:`.keyword` 物件串列，表示透過關鍵字傳遞的引數。" + +#: ../../library/ast.rst:663 +msgid "" +"The ``args`` and ``keywords`` arguments are optional and default to empty " +"lists." +msgstr "``args`` 和 ``keywords`` 引數是可選的，預設為空串列。" + +#: ../../library/ast.rst:665 +msgid "" +">>> print(ast.dump(ast.parse('func(a, b=c, *d, **e)', mode='eval'), " +"indent=4))\n" +"Expression(\n" +" body=Call(\n" +" func=Name(id='func', ctx=Load()),\n" +" args=[\n" +" Name(id='a', ctx=Load()),\n" +" Starred(\n" +" value=Name(id='d', ctx=Load()),\n" +" ctx=Load())],\n" +" keywords=[\n" +" keyword(\n" +" arg='b',\n" +" value=Name(id='c', ctx=Load())),\n" +" keyword(\n" +" value=Name(id='e', ctx=Load()))]))" +msgstr "" +">>> print(ast.dump(ast.parse('func(a, b=c, *d, **e)', mode='eval'), " +"indent=4))\n" +"Expression(\n" +" body=Call(\n" +" func=Name(id='func', ctx=Load()),\n" +" args=[\n" +" Name(id='a', ctx=Load()),\n" +" Starred(\n" +" value=Name(id='d', ctx=Load()),\n" +" ctx=Load())],\n" +" keywords=[\n" +" keyword(\n" +" arg='b',\n" +" value=Name(id='c', ctx=Load())),\n" +" keyword(\n" +" value=Name(id='e', ctx=Load()))]))" + +#: ../../library/ast.rst:686 +msgid "" +"A keyword argument to a function call or class definition. ``arg`` is a raw " +"string of the parameter name, ``value`` is a node to pass in." +msgstr "" +"函式呼叫或類別定義的關鍵字引數。``arg`` 是參數名稱的原始字串，``value`` 是要" +"傳入的節點。" + +#: ../../library/ast.rst:692 +msgid "" +"An expression such as ``a if b else c``. Each field holds a single node, so " +"in the following example, all three are :class:`Name` nodes." +msgstr "" +"像是 ``a if b else c`` 之類的運算式。每個欄位都保存一個節點，因此在以下範例" +"中，所有三個都是 :class:`Name` 節點。" + +#: ../../library/ast.rst:695 +msgid "" +">>> print(ast.dump(ast.parse('a if b else c', mode='eval'), indent=4))\n" +"Expression(\n" +" body=IfExp(\n" +" test=Name(id='b', ctx=Load()),\n" +" body=Name(id='a', ctx=Load()),\n" +" orelse=Name(id='c', ctx=Load())))" +msgstr "" +">>> print(ast.dump(ast.parse('a if b else c', mode='eval'), indent=4))\n" +"Expression(\n" +" body=IfExp(\n" +" test=Name(id='b', ctx=Load()),\n" +" body=Name(id='a', ctx=Load()),\n" +" orelse=Name(id='c', ctx=Load())))" + +#: ../../library/ast.rst:707 +msgid "" +"Attribute access, e.g. ``d.keys``. ``value`` is a node, typically a :class:" +"`Name`. ``attr`` is a bare string giving the name of the attribute, and " +"``ctx`` is :class:`Load`, :class:`Store` or :class:`Del` according to how " +"the attribute is acted on." +msgstr "" +"屬性的存取，例如 ``d.keys``。``value`` 是一個節點，通常是一個 :class:`Name`。" +"``attr`` 是一個屬性名稱的字串，``ctx`` 根據屬性的作用方式可能是 :class:" +"`Load`、:class:`Store` 或 :class:`Del`。" + +#: ../../library/ast.rst:712 +msgid "" +">>> print(ast.dump(ast.parse('snake.colour', mode='eval'), indent=4))\n" +"Expression(\n" +" body=Attribute(\n" +" value=Name(id='snake', ctx=Load()),\n" +" attr='colour',\n" +" ctx=Load()))" +msgstr "" +">>> print(ast.dump(ast.parse('snake.colour', mode='eval'), indent=4))\n" +"Expression(\n" +" body=Attribute(\n" +" value=Name(id='snake', ctx=Load()),\n" +" attr='colour',\n" +" ctx=Load()))" + +#: ../../library/ast.rst:724 +msgid "" +"A named expression. This AST node is produced by the assignment expressions " +"operator (also known as the walrus operator). As opposed to the :class:" +"`Assign` node in which the first argument can be multiple nodes, in this " +"case both ``target`` and ``value`` must be single nodes." +msgstr "" +"一個附名運算式 (named expression)。該 AST 節點由賦值運算式運算子（也稱為海象" +"運算子）產生。相對於 :class:`Assign` 節點之第一個引數可為多個節點，在這種情況" +"下 ``target`` 和 ``value`` 都必須是單個節點。" + +#: ../../library/ast.rst:729 +msgid "" +">>> print(ast.dump(ast.parse('(x := 4)', mode='eval'), indent=4))\n" +"Expression(\n" +" body=NamedExpr(\n" +" target=Name(id='x', ctx=Store()),\n" +" value=Constant(value=4)))" +msgstr "" +">>> print(ast.dump(ast.parse('(x := 4)', mode='eval'), indent=4))\n" +"Expression(\n" +" body=NamedExpr(\n" +" target=Name(id='x', ctx=Store()),\n" +" value=Constant(value=4)))" + +#: ../../library/ast.rst:740 +msgid "Subscripting" +msgstr "下標 (Subscripting)" + +#: ../../library/ast.rst:744 +msgid "" +"A subscript, such as ``l[1]``. ``value`` is the subscripted object (usually " +"sequence or mapping). ``slice`` is an index, slice or key. It can be a :" +"class:`Tuple` and contain a :class:`Slice`. ``ctx`` is :class:`Load`, :class:" +"`Store` or :class:`Del` according to the action performed with the subscript." +msgstr "" +"一個下標，例如 ``l[1]``。``value`` 是下標物件（通常是序列或對映）。``slice`` " +"是索引、切片或鍵。它可以是一個 :class:`Tuple` 並包含一個 :class:`Slice`。根據" +"下標執行的操作不同，``ctx`` 可以是 :class:`Load`、:class:`Store` 或 :class:" +"`Del`。" + +#: ../../library/ast.rst:750 +msgid "" +">>> print(ast.dump(ast.parse('l[1:2, 3]', mode='eval'), indent=4))\n" +"Expression(\n" +" body=Subscript(\n" +" value=Name(id='l', ctx=Load()),\n" +" slice=Tuple(\n" +" elts=[\n" +" Slice(\n" +" lower=Constant(value=1),\n" +" upper=Constant(value=2)),\n" +" Constant(value=3)],\n" +" ctx=Load()),\n" +" ctx=Load()))" +msgstr "" +">>> print(ast.dump(ast.parse('l[1:2, 3]', mode='eval'), indent=4))\n" +"Expression(\n" +" body=Subscript(\n" +" value=Name(id='l', ctx=Load()),\n" +" slice=Tuple(\n" +" elts=[\n" +" Slice(\n" +" lower=Constant(value=1),\n" +" upper=Constant(value=2)),\n" +" Constant(value=3)],\n" +" ctx=Load()),\n" +" ctx=Load()))" + +#: ../../library/ast.rst:768 +msgid "" +"Regular slicing (on the form ``lower:upper`` or ``lower:upper:step``). Can " +"occur only inside the *slice* field of :class:`Subscript`, either directly " +"or as an element of :class:`Tuple`." +msgstr "" +"常規切片（形式為 ``lower:upper`` 或 ``lower:upper:step``）。只能直接或者或者" +"作為 :class:`Tuple` 的元素出現在 :class:`Subscript` 的 *slice* 欄位內。" + +#: ../../library/ast.rst:772 +msgid "" +">>> print(ast.dump(ast.parse('l[1:2]', mode='eval'), indent=4))\n" +"Expression(\n" +" body=Subscript(\n" +" value=Name(id='l', ctx=Load()),\n" +" slice=Slice(\n" +" lower=Constant(value=1),\n" +" upper=Constant(value=2)),\n" +" ctx=Load()))" +msgstr "" +">>> print(ast.dump(ast.parse('l[1:2]', mode='eval'), indent=4))\n" +"Expression(\n" +" body=Subscript(\n" +" value=Name(id='l', ctx=Load()),\n" +" slice=Slice(\n" +" lower=Constant(value=1),\n" +" upper=Constant(value=2)),\n" +" ctx=Load()))" + +#: ../../library/ast.rst:785 +msgid "Comprehensions" +msgstr "綜合運算式 (comprehensions)" + +#: ../../library/ast.rst:792 +msgid "" +"List and set comprehensions, generator expressions, and dictionary " +"comprehensions. ``elt`` (or ``key`` and ``value``) is a single node " +"representing the part that will be evaluated for each item." +msgstr "" +"串列和集合綜合運算、生成器運算式和字典綜合運算。``elt``\\ （或 ``key`` 和 " +"``value``）是單個節點，表示各個項目會被求值 (evaluate) 的部分。" + +#: ../../library/ast.rst:796 +msgid "``generators`` is a list of :class:`comprehension` nodes." +msgstr "``generators`` 是一個 :class:`comprehension` 節點的串列。" + +#: ../../library/ast.rst:798 +msgid "" +">>> print(ast.dump(\n" +"... ast.parse('[x for x in numbers]', mode='eval'),\n" +"... indent=4,\n" +"... ))\n" +"Expression(\n" +" body=ListComp(\n" +" elt=Name(id='x', ctx=Load()),\n" +" generators=[\n" +" comprehension(\n" +" target=Name(id='x', ctx=Store()),\n" +" iter=Name(id='numbers', ctx=Load()),\n" +" is_async=0)]))\n" +">>> print(ast.dump(\n" +"... ast.parse('{x: x**2 for x in numbers}', mode='eval'),\n" +"... indent=4,\n" +"... ))\n" +"Expression(\n" +" body=DictComp(\n" +" key=Name(id='x', ctx=Load()),\n" +" value=BinOp(\n" +" left=Name(id='x', ctx=Load()),\n" +" op=Pow(),\n" +" right=Constant(value=2)),\n" +" generators=[\n" +" comprehension(\n" +" target=Name(id='x', ctx=Store()),\n" +" iter=Name(id='numbers', ctx=Load()),\n" +" is_async=0)]))\n" +">>> print(ast.dump(\n" +"... ast.parse('{x for x in numbers}', mode='eval'),\n" +"... indent=4,\n" +"... ))\n" +"Expression(\n" +" body=SetComp(\n" +" elt=Name(id='x', ctx=Load()),\n" +" generators=[\n" +" comprehension(\n" +" target=Name(id='x', ctx=Store()),\n" +" iter=Name(id='numbers', ctx=Load()),\n" +" is_async=0)]))" +msgstr "" +">>> print(ast.dump(\n" +"... ast.parse('[x for x in numbers]', mode='eval'),\n" +"... indent=4,\n" +"... ))\n" +"Expression(\n" +" body=ListComp(\n" +" elt=Name(id='x', ctx=Load()),\n" +" generators=[\n" +" comprehension(\n" +" target=Name(id='x', ctx=Store()),\n" +" iter=Name(id='numbers', ctx=Load()),\n" +" is_async=0)]))\n" +">>> print(ast.dump(\n" +"... ast.parse('{x: x**2 for x in numbers}', mode='eval'),\n" +"... indent=4,\n" +"... ))\n" +"Expression(\n" +" body=DictComp(\n" +" key=Name(id='x', ctx=Load()),\n" +" value=BinOp(\n" +" left=Name(id='x', ctx=Load()),\n" +" op=Pow(),\n" +" right=Constant(value=2)),\n" +" generators=[\n" +" comprehension(\n" +" target=Name(id='x', ctx=Store()),\n" +" iter=Name(id='numbers', ctx=Load()),\n" +" is_async=0)]))\n" +">>> print(ast.dump(\n" +"... ast.parse('{x for x in numbers}', mode='eval'),\n" +"... indent=4,\n" +"... ))\n" +"Expression(\n" +" body=SetComp(\n" +" elt=Name(id='x', ctx=Load()),\n" +" generators=[\n" +" comprehension(\n" +" target=Name(id='x', ctx=Store()),\n" +" iter=Name(id='numbers', ctx=Load()),\n" +" is_async=0)]))" + +#: ../../library/ast.rst:844 +msgid "" +"One ``for`` clause in a comprehension. ``target`` is the reference to use " +"for each element - typically a :class:`Name` or :class:`Tuple` node. " +"``iter`` is the object to iterate over. ``ifs`` is a list of test " +"expressions: each ``for`` clause can have multiple ``ifs``." +msgstr "" +"綜合運算中的一個 ``for`` 子句。``target`` 是用於每個元素的參照 - 通常是 :" +"class:`Name` 或 :class:`Tuple` 節點。``iter`` 是要疊代的物件。``ifs`` 是測試" +"運算式的串列：每個 ``for`` 子句可以有多個 ``ifs``。" + +#: ../../library/ast.rst:849 +msgid "" +"``is_async`` indicates a comprehension is asynchronous (using an ``async " +"for`` instead of ``for``). The value is an integer (0 or 1)." +msgstr "" +"``is_async`` 表示綜合運算式是非同步的（使用 ``async for`` 而不是 ``for`` ）。" +"該值為整數（0 或 1）。" + +#: ../../library/ast.rst:852 +msgid "" +">>> print(ast.dump(ast.parse('[ord(c) for line in file for c in line]', " +"mode='eval'),\n" +"... indent=4)) # Multiple comprehensions in one.\n" +"Expression(\n" +" body=ListComp(\n" +" elt=Call(\n" +" func=Name(id='ord', ctx=Load()),\n" +" args=[\n" +" Name(id='c', ctx=Load())]),\n" +" generators=[\n" +" comprehension(\n" +" target=Name(id='line', ctx=Store()),\n" +" iter=Name(id='file', ctx=Load()),\n" +" is_async=0),\n" +" comprehension(\n" +" target=Name(id='c', ctx=Store()),\n" +" iter=Name(id='line', ctx=Load()),\n" +" is_async=0)]))\n" +"\n" +">>> print(ast.dump(ast.parse('(n**2 for n in it if n>5 if n<10)', " +"mode='eval'),\n" +"... indent=4)) # generator comprehension\n" +"Expression(\n" +" body=GeneratorExp(\n" +" elt=BinOp(\n" +" left=Name(id='n', ctx=Load()),\n" +" op=Pow(),\n" +" right=Constant(value=2)),\n" +" generators=[\n" +" comprehension(\n" +" target=Name(id='n', ctx=Store()),\n" +" iter=Name(id='it', ctx=Load()),\n" +" ifs=[\n" +" Compare(\n" +" left=Name(id='n', ctx=Load()),\n" +" ops=[\n" +" Gt()],\n" +" comparators=[\n" +" Constant(value=5)]),\n" +" Compare(\n" +" left=Name(id='n', ctx=Load()),\n" +" ops=[\n" +" Lt()],\n" +" comparators=[\n" +" Constant(value=10)])],\n" +" is_async=0)]))\n" +"\n" +">>> print(ast.dump(ast.parse('[i async for i in soc]', mode='eval'),\n" +"... indent=4)) # Async comprehension\n" +"Expression(\n" +" body=ListComp(\n" +" elt=Name(id='i', ctx=Load()),\n" +" generators=[\n" +" comprehension(\n" +" target=Name(id='i', ctx=Store()),\n" +" iter=Name(id='soc', ctx=Load()),\n" +" is_async=1)]))" +msgstr "" +">>> print(ast.dump(ast.parse('[ord(c) for line in file for c in line]', " +"mode='eval'),\n" +"... indent=4)) # Multiple comprehensions in one.\n" +"Expression(\n" +" body=ListComp(\n" +" elt=Call(\n" +" func=Name(id='ord', ctx=Load()),\n" +" args=[\n" +" Name(id='c', ctx=Load())]),\n" +" generators=[\n" +" comprehension(\n" +" target=Name(id='line', ctx=Store()),\n" +" iter=Name(id='file', ctx=Load()),\n" +" is_async=0),\n" +" comprehension(\n" +" target=Name(id='c', ctx=Store()),\n" +" iter=Name(id='line', ctx=Load()),\n" +" is_async=0)]))\n" +"\n" +">>> print(ast.dump(ast.parse('(n**2 for n in it if n>5 if n<10)', " +"mode='eval'),\n" +"... indent=4)) # generator comprehension\n" +"Expression(\n" +" body=GeneratorExp(\n" +" elt=BinOp(\n" +" left=Name(id='n', ctx=Load()),\n" +" op=Pow(),\n" +" right=Constant(value=2)),\n" +" generators=[\n" +" comprehension(\n" +" target=Name(id='n', ctx=Store()),\n" +" iter=Name(id='it', ctx=Load()),\n" +" ifs=[\n" +" Compare(\n" +" left=Name(id='n', ctx=Load()),\n" +" ops=[\n" +" Gt()],\n" +" comparators=[\n" +" Constant(value=5)]),\n" +" Compare(\n" +" left=Name(id='n', ctx=Load()),\n" +" ops=[\n" +" Lt()],\n" +" comparators=[\n" +" Constant(value=10)])],\n" +" is_async=0)]))\n" +"\n" +">>> print(ast.dump(ast.parse('[i async for i in soc]', mode='eval'),\n" +"... indent=4)) # Async comprehension\n" +"Expression(\n" +" body=ListComp(\n" +" elt=Name(id='i', ctx=Load()),\n" +" generators=[\n" +" comprehension(\n" +" target=Name(id='i', ctx=Store()),\n" +" iter=Name(id='soc', ctx=Load()),\n" +" is_async=1)]))" + +#: ../../library/ast.rst:914 +msgid "Statements" +msgstr "陳述式" + +#: ../../library/ast.rst:918 +msgid "" +"An assignment. ``targets`` is a list of nodes, and ``value`` is a single " +"node." +msgstr "一個賦值。``targets`` 是節點串列，``value`` 是單個節點。" + +#: ../../library/ast.rst:920 +msgid "" +"Multiple nodes in ``targets`` represents assigning the same value to each. " +"Unpacking is represented by putting a :class:`Tuple` or :class:`List` within " +"``targets``." +msgstr "" +"``targets`` 中的多個節點表示為每個節點分配相同的值。解包是透過在 ``targets`` " +"中放置一個 :class:`Tuple` 或 :class:`List` 來表示的。" + +#: ../../library/ast.rst:926 ../../library/ast.rst:1221 +#: ../../library/ast.rst:1415 ../../library/ast.rst:1981 +msgid "" +"``type_comment`` is an optional string with the type annotation as a comment." +msgstr "``type_comment`` 是一個可選字串，其中的註解為型別註釋。" + +#: ../../library/ast.rst:928 +msgid "" +">>> print(ast.dump(ast.parse('a = b = 1'), indent=4)) # Multiple assignment\n" +"Module(\n" +" body=[\n" +" Assign(\n" +" targets=[\n" +" Name(id='a', ctx=Store()),\n" +" Name(id='b', ctx=Store())],\n" +" value=Constant(value=1))])\n" +"\n" +">>> print(ast.dump(ast.parse('a,b = c'), indent=4)) # Unpacking\n" +"Module(\n" +" body=[\n" +" Assign(\n" +" targets=[\n" +" Tuple(\n" +" elts=[\n" +" Name(id='a', ctx=Store()),\n" +" Name(id='b', ctx=Store())],\n" +" ctx=Store())],\n" +" value=Name(id='c', ctx=Load()))])" +msgstr "" +">>> print(ast.dump(ast.parse('a = b = 1'), indent=4)) # Multiple assignment\n" +"Module(\n" +" body=[\n" +" Assign(\n" +" targets=[\n" +" Name(id='a', ctx=Store()),\n" +" Name(id='b', ctx=Store())],\n" +" value=Constant(value=1))])\n" +"\n" +">>> print(ast.dump(ast.parse('a,b = c'), indent=4)) # Unpacking\n" +"Module(\n" +" body=[\n" +" Assign(\n" +" targets=[\n" +" Tuple(\n" +" elts=[\n" +" Name(id='a', ctx=Store()),\n" +" Name(id='b', ctx=Store())],\n" +" ctx=Store())],\n" +" value=Name(id='c', ctx=Load()))])" + +#: ../../library/ast.rst:954 +msgid "" +"An assignment with a type annotation. ``target`` is a single node and can be " +"a :class:`Name`, an :class:`Attribute` or a :class:`Subscript`. " +"``annotation`` is the annotation, such as a :class:`Constant` or :class:" +"`Name` node. ``value`` is a single optional node." +msgstr "" +"帶有型別註釋的賦值。``target`` 是單個節點，可以是 :class:`Name`、:class:" +"`Attribute` 或 :class:`Subscript`。``annotation`` 是註釋，例如 :class:" +"`Constant` 或 :class:`Name` 節點。``value`` 是單個可選節點。" + +#: ../../library/ast.rst:959 +msgid "" +"``simple`` is always either 0 (indicating a \"complex\" target) or 1 " +"(indicating a \"simple\" target). A \"simple\" target consists solely of a :" +"class:`Name` node that does not appear between parentheses; all other " +"targets are considered complex. Only simple targets appear in the :attr:" +"`~object.__annotations__` dictionary of modules and classes." +msgstr "" +"``simple`` 總會是 0（表示一個「複雜」目標）或 1（表示一個「簡單」目標）。一個" +"「簡單」目標僅包含一個 :class:`Name` 節點，且不出現在括號之間；所有其他目標都" +"被視為是複雜的。只有簡單目標會出現在模組和類別的 :attr:`~object." +"__annotations__` 字典中。" + +#: ../../library/ast.rst:965 +msgid "" +">>> print(ast.dump(ast.parse('c: int'), indent=4))\n" +"Module(\n" +" body=[\n" +" AnnAssign(\n" +" target=Name(id='c', ctx=Store()),\n" +" annotation=Name(id='int', ctx=Load()),\n" +" simple=1)])\n" +"\n" +">>> print(ast.dump(ast.parse('(a): int = 1'), indent=4)) # Annotation with " +"parenthesis\n" +"Module(\n" +" body=[\n" +" AnnAssign(\n" +" target=Name(id='a', ctx=Store()),\n" +" annotation=Name(id='int', ctx=Load()),\n" +" value=Constant(value=1),\n" +" simple=0)])\n" +"\n" +">>> print(ast.dump(ast.parse('a.b: int'), indent=4)) # Attribute annotation\n" +"Module(\n" +" body=[\n" +" AnnAssign(\n" +" target=Attribute(\n" +" value=Name(id='a', ctx=Load()),\n" +" attr='b',\n" +" ctx=Store()),\n" +" annotation=Name(id='int', ctx=Load()),\n" +" simple=0)])\n" +"\n" +">>> print(ast.dump(ast.parse('a[1]: int'), indent=4)) # Subscript " +"annotation\n" +"Module(\n" +" body=[\n" +" AnnAssign(\n" +" target=Subscript(\n" +" value=Name(id='a', ctx=Load()),\n" +" slice=Constant(value=1),\n" +" ctx=Store()),\n" +" annotation=Name(id='int', ctx=Load()),\n" +" simple=0)])" +msgstr "" +">>> print(ast.dump(ast.parse('c: int'), indent=4))\n" +"Module(\n" +" body=[\n" +" AnnAssign(\n" +" target=Name(id='c', ctx=Store()),\n" +" annotation=Name(id='int', ctx=Load()),\n" +" simple=1)])\n" +"\n" +">>> print(ast.dump(ast.parse('(a): int = 1'), indent=4)) # Annotation with " +"parenthesis\n" +"Module(\n" +" body=[\n" +" AnnAssign(\n" +" target=Name(id='a', ctx=Store()),\n" +" annotation=Name(id='int', ctx=Load()),\n" +" value=Constant(value=1),\n" +" simple=0)])\n" +"\n" +">>> print(ast.dump(ast.parse('a.b: int'), indent=4)) # Attribute annotation\n" +"Module(\n" +" body=[\n" +" AnnAssign(\n" +" target=Attribute(\n" +" value=Name(id='a', ctx=Load()),\n" +" attr='b',\n" +" ctx=Store()),\n" +" annotation=Name(id='int', ctx=Load()),\n" +" simple=0)])\n" +"\n" +">>> print(ast.dump(ast.parse('a[1]: int'), indent=4)) # Subscript " +"annotation\n" +"Module(\n" +" body=[\n" +" AnnAssign(\n" +" target=Subscript(\n" +" value=Name(id='a', ctx=Load()),\n" +" slice=Constant(value=1),\n" +" ctx=Store()),\n" +" annotation=Name(id='int', ctx=Load()),\n" +" simple=0)])" + +#: ../../library/ast.rst:1009 +msgid "" +"Augmented assignment, such as ``a += 1``. In the following example, " +"``target`` is a :class:`Name` node for ``x`` (with the :class:`Store` " +"context), ``op`` is :class:`Add`, and ``value`` is a :class:`Constant` with " +"value for 1." +msgstr "" +"增加賦值 (augmented assignment)，例如 ``a += 1``。在下面的範例中，``target`` " +"是 ``x`` 的 :class:`Name` 節點（帶有 :class:`Store` 情境），``op`` 是 :class:" +"`Add`，``value`` 是一個值為 1 的 :class:`Constant`。" + +#: ../../library/ast.rst:1014 +msgid "" +"The ``target`` attribute cannot be of class :class:`Tuple` or :class:`List`, " +"unlike the targets of :class:`Assign`." +msgstr "" +"與 :class:`Assign` 的目標不同，``target`` 屬性不能屬於 :class:`Tuple` 或 :" +"class:`List` 類別。" + +#: ../../library/ast.rst:1017 +msgid "" +">>> print(ast.dump(ast.parse('x += 2'), indent=4))\n" +"Module(\n" +" body=[\n" +" AugAssign(\n" +" target=Name(id='x', ctx=Store()),\n" +" op=Add(),\n" +" value=Constant(value=2))])" +msgstr "" +">>> print(ast.dump(ast.parse('x += 2'), indent=4))\n" +"Module(\n" +" body=[\n" +" AugAssign(\n" +" target=Name(id='x', ctx=Store()),\n" +" op=Add(),\n" +" value=Constant(value=2))])" + +#: ../../library/ast.rst:1030 +msgid "" +"A ``raise`` statement. ``exc`` is the exception object to be raised, " +"normally a :class:`Call` or :class:`Name`, or ``None`` for a standalone " +"``raise``. ``cause`` is the optional part for ``y`` in ``raise x from y``." +msgstr "" +"一個 ``raise`` 陳述式。``exc`` 是要引發的例外物件，通常是 :class:`Call` 或 :" +"class:`Name`，若是獨立的 ``raise`` 則為 ``None``。``cause`` 是 ``raise x " +"from y`` 中的可選部分 ``y``。" + +#: ../../library/ast.rst:1034 +msgid "" +">>> print(ast.dump(ast.parse('raise x from y'), indent=4))\n" +"Module(\n" +" body=[\n" +" Raise(\n" +" exc=Name(id='x', ctx=Load()),\n" +" cause=Name(id='y', ctx=Load()))])" +msgstr "" +">>> print(ast.dump(ast.parse('raise x from y'), indent=4))\n" +"Module(\n" +" body=[\n" +" Raise(\n" +" exc=Name(id='x', ctx=Load()),\n" +" cause=Name(id='y', ctx=Load()))])" + +#: ../../library/ast.rst:1046 +msgid "" +"An assertion. ``test`` holds the condition, such as a :class:`Compare` node. " +"``msg`` holds the failure message." +msgstr "" +"一個斷言 (assertion)。``test`` 保存條件，例如 :class:`Compare` 節點。``msg`` " +"保存失敗訊息。" + +#: ../../library/ast.rst:1049 +msgid "" +">>> print(ast.dump(ast.parse('assert x,y'), indent=4))\n" +"Module(\n" +" body=[\n" +" Assert(\n" +" test=Name(id='x', ctx=Load()),\n" +" msg=Name(id='y', ctx=Load()))])" +msgstr "" +">>> print(ast.dump(ast.parse('assert x,y'), indent=4))\n" +"Module(\n" +" body=[\n" +" Assert(\n" +" test=Name(id='x', ctx=Load()),\n" +" msg=Name(id='y', ctx=Load()))])" + +#: ../../library/ast.rst:1061 +msgid "" +"Represents a ``del`` statement. ``targets`` is a list of nodes, such as :" +"class:`Name`, :class:`Attribute` or :class:`Subscript` nodes." +msgstr "" +"代表一個 ``del`` 陳述式。``targets`` 是節點串列，例如 :class:`Name`、:class:" +"`Attribute` 或 :class:`Subscript` 節點。" + +#: ../../library/ast.rst:1064 +msgid "" +">>> print(ast.dump(ast.parse('del x,y,z'), indent=4))\n" +"Module(\n" +" body=[\n" +" Delete(\n" +" targets=[\n" +" Name(id='x', ctx=Del()),\n" +" Name(id='y', ctx=Del()),\n" +" Name(id='z', ctx=Del())])])" +msgstr "" +">>> print(ast.dump(ast.parse('del x,y,z'), indent=4))\n" +"Module(\n" +" body=[\n" +" Delete(\n" +" targets=[\n" +" Name(id='x', ctx=Del()),\n" +" Name(id='y', ctx=Del()),\n" +" Name(id='z', ctx=Del())])])" + +#: ../../library/ast.rst:1078 +msgid "A ``pass`` statement." +msgstr "一個 ``pass`` 陳述式。" + +#: ../../library/ast.rst:1080 +msgid "" +">>> print(ast.dump(ast.parse('pass'), indent=4))\n" +"Module(\n" +" body=[\n" +" Pass()])" +msgstr "" +">>> print(ast.dump(ast.parse('pass'), indent=4))\n" +"Module(\n" +" body=[\n" +" Pass()])" + +#: ../../library/ast.rst:1090 +msgid "" +"A :ref:`type alias ` created through the :keyword:`type` " +"statement. ``name`` is the name of the alias, ``type_params`` is a list of :" +"ref:`type parameters `, and ``value`` is the value of the " +"type alias." +msgstr "" +"透過 :keyword:`type` 陳述式建立的\\ :ref:`型別別名 (type alias) `。``name`` 是別名的名稱、``type_params`` 是\\ :ref:`型別參數 (type " +"parameter) ` 的串列、``value`` 是型別別名的值。" + +#: ../../library/ast.rst:1095 +msgid "" +">>> print(ast.dump(ast.parse('type Alias = int'), indent=4))\n" +"Module(\n" +" body=[\n" +" TypeAlias(\n" +" name=Name(id='Alias', ctx=Store()),\n" +" value=Name(id='int', ctx=Load()))])" +msgstr "" +">>> print(ast.dump(ast.parse('type Alias = int'), indent=4))\n" +"Module(\n" +" body=[\n" +" TypeAlias(\n" +" name=Name(id='Alias', ctx=Store()),\n" +" value=Name(id='int', ctx=Load()))])" + +#: ../../library/ast.rst:1106 +msgid "" +"Other statements which are only applicable inside functions or loops are " +"described in other sections." +msgstr "其他僅適用於函式或迴圈內部的陳述式將在其他部分中描述。" + +#: ../../library/ast.rst:1110 +msgid "Imports" +msgstr "引入 (imports)" + +#: ../../library/ast.rst:1114 +msgid "An import statement. ``names`` is a list of :class:`alias` nodes." +msgstr "一個 import 陳述式。``names`` 是 :class:`alias` 節點的串列。" + +#: ../../library/ast.rst:1116 +msgid "" +">>> print(ast.dump(ast.parse('import x,y,z'), indent=4))\n" +"Module(\n" +" body=[\n" +" Import(\n" +" names=[\n" +" alias(name='x'),\n" +" alias(name='y'),\n" +" alias(name='z')])])" +msgstr "" +">>> print(ast.dump(ast.parse('import x,y,z'), indent=4))\n" +"Module(\n" +" body=[\n" +" Import(\n" +" names=[\n" +" alias(name='x'),\n" +" alias(name='y'),\n" +" alias(name='z')])])" + +#: ../../library/ast.rst:1130 +msgid "" +"Represents ``from x import y``. ``module`` is a raw string of the 'from' " +"name, without any leading dots, or ``None`` for statements such as ``from . " +"import foo``. ``level`` is an integer holding the level of the relative " +"import (0 means absolute import)." +msgstr "" +"代表 ``from x import y``。``module`` 是 'from' 名稱的原始字串，前面沒有任何的" +"點 (dot)，或者對於諸如 ``from . import foo`` 之類的陳述式則為 ``None``。" +"``level`` 是一個整數，保存相對引入的級別（0 表示絕對引入）。" + +#: ../../library/ast.rst:1135 +msgid "" +">>> print(ast.dump(ast.parse('from y import x,y,z'), indent=4))\n" +"Module(\n" +" body=[\n" +" ImportFrom(\n" +" module='y',\n" +" names=[\n" +" alias(name='x'),\n" +" alias(name='y'),\n" +" alias(name='z')],\n" +" level=0)])" +msgstr "" +">>> print(ast.dump(ast.parse('from y import x,y,z'), indent=4))\n" +"Module(\n" +" body=[\n" +" ImportFrom(\n" +" module='y',\n" +" names=[\n" +" alias(name='x'),\n" +" alias(name='y'),\n" +" alias(name='z')],\n" +" level=0)])" + +#: ../../library/ast.rst:1151 +msgid "" +"Both parameters are raw strings of the names. ``asname`` can be ``None`` if " +"the regular name is to be used." +msgstr "" +"這兩個參數都是名稱的原始字串。如果要使用常規名稱，``asname`` 可以為 " +"``None``。" + +#: ../../library/ast.rst:1154 +msgid "" +">>> print(ast.dump(ast.parse('from ..foo.bar import a as b, c'), indent=4))\n" +"Module(\n" +" body=[\n" +" ImportFrom(\n" +" module='foo.bar',\n" +" names=[\n" +" alias(name='a', asname='b'),\n" +" alias(name='c')],\n" +" level=2)])" +msgstr "" +">>> print(ast.dump(ast.parse('from ..foo.bar import a as b, c'), indent=4))\n" +"Module(\n" +" body=[\n" +" ImportFrom(\n" +" module='foo.bar',\n" +" names=[\n" +" alias(name='a', asname='b'),\n" +" alias(name='c')],\n" +" level=2)])" + +#: ../../library/ast.rst:1167 +msgid "Control flow" +msgstr "流程控制" + +#: ../../library/ast.rst:1170 +msgid "" +"Optional clauses such as ``else`` are stored as an empty list if they're not " +"present." +msgstr "諸如 ``else`` 之類的可選子句如果不存在，則將被儲存為空串列。" + +#: ../../library/ast.rst:1175 +msgid "" +"An ``if`` statement. ``test`` holds a single node, such as a :class:" +"`Compare` node. ``body`` and ``orelse`` each hold a list of nodes." +msgstr "" +"一個 ``if`` 陳述式。``test`` 保存單個節點，例如 :class:`Compare` 節點。" +"``body`` 和 ``orelse`` 各自保存一個節點串列。" + +#: ../../library/ast.rst:1178 +msgid "" +"``elif`` clauses don't have a special representation in the AST, but rather " +"appear as extra :class:`If` nodes within the ``orelse`` section of the " +"previous one." +msgstr "" +"``elif`` 子句在 AST 中沒有特殊表示，而是在前一個子句的 ``orelse`` 部分中作為" +"額外的 :class:`If` 節點出現。" + +#: ../../library/ast.rst:1182 +msgid "" +">>> print(ast.dump(ast.parse(\"\"\"\n" +"... if x:\n" +"... ...\n" +"... elif y:\n" +"... ...\n" +"... else:\n" +"... ...\n" +"... \"\"\"), indent=4))\n" +"Module(\n" +" body=[\n" +" If(\n" +" test=Name(id='x', ctx=Load()),\n" +" body=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))],\n" +" orelse=[\n" +" If(\n" +" test=Name(id='y', ctx=Load()),\n" +" body=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))],\n" +" orelse=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))])])])" +msgstr "" +">>> print(ast.dump(ast.parse(\"\"\"\n" +"... if x:\n" +"... ...\n" +"... elif y:\n" +"... ...\n" +"... else:\n" +"... ...\n" +"... \"\"\"), indent=4))\n" +"Module(\n" +" body=[\n" +" If(\n" +" test=Name(id='x', ctx=Load()),\n" +" body=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))],\n" +" orelse=[\n" +" If(\n" +" test=Name(id='y', ctx=Load()),\n" +" body=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))],\n" +" orelse=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))])])])" + +#: ../../library/ast.rst:1212 +msgid "" +"A ``for`` loop. ``target`` holds the variable(s) the loop assigns to, as a " +"single :class:`Name`, :class:`Tuple`, :class:`List`, :class:`Attribute` or :" +"class:`Subscript` node. ``iter`` holds the item to be looped over, again as " +"a single node. ``body`` and ``orelse`` contain lists of nodes to execute. " +"Those in ``orelse`` are executed if the loop finishes normally, rather than " +"via a ``break`` statement." +msgstr "" +"一個 ``for`` 迴圈。 ``target`` 保存迴圈賦予的變數，為單個 :class:`Name`、:" +"class:`Tuple`、:class:`List`、:class:`Attribute` 或 :class:`Subscript` 節點。" +"``iter`` 保存要迴圈跑過的項目，也為單個節點。``body`` 和 ``orelse`` 包含要執" +"行的節點串列。如果迴圈正常完成，則執行 ``orelse`` 中的內容，而不是透過 " +"``break`` 陳述式執行。" + +#: ../../library/ast.rst:1223 +msgid "" +">>> print(ast.dump(ast.parse(\"\"\"\n" +"... for x in y:\n" +"... ...\n" +"... else:\n" +"... ...\n" +"... \"\"\"), indent=4))\n" +"Module(\n" +" body=[\n" +" For(\n" +" target=Name(id='x', ctx=Store()),\n" +" iter=Name(id='y', ctx=Load()),\n" +" body=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))],\n" +" orelse=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))])])" +msgstr "" +">>> print(ast.dump(ast.parse(\"\"\"\n" +"... for x in y:\n" +"... ...\n" +"... else:\n" +"... ...\n" +"... \"\"\"), indent=4))\n" +"Module(\n" +" body=[\n" +" For(\n" +" target=Name(id='x', ctx=Store()),\n" +" iter=Name(id='y', ctx=Load()),\n" +" body=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))],\n" +" orelse=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))])])" + +#: ../../library/ast.rst:1246 +msgid "" +"A ``while`` loop. ``test`` holds the condition, such as a :class:`Compare` " +"node." +msgstr "一個 ``while`` 迴圈。``test`` 保存條件，例如 :class:`Compare` 節點。" + +#: ../../library/ast.rst:1249 +msgid "" +">>> print(ast.dump(ast.parse(\"\"\"\n" +"... while x:\n" +"... ...\n" +"... else:\n" +"... ...\n" +"... \"\"\"), indent=4))\n" +"Module(\n" +" body=[\n" +" While(\n" +" test=Name(id='x', ctx=Load()),\n" +" body=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))],\n" +" orelse=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))])])" +msgstr "" +">>> print(ast.dump(ast.parse(\"\"\"\n" +"... while x:\n" +"... ...\n" +"... else:\n" +"... ...\n" +"... \"\"\"), indent=4))\n" +"Module(\n" +" body=[\n" +" While(\n" +" test=Name(id='x', ctx=Load()),\n" +" body=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))],\n" +" orelse=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))])])" + +#: ../../library/ast.rst:1272 +msgid "The ``break`` and ``continue`` statements." +msgstr "``break`` 和 ``continue`` 陳述式。" + +#: ../../library/ast.rst:1274 +msgid "" +">>> print(ast.dump(ast.parse(\"\"\"\\\n" +"... for a in b:\n" +"... if a > 5:\n" +"... break\n" +"... else:\n" +"... continue\n" +"...\n" +"... \"\"\"), indent=4))\n" +"Module(\n" +" body=[\n" +" For(\n" +" target=Name(id='a', ctx=Store()),\n" +" iter=Name(id='b', ctx=Load()),\n" +" body=[\n" +" If(\n" +" test=Compare(\n" +" left=Name(id='a', ctx=Load()),\n" +" ops=[\n" +" Gt()],\n" +" comparators=[\n" +" Constant(value=5)]),\n" +" body=[\n" +" Break()],\n" +" orelse=[\n" +" Continue()])])])" +msgstr "" +">>> print(ast.dump(ast.parse(\"\"\"\\\n" +"... for a in b:\n" +"... if a > 5:\n" +"... break\n" +"... else:\n" +"... continue\n" +"...\n" +"... \"\"\"), indent=4))\n" +"Module(\n" +" body=[\n" +" For(\n" +" target=Name(id='a', ctx=Store()),\n" +" iter=Name(id='b', ctx=Load()),\n" +" body=[\n" +" If(\n" +" test=Compare(\n" +" left=Name(id='a', ctx=Load()),\n" +" ops=[\n" +" Gt()],\n" +" comparators=[\n" +" Constant(value=5)]),\n" +" body=[\n" +" Break()],\n" +" orelse=[\n" +" Continue()])])])" + +#: ../../library/ast.rst:1305 +msgid "" +"``try`` blocks. All attributes are list of nodes to execute, except for " +"``handlers``, which is a list of :class:`ExceptHandler` nodes." +msgstr "" +"``try`` 區塊。除 ``handlers`` 是 :class:`ExceptHandler` 節點的串列外，其他所" +"有屬性都是要執行之節點的串列。" + +#: ../../library/ast.rst:1308 +msgid "" +">>> print(ast.dump(ast.parse(\"\"\"\n" +"... try:\n" +"... ...\n" +"... except Exception:\n" +"... ...\n" +"... except OtherException as e:\n" +"... ...\n" +"... else:\n" +"... ...\n" +"... finally:\n" +"... ...\n" +"... \"\"\"), indent=4))\n" +"Module(\n" +" body=[\n" +" Try(\n" +" body=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))],\n" +" handlers=[\n" +" ExceptHandler(\n" +" type=Name(id='Exception', ctx=Load()),\n" +" body=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))]),\n" +" ExceptHandler(\n" +" type=Name(id='OtherException', ctx=Load()),\n" +" name='e',\n" +" body=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))])],\n" +" orelse=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))],\n" +" finalbody=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))])])" +msgstr "" +">>> print(ast.dump(ast.parse(\"\"\"\n" +"... try:\n" +"... ...\n" +"... except Exception:\n" +"... ...\n" +"... except OtherException as e:\n" +"... ...\n" +"... else:\n" +"... ...\n" +"... finally:\n" +"... ...\n" +"... \"\"\"), indent=4))\n" +"Module(\n" +" body=[\n" +" Try(\n" +" body=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))],\n" +" handlers=[\n" +" ExceptHandler(\n" +" type=Name(id='Exception', ctx=Load()),\n" +" body=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))]),\n" +" ExceptHandler(\n" +" type=Name(id='OtherException', ctx=Load()),\n" +" name='e',\n" +" body=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))])],\n" +" orelse=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))],\n" +" finalbody=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))])])" + +#: ../../library/ast.rst:1350 +msgid "" +"``try`` blocks which are followed by ``except*`` clauses. The attributes are " +"the same as for :class:`Try` but the :class:`ExceptHandler` nodes in " +"``handlers`` are interpreted as ``except*`` blocks rather then ``except``." +msgstr "" +"``try`` 區塊，後面跟著 ``except*`` 子句。這些屬性與 :class:`Try` 相同，但是 " +"``handlers`` 中的 :class:`ExceptHandler` 節點被直譯 (interpret) 為 " +"``except*`` 區塊而不是 ``except``。" + +#: ../../library/ast.rst:1354 +msgid "" +">>> print(ast.dump(ast.parse(\"\"\"\n" +"... try:\n" +"... ...\n" +"... except* Exception:\n" +"... ...\n" +"... \"\"\"), indent=4))\n" +"Module(\n" +" body=[\n" +" TryStar(\n" +" body=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))],\n" +" handlers=[\n" +" ExceptHandler(\n" +" type=Name(id='Exception', ctx=Load()),\n" +" body=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))])])])" +msgstr "" +">>> print(ast.dump(ast.parse(\"\"\"\n" +"... try:\n" +"... ...\n" +"... except* Exception:\n" +"... ...\n" +"... \"\"\"), indent=4))\n" +"Module(\n" +" body=[\n" +" TryStar(\n" +" body=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))],\n" +" handlers=[\n" +" ExceptHandler(\n" +" type=Name(id='Exception', ctx=Load()),\n" +" body=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))])])])" + +#: ../../library/ast.rst:1379 +msgid "" +"A single ``except`` clause. ``type`` is the exception type it will match, " +"typically a :class:`Name` node (or ``None`` for a catch-all ``except:`` " +"clause). ``name`` is a raw string for the name to hold the exception, or " +"``None`` if the clause doesn't have ``as foo``. ``body`` is a list of nodes." +msgstr "" +"單個 ``except`` 子句。``type`` 是會被匹配的例外型別，通常是一個 :class:" +"`Name` 節點（或者 ``None`` 表示會捕捉到所有例外的 ``except:`` 子句）。" +"``name`` 是用於保存例外的名稱之原始字串，如果子句沒有 ``as foo`` ，則為 " +"``None``。``body`` 是節點串列。" + +#: ../../library/ast.rst:1384 +msgid "" +">>> print(ast.dump(ast.parse(\"\"\"\\\n" +"... try:\n" +"... a + 1\n" +"... except TypeError:\n" +"... pass\n" +"... \"\"\"), indent=4))\n" +"Module(\n" +" body=[\n" +" Try(\n" +" body=[\n" +" Expr(\n" +" value=BinOp(\n" +" left=Name(id='a', ctx=Load()),\n" +" op=Add(),\n" +" right=Constant(value=1)))],\n" +" handlers=[\n" +" ExceptHandler(\n" +" type=Name(id='TypeError', ctx=Load()),\n" +" body=[\n" +" Pass()])])])" +msgstr "" +">>> print(ast.dump(ast.parse(\"\"\"\\\n" +"... try:\n" +"... a + 1\n" +"... except TypeError:\n" +"... pass\n" +"... \"\"\"), indent=4))\n" +"Module(\n" +" body=[\n" +" Try(\n" +" body=[\n" +" Expr(\n" +" value=BinOp(\n" +" left=Name(id='a', ctx=Load()),\n" +" op=Add(),\n" +" right=Constant(value=1)))],\n" +" handlers=[\n" +" ExceptHandler(\n" +" type=Name(id='TypeError', ctx=Load()),\n" +" body=[\n" +" Pass()])])])" + +#: ../../library/ast.rst:1410 +msgid "" +"A ``with`` block. ``items`` is a list of :class:`withitem` nodes " +"representing the context managers, and ``body`` is the indented block inside " +"the context." +msgstr "" +"一個 ``with`` 區塊。``items`` 是表示情境管理器的 :class:`withitem` 節點串列，" +"``body`` 是情境內的縮進區塊。" + +#: ../../library/ast.rst:1420 +msgid "" +"A single context manager in a ``with`` block. ``context_expr`` is the " +"context manager, often a :class:`Call` node. ``optional_vars`` is a :class:" +"`Name`, :class:`Tuple` or :class:`List` for the ``as foo`` part, or ``None`` " +"if that isn't used." +msgstr "" +"``with`` 區塊中的單個情境管理器。``context_expr`` 是情境管理器，通常是一個 :" +"class:`Call` 節點。``Optional_vars`` 是 ``as foo`` 部分的 :class:`Name`、:" +"class:`Tuple` 或 :class:`List`，或者如果不使用則為 ``None`` 。" + +#: ../../library/ast.rst:1425 +msgid "" +">>> print(ast.dump(ast.parse(\"\"\"\\\n" +"... with a as b, c as d:\n" +"... something(b, d)\n" +"... \"\"\"), indent=4))\n" +"Module(\n" +" body=[\n" +" With(\n" +" items=[\n" +" withitem(\n" +" context_expr=Name(id='a', ctx=Load()),\n" +" optional_vars=Name(id='b', ctx=Store())),\n" +" withitem(\n" +" context_expr=Name(id='c', ctx=Load()),\n" +" optional_vars=Name(id='d', ctx=Store()))],\n" +" body=[\n" +" Expr(\n" +" value=Call(\n" +" func=Name(id='something', ctx=Load()),\n" +" args=[\n" +" Name(id='b', ctx=Load()),\n" +" Name(id='d', ctx=Load())]))])])" +msgstr "" +">>> print(ast.dump(ast.parse(\"\"\"\\\n" +"... with a as b, c as d:\n" +"... something(b, d)\n" +"... \"\"\"), indent=4))\n" +"Module(\n" +" body=[\n" +" With(\n" +" items=[\n" +" withitem(\n" +" context_expr=Name(id='a', ctx=Load()),\n" +" optional_vars=Name(id='b', ctx=Store())),\n" +" withitem(\n" +" context_expr=Name(id='c', ctx=Load()),\n" +" optional_vars=Name(id='d', ctx=Store()))],\n" +" body=[\n" +" Expr(\n" +" value=Call(\n" +" func=Name(id='something', ctx=Load()),\n" +" args=[\n" +" Name(id='b', ctx=Load()),\n" +" Name(id='d', ctx=Load())]))])])" + +#: ../../library/ast.rst:1451 +msgid "Pattern matching" +msgstr "模式匹配 (pattern matching)" + +#: ../../library/ast.rst:1456 +msgid "" +"A ``match`` statement. ``subject`` holds the subject of the match (the " +"object that is being matched against the cases) and ``cases`` contains an " +"iterable of :class:`match_case` nodes with the different cases." +msgstr "" +"一個 ``match`` 陳述式。``subject`` 保存匹配的主題（與案例匹配的物件），" +"``cases`` 包含具有不同案例的 :class:`match_case` 節點的可疊代物件。" + +#: ../../library/ast.rst:1464 +msgid "" +"A single case pattern in a ``match`` statement. ``pattern`` contains the " +"match pattern that the subject will be matched against. Note that the :class:" +"`AST` nodes produced for patterns differ from those produced for " +"expressions, even when they share the same syntax." +msgstr "" +"``match`` 陳述式中的單個案例模式。``pattern`` 包含主題將與之匹配的匹配模式。" +"請注意，為模式生成的 :class:`AST` 節點與為運算式生成的節點不同，即使它們共享" +"相同的語法。" + +#: ../../library/ast.rst:1469 +msgid "" +"The ``guard`` attribute contains an expression that will be evaluated if the " +"pattern matches the subject." +msgstr "``guard`` 屬性包含一個運算式，如果模式與主題匹配，則將對該運算式求值。" + +#: ../../library/ast.rst:1472 +msgid "" +"``body`` contains a list of nodes to execute if the pattern matches and the " +"result of evaluating the guard expression is true." +msgstr "" +"``body`` 包含一個節點串列，如果模式匹配並且為防護運算式 (guard expression) 的" +"求值 (evaluate) 結果為真，則會執行該節點串列。" + +#: ../../library/ast.rst:1475 +msgid "" +">>> print(ast.dump(ast.parse(\"\"\"\n" +"... match x:\n" +"... case [x] if x>0:\n" +"... ...\n" +"... case tuple():\n" +"... ...\n" +"... \"\"\"), indent=4))\n" +"Module(\n" +" body=[\n" +" Match(\n" +" subject=Name(id='x', ctx=Load()),\n" +" cases=[\n" +" match_case(\n" +" pattern=MatchSequence(\n" +" patterns=[\n" +" MatchAs(name='x')]),\n" +" guard=Compare(\n" +" left=Name(id='x', ctx=Load()),\n" +" ops=[\n" +" Gt()],\n" +" comparators=[\n" +" Constant(value=0)]),\n" +" body=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))]),\n" +" match_case(\n" +" pattern=MatchClass(\n" +" cls=Name(id='tuple', ctx=Load())),\n" +" body=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))])])])" +msgstr "" +">>> print(ast.dump(ast.parse(\"\"\"\n" +"... match x:\n" +"... case [x] if x>0:\n" +"... ...\n" +"... case tuple():\n" +"... ...\n" +"... \"\"\"), indent=4))\n" +"Module(\n" +" body=[\n" +" Match(\n" +" subject=Name(id='x', ctx=Load()),\n" +" cases=[\n" +" match_case(\n" +" pattern=MatchSequence(\n" +" patterns=[\n" +" MatchAs(name='x')]),\n" +" guard=Compare(\n" +" left=Name(id='x', ctx=Load()),\n" +" ops=[\n" +" Gt()],\n" +" comparators=[\n" +" Constant(value=0)]),\n" +" body=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))]),\n" +" match_case(\n" +" pattern=MatchClass(\n" +" cls=Name(id='tuple', ctx=Load())),\n" +" body=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))])])])" + +#: ../../library/ast.rst:1513 +msgid "" +"A match literal or value pattern that compares by equality. ``value`` is an " +"expression node. Permitted value nodes are restricted as described in the " +"match statement documentation. This pattern succeeds if the match subject is " +"equal to the evaluated value." +msgstr "" +"以相等性進行比較的匹配文本或值的模式。``value`` 是一個運算式節點。允許值節點" +"受到匹配陳述式文件中所述的限制。如果匹配主題等於求出值，則此模式成功。" + +#: ../../library/ast.rst:1518 +msgid "" +">>> print(ast.dump(ast.parse(\"\"\"\n" +"... match x:\n" +"... case \"Relevant\":\n" +"... ...\n" +"... \"\"\"), indent=4))\n" +"Module(\n" +" body=[\n" +" Match(\n" +" subject=Name(id='x', ctx=Load()),\n" +" cases=[\n" +" match_case(\n" +" pattern=MatchValue(\n" +" value=Constant(value='Relevant')),\n" +" body=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))])])])" +msgstr "" +">>> print(ast.dump(ast.parse(\"\"\"\n" +"... match x:\n" +"... case \"Relevant\":\n" +"... ...\n" +"... \"\"\"), indent=4))\n" +"Module(\n" +" body=[\n" +" Match(\n" +" subject=Name(id='x', ctx=Load()),\n" +" cases=[\n" +" match_case(\n" +" pattern=MatchValue(\n" +" value=Constant(value='Relevant')),\n" +" body=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))])])])" + +#: ../../library/ast.rst:1541 +msgid "" +"A match literal pattern that compares by identity. ``value`` is the " +"singleton to be compared against: ``None``, ``True``, or ``False``. This " +"pattern succeeds if the match subject is the given constant." +msgstr "" +"按識別性 (identity) 進行比較的匹配文本模式。``value`` 是要與 ``None``、" +"``True`` 或 ``False`` 進行比較的單例 (singleton)。如果匹配主題是給定的常數，" +"則此模式成功。" + +#: ../../library/ast.rst:1545 +msgid "" +">>> print(ast.dump(ast.parse(\"\"\"\n" +"... match x:\n" +"... case None:\n" +"... ...\n" +"... \"\"\"), indent=4))\n" +"Module(\n" +" body=[\n" +" Match(\n" +" subject=Name(id='x', ctx=Load()),\n" +" cases=[\n" +" match_case(\n" +" pattern=MatchSingleton(value=None),\n" +" body=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))])])])" +msgstr "" +">>> print(ast.dump(ast.parse(\"\"\"\n" +"... match x:\n" +"... case None:\n" +"... ...\n" +"... \"\"\"), indent=4))\n" +"Module(\n" +" body=[\n" +" Match(\n" +" subject=Name(id='x', ctx=Load()),\n" +" cases=[\n" +" match_case(\n" +" pattern=MatchSingleton(value=None),\n" +" body=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))])])])" + +#: ../../library/ast.rst:1567 +msgid "" +"A match sequence pattern. ``patterns`` contains the patterns to be matched " +"against the subject elements if the subject is a sequence. Matches a " +"variable length sequence if one of the subpatterns is a ``MatchStar`` node, " +"otherwise matches a fixed length sequence." +msgstr "" +"匹配序列模式。如果主題是一個序列，``patterns`` 包含與主題元素匹配的模式。如果" +"子模式之一是 ``MatchStar`` 節點，則匹配可變長度序列，否則匹配固定長度序列。" + +#: ../../library/ast.rst:1572 +msgid "" +">>> print(ast.dump(ast.parse(\"\"\"\n" +"... match x:\n" +"... case [1, 2]:\n" +"... ...\n" +"... \"\"\"), indent=4))\n" +"Module(\n" +" body=[\n" +" Match(\n" +" subject=Name(id='x', ctx=Load()),\n" +" cases=[\n" +" match_case(\n" +" pattern=MatchSequence(\n" +" patterns=[\n" +" MatchValue(\n" +" value=Constant(value=1)),\n" +" MatchValue(\n" +" value=Constant(value=2))]),\n" +" body=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))])])])" +msgstr "" +">>> print(ast.dump(ast.parse(\"\"\"\n" +"... match x:\n" +"... case [1, 2]:\n" +"... ...\n" +"... \"\"\"), indent=4))\n" +"Module(\n" +" body=[\n" +" Match(\n" +" subject=Name(id='x', ctx=Load()),\n" +" cases=[\n" +" match_case(\n" +" pattern=MatchSequence(\n" +" patterns=[\n" +" MatchValue(\n" +" value=Constant(value=1)),\n" +" MatchValue(\n" +" value=Constant(value=2))]),\n" +" body=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))])])])" + +#: ../../library/ast.rst:1599 +msgid "" +"Matches the rest of the sequence in a variable length match sequence " +"pattern. If ``name`` is not ``None``, a list containing the remaining " +"sequence elements is bound to that name if the overall sequence pattern is " +"successful." +msgstr "" +"以可變長度匹配序列模式匹配序列的其餘部分。如果 ``name`` 不是 ``None``，則如果" +"整體序列模式成功，則包含其餘序列元素的串列將綁定到該名稱。" + +#: ../../library/ast.rst:1603 +msgid "" +">>> print(ast.dump(ast.parse(\"\"\"\n" +"... match x:\n" +"... case [1, 2, *rest]:\n" +"... ...\n" +"... case [*_]:\n" +"... ...\n" +"... \"\"\"), indent=4))\n" +"Module(\n" +" body=[\n" +" Match(\n" +" subject=Name(id='x', ctx=Load()),\n" +" cases=[\n" +" match_case(\n" +" pattern=MatchSequence(\n" +" patterns=[\n" +" MatchValue(\n" +" value=Constant(value=1)),\n" +" MatchValue(\n" +" value=Constant(value=2)),\n" +" MatchStar(name='rest')]),\n" +" body=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))]),\n" +" match_case(\n" +" pattern=MatchSequence(\n" +" patterns=[\n" +" MatchStar()]),\n" +" body=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))])])])" +msgstr "" +">>> print(ast.dump(ast.parse(\"\"\"\n" +"... match x:\n" +"... case [1, 2, *rest]:\n" +"... ...\n" +"... case [*_]:\n" +"... ...\n" +"... \"\"\"), indent=4))\n" +"Module(\n" +" body=[\n" +" Match(\n" +" subject=Name(id='x', ctx=Load()),\n" +" cases=[\n" +" match_case(\n" +" pattern=MatchSequence(\n" +" patterns=[\n" +" MatchValue(\n" +" value=Constant(value=1)),\n" +" MatchValue(\n" +" value=Constant(value=2)),\n" +" MatchStar(name='rest')]),\n" +" body=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))]),\n" +" match_case(\n" +" pattern=MatchSequence(\n" +" patterns=[\n" +" MatchStar()]),\n" +" body=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))])])])" + +#: ../../library/ast.rst:1640 +msgid "" +"A match mapping pattern. ``keys`` is a sequence of expression nodes. " +"``patterns`` is a corresponding sequence of pattern nodes. ``rest`` is an " +"optional name that can be specified to capture the remaining mapping " +"elements. Permitted key expressions are restricted as described in the match " +"statement documentation." +msgstr "" +"匹配對映模式。``keys`` 是運算式節點的序列。``patterns`` 是相應的模式節點序" +"列。``rest`` 是一個可選名稱，可以指定它來捕獲剩餘的對映元素。允許的鍵運算式受" +"到匹配陳述式文件中所述的限制。" + +#: ../../library/ast.rst:1646 +msgid "" +"This pattern succeeds if the subject is a mapping, all evaluated key " +"expressions are present in the mapping, and the value corresponding to each " +"key matches the corresponding subpattern. If ``rest`` is not ``None``, a " +"dict containing the remaining mapping elements is bound to that name if the " +"overall mapping pattern is successful." +msgstr "" +"如果主題是對映，所有求值出的鍵運算式都存在於對映中，並且與每個鍵對應的值與相" +"應的子模式匹配，則此模式成功。如果 ``rest`` 不是 ``None``，則如果整體對映模式" +"成功，則包含其餘對映元素的字典將綁定到該名稱。" + +#: ../../library/ast.rst:1652 +msgid "" +">>> print(ast.dump(ast.parse(\"\"\"\n" +"... match x:\n" +"... case {1: _, 2: _}:\n" +"... ...\n" +"... case {**rest}:\n" +"... ...\n" +"... \"\"\"), indent=4))\n" +"Module(\n" +" body=[\n" +" Match(\n" +" subject=Name(id='x', ctx=Load()),\n" +" cases=[\n" +" match_case(\n" +" pattern=MatchMapping(\n" +" keys=[\n" +" Constant(value=1),\n" +" Constant(value=2)],\n" +" patterns=[\n" +" MatchAs(),\n" +" MatchAs()]),\n" +" body=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))]),\n" +" match_case(\n" +" pattern=MatchMapping(rest='rest'),\n" +" body=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))])])])" +msgstr "" +">>> print(ast.dump(ast.parse(\"\"\"\n" +"... match x:\n" +"... case {1: _, 2: _}:\n" +"... ...\n" +"... case {**rest}:\n" +"... ...\n" +"... \"\"\"), indent=4))\n" +"Module(\n" +" body=[\n" +" Match(\n" +" subject=Name(id='x', ctx=Load()),\n" +" cases=[\n" +" match_case(\n" +" pattern=MatchMapping(\n" +" keys=[\n" +" Constant(value=1),\n" +" Constant(value=2)],\n" +" patterns=[\n" +" MatchAs(),\n" +" MatchAs()]),\n" +" body=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))]),\n" +" match_case(\n" +" pattern=MatchMapping(rest='rest'),\n" +" body=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))])])])" + +#: ../../library/ast.rst:1687 +msgid "" +"A match class pattern. ``cls`` is an expression giving the nominal class to " +"be matched. ``patterns`` is a sequence of pattern nodes to be matched " +"against the class defined sequence of pattern matching attributes. " +"``kwd_attrs`` is a sequence of additional attributes to be matched " +"(specified as keyword arguments in the class pattern), ``kwd_patterns`` are " +"the corresponding patterns (specified as keyword values in the class " +"pattern)." +msgstr "" +"匹配類別模式。``cls`` 是一個給定要匹配的名義類別 (nominal class) 的運算式。" +"``patterns`` 是要與類別定義的模式匹配屬性序列進行匹配的模式節點序列。" +"``kwd_attrs`` 是要匹配的附加屬性序列（在類別模式中指定為關鍵字引數），" +"``kwd_patterns`` 是相應的模式（在類別模式中指定為關鍵字的值）。" + +#: ../../library/ast.rst:1694 +msgid "" +"This pattern succeeds if the subject is an instance of the nominated class, " +"all positional patterns match the corresponding class-defined attributes, " +"and any specified keyword attributes match their corresponding pattern." +msgstr "" +"如果主題是指定類別的實例，所有位置模式都與相應的類別定義屬性匹配，並且任何指" +"定的關鍵字屬性與其相應模式匹配，則此模式成功。" + +#: ../../library/ast.rst:1698 +msgid "" +"Note: classes may define a property that returns self in order to match a " +"pattern node against the instance being matched. Several builtin types are " +"also matched that way, as described in the match statement documentation." +msgstr "" +"注意：類別可以定義一個回傳 self 的特性 (property)，以便將模式節點與正在匹配的" +"實例進行匹配。一些內建型別也以這種方式匹配，如同匹配陳述式文件中所述。" + +#: ../../library/ast.rst:1702 +msgid "" +">>> print(ast.dump(ast.parse(\"\"\"\n" +"... match x:\n" +"... case Point2D(0, 0):\n" +"... ...\n" +"... case Point3D(x=0, y=0, z=0):\n" +"... ...\n" +"... \"\"\"), indent=4))\n" +"Module(\n" +" body=[\n" +" Match(\n" +" subject=Name(id='x', ctx=Load()),\n" +" cases=[\n" +" match_case(\n" +" pattern=MatchClass(\n" +" cls=Name(id='Point2D', ctx=Load()),\n" +" patterns=[\n" +" MatchValue(\n" +" value=Constant(value=0)),\n" +" MatchValue(\n" +" value=Constant(value=0))]),\n" +" body=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))]),\n" +" match_case(\n" +" pattern=MatchClass(\n" +" cls=Name(id='Point3D', ctx=Load()),\n" +" kwd_attrs=[\n" +" 'x',\n" +" 'y',\n" +" 'z'],\n" +" kwd_patterns=[\n" +" MatchValue(\n" +" value=Constant(value=0)),\n" +" MatchValue(\n" +" value=Constant(value=0)),\n" +" MatchValue(\n" +" value=Constant(value=0))]),\n" +" body=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))])])])" +msgstr "" +">>> print(ast.dump(ast.parse(\"\"\"\n" +"... match x:\n" +"... case Point2D(0, 0):\n" +"... ...\n" +"... case Point3D(x=0, y=0, z=0):\n" +"... ...\n" +"... \"\"\"), indent=4))\n" +"Module(\n" +" body=[\n" +" Match(\n" +" subject=Name(id='x', ctx=Load()),\n" +" cases=[\n" +" match_case(\n" +" pattern=MatchClass(\n" +" cls=Name(id='Point2D', ctx=Load()),\n" +" patterns=[\n" +" MatchValue(\n" +" value=Constant(value=0)),\n" +" MatchValue(\n" +" value=Constant(value=0))]),\n" +" body=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))]),\n" +" match_case(\n" +" pattern=MatchClass(\n" +" cls=Name(id='Point3D', ctx=Load()),\n" +" kwd_attrs=[\n" +" 'x',\n" +" 'y',\n" +" 'z'],\n" +" kwd_patterns=[\n" +" MatchValue(\n" +" value=Constant(value=0)),\n" +" MatchValue(\n" +" value=Constant(value=0)),\n" +" MatchValue(\n" +" value=Constant(value=0))]),\n" +" body=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))])])])" + +#: ../../library/ast.rst:1749 +msgid "" +"A match \"as-pattern\", capture pattern or wildcard pattern. ``pattern`` " +"contains the match pattern that the subject will be matched against. If the " +"pattern is ``None``, the node represents a capture pattern (i.e a bare name) " +"and will always succeed." +msgstr "" +"匹配的 「as 模式 (as-pattern)」，為捕獲模式 (capture pattern) 或通配模式 " +"(wildcard pattern)。``pattern`` 包含主題將與之匹配的匹配模式。如果模式為 " +"``None``，則該節點代表捕獲模式（即裸名 (bare name)）並且始終會成功。" + +#: ../../library/ast.rst:1754 +msgid "" +"The ``name`` attribute contains the name that will be bound if the pattern " +"is successful. If ``name`` is ``None``, ``pattern`` must also be ``None`` " +"and the node represents the wildcard pattern." +msgstr "" +"``name`` 屬性包含模式成功時將綁定的名稱。如果 ``name`` 為 ``None``，則 " +"``pattern`` 也必須為 ``None``，並且節點代表通配模式。" + +#: ../../library/ast.rst:1758 +msgid "" +">>> print(ast.dump(ast.parse(\"\"\"\n" +"... match x:\n" +"... case [x] as y:\n" +"... ...\n" +"... case _:\n" +"... ...\n" +"... \"\"\"), indent=4))\n" +"Module(\n" +" body=[\n" +" Match(\n" +" subject=Name(id='x', ctx=Load()),\n" +" cases=[\n" +" match_case(\n" +" pattern=MatchAs(\n" +" pattern=MatchSequence(\n" +" patterns=[\n" +" MatchAs(name='x')]),\n" +" name='y'),\n" +" body=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))]),\n" +" match_case(\n" +" pattern=MatchAs(),\n" +" body=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))])])])" +msgstr "" +">>> print(ast.dump(ast.parse(\"\"\"\n" +"... match x:\n" +"... case [x] as y:\n" +"... ...\n" +"... case _:\n" +"... ...\n" +"... \"\"\"), indent=4))\n" +"Module(\n" +" body=[\n" +" Match(\n" +" subject=Name(id='x', ctx=Load()),\n" +" cases=[\n" +" match_case(\n" +" pattern=MatchAs(\n" +" pattern=MatchSequence(\n" +" patterns=[\n" +" MatchAs(name='x')]),\n" +" name='y'),\n" +" body=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))]),\n" +" match_case(\n" +" pattern=MatchAs(),\n" +" body=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))])])])" + +#: ../../library/ast.rst:1791 +msgid "" +"A match \"or-pattern\". An or-pattern matches each of its subpatterns in " +"turn to the subject, until one succeeds. The or-pattern is then deemed to " +"succeed. If none of the subpatterns succeed the or-pattern fails. The " +"``patterns`` attribute contains a list of match pattern nodes that will be " +"matched against the subject." +msgstr "" +"匹配的 「or 模式 (or-pattern)」。 or 模式依次將其每個子模式與主題進行匹配，直" +"到成功為止，然後 or 模式就會被認為是成功的。如果沒有一個子模式成功，則 or 模" +"式將失敗。 ``patterns`` 屬性包含將與主題進行匹配的匹配模式節點串列。" + +#: ../../library/ast.rst:1797 +msgid "" +">>> print(ast.dump(ast.parse(\"\"\"\n" +"... match x:\n" +"... case [x] | (y):\n" +"... ...\n" +"... \"\"\"), indent=4))\n" +"Module(\n" +" body=[\n" +" Match(\n" +" subject=Name(id='x', ctx=Load()),\n" +" cases=[\n" +" match_case(\n" +" pattern=MatchOr(\n" +" patterns=[\n" +" MatchSequence(\n" +" patterns=[\n" +" MatchAs(name='x')]),\n" +" MatchAs(name='y')]),\n" +" body=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))])])])" +msgstr "" +">>> print(ast.dump(ast.parse(\"\"\"\n" +"... match x:\n" +"... case [x] | (y):\n" +"... ...\n" +"... \"\"\"), indent=4))\n" +"Module(\n" +" body=[\n" +" Match(\n" +" subject=Name(id='x', ctx=Load()),\n" +" cases=[\n" +" match_case(\n" +" pattern=MatchOr(\n" +" patterns=[\n" +" MatchSequence(\n" +" patterns=[\n" +" MatchAs(name='x')]),\n" +" MatchAs(name='y')]),\n" +" body=[\n" +" Expr(\n" +" value=Constant(value=Ellipsis))])])])" + +#: ../../library/ast.rst:1824 +msgid "Type annotations" +msgstr "型別註釋" + +#: ../../library/ast.rst:1828 +msgid "" +"A ``# type: ignore`` comment located at *lineno*. *tag* is the optional tag " +"specified by the form ``# type: ignore ``." +msgstr "" +"位於 *lineno* 的 ``# type: ignore`` 註解。*tag* 是以 " +"``# type: ignore `` 形式指定的可選標籤。" + +#: ../../library/ast.rst:1831 +msgid "" +">>> print(ast.dump(ast.parse('x = 1 # type: ignore', type_comments=True), " +"indent=4))\n" +"Module(\n" +" body=[\n" +" Assign(\n" +" targets=[\n" +" Name(id='x', ctx=Store())],\n" +" value=Constant(value=1))],\n" +" type_ignores=[\n" +" TypeIgnore(lineno=1, tag='')])\n" +">>> print(ast.dump(ast.parse('x: bool = 1 # type: ignore[assignment]', " +"type_comments=True), indent=4))\n" +"Module(\n" +" body=[\n" +" AnnAssign(\n" +" target=Name(id='x', ctx=Store()),\n" +" annotation=Name(id='bool', ctx=Load()),\n" +" value=Constant(value=1),\n" +" simple=1)],\n" +" type_ignores=[\n" +" TypeIgnore(lineno=1, tag='[assignment]')])" +msgstr "" +">>> print(ast.dump(ast.parse('x = 1 # type: ignore', type_comments=True), " +"indent=4))\n" +"Module(\n" +" body=[\n" +" Assign(\n" +" targets=[\n" +" Name(id='x', ctx=Store())],\n" +" value=Constant(value=1))],\n" +" type_ignores=[\n" +" TypeIgnore(lineno=1, tag='')])\n" +">>> print(ast.dump(ast.parse('x: bool = 1 # type: ignore[assignment]', " +"type_comments=True), indent=4))\n" +"Module(\n" +" body=[\n" +" AnnAssign(\n" +" target=Name(id='x', ctx=Store()),\n" +" annotation=Name(id='bool', ctx=Load()),\n" +" value=Constant(value=1),\n" +" simple=1)],\n" +" type_ignores=[\n" +" TypeIgnore(lineno=1, tag='[assignment]')])" + +#: ../../library/ast.rst:1854 +msgid "" +":class:`!TypeIgnore` nodes are not generated when the *type_comments* " +"parameter is set to ``False`` (default). See :func:`ast.parse` for more " +"details." +msgstr "" +"當 *type_comments* 參數設為 ``False``\\ （預設值）時，不會產生 " +":class:`!TypeIgnore` 節點。更多細節請參閱 :func:`ast.parse`。" + +#: ../../library/ast.rst:1862 +msgid "Type parameters" +msgstr "型別參數 (type parameters)" + +#: ../../library/ast.rst:1864 +msgid "" +":ref:`Type parameters ` can exist on classes, functions, and " +"type aliases." +msgstr ":ref:`型別參數 `\\ 可以存在於類別、函式和型別別名上。" + +#: ../../library/ast.rst:1869 +msgid "" +"A :class:`typing.TypeVar`. ``name`` is the name of the type variable. " +"``bound`` is the bound or constraints, if any. If ``bound`` is a :class:" +"`Tuple`, it represents constraints; otherwise it represents the bound. " +"``default_value`` is the default value; if the :class:`!TypeVar` has no " +"default, this attribute will be set to ``None``." +msgstr "" +"一個 :class:`typing.TypeVar`。``name`` 是型別變數的名稱。``bound`` 是（如果有" +"存在的）界限 (bound) 或約束 (constraint)。如果 ``bound`` 是一個 :class:" +"`Tuple`，它代表約束；否則它代表界限。``default_value`` 為預設值；如果 :class:" +"`!TypeVar` 沒有預設值，那此屬性會被設為 ``None``。" + +#: ../../library/ast.rst:1875 +msgid "" +">>> print(ast.dump(ast.parse(\"type Alias[T: int = bool] = list[T]\"), " +"indent=4))\n" +"Module(\n" +" body=[\n" +" TypeAlias(\n" +" name=Name(id='Alias', ctx=Store()),\n" +" type_params=[\n" +" TypeVar(\n" +" name='T',\n" +" bound=Name(id='int', ctx=Load()),\n" +" default_value=Name(id='bool', ctx=Load()))],\n" +" value=Subscript(\n" +" value=Name(id='list', ctx=Load()),\n" +" slice=Name(id='T', ctx=Load()),\n" +" ctx=Load()))])" +msgstr "" +">>> print(ast.dump(ast.parse(\"type Alias[T: int = bool] = list[T]\"), " +"indent=4))\n" +"Module(\n" +" body=[\n" +" TypeAlias(\n" +" name=Name(id='Alias', ctx=Store()),\n" +" type_params=[\n" +" TypeVar(\n" +" name='T',\n" +" bound=Name(id='int', ctx=Load()),\n" +" default_value=Name(id='bool', ctx=Load()))],\n" +" value=Subscript(\n" +" value=Name(id='list', ctx=Load()),\n" +" slice=Name(id='T', ctx=Load()),\n" +" ctx=Load()))])" + +#: ../../library/ast.rst:1894 ../../library/ast.rst:1929 +#: ../../library/ast.rst:1961 +msgid "Added the *default_value* parameter." +msgstr "新增 *default_value* 參數。" + +#: ../../library/ast.rst:1899 +msgid "" +"A :class:`typing.ParamSpec`. ``name`` is the name of the parameter " +"specification. ``default_value`` is the default value; if the :class:`!" +"ParamSpec` has no default, this attribute will be set to ``None``." +msgstr "" +"一個 :class:`typing.ParamSpec`。``name`` 是參數規範的名稱。``default_value`` " +"是預設值；如果 :class:`!ParamSpec` 沒有預設值，則該屬性將設定為 ``None``。" + +#: ../../library/ast.rst:1903 +msgid "" +">>> print(ast.dump(ast.parse(\"type Alias[**P = [int, str]] = Callable[P, " +"int]\"), indent=4))\n" +"Module(\n" +" body=[\n" +" TypeAlias(\n" +" name=Name(id='Alias', ctx=Store()),\n" +" type_params=[\n" +" ParamSpec(\n" +" name='P',\n" +" default_value=List(\n" +" elts=[\n" +" Name(id='int', ctx=Load()),\n" +" Name(id='str', ctx=Load())],\n" +" ctx=Load()))],\n" +" value=Subscript(\n" +" value=Name(id='Callable', ctx=Load()),\n" +" slice=Tuple(\n" +" elts=[\n" +" Name(id='P', ctx=Load()),\n" +" Name(id='int', ctx=Load())],\n" +" ctx=Load()),\n" +" ctx=Load()))])" +msgstr "" +">>> print(ast.dump(ast.parse(\"type Alias[**P = [int, str]] = Callable[P, " +"int]\"), indent=4))\n" +"Module(\n" +" body=[\n" +" TypeAlias(\n" +" name=Name(id='Alias', ctx=Store()),\n" +" type_params=[\n" +" ParamSpec(\n" +" name='P',\n" +" default_value=List(\n" +" elts=[\n" +" Name(id='int', ctx=Load()),\n" +" Name(id='str', ctx=Load())],\n" +" ctx=Load()))],\n" +" value=Subscript(\n" +" value=Name(id='Callable', ctx=Load()),\n" +" slice=Tuple(\n" +" elts=[\n" +" Name(id='P', ctx=Load()),\n" +" Name(id='int', ctx=Load())],\n" +" ctx=Load()),\n" +" ctx=Load()))])" + +#: ../../library/ast.rst:1934 +msgid "" +"A :class:`typing.TypeVarTuple`. ``name`` is the name of the type variable " +"tuple. ``default_value`` is the default value; if the :class:`!TypeVarTuple` " +"has no default, this attribute will be set to ``None``." +msgstr "" +"一個 :class:`typing.TypeVarTuple`。``name`` 是型別變數元組的名稱。" +"``default_value`` 為預設值；如果 :class:`!TypeVarTuple` 沒有預設值，那此屬性" +"會被設為 ``None``。" + +#: ../../library/ast.rst:1938 +msgid "" +">>> print(ast.dump(ast.parse(\"type Alias[*Ts = ()] = tuple[*Ts]\"), " +"indent=4))\n" +"Module(\n" +" body=[\n" +" TypeAlias(\n" +" name=Name(id='Alias', ctx=Store()),\n" +" type_params=[\n" +" TypeVarTuple(\n" +" name='Ts',\n" +" default_value=Tuple(ctx=Load()))],\n" +" value=Subscript(\n" +" value=Name(id='tuple', ctx=Load()),\n" +" slice=Tuple(\n" +" elts=[\n" +" Starred(\n" +" value=Name(id='Ts', ctx=Load()),\n" +" ctx=Load())],\n" +" ctx=Load()),\n" +" ctx=Load()))])" +msgstr "" +">>> print(ast.dump(ast.parse(\"type Alias[*Ts = ()] = tuple[*Ts]\"), " +"indent=4))\n" +"Module(\n" +" body=[\n" +" TypeAlias(\n" +" name=Name(id='Alias', ctx=Store()),\n" +" type_params=[\n" +" TypeVarTuple(\n" +" name='Ts',\n" +" default_value=Tuple(ctx=Load()))],\n" +" value=Subscript(\n" +" value=Name(id='tuple', ctx=Load()),\n" +" slice=Tuple(\n" +" elts=[\n" +" Starred(\n" +" value=Name(id='Ts', ctx=Load()),\n" +" ctx=Load())],\n" +" ctx=Load()),\n" +" ctx=Load()))])" + +#: ../../library/ast.rst:1965 +msgid "Function and class definitions" +msgstr "函式和類別定義" + +#: ../../library/ast.rst:1969 +msgid "A function definition." +msgstr "一個函式定義。" + +#: ../../library/ast.rst:1971 +msgid "``name`` is a raw string of the function name." +msgstr "``name`` 是函式名稱的原始字串。" + +#: ../../library/ast.rst:1972 +msgid "``args`` is an :class:`arguments` node." +msgstr "``args`` 是一個 :class:`arguments` 節點。" + +#: ../../library/ast.rst:1973 +msgid "``body`` is the list of nodes inside the function." +msgstr "``body`` 是函式內節點的串列。" + +#: ../../library/ast.rst:1974 +msgid "" +"``decorator_list`` is the list of decorators to be applied, stored outermost " +"first (i.e. the first in the list will be applied last)." +msgstr "" +"``decorator_list`` 是要應用的裝飾器串列，在最外層者會被儲存在首位（即串列中首" +"位將會是最後一個被應用的那個）。" + +#: ../../library/ast.rst:1976 +msgid "``returns`` is the return annotation." +msgstr "``returns`` 是回傳註釋。" + +#: ../../library/ast.rst:1977 ../../library/ast.rst:2140 +msgid "``type_params`` is a list of :ref:`type parameters `." +msgstr "``type_params`` 是\\ :ref:`型別參數 `\\ 的串列。" + +#: ../../library/ast.rst:1983 ../../library/ast.rst:2167 +#: ../../library/ast.rst:2178 +msgid "Added ``type_params``." +msgstr "新增了 ``type_params``。" + +#: ../../library/ast.rst:1989 +msgid "" +"``lambda`` is a minimal function definition that can be used inside an " +"expression. Unlike :class:`FunctionDef`, ``body`` holds a single node." +msgstr "" +"``lambda`` 是可以在運算式內使用的最小函式定義。與 :class:`FunctionDef` 不同，" +"``body`` 保存單個節點。" + +#: ../../library/ast.rst:1992 +msgid "" +">>> print(ast.dump(ast.parse('lambda x,y: ...'), indent=4))\n" +"Module(\n" +" body=[\n" +" Expr(\n" +" value=Lambda(\n" +" args=arguments(\n" +" args=[\n" +" arg(arg='x'),\n" +" arg(arg='y')]),\n" +" body=Constant(value=Ellipsis)))])" +msgstr "" +">>> print(ast.dump(ast.parse('lambda x,y: ...'), indent=4))\n" +"Module(\n" +" body=[\n" +" Expr(\n" +" value=Lambda(\n" +" args=arguments(\n" +" args=[\n" +" arg(arg='x'),\n" +" arg(arg='y')]),\n" +" body=Constant(value=Ellipsis)))])" + +#: ../../library/ast.rst:2008 +msgid "The arguments for a function." +msgstr "函式的引數。" + +#: ../../library/ast.rst:2010 +msgid "" +"``posonlyargs``, ``args`` and ``kwonlyargs`` are lists of :class:`arg` nodes." +msgstr "" +"``posonlyargs``、``args`` 和 ``kwonlyargs`` 是 :class:`arg` 節點的串列。" + +#: ../../library/ast.rst:2011 +msgid "" +"``vararg`` and ``kwarg`` are single :class:`arg` nodes, referring to the " +"``*args, **kwargs`` parameters." +msgstr "" +"``vararg`` 和 ``kwarg`` 是單個 :class:`arg` 節點，指的是 ``*args, **kwargs`` " +"參數。" + +#: ../../library/ast.rst:2013 +msgid "" +"``kw_defaults`` is a list of default values for keyword-only arguments. If " +"one is ``None``, the corresponding argument is required." +msgstr "" +"``kw_defaults`` 是僅限關鍵字引數的預設值串列。如果其中某個為 ``None``，則相應" +"參數就會是必要的。" + +#: ../../library/ast.rst:2015 +msgid "" +"``defaults`` is a list of default values for arguments that can be passed " +"positionally. If there are fewer defaults, they correspond to the last n " +"arguments." +msgstr "" +"``defaults`` 是可以按位置傳遞的引數的預設值串列。如果預設值較少，則它們對應於" +"最後 n 個引數。" + +#: ../../library/ast.rst:2022 +msgid "" +"A single argument in a list. ``arg`` is a raw string of the argument name; " +"``annotation`` is its annotation, such as a :class:`Name` node." +msgstr "" +"串列中的單個引數。``arg`` 是引數名稱的原始字串，``annotation`` 是它的註釋，例" +"如 :class:`Name` 節點。" + +#: ../../library/ast.rst:2027 +msgid "" +"``type_comment`` is an optional string with the type annotation as a comment" +msgstr "``type_comment`` 是一個可選字串，其註解為型別註釋" + +#: ../../library/ast.rst:2029 +msgid "" +">>> print(ast.dump(ast.parse(\"\"\"\\\n" +"... @decorator1\n" +"... @decorator2\n" +"... def f(a: 'annotation', b=1, c=2, *d, e, f=3, **g) -> 'return " +"annotation':\n" +"... pass\n" +"... \"\"\"), indent=4))\n" +"Module(\n" +" body=[\n" +" FunctionDef(\n" +" name='f',\n" +" args=arguments(\n" +" args=[\n" +" arg(\n" +" arg='a',\n" +" annotation=Constant(value='annotation')),\n" +" arg(arg='b'),\n" +" arg(arg='c')],\n" +" vararg=arg(arg='d'),\n" +" kwonlyargs=[\n" +" arg(arg='e'),\n" +" arg(arg='f')],\n" +" kw_defaults=[\n" +" None,\n" +" Constant(value=3)],\n" +" kwarg=arg(arg='g'),\n" +" defaults=[\n" +" Constant(value=1),\n" +" Constant(value=2)]),\n" +" body=[\n" +" Pass()],\n" +" decorator_list=[\n" +" Name(id='decorator1', ctx=Load()),\n" +" Name(id='decorator2', ctx=Load())],\n" +" returns=Constant(value='return annotation'))])" +msgstr "" +">>> print(ast.dump(ast.parse(\"\"\"\\\n" +"... @decorator1\n" +"... @decorator2\n" +"... def f(a: 'annotation', b=1, c=2, *d, e, f=3, **g) -> 'return " +"annotation':\n" +"... pass\n" +"... \"\"\"), indent=4))\n" +"Module(\n" +" body=[\n" +" FunctionDef(\n" +" name='f',\n" +" args=arguments(\n" +" args=[\n" +" arg(\n" +" arg='a',\n" +" annotation=Constant(value='annotation')),\n" +" arg(arg='b'),\n" +" arg(arg='c')],\n" +" vararg=arg(arg='d'),\n" +" kwonlyargs=[\n" +" arg(arg='e'),\n" +" arg(arg='f')],\n" +" kw_defaults=[\n" +" None,\n" +" Constant(value=3)],\n" +" kwarg=arg(arg='g'),\n" +" defaults=[\n" +" Constant(value=1),\n" +" Constant(value=2)]),\n" +" body=[\n" +" Pass()],\n" +" decorator_list=[\n" +" Name(id='decorator1', ctx=Load()),\n" +" Name(id='decorator2', ctx=Load())],\n" +" returns=Constant(value='return annotation'))])" + +#: ../../library/ast.rst:2069 +msgid "A ``return`` statement." +msgstr "一個 ``return`` 陳述式。" + +#: ../../library/ast.rst:2071 +msgid "" +">>> print(ast.dump(ast.parse('return 4'), indent=4))\n" +"Module(\n" +" body=[\n" +" Return(\n" +" value=Constant(value=4))])" +msgstr "" +">>> print(ast.dump(ast.parse('return 4'), indent=4))\n" +"Module(\n" +" body=[\n" +" Return(\n" +" value=Constant(value=4))])" + +#: ../../library/ast.rst:2083 +msgid "" +"A ``yield`` or ``yield from`` expression. Because these are expressions, " +"they must be wrapped in an :class:`Expr` node if the value sent back is not " +"used." +msgstr "" +"一個 ``yield`` 或 ``yield from`` 運算式。因為這些是運算式，所以如果不使用發送" +"回來的值，則必須將它們包裝在 :class:`Expr` 節點中。" + +#: ../../library/ast.rst:2086 +msgid "" +">>> print(ast.dump(ast.parse('yield x'), indent=4))\n" +"Module(\n" +" body=[\n" +" Expr(\n" +" value=Yield(\n" +" value=Name(id='x', ctx=Load())))])\n" +"\n" +">>> print(ast.dump(ast.parse('yield from x'), indent=4))\n" +"Module(\n" +" body=[\n" +" Expr(\n" +" value=YieldFrom(\n" +" value=Name(id='x', ctx=Load())))])" +msgstr "" +">>> print(ast.dump(ast.parse('yield x'), indent=4))\n" +"Module(\n" +" body=[\n" +" Expr(\n" +" value=Yield(\n" +" value=Name(id='x', ctx=Load())))])\n" +"\n" +">>> print(ast.dump(ast.parse('yield from x'), indent=4))\n" +"Module(\n" +" body=[\n" +" Expr(\n" +" value=YieldFrom(\n" +" value=Name(id='x', ctx=Load())))])" + +#: ../../library/ast.rst:2106 +msgid "" +"``global`` and ``nonlocal`` statements. ``names`` is a list of raw strings." +msgstr "``global`` 和 ``nonlocal`` 陳述式。``names`` 是原始字串的串列。" + +#: ../../library/ast.rst:2108 +msgid "" +">>> print(ast.dump(ast.parse('global x,y,z'), indent=4))\n" +"Module(\n" +" body=[\n" +" Global(\n" +" names=[\n" +" 'x',\n" +" 'y',\n" +" 'z'])])\n" +"\n" +">>> print(ast.dump(ast.parse('nonlocal x,y,z'), indent=4))\n" +"Module(\n" +" body=[\n" +" Nonlocal(\n" +" names=[\n" +" 'x',\n" +" 'y',\n" +" 'z'])])" +msgstr "" +">>> print(ast.dump(ast.parse('global x,y,z'), indent=4))\n" +"Module(\n" +" body=[\n" +" Global(\n" +" names=[\n" +" 'x',\n" +" 'y',\n" +" 'z'])])\n" +"\n" +">>> print(ast.dump(ast.parse('nonlocal x,y,z'), indent=4))\n" +"Module(\n" +" body=[\n" +" Nonlocal(\n" +" names=[\n" +" 'x',\n" +" 'y',\n" +" 'z'])])" + +#: ../../library/ast.rst:2131 +msgid "A class definition." +msgstr "一個類別定義。" + +#: ../../library/ast.rst:2133 +msgid "``name`` is a raw string for the class name" +msgstr "``name`` 是類別名稱的原始字串" + +#: ../../library/ast.rst:2134 +msgid "``bases`` is a list of nodes for explicitly specified base classes." +msgstr "``bases`` 是被顯式指定的基底類別節點串列。" + +#: ../../library/ast.rst:2135 +msgid "" +"``keywords`` is a list of :class:`.keyword` nodes, principally for " +"'metaclass'. Other keywords will be passed to the metaclass, as per :pep:" +"`3115`." +msgstr "" +"``keywords`` 是一個 :class:`.keyword` 節點的串列，主要用於 'metaclass'（元類" +"別）。如 :pep:`3115` 所述，其他關鍵字將被傳遞到 metaclass。" + +#: ../../library/ast.rst:2137 +msgid "" +"``body`` is a list of nodes representing the code within the class " +"definition." +msgstr "``body`` 是表示類別定義中程式碼的節點串列。" + +#: ../../library/ast.rst:2139 +msgid "``decorator_list`` is a list of nodes, as in :class:`FunctionDef`." +msgstr "``decorator_list`` 是一個節點串列，如 :class:`FunctionDef` 中所示。" + +#: ../../library/ast.rst:2142 +msgid "" +">>> print(ast.dump(ast.parse(\"\"\"\\\n" +"... @decorator1\n" +"... @decorator2\n" +"... class Foo(base1, base2, metaclass=meta):\n" +"... pass\n" +"... \"\"\"), indent=4))\n" +"Module(\n" +" body=[\n" +" ClassDef(\n" +" name='Foo',\n" +" bases=[\n" +" Name(id='base1', ctx=Load()),\n" +" Name(id='base2', ctx=Load())],\n" +" keywords=[\n" +" keyword(\n" +" arg='metaclass',\n" +" value=Name(id='meta', ctx=Load()))],\n" +" body=[\n" +" Pass()],\n" +" decorator_list=[\n" +" Name(id='decorator1', ctx=Load()),\n" +" Name(id='decorator2', ctx=Load())])])" +msgstr "" +">>> print(ast.dump(ast.parse(\"\"\"\\\n" +"... @decorator1\n" +"... @decorator2\n" +"... class Foo(base1, base2, metaclass=meta):\n" +"... pass\n" +"... \"\"\"), indent=4))\n" +"Module(\n" +" body=[\n" +" ClassDef(\n" +" name='Foo',\n" +" bases=[\n" +" Name(id='base1', ctx=Load()),\n" +" Name(id='base2', ctx=Load())],\n" +" keywords=[\n" +" keyword(\n" +" arg='metaclass',\n" +" value=Name(id='meta', ctx=Load()))],\n" +" body=[\n" +" Pass()],\n" +" decorator_list=[\n" +" Name(id='decorator1', ctx=Load()),\n" +" Name(id='decorator2', ctx=Load())])])" + +#: ../../library/ast.rst:2171 +msgid "Async and await" +msgstr "async 和 await" + +#: ../../library/ast.rst:2175 +msgid "" +"An ``async def`` function definition. Has the same fields as :class:" +"`FunctionDef`." +msgstr "一個 ``async def`` 函式定義。與 :class:`FunctionDef` 具有相同的欄位。" + +#: ../../library/ast.rst:2184 +msgid "" +"An ``await`` expression. ``value`` is what it waits for. Only valid in the " +"body of an :class:`AsyncFunctionDef`." +msgstr "" +"一個 ``await`` 運算式。``value`` 是它等待的東西。僅在 :class:" +"`AsyncFunctionDef` 主體 (body) 中有效。" + +#: ../../library/ast.rst:2187 +msgid "" +">>> print(ast.dump(ast.parse(\"\"\"\\\n" +"... async def f():\n" +"... await other_func()\n" +"... \"\"\"), indent=4))\n" +"Module(\n" +" body=[\n" +" AsyncFunctionDef(\n" +" name='f',\n" +" args=arguments(),\n" +" body=[\n" +" Expr(\n" +" value=Await(\n" +" value=Call(\n" +" func=Name(id='other_func', ctx=Load()))))])])" +msgstr "" +">>> print(ast.dump(ast.parse(\"\"\"\\\n" +"... async def f():\n" +"... await other_func()\n" +"... \"\"\"), indent=4))\n" +"Module(\n" +" body=[\n" +" AsyncFunctionDef(\n" +" name='f',\n" +" args=arguments(),\n" +" body=[\n" +" Expr(\n" +" value=Await(\n" +" value=Call(\n" +" func=Name(id='other_func', ctx=Load()))))])])" + +#: ../../library/ast.rst:2208 +msgid "" +"``async for`` loops and ``async with`` context managers. They have the same " +"fields as :class:`For` and :class:`With`, respectively. Only valid in the " +"body of an :class:`AsyncFunctionDef`." +msgstr "" +"``async for`` 迴圈和 ``async with`` 情境管理器。它們分別具有與 :class:`For` " +"和 :class:`With` 相同的欄位。僅在 :class:`AsyncFunctionDef` 主體中有效。" + +#: ../../library/ast.rst:2213 +msgid "" +"When a string is parsed by :func:`ast.parse`, operator nodes (subclasses of :" +"class:`ast.operator`, :class:`ast.unaryop`, :class:`ast.cmpop`, :class:`ast." +"boolop` and :class:`ast.expr_context`) on the returned tree will be " +"singletons. Changes to one will be reflected in all other occurrences of the " +"same value (for example, :class:`ast.Add`)." +msgstr "" +"當字串被 :func:`ast.parse` 剖析時，回傳樹的運算子節點（:class:`ast." +"operator`、:class:`ast.unaryop`、:class:`ast.cmpop`、:class:`ast.boolop` 和 :" +"class:`ast.expr_context` 的子類別）將是單例。對其中之一的更改將反映在所有其他" +"出現的相同值中（例如 :class:`ast.Add`）。" + +#: ../../library/ast.rst:2221 +msgid ":mod:`ast` helpers" +msgstr ":mod:`ast` 輔助程式" + +#: ../../library/ast.rst:2223 +msgid "" +"Apart from the node classes, the :mod:`ast` module defines these utility " +"functions and classes for traversing abstract syntax trees:" +msgstr "" +"除了節點類別之外，:mod:`ast` 模組還定義了這些用於遍歷 (traverse) 抽象語法樹的" +"實用函式和類別：" + +#: ../../library/ast.rst:2228 +msgid "" +"Parse the source into an AST node. Equivalent to ``compile(source, " +"filename, mode, flags=FLAGS_VALUE, optimize=optimize)``, where " +"``FLAGS_VALUE`` is ``ast.PyCF_ONLY_AST`` if ``optimize <= 0`` and ``ast." +"PyCF_OPTIMIZED_AST`` otherwise." +msgstr "" +"將原始碼剖析為 AST 節點，相當於 ``compile(source, filename, mode, " +"flags=FLAGS_VALUE, optimize=optimize)``，其中 ``FLAGS_VALUE`` 在 ``optimize " +"<= 0`` 時為 ``ast.PyCF_ONLY_AST``，否則為 ``ast.PyCF_OPTIMIZED_AST``。" + +#: ../../library/ast.rst:2233 +msgid "" +"If ``type_comments=True`` is given, the parser is modified to check and " +"return type comments as specified by :pep:`484` and :pep:`526`. This is " +"equivalent to adding :data:`ast.PyCF_TYPE_COMMENTS` to the flags passed to :" +"func:`compile`. This will report syntax errors for misplaced type " +"comments. Without this flag, type comments will be ignored, and the " +"``type_comment`` field on selected AST nodes will always be ``None``. In " +"addition, the locations of ``# type: ignore`` comments will be returned as " +"the ``type_ignores`` attribute of :class:`Module` (otherwise it is always an " +"empty list)." +msgstr "" +"如果給定 ``type_comments=True``，剖析器將被修改為檢查並回傳 :pep:`484` 和 :" +"pep:`526` 指定的型別註釋。這相當於將 :data:`ast.PyCF_TYPE_COMMENTS` 新增到傳" +"遞給 :func:`compile` 的旗標中。這將報告錯誤型別註釋的語法錯誤。如果沒有此旗" +"標，型別註釋將被忽略，並且所選 AST 節點上的 ``type_comment`` 欄位將始終為 " +"``None``。此外，``# type: ignore`` 註釋的位置將作為 :class:`Module` 的 " +"``type_ignores`` 屬性回傳（否則它始終是一個空串列）。" + +#: ../../library/ast.rst:2243 +msgid "" +"In addition, if ``mode`` is ``'func_type'``, the input syntax is modified to " +"correspond to :pep:`484` \"signature type comments\", e.g. ``(str, int) -> " +"List[str]``." +msgstr "" +"此外，如果 ``mode`` 是 ``'func_type'``，則輸入語法將會依據 :pep:`484`\\ 「簽" +"名型別註解 (signature type comments)」而被修改，例如 ``(str, int) -> " +"List[str]``。" + +#: ../../library/ast.rst:2247 +msgid "" +"Setting ``feature_version`` to a tuple ``(major, minor)`` will result in a " +"\"best-effort\" attempt to parse using that Python version's grammar. For " +"example, setting ``feature_version=(3, 9)`` will attempt to disallow parsing " +"of :keyword:`match` statements. Currently ``major`` must equal to ``3``. The " +"lowest supported version is ``(3, 7)`` (and this may increase in future " +"Python versions); the highest is ``sys.version_info[0:2]``. \"Best-effort\" " +"attempt means there is no guarantee that the parse (or success of the parse) " +"is the same as when run on the Python version corresponding to " +"``feature_version``." +msgstr "" +"將 ``feature_version`` 設定為元組 ``(major, minor)`` 將「盡可能」嘗試使用該 " +"Python 版本的文法進行剖析。目前 ``major`` 必須等於 ``3``。例如，設定 " +"``feature_version=(3, 9)`` 將嘗試禁止剖析 :keyword:`match` 陳述式。目前 " +"``major`` 必須為 ``3``、支援的最低版本為 ``(3, 7)``\\ （這在未來的 Python 版" +"本中可能會增加）；最高的是 ``sys.version_info[0:2]``。「盡可能」嘗試意味著不" +"能保證剖析（或剖析的成功）與在與 ``feature_version`` 對應的 Python 版本上運行" +"時相同。" + +#: ../../library/ast.rst:2257 +msgid "" +"If source contains a null character (``\\0``), :exc:`ValueError` is raised." +msgstr "如果來源包含 null 字元 (``\\0``)，則會引發 :exc:`ValueError`。" + +#: ../../library/ast.rst:2260 +msgid "" +"Note that successfully parsing source code into an AST object doesn't " +"guarantee that the source code provided is valid Python code that can be " +"executed as the compilation step can raise further :exc:`SyntaxError` " +"exceptions. For instance, the source ``return 42`` generates a valid AST " +"node for a return statement, but it cannot be compiled alone (it needs to be " +"inside a function node)." +msgstr "" +"請注意，成功將原始碼剖析為 AST 物件並不能保證提供的原始碼是可以執行的有效 " +"Python 程式碼，因為編譯步驟可能會引發進一步的 :exc:`SyntaxError` 例外。例如，" +"原始的 ``return 42`` 為 return 陳述式生成一個有效的 AST 節點，但它不能單獨編" +"譯（它需要位於函式節點內）。" + +#: ../../library/ast.rst:2267 +msgid "" +"In particular, :func:`ast.parse` won't do any scoping checks, which the " +"compilation step does." +msgstr "" +"特別是 :func:`ast.parse` 不會執行任何範圍檢查，而編譯步驟才會執行此操作。" + +#: ../../library/ast.rst:2271 +msgid "" +"It is possible to crash the Python interpreter with a sufficiently large/" +"complex string due to stack depth limitations in Python's AST compiler." +msgstr "" +"由於 Python AST 編譯器中的堆疊 (stack) 深度限制，太大或太複雜的字串可能會導" +"致 Python 直譯器崩潰。" + +#: ../../library/ast.rst:2275 +msgid "Added ``type_comments``, ``mode='func_type'`` and ``feature_version``." +msgstr "新增 ``type_comments``、``mode='func_type'`` 與 ``feature_version``。" + +#: ../../library/ast.rst:2278 +msgid "" +"The minimum supported version for ``feature_version`` is now ``(3, 7)``. The " +"``optimize`` argument was added." +msgstr "" +"``feature_version`` 的最低支援版本現在是 ``(3, 7)``。新增了 ``optimize`` 引" +"數。" + +#: ../../library/ast.rst:2285 +msgid "" +"Unparse an :class:`ast.AST` object and generate a string with code that " +"would produce an equivalent :class:`ast.AST` object if parsed back with :" +"func:`ast.parse`." +msgstr "" +"反剖析 :class:`ast.AST` 物件並生成一個帶有程式碼的字串，如果使用 :func:`ast." +"parse` 剖析回來，該程式碼將生成等效的 :class:`ast.AST` 物件。" + +#: ../../library/ast.rst:2290 +msgid "" +"The produced code string will not necessarily be equal to the original code " +"that generated the :class:`ast.AST` object (without any compiler " +"optimizations, such as constant tuples/frozensets)." +msgstr "" +"生成的程式碼字串不一定等於生成 :class:`ast.AST` 物件的原始程式碼（沒有任何編" +"譯器最佳化，例如常數元組/凍結集合）。" + +#: ../../library/ast.rst:2295 +msgid "" +"Trying to unparse a highly complex expression would result with :exc:" +"`RecursionError`." +msgstr "嘗試剖析高度複雜的運算式會導致 :exc:`RecursionError`。" + +#: ../../library/ast.rst:2303 +msgid "" +"Evaluate an expression node or a string containing only a Python literal or " +"container display. The string or node provided may only consist of the " +"following Python literal structures: strings, bytes, numbers, tuples, lists, " +"dicts, sets, booleans, ``None`` and ``Ellipsis``." +msgstr "" +"為僅包含 Python 文本或容器之顯示的運算式節點或字串來求值。提供的字串或節點只" +"能包含以下 Python 文本結構：字串、位元組、數字、元組、串列、字典、集合、布林" +"值、``None`` 和 ``Ellipsis``。" + +#: ../../library/ast.rst:2308 +msgid "" +"This can be used for evaluating strings containing Python values without the " +"need to parse the values oneself. It is not capable of evaluating " +"arbitrarily complex expressions, for example involving operators or indexing." +msgstr "" +"這可用於為包含 Python 值的字串求值，而無需自己剖析這些值。它無法計算任意複雜" +"的運算式，例如涉及運算子或索引。" + +#: ../../library/ast.rst:2313 +msgid "" +"This function had been documented as \"safe\" in the past without defining " +"what that meant. That was misleading. This is specifically designed not to " +"execute Python code, unlike the more general :func:`eval`. There is no " +"namespace, no name lookups, or ability to call out. But it is not free from " +"attack: A relatively small input can lead to memory exhaustion or to C stack " +"exhaustion, crashing the process. There is also the possibility for " +"excessive CPU consumption denial of service on some inputs. Calling it on " +"untrusted data is thus not recommended." +msgstr "" +"該函式過去被記錄為「安全」，但沒有定義其含義，這有點誤導讀者，它是特別設計為" +"不去執行 Python 程式碼，與更通用的 :func:`eval` 不同。沒有命名空間、沒有名稱" +"查找、也沒有呼叫的能力。但它也不能免受攻擊：相對較小的輸入可能會導致記憶體耗" +"盡或 C 堆疊耗盡，從而導致行程崩潰。某些輸入也可能會出現 CPU 消耗過多而導致拒" +"絕服務的情況。因此不建議在不受信任的資料上呼叫它。" + +#: ../../library/ast.rst:2323 +msgid "" +"It is possible to crash the Python interpreter due to stack depth " +"limitations in Python's AST compiler." +msgstr "由於 Python AST 編譯器的堆疊深度限制，Python 直譯器可能會崩潰。" + +#: ../../library/ast.rst:2326 +msgid "" +"It can raise :exc:`ValueError`, :exc:`TypeError`, :exc:`SyntaxError`, :exc:" +"`MemoryError` and :exc:`RecursionError` depending on the malformed input." +msgstr "" +"它可能會引發 :exc:`ValueError`、:exc:`TypeError`、:exc:`SyntaxError`、:exc:" +"`MemoryError` 和 :exc:`RecursionError`，具體取決於格式錯誤的輸入。" + +#: ../../library/ast.rst:2330 +msgid "Now allows bytes and set literals." +msgstr "現在允許位元組和集合文本 (set literal)。" + +#: ../../library/ast.rst:2333 +msgid "Now supports creating empty sets with ``'set()'``." +msgstr "現在支援使用 ``'set()'`` 建立空集合。" + +#: ../../library/ast.rst:2336 +msgid "For string inputs, leading spaces and tabs are now stripped." +msgstr "對於字串輸入，前導空格和定位字元 (tab) 現在已被去除。" + +#: ../../library/ast.rst:2342 +msgid "" +"Return the docstring of the given *node* (which must be a :class:" +"`FunctionDef`, :class:`AsyncFunctionDef`, :class:`ClassDef`, or :class:" +"`Module` node), or ``None`` if it has no docstring. If *clean* is true, " +"clean up the docstring's indentation with :func:`inspect.cleandoc`." +msgstr "" +"回傳給定 *node* 的文件字串 (docstring)（必須是 :class:`FunctionDef`、:class:" +"`AsyncFunctionDef`、:class:`ClassDef` 或 :class:`Module` 節點）或如果它沒有文" +"件字串則為 ``None``。如果 *clean* 為 true，則使用 :func:`inspect.cleandoc` 清" +"理文件字串的縮排。" + +#: ../../library/ast.rst:2348 +msgid ":class:`AsyncFunctionDef` is now supported." +msgstr "目前已支援 :class:`AsyncFunctionDef`。" + +#: ../../library/ast.rst:2354 +msgid "" +"Get source code segment of the *source* that generated *node*. If some " +"location information (:attr:`~ast.AST.lineno`, :attr:`~ast.AST.end_lineno`, :" +"attr:`~ast.AST.col_offset`, or :attr:`~ast.AST.end_col_offset`) is missing, " +"return ``None``." +msgstr "" +"取得生成 *node* 的 *source* 的原始碼片段。如果某些位置資訊（:attr:`~ast.AST." +"lineno`、:attr:`~ast.AST.end_lineno`、:attr:`~ast.AST.col_offset` 或 :attr:" +"`~ast.AST.end_col_offset`）遺漏，則回傳 ``None``。" + +#: ../../library/ast.rst:2358 +msgid "" +"If *padded* is ``True``, the first line of a multi-line statement will be " +"padded with spaces to match its original position." +msgstr "" +"如果 *padded* 為 ``True``，則多列陳述式的第一列將用空格填充 (padded) 以匹配其" +"原始位置。" + +#: ../../library/ast.rst:2366 +msgid "" +"When you compile a node tree with :func:`compile`, the compiler expects :" +"attr:`~ast.AST.lineno` and :attr:`~ast.AST.col_offset` attributes for every " +"node that supports them. This is rather tedious to fill in for generated " +"nodes, so this helper adds these attributes recursively where not already " +"set, by setting them to the values of the parent node. It works recursively " +"starting at *node*." +msgstr "" +"當你使用 :func:`compile` 編譯節點樹時，對於每個有支援 :attr:`~ast.AST." +"lineno` 和 :attr:`~ast.AST.col_offset` 屬性之節點，編譯器預期他們的這些屬性都" +"要存在。填入生成的節點相當繁瑣，因此該輔助工具透過將這些屬性設定為父節點的" +"值，在尚未設定的地方遞迴地新增這些屬性。它從 *node* 開始遞迴地作用。" + +#: ../../library/ast.rst:2375 +msgid "" +"Increment the line number and end line number of each node in the tree " +"starting at *node* by *n*. This is useful to \"move code\" to a different " +"location in a file." +msgstr "" +"將樹中從 *node* 開始的每個節點的列號和結束列號增加 *n*。這對於「移動程式碼」" +"到檔案中的不同位置很有用。" + +#: ../../library/ast.rst:2382 +msgid "" +"Copy source location (:attr:`~ast.AST.lineno`, :attr:`~ast.AST.col_offset`, :" +"attr:`~ast.AST.end_lineno`, and :attr:`~ast.AST.end_col_offset`) from " +"*old_node* to *new_node* if possible, and return *new_node*." +msgstr "" +"如果可行，將原始位置（:attr:`~ast.AST.lineno`、:attr:`~ast.AST.col_offset`、:" +"attr:`~ast.AST.end_lineno` 和 :attr:`~ast.AST.end_col_offset` ）從 " +"*old_node* 複製到 *new_node*，並回傳 *new_node* 。" + +#: ../../library/ast.rst:2389 +msgid "" +"Yield a tuple of ``(fieldname, value)`` for each field in ``node._fields`` " +"that is present on *node*." +msgstr "" +"為 *node* 上存在的 ``node._fields`` 中的每個欄位生成一個 ``(fieldname, " +"value)`` 元組。" + +#: ../../library/ast.rst:2395 +msgid "" +"Yield all direct child nodes of *node*, that is, all fields that are nodes " +"and all items of fields that are lists of nodes." +msgstr "" +"生成 *node* 的所有直接子節點，即作為節點的所有欄位以及作為節點串列欄位的所有" +"項目。" + +#: ../../library/ast.rst:2401 +msgid "" +"Recursively yield all descendant nodes in the tree starting at *node* " +"(including *node* itself), in no specified order. This is useful if you " +"only want to modify nodes in place and don't care about the context." +msgstr "" +"遞迴地生成樹中從 *node* 開始的所有後代節點（包括 *node* 本身），不按指定順" +"序。如果你只想就地修改節點而不關心情境，這非常有用。" + +#: ../../library/ast.rst:2408 +msgid "" +"A node visitor base class that walks the abstract syntax tree and calls a " +"visitor function for every node found. This function may return a value " +"which is forwarded by the :meth:`visit` method." +msgstr "" +"節點瀏覽者基底類別，它遍歷抽象語法樹並為找到的每個節點呼叫瀏覽者函式。該函式" +"可能會回傳一個由 :meth:`visit` 方法轉發的值。" + +#: ../../library/ast.rst:2412 +msgid "" +"This class is meant to be subclassed, with the subclass adding visitor " +"methods." +msgstr "這個類別應該被子類別化，子類別新增瀏覽者方法。" + +#: ../../library/ast.rst:2417 +msgid "" +"Visit a node. The default implementation calls the method called :samp:" +"`self.visit_{classname}` where *classname* is the name of the node class, " +"or :meth:`generic_visit` if that method doesn't exist." +msgstr "" +"瀏覽一個節點。預設實作呼叫名為 :samp:`self.visit_{classname}` 的方法，其中 " +"*classname* 是節點類別的名稱，或者在該方法不存在時呼叫 :meth:" +"`generic_visit`。" + +#: ../../library/ast.rst:2423 +msgid "This visitor calls :meth:`visit` on all children of the node." +msgstr "該瀏覽者對該節點的所有子節點呼叫 :meth:`visit`。" + +#: ../../library/ast.rst:2425 +msgid "" +"Note that child nodes of nodes that have a custom visitor method won't be " +"visited unless the visitor calls :meth:`generic_visit` or visits them itself." +msgstr "" +"請注意，除非瀏覽者呼叫 :meth:`generic_visit` 或瀏覽它們本身，否則不會瀏覽具有" +"自訂瀏覽者方法的節點之子節點。" + +#: ../../library/ast.rst:2431 +msgid "Handles all constant nodes." +msgstr "處理所有常數節點。" + +#: ../../library/ast.rst:2433 +msgid "" +"Don't use the :class:`NodeVisitor` if you want to apply changes to nodes " +"during traversal. For this a special visitor exists (:class:" +"`NodeTransformer`) that allows modifications." +msgstr "" +"如果你想在遍歷期間將變更應用 (apply) 於節點，請不要使用 :class:" +"`NodeVisitor`。為此，有個允許修改的特殊遍歷瀏覽者工具 :class:" +"`NodeTransformer`。" + +#: ../../library/ast.rst:2439 +msgid "" +"Methods :meth:`!visit_Num`, :meth:`!visit_Str`, :meth:`!visit_Bytes`, :meth:" +"`!visit_NameConstant` and :meth:`!visit_Ellipsis` will not be called in " +"Python 3.14+. Add the :meth:`visit_Constant` method instead to handle all " +"constant nodes." +msgstr "" +":meth:`!visit_Num`、:meth:`!visit_Str`、:meth:`!visit_Bytes`、:meth:`!" +"visit_NameConstant` 和 :meth:`!visit_Ellipsis` 方法在 Python 3.14+ 中將不會被" +"呼叫。請改為新增 :meth:`visit_Constant` 方法來處理所有常數節點。" + +#: ../../library/ast.rst:2447 +msgid "" +"A :class:`NodeVisitor` subclass that walks the abstract syntax tree and " +"allows modification of nodes." +msgstr "一個 :class:`NodeVisitor` 子類別，它會遍歷抽象語法樹並允許修改節點。" + +#: ../../library/ast.rst:2450 +msgid "" +"The :class:`NodeTransformer` will walk the AST and use the return value of " +"the visitor methods to replace or remove the old node. If the return value " +"of the visitor method is ``None``, the node will be removed from its " +"location, otherwise it is replaced with the return value. The return value " +"may be the original node in which case no replacement takes place." +msgstr "" +":class:`NodeTransformer` 將遍歷 AST 並使用瀏覽者方法的回傳值來替換或刪除舊節" +"點。如果瀏覽者方法的回傳值為 ``None``，則該節點將從其位置中刪除，否則將被替換" +"為回傳值。回傳值可能是原始節點，在這種情況下不會發生替換。" + +#: ../../library/ast.rst:2456 +msgid "" +"Here is an example transformer that rewrites all occurrences of name lookups " +"(``foo``) to ``data['foo']``::" +msgstr "" +"下面是一個示範用的 transformer，它將查找所有出現名稱 (``foo``) 並改寫為 " +"``data['foo']``： ::" + +#: ../../library/ast.rst:2459 +msgid "" +"class RewriteName(NodeTransformer):\n" +"\n" +" def visit_Name(self, node):\n" +" return Subscript(\n" +" value=Name(id='data', ctx=Load()),\n" +" slice=Constant(value=node.id),\n" +" ctx=node.ctx\n" +" )" +msgstr "" +"class RewriteName(NodeTransformer):\n" +"\n" +" def visit_Name(self, node):\n" +" return Subscript(\n" +" value=Name(id='data', ctx=Load()),\n" +" slice=Constant(value=node.id),\n" +" ctx=node.ctx\n" +" )" + +#: ../../library/ast.rst:2468 +msgid "" +"Keep in mind that if the node you're operating on has child nodes you must " +"either transform the child nodes yourself or call the :meth:`~ast." +"NodeVisitor.generic_visit` method for the node first." +msgstr "" +"請記住，如果你正在操作的節點有子節點，你必須自己轉換子節點或先呼叫該節點的 :" +"meth:`~ast.NodeVisitor.generic_visit` 方法。" + +#: ../../library/ast.rst:2472 +msgid "" +"For nodes that were part of a collection of statements (that applies to all " +"statement nodes), the visitor may also return a list of nodes rather than " +"just a single node." +msgstr "" +"對於屬於陳述式總集 (collection) 一部分的節點（適用於所有陳述式節點），瀏覽者" +"還可以回傳節點串列，而不僅僅是單個節點。" + +#: ../../library/ast.rst:2476 +msgid "" +"If :class:`NodeTransformer` introduces new nodes (that weren't part of " +"original tree) without giving them location information (such as :attr:`~ast." +"AST.lineno`), :func:`fix_missing_locations` should be called with the new " +"sub-tree to recalculate the location information::" +msgstr "" +"如果 :class:`NodeTransformer` 引進了新節點（不屬於原始樹的一部分），但沒有給" +"它們提供位置資訊（例如 :attr:`~ast.AST.lineno`），則應使用新的子樹呼叫 :func:" +"`fix_missing_locations` 以重新計算位置資訊： ::" + +#: ../../library/ast.rst:2481 +msgid "" +"tree = ast.parse('foo', mode='eval')\n" +"new_tree = fix_missing_locations(RewriteName().visit(tree))" +msgstr "" +"tree = ast.parse('foo', mode='eval')\n" +"new_tree = fix_missing_locations(RewriteName().visit(tree))" + +#: ../../library/ast.rst:2484 +msgid "Usually you use the transformer like this::" +msgstr "你通常會像這樣使用 transformer： ::" + +#: ../../library/ast.rst:2486 +msgid "node = YourTransformer().visit(node)" +msgstr "node = YourTransformer().visit(node)" + +#: ../../library/ast.rst:2491 +msgid "" +"Return a formatted dump of the tree in *node*. This is mainly useful for " +"debugging purposes. If *annotate_fields* is true (by default), the returned " +"string will show the names and the values for fields. If *annotate_fields* " +"is false, the result string will be more compact by omitting unambiguous " +"field names. Attributes such as line numbers and column offsets are not " +"dumped by default. If this is wanted, *include_attributes* can be set to " +"true." +msgstr "" +"回傳 *node* 中樹的格式化傾印 (formatted dump)，這主要用於除錯。如果 " +"*annotate_fields* 為 true（為預設值），則回傳的字串將顯示欄位的名稱和值。如" +"果 *annotate_fields* 為 false，則透過省略明確的欄位名稱，結果字串將更加縮減簡" +"潔。預設情況下，不會傾印列號和行偏移量等屬性。如果需要，可以設定 " +"*include_attributes* 為 true。" + +#: ../../library/ast.rst:2499 +msgid "" +"If *indent* is a non-negative integer or string, then the tree will be " +"pretty-printed with that indent level. An indent level of 0, negative, or " +"``\"\"`` will only insert newlines. ``None`` (the default) selects the " +"single line representation. Using a positive integer indent indents that " +"many spaces per level. If *indent* is a string (such as ``\"\\t\"``), that " +"string is used to indent each level." +msgstr "" +"如果 *indent* 是非負整數或字串，那麼樹將使用該縮排級別來做漂亮印出 (pretty-" +"print)。縮排級別 0、負數或 ``\"\"`` 只會插入換列符號 (newlines)。``None``\\ " +"（預設值）代表選擇單列表示。使用正整數縮排可以在每個級別縮排相同數量的空格。" +"如果 *indent* 是一個字串（例如 ``\"\\t\"``），則該字串用於縮排每個級別。" + +#: ../../library/ast.rst:2506 +msgid "" +"If *show_empty* is false (the default), optional empty lists will be omitted " +"from the output. Optional ``None`` values are always omitted." +msgstr "" +"如果 *show_empty* 為 false（預設值），則輸出中將省略可選的空串列。可選的 " +"``None`` 值總是會被省略。" + +#: ../../library/ast.rst:2510 +msgid "Added the *indent* option." +msgstr "新增 *indent* 選項。" + +#: ../../library/ast.rst:2513 +msgid "Added the *show_empty* option." +msgstr "新增 *show_empty* 選項。" + +#: ../../library/ast.rst:2516 +msgid "" +">>> print(ast.dump(ast.parse(\"\"\"\\\n" +"... async def f():\n" +"... await other_func()\n" +"... \"\"\"), indent=4, show_empty=True))\n" +"Module(\n" +" body=[\n" +" AsyncFunctionDef(\n" +" name='f',\n" +" args=arguments(\n" +" posonlyargs=[],\n" +" args=[],\n" +" kwonlyargs=[],\n" +" kw_defaults=[],\n" +" defaults=[]),\n" +" body=[\n" +" Expr(\n" +" value=Await(\n" +" value=Call(\n" +" func=Name(id='other_func', ctx=Load()),\n" +" args=[],\n" +" keywords=[])))],\n" +" decorator_list=[],\n" +" type_params=[])],\n" +" type_ignores=[])" +msgstr "" +">>> print(ast.dump(ast.parse(\"\"\"\\\n" +"... async def f():\n" +"... await other_func()\n" +"... \"\"\"), indent=4, show_empty=True))\n" +"Module(\n" +" body=[\n" +" AsyncFunctionDef(\n" +" name='f',\n" +" args=arguments(\n" +" posonlyargs=[],\n" +" args=[],\n" +" kwonlyargs=[],\n" +" kw_defaults=[],\n" +" defaults=[]),\n" +" body=[\n" +" Expr(\n" +" value=Await(\n" +" value=Call(\n" +" func=Name(id='other_func', ctx=Load()),\n" +" args=[],\n" +" keywords=[])))],\n" +" decorator_list=[],\n" +" type_params=[])],\n" +" type_ignores=[])" + +#: ../../library/ast.rst:2547 +msgid "Compiler flags" +msgstr "編譯器旗標" + +#: ../../library/ast.rst:2549 +msgid "" +"The following flags may be passed to :func:`compile` in order to change " +"effects on the compilation of a program:" +msgstr "可以將以下旗標傳遞給 :func:`compile` 以變更對程式的編譯效果：" + +#: ../../library/ast.rst:2554 +msgid "" +"Enables support for top-level ``await``, ``async for``, ``async with`` and " +"async comprehensions." +msgstr "" +"啟用對最高階 ``await``、``async for``、``async with`` 和非同步綜合運算的支" +"援。" + +#: ../../library/ast.rst:2561 +msgid "" +"Generates and returns an abstract syntax tree instead of returning a " +"compiled code object." +msgstr "生成並回傳抽象語法樹，而不是回傳已編譯的程式碼物件。" + +#: ../../library/ast.rst:2566 +msgid "" +"The returned AST is optimized according to the *optimize* argument in :func:" +"`compile` or :func:`ast.parse`." +msgstr "" +"回傳的 AST 會根據 :func:`compile` 或 :func:`ast.parse` 中的 *optimize* 引數進" +"行最佳化。" + +#: ../../library/ast.rst:2573 +msgid "" +"Enables support for :pep:`484` and :pep:`526` style type comments (``# type: " +"``, ``# type: ignore ``)." +msgstr "" +"啟用對 :pep:`484` 和 :pep:`526` 樣式型別註釋的支援 (``# type: ``, ``# " +"type: ignore ``)。" + +#: ../../library/ast.rst:2581 +msgid "Recursively compares two ASTs." +msgstr "遞迴比較兩個 AST。" + +#: ../../library/ast.rst:2583 +msgid "" +"*compare_attributes* affects whether AST attributes are considered in the " +"comparison. If *compare_attributes* is ``False`` (default), then attributes " +"are ignored. Otherwise they must all be equal. This option is useful to " +"check whether the ASTs are structurally equal but differ in whitespace or " +"similar details. Attributes include line numbers and column offsets." +msgstr "" +"*compare_attributes* 會影響比較時是否考慮 AST 屬性。如果 *compare_attributes* " +"為 ``False``\\ （預設值），則忽略屬性。否則所有屬性都必須相等。此選項用於檢查 " +"AST 在結構上是否相等，但在空白或類似細節上有所不同。屬性包括列號和行偏移量。" + +#: ../../library/ast.rst:2596 +msgid "Command-line usage" +msgstr "命令列用法" + +#: ../../library/ast.rst:2600 +msgid "" +"The :mod:`ast` module can be executed as a script from the command line. It " +"is as simple as:" +msgstr ":mod:`ast` 模組可以作為腳本從命令列執行，可以像這樣簡單地做到：" + +#: ../../library/ast.rst:2603 +msgid "python -m ast [-m ] [-a] [infile]" +msgstr "python -m ast [-m ] [-a] [infile]" + +#: ../../library/ast.rst:2607 +msgid "The following options are accepted:" +msgstr "以下選項可被接受：" + +#: ../../library/ast.rst:2613 +msgid "Show the help message and exit." +msgstr "顯示幫助訊息並退出。" + +#: ../../library/ast.rst:2618 +msgid "" +"Specify what kind of code must be compiled, like the *mode* argument in :" +"func:`parse`." +msgstr "指定必須編譯哪種類型的程式碼，像是 :func:`parse` 中的 *mode* 引數。" + +#: ../../library/ast.rst:2623 +msgid "Don't parse type comments." +msgstr "不要剖析型別註解。" + +#: ../../library/ast.rst:2627 +msgid "Include attributes such as line numbers and column offsets." +msgstr "包括列號和行偏移量等屬性。" + +#: ../../library/ast.rst:2632 +msgid "Indentation of nodes in AST (number of spaces)." +msgstr "AST 中節點的縮進（空格數）。" + +#: ../../library/ast.rst:2636 +msgid "" +"Python version in the format 3.x (for example, 3.10). Defaults to the " +"current version of the interpreter." +msgstr "以 3.x 格式表示的 Python 版本（例如 3.10）。預設為直譯器的目前版本。" + +#: ../../library/ast.rst:2644 +msgid "Optimization level for parser. Defaults to no optimization." +msgstr "剖析器的最佳化層級。預設為不進行最佳化。" + +#: ../../library/ast.rst:2650 +msgid "" +"Show empty lists and fields that are ``None``. Defaults to not showing empty " +"objects." +msgstr "顯示空串列和值為 ``None`` 的欄位。預設為不顯示空物件。" + +#: ../../library/ast.rst:2656 +msgid "" +"If :file:`infile` is specified its contents are parsed to AST and dumped to " +"stdout. Otherwise, the content is read from stdin." +msgstr "" +"如果指定了 :file:`infile`，則其內容將被剖析為 AST 並傾印 (dump) 到 stdout。否" +"則會從 stdin 讀取內容。" + +#: ../../library/ast.rst:2662 +msgid "" +"`Green Tree Snakes `_, an external " +"documentation resource, has good details on working with Python ASTs." +msgstr "" +"`Green Tree Snakes `_ 是一個外部文件" +"資源，提供了有關使用 Python AST 的詳細資訊。" + +#: ../../library/ast.rst:2665 +msgid "" +"`ASTTokens `_ " +"annotates Python ASTs with the positions of tokens and text in the source " +"code that generated them. This is helpful for tools that make source code " +"transformations." +msgstr "" +"`ASTTokens `_ 使" +"用生成它們的原始碼中的標記和文本的位置來註釋 Python AST。這對於進行原始碼轉換" +"的工具很有幫助。" + +#: ../../library/ast.rst:2670 +msgid "" +"`leoAst.py `_ unifies the token-based and parse-tree-based views of python programs " +"by inserting two-way links between tokens and ast nodes." +msgstr "" +"`leoAst.py `_ 透過在 token 和 ast 節點之間插入雙向鏈結，統一了 python 程式的基於 " +"token 和基於剖析樹的視圖。" + +#: ../../library/ast.rst:2675 +msgid "" +"`LibCST `_ parses code as a Concrete Syntax " +"Tree that looks like an ast tree and keeps all formatting details. It's " +"useful for building automated refactoring (codemod) applications and linters." +msgstr "" +"`LibCST `_ 將程式碼剖析為具體語法樹 " +"(Concrete Syntax Tree)，看起來像 ast 樹並保留所有格式詳細資訊。它對於建置自動" +"重構 (codemod) 應用程式和 linter 非常有用。" + +#: ../../library/ast.rst:2680 +msgid "" +"`Parso `_ is a Python parser that supports " +"error recovery and round-trip parsing for different Python versions (in " +"multiple Python versions). Parso is also able to list multiple syntax errors " +"in your Python file." +msgstr "" +"`Parso `_ 是一個 Python 剖析器，支援不同 " +"Python 版本的錯誤復原和往返剖析。Parso 還能夠列出 Python 檔案中的多個語法錯" +"誤。" + +#: ../../library/ast.rst:59 +msgid "? (question mark)" +msgstr "? （問號）" + +#: ../../library/ast.rst:59 ../../library/ast.rst:60 +msgid "in AST grammar" +msgstr "於 AST 文法中" + +#: ../../library/ast.rst:60 +msgid "* (asterisk)" +msgstr "* （星號）" diff --git a/library/asynchat.po b/library/asynchat.po index 465364123a..f2c21ddcd0 100644 --- a/library/asynchat.po +++ b/library/asynchat.po @@ -1,43 +1,43 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -#, fuzzy -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-11-18 00:15+0000\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" -"tw)\n" -"Language: zh_TW\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=UTF-8\n" -"Content-Transfer-Encoding: 8bit\n" - -#: ../../library/asynchat.rst:2 -msgid ":mod:`!asynchat` --- Asynchronous socket command/response handler" -msgstr ":mod:`!asynchat` --- 非同步 socket 指令/回應處理函式" - -#: ../../library/asynchat.rst:10 -msgid "" -"This module is no longer part of the Python standard library. It was :ref:" -"`removed in Python 3.12 ` after being deprecated in " -"Python 3.6. The removal was decided in :pep:`594`." -msgstr "" -"這個模組已不再是 Python 標準函式庫的一部分。它在 Python 3.6 中被棄用，並\\ :" -"ref:`已在 Python 3.12 中被移除 `。它的移除是在 :pep:" -"`594` 中決定的。" - -#: ../../library/asynchat.rst:14 -msgid "Applications should use the :mod:`asyncio` module instead." -msgstr "應用程式應改用 :mod:`asyncio` 模組。" - -#: ../../library/asynchat.rst:16 -msgid "" -"The last version of Python that provided the :mod:`!asynchat` module was " -"`Python 3.11 `_." -msgstr "" -"最後提供 :mod:`!asynchat` 模組的 Python 版本是 `Python 3.11 `_。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-11-18 00:15+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" +"tw)\n" +"Language: zh_TW\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../library/asynchat.rst:2 +msgid ":mod:`!asynchat` --- Asynchronous socket command/response handler" +msgstr ":mod:`!asynchat` --- 非同步 socket 指令/回應處理函式" + +#: ../../library/asynchat.rst:10 +msgid "" +"This module is no longer part of the Python standard library. It was :ref:" +"`removed in Python 3.12 ` after being deprecated in " +"Python 3.6. The removal was decided in :pep:`594`." +msgstr "" +"這個模組已不再是 Python 標準函式庫的一部分。它在 Python 3.6 中被棄用，並\\ :" +"ref:`已在 Python 3.12 中被移除 `。它的移除是在 :pep:" +"`594` 中決定的。" + +#: ../../library/asynchat.rst:14 +msgid "Applications should use the :mod:`asyncio` module instead." +msgstr "應用程式應改用 :mod:`asyncio` 模組。" + +#: ../../library/asynchat.rst:16 +msgid "" +"The last version of Python that provided the :mod:`!asynchat` module was " +"`Python 3.11 `_." +msgstr "" +"最後提供 :mod:`!asynchat` 模組的 Python 版本是 `Python 3.11 `_。" diff --git a/library/asyncio-api-index.po b/library/asyncio-api-index.po index 02fbcb284b..c835ebb2f4 100644 --- a/library/asyncio-api-index.po +++ b/library/asyncio-api-index.po @@ -1,460 +1,460 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Matt Wang , 2022 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2022-10-31 08:13+0000\n" -"PO-Revision-Date: 2022-01-27 21:25+0800\n" -"Last-Translator: Matt Wang \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" -"X-Generator: Poedit 3.0.1\n" - -#: ../../library/asyncio-api-index.rst:6 -msgid "High-level API Index" -msgstr "高階 API 索引" - -#: ../../library/asyncio-api-index.rst:8 -msgid "This page lists all high-level async/await enabled asyncio APIs." -msgstr "這個頁面列出了所有能使用 async/wait 的高階 asyncio API。" - -#: ../../library/asyncio-api-index.rst:12 -msgid "Tasks" -msgstr "任務 (Tasks)" - -#: ../../library/asyncio-api-index.rst:14 -msgid "" -"Utilities to run asyncio programs, create Tasks, and await on multiple " -"things with timeouts." -msgstr "" -"用於執行非同步程式、建立 Task 物件、帶有超時 (timeout) 設定地等待多個事件的工" -"具程式。" - -#: ../../library/asyncio-api-index.rst:21 -msgid ":func:`run`" -msgstr ":func:`run`" - -#: ../../library/asyncio-api-index.rst:22 -msgid "Create event loop, run a coroutine, close the loop." -msgstr "建立事件迴圈 (event loop)、執行一個協程 (coroutine)、關閉事件迴圈。" - -#: ../../library/asyncio-api-index.rst:24 -msgid ":class:`Runner`" -msgstr ":class:`Runner`" - -#: ../../library/asyncio-api-index.rst:25 -msgid "A context manager that simplifies multiple async function calls." -msgstr "" - -#: ../../library/asyncio-api-index.rst:27 -msgid ":class:`Task`" -msgstr ":class:`Task`" - -#: ../../library/asyncio-api-index.rst:28 -msgid "Task object." -msgstr "Task 物件。" - -#: ../../library/asyncio-api-index.rst:30 -msgid ":class:`TaskGroup`" -msgstr ":class:`TaskGroup`" - -#: ../../library/asyncio-api-index.rst:31 -msgid "" -"A context manager that holds a group of tasks. Provides a convenient and " -"reliable way to wait for all tasks in the group to finish." -msgstr "" - -#: ../../library/asyncio-api-index.rst:35 -msgid ":func:`create_task`" -msgstr ":func:`create_task`" - -#: ../../library/asyncio-api-index.rst:36 -msgid "Start an asyncio Task, then returns it." -msgstr "啟動一個 asyncio 的 Task 物件，然後回傳它。" - -#: ../../library/asyncio-api-index.rst:38 -msgid ":func:`current_task`" -msgstr ":func:`current_task`" - -#: ../../library/asyncio-api-index.rst:39 -msgid "Return the current Task." -msgstr "回傳目前 Task 物件。" - -#: ../../library/asyncio-api-index.rst:41 -msgid ":func:`all_tasks`" -msgstr ":func:`all_tasks`" - -#: ../../library/asyncio-api-index.rst:42 -msgid "Return all tasks that are not yet finished for an event loop." -msgstr "回傳事件迴圈中所有未完成的 task 物件。" - -#: ../../library/asyncio-api-index.rst:44 -msgid "``await`` :func:`sleep`" -msgstr "``await`` :func:`sleep`" - -#: ../../library/asyncio-api-index.rst:45 -msgid "Sleep for a number of seconds." -msgstr "休眠數秒鐘。" - -#: ../../library/asyncio-api-index.rst:47 -msgid "``await`` :func:`gather`" -msgstr "``await`` :func:`gather`" - -#: ../../library/asyncio-api-index.rst:48 -msgid "Schedule and wait for things concurrently." -msgstr "並行 (concurrent) 地執行事件的排程與等待。" - -#: ../../library/asyncio-api-index.rst:50 -msgid "``await`` :func:`wait_for`" -msgstr "``await`` :func:`wait_for`" - -#: ../../library/asyncio-api-index.rst:51 -msgid "Run with a timeout." -msgstr "有超時設置的執行。" - -#: ../../library/asyncio-api-index.rst:53 -msgid "``await`` :func:`shield`" -msgstr "``await`` :func:`shield`" - -#: ../../library/asyncio-api-index.rst:54 -msgid "Shield from cancellation." -msgstr "防止被取消。" - -#: ../../library/asyncio-api-index.rst:56 -msgid "``await`` :func:`wait`" -msgstr "``await`` :func:`wait`" - -#: ../../library/asyncio-api-index.rst:57 -msgid "Monitor for completion." -msgstr "監控完成情況。" - -#: ../../library/asyncio-api-index.rst:59 -msgid ":func:`timeout`" -msgstr ":func:`timeout`" - -#: ../../library/asyncio-api-index.rst:60 -msgid "Run with a timeout. Useful in cases when ``wait_for`` is not suitable." -msgstr "" - -#: ../../library/asyncio-api-index.rst:62 -msgid ":func:`to_thread`" -msgstr ":func:`to_thread`" - -#: ../../library/asyncio-api-index.rst:63 -msgid "Asynchronously run a function in a separate OS thread." -msgstr "在不同的 OS 執行緒 (thread) 中非同步地執行一個函式。" - -#: ../../library/asyncio-api-index.rst:65 -msgid ":func:`run_coroutine_threadsafe`" -msgstr ":func:`run_coroutine_threadsafe`" - -#: ../../library/asyncio-api-index.rst:66 -msgid "Schedule a coroutine from another OS thread." -msgstr "從其他 OS 執行緒中為一個協程排程。" - -#: ../../library/asyncio-api-index.rst:68 -msgid "``for in`` :func:`as_completed`" -msgstr "``for in`` :func:`as_completed`" - -#: ../../library/asyncio-api-index.rst:69 -msgid "Monitor for completion with a ``for`` loop." -msgstr "用 ``for`` 迴圈來監控完成情況。" - -#: ../../library/asyncio-api-index.rst:73 -#: ../../library/asyncio-api-index.rst:109 -#: ../../library/asyncio-api-index.rst:133 -#: ../../library/asyncio-api-index.rst:169 -#: ../../library/asyncio-api-index.rst:205 -#: ../../library/asyncio-api-index.rst:230 -msgid "Examples" -msgstr "範例" - -#: ../../library/asyncio-api-index.rst:74 -msgid "" -":ref:`Using asyncio.gather() to run things in parallel " -"`." -msgstr "" -":ref:`使用 asyncio.gather() 平行 (parallel) 執行 `。" - -#: ../../library/asyncio-api-index.rst:77 -msgid "" -":ref:`Using asyncio.wait_for() to enforce a timeout " -"`." -msgstr "" -":ref:`使用 asyncio.wait_for() 強制設置超時 `。" - -#: ../../library/asyncio-api-index.rst:80 -msgid ":ref:`Cancellation `." -msgstr ":ref:`取消任務 `。" - -#: ../../library/asyncio-api-index.rst:82 -msgid ":ref:`Using asyncio.sleep() `." -msgstr ":ref:`使用 asyncio.sleep() `。" - -#: ../../library/asyncio-api-index.rst:84 -msgid "See also the main :ref:`Tasks documentation page `." -msgstr "請參閱 :ref:`Tasks 文件頁面 `。" - -#: ../../library/asyncio-api-index.rst:88 -msgid "Queues" -msgstr "佇列 (Queues)" - -#: ../../library/asyncio-api-index.rst:90 -msgid "" -"Queues should be used to distribute work amongst multiple asyncio Tasks, " -"implement connection pools, and pub/sub patterns." -msgstr "" -"佇列應被用於為多個 asyncio Task 物件分配工作、實作 connection pools（連線池）" -"以及 pub/sub（發行/訂閱）模式。" - -#: ../../library/asyncio-api-index.rst:98 -msgid ":class:`Queue`" -msgstr ":class:`Queue`" - -#: ../../library/asyncio-api-index.rst:99 -msgid "A FIFO queue." -msgstr "一個先進先出 (FIFO) 佇列。" - -#: ../../library/asyncio-api-index.rst:101 -msgid ":class:`PriorityQueue`" -msgstr ":class:`PriorityQueue`" - -#: ../../library/asyncio-api-index.rst:102 -msgid "A priority queue." -msgstr "一個優先佇列 (priority queue)。" - -#: ../../library/asyncio-api-index.rst:104 -msgid ":class:`LifoQueue`" -msgstr ":class:`LifoQueue`" - -#: ../../library/asyncio-api-index.rst:105 -msgid "A LIFO queue." -msgstr "一個後進先出 (LIFO) 佇列。" - -#: ../../library/asyncio-api-index.rst:110 -msgid "" -":ref:`Using asyncio.Queue to distribute workload between several Tasks " -"`." -msgstr "" -":ref:`使用 asyncio.Queue 為多個 Task 分配工作 `。" - -#: ../../library/asyncio-api-index.rst:113 -msgid "See also the :ref:`Queues documentation page `." -msgstr "請參閱\\ :ref:`佇列文件頁面 `。" - -#: ../../library/asyncio-api-index.rst:117 -msgid "Subprocesses" -msgstr "子行程 (Subprocesses)" - -#: ../../library/asyncio-api-index.rst:119 -msgid "Utilities to spawn subprocesses and run shell commands." -msgstr "用於衍生（spawn）子行程和執行 shell 指令的工具程式。" - -#: ../../library/asyncio-api-index.rst:125 -msgid "``await`` :func:`create_subprocess_exec`" -msgstr "``await`` :func:`create_subprocess_exec`" - -#: ../../library/asyncio-api-index.rst:126 -msgid "Create a subprocess." -msgstr "建立一個子行程。" - -#: ../../library/asyncio-api-index.rst:128 -msgid "``await`` :func:`create_subprocess_shell`" -msgstr "``await`` :func:`create_subprocess_shell`" - -#: ../../library/asyncio-api-index.rst:129 -msgid "Run a shell command." -msgstr "執行一個 shell 命令。" - -#: ../../library/asyncio-api-index.rst:134 -msgid ":ref:`Executing a shell command `." -msgstr ":ref:`執行一個 shell 指令 `。" - -#: ../../library/asyncio-api-index.rst:136 -msgid "See also the :ref:`subprocess APIs ` documentation." -msgstr "請參閱\\ :ref:`子行程 APIs ` 相關文件。" - -#: ../../library/asyncio-api-index.rst:141 -msgid "Streams" -msgstr "串流 (Streams)" - -#: ../../library/asyncio-api-index.rst:143 -msgid "High-level APIs to work with network IO." -msgstr "用於網路 IO 處理的高階 API。" - -#: ../../library/asyncio-api-index.rst:149 -msgid "``await`` :func:`open_connection`" -msgstr "``await`` :func:`open_connection`" - -#: ../../library/asyncio-api-index.rst:150 -msgid "Establish a TCP connection." -msgstr "建立一個 TCP 連線。" - -#: ../../library/asyncio-api-index.rst:152 -msgid "``await`` :func:`open_unix_connection`" -msgstr "``await`` :func:`open_unix_connection`" - -#: ../../library/asyncio-api-index.rst:153 -msgid "Establish a Unix socket connection." -msgstr "建立一個 Unix socket 連線。" - -#: ../../library/asyncio-api-index.rst:155 -msgid "``await`` :func:`start_server`" -msgstr "``await`` :func:`start_server`" - -#: ../../library/asyncio-api-index.rst:156 -msgid "Start a TCP server." -msgstr "啟動一個 TCP 伺服器。" - -#: ../../library/asyncio-api-index.rst:158 -msgid "``await`` :func:`start_unix_server`" -msgstr "``await`` :func:`start_unix_server`" - -#: ../../library/asyncio-api-index.rst:159 -msgid "Start a Unix socket server." -msgstr "啟動一個 Unix socket 伺服器。" - -#: ../../library/asyncio-api-index.rst:161 -msgid ":class:`StreamReader`" -msgstr ":class:`StreamReader`" - -#: ../../library/asyncio-api-index.rst:162 -msgid "High-level async/await object to receive network data." -msgstr "接收網路資料的高階 async/await 物件。" - -#: ../../library/asyncio-api-index.rst:164 -msgid ":class:`StreamWriter`" -msgstr ":class:`StreamWriter`" - -#: ../../library/asyncio-api-index.rst:165 -msgid "High-level async/await object to send network data." -msgstr "傳送網路資料的高階 async/await 物件。" - -#: ../../library/asyncio-api-index.rst:170 -msgid ":ref:`Example TCP client `." -msgstr ":ref:`TCP 用戶端範例 `。" - -#: ../../library/asyncio-api-index.rst:172 -msgid "See also the :ref:`streams APIs ` documentation." -msgstr "請參閱\\ :ref:`串流 APIs ` 文件。" - -#: ../../library/asyncio-api-index.rst:177 -msgid "Synchronization" -msgstr "同步化 (Synchronization)" - -#: ../../library/asyncio-api-index.rst:179 -msgid "Threading-like synchronization primitives that can be used in Tasks." -msgstr "類似執行緒且能被用於 Task 中的同步化原始物件 (primitive)。" - -#: ../../library/asyncio-api-index.rst:185 -msgid ":class:`Lock`" -msgstr ":class:`Lock`" - -#: ../../library/asyncio-api-index.rst:186 -msgid "A mutex lock." -msgstr "一個互斥鎖 (mutex lock)。" - -#: ../../library/asyncio-api-index.rst:188 -msgid ":class:`Event`" -msgstr ":class:`Event`" - -#: ../../library/asyncio-api-index.rst:189 -msgid "An event object." -msgstr "一個事件物件。" - -#: ../../library/asyncio-api-index.rst:191 -msgid ":class:`Condition`" -msgstr ":class:`Condition`" - -#: ../../library/asyncio-api-index.rst:192 -msgid "A condition object." -msgstr "一個條件物件。" - -#: ../../library/asyncio-api-index.rst:194 -msgid ":class:`Semaphore`" -msgstr ":class:`Semaphore`" - -#: ../../library/asyncio-api-index.rst:195 -msgid "A semaphore." -msgstr "一個旗號 (semaphore) 物件。" - -#: ../../library/asyncio-api-index.rst:197 -msgid ":class:`BoundedSemaphore`" -msgstr ":class:`BoundedSemaphore`" - -#: ../../library/asyncio-api-index.rst:198 -msgid "A bounded semaphore." -msgstr "一個有界的旗號物件。" - -#: ../../library/asyncio-api-index.rst:200 -msgid ":class:`Barrier`" -msgstr ":class:`Barrier`" - -#: ../../library/asyncio-api-index.rst:201 -msgid "A barrier object." -msgstr "一個屏障物件。" - -#: ../../library/asyncio-api-index.rst:206 -msgid ":ref:`Using asyncio.Event `." -msgstr ":ref:`使用 asyncio.Event `。" - -#: ../../library/asyncio-api-index.rst:208 -msgid ":ref:`Using asyncio.Barrier `." -msgstr ":ref:`使用 asyncio.Barrier `。" - -#: ../../library/asyncio-api-index.rst:210 -msgid "" -"See also the documentation of asyncio :ref:`synchronization primitives " -"`." -msgstr "請參閱 asyncio 關於\\ :ref:`同步化原始物件 `\\ 的文件。" - -#: ../../library/asyncio-api-index.rst:215 -msgid "Exceptions" -msgstr "例外" - -#: ../../library/asyncio-api-index.rst:222 -msgid ":exc:`asyncio.CancelledError`" -msgstr ":exc:`asyncio.CancelledError`" - -#: ../../library/asyncio-api-index.rst:223 -msgid "Raised when a Task is cancelled. See also :meth:`Task.cancel`." -msgstr "當一 Task 物件被取消時被引發。請參閱 :meth:`Task.cancel`。" - -#: ../../library/asyncio-api-index.rst:225 -msgid ":exc:`asyncio.BrokenBarrierError`" -msgstr ":exc:`asyncio.BrokenBarrierError`" - -#: ../../library/asyncio-api-index.rst:226 -msgid "Raised when a Barrier is broken. See also :meth:`Barrier.wait`." -msgstr "當一 Barrier 物件損壞時被引發。請參閱 :meth:`Barrier.wait`。" - -#: ../../library/asyncio-api-index.rst:231 -msgid "" -":ref:`Handling CancelledError to run code on cancellation request " -"`." -msgstr "" -":ref:`在取消請求發生的程式中處理 CancelledError 例外 " -"`。" - -#: ../../library/asyncio-api-index.rst:234 -msgid "" -"See also the full list of :ref:`asyncio-specific exceptions `." -msgstr "請參閱 :ref:`asyncio 專用例外 `\\ 完整列表。" - -#~ msgid "" -#~ "Raised on timeout by functions like :func:`wait_for`. Keep in mind that " -#~ "``asyncio.TimeoutError`` is **unrelated** to the built-in :exc:" -#~ "`TimeoutError` exception." -#~ msgstr "" -#~ "在像是 :func:`wait_for` 等函式超時的時候被引發。請注意 ``asyncio." -#~ "TimeoutError`` 與內建例外 :exc:`TimeoutError` **無關**。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Matt Wang , 2022 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2022-10-31 08:13+0000\n" +"PO-Revision-Date: 2022-01-27 21:25+0800\n" +"Last-Translator: Matt Wang \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" +"X-Generator: Poedit 3.0.1\n" + +#: ../../library/asyncio-api-index.rst:6 +msgid "High-level API Index" +msgstr "高階 API 索引" + +#: ../../library/asyncio-api-index.rst:8 +msgid "This page lists all high-level async/await enabled asyncio APIs." +msgstr "這個頁面列出了所有能使用 async/wait 的高階 asyncio API。" + +#: ../../library/asyncio-api-index.rst:12 +msgid "Tasks" +msgstr "任務 (Tasks)" + +#: ../../library/asyncio-api-index.rst:14 +msgid "" +"Utilities to run asyncio programs, create Tasks, and await on multiple " +"things with timeouts." +msgstr "" +"用於執行非同步程式、建立 Task 物件、帶有超時 (timeout) 設定地等待多個事件的工" +"具程式。" + +#: ../../library/asyncio-api-index.rst:21 +msgid ":func:`run`" +msgstr ":func:`run`" + +#: ../../library/asyncio-api-index.rst:22 +msgid "Create event loop, run a coroutine, close the loop." +msgstr "建立事件迴圈 (event loop)、執行一個協程 (coroutine)、關閉事件迴圈。" + +#: ../../library/asyncio-api-index.rst:24 +msgid ":class:`Runner`" +msgstr ":class:`Runner`" + +#: ../../library/asyncio-api-index.rst:25 +msgid "A context manager that simplifies multiple async function calls." +msgstr "" + +#: ../../library/asyncio-api-index.rst:27 +msgid ":class:`Task`" +msgstr ":class:`Task`" + +#: ../../library/asyncio-api-index.rst:28 +msgid "Task object." +msgstr "Task 物件。" + +#: ../../library/asyncio-api-index.rst:30 +msgid ":class:`TaskGroup`" +msgstr ":class:`TaskGroup`" + +#: ../../library/asyncio-api-index.rst:31 +msgid "" +"A context manager that holds a group of tasks. Provides a convenient and " +"reliable way to wait for all tasks in the group to finish." +msgstr "" + +#: ../../library/asyncio-api-index.rst:35 +msgid ":func:`create_task`" +msgstr ":func:`create_task`" + +#: ../../library/asyncio-api-index.rst:36 +msgid "Start an asyncio Task, then returns it." +msgstr "啟動一個 asyncio 的 Task 物件，然後回傳它。" + +#: ../../library/asyncio-api-index.rst:38 +msgid ":func:`current_task`" +msgstr ":func:`current_task`" + +#: ../../library/asyncio-api-index.rst:39 +msgid "Return the current Task." +msgstr "回傳目前 Task 物件。" + +#: ../../library/asyncio-api-index.rst:41 +msgid ":func:`all_tasks`" +msgstr ":func:`all_tasks`" + +#: ../../library/asyncio-api-index.rst:42 +msgid "Return all tasks that are not yet finished for an event loop." +msgstr "回傳事件迴圈中所有未完成的 task 物件。" + +#: ../../library/asyncio-api-index.rst:44 +msgid "``await`` :func:`sleep`" +msgstr "``await`` :func:`sleep`" + +#: ../../library/asyncio-api-index.rst:45 +msgid "Sleep for a number of seconds." +msgstr "休眠數秒鐘。" + +#: ../../library/asyncio-api-index.rst:47 +msgid "``await`` :func:`gather`" +msgstr "``await`` :func:`gather`" + +#: ../../library/asyncio-api-index.rst:48 +msgid "Schedule and wait for things concurrently." +msgstr "並行 (concurrent) 地執行事件的排程與等待。" + +#: ../../library/asyncio-api-index.rst:50 +msgid "``await`` :func:`wait_for`" +msgstr "``await`` :func:`wait_for`" + +#: ../../library/asyncio-api-index.rst:51 +msgid "Run with a timeout." +msgstr "有超時設置的執行。" + +#: ../../library/asyncio-api-index.rst:53 +msgid "``await`` :func:`shield`" +msgstr "``await`` :func:`shield`" + +#: ../../library/asyncio-api-index.rst:54 +msgid "Shield from cancellation." +msgstr "防止被取消。" + +#: ../../library/asyncio-api-index.rst:56 +msgid "``await`` :func:`wait`" +msgstr "``await`` :func:`wait`" + +#: ../../library/asyncio-api-index.rst:57 +msgid "Monitor for completion." +msgstr "監控完成情況。" + +#: ../../library/asyncio-api-index.rst:59 +msgid ":func:`timeout`" +msgstr ":func:`timeout`" + +#: ../../library/asyncio-api-index.rst:60 +msgid "Run with a timeout. Useful in cases when ``wait_for`` is not suitable." +msgstr "" + +#: ../../library/asyncio-api-index.rst:62 +msgid ":func:`to_thread`" +msgstr ":func:`to_thread`" + +#: ../../library/asyncio-api-index.rst:63 +msgid "Asynchronously run a function in a separate OS thread." +msgstr "在不同的 OS 執行緒 (thread) 中非同步地執行一個函式。" + +#: ../../library/asyncio-api-index.rst:65 +msgid ":func:`run_coroutine_threadsafe`" +msgstr ":func:`run_coroutine_threadsafe`" + +#: ../../library/asyncio-api-index.rst:66 +msgid "Schedule a coroutine from another OS thread." +msgstr "從其他 OS 執行緒中為一個協程排程。" + +#: ../../library/asyncio-api-index.rst:68 +msgid "``for in`` :func:`as_completed`" +msgstr "``for in`` :func:`as_completed`" + +#: ../../library/asyncio-api-index.rst:69 +msgid "Monitor for completion with a ``for`` loop." +msgstr "用 ``for`` 迴圈來監控完成情況。" + +#: ../../library/asyncio-api-index.rst:73 +#: ../../library/asyncio-api-index.rst:109 +#: ../../library/asyncio-api-index.rst:133 +#: ../../library/asyncio-api-index.rst:169 +#: ../../library/asyncio-api-index.rst:205 +#: ../../library/asyncio-api-index.rst:230 +msgid "Examples" +msgstr "範例" + +#: ../../library/asyncio-api-index.rst:74 +msgid "" +":ref:`Using asyncio.gather() to run things in parallel " +"`." +msgstr "" +":ref:`使用 asyncio.gather() 平行 (parallel) 執行 `。" + +#: ../../library/asyncio-api-index.rst:77 +msgid "" +":ref:`Using asyncio.wait_for() to enforce a timeout " +"`." +msgstr "" +":ref:`使用 asyncio.wait_for() 強制設置超時 `。" + +#: ../../library/asyncio-api-index.rst:80 +msgid ":ref:`Cancellation `." +msgstr ":ref:`取消任務 `。" + +#: ../../library/asyncio-api-index.rst:82 +msgid ":ref:`Using asyncio.sleep() `." +msgstr ":ref:`使用 asyncio.sleep() `。" + +#: ../../library/asyncio-api-index.rst:84 +msgid "See also the main :ref:`Tasks documentation page `." +msgstr "請參閱 :ref:`Tasks 文件頁面 `。" + +#: ../../library/asyncio-api-index.rst:88 +msgid "Queues" +msgstr "佇列 (Queues)" + +#: ../../library/asyncio-api-index.rst:90 +msgid "" +"Queues should be used to distribute work amongst multiple asyncio Tasks, " +"implement connection pools, and pub/sub patterns." +msgstr "" +"佇列應被用於為多個 asyncio Task 物件分配工作、實作 connection pools（連線池）" +"以及 pub/sub（發行/訂閱）模式。" + +#: ../../library/asyncio-api-index.rst:98 +msgid ":class:`Queue`" +msgstr ":class:`Queue`" + +#: ../../library/asyncio-api-index.rst:99 +msgid "A FIFO queue." +msgstr "一個先進先出 (FIFO) 佇列。" + +#: ../../library/asyncio-api-index.rst:101 +msgid ":class:`PriorityQueue`" +msgstr ":class:`PriorityQueue`" + +#: ../../library/asyncio-api-index.rst:102 +msgid "A priority queue." +msgstr "一個優先佇列 (priority queue)。" + +#: ../../library/asyncio-api-index.rst:104 +msgid ":class:`LifoQueue`" +msgstr ":class:`LifoQueue`" + +#: ../../library/asyncio-api-index.rst:105 +msgid "A LIFO queue." +msgstr "一個後進先出 (LIFO) 佇列。" + +#: ../../library/asyncio-api-index.rst:110 +msgid "" +":ref:`Using asyncio.Queue to distribute workload between several Tasks " +"`." +msgstr "" +":ref:`使用 asyncio.Queue 為多個 Task 分配工作 `。" + +#: ../../library/asyncio-api-index.rst:113 +msgid "See also the :ref:`Queues documentation page `." +msgstr "請參閱\\ :ref:`佇列文件頁面 `。" + +#: ../../library/asyncio-api-index.rst:117 +msgid "Subprocesses" +msgstr "子行程 (Subprocesses)" + +#: ../../library/asyncio-api-index.rst:119 +msgid "Utilities to spawn subprocesses and run shell commands." +msgstr "用於衍生（spawn）子行程和執行 shell 指令的工具程式。" + +#: ../../library/asyncio-api-index.rst:125 +msgid "``await`` :func:`create_subprocess_exec`" +msgstr "``await`` :func:`create_subprocess_exec`" + +#: ../../library/asyncio-api-index.rst:126 +msgid "Create a subprocess." +msgstr "建立一個子行程。" + +#: ../../library/asyncio-api-index.rst:128 +msgid "``await`` :func:`create_subprocess_shell`" +msgstr "``await`` :func:`create_subprocess_shell`" + +#: ../../library/asyncio-api-index.rst:129 +msgid "Run a shell command." +msgstr "執行一個 shell 命令。" + +#: ../../library/asyncio-api-index.rst:134 +msgid ":ref:`Executing a shell command `." +msgstr ":ref:`執行一個 shell 指令 `。" + +#: ../../library/asyncio-api-index.rst:136 +msgid "See also the :ref:`subprocess APIs ` documentation." +msgstr "請參閱\\ :ref:`子行程 APIs ` 相關文件。" + +#: ../../library/asyncio-api-index.rst:141 +msgid "Streams" +msgstr "串流 (Streams)" + +#: ../../library/asyncio-api-index.rst:143 +msgid "High-level APIs to work with network IO." +msgstr "用於網路 IO 處理的高階 API。" + +#: ../../library/asyncio-api-index.rst:149 +msgid "``await`` :func:`open_connection`" +msgstr "``await`` :func:`open_connection`" + +#: ../../library/asyncio-api-index.rst:150 +msgid "Establish a TCP connection." +msgstr "建立一個 TCP 連線。" + +#: ../../library/asyncio-api-index.rst:152 +msgid "``await`` :func:`open_unix_connection`" +msgstr "``await`` :func:`open_unix_connection`" + +#: ../../library/asyncio-api-index.rst:153 +msgid "Establish a Unix socket connection." +msgstr "建立一個 Unix socket 連線。" + +#: ../../library/asyncio-api-index.rst:155 +msgid "``await`` :func:`start_server`" +msgstr "``await`` :func:`start_server`" + +#: ../../library/asyncio-api-index.rst:156 +msgid "Start a TCP server." +msgstr "啟動一個 TCP 伺服器。" + +#: ../../library/asyncio-api-index.rst:158 +msgid "``await`` :func:`start_unix_server`" +msgstr "``await`` :func:`start_unix_server`" + +#: ../../library/asyncio-api-index.rst:159 +msgid "Start a Unix socket server." +msgstr "啟動一個 Unix socket 伺服器。" + +#: ../../library/asyncio-api-index.rst:161 +msgid ":class:`StreamReader`" +msgstr ":class:`StreamReader`" + +#: ../../library/asyncio-api-index.rst:162 +msgid "High-level async/await object to receive network data." +msgstr "接收網路資料的高階 async/await 物件。" + +#: ../../library/asyncio-api-index.rst:164 +msgid ":class:`StreamWriter`" +msgstr ":class:`StreamWriter`" + +#: ../../library/asyncio-api-index.rst:165 +msgid "High-level async/await object to send network data." +msgstr "傳送網路資料的高階 async/await 物件。" + +#: ../../library/asyncio-api-index.rst:170 +msgid ":ref:`Example TCP client `." +msgstr ":ref:`TCP 用戶端範例 `。" + +#: ../../library/asyncio-api-index.rst:172 +msgid "See also the :ref:`streams APIs ` documentation." +msgstr "請參閱\\ :ref:`串流 APIs ` 文件。" + +#: ../../library/asyncio-api-index.rst:177 +msgid "Synchronization" +msgstr "同步化 (Synchronization)" + +#: ../../library/asyncio-api-index.rst:179 +msgid "Threading-like synchronization primitives that can be used in Tasks." +msgstr "類似執行緒且能被用於 Task 中的同步化原始物件 (primitive)。" + +#: ../../library/asyncio-api-index.rst:185 +msgid ":class:`Lock`" +msgstr ":class:`Lock`" + +#: ../../library/asyncio-api-index.rst:186 +msgid "A mutex lock." +msgstr "一個互斥鎖 (mutex lock)。" + +#: ../../library/asyncio-api-index.rst:188 +msgid ":class:`Event`" +msgstr ":class:`Event`" + +#: ../../library/asyncio-api-index.rst:189 +msgid "An event object." +msgstr "一個事件物件。" + +#: ../../library/asyncio-api-index.rst:191 +msgid ":class:`Condition`" +msgstr ":class:`Condition`" + +#: ../../library/asyncio-api-index.rst:192 +msgid "A condition object." +msgstr "一個條件物件。" + +#: ../../library/asyncio-api-index.rst:194 +msgid ":class:`Semaphore`" +msgstr ":class:`Semaphore`" + +#: ../../library/asyncio-api-index.rst:195 +msgid "A semaphore." +msgstr "一個旗號 (semaphore) 物件。" + +#: ../../library/asyncio-api-index.rst:197 +msgid ":class:`BoundedSemaphore`" +msgstr ":class:`BoundedSemaphore`" + +#: ../../library/asyncio-api-index.rst:198 +msgid "A bounded semaphore." +msgstr "一個有界的旗號物件。" + +#: ../../library/asyncio-api-index.rst:200 +msgid ":class:`Barrier`" +msgstr ":class:`Barrier`" + +#: ../../library/asyncio-api-index.rst:201 +msgid "A barrier object." +msgstr "一個屏障物件。" + +#: ../../library/asyncio-api-index.rst:206 +msgid ":ref:`Using asyncio.Event `." +msgstr ":ref:`使用 asyncio.Event `。" + +#: ../../library/asyncio-api-index.rst:208 +msgid ":ref:`Using asyncio.Barrier `." +msgstr ":ref:`使用 asyncio.Barrier `。" + +#: ../../library/asyncio-api-index.rst:210 +msgid "" +"See also the documentation of asyncio :ref:`synchronization primitives " +"`." +msgstr "請參閱 asyncio 關於\\ :ref:`同步化原始物件 `\\ 的文件。" + +#: ../../library/asyncio-api-index.rst:215 +msgid "Exceptions" +msgstr "例外" + +#: ../../library/asyncio-api-index.rst:222 +msgid ":exc:`asyncio.CancelledError`" +msgstr ":exc:`asyncio.CancelledError`" + +#: ../../library/asyncio-api-index.rst:223 +msgid "Raised when a Task is cancelled. See also :meth:`Task.cancel`." +msgstr "當一 Task 物件被取消時被引發。請參閱 :meth:`Task.cancel`。" + +#: ../../library/asyncio-api-index.rst:225 +msgid ":exc:`asyncio.BrokenBarrierError`" +msgstr ":exc:`asyncio.BrokenBarrierError`" + +#: ../../library/asyncio-api-index.rst:226 +msgid "Raised when a Barrier is broken. See also :meth:`Barrier.wait`." +msgstr "當一 Barrier 物件損壞時被引發。請參閱 :meth:`Barrier.wait`。" + +#: ../../library/asyncio-api-index.rst:231 +msgid "" +":ref:`Handling CancelledError to run code on cancellation request " +"`." +msgstr "" +":ref:`在取消請求發生的程式中處理 CancelledError 例外 " +"`。" + +#: ../../library/asyncio-api-index.rst:234 +msgid "" +"See also the full list of :ref:`asyncio-specific exceptions `." +msgstr "請參閱 :ref:`asyncio 專用例外 `\\ 完整列表。" + +#~ msgid "" +#~ "Raised on timeout by functions like :func:`wait_for`. Keep in mind that " +#~ "``asyncio.TimeoutError`` is **unrelated** to the built-in :exc:" +#~ "`TimeoutError` exception." +#~ msgstr "" +#~ "在像是 :func:`wait_for` 等函式超時的時候被引發。請注意 ``asyncio." +#~ "TimeoutError`` 與內建例外 :exc:`TimeoutError` **無關**。" diff --git a/library/asyncio-dev.po b/library/asyncio-dev.po index df22955bfb..f80b42b1aa 100644 --- a/library/asyncio-dev.po +++ b/library/asyncio-dev.po @@ -1,483 +1,483 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Adrian Liaw , 2018 -# Matt Wang , 2022 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: 2023-02-18 14:17+0800\n" -"Last-Translator: Matt Wang \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" -"X-Generator: Poedit 3.2.2\n" - -#: ../../library/asyncio-dev.rst:7 -msgid "Developing with asyncio" -msgstr "使用 asyncio 開發" - -#: ../../library/asyncio-dev.rst:9 -msgid "" -"Asynchronous programming is different from classic \"sequential\" " -"programming." -msgstr "" -"非同步程式設計 (asynchronous programming) 與傳統的\"順序\"程式設計 " -"(sequential programming) 不同。" - -#: ../../library/asyncio-dev.rst:12 -msgid "" -"This page lists common mistakes and traps and explains how to avoid them." -msgstr "本頁列出常見的錯誤和陷阱，並解釋如何避免它們。" - -#: ../../library/asyncio-dev.rst:19 -msgid "Debug Mode" -msgstr "除錯模式" - -#: ../../library/asyncio-dev.rst:21 -msgid "" -"By default asyncio runs in production mode. In order to ease the " -"development asyncio has a *debug mode*." -msgstr "" -"在預設情況下 asyncio 以正式生產模式 (production mode) 執行。為了讓開發更輕" -"鬆，asyncio 還有一種\\ *除錯模式 (debug mode)*。" - -#: ../../library/asyncio-dev.rst:24 -msgid "There are several ways to enable asyncio debug mode:" -msgstr "有幾種方法可以啟用 asyncio 除錯模式：" - -#: ../../library/asyncio-dev.rst:26 -msgid "Setting the :envvar:`PYTHONASYNCIODEBUG` environment variable to ``1``." -msgstr "將 :envvar:`PYTHONASYNCIODEBUG` 環境變數設定為 ``1``。" - -#: ../../library/asyncio-dev.rst:28 -msgid "Using the :ref:`Python Development Mode `." -msgstr "使用 :ref:`Python 開發模式 (Development Mode) `。" - -#: ../../library/asyncio-dev.rst:30 -msgid "Passing ``debug=True`` to :func:`asyncio.run`." -msgstr "將 ``debug=True`` 傳遞給 :func:`asyncio.run`。" - -#: ../../library/asyncio-dev.rst:32 -msgid "Calling :meth:`loop.set_debug`." -msgstr "呼叫 :meth:`loop.set_debug`。" - -#: ../../library/asyncio-dev.rst:34 -msgid "In addition to enabling the debug mode, consider also:" -msgstr "除了啟用除錯模式外，還要考慮：" - -#: ../../library/asyncio-dev.rst:36 -msgid "" -"setting the log level of the :ref:`asyncio logger ` " -"to :py:const:`logging.DEBUG`, for example the following snippet of code can " -"be run at startup of the application::" -msgstr "" -"將 :ref:`asyncio logger（日誌記錄器） `\\ 的日誌級别設置" -"為 :py:const:`logging.DEBUG`，例如下面的程式片段可以在應用程式啟動時運行： ::" - -#: ../../library/asyncio-dev.rst:40 -msgid "logging.basicConfig(level=logging.DEBUG)" -msgstr "logging.basicConfig(level=logging.DEBUG)" - -#: ../../library/asyncio-dev.rst:42 -msgid "" -"configuring the :mod:`warnings` module to display :exc:`ResourceWarning` " -"warnings. One way of doing that is by using the :option:`-W` ``default`` " -"command line option." -msgstr "" -"配置 :mod:`warnings` 模組以顯示 :exc:`ResourceWarning` 警告。一種方法是使" -"用 :option:`-W` ``default`` 命令列選項。" - -#: ../../library/asyncio-dev.rst:47 -msgid "When the debug mode is enabled:" -msgstr "啟用除錯模式時：" - -#: ../../library/asyncio-dev.rst:49 -msgid "" -"Many non-threadsafe asyncio APIs (such as :meth:`loop.call_soon` " -"and :meth:`loop.call_at` methods) raise an exception if they are called from " -"a wrong thread." -msgstr "" -"許多非執行緒安全 (non-threadsafe) 的 asyncio APIs（例" -"如 :meth:`loop.call_soon` 和 :meth:`loop.call_at` 方法），如果從錯誤的執行緒" -"呼叫就會引發例外。" - -#: ../../library/asyncio-dev.rst:53 -msgid "" -"The execution time of the I/O selector is logged if it takes too long to " -"perform an I/O operation." -msgstr "" -"如果執行一個 I/O 操作花費的時間太長，則將 I/O 選擇器 (selector) 的執行時間記" -"錄到日誌中。" - -#: ../../library/asyncio-dev.rst:56 -msgid "" -"Callbacks taking longer than 100 milliseconds are logged. " -"The :attr:`loop.slow_callback_duration` attribute can be used to set the " -"minimum execution duration in seconds that is considered \"slow\"." -msgstr "" -"執行時間超過 100 毫秒的回呼 (callback) 將會被記錄於日誌。屬" -"性 :attr:`loop.slow_callback_duration` 可用於設定以秒為單位的最小執行持續時" -"間，超過這個值執行時間就會被視為\"緩慢\"。" - -#: ../../library/asyncio-dev.rst:64 -msgid "Concurrency and Multithreading" -msgstr "並行性和多執行緒 (Concurrency and Multithreading)" - -#: ../../library/asyncio-dev.rst:66 -msgid "" -"An event loop runs in a thread (typically the main thread) and executes all " -"callbacks and Tasks in its thread. While a Task is running in the event " -"loop, no other Tasks can run in the same thread. When a Task executes an " -"``await`` expression, the running Task gets suspended, and the event loop " -"executes the next Task." -msgstr "" -"事件迴圈在執行緒中運行（通常是主執行緒），並在其執行緒中執行所有回呼和 Tasks" -"（任務）。當一個 Task 在事件迴圈中運行時，沒有其他 Task 可以在同一個執行緒中" -"運行。當一個 Task 執行一個 ``await`` 運算式時，正在執行的 Task 會被暫停，而事" -"件迴圈會執行下一個 Task。" - -#: ../../library/asyncio-dev.rst:72 -msgid "" -"To schedule a :term:`callback` from another OS thread, " -"the :meth:`loop.call_soon_threadsafe` method should be used. Example::" -msgstr "" -"要從不同的 OS 執行緒為一個 :term:`callback` 排程，應該使" -"用 :meth:`loop.call_soon_threadsafe` 方法。例如： ::" - -#: ../../library/asyncio-dev.rst:75 -msgid "loop.call_soon_threadsafe(callback, *args)" -msgstr "loop.call_soon_threadsafe(callback, *args)" - -#: ../../library/asyncio-dev.rst:77 -msgid "" -"Almost all asyncio objects are not thread safe, which is typically not a " -"problem unless there is code that works with them from outside of a Task or " -"a callback. If there's a need for such code to call a low-level asyncio " -"API, the :meth:`loop.call_soon_threadsafe` method should be used, e.g.::" -msgstr "" -"幾乎所有 asyncio 物件都不支援執行緒安全 (thread safe)，這通常不是問題，除非" -"在 Task 或回呼函式之外有程式需要和它們一起運作。如果需要這樣的程式來呼叫低階 " -"asyncio API，應該使用 :meth:`loop.call_soon_threadsafe` 方法，例如： ::" - -#: ../../library/asyncio-dev.rst:83 -msgid "loop.call_soon_threadsafe(fut.cancel)" -msgstr "loop.call_soon_threadsafe(fut.cancel)" - -#: ../../library/asyncio-dev.rst:85 -msgid "" -"To schedule a coroutine object from a different OS thread, " -"the :func:`run_coroutine_threadsafe` function should be used. It returns " -"a :class:`concurrent.futures.Future` to access the result::" -msgstr "" -"要從不同的 OS 執行緒為一個協程物件排程，應該使" -"用 :func:`run_coroutine_threadsafe` 函式。它會回傳一" -"個 :class:`concurrent.futures.Future` 以存取結果： ::" - -#: ../../library/asyncio-dev.rst:89 -msgid "" -"async def coro_func():\n" -" return await asyncio.sleep(1, 42)\n" -"\n" -"# Later in another OS thread:\n" -"\n" -"future = asyncio.run_coroutine_threadsafe(coro_func(), loop)\n" -"# Wait for the result:\n" -"result = future.result()" -msgstr "" - -#: ../../library/asyncio-dev.rst:98 -msgid "To handle signals the event loop must be run in the main thread." -msgstr "為了能夠處理訊號，事件迴圈必須於主執行緒中運行。" - -#: ../../library/asyncio-dev.rst:101 -msgid "" -"The :meth:`loop.run_in_executor` method can be used with " -"a :class:`concurrent.futures.ThreadPoolExecutor` " -"or :class:`~concurrent.futures.InterpreterPoolExecutor` to execute blocking " -"code in a different OS thread without blocking the OS thread that the event " -"loop runs in." -msgstr "" -":meth:`loop.run_in_executor` 方法可以" -"和 :class:`concurrent.futures.ThreadPoolExecutor` 或 " -":class:`~concurrent.futures.InterpreterPoolExecutor` 一起使用，這能夠在作業系統" -"上另一個不同的執行緒中執行阻塞程式，且避免阻塞執行事件迴圈的執行緒。" - -#: ../../library/asyncio-dev.rst:107 -msgid "" -"There is currently no way to schedule coroutines or callbacks directly from " -"a different process (such as one started with :mod:`multiprocessing`). " -"The :ref:`asyncio-event-loop-methods` section lists APIs that can read from " -"pipes and watch file descriptors without blocking the event loop. In " -"addition, asyncio's :ref:`Subprocess ` APIs provide a " -"way to start a process and communicate with it from the event loop. Lastly, " -"the aforementioned :meth:`loop.run_in_executor` method can also be used with " -"a :class:`concurrent.futures.ProcessPoolExecutor` to execute code in a " -"different process." -msgstr "" -"目前沒有什麼辦法能直接從另一個行程（例如透過 :mod:`multiprocessing` 啟動的程" -"序）來為協程或回呼排程。:ref:`asyncio-event-loop-methods`\\ 小節列出了可以從 " -"pipes（管道）讀取並監視 file descriptor（檔案描述器）而不會阻塞事件迴圈的 " -"API。此外，asyncio 的\\ :ref:`子行程 ` API 提供了一種啟動" -"行程並從事件迴圈與其通訊的辦法。最後，之前提到" -"的 :meth:`loop.run_in_executor` 方法也可" -"和 :class:`concurrent.futures.ProcessPoolExecutor` 搭配使用，以在另一個行程中" -"執行程式。" - -#: ../../library/asyncio-dev.rst:121 -msgid "Running Blocking Code" -msgstr "執行阻塞的程式" - -#: ../../library/asyncio-dev.rst:123 -msgid "" -"Blocking (CPU-bound) code should not be called directly. For example, if a " -"function performs a CPU-intensive calculation for 1 second, all concurrent " -"asyncio Tasks and IO operations would be delayed by 1 second." -msgstr "" -"不應該直接呼叫阻塞（CPU 密集型）程式。例如一個執行 1 秒 CPU 密集型計算的函" -"式，那麼所有並行非同步 Tasks 和 IO 操作都會被延遲 1 秒。" - -#: ../../library/asyncio-dev.rst:128 -msgid "" -"An executor can be used to run a task in a different thread, including in a " -"different interpreter, or even in a different process to avoid blocking the " -"OS thread with the event loop. See the :meth:`loop.run_in_executor` method " -"for more details." -msgstr "" -"一個 executor（執行器）可以被用來在不同的執行緒（包含不同直譯器）、或甚至不同的行程中執行任務，" -"以避免事件迴圈阻塞了 OS 執行緒。詳情請見 :meth:`loop.run_in_executor` 方" -"法。" - -#: ../../library/asyncio-dev.rst:138 -msgid "Logging" -msgstr "日誌記錄" - -#: ../../library/asyncio-dev.rst:140 -msgid "" -"asyncio uses the :mod:`logging` module and all logging is performed via the " -"``\"asyncio\"`` logger." -msgstr "" -"asyncio 使用 :mod:`logging` 模組，所有日誌記錄都是透過 ``\"asyncio\"`` " -"logger 執行的。" - -#: ../../library/asyncio-dev.rst:143 -msgid "" -"The default log level is :py:const:`logging.INFO`, which can be easily " -"adjusted::" -msgstr "日誌級別被預設為 :py:const:`logging.INFO`，它可以很容易地被調整： ::" - -#: ../../library/asyncio-dev.rst:146 -msgid "logging.getLogger(\"asyncio\").setLevel(logging.WARNING)" -msgstr "logging.getLogger(\"asyncio\").setLevel(logging.WARNING)" - -#: ../../library/asyncio-dev.rst:149 -msgid "" -"Network logging can block the event loop. It is recommended to use a " -"separate thread for handling logs or use non-blocking IO. For example, " -"see :ref:`blocking-handlers`." -msgstr "" -"網路日誌記錄可能會阻塞事件迴圈。建議使用獨立的執行緒來處理日誌或使用非阻塞 " -"IO，範例請參見 :ref:`blocking-handlers`。" - -#: ../../library/asyncio-dev.rst:157 -msgid "Detect never-awaited coroutines" -msgstr "偵測從未被等待的 (never-awaited) 協程" - -#: ../../library/asyncio-dev.rst:159 -msgid "" -"When a coroutine function is called, but not awaited (e.g. ``coro()`` " -"instead of ``await coro()``) or the coroutine is not scheduled " -"with :meth:`asyncio.create_task`, asyncio will emit a :exc:`RuntimeWarning`::" -msgstr "" -"當協程函式被呼叫而不是被等待時（即執行 ``coro()`` 而不是 ``await coro()``）或" -"者協程沒有透過 :meth:`asyncio.create_task` 被排程，asyncio 將會發" -"出 :exc:`RuntimeWarning`： ::" - -#: ../../library/asyncio-dev.rst:164 -msgid "" -"import asyncio\n" -"\n" -"async def test():\n" -" print(\"never scheduled\")\n" -"\n" -"async def main():\n" -" test()\n" -"\n" -"asyncio.run(main())" -msgstr "" -"import asyncio\n" -"\n" -"async def test():\n" -" print(\"never scheduled\")\n" -"\n" -"async def main():\n" -" test()\n" -"\n" -"asyncio.run(main())" - -#: ../../library/asyncio-dev.rst:174 ../../library/asyncio-dev.rst:219 -msgid "Output::" -msgstr "輸出： ::" - -#: ../../library/asyncio-dev.rst:176 -msgid "" -"test.py:7: RuntimeWarning: coroutine 'test' was never awaited\n" -" test()" -msgstr "" -"test.py:7: RuntimeWarning: coroutine 'test' was never awaited\n" -" test()" - -#: ../../library/asyncio-dev.rst:179 ../../library/asyncio-dev.rst:235 -msgid "Output in debug mode::" -msgstr "除錯模式中的輸出： ::" - -#: ../../library/asyncio-dev.rst:181 -msgid "" -"test.py:7: RuntimeWarning: coroutine 'test' was never awaited\n" -"Coroutine created at (most recent call last)\n" -" File \"../t.py\", line 9, in \n" -" asyncio.run(main(), debug=True)\n" -"\n" -" < .. >\n" -"\n" -" File \"../t.py\", line 7, in main\n" -" test()\n" -" test()" -msgstr "" -"test.py:7: RuntimeWarning: coroutine 'test' was never awaited\n" -"Coroutine created at (most recent call last)\n" -" File \"../t.py\", line 9, in \n" -" asyncio.run(main(), debug=True)\n" -"\n" -" < .. >\n" -"\n" -" File \"../t.py\", line 7, in main\n" -" test()\n" -" test()" - -#: ../../library/asyncio-dev.rst:192 -msgid "" -"The usual fix is to either await the coroutine or call " -"the :meth:`asyncio.create_task` function::" -msgstr "" -"常用的修復方法是去等待協程或者呼叫 :meth:`asyncio.create_task` 函式： ::" - -#: ../../library/asyncio-dev.rst:195 -msgid "" -"async def main():\n" -" await test()" -msgstr "" -"async def main():\n" -" await test()" - -#: ../../library/asyncio-dev.rst:200 -msgid "Detect never-retrieved exceptions" -msgstr "偵測從未被取得的 (never-retrieved) 例外" - -#: ../../library/asyncio-dev.rst:202 -msgid "" -"If a :meth:`Future.set_exception` is called but the Future object is never " -"awaited on, the exception would never be propagated to the user code. In " -"this case, asyncio would emit a log message when the Future object is " -"garbage collected." -msgstr "" -"如果呼叫 :meth:`Future.set_exception`，但 Future 物件從未被等待，例外將無法被" -"傳播 (propagate) 到使用者程式。在這種情況下，當 Future 物件被垃圾回收 " -"(garbage collected) 時，asyncio 將發出一則日誌訊息。" - -#: ../../library/asyncio-dev.rst:207 -msgid "Example of an unhandled exception::" -msgstr "未處理例外的例子： ::" - -#: ../../library/asyncio-dev.rst:209 -msgid "" -"import asyncio\n" -"\n" -"async def bug():\n" -" raise Exception(\"not consumed\")\n" -"\n" -"async def main():\n" -" asyncio.create_task(bug())\n" -"\n" -"asyncio.run(main())" -msgstr "" -"import asyncio\n" -"\n" -"async def bug():\n" -" raise Exception(\"not consumed\")\n" -"\n" -"async def main():\n" -" asyncio.create_task(bug())\n" -"\n" -"asyncio.run(main())" - -#: ../../library/asyncio-dev.rst:221 -msgid "" -"Task exception was never retrieved\n" -"future: \n" -" exception=Exception('not consumed')>\n" -"\n" -"Traceback (most recent call last):\n" -" File \"test.py\", line 4, in bug\n" -" raise Exception(\"not consumed\")\n" -"Exception: not consumed" -msgstr "" -"Task exception was never retrieved\n" -"future: \n" -" exception=Exception('not consumed')>\n" -"\n" -"Traceback (most recent call last):\n" -" File \"test.py\", line 4, in bug\n" -" raise Exception(\"not consumed\")\n" -"Exception: not consumed" - -#: ../../library/asyncio-dev.rst:230 -msgid "" -":ref:`Enable the debug mode ` to get the traceback where " -"the task was created::" -msgstr "" -":ref:`啟用除錯模式 `\\ 以取得任務建立處的追蹤資訊 " -"(traceback)： ::" - -#: ../../library/asyncio-dev.rst:233 -msgid "asyncio.run(main(), debug=True)" -msgstr "asyncio.run(main(), debug=True)" - -#: ../../library/asyncio-dev.rst:237 -msgid "" -"Task exception was never retrieved\n" -"future: \n" -" exception=Exception('not consumed') created at asyncio/tasks.py:321>\n" -"\n" -"source_traceback: Object created at (most recent call last):\n" -" File \"../t.py\", line 9, in \n" -" asyncio.run(main(), debug=True)\n" -"\n" -"< .. >\n" -"\n" -"Traceback (most recent call last):\n" -" File \"../t.py\", line 4, in bug\n" -" raise Exception(\"not consumed\")\n" -"Exception: not consumed" -msgstr "" -"Task exception was never retrieved\n" -"future: \n" -" exception=Exception('not consumed') created at asyncio/tasks.py:321>\n" -"\n" -"source_traceback: Object created at (most recent call last):\n" -" File \"../t.py\", line 9, in \n" -" asyncio.run(main(), debug=True)\n" -"\n" -"< .. >\n" -"\n" -"Traceback (most recent call last):\n" -" File \"../t.py\", line 4, in bug\n" -" raise Exception(\"not consumed\")\n" -"Exception: not consumed" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Adrian Liaw , 2018 +# Matt Wang , 2022 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: 2023-02-18 14:17+0800\n" +"Last-Translator: Matt Wang \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" +"X-Generator: Poedit 3.2.2\n" + +#: ../../library/asyncio-dev.rst:7 +msgid "Developing with asyncio" +msgstr "使用 asyncio 開發" + +#: ../../library/asyncio-dev.rst:9 +msgid "" +"Asynchronous programming is different from classic \"sequential\" " +"programming." +msgstr "" +"非同步程式設計 (asynchronous programming) 與傳統的\"順序\"程式設計 " +"(sequential programming) 不同。" + +#: ../../library/asyncio-dev.rst:12 +msgid "" +"This page lists common mistakes and traps and explains how to avoid them." +msgstr "本頁列出常見的錯誤和陷阱，並解釋如何避免它們。" + +#: ../../library/asyncio-dev.rst:19 +msgid "Debug Mode" +msgstr "除錯模式" + +#: ../../library/asyncio-dev.rst:21 +msgid "" +"By default asyncio runs in production mode. In order to ease the " +"development asyncio has a *debug mode*." +msgstr "" +"在預設情況下 asyncio 以正式生產模式 (production mode) 執行。為了讓開發更輕" +"鬆，asyncio 還有一種\\ *除錯模式 (debug mode)*。" + +#: ../../library/asyncio-dev.rst:24 +msgid "There are several ways to enable asyncio debug mode:" +msgstr "有幾種方法可以啟用 asyncio 除錯模式：" + +#: ../../library/asyncio-dev.rst:26 +msgid "Setting the :envvar:`PYTHONASYNCIODEBUG` environment variable to ``1``." +msgstr "將 :envvar:`PYTHONASYNCIODEBUG` 環境變數設定為 ``1``。" + +#: ../../library/asyncio-dev.rst:28 +msgid "Using the :ref:`Python Development Mode `." +msgstr "使用 :ref:`Python 開發模式 (Development Mode) `。" + +#: ../../library/asyncio-dev.rst:30 +msgid "Passing ``debug=True`` to :func:`asyncio.run`." +msgstr "將 ``debug=True`` 傳遞給 :func:`asyncio.run`。" + +#: ../../library/asyncio-dev.rst:32 +msgid "Calling :meth:`loop.set_debug`." +msgstr "呼叫 :meth:`loop.set_debug`。" + +#: ../../library/asyncio-dev.rst:34 +msgid "In addition to enabling the debug mode, consider also:" +msgstr "除了啟用除錯模式外，還要考慮：" + +#: ../../library/asyncio-dev.rst:36 +msgid "" +"setting the log level of the :ref:`asyncio logger ` " +"to :py:const:`logging.DEBUG`, for example the following snippet of code can " +"be run at startup of the application::" +msgstr "" +"將 :ref:`asyncio logger（日誌記錄器） `\\ 的日誌級别設置" +"為 :py:const:`logging.DEBUG`，例如下面的程式片段可以在應用程式啟動時運行： ::" + +#: ../../library/asyncio-dev.rst:40 +msgid "logging.basicConfig(level=logging.DEBUG)" +msgstr "logging.basicConfig(level=logging.DEBUG)" + +#: ../../library/asyncio-dev.rst:42 +msgid "" +"configuring the :mod:`warnings` module to display :exc:`ResourceWarning` " +"warnings. One way of doing that is by using the :option:`-W` ``default`` " +"command line option." +msgstr "" +"配置 :mod:`warnings` 模組以顯示 :exc:`ResourceWarning` 警告。一種方法是使" +"用 :option:`-W` ``default`` 命令列選項。" + +#: ../../library/asyncio-dev.rst:47 +msgid "When the debug mode is enabled:" +msgstr "啟用除錯模式時：" + +#: ../../library/asyncio-dev.rst:49 +msgid "" +"Many non-threadsafe asyncio APIs (such as :meth:`loop.call_soon` " +"and :meth:`loop.call_at` methods) raise an exception if they are called from " +"a wrong thread." +msgstr "" +"許多非執行緒安全 (non-threadsafe) 的 asyncio APIs（例" +"如 :meth:`loop.call_soon` 和 :meth:`loop.call_at` 方法），如果從錯誤的執行緒" +"呼叫就會引發例外。" + +#: ../../library/asyncio-dev.rst:53 +msgid "" +"The execution time of the I/O selector is logged if it takes too long to " +"perform an I/O operation." +msgstr "" +"如果執行一個 I/O 操作花費的時間太長，則將 I/O 選擇器 (selector) 的執行時間記" +"錄到日誌中。" + +#: ../../library/asyncio-dev.rst:56 +msgid "" +"Callbacks taking longer than 100 milliseconds are logged. " +"The :attr:`loop.slow_callback_duration` attribute can be used to set the " +"minimum execution duration in seconds that is considered \"slow\"." +msgstr "" +"執行時間超過 100 毫秒的回呼 (callback) 將會被記錄於日誌。屬" +"性 :attr:`loop.slow_callback_duration` 可用於設定以秒為單位的最小執行持續時" +"間，超過這個值執行時間就會被視為\"緩慢\"。" + +#: ../../library/asyncio-dev.rst:64 +msgid "Concurrency and Multithreading" +msgstr "並行性和多執行緒 (Concurrency and Multithreading)" + +#: ../../library/asyncio-dev.rst:66 +msgid "" +"An event loop runs in a thread (typically the main thread) and executes all " +"callbacks and Tasks in its thread. While a Task is running in the event " +"loop, no other Tasks can run in the same thread. When a Task executes an " +"``await`` expression, the running Task gets suspended, and the event loop " +"executes the next Task." +msgstr "" +"事件迴圈在執行緒中運行（通常是主執行緒），並在其執行緒中執行所有回呼和 Tasks" +"（任務）。當一個 Task 在事件迴圈中運行時，沒有其他 Task 可以在同一個執行緒中" +"運行。當一個 Task 執行一個 ``await`` 運算式時，正在執行的 Task 會被暫停，而事" +"件迴圈會執行下一個 Task。" + +#: ../../library/asyncio-dev.rst:72 +msgid "" +"To schedule a :term:`callback` from another OS thread, " +"the :meth:`loop.call_soon_threadsafe` method should be used. Example::" +msgstr "" +"要從不同的 OS 執行緒為一個 :term:`callback` 排程，應該使" +"用 :meth:`loop.call_soon_threadsafe` 方法。例如： ::" + +#: ../../library/asyncio-dev.rst:75 +msgid "loop.call_soon_threadsafe(callback, *args)" +msgstr "loop.call_soon_threadsafe(callback, *args)" + +#: ../../library/asyncio-dev.rst:77 +msgid "" +"Almost all asyncio objects are not thread safe, which is typically not a " +"problem unless there is code that works with them from outside of a Task or " +"a callback. If there's a need for such code to call a low-level asyncio " +"API, the :meth:`loop.call_soon_threadsafe` method should be used, e.g.::" +msgstr "" +"幾乎所有 asyncio 物件都不支援執行緒安全 (thread safe)，這通常不是問題，除非" +"在 Task 或回呼函式之外有程式需要和它們一起運作。如果需要這樣的程式來呼叫低階 " +"asyncio API，應該使用 :meth:`loop.call_soon_threadsafe` 方法，例如： ::" + +#: ../../library/asyncio-dev.rst:83 +msgid "loop.call_soon_threadsafe(fut.cancel)" +msgstr "loop.call_soon_threadsafe(fut.cancel)" + +#: ../../library/asyncio-dev.rst:85 +msgid "" +"To schedule a coroutine object from a different OS thread, " +"the :func:`run_coroutine_threadsafe` function should be used. It returns " +"a :class:`concurrent.futures.Future` to access the result::" +msgstr "" +"要從不同的 OS 執行緒為一個協程物件排程，應該使" +"用 :func:`run_coroutine_threadsafe` 函式。它會回傳一" +"個 :class:`concurrent.futures.Future` 以存取結果： ::" + +#: ../../library/asyncio-dev.rst:89 +msgid "" +"async def coro_func():\n" +" return await asyncio.sleep(1, 42)\n" +"\n" +"# Later in another OS thread:\n" +"\n" +"future = asyncio.run_coroutine_threadsafe(coro_func(), loop)\n" +"# Wait for the result:\n" +"result = future.result()" +msgstr "" + +#: ../../library/asyncio-dev.rst:98 +msgid "To handle signals the event loop must be run in the main thread." +msgstr "為了能夠處理訊號，事件迴圈必須於主執行緒中運行。" + +#: ../../library/asyncio-dev.rst:101 +msgid "" +"The :meth:`loop.run_in_executor` method can be used with " +"a :class:`concurrent.futures.ThreadPoolExecutor` " +"or :class:`~concurrent.futures.InterpreterPoolExecutor` to execute blocking " +"code in a different OS thread without blocking the OS thread that the event " +"loop runs in." +msgstr "" +":meth:`loop.run_in_executor` 方法可以" +"和 :class:`concurrent.futures.ThreadPoolExecutor` 或 " +":class:`~concurrent.futures.InterpreterPoolExecutor` 一起使用，這能夠在作業系統" +"上另一個不同的執行緒中執行阻塞程式，且避免阻塞執行事件迴圈的執行緒。" + +#: ../../library/asyncio-dev.rst:107 +msgid "" +"There is currently no way to schedule coroutines or callbacks directly from " +"a different process (such as one started with :mod:`multiprocessing`). " +"The :ref:`asyncio-event-loop-methods` section lists APIs that can read from " +"pipes and watch file descriptors without blocking the event loop. In " +"addition, asyncio's :ref:`Subprocess ` APIs provide a " +"way to start a process and communicate with it from the event loop. Lastly, " +"the aforementioned :meth:`loop.run_in_executor` method can also be used with " +"a :class:`concurrent.futures.ProcessPoolExecutor` to execute code in a " +"different process." +msgstr "" +"目前沒有什麼辦法能直接從另一個行程（例如透過 :mod:`multiprocessing` 啟動的程" +"序）來為協程或回呼排程。:ref:`asyncio-event-loop-methods`\\ 小節列出了可以從 " +"pipes（管道）讀取並監視 file descriptor（檔案描述器）而不會阻塞事件迴圈的 " +"API。此外，asyncio 的\\ :ref:`子行程 ` API 提供了一種啟動" +"行程並從事件迴圈與其通訊的辦法。最後，之前提到" +"的 :meth:`loop.run_in_executor` 方法也可" +"和 :class:`concurrent.futures.ProcessPoolExecutor` 搭配使用，以在另一個行程中" +"執行程式。" + +#: ../../library/asyncio-dev.rst:121 +msgid "Running Blocking Code" +msgstr "執行阻塞的程式" + +#: ../../library/asyncio-dev.rst:123 +msgid "" +"Blocking (CPU-bound) code should not be called directly. For example, if a " +"function performs a CPU-intensive calculation for 1 second, all concurrent " +"asyncio Tasks and IO operations would be delayed by 1 second." +msgstr "" +"不應該直接呼叫阻塞（CPU 密集型）程式。例如一個執行 1 秒 CPU 密集型計算的函" +"式，那麼所有並行非同步 Tasks 和 IO 操作都會被延遲 1 秒。" + +#: ../../library/asyncio-dev.rst:128 +msgid "" +"An executor can be used to run a task in a different thread, including in a " +"different interpreter, or even in a different process to avoid blocking the " +"OS thread with the event loop. See the :meth:`loop.run_in_executor` method " +"for more details." +msgstr "" +"一個 executor（執行器）可以被用來在不同的執行緒（包含不同直譯器）、或甚至不同的行程中執行任務，" +"以避免事件迴圈阻塞了 OS 執行緒。詳情請見 :meth:`loop.run_in_executor` 方" +"法。" + +#: ../../library/asyncio-dev.rst:138 +msgid "Logging" +msgstr "日誌記錄" + +#: ../../library/asyncio-dev.rst:140 +msgid "" +"asyncio uses the :mod:`logging` module and all logging is performed via the " +"``\"asyncio\"`` logger." +msgstr "" +"asyncio 使用 :mod:`logging` 模組，所有日誌記錄都是透過 ``\"asyncio\"`` " +"logger 執行的。" + +#: ../../library/asyncio-dev.rst:143 +msgid "" +"The default log level is :py:const:`logging.INFO`, which can be easily " +"adjusted::" +msgstr "日誌級別被預設為 :py:const:`logging.INFO`，它可以很容易地被調整： ::" + +#: ../../library/asyncio-dev.rst:146 +msgid "logging.getLogger(\"asyncio\").setLevel(logging.WARNING)" +msgstr "logging.getLogger(\"asyncio\").setLevel(logging.WARNING)" + +#: ../../library/asyncio-dev.rst:149 +msgid "" +"Network logging can block the event loop. It is recommended to use a " +"separate thread for handling logs or use non-blocking IO. For example, " +"see :ref:`blocking-handlers`." +msgstr "" +"網路日誌記錄可能會阻塞事件迴圈。建議使用獨立的執行緒來處理日誌或使用非阻塞 " +"IO，範例請參見 :ref:`blocking-handlers`。" + +#: ../../library/asyncio-dev.rst:157 +msgid "Detect never-awaited coroutines" +msgstr "偵測從未被等待的 (never-awaited) 協程" + +#: ../../library/asyncio-dev.rst:159 +msgid "" +"When a coroutine function is called, but not awaited (e.g. ``coro()`` " +"instead of ``await coro()``) or the coroutine is not scheduled " +"with :meth:`asyncio.create_task`, asyncio will emit a :exc:`RuntimeWarning`::" +msgstr "" +"當協程函式被呼叫而不是被等待時（即執行 ``coro()`` 而不是 ``await coro()``）或" +"者協程沒有透過 :meth:`asyncio.create_task` 被排程，asyncio 將會發" +"出 :exc:`RuntimeWarning`： ::" + +#: ../../library/asyncio-dev.rst:164 +msgid "" +"import asyncio\n" +"\n" +"async def test():\n" +" print(\"never scheduled\")\n" +"\n" +"async def main():\n" +" test()\n" +"\n" +"asyncio.run(main())" +msgstr "" +"import asyncio\n" +"\n" +"async def test():\n" +" print(\"never scheduled\")\n" +"\n" +"async def main():\n" +" test()\n" +"\n" +"asyncio.run(main())" + +#: ../../library/asyncio-dev.rst:174 ../../library/asyncio-dev.rst:219 +msgid "Output::" +msgstr "輸出： ::" + +#: ../../library/asyncio-dev.rst:176 +msgid "" +"test.py:7: RuntimeWarning: coroutine 'test' was never awaited\n" +" test()" +msgstr "" +"test.py:7: RuntimeWarning: coroutine 'test' was never awaited\n" +" test()" + +#: ../../library/asyncio-dev.rst:179 ../../library/asyncio-dev.rst:235 +msgid "Output in debug mode::" +msgstr "除錯模式中的輸出： ::" + +#: ../../library/asyncio-dev.rst:181 +msgid "" +"test.py:7: RuntimeWarning: coroutine 'test' was never awaited\n" +"Coroutine created at (most recent call last)\n" +" File \"../t.py\", line 9, in \n" +" asyncio.run(main(), debug=True)\n" +"\n" +" < .. >\n" +"\n" +" File \"../t.py\", line 7, in main\n" +" test()\n" +" test()" +msgstr "" +"test.py:7: RuntimeWarning: coroutine 'test' was never awaited\n" +"Coroutine created at (most recent call last)\n" +" File \"../t.py\", line 9, in \n" +" asyncio.run(main(), debug=True)\n" +"\n" +" < .. >\n" +"\n" +" File \"../t.py\", line 7, in main\n" +" test()\n" +" test()" + +#: ../../library/asyncio-dev.rst:192 +msgid "" +"The usual fix is to either await the coroutine or call " +"the :meth:`asyncio.create_task` function::" +msgstr "" +"常用的修復方法是去等待協程或者呼叫 :meth:`asyncio.create_task` 函式： ::" + +#: ../../library/asyncio-dev.rst:195 +msgid "" +"async def main():\n" +" await test()" +msgstr "" +"async def main():\n" +" await test()" + +#: ../../library/asyncio-dev.rst:200 +msgid "Detect never-retrieved exceptions" +msgstr "偵測從未被取得的 (never-retrieved) 例外" + +#: ../../library/asyncio-dev.rst:202 +msgid "" +"If a :meth:`Future.set_exception` is called but the Future object is never " +"awaited on, the exception would never be propagated to the user code. In " +"this case, asyncio would emit a log message when the Future object is " +"garbage collected." +msgstr "" +"如果呼叫 :meth:`Future.set_exception`，但 Future 物件從未被等待，例外將無法被" +"傳播 (propagate) 到使用者程式。在這種情況下，當 Future 物件被垃圾回收 " +"(garbage collected) 時，asyncio 將發出一則日誌訊息。" + +#: ../../library/asyncio-dev.rst:207 +msgid "Example of an unhandled exception::" +msgstr "未處理例外的例子： ::" + +#: ../../library/asyncio-dev.rst:209 +msgid "" +"import asyncio\n" +"\n" +"async def bug():\n" +" raise Exception(\"not consumed\")\n" +"\n" +"async def main():\n" +" asyncio.create_task(bug())\n" +"\n" +"asyncio.run(main())" +msgstr "" +"import asyncio\n" +"\n" +"async def bug():\n" +" raise Exception(\"not consumed\")\n" +"\n" +"async def main():\n" +" asyncio.create_task(bug())\n" +"\n" +"asyncio.run(main())" + +#: ../../library/asyncio-dev.rst:221 +msgid "" +"Task exception was never retrieved\n" +"future: \n" +" exception=Exception('not consumed')>\n" +"\n" +"Traceback (most recent call last):\n" +" File \"test.py\", line 4, in bug\n" +" raise Exception(\"not consumed\")\n" +"Exception: not consumed" +msgstr "" +"Task exception was never retrieved\n" +"future: \n" +" exception=Exception('not consumed')>\n" +"\n" +"Traceback (most recent call last):\n" +" File \"test.py\", line 4, in bug\n" +" raise Exception(\"not consumed\")\n" +"Exception: not consumed" + +#: ../../library/asyncio-dev.rst:230 +msgid "" +":ref:`Enable the debug mode ` to get the traceback where " +"the task was created::" +msgstr "" +":ref:`啟用除錯模式 `\\ 以取得任務建立處的追蹤資訊 " +"(traceback)： ::" + +#: ../../library/asyncio-dev.rst:233 +msgid "asyncio.run(main(), debug=True)" +msgstr "asyncio.run(main(), debug=True)" + +#: ../../library/asyncio-dev.rst:237 +msgid "" +"Task exception was never retrieved\n" +"future: \n" +" exception=Exception('not consumed') created at asyncio/tasks.py:321>\n" +"\n" +"source_traceback: Object created at (most recent call last):\n" +" File \"../t.py\", line 9, in \n" +" asyncio.run(main(), debug=True)\n" +"\n" +"< .. >\n" +"\n" +"Traceback (most recent call last):\n" +" File \"../t.py\", line 4, in bug\n" +" raise Exception(\"not consumed\")\n" +"Exception: not consumed" +msgstr "" +"Task exception was never retrieved\n" +"future: \n" +" exception=Exception('not consumed') created at asyncio/tasks.py:321>\n" +"\n" +"source_traceback: Object created at (most recent call last):\n" +" File \"../t.py\", line 9, in \n" +" asyncio.run(main(), debug=True)\n" +"\n" +"< .. >\n" +"\n" +"Traceback (most recent call last):\n" +" File \"../t.py\", line 4, in bug\n" +" raise Exception(\"not consumed\")\n" +"Exception: not consumed" diff --git a/library/asyncio-eventloop.po b/library/asyncio-eventloop.po index d2237d3c5a..843a43b143 100644 --- a/library/asyncio-eventloop.po +++ b/library/asyncio-eventloop.po @@ -1,3166 +1,3166 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-07 00:14+0000\n" -"PO-Revision-Date: 2022-02-20 12:36+0800\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" -"X-Generator: Poedit 3.4.2\n" - -#: ../../library/asyncio-eventloop.rst:8 -msgid "Event Loop" -msgstr "事件迴圈" - -#: ../../library/asyncio-eventloop.rst:10 -msgid "" -"**Source code:** :source:`Lib/asyncio/events.py`, :source:`Lib/asyncio/" -"base_events.py`" -msgstr "" -"**原始碼：** :source:`Lib/asyncio/events.py`、:source:`Lib/asyncio/" -"base_events.py`" - -#: ../../library/asyncio-eventloop.rst:16 -msgid "Preface" -msgstr "前言" - -#: ../../library/asyncio-eventloop.rst:17 -msgid "" -"The event loop is the core of every asyncio application. Event loops run " -"asynchronous tasks and callbacks, perform network IO operations, and run " -"subprocesses." -msgstr "" -"事件迴圈是每個 asyncio 應用程式的核心。事件迴圈執行非同步任務和回呼、執行網" -"路 IO 操作並啟動子行程。" - -#: ../../library/asyncio-eventloop.rst:21 -msgid "" -"Application developers should typically use the high-level asyncio " -"functions, such as :func:`asyncio.run`, and should rarely need to reference " -"the loop object or call its methods. This section is intended mostly for " -"authors of lower-level code, libraries, and frameworks, who need finer " -"control over the event loop behavior." -msgstr "" -"應用程式開發人員通常應使用高階的 asyncio 函式，例如 :func:`asyncio.run`，並且" -"很少需要參照事件迴圈物件或呼叫其方法。本節主要針對那些需要更細粒度控制事件迴" -"圈行為的低階程式碼、函式庫和框架的作者。" - -#: ../../library/asyncio-eventloop.rst:28 -msgid "Obtaining the Event Loop" -msgstr "取得事件迴圈" - -#: ../../library/asyncio-eventloop.rst:29 -msgid "" -"The following low-level functions can be used to get, set, or create an " -"event loop:" -msgstr "以下的低階函式可用於取得、設置或建立事件迴圈：" - -#: ../../library/asyncio-eventloop.rst:34 -msgid "Return the running event loop in the current OS thread." -msgstr "在目前作業系統執行緒中回傳正在運行的事件迴圈。" - -#: ../../library/asyncio-eventloop.rst:36 -msgid "Raise a :exc:`RuntimeError` if there is no running event loop." -msgstr "如果沒有運行的事件迴圈，則引發 :exc:`RuntimeError`。" - -#: ../../library/asyncio-eventloop.rst:38 -msgid "This function can only be called from a coroutine or a callback." -msgstr "此函式只能從協程或回呼函式中呼叫。" - -#: ../../library/asyncio-eventloop.rst:44 -msgid "Get the current event loop." -msgstr "取得目前的事件迴圈。" - -#: ../../library/asyncio-eventloop.rst:46 -msgid "" -"When called from a coroutine or a callback (e.g. scheduled with call_soon or " -"similar API), this function will always return the running event loop." -msgstr "" -"當從協程或回呼函式呼叫此函式（例如，使用 call_soon 或類似的 API 於排程呼" -"叫），此函式將永遠回傳正在運行的事件迴圈。" - -#: ../../library/asyncio-eventloop.rst:50 -msgid "" -"If there is no running event loop set, the function will return the result " -"of the ``get_event_loop_policy().get_event_loop()`` call." -msgstr "" -"如果沒有設定正在運行的事件迴圈，該函式將回傳 ``get_event_loop_policy()." -"get_event_loop()`` 呼叫的結果。" - -#: ../../library/asyncio-eventloop.rst:53 -msgid "" -"Because this function has rather complex behavior (especially when custom " -"event loop policies are in use), using the :func:`get_running_loop` function " -"is preferred to :func:`get_event_loop` in coroutines and callbacks." -msgstr "" -"由於此函式具有相當複雜的行為（尤其是在使用自訂事件迴圈策略時），在協程和回呼" -"函式中，建議使用 :func:`get_running_loop` 函式，而不是 :func:" -"`get_event_loop`。" - -#: ../../library/asyncio-eventloop.rst:58 -msgid "" -"As noted above, consider using the higher-level :func:`asyncio.run` " -"function, instead of using these lower level functions to manually create " -"and close an event loop." -msgstr "" -"如上所述，可以考慮使用高階的 :func:`asyncio.run` 函式，而不是使用這些較低階的" -"函式手動建立和關閉事件迴圈。" - -#: ../../library/asyncio-eventloop.rst:62 -msgid "Raises a :exc:`RuntimeError` if there is no current event loop." -msgstr "如果沒有目前的事件迴圈，則引發 :exc:`RuntimeError`。" - -#: ../../library/asyncio-eventloop.rst:67 -msgid "" -"The :mod:`!asyncio` policy system is deprecated and will be removed in " -"Python 3.16; from there on, this function will return the current running " -"event loop if present else it will return the loop set by :func:" -"`set_event_loop`." -msgstr "" - -#: ../../library/asyncio-eventloop.rst:74 -msgid "Set *loop* as the current event loop for the current OS thread." -msgstr "將 *loop* 設置為目前 OS 執行緒的目前事件迴圈。" - -#: ../../library/asyncio-eventloop.rst:78 -msgid "Create and return a new event loop object." -msgstr "建立並回傳新的事件迴圈物件。" - -#: ../../library/asyncio-eventloop.rst:80 -msgid "" -"Note that the behaviour of :func:`get_event_loop`, :func:`set_event_loop`, " -"and :func:`new_event_loop` functions can be altered by :ref:`setting a " -"custom event loop policy `." -msgstr "" -"請注意 :func:`get_event_loop`、:func:`set_event_loop` 和 :func:" -"`new_event_loop` 函式的行為可以透過\\ :ref:`設定自訂事件迴圈策略 `\\ 進行調整。" - -#: ../../library/asyncio-eventloop.rst:86 -msgid "Contents" -msgstr "目錄" - -#: ../../library/asyncio-eventloop.rst:87 -msgid "This documentation page contains the following sections:" -msgstr "本頁文件包含以下章節：" - -#: ../../library/asyncio-eventloop.rst:89 -msgid "" -"The `Event Loop Methods`_ section is the reference documentation of the " -"event loop APIs;" -msgstr "" -"`事件迴圈方法 `_\\ 章節是事件迴圈 API 們的參照文件；" - -#: ../../library/asyncio-eventloop.rst:92 -msgid "" -"The `Callback Handles`_ section documents the :class:`Handle` and :class:" -"`TimerHandle` instances which are returned from scheduling methods such as :" -"meth:`loop.call_soon` and :meth:`loop.call_later`;" -msgstr "" -"`回呼處理 `_\\ 章節記錄了從排程方法（如 :meth:`loop." -"call_soon` 和 :meth:`loop.call_later`）回傳的 :class:`Handle` 和 :class:" -"`TimerHandle` 實例；" - -#: ../../library/asyncio-eventloop.rst:96 -msgid "" -"The `Server Objects`_ section documents types returned from event loop " -"methods like :meth:`loop.create_server`;" -msgstr "" -"`Server 物件 `_\\ 章節記錄了從事件迴圈方法（如 :meth:`loop." -"create_server`）回傳的資料型別；" - -#: ../../library/asyncio-eventloop.rst:99 -msgid "" -"The `Event Loop Implementations`_ section documents the :class:" -"`SelectorEventLoop` and :class:`ProactorEventLoop` classes;" -msgstr "" -"`事件迴圈實作 `_\\ 章節記錄了 :class:" -"`SelectorEventLoop` 和 :class:`ProactorEventLoop` 類別；" - -#: ../../library/asyncio-eventloop.rst:102 -msgid "" -"The `Examples`_ section showcases how to work with some event loop APIs." -msgstr "`範例 `_\\ 章節展示了如何使用一些事件迴圈 API。" - -#: ../../library/asyncio-eventloop.rst:109 -msgid "Event Loop Methods" -msgstr "事件迴圈方法" - -#: ../../library/asyncio-eventloop.rst:111 -msgid "Event loops have **low-level** APIs for the following:" -msgstr "事件迴圈提供以下\\ **低階** API：" - -#: ../../library/asyncio-eventloop.rst:119 -msgid "Running and stopping the loop" -msgstr "啟動和停止迴圈" - -#: ../../library/asyncio-eventloop.rst:123 -msgid "Run until the *future* (an instance of :class:`Future`) has completed." -msgstr "運行直到 *future* （一個 :class:`Future` 實例）完成。" - -#: ../../library/asyncio-eventloop.rst:126 -msgid "" -"If the argument is a :ref:`coroutine object ` it is implicitly " -"scheduled to run as a :class:`asyncio.Task`." -msgstr "" -"如果引數是\\ :ref:`協程物件 `，則它將被隱式排程為 :class:`asyncio." -"Task` 運行。" - -#: ../../library/asyncio-eventloop.rst:129 -msgid "Return the Future's result or raise its exception." -msgstr "回傳 Future 的結果或引發其例外。" - -#: ../../library/asyncio-eventloop.rst:133 -msgid "Run the event loop until :meth:`stop` is called." -msgstr "運行事件迴圈直到 :meth:`stop` 被呼叫。" - -#: ../../library/asyncio-eventloop.rst:135 -msgid "" -"If :meth:`stop` is called before :meth:`run_forever` is called, the loop " -"will poll the I/O selector once with a timeout of zero, run all callbacks " -"scheduled in response to I/O events (and those that were already scheduled), " -"and then exit." -msgstr "" -"如果在呼叫 :meth:`run_forever` 之前呼叫 :meth:`stop`，則迴圈將使用超時為零的" -"方式輪詢 I/O 選擇器，運行所有回應 I/O 事件（以及已經排程的事件）的回呼，然後" -"退出。" - -#: ../../library/asyncio-eventloop.rst:140 -msgid "" -"If :meth:`stop` is called while :meth:`run_forever` is running, the loop " -"will run the current batch of callbacks and then exit. Note that new " -"callbacks scheduled by callbacks will not run in this case; instead, they " -"will run the next time :meth:`run_forever` or :meth:`run_until_complete` is " -"called." -msgstr "" -"如果在 :meth:`run_forever` 運行時呼叫 :meth:`stop`，則迴圈將運行目前批次的回" -"呼函式，然後退出。請注意，由回呼函式排程的新回呼在此情況下不會運行；而是在下" -"次呼叫 :meth:`run_forever` 或 :meth:`run_until_complete` 時運行。" - -#: ../../library/asyncio-eventloop.rst:148 -msgid "Stop the event loop." -msgstr "停止事件迴圈。" - -#: ../../library/asyncio-eventloop.rst:152 -msgid "Return ``True`` if the event loop is currently running." -msgstr "如果事件迴圈目前正在運行，則回傳 ``True``。" - -#: ../../library/asyncio-eventloop.rst:156 -msgid "Return ``True`` if the event loop was closed." -msgstr "如果事件迴圈已關閉，則回傳 ``True``。" - -#: ../../library/asyncio-eventloop.rst:160 -msgid "Close the event loop." -msgstr "關閉事件迴圈。" - -#: ../../library/asyncio-eventloop.rst:162 -msgid "" -"The loop must not be running when this function is called. Any pending " -"callbacks will be discarded." -msgstr "不得於迴圈運行中呼叫此函式。將丟棄任何待處理的回呼。" - -#: ../../library/asyncio-eventloop.rst:165 -msgid "" -"This method clears all queues and shuts down the executor, but does not wait " -"for the executor to finish." -msgstr "此方法清除所有佇列並關閉執行器，但不等待執行器完成。" - -#: ../../library/asyncio-eventloop.rst:168 -msgid "" -"This method is idempotent and irreversible. No other methods should be " -"called after the event loop is closed." -msgstr "此方法是冪等且不可逆的。在事件迴圈關閉後不應呼叫其他方法。" - -#: ../../library/asyncio-eventloop.rst:174 -msgid "" -"Schedule all currently open :term:`asynchronous generator` objects to close " -"with an :meth:`~agen.aclose` call. After calling this method, the event " -"loop will issue a warning if a new asynchronous generator is iterated. This " -"should be used to reliably finalize all scheduled asynchronous generators." -msgstr "" -"排程所有目前打開的\\ :term:`非同步產生器 `\\ 物件使" -"用 :meth:`~agen.aclose` 呼叫來關閉。呼叫此方法後，如果疊代新的非同步產生器，" -"事件迴圈將發出警告。應該使用此方法可靠地完成所有已排程的非同步產生器。" - -#: ../../library/asyncio-eventloop.rst:180 -msgid "" -"Note that there is no need to call this function when :func:`asyncio.run` is " -"used." -msgstr "請注意，使用 :func:`asyncio.run` 時不需要呼叫此函式。" - -#: ../../library/asyncio-eventloop.rst:183 -#: ../../library/asyncio-eventloop.rst:1354 -#: ../../library/asyncio-eventloop.rst:1816 -msgid "Example::" -msgstr "範例： ::" - -#: ../../library/asyncio-eventloop.rst:185 -msgid "" -"try:\n" -" loop.run_forever()\n" -"finally:\n" -" loop.run_until_complete(loop.shutdown_asyncgens())\n" -" loop.close()" -msgstr "" -"try:\n" -" loop.run_forever()\n" -"finally:\n" -" loop.run_until_complete(loop.shutdown_asyncgens())\n" -" loop.close()" - -#: ../../library/asyncio-eventloop.rst:196 -msgid "" -"Schedule the closure of the default executor and wait for it to join all of " -"the threads in the :class:`~concurrent.futures.ThreadPoolExecutor`. Once " -"this method has been called, using the default executor with :meth:`loop." -"run_in_executor` will raise a :exc:`RuntimeError`." -msgstr "" -"排程預設執行器的關閉，並等待它加入 :class:`~concurrent.futures." -"ThreadPoolExecutor` 中的所有執行緒。一旦呼叫了此方法，使用預設執行器與 :meth:" -"`loop.run_in_executor` 將引發 :exc:`RuntimeError`。" - -#: ../../library/asyncio-eventloop.rst:202 -msgid "" -"The *timeout* parameter specifies the amount of time (in :class:`float` " -"seconds) the executor will be given to finish joining. With the default, " -"``None``, the executor is allowed an unlimited amount of time." -msgstr "" -"*timeout* 參數指定執行器完成加入所需的時間（以 :class:`float` 秒為單位）。預" -"設情況下為 ``None``，不會限制執行器所花費的時間。" - -#: ../../library/asyncio-eventloop.rst:207 -msgid "" -"If the *timeout* is reached, a :exc:`RuntimeWarning` is emitted and the " -"default executor is terminated without waiting for its threads to finish " -"joining." -msgstr "" -"如果達到 *timeout*，將發出 :exc:`RuntimeWarning` 警告，預設執行器將立即終止，" -"不等待其執行緒完成加入。" - -#: ../../library/asyncio-eventloop.rst:213 -msgid "" -"Do not call this method when using :func:`asyncio.run`, as the latter " -"handles default executor shutdown automatically." -msgstr "" -"使用 :func:`asyncio.run` 時請勿呼叫此方法，因為後者會自動處理預設執行器的關" -"閉。" - -#: ../../library/asyncio-eventloop.rst:218 -msgid "Added the *timeout* parameter." -msgstr "加入 *timeout* 參數。" - -#: ../../library/asyncio-eventloop.rst:222 -msgid "Scheduling callbacks" -msgstr "排程回呼函式" - -#: ../../library/asyncio-eventloop.rst:226 -msgid "" -"Schedule the *callback* :term:`callback` to be called with *args* arguments " -"at the next iteration of the event loop." -msgstr "" -"在事件迴圈的下一次疊代中排程以 *args* 引數呼叫 *callback* :term:`callback`。" - -#: ../../library/asyncio-eventloop.rst:229 -msgid "" -"Return an instance of :class:`asyncio.Handle`, which can be used later to " -"cancel the callback." -msgstr "回傳 :class:`asyncio.Handle` 的實例，稍後可以用於取消回呼函式。" - -#: ../../library/asyncio-eventloop.rst:232 -msgid "" -"Callbacks are called in the order in which they are registered. Each " -"callback will be called exactly once." -msgstr "回呼函式按照其註冊的順序呼叫。每個回呼函式將被呼叫恰好一次。" - -#: ../../library/asyncio-eventloop.rst:235 -msgid "" -"The optional keyword-only *context* argument specifies a custom :class:" -"`contextvars.Context` for the *callback* to run in. Callbacks use the " -"current context when no *context* is provided." -msgstr "" -"選用的僅限關鍵字引數 *context* 指定了要給 *callback* 執行的自訂 :class:" -"`contextvars.Context`。當未提供 *context* 時，回呼函式使用目前情境。" - -#: ../../library/asyncio-eventloop.rst:239 -msgid "Unlike :meth:`call_soon_threadsafe`, this method is not thread-safe." -msgstr "與 :meth:`call_soon_threadsafe` 不同，此方法不是執行緒安全的。" - -#: ../../library/asyncio-eventloop.rst:243 -msgid "" -"A thread-safe variant of :meth:`call_soon`. When scheduling callbacks from " -"another thread, this function *must* be used, since :meth:`call_soon` is not " -"thread-safe." -msgstr "" -"這是 :meth:`call_soon` 的執行緒安全變體。當從另一個執行緒排程回呼函式時，*必" -"須*\\ 使用此函式，因為 :meth:`call_soon` 不是執行緒安全的。" - -#: ../../library/asyncio-eventloop.rst:247 -msgid "" -"This function is safe to be called from a reentrant context or signal " -"handler, however, it is not safe or fruitful to use the returned handle in " -"such contexts." -msgstr "" - -#: ../../library/asyncio-eventloop.rst:250 -msgid "" -"Raises :exc:`RuntimeError` if called on a loop that's been closed. This can " -"happen on a secondary thread when the main application is shutting down." -msgstr "" -"如果在已關閉的迴圈上呼叫，則引發 :exc:`RuntimeError`。在主應用程式關閉時，這" -"可能發生在次要執行緒上。" - -#: ../../library/asyncio-eventloop.rst:254 -msgid "" -"See the :ref:`concurrency and multithreading ` " -"section of the documentation." -msgstr "請參閱文件的\\ :ref:`並行和多執行緒 `\\ 部分。" - -#: ../../library/asyncio-eventloop.rst:257 -#: ../../library/asyncio-eventloop.rst:313 -#: ../../library/asyncio-eventloop.rst:339 -msgid "" -"The *context* keyword-only parameter was added. See :pep:`567` for more " -"details." -msgstr "新增了 *context* 僅限關鍵字參數。詳細資訊請參閱 :pep:`567`。" - -#: ../../library/asyncio-eventloop.rst:265 -msgid "" -"Most :mod:`asyncio` scheduling functions don't allow passing keyword " -"arguments. To do that, use :func:`functools.partial`::" -msgstr "" -"大多數 :mod:`asyncio` 排程函式不允許傳遞關鍵字引數。要傳遞關鍵字引數，請使" -"用 :func:`functools.partial`： ::" - -#: ../../library/asyncio-eventloop.rst:268 -msgid "" -"# will schedule \"print(\"Hello\", flush=True)\"\n" -"loop.call_soon(\n" -" functools.partial(print, \"Hello\", flush=True))" -msgstr "" -"# 將會排程 \"print(\"Hello\", flush=True)\"\n" -"loop.call_soon(\n" -" functools.partial(print, \"Hello\", flush=True))" - -#: ../../library/asyncio-eventloop.rst:272 -msgid "" -"Using partial objects is usually more convenient than using lambdas, as " -"asyncio can render partial objects better in debug and error messages." -msgstr "" -"通常使用 partial 物件比使用 lambda 更方便，因為 asyncio 可以在除錯和錯誤訊息" -"中更好地呈現 partial 物件。" - -#: ../../library/asyncio-eventloop.rst:280 -msgid "Scheduling delayed callbacks" -msgstr "排程延遲的回呼函式" - -#: ../../library/asyncio-eventloop.rst:282 -msgid "" -"Event loop provides mechanisms to schedule callback functions to be called " -"at some point in the future. Event loop uses monotonic clocks to track time." -msgstr "" -"事件迴圈提供為回呼函式排程在將來某個時間點才呼叫的機制。事件迴圈使用了單調時" -"鐘來追蹤時間。" - -#: ../../library/asyncio-eventloop.rst:289 -msgid "" -"Schedule *callback* to be called after the given *delay* number of seconds " -"(can be either an int or a float)." -msgstr "排程 *callback* 在給定的 *delay* 秒數後呼叫（可以是整數或浮點數）。" - -#: ../../library/asyncio-eventloop.rst:292 -#: ../../library/asyncio-eventloop.rst:330 -msgid "" -"An instance of :class:`asyncio.TimerHandle` is returned which can be used to " -"cancel the callback." -msgstr "回傳 :class:`asyncio.TimerHandle` 的實例，可用於取消回呼函式。" - -#: ../../library/asyncio-eventloop.rst:295 -msgid "" -"*callback* will be called exactly once. If two callbacks are scheduled for " -"exactly the same time, the order in which they are called is undefined." -msgstr "" -"*callback* 將只被呼叫恰好一次。如果有兩個回呼函式被排程在完全相同的時間，則其" -"呼叫順序是不定的。" - -#: ../../library/asyncio-eventloop.rst:299 -msgid "" -"The optional positional *args* will be passed to the callback when it is " -"called. If you want the callback to be called with keyword arguments use :" -"func:`functools.partial`." -msgstr "" -"可選的位置引數 *args* 將在呼叫回呼函式時傳遞。如果要使用關鍵字引數呼叫回呼函" -"數，請使用 :func:`functools.partial`。" - -#: ../../library/asyncio-eventloop.rst:303 -msgid "" -"An optional keyword-only *context* argument allows specifying a custom :" -"class:`contextvars.Context` for the *callback* to run in. The current " -"context is used when no *context* is provided." -msgstr "" -"可選的僅限關鍵字 *context* 引數允許為 *callback* 指定自訂的 :class:" -"`contextvars.Context` 以提供運行。當未提供 *context* 時，將使用目前情境。" - -#: ../../library/asyncio-eventloop.rst:309 -msgid "" -"For performance, callbacks scheduled with :meth:`loop.call_later` may run up " -"to one clock-resolution early (see ``time.get_clock_info('monotonic')." -"resolution``)." -msgstr "" - -#: ../../library/asyncio-eventloop.rst:317 -msgid "" -"In Python 3.7 and earlier with the default event loop implementation, the " -"*delay* could not exceed one day. This has been fixed in Python 3.8." -msgstr "" -"在 Python 3.7 及更早版本中，使用預設事件迴圈實作時，*delay* 不能超過一天。這" -"在 Python 3.8 中已經修復。" - -#: ../../library/asyncio-eventloop.rst:324 -msgid "" -"Schedule *callback* to be called at the given absolute timestamp *when* (an " -"int or a float), using the same time reference as :meth:`loop.time`." -msgstr "" -"排程 *callback* 在給定的絕對時間戳 *when* （整數或浮點數）處呼叫，使用與 :" -"meth:`loop.time` 相同的時間參照。" - -#: ../../library/asyncio-eventloop.rst:328 -msgid "This method's behavior is the same as :meth:`call_later`." -msgstr "此方法的行為與 :meth:`call_later` 相同。" - -#: ../../library/asyncio-eventloop.rst:335 -msgid "" -"For performance, callbacks scheduled with :meth:`loop.call_at` may run up to " -"one clock-resolution early (see ``time.get_clock_info('monotonic')." -"resolution``)." -msgstr "" - -#: ../../library/asyncio-eventloop.rst:343 -msgid "" -"In Python 3.7 and earlier with the default event loop implementation, the " -"difference between *when* and the current time could not exceed one day. " -"This has been fixed in Python 3.8." -msgstr "" -"在 Python 3.7 及更早版本中，使用預設事件迴圈實作時，*when* 和目前時間之間的差" -"值不能超過一天。這在 Python 3.8 中已經修復。" - -#: ../../library/asyncio-eventloop.rst:350 -msgid "" -"Return the current time, as a :class:`float` value, according to the event " -"loop's internal monotonic clock." -msgstr "根據事件迴圈的內部單調時鐘，回傳目前時間，以 :class:`float` 值表示。" - -#: ../../library/asyncio-eventloop.rst:354 -msgid "" -"In Python 3.7 and earlier timeouts (relative *delay* or absolute *when*) " -"should not exceed one day. This has been fixed in Python 3.8." -msgstr "" -"在 Python 3.7 及更早版本中，超時（相對 *delay* 或絕對 *when*）不應超過一天。" -"這在 Python 3.8 中已經修復。" - -#: ../../library/asyncio-eventloop.rst:360 -msgid "The :func:`asyncio.sleep` function." -msgstr "函式 :func:`asyncio.sleep`。" - -#: ../../library/asyncio-eventloop.rst:364 -msgid "Creating Futures and Tasks" -msgstr "建立 Futures 和 Tasks" - -#: ../../library/asyncio-eventloop.rst:368 -msgid "Create an :class:`asyncio.Future` object attached to the event loop." -msgstr "建立附加到事件迴圈的 :class:`asyncio.Future` 物件。" - -#: ../../library/asyncio-eventloop.rst:370 -msgid "" -"This is the preferred way to create Futures in asyncio. This lets third-" -"party event loops provide alternative implementations of the Future object " -"(with better performance or instrumentation)." -msgstr "" -"這是在 asyncio 中建立 Futures 的首選方式。這允許第三方事件迴圈提供 Future 物" -"件的替代實作（具有更好的性能或儀器計測表現）。" - -#: ../../library/asyncio-eventloop.rst:378 -msgid "" -"Schedule the execution of :ref:`coroutine ` *coro*. Return a :" -"class:`Task` object." -msgstr "排程執行\\ :ref:`協程 ` *coro*。回傳 :class:`Task` 物件。" - -#: ../../library/asyncio-eventloop.rst:381 -msgid "" -"Third-party event loops can use their own subclass of :class:`Task` for " -"interoperability. In this case, the result type is a subclass of :class:" -"`Task`." -msgstr "" -"第三方事件迴圈可以使用其自己的 :class:`Task` 子類別以實現互操作性" -"（interoperability）。在這種情況下，結果類型是 :class:`Task` 的子類別。" - -#: ../../library/asyncio-eventloop.rst:385 -msgid "" -"The full function signature is largely the same as that of the :class:`Task` " -"constructor (or factory) - all of the keyword arguments to this function are " -"passed through to that interface." -msgstr "" - -#: ../../library/asyncio-eventloop.rst:389 -msgid "" -"If the *name* argument is provided and not ``None``, it is set as the name " -"of the task using :meth:`Task.set_name`." -msgstr "" -"如果提供了 *name* 引數且不為 ``None``，則將其設置為任務的名稱，使用 :meth:" -"`Task.set_name`。" - -#: ../../library/asyncio-eventloop.rst:392 -msgid "" -"An optional keyword-only *context* argument allows specifying a custom :" -"class:`contextvars.Context` for the *coro* to run in. The current context " -"copy is created when no *context* is provided." -msgstr "" -"可選的僅限關鍵字 *context* 引數允許為 *coro* 指定自訂的 :class:" -"`contextvars.Context` 以提供運行。當未提供 *context* 時，將建立目前情境的副" -"本。" - -#: ../../library/asyncio-eventloop.rst:396 -msgid "" -"An optional keyword-only *eager_start* argument allows specifying if the " -"task should execute eagerly during the call to create_task, or be scheduled " -"later. If *eager_start* is not passed the mode set by :meth:`loop." -"set_task_factory` will be used." -msgstr "" - -#: ../../library/asyncio-eventloop.rst:401 -msgid "Added the *name* parameter." -msgstr "加入 *name* 參數。" - -#: ../../library/asyncio-eventloop.rst:404 -msgid "Added the *context* parameter." -msgstr "加入 *context* 參數。" - -#: ../../library/asyncio-eventloop.rst:407 -msgid "" -"Added ``kwargs`` which passes on arbitrary extra parameters, including " -"``name`` and ``context``." -msgstr "" - -#: ../../library/asyncio-eventloop.rst:410 -msgid "" -"Rolled back the change that passes on *name* and *context* (if it is None), " -"while still passing on other arbitrary keyword arguments (to avoid breaking " -"backwards compatibility with 3.13.3)." -msgstr "" - -#: ../../library/asyncio-eventloop.rst:414 -msgid "" -"All *kwargs* are now passed on. The *eager_start* parameter works with eager " -"task factories." -msgstr "" - -#: ../../library/asyncio-eventloop.rst:419 -msgid "Set a task factory that will be used by :meth:`loop.create_task`." -msgstr "設置將由 :meth:`loop.create_task` 使用的任務工廠。" - -#: ../../library/asyncio-eventloop.rst:422 -msgid "" -"If *factory* is ``None`` the default task factory will be set. Otherwise, " -"*factory* must be a *callable* with the signature matching ``(loop, coro, " -"**kwargs)``, where *loop* is a reference to the active event loop, and " -"*coro* is a coroutine object. The callable must pass on all *kwargs*, and " -"return a :class:`asyncio.Task`-compatible object." -msgstr "" -"如果 *factory* 為 ``None``，將設置預設的任務工廠。否則，*factory* 必須是一個" -"具有匹配簽名 ``(loop, coro, **kwargs)`` 的 *callable*，其中 *loop* 是有效事件" -"迴圈的參照、*coro* 是一個協程物件。該可呼叫物件必須傳遞所有 *kwargs* 並回傳一" -"個與 :class:`asyncio.Task` 相容的物件。" - -#: ../../library/asyncio-eventloop.rst:428 -msgid "Required that all *kwargs* are passed on to :class:`asyncio.Task`." -msgstr "" - -#: ../../library/asyncio-eventloop.rst:431 -msgid "" -"*name* is no longer passed to task factories. *context* is no longer passed " -"to task factories if it is ``None``." -msgstr "" - -#: ../../library/asyncio-eventloop.rst:435 -msgid "" -"*name* and *context* are now unconditionally passed on to task factories " -"again." -msgstr "" - -#: ../../library/asyncio-eventloop.rst:440 -msgid "Return a task factory or ``None`` if the default one is in use." -msgstr "回傳任務工廠，如果使用預設任務工廠則回傳 ``None``。" - -#: ../../library/asyncio-eventloop.rst:444 -msgid "Opening network connections" -msgstr "打開網路連線" - -#: ../../library/asyncio-eventloop.rst:456 -msgid "" -"Open a streaming transport connection to a given address specified by *host* " -"and *port*." -msgstr "打開以 *host* 和 *port* 指定之給定地址的串流傳輸連線。" - -#: ../../library/asyncio-eventloop.rst:459 -msgid "" -"The socket family can be either :py:const:`~socket.AF_INET` or :py:const:" -"`~socket.AF_INET6` depending on *host* (or the *family* argument, if " -"provided)." -msgstr "" -"根據 *host*\\ （或提供的 *family* 引數）的情況，socket 家族可以是 :py:const:" -"`~socket.AF_INET` 或 :py:const:`~socket.AF_INET6`。" - -#: ../../library/asyncio-eventloop.rst:463 -msgid "The socket type will be :py:const:`~socket.SOCK_STREAM`." -msgstr "Socket 類型將為 :py:const:`~socket.SOCK_STREAM`。" - -#: ../../library/asyncio-eventloop.rst:465 -#: ../../library/asyncio-eventloop.rst:1264 -#: ../../library/asyncio-eventloop.rst:1281 -msgid "" -"*protocol_factory* must be a callable returning an :ref:`asyncio protocol " -"` implementation." -msgstr "" -"*protocol_factory* 必須是一個回傳 :ref:`asyncio protocol ` " -"實作的可呼叫函式。" - -#: ../../library/asyncio-eventloop.rst:468 -msgid "" -"This method will try to establish the connection in the background. When " -"successful, it returns a ``(transport, protocol)`` pair." -msgstr "" -"此方法將嘗試在背景建立連線。成功時，它將回傳一對 ``(transport, protocol)``。" - -#: ../../library/asyncio-eventloop.rst:471 -msgid "The chronological synopsis of the underlying operation is as follows:" -msgstr "底層操作的時間軸簡介如下：" - -#: ../../library/asyncio-eventloop.rst:473 -msgid "" -"The connection is established and a :ref:`transport ` is " -"created for it." -msgstr "建立連線並為其建立\\ :ref:`傳輸 `。" - -#: ../../library/asyncio-eventloop.rst:476 -msgid "" -"*protocol_factory* is called without arguments and is expected to return a :" -"ref:`protocol ` instance." -msgstr "" -"*protocol_factory* 在無引數的情況下被呼叫，並且預計回傳一個 :ref:`協定 " -"` 實例。" - -#: ../../library/asyncio-eventloop.rst:479 -msgid "" -"The protocol instance is coupled with the transport by calling its :meth:" -"`~BaseProtocol.connection_made` method." -msgstr "" -"透過呼叫其 :meth:`~BaseProtocol.connection_made` 方法，將協定實例與傳輸連線在" -"一起。" - -#: ../../library/asyncio-eventloop.rst:482 -msgid "A ``(transport, protocol)`` tuple is returned on success." -msgstr "成功時回傳一個 ``(transport, protocol)`` 元組。" - -#: ../../library/asyncio-eventloop.rst:484 -msgid "" -"The created transport is an implementation-dependent bidirectional stream." -msgstr "建立的傳輸是一個依賴實作的雙向串流。" - -#: ../../library/asyncio-eventloop.rst:487 -#: ../../library/asyncio-eventloop.rst:620 -msgid "Other arguments:" -msgstr "其他引數：" - -#: ../../library/asyncio-eventloop.rst:489 -msgid "" -"*ssl*: if given and not false, a SSL/TLS transport is created (by default a " -"plain TCP transport is created). If *ssl* is a :class:`ssl.SSLContext` " -"object, this context is used to create the transport; if *ssl* is :const:" -"`True`, a default context returned from :func:`ssl.create_default_context` " -"is used." -msgstr "" -"若有給定 *ssl* 且非 false，將建立 SSL/TLS 傳輸（預設建立普通 TCP 傳輸）。如" -"果 *ssl* 為 :class:`ssl.SSLContext` 物件，則使用該情境來建立傳輸；如果 *ssl* " -"為 :const:`True`，則使用 :func:`ssl.create_default_context` 回傳的預設情境。" - -#: ../../library/asyncio-eventloop.rst:495 -msgid ":ref:`SSL/TLS security considerations `" -msgstr ":ref:`SSL/TLS 安全考量 `" - -#: ../../library/asyncio-eventloop.rst:497 -msgid "" -"*server_hostname* sets or overrides the hostname that the target server's " -"certificate will be matched against. Should only be passed if *ssl* is not " -"``None``. By default the value of the *host* argument is used. If *host* " -"is empty, there is no default and you must pass a value for " -"*server_hostname*. If *server_hostname* is an empty string, hostname " -"matching is disabled (which is a serious security risk, allowing for " -"potential man-in-the-middle attacks)." -msgstr "" -"*server_hostname* 設置或覆蓋目標伺服器憑證將匹配的主機名稱。僅在 *ssl* 不為 " -"``None`` 時傳遞。預設情況下，將使用 *host* 引數的值。如果 *host* 為空，則沒有" -"預設值，必須傳遞 *server_hostname* 的值。若 *server_hostname* 為空字串，將停" -"用主機名稱匹配（這是一個嚴重的安全風險，可能導致中間人攻擊）。" - -#: ../../library/asyncio-eventloop.rst:505 -msgid "" -"*family*, *proto*, *flags* are the optional address family, protocol and " -"flags to be passed through to getaddrinfo() for *host* resolution. If given, " -"these should all be integers from the corresponding :mod:`socket` module " -"constants." -msgstr "" -"*family*、*proto*、*flags* 是可選的位址家族、協定和旗標，用於傳遞至 " -"getaddrinfo() 進行 *host* 解析。若有給定這些應該都是相應 :mod:`socket` 模組常" -"數的整數。" - -#: ../../library/asyncio-eventloop.rst:510 -msgid "" -"*happy_eyeballs_delay*, if given, enables Happy Eyeballs for this " -"connection. It should be a floating-point number representing the amount of " -"time in seconds to wait for a connection attempt to complete, before " -"starting the next attempt in parallel. This is the \"Connection Attempt " -"Delay\" as defined in :rfc:`8305`. A sensible default value recommended by " -"the RFC is ``0.25`` (250 milliseconds)." -msgstr "" -"若有給定，*happy_eyeballs_delay* 會啟用此連線的 Happy Eyeballs。它應該是一個" -"浮點數，表示等待連線嘗試完成的秒數，然後在並行啟動下一次嘗試。這是 :rfc:" -"`8305` 中定義的「連線嘗試延遲」。RFC 建議的合理預設值為 ``0.25`` 秒（250 毫" -"秒）。" - -#: ../../library/asyncio-eventloop.rst:518 -msgid "" -"*interleave* controls address reordering when a host name resolves to " -"multiple IP addresses. If ``0`` or unspecified, no reordering is done, and " -"addresses are tried in the order returned by :meth:`getaddrinfo`. If a " -"positive integer is specified, the addresses are interleaved by address " -"family, and the given integer is interpreted as \"First Address Family " -"Count\" as defined in :rfc:`8305`. The default is ``0`` if " -"*happy_eyeballs_delay* is not specified, and ``1`` if it is." -msgstr "" -"*interleave* 控制主機名稱解析為多個 IP 位址時的地址重新排序。若為 ``0`` 或未" -"指定，將不執行重排序，並按 :meth:`getaddrinfo` 回傳的順序嘗試位址。如果指定正" -"整數，則按地址家族交錯排列，給定的整數直譯為 :rfc:`8305` 中定義的「首個地址家" -"族計數」。如果未指定 *happy_eyeballs_delay*，則預設值為 ``0``，如果指定則為 " -"``1``。" - -#: ../../library/asyncio-eventloop.rst:527 -msgid "" -"*sock*, if given, should be an existing, already connected :class:`socket." -"socket` object to be used by the transport. If *sock* is given, none of " -"*host*, *port*, *family*, *proto*, *flags*, *happy_eyeballs_delay*, " -"*interleave* and *local_addr* should be specified." -msgstr "" -"若有給定 *sock* 則其應為已存在且已連線的 :class:`socket.socket` 物件，可供傳" -"輸使用。如果提供了 *sock*，則不應指定 *host*、*port*、*family*、*proto*、" -"*flags*、*happy_eyeballs_delay*、*interleave* 和 *local_addr* 中的任何一項。" - -#: ../../library/asyncio-eventloop.rst:535 -#: ../../library/asyncio-eventloop.rst:657 -#: ../../library/asyncio-eventloop.rst:905 -msgid "" -"The *sock* argument transfers ownership of the socket to the transport " -"created. To close the socket, call the transport's :meth:`~asyncio." -"BaseTransport.close` method." -msgstr "" -"引數 *sock* 將 socket 所有權轉移給所建立的傳輸 socket，請呼叫傳輸的 :meth:" -"`~asyncio.BaseTransport.close` 方法。" - -#: ../../library/asyncio-eventloop.rst:539 -msgid "" -"*local_addr*, if given, is a ``(local_host, local_port)`` tuple used to bind " -"the socket locally. The *local_host* and *local_port* are looked up using " -"``getaddrinfo()``, similarly to *host* and *port*." -msgstr "" -"若有給定 *local_addr* 則其為一個 ``(local_host, local_port)`` 元組，用於在本" -"地綁定 socket。將使用 ``getaddrinfo()`` 查找 *local_host* 和 *local_port*，方" -"式類似於 *host* 和 *port*。" - -#: ../../library/asyncio-eventloop.rst:543 -#: ../../library/asyncio-eventloop.rst:1001 -msgid "" -"*ssl_handshake_timeout* is (for a TLS connection) the time in seconds to " -"wait for the TLS handshake to complete before aborting the connection. " -"``60.0`` seconds if ``None`` (default)." -msgstr "" -"*ssl_handshake_timeout* （對於 TLS 連線）是等待 TLS 交握的時間，以秒為單位，" -"在那之前若未完成則會中斷連線。如果為 ``None`` （預設值），則會等待 ``60.0`` " -"秒。" - -#: ../../library/asyncio-eventloop.rst:547 -#: ../../library/asyncio-eventloop.rst:812 -#: ../../library/asyncio-eventloop.rst:916 -#: ../../library/asyncio-eventloop.rst:1005 -msgid "" -"*ssl_shutdown_timeout* is the time in seconds to wait for the SSL shutdown " -"to complete before aborting the connection. ``30.0`` seconds if ``None`` " -"(default)." -msgstr "" -"*ssl_shutdown_timeout* 是等待 SSL 關閉完成以前中斷連線的時間，以秒為單位。如" -"果為 ``None`` （預設值），則會等待 ``30.0`` 秒。" - -#: ../../library/asyncio-eventloop.rst:551 -msgid "" -"*all_errors* determines what exceptions are raised when a connection cannot " -"be created. By default, only a single ``Exception`` is raised: the first " -"exception if there is only one or all errors have same message, or a single " -"``OSError`` with the error messages combined. When ``all_errors`` is " -"``True``, an ``ExceptionGroup`` will be raised containing all exceptions " -"(even if there is only one)." -msgstr "" -"*all_errors* 決定在無法建立連線時會引發哪些例外。預設情況下，只會引發單一 " -"``Exception``：如果只有一個例外或所有錯誤訊息相同，則引發第一個例外，否則引發" -"包含所有錯誤訊息的單一 ``OSError``。當 ``all_errors`` 為 ``True`` 時，將引發" -"包含所有例外的 ``ExceptionGroup`` （即使只有一個例外）。" - -#: ../../library/asyncio-eventloop.rst:561 -#: ../../library/asyncio-eventloop.rst:824 -msgid "Added support for SSL/TLS in :class:`ProactorEventLoop`." -msgstr "新增 :class:`ProactorEventLoop` 中的 SSL/TLS 支援。" - -#: ../../library/asyncio-eventloop.rst:565 -msgid "" -"The socket option :ref:`socket.TCP_NODELAY ` is set " -"by default for all TCP connections." -msgstr "" -"所有 TCP 連線都預設有 :ref:`socket.TCP_NODELAY ` " -"socket 選項。" - -#: ../../library/asyncio-eventloop.rst:570 -#: ../../library/asyncio-eventloop.rst:926 -msgid "Added the *ssl_handshake_timeout* parameter." -msgstr "增加 *ssl_handshake_timeout* 參數。" - -#: ../../library/asyncio-eventloop.rst:574 -msgid "Added the *happy_eyeballs_delay* and *interleave* parameters." -msgstr "加入 *happy_eyeballs_delay* 和 *interleave* 參數。" - -#: ../../library/asyncio-eventloop.rst:576 -msgid "" -"Happy Eyeballs Algorithm: Success with Dual-Stack Hosts. When a server's " -"IPv4 path and protocol are working, but the server's IPv6 path and protocol " -"are not working, a dual-stack client application experiences significant " -"connection delay compared to an IPv4-only client. This is undesirable " -"because it causes the dual-stack client to have a worse user experience. " -"This document specifies requirements for algorithms that reduce this user-" -"visible delay and provides an algorithm." -msgstr "" -"Happy Eyeballs 演算法：雙協定堆疊主機 (Dual-Stack Hosts) 的成功。當伺服器的 " -"IPv4 路徑和協定運作正常，但伺服器的 IPv6 路徑和協定不運作時，雙棧用戶端應用程" -"式會比僅具 IPv4 的用戶端體驗到顯著的連線延遲。這是不希望的，因為這會導致雙棧" -"用戶端的使用者體驗變差。本文件具體說明了減少此用戶可見延遲的演算法要求並提供" -"了一種演算法。" - -#: ../../library/asyncio-eventloop.rst:585 -msgid "For more information: https://datatracker.ietf.org/doc/html/rfc6555" -msgstr "更多資訊請見： https://datatracker.ietf.org/doc/html/rfc6555" - -#: ../../library/asyncio-eventloop.rst:589 -#: ../../library/asyncio-eventloop.rst:721 -#: ../../library/asyncio-eventloop.rst:838 -#: ../../library/asyncio-eventloop.rst:878 -#: ../../library/asyncio-eventloop.rst:930 -#: ../../library/asyncio-eventloop.rst:1013 -msgid "Added the *ssl_shutdown_timeout* parameter." -msgstr "增加 *ssl_shutdown_timeout* 參數。" - -#: ../../library/asyncio-eventloop.rst:591 -msgid "*all_errors* was added." -msgstr "已新增 *all_errors*。" - -#: ../../library/asyncio-eventloop.rst:596 -msgid "" -"The :func:`open_connection` function is a high-level alternative API. It " -"returns a pair of (:class:`StreamReader`, :class:`StreamWriter`) that can be " -"used directly in async/await code." -msgstr "" -"函式 :func:`open_connection` 是高階的替代 API。它回傳一對 (:class:" -"`StreamReader`, :class:`StreamWriter`) 可直接在 async/await 程式碼中使用。" - -#: ../../library/asyncio-eventloop.rst:607 -msgid "Create a datagram connection." -msgstr "建立一個資料報連線。" - -#: ../../library/asyncio-eventloop.rst:609 -msgid "" -"The socket family can be either :py:const:`~socket.AF_INET`, :py:const:" -"`~socket.AF_INET6`, or :py:const:`~socket.AF_UNIX`, depending on *host* (or " -"the *family* argument, if provided)." -msgstr "" -"Socket 家族可以是 :py:const:`~socket.AF_INET`、:py:const:`~socket.AF_INET6` " -"或 :py:const:`~socket.AF_UNIX`，視乎 *host*\\ （或提供的 *family* 引數）而" -"定。" - -#: ../../library/asyncio-eventloop.rst:613 -msgid "The socket type will be :py:const:`~socket.SOCK_DGRAM`." -msgstr "Socket 類型將為 :py:const:`~socket.SOCK_DGRAM`。" - -#: ../../library/asyncio-eventloop.rst:615 -#: ../../library/asyncio-eventloop.rst:748 -#: ../../library/asyncio-eventloop.rst:897 -msgid "" -"*protocol_factory* must be a callable returning a :ref:`protocol ` implementation." -msgstr "" -"*protocol_factory* 必須是可呼叫的函式，回傳 :ref:`protocol ` 實作。" - -#: ../../library/asyncio-eventloop.rst:618 -#: ../../library/asyncio-eventloop.rst:703 -msgid "A tuple of ``(transport, protocol)`` is returned on success." -msgstr "成功時回傳 ``(transport, protocol)`` 元組。" - -#: ../../library/asyncio-eventloop.rst:622 -msgid "" -"*local_addr*, if given, is a ``(local_host, local_port)`` tuple used to bind " -"the socket locally. The *local_host* and *local_port* are looked up using :" -"meth:`getaddrinfo`." -msgstr "" -"*local_addr*，如果提供，是一個 ``(local_host, local_port)`` 元組，用於在本地" -"綁定 socket。*local_host* 和 *local_port* 使用 :meth:`getaddrinfo` 來查找。" - -#: ../../library/asyncio-eventloop.rst:628 -msgid "" -"On Windows, when using the proactor event loop with ``local_addr=None``, an :" -"exc:`OSError` with :attr:`!errno.WSAEINVAL` will be raised when running it." -msgstr "" - -#: ../../library/asyncio-eventloop.rst:632 -msgid "" -"*remote_addr*, if given, is a ``(remote_host, remote_port)`` tuple used to " -"connect the socket to a remote address. The *remote_host* and *remote_port* " -"are looked up using :meth:`getaddrinfo`." -msgstr "" -"*remote_addr*，如果提供，是一個 ``(remote_host, remote_port)`` 元組，用於將 " -"socket 連線到遠端位址。 *remote_host* 和 *remote_port* 使用 :meth:" -"`getaddrinfo` 來查找。" - -#: ../../library/asyncio-eventloop.rst:636 -msgid "" -"*family*, *proto*, *flags* are the optional address family, protocol and " -"flags to be passed through to :meth:`getaddrinfo` for *host* resolution. If " -"given, these should all be integers from the corresponding :mod:`socket` " -"module constants." -msgstr "" -"*family*、*proto* 和 *flags* 是用於傳遞給 :meth:`getaddrinfo` 以解析 *host* " -"的可選地址家族、協定和旗標。如果提供，這些應該都是來自相應的 :mod:`socket` 模" -"組常數的整數。" - -#: ../../library/asyncio-eventloop.rst:641 -msgid "" -"*reuse_port* tells the kernel to allow this endpoint to be bound to the same " -"port as other existing endpoints are bound to, so long as they all set this " -"flag when being created. This option is not supported on Windows and some " -"Unixes. If the :ref:`socket.SO_REUSEPORT ` constant " -"is not defined then this capability is unsupported." -msgstr "" -"*reuse_port* 告訴核心允許將此端點綁定到與其他現有端點相同的埠，只要它們在建立" -"時都設定了此旗標。此選項不受 Windows 和某些 Unix 系統支援。如果未定義 :py:" -"const:`socket.SO_REUSEPORT ` 常數，則不支援此功能。" - -#: ../../library/asyncio-eventloop.rst:647 -msgid "" -"*allow_broadcast* tells the kernel to allow this endpoint to send messages " -"to the broadcast address." -msgstr "*allow_broadcast* 告訴核心允許此端點向廣播位址發送訊息。" - -#: ../../library/asyncio-eventloop.rst:650 -msgid "" -"*sock* can optionally be specified in order to use a preexisting, already " -"connected, :class:`socket.socket` object to be used by the transport. If " -"specified, *local_addr* and *remote_addr* should be omitted (must be :const:" -"`None`)." -msgstr "" -"*sock* 可以選擇性地指定，以使用預先存在且已連線的 :class:`socket.socket` 物件" -"供傳輸使用。如果指定，*local_addr* 和 *remote_addr* 應省略（必須是 :const:" -"`None`\\ ）。" - -#: ../../library/asyncio-eventloop.rst:661 -msgid "" -"See :ref:`UDP echo client protocol ` and :" -"ref:`UDP echo server protocol ` examples." -msgstr "" -"請參閱 :ref:`UDP 回應用戶端協定 ` 和 :ref:" -"`UDP 回應伺服器協定 ` 範例。" - -#: ../../library/asyncio-eventloop.rst:664 -msgid "" -"The *family*, *proto*, *flags*, *reuse_address*, *reuse_port*, " -"*allow_broadcast*, and *sock* parameters were added." -msgstr "" -"新增 *family*、*proto*、*flags*、*reuse_address*、*reuse_port*、" -"*allow_broadcast* 和 *sock* 參數。" - -#: ../../library/asyncio-eventloop.rst:668 -msgid "Added support for Windows." -msgstr "新增對於 Windows 的支援。" - -#: ../../library/asyncio-eventloop.rst:671 -msgid "" -"The *reuse_address* parameter is no longer supported, as using :ref:`socket." -"SO_REUSEADDR ` poses a significant security concern " -"for UDP. Explicitly passing ``reuse_address=True`` will raise an exception." -msgstr "" -"不再支援 *reuse_address* 參數，因為使用 :py:const:`~socket.SO_REUSEADDR ` 對" -"於 UDP 存有重大的安全疑慮。明確傳遞 ``reuse_address=True`` 將引發例外。" - -#: ../../library/asyncio-eventloop.rst:677 -msgid "" -"When multiple processes with differing UIDs assign sockets to an identical " -"UDP socket address with ``SO_REUSEADDR``, incoming packets can become " -"randomly distributed among the sockets." -msgstr "" -"當具有不同 UID 的多個行程使用 ``SO_REUSEADDR`` 將 socket 分配給相同的 UDP " -"socket 地址時，傳入的封包可能會在 socket 之間隨機分佈。" - -#: ../../library/asyncio-eventloop.rst:681 -msgid "" -"For supported platforms, *reuse_port* can be used as a replacement for " -"similar functionality. With *reuse_port*, :ref:`socket.SO_REUSEPORT ` is used instead, which specifically prevents processes with " -"differing UIDs from assigning sockets to the same socket address." -msgstr "" -"對於有支援的平台，*reuse_port* 可以用作類似功能的替代方案。使用 " -"*reuse_port*，將改為使用 :py:const:`~socket.SO_REUSEPORT `，該選項明確禁止具" -"有不同 UID 的行程將 socket 分配給相同的 socket 地址。" - -#: ../../library/asyncio-eventloop.rst:688 -msgid "" -"The *reuse_address* parameter, disabled since Python 3.8.1, 3.7.6 and " -"3.6.10, has been entirely removed." -msgstr "" -"自 Python 3.9.0、3.8.1、3.7.6 和 3.6.10 起，已完全移除 *reuse_address* 參數。" - -#: ../../library/asyncio-eventloop.rst:698 -msgid "Create a Unix connection." -msgstr "建立一個 Unix 連線。" - -#: ../../library/asyncio-eventloop.rst:700 -msgid "" -"The socket family will be :py:const:`~socket.AF_UNIX`; socket type will be :" -"py:const:`~socket.SOCK_STREAM`." -msgstr "" -"Socket 家族將為 :py:const:`~socket.AF_UNIX`；socket 類型將為 :py:const:" -"`~socket.SOCK_STREAM`。" - -#: ../../library/asyncio-eventloop.rst:705 -msgid "" -"*path* is the name of a Unix domain socket and is required, unless a *sock* " -"parameter is specified. Abstract Unix sockets, :class:`str`, :class:" -"`bytes`, and :class:`~pathlib.Path` paths are supported." -msgstr "" -"*path* 是 Unix 域 socket 的名稱，除非指定 *sock* 參數，否則為必填。支援抽象 " -"Unix sockets、:class:`str`、:class:`bytes` 和 :class:`~pathlib.Path` 路徑。" - -#: ../../library/asyncio-eventloop.rst:710 -msgid "" -"See the documentation of the :meth:`loop.create_connection` method for " -"information about arguments to this method." -msgstr "" -"有關此方法的引數資訊，請參閱 :meth:`loop.create_connection` 方法的文件。" - -#: ../../library/asyncio-eventloop.rst:713 -#: ../../library/asyncio-eventloop.rst:869 -#: ../../library/asyncio-eventloop.rst:1334 -#: ../../library/asyncio-eventloop.rst:1886 -#: ../../library/asyncio-eventloop.rst:1893 -msgid "Availability" -msgstr "可用性" - -#: ../../library/asyncio-eventloop.rst:715 -msgid "" -"Added the *ssl_handshake_timeout* parameter. The *path* parameter can now be " -"a :term:`path-like object`." -msgstr "" -"新增 *ssl_handshake_timeout* 參數。*path* 參數現在可以是 :term:`path-like " -"object`。" - -#: ../../library/asyncio-eventloop.rst:725 -msgid "Creating network servers" -msgstr "建立網路伺服器" - -#: ../../library/asyncio-eventloop.rst:741 -msgid "" -"Create a TCP server (socket type :const:`~socket.SOCK_STREAM`) listening on " -"*port* of the *host* address." -msgstr "" -"建立一個 TCP 伺服器（socket 類型 :const:`~socket.SOCK_STREAM`\\ ），監聽 " -"*host* 位址的 *port*。" - -#: ../../library/asyncio-eventloop.rst:744 -msgid "Returns a :class:`Server` object." -msgstr "回傳一個 :class:`Server` 物件。" - -#: ../../library/asyncio-eventloop.rst:746 -msgid "Arguments:" -msgstr "引數：" - -#: ../../library/asyncio-eventloop.rst:751 -msgid "" -"The *host* parameter can be set to several types which determine where the " -"server would be listening:" -msgstr "可以將 *host* 參數設為幾種類型，以確定伺服器將監聽的位置：" - -#: ../../library/asyncio-eventloop.rst:754 -msgid "" -"If *host* is a string, the TCP server is bound to a single network interface " -"specified by *host*." -msgstr "如果 *host* 是字串，則 TCP 伺服器綁定到由 *host* 指定的單個網路介面。" - -#: ../../library/asyncio-eventloop.rst:757 -msgid "" -"If *host* is a sequence of strings, the TCP server is bound to all network " -"interfaces specified by the sequence." -msgstr "如果 *host* 是字串序列，則 TCP 伺服器綁定到序列指定的所有網路介面。" - -#: ../../library/asyncio-eventloop.rst:760 -msgid "" -"If *host* is an empty string or ``None``, all interfaces are assumed and a " -"list of multiple sockets will be returned (most likely one for IPv4 and " -"another one for IPv6)." -msgstr "" -"若 *host* 是空字串或 ``None``，則所有介面都被假定並回傳多個 socket 的清單（可" -"能一個用於 IPv4，另一個用於 IPv6）。" - -#: ../../library/asyncio-eventloop.rst:764 -msgid "" -"The *port* parameter can be set to specify which port the server should " -"listen on. If ``0`` or ``None`` (the default), a random unused port will be " -"selected (note that if *host* resolves to multiple network interfaces, a " -"different random port will be selected for each interface)." -msgstr "" -"可以設定 *port* 參數以指定伺服器應該監聽的埠。如果是 ``0`` 或 ``None``\\ （預" -"設值），將隨機選擇一個未使用的埠（請注意，如果 *host* 解析為多個網路介面，將" -"為每個介面隨機選擇不同的隨機埠）。" - -#: ../../library/asyncio-eventloop.rst:769 -msgid "" -"*family* can be set to either :const:`socket.AF_INET` or :const:`~socket." -"AF_INET6` to force the socket to use IPv4 or IPv6. If not set, the *family* " -"will be determined from host name (defaults to :const:`~socket.AF_UNSPEC`)." -msgstr "" -"*family* 可以設定為 :const:`socket.AF_INET` 或 :const:`~socket.AF_INET6` 以強" -"制使用 IPv4 或 IPv6。如果未設定，*family* 將從主機名稱決定（預設為 :const:" -"`~socket.AF_UNSPEC`\\ ）。" - -#: ../../library/asyncio-eventloop.rst:774 -msgid "*flags* is a bitmask for :meth:`getaddrinfo`." -msgstr "*flags* 是 :meth:`getaddrinfo` 的位元遮罩。" - -#: ../../library/asyncio-eventloop.rst:776 -msgid "" -"*sock* can optionally be specified in order to use a preexisting socket " -"object. If specified, *host* and *port* must not be specified." -msgstr "" -"可以可選地指定 *sock* 以使用現有的 socket 物件。如果指定了，*host* 和 *port* " -"不能指定。" - -#: ../../library/asyncio-eventloop.rst:781 -msgid "" -"The *sock* argument transfers ownership of the socket to the server created. " -"To close the socket, call the server's :meth:`~asyncio.Server.close` method." -msgstr "" -"*sock* 引數將 socket 的所有權轉移給建立的伺服器。要關閉 socket，請呼叫伺服器" -"的 :meth:`~asyncio.Server.close` 方法。" - -#: ../../library/asyncio-eventloop.rst:785 -msgid "" -"*backlog* is the maximum number of queued connections passed to :meth:" -"`~socket.socket.listen` (defaults to 100)." -msgstr "" -"*backlog* 是傳遞給 :meth:`~socket.socket.listen` 的最大佇列連線數（預設為 " -"100）。" - -#: ../../library/asyncio-eventloop.rst:788 -msgid "" -"*ssl* can be set to an :class:`~ssl.SSLContext` instance to enable TLS over " -"the accepted connections." -msgstr "" -"*ssl* 可以設定為 :class:`~ssl.SSLContext` 實例以在接受的連線上啟用 TLS。" - -#: ../../library/asyncio-eventloop.rst:791 -msgid "" -"*reuse_address* tells the kernel to reuse a local socket in ``TIME_WAIT`` " -"state, without waiting for its natural timeout to expire. If not specified " -"will automatically be set to ``True`` on Unix." -msgstr "" -"*reuse_address* 告訴內核重用 ``TIME_WAIT`` 狀態下的本地 socket，而不等待其自" -"然超時過期。如果未指定，在 Unix 上將自動設置為 ``True``。" - -#: ../../library/asyncio-eventloop.rst:796 -msgid "" -"*reuse_port* tells the kernel to allow this endpoint to be bound to the same " -"port as other existing endpoints are bound to, so long as they all set this " -"flag when being created. This option is not supported on Windows." -msgstr "" -"*reuse_port* 告訴內核允許此端點繫結到與其他現有端點繫結的相同埠，只要它們在建" -"立時都設置了此旗標。此選項在旗標 Windows 上不受支援。" - -#: ../../library/asyncio-eventloop.rst:801 -msgid "" -"*keep_alive* set to ``True`` keeps connections active by enabling the " -"periodic transmission of messages." -msgstr "將 *keep_alive* 設為 ``True`` 透過啟用定期的訊息傳輸來保持連線活躍。" - -#: ../../library/asyncio-eventloop.rst:806 -msgid "Added the *keep_alive* parameter." -msgstr "加入 *keep_alive* 參數。" - -#: ../../library/asyncio-eventloop.rst:808 -msgid "" -"*ssl_handshake_timeout* is (for a TLS server) the time in seconds to wait " -"for the TLS handshake to complete before aborting the connection. ``60.0`` " -"seconds if ``None`` (default)." -msgstr "" -"（對於 TLS 伺服器）\\ *ssl_handshake_timeout* 是在中斷連線之前等待 TLS 握手完" -"成的時間（以秒為單位）。如果為 ``None``\\ （預設），則為 ``60.0`` 秒。" - -#: ../../library/asyncio-eventloop.rst:816 -msgid "" -"*start_serving* set to ``True`` (the default) causes the created server to " -"start accepting connections immediately. When set to ``False``, the user " -"should await on :meth:`Server.start_serving` or :meth:`Server.serve_forever` " -"to make the server to start accepting connections." -msgstr "" -"將 *start_serving* 設置為 ``True``\\ （預設）將使建立的伺服器立即開始接受連" -"接。當設置為 ``False`` 時，用戶應該等待 :meth:`Server.start_serving` 或 :" -"meth:`Server.serve_forever` 來使伺服器開始接受連線。" - -#: ../../library/asyncio-eventloop.rst:828 -msgid "The *host* parameter can be a sequence of strings." -msgstr "*host* 參數可以是字串序列。" - -#: ../../library/asyncio-eventloop.rst:832 -msgid "" -"Added *ssl_handshake_timeout* and *start_serving* parameters. The socket " -"option :ref:`socket.TCP_NODELAY ` is set by default " -"for all TCP connections." -msgstr "" -"新增 *ssl_handshake_timeout* 與 *start_serving* 參數。所有 TCP 連線都預設有 :" -"ref:`socket.TCP_NODELAY ` socket 選項。" - -#: ../../library/asyncio-eventloop.rst:842 -msgid "" -"The :func:`start_server` function is a higher-level alternative API that " -"returns a pair of :class:`StreamReader` and :class:`StreamWriter` that can " -"be used in an async/await code." -msgstr "" -":func:`start_server` 函式是一個更高階的替代 API，它回傳一對 :class:" -"`StreamReader` 和 :class:`StreamWriter`，可以在 async/await 程式碼中使用。" - -#: ../../library/asyncio-eventloop.rst:854 -msgid "" -"Similar to :meth:`loop.create_server` but works with the :py:const:`~socket." -"AF_UNIX` socket family." -msgstr "" -"類似 :meth:`loop.create_server`，但適用於 :py:const:`~socket.AF_UNIX` socket " -"家族。" - -#: ../../library/asyncio-eventloop.rst:857 -msgid "" -"*path* is the name of a Unix domain socket, and is required, unless a *sock* " -"argument is provided. Abstract Unix sockets, :class:`str`, :class:`bytes`, " -"and :class:`~pathlib.Path` paths are supported." -msgstr "" -"*path* 是 Unix 域 socket 的名稱，除非提供了 *sock* 引數，否則必須給定。支援抽" -"象 Unix sockets、:class:`str`、:class:`bytes` 和 :class:`~pathlib.Path` 路" -"徑。" - -#: ../../library/asyncio-eventloop.rst:862 -msgid "" -"If *cleanup_socket* is true then the Unix socket will automatically be " -"removed from the filesystem when the server is closed, unless the socket has " -"been replaced after the server has been created." -msgstr "" -"如果 *cleanup_socket* 為真，則 Unix socket 將在伺服器關閉時自動從檔案系統中刪" -"除，除非在建立伺服器後替換了 socket。" - -#: ../../library/asyncio-eventloop.rst:866 -msgid "" -"See the documentation of the :meth:`loop.create_server` method for " -"information about arguments to this method." -msgstr "有關此方法的引數資訊，請參閱 :meth:`loop.create_server` 方法的文件。" - -#: ../../library/asyncio-eventloop.rst:873 -msgid "" -"Added the *ssl_handshake_timeout* and *start_serving* parameters. The *path* " -"parameter can now be a :class:`~pathlib.Path` object." -msgstr "" -"新增 *ssl_handshake_timeout* 與 *start_serving* 參數。*path* 參數現在可為一" -"個 :class:`~pathlib.Path` 物件。" - -#: ../../library/asyncio-eventloop.rst:882 -msgid "Added the *cleanup_socket* parameter." -msgstr "加入 *cleanup_socket* 參數。" - -#: ../../library/asyncio-eventloop.rst:890 -msgid "Wrap an already accepted connection into a transport/protocol pair." -msgstr "將已接受的連線包裝成傳輸層/協定對。" - -#: ../../library/asyncio-eventloop.rst:892 -msgid "" -"This method can be used by servers that accept connections outside of " -"asyncio but that use asyncio to handle them." -msgstr "此方法可以由在 asyncio 外接受連線但使用 asyncio 處理連線的伺服器使用。" - -#: ../../library/asyncio-eventloop.rst:895 -#: ../../library/asyncio-eventloop.rst:987 -msgid "Parameters:" -msgstr "參數：" - -#: ../../library/asyncio-eventloop.rst:900 -msgid "" -"*sock* is a preexisting socket object returned from :meth:`socket.accept " -"`." -msgstr "" -"*sock* 是從 :meth:`socket.accept ` 回傳的預先存在的 " -"socket 物件。" - -#: ../../library/asyncio-eventloop.rst:909 -msgid "" -"*ssl* can be set to an :class:`~ssl.SSLContext` to enable SSL over the " -"accepted connections." -msgstr "*ssl* 可以設置為 :class:`~ssl.SSLContext` 以在已接受的連線上啟用 SSL。" - -#: ../../library/asyncio-eventloop.rst:912 -msgid "" -"*ssl_handshake_timeout* is (for an SSL connection) the time in seconds to " -"wait for the SSL handshake to complete before aborting the connection. " -"``60.0`` seconds if ``None`` (default)." -msgstr "" -"（對於 SSL 連線）\\ *ssl_handshake_timeout* 是在中斷連線之前等待 SSL 握手完成" -"的時間（以秒為單位）。如果為 ``None``\\ （預設），則為 ``60.0`` 秒。" - -#: ../../library/asyncio-eventloop.rst:920 -msgid "Returns a ``(transport, protocol)`` pair." -msgstr "回傳 ``(transport, protocol)`` 對。" - -#: ../../library/asyncio-eventloop.rst:934 -msgid "Transferring files" -msgstr "傳輸檔案" - -#: ../../library/asyncio-eventloop.rst:940 -msgid "" -"Send a *file* over a *transport*. Return the total number of bytes sent." -msgstr "透過 *transport* 發送 *file*。回傳發送的總位元組數。" - -#: ../../library/asyncio-eventloop.rst:943 -msgid "The method uses high-performance :meth:`os.sendfile` if available." -msgstr "如果可用，該方法使用高性能 :meth:`os.sendfile`。" - -#: ../../library/asyncio-eventloop.rst:945 -msgid "*file* must be a regular file object opened in binary mode." -msgstr "*file* 必須是以二進位模式打開的常規檔案物件。" - -#: ../../library/asyncio-eventloop.rst:947 -#: ../../library/asyncio-eventloop.rst:1208 -msgid "" -"*offset* tells from where to start reading the file. If specified, *count* " -"is the total number of bytes to transmit as opposed to sending the file " -"until EOF is reached. File position is always updated, even when this method " -"raises an error, and :meth:`file.tell() ` can be used to " -"obtain the actual number of bytes sent." -msgstr "" -"*offset* 告訴從哪裡開始讀取檔案。如果指定了，*count* 是要傳輸的總位元組數，而" -"不是發送檔案直到達到 EOF。即使此方法引發錯誤時，檔案位置也始終更新，可以使" -"用 :meth:`file.tell() ` 取得實際發送的位元組數。" - -#: ../../library/asyncio-eventloop.rst:954 -msgid "" -"*fallback* set to ``True`` makes asyncio to manually read and send the file " -"when the platform does not support the sendfile system call (e.g. Windows or " -"SSL socket on Unix)." -msgstr "" -"將 *fallback* 設置為 ``True`` 會使 asyncio 在平台不支援 sendfile 系統呼叫時" -"（例如 Windows 或 Unix 上的 SSL socket）手動讀取和發送檔案。" - -#: ../../library/asyncio-eventloop.rst:958 -msgid "" -"Raise :exc:`SendfileNotAvailableError` if the system does not support the " -"*sendfile* syscall and *fallback* is ``False``." -msgstr "" -"如果系統不支援 *sendfile* 系統呼叫且 *fallback* 為 ``False``，則引發 :exc:" -"`SendfileNotAvailableError`。" - -#: ../../library/asyncio-eventloop.rst:965 -msgid "TLS Upgrade" -msgstr "TLS 升級" - -#: ../../library/asyncio-eventloop.rst:973 -msgid "Upgrade an existing transport-based connection to TLS." -msgstr "將基於傳輸的現有連線升級到 TLS。" - -#: ../../library/asyncio-eventloop.rst:975 -msgid "" -"Create a TLS coder/decoder instance and insert it between the *transport* " -"and the *protocol*. The coder/decoder implements both *transport*-facing " -"protocol and *protocol*-facing transport." -msgstr "" -"建立 TLS 編解碼器實例並在 *transport* 和 *protocol* 之間插入它。編解碼器既實" -"作了對於 *transport* 的協定，也實作了對於 *protocol* 的傳輸。" - -#: ../../library/asyncio-eventloop.rst:979 -msgid "" -"Return the created two-interface instance. After *await*, the *protocol* " -"must stop using the original *transport* and communicate with the returned " -"object only because the coder caches *protocol*-side data and sporadically " -"exchanges extra TLS session packets with *transport*." -msgstr "" -"回傳建立的雙介面實例。在 *await* 後，*protocol* 必須停止使用原始的 " -"*transport*，僅與回傳的物件通信，因為編碼器快取了 *protocol* 端的資料，並且" -"與 *transport* 間歇性地交換額外的 TLS session 封包。" - -#: ../../library/asyncio-eventloop.rst:984 -msgid "" -"In some situations (e.g. when the passed transport is already closing) this " -"may return ``None``." -msgstr "在某些情況下（例如傳入的傳輸已經關閉），此函式可能回傳 ``None``。" - -#: ../../library/asyncio-eventloop.rst:989 -msgid "" -"*transport* and *protocol* instances that methods like :meth:`~loop." -"create_server` and :meth:`~loop.create_connection` return." -msgstr "" -"*transport* 和 *protocol* 實例，由像 :meth:`~loop.create_server` 和 :meth:" -"`~loop.create_connection` 等方法回傳。" - -#: ../../library/asyncio-eventloop.rst:993 -msgid "*sslcontext*: a configured instance of :class:`~ssl.SSLContext`." -msgstr "*sslcontext*：配置好的 :class:`~ssl.SSLContext` 實例。" - -#: ../../library/asyncio-eventloop.rst:995 -msgid "" -"*server_side* pass ``True`` when a server-side connection is being upgraded " -"(like the one created by :meth:`~loop.create_server`)." -msgstr "" -"當升級伺服器端連線時（像由 :meth:`~loop.create_server` 建立的那樣）傳遞 " -"``True``。" - -#: ../../library/asyncio-eventloop.rst:998 -msgid "" -"*server_hostname*: sets or overrides the host name that the target server's " -"certificate will be matched against." -msgstr "*server_hostname*：設置或覆蓋將用於匹配目標伺服器憑證的主機名。" - -#: ../../library/asyncio-eventloop.rst:1018 -msgid "Watching file descriptors" -msgstr "監視檔案描述器" - -#: ../../library/asyncio-eventloop.rst:1022 -msgid "" -"Start monitoring the *fd* file descriptor for read availability and invoke " -"*callback* with the specified arguments once *fd* is available for reading." -msgstr "" -"開始監視 *fd* 檔案描述器的讀取可用性，一但 *fd* 可讀取，使用指定引數叫用 " -"*callback*。" - -#: ../../library/asyncio-eventloop.rst:1026 -#: ../../library/asyncio-eventloop.rst:1040 -msgid "" -"Any preexisting callback registered for *fd* is cancelled and replaced by " -"*callback*." -msgstr "任何預先存在、為 *fd* 註冊的回呼函式將被取消並替換為 *callback*。" - -#: ../../library/asyncio-eventloop.rst:1031 -msgid "" -"Stop monitoring the *fd* file descriptor for read availability. Returns " -"``True`` if *fd* was previously being monitored for reads." -msgstr "" -"停止監視 *fd* 檔案描述器的讀取可用性。如果 *fd* 之前正在監視讀取，則回傳 " -"``True``。" - -#: ../../library/asyncio-eventloop.rst:1036 -msgid "" -"Start monitoring the *fd* file descriptor for write availability and invoke " -"*callback* with the specified arguments once *fd* is available for writing." -msgstr "" -"開始監視 *fd* 檔案描述器的寫入可用性，一旦 *fd* 可寫入，使用指定引數叫用 " -"*callback*。" - -#: ../../library/asyncio-eventloop.rst:1043 -#: ../../library/asyncio-eventloop.rst:1321 -msgid "" -"Use :func:`functools.partial` :ref:`to pass keyword arguments ` to *callback*." -msgstr "" -"使用 :func:`functools.partial` 向 *callback* :ref:`傳送關鍵字引數 `。" - -#: ../../library/asyncio-eventloop.rst:1048 -msgid "" -"Stop monitoring the *fd* file descriptor for write availability. Returns " -"``True`` if *fd* was previously being monitored for writes." -msgstr "" -"停止監視 *fd* 檔案描述器的寫入可用性。如果 *fd* 之前正在監視寫入，則回傳 " -"``True``。" - -#: ../../library/asyncio-eventloop.rst:1051 -msgid "" -"See also :ref:`Platform Support ` section for some " -"limitations of these methods." -msgstr "" -"另請參閱\\ :ref:`平台支援 `\\ 部分以了解這些方法的" -"一些限制。" - -#: ../../library/asyncio-eventloop.rst:1056 -msgid "Working with socket objects directly" -msgstr "直接使用 socket 物件" - -#: ../../library/asyncio-eventloop.rst:1058 -msgid "" -"In general, protocol implementations that use transport-based APIs such as :" -"meth:`loop.create_connection` and :meth:`loop.create_server` are faster than " -"implementations that work with sockets directly. However, there are some use " -"cases when performance is not critical, and working with :class:`~socket." -"socket` objects directly is more convenient." -msgstr "" -"一般情況下，使用基於傳輸的 API（如 :meth:`loop.create_connection` 和 :meth:" -"`loop.create_server`）的協定實作比直接使用 socket 的實作更快。然而在某些情況" -"下性能不是關鍵，直接使用 :class:`~socket.socket` 物件更方便。" - -#: ../../library/asyncio-eventloop.rst:1068 -msgid "" -"Receive up to *nbytes* from *sock*. Asynchronous version of :meth:`socket." -"recv() `." -msgstr "" -"從 *sock* 接收最多 *nbytes*。:meth:`socket.recv() ` 的非" -"同步版本。" - -#: ../../library/asyncio-eventloop.rst:1071 -msgid "Return the received data as a bytes object." -msgstr "將接收到的資料作為 bytes 物件回傳。" - -#: ../../library/asyncio-eventloop.rst:1073 -#: ../../library/asyncio-eventloop.rst:1088 -#: ../../library/asyncio-eventloop.rst:1100 -#: ../../library/asyncio-eventloop.rst:1113 -#: ../../library/asyncio-eventloop.rst:1129 -#: ../../library/asyncio-eventloop.rst:1145 -#: ../../library/asyncio-eventloop.rst:1156 -#: ../../library/asyncio-eventloop.rst:1183 -#: ../../library/asyncio-eventloop.rst:1222 -msgid "*sock* must be a non-blocking socket." -msgstr "*sock* 必須是非阻塞 socket。" - -#: ../../library/asyncio-eventloop.rst:1075 -msgid "" -"Even though this method was always documented as a coroutine method, " -"releases before Python 3.7 returned a :class:`Future`. Since Python 3.7 this " -"is an ``async def`` method." -msgstr "" -"儘管此方法一直記錄為協程方法，但 Python 3.7 之前的版本回傳 :class:`Future`。" -"自 Python 3.7 起，這是 ``async def`` 方法。" - -#: ../../library/asyncio-eventloop.rst:1083 -msgid "" -"Receive data from *sock* into the *buf* buffer. Modeled after the blocking :" -"meth:`socket.recv_into() ` method." -msgstr "" -"從 *sock* 接收資料到 *buf* 緩衝區。仿照阻塞 :meth:`socket.recv_into() " -"` 方法。" - -#: ../../library/asyncio-eventloop.rst:1086 -msgid "Return the number of bytes written to the buffer." -msgstr "回傳寫入緩衝區位元組的數目。" - -#: ../../library/asyncio-eventloop.rst:1095 -msgid "" -"Receive a datagram of up to *bufsize* from *sock*. Asynchronous version of :" -"meth:`socket.recvfrom() `." -msgstr "" -"從 *sock* 接收最多 *bufsize* 大小的資料單元。:meth:`socket.recvfrom() " -"` 的非同步版本。" - -#: ../../library/asyncio-eventloop.rst:1098 -msgid "Return a tuple of (received data, remote address)." -msgstr "回傳一個元組 (received data, remote address)。" - -#: ../../library/asyncio-eventloop.rst:1107 -msgid "" -"Receive a datagram of up to *nbytes* from *sock* into *buf*. Asynchronous " -"version of :meth:`socket.recvfrom_into() `." -msgstr "" -"從 *sock* 接收最多 *nbytes* 大小的資料單元到 *buf*。:meth:`socket." -"recvfrom_into() ` 的非同步版本。" - -#: ../../library/asyncio-eventloop.rst:1111 -msgid "Return a tuple of (number of bytes received, remote address)." -msgstr "回傳一個元組 (number of bytes received, remote address)。" - -#: ../../library/asyncio-eventloop.rst:1120 -msgid "" -"Send *data* to the *sock* socket. Asynchronous version of :meth:`socket." -"sendall() `." -msgstr "" -"將 *data* 發送到 *sock* socket。:meth:`socket.sendall() ` 的非同步版本。" - -#: ../../library/asyncio-eventloop.rst:1123 -msgid "" -"This method continues to send to the socket until either all data in *data* " -"has been sent or an error occurs. ``None`` is returned on success. On " -"error, an exception is raised. Additionally, there is no way to determine " -"how much data, if any, was successfully processed by the receiving end of " -"the connection." -msgstr "" -"此方法將繼續發送到 socket，直到 *data* 中的所有資料都已發送或發生錯誤。成功時" -"回傳 ``None``。錯誤時引發例外。此外，沒有辦法確定接收端成功處理了多少資料（如" -"果有的話）。" - -#: ../../library/asyncio-eventloop.rst:1131 -#: ../../library/asyncio-eventloop.rst:1185 -msgid "" -"Even though the method was always documented as a coroutine method, before " -"Python 3.7 it returned a :class:`Future`. Since Python 3.7, this is an " -"``async def`` method." -msgstr "" -"儘管該方法一直被記錄為協程方法，但在 Python 3.7 之前它回傳 :class:`Future`。" -"從 Python 3.7 開始，這是一個 ``async def`` 方法。" - -#: ../../library/asyncio-eventloop.rst:1139 -msgid "" -"Send a datagram from *sock* to *address*. Asynchronous version of :meth:" -"`socket.sendto() `." -msgstr "" -"從 *sock* 向 *address* 發送一個資料單元。:meth:`socket.sendto() ` 的非同步版本。" - -#: ../../library/asyncio-eventloop.rst:1143 -msgid "Return the number of bytes sent." -msgstr "回傳發送的位元組數。" - -#: ../../library/asyncio-eventloop.rst:1152 -msgid "Connect *sock* to a remote socket at *address*." -msgstr "將 *sock* 連線到位於 *address* 的遠端 socket。" - -#: ../../library/asyncio-eventloop.rst:1154 -msgid "" -"Asynchronous version of :meth:`socket.connect() `." -msgstr ":meth:`socket.connect() ` 的非同步版本。" - -#: ../../library/asyncio-eventloop.rst:1158 -msgid "" -"``address`` no longer needs to be resolved. ``sock_connect`` will try to " -"check if the *address* is already resolved by calling :func:`socket." -"inet_pton`. If not, :meth:`loop.getaddrinfo` will be used to resolve the " -"*address*." -msgstr "" -"不再需要解析 ``address``。``sock_connect`` 將嘗試透過呼叫 :func:`socket." -"inet_pton` 檢查 *address* 是否已解析。如果沒有，將使用 :meth:`loop." -"getaddrinfo` 解析 *address*。" - -#: ../../library/asyncio-eventloop.rst:1167 -msgid "" -":meth:`loop.create_connection` and :func:`asyncio.open_connection() " -"`." -msgstr "" -":meth:`loop.create_connection` 和 :func:`asyncio.open_connection() " -"`。" - -#: ../../library/asyncio-eventloop.rst:1174 -msgid "" -"Accept a connection. Modeled after the blocking :meth:`socket.accept() " -"` method." -msgstr "" -"接受一個連線。模擬阻塞的 :meth:`socket.accept() ` 方" -"法。" - -#: ../../library/asyncio-eventloop.rst:1177 -msgid "" -"The socket must be bound to an address and listening for connections. The " -"return value is a pair ``(conn, address)`` where *conn* is a *new* socket " -"object usable to send and receive data on the connection, and *address* is " -"the address bound to the socket on the other end of the connection." -msgstr "" -"Socket 必須繫結到一個地址並偵聽連線。回傳值是一個 ``(conn, address)`` 對，其" -"中 *conn* 是一個 *新* socket 物件，可在連線上發送和接收資料，*address* 是連接" -"另一端對應的 socket 地址。" - -#: ../../library/asyncio-eventloop.rst:1192 -msgid ":meth:`loop.create_server` and :func:`start_server`." -msgstr ":meth:`loop.create_server` 和 :func:`start_server`。" - -#: ../../library/asyncio-eventloop.rst:1198 -msgid "" -"Send a file using high-performance :mod:`os.sendfile` if possible. Return " -"the total number of bytes sent." -msgstr "" -"如果可行，使用高性能 :mod:`os.sendfile` 發送檔案。回傳發送的總位元組數。" - -#: ../../library/asyncio-eventloop.rst:1201 -msgid "" -"Asynchronous version of :meth:`socket.sendfile() `." -msgstr ":meth:`socket.sendfile() ` 的非同步版本。" - -#: ../../library/asyncio-eventloop.rst:1203 -msgid "" -"*sock* must be a non-blocking :const:`socket.SOCK_STREAM` :class:`~socket." -"socket`." -msgstr "" -"*sock* 必須是非阻塞的 :const:`socket.SOCK_STREAM` :class:`~socket.socket`。" - -#: ../../library/asyncio-eventloop.rst:1206 -msgid "*file* must be a regular file object open in binary mode." -msgstr "*file* 必須是以二進位模式打開的常規檔案物件。" - -#: ../../library/asyncio-eventloop.rst:1215 -msgid "" -"*fallback*, when set to ``True``, makes asyncio manually read and send the " -"file when the platform does not support the sendfile syscall (e.g. Windows " -"or SSL socket on Unix)." -msgstr "" -"當設置為 ``True`` 時，*fallback* 使 asyncio 在平台不支援 sendfile 系統呼叫時" -"（例如 Windows 或 Unix 上的 SSL socket）手動讀取和發送檔案。" - -#: ../../library/asyncio-eventloop.rst:1219 -msgid "" -"Raise :exc:`SendfileNotAvailableError` if the system does not support " -"*sendfile* syscall and *fallback* is ``False``." -msgstr "" -"如果系統不支援 *sendfile* 系統呼叫且 *fallback* 為 ``False``，引發 :exc:" -"`SendfileNotAvailableError`。" - -#: ../../library/asyncio-eventloop.rst:1228 -msgid "DNS" -msgstr "DNS" - -#: ../../library/asyncio-eventloop.rst:1234 -msgid "Asynchronous version of :meth:`socket.getaddrinfo`." -msgstr ":meth:`socket.getaddrinfo` 的非同步版本。" - -#: ../../library/asyncio-eventloop.rst:1239 -msgid "Asynchronous version of :meth:`socket.getnameinfo`." -msgstr ":meth:`socket.getnameinfo` 的非同步版本。" - -#: ../../library/asyncio-eventloop.rst:1242 -msgid "" -"Both *getaddrinfo* and *getnameinfo* internally utilize their synchronous " -"versions through the loop's default thread pool executor. When this executor " -"is saturated, these methods may experience delays, which higher-level " -"networking libraries may report as increased timeouts. To mitigate this, " -"consider using a custom executor for other user tasks, or setting a default " -"executor with a larger number of workers." -msgstr "" - -#: ../../library/asyncio-eventloop.rst:1249 -msgid "" -"Both *getaddrinfo* and *getnameinfo* methods were always documented to " -"return a coroutine, but prior to Python 3.7 they were, in fact, returning :" -"class:`asyncio.Future` objects. Starting with Python 3.7 both methods are " -"coroutines." -msgstr "" -"*getaddrinfo* 和 *getnameinfo* 方法一直被記錄為回傳協程，但在 Python 3.7 之前" -"它們實際上回傳 :class:`asyncio.Future` 物件。從 Python 3.7 開始，兩個方法都是" -"協程。" - -#: ../../library/asyncio-eventloop.rst:1257 -msgid "Working with pipes" -msgstr "使用管道" - -#: ../../library/asyncio-eventloop.rst:1262 -msgid "Register the read end of *pipe* in the event loop." -msgstr "在事件迴圈中註冊 *pipe* 的讀取端。" - -#: ../../library/asyncio-eventloop.rst:1267 -msgid "*pipe* is a :term:`file-like object `." -msgstr "*pipe* 是 :term:`類檔案物件 `。" - -#: ../../library/asyncio-eventloop.rst:1269 -msgid "" -"Return pair ``(transport, protocol)``, where *transport* supports the :class:" -"`ReadTransport` interface and *protocol* is an object instantiated by the " -"*protocol_factory*." -msgstr "" -"回傳 ``(transport, protocol)`` 對，其中 *transport* 支援 :class:" -"`ReadTransport` 介面，*protocol* 是由 *protocol_factory* 實例化的物件。" - -#: ../../library/asyncio-eventloop.rst:1273 -#: ../../library/asyncio-eventloop.rst:1290 -msgid "" -"With :class:`SelectorEventLoop` event loop, the *pipe* is set to non-" -"blocking mode." -msgstr "使用 :class:`SelectorEventLoop` 事件迴圈時，*pipe* 設置為非阻塞模式。" - -#: ../../library/asyncio-eventloop.rst:1279 -msgid "Register the write end of *pipe* in the event loop." -msgstr "在事件迴圈中註冊 *pipe* 的寫入端。" - -#: ../../library/asyncio-eventloop.rst:1284 -msgid "*pipe* is :term:`file-like object `." -msgstr "*pipe* 是 :term:`file-like object `。" - -#: ../../library/asyncio-eventloop.rst:1286 -msgid "" -"Return pair ``(transport, protocol)``, where *transport* supports :class:" -"`WriteTransport` interface and *protocol* is an object instantiated by the " -"*protocol_factory*." -msgstr "" -"回傳 ``(transport, protocol)`` 對，其中 *transport* 支援 :class:" -"`WriteTransport` 介面，*protocol* 是由 *protocol_factory* 實例化的物件。" - -#: ../../library/asyncio-eventloop.rst:1295 -msgid "" -":class:`SelectorEventLoop` does not support the above methods on Windows. " -"Use :class:`ProactorEventLoop` instead for Windows." -msgstr "" -":class:`SelectorEventLoop` 在 Windows 上不支援上述方法。對於 Windows 請使用 :" -"class:`ProactorEventLoop`。" - -#: ../../library/asyncio-eventloop.rst:1300 -msgid "" -"The :meth:`loop.subprocess_exec` and :meth:`loop.subprocess_shell` methods." -msgstr ":meth:`loop.subprocess_exec` 和 :meth:`loop.subprocess_shell` 方法。" - -#: ../../library/asyncio-eventloop.rst:1305 -msgid "Unix signals" -msgstr "Unix 訊號" - -#: ../../library/asyncio-eventloop.rst:1311 -msgid "Set *callback* as the handler for the *signum* signal." -msgstr "將 *callback* 設置為 *signum* 訊號的處理程式。" - -#: ../../library/asyncio-eventloop.rst:1313 -msgid "" -"The callback will be invoked by *loop*, along with other queued callbacks " -"and runnable coroutines of that event loop. Unlike signal handlers " -"registered using :func:`signal.signal`, a callback registered with this " -"function is allowed to interact with the event loop." -msgstr "" -"該回呼將由 *loop* 叫用，與該事件迴圈的其他排隊回呼和可運行的協程一起。與使" -"用 :func:`signal.signal` 註冊的訊號處理程式不同，使用此函式註冊的回呼允許與事" -"件迴圈進行互動。" - -#: ../../library/asyncio-eventloop.rst:1318 -msgid "" -"Raise :exc:`ValueError` if the signal number is invalid or uncatchable. " -"Raise :exc:`RuntimeError` if there is a problem setting up the handler." -msgstr "" -"如果訊號號無效或不可捕獲，引發 :exc:`ValueError`。如果設定處理程序有問題，拋" -"出 :exc:`RuntimeError`。" - -#: ../../library/asyncio-eventloop.rst:1324 -msgid "" -"Like :func:`signal.signal`, this function must be invoked in the main thread." -msgstr "像 :func:`signal.signal` 一樣，此函式必須在主執行緒中叫用。" - -#: ../../library/asyncio-eventloop.rst:1329 -msgid "Remove the handler for the *sig* signal." -msgstr "移除 *sig* 訊號的處理程式。" - -#: ../../library/asyncio-eventloop.rst:1331 -msgid "" -"Return ``True`` if the signal handler was removed, or ``False`` if no " -"handler was set for the given signal." -msgstr "" -"如果訊號處理程式被移除，回傳 ``True``；如果給定訊號沒有設置處理程式，回傳 " -"``False``。" - -#: ../../library/asyncio-eventloop.rst:1338 -msgid "The :mod:`signal` module." -msgstr ":mod:`signal` 模組。" - -#: ../../library/asyncio-eventloop.rst:1342 -msgid "Executing code in thread or process pools" -msgstr "在執行緒池或行程池中執行程式碼" - -#: ../../library/asyncio-eventloop.rst:1346 -msgid "Arrange for *func* to be called in the specified executor." -msgstr "安排在指定的執行器中呼叫 *func*。" - -#: ../../library/asyncio-eventloop.rst:1348 -msgid "" -"The *executor* argument should be an :class:`concurrent.futures.Executor` " -"instance. The default executor is used if *executor* is ``None``. The " -"default executor can be set by :meth:`loop.set_default_executor`, otherwise, " -"a :class:`concurrent.futures.ThreadPoolExecutor` will be lazy-initialized " -"and used by :func:`run_in_executor` if needed." -msgstr "" - -#: ../../library/asyncio-eventloop.rst:1356 -msgid "" -"import asyncio\n" -"import concurrent.futures\n" -"\n" -"def blocking_io():\n" -" # File operations (such as logging) can block the\n" -" # event loop: run them in a thread pool.\n" -" with open('/dev/urandom', 'rb') as f:\n" -" return f.read(100)\n" -"\n" -"def cpu_bound():\n" -" # CPU-bound operations will block the event loop:\n" -" # in general it is preferable to run them in a\n" -" # process pool.\n" -" return sum(i * i for i in range(10 ** 7))\n" -"\n" -"async def main():\n" -" loop = asyncio.get_running_loop()\n" -"\n" -" ## Options:\n" -"\n" -" # 1. Run in the default loop's executor:\n" -" result = await loop.run_in_executor(\n" -" None, blocking_io)\n" -" print('default thread pool', result)\n" -"\n" -" # 2. Run in a custom thread pool:\n" -" with concurrent.futures.ThreadPoolExecutor() as pool:\n" -" result = await loop.run_in_executor(\n" -" pool, blocking_io)\n" -" print('custom thread pool', result)\n" -"\n" -" # 3. Run in a custom process pool:\n" -" with concurrent.futures.ProcessPoolExecutor() as pool:\n" -" result = await loop.run_in_executor(\n" -" pool, cpu_bound)\n" -" print('custom process pool', result)\n" -"\n" -" # 4. Run in a custom interpreter pool:\n" -" with concurrent.futures.InterpreterPoolExecutor() as pool:\n" -" result = await loop.run_in_executor(\n" -" pool, cpu_bound)\n" -" print('custom interpreter pool', result)\n" -"\n" -"if __name__ == '__main__':\n" -" asyncio.run(main())" -msgstr "" - -#: ../../library/asyncio-eventloop.rst:1402 -msgid "" -"Note that the entry point guard (``if __name__ == '__main__'``) is required " -"for option 3 due to the peculiarities of :mod:`multiprocessing`, which is " -"used by :class:`~concurrent.futures.ProcessPoolExecutor`. See :ref:`Safe " -"importing of main module `." -msgstr "" -"請注意，由於 :mod:`multiprocessing`\\ （由 :class:`~concurrent.futures." -"ProcessPoolExecutor` 使用）的特殊性，選項 3 需要進入點保護（\\ ``if __name__ " -"== '__main__'``\\ ）。請參閱\\ :ref:`主模組的安全引入 `。" - -#: ../../library/asyncio-eventloop.rst:1407 -msgid "This method returns a :class:`asyncio.Future` object." -msgstr "此方法回傳 :class:`asyncio.Future` 物件。" - -#: ../../library/asyncio-eventloop.rst:1409 -msgid "" -"Use :func:`functools.partial` :ref:`to pass keyword arguments ` to *func*." -msgstr "" -"使用 :func:`functools.partial` 將來\\ :ref:`關鍵字引數傳遞 `\\ 給 *func*。" - -#: ../../library/asyncio-eventloop.rst:1412 -msgid "" -":meth:`loop.run_in_executor` no longer configures the ``max_workers`` of the " -"thread pool executor it creates, instead leaving it up to the thread pool " -"executor (:class:`~concurrent.futures.ThreadPoolExecutor`) to set the " -"default." -msgstr "" -":meth:`loop.run_in_executor` 不再配置它建立的執行緒池執行器的 " -"``max_workers``，而是讓執行緒池執行器（\\ :class:`~concurrent.futures." -"ThreadPoolExecutor`）設定預設值。" - -#: ../../library/asyncio-eventloop.rst:1421 -msgid "" -"Set *executor* as the default executor used by :meth:`run_in_executor`. " -"*executor* must be an instance of :class:`~concurrent.futures." -"ThreadPoolExecutor`, which includes :class:`~concurrent.futures." -"InterpreterPoolExecutor`." -msgstr "" -"將 *executor* 設置為 :meth:`run_in_executor` 使用的預設執行器。*executor* 必" -"須是 :class:`~concurrent.futures.ThreadPoolExecutor`\\ （也包含 :class:" -"`~concurrent.futures.InterpreterPoolExecutor`）的實例。" - -#: ../../library/asyncio-eventloop.rst:1426 -msgid "" -"*executor* must be an instance of :class:`~concurrent.futures." -"ThreadPoolExecutor`." -msgstr "" -"*executor* 必須是 :class:`~concurrent.futures.ThreadPoolExecutor` 的實例。" - -#: ../../library/asyncio-eventloop.rst:1432 -msgid "Error Handling API" -msgstr "錯誤處理 API" - -#: ../../library/asyncio-eventloop.rst:1434 -msgid "Allows customizing how exceptions are handled in the event loop." -msgstr "允許自訂事件迴圈中的例外處理方式。" - -#: ../../library/asyncio-eventloop.rst:1438 -msgid "Set *handler* as the new event loop exception handler." -msgstr "將 *handler* 設定為新的事件迴圈例外處理程式。" - -#: ../../library/asyncio-eventloop.rst:1440 -msgid "" -"If *handler* is ``None``, the default exception handler will be set. " -"Otherwise, *handler* must be a callable with the signature matching ``(loop, " -"context)``, where ``loop`` is a reference to the active event loop, and " -"``context`` is a ``dict`` object containing the details of the exception " -"(see :meth:`call_exception_handler` documentation for details about context)." -msgstr "" -"如果 *handler* 是 ``None``，則將設置預設例外處理程式。否則，*handler* 必須是" -"一個可呼叫物件，簽名匹配 ``(loop, context)``，其中 ``loop`` 是參照活躍事件迴" -"圈的，``context`` 是包含例外詳細資訊的 ``dict`` 物件（有關情境的詳細資訊，請" -"參閱 :meth:`call_exception_handler` 文件）。" - -#: ../../library/asyncio-eventloop.rst:1448 -msgid "" -"If the handler is called on behalf of a :class:`~asyncio.Task` or :class:" -"`~asyncio.Handle`, it is run in the :class:`contextvars.Context` of that " -"task or callback handle." -msgstr "" -"如果代表 :class:`~asyncio.Task` 或 :class:`~asyncio.Handle` 呼叫處理程式，它" -"將在該任務或回呼處理程式的 :class:`contextvars.Context` 中運行。" - -#: ../../library/asyncio-eventloop.rst:1454 -msgid "" -"The handler may be called in the :class:`~contextvars.Context` of the task " -"or handle where the exception originated." -msgstr "" -"處理程式可能在引發例外的任務或處理程式的 :class:`~contextvars.Context` 中被呼" -"叫。" - -#: ../../library/asyncio-eventloop.rst:1459 -msgid "" -"Return the current exception handler, or ``None`` if no custom exception " -"handler was set." -msgstr "" -"回傳目前的例外處理程式，如果未設置自訂例外處理程式，則回傳 ``None``。" - -#: ../../library/asyncio-eventloop.rst:1466 -msgid "Default exception handler." -msgstr "預設例外處理程式。" - -#: ../../library/asyncio-eventloop.rst:1468 -msgid "" -"This is called when an exception occurs and no exception handler is set. " -"This can be called by a custom exception handler that wants to defer to the " -"default handler behavior." -msgstr "" -"當發生例外且未設置例外處理程式時呼叫此函式。自訂例外處理程式可以呼叫此函式" -"以轉由預設處理程式處理。" - -#: ../../library/asyncio-eventloop.rst:1472 -msgid "" -"*context* parameter has the same meaning as in :meth:" -"`call_exception_handler`." -msgstr "*context* 參數與 :meth:`call_exception_handler` 中的意思相同。" - -#: ../../library/asyncio-eventloop.rst:1477 -msgid "Call the current event loop exception handler." -msgstr "呼叫目前事件迴圈例外處理程式。" - -#: ../../library/asyncio-eventloop.rst:1479 -msgid "" -"*context* is a ``dict`` object containing the following keys (new keys may " -"be introduced in future Python versions):" -msgstr "" -"*context* 是一個包含以下鍵的 ``dict`` 物件（未來的 Python 版本中可能會引入新" -"的鍵）:" - -#: ../../library/asyncio-eventloop.rst:1482 -msgid "'message': Error message;" -msgstr "'message'：錯誤訊息；" - -#: ../../library/asyncio-eventloop.rst:1483 -msgid "'exception' (optional): Exception object;" -msgstr "'exception'（可選）：例外物件；" - -#: ../../library/asyncio-eventloop.rst:1484 -msgid "'future' (optional): :class:`asyncio.Future` instance;" -msgstr "'future'（可選）： :class:`asyncio.Future` 實例；" - -#: ../../library/asyncio-eventloop.rst:1485 -msgid "'task' (optional): :class:`asyncio.Task` instance;" -msgstr "'task'（可選）： :class:`asyncio.Task` 實例；" - -#: ../../library/asyncio-eventloop.rst:1486 -msgid "'handle' (optional): :class:`asyncio.Handle` instance;" -msgstr "'handle'（可選）： :class:`asyncio.Handle` 實例；" - -#: ../../library/asyncio-eventloop.rst:1487 -msgid "'protocol' (optional): :ref:`Protocol ` instance;" -msgstr "'protocol'（可選）： :ref:`Protocol ` 實例；" - -#: ../../library/asyncio-eventloop.rst:1488 -msgid "'transport' (optional): :ref:`Transport ` instance;" -msgstr "'transport'（可選）： :ref:`Transport ` 實例；" - -#: ../../library/asyncio-eventloop.rst:1489 -msgid "'socket' (optional): :class:`socket.socket` instance;" -msgstr "'socket'（可選）： :class:`socket.socket` 實例；" - -#: ../../library/asyncio-eventloop.rst:1490 -msgid "'source_traceback' (optional): Traceback of the source;" -msgstr "" - -#: ../../library/asyncio-eventloop.rst:1491 -msgid "'handle_traceback' (optional): Traceback of the handle;" -msgstr "" - -#: ../../library/asyncio-eventloop.rst:1492 -msgid "'asyncgen' (optional): Asynchronous generator that caused" -msgstr "'asyncgen'(可選)： 非同步產生器引發" - -#: ../../library/asyncio-eventloop.rst:1493 -msgid "the exception." -msgstr "例外。" - -#: ../../library/asyncio-eventloop.rst:1497 -msgid "" -"This method should not be overloaded in subclassed event loops. For custom " -"exception handling, use the :meth:`set_exception_handler` method." -msgstr "" -"此方法不應在子類別事件迴圈中被覆寫。為了自訂例外處理，請使用 :meth:" -"`set_exception_handler` 方法。" - -#: ../../library/asyncio-eventloop.rst:1502 -msgid "Enabling debug mode" -msgstr "啟用除錯模式" - -#: ../../library/asyncio-eventloop.rst:1506 -msgid "Get the debug mode (:class:`bool`) of the event loop." -msgstr "取得事件迴圈的除錯模式（\\ :class:`bool`\\ ）。" - -#: ../../library/asyncio-eventloop.rst:1508 -msgid "" -"The default value is ``True`` if the environment variable :envvar:" -"`PYTHONASYNCIODEBUG` is set to a non-empty string, ``False`` otherwise." -msgstr "" -"如果環境變數 :envvar:`PYTHONASYNCIODEBUG` 被設定為非空字串，則預設值為 " -"``True``，否則為 ``False``。" - -#: ../../library/asyncio-eventloop.rst:1514 -msgid "Set the debug mode of the event loop." -msgstr "設定事件迴圈的除錯模式。" - -#: ../../library/asyncio-eventloop.rst:1518 -msgid "" -"The new :ref:`Python Development Mode ` can now also be used to " -"enable the debug mode." -msgstr "現在也可以使用新的 :ref:`Python 開發模式 ` 啟用除錯模式。" - -#: ../../library/asyncio-eventloop.rst:1523 -msgid "" -"This attribute can be used to set the minimum execution duration in seconds " -"that is considered \"slow\". When debug mode is enabled, \"slow\" callbacks " -"are logged." -msgstr "" -"此屬性可用於設定被視為\"慢\"的最短執行時間（以秒為單位）。啟用偵錯模式" -"後，\"慢\"回呼將被記錄。" - -#: ../../library/asyncio-eventloop.rst:1527 -msgid "Default value is 100 milliseconds." -msgstr "預設值為 100 毫秒" - -#: ../../library/asyncio-eventloop.rst:1531 -msgid "The :ref:`debug mode of asyncio `." -msgstr ":ref:`asyncio 的除錯模式 `。" - -#: ../../library/asyncio-eventloop.rst:1535 -msgid "Running Subprocesses" -msgstr "運行子行程" - -#: ../../library/asyncio-eventloop.rst:1537 -msgid "" -"Methods described in this subsections are low-level. In regular async/await " -"code consider using the high-level :func:`asyncio.create_subprocess_shell` " -"and :func:`asyncio.create_subprocess_exec` convenience functions instead." -msgstr "" -"本小節描述的方法是低階的。在常規的 async/await 程式碼中，請考慮使用高階 :" -"func:`asyncio.create_subprocess_shell` 和 :func:`asyncio." -"create_subprocess_exec` 輔助功能而不是。" - -#: ../../library/asyncio-eventloop.rst:1544 -msgid "" -"On Windows, the default event loop :class:`ProactorEventLoop` supports " -"subprocesses, whereas :class:`SelectorEventLoop` does not. See :ref:" -"`Subprocess Support on Windows ` for details." -msgstr "" -"在 Windows 上，預設事件迴圈 :class:`ProactorEventLoop` 支援子行程，而 :class:" -"`SelectorEventLoop` 不支援。詳細資訊請參見 :ref:`Windows 上對於子行程的支援 " -"`。" - -#: ../../library/asyncio-eventloop.rst:1556 -msgid "" -"Create a subprocess from one or more string arguments specified by *args*." -msgstr "從 *args* 指定的一個或多個字串引數建立子行程。" - -#: ../../library/asyncio-eventloop.rst:1559 -msgid "*args* must be a list of strings represented by:" -msgstr "*args* 必須是由以下項表示的字串串列：" - -#: ../../library/asyncio-eventloop.rst:1561 -msgid ":class:`str`;" -msgstr ":class:`str`；" - -#: ../../library/asyncio-eventloop.rst:1562 -msgid "" -"or :class:`bytes`, encoded to the :ref:`filesystem encoding `." -msgstr "或 :class:`bytes`，編碼為 :ref:`檔案系統編碼 `。" - -#: ../../library/asyncio-eventloop.rst:1565 -msgid "" -"The first string specifies the program executable, and the remaining strings " -"specify the arguments. Together, string arguments form the ``argv`` of the " -"program." -msgstr "" -"第一個字串指定程序可執行檔案，其餘字串指定引數。字串引數一起組成程序的 " -"``argv``。" - -#: ../../library/asyncio-eventloop.rst:1569 -msgid "" -"This is similar to the standard library :class:`subprocess.Popen` class " -"called with ``shell=False`` and the list of strings passed as the first " -"argument; however, where :class:`~subprocess.Popen` takes a single argument " -"which is list of strings, *subprocess_exec* takes multiple string arguments." -msgstr "" -"這與標準函式庫 :class:`subprocess.Popen` 類似，使用 ``shell=False`` 呼叫並將" -"字串串列作為第一個引數傳遞；然而，:class:`~subprocess.Popen` 接受單個字串串列" -"引數，*subprocess_exec* 接受多個字串引數。" - -#: ../../library/asyncio-eventloop.rst:1575 -msgid "" -"The *protocol_factory* must be a callable returning a subclass of the :class:" -"`asyncio.SubprocessProtocol` class." -msgstr "" -"*protocol_factory* 必須是回傳 :class:`asyncio.SubprocessProtocol` 子類別的可" -"呼叫物件。" - -#: ../../library/asyncio-eventloop.rst:1578 -msgid "Other parameters:" -msgstr "其他參數：" - -#: ../../library/asyncio-eventloop.rst:1580 -msgid "*stdin* can be any of these:" -msgstr "*stdin* 可以是以下任意一個：" - -#: ../../library/asyncio-eventloop.rst:1582 -#: ../../library/asyncio-eventloop.rst:1593 -#: ../../library/asyncio-eventloop.rst:1603 -msgid "a file-like object" -msgstr "類檔案物件" - -#: ../../library/asyncio-eventloop.rst:1583 -msgid "" -"an existing file descriptor (a positive integer), for example those created " -"with :meth:`os.pipe`" -msgstr "現有的檔案描述器（正整數），例如用 :meth:`os.pipe` 建立的" - -#: ../../library/asyncio-eventloop.rst:1584 -#: ../../library/asyncio-eventloop.rst:1594 -#: ../../library/asyncio-eventloop.rst:1604 -msgid "" -"the :const:`subprocess.PIPE` constant (default) which will create a new pipe " -"and connect it," -msgstr ":const:`subprocess.PIPE` 常數（預設），它將建立一個新的管道並連線，" - -#: ../../library/asyncio-eventloop.rst:1586 -#: ../../library/asyncio-eventloop.rst:1596 -#: ../../library/asyncio-eventloop.rst:1606 -msgid "" -"the value ``None`` which will make the subprocess inherit the file " -"descriptor from this process" -msgstr "值 ``None`` 將使子行程從此行程繼承檔案描述器" - -#: ../../library/asyncio-eventloop.rst:1588 -#: ../../library/asyncio-eventloop.rst:1598 -#: ../../library/asyncio-eventloop.rst:1608 -msgid "" -"the :const:`subprocess.DEVNULL` constant which indicates that the special :" -"data:`os.devnull` file will be used" -msgstr "" -":const:`subprocess.DEVNULL` 常數，表示將使用特殊的 :data:`os.devnull` 檔案" - -#: ../../library/asyncio-eventloop.rst:1591 -msgid "*stdout* can be any of these:" -msgstr "*stdout* 可以是以下任意一個：" - -#: ../../library/asyncio-eventloop.rst:1601 -msgid "*stderr* can be any of these:" -msgstr "*stderr* 可以是以下任意一個：" - -#: ../../library/asyncio-eventloop.rst:1610 -msgid "" -"the :const:`subprocess.STDOUT` constant which will connect the standard " -"error stream to the process' standard output stream" -msgstr "" -":const:`subprocess.STDOUT` 常數，它將標準錯誤串流連線到行程的標準輸出串流" - -#: ../../library/asyncio-eventloop.rst:1613 -msgid "" -"All other keyword arguments are passed to :class:`subprocess.Popen` without " -"interpretation, except for *bufsize*, *universal_newlines*, *shell*, *text*, " -"*encoding* and *errors*, which should not be specified at all." -msgstr "" -"所有其他關鍵字引數都會傳遞給 :class:`subprocess.Popen` 而不進行直譯，但 " -"*bufsize*、*universal_newlines*、*shell*、*text*、*encoding* 和 *errors* 除" -"外，這些不應該指定。" - -#: ../../library/asyncio-eventloop.rst:1618 -msgid "" -"The ``asyncio`` subprocess API does not support decoding the streams as " -"text. :func:`bytes.decode` can be used to convert the bytes returned from " -"the stream to text." -msgstr "" -"``asyncio`` 子行程 API 不支援將串流解碼為文本。可以使用 :func:`bytes.decode` " -"將從串流回傳的位元組轉換為文本。" - -#: ../../library/asyncio-eventloop.rst:1622 -msgid "" -"If a file-like object passed as *stdin*, *stdout* or *stderr* represents a " -"pipe, then the other side of this pipe should be registered with :meth:" -"`~loop.connect_write_pipe` or :meth:`~loop.connect_read_pipe` for use with " -"the event loop." -msgstr "" -"如果傳遞給 *stdin*、*stdout* 或 *stderr* 的類檔案物件表示管道，則該管道的另一" -"端應該使用 :meth:`~loop.connect_write_pipe` 或 :meth:`~loop." -"connect_read_pipe` 註冊到事件迴圈中。" - -#: ../../library/asyncio-eventloop.rst:1627 -msgid "" -"See the constructor of the :class:`subprocess.Popen` class for documentation " -"on other arguments." -msgstr "有關其他引數的文件，請參閱 :class:`subprocess.Popen` 類別的建構函式。" - -#: ../../library/asyncio-eventloop.rst:1630 -msgid "" -"Returns a pair of ``(transport, protocol)``, where *transport* conforms to " -"the :class:`asyncio.SubprocessTransport` base class and *protocol* is an " -"object instantiated by the *protocol_factory*." -msgstr "" -"回傳 ``(transport, protocol)`` 對，其中 *transport* 符合 :class:`asyncio." -"SubprocessTransport` 基底類別，*protocol* 是由 *protocol_factory* 實例化的物" -"件。" - -#: ../../library/asyncio-eventloop.rst:1634 -#: ../../library/asyncio-eventloop.rst:1660 -msgid "" -"If the transport is closed or is garbage collected, the child process is " -"killed if it is still running." -msgstr "" - -#: ../../library/asyncio-eventloop.rst:1642 -msgid "" -"Create a subprocess from *cmd*, which can be a :class:`str` or a :class:" -"`bytes` string encoded to the :ref:`filesystem encoding `, using the platform's \"shell\" syntax." -msgstr "" -"使用平台的 \"shell\" 語法從 *cmd* 建立子行程，*cmd* 可以是 :class:`str` 或編" -"碼為 :ref:`檔案系統編碼 ` 的 :class:`bytes` 字串。" - -#: ../../library/asyncio-eventloop.rst:1647 -msgid "" -"This is similar to the standard library :class:`subprocess.Popen` class " -"called with ``shell=True``." -msgstr "" -"這類似於標準函式庫中的 :class:`subprocess.Popen` 類別，使用 ``shell=True`` 呼" -"叫。" - -#: ../../library/asyncio-eventloop.rst:1650 -msgid "" -"The *protocol_factory* must be a callable returning a subclass of the :class:" -"`SubprocessProtocol` class." -msgstr "" -"*protocol_factory* 必須是回傳 :class:`SubprocessProtocol` 子類別的可呼叫物" -"件。" - -#: ../../library/asyncio-eventloop.rst:1653 -msgid "" -"See :meth:`~loop.subprocess_exec` for more details about the remaining " -"arguments." -msgstr "有關其餘引數的更多詳細資訊，請參閱 :meth:`~loop.subprocess_exec`。" - -#: ../../library/asyncio-eventloop.rst:1656 -msgid "" -"Returns a pair of ``(transport, protocol)``, where *transport* conforms to " -"the :class:`SubprocessTransport` base class and *protocol* is an object " -"instantiated by the *protocol_factory*." -msgstr "" -"回傳一對 ``(transport, protocol)``，其中 *transport* 符合 :class:" -"`SubprocessTransport` 基底類別，而 *protocol* 是由 *protocol_factory* 實例化" -"的物件。" - -#: ../../library/asyncio-eventloop.rst:1664 -msgid "" -"It is the application's responsibility to ensure that all whitespace and " -"special characters are quoted appropriately to avoid `shell injection " -"`_ " -"vulnerabilities. The :func:`shlex.quote` function can be used to properly " -"escape whitespace and special characters in strings that are going to be " -"used to construct shell commands." -msgstr "" -"由應用程式負責確保適當引用所有空白和特殊字元，以避免 `shell 注入 `_\\ 風險。可以使用 :func:" -"`shlex.quote` 函式來正確跳脫用於構建 shell 命令的字串中的空白和特殊字元。" - -#: ../../library/asyncio-eventloop.rst:1673 -msgid "Callback Handles" -msgstr "回呼處理" - -#: ../../library/asyncio-eventloop.rst:1677 -msgid "" -"A callback wrapper object returned by :meth:`loop.call_soon`, :meth:`loop." -"call_soon_threadsafe`." -msgstr "" -"由 :meth:`loop.call_soon` 和 :meth:`loop.call_soon_threadsafe` 回傳的回呼包裝" -"器。" - -#: ../../library/asyncio-eventloop.rst:1682 -msgid "" -"Return the :class:`contextvars.Context` object associated with the handle." -msgstr "回傳與處理相關聯的 :class:`contextvars.Context` 物件。" - -#: ../../library/asyncio-eventloop.rst:1689 -msgid "" -"Cancel the callback. If the callback has already been canceled or executed, " -"this method has no effect." -msgstr "取消回呼。如果回呼已被取消或執行，此方法將不起作用。" - -#: ../../library/asyncio-eventloop.rst:1694 -msgid "Return ``True`` if the callback was cancelled." -msgstr "如果回呼已被取消，回傳 ``True``。" - -#: ../../library/asyncio-eventloop.rst:1700 -msgid "" -"A callback wrapper object returned by :meth:`loop.call_later`, and :meth:" -"`loop.call_at`." -msgstr "由 :meth:`loop.call_later` 和 :meth:`loop.call_at` 回傳的回呼包裝器。" - -#: ../../library/asyncio-eventloop.rst:1703 -msgid "This class is a subclass of :class:`Handle`." -msgstr "這個類別是 :class:`Handle` 的子類別。" - -#: ../../library/asyncio-eventloop.rst:1707 -msgid "Return a scheduled callback time as :class:`float` seconds." -msgstr "回傳預定的回呼時間，以 :class:`float` 秒為單位。" - -#: ../../library/asyncio-eventloop.rst:1709 -msgid "" -"The time is an absolute timestamp, using the same time reference as :meth:" -"`loop.time`." -msgstr "時間是一個絕對的時間戳，使用與 :meth:`loop.time` 相同的時間參照。" - -#: ../../library/asyncio-eventloop.rst:1716 -msgid "Server Objects" -msgstr "Server 物件" - -#: ../../library/asyncio-eventloop.rst:1718 -msgid "" -"Server objects are created by :meth:`loop.create_server`, :meth:`loop." -"create_unix_server`, :func:`start_server`, and :func:`start_unix_server` " -"functions." -msgstr "" -"Server 物件是由 :meth:`loop.create_server`、:meth:`loop." -"create_unix_server`、:func:`start_server` 和 :func:`start_unix_server` 函式所" -"建立。" - -#: ../../library/asyncio-eventloop.rst:1722 -msgid "Do not instantiate the :class:`Server` class directly." -msgstr "請勿直接實例化 :class:`Server` 類別。" - -#: ../../library/asyncio-eventloop.rst:1726 -msgid "" -"*Server* objects are asynchronous context managers. When used in an ``async " -"with`` statement, it's guaranteed that the Server object is closed and not " -"accepting new connections when the ``async with`` statement is completed::" -msgstr "" -"*Server* 物件是非同步情境管理器。當在 ``async with`` 陳述中使用時，可以保證在" -"完成 ``async with`` 陳述時，Server 物件將會關閉並停止接受新的連線： ::" - -#: ../../library/asyncio-eventloop.rst:1731 -msgid "" -"srv = await loop.create_server(...)\n" -"\n" -"async with srv:\n" -" # some code\n" -"\n" -"# At this point, srv is closed and no longer accepts new connections." -msgstr "" -"srv = await loop.create_server(...)\n" -"\n" -"async with srv:\n" -" # 一些程式碼\n" -"\n" -"# 此時 srv 已關閉，不再接受新的連線。" - -#: ../../library/asyncio-eventloop.rst:1739 -msgid "Server object is an asynchronous context manager since Python 3.7." -msgstr "自 Python 3.7 起，Server 物件是非同步情境管理器。" - -#: ../../library/asyncio-eventloop.rst:1742 -msgid "" -"This class was exposed publicly as ``asyncio.Server`` in Python 3.9.11, " -"3.10.3 and 3.11." -msgstr "" -"此類別在 Python 3.9.11、3.10.3 和 3.11 中以 ``asyncio.Server`` 的形式被公開。" - -#: ../../library/asyncio-eventloop.rst:1747 -msgid "" -"Stop serving: close listening sockets and set the :attr:`sockets` attribute " -"to ``None``." -msgstr "停止服務：關閉監聽的 sockets 並將 :attr:`sockets` 屬性設為 ``None``。" - -#: ../../library/asyncio-eventloop.rst:1750 -msgid "" -"The sockets that represent existing incoming client connections are left " -"open." -msgstr "代表現有傳入用戶端連線的 sockets 仍然保持開啟。" - -#: ../../library/asyncio-eventloop.rst:1753 -msgid "" -"The server is closed asynchronously; use the :meth:`wait_closed` coroutine " -"to wait until the server is closed (and no more connections are active)." -msgstr "" -"伺服器以非同步方式關閉；使用 :meth:`wait_closed` 協程等待伺服器關閉（不再有活" -"躍連線）。" - -#: ../../library/asyncio-eventloop.rst:1759 -msgid "Close all existing incoming client connections." -msgstr "關閉所有現有的傳入用戶端連線。" - -#: ../../library/asyncio-eventloop.rst:1761 -msgid "" -"Calls :meth:`~asyncio.BaseTransport.close` on all associated transports." -msgstr "在所有關聯的傳輸上呼叫 :meth:`~asyncio.BaseTransport.close`。" - -#: ../../library/asyncio-eventloop.rst:1764 -msgid "" -":meth:`close` should be called before :meth:`close_clients` when closing the " -"server to avoid races with new clients connecting." -msgstr "" - -#: ../../library/asyncio-eventloop.rst:1771 -msgid "" -"Close all existing incoming client connections immediately, without waiting " -"for pending operations to complete." -msgstr "立即關閉所有現有的傳入用戶端連線，而不等待待定操作完成。" - -#: ../../library/asyncio-eventloop.rst:1774 -msgid "" -"Calls :meth:`~asyncio.WriteTransport.abort` on all associated transports." -msgstr "在所有關聯的傳輸上呼叫 :meth:`~asyncio.WriteTransport.abort`。" - -#: ../../library/asyncio-eventloop.rst:1777 -msgid "" -":meth:`close` should be called before :meth:`abort_clients` when closing the " -"server to avoid races with new clients connecting." -msgstr "" - -#: ../../library/asyncio-eventloop.rst:1784 -msgid "Return the event loop associated with the server object." -msgstr "回傳與伺服器物件關聯的事件迴圈。" - -#: ../../library/asyncio-eventloop.rst:1791 -msgid "Start accepting connections." -msgstr "開始接受連線。" - -#: ../../library/asyncio-eventloop.rst:1793 -msgid "" -"This method is idempotent, so it can be called when the server is already " -"serving." -msgstr "此方法是幂等的，因此可以在伺服器已經運行時呼叫。" - -#: ../../library/asyncio-eventloop.rst:1796 -msgid "" -"The *start_serving* keyword-only parameter to :meth:`loop.create_server` " -"and :meth:`asyncio.start_server` allows creating a Server object that is not " -"accepting connections initially. In this case ``Server.start_serving()``, " -"or :meth:`Server.serve_forever` can be used to make the Server start " -"accepting connections." -msgstr "" -"*start_serving* 僅限關鍵字參數只能在 :meth:`loop.create_server` 和 :meth:" -"`asyncio.start_server` 中使用，允許建立一個最初不接受連線的 Server 物件。在這" -"種情況下，可以使用 ``Server.start_serving()`` 或 :meth:`Server." -"serve_forever` 來使 Server 開始接受連線。" - -#: ../../library/asyncio-eventloop.rst:1808 -msgid "" -"Start accepting connections until the coroutine is cancelled. Cancellation " -"of ``serve_forever`` task causes the server to be closed." -msgstr "" -"開始接受連線，直到協程被取消。取消 ``serve_forever`` 任務會導致伺服器關閉。" - -#: ../../library/asyncio-eventloop.rst:1812 -msgid "" -"This method can be called if the server is already accepting connections. " -"Only one ``serve_forever`` task can exist per one *Server* object." -msgstr "" -"如果伺服器已經接受連線，則可以呼叫此方法。每個 *Server* 物件只能存在一個 " -"``serve_forever`` 任務。" - -#: ../../library/asyncio-eventloop.rst:1818 -msgid "" -"async def client_connected(reader, writer):\n" -" # Communicate with the client with\n" -" # reader/writer streams. For example:\n" -" await reader.readline()\n" -"\n" -"async def main(host, port):\n" -" srv = await asyncio.start_server(\n" -" client_connected, host, port)\n" -" await srv.serve_forever()\n" -"\n" -"asyncio.run(main('127.0.0.1', 0))" -msgstr "" -"async def client_connected(reader, writer):\n" -" # 透過讀取器/寫入器串流\n" -" # 與用戶端溝通。例如：\n" -" await reader.readline()\n" -"\n" -"async def main(host, port):\n" -" srv = await asyncio.start_server(\n" -" client_connected, host, port)\n" -" await srv.serve_forever()\n" -"\n" -"asyncio.run(main('127.0.0.1', 0))" - -#: ../../library/asyncio-eventloop.rst:1834 -msgid "Return ``True`` if the server is accepting new connections." -msgstr "如果伺服器正在接受新連線，則回傳 ``True``。" - -#: ../../library/asyncio-eventloop.rst:1841 -msgid "" -"Wait until the :meth:`close` method completes and all active connections " -"have finished." -msgstr "等待 :meth:`close` 方法完成且所有活動連線都已結束。" - -#: ../../library/asyncio-eventloop.rst:1846 -msgid "" -"List of socket-like objects, ``asyncio.trsock.TransportSocket``, which the " -"server is listening on." -msgstr "" -"伺服器正在監聽的類似 socket 的物件串列，``asyncio.trsock.TransportSocket``。" - -#: ../../library/asyncio-eventloop.rst:1849 -msgid "" -"Prior to Python 3.7 ``Server.sockets`` used to return an internal list of " -"server sockets directly. In 3.7 a copy of that list is returned." -msgstr "" -"在 Python 3.7 之前，``Server.sockets`` 曾經直接回傳內部伺服器 sockets 的串" -"列。在 3.7 中回傳了該串列的副本。" - -#: ../../library/asyncio-eventloop.rst:1859 -msgid "Event Loop Implementations" -msgstr "事件迴圈實作" - -#: ../../library/asyncio-eventloop.rst:1861 -msgid "" -"asyncio ships with two different event loop implementations: :class:" -"`SelectorEventLoop` and :class:`ProactorEventLoop`." -msgstr "" -"asyncio 內附兩個不同的事件迴圈實作：:class:`SelectorEventLoop` 和 :class:" -"`ProactorEventLoop`。" - -#: ../../library/asyncio-eventloop.rst:1864 -msgid "By default asyncio is configured to use :class:`EventLoop`." -msgstr "預設情況下，asyncio 被配置為要使用 :class:`EventLoop`。" - -#: ../../library/asyncio-eventloop.rst:1869 -msgid "" -"A subclass of :class:`AbstractEventLoop` based on the :mod:`selectors` " -"module." -msgstr "基於 :mod:`selectors` 模組的一個 :class:`AbstractEventLoop` 子類別。" - -#: ../../library/asyncio-eventloop.rst:1872 -msgid "" -"Uses the most efficient *selector* available for the given platform. It is " -"also possible to manually configure the exact selector implementation to be " -"used::" -msgstr "" -"使用特定平台上最有效的 *selector*。也可以手動配置要使用的確切 selector 實" -"作： ::" - -#: ../../library/asyncio-eventloop.rst:1876 -msgid "" -"import asyncio\n" -"import selectors\n" -"\n" -"async def main():\n" -" ...\n" -"\n" -"loop_factory = lambda: asyncio.SelectorEventLoop(selectors." -"SelectSelector())\n" -"asyncio.run(main(), loop_factory=loop_factory)" -msgstr "" - -#: ../../library/asyncio-eventloop.rst:1891 -msgid "" -"A subclass of :class:`AbstractEventLoop` for Windows that uses \"I/O " -"Completion Ports\" (IOCP)." -msgstr "" -"用於 Windows 的 :class:`AbstractEventLoop` 子類別，使用「I/O 完成埠 (IOCP, I/" -"O Completion Ports)」。" - -#: ../../library/asyncio-eventloop.rst:1897 -msgid "" -"`MSDN documentation on I/O Completion Ports `_." -msgstr "" -"`I/O 完成埠的 MSDN 文件 `_。" - -#: ../../library/asyncio-eventloop.rst:1902 -msgid "" -"An alias to the most efficient available subclass of :class:" -"`AbstractEventLoop` for the given platform." -msgstr "" - -#: ../../library/asyncio-eventloop.rst:1905 -msgid "" -"It is an alias to :class:`SelectorEventLoop` on Unix and :class:" -"`ProactorEventLoop` on Windows." -msgstr "" -"在 Unix 上是 :class:`SelectorEventLoop` 的別名，在 Windows 上是 :class:" -"`ProactorEventLoop` 的別名。" - -#: ../../library/asyncio-eventloop.rst:1911 -msgid "Abstract base class for asyncio-compliant event loops." -msgstr "為符合 asyncio 標準的事件迴圈的抽象基礎類別。" - -#: ../../library/asyncio-eventloop.rst:1913 -msgid "" -"The :ref:`asyncio-event-loop-methods` section lists all methods that an " -"alternative implementation of ``AbstractEventLoop`` should have defined." -msgstr "" -":ref:`asyncio-event-loop-methods` 部分列出了替代 ``AbstractEventLoop`` 實作應" -"該定義的所有方法。" - -#: ../../library/asyncio-eventloop.rst:1919 -msgid "Examples" -msgstr "範例" - -#: ../../library/asyncio-eventloop.rst:1921 -msgid "" -"Note that all examples in this section **purposefully** show how to use the " -"low-level event loop APIs, such as :meth:`loop.run_forever` and :meth:`loop." -"call_soon`. Modern asyncio applications rarely need to be written this way; " -"consider using the high-level functions like :func:`asyncio.run`." -msgstr "" -"請注意，本節中的所有範例都 **故意** 展示如何使用低階事件迴圈 API，如 :meth:" -"`loop.run_forever` 和 :meth:`loop.call_soon`。現代 asyncio 應用程式很少需要這" -"種方式撰寫；請考慮使用高階的函式，如 :func:`asyncio.run`。" - -#: ../../library/asyncio-eventloop.rst:1931 -msgid "Hello World with call_soon()" -msgstr "使用 call_soon() 的 Hello World 範例" - -#: ../../library/asyncio-eventloop.rst:1933 -msgid "" -"An example using the :meth:`loop.call_soon` method to schedule a callback. " -"The callback displays ``\"Hello World\"`` and then stops the event loop::" -msgstr "" -"使用 :meth:`loop.call_soon` 方法排程回呼的範例。回呼會顯示 ``\"Hello " -"World\"``，然後停止事件迴圈： ::" - -#: ../../library/asyncio-eventloop.rst:1937 -msgid "" -"import asyncio\n" -"\n" -"def hello_world(loop):\n" -" \"\"\"A callback to print 'Hello World' and stop the event loop\"\"\"\n" -" print('Hello World')\n" -" loop.stop()\n" -"\n" -"loop = asyncio.new_event_loop()\n" -"\n" -"# Schedule a call to hello_world()\n" -"loop.call_soon(hello_world, loop)\n" -"\n" -"# Blocking call interrupted by loop.stop()\n" -"try:\n" -" loop.run_forever()\n" -"finally:\n" -" loop.close()" -msgstr "" -"import asyncio\n" -"\n" -"def hello_world(loop):\n" -" \"\"\"列印 'Hello World' 並停止事件迴圈的回呼\"\"\"\n" -" print('Hello World')\n" -" loop.stop()\n" -"\n" -"loop = asyncio.new_event_loop()\n" -"\n" -"# 排程對 hello_world() 的呼叫\n" -"loop.call_soon(hello_world, loop)\n" -"\n" -"# 阻塞呼叫被 loop.stop() 中斷\n" -"try:\n" -" loop.run_forever()\n" -"finally:\n" -" loop.close()" - -#: ../../library/asyncio-eventloop.rst:1957 -msgid "" -"A similar :ref:`Hello World ` example created with a coroutine " -"and the :func:`run` function." -msgstr "" -"使用協程和 :func:`run` 函式建立的類似 :ref:`Hello World ` 範例。" - -#: ../../library/asyncio-eventloop.rst:1964 -msgid "Display the current date with call_later()" -msgstr "使用 call_later() 顯示目前日期" - -#: ../../library/asyncio-eventloop.rst:1966 -msgid "" -"An example of a callback displaying the current date every second. The " -"callback uses the :meth:`loop.call_later` method to reschedule itself after " -"5 seconds, and then stops the event loop::" -msgstr "" -"一個回呼的範例，每秒顯示目前日期。回呼使用 :meth:`loop.call_later` 方法在 5 " -"秒後重新排程自己，然後停止事件迴圈： ::" - -#: ../../library/asyncio-eventloop.rst:1970 -msgid "" -"import asyncio\n" -"import datetime\n" -"\n" -"def display_date(end_time, loop):\n" -" print(datetime.datetime.now())\n" -" if (loop.time() + 1.0) < end_time:\n" -" loop.call_later(1, display_date, end_time, loop)\n" -" else:\n" -" loop.stop()\n" -"\n" -"loop = asyncio.new_event_loop()\n" -"\n" -"# Schedule the first call to display_date()\n" -"end_time = loop.time() + 5.0\n" -"loop.call_soon(display_date, end_time, loop)\n" -"\n" -"# Blocking call interrupted by loop.stop()\n" -"try:\n" -" loop.run_forever()\n" -"finally:\n" -" loop.close()" -msgstr "" -"import asyncio\n" -"import datetime\n" -"\n" -"def display_date(end_time, loop):\n" -" print(datetime.datetime.now())\n" -" if (loop.time() + 1.0) < end_time:\n" -" loop.call_later(1, display_date, end_time, loop)\n" -" else:\n" -" loop.stop()\n" -"\n" -"loop = asyncio.new_event_loop()\n" -"\n" -"# 排程 display_date() 的第一次呼叫\n" -"end_time = loop.time() + 5.0\n" -"loop.call_soon(display_date, end_time, loop)\n" -"\n" -"# 阻塞呼叫被 loop.stop() 中斷\n" -"try:\n" -" loop.run_forever()\n" -"finally:\n" -" loop.close()" - -#: ../../library/asyncio-eventloop.rst:1994 -msgid "" -"A similar :ref:`current date ` example created with a " -"coroutine and the :func:`run` function." -msgstr "" -"使用協程和 :func:`run` 函式建立的類似 :ref:`current date " -"` 範例。" - -#: ../../library/asyncio-eventloop.rst:2001 -msgid "Watch a file descriptor for read events" -msgstr "監聽檔案描述器以進行讀取事件" - -#: ../../library/asyncio-eventloop.rst:2003 -msgid "" -"Wait until a file descriptor received some data using the :meth:`loop." -"add_reader` method and then close the event loop::" -msgstr "" -"使用 :meth:`loop.add_reader` 方法等待檔案描述器接收到某些資料，然後關閉事件迴" -"圈： ::" - -#: ../../library/asyncio-eventloop.rst:2006 -msgid "" -"import asyncio\n" -"from socket import socketpair\n" -"\n" -"# Create a pair of connected file descriptors\n" -"rsock, wsock = socketpair()\n" -"\n" -"loop = asyncio.new_event_loop()\n" -"\n" -"def reader():\n" -" data = rsock.recv(100)\n" -" print(\"Received:\", data.decode())\n" -"\n" -" # We are done: unregister the file descriptor\n" -" loop.remove_reader(rsock)\n" -"\n" -" # Stop the event loop\n" -" loop.stop()\n" -"\n" -"# Register the file descriptor for read event\n" -"loop.add_reader(rsock, reader)\n" -"\n" -"# Simulate the reception of data from the network\n" -"loop.call_soon(wsock.send, 'abc'.encode())\n" -"\n" -"try:\n" -" # Run the event loop\n" -" loop.run_forever()\n" -"finally:\n" -" # We are done. Close sockets and the event loop.\n" -" rsock.close()\n" -" wsock.close()\n" -" loop.close()" -msgstr "" -"import asyncio\n" -"from socket import socketpair\n" -"\n" -"# 建立一對連接的檔案描述器\n" -"rsock, wsock = socketpair()\n" -"\n" -"loop = asyncio.new_event_loop()\n" -"\n" -"def reader():\n" -" data = rsock.recv(100)\n" -" print(\"Received:\", data.decode())\n" -"\n" -" # 我們完成了：註銷檔案描述器\n" -" loop.remove_reader(rsock)\n" -"\n" -" # 停止事件迴圈\n" -" loop.stop()\n" -"\n" -"# 為讀取事件註冊檔案描述器\n" -"loop.add_reader(rsock, reader)\n" -"\n" -"# 模擬從網路接收資料\n" -"loop.call_soon(wsock.send, 'abc'.encode())\n" -"\n" -"try:\n" -" # 運行事件迴圈\n" -" loop.run_forever()\n" -"finally:\n" -" # 我們完成了。關閉 socket 和事件迴圈。\n" -" rsock.close()\n" -" wsock.close()\n" -" loop.close()" - -#: ../../library/asyncio-eventloop.rst:2041 -msgid "" -"A similar :ref:`example ` using " -"transports, protocols, and the :meth:`loop.create_connection` method." -msgstr "" -"使用傳輸、協定和 :meth:`loop.create_connection` 方法的類似 :ref:`範例 " -"`。" - -#: ../../library/asyncio-eventloop.rst:2045 -msgid "" -"Another similar :ref:`example ` " -"using the high-level :func:`asyncio.open_connection` function and streams." -msgstr "" -"另一個使用高階 :func:`asyncio.open_connection` 函式和串流的類似 :ref:`範例 " -"`。" - -#: ../../library/asyncio-eventloop.rst:2053 -msgid "Set signal handlers for SIGINT and SIGTERM" -msgstr "設定 SIGINT 和 SIGTERM 的訊號處理程式" - -#: ../../library/asyncio-eventloop.rst:2055 -msgid "(This ``signals`` example only works on Unix.)" -msgstr "（此 ``signals`` 範例僅在 Unix 上運作。）" - -#: ../../library/asyncio-eventloop.rst:2057 -msgid "" -"Register handlers for signals :const:`~signal.SIGINT` and :const:`~signal." -"SIGTERM` using the :meth:`loop.add_signal_handler` method::" -msgstr "" -"使用 :meth:`loop.add_signal_handler` 方法註冊訊號 :const:`~signal.SIGINT` 和 :const:`~signal." -"SIGTERM` 的處理程式： ::" - -#: ../../library/asyncio-eventloop.rst:2060 -msgid "" -"import asyncio\n" -"import functools\n" -"import os\n" -"import signal\n" -"\n" -"def ask_exit(signame, loop):\n" -" print(\"got signal %s: exit\" % signame)\n" -" loop.stop()\n" -"\n" -"async def main():\n" -" loop = asyncio.get_running_loop()\n" -"\n" -" for signame in {'SIGINT', 'SIGTERM'}:\n" -" loop.add_signal_handler(\n" -" getattr(signal, signame),\n" -" functools.partial(ask_exit, signame, loop))\n" -"\n" -" await asyncio.sleep(3600)\n" -"\n" -"print(\"Event loop running for 1 hour, press Ctrl+C to interrupt.\")\n" -"print(f\"pid {os.getpid()}: send SIGINT or SIGTERM to exit.\")\n" -"\n" -"asyncio.run(main())" -msgstr "" -"import asyncio\n" -"import functools\n" -"import os\n" -"import signal\n" -"\n" -"def ask_exit(signame, loop):\n" -" print(\"got signal %s: exit\" % signame)\n" -" loop.stop()\n" -"\n" -"async def main():\n" -" loop = asyncio.get_running_loop()\n" -"\n" -" for signame in {'SIGINT', 'SIGTERM'}:\n" -" loop.add_signal_handler(\n" -" getattr(signal, signame),\n" -" functools.partial(ask_exit, signame, loop))\n" -"\n" -" await asyncio.sleep(3600)\n" -"\n" -"print(\"Event loop running for 1 hour, press Ctrl+C to interrupt.\")\n" -"print(f\"pid {os.getpid()}: send SIGINT or SIGTERM to exit.\")\n" -"\n" -"asyncio.run(main())" - -#~ msgid "" -#~ "Deprecation warning is emitted if there is no current event loop. In some " -#~ "future Python release this will become an error." -#~ msgstr "" -#~ "如果沒有目前事件迴圈，則會發出棄用警告。在未來的某個 Python 發行版中，這將" -#~ "變成錯誤。" - -#~ msgid "" -#~ "import asyncio\n" -#~ "import selectors\n" -#~ "\n" -#~ "class MyPolicy(asyncio.DefaultEventLoopPolicy):\n" -#~ " def new_event_loop(self):\n" -#~ " selector = selectors.SelectSelector()\n" -#~ " return asyncio.SelectorEventLoop(selector)\n" -#~ "\n" -#~ "asyncio.set_event_loop_policy(MyPolicy())" -#~ msgstr "" -#~ "import asyncio\n" -#~ "import selectors\n" -#~ "\n" -#~ "class MyPolicy(asyncio.DefaultEventLoopPolicy):\n" -#~ " def new_event_loop(self):\n" -#~ " selector = selectors.SelectSelector()\n" -#~ " return asyncio.SelectorEventLoop(selector)\n" -#~ "\n" -#~ "asyncio.set_event_loop_policy(MyPolicy())" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-07 00:14+0000\n" +"PO-Revision-Date: 2022-02-20 12:36+0800\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" +"X-Generator: Poedit 3.4.2\n" + +#: ../../library/asyncio-eventloop.rst:8 +msgid "Event Loop" +msgstr "事件迴圈" + +#: ../../library/asyncio-eventloop.rst:10 +msgid "" +"**Source code:** :source:`Lib/asyncio/events.py`, :source:`Lib/asyncio/" +"base_events.py`" +msgstr "" +"**原始碼：** :source:`Lib/asyncio/events.py`、:source:`Lib/asyncio/" +"base_events.py`" + +#: ../../library/asyncio-eventloop.rst:16 +msgid "Preface" +msgstr "前言" + +#: ../../library/asyncio-eventloop.rst:17 +msgid "" +"The event loop is the core of every asyncio application. Event loops run " +"asynchronous tasks and callbacks, perform network IO operations, and run " +"subprocesses." +msgstr "" +"事件迴圈是每個 asyncio 應用程式的核心。事件迴圈執行非同步任務和回呼、執行網" +"路 IO 操作並啟動子行程。" + +#: ../../library/asyncio-eventloop.rst:21 +msgid "" +"Application developers should typically use the high-level asyncio " +"functions, such as :func:`asyncio.run`, and should rarely need to reference " +"the loop object or call its methods. This section is intended mostly for " +"authors of lower-level code, libraries, and frameworks, who need finer " +"control over the event loop behavior." +msgstr "" +"應用程式開發人員通常應使用高階的 asyncio 函式，例如 :func:`asyncio.run`，並且" +"很少需要參照事件迴圈物件或呼叫其方法。本節主要針對那些需要更細粒度控制事件迴" +"圈行為的低階程式碼、函式庫和框架的作者。" + +#: ../../library/asyncio-eventloop.rst:28 +msgid "Obtaining the Event Loop" +msgstr "取得事件迴圈" + +#: ../../library/asyncio-eventloop.rst:29 +msgid "" +"The following low-level functions can be used to get, set, or create an " +"event loop:" +msgstr "以下的低階函式可用於取得、設置或建立事件迴圈：" + +#: ../../library/asyncio-eventloop.rst:34 +msgid "Return the running event loop in the current OS thread." +msgstr "在目前作業系統執行緒中回傳正在運行的事件迴圈。" + +#: ../../library/asyncio-eventloop.rst:36 +msgid "Raise a :exc:`RuntimeError` if there is no running event loop." +msgstr "如果沒有運行的事件迴圈，則引發 :exc:`RuntimeError`。" + +#: ../../library/asyncio-eventloop.rst:38 +msgid "This function can only be called from a coroutine or a callback." +msgstr "此函式只能從協程或回呼函式中呼叫。" + +#: ../../library/asyncio-eventloop.rst:44 +msgid "Get the current event loop." +msgstr "取得目前的事件迴圈。" + +#: ../../library/asyncio-eventloop.rst:46 +msgid "" +"When called from a coroutine or a callback (e.g. scheduled with call_soon or " +"similar API), this function will always return the running event loop." +msgstr "" +"當從協程或回呼函式呼叫此函式（例如，使用 call_soon 或類似的 API 於排程呼" +"叫），此函式將永遠回傳正在運行的事件迴圈。" + +#: ../../library/asyncio-eventloop.rst:50 +msgid "" +"If there is no running event loop set, the function will return the result " +"of the ``get_event_loop_policy().get_event_loop()`` call." +msgstr "" +"如果沒有設定正在運行的事件迴圈，該函式將回傳 ``get_event_loop_policy()." +"get_event_loop()`` 呼叫的結果。" + +#: ../../library/asyncio-eventloop.rst:53 +msgid "" +"Because this function has rather complex behavior (especially when custom " +"event loop policies are in use), using the :func:`get_running_loop` function " +"is preferred to :func:`get_event_loop` in coroutines and callbacks." +msgstr "" +"由於此函式具有相當複雜的行為（尤其是在使用自訂事件迴圈策略時），在協程和回呼" +"函式中，建議使用 :func:`get_running_loop` 函式，而不是 :func:" +"`get_event_loop`。" + +#: ../../library/asyncio-eventloop.rst:58 +msgid "" +"As noted above, consider using the higher-level :func:`asyncio.run` " +"function, instead of using these lower level functions to manually create " +"and close an event loop." +msgstr "" +"如上所述，可以考慮使用高階的 :func:`asyncio.run` 函式，而不是使用這些較低階的" +"函式手動建立和關閉事件迴圈。" + +#: ../../library/asyncio-eventloop.rst:62 +msgid "Raises a :exc:`RuntimeError` if there is no current event loop." +msgstr "如果沒有目前的事件迴圈，則引發 :exc:`RuntimeError`。" + +#: ../../library/asyncio-eventloop.rst:67 +msgid "" +"The :mod:`!asyncio` policy system is deprecated and will be removed in " +"Python 3.16; from there on, this function will return the current running " +"event loop if present else it will return the loop set by :func:" +"`set_event_loop`." +msgstr "" + +#: ../../library/asyncio-eventloop.rst:74 +msgid "Set *loop* as the current event loop for the current OS thread." +msgstr "將 *loop* 設置為目前 OS 執行緒的目前事件迴圈。" + +#: ../../library/asyncio-eventloop.rst:78 +msgid "Create and return a new event loop object." +msgstr "建立並回傳新的事件迴圈物件。" + +#: ../../library/asyncio-eventloop.rst:80 +msgid "" +"Note that the behaviour of :func:`get_event_loop`, :func:`set_event_loop`, " +"and :func:`new_event_loop` functions can be altered by :ref:`setting a " +"custom event loop policy `." +msgstr "" +"請注意 :func:`get_event_loop`、:func:`set_event_loop` 和 :func:" +"`new_event_loop` 函式的行為可以透過\\ :ref:`設定自訂事件迴圈策略 `\\ 進行調整。" + +#: ../../library/asyncio-eventloop.rst:86 +msgid "Contents" +msgstr "目錄" + +#: ../../library/asyncio-eventloop.rst:87 +msgid "This documentation page contains the following sections:" +msgstr "本頁文件包含以下章節：" + +#: ../../library/asyncio-eventloop.rst:89 +msgid "" +"The `Event Loop Methods`_ section is the reference documentation of the " +"event loop APIs;" +msgstr "" +"`事件迴圈方法 `_\\ 章節是事件迴圈 API 們的參照文件；" + +#: ../../library/asyncio-eventloop.rst:92 +msgid "" +"The `Callback Handles`_ section documents the :class:`Handle` and :class:" +"`TimerHandle` instances which are returned from scheduling methods such as :" +"meth:`loop.call_soon` and :meth:`loop.call_later`;" +msgstr "" +"`回呼處理 `_\\ 章節記錄了從排程方法（如 :meth:`loop." +"call_soon` 和 :meth:`loop.call_later`）回傳的 :class:`Handle` 和 :class:" +"`TimerHandle` 實例；" + +#: ../../library/asyncio-eventloop.rst:96 +msgid "" +"The `Server Objects`_ section documents types returned from event loop " +"methods like :meth:`loop.create_server`;" +msgstr "" +"`Server 物件 `_\\ 章節記錄了從事件迴圈方法（如 :meth:`loop." +"create_server`）回傳的資料型別；" + +#: ../../library/asyncio-eventloop.rst:99 +msgid "" +"The `Event Loop Implementations`_ section documents the :class:" +"`SelectorEventLoop` and :class:`ProactorEventLoop` classes;" +msgstr "" +"`事件迴圈實作 `_\\ 章節記錄了 :class:" +"`SelectorEventLoop` 和 :class:`ProactorEventLoop` 類別；" + +#: ../../library/asyncio-eventloop.rst:102 +msgid "" +"The `Examples`_ section showcases how to work with some event loop APIs." +msgstr "`範例 `_\\ 章節展示了如何使用一些事件迴圈 API。" + +#: ../../library/asyncio-eventloop.rst:109 +msgid "Event Loop Methods" +msgstr "事件迴圈方法" + +#: ../../library/asyncio-eventloop.rst:111 +msgid "Event loops have **low-level** APIs for the following:" +msgstr "事件迴圈提供以下\\ **低階** API：" + +#: ../../library/asyncio-eventloop.rst:119 +msgid "Running and stopping the loop" +msgstr "啟動和停止迴圈" + +#: ../../library/asyncio-eventloop.rst:123 +msgid "Run until the *future* (an instance of :class:`Future`) has completed." +msgstr "運行直到 *future* （一個 :class:`Future` 實例）完成。" + +#: ../../library/asyncio-eventloop.rst:126 +msgid "" +"If the argument is a :ref:`coroutine object ` it is implicitly " +"scheduled to run as a :class:`asyncio.Task`." +msgstr "" +"如果引數是\\ :ref:`協程物件 `，則它將被隱式排程為 :class:`asyncio." +"Task` 運行。" + +#: ../../library/asyncio-eventloop.rst:129 +msgid "Return the Future's result or raise its exception." +msgstr "回傳 Future 的結果或引發其例外。" + +#: ../../library/asyncio-eventloop.rst:133 +msgid "Run the event loop until :meth:`stop` is called." +msgstr "運行事件迴圈直到 :meth:`stop` 被呼叫。" + +#: ../../library/asyncio-eventloop.rst:135 +msgid "" +"If :meth:`stop` is called before :meth:`run_forever` is called, the loop " +"will poll the I/O selector once with a timeout of zero, run all callbacks " +"scheduled in response to I/O events (and those that were already scheduled), " +"and then exit." +msgstr "" +"如果在呼叫 :meth:`run_forever` 之前呼叫 :meth:`stop`，則迴圈將使用超時為零的" +"方式輪詢 I/O 選擇器，運行所有回應 I/O 事件（以及已經排程的事件）的回呼，然後" +"退出。" + +#: ../../library/asyncio-eventloop.rst:140 +msgid "" +"If :meth:`stop` is called while :meth:`run_forever` is running, the loop " +"will run the current batch of callbacks and then exit. Note that new " +"callbacks scheduled by callbacks will not run in this case; instead, they " +"will run the next time :meth:`run_forever` or :meth:`run_until_complete` is " +"called." +msgstr "" +"如果在 :meth:`run_forever` 運行時呼叫 :meth:`stop`，則迴圈將運行目前批次的回" +"呼函式，然後退出。請注意，由回呼函式排程的新回呼在此情況下不會運行；而是在下" +"次呼叫 :meth:`run_forever` 或 :meth:`run_until_complete` 時運行。" + +#: ../../library/asyncio-eventloop.rst:148 +msgid "Stop the event loop." +msgstr "停止事件迴圈。" + +#: ../../library/asyncio-eventloop.rst:152 +msgid "Return ``True`` if the event loop is currently running." +msgstr "如果事件迴圈目前正在運行，則回傳 ``True``。" + +#: ../../library/asyncio-eventloop.rst:156 +msgid "Return ``True`` if the event loop was closed." +msgstr "如果事件迴圈已關閉，則回傳 ``True``。" + +#: ../../library/asyncio-eventloop.rst:160 +msgid "Close the event loop." +msgstr "關閉事件迴圈。" + +#: ../../library/asyncio-eventloop.rst:162 +msgid "" +"The loop must not be running when this function is called. Any pending " +"callbacks will be discarded." +msgstr "不得於迴圈運行中呼叫此函式。將丟棄任何待處理的回呼。" + +#: ../../library/asyncio-eventloop.rst:165 +msgid "" +"This method clears all queues and shuts down the executor, but does not wait " +"for the executor to finish." +msgstr "此方法清除所有佇列並關閉執行器，但不等待執行器完成。" + +#: ../../library/asyncio-eventloop.rst:168 +msgid "" +"This method is idempotent and irreversible. No other methods should be " +"called after the event loop is closed." +msgstr "此方法是冪等且不可逆的。在事件迴圈關閉後不應呼叫其他方法。" + +#: ../../library/asyncio-eventloop.rst:174 +msgid "" +"Schedule all currently open :term:`asynchronous generator` objects to close " +"with an :meth:`~agen.aclose` call. After calling this method, the event " +"loop will issue a warning if a new asynchronous generator is iterated. This " +"should be used to reliably finalize all scheduled asynchronous generators." +msgstr "" +"排程所有目前打開的\\ :term:`非同步產生器 `\\ 物件使" +"用 :meth:`~agen.aclose` 呼叫來關閉。呼叫此方法後，如果疊代新的非同步產生器，" +"事件迴圈將發出警告。應該使用此方法可靠地完成所有已排程的非同步產生器。" + +#: ../../library/asyncio-eventloop.rst:180 +msgid "" +"Note that there is no need to call this function when :func:`asyncio.run` is " +"used." +msgstr "請注意，使用 :func:`asyncio.run` 時不需要呼叫此函式。" + +#: ../../library/asyncio-eventloop.rst:183 +#: ../../library/asyncio-eventloop.rst:1354 +#: ../../library/asyncio-eventloop.rst:1816 +msgid "Example::" +msgstr "範例： ::" + +#: ../../library/asyncio-eventloop.rst:185 +msgid "" +"try:\n" +" loop.run_forever()\n" +"finally:\n" +" loop.run_until_complete(loop.shutdown_asyncgens())\n" +" loop.close()" +msgstr "" +"try:\n" +" loop.run_forever()\n" +"finally:\n" +" loop.run_until_complete(loop.shutdown_asyncgens())\n" +" loop.close()" + +#: ../../library/asyncio-eventloop.rst:196 +msgid "" +"Schedule the closure of the default executor and wait for it to join all of " +"the threads in the :class:`~concurrent.futures.ThreadPoolExecutor`. Once " +"this method has been called, using the default executor with :meth:`loop." +"run_in_executor` will raise a :exc:`RuntimeError`." +msgstr "" +"排程預設執行器的關閉，並等待它加入 :class:`~concurrent.futures." +"ThreadPoolExecutor` 中的所有執行緒。一旦呼叫了此方法，使用預設執行器與 :meth:" +"`loop.run_in_executor` 將引發 :exc:`RuntimeError`。" + +#: ../../library/asyncio-eventloop.rst:202 +msgid "" +"The *timeout* parameter specifies the amount of time (in :class:`float` " +"seconds) the executor will be given to finish joining. With the default, " +"``None``, the executor is allowed an unlimited amount of time." +msgstr "" +"*timeout* 參數指定執行器完成加入所需的時間（以 :class:`float` 秒為單位）。預" +"設情況下為 ``None``，不會限制執行器所花費的時間。" + +#: ../../library/asyncio-eventloop.rst:207 +msgid "" +"If the *timeout* is reached, a :exc:`RuntimeWarning` is emitted and the " +"default executor is terminated without waiting for its threads to finish " +"joining." +msgstr "" +"如果達到 *timeout*，將發出 :exc:`RuntimeWarning` 警告，預設執行器將立即終止，" +"不等待其執行緒完成加入。" + +#: ../../library/asyncio-eventloop.rst:213 +msgid "" +"Do not call this method when using :func:`asyncio.run`, as the latter " +"handles default executor shutdown automatically." +msgstr "" +"使用 :func:`asyncio.run` 時請勿呼叫此方法，因為後者會自動處理預設執行器的關" +"閉。" + +#: ../../library/asyncio-eventloop.rst:218 +msgid "Added the *timeout* parameter." +msgstr "加入 *timeout* 參數。" + +#: ../../library/asyncio-eventloop.rst:222 +msgid "Scheduling callbacks" +msgstr "排程回呼函式" + +#: ../../library/asyncio-eventloop.rst:226 +msgid "" +"Schedule the *callback* :term:`callback` to be called with *args* arguments " +"at the next iteration of the event loop." +msgstr "" +"在事件迴圈的下一次疊代中排程以 *args* 引數呼叫 *callback* :term:`callback`。" + +#: ../../library/asyncio-eventloop.rst:229 +msgid "" +"Return an instance of :class:`asyncio.Handle`, which can be used later to " +"cancel the callback." +msgstr "回傳 :class:`asyncio.Handle` 的實例，稍後可以用於取消回呼函式。" + +#: ../../library/asyncio-eventloop.rst:232 +msgid "" +"Callbacks are called in the order in which they are registered. Each " +"callback will be called exactly once." +msgstr "回呼函式按照其註冊的順序呼叫。每個回呼函式將被呼叫恰好一次。" + +#: ../../library/asyncio-eventloop.rst:235 +msgid "" +"The optional keyword-only *context* argument specifies a custom :class:" +"`contextvars.Context` for the *callback* to run in. Callbacks use the " +"current context when no *context* is provided." +msgstr "" +"選用的僅限關鍵字引數 *context* 指定了要給 *callback* 執行的自訂 :class:" +"`contextvars.Context`。當未提供 *context* 時，回呼函式使用目前情境。" + +#: ../../library/asyncio-eventloop.rst:239 +msgid "Unlike :meth:`call_soon_threadsafe`, this method is not thread-safe." +msgstr "與 :meth:`call_soon_threadsafe` 不同，此方法不是執行緒安全的。" + +#: ../../library/asyncio-eventloop.rst:243 +msgid "" +"A thread-safe variant of :meth:`call_soon`. When scheduling callbacks from " +"another thread, this function *must* be used, since :meth:`call_soon` is not " +"thread-safe." +msgstr "" +"這是 :meth:`call_soon` 的執行緒安全變體。當從另一個執行緒排程回呼函式時，*必" +"須*\\ 使用此函式，因為 :meth:`call_soon` 不是執行緒安全的。" + +#: ../../library/asyncio-eventloop.rst:247 +msgid "" +"This function is safe to be called from a reentrant context or signal " +"handler, however, it is not safe or fruitful to use the returned handle in " +"such contexts." +msgstr "" + +#: ../../library/asyncio-eventloop.rst:250 +msgid "" +"Raises :exc:`RuntimeError` if called on a loop that's been closed. This can " +"happen on a secondary thread when the main application is shutting down." +msgstr "" +"如果在已關閉的迴圈上呼叫，則引發 :exc:`RuntimeError`。在主應用程式關閉時，這" +"可能發生在次要執行緒上。" + +#: ../../library/asyncio-eventloop.rst:254 +msgid "" +"See the :ref:`concurrency and multithreading ` " +"section of the documentation." +msgstr "請參閱文件的\\ :ref:`並行和多執行緒 `\\ 部分。" + +#: ../../library/asyncio-eventloop.rst:257 +#: ../../library/asyncio-eventloop.rst:313 +#: ../../library/asyncio-eventloop.rst:339 +msgid "" +"The *context* keyword-only parameter was added. See :pep:`567` for more " +"details." +msgstr "新增了 *context* 僅限關鍵字參數。詳細資訊請參閱 :pep:`567`。" + +#: ../../library/asyncio-eventloop.rst:265 +msgid "" +"Most :mod:`asyncio` scheduling functions don't allow passing keyword " +"arguments. To do that, use :func:`functools.partial`::" +msgstr "" +"大多數 :mod:`asyncio` 排程函式不允許傳遞關鍵字引數。要傳遞關鍵字引數，請使" +"用 :func:`functools.partial`： ::" + +#: ../../library/asyncio-eventloop.rst:268 +msgid "" +"# will schedule \"print(\"Hello\", flush=True)\"\n" +"loop.call_soon(\n" +" functools.partial(print, \"Hello\", flush=True))" +msgstr "" +"# 將會排程 \"print(\"Hello\", flush=True)\"\n" +"loop.call_soon(\n" +" functools.partial(print, \"Hello\", flush=True))" + +#: ../../library/asyncio-eventloop.rst:272 +msgid "" +"Using partial objects is usually more convenient than using lambdas, as " +"asyncio can render partial objects better in debug and error messages." +msgstr "" +"通常使用 partial 物件比使用 lambda 更方便，因為 asyncio 可以在除錯和錯誤訊息" +"中更好地呈現 partial 物件。" + +#: ../../library/asyncio-eventloop.rst:280 +msgid "Scheduling delayed callbacks" +msgstr "排程延遲的回呼函式" + +#: ../../library/asyncio-eventloop.rst:282 +msgid "" +"Event loop provides mechanisms to schedule callback functions to be called " +"at some point in the future. Event loop uses monotonic clocks to track time." +msgstr "" +"事件迴圈提供為回呼函式排程在將來某個時間點才呼叫的機制。事件迴圈使用了單調時" +"鐘來追蹤時間。" + +#: ../../library/asyncio-eventloop.rst:289 +msgid "" +"Schedule *callback* to be called after the given *delay* number of seconds " +"(can be either an int or a float)." +msgstr "排程 *callback* 在給定的 *delay* 秒數後呼叫（可以是整數或浮點數）。" + +#: ../../library/asyncio-eventloop.rst:292 +#: ../../library/asyncio-eventloop.rst:330 +msgid "" +"An instance of :class:`asyncio.TimerHandle` is returned which can be used to " +"cancel the callback." +msgstr "回傳 :class:`asyncio.TimerHandle` 的實例，可用於取消回呼函式。" + +#: ../../library/asyncio-eventloop.rst:295 +msgid "" +"*callback* will be called exactly once. If two callbacks are scheduled for " +"exactly the same time, the order in which they are called is undefined." +msgstr "" +"*callback* 將只被呼叫恰好一次。如果有兩個回呼函式被排程在完全相同的時間，則其" +"呼叫順序是不定的。" + +#: ../../library/asyncio-eventloop.rst:299 +msgid "" +"The optional positional *args* will be passed to the callback when it is " +"called. If you want the callback to be called with keyword arguments use :" +"func:`functools.partial`." +msgstr "" +"可選的位置引數 *args* 將在呼叫回呼函式時傳遞。如果要使用關鍵字引數呼叫回呼函" +"數，請使用 :func:`functools.partial`。" + +#: ../../library/asyncio-eventloop.rst:303 +msgid "" +"An optional keyword-only *context* argument allows specifying a custom :" +"class:`contextvars.Context` for the *callback* to run in. The current " +"context is used when no *context* is provided." +msgstr "" +"可選的僅限關鍵字 *context* 引數允許為 *callback* 指定自訂的 :class:" +"`contextvars.Context` 以提供運行。當未提供 *context* 時，將使用目前情境。" + +#: ../../library/asyncio-eventloop.rst:309 +msgid "" +"For performance, callbacks scheduled with :meth:`loop.call_later` may run up " +"to one clock-resolution early (see ``time.get_clock_info('monotonic')." +"resolution``)." +msgstr "" + +#: ../../library/asyncio-eventloop.rst:317 +msgid "" +"In Python 3.7 and earlier with the default event loop implementation, the " +"*delay* could not exceed one day. This has been fixed in Python 3.8." +msgstr "" +"在 Python 3.7 及更早版本中，使用預設事件迴圈實作時，*delay* 不能超過一天。這" +"在 Python 3.8 中已經修復。" + +#: ../../library/asyncio-eventloop.rst:324 +msgid "" +"Schedule *callback* to be called at the given absolute timestamp *when* (an " +"int or a float), using the same time reference as :meth:`loop.time`." +msgstr "" +"排程 *callback* 在給定的絕對時間戳 *when* （整數或浮點數）處呼叫，使用與 :" +"meth:`loop.time` 相同的時間參照。" + +#: ../../library/asyncio-eventloop.rst:328 +msgid "This method's behavior is the same as :meth:`call_later`." +msgstr "此方法的行為與 :meth:`call_later` 相同。" + +#: ../../library/asyncio-eventloop.rst:335 +msgid "" +"For performance, callbacks scheduled with :meth:`loop.call_at` may run up to " +"one clock-resolution early (see ``time.get_clock_info('monotonic')." +"resolution``)." +msgstr "" + +#: ../../library/asyncio-eventloop.rst:343 +msgid "" +"In Python 3.7 and earlier with the default event loop implementation, the " +"difference between *when* and the current time could not exceed one day. " +"This has been fixed in Python 3.8." +msgstr "" +"在 Python 3.7 及更早版本中，使用預設事件迴圈實作時，*when* 和目前時間之間的差" +"值不能超過一天。這在 Python 3.8 中已經修復。" + +#: ../../library/asyncio-eventloop.rst:350 +msgid "" +"Return the current time, as a :class:`float` value, according to the event " +"loop's internal monotonic clock." +msgstr "根據事件迴圈的內部單調時鐘，回傳目前時間，以 :class:`float` 值表示。" + +#: ../../library/asyncio-eventloop.rst:354 +msgid "" +"In Python 3.7 and earlier timeouts (relative *delay* or absolute *when*) " +"should not exceed one day. This has been fixed in Python 3.8." +msgstr "" +"在 Python 3.7 及更早版本中，超時（相對 *delay* 或絕對 *when*）不應超過一天。" +"這在 Python 3.8 中已經修復。" + +#: ../../library/asyncio-eventloop.rst:360 +msgid "The :func:`asyncio.sleep` function." +msgstr "函式 :func:`asyncio.sleep`。" + +#: ../../library/asyncio-eventloop.rst:364 +msgid "Creating Futures and Tasks" +msgstr "建立 Futures 和 Tasks" + +#: ../../library/asyncio-eventloop.rst:368 +msgid "Create an :class:`asyncio.Future` object attached to the event loop." +msgstr "建立附加到事件迴圈的 :class:`asyncio.Future` 物件。" + +#: ../../library/asyncio-eventloop.rst:370 +msgid "" +"This is the preferred way to create Futures in asyncio. This lets third-" +"party event loops provide alternative implementations of the Future object " +"(with better performance or instrumentation)." +msgstr "" +"這是在 asyncio 中建立 Futures 的首選方式。這允許第三方事件迴圈提供 Future 物" +"件的替代實作（具有更好的性能或儀器計測表現）。" + +#: ../../library/asyncio-eventloop.rst:378 +msgid "" +"Schedule the execution of :ref:`coroutine ` *coro*. Return a :" +"class:`Task` object." +msgstr "排程執行\\ :ref:`協程 ` *coro*。回傳 :class:`Task` 物件。" + +#: ../../library/asyncio-eventloop.rst:381 +msgid "" +"Third-party event loops can use their own subclass of :class:`Task` for " +"interoperability. In this case, the result type is a subclass of :class:" +"`Task`." +msgstr "" +"第三方事件迴圈可以使用其自己的 :class:`Task` 子類別以實現互操作性" +"（interoperability）。在這種情況下，結果類型是 :class:`Task` 的子類別。" + +#: ../../library/asyncio-eventloop.rst:385 +msgid "" +"The full function signature is largely the same as that of the :class:`Task` " +"constructor (or factory) - all of the keyword arguments to this function are " +"passed through to that interface." +msgstr "" + +#: ../../library/asyncio-eventloop.rst:389 +msgid "" +"If the *name* argument is provided and not ``None``, it is set as the name " +"of the task using :meth:`Task.set_name`." +msgstr "" +"如果提供了 *name* 引數且不為 ``None``，則將其設置為任務的名稱，使用 :meth:" +"`Task.set_name`。" + +#: ../../library/asyncio-eventloop.rst:392 +msgid "" +"An optional keyword-only *context* argument allows specifying a custom :" +"class:`contextvars.Context` for the *coro* to run in. The current context " +"copy is created when no *context* is provided." +msgstr "" +"可選的僅限關鍵字 *context* 引數允許為 *coro* 指定自訂的 :class:" +"`contextvars.Context` 以提供運行。當未提供 *context* 時，將建立目前情境的副" +"本。" + +#: ../../library/asyncio-eventloop.rst:396 +msgid "" +"An optional keyword-only *eager_start* argument allows specifying if the " +"task should execute eagerly during the call to create_task, or be scheduled " +"later. If *eager_start* is not passed the mode set by :meth:`loop." +"set_task_factory` will be used." +msgstr "" + +#: ../../library/asyncio-eventloop.rst:401 +msgid "Added the *name* parameter." +msgstr "加入 *name* 參數。" + +#: ../../library/asyncio-eventloop.rst:404 +msgid "Added the *context* parameter." +msgstr "加入 *context* 參數。" + +#: ../../library/asyncio-eventloop.rst:407 +msgid "" +"Added ``kwargs`` which passes on arbitrary extra parameters, including " +"``name`` and ``context``." +msgstr "" + +#: ../../library/asyncio-eventloop.rst:410 +msgid "" +"Rolled back the change that passes on *name* and *context* (if it is None), " +"while still passing on other arbitrary keyword arguments (to avoid breaking " +"backwards compatibility with 3.13.3)." +msgstr "" + +#: ../../library/asyncio-eventloop.rst:414 +msgid "" +"All *kwargs* are now passed on. The *eager_start* parameter works with eager " +"task factories." +msgstr "" + +#: ../../library/asyncio-eventloop.rst:419 +msgid "Set a task factory that will be used by :meth:`loop.create_task`." +msgstr "設置將由 :meth:`loop.create_task` 使用的任務工廠。" + +#: ../../library/asyncio-eventloop.rst:422 +msgid "" +"If *factory* is ``None`` the default task factory will be set. Otherwise, " +"*factory* must be a *callable* with the signature matching ``(loop, coro, " +"**kwargs)``, where *loop* is a reference to the active event loop, and " +"*coro* is a coroutine object. The callable must pass on all *kwargs*, and " +"return a :class:`asyncio.Task`-compatible object." +msgstr "" +"如果 *factory* 為 ``None``，將設置預設的任務工廠。否則，*factory* 必須是一個" +"具有匹配簽名 ``(loop, coro, **kwargs)`` 的 *callable*，其中 *loop* 是有效事件" +"迴圈的參照、*coro* 是一個協程物件。該可呼叫物件必須傳遞所有 *kwargs* 並回傳一" +"個與 :class:`asyncio.Task` 相容的物件。" + +#: ../../library/asyncio-eventloop.rst:428 +msgid "Required that all *kwargs* are passed on to :class:`asyncio.Task`." +msgstr "" + +#: ../../library/asyncio-eventloop.rst:431 +msgid "" +"*name* is no longer passed to task factories. *context* is no longer passed " +"to task factories if it is ``None``." +msgstr "" + +#: ../../library/asyncio-eventloop.rst:435 +msgid "" +"*name* and *context* are now unconditionally passed on to task factories " +"again." +msgstr "" + +#: ../../library/asyncio-eventloop.rst:440 +msgid "Return a task factory or ``None`` if the default one is in use." +msgstr "回傳任務工廠，如果使用預設任務工廠則回傳 ``None``。" + +#: ../../library/asyncio-eventloop.rst:444 +msgid "Opening network connections" +msgstr "打開網路連線" + +#: ../../library/asyncio-eventloop.rst:456 +msgid "" +"Open a streaming transport connection to a given address specified by *host* " +"and *port*." +msgstr "打開以 *host* 和 *port* 指定之給定地址的串流傳輸連線。" + +#: ../../library/asyncio-eventloop.rst:459 +msgid "" +"The socket family can be either :py:const:`~socket.AF_INET` or :py:const:" +"`~socket.AF_INET6` depending on *host* (or the *family* argument, if " +"provided)." +msgstr "" +"根據 *host*\\ （或提供的 *family* 引數）的情況，socket 家族可以是 :py:const:" +"`~socket.AF_INET` 或 :py:const:`~socket.AF_INET6`。" + +#: ../../library/asyncio-eventloop.rst:463 +msgid "The socket type will be :py:const:`~socket.SOCK_STREAM`." +msgstr "Socket 類型將為 :py:const:`~socket.SOCK_STREAM`。" + +#: ../../library/asyncio-eventloop.rst:465 +#: ../../library/asyncio-eventloop.rst:1264 +#: ../../library/asyncio-eventloop.rst:1281 +msgid "" +"*protocol_factory* must be a callable returning an :ref:`asyncio protocol " +"` implementation." +msgstr "" +"*protocol_factory* 必須是一個回傳 :ref:`asyncio protocol ` " +"實作的可呼叫函式。" + +#: ../../library/asyncio-eventloop.rst:468 +msgid "" +"This method will try to establish the connection in the background. When " +"successful, it returns a ``(transport, protocol)`` pair." +msgstr "" +"此方法將嘗試在背景建立連線。成功時，它將回傳一對 ``(transport, protocol)``。" + +#: ../../library/asyncio-eventloop.rst:471 +msgid "The chronological synopsis of the underlying operation is as follows:" +msgstr "底層操作的時間軸簡介如下：" + +#: ../../library/asyncio-eventloop.rst:473 +msgid "" +"The connection is established and a :ref:`transport ` is " +"created for it." +msgstr "建立連線並為其建立\\ :ref:`傳輸 `。" + +#: ../../library/asyncio-eventloop.rst:476 +msgid "" +"*protocol_factory* is called without arguments and is expected to return a :" +"ref:`protocol ` instance." +msgstr "" +"*protocol_factory* 在無引數的情況下被呼叫，並且預計回傳一個 :ref:`協定 " +"` 實例。" + +#: ../../library/asyncio-eventloop.rst:479 +msgid "" +"The protocol instance is coupled with the transport by calling its :meth:" +"`~BaseProtocol.connection_made` method." +msgstr "" +"透過呼叫其 :meth:`~BaseProtocol.connection_made` 方法，將協定實例與傳輸連線在" +"一起。" + +#: ../../library/asyncio-eventloop.rst:482 +msgid "A ``(transport, protocol)`` tuple is returned on success." +msgstr "成功時回傳一個 ``(transport, protocol)`` 元組。" + +#: ../../library/asyncio-eventloop.rst:484 +msgid "" +"The created transport is an implementation-dependent bidirectional stream." +msgstr "建立的傳輸是一個依賴實作的雙向串流。" + +#: ../../library/asyncio-eventloop.rst:487 +#: ../../library/asyncio-eventloop.rst:620 +msgid "Other arguments:" +msgstr "其他引數：" + +#: ../../library/asyncio-eventloop.rst:489 +msgid "" +"*ssl*: if given and not false, a SSL/TLS transport is created (by default a " +"plain TCP transport is created). If *ssl* is a :class:`ssl.SSLContext` " +"object, this context is used to create the transport; if *ssl* is :const:" +"`True`, a default context returned from :func:`ssl.create_default_context` " +"is used." +msgstr "" +"若有給定 *ssl* 且非 false，將建立 SSL/TLS 傳輸（預設建立普通 TCP 傳輸）。如" +"果 *ssl* 為 :class:`ssl.SSLContext` 物件，則使用該情境來建立傳輸；如果 *ssl* " +"為 :const:`True`，則使用 :func:`ssl.create_default_context` 回傳的預設情境。" + +#: ../../library/asyncio-eventloop.rst:495 +msgid ":ref:`SSL/TLS security considerations `" +msgstr ":ref:`SSL/TLS 安全考量 `" + +#: ../../library/asyncio-eventloop.rst:497 +msgid "" +"*server_hostname* sets or overrides the hostname that the target server's " +"certificate will be matched against. Should only be passed if *ssl* is not " +"``None``. By default the value of the *host* argument is used. If *host* " +"is empty, there is no default and you must pass a value for " +"*server_hostname*. If *server_hostname* is an empty string, hostname " +"matching is disabled (which is a serious security risk, allowing for " +"potential man-in-the-middle attacks)." +msgstr "" +"*server_hostname* 設置或覆蓋目標伺服器憑證將匹配的主機名稱。僅在 *ssl* 不為 " +"``None`` 時傳遞。預設情況下，將使用 *host* 引數的值。如果 *host* 為空，則沒有" +"預設值，必須傳遞 *server_hostname* 的值。若 *server_hostname* 為空字串，將停" +"用主機名稱匹配（這是一個嚴重的安全風險，可能導致中間人攻擊）。" + +#: ../../library/asyncio-eventloop.rst:505 +msgid "" +"*family*, *proto*, *flags* are the optional address family, protocol and " +"flags to be passed through to getaddrinfo() for *host* resolution. If given, " +"these should all be integers from the corresponding :mod:`socket` module " +"constants." +msgstr "" +"*family*、*proto*、*flags* 是可選的位址家族、協定和旗標，用於傳遞至 " +"getaddrinfo() 進行 *host* 解析。若有給定這些應該都是相應 :mod:`socket` 模組常" +"數的整數。" + +#: ../../library/asyncio-eventloop.rst:510 +msgid "" +"*happy_eyeballs_delay*, if given, enables Happy Eyeballs for this " +"connection. It should be a floating-point number representing the amount of " +"time in seconds to wait for a connection attempt to complete, before " +"starting the next attempt in parallel. This is the \"Connection Attempt " +"Delay\" as defined in :rfc:`8305`. A sensible default value recommended by " +"the RFC is ``0.25`` (250 milliseconds)." +msgstr "" +"若有給定，*happy_eyeballs_delay* 會啟用此連線的 Happy Eyeballs。它應該是一個" +"浮點數，表示等待連線嘗試完成的秒數，然後在並行啟動下一次嘗試。這是 :rfc:" +"`8305` 中定義的「連線嘗試延遲」。RFC 建議的合理預設值為 ``0.25`` 秒（250 毫" +"秒）。" + +#: ../../library/asyncio-eventloop.rst:518 +msgid "" +"*interleave* controls address reordering when a host name resolves to " +"multiple IP addresses. If ``0`` or unspecified, no reordering is done, and " +"addresses are tried in the order returned by :meth:`getaddrinfo`. If a " +"positive integer is specified, the addresses are interleaved by address " +"family, and the given integer is interpreted as \"First Address Family " +"Count\" as defined in :rfc:`8305`. The default is ``0`` if " +"*happy_eyeballs_delay* is not specified, and ``1`` if it is." +msgstr "" +"*interleave* 控制主機名稱解析為多個 IP 位址時的地址重新排序。若為 ``0`` 或未" +"指定，將不執行重排序，並按 :meth:`getaddrinfo` 回傳的順序嘗試位址。如果指定正" +"整數，則按地址家族交錯排列，給定的整數直譯為 :rfc:`8305` 中定義的「首個地址家" +"族計數」。如果未指定 *happy_eyeballs_delay*，則預設值為 ``0``，如果指定則為 " +"``1``。" + +#: ../../library/asyncio-eventloop.rst:527 +msgid "" +"*sock*, if given, should be an existing, already connected :class:`socket." +"socket` object to be used by the transport. If *sock* is given, none of " +"*host*, *port*, *family*, *proto*, *flags*, *happy_eyeballs_delay*, " +"*interleave* and *local_addr* should be specified." +msgstr "" +"若有給定 *sock* 則其應為已存在且已連線的 :class:`socket.socket` 物件，可供傳" +"輸使用。如果提供了 *sock*，則不應指定 *host*、*port*、*family*、*proto*、" +"*flags*、*happy_eyeballs_delay*、*interleave* 和 *local_addr* 中的任何一項。" + +#: ../../library/asyncio-eventloop.rst:535 +#: ../../library/asyncio-eventloop.rst:657 +#: ../../library/asyncio-eventloop.rst:905 +msgid "" +"The *sock* argument transfers ownership of the socket to the transport " +"created. To close the socket, call the transport's :meth:`~asyncio." +"BaseTransport.close` method." +msgstr "" +"引數 *sock* 將 socket 所有權轉移給所建立的傳輸 socket，請呼叫傳輸的 :meth:" +"`~asyncio.BaseTransport.close` 方法。" + +#: ../../library/asyncio-eventloop.rst:539 +msgid "" +"*local_addr*, if given, is a ``(local_host, local_port)`` tuple used to bind " +"the socket locally. The *local_host* and *local_port* are looked up using " +"``getaddrinfo()``, similarly to *host* and *port*." +msgstr "" +"若有給定 *local_addr* 則其為一個 ``(local_host, local_port)`` 元組，用於在本" +"地綁定 socket。將使用 ``getaddrinfo()`` 查找 *local_host* 和 *local_port*，方" +"式類似於 *host* 和 *port*。" + +#: ../../library/asyncio-eventloop.rst:543 +#: ../../library/asyncio-eventloop.rst:1001 +msgid "" +"*ssl_handshake_timeout* is (for a TLS connection) the time in seconds to " +"wait for the TLS handshake to complete before aborting the connection. " +"``60.0`` seconds if ``None`` (default)." +msgstr "" +"*ssl_handshake_timeout* （對於 TLS 連線）是等待 TLS 交握的時間，以秒為單位，" +"在那之前若未完成則會中斷連線。如果為 ``None`` （預設值），則會等待 ``60.0`` " +"秒。" + +#: ../../library/asyncio-eventloop.rst:547 +#: ../../library/asyncio-eventloop.rst:812 +#: ../../library/asyncio-eventloop.rst:916 +#: ../../library/asyncio-eventloop.rst:1005 +msgid "" +"*ssl_shutdown_timeout* is the time in seconds to wait for the SSL shutdown " +"to complete before aborting the connection. ``30.0`` seconds if ``None`` " +"(default)." +msgstr "" +"*ssl_shutdown_timeout* 是等待 SSL 關閉完成以前中斷連線的時間，以秒為單位。如" +"果為 ``None`` （預設值），則會等待 ``30.0`` 秒。" + +#: ../../library/asyncio-eventloop.rst:551 +msgid "" +"*all_errors* determines what exceptions are raised when a connection cannot " +"be created. By default, only a single ``Exception`` is raised: the first " +"exception if there is only one or all errors have same message, or a single " +"``OSError`` with the error messages combined. When ``all_errors`` is " +"``True``, an ``ExceptionGroup`` will be raised containing all exceptions " +"(even if there is only one)." +msgstr "" +"*all_errors* 決定在無法建立連線時會引發哪些例外。預設情況下，只會引發單一 " +"``Exception``：如果只有一個例外或所有錯誤訊息相同，則引發第一個例外，否則引發" +"包含所有錯誤訊息的單一 ``OSError``。當 ``all_errors`` 為 ``True`` 時，將引發" +"包含所有例外的 ``ExceptionGroup`` （即使只有一個例外）。" + +#: ../../library/asyncio-eventloop.rst:561 +#: ../../library/asyncio-eventloop.rst:824 +msgid "Added support for SSL/TLS in :class:`ProactorEventLoop`." +msgstr "新增 :class:`ProactorEventLoop` 中的 SSL/TLS 支援。" + +#: ../../library/asyncio-eventloop.rst:565 +msgid "" +"The socket option :ref:`socket.TCP_NODELAY ` is set " +"by default for all TCP connections." +msgstr "" +"所有 TCP 連線都預設有 :ref:`socket.TCP_NODELAY ` " +"socket 選項。" + +#: ../../library/asyncio-eventloop.rst:570 +#: ../../library/asyncio-eventloop.rst:926 +msgid "Added the *ssl_handshake_timeout* parameter." +msgstr "增加 *ssl_handshake_timeout* 參數。" + +#: ../../library/asyncio-eventloop.rst:574 +msgid "Added the *happy_eyeballs_delay* and *interleave* parameters." +msgstr "加入 *happy_eyeballs_delay* 和 *interleave* 參數。" + +#: ../../library/asyncio-eventloop.rst:576 +msgid "" +"Happy Eyeballs Algorithm: Success with Dual-Stack Hosts. When a server's " +"IPv4 path and protocol are working, but the server's IPv6 path and protocol " +"are not working, a dual-stack client application experiences significant " +"connection delay compared to an IPv4-only client. This is undesirable " +"because it causes the dual-stack client to have a worse user experience. " +"This document specifies requirements for algorithms that reduce this user-" +"visible delay and provides an algorithm." +msgstr "" +"Happy Eyeballs 演算法：雙協定堆疊主機 (Dual-Stack Hosts) 的成功。當伺服器的 " +"IPv4 路徑和協定運作正常，但伺服器的 IPv6 路徑和協定不運作時，雙棧用戶端應用程" +"式會比僅具 IPv4 的用戶端體驗到顯著的連線延遲。這是不希望的，因為這會導致雙棧" +"用戶端的使用者體驗變差。本文件具體說明了減少此用戶可見延遲的演算法要求並提供" +"了一種演算法。" + +#: ../../library/asyncio-eventloop.rst:585 +msgid "For more information: https://datatracker.ietf.org/doc/html/rfc6555" +msgstr "更多資訊請見： https://datatracker.ietf.org/doc/html/rfc6555" + +#: ../../library/asyncio-eventloop.rst:589 +#: ../../library/asyncio-eventloop.rst:721 +#: ../../library/asyncio-eventloop.rst:838 +#: ../../library/asyncio-eventloop.rst:878 +#: ../../library/asyncio-eventloop.rst:930 +#: ../../library/asyncio-eventloop.rst:1013 +msgid "Added the *ssl_shutdown_timeout* parameter." +msgstr "增加 *ssl_shutdown_timeout* 參數。" + +#: ../../library/asyncio-eventloop.rst:591 +msgid "*all_errors* was added." +msgstr "已新增 *all_errors*。" + +#: ../../library/asyncio-eventloop.rst:596 +msgid "" +"The :func:`open_connection` function is a high-level alternative API. It " +"returns a pair of (:class:`StreamReader`, :class:`StreamWriter`) that can be " +"used directly in async/await code." +msgstr "" +"函式 :func:`open_connection` 是高階的替代 API。它回傳一對 (:class:" +"`StreamReader`, :class:`StreamWriter`) 可直接在 async/await 程式碼中使用。" + +#: ../../library/asyncio-eventloop.rst:607 +msgid "Create a datagram connection." +msgstr "建立一個資料報連線。" + +#: ../../library/asyncio-eventloop.rst:609 +msgid "" +"The socket family can be either :py:const:`~socket.AF_INET`, :py:const:" +"`~socket.AF_INET6`, or :py:const:`~socket.AF_UNIX`, depending on *host* (or " +"the *family* argument, if provided)." +msgstr "" +"Socket 家族可以是 :py:const:`~socket.AF_INET`、:py:const:`~socket.AF_INET6` " +"或 :py:const:`~socket.AF_UNIX`，視乎 *host*\\ （或提供的 *family* 引數）而" +"定。" + +#: ../../library/asyncio-eventloop.rst:613 +msgid "The socket type will be :py:const:`~socket.SOCK_DGRAM`." +msgstr "Socket 類型將為 :py:const:`~socket.SOCK_DGRAM`。" + +#: ../../library/asyncio-eventloop.rst:615 +#: ../../library/asyncio-eventloop.rst:748 +#: ../../library/asyncio-eventloop.rst:897 +msgid "" +"*protocol_factory* must be a callable returning a :ref:`protocol ` implementation." +msgstr "" +"*protocol_factory* 必須是可呼叫的函式，回傳 :ref:`protocol ` 實作。" + +#: ../../library/asyncio-eventloop.rst:618 +#: ../../library/asyncio-eventloop.rst:703 +msgid "A tuple of ``(transport, protocol)`` is returned on success." +msgstr "成功時回傳 ``(transport, protocol)`` 元組。" + +#: ../../library/asyncio-eventloop.rst:622 +msgid "" +"*local_addr*, if given, is a ``(local_host, local_port)`` tuple used to bind " +"the socket locally. The *local_host* and *local_port* are looked up using :" +"meth:`getaddrinfo`." +msgstr "" +"*local_addr*，如果提供，是一個 ``(local_host, local_port)`` 元組，用於在本地" +"綁定 socket。*local_host* 和 *local_port* 使用 :meth:`getaddrinfo` 來查找。" + +#: ../../library/asyncio-eventloop.rst:628 +msgid "" +"On Windows, when using the proactor event loop with ``local_addr=None``, an :" +"exc:`OSError` with :attr:`!errno.WSAEINVAL` will be raised when running it." +msgstr "" + +#: ../../library/asyncio-eventloop.rst:632 +msgid "" +"*remote_addr*, if given, is a ``(remote_host, remote_port)`` tuple used to " +"connect the socket to a remote address. The *remote_host* and *remote_port* " +"are looked up using :meth:`getaddrinfo`." +msgstr "" +"*remote_addr*，如果提供，是一個 ``(remote_host, remote_port)`` 元組，用於將 " +"socket 連線到遠端位址。 *remote_host* 和 *remote_port* 使用 :meth:" +"`getaddrinfo` 來查找。" + +#: ../../library/asyncio-eventloop.rst:636 +msgid "" +"*family*, *proto*, *flags* are the optional address family, protocol and " +"flags to be passed through to :meth:`getaddrinfo` for *host* resolution. If " +"given, these should all be integers from the corresponding :mod:`socket` " +"module constants." +msgstr "" +"*family*、*proto* 和 *flags* 是用於傳遞給 :meth:`getaddrinfo` 以解析 *host* " +"的可選地址家族、協定和旗標。如果提供，這些應該都是來自相應的 :mod:`socket` 模" +"組常數的整數。" + +#: ../../library/asyncio-eventloop.rst:641 +msgid "" +"*reuse_port* tells the kernel to allow this endpoint to be bound to the same " +"port as other existing endpoints are bound to, so long as they all set this " +"flag when being created. This option is not supported on Windows and some " +"Unixes. If the :ref:`socket.SO_REUSEPORT ` constant " +"is not defined then this capability is unsupported." +msgstr "" +"*reuse_port* 告訴核心允許將此端點綁定到與其他現有端點相同的埠，只要它們在建立" +"時都設定了此旗標。此選項不受 Windows 和某些 Unix 系統支援。如果未定義 :py:" +"const:`socket.SO_REUSEPORT ` 常數，則不支援此功能。" + +#: ../../library/asyncio-eventloop.rst:647 +msgid "" +"*allow_broadcast* tells the kernel to allow this endpoint to send messages " +"to the broadcast address." +msgstr "*allow_broadcast* 告訴核心允許此端點向廣播位址發送訊息。" + +#: ../../library/asyncio-eventloop.rst:650 +msgid "" +"*sock* can optionally be specified in order to use a preexisting, already " +"connected, :class:`socket.socket` object to be used by the transport. If " +"specified, *local_addr* and *remote_addr* should be omitted (must be :const:" +"`None`)." +msgstr "" +"*sock* 可以選擇性地指定，以使用預先存在且已連線的 :class:`socket.socket` 物件" +"供傳輸使用。如果指定，*local_addr* 和 *remote_addr* 應省略（必須是 :const:" +"`None`\\ ）。" + +#: ../../library/asyncio-eventloop.rst:661 +msgid "" +"See :ref:`UDP echo client protocol ` and :" +"ref:`UDP echo server protocol ` examples." +msgstr "" +"請參閱 :ref:`UDP 回應用戶端協定 ` 和 :ref:" +"`UDP 回應伺服器協定 ` 範例。" + +#: ../../library/asyncio-eventloop.rst:664 +msgid "" +"The *family*, *proto*, *flags*, *reuse_address*, *reuse_port*, " +"*allow_broadcast*, and *sock* parameters were added." +msgstr "" +"新增 *family*、*proto*、*flags*、*reuse_address*、*reuse_port*、" +"*allow_broadcast* 和 *sock* 參數。" + +#: ../../library/asyncio-eventloop.rst:668 +msgid "Added support for Windows." +msgstr "新增對於 Windows 的支援。" + +#: ../../library/asyncio-eventloop.rst:671 +msgid "" +"The *reuse_address* parameter is no longer supported, as using :ref:`socket." +"SO_REUSEADDR ` poses a significant security concern " +"for UDP. Explicitly passing ``reuse_address=True`` will raise an exception." +msgstr "" +"不再支援 *reuse_address* 參數，因為使用 :py:const:`~socket.SO_REUSEADDR ` 對" +"於 UDP 存有重大的安全疑慮。明確傳遞 ``reuse_address=True`` 將引發例外。" + +#: ../../library/asyncio-eventloop.rst:677 +msgid "" +"When multiple processes with differing UIDs assign sockets to an identical " +"UDP socket address with ``SO_REUSEADDR``, incoming packets can become " +"randomly distributed among the sockets." +msgstr "" +"當具有不同 UID 的多個行程使用 ``SO_REUSEADDR`` 將 socket 分配給相同的 UDP " +"socket 地址時，傳入的封包可能會在 socket 之間隨機分佈。" + +#: ../../library/asyncio-eventloop.rst:681 +msgid "" +"For supported platforms, *reuse_port* can be used as a replacement for " +"similar functionality. With *reuse_port*, :ref:`socket.SO_REUSEPORT ` is used instead, which specifically prevents processes with " +"differing UIDs from assigning sockets to the same socket address." +msgstr "" +"對於有支援的平台，*reuse_port* 可以用作類似功能的替代方案。使用 " +"*reuse_port*，將改為使用 :py:const:`~socket.SO_REUSEPORT `，該選項明確禁止具" +"有不同 UID 的行程將 socket 分配給相同的 socket 地址。" + +#: ../../library/asyncio-eventloop.rst:688 +msgid "" +"The *reuse_address* parameter, disabled since Python 3.8.1, 3.7.6 and " +"3.6.10, has been entirely removed." +msgstr "" +"自 Python 3.9.0、3.8.1、3.7.6 和 3.6.10 起，已完全移除 *reuse_address* 參數。" + +#: ../../library/asyncio-eventloop.rst:698 +msgid "Create a Unix connection." +msgstr "建立一個 Unix 連線。" + +#: ../../library/asyncio-eventloop.rst:700 +msgid "" +"The socket family will be :py:const:`~socket.AF_UNIX`; socket type will be :" +"py:const:`~socket.SOCK_STREAM`." +msgstr "" +"Socket 家族將為 :py:const:`~socket.AF_UNIX`；socket 類型將為 :py:const:" +"`~socket.SOCK_STREAM`。" + +#: ../../library/asyncio-eventloop.rst:705 +msgid "" +"*path* is the name of a Unix domain socket and is required, unless a *sock* " +"parameter is specified. Abstract Unix sockets, :class:`str`, :class:" +"`bytes`, and :class:`~pathlib.Path` paths are supported." +msgstr "" +"*path* 是 Unix 域 socket 的名稱，除非指定 *sock* 參數，否則為必填。支援抽象 " +"Unix sockets、:class:`str`、:class:`bytes` 和 :class:`~pathlib.Path` 路徑。" + +#: ../../library/asyncio-eventloop.rst:710 +msgid "" +"See the documentation of the :meth:`loop.create_connection` method for " +"information about arguments to this method." +msgstr "" +"有關此方法的引數資訊，請參閱 :meth:`loop.create_connection` 方法的文件。" + +#: ../../library/asyncio-eventloop.rst:713 +#: ../../library/asyncio-eventloop.rst:869 +#: ../../library/asyncio-eventloop.rst:1334 +#: ../../library/asyncio-eventloop.rst:1886 +#: ../../library/asyncio-eventloop.rst:1893 +msgid "Availability" +msgstr "可用性" + +#: ../../library/asyncio-eventloop.rst:715 +msgid "" +"Added the *ssl_handshake_timeout* parameter. The *path* parameter can now be " +"a :term:`path-like object`." +msgstr "" +"新增 *ssl_handshake_timeout* 參數。*path* 參數現在可以是 :term:`path-like " +"object`。" + +#: ../../library/asyncio-eventloop.rst:725 +msgid "Creating network servers" +msgstr "建立網路伺服器" + +#: ../../library/asyncio-eventloop.rst:741 +msgid "" +"Create a TCP server (socket type :const:`~socket.SOCK_STREAM`) listening on " +"*port* of the *host* address." +msgstr "" +"建立一個 TCP 伺服器（socket 類型 :const:`~socket.SOCK_STREAM`\\ ），監聽 " +"*host* 位址的 *port*。" + +#: ../../library/asyncio-eventloop.rst:744 +msgid "Returns a :class:`Server` object." +msgstr "回傳一個 :class:`Server` 物件。" + +#: ../../library/asyncio-eventloop.rst:746 +msgid "Arguments:" +msgstr "引數：" + +#: ../../library/asyncio-eventloop.rst:751 +msgid "" +"The *host* parameter can be set to several types which determine where the " +"server would be listening:" +msgstr "可以將 *host* 參數設為幾種類型，以確定伺服器將監聽的位置：" + +#: ../../library/asyncio-eventloop.rst:754 +msgid "" +"If *host* is a string, the TCP server is bound to a single network interface " +"specified by *host*." +msgstr "如果 *host* 是字串，則 TCP 伺服器綁定到由 *host* 指定的單個網路介面。" + +#: ../../library/asyncio-eventloop.rst:757 +msgid "" +"If *host* is a sequence of strings, the TCP server is bound to all network " +"interfaces specified by the sequence." +msgstr "如果 *host* 是字串序列，則 TCP 伺服器綁定到序列指定的所有網路介面。" + +#: ../../library/asyncio-eventloop.rst:760 +msgid "" +"If *host* is an empty string or ``None``, all interfaces are assumed and a " +"list of multiple sockets will be returned (most likely one for IPv4 and " +"another one for IPv6)." +msgstr "" +"若 *host* 是空字串或 ``None``，則所有介面都被假定並回傳多個 socket 的清單（可" +"能一個用於 IPv4，另一個用於 IPv6）。" + +#: ../../library/asyncio-eventloop.rst:764 +msgid "" +"The *port* parameter can be set to specify which port the server should " +"listen on. If ``0`` or ``None`` (the default), a random unused port will be " +"selected (note that if *host* resolves to multiple network interfaces, a " +"different random port will be selected for each interface)." +msgstr "" +"可以設定 *port* 參數以指定伺服器應該監聽的埠。如果是 ``0`` 或 ``None``\\ （預" +"設值），將隨機選擇一個未使用的埠（請注意，如果 *host* 解析為多個網路介面，將" +"為每個介面隨機選擇不同的隨機埠）。" + +#: ../../library/asyncio-eventloop.rst:769 +msgid "" +"*family* can be set to either :const:`socket.AF_INET` or :const:`~socket." +"AF_INET6` to force the socket to use IPv4 or IPv6. If not set, the *family* " +"will be determined from host name (defaults to :const:`~socket.AF_UNSPEC`)." +msgstr "" +"*family* 可以設定為 :const:`socket.AF_INET` 或 :const:`~socket.AF_INET6` 以強" +"制使用 IPv4 或 IPv6。如果未設定，*family* 將從主機名稱決定（預設為 :const:" +"`~socket.AF_UNSPEC`\\ ）。" + +#: ../../library/asyncio-eventloop.rst:774 +msgid "*flags* is a bitmask for :meth:`getaddrinfo`." +msgstr "*flags* 是 :meth:`getaddrinfo` 的位元遮罩。" + +#: ../../library/asyncio-eventloop.rst:776 +msgid "" +"*sock* can optionally be specified in order to use a preexisting socket " +"object. If specified, *host* and *port* must not be specified." +msgstr "" +"可以可選地指定 *sock* 以使用現有的 socket 物件。如果指定了，*host* 和 *port* " +"不能指定。" + +#: ../../library/asyncio-eventloop.rst:781 +msgid "" +"The *sock* argument transfers ownership of the socket to the server created. " +"To close the socket, call the server's :meth:`~asyncio.Server.close` method." +msgstr "" +"*sock* 引數將 socket 的所有權轉移給建立的伺服器。要關閉 socket，請呼叫伺服器" +"的 :meth:`~asyncio.Server.close` 方法。" + +#: ../../library/asyncio-eventloop.rst:785 +msgid "" +"*backlog* is the maximum number of queued connections passed to :meth:" +"`~socket.socket.listen` (defaults to 100)." +msgstr "" +"*backlog* 是傳遞給 :meth:`~socket.socket.listen` 的最大佇列連線數（預設為 " +"100）。" + +#: ../../library/asyncio-eventloop.rst:788 +msgid "" +"*ssl* can be set to an :class:`~ssl.SSLContext` instance to enable TLS over " +"the accepted connections." +msgstr "" +"*ssl* 可以設定為 :class:`~ssl.SSLContext` 實例以在接受的連線上啟用 TLS。" + +#: ../../library/asyncio-eventloop.rst:791 +msgid "" +"*reuse_address* tells the kernel to reuse a local socket in ``TIME_WAIT`` " +"state, without waiting for its natural timeout to expire. If not specified " +"will automatically be set to ``True`` on Unix." +msgstr "" +"*reuse_address* 告訴內核重用 ``TIME_WAIT`` 狀態下的本地 socket，而不等待其自" +"然超時過期。如果未指定，在 Unix 上將自動設置為 ``True``。" + +#: ../../library/asyncio-eventloop.rst:796 +msgid "" +"*reuse_port* tells the kernel to allow this endpoint to be bound to the same " +"port as other existing endpoints are bound to, so long as they all set this " +"flag when being created. This option is not supported on Windows." +msgstr "" +"*reuse_port* 告訴內核允許此端點繫結到與其他現有端點繫結的相同埠，只要它們在建" +"立時都設置了此旗標。此選項在旗標 Windows 上不受支援。" + +#: ../../library/asyncio-eventloop.rst:801 +msgid "" +"*keep_alive* set to ``True`` keeps connections active by enabling the " +"periodic transmission of messages." +msgstr "將 *keep_alive* 設為 ``True`` 透過啟用定期的訊息傳輸來保持連線活躍。" + +#: ../../library/asyncio-eventloop.rst:806 +msgid "Added the *keep_alive* parameter." +msgstr "加入 *keep_alive* 參數。" + +#: ../../library/asyncio-eventloop.rst:808 +msgid "" +"*ssl_handshake_timeout* is (for a TLS server) the time in seconds to wait " +"for the TLS handshake to complete before aborting the connection. ``60.0`` " +"seconds if ``None`` (default)." +msgstr "" +"（對於 TLS 伺服器）\\ *ssl_handshake_timeout* 是在中斷連線之前等待 TLS 握手完" +"成的時間（以秒為單位）。如果為 ``None``\\ （預設），則為 ``60.0`` 秒。" + +#: ../../library/asyncio-eventloop.rst:816 +msgid "" +"*start_serving* set to ``True`` (the default) causes the created server to " +"start accepting connections immediately. When set to ``False``, the user " +"should await on :meth:`Server.start_serving` or :meth:`Server.serve_forever` " +"to make the server to start accepting connections." +msgstr "" +"將 *start_serving* 設置為 ``True``\\ （預設）將使建立的伺服器立即開始接受連" +"接。當設置為 ``False`` 時，用戶應該等待 :meth:`Server.start_serving` 或 :" +"meth:`Server.serve_forever` 來使伺服器開始接受連線。" + +#: ../../library/asyncio-eventloop.rst:828 +msgid "The *host* parameter can be a sequence of strings." +msgstr "*host* 參數可以是字串序列。" + +#: ../../library/asyncio-eventloop.rst:832 +msgid "" +"Added *ssl_handshake_timeout* and *start_serving* parameters. The socket " +"option :ref:`socket.TCP_NODELAY ` is set by default " +"for all TCP connections." +msgstr "" +"新增 *ssl_handshake_timeout* 與 *start_serving* 參數。所有 TCP 連線都預設有 :" +"ref:`socket.TCP_NODELAY ` socket 選項。" + +#: ../../library/asyncio-eventloop.rst:842 +msgid "" +"The :func:`start_server` function is a higher-level alternative API that " +"returns a pair of :class:`StreamReader` and :class:`StreamWriter` that can " +"be used in an async/await code." +msgstr "" +":func:`start_server` 函式是一個更高階的替代 API，它回傳一對 :class:" +"`StreamReader` 和 :class:`StreamWriter`，可以在 async/await 程式碼中使用。" + +#: ../../library/asyncio-eventloop.rst:854 +msgid "" +"Similar to :meth:`loop.create_server` but works with the :py:const:`~socket." +"AF_UNIX` socket family." +msgstr "" +"類似 :meth:`loop.create_server`，但適用於 :py:const:`~socket.AF_UNIX` socket " +"家族。" + +#: ../../library/asyncio-eventloop.rst:857 +msgid "" +"*path* is the name of a Unix domain socket, and is required, unless a *sock* " +"argument is provided. Abstract Unix sockets, :class:`str`, :class:`bytes`, " +"and :class:`~pathlib.Path` paths are supported." +msgstr "" +"*path* 是 Unix 域 socket 的名稱，除非提供了 *sock* 引數，否則必須給定。支援抽" +"象 Unix sockets、:class:`str`、:class:`bytes` 和 :class:`~pathlib.Path` 路" +"徑。" + +#: ../../library/asyncio-eventloop.rst:862 +msgid "" +"If *cleanup_socket* is true then the Unix socket will automatically be " +"removed from the filesystem when the server is closed, unless the socket has " +"been replaced after the server has been created." +msgstr "" +"如果 *cleanup_socket* 為真，則 Unix socket 將在伺服器關閉時自動從檔案系統中刪" +"除，除非在建立伺服器後替換了 socket。" + +#: ../../library/asyncio-eventloop.rst:866 +msgid "" +"See the documentation of the :meth:`loop.create_server` method for " +"information about arguments to this method." +msgstr "有關此方法的引數資訊，請參閱 :meth:`loop.create_server` 方法的文件。" + +#: ../../library/asyncio-eventloop.rst:873 +msgid "" +"Added the *ssl_handshake_timeout* and *start_serving* parameters. The *path* " +"parameter can now be a :class:`~pathlib.Path` object." +msgstr "" +"新增 *ssl_handshake_timeout* 與 *start_serving* 參數。*path* 參數現在可為一" +"個 :class:`~pathlib.Path` 物件。" + +#: ../../library/asyncio-eventloop.rst:882 +msgid "Added the *cleanup_socket* parameter." +msgstr "加入 *cleanup_socket* 參數。" + +#: ../../library/asyncio-eventloop.rst:890 +msgid "Wrap an already accepted connection into a transport/protocol pair." +msgstr "將已接受的連線包裝成傳輸層/協定對。" + +#: ../../library/asyncio-eventloop.rst:892 +msgid "" +"This method can be used by servers that accept connections outside of " +"asyncio but that use asyncio to handle them." +msgstr "此方法可以由在 asyncio 外接受連線但使用 asyncio 處理連線的伺服器使用。" + +#: ../../library/asyncio-eventloop.rst:895 +#: ../../library/asyncio-eventloop.rst:987 +msgid "Parameters:" +msgstr "參數：" + +#: ../../library/asyncio-eventloop.rst:900 +msgid "" +"*sock* is a preexisting socket object returned from :meth:`socket.accept " +"`." +msgstr "" +"*sock* 是從 :meth:`socket.accept ` 回傳的預先存在的 " +"socket 物件。" + +#: ../../library/asyncio-eventloop.rst:909 +msgid "" +"*ssl* can be set to an :class:`~ssl.SSLContext` to enable SSL over the " +"accepted connections." +msgstr "*ssl* 可以設置為 :class:`~ssl.SSLContext` 以在已接受的連線上啟用 SSL。" + +#: ../../library/asyncio-eventloop.rst:912 +msgid "" +"*ssl_handshake_timeout* is (for an SSL connection) the time in seconds to " +"wait for the SSL handshake to complete before aborting the connection. " +"``60.0`` seconds if ``None`` (default)." +msgstr "" +"（對於 SSL 連線）\\ *ssl_handshake_timeout* 是在中斷連線之前等待 SSL 握手完成" +"的時間（以秒為單位）。如果為 ``None``\\ （預設），則為 ``60.0`` 秒。" + +#: ../../library/asyncio-eventloop.rst:920 +msgid "Returns a ``(transport, protocol)`` pair." +msgstr "回傳 ``(transport, protocol)`` 對。" + +#: ../../library/asyncio-eventloop.rst:934 +msgid "Transferring files" +msgstr "傳輸檔案" + +#: ../../library/asyncio-eventloop.rst:940 +msgid "" +"Send a *file* over a *transport*. Return the total number of bytes sent." +msgstr "透過 *transport* 發送 *file*。回傳發送的總位元組數。" + +#: ../../library/asyncio-eventloop.rst:943 +msgid "The method uses high-performance :meth:`os.sendfile` if available." +msgstr "如果可用，該方法使用高性能 :meth:`os.sendfile`。" + +#: ../../library/asyncio-eventloop.rst:945 +msgid "*file* must be a regular file object opened in binary mode." +msgstr "*file* 必須是以二進位模式打開的常規檔案物件。" + +#: ../../library/asyncio-eventloop.rst:947 +#: ../../library/asyncio-eventloop.rst:1208 +msgid "" +"*offset* tells from where to start reading the file. If specified, *count* " +"is the total number of bytes to transmit as opposed to sending the file " +"until EOF is reached. File position is always updated, even when this method " +"raises an error, and :meth:`file.tell() ` can be used to " +"obtain the actual number of bytes sent." +msgstr "" +"*offset* 告訴從哪裡開始讀取檔案。如果指定了，*count* 是要傳輸的總位元組數，而" +"不是發送檔案直到達到 EOF。即使此方法引發錯誤時，檔案位置也始終更新，可以使" +"用 :meth:`file.tell() ` 取得實際發送的位元組數。" + +#: ../../library/asyncio-eventloop.rst:954 +msgid "" +"*fallback* set to ``True`` makes asyncio to manually read and send the file " +"when the platform does not support the sendfile system call (e.g. Windows or " +"SSL socket on Unix)." +msgstr "" +"將 *fallback* 設置為 ``True`` 會使 asyncio 在平台不支援 sendfile 系統呼叫時" +"（例如 Windows 或 Unix 上的 SSL socket）手動讀取和發送檔案。" + +#: ../../library/asyncio-eventloop.rst:958 +msgid "" +"Raise :exc:`SendfileNotAvailableError` if the system does not support the " +"*sendfile* syscall and *fallback* is ``False``." +msgstr "" +"如果系統不支援 *sendfile* 系統呼叫且 *fallback* 為 ``False``，則引發 :exc:" +"`SendfileNotAvailableError`。" + +#: ../../library/asyncio-eventloop.rst:965 +msgid "TLS Upgrade" +msgstr "TLS 升級" + +#: ../../library/asyncio-eventloop.rst:973 +msgid "Upgrade an existing transport-based connection to TLS." +msgstr "將基於傳輸的現有連線升級到 TLS。" + +#: ../../library/asyncio-eventloop.rst:975 +msgid "" +"Create a TLS coder/decoder instance and insert it between the *transport* " +"and the *protocol*. The coder/decoder implements both *transport*-facing " +"protocol and *protocol*-facing transport." +msgstr "" +"建立 TLS 編解碼器實例並在 *transport* 和 *protocol* 之間插入它。編解碼器既實" +"作了對於 *transport* 的協定，也實作了對於 *protocol* 的傳輸。" + +#: ../../library/asyncio-eventloop.rst:979 +msgid "" +"Return the created two-interface instance. After *await*, the *protocol* " +"must stop using the original *transport* and communicate with the returned " +"object only because the coder caches *protocol*-side data and sporadically " +"exchanges extra TLS session packets with *transport*." +msgstr "" +"回傳建立的雙介面實例。在 *await* 後，*protocol* 必須停止使用原始的 " +"*transport*，僅與回傳的物件通信，因為編碼器快取了 *protocol* 端的資料，並且" +"與 *transport* 間歇性地交換額外的 TLS session 封包。" + +#: ../../library/asyncio-eventloop.rst:984 +msgid "" +"In some situations (e.g. when the passed transport is already closing) this " +"may return ``None``." +msgstr "在某些情況下（例如傳入的傳輸已經關閉），此函式可能回傳 ``None``。" + +#: ../../library/asyncio-eventloop.rst:989 +msgid "" +"*transport* and *protocol* instances that methods like :meth:`~loop." +"create_server` and :meth:`~loop.create_connection` return." +msgstr "" +"*transport* 和 *protocol* 實例，由像 :meth:`~loop.create_server` 和 :meth:" +"`~loop.create_connection` 等方法回傳。" + +#: ../../library/asyncio-eventloop.rst:993 +msgid "*sslcontext*: a configured instance of :class:`~ssl.SSLContext`." +msgstr "*sslcontext*：配置好的 :class:`~ssl.SSLContext` 實例。" + +#: ../../library/asyncio-eventloop.rst:995 +msgid "" +"*server_side* pass ``True`` when a server-side connection is being upgraded " +"(like the one created by :meth:`~loop.create_server`)." +msgstr "" +"當升級伺服器端連線時（像由 :meth:`~loop.create_server` 建立的那樣）傳遞 " +"``True``。" + +#: ../../library/asyncio-eventloop.rst:998 +msgid "" +"*server_hostname*: sets or overrides the host name that the target server's " +"certificate will be matched against." +msgstr "*server_hostname*：設置或覆蓋將用於匹配目標伺服器憑證的主機名。" + +#: ../../library/asyncio-eventloop.rst:1018 +msgid "Watching file descriptors" +msgstr "監視檔案描述器" + +#: ../../library/asyncio-eventloop.rst:1022 +msgid "" +"Start monitoring the *fd* file descriptor for read availability and invoke " +"*callback* with the specified arguments once *fd* is available for reading." +msgstr "" +"開始監視 *fd* 檔案描述器的讀取可用性，一但 *fd* 可讀取，使用指定引數叫用 " +"*callback*。" + +#: ../../library/asyncio-eventloop.rst:1026 +#: ../../library/asyncio-eventloop.rst:1040 +msgid "" +"Any preexisting callback registered for *fd* is cancelled and replaced by " +"*callback*." +msgstr "任何預先存在、為 *fd* 註冊的回呼函式將被取消並替換為 *callback*。" + +#: ../../library/asyncio-eventloop.rst:1031 +msgid "" +"Stop monitoring the *fd* file descriptor for read availability. Returns " +"``True`` if *fd* was previously being monitored for reads." +msgstr "" +"停止監視 *fd* 檔案描述器的讀取可用性。如果 *fd* 之前正在監視讀取，則回傳 " +"``True``。" + +#: ../../library/asyncio-eventloop.rst:1036 +msgid "" +"Start monitoring the *fd* file descriptor for write availability and invoke " +"*callback* with the specified arguments once *fd* is available for writing." +msgstr "" +"開始監視 *fd* 檔案描述器的寫入可用性，一旦 *fd* 可寫入，使用指定引數叫用 " +"*callback*。" + +#: ../../library/asyncio-eventloop.rst:1043 +#: ../../library/asyncio-eventloop.rst:1321 +msgid "" +"Use :func:`functools.partial` :ref:`to pass keyword arguments ` to *callback*." +msgstr "" +"使用 :func:`functools.partial` 向 *callback* :ref:`傳送關鍵字引數 `。" + +#: ../../library/asyncio-eventloop.rst:1048 +msgid "" +"Stop monitoring the *fd* file descriptor for write availability. Returns " +"``True`` if *fd* was previously being monitored for writes." +msgstr "" +"停止監視 *fd* 檔案描述器的寫入可用性。如果 *fd* 之前正在監視寫入，則回傳 " +"``True``。" + +#: ../../library/asyncio-eventloop.rst:1051 +msgid "" +"See also :ref:`Platform Support ` section for some " +"limitations of these methods." +msgstr "" +"另請參閱\\ :ref:`平台支援 `\\ 部分以了解這些方法的" +"一些限制。" + +#: ../../library/asyncio-eventloop.rst:1056 +msgid "Working with socket objects directly" +msgstr "直接使用 socket 物件" + +#: ../../library/asyncio-eventloop.rst:1058 +msgid "" +"In general, protocol implementations that use transport-based APIs such as :" +"meth:`loop.create_connection` and :meth:`loop.create_server` are faster than " +"implementations that work with sockets directly. However, there are some use " +"cases when performance is not critical, and working with :class:`~socket." +"socket` objects directly is more convenient." +msgstr "" +"一般情況下，使用基於傳輸的 API（如 :meth:`loop.create_connection` 和 :meth:" +"`loop.create_server`）的協定實作比直接使用 socket 的實作更快。然而在某些情況" +"下性能不是關鍵，直接使用 :class:`~socket.socket` 物件更方便。" + +#: ../../library/asyncio-eventloop.rst:1068 +msgid "" +"Receive up to *nbytes* from *sock*. Asynchronous version of :meth:`socket." +"recv() `." +msgstr "" +"從 *sock* 接收最多 *nbytes*。:meth:`socket.recv() ` 的非" +"同步版本。" + +#: ../../library/asyncio-eventloop.rst:1071 +msgid "Return the received data as a bytes object." +msgstr "將接收到的資料作為 bytes 物件回傳。" + +#: ../../library/asyncio-eventloop.rst:1073 +#: ../../library/asyncio-eventloop.rst:1088 +#: ../../library/asyncio-eventloop.rst:1100 +#: ../../library/asyncio-eventloop.rst:1113 +#: ../../library/asyncio-eventloop.rst:1129 +#: ../../library/asyncio-eventloop.rst:1145 +#: ../../library/asyncio-eventloop.rst:1156 +#: ../../library/asyncio-eventloop.rst:1183 +#: ../../library/asyncio-eventloop.rst:1222 +msgid "*sock* must be a non-blocking socket." +msgstr "*sock* 必須是非阻塞 socket。" + +#: ../../library/asyncio-eventloop.rst:1075 +msgid "" +"Even though this method was always documented as a coroutine method, " +"releases before Python 3.7 returned a :class:`Future`. Since Python 3.7 this " +"is an ``async def`` method." +msgstr "" +"儘管此方法一直記錄為協程方法，但 Python 3.7 之前的版本回傳 :class:`Future`。" +"自 Python 3.7 起，這是 ``async def`` 方法。" + +#: ../../library/asyncio-eventloop.rst:1083 +msgid "" +"Receive data from *sock* into the *buf* buffer. Modeled after the blocking :" +"meth:`socket.recv_into() ` method." +msgstr "" +"從 *sock* 接收資料到 *buf* 緩衝區。仿照阻塞 :meth:`socket.recv_into() " +"` 方法。" + +#: ../../library/asyncio-eventloop.rst:1086 +msgid "Return the number of bytes written to the buffer." +msgstr "回傳寫入緩衝區位元組的數目。" + +#: ../../library/asyncio-eventloop.rst:1095 +msgid "" +"Receive a datagram of up to *bufsize* from *sock*. Asynchronous version of :" +"meth:`socket.recvfrom() `." +msgstr "" +"從 *sock* 接收最多 *bufsize* 大小的資料單元。:meth:`socket.recvfrom() " +"` 的非同步版本。" + +#: ../../library/asyncio-eventloop.rst:1098 +msgid "Return a tuple of (received data, remote address)." +msgstr "回傳一個元組 (received data, remote address)。" + +#: ../../library/asyncio-eventloop.rst:1107 +msgid "" +"Receive a datagram of up to *nbytes* from *sock* into *buf*. Asynchronous " +"version of :meth:`socket.recvfrom_into() `." +msgstr "" +"從 *sock* 接收最多 *nbytes* 大小的資料單元到 *buf*。:meth:`socket." +"recvfrom_into() ` 的非同步版本。" + +#: ../../library/asyncio-eventloop.rst:1111 +msgid "Return a tuple of (number of bytes received, remote address)." +msgstr "回傳一個元組 (number of bytes received, remote address)。" + +#: ../../library/asyncio-eventloop.rst:1120 +msgid "" +"Send *data* to the *sock* socket. Asynchronous version of :meth:`socket." +"sendall() `." +msgstr "" +"將 *data* 發送到 *sock* socket。:meth:`socket.sendall() ` 的非同步版本。" + +#: ../../library/asyncio-eventloop.rst:1123 +msgid "" +"This method continues to send to the socket until either all data in *data* " +"has been sent or an error occurs. ``None`` is returned on success. On " +"error, an exception is raised. Additionally, there is no way to determine " +"how much data, if any, was successfully processed by the receiving end of " +"the connection." +msgstr "" +"此方法將繼續發送到 socket，直到 *data* 中的所有資料都已發送或發生錯誤。成功時" +"回傳 ``None``。錯誤時引發例外。此外，沒有辦法確定接收端成功處理了多少資料（如" +"果有的話）。" + +#: ../../library/asyncio-eventloop.rst:1131 +#: ../../library/asyncio-eventloop.rst:1185 +msgid "" +"Even though the method was always documented as a coroutine method, before " +"Python 3.7 it returned a :class:`Future`. Since Python 3.7, this is an " +"``async def`` method." +msgstr "" +"儘管該方法一直被記錄為協程方法，但在 Python 3.7 之前它回傳 :class:`Future`。" +"從 Python 3.7 開始，這是一個 ``async def`` 方法。" + +#: ../../library/asyncio-eventloop.rst:1139 +msgid "" +"Send a datagram from *sock* to *address*. Asynchronous version of :meth:" +"`socket.sendto() `." +msgstr "" +"從 *sock* 向 *address* 發送一個資料單元。:meth:`socket.sendto() ` 的非同步版本。" + +#: ../../library/asyncio-eventloop.rst:1143 +msgid "Return the number of bytes sent." +msgstr "回傳發送的位元組數。" + +#: ../../library/asyncio-eventloop.rst:1152 +msgid "Connect *sock* to a remote socket at *address*." +msgstr "將 *sock* 連線到位於 *address* 的遠端 socket。" + +#: ../../library/asyncio-eventloop.rst:1154 +msgid "" +"Asynchronous version of :meth:`socket.connect() `." +msgstr ":meth:`socket.connect() ` 的非同步版本。" + +#: ../../library/asyncio-eventloop.rst:1158 +msgid "" +"``address`` no longer needs to be resolved. ``sock_connect`` will try to " +"check if the *address* is already resolved by calling :func:`socket." +"inet_pton`. If not, :meth:`loop.getaddrinfo` will be used to resolve the " +"*address*." +msgstr "" +"不再需要解析 ``address``。``sock_connect`` 將嘗試透過呼叫 :func:`socket." +"inet_pton` 檢查 *address* 是否已解析。如果沒有，將使用 :meth:`loop." +"getaddrinfo` 解析 *address*。" + +#: ../../library/asyncio-eventloop.rst:1167 +msgid "" +":meth:`loop.create_connection` and :func:`asyncio.open_connection() " +"`." +msgstr "" +":meth:`loop.create_connection` 和 :func:`asyncio.open_connection() " +"`。" + +#: ../../library/asyncio-eventloop.rst:1174 +msgid "" +"Accept a connection. Modeled after the blocking :meth:`socket.accept() " +"` method." +msgstr "" +"接受一個連線。模擬阻塞的 :meth:`socket.accept() ` 方" +"法。" + +#: ../../library/asyncio-eventloop.rst:1177 +msgid "" +"The socket must be bound to an address and listening for connections. The " +"return value is a pair ``(conn, address)`` where *conn* is a *new* socket " +"object usable to send and receive data on the connection, and *address* is " +"the address bound to the socket on the other end of the connection." +msgstr "" +"Socket 必須繫結到一個地址並偵聽連線。回傳值是一個 ``(conn, address)`` 對，其" +"中 *conn* 是一個 *新* socket 物件，可在連線上發送和接收資料，*address* 是連接" +"另一端對應的 socket 地址。" + +#: ../../library/asyncio-eventloop.rst:1192 +msgid ":meth:`loop.create_server` and :func:`start_server`." +msgstr ":meth:`loop.create_server` 和 :func:`start_server`。" + +#: ../../library/asyncio-eventloop.rst:1198 +msgid "" +"Send a file using high-performance :mod:`os.sendfile` if possible. Return " +"the total number of bytes sent." +msgstr "" +"如果可行，使用高性能 :mod:`os.sendfile` 發送檔案。回傳發送的總位元組數。" + +#: ../../library/asyncio-eventloop.rst:1201 +msgid "" +"Asynchronous version of :meth:`socket.sendfile() `." +msgstr ":meth:`socket.sendfile() ` 的非同步版本。" + +#: ../../library/asyncio-eventloop.rst:1203 +msgid "" +"*sock* must be a non-blocking :const:`socket.SOCK_STREAM` :class:`~socket." +"socket`." +msgstr "" +"*sock* 必須是非阻塞的 :const:`socket.SOCK_STREAM` :class:`~socket.socket`。" + +#: ../../library/asyncio-eventloop.rst:1206 +msgid "*file* must be a regular file object open in binary mode." +msgstr "*file* 必須是以二進位模式打開的常規檔案物件。" + +#: ../../library/asyncio-eventloop.rst:1215 +msgid "" +"*fallback*, when set to ``True``, makes asyncio manually read and send the " +"file when the platform does not support the sendfile syscall (e.g. Windows " +"or SSL socket on Unix)." +msgstr "" +"當設置為 ``True`` 時，*fallback* 使 asyncio 在平台不支援 sendfile 系統呼叫時" +"（例如 Windows 或 Unix 上的 SSL socket）手動讀取和發送檔案。" + +#: ../../library/asyncio-eventloop.rst:1219 +msgid "" +"Raise :exc:`SendfileNotAvailableError` if the system does not support " +"*sendfile* syscall and *fallback* is ``False``." +msgstr "" +"如果系統不支援 *sendfile* 系統呼叫且 *fallback* 為 ``False``，引發 :exc:" +"`SendfileNotAvailableError`。" + +#: ../../library/asyncio-eventloop.rst:1228 +msgid "DNS" +msgstr "DNS" + +#: ../../library/asyncio-eventloop.rst:1234 +msgid "Asynchronous version of :meth:`socket.getaddrinfo`." +msgstr ":meth:`socket.getaddrinfo` 的非同步版本。" + +#: ../../library/asyncio-eventloop.rst:1239 +msgid "Asynchronous version of :meth:`socket.getnameinfo`." +msgstr ":meth:`socket.getnameinfo` 的非同步版本。" + +#: ../../library/asyncio-eventloop.rst:1242 +msgid "" +"Both *getaddrinfo* and *getnameinfo* internally utilize their synchronous " +"versions through the loop's default thread pool executor. When this executor " +"is saturated, these methods may experience delays, which higher-level " +"networking libraries may report as increased timeouts. To mitigate this, " +"consider using a custom executor for other user tasks, or setting a default " +"executor with a larger number of workers." +msgstr "" + +#: ../../library/asyncio-eventloop.rst:1249 +msgid "" +"Both *getaddrinfo* and *getnameinfo* methods were always documented to " +"return a coroutine, but prior to Python 3.7 they were, in fact, returning :" +"class:`asyncio.Future` objects. Starting with Python 3.7 both methods are " +"coroutines." +msgstr "" +"*getaddrinfo* 和 *getnameinfo* 方法一直被記錄為回傳協程，但在 Python 3.7 之前" +"它們實際上回傳 :class:`asyncio.Future` 物件。從 Python 3.7 開始，兩個方法都是" +"協程。" + +#: ../../library/asyncio-eventloop.rst:1257 +msgid "Working with pipes" +msgstr "使用管道" + +#: ../../library/asyncio-eventloop.rst:1262 +msgid "Register the read end of *pipe* in the event loop." +msgstr "在事件迴圈中註冊 *pipe* 的讀取端。" + +#: ../../library/asyncio-eventloop.rst:1267 +msgid "*pipe* is a :term:`file-like object `." +msgstr "*pipe* 是 :term:`類檔案物件 `。" + +#: ../../library/asyncio-eventloop.rst:1269 +msgid "" +"Return pair ``(transport, protocol)``, where *transport* supports the :class:" +"`ReadTransport` interface and *protocol* is an object instantiated by the " +"*protocol_factory*." +msgstr "" +"回傳 ``(transport, protocol)`` 對，其中 *transport* 支援 :class:" +"`ReadTransport` 介面，*protocol* 是由 *protocol_factory* 實例化的物件。" + +#: ../../library/asyncio-eventloop.rst:1273 +#: ../../library/asyncio-eventloop.rst:1290 +msgid "" +"With :class:`SelectorEventLoop` event loop, the *pipe* is set to non-" +"blocking mode." +msgstr "使用 :class:`SelectorEventLoop` 事件迴圈時，*pipe* 設置為非阻塞模式。" + +#: ../../library/asyncio-eventloop.rst:1279 +msgid "Register the write end of *pipe* in the event loop." +msgstr "在事件迴圈中註冊 *pipe* 的寫入端。" + +#: ../../library/asyncio-eventloop.rst:1284 +msgid "*pipe* is :term:`file-like object `." +msgstr "*pipe* 是 :term:`file-like object `。" + +#: ../../library/asyncio-eventloop.rst:1286 +msgid "" +"Return pair ``(transport, protocol)``, where *transport* supports :class:" +"`WriteTransport` interface and *protocol* is an object instantiated by the " +"*protocol_factory*." +msgstr "" +"回傳 ``(transport, protocol)`` 對，其中 *transport* 支援 :class:" +"`WriteTransport` 介面，*protocol* 是由 *protocol_factory* 實例化的物件。" + +#: ../../library/asyncio-eventloop.rst:1295 +msgid "" +":class:`SelectorEventLoop` does not support the above methods on Windows. " +"Use :class:`ProactorEventLoop` instead for Windows." +msgstr "" +":class:`SelectorEventLoop` 在 Windows 上不支援上述方法。對於 Windows 請使用 :" +"class:`ProactorEventLoop`。" + +#: ../../library/asyncio-eventloop.rst:1300 +msgid "" +"The :meth:`loop.subprocess_exec` and :meth:`loop.subprocess_shell` methods." +msgstr ":meth:`loop.subprocess_exec` 和 :meth:`loop.subprocess_shell` 方法。" + +#: ../../library/asyncio-eventloop.rst:1305 +msgid "Unix signals" +msgstr "Unix 訊號" + +#: ../../library/asyncio-eventloop.rst:1311 +msgid "Set *callback* as the handler for the *signum* signal." +msgstr "將 *callback* 設置為 *signum* 訊號的處理程式。" + +#: ../../library/asyncio-eventloop.rst:1313 +msgid "" +"The callback will be invoked by *loop*, along with other queued callbacks " +"and runnable coroutines of that event loop. Unlike signal handlers " +"registered using :func:`signal.signal`, a callback registered with this " +"function is allowed to interact with the event loop." +msgstr "" +"該回呼將由 *loop* 叫用，與該事件迴圈的其他排隊回呼和可運行的協程一起。與使" +"用 :func:`signal.signal` 註冊的訊號處理程式不同，使用此函式註冊的回呼允許與事" +"件迴圈進行互動。" + +#: ../../library/asyncio-eventloop.rst:1318 +msgid "" +"Raise :exc:`ValueError` if the signal number is invalid or uncatchable. " +"Raise :exc:`RuntimeError` if there is a problem setting up the handler." +msgstr "" +"如果訊號號無效或不可捕獲，引發 :exc:`ValueError`。如果設定處理程序有問題，拋" +"出 :exc:`RuntimeError`。" + +#: ../../library/asyncio-eventloop.rst:1324 +msgid "" +"Like :func:`signal.signal`, this function must be invoked in the main thread." +msgstr "像 :func:`signal.signal` 一樣，此函式必須在主執行緒中叫用。" + +#: ../../library/asyncio-eventloop.rst:1329 +msgid "Remove the handler for the *sig* signal." +msgstr "移除 *sig* 訊號的處理程式。" + +#: ../../library/asyncio-eventloop.rst:1331 +msgid "" +"Return ``True`` if the signal handler was removed, or ``False`` if no " +"handler was set for the given signal." +msgstr "" +"如果訊號處理程式被移除，回傳 ``True``；如果給定訊號沒有設置處理程式，回傳 " +"``False``。" + +#: ../../library/asyncio-eventloop.rst:1338 +msgid "The :mod:`signal` module." +msgstr ":mod:`signal` 模組。" + +#: ../../library/asyncio-eventloop.rst:1342 +msgid "Executing code in thread or process pools" +msgstr "在執行緒池或行程池中執行程式碼" + +#: ../../library/asyncio-eventloop.rst:1346 +msgid "Arrange for *func* to be called in the specified executor." +msgstr "安排在指定的執行器中呼叫 *func*。" + +#: ../../library/asyncio-eventloop.rst:1348 +msgid "" +"The *executor* argument should be an :class:`concurrent.futures.Executor` " +"instance. The default executor is used if *executor* is ``None``. The " +"default executor can be set by :meth:`loop.set_default_executor`, otherwise, " +"a :class:`concurrent.futures.ThreadPoolExecutor` will be lazy-initialized " +"and used by :func:`run_in_executor` if needed." +msgstr "" + +#: ../../library/asyncio-eventloop.rst:1356 +msgid "" +"import asyncio\n" +"import concurrent.futures\n" +"\n" +"def blocking_io():\n" +" # File operations (such as logging) can block the\n" +" # event loop: run them in a thread pool.\n" +" with open('/dev/urandom', 'rb') as f:\n" +" return f.read(100)\n" +"\n" +"def cpu_bound():\n" +" # CPU-bound operations will block the event loop:\n" +" # in general it is preferable to run them in a\n" +" # process pool.\n" +" return sum(i * i for i in range(10 ** 7))\n" +"\n" +"async def main():\n" +" loop = asyncio.get_running_loop()\n" +"\n" +" ## Options:\n" +"\n" +" # 1. Run in the default loop's executor:\n" +" result = await loop.run_in_executor(\n" +" None, blocking_io)\n" +" print('default thread pool', result)\n" +"\n" +" # 2. Run in a custom thread pool:\n" +" with concurrent.futures.ThreadPoolExecutor() as pool:\n" +" result = await loop.run_in_executor(\n" +" pool, blocking_io)\n" +" print('custom thread pool', result)\n" +"\n" +" # 3. Run in a custom process pool:\n" +" with concurrent.futures.ProcessPoolExecutor() as pool:\n" +" result = await loop.run_in_executor(\n" +" pool, cpu_bound)\n" +" print('custom process pool', result)\n" +"\n" +" # 4. Run in a custom interpreter pool:\n" +" with concurrent.futures.InterpreterPoolExecutor() as pool:\n" +" result = await loop.run_in_executor(\n" +" pool, cpu_bound)\n" +" print('custom interpreter pool', result)\n" +"\n" +"if __name__ == '__main__':\n" +" asyncio.run(main())" +msgstr "" + +#: ../../library/asyncio-eventloop.rst:1402 +msgid "" +"Note that the entry point guard (``if __name__ == '__main__'``) is required " +"for option 3 due to the peculiarities of :mod:`multiprocessing`, which is " +"used by :class:`~concurrent.futures.ProcessPoolExecutor`. See :ref:`Safe " +"importing of main module `." +msgstr "" +"請注意，由於 :mod:`multiprocessing`\\ （由 :class:`~concurrent.futures." +"ProcessPoolExecutor` 使用）的特殊性，選項 3 需要進入點保護（\\ ``if __name__ " +"== '__main__'``\\ ）。請參閱\\ :ref:`主模組的安全引入 `。" + +#: ../../library/asyncio-eventloop.rst:1407 +msgid "This method returns a :class:`asyncio.Future` object." +msgstr "此方法回傳 :class:`asyncio.Future` 物件。" + +#: ../../library/asyncio-eventloop.rst:1409 +msgid "" +"Use :func:`functools.partial` :ref:`to pass keyword arguments ` to *func*." +msgstr "" +"使用 :func:`functools.partial` 將來\\ :ref:`關鍵字引數傳遞 `\\ 給 *func*。" + +#: ../../library/asyncio-eventloop.rst:1412 +msgid "" +":meth:`loop.run_in_executor` no longer configures the ``max_workers`` of the " +"thread pool executor it creates, instead leaving it up to the thread pool " +"executor (:class:`~concurrent.futures.ThreadPoolExecutor`) to set the " +"default." +msgstr "" +":meth:`loop.run_in_executor` 不再配置它建立的執行緒池執行器的 " +"``max_workers``，而是讓執行緒池執行器（\\ :class:`~concurrent.futures." +"ThreadPoolExecutor`）設定預設值。" + +#: ../../library/asyncio-eventloop.rst:1421 +msgid "" +"Set *executor* as the default executor used by :meth:`run_in_executor`. " +"*executor* must be an instance of :class:`~concurrent.futures." +"ThreadPoolExecutor`, which includes :class:`~concurrent.futures." +"InterpreterPoolExecutor`." +msgstr "" +"將 *executor* 設置為 :meth:`run_in_executor` 使用的預設執行器。*executor* 必" +"須是 :class:`~concurrent.futures.ThreadPoolExecutor`\\ （也包含 :class:" +"`~concurrent.futures.InterpreterPoolExecutor`）的實例。" + +#: ../../library/asyncio-eventloop.rst:1426 +msgid "" +"*executor* must be an instance of :class:`~concurrent.futures." +"ThreadPoolExecutor`." +msgstr "" +"*executor* 必須是 :class:`~concurrent.futures.ThreadPoolExecutor` 的實例。" + +#: ../../library/asyncio-eventloop.rst:1432 +msgid "Error Handling API" +msgstr "錯誤處理 API" + +#: ../../library/asyncio-eventloop.rst:1434 +msgid "Allows customizing how exceptions are handled in the event loop." +msgstr "允許自訂事件迴圈中的例外處理方式。" + +#: ../../library/asyncio-eventloop.rst:1438 +msgid "Set *handler* as the new event loop exception handler." +msgstr "將 *handler* 設定為新的事件迴圈例外處理程式。" + +#: ../../library/asyncio-eventloop.rst:1440 +msgid "" +"If *handler* is ``None``, the default exception handler will be set. " +"Otherwise, *handler* must be a callable with the signature matching ``(loop, " +"context)``, where ``loop`` is a reference to the active event loop, and " +"``context`` is a ``dict`` object containing the details of the exception " +"(see :meth:`call_exception_handler` documentation for details about context)." +msgstr "" +"如果 *handler* 是 ``None``，則將設置預設例外處理程式。否則，*handler* 必須是" +"一個可呼叫物件，簽名匹配 ``(loop, context)``，其中 ``loop`` 是參照活躍事件迴" +"圈的，``context`` 是包含例外詳細資訊的 ``dict`` 物件（有關情境的詳細資訊，請" +"參閱 :meth:`call_exception_handler` 文件）。" + +#: ../../library/asyncio-eventloop.rst:1448 +msgid "" +"If the handler is called on behalf of a :class:`~asyncio.Task` or :class:" +"`~asyncio.Handle`, it is run in the :class:`contextvars.Context` of that " +"task or callback handle." +msgstr "" +"如果代表 :class:`~asyncio.Task` 或 :class:`~asyncio.Handle` 呼叫處理程式，它" +"將在該任務或回呼處理程式的 :class:`contextvars.Context` 中運行。" + +#: ../../library/asyncio-eventloop.rst:1454 +msgid "" +"The handler may be called in the :class:`~contextvars.Context` of the task " +"or handle where the exception originated." +msgstr "" +"處理程式可能在引發例外的任務或處理程式的 :class:`~contextvars.Context` 中被呼" +"叫。" + +#: ../../library/asyncio-eventloop.rst:1459 +msgid "" +"Return the current exception handler, or ``None`` if no custom exception " +"handler was set." +msgstr "" +"回傳目前的例外處理程式，如果未設置自訂例外處理程式，則回傳 ``None``。" + +#: ../../library/asyncio-eventloop.rst:1466 +msgid "Default exception handler." +msgstr "預設例外處理程式。" + +#: ../../library/asyncio-eventloop.rst:1468 +msgid "" +"This is called when an exception occurs and no exception handler is set. " +"This can be called by a custom exception handler that wants to defer to the " +"default handler behavior." +msgstr "" +"當發生例外且未設置例外處理程式時呼叫此函式。自訂例外處理程式可以呼叫此函式" +"以轉由預設處理程式處理。" + +#: ../../library/asyncio-eventloop.rst:1472 +msgid "" +"*context* parameter has the same meaning as in :meth:" +"`call_exception_handler`." +msgstr "*context* 參數與 :meth:`call_exception_handler` 中的意思相同。" + +#: ../../library/asyncio-eventloop.rst:1477 +msgid "Call the current event loop exception handler." +msgstr "呼叫目前事件迴圈例外處理程式。" + +#: ../../library/asyncio-eventloop.rst:1479 +msgid "" +"*context* is a ``dict`` object containing the following keys (new keys may " +"be introduced in future Python versions):" +msgstr "" +"*context* 是一個包含以下鍵的 ``dict`` 物件（未來的 Python 版本中可能會引入新" +"的鍵）:" + +#: ../../library/asyncio-eventloop.rst:1482 +msgid "'message': Error message;" +msgstr "'message'：錯誤訊息；" + +#: ../../library/asyncio-eventloop.rst:1483 +msgid "'exception' (optional): Exception object;" +msgstr "'exception'（可選）：例外物件；" + +#: ../../library/asyncio-eventloop.rst:1484 +msgid "'future' (optional): :class:`asyncio.Future` instance;" +msgstr "'future'（可選）： :class:`asyncio.Future` 實例；" + +#: ../../library/asyncio-eventloop.rst:1485 +msgid "'task' (optional): :class:`asyncio.Task` instance;" +msgstr "'task'（可選）： :class:`asyncio.Task` 實例；" + +#: ../../library/asyncio-eventloop.rst:1486 +msgid "'handle' (optional): :class:`asyncio.Handle` instance;" +msgstr "'handle'（可選）： :class:`asyncio.Handle` 實例；" + +#: ../../library/asyncio-eventloop.rst:1487 +msgid "'protocol' (optional): :ref:`Protocol ` instance;" +msgstr "'protocol'（可選）： :ref:`Protocol ` 實例；" + +#: ../../library/asyncio-eventloop.rst:1488 +msgid "'transport' (optional): :ref:`Transport ` instance;" +msgstr "'transport'（可選）： :ref:`Transport ` 實例；" + +#: ../../library/asyncio-eventloop.rst:1489 +msgid "'socket' (optional): :class:`socket.socket` instance;" +msgstr "'socket'（可選）： :class:`socket.socket` 實例；" + +#: ../../library/asyncio-eventloop.rst:1490 +msgid "'source_traceback' (optional): Traceback of the source;" +msgstr "" + +#: ../../library/asyncio-eventloop.rst:1491 +msgid "'handle_traceback' (optional): Traceback of the handle;" +msgstr "" + +#: ../../library/asyncio-eventloop.rst:1492 +msgid "'asyncgen' (optional): Asynchronous generator that caused" +msgstr "'asyncgen'(可選)： 非同步產生器引發" + +#: ../../library/asyncio-eventloop.rst:1493 +msgid "the exception." +msgstr "例外。" + +#: ../../library/asyncio-eventloop.rst:1497 +msgid "" +"This method should not be overloaded in subclassed event loops. For custom " +"exception handling, use the :meth:`set_exception_handler` method." +msgstr "" +"此方法不應在子類別事件迴圈中被覆寫。為了自訂例外處理，請使用 :meth:" +"`set_exception_handler` 方法。" + +#: ../../library/asyncio-eventloop.rst:1502 +msgid "Enabling debug mode" +msgstr "啟用除錯模式" + +#: ../../library/asyncio-eventloop.rst:1506 +msgid "Get the debug mode (:class:`bool`) of the event loop." +msgstr "取得事件迴圈的除錯模式（\\ :class:`bool`\\ ）。" + +#: ../../library/asyncio-eventloop.rst:1508 +msgid "" +"The default value is ``True`` if the environment variable :envvar:" +"`PYTHONASYNCIODEBUG` is set to a non-empty string, ``False`` otherwise." +msgstr "" +"如果環境變數 :envvar:`PYTHONASYNCIODEBUG` 被設定為非空字串，則預設值為 " +"``True``，否則為 ``False``。" + +#: ../../library/asyncio-eventloop.rst:1514 +msgid "Set the debug mode of the event loop." +msgstr "設定事件迴圈的除錯模式。" + +#: ../../library/asyncio-eventloop.rst:1518 +msgid "" +"The new :ref:`Python Development Mode ` can now also be used to " +"enable the debug mode." +msgstr "現在也可以使用新的 :ref:`Python 開發模式 ` 啟用除錯模式。" + +#: ../../library/asyncio-eventloop.rst:1523 +msgid "" +"This attribute can be used to set the minimum execution duration in seconds " +"that is considered \"slow\". When debug mode is enabled, \"slow\" callbacks " +"are logged." +msgstr "" +"此屬性可用於設定被視為\"慢\"的最短執行時間（以秒為單位）。啟用偵錯模式" +"後，\"慢\"回呼將被記錄。" + +#: ../../library/asyncio-eventloop.rst:1527 +msgid "Default value is 100 milliseconds." +msgstr "預設值為 100 毫秒" + +#: ../../library/asyncio-eventloop.rst:1531 +msgid "The :ref:`debug mode of asyncio `." +msgstr ":ref:`asyncio 的除錯模式 `。" + +#: ../../library/asyncio-eventloop.rst:1535 +msgid "Running Subprocesses" +msgstr "運行子行程" + +#: ../../library/asyncio-eventloop.rst:1537 +msgid "" +"Methods described in this subsections are low-level. In regular async/await " +"code consider using the high-level :func:`asyncio.create_subprocess_shell` " +"and :func:`asyncio.create_subprocess_exec` convenience functions instead." +msgstr "" +"本小節描述的方法是低階的。在常規的 async/await 程式碼中，請考慮使用高階 :" +"func:`asyncio.create_subprocess_shell` 和 :func:`asyncio." +"create_subprocess_exec` 輔助功能而不是。" + +#: ../../library/asyncio-eventloop.rst:1544 +msgid "" +"On Windows, the default event loop :class:`ProactorEventLoop` supports " +"subprocesses, whereas :class:`SelectorEventLoop` does not. See :ref:" +"`Subprocess Support on Windows ` for details." +msgstr "" +"在 Windows 上，預設事件迴圈 :class:`ProactorEventLoop` 支援子行程，而 :class:" +"`SelectorEventLoop` 不支援。詳細資訊請參見 :ref:`Windows 上對於子行程的支援 " +"`。" + +#: ../../library/asyncio-eventloop.rst:1556 +msgid "" +"Create a subprocess from one or more string arguments specified by *args*." +msgstr "從 *args* 指定的一個或多個字串引數建立子行程。" + +#: ../../library/asyncio-eventloop.rst:1559 +msgid "*args* must be a list of strings represented by:" +msgstr "*args* 必須是由以下項表示的字串串列：" + +#: ../../library/asyncio-eventloop.rst:1561 +msgid ":class:`str`;" +msgstr ":class:`str`；" + +#: ../../library/asyncio-eventloop.rst:1562 +msgid "" +"or :class:`bytes`, encoded to the :ref:`filesystem encoding `." +msgstr "或 :class:`bytes`，編碼為 :ref:`檔案系統編碼 `。" + +#: ../../library/asyncio-eventloop.rst:1565 +msgid "" +"The first string specifies the program executable, and the remaining strings " +"specify the arguments. Together, string arguments form the ``argv`` of the " +"program." +msgstr "" +"第一個字串指定程序可執行檔案，其餘字串指定引數。字串引數一起組成程序的 " +"``argv``。" + +#: ../../library/asyncio-eventloop.rst:1569 +msgid "" +"This is similar to the standard library :class:`subprocess.Popen` class " +"called with ``shell=False`` and the list of strings passed as the first " +"argument; however, where :class:`~subprocess.Popen` takes a single argument " +"which is list of strings, *subprocess_exec* takes multiple string arguments." +msgstr "" +"這與標準函式庫 :class:`subprocess.Popen` 類似，使用 ``shell=False`` 呼叫並將" +"字串串列作為第一個引數傳遞；然而，:class:`~subprocess.Popen` 接受單個字串串列" +"引數，*subprocess_exec* 接受多個字串引數。" + +#: ../../library/asyncio-eventloop.rst:1575 +msgid "" +"The *protocol_factory* must be a callable returning a subclass of the :class:" +"`asyncio.SubprocessProtocol` class." +msgstr "" +"*protocol_factory* 必須是回傳 :class:`asyncio.SubprocessProtocol` 子類別的可" +"呼叫物件。" + +#: ../../library/asyncio-eventloop.rst:1578 +msgid "Other parameters:" +msgstr "其他參數：" + +#: ../../library/asyncio-eventloop.rst:1580 +msgid "*stdin* can be any of these:" +msgstr "*stdin* 可以是以下任意一個：" + +#: ../../library/asyncio-eventloop.rst:1582 +#: ../../library/asyncio-eventloop.rst:1593 +#: ../../library/asyncio-eventloop.rst:1603 +msgid "a file-like object" +msgstr "類檔案物件" + +#: ../../library/asyncio-eventloop.rst:1583 +msgid "" +"an existing file descriptor (a positive integer), for example those created " +"with :meth:`os.pipe`" +msgstr "現有的檔案描述器（正整數），例如用 :meth:`os.pipe` 建立的" + +#: ../../library/asyncio-eventloop.rst:1584 +#: ../../library/asyncio-eventloop.rst:1594 +#: ../../library/asyncio-eventloop.rst:1604 +msgid "" +"the :const:`subprocess.PIPE` constant (default) which will create a new pipe " +"and connect it," +msgstr ":const:`subprocess.PIPE` 常數（預設），它將建立一個新的管道並連線，" + +#: ../../library/asyncio-eventloop.rst:1586 +#: ../../library/asyncio-eventloop.rst:1596 +#: ../../library/asyncio-eventloop.rst:1606 +msgid "" +"the value ``None`` which will make the subprocess inherit the file " +"descriptor from this process" +msgstr "值 ``None`` 將使子行程從此行程繼承檔案描述器" + +#: ../../library/asyncio-eventloop.rst:1588 +#: ../../library/asyncio-eventloop.rst:1598 +#: ../../library/asyncio-eventloop.rst:1608 +msgid "" +"the :const:`subprocess.DEVNULL` constant which indicates that the special :" +"data:`os.devnull` file will be used" +msgstr "" +":const:`subprocess.DEVNULL` 常數，表示將使用特殊的 :data:`os.devnull` 檔案" + +#: ../../library/asyncio-eventloop.rst:1591 +msgid "*stdout* can be any of these:" +msgstr "*stdout* 可以是以下任意一個：" + +#: ../../library/asyncio-eventloop.rst:1601 +msgid "*stderr* can be any of these:" +msgstr "*stderr* 可以是以下任意一個：" + +#: ../../library/asyncio-eventloop.rst:1610 +msgid "" +"the :const:`subprocess.STDOUT` constant which will connect the standard " +"error stream to the process' standard output stream" +msgstr "" +":const:`subprocess.STDOUT` 常數，它將標準錯誤串流連線到行程的標準輸出串流" + +#: ../../library/asyncio-eventloop.rst:1613 +msgid "" +"All other keyword arguments are passed to :class:`subprocess.Popen` without " +"interpretation, except for *bufsize*, *universal_newlines*, *shell*, *text*, " +"*encoding* and *errors*, which should not be specified at all." +msgstr "" +"所有其他關鍵字引數都會傳遞給 :class:`subprocess.Popen` 而不進行直譯，但 " +"*bufsize*、*universal_newlines*、*shell*、*text*、*encoding* 和 *errors* 除" +"外，這些不應該指定。" + +#: ../../library/asyncio-eventloop.rst:1618 +msgid "" +"The ``asyncio`` subprocess API does not support decoding the streams as " +"text. :func:`bytes.decode` can be used to convert the bytes returned from " +"the stream to text." +msgstr "" +"``asyncio`` 子行程 API 不支援將串流解碼為文本。可以使用 :func:`bytes.decode` " +"將從串流回傳的位元組轉換為文本。" + +#: ../../library/asyncio-eventloop.rst:1622 +msgid "" +"If a file-like object passed as *stdin*, *stdout* or *stderr* represents a " +"pipe, then the other side of this pipe should be registered with :meth:" +"`~loop.connect_write_pipe` or :meth:`~loop.connect_read_pipe` for use with " +"the event loop." +msgstr "" +"如果傳遞給 *stdin*、*stdout* 或 *stderr* 的類檔案物件表示管道，則該管道的另一" +"端應該使用 :meth:`~loop.connect_write_pipe` 或 :meth:`~loop." +"connect_read_pipe` 註冊到事件迴圈中。" + +#: ../../library/asyncio-eventloop.rst:1627 +msgid "" +"See the constructor of the :class:`subprocess.Popen` class for documentation " +"on other arguments." +msgstr "有關其他引數的文件，請參閱 :class:`subprocess.Popen` 類別的建構函式。" + +#: ../../library/asyncio-eventloop.rst:1630 +msgid "" +"Returns a pair of ``(transport, protocol)``, where *transport* conforms to " +"the :class:`asyncio.SubprocessTransport` base class and *protocol* is an " +"object instantiated by the *protocol_factory*." +msgstr "" +"回傳 ``(transport, protocol)`` 對，其中 *transport* 符合 :class:`asyncio." +"SubprocessTransport` 基底類別，*protocol* 是由 *protocol_factory* 實例化的物" +"件。" + +#: ../../library/asyncio-eventloop.rst:1634 +#: ../../library/asyncio-eventloop.rst:1660 +msgid "" +"If the transport is closed or is garbage collected, the child process is " +"killed if it is still running." +msgstr "" + +#: ../../library/asyncio-eventloop.rst:1642 +msgid "" +"Create a subprocess from *cmd*, which can be a :class:`str` or a :class:" +"`bytes` string encoded to the :ref:`filesystem encoding `, using the platform's \"shell\" syntax." +msgstr "" +"使用平台的 \"shell\" 語法從 *cmd* 建立子行程，*cmd* 可以是 :class:`str` 或編" +"碼為 :ref:`檔案系統編碼 ` 的 :class:`bytes` 字串。" + +#: ../../library/asyncio-eventloop.rst:1647 +msgid "" +"This is similar to the standard library :class:`subprocess.Popen` class " +"called with ``shell=True``." +msgstr "" +"這類似於標準函式庫中的 :class:`subprocess.Popen` 類別，使用 ``shell=True`` 呼" +"叫。" + +#: ../../library/asyncio-eventloop.rst:1650 +msgid "" +"The *protocol_factory* must be a callable returning a subclass of the :class:" +"`SubprocessProtocol` class." +msgstr "" +"*protocol_factory* 必須是回傳 :class:`SubprocessProtocol` 子類別的可呼叫物" +"件。" + +#: ../../library/asyncio-eventloop.rst:1653 +msgid "" +"See :meth:`~loop.subprocess_exec` for more details about the remaining " +"arguments." +msgstr "有關其餘引數的更多詳細資訊，請參閱 :meth:`~loop.subprocess_exec`。" + +#: ../../library/asyncio-eventloop.rst:1656 +msgid "" +"Returns a pair of ``(transport, protocol)``, where *transport* conforms to " +"the :class:`SubprocessTransport` base class and *protocol* is an object " +"instantiated by the *protocol_factory*." +msgstr "" +"回傳一對 ``(transport, protocol)``，其中 *transport* 符合 :class:" +"`SubprocessTransport` 基底類別，而 *protocol* 是由 *protocol_factory* 實例化" +"的物件。" + +#: ../../library/asyncio-eventloop.rst:1664 +msgid "" +"It is the application's responsibility to ensure that all whitespace and " +"special characters are quoted appropriately to avoid `shell injection " +"`_ " +"vulnerabilities. The :func:`shlex.quote` function can be used to properly " +"escape whitespace and special characters in strings that are going to be " +"used to construct shell commands." +msgstr "" +"由應用程式負責確保適當引用所有空白和特殊字元，以避免 `shell 注入 `_\\ 風險。可以使用 :func:" +"`shlex.quote` 函式來正確跳脫用於構建 shell 命令的字串中的空白和特殊字元。" + +#: ../../library/asyncio-eventloop.rst:1673 +msgid "Callback Handles" +msgstr "回呼處理" + +#: ../../library/asyncio-eventloop.rst:1677 +msgid "" +"A callback wrapper object returned by :meth:`loop.call_soon`, :meth:`loop." +"call_soon_threadsafe`." +msgstr "" +"由 :meth:`loop.call_soon` 和 :meth:`loop.call_soon_threadsafe` 回傳的回呼包裝" +"器。" + +#: ../../library/asyncio-eventloop.rst:1682 +msgid "" +"Return the :class:`contextvars.Context` object associated with the handle." +msgstr "回傳與處理相關聯的 :class:`contextvars.Context` 物件。" + +#: ../../library/asyncio-eventloop.rst:1689 +msgid "" +"Cancel the callback. If the callback has already been canceled or executed, " +"this method has no effect." +msgstr "取消回呼。如果回呼已被取消或執行，此方法將不起作用。" + +#: ../../library/asyncio-eventloop.rst:1694 +msgid "Return ``True`` if the callback was cancelled." +msgstr "如果回呼已被取消，回傳 ``True``。" + +#: ../../library/asyncio-eventloop.rst:1700 +msgid "" +"A callback wrapper object returned by :meth:`loop.call_later`, and :meth:" +"`loop.call_at`." +msgstr "由 :meth:`loop.call_later` 和 :meth:`loop.call_at` 回傳的回呼包裝器。" + +#: ../../library/asyncio-eventloop.rst:1703 +msgid "This class is a subclass of :class:`Handle`." +msgstr "這個類別是 :class:`Handle` 的子類別。" + +#: ../../library/asyncio-eventloop.rst:1707 +msgid "Return a scheduled callback time as :class:`float` seconds." +msgstr "回傳預定的回呼時間，以 :class:`float` 秒為單位。" + +#: ../../library/asyncio-eventloop.rst:1709 +msgid "" +"The time is an absolute timestamp, using the same time reference as :meth:" +"`loop.time`." +msgstr "時間是一個絕對的時間戳，使用與 :meth:`loop.time` 相同的時間參照。" + +#: ../../library/asyncio-eventloop.rst:1716 +msgid "Server Objects" +msgstr "Server 物件" + +#: ../../library/asyncio-eventloop.rst:1718 +msgid "" +"Server objects are created by :meth:`loop.create_server`, :meth:`loop." +"create_unix_server`, :func:`start_server`, and :func:`start_unix_server` " +"functions." +msgstr "" +"Server 物件是由 :meth:`loop.create_server`、:meth:`loop." +"create_unix_server`、:func:`start_server` 和 :func:`start_unix_server` 函式所" +"建立。" + +#: ../../library/asyncio-eventloop.rst:1722 +msgid "Do not instantiate the :class:`Server` class directly." +msgstr "請勿直接實例化 :class:`Server` 類別。" + +#: ../../library/asyncio-eventloop.rst:1726 +msgid "" +"*Server* objects are asynchronous context managers. When used in an ``async " +"with`` statement, it's guaranteed that the Server object is closed and not " +"accepting new connections when the ``async with`` statement is completed::" +msgstr "" +"*Server* 物件是非同步情境管理器。當在 ``async with`` 陳述中使用時，可以保證在" +"完成 ``async with`` 陳述時，Server 物件將會關閉並停止接受新的連線： ::" + +#: ../../library/asyncio-eventloop.rst:1731 +msgid "" +"srv = await loop.create_server(...)\n" +"\n" +"async with srv:\n" +" # some code\n" +"\n" +"# At this point, srv is closed and no longer accepts new connections." +msgstr "" +"srv = await loop.create_server(...)\n" +"\n" +"async with srv:\n" +" # 一些程式碼\n" +"\n" +"# 此時 srv 已關閉，不再接受新的連線。" + +#: ../../library/asyncio-eventloop.rst:1739 +msgid "Server object is an asynchronous context manager since Python 3.7." +msgstr "自 Python 3.7 起，Server 物件是非同步情境管理器。" + +#: ../../library/asyncio-eventloop.rst:1742 +msgid "" +"This class was exposed publicly as ``asyncio.Server`` in Python 3.9.11, " +"3.10.3 and 3.11." +msgstr "" +"此類別在 Python 3.9.11、3.10.3 和 3.11 中以 ``asyncio.Server`` 的形式被公開。" + +#: ../../library/asyncio-eventloop.rst:1747 +msgid "" +"Stop serving: close listening sockets and set the :attr:`sockets` attribute " +"to ``None``." +msgstr "停止服務：關閉監聽的 sockets 並將 :attr:`sockets` 屬性設為 ``None``。" + +#: ../../library/asyncio-eventloop.rst:1750 +msgid "" +"The sockets that represent existing incoming client connections are left " +"open." +msgstr "代表現有傳入用戶端連線的 sockets 仍然保持開啟。" + +#: ../../library/asyncio-eventloop.rst:1753 +msgid "" +"The server is closed asynchronously; use the :meth:`wait_closed` coroutine " +"to wait until the server is closed (and no more connections are active)." +msgstr "" +"伺服器以非同步方式關閉；使用 :meth:`wait_closed` 協程等待伺服器關閉（不再有活" +"躍連線）。" + +#: ../../library/asyncio-eventloop.rst:1759 +msgid "Close all existing incoming client connections." +msgstr "關閉所有現有的傳入用戶端連線。" + +#: ../../library/asyncio-eventloop.rst:1761 +msgid "" +"Calls :meth:`~asyncio.BaseTransport.close` on all associated transports." +msgstr "在所有關聯的傳輸上呼叫 :meth:`~asyncio.BaseTransport.close`。" + +#: ../../library/asyncio-eventloop.rst:1764 +msgid "" +":meth:`close` should be called before :meth:`close_clients` when closing the " +"server to avoid races with new clients connecting." +msgstr "" + +#: ../../library/asyncio-eventloop.rst:1771 +msgid "" +"Close all existing incoming client connections immediately, without waiting " +"for pending operations to complete." +msgstr "立即關閉所有現有的傳入用戶端連線，而不等待待定操作完成。" + +#: ../../library/asyncio-eventloop.rst:1774 +msgid "" +"Calls :meth:`~asyncio.WriteTransport.abort` on all associated transports." +msgstr "在所有關聯的傳輸上呼叫 :meth:`~asyncio.WriteTransport.abort`。" + +#: ../../library/asyncio-eventloop.rst:1777 +msgid "" +":meth:`close` should be called before :meth:`abort_clients` when closing the " +"server to avoid races with new clients connecting." +msgstr "" + +#: ../../library/asyncio-eventloop.rst:1784 +msgid "Return the event loop associated with the server object." +msgstr "回傳與伺服器物件關聯的事件迴圈。" + +#: ../../library/asyncio-eventloop.rst:1791 +msgid "Start accepting connections." +msgstr "開始接受連線。" + +#: ../../library/asyncio-eventloop.rst:1793 +msgid "" +"This method is idempotent, so it can be called when the server is already " +"serving." +msgstr "此方法是幂等的，因此可以在伺服器已經運行時呼叫。" + +#: ../../library/asyncio-eventloop.rst:1796 +msgid "" +"The *start_serving* keyword-only parameter to :meth:`loop.create_server` " +"and :meth:`asyncio.start_server` allows creating a Server object that is not " +"accepting connections initially. In this case ``Server.start_serving()``, " +"or :meth:`Server.serve_forever` can be used to make the Server start " +"accepting connections." +msgstr "" +"*start_serving* 僅限關鍵字參數只能在 :meth:`loop.create_server` 和 :meth:" +"`asyncio.start_server` 中使用，允許建立一個最初不接受連線的 Server 物件。在這" +"種情況下，可以使用 ``Server.start_serving()`` 或 :meth:`Server." +"serve_forever` 來使 Server 開始接受連線。" + +#: ../../library/asyncio-eventloop.rst:1808 +msgid "" +"Start accepting connections until the coroutine is cancelled. Cancellation " +"of ``serve_forever`` task causes the server to be closed." +msgstr "" +"開始接受連線，直到協程被取消。取消 ``serve_forever`` 任務會導致伺服器關閉。" + +#: ../../library/asyncio-eventloop.rst:1812 +msgid "" +"This method can be called if the server is already accepting connections. " +"Only one ``serve_forever`` task can exist per one *Server* object." +msgstr "" +"如果伺服器已經接受連線，則可以呼叫此方法。每個 *Server* 物件只能存在一個 " +"``serve_forever`` 任務。" + +#: ../../library/asyncio-eventloop.rst:1818 +msgid "" +"async def client_connected(reader, writer):\n" +" # Communicate with the client with\n" +" # reader/writer streams. For example:\n" +" await reader.readline()\n" +"\n" +"async def main(host, port):\n" +" srv = await asyncio.start_server(\n" +" client_connected, host, port)\n" +" await srv.serve_forever()\n" +"\n" +"asyncio.run(main('127.0.0.1', 0))" +msgstr "" +"async def client_connected(reader, writer):\n" +" # 透過讀取器/寫入器串流\n" +" # 與用戶端溝通。例如：\n" +" await reader.readline()\n" +"\n" +"async def main(host, port):\n" +" srv = await asyncio.start_server(\n" +" client_connected, host, port)\n" +" await srv.serve_forever()\n" +"\n" +"asyncio.run(main('127.0.0.1', 0))" + +#: ../../library/asyncio-eventloop.rst:1834 +msgid "Return ``True`` if the server is accepting new connections." +msgstr "如果伺服器正在接受新連線，則回傳 ``True``。" + +#: ../../library/asyncio-eventloop.rst:1841 +msgid "" +"Wait until the :meth:`close` method completes and all active connections " +"have finished." +msgstr "等待 :meth:`close` 方法完成且所有活動連線都已結束。" + +#: ../../library/asyncio-eventloop.rst:1846 +msgid "" +"List of socket-like objects, ``asyncio.trsock.TransportSocket``, which the " +"server is listening on." +msgstr "" +"伺服器正在監聽的類似 socket 的物件串列，``asyncio.trsock.TransportSocket``。" + +#: ../../library/asyncio-eventloop.rst:1849 +msgid "" +"Prior to Python 3.7 ``Server.sockets`` used to return an internal list of " +"server sockets directly. In 3.7 a copy of that list is returned." +msgstr "" +"在 Python 3.7 之前，``Server.sockets`` 曾經直接回傳內部伺服器 sockets 的串" +"列。在 3.7 中回傳了該串列的副本。" + +#: ../../library/asyncio-eventloop.rst:1859 +msgid "Event Loop Implementations" +msgstr "事件迴圈實作" + +#: ../../library/asyncio-eventloop.rst:1861 +msgid "" +"asyncio ships with two different event loop implementations: :class:" +"`SelectorEventLoop` and :class:`ProactorEventLoop`." +msgstr "" +"asyncio 內附兩個不同的事件迴圈實作：:class:`SelectorEventLoop` 和 :class:" +"`ProactorEventLoop`。" + +#: ../../library/asyncio-eventloop.rst:1864 +msgid "By default asyncio is configured to use :class:`EventLoop`." +msgstr "預設情況下，asyncio 被配置為要使用 :class:`EventLoop`。" + +#: ../../library/asyncio-eventloop.rst:1869 +msgid "" +"A subclass of :class:`AbstractEventLoop` based on the :mod:`selectors` " +"module." +msgstr "基於 :mod:`selectors` 模組的一個 :class:`AbstractEventLoop` 子類別。" + +#: ../../library/asyncio-eventloop.rst:1872 +msgid "" +"Uses the most efficient *selector* available for the given platform. It is " +"also possible to manually configure the exact selector implementation to be " +"used::" +msgstr "" +"使用特定平台上最有效的 *selector*。也可以手動配置要使用的確切 selector 實" +"作： ::" + +#: ../../library/asyncio-eventloop.rst:1876 +msgid "" +"import asyncio\n" +"import selectors\n" +"\n" +"async def main():\n" +" ...\n" +"\n" +"loop_factory = lambda: asyncio.SelectorEventLoop(selectors." +"SelectSelector())\n" +"asyncio.run(main(), loop_factory=loop_factory)" +msgstr "" + +#: ../../library/asyncio-eventloop.rst:1891 +msgid "" +"A subclass of :class:`AbstractEventLoop` for Windows that uses \"I/O " +"Completion Ports\" (IOCP)." +msgstr "" +"用於 Windows 的 :class:`AbstractEventLoop` 子類別，使用「I/O 完成埠 (IOCP, I/" +"O Completion Ports)」。" + +#: ../../library/asyncio-eventloop.rst:1897 +msgid "" +"`MSDN documentation on I/O Completion Ports `_." +msgstr "" +"`I/O 完成埠的 MSDN 文件 `_。" + +#: ../../library/asyncio-eventloop.rst:1902 +msgid "" +"An alias to the most efficient available subclass of :class:" +"`AbstractEventLoop` for the given platform." +msgstr "" + +#: ../../library/asyncio-eventloop.rst:1905 +msgid "" +"It is an alias to :class:`SelectorEventLoop` on Unix and :class:" +"`ProactorEventLoop` on Windows." +msgstr "" +"在 Unix 上是 :class:`SelectorEventLoop` 的別名，在 Windows 上是 :class:" +"`ProactorEventLoop` 的別名。" + +#: ../../library/asyncio-eventloop.rst:1911 +msgid "Abstract base class for asyncio-compliant event loops." +msgstr "為符合 asyncio 標準的事件迴圈的抽象基礎類別。" + +#: ../../library/asyncio-eventloop.rst:1913 +msgid "" +"The :ref:`asyncio-event-loop-methods` section lists all methods that an " +"alternative implementation of ``AbstractEventLoop`` should have defined." +msgstr "" +":ref:`asyncio-event-loop-methods` 部分列出了替代 ``AbstractEventLoop`` 實作應" +"該定義的所有方法。" + +#: ../../library/asyncio-eventloop.rst:1919 +msgid "Examples" +msgstr "範例" + +#: ../../library/asyncio-eventloop.rst:1921 +msgid "" +"Note that all examples in this section **purposefully** show how to use the " +"low-level event loop APIs, such as :meth:`loop.run_forever` and :meth:`loop." +"call_soon`. Modern asyncio applications rarely need to be written this way; " +"consider using the high-level functions like :func:`asyncio.run`." +msgstr "" +"請注意，本節中的所有範例都 **故意** 展示如何使用低階事件迴圈 API，如 :meth:" +"`loop.run_forever` 和 :meth:`loop.call_soon`。現代 asyncio 應用程式很少需要這" +"種方式撰寫；請考慮使用高階的函式，如 :func:`asyncio.run`。" + +#: ../../library/asyncio-eventloop.rst:1931 +msgid "Hello World with call_soon()" +msgstr "使用 call_soon() 的 Hello World 範例" + +#: ../../library/asyncio-eventloop.rst:1933 +msgid "" +"An example using the :meth:`loop.call_soon` method to schedule a callback. " +"The callback displays ``\"Hello World\"`` and then stops the event loop::" +msgstr "" +"使用 :meth:`loop.call_soon` 方法排程回呼的範例。回呼會顯示 ``\"Hello " +"World\"``，然後停止事件迴圈： ::" + +#: ../../library/asyncio-eventloop.rst:1937 +msgid "" +"import asyncio\n" +"\n" +"def hello_world(loop):\n" +" \"\"\"A callback to print 'Hello World' and stop the event loop\"\"\"\n" +" print('Hello World')\n" +" loop.stop()\n" +"\n" +"loop = asyncio.new_event_loop()\n" +"\n" +"# Schedule a call to hello_world()\n" +"loop.call_soon(hello_world, loop)\n" +"\n" +"# Blocking call interrupted by loop.stop()\n" +"try:\n" +" loop.run_forever()\n" +"finally:\n" +" loop.close()" +msgstr "" +"import asyncio\n" +"\n" +"def hello_world(loop):\n" +" \"\"\"列印 'Hello World' 並停止事件迴圈的回呼\"\"\"\n" +" print('Hello World')\n" +" loop.stop()\n" +"\n" +"loop = asyncio.new_event_loop()\n" +"\n" +"# 排程對 hello_world() 的呼叫\n" +"loop.call_soon(hello_world, loop)\n" +"\n" +"# 阻塞呼叫被 loop.stop() 中斷\n" +"try:\n" +" loop.run_forever()\n" +"finally:\n" +" loop.close()" + +#: ../../library/asyncio-eventloop.rst:1957 +msgid "" +"A similar :ref:`Hello World ` example created with a coroutine " +"and the :func:`run` function." +msgstr "" +"使用協程和 :func:`run` 函式建立的類似 :ref:`Hello World ` 範例。" + +#: ../../library/asyncio-eventloop.rst:1964 +msgid "Display the current date with call_later()" +msgstr "使用 call_later() 顯示目前日期" + +#: ../../library/asyncio-eventloop.rst:1966 +msgid "" +"An example of a callback displaying the current date every second. The " +"callback uses the :meth:`loop.call_later` method to reschedule itself after " +"5 seconds, and then stops the event loop::" +msgstr "" +"一個回呼的範例，每秒顯示目前日期。回呼使用 :meth:`loop.call_later` 方法在 5 " +"秒後重新排程自己，然後停止事件迴圈： ::" + +#: ../../library/asyncio-eventloop.rst:1970 +msgid "" +"import asyncio\n" +"import datetime\n" +"\n" +"def display_date(end_time, loop):\n" +" print(datetime.datetime.now())\n" +" if (loop.time() + 1.0) < end_time:\n" +" loop.call_later(1, display_date, end_time, loop)\n" +" else:\n" +" loop.stop()\n" +"\n" +"loop = asyncio.new_event_loop()\n" +"\n" +"# Schedule the first call to display_date()\n" +"end_time = loop.time() + 5.0\n" +"loop.call_soon(display_date, end_time, loop)\n" +"\n" +"# Blocking call interrupted by loop.stop()\n" +"try:\n" +" loop.run_forever()\n" +"finally:\n" +" loop.close()" +msgstr "" +"import asyncio\n" +"import datetime\n" +"\n" +"def display_date(end_time, loop):\n" +" print(datetime.datetime.now())\n" +" if (loop.time() + 1.0) < end_time:\n" +" loop.call_later(1, display_date, end_time, loop)\n" +" else:\n" +" loop.stop()\n" +"\n" +"loop = asyncio.new_event_loop()\n" +"\n" +"# 排程 display_date() 的第一次呼叫\n" +"end_time = loop.time() + 5.0\n" +"loop.call_soon(display_date, end_time, loop)\n" +"\n" +"# 阻塞呼叫被 loop.stop() 中斷\n" +"try:\n" +" loop.run_forever()\n" +"finally:\n" +" loop.close()" + +#: ../../library/asyncio-eventloop.rst:1994 +msgid "" +"A similar :ref:`current date ` example created with a " +"coroutine and the :func:`run` function." +msgstr "" +"使用協程和 :func:`run` 函式建立的類似 :ref:`current date " +"` 範例。" + +#: ../../library/asyncio-eventloop.rst:2001 +msgid "Watch a file descriptor for read events" +msgstr "監聽檔案描述器以進行讀取事件" + +#: ../../library/asyncio-eventloop.rst:2003 +msgid "" +"Wait until a file descriptor received some data using the :meth:`loop." +"add_reader` method and then close the event loop::" +msgstr "" +"使用 :meth:`loop.add_reader` 方法等待檔案描述器接收到某些資料，然後關閉事件迴" +"圈： ::" + +#: ../../library/asyncio-eventloop.rst:2006 +msgid "" +"import asyncio\n" +"from socket import socketpair\n" +"\n" +"# Create a pair of connected file descriptors\n" +"rsock, wsock = socketpair()\n" +"\n" +"loop = asyncio.new_event_loop()\n" +"\n" +"def reader():\n" +" data = rsock.recv(100)\n" +" print(\"Received:\", data.decode())\n" +"\n" +" # We are done: unregister the file descriptor\n" +" loop.remove_reader(rsock)\n" +"\n" +" # Stop the event loop\n" +" loop.stop()\n" +"\n" +"# Register the file descriptor for read event\n" +"loop.add_reader(rsock, reader)\n" +"\n" +"# Simulate the reception of data from the network\n" +"loop.call_soon(wsock.send, 'abc'.encode())\n" +"\n" +"try:\n" +" # Run the event loop\n" +" loop.run_forever()\n" +"finally:\n" +" # We are done. Close sockets and the event loop.\n" +" rsock.close()\n" +" wsock.close()\n" +" loop.close()" +msgstr "" +"import asyncio\n" +"from socket import socketpair\n" +"\n" +"# 建立一對連接的檔案描述器\n" +"rsock, wsock = socketpair()\n" +"\n" +"loop = asyncio.new_event_loop()\n" +"\n" +"def reader():\n" +" data = rsock.recv(100)\n" +" print(\"Received:\", data.decode())\n" +"\n" +" # 我們完成了：註銷檔案描述器\n" +" loop.remove_reader(rsock)\n" +"\n" +" # 停止事件迴圈\n" +" loop.stop()\n" +"\n" +"# 為讀取事件註冊檔案描述器\n" +"loop.add_reader(rsock, reader)\n" +"\n" +"# 模擬從網路接收資料\n" +"loop.call_soon(wsock.send, 'abc'.encode())\n" +"\n" +"try:\n" +" # 運行事件迴圈\n" +" loop.run_forever()\n" +"finally:\n" +" # 我們完成了。關閉 socket 和事件迴圈。\n" +" rsock.close()\n" +" wsock.close()\n" +" loop.close()" + +#: ../../library/asyncio-eventloop.rst:2041 +msgid "" +"A similar :ref:`example ` using " +"transports, protocols, and the :meth:`loop.create_connection` method." +msgstr "" +"使用傳輸、協定和 :meth:`loop.create_connection` 方法的類似 :ref:`範例 " +"`。" + +#: ../../library/asyncio-eventloop.rst:2045 +msgid "" +"Another similar :ref:`example ` " +"using the high-level :func:`asyncio.open_connection` function and streams." +msgstr "" +"另一個使用高階 :func:`asyncio.open_connection` 函式和串流的類似 :ref:`範例 " +"`。" + +#: ../../library/asyncio-eventloop.rst:2053 +msgid "Set signal handlers for SIGINT and SIGTERM" +msgstr "設定 SIGINT 和 SIGTERM 的訊號處理程式" + +#: ../../library/asyncio-eventloop.rst:2055 +msgid "(This ``signals`` example only works on Unix.)" +msgstr "（此 ``signals`` 範例僅在 Unix 上運作。）" + +#: ../../library/asyncio-eventloop.rst:2057 +msgid "" +"Register handlers for signals :const:`~signal.SIGINT` and :const:`~signal." +"SIGTERM` using the :meth:`loop.add_signal_handler` method::" +msgstr "" +"使用 :meth:`loop.add_signal_handler` 方法註冊訊號 :const:`~signal.SIGINT` 和 :const:`~signal." +"SIGTERM` 的處理程式： ::" + +#: ../../library/asyncio-eventloop.rst:2060 +msgid "" +"import asyncio\n" +"import functools\n" +"import os\n" +"import signal\n" +"\n" +"def ask_exit(signame, loop):\n" +" print(\"got signal %s: exit\" % signame)\n" +" loop.stop()\n" +"\n" +"async def main():\n" +" loop = asyncio.get_running_loop()\n" +"\n" +" for signame in {'SIGINT', 'SIGTERM'}:\n" +" loop.add_signal_handler(\n" +" getattr(signal, signame),\n" +" functools.partial(ask_exit, signame, loop))\n" +"\n" +" await asyncio.sleep(3600)\n" +"\n" +"print(\"Event loop running for 1 hour, press Ctrl+C to interrupt.\")\n" +"print(f\"pid {os.getpid()}: send SIGINT or SIGTERM to exit.\")\n" +"\n" +"asyncio.run(main())" +msgstr "" +"import asyncio\n" +"import functools\n" +"import os\n" +"import signal\n" +"\n" +"def ask_exit(signame, loop):\n" +" print(\"got signal %s: exit\" % signame)\n" +" loop.stop()\n" +"\n" +"async def main():\n" +" loop = asyncio.get_running_loop()\n" +"\n" +" for signame in {'SIGINT', 'SIGTERM'}:\n" +" loop.add_signal_handler(\n" +" getattr(signal, signame),\n" +" functools.partial(ask_exit, signame, loop))\n" +"\n" +" await asyncio.sleep(3600)\n" +"\n" +"print(\"Event loop running for 1 hour, press Ctrl+C to interrupt.\")\n" +"print(f\"pid {os.getpid()}: send SIGINT or SIGTERM to exit.\")\n" +"\n" +"asyncio.run(main())" + +#~ msgid "" +#~ "Deprecation warning is emitted if there is no current event loop. In some " +#~ "future Python release this will become an error." +#~ msgstr "" +#~ "如果沒有目前事件迴圈，則會發出棄用警告。在未來的某個 Python 發行版中，這將" +#~ "變成錯誤。" + +#~ msgid "" +#~ "import asyncio\n" +#~ "import selectors\n" +#~ "\n" +#~ "class MyPolicy(asyncio.DefaultEventLoopPolicy):\n" +#~ " def new_event_loop(self):\n" +#~ " selector = selectors.SelectSelector()\n" +#~ " return asyncio.SelectorEventLoop(selector)\n" +#~ "\n" +#~ "asyncio.set_event_loop_policy(MyPolicy())" +#~ msgstr "" +#~ "import asyncio\n" +#~ "import selectors\n" +#~ "\n" +#~ "class MyPolicy(asyncio.DefaultEventLoopPolicy):\n" +#~ " def new_event_loop(self):\n" +#~ " selector = selectors.SelectSelector()\n" +#~ " return asyncio.SelectorEventLoop(selector)\n" +#~ "\n" +#~ "asyncio.set_event_loop_policy(MyPolicy())" diff --git a/library/asyncio-exceptions.po b/library/asyncio-exceptions.po index ddcb5a4f75..d6c5cc7ab4 100644 --- a/library/asyncio-exceptions.po +++ b/library/asyncio-exceptions.po @@ -1,112 +1,112 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Matt Wang , 2022 -# -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2023-07-06 00:19+0000\n" -"PO-Revision-Date: 2022-01-31 21:41+0800\n" -"Last-Translator: Matt Wang \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" -"X-Generator: Poedit 3.0.1\n" - -#: ../../library/asyncio-exceptions.rst:8 -msgid "Exceptions" -msgstr "例外" - -#: ../../library/asyncio-exceptions.rst:10 -msgid "**Source code:** :source:`Lib/asyncio/exceptions.py`" -msgstr "**原始碼：**\\ :source:`Lib/asyncio/exceptions.py`" - -#: ../../library/asyncio-exceptions.rst:16 -msgid "" -"A deprecated alias of :exc:`TimeoutError`, raised when the operation has " -"exceeded the given deadline." -msgstr "" -":exc:`TimeoutError` 的一個已被棄用的別名，當操作已超過規定的截止時間時被引" -"發。" - -#: ../../library/asyncio-exceptions.rst:21 -msgid "This class was made an alias of :exc:`TimeoutError`." -msgstr "此 class 是 :exc:`TimeoutError` 的一個別名。" - -#: ../../library/asyncio-exceptions.rst:26 -msgid "The operation has been cancelled." -msgstr "該操作已被取消。" - -#: ../../library/asyncio-exceptions.rst:28 -msgid "" -"This exception can be caught to perform custom operations when asyncio Tasks " -"are cancelled. In almost all situations the exception must be re-raised." -msgstr "" -"當 asyncio Task 被取消時，可以捕獲此例外以執行客製化操作。在幾乎所有情況下，" -"該例外必須重新被引發。" - -#: ../../library/asyncio-exceptions.rst:34 -msgid "" -":exc:`CancelledError` is now a subclass of :class:`BaseException` rather " -"than :class:`Exception`." -msgstr "" -":exc:`CancelledError` 現在是 :class:`BaseException` 而非 :class:`Exception` " -"的子類別。" - -#: ../../library/asyncio-exceptions.rst:39 -msgid "Invalid internal state of :class:`Task` or :class:`Future`." -msgstr ":class:`Task` 或 :class:`Future` 的無效內部狀態。" - -#: ../../library/asyncio-exceptions.rst:41 -msgid "" -"Can be raised in situations like setting a result value for a *Future* " -"object that already has a result value set." -msgstr "可以在像是為已設定結果值的 *Future* 物件設定結果值的情況下引發。" - -#: ../../library/asyncio-exceptions.rst:47 -msgid "" -"The \"sendfile\" syscall is not available for the given socket or file type." -msgstr "\"sendfile\" 系統呼叫不適用於給定的 socket 或檔案型別。" - -#: ../../library/asyncio-exceptions.rst:50 -msgid "A subclass of :exc:`RuntimeError`." -msgstr "一個 :exc:`RuntimeError` 的子類別。" - -#: ../../library/asyncio-exceptions.rst:55 -msgid "The requested read operation did not complete fully." -msgstr "請求的讀取操作未全部完成。" - -#: ../../library/asyncio-exceptions.rst:57 -msgid "Raised by the :ref:`asyncio stream APIs`." -msgstr "由 :ref:`asyncio 串流 APIs ` 引發。" - -#: ../../library/asyncio-exceptions.rst:59 -msgid "This exception is a subclass of :exc:`EOFError`." -msgstr "此例外是 :exc:`EOFError` 的子類別。" - -#: ../../library/asyncio-exceptions.rst:63 -msgid "The total number (:class:`int`) of expected bytes." -msgstr "預期的位元組總數 (\\ :class:`int`\\ )。" - -#: ../../library/asyncio-exceptions.rst:67 -msgid "A string of :class:`bytes` read before the end of stream was reached." -msgstr "串流結束之前讀取的 :class:`bytes` 字串。" - -#: ../../library/asyncio-exceptions.rst:72 -msgid "Reached the buffer size limit while looking for a separator." -msgstr "在查詢分隔符號 (separator) 時達到緩衝區 (buffer) 大小限制。" - -#: ../../library/asyncio-exceptions.rst:74 -msgid "Raised by the :ref:`asyncio stream APIs `." -msgstr "由 :ref:`asyncio 串流 APIs ` 引發。" - -#: ../../library/asyncio-exceptions.rst:78 -msgid "The total number of to be consumed bytes." -msgstr "要消耗的位元組總數。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Matt Wang , 2022 +# +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-07-06 00:19+0000\n" +"PO-Revision-Date: 2022-01-31 21:41+0800\n" +"Last-Translator: Matt Wang \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" +"X-Generator: Poedit 3.0.1\n" + +#: ../../library/asyncio-exceptions.rst:8 +msgid "Exceptions" +msgstr "例外" + +#: ../../library/asyncio-exceptions.rst:10 +msgid "**Source code:** :source:`Lib/asyncio/exceptions.py`" +msgstr "**原始碼：**\\ :source:`Lib/asyncio/exceptions.py`" + +#: ../../library/asyncio-exceptions.rst:16 +msgid "" +"A deprecated alias of :exc:`TimeoutError`, raised when the operation has " +"exceeded the given deadline." +msgstr "" +":exc:`TimeoutError` 的一個已被棄用的別名，當操作已超過規定的截止時間時被引" +"發。" + +#: ../../library/asyncio-exceptions.rst:21 +msgid "This class was made an alias of :exc:`TimeoutError`." +msgstr "此 class 是 :exc:`TimeoutError` 的一個別名。" + +#: ../../library/asyncio-exceptions.rst:26 +msgid "The operation has been cancelled." +msgstr "該操作已被取消。" + +#: ../../library/asyncio-exceptions.rst:28 +msgid "" +"This exception can be caught to perform custom operations when asyncio Tasks " +"are cancelled. In almost all situations the exception must be re-raised." +msgstr "" +"當 asyncio Task 被取消時，可以捕獲此例外以執行客製化操作。在幾乎所有情況下，" +"該例外必須重新被引發。" + +#: ../../library/asyncio-exceptions.rst:34 +msgid "" +":exc:`CancelledError` is now a subclass of :class:`BaseException` rather " +"than :class:`Exception`." +msgstr "" +":exc:`CancelledError` 現在是 :class:`BaseException` 而非 :class:`Exception` " +"的子類別。" + +#: ../../library/asyncio-exceptions.rst:39 +msgid "Invalid internal state of :class:`Task` or :class:`Future`." +msgstr ":class:`Task` 或 :class:`Future` 的無效內部狀態。" + +#: ../../library/asyncio-exceptions.rst:41 +msgid "" +"Can be raised in situations like setting a result value for a *Future* " +"object that already has a result value set." +msgstr "可以在像是為已設定結果值的 *Future* 物件設定結果值的情況下引發。" + +#: ../../library/asyncio-exceptions.rst:47 +msgid "" +"The \"sendfile\" syscall is not available for the given socket or file type." +msgstr "\"sendfile\" 系統呼叫不適用於給定的 socket 或檔案型別。" + +#: ../../library/asyncio-exceptions.rst:50 +msgid "A subclass of :exc:`RuntimeError`." +msgstr "一個 :exc:`RuntimeError` 的子類別。" + +#: ../../library/asyncio-exceptions.rst:55 +msgid "The requested read operation did not complete fully." +msgstr "請求的讀取操作未全部完成。" + +#: ../../library/asyncio-exceptions.rst:57 +msgid "Raised by the :ref:`asyncio stream APIs`." +msgstr "由 :ref:`asyncio 串流 APIs ` 引發。" + +#: ../../library/asyncio-exceptions.rst:59 +msgid "This exception is a subclass of :exc:`EOFError`." +msgstr "此例外是 :exc:`EOFError` 的子類別。" + +#: ../../library/asyncio-exceptions.rst:63 +msgid "The total number (:class:`int`) of expected bytes." +msgstr "預期的位元組總數 (\\ :class:`int`\\ )。" + +#: ../../library/asyncio-exceptions.rst:67 +msgid "A string of :class:`bytes` read before the end of stream was reached." +msgstr "串流結束之前讀取的 :class:`bytes` 字串。" + +#: ../../library/asyncio-exceptions.rst:72 +msgid "Reached the buffer size limit while looking for a separator." +msgstr "在查詢分隔符號 (separator) 時達到緩衝區 (buffer) 大小限制。" + +#: ../../library/asyncio-exceptions.rst:74 +msgid "Raised by the :ref:`asyncio stream APIs `." +msgstr "由 :ref:`asyncio 串流 APIs ` 引發。" + +#: ../../library/asyncio-exceptions.rst:78 +msgid "The total number of to be consumed bytes." +msgstr "要消耗的位元組總數。" diff --git a/library/asyncio-extending.po b/library/asyncio-extending.po index 1f8b54e078..348033118a 100644 --- a/library/asyncio-extending.po +++ b/library/asyncio-extending.po @@ -1,155 +1,155 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# FIRST AUTHOR , YEAR. -# -#, fuzzy -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2023-07-29 10:36+0000\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" -"tw)\n" -"Language: zh_TW\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=UTF-8\n" -"Content-Transfer-Encoding: 8bit\n" - -#: ../../library/asyncio-extending.rst:6 -msgid "Extending" -msgstr "擴充" - -#: ../../library/asyncio-extending.rst:8 -msgid "" -"The main direction for :mod:`asyncio` extending is writing custom *event " -"loop* classes. Asyncio has helpers that could be used to simplify this task." -msgstr "" - -#: ../../library/asyncio-extending.rst:13 -msgid "" -"Third-parties should reuse existing asyncio code with caution, a new Python " -"version is free to break backward compatibility in *internal* part of API." -msgstr "" - -#: ../../library/asyncio-extending.rst:19 -msgid "Writing a Custom Event Loop" -msgstr "" - -#: ../../library/asyncio-extending.rst:21 -msgid "" -":class:`asyncio.AbstractEventLoop` declares very many methods. Implementing " -"all them from scratch is a tedious job." -msgstr "" - -#: ../../library/asyncio-extending.rst:24 -msgid "" -"A loop can get many common methods implementation for free by inheriting " -"from :class:`asyncio.BaseEventLoop`." -msgstr "" - -#: ../../library/asyncio-extending.rst:27 -msgid "" -"In turn, the successor should implement a bunch of *private* methods " -"declared but not implemented in :class:`asyncio.BaseEventLoop`." -msgstr "" - -#: ../../library/asyncio-extending.rst:30 -msgid "" -"For example, ``loop.create_connection()`` checks arguments, resolves DNS " -"addresses, and calls ``loop._make_socket_transport()`` that should be " -"implemented by inherited class. The ``_make_socket_transport()`` method is " -"not documented and is considered as an *internal* API." -msgstr "" - -#: ../../library/asyncio-extending.rst:38 -msgid "Future and Task private constructors" -msgstr "" - -#: ../../library/asyncio-extending.rst:40 -msgid "" -":class:`asyncio.Future` and :class:`asyncio.Task` should be never created " -"directly, please use corresponding :meth:`loop.create_future` and :meth:" -"`loop.create_task`, or :func:`asyncio.create_task` factories instead." -msgstr "" - -#: ../../library/asyncio-extending.rst:44 -msgid "" -"However, third-party *event loops* may *reuse* built-in future and task " -"implementations for the sake of getting a complex and highly optimized code " -"for free." -msgstr "" - -#: ../../library/asyncio-extending.rst:47 -msgid "For this purpose the following, *private* constructors are listed:" -msgstr "" - -#: ../../library/asyncio-extending.rst:51 -msgid "Create a built-in future instance." -msgstr "" - -#: ../../library/asyncio-extending.rst:53 -msgid "*loop* is an optional event loop instance." -msgstr "" - -#: ../../library/asyncio-extending.rst:57 -msgid "Create a built-in task instance." -msgstr "" - -#: ../../library/asyncio-extending.rst:59 -msgid "" -"*loop* is an optional event loop instance. The rest of arguments are " -"described in :meth:`loop.create_task` description." -msgstr "" - -#: ../../library/asyncio-extending.rst:64 -msgid "*context* argument is added." -msgstr "" - -#: ../../library/asyncio-extending.rst:69 -msgid "Task lifetime support" -msgstr "" - -#: ../../library/asyncio-extending.rst:71 -msgid "" -"A third party task implementation should call the following functions to " -"keep a task visible by :func:`asyncio.all_tasks` and :func:`asyncio." -"current_task`:" -msgstr "" - -#: ../../library/asyncio-extending.rst:76 -msgid "Register a new *task* as managed by *asyncio*." -msgstr "" - -#: ../../library/asyncio-extending.rst:78 -msgid "Call the function from a task constructor." -msgstr "" - -#: ../../library/asyncio-extending.rst:82 -msgid "Unregister a *task* from *asyncio* internal structures." -msgstr "" - -#: ../../library/asyncio-extending.rst:84 -msgid "The function should be called when a task is about to finish." -msgstr "" - -#: ../../library/asyncio-extending.rst:88 -msgid "Switch the current task to the *task* argument." -msgstr "" - -#: ../../library/asyncio-extending.rst:90 -msgid "" -"Call the function just before executing a portion of embedded *coroutine* (:" -"meth:`coroutine.send` or :meth:`coroutine.throw`)." -msgstr "" - -#: ../../library/asyncio-extending.rst:95 -msgid "Switch the current task back from *task* to ``None``." -msgstr "" - -#: ../../library/asyncio-extending.rst:97 -msgid "" -"Call the function just after :meth:`coroutine.send` or :meth:`coroutine." -"throw` execution." -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-07-29 10:36+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" +"tw)\n" +"Language: zh_TW\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../library/asyncio-extending.rst:6 +msgid "Extending" +msgstr "擴充" + +#: ../../library/asyncio-extending.rst:8 +msgid "" +"The main direction for :mod:`asyncio` extending is writing custom *event " +"loop* classes. Asyncio has helpers that could be used to simplify this task." +msgstr "" + +#: ../../library/asyncio-extending.rst:13 +msgid "" +"Third-parties should reuse existing asyncio code with caution, a new Python " +"version is free to break backward compatibility in *internal* part of API." +msgstr "" + +#: ../../library/asyncio-extending.rst:19 +msgid "Writing a Custom Event Loop" +msgstr "" + +#: ../../library/asyncio-extending.rst:21 +msgid "" +":class:`asyncio.AbstractEventLoop` declares very many methods. Implementing " +"all them from scratch is a tedious job." +msgstr "" + +#: ../../library/asyncio-extending.rst:24 +msgid "" +"A loop can get many common methods implementation for free by inheriting " +"from :class:`asyncio.BaseEventLoop`." +msgstr "" + +#: ../../library/asyncio-extending.rst:27 +msgid "" +"In turn, the successor should implement a bunch of *private* methods " +"declared but not implemented in :class:`asyncio.BaseEventLoop`." +msgstr "" + +#: ../../library/asyncio-extending.rst:30 +msgid "" +"For example, ``loop.create_connection()`` checks arguments, resolves DNS " +"addresses, and calls ``loop._make_socket_transport()`` that should be " +"implemented by inherited class. The ``_make_socket_transport()`` method is " +"not documented and is considered as an *internal* API." +msgstr "" + +#: ../../library/asyncio-extending.rst:38 +msgid "Future and Task private constructors" +msgstr "" + +#: ../../library/asyncio-extending.rst:40 +msgid "" +":class:`asyncio.Future` and :class:`asyncio.Task` should be never created " +"directly, please use corresponding :meth:`loop.create_future` and :meth:" +"`loop.create_task`, or :func:`asyncio.create_task` factories instead." +msgstr "" + +#: ../../library/asyncio-extending.rst:44 +msgid "" +"However, third-party *event loops* may *reuse* built-in future and task " +"implementations for the sake of getting a complex and highly optimized code " +"for free." +msgstr "" + +#: ../../library/asyncio-extending.rst:47 +msgid "For this purpose the following, *private* constructors are listed:" +msgstr "" + +#: ../../library/asyncio-extending.rst:51 +msgid "Create a built-in future instance." +msgstr "" + +#: ../../library/asyncio-extending.rst:53 +msgid "*loop* is an optional event loop instance." +msgstr "" + +#: ../../library/asyncio-extending.rst:57 +msgid "Create a built-in task instance." +msgstr "" + +#: ../../library/asyncio-extending.rst:59 +msgid "" +"*loop* is an optional event loop instance. The rest of arguments are " +"described in :meth:`loop.create_task` description." +msgstr "" + +#: ../../library/asyncio-extending.rst:64 +msgid "*context* argument is added." +msgstr "" + +#: ../../library/asyncio-extending.rst:69 +msgid "Task lifetime support" +msgstr "" + +#: ../../library/asyncio-extending.rst:71 +msgid "" +"A third party task implementation should call the following functions to " +"keep a task visible by :func:`asyncio.all_tasks` and :func:`asyncio." +"current_task`:" +msgstr "" + +#: ../../library/asyncio-extending.rst:76 +msgid "Register a new *task* as managed by *asyncio*." +msgstr "" + +#: ../../library/asyncio-extending.rst:78 +msgid "Call the function from a task constructor." +msgstr "" + +#: ../../library/asyncio-extending.rst:82 +msgid "Unregister a *task* from *asyncio* internal structures." +msgstr "" + +#: ../../library/asyncio-extending.rst:84 +msgid "The function should be called when a task is about to finish." +msgstr "" + +#: ../../library/asyncio-extending.rst:88 +msgid "Switch the current task to the *task* argument." +msgstr "" + +#: ../../library/asyncio-extending.rst:90 +msgid "" +"Call the function just before executing a portion of embedded *coroutine* (:" +"meth:`coroutine.send` or :meth:`coroutine.throw`)." +msgstr "" + +#: ../../library/asyncio-extending.rst:95 +msgid "Switch the current task back from *task* to ``None``." +msgstr "" + +#: ../../library/asyncio-extending.rst:97 +msgid "" +"Call the function just after :meth:`coroutine.send` or :meth:`coroutine." +"throw` execution." +msgstr "" diff --git a/library/asyncio-future.po b/library/asyncio-future.po index c2812e4b70..ca175b2afe 100644 --- a/library/asyncio-future.po +++ b/library/asyncio-future.po @@ -1,456 +1,456 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Matt Wang , 2022 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: 2022-01-25 01:29+0800\n" -"Last-Translator: Matt Wang \n" -"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" -"tw)\n" -"Language: zh_TW\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=UTF-8\n" -"Content-Transfer-Encoding: 8bit\n" -"X-Generator: Poedit 3.0.1\n" - -#: ../../library/asyncio-future.rst:8 -msgid "Futures" -msgstr "Futures" - -#: ../../library/asyncio-future.rst:10 -msgid "" -"**Source code:** :source:`Lib/asyncio/futures.py`, :source:`Lib/asyncio/" -"base_futures.py`" -msgstr "" -"**原始碼：**\\ :source:`Lib/asyncio/futures.py、source:`Lib/asyncio/" -"base_futures.py`" - -#: ../../library/asyncio-future.rst:15 -msgid "" -"*Future* objects are used to bridge **low-level callback-based code** with " -"high-level async/await code." -msgstr "" -"*Future* 物件被用來連結\\ **低階回呼式程式**\\ 和高階 async/await 程式。" - -#: ../../library/asyncio-future.rst:20 -msgid "Future Functions" -msgstr "Future 函式" - -#: ../../library/asyncio-future.rst:24 -msgid "Return ``True`` if *obj* is either of:" -msgstr "如果 *obj* 為下面任意物件，回傳 ``True``：" - -#: ../../library/asyncio-future.rst:26 -msgid "an instance of :class:`asyncio.Future`," -msgstr "一個 :class:`asyncio.Future` 的實例、" - -#: ../../library/asyncio-future.rst:27 -msgid "an instance of :class:`asyncio.Task`," -msgstr "一個 :class:`asyncio.Task` 的實例、" - -#: ../../library/asyncio-future.rst:28 -msgid "a Future-like object with a ``_asyncio_future_blocking`` attribute." -msgstr "" -"帶有 ``_asyncio_future_blocking`` 屬性的類 Future 物件 (Future-like object)。" - -#: ../../library/asyncio-future.rst:36 -msgid "Return:" -msgstr "回傳：" - -#: ../../library/asyncio-future.rst:38 -msgid "" -"*obj* argument as is, if *obj* is a :class:`Future`, a :class:`Task`, or a " -"Future-like object (:func:`isfuture` is used for the test.)" -msgstr "" -"*obj* 引數會保持原樣，*obj* 須為 :class:`Future`、:class:`Task` 或類 Future " -"物件（可以用 :func:`isfuture` 來進行檢查。）" - -#: ../../library/asyncio-future.rst:42 -msgid "" -"a :class:`Task` object wrapping *obj*, if *obj* is a coroutine " -"(:func:`iscoroutine` is used for the test); in this case the coroutine will " -"be scheduled by ``ensure_future()``." -msgstr "" -"包裝 (wrap) 了 *obj* 的 :class:`Task` 物件，如果 *obj* 是一個協程 " -"(coroutine) (可以用 :func:`iscoroutine` 來進行檢查)；在此情況下該協程將透過 " -"``ensure_future()`` 來排程。" - -#: ../../library/asyncio-future.rst:47 -msgid "" -"a :class:`Task` object that would await on *obj*, if *obj* is an awaitable " -"(:func:`inspect.isawaitable` is used for the test.)" -msgstr "" -"一個會等待 *obj* 的 :class:`Task` 物件，*obj* 須為一個可等待物件" -"（\\ :func:`inspect.isawaitable` 用於測試。)" - -#: ../../library/asyncio-future.rst:50 -msgid "If *obj* is neither of the above a :exc:`TypeError` is raised." -msgstr "如果 *obj* 不是上述物件的話會引發一個 :exc:`TypeError` 例外。" - -#: ../../library/asyncio-future.rst:54 -msgid "" -"Save a reference to the result of this function, to avoid a task " -"disappearing mid-execution." -msgstr "將參照 (reference) 儲存至此函式的結果，用以防止任務在執行中消失。" - -#: ../../library/asyncio-future.rst:57 -msgid "" -"See also the :func:`create_task` function which is the preferred way for " -"creating new tasks or use :class:`asyncio.TaskGroup` which keeps reference " -"to the task internally." -msgstr "請見 :func:`create_task` 函式，它是建立新 Task 的推薦方法。或者使用 " -":class:`asyncio.TaskGroup`，它會在內部保留對 Task 的參照。" - -#: ../../library/asyncio-future.rst:61 -msgid "The function accepts any :term:`awaitable` object." -msgstr "這個函式接受任意 :term:`awaitable` 物件。" - -#: ../../library/asyncio-future.rst:64 -msgid "" -"Deprecation warning is emitted if *obj* is not a Future-like object and " -"*loop* is not specified and there is no running event loop." -msgstr "" -"如果 *obj* 不是類 Future 物件且 *loop* 並未被指定，同時沒有正在執行的事件迴" -"圈 (event loop)，則會發出棄用警告。" - -#: ../../library/asyncio-future.rst:71 -msgid "" -"Wrap a :class:`concurrent.futures.Future` object in " -"a :class:`asyncio.Future` object." -msgstr "" -"將一個 :class:`concurrent.futures.Future` 物件包裝到 :class:`asyncio.Future` " -"物件中。" - -#: ../../library/asyncio-future.rst:74 -msgid "" -"Deprecation warning is emitted if *future* is not a Future-like object and " -"*loop* is not specified and there is no running event loop." -msgstr "" -"如果 *future* 不是類 Future 物件且 *loop* 未被指定，同時沒有正在執行的事件迴" -"圈，則會發出棄用警告。" - -#: ../../library/asyncio-future.rst:81 -msgid "Future Object" -msgstr "Future 物件" - -#: ../../library/asyncio-future.rst:85 -msgid "" -"A Future represents an eventual result of an asynchronous operation. Not " -"thread-safe." -msgstr "" -"一個 Future 代表一個非同步運算的最終結果。並不支援執行緒安全 (thread-safe)。" - -#: ../../library/asyncio-future.rst:88 -msgid "" -"Future is an :term:`awaitable` object. Coroutines can await on Future " -"objects until they either have a result or an exception set, or until they " -"are cancelled. A Future can be awaited multiple times and the result is same." -msgstr "" -"Future 是一個 :term:`awaitable` 物件。協程可以等待 Future 物件直到它們有結果" -"或例外被設置、或者被取消。一個 Future 可被多次等待而結果都會是相同的。" - -#: ../../library/asyncio-future.rst:93 -msgid "" -"Typically Futures are used to enable low-level callback-based code (e.g. in " -"protocols implemented using asyncio :ref:`transports `) to interoperate with high-level async/await code." -msgstr "" -"Future 通常用於讓低階基於回呼的程式（例如在協定實作中使用 " -"asyncio :ref:`transports `\\ ）能夠與高階 " -"async/await 程式互動。" - -#: ../../library/asyncio-future.rst:98 -msgid "" -"The rule of thumb is to never expose Future objects in user-facing APIs, and " -"the recommended way to create a Future object is to " -"call :meth:`loop.create_future`. This way alternative event loop " -"implementations can inject their own optimized implementations of a Future " -"object." -msgstr "" -"經驗法則為永遠不要在提供給使用者的 API 中公開 Future 物件，同時建議使" -"用 :meth:`loop.create_future` 來建立 Future 物件。如此一來，不同實作的事件迴" -"圈可以注入自己最佳化實作的 Future 物件。" - -#: ../../library/asyncio-future.rst:104 -msgid "Added support for the :mod:`contextvars` module." -msgstr "加入對 :mod:`contextvars` 模組的支援。" - -#: ../../library/asyncio-future.rst:107 -msgid "" -"Deprecation warning is emitted if *loop* is not specified and there is no " -"running event loop." -msgstr "如果未指定 *loop* 並且沒有正在執行的事件迴圈則會發出棄用警告。" - -#: ../../library/asyncio-future.rst:113 -msgid "Return the result of the Future." -msgstr "回傳 Future 的結果。" - -#: ../../library/asyncio-future.rst:115 -msgid "" -"If the Future is *done* and has a result set by the :meth:`set_result` " -"method, the result value is returned." -msgstr "" -"如果 Future 狀態為 *done*\\ （完成），並擁有 :meth:`set_result` 方法設定的一" -"個結果，則回傳該結果之值。" - -#: ../../library/asyncio-future.rst:118 -msgid "" -"If the Future is *done* and has an exception set by " -"the :meth:`set_exception` method, this method raises the exception." -msgstr "" -"如果 Future 狀態為 *done*，並擁有 :meth:`set_exception` 方法設定的一個例外，" -"那麼這個方法會引發該例外。" - -#: ../../library/asyncio-future.rst:121 ../../library/asyncio-future.rst:209 -msgid "" -"If the Future has been *cancelled*, this method raises " -"a :exc:`CancelledError` exception." -msgstr "" -"如果 Future 已被 *cancelled*\\ （取消），此方法會引發一" -"個 :exc:`CancelledError` 例外。" - -#: ../../library/asyncio-future.rst:124 -msgid "" -"If the Future's result isn't yet available, this method raises " -"an :exc:`InvalidStateError` exception." -msgstr "" -"如果 Future 的結果還不可用，此方法會引發一個 :exc:`InvalidStateError` 例外。" - -#: ../../library/asyncio-future.rst:129 -msgid "Mark the Future as *done* and set its result." -msgstr "將 Future 標記為 *done* 並設定其結果。" - -#: ../../library/asyncio-future.rst:131 ../../library/asyncio-future.rst:138 -msgid "" -"Raises an :exc:`InvalidStateError` error if the Future is already *done*." -msgstr "如果 Future 已經 *done* 則引發一個 :exc:`InvalidStateError` 錯誤。" - -#: ../../library/asyncio-future.rst:136 -msgid "Mark the Future as *done* and set an exception." -msgstr "將 Future 標記為 *done* 並設定一個例外。" - -#: ../../library/asyncio-future.rst:143 -msgid "Return ``True`` if the Future is *done*." -msgstr "如果 Future 已為 *done* 則回傳 ``True``。" - -#: ../../library/asyncio-future.rst:145 -msgid "" -"A Future is *done* if it was *cancelled* or if it has a result or an " -"exception set with :meth:`set_result` or :meth:`set_exception` calls." -msgstr "" -"如果 Future 有被 *cancelled*、:meth:`set_result` 有被呼叫來為其設定結果、" -"或 :meth:`set_exception` 有被呼叫為其設定例外，那麼它就是 *done*。" - -#: ../../library/asyncio-future.rst:151 -msgid "Return ``True`` if the Future was *cancelled*." -msgstr "如果 Future 已經被 *cancelled* 則回傳 ``True``。" - -#: ../../library/asyncio-future.rst:153 -msgid "" -"The method is usually used to check if a Future is not *cancelled* before " -"setting a result or an exception for it::" -msgstr "" -"這個方法通常在為 Future 設定結果或例外前用來確認它還沒被 *cancelled*： ::" - -#: ../../library/asyncio-future.rst:156 -msgid "" -"if not fut.cancelled():\n" -" fut.set_result(42)" -msgstr "" -"if not fut.cancelled():\n" -" fut.set_result(42)" - -#: ../../library/asyncio-future.rst:161 -msgid "Add a callback to be run when the Future is *done*." -msgstr "新增一個在 Future 為 *done* 時執行的回呼函式。" - -#: ../../library/asyncio-future.rst:163 -msgid "The *callback* is called with the Future object as its only argument." -msgstr "呼叫 *callback* 並附帶做為唯一引數的 Future 物件。" - -#: ../../library/asyncio-future.rst:166 -msgid "" -"If the Future is already *done* when this method is called, the callback is " -"scheduled with :meth:`loop.call_soon`." -msgstr "" -"如果呼叫這個方法時 Future 已經為 *done*，回呼函式會被 :meth:`loop.call_soon` " -"排程。" - -#: ../../library/asyncio-future.rst:169 -msgid "" -"An optional keyword-only *context* argument allows specifying a " -"custom :class:`contextvars.Context` for the *callback* to run in. The " -"current context is used when no *context* is provided." -msgstr "" -"可選僅限關鍵字引數 *context* 用來指定一個讓 *callback* 執行於其中的客製" -"化 :class:`contextvars.Context` 物件。如果沒有提供 *context*，則使用目前情" -"境。" - -#: ../../library/asyncio-future.rst:173 -msgid "" -":func:`functools.partial` can be used to pass parameters to the callback, " -"e.g.::" -msgstr "可以用 :func:`functools.partial` 傳遞引數給回呼函式，例如： ::" - -#: ../../library/asyncio-future.rst:176 -msgid "" -"# Call 'print(\"Future:\", fut)' when \"fut\" is done.\n" -"fut.add_done_callback(\n" -" functools.partial(print, \"Future:\"))" -msgstr "" - -#: ../../library/asyncio-future.rst:180 -msgid "" -"The *context* keyword-only parameter was added. See :pep:`567` for more " -"details." -msgstr "加入僅限關鍵字參數 *context*。更多細節請參閱 :pep:`567`。" - -#: ../../library/asyncio-future.rst:186 -msgid "Remove *callback* from the callbacks list." -msgstr "從回呼列表中移除 *callback*。" - -#: ../../library/asyncio-future.rst:188 -msgid "" -"Returns the number of callbacks removed, which is typically 1, unless a " -"callback was added more than once." -msgstr "回傳被移除的回呼函式數量，通常為 1，除非一個回呼函式被多次加入。" - -#: ../../library/asyncio-future.rst:193 -msgid "Cancel the Future and schedule callbacks." -msgstr "取消 Future 並為回呼函式排程。" - -#: ../../library/asyncio-future.rst:195 -msgid "" -"If the Future is already *done* or *cancelled*, return ``False``. Otherwise, " -"change the Future's state to *cancelled*, schedule the callbacks, and return " -"``True``." -msgstr "" -"如果 Future 已經是 *done* 或 *cancelled*，回傳 ``False``。否則將 Future 狀態" -"改為 *cancelled* 並在為回呼函式排程後回傳 ``True``。" - -#: ../../library/asyncio-future.rst:199 -msgid "Added the *msg* parameter." -msgstr "新增 *msg* 參數。" - -#: ../../library/asyncio-future.rst:204 -msgid "Return the exception that was set on this Future." -msgstr "回傳被設定於此 Future 的例外。" - -#: ../../library/asyncio-future.rst:206 -msgid "" -"The exception (or ``None`` if no exception was set) is returned only if the " -"Future is *done*." -msgstr "" -"只有 Future 在 *done* 時才回傳例外（如果沒有設定例外則回傳 ``None``\\ ）。" - -#: ../../library/asyncio-future.rst:212 -msgid "" -"If the Future isn't *done* yet, this method raises " -"an :exc:`InvalidStateError` exception." -msgstr "" -"如果 Future 還不為 *done*，此方法會引發一個 :exc:`InvalidStateError` 例外。" - -#: ../../library/asyncio-future.rst:217 -msgid "Return the event loop the Future object is bound to." -msgstr "回傳已被 Future 物件繫結 (bind) 的事件迴圈。" - -#: ../../library/asyncio-future.rst:224 -msgid "" -"This example creates a Future object, creates and schedules an asynchronous " -"Task to set result for the Future, and waits until the Future has a result::" -msgstr "" -"這個例子建立一個 Future 物件，建立一個非同步 Task 並為其排程以設定 Future 結" -"果，然後等待 Future 結果出現： ::" - -#: ../../library/asyncio-future.rst:228 -msgid "" -"async def set_after(fut, delay, value):\n" -" # Sleep for *delay* seconds.\n" -" await asyncio.sleep(delay)\n" -"\n" -" # Set *value* as a result of *fut* Future.\n" -" fut.set_result(value)\n" -"\n" -"async def main():\n" -" # Get the current event loop.\n" -" loop = asyncio.get_running_loop()\n" -"\n" -" # Create a new Future object.\n" -" fut = loop.create_future()\n" -"\n" -" # Run \"set_after()\" coroutine in a parallel Task.\n" -" # We are using the low-level \"loop.create_task()\" API here because\n" -" # we already have a reference to the event loop at hand.\n" -" # Otherwise we could have just used \"asyncio.create_task()\".\n" -" loop.create_task(\n" -" set_after(fut, 1, '... world'))\n" -"\n" -" print('hello ...')\n" -"\n" -" # Wait until *fut* has a result (1 second) and print it.\n" -" print(await fut)\n" -"\n" -"asyncio.run(main())" -msgstr "" - -#: ../../library/asyncio-future.rst:259 -msgid "" -"The Future object was designed to mimic :class:`concurrent.futures.Future`. " -"Key differences include:" -msgstr "" -"該 Future 物件是為了模仿 :class:`concurrent.futures.Future` 而設計。主要差異" -"包含：" - -#: ../../library/asyncio-future.rst:262 -msgid "" -"unlike asyncio Futures, :class:`concurrent.futures.Future` instances cannot " -"be awaited." -msgstr "" -"與 asyncio 的 Future 不同，:class:`concurrent.futures.Future` 實例不可被等" -"待。" - -#: ../../library/asyncio-future.rst:265 -msgid "" -":meth:`asyncio.Future.result` and :meth:`asyncio.Future.exception` do not " -"accept the *timeout* argument." -msgstr "" -":meth:`asyncio.Future.result` 和 :meth:`asyncio.Future.exception` 不接受 " -"*timeout* 引數。" - -#: ../../library/asyncio-future.rst:268 -msgid "" -":meth:`asyncio.Future.result` and :meth:`asyncio.Future.exception` raise " -"an :exc:`InvalidStateError` exception when the Future is not *done*." -msgstr "" -"Future 不為 *done* 時 :meth:`asyncio.Future.result` " -"和 :meth:`asyncio.Future.exception` 會引發一個 :exc:`InvalidStateError` 例" -"外。" - -#: ../../library/asyncio-future.rst:272 -msgid "" -"Callbacks registered with :meth:`asyncio.Future.add_done_callback` are not " -"called immediately. They are scheduled with :meth:`loop.call_soon` instead." -msgstr "" -"使用 :meth:`asyncio.Future.add_done_callback` 註冊的回呼函式不會立即呼叫，而" -"是被 :meth:`loop.call_soon` 排程。" - -#: ../../library/asyncio-future.rst:276 -msgid "" -"asyncio Future is not compatible with the :func:`concurrent.futures.wait` " -"and :func:`concurrent.futures.as_completed` functions." -msgstr "" -"asyncio Future 不能與 :func:`concurrent.futures.wait` " -"和 :func:`concurrent.futures.as_completed` 函式相容。" - -#: ../../library/asyncio-future.rst:280 -msgid "" -":meth:`asyncio.Future.cancel` accepts an optional ``msg`` argument, " -"but :meth:`concurrent.futures.Future.cancel` does not." -msgstr "" -":meth:`asyncio.Future.cancel` 接受一個可選的 ``msg`` 引數，" -"但 :func:`concurrent.futures.Future.cancel` 無此引數。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Matt Wang , 2022 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: 2022-01-25 01:29+0800\n" +"Last-Translator: Matt Wang \n" +"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" +"tw)\n" +"Language: zh_TW\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"X-Generator: Poedit 3.0.1\n" + +#: ../../library/asyncio-future.rst:8 +msgid "Futures" +msgstr "Futures" + +#: ../../library/asyncio-future.rst:10 +msgid "" +"**Source code:** :source:`Lib/asyncio/futures.py`, :source:`Lib/asyncio/" +"base_futures.py`" +msgstr "" +"**原始碼：**\\ :source:`Lib/asyncio/futures.py、source:`Lib/asyncio/" +"base_futures.py`" + +#: ../../library/asyncio-future.rst:15 +msgid "" +"*Future* objects are used to bridge **low-level callback-based code** with " +"high-level async/await code." +msgstr "" +"*Future* 物件被用來連結\\ **低階回呼式程式**\\ 和高階 async/await 程式。" + +#: ../../library/asyncio-future.rst:20 +msgid "Future Functions" +msgstr "Future 函式" + +#: ../../library/asyncio-future.rst:24 +msgid "Return ``True`` if *obj* is either of:" +msgstr "如果 *obj* 為下面任意物件，回傳 ``True``：" + +#: ../../library/asyncio-future.rst:26 +msgid "an instance of :class:`asyncio.Future`," +msgstr "一個 :class:`asyncio.Future` 的實例、" + +#: ../../library/asyncio-future.rst:27 +msgid "an instance of :class:`asyncio.Task`," +msgstr "一個 :class:`asyncio.Task` 的實例、" + +#: ../../library/asyncio-future.rst:28 +msgid "a Future-like object with a ``_asyncio_future_blocking`` attribute." +msgstr "" +"帶有 ``_asyncio_future_blocking`` 屬性的類 Future 物件 (Future-like object)。" + +#: ../../library/asyncio-future.rst:36 +msgid "Return:" +msgstr "回傳：" + +#: ../../library/asyncio-future.rst:38 +msgid "" +"*obj* argument as is, if *obj* is a :class:`Future`, a :class:`Task`, or a " +"Future-like object (:func:`isfuture` is used for the test.)" +msgstr "" +"*obj* 引數會保持原樣，*obj* 須為 :class:`Future`、:class:`Task` 或類 Future " +"物件（可以用 :func:`isfuture` 來進行檢查。）" + +#: ../../library/asyncio-future.rst:42 +msgid "" +"a :class:`Task` object wrapping *obj*, if *obj* is a coroutine " +"(:func:`iscoroutine` is used for the test); in this case the coroutine will " +"be scheduled by ``ensure_future()``." +msgstr "" +"包裝 (wrap) 了 *obj* 的 :class:`Task` 物件，如果 *obj* 是一個協程 " +"(coroutine) (可以用 :func:`iscoroutine` 來進行檢查)；在此情況下該協程將透過 " +"``ensure_future()`` 來排程。" + +#: ../../library/asyncio-future.rst:47 +msgid "" +"a :class:`Task` object that would await on *obj*, if *obj* is an awaitable " +"(:func:`inspect.isawaitable` is used for the test.)" +msgstr "" +"一個會等待 *obj* 的 :class:`Task` 物件，*obj* 須為一個可等待物件" +"（\\ :func:`inspect.isawaitable` 用於測試。)" + +#: ../../library/asyncio-future.rst:50 +msgid "If *obj* is neither of the above a :exc:`TypeError` is raised." +msgstr "如果 *obj* 不是上述物件的話會引發一個 :exc:`TypeError` 例外。" + +#: ../../library/asyncio-future.rst:54 +msgid "" +"Save a reference to the result of this function, to avoid a task " +"disappearing mid-execution." +msgstr "將參照 (reference) 儲存至此函式的結果，用以防止任務在執行中消失。" + +#: ../../library/asyncio-future.rst:57 +msgid "" +"See also the :func:`create_task` function which is the preferred way for " +"creating new tasks or use :class:`asyncio.TaskGroup` which keeps reference " +"to the task internally." +msgstr "請見 :func:`create_task` 函式，它是建立新 Task 的推薦方法。或者使用 " +":class:`asyncio.TaskGroup`，它會在內部保留對 Task 的參照。" + +#: ../../library/asyncio-future.rst:61 +msgid "The function accepts any :term:`awaitable` object." +msgstr "這個函式接受任意 :term:`awaitable` 物件。" + +#: ../../library/asyncio-future.rst:64 +msgid "" +"Deprecation warning is emitted if *obj* is not a Future-like object and " +"*loop* is not specified and there is no running event loop." +msgstr "" +"如果 *obj* 不是類 Future 物件且 *loop* 並未被指定，同時沒有正在執行的事件迴" +"圈 (event loop)，則會發出棄用警告。" + +#: ../../library/asyncio-future.rst:71 +msgid "" +"Wrap a :class:`concurrent.futures.Future` object in " +"a :class:`asyncio.Future` object." +msgstr "" +"將一個 :class:`concurrent.futures.Future` 物件包裝到 :class:`asyncio.Future` " +"物件中。" + +#: ../../library/asyncio-future.rst:74 +msgid "" +"Deprecation warning is emitted if *future* is not a Future-like object and " +"*loop* is not specified and there is no running event loop." +msgstr "" +"如果 *future* 不是類 Future 物件且 *loop* 未被指定，同時沒有正在執行的事件迴" +"圈，則會發出棄用警告。" + +#: ../../library/asyncio-future.rst:81 +msgid "Future Object" +msgstr "Future 物件" + +#: ../../library/asyncio-future.rst:85 +msgid "" +"A Future represents an eventual result of an asynchronous operation. Not " +"thread-safe." +msgstr "" +"一個 Future 代表一個非同步運算的最終結果。並不支援執行緒安全 (thread-safe)。" + +#: ../../library/asyncio-future.rst:88 +msgid "" +"Future is an :term:`awaitable` object. Coroutines can await on Future " +"objects until they either have a result or an exception set, or until they " +"are cancelled. A Future can be awaited multiple times and the result is same." +msgstr "" +"Future 是一個 :term:`awaitable` 物件。協程可以等待 Future 物件直到它們有結果" +"或例外被設置、或者被取消。一個 Future 可被多次等待而結果都會是相同的。" + +#: ../../library/asyncio-future.rst:93 +msgid "" +"Typically Futures are used to enable low-level callback-based code (e.g. in " +"protocols implemented using asyncio :ref:`transports `) to interoperate with high-level async/await code." +msgstr "" +"Future 通常用於讓低階基於回呼的程式（例如在協定實作中使用 " +"asyncio :ref:`transports `\\ ）能夠與高階 " +"async/await 程式互動。" + +#: ../../library/asyncio-future.rst:98 +msgid "" +"The rule of thumb is to never expose Future objects in user-facing APIs, and " +"the recommended way to create a Future object is to " +"call :meth:`loop.create_future`. This way alternative event loop " +"implementations can inject their own optimized implementations of a Future " +"object." +msgstr "" +"經驗法則為永遠不要在提供給使用者的 API 中公開 Future 物件，同時建議使" +"用 :meth:`loop.create_future` 來建立 Future 物件。如此一來，不同實作的事件迴" +"圈可以注入自己最佳化實作的 Future 物件。" + +#: ../../library/asyncio-future.rst:104 +msgid "Added support for the :mod:`contextvars` module." +msgstr "加入對 :mod:`contextvars` 模組的支援。" + +#: ../../library/asyncio-future.rst:107 +msgid "" +"Deprecation warning is emitted if *loop* is not specified and there is no " +"running event loop." +msgstr "如果未指定 *loop* 並且沒有正在執行的事件迴圈則會發出棄用警告。" + +#: ../../library/asyncio-future.rst:113 +msgid "Return the result of the Future." +msgstr "回傳 Future 的結果。" + +#: ../../library/asyncio-future.rst:115 +msgid "" +"If the Future is *done* and has a result set by the :meth:`set_result` " +"method, the result value is returned." +msgstr "" +"如果 Future 狀態為 *done*\\ （完成），並擁有 :meth:`set_result` 方法設定的一" +"個結果，則回傳該結果之值。" + +#: ../../library/asyncio-future.rst:118 +msgid "" +"If the Future is *done* and has an exception set by " +"the :meth:`set_exception` method, this method raises the exception." +msgstr "" +"如果 Future 狀態為 *done*，並擁有 :meth:`set_exception` 方法設定的一個例外，" +"那麼這個方法會引發該例外。" + +#: ../../library/asyncio-future.rst:121 ../../library/asyncio-future.rst:209 +msgid "" +"If the Future has been *cancelled*, this method raises " +"a :exc:`CancelledError` exception." +msgstr "" +"如果 Future 已被 *cancelled*\\ （取消），此方法會引發一" +"個 :exc:`CancelledError` 例外。" + +#: ../../library/asyncio-future.rst:124 +msgid "" +"If the Future's result isn't yet available, this method raises " +"an :exc:`InvalidStateError` exception." +msgstr "" +"如果 Future 的結果還不可用，此方法會引發一個 :exc:`InvalidStateError` 例外。" + +#: ../../library/asyncio-future.rst:129 +msgid "Mark the Future as *done* and set its result." +msgstr "將 Future 標記為 *done* 並設定其結果。" + +#: ../../library/asyncio-future.rst:131 ../../library/asyncio-future.rst:138 +msgid "" +"Raises an :exc:`InvalidStateError` error if the Future is already *done*." +msgstr "如果 Future 已經 *done* 則引發一個 :exc:`InvalidStateError` 錯誤。" + +#: ../../library/asyncio-future.rst:136 +msgid "Mark the Future as *done* and set an exception." +msgstr "將 Future 標記為 *done* 並設定一個例外。" + +#: ../../library/asyncio-future.rst:143 +msgid "Return ``True`` if the Future is *done*." +msgstr "如果 Future 已為 *done* 則回傳 ``True``。" + +#: ../../library/asyncio-future.rst:145 +msgid "" +"A Future is *done* if it was *cancelled* or if it has a result or an " +"exception set with :meth:`set_result` or :meth:`set_exception` calls." +msgstr "" +"如果 Future 有被 *cancelled*、:meth:`set_result` 有被呼叫來為其設定結果、" +"或 :meth:`set_exception` 有被呼叫為其設定例外，那麼它就是 *done*。" + +#: ../../library/asyncio-future.rst:151 +msgid "Return ``True`` if the Future was *cancelled*." +msgstr "如果 Future 已經被 *cancelled* 則回傳 ``True``。" + +#: ../../library/asyncio-future.rst:153 +msgid "" +"The method is usually used to check if a Future is not *cancelled* before " +"setting a result or an exception for it::" +msgstr "" +"這個方法通常在為 Future 設定結果或例外前用來確認它還沒被 *cancelled*： ::" + +#: ../../library/asyncio-future.rst:156 +msgid "" +"if not fut.cancelled():\n" +" fut.set_result(42)" +msgstr "" +"if not fut.cancelled():\n" +" fut.set_result(42)" + +#: ../../library/asyncio-future.rst:161 +msgid "Add a callback to be run when the Future is *done*." +msgstr "新增一個在 Future 為 *done* 時執行的回呼函式。" + +#: ../../library/asyncio-future.rst:163 +msgid "The *callback* is called with the Future object as its only argument." +msgstr "呼叫 *callback* 並附帶做為唯一引數的 Future 物件。" + +#: ../../library/asyncio-future.rst:166 +msgid "" +"If the Future is already *done* when this method is called, the callback is " +"scheduled with :meth:`loop.call_soon`." +msgstr "" +"如果呼叫這個方法時 Future 已經為 *done*，回呼函式會被 :meth:`loop.call_soon` " +"排程。" + +#: ../../library/asyncio-future.rst:169 +msgid "" +"An optional keyword-only *context* argument allows specifying a " +"custom :class:`contextvars.Context` for the *callback* to run in. The " +"current context is used when no *context* is provided." +msgstr "" +"可選僅限關鍵字引數 *context* 用來指定一個讓 *callback* 執行於其中的客製" +"化 :class:`contextvars.Context` 物件。如果沒有提供 *context*，則使用目前情" +"境。" + +#: ../../library/asyncio-future.rst:173 +msgid "" +":func:`functools.partial` can be used to pass parameters to the callback, " +"e.g.::" +msgstr "可以用 :func:`functools.partial` 傳遞引數給回呼函式，例如： ::" + +#: ../../library/asyncio-future.rst:176 +msgid "" +"# Call 'print(\"Future:\", fut)' when \"fut\" is done.\n" +"fut.add_done_callback(\n" +" functools.partial(print, \"Future:\"))" +msgstr "" + +#: ../../library/asyncio-future.rst:180 +msgid "" +"The *context* keyword-only parameter was added. See :pep:`567` for more " +"details." +msgstr "加入僅限關鍵字參數 *context*。更多細節請參閱 :pep:`567`。" + +#: ../../library/asyncio-future.rst:186 +msgid "Remove *callback* from the callbacks list." +msgstr "從回呼列表中移除 *callback*。" + +#: ../../library/asyncio-future.rst:188 +msgid "" +"Returns the number of callbacks removed, which is typically 1, unless a " +"callback was added more than once." +msgstr "回傳被移除的回呼函式數量，通常為 1，除非一個回呼函式被多次加入。" + +#: ../../library/asyncio-future.rst:193 +msgid "Cancel the Future and schedule callbacks." +msgstr "取消 Future 並為回呼函式排程。" + +#: ../../library/asyncio-future.rst:195 +msgid "" +"If the Future is already *done* or *cancelled*, return ``False``. Otherwise, " +"change the Future's state to *cancelled*, schedule the callbacks, and return " +"``True``." +msgstr "" +"如果 Future 已經是 *done* 或 *cancelled*，回傳 ``False``。否則將 Future 狀態" +"改為 *cancelled* 並在為回呼函式排程後回傳 ``True``。" + +#: ../../library/asyncio-future.rst:199 +msgid "Added the *msg* parameter." +msgstr "新增 *msg* 參數。" + +#: ../../library/asyncio-future.rst:204 +msgid "Return the exception that was set on this Future." +msgstr "回傳被設定於此 Future 的例外。" + +#: ../../library/asyncio-future.rst:206 +msgid "" +"The exception (or ``None`` if no exception was set) is returned only if the " +"Future is *done*." +msgstr "" +"只有 Future 在 *done* 時才回傳例外（如果沒有設定例外則回傳 ``None``\\ ）。" + +#: ../../library/asyncio-future.rst:212 +msgid "" +"If the Future isn't *done* yet, this method raises " +"an :exc:`InvalidStateError` exception." +msgstr "" +"如果 Future 還不為 *done*，此方法會引發一個 :exc:`InvalidStateError` 例外。" + +#: ../../library/asyncio-future.rst:217 +msgid "Return the event loop the Future object is bound to." +msgstr "回傳已被 Future 物件繫結 (bind) 的事件迴圈。" + +#: ../../library/asyncio-future.rst:224 +msgid "" +"This example creates a Future object, creates and schedules an asynchronous " +"Task to set result for the Future, and waits until the Future has a result::" +msgstr "" +"這個例子建立一個 Future 物件，建立一個非同步 Task 並為其排程以設定 Future 結" +"果，然後等待 Future 結果出現： ::" + +#: ../../library/asyncio-future.rst:228 +msgid "" +"async def set_after(fut, delay, value):\n" +" # Sleep for *delay* seconds.\n" +" await asyncio.sleep(delay)\n" +"\n" +" # Set *value* as a result of *fut* Future.\n" +" fut.set_result(value)\n" +"\n" +"async def main():\n" +" # Get the current event loop.\n" +" loop = asyncio.get_running_loop()\n" +"\n" +" # Create a new Future object.\n" +" fut = loop.create_future()\n" +"\n" +" # Run \"set_after()\" coroutine in a parallel Task.\n" +" # We are using the low-level \"loop.create_task()\" API here because\n" +" # we already have a reference to the event loop at hand.\n" +" # Otherwise we could have just used \"asyncio.create_task()\".\n" +" loop.create_task(\n" +" set_after(fut, 1, '... world'))\n" +"\n" +" print('hello ...')\n" +"\n" +" # Wait until *fut* has a result (1 second) and print it.\n" +" print(await fut)\n" +"\n" +"asyncio.run(main())" +msgstr "" + +#: ../../library/asyncio-future.rst:259 +msgid "" +"The Future object was designed to mimic :class:`concurrent.futures.Future`. " +"Key differences include:" +msgstr "" +"該 Future 物件是為了模仿 :class:`concurrent.futures.Future` 而設計。主要差異" +"包含：" + +#: ../../library/asyncio-future.rst:262 +msgid "" +"unlike asyncio Futures, :class:`concurrent.futures.Future` instances cannot " +"be awaited." +msgstr "" +"與 asyncio 的 Future 不同，:class:`concurrent.futures.Future` 實例不可被等" +"待。" + +#: ../../library/asyncio-future.rst:265 +msgid "" +":meth:`asyncio.Future.result` and :meth:`asyncio.Future.exception` do not " +"accept the *timeout* argument." +msgstr "" +":meth:`asyncio.Future.result` 和 :meth:`asyncio.Future.exception` 不接受 " +"*timeout* 引數。" + +#: ../../library/asyncio-future.rst:268 +msgid "" +":meth:`asyncio.Future.result` and :meth:`asyncio.Future.exception` raise " +"an :exc:`InvalidStateError` exception when the Future is not *done*." +msgstr "" +"Future 不為 *done* 時 :meth:`asyncio.Future.result` " +"和 :meth:`asyncio.Future.exception` 會引發一個 :exc:`InvalidStateError` 例" +"外。" + +#: ../../library/asyncio-future.rst:272 +msgid "" +"Callbacks registered with :meth:`asyncio.Future.add_done_callback` are not " +"called immediately. They are scheduled with :meth:`loop.call_soon` instead." +msgstr "" +"使用 :meth:`asyncio.Future.add_done_callback` 註冊的回呼函式不會立即呼叫，而" +"是被 :meth:`loop.call_soon` 排程。" + +#: ../../library/asyncio-future.rst:276 +msgid "" +"asyncio Future is not compatible with the :func:`concurrent.futures.wait` " +"and :func:`concurrent.futures.as_completed` functions." +msgstr "" +"asyncio Future 不能與 :func:`concurrent.futures.wait` " +"和 :func:`concurrent.futures.as_completed` 函式相容。" + +#: ../../library/asyncio-future.rst:280 +msgid "" +":meth:`asyncio.Future.cancel` accepts an optional ``msg`` argument, " +"but :meth:`concurrent.futures.Future.cancel` does not." +msgstr "" +":meth:`asyncio.Future.cancel` 接受一個可選的 ``msg`` 引數，" +"但 :func:`concurrent.futures.Future.cancel` 無此引數。" diff --git a/library/asyncio-graph.po b/library/asyncio-graph.po index 59b3e1cfb8..4ef785790d 100644 --- a/library/asyncio-graph.po +++ b/library/asyncio-graph.po @@ -1,219 +1,219 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# FIRST AUTHOR , YEAR. -# -#, fuzzy -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language-Team: LANGUAGE \n" -"Language: zh_TW\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=UTF-8\n" -"Content-Transfer-Encoding: 8bit\n" - -#: ../../library/asyncio-graph.rst:8 -msgid "Call Graph Introspection" -msgstr "" - -#: ../../library/asyncio-graph.rst:10 -msgid "**Source code:** :source:`Lib/asyncio/graph.py`" -msgstr "**原始碼：**\\ :source:`Lib/asyncio/graph.py`" - -#: ../../library/asyncio-graph.rst:14 -msgid "" -"asyncio has powerful runtime call graph introspection utilities to trace the " -"entire call graph of a running *coroutine* or *task*, or a suspended " -"*future*. These utilities and the underlying machinery can be used from " -"within a Python program or by external profilers and debuggers." -msgstr "" - -#: ../../library/asyncio-graph.rst:25 -msgid "" -"Print the async call graph for the current task or the " -"provided :class:`Task` or :class:`Future`." -msgstr "" - -#: ../../library/asyncio-graph.rst:28 -msgid "" -"This function prints entries starting from the top frame and going down " -"towards the invocation point." -msgstr "" - -#: ../../library/asyncio-graph.rst:31 -msgid "" -"The function receives an optional *future* argument. If not passed, the " -"current running task will be used." -msgstr "" - -#: ../../library/asyncio-graph.rst:34 ../../library/asyncio-graph.rst:93 -msgid "" -"If the function is called on *the current task*, the optional keyword-only " -"*depth* argument can be used to skip the specified number of frames from top " -"of the stack." -msgstr "" - -#: ../../library/asyncio-graph.rst:38 -msgid "" -"If the optional keyword-only *limit* argument is provided, each call stack " -"in the resulting graph is truncated to include at most ``abs(limit)`` " -"entries. If *limit* is positive, the entries left are the closest to the " -"invocation point. If *limit* is negative, the topmost entries are left. If " -"*limit* is omitted or ``None``, all entries are present. If *limit* is " -"``0``, the call stack is not printed at all, only \"awaited by\" information " -"is printed." -msgstr "" - -#: ../../library/asyncio-graph.rst:46 -msgid "" -"If *file* is omitted or ``None``, the function will print " -"to :data:`sys.stdout`." -msgstr "" - -#: ../../library/asyncio-graph.rst:49 -msgid "**Example:**" -msgstr "**範例：**" - -#: ../../library/asyncio-graph.rst:51 -msgid "The following Python code:" -msgstr "以下 Python 程式碼：" - -#: ../../library/asyncio-graph.rst:53 -msgid "" -"import asyncio\n" -"\n" -"async def test():\n" -" asyncio.print_call_graph()\n" -"\n" -"async def main():\n" -" async with asyncio.TaskGroup() as g:\n" -" g.create_task(test(), name='test')\n" -"\n" -"asyncio.run(main())" -msgstr "" -"import asyncio\n" -"\n" -"async def test():\n" -" asyncio.print_call_graph()\n" -"\n" -"async def main():\n" -" async with asyncio.TaskGroup() as g:\n" -" g.create_task(test(), name='test')\n" -"\n" -"asyncio.run(main())" - -#: ../../library/asyncio-graph.rst:66 -msgid "will print::" -msgstr "會印出： ::" - -#: ../../library/asyncio-graph.rst:68 -msgid "" -"* Task(name='test', id=0x1039f0fe0)\n" -"+ Call stack:\n" -"| File 't2.py', line 4, in async test()\n" -"+ Awaited by:\n" -" * Task(name='Task-1', id=0x103a5e060)\n" -" + Call stack:\n" -" | File 'taskgroups.py', line 107, in async TaskGroup.__aexit__()\n" -" | File 't2.py', line 7, in async main()" -msgstr "" -"* Task(name='test', id=0x1039f0fe0)\n" -"+ Call stack:\n" -"| File 't2.py', line 4, in async test()\n" -"+ Awaited by:\n" -" * Task(name='Task-1', id=0x103a5e060)\n" -" + Call stack:\n" -" | File 'taskgroups.py', line 107, in async TaskGroup.__aexit__()\n" -" | File 't2.py', line 7, in async main()" - -#: ../../library/asyncio-graph.rst:79 -msgid "" -"Like :func:`print_call_graph`, but returns a string. If *future* is ``None`` " -"and there's no current task, the function returns an empty string." -msgstr "" - -#: ../../library/asyncio-graph.rst:86 -msgid "" -"Capture the async call graph for the current task or the " -"provided :class:`Task` or :class:`Future`." -msgstr "" - -#: ../../library/asyncio-graph.rst:89 -msgid "" -"The function receives an optional *future* argument. If not passed, the " -"current running task will be used. If there's no current task, the function " -"returns ``None``." -msgstr "" - -#: ../../library/asyncio-graph.rst:97 -msgid "Returns a ``FutureCallGraph`` data class object:" -msgstr "會回傳一個 ``FutureCallGraph`` 資料類別物件：" - -#: ../../library/asyncio-graph.rst:99 -msgid "``FutureCallGraph(future, call_stack, awaited_by)``" -msgstr "``FutureCallGraph(future, call_stack, awaited_by)``" - -#: ../../library/asyncio-graph.rst:101 -msgid "" -"Where *future* is a reference to a :class:`Future` or a :class:`Task` (or " -"their subclasses.)" -msgstr "" - -#: ../../library/asyncio-graph.rst:104 -msgid "``call_stack`` is a tuple of ``FrameCallGraphEntry`` objects." -msgstr "``call_stack`` 是一個由 ``FrameCallGraphEntry`` 物件組成的元組。" - -#: ../../library/asyncio-graph.rst:106 -msgid "``awaited_by`` is a tuple of ``FutureCallGraph`` objects." -msgstr "``awaited_by`` 是一個由 ``FutureCallGraph`` 物件組成的元組。" - -#: ../../library/asyncio-graph.rst:108 -msgid "``FrameCallGraphEntry(frame)``" -msgstr "``FrameCallGraphEntry(frame)``" - -#: ../../library/asyncio-graph.rst:110 -msgid "" -"Where *frame* is a frame object of a regular Python function in the call " -"stack." -msgstr "" - -#: ../../library/asyncio-graph.rst:115 -msgid "Low level utility functions" -msgstr "低階工具函式" - -#: ../../library/asyncio-graph.rst:117 -msgid "" -"To introspect an async call graph asyncio requires cooperation from control " -"flow structures, such as :func:`shield` or :class:`TaskGroup`. Any time an " -"intermediate :class:`Future` object with low-level APIs " -"like :meth:`Future.add_done_callback() ` " -"is involved, the following two functions should be used to inform asyncio " -"about how exactly such intermediate future objects are connected with the " -"tasks they wrap or control." -msgstr "" - -#: ../../library/asyncio-graph.rst:128 -msgid "Record that *future* is awaited on by *waiter*." -msgstr "" - -#: ../../library/asyncio-graph.rst:130 ../../library/asyncio-graph.rst:143 -msgid "" -"Both *future* and *waiter* must be instances of :class:`Future` " -"or :class:`Task` or their subclasses, otherwise the call would have no " -"effect." -msgstr "" - -#: ../../library/asyncio-graph.rst:134 -msgid "" -"A call to ``future_add_to_awaited_by()`` must be followed by an eventual " -"call to the :func:`future_discard_from_awaited_by` function with the same " -"arguments." -msgstr "" - -#: ../../library/asyncio-graph.rst:141 -msgid "Record that *future* is no longer awaited on by *waiter*." -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"Language: zh_TW\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../library/asyncio-graph.rst:8 +msgid "Call Graph Introspection" +msgstr "" + +#: ../../library/asyncio-graph.rst:10 +msgid "**Source code:** :source:`Lib/asyncio/graph.py`" +msgstr "**原始碼：**\\ :source:`Lib/asyncio/graph.py`" + +#: ../../library/asyncio-graph.rst:14 +msgid "" +"asyncio has powerful runtime call graph introspection utilities to trace the " +"entire call graph of a running *coroutine* or *task*, or a suspended " +"*future*. These utilities and the underlying machinery can be used from " +"within a Python program or by external profilers and debuggers." +msgstr "" + +#: ../../library/asyncio-graph.rst:25 +msgid "" +"Print the async call graph for the current task or the " +"provided :class:`Task` or :class:`Future`." +msgstr "" + +#: ../../library/asyncio-graph.rst:28 +msgid "" +"This function prints entries starting from the top frame and going down " +"towards the invocation point." +msgstr "" + +#: ../../library/asyncio-graph.rst:31 +msgid "" +"The function receives an optional *future* argument. If not passed, the " +"current running task will be used." +msgstr "" + +#: ../../library/asyncio-graph.rst:34 ../../library/asyncio-graph.rst:93 +msgid "" +"If the function is called on *the current task*, the optional keyword-only " +"*depth* argument can be used to skip the specified number of frames from top " +"of the stack." +msgstr "" + +#: ../../library/asyncio-graph.rst:38 +msgid "" +"If the optional keyword-only *limit* argument is provided, each call stack " +"in the resulting graph is truncated to include at most ``abs(limit)`` " +"entries. If *limit* is positive, the entries left are the closest to the " +"invocation point. If *limit* is negative, the topmost entries are left. If " +"*limit* is omitted or ``None``, all entries are present. If *limit* is " +"``0``, the call stack is not printed at all, only \"awaited by\" information " +"is printed." +msgstr "" + +#: ../../library/asyncio-graph.rst:46 +msgid "" +"If *file* is omitted or ``None``, the function will print " +"to :data:`sys.stdout`." +msgstr "" + +#: ../../library/asyncio-graph.rst:49 +msgid "**Example:**" +msgstr "**範例：**" + +#: ../../library/asyncio-graph.rst:51 +msgid "The following Python code:" +msgstr "以下 Python 程式碼：" + +#: ../../library/asyncio-graph.rst:53 +msgid "" +"import asyncio\n" +"\n" +"async def test():\n" +" asyncio.print_call_graph()\n" +"\n" +"async def main():\n" +" async with asyncio.TaskGroup() as g:\n" +" g.create_task(test(), name='test')\n" +"\n" +"asyncio.run(main())" +msgstr "" +"import asyncio\n" +"\n" +"async def test():\n" +" asyncio.print_call_graph()\n" +"\n" +"async def main():\n" +" async with asyncio.TaskGroup() as g:\n" +" g.create_task(test(), name='test')\n" +"\n" +"asyncio.run(main())" + +#: ../../library/asyncio-graph.rst:66 +msgid "will print::" +msgstr "會印出： ::" + +#: ../../library/asyncio-graph.rst:68 +msgid "" +"* Task(name='test', id=0x1039f0fe0)\n" +"+ Call stack:\n" +"| File 't2.py', line 4, in async test()\n" +"+ Awaited by:\n" +" * Task(name='Task-1', id=0x103a5e060)\n" +" + Call stack:\n" +" | File 'taskgroups.py', line 107, in async TaskGroup.__aexit__()\n" +" | File 't2.py', line 7, in async main()" +msgstr "" +"* Task(name='test', id=0x1039f0fe0)\n" +"+ Call stack:\n" +"| File 't2.py', line 4, in async test()\n" +"+ Awaited by:\n" +" * Task(name='Task-1', id=0x103a5e060)\n" +" + Call stack:\n" +" | File 'taskgroups.py', line 107, in async TaskGroup.__aexit__()\n" +" | File 't2.py', line 7, in async main()" + +#: ../../library/asyncio-graph.rst:79 +msgid "" +"Like :func:`print_call_graph`, but returns a string. If *future* is ``None`` " +"and there's no current task, the function returns an empty string." +msgstr "" + +#: ../../library/asyncio-graph.rst:86 +msgid "" +"Capture the async call graph for the current task or the " +"provided :class:`Task` or :class:`Future`." +msgstr "" + +#: ../../library/asyncio-graph.rst:89 +msgid "" +"The function receives an optional *future* argument. If not passed, the " +"current running task will be used. If there's no current task, the function " +"returns ``None``." +msgstr "" + +#: ../../library/asyncio-graph.rst:97 +msgid "Returns a ``FutureCallGraph`` data class object:" +msgstr "會回傳一個 ``FutureCallGraph`` 資料類別物件：" + +#: ../../library/asyncio-graph.rst:99 +msgid "``FutureCallGraph(future, call_stack, awaited_by)``" +msgstr "``FutureCallGraph(future, call_stack, awaited_by)``" + +#: ../../library/asyncio-graph.rst:101 +msgid "" +"Where *future* is a reference to a :class:`Future` or a :class:`Task` (or " +"their subclasses.)" +msgstr "" + +#: ../../library/asyncio-graph.rst:104 +msgid "``call_stack`` is a tuple of ``FrameCallGraphEntry`` objects." +msgstr "``call_stack`` 是一個由 ``FrameCallGraphEntry`` 物件組成的元組。" + +#: ../../library/asyncio-graph.rst:106 +msgid "``awaited_by`` is a tuple of ``FutureCallGraph`` objects." +msgstr "``awaited_by`` 是一個由 ``FutureCallGraph`` 物件組成的元組。" + +#: ../../library/asyncio-graph.rst:108 +msgid "``FrameCallGraphEntry(frame)``" +msgstr "``FrameCallGraphEntry(frame)``" + +#: ../../library/asyncio-graph.rst:110 +msgid "" +"Where *frame* is a frame object of a regular Python function in the call " +"stack." +msgstr "" + +#: ../../library/asyncio-graph.rst:115 +msgid "Low level utility functions" +msgstr "低階工具函式" + +#: ../../library/asyncio-graph.rst:117 +msgid "" +"To introspect an async call graph asyncio requires cooperation from control " +"flow structures, such as :func:`shield` or :class:`TaskGroup`. Any time an " +"intermediate :class:`Future` object with low-level APIs " +"like :meth:`Future.add_done_callback() ` " +"is involved, the following two functions should be used to inform asyncio " +"about how exactly such intermediate future objects are connected with the " +"tasks they wrap or control." +msgstr "" + +#: ../../library/asyncio-graph.rst:128 +msgid "Record that *future* is awaited on by *waiter*." +msgstr "" + +#: ../../library/asyncio-graph.rst:130 ../../library/asyncio-graph.rst:143 +msgid "" +"Both *future* and *waiter* must be instances of :class:`Future` " +"or :class:`Task` or their subclasses, otherwise the call would have no " +"effect." +msgstr "" + +#: ../../library/asyncio-graph.rst:134 +msgid "" +"A call to ``future_add_to_awaited_by()`` must be followed by an eventual " +"call to the :func:`future_discard_from_awaited_by` function with the same " +"arguments." +msgstr "" + +#: ../../library/asyncio-graph.rst:141 +msgid "Record that *future* is no longer awaited on by *waiter*." +msgstr "" diff --git a/library/asyncio-llapi-index.po b/library/asyncio-llapi-index.po index 6ddd9f538c..6ddd59e8d1 100644 --- a/library/asyncio-llapi-index.po +++ b/library/asyncio-llapi-index.po @@ -1,1063 +1,1063 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Matt Wang , 2022-2023 -# -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: 2023-10-12 11:27+0800\n" -"Last-Translator: Matt Wang \n" -"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" -"tw)\n" -"Language: zh_TW\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=UTF-8\n" -"Content-Transfer-Encoding: 8bit\n" -"X-Generator: Poedit 3.0.1\n" - -#: ../../library/asyncio-llapi-index.rst:6 -msgid "Low-level API Index" -msgstr "低階 API 索引" - -#: ../../library/asyncio-llapi-index.rst:8 -msgid "This page lists all low-level asyncio APIs." -msgstr "本頁列出所有低階 asyncio APIs。" - -#: ../../library/asyncio-llapi-index.rst:12 -msgid "Obtaining the Event Loop" -msgstr "取得事件迴圈" - -#: ../../library/asyncio-llapi-index.rst:18 -msgid ":func:`asyncio.get_running_loop`" -msgstr ":func:`asyncio.get_running_loop`" - -#: ../../library/asyncio-llapi-index.rst:19 -msgid "The **preferred** function to get the running event loop." -msgstr "**推薦使用**\\ 於取得目前運行事件迴圈 (event loop) 的函式。" - -#: ../../library/asyncio-llapi-index.rst:21 -msgid ":func:`asyncio.get_event_loop`" -msgstr ":func:`asyncio.get_event_loop`" - -#: ../../library/asyncio-llapi-index.rst:22 -msgid "Get an event loop instance (running or current via the current policy)." -msgstr "獲得一個（正在運行的或透過目前 policy 建立的）事件迴圈實例。" - -#: ../../library/asyncio-llapi-index.rst:24 -msgid ":func:`asyncio.set_event_loop`" -msgstr ":func:`asyncio.set_event_loop`" - -#: ../../library/asyncio-llapi-index.rst:25 -msgid "Set the event loop as current via the current policy." -msgstr "透過目前 policy 來設定目前事件迴圈。" - -#: ../../library/asyncio-llapi-index.rst:27 -msgid ":func:`asyncio.new_event_loop`" -msgstr ":func:`asyncio.new_event_loop`" - -#: ../../library/asyncio-llapi-index.rst:28 -msgid "Create a new event loop." -msgstr "建立一個新的事件迴圈。" - -#: ../../library/asyncio-llapi-index.rst:32 -#: ../../library/asyncio-llapi-index.rst:269 -msgid "Examples" -msgstr "範例" - -#: ../../library/asyncio-llapi-index.rst:33 -msgid ":ref:`Using asyncio.get_running_loop() `." -msgstr ":ref:`使用 asyncio.get_running_loop() `。" - -#: ../../library/asyncio-llapi-index.rst:37 -msgid "Event Loop Methods" -msgstr "事件迴圈方法" - -#: ../../library/asyncio-llapi-index.rst:39 -msgid "" -"See also the main documentation section about the :ref:`asyncio-event-loop-" -"methods`." -msgstr "也請查閱文件中關於\\ :ref:`asyncio-event-loop-methods`\\ 的主要段落。" - -#: ../../library/asyncio-llapi-index.rst:42 -msgid "Lifecycle" -msgstr "生命週期" - -#: ../../library/asyncio-llapi-index.rst:47 -msgid ":meth:`loop.run_until_complete`" -msgstr ":meth:`loop.run_until_complete`" - -#: ../../library/asyncio-llapi-index.rst:48 -msgid "Run a Future/Task/awaitable until complete." -msgstr "執行一個 Future/Task/awaitable（可等待物件）直到完成。" - -#: ../../library/asyncio-llapi-index.rst:50 -msgid ":meth:`loop.run_forever`" -msgstr ":meth:`loop.run_forever`" - -#: ../../library/asyncio-llapi-index.rst:51 -msgid "Run the event loop forever." -msgstr "持續運行事件迴圈。" - -#: ../../library/asyncio-llapi-index.rst:53 -msgid ":meth:`loop.stop`" -msgstr ":meth:`loop.stop`" - -#: ../../library/asyncio-llapi-index.rst:54 -msgid "Stop the event loop." -msgstr "停止事件迴圈。" - -#: ../../library/asyncio-llapi-index.rst:56 -msgid ":meth:`loop.close`" -msgstr ":meth:`loop.close`" - -#: ../../library/asyncio-llapi-index.rst:57 -msgid "Close the event loop." -msgstr "關閉事件迴圈。" - -#: ../../library/asyncio-llapi-index.rst:59 -msgid ":meth:`loop.is_running`" -msgstr ":meth:`loop.is_running`" - -#: ../../library/asyncio-llapi-index.rst:60 -msgid "Return ``True`` if the event loop is running." -msgstr "如果事件迴圈正在執行則回傳 ``True``。" - -#: ../../library/asyncio-llapi-index.rst:62 -msgid ":meth:`loop.is_closed`" -msgstr ":meth:`loop.is_closed`" - -#: ../../library/asyncio-llapi-index.rst:63 -msgid "Return ``True`` if the event loop is closed." -msgstr "如果事件迴圈已經被關閉則回傳 ``True``。" - -#: ../../library/asyncio-llapi-index.rst:65 -msgid "``await`` :meth:`loop.shutdown_asyncgens`" -msgstr "``await`` :meth:`loop.shutdown_asyncgens`" - -#: ../../library/asyncio-llapi-index.rst:66 -msgid "Close asynchronous generators." -msgstr "關閉非同步產生器 (asynchronous generators)。" - -#: ../../library/asyncio-llapi-index.rst:69 -msgid "Debugging" -msgstr "除錯" - -#: ../../library/asyncio-llapi-index.rst:74 -msgid ":meth:`loop.set_debug`" -msgstr ":meth:`loop.set_debug`" - -#: ../../library/asyncio-llapi-index.rst:75 -msgid "Enable or disable the debug mode." -msgstr "開啟或禁用除錯模式。" - -#: ../../library/asyncio-llapi-index.rst:77 -msgid ":meth:`loop.get_debug`" -msgstr ":meth:`loop.get_debug`" - -#: ../../library/asyncio-llapi-index.rst:78 -msgid "Get the current debug mode." -msgstr "取得目前除錯模式。" - -#: ../../library/asyncio-llapi-index.rst:81 -msgid "Scheduling Callbacks" -msgstr "為回呼函式排程" - -#: ../../library/asyncio-llapi-index.rst:86 -msgid ":meth:`loop.call_soon`" -msgstr ":meth:`loop.call_soon`" - -#: ../../library/asyncio-llapi-index.rst:87 -msgid "Invoke a callback soon." -msgstr "儘快呼叫回呼函式 (callback)。" - -#: ../../library/asyncio-llapi-index.rst:89 -msgid ":meth:`loop.call_soon_threadsafe`" -msgstr ":meth:`loop.call_soon_threadsafe`" - -#: ../../library/asyncio-llapi-index.rst:90 -msgid "A thread-safe variant of :meth:`loop.call_soon`." -msgstr ":meth:`loop.call_soon` 方法之有支援執行緒安全 (thread-safe) 變體。" - -#: ../../library/asyncio-llapi-index.rst:92 -msgid ":meth:`loop.call_later`" -msgstr ":meth:`loop.call_later`" - -#: ../../library/asyncio-llapi-index.rst:93 -msgid "Invoke a callback *after* the given time." -msgstr "在給定時間\\ *之後*\\ 呼叫回呼函式。" - -#: ../../library/asyncio-llapi-index.rst:95 -msgid ":meth:`loop.call_at`" -msgstr ":meth:`loop.call_at`" - -#: ../../library/asyncio-llapi-index.rst:96 -msgid "Invoke a callback *at* the given time." -msgstr "在給定時間\\ *當下*\\ 呼叫回呼函式。" - -#: ../../library/asyncio-llapi-index.rst:99 -msgid "Thread/Interpreter/Process Pool" -msgstr "執行緒 (Thread)/直譯器 (Interpreter)/行程池 (Process Pool)" - -#: ../../library/asyncio-llapi-index.rst:104 -msgid "``await`` :meth:`loop.run_in_executor`" -msgstr "``await`` :meth:`loop.run_in_executor`" - -#: ../../library/asyncio-llapi-index.rst:105 -msgid "" -"Run a CPU-bound or other blocking function in a :mod:`concurrent.futures` " -"executor." -msgstr "" -"在 :mod:`concurrent.futures` 執行器 (excutor) 中執行一個 CPU 密集型 (CPU-" -"bound) 或其它阻塞型式的函式。" - -#: ../../library/asyncio-llapi-index.rst:108 -msgid ":meth:`loop.set_default_executor`" -msgstr ":meth:`loop.set_default_executor`" - -#: ../../library/asyncio-llapi-index.rst:109 -msgid "Set the default executor for :meth:`loop.run_in_executor`." -msgstr "為 :meth:`loop.run_in_executor` 設定預設執行器。" - -#: ../../library/asyncio-llapi-index.rst:112 -msgid "Tasks and Futures" -msgstr "Tasks 與 Futures" - -#: ../../library/asyncio-llapi-index.rst:117 -msgid ":meth:`loop.create_future`" -msgstr ":meth:`loop.create_future`" - -#: ../../library/asyncio-llapi-index.rst:118 -msgid "Create a :class:`Future` object." -msgstr "建立一個 :class:`Future` 物件。" - -#: ../../library/asyncio-llapi-index.rst:120 -msgid ":meth:`loop.create_task`" -msgstr ":meth:`loop.create_task`" - -#: ../../library/asyncio-llapi-index.rst:121 -msgid "Schedule coroutine as a :class:`Task`." -msgstr "像是 :class:`Task` 一樣，為協程 (coroutine) 排程。" - -#: ../../library/asyncio-llapi-index.rst:123 -msgid ":meth:`loop.set_task_factory`" -msgstr ":meth:`loop.set_task_factory`" - -#: ../../library/asyncio-llapi-index.rst:124 -msgid "" -"Set a factory used by :meth:`loop.create_task` to create :class:`Tasks " -"`." -msgstr "" -"設定被 :meth:`loop.create_task` 用來建立 :class:`Tasks ` 的工廠函式 " -"(factory)。" - -#: ../../library/asyncio-llapi-index.rst:127 -msgid ":meth:`loop.get_task_factory`" -msgstr ":meth:`loop.get_task_factory`" - -#: ../../library/asyncio-llapi-index.rst:128 -msgid "" -"Get the factory :meth:`loop.create_task` uses to create :class:`Tasks " -"`." -msgstr "" -"取得被 :meth:`loop.create_task` 用來建立 :class:`Tasks ` 的工廠函式。" - -#: ../../library/asyncio-llapi-index.rst:132 -msgid "DNS" -msgstr "DNS" - -#: ../../library/asyncio-llapi-index.rst:137 -msgid "``await`` :meth:`loop.getaddrinfo`" -msgstr "``await`` :meth:`loop.getaddrinfo`" - -#: ../../library/asyncio-llapi-index.rst:138 -msgid "Asynchronous version of :meth:`socket.getaddrinfo`." -msgstr "非同步版本的 :meth:`socket.getaddrinfo`。" - -#: ../../library/asyncio-llapi-index.rst:140 -msgid "``await`` :meth:`loop.getnameinfo`" -msgstr "``await`` :meth:`loop.getnameinfo`" - -#: ../../library/asyncio-llapi-index.rst:141 -msgid "Asynchronous version of :meth:`socket.getnameinfo`." -msgstr "非同步版本的 :meth:`socket.getnameinfo`。" - -#: ../../library/asyncio-llapi-index.rst:144 -msgid "Networking and IPC" -msgstr "網路和 IPC" - -#: ../../library/asyncio-llapi-index.rst:149 -msgid "``await`` :meth:`loop.create_connection`" -msgstr "``await`` :meth:`loop.create_connection`" - -#: ../../library/asyncio-llapi-index.rst:150 -msgid "Open a TCP connection." -msgstr "開啟一個 TCP 連線。" - -#: ../../library/asyncio-llapi-index.rst:152 -msgid "``await`` :meth:`loop.create_server`" -msgstr "``await`` :meth:`loop.create_server`" - -#: ../../library/asyncio-llapi-index.rst:153 -msgid "Create a TCP server." -msgstr "建立一個 TCP 伺服器。" - -#: ../../library/asyncio-llapi-index.rst:155 -msgid "``await`` :meth:`loop.create_unix_connection`" -msgstr "``await`` :meth:`loop.create_unix_connection`" - -#: ../../library/asyncio-llapi-index.rst:156 -msgid "Open a Unix socket connection." -msgstr "開啟一個 Unix socket 連線。" - -#: ../../library/asyncio-llapi-index.rst:158 -msgid "``await`` :meth:`loop.create_unix_server`" -msgstr "``await`` :meth:`loop.create_unix_server`" - -#: ../../library/asyncio-llapi-index.rst:159 -msgid "Create a Unix socket server." -msgstr "建立一個 Unix socket 伺服器。" - -#: ../../library/asyncio-llapi-index.rst:161 -msgid "``await`` :meth:`loop.connect_accepted_socket`" -msgstr "``await`` :meth:`loop.connect_accepted_socket`" - -#: ../../library/asyncio-llapi-index.rst:162 -msgid "Wrap a :class:`~socket.socket` into a ``(transport, protocol)`` pair." -msgstr "將 :class:`~socket.socket` 包裝成 ``(transport, protocol)``。" - -#: ../../library/asyncio-llapi-index.rst:165 -msgid "``await`` :meth:`loop.create_datagram_endpoint`" -msgstr "``await`` :meth:`loop.create_datagram_endpoint`" - -#: ../../library/asyncio-llapi-index.rst:166 -msgid "Open a datagram (UDP) connection." -msgstr "開啟一個資料單元 (datagram) (UDP) 連線。" - -#: ../../library/asyncio-llapi-index.rst:168 -msgid "``await`` :meth:`loop.sendfile`" -msgstr "``await`` :meth:`loop.sendfile`" - -#: ../../library/asyncio-llapi-index.rst:169 -msgid "Send a file over a transport." -msgstr "透過傳輸通道傳送一個檔案。" - -#: ../../library/asyncio-llapi-index.rst:171 -msgid "``await`` :meth:`loop.start_tls`" -msgstr "``await`` :meth:`loop.start_tls`" - -#: ../../library/asyncio-llapi-index.rst:172 -msgid "Upgrade an existing connection to TLS." -msgstr "將一個已存在的連線升級到 TLS。" - -#: ../../library/asyncio-llapi-index.rst:174 -msgid "``await`` :meth:`loop.connect_read_pipe`" -msgstr "``await`` :meth:`loop.connect_read_pipe`" - -#: ../../library/asyncio-llapi-index.rst:175 -msgid "Wrap a read end of a pipe into a ``(transport, protocol)`` pair." -msgstr "將 pipe（管道）讀取端包裝成 ``(transport, protocol)``。" - -#: ../../library/asyncio-llapi-index.rst:177 -msgid "``await`` :meth:`loop.connect_write_pipe`" -msgstr "``await`` :meth:`loop.connect_write_pipe`" - -#: ../../library/asyncio-llapi-index.rst:178 -msgid "Wrap a write end of a pipe into a ``(transport, protocol)`` pair." -msgstr "將 pipe 寫入端包裝成 ``(transport, protocol)``。" - -#: ../../library/asyncio-llapi-index.rst:181 -msgid "Sockets" -msgstr "Sockets" - -#: ../../library/asyncio-llapi-index.rst:186 -msgid "``await`` :meth:`loop.sock_recv`" -msgstr "``await`` :meth:`loop.sock_recv`" - -#: ../../library/asyncio-llapi-index.rst:187 -msgid "Receive data from the :class:`~socket.socket`." -msgstr "從 :class:`~socket.socket` 接收資料。" - -#: ../../library/asyncio-llapi-index.rst:189 -msgid "``await`` :meth:`loop.sock_recv_into`" -msgstr "``await`` :meth:`loop.sock_recv_into`" - -#: ../../library/asyncio-llapi-index.rst:190 -msgid "Receive data from the :class:`~socket.socket` into a buffer." -msgstr "" -"將從 :class:`~socket.socket` 接收到的資料存放於一個緩衝區 (buffer) 中。" - -#: ../../library/asyncio-llapi-index.rst:192 -msgid "``await`` :meth:`loop.sock_recvfrom`" -msgstr "``await`` :meth:`loop.sock_recvfrom`" - -#: ../../library/asyncio-llapi-index.rst:193 -msgid "Receive a datagram from the :class:`~socket.socket`." -msgstr "從 :class:`~socket.socket` 接收一個資料單元。" - -#: ../../library/asyncio-llapi-index.rst:195 -msgid "``await`` :meth:`loop.sock_recvfrom_into`" -msgstr "``await`` :meth:`loop.sock_recvfrom_into`" - -#: ../../library/asyncio-llapi-index.rst:196 -msgid "Receive a datagram from the :class:`~socket.socket` into a buffer." -msgstr "將從 :class:`~socket.socket` 接收到的資料單元存放於一個緩衝區中。" - -#: ../../library/asyncio-llapi-index.rst:198 -msgid "``await`` :meth:`loop.sock_sendall`" -msgstr "``await`` :meth:`loop.sock_sendall`" - -#: ../../library/asyncio-llapi-index.rst:199 -msgid "Send data to the :class:`~socket.socket`." -msgstr "傳送資料到 :class:`~socket.socket`。" - -#: ../../library/asyncio-llapi-index.rst:201 -msgid "``await`` :meth:`loop.sock_sendto`" -msgstr "``await`` :meth:`loop.sock_sendto`" - -#: ../../library/asyncio-llapi-index.rst:202 -msgid "Send a datagram via the :class:`~socket.socket` to the given address." -msgstr "透過 :class:`~socket.socket` 將資料單元傳送至給定的地址。" - -#: ../../library/asyncio-llapi-index.rst:204 -msgid "``await`` :meth:`loop.sock_connect`" -msgstr "``await`` :meth:`loop.sock_connect`" - -#: ../../library/asyncio-llapi-index.rst:205 -msgid "Connect the :class:`~socket.socket`." -msgstr "連接 :class:`~socket.socket`。" - -#: ../../library/asyncio-llapi-index.rst:207 -msgid "``await`` :meth:`loop.sock_accept`" -msgstr "``await`` :meth:`loop.sock_accept`" - -#: ../../library/asyncio-llapi-index.rst:208 -msgid "Accept a :class:`~socket.socket` connection." -msgstr "接受一個 :class:`~socket.socket` 連線。" - -#: ../../library/asyncio-llapi-index.rst:210 -msgid "``await`` :meth:`loop.sock_sendfile`" -msgstr "``await`` :meth:`loop.sock_sendfile`" - -#: ../../library/asyncio-llapi-index.rst:211 -msgid "Send a file over the :class:`~socket.socket`." -msgstr "透過 :class:`~socket.socket` 傳送一個檔案。" - -#: ../../library/asyncio-llapi-index.rst:213 -msgid ":meth:`loop.add_reader`" -msgstr ":meth:`loop.add_reader`" - -#: ../../library/asyncio-llapi-index.rst:214 -msgid "Start watching a file descriptor for read availability." -msgstr "開始監控一個檔案描述器 (file descriptor) 的可讀取性。" - -#: ../../library/asyncio-llapi-index.rst:216 -msgid ":meth:`loop.remove_reader`" -msgstr ":meth:`loop.remove_reader`" - -#: ../../library/asyncio-llapi-index.rst:217 -msgid "Stop watching a file descriptor for read availability." -msgstr "停止監控一個檔案描述器的可讀取性。" - -#: ../../library/asyncio-llapi-index.rst:219 -msgid ":meth:`loop.add_writer`" -msgstr ":meth:`loop.add_writer`" - -#: ../../library/asyncio-llapi-index.rst:220 -msgid "Start watching a file descriptor for write availability." -msgstr "開始監控一個檔案描述器的可寫入性。" - -#: ../../library/asyncio-llapi-index.rst:222 -msgid ":meth:`loop.remove_writer`" -msgstr ":meth:`loop.remove_writer`" - -#: ../../library/asyncio-llapi-index.rst:223 -msgid "Stop watching a file descriptor for write availability." -msgstr "停止監控一個檔案描述器的可寫入性。" - -#: ../../library/asyncio-llapi-index.rst:226 -msgid "Unix Signals" -msgstr "Unix 信號" - -#: ../../library/asyncio-llapi-index.rst:231 -msgid ":meth:`loop.add_signal_handler`" -msgstr ":meth:`loop.add_signal_handler`" - -#: ../../library/asyncio-llapi-index.rst:232 -msgid "Add a handler for a :mod:`signal`." -msgstr "為 :mod:`signal` 新增一個處理函式 (handler)。" - -#: ../../library/asyncio-llapi-index.rst:234 -msgid ":meth:`loop.remove_signal_handler`" -msgstr ":meth:`loop.remove_signal_handler`" - -#: ../../library/asyncio-llapi-index.rst:235 -msgid "Remove a handler for a :mod:`signal`." -msgstr "刪除 :mod:`signal` 的處理函式。" - -#: ../../library/asyncio-llapi-index.rst:238 -msgid "Subprocesses" -msgstr "子行程" - -#: ../../library/asyncio-llapi-index.rst:243 -msgid ":meth:`loop.subprocess_exec`" -msgstr ":meth:`loop.subprocess_exec`" - -#: ../../library/asyncio-llapi-index.rst:244 -msgid "Spawn a subprocess." -msgstr "衍生 (spawn) 一個子行程 (subprocess)。" - -#: ../../library/asyncio-llapi-index.rst:246 -msgid ":meth:`loop.subprocess_shell`" -msgstr ":meth:`loop.subprocess_shell`" - -#: ../../library/asyncio-llapi-index.rst:247 -msgid "Spawn a subprocess from a shell command." -msgstr "從 shell 指令衍生一個子行程。" - -#: ../../library/asyncio-llapi-index.rst:250 -msgid "Error Handling" -msgstr "錯誤處理" - -#: ../../library/asyncio-llapi-index.rst:255 -msgid ":meth:`loop.call_exception_handler`" -msgstr ":meth:`loop.call_exception_handler`" - -#: ../../library/asyncio-llapi-index.rst:256 -msgid "Call the exception handler." -msgstr "呼叫例外處理函式。" - -#: ../../library/asyncio-llapi-index.rst:258 -msgid ":meth:`loop.set_exception_handler`" -msgstr ":meth:`loop.set_exception_handler`" - -#: ../../library/asyncio-llapi-index.rst:259 -msgid "Set a new exception handler." -msgstr "設定一個新的例外處理函式。" - -#: ../../library/asyncio-llapi-index.rst:261 -msgid ":meth:`loop.get_exception_handler`" -msgstr ":meth:`loop.get_exception_handler`" - -#: ../../library/asyncio-llapi-index.rst:262 -msgid "Get the current exception handler." -msgstr "取得目前例外處理函式。" - -#: ../../library/asyncio-llapi-index.rst:264 -msgid ":meth:`loop.default_exception_handler`" -msgstr ":meth:`loop.default_exception_handler`" - -#: ../../library/asyncio-llapi-index.rst:265 -msgid "The default exception handler implementation." -msgstr "預設例外處理函式實作。" - -#: ../../library/asyncio-llapi-index.rst:270 -msgid "" -":ref:`Using asyncio.new_event_loop() and loop.run_forever() " -"`." -msgstr "" -":ref:`使用 asyncio.new_event_loop() 和 loop.run_forever() " -"`。" - -#: ../../library/asyncio-llapi-index.rst:273 -msgid ":ref:`Using loop.call_later() `." -msgstr ":ref:`使用 loop.call_later() `。" - -#: ../../library/asyncio-llapi-index.rst:275 -msgid "" -"Using ``loop.create_connection()`` to implement :ref:`an echo-client " -"`." -msgstr "" -"使用 ``loop.create_connection()`` 以實作\\ :ref:`一個 echo 用戶端 " -"`。" - -#: ../../library/asyncio-llapi-index.rst:278 -msgid "" -"Using ``loop.create_connection()`` to :ref:`connect a socket " -"`." -msgstr "" -"使用 ``loop.create_connection()`` 來\\ :ref:`連接 socket " -"`。" - -#: ../../library/asyncio-llapi-index.rst:281 -msgid "" -":ref:`Using add_reader() to watch an FD for read events " -"`." -msgstr "" -":ref:`使用 add_reader() 監控 FD 的讀取事件 `。" - -#: ../../library/asyncio-llapi-index.rst:284 -msgid ":ref:`Using loop.add_signal_handler() `." -msgstr ":ref:`使用 loop.add_signal_handler() `。" - -#: ../../library/asyncio-llapi-index.rst:286 -msgid ":ref:`Using loop.subprocess_exec() `." -msgstr "" -":ref:`使用 loop.add_signal_handler() `。" - -#: ../../library/asyncio-llapi-index.rst:290 -msgid "Transports" -msgstr "傳輸" - -#: ../../library/asyncio-llapi-index.rst:292 -msgid "All transports implement the following methods:" -msgstr "所有傳輸方式都有實作以下方法：" - -#: ../../library/asyncio-llapi-index.rst:298 -msgid ":meth:`transport.close() `" -msgstr ":meth:`transport.close() `" - -#: ../../library/asyncio-llapi-index.rst:299 -msgid "Close the transport." -msgstr "關閉傳輸。" - -#: ../../library/asyncio-llapi-index.rst:301 -msgid ":meth:`transport.is_closing() `" -msgstr ":meth:`transport.is_closing() `" - -#: ../../library/asyncio-llapi-index.rst:302 -msgid "Return ``True`` if the transport is closing or is closed." -msgstr "如果傳輸正在關閉或已經關閉則回傳 ``True``。" - -#: ../../library/asyncio-llapi-index.rst:304 -msgid ":meth:`transport.get_extra_info() `" -msgstr ":meth:`transport.get_extra_info() `" - -#: ../../library/asyncio-llapi-index.rst:305 -msgid "Request for information about the transport." -msgstr "請求傳輸的相關資訊。" - -#: ../../library/asyncio-llapi-index.rst:307 -msgid ":meth:`transport.set_protocol() `" -msgstr ":meth:`transport.set_protocol() `" - -#: ../../library/asyncio-llapi-index.rst:308 -msgid "Set a new protocol." -msgstr "設定一個新協定。" - -#: ../../library/asyncio-llapi-index.rst:310 -msgid ":meth:`transport.get_protocol() `" -msgstr ":meth:`transport.get_protocol() `" - -#: ../../library/asyncio-llapi-index.rst:311 -msgid "Return the current protocol." -msgstr "回傳目前協定。" - -#: ../../library/asyncio-llapi-index.rst:314 -msgid "" -"Transports that can receive data (TCP and Unix connections, pipes, etc). " -"Returned from methods " -"like :meth:`loop.create_connection`, :meth:`loop.create_unix_connection`, :meth:`loop.connect_read_pipe`, " -"etc:" -msgstr "" -"可以接收資料（TCP 和 Unix 連線、pipe 等）的傳輸。它" -"由 :meth:`loop.create_connection`、:meth:`loop.create_unix_connection`、:meth:`loop.connect_read_pipe` " -"等方法回傳：" - -#: ../../library/asyncio-llapi-index.rst:319 -msgid "Read Transports" -msgstr "讀取傳輸" - -#: ../../library/asyncio-llapi-index.rst:324 -msgid ":meth:`transport.is_reading() `" -msgstr ":meth:`transport.is_reading() `" - -#: ../../library/asyncio-llapi-index.rst:325 -msgid "Return ``True`` if the transport is receiving." -msgstr "如果傳輸正在接收則回傳 ``True``。" - -#: ../../library/asyncio-llapi-index.rst:327 -msgid ":meth:`transport.pause_reading() `" -msgstr ":meth:`transport.pause_reading() `" - -#: ../../library/asyncio-llapi-index.rst:328 -msgid "Pause receiving." -msgstr "暫停接收。" - -#: ../../library/asyncio-llapi-index.rst:330 -msgid ":meth:`transport.resume_reading() `" -msgstr ":meth:`transport.resume_reading() `" - -#: ../../library/asyncio-llapi-index.rst:331 -msgid "Resume receiving." -msgstr "繼續接收。" - -#: ../../library/asyncio-llapi-index.rst:334 -msgid "" -"Transports that can Send data (TCP and Unix connections, pipes, etc). " -"Returned from methods " -"like :meth:`loop.create_connection`, :meth:`loop.create_unix_connection`, :meth:`loop.connect_write_pipe`, " -"etc:" -msgstr "" -"可以傳送資料（TCP 和 Unix 連線、pipe 等）的傳輸。它" -"由 :meth:`loop.create_connection`、:meth:`loop.create_unix_connection`、:meth:`loop.connect_write_pipe` " -"等方法回傳：" - -#: ../../library/asyncio-llapi-index.rst:339 -msgid "Write Transports" -msgstr "寫入傳輸" - -#: ../../library/asyncio-llapi-index.rst:344 -msgid ":meth:`transport.write() `" -msgstr ":meth:`transport.write() `" - -#: ../../library/asyncio-llapi-index.rst:345 -msgid "Write data to the transport." -msgstr "將資料寫入傳輸。" - -#: ../../library/asyncio-llapi-index.rst:347 -msgid ":meth:`transport.writelines() `" -msgstr ":meth:`transport.writelines() `" - -#: ../../library/asyncio-llapi-index.rst:348 -msgid "Write buffers to the transport." -msgstr "將緩衝區資料寫入傳輸。" - -#: ../../library/asyncio-llapi-index.rst:350 -msgid ":meth:`transport.can_write_eof() `" -msgstr ":meth:`transport.can_write_eof() `" - -#: ../../library/asyncio-llapi-index.rst:351 -msgid "Return :const:`True` if the transport supports sending EOF." -msgstr "如果傳輸支援傳送 EOF 則回傳 :const:`True`。" - -#: ../../library/asyncio-llapi-index.rst:353 -msgid ":meth:`transport.write_eof() `" -msgstr ":meth:`transport.write_eof() `" - -#: ../../library/asyncio-llapi-index.rst:354 -msgid "Close and send EOF after flushing buffered data." -msgstr "在清除 (flush) 已緩衝的資料後關閉傳輸並傳送 EOF。" - -#: ../../library/asyncio-llapi-index.rst:356 -msgid ":meth:`transport.abort() `" -msgstr ":meth:`transport.abort() `" - -#: ../../library/asyncio-llapi-index.rst:357 -#: ../../library/asyncio-llapi-index.rst:383 -msgid "Close the transport immediately." -msgstr "立即關閉傳輸。" - -#: ../../library/asyncio-llapi-index.rst:359 -msgid "" -":meth:`transport.get_write_buffer_size() " -"`" -msgstr "" -":meth:`transport.get_write_buffer_size() " -"`" - -#: ../../library/asyncio-llapi-index.rst:361 -msgid "Return the current size of the output buffer." -msgstr "回傳目前輸出緩衝區的大小。" - -#: ../../library/asyncio-llapi-index.rst:363 -msgid "" -":meth:`transport.get_write_buffer_limits() " -"`" -msgstr "" -":meth:`transport.get_write_buffer_limits() " -"`" - -#: ../../library/asyncio-llapi-index.rst:365 -msgid "Return high and low water marks for write flow control." -msgstr "" -"回傳用於寫入流量控制 (write flow control) 的高低標記位 (high and low water " -"marks)。" - -#: ../../library/asyncio-llapi-index.rst:367 -msgid "" -":meth:`transport.set_write_buffer_limits() " -"`" -msgstr "" -":meth:`transport.set_write_buffer_limits() " -"`" - -#: ../../library/asyncio-llapi-index.rst:369 -msgid "Set new high and low water marks for write flow control." -msgstr "為寫入流量控制設定高低標記位。" - -#: ../../library/asyncio-llapi-index.rst:372 -msgid "Transports returned by :meth:`loop.create_datagram_endpoint`:" -msgstr "由 :meth:`loop.create_datagram_endpoint` 回傳的傳輸：" - -#: ../../library/asyncio-llapi-index.rst:374 -msgid "Datagram Transports" -msgstr "資料單元傳輸" - -#: ../../library/asyncio-llapi-index.rst:379 -msgid ":meth:`transport.sendto() `" -msgstr ":meth:`transport.sendto() `" - -#: ../../library/asyncio-llapi-index.rst:380 -msgid "Send data to the remote peer." -msgstr "傳送資料到連線遠端。" - -#: ../../library/asyncio-llapi-index.rst:382 -msgid ":meth:`transport.abort() `" -msgstr ":meth:`transport.abort() `" - -#: ../../library/asyncio-llapi-index.rst:386 -msgid "" -"Low-level transport abstraction over subprocesses. Returned " -"by :meth:`loop.subprocess_exec` and :meth:`loop.subprocess_shell`:" -msgstr "" -"基於子行程的低階傳輸抽象，它會由 :meth:`loop.subprocess_exec` " -"和 :meth:`loop.subprocess_shell` 所回傳：" - -#: ../../library/asyncio-llapi-index.rst:390 -msgid "Subprocess Transports" -msgstr "子行程傳輸" - -#: ../../library/asyncio-llapi-index.rst:395 -msgid ":meth:`transport.get_pid() `" -msgstr ":meth:`transport.get_pid() `" - -#: ../../library/asyncio-llapi-index.rst:396 -msgid "Return the subprocess process id." -msgstr "回傳子行程的行程 id。" - -#: ../../library/asyncio-llapi-index.rst:398 -msgid "" -":meth:`transport.get_pipe_transport() " -"`" -msgstr "" -":meth:`transport.get_pipe_transport() " -"`" - -#: ../../library/asyncio-llapi-index.rst:400 -msgid "" -"Return the transport for the requested communication pipe (*stdin*, " -"*stdout*, or *stderr*)." -msgstr "回傳被請求用於通訊 pipe （*stdin*、*stdout* 或 *stderr*）的傳輸。" - -#: ../../library/asyncio-llapi-index.rst:403 -msgid ":meth:`transport.get_returncode() `" -msgstr "" -":meth:`transport.get_returncode() `" - -#: ../../library/asyncio-llapi-index.rst:404 -msgid "Return the subprocess return code." -msgstr "回傳子行程的回傳代號 (return code)。" - -#: ../../library/asyncio-llapi-index.rst:406 -msgid ":meth:`transport.kill() `" -msgstr ":meth:`transport.kill() `" - -#: ../../library/asyncio-llapi-index.rst:407 -msgid "Kill the subprocess." -msgstr "殺死子行程。" - -#: ../../library/asyncio-llapi-index.rst:409 -msgid ":meth:`transport.send_signal() `" -msgstr ":meth:`transport.send_signal() `" - -#: ../../library/asyncio-llapi-index.rst:410 -msgid "Send a signal to the subprocess." -msgstr "傳送一個訊號到子行程。" - -#: ../../library/asyncio-llapi-index.rst:412 -msgid ":meth:`transport.terminate() `" -msgstr ":meth:`transport.terminate() `" - -#: ../../library/asyncio-llapi-index.rst:413 -msgid "Stop the subprocess." -msgstr "停止子行程。" - -#: ../../library/asyncio-llapi-index.rst:415 -msgid ":meth:`transport.close() `" -msgstr ":meth:`transport.close() `" - -#: ../../library/asyncio-llapi-index.rst:416 -msgid "Kill the subprocess and close all pipes." -msgstr "殺死子行程並關閉所有 pipes。" - -#: ../../library/asyncio-llapi-index.rst:420 -msgid "Protocols" -msgstr "協定" - -#: ../../library/asyncio-llapi-index.rst:422 -msgid "Protocol classes can implement the following **callback methods**:" -msgstr "協定類別可以實作以下\\ **回呼方法**：" - -#: ../../library/asyncio-llapi-index.rst:428 -msgid "``callback`` :meth:`connection_made() `" -msgstr "``callback`` :meth:`connection_made() `" - -#: ../../library/asyncio-llapi-index.rst:429 -msgid "Called when a connection is made." -msgstr "在連線建立時被呼叫。" - -#: ../../library/asyncio-llapi-index.rst:431 -msgid "``callback`` :meth:`connection_lost() `" -msgstr "``callback`` :meth:`connection_lost() `" - -#: ../../library/asyncio-llapi-index.rst:432 -msgid "Called when the connection is lost or closed." -msgstr "在失去連線或連線關閉時被呼叫。" - -#: ../../library/asyncio-llapi-index.rst:434 -msgid "``callback`` :meth:`pause_writing() `" -msgstr "``callback`` :meth:`pause_writing() `" - -#: ../../library/asyncio-llapi-index.rst:435 -msgid "Called when the transport's buffer goes over the high water mark." -msgstr "在傳輸緩衝區超過高標記位時被呼叫。" - -#: ../../library/asyncio-llapi-index.rst:437 -msgid "``callback`` :meth:`resume_writing() `" -msgstr "``callback`` :meth:`resume_writing() `" - -#: ../../library/asyncio-llapi-index.rst:438 -msgid "Called when the transport's buffer drains below the low water mark." -msgstr "在傳輸緩衝區低於低標記位時被呼叫。" - -#: ../../library/asyncio-llapi-index.rst:441 -msgid "Streaming Protocols (TCP, Unix Sockets, Pipes)" -msgstr "串流協定 (TCP, Unix socket, Pipes)" - -#: ../../library/asyncio-llapi-index.rst:446 -msgid "``callback`` :meth:`data_received() `" -msgstr "``callback`` :meth:`data_received() `" - -#: ../../library/asyncio-llapi-index.rst:447 -msgid "Called when some data is received." -msgstr "在接收到資料時被呼叫。" - -#: ../../library/asyncio-llapi-index.rst:449 -msgid "``callback`` :meth:`eof_received() `" -msgstr "``callback`` :meth:`eof_received() `" - -#: ../../library/asyncio-llapi-index.rst:450 -#: ../../library/asyncio-llapi-index.rst:465 -msgid "Called when an EOF is received." -msgstr "在接收到 EOF 時被呼叫。" - -#: ../../library/asyncio-llapi-index.rst:453 -msgid "Buffered Streaming Protocols" -msgstr "緩衝串流協定" - -#: ../../library/asyncio-llapi-index.rst:458 -msgid "``callback`` :meth:`get_buffer() `" -msgstr "``callback`` :meth:`get_buffer() `" - -#: ../../library/asyncio-llapi-index.rst:459 -msgid "Called to allocate a new receive buffer." -msgstr "呼叫後會分配新的接收緩衝區。" - -#: ../../library/asyncio-llapi-index.rst:461 -msgid "``callback`` :meth:`buffer_updated() `" -msgstr "" -"``callback`` :meth:`buffer_updated() `" - -#: ../../library/asyncio-llapi-index.rst:462 -msgid "Called when the buffer was updated with the received data." -msgstr "在以接收到的資料更新緩衝區時被呼叫。" - -#: ../../library/asyncio-llapi-index.rst:464 -msgid "``callback`` :meth:`eof_received() `" -msgstr "``callback`` :meth:`eof_received() `" - -#: ../../library/asyncio-llapi-index.rst:468 -msgid "Datagram Protocols" -msgstr "資料單元協定" - -#: ../../library/asyncio-llapi-index.rst:473 -msgid "" -"``callback`` :meth:`datagram_received() `" -msgstr "" -"``callback`` :meth:`datagram_received() `" - -#: ../../library/asyncio-llapi-index.rst:475 -msgid "Called when a datagram is received." -msgstr "在接收到資料單元時被呼叫。" - -#: ../../library/asyncio-llapi-index.rst:477 -msgid "``callback`` :meth:`error_received() `" -msgstr "" -"``callback`` :meth:`error_received() `" - -#: ../../library/asyncio-llapi-index.rst:478 -msgid "" -"Called when a previous send or receive operation raises an :class:`OSError`." -msgstr "在前一個傳送或接收操作引發 :class:`OSError` 時被呼叫。" - -#: ../../library/asyncio-llapi-index.rst:482 -msgid "Subprocess Protocols" -msgstr "子行程協定" - -#: ../../library/asyncio-llapi-index.rst:487 -msgid "``callback`` :meth:`~SubprocessProtocol.pipe_data_received`" -msgstr "``callback`` :meth:`~SubprocessProtocol.pipe_data_received`" - -#: ../../library/asyncio-llapi-index.rst:488 -msgid "" -"Called when the child process writes data into its *stdout* or *stderr* pipe." -msgstr "在子行程向 *stdout* 或 *stderr* pipe 寫入資料時被呼叫。" - -#: ../../library/asyncio-llapi-index.rst:491 -msgid "``callback`` :meth:`~SubprocessProtocol.pipe_connection_lost`" -msgstr "``callback`` :meth:`~SubprocessProtocol.pipe_connection_lost`" - -#: ../../library/asyncio-llapi-index.rst:492 -msgid "" -"Called when one of the pipes communicating with the child process is closed." -msgstr "在與子行程通訊的其中一個 pipes 關閉時被呼叫。" - -#: ../../library/asyncio-llapi-index.rst:495 -msgid "" -"``callback`` :meth:`process_exited() `" -msgstr "" -"``callback`` :meth:`process_exited() `" - -#: ../../library/asyncio-llapi-index.rst:497 -msgid "" -"Called when the child process has exited. It can be called " -"before :meth:`~SubprocessProtocol.pipe_data_received` " -"and :meth:`~SubprocessProtocol.pipe_connection_lost` methods." -msgstr "" -"在子行程退出時呼叫。它可以在 :meth:`~SubprocessProtocol.pipe_data_received` " -"和 :meth:`~SubprocessProtocol.pipe_connection_lost` 方法之前呼叫。" - -#: ../../library/asyncio-llapi-index.rst:503 -msgid "Event Loop Policies" -msgstr "事件迴圈 Policies" - -#: ../../library/asyncio-llapi-index.rst:505 -msgid "" -"Policies is a low-level mechanism to alter the behavior of functions " -"like :func:`asyncio.get_event_loop`. See also the main :ref:`policies " -"section ` for more details." -msgstr "" -"Policy 是改變 :func:`asyncio.get_event_loop` 這類函式行為的一個低階機制。更多" -"細節請見 :ref:`Policy 相關段落 `。" - -#: ../../library/asyncio-llapi-index.rst:511 -msgid "Accessing Policies" -msgstr "存取 Policy" - -#: ../../library/asyncio-llapi-index.rst:516 -msgid ":meth:`asyncio.get_event_loop_policy`" -msgstr ":meth:`asyncio.get_event_loop_policy`" - -#: ../../library/asyncio-llapi-index.rst:517 -msgid "Return the current process-wide policy." -msgstr "回傳目前整個行程中的 Policy。" - -#: ../../library/asyncio-llapi-index.rst:519 -msgid ":meth:`asyncio.set_event_loop_policy`" -msgstr ":meth:`asyncio.set_event_loop_policy`" - -#: ../../library/asyncio-llapi-index.rst:520 -msgid "Set a new process-wide policy." -msgstr "設定整個行程中的一個新 Policy。" - -#: ../../library/asyncio-llapi-index.rst:522 -msgid ":class:`AbstractEventLoopPolicy`" -msgstr ":class:`AbstractEventLoopPolicy`" - -#: ../../library/asyncio-llapi-index.rst:523 -msgid "Base class for policy objects." -msgstr "Policy 物件的基礎類別。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Matt Wang , 2022-2023 +# +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: 2023-10-12 11:27+0800\n" +"Last-Translator: Matt Wang \n" +"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" +"tw)\n" +"Language: zh_TW\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"X-Generator: Poedit 3.0.1\n" + +#: ../../library/asyncio-llapi-index.rst:6 +msgid "Low-level API Index" +msgstr "低階 API 索引" + +#: ../../library/asyncio-llapi-index.rst:8 +msgid "This page lists all low-level asyncio APIs." +msgstr "本頁列出所有低階 asyncio APIs。" + +#: ../../library/asyncio-llapi-index.rst:12 +msgid "Obtaining the Event Loop" +msgstr "取得事件迴圈" + +#: ../../library/asyncio-llapi-index.rst:18 +msgid ":func:`asyncio.get_running_loop`" +msgstr ":func:`asyncio.get_running_loop`" + +#: ../../library/asyncio-llapi-index.rst:19 +msgid "The **preferred** function to get the running event loop." +msgstr "**推薦使用**\\ 於取得目前運行事件迴圈 (event loop) 的函式。" + +#: ../../library/asyncio-llapi-index.rst:21 +msgid ":func:`asyncio.get_event_loop`" +msgstr ":func:`asyncio.get_event_loop`" + +#: ../../library/asyncio-llapi-index.rst:22 +msgid "Get an event loop instance (running or current via the current policy)." +msgstr "獲得一個（正在運行的或透過目前 policy 建立的）事件迴圈實例。" + +#: ../../library/asyncio-llapi-index.rst:24 +msgid ":func:`asyncio.set_event_loop`" +msgstr ":func:`asyncio.set_event_loop`" + +#: ../../library/asyncio-llapi-index.rst:25 +msgid "Set the event loop as current via the current policy." +msgstr "透過目前 policy 來設定目前事件迴圈。" + +#: ../../library/asyncio-llapi-index.rst:27 +msgid ":func:`asyncio.new_event_loop`" +msgstr ":func:`asyncio.new_event_loop`" + +#: ../../library/asyncio-llapi-index.rst:28 +msgid "Create a new event loop." +msgstr "建立一個新的事件迴圈。" + +#: ../../library/asyncio-llapi-index.rst:32 +#: ../../library/asyncio-llapi-index.rst:269 +msgid "Examples" +msgstr "範例" + +#: ../../library/asyncio-llapi-index.rst:33 +msgid ":ref:`Using asyncio.get_running_loop() `." +msgstr ":ref:`使用 asyncio.get_running_loop() `。" + +#: ../../library/asyncio-llapi-index.rst:37 +msgid "Event Loop Methods" +msgstr "事件迴圈方法" + +#: ../../library/asyncio-llapi-index.rst:39 +msgid "" +"See also the main documentation section about the :ref:`asyncio-event-loop-" +"methods`." +msgstr "也請查閱文件中關於\\ :ref:`asyncio-event-loop-methods`\\ 的主要段落。" + +#: ../../library/asyncio-llapi-index.rst:42 +msgid "Lifecycle" +msgstr "生命週期" + +#: ../../library/asyncio-llapi-index.rst:47 +msgid ":meth:`loop.run_until_complete`" +msgstr ":meth:`loop.run_until_complete`" + +#: ../../library/asyncio-llapi-index.rst:48 +msgid "Run a Future/Task/awaitable until complete." +msgstr "執行一個 Future/Task/awaitable（可等待物件）直到完成。" + +#: ../../library/asyncio-llapi-index.rst:50 +msgid ":meth:`loop.run_forever`" +msgstr ":meth:`loop.run_forever`" + +#: ../../library/asyncio-llapi-index.rst:51 +msgid "Run the event loop forever." +msgstr "持續運行事件迴圈。" + +#: ../../library/asyncio-llapi-index.rst:53 +msgid ":meth:`loop.stop`" +msgstr ":meth:`loop.stop`" + +#: ../../library/asyncio-llapi-index.rst:54 +msgid "Stop the event loop." +msgstr "停止事件迴圈。" + +#: ../../library/asyncio-llapi-index.rst:56 +msgid ":meth:`loop.close`" +msgstr ":meth:`loop.close`" + +#: ../../library/asyncio-llapi-index.rst:57 +msgid "Close the event loop." +msgstr "關閉事件迴圈。" + +#: ../../library/asyncio-llapi-index.rst:59 +msgid ":meth:`loop.is_running`" +msgstr ":meth:`loop.is_running`" + +#: ../../library/asyncio-llapi-index.rst:60 +msgid "Return ``True`` if the event loop is running." +msgstr "如果事件迴圈正在執行則回傳 ``True``。" + +#: ../../library/asyncio-llapi-index.rst:62 +msgid ":meth:`loop.is_closed`" +msgstr ":meth:`loop.is_closed`" + +#: ../../library/asyncio-llapi-index.rst:63 +msgid "Return ``True`` if the event loop is closed." +msgstr "如果事件迴圈已經被關閉則回傳 ``True``。" + +#: ../../library/asyncio-llapi-index.rst:65 +msgid "``await`` :meth:`loop.shutdown_asyncgens`" +msgstr "``await`` :meth:`loop.shutdown_asyncgens`" + +#: ../../library/asyncio-llapi-index.rst:66 +msgid "Close asynchronous generators." +msgstr "關閉非同步產生器 (asynchronous generators)。" + +#: ../../library/asyncio-llapi-index.rst:69 +msgid "Debugging" +msgstr "除錯" + +#: ../../library/asyncio-llapi-index.rst:74 +msgid ":meth:`loop.set_debug`" +msgstr ":meth:`loop.set_debug`" + +#: ../../library/asyncio-llapi-index.rst:75 +msgid "Enable or disable the debug mode." +msgstr "開啟或禁用除錯模式。" + +#: ../../library/asyncio-llapi-index.rst:77 +msgid ":meth:`loop.get_debug`" +msgstr ":meth:`loop.get_debug`" + +#: ../../library/asyncio-llapi-index.rst:78 +msgid "Get the current debug mode." +msgstr "取得目前除錯模式。" + +#: ../../library/asyncio-llapi-index.rst:81 +msgid "Scheduling Callbacks" +msgstr "為回呼函式排程" + +#: ../../library/asyncio-llapi-index.rst:86 +msgid ":meth:`loop.call_soon`" +msgstr ":meth:`loop.call_soon`" + +#: ../../library/asyncio-llapi-index.rst:87 +msgid "Invoke a callback soon." +msgstr "儘快呼叫回呼函式 (callback)。" + +#: ../../library/asyncio-llapi-index.rst:89 +msgid ":meth:`loop.call_soon_threadsafe`" +msgstr ":meth:`loop.call_soon_threadsafe`" + +#: ../../library/asyncio-llapi-index.rst:90 +msgid "A thread-safe variant of :meth:`loop.call_soon`." +msgstr ":meth:`loop.call_soon` 方法之有支援執行緒安全 (thread-safe) 變體。" + +#: ../../library/asyncio-llapi-index.rst:92 +msgid ":meth:`loop.call_later`" +msgstr ":meth:`loop.call_later`" + +#: ../../library/asyncio-llapi-index.rst:93 +msgid "Invoke a callback *after* the given time." +msgstr "在給定時間\\ *之後*\\ 呼叫回呼函式。" + +#: ../../library/asyncio-llapi-index.rst:95 +msgid ":meth:`loop.call_at`" +msgstr ":meth:`loop.call_at`" + +#: ../../library/asyncio-llapi-index.rst:96 +msgid "Invoke a callback *at* the given time." +msgstr "在給定時間\\ *當下*\\ 呼叫回呼函式。" + +#: ../../library/asyncio-llapi-index.rst:99 +msgid "Thread/Interpreter/Process Pool" +msgstr "執行緒 (Thread)/直譯器 (Interpreter)/行程池 (Process Pool)" + +#: ../../library/asyncio-llapi-index.rst:104 +msgid "``await`` :meth:`loop.run_in_executor`" +msgstr "``await`` :meth:`loop.run_in_executor`" + +#: ../../library/asyncio-llapi-index.rst:105 +msgid "" +"Run a CPU-bound or other blocking function in a :mod:`concurrent.futures` " +"executor." +msgstr "" +"在 :mod:`concurrent.futures` 執行器 (excutor) 中執行一個 CPU 密集型 (CPU-" +"bound) 或其它阻塞型式的函式。" + +#: ../../library/asyncio-llapi-index.rst:108 +msgid ":meth:`loop.set_default_executor`" +msgstr ":meth:`loop.set_default_executor`" + +#: ../../library/asyncio-llapi-index.rst:109 +msgid "Set the default executor for :meth:`loop.run_in_executor`." +msgstr "為 :meth:`loop.run_in_executor` 設定預設執行器。" + +#: ../../library/asyncio-llapi-index.rst:112 +msgid "Tasks and Futures" +msgstr "Tasks 與 Futures" + +#: ../../library/asyncio-llapi-index.rst:117 +msgid ":meth:`loop.create_future`" +msgstr ":meth:`loop.create_future`" + +#: ../../library/asyncio-llapi-index.rst:118 +msgid "Create a :class:`Future` object." +msgstr "建立一個 :class:`Future` 物件。" + +#: ../../library/asyncio-llapi-index.rst:120 +msgid ":meth:`loop.create_task`" +msgstr ":meth:`loop.create_task`" + +#: ../../library/asyncio-llapi-index.rst:121 +msgid "Schedule coroutine as a :class:`Task`." +msgstr "像是 :class:`Task` 一樣，為協程 (coroutine) 排程。" + +#: ../../library/asyncio-llapi-index.rst:123 +msgid ":meth:`loop.set_task_factory`" +msgstr ":meth:`loop.set_task_factory`" + +#: ../../library/asyncio-llapi-index.rst:124 +msgid "" +"Set a factory used by :meth:`loop.create_task` to create :class:`Tasks " +"`." +msgstr "" +"設定被 :meth:`loop.create_task` 用來建立 :class:`Tasks ` 的工廠函式 " +"(factory)。" + +#: ../../library/asyncio-llapi-index.rst:127 +msgid ":meth:`loop.get_task_factory`" +msgstr ":meth:`loop.get_task_factory`" + +#: ../../library/asyncio-llapi-index.rst:128 +msgid "" +"Get the factory :meth:`loop.create_task` uses to create :class:`Tasks " +"`." +msgstr "" +"取得被 :meth:`loop.create_task` 用來建立 :class:`Tasks ` 的工廠函式。" + +#: ../../library/asyncio-llapi-index.rst:132 +msgid "DNS" +msgstr "DNS" + +#: ../../library/asyncio-llapi-index.rst:137 +msgid "``await`` :meth:`loop.getaddrinfo`" +msgstr "``await`` :meth:`loop.getaddrinfo`" + +#: ../../library/asyncio-llapi-index.rst:138 +msgid "Asynchronous version of :meth:`socket.getaddrinfo`." +msgstr "非同步版本的 :meth:`socket.getaddrinfo`。" + +#: ../../library/asyncio-llapi-index.rst:140 +msgid "``await`` :meth:`loop.getnameinfo`" +msgstr "``await`` :meth:`loop.getnameinfo`" + +#: ../../library/asyncio-llapi-index.rst:141 +msgid "Asynchronous version of :meth:`socket.getnameinfo`." +msgstr "非同步版本的 :meth:`socket.getnameinfo`。" + +#: ../../library/asyncio-llapi-index.rst:144 +msgid "Networking and IPC" +msgstr "網路和 IPC" + +#: ../../library/asyncio-llapi-index.rst:149 +msgid "``await`` :meth:`loop.create_connection`" +msgstr "``await`` :meth:`loop.create_connection`" + +#: ../../library/asyncio-llapi-index.rst:150 +msgid "Open a TCP connection." +msgstr "開啟一個 TCP 連線。" + +#: ../../library/asyncio-llapi-index.rst:152 +msgid "``await`` :meth:`loop.create_server`" +msgstr "``await`` :meth:`loop.create_server`" + +#: ../../library/asyncio-llapi-index.rst:153 +msgid "Create a TCP server." +msgstr "建立一個 TCP 伺服器。" + +#: ../../library/asyncio-llapi-index.rst:155 +msgid "``await`` :meth:`loop.create_unix_connection`" +msgstr "``await`` :meth:`loop.create_unix_connection`" + +#: ../../library/asyncio-llapi-index.rst:156 +msgid "Open a Unix socket connection." +msgstr "開啟一個 Unix socket 連線。" + +#: ../../library/asyncio-llapi-index.rst:158 +msgid "``await`` :meth:`loop.create_unix_server`" +msgstr "``await`` :meth:`loop.create_unix_server`" + +#: ../../library/asyncio-llapi-index.rst:159 +msgid "Create a Unix socket server." +msgstr "建立一個 Unix socket 伺服器。" + +#: ../../library/asyncio-llapi-index.rst:161 +msgid "``await`` :meth:`loop.connect_accepted_socket`" +msgstr "``await`` :meth:`loop.connect_accepted_socket`" + +#: ../../library/asyncio-llapi-index.rst:162 +msgid "Wrap a :class:`~socket.socket` into a ``(transport, protocol)`` pair." +msgstr "將 :class:`~socket.socket` 包裝成 ``(transport, protocol)``。" + +#: ../../library/asyncio-llapi-index.rst:165 +msgid "``await`` :meth:`loop.create_datagram_endpoint`" +msgstr "``await`` :meth:`loop.create_datagram_endpoint`" + +#: ../../library/asyncio-llapi-index.rst:166 +msgid "Open a datagram (UDP) connection." +msgstr "開啟一個資料單元 (datagram) (UDP) 連線。" + +#: ../../library/asyncio-llapi-index.rst:168 +msgid "``await`` :meth:`loop.sendfile`" +msgstr "``await`` :meth:`loop.sendfile`" + +#: ../../library/asyncio-llapi-index.rst:169 +msgid "Send a file over a transport." +msgstr "透過傳輸通道傳送一個檔案。" + +#: ../../library/asyncio-llapi-index.rst:171 +msgid "``await`` :meth:`loop.start_tls`" +msgstr "``await`` :meth:`loop.start_tls`" + +#: ../../library/asyncio-llapi-index.rst:172 +msgid "Upgrade an existing connection to TLS." +msgstr "將一個已存在的連線升級到 TLS。" + +#: ../../library/asyncio-llapi-index.rst:174 +msgid "``await`` :meth:`loop.connect_read_pipe`" +msgstr "``await`` :meth:`loop.connect_read_pipe`" + +#: ../../library/asyncio-llapi-index.rst:175 +msgid "Wrap a read end of a pipe into a ``(transport, protocol)`` pair." +msgstr "將 pipe（管道）讀取端包裝成 ``(transport, protocol)``。" + +#: ../../library/asyncio-llapi-index.rst:177 +msgid "``await`` :meth:`loop.connect_write_pipe`" +msgstr "``await`` :meth:`loop.connect_write_pipe`" + +#: ../../library/asyncio-llapi-index.rst:178 +msgid "Wrap a write end of a pipe into a ``(transport, protocol)`` pair." +msgstr "將 pipe 寫入端包裝成 ``(transport, protocol)``。" + +#: ../../library/asyncio-llapi-index.rst:181 +msgid "Sockets" +msgstr "Sockets" + +#: ../../library/asyncio-llapi-index.rst:186 +msgid "``await`` :meth:`loop.sock_recv`" +msgstr "``await`` :meth:`loop.sock_recv`" + +#: ../../library/asyncio-llapi-index.rst:187 +msgid "Receive data from the :class:`~socket.socket`." +msgstr "從 :class:`~socket.socket` 接收資料。" + +#: ../../library/asyncio-llapi-index.rst:189 +msgid "``await`` :meth:`loop.sock_recv_into`" +msgstr "``await`` :meth:`loop.sock_recv_into`" + +#: ../../library/asyncio-llapi-index.rst:190 +msgid "Receive data from the :class:`~socket.socket` into a buffer." +msgstr "" +"將從 :class:`~socket.socket` 接收到的資料存放於一個緩衝區 (buffer) 中。" + +#: ../../library/asyncio-llapi-index.rst:192 +msgid "``await`` :meth:`loop.sock_recvfrom`" +msgstr "``await`` :meth:`loop.sock_recvfrom`" + +#: ../../library/asyncio-llapi-index.rst:193 +msgid "Receive a datagram from the :class:`~socket.socket`." +msgstr "從 :class:`~socket.socket` 接收一個資料單元。" + +#: ../../library/asyncio-llapi-index.rst:195 +msgid "``await`` :meth:`loop.sock_recvfrom_into`" +msgstr "``await`` :meth:`loop.sock_recvfrom_into`" + +#: ../../library/asyncio-llapi-index.rst:196 +msgid "Receive a datagram from the :class:`~socket.socket` into a buffer." +msgstr "將從 :class:`~socket.socket` 接收到的資料單元存放於一個緩衝區中。" + +#: ../../library/asyncio-llapi-index.rst:198 +msgid "``await`` :meth:`loop.sock_sendall`" +msgstr "``await`` :meth:`loop.sock_sendall`" + +#: ../../library/asyncio-llapi-index.rst:199 +msgid "Send data to the :class:`~socket.socket`." +msgstr "傳送資料到 :class:`~socket.socket`。" + +#: ../../library/asyncio-llapi-index.rst:201 +msgid "``await`` :meth:`loop.sock_sendto`" +msgstr "``await`` :meth:`loop.sock_sendto`" + +#: ../../library/asyncio-llapi-index.rst:202 +msgid "Send a datagram via the :class:`~socket.socket` to the given address." +msgstr "透過 :class:`~socket.socket` 將資料單元傳送至給定的地址。" + +#: ../../library/asyncio-llapi-index.rst:204 +msgid "``await`` :meth:`loop.sock_connect`" +msgstr "``await`` :meth:`loop.sock_connect`" + +#: ../../library/asyncio-llapi-index.rst:205 +msgid "Connect the :class:`~socket.socket`." +msgstr "連接 :class:`~socket.socket`。" + +#: ../../library/asyncio-llapi-index.rst:207 +msgid "``await`` :meth:`loop.sock_accept`" +msgstr "``await`` :meth:`loop.sock_accept`" + +#: ../../library/asyncio-llapi-index.rst:208 +msgid "Accept a :class:`~socket.socket` connection." +msgstr "接受一個 :class:`~socket.socket` 連線。" + +#: ../../library/asyncio-llapi-index.rst:210 +msgid "``await`` :meth:`loop.sock_sendfile`" +msgstr "``await`` :meth:`loop.sock_sendfile`" + +#: ../../library/asyncio-llapi-index.rst:211 +msgid "Send a file over the :class:`~socket.socket`." +msgstr "透過 :class:`~socket.socket` 傳送一個檔案。" + +#: ../../library/asyncio-llapi-index.rst:213 +msgid ":meth:`loop.add_reader`" +msgstr ":meth:`loop.add_reader`" + +#: ../../library/asyncio-llapi-index.rst:214 +msgid "Start watching a file descriptor for read availability." +msgstr "開始監控一個檔案描述器 (file descriptor) 的可讀取性。" + +#: ../../library/asyncio-llapi-index.rst:216 +msgid ":meth:`loop.remove_reader`" +msgstr ":meth:`loop.remove_reader`" + +#: ../../library/asyncio-llapi-index.rst:217 +msgid "Stop watching a file descriptor for read availability." +msgstr "停止監控一個檔案描述器的可讀取性。" + +#: ../../library/asyncio-llapi-index.rst:219 +msgid ":meth:`loop.add_writer`" +msgstr ":meth:`loop.add_writer`" + +#: ../../library/asyncio-llapi-index.rst:220 +msgid "Start watching a file descriptor for write availability." +msgstr "開始監控一個檔案描述器的可寫入性。" + +#: ../../library/asyncio-llapi-index.rst:222 +msgid ":meth:`loop.remove_writer`" +msgstr ":meth:`loop.remove_writer`" + +#: ../../library/asyncio-llapi-index.rst:223 +msgid "Stop watching a file descriptor for write availability." +msgstr "停止監控一個檔案描述器的可寫入性。" + +#: ../../library/asyncio-llapi-index.rst:226 +msgid "Unix Signals" +msgstr "Unix 信號" + +#: ../../library/asyncio-llapi-index.rst:231 +msgid ":meth:`loop.add_signal_handler`" +msgstr ":meth:`loop.add_signal_handler`" + +#: ../../library/asyncio-llapi-index.rst:232 +msgid "Add a handler for a :mod:`signal`." +msgstr "為 :mod:`signal` 新增一個處理函式 (handler)。" + +#: ../../library/asyncio-llapi-index.rst:234 +msgid ":meth:`loop.remove_signal_handler`" +msgstr ":meth:`loop.remove_signal_handler`" + +#: ../../library/asyncio-llapi-index.rst:235 +msgid "Remove a handler for a :mod:`signal`." +msgstr "刪除 :mod:`signal` 的處理函式。" + +#: ../../library/asyncio-llapi-index.rst:238 +msgid "Subprocesses" +msgstr "子行程" + +#: ../../library/asyncio-llapi-index.rst:243 +msgid ":meth:`loop.subprocess_exec`" +msgstr ":meth:`loop.subprocess_exec`" + +#: ../../library/asyncio-llapi-index.rst:244 +msgid "Spawn a subprocess." +msgstr "衍生 (spawn) 一個子行程 (subprocess)。" + +#: ../../library/asyncio-llapi-index.rst:246 +msgid ":meth:`loop.subprocess_shell`" +msgstr ":meth:`loop.subprocess_shell`" + +#: ../../library/asyncio-llapi-index.rst:247 +msgid "Spawn a subprocess from a shell command." +msgstr "從 shell 指令衍生一個子行程。" + +#: ../../library/asyncio-llapi-index.rst:250 +msgid "Error Handling" +msgstr "錯誤處理" + +#: ../../library/asyncio-llapi-index.rst:255 +msgid ":meth:`loop.call_exception_handler`" +msgstr ":meth:`loop.call_exception_handler`" + +#: ../../library/asyncio-llapi-index.rst:256 +msgid "Call the exception handler." +msgstr "呼叫例外處理函式。" + +#: ../../library/asyncio-llapi-index.rst:258 +msgid ":meth:`loop.set_exception_handler`" +msgstr ":meth:`loop.set_exception_handler`" + +#: ../../library/asyncio-llapi-index.rst:259 +msgid "Set a new exception handler." +msgstr "設定一個新的例外處理函式。" + +#: ../../library/asyncio-llapi-index.rst:261 +msgid ":meth:`loop.get_exception_handler`" +msgstr ":meth:`loop.get_exception_handler`" + +#: ../../library/asyncio-llapi-index.rst:262 +msgid "Get the current exception handler." +msgstr "取得目前例外處理函式。" + +#: ../../library/asyncio-llapi-index.rst:264 +msgid ":meth:`loop.default_exception_handler`" +msgstr ":meth:`loop.default_exception_handler`" + +#: ../../library/asyncio-llapi-index.rst:265 +msgid "The default exception handler implementation." +msgstr "預設例外處理函式實作。" + +#: ../../library/asyncio-llapi-index.rst:270 +msgid "" +":ref:`Using asyncio.new_event_loop() and loop.run_forever() " +"`." +msgstr "" +":ref:`使用 asyncio.new_event_loop() 和 loop.run_forever() " +"`。" + +#: ../../library/asyncio-llapi-index.rst:273 +msgid ":ref:`Using loop.call_later() `." +msgstr ":ref:`使用 loop.call_later() `。" + +#: ../../library/asyncio-llapi-index.rst:275 +msgid "" +"Using ``loop.create_connection()`` to implement :ref:`an echo-client " +"`." +msgstr "" +"使用 ``loop.create_connection()`` 以實作\\ :ref:`一個 echo 用戶端 " +"`。" + +#: ../../library/asyncio-llapi-index.rst:278 +msgid "" +"Using ``loop.create_connection()`` to :ref:`connect a socket " +"`." +msgstr "" +"使用 ``loop.create_connection()`` 來\\ :ref:`連接 socket " +"`。" + +#: ../../library/asyncio-llapi-index.rst:281 +msgid "" +":ref:`Using add_reader() to watch an FD for read events " +"`." +msgstr "" +":ref:`使用 add_reader() 監控 FD 的讀取事件 `。" + +#: ../../library/asyncio-llapi-index.rst:284 +msgid ":ref:`Using loop.add_signal_handler() `." +msgstr ":ref:`使用 loop.add_signal_handler() `。" + +#: ../../library/asyncio-llapi-index.rst:286 +msgid ":ref:`Using loop.subprocess_exec() `." +msgstr "" +":ref:`使用 loop.add_signal_handler() `。" + +#: ../../library/asyncio-llapi-index.rst:290 +msgid "Transports" +msgstr "傳輸" + +#: ../../library/asyncio-llapi-index.rst:292 +msgid "All transports implement the following methods:" +msgstr "所有傳輸方式都有實作以下方法：" + +#: ../../library/asyncio-llapi-index.rst:298 +msgid ":meth:`transport.close() `" +msgstr ":meth:`transport.close() `" + +#: ../../library/asyncio-llapi-index.rst:299 +msgid "Close the transport." +msgstr "關閉傳輸。" + +#: ../../library/asyncio-llapi-index.rst:301 +msgid ":meth:`transport.is_closing() `" +msgstr ":meth:`transport.is_closing() `" + +#: ../../library/asyncio-llapi-index.rst:302 +msgid "Return ``True`` if the transport is closing or is closed." +msgstr "如果傳輸正在關閉或已經關閉則回傳 ``True``。" + +#: ../../library/asyncio-llapi-index.rst:304 +msgid ":meth:`transport.get_extra_info() `" +msgstr ":meth:`transport.get_extra_info() `" + +#: ../../library/asyncio-llapi-index.rst:305 +msgid "Request for information about the transport." +msgstr "請求傳輸的相關資訊。" + +#: ../../library/asyncio-llapi-index.rst:307 +msgid ":meth:`transport.set_protocol() `" +msgstr ":meth:`transport.set_protocol() `" + +#: ../../library/asyncio-llapi-index.rst:308 +msgid "Set a new protocol." +msgstr "設定一個新協定。" + +#: ../../library/asyncio-llapi-index.rst:310 +msgid ":meth:`transport.get_protocol() `" +msgstr ":meth:`transport.get_protocol() `" + +#: ../../library/asyncio-llapi-index.rst:311 +msgid "Return the current protocol." +msgstr "回傳目前協定。" + +#: ../../library/asyncio-llapi-index.rst:314 +msgid "" +"Transports that can receive data (TCP and Unix connections, pipes, etc). " +"Returned from methods " +"like :meth:`loop.create_connection`, :meth:`loop.create_unix_connection`, :meth:`loop.connect_read_pipe`, " +"etc:" +msgstr "" +"可以接收資料（TCP 和 Unix 連線、pipe 等）的傳輸。它" +"由 :meth:`loop.create_connection`、:meth:`loop.create_unix_connection`、:meth:`loop.connect_read_pipe` " +"等方法回傳：" + +#: ../../library/asyncio-llapi-index.rst:319 +msgid "Read Transports" +msgstr "讀取傳輸" + +#: ../../library/asyncio-llapi-index.rst:324 +msgid ":meth:`transport.is_reading() `" +msgstr ":meth:`transport.is_reading() `" + +#: ../../library/asyncio-llapi-index.rst:325 +msgid "Return ``True`` if the transport is receiving." +msgstr "如果傳輸正在接收則回傳 ``True``。" + +#: ../../library/asyncio-llapi-index.rst:327 +msgid ":meth:`transport.pause_reading() `" +msgstr ":meth:`transport.pause_reading() `" + +#: ../../library/asyncio-llapi-index.rst:328 +msgid "Pause receiving." +msgstr "暫停接收。" + +#: ../../library/asyncio-llapi-index.rst:330 +msgid ":meth:`transport.resume_reading() `" +msgstr ":meth:`transport.resume_reading() `" + +#: ../../library/asyncio-llapi-index.rst:331 +msgid "Resume receiving." +msgstr "繼續接收。" + +#: ../../library/asyncio-llapi-index.rst:334 +msgid "" +"Transports that can Send data (TCP and Unix connections, pipes, etc). " +"Returned from methods " +"like :meth:`loop.create_connection`, :meth:`loop.create_unix_connection`, :meth:`loop.connect_write_pipe`, " +"etc:" +msgstr "" +"可以傳送資料（TCP 和 Unix 連線、pipe 等）的傳輸。它" +"由 :meth:`loop.create_connection`、:meth:`loop.create_unix_connection`、:meth:`loop.connect_write_pipe` " +"等方法回傳：" + +#: ../../library/asyncio-llapi-index.rst:339 +msgid "Write Transports" +msgstr "寫入傳輸" + +#: ../../library/asyncio-llapi-index.rst:344 +msgid ":meth:`transport.write() `" +msgstr ":meth:`transport.write() `" + +#: ../../library/asyncio-llapi-index.rst:345 +msgid "Write data to the transport." +msgstr "將資料寫入傳輸。" + +#: ../../library/asyncio-llapi-index.rst:347 +msgid ":meth:`transport.writelines() `" +msgstr ":meth:`transport.writelines() `" + +#: ../../library/asyncio-llapi-index.rst:348 +msgid "Write buffers to the transport." +msgstr "將緩衝區資料寫入傳輸。" + +#: ../../library/asyncio-llapi-index.rst:350 +msgid ":meth:`transport.can_write_eof() `" +msgstr ":meth:`transport.can_write_eof() `" + +#: ../../library/asyncio-llapi-index.rst:351 +msgid "Return :const:`True` if the transport supports sending EOF." +msgstr "如果傳輸支援傳送 EOF 則回傳 :const:`True`。" + +#: ../../library/asyncio-llapi-index.rst:353 +msgid ":meth:`transport.write_eof() `" +msgstr ":meth:`transport.write_eof() `" + +#: ../../library/asyncio-llapi-index.rst:354 +msgid "Close and send EOF after flushing buffered data." +msgstr "在清除 (flush) 已緩衝的資料後關閉傳輸並傳送 EOF。" + +#: ../../library/asyncio-llapi-index.rst:356 +msgid ":meth:`transport.abort() `" +msgstr ":meth:`transport.abort() `" + +#: ../../library/asyncio-llapi-index.rst:357 +#: ../../library/asyncio-llapi-index.rst:383 +msgid "Close the transport immediately." +msgstr "立即關閉傳輸。" + +#: ../../library/asyncio-llapi-index.rst:359 +msgid "" +":meth:`transport.get_write_buffer_size() " +"`" +msgstr "" +":meth:`transport.get_write_buffer_size() " +"`" + +#: ../../library/asyncio-llapi-index.rst:361 +msgid "Return the current size of the output buffer." +msgstr "回傳目前輸出緩衝區的大小。" + +#: ../../library/asyncio-llapi-index.rst:363 +msgid "" +":meth:`transport.get_write_buffer_limits() " +"`" +msgstr "" +":meth:`transport.get_write_buffer_limits() " +"`" + +#: ../../library/asyncio-llapi-index.rst:365 +msgid "Return high and low water marks for write flow control." +msgstr "" +"回傳用於寫入流量控制 (write flow control) 的高低標記位 (high and low water " +"marks)。" + +#: ../../library/asyncio-llapi-index.rst:367 +msgid "" +":meth:`transport.set_write_buffer_limits() " +"`" +msgstr "" +":meth:`transport.set_write_buffer_limits() " +"`" + +#: ../../library/asyncio-llapi-index.rst:369 +msgid "Set new high and low water marks for write flow control." +msgstr "為寫入流量控制設定高低標記位。" + +#: ../../library/asyncio-llapi-index.rst:372 +msgid "Transports returned by :meth:`loop.create_datagram_endpoint`:" +msgstr "由 :meth:`loop.create_datagram_endpoint` 回傳的傳輸：" + +#: ../../library/asyncio-llapi-index.rst:374 +msgid "Datagram Transports" +msgstr "資料單元傳輸" + +#: ../../library/asyncio-llapi-index.rst:379 +msgid ":meth:`transport.sendto() `" +msgstr ":meth:`transport.sendto() `" + +#: ../../library/asyncio-llapi-index.rst:380 +msgid "Send data to the remote peer." +msgstr "傳送資料到連線遠端。" + +#: ../../library/asyncio-llapi-index.rst:382 +msgid ":meth:`transport.abort() `" +msgstr ":meth:`transport.abort() `" + +#: ../../library/asyncio-llapi-index.rst:386 +msgid "" +"Low-level transport abstraction over subprocesses. Returned " +"by :meth:`loop.subprocess_exec` and :meth:`loop.subprocess_shell`:" +msgstr "" +"基於子行程的低階傳輸抽象，它會由 :meth:`loop.subprocess_exec` " +"和 :meth:`loop.subprocess_shell` 所回傳：" + +#: ../../library/asyncio-llapi-index.rst:390 +msgid "Subprocess Transports" +msgstr "子行程傳輸" + +#: ../../library/asyncio-llapi-index.rst:395 +msgid ":meth:`transport.get_pid() `" +msgstr ":meth:`transport.get_pid() `" + +#: ../../library/asyncio-llapi-index.rst:396 +msgid "Return the subprocess process id." +msgstr "回傳子行程的行程 id。" + +#: ../../library/asyncio-llapi-index.rst:398 +msgid "" +":meth:`transport.get_pipe_transport() " +"`" +msgstr "" +":meth:`transport.get_pipe_transport() " +"`" + +#: ../../library/asyncio-llapi-index.rst:400 +msgid "" +"Return the transport for the requested communication pipe (*stdin*, " +"*stdout*, or *stderr*)." +msgstr "回傳被請求用於通訊 pipe （*stdin*、*stdout* 或 *stderr*）的傳輸。" + +#: ../../library/asyncio-llapi-index.rst:403 +msgid ":meth:`transport.get_returncode() `" +msgstr "" +":meth:`transport.get_returncode() `" + +#: ../../library/asyncio-llapi-index.rst:404 +msgid "Return the subprocess return code." +msgstr "回傳子行程的回傳代號 (return code)。" + +#: ../../library/asyncio-llapi-index.rst:406 +msgid ":meth:`transport.kill() `" +msgstr ":meth:`transport.kill() `" + +#: ../../library/asyncio-llapi-index.rst:407 +msgid "Kill the subprocess." +msgstr "殺死子行程。" + +#: ../../library/asyncio-llapi-index.rst:409 +msgid ":meth:`transport.send_signal() `" +msgstr ":meth:`transport.send_signal() `" + +#: ../../library/asyncio-llapi-index.rst:410 +msgid "Send a signal to the subprocess." +msgstr "傳送一個訊號到子行程。" + +#: ../../library/asyncio-llapi-index.rst:412 +msgid ":meth:`transport.terminate() `" +msgstr ":meth:`transport.terminate() `" + +#: ../../library/asyncio-llapi-index.rst:413 +msgid "Stop the subprocess." +msgstr "停止子行程。" + +#: ../../library/asyncio-llapi-index.rst:415 +msgid ":meth:`transport.close() `" +msgstr ":meth:`transport.close() `" + +#: ../../library/asyncio-llapi-index.rst:416 +msgid "Kill the subprocess and close all pipes." +msgstr "殺死子行程並關閉所有 pipes。" + +#: ../../library/asyncio-llapi-index.rst:420 +msgid "Protocols" +msgstr "協定" + +#: ../../library/asyncio-llapi-index.rst:422 +msgid "Protocol classes can implement the following **callback methods**:" +msgstr "協定類別可以實作以下\\ **回呼方法**：" + +#: ../../library/asyncio-llapi-index.rst:428 +msgid "``callback`` :meth:`connection_made() `" +msgstr "``callback`` :meth:`connection_made() `" + +#: ../../library/asyncio-llapi-index.rst:429 +msgid "Called when a connection is made." +msgstr "在連線建立時被呼叫。" + +#: ../../library/asyncio-llapi-index.rst:431 +msgid "``callback`` :meth:`connection_lost() `" +msgstr "``callback`` :meth:`connection_lost() `" + +#: ../../library/asyncio-llapi-index.rst:432 +msgid "Called when the connection is lost or closed." +msgstr "在失去連線或連線關閉時被呼叫。" + +#: ../../library/asyncio-llapi-index.rst:434 +msgid "``callback`` :meth:`pause_writing() `" +msgstr "``callback`` :meth:`pause_writing() `" + +#: ../../library/asyncio-llapi-index.rst:435 +msgid "Called when the transport's buffer goes over the high water mark." +msgstr "在傳輸緩衝區超過高標記位時被呼叫。" + +#: ../../library/asyncio-llapi-index.rst:437 +msgid "``callback`` :meth:`resume_writing() `" +msgstr "``callback`` :meth:`resume_writing() `" + +#: ../../library/asyncio-llapi-index.rst:438 +msgid "Called when the transport's buffer drains below the low water mark." +msgstr "在傳輸緩衝區低於低標記位時被呼叫。" + +#: ../../library/asyncio-llapi-index.rst:441 +msgid "Streaming Protocols (TCP, Unix Sockets, Pipes)" +msgstr "串流協定 (TCP, Unix socket, Pipes)" + +#: ../../library/asyncio-llapi-index.rst:446 +msgid "``callback`` :meth:`data_received() `" +msgstr "``callback`` :meth:`data_received() `" + +#: ../../library/asyncio-llapi-index.rst:447 +msgid "Called when some data is received." +msgstr "在接收到資料時被呼叫。" + +#: ../../library/asyncio-llapi-index.rst:449 +msgid "``callback`` :meth:`eof_received() `" +msgstr "``callback`` :meth:`eof_received() `" + +#: ../../library/asyncio-llapi-index.rst:450 +#: ../../library/asyncio-llapi-index.rst:465 +msgid "Called when an EOF is received." +msgstr "在接收到 EOF 時被呼叫。" + +#: ../../library/asyncio-llapi-index.rst:453 +msgid "Buffered Streaming Protocols" +msgstr "緩衝串流協定" + +#: ../../library/asyncio-llapi-index.rst:458 +msgid "``callback`` :meth:`get_buffer() `" +msgstr "``callback`` :meth:`get_buffer() `" + +#: ../../library/asyncio-llapi-index.rst:459 +msgid "Called to allocate a new receive buffer." +msgstr "呼叫後會分配新的接收緩衝區。" + +#: ../../library/asyncio-llapi-index.rst:461 +msgid "``callback`` :meth:`buffer_updated() `" +msgstr "" +"``callback`` :meth:`buffer_updated() `" + +#: ../../library/asyncio-llapi-index.rst:462 +msgid "Called when the buffer was updated with the received data." +msgstr "在以接收到的資料更新緩衝區時被呼叫。" + +#: ../../library/asyncio-llapi-index.rst:464 +msgid "``callback`` :meth:`eof_received() `" +msgstr "``callback`` :meth:`eof_received() `" + +#: ../../library/asyncio-llapi-index.rst:468 +msgid "Datagram Protocols" +msgstr "資料單元協定" + +#: ../../library/asyncio-llapi-index.rst:473 +msgid "" +"``callback`` :meth:`datagram_received() `" +msgstr "" +"``callback`` :meth:`datagram_received() `" + +#: ../../library/asyncio-llapi-index.rst:475 +msgid "Called when a datagram is received." +msgstr "在接收到資料單元時被呼叫。" + +#: ../../library/asyncio-llapi-index.rst:477 +msgid "``callback`` :meth:`error_received() `" +msgstr "" +"``callback`` :meth:`error_received() `" + +#: ../../library/asyncio-llapi-index.rst:478 +msgid "" +"Called when a previous send or receive operation raises an :class:`OSError`." +msgstr "在前一個傳送或接收操作引發 :class:`OSError` 時被呼叫。" + +#: ../../library/asyncio-llapi-index.rst:482 +msgid "Subprocess Protocols" +msgstr "子行程協定" + +#: ../../library/asyncio-llapi-index.rst:487 +msgid "``callback`` :meth:`~SubprocessProtocol.pipe_data_received`" +msgstr "``callback`` :meth:`~SubprocessProtocol.pipe_data_received`" + +#: ../../library/asyncio-llapi-index.rst:488 +msgid "" +"Called when the child process writes data into its *stdout* or *stderr* pipe." +msgstr "在子行程向 *stdout* 或 *stderr* pipe 寫入資料時被呼叫。" + +#: ../../library/asyncio-llapi-index.rst:491 +msgid "``callback`` :meth:`~SubprocessProtocol.pipe_connection_lost`" +msgstr "``callback`` :meth:`~SubprocessProtocol.pipe_connection_lost`" + +#: ../../library/asyncio-llapi-index.rst:492 +msgid "" +"Called when one of the pipes communicating with the child process is closed." +msgstr "在與子行程通訊的其中一個 pipes 關閉時被呼叫。" + +#: ../../library/asyncio-llapi-index.rst:495 +msgid "" +"``callback`` :meth:`process_exited() `" +msgstr "" +"``callback`` :meth:`process_exited() `" + +#: ../../library/asyncio-llapi-index.rst:497 +msgid "" +"Called when the child process has exited. It can be called " +"before :meth:`~SubprocessProtocol.pipe_data_received` " +"and :meth:`~SubprocessProtocol.pipe_connection_lost` methods." +msgstr "" +"在子行程退出時呼叫。它可以在 :meth:`~SubprocessProtocol.pipe_data_received` " +"和 :meth:`~SubprocessProtocol.pipe_connection_lost` 方法之前呼叫。" + +#: ../../library/asyncio-llapi-index.rst:503 +msgid "Event Loop Policies" +msgstr "事件迴圈 Policies" + +#: ../../library/asyncio-llapi-index.rst:505 +msgid "" +"Policies is a low-level mechanism to alter the behavior of functions " +"like :func:`asyncio.get_event_loop`. See also the main :ref:`policies " +"section ` for more details." +msgstr "" +"Policy 是改變 :func:`asyncio.get_event_loop` 這類函式行為的一個低階機制。更多" +"細節請見 :ref:`Policy 相關段落 `。" + +#: ../../library/asyncio-llapi-index.rst:511 +msgid "Accessing Policies" +msgstr "存取 Policy" + +#: ../../library/asyncio-llapi-index.rst:516 +msgid ":meth:`asyncio.get_event_loop_policy`" +msgstr ":meth:`asyncio.get_event_loop_policy`" + +#: ../../library/asyncio-llapi-index.rst:517 +msgid "Return the current process-wide policy." +msgstr "回傳目前整個行程中的 Policy。" + +#: ../../library/asyncio-llapi-index.rst:519 +msgid ":meth:`asyncio.set_event_loop_policy`" +msgstr ":meth:`asyncio.set_event_loop_policy`" + +#: ../../library/asyncio-llapi-index.rst:520 +msgid "Set a new process-wide policy." +msgstr "設定整個行程中的一個新 Policy。" + +#: ../../library/asyncio-llapi-index.rst:522 +msgid ":class:`AbstractEventLoopPolicy`" +msgstr ":class:`AbstractEventLoopPolicy`" + +#: ../../library/asyncio-llapi-index.rst:523 +msgid "Base class for policy objects." +msgstr "Policy 物件的基礎類別。" diff --git a/library/asyncio-platforms.po b/library/asyncio-platforms.po index 781b0afe80..f3ec546f5e 100644 --- a/library/asyncio-platforms.po +++ b/library/asyncio-platforms.po @@ -1,196 +1,196 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# FIRST AUTHOR , YEAR. -# -# Translators: -# Matt Wang , 2021 -# -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: 2022-01-17 11:37+0800\n" -"Last-Translator: Matt Wang \n" -"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" -"tw)\n" -"Language: zh_TW\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=UTF-8\n" -"Content-Transfer-Encoding: 8bit\n" -"X-Generator: Poedit 3.0.1\n" - -#: ../../library/asyncio-platforms.rst:9 -msgid "Platform Support" -msgstr "平臺支援" - -#: ../../library/asyncio-platforms.rst:11 -msgid "" -"The :mod:`asyncio` module is designed to be portable, but some platforms " -"have subtle differences and limitations due to the platforms' underlying " -"architecture and capabilities." -msgstr "" -":mod:`asyncio` module（模組）被設計為可攜的 (portable)，但由於平臺的底層架構" -"和功能不同，在一些平臺上存在細微的差異和限制。" - -#: ../../library/asyncio-platforms.rst:17 -msgid "All Platforms" -msgstr "所有平台" - -#: ../../library/asyncio-platforms.rst:19 -msgid "" -":meth:`loop.add_reader` and :meth:`loop.add_writer` cannot be used to " -"monitor file I/O." -msgstr "" -":meth:`loop.add_reader` 和 :meth:`loop.add_writer` 不能用來監視檔案 I/O。" - -#: ../../library/asyncio-platforms.rst:24 -msgid "Windows" -msgstr "Windows" - -#: ../../library/asyncio-platforms.rst:26 -msgid "" -"**Source code:** :source:`Lib/asyncio/proactor_events.py`, :source:`Lib/" -"asyncio/windows_events.py`, :source:`Lib/asyncio/windows_utils.py`" -msgstr "" -"**原始碼：**\\ :source:`Lib/asyncio/proactor_events.py、source:`Lib/asyncio/" -"windows_events.py、source:`Lib/asyncio/windows_utils.py`" - -#: ../../library/asyncio-platforms.rst:34 -msgid "On Windows, :class:`ProactorEventLoop` is now the default event loop." -msgstr "在 Windows 上，現在 :class:`ProactorEventLoop` 是預設的事件迴圈。" - -#: ../../library/asyncio-platforms.rst:36 -msgid "All event loops on Windows do not support the following methods:" -msgstr "Windows 上的所有事件迴圈都不支援以下 method（方法）：" - -#: ../../library/asyncio-platforms.rst:38 -msgid "" -":meth:`loop.create_unix_connection` and :meth:`loop.create_unix_server` are " -"not supported. The :const:`socket.AF_UNIX` socket family is specific to Unix." -msgstr "" -"不支援 :meth:`loop.create_unix_connection` " -"和 :meth:`loop.create_unix_server`。:const:`socket.AF_UNIX` socket 系列常數僅" -"限於 Unix 上使用。" - -#: ../../library/asyncio-platforms.rst:42 -msgid "" -":meth:`loop.add_signal_handler` and :meth:`loop.remove_signal_handler` are " -"not supported." -msgstr "" -"不支援 :meth:`loop.add_signal_handler` " -"和 :meth:`loop.remove_signal_handler`。" - -#: ../../library/asyncio-platforms.rst:45 -msgid ":class:`SelectorEventLoop` has the following limitations:" -msgstr ":class:`SelectorEventLoop` 有以下限制：" - -#: ../../library/asyncio-platforms.rst:47 -msgid "" -":class:`~selectors.SelectSelector` is used to wait on socket events: it " -"supports sockets and is limited to 512 sockets." -msgstr "" -":class:`~selectors.SelectSelector` 只被用於等待 socket 事件：它支援 socket 且" -"最多支援 512 個 socket。" - -#: ../../library/asyncio-platforms.rst:50 -msgid "" -":meth:`loop.add_reader` and :meth:`loop.add_writer` only accept socket " -"handles (e.g. pipe file descriptors are not supported)." -msgstr "" -":meth:`loop.add_reader` 和 :meth:`loop.add_writer` 只接受 socket 處理函式（例" -"如不支援 pipe 檔案描述器 (pipe file descriptor)）。" - -#: ../../library/asyncio-platforms.rst:53 -msgid "" -"Pipes are not supported, so the :meth:`loop.connect_read_pipe` " -"and :meth:`loop.connect_write_pipe` methods are not implemented." -msgstr "" -"因為不支援 pipe，所以 :meth:`loop.connect_read_pipe` " -"和 :meth:`loop.connect_write_pipe` method 沒有被實作出來。" - -#: ../../library/asyncio-platforms.rst:56 -msgid "" -":ref:`Subprocesses ` are not supported, " -"i.e. :meth:`loop.subprocess_exec` and :meth:`loop.subprocess_shell` methods " -"are not implemented." -msgstr "" -"不支援\\ :ref:`子行程 (subprocess) `，也就是" -"說 :meth:`loop.subprocess_exec` 和 :meth:`loop.subprocess_shell` method 沒有" -"被實作出來。" - -#: ../../library/asyncio-platforms.rst:60 -msgid ":class:`ProactorEventLoop` has the following limitations:" -msgstr ":class:`ProactorEventLoop` 有以下限制：" - -#: ../../library/asyncio-platforms.rst:62 -msgid "" -"The :meth:`loop.add_reader` and :meth:`loop.add_writer` methods are not " -"supported." -msgstr "不支援 :meth:`loop.add_reader` 和 :meth:`loop.add_writer` method。" - -#: ../../library/asyncio-platforms.rst:65 -msgid "" -"The resolution of the monotonic clock on Windows is usually around 15.6 " -"milliseconds. The best resolution is 0.5 milliseconds. The resolution " -"depends on the hardware (availability of `HPET `_) and on the Windows configuration." -msgstr "" -"Windows 上單調時鐘 (monotonic clock) 的解析度大約為 15.6 毫秒。最佳的解析度" -"是 0.5 毫秒。解析度和硬體（\\ `HPET `_ 是否可用）與 Windows 的設定有關。" - -#: ../../library/asyncio-platforms.rst:75 -msgid "Subprocess Support on Windows" -msgstr "Windows 的子行程支援" - -#: ../../library/asyncio-platforms.rst:77 -msgid "" -"On Windows, the default event loop :class:`ProactorEventLoop` supports " -"subprocesses, whereas :class:`SelectorEventLoop` does not." -msgstr "" -"在 Windows 上，預設的事件迴圈 :class:`ProactorEventLoop` 支援子行程，" -"而 :class:`SelectorEventLoop` 則不支援。" - -#: ../../library/asyncio-platforms.rst:82 -msgid "macOS" -msgstr "macOS" - -#: ../../library/asyncio-platforms.rst:84 -msgid "Modern macOS versions are fully supported." -msgstr "完整支援現在普遍流行的 macOS 版本。" - -#: ../../library/asyncio-platforms.rst:87 -msgid "macOS <= 10.8" -msgstr "macOS <= 10.8" - -#: ../../library/asyncio-platforms.rst:88 -msgid "" -"On macOS 10.6, 10.7 and 10.8, the default event loop " -"uses :class:`selectors.KqueueSelector`, which does not support character " -"devices on these versions. The :class:`SelectorEventLoop` can be manually " -"configured to use :class:`~selectors.SelectSelector` " -"or :class:`~selectors.PollSelector` to support character devices on these " -"older versions of macOS. Example::" -msgstr "" -"在 macOS 10.6、10.7 和 10.8 上，預設的事件迴圈是使" -"用 :class:`selectors.KqueueSelector`，在這些版本上它並不支援字元裝置 " -"(character device)。可以手工設置 :class:`SelectorEventLoop` 來使" -"用 :class:`~selectors.SelectSelector` 或 :class:`~selectors.PollSelector` 以" -"在這些舊版 macOS 上支援字元裝置。例如： ::" - -#: ../../library/asyncio-platforms.rst:95 -msgid "" -"import asyncio\n" -"import selectors\n" -"\n" -"selector = selectors.SelectSelector()\n" -"loop = asyncio.SelectorEventLoop(selector)\n" -"asyncio.set_event_loop(loop)" -msgstr "" -"import asyncio\n" -"import selectors\n" -"\n" -"selector = selectors.SelectSelector()\n" -"loop = asyncio.SelectorEventLoop(selector)\n" -"asyncio.set_event_loop(loop)" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# FIRST AUTHOR , YEAR. +# +# Translators: +# Matt Wang , 2021 +# +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: 2022-01-17 11:37+0800\n" +"Last-Translator: Matt Wang \n" +"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" +"tw)\n" +"Language: zh_TW\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"X-Generator: Poedit 3.0.1\n" + +#: ../../library/asyncio-platforms.rst:9 +msgid "Platform Support" +msgstr "平臺支援" + +#: ../../library/asyncio-platforms.rst:11 +msgid "" +"The :mod:`asyncio` module is designed to be portable, but some platforms " +"have subtle differences and limitations due to the platforms' underlying " +"architecture and capabilities." +msgstr "" +":mod:`asyncio` module（模組）被設計為可攜的 (portable)，但由於平臺的底層架構" +"和功能不同，在一些平臺上存在細微的差異和限制。" + +#: ../../library/asyncio-platforms.rst:17 +msgid "All Platforms" +msgstr "所有平台" + +#: ../../library/asyncio-platforms.rst:19 +msgid "" +":meth:`loop.add_reader` and :meth:`loop.add_writer` cannot be used to " +"monitor file I/O." +msgstr "" +":meth:`loop.add_reader` 和 :meth:`loop.add_writer` 不能用來監視檔案 I/O。" + +#: ../../library/asyncio-platforms.rst:24 +msgid "Windows" +msgstr "Windows" + +#: ../../library/asyncio-platforms.rst:26 +msgid "" +"**Source code:** :source:`Lib/asyncio/proactor_events.py`, :source:`Lib/" +"asyncio/windows_events.py`, :source:`Lib/asyncio/windows_utils.py`" +msgstr "" +"**原始碼：**\\ :source:`Lib/asyncio/proactor_events.py、source:`Lib/asyncio/" +"windows_events.py、source:`Lib/asyncio/windows_utils.py`" + +#: ../../library/asyncio-platforms.rst:34 +msgid "On Windows, :class:`ProactorEventLoop` is now the default event loop." +msgstr "在 Windows 上，現在 :class:`ProactorEventLoop` 是預設的事件迴圈。" + +#: ../../library/asyncio-platforms.rst:36 +msgid "All event loops on Windows do not support the following methods:" +msgstr "Windows 上的所有事件迴圈都不支援以下 method（方法）：" + +#: ../../library/asyncio-platforms.rst:38 +msgid "" +":meth:`loop.create_unix_connection` and :meth:`loop.create_unix_server` are " +"not supported. The :const:`socket.AF_UNIX` socket family is specific to Unix." +msgstr "" +"不支援 :meth:`loop.create_unix_connection` " +"和 :meth:`loop.create_unix_server`。:const:`socket.AF_UNIX` socket 系列常數僅" +"限於 Unix 上使用。" + +#: ../../library/asyncio-platforms.rst:42 +msgid "" +":meth:`loop.add_signal_handler` and :meth:`loop.remove_signal_handler` are " +"not supported." +msgstr "" +"不支援 :meth:`loop.add_signal_handler` " +"和 :meth:`loop.remove_signal_handler`。" + +#: ../../library/asyncio-platforms.rst:45 +msgid ":class:`SelectorEventLoop` has the following limitations:" +msgstr ":class:`SelectorEventLoop` 有以下限制：" + +#: ../../library/asyncio-platforms.rst:47 +msgid "" +":class:`~selectors.SelectSelector` is used to wait on socket events: it " +"supports sockets and is limited to 512 sockets." +msgstr "" +":class:`~selectors.SelectSelector` 只被用於等待 socket 事件：它支援 socket 且" +"最多支援 512 個 socket。" + +#: ../../library/asyncio-platforms.rst:50 +msgid "" +":meth:`loop.add_reader` and :meth:`loop.add_writer` only accept socket " +"handles (e.g. pipe file descriptors are not supported)." +msgstr "" +":meth:`loop.add_reader` 和 :meth:`loop.add_writer` 只接受 socket 處理函式（例" +"如不支援 pipe 檔案描述器 (pipe file descriptor)）。" + +#: ../../library/asyncio-platforms.rst:53 +msgid "" +"Pipes are not supported, so the :meth:`loop.connect_read_pipe` " +"and :meth:`loop.connect_write_pipe` methods are not implemented." +msgstr "" +"因為不支援 pipe，所以 :meth:`loop.connect_read_pipe` " +"和 :meth:`loop.connect_write_pipe` method 沒有被實作出來。" + +#: ../../library/asyncio-platforms.rst:56 +msgid "" +":ref:`Subprocesses ` are not supported, " +"i.e. :meth:`loop.subprocess_exec` and :meth:`loop.subprocess_shell` methods " +"are not implemented." +msgstr "" +"不支援\\ :ref:`子行程 (subprocess) `，也就是" +"說 :meth:`loop.subprocess_exec` 和 :meth:`loop.subprocess_shell` method 沒有" +"被實作出來。" + +#: ../../library/asyncio-platforms.rst:60 +msgid ":class:`ProactorEventLoop` has the following limitations:" +msgstr ":class:`ProactorEventLoop` 有以下限制：" + +#: ../../library/asyncio-platforms.rst:62 +msgid "" +"The :meth:`loop.add_reader` and :meth:`loop.add_writer` methods are not " +"supported." +msgstr "不支援 :meth:`loop.add_reader` 和 :meth:`loop.add_writer` method。" + +#: ../../library/asyncio-platforms.rst:65 +msgid "" +"The resolution of the monotonic clock on Windows is usually around 15.6 " +"milliseconds. The best resolution is 0.5 milliseconds. The resolution " +"depends on the hardware (availability of `HPET `_) and on the Windows configuration." +msgstr "" +"Windows 上單調時鐘 (monotonic clock) 的解析度大約為 15.6 毫秒。最佳的解析度" +"是 0.5 毫秒。解析度和硬體（\\ `HPET `_ 是否可用）與 Windows 的設定有關。" + +#: ../../library/asyncio-platforms.rst:75 +msgid "Subprocess Support on Windows" +msgstr "Windows 的子行程支援" + +#: ../../library/asyncio-platforms.rst:77 +msgid "" +"On Windows, the default event loop :class:`ProactorEventLoop` supports " +"subprocesses, whereas :class:`SelectorEventLoop` does not." +msgstr "" +"在 Windows 上，預設的事件迴圈 :class:`ProactorEventLoop` 支援子行程，" +"而 :class:`SelectorEventLoop` 則不支援。" + +#: ../../library/asyncio-platforms.rst:82 +msgid "macOS" +msgstr "macOS" + +#: ../../library/asyncio-platforms.rst:84 +msgid "Modern macOS versions are fully supported." +msgstr "完整支援現在普遍流行的 macOS 版本。" + +#: ../../library/asyncio-platforms.rst:87 +msgid "macOS <= 10.8" +msgstr "macOS <= 10.8" + +#: ../../library/asyncio-platforms.rst:88 +msgid "" +"On macOS 10.6, 10.7 and 10.8, the default event loop " +"uses :class:`selectors.KqueueSelector`, which does not support character " +"devices on these versions. The :class:`SelectorEventLoop` can be manually " +"configured to use :class:`~selectors.SelectSelector` " +"or :class:`~selectors.PollSelector` to support character devices on these " +"older versions of macOS. Example::" +msgstr "" +"在 macOS 10.6、10.7 和 10.8 上，預設的事件迴圈是使" +"用 :class:`selectors.KqueueSelector`，在這些版本上它並不支援字元裝置 " +"(character device)。可以手工設置 :class:`SelectorEventLoop` 來使" +"用 :class:`~selectors.SelectSelector` 或 :class:`~selectors.PollSelector` 以" +"在這些舊版 macOS 上支援字元裝置。例如： ::" + +#: ../../library/asyncio-platforms.rst:95 +msgid "" +"import asyncio\n" +"import selectors\n" +"\n" +"selector = selectors.SelectSelector()\n" +"loop = asyncio.SelectorEventLoop(selector)\n" +"asyncio.set_event_loop(loop)" +msgstr "" +"import asyncio\n" +"import selectors\n" +"\n" +"selector = selectors.SelectSelector()\n" +"loop = asyncio.SelectorEventLoop(selector)\n" +"asyncio.set_event_loop(loop)" diff --git a/library/asyncio-policy.po b/library/asyncio-policy.po index e954684ad8..67042225a3 100644 --- a/library/asyncio-policy.po +++ b/library/asyncio-policy.po @@ -1,233 +1,233 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# FIRST AUTHOR , YEAR. -# -#, fuzzy -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" -"tw)\n" -"Language: zh_TW\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=UTF-8\n" -"Content-Transfer-Encoding: 8bit\n" - -#: ../../library/asyncio-policy.rst:8 -msgid "Policies" -msgstr "" - -#: ../../library/asyncio-policy.rst:12 -msgid "" -"Policies are deprecated and will be removed in Python 3.16. Users are " -"encouraged to use the :func:`asyncio.run` function or " -"the :class:`asyncio.Runner` with *loop_factory* to use the desired loop " -"implementation." -msgstr "" - -#: ../../library/asyncio-policy.rst:18 -msgid "" -"An event loop policy is a global object used to get and set the " -"current :ref:`event loop `, as well as create new event " -"loops. The default policy can be :ref:`replaced ` " -"with :ref:`built-in alternatives ` to use different " -"event loop implementations, or substituted by a :ref:`custom policy ` that can override these behaviors." -msgstr "" - -#: ../../library/asyncio-policy.rst:27 -msgid "" -"The :ref:`policy object ` gets and sets a separate " -"event loop per *context*. This is per-thread by default, though custom " -"policies could define *context* differently." -msgstr "" - -#: ../../library/asyncio-policy.rst:32 -msgid "" -"Custom event loop policies can control the behavior " -"of :func:`get_event_loop`, :func:`set_event_loop`, " -"and :func:`new_event_loop`." -msgstr "" - -#: ../../library/asyncio-policy.rst:35 -msgid "" -"Policy objects should implement the APIs defined in " -"the :class:`AbstractEventLoopPolicy` abstract base class." -msgstr "" - -#: ../../library/asyncio-policy.rst:42 -msgid "Getting and Setting the Policy" -msgstr "" - -#: ../../library/asyncio-policy.rst:44 -msgid "" -"The following functions can be used to get and set the policy for the " -"current process:" -msgstr "" - -#: ../../library/asyncio-policy.rst:49 -msgid "Return the current process-wide policy." -msgstr "" - -#: ../../library/asyncio-policy.rst:51 -msgid "" -"The :func:`get_event_loop_policy` function is deprecated and will be removed " -"in Python 3.16." -msgstr "" - -#: ../../library/asyncio-policy.rst:57 -msgid "Set the current process-wide policy to *policy*." -msgstr "" - -#: ../../library/asyncio-policy.rst:59 -msgid "If *policy* is set to ``None``, the default policy is restored." -msgstr "" - -#: ../../library/asyncio-policy.rst:61 -msgid "" -"The :func:`set_event_loop_policy` function is deprecated and will be removed " -"in Python 3.16." -msgstr "" - -#: ../../library/asyncio-policy.rst:69 -msgid "Policy Objects" -msgstr "" - -#: ../../library/asyncio-policy.rst:71 -msgid "The abstract event loop policy base class is defined as follows:" -msgstr "" - -#: ../../library/asyncio-policy.rst:75 -msgid "An abstract base class for asyncio policies." -msgstr "" - -#: ../../library/asyncio-policy.rst:79 -msgid "Get the event loop for the current context." -msgstr "" - -#: ../../library/asyncio-policy.rst:81 -msgid "" -"Return an event loop object implementing the :class:`AbstractEventLoop` " -"interface." -msgstr "" - -#: ../../library/asyncio-policy.rst:84 ../../library/asyncio-policy.rst:96 -msgid "This method should never return ``None``." -msgstr "" - -#: ../../library/asyncio-policy.rst:90 -msgid "Set the event loop for the current context to *loop*." -msgstr "" - -#: ../../library/asyncio-policy.rst:94 -msgid "Create and return a new event loop object." -msgstr "" - -#: ../../library/asyncio-policy.rst:98 -msgid "" -"The :class:`AbstractEventLoopPolicy` class is deprecated and will be removed " -"in Python 3.16." -msgstr "" - -#: ../../library/asyncio-policy.rst:105 -msgid "asyncio ships with the following built-in policies:" -msgstr "" - -#: ../../library/asyncio-policy.rst:110 -msgid "" -"The default asyncio policy. Uses :class:`SelectorEventLoop` on Unix " -"and :class:`ProactorEventLoop` on Windows." -msgstr "" - -#: ../../library/asyncio-policy.rst:113 -msgid "" -"There is no need to install the default policy manually. asyncio is " -"configured to use the default policy automatically." -msgstr "" - -#: ../../library/asyncio-policy.rst:118 -msgid "On Windows, :class:`ProactorEventLoop` is now used by default." -msgstr "" - -#: ../../library/asyncio-policy.rst:120 -msgid "" -"The :meth:`get_event_loop` method of the default asyncio policy now raises " -"a :exc:`RuntimeError` if there is no set event loop." -msgstr "" - -#: ../../library/asyncio-policy.rst:124 -msgid "" -"The :class:`DefaultEventLoopPolicy` class is deprecated and will be removed " -"in Python 3.16." -msgstr "" - -#: ../../library/asyncio-policy.rst:131 -msgid "" -"An alternative event loop policy that uses the :class:`SelectorEventLoop` " -"event loop implementation." -msgstr "" - -#: ../../library/asyncio-policy.rst:134 ../../library/asyncio-policy.rst:146 -msgid "Availability" -msgstr "可用性" - -#: ../../library/asyncio-policy.rst:136 -msgid "" -"The :class:`WindowsSelectorEventLoopPolicy` class is deprecated and will be " -"removed in Python 3.16." -msgstr "" - -#: ../../library/asyncio-policy.rst:143 -msgid "" -"An alternative event loop policy that uses the :class:`ProactorEventLoop` " -"event loop implementation." -msgstr "" - -#: ../../library/asyncio-policy.rst:148 -msgid "" -"The :class:`WindowsProactorEventLoopPolicy` class is deprecated and will be " -"removed in Python 3.16." -msgstr "" - -#: ../../library/asyncio-policy.rst:156 -msgid "Custom Policies" -msgstr "" - -#: ../../library/asyncio-policy.rst:158 -msgid "" -"To implement a new event loop policy, it is recommended to " -"subclass :class:`DefaultEventLoopPolicy` and override the methods for which " -"custom behavior is wanted, e.g.::" -msgstr "" - -#: ../../library/asyncio-policy.rst:162 -msgid "" -"class MyEventLoopPolicy(asyncio.DefaultEventLoopPolicy):\n" -"\n" -" def get_event_loop(self):\n" -" \"\"\"Get the event loop.\n" -"\n" -" This may be None or an instance of EventLoop.\n" -" \"\"\"\n" -" loop = super().get_event_loop()\n" -" # Do something with loop ...\n" -" return loop\n" -"\n" -"asyncio.set_event_loop_policy(MyEventLoopPolicy())" -msgstr "" -"class MyEventLoopPolicy(asyncio.DefaultEventLoopPolicy):\n" -"\n" -" def get_event_loop(self):\n" -" \"\"\"Get the event loop.\n" -"\n" -" This may be None or an instance of EventLoop.\n" -" \"\"\"\n" -" loop = super().get_event_loop()\n" -" # Do something with loop ...\n" -" return loop\n" -"\n" -"asyncio.set_event_loop_policy(MyEventLoopPolicy())" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" +"tw)\n" +"Language: zh_TW\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../library/asyncio-policy.rst:8 +msgid "Policies" +msgstr "" + +#: ../../library/asyncio-policy.rst:12 +msgid "" +"Policies are deprecated and will be removed in Python 3.16. Users are " +"encouraged to use the :func:`asyncio.run` function or " +"the :class:`asyncio.Runner` with *loop_factory* to use the desired loop " +"implementation." +msgstr "" + +#: ../../library/asyncio-policy.rst:18 +msgid "" +"An event loop policy is a global object used to get and set the " +"current :ref:`event loop `, as well as create new event " +"loops. The default policy can be :ref:`replaced ` " +"with :ref:`built-in alternatives ` to use different " +"event loop implementations, or substituted by a :ref:`custom policy ` that can override these behaviors." +msgstr "" + +#: ../../library/asyncio-policy.rst:27 +msgid "" +"The :ref:`policy object ` gets and sets a separate " +"event loop per *context*. This is per-thread by default, though custom " +"policies could define *context* differently." +msgstr "" + +#: ../../library/asyncio-policy.rst:32 +msgid "" +"Custom event loop policies can control the behavior " +"of :func:`get_event_loop`, :func:`set_event_loop`, " +"and :func:`new_event_loop`." +msgstr "" + +#: ../../library/asyncio-policy.rst:35 +msgid "" +"Policy objects should implement the APIs defined in " +"the :class:`AbstractEventLoopPolicy` abstract base class." +msgstr "" + +#: ../../library/asyncio-policy.rst:42 +msgid "Getting and Setting the Policy" +msgstr "" + +#: ../../library/asyncio-policy.rst:44 +msgid "" +"The following functions can be used to get and set the policy for the " +"current process:" +msgstr "" + +#: ../../library/asyncio-policy.rst:49 +msgid "Return the current process-wide policy." +msgstr "" + +#: ../../library/asyncio-policy.rst:51 +msgid "" +"The :func:`get_event_loop_policy` function is deprecated and will be removed " +"in Python 3.16." +msgstr "" + +#: ../../library/asyncio-policy.rst:57 +msgid "Set the current process-wide policy to *policy*." +msgstr "" + +#: ../../library/asyncio-policy.rst:59 +msgid "If *policy* is set to ``None``, the default policy is restored." +msgstr "" + +#: ../../library/asyncio-policy.rst:61 +msgid "" +"The :func:`set_event_loop_policy` function is deprecated and will be removed " +"in Python 3.16." +msgstr "" + +#: ../../library/asyncio-policy.rst:69 +msgid "Policy Objects" +msgstr "" + +#: ../../library/asyncio-policy.rst:71 +msgid "The abstract event loop policy base class is defined as follows:" +msgstr "" + +#: ../../library/asyncio-policy.rst:75 +msgid "An abstract base class for asyncio policies." +msgstr "" + +#: ../../library/asyncio-policy.rst:79 +msgid "Get the event loop for the current context." +msgstr "" + +#: ../../library/asyncio-policy.rst:81 +msgid "" +"Return an event loop object implementing the :class:`AbstractEventLoop` " +"interface." +msgstr "" + +#: ../../library/asyncio-policy.rst:84 ../../library/asyncio-policy.rst:96 +msgid "This method should never return ``None``." +msgstr "" + +#: ../../library/asyncio-policy.rst:90 +msgid "Set the event loop for the current context to *loop*." +msgstr "" + +#: ../../library/asyncio-policy.rst:94 +msgid "Create and return a new event loop object." +msgstr "" + +#: ../../library/asyncio-policy.rst:98 +msgid "" +"The :class:`AbstractEventLoopPolicy` class is deprecated and will be removed " +"in Python 3.16." +msgstr "" + +#: ../../library/asyncio-policy.rst:105 +msgid "asyncio ships with the following built-in policies:" +msgstr "" + +#: ../../library/asyncio-policy.rst:110 +msgid "" +"The default asyncio policy. Uses :class:`SelectorEventLoop` on Unix " +"and :class:`ProactorEventLoop` on Windows." +msgstr "" + +#: ../../library/asyncio-policy.rst:113 +msgid "" +"There is no need to install the default policy manually. asyncio is " +"configured to use the default policy automatically." +msgstr "" + +#: ../../library/asyncio-policy.rst:118 +msgid "On Windows, :class:`ProactorEventLoop` is now used by default." +msgstr "" + +#: ../../library/asyncio-policy.rst:120 +msgid "" +"The :meth:`get_event_loop` method of the default asyncio policy now raises " +"a :exc:`RuntimeError` if there is no set event loop." +msgstr "" + +#: ../../library/asyncio-policy.rst:124 +msgid "" +"The :class:`DefaultEventLoopPolicy` class is deprecated and will be removed " +"in Python 3.16." +msgstr "" + +#: ../../library/asyncio-policy.rst:131 +msgid "" +"An alternative event loop policy that uses the :class:`SelectorEventLoop` " +"event loop implementation." +msgstr "" + +#: ../../library/asyncio-policy.rst:134 ../../library/asyncio-policy.rst:146 +msgid "Availability" +msgstr "可用性" + +#: ../../library/asyncio-policy.rst:136 +msgid "" +"The :class:`WindowsSelectorEventLoopPolicy` class is deprecated and will be " +"removed in Python 3.16." +msgstr "" + +#: ../../library/asyncio-policy.rst:143 +msgid "" +"An alternative event loop policy that uses the :class:`ProactorEventLoop` " +"event loop implementation." +msgstr "" + +#: ../../library/asyncio-policy.rst:148 +msgid "" +"The :class:`WindowsProactorEventLoopPolicy` class is deprecated and will be " +"removed in Python 3.16." +msgstr "" + +#: ../../library/asyncio-policy.rst:156 +msgid "Custom Policies" +msgstr "" + +#: ../../library/asyncio-policy.rst:158 +msgid "" +"To implement a new event loop policy, it is recommended to " +"subclass :class:`DefaultEventLoopPolicy` and override the methods for which " +"custom behavior is wanted, e.g.::" +msgstr "" + +#: ../../library/asyncio-policy.rst:162 +msgid "" +"class MyEventLoopPolicy(asyncio.DefaultEventLoopPolicy):\n" +"\n" +" def get_event_loop(self):\n" +" \"\"\"Get the event loop.\n" +"\n" +" This may be None or an instance of EventLoop.\n" +" \"\"\"\n" +" loop = super().get_event_loop()\n" +" # Do something with loop ...\n" +" return loop\n" +"\n" +"asyncio.set_event_loop_policy(MyEventLoopPolicy())" +msgstr "" +"class MyEventLoopPolicy(asyncio.DefaultEventLoopPolicy):\n" +"\n" +" def get_event_loop(self):\n" +" \"\"\"Get the event loop.\n" +"\n" +" This may be None or an instance of EventLoop.\n" +" \"\"\"\n" +" loop = super().get_event_loop()\n" +" # Do something with loop ...\n" +" return loop\n" +"\n" +"asyncio.set_event_loop_policy(MyEventLoopPolicy())" diff --git a/library/asyncio-protocol.po b/library/asyncio-protocol.po index a8034290eb..e99419ac04 100644 --- a/library/asyncio-protocol.po +++ b/library/asyncio-protocol.po @@ -1,1368 +1,1368 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-08-17 00:18+0000\n" -"PO-Revision-Date: 2018-05-23 14:39+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/asyncio-protocol.rst:9 -msgid "Transports and Protocols" -msgstr "傳輸與協定" - -#: ../../library/asyncio-protocol.rst:12 -msgid "Preface" -msgstr "前言" - -#: ../../library/asyncio-protocol.rst:13 -msgid "" -"Transports and Protocols are used by the **low-level** event loop APIs such " -"as :meth:`loop.create_connection`. They use callback-based programming " -"style and enable high-performance implementations of network or IPC " -"protocols (e.g. HTTP)." -msgstr "" - -#: ../../library/asyncio-protocol.rst:18 -msgid "" -"Essentially, transports and protocols should only be used in libraries and " -"frameworks and never in high-level asyncio applications." -msgstr "" - -#: ../../library/asyncio-protocol.rst:22 -msgid "This documentation page covers both `Transports`_ and `Protocols`_." -msgstr "" - -#: ../../library/asyncio-protocol.rst:25 -msgid "Introduction" -msgstr "" - -#: ../../library/asyncio-protocol.rst:26 -msgid "" -"At the highest level, the transport is concerned with *how* bytes are " -"transmitted, while the protocol determines *which* bytes to transmit (and to " -"some extent when)." -msgstr "" - -#: ../../library/asyncio-protocol.rst:30 -msgid "" -"A different way of saying the same thing: a transport is an abstraction for " -"a socket (or similar I/O endpoint) while a protocol is an abstraction for an " -"application, from the transport's point of view." -msgstr "" - -#: ../../library/asyncio-protocol.rst:35 -msgid "" -"Yet another view is the transport and protocol interfaces together define an " -"abstract interface for using network I/O and interprocess I/O." -msgstr "" - -#: ../../library/asyncio-protocol.rst:39 -msgid "" -"There is always a 1:1 relationship between transport and protocol objects: " -"the protocol calls transport methods to send data, while the transport calls " -"protocol methods to pass it data that has been received." -msgstr "" - -#: ../../library/asyncio-protocol.rst:44 -msgid "" -"Most of connection oriented event loop methods (such as :meth:`loop." -"create_connection`) usually accept a *protocol_factory* argument used to " -"create a *Protocol* object for an accepted connection, represented by a " -"*Transport* object. Such methods usually return a tuple of ``(transport, " -"protocol)``." -msgstr "" - -#: ../../library/asyncio-protocol.rst:51 -msgid "Contents" -msgstr "目錄" - -#: ../../library/asyncio-protocol.rst:52 -msgid "This documentation page contains the following sections:" -msgstr "" - -#: ../../library/asyncio-protocol.rst:54 -msgid "" -"The `Transports`_ section documents asyncio :class:`BaseTransport`, :class:" -"`ReadTransport`, :class:`WriteTransport`, :class:`Transport`, :class:" -"`DatagramTransport`, and :class:`SubprocessTransport` classes." -msgstr "" - -#: ../../library/asyncio-protocol.rst:59 -msgid "" -"The `Protocols`_ section documents asyncio :class:`BaseProtocol`, :class:" -"`Protocol`, :class:`BufferedProtocol`, :class:`DatagramProtocol`, and :class:" -"`SubprocessProtocol` classes." -msgstr "" - -#: ../../library/asyncio-protocol.rst:63 -msgid "" -"The `Examples`_ section showcases how to work with transports, protocols, " -"and low-level event loop APIs." -msgstr "" - -#: ../../library/asyncio-protocol.rst:70 -msgid "Transports" -msgstr "" - -#: ../../library/asyncio-protocol.rst:72 -msgid "**Source code:** :source:`Lib/asyncio/transports.py`" -msgstr "**原始碼：**\\ :source:`Lib/asyncio/transports.py`" - -#: ../../library/asyncio-protocol.rst:76 -msgid "" -"Transports are classes provided by :mod:`asyncio` in order to abstract " -"various kinds of communication channels." -msgstr "" - -#: ../../library/asyncio-protocol.rst:79 -msgid "" -"Transport objects are always instantiated by an :ref:`asyncio event loop " -"`." -msgstr "" - -#: ../../library/asyncio-protocol.rst:82 -msgid "" -"asyncio implements transports for TCP, UDP, SSL, and subprocess pipes. The " -"methods available on a transport depend on the transport's kind." -msgstr "" - -#: ../../library/asyncio-protocol.rst:85 -msgid "" -"The transport classes are :ref:`not thread safe `." -msgstr "" - -#: ../../library/asyncio-protocol.rst:89 -msgid "Transports Hierarchy" -msgstr "" - -#: ../../library/asyncio-protocol.rst:93 -msgid "" -"Base class for all transports. Contains methods that all asyncio transports " -"share." -msgstr "" - -#: ../../library/asyncio-protocol.rst:98 -msgid "A base transport for write-only connections." -msgstr "" - -#: ../../library/asyncio-protocol.rst:100 -msgid "" -"Instances of the *WriteTransport* class are returned from the :meth:`loop." -"connect_write_pipe` event loop method and are also used by subprocess-" -"related methods like :meth:`loop.subprocess_exec`." -msgstr "" - -#: ../../library/asyncio-protocol.rst:107 -msgid "A base transport for read-only connections." -msgstr "" - -#: ../../library/asyncio-protocol.rst:109 -msgid "" -"Instances of the *ReadTransport* class are returned from the :meth:`loop." -"connect_read_pipe` event loop method and are also used by subprocess-related " -"methods like :meth:`loop.subprocess_exec`." -msgstr "" - -#: ../../library/asyncio-protocol.rst:116 -msgid "" -"Interface representing a bidirectional transport, such as a TCP connection." -msgstr "" - -#: ../../library/asyncio-protocol.rst:119 -msgid "" -"The user does not instantiate a transport directly; they call a utility " -"function, passing it a protocol factory and other information necessary to " -"create the transport and protocol." -msgstr "" - -#: ../../library/asyncio-protocol.rst:123 -msgid "" -"Instances of the *Transport* class are returned from or used by event loop " -"methods like :meth:`loop.create_connection`, :meth:`loop." -"create_unix_connection`, :meth:`loop.create_server`, :meth:`loop.sendfile`, " -"etc." -msgstr "" - -#: ../../library/asyncio-protocol.rst:131 -msgid "A transport for datagram (UDP) connections." -msgstr "" - -#: ../../library/asyncio-protocol.rst:133 -msgid "" -"Instances of the *DatagramTransport* class are returned from the :meth:`loop." -"create_datagram_endpoint` event loop method." -msgstr "" - -#: ../../library/asyncio-protocol.rst:139 -msgid "" -"An abstraction to represent a connection between a parent and its child OS " -"process." -msgstr "" - -#: ../../library/asyncio-protocol.rst:142 -msgid "" -"Instances of the *SubprocessTransport* class are returned from event loop " -"methods :meth:`loop.subprocess_shell` and :meth:`loop.subprocess_exec`." -msgstr "" - -#: ../../library/asyncio-protocol.rst:148 -msgid "Base Transport" -msgstr "" - -#: ../../library/asyncio-protocol.rst:152 -msgid "Close the transport." -msgstr "" - -#: ../../library/asyncio-protocol.rst:154 -msgid "" -"If the transport has a buffer for outgoing data, buffered data will be " -"flushed asynchronously. No more data will be received. After all buffered " -"data is flushed, the protocol's :meth:`protocol.connection_lost() " -"` method will be called with :const:`None` as " -"its argument. The transport should not be used once it is closed." -msgstr "" - -#: ../../library/asyncio-protocol.rst:164 -msgid "Return ``True`` if the transport is closing or is closed." -msgstr "" - -#: ../../library/asyncio-protocol.rst:168 -msgid "Return information about the transport or underlying resources it uses." -msgstr "" - -#: ../../library/asyncio-protocol.rst:171 -msgid "" -"*name* is a string representing the piece of transport-specific information " -"to get." -msgstr "" - -#: ../../library/asyncio-protocol.rst:174 -msgid "" -"*default* is the value to return if the information is not available, or if " -"the transport does not support querying it with the given third-party event " -"loop implementation or on the current platform." -msgstr "" - -#: ../../library/asyncio-protocol.rst:179 -msgid "" -"For example, the following code attempts to get the underlying socket object " -"of the transport::" -msgstr "" - -#: ../../library/asyncio-protocol.rst:182 -msgid "" -"sock = transport.get_extra_info('socket')\n" -"if sock is not None:\n" -" print(sock.getsockopt(...))" -msgstr "" -"sock = transport.get_extra_info('socket')\n" -"if sock is not None:\n" -" print(sock.getsockopt(...))" - -#: ../../library/asyncio-protocol.rst:186 -msgid "Categories of information that can be queried on some transports:" -msgstr "" - -#: ../../library/asyncio-protocol.rst:188 -msgid "socket:" -msgstr "" - -#: ../../library/asyncio-protocol.rst:190 -msgid "" -"``'peername'``: the remote address to which the socket is connected, result " -"of :meth:`socket.socket.getpeername` (``None`` on error)" -msgstr "" - -#: ../../library/asyncio-protocol.rst:194 -msgid "``'socket'``: :class:`socket.socket` instance" -msgstr "" - -#: ../../library/asyncio-protocol.rst:196 -msgid "" -"``'sockname'``: the socket's own address, result of :meth:`socket.socket." -"getsockname`" -msgstr "" - -#: ../../library/asyncio-protocol.rst:199 -msgid "SSL socket:" -msgstr "" - -#: ../../library/asyncio-protocol.rst:201 -msgid "" -"``'compression'``: the compression algorithm being used as a string, or " -"``None`` if the connection isn't compressed; result of :meth:`ssl.SSLSocket." -"compression`" -msgstr "" - -#: ../../library/asyncio-protocol.rst:205 -msgid "" -"``'cipher'``: a three-value tuple containing the name of the cipher being " -"used, the version of the SSL protocol that defines its use, and the number " -"of secret bits being used; result of :meth:`ssl.SSLSocket.cipher`" -msgstr "" - -#: ../../library/asyncio-protocol.rst:210 -msgid "" -"``'peercert'``: peer certificate; result of :meth:`ssl.SSLSocket.getpeercert`" -msgstr "" - -#: ../../library/asyncio-protocol.rst:213 -msgid "``'sslcontext'``: :class:`ssl.SSLContext` instance" -msgstr "" - -#: ../../library/asyncio-protocol.rst:215 -msgid "" -"``'ssl_object'``: :class:`ssl.SSLObject` or :class:`ssl.SSLSocket` instance" -msgstr "" - -#: ../../library/asyncio-protocol.rst:218 -msgid "pipe:" -msgstr "" - -#: ../../library/asyncio-protocol.rst:220 -msgid "``'pipe'``: pipe object" -msgstr "" - -#: ../../library/asyncio-protocol.rst:222 -msgid "subprocess:" -msgstr "" - -#: ../../library/asyncio-protocol.rst:224 -msgid "``'subprocess'``: :class:`subprocess.Popen` instance" -msgstr "" - -#: ../../library/asyncio-protocol.rst:228 -msgid "Set a new protocol." -msgstr "" - -#: ../../library/asyncio-protocol.rst:230 -msgid "" -"Switching protocol should only be done when both protocols are documented to " -"support the switch." -msgstr "" - -#: ../../library/asyncio-protocol.rst:235 -msgid "Return the current protocol." -msgstr "" - -#: ../../library/asyncio-protocol.rst:239 -msgid "Read-only Transports" -msgstr "" - -#: ../../library/asyncio-protocol.rst:243 -msgid "Return ``True`` if the transport is receiving new data." -msgstr "" - -#: ../../library/asyncio-protocol.rst:249 -msgid "" -"Pause the receiving end of the transport. No data will be passed to the " -"protocol's :meth:`protocol.data_received() ` method " -"until :meth:`resume_reading` is called." -msgstr "" - -#: ../../library/asyncio-protocol.rst:253 -msgid "" -"The method is idempotent, i.e. it can be called when the transport is " -"already paused or closed." -msgstr "" - -#: ../../library/asyncio-protocol.rst:259 -msgid "" -"Resume the receiving end. The protocol's :meth:`protocol.data_received() " -"` method will be called once again if some data is " -"available for reading." -msgstr "" - -#: ../../library/asyncio-protocol.rst:263 -msgid "" -"The method is idempotent, i.e. it can be called when the transport is " -"already reading." -msgstr "" - -#: ../../library/asyncio-protocol.rst:269 -msgid "Write-only Transports" -msgstr "" - -#: ../../library/asyncio-protocol.rst:273 -msgid "" -"Close the transport immediately, without waiting for pending operations to " -"complete. Buffered data will be lost. No more data will be received. The " -"protocol's :meth:`protocol.connection_lost() ` " -"method will eventually be called with :const:`None` as its argument." -msgstr "" - -#: ../../library/asyncio-protocol.rst:281 -msgid "" -"Return :const:`True` if the transport supports :meth:`~WriteTransport." -"write_eof`, :const:`False` if not." -msgstr "" - -#: ../../library/asyncio-protocol.rst:286 -msgid "Return the current size of the output buffer used by the transport." -msgstr "" - -#: ../../library/asyncio-protocol.rst:290 -msgid "" -"Get the *high* and *low* watermarks for write flow control. Return a tuple " -"``(low, high)`` where *low* and *high* are positive number of bytes." -msgstr "" - -#: ../../library/asyncio-protocol.rst:294 -msgid "Use :meth:`set_write_buffer_limits` to set the limits." -msgstr "" - -#: ../../library/asyncio-protocol.rst:300 -msgid "Set the *high* and *low* watermarks for write flow control." -msgstr "" - -#: ../../library/asyncio-protocol.rst:302 -msgid "" -"These two values (measured in number of bytes) control when the protocol's :" -"meth:`protocol.pause_writing() ` and :meth:" -"`protocol.resume_writing() ` methods are " -"called. If specified, the low watermark must be less than or equal to the " -"high watermark. Neither *high* nor *low* can be negative." -msgstr "" - -#: ../../library/asyncio-protocol.rst:310 -msgid "" -":meth:`~BaseProtocol.pause_writing` is called when the buffer size becomes " -"greater than or equal to the *high* value. If writing has been paused, :meth:" -"`~BaseProtocol.resume_writing` is called when the buffer size becomes less " -"than or equal to the *low* value." -msgstr "" - -#: ../../library/asyncio-protocol.rst:315 -msgid "" -"The defaults are implementation-specific. If only the high watermark is " -"given, the low watermark defaults to an implementation-specific value less " -"than or equal to the high watermark. Setting *high* to zero forces *low* to " -"zero as well, and causes :meth:`~BaseProtocol.pause_writing` to be called " -"whenever the buffer becomes non-empty. Setting *low* to zero causes :meth:" -"`~BaseProtocol.resume_writing` to be called only once the buffer is empty. " -"Use of zero for either limit is generally sub-optimal as it reduces " -"opportunities for doing I/O and computation concurrently." -msgstr "" - -#: ../../library/asyncio-protocol.rst:326 -msgid "Use :meth:`~WriteTransport.get_write_buffer_limits` to get the limits." -msgstr "" - -#: ../../library/asyncio-protocol.rst:331 -msgid "Write some *data* bytes to the transport." -msgstr "" - -#: ../../library/asyncio-protocol.rst:333 -#: ../../library/asyncio-protocol.rst:362 -msgid "" -"This method does not block; it buffers the data and arranges for it to be " -"sent out asynchronously." -msgstr "" - -#: ../../library/asyncio-protocol.rst:338 -msgid "" -"Write a list (or any iterable) of data bytes to the transport. This is " -"functionally equivalent to calling :meth:`write` on each element yielded by " -"the iterable, but may be implemented more efficiently." -msgstr "" - -#: ../../library/asyncio-protocol.rst:345 -msgid "" -"Close the write end of the transport after flushing all buffered data. Data " -"may still be received." -msgstr "" - -#: ../../library/asyncio-protocol.rst:348 -msgid "" -"This method can raise :exc:`NotImplementedError` if the transport (e.g. SSL) " -"doesn't support half-closed connections." -msgstr "" - -#: ../../library/asyncio-protocol.rst:353 -msgid "Datagram Transports" -msgstr "" - -#: ../../library/asyncio-protocol.rst:357 -msgid "" -"Send the *data* bytes to the remote peer given by *addr* (a transport-" -"dependent target address). If *addr* is :const:`None`, the data is sent to " -"the target address given on transport creation." -msgstr "" - -#: ../../library/asyncio-protocol.rst:365 -msgid "" -"This method can be called with an empty bytes object to send a zero-length " -"datagram. The buffer size calculation used for flow control is also updated " -"to account for the datagram header." -msgstr "" - -#: ../../library/asyncio-protocol.rst:372 -msgid "" -"Close the transport immediately, without waiting for pending operations to " -"complete. Buffered data will be lost. No more data will be received. The " -"protocol's :meth:`protocol.connection_lost() ` " -"method will eventually be called with :const:`None` as its argument." -msgstr "" - -#: ../../library/asyncio-protocol.rst:382 -msgid "Subprocess Transports" -msgstr "" - -#: ../../library/asyncio-protocol.rst:386 -msgid "Return the subprocess process id as an integer." -msgstr "" - -#: ../../library/asyncio-protocol.rst:390 -msgid "" -"Return the transport for the communication pipe corresponding to the integer " -"file descriptor *fd*:" -msgstr "" - -#: ../../library/asyncio-protocol.rst:393 -msgid "" -"``0``: writable streaming transport of the standard input (*stdin*), or :" -"const:`None` if the subprocess was not created with ``stdin=PIPE``" -msgstr "" - -#: ../../library/asyncio-protocol.rst:395 -msgid "" -"``1``: readable streaming transport of the standard output (*stdout*), or :" -"const:`None` if the subprocess was not created with ``stdout=PIPE``" -msgstr "" - -#: ../../library/asyncio-protocol.rst:397 -msgid "" -"``2``: readable streaming transport of the standard error (*stderr*), or :" -"const:`None` if the subprocess was not created with ``stderr=PIPE``" -msgstr "" - -#: ../../library/asyncio-protocol.rst:399 -msgid "other *fd*: :const:`None`" -msgstr "" - -#: ../../library/asyncio-protocol.rst:403 -msgid "" -"Return the subprocess return code as an integer or :const:`None` if it " -"hasn't returned, which is similar to the :attr:`subprocess.Popen.returncode` " -"attribute." -msgstr "" - -#: ../../library/asyncio-protocol.rst:409 -msgid "Kill the subprocess." -msgstr "" - -#: ../../library/asyncio-protocol.rst:411 -msgid "" -"On POSIX systems, the function sends SIGKILL to the subprocess. On Windows, " -"this method is an alias for :meth:`terminate`." -msgstr "" - -#: ../../library/asyncio-protocol.rst:414 -msgid "See also :meth:`subprocess.Popen.kill`." -msgstr "另請參閱 :meth:`subprocess.Popen.kill`。" - -#: ../../library/asyncio-protocol.rst:418 -msgid "" -"Send the *signal* number to the subprocess, as in :meth:`subprocess.Popen." -"send_signal`." -msgstr "" - -#: ../../library/asyncio-protocol.rst:423 -msgid "Stop the subprocess." -msgstr "" - -#: ../../library/asyncio-protocol.rst:425 -msgid "" -"On POSIX systems, this method sends :py:const:`~signal.SIGTERM` to the " -"subprocess. On Windows, the Windows API function :c:func:`!TerminateProcess` " -"is called to stop the subprocess." -msgstr "" - -#: ../../library/asyncio-protocol.rst:429 -msgid "See also :meth:`subprocess.Popen.terminate`." -msgstr "另請參閱 :meth:`subprocess.Popen.terminate`。" - -#: ../../library/asyncio-protocol.rst:433 -msgid "Kill the subprocess by calling the :meth:`kill` method." -msgstr "" - -#: ../../library/asyncio-protocol.rst:435 -msgid "" -"If the subprocess hasn't returned yet, and close transports of *stdin*, " -"*stdout*, and *stderr* pipes." -msgstr "" - -#: ../../library/asyncio-protocol.rst:442 -msgid "Protocols" -msgstr "" - -#: ../../library/asyncio-protocol.rst:444 -msgid "**Source code:** :source:`Lib/asyncio/protocols.py`" -msgstr "**原始碼：**\\ :source:`Lib/asyncio/protocols.py`" - -#: ../../library/asyncio-protocol.rst:448 -msgid "" -"asyncio provides a set of abstract base classes that should be used to " -"implement network protocols. Those classes are meant to be used together " -"with :ref:`transports `." -msgstr "" - -#: ../../library/asyncio-protocol.rst:452 -msgid "" -"Subclasses of abstract base protocol classes may implement some or all " -"methods. All these methods are callbacks: they are called by transports on " -"certain events, for example when some data is received. A base protocol " -"method should be called by the corresponding transport." -msgstr "" - -#: ../../library/asyncio-protocol.rst:459 -msgid "Base Protocols" -msgstr "" - -#: ../../library/asyncio-protocol.rst:463 -msgid "Base protocol with methods that all protocols share." -msgstr "" - -#: ../../library/asyncio-protocol.rst:467 -msgid "" -"The base class for implementing streaming protocols (TCP, Unix sockets, etc)." -msgstr "" - -#: ../../library/asyncio-protocol.rst:472 -msgid "" -"A base class for implementing streaming protocols with manual control of the " -"receive buffer." -msgstr "" - -#: ../../library/asyncio-protocol.rst:477 -msgid "The base class for implementing datagram (UDP) protocols." -msgstr "" - -#: ../../library/asyncio-protocol.rst:481 -msgid "" -"The base class for implementing protocols communicating with child processes " -"(unidirectional pipes)." -msgstr "" - -#: ../../library/asyncio-protocol.rst:486 -msgid "Base Protocol" -msgstr "" - -#: ../../library/asyncio-protocol.rst:488 -msgid "All asyncio protocols can implement Base Protocol callbacks." -msgstr "" - -#: ../../library/asyncio-protocol.rst:491 -msgid "Connection Callbacks" -msgstr "" - -#: ../../library/asyncio-protocol.rst:492 -msgid "" -"Connection callbacks are called on all protocols, exactly once per a " -"successful connection. All other protocol callbacks can only be called " -"between those two methods." -msgstr "" - -#: ../../library/asyncio-protocol.rst:498 -msgid "Called when a connection is made." -msgstr "" - -#: ../../library/asyncio-protocol.rst:500 -msgid "" -"The *transport* argument is the transport representing the connection. The " -"protocol is responsible for storing the reference to its transport." -msgstr "" - -#: ../../library/asyncio-protocol.rst:506 -msgid "Called when the connection is lost or closed." -msgstr "" - -#: ../../library/asyncio-protocol.rst:508 -msgid "" -"The argument is either an exception object or :const:`None`. The latter " -"means a regular EOF is received, or the connection was aborted or closed by " -"this side of the connection." -msgstr "" - -#: ../../library/asyncio-protocol.rst:514 -msgid "Flow Control Callbacks" -msgstr "" - -#: ../../library/asyncio-protocol.rst:515 -msgid "" -"Flow control callbacks can be called by transports to pause or resume " -"writing performed by the protocol." -msgstr "" - -#: ../../library/asyncio-protocol.rst:518 -msgid "" -"See the documentation of the :meth:`~WriteTransport.set_write_buffer_limits` " -"method for more details." -msgstr "" - -#: ../../library/asyncio-protocol.rst:523 -msgid "Called when the transport's buffer goes over the high watermark." -msgstr "" - -#: ../../library/asyncio-protocol.rst:527 -msgid "Called when the transport's buffer drains below the low watermark." -msgstr "" - -#: ../../library/asyncio-protocol.rst:529 -msgid "" -"If the buffer size equals the high watermark, :meth:`~BaseProtocol." -"pause_writing` is not called: the buffer size must go strictly over." -msgstr "" - -#: ../../library/asyncio-protocol.rst:533 -msgid "" -"Conversely, :meth:`~BaseProtocol.resume_writing` is called when the buffer " -"size is equal or lower than the low watermark. These end conditions are " -"important to ensure that things go as expected when either mark is zero." -msgstr "" - -#: ../../library/asyncio-protocol.rst:540 -msgid "Streaming Protocols" -msgstr "" - -#: ../../library/asyncio-protocol.rst:542 -msgid "" -"Event methods, such as :meth:`loop.create_server`, :meth:`loop." -"create_unix_server`, :meth:`loop.create_connection`, :meth:`loop." -"create_unix_connection`, :meth:`loop.connect_accepted_socket`, :meth:`loop." -"connect_read_pipe`, and :meth:`loop.connect_write_pipe` accept factories " -"that return streaming protocols." -msgstr "" - -#: ../../library/asyncio-protocol.rst:550 -msgid "" -"Called when some data is received. *data* is a non-empty bytes object " -"containing the incoming data." -msgstr "" - -#: ../../library/asyncio-protocol.rst:553 -msgid "" -"Whether the data is buffered, chunked or reassembled depends on the " -"transport. In general, you shouldn't rely on specific semantics and instead " -"make your parsing generic and flexible. However, data is always received in " -"the correct order." -msgstr "" - -#: ../../library/asyncio-protocol.rst:558 -msgid "" -"The method can be called an arbitrary number of times while a connection is " -"open." -msgstr "" - -#: ../../library/asyncio-protocol.rst:561 -msgid "" -"However, :meth:`protocol.eof_received() ` is called " -"at most once. Once ``eof_received()`` is called, ``data_received()`` is not " -"called anymore." -msgstr "" - -#: ../../library/asyncio-protocol.rst:567 -msgid "" -"Called when the other end signals it won't send any more data (for example " -"by calling :meth:`transport.write_eof() `, if the " -"other end also uses asyncio)." -msgstr "" - -#: ../../library/asyncio-protocol.rst:572 -msgid "" -"This method may return a false value (including ``None``), in which case the " -"transport will close itself. Conversely, if this method returns a true " -"value, the protocol used determines whether to close the transport. Since " -"the default implementation returns ``None``, it implicitly closes the " -"connection." -msgstr "" - -#: ../../library/asyncio-protocol.rst:578 -msgid "" -"Some transports, including SSL, don't support half-closed connections, in " -"which case returning true from this method will result in the connection " -"being closed." -msgstr "" - -#: ../../library/asyncio-protocol.rst:583 -#: ../../library/asyncio-protocol.rst:641 -msgid "State machine:" -msgstr "" - -#: ../../library/asyncio-protocol.rst:585 -msgid "" -"start -> connection_made\n" -" [-> data_received]*\n" -" [-> eof_received]?\n" -"-> connection_lost -> end" -msgstr "" -"start -> connection_made\n" -" [-> data_received]*\n" -" [-> eof_received]?\n" -"-> connection_lost -> end" - -#: ../../library/asyncio-protocol.rst:594 -msgid "Buffered Streaming Protocols" -msgstr "" - -#: ../../library/asyncio-protocol.rst:598 -msgid "" -"Buffered Protocols can be used with any event loop method that supports " -"`Streaming Protocols`_." -msgstr "" - -#: ../../library/asyncio-protocol.rst:601 -msgid "" -"``BufferedProtocol`` implementations allow explicit manual allocation and " -"control of the receive buffer. Event loops can then use the buffer provided " -"by the protocol to avoid unnecessary data copies. This can result in " -"noticeable performance improvement for protocols that receive big amounts of " -"data. Sophisticated protocol implementations can significantly reduce the " -"number of buffer allocations." -msgstr "" - -#: ../../library/asyncio-protocol.rst:608 -msgid "" -"The following callbacks are called on :class:`BufferedProtocol` instances:" -msgstr "" - -#: ../../library/asyncio-protocol.rst:613 -msgid "Called to allocate a new receive buffer." -msgstr "" - -#: ../../library/asyncio-protocol.rst:615 -msgid "" -"*sizehint* is the recommended minimum size for the returned buffer. It is " -"acceptable to return smaller or larger buffers than what *sizehint* " -"suggests. When set to -1, the buffer size can be arbitrary. It is an error " -"to return a buffer with a zero size." -msgstr "" - -#: ../../library/asyncio-protocol.rst:620 -msgid "" -"``get_buffer()`` must return an object implementing the :ref:`buffer " -"protocol `." -msgstr "" - -#: ../../library/asyncio-protocol.rst:625 -msgid "Called when the buffer was updated with the received data." -msgstr "" - -#: ../../library/asyncio-protocol.rst:627 -msgid "*nbytes* is the total number of bytes that were written to the buffer." -msgstr "" - -#: ../../library/asyncio-protocol.rst:631 -msgid "" -"See the documentation of the :meth:`protocol.eof_received() ` method." -msgstr "" - -#: ../../library/asyncio-protocol.rst:635 -msgid "" -":meth:`~BufferedProtocol.get_buffer` can be called an arbitrary number of " -"times during a connection. However, :meth:`protocol.eof_received() " -"` is called at most once and, if called, :meth:" -"`~BufferedProtocol.get_buffer` and :meth:`~BufferedProtocol.buffer_updated` " -"won't be called after it." -msgstr "" - -#: ../../library/asyncio-protocol.rst:643 -msgid "" -"start -> connection_made\n" -" [-> get_buffer\n" -" [-> buffer_updated]?\n" -" ]*\n" -" [-> eof_received]?\n" -"-> connection_lost -> end" -msgstr "" -"start -> connection_made\n" -" [-> get_buffer\n" -" [-> buffer_updated]?\n" -" ]*\n" -" [-> eof_received]?\n" -"-> connection_lost -> end" - -#: ../../library/asyncio-protocol.rst:654 -msgid "Datagram Protocols" -msgstr "" - -#: ../../library/asyncio-protocol.rst:656 -msgid "" -"Datagram Protocol instances should be constructed by protocol factories " -"passed to the :meth:`loop.create_datagram_endpoint` method." -msgstr "" - -#: ../../library/asyncio-protocol.rst:661 -msgid "" -"Called when a datagram is received. *data* is a bytes object containing the " -"incoming data. *addr* is the address of the peer sending the data; the " -"exact format depends on the transport." -msgstr "" - -#: ../../library/asyncio-protocol.rst:667 -msgid "" -"Called when a previous send or receive operation raises an :class:" -"`OSError`. *exc* is the :class:`OSError` instance." -msgstr "" - -#: ../../library/asyncio-protocol.rst:670 -msgid "" -"This method is called in rare conditions, when the transport (e.g. UDP) " -"detects that a datagram could not be delivered to its recipient. In many " -"conditions though, undeliverable datagrams will be silently dropped." -msgstr "" - -#: ../../library/asyncio-protocol.rst:677 -msgid "" -"On BSD systems (macOS, FreeBSD, etc.) flow control is not supported for " -"datagram protocols, because there is no reliable way to detect send failures " -"caused by writing too many packets." -msgstr "" - -#: ../../library/asyncio-protocol.rst:681 -msgid "" -"The socket always appears 'ready' and excess packets are dropped. An :class:" -"`OSError` with ``errno`` set to :const:`errno.ENOBUFS` may or may not be " -"raised; if it is raised, it will be reported to :meth:`DatagramProtocol." -"error_received` but otherwise ignored." -msgstr "" - -#: ../../library/asyncio-protocol.rst:690 -msgid "Subprocess Protocols" -msgstr "" - -#: ../../library/asyncio-protocol.rst:692 -msgid "" -"Subprocess Protocol instances should be constructed by protocol factories " -"passed to the :meth:`loop.subprocess_exec` and :meth:`loop.subprocess_shell` " -"methods." -msgstr "" - -#: ../../library/asyncio-protocol.rst:698 -msgid "" -"Called when the child process writes data into its stdout or stderr pipe." -msgstr "" - -#: ../../library/asyncio-protocol.rst:701 -msgid "*fd* is the integer file descriptor of the pipe." -msgstr "" - -#: ../../library/asyncio-protocol.rst:703 -msgid "*data* is a non-empty bytes object containing the received data." -msgstr "" - -#: ../../library/asyncio-protocol.rst:707 -msgid "" -"Called when one of the pipes communicating with the child process is closed." -msgstr "" - -#: ../../library/asyncio-protocol.rst:710 -msgid "*fd* is the integer file descriptor that was closed." -msgstr "" - -#: ../../library/asyncio-protocol.rst:714 -msgid "Called when the child process has exited." -msgstr "" - -#: ../../library/asyncio-protocol.rst:716 -msgid "" -"It can be called before :meth:`~SubprocessProtocol.pipe_data_received` and :" -"meth:`~SubprocessProtocol.pipe_connection_lost` methods." -msgstr "" - -#: ../../library/asyncio-protocol.rst:721 -msgid "Examples" -msgstr "範例" - -#: ../../library/asyncio-protocol.rst:726 -msgid "TCP Echo Server" -msgstr "" - -#: ../../library/asyncio-protocol.rst:728 -msgid "" -"Create a TCP echo server using the :meth:`loop.create_server` method, send " -"back received data, and close the connection::" -msgstr "" - -#: ../../library/asyncio-protocol.rst:731 -msgid "" -"import asyncio\n" -"\n" -"\n" -"class EchoServerProtocol(asyncio.Protocol):\n" -" def connection_made(self, transport):\n" -" peername = transport.get_extra_info('peername')\n" -" print('Connection from {}'.format(peername))\n" -" self.transport = transport\n" -"\n" -" def data_received(self, data):\n" -" message = data.decode()\n" -" print('Data received: {!r}'.format(message))\n" -"\n" -" print('Send: {!r}'.format(message))\n" -" self.transport.write(data)\n" -"\n" -" print('Close the client socket')\n" -" self.transport.close()\n" -"\n" -"\n" -"async def main():\n" -" # Get a reference to the event loop as we plan to use\n" -" # low-level APIs.\n" -" loop = asyncio.get_running_loop()\n" -"\n" -" server = await loop.create_server(\n" -" EchoServerProtocol,\n" -" '127.0.0.1', 8888)\n" -"\n" -" async with server:\n" -" await server.serve_forever()\n" -"\n" -"\n" -"asyncio.run(main())" -msgstr "" - -#: ../../library/asyncio-protocol.rst:769 -msgid "" -"The :ref:`TCP echo server using streams ` " -"example uses the high-level :func:`asyncio.start_server` function." -msgstr "" - -#: ../../library/asyncio-protocol.rst:775 -msgid "TCP Echo Client" -msgstr "" - -#: ../../library/asyncio-protocol.rst:777 -msgid "" -"A TCP echo client using the :meth:`loop.create_connection` method, sends " -"data, and waits until the connection is closed::" -msgstr "" - -#: ../../library/asyncio-protocol.rst:780 -msgid "" -"import asyncio\n" -"\n" -"\n" -"class EchoClientProtocol(asyncio.Protocol):\n" -" def __init__(self, message, on_con_lost):\n" -" self.message = message\n" -" self.on_con_lost = on_con_lost\n" -"\n" -" def connection_made(self, transport):\n" -" transport.write(self.message.encode())\n" -" print('Data sent: {!r}'.format(self.message))\n" -"\n" -" def data_received(self, data):\n" -" print('Data received: {!r}'.format(data.decode()))\n" -"\n" -" def connection_lost(self, exc):\n" -" print('The server closed the connection')\n" -" self.on_con_lost.set_result(True)\n" -"\n" -"\n" -"async def main():\n" -" # Get a reference to the event loop as we plan to use\n" -" # low-level APIs.\n" -" loop = asyncio.get_running_loop()\n" -"\n" -" on_con_lost = loop.create_future()\n" -" message = 'Hello World!'\n" -"\n" -" transport, protocol = await loop.create_connection(\n" -" lambda: EchoClientProtocol(message, on_con_lost),\n" -" '127.0.0.1', 8888)\n" -"\n" -" # Wait until the protocol signals that the connection\n" -" # is lost and close the transport.\n" -" try:\n" -" await on_con_lost\n" -" finally:\n" -" transport.close()\n" -"\n" -"\n" -"asyncio.run(main())" -msgstr "" - -#: ../../library/asyncio-protocol.rst:825 -msgid "" -"The :ref:`TCP echo client using streams ` " -"example uses the high-level :func:`asyncio.open_connection` function." -msgstr "" - -#: ../../library/asyncio-protocol.rst:832 -msgid "UDP Echo Server" -msgstr "" - -#: ../../library/asyncio-protocol.rst:834 -msgid "" -"A UDP echo server, using the :meth:`loop.create_datagram_endpoint` method, " -"sends back received data::" -msgstr "" - -#: ../../library/asyncio-protocol.rst:837 -msgid "" -"import asyncio\n" -"\n" -"\n" -"class EchoServerProtocol:\n" -" def connection_made(self, transport):\n" -" self.transport = transport\n" -"\n" -" def datagram_received(self, data, addr):\n" -" message = data.decode()\n" -" print('Received %r from %s' % (message, addr))\n" -" print('Send %r to %s' % (message, addr))\n" -" self.transport.sendto(data, addr)\n" -"\n" -"\n" -"async def main():\n" -" print(\"Starting UDP server\")\n" -"\n" -" # Get a reference to the event loop as we plan to use\n" -" # low-level APIs.\n" -" loop = asyncio.get_running_loop()\n" -"\n" -" # One protocol instance will be created to serve all\n" -" # client requests.\n" -" transport, protocol = await loop.create_datagram_endpoint(\n" -" EchoServerProtocol,\n" -" local_addr=('127.0.0.1', 9999))\n" -"\n" -" try:\n" -" await asyncio.sleep(3600) # Serve for 1 hour.\n" -" finally:\n" -" transport.close()\n" -"\n" -"\n" -"asyncio.run(main())" -msgstr "" - -#: ../../library/asyncio-protocol.rst:876 -msgid "UDP Echo Client" -msgstr "" - -#: ../../library/asyncio-protocol.rst:878 -msgid "" -"A UDP echo client, using the :meth:`loop.create_datagram_endpoint` method, " -"sends data and closes the transport when it receives the answer::" -msgstr "" - -#: ../../library/asyncio-protocol.rst:881 -msgid "" -"import asyncio\n" -"\n" -"\n" -"class EchoClientProtocol:\n" -" def __init__(self, message, on_con_lost):\n" -" self.message = message\n" -" self.on_con_lost = on_con_lost\n" -" self.transport = None\n" -"\n" -" def connection_made(self, transport):\n" -" self.transport = transport\n" -" print('Send:', self.message)\n" -" self.transport.sendto(self.message.encode())\n" -"\n" -" def datagram_received(self, data, addr):\n" -" print(\"Received:\", data.decode())\n" -"\n" -" print(\"Close the socket\")\n" -" self.transport.close()\n" -"\n" -" def error_received(self, exc):\n" -" print('Error received:', exc)\n" -"\n" -" def connection_lost(self, exc):\n" -" print(\"Connection closed\")\n" -" self.on_con_lost.set_result(True)\n" -"\n" -"\n" -"async def main():\n" -" # Get a reference to the event loop as we plan to use\n" -" # low-level APIs.\n" -" loop = asyncio.get_running_loop()\n" -"\n" -" on_con_lost = loop.create_future()\n" -" message = \"Hello World!\"\n" -"\n" -" transport, protocol = await loop.create_datagram_endpoint(\n" -" lambda: EchoClientProtocol(message, on_con_lost),\n" -" remote_addr=('127.0.0.1', 9999))\n" -"\n" -" try:\n" -" await on_con_lost\n" -" finally:\n" -" transport.close()\n" -"\n" -"\n" -"asyncio.run(main())" -msgstr "" - -#: ../../library/asyncio-protocol.rst:933 -msgid "Connecting Existing Sockets" -msgstr "" - -#: ../../library/asyncio-protocol.rst:935 -msgid "" -"Wait until a socket receives data using the :meth:`loop.create_connection` " -"method with a protocol::" -msgstr "" - -#: ../../library/asyncio-protocol.rst:938 -msgid "" -"import asyncio\n" -"import socket\n" -"\n" -"\n" -"class MyProtocol(asyncio.Protocol):\n" -"\n" -" def __init__(self, on_con_lost):\n" -" self.transport = None\n" -" self.on_con_lost = on_con_lost\n" -"\n" -" def connection_made(self, transport):\n" -" self.transport = transport\n" -"\n" -" def data_received(self, data):\n" -" print(\"Received:\", data.decode())\n" -"\n" -" # We are done: close the transport;\n" -" # connection_lost() will be called automatically.\n" -" self.transport.close()\n" -"\n" -" def connection_lost(self, exc):\n" -" # The socket has been closed\n" -" self.on_con_lost.set_result(True)\n" -"\n" -"\n" -"async def main():\n" -" # Get a reference to the event loop as we plan to use\n" -" # low-level APIs.\n" -" loop = asyncio.get_running_loop()\n" -" on_con_lost = loop.create_future()\n" -"\n" -" # Create a pair of connected sockets\n" -" rsock, wsock = socket.socketpair()\n" -"\n" -" # Register the socket to wait for data.\n" -" transport, protocol = await loop.create_connection(\n" -" lambda: MyProtocol(on_con_lost), sock=rsock)\n" -"\n" -" # Simulate the reception of data from the network.\n" -" loop.call_soon(wsock.send, 'abc'.encode())\n" -"\n" -" try:\n" -" await protocol.on_con_lost\n" -" finally:\n" -" transport.close()\n" -" wsock.close()\n" -"\n" -"asyncio.run(main())" -msgstr "" - -#: ../../library/asyncio-protocol.rst:989 -msgid "" -"The :ref:`watch a file descriptor for read events " -"` example uses the low-level :meth:`loop." -"add_reader` method to register an FD." -msgstr "" - -#: ../../library/asyncio-protocol.rst:993 -msgid "" -"The :ref:`register an open socket to wait for data using streams " -"` example uses high-level streams " -"created by the :func:`open_connection` function in a coroutine." -msgstr "" - -#: ../../library/asyncio-protocol.rst:1000 -msgid "loop.subprocess_exec() and SubprocessProtocol" -msgstr "" - -#: ../../library/asyncio-protocol.rst:1002 -msgid "" -"An example of a subprocess protocol used to get the output of a subprocess " -"and to wait for the subprocess exit." -msgstr "" - -#: ../../library/asyncio-protocol.rst:1005 -msgid "The subprocess is created by the :meth:`loop.subprocess_exec` method::" -msgstr "" - -#: ../../library/asyncio-protocol.rst:1007 -msgid "" -"import asyncio\n" -"import sys\n" -"\n" -"class DateProtocol(asyncio.SubprocessProtocol):\n" -" def __init__(self, exit_future):\n" -" self.exit_future = exit_future\n" -" self.output = bytearray()\n" -" self.pipe_closed = False\n" -" self.exited = False\n" -"\n" -" def pipe_connection_lost(self, fd, exc):\n" -" self.pipe_closed = True\n" -" self.check_for_exit()\n" -"\n" -" def pipe_data_received(self, fd, data):\n" -" self.output.extend(data)\n" -"\n" -" def process_exited(self):\n" -" self.exited = True\n" -" # process_exited() method can be called before\n" -" # pipe_connection_lost() method: wait until both methods are\n" -" # called.\n" -" self.check_for_exit()\n" -"\n" -" def check_for_exit(self):\n" -" if self.pipe_closed and self.exited:\n" -" self.exit_future.set_result(True)\n" -"\n" -"async def get_date():\n" -" # Get a reference to the event loop as we plan to use\n" -" # low-level APIs.\n" -" loop = asyncio.get_running_loop()\n" -"\n" -" code = 'import datetime; print(datetime.datetime.now())'\n" -" exit_future = asyncio.Future(loop=loop)\n" -"\n" -" # Create the subprocess controlled by DateProtocol;\n" -" # redirect the standard output into a pipe.\n" -" transport, protocol = await loop.subprocess_exec(\n" -" lambda: DateProtocol(exit_future),\n" -" sys.executable, '-c', code,\n" -" stdin=None, stderr=None)\n" -"\n" -" # Wait for the subprocess exit using the process_exited()\n" -" # method of the protocol.\n" -" await exit_future\n" -"\n" -" # Close the stdout pipe.\n" -" transport.close()\n" -"\n" -" # Read the output which was collected by the\n" -" # pipe_data_received() method of the protocol.\n" -" data = bytes(protocol.output)\n" -" return data.decode('ascii').rstrip()\n" -"\n" -"date = asyncio.run(get_date())\n" -"print(f\"Current date: {date}\")" -msgstr "" - -#: ../../library/asyncio-protocol.rst:1065 -msgid "" -"See also the :ref:`same example ` " -"written using high-level APIs." -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-08-17 00:18+0000\n" +"PO-Revision-Date: 2018-05-23 14:39+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/asyncio-protocol.rst:9 +msgid "Transports and Protocols" +msgstr "傳輸與協定" + +#: ../../library/asyncio-protocol.rst:12 +msgid "Preface" +msgstr "前言" + +#: ../../library/asyncio-protocol.rst:13 +msgid "" +"Transports and Protocols are used by the **low-level** event loop APIs such " +"as :meth:`loop.create_connection`. They use callback-based programming " +"style and enable high-performance implementations of network or IPC " +"protocols (e.g. HTTP)." +msgstr "" + +#: ../../library/asyncio-protocol.rst:18 +msgid "" +"Essentially, transports and protocols should only be used in libraries and " +"frameworks and never in high-level asyncio applications." +msgstr "" + +#: ../../library/asyncio-protocol.rst:22 +msgid "This documentation page covers both `Transports`_ and `Protocols`_." +msgstr "" + +#: ../../library/asyncio-protocol.rst:25 +msgid "Introduction" +msgstr "" + +#: ../../library/asyncio-protocol.rst:26 +msgid "" +"At the highest level, the transport is concerned with *how* bytes are " +"transmitted, while the protocol determines *which* bytes to transmit (and to " +"some extent when)." +msgstr "" + +#: ../../library/asyncio-protocol.rst:30 +msgid "" +"A different way of saying the same thing: a transport is an abstraction for " +"a socket (or similar I/O endpoint) while a protocol is an abstraction for an " +"application, from the transport's point of view." +msgstr "" + +#: ../../library/asyncio-protocol.rst:35 +msgid "" +"Yet another view is the transport and protocol interfaces together define an " +"abstract interface for using network I/O and interprocess I/O." +msgstr "" + +#: ../../library/asyncio-protocol.rst:39 +msgid "" +"There is always a 1:1 relationship between transport and protocol objects: " +"the protocol calls transport methods to send data, while the transport calls " +"protocol methods to pass it data that has been received." +msgstr "" + +#: ../../library/asyncio-protocol.rst:44 +msgid "" +"Most of connection oriented event loop methods (such as :meth:`loop." +"create_connection`) usually accept a *protocol_factory* argument used to " +"create a *Protocol* object for an accepted connection, represented by a " +"*Transport* object. Such methods usually return a tuple of ``(transport, " +"protocol)``." +msgstr "" + +#: ../../library/asyncio-protocol.rst:51 +msgid "Contents" +msgstr "目錄" + +#: ../../library/asyncio-protocol.rst:52 +msgid "This documentation page contains the following sections:" +msgstr "" + +#: ../../library/asyncio-protocol.rst:54 +msgid "" +"The `Transports`_ section documents asyncio :class:`BaseTransport`, :class:" +"`ReadTransport`, :class:`WriteTransport`, :class:`Transport`, :class:" +"`DatagramTransport`, and :class:`SubprocessTransport` classes." +msgstr "" + +#: ../../library/asyncio-protocol.rst:59 +msgid "" +"The `Protocols`_ section documents asyncio :class:`BaseProtocol`, :class:" +"`Protocol`, :class:`BufferedProtocol`, :class:`DatagramProtocol`, and :class:" +"`SubprocessProtocol` classes." +msgstr "" + +#: ../../library/asyncio-protocol.rst:63 +msgid "" +"The `Examples`_ section showcases how to work with transports, protocols, " +"and low-level event loop APIs." +msgstr "" + +#: ../../library/asyncio-protocol.rst:70 +msgid "Transports" +msgstr "" + +#: ../../library/asyncio-protocol.rst:72 +msgid "**Source code:** :source:`Lib/asyncio/transports.py`" +msgstr "**原始碼：**\\ :source:`Lib/asyncio/transports.py`" + +#: ../../library/asyncio-protocol.rst:76 +msgid "" +"Transports are classes provided by :mod:`asyncio` in order to abstract " +"various kinds of communication channels." +msgstr "" + +#: ../../library/asyncio-protocol.rst:79 +msgid "" +"Transport objects are always instantiated by an :ref:`asyncio event loop " +"`." +msgstr "" + +#: ../../library/asyncio-protocol.rst:82 +msgid "" +"asyncio implements transports for TCP, UDP, SSL, and subprocess pipes. The " +"methods available on a transport depend on the transport's kind." +msgstr "" + +#: ../../library/asyncio-protocol.rst:85 +msgid "" +"The transport classes are :ref:`not thread safe `." +msgstr "" + +#: ../../library/asyncio-protocol.rst:89 +msgid "Transports Hierarchy" +msgstr "" + +#: ../../library/asyncio-protocol.rst:93 +msgid "" +"Base class for all transports. Contains methods that all asyncio transports " +"share." +msgstr "" + +#: ../../library/asyncio-protocol.rst:98 +msgid "A base transport for write-only connections." +msgstr "" + +#: ../../library/asyncio-protocol.rst:100 +msgid "" +"Instances of the *WriteTransport* class are returned from the :meth:`loop." +"connect_write_pipe` event loop method and are also used by subprocess-" +"related methods like :meth:`loop.subprocess_exec`." +msgstr "" + +#: ../../library/asyncio-protocol.rst:107 +msgid "A base transport for read-only connections." +msgstr "" + +#: ../../library/asyncio-protocol.rst:109 +msgid "" +"Instances of the *ReadTransport* class are returned from the :meth:`loop." +"connect_read_pipe` event loop method and are also used by subprocess-related " +"methods like :meth:`loop.subprocess_exec`." +msgstr "" + +#: ../../library/asyncio-protocol.rst:116 +msgid "" +"Interface representing a bidirectional transport, such as a TCP connection." +msgstr "" + +#: ../../library/asyncio-protocol.rst:119 +msgid "" +"The user does not instantiate a transport directly; they call a utility " +"function, passing it a protocol factory and other information necessary to " +"create the transport and protocol." +msgstr "" + +#: ../../library/asyncio-protocol.rst:123 +msgid "" +"Instances of the *Transport* class are returned from or used by event loop " +"methods like :meth:`loop.create_connection`, :meth:`loop." +"create_unix_connection`, :meth:`loop.create_server`, :meth:`loop.sendfile`, " +"etc." +msgstr "" + +#: ../../library/asyncio-protocol.rst:131 +msgid "A transport for datagram (UDP) connections." +msgstr "" + +#: ../../library/asyncio-protocol.rst:133 +msgid "" +"Instances of the *DatagramTransport* class are returned from the :meth:`loop." +"create_datagram_endpoint` event loop method." +msgstr "" + +#: ../../library/asyncio-protocol.rst:139 +msgid "" +"An abstraction to represent a connection between a parent and its child OS " +"process." +msgstr "" + +#: ../../library/asyncio-protocol.rst:142 +msgid "" +"Instances of the *SubprocessTransport* class are returned from event loop " +"methods :meth:`loop.subprocess_shell` and :meth:`loop.subprocess_exec`." +msgstr "" + +#: ../../library/asyncio-protocol.rst:148 +msgid "Base Transport" +msgstr "" + +#: ../../library/asyncio-protocol.rst:152 +msgid "Close the transport." +msgstr "" + +#: ../../library/asyncio-protocol.rst:154 +msgid "" +"If the transport has a buffer for outgoing data, buffered data will be " +"flushed asynchronously. No more data will be received. After all buffered " +"data is flushed, the protocol's :meth:`protocol.connection_lost() " +"` method will be called with :const:`None` as " +"its argument. The transport should not be used once it is closed." +msgstr "" + +#: ../../library/asyncio-protocol.rst:164 +msgid "Return ``True`` if the transport is closing or is closed." +msgstr "" + +#: ../../library/asyncio-protocol.rst:168 +msgid "Return information about the transport or underlying resources it uses." +msgstr "" + +#: ../../library/asyncio-protocol.rst:171 +msgid "" +"*name* is a string representing the piece of transport-specific information " +"to get." +msgstr "" + +#: ../../library/asyncio-protocol.rst:174 +msgid "" +"*default* is the value to return if the information is not available, or if " +"the transport does not support querying it with the given third-party event " +"loop implementation or on the current platform." +msgstr "" + +#: ../../library/asyncio-protocol.rst:179 +msgid "" +"For example, the following code attempts to get the underlying socket object " +"of the transport::" +msgstr "" + +#: ../../library/asyncio-protocol.rst:182 +msgid "" +"sock = transport.get_extra_info('socket')\n" +"if sock is not None:\n" +" print(sock.getsockopt(...))" +msgstr "" +"sock = transport.get_extra_info('socket')\n" +"if sock is not None:\n" +" print(sock.getsockopt(...))" + +#: ../../library/asyncio-protocol.rst:186 +msgid "Categories of information that can be queried on some transports:" +msgstr "" + +#: ../../library/asyncio-protocol.rst:188 +msgid "socket:" +msgstr "" + +#: ../../library/asyncio-protocol.rst:190 +msgid "" +"``'peername'``: the remote address to which the socket is connected, result " +"of :meth:`socket.socket.getpeername` (``None`` on error)" +msgstr "" + +#: ../../library/asyncio-protocol.rst:194 +msgid "``'socket'``: :class:`socket.socket` instance" +msgstr "" + +#: ../../library/asyncio-protocol.rst:196 +msgid "" +"``'sockname'``: the socket's own address, result of :meth:`socket.socket." +"getsockname`" +msgstr "" + +#: ../../library/asyncio-protocol.rst:199 +msgid "SSL socket:" +msgstr "" + +#: ../../library/asyncio-protocol.rst:201 +msgid "" +"``'compression'``: the compression algorithm being used as a string, or " +"``None`` if the connection isn't compressed; result of :meth:`ssl.SSLSocket." +"compression`" +msgstr "" + +#: ../../library/asyncio-protocol.rst:205 +msgid "" +"``'cipher'``: a three-value tuple containing the name of the cipher being " +"used, the version of the SSL protocol that defines its use, and the number " +"of secret bits being used; result of :meth:`ssl.SSLSocket.cipher`" +msgstr "" + +#: ../../library/asyncio-protocol.rst:210 +msgid "" +"``'peercert'``: peer certificate; result of :meth:`ssl.SSLSocket.getpeercert`" +msgstr "" + +#: ../../library/asyncio-protocol.rst:213 +msgid "``'sslcontext'``: :class:`ssl.SSLContext` instance" +msgstr "" + +#: ../../library/asyncio-protocol.rst:215 +msgid "" +"``'ssl_object'``: :class:`ssl.SSLObject` or :class:`ssl.SSLSocket` instance" +msgstr "" + +#: ../../library/asyncio-protocol.rst:218 +msgid "pipe:" +msgstr "" + +#: ../../library/asyncio-protocol.rst:220 +msgid "``'pipe'``: pipe object" +msgstr "" + +#: ../../library/asyncio-protocol.rst:222 +msgid "subprocess:" +msgstr "" + +#: ../../library/asyncio-protocol.rst:224 +msgid "``'subprocess'``: :class:`subprocess.Popen` instance" +msgstr "" + +#: ../../library/asyncio-protocol.rst:228 +msgid "Set a new protocol." +msgstr "" + +#: ../../library/asyncio-protocol.rst:230 +msgid "" +"Switching protocol should only be done when both protocols are documented to " +"support the switch." +msgstr "" + +#: ../../library/asyncio-protocol.rst:235 +msgid "Return the current protocol." +msgstr "" + +#: ../../library/asyncio-protocol.rst:239 +msgid "Read-only Transports" +msgstr "" + +#: ../../library/asyncio-protocol.rst:243 +msgid "Return ``True`` if the transport is receiving new data." +msgstr "" + +#: ../../library/asyncio-protocol.rst:249 +msgid "" +"Pause the receiving end of the transport. No data will be passed to the " +"protocol's :meth:`protocol.data_received() ` method " +"until :meth:`resume_reading` is called." +msgstr "" + +#: ../../library/asyncio-protocol.rst:253 +msgid "" +"The method is idempotent, i.e. it can be called when the transport is " +"already paused or closed." +msgstr "" + +#: ../../library/asyncio-protocol.rst:259 +msgid "" +"Resume the receiving end. The protocol's :meth:`protocol.data_received() " +"` method will be called once again if some data is " +"available for reading." +msgstr "" + +#: ../../library/asyncio-protocol.rst:263 +msgid "" +"The method is idempotent, i.e. it can be called when the transport is " +"already reading." +msgstr "" + +#: ../../library/asyncio-protocol.rst:269 +msgid "Write-only Transports" +msgstr "" + +#: ../../library/asyncio-protocol.rst:273 +msgid "" +"Close the transport immediately, without waiting for pending operations to " +"complete. Buffered data will be lost. No more data will be received. The " +"protocol's :meth:`protocol.connection_lost() ` " +"method will eventually be called with :const:`None` as its argument." +msgstr "" + +#: ../../library/asyncio-protocol.rst:281 +msgid "" +"Return :const:`True` if the transport supports :meth:`~WriteTransport." +"write_eof`, :const:`False` if not." +msgstr "" + +#: ../../library/asyncio-protocol.rst:286 +msgid "Return the current size of the output buffer used by the transport." +msgstr "" + +#: ../../library/asyncio-protocol.rst:290 +msgid "" +"Get the *high* and *low* watermarks for write flow control. Return a tuple " +"``(low, high)`` where *low* and *high* are positive number of bytes." +msgstr "" + +#: ../../library/asyncio-protocol.rst:294 +msgid "Use :meth:`set_write_buffer_limits` to set the limits." +msgstr "" + +#: ../../library/asyncio-protocol.rst:300 +msgid "Set the *high* and *low* watermarks for write flow control." +msgstr "" + +#: ../../library/asyncio-protocol.rst:302 +msgid "" +"These two values (measured in number of bytes) control when the protocol's :" +"meth:`protocol.pause_writing() ` and :meth:" +"`protocol.resume_writing() ` methods are " +"called. If specified, the low watermark must be less than or equal to the " +"high watermark. Neither *high* nor *low* can be negative." +msgstr "" + +#: ../../library/asyncio-protocol.rst:310 +msgid "" +":meth:`~BaseProtocol.pause_writing` is called when the buffer size becomes " +"greater than or equal to the *high* value. If writing has been paused, :meth:" +"`~BaseProtocol.resume_writing` is called when the buffer size becomes less " +"than or equal to the *low* value." +msgstr "" + +#: ../../library/asyncio-protocol.rst:315 +msgid "" +"The defaults are implementation-specific. If only the high watermark is " +"given, the low watermark defaults to an implementation-specific value less " +"than or equal to the high watermark. Setting *high* to zero forces *low* to " +"zero as well, and causes :meth:`~BaseProtocol.pause_writing` to be called " +"whenever the buffer becomes non-empty. Setting *low* to zero causes :meth:" +"`~BaseProtocol.resume_writing` to be called only once the buffer is empty. " +"Use of zero for either limit is generally sub-optimal as it reduces " +"opportunities for doing I/O and computation concurrently." +msgstr "" + +#: ../../library/asyncio-protocol.rst:326 +msgid "Use :meth:`~WriteTransport.get_write_buffer_limits` to get the limits." +msgstr "" + +#: ../../library/asyncio-protocol.rst:331 +msgid "Write some *data* bytes to the transport." +msgstr "" + +#: ../../library/asyncio-protocol.rst:333 +#: ../../library/asyncio-protocol.rst:362 +msgid "" +"This method does not block; it buffers the data and arranges for it to be " +"sent out asynchronously." +msgstr "" + +#: ../../library/asyncio-protocol.rst:338 +msgid "" +"Write a list (or any iterable) of data bytes to the transport. This is " +"functionally equivalent to calling :meth:`write` on each element yielded by " +"the iterable, but may be implemented more efficiently." +msgstr "" + +#: ../../library/asyncio-protocol.rst:345 +msgid "" +"Close the write end of the transport after flushing all buffered data. Data " +"may still be received." +msgstr "" + +#: ../../library/asyncio-protocol.rst:348 +msgid "" +"This method can raise :exc:`NotImplementedError` if the transport (e.g. SSL) " +"doesn't support half-closed connections." +msgstr "" + +#: ../../library/asyncio-protocol.rst:353 +msgid "Datagram Transports" +msgstr "" + +#: ../../library/asyncio-protocol.rst:357 +msgid "" +"Send the *data* bytes to the remote peer given by *addr* (a transport-" +"dependent target address). If *addr* is :const:`None`, the data is sent to " +"the target address given on transport creation." +msgstr "" + +#: ../../library/asyncio-protocol.rst:365 +msgid "" +"This method can be called with an empty bytes object to send a zero-length " +"datagram. The buffer size calculation used for flow control is also updated " +"to account for the datagram header." +msgstr "" + +#: ../../library/asyncio-protocol.rst:372 +msgid "" +"Close the transport immediately, without waiting for pending operations to " +"complete. Buffered data will be lost. No more data will be received. The " +"protocol's :meth:`protocol.connection_lost() ` " +"method will eventually be called with :const:`None` as its argument." +msgstr "" + +#: ../../library/asyncio-protocol.rst:382 +msgid "Subprocess Transports" +msgstr "" + +#: ../../library/asyncio-protocol.rst:386 +msgid "Return the subprocess process id as an integer." +msgstr "" + +#: ../../library/asyncio-protocol.rst:390 +msgid "" +"Return the transport for the communication pipe corresponding to the integer " +"file descriptor *fd*:" +msgstr "" + +#: ../../library/asyncio-protocol.rst:393 +msgid "" +"``0``: writable streaming transport of the standard input (*stdin*), or :" +"const:`None` if the subprocess was not created with ``stdin=PIPE``" +msgstr "" + +#: ../../library/asyncio-protocol.rst:395 +msgid "" +"``1``: readable streaming transport of the standard output (*stdout*), or :" +"const:`None` if the subprocess was not created with ``stdout=PIPE``" +msgstr "" + +#: ../../library/asyncio-protocol.rst:397 +msgid "" +"``2``: readable streaming transport of the standard error (*stderr*), or :" +"const:`None` if the subprocess was not created with ``stderr=PIPE``" +msgstr "" + +#: ../../library/asyncio-protocol.rst:399 +msgid "other *fd*: :const:`None`" +msgstr "" + +#: ../../library/asyncio-protocol.rst:403 +msgid "" +"Return the subprocess return code as an integer or :const:`None` if it " +"hasn't returned, which is similar to the :attr:`subprocess.Popen.returncode` " +"attribute." +msgstr "" + +#: ../../library/asyncio-protocol.rst:409 +msgid "Kill the subprocess." +msgstr "" + +#: ../../library/asyncio-protocol.rst:411 +msgid "" +"On POSIX systems, the function sends SIGKILL to the subprocess. On Windows, " +"this method is an alias for :meth:`terminate`." +msgstr "" + +#: ../../library/asyncio-protocol.rst:414 +msgid "See also :meth:`subprocess.Popen.kill`." +msgstr "另請參閱 :meth:`subprocess.Popen.kill`。" + +#: ../../library/asyncio-protocol.rst:418 +msgid "" +"Send the *signal* number to the subprocess, as in :meth:`subprocess.Popen." +"send_signal`." +msgstr "" + +#: ../../library/asyncio-protocol.rst:423 +msgid "Stop the subprocess." +msgstr "" + +#: ../../library/asyncio-protocol.rst:425 +msgid "" +"On POSIX systems, this method sends :py:const:`~signal.SIGTERM` to the " +"subprocess. On Windows, the Windows API function :c:func:`!TerminateProcess` " +"is called to stop the subprocess." +msgstr "" + +#: ../../library/asyncio-protocol.rst:429 +msgid "See also :meth:`subprocess.Popen.terminate`." +msgstr "另請參閱 :meth:`subprocess.Popen.terminate`。" + +#: ../../library/asyncio-protocol.rst:433 +msgid "Kill the subprocess by calling the :meth:`kill` method." +msgstr "" + +#: ../../library/asyncio-protocol.rst:435 +msgid "" +"If the subprocess hasn't returned yet, and close transports of *stdin*, " +"*stdout*, and *stderr* pipes." +msgstr "" + +#: ../../library/asyncio-protocol.rst:442 +msgid "Protocols" +msgstr "" + +#: ../../library/asyncio-protocol.rst:444 +msgid "**Source code:** :source:`Lib/asyncio/protocols.py`" +msgstr "**原始碼：**\\ :source:`Lib/asyncio/protocols.py`" + +#: ../../library/asyncio-protocol.rst:448 +msgid "" +"asyncio provides a set of abstract base classes that should be used to " +"implement network protocols. Those classes are meant to be used together " +"with :ref:`transports `." +msgstr "" + +#: ../../library/asyncio-protocol.rst:452 +msgid "" +"Subclasses of abstract base protocol classes may implement some or all " +"methods. All these methods are callbacks: they are called by transports on " +"certain events, for example when some data is received. A base protocol " +"method should be called by the corresponding transport." +msgstr "" + +#: ../../library/asyncio-protocol.rst:459 +msgid "Base Protocols" +msgstr "" + +#: ../../library/asyncio-protocol.rst:463 +msgid "Base protocol with methods that all protocols share." +msgstr "" + +#: ../../library/asyncio-protocol.rst:467 +msgid "" +"The base class for implementing streaming protocols (TCP, Unix sockets, etc)." +msgstr "" + +#: ../../library/asyncio-protocol.rst:472 +msgid "" +"A base class for implementing streaming protocols with manual control of the " +"receive buffer." +msgstr "" + +#: ../../library/asyncio-protocol.rst:477 +msgid "The base class for implementing datagram (UDP) protocols." +msgstr "" + +#: ../../library/asyncio-protocol.rst:481 +msgid "" +"The base class for implementing protocols communicating with child processes " +"(unidirectional pipes)." +msgstr "" + +#: ../../library/asyncio-protocol.rst:486 +msgid "Base Protocol" +msgstr "" + +#: ../../library/asyncio-protocol.rst:488 +msgid "All asyncio protocols can implement Base Protocol callbacks." +msgstr "" + +#: ../../library/asyncio-protocol.rst:491 +msgid "Connection Callbacks" +msgstr "" + +#: ../../library/asyncio-protocol.rst:492 +msgid "" +"Connection callbacks are called on all protocols, exactly once per a " +"successful connection. All other protocol callbacks can only be called " +"between those two methods." +msgstr "" + +#: ../../library/asyncio-protocol.rst:498 +msgid "Called when a connection is made." +msgstr "" + +#: ../../library/asyncio-protocol.rst:500 +msgid "" +"The *transport* argument is the transport representing the connection. The " +"protocol is responsible for storing the reference to its transport." +msgstr "" + +#: ../../library/asyncio-protocol.rst:506 +msgid "Called when the connection is lost or closed." +msgstr "" + +#: ../../library/asyncio-protocol.rst:508 +msgid "" +"The argument is either an exception object or :const:`None`. The latter " +"means a regular EOF is received, or the connection was aborted or closed by " +"this side of the connection." +msgstr "" + +#: ../../library/asyncio-protocol.rst:514 +msgid "Flow Control Callbacks" +msgstr "" + +#: ../../library/asyncio-protocol.rst:515 +msgid "" +"Flow control callbacks can be called by transports to pause or resume " +"writing performed by the protocol." +msgstr "" + +#: ../../library/asyncio-protocol.rst:518 +msgid "" +"See the documentation of the :meth:`~WriteTransport.set_write_buffer_limits` " +"method for more details." +msgstr "" + +#: ../../library/asyncio-protocol.rst:523 +msgid "Called when the transport's buffer goes over the high watermark." +msgstr "" + +#: ../../library/asyncio-protocol.rst:527 +msgid "Called when the transport's buffer drains below the low watermark." +msgstr "" + +#: ../../library/asyncio-protocol.rst:529 +msgid "" +"If the buffer size equals the high watermark, :meth:`~BaseProtocol." +"pause_writing` is not called: the buffer size must go strictly over." +msgstr "" + +#: ../../library/asyncio-protocol.rst:533 +msgid "" +"Conversely, :meth:`~BaseProtocol.resume_writing` is called when the buffer " +"size is equal or lower than the low watermark. These end conditions are " +"important to ensure that things go as expected when either mark is zero." +msgstr "" + +#: ../../library/asyncio-protocol.rst:540 +msgid "Streaming Protocols" +msgstr "" + +#: ../../library/asyncio-protocol.rst:542 +msgid "" +"Event methods, such as :meth:`loop.create_server`, :meth:`loop." +"create_unix_server`, :meth:`loop.create_connection`, :meth:`loop." +"create_unix_connection`, :meth:`loop.connect_accepted_socket`, :meth:`loop." +"connect_read_pipe`, and :meth:`loop.connect_write_pipe` accept factories " +"that return streaming protocols." +msgstr "" + +#: ../../library/asyncio-protocol.rst:550 +msgid "" +"Called when some data is received. *data* is a non-empty bytes object " +"containing the incoming data." +msgstr "" + +#: ../../library/asyncio-protocol.rst:553 +msgid "" +"Whether the data is buffered, chunked or reassembled depends on the " +"transport. In general, you shouldn't rely on specific semantics and instead " +"make your parsing generic and flexible. However, data is always received in " +"the correct order." +msgstr "" + +#: ../../library/asyncio-protocol.rst:558 +msgid "" +"The method can be called an arbitrary number of times while a connection is " +"open." +msgstr "" + +#: ../../library/asyncio-protocol.rst:561 +msgid "" +"However, :meth:`protocol.eof_received() ` is called " +"at most once. Once ``eof_received()`` is called, ``data_received()`` is not " +"called anymore." +msgstr "" + +#: ../../library/asyncio-protocol.rst:567 +msgid "" +"Called when the other end signals it won't send any more data (for example " +"by calling :meth:`transport.write_eof() `, if the " +"other end also uses asyncio)." +msgstr "" + +#: ../../library/asyncio-protocol.rst:572 +msgid "" +"This method may return a false value (including ``None``), in which case the " +"transport will close itself. Conversely, if this method returns a true " +"value, the protocol used determines whether to close the transport. Since " +"the default implementation returns ``None``, it implicitly closes the " +"connection." +msgstr "" + +#: ../../library/asyncio-protocol.rst:578 +msgid "" +"Some transports, including SSL, don't support half-closed connections, in " +"which case returning true from this method will result in the connection " +"being closed." +msgstr "" + +#: ../../library/asyncio-protocol.rst:583 +#: ../../library/asyncio-protocol.rst:641 +msgid "State machine:" +msgstr "" + +#: ../../library/asyncio-protocol.rst:585 +msgid "" +"start -> connection_made\n" +" [-> data_received]*\n" +" [-> eof_received]?\n" +"-> connection_lost -> end" +msgstr "" +"start -> connection_made\n" +" [-> data_received]*\n" +" [-> eof_received]?\n" +"-> connection_lost -> end" + +#: ../../library/asyncio-protocol.rst:594 +msgid "Buffered Streaming Protocols" +msgstr "" + +#: ../../library/asyncio-protocol.rst:598 +msgid "" +"Buffered Protocols can be used with any event loop method that supports " +"`Streaming Protocols`_." +msgstr "" + +#: ../../library/asyncio-protocol.rst:601 +msgid "" +"``BufferedProtocol`` implementations allow explicit manual allocation and " +"control of the receive buffer. Event loops can then use the buffer provided " +"by the protocol to avoid unnecessary data copies. This can result in " +"noticeable performance improvement for protocols that receive big amounts of " +"data. Sophisticated protocol implementations can significantly reduce the " +"number of buffer allocations." +msgstr "" + +#: ../../library/asyncio-protocol.rst:608 +msgid "" +"The following callbacks are called on :class:`BufferedProtocol` instances:" +msgstr "" + +#: ../../library/asyncio-protocol.rst:613 +msgid "Called to allocate a new receive buffer." +msgstr "" + +#: ../../library/asyncio-protocol.rst:615 +msgid "" +"*sizehint* is the recommended minimum size for the returned buffer. It is " +"acceptable to return smaller or larger buffers than what *sizehint* " +"suggests. When set to -1, the buffer size can be arbitrary. It is an error " +"to return a buffer with a zero size." +msgstr "" + +#: ../../library/asyncio-protocol.rst:620 +msgid "" +"``get_buffer()`` must return an object implementing the :ref:`buffer " +"protocol `." +msgstr "" + +#: ../../library/asyncio-protocol.rst:625 +msgid "Called when the buffer was updated with the received data." +msgstr "" + +#: ../../library/asyncio-protocol.rst:627 +msgid "*nbytes* is the total number of bytes that were written to the buffer." +msgstr "" + +#: ../../library/asyncio-protocol.rst:631 +msgid "" +"See the documentation of the :meth:`protocol.eof_received() ` method." +msgstr "" + +#: ../../library/asyncio-protocol.rst:635 +msgid "" +":meth:`~BufferedProtocol.get_buffer` can be called an arbitrary number of " +"times during a connection. However, :meth:`protocol.eof_received() " +"` is called at most once and, if called, :meth:" +"`~BufferedProtocol.get_buffer` and :meth:`~BufferedProtocol.buffer_updated` " +"won't be called after it." +msgstr "" + +#: ../../library/asyncio-protocol.rst:643 +msgid "" +"start -> connection_made\n" +" [-> get_buffer\n" +" [-> buffer_updated]?\n" +" ]*\n" +" [-> eof_received]?\n" +"-> connection_lost -> end" +msgstr "" +"start -> connection_made\n" +" [-> get_buffer\n" +" [-> buffer_updated]?\n" +" ]*\n" +" [-> eof_received]?\n" +"-> connection_lost -> end" + +#: ../../library/asyncio-protocol.rst:654 +msgid "Datagram Protocols" +msgstr "" + +#: ../../library/asyncio-protocol.rst:656 +msgid "" +"Datagram Protocol instances should be constructed by protocol factories " +"passed to the :meth:`loop.create_datagram_endpoint` method." +msgstr "" + +#: ../../library/asyncio-protocol.rst:661 +msgid "" +"Called when a datagram is received. *data* is a bytes object containing the " +"incoming data. *addr* is the address of the peer sending the data; the " +"exact format depends on the transport." +msgstr "" + +#: ../../library/asyncio-protocol.rst:667 +msgid "" +"Called when a previous send or receive operation raises an :class:" +"`OSError`. *exc* is the :class:`OSError` instance." +msgstr "" + +#: ../../library/asyncio-protocol.rst:670 +msgid "" +"This method is called in rare conditions, when the transport (e.g. UDP) " +"detects that a datagram could not be delivered to its recipient. In many " +"conditions though, undeliverable datagrams will be silently dropped." +msgstr "" + +#: ../../library/asyncio-protocol.rst:677 +msgid "" +"On BSD systems (macOS, FreeBSD, etc.) flow control is not supported for " +"datagram protocols, because there is no reliable way to detect send failures " +"caused by writing too many packets." +msgstr "" + +#: ../../library/asyncio-protocol.rst:681 +msgid "" +"The socket always appears 'ready' and excess packets are dropped. An :class:" +"`OSError` with ``errno`` set to :const:`errno.ENOBUFS` may or may not be " +"raised; if it is raised, it will be reported to :meth:`DatagramProtocol." +"error_received` but otherwise ignored." +msgstr "" + +#: ../../library/asyncio-protocol.rst:690 +msgid "Subprocess Protocols" +msgstr "" + +#: ../../library/asyncio-protocol.rst:692 +msgid "" +"Subprocess Protocol instances should be constructed by protocol factories " +"passed to the :meth:`loop.subprocess_exec` and :meth:`loop.subprocess_shell` " +"methods." +msgstr "" + +#: ../../library/asyncio-protocol.rst:698 +msgid "" +"Called when the child process writes data into its stdout or stderr pipe." +msgstr "" + +#: ../../library/asyncio-protocol.rst:701 +msgid "*fd* is the integer file descriptor of the pipe." +msgstr "" + +#: ../../library/asyncio-protocol.rst:703 +msgid "*data* is a non-empty bytes object containing the received data." +msgstr "" + +#: ../../library/asyncio-protocol.rst:707 +msgid "" +"Called when one of the pipes communicating with the child process is closed." +msgstr "" + +#: ../../library/asyncio-protocol.rst:710 +msgid "*fd* is the integer file descriptor that was closed." +msgstr "" + +#: ../../library/asyncio-protocol.rst:714 +msgid "Called when the child process has exited." +msgstr "" + +#: ../../library/asyncio-protocol.rst:716 +msgid "" +"It can be called before :meth:`~SubprocessProtocol.pipe_data_received` and :" +"meth:`~SubprocessProtocol.pipe_connection_lost` methods." +msgstr "" + +#: ../../library/asyncio-protocol.rst:721 +msgid "Examples" +msgstr "範例" + +#: ../../library/asyncio-protocol.rst:726 +msgid "TCP Echo Server" +msgstr "" + +#: ../../library/asyncio-protocol.rst:728 +msgid "" +"Create a TCP echo server using the :meth:`loop.create_server` method, send " +"back received data, and close the connection::" +msgstr "" + +#: ../../library/asyncio-protocol.rst:731 +msgid "" +"import asyncio\n" +"\n" +"\n" +"class EchoServerProtocol(asyncio.Protocol):\n" +" def connection_made(self, transport):\n" +" peername = transport.get_extra_info('peername')\n" +" print('Connection from {}'.format(peername))\n" +" self.transport = transport\n" +"\n" +" def data_received(self, data):\n" +" message = data.decode()\n" +" print('Data received: {!r}'.format(message))\n" +"\n" +" print('Send: {!r}'.format(message))\n" +" self.transport.write(data)\n" +"\n" +" print('Close the client socket')\n" +" self.transport.close()\n" +"\n" +"\n" +"async def main():\n" +" # Get a reference to the event loop as we plan to use\n" +" # low-level APIs.\n" +" loop = asyncio.get_running_loop()\n" +"\n" +" server = await loop.create_server(\n" +" EchoServerProtocol,\n" +" '127.0.0.1', 8888)\n" +"\n" +" async with server:\n" +" await server.serve_forever()\n" +"\n" +"\n" +"asyncio.run(main())" +msgstr "" + +#: ../../library/asyncio-protocol.rst:769 +msgid "" +"The :ref:`TCP echo server using streams ` " +"example uses the high-level :func:`asyncio.start_server` function." +msgstr "" + +#: ../../library/asyncio-protocol.rst:775 +msgid "TCP Echo Client" +msgstr "" + +#: ../../library/asyncio-protocol.rst:777 +msgid "" +"A TCP echo client using the :meth:`loop.create_connection` method, sends " +"data, and waits until the connection is closed::" +msgstr "" + +#: ../../library/asyncio-protocol.rst:780 +msgid "" +"import asyncio\n" +"\n" +"\n" +"class EchoClientProtocol(asyncio.Protocol):\n" +" def __init__(self, message, on_con_lost):\n" +" self.message = message\n" +" self.on_con_lost = on_con_lost\n" +"\n" +" def connection_made(self, transport):\n" +" transport.write(self.message.encode())\n" +" print('Data sent: {!r}'.format(self.message))\n" +"\n" +" def data_received(self, data):\n" +" print('Data received: {!r}'.format(data.decode()))\n" +"\n" +" def connection_lost(self, exc):\n" +" print('The server closed the connection')\n" +" self.on_con_lost.set_result(True)\n" +"\n" +"\n" +"async def main():\n" +" # Get a reference to the event loop as we plan to use\n" +" # low-level APIs.\n" +" loop = asyncio.get_running_loop()\n" +"\n" +" on_con_lost = loop.create_future()\n" +" message = 'Hello World!'\n" +"\n" +" transport, protocol = await loop.create_connection(\n" +" lambda: EchoClientProtocol(message, on_con_lost),\n" +" '127.0.0.1', 8888)\n" +"\n" +" # Wait until the protocol signals that the connection\n" +" # is lost and close the transport.\n" +" try:\n" +" await on_con_lost\n" +" finally:\n" +" transport.close()\n" +"\n" +"\n" +"asyncio.run(main())" +msgstr "" + +#: ../../library/asyncio-protocol.rst:825 +msgid "" +"The :ref:`TCP echo client using streams ` " +"example uses the high-level :func:`asyncio.open_connection` function." +msgstr "" + +#: ../../library/asyncio-protocol.rst:832 +msgid "UDP Echo Server" +msgstr "" + +#: ../../library/asyncio-protocol.rst:834 +msgid "" +"A UDP echo server, using the :meth:`loop.create_datagram_endpoint` method, " +"sends back received data::" +msgstr "" + +#: ../../library/asyncio-protocol.rst:837 +msgid "" +"import asyncio\n" +"\n" +"\n" +"class EchoServerProtocol:\n" +" def connection_made(self, transport):\n" +" self.transport = transport\n" +"\n" +" def datagram_received(self, data, addr):\n" +" message = data.decode()\n" +" print('Received %r from %s' % (message, addr))\n" +" print('Send %r to %s' % (message, addr))\n" +" self.transport.sendto(data, addr)\n" +"\n" +"\n" +"async def main():\n" +" print(\"Starting UDP server\")\n" +"\n" +" # Get a reference to the event loop as we plan to use\n" +" # low-level APIs.\n" +" loop = asyncio.get_running_loop()\n" +"\n" +" # One protocol instance will be created to serve all\n" +" # client requests.\n" +" transport, protocol = await loop.create_datagram_endpoint(\n" +" EchoServerProtocol,\n" +" local_addr=('127.0.0.1', 9999))\n" +"\n" +" try:\n" +" await asyncio.sleep(3600) # Serve for 1 hour.\n" +" finally:\n" +" transport.close()\n" +"\n" +"\n" +"asyncio.run(main())" +msgstr "" + +#: ../../library/asyncio-protocol.rst:876 +msgid "UDP Echo Client" +msgstr "" + +#: ../../library/asyncio-protocol.rst:878 +msgid "" +"A UDP echo client, using the :meth:`loop.create_datagram_endpoint` method, " +"sends data and closes the transport when it receives the answer::" +msgstr "" + +#: ../../library/asyncio-protocol.rst:881 +msgid "" +"import asyncio\n" +"\n" +"\n" +"class EchoClientProtocol:\n" +" def __init__(self, message, on_con_lost):\n" +" self.message = message\n" +" self.on_con_lost = on_con_lost\n" +" self.transport = None\n" +"\n" +" def connection_made(self, transport):\n" +" self.transport = transport\n" +" print('Send:', self.message)\n" +" self.transport.sendto(self.message.encode())\n" +"\n" +" def datagram_received(self, data, addr):\n" +" print(\"Received:\", data.decode())\n" +"\n" +" print(\"Close the socket\")\n" +" self.transport.close()\n" +"\n" +" def error_received(self, exc):\n" +" print('Error received:', exc)\n" +"\n" +" def connection_lost(self, exc):\n" +" print(\"Connection closed\")\n" +" self.on_con_lost.set_result(True)\n" +"\n" +"\n" +"async def main():\n" +" # Get a reference to the event loop as we plan to use\n" +" # low-level APIs.\n" +" loop = asyncio.get_running_loop()\n" +"\n" +" on_con_lost = loop.create_future()\n" +" message = \"Hello World!\"\n" +"\n" +" transport, protocol = await loop.create_datagram_endpoint(\n" +" lambda: EchoClientProtocol(message, on_con_lost),\n" +" remote_addr=('127.0.0.1', 9999))\n" +"\n" +" try:\n" +" await on_con_lost\n" +" finally:\n" +" transport.close()\n" +"\n" +"\n" +"asyncio.run(main())" +msgstr "" + +#: ../../library/asyncio-protocol.rst:933 +msgid "Connecting Existing Sockets" +msgstr "" + +#: ../../library/asyncio-protocol.rst:935 +msgid "" +"Wait until a socket receives data using the :meth:`loop.create_connection` " +"method with a protocol::" +msgstr "" + +#: ../../library/asyncio-protocol.rst:938 +msgid "" +"import asyncio\n" +"import socket\n" +"\n" +"\n" +"class MyProtocol(asyncio.Protocol):\n" +"\n" +" def __init__(self, on_con_lost):\n" +" self.transport = None\n" +" self.on_con_lost = on_con_lost\n" +"\n" +" def connection_made(self, transport):\n" +" self.transport = transport\n" +"\n" +" def data_received(self, data):\n" +" print(\"Received:\", data.decode())\n" +"\n" +" # We are done: close the transport;\n" +" # connection_lost() will be called automatically.\n" +" self.transport.close()\n" +"\n" +" def connection_lost(self, exc):\n" +" # The socket has been closed\n" +" self.on_con_lost.set_result(True)\n" +"\n" +"\n" +"async def main():\n" +" # Get a reference to the event loop as we plan to use\n" +" # low-level APIs.\n" +" loop = asyncio.get_running_loop()\n" +" on_con_lost = loop.create_future()\n" +"\n" +" # Create a pair of connected sockets\n" +" rsock, wsock = socket.socketpair()\n" +"\n" +" # Register the socket to wait for data.\n" +" transport, protocol = await loop.create_connection(\n" +" lambda: MyProtocol(on_con_lost), sock=rsock)\n" +"\n" +" # Simulate the reception of data from the network.\n" +" loop.call_soon(wsock.send, 'abc'.encode())\n" +"\n" +" try:\n" +" await protocol.on_con_lost\n" +" finally:\n" +" transport.close()\n" +" wsock.close()\n" +"\n" +"asyncio.run(main())" +msgstr "" + +#: ../../library/asyncio-protocol.rst:989 +msgid "" +"The :ref:`watch a file descriptor for read events " +"` example uses the low-level :meth:`loop." +"add_reader` method to register an FD." +msgstr "" + +#: ../../library/asyncio-protocol.rst:993 +msgid "" +"The :ref:`register an open socket to wait for data using streams " +"` example uses high-level streams " +"created by the :func:`open_connection` function in a coroutine." +msgstr "" + +#: ../../library/asyncio-protocol.rst:1000 +msgid "loop.subprocess_exec() and SubprocessProtocol" +msgstr "" + +#: ../../library/asyncio-protocol.rst:1002 +msgid "" +"An example of a subprocess protocol used to get the output of a subprocess " +"and to wait for the subprocess exit." +msgstr "" + +#: ../../library/asyncio-protocol.rst:1005 +msgid "The subprocess is created by the :meth:`loop.subprocess_exec` method::" +msgstr "" + +#: ../../library/asyncio-protocol.rst:1007 +msgid "" +"import asyncio\n" +"import sys\n" +"\n" +"class DateProtocol(asyncio.SubprocessProtocol):\n" +" def __init__(self, exit_future):\n" +" self.exit_future = exit_future\n" +" self.output = bytearray()\n" +" self.pipe_closed = False\n" +" self.exited = False\n" +"\n" +" def pipe_connection_lost(self, fd, exc):\n" +" self.pipe_closed = True\n" +" self.check_for_exit()\n" +"\n" +" def pipe_data_received(self, fd, data):\n" +" self.output.extend(data)\n" +"\n" +" def process_exited(self):\n" +" self.exited = True\n" +" # process_exited() method can be called before\n" +" # pipe_connection_lost() method: wait until both methods are\n" +" # called.\n" +" self.check_for_exit()\n" +"\n" +" def check_for_exit(self):\n" +" if self.pipe_closed and self.exited:\n" +" self.exit_future.set_result(True)\n" +"\n" +"async def get_date():\n" +" # Get a reference to the event loop as we plan to use\n" +" # low-level APIs.\n" +" loop = asyncio.get_running_loop()\n" +"\n" +" code = 'import datetime; print(datetime.datetime.now())'\n" +" exit_future = asyncio.Future(loop=loop)\n" +"\n" +" # Create the subprocess controlled by DateProtocol;\n" +" # redirect the standard output into a pipe.\n" +" transport, protocol = await loop.subprocess_exec(\n" +" lambda: DateProtocol(exit_future),\n" +" sys.executable, '-c', code,\n" +" stdin=None, stderr=None)\n" +"\n" +" # Wait for the subprocess exit using the process_exited()\n" +" # method of the protocol.\n" +" await exit_future\n" +"\n" +" # Close the stdout pipe.\n" +" transport.close()\n" +"\n" +" # Read the output which was collected by the\n" +" # pipe_data_received() method of the protocol.\n" +" data = bytes(protocol.output)\n" +" return data.decode('ascii').rstrip()\n" +"\n" +"date = asyncio.run(get_date())\n" +"print(f\"Current date: {date}\")" +msgstr "" + +#: ../../library/asyncio-protocol.rst:1065 +msgid "" +"See also the :ref:`same example ` " +"written using high-level APIs." +msgstr "" diff --git a/library/asyncio-queue.po b/library/asyncio-queue.po index 78ed067bdb..6c067b1313 100644 --- a/library/asyncio-queue.po +++ b/library/asyncio-queue.po @@ -1,350 +1,350 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Adrian Liaw , 2018 -# Matt Wang , 2022 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-12-17 17:02+0000\n" -"PO-Revision-Date: 2022-02-20 18:34+0800\n" -"Last-Translator: Matt Wang \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" -"X-Generator: Poedit 3.0.1\n" - -#: ../../library/asyncio-queue.rst:7 -msgid "Queues" -msgstr "佇列 (Queues)" - -#: ../../library/asyncio-queue.rst:9 -msgid "**Source code:** :source:`Lib/asyncio/queues.py`" -msgstr "**原始碼：**\\ :source:`Lib/asyncio/queues.py`" - -#: ../../library/asyncio-queue.rst:13 -msgid "" -"asyncio queues are designed to be similar to classes of the :mod:`queue` " -"module. Although asyncio queues are not thread-safe, they are designed to " -"be used specifically in async/await code." -msgstr "" -"asyncio 佇列被設計成與 :mod:`queue` 模組類似。儘管 asyncio 佇列不支援執行緒安" -"全 (thread-safe)，但他們是被設計來專用於 async/await 程式。" - -#: ../../library/asyncio-queue.rst:17 -msgid "" -"Note that methods of asyncio queues don't have a *timeout* parameter; use :" -"func:`asyncio.wait_for` function to do queue operations with a timeout." -msgstr "" -"注意 asyncio 的佇列沒有 *timeout* 參數；請使用 :func:`asyncio.wait_for` 函式" -"來為佇列新增具有超時 (timeout) 設定的操作。" - -#: ../../library/asyncio-queue.rst:21 -msgid "See also the `Examples`_ section below." -msgstr "另請參閱下方 `Examples`_。" - -#: ../../library/asyncio-queue.rst:24 -msgid "Queue" -msgstr "Queue" - -#: ../../library/asyncio-queue.rst:28 -msgid "A first in, first out (FIFO) queue." -msgstr "先進先出 (FIFO) 佇列。" - -#: ../../library/asyncio-queue.rst:30 -msgid "" -"If *maxsize* is less than or equal to zero, the queue size is infinite. If " -"it is an integer greater than ``0``, then ``await put()`` blocks when the " -"queue reaches *maxsize* until an item is removed by :meth:`get`." -msgstr "" -"如果 *maxsize* 小於或等於零，則佇列大小是無限制的。如果是大於 ``0`` 的整數，" -"則當佇列達到 *maxsize* 時，``await put()`` 將會阻塞 (block)，直到某個元素被 :" -"meth:`get` 取出。" - -#: ../../library/asyncio-queue.rst:35 -msgid "" -"Unlike the standard library threading :mod:`queue`, the size of the queue is " -"always known and can be returned by calling the :meth:`qsize` method." -msgstr "" -"不像標準函式庫中執行緒類型的 :mod:`queue`，佇列的大小一直是已知的，可以透過呼" -"叫 :meth:`qsize` 方法回傳。" - -#: ../../library/asyncio-queue.rst:39 -msgid "Removed the *loop* parameter." -msgstr "移除 *loop* 參數。" - -#: ../../library/asyncio-queue.rst:43 -msgid "This class is :ref:`not thread safe `." -msgstr "這個類別是\\ :ref:`不支援執行緒安全的 `。" - -#: ../../library/asyncio-queue.rst:47 -msgid "Number of items allowed in the queue." -msgstr "佇列中可存放的元素數量。" - -#: ../../library/asyncio-queue.rst:51 -msgid "Return ``True`` if the queue is empty, ``False`` otherwise." -msgstr "如果佇列為空則回傳 ``True``，否則回傳 ``False``。" - -#: ../../library/asyncio-queue.rst:55 -msgid "Return ``True`` if there are :attr:`maxsize` items in the queue." -msgstr "如果有 :attr:`maxsize` 個條目在佇列中，則回傳 ``True``。" - -#: ../../library/asyncio-queue.rst:57 -msgid "" -"If the queue was initialized with ``maxsize=0`` (the default), then :meth:" -"`full` never returns ``True``." -msgstr "" -"如果佇列用 ``maxsize=0`` （預設）初始化，則 :meth:`full` 永遠不會回傳 " -"``True``。" - -#: ../../library/asyncio-queue.rst:63 -msgid "" -"Remove and return an item from the queue. If queue is empty, wait until an " -"item is available." -msgstr "從佇列中刪除並回傳一個元素。如果佇列為空，則持續等待直到佇列中有元素。" - -#: ../../library/asyncio-queue.rst:66 -msgid "" -"Raises :exc:`QueueShutDown` if the queue has been shut down and is empty, or " -"if the queue has been shut down immediately." -msgstr "" - -#: ../../library/asyncio-queue.rst:71 -msgid "" -"Return an item if one is immediately available, else raise :exc:`QueueEmpty`." -msgstr "如果佇列內有值則立即回傳佇列中的元素，否則引發 :exc:`QueueEmpty`。" - -#: ../../library/asyncio-queue.rst:77 -msgid "Block until all items in the queue have been received and processed." -msgstr "持續阻塞直到佇列中所有的元素都被接收和處理完畢。" - -#: ../../library/asyncio-queue.rst:79 -msgid "" -"The count of unfinished tasks goes up whenever an item is added to the " -"queue. The count goes down whenever a consumer coroutine calls :meth:" -"`task_done` to indicate that the item was retrieved and all work on it is " -"complete. When the count of unfinished tasks drops to zero, :meth:`join` " -"unblocks." -msgstr "" -"當條目新增到佇列的時候，未完成任務的計數就會增加。每當一個消耗者 (consumer) " -"協程呼叫 :meth:`task_done`，表示這個條目已經被取回且被它包含的所有工作都已完" -"成，未完成任務計數就會減少。當未完成計數降到零的時候，:meth:`join` 阻塞會被解" -"除 (unblock)。" - -#: ../../library/asyncio-queue.rst:88 -msgid "" -"Put an item into the queue. If the queue is full, wait until a free slot is " -"available before adding the item." -msgstr "" -"將一個元素放進佇列。如果佇列滿了，在新增元素之前，會持續等待直到有空閒插槽 " -"(free slot) 能被使用。" - -#: ../../library/asyncio-queue.rst:91 -msgid "Raises :exc:`QueueShutDown` if the queue has been shut down." -msgstr "如果佇列已經被關閉，則引發 :exc:`QueueShutDown`。" - -#: ../../library/asyncio-queue.rst:95 -msgid "Put an item into the queue without blocking." -msgstr "不阻塞地將一個元素放入佇列。" - -#: ../../library/asyncio-queue.rst:97 -msgid "If no free slot is immediately available, raise :exc:`QueueFull`." -msgstr "如果沒有立即可用的空閒插槽，引發 :exc:`QueueFull`。" - -#: ../../library/asyncio-queue.rst:101 -msgid "Return the number of items in the queue." -msgstr "回傳佇列中的元素數量。" - -#: ../../library/asyncio-queue.rst:105 -msgid "Put a :class:`Queue` instance into a shutdown mode." -msgstr "" - -#: ../../library/asyncio-queue.rst:107 -msgid "" -"The queue can no longer grow. Future calls to :meth:`~Queue.put` raise :exc:" -"`QueueShutDown`. Currently blocked callers of :meth:`~Queue.put` will be " -"unblocked and will raise :exc:`QueueShutDown` in the formerly awaiting task." -msgstr "" - -#: ../../library/asyncio-queue.rst:112 -msgid "" -"If *immediate* is false (the default), the queue can be wound down normally " -"with :meth:`~Queue.get` calls to extract tasks that have already been loaded." -msgstr "" - -#: ../../library/asyncio-queue.rst:116 -msgid "" -"And if :meth:`~Queue.task_done` is called for each remaining task, a " -"pending :meth:`~Queue.join` will be unblocked normally." -msgstr "" - -#: ../../library/asyncio-queue.rst:119 -msgid "" -"Once the queue is empty, future calls to :meth:`~Queue.get` will raise :exc:" -"`QueueShutDown`." -msgstr "" - -#: ../../library/asyncio-queue.rst:122 -msgid "" -"If *immediate* is true, the queue is terminated immediately. The queue is " -"drained to be completely empty and the count of unfinished tasks is reduced " -"by the number of tasks drained. If unfinished tasks is zero, callers of :" -"meth:`~Queue.join` are unblocked. Also, blocked callers of :meth:`~Queue." -"get` are unblocked and will raise :exc:`QueueShutDown` because the queue is " -"empty." -msgstr "" - -#: ../../library/asyncio-queue.rst:130 -msgid "" -"Use caution when using :meth:`~Queue.join` with *immediate* set to true. " -"This unblocks the join even when no work has been done on the tasks, " -"violating the usual invariant for joining a queue." -msgstr "" - -#: ../../library/asyncio-queue.rst:138 -msgid "Indicate that a formerly enqueued work item is complete." -msgstr "表示前面一個排隊的工作項目已經完成。" - -#: ../../library/asyncio-queue.rst:140 -msgid "" -"Used by queue consumers. For each :meth:`~Queue.get` used to fetch a work " -"item, a subsequent call to :meth:`task_done` tells the queue that the " -"processing on the work item is complete." -msgstr "" -"由佇列消耗者使用。對於每個用於取得一個工作項目的 :meth:`~Queue.get`，接續的 :" -"meth:`task_done` 呼叫會告訴佇列這個工作項目的處理已經完成。" - -#: ../../library/asyncio-queue.rst:144 -msgid "" -"If a :meth:`join` is currently blocking, it will resume when all items have " -"been processed (meaning that a :meth:`task_done` call was received for every " -"item that had been :meth:`~Queue.put` into the queue)." -msgstr "" -"如果 :meth:`join` 目前正在阻塞，在所有項目都被處理後會解除阻塞（意味著每個" -"以 :meth:`~Queue.put` 放進佇列的條目都會收到一個 :meth:`task_done`）。" - -#: ../../library/asyncio-queue.rst:149 -msgid "" -"Raises :exc:`ValueError` if called more times than there were items placed " -"in the queue." -msgstr "如果被呼叫的次數多於放入佇列中的項目數量，將引發 :exc:`ValueError`。" - -#: ../../library/asyncio-queue.rst:154 -msgid "Priority Queue" -msgstr "Priority Queue（優先佇列）" - -#: ../../library/asyncio-queue.rst:158 -msgid "" -"A variant of :class:`Queue`; retrieves entries in priority order (lowest " -"first)." -msgstr ":class:`Queue` 的變形；按優先順序取出條目 (最小的先取出)。" - -#: ../../library/asyncio-queue.rst:161 -msgid "Entries are typically tuples of the form ``(priority_number, data)``." -msgstr "條目通常是 ``(priority_number, data)`` 形式的 tuple（元組）。" - -#: ../../library/asyncio-queue.rst:166 -msgid "LIFO Queue" -msgstr "LIFO Queue" - -#: ../../library/asyncio-queue.rst:170 -msgid "" -"A variant of :class:`Queue` that retrieves most recently added entries first " -"(last in, first out)." -msgstr ":class:`Queue` 的變形，先取出最近新增的條目（後進先出）。" - -#: ../../library/asyncio-queue.rst:175 -msgid "Exceptions" -msgstr "例外" - -#: ../../library/asyncio-queue.rst:179 -msgid "" -"This exception is raised when the :meth:`~Queue.get_nowait` method is called " -"on an empty queue." -msgstr "當佇列為空的時候，呼叫 :meth:`~Queue.get_nowait` 方法會引發這個例外。" - -#: ../../library/asyncio-queue.rst:185 -msgid "" -"Exception raised when the :meth:`~Queue.put_nowait` method is called on a " -"queue that has reached its *maxsize*." -msgstr "" -"當佇列中條目數量已經達到它的 *maxsize* 時，呼叫 :meth:`~Queue.put_nowait` 方" -"法會引發這個例外。" - -#: ../../library/asyncio-queue.rst:191 -msgid "" -"Exception raised when :meth:`~Queue.put` or :meth:`~Queue.get` is called on " -"a queue which has been shut down." -msgstr "" - -#: ../../library/asyncio-queue.rst:198 -msgid "Examples" -msgstr "範例" - -#: ../../library/asyncio-queue.rst:202 -msgid "" -"Queues can be used to distribute workload between several concurrent tasks::" -msgstr "佇列能被用於多個並行任務的工作分配：" - -#: ../../library/asyncio-queue.rst:205 -msgid "" -"import asyncio\n" -"import random\n" -"import time\n" -"\n" -"\n" -"async def worker(name, queue):\n" -" while True:\n" -" # Get a \"work item\" out of the queue.\n" -" sleep_for = await queue.get()\n" -"\n" -" # Sleep for the \"sleep_for\" seconds.\n" -" await asyncio.sleep(sleep_for)\n" -"\n" -" # Notify the queue that the \"work item\" has been processed.\n" -" queue.task_done()\n" -"\n" -" print(f'{name} has slept for {sleep_for:.2f} seconds')\n" -"\n" -"\n" -"async def main():\n" -" # Create a queue that we will use to store our \"workload\".\n" -" queue = asyncio.Queue()\n" -"\n" -" # Generate random timings and put them into the queue.\n" -" total_sleep_time = 0\n" -" for _ in range(20):\n" -" sleep_for = random.uniform(0.05, 1.0)\n" -" total_sleep_time += sleep_for\n" -" queue.put_nowait(sleep_for)\n" -"\n" -" # Create three worker tasks to process the queue concurrently.\n" -" tasks = []\n" -" for i in range(3):\n" -" task = asyncio.create_task(worker(f'worker-{i}', queue))\n" -" tasks.append(task)\n" -"\n" -" # Wait until the queue is fully processed.\n" -" started_at = time.monotonic()\n" -" await queue.join()\n" -" total_slept_for = time.monotonic() - started_at\n" -"\n" -" # Cancel our worker tasks.\n" -" for task in tasks:\n" -" task.cancel()\n" -" # Wait until all worker tasks are cancelled.\n" -" await asyncio.gather(*tasks, return_exceptions=True)\n" -"\n" -" print('====')\n" -" print(f'3 workers slept in parallel for {total_slept_for:.2f} seconds')\n" -" print(f'total expected sleep time: {total_sleep_time:.2f} seconds')\n" -"\n" -"\n" -"asyncio.run(main())" -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Adrian Liaw , 2018 +# Matt Wang , 2022 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-12-17 17:02+0000\n" +"PO-Revision-Date: 2022-02-20 18:34+0800\n" +"Last-Translator: Matt Wang \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" +"X-Generator: Poedit 3.0.1\n" + +#: ../../library/asyncio-queue.rst:7 +msgid "Queues" +msgstr "佇列 (Queues)" + +#: ../../library/asyncio-queue.rst:9 +msgid "**Source code:** :source:`Lib/asyncio/queues.py`" +msgstr "**原始碼：**\\ :source:`Lib/asyncio/queues.py`" + +#: ../../library/asyncio-queue.rst:13 +msgid "" +"asyncio queues are designed to be similar to classes of the :mod:`queue` " +"module. Although asyncio queues are not thread-safe, they are designed to " +"be used specifically in async/await code." +msgstr "" +"asyncio 佇列被設計成與 :mod:`queue` 模組類似。儘管 asyncio 佇列不支援執行緒安" +"全 (thread-safe)，但他們是被設計來專用於 async/await 程式。" + +#: ../../library/asyncio-queue.rst:17 +msgid "" +"Note that methods of asyncio queues don't have a *timeout* parameter; use :" +"func:`asyncio.wait_for` function to do queue operations with a timeout." +msgstr "" +"注意 asyncio 的佇列沒有 *timeout* 參數；請使用 :func:`asyncio.wait_for` 函式" +"來為佇列新增具有超時 (timeout) 設定的操作。" + +#: ../../library/asyncio-queue.rst:21 +msgid "See also the `Examples`_ section below." +msgstr "另請參閱下方 `Examples`_。" + +#: ../../library/asyncio-queue.rst:24 +msgid "Queue" +msgstr "Queue" + +#: ../../library/asyncio-queue.rst:28 +msgid "A first in, first out (FIFO) queue." +msgstr "先進先出 (FIFO) 佇列。" + +#: ../../library/asyncio-queue.rst:30 +msgid "" +"If *maxsize* is less than or equal to zero, the queue size is infinite. If " +"it is an integer greater than ``0``, then ``await put()`` blocks when the " +"queue reaches *maxsize* until an item is removed by :meth:`get`." +msgstr "" +"如果 *maxsize* 小於或等於零，則佇列大小是無限制的。如果是大於 ``0`` 的整數，" +"則當佇列達到 *maxsize* 時，``await put()`` 將會阻塞 (block)，直到某個元素被 :" +"meth:`get` 取出。" + +#: ../../library/asyncio-queue.rst:35 +msgid "" +"Unlike the standard library threading :mod:`queue`, the size of the queue is " +"always known and can be returned by calling the :meth:`qsize` method." +msgstr "" +"不像標準函式庫中執行緒類型的 :mod:`queue`，佇列的大小一直是已知的，可以透過呼" +"叫 :meth:`qsize` 方法回傳。" + +#: ../../library/asyncio-queue.rst:39 +msgid "Removed the *loop* parameter." +msgstr "移除 *loop* 參數。" + +#: ../../library/asyncio-queue.rst:43 +msgid "This class is :ref:`not thread safe `." +msgstr "這個類別是\\ :ref:`不支援執行緒安全的 `。" + +#: ../../library/asyncio-queue.rst:47 +msgid "Number of items allowed in the queue." +msgstr "佇列中可存放的元素數量。" + +#: ../../library/asyncio-queue.rst:51 +msgid "Return ``True`` if the queue is empty, ``False`` otherwise." +msgstr "如果佇列為空則回傳 ``True``，否則回傳 ``False``。" + +#: ../../library/asyncio-queue.rst:55 +msgid "Return ``True`` if there are :attr:`maxsize` items in the queue." +msgstr "如果有 :attr:`maxsize` 個條目在佇列中，則回傳 ``True``。" + +#: ../../library/asyncio-queue.rst:57 +msgid "" +"If the queue was initialized with ``maxsize=0`` (the default), then :meth:" +"`full` never returns ``True``." +msgstr "" +"如果佇列用 ``maxsize=0`` （預設）初始化，則 :meth:`full` 永遠不會回傳 " +"``True``。" + +#: ../../library/asyncio-queue.rst:63 +msgid "" +"Remove and return an item from the queue. If queue is empty, wait until an " +"item is available." +msgstr "從佇列中刪除並回傳一個元素。如果佇列為空，則持續等待直到佇列中有元素。" + +#: ../../library/asyncio-queue.rst:66 +msgid "" +"Raises :exc:`QueueShutDown` if the queue has been shut down and is empty, or " +"if the queue has been shut down immediately." +msgstr "" + +#: ../../library/asyncio-queue.rst:71 +msgid "" +"Return an item if one is immediately available, else raise :exc:`QueueEmpty`." +msgstr "如果佇列內有值則立即回傳佇列中的元素，否則引發 :exc:`QueueEmpty`。" + +#: ../../library/asyncio-queue.rst:77 +msgid "Block until all items in the queue have been received and processed." +msgstr "持續阻塞直到佇列中所有的元素都被接收和處理完畢。" + +#: ../../library/asyncio-queue.rst:79 +msgid "" +"The count of unfinished tasks goes up whenever an item is added to the " +"queue. The count goes down whenever a consumer coroutine calls :meth:" +"`task_done` to indicate that the item was retrieved and all work on it is " +"complete. When the count of unfinished tasks drops to zero, :meth:`join` " +"unblocks." +msgstr "" +"當條目新增到佇列的時候，未完成任務的計數就會增加。每當一個消耗者 (consumer) " +"協程呼叫 :meth:`task_done`，表示這個條目已經被取回且被它包含的所有工作都已完" +"成，未完成任務計數就會減少。當未完成計數降到零的時候，:meth:`join` 阻塞會被解" +"除 (unblock)。" + +#: ../../library/asyncio-queue.rst:88 +msgid "" +"Put an item into the queue. If the queue is full, wait until a free slot is " +"available before adding the item." +msgstr "" +"將一個元素放進佇列。如果佇列滿了，在新增元素之前，會持續等待直到有空閒插槽 " +"(free slot) 能被使用。" + +#: ../../library/asyncio-queue.rst:91 +msgid "Raises :exc:`QueueShutDown` if the queue has been shut down." +msgstr "如果佇列已經被關閉，則引發 :exc:`QueueShutDown`。" + +#: ../../library/asyncio-queue.rst:95 +msgid "Put an item into the queue without blocking." +msgstr "不阻塞地將一個元素放入佇列。" + +#: ../../library/asyncio-queue.rst:97 +msgid "If no free slot is immediately available, raise :exc:`QueueFull`." +msgstr "如果沒有立即可用的空閒插槽，引發 :exc:`QueueFull`。" + +#: ../../library/asyncio-queue.rst:101 +msgid "Return the number of items in the queue." +msgstr "回傳佇列中的元素數量。" + +#: ../../library/asyncio-queue.rst:105 +msgid "Put a :class:`Queue` instance into a shutdown mode." +msgstr "" + +#: ../../library/asyncio-queue.rst:107 +msgid "" +"The queue can no longer grow. Future calls to :meth:`~Queue.put` raise :exc:" +"`QueueShutDown`. Currently blocked callers of :meth:`~Queue.put` will be " +"unblocked and will raise :exc:`QueueShutDown` in the formerly awaiting task." +msgstr "" + +#: ../../library/asyncio-queue.rst:112 +msgid "" +"If *immediate* is false (the default), the queue can be wound down normally " +"with :meth:`~Queue.get` calls to extract tasks that have already been loaded." +msgstr "" + +#: ../../library/asyncio-queue.rst:116 +msgid "" +"And if :meth:`~Queue.task_done` is called for each remaining task, a " +"pending :meth:`~Queue.join` will be unblocked normally." +msgstr "" + +#: ../../library/asyncio-queue.rst:119 +msgid "" +"Once the queue is empty, future calls to :meth:`~Queue.get` will raise :exc:" +"`QueueShutDown`." +msgstr "" + +#: ../../library/asyncio-queue.rst:122 +msgid "" +"If *immediate* is true, the queue is terminated immediately. The queue is " +"drained to be completely empty and the count of unfinished tasks is reduced " +"by the number of tasks drained. If unfinished tasks is zero, callers of :" +"meth:`~Queue.join` are unblocked. Also, blocked callers of :meth:`~Queue." +"get` are unblocked and will raise :exc:`QueueShutDown` because the queue is " +"empty." +msgstr "" + +#: ../../library/asyncio-queue.rst:130 +msgid "" +"Use caution when using :meth:`~Queue.join` with *immediate* set to true. " +"This unblocks the join even when no work has been done on the tasks, " +"violating the usual invariant for joining a queue." +msgstr "" + +#: ../../library/asyncio-queue.rst:138 +msgid "Indicate that a formerly enqueued work item is complete." +msgstr "表示前面一個排隊的工作項目已經完成。" + +#: ../../library/asyncio-queue.rst:140 +msgid "" +"Used by queue consumers. For each :meth:`~Queue.get` used to fetch a work " +"item, a subsequent call to :meth:`task_done` tells the queue that the " +"processing on the work item is complete." +msgstr "" +"由佇列消耗者使用。對於每個用於取得一個工作項目的 :meth:`~Queue.get`，接續的 :" +"meth:`task_done` 呼叫會告訴佇列這個工作項目的處理已經完成。" + +#: ../../library/asyncio-queue.rst:144 +msgid "" +"If a :meth:`join` is currently blocking, it will resume when all items have " +"been processed (meaning that a :meth:`task_done` call was received for every " +"item that had been :meth:`~Queue.put` into the queue)." +msgstr "" +"如果 :meth:`join` 目前正在阻塞，在所有項目都被處理後會解除阻塞（意味著每個" +"以 :meth:`~Queue.put` 放進佇列的條目都會收到一個 :meth:`task_done`）。" + +#: ../../library/asyncio-queue.rst:149 +msgid "" +"Raises :exc:`ValueError` if called more times than there were items placed " +"in the queue." +msgstr "如果被呼叫的次數多於放入佇列中的項目數量，將引發 :exc:`ValueError`。" + +#: ../../library/asyncio-queue.rst:154 +msgid "Priority Queue" +msgstr "Priority Queue（優先佇列）" + +#: ../../library/asyncio-queue.rst:158 +msgid "" +"A variant of :class:`Queue`; retrieves entries in priority order (lowest " +"first)." +msgstr ":class:`Queue` 的變形；按優先順序取出條目 (最小的先取出)。" + +#: ../../library/asyncio-queue.rst:161 +msgid "Entries are typically tuples of the form ``(priority_number, data)``." +msgstr "條目通常是 ``(priority_number, data)`` 形式的 tuple（元組）。" + +#: ../../library/asyncio-queue.rst:166 +msgid "LIFO Queue" +msgstr "LIFO Queue" + +#: ../../library/asyncio-queue.rst:170 +msgid "" +"A variant of :class:`Queue` that retrieves most recently added entries first " +"(last in, first out)." +msgstr ":class:`Queue` 的變形，先取出最近新增的條目（後進先出）。" + +#: ../../library/asyncio-queue.rst:175 +msgid "Exceptions" +msgstr "例外" + +#: ../../library/asyncio-queue.rst:179 +msgid "" +"This exception is raised when the :meth:`~Queue.get_nowait` method is called " +"on an empty queue." +msgstr "當佇列為空的時候，呼叫 :meth:`~Queue.get_nowait` 方法會引發這個例外。" + +#: ../../library/asyncio-queue.rst:185 +msgid "" +"Exception raised when the :meth:`~Queue.put_nowait` method is called on a " +"queue that has reached its *maxsize*." +msgstr "" +"當佇列中條目數量已經達到它的 *maxsize* 時，呼叫 :meth:`~Queue.put_nowait` 方" +"法會引發這個例外。" + +#: ../../library/asyncio-queue.rst:191 +msgid "" +"Exception raised when :meth:`~Queue.put` or :meth:`~Queue.get` is called on " +"a queue which has been shut down." +msgstr "" + +#: ../../library/asyncio-queue.rst:198 +msgid "Examples" +msgstr "範例" + +#: ../../library/asyncio-queue.rst:202 +msgid "" +"Queues can be used to distribute workload between several concurrent tasks::" +msgstr "佇列能被用於多個並行任務的工作分配：" + +#: ../../library/asyncio-queue.rst:205 +msgid "" +"import asyncio\n" +"import random\n" +"import time\n" +"\n" +"\n" +"async def worker(name, queue):\n" +" while True:\n" +" # Get a \"work item\" out of the queue.\n" +" sleep_for = await queue.get()\n" +"\n" +" # Sleep for the \"sleep_for\" seconds.\n" +" await asyncio.sleep(sleep_for)\n" +"\n" +" # Notify the queue that the \"work item\" has been processed.\n" +" queue.task_done()\n" +"\n" +" print(f'{name} has slept for {sleep_for:.2f} seconds')\n" +"\n" +"\n" +"async def main():\n" +" # Create a queue that we will use to store our \"workload\".\n" +" queue = asyncio.Queue()\n" +"\n" +" # Generate random timings and put them into the queue.\n" +" total_sleep_time = 0\n" +" for _ in range(20):\n" +" sleep_for = random.uniform(0.05, 1.0)\n" +" total_sleep_time += sleep_for\n" +" queue.put_nowait(sleep_for)\n" +"\n" +" # Create three worker tasks to process the queue concurrently.\n" +" tasks = []\n" +" for i in range(3):\n" +" task = asyncio.create_task(worker(f'worker-{i}', queue))\n" +" tasks.append(task)\n" +"\n" +" # Wait until the queue is fully processed.\n" +" started_at = time.monotonic()\n" +" await queue.join()\n" +" total_slept_for = time.monotonic() - started_at\n" +"\n" +" # Cancel our worker tasks.\n" +" for task in tasks:\n" +" task.cancel()\n" +" # Wait until all worker tasks are cancelled.\n" +" await asyncio.gather(*tasks, return_exceptions=True)\n" +"\n" +" print('====')\n" +" print(f'3 workers slept in parallel for {total_slept_for:.2f} seconds')\n" +" print(f'total expected sleep time: {total_sleep_time:.2f} seconds')\n" +"\n" +"\n" +"asyncio.run(main())" +msgstr "" diff --git a/library/asyncio-runner.po b/library/asyncio-runner.po index 6ae58e897c..20b5527a6c 100644 --- a/library/asyncio-runner.po +++ b/library/asyncio-runner.po @@ -1,280 +1,280 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# FIRST AUTHOR , YEAR. -# -#, fuzzy -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" -"tw)\n" -"Language: zh_TW\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=UTF-8\n" -"Content-Transfer-Encoding: 8bit\n" - -#: ../../library/asyncio-runner.rst:6 -msgid "Runners" -msgstr "Runners (執行器)" - -#: ../../library/asyncio-runner.rst:8 -msgid "**Source code:** :source:`Lib/asyncio/runners.py`" -msgstr "**原始碼：**\\ :source:`Lib/asyncio/runners.py`" - -#: ../../library/asyncio-runner.rst:11 -msgid "" -"This section outlines high-level asyncio primitives to run asyncio code." -msgstr "這個章節概述用於執行 asyncio 程式碼的高階 asyncio 原始物件。" - -#: ../../library/asyncio-runner.rst:13 -msgid "" -"They are built on top of an :ref:`event loop ` with the " -"aim to simplify async code usage for common wide-spread scenarios." -msgstr "" -"他們是基於一個\\ :ref:`事件迴圈 `，目的是為了簡化常見且廣" -"泛運用場景的非同步程式碼。" - -#: ../../library/asyncio-runner.rst:23 -msgid "Running an asyncio Program" -msgstr "運行一個 asyncio 程式" - -#: ../../library/asyncio-runner.rst:27 -msgid "Execute *coro* in an asyncio event loop and return the result." -msgstr "在 asyncio 事件迴圈中執行 *coro* 並回傳結果。" - -#: ../../library/asyncio-runner.rst:29 ../../library/asyncio-runner.rst:121 -msgid "The argument can be any awaitable object." -msgstr "該引數可以是任何可等待物件 (awaitable object)。" - -#: ../../library/asyncio-runner.rst:31 -msgid "" -"This function runs the awaitable, taking care of managing the asyncio event " -"loop, *finalizing asynchronous generators*, and closing the executor." -msgstr "" -"這個函式負責運行被傳入的可等待物件、管理 asyncio 的事件迴圈、*終結非同步產生器*\\ 以" -"及關閉執行器。" - -#: ../../library/asyncio-runner.rst:35 ../../library/asyncio-runner.rst:131 -msgid "" -"This function cannot be called when another asyncio event loop is running in " -"the same thread." -msgstr "當另一個非同步事件迴圈在同一執行緒中執行時，無法呼叫此函式。" - -#: ../../library/asyncio-runner.rst:38 ../../library/asyncio-runner.rst:97 -msgid "" -"If *debug* is ``True``, the event loop will be run in debug mode. ``False`` " -"disables debug mode explicitly. ``None`` is used to respect the " -"global :ref:`asyncio-debug-mode` settings." -msgstr "" -"如果 *debug* 為 ``True``，事件迴圈會以除錯模式執行。``False`` 則會關閉除錯模" -"式。``None`` 則會優先使用\\ :ref:`除錯模式 `\\ 的全域設" -"定。" - -#: ../../library/asyncio-runner.rst:42 -msgid "" -"If *loop_factory* is not ``None``, it is used to create a new event loop; " -"otherwise :func:`asyncio.new_event_loop` is used. The loop is closed at the " -"end. This function should be used as a main entry point for asyncio " -"programs, and should ideally only be called once. It is recommended to use " -"*loop_factory* to configure the event loop instead of policies. " -"Passing :class:`asyncio.EventLoop` allows running asyncio without the policy " -"system." -msgstr "" -"如果 *loop_factory* 不為 ``None``，它會被用於建立一個新的事件迴圈；否則會改" -"用 :func:`asyncio.new_event_loop`。迴圈會在最後關閉。這個函式應該要作為" -"asyncio 程式的主要進入點，且理想上僅會被呼叫一次。推薦使用 *loop_factory* 來" -"設定事件迴圈時而不是使用 policies（政策）。傳遞 :class:`asyncio.EventLoop` 可" -"以讓 asyncio 在沒有政策系統的情況下運行。" - -#: ../../library/asyncio-runner.rst:50 -msgid "" -"The executor is given a timeout duration of 5 minutes to shutdown. If the " -"executor hasn't finished within that duration, a warning is emitted and the " -"executor is closed." -msgstr "" - -#: ../../library/asyncio-runner.rst:54 -msgid "Example::" -msgstr "範例： ::" - -#: ../../library/asyncio-runner.rst:56 -msgid "" -"async def main():\n" -" await asyncio.sleep(1)\n" -" print('hello')\n" -"\n" -"asyncio.run(main())" -msgstr "" -"async def main():\n" -" await asyncio.sleep(1)\n" -" print('hello')\n" -"\n" -"asyncio.run(main())" - -#: ../../library/asyncio-runner.rst:64 -msgid "Updated to use :meth:`loop.shutdown_default_executor`." -msgstr "" - -#: ../../library/asyncio-runner.rst:69 -msgid "" -"*debug* is ``None`` by default to respect the global debug mode settings." -msgstr "" - -#: ../../library/asyncio-runner.rst:73 -msgid "Added *loop_factory* parameter." -msgstr "新增 *loop_factory* 參數。" - -#: ../../library/asyncio-runner.rst:77 ../../library/asyncio-runner.rst:136 -msgid "*coro* can be any awaitable object." -msgstr "" - -#: ../../library/asyncio-runner.rst:81 -msgid "" -"The :mod:`!asyncio` policy system is deprecated and will be removed in " -"Python 3.16; from there on, an explicit *loop_factory* is needed to " -"configure the event loop." -msgstr "" - -#: ../../library/asyncio-runner.rst:87 -msgid "Runner context manager" -msgstr "" - -#: ../../library/asyncio-runner.rst:91 -msgid "" -"A context manager that simplifies *multiple* async function calls in the " -"same context." -msgstr "" - -#: ../../library/asyncio-runner.rst:94 -msgid "" -"Sometimes several top-level async functions should be called in the " -"same :ref:`event loop ` and :class:`contextvars.Context`." -msgstr "" - -#: ../../library/asyncio-runner.rst:101 -msgid "" -"*loop_factory* could be used for overriding the loop creation. It is the " -"responsibility of the *loop_factory* to set the created loop as the current " -"one. By default :func:`asyncio.new_event_loop` is used and set as current " -"event loop with :func:`asyncio.set_event_loop` if *loop_factory* is ``None``." -msgstr "" - -#: ../../library/asyncio-runner.rst:106 -msgid "" -"Basically, :func:`asyncio.run` example can be rewritten with the runner " -"usage::" -msgstr "" - -#: ../../library/asyncio-runner.rst:108 -msgid "" -"async def main():\n" -" await asyncio.sleep(1)\n" -" print('hello')\n" -"\n" -"with asyncio.Runner() as runner:\n" -" runner.run(main())" -msgstr "" -"async def main():\n" -" await asyncio.sleep(1)\n" -" print('hello')\n" -"\n" -"with asyncio.Runner() as runner:\n" -" runner.run(main())" - -#: ../../library/asyncio-runner.rst:119 -msgid "Execute *coro* in the embedded event loop." -msgstr "" - -#: ../../library/asyncio-runner.rst:123 -msgid "If the argument is a coroutine, it is wrapped in a Task." -msgstr "" - -#: ../../library/asyncio-runner.rst:125 -msgid "" -"An optional keyword-only *context* argument allows specifying a " -"custom :class:`contextvars.Context` for the code to run in. The runner's " -"default context is used if context is ``None``." -msgstr "" - -#: ../../library/asyncio-runner.rst:129 -msgid "Returns the awaitable's result or raises an exception." -msgstr "" - -#: ../../library/asyncio-runner.rst:140 -msgid "Close the runner." -msgstr "" - -#: ../../library/asyncio-runner.rst:142 -msgid "" -"Finalize asynchronous generators, shutdown default executor, close the event " -"loop and release embedded :class:`contextvars.Context`." -msgstr "" - -#: ../../library/asyncio-runner.rst:147 -msgid "Return the event loop associated with the runner instance." -msgstr "" - -#: ../../library/asyncio-runner.rst:151 -msgid "" -":class:`Runner` uses the lazy initialization strategy, its constructor " -"doesn't initialize underlying low-level structures." -msgstr "" - -#: ../../library/asyncio-runner.rst:154 -msgid "" -"Embedded *loop* and *context* are created at the :keyword:`with` body " -"entering or the first call of :meth:`run` or :meth:`get_loop`." -msgstr "" - -#: ../../library/asyncio-runner.rst:159 -msgid "Handling Keyboard Interruption" -msgstr "" - -#: ../../library/asyncio-runner.rst:163 -msgid "" -"When :const:`signal.SIGINT` is raised by :kbd:`Ctrl-" -"C`, :exc:`KeyboardInterrupt` exception is raised in the main thread by " -"default. However this doesn't work with :mod:`asyncio` because it can " -"interrupt asyncio internals and can hang the program from exiting." -msgstr "" - -#: ../../library/asyncio-runner.rst:168 -msgid "" -"To mitigate this issue, :mod:`asyncio` handles :const:`signal.SIGINT` as " -"follows:" -msgstr "" - -#: ../../library/asyncio-runner.rst:170 -msgid "" -":meth:`asyncio.Runner.run` installs a custom :const:`signal.SIGINT` handler " -"before any user code is executed and removes it when exiting from the " -"function." -msgstr "" - -#: ../../library/asyncio-runner.rst:172 -msgid "" -"The :class:`~asyncio.Runner` creates the main task for the passed coroutine " -"for its execution." -msgstr "" - -#: ../../library/asyncio-runner.rst:174 -msgid "" -"When :const:`signal.SIGINT` is raised by :kbd:`Ctrl-C`, the custom signal " -"handler cancels the main task by calling :meth:`asyncio.Task.cancel` which " -"raises :exc:`asyncio.CancelledError` inside the main task. This causes the " -"Python stack to unwind, ``try/except`` and ``try/finally`` blocks can be " -"used for resource cleanup. After the main task is " -"cancelled, :meth:`asyncio.Runner.run` raises :exc:`KeyboardInterrupt`." -msgstr "" - -#: ../../library/asyncio-runner.rst:180 -msgid "" -"A user could write a tight loop which cannot be interrupted " -"by :meth:`asyncio.Task.cancel`, in which case the second " -"following :kbd:`Ctrl-C` immediately raises the :exc:`KeyboardInterrupt` " -"without cancelling the main task." -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" +"tw)\n" +"Language: zh_TW\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../library/asyncio-runner.rst:6 +msgid "Runners" +msgstr "Runners (執行器)" + +#: ../../library/asyncio-runner.rst:8 +msgid "**Source code:** :source:`Lib/asyncio/runners.py`" +msgstr "**原始碼：**\\ :source:`Lib/asyncio/runners.py`" + +#: ../../library/asyncio-runner.rst:11 +msgid "" +"This section outlines high-level asyncio primitives to run asyncio code." +msgstr "這個章節概述用於執行 asyncio 程式碼的高階 asyncio 原始物件。" + +#: ../../library/asyncio-runner.rst:13 +msgid "" +"They are built on top of an :ref:`event loop ` with the " +"aim to simplify async code usage for common wide-spread scenarios." +msgstr "" +"他們是基於一個\\ :ref:`事件迴圈 `，目的是為了簡化常見且廣" +"泛運用場景的非同步程式碼。" + +#: ../../library/asyncio-runner.rst:23 +msgid "Running an asyncio Program" +msgstr "運行一個 asyncio 程式" + +#: ../../library/asyncio-runner.rst:27 +msgid "Execute *coro* in an asyncio event loop and return the result." +msgstr "在 asyncio 事件迴圈中執行 *coro* 並回傳結果。" + +#: ../../library/asyncio-runner.rst:29 ../../library/asyncio-runner.rst:121 +msgid "The argument can be any awaitable object." +msgstr "該引數可以是任何可等待物件 (awaitable object)。" + +#: ../../library/asyncio-runner.rst:31 +msgid "" +"This function runs the awaitable, taking care of managing the asyncio event " +"loop, *finalizing asynchronous generators*, and closing the executor." +msgstr "" +"這個函式負責運行被傳入的可等待物件、管理 asyncio 的事件迴圈、*終結非同步產生器*\\ 以" +"及關閉執行器。" + +#: ../../library/asyncio-runner.rst:35 ../../library/asyncio-runner.rst:131 +msgid "" +"This function cannot be called when another asyncio event loop is running in " +"the same thread." +msgstr "當另一個非同步事件迴圈在同一執行緒中執行時，無法呼叫此函式。" + +#: ../../library/asyncio-runner.rst:38 ../../library/asyncio-runner.rst:97 +msgid "" +"If *debug* is ``True``, the event loop will be run in debug mode. ``False`` " +"disables debug mode explicitly. ``None`` is used to respect the " +"global :ref:`asyncio-debug-mode` settings." +msgstr "" +"如果 *debug* 為 ``True``，事件迴圈會以除錯模式執行。``False`` 則會關閉除錯模" +"式。``None`` 則會優先使用\\ :ref:`除錯模式 `\\ 的全域設" +"定。" + +#: ../../library/asyncio-runner.rst:42 +msgid "" +"If *loop_factory* is not ``None``, it is used to create a new event loop; " +"otherwise :func:`asyncio.new_event_loop` is used. The loop is closed at the " +"end. This function should be used as a main entry point for asyncio " +"programs, and should ideally only be called once. It is recommended to use " +"*loop_factory* to configure the event loop instead of policies. " +"Passing :class:`asyncio.EventLoop` allows running asyncio without the policy " +"system." +msgstr "" +"如果 *loop_factory* 不為 ``None``，它會被用於建立一個新的事件迴圈；否則會改" +"用 :func:`asyncio.new_event_loop`。迴圈會在最後關閉。這個函式應該要作為" +"asyncio 程式的主要進入點，且理想上僅會被呼叫一次。推薦使用 *loop_factory* 來" +"設定事件迴圈時而不是使用 policies（政策）。傳遞 :class:`asyncio.EventLoop` 可" +"以讓 asyncio 在沒有政策系統的情況下運行。" + +#: ../../library/asyncio-runner.rst:50 +msgid "" +"The executor is given a timeout duration of 5 minutes to shutdown. If the " +"executor hasn't finished within that duration, a warning is emitted and the " +"executor is closed." +msgstr "" + +#: ../../library/asyncio-runner.rst:54 +msgid "Example::" +msgstr "範例： ::" + +#: ../../library/asyncio-runner.rst:56 +msgid "" +"async def main():\n" +" await asyncio.sleep(1)\n" +" print('hello')\n" +"\n" +"asyncio.run(main())" +msgstr "" +"async def main():\n" +" await asyncio.sleep(1)\n" +" print('hello')\n" +"\n" +"asyncio.run(main())" + +#: ../../library/asyncio-runner.rst:64 +msgid "Updated to use :meth:`loop.shutdown_default_executor`." +msgstr "" + +#: ../../library/asyncio-runner.rst:69 +msgid "" +"*debug* is ``None`` by default to respect the global debug mode settings." +msgstr "" + +#: ../../library/asyncio-runner.rst:73 +msgid "Added *loop_factory* parameter." +msgstr "新增 *loop_factory* 參數。" + +#: ../../library/asyncio-runner.rst:77 ../../library/asyncio-runner.rst:136 +msgid "*coro* can be any awaitable object." +msgstr "" + +#: ../../library/asyncio-runner.rst:81 +msgid "" +"The :mod:`!asyncio` policy system is deprecated and will be removed in " +"Python 3.16; from there on, an explicit *loop_factory* is needed to " +"configure the event loop." +msgstr "" + +#: ../../library/asyncio-runner.rst:87 +msgid "Runner context manager" +msgstr "" + +#: ../../library/asyncio-runner.rst:91 +msgid "" +"A context manager that simplifies *multiple* async function calls in the " +"same context." +msgstr "" + +#: ../../library/asyncio-runner.rst:94 +msgid "" +"Sometimes several top-level async functions should be called in the " +"same :ref:`event loop ` and :class:`contextvars.Context`." +msgstr "" + +#: ../../library/asyncio-runner.rst:101 +msgid "" +"*loop_factory* could be used for overriding the loop creation. It is the " +"responsibility of the *loop_factory* to set the created loop as the current " +"one. By default :func:`asyncio.new_event_loop` is used and set as current " +"event loop with :func:`asyncio.set_event_loop` if *loop_factory* is ``None``." +msgstr "" + +#: ../../library/asyncio-runner.rst:106 +msgid "" +"Basically, :func:`asyncio.run` example can be rewritten with the runner " +"usage::" +msgstr "" + +#: ../../library/asyncio-runner.rst:108 +msgid "" +"async def main():\n" +" await asyncio.sleep(1)\n" +" print('hello')\n" +"\n" +"with asyncio.Runner() as runner:\n" +" runner.run(main())" +msgstr "" +"async def main():\n" +" await asyncio.sleep(1)\n" +" print('hello')\n" +"\n" +"with asyncio.Runner() as runner:\n" +" runner.run(main())" + +#: ../../library/asyncio-runner.rst:119 +msgid "Execute *coro* in the embedded event loop." +msgstr "" + +#: ../../library/asyncio-runner.rst:123 +msgid "If the argument is a coroutine, it is wrapped in a Task." +msgstr "" + +#: ../../library/asyncio-runner.rst:125 +msgid "" +"An optional keyword-only *context* argument allows specifying a " +"custom :class:`contextvars.Context` for the code to run in. The runner's " +"default context is used if context is ``None``." +msgstr "" + +#: ../../library/asyncio-runner.rst:129 +msgid "Returns the awaitable's result or raises an exception." +msgstr "" + +#: ../../library/asyncio-runner.rst:140 +msgid "Close the runner." +msgstr "" + +#: ../../library/asyncio-runner.rst:142 +msgid "" +"Finalize asynchronous generators, shutdown default executor, close the event " +"loop and release embedded :class:`contextvars.Context`." +msgstr "" + +#: ../../library/asyncio-runner.rst:147 +msgid "Return the event loop associated with the runner instance." +msgstr "" + +#: ../../library/asyncio-runner.rst:151 +msgid "" +":class:`Runner` uses the lazy initialization strategy, its constructor " +"doesn't initialize underlying low-level structures." +msgstr "" + +#: ../../library/asyncio-runner.rst:154 +msgid "" +"Embedded *loop* and *context* are created at the :keyword:`with` body " +"entering or the first call of :meth:`run` or :meth:`get_loop`." +msgstr "" + +#: ../../library/asyncio-runner.rst:159 +msgid "Handling Keyboard Interruption" +msgstr "" + +#: ../../library/asyncio-runner.rst:163 +msgid "" +"When :const:`signal.SIGINT` is raised by :kbd:`Ctrl-" +"C`, :exc:`KeyboardInterrupt` exception is raised in the main thread by " +"default. However this doesn't work with :mod:`asyncio` because it can " +"interrupt asyncio internals and can hang the program from exiting." +msgstr "" + +#: ../../library/asyncio-runner.rst:168 +msgid "" +"To mitigate this issue, :mod:`asyncio` handles :const:`signal.SIGINT` as " +"follows:" +msgstr "" + +#: ../../library/asyncio-runner.rst:170 +msgid "" +":meth:`asyncio.Runner.run` installs a custom :const:`signal.SIGINT` handler " +"before any user code is executed and removes it when exiting from the " +"function." +msgstr "" + +#: ../../library/asyncio-runner.rst:172 +msgid "" +"The :class:`~asyncio.Runner` creates the main task for the passed coroutine " +"for its execution." +msgstr "" + +#: ../../library/asyncio-runner.rst:174 +msgid "" +"When :const:`signal.SIGINT` is raised by :kbd:`Ctrl-C`, the custom signal " +"handler cancels the main task by calling :meth:`asyncio.Task.cancel` which " +"raises :exc:`asyncio.CancelledError` inside the main task. This causes the " +"Python stack to unwind, ``try/except`` and ``try/finally`` blocks can be " +"used for resource cleanup. After the main task is " +"cancelled, :meth:`asyncio.Runner.run` raises :exc:`KeyboardInterrupt`." +msgstr "" + +#: ../../library/asyncio-runner.rst:180 +msgid "" +"A user could write a tight loop which cannot be interrupted " +"by :meth:`asyncio.Task.cancel`, in which case the second " +"following :kbd:`Ctrl-C` immediately raises the :exc:`KeyboardInterrupt` " +"without cancelling the main task." +msgstr "" diff --git a/library/asyncio-stream.po b/library/asyncio-stream.po index 064b189944..c50c9a5144 100644 --- a/library/asyncio-stream.po +++ b/library/asyncio-stream.po @@ -1,785 +1,785 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Adrian Liaw , 2018 -# Matt Wang , 2022-2024 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-10-05 00:16+0000\n" -"PO-Revision-Date: 2022-10-31 16:28+0800\n" -"Last-Translator: Matt Wang \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" -"X-Generator: Poedit 3.1.1\n" - -#: ../../library/asyncio-stream.rst:7 -msgid "Streams" -msgstr "串流" - -#: ../../library/asyncio-stream.rst:9 -msgid "**Source code:** :source:`Lib/asyncio/streams.py`" -msgstr "**原始碼：**\\ :source:`Lib/asyncio/streams.py`" - -#: ../../library/asyncio-stream.rst:13 -msgid "" -"Streams are high-level async/await-ready primitives to work with network " -"connections. Streams allow sending and receiving data without using " -"callbacks or low-level protocols and transports." -msgstr "" -"串流是支援 async/await (async/await-ready) 的高階原始物件 (high-level " -"primitive)，用於處理網路連線。串流不需要使用回呼 (callback) 或低階協定和傳輸 " -"(transport) 就能夠傳送和接收資料。" - -#: ../../library/asyncio-stream.rst:19 -msgid "Here is an example of a TCP echo client written using asyncio streams::" -msgstr "這是一個使用 asyncio 串流編寫的 TCP echo 用戶端範例： ::" - -#: ../../library/asyncio-stream.rst:22 ../../library/asyncio-stream.rst:441 -msgid "" -"import asyncio\n" -"\n" -"async def tcp_echo_client(message):\n" -" reader, writer = await asyncio.open_connection(\n" -" '127.0.0.1', 8888)\n" -"\n" -" print(f'Send: {message!r}')\n" -" writer.write(message.encode())\n" -" await writer.drain()\n" -"\n" -" data = await reader.read(100)\n" -" print(f'Received: {data.decode()!r}')\n" -"\n" -" print('Close the connection')\n" -" writer.close()\n" -" await writer.wait_closed()\n" -"\n" -"asyncio.run(tcp_echo_client('Hello World!'))" -msgstr "" -"import asyncio\n" -"\n" -"async def tcp_echo_client(message):\n" -" reader, writer = await asyncio.open_connection(\n" -" '127.0.0.1', 8888)\n" -"\n" -" print(f'Send: {message!r}')\n" -" writer.write(message.encode())\n" -" await writer.drain()\n" -"\n" -" data = await reader.read(100)\n" -" print(f'Received: {data.decode()!r}')\n" -"\n" -" print('Close the connection')\n" -" writer.close()\n" -" await writer.wait_closed()\n" -"\n" -"asyncio.run(tcp_echo_client('Hello World!'))" - -#: ../../library/asyncio-stream.rst:42 -msgid "See also the `Examples`_ section below." -msgstr "另請參閱下方 `Examples`_ 段落。" - -#: ../../library/asyncio-stream.rst:46 -msgid "Stream Functions" -msgstr "串流函式" - -#: ../../library/asyncio-stream.rst:47 -msgid "" -"The following top-level asyncio functions can be used to create and work " -"with streams:" -msgstr "下面的高階 asyncio 函式可以用來建立和處理串流：" - -#: ../../library/asyncio-stream.rst:59 -msgid "" -"Establish a network connection and return a pair of ``(reader, writer)`` " -"objects." -msgstr "建立網路連線並回傳一對 ``(reader, writer)`` 物件。" - -#: ../../library/asyncio-stream.rst:62 -msgid "" -"The returned *reader* and *writer* objects are instances of :class:" -"`StreamReader` and :class:`StreamWriter` classes." -msgstr "" -"回傳的 *reader* 和 *writer* 物件是 :class:`StreamReader` 和 :class:" -"`StreamWriter` 類別的實例。" - -#: ../../library/asyncio-stream.rst:65 ../../library/asyncio-stream.rst:112 -msgid "" -"*limit* determines the buffer size limit used by the returned :class:" -"`StreamReader` instance. By default the *limit* is set to 64 KiB." -msgstr "" -"*limit* 指定了回傳的 :class:`StreamReader` 實例所使用的緩衝區 (buffer) 大小限" -"制。*limit* 預設為 64 KiB。" - -#: ../../library/asyncio-stream.rst:69 -msgid "" -"The rest of the arguments are passed directly to :meth:`loop." -"create_connection`." -msgstr "其餘的引數會直接傳遞到 :meth:`loop.create_connection`。" - -#: ../../library/asyncio-stream.rst:74 ../../library/asyncio-stream.rst:154 -msgid "" -"The *sock* argument transfers ownership of the socket to the :class:" -"`StreamWriter` created. To close the socket, call its :meth:`~asyncio." -"StreamWriter.close` method." -msgstr "" - -#: ../../library/asyncio-stream.rst:78 -msgid "Added the *ssl_handshake_timeout* parameter." -msgstr "新增 *ssl_handshake_timeout* 參數。" - -#: ../../library/asyncio-stream.rst:81 -msgid "Added the *happy_eyeballs_delay* and *interleave* parameters." -msgstr "新增 *happy_eyeballs_delay* 和 *interleave* 參數。" - -#: ../../library/asyncio-stream.rst:84 ../../library/asyncio-stream.rst:128 -#: ../../library/asyncio-stream.rst:164 ../../library/asyncio-stream.rst:199 -msgid "Removed the *loop* parameter." -msgstr "移除 *loop* 參數。" - -#: ../../library/asyncio-stream.rst:87 ../../library/asyncio-stream.rst:131 -#: ../../library/asyncio-stream.rst:167 ../../library/asyncio-stream.rst:202 -#: ../../library/asyncio-stream.rst:408 -msgid "Added the *ssl_shutdown_timeout* parameter." -msgstr "新增 *ssl_shutdown_timeout* 參數。" - -#: ../../library/asyncio-stream.rst:101 -msgid "Start a socket server." -msgstr "啟動 socket 伺服器。" - -#: ../../library/asyncio-stream.rst:103 -msgid "" -"The *client_connected_cb* callback is called whenever a new client " -"connection is established. It receives a ``(reader, writer)`` pair as two " -"arguments, instances of the :class:`StreamReader` and :class:`StreamWriter` " -"classes." -msgstr "" -"當一個新的用戶端連線被建立時，回呼函式 *client_connected_cb* 就會被呼叫。該函" -"式會接收到一對引數 ``(reader, writer)``，分別為 :class:`StreamReader` 和 :" -"class:`StreamWriter` 的實例。" - -#: ../../library/asyncio-stream.rst:108 -msgid "" -"*client_connected_cb* can be a plain callable or a :ref:`coroutine function " -"`; if it is a coroutine function, it will be automatically " -"scheduled as a :class:`Task`." -msgstr "" -"*client_connected_cb* 既可以是普通的可呼叫物件 (callable)，也可以是一個\\ :" -"ref:`協程函式 `；如果它是一個協程函式，它將自動作為 :class:`Task` " -"來被排程。" - -#: ../../library/asyncio-stream.rst:116 -msgid "" -"The rest of the arguments are passed directly to :meth:`loop.create_server`." -msgstr "剩下的引數將會直接傳遞給 :meth:`loop.create_server`。" - -#: ../../library/asyncio-stream.rst:121 ../../library/asyncio-stream.rst:189 -msgid "" -"The *sock* argument transfers ownership of the socket to the server created. " -"To close the socket, call the server's :meth:`~asyncio.Server.close` method." -msgstr "" - -#: ../../library/asyncio-stream.rst:125 -msgid "Added the *ssl_handshake_timeout* and *start_serving* parameters." -msgstr "新增 *ssl_handshake_timeout* 與 *start_serving* 參數。" - -#: ../../library/asyncio-stream.rst:134 -msgid "Added the *keep_alive* parameter." -msgstr "新增 *keep_alive* 參數。" - -#: ../../library/asyncio-stream.rst:139 -msgid "Unix Sockets" -msgstr "Unix Sockets" - -#: ../../library/asyncio-stream.rst:145 -msgid "" -"Establish a Unix socket connection and return a pair of ``(reader, writer)``." -msgstr "建立一個 Unix socket 連線並回傳一對 ``(reader, writer)``。" - -#: ../../library/asyncio-stream.rst:148 -msgid "Similar to :func:`open_connection` but operates on Unix sockets." -msgstr "與 :func:`open_connection` 相似，但是是操作 Unix sockets。" - -#: ../../library/asyncio-stream.rst:150 -msgid "See also the documentation of :meth:`loop.create_unix_connection`." -msgstr "另請參閱 :meth:`loop.create_unix_connection` 文件。" - -#: ../../library/asyncio-stream.rst:158 ../../library/asyncio-stream.rst:193 -msgid "Availability" -msgstr "可用性" - -#: ../../library/asyncio-stream.rst:160 -msgid "" -"Added the *ssl_handshake_timeout* parameter. The *path* parameter can now be " -"a :term:`path-like object`" -msgstr "" -"新增 *ssl_handshake_timeout* 參數。*path* 參數現在可以是個 :term:`path-like " -"object`" - -#: ../../library/asyncio-stream.rst:177 -msgid "Start a Unix socket server." -msgstr "啟動一個 Unix socket 伺服器。" - -#: ../../library/asyncio-stream.rst:179 -msgid "Similar to :func:`start_server` but works with Unix sockets." -msgstr "與 :func:`start_server` 相似，但會是操作 Unix sockets。" - -#: ../../library/asyncio-stream.rst:181 -msgid "" -"If *cleanup_socket* is true then the Unix socket will automatically be " -"removed from the filesystem when the server is closed, unless the socket has " -"been replaced after the server has been created." -msgstr "" - -#: ../../library/asyncio-stream.rst:185 -msgid "See also the documentation of :meth:`loop.create_unix_server`." -msgstr "另請參閱 :meth:`loop.create_unix_server` 文件。" - -#: ../../library/asyncio-stream.rst:195 -msgid "" -"Added the *ssl_handshake_timeout* and *start_serving* parameters. The *path* " -"parameter can now be a :term:`path-like object`." -msgstr "" -"新增 *ssl_handshake_timeout* 與 *start_serving* 參數。*path* 參數現在可以是" -"個 :term:`path-like object`。" - -#: ../../library/asyncio-stream.rst:205 -msgid "Added the *cleanup_socket* parameter." -msgstr "新增 *cleanup_socket* 參數。" - -#: ../../library/asyncio-stream.rst:210 -msgid "StreamReader" -msgstr "StreamReader" - -#: ../../library/asyncio-stream.rst:214 -msgid "" -"Represents a reader object that provides APIs to read data from the IO " -"stream. As an :term:`asynchronous iterable`, the object supports the :" -"keyword:`async for` statement." -msgstr "" -"表示一個有提供 API 來從 IO 串流中讀取資料的 reader 物件。作為一個 :term:" -"`asynchronous iterable`，此物件支援 :keyword:`async for` 陳述式。" - -#: ../../library/asyncio-stream.rst:218 -msgid "" -"It is not recommended to instantiate *StreamReader* objects directly; use :" -"func:`open_connection` and :func:`start_server` instead." -msgstr "" -"不建議直接實例化 *StreamReader* 物件；使用 :func:`open_connection` 和 :func:" -"`start_server` 會是較好的做法。" - -#: ../../library/asyncio-stream.rst:224 -msgid "Acknowledge the EOF." -msgstr "" - -#: ../../library/asyncio-stream.rst:229 -msgid "Read up to *n* bytes from the stream." -msgstr "從串流中讀取至多 *n* 個位元組的資料。" - -#: ../../library/asyncio-stream.rst:231 -msgid "" -"If *n* is not provided or set to ``-1``, read until EOF, then return all " -"read :class:`bytes`. If EOF was received and the internal buffer is empty, " -"return an empty ``bytes`` object." -msgstr "" -"如果沒有設定 *n* 或是被設為 ``-1``，則會持續讀取直到 EOF，然後回傳所有讀取到" -"的 :class:`bytes`。讀取到 EOF 且內部緩衝區是空的，則回傳一個空的 ``bytes`` 物" -"件。" - -#: ../../library/asyncio-stream.rst:236 -msgid "If *n* is ``0``, return an empty ``bytes`` object immediately." -msgstr "如果 *n* 為 ``0``，則立即回傳一個空的 ``bytes`` 物件。" - -#: ../../library/asyncio-stream.rst:238 -msgid "" -"If *n* is positive, return at most *n* available ``bytes`` as soon as at " -"least 1 byte is available in the internal buffer. If EOF is received before " -"any byte is read, return an empty ``bytes`` object." -msgstr "" - -#: ../../library/asyncio-stream.rst:246 -msgid "" -"Read one line, where \"line\" is a sequence of bytes ending with ``\\n``." -msgstr "讀取一行，其中\"行\"指的是以 ``\\n`` 結尾的位元組序列。" - -#: ../../library/asyncio-stream.rst:249 -msgid "" -"If EOF is received and ``\\n`` was not found, the method returns partially " -"read data." -msgstr "如果讀取到 EOF 而沒有找到 ``\\n``，該方法會回傳部分的已讀取資料。" - -#: ../../library/asyncio-stream.rst:252 -msgid "" -"If EOF is received and the internal buffer is empty, return an empty " -"``bytes`` object." -msgstr "如果讀取到 EOF 且內部緩衝區是空的，則回傳一個空的 ``bytes`` 物件。" - -#: ../../library/asyncio-stream.rst:258 -msgid "Read exactly *n* bytes." -msgstr "讀取剛好 *n* 個位元組。" - -#: ../../library/asyncio-stream.rst:260 -msgid "" -"Raise an :exc:`IncompleteReadError` if EOF is reached before *n* can be " -"read. Use the :attr:`IncompleteReadError.partial` attribute to get the " -"partially read data." -msgstr "" -"如果在讀取完 *n* 個位元組之前讀取到 EOF，則會引發 :exc:" -"`IncompleteReadError`。使用 :attr:`IncompleteReadError.partial` 屬性來取得串" -"流結束前已讀取的部分資料。" - -#: ../../library/asyncio-stream.rst:267 -msgid "Read data from the stream until *separator* is found." -msgstr "從串流中持續讀取資料直到出現 *separator*。" - -#: ../../library/asyncio-stream.rst:269 -msgid "" -"On success, the data and separator will be removed from the internal buffer " -"(consumed). Returned data will include the separator at the end." -msgstr "" -"成功後，資料和 separator（分隔符號）會從內部緩衝區中刪除（或者說是被消費掉 " -"(consumed)）。回傳的資料在末尾會有一個 separator。" - -#: ../../library/asyncio-stream.rst:273 -msgid "" -"If the amount of data read exceeds the configured stream limit, a :exc:" -"`LimitOverrunError` exception is raised, and the data is left in the " -"internal buffer and can be read again." -msgstr "" -"如果讀取的資料量超過了設定的串流限制，將會引發 :exc:`LimitOverrunError` 例" -"外，資料將被留在內部緩衝區中，並可以再次被讀取。" - -#: ../../library/asyncio-stream.rst:277 -msgid "" -"If EOF is reached before the complete separator is found, an :exc:" -"`IncompleteReadError` exception is raised, and the internal buffer is " -"reset. The :attr:`IncompleteReadError.partial` attribute may contain a " -"portion of the separator." -msgstr "" -"如果在完整的 separator 被找到之前就讀取到 EOF，則會引發 :exc:" -"`IncompleteReadError` 例外，且內部緩衝區會被重置。:attr:`IncompleteReadError." -"partial` 屬性可能包含一部分的 separator。" - -#: ../../library/asyncio-stream.rst:282 -msgid "" -"The *separator* may also be a tuple of separators. In this case the return " -"value will be the shortest possible that has any separator as the suffix. " -"For the purposes of :exc:`LimitOverrunError`, the shortest possible " -"separator is considered to be the one that matched." -msgstr "" - -#: ../../library/asyncio-stream.rst:292 -msgid "The *separator* parameter may now be a :class:`tuple` of separators." -msgstr "現在 *separator* 參數可以是一個分隔符號的 :class:`tuple`。" - -#: ../../library/asyncio-stream.rst:297 -msgid "Return ``True`` if the buffer is empty and :meth:`feed_eof` was called." -msgstr "如果緩衝區是空的且 :meth:`feed_eof` 曾被呼叫則回傳 ``True``。" - -#: ../../library/asyncio-stream.rst:302 -msgid "StreamWriter" -msgstr "StreamWriter" - -#: ../../library/asyncio-stream.rst:306 -msgid "" -"Represents a writer object that provides APIs to write data to the IO stream." -msgstr "表示一個有提供 API 來將資料寫入 IO 串流的 writer 物件。" - -#: ../../library/asyncio-stream.rst:309 -msgid "" -"It is not recommended to instantiate *StreamWriter* objects directly; use :" -"func:`open_connection` and :func:`start_server` instead." -msgstr "" -"不建議直接實例化 *StreamWriter* 物件；使用 :func:`open_connection` 和 :func:" -"`start_server` 會是較好的做法。" - -#: ../../library/asyncio-stream.rst:315 -msgid "" -"The method attempts to write the *data* to the underlying socket " -"immediately. If that fails, the data is queued in an internal write buffer " -"until it can be sent." -msgstr "" -"此方法會嘗試立即將 *data* 寫入到底層的 socket。如果失敗，資料會被放到內部寫入" -"緩衝中排隊等待 (queue)，直到它可被發送。" - -#: ../../library/asyncio-stream.rst:319 -msgid "" -"The *data* buffer should be a bytes, bytearray, or C-contiguous one-" -"dimensional memoryview object." -msgstr "" - -#: ../../library/asyncio-stream.rst:322 ../../library/asyncio-stream.rst:335 -msgid "The method should be used along with the ``drain()`` method::" -msgstr "此方法應當與 ``drain()`` 方法一起使用： ::" - -#: ../../library/asyncio-stream.rst:324 -msgid "" -"stream.write(data)\n" -"await stream.drain()" -msgstr "" -"stream.write(data)\n" -"await stream.drain()" - -#: ../../library/asyncio-stream.rst:330 -msgid "" -"The method writes a list (or any iterable) of bytes to the underlying socket " -"immediately. If that fails, the data is queued in an internal write buffer " -"until it can be sent." -msgstr "" -"此方法會立即嘗試將一個位元組 list（或任何可疊代物件 (iterable)）寫入到底層的 " -"socket。如果失敗，資料會被放到內部寫入緩衝中排隊等待，直到它可被發送。" - -#: ../../library/asyncio-stream.rst:337 -msgid "" -"stream.writelines(lines)\n" -"await stream.drain()" -msgstr "" -"stream.writelines(lines)\n" -"await stream.drain()" - -#: ../../library/asyncio-stream.rst:342 -msgid "The method closes the stream and the underlying socket." -msgstr "此方法會關閉串流以及底層的 socket。" - -#: ../../library/asyncio-stream.rst:344 -msgid "" -"The method should be used, though not mandatory, along with the " -"``wait_closed()`` method::" -msgstr "此方法應與 ``wait_closed()`` 方法一起使用，但並非強制： ::" - -#: ../../library/asyncio-stream.rst:347 -msgid "" -"stream.close()\n" -"await stream.wait_closed()" -msgstr "" -"stream.close()\n" -"await stream.wait_closed()" - -#: ../../library/asyncio-stream.rst:352 -msgid "" -"Return ``True`` if the underlying transport supports the :meth:`write_eof` " -"method, ``False`` otherwise." -msgstr "" -"如果底層的傳輸支援 :meth:`write_eof` 方法就回傳 ``True``，否則回傳 " -"``False``。" - -#: ../../library/asyncio-stream.rst:357 -msgid "" -"Close the write end of the stream after the buffered write data is flushed." -msgstr "在已緩衝的寫入資料被清理 (flush) 後關閉串流的寫入端。" - -#: ../../library/asyncio-stream.rst:362 -msgid "Return the underlying asyncio transport." -msgstr "回傳底層的 asyncio 傳輸。" - -#: ../../library/asyncio-stream.rst:366 -msgid "" -"Access optional transport information; see :meth:`BaseTransport." -"get_extra_info` for details." -msgstr "存取可選的傳輸資訊；詳情請見 :meth:`BaseTransport.get_extra_info`。" - -#: ../../library/asyncio-stream.rst:372 -msgid "Wait until it is appropriate to resume writing to the stream. Example::" -msgstr "等待直到可以繼續寫入到串流。範例： ::" - -#: ../../library/asyncio-stream.rst:375 -msgid "" -"writer.write(data)\n" -"await writer.drain()" -msgstr "" -"writer.write(data)\n" -"await writer.drain()" - -#: ../../library/asyncio-stream.rst:378 -msgid "" -"This is a flow control method that interacts with the underlying IO write " -"buffer. When the size of the buffer reaches the high watermark, *drain()* " -"blocks until the size of the buffer is drained down to the low watermark and " -"writing can be resumed. When there is nothing to wait for, the :meth:" -"`drain` returns immediately." -msgstr "" -"這是一個與底層 IO 寫入緩衝區互動的流程控制方法。當緩衝區大小達到最高標記位 " -"(high watermark) 時，*drain()* 會阻塞直到緩衝區大小減少至最低標記位 (low " -"watermark) 以便繼續寫入。當沒有要等待的資料時，:meth:`drain` 會立即回傳。" - -#: ../../library/asyncio-stream.rst:389 -msgid "Upgrade an existing stream-based connection to TLS." -msgstr "將現有的基於串流的連線升級到 TLS。" - -#: ../../library/asyncio-stream.rst:391 -msgid "Parameters:" -msgstr "參數：" - -#: ../../library/asyncio-stream.rst:393 -msgid "*sslcontext*: a configured instance of :class:`~ssl.SSLContext`." -msgstr "*sslcontext*：一個 :class:`~ssl.SSLContext` 的已配置實例。" - -#: ../../library/asyncio-stream.rst:395 -msgid "" -"*server_hostname*: sets or overrides the host name that the target server's " -"certificate will be matched against." -msgstr "*server_hostname*：設定或覆寫將會被目標伺服器憑證比對的主機名稱。" - -#: ../../library/asyncio-stream.rst:398 -msgid "" -"*ssl_handshake_timeout* is the time in seconds to wait for the TLS handshake " -"to complete before aborting the connection. ``60.0`` seconds if ``None`` " -"(default)." -msgstr "" - -#: ../../library/asyncio-stream.rst:402 -msgid "" -"*ssl_shutdown_timeout* is the time in seconds to wait for the SSL shutdown " -"to complete before aborting the connection. ``30.0`` seconds if ``None`` " -"(default)." -msgstr "" - -#: ../../library/asyncio-stream.rst:414 -msgid "" -"Return ``True`` if the stream is closed or in the process of being closed." -msgstr "如果串流已被關閉或正在被關閉則回傳 ``True``。" - -#: ../../library/asyncio-stream.rst:422 -msgid "Wait until the stream is closed." -msgstr "等待直到串流被關閉。" - -#: ../../library/asyncio-stream.rst:424 -msgid "" -"Should be called after :meth:`close` to wait until the underlying connection " -"is closed, ensuring that all data has been flushed before e.g. exiting the " -"program." -msgstr "" -"應當在 :meth:`close` 之後才被呼叫，這會持續等待直到底層的連線被關閉，以確保在" -"這之前（例如在程式退出前）所有資料都已經被清空" - -#: ../../library/asyncio-stream.rst:432 -msgid "Examples" -msgstr "範例" - -#: ../../library/asyncio-stream.rst:437 -msgid "TCP echo client using streams" -msgstr "使用串流的 TCP echo 用戶端" - -#: ../../library/asyncio-stream.rst:439 -msgid "TCP echo client using the :func:`asyncio.open_connection` function::" -msgstr "使用 :func:`asyncio.open_connection` 函式的 TCP echo 用戶端： ::" - -#: ../../library/asyncio-stream.rst:463 -msgid "" -"The :ref:`TCP echo client protocol " -"` example uses the low-level :meth:" -"`loop.create_connection` method." -msgstr "" -"使用低階 :meth:`loop.create_connection` 方法的 :ref:`TCP echo 用戶端協定 " -"`\\ 範例。" - -#: ../../library/asyncio-stream.rst:470 -msgid "TCP echo server using streams" -msgstr "使用串流的 TCP echo 伺服器" - -#: ../../library/asyncio-stream.rst:472 -msgid "TCP echo server using the :func:`asyncio.start_server` function::" -msgstr "TCP echo 伺服器使用 :func:`asyncio.start_server` 函式： ::" - -#: ../../library/asyncio-stream.rst:474 -msgid "" -"import asyncio\n" -"\n" -"async def handle_echo(reader, writer):\n" -" data = await reader.read(100)\n" -" message = data.decode()\n" -" addr = writer.get_extra_info('peername')\n" -"\n" -" print(f\"Received {message!r} from {addr!r}\")\n" -"\n" -" print(f\"Send: {message!r}\")\n" -" writer.write(data)\n" -" await writer.drain()\n" -"\n" -" print(\"Close the connection\")\n" -" writer.close()\n" -" await writer.wait_closed()\n" -"\n" -"async def main():\n" -" server = await asyncio.start_server(\n" -" handle_echo, '127.0.0.1', 8888)\n" -"\n" -" addrs = ', '.join(str(sock.getsockname()) for sock in server.sockets)\n" -" print(f'Serving on {addrs}')\n" -"\n" -" async with server:\n" -" await server.serve_forever()\n" -"\n" -"asyncio.run(main())" -msgstr "" -"import asyncio\n" -"\n" -"async def handle_echo(reader, writer):\n" -" data = await reader.read(100)\n" -" message = data.decode()\n" -" addr = writer.get_extra_info('peername')\n" -"\n" -" print(f\"Received {message!r} from {addr!r}\")\n" -"\n" -" print(f\"Send: {message!r}\")\n" -" writer.write(data)\n" -" await writer.drain()\n" -"\n" -" print(\"Close the connection\")\n" -" writer.close()\n" -" await writer.wait_closed()\n" -"\n" -"async def main():\n" -" server = await asyncio.start_server(\n" -" handle_echo, '127.0.0.1', 8888)\n" -"\n" -" addrs = ', '.join(str(sock.getsockname()) for sock in server.sockets)\n" -" print(f'Serving on {addrs}')\n" -"\n" -" async with server:\n" -" await server.serve_forever()\n" -"\n" -"asyncio.run(main())" - -#: ../../library/asyncio-stream.rst:506 -msgid "" -"The :ref:`TCP echo server protocol " -"` example uses the :meth:`loop." -"create_server` method." -msgstr "" -"使用 :meth:`loop.create_server` 方法的 :ref:`TCP echo 伺服器協定 " -"` 範例。" - -#: ../../library/asyncio-stream.rst:511 -msgid "Get HTTP headers" -msgstr "取得 HTTP 標頭" - -#: ../../library/asyncio-stream.rst:513 -msgid "" -"Simple example querying HTTP headers of the URL passed on the command line::" -msgstr "查詢自命令列傳入之 URL 所帶有 HTTP 標頭的簡單範例： ::" - -#: ../../library/asyncio-stream.rst:515 -msgid "" -"import asyncio\n" -"import urllib.parse\n" -"import sys\n" -"\n" -"async def print_http_headers(url):\n" -" url = urllib.parse.urlsplit(url)\n" -" if url.scheme == 'https':\n" -" reader, writer = await asyncio.open_connection(\n" -" url.hostname, 443, ssl=True)\n" -" else:\n" -" reader, writer = await asyncio.open_connection(\n" -" url.hostname, 80)\n" -"\n" -" query = (\n" -" f\"HEAD {url.path or '/'} HTTP/1.0\\r\\n\"\n" -" f\"Host: {url.hostname}\\r\\n\"\n" -" f\"\\r\\n\"\n" -" )\n" -"\n" -" writer.write(query.encode('latin-1'))\n" -" while True:\n" -" line = await reader.readline()\n" -" if not line:\n" -" break\n" -"\n" -" line = line.decode('latin1').rstrip()\n" -" if line:\n" -" print(f'HTTP header> {line}')\n" -"\n" -" # Ignore the body, close the socket\n" -" writer.close()\n" -" await writer.wait_closed()\n" -"\n" -"url = sys.argv[1]\n" -"asyncio.run(print_http_headers(url))" -msgstr "" - -#: ../../library/asyncio-stream.rst:552 -msgid "Usage::" -msgstr "用法： ::" - -#: ../../library/asyncio-stream.rst:554 -msgid "python example.py http://example.com/path/page.html" -msgstr "python example.py http://example.com/path/page.html" - -#: ../../library/asyncio-stream.rst:556 -msgid "or with HTTPS::" -msgstr "或使用 HTTPS： ::" - -#: ../../library/asyncio-stream.rst:558 -msgid "python example.py https://example.com/path/page.html" -msgstr "python example.py https://example.com/path/page.html" - -#: ../../library/asyncio-stream.rst:564 -msgid "Register an open socket to wait for data using streams" -msgstr "註冊一個使用串流來等待資料的開放 socket" - -#: ../../library/asyncio-stream.rst:566 -msgid "" -"Coroutine waiting until a socket receives data using the :func:" -"`open_connection` function::" -msgstr "" -"等待直到 socket 透過使用 :func:`open_connection` 函式接收到資料的協程： ::" - -#: ../../library/asyncio-stream.rst:569 -msgid "" -"import asyncio\n" -"import socket\n" -"\n" -"async def wait_for_data():\n" -" # Get a reference to the current event loop because\n" -" # we want to access low-level APIs.\n" -" loop = asyncio.get_running_loop()\n" -"\n" -" # Create a pair of connected sockets.\n" -" rsock, wsock = socket.socketpair()\n" -"\n" -" # Register the open socket to wait for data.\n" -" reader, writer = await asyncio.open_connection(sock=rsock)\n" -"\n" -" # Simulate the reception of data from the network\n" -" loop.call_soon(wsock.send, 'abc'.encode())\n" -"\n" -" # Wait for data\n" -" data = await reader.read(100)\n" -"\n" -" # Got data, we are done: close the socket\n" -" print(\"Received:\", data.decode())\n" -" writer.close()\n" -" await writer.wait_closed()\n" -"\n" -" # Close the second socket\n" -" wsock.close()\n" -"\n" -"asyncio.run(wait_for_data())" -msgstr "" - -#: ../../library/asyncio-stream.rst:601 -msgid "" -"The :ref:`register an open socket to wait for data using a protocol " -"` example uses a low-level protocol and " -"the :meth:`loop.create_connection` method." -msgstr "" -"在\\ :ref:`註冊一個開啟的 socket 以等待有使用協定的資料 " -"`\\ 範例中，有使用了低階協定以及 :meth:" -"`loop.create_connection` 方法。" - -#: ../../library/asyncio-stream.rst:605 -msgid "" -"The :ref:`watch a file descriptor for read events " -"` example uses the low-level :meth:`loop." -"add_reader` method to watch a file descriptor." -msgstr "" -"在\\ :ref:`監視檔案描述器以讀取事件 `\\ 範例中，有" -"使用低階的 :meth:`loop.add_reader` 方法來監視檔案描述器。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Adrian Liaw , 2018 +# Matt Wang , 2022-2024 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-10-05 00:16+0000\n" +"PO-Revision-Date: 2022-10-31 16:28+0800\n" +"Last-Translator: Matt Wang \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" +"X-Generator: Poedit 3.1.1\n" + +#: ../../library/asyncio-stream.rst:7 +msgid "Streams" +msgstr "串流" + +#: ../../library/asyncio-stream.rst:9 +msgid "**Source code:** :source:`Lib/asyncio/streams.py`" +msgstr "**原始碼：**\\ :source:`Lib/asyncio/streams.py`" + +#: ../../library/asyncio-stream.rst:13 +msgid "" +"Streams are high-level async/await-ready primitives to work with network " +"connections. Streams allow sending and receiving data without using " +"callbacks or low-level protocols and transports." +msgstr "" +"串流是支援 async/await (async/await-ready) 的高階原始物件 (high-level " +"primitive)，用於處理網路連線。串流不需要使用回呼 (callback) 或低階協定和傳輸 " +"(transport) 就能夠傳送和接收資料。" + +#: ../../library/asyncio-stream.rst:19 +msgid "Here is an example of a TCP echo client written using asyncio streams::" +msgstr "這是一個使用 asyncio 串流編寫的 TCP echo 用戶端範例： ::" + +#: ../../library/asyncio-stream.rst:22 ../../library/asyncio-stream.rst:441 +msgid "" +"import asyncio\n" +"\n" +"async def tcp_echo_client(message):\n" +" reader, writer = await asyncio.open_connection(\n" +" '127.0.0.1', 8888)\n" +"\n" +" print(f'Send: {message!r}')\n" +" writer.write(message.encode())\n" +" await writer.drain()\n" +"\n" +" data = await reader.read(100)\n" +" print(f'Received: {data.decode()!r}')\n" +"\n" +" print('Close the connection')\n" +" writer.close()\n" +" await writer.wait_closed()\n" +"\n" +"asyncio.run(tcp_echo_client('Hello World!'))" +msgstr "" +"import asyncio\n" +"\n" +"async def tcp_echo_client(message):\n" +" reader, writer = await asyncio.open_connection(\n" +" '127.0.0.1', 8888)\n" +"\n" +" print(f'Send: {message!r}')\n" +" writer.write(message.encode())\n" +" await writer.drain()\n" +"\n" +" data = await reader.read(100)\n" +" print(f'Received: {data.decode()!r}')\n" +"\n" +" print('Close the connection')\n" +" writer.close()\n" +" await writer.wait_closed()\n" +"\n" +"asyncio.run(tcp_echo_client('Hello World!'))" + +#: ../../library/asyncio-stream.rst:42 +msgid "See also the `Examples`_ section below." +msgstr "另請參閱下方 `Examples`_ 段落。" + +#: ../../library/asyncio-stream.rst:46 +msgid "Stream Functions" +msgstr "串流函式" + +#: ../../library/asyncio-stream.rst:47 +msgid "" +"The following top-level asyncio functions can be used to create and work " +"with streams:" +msgstr "下面的高階 asyncio 函式可以用來建立和處理串流：" + +#: ../../library/asyncio-stream.rst:59 +msgid "" +"Establish a network connection and return a pair of ``(reader, writer)`` " +"objects." +msgstr "建立網路連線並回傳一對 ``(reader, writer)`` 物件。" + +#: ../../library/asyncio-stream.rst:62 +msgid "" +"The returned *reader* and *writer* objects are instances of :class:" +"`StreamReader` and :class:`StreamWriter` classes." +msgstr "" +"回傳的 *reader* 和 *writer* 物件是 :class:`StreamReader` 和 :class:" +"`StreamWriter` 類別的實例。" + +#: ../../library/asyncio-stream.rst:65 ../../library/asyncio-stream.rst:112 +msgid "" +"*limit* determines the buffer size limit used by the returned :class:" +"`StreamReader` instance. By default the *limit* is set to 64 KiB." +msgstr "" +"*limit* 指定了回傳的 :class:`StreamReader` 實例所使用的緩衝區 (buffer) 大小限" +"制。*limit* 預設為 64 KiB。" + +#: ../../library/asyncio-stream.rst:69 +msgid "" +"The rest of the arguments are passed directly to :meth:`loop." +"create_connection`." +msgstr "其餘的引數會直接傳遞到 :meth:`loop.create_connection`。" + +#: ../../library/asyncio-stream.rst:74 ../../library/asyncio-stream.rst:154 +msgid "" +"The *sock* argument transfers ownership of the socket to the :class:" +"`StreamWriter` created. To close the socket, call its :meth:`~asyncio." +"StreamWriter.close` method." +msgstr "" + +#: ../../library/asyncio-stream.rst:78 +msgid "Added the *ssl_handshake_timeout* parameter." +msgstr "新增 *ssl_handshake_timeout* 參數。" + +#: ../../library/asyncio-stream.rst:81 +msgid "Added the *happy_eyeballs_delay* and *interleave* parameters." +msgstr "新增 *happy_eyeballs_delay* 和 *interleave* 參數。" + +#: ../../library/asyncio-stream.rst:84 ../../library/asyncio-stream.rst:128 +#: ../../library/asyncio-stream.rst:164 ../../library/asyncio-stream.rst:199 +msgid "Removed the *loop* parameter." +msgstr "移除 *loop* 參數。" + +#: ../../library/asyncio-stream.rst:87 ../../library/asyncio-stream.rst:131 +#: ../../library/asyncio-stream.rst:167 ../../library/asyncio-stream.rst:202 +#: ../../library/asyncio-stream.rst:408 +msgid "Added the *ssl_shutdown_timeout* parameter." +msgstr "新增 *ssl_shutdown_timeout* 參數。" + +#: ../../library/asyncio-stream.rst:101 +msgid "Start a socket server." +msgstr "啟動 socket 伺服器。" + +#: ../../library/asyncio-stream.rst:103 +msgid "" +"The *client_connected_cb* callback is called whenever a new client " +"connection is established. It receives a ``(reader, writer)`` pair as two " +"arguments, instances of the :class:`StreamReader` and :class:`StreamWriter` " +"classes." +msgstr "" +"當一個新的用戶端連線被建立時，回呼函式 *client_connected_cb* 就會被呼叫。該函" +"式會接收到一對引數 ``(reader, writer)``，分別為 :class:`StreamReader` 和 :" +"class:`StreamWriter` 的實例。" + +#: ../../library/asyncio-stream.rst:108 +msgid "" +"*client_connected_cb* can be a plain callable or a :ref:`coroutine function " +"`; if it is a coroutine function, it will be automatically " +"scheduled as a :class:`Task`." +msgstr "" +"*client_connected_cb* 既可以是普通的可呼叫物件 (callable)，也可以是一個\\ :" +"ref:`協程函式 `；如果它是一個協程函式，它將自動作為 :class:`Task` " +"來被排程。" + +#: ../../library/asyncio-stream.rst:116 +msgid "" +"The rest of the arguments are passed directly to :meth:`loop.create_server`." +msgstr "剩下的引數將會直接傳遞給 :meth:`loop.create_server`。" + +#: ../../library/asyncio-stream.rst:121 ../../library/asyncio-stream.rst:189 +msgid "" +"The *sock* argument transfers ownership of the socket to the server created. " +"To close the socket, call the server's :meth:`~asyncio.Server.close` method." +msgstr "" + +#: ../../library/asyncio-stream.rst:125 +msgid "Added the *ssl_handshake_timeout* and *start_serving* parameters." +msgstr "新增 *ssl_handshake_timeout* 與 *start_serving* 參數。" + +#: ../../library/asyncio-stream.rst:134 +msgid "Added the *keep_alive* parameter." +msgstr "新增 *keep_alive* 參數。" + +#: ../../library/asyncio-stream.rst:139 +msgid "Unix Sockets" +msgstr "Unix Sockets" + +#: ../../library/asyncio-stream.rst:145 +msgid "" +"Establish a Unix socket connection and return a pair of ``(reader, writer)``." +msgstr "建立一個 Unix socket 連線並回傳一對 ``(reader, writer)``。" + +#: ../../library/asyncio-stream.rst:148 +msgid "Similar to :func:`open_connection` but operates on Unix sockets." +msgstr "與 :func:`open_connection` 相似，但是是操作 Unix sockets。" + +#: ../../library/asyncio-stream.rst:150 +msgid "See also the documentation of :meth:`loop.create_unix_connection`." +msgstr "另請參閱 :meth:`loop.create_unix_connection` 文件。" + +#: ../../library/asyncio-stream.rst:158 ../../library/asyncio-stream.rst:193 +msgid "Availability" +msgstr "可用性" + +#: ../../library/asyncio-stream.rst:160 +msgid "" +"Added the *ssl_handshake_timeout* parameter. The *path* parameter can now be " +"a :term:`path-like object`" +msgstr "" +"新增 *ssl_handshake_timeout* 參數。*path* 參數現在可以是個 :term:`path-like " +"object`" + +#: ../../library/asyncio-stream.rst:177 +msgid "Start a Unix socket server." +msgstr "啟動一個 Unix socket 伺服器。" + +#: ../../library/asyncio-stream.rst:179 +msgid "Similar to :func:`start_server` but works with Unix sockets." +msgstr "與 :func:`start_server` 相似，但會是操作 Unix sockets。" + +#: ../../library/asyncio-stream.rst:181 +msgid "" +"If *cleanup_socket* is true then the Unix socket will automatically be " +"removed from the filesystem when the server is closed, unless the socket has " +"been replaced after the server has been created." +msgstr "" + +#: ../../library/asyncio-stream.rst:185 +msgid "See also the documentation of :meth:`loop.create_unix_server`." +msgstr "另請參閱 :meth:`loop.create_unix_server` 文件。" + +#: ../../library/asyncio-stream.rst:195 +msgid "" +"Added the *ssl_handshake_timeout* and *start_serving* parameters. The *path* " +"parameter can now be a :term:`path-like object`." +msgstr "" +"新增 *ssl_handshake_timeout* 與 *start_serving* 參數。*path* 參數現在可以是" +"個 :term:`path-like object`。" + +#: ../../library/asyncio-stream.rst:205 +msgid "Added the *cleanup_socket* parameter." +msgstr "新增 *cleanup_socket* 參數。" + +#: ../../library/asyncio-stream.rst:210 +msgid "StreamReader" +msgstr "StreamReader" + +#: ../../library/asyncio-stream.rst:214 +msgid "" +"Represents a reader object that provides APIs to read data from the IO " +"stream. As an :term:`asynchronous iterable`, the object supports the :" +"keyword:`async for` statement." +msgstr "" +"表示一個有提供 API 來從 IO 串流中讀取資料的 reader 物件。作為一個 :term:" +"`asynchronous iterable`，此物件支援 :keyword:`async for` 陳述式。" + +#: ../../library/asyncio-stream.rst:218 +msgid "" +"It is not recommended to instantiate *StreamReader* objects directly; use :" +"func:`open_connection` and :func:`start_server` instead." +msgstr "" +"不建議直接實例化 *StreamReader* 物件；使用 :func:`open_connection` 和 :func:" +"`start_server` 會是較好的做法。" + +#: ../../library/asyncio-stream.rst:224 +msgid "Acknowledge the EOF." +msgstr "" + +#: ../../library/asyncio-stream.rst:229 +msgid "Read up to *n* bytes from the stream." +msgstr "從串流中讀取至多 *n* 個位元組的資料。" + +#: ../../library/asyncio-stream.rst:231 +msgid "" +"If *n* is not provided or set to ``-1``, read until EOF, then return all " +"read :class:`bytes`. If EOF was received and the internal buffer is empty, " +"return an empty ``bytes`` object." +msgstr "" +"如果沒有設定 *n* 或是被設為 ``-1``，則會持續讀取直到 EOF，然後回傳所有讀取到" +"的 :class:`bytes`。讀取到 EOF 且內部緩衝區是空的，則回傳一個空的 ``bytes`` 物" +"件。" + +#: ../../library/asyncio-stream.rst:236 +msgid "If *n* is ``0``, return an empty ``bytes`` object immediately." +msgstr "如果 *n* 為 ``0``，則立即回傳一個空的 ``bytes`` 物件。" + +#: ../../library/asyncio-stream.rst:238 +msgid "" +"If *n* is positive, return at most *n* available ``bytes`` as soon as at " +"least 1 byte is available in the internal buffer. If EOF is received before " +"any byte is read, return an empty ``bytes`` object." +msgstr "" + +#: ../../library/asyncio-stream.rst:246 +msgid "" +"Read one line, where \"line\" is a sequence of bytes ending with ``\\n``." +msgstr "讀取一行，其中\"行\"指的是以 ``\\n`` 結尾的位元組序列。" + +#: ../../library/asyncio-stream.rst:249 +msgid "" +"If EOF is received and ``\\n`` was not found, the method returns partially " +"read data." +msgstr "如果讀取到 EOF 而沒有找到 ``\\n``，該方法會回傳部分的已讀取資料。" + +#: ../../library/asyncio-stream.rst:252 +msgid "" +"If EOF is received and the internal buffer is empty, return an empty " +"``bytes`` object." +msgstr "如果讀取到 EOF 且內部緩衝區是空的，則回傳一個空的 ``bytes`` 物件。" + +#: ../../library/asyncio-stream.rst:258 +msgid "Read exactly *n* bytes." +msgstr "讀取剛好 *n* 個位元組。" + +#: ../../library/asyncio-stream.rst:260 +msgid "" +"Raise an :exc:`IncompleteReadError` if EOF is reached before *n* can be " +"read. Use the :attr:`IncompleteReadError.partial` attribute to get the " +"partially read data." +msgstr "" +"如果在讀取完 *n* 個位元組之前讀取到 EOF，則會引發 :exc:" +"`IncompleteReadError`。使用 :attr:`IncompleteReadError.partial` 屬性來取得串" +"流結束前已讀取的部分資料。" + +#: ../../library/asyncio-stream.rst:267 +msgid "Read data from the stream until *separator* is found." +msgstr "從串流中持續讀取資料直到出現 *separator*。" + +#: ../../library/asyncio-stream.rst:269 +msgid "" +"On success, the data and separator will be removed from the internal buffer " +"(consumed). Returned data will include the separator at the end." +msgstr "" +"成功後，資料和 separator（分隔符號）會從內部緩衝區中刪除（或者說是被消費掉 " +"(consumed)）。回傳的資料在末尾會有一個 separator。" + +#: ../../library/asyncio-stream.rst:273 +msgid "" +"If the amount of data read exceeds the configured stream limit, a :exc:" +"`LimitOverrunError` exception is raised, and the data is left in the " +"internal buffer and can be read again." +msgstr "" +"如果讀取的資料量超過了設定的串流限制，將會引發 :exc:`LimitOverrunError` 例" +"外，資料將被留在內部緩衝區中，並可以再次被讀取。" + +#: ../../library/asyncio-stream.rst:277 +msgid "" +"If EOF is reached before the complete separator is found, an :exc:" +"`IncompleteReadError` exception is raised, and the internal buffer is " +"reset. The :attr:`IncompleteReadError.partial` attribute may contain a " +"portion of the separator." +msgstr "" +"如果在完整的 separator 被找到之前就讀取到 EOF，則會引發 :exc:" +"`IncompleteReadError` 例外，且內部緩衝區會被重置。:attr:`IncompleteReadError." +"partial` 屬性可能包含一部分的 separator。" + +#: ../../library/asyncio-stream.rst:282 +msgid "" +"The *separator* may also be a tuple of separators. In this case the return " +"value will be the shortest possible that has any separator as the suffix. " +"For the purposes of :exc:`LimitOverrunError`, the shortest possible " +"separator is considered to be the one that matched." +msgstr "" + +#: ../../library/asyncio-stream.rst:292 +msgid "The *separator* parameter may now be a :class:`tuple` of separators." +msgstr "現在 *separator* 參數可以是一個分隔符號的 :class:`tuple`。" + +#: ../../library/asyncio-stream.rst:297 +msgid "Return ``True`` if the buffer is empty and :meth:`feed_eof` was called." +msgstr "如果緩衝區是空的且 :meth:`feed_eof` 曾被呼叫則回傳 ``True``。" + +#: ../../library/asyncio-stream.rst:302 +msgid "StreamWriter" +msgstr "StreamWriter" + +#: ../../library/asyncio-stream.rst:306 +msgid "" +"Represents a writer object that provides APIs to write data to the IO stream." +msgstr "表示一個有提供 API 來將資料寫入 IO 串流的 writer 物件。" + +#: ../../library/asyncio-stream.rst:309 +msgid "" +"It is not recommended to instantiate *StreamWriter* objects directly; use :" +"func:`open_connection` and :func:`start_server` instead." +msgstr "" +"不建議直接實例化 *StreamWriter* 物件；使用 :func:`open_connection` 和 :func:" +"`start_server` 會是較好的做法。" + +#: ../../library/asyncio-stream.rst:315 +msgid "" +"The method attempts to write the *data* to the underlying socket " +"immediately. If that fails, the data is queued in an internal write buffer " +"until it can be sent." +msgstr "" +"此方法會嘗試立即將 *data* 寫入到底層的 socket。如果失敗，資料會被放到內部寫入" +"緩衝中排隊等待 (queue)，直到它可被發送。" + +#: ../../library/asyncio-stream.rst:319 +msgid "" +"The *data* buffer should be a bytes, bytearray, or C-contiguous one-" +"dimensional memoryview object." +msgstr "" + +#: ../../library/asyncio-stream.rst:322 ../../library/asyncio-stream.rst:335 +msgid "The method should be used along with the ``drain()`` method::" +msgstr "此方法應當與 ``drain()`` 方法一起使用： ::" + +#: ../../library/asyncio-stream.rst:324 +msgid "" +"stream.write(data)\n" +"await stream.drain()" +msgstr "" +"stream.write(data)\n" +"await stream.drain()" + +#: ../../library/asyncio-stream.rst:330 +msgid "" +"The method writes a list (or any iterable) of bytes to the underlying socket " +"immediately. If that fails, the data is queued in an internal write buffer " +"until it can be sent." +msgstr "" +"此方法會立即嘗試將一個位元組 list（或任何可疊代物件 (iterable)）寫入到底層的 " +"socket。如果失敗，資料會被放到內部寫入緩衝中排隊等待，直到它可被發送。" + +#: ../../library/asyncio-stream.rst:337 +msgid "" +"stream.writelines(lines)\n" +"await stream.drain()" +msgstr "" +"stream.writelines(lines)\n" +"await stream.drain()" + +#: ../../library/asyncio-stream.rst:342 +msgid "The method closes the stream and the underlying socket." +msgstr "此方法會關閉串流以及底層的 socket。" + +#: ../../library/asyncio-stream.rst:344 +msgid "" +"The method should be used, though not mandatory, along with the " +"``wait_closed()`` method::" +msgstr "此方法應與 ``wait_closed()`` 方法一起使用，但並非強制： ::" + +#: ../../library/asyncio-stream.rst:347 +msgid "" +"stream.close()\n" +"await stream.wait_closed()" +msgstr "" +"stream.close()\n" +"await stream.wait_closed()" + +#: ../../library/asyncio-stream.rst:352 +msgid "" +"Return ``True`` if the underlying transport supports the :meth:`write_eof` " +"method, ``False`` otherwise." +msgstr "" +"如果底層的傳輸支援 :meth:`write_eof` 方法就回傳 ``True``，否則回傳 " +"``False``。" + +#: ../../library/asyncio-stream.rst:357 +msgid "" +"Close the write end of the stream after the buffered write data is flushed." +msgstr "在已緩衝的寫入資料被清理 (flush) 後關閉串流的寫入端。" + +#: ../../library/asyncio-stream.rst:362 +msgid "Return the underlying asyncio transport." +msgstr "回傳底層的 asyncio 傳輸。" + +#: ../../library/asyncio-stream.rst:366 +msgid "" +"Access optional transport information; see :meth:`BaseTransport." +"get_extra_info` for details." +msgstr "存取可選的傳輸資訊；詳情請見 :meth:`BaseTransport.get_extra_info`。" + +#: ../../library/asyncio-stream.rst:372 +msgid "Wait until it is appropriate to resume writing to the stream. Example::" +msgstr "等待直到可以繼續寫入到串流。範例： ::" + +#: ../../library/asyncio-stream.rst:375 +msgid "" +"writer.write(data)\n" +"await writer.drain()" +msgstr "" +"writer.write(data)\n" +"await writer.drain()" + +#: ../../library/asyncio-stream.rst:378 +msgid "" +"This is a flow control method that interacts with the underlying IO write " +"buffer. When the size of the buffer reaches the high watermark, *drain()* " +"blocks until the size of the buffer is drained down to the low watermark and " +"writing can be resumed. When there is nothing to wait for, the :meth:" +"`drain` returns immediately." +msgstr "" +"這是一個與底層 IO 寫入緩衝區互動的流程控制方法。當緩衝區大小達到最高標記位 " +"(high watermark) 時，*drain()* 會阻塞直到緩衝區大小減少至最低標記位 (low " +"watermark) 以便繼續寫入。當沒有要等待的資料時，:meth:`drain` 會立即回傳。" + +#: ../../library/asyncio-stream.rst:389 +msgid "Upgrade an existing stream-based connection to TLS." +msgstr "將現有的基於串流的連線升級到 TLS。" + +#: ../../library/asyncio-stream.rst:391 +msgid "Parameters:" +msgstr "參數：" + +#: ../../library/asyncio-stream.rst:393 +msgid "*sslcontext*: a configured instance of :class:`~ssl.SSLContext`." +msgstr "*sslcontext*：一個 :class:`~ssl.SSLContext` 的已配置實例。" + +#: ../../library/asyncio-stream.rst:395 +msgid "" +"*server_hostname*: sets or overrides the host name that the target server's " +"certificate will be matched against." +msgstr "*server_hostname*：設定或覆寫將會被目標伺服器憑證比對的主機名稱。" + +#: ../../library/asyncio-stream.rst:398 +msgid "" +"*ssl_handshake_timeout* is the time in seconds to wait for the TLS handshake " +"to complete before aborting the connection. ``60.0`` seconds if ``None`` " +"(default)." +msgstr "" + +#: ../../library/asyncio-stream.rst:402 +msgid "" +"*ssl_shutdown_timeout* is the time in seconds to wait for the SSL shutdown " +"to complete before aborting the connection. ``30.0`` seconds if ``None`` " +"(default)." +msgstr "" + +#: ../../library/asyncio-stream.rst:414 +msgid "" +"Return ``True`` if the stream is closed or in the process of being closed." +msgstr "如果串流已被關閉或正在被關閉則回傳 ``True``。" + +#: ../../library/asyncio-stream.rst:422 +msgid "Wait until the stream is closed." +msgstr "等待直到串流被關閉。" + +#: ../../library/asyncio-stream.rst:424 +msgid "" +"Should be called after :meth:`close` to wait until the underlying connection " +"is closed, ensuring that all data has been flushed before e.g. exiting the " +"program." +msgstr "" +"應當在 :meth:`close` 之後才被呼叫，這會持續等待直到底層的連線被關閉，以確保在" +"這之前（例如在程式退出前）所有資料都已經被清空" + +#: ../../library/asyncio-stream.rst:432 +msgid "Examples" +msgstr "範例" + +#: ../../library/asyncio-stream.rst:437 +msgid "TCP echo client using streams" +msgstr "使用串流的 TCP echo 用戶端" + +#: ../../library/asyncio-stream.rst:439 +msgid "TCP echo client using the :func:`asyncio.open_connection` function::" +msgstr "使用 :func:`asyncio.open_connection` 函式的 TCP echo 用戶端： ::" + +#: ../../library/asyncio-stream.rst:463 +msgid "" +"The :ref:`TCP echo client protocol " +"` example uses the low-level :meth:" +"`loop.create_connection` method." +msgstr "" +"使用低階 :meth:`loop.create_connection` 方法的 :ref:`TCP echo 用戶端協定 " +"`\\ 範例。" + +#: ../../library/asyncio-stream.rst:470 +msgid "TCP echo server using streams" +msgstr "使用串流的 TCP echo 伺服器" + +#: ../../library/asyncio-stream.rst:472 +msgid "TCP echo server using the :func:`asyncio.start_server` function::" +msgstr "TCP echo 伺服器使用 :func:`asyncio.start_server` 函式： ::" + +#: ../../library/asyncio-stream.rst:474 +msgid "" +"import asyncio\n" +"\n" +"async def handle_echo(reader, writer):\n" +" data = await reader.read(100)\n" +" message = data.decode()\n" +" addr = writer.get_extra_info('peername')\n" +"\n" +" print(f\"Received {message!r} from {addr!r}\")\n" +"\n" +" print(f\"Send: {message!r}\")\n" +" writer.write(data)\n" +" await writer.drain()\n" +"\n" +" print(\"Close the connection\")\n" +" writer.close()\n" +" await writer.wait_closed()\n" +"\n" +"async def main():\n" +" server = await asyncio.start_server(\n" +" handle_echo, '127.0.0.1', 8888)\n" +"\n" +" addrs = ', '.join(str(sock.getsockname()) for sock in server.sockets)\n" +" print(f'Serving on {addrs}')\n" +"\n" +" async with server:\n" +" await server.serve_forever()\n" +"\n" +"asyncio.run(main())" +msgstr "" +"import asyncio\n" +"\n" +"async def handle_echo(reader, writer):\n" +" data = await reader.read(100)\n" +" message = data.decode()\n" +" addr = writer.get_extra_info('peername')\n" +"\n" +" print(f\"Received {message!r} from {addr!r}\")\n" +"\n" +" print(f\"Send: {message!r}\")\n" +" writer.write(data)\n" +" await writer.drain()\n" +"\n" +" print(\"Close the connection\")\n" +" writer.close()\n" +" await writer.wait_closed()\n" +"\n" +"async def main():\n" +" server = await asyncio.start_server(\n" +" handle_echo, '127.0.0.1', 8888)\n" +"\n" +" addrs = ', '.join(str(sock.getsockname()) for sock in server.sockets)\n" +" print(f'Serving on {addrs}')\n" +"\n" +" async with server:\n" +" await server.serve_forever()\n" +"\n" +"asyncio.run(main())" + +#: ../../library/asyncio-stream.rst:506 +msgid "" +"The :ref:`TCP echo server protocol " +"` example uses the :meth:`loop." +"create_server` method." +msgstr "" +"使用 :meth:`loop.create_server` 方法的 :ref:`TCP echo 伺服器協定 " +"` 範例。" + +#: ../../library/asyncio-stream.rst:511 +msgid "Get HTTP headers" +msgstr "取得 HTTP 標頭" + +#: ../../library/asyncio-stream.rst:513 +msgid "" +"Simple example querying HTTP headers of the URL passed on the command line::" +msgstr "查詢自命令列傳入之 URL 所帶有 HTTP 標頭的簡單範例： ::" + +#: ../../library/asyncio-stream.rst:515 +msgid "" +"import asyncio\n" +"import urllib.parse\n" +"import sys\n" +"\n" +"async def print_http_headers(url):\n" +" url = urllib.parse.urlsplit(url)\n" +" if url.scheme == 'https':\n" +" reader, writer = await asyncio.open_connection(\n" +" url.hostname, 443, ssl=True)\n" +" else:\n" +" reader, writer = await asyncio.open_connection(\n" +" url.hostname, 80)\n" +"\n" +" query = (\n" +" f\"HEAD {url.path or '/'} HTTP/1.0\\r\\n\"\n" +" f\"Host: {url.hostname}\\r\\n\"\n" +" f\"\\r\\n\"\n" +" )\n" +"\n" +" writer.write(query.encode('latin-1'))\n" +" while True:\n" +" line = await reader.readline()\n" +" if not line:\n" +" break\n" +"\n" +" line = line.decode('latin1').rstrip()\n" +" if line:\n" +" print(f'HTTP header> {line}')\n" +"\n" +" # Ignore the body, close the socket\n" +" writer.close()\n" +" await writer.wait_closed()\n" +"\n" +"url = sys.argv[1]\n" +"asyncio.run(print_http_headers(url))" +msgstr "" + +#: ../../library/asyncio-stream.rst:552 +msgid "Usage::" +msgstr "用法： ::" + +#: ../../library/asyncio-stream.rst:554 +msgid "python example.py http://example.com/path/page.html" +msgstr "python example.py http://example.com/path/page.html" + +#: ../../library/asyncio-stream.rst:556 +msgid "or with HTTPS::" +msgstr "或使用 HTTPS： ::" + +#: ../../library/asyncio-stream.rst:558 +msgid "python example.py https://example.com/path/page.html" +msgstr "python example.py https://example.com/path/page.html" + +#: ../../library/asyncio-stream.rst:564 +msgid "Register an open socket to wait for data using streams" +msgstr "註冊一個使用串流來等待資料的開放 socket" + +#: ../../library/asyncio-stream.rst:566 +msgid "" +"Coroutine waiting until a socket receives data using the :func:" +"`open_connection` function::" +msgstr "" +"等待直到 socket 透過使用 :func:`open_connection` 函式接收到資料的協程： ::" + +#: ../../library/asyncio-stream.rst:569 +msgid "" +"import asyncio\n" +"import socket\n" +"\n" +"async def wait_for_data():\n" +" # Get a reference to the current event loop because\n" +" # we want to access low-level APIs.\n" +" loop = asyncio.get_running_loop()\n" +"\n" +" # Create a pair of connected sockets.\n" +" rsock, wsock = socket.socketpair()\n" +"\n" +" # Register the open socket to wait for data.\n" +" reader, writer = await asyncio.open_connection(sock=rsock)\n" +"\n" +" # Simulate the reception of data from the network\n" +" loop.call_soon(wsock.send, 'abc'.encode())\n" +"\n" +" # Wait for data\n" +" data = await reader.read(100)\n" +"\n" +" # Got data, we are done: close the socket\n" +" print(\"Received:\", data.decode())\n" +" writer.close()\n" +" await writer.wait_closed()\n" +"\n" +" # Close the second socket\n" +" wsock.close()\n" +"\n" +"asyncio.run(wait_for_data())" +msgstr "" + +#: ../../library/asyncio-stream.rst:601 +msgid "" +"The :ref:`register an open socket to wait for data using a protocol " +"` example uses a low-level protocol and " +"the :meth:`loop.create_connection` method." +msgstr "" +"在\\ :ref:`註冊一個開啟的 socket 以等待有使用協定的資料 " +"`\\ 範例中，有使用了低階協定以及 :meth:" +"`loop.create_connection` 方法。" + +#: ../../library/asyncio-stream.rst:605 +msgid "" +"The :ref:`watch a file descriptor for read events " +"` example uses the low-level :meth:`loop." +"add_reader` method to watch a file descriptor." +msgstr "" +"在\\ :ref:`監視檔案描述器以讀取事件 `\\ 範例中，有" +"使用低階的 :meth:`loop.add_reader` 方法來監視檔案描述器。" diff --git a/library/asyncio-subprocess.po b/library/asyncio-subprocess.po index aec812b1ee..3f8f1a4784 100644 --- a/library/asyncio-subprocess.po +++ b/library/asyncio-subprocess.po @@ -1,532 +1,532 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Leon H., 2017 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-07 00:14+0000\n" -"PO-Revision-Date: 2018-05-23 14:39+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/asyncio-subprocess.rst:7 -msgid "Subprocesses" -msgstr "子行程" - -#: ../../library/asyncio-subprocess.rst:9 -msgid "" -"**Source code:** :source:`Lib/asyncio/subprocess.py`, :source:`Lib/asyncio/" -"base_subprocess.py`" -msgstr "" -"**原始碼：**\\ :source:`Lib/asyncio/subprocess.py`、:source:`Lib/asyncio/" -"base_subprocess.py`" - -#: ../../library/asyncio-subprocess.rst:14 -msgid "" -"This section describes high-level async/await asyncio APIs to create and " -"manage subprocesses." -msgstr "" - -#: ../../library/asyncio-subprocess.rst:19 -msgid "" -"Here's an example of how asyncio can run a shell command and obtain its " -"result::" -msgstr "" - -#: ../../library/asyncio-subprocess.rst:22 -msgid "" -"import asyncio\n" -"\n" -"async def run(cmd):\n" -" proc = await asyncio.create_subprocess_shell(\n" -" cmd,\n" -" stdout=asyncio.subprocess.PIPE,\n" -" stderr=asyncio.subprocess.PIPE)\n" -"\n" -" stdout, stderr = await proc.communicate()\n" -"\n" -" print(f'[{cmd!r} exited with {proc.returncode}]')\n" -" if stdout:\n" -" print(f'[stdout]\\n{stdout.decode()}')\n" -" if stderr:\n" -" print(f'[stderr]\\n{stderr.decode()}')\n" -"\n" -"asyncio.run(run('ls /zzz'))" -msgstr "" -"import asyncio\n" -"\n" -"async def run(cmd):\n" -" proc = await asyncio.create_subprocess_shell(\n" -" cmd,\n" -" stdout=asyncio.subprocess.PIPE,\n" -" stderr=asyncio.subprocess.PIPE)\n" -"\n" -" stdout, stderr = await proc.communicate()\n" -"\n" -" print(f'[{cmd!r} exited with {proc.returncode}]')\n" -" if stdout:\n" -" print(f'[stdout]\\n{stdout.decode()}')\n" -" if stderr:\n" -" print(f'[stderr]\\n{stderr.decode()}')\n" -"\n" -"asyncio.run(run('ls /zzz'))" - -#: ../../library/asyncio-subprocess.rst:40 -msgid "will print::" -msgstr "會印出： ::" - -#: ../../library/asyncio-subprocess.rst:42 -msgid "" -"['ls /zzz' exited with 1]\n" -"[stderr]\n" -"ls: /zzz: No such file or directory" -msgstr "" -"['ls /zzz' exited with 1]\n" -"[stderr]\n" -"ls: /zzz: No such file or directory" - -#: ../../library/asyncio-subprocess.rst:46 -msgid "" -"Because all asyncio subprocess functions are asynchronous and asyncio " -"provides many tools to work with such functions, it is easy to execute and " -"monitor multiple subprocesses in parallel. It is indeed trivial to modify " -"the above example to run several commands simultaneously::" -msgstr "" - -#: ../../library/asyncio-subprocess.rst:51 -msgid "" -"async def main():\n" -" await asyncio.gather(\n" -" run('ls /zzz'),\n" -" run('sleep 1; echo \"hello\"'))\n" -"\n" -"asyncio.run(main())" -msgstr "" -"async def main():\n" -" await asyncio.gather(\n" -" run('ls /zzz'),\n" -" run('sleep 1; echo \"hello\"'))\n" -"\n" -"asyncio.run(main())" - -#: ../../library/asyncio-subprocess.rst:58 -msgid "See also the `Examples`_ subsection." -msgstr "另請參閱\\ `Examples`_。" - -#: ../../library/asyncio-subprocess.rst:62 -msgid "Creating Subprocesses" -msgstr "建立子行程" - -#: ../../library/asyncio-subprocess.rst:68 -msgid "Create a subprocess." -msgstr "建立一個子行程。" - -#: ../../library/asyncio-subprocess.rst:70 -#: ../../library/asyncio-subprocess.rst:92 -msgid "" -"The *limit* argument sets the buffer limit for :class:`StreamReader` " -"wrappers for :attr:`~asyncio.subprocess.Process.stdout` and :attr:`~asyncio." -"subprocess.Process.stderr` (if :const:`subprocess.PIPE` is passed to " -"*stdout* and *stderr* arguments)." -msgstr "" - -#: ../../library/asyncio-subprocess.rst:74 -#: ../../library/asyncio-subprocess.rst:96 -msgid "Return a :class:`~asyncio.subprocess.Process` instance." -msgstr "回傳一個 :class:`~asyncio.subprocess.Process` 實例。" - -#: ../../library/asyncio-subprocess.rst:76 -msgid "" -"See the documentation of :meth:`loop.subprocess_exec` for other parameters." -msgstr "" - -#: ../../library/asyncio-subprocess.rst:79 -#: ../../library/asyncio-subprocess.rst:101 -msgid "" -"If the process object is garbage collected while the process is still " -"running, the child process will be killed." -msgstr "" - -#: ../../library/asyncio-subprocess.rst:82 -#: ../../library/asyncio-subprocess.rst:113 -msgid "Removed the *loop* parameter." -msgstr "移除了 *loop* 參數。" - -#: ../../library/asyncio-subprocess.rst:90 -msgid "Run the *cmd* shell command." -msgstr "執行 *cmd* shell 命令。" - -#: ../../library/asyncio-subprocess.rst:98 -msgid "" -"See the documentation of :meth:`loop.subprocess_shell` for other parameters." -msgstr "" - -#: ../../library/asyncio-subprocess.rst:106 -msgid "" -"It is the application's responsibility to ensure that all whitespace and " -"special characters are quoted appropriately to avoid `shell injection " -"`_ " -"vulnerabilities. The :func:`shlex.quote` function can be used to properly " -"escape whitespace and special shell characters in strings that are going to " -"be used to construct shell commands." -msgstr "" - -#: ../../library/asyncio-subprocess.rst:118 -msgid "" -"Subprocesses are available for Windows if a :class:`ProactorEventLoop` is " -"used. See :ref:`Subprocess Support on Windows ` " -"for details." -msgstr "" - -#: ../../library/asyncio-subprocess.rst:124 -msgid "" -"asyncio also has the following *low-level* APIs to work with subprocesses: :" -"meth:`loop.subprocess_exec`, :meth:`loop.subprocess_shell`, :meth:`loop." -"connect_read_pipe`, :meth:`loop.connect_write_pipe`, as well as the :ref:" -"`Subprocess Transports ` and :ref:`Subprocess " -"Protocols `." -msgstr "" - -#: ../../library/asyncio-subprocess.rst:132 -msgid "Constants" -msgstr "常數" - -#: ../../library/asyncio-subprocess.rst:137 -msgid "Can be passed to the *stdin*, *stdout* or *stderr* parameters." -msgstr "" - -#: ../../library/asyncio-subprocess.rst:139 -msgid "" -"If *PIPE* is passed to *stdin* argument, the :attr:`Process.stdin ` attribute will point to a :class:`~asyncio." -"StreamWriter` instance." -msgstr "" - -#: ../../library/asyncio-subprocess.rst:143 -msgid "" -"If *PIPE* is passed to *stdout* or *stderr* arguments, the :attr:`Process." -"stdout ` and :attr:`Process.stderr " -"` attributes will point to :class:" -"`~asyncio.StreamReader` instances." -msgstr "" - -#: ../../library/asyncio-subprocess.rst:151 -msgid "" -"Special value that can be used as the *stderr* argument and indicates that " -"standard error should be redirected into standard output." -msgstr "" - -#: ../../library/asyncio-subprocess.rst:157 -msgid "" -"Special value that can be used as the *stdin*, *stdout* or *stderr* argument " -"to process creation functions. It indicates that the special file :data:`os." -"devnull` will be used for the corresponding subprocess stream." -msgstr "" - -#: ../../library/asyncio-subprocess.rst:163 -msgid "Interacting with Subprocesses" -msgstr "與子行程互動" - -#: ../../library/asyncio-subprocess.rst:165 -msgid "" -"Both :func:`create_subprocess_exec` and :func:`create_subprocess_shell` " -"functions return instances of the *Process* class. *Process* is a high-" -"level wrapper that allows communicating with subprocesses and watching for " -"their completion." -msgstr "" - -#: ../../library/asyncio-subprocess.rst:173 -msgid "" -"An object that wraps OS processes created by the :func:`~asyncio." -"create_subprocess_exec` and :func:`~asyncio.create_subprocess_shell` " -"functions." -msgstr "" - -#: ../../library/asyncio-subprocess.rst:177 -msgid "" -"This class is designed to have a similar API to the :class:`subprocess." -"Popen` class, but there are some notable differences:" -msgstr "" - -#: ../../library/asyncio-subprocess.rst:181 -msgid "" -"unlike Popen, Process instances do not have an equivalent to the :meth:" -"`~subprocess.Popen.poll` method;" -msgstr "" - -#: ../../library/asyncio-subprocess.rst:184 -msgid "" -"the :meth:`~asyncio.subprocess.Process.communicate` and :meth:`~asyncio." -"subprocess.Process.wait` methods don't have a *timeout* parameter: use the :" -"func:`~asyncio.wait_for` function;" -msgstr "" - -#: ../../library/asyncio-subprocess.rst:188 -msgid "" -"the :meth:`Process.wait() ` method is " -"asynchronous, whereas :meth:`subprocess.Popen.wait` method is implemented as " -"a blocking busy loop;" -msgstr "" - -#: ../../library/asyncio-subprocess.rst:192 -msgid "the *universal_newlines* parameter is not supported." -msgstr "" - -#: ../../library/asyncio-subprocess.rst:194 -msgid "This class is :ref:`not thread safe `." -msgstr "" - -#: ../../library/asyncio-subprocess.rst:196 -msgid "" -"See also the :ref:`Subprocess and Threads ` " -"section." -msgstr "" - -#: ../../library/asyncio-subprocess.rst:202 -msgid "Wait for the child process to terminate." -msgstr "" - -#: ../../library/asyncio-subprocess.rst:204 -msgid "Set and return the :attr:`returncode` attribute." -msgstr "" - -#: ../../library/asyncio-subprocess.rst:208 -msgid "" -"This method can deadlock when using ``stdout=PIPE`` or ``stderr=PIPE`` and " -"the child process generates so much output that it blocks waiting for the OS " -"pipe buffer to accept more data. Use the :meth:`communicate` method when " -"using pipes to avoid this condition." -msgstr "" - -#: ../../library/asyncio-subprocess.rst:217 -msgid "Interact with process:" -msgstr "" - -#: ../../library/asyncio-subprocess.rst:219 -msgid "send data to *stdin* (if *input* is not ``None``);" -msgstr "" - -#: ../../library/asyncio-subprocess.rst:220 -msgid "closes *stdin*;" -msgstr "關閉 *stdin*；" - -#: ../../library/asyncio-subprocess.rst:221 -msgid "read data from *stdout* and *stderr*, until EOF is reached;" -msgstr "從 *stdout* 和 *stderr* 讀取資料，直到 EOF；" - -#: ../../library/asyncio-subprocess.rst:222 -msgid "wait for process to terminate." -msgstr "等待行程終止。" - -#: ../../library/asyncio-subprocess.rst:224 -msgid "" -"The optional *input* argument is the data (:class:`bytes` object) that will " -"be sent to the child process." -msgstr "" - -#: ../../library/asyncio-subprocess.rst:227 -msgid "Return a tuple ``(stdout_data, stderr_data)``." -msgstr "回傳一個 ``(stdout_data, stderr_data)`` 元組。" - -#: ../../library/asyncio-subprocess.rst:229 -msgid "" -"If either :exc:`BrokenPipeError` or :exc:`ConnectionResetError` exception is " -"raised when writing *input* into *stdin*, the exception is ignored. This " -"condition occurs when the process exits before all data are written into " -"*stdin*." -msgstr "" - -#: ../../library/asyncio-subprocess.rst:234 -msgid "" -"If it is desired to send data to the process' *stdin*, the process needs to " -"be created with ``stdin=PIPE``. Similarly, to get anything other than " -"``None`` in the result tuple, the process has to be created with " -"``stdout=PIPE`` and/or ``stderr=PIPE`` arguments." -msgstr "" - -#: ../../library/asyncio-subprocess.rst:240 -msgid "" -"Note, that the data read is buffered in memory, so do not use this method if " -"the data size is large or unlimited." -msgstr "" - -#: ../../library/asyncio-subprocess.rst:245 -msgid "*stdin* gets closed when ``input=None`` too." -msgstr "" - -#: ../../library/asyncio-subprocess.rst:249 -msgid "Sends the signal *signal* to the child process." -msgstr "" - -#: ../../library/asyncio-subprocess.rst:253 -msgid "" -"On Windows, :py:const:`~signal.SIGTERM` is an alias for :meth:`terminate`. " -"``CTRL_C_EVENT`` and ``CTRL_BREAK_EVENT`` can be sent to processes started " -"with a *creationflags* parameter which includes ``CREATE_NEW_PROCESS_GROUP``." -msgstr "" - -#: ../../library/asyncio-subprocess.rst:260 -msgid "Stop the child process." -msgstr "" - -#: ../../library/asyncio-subprocess.rst:262 -msgid "" -"On POSIX systems this method sends :py:const:`~signal.SIGTERM` to the child " -"process." -msgstr "" - -#: ../../library/asyncio-subprocess.rst:265 -msgid "" -"On Windows the Win32 API function :c:func:`!TerminateProcess` is called to " -"stop the child process." -msgstr "" - -#: ../../library/asyncio-subprocess.rst:270 -msgid "Kill the child process." -msgstr "" - -#: ../../library/asyncio-subprocess.rst:272 -msgid "" -"On POSIX systems this method sends :py:data:`~signal.SIGKILL` to the child " -"process." -msgstr "" - -#: ../../library/asyncio-subprocess.rst:275 -msgid "On Windows this method is an alias for :meth:`terminate`." -msgstr "" - -#: ../../library/asyncio-subprocess.rst:279 -msgid "" -"Standard input stream (:class:`~asyncio.StreamWriter`) or ``None`` if the " -"process was created with ``stdin=None``." -msgstr "" - -#: ../../library/asyncio-subprocess.rst:284 -msgid "" -"Standard output stream (:class:`~asyncio.StreamReader`) or ``None`` if the " -"process was created with ``stdout=None``." -msgstr "" - -#: ../../library/asyncio-subprocess.rst:289 -msgid "" -"Standard error stream (:class:`~asyncio.StreamReader`) or ``None`` if the " -"process was created with ``stderr=None``." -msgstr "" - -#: ../../library/asyncio-subprocess.rst:294 -msgid "" -"Use the :meth:`communicate` method rather than :attr:`process.stdin.write() " -"`, :attr:`await process.stdout.read() ` or :attr:`await " -"process.stderr.read() `. This avoids deadlocks due to streams " -"pausing reading or writing and blocking the child process." -msgstr "" - -#: ../../library/asyncio-subprocess.rst:303 -msgid "Process identification number (PID)." -msgstr "" - -#: ../../library/asyncio-subprocess.rst:305 -msgid "" -"Note that for processes created by the :func:`~asyncio." -"create_subprocess_shell` function, this attribute is the PID of the spawned " -"shell." -msgstr "" - -#: ../../library/asyncio-subprocess.rst:310 -msgid "Return code of the process when it exits." -msgstr "" - -#: ../../library/asyncio-subprocess.rst:312 -msgid "A ``None`` value indicates that the process has not terminated yet." -msgstr "" - -#: ../../library/asyncio-subprocess.rst:314 -msgid "" -"A negative value ``-N`` indicates that the child was terminated by signal " -"``N`` (POSIX only)." -msgstr "" - -#: ../../library/asyncio-subprocess.rst:321 -msgid "Subprocess and Threads" -msgstr "子行程與執行緒" - -#: ../../library/asyncio-subprocess.rst:323 -msgid "" -"Standard asyncio event loop supports running subprocesses from different " -"threads by default." -msgstr "" - -#: ../../library/asyncio-subprocess.rst:326 -msgid "" -"On Windows subprocesses are provided by :class:`ProactorEventLoop` only " -"(default), :class:`SelectorEventLoop` has no subprocess support." -msgstr "" - -#: ../../library/asyncio-subprocess.rst:329 -msgid "" -"Note that alternative event loop implementations might have own limitations; " -"please refer to their documentation." -msgstr "" - -#: ../../library/asyncio-subprocess.rst:334 -msgid "" -"The :ref:`Concurrency and multithreading in asyncio ` section." -msgstr "" - -#: ../../library/asyncio-subprocess.rst:339 -msgid "Examples" -msgstr "範例" - -#: ../../library/asyncio-subprocess.rst:341 -msgid "" -"An example using the :class:`~asyncio.subprocess.Process` class to control a " -"subprocess and the :class:`StreamReader` class to read from its standard " -"output." -msgstr "" - -#: ../../library/asyncio-subprocess.rst:347 -msgid "" -"The subprocess is created by the :func:`create_subprocess_exec` function::" -msgstr "" - -#: ../../library/asyncio-subprocess.rst:350 -msgid "" -"import asyncio\n" -"import sys\n" -"\n" -"async def get_date():\n" -" code = 'import datetime; print(datetime.datetime.now())'\n" -"\n" -" # Create the subprocess; redirect the standard output\n" -" # into a pipe.\n" -" proc = await asyncio.create_subprocess_exec(\n" -" sys.executable, '-c', code,\n" -" stdout=asyncio.subprocess.PIPE)\n" -"\n" -" # Read one line of output.\n" -" data = await proc.stdout.readline()\n" -" line = data.decode('ascii').rstrip()\n" -"\n" -" # Wait for the subprocess exit.\n" -" await proc.wait()\n" -" return line\n" -"\n" -"date = asyncio.run(get_date())\n" -"print(f\"Current date: {date}\")" -msgstr "" - -#: ../../library/asyncio-subprocess.rst:374 -msgid "" -"See also the :ref:`same example ` written " -"using low-level APIs." -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Leon H., 2017 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-07 00:14+0000\n" +"PO-Revision-Date: 2018-05-23 14:39+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/asyncio-subprocess.rst:7 +msgid "Subprocesses" +msgstr "子行程" + +#: ../../library/asyncio-subprocess.rst:9 +msgid "" +"**Source code:** :source:`Lib/asyncio/subprocess.py`, :source:`Lib/asyncio/" +"base_subprocess.py`" +msgstr "" +"**原始碼：**\\ :source:`Lib/asyncio/subprocess.py`、:source:`Lib/asyncio/" +"base_subprocess.py`" + +#: ../../library/asyncio-subprocess.rst:14 +msgid "" +"This section describes high-level async/await asyncio APIs to create and " +"manage subprocesses." +msgstr "" + +#: ../../library/asyncio-subprocess.rst:19 +msgid "" +"Here's an example of how asyncio can run a shell command and obtain its " +"result::" +msgstr "" + +#: ../../library/asyncio-subprocess.rst:22 +msgid "" +"import asyncio\n" +"\n" +"async def run(cmd):\n" +" proc = await asyncio.create_subprocess_shell(\n" +" cmd,\n" +" stdout=asyncio.subprocess.PIPE,\n" +" stderr=asyncio.subprocess.PIPE)\n" +"\n" +" stdout, stderr = await proc.communicate()\n" +"\n" +" print(f'[{cmd!r} exited with {proc.returncode}]')\n" +" if stdout:\n" +" print(f'[stdout]\\n{stdout.decode()}')\n" +" if stderr:\n" +" print(f'[stderr]\\n{stderr.decode()}')\n" +"\n" +"asyncio.run(run('ls /zzz'))" +msgstr "" +"import asyncio\n" +"\n" +"async def run(cmd):\n" +" proc = await asyncio.create_subprocess_shell(\n" +" cmd,\n" +" stdout=asyncio.subprocess.PIPE,\n" +" stderr=asyncio.subprocess.PIPE)\n" +"\n" +" stdout, stderr = await proc.communicate()\n" +"\n" +" print(f'[{cmd!r} exited with {proc.returncode}]')\n" +" if stdout:\n" +" print(f'[stdout]\\n{stdout.decode()}')\n" +" if stderr:\n" +" print(f'[stderr]\\n{stderr.decode()}')\n" +"\n" +"asyncio.run(run('ls /zzz'))" + +#: ../../library/asyncio-subprocess.rst:40 +msgid "will print::" +msgstr "會印出： ::" + +#: ../../library/asyncio-subprocess.rst:42 +msgid "" +"['ls /zzz' exited with 1]\n" +"[stderr]\n" +"ls: /zzz: No such file or directory" +msgstr "" +"['ls /zzz' exited with 1]\n" +"[stderr]\n" +"ls: /zzz: No such file or directory" + +#: ../../library/asyncio-subprocess.rst:46 +msgid "" +"Because all asyncio subprocess functions are asynchronous and asyncio " +"provides many tools to work with such functions, it is easy to execute and " +"monitor multiple subprocesses in parallel. It is indeed trivial to modify " +"the above example to run several commands simultaneously::" +msgstr "" + +#: ../../library/asyncio-subprocess.rst:51 +msgid "" +"async def main():\n" +" await asyncio.gather(\n" +" run('ls /zzz'),\n" +" run('sleep 1; echo \"hello\"'))\n" +"\n" +"asyncio.run(main())" +msgstr "" +"async def main():\n" +" await asyncio.gather(\n" +" run('ls /zzz'),\n" +" run('sleep 1; echo \"hello\"'))\n" +"\n" +"asyncio.run(main())" + +#: ../../library/asyncio-subprocess.rst:58 +msgid "See also the `Examples`_ subsection." +msgstr "另請參閱\\ `Examples`_。" + +#: ../../library/asyncio-subprocess.rst:62 +msgid "Creating Subprocesses" +msgstr "建立子行程" + +#: ../../library/asyncio-subprocess.rst:68 +msgid "Create a subprocess." +msgstr "建立一個子行程。" + +#: ../../library/asyncio-subprocess.rst:70 +#: ../../library/asyncio-subprocess.rst:92 +msgid "" +"The *limit* argument sets the buffer limit for :class:`StreamReader` " +"wrappers for :attr:`~asyncio.subprocess.Process.stdout` and :attr:`~asyncio." +"subprocess.Process.stderr` (if :const:`subprocess.PIPE` is passed to " +"*stdout* and *stderr* arguments)." +msgstr "" + +#: ../../library/asyncio-subprocess.rst:74 +#: ../../library/asyncio-subprocess.rst:96 +msgid "Return a :class:`~asyncio.subprocess.Process` instance." +msgstr "回傳一個 :class:`~asyncio.subprocess.Process` 實例。" + +#: ../../library/asyncio-subprocess.rst:76 +msgid "" +"See the documentation of :meth:`loop.subprocess_exec` for other parameters." +msgstr "" + +#: ../../library/asyncio-subprocess.rst:79 +#: ../../library/asyncio-subprocess.rst:101 +msgid "" +"If the process object is garbage collected while the process is still " +"running, the child process will be killed." +msgstr "" + +#: ../../library/asyncio-subprocess.rst:82 +#: ../../library/asyncio-subprocess.rst:113 +msgid "Removed the *loop* parameter." +msgstr "移除了 *loop* 參數。" + +#: ../../library/asyncio-subprocess.rst:90 +msgid "Run the *cmd* shell command." +msgstr "執行 *cmd* shell 命令。" + +#: ../../library/asyncio-subprocess.rst:98 +msgid "" +"See the documentation of :meth:`loop.subprocess_shell` for other parameters." +msgstr "" + +#: ../../library/asyncio-subprocess.rst:106 +msgid "" +"It is the application's responsibility to ensure that all whitespace and " +"special characters are quoted appropriately to avoid `shell injection " +"`_ " +"vulnerabilities. The :func:`shlex.quote` function can be used to properly " +"escape whitespace and special shell characters in strings that are going to " +"be used to construct shell commands." +msgstr "" + +#: ../../library/asyncio-subprocess.rst:118 +msgid "" +"Subprocesses are available for Windows if a :class:`ProactorEventLoop` is " +"used. See :ref:`Subprocess Support on Windows ` " +"for details." +msgstr "" + +#: ../../library/asyncio-subprocess.rst:124 +msgid "" +"asyncio also has the following *low-level* APIs to work with subprocesses: :" +"meth:`loop.subprocess_exec`, :meth:`loop.subprocess_shell`, :meth:`loop." +"connect_read_pipe`, :meth:`loop.connect_write_pipe`, as well as the :ref:" +"`Subprocess Transports ` and :ref:`Subprocess " +"Protocols `." +msgstr "" + +#: ../../library/asyncio-subprocess.rst:132 +msgid "Constants" +msgstr "常數" + +#: ../../library/asyncio-subprocess.rst:137 +msgid "Can be passed to the *stdin*, *stdout* or *stderr* parameters." +msgstr "" + +#: ../../library/asyncio-subprocess.rst:139 +msgid "" +"If *PIPE* is passed to *stdin* argument, the :attr:`Process.stdin ` attribute will point to a :class:`~asyncio." +"StreamWriter` instance." +msgstr "" + +#: ../../library/asyncio-subprocess.rst:143 +msgid "" +"If *PIPE* is passed to *stdout* or *stderr* arguments, the :attr:`Process." +"stdout ` and :attr:`Process.stderr " +"` attributes will point to :class:" +"`~asyncio.StreamReader` instances." +msgstr "" + +#: ../../library/asyncio-subprocess.rst:151 +msgid "" +"Special value that can be used as the *stderr* argument and indicates that " +"standard error should be redirected into standard output." +msgstr "" + +#: ../../library/asyncio-subprocess.rst:157 +msgid "" +"Special value that can be used as the *stdin*, *stdout* or *stderr* argument " +"to process creation functions. It indicates that the special file :data:`os." +"devnull` will be used for the corresponding subprocess stream." +msgstr "" + +#: ../../library/asyncio-subprocess.rst:163 +msgid "Interacting with Subprocesses" +msgstr "與子行程互動" + +#: ../../library/asyncio-subprocess.rst:165 +msgid "" +"Both :func:`create_subprocess_exec` and :func:`create_subprocess_shell` " +"functions return instances of the *Process* class. *Process* is a high-" +"level wrapper that allows communicating with subprocesses and watching for " +"their completion." +msgstr "" + +#: ../../library/asyncio-subprocess.rst:173 +msgid "" +"An object that wraps OS processes created by the :func:`~asyncio." +"create_subprocess_exec` and :func:`~asyncio.create_subprocess_shell` " +"functions." +msgstr "" + +#: ../../library/asyncio-subprocess.rst:177 +msgid "" +"This class is designed to have a similar API to the :class:`subprocess." +"Popen` class, but there are some notable differences:" +msgstr "" + +#: ../../library/asyncio-subprocess.rst:181 +msgid "" +"unlike Popen, Process instances do not have an equivalent to the :meth:" +"`~subprocess.Popen.poll` method;" +msgstr "" + +#: ../../library/asyncio-subprocess.rst:184 +msgid "" +"the :meth:`~asyncio.subprocess.Process.communicate` and :meth:`~asyncio." +"subprocess.Process.wait` methods don't have a *timeout* parameter: use the :" +"func:`~asyncio.wait_for` function;" +msgstr "" + +#: ../../library/asyncio-subprocess.rst:188 +msgid "" +"the :meth:`Process.wait() ` method is " +"asynchronous, whereas :meth:`subprocess.Popen.wait` method is implemented as " +"a blocking busy loop;" +msgstr "" + +#: ../../library/asyncio-subprocess.rst:192 +msgid "the *universal_newlines* parameter is not supported." +msgstr "" + +#: ../../library/asyncio-subprocess.rst:194 +msgid "This class is :ref:`not thread safe `." +msgstr "" + +#: ../../library/asyncio-subprocess.rst:196 +msgid "" +"See also the :ref:`Subprocess and Threads ` " +"section." +msgstr "" + +#: ../../library/asyncio-subprocess.rst:202 +msgid "Wait for the child process to terminate." +msgstr "" + +#: ../../library/asyncio-subprocess.rst:204 +msgid "Set and return the :attr:`returncode` attribute." +msgstr "" + +#: ../../library/asyncio-subprocess.rst:208 +msgid "" +"This method can deadlock when using ``stdout=PIPE`` or ``stderr=PIPE`` and " +"the child process generates so much output that it blocks waiting for the OS " +"pipe buffer to accept more data. Use the :meth:`communicate` method when " +"using pipes to avoid this condition." +msgstr "" + +#: ../../library/asyncio-subprocess.rst:217 +msgid "Interact with process:" +msgstr "" + +#: ../../library/asyncio-subprocess.rst:219 +msgid "send data to *stdin* (if *input* is not ``None``);" +msgstr "" + +#: ../../library/asyncio-subprocess.rst:220 +msgid "closes *stdin*;" +msgstr "關閉 *stdin*；" + +#: ../../library/asyncio-subprocess.rst:221 +msgid "read data from *stdout* and *stderr*, until EOF is reached;" +msgstr "從 *stdout* 和 *stderr* 讀取資料，直到 EOF；" + +#: ../../library/asyncio-subprocess.rst:222 +msgid "wait for process to terminate." +msgstr "等待行程終止。" + +#: ../../library/asyncio-subprocess.rst:224 +msgid "" +"The optional *input* argument is the data (:class:`bytes` object) that will " +"be sent to the child process." +msgstr "" + +#: ../../library/asyncio-subprocess.rst:227 +msgid "Return a tuple ``(stdout_data, stderr_data)``." +msgstr "回傳一個 ``(stdout_data, stderr_data)`` 元組。" + +#: ../../library/asyncio-subprocess.rst:229 +msgid "" +"If either :exc:`BrokenPipeError` or :exc:`ConnectionResetError` exception is " +"raised when writing *input* into *stdin*, the exception is ignored. This " +"condition occurs when the process exits before all data are written into " +"*stdin*." +msgstr "" + +#: ../../library/asyncio-subprocess.rst:234 +msgid "" +"If it is desired to send data to the process' *stdin*, the process needs to " +"be created with ``stdin=PIPE``. Similarly, to get anything other than " +"``None`` in the result tuple, the process has to be created with " +"``stdout=PIPE`` and/or ``stderr=PIPE`` arguments." +msgstr "" + +#: ../../library/asyncio-subprocess.rst:240 +msgid "" +"Note, that the data read is buffered in memory, so do not use this method if " +"the data size is large or unlimited." +msgstr "" + +#: ../../library/asyncio-subprocess.rst:245 +msgid "*stdin* gets closed when ``input=None`` too." +msgstr "" + +#: ../../library/asyncio-subprocess.rst:249 +msgid "Sends the signal *signal* to the child process." +msgstr "" + +#: ../../library/asyncio-subprocess.rst:253 +msgid "" +"On Windows, :py:const:`~signal.SIGTERM` is an alias for :meth:`terminate`. " +"``CTRL_C_EVENT`` and ``CTRL_BREAK_EVENT`` can be sent to processes started " +"with a *creationflags* parameter which includes ``CREATE_NEW_PROCESS_GROUP``." +msgstr "" + +#: ../../library/asyncio-subprocess.rst:260 +msgid "Stop the child process." +msgstr "" + +#: ../../library/asyncio-subprocess.rst:262 +msgid "" +"On POSIX systems this method sends :py:const:`~signal.SIGTERM` to the child " +"process." +msgstr "" + +#: ../../library/asyncio-subprocess.rst:265 +msgid "" +"On Windows the Win32 API function :c:func:`!TerminateProcess` is called to " +"stop the child process." +msgstr "" + +#: ../../library/asyncio-subprocess.rst:270 +msgid "Kill the child process." +msgstr "" + +#: ../../library/asyncio-subprocess.rst:272 +msgid "" +"On POSIX systems this method sends :py:data:`~signal.SIGKILL` to the child " +"process." +msgstr "" + +#: ../../library/asyncio-subprocess.rst:275 +msgid "On Windows this method is an alias for :meth:`terminate`." +msgstr "" + +#: ../../library/asyncio-subprocess.rst:279 +msgid "" +"Standard input stream (:class:`~asyncio.StreamWriter`) or ``None`` if the " +"process was created with ``stdin=None``." +msgstr "" + +#: ../../library/asyncio-subprocess.rst:284 +msgid "" +"Standard output stream (:class:`~asyncio.StreamReader`) or ``None`` if the " +"process was created with ``stdout=None``." +msgstr "" + +#: ../../library/asyncio-subprocess.rst:289 +msgid "" +"Standard error stream (:class:`~asyncio.StreamReader`) or ``None`` if the " +"process was created with ``stderr=None``." +msgstr "" + +#: ../../library/asyncio-subprocess.rst:294 +msgid "" +"Use the :meth:`communicate` method rather than :attr:`process.stdin.write() " +"`, :attr:`await process.stdout.read() ` or :attr:`await " +"process.stderr.read() `. This avoids deadlocks due to streams " +"pausing reading or writing and blocking the child process." +msgstr "" + +#: ../../library/asyncio-subprocess.rst:303 +msgid "Process identification number (PID)." +msgstr "" + +#: ../../library/asyncio-subprocess.rst:305 +msgid "" +"Note that for processes created by the :func:`~asyncio." +"create_subprocess_shell` function, this attribute is the PID of the spawned " +"shell." +msgstr "" + +#: ../../library/asyncio-subprocess.rst:310 +msgid "Return code of the process when it exits." +msgstr "" + +#: ../../library/asyncio-subprocess.rst:312 +msgid "A ``None`` value indicates that the process has not terminated yet." +msgstr "" + +#: ../../library/asyncio-subprocess.rst:314 +msgid "" +"A negative value ``-N`` indicates that the child was terminated by signal " +"``N`` (POSIX only)." +msgstr "" + +#: ../../library/asyncio-subprocess.rst:321 +msgid "Subprocess and Threads" +msgstr "子行程與執行緒" + +#: ../../library/asyncio-subprocess.rst:323 +msgid "" +"Standard asyncio event loop supports running subprocesses from different " +"threads by default." +msgstr "" + +#: ../../library/asyncio-subprocess.rst:326 +msgid "" +"On Windows subprocesses are provided by :class:`ProactorEventLoop` only " +"(default), :class:`SelectorEventLoop` has no subprocess support." +msgstr "" + +#: ../../library/asyncio-subprocess.rst:329 +msgid "" +"Note that alternative event loop implementations might have own limitations; " +"please refer to their documentation." +msgstr "" + +#: ../../library/asyncio-subprocess.rst:334 +msgid "" +"The :ref:`Concurrency and multithreading in asyncio ` section." +msgstr "" + +#: ../../library/asyncio-subprocess.rst:339 +msgid "Examples" +msgstr "範例" + +#: ../../library/asyncio-subprocess.rst:341 +msgid "" +"An example using the :class:`~asyncio.subprocess.Process` class to control a " +"subprocess and the :class:`StreamReader` class to read from its standard " +"output." +msgstr "" + +#: ../../library/asyncio-subprocess.rst:347 +msgid "" +"The subprocess is created by the :func:`create_subprocess_exec` function::" +msgstr "" + +#: ../../library/asyncio-subprocess.rst:350 +msgid "" +"import asyncio\n" +"import sys\n" +"\n" +"async def get_date():\n" +" code = 'import datetime; print(datetime.datetime.now())'\n" +"\n" +" # Create the subprocess; redirect the standard output\n" +" # into a pipe.\n" +" proc = await asyncio.create_subprocess_exec(\n" +" sys.executable, '-c', code,\n" +" stdout=asyncio.subprocess.PIPE)\n" +"\n" +" # Read one line of output.\n" +" data = await proc.stdout.readline()\n" +" line = data.decode('ascii').rstrip()\n" +"\n" +" # Wait for the subprocess exit.\n" +" await proc.wait()\n" +" return line\n" +"\n" +"date = asyncio.run(get_date())\n" +"print(f\"Current date: {date}\")" +msgstr "" + +#: ../../library/asyncio-subprocess.rst:374 +msgid "" +"See also the :ref:`same example ` written " +"using low-level APIs." +msgstr "" diff --git a/library/asyncio-sync.po b/library/asyncio-sync.po index 4d524fee3b..15960bab33 100644 --- a/library/asyncio-sync.po +++ b/library/asyncio-sync.po @@ -1,676 +1,676 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-08-17 00:18+0000\n" -"PO-Revision-Date: 2022-02-09 19:27+0800\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" -"X-Generator: Poedit 3.0.1\n" - -#: ../../library/asyncio-sync.rst:7 -msgid "Synchronization Primitives" -msgstr "同步化原始物件 (Synchronization Primitives)" - -#: ../../library/asyncio-sync.rst:9 -msgid "**Source code:** :source:`Lib/asyncio/locks.py`" -msgstr "**原始碼：**\\ :source:`Lib/asyncio/locks.py`" - -#: ../../library/asyncio-sync.rst:13 -msgid "" -"asyncio synchronization primitives are designed to be similar to those of " -"the :mod:`threading` module with two important caveats:" -msgstr "" -"asyncio 的同步化原始物件被設計成和那些 :mod:`threading` 模組 (module) 中的同" -"名物件相似，但有兩個重要的限制條件：" - -#: ../../library/asyncio-sync.rst:16 -msgid "" -"asyncio primitives are not thread-safe, therefore they should not be used " -"for OS thread synchronization (use :mod:`threading` for that);" -msgstr "" -"asyncio 原始物件並不支援執行緒安全 (thread-safe)，因此他們不可被用於 OS 執行" -"緒同步化（請改用 :mod:`threading`\\ ）；" - -#: ../../library/asyncio-sync.rst:20 -msgid "" -"methods of these synchronization primitives do not accept the *timeout* " -"argument; use the :func:`asyncio.wait_for` function to perform operations " -"with timeouts." -msgstr "" -"這些同步化原始物件的方法 (method) 並不接受 *timeout* 引數；要達成有超時 " -"(timeout) 設定的操作請改用 :func:`asyncio.wait_for` 函式。" - -#: ../../library/asyncio-sync.rst:24 -msgid "asyncio has the following basic synchronization primitives:" -msgstr "asyncio 有以下基礎同步化原始物件：" - -#: ../../library/asyncio-sync.rst:26 -msgid ":class:`Lock`" -msgstr ":class:`Lock`" - -#: ../../library/asyncio-sync.rst:27 -msgid ":class:`Event`" -msgstr ":class:`Event`" - -#: ../../library/asyncio-sync.rst:28 -msgid ":class:`Condition`" -msgstr ":class:`Condition`" - -#: ../../library/asyncio-sync.rst:29 -msgid ":class:`Semaphore`" -msgstr ":class:`Semaphore`" - -#: ../../library/asyncio-sync.rst:30 -msgid ":class:`BoundedSemaphore`" -msgstr ":class:`BoundedSemaphore`" - -#: ../../library/asyncio-sync.rst:31 -msgid ":class:`Barrier`" -msgstr ":class:`Barrier`" - -#: ../../library/asyncio-sync.rst:38 -msgid "Lock" -msgstr "Lock" - -#: ../../library/asyncio-sync.rst:42 -msgid "Implements a mutex lock for asyncio tasks. Not thread-safe." -msgstr "" -"實作了一個給 asyncio 任務 (task) 用的互斥鎖 (mutex lock)。不支援執行緒安全。" - -#: ../../library/asyncio-sync.rst:44 -msgid "" -"An asyncio lock can be used to guarantee exclusive access to a shared " -"resource." -msgstr "一個 asyncio 的鎖可以用來確保一個共享資源的存取權被獨佔。" - -#: ../../library/asyncio-sync.rst:47 -msgid "The preferred way to use a Lock is an :keyword:`async with` statement::" -msgstr "使用 Lock 的推薦方式是透過 :keyword:`async with` 陳述式： ::" - -#: ../../library/asyncio-sync.rst:50 -msgid "" -"lock = asyncio.Lock()\n" -"\n" -"# ... later\n" -"async with lock:\n" -" # access shared state" -msgstr "" - -#: ../../library/asyncio-sync.rst:56 ../../library/asyncio-sync.rst:201 -#: ../../library/asyncio-sync.rst:309 -msgid "which is equivalent to::" -msgstr "這等價於： ::" - -#: ../../library/asyncio-sync.rst:58 -msgid "" -"lock = asyncio.Lock()\n" -"\n" -"# ... later\n" -"await lock.acquire()\n" -"try:\n" -" # access shared state\n" -"finally:\n" -" lock.release()" -msgstr "" - -#: ../../library/asyncio-sync.rst:67 ../../library/asyncio-sync.rst:113 -#: ../../library/asyncio-sync.rst:189 ../../library/asyncio-sync.rst:297 -#: ../../library/asyncio-sync.rst:353 -msgid "Removed the *loop* parameter." -msgstr "移除 ``loop`` 參數。" - -#: ../../library/asyncio-sync.rst:73 -msgid "Acquire the lock." -msgstr "獲得鎖。" - -#: ../../library/asyncio-sync.rst:75 -msgid "" -"This method waits until the lock is *unlocked*, sets it to *locked* and " -"returns ``True``." -msgstr "" -"此方法會持續等待直到鎖的狀態成為 *unlocked*，並將其設置為 *locked* 和回傳 " -"``True``。" - -#: ../../library/asyncio-sync.rst:78 -msgid "" -"When more than one coroutine is blocked in :meth:`acquire` waiting for the " -"lock to be unlocked, only one coroutine eventually proceeds." -msgstr "" -"當多於一個的協程 (coroutine) 在 :meth:`acquire` 中等待解鎖而被阻塞，最終只會" -"有其中的一個被處理。" - -#: ../../library/asyncio-sync.rst:82 -msgid "" -"Acquiring a lock is *fair*: the coroutine that proceeds will be the first " -"coroutine that started waiting on the lock." -msgstr "" -"鎖的取得方式是\\ *公平*\\ 的：被處理的協程會是最早開始等待解鎖的那一個。" - -#: ../../library/asyncio-sync.rst:87 -msgid "Release the lock." -msgstr "釋放鎖。" - -#: ../../library/asyncio-sync.rst:89 -msgid "When the lock is *locked*, reset it to *unlocked* and return." -msgstr "如果鎖的狀態為 *locked* 則將其重置為 *unlocked* 並回傳。" - -#: ../../library/asyncio-sync.rst:91 -msgid "If the lock is *unlocked*, a :exc:`RuntimeError` is raised." -msgstr "如果鎖的狀態為 *unlocked* 則 :exc:`RuntimeError` 會被引發。" - -#: ../../library/asyncio-sync.rst:95 -msgid "Return ``True`` if the lock is *locked*." -msgstr "如果鎖的狀態為 *locked* 則回傳 ``True``。" - -#: ../../library/asyncio-sync.rst:99 -msgid "Event" -msgstr "Event" - -#: ../../library/asyncio-sync.rst:103 -msgid "An event object. Not thread-safe." -msgstr "一個事件 (event) 物件。不支援執行緒安全。" - -#: ../../library/asyncio-sync.rst:105 -msgid "" -"An asyncio event can be used to notify multiple asyncio tasks that some " -"event has happened." -msgstr "" -"一個 asyncio 事件可以被用於通知多個有發生某些事件於其中的 asyncio 任務。" - -#: ../../library/asyncio-sync.rst:108 -msgid "" -"An Event object manages an internal flag that can be set to *true* with the :" -"meth:`~Event.set` method and reset to *false* with the :meth:`clear` " -"method. The :meth:`~Event.wait` method blocks until the flag is set to " -"*true*. The flag is set to *false* initially." -msgstr "" -"一個 Event 物件會管理一個內部旗標 (flag)，它可以透過 :meth:`~Event.set` 方法" -"來被設為 *true* 並透過 :meth:`clear` 方法來重置為 *false*。:meth:`~Event." -"wait` 方法會被阻塞 (block) 直到該旗標被設為 *true*。該旗標初始設置為 " -"*false*。" - -#: ../../library/asyncio-sync.rst:118 ../../library/asyncio-sync.rst:377 -msgid "Example::" -msgstr "範例： ::" - -#: ../../library/asyncio-sync.rst:120 -msgid "" -"async def waiter(event):\n" -" print('waiting for it ...')\n" -" await event.wait()\n" -" print('... got it!')\n" -"\n" -"async def main():\n" -" # Create an Event object.\n" -" event = asyncio.Event()\n" -"\n" -" # Spawn a Task to wait until 'event' is set.\n" -" waiter_task = asyncio.create_task(waiter(event))\n" -"\n" -" # Sleep for 1 second and set the event.\n" -" await asyncio.sleep(1)\n" -" event.set()\n" -"\n" -" # Wait until the waiter task is finished.\n" -" await waiter_task\n" -"\n" -"asyncio.run(main())" -msgstr "" - -#: ../../library/asyncio-sync.rst:144 -msgid "Wait until the event is set." -msgstr "持續等待直到事件被設置。" - -#: ../../library/asyncio-sync.rst:146 -msgid "" -"If the event is set, return ``True`` immediately. Otherwise block until " -"another task calls :meth:`~Event.set`." -msgstr "" -"如果事件有被設置則立刻回傳 ``True``。否則持續阻塞直到另一個任務呼叫 :meth:" -"`~Event.set`。" - -#: ../../library/asyncio-sync.rst:151 -msgid "Set the event." -msgstr "設置事件。" - -#: ../../library/asyncio-sync.rst:153 -msgid "All tasks waiting for event to be set will be immediately awakened." -msgstr "所有正在等待事件被設置的任務會立即被喚醒。" - -#: ../../library/asyncio-sync.rst:158 -msgid "Clear (unset) the event." -msgstr "清除（還原）事件。" - -#: ../../library/asyncio-sync.rst:160 -msgid "" -"Subsequent tasks awaiting on :meth:`~Event.wait` will now block until the :" -"meth:`~Event.set` method is called again." -msgstr "" -"正透過 :meth:`~Event.wait` 等待的後續 Tasks 現在會持續阻塞直到 :meth:`~Event." -"set` 方法再次被呼叫。" - -#: ../../library/asyncio-sync.rst:165 -msgid "Return ``True`` if the event is set." -msgstr "如果事件有被設置則回傳 ``True``。" - -#: ../../library/asyncio-sync.rst:169 -msgid "Condition" -msgstr "Condition" - -#: ../../library/asyncio-sync.rst:173 -msgid "A Condition object. Not thread-safe." -msgstr "一個條件 (codition) 物件。不支援執行緒安全。" - -#: ../../library/asyncio-sync.rst:175 -msgid "" -"An asyncio condition primitive can be used by a task to wait for some event " -"to happen and then get exclusive access to a shared resource." -msgstr "" -"一個 asyncio 條件原始物件可以被任務用來等待某事件發生，並獲得一個共享資源的獨" -"佔存取權。" - -#: ../../library/asyncio-sync.rst:179 -msgid "" -"In essence, a Condition object combines the functionality of an :class:" -"`Event` and a :class:`Lock`. It is possible to have multiple Condition " -"objects share one Lock, which allows coordinating exclusive access to a " -"shared resource between different tasks interested in particular states of " -"that shared resource." -msgstr "" -"本質上，一個 Condition 物件會結合 :class:`Event` 和 :class:`Lock` 的功能。多" -"個 Condition 物件共享一個 Lock 是有可能發生的，這能夠協調關注同一共享資源的不" -"同狀態以取得其獨佔存取權的多個任務。" - -#: ../../library/asyncio-sync.rst:185 -msgid "" -"The optional *lock* argument must be a :class:`Lock` object or ``None``. In " -"the latter case a new Lock object is created automatically." -msgstr "" -"可選的 *lock* 引數必須是一個 :class:`Lock` 物件或者為 ``None``。如為後者則一" -"個新的 Lock 物件會被自動建立。" - -#: ../../library/asyncio-sync.rst:192 -msgid "" -"The preferred way to use a Condition is an :keyword:`async with` statement::" -msgstr "使用 Condition 的推薦方式是透過 :keyword:`async with` 陳述式： ::" - -#: ../../library/asyncio-sync.rst:195 -msgid "" -"cond = asyncio.Condition()\n" -"\n" -"# ... later\n" -"async with cond:\n" -" await cond.wait()" -msgstr "" - -#: ../../library/asyncio-sync.rst:203 -msgid "" -"cond = asyncio.Condition()\n" -"\n" -"# ... later\n" -"await cond.acquire()\n" -"try:\n" -" await cond.wait()\n" -"finally:\n" -" cond.release()" -msgstr "" - -#: ../../library/asyncio-sync.rst:215 -msgid "Acquire the underlying lock." -msgstr "取得底層的鎖。" - -#: ../../library/asyncio-sync.rst:217 -msgid "" -"This method waits until the underlying lock is *unlocked*, sets it to " -"*locked* and returns ``True``." -msgstr "" -"此方法會持續等待直到底層的鎖為 *unlocked*，並將其設為 *locked* 並回傳 " -"``True``。" - -#: ../../library/asyncio-sync.rst:222 -msgid "" -"Wake up *n* tasks (1 by default) waiting on this condition. If fewer than " -"*n* tasks are waiting they are all awakened." -msgstr "" -"喚醒至多 *n* 個正在等待此條件的任務（預設為 1），如果少於 *n* 個任務則全部被" -"喚醒。" - -#: ../../library/asyncio-sync.rst:225 ../../library/asyncio-sync.rst:240 -msgid "" -"The lock must be acquired before this method is called and released shortly " -"after. If called with an *unlocked* lock a :exc:`RuntimeError` error is " -"raised." -msgstr "" -"在此方法被呼叫前必須先獲得鎖，並在之後立刻將其釋放。如果呼叫於一個 " -"*unlocked* 的鎖則 :exc:`RuntimeError` 錯誤會被引發。" - -#: ../../library/asyncio-sync.rst:231 -msgid "Return ``True`` if the underlying lock is acquired." -msgstr "如果已取得底層的鎖則回傳 ``True``。" - -#: ../../library/asyncio-sync.rst:235 -msgid "Wake up all tasks waiting on this condition." -msgstr "喚醒所有正在等待此條件的任務。" - -#: ../../library/asyncio-sync.rst:237 -msgid "This method acts like :meth:`notify`, but wakes up all waiting tasks." -msgstr "這個方法的行為就像 :meth:`notify`，但會喚醒所有正在等待的任務。" - -#: ../../library/asyncio-sync.rst:246 -msgid "Release the underlying lock." -msgstr "釋放底層的鎖。" - -#: ../../library/asyncio-sync.rst:248 -msgid "When invoked on an unlocked lock, a :exc:`RuntimeError` is raised." -msgstr "當叫用於一個未被解開的鎖之上時，會引發一個 :exc:`RuntimeError`。" - -#: ../../library/asyncio-sync.rst:254 -msgid "Wait until notified." -msgstr "持續等待直到被通知 (notify)。" - -#: ../../library/asyncio-sync.rst:256 -msgid "" -"If the calling task has not acquired the lock when this method is called, a :" -"exc:`RuntimeError` is raised." -msgstr "" -"當此方法被呼叫時，如果呼叫它的任務還沒有取得鎖的話，:exc:`RuntimeError` 會被" -"引發。" - -#: ../../library/asyncio-sync.rst:259 -msgid "" -"This method releases the underlying lock, and then blocks until it is " -"awakened by a :meth:`notify` or :meth:`notify_all` call. Once awakened, the " -"Condition re-acquires its lock and this method returns ``True``." -msgstr "" -"此方法會釋放底層的鎖，然後持續阻塞直到被 :meth:`notify` 或 :meth:" -"`notify_all` 的呼叫所喚醒。一但被喚醒，Condition 會重新取得該鎖且此方法會回" -"傳 ``True``。" - -#: ../../library/asyncio-sync.rst:264 -msgid "" -"Note that a task *may* return from this call spuriously, which is why the " -"caller should always re-check the state and be prepared to :meth:`~Condition." -"wait` again. For this reason, you may prefer to use :meth:`~Condition." -"wait_for` instead." -msgstr "" - -#: ../../library/asyncio-sync.rst:272 -msgid "Wait until a predicate becomes *true*." -msgstr "持續等待直到謂語 (predicate) 成為 *true*。" - -#: ../../library/asyncio-sync.rst:274 -msgid "" -"The predicate must be a callable which result will be interpreted as a " -"boolean value. The method will repeatedly :meth:`~Condition.wait` until the " -"predicate evaluates to *true*. The final value is the return value." -msgstr "" -"謂語必須是一個結果可被直譯為一個 boolean 值的可呼叫物件 (callable)。此方法會" -"重複地 :meth:`~Condition.wait` 直到謂語求值結果為 *true*。最終的值即為回傳" -"值。" - -#: ../../library/asyncio-sync.rst:281 -msgid "Semaphore" -msgstr "Semaphore" - -#: ../../library/asyncio-sync.rst:285 -msgid "A Semaphore object. Not thread-safe." -msgstr "一個旗號 (semaphore) 物件。不支援執行緒安全。" - -#: ../../library/asyncio-sync.rst:287 -msgid "" -"A semaphore manages an internal counter which is decremented by each :meth:" -"`acquire` call and incremented by each :meth:`release` call. The counter can " -"never go below zero; when :meth:`acquire` finds that it is zero, it blocks, " -"waiting until some task calls :meth:`release`." -msgstr "" -"一個旗號物件會管理一個內部計數器，會在每次呼叫 :meth:`acquire` 時減少一、每次" -"呼叫 :meth:`release` 時增加一。此計數器永遠不會少於零；當 :meth:`acquire` 發" -"現它是零時，它會持續阻塞並等待某任務呼叫 :meth:`release`。" - -#: ../../library/asyncio-sync.rst:293 -msgid "" -"The optional *value* argument gives the initial value for the internal " -"counter (``1`` by default). If the given value is less than ``0`` a :exc:" -"`ValueError` is raised." -msgstr "" -"可選的 *value* 引數給定了內部計數器的初始值（預設為 ``1``\\ ）。如給定的值少" -"於 ``0`` 則 :exc:`ValueError` 會被引發。" - -#: ../../library/asyncio-sync.rst:300 -msgid "" -"The preferred way to use a Semaphore is an :keyword:`async with` statement::" -msgstr "使用 Semaphore 的推薦方式是透過 :keyword:`async with` 陳述式： ::" - -#: ../../library/asyncio-sync.rst:303 -msgid "" -"sem = asyncio.Semaphore(10)\n" -"\n" -"# ... later\n" -"async with sem:\n" -" # work with shared resource" -msgstr "" - -#: ../../library/asyncio-sync.rst:311 -msgid "" -"sem = asyncio.Semaphore(10)\n" -"\n" -"# ... later\n" -"await sem.acquire()\n" -"try:\n" -" # work with shared resource\n" -"finally:\n" -" sem.release()" -msgstr "" - -#: ../../library/asyncio-sync.rst:323 -msgid "Acquire a semaphore." -msgstr "取得一個旗號。" - -#: ../../library/asyncio-sync.rst:325 -msgid "" -"If the internal counter is greater than zero, decrement it by one and return " -"``True`` immediately. If it is zero, wait until a :meth:`release` is called " -"and return ``True``." -msgstr "" -"如果內部計數器大於零，將其減一並立刻回傳 ``True``。如果為零，則持續等待直到 :" -"meth:`release` 被呼叫，並回傳 ``True``。" - -#: ../../library/asyncio-sync.rst:331 -msgid "Returns ``True`` if semaphore can not be acquired immediately." -msgstr "如果旗號無法立即被取得則回傳 ``True``。" - -#: ../../library/asyncio-sync.rst:335 -msgid "" -"Release a semaphore, incrementing the internal counter by one. Can wake up a " -"task waiting to acquire the semaphore." -msgstr "" -"釋放一個旗號，並為其內部的計數器數值增加一。可以把一個正在等待取得旗號的任務" -"叫醒。" - -#: ../../library/asyncio-sync.rst:338 -msgid "" -"Unlike :class:`BoundedSemaphore`, :class:`Semaphore` allows making more " -"``release()`` calls than ``acquire()`` calls." -msgstr "" -"和 :class:`BoundedSemaphore` 不同，:class:`Semaphore` 允許 ``release()`` 的呼" -"叫次數多於 ``acquire()``。" - -#: ../../library/asyncio-sync.rst:343 -msgid "BoundedSemaphore" -msgstr "BoundedSemaphore" - -#: ../../library/asyncio-sync.rst:347 -msgid "A bounded semaphore object. Not thread-safe." -msgstr "一個有界的旗號物件。不支援執行緒安全。" - -#: ../../library/asyncio-sync.rst:349 -msgid "" -"Bounded Semaphore is a version of :class:`Semaphore` that raises a :exc:" -"`ValueError` in :meth:`~Semaphore.release` if it increases the internal " -"counter above the initial *value*." -msgstr "" -"Bounded Semaphore 是 :class:`Semaphore` 的另一版本，如果其內部的計數器數值增" -"加至大於初始 *value* 值的話，:exc:`ValueError` 會在 :meth:`~Semaphore." -"release` 時被引發。" - -#: ../../library/asyncio-sync.rst:358 -msgid "Barrier" -msgstr "Barrier" - -#: ../../library/asyncio-sync.rst:362 -msgid "A barrier object. Not thread-safe." -msgstr "一個屏障 (barrier) 物件。不支援執行緒安全。" - -#: ../../library/asyncio-sync.rst:364 -msgid "" -"A barrier is a simple synchronization primitive that allows to block until " -"*parties* number of tasks are waiting on it. Tasks can wait on the :meth:" -"`~Barrier.wait` method and would be blocked until the specified number of " -"tasks end up waiting on :meth:`~Barrier.wait`. At that point all of the " -"waiting tasks would unblock simultaneously." -msgstr "" - -#: ../../library/asyncio-sync.rst:370 -msgid "" -":keyword:`async with` can be used as an alternative to awaiting on :meth:" -"`~Barrier.wait`." -msgstr "" - -#: ../../library/asyncio-sync.rst:373 -msgid "The barrier can be reused any number of times." -msgstr "" - -#: ../../library/asyncio-sync.rst:379 -msgid "" -"async def example_barrier():\n" -" # barrier with 3 parties\n" -" b = asyncio.Barrier(3)\n" -"\n" -" # create 2 new waiting tasks\n" -" asyncio.create_task(b.wait())\n" -" asyncio.create_task(b.wait())\n" -"\n" -" await asyncio.sleep(0)\n" -" print(b)\n" -"\n" -" # The third .wait() call passes the barrier\n" -" await b.wait()\n" -" print(b)\n" -" print(\"barrier passed\")\n" -"\n" -" await asyncio.sleep(0)\n" -" print(b)\n" -"\n" -"asyncio.run(example_barrier())" -msgstr "" - -#: ../../library/asyncio-sync.rst:400 -msgid "Result of this example is::" -msgstr "" - -#: ../../library/asyncio-sync.rst:402 -msgid "" -"\n" -"\n" -"barrier passed\n" -"" -msgstr "" -"\n" -"\n" -"barrier passed\n" -"" - -#: ../../library/asyncio-sync.rst:412 -msgid "" -"Pass the barrier. When all the tasks party to the barrier have called this " -"function, they are all unblocked simultaneously." -msgstr "" - -#: ../../library/asyncio-sync.rst:415 -msgid "" -"When a waiting or blocked task in the barrier is cancelled, this task exits " -"the barrier which stays in the same state. If the state of the barrier is " -"\"filling\", the number of waiting task decreases by 1." -msgstr "" - -#: ../../library/asyncio-sync.rst:420 -msgid "" -"The return value is an integer in the range of 0 to ``parties-1``, different " -"for each task. This can be used to select a task to do some special " -"housekeeping, e.g.::" -msgstr "" - -#: ../../library/asyncio-sync.rst:424 -msgid "" -"...\n" -"async with barrier as position:\n" -" if position == 0:\n" -" # Only one task prints this\n" -" print('End of *draining phase*')" -msgstr "" - -#: ../../library/asyncio-sync.rst:430 -msgid "" -"This method may raise a :class:`BrokenBarrierError` exception if the barrier " -"is broken or reset while a task is waiting. It could raise a :exc:" -"`CancelledError` if a task is cancelled." -msgstr "" - -#: ../../library/asyncio-sync.rst:437 -msgid "" -"Return the barrier to the default, empty state. Any tasks waiting on it " -"will receive the :class:`BrokenBarrierError` exception." -msgstr "" - -#: ../../library/asyncio-sync.rst:440 -msgid "" -"If a barrier is broken it may be better to just leave it and create a new " -"one." -msgstr "" - -#: ../../library/asyncio-sync.rst:445 -msgid "" -"Put the barrier into a broken state. This causes any active or future calls " -"to :meth:`~Barrier.wait` to fail with the :class:`BrokenBarrierError`. Use " -"this for example if one of the tasks needs to abort, to avoid infinite " -"waiting tasks." -msgstr "" - -#: ../../library/asyncio-sync.rst:452 -msgid "The number of tasks required to pass the barrier." -msgstr "" - -#: ../../library/asyncio-sync.rst:456 -msgid "The number of tasks currently waiting in the barrier while filling." -msgstr "" - -#: ../../library/asyncio-sync.rst:460 -msgid "A boolean that is ``True`` if the barrier is in the broken state." -msgstr "" - -#: ../../library/asyncio-sync.rst:465 -msgid "" -"This exception, a subclass of :exc:`RuntimeError`, is raised when the :class:" -"`Barrier` object is reset or broken." -msgstr "" - -#: ../../library/asyncio-sync.rst:473 -msgid "" -"Acquiring a lock using ``await lock`` or ``yield from lock`` and/or :keyword:" -"`with` statement (``with await lock``, ``with (yield from lock)``) was " -"removed. Use ``async with lock`` instead." -msgstr "" -"透過 ``await lock`` 或 ``yield from lock`` 和/或 :keyword:`with` 陳述式 " -"(``with await lock``, ``with (yield from lock)``) 來取得鎖的方式已被移除。請" -"改用 ``async with lock``。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-08-17 00:18+0000\n" +"PO-Revision-Date: 2022-02-09 19:27+0800\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" +"X-Generator: Poedit 3.0.1\n" + +#: ../../library/asyncio-sync.rst:7 +msgid "Synchronization Primitives" +msgstr "同步化原始物件 (Synchronization Primitives)" + +#: ../../library/asyncio-sync.rst:9 +msgid "**Source code:** :source:`Lib/asyncio/locks.py`" +msgstr "**原始碼：**\\ :source:`Lib/asyncio/locks.py`" + +#: ../../library/asyncio-sync.rst:13 +msgid "" +"asyncio synchronization primitives are designed to be similar to those of " +"the :mod:`threading` module with two important caveats:" +msgstr "" +"asyncio 的同步化原始物件被設計成和那些 :mod:`threading` 模組 (module) 中的同" +"名物件相似，但有兩個重要的限制條件：" + +#: ../../library/asyncio-sync.rst:16 +msgid "" +"asyncio primitives are not thread-safe, therefore they should not be used " +"for OS thread synchronization (use :mod:`threading` for that);" +msgstr "" +"asyncio 原始物件並不支援執行緒安全 (thread-safe)，因此他們不可被用於 OS 執行" +"緒同步化（請改用 :mod:`threading`\\ ）；" + +#: ../../library/asyncio-sync.rst:20 +msgid "" +"methods of these synchronization primitives do not accept the *timeout* " +"argument; use the :func:`asyncio.wait_for` function to perform operations " +"with timeouts." +msgstr "" +"這些同步化原始物件的方法 (method) 並不接受 *timeout* 引數；要達成有超時 " +"(timeout) 設定的操作請改用 :func:`asyncio.wait_for` 函式。" + +#: ../../library/asyncio-sync.rst:24 +msgid "asyncio has the following basic synchronization primitives:" +msgstr "asyncio 有以下基礎同步化原始物件：" + +#: ../../library/asyncio-sync.rst:26 +msgid ":class:`Lock`" +msgstr ":class:`Lock`" + +#: ../../library/asyncio-sync.rst:27 +msgid ":class:`Event`" +msgstr ":class:`Event`" + +#: ../../library/asyncio-sync.rst:28 +msgid ":class:`Condition`" +msgstr ":class:`Condition`" + +#: ../../library/asyncio-sync.rst:29 +msgid ":class:`Semaphore`" +msgstr ":class:`Semaphore`" + +#: ../../library/asyncio-sync.rst:30 +msgid ":class:`BoundedSemaphore`" +msgstr ":class:`BoundedSemaphore`" + +#: ../../library/asyncio-sync.rst:31 +msgid ":class:`Barrier`" +msgstr ":class:`Barrier`" + +#: ../../library/asyncio-sync.rst:38 +msgid "Lock" +msgstr "Lock" + +#: ../../library/asyncio-sync.rst:42 +msgid "Implements a mutex lock for asyncio tasks. Not thread-safe." +msgstr "" +"實作了一個給 asyncio 任務 (task) 用的互斥鎖 (mutex lock)。不支援執行緒安全。" + +#: ../../library/asyncio-sync.rst:44 +msgid "" +"An asyncio lock can be used to guarantee exclusive access to a shared " +"resource." +msgstr "一個 asyncio 的鎖可以用來確保一個共享資源的存取權被獨佔。" + +#: ../../library/asyncio-sync.rst:47 +msgid "The preferred way to use a Lock is an :keyword:`async with` statement::" +msgstr "使用 Lock 的推薦方式是透過 :keyword:`async with` 陳述式： ::" + +#: ../../library/asyncio-sync.rst:50 +msgid "" +"lock = asyncio.Lock()\n" +"\n" +"# ... later\n" +"async with lock:\n" +" # access shared state" +msgstr "" + +#: ../../library/asyncio-sync.rst:56 ../../library/asyncio-sync.rst:201 +#: ../../library/asyncio-sync.rst:309 +msgid "which is equivalent to::" +msgstr "這等價於： ::" + +#: ../../library/asyncio-sync.rst:58 +msgid "" +"lock = asyncio.Lock()\n" +"\n" +"# ... later\n" +"await lock.acquire()\n" +"try:\n" +" # access shared state\n" +"finally:\n" +" lock.release()" +msgstr "" + +#: ../../library/asyncio-sync.rst:67 ../../library/asyncio-sync.rst:113 +#: ../../library/asyncio-sync.rst:189 ../../library/asyncio-sync.rst:297 +#: ../../library/asyncio-sync.rst:353 +msgid "Removed the *loop* parameter." +msgstr "移除 ``loop`` 參數。" + +#: ../../library/asyncio-sync.rst:73 +msgid "Acquire the lock." +msgstr "獲得鎖。" + +#: ../../library/asyncio-sync.rst:75 +msgid "" +"This method waits until the lock is *unlocked*, sets it to *locked* and " +"returns ``True``." +msgstr "" +"此方法會持續等待直到鎖的狀態成為 *unlocked*，並將其設置為 *locked* 和回傳 " +"``True``。" + +#: ../../library/asyncio-sync.rst:78 +msgid "" +"When more than one coroutine is blocked in :meth:`acquire` waiting for the " +"lock to be unlocked, only one coroutine eventually proceeds." +msgstr "" +"當多於一個的協程 (coroutine) 在 :meth:`acquire` 中等待解鎖而被阻塞，最終只會" +"有其中的一個被處理。" + +#: ../../library/asyncio-sync.rst:82 +msgid "" +"Acquiring a lock is *fair*: the coroutine that proceeds will be the first " +"coroutine that started waiting on the lock." +msgstr "" +"鎖的取得方式是\\ *公平*\\ 的：被處理的協程會是最早開始等待解鎖的那一個。" + +#: ../../library/asyncio-sync.rst:87 +msgid "Release the lock." +msgstr "釋放鎖。" + +#: ../../library/asyncio-sync.rst:89 +msgid "When the lock is *locked*, reset it to *unlocked* and return." +msgstr "如果鎖的狀態為 *locked* 則將其重置為 *unlocked* 並回傳。" + +#: ../../library/asyncio-sync.rst:91 +msgid "If the lock is *unlocked*, a :exc:`RuntimeError` is raised." +msgstr "如果鎖的狀態為 *unlocked* 則 :exc:`RuntimeError` 會被引發。" + +#: ../../library/asyncio-sync.rst:95 +msgid "Return ``True`` if the lock is *locked*." +msgstr "如果鎖的狀態為 *locked* 則回傳 ``True``。" + +#: ../../library/asyncio-sync.rst:99 +msgid "Event" +msgstr "Event" + +#: ../../library/asyncio-sync.rst:103 +msgid "An event object. Not thread-safe." +msgstr "一個事件 (event) 物件。不支援執行緒安全。" + +#: ../../library/asyncio-sync.rst:105 +msgid "" +"An asyncio event can be used to notify multiple asyncio tasks that some " +"event has happened." +msgstr "" +"一個 asyncio 事件可以被用於通知多個有發生某些事件於其中的 asyncio 任務。" + +#: ../../library/asyncio-sync.rst:108 +msgid "" +"An Event object manages an internal flag that can be set to *true* with the :" +"meth:`~Event.set` method and reset to *false* with the :meth:`clear` " +"method. The :meth:`~Event.wait` method blocks until the flag is set to " +"*true*. The flag is set to *false* initially." +msgstr "" +"一個 Event 物件會管理一個內部旗標 (flag)，它可以透過 :meth:`~Event.set` 方法" +"來被設為 *true* 並透過 :meth:`clear` 方法來重置為 *false*。:meth:`~Event." +"wait` 方法會被阻塞 (block) 直到該旗標被設為 *true*。該旗標初始設置為 " +"*false*。" + +#: ../../library/asyncio-sync.rst:118 ../../library/asyncio-sync.rst:377 +msgid "Example::" +msgstr "範例： ::" + +#: ../../library/asyncio-sync.rst:120 +msgid "" +"async def waiter(event):\n" +" print('waiting for it ...')\n" +" await event.wait()\n" +" print('... got it!')\n" +"\n" +"async def main():\n" +" # Create an Event object.\n" +" event = asyncio.Event()\n" +"\n" +" # Spawn a Task to wait until 'event' is set.\n" +" waiter_task = asyncio.create_task(waiter(event))\n" +"\n" +" # Sleep for 1 second and set the event.\n" +" await asyncio.sleep(1)\n" +" event.set()\n" +"\n" +" # Wait until the waiter task is finished.\n" +" await waiter_task\n" +"\n" +"asyncio.run(main())" +msgstr "" + +#: ../../library/asyncio-sync.rst:144 +msgid "Wait until the event is set." +msgstr "持續等待直到事件被設置。" + +#: ../../library/asyncio-sync.rst:146 +msgid "" +"If the event is set, return ``True`` immediately. Otherwise block until " +"another task calls :meth:`~Event.set`." +msgstr "" +"如果事件有被設置則立刻回傳 ``True``。否則持續阻塞直到另一個任務呼叫 :meth:" +"`~Event.set`。" + +#: ../../library/asyncio-sync.rst:151 +msgid "Set the event." +msgstr "設置事件。" + +#: ../../library/asyncio-sync.rst:153 +msgid "All tasks waiting for event to be set will be immediately awakened." +msgstr "所有正在等待事件被設置的任務會立即被喚醒。" + +#: ../../library/asyncio-sync.rst:158 +msgid "Clear (unset) the event." +msgstr "清除（還原）事件。" + +#: ../../library/asyncio-sync.rst:160 +msgid "" +"Subsequent tasks awaiting on :meth:`~Event.wait` will now block until the :" +"meth:`~Event.set` method is called again." +msgstr "" +"正透過 :meth:`~Event.wait` 等待的後續 Tasks 現在會持續阻塞直到 :meth:`~Event." +"set` 方法再次被呼叫。" + +#: ../../library/asyncio-sync.rst:165 +msgid "Return ``True`` if the event is set." +msgstr "如果事件有被設置則回傳 ``True``。" + +#: ../../library/asyncio-sync.rst:169 +msgid "Condition" +msgstr "Condition" + +#: ../../library/asyncio-sync.rst:173 +msgid "A Condition object. Not thread-safe." +msgstr "一個條件 (codition) 物件。不支援執行緒安全。" + +#: ../../library/asyncio-sync.rst:175 +msgid "" +"An asyncio condition primitive can be used by a task to wait for some event " +"to happen and then get exclusive access to a shared resource." +msgstr "" +"一個 asyncio 條件原始物件可以被任務用來等待某事件發生，並獲得一個共享資源的獨" +"佔存取權。" + +#: ../../library/asyncio-sync.rst:179 +msgid "" +"In essence, a Condition object combines the functionality of an :class:" +"`Event` and a :class:`Lock`. It is possible to have multiple Condition " +"objects share one Lock, which allows coordinating exclusive access to a " +"shared resource between different tasks interested in particular states of " +"that shared resource." +msgstr "" +"本質上，一個 Condition 物件會結合 :class:`Event` 和 :class:`Lock` 的功能。多" +"個 Condition 物件共享一個 Lock 是有可能發生的，這能夠協調關注同一共享資源的不" +"同狀態以取得其獨佔存取權的多個任務。" + +#: ../../library/asyncio-sync.rst:185 +msgid "" +"The optional *lock* argument must be a :class:`Lock` object or ``None``. In " +"the latter case a new Lock object is created automatically." +msgstr "" +"可選的 *lock* 引數必須是一個 :class:`Lock` 物件或者為 ``None``。如為後者則一" +"個新的 Lock 物件會被自動建立。" + +#: ../../library/asyncio-sync.rst:192 +msgid "" +"The preferred way to use a Condition is an :keyword:`async with` statement::" +msgstr "使用 Condition 的推薦方式是透過 :keyword:`async with` 陳述式： ::" + +#: ../../library/asyncio-sync.rst:195 +msgid "" +"cond = asyncio.Condition()\n" +"\n" +"# ... later\n" +"async with cond:\n" +" await cond.wait()" +msgstr "" + +#: ../../library/asyncio-sync.rst:203 +msgid "" +"cond = asyncio.Condition()\n" +"\n" +"# ... later\n" +"await cond.acquire()\n" +"try:\n" +" await cond.wait()\n" +"finally:\n" +" cond.release()" +msgstr "" + +#: ../../library/asyncio-sync.rst:215 +msgid "Acquire the underlying lock." +msgstr "取得底層的鎖。" + +#: ../../library/asyncio-sync.rst:217 +msgid "" +"This method waits until the underlying lock is *unlocked*, sets it to " +"*locked* and returns ``True``." +msgstr "" +"此方法會持續等待直到底層的鎖為 *unlocked*，並將其設為 *locked* 並回傳 " +"``True``。" + +#: ../../library/asyncio-sync.rst:222 +msgid "" +"Wake up *n* tasks (1 by default) waiting on this condition. If fewer than " +"*n* tasks are waiting they are all awakened." +msgstr "" +"喚醒至多 *n* 個正在等待此條件的任務（預設為 1），如果少於 *n* 個任務則全部被" +"喚醒。" + +#: ../../library/asyncio-sync.rst:225 ../../library/asyncio-sync.rst:240 +msgid "" +"The lock must be acquired before this method is called and released shortly " +"after. If called with an *unlocked* lock a :exc:`RuntimeError` error is " +"raised." +msgstr "" +"在此方法被呼叫前必須先獲得鎖，並在之後立刻將其釋放。如果呼叫於一個 " +"*unlocked* 的鎖則 :exc:`RuntimeError` 錯誤會被引發。" + +#: ../../library/asyncio-sync.rst:231 +msgid "Return ``True`` if the underlying lock is acquired." +msgstr "如果已取得底層的鎖則回傳 ``True``。" + +#: ../../library/asyncio-sync.rst:235 +msgid "Wake up all tasks waiting on this condition." +msgstr "喚醒所有正在等待此條件的任務。" + +#: ../../library/asyncio-sync.rst:237 +msgid "This method acts like :meth:`notify`, but wakes up all waiting tasks." +msgstr "這個方法的行為就像 :meth:`notify`，但會喚醒所有正在等待的任務。" + +#: ../../library/asyncio-sync.rst:246 +msgid "Release the underlying lock." +msgstr "釋放底層的鎖。" + +#: ../../library/asyncio-sync.rst:248 +msgid "When invoked on an unlocked lock, a :exc:`RuntimeError` is raised." +msgstr "當叫用於一個未被解開的鎖之上時，會引發一個 :exc:`RuntimeError`。" + +#: ../../library/asyncio-sync.rst:254 +msgid "Wait until notified." +msgstr "持續等待直到被通知 (notify)。" + +#: ../../library/asyncio-sync.rst:256 +msgid "" +"If the calling task has not acquired the lock when this method is called, a :" +"exc:`RuntimeError` is raised." +msgstr "" +"當此方法被呼叫時，如果呼叫它的任務還沒有取得鎖的話，:exc:`RuntimeError` 會被" +"引發。" + +#: ../../library/asyncio-sync.rst:259 +msgid "" +"This method releases the underlying lock, and then blocks until it is " +"awakened by a :meth:`notify` or :meth:`notify_all` call. Once awakened, the " +"Condition re-acquires its lock and this method returns ``True``." +msgstr "" +"此方法會釋放底層的鎖，然後持續阻塞直到被 :meth:`notify` 或 :meth:" +"`notify_all` 的呼叫所喚醒。一但被喚醒，Condition 會重新取得該鎖且此方法會回" +"傳 ``True``。" + +#: ../../library/asyncio-sync.rst:264 +msgid "" +"Note that a task *may* return from this call spuriously, which is why the " +"caller should always re-check the state and be prepared to :meth:`~Condition." +"wait` again. For this reason, you may prefer to use :meth:`~Condition." +"wait_for` instead." +msgstr "" + +#: ../../library/asyncio-sync.rst:272 +msgid "Wait until a predicate becomes *true*." +msgstr "持續等待直到謂語 (predicate) 成為 *true*。" + +#: ../../library/asyncio-sync.rst:274 +msgid "" +"The predicate must be a callable which result will be interpreted as a " +"boolean value. The method will repeatedly :meth:`~Condition.wait` until the " +"predicate evaluates to *true*. The final value is the return value." +msgstr "" +"謂語必須是一個結果可被直譯為一個 boolean 值的可呼叫物件 (callable)。此方法會" +"重複地 :meth:`~Condition.wait` 直到謂語求值結果為 *true*。最終的值即為回傳" +"值。" + +#: ../../library/asyncio-sync.rst:281 +msgid "Semaphore" +msgstr "Semaphore" + +#: ../../library/asyncio-sync.rst:285 +msgid "A Semaphore object. Not thread-safe." +msgstr "一個旗號 (semaphore) 物件。不支援執行緒安全。" + +#: ../../library/asyncio-sync.rst:287 +msgid "" +"A semaphore manages an internal counter which is decremented by each :meth:" +"`acquire` call and incremented by each :meth:`release` call. The counter can " +"never go below zero; when :meth:`acquire` finds that it is zero, it blocks, " +"waiting until some task calls :meth:`release`." +msgstr "" +"一個旗號物件會管理一個內部計數器，會在每次呼叫 :meth:`acquire` 時減少一、每次" +"呼叫 :meth:`release` 時增加一。此計數器永遠不會少於零；當 :meth:`acquire` 發" +"現它是零時，它會持續阻塞並等待某任務呼叫 :meth:`release`。" + +#: ../../library/asyncio-sync.rst:293 +msgid "" +"The optional *value* argument gives the initial value for the internal " +"counter (``1`` by default). If the given value is less than ``0`` a :exc:" +"`ValueError` is raised." +msgstr "" +"可選的 *value* 引數給定了內部計數器的初始值（預設為 ``1``\\ ）。如給定的值少" +"於 ``0`` 則 :exc:`ValueError` 會被引發。" + +#: ../../library/asyncio-sync.rst:300 +msgid "" +"The preferred way to use a Semaphore is an :keyword:`async with` statement::" +msgstr "使用 Semaphore 的推薦方式是透過 :keyword:`async with` 陳述式： ::" + +#: ../../library/asyncio-sync.rst:303 +msgid "" +"sem = asyncio.Semaphore(10)\n" +"\n" +"# ... later\n" +"async with sem:\n" +" # work with shared resource" +msgstr "" + +#: ../../library/asyncio-sync.rst:311 +msgid "" +"sem = asyncio.Semaphore(10)\n" +"\n" +"# ... later\n" +"await sem.acquire()\n" +"try:\n" +" # work with shared resource\n" +"finally:\n" +" sem.release()" +msgstr "" + +#: ../../library/asyncio-sync.rst:323 +msgid "Acquire a semaphore." +msgstr "取得一個旗號。" + +#: ../../library/asyncio-sync.rst:325 +msgid "" +"If the internal counter is greater than zero, decrement it by one and return " +"``True`` immediately. If it is zero, wait until a :meth:`release` is called " +"and return ``True``." +msgstr "" +"如果內部計數器大於零，將其減一並立刻回傳 ``True``。如果為零，則持續等待直到 :" +"meth:`release` 被呼叫，並回傳 ``True``。" + +#: ../../library/asyncio-sync.rst:331 +msgid "Returns ``True`` if semaphore can not be acquired immediately." +msgstr "如果旗號無法立即被取得則回傳 ``True``。" + +#: ../../library/asyncio-sync.rst:335 +msgid "" +"Release a semaphore, incrementing the internal counter by one. Can wake up a " +"task waiting to acquire the semaphore." +msgstr "" +"釋放一個旗號，並為其內部的計數器數值增加一。可以把一個正在等待取得旗號的任務" +"叫醒。" + +#: ../../library/asyncio-sync.rst:338 +msgid "" +"Unlike :class:`BoundedSemaphore`, :class:`Semaphore` allows making more " +"``release()`` calls than ``acquire()`` calls." +msgstr "" +"和 :class:`BoundedSemaphore` 不同，:class:`Semaphore` 允許 ``release()`` 的呼" +"叫次數多於 ``acquire()``。" + +#: ../../library/asyncio-sync.rst:343 +msgid "BoundedSemaphore" +msgstr "BoundedSemaphore" + +#: ../../library/asyncio-sync.rst:347 +msgid "A bounded semaphore object. Not thread-safe." +msgstr "一個有界的旗號物件。不支援執行緒安全。" + +#: ../../library/asyncio-sync.rst:349 +msgid "" +"Bounded Semaphore is a version of :class:`Semaphore` that raises a :exc:" +"`ValueError` in :meth:`~Semaphore.release` if it increases the internal " +"counter above the initial *value*." +msgstr "" +"Bounded Semaphore 是 :class:`Semaphore` 的另一版本，如果其內部的計數器數值增" +"加至大於初始 *value* 值的話，:exc:`ValueError` 會在 :meth:`~Semaphore." +"release` 時被引發。" + +#: ../../library/asyncio-sync.rst:358 +msgid "Barrier" +msgstr "Barrier" + +#: ../../library/asyncio-sync.rst:362 +msgid "A barrier object. Not thread-safe." +msgstr "一個屏障 (barrier) 物件。不支援執行緒安全。" + +#: ../../library/asyncio-sync.rst:364 +msgid "" +"A barrier is a simple synchronization primitive that allows to block until " +"*parties* number of tasks are waiting on it. Tasks can wait on the :meth:" +"`~Barrier.wait` method and would be blocked until the specified number of " +"tasks end up waiting on :meth:`~Barrier.wait`. At that point all of the " +"waiting tasks would unblock simultaneously." +msgstr "" + +#: ../../library/asyncio-sync.rst:370 +msgid "" +":keyword:`async with` can be used as an alternative to awaiting on :meth:" +"`~Barrier.wait`." +msgstr "" + +#: ../../library/asyncio-sync.rst:373 +msgid "The barrier can be reused any number of times." +msgstr "" + +#: ../../library/asyncio-sync.rst:379 +msgid "" +"async def example_barrier():\n" +" # barrier with 3 parties\n" +" b = asyncio.Barrier(3)\n" +"\n" +" # create 2 new waiting tasks\n" +" asyncio.create_task(b.wait())\n" +" asyncio.create_task(b.wait())\n" +"\n" +" await asyncio.sleep(0)\n" +" print(b)\n" +"\n" +" # The third .wait() call passes the barrier\n" +" await b.wait()\n" +" print(b)\n" +" print(\"barrier passed\")\n" +"\n" +" await asyncio.sleep(0)\n" +" print(b)\n" +"\n" +"asyncio.run(example_barrier())" +msgstr "" + +#: ../../library/asyncio-sync.rst:400 +msgid "Result of this example is::" +msgstr "" + +#: ../../library/asyncio-sync.rst:402 +msgid "" +"\n" +"\n" +"barrier passed\n" +"" +msgstr "" +"\n" +"\n" +"barrier passed\n" +"" + +#: ../../library/asyncio-sync.rst:412 +msgid "" +"Pass the barrier. When all the tasks party to the barrier have called this " +"function, they are all unblocked simultaneously." +msgstr "" + +#: ../../library/asyncio-sync.rst:415 +msgid "" +"When a waiting or blocked task in the barrier is cancelled, this task exits " +"the barrier which stays in the same state. If the state of the barrier is " +"\"filling\", the number of waiting task decreases by 1." +msgstr "" + +#: ../../library/asyncio-sync.rst:420 +msgid "" +"The return value is an integer in the range of 0 to ``parties-1``, different " +"for each task. This can be used to select a task to do some special " +"housekeeping, e.g.::" +msgstr "" + +#: ../../library/asyncio-sync.rst:424 +msgid "" +"...\n" +"async with barrier as position:\n" +" if position == 0:\n" +" # Only one task prints this\n" +" print('End of *draining phase*')" +msgstr "" + +#: ../../library/asyncio-sync.rst:430 +msgid "" +"This method may raise a :class:`BrokenBarrierError` exception if the barrier " +"is broken or reset while a task is waiting. It could raise a :exc:" +"`CancelledError` if a task is cancelled." +msgstr "" + +#: ../../library/asyncio-sync.rst:437 +msgid "" +"Return the barrier to the default, empty state. Any tasks waiting on it " +"will receive the :class:`BrokenBarrierError` exception." +msgstr "" + +#: ../../library/asyncio-sync.rst:440 +msgid "" +"If a barrier is broken it may be better to just leave it and create a new " +"one." +msgstr "" + +#: ../../library/asyncio-sync.rst:445 +msgid "" +"Put the barrier into a broken state. This causes any active or future calls " +"to :meth:`~Barrier.wait` to fail with the :class:`BrokenBarrierError`. Use " +"this for example if one of the tasks needs to abort, to avoid infinite " +"waiting tasks." +msgstr "" + +#: ../../library/asyncio-sync.rst:452 +msgid "The number of tasks required to pass the barrier." +msgstr "" + +#: ../../library/asyncio-sync.rst:456 +msgid "The number of tasks currently waiting in the barrier while filling." +msgstr "" + +#: ../../library/asyncio-sync.rst:460 +msgid "A boolean that is ``True`` if the barrier is in the broken state." +msgstr "" + +#: ../../library/asyncio-sync.rst:465 +msgid "" +"This exception, a subclass of :exc:`RuntimeError`, is raised when the :class:" +"`Barrier` object is reset or broken." +msgstr "" + +#: ../../library/asyncio-sync.rst:473 +msgid "" +"Acquiring a lock using ``await lock`` or ``yield from lock`` and/or :keyword:" +"`with` statement (``with await lock``, ``with (yield from lock)``) was " +"removed. Use ``async with lock`` instead." +msgstr "" +"透過 ``await lock`` 或 ``yield from lock`` 和/或 :keyword:`with` 陳述式 " +"(``with await lock``, ``with (yield from lock)``) 來取得鎖的方式已被移除。請" +"改用 ``async with lock``。" diff --git a/library/asyncio-task.po b/library/asyncio-task.po index 061f1ca20a..2e273a7cab 100644 --- a/library/asyncio-task.po +++ b/library/asyncio-task.po @@ -1,2053 +1,2053 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: 2018-05-23 14:39+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/asyncio-task.rst:6 -msgid "Coroutines and Tasks" -msgstr "協程與任務" - -#: ../../library/asyncio-task.rst:8 -msgid "" -"This section outlines high-level asyncio APIs to work with coroutines and " -"Tasks." -msgstr "" - -#: ../../library/asyncio-task.rst:19 ../../library/asyncio-task.rst:148 -msgid "Coroutines" -msgstr "協程" - -#: ../../library/asyncio-task.rst:21 -msgid "**Source code:** :source:`Lib/asyncio/coroutines.py`" -msgstr "**原始碼：**\\ :source:`Lib/asyncio/coroutines.py`" - -#: ../../library/asyncio-task.rst:25 -msgid "" -":term:`Coroutines ` declared with the async/await syntax is the " -"preferred way of writing asyncio applications. For example, the following " -"snippet of code prints \"hello\", waits 1 second, and then prints \"world\"::" -msgstr "" - -#: ../../library/asyncio-task.rst:30 -msgid "" -">>> import asyncio\n" -"\n" -">>> async def main():\n" -"... print('hello')\n" -"... await asyncio.sleep(1)\n" -"... print('world')\n" -"\n" -">>> asyncio.run(main())\n" -"hello\n" -"world" -msgstr "" -">>> import asyncio\n" -"\n" -">>> async def main():\n" -"... print('hello')\n" -"... await asyncio.sleep(1)\n" -"... print('world')\n" -"\n" -">>> asyncio.run(main())\n" -"hello\n" -"world" - -#: ../../library/asyncio-task.rst:41 -msgid "" -"Note that simply calling a coroutine will not schedule it to be executed::" -msgstr "" - -#: ../../library/asyncio-task.rst:44 -msgid "" -">>> main()\n" -"" -msgstr "" -">>> main()\n" -"" - -#: ../../library/asyncio-task.rst:47 -msgid "To actually run a coroutine, asyncio provides the following mechanisms:" -msgstr "" - -#: ../../library/asyncio-task.rst:49 -msgid "" -"The :func:`asyncio.run` function to run the top-level entry point \"main()\" " -"function (see the above example.)" -msgstr "" - -#: ../../library/asyncio-task.rst:52 -msgid "" -"Awaiting on a coroutine. The following snippet of code will print \"hello\" " -"after waiting for 1 second, and then print \"world\" after waiting for " -"*another* 2 seconds::" -msgstr "" - -#: ../../library/asyncio-task.rst:56 -msgid "" -"import asyncio\n" -"import time\n" -"\n" -"async def say_after(delay, what):\n" -" await asyncio.sleep(delay)\n" -" print(what)\n" -"\n" -"async def main():\n" -" print(f\"started at {time.strftime('%X')}\")\n" -"\n" -" await say_after(1, 'hello')\n" -" await say_after(2, 'world')\n" -"\n" -" print(f\"finished at {time.strftime('%X')}\")\n" -"\n" -"asyncio.run(main())" -msgstr "" -"import asyncio\n" -"import time\n" -"\n" -"async def say_after(delay, what):\n" -" await asyncio.sleep(delay)\n" -" print(what)\n" -"\n" -"async def main():\n" -" print(f\"started at {time.strftime('%X')}\")\n" -"\n" -" await say_after(1, 'hello')\n" -" await say_after(2, 'world')\n" -"\n" -" print(f\"finished at {time.strftime('%X')}\")\n" -"\n" -"asyncio.run(main())" - -#: ../../library/asyncio-task.rst:73 -msgid "Expected output::" -msgstr "預期的輸出： ::" - -#: ../../library/asyncio-task.rst:75 -msgid "" -"started at 17:13:52\n" -"hello\n" -"world\n" -"finished at 17:13:55" -msgstr "" -"started at 17:13:52\n" -"hello\n" -"world\n" -"finished at 17:13:55" - -#: ../../library/asyncio-task.rst:80 -msgid "" -"The :func:`asyncio.create_task` function to run coroutines concurrently as " -"asyncio :class:`Tasks `." -msgstr "" - -#: ../../library/asyncio-task.rst:83 -msgid "" -"Let's modify the above example and run two ``say_after`` coroutines " -"*concurrently*::" -msgstr "" - -#: ../../library/asyncio-task.rst:86 -msgid "" -"async def main():\n" -" task1 = asyncio.create_task(\n" -" say_after(1, 'hello'))\n" -"\n" -" task2 = asyncio.create_task(\n" -" say_after(2, 'world'))\n" -"\n" -" print(f\"started at {time.strftime('%X')}\")\n" -"\n" -" # Wait until both tasks are completed (should take\n" -" # around 2 seconds.)\n" -" await task1\n" -" await task2\n" -"\n" -" print(f\"finished at {time.strftime('%X')}\")" -msgstr "" - -#: ../../library/asyncio-task.rst:102 -msgid "" -"Note that expected output now shows that the snippet runs 1 second faster " -"than before::" -msgstr "" - -#: ../../library/asyncio-task.rst:105 -msgid "" -"started at 17:14:32\n" -"hello\n" -"world\n" -"finished at 17:14:34" -msgstr "" -"started at 17:14:32\n" -"hello\n" -"world\n" -"finished at 17:14:34" - -#: ../../library/asyncio-task.rst:110 -msgid "" -"The :class:`asyncio.TaskGroup` class provides a more modern alternative " -"to :func:`create_task`. Using this API, the last example becomes::" -msgstr "" - -#: ../../library/asyncio-task.rst:114 -msgid "" -"async def main():\n" -" async with asyncio.TaskGroup() as tg:\n" -" task1 = tg.create_task(\n" -" say_after(1, 'hello'))\n" -"\n" -" task2 = tg.create_task(\n" -" say_after(2, 'world'))\n" -"\n" -" print(f\"started at {time.strftime('%X')}\")\n" -"\n" -" # The await is implicit when the context manager exits.\n" -"\n" -" print(f\"finished at {time.strftime('%X')}\")" -msgstr "" - -#: ../../library/asyncio-task.rst:128 -msgid "The timing and output should be the same as for the previous version." -msgstr "" - -#: ../../library/asyncio-task.rst:130 -msgid ":class:`asyncio.TaskGroup`." -msgstr ":class:`asyncio.TaskGroup`。" - -#: ../../library/asyncio-task.rst:137 -msgid "Awaitables" -msgstr "" - -#: ../../library/asyncio-task.rst:139 -msgid "" -"We say that an object is an **awaitable** object if it can be used in " -"an :keyword:`await` expression. Many asyncio APIs are designed to accept " -"awaitables." -msgstr "" - -#: ../../library/asyncio-task.rst:143 -msgid "" -"There are three main types of *awaitable* objects: **coroutines**, " -"**Tasks**, and **Futures**." -msgstr "" - -#: ../../library/asyncio-task.rst:149 -msgid "" -"Python coroutines are *awaitables* and therefore can be awaited from other " -"coroutines::" -msgstr "" - -#: ../../library/asyncio-task.rst:152 -msgid "" -"import asyncio\n" -"\n" -"async def nested():\n" -" return 42\n" -"\n" -"async def main():\n" -" # Nothing happens if we just call \"nested()\".\n" -" # A coroutine object is created but not awaited,\n" -" # so it *won't run at all*.\n" -" nested() # will raise a \"RuntimeWarning\".\n" -"\n" -" # Let's do it differently now and await it:\n" -" print(await nested()) # will print \"42\".\n" -"\n" -"asyncio.run(main())" -msgstr "" - -#: ../../library/asyncio-task.rst:170 -msgid "" -"In this documentation the term \"coroutine\" can be used for two closely " -"related concepts:" -msgstr "" - -#: ../../library/asyncio-task.rst:173 -msgid "a *coroutine function*: an :keyword:`async def` function;" -msgstr "" - -#: ../../library/asyncio-task.rst:175 -msgid "" -"a *coroutine object*: an object returned by calling a *coroutine function*." -msgstr "" - -#: ../../library/asyncio-task.rst:180 -msgid "Tasks" -msgstr "" - -#: ../../library/asyncio-task.rst:181 -msgid "*Tasks* are used to schedule coroutines *concurrently*." -msgstr "" - -#: ../../library/asyncio-task.rst:183 -msgid "" -"When a coroutine is wrapped into a *Task* with functions " -"like :func:`asyncio.create_task` the coroutine is automatically scheduled to " -"run soon::" -msgstr "" - -#: ../../library/asyncio-task.rst:187 -msgid "" -"import asyncio\n" -"\n" -"async def nested():\n" -" return 42\n" -"\n" -"async def main():\n" -" # Schedule nested() to run soon concurrently\n" -" # with \"main()\".\n" -" task = asyncio.create_task(nested())\n" -"\n" -" # \"task\" can now be used to cancel \"nested()\", or\n" -" # can simply be awaited to wait until it is complete:\n" -" await task\n" -"\n" -"asyncio.run(main())" -msgstr "" - -#: ../../library/asyncio-task.rst:205 -msgid "Futures" -msgstr "" - -#: ../../library/asyncio-task.rst:206 -msgid "" -"A :class:`Future` is a special **low-level** awaitable object that " -"represents an **eventual result** of an asynchronous operation." -msgstr "" - -#: ../../library/asyncio-task.rst:209 -msgid "" -"When a Future object is *awaited* it means that the coroutine will wait " -"until the Future is resolved in some other place." -msgstr "" - -#: ../../library/asyncio-task.rst:212 -msgid "" -"Future objects in asyncio are needed to allow callback-based code to be used " -"with async/await." -msgstr "" - -#: ../../library/asyncio-task.rst:215 -msgid "" -"Normally **there is no need** to create Future objects at the application " -"level code." -msgstr "" - -#: ../../library/asyncio-task.rst:218 -msgid "" -"Future objects, sometimes exposed by libraries and some asyncio APIs, can be " -"awaited::" -msgstr "" - -#: ../../library/asyncio-task.rst:221 -msgid "" -"async def main():\n" -" await function_that_returns_a_future_object()\n" -"\n" -" # this is also valid:\n" -" await asyncio.gather(\n" -" function_that_returns_a_future_object(),\n" -" some_python_coroutine()\n" -" )" -msgstr "" - -#: ../../library/asyncio-task.rst:230 -msgid "" -"A good example of a low-level function that returns a Future object " -"is :meth:`loop.run_in_executor`." -msgstr "" - -#: ../../library/asyncio-task.rst:235 -msgid "Creating Tasks" -msgstr "" - -#: ../../library/asyncio-task.rst:237 -msgid "**Source code:** :source:`Lib/asyncio/tasks.py`" -msgstr "**原始碼：**\\ :source:`Lib/asyncio/tasks.py`" - -#: ../../library/asyncio-task.rst:243 -msgid "" -"Wrap the *coro* :ref:`coroutine ` into a :class:`Task` and " -"schedule its execution. Return the Task object." -msgstr "" - -#: ../../library/asyncio-task.rst:246 -msgid "" -"The full function signature is largely the same as that of the :class:`Task` " -"constructor (or factory) - all of the keyword arguments to this function are " -"passed through to that interface." -msgstr "" - -#: ../../library/asyncio-task.rst:250 -msgid "" -"An optional keyword-only *context* argument allows specifying a " -"custom :class:`contextvars.Context` for the *coro* to run in. The current " -"context copy is created when no *context* is provided." -msgstr "" - -#: ../../library/asyncio-task.rst:254 -msgid "" -"An optional keyword-only *eager_start* argument allows specifying if the " -"task should execute eagerly during the call to create_task, or be scheduled " -"later. If *eager_start* is not passed the mode set " -"by :meth:`loop.set_task_factory` will be used." -msgstr "" - -#: ../../library/asyncio-task.rst:259 -msgid "" -"The task is executed in the loop returned " -"by :func:`get_running_loop`, :exc:`RuntimeError` is raised if there is no " -"running loop in current thread." -msgstr "" - -#: ../../library/asyncio-task.rst:265 -msgid "" -":meth:`asyncio.TaskGroup.create_task` is a new alternative leveraging " -"structural concurrency; it allows for waiting for a group of related tasks " -"with strong safety guarantees." -msgstr "" - -#: ../../library/asyncio-task.rst:271 -msgid "" -"Save a reference to the result of this function, to avoid a task " -"disappearing mid-execution. The event loop only keeps weak references to " -"tasks. A task that isn't referenced elsewhere may get garbage collected at " -"any time, even before it's done. For reliable \"fire-and-forget\" background " -"tasks, gather them in a collection::" -msgstr "" - -#: ../../library/asyncio-task.rst:278 -msgid "" -"background_tasks = set()\n" -"\n" -"for i in range(10):\n" -" task = asyncio.create_task(some_coro(param=i))\n" -"\n" -" # Add task to the set. This creates a strong reference.\n" -" background_tasks.add(task)\n" -"\n" -" # To prevent keeping references to finished tasks forever,\n" -" # make each task remove its own reference from the set after\n" -" # completion:\n" -" task.add_done_callback(background_tasks.discard)" -msgstr "" - -#: ../../library/asyncio-task.rst:293 ../../library/asyncio-task.rst:1251 -msgid "Added the *name* parameter." -msgstr "新增 *name* 參數。" - -#: ../../library/asyncio-task.rst:296 ../../library/asyncio-task.rst:1258 -msgid "Added the *context* parameter." -msgstr "新增 *context* 參數。" - -#: ../../library/asyncio-task.rst:299 -msgid "Added the *eager_start* parameter by passing on all *kwargs*." -msgstr "" - -#: ../../library/asyncio-task.rst:304 -msgid "Task Cancellation" -msgstr "" - -#: ../../library/asyncio-task.rst:306 -msgid "" -"Tasks can easily and safely be cancelled. When a task is " -"cancelled, :exc:`asyncio.CancelledError` will be raised in the task at the " -"next opportunity." -msgstr "" - -#: ../../library/asyncio-task.rst:310 -msgid "" -"It is recommended that coroutines use ``try/finally`` blocks to robustly " -"perform clean-up logic. In case :exc:`asyncio.CancelledError` is explicitly " -"caught, it should generally be propagated when clean-up is " -"complete. :exc:`asyncio.CancelledError` directly " -"subclasses :exc:`BaseException` so most code will not need to be aware of it." -msgstr "" - -#: ../../library/asyncio-task.rst:316 -msgid "" -"The asyncio components that enable structured concurrency, " -"like :class:`asyncio.TaskGroup` and :func:`asyncio.timeout`, are implemented " -"using cancellation internally and might misbehave if a coroutine " -"swallows :exc:`asyncio.CancelledError`. Similarly, user code should not " -"generally call :meth:`uncancel `. However, in cases " -"when suppressing :exc:`asyncio.CancelledError` is truly desired, it is " -"necessary to also call ``uncancel()`` to completely remove the cancellation " -"state." -msgstr "" - -#: ../../library/asyncio-task.rst:328 -msgid "Task Groups" -msgstr "" - -#: ../../library/asyncio-task.rst:330 -msgid "" -"Task groups combine a task creation API with a convenient and reliable way " -"to wait for all tasks in the group to finish." -msgstr "" - -#: ../../library/asyncio-task.rst:335 -msgid "" -"An :ref:`asynchronous context manager ` holding a " -"group of tasks. Tasks can be added to the group using :meth:`create_task`. " -"All tasks are awaited when the context manager exits." -msgstr "" - -#: ../../library/asyncio-task.rst:344 -msgid "" -"Create a task in this task group. The signature matches that " -"of :func:`asyncio.create_task`. If the task group is inactive (e.g. not yet " -"entered, already finished, or in the process of shutting down), we will " -"close the given ``coro``." -msgstr "" - -#: ../../library/asyncio-task.rst:352 -msgid "Close the given coroutine if the task group is not active." -msgstr "" - -#: ../../library/asyncio-task.rst:356 -msgid "Passes on all *kwargs* to :meth:`loop.create_task`" -msgstr "" - -#: ../../library/asyncio-task.rst:358 ../../library/asyncio-task.rst:564 -#: ../../library/asyncio-task.rst:737 ../../library/asyncio-task.rst:795 -#: ../../library/asyncio-task.rst:821 ../../library/asyncio-task.rst:862 -msgid "Example::" -msgstr "範例： ::" - -#: ../../library/asyncio-task.rst:360 -msgid "" -"async def main():\n" -" async with asyncio.TaskGroup() as tg:\n" -" task1 = tg.create_task(some_coro(...))\n" -" task2 = tg.create_task(another_coro(...))\n" -" print(f\"Both tasks have completed now: {task1.result()}, " -"{task2.result()}\")" -msgstr "" -"async def main():\n" -" async with asyncio.TaskGroup() as tg:\n" -" task1 = tg.create_task(some_coro(...))\n" -" task2 = tg.create_task(another_coro(...))\n" -" print(f\"Both tasks have completed now: {task1.result()}, " -"{task2.result()}\")" - -#: ../../library/asyncio-task.rst:366 -msgid "" -"The ``async with`` statement will wait for all tasks in the group to finish. " -"While waiting, new tasks may still be added to the group (for example, by " -"passing ``tg`` into one of the coroutines and calling ``tg.create_task()`` " -"in that coroutine). Once the last task has finished and the ``async with`` " -"block is exited, no new tasks may be added to the group." -msgstr "" - -#: ../../library/asyncio-task.rst:373 -msgid "" -"The first time any of the tasks belonging to the group fails with an " -"exception other than :exc:`asyncio.CancelledError`, the remaining tasks in " -"the group are cancelled. No further tasks can then be added to the group. At " -"this point, if the body of the ``async with`` statement is still active " -"(i.e., :meth:`~object.__aexit__` hasn't been called yet), the task directly " -"containing the ``async with`` statement is also cancelled. The " -"resulting :exc:`asyncio.CancelledError` will interrupt an ``await``, but it " -"will not bubble out of the containing ``async with`` statement." -msgstr "" - -#: ../../library/asyncio-task.rst:383 -msgid "" -"Once all tasks have finished, if any tasks have failed with an exception " -"other than :exc:`asyncio.CancelledError`, those exceptions are combined in " -"an :exc:`ExceptionGroup` or :exc:`BaseExceptionGroup` (as appropriate; see " -"their documentation) which is then raised." -msgstr "" - -#: ../../library/asyncio-task.rst:390 -msgid "" -"Two base exceptions are treated specially: If any task fails " -"with :exc:`KeyboardInterrupt` or :exc:`SystemExit`, the task group still " -"cancels the remaining tasks and waits for them, but then the " -"initial :exc:`KeyboardInterrupt` or :exc:`SystemExit` is re-raised instead " -"of :exc:`ExceptionGroup` or :exc:`BaseExceptionGroup`." -msgstr "" - -#: ../../library/asyncio-task.rst:396 -msgid "" -"If the body of the ``async with`` statement exits with an exception " -"(so :meth:`~object.__aexit__` is called with an exception set), this is " -"treated the same as if one of the tasks failed: the remaining tasks are " -"cancelled and then waited for, and non-cancellation exceptions are grouped " -"into an exception group and raised. The exception passed " -"into :meth:`~object.__aexit__`, unless it is :exc:`asyncio.CancelledError`, " -"is also included in the exception group. The same special case is made " -"for :exc:`KeyboardInterrupt` and :exc:`SystemExit` as in the previous " -"paragraph." -msgstr "" - -#: ../../library/asyncio-task.rst:408 -msgid "" -"Task groups are careful not to mix up the internal cancellation used to " -"\"wake up\" their :meth:`~object.__aexit__` with cancellation requests for " -"the task in which they are running made by other parties. In particular, " -"when one task group is syntactically nested in another, and both experience " -"an exception in one of their child tasks simultaneously, the inner task " -"group will process its exceptions, and then the outer task group will " -"receive another cancellation and process its own exceptions." -msgstr "" - -#: ../../library/asyncio-task.rst:416 -msgid "" -"In the case where a task group is cancelled externally and also must raise " -"an :exc:`ExceptionGroup`, it will call the parent " -"task's :meth:`~asyncio.Task.cancel` method. This ensures that " -"a :exc:`asyncio.CancelledError` will be raised at the next :keyword:`await`, " -"so the cancellation is not lost." -msgstr "" - -#: ../../library/asyncio-task.rst:422 -msgid "" -"Task groups preserve the cancellation count reported " -"by :meth:`asyncio.Task.cancelling`." -msgstr "" - -#: ../../library/asyncio-task.rst:427 -msgid "" -"Improved handling of simultaneous internal and external cancellations and " -"correct preservation of cancellation counts." -msgstr "" - -#: ../../library/asyncio-task.rst:431 -msgid "Terminating a Task Group" -msgstr "" - -#: ../../library/asyncio-task.rst:433 -msgid "" -"While terminating a task group is not natively supported by the standard " -"library, termination can be achieved by adding an exception-raising task to " -"the task group and ignoring the raised exception:" -msgstr "" - -#: ../../library/asyncio-task.rst:437 -msgid "" -"import asyncio\n" -"from asyncio import TaskGroup\n" -"\n" -"class TerminateTaskGroup(Exception):\n" -" \"\"\"Exception raised to terminate a task group.\"\"\"\n" -"\n" -"async def force_terminate_task_group():\n" -" \"\"\"Used to force termination of a task group.\"\"\"\n" -" raise TerminateTaskGroup()\n" -"\n" -"async def job(task_id, sleep_time):\n" -" print(f'Task {task_id}: start')\n" -" await asyncio.sleep(sleep_time)\n" -" print(f'Task {task_id}: done')\n" -"\n" -"async def main():\n" -" try:\n" -" async with TaskGroup() as group:\n" -" # spawn some tasks\n" -" group.create_task(job(1, 0.5))\n" -" group.create_task(job(2, 1.5))\n" -" # sleep for 1 second\n" -" await asyncio.sleep(1)\n" -" # add an exception-raising task to force the group to terminate\n" -" group.create_task(force_terminate_task_group())\n" -" except* TerminateTaskGroup:\n" -" pass\n" -"\n" -"asyncio.run(main())" -msgstr "" - -#: ../../library/asyncio-task.rst:469 -msgid "Expected output:" -msgstr "預期的輸出： ::" - -#: ../../library/asyncio-task.rst:471 -msgid "" -"Task 1: start\n" -"Task 2: start\n" -"Task 1: done" -msgstr "" -"Task 1: start\n" -"Task 2: start\n" -"Task 1: done" - -#: ../../library/asyncio-task.rst:478 -msgid "Sleeping" -msgstr "" - -#: ../../library/asyncio-task.rst:483 -msgid "Block for *delay* seconds." -msgstr "" - -#: ../../library/asyncio-task.rst:485 -msgid "" -"If *result* is provided, it is returned to the caller when the coroutine " -"completes." -msgstr "" - -#: ../../library/asyncio-task.rst:488 -msgid "" -"``sleep()`` always suspends the current task, allowing other tasks to run." -msgstr "" - -#: ../../library/asyncio-task.rst:491 -msgid "" -"Setting the delay to 0 provides an optimized path to allow other tasks to " -"run. This can be used by long-running functions to avoid blocking the event " -"loop for the full duration of the function call." -msgstr "" - -#: ../../library/asyncio-task.rst:497 -msgid "" -"Example of coroutine displaying the current date every second for 5 seconds::" -msgstr "" - -#: ../../library/asyncio-task.rst:500 -msgid "" -"import asyncio\n" -"import datetime\n" -"\n" -"async def display_date():\n" -" loop = asyncio.get_running_loop()\n" -" end_time = loop.time() + 5.0\n" -" while True:\n" -" print(datetime.datetime.now())\n" -" if (loop.time() + 1.0) >= end_time:\n" -" break\n" -" await asyncio.sleep(1)\n" -"\n" -"asyncio.run(display_date())" -msgstr "" -"import asyncio\n" -"import datetime\n" -"\n" -"async def display_date():\n" -" loop = asyncio.get_running_loop()\n" -" end_time = loop.time() + 5.0\n" -" while True:\n" -" print(datetime.datetime.now())\n" -" if (loop.time() + 1.0) >= end_time:\n" -" break\n" -" await asyncio.sleep(1)\n" -"\n" -"asyncio.run(display_date())" - -#: ../../library/asyncio-task.rst:515 ../../library/asyncio-task.rst:613 -#: ../../library/asyncio-task.rst:712 ../../library/asyncio-task.rst:887 -#: ../../library/asyncio-task.rst:942 ../../library/asyncio-task.rst:999 -msgid "Removed the *loop* parameter." -msgstr "移除 *loop* 參數。" - -#: ../../library/asyncio-task.rst:518 -msgid "Raises :exc:`ValueError` if *delay* is :data:`~math.nan`." -msgstr "如果 *delay* 是 :data:`~math.nan`，則引發 :exc:`ValueError`。" - -#: ../../library/asyncio-task.rst:523 -msgid "Running Tasks Concurrently" -msgstr "" - -#: ../../library/asyncio-task.rst:527 -msgid "" -"Run :ref:`awaitable objects ` in the *aws* sequence " -"*concurrently*." -msgstr "" - -#: ../../library/asyncio-task.rst:530 -msgid "" -"If any awaitable in *aws* is a coroutine, it is automatically scheduled as a " -"Task." -msgstr "" - -#: ../../library/asyncio-task.rst:533 -msgid "" -"If all awaitables are completed successfully, the result is an aggregate " -"list of returned values. The order of result values corresponds to the " -"order of awaitables in *aws*." -msgstr "" - -#: ../../library/asyncio-task.rst:537 -msgid "" -"If *return_exceptions* is ``False`` (default), the first raised exception is " -"immediately propagated to the task that awaits on ``gather()``. Other " -"awaitables in the *aws* sequence **won't be cancelled** and will continue to " -"run." -msgstr "" - -#: ../../library/asyncio-task.rst:542 -msgid "" -"If *return_exceptions* is ``True``, exceptions are treated the same as " -"successful results, and aggregated in the result list." -msgstr "" - -#: ../../library/asyncio-task.rst:545 -msgid "" -"If ``gather()`` is *cancelled*, all submitted awaitables (that have not " -"completed yet) are also *cancelled*." -msgstr "" - -#: ../../library/asyncio-task.rst:548 -msgid "" -"If any Task or Future from the *aws* sequence is *cancelled*, it is treated " -"as if it raised :exc:`CancelledError` -- the ``gather()`` call is **not** " -"cancelled in this case. This is to prevent the cancellation of one " -"submitted Task/Future to cause other Tasks/Futures to be cancelled." -msgstr "" - -#: ../../library/asyncio-task.rst:555 -msgid "" -"A new alternative to create and run tasks concurrently and wait for their " -"completion is :class:`asyncio.TaskGroup`. *TaskGroup* provides stronger " -"safety guarantees than *gather* for scheduling a nesting of subtasks: if a " -"task (or a subtask, a task scheduled by a task) raises an exception, " -"*TaskGroup* will, while *gather* will not, cancel the remaining scheduled " -"tasks)." -msgstr "" - -#: ../../library/asyncio-task.rst:566 -msgid "" -"import asyncio\n" -"\n" -"async def factorial(name, number):\n" -" f = 1\n" -" for i in range(2, number + 1):\n" -" print(f\"Task {name}: Compute factorial({number}), currently i={i}..." -"\")\n" -" await asyncio.sleep(1)\n" -" f *= i\n" -" print(f\"Task {name}: factorial({number}) = {f}\")\n" -" return f\n" -"\n" -"async def main():\n" -" # Schedule three calls *concurrently*:\n" -" L = await asyncio.gather(\n" -" factorial(\"A\", 2),\n" -" factorial(\"B\", 3),\n" -" factorial(\"C\", 4),\n" -" )\n" -" print(L)\n" -"\n" -"asyncio.run(main())\n" -"\n" -"# Expected output:\n" -"#\n" -"# Task A: Compute factorial(2), currently i=2...\n" -"# Task B: Compute factorial(3), currently i=2...\n" -"# Task C: Compute factorial(4), currently i=2...\n" -"# Task A: factorial(2) = 2\n" -"# Task B: Compute factorial(3), currently i=3...\n" -"# Task C: Compute factorial(4), currently i=3...\n" -"# Task B: factorial(3) = 6\n" -"# Task C: Compute factorial(4), currently i=4...\n" -"# Task C: factorial(4) = 24\n" -"# [2, 6, 24]" -msgstr "" - -#: ../../library/asyncio-task.rst:602 -msgid "" -"If *return_exceptions* is false, cancelling gather() after it has been " -"marked done won't cancel any submitted awaitables. For instance, gather can " -"be marked done after propagating an exception to the caller, therefore, " -"calling ``gather.cancel()`` after catching an exception (raised by one of " -"the awaitables) from gather won't cancel any other awaitables." -msgstr "" - -#: ../../library/asyncio-task.rst:609 -msgid "" -"If the *gather* itself is cancelled, the cancellation is propagated " -"regardless of *return_exceptions*." -msgstr "" - -#: ../../library/asyncio-task.rst:616 -msgid "" -"Deprecation warning is emitted if no positional arguments are provided or " -"not all positional arguments are Future-like objects and there is no running " -"event loop." -msgstr "" - -#: ../../library/asyncio-task.rst:625 -msgid "Eager Task Factory" -msgstr "" - -#: ../../library/asyncio-task.rst:629 -msgid "A task factory for eager task execution." -msgstr "" - -#: ../../library/asyncio-task.rst:631 -msgid "" -"When using this factory " -"(via :meth:`loop.set_task_factory(asyncio.eager_task_factory) " -"`), coroutines begin execution synchronously " -"during :class:`Task` construction. Tasks are only scheduled on the event " -"loop if they block. This can be a performance improvement as the overhead of " -"loop scheduling is avoided for coroutines that complete synchronously." -msgstr "" - -#: ../../library/asyncio-task.rst:637 -msgid "" -"A common example where this is beneficial is coroutines which employ caching " -"or memoization to avoid actual I/O when possible." -msgstr "" - -#: ../../library/asyncio-task.rst:642 -msgid "" -"Immediate execution of the coroutine is a semantic change. If the coroutine " -"returns or raises, the task is never scheduled to the event loop. If the " -"coroutine execution blocks, the task is scheduled to the event loop. This " -"change may introduce behavior changes to existing applications. For example, " -"the application's task execution order is likely to change." -msgstr "" - -#: ../../library/asyncio-task.rst:653 -msgid "" -"Create an eager task factory, similar to :func:`eager_task_factory`, using " -"the provided *custom_task_constructor* when creating a new task instead of " -"the default :class:`Task`." -msgstr "" - -#: ../../library/asyncio-task.rst:657 -msgid "" -"*custom_task_constructor* must be a *callable* with the signature matching " -"the signature of :class:`Task.__init__ `. The callable must return " -"a :class:`asyncio.Task`-compatible object." -msgstr "" - -#: ../../library/asyncio-task.rst:661 -msgid "" -"This function returns a *callable* intended to be used as a task factory of " -"an event loop via :meth:`loop.set_task_factory(factory) " -"`)." -msgstr "" - -#: ../../library/asyncio-task.rst:668 -msgid "Shielding From Cancellation" -msgstr "" - -#: ../../library/asyncio-task.rst:672 -msgid "" -"Protect an :ref:`awaitable object ` from " -"being :meth:`cancelled `." -msgstr "" - -#: ../../library/asyncio-task.rst:675 ../../library/asyncio-task.rst:842 -msgid "If *aw* is a coroutine it is automatically scheduled as a Task." -msgstr "" - -#: ../../library/asyncio-task.rst:677 -msgid "The statement::" -msgstr "" - -#: ../../library/asyncio-task.rst:679 -msgid "" -"task = asyncio.create_task(something())\n" -"res = await shield(task)" -msgstr "" -"task = asyncio.create_task(something())\n" -"res = await shield(task)" - -#: ../../library/asyncio-task.rst:682 -msgid "is equivalent to::" -msgstr "" - -#: ../../library/asyncio-task.rst:684 -msgid "res = await something()" -msgstr "res = await something()" - -#: ../../library/asyncio-task.rst:686 -msgid "" -"*except* that if the coroutine containing it is cancelled, the Task running " -"in ``something()`` is not cancelled. From the point of view of " -"``something()``, the cancellation did not happen. Although its caller is " -"still cancelled, so the \"await\" expression still raises " -"a :exc:`CancelledError`." -msgstr "" - -#: ../../library/asyncio-task.rst:692 -msgid "" -"If ``something()`` is cancelled by other means (i.e. from within itself) " -"that would also cancel ``shield()``." -msgstr "" - -#: ../../library/asyncio-task.rst:695 -msgid "" -"If it is desired to completely ignore cancellation (not recommended) the " -"``shield()`` function should be combined with a try/except clause, as " -"follows::" -msgstr "" - -#: ../../library/asyncio-task.rst:699 -msgid "" -"task = asyncio.create_task(something())\n" -"try:\n" -" res = await shield(task)\n" -"except CancelledError:\n" -" res = None" -msgstr "" -"task = asyncio.create_task(something())\n" -"try:\n" -" res = await shield(task)\n" -"except CancelledError:\n" -" res = None" - -#: ../../library/asyncio-task.rst:707 -msgid "" -"Save a reference to tasks passed to this function, to avoid a task " -"disappearing mid-execution. The event loop only keeps weak references to " -"tasks. A task that isn't referenced elsewhere may get garbage collected at " -"any time, even before it's done." -msgstr "" - -#: ../../library/asyncio-task.rst:715 -msgid "" -"Deprecation warning is emitted if *aw* is not Future-like object and there " -"is no running event loop." -msgstr "" - -#: ../../library/asyncio-task.rst:721 -msgid "Timeouts" -msgstr "" - -#: ../../library/asyncio-task.rst:725 -msgid "" -"Return an :ref:`asynchronous context manager ` that " -"can be used to limit the amount of time spent waiting on something." -msgstr "" - -#: ../../library/asyncio-task.rst:729 -msgid "" -"*delay* can either be ``None``, or a float/int number of seconds to wait. If " -"*delay* is ``None``, no time limit will be applied; this can be useful if " -"the delay is unknown when the context manager is created." -msgstr "" - -#: ../../library/asyncio-task.rst:734 -msgid "" -"In either case, the context manager can be rescheduled after creation " -"using :meth:`Timeout.reschedule`." -msgstr "" - -#: ../../library/asyncio-task.rst:739 -msgid "" -"async def main():\n" -" async with asyncio.timeout(10):\n" -" await long_running_task()" -msgstr "" -"async def main():\n" -" async with asyncio.timeout(10):\n" -" await long_running_task()" - -#: ../../library/asyncio-task.rst:743 -msgid "" -"If ``long_running_task`` takes more than 10 seconds to complete, the context " -"manager will cancel the current task and handle the " -"resulting :exc:`asyncio.CancelledError` internally, transforming it into " -"a :exc:`TimeoutError` which can be caught and handled." -msgstr "" - -#: ../../library/asyncio-task.rst:750 -msgid "" -"The :func:`asyncio.timeout` context manager is what transforms " -"the :exc:`asyncio.CancelledError` into a :exc:`TimeoutError`, which means " -"the :exc:`TimeoutError` can only be caught *outside* of the context manager." -msgstr "" - -#: ../../library/asyncio-task.rst:755 -msgid "Example of catching :exc:`TimeoutError`::" -msgstr "" - -#: ../../library/asyncio-task.rst:757 -msgid "" -"async def main():\n" -" try:\n" -" async with asyncio.timeout(10):\n" -" await long_running_task()\n" -" except TimeoutError:\n" -" print(\"The long operation timed out, but we've handled it.\")\n" -"\n" -" print(\"This statement will run regardless.\")" -msgstr "" - -#: ../../library/asyncio-task.rst:766 -msgid "" -"The context manager produced by :func:`asyncio.timeout` can be rescheduled " -"to a different deadline and inspected." -msgstr "" - -#: ../../library/asyncio-task.rst:771 -msgid "" -"An :ref:`asynchronous context manager ` for " -"cancelling overdue coroutines." -msgstr "" - -#: ../../library/asyncio-task.rst:774 -msgid "" -"``when`` should be an absolute time at which the context should time out, as " -"measured by the event loop's clock:" -msgstr "" - -#: ../../library/asyncio-task.rst:777 -msgid "If ``when`` is ``None``, the timeout will never trigger." -msgstr "" - -#: ../../library/asyncio-task.rst:778 -msgid "" -"If ``when < loop.time()``, the timeout will trigger on the next iteration of " -"the event loop." -msgstr "" - -#: ../../library/asyncio-task.rst:783 -msgid "" -"Return the current deadline, or ``None`` if the current deadline is not set." -msgstr "" - -#: ../../library/asyncio-task.rst:788 -msgid "Reschedule the timeout." -msgstr "" - -#: ../../library/asyncio-task.rst:792 -msgid "Return whether the context manager has exceeded its deadline (expired)." -msgstr "" - -#: ../../library/asyncio-task.rst:797 -msgid "" -"async def main():\n" -" try:\n" -" # We do not know the timeout when starting, so we pass ``None``.\n" -" async with asyncio.timeout(None) as cm:\n" -" # We know the timeout now, so we reschedule it.\n" -" new_deadline = get_running_loop().time() + 10\n" -" cm.reschedule(new_deadline)\n" -"\n" -" await long_running_task()\n" -" except TimeoutError:\n" -" pass\n" -"\n" -" if cm.expired():\n" -" print(\"Looks like we haven't finished on time.\")" -msgstr "" - -#: ../../library/asyncio-task.rst:812 -msgid "Timeout context managers can be safely nested." -msgstr "" - -#: ../../library/asyncio-task.rst:818 -msgid "" -"Similar to :func:`asyncio.timeout`, except *when* is the absolute time to " -"stop waiting, or ``None``." -msgstr "" - -#: ../../library/asyncio-task.rst:823 -msgid "" -"async def main():\n" -" loop = get_running_loop()\n" -" deadline = loop.time() + 20\n" -" try:\n" -" async with asyncio.timeout_at(deadline):\n" -" await long_running_task()\n" -" except TimeoutError:\n" -" print(\"The long operation timed out, but we've handled it.\")\n" -"\n" -" print(\"This statement will run regardless.\")" -msgstr "" - -#: ../../library/asyncio-task.rst:839 -msgid "" -"Wait for the *aw* :ref:`awaitable ` to complete with a " -"timeout." -msgstr "" - -#: ../../library/asyncio-task.rst:844 -msgid "" -"*timeout* can either be ``None`` or a float or int number of seconds to wait " -"for. If *timeout* is ``None``, block until the future completes." -msgstr "" - -#: ../../library/asyncio-task.rst:848 -msgid "" -"If a timeout occurs, it cancels the task and raises :exc:`TimeoutError`." -msgstr "" - -#: ../../library/asyncio-task.rst:851 -msgid "" -"To avoid the task :meth:`cancellation `, wrap it " -"in :func:`shield`." -msgstr "" - -#: ../../library/asyncio-task.rst:854 -msgid "" -"The function will wait until the future is actually cancelled, so the total " -"wait time may exceed the *timeout*. If an exception happens during " -"cancellation, it is propagated." -msgstr "" - -#: ../../library/asyncio-task.rst:858 -msgid "If the wait is cancelled, the future *aw* is also cancelled." -msgstr "" - -#: ../../library/asyncio-task.rst:864 -msgid "" -"async def eternity():\n" -" # Sleep for one hour\n" -" await asyncio.sleep(3600)\n" -" print('yay!')\n" -"\n" -"async def main():\n" -" # Wait for at most 1 second\n" -" try:\n" -" await asyncio.wait_for(eternity(), timeout=1.0)\n" -" except TimeoutError:\n" -" print('timeout!')\n" -"\n" -"asyncio.run(main())\n" -"\n" -"# Expected output:\n" -"#\n" -"# timeout!" -msgstr "" - -#: ../../library/asyncio-task.rst:882 -msgid "" -"When *aw* is cancelled due to a timeout, ``wait_for`` waits for *aw* to be " -"cancelled. Previously, it raised :exc:`TimeoutError` immediately." -msgstr "" - -#: ../../library/asyncio-task.rst:890 -msgid "Raises :exc:`TimeoutError` instead of :exc:`asyncio.TimeoutError`." -msgstr "引發 :exc:`TimeoutError` 而不是 :exc:`asyncio.TimeoutError`。" - -#: ../../library/asyncio-task.rst:895 -msgid "Waiting Primitives" -msgstr "" - -#: ../../library/asyncio-task.rst:900 -msgid "" -"Run :class:`~asyncio.Future` and :class:`~asyncio.Task` instances in the " -"*aws* iterable concurrently and block until the condition specified by " -"*return_when*." -msgstr "" - -#: ../../library/asyncio-task.rst:904 -msgid "The *aws* iterable must not be empty." -msgstr "" - -#: ../../library/asyncio-task.rst:906 -msgid "Returns two sets of Tasks/Futures: ``(done, pending)``." -msgstr "" - -#: ../../library/asyncio-task.rst:908 -msgid "Usage::" -msgstr "用法： ::" - -#: ../../library/asyncio-task.rst:910 -msgid "done, pending = await asyncio.wait(aws)" -msgstr "done, pending = await asyncio.wait(aws)" - -#: ../../library/asyncio-task.rst:912 -msgid "" -"*timeout* (a float or int), if specified, can be used to control the maximum " -"number of seconds to wait before returning." -msgstr "" - -#: ../../library/asyncio-task.rst:915 -msgid "" -"Note that this function does not raise :exc:`TimeoutError`. Futures or Tasks " -"that aren't done when the timeout occurs are simply returned in the second " -"set." -msgstr "" - -#: ../../library/asyncio-task.rst:919 -msgid "" -"*return_when* indicates when this function should return. It must be one of " -"the following constants:" -msgstr "" - -#: ../../library/asyncio-task.rst:925 -msgid "Constant" -msgstr "常數" - -#: ../../library/asyncio-task.rst:926 -msgid "Description" -msgstr "描述" - -#: ../../library/asyncio-task.rst:929 -msgid "The function will return when any future finishes or is cancelled." -msgstr "" - -#: ../../library/asyncio-task.rst:932 -msgid "" -"The function will return when any future finishes by raising an exception. " -"If no future raises an exception then it is equivalent " -"to :const:`ALL_COMPLETED`." -msgstr "" - -#: ../../library/asyncio-task.rst:937 -msgid "The function will return when all futures finish or are cancelled." -msgstr "" - -#: ../../library/asyncio-task.rst:939 -msgid "" -"Unlike :func:`~asyncio.wait_for`, ``wait()`` does not cancel the futures " -"when a timeout occurs." -msgstr "" - -#: ../../library/asyncio-task.rst:945 -msgid "Passing coroutine objects to ``wait()`` directly is forbidden." -msgstr "" - -#: ../../library/asyncio-task.rst:948 ../../library/asyncio-task.rst:1006 -msgid "Added support for generators yielding tasks." -msgstr "" - -#: ../../library/asyncio-task.rst:954 -msgid "" -"Run :ref:`awaitable objects ` in the *aws* iterable " -"concurrently. The returned object can be iterated to obtain the results of " -"the awaitables as they finish." -msgstr "" - -#: ../../library/asyncio-task.rst:958 -msgid "" -"The object returned by ``as_completed()`` can be iterated as " -"an :term:`asynchronous iterator` or a plain :term:`iterator`. When " -"asynchronous iteration is used, the originally-supplied awaitables are " -"yielded if they are tasks or futures. This makes it easy to correlate " -"previously-scheduled tasks with their results. Example::" -msgstr "" - -#: ../../library/asyncio-task.rst:964 -msgid "" -"ipv4_connect = create_task(open_connection(\"127.0.0.1\", 80))\n" -"ipv6_connect = create_task(open_connection(\"::1\", 80))\n" -"tasks = [ipv4_connect, ipv6_connect]\n" -"\n" -"async for earliest_connect in as_completed(tasks):\n" -" # earliest_connect is done. The result can be obtained by\n" -" # awaiting it or calling earliest_connect.result()\n" -" reader, writer = await earliest_connect\n" -"\n" -" if earliest_connect is ipv6_connect:\n" -" print(\"IPv6 connection established.\")\n" -" else:\n" -" print(\"IPv4 connection established.\")" -msgstr "" - -#: ../../library/asyncio-task.rst:978 -msgid "" -"During asynchronous iteration, implicitly-created tasks will be yielded for " -"supplied awaitables that aren't tasks or futures." -msgstr "" - -#: ../../library/asyncio-task.rst:981 -msgid "" -"When used as a plain iterator, each iteration yields a new coroutine that " -"returns the result or raises the exception of the next completed awaitable. " -"This pattern is compatible with Python versions older than 3.13::" -msgstr "" - -#: ../../library/asyncio-task.rst:985 -msgid "" -"ipv4_connect = create_task(open_connection(\"127.0.0.1\", 80))\n" -"ipv6_connect = create_task(open_connection(\"::1\", 80))\n" -"tasks = [ipv4_connect, ipv6_connect]\n" -"\n" -"for next_connect in as_completed(tasks):\n" -" # next_connect is not one of the original task objects. It must be\n" -" # awaited to obtain the result value or raise the exception of the\n" -" # awaitable that finishes next.\n" -" reader, writer = await next_connect" -msgstr "" - -#: ../../library/asyncio-task.rst:995 -msgid "" -"A :exc:`TimeoutError` is raised if the timeout occurs before all awaitables " -"are done. This is raised by the ``async for`` loop during asynchronous " -"iteration or by the coroutines yielded during plain iteration." -msgstr "" - -#: ../../library/asyncio-task.rst:1002 -msgid "" -"Deprecation warning is emitted if not all awaitable objects in the *aws* " -"iterable are Future-like objects and there is no running event loop." -msgstr "" - -#: ../../library/asyncio-task.rst:1009 -msgid "" -"The result can now be used as either an :term:`asynchronous iterator` or as " -"a plain :term:`iterator` (previously it was only a plain iterator)." -msgstr "" - -#: ../../library/asyncio-task.rst:1015 -msgid "Running in Threads" -msgstr "" - -#: ../../library/asyncio-task.rst:1020 -msgid "Asynchronously run function *func* in a separate thread." -msgstr "" - -#: ../../library/asyncio-task.rst:1022 -msgid "" -"Any \\*args and \\*\\*kwargs supplied for this function are directly passed " -"to *func*. Also, the current :class:`contextvars.Context` is propagated, " -"allowing context variables from the event loop thread to be accessed in the " -"separate thread." -msgstr "" - -#: ../../library/asyncio-task.rst:1027 -msgid "" -"Return a coroutine that can be awaited to get the eventual result of *func*." -msgstr "" - -#: ../../library/asyncio-task.rst:1029 -msgid "" -"This coroutine function is primarily intended to be used for executing IO-" -"bound functions/methods that would otherwise block the event loop if they " -"were run in the main thread. For example::" -msgstr "" - -#: ../../library/asyncio-task.rst:1033 -msgid "" -"def blocking_io():\n" -" print(f\"start blocking_io at {time.strftime('%X')}\")\n" -" # Note that time.sleep() can be replaced with any blocking\n" -" # IO-bound operation, such as file operations.\n" -" time.sleep(1)\n" -" print(f\"blocking_io complete at {time.strftime('%X')}\")\n" -"\n" -"async def main():\n" -" print(f\"started main at {time.strftime('%X')}\")\n" -"\n" -" await asyncio.gather(\n" -" asyncio.to_thread(blocking_io),\n" -" asyncio.sleep(1))\n" -"\n" -" print(f\"finished main at {time.strftime('%X')}\")\n" -"\n" -"\n" -"asyncio.run(main())\n" -"\n" -"# Expected output:\n" -"#\n" -"# started main at 19:50:53\n" -"# start blocking_io at 19:50:53\n" -"# blocking_io complete at 19:50:54\n" -"# finished main at 19:50:54" -msgstr "" - -#: ../../library/asyncio-task.rst:1059 -msgid "" -"Directly calling ``blocking_io()`` in any coroutine would block the event " -"loop for its duration, resulting in an additional 1 second of run time. " -"Instead, by using ``asyncio.to_thread()``, we can run it in a separate " -"thread without blocking the event loop." -msgstr "" - -#: ../../library/asyncio-task.rst:1066 -msgid "" -"Due to the :term:`GIL`, ``asyncio.to_thread()`` can typically only be used " -"to make IO-bound functions non-blocking. However, for extension modules that " -"release the GIL or alternative Python implementations that don't have one, " -"``asyncio.to_thread()`` can also be used for CPU-bound functions." -msgstr "" - -#: ../../library/asyncio-task.rst:1075 -msgid "Scheduling From Other Threads" -msgstr "" - -#: ../../library/asyncio-task.rst:1079 -msgid "Submit a coroutine to the given event loop. Thread-safe." -msgstr "" - -#: ../../library/asyncio-task.rst:1081 -msgid "" -"Return a :class:`concurrent.futures.Future` to wait for the result from " -"another OS thread." -msgstr "" - -#: ../../library/asyncio-task.rst:1084 -msgid "" -"This function is meant to be called from a different OS thread than the one " -"where the event loop is running. Example::" -msgstr "" - -#: ../../library/asyncio-task.rst:1087 -msgid "" -"def in_thread(loop: asyncio.AbstractEventLoop) -> None:\n" -" # Run some blocking IO\n" -" pathlib.Path(\"example.txt\").write_text(\"hello world\", " -"encoding=\"utf8\")\n" -"\n" -" # Create a coroutine\n" -" coro = asyncio.sleep(1, result=3)\n" -"\n" -" # Submit the coroutine to a given loop\n" -" future = asyncio.run_coroutine_threadsafe(coro, loop)\n" -"\n" -" # Wait for the result with an optional timeout argument\n" -" assert future.result(timeout=2) == 3\n" -"\n" -"async def amain() -> None:\n" -" # Get the running loop\n" -" loop = asyncio.get_running_loop()\n" -"\n" -" # Run something in a thread\n" -" await asyncio.to_thread(in_thread, loop)" -msgstr "" - -#: ../../library/asyncio-task.rst:1107 -msgid "It's also possible to run the other way around. Example::" -msgstr "" - -#: ../../library/asyncio-task.rst:1109 -msgid "" -"@contextlib.contextmanager\n" -"def loop_in_thread() -> Generator[asyncio.AbstractEventLoop]:\n" -" loop_fut = concurrent.futures.Future[asyncio.AbstractEventLoop]()\n" -" stop_event = asyncio.Event()\n" -"\n" -" async def main() -> None:\n" -" loop_fut.set_result(asyncio.get_running_loop())\n" -" await stop_event.wait()\n" -"\n" -" with concurrent.futures.ThreadPoolExecutor(1) as tpe:\n" -" complete_fut = tpe.submit(asyncio.run, main())\n" -" for fut in concurrent.futures.as_completed((loop_fut, " -"complete_fut)):\n" -" if fut is loop_fut:\n" -" loop = loop_fut.result()\n" -" try:\n" -" yield loop\n" -" finally:\n" -" loop.call_soon_threadsafe(stop_event.set)\n" -" else:\n" -" fut.result()\n" -"\n" -"# Create a loop in another thread\n" -"with loop_in_thread() as loop:\n" -" # Create a coroutine\n" -" coro = asyncio.sleep(1, result=3)\n" -"\n" -" # Submit the coroutine to a given loop\n" -" future = asyncio.run_coroutine_threadsafe(coro, loop)\n" -"\n" -" # Wait for the result with an optional timeout argument\n" -" assert future.result(timeout=2) == 3" -msgstr "" - -#: ../../library/asyncio-task.rst:1141 -msgid "" -"If an exception is raised in the coroutine, the returned Future will be " -"notified. It can also be used to cancel the task in the event loop::" -msgstr "" - -#: ../../library/asyncio-task.rst:1145 -msgid "" -"try:\n" -" result = future.result(timeout)\n" -"except TimeoutError:\n" -" print('The coroutine took too long, cancelling the task...')\n" -" future.cancel()\n" -"except Exception as exc:\n" -" print(f'The coroutine raised an exception: {exc!r}')\n" -"else:\n" -" print(f'The coroutine returned: {result!r}')" -msgstr "" - -#: ../../library/asyncio-task.rst:1155 -msgid "" -"See the :ref:`concurrency and multithreading ` " -"section of the documentation." -msgstr "" - -#: ../../library/asyncio-task.rst:1158 -msgid "" -"Unlike other asyncio functions this function requires the *loop* argument to " -"be passed explicitly." -msgstr "" - -#: ../../library/asyncio-task.rst:1165 -msgid "Introspection" -msgstr "" - -#: ../../library/asyncio-task.rst:1170 -msgid "" -"Return the currently running :class:`Task` instance, or ``None`` if no task " -"is running." -msgstr "" - -#: ../../library/asyncio-task.rst:1173 -msgid "" -"If *loop* is ``None`` :func:`get_running_loop` is used to get the current " -"loop." -msgstr "" - -#: ../../library/asyncio-task.rst:1181 -msgid "Return a set of not yet finished :class:`Task` objects run by the loop." -msgstr "" - -#: ../../library/asyncio-task.rst:1184 -msgid "" -"If *loop* is ``None``, :func:`get_running_loop` is used for getting current " -"loop." -msgstr "" - -#: ../../library/asyncio-task.rst:1192 -msgid "Return ``True`` if *obj* is a coroutine object." -msgstr "" - -#: ../../library/asyncio-task.rst:1199 -msgid "Task Object" -msgstr "Task 物件" - -#: ../../library/asyncio-task.rst:1203 -msgid "" -"A :class:`Future-like ` object that runs a Python :ref:`coroutine " -"`. Not thread-safe." -msgstr "" - -#: ../../library/asyncio-task.rst:1206 -msgid "" -"Tasks are used to run coroutines in event loops. If a coroutine awaits on a " -"Future, the Task suspends the execution of the coroutine and waits for the " -"completion of the Future. When the Future is *done*, the execution of the " -"wrapped coroutine resumes." -msgstr "" - -#: ../../library/asyncio-task.rst:1212 -msgid "" -"Event loops use cooperative scheduling: an event loop runs one Task at a " -"time. While a Task awaits for the completion of a Future, the event loop " -"runs other Tasks, callbacks, or performs IO operations." -msgstr "" - -#: ../../library/asyncio-task.rst:1217 -msgid "" -"Use the high-level :func:`asyncio.create_task` function to create Tasks, or " -"the low-level :meth:`loop.create_task` or :func:`ensure_future` functions. " -"Manual instantiation of Tasks is discouraged." -msgstr "" - -#: ../../library/asyncio-task.rst:1222 -msgid "" -"To cancel a running Task use the :meth:`cancel` method. Calling it will " -"cause the Task to throw a :exc:`CancelledError` exception into the wrapped " -"coroutine. If a coroutine is awaiting on a Future object during " -"cancellation, the Future object will be cancelled." -msgstr "" - -#: ../../library/asyncio-task.rst:1227 -msgid "" -":meth:`cancelled` can be used to check if the Task was cancelled. The method " -"returns ``True`` if the wrapped coroutine did not suppress " -"the :exc:`CancelledError` exception and was actually cancelled." -msgstr "" - -#: ../../library/asyncio-task.rst:1232 -msgid "" -":class:`asyncio.Task` inherits from :class:`Future` all of its APIs " -"except :meth:`Future.set_result` and :meth:`Future.set_exception`." -msgstr "" - -#: ../../library/asyncio-task.rst:1236 -msgid "" -"An optional keyword-only *context* argument allows specifying a " -"custom :class:`contextvars.Context` for the *coro* to run in. If no " -"*context* is provided, the Task copies the current context and later runs " -"its coroutine in the copied context." -msgstr "" - -#: ../../library/asyncio-task.rst:1241 -msgid "" -"An optional keyword-only *eager_start* argument allows eagerly starting the " -"execution of the :class:`asyncio.Task` at task creation time. If set to " -"``True`` and the event loop is running, the task will start executing the " -"coroutine immediately, until the first time the coroutine blocks. If the " -"coroutine returns or raises without blocking, the task will be finished " -"eagerly and will skip scheduling to the event loop." -msgstr "" - -#: ../../library/asyncio-task.rst:1248 -msgid "Added support for the :mod:`contextvars` module." -msgstr "新增對 :mod:`contextvars` 模組的支援。" - -#: ../../library/asyncio-task.rst:1254 -msgid "" -"Deprecation warning is emitted if *loop* is not specified and there is no " -"running event loop." -msgstr "" - -#: ../../library/asyncio-task.rst:1261 -msgid "Added the *eager_start* parameter." -msgstr "新增 *eager_start* 參數。" - -#: ../../library/asyncio-task.rst:1266 -msgid "Return ``True`` if the Task is *done*." -msgstr "" - -#: ../../library/asyncio-task.rst:1268 -msgid "" -"A Task is *done* when the wrapped coroutine either returned a value, raised " -"an exception, or the Task was cancelled." -msgstr "" - -#: ../../library/asyncio-task.rst:1273 -msgid "Return the result of the Task." -msgstr "" - -#: ../../library/asyncio-task.rst:1275 -msgid "" -"If the Task is *done*, the result of the wrapped coroutine is returned (or " -"if the coroutine raised an exception, that exception is re-raised.)" -msgstr "" - -#: ../../library/asyncio-task.rst:1279 ../../library/asyncio-task.rst:1293 -msgid "" -"If the Task has been *cancelled*, this method raises a :exc:`CancelledError` " -"exception." -msgstr "" - -#: ../../library/asyncio-task.rst:1282 -msgid "" -"If the Task's result isn't yet available, this method raises " -"an :exc:`InvalidStateError` exception." -msgstr "" - -#: ../../library/asyncio-task.rst:1287 -msgid "Return the exception of the Task." -msgstr "" - -#: ../../library/asyncio-task.rst:1289 -msgid "" -"If the wrapped coroutine raised an exception that exception is returned. If " -"the wrapped coroutine returned normally this method returns ``None``." -msgstr "" - -#: ../../library/asyncio-task.rst:1296 -msgid "" -"If the Task isn't *done* yet, this method raises an :exc:`InvalidStateError` " -"exception." -msgstr "" - -#: ../../library/asyncio-task.rst:1301 -msgid "Add a callback to be run when the Task is *done*." -msgstr "" - -#: ../../library/asyncio-task.rst:1303 ../../library/asyncio-task.rst:1312 -msgid "This method should only be used in low-level callback-based code." -msgstr "" - -#: ../../library/asyncio-task.rst:1305 -msgid "" -"See the documentation of :meth:`Future.add_done_callback` for more details." -msgstr "" - -#: ../../library/asyncio-task.rst:1310 -msgid "Remove *callback* from the callbacks list." -msgstr "" - -#: ../../library/asyncio-task.rst:1314 -msgid "" -"See the documentation of :meth:`Future.remove_done_callback` for more " -"details." -msgstr "" - -#: ../../library/asyncio-task.rst:1319 -msgid "Return the list of stack frames for this Task." -msgstr "" - -#: ../../library/asyncio-task.rst:1321 -msgid "" -"If the wrapped coroutine is not done, this returns the stack where it is " -"suspended. If the coroutine has completed successfully or was cancelled, " -"this returns an empty list. If the coroutine was terminated by an exception, " -"this returns the list of traceback frames." -msgstr "" - -#: ../../library/asyncio-task.rst:1327 -msgid "The frames are always ordered from oldest to newest." -msgstr "" - -#: ../../library/asyncio-task.rst:1329 -msgid "Only one stack frame is returned for a suspended coroutine." -msgstr "" - -#: ../../library/asyncio-task.rst:1331 -msgid "" -"The optional *limit* argument sets the maximum number of frames to return; " -"by default all available frames are returned. The ordering of the returned " -"list differs depending on whether a stack or a traceback is returned: the " -"newest frames of a stack are returned, but the oldest frames of a traceback " -"are returned. (This matches the behavior of the traceback module.)" -msgstr "" - -#: ../../library/asyncio-task.rst:1340 -msgid "Print the stack or traceback for this Task." -msgstr "" - -#: ../../library/asyncio-task.rst:1342 -msgid "" -"This produces output similar to that of the traceback module for the frames " -"retrieved by :meth:`get_stack`." -msgstr "" - -#: ../../library/asyncio-task.rst:1345 -msgid "The *limit* argument is passed to :meth:`get_stack` directly." -msgstr "" - -#: ../../library/asyncio-task.rst:1347 -msgid "" -"The *file* argument is an I/O stream to which the output is written; by " -"default output is written to :data:`sys.stdout`." -msgstr "" - -#: ../../library/asyncio-task.rst:1352 -msgid "Return the coroutine object wrapped by the :class:`Task`." -msgstr "" - -#: ../../library/asyncio-task.rst:1356 -msgid "" -"This will return ``None`` for Tasks which have already completed eagerly. " -"See the :ref:`Eager Task Factory `." -msgstr "" - -#: ../../library/asyncio-task.rst:1363 -msgid "Newly added eager task execution means result may be ``None``." -msgstr "" - -#: ../../library/asyncio-task.rst:1367 -msgid "" -"Return the :class:`contextvars.Context` object associated with the task." -msgstr "" - -#: ../../library/asyncio-task.rst:1374 -msgid "Return the name of the Task." -msgstr "" - -#: ../../library/asyncio-task.rst:1376 -msgid "" -"If no name has been explicitly assigned to the Task, the default asyncio " -"Task implementation generates a default name during instantiation." -msgstr "" - -#: ../../library/asyncio-task.rst:1384 -msgid "Set the name of the Task." -msgstr "" - -#: ../../library/asyncio-task.rst:1386 -msgid "" -"The *value* argument can be any object, which is then converted to a string." -msgstr "" - -#: ../../library/asyncio-task.rst:1389 -msgid "" -"In the default Task implementation, the name will be visible in " -"the :func:`repr` output of a task object." -msgstr "" - -#: ../../library/asyncio-task.rst:1396 -msgid "Request the Task to be cancelled." -msgstr "" - -#: ../../library/asyncio-task.rst:1398 -msgid "" -"If the Task is already *done* or *cancelled*, return ``False``, otherwise, " -"return ``True``." -msgstr "" - -#: ../../library/asyncio-task.rst:1401 -msgid "" -"The method arranges for a :exc:`CancelledError` exception to be thrown into " -"the wrapped coroutine on the next cycle of the event loop." -msgstr "" - -#: ../../library/asyncio-task.rst:1404 -msgid "" -"The coroutine then has a chance to clean up or even deny the request by " -"suppressing the exception with a :keyword:`try` ... ... ``except " -"CancelledError`` ... :keyword:`finally` block. Therefore, " -"unlike :meth:`Future.cancel`, :meth:`Task.cancel` does not guarantee that " -"the Task will be cancelled, although suppressing cancellation completely is " -"not common and is actively discouraged. Should the coroutine nevertheless " -"decide to suppress the cancellation, it needs to call :meth:`Task.uncancel` " -"in addition to catching the exception." -msgstr "" - -#: ../../library/asyncio-task.rst:1414 -msgid "Added the *msg* parameter." -msgstr "新增 *msg* 參數。" - -#: ../../library/asyncio-task.rst:1417 -msgid "The ``msg`` parameter is propagated from cancelled task to its awaiter." -msgstr "" - -#: ../../library/asyncio-task.rst:1422 -msgid "" -"The following example illustrates how coroutines can intercept the " -"cancellation request::" -msgstr "" - -#: ../../library/asyncio-task.rst:1425 -msgid "" -"async def cancel_me():\n" -" print('cancel_me(): before sleep')\n" -"\n" -" try:\n" -" # Wait for 1 hour\n" -" await asyncio.sleep(3600)\n" -" except asyncio.CancelledError:\n" -" print('cancel_me(): cancel sleep')\n" -" raise\n" -" finally:\n" -" print('cancel_me(): after sleep')\n" -"\n" -"async def main():\n" -" # Create a \"cancel_me\" Task\n" -" task = asyncio.create_task(cancel_me())\n" -"\n" -" # Wait for 1 second\n" -" await asyncio.sleep(1)\n" -"\n" -" task.cancel()\n" -" try:\n" -" await task\n" -" except asyncio.CancelledError:\n" -" print(\"main(): cancel_me is cancelled now\")\n" -"\n" -"asyncio.run(main())\n" -"\n" -"# Expected output:\n" -"#\n" -"# cancel_me(): before sleep\n" -"# cancel_me(): cancel sleep\n" -"# cancel_me(): after sleep\n" -"# main(): cancel_me is cancelled now" -msgstr "" - -#: ../../library/asyncio-task.rst:1461 -msgid "Return ``True`` if the Task is *cancelled*." -msgstr "" - -#: ../../library/asyncio-task.rst:1463 -msgid "" -"The Task is *cancelled* when the cancellation was requested " -"with :meth:`cancel` and the wrapped coroutine propagated " -"the :exc:`CancelledError` exception thrown into it." -msgstr "" - -#: ../../library/asyncio-task.rst:1469 -msgid "Decrement the count of cancellation requests to this Task." -msgstr "" - -#: ../../library/asyncio-task.rst:1471 -msgid "Returns the remaining number of cancellation requests." -msgstr "" - -#: ../../library/asyncio-task.rst:1473 -msgid "" -"Note that once execution of a cancelled task completed, further calls " -"to :meth:`uncancel` are ineffective." -msgstr "" - -#: ../../library/asyncio-task.rst:1478 -msgid "" -"This method is used by asyncio's internals and isn't expected to be used by " -"end-user code. In particular, if a Task gets successfully uncancelled, this " -"allows for elements of structured concurrency like :ref:`taskgroups` " -"and :func:`asyncio.timeout` to continue running, isolating cancellation to " -"the respective structured block. For example::" -msgstr "" - -#: ../../library/asyncio-task.rst:1485 -msgid "" -"async def make_request_with_timeout():\n" -" try:\n" -" async with asyncio.timeout(1):\n" -" # Structured block affected by the timeout:\n" -" await make_request()\n" -" await make_another_request()\n" -" except TimeoutError:\n" -" log(\"There was a timeout\")\n" -" # Outer code not affected by the timeout:\n" -" await unrelated_code()" -msgstr "" - -#: ../../library/asyncio-task.rst:1496 -msgid "" -"While the block with ``make_request()`` and ``make_another_request()`` might " -"get cancelled due to the timeout, ``unrelated_code()`` should continue " -"running even in case of the timeout. This is implemented " -"with :meth:`uncancel`. :class:`TaskGroup` context managers " -"use :func:`uncancel` in a similar fashion." -msgstr "" - -#: ../../library/asyncio-task.rst:1502 -msgid "" -"If end-user code is, for some reason, suppressing cancellation by " -"catching :exc:`CancelledError`, it needs to call this method to remove the " -"cancellation state." -msgstr "" - -#: ../../library/asyncio-task.rst:1506 -msgid "" -"When this method decrements the cancellation count to zero, the method " -"checks if a previous :meth:`cancel` call had arranged " -"for :exc:`CancelledError` to be thrown into the task. If it hasn't been " -"thrown yet, that arrangement will be rescinded (by resetting the internal " -"``_must_cancel`` flag)." -msgstr "" - -#: ../../library/asyncio-task.rst:1512 -msgid "Changed to rescind pending cancellation requests upon reaching zero." -msgstr "" - -#: ../../library/asyncio-task.rst:1517 -msgid "" -"Return the number of pending cancellation requests to this Task, i.e., the " -"number of calls to :meth:`cancel` less the number of :meth:`uncancel` calls." -msgstr "" - -#: ../../library/asyncio-task.rst:1521 -msgid "" -"Note that if this number is greater than zero but the Task is still " -"executing, :meth:`cancelled` will still return ``False``. This is because " -"this number can be lowered by calling :meth:`uncancel`, which can lead to " -"the task not being cancelled after all if the cancellation requests go down " -"to zero." -msgstr "" - -#: ../../library/asyncio-task.rst:1527 -msgid "" -"This method is used by asyncio's internals and isn't expected to be used by " -"end-user code. See :meth:`uncancel` for more details." -msgstr "" - -#~ msgid "" -#~ "for coro in as_completed(aws):\n" -#~ " earliest_result = await coro\n" -#~ " # ..." -#~ msgstr "" -#~ "for coro in as_completed(aws):\n" -#~ " earliest_result = await coro\n" -#~ " # ..." - -#~ msgid ":const:`FIRST_COMPLETED`" -#~ msgstr ":const:`FIRST_COMPLETED`" - -#~ msgid ":const:`FIRST_EXCEPTION`" -#~ msgstr ":const:`FIRST_EXCEPTION`" - -#~ msgid ":const:`ALL_COMPLETED`" -#~ msgstr ":const:`ALL_COMPLETED`" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: 2018-05-23 14:39+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/asyncio-task.rst:6 +msgid "Coroutines and Tasks" +msgstr "協程與任務" + +#: ../../library/asyncio-task.rst:8 +msgid "" +"This section outlines high-level asyncio APIs to work with coroutines and " +"Tasks." +msgstr "" + +#: ../../library/asyncio-task.rst:19 ../../library/asyncio-task.rst:148 +msgid "Coroutines" +msgstr "協程" + +#: ../../library/asyncio-task.rst:21 +msgid "**Source code:** :source:`Lib/asyncio/coroutines.py`" +msgstr "**原始碼：**\\ :source:`Lib/asyncio/coroutines.py`" + +#: ../../library/asyncio-task.rst:25 +msgid "" +":term:`Coroutines ` declared with the async/await syntax is the " +"preferred way of writing asyncio applications. For example, the following " +"snippet of code prints \"hello\", waits 1 second, and then prints \"world\"::" +msgstr "" + +#: ../../library/asyncio-task.rst:30 +msgid "" +">>> import asyncio\n" +"\n" +">>> async def main():\n" +"... print('hello')\n" +"... await asyncio.sleep(1)\n" +"... print('world')\n" +"\n" +">>> asyncio.run(main())\n" +"hello\n" +"world" +msgstr "" +">>> import asyncio\n" +"\n" +">>> async def main():\n" +"... print('hello')\n" +"... await asyncio.sleep(1)\n" +"... print('world')\n" +"\n" +">>> asyncio.run(main())\n" +"hello\n" +"world" + +#: ../../library/asyncio-task.rst:41 +msgid "" +"Note that simply calling a coroutine will not schedule it to be executed::" +msgstr "" + +#: ../../library/asyncio-task.rst:44 +msgid "" +">>> main()\n" +"" +msgstr "" +">>> main()\n" +"" + +#: ../../library/asyncio-task.rst:47 +msgid "To actually run a coroutine, asyncio provides the following mechanisms:" +msgstr "" + +#: ../../library/asyncio-task.rst:49 +msgid "" +"The :func:`asyncio.run` function to run the top-level entry point \"main()\" " +"function (see the above example.)" +msgstr "" + +#: ../../library/asyncio-task.rst:52 +msgid "" +"Awaiting on a coroutine. The following snippet of code will print \"hello\" " +"after waiting for 1 second, and then print \"world\" after waiting for " +"*another* 2 seconds::" +msgstr "" + +#: ../../library/asyncio-task.rst:56 +msgid "" +"import asyncio\n" +"import time\n" +"\n" +"async def say_after(delay, what):\n" +" await asyncio.sleep(delay)\n" +" print(what)\n" +"\n" +"async def main():\n" +" print(f\"started at {time.strftime('%X')}\")\n" +"\n" +" await say_after(1, 'hello')\n" +" await say_after(2, 'world')\n" +"\n" +" print(f\"finished at {time.strftime('%X')}\")\n" +"\n" +"asyncio.run(main())" +msgstr "" +"import asyncio\n" +"import time\n" +"\n" +"async def say_after(delay, what):\n" +" await asyncio.sleep(delay)\n" +" print(what)\n" +"\n" +"async def main():\n" +" print(f\"started at {time.strftime('%X')}\")\n" +"\n" +" await say_after(1, 'hello')\n" +" await say_after(2, 'world')\n" +"\n" +" print(f\"finished at {time.strftime('%X')}\")\n" +"\n" +"asyncio.run(main())" + +#: ../../library/asyncio-task.rst:73 +msgid "Expected output::" +msgstr "預期的輸出： ::" + +#: ../../library/asyncio-task.rst:75 +msgid "" +"started at 17:13:52\n" +"hello\n" +"world\n" +"finished at 17:13:55" +msgstr "" +"started at 17:13:52\n" +"hello\n" +"world\n" +"finished at 17:13:55" + +#: ../../library/asyncio-task.rst:80 +msgid "" +"The :func:`asyncio.create_task` function to run coroutines concurrently as " +"asyncio :class:`Tasks `." +msgstr "" + +#: ../../library/asyncio-task.rst:83 +msgid "" +"Let's modify the above example and run two ``say_after`` coroutines " +"*concurrently*::" +msgstr "" + +#: ../../library/asyncio-task.rst:86 +msgid "" +"async def main():\n" +" task1 = asyncio.create_task(\n" +" say_after(1, 'hello'))\n" +"\n" +" task2 = asyncio.create_task(\n" +" say_after(2, 'world'))\n" +"\n" +" print(f\"started at {time.strftime('%X')}\")\n" +"\n" +" # Wait until both tasks are completed (should take\n" +" # around 2 seconds.)\n" +" await task1\n" +" await task2\n" +"\n" +" print(f\"finished at {time.strftime('%X')}\")" +msgstr "" + +#: ../../library/asyncio-task.rst:102 +msgid "" +"Note that expected output now shows that the snippet runs 1 second faster " +"than before::" +msgstr "" + +#: ../../library/asyncio-task.rst:105 +msgid "" +"started at 17:14:32\n" +"hello\n" +"world\n" +"finished at 17:14:34" +msgstr "" +"started at 17:14:32\n" +"hello\n" +"world\n" +"finished at 17:14:34" + +#: ../../library/asyncio-task.rst:110 +msgid "" +"The :class:`asyncio.TaskGroup` class provides a more modern alternative " +"to :func:`create_task`. Using this API, the last example becomes::" +msgstr "" + +#: ../../library/asyncio-task.rst:114 +msgid "" +"async def main():\n" +" async with asyncio.TaskGroup() as tg:\n" +" task1 = tg.create_task(\n" +" say_after(1, 'hello'))\n" +"\n" +" task2 = tg.create_task(\n" +" say_after(2, 'world'))\n" +"\n" +" print(f\"started at {time.strftime('%X')}\")\n" +"\n" +" # The await is implicit when the context manager exits.\n" +"\n" +" print(f\"finished at {time.strftime('%X')}\")" +msgstr "" + +#: ../../library/asyncio-task.rst:128 +msgid "The timing and output should be the same as for the previous version." +msgstr "" + +#: ../../library/asyncio-task.rst:130 +msgid ":class:`asyncio.TaskGroup`." +msgstr ":class:`asyncio.TaskGroup`。" + +#: ../../library/asyncio-task.rst:137 +msgid "Awaitables" +msgstr "" + +#: ../../library/asyncio-task.rst:139 +msgid "" +"We say that an object is an **awaitable** object if it can be used in " +"an :keyword:`await` expression. Many asyncio APIs are designed to accept " +"awaitables." +msgstr "" + +#: ../../library/asyncio-task.rst:143 +msgid "" +"There are three main types of *awaitable* objects: **coroutines**, " +"**Tasks**, and **Futures**." +msgstr "" + +#: ../../library/asyncio-task.rst:149 +msgid "" +"Python coroutines are *awaitables* and therefore can be awaited from other " +"coroutines::" +msgstr "" + +#: ../../library/asyncio-task.rst:152 +msgid "" +"import asyncio\n" +"\n" +"async def nested():\n" +" return 42\n" +"\n" +"async def main():\n" +" # Nothing happens if we just call \"nested()\".\n" +" # A coroutine object is created but not awaited,\n" +" # so it *won't run at all*.\n" +" nested() # will raise a \"RuntimeWarning\".\n" +"\n" +" # Let's do it differently now and await it:\n" +" print(await nested()) # will print \"42\".\n" +"\n" +"asyncio.run(main())" +msgstr "" + +#: ../../library/asyncio-task.rst:170 +msgid "" +"In this documentation the term \"coroutine\" can be used for two closely " +"related concepts:" +msgstr "" + +#: ../../library/asyncio-task.rst:173 +msgid "a *coroutine function*: an :keyword:`async def` function;" +msgstr "" + +#: ../../library/asyncio-task.rst:175 +msgid "" +"a *coroutine object*: an object returned by calling a *coroutine function*." +msgstr "" + +#: ../../library/asyncio-task.rst:180 +msgid "Tasks" +msgstr "" + +#: ../../library/asyncio-task.rst:181 +msgid "*Tasks* are used to schedule coroutines *concurrently*." +msgstr "" + +#: ../../library/asyncio-task.rst:183 +msgid "" +"When a coroutine is wrapped into a *Task* with functions " +"like :func:`asyncio.create_task` the coroutine is automatically scheduled to " +"run soon::" +msgstr "" + +#: ../../library/asyncio-task.rst:187 +msgid "" +"import asyncio\n" +"\n" +"async def nested():\n" +" return 42\n" +"\n" +"async def main():\n" +" # Schedule nested() to run soon concurrently\n" +" # with \"main()\".\n" +" task = asyncio.create_task(nested())\n" +"\n" +" # \"task\" can now be used to cancel \"nested()\", or\n" +" # can simply be awaited to wait until it is complete:\n" +" await task\n" +"\n" +"asyncio.run(main())" +msgstr "" + +#: ../../library/asyncio-task.rst:205 +msgid "Futures" +msgstr "" + +#: ../../library/asyncio-task.rst:206 +msgid "" +"A :class:`Future` is a special **low-level** awaitable object that " +"represents an **eventual result** of an asynchronous operation." +msgstr "" + +#: ../../library/asyncio-task.rst:209 +msgid "" +"When a Future object is *awaited* it means that the coroutine will wait " +"until the Future is resolved in some other place." +msgstr "" + +#: ../../library/asyncio-task.rst:212 +msgid "" +"Future objects in asyncio are needed to allow callback-based code to be used " +"with async/await." +msgstr "" + +#: ../../library/asyncio-task.rst:215 +msgid "" +"Normally **there is no need** to create Future objects at the application " +"level code." +msgstr "" + +#: ../../library/asyncio-task.rst:218 +msgid "" +"Future objects, sometimes exposed by libraries and some asyncio APIs, can be " +"awaited::" +msgstr "" + +#: ../../library/asyncio-task.rst:221 +msgid "" +"async def main():\n" +" await function_that_returns_a_future_object()\n" +"\n" +" # this is also valid:\n" +" await asyncio.gather(\n" +" function_that_returns_a_future_object(),\n" +" some_python_coroutine()\n" +" )" +msgstr "" + +#: ../../library/asyncio-task.rst:230 +msgid "" +"A good example of a low-level function that returns a Future object " +"is :meth:`loop.run_in_executor`." +msgstr "" + +#: ../../library/asyncio-task.rst:235 +msgid "Creating Tasks" +msgstr "" + +#: ../../library/asyncio-task.rst:237 +msgid "**Source code:** :source:`Lib/asyncio/tasks.py`" +msgstr "**原始碼：**\\ :source:`Lib/asyncio/tasks.py`" + +#: ../../library/asyncio-task.rst:243 +msgid "" +"Wrap the *coro* :ref:`coroutine ` into a :class:`Task` and " +"schedule its execution. Return the Task object." +msgstr "" + +#: ../../library/asyncio-task.rst:246 +msgid "" +"The full function signature is largely the same as that of the :class:`Task` " +"constructor (or factory) - all of the keyword arguments to this function are " +"passed through to that interface." +msgstr "" + +#: ../../library/asyncio-task.rst:250 +msgid "" +"An optional keyword-only *context* argument allows specifying a " +"custom :class:`contextvars.Context` for the *coro* to run in. The current " +"context copy is created when no *context* is provided." +msgstr "" + +#: ../../library/asyncio-task.rst:254 +msgid "" +"An optional keyword-only *eager_start* argument allows specifying if the " +"task should execute eagerly during the call to create_task, or be scheduled " +"later. If *eager_start* is not passed the mode set " +"by :meth:`loop.set_task_factory` will be used." +msgstr "" + +#: ../../library/asyncio-task.rst:259 +msgid "" +"The task is executed in the loop returned " +"by :func:`get_running_loop`, :exc:`RuntimeError` is raised if there is no " +"running loop in current thread." +msgstr "" + +#: ../../library/asyncio-task.rst:265 +msgid "" +":meth:`asyncio.TaskGroup.create_task` is a new alternative leveraging " +"structural concurrency; it allows for waiting for a group of related tasks " +"with strong safety guarantees." +msgstr "" + +#: ../../library/asyncio-task.rst:271 +msgid "" +"Save a reference to the result of this function, to avoid a task " +"disappearing mid-execution. The event loop only keeps weak references to " +"tasks. A task that isn't referenced elsewhere may get garbage collected at " +"any time, even before it's done. For reliable \"fire-and-forget\" background " +"tasks, gather them in a collection::" +msgstr "" + +#: ../../library/asyncio-task.rst:278 +msgid "" +"background_tasks = set()\n" +"\n" +"for i in range(10):\n" +" task = asyncio.create_task(some_coro(param=i))\n" +"\n" +" # Add task to the set. This creates a strong reference.\n" +" background_tasks.add(task)\n" +"\n" +" # To prevent keeping references to finished tasks forever,\n" +" # make each task remove its own reference from the set after\n" +" # completion:\n" +" task.add_done_callback(background_tasks.discard)" +msgstr "" + +#: ../../library/asyncio-task.rst:293 ../../library/asyncio-task.rst:1251 +msgid "Added the *name* parameter." +msgstr "新增 *name* 參數。" + +#: ../../library/asyncio-task.rst:296 ../../library/asyncio-task.rst:1258 +msgid "Added the *context* parameter." +msgstr "新增 *context* 參數。" + +#: ../../library/asyncio-task.rst:299 +msgid "Added the *eager_start* parameter by passing on all *kwargs*." +msgstr "" + +#: ../../library/asyncio-task.rst:304 +msgid "Task Cancellation" +msgstr "" + +#: ../../library/asyncio-task.rst:306 +msgid "" +"Tasks can easily and safely be cancelled. When a task is " +"cancelled, :exc:`asyncio.CancelledError` will be raised in the task at the " +"next opportunity." +msgstr "" + +#: ../../library/asyncio-task.rst:310 +msgid "" +"It is recommended that coroutines use ``try/finally`` blocks to robustly " +"perform clean-up logic. In case :exc:`asyncio.CancelledError` is explicitly " +"caught, it should generally be propagated when clean-up is " +"complete. :exc:`asyncio.CancelledError` directly " +"subclasses :exc:`BaseException` so most code will not need to be aware of it." +msgstr "" + +#: ../../library/asyncio-task.rst:316 +msgid "" +"The asyncio components that enable structured concurrency, " +"like :class:`asyncio.TaskGroup` and :func:`asyncio.timeout`, are implemented " +"using cancellation internally and might misbehave if a coroutine " +"swallows :exc:`asyncio.CancelledError`. Similarly, user code should not " +"generally call :meth:`uncancel `. However, in cases " +"when suppressing :exc:`asyncio.CancelledError` is truly desired, it is " +"necessary to also call ``uncancel()`` to completely remove the cancellation " +"state." +msgstr "" + +#: ../../library/asyncio-task.rst:328 +msgid "Task Groups" +msgstr "" + +#: ../../library/asyncio-task.rst:330 +msgid "" +"Task groups combine a task creation API with a convenient and reliable way " +"to wait for all tasks in the group to finish." +msgstr "" + +#: ../../library/asyncio-task.rst:335 +msgid "" +"An :ref:`asynchronous context manager ` holding a " +"group of tasks. Tasks can be added to the group using :meth:`create_task`. " +"All tasks are awaited when the context manager exits." +msgstr "" + +#: ../../library/asyncio-task.rst:344 +msgid "" +"Create a task in this task group. The signature matches that " +"of :func:`asyncio.create_task`. If the task group is inactive (e.g. not yet " +"entered, already finished, or in the process of shutting down), we will " +"close the given ``coro``." +msgstr "" + +#: ../../library/asyncio-task.rst:352 +msgid "Close the given coroutine if the task group is not active." +msgstr "" + +#: ../../library/asyncio-task.rst:356 +msgid "Passes on all *kwargs* to :meth:`loop.create_task`" +msgstr "" + +#: ../../library/asyncio-task.rst:358 ../../library/asyncio-task.rst:564 +#: ../../library/asyncio-task.rst:737 ../../library/asyncio-task.rst:795 +#: ../../library/asyncio-task.rst:821 ../../library/asyncio-task.rst:862 +msgid "Example::" +msgstr "範例： ::" + +#: ../../library/asyncio-task.rst:360 +msgid "" +"async def main():\n" +" async with asyncio.TaskGroup() as tg:\n" +" task1 = tg.create_task(some_coro(...))\n" +" task2 = tg.create_task(another_coro(...))\n" +" print(f\"Both tasks have completed now: {task1.result()}, " +"{task2.result()}\")" +msgstr "" +"async def main():\n" +" async with asyncio.TaskGroup() as tg:\n" +" task1 = tg.create_task(some_coro(...))\n" +" task2 = tg.create_task(another_coro(...))\n" +" print(f\"Both tasks have completed now: {task1.result()}, " +"{task2.result()}\")" + +#: ../../library/asyncio-task.rst:366 +msgid "" +"The ``async with`` statement will wait for all tasks in the group to finish. " +"While waiting, new tasks may still be added to the group (for example, by " +"passing ``tg`` into one of the coroutines and calling ``tg.create_task()`` " +"in that coroutine). Once the last task has finished and the ``async with`` " +"block is exited, no new tasks may be added to the group." +msgstr "" + +#: ../../library/asyncio-task.rst:373 +msgid "" +"The first time any of the tasks belonging to the group fails with an " +"exception other than :exc:`asyncio.CancelledError`, the remaining tasks in " +"the group are cancelled. No further tasks can then be added to the group. At " +"this point, if the body of the ``async with`` statement is still active " +"(i.e., :meth:`~object.__aexit__` hasn't been called yet), the task directly " +"containing the ``async with`` statement is also cancelled. The " +"resulting :exc:`asyncio.CancelledError` will interrupt an ``await``, but it " +"will not bubble out of the containing ``async with`` statement." +msgstr "" + +#: ../../library/asyncio-task.rst:383 +msgid "" +"Once all tasks have finished, if any tasks have failed with an exception " +"other than :exc:`asyncio.CancelledError`, those exceptions are combined in " +"an :exc:`ExceptionGroup` or :exc:`BaseExceptionGroup` (as appropriate; see " +"their documentation) which is then raised." +msgstr "" + +#: ../../library/asyncio-task.rst:390 +msgid "" +"Two base exceptions are treated specially: If any task fails " +"with :exc:`KeyboardInterrupt` or :exc:`SystemExit`, the task group still " +"cancels the remaining tasks and waits for them, but then the " +"initial :exc:`KeyboardInterrupt` or :exc:`SystemExit` is re-raised instead " +"of :exc:`ExceptionGroup` or :exc:`BaseExceptionGroup`." +msgstr "" + +#: ../../library/asyncio-task.rst:396 +msgid "" +"If the body of the ``async with`` statement exits with an exception " +"(so :meth:`~object.__aexit__` is called with an exception set), this is " +"treated the same as if one of the tasks failed: the remaining tasks are " +"cancelled and then waited for, and non-cancellation exceptions are grouped " +"into an exception group and raised. The exception passed " +"into :meth:`~object.__aexit__`, unless it is :exc:`asyncio.CancelledError`, " +"is also included in the exception group. The same special case is made " +"for :exc:`KeyboardInterrupt` and :exc:`SystemExit` as in the previous " +"paragraph." +msgstr "" + +#: ../../library/asyncio-task.rst:408 +msgid "" +"Task groups are careful not to mix up the internal cancellation used to " +"\"wake up\" their :meth:`~object.__aexit__` with cancellation requests for " +"the task in which they are running made by other parties. In particular, " +"when one task group is syntactically nested in another, and both experience " +"an exception in one of their child tasks simultaneously, the inner task " +"group will process its exceptions, and then the outer task group will " +"receive another cancellation and process its own exceptions." +msgstr "" + +#: ../../library/asyncio-task.rst:416 +msgid "" +"In the case where a task group is cancelled externally and also must raise " +"an :exc:`ExceptionGroup`, it will call the parent " +"task's :meth:`~asyncio.Task.cancel` method. This ensures that " +"a :exc:`asyncio.CancelledError` will be raised at the next :keyword:`await`, " +"so the cancellation is not lost." +msgstr "" + +#: ../../library/asyncio-task.rst:422 +msgid "" +"Task groups preserve the cancellation count reported " +"by :meth:`asyncio.Task.cancelling`." +msgstr "" + +#: ../../library/asyncio-task.rst:427 +msgid "" +"Improved handling of simultaneous internal and external cancellations and " +"correct preservation of cancellation counts." +msgstr "" + +#: ../../library/asyncio-task.rst:431 +msgid "Terminating a Task Group" +msgstr "" + +#: ../../library/asyncio-task.rst:433 +msgid "" +"While terminating a task group is not natively supported by the standard " +"library, termination can be achieved by adding an exception-raising task to " +"the task group and ignoring the raised exception:" +msgstr "" + +#: ../../library/asyncio-task.rst:437 +msgid "" +"import asyncio\n" +"from asyncio import TaskGroup\n" +"\n" +"class TerminateTaskGroup(Exception):\n" +" \"\"\"Exception raised to terminate a task group.\"\"\"\n" +"\n" +"async def force_terminate_task_group():\n" +" \"\"\"Used to force termination of a task group.\"\"\"\n" +" raise TerminateTaskGroup()\n" +"\n" +"async def job(task_id, sleep_time):\n" +" print(f'Task {task_id}: start')\n" +" await asyncio.sleep(sleep_time)\n" +" print(f'Task {task_id}: done')\n" +"\n" +"async def main():\n" +" try:\n" +" async with TaskGroup() as group:\n" +" # spawn some tasks\n" +" group.create_task(job(1, 0.5))\n" +" group.create_task(job(2, 1.5))\n" +" # sleep for 1 second\n" +" await asyncio.sleep(1)\n" +" # add an exception-raising task to force the group to terminate\n" +" group.create_task(force_terminate_task_group())\n" +" except* TerminateTaskGroup:\n" +" pass\n" +"\n" +"asyncio.run(main())" +msgstr "" + +#: ../../library/asyncio-task.rst:469 +msgid "Expected output:" +msgstr "預期的輸出： ::" + +#: ../../library/asyncio-task.rst:471 +msgid "" +"Task 1: start\n" +"Task 2: start\n" +"Task 1: done" +msgstr "" +"Task 1: start\n" +"Task 2: start\n" +"Task 1: done" + +#: ../../library/asyncio-task.rst:478 +msgid "Sleeping" +msgstr "" + +#: ../../library/asyncio-task.rst:483 +msgid "Block for *delay* seconds." +msgstr "" + +#: ../../library/asyncio-task.rst:485 +msgid "" +"If *result* is provided, it is returned to the caller when the coroutine " +"completes." +msgstr "" + +#: ../../library/asyncio-task.rst:488 +msgid "" +"``sleep()`` always suspends the current task, allowing other tasks to run." +msgstr "" + +#: ../../library/asyncio-task.rst:491 +msgid "" +"Setting the delay to 0 provides an optimized path to allow other tasks to " +"run. This can be used by long-running functions to avoid blocking the event " +"loop for the full duration of the function call." +msgstr "" + +#: ../../library/asyncio-task.rst:497 +msgid "" +"Example of coroutine displaying the current date every second for 5 seconds::" +msgstr "" + +#: ../../library/asyncio-task.rst:500 +msgid "" +"import asyncio\n" +"import datetime\n" +"\n" +"async def display_date():\n" +" loop = asyncio.get_running_loop()\n" +" end_time = loop.time() + 5.0\n" +" while True:\n" +" print(datetime.datetime.now())\n" +" if (loop.time() + 1.0) >= end_time:\n" +" break\n" +" await asyncio.sleep(1)\n" +"\n" +"asyncio.run(display_date())" +msgstr "" +"import asyncio\n" +"import datetime\n" +"\n" +"async def display_date():\n" +" loop = asyncio.get_running_loop()\n" +" end_time = loop.time() + 5.0\n" +" while True:\n" +" print(datetime.datetime.now())\n" +" if (loop.time() + 1.0) >= end_time:\n" +" break\n" +" await asyncio.sleep(1)\n" +"\n" +"asyncio.run(display_date())" + +#: ../../library/asyncio-task.rst:515 ../../library/asyncio-task.rst:613 +#: ../../library/asyncio-task.rst:712 ../../library/asyncio-task.rst:887 +#: ../../library/asyncio-task.rst:942 ../../library/asyncio-task.rst:999 +msgid "Removed the *loop* parameter." +msgstr "移除 *loop* 參數。" + +#: ../../library/asyncio-task.rst:518 +msgid "Raises :exc:`ValueError` if *delay* is :data:`~math.nan`." +msgstr "如果 *delay* 是 :data:`~math.nan`，則引發 :exc:`ValueError`。" + +#: ../../library/asyncio-task.rst:523 +msgid "Running Tasks Concurrently" +msgstr "" + +#: ../../library/asyncio-task.rst:527 +msgid "" +"Run :ref:`awaitable objects ` in the *aws* sequence " +"*concurrently*." +msgstr "" + +#: ../../library/asyncio-task.rst:530 +msgid "" +"If any awaitable in *aws* is a coroutine, it is automatically scheduled as a " +"Task." +msgstr "" + +#: ../../library/asyncio-task.rst:533 +msgid "" +"If all awaitables are completed successfully, the result is an aggregate " +"list of returned values. The order of result values corresponds to the " +"order of awaitables in *aws*." +msgstr "" + +#: ../../library/asyncio-task.rst:537 +msgid "" +"If *return_exceptions* is ``False`` (default), the first raised exception is " +"immediately propagated to the task that awaits on ``gather()``. Other " +"awaitables in the *aws* sequence **won't be cancelled** and will continue to " +"run." +msgstr "" + +#: ../../library/asyncio-task.rst:542 +msgid "" +"If *return_exceptions* is ``True``, exceptions are treated the same as " +"successful results, and aggregated in the result list." +msgstr "" + +#: ../../library/asyncio-task.rst:545 +msgid "" +"If ``gather()`` is *cancelled*, all submitted awaitables (that have not " +"completed yet) are also *cancelled*." +msgstr "" + +#: ../../library/asyncio-task.rst:548 +msgid "" +"If any Task or Future from the *aws* sequence is *cancelled*, it is treated " +"as if it raised :exc:`CancelledError` -- the ``gather()`` call is **not** " +"cancelled in this case. This is to prevent the cancellation of one " +"submitted Task/Future to cause other Tasks/Futures to be cancelled." +msgstr "" + +#: ../../library/asyncio-task.rst:555 +msgid "" +"A new alternative to create and run tasks concurrently and wait for their " +"completion is :class:`asyncio.TaskGroup`. *TaskGroup* provides stronger " +"safety guarantees than *gather* for scheduling a nesting of subtasks: if a " +"task (or a subtask, a task scheduled by a task) raises an exception, " +"*TaskGroup* will, while *gather* will not, cancel the remaining scheduled " +"tasks)." +msgstr "" + +#: ../../library/asyncio-task.rst:566 +msgid "" +"import asyncio\n" +"\n" +"async def factorial(name, number):\n" +" f = 1\n" +" for i in range(2, number + 1):\n" +" print(f\"Task {name}: Compute factorial({number}), currently i={i}..." +"\")\n" +" await asyncio.sleep(1)\n" +" f *= i\n" +" print(f\"Task {name}: factorial({number}) = {f}\")\n" +" return f\n" +"\n" +"async def main():\n" +" # Schedule three calls *concurrently*:\n" +" L = await asyncio.gather(\n" +" factorial(\"A\", 2),\n" +" factorial(\"B\", 3),\n" +" factorial(\"C\", 4),\n" +" )\n" +" print(L)\n" +"\n" +"asyncio.run(main())\n" +"\n" +"# Expected output:\n" +"#\n" +"# Task A: Compute factorial(2), currently i=2...\n" +"# Task B: Compute factorial(3), currently i=2...\n" +"# Task C: Compute factorial(4), currently i=2...\n" +"# Task A: factorial(2) = 2\n" +"# Task B: Compute factorial(3), currently i=3...\n" +"# Task C: Compute factorial(4), currently i=3...\n" +"# Task B: factorial(3) = 6\n" +"# Task C: Compute factorial(4), currently i=4...\n" +"# Task C: factorial(4) = 24\n" +"# [2, 6, 24]" +msgstr "" + +#: ../../library/asyncio-task.rst:602 +msgid "" +"If *return_exceptions* is false, cancelling gather() after it has been " +"marked done won't cancel any submitted awaitables. For instance, gather can " +"be marked done after propagating an exception to the caller, therefore, " +"calling ``gather.cancel()`` after catching an exception (raised by one of " +"the awaitables) from gather won't cancel any other awaitables." +msgstr "" + +#: ../../library/asyncio-task.rst:609 +msgid "" +"If the *gather* itself is cancelled, the cancellation is propagated " +"regardless of *return_exceptions*." +msgstr "" + +#: ../../library/asyncio-task.rst:616 +msgid "" +"Deprecation warning is emitted if no positional arguments are provided or " +"not all positional arguments are Future-like objects and there is no running " +"event loop." +msgstr "" + +#: ../../library/asyncio-task.rst:625 +msgid "Eager Task Factory" +msgstr "" + +#: ../../library/asyncio-task.rst:629 +msgid "A task factory for eager task execution." +msgstr "" + +#: ../../library/asyncio-task.rst:631 +msgid "" +"When using this factory " +"(via :meth:`loop.set_task_factory(asyncio.eager_task_factory) " +"`), coroutines begin execution synchronously " +"during :class:`Task` construction. Tasks are only scheduled on the event " +"loop if they block. This can be a performance improvement as the overhead of " +"loop scheduling is avoided for coroutines that complete synchronously." +msgstr "" + +#: ../../library/asyncio-task.rst:637 +msgid "" +"A common example where this is beneficial is coroutines which employ caching " +"or memoization to avoid actual I/O when possible." +msgstr "" + +#: ../../library/asyncio-task.rst:642 +msgid "" +"Immediate execution of the coroutine is a semantic change. If the coroutine " +"returns or raises, the task is never scheduled to the event loop. If the " +"coroutine execution blocks, the task is scheduled to the event loop. This " +"change may introduce behavior changes to existing applications. For example, " +"the application's task execution order is likely to change." +msgstr "" + +#: ../../library/asyncio-task.rst:653 +msgid "" +"Create an eager task factory, similar to :func:`eager_task_factory`, using " +"the provided *custom_task_constructor* when creating a new task instead of " +"the default :class:`Task`." +msgstr "" + +#: ../../library/asyncio-task.rst:657 +msgid "" +"*custom_task_constructor* must be a *callable* with the signature matching " +"the signature of :class:`Task.__init__ `. The callable must return " +"a :class:`asyncio.Task`-compatible object." +msgstr "" + +#: ../../library/asyncio-task.rst:661 +msgid "" +"This function returns a *callable* intended to be used as a task factory of " +"an event loop via :meth:`loop.set_task_factory(factory) " +"`)." +msgstr "" + +#: ../../library/asyncio-task.rst:668 +msgid "Shielding From Cancellation" +msgstr "" + +#: ../../library/asyncio-task.rst:672 +msgid "" +"Protect an :ref:`awaitable object ` from " +"being :meth:`cancelled `." +msgstr "" + +#: ../../library/asyncio-task.rst:675 ../../library/asyncio-task.rst:842 +msgid "If *aw* is a coroutine it is automatically scheduled as a Task." +msgstr "" + +#: ../../library/asyncio-task.rst:677 +msgid "The statement::" +msgstr "" + +#: ../../library/asyncio-task.rst:679 +msgid "" +"task = asyncio.create_task(something())\n" +"res = await shield(task)" +msgstr "" +"task = asyncio.create_task(something())\n" +"res = await shield(task)" + +#: ../../library/asyncio-task.rst:682 +msgid "is equivalent to::" +msgstr "" + +#: ../../library/asyncio-task.rst:684 +msgid "res = await something()" +msgstr "res = await something()" + +#: ../../library/asyncio-task.rst:686 +msgid "" +"*except* that if the coroutine containing it is cancelled, the Task running " +"in ``something()`` is not cancelled. From the point of view of " +"``something()``, the cancellation did not happen. Although its caller is " +"still cancelled, so the \"await\" expression still raises " +"a :exc:`CancelledError`." +msgstr "" + +#: ../../library/asyncio-task.rst:692 +msgid "" +"If ``something()`` is cancelled by other means (i.e. from within itself) " +"that would also cancel ``shield()``." +msgstr "" + +#: ../../library/asyncio-task.rst:695 +msgid "" +"If it is desired to completely ignore cancellation (not recommended) the " +"``shield()`` function should be combined with a try/except clause, as " +"follows::" +msgstr "" + +#: ../../library/asyncio-task.rst:699 +msgid "" +"task = asyncio.create_task(something())\n" +"try:\n" +" res = await shield(task)\n" +"except CancelledError:\n" +" res = None" +msgstr "" +"task = asyncio.create_task(something())\n" +"try:\n" +" res = await shield(task)\n" +"except CancelledError:\n" +" res = None" + +#: ../../library/asyncio-task.rst:707 +msgid "" +"Save a reference to tasks passed to this function, to avoid a task " +"disappearing mid-execution. The event loop only keeps weak references to " +"tasks. A task that isn't referenced elsewhere may get garbage collected at " +"any time, even before it's done." +msgstr "" + +#: ../../library/asyncio-task.rst:715 +msgid "" +"Deprecation warning is emitted if *aw* is not Future-like object and there " +"is no running event loop." +msgstr "" + +#: ../../library/asyncio-task.rst:721 +msgid "Timeouts" +msgstr "" + +#: ../../library/asyncio-task.rst:725 +msgid "" +"Return an :ref:`asynchronous context manager ` that " +"can be used to limit the amount of time spent waiting on something." +msgstr "" + +#: ../../library/asyncio-task.rst:729 +msgid "" +"*delay* can either be ``None``, or a float/int number of seconds to wait. If " +"*delay* is ``None``, no time limit will be applied; this can be useful if " +"the delay is unknown when the context manager is created." +msgstr "" + +#: ../../library/asyncio-task.rst:734 +msgid "" +"In either case, the context manager can be rescheduled after creation " +"using :meth:`Timeout.reschedule`." +msgstr "" + +#: ../../library/asyncio-task.rst:739 +msgid "" +"async def main():\n" +" async with asyncio.timeout(10):\n" +" await long_running_task()" +msgstr "" +"async def main():\n" +" async with asyncio.timeout(10):\n" +" await long_running_task()" + +#: ../../library/asyncio-task.rst:743 +msgid "" +"If ``long_running_task`` takes more than 10 seconds to complete, the context " +"manager will cancel the current task and handle the " +"resulting :exc:`asyncio.CancelledError` internally, transforming it into " +"a :exc:`TimeoutError` which can be caught and handled." +msgstr "" + +#: ../../library/asyncio-task.rst:750 +msgid "" +"The :func:`asyncio.timeout` context manager is what transforms " +"the :exc:`asyncio.CancelledError` into a :exc:`TimeoutError`, which means " +"the :exc:`TimeoutError` can only be caught *outside* of the context manager." +msgstr "" + +#: ../../library/asyncio-task.rst:755 +msgid "Example of catching :exc:`TimeoutError`::" +msgstr "" + +#: ../../library/asyncio-task.rst:757 +msgid "" +"async def main():\n" +" try:\n" +" async with asyncio.timeout(10):\n" +" await long_running_task()\n" +" except TimeoutError:\n" +" print(\"The long operation timed out, but we've handled it.\")\n" +"\n" +" print(\"This statement will run regardless.\")" +msgstr "" + +#: ../../library/asyncio-task.rst:766 +msgid "" +"The context manager produced by :func:`asyncio.timeout` can be rescheduled " +"to a different deadline and inspected." +msgstr "" + +#: ../../library/asyncio-task.rst:771 +msgid "" +"An :ref:`asynchronous context manager ` for " +"cancelling overdue coroutines." +msgstr "" + +#: ../../library/asyncio-task.rst:774 +msgid "" +"``when`` should be an absolute time at which the context should time out, as " +"measured by the event loop's clock:" +msgstr "" + +#: ../../library/asyncio-task.rst:777 +msgid "If ``when`` is ``None``, the timeout will never trigger." +msgstr "" + +#: ../../library/asyncio-task.rst:778 +msgid "" +"If ``when < loop.time()``, the timeout will trigger on the next iteration of " +"the event loop." +msgstr "" + +#: ../../library/asyncio-task.rst:783 +msgid "" +"Return the current deadline, or ``None`` if the current deadline is not set." +msgstr "" + +#: ../../library/asyncio-task.rst:788 +msgid "Reschedule the timeout." +msgstr "" + +#: ../../library/asyncio-task.rst:792 +msgid "Return whether the context manager has exceeded its deadline (expired)." +msgstr "" + +#: ../../library/asyncio-task.rst:797 +msgid "" +"async def main():\n" +" try:\n" +" # We do not know the timeout when starting, so we pass ``None``.\n" +" async with asyncio.timeout(None) as cm:\n" +" # We know the timeout now, so we reschedule it.\n" +" new_deadline = get_running_loop().time() + 10\n" +" cm.reschedule(new_deadline)\n" +"\n" +" await long_running_task()\n" +" except TimeoutError:\n" +" pass\n" +"\n" +" if cm.expired():\n" +" print(\"Looks like we haven't finished on time.\")" +msgstr "" + +#: ../../library/asyncio-task.rst:812 +msgid "Timeout context managers can be safely nested." +msgstr "" + +#: ../../library/asyncio-task.rst:818 +msgid "" +"Similar to :func:`asyncio.timeout`, except *when* is the absolute time to " +"stop waiting, or ``None``." +msgstr "" + +#: ../../library/asyncio-task.rst:823 +msgid "" +"async def main():\n" +" loop = get_running_loop()\n" +" deadline = loop.time() + 20\n" +" try:\n" +" async with asyncio.timeout_at(deadline):\n" +" await long_running_task()\n" +" except TimeoutError:\n" +" print(\"The long operation timed out, but we've handled it.\")\n" +"\n" +" print(\"This statement will run regardless.\")" +msgstr "" + +#: ../../library/asyncio-task.rst:839 +msgid "" +"Wait for the *aw* :ref:`awaitable ` to complete with a " +"timeout." +msgstr "" + +#: ../../library/asyncio-task.rst:844 +msgid "" +"*timeout* can either be ``None`` or a float or int number of seconds to wait " +"for. If *timeout* is ``None``, block until the future completes." +msgstr "" + +#: ../../library/asyncio-task.rst:848 +msgid "" +"If a timeout occurs, it cancels the task and raises :exc:`TimeoutError`." +msgstr "" + +#: ../../library/asyncio-task.rst:851 +msgid "" +"To avoid the task :meth:`cancellation `, wrap it " +"in :func:`shield`." +msgstr "" + +#: ../../library/asyncio-task.rst:854 +msgid "" +"The function will wait until the future is actually cancelled, so the total " +"wait time may exceed the *timeout*. If an exception happens during " +"cancellation, it is propagated." +msgstr "" + +#: ../../library/asyncio-task.rst:858 +msgid "If the wait is cancelled, the future *aw* is also cancelled." +msgstr "" + +#: ../../library/asyncio-task.rst:864 +msgid "" +"async def eternity():\n" +" # Sleep for one hour\n" +" await asyncio.sleep(3600)\n" +" print('yay!')\n" +"\n" +"async def main():\n" +" # Wait for at most 1 second\n" +" try:\n" +" await asyncio.wait_for(eternity(), timeout=1.0)\n" +" except TimeoutError:\n" +" print('timeout!')\n" +"\n" +"asyncio.run(main())\n" +"\n" +"# Expected output:\n" +"#\n" +"# timeout!" +msgstr "" + +#: ../../library/asyncio-task.rst:882 +msgid "" +"When *aw* is cancelled due to a timeout, ``wait_for`` waits for *aw* to be " +"cancelled. Previously, it raised :exc:`TimeoutError` immediately." +msgstr "" + +#: ../../library/asyncio-task.rst:890 +msgid "Raises :exc:`TimeoutError` instead of :exc:`asyncio.TimeoutError`." +msgstr "引發 :exc:`TimeoutError` 而不是 :exc:`asyncio.TimeoutError`。" + +#: ../../library/asyncio-task.rst:895 +msgid "Waiting Primitives" +msgstr "" + +#: ../../library/asyncio-task.rst:900 +msgid "" +"Run :class:`~asyncio.Future` and :class:`~asyncio.Task` instances in the " +"*aws* iterable concurrently and block until the condition specified by " +"*return_when*." +msgstr "" + +#: ../../library/asyncio-task.rst:904 +msgid "The *aws* iterable must not be empty." +msgstr "" + +#: ../../library/asyncio-task.rst:906 +msgid "Returns two sets of Tasks/Futures: ``(done, pending)``." +msgstr "" + +#: ../../library/asyncio-task.rst:908 +msgid "Usage::" +msgstr "用法： ::" + +#: ../../library/asyncio-task.rst:910 +msgid "done, pending = await asyncio.wait(aws)" +msgstr "done, pending = await asyncio.wait(aws)" + +#: ../../library/asyncio-task.rst:912 +msgid "" +"*timeout* (a float or int), if specified, can be used to control the maximum " +"number of seconds to wait before returning." +msgstr "" + +#: ../../library/asyncio-task.rst:915 +msgid "" +"Note that this function does not raise :exc:`TimeoutError`. Futures or Tasks " +"that aren't done when the timeout occurs are simply returned in the second " +"set." +msgstr "" + +#: ../../library/asyncio-task.rst:919 +msgid "" +"*return_when* indicates when this function should return. It must be one of " +"the following constants:" +msgstr "" + +#: ../../library/asyncio-task.rst:925 +msgid "Constant" +msgstr "常數" + +#: ../../library/asyncio-task.rst:926 +msgid "Description" +msgstr "描述" + +#: ../../library/asyncio-task.rst:929 +msgid "The function will return when any future finishes or is cancelled." +msgstr "" + +#: ../../library/asyncio-task.rst:932 +msgid "" +"The function will return when any future finishes by raising an exception. " +"If no future raises an exception then it is equivalent " +"to :const:`ALL_COMPLETED`." +msgstr "" + +#: ../../library/asyncio-task.rst:937 +msgid "The function will return when all futures finish or are cancelled." +msgstr "" + +#: ../../library/asyncio-task.rst:939 +msgid "" +"Unlike :func:`~asyncio.wait_for`, ``wait()`` does not cancel the futures " +"when a timeout occurs." +msgstr "" + +#: ../../library/asyncio-task.rst:945 +msgid "Passing coroutine objects to ``wait()`` directly is forbidden." +msgstr "" + +#: ../../library/asyncio-task.rst:948 ../../library/asyncio-task.rst:1006 +msgid "Added support for generators yielding tasks." +msgstr "" + +#: ../../library/asyncio-task.rst:954 +msgid "" +"Run :ref:`awaitable objects ` in the *aws* iterable " +"concurrently. The returned object can be iterated to obtain the results of " +"the awaitables as they finish." +msgstr "" + +#: ../../library/asyncio-task.rst:958 +msgid "" +"The object returned by ``as_completed()`` can be iterated as " +"an :term:`asynchronous iterator` or a plain :term:`iterator`. When " +"asynchronous iteration is used, the originally-supplied awaitables are " +"yielded if they are tasks or futures. This makes it easy to correlate " +"previously-scheduled tasks with their results. Example::" +msgstr "" + +#: ../../library/asyncio-task.rst:964 +msgid "" +"ipv4_connect = create_task(open_connection(\"127.0.0.1\", 80))\n" +"ipv6_connect = create_task(open_connection(\"::1\", 80))\n" +"tasks = [ipv4_connect, ipv6_connect]\n" +"\n" +"async for earliest_connect in as_completed(tasks):\n" +" # earliest_connect is done. The result can be obtained by\n" +" # awaiting it or calling earliest_connect.result()\n" +" reader, writer = await earliest_connect\n" +"\n" +" if earliest_connect is ipv6_connect:\n" +" print(\"IPv6 connection established.\")\n" +" else:\n" +" print(\"IPv4 connection established.\")" +msgstr "" + +#: ../../library/asyncio-task.rst:978 +msgid "" +"During asynchronous iteration, implicitly-created tasks will be yielded for " +"supplied awaitables that aren't tasks or futures." +msgstr "" + +#: ../../library/asyncio-task.rst:981 +msgid "" +"When used as a plain iterator, each iteration yields a new coroutine that " +"returns the result or raises the exception of the next completed awaitable. " +"This pattern is compatible with Python versions older than 3.13::" +msgstr "" + +#: ../../library/asyncio-task.rst:985 +msgid "" +"ipv4_connect = create_task(open_connection(\"127.0.0.1\", 80))\n" +"ipv6_connect = create_task(open_connection(\"::1\", 80))\n" +"tasks = [ipv4_connect, ipv6_connect]\n" +"\n" +"for next_connect in as_completed(tasks):\n" +" # next_connect is not one of the original task objects. It must be\n" +" # awaited to obtain the result value or raise the exception of the\n" +" # awaitable that finishes next.\n" +" reader, writer = await next_connect" +msgstr "" + +#: ../../library/asyncio-task.rst:995 +msgid "" +"A :exc:`TimeoutError` is raised if the timeout occurs before all awaitables " +"are done. This is raised by the ``async for`` loop during asynchronous " +"iteration or by the coroutines yielded during plain iteration." +msgstr "" + +#: ../../library/asyncio-task.rst:1002 +msgid "" +"Deprecation warning is emitted if not all awaitable objects in the *aws* " +"iterable are Future-like objects and there is no running event loop." +msgstr "" + +#: ../../library/asyncio-task.rst:1009 +msgid "" +"The result can now be used as either an :term:`asynchronous iterator` or as " +"a plain :term:`iterator` (previously it was only a plain iterator)." +msgstr "" + +#: ../../library/asyncio-task.rst:1015 +msgid "Running in Threads" +msgstr "" + +#: ../../library/asyncio-task.rst:1020 +msgid "Asynchronously run function *func* in a separate thread." +msgstr "" + +#: ../../library/asyncio-task.rst:1022 +msgid "" +"Any \\*args and \\*\\*kwargs supplied for this function are directly passed " +"to *func*. Also, the current :class:`contextvars.Context` is propagated, " +"allowing context variables from the event loop thread to be accessed in the " +"separate thread." +msgstr "" + +#: ../../library/asyncio-task.rst:1027 +msgid "" +"Return a coroutine that can be awaited to get the eventual result of *func*." +msgstr "" + +#: ../../library/asyncio-task.rst:1029 +msgid "" +"This coroutine function is primarily intended to be used for executing IO-" +"bound functions/methods that would otherwise block the event loop if they " +"were run in the main thread. For example::" +msgstr "" + +#: ../../library/asyncio-task.rst:1033 +msgid "" +"def blocking_io():\n" +" print(f\"start blocking_io at {time.strftime('%X')}\")\n" +" # Note that time.sleep() can be replaced with any blocking\n" +" # IO-bound operation, such as file operations.\n" +" time.sleep(1)\n" +" print(f\"blocking_io complete at {time.strftime('%X')}\")\n" +"\n" +"async def main():\n" +" print(f\"started main at {time.strftime('%X')}\")\n" +"\n" +" await asyncio.gather(\n" +" asyncio.to_thread(blocking_io),\n" +" asyncio.sleep(1))\n" +"\n" +" print(f\"finished main at {time.strftime('%X')}\")\n" +"\n" +"\n" +"asyncio.run(main())\n" +"\n" +"# Expected output:\n" +"#\n" +"# started main at 19:50:53\n" +"# start blocking_io at 19:50:53\n" +"# blocking_io complete at 19:50:54\n" +"# finished main at 19:50:54" +msgstr "" + +#: ../../library/asyncio-task.rst:1059 +msgid "" +"Directly calling ``blocking_io()`` in any coroutine would block the event " +"loop for its duration, resulting in an additional 1 second of run time. " +"Instead, by using ``asyncio.to_thread()``, we can run it in a separate " +"thread without blocking the event loop." +msgstr "" + +#: ../../library/asyncio-task.rst:1066 +msgid "" +"Due to the :term:`GIL`, ``asyncio.to_thread()`` can typically only be used " +"to make IO-bound functions non-blocking. However, for extension modules that " +"release the GIL or alternative Python implementations that don't have one, " +"``asyncio.to_thread()`` can also be used for CPU-bound functions." +msgstr "" + +#: ../../library/asyncio-task.rst:1075 +msgid "Scheduling From Other Threads" +msgstr "" + +#: ../../library/asyncio-task.rst:1079 +msgid "Submit a coroutine to the given event loop. Thread-safe." +msgstr "" + +#: ../../library/asyncio-task.rst:1081 +msgid "" +"Return a :class:`concurrent.futures.Future` to wait for the result from " +"another OS thread." +msgstr "" + +#: ../../library/asyncio-task.rst:1084 +msgid "" +"This function is meant to be called from a different OS thread than the one " +"where the event loop is running. Example::" +msgstr "" + +#: ../../library/asyncio-task.rst:1087 +msgid "" +"def in_thread(loop: asyncio.AbstractEventLoop) -> None:\n" +" # Run some blocking IO\n" +" pathlib.Path(\"example.txt\").write_text(\"hello world\", " +"encoding=\"utf8\")\n" +"\n" +" # Create a coroutine\n" +" coro = asyncio.sleep(1, result=3)\n" +"\n" +" # Submit the coroutine to a given loop\n" +" future = asyncio.run_coroutine_threadsafe(coro, loop)\n" +"\n" +" # Wait for the result with an optional timeout argument\n" +" assert future.result(timeout=2) == 3\n" +"\n" +"async def amain() -> None:\n" +" # Get the running loop\n" +" loop = asyncio.get_running_loop()\n" +"\n" +" # Run something in a thread\n" +" await asyncio.to_thread(in_thread, loop)" +msgstr "" + +#: ../../library/asyncio-task.rst:1107 +msgid "It's also possible to run the other way around. Example::" +msgstr "" + +#: ../../library/asyncio-task.rst:1109 +msgid "" +"@contextlib.contextmanager\n" +"def loop_in_thread() -> Generator[asyncio.AbstractEventLoop]:\n" +" loop_fut = concurrent.futures.Future[asyncio.AbstractEventLoop]()\n" +" stop_event = asyncio.Event()\n" +"\n" +" async def main() -> None:\n" +" loop_fut.set_result(asyncio.get_running_loop())\n" +" await stop_event.wait()\n" +"\n" +" with concurrent.futures.ThreadPoolExecutor(1) as tpe:\n" +" complete_fut = tpe.submit(asyncio.run, main())\n" +" for fut in concurrent.futures.as_completed((loop_fut, " +"complete_fut)):\n" +" if fut is loop_fut:\n" +" loop = loop_fut.result()\n" +" try:\n" +" yield loop\n" +" finally:\n" +" loop.call_soon_threadsafe(stop_event.set)\n" +" else:\n" +" fut.result()\n" +"\n" +"# Create a loop in another thread\n" +"with loop_in_thread() as loop:\n" +" # Create a coroutine\n" +" coro = asyncio.sleep(1, result=3)\n" +"\n" +" # Submit the coroutine to a given loop\n" +" future = asyncio.run_coroutine_threadsafe(coro, loop)\n" +"\n" +" # Wait for the result with an optional timeout argument\n" +" assert future.result(timeout=2) == 3" +msgstr "" + +#: ../../library/asyncio-task.rst:1141 +msgid "" +"If an exception is raised in the coroutine, the returned Future will be " +"notified. It can also be used to cancel the task in the event loop::" +msgstr "" + +#: ../../library/asyncio-task.rst:1145 +msgid "" +"try:\n" +" result = future.result(timeout)\n" +"except TimeoutError:\n" +" print('The coroutine took too long, cancelling the task...')\n" +" future.cancel()\n" +"except Exception as exc:\n" +" print(f'The coroutine raised an exception: {exc!r}')\n" +"else:\n" +" print(f'The coroutine returned: {result!r}')" +msgstr "" + +#: ../../library/asyncio-task.rst:1155 +msgid "" +"See the :ref:`concurrency and multithreading ` " +"section of the documentation." +msgstr "" + +#: ../../library/asyncio-task.rst:1158 +msgid "" +"Unlike other asyncio functions this function requires the *loop* argument to " +"be passed explicitly." +msgstr "" + +#: ../../library/asyncio-task.rst:1165 +msgid "Introspection" +msgstr "" + +#: ../../library/asyncio-task.rst:1170 +msgid "" +"Return the currently running :class:`Task` instance, or ``None`` if no task " +"is running." +msgstr "" + +#: ../../library/asyncio-task.rst:1173 +msgid "" +"If *loop* is ``None`` :func:`get_running_loop` is used to get the current " +"loop." +msgstr "" + +#: ../../library/asyncio-task.rst:1181 +msgid "Return a set of not yet finished :class:`Task` objects run by the loop." +msgstr "" + +#: ../../library/asyncio-task.rst:1184 +msgid "" +"If *loop* is ``None``, :func:`get_running_loop` is used for getting current " +"loop." +msgstr "" + +#: ../../library/asyncio-task.rst:1192 +msgid "Return ``True`` if *obj* is a coroutine object." +msgstr "" + +#: ../../library/asyncio-task.rst:1199 +msgid "Task Object" +msgstr "Task 物件" + +#: ../../library/asyncio-task.rst:1203 +msgid "" +"A :class:`Future-like ` object that runs a Python :ref:`coroutine " +"`. Not thread-safe." +msgstr "" + +#: ../../library/asyncio-task.rst:1206 +msgid "" +"Tasks are used to run coroutines in event loops. If a coroutine awaits on a " +"Future, the Task suspends the execution of the coroutine and waits for the " +"completion of the Future. When the Future is *done*, the execution of the " +"wrapped coroutine resumes." +msgstr "" + +#: ../../library/asyncio-task.rst:1212 +msgid "" +"Event loops use cooperative scheduling: an event loop runs one Task at a " +"time. While a Task awaits for the completion of a Future, the event loop " +"runs other Tasks, callbacks, or performs IO operations." +msgstr "" + +#: ../../library/asyncio-task.rst:1217 +msgid "" +"Use the high-level :func:`asyncio.create_task` function to create Tasks, or " +"the low-level :meth:`loop.create_task` or :func:`ensure_future` functions. " +"Manual instantiation of Tasks is discouraged." +msgstr "" + +#: ../../library/asyncio-task.rst:1222 +msgid "" +"To cancel a running Task use the :meth:`cancel` method. Calling it will " +"cause the Task to throw a :exc:`CancelledError` exception into the wrapped " +"coroutine. If a coroutine is awaiting on a Future object during " +"cancellation, the Future object will be cancelled." +msgstr "" + +#: ../../library/asyncio-task.rst:1227 +msgid "" +":meth:`cancelled` can be used to check if the Task was cancelled. The method " +"returns ``True`` if the wrapped coroutine did not suppress " +"the :exc:`CancelledError` exception and was actually cancelled." +msgstr "" + +#: ../../library/asyncio-task.rst:1232 +msgid "" +":class:`asyncio.Task` inherits from :class:`Future` all of its APIs " +"except :meth:`Future.set_result` and :meth:`Future.set_exception`." +msgstr "" + +#: ../../library/asyncio-task.rst:1236 +msgid "" +"An optional keyword-only *context* argument allows specifying a " +"custom :class:`contextvars.Context` for the *coro* to run in. If no " +"*context* is provided, the Task copies the current context and later runs " +"its coroutine in the copied context." +msgstr "" + +#: ../../library/asyncio-task.rst:1241 +msgid "" +"An optional keyword-only *eager_start* argument allows eagerly starting the " +"execution of the :class:`asyncio.Task` at task creation time. If set to " +"``True`` and the event loop is running, the task will start executing the " +"coroutine immediately, until the first time the coroutine blocks. If the " +"coroutine returns or raises without blocking, the task will be finished " +"eagerly and will skip scheduling to the event loop." +msgstr "" + +#: ../../library/asyncio-task.rst:1248 +msgid "Added support for the :mod:`contextvars` module." +msgstr "新增對 :mod:`contextvars` 模組的支援。" + +#: ../../library/asyncio-task.rst:1254 +msgid "" +"Deprecation warning is emitted if *loop* is not specified and there is no " +"running event loop." +msgstr "" + +#: ../../library/asyncio-task.rst:1261 +msgid "Added the *eager_start* parameter." +msgstr "新增 *eager_start* 參數。" + +#: ../../library/asyncio-task.rst:1266 +msgid "Return ``True`` if the Task is *done*." +msgstr "" + +#: ../../library/asyncio-task.rst:1268 +msgid "" +"A Task is *done* when the wrapped coroutine either returned a value, raised " +"an exception, or the Task was cancelled." +msgstr "" + +#: ../../library/asyncio-task.rst:1273 +msgid "Return the result of the Task." +msgstr "" + +#: ../../library/asyncio-task.rst:1275 +msgid "" +"If the Task is *done*, the result of the wrapped coroutine is returned (or " +"if the coroutine raised an exception, that exception is re-raised.)" +msgstr "" + +#: ../../library/asyncio-task.rst:1279 ../../library/asyncio-task.rst:1293 +msgid "" +"If the Task has been *cancelled*, this method raises a :exc:`CancelledError` " +"exception." +msgstr "" + +#: ../../library/asyncio-task.rst:1282 +msgid "" +"If the Task's result isn't yet available, this method raises " +"an :exc:`InvalidStateError` exception." +msgstr "" + +#: ../../library/asyncio-task.rst:1287 +msgid "Return the exception of the Task." +msgstr "" + +#: ../../library/asyncio-task.rst:1289 +msgid "" +"If the wrapped coroutine raised an exception that exception is returned. If " +"the wrapped coroutine returned normally this method returns ``None``." +msgstr "" + +#: ../../library/asyncio-task.rst:1296 +msgid "" +"If the Task isn't *done* yet, this method raises an :exc:`InvalidStateError` " +"exception." +msgstr "" + +#: ../../library/asyncio-task.rst:1301 +msgid "Add a callback to be run when the Task is *done*." +msgstr "" + +#: ../../library/asyncio-task.rst:1303 ../../library/asyncio-task.rst:1312 +msgid "This method should only be used in low-level callback-based code." +msgstr "" + +#: ../../library/asyncio-task.rst:1305 +msgid "" +"See the documentation of :meth:`Future.add_done_callback` for more details." +msgstr "" + +#: ../../library/asyncio-task.rst:1310 +msgid "Remove *callback* from the callbacks list." +msgstr "" + +#: ../../library/asyncio-task.rst:1314 +msgid "" +"See the documentation of :meth:`Future.remove_done_callback` for more " +"details." +msgstr "" + +#: ../../library/asyncio-task.rst:1319 +msgid "Return the list of stack frames for this Task." +msgstr "" + +#: ../../library/asyncio-task.rst:1321 +msgid "" +"If the wrapped coroutine is not done, this returns the stack where it is " +"suspended. If the coroutine has completed successfully or was cancelled, " +"this returns an empty list. If the coroutine was terminated by an exception, " +"this returns the list of traceback frames." +msgstr "" + +#: ../../library/asyncio-task.rst:1327 +msgid "The frames are always ordered from oldest to newest." +msgstr "" + +#: ../../library/asyncio-task.rst:1329 +msgid "Only one stack frame is returned for a suspended coroutine." +msgstr "" + +#: ../../library/asyncio-task.rst:1331 +msgid "" +"The optional *limit* argument sets the maximum number of frames to return; " +"by default all available frames are returned. The ordering of the returned " +"list differs depending on whether a stack or a traceback is returned: the " +"newest frames of a stack are returned, but the oldest frames of a traceback " +"are returned. (This matches the behavior of the traceback module.)" +msgstr "" + +#: ../../library/asyncio-task.rst:1340 +msgid "Print the stack or traceback for this Task." +msgstr "" + +#: ../../library/asyncio-task.rst:1342 +msgid "" +"This produces output similar to that of the traceback module for the frames " +"retrieved by :meth:`get_stack`." +msgstr "" + +#: ../../library/asyncio-task.rst:1345 +msgid "The *limit* argument is passed to :meth:`get_stack` directly." +msgstr "" + +#: ../../library/asyncio-task.rst:1347 +msgid "" +"The *file* argument is an I/O stream to which the output is written; by " +"default output is written to :data:`sys.stdout`." +msgstr "" + +#: ../../library/asyncio-task.rst:1352 +msgid "Return the coroutine object wrapped by the :class:`Task`." +msgstr "" + +#: ../../library/asyncio-task.rst:1356 +msgid "" +"This will return ``None`` for Tasks which have already completed eagerly. " +"See the :ref:`Eager Task Factory `." +msgstr "" + +#: ../../library/asyncio-task.rst:1363 +msgid "Newly added eager task execution means result may be ``None``." +msgstr "" + +#: ../../library/asyncio-task.rst:1367 +msgid "" +"Return the :class:`contextvars.Context` object associated with the task." +msgstr "" + +#: ../../library/asyncio-task.rst:1374 +msgid "Return the name of the Task." +msgstr "" + +#: ../../library/asyncio-task.rst:1376 +msgid "" +"If no name has been explicitly assigned to the Task, the default asyncio " +"Task implementation generates a default name during instantiation." +msgstr "" + +#: ../../library/asyncio-task.rst:1384 +msgid "Set the name of the Task." +msgstr "" + +#: ../../library/asyncio-task.rst:1386 +msgid "" +"The *value* argument can be any object, which is then converted to a string." +msgstr "" + +#: ../../library/asyncio-task.rst:1389 +msgid "" +"In the default Task implementation, the name will be visible in " +"the :func:`repr` output of a task object." +msgstr "" + +#: ../../library/asyncio-task.rst:1396 +msgid "Request the Task to be cancelled." +msgstr "" + +#: ../../library/asyncio-task.rst:1398 +msgid "" +"If the Task is already *done* or *cancelled*, return ``False``, otherwise, " +"return ``True``." +msgstr "" + +#: ../../library/asyncio-task.rst:1401 +msgid "" +"The method arranges for a :exc:`CancelledError` exception to be thrown into " +"the wrapped coroutine on the next cycle of the event loop." +msgstr "" + +#: ../../library/asyncio-task.rst:1404 +msgid "" +"The coroutine then has a chance to clean up or even deny the request by " +"suppressing the exception with a :keyword:`try` ... ... ``except " +"CancelledError`` ... :keyword:`finally` block. Therefore, " +"unlike :meth:`Future.cancel`, :meth:`Task.cancel` does not guarantee that " +"the Task will be cancelled, although suppressing cancellation completely is " +"not common and is actively discouraged. Should the coroutine nevertheless " +"decide to suppress the cancellation, it needs to call :meth:`Task.uncancel` " +"in addition to catching the exception." +msgstr "" + +#: ../../library/asyncio-task.rst:1414 +msgid "Added the *msg* parameter." +msgstr "新增 *msg* 參數。" + +#: ../../library/asyncio-task.rst:1417 +msgid "The ``msg`` parameter is propagated from cancelled task to its awaiter." +msgstr "" + +#: ../../library/asyncio-task.rst:1422 +msgid "" +"The following example illustrates how coroutines can intercept the " +"cancellation request::" +msgstr "" + +#: ../../library/asyncio-task.rst:1425 +msgid "" +"async def cancel_me():\n" +" print('cancel_me(): before sleep')\n" +"\n" +" try:\n" +" # Wait for 1 hour\n" +" await asyncio.sleep(3600)\n" +" except asyncio.CancelledError:\n" +" print('cancel_me(): cancel sleep')\n" +" raise\n" +" finally:\n" +" print('cancel_me(): after sleep')\n" +"\n" +"async def main():\n" +" # Create a \"cancel_me\" Task\n" +" task = asyncio.create_task(cancel_me())\n" +"\n" +" # Wait for 1 second\n" +" await asyncio.sleep(1)\n" +"\n" +" task.cancel()\n" +" try:\n" +" await task\n" +" except asyncio.CancelledError:\n" +" print(\"main(): cancel_me is cancelled now\")\n" +"\n" +"asyncio.run(main())\n" +"\n" +"# Expected output:\n" +"#\n" +"# cancel_me(): before sleep\n" +"# cancel_me(): cancel sleep\n" +"# cancel_me(): after sleep\n" +"# main(): cancel_me is cancelled now" +msgstr "" + +#: ../../library/asyncio-task.rst:1461 +msgid "Return ``True`` if the Task is *cancelled*." +msgstr "" + +#: ../../library/asyncio-task.rst:1463 +msgid "" +"The Task is *cancelled* when the cancellation was requested " +"with :meth:`cancel` and the wrapped coroutine propagated " +"the :exc:`CancelledError` exception thrown into it." +msgstr "" + +#: ../../library/asyncio-task.rst:1469 +msgid "Decrement the count of cancellation requests to this Task." +msgstr "" + +#: ../../library/asyncio-task.rst:1471 +msgid "Returns the remaining number of cancellation requests." +msgstr "" + +#: ../../library/asyncio-task.rst:1473 +msgid "" +"Note that once execution of a cancelled task completed, further calls " +"to :meth:`uncancel` are ineffective." +msgstr "" + +#: ../../library/asyncio-task.rst:1478 +msgid "" +"This method is used by asyncio's internals and isn't expected to be used by " +"end-user code. In particular, if a Task gets successfully uncancelled, this " +"allows for elements of structured concurrency like :ref:`taskgroups` " +"and :func:`asyncio.timeout` to continue running, isolating cancellation to " +"the respective structured block. For example::" +msgstr "" + +#: ../../library/asyncio-task.rst:1485 +msgid "" +"async def make_request_with_timeout():\n" +" try:\n" +" async with asyncio.timeout(1):\n" +" # Structured block affected by the timeout:\n" +" await make_request()\n" +" await make_another_request()\n" +" except TimeoutError:\n" +" log(\"There was a timeout\")\n" +" # Outer code not affected by the timeout:\n" +" await unrelated_code()" +msgstr "" + +#: ../../library/asyncio-task.rst:1496 +msgid "" +"While the block with ``make_request()`` and ``make_another_request()`` might " +"get cancelled due to the timeout, ``unrelated_code()`` should continue " +"running even in case of the timeout. This is implemented " +"with :meth:`uncancel`. :class:`TaskGroup` context managers " +"use :func:`uncancel` in a similar fashion." +msgstr "" + +#: ../../library/asyncio-task.rst:1502 +msgid "" +"If end-user code is, for some reason, suppressing cancellation by " +"catching :exc:`CancelledError`, it needs to call this method to remove the " +"cancellation state." +msgstr "" + +#: ../../library/asyncio-task.rst:1506 +msgid "" +"When this method decrements the cancellation count to zero, the method " +"checks if a previous :meth:`cancel` call had arranged " +"for :exc:`CancelledError` to be thrown into the task. If it hasn't been " +"thrown yet, that arrangement will be rescinded (by resetting the internal " +"``_must_cancel`` flag)." +msgstr "" + +#: ../../library/asyncio-task.rst:1512 +msgid "Changed to rescind pending cancellation requests upon reaching zero." +msgstr "" + +#: ../../library/asyncio-task.rst:1517 +msgid "" +"Return the number of pending cancellation requests to this Task, i.e., the " +"number of calls to :meth:`cancel` less the number of :meth:`uncancel` calls." +msgstr "" + +#: ../../library/asyncio-task.rst:1521 +msgid "" +"Note that if this number is greater than zero but the Task is still " +"executing, :meth:`cancelled` will still return ``False``. This is because " +"this number can be lowered by calling :meth:`uncancel`, which can lead to " +"the task not being cancelled after all if the cancellation requests go down " +"to zero." +msgstr "" + +#: ../../library/asyncio-task.rst:1527 +msgid "" +"This method is used by asyncio's internals and isn't expected to be used by " +"end-user code. See :meth:`uncancel` for more details." +msgstr "" + +#~ msgid "" +#~ "for coro in as_completed(aws):\n" +#~ " earliest_result = await coro\n" +#~ " # ..." +#~ msgstr "" +#~ "for coro in as_completed(aws):\n" +#~ " earliest_result = await coro\n" +#~ " # ..." + +#~ msgid ":const:`FIRST_COMPLETED`" +#~ msgstr ":const:`FIRST_COMPLETED`" + +#~ msgid ":const:`FIRST_EXCEPTION`" +#~ msgstr ":const:`FIRST_EXCEPTION`" + +#~ msgid ":const:`ALL_COMPLETED`" +#~ msgstr ":const:`ALL_COMPLETED`" diff --git a/library/asyncio.po b/library/asyncio.po index 79c9d8f5e1..bde0e82bd4 100644 --- a/library/asyncio.po +++ b/library/asyncio.po @@ -1,232 +1,232 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Adrian Liaw , 2018 -# Matt Wang , 2021 -# Leo Wang , 2023 -# Weilin Du, 2025 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-12-01 00:17+0000\n" -"PO-Revision-Date: 2025-07-06 17:13+0800\n" -"Last-Translator: Weilin Du\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/asyncio.rst:100 -msgid "High-level APIs" -msgstr "高階 API" - -#: ../../library/asyncio.rst:113 -msgid "Low-level APIs" -msgstr "低階 API" - -#: ../../library/asyncio.rst:124 -msgid "Guides and Tutorials" -msgstr "指南與教學" - -#: ../../library/asyncio.rst:2 -msgid ":mod:`!asyncio` --- Asynchronous I/O" -msgstr ":mod:`!asyncio` --- 非同步 I/O" - -#: ../../library/asyncio.rst:9 -msgid "Hello World!" -msgstr "Hello World!" - -#: ../../library/asyncio.rst:13 -msgid "" -"import asyncio\n" -"\n" -"async def main():\n" -" print('Hello ...')\n" -" await asyncio.sleep(1)\n" -" print('... World!')\n" -"\n" -"asyncio.run(main())" -msgstr "" -"import asyncio\n" -"\n" -"async def main():\n" -" print('Hello ...')\n" -" await asyncio.sleep(1)\n" -" print('... World!')\n" -"\n" -"asyncio.run(main())" - -#: ../../library/asyncio.rst:22 -msgid "" -"asyncio is a library to write **concurrent** code using the **async/await** " -"syntax." -msgstr "" -"asyncio 是讓使用者以 **async/await** 語法來編寫\\ *並行 (concurrent)* 程式碼" -"的函式庫 (library)。" - -#: ../../library/asyncio.rst:25 -msgid "" -"asyncio is used as a foundation for multiple Python asynchronous frameworks " -"that provide high-performance network and web-servers, database connection " -"libraries, distributed task queues, etc." -msgstr "" -"asyncio 作為多個 Python 非同步框架的基礎，在高效能網路與網頁伺服器、資料庫連" -"線函式庫、分散式任務佇列等服務都可以看得到它。" - -#: ../../library/asyncio.rst:29 -msgid "" -"asyncio is often a perfect fit for IO-bound and high-level **structured** " -"network code." -msgstr "" -"asyncio 往往是個建構 IO 密集型與高階層\\ **結構化**\\ 網路程式碼的完美選擇。" - -#: ../../library/asyncio.rst:34 -msgid ":ref:`a-conceptual-overview-of-asyncio`" -msgstr ":ref:`a-conceptual-overview-of-asyncio`" - -#: ../../library/asyncio.rst:35 -msgid "Explanation of the fundamentals of asyncio." -msgstr "asyncio 的基本原理說明。" - -#: ../../library/asyncio.rst:37 -msgid "asyncio provides a set of **high-level** APIs to:" -msgstr "asyncio 提供了一系列\\ **高階** API：" - -#: ../../library/asyncio.rst:39 -msgid "" -":ref:`run Python coroutines ` concurrently and have full control " -"over their execution;" -msgstr "" -"並行地\\ :ref:`運行 Python 協程 (coroutine) ` 並擁有完整控制權；" - -#: ../../library/asyncio.rst:42 -msgid "perform :ref:`network IO and IPC `;" -msgstr "執行\\ :ref:`網路 IO 與 IPC `；" - -#: ../../library/asyncio.rst:44 -msgid "control :ref:`subprocesses `;" -msgstr "控制\\ :ref:`子行程 (subprocess) `；" - -#: ../../library/asyncio.rst:46 -msgid "distribute tasks via :ref:`queues `;" -msgstr "透過\\ :ref:`佇列 (queue) ` 分配任務；" - -#: ../../library/asyncio.rst:48 -msgid ":ref:`synchronize ` concurrent code;" -msgstr ":ref:`同步 `\\ 並行程式碼；" - -#: ../../library/asyncio.rst:50 -msgid "" -"Additionally, there are **low-level** APIs for *library and framework " -"developers* to:" -msgstr "" -"此外，還有一些給\\ *函式庫與框架 (framework) 開發者*\\ 的\\ **低階** API：" - -#: ../../library/asyncio.rst:53 -msgid "" -"create and manage :ref:`event loops `, which provide " -"asynchronous APIs for :ref:`networking `, running :ref:" -"`subprocesses `, handling :ref:`OS signals " -"`, etc;" -msgstr "" -"建立與管理 :ref:`event loops（事件迴圈） `，它提供了能被" -"用於\\ :ref:`網路 `、執行\\ :ref:`子行程 " -"`、處理\\ :ref:`作業系統訊號 " -"`\\ 等任務的非同步 API；" - -#: ../../library/asyncio.rst:58 -msgid "" -"implement efficient protocols using :ref:`transports `;" -msgstr "" -"使用 :ref:`transports（asyncio 底層傳輸相關類別） `\\ 來實作高效能協定；" - -#: ../../library/asyncio.rst:61 -msgid "" -":ref:`bridge ` callback-based libraries and code with async/" -"await syntax." -msgstr "" -"透過 async/await 語法來\\ :ref:`橋接 `\\ 基於回呼 (callback-" -"based) 的函式庫與程式碼。" - -#: ../../includes/wasm-notavail.rst:3 -msgid "Availability" -msgstr "可用性" - -#: ../../includes/wasm-notavail.rst:5 -msgid "" -"This module does not work or is not available on WebAssembly. See :ref:`wasm-" -"availability` for more information." -msgstr "" -"此模組在 WebAssembly 平台上不起作用或無法使用。更多資訊請參閱 :ref:`wasm-" -"availability`。" - -#: ../../library/asyncio.rst:69 -msgid "asyncio REPL" -msgstr "asyncio REPL" - -#: ../../library/asyncio.rst:70 -msgid "" -"You can experiment with an ``asyncio`` concurrent context in the :term:" -"`REPL`:" -msgstr "" -"你能在 :term:`REPL` 中對一個 ``asyncio`` 的並行情境 (context) 進行實驗：" - -#: ../../library/asyncio.rst:72 -msgid "" -"$ python -m asyncio\n" -"asyncio REPL ...\n" -"Use \"await\" directly instead of \"asyncio.run()\".\n" -"Type \"help\", \"copyright\", \"credits\" or \"license\" for more " -"information.\n" -">>> import asyncio\n" -">>> await asyncio.sleep(10, result='hello')\n" -"'hello'" -msgstr "" -"$ python -m asyncio\n" -"asyncio REPL ...\n" -"Use \"await\" directly instead of \"asyncio.run()\".\n" -"Type \"help\", \"copyright\", \"credits\" or \"license\" for more " -"information.\n" -">>> import asyncio\n" -">>> await asyncio.sleep(10, result='hello')\n" -"'hello'" - -#: ../../library/asyncio.rst:82 -msgid "" -"This REPL provides limited compatibility with :envvar:`PYTHON_BASIC_REPL`. " -"It is recommended that the default REPL is used for full functionality and " -"the latest features." -msgstr "" - -#: ../../library/asyncio.rst:86 -msgid "" -"Raises an :ref:`auditing event ` ``cpython.run_stdin`` with no " -"arguments." -msgstr "產生一個 :ref:`稽核事件 ` ``cpython.run_stdin`` 且沒有引數。" - -#: ../../library/asyncio.rst:88 -msgid "(also 3.11.10, 3.10.15, 3.9.20, and 3.8.20) Emits audit events." -msgstr "(也包括 3.11.10、3.10.15、3.9.20 及 3.8.20）發出稽核事件。" - -#: ../../library/asyncio.rst:91 -msgid "" -"Uses PyREPL if possible, in which case :envvar:`PYTHONSTARTUP` is also " -"executed. Emits audit events." -msgstr "" -"可能的話使用 PyREPL，在這種情況下 :envvar:`PYTHONSTARTUP` 也會被執行。發出稽" -"核事件。" - -#: ../../library/asyncio.rst:99 -msgid "Reference" -msgstr "參閱" - -#: ../../library/asyncio.rst:133 -msgid "The source code for asyncio can be found in :source:`Lib/asyncio/`." -msgstr "asyncio 的原始碼可以在 :source:`Lib/asyncio/` 中找到。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Adrian Liaw , 2018 +# Matt Wang , 2021 +# Leo Wang , 2023 +# Weilin Du, 2025 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-12-01 00:17+0000\n" +"PO-Revision-Date: 2025-07-06 17:13+0800\n" +"Last-Translator: Weilin Du\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/asyncio.rst:100 +msgid "High-level APIs" +msgstr "高階 API" + +#: ../../library/asyncio.rst:113 +msgid "Low-level APIs" +msgstr "低階 API" + +#: ../../library/asyncio.rst:124 +msgid "Guides and Tutorials" +msgstr "指南與教學" + +#: ../../library/asyncio.rst:2 +msgid ":mod:`!asyncio` --- Asynchronous I/O" +msgstr ":mod:`!asyncio` --- 非同步 I/O" + +#: ../../library/asyncio.rst:9 +msgid "Hello World!" +msgstr "Hello World!" + +#: ../../library/asyncio.rst:13 +msgid "" +"import asyncio\n" +"\n" +"async def main():\n" +" print('Hello ...')\n" +" await asyncio.sleep(1)\n" +" print('... World!')\n" +"\n" +"asyncio.run(main())" +msgstr "" +"import asyncio\n" +"\n" +"async def main():\n" +" print('Hello ...')\n" +" await asyncio.sleep(1)\n" +" print('... World!')\n" +"\n" +"asyncio.run(main())" + +#: ../../library/asyncio.rst:22 +msgid "" +"asyncio is a library to write **concurrent** code using the **async/await** " +"syntax." +msgstr "" +"asyncio 是讓使用者以 **async/await** 語法來編寫\\ *並行 (concurrent)* 程式碼" +"的函式庫 (library)。" + +#: ../../library/asyncio.rst:25 +msgid "" +"asyncio is used as a foundation for multiple Python asynchronous frameworks " +"that provide high-performance network and web-servers, database connection " +"libraries, distributed task queues, etc." +msgstr "" +"asyncio 作為多個 Python 非同步框架的基礎，在高效能網路與網頁伺服器、資料庫連" +"線函式庫、分散式任務佇列等服務都可以看得到它。" + +#: ../../library/asyncio.rst:29 +msgid "" +"asyncio is often a perfect fit for IO-bound and high-level **structured** " +"network code." +msgstr "" +"asyncio 往往是個建構 IO 密集型與高階層\\ **結構化**\\ 網路程式碼的完美選擇。" + +#: ../../library/asyncio.rst:34 +msgid ":ref:`a-conceptual-overview-of-asyncio`" +msgstr ":ref:`a-conceptual-overview-of-asyncio`" + +#: ../../library/asyncio.rst:35 +msgid "Explanation of the fundamentals of asyncio." +msgstr "asyncio 的基本原理說明。" + +#: ../../library/asyncio.rst:37 +msgid "asyncio provides a set of **high-level** APIs to:" +msgstr "asyncio 提供了一系列\\ **高階** API：" + +#: ../../library/asyncio.rst:39 +msgid "" +":ref:`run Python coroutines ` concurrently and have full control " +"over their execution;" +msgstr "" +"並行地\\ :ref:`運行 Python 協程 (coroutine) ` 並擁有完整控制權；" + +#: ../../library/asyncio.rst:42 +msgid "perform :ref:`network IO and IPC `;" +msgstr "執行\\ :ref:`網路 IO 與 IPC `；" + +#: ../../library/asyncio.rst:44 +msgid "control :ref:`subprocesses `;" +msgstr "控制\\ :ref:`子行程 (subprocess) `；" + +#: ../../library/asyncio.rst:46 +msgid "distribute tasks via :ref:`queues `;" +msgstr "透過\\ :ref:`佇列 (queue) ` 分配任務；" + +#: ../../library/asyncio.rst:48 +msgid ":ref:`synchronize ` concurrent code;" +msgstr ":ref:`同步 `\\ 並行程式碼；" + +#: ../../library/asyncio.rst:50 +msgid "" +"Additionally, there are **low-level** APIs for *library and framework " +"developers* to:" +msgstr "" +"此外，還有一些給\\ *函式庫與框架 (framework) 開發者*\\ 的\\ **低階** API：" + +#: ../../library/asyncio.rst:53 +msgid "" +"create and manage :ref:`event loops `, which provide " +"asynchronous APIs for :ref:`networking `, running :ref:" +"`subprocesses `, handling :ref:`OS signals " +"`, etc;" +msgstr "" +"建立與管理 :ref:`event loops（事件迴圈） `，它提供了能被" +"用於\\ :ref:`網路 `、執行\\ :ref:`子行程 " +"`、處理\\ :ref:`作業系統訊號 " +"`\\ 等任務的非同步 API；" + +#: ../../library/asyncio.rst:58 +msgid "" +"implement efficient protocols using :ref:`transports `;" +msgstr "" +"使用 :ref:`transports（asyncio 底層傳輸相關類別） `\\ 來實作高效能協定；" + +#: ../../library/asyncio.rst:61 +msgid "" +":ref:`bridge ` callback-based libraries and code with async/" +"await syntax." +msgstr "" +"透過 async/await 語法來\\ :ref:`橋接 `\\ 基於回呼 (callback-" +"based) 的函式庫與程式碼。" + +#: ../../includes/wasm-notavail.rst:3 +msgid "Availability" +msgstr "可用性" + +#: ../../includes/wasm-notavail.rst:5 +msgid "" +"This module does not work or is not available on WebAssembly. See :ref:`wasm-" +"availability` for more information." +msgstr "" +"此模組在 WebAssembly 平台上不起作用或無法使用。更多資訊請參閱 :ref:`wasm-" +"availability`。" + +#: ../../library/asyncio.rst:69 +msgid "asyncio REPL" +msgstr "asyncio REPL" + +#: ../../library/asyncio.rst:70 +msgid "" +"You can experiment with an ``asyncio`` concurrent context in the :term:" +"`REPL`:" +msgstr "" +"你能在 :term:`REPL` 中對一個 ``asyncio`` 的並行情境 (context) 進行實驗：" + +#: ../../library/asyncio.rst:72 +msgid "" +"$ python -m asyncio\n" +"asyncio REPL ...\n" +"Use \"await\" directly instead of \"asyncio.run()\".\n" +"Type \"help\", \"copyright\", \"credits\" or \"license\" for more " +"information.\n" +">>> import asyncio\n" +">>> await asyncio.sleep(10, result='hello')\n" +"'hello'" +msgstr "" +"$ python -m asyncio\n" +"asyncio REPL ...\n" +"Use \"await\" directly instead of \"asyncio.run()\".\n" +"Type \"help\", \"copyright\", \"credits\" or \"license\" for more " +"information.\n" +">>> import asyncio\n" +">>> await asyncio.sleep(10, result='hello')\n" +"'hello'" + +#: ../../library/asyncio.rst:82 +msgid "" +"This REPL provides limited compatibility with :envvar:`PYTHON_BASIC_REPL`. " +"It is recommended that the default REPL is used for full functionality and " +"the latest features." +msgstr "" + +#: ../../library/asyncio.rst:86 +msgid "" +"Raises an :ref:`auditing event ` ``cpython.run_stdin`` with no " +"arguments." +msgstr "產生一個 :ref:`稽核事件 ` ``cpython.run_stdin`` 且沒有引數。" + +#: ../../library/asyncio.rst:88 +msgid "(also 3.11.10, 3.10.15, 3.9.20, and 3.8.20) Emits audit events." +msgstr "(也包括 3.11.10、3.10.15、3.9.20 及 3.8.20）發出稽核事件。" + +#: ../../library/asyncio.rst:91 +msgid "" +"Uses PyREPL if possible, in which case :envvar:`PYTHONSTARTUP` is also " +"executed. Emits audit events." +msgstr "" +"可能的話使用 PyREPL，在這種情況下 :envvar:`PYTHONSTARTUP` 也會被執行。發出稽" +"核事件。" + +#: ../../library/asyncio.rst:99 +msgid "Reference" +msgstr "參閱" + +#: ../../library/asyncio.rst:133 +msgid "The source code for asyncio can be found in :source:`Lib/asyncio/`." +msgstr "asyncio 的原始碼可以在 :source:`Lib/asyncio/` 中找到。" diff --git a/library/asyncore.po b/library/asyncore.po index 39efa7aab0..0502a329a0 100644 --- a/library/asyncore.po +++ b/library/asyncore.po @@ -1,43 +1,43 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -#, fuzzy -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-11-18 00:15+0000\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" -"tw)\n" -"Language: zh_TW\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=UTF-8\n" -"Content-Transfer-Encoding: 8bit\n" - -#: ../../library/asyncore.rst:2 -msgid ":mod:`!asyncore` --- Asynchronous socket handler" -msgstr ":mod:`!asyncore` --- 非同步 socket 處理函式" - -#: ../../library/asyncore.rst:10 -msgid "" -"This module is no longer part of the Python standard library. It was :ref:" -"`removed in Python 3.12 ` after being deprecated in " -"Python 3.6. The removal was decided in :pep:`594`." -msgstr "" -"這個模組已不再是 Python 標準函式庫的一部分。它在 Python 3.6 中被棄用，並\\ :" -"ref:`已在 Python 3.12 中被移除 `。它的移除是在 :pep:" -"`594` 中決定的。" - -#: ../../library/asyncore.rst:14 -msgid "Applications should use the :mod:`asyncio` module instead." -msgstr "應用程式應改用 :mod:`asyncio` 模組。" - -#: ../../library/asyncore.rst:16 -msgid "" -"The last version of Python that provided the :mod:`!asyncore` module was " -"`Python 3.11 `_." -msgstr "" -"最後提供 :mod:`!asyncore` 模組的 Python 版本是 `Python 3.11 `_。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-11-18 00:15+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" +"tw)\n" +"Language: zh_TW\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../library/asyncore.rst:2 +msgid ":mod:`!asyncore` --- Asynchronous socket handler" +msgstr ":mod:`!asyncore` --- 非同步 socket 處理函式" + +#: ../../library/asyncore.rst:10 +msgid "" +"This module is no longer part of the Python standard library. It was :ref:" +"`removed in Python 3.12 ` after being deprecated in " +"Python 3.6. The removal was decided in :pep:`594`." +msgstr "" +"這個模組已不再是 Python 標準函式庫的一部分。它在 Python 3.6 中被棄用，並\\ :" +"ref:`已在 Python 3.12 中被移除 `。它的移除是在 :pep:" +"`594` 中決定的。" + +#: ../../library/asyncore.rst:14 +msgid "Applications should use the :mod:`asyncio` module instead." +msgstr "應用程式應改用 :mod:`asyncio` 模組。" + +#: ../../library/asyncore.rst:16 +msgid "" +"The last version of Python that provided the :mod:`!asyncore` module was " +"`Python 3.11 `_." +msgstr "" +"最後提供 :mod:`!asyncore` 模組的 Python 版本是 `Python 3.11 `_。" diff --git a/library/atexit.po b/library/atexit.po index 2ad3f8cf56..853c1e7a37 100644 --- a/library/atexit.po +++ b/library/atexit.po @@ -1,246 +1,246 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Matt Wang , 2024 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-09-03 11:11+0800\n" -"PO-Revision-Date: 2016-01-31 07:13+0000\n" -"Last-Translator: Matt Wang \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/atexit.rst:2 -msgid ":mod:`!atexit` --- Exit handlers" -msgstr ":mod:`!atexit` --- 退出處理函式" - -#: ../../library/atexit.rst:12 -msgid "" -"The :mod:`atexit` module defines functions to register and unregister " -"cleanup functions. Functions thus registered are automatically executed " -"upon normal interpreter termination. :mod:`atexit` runs these functions in " -"the *reverse* order in which they were registered; if you register ``A``, " -"``B``, and ``C``, at interpreter termination time they will be run in the " -"order ``C``, ``B``, ``A``." -msgstr "" -":mod:`atexit` 模組定義了註冊和註銷清理函式 (cleanup function) 的函式，這樣的" -"註冊函式會在直譯器正常終止時自動執行。:mod:`atexit` 按照這些函式註冊之\\ *反" -"序*\\ 來運行這些函式；如果你有註冊 ``A``、``B`` 和 ``C``，則在直譯器終止時它" -"們將按 ``C``、``B``、``A`` 的順序運行。" - -#: ../../library/atexit.rst:19 -msgid "" -"**Note:** The functions registered via this module are not called when the " -"program is killed by a signal not handled by Python, when a Python fatal " -"internal error is detected, or when :func:`os._exit` is called." -msgstr "" -"**注意：**\\ 當程式被一個不是來自 Python 的訊號終止、偵測到有 Python 嚴重內部" -"錯誤時或者 :func:`os._exit` 被呼叫時，透過此模組註冊的函式就不會被呼叫。" - -#: ../../library/atexit.rst:23 -msgid "" -"**Note:** The effect of registering or unregistering functions from within a " -"cleanup function is undefined." -msgstr "**注意：**\\ 在清理函式中註冊或註銷函式的作用並未定義。" - -#: ../../library/atexit.rst:26 -msgid "" -"When used with C-API subinterpreters, registered functions are local to the " -"interpreter they were registered in." -msgstr "" -"當與 C-API 子直譯器 (subinterpreter) 一起使用時，已註冊函式對於它們所註冊的直" -"譯器來說是區域的 (local)。" - -#: ../../library/atexit.rst:32 -msgid "" -"Register *func* as a function to be executed at termination. Any optional " -"arguments that are to be passed to *func* must be passed as arguments to :" -"func:`register`. It is possible to register the same function and arguments " -"more than once." -msgstr "" -"將 *func* 註冊為要在終止時執行的函式。任何要傳遞給 *func* 的可選引數都必須作" -"為引數傳遞給 :func:`register`。可以多次註冊相同的函式和引數。" - -#: ../../library/atexit.rst:37 -msgid "" -"At normal program termination (for instance, if :func:`sys.exit` is called " -"or the main module's execution completes), all functions registered are " -"called in last in, first out order. The assumption is that lower level " -"modules will normally be imported before higher level modules and thus must " -"be cleaned up later." -msgstr "" -"在程式正常終止時（例如呼叫 :func:`sys.exit` 或主要模組執行完成），所有已註冊" -"函式都會依照後進先出的順序呼叫。這邊做的假設是較低階的模組通常會在較高階模組" -"之前被引入，因此較低階模組必須在比較後面才被清理。" - -#: ../../library/atexit.rst:43 -msgid "" -"If an exception is raised during execution of the exit handlers, a traceback " -"is printed (unless :exc:`SystemExit` is raised) and the exception " -"information is saved. After all exit handlers have had a chance to run, the " -"last exception to be raised is re-raised." -msgstr "" -"如果在執行退出處理函式期間引發例外，則會列印回溯 (traceback)（除非引發 :exc:" -"`SystemExit`）並儲存例外資訊。在所有退出處理函式都有嘗試運作過後，將重新引發" -"最後一個引發的例外。" - -#: ../../library/atexit.rst:48 -msgid "" -"This function returns *func*, which makes it possible to use it as a " -"decorator." -msgstr "該函式回傳 *func*，這使得可以將其作為裝飾器使用。" - -#: ../../library/atexit.rst:52 -msgid "" -"Starting new threads or calling :func:`os.fork` from a registered function " -"can lead to race condition between the main Python runtime thread freeing " -"thread states while internal :mod:`threading` routines or the new process " -"try to use that state. This can lead to crashes rather than clean shutdown." -msgstr "" -"啟動新執行緒或從已註冊函式呼叫 :func:`os.fork` 可能會導致 Python 主要 " -"runtime 執行緒釋放執行緒狀態，而內部 :mod:`threading` 例程或新行程嘗試使用該" -"狀態所形成的競態條件 (race condition)。這可能會導致崩潰 (crash) 而不是完整關" -"閉中止。" - -#: ../../library/atexit.rst:58 -msgid "" -"Attempts to start a new thread or :func:`os.fork` a new process in a " -"registered function now leads to :exc:`RuntimeError`." -msgstr "" -"嘗試在已註冊函式中啟動新執行緒或 :func:`os.fork` 新行程現在會導致 :exc:" -"`RuntimeError`。" - -#: ../../library/atexit.rst:64 -msgid "" -"Remove *func* from the list of functions to be run at interpreter shutdown. :" -"func:`unregister` silently does nothing if *func* was not previously " -"registered. If *func* has been registered more than once, every occurrence " -"of that function in the :mod:`atexit` call stack will be removed. Equality " -"comparisons (``==``) are used internally during unregistration, so function " -"references do not need to have matching identities." -msgstr "" -"從在直譯器中止時會執行之函式串列中刪除 *func*。如果 *func* 先前未被註冊，則 :" -"func:`unregister` 不會執行任何操作。如果 *func* 已被註冊多次，則該函式在 :" -"mod:`atexit` 呼叫堆疊 (call stack) 中的所有存在都會被刪除。會在註銷期間於內部" -"使用相等性比較 (``==``)，因此函式參照不需要具有匹配的識別性。" - -#: ../../library/atexit.rst:74 -msgid "Module :mod:`readline`" -msgstr ":mod:`readline` 模組" - -#: ../../library/atexit.rst:75 -msgid "" -"Useful example of :mod:`atexit` to read and write :mod:`readline` history " -"files." -msgstr "" -":mod:`atexit` 用於讀取和寫入 :mod:`readline` 歷史檔案的一個不錯的範例。" - -#: ../../library/atexit.rst:82 -msgid ":mod:`atexit` Example" -msgstr ":mod:`atexit` 範例" - -#: ../../library/atexit.rst:84 -msgid "" -"The following simple example demonstrates how a module can initialize a " -"counter from a file when it is imported and save the counter's updated value " -"automatically when the program terminates without relying on the application " -"making an explicit call into this module at termination. ::" -msgstr "" -"以下的簡單範例示範了模組如何在被引入時以檔案來初始化計數器，並在程式終止時自" -"動儲存計數器的更新值，而不需要仰賴應用程式在終止時明確呼叫該模組。 ::" - -#: ../../library/atexit.rst:89 -msgid "" -"try:\n" -" with open('counterfile') as infile:\n" -" _count = int(infile.read())\n" -"except FileNotFoundError:\n" -" _count = 0\n" -"\n" -"def incrcounter(n):\n" -" global _count\n" -" _count = _count + n\n" -"\n" -"def savecounter():\n" -" with open('counterfile', 'w') as outfile:\n" -" outfile.write('%d' % _count)\n" -"\n" -"import atexit\n" -"\n" -"atexit.register(savecounter)" -msgstr "" -"try:\n" -" with open('counterfile') as infile:\n" -" _count = int(infile.read())\n" -"except FileNotFoundError:\n" -" _count = 0\n" -"\n" -"def incrcounter(n):\n" -" global _count\n" -" _count = _count + n\n" -"\n" -"def savecounter():\n" -" with open('counterfile', 'w') as outfile:\n" -" outfile.write('%d' % _count)\n" -"\n" -"import atexit\n" -"\n" -"atexit.register(savecounter)" - -#: ../../library/atexit.rst:107 -msgid "" -"Positional and keyword arguments may also be passed to :func:`register` to " -"be passed along to the registered function when it is called::" -msgstr "" -"位置引數和關鍵字引數也可以被傳遞給 :func:`register`，以便在呼叫時也傳遞給已註" -"冊函式： ::" - -#: ../../library/atexit.rst:110 -msgid "" -"def goodbye(name, adjective):\n" -" print('Goodbye %s, it was %s to meet you.' % (name, adjective))\n" -"\n" -"import atexit\n" -"\n" -"atexit.register(goodbye, 'Donny', 'nice')\n" -"# or:\n" -"atexit.register(goodbye, adjective='nice', name='Donny')" -msgstr "" -"def goodbye(name, adjective):\n" -" print('Goodbye %s, it was %s to meet you.' % (name, adjective))\n" -"\n" -"import atexit\n" -"\n" -"atexit.register(goodbye, 'Donny', 'nice')\n" -"# 或是：\n" -"atexit.register(goodbye, adjective='nice', name='Donny')" - -#: ../../library/atexit.rst:119 -msgid "Usage as a :term:`decorator`::" -msgstr "作為\\ :term:`裝飾器 `\\ 使用： ::" - -#: ../../library/atexit.rst:121 -msgid "" -"import atexit\n" -"\n" -"@atexit.register\n" -"def goodbye():\n" -" print('You are now leaving the Python sector.')" -msgstr "" -"import atexit\n" -"\n" -"@atexit.register\n" -"def goodbye():\n" -" print('You are now leaving the Python sector.')" - -#: ../../library/atexit.rst:127 -msgid "This only works with functions that can be called without arguments." -msgstr "這只適用於可以不帶引數呼叫的函式。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Matt Wang , 2024 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-09-03 11:11+0800\n" +"PO-Revision-Date: 2016-01-31 07:13+0000\n" +"Last-Translator: Matt Wang \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/atexit.rst:2 +msgid ":mod:`!atexit` --- Exit handlers" +msgstr ":mod:`!atexit` --- 退出處理函式" + +#: ../../library/atexit.rst:12 +msgid "" +"The :mod:`atexit` module defines functions to register and unregister " +"cleanup functions. Functions thus registered are automatically executed " +"upon normal interpreter termination. :mod:`atexit` runs these functions in " +"the *reverse* order in which they were registered; if you register ``A``, " +"``B``, and ``C``, at interpreter termination time they will be run in the " +"order ``C``, ``B``, ``A``." +msgstr "" +":mod:`atexit` 模組定義了註冊和註銷清理函式 (cleanup function) 的函式，這樣的" +"註冊函式會在直譯器正常終止時自動執行。:mod:`atexit` 按照這些函式註冊之\\ *反" +"序*\\ 來運行這些函式；如果你有註冊 ``A``、``B`` 和 ``C``，則在直譯器終止時它" +"們將按 ``C``、``B``、``A`` 的順序運行。" + +#: ../../library/atexit.rst:19 +msgid "" +"**Note:** The functions registered via this module are not called when the " +"program is killed by a signal not handled by Python, when a Python fatal " +"internal error is detected, or when :func:`os._exit` is called." +msgstr "" +"**注意：**\\ 當程式被一個不是來自 Python 的訊號終止、偵測到有 Python 嚴重內部" +"錯誤時或者 :func:`os._exit` 被呼叫時，透過此模組註冊的函式就不會被呼叫。" + +#: ../../library/atexit.rst:23 +msgid "" +"**Note:** The effect of registering or unregistering functions from within a " +"cleanup function is undefined." +msgstr "**注意：**\\ 在清理函式中註冊或註銷函式的作用並未定義。" + +#: ../../library/atexit.rst:26 +msgid "" +"When used with C-API subinterpreters, registered functions are local to the " +"interpreter they were registered in." +msgstr "" +"當與 C-API 子直譯器 (subinterpreter) 一起使用時，已註冊函式對於它們所註冊的直" +"譯器來說是區域的 (local)。" + +#: ../../library/atexit.rst:32 +msgid "" +"Register *func* as a function to be executed at termination. Any optional " +"arguments that are to be passed to *func* must be passed as arguments to :" +"func:`register`. It is possible to register the same function and arguments " +"more than once." +msgstr "" +"將 *func* 註冊為要在終止時執行的函式。任何要傳遞給 *func* 的可選引數都必須作" +"為引數傳遞給 :func:`register`。可以多次註冊相同的函式和引數。" + +#: ../../library/atexit.rst:37 +msgid "" +"At normal program termination (for instance, if :func:`sys.exit` is called " +"or the main module's execution completes), all functions registered are " +"called in last in, first out order. The assumption is that lower level " +"modules will normally be imported before higher level modules and thus must " +"be cleaned up later." +msgstr "" +"在程式正常終止時（例如呼叫 :func:`sys.exit` 或主要模組執行完成），所有已註冊" +"函式都會依照後進先出的順序呼叫。這邊做的假設是較低階的模組通常會在較高階模組" +"之前被引入，因此較低階模組必須在比較後面才被清理。" + +#: ../../library/atexit.rst:43 +msgid "" +"If an exception is raised during execution of the exit handlers, a traceback " +"is printed (unless :exc:`SystemExit` is raised) and the exception " +"information is saved. After all exit handlers have had a chance to run, the " +"last exception to be raised is re-raised." +msgstr "" +"如果在執行退出處理函式期間引發例外，則會列印回溯 (traceback)（除非引發 :exc:" +"`SystemExit`）並儲存例外資訊。在所有退出處理函式都有嘗試運作過後，將重新引發" +"最後一個引發的例外。" + +#: ../../library/atexit.rst:48 +msgid "" +"This function returns *func*, which makes it possible to use it as a " +"decorator." +msgstr "該函式回傳 *func*，這使得可以將其作為裝飾器使用。" + +#: ../../library/atexit.rst:52 +msgid "" +"Starting new threads or calling :func:`os.fork` from a registered function " +"can lead to race condition between the main Python runtime thread freeing " +"thread states while internal :mod:`threading` routines or the new process " +"try to use that state. This can lead to crashes rather than clean shutdown." +msgstr "" +"啟動新執行緒或從已註冊函式呼叫 :func:`os.fork` 可能會導致 Python 主要 " +"runtime 執行緒釋放執行緒狀態，而內部 :mod:`threading` 例程或新行程嘗試使用該" +"狀態所形成的競態條件 (race condition)。這可能會導致崩潰 (crash) 而不是完整關" +"閉中止。" + +#: ../../library/atexit.rst:58 +msgid "" +"Attempts to start a new thread or :func:`os.fork` a new process in a " +"registered function now leads to :exc:`RuntimeError`." +msgstr "" +"嘗試在已註冊函式中啟動新執行緒或 :func:`os.fork` 新行程現在會導致 :exc:" +"`RuntimeError`。" + +#: ../../library/atexit.rst:64 +msgid "" +"Remove *func* from the list of functions to be run at interpreter shutdown. :" +"func:`unregister` silently does nothing if *func* was not previously " +"registered. If *func* has been registered more than once, every occurrence " +"of that function in the :mod:`atexit` call stack will be removed. Equality " +"comparisons (``==``) are used internally during unregistration, so function " +"references do not need to have matching identities." +msgstr "" +"從在直譯器中止時會執行之函式串列中刪除 *func*。如果 *func* 先前未被註冊，則 :" +"func:`unregister` 不會執行任何操作。如果 *func* 已被註冊多次，則該函式在 :" +"mod:`atexit` 呼叫堆疊 (call stack) 中的所有存在都會被刪除。會在註銷期間於內部" +"使用相等性比較 (``==``)，因此函式參照不需要具有匹配的識別性。" + +#: ../../library/atexit.rst:74 +msgid "Module :mod:`readline`" +msgstr ":mod:`readline` 模組" + +#: ../../library/atexit.rst:75 +msgid "" +"Useful example of :mod:`atexit` to read and write :mod:`readline` history " +"files." +msgstr "" +":mod:`atexit` 用於讀取和寫入 :mod:`readline` 歷史檔案的一個不錯的範例。" + +#: ../../library/atexit.rst:82 +msgid ":mod:`atexit` Example" +msgstr ":mod:`atexit` 範例" + +#: ../../library/atexit.rst:84 +msgid "" +"The following simple example demonstrates how a module can initialize a " +"counter from a file when it is imported and save the counter's updated value " +"automatically when the program terminates without relying on the application " +"making an explicit call into this module at termination. ::" +msgstr "" +"以下的簡單範例示範了模組如何在被引入時以檔案來初始化計數器，並在程式終止時自" +"動儲存計數器的更新值，而不需要仰賴應用程式在終止時明確呼叫該模組。 ::" + +#: ../../library/atexit.rst:89 +msgid "" +"try:\n" +" with open('counterfile') as infile:\n" +" _count = int(infile.read())\n" +"except FileNotFoundError:\n" +" _count = 0\n" +"\n" +"def incrcounter(n):\n" +" global _count\n" +" _count = _count + n\n" +"\n" +"def savecounter():\n" +" with open('counterfile', 'w') as outfile:\n" +" outfile.write('%d' % _count)\n" +"\n" +"import atexit\n" +"\n" +"atexit.register(savecounter)" +msgstr "" +"try:\n" +" with open('counterfile') as infile:\n" +" _count = int(infile.read())\n" +"except FileNotFoundError:\n" +" _count = 0\n" +"\n" +"def incrcounter(n):\n" +" global _count\n" +" _count = _count + n\n" +"\n" +"def savecounter():\n" +" with open('counterfile', 'w') as outfile:\n" +" outfile.write('%d' % _count)\n" +"\n" +"import atexit\n" +"\n" +"atexit.register(savecounter)" + +#: ../../library/atexit.rst:107 +msgid "" +"Positional and keyword arguments may also be passed to :func:`register` to " +"be passed along to the registered function when it is called::" +msgstr "" +"位置引數和關鍵字引數也可以被傳遞給 :func:`register`，以便在呼叫時也傳遞給已註" +"冊函式： ::" + +#: ../../library/atexit.rst:110 +msgid "" +"def goodbye(name, adjective):\n" +" print('Goodbye %s, it was %s to meet you.' % (name, adjective))\n" +"\n" +"import atexit\n" +"\n" +"atexit.register(goodbye, 'Donny', 'nice')\n" +"# or:\n" +"atexit.register(goodbye, adjective='nice', name='Donny')" +msgstr "" +"def goodbye(name, adjective):\n" +" print('Goodbye %s, it was %s to meet you.' % (name, adjective))\n" +"\n" +"import atexit\n" +"\n" +"atexit.register(goodbye, 'Donny', 'nice')\n" +"# 或是：\n" +"atexit.register(goodbye, adjective='nice', name='Donny')" + +#: ../../library/atexit.rst:119 +msgid "Usage as a :term:`decorator`::" +msgstr "作為\\ :term:`裝飾器 `\\ 使用： ::" + +#: ../../library/atexit.rst:121 +msgid "" +"import atexit\n" +"\n" +"@atexit.register\n" +"def goodbye():\n" +" print('You are now leaving the Python sector.')" +msgstr "" +"import atexit\n" +"\n" +"@atexit.register\n" +"def goodbye():\n" +" print('You are now leaving the Python sector.')" + +#: ../../library/atexit.rst:127 +msgid "This only works with functions that can be called without arguments." +msgstr "這只適用於可以不帶引數呼叫的函式。" diff --git a/library/audioop.po b/library/audioop.po index 9fd2a98adb..ecc3d1c0c7 100644 --- a/library/audioop.po +++ b/library/audioop.po @@ -1,39 +1,39 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -#, fuzzy -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-11-18 00:15+0000\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" -"tw)\n" -"Language: zh_TW\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=UTF-8\n" -"Content-Transfer-Encoding: 8bit\n" - -#: ../../library/audioop.rst:2 -msgid ":mod:`!audioop` --- Manipulate raw audio data" -msgstr ":mod:`!audioop` --- 操作原始聲音檔案" - -#: ../../library/audioop.rst:10 -msgid "" -"This module is no longer part of the Python standard library. It was :ref:" -"`removed in Python 3.13 ` after being deprecated in " -"Python 3.11. The removal was decided in :pep:`594`." -msgstr "" -"這個模組已不再是 Python 標準函式庫的一部分。它在 Python 3.11 中被棄用，並\\ :" -"ref:`已在 Python 3.13 中被移除 `。它的移除是在 :pep:" -"`594` 中決定的。" - -#: ../../library/audioop.rst:14 -msgid "" -"The last version of Python that provided the :mod:`!audioop` module was " -"`Python 3.12 `_." -msgstr "" -"最後提供 :mod:`!audioop` 模組的 Python 版本是 `Python 3.12 `_。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-11-18 00:15+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" +"tw)\n" +"Language: zh_TW\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../library/audioop.rst:2 +msgid ":mod:`!audioop` --- Manipulate raw audio data" +msgstr ":mod:`!audioop` --- 操作原始聲音檔案" + +#: ../../library/audioop.rst:10 +msgid "" +"This module is no longer part of the Python standard library. It was :ref:" +"`removed in Python 3.13 ` after being deprecated in " +"Python 3.11. The removal was decided in :pep:`594`." +msgstr "" +"這個模組已不再是 Python 標準函式庫的一部分。它在 Python 3.11 中被棄用，並\\ :" +"ref:`已在 Python 3.13 中被移除 `。它的移除是在 :pep:" +"`594` 中決定的。" + +#: ../../library/audioop.rst:14 +msgid "" +"The last version of Python that provided the :mod:`!audioop` module was " +"`Python 3.12 `_." +msgstr "" +"最後提供 :mod:`!audioop` 模組的 Python 版本是 `Python 3.12 `_。" diff --git a/library/audit_events.po b/library/audit_events.po index 215970aa6e..412ba08550 100644 --- a/library/audit_events.po +++ b/library/audit_events.po @@ -1,143 +1,143 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# FIRST AUTHOR , YEAR. -# -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: 2021-12-06 21:50+0800\n" -"Last-Translator: Jordan Su \n" -"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" -"tw)\n" -"Language: zh_TW\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=UTF-8\n" -"Content-Transfer-Encoding: 8bit\n" -"X-Generator: Poedit 3.0\n" - -#: ../../library/audit_events.rst:6 -msgid "Audit events table" -msgstr "稽核事件表" - -#: ../../library/audit_events.rst:8 -msgid "" -"This table contains all events raised by :func:`sys.audit` " -"or :c:func:`PySys_Audit` calls throughout the CPython runtime and the " -"standard library. These calls were added in 3.8 or later (see :pep:`578`)." -msgstr "" -"這張表包含了所有在 CPython 運行環境 (runtime) 與標準函式庫對" -"於 :func:`sys.audit` 或 :c:func:`PySys_Audit` 的呼叫所觸發的事件。這些呼叫是" -"在 3.8 或更新的版本中被新增（請見 :pep:`578`\\ ）。" - -#: ../../library/audit_events.rst:12 -msgid "" -"See :func:`sys.addaudithook` and :c:func:`PySys_AddAuditHook` for " -"information on handling these events." -msgstr "" -"請參考 :func:`sys.addaudithook` 及 :c:func:`PySys_AddAuditHook` 來了解如何處" -"理這些事件。" - -#: ../../library/audit_events.rst:17 -msgid "" -"This table is generated from the CPython documentation, and may not " -"represent events raised by other implementations. See your runtime specific " -"documentation for actual events raised." -msgstr "" -"這張表是從 CPython 文件產生的，可能不包含其它實作所觸發的事件。請參考你的運行" -"環境 (runtime) 特定文件來了解實際會觸發的事件。" - -#: ../../library/audit_events.rst:23 -msgid "" -"The following events are raised internally and do not correspond to any " -"public API of CPython:" -msgstr "下列事件是內部觸發的，與任何 CPython 的公開 API 並無關係：" - -#: ../../library/audit_events.rst:27 -msgid "Audit event" -msgstr "稽核事件" - -#: ../../library/audit_events.rst:27 -msgid "Arguments" -msgstr "引數" - -#: ../../library/audit_events.rst:29 -msgid "_winapi.CreateFile" -msgstr "_winapi.CreateFile" - -#: ../../library/audit_events.rst:29 -msgid "" -"``file_name``, ``desired_access``, ``share_mode``, ``creation_disposition``, " -"``flags_and_attributes``" -msgstr "" -"``file_name``, ``desired_access``, ``share_mode``, ``creation_disposition``, " -"``flags_and_attributes``" - -#: ../../library/audit_events.rst:33 -msgid "_winapi.CreateJunction" -msgstr "_winapi.CreateJunction" - -#: ../../library/audit_events.rst:33 -msgid "``src_path``, ``dst_path``" -msgstr "``src_path``, ``dst_path``" - -#: ../../library/audit_events.rst:35 -msgid "_winapi.CreateNamedPipe" -msgstr "_winapi.CreateNamedPipe" - -#: ../../library/audit_events.rst:35 -msgid "``name``, ``open_mode``, ``pipe_mode``" -msgstr "``name``, ``open_mode``, ``pipe_mode``" - -#: ../../library/audit_events.rst:37 -msgid "_winapi.CreatePipe" -msgstr "_winapi.CreatePipe" - -#: ../../library/audit_events.rst:39 -msgid "_winapi.CreateProcess" -msgstr "_winapi.CreateProcess" - -#: ../../library/audit_events.rst:39 -msgid "``application_name``, ``command_line``, ``current_directory``" -msgstr "``application_name``, ``command_line``, ``current_directory``" - -#: ../../library/audit_events.rst:42 -msgid "_winapi.OpenProcess" -msgstr "_winapi.OpenProcess" - -#: ../../library/audit_events.rst:42 -msgid "``process_id``, ``desired_access``" -msgstr "``process_id``, ``desired_access``" - -#: ../../library/audit_events.rst:44 -msgid "_winapi.TerminateProcess" -msgstr "_winapi.TerminateProcess" - -#: ../../library/audit_events.rst:44 -msgid "``handle``, ``exit_code``" -msgstr "``handle``, ``exit_code``" - -#: ../../library/audit_events.rst:46 -msgid "_posixsubprocess.fork_exec" -msgstr "_posixsubprocess.fork_exec" - -#: ../../library/audit_events.rst:46 -msgid "``exec_list``, ``args``, ``env``" -msgstr "``exec_list``, ``args``, ``env``" - -#: ../../library/audit_events.rst:48 -msgid "ctypes.PyObj_FromPtr" -msgstr "ctypes.PyObj_FromPtr" - -#: ../../library/audit_events.rst:48 -msgid "``obj``" -msgstr "``obj``" - -#: ../../library/audit_events.rst:51 -msgid "The ``_posixsubprocess.fork_exec`` internal audit event." -msgstr "內部稽核事件 ``_posixsubprocess.fork_exec``。" - -#: ../../library/audit_events.rst:3 -msgid "audit events" -msgstr "audit events（稽核事件）" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# FIRST AUTHOR , YEAR. +# +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: 2021-12-06 21:50+0800\n" +"Last-Translator: Jordan Su \n" +"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" +"tw)\n" +"Language: zh_TW\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"X-Generator: Poedit 3.0\n" + +#: ../../library/audit_events.rst:6 +msgid "Audit events table" +msgstr "稽核事件表" + +#: ../../library/audit_events.rst:8 +msgid "" +"This table contains all events raised by :func:`sys.audit` " +"or :c:func:`PySys_Audit` calls throughout the CPython runtime and the " +"standard library. These calls were added in 3.8 or later (see :pep:`578`)." +msgstr "" +"這張表包含了所有在 CPython 運行環境 (runtime) 與標準函式庫對" +"於 :func:`sys.audit` 或 :c:func:`PySys_Audit` 的呼叫所觸發的事件。這些呼叫是" +"在 3.8 或更新的版本中被新增（請見 :pep:`578`\\ ）。" + +#: ../../library/audit_events.rst:12 +msgid "" +"See :func:`sys.addaudithook` and :c:func:`PySys_AddAuditHook` for " +"information on handling these events." +msgstr "" +"請參考 :func:`sys.addaudithook` 及 :c:func:`PySys_AddAuditHook` 來了解如何處" +"理這些事件。" + +#: ../../library/audit_events.rst:17 +msgid "" +"This table is generated from the CPython documentation, and may not " +"represent events raised by other implementations. See your runtime specific " +"documentation for actual events raised." +msgstr "" +"這張表是從 CPython 文件產生的，可能不包含其它實作所觸發的事件。請參考你的運行" +"環境 (runtime) 特定文件來了解實際會觸發的事件。" + +#: ../../library/audit_events.rst:23 +msgid "" +"The following events are raised internally and do not correspond to any " +"public API of CPython:" +msgstr "下列事件是內部觸發的，與任何 CPython 的公開 API 並無關係：" + +#: ../../library/audit_events.rst:27 +msgid "Audit event" +msgstr "稽核事件" + +#: ../../library/audit_events.rst:27 +msgid "Arguments" +msgstr "引數" + +#: ../../library/audit_events.rst:29 +msgid "_winapi.CreateFile" +msgstr "_winapi.CreateFile" + +#: ../../library/audit_events.rst:29 +msgid "" +"``file_name``, ``desired_access``, ``share_mode``, ``creation_disposition``, " +"``flags_and_attributes``" +msgstr "" +"``file_name``, ``desired_access``, ``share_mode``, ``creation_disposition``, " +"``flags_and_attributes``" + +#: ../../library/audit_events.rst:33 +msgid "_winapi.CreateJunction" +msgstr "_winapi.CreateJunction" + +#: ../../library/audit_events.rst:33 +msgid "``src_path``, ``dst_path``" +msgstr "``src_path``, ``dst_path``" + +#: ../../library/audit_events.rst:35 +msgid "_winapi.CreateNamedPipe" +msgstr "_winapi.CreateNamedPipe" + +#: ../../library/audit_events.rst:35 +msgid "``name``, ``open_mode``, ``pipe_mode``" +msgstr "``name``, ``open_mode``, ``pipe_mode``" + +#: ../../library/audit_events.rst:37 +msgid "_winapi.CreatePipe" +msgstr "_winapi.CreatePipe" + +#: ../../library/audit_events.rst:39 +msgid "_winapi.CreateProcess" +msgstr "_winapi.CreateProcess" + +#: ../../library/audit_events.rst:39 +msgid "``application_name``, ``command_line``, ``current_directory``" +msgstr "``application_name``, ``command_line``, ``current_directory``" + +#: ../../library/audit_events.rst:42 +msgid "_winapi.OpenProcess" +msgstr "_winapi.OpenProcess" + +#: ../../library/audit_events.rst:42 +msgid "``process_id``, ``desired_access``" +msgstr "``process_id``, ``desired_access``" + +#: ../../library/audit_events.rst:44 +msgid "_winapi.TerminateProcess" +msgstr "_winapi.TerminateProcess" + +#: ../../library/audit_events.rst:44 +msgid "``handle``, ``exit_code``" +msgstr "``handle``, ``exit_code``" + +#: ../../library/audit_events.rst:46 +msgid "_posixsubprocess.fork_exec" +msgstr "_posixsubprocess.fork_exec" + +#: ../../library/audit_events.rst:46 +msgid "``exec_list``, ``args``, ``env``" +msgstr "``exec_list``, ``args``, ``env``" + +#: ../../library/audit_events.rst:48 +msgid "ctypes.PyObj_FromPtr" +msgstr "ctypes.PyObj_FromPtr" + +#: ../../library/audit_events.rst:48 +msgid "``obj``" +msgstr "``obj``" + +#: ../../library/audit_events.rst:51 +msgid "The ``_posixsubprocess.fork_exec`` internal audit event." +msgstr "內部稽核事件 ``_posixsubprocess.fork_exec``。" + +#: ../../library/audit_events.rst:3 +msgid "audit events" +msgstr "audit events（稽核事件）" diff --git a/library/base64.po b/library/base64.po index 9af6ca2344..c31d20a4ad 100644 --- a/library/base64.po +++ b/library/base64.po @@ -1,570 +1,570 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Inndy, 2016 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-06-27 07:36+0000\n" -"PO-Revision-Date: 2018-05-23 14:39+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/base64.rst:2 -msgid ":mod:`!base64` --- Base16, Base32, Base64, Base85 Data Encodings" -msgstr ":mod:`!base64` --- Base16、Base32、Base64、Base85 資料編碼" - -#: ../../library/base64.rst:8 -msgid "**Source code:** :source:`Lib/base64.py`" -msgstr "**原始碼：** :source:`Lib/base64.py`" - -#: ../../library/base64.rst:16 -msgid "" -"This module provides functions for encoding binary data to printable ASCII " -"characters and decoding such encodings back to binary data. This includes " -"the :ref:`encodings specified in ` :rfc:`4648` (Base64, " -"Base32 and Base16) and the non-standard :ref:`Base85 encodings `." -msgstr "" -"這個模組提供將二進位資料編碼成可顯示 ASCII 字元以及解碼回原始資料的功能。這包括" -"了 :rfc:`4648` 中\\ :ref:`指定的編碼 `\\ （Base64、Base32 " -"和 Base16）和非標準的 :ref:`Base85 編碼 `。" - -#: ../../library/base64.rst:22 -msgid "" -"There are two interfaces provided by this module. The modern interface " -"supports encoding :term:`bytes-like objects ` to ASCII :" -"class:`bytes`, and decoding :term:`bytes-like objects ` " -"or strings containing ASCII to :class:`bytes`. Both base-64 alphabets " -"defined in :rfc:`4648` (normal, and URL- and filesystem-safe) are supported." -msgstr "" -"該模組提供了兩個介面。新介面支援將\\ :term:`類位元組物件 ` 編碼成 ASCII :class:`bytes`，並將包含 ASCII 的\\ :term:`類位元組物" -"件 `\\ 或字串解碼為 :class:`bytes`。支援 :rfc:`4648` 中定" -"義的兩種 base-64 字母表（常見和 URL 安全 (URL-safe) 及檔案系統安全 " -"(filesystem-safe) 字母表）。" - -#: ../../library/base64.rst:28 -msgid "" -"The :ref:`legacy interface ` does not support decoding from " -"strings, but it does provide functions for encoding and decoding to and " -"from :term:`file objects `. It only supports the Base64 " -"standard alphabet, and it adds newlines every 76 characters as per :rfc:" -"`2045`. Note that if you are looking for :rfc:`2045` support you probably " -"want to be looking at the :mod:`email` package instead." -msgstr "" -":ref:`舊版介面 `\\ 不支援從字串解碼，但它提供對\\ :term:`檔案物件 `\\ 進行" -"編碼和解碼的函式。它僅支援 Base64 標準字母表，並且按照 :rfc:`2045` 每 76 個字" -"元添加換行字元。請注意，如果你需要 :rfc:`2045` 的支援，你可能會需要 :mod:" -"`email` 函式庫。" - -#: ../../library/base64.rst:36 -msgid "" -"ASCII-only Unicode strings are now accepted by the decoding functions of the " -"modern interface." -msgstr "新介面的解碼功能現在接受 ASCII-only 的 Unicode 字串。" - -#: ../../library/base64.rst:40 -msgid "" -"Any :term:`bytes-like objects ` are now accepted by all " -"encoding and decoding functions in this module. Ascii85/Base85 support " -"added." -msgstr "" -"任何\\ :term:`類位元組物件 `\\ 現在被該模組中的所有編碼和" -"解碼函式接受。新增了對 Ascii85/Base85 的支援。" - -#: ../../library/base64.rst:48 -msgid "RFC 4648 Encodings" -msgstr "RFC 4648 編碼" - -#: ../../library/base64.rst:50 -msgid "" -"The :rfc:`4648` encodings are suitable for encoding binary data so that it " -"can be safely sent by email, used as parts of URLs, or included as part of " -"an HTTP POST request." -msgstr "" -":rfc:`4648` 編碼適合對二進位資料進行編碼來使得電子郵件、URL 或是 HTTP POST 內" -"容等傳輸管道能夠安全地傳遞資料。" - -#: ../../library/base64.rst:56 -msgid "" -"Encode the :term:`bytes-like object` *s* using Base64 and return the " -"encoded :class:`bytes`." -msgstr "" -"使用 Base64 對\\ :term:`類位元組物件 ` *s* 進行編碼並回傳" -"編碼過的 :class:`bytes`。" - -#: ../../library/base64.rst:59 -msgid "" -"Optional *altchars* must be a :term:`bytes-like object` of length 2 which " -"specifies an alternative alphabet for the ``+`` and ``/`` characters. This " -"allows an application to e.g. generate URL or filesystem safe Base64 " -"strings. The default is ``None``, for which the standard Base64 alphabet is " -"used." -msgstr "" -"可選的 *altchars* 必須是一個長度為 2 的\\ :term:`類位元組物件 `，用來指定替代的字母表，以替換 ``+`` 和 ``/`` 字元。這使得應用程式可" -"以生成對 URL 或檔案系統安全的 Base64 字串。預設值為 ``None``，即使用標準的 " -"Base64 字母表。" - -#: ../../library/base64.rst:64 -msgid "" -"May assert or raise a :exc:`ValueError` if the length of *altchars* is not " -"2. Raises a :exc:`TypeError` if *altchars* is not a :term:`bytes-like " -"object`." -msgstr "" -"如果 *altchars* 的長度不是 2，可以斷言或引發 :exc:`ValueError`。如果 " -"*altchars* 不是\\ :term:`類位元組物件 `，則會引發 :exc:" -"`TypeError`。" - -#: ../../library/base64.rst:70 -msgid "" -"Decode the Base64 encoded :term:`bytes-like object` or ASCII string *s* and " -"return the decoded :class:`bytes`." -msgstr "" -"將經過 Base64 編碼的\\ :term:`類位元組物件 `\\ 或 ASCII 字" -"串 *s* 解碼，並回傳解碼後的 :class:`bytes`。" - -#: ../../library/base64.rst:73 -msgid "" -"Optional *altchars* must be a :term:`bytes-like object` or ASCII string of " -"length 2 which specifies the alternative alphabet used instead of the ``+`` " -"and ``/`` characters." -msgstr "" -"可選的 *altchars* 必須是長度為 2 的\\ :term:`類位元組物件 `\\ 或 ASCII 字串，用於指定替代字母表，取代 ``+`` 和 ``/`` 字元。" - -#: ../../library/base64.rst:77 -msgid "" -"A :exc:`binascii.Error` exception is raised if *s* is incorrectly padded." -msgstr "如果 *s* 填充 (pad) 不正確，將引發 :exc:`binascii.Error` 例外。" - -#: ../../library/base64.rst:80 -msgid "" -"If *validate* is ``False`` (the default), characters that are neither in the " -"normal base-64 alphabet nor the alternative alphabet are discarded prior to " -"the padding check. If *validate* is ``True``, these non-alphabet characters " -"in the input result in a :exc:`binascii.Error`." -msgstr "" -"如果 *validate* 為 ``False``\\ （預設值），在 padding check（填充檢查）之前，" -"不屬於標準 base-64 字母表和替代字母表的字元將被丟棄。如果 *validate* 為 " -"``True``，輸入中的這些非字母表字元將導致引發 :exc:`binascii.Error`。" - -#: ../../library/base64.rst:86 -msgid "" -"For more information about the strict base64 check, see :func:`binascii." -"a2b_base64`" -msgstr "有關嚴格的 base64 檢查的更多資訊，請參閱 :func:`binascii.a2b_base64`。" - -#: ../../library/base64.rst:88 -msgid "" -"May assert or raise a :exc:`ValueError` if the length of *altchars* is not 2." -msgstr "如果 *altchars* 的長度不是 2，可能會斷言或引發 :exc:`ValueError`。" - -#: ../../library/base64.rst:92 -msgid "" -"Encode :term:`bytes-like object` *s* using the standard Base64 alphabet and " -"return the encoded :class:`bytes`." -msgstr "" -"使用標準 Base64 字母表對\\ :term:`類位元組物件 ` *s* 進行" -"編碼，並回傳編碼後的 :class:`bytes`。" - -#: ../../library/base64.rst:98 -msgid "" -"Decode :term:`bytes-like object` or ASCII string *s* using the standard " -"Base64 alphabet and return the decoded :class:`bytes`." -msgstr "" -"使用標準 Base64 字母表對\\ :term:`類位元組物件 `\\ 或 " -"ASCII 字串 *s* 進行解碼，並回傳解碼後的 :class:`bytes`。" - -#: ../../library/base64.rst:104 -msgid "" -"Encode :term:`bytes-like object` *s* using the URL- and filesystem-safe " -"alphabet, which substitutes ``-`` instead of ``+`` and ``_`` instead of ``/" -"`` in the standard Base64 alphabet, and return the encoded :class:`bytes`. " -"The result can still contain ``=``." -msgstr "" -"使用 URL 安全和檔案系統安全的字母表對\\ :term:`類位元組物件 ` *s* 進行編碼，該字母表將標準 Base64 字母表中的 ``+`` 替換為 ``-``，" -"``/`` 替換為 ``_``，並回傳編碼後的 :class:`bytes`。結果仍可能包含 ``=``。" - -#: ../../library/base64.rst:113 -msgid "" -"Decode :term:`bytes-like object` or ASCII string *s* using the URL- and " -"filesystem-safe alphabet, which substitutes ``-`` instead of ``+`` and ``_`` " -"instead of ``/`` in the standard Base64 alphabet, and return the decoded :" -"class:`bytes`." -msgstr "" -"使用 URL 安全和檔案系統安全字母表對\\ :term:`類位元組物件 `\\ 或 ASCII 字串 *s* 進行解碼，該字母表將標準 Base64 字母表中的 " -"``+`` 替換為 ``-``，``/`` 替換為 ``_``，並回傳解碼後的 :class:`bytes`。" - -#: ../../library/base64.rst:122 -msgid "" -"Encode the :term:`bytes-like object` *s* using Base32 and return the " -"encoded :class:`bytes`." -msgstr "" -"使用 Base32 對\\ :term:`類位元組物件 ` *s* 進行編碼，並回" -"傳編碼後的 :class:`bytes`。" - -#: ../../library/base64.rst:128 -msgid "" -"Decode the Base32 encoded :term:`bytes-like object` or ASCII string *s* and " -"return the decoded :class:`bytes`." -msgstr "" -"解碼經過 Base32 編碼的\\ :term:`類位元組物件 `\\ 或 ASCII " -"字串 *s*，並回傳解碼後的 :class:`bytes`。" - -#: ../../library/base64.rst:131 ../../library/base64.rst:179 -msgid "" -"Optional *casefold* is a flag specifying whether a lowercase alphabet is " -"acceptable as input. For security purposes, the default is ``False``." -msgstr "" -"可選的 *casefold* 是一個是否接受小寫字母表作為輸入的旗標。出於安全性考量，預" -"設值為 ``False``。" - -#: ../../library/base64.rst:135 -msgid "" -":rfc:`4648` allows for optional mapping of the digit 0 (zero) to the letter " -"O (oh), and for optional mapping of the digit 1 (one) to either the letter I " -"(eye) or letter L (el). The optional argument *map01* when not ``None``, " -"specifies which letter the digit 1 should be mapped to (when *map01* is not " -"``None``, the digit 0 is always mapped to the letter O). For security " -"purposes the default is ``None``, so that 0 and 1 are not allowed in the " -"input." -msgstr "" -":rfc:`4648` 允許將數字 0 選擇性地對應對映為字母 O，並且允許將數字 1 選擇性地" -"對映為字母 I 或字母 L。當可選的引數 *map01* 不為 ``None`` 時，指定數字 1 應該" -"對映為哪個字母（當 *map01* 不為 ``None`` 時，數字 0 總是對映為字母 O）。出於" -"安全性考量，預設值為 ``None``，因此不允許在輸入中使用數字 0 和 1。" - -#: ../../library/base64.rst:142 ../../library/base64.rst:183 -msgid "" -"A :exc:`binascii.Error` is raised if *s* is incorrectly padded or if there " -"are non-alphabet characters present in the input." -msgstr "" -"如果 *s* 的填充不正確或輸入中存在非字母表字元，將引發 :exc:`binascii.Error`。" - -#: ../../library/base64.rst:149 -msgid "" -"Similar to :func:`b32encode` but uses the Extended Hex Alphabet, as defined " -"in :rfc:`4648`." -msgstr "" -"類似於 :func:`b32encode`，但使用在 :rfc:`4648` 中定義的擴展十六進位字母表 " -"(Extended Hex Alphabet)。" - -#: ../../library/base64.rst:157 -msgid "" -"Similar to :func:`b32decode` but uses the Extended Hex Alphabet, as defined " -"in :rfc:`4648`." -msgstr "" -"類似於 :func:`b32decode`，但使用在 :rfc:`4648` 中定義的擴展十六進位字母表。" - -#: ../../library/base64.rst:160 -msgid "" -"This version does not allow the digit 0 (zero) to the letter O (oh) and " -"digit 1 (one) to either the letter I (eye) or letter L (el) mappings, all " -"these characters are included in the Extended Hex Alphabet and are not " -"interchangeable." -msgstr "" -"這個版本不允許將數字 0 對映為字母 O ，以及將數字 1 對映為字母 I 或字母 L，所" -"有這些字元都包含在擴展十六進位字母表中，並且不能互換使用。" - -#: ../../library/base64.rst:170 -msgid "" -"Encode the :term:`bytes-like object` *s* using Base16 and return the " -"encoded :class:`bytes`." -msgstr "" -"使用 Base16 對\\ :term:`類位元組物件 ` *s* 進行編碼，並回" -"傳編碼後的 :class:`bytes`。" - -#: ../../library/base64.rst:176 -msgid "" -"Decode the Base16 encoded :term:`bytes-like object` or ASCII string *s* and " -"return the decoded :class:`bytes`." -msgstr "" -"解碼經過 Base16 編碼的\\ :term:`類位元組物件 `\\ 或 ASCII " -"字串 *s*，並回傳解碼後的 :class:`bytes`。" - -#: ../../library/base64.rst:190 -msgid "Base85 Encodings" -msgstr "Base85 編碼" - -#: ../../library/base64.rst:192 -msgid "" -"Base85 encoding is not formally specified but rather a de facto standard, " -"thus different systems perform the encoding differently." -msgstr "" - -#: ../../library/base64.rst:195 -msgid "" -"The :func:`a85encode` and :func:`b85encode` functions in this module are two " -"implementations of the de facto standard. You should call the function with " -"the Base85 implementation used by the software you intend to work with." -msgstr "" - -#: ../../library/base64.rst:199 -msgid "" -"The two functions present in this module differ in how they handle the " -"following:" -msgstr "" - -#: ../../library/base64.rst:201 -msgid "Whether to include enclosing ``<~`` and ``~>`` markers" -msgstr "" - -#: ../../library/base64.rst:202 -msgid "Whether to include newline characters" -msgstr "" - -#: ../../library/base64.rst:203 -msgid "The set of ASCII characters used for encoding" -msgstr "" - -#: ../../library/base64.rst:204 -msgid "Handling of null bytes" -msgstr "" - -#: ../../library/base64.rst:206 -msgid "" -"Refer to the documentation of the individual functions for more information." -msgstr "" - -#: ../../library/base64.rst:210 -msgid "" -"Encode the :term:`bytes-like object` *b* using Ascii85 and return the " -"encoded :class:`bytes`." -msgstr "" -"使用 Ascii85 對\\ :term:`類位元組物件 ` *b* 進行編碼，並回" -"傳編碼後的 :class:`bytes`。" - -#: ../../library/base64.rst:213 -msgid "" -"*foldspaces* is an optional flag that uses the special short sequence 'y' " -"instead of 4 consecutive spaces (ASCII 0x20) as supported by 'btoa'. This " -"feature is not supported by the \"standard\" Ascii85 encoding." -msgstr "" -"*foldspaces* 是一個可選的旗標，它使用特殊的短序列 'y' 來替代連續的 4 個空格 " -"(ASCII 0x20)，這是由 'btoa' 支援的功能。這個特性不被「標準」的 Ascii85 編碼所" -"支援。" - -#: ../../library/base64.rst:217 -msgid "" -"*wrapcol* controls whether the output should have newline (``b'\\n'``) " -"characters added to it. If this is non-zero, each output line will be at " -"most this many characters long, excluding the trailing newline." -msgstr "" -"*wrapcol* 控制輸出是否應該包含換行字元 (``b'\\n'``) 。如果這個值不為零，每行" -"輸出的長度將不超過這個字元長度（不包含後面的換行符號）。" - -#: ../../library/base64.rst:221 -msgid "" -"*pad* controls whether the input is padded to a multiple of 4 before " -"encoding. Note that the ``btoa`` implementation always pads." -msgstr "" -"*pad* 控制是否在編碼之前將輸入填充為 4 的倍數。請注意，``btoa`` 實作始終會填" -"充。" - -#: ../../library/base64.rst:224 -msgid "" -"*adobe* controls whether the encoded byte sequence is framed with ``<~`` and " -"``~>``, which is used by the Adobe implementation." -msgstr "" -"*adobe* 控制編碼的位元組序列前後是否加上 ``<~`` 和 ``~>``，這是 Adobe 實作中" -"使用的。" - -#: ../../library/base64.rst:232 -msgid "" -"Decode the Ascii85 encoded :term:`bytes-like object` or ASCII string *b* and " -"return the decoded :class:`bytes`." -msgstr "" -"解碼經過 Ascii85 編碼的\\ :term:`類位元組物件 `\\ 或 " -"ASCII 字串 *b*，並回傳解碼後的 :class:`bytes`。" - -#: ../../library/base64.rst:235 -msgid "" -"*foldspaces* is a flag that specifies whether the 'y' short sequence should " -"be accepted as shorthand for 4 consecutive spaces (ASCII 0x20). This feature " -"is not supported by the \"standard\" Ascii85 encoding." -msgstr "" -"*foldspaces* 是一個旗標，指定是否應該將短序列 'y' 視為 4 個連續的空格 (ASCII " -"0x20) 的簡寫。這個功能不受「標準」Ascii85 編碼的支援。" - -#: ../../library/base64.rst:239 -msgid "" -"*adobe* controls whether the input sequence is in Adobe Ascii85 format (i.e. " -"is framed with <~ and ~>)." -msgstr "" -"*adobe* 控制輸入序列是否符合 Adobe Ascii85 格式（即前後加上 ``<~`` 和 " -"``~>``）。" - -#: ../../library/base64.rst:242 -msgid "" -"*ignorechars* should be a :term:`bytes-like object` or ASCII string " -"containing characters to ignore from the input. This should only contain " -"whitespace characters, and by default contains all whitespace characters in " -"ASCII." -msgstr "" -"*ignorechars* 是一個包含要從輸入中忽略的字元的\\ :term:`類位元組物件 `\\ 或 ASCII 字串。這只包含空格字元，預設情況下包含 ASCII 中的所" -"有空格字元。" - -#: ../../library/base64.rst:252 -msgid "" -"Encode the :term:`bytes-like object` *b* using base85 (as used in e.g. git-" -"style binary diffs) and return the encoded :class:`bytes`." -msgstr "" -"使用 Base85（例如，git 風格的二進位差異 (binary diff)）對\\ :term:`類位元組物" -"件 ` *b* 進行編碼，並回傳編碼後的 :class:`bytes`。" - -#: ../../library/base64.rst:255 -msgid "" -"If *pad* is true, the input is padded with ``b'\\0'`` so its length is a " -"multiple of 4 bytes before encoding." -msgstr "" -"如果 *pad* 為 true，則在編碼之前，輸入將使用 ``b'\\0'`` 進行填充，以使其長度" -"為 4 的倍數。" - -#: ../../library/base64.rst:263 -msgid "" -"Decode the base85-encoded :term:`bytes-like object` or ASCII string *b* and " -"return the decoded :class:`bytes`. Padding is implicitly removed, if " -"necessary." -msgstr "" -"解碼經過 base85 編碼的\\ :term:`類位元組物件 `\\ 或 ASCII " -"字串 *b*，並回傳解碼後的 :class:`bytes`。必要時會隱式移除填充。" - -#: ../../library/base64.rst:272 -msgid "" -"Encode the :term:`bytes-like object` *s* using Z85 (as used in ZeroMQ) and " -"return the encoded :class:`bytes`. See `Z85 specification `_ for more information." -msgstr "" -"使用 Z85（如用於 ZeroMQ）對\\ :term:`類位元組物件 ` *s* 進行編碼，並回傳" -"編碼後的 :class:`bytes`。有關更多資訊，請參閱 `Z85 規格 `_。" - -#: ../../library/base64.rst:281 -msgid "" -"Decode the Z85-encoded :term:`bytes-like object` or ASCII string *s* and " -"return the decoded :class:`bytes`. See `Z85 specification `_ for more information." -msgstr "" -"解碼經 Z85 編碼的\\ :term:`類位元組物件 `\\ 或 ASCII " -"字串 *s*，並回傳解碼後的 :class:`bytes`。有關更多資訊，請參閱 `Z85 規格 `_。" - -#: ../../library/base64.rst:291 -msgid "Legacy Interface" -msgstr "舊版介面" - -#: ../../library/base64.rst:295 -msgid "" -"Decode the contents of the binary *input* file and write the resulting " -"binary data to the *output* file. *input* and *output* must be :term:`file " -"objects `. *input* will be read until ``input.readline()`` " -"returns an empty bytes object." -msgstr "" -"解碼二進位檔案 *input* 的內容，並將結果的二進位資料寫入 *output* 檔案。 " -"*input* 和 *output* 必須是\\ :term:`檔案物件 `。*input* 將被讀" -"取，直到 ``input.readline()`` 回傳一個空的 bytes 物件為止。" - -#: ../../library/base64.rst:303 -msgid "" -"Decode the :term:`bytes-like object` *s*, which must contain one or more " -"lines of base64 encoded data, and return the decoded :class:`bytes`." -msgstr "" -"解碼必須包含一行或多行的 base64 編碼資料\\ :term:`類位元組物件 ` *s*，並回傳解碼後的 :class:`bytes`。" - -#: ../../library/base64.rst:311 -msgid "" -"Encode the contents of the binary *input* file and write the resulting " -"base64 encoded data to the *output* file. *input* and *output* must be :term:" -"`file objects `. *input* will be read until ``input.read()`` " -"returns an empty bytes object. :func:`encode` inserts a newline character " -"(``b'\\n'``) after every 76 bytes of the output, as well as ensuring that " -"the output always ends with a newline, as per :rfc:`2045` (MIME)." -msgstr "" -"編碼二進位檔案 *input* 的內容，並將結果的 base64 編碼資料寫入 *output* 檔案。" -"*input* 和 *output* 必須是\\ :term:`檔案物件 `。*input* 將被讀" -"取，直到 ``input.read()`` 回傳一個空的 bytes 物件為止。:func:`encode` 會在輸" -"出的每 76 個位元組之後插入一個換行字元 (``b'\\n'``)，並確保輸出始終以換行字元" -"結尾，符合 :rfc:`2045` (MIME) 的規定。" - -#: ../../library/base64.rst:321 -msgid "" -"Encode the :term:`bytes-like object` *s*, which can contain arbitrary binary " -"data, and return :class:`bytes` containing the base64-encoded data, with " -"newlines (``b'\\n'``) inserted after every 76 bytes of output, and ensuring " -"that there is a trailing newline, as per :rfc:`2045` (MIME)." -msgstr "" -"對包含任意二進位資料的\\ :term:`類位元組物件 ` *s* 進行編" -"碼，並回傳包含 base64 編碼資料 :class:`bytes`，在每 76 個輸出位元組後插入換行" -"字元 (``b'\\n'``) ，並確保有尾隨換行字元，符合 :rfc:`2045` (MIME) 的規定。" - -#: ../../library/base64.rst:329 -msgid "An example usage of the module:" -msgstr "模組的一個範例用法：" - -#: ../../library/base64.rst:342 -msgid "Security Considerations" -msgstr "安全性注意事項" - -#: ../../library/base64.rst:344 -msgid "" -"A new security considerations section was added to :rfc:`4648` (section 12); " -"it's recommended to review the security section for any code deployed to " -"production." -msgstr "" -":rfc:`4648`\\ （第 12 節）中添加了一個新的安全性考量部分；建議對部署到正式環" -"境的任何程式碼進行安全性部分的審查。" - -#: ../../library/base64.rst:349 -msgid "Module :mod:`binascii`" -msgstr ":mod:`binascii` 模組" - -#: ../../library/base64.rst:350 -msgid "" -"Support module containing ASCII-to-binary and binary-to-ASCII conversions." -msgstr "" -"支援模組中包含 ASCII 到二進位 (ASCII-to-binary) 和二進位到 ASCII (binary-to-" -"ASCII) 的轉換功能。" - -#: ../../library/base64.rst:352 -msgid "" -":rfc:`1521` - MIME (Multipurpose Internet Mail Extensions) Part One: " -"Mechanisms for Specifying and Describing the Format of Internet Message " -"Bodies" -msgstr "" -":rfc:`1521` - MIME（多用途網際網路郵件擴展）第一部分：指定和描述網際網路主體" -"格式的機制。" - -#: ../../library/base64.rst:353 -msgid "" -"Section 5.2, \"Base64 Content-Transfer-Encoding,\" provides the definition " -"of the base64 encoding." -msgstr "" -"第 5.2 節，\"Base64 Content-Transfer-Encoding\"，提供了 base64 編碼的定義。" - -#: ../../library/base64.rst:10 -msgid "base64" -msgstr "base64" - -#: ../../library/base64.rst:10 -msgid "encoding" -msgstr "encoding（編碼）" - -#: ../../library/base64.rst:10 -msgid "MIME" -msgstr "MIME" - -#: ../../library/base64.rst:10 -msgid "base64 encoding" -msgstr "base64 encoding（base64 編碼）" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Inndy, 2016 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-06-27 07:36+0000\n" +"PO-Revision-Date: 2018-05-23 14:39+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/base64.rst:2 +msgid ":mod:`!base64` --- Base16, Base32, Base64, Base85 Data Encodings" +msgstr ":mod:`!base64` --- Base16、Base32、Base64、Base85 資料編碼" + +#: ../../library/base64.rst:8 +msgid "**Source code:** :source:`Lib/base64.py`" +msgstr "**原始碼：** :source:`Lib/base64.py`" + +#: ../../library/base64.rst:16 +msgid "" +"This module provides functions for encoding binary data to printable ASCII " +"characters and decoding such encodings back to binary data. This includes " +"the :ref:`encodings specified in ` :rfc:`4648` (Base64, " +"Base32 and Base16) and the non-standard :ref:`Base85 encodings `." +msgstr "" +"這個模組提供將二進位資料編碼成可顯示 ASCII 字元以及解碼回原始資料的功能。這包括" +"了 :rfc:`4648` 中\\ :ref:`指定的編碼 `\\ （Base64、Base32 " +"和 Base16）和非標準的 :ref:`Base85 編碼 `。" + +#: ../../library/base64.rst:22 +msgid "" +"There are two interfaces provided by this module. The modern interface " +"supports encoding :term:`bytes-like objects ` to ASCII :" +"class:`bytes`, and decoding :term:`bytes-like objects ` " +"or strings containing ASCII to :class:`bytes`. Both base-64 alphabets " +"defined in :rfc:`4648` (normal, and URL- and filesystem-safe) are supported." +msgstr "" +"該模組提供了兩個介面。新介面支援將\\ :term:`類位元組物件 ` 編碼成 ASCII :class:`bytes`，並將包含 ASCII 的\\ :term:`類位元組物" +"件 `\\ 或字串解碼為 :class:`bytes`。支援 :rfc:`4648` 中定" +"義的兩種 base-64 字母表（常見和 URL 安全 (URL-safe) 及檔案系統安全 " +"(filesystem-safe) 字母表）。" + +#: ../../library/base64.rst:28 +msgid "" +"The :ref:`legacy interface ` does not support decoding from " +"strings, but it does provide functions for encoding and decoding to and " +"from :term:`file objects `. It only supports the Base64 " +"standard alphabet, and it adds newlines every 76 characters as per :rfc:" +"`2045`. Note that if you are looking for :rfc:`2045` support you probably " +"want to be looking at the :mod:`email` package instead." +msgstr "" +":ref:`舊版介面 `\\ 不支援從字串解碼，但它提供對\\ :term:`檔案物件 `\\ 進行" +"編碼和解碼的函式。它僅支援 Base64 標準字母表，並且按照 :rfc:`2045` 每 76 個字" +"元添加換行字元。請注意，如果你需要 :rfc:`2045` 的支援，你可能會需要 :mod:" +"`email` 函式庫。" + +#: ../../library/base64.rst:36 +msgid "" +"ASCII-only Unicode strings are now accepted by the decoding functions of the " +"modern interface." +msgstr "新介面的解碼功能現在接受 ASCII-only 的 Unicode 字串。" + +#: ../../library/base64.rst:40 +msgid "" +"Any :term:`bytes-like objects ` are now accepted by all " +"encoding and decoding functions in this module. Ascii85/Base85 support " +"added." +msgstr "" +"任何\\ :term:`類位元組物件 `\\ 現在被該模組中的所有編碼和" +"解碼函式接受。新增了對 Ascii85/Base85 的支援。" + +#: ../../library/base64.rst:48 +msgid "RFC 4648 Encodings" +msgstr "RFC 4648 編碼" + +#: ../../library/base64.rst:50 +msgid "" +"The :rfc:`4648` encodings are suitable for encoding binary data so that it " +"can be safely sent by email, used as parts of URLs, or included as part of " +"an HTTP POST request." +msgstr "" +":rfc:`4648` 編碼適合對二進位資料進行編碼來使得電子郵件、URL 或是 HTTP POST 內" +"容等傳輸管道能夠安全地傳遞資料。" + +#: ../../library/base64.rst:56 +msgid "" +"Encode the :term:`bytes-like object` *s* using Base64 and return the " +"encoded :class:`bytes`." +msgstr "" +"使用 Base64 對\\ :term:`類位元組物件 ` *s* 進行編碼並回傳" +"編碼過的 :class:`bytes`。" + +#: ../../library/base64.rst:59 +msgid "" +"Optional *altchars* must be a :term:`bytes-like object` of length 2 which " +"specifies an alternative alphabet for the ``+`` and ``/`` characters. This " +"allows an application to e.g. generate URL or filesystem safe Base64 " +"strings. The default is ``None``, for which the standard Base64 alphabet is " +"used." +msgstr "" +"可選的 *altchars* 必須是一個長度為 2 的\\ :term:`類位元組物件 `，用來指定替代的字母表，以替換 ``+`` 和 ``/`` 字元。這使得應用程式可" +"以生成對 URL 或檔案系統安全的 Base64 字串。預設值為 ``None``，即使用標準的 " +"Base64 字母表。" + +#: ../../library/base64.rst:64 +msgid "" +"May assert or raise a :exc:`ValueError` if the length of *altchars* is not " +"2. Raises a :exc:`TypeError` if *altchars* is not a :term:`bytes-like " +"object`." +msgstr "" +"如果 *altchars* 的長度不是 2，可以斷言或引發 :exc:`ValueError`。如果 " +"*altchars* 不是\\ :term:`類位元組物件 `，則會引發 :exc:" +"`TypeError`。" + +#: ../../library/base64.rst:70 +msgid "" +"Decode the Base64 encoded :term:`bytes-like object` or ASCII string *s* and " +"return the decoded :class:`bytes`." +msgstr "" +"將經過 Base64 編碼的\\ :term:`類位元組物件 `\\ 或 ASCII 字" +"串 *s* 解碼，並回傳解碼後的 :class:`bytes`。" + +#: ../../library/base64.rst:73 +msgid "" +"Optional *altchars* must be a :term:`bytes-like object` or ASCII string of " +"length 2 which specifies the alternative alphabet used instead of the ``+`` " +"and ``/`` characters." +msgstr "" +"可選的 *altchars* 必須是長度為 2 的\\ :term:`類位元組物件 `\\ 或 ASCII 字串，用於指定替代字母表，取代 ``+`` 和 ``/`` 字元。" + +#: ../../library/base64.rst:77 +msgid "" +"A :exc:`binascii.Error` exception is raised if *s* is incorrectly padded." +msgstr "如果 *s* 填充 (pad) 不正確，將引發 :exc:`binascii.Error` 例外。" + +#: ../../library/base64.rst:80 +msgid "" +"If *validate* is ``False`` (the default), characters that are neither in the " +"normal base-64 alphabet nor the alternative alphabet are discarded prior to " +"the padding check. If *validate* is ``True``, these non-alphabet characters " +"in the input result in a :exc:`binascii.Error`." +msgstr "" +"如果 *validate* 為 ``False``\\ （預設值），在 padding check（填充檢查）之前，" +"不屬於標準 base-64 字母表和替代字母表的字元將被丟棄。如果 *validate* 為 " +"``True``，輸入中的這些非字母表字元將導致引發 :exc:`binascii.Error`。" + +#: ../../library/base64.rst:86 +msgid "" +"For more information about the strict base64 check, see :func:`binascii." +"a2b_base64`" +msgstr "有關嚴格的 base64 檢查的更多資訊，請參閱 :func:`binascii.a2b_base64`。" + +#: ../../library/base64.rst:88 +msgid "" +"May assert or raise a :exc:`ValueError` if the length of *altchars* is not 2." +msgstr "如果 *altchars* 的長度不是 2，可能會斷言或引發 :exc:`ValueError`。" + +#: ../../library/base64.rst:92 +msgid "" +"Encode :term:`bytes-like object` *s* using the standard Base64 alphabet and " +"return the encoded :class:`bytes`." +msgstr "" +"使用標準 Base64 字母表對\\ :term:`類位元組物件 ` *s* 進行" +"編碼，並回傳編碼後的 :class:`bytes`。" + +#: ../../library/base64.rst:98 +msgid "" +"Decode :term:`bytes-like object` or ASCII string *s* using the standard " +"Base64 alphabet and return the decoded :class:`bytes`." +msgstr "" +"使用標準 Base64 字母表對\\ :term:`類位元組物件 `\\ 或 " +"ASCII 字串 *s* 進行解碼，並回傳解碼後的 :class:`bytes`。" + +#: ../../library/base64.rst:104 +msgid "" +"Encode :term:`bytes-like object` *s* using the URL- and filesystem-safe " +"alphabet, which substitutes ``-`` instead of ``+`` and ``_`` instead of ``/" +"`` in the standard Base64 alphabet, and return the encoded :class:`bytes`. " +"The result can still contain ``=``." +msgstr "" +"使用 URL 安全和檔案系統安全的字母表對\\ :term:`類位元組物件 ` *s* 進行編碼，該字母表將標準 Base64 字母表中的 ``+`` 替換為 ``-``，" +"``/`` 替換為 ``_``，並回傳編碼後的 :class:`bytes`。結果仍可能包含 ``=``。" + +#: ../../library/base64.rst:113 +msgid "" +"Decode :term:`bytes-like object` or ASCII string *s* using the URL- and " +"filesystem-safe alphabet, which substitutes ``-`` instead of ``+`` and ``_`` " +"instead of ``/`` in the standard Base64 alphabet, and return the decoded :" +"class:`bytes`." +msgstr "" +"使用 URL 安全和檔案系統安全字母表對\\ :term:`類位元組物件 `\\ 或 ASCII 字串 *s* 進行解碼，該字母表將標準 Base64 字母表中的 " +"``+`` 替換為 ``-``，``/`` 替換為 ``_``，並回傳解碼後的 :class:`bytes`。" + +#: ../../library/base64.rst:122 +msgid "" +"Encode the :term:`bytes-like object` *s* using Base32 and return the " +"encoded :class:`bytes`." +msgstr "" +"使用 Base32 對\\ :term:`類位元組物件 ` *s* 進行編碼，並回" +"傳編碼後的 :class:`bytes`。" + +#: ../../library/base64.rst:128 +msgid "" +"Decode the Base32 encoded :term:`bytes-like object` or ASCII string *s* and " +"return the decoded :class:`bytes`." +msgstr "" +"解碼經過 Base32 編碼的\\ :term:`類位元組物件 `\\ 或 ASCII " +"字串 *s*，並回傳解碼後的 :class:`bytes`。" + +#: ../../library/base64.rst:131 ../../library/base64.rst:179 +msgid "" +"Optional *casefold* is a flag specifying whether a lowercase alphabet is " +"acceptable as input. For security purposes, the default is ``False``." +msgstr "" +"可選的 *casefold* 是一個是否接受小寫字母表作為輸入的旗標。出於安全性考量，預" +"設值為 ``False``。" + +#: ../../library/base64.rst:135 +msgid "" +":rfc:`4648` allows for optional mapping of the digit 0 (zero) to the letter " +"O (oh), and for optional mapping of the digit 1 (one) to either the letter I " +"(eye) or letter L (el). The optional argument *map01* when not ``None``, " +"specifies which letter the digit 1 should be mapped to (when *map01* is not " +"``None``, the digit 0 is always mapped to the letter O). For security " +"purposes the default is ``None``, so that 0 and 1 are not allowed in the " +"input." +msgstr "" +":rfc:`4648` 允許將數字 0 選擇性地對應對映為字母 O，並且允許將數字 1 選擇性地" +"對映為字母 I 或字母 L。當可選的引數 *map01* 不為 ``None`` 時，指定數字 1 應該" +"對映為哪個字母（當 *map01* 不為 ``None`` 時，數字 0 總是對映為字母 O）。出於" +"安全性考量，預設值為 ``None``，因此不允許在輸入中使用數字 0 和 1。" + +#: ../../library/base64.rst:142 ../../library/base64.rst:183 +msgid "" +"A :exc:`binascii.Error` is raised if *s* is incorrectly padded or if there " +"are non-alphabet characters present in the input." +msgstr "" +"如果 *s* 的填充不正確或輸入中存在非字母表字元，將引發 :exc:`binascii.Error`。" + +#: ../../library/base64.rst:149 +msgid "" +"Similar to :func:`b32encode` but uses the Extended Hex Alphabet, as defined " +"in :rfc:`4648`." +msgstr "" +"類似於 :func:`b32encode`，但使用在 :rfc:`4648` 中定義的擴展十六進位字母表 " +"(Extended Hex Alphabet)。" + +#: ../../library/base64.rst:157 +msgid "" +"Similar to :func:`b32decode` but uses the Extended Hex Alphabet, as defined " +"in :rfc:`4648`." +msgstr "" +"類似於 :func:`b32decode`，但使用在 :rfc:`4648` 中定義的擴展十六進位字母表。" + +#: ../../library/base64.rst:160 +msgid "" +"This version does not allow the digit 0 (zero) to the letter O (oh) and " +"digit 1 (one) to either the letter I (eye) or letter L (el) mappings, all " +"these characters are included in the Extended Hex Alphabet and are not " +"interchangeable." +msgstr "" +"這個版本不允許將數字 0 對映為字母 O ，以及將數字 1 對映為字母 I 或字母 L，所" +"有這些字元都包含在擴展十六進位字母表中，並且不能互換使用。" + +#: ../../library/base64.rst:170 +msgid "" +"Encode the :term:`bytes-like object` *s* using Base16 and return the " +"encoded :class:`bytes`." +msgstr "" +"使用 Base16 對\\ :term:`類位元組物件 ` *s* 進行編碼，並回" +"傳編碼後的 :class:`bytes`。" + +#: ../../library/base64.rst:176 +msgid "" +"Decode the Base16 encoded :term:`bytes-like object` or ASCII string *s* and " +"return the decoded :class:`bytes`." +msgstr "" +"解碼經過 Base16 編碼的\\ :term:`類位元組物件 `\\ 或 ASCII " +"字串 *s*，並回傳解碼後的 :class:`bytes`。" + +#: ../../library/base64.rst:190 +msgid "Base85 Encodings" +msgstr "Base85 編碼" + +#: ../../library/base64.rst:192 +msgid "" +"Base85 encoding is not formally specified but rather a de facto standard, " +"thus different systems perform the encoding differently." +msgstr "" + +#: ../../library/base64.rst:195 +msgid "" +"The :func:`a85encode` and :func:`b85encode` functions in this module are two " +"implementations of the de facto standard. You should call the function with " +"the Base85 implementation used by the software you intend to work with." +msgstr "" + +#: ../../library/base64.rst:199 +msgid "" +"The two functions present in this module differ in how they handle the " +"following:" +msgstr "" + +#: ../../library/base64.rst:201 +msgid "Whether to include enclosing ``<~`` and ``~>`` markers" +msgstr "" + +#: ../../library/base64.rst:202 +msgid "Whether to include newline characters" +msgstr "" + +#: ../../library/base64.rst:203 +msgid "The set of ASCII characters used for encoding" +msgstr "" + +#: ../../library/base64.rst:204 +msgid "Handling of null bytes" +msgstr "" + +#: ../../library/base64.rst:206 +msgid "" +"Refer to the documentation of the individual functions for more information." +msgstr "" + +#: ../../library/base64.rst:210 +msgid "" +"Encode the :term:`bytes-like object` *b* using Ascii85 and return the " +"encoded :class:`bytes`." +msgstr "" +"使用 Ascii85 對\\ :term:`類位元組物件 ` *b* 進行編碼，並回" +"傳編碼後的 :class:`bytes`。" + +#: ../../library/base64.rst:213 +msgid "" +"*foldspaces* is an optional flag that uses the special short sequence 'y' " +"instead of 4 consecutive spaces (ASCII 0x20) as supported by 'btoa'. This " +"feature is not supported by the \"standard\" Ascii85 encoding." +msgstr "" +"*foldspaces* 是一個可選的旗標，它使用特殊的短序列 'y' 來替代連續的 4 個空格 " +"(ASCII 0x20)，這是由 'btoa' 支援的功能。這個特性不被「標準」的 Ascii85 編碼所" +"支援。" + +#: ../../library/base64.rst:217 +msgid "" +"*wrapcol* controls whether the output should have newline (``b'\\n'``) " +"characters added to it. If this is non-zero, each output line will be at " +"most this many characters long, excluding the trailing newline." +msgstr "" +"*wrapcol* 控制輸出是否應該包含換行字元 (``b'\\n'``) 。如果這個值不為零，每行" +"輸出的長度將不超過這個字元長度（不包含後面的換行符號）。" + +#: ../../library/base64.rst:221 +msgid "" +"*pad* controls whether the input is padded to a multiple of 4 before " +"encoding. Note that the ``btoa`` implementation always pads." +msgstr "" +"*pad* 控制是否在編碼之前將輸入填充為 4 的倍數。請注意，``btoa`` 實作始終會填" +"充。" + +#: ../../library/base64.rst:224 +msgid "" +"*adobe* controls whether the encoded byte sequence is framed with ``<~`` and " +"``~>``, which is used by the Adobe implementation." +msgstr "" +"*adobe* 控制編碼的位元組序列前後是否加上 ``<~`` 和 ``~>``，這是 Adobe 實作中" +"使用的。" + +#: ../../library/base64.rst:232 +msgid "" +"Decode the Ascii85 encoded :term:`bytes-like object` or ASCII string *b* and " +"return the decoded :class:`bytes`." +msgstr "" +"解碼經過 Ascii85 編碼的\\ :term:`類位元組物件 `\\ 或 " +"ASCII 字串 *b*，並回傳解碼後的 :class:`bytes`。" + +#: ../../library/base64.rst:235 +msgid "" +"*foldspaces* is a flag that specifies whether the 'y' short sequence should " +"be accepted as shorthand for 4 consecutive spaces (ASCII 0x20). This feature " +"is not supported by the \"standard\" Ascii85 encoding." +msgstr "" +"*foldspaces* 是一個旗標，指定是否應該將短序列 'y' 視為 4 個連續的空格 (ASCII " +"0x20) 的簡寫。這個功能不受「標準」Ascii85 編碼的支援。" + +#: ../../library/base64.rst:239 +msgid "" +"*adobe* controls whether the input sequence is in Adobe Ascii85 format (i.e. " +"is framed with <~ and ~>)." +msgstr "" +"*adobe* 控制輸入序列是否符合 Adobe Ascii85 格式（即前後加上 ``<~`` 和 " +"``~>``）。" + +#: ../../library/base64.rst:242 +msgid "" +"*ignorechars* should be a :term:`bytes-like object` or ASCII string " +"containing characters to ignore from the input. This should only contain " +"whitespace characters, and by default contains all whitespace characters in " +"ASCII." +msgstr "" +"*ignorechars* 是一個包含要從輸入中忽略的字元的\\ :term:`類位元組物件 `\\ 或 ASCII 字串。這只包含空格字元，預設情況下包含 ASCII 中的所" +"有空格字元。" + +#: ../../library/base64.rst:252 +msgid "" +"Encode the :term:`bytes-like object` *b* using base85 (as used in e.g. git-" +"style binary diffs) and return the encoded :class:`bytes`." +msgstr "" +"使用 Base85（例如，git 風格的二進位差異 (binary diff)）對\\ :term:`類位元組物" +"件 ` *b* 進行編碼，並回傳編碼後的 :class:`bytes`。" + +#: ../../library/base64.rst:255 +msgid "" +"If *pad* is true, the input is padded with ``b'\\0'`` so its length is a " +"multiple of 4 bytes before encoding." +msgstr "" +"如果 *pad* 為 true，則在編碼之前，輸入將使用 ``b'\\0'`` 進行填充，以使其長度" +"為 4 的倍數。" + +#: ../../library/base64.rst:263 +msgid "" +"Decode the base85-encoded :term:`bytes-like object` or ASCII string *b* and " +"return the decoded :class:`bytes`. Padding is implicitly removed, if " +"necessary." +msgstr "" +"解碼經過 base85 編碼的\\ :term:`類位元組物件 `\\ 或 ASCII " +"字串 *b*，並回傳解碼後的 :class:`bytes`。必要時會隱式移除填充。" + +#: ../../library/base64.rst:272 +msgid "" +"Encode the :term:`bytes-like object` *s* using Z85 (as used in ZeroMQ) and " +"return the encoded :class:`bytes`. See `Z85 specification `_ for more information." +msgstr "" +"使用 Z85（如用於 ZeroMQ）對\\ :term:`類位元組物件 ` *s* 進行編碼，並回傳" +"編碼後的 :class:`bytes`。有關更多資訊，請參閱 `Z85 規格 `_。" + +#: ../../library/base64.rst:281 +msgid "" +"Decode the Z85-encoded :term:`bytes-like object` or ASCII string *s* and " +"return the decoded :class:`bytes`. See `Z85 specification `_ for more information." +msgstr "" +"解碼經 Z85 編碼的\\ :term:`類位元組物件 `\\ 或 ASCII " +"字串 *s*，並回傳解碼後的 :class:`bytes`。有關更多資訊，請參閱 `Z85 規格 `_。" + +#: ../../library/base64.rst:291 +msgid "Legacy Interface" +msgstr "舊版介面" + +#: ../../library/base64.rst:295 +msgid "" +"Decode the contents of the binary *input* file and write the resulting " +"binary data to the *output* file. *input* and *output* must be :term:`file " +"objects `. *input* will be read until ``input.readline()`` " +"returns an empty bytes object." +msgstr "" +"解碼二進位檔案 *input* 的內容，並將結果的二進位資料寫入 *output* 檔案。 " +"*input* 和 *output* 必須是\\ :term:`檔案物件 `。*input* 將被讀" +"取，直到 ``input.readline()`` 回傳一個空的 bytes 物件為止。" + +#: ../../library/base64.rst:303 +msgid "" +"Decode the :term:`bytes-like object` *s*, which must contain one or more " +"lines of base64 encoded data, and return the decoded :class:`bytes`." +msgstr "" +"解碼必須包含一行或多行的 base64 編碼資料\\ :term:`類位元組物件 ` *s*，並回傳解碼後的 :class:`bytes`。" + +#: ../../library/base64.rst:311 +msgid "" +"Encode the contents of the binary *input* file and write the resulting " +"base64 encoded data to the *output* file. *input* and *output* must be :term:" +"`file objects `. *input* will be read until ``input.read()`` " +"returns an empty bytes object. :func:`encode` inserts a newline character " +"(``b'\\n'``) after every 76 bytes of the output, as well as ensuring that " +"the output always ends with a newline, as per :rfc:`2045` (MIME)." +msgstr "" +"編碼二進位檔案 *input* 的內容，並將結果的 base64 編碼資料寫入 *output* 檔案。" +"*input* 和 *output* 必須是\\ :term:`檔案物件 `。*input* 將被讀" +"取，直到 ``input.read()`` 回傳一個空的 bytes 物件為止。:func:`encode` 會在輸" +"出的每 76 個位元組之後插入一個換行字元 (``b'\\n'``)，並確保輸出始終以換行字元" +"結尾，符合 :rfc:`2045` (MIME) 的規定。" + +#: ../../library/base64.rst:321 +msgid "" +"Encode the :term:`bytes-like object` *s*, which can contain arbitrary binary " +"data, and return :class:`bytes` containing the base64-encoded data, with " +"newlines (``b'\\n'``) inserted after every 76 bytes of output, and ensuring " +"that there is a trailing newline, as per :rfc:`2045` (MIME)." +msgstr "" +"對包含任意二進位資料的\\ :term:`類位元組物件 ` *s* 進行編" +"碼，並回傳包含 base64 編碼資料 :class:`bytes`，在每 76 個輸出位元組後插入換行" +"字元 (``b'\\n'``) ，並確保有尾隨換行字元，符合 :rfc:`2045` (MIME) 的規定。" + +#: ../../library/base64.rst:329 +msgid "An example usage of the module:" +msgstr "模組的一個範例用法：" + +#: ../../library/base64.rst:342 +msgid "Security Considerations" +msgstr "安全性注意事項" + +#: ../../library/base64.rst:344 +msgid "" +"A new security considerations section was added to :rfc:`4648` (section 12); " +"it's recommended to review the security section for any code deployed to " +"production." +msgstr "" +":rfc:`4648`\\ （第 12 節）中添加了一個新的安全性考量部分；建議對部署到正式環" +"境的任何程式碼進行安全性部分的審查。" + +#: ../../library/base64.rst:349 +msgid "Module :mod:`binascii`" +msgstr ":mod:`binascii` 模組" + +#: ../../library/base64.rst:350 +msgid "" +"Support module containing ASCII-to-binary and binary-to-ASCII conversions." +msgstr "" +"支援模組中包含 ASCII 到二進位 (ASCII-to-binary) 和二進位到 ASCII (binary-to-" +"ASCII) 的轉換功能。" + +#: ../../library/base64.rst:352 +msgid "" +":rfc:`1521` - MIME (Multipurpose Internet Mail Extensions) Part One: " +"Mechanisms for Specifying and Describing the Format of Internet Message " +"Bodies" +msgstr "" +":rfc:`1521` - MIME（多用途網際網路郵件擴展）第一部分：指定和描述網際網路主體" +"格式的機制。" + +#: ../../library/base64.rst:353 +msgid "" +"Section 5.2, \"Base64 Content-Transfer-Encoding,\" provides the definition " +"of the base64 encoding." +msgstr "" +"第 5.2 節，\"Base64 Content-Transfer-Encoding\"，提供了 base64 編碼的定義。" + +#: ../../library/base64.rst:10 +msgid "base64" +msgstr "base64" + +#: ../../library/base64.rst:10 +msgid "encoding" +msgstr "encoding（編碼）" + +#: ../../library/base64.rst:10 +msgid "MIME" +msgstr "MIME" + +#: ../../library/base64.rst:10 +msgid "base64 encoding" +msgstr "base64 encoding（base64 編碼）" diff --git a/library/bdb.po b/library/bdb.po index 37f55c0b11..79e12dd06f 100644 --- a/library/bdb.po +++ b/library/bdb.po @@ -1,667 +1,667 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: 2018-05-23 14:39+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/bdb.rst:2 -msgid ":mod:`!bdb` --- Debugger framework" -msgstr ":mod:`!bdb` --- 偵錯器框架" - -#: ../../library/bdb.rst:7 -msgid "**Source code:** :source:`Lib/bdb.py`" -msgstr "**原始碼：**\\ :source:`Lib/bdb.py`" - -#: ../../library/bdb.rst:11 -msgid "" -"The :mod:`bdb` module handles basic debugger functions, like setting " -"breakpoints or managing execution via the debugger." -msgstr "" - -#: ../../library/bdb.rst:14 -msgid "The following exception is defined:" -msgstr "有定義以下例外：" - -#: ../../library/bdb.rst:18 -msgid "Exception raised by the :class:`Bdb` class for quitting the debugger." -msgstr "由 :class:`Bdb` 類別所引發的例外，用來退出偵錯器。" - -#: ../../library/bdb.rst:21 -msgid "The :mod:`bdb` module also defines two classes:" -msgstr ":mod:`bdb` 模組也定義了兩個類別：" - -#: ../../library/bdb.rst:25 -msgid "" -"This class implements temporary breakpoints, ignore counts, disabling and " -"(re-)enabling, and conditionals." -msgstr "" - -#: ../../library/bdb.rst:28 -msgid "" -"Breakpoints are indexed by number through a list called :attr:`bpbynumber` " -"and by ``(file, line)`` pairs through :attr:`bplist`. The former points to " -"a single instance of class :class:`Breakpoint`. The latter points to a list " -"of such instances since there may be more than one breakpoint per line." -msgstr "" - -#: ../../library/bdb.rst:33 -msgid "" -"When creating a breakpoint, its associated :attr:`file name ` should " -"be in canonical form. If a :attr:`funcname` is defined, a " -"breakpoint :attr:`hit ` will be counted when the first line of that " -"function is executed. A :attr:`conditional ` breakpoint always counts " -"a :attr:`hit `." -msgstr "" - -#: ../../library/bdb.rst:39 -msgid ":class:`Breakpoint` instances have the following methods:" -msgstr ":class:`Breakpoint` 實例有以下方法：" - -#: ../../library/bdb.rst:43 -msgid "" -"Delete the breakpoint from the list associated to a file/line. If it is the " -"last breakpoint in that position, it also deletes the entry for the file/" -"line." -msgstr "" - -#: ../../library/bdb.rst:50 -msgid "Mark the breakpoint as enabled." -msgstr "" - -#: ../../library/bdb.rst:55 -msgid "Mark the breakpoint as disabled." -msgstr "" - -#: ../../library/bdb.rst:60 -msgid "" -"Return a string with all the information about the breakpoint, nicely " -"formatted:" -msgstr "" - -#: ../../library/bdb.rst:63 -msgid "Breakpoint number." -msgstr "" - -#: ../../library/bdb.rst:64 -msgid "Temporary status (del or keep)." -msgstr "" - -#: ../../library/bdb.rst:65 -msgid "File/line position." -msgstr "" - -#: ../../library/bdb.rst:66 -msgid "Break condition." -msgstr "" - -#: ../../library/bdb.rst:67 -msgid "Number of times to ignore." -msgstr "" - -#: ../../library/bdb.rst:68 -msgid "Number of times hit." -msgstr "" - -#: ../../library/bdb.rst:74 -msgid "" -"Print the output of :meth:`bpformat` to the file *out*, or if it is " -"``None``, to standard output." -msgstr "" - -#: ../../library/bdb.rst:77 -msgid ":class:`Breakpoint` instances have the following attributes:" -msgstr ":class:`Breakpoint` 實例有以下屬性：" - -#: ../../library/bdb.rst:81 -msgid "File name of the :class:`Breakpoint`." -msgstr ":class:`Breakpoint` 的檔案名稱。" - -#: ../../library/bdb.rst:85 -msgid "Line number of the :class:`Breakpoint` within :attr:`file`." -msgstr "" - -#: ../../library/bdb.rst:89 -msgid "``True`` if a :class:`Breakpoint` at (file, line) is temporary." -msgstr "" - -#: ../../library/bdb.rst:93 -msgid "Condition for evaluating a :class:`Breakpoint` at (file, line)." -msgstr "" - -#: ../../library/bdb.rst:97 -msgid "" -"Function name that defines whether a :class:`Breakpoint` is hit upon " -"entering the function." -msgstr "" - -#: ../../library/bdb.rst:102 -msgid "``True`` if :class:`Breakpoint` is enabled." -msgstr "如 :class:`Breakpoint` 有被啟用則為 ``True``。" - -#: ../../library/bdb.rst:106 -msgid "Numeric index for a single instance of a :class:`Breakpoint`." -msgstr "" - -#: ../../library/bdb.rst:110 -msgid "" -"Dictionary of :class:`Breakpoint` instances indexed by " -"(:attr:`file`, :attr:`line`) tuples." -msgstr "" - -#: ../../library/bdb.rst:115 -msgid "Number of times to ignore a :class:`Breakpoint`." -msgstr "" - -#: ../../library/bdb.rst:119 -msgid "Count of the number of times a :class:`Breakpoint` has been hit." -msgstr "" - -#: ../../library/bdb.rst:123 -msgid "The :class:`Bdb` class acts as a generic Python debugger base class." -msgstr "" - -#: ../../library/bdb.rst:125 -msgid "" -"This class takes care of the details of the trace facility; a derived class " -"should implement user interaction. The standard debugger class " -"(:class:`pdb.Pdb`) is an example." -msgstr "" - -#: ../../library/bdb.rst:129 -msgid "" -"The *skip* argument, if given, must be an iterable of glob-style module name " -"patterns. The debugger will not step into frames that originate in a module " -"that matches one of these patterns. Whether a frame is considered to " -"originate in a certain module is determined by the ``__name__`` in the frame " -"globals." -msgstr "" - -#: ../../library/bdb.rst:135 -msgid "" -"The *backend* argument specifies the backend to use for :class:`Bdb`. It can " -"be either ``'settrace'`` or ``'monitoring'``. ``'settrace'`` " -"uses :func:`sys.settrace` which has the best backward compatibility. The " -"``'monitoring'`` backend uses the new :mod:`sys.monitoring` that was " -"introduced in Python 3.12, which can be much more efficient because it can " -"disable unused events. We are trying to keep the exact interfaces for both " -"backends, but there are some differences. The debugger developers are " -"encouraged to use the ``'monitoring'`` backend to achieve better performance." -msgstr "" - -#: ../../library/bdb.rst:145 -msgid "Added the *skip* parameter." -msgstr "新增 *skip* 引數。" - -#: ../../library/bdb.rst:148 -msgid "Added the *backend* parameter." -msgstr "新增 *backend* 參數。" - -#: ../../library/bdb.rst:151 -msgid "" -"The following methods of :class:`Bdb` normally don't need to be overridden." -msgstr "" - -#: ../../library/bdb.rst:155 -msgid "Return canonical form of *filename*." -msgstr "" - -#: ../../library/bdb.rst:157 -msgid "" -"For real file names, the canonical form is an operating-system-" -"dependent, :func:`case-normalized ` :func:`absolute path " -"`. A *filename* with angle brackets, such as " -"``\"\"`` generated in interactive mode, is returned unchanged." -msgstr "" - -#: ../../library/bdb.rst:164 -msgid "" -"Start tracing. For ``'settrace'`` backend, this method is equivalent to " -"``sys.settrace(self.trace_dispatch)``" -msgstr "" - -#: ../../library/bdb.rst:171 -msgid "" -"Stop tracing. For ``'settrace'`` backend, this method is equivalent to " -"``sys.settrace(None)``" -msgstr "" - -#: ../../library/bdb.rst:178 -msgid "" -"Set the :attr:`!botframe`, :attr:`!stopframe`, :attr:`!returnframe` " -"and :attr:`quitting ` attributes with values ready to start " -"debugging." -msgstr "" - -#: ../../library/bdb.rst:183 -msgid "" -"This function is installed as the trace function of debugged frames. Its " -"return value is the new trace function (in most cases, that is, itself)." -msgstr "" - -#: ../../library/bdb.rst:186 -msgid "" -"The default implementation decides how to dispatch a frame, depending on the " -"type of event (passed as a string) that is about to be executed. *event* can " -"be one of the following:" -msgstr "" - -#: ../../library/bdb.rst:190 -msgid "``\"line\"``: A new line of code is going to be executed." -msgstr "" - -#: ../../library/bdb.rst:191 -msgid "" -"``\"call\"``: A function is about to be called, or another code block " -"entered." -msgstr "" - -#: ../../library/bdb.rst:193 -msgid "``\"return\"``: A function or other code block is about to return." -msgstr "" - -#: ../../library/bdb.rst:194 -msgid "``\"exception\"``: An exception has occurred." -msgstr "" - -#: ../../library/bdb.rst:195 -msgid "``\"c_call\"``: A C function is about to be called." -msgstr "" - -#: ../../library/bdb.rst:196 -msgid "``\"c_return\"``: A C function has returned." -msgstr "" - -#: ../../library/bdb.rst:197 -msgid "``\"c_exception\"``: A C function has raised an exception." -msgstr "" - -#: ../../library/bdb.rst:199 -msgid "" -"For the Python events, specialized functions (see below) are called. For " -"the C events, no action is taken." -msgstr "" - -#: ../../library/bdb.rst:202 -msgid "The *arg* parameter depends on the previous event." -msgstr "" - -#: ../../library/bdb.rst:204 -msgid "" -"See the documentation for :func:`sys.settrace` for more information on the " -"trace function. For more information on code and frame objects, refer " -"to :ref:`types`." -msgstr "" - -#: ../../library/bdb.rst:210 -msgid "" -"If the debugger should stop on the current line, invoke " -"the :meth:`user_line` method (which should be overridden in subclasses). " -"Raise a :exc:`BdbQuit` exception if the :attr:`quitting ` " -"flag is set (which can be set from :meth:`user_line`). Return a reference " -"to the :meth:`trace_dispatch` method for further tracing in that scope." -msgstr "" - -#: ../../library/bdb.rst:218 -msgid "" -"If the debugger should stop on this function call, invoke " -"the :meth:`user_call` method (which should be overridden in subclasses). " -"Raise a :exc:`BdbQuit` exception if the :attr:`quitting ` " -"flag is set (which can be set from :meth:`user_call`). Return a reference " -"to the :meth:`trace_dispatch` method for further tracing in that scope." -msgstr "" - -#: ../../library/bdb.rst:226 -msgid "" -"If the debugger should stop on this function return, invoke " -"the :meth:`user_return` method (which should be overridden in subclasses). " -"Raise a :exc:`BdbQuit` exception if the :attr:`quitting ` " -"flag is set (which can be set from :meth:`user_return`). Return a reference " -"to the :meth:`trace_dispatch` method for further tracing in that scope." -msgstr "" - -#: ../../library/bdb.rst:234 -msgid "" -"If the debugger should stop at this exception, invokes " -"the :meth:`user_exception` method (which should be overridden in " -"subclasses). Raise a :exc:`BdbQuit` exception if the :attr:`quitting " -"` flag is set (which can be set from :meth:`user_exception`). " -"Return a reference to the :meth:`trace_dispatch` method for further tracing " -"in that scope." -msgstr "" - -#: ../../library/bdb.rst:240 -msgid "" -"Normally derived classes don't override the following methods, but they may " -"if they want to redefine the definition of stopping and breakpoints." -msgstr "" - -#: ../../library/bdb.rst:245 -msgid "Return ``True`` if *module_name* matches any skip pattern." -msgstr "" - -#: ../../library/bdb.rst:249 -msgid "Return ``True`` if *frame* is below the starting frame in the stack." -msgstr "" - -#: ../../library/bdb.rst:253 -msgid "Return ``True`` if there is an effective breakpoint for this line." -msgstr "" - -#: ../../library/bdb.rst:255 -msgid "" -"Check whether a line or function breakpoint exists and is in effect. Delete " -"temporary breakpoints based on information from :func:`effective`." -msgstr "" - -#: ../../library/bdb.rst:260 -msgid "Return ``True`` if any breakpoint exists for *frame*'s filename." -msgstr "" - -#: ../../library/bdb.rst:262 -msgid "" -"Derived classes should override these methods to gain control over debugger " -"operation." -msgstr "" - -#: ../../library/bdb.rst:267 -msgid "" -"Called from :meth:`dispatch_call` if a break might stop inside the called " -"function." -msgstr "" - -#: ../../library/bdb.rst:270 -msgid "" -"*argument_list* is not used anymore and will always be ``None``. The " -"argument is kept for backwards compatibility." -msgstr "" - -#: ../../library/bdb.rst:275 -msgid "" -"Called from :meth:`dispatch_line` when either :meth:`stop_here` " -"or :meth:`break_here` returns ``True``." -msgstr "" - -#: ../../library/bdb.rst:280 -msgid "" -"Called from :meth:`dispatch_return` when :meth:`stop_here` returns ``True``." -msgstr "" - -#: ../../library/bdb.rst:284 -msgid "" -"Called from :meth:`dispatch_exception` when :meth:`stop_here` returns " -"``True``." -msgstr "" - -#: ../../library/bdb.rst:289 -msgid "Handle how a breakpoint must be removed when it is a temporary one." -msgstr "" - -#: ../../library/bdb.rst:291 -msgid "This method must be implemented by derived classes." -msgstr "" - -#: ../../library/bdb.rst:294 -msgid "" -"Derived classes and clients can call the following methods to affect the " -"stepping state." -msgstr "" - -#: ../../library/bdb.rst:299 -msgid "Stop after one line of code." -msgstr "" - -#: ../../library/bdb.rst:303 -msgid "Stop on the next line in or below the given frame." -msgstr "" - -#: ../../library/bdb.rst:307 -msgid "Stop when returning from the given frame." -msgstr "" - -#: ../../library/bdb.rst:311 -msgid "" -"Stop when the line with the *lineno* greater than the current one is reached " -"or when returning from current frame." -msgstr "" - -#: ../../library/bdb.rst:316 -msgid "" -"Start debugging from *frame*. If *frame* is not specified, debugging starts " -"from caller's frame." -msgstr "" - -#: ../../library/bdb.rst:319 -msgid "" -":func:`set_trace` will enter the debugger immediately, rather than on the " -"next line of code to be executed." -msgstr "" - -#: ../../library/bdb.rst:325 -msgid "" -"Stop only at breakpoints or when finished. If there are no breakpoints, set " -"the system trace function to ``None``." -msgstr "" - -#: ../../library/bdb.rst:332 -msgid "" -"Set the :attr:`!quitting` attribute to ``True``. This raises :exc:`BdbQuit` " -"in the next call to one of the :meth:`!dispatch_\\*` methods." -msgstr "" - -#: ../../library/bdb.rst:336 -msgid "" -"Derived classes and clients can call the following methods to manipulate " -"breakpoints. These methods return a string containing an error message if " -"something went wrong, or ``None`` if all is well." -msgstr "" - -#: ../../library/bdb.rst:342 -msgid "" -"Set a new breakpoint. If the *lineno* line doesn't exist for the *filename* " -"passed as argument, return an error message. The *filename* should be in " -"canonical form, as described in the :meth:`canonic` method." -msgstr "" - -#: ../../library/bdb.rst:348 -msgid "" -"Delete the breakpoints in *filename* and *lineno*. If none were set, return " -"an error message." -msgstr "" - -#: ../../library/bdb.rst:353 -msgid "" -"Delete the breakpoint which has the index *arg* in " -"the :attr:`Breakpoint.bpbynumber`. If *arg* is not numeric or out of range, " -"return an error message." -msgstr "" - -#: ../../library/bdb.rst:359 -msgid "" -"Delete all breakpoints in *filename*. If none were set, return an error " -"message." -msgstr "" - -#: ../../library/bdb.rst:364 -msgid "" -"Delete all existing breakpoints. If none were set, return an error message." -msgstr "" - -#: ../../library/bdb.rst:369 -msgid "" -"Return a breakpoint specified by the given number. If *arg* is a string, it " -"will be converted to a number. If *arg* is a non-numeric string, if the " -"given breakpoint never existed or has been deleted, a :exc:`ValueError` is " -"raised." -msgstr "" - -#: ../../library/bdb.rst:378 -msgid "Return ``True`` if there is a breakpoint for *lineno* in *filename*." -msgstr "" - -#: ../../library/bdb.rst:382 -msgid "" -"Return all breakpoints for *lineno* in *filename*, or an empty list if none " -"are set." -msgstr "" - -#: ../../library/bdb.rst:387 -msgid "Return all breakpoints in *filename*, or an empty list if none are set." -msgstr "" - -#: ../../library/bdb.rst:391 -msgid "Return all breakpoints that are set." -msgstr "" - -#: ../../library/bdb.rst:394 -msgid "" -"Derived classes and clients can call the following methods to disable and " -"restart events to achieve better performance. These methods only work when " -"using the ``'monitoring'`` backend." -msgstr "" - -#: ../../library/bdb.rst:400 -msgid "" -"Disable the current event until the next time :func:`restart_events` is " -"called. This is helpful when the debugger is not interested in the current " -"line." -msgstr "" - -#: ../../library/bdb.rst:408 -msgid "" -"Restart all the disabled events. This function is automatically called in " -"``dispatch_*`` methods after ``user_*`` methods are called. If the " -"``dispatch_*`` methods are not overridden, the disabled events will be " -"restarted after each user interaction." -msgstr "" - -#: ../../library/bdb.rst:416 -msgid "" -"Derived classes and clients can call the following methods to get a data " -"structure representing a stack trace." -msgstr "" - -#: ../../library/bdb.rst:421 -msgid "Return a list of (frame, lineno) tuples in a stack trace, and a size." -msgstr "" - -#: ../../library/bdb.rst:423 -msgid "" -"The most recently called frame is last in the list. The size is the number " -"of frames below the frame where the debugger was invoked." -msgstr "" - -#: ../../library/bdb.rst:428 -msgid "" -"Return a string with information about a stack entry, which is a ``(frame, " -"lineno)`` tuple. The return string contains:" -msgstr "" - -#: ../../library/bdb.rst:431 -msgid "The canonical filename which contains the frame." -msgstr "" - -#: ../../library/bdb.rst:432 -msgid "The function name or ``\"\"``." -msgstr "函式名稱或 ``\"\"``。" - -#: ../../library/bdb.rst:433 -msgid "The input arguments." -msgstr "輸入引數。" - -#: ../../library/bdb.rst:434 -msgid "The return value." -msgstr "回傳值。" - -#: ../../library/bdb.rst:435 -msgid "The line of code (if it exists)." -msgstr "" - -#: ../../library/bdb.rst:438 -msgid "" -"The following two methods can be called by clients to use a debugger to " -"debug a :term:`statement`, given as a string." -msgstr "" - -#: ../../library/bdb.rst:443 -msgid "" -"Debug a statement executed via the :func:`exec` function. *globals* " -"defaults to :attr:`!__main__.__dict__`, *locals* defaults to *globals*." -msgstr "" - -#: ../../library/bdb.rst:448 -msgid "" -"Debug an expression executed via the :func:`eval` function. *globals* and " -"*locals* have the same meaning as in :meth:`run`." -msgstr "" - -#: ../../library/bdb.rst:453 -msgid "For backwards compatibility. Calls the :meth:`run` method." -msgstr "" - -#: ../../library/bdb.rst:457 -msgid "Debug a single function call, and return its result." -msgstr "" - -#: ../../library/bdb.rst:460 -msgid "Finally, the module defines the following functions:" -msgstr "最後，這個模組定義了以下函式：" - -#: ../../library/bdb.rst:464 -msgid "" -"Return ``True`` if we should break here, depending on the way " -"the :class:`Breakpoint` *b* was set." -msgstr "" - -#: ../../library/bdb.rst:467 -msgid "" -"If it was set via line number, it checks if :attr:`b.line " -"` is the same as the one in *frame*. If the breakpoint " -"was set via :attr:`function name `, we have to " -"check we are in the right *frame* (the right function) and if we are on its " -"first executable line." -msgstr "" - -#: ../../library/bdb.rst:476 -msgid "" -"Return ``(active breakpoint, delete temporary flag)`` or ``(None, None)`` as " -"the breakpoint to act upon." -msgstr "" - -#: ../../library/bdb.rst:479 -msgid "" -"The *active breakpoint* is the first entry in :attr:`bplist " -"` for the (:attr:`file " -"`, :attr:`line `) (which must " -"exist) that is :attr:`enabled `, for " -"which :func:`checkfuncname` is true, and that has neither a " -"false :attr:`condition ` nor positive :attr:`ignore " -"` count. The *flag*, meaning that a temporary " -"breakpoint should be deleted, is ``False`` only when the :attr:`cond " -"` cannot be evaluated (in which case, :attr:`ignore " -"` count is ignored)." -msgstr "" - -#: ../../library/bdb.rst:490 -msgid "If no such entry exists, then ``(None, None)`` is returned." -msgstr "" - -#: ../../library/bdb.rst:495 -msgid "Start debugging with a :class:`Bdb` instance from caller's frame." -msgstr "" - -#: ../../library/bdb.rst:330 -msgid "quitting (bdb.Bdb attribute)" -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: 2018-05-23 14:39+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/bdb.rst:2 +msgid ":mod:`!bdb` --- Debugger framework" +msgstr ":mod:`!bdb` --- 偵錯器框架" + +#: ../../library/bdb.rst:7 +msgid "**Source code:** :source:`Lib/bdb.py`" +msgstr "**原始碼：**\\ :source:`Lib/bdb.py`" + +#: ../../library/bdb.rst:11 +msgid "" +"The :mod:`bdb` module handles basic debugger functions, like setting " +"breakpoints or managing execution via the debugger." +msgstr "" + +#: ../../library/bdb.rst:14 +msgid "The following exception is defined:" +msgstr "有定義以下例外：" + +#: ../../library/bdb.rst:18 +msgid "Exception raised by the :class:`Bdb` class for quitting the debugger." +msgstr "由 :class:`Bdb` 類別所引發的例外，用來退出偵錯器。" + +#: ../../library/bdb.rst:21 +msgid "The :mod:`bdb` module also defines two classes:" +msgstr ":mod:`bdb` 模組也定義了兩個類別：" + +#: ../../library/bdb.rst:25 +msgid "" +"This class implements temporary breakpoints, ignore counts, disabling and " +"(re-)enabling, and conditionals." +msgstr "" + +#: ../../library/bdb.rst:28 +msgid "" +"Breakpoints are indexed by number through a list called :attr:`bpbynumber` " +"and by ``(file, line)`` pairs through :attr:`bplist`. The former points to " +"a single instance of class :class:`Breakpoint`. The latter points to a list " +"of such instances since there may be more than one breakpoint per line." +msgstr "" + +#: ../../library/bdb.rst:33 +msgid "" +"When creating a breakpoint, its associated :attr:`file name ` should " +"be in canonical form. If a :attr:`funcname` is defined, a " +"breakpoint :attr:`hit ` will be counted when the first line of that " +"function is executed. A :attr:`conditional ` breakpoint always counts " +"a :attr:`hit `." +msgstr "" + +#: ../../library/bdb.rst:39 +msgid ":class:`Breakpoint` instances have the following methods:" +msgstr ":class:`Breakpoint` 實例有以下方法：" + +#: ../../library/bdb.rst:43 +msgid "" +"Delete the breakpoint from the list associated to a file/line. If it is the " +"last breakpoint in that position, it also deletes the entry for the file/" +"line." +msgstr "" + +#: ../../library/bdb.rst:50 +msgid "Mark the breakpoint as enabled." +msgstr "" + +#: ../../library/bdb.rst:55 +msgid "Mark the breakpoint as disabled." +msgstr "" + +#: ../../library/bdb.rst:60 +msgid "" +"Return a string with all the information about the breakpoint, nicely " +"formatted:" +msgstr "" + +#: ../../library/bdb.rst:63 +msgid "Breakpoint number." +msgstr "" + +#: ../../library/bdb.rst:64 +msgid "Temporary status (del or keep)." +msgstr "" + +#: ../../library/bdb.rst:65 +msgid "File/line position." +msgstr "" + +#: ../../library/bdb.rst:66 +msgid "Break condition." +msgstr "" + +#: ../../library/bdb.rst:67 +msgid "Number of times to ignore." +msgstr "" + +#: ../../library/bdb.rst:68 +msgid "Number of times hit." +msgstr "" + +#: ../../library/bdb.rst:74 +msgid "" +"Print the output of :meth:`bpformat` to the file *out*, or if it is " +"``None``, to standard output." +msgstr "" + +#: ../../library/bdb.rst:77 +msgid ":class:`Breakpoint` instances have the following attributes:" +msgstr ":class:`Breakpoint` 實例有以下屬性：" + +#: ../../library/bdb.rst:81 +msgid "File name of the :class:`Breakpoint`." +msgstr ":class:`Breakpoint` 的檔案名稱。" + +#: ../../library/bdb.rst:85 +msgid "Line number of the :class:`Breakpoint` within :attr:`file`." +msgstr "" + +#: ../../library/bdb.rst:89 +msgid "``True`` if a :class:`Breakpoint` at (file, line) is temporary." +msgstr "" + +#: ../../library/bdb.rst:93 +msgid "Condition for evaluating a :class:`Breakpoint` at (file, line)." +msgstr "" + +#: ../../library/bdb.rst:97 +msgid "" +"Function name that defines whether a :class:`Breakpoint` is hit upon " +"entering the function." +msgstr "" + +#: ../../library/bdb.rst:102 +msgid "``True`` if :class:`Breakpoint` is enabled." +msgstr "如 :class:`Breakpoint` 有被啟用則為 ``True``。" + +#: ../../library/bdb.rst:106 +msgid "Numeric index for a single instance of a :class:`Breakpoint`." +msgstr "" + +#: ../../library/bdb.rst:110 +msgid "" +"Dictionary of :class:`Breakpoint` instances indexed by " +"(:attr:`file`, :attr:`line`) tuples." +msgstr "" + +#: ../../library/bdb.rst:115 +msgid "Number of times to ignore a :class:`Breakpoint`." +msgstr "" + +#: ../../library/bdb.rst:119 +msgid "Count of the number of times a :class:`Breakpoint` has been hit." +msgstr "" + +#: ../../library/bdb.rst:123 +msgid "The :class:`Bdb` class acts as a generic Python debugger base class." +msgstr "" + +#: ../../library/bdb.rst:125 +msgid "" +"This class takes care of the details of the trace facility; a derived class " +"should implement user interaction. The standard debugger class " +"(:class:`pdb.Pdb`) is an example." +msgstr "" + +#: ../../library/bdb.rst:129 +msgid "" +"The *skip* argument, if given, must be an iterable of glob-style module name " +"patterns. The debugger will not step into frames that originate in a module " +"that matches one of these patterns. Whether a frame is considered to " +"originate in a certain module is determined by the ``__name__`` in the frame " +"globals." +msgstr "" + +#: ../../library/bdb.rst:135 +msgid "" +"The *backend* argument specifies the backend to use for :class:`Bdb`. It can " +"be either ``'settrace'`` or ``'monitoring'``. ``'settrace'`` " +"uses :func:`sys.settrace` which has the best backward compatibility. The " +"``'monitoring'`` backend uses the new :mod:`sys.monitoring` that was " +"introduced in Python 3.12, which can be much more efficient because it can " +"disable unused events. We are trying to keep the exact interfaces for both " +"backends, but there are some differences. The debugger developers are " +"encouraged to use the ``'monitoring'`` backend to achieve better performance." +msgstr "" + +#: ../../library/bdb.rst:145 +msgid "Added the *skip* parameter." +msgstr "新增 *skip* 引數。" + +#: ../../library/bdb.rst:148 +msgid "Added the *backend* parameter." +msgstr "新增 *backend* 參數。" + +#: ../../library/bdb.rst:151 +msgid "" +"The following methods of :class:`Bdb` normally don't need to be overridden." +msgstr "" + +#: ../../library/bdb.rst:155 +msgid "Return canonical form of *filename*." +msgstr "" + +#: ../../library/bdb.rst:157 +msgid "" +"For real file names, the canonical form is an operating-system-" +"dependent, :func:`case-normalized ` :func:`absolute path " +"`. A *filename* with angle brackets, such as " +"``\"\"`` generated in interactive mode, is returned unchanged." +msgstr "" + +#: ../../library/bdb.rst:164 +msgid "" +"Start tracing. For ``'settrace'`` backend, this method is equivalent to " +"``sys.settrace(self.trace_dispatch)``" +msgstr "" + +#: ../../library/bdb.rst:171 +msgid "" +"Stop tracing. For ``'settrace'`` backend, this method is equivalent to " +"``sys.settrace(None)``" +msgstr "" + +#: ../../library/bdb.rst:178 +msgid "" +"Set the :attr:`!botframe`, :attr:`!stopframe`, :attr:`!returnframe` " +"and :attr:`quitting ` attributes with values ready to start " +"debugging." +msgstr "" + +#: ../../library/bdb.rst:183 +msgid "" +"This function is installed as the trace function of debugged frames. Its " +"return value is the new trace function (in most cases, that is, itself)." +msgstr "" + +#: ../../library/bdb.rst:186 +msgid "" +"The default implementation decides how to dispatch a frame, depending on the " +"type of event (passed as a string) that is about to be executed. *event* can " +"be one of the following:" +msgstr "" + +#: ../../library/bdb.rst:190 +msgid "``\"line\"``: A new line of code is going to be executed." +msgstr "" + +#: ../../library/bdb.rst:191 +msgid "" +"``\"call\"``: A function is about to be called, or another code block " +"entered." +msgstr "" + +#: ../../library/bdb.rst:193 +msgid "``\"return\"``: A function or other code block is about to return." +msgstr "" + +#: ../../library/bdb.rst:194 +msgid "``\"exception\"``: An exception has occurred." +msgstr "" + +#: ../../library/bdb.rst:195 +msgid "``\"c_call\"``: A C function is about to be called." +msgstr "" + +#: ../../library/bdb.rst:196 +msgid "``\"c_return\"``: A C function has returned." +msgstr "" + +#: ../../library/bdb.rst:197 +msgid "``\"c_exception\"``: A C function has raised an exception." +msgstr "" + +#: ../../library/bdb.rst:199 +msgid "" +"For the Python events, specialized functions (see below) are called. For " +"the C events, no action is taken." +msgstr "" + +#: ../../library/bdb.rst:202 +msgid "The *arg* parameter depends on the previous event." +msgstr "" + +#: ../../library/bdb.rst:204 +msgid "" +"See the documentation for :func:`sys.settrace` for more information on the " +"trace function. For more information on code and frame objects, refer " +"to :ref:`types`." +msgstr "" + +#: ../../library/bdb.rst:210 +msgid "" +"If the debugger should stop on the current line, invoke " +"the :meth:`user_line` method (which should be overridden in subclasses). " +"Raise a :exc:`BdbQuit` exception if the :attr:`quitting ` " +"flag is set (which can be set from :meth:`user_line`). Return a reference " +"to the :meth:`trace_dispatch` method for further tracing in that scope." +msgstr "" + +#: ../../library/bdb.rst:218 +msgid "" +"If the debugger should stop on this function call, invoke " +"the :meth:`user_call` method (which should be overridden in subclasses). " +"Raise a :exc:`BdbQuit` exception if the :attr:`quitting ` " +"flag is set (which can be set from :meth:`user_call`). Return a reference " +"to the :meth:`trace_dispatch` method for further tracing in that scope." +msgstr "" + +#: ../../library/bdb.rst:226 +msgid "" +"If the debugger should stop on this function return, invoke " +"the :meth:`user_return` method (which should be overridden in subclasses). " +"Raise a :exc:`BdbQuit` exception if the :attr:`quitting ` " +"flag is set (which can be set from :meth:`user_return`). Return a reference " +"to the :meth:`trace_dispatch` method for further tracing in that scope." +msgstr "" + +#: ../../library/bdb.rst:234 +msgid "" +"If the debugger should stop at this exception, invokes " +"the :meth:`user_exception` method (which should be overridden in " +"subclasses). Raise a :exc:`BdbQuit` exception if the :attr:`quitting " +"` flag is set (which can be set from :meth:`user_exception`). " +"Return a reference to the :meth:`trace_dispatch` method for further tracing " +"in that scope." +msgstr "" + +#: ../../library/bdb.rst:240 +msgid "" +"Normally derived classes don't override the following methods, but they may " +"if they want to redefine the definition of stopping and breakpoints." +msgstr "" + +#: ../../library/bdb.rst:245 +msgid "Return ``True`` if *module_name* matches any skip pattern." +msgstr "" + +#: ../../library/bdb.rst:249 +msgid "Return ``True`` if *frame* is below the starting frame in the stack." +msgstr "" + +#: ../../library/bdb.rst:253 +msgid "Return ``True`` if there is an effective breakpoint for this line." +msgstr "" + +#: ../../library/bdb.rst:255 +msgid "" +"Check whether a line or function breakpoint exists and is in effect. Delete " +"temporary breakpoints based on information from :func:`effective`." +msgstr "" + +#: ../../library/bdb.rst:260 +msgid "Return ``True`` if any breakpoint exists for *frame*'s filename." +msgstr "" + +#: ../../library/bdb.rst:262 +msgid "" +"Derived classes should override these methods to gain control over debugger " +"operation." +msgstr "" + +#: ../../library/bdb.rst:267 +msgid "" +"Called from :meth:`dispatch_call` if a break might stop inside the called " +"function." +msgstr "" + +#: ../../library/bdb.rst:270 +msgid "" +"*argument_list* is not used anymore and will always be ``None``. The " +"argument is kept for backwards compatibility." +msgstr "" + +#: ../../library/bdb.rst:275 +msgid "" +"Called from :meth:`dispatch_line` when either :meth:`stop_here` " +"or :meth:`break_here` returns ``True``." +msgstr "" + +#: ../../library/bdb.rst:280 +msgid "" +"Called from :meth:`dispatch_return` when :meth:`stop_here` returns ``True``." +msgstr "" + +#: ../../library/bdb.rst:284 +msgid "" +"Called from :meth:`dispatch_exception` when :meth:`stop_here` returns " +"``True``." +msgstr "" + +#: ../../library/bdb.rst:289 +msgid "Handle how a breakpoint must be removed when it is a temporary one." +msgstr "" + +#: ../../library/bdb.rst:291 +msgid "This method must be implemented by derived classes." +msgstr "" + +#: ../../library/bdb.rst:294 +msgid "" +"Derived classes and clients can call the following methods to affect the " +"stepping state." +msgstr "" + +#: ../../library/bdb.rst:299 +msgid "Stop after one line of code." +msgstr "" + +#: ../../library/bdb.rst:303 +msgid "Stop on the next line in or below the given frame." +msgstr "" + +#: ../../library/bdb.rst:307 +msgid "Stop when returning from the given frame." +msgstr "" + +#: ../../library/bdb.rst:311 +msgid "" +"Stop when the line with the *lineno* greater than the current one is reached " +"or when returning from current frame." +msgstr "" + +#: ../../library/bdb.rst:316 +msgid "" +"Start debugging from *frame*. If *frame* is not specified, debugging starts " +"from caller's frame." +msgstr "" + +#: ../../library/bdb.rst:319 +msgid "" +":func:`set_trace` will enter the debugger immediately, rather than on the " +"next line of code to be executed." +msgstr "" + +#: ../../library/bdb.rst:325 +msgid "" +"Stop only at breakpoints or when finished. If there are no breakpoints, set " +"the system trace function to ``None``." +msgstr "" + +#: ../../library/bdb.rst:332 +msgid "" +"Set the :attr:`!quitting` attribute to ``True``. This raises :exc:`BdbQuit` " +"in the next call to one of the :meth:`!dispatch_\\*` methods." +msgstr "" + +#: ../../library/bdb.rst:336 +msgid "" +"Derived classes and clients can call the following methods to manipulate " +"breakpoints. These methods return a string containing an error message if " +"something went wrong, or ``None`` if all is well." +msgstr "" + +#: ../../library/bdb.rst:342 +msgid "" +"Set a new breakpoint. If the *lineno* line doesn't exist for the *filename* " +"passed as argument, return an error message. The *filename* should be in " +"canonical form, as described in the :meth:`canonic` method." +msgstr "" + +#: ../../library/bdb.rst:348 +msgid "" +"Delete the breakpoints in *filename* and *lineno*. If none were set, return " +"an error message." +msgstr "" + +#: ../../library/bdb.rst:353 +msgid "" +"Delete the breakpoint which has the index *arg* in " +"the :attr:`Breakpoint.bpbynumber`. If *arg* is not numeric or out of range, " +"return an error message." +msgstr "" + +#: ../../library/bdb.rst:359 +msgid "" +"Delete all breakpoints in *filename*. If none were set, return an error " +"message." +msgstr "" + +#: ../../library/bdb.rst:364 +msgid "" +"Delete all existing breakpoints. If none were set, return an error message." +msgstr "" + +#: ../../library/bdb.rst:369 +msgid "" +"Return a breakpoint specified by the given number. If *arg* is a string, it " +"will be converted to a number. If *arg* is a non-numeric string, if the " +"given breakpoint never existed or has been deleted, a :exc:`ValueError` is " +"raised." +msgstr "" + +#: ../../library/bdb.rst:378 +msgid "Return ``True`` if there is a breakpoint for *lineno* in *filename*." +msgstr "" + +#: ../../library/bdb.rst:382 +msgid "" +"Return all breakpoints for *lineno* in *filename*, or an empty list if none " +"are set." +msgstr "" + +#: ../../library/bdb.rst:387 +msgid "Return all breakpoints in *filename*, or an empty list if none are set." +msgstr "" + +#: ../../library/bdb.rst:391 +msgid "Return all breakpoints that are set." +msgstr "" + +#: ../../library/bdb.rst:394 +msgid "" +"Derived classes and clients can call the following methods to disable and " +"restart events to achieve better performance. These methods only work when " +"using the ``'monitoring'`` backend." +msgstr "" + +#: ../../library/bdb.rst:400 +msgid "" +"Disable the current event until the next time :func:`restart_events` is " +"called. This is helpful when the debugger is not interested in the current " +"line." +msgstr "" + +#: ../../library/bdb.rst:408 +msgid "" +"Restart all the disabled events. This function is automatically called in " +"``dispatch_*`` methods after ``user_*`` methods are called. If the " +"``dispatch_*`` methods are not overridden, the disabled events will be " +"restarted after each user interaction." +msgstr "" + +#: ../../library/bdb.rst:416 +msgid "" +"Derived classes and clients can call the following methods to get a data " +"structure representing a stack trace." +msgstr "" + +#: ../../library/bdb.rst:421 +msgid "Return a list of (frame, lineno) tuples in a stack trace, and a size." +msgstr "" + +#: ../../library/bdb.rst:423 +msgid "" +"The most recently called frame is last in the list. The size is the number " +"of frames below the frame where the debugger was invoked." +msgstr "" + +#: ../../library/bdb.rst:428 +msgid "" +"Return a string with information about a stack entry, which is a ``(frame, " +"lineno)`` tuple. The return string contains:" +msgstr "" + +#: ../../library/bdb.rst:431 +msgid "The canonical filename which contains the frame." +msgstr "" + +#: ../../library/bdb.rst:432 +msgid "The function name or ``\"\"``." +msgstr "函式名稱或 ``\"\"``。" + +#: ../../library/bdb.rst:433 +msgid "The input arguments." +msgstr "輸入引數。" + +#: ../../library/bdb.rst:434 +msgid "The return value." +msgstr "回傳值。" + +#: ../../library/bdb.rst:435 +msgid "The line of code (if it exists)." +msgstr "" + +#: ../../library/bdb.rst:438 +msgid "" +"The following two methods can be called by clients to use a debugger to " +"debug a :term:`statement`, given as a string." +msgstr "" + +#: ../../library/bdb.rst:443 +msgid "" +"Debug a statement executed via the :func:`exec` function. *globals* " +"defaults to :attr:`!__main__.__dict__`, *locals* defaults to *globals*." +msgstr "" + +#: ../../library/bdb.rst:448 +msgid "" +"Debug an expression executed via the :func:`eval` function. *globals* and " +"*locals* have the same meaning as in :meth:`run`." +msgstr "" + +#: ../../library/bdb.rst:453 +msgid "For backwards compatibility. Calls the :meth:`run` method." +msgstr "" + +#: ../../library/bdb.rst:457 +msgid "Debug a single function call, and return its result." +msgstr "" + +#: ../../library/bdb.rst:460 +msgid "Finally, the module defines the following functions:" +msgstr "最後，這個模組定義了以下函式：" + +#: ../../library/bdb.rst:464 +msgid "" +"Return ``True`` if we should break here, depending on the way " +"the :class:`Breakpoint` *b* was set." +msgstr "" + +#: ../../library/bdb.rst:467 +msgid "" +"If it was set via line number, it checks if :attr:`b.line " +"` is the same as the one in *frame*. If the breakpoint " +"was set via :attr:`function name `, we have to " +"check we are in the right *frame* (the right function) and if we are on its " +"first executable line." +msgstr "" + +#: ../../library/bdb.rst:476 +msgid "" +"Return ``(active breakpoint, delete temporary flag)`` or ``(None, None)`` as " +"the breakpoint to act upon." +msgstr "" + +#: ../../library/bdb.rst:479 +msgid "" +"The *active breakpoint* is the first entry in :attr:`bplist " +"` for the (:attr:`file " +"`, :attr:`line `) (which must " +"exist) that is :attr:`enabled `, for " +"which :func:`checkfuncname` is true, and that has neither a " +"false :attr:`condition ` nor positive :attr:`ignore " +"` count. The *flag*, meaning that a temporary " +"breakpoint should be deleted, is ``False`` only when the :attr:`cond " +"` cannot be evaluated (in which case, :attr:`ignore " +"` count is ignored)." +msgstr "" + +#: ../../library/bdb.rst:490 +msgid "If no such entry exists, then ``(None, None)`` is returned." +msgstr "" + +#: ../../library/bdb.rst:495 +msgid "Start debugging with a :class:`Bdb` instance from caller's frame." +msgstr "" + +#: ../../library/bdb.rst:330 +msgid "quitting (bdb.Bdb attribute)" +msgstr "" diff --git a/library/binary.po b/library/binary.po index 2b91220f39..f1f91b9299 100644 --- a/library/binary.po +++ b/library/binary.po @@ -1,48 +1,48 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2018-06-26 18:54+0800\n" -"PO-Revision-Date: 2015-12-09 17:51+0000\n" -"Last-Translator: Liang-Bo Wang \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/binary.rst:5 -msgid "Binary Data Services" -msgstr "二進位資料服務" - -#: ../../library/binary.rst:7 -msgid "" -"The modules described in this chapter provide some basic services operations " -"for manipulation of binary data. Other operations on binary data, " -"specifically in relation to file formats and network protocols, are " -"described in the relevant sections." -msgstr "" -"本章所描述的模組提供了一些基本的二進位資料操作服務。而針對二進位資料的其他操" -"作──尤其是關於檔案格式和網路協定的部分──則會在相關章節中詳細描述。" - -#: ../../library/binary.rst:12 -msgid "" -"Some libraries described under :ref:`textservices` also work with either " -"ASCII-compatible binary formats (for example, :mod:`re`) or all binary data " -"(for example, :mod:`difflib`)." -msgstr "" -"一些在 :ref:`textservices` 中提及的函式庫也可處理 ASCII 相容的二進位格式（例" -"如，:mod:`re`）及所有的二進位資料（例如，:mod:`difflib`）。" - -#: ../../library/binary.rst:16 -msgid "" -"In addition, see the documentation for Python's built-in binary data types " -"in :ref:`binaryseq`." -msgstr "" -"此外，請參閱 Python 內建的二進位資料類型的文件，詳情請參考 :ref:`binaryseq`。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2018-06-26 18:54+0800\n" +"PO-Revision-Date: 2015-12-09 17:51+0000\n" +"Last-Translator: Liang-Bo Wang \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/binary.rst:5 +msgid "Binary Data Services" +msgstr "二進位資料服務" + +#: ../../library/binary.rst:7 +msgid "" +"The modules described in this chapter provide some basic services operations " +"for manipulation of binary data. Other operations on binary data, " +"specifically in relation to file formats and network protocols, are " +"described in the relevant sections." +msgstr "" +"本章所描述的模組提供了一些基本的二進位資料操作服務。而針對二進位資料的其他操" +"作──尤其是關於檔案格式和網路協定的部分──則會在相關章節中詳細描述。" + +#: ../../library/binary.rst:12 +msgid "" +"Some libraries described under :ref:`textservices` also work with either " +"ASCII-compatible binary formats (for example, :mod:`re`) or all binary data " +"(for example, :mod:`difflib`)." +msgstr "" +"一些在 :ref:`textservices` 中提及的函式庫也可處理 ASCII 相容的二進位格式（例" +"如，:mod:`re`）及所有的二進位資料（例如，:mod:`difflib`）。" + +#: ../../library/binary.rst:16 +msgid "" +"In addition, see the documentation for Python's built-in binary data types " +"in :ref:`binaryseq`." +msgstr "" +"此外，請參閱 Python 內建的二進位資料類型的文件，詳情請參考 :ref:`binaryseq`。" diff --git a/library/binascii.po b/library/binascii.po index 4cae1df2e3..50d22a9281 100644 --- a/library/binascii.po +++ b/library/binascii.po @@ -1,246 +1,246 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-09-23 07:52+0800\n" -"PO-Revision-Date: 2018-05-23 14:39+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/binascii.rst:2 -msgid ":mod:`!binascii` --- Convert between binary and ASCII" -msgstr ":mod:`!binascii` --- 在二進位制和 ASCII 之間轉換" - -#: ../../library/binascii.rst:13 -msgid "" -"The :mod:`binascii` module contains a number of methods to convert between " -"binary and various ASCII-encoded binary representations. Normally, you will " -"not use these functions directly but use wrapper modules like :mod:`base64` " -"instead. The :mod:`binascii` module contains low-level functions written in " -"C for greater speed that are used by the higher-level modules." -msgstr "" - -#: ../../library/binascii.rst:22 -msgid "" -"``a2b_*`` functions accept Unicode strings containing only ASCII characters. " -"Other functions only accept :term:`bytes-like objects ` " -"(such as :class:`bytes`, :class:`bytearray` and other objects that support " -"the buffer protocol)." -msgstr "" - -#: ../../library/binascii.rst:27 -msgid "ASCII-only unicode strings are now accepted by the ``a2b_*`` functions." -msgstr "" - -#: ../../library/binascii.rst:31 -msgid "The :mod:`binascii` module defines the following functions:" -msgstr ":mod:`binascii` 模組定義了以下函式：" - -#: ../../library/binascii.rst:36 -msgid "" -"Convert a single line of uuencoded data back to binary and return the binary " -"data. Lines normally contain 45 (binary) bytes, except for the last line. " -"Line data may be followed by whitespace." -msgstr "" - -#: ../../library/binascii.rst:43 -msgid "" -"Convert binary data to a line of ASCII characters, the return value is the " -"converted line, including a newline char. The length of *data* should be at " -"most 45. If *backtick* is true, zeros are represented by ``'`'`` instead of " -"spaces." -msgstr "" - -#: ../../library/binascii.rst:47 -msgid "Added the *backtick* parameter." -msgstr "新增 *backtick* 參數。" - -#: ../../library/binascii.rst:53 -msgid "" -"Convert a block of base64 data back to binary and return the binary data. " -"More than one line may be passed at a time." -msgstr "" - -#: ../../library/binascii.rst:56 -msgid "" -"If *strict_mode* is true, only valid base64 data will be converted. Invalid " -"base64 data will raise :exc:`binascii.Error`." -msgstr "" - -#: ../../library/binascii.rst:59 -msgid "Valid base64:" -msgstr "" - -#: ../../library/binascii.rst:61 -msgid "Conforms to :rfc:`3548`." -msgstr "" - -#: ../../library/binascii.rst:62 -msgid "Contains only characters from the base64 alphabet." -msgstr "" - -#: ../../library/binascii.rst:63 -msgid "" -"Contains no excess data after padding (including excess padding, newlines, " -"etc.)." -msgstr "" - -#: ../../library/binascii.rst:64 -msgid "Does not start with a padding." -msgstr "" - -#: ../../library/binascii.rst:66 -msgid "Added the *strict_mode* parameter." -msgstr "新增 *strict_mode* 參數。" - -#: ../../library/binascii.rst:72 -msgid "" -"Convert binary data to a line of ASCII characters in base64 coding. The " -"return value is the converted line, including a newline char if *newline* is " -"true. The output of this function conforms to :rfc:`3548`." -msgstr "" - -#: ../../library/binascii.rst:76 -msgid "Added the *newline* parameter." -msgstr "新增 *newline* 參數。" - -#: ../../library/binascii.rst:82 -msgid "" -"Convert a block of quoted-printable data back to binary and return the " -"binary data. More than one line may be passed at a time. If the optional " -"argument *header* is present and true, underscores will be decoded as spaces." -msgstr "" - -#: ../../library/binascii.rst:89 -msgid "" -"Convert binary data to a line(s) of ASCII characters in quoted-printable " -"encoding. The return value is the converted line(s). If the optional " -"argument *quotetabs* is present and true, all tabs and spaces will be " -"encoded. If the optional argument *istext* is present and true, newlines " -"are not encoded but trailing whitespace will be encoded. If the optional " -"argument *header* is present and true, spaces will be encoded as underscores " -"per :rfc:`1522`. If the optional argument *header* is present and false, " -"newline characters will be encoded as well; otherwise linefeed conversion " -"might corrupt the binary data stream." -msgstr "" - -#: ../../library/binascii.rst:102 -msgid "" -"Compute a 16-bit CRC value of *data*, starting with *value* as the initial " -"CRC, and return the result. This uses the CRC-CCITT polynomial *x*:sup:`16` " -"+ *x*:sup:`12` + *x*:sup:`5` + 1, often represented as 0x1021. This CRC is " -"used in the binhex4 format." -msgstr "" - -#: ../../library/binascii.rst:110 -msgid "" -"Compute CRC-32, the unsigned 32-bit checksum of *data*, starting with an " -"initial CRC of *value*. The default initial CRC is zero. The algorithm is " -"consistent with the ZIP file checksum. Since the algorithm is designed for " -"use as a checksum algorithm, it is not suitable for use as a general hash " -"algorithm. Use as follows::" -msgstr "" - -#: ../../library/binascii.rst:116 -msgid "" -"print(binascii.crc32(b\"hello world\"))\n" -"# Or, in two pieces:\n" -"crc = binascii.crc32(b\"hello\")\n" -"crc = binascii.crc32(b\" world\", crc)\n" -"print('crc32 = {:#010x}'.format(crc))" -msgstr "" - -#: ../../library/binascii.rst:122 -msgid "The result is always unsigned." -msgstr "" - -#: ../../library/binascii.rst:128 -msgid "" -"Return the hexadecimal representation of the binary *data*. Every byte of " -"*data* is converted into the corresponding 2-digit hex representation. The " -"returned bytes object is therefore twice as long as the length of *data*." -msgstr "" - -#: ../../library/binascii.rst:132 -msgid "" -"Similar functionality (but returning a text string) is also conveniently " -"accessible using the :meth:`bytes.hex` method." -msgstr "" - -#: ../../library/binascii.rst:135 -msgid "" -"If *sep* is specified, it must be a single character str or bytes object. It " -"will be inserted in the output after every *bytes_per_sep* input bytes. " -"Separator placement is counted from the right end of the output by default, " -"if you wish to count from the left, supply a negative *bytes_per_sep* value." -msgstr "" - -#: ../../library/binascii.rst:150 -msgid "The *sep* and *bytes_per_sep* parameters were added." -msgstr "新增 *sep* 與 *bytes_per_sep* 參數。" - -#: ../../library/binascii.rst:156 -msgid "" -"Return the binary data represented by the hexadecimal string *hexstr*. This " -"function is the inverse of :func:`b2a_hex`. *hexstr* must contain an even " -"number of hexadecimal digits (which can be upper or lower case), otherwise " -"an :exc:`Error` exception is raised." -msgstr "" - -#: ../../library/binascii.rst:161 -msgid "" -"Similar functionality (accepting only text string arguments, but more " -"liberal towards whitespace) is also accessible using the :meth:`bytes." -"fromhex` class method." -msgstr "" - -#: ../../library/binascii.rst:167 -msgid "Exception raised on errors. These are usually programming errors." -msgstr "" - -#: ../../library/binascii.rst:172 -msgid "" -"Exception raised on incomplete data. These are usually not programming " -"errors, but may be handled by reading a little more data and trying again." -msgstr "" - -#: ../../library/binascii.rst:178 -msgid "Module :mod:`base64`" -msgstr ":mod:`base64` 模組" - -#: ../../library/binascii.rst:179 -msgid "" -"Support for RFC compliant base64-style encoding in base 16, 32, 64, and 85." -msgstr "" - -#: ../../library/binascii.rst:182 -msgid "Module :mod:`quopri`" -msgstr ":mod:`quopri` 模組" - -#: ../../library/binascii.rst:183 -msgid "Support for quoted-printable encoding used in MIME email messages." -msgstr "" - -#: ../../library/binascii.rst:8 -msgid "module" -msgstr "module（模組）" - -#: ../../library/binascii.rst:8 -msgid "base64" -msgstr "base64" - -#~ msgid "Module :mod:`uu`" -#~ msgstr ":mod:`uu` 模組" - -#~ msgid "uu" -#~ msgstr "uu" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-09-23 07:52+0800\n" +"PO-Revision-Date: 2018-05-23 14:39+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/binascii.rst:2 +msgid ":mod:`!binascii` --- Convert between binary and ASCII" +msgstr ":mod:`!binascii` --- 在二進位制和 ASCII 之間轉換" + +#: ../../library/binascii.rst:13 +msgid "" +"The :mod:`binascii` module contains a number of methods to convert between " +"binary and various ASCII-encoded binary representations. Normally, you will " +"not use these functions directly but use wrapper modules like :mod:`base64` " +"instead. The :mod:`binascii` module contains low-level functions written in " +"C for greater speed that are used by the higher-level modules." +msgstr "" + +#: ../../library/binascii.rst:22 +msgid "" +"``a2b_*`` functions accept Unicode strings containing only ASCII characters. " +"Other functions only accept :term:`bytes-like objects ` " +"(such as :class:`bytes`, :class:`bytearray` and other objects that support " +"the buffer protocol)." +msgstr "" + +#: ../../library/binascii.rst:27 +msgid "ASCII-only unicode strings are now accepted by the ``a2b_*`` functions." +msgstr "" + +#: ../../library/binascii.rst:31 +msgid "The :mod:`binascii` module defines the following functions:" +msgstr ":mod:`binascii` 模組定義了以下函式：" + +#: ../../library/binascii.rst:36 +msgid "" +"Convert a single line of uuencoded data back to binary and return the binary " +"data. Lines normally contain 45 (binary) bytes, except for the last line. " +"Line data may be followed by whitespace." +msgstr "" + +#: ../../library/binascii.rst:43 +msgid "" +"Convert binary data to a line of ASCII characters, the return value is the " +"converted line, including a newline char. The length of *data* should be at " +"most 45. If *backtick* is true, zeros are represented by ``'`'`` instead of " +"spaces." +msgstr "" + +#: ../../library/binascii.rst:47 +msgid "Added the *backtick* parameter." +msgstr "新增 *backtick* 參數。" + +#: ../../library/binascii.rst:53 +msgid "" +"Convert a block of base64 data back to binary and return the binary data. " +"More than one line may be passed at a time." +msgstr "" + +#: ../../library/binascii.rst:56 +msgid "" +"If *strict_mode* is true, only valid base64 data will be converted. Invalid " +"base64 data will raise :exc:`binascii.Error`." +msgstr "" + +#: ../../library/binascii.rst:59 +msgid "Valid base64:" +msgstr "" + +#: ../../library/binascii.rst:61 +msgid "Conforms to :rfc:`3548`." +msgstr "" + +#: ../../library/binascii.rst:62 +msgid "Contains only characters from the base64 alphabet." +msgstr "" + +#: ../../library/binascii.rst:63 +msgid "" +"Contains no excess data after padding (including excess padding, newlines, " +"etc.)." +msgstr "" + +#: ../../library/binascii.rst:64 +msgid "Does not start with a padding." +msgstr "" + +#: ../../library/binascii.rst:66 +msgid "Added the *strict_mode* parameter." +msgstr "新增 *strict_mode* 參數。" + +#: ../../library/binascii.rst:72 +msgid "" +"Convert binary data to a line of ASCII characters in base64 coding. The " +"return value is the converted line, including a newline char if *newline* is " +"true. The output of this function conforms to :rfc:`3548`." +msgstr "" + +#: ../../library/binascii.rst:76 +msgid "Added the *newline* parameter." +msgstr "新增 *newline* 參數。" + +#: ../../library/binascii.rst:82 +msgid "" +"Convert a block of quoted-printable data back to binary and return the " +"binary data. More than one line may be passed at a time. If the optional " +"argument *header* is present and true, underscores will be decoded as spaces." +msgstr "" + +#: ../../library/binascii.rst:89 +msgid "" +"Convert binary data to a line(s) of ASCII characters in quoted-printable " +"encoding. The return value is the converted line(s). If the optional " +"argument *quotetabs* is present and true, all tabs and spaces will be " +"encoded. If the optional argument *istext* is present and true, newlines " +"are not encoded but trailing whitespace will be encoded. If the optional " +"argument *header* is present and true, spaces will be encoded as underscores " +"per :rfc:`1522`. If the optional argument *header* is present and false, " +"newline characters will be encoded as well; otherwise linefeed conversion " +"might corrupt the binary data stream." +msgstr "" + +#: ../../library/binascii.rst:102 +msgid "" +"Compute a 16-bit CRC value of *data*, starting with *value* as the initial " +"CRC, and return the result. This uses the CRC-CCITT polynomial *x*:sup:`16` " +"+ *x*:sup:`12` + *x*:sup:`5` + 1, often represented as 0x1021. This CRC is " +"used in the binhex4 format." +msgstr "" + +#: ../../library/binascii.rst:110 +msgid "" +"Compute CRC-32, the unsigned 32-bit checksum of *data*, starting with an " +"initial CRC of *value*. The default initial CRC is zero. The algorithm is " +"consistent with the ZIP file checksum. Since the algorithm is designed for " +"use as a checksum algorithm, it is not suitable for use as a general hash " +"algorithm. Use as follows::" +msgstr "" + +#: ../../library/binascii.rst:116 +msgid "" +"print(binascii.crc32(b\"hello world\"))\n" +"# Or, in two pieces:\n" +"crc = binascii.crc32(b\"hello\")\n" +"crc = binascii.crc32(b\" world\", crc)\n" +"print('crc32 = {:#010x}'.format(crc))" +msgstr "" + +#: ../../library/binascii.rst:122 +msgid "The result is always unsigned." +msgstr "" + +#: ../../library/binascii.rst:128 +msgid "" +"Return the hexadecimal representation of the binary *data*. Every byte of " +"*data* is converted into the corresponding 2-digit hex representation. The " +"returned bytes object is therefore twice as long as the length of *data*." +msgstr "" + +#: ../../library/binascii.rst:132 +msgid "" +"Similar functionality (but returning a text string) is also conveniently " +"accessible using the :meth:`bytes.hex` method." +msgstr "" + +#: ../../library/binascii.rst:135 +msgid "" +"If *sep* is specified, it must be a single character str or bytes object. It " +"will be inserted in the output after every *bytes_per_sep* input bytes. " +"Separator placement is counted from the right end of the output by default, " +"if you wish to count from the left, supply a negative *bytes_per_sep* value." +msgstr "" + +#: ../../library/binascii.rst:150 +msgid "The *sep* and *bytes_per_sep* parameters were added." +msgstr "新增 *sep* 與 *bytes_per_sep* 參數。" + +#: ../../library/binascii.rst:156 +msgid "" +"Return the binary data represented by the hexadecimal string *hexstr*. This " +"function is the inverse of :func:`b2a_hex`. *hexstr* must contain an even " +"number of hexadecimal digits (which can be upper or lower case), otherwise " +"an :exc:`Error` exception is raised." +msgstr "" + +#: ../../library/binascii.rst:161 +msgid "" +"Similar functionality (accepting only text string arguments, but more " +"liberal towards whitespace) is also accessible using the :meth:`bytes." +"fromhex` class method." +msgstr "" + +#: ../../library/binascii.rst:167 +msgid "Exception raised on errors. These are usually programming errors." +msgstr "" + +#: ../../library/binascii.rst:172 +msgid "" +"Exception raised on incomplete data. These are usually not programming " +"errors, but may be handled by reading a little more data and trying again." +msgstr "" + +#: ../../library/binascii.rst:178 +msgid "Module :mod:`base64`" +msgstr ":mod:`base64` 模組" + +#: ../../library/binascii.rst:179 +msgid "" +"Support for RFC compliant base64-style encoding in base 16, 32, 64, and 85." +msgstr "" + +#: ../../library/binascii.rst:182 +msgid "Module :mod:`quopri`" +msgstr ":mod:`quopri` 模組" + +#: ../../library/binascii.rst:183 +msgid "Support for quoted-printable encoding used in MIME email messages." +msgstr "" + +#: ../../library/binascii.rst:8 +msgid "module" +msgstr "module（模組）" + +#: ../../library/binascii.rst:8 +msgid "base64" +msgstr "base64" + +#~ msgid "Module :mod:`uu`" +#~ msgstr ":mod:`uu` 模組" + +#~ msgid "uu" +#~ msgstr "uu" diff --git a/library/bisect.po b/library/bisect.po index e18d196ae0..ad76619bd2 100644 --- a/library/bisect.po +++ b/library/bisect.po @@ -1,424 +1,424 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# 周 忠毅 , 2016 -# Liang-Bo Wang , 2017 -# pertertc , 2022 -# Matt Wang , 2022 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: 2023-08-01 12:53+0800\n" -"Last-Translator: Matt Wang \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" -"X-Generator: Poedit 3.3.2\n" - -#: ../../library/bisect.rst:2 -msgid ":mod:`!bisect` --- Array bisection algorithm" -msgstr ":mod:`!bisect` --- 陣列二分演算法 (Array bisection algorithm)" - -#: ../../library/bisect.rst:10 -msgid "**Source code:** :source:`Lib/bisect.py`" -msgstr "**原始碼：**\\ :source:`Lib/bisect.py`" - -#: ../../library/bisect.rst:14 -msgid "" -"This module provides support for maintaining a list in sorted order without " -"having to sort the list after each insertion. For long lists of items with " -"expensive comparison operations, this can be an improvement over linear " -"searches or frequent resorting." -msgstr "" -"這個模組維護一個已經排序過的 list ，當我們每次做完插入後不需要再次排序整個 " -"list 。一個很長的 list 的比較操作很花費時間，可以透過線性搜尋或頻繁地詢問來改" -"善。" - -#: ../../library/bisect.rst:19 -msgid "" -"The module is called :mod:`bisect` because it uses a basic bisection " -"algorithm to do its work. Unlike other bisection tools that search for a " -"specific value, the functions in this module are designed to locate an " -"insertion point. Accordingly, the functions never call " -"an :meth:`~object.__eq__` method to determine whether a value has been " -"found. Instead, the functions only call the :meth:`~object.__lt__` method " -"and will return an insertion point between values in an array." -msgstr "" -"這個模組被稱為 :mod:`bisect` 是因為它使用基本二分演算法來完成其工作。不像其它" -"搜尋特定值的二分法工具，本模組中的函式旨在定位插入點。因此，這些函式永遠不會" -"呼叫 :meth:`~object.__eq__` 方法來確認是否找到一個值。相反地，這些函式只呼" -"叫 :meth:`~object.__lt__` 方法，並在陣列中的值回傳一個插入點。" - -#: ../../library/bisect.rst:29 -msgid "" -"The functions in this module are not thread-safe. If multiple threads " -"concurrently use :mod:`bisect` functions on the same sequence, this may " -"result in undefined behaviour. Likewise, if the provided sequence is mutated " -"by a different thread while a :mod:`bisect` function is operating on it, the " -"result is undefined. For example, using :py:func:`~bisect.insort_left` on " -"the same list from multiple threads may result in the list becoming unsorted." -msgstr "" - -#: ../../library/bisect.rst:39 -msgid "The following functions are provided:" -msgstr "此模組提供下面的函式：" - -#: ../../library/bisect.rst:44 -msgid "" -"Locate the insertion point for *x* in *a* to maintain sorted order. The " -"parameters *lo* and *hi* may be used to specify a subset of the list which " -"should be considered; by default the entire list is used. If *x* is already " -"present in *a*, the insertion point will be before (to the left of) any " -"existing entries. The return value is suitable for use as the first " -"parameter to ``list.insert()`` assuming that *a* is already sorted." -msgstr "" -"在 *a* 當中找到一個位置，讓 *x* 插入後 *a* 仍然是排序好的。參數 *lo* 和 *hi* " -"用來指定 list 中應該被考慮的子區間，預設是考慮整個 list 。如果 *a* 裡面已經" -"有 *x* 出現，插入的位置會在所有 *x* 的前面（左邊）。回傳值可以被當作 " -"``list.insert()`` 的第一個參數，但列表 *a* 必須先排序過。" - -#: ../../library/bisect.rst:51 -msgid "" -"The returned insertion point *ip* partitions the array *a* into two slices " -"such that ``all(elem < x for elem in a[lo : ip])`` is true for the left " -"slice and ``all(elem >= x for elem in a[ip : hi])`` is true for the right " -"slice." -msgstr "" -"回傳的插入點 *ip* 將陣列 *a* 劃分為左右兩個切片，使得對於左切片而言 " -"``all(elem < x for elem in a[lo : ip])`` 為真，對於右切片而言 ``all(elem >= " -"x for elem in a[ip : hi])`` 為真。" - -#: ../../library/bisect.rst:56 -msgid "" -"*key* specifies a :term:`key function` of one argument that is used to " -"extract a comparison key from each element in the array. To support " -"searching complex records, the key function is not applied to the *x* value." -msgstr "" -"*key* 可指定一個單一參數的 :term:`key function`。函式將套用此 function 在陣列" -"所有元素以得到比較值來計算順位。注意此 function 只會套用在陣列中的元素，不會" -"套用在 *x*。" - -#: ../../library/bisect.rst:60 -msgid "" -"If *key* is ``None``, the elements are compared directly and no key function " -"is called." -msgstr "若 *key* 為 ``None``，元素將直接進行比較，不會呼叫任何鍵函式。" - -#: ../../library/bisect.rst:63 ../../library/bisect.rst:77 -#: ../../library/bisect.rst:95 ../../library/bisect.rst:115 -msgid "Added the *key* parameter." -msgstr "新增 *key* 參數。" - -#: ../../library/bisect.rst:70 -msgid "" -"Similar to :py:func:`~bisect.bisect_left`, but returns an insertion point " -"which comes after (to the right of) any existing entries of *x* in *a*." -msgstr "" -"類似 :py:func:`~bisect.bisect_left`，但回傳的插入位置會在所有 *a* 當中的 *x* " -"的後面（右邊）。" - -#: ../../library/bisect.rst:73 -msgid "" -"The returned insertion point *ip* partitions the array *a* into two slices " -"such that ``all(elem <= x for elem in a[lo : ip])`` is true for the left " -"slice and ``all(elem > x for elem in a[ip : hi])`` is true for the right " -"slice." -msgstr "" -"回傳的插入點 *ip* 將陣列 *a* 劃分為左右兩個切片，使得對於左切片而言 " -"``all(elem <= x for elem in a[lo : ip])`` 為真，對於右切片而言 ``all(elem > " -"x for elem in a[ip : hi])`` 為真。" - -#: ../../library/bisect.rst:83 -msgid "Insert *x* in *a* in sorted order." -msgstr "將元素 *x* 插入 list *a*，並維持順序。" - -#: ../../library/bisect.rst:85 -msgid "" -"This function first runs :py:func:`~bisect.bisect_left` to locate an " -"insertion point. Next, it runs the :meth:`~sequence.insert` method on *a* to " -"insert *x* at the appropriate position to maintain sort order." -msgstr "" -"此函式先使用 :py:func:`~bisect.bisect_left` 搜尋插入位置，接著用 :meth:`~sequence." -"insert` 於 *a* 以將 *x* 插入，並維持添加元素後的順序。" - -#: ../../library/bisect.rst:89 ../../library/bisect.rst:109 -msgid "" -"To support inserting records in a table, the *key* function (if any) is " -"applied to *x* for the search step but not for the insertion step." -msgstr "此函式只有在搜尋時會使用 *key* 函式，插入時不會。" - -#: ../../library/bisect.rst:92 ../../library/bisect.rst:112 -msgid "" -"Keep in mind that the *O*\\ (log *n*) search is dominated by the slow *O*\\ " -"(*n*) insertion step." -msgstr "" -"注意雖然搜尋是 *O*\\ (log *n*)，但插入是 *O*\\ (*n*)，因此此函式整體時間複雜" -"度是 *O*\\ (*n*)。" - -#: ../../library/bisect.rst:102 -msgid "" -"Similar to :py:func:`~bisect.insort_left`, but inserting *x* in *a* after " -"any existing entries of *x*." -msgstr "" -"類似 :py:func:`~bisect.insort_left`，但插入的位置會在所有 *a* 當中的 *x* 的後" -"面（右邊）。" - -#: ../../library/bisect.rst:105 -msgid "" -"This function first runs :py:func:`~bisect.bisect_right` to locate an " -"insertion point. Next, it runs the :meth:`~sequence.insert` method on *a* to " -"insert *x* at the appropriate position to maintain sort order." -msgstr "" -"此函式先使用 :py:func:`~bisect.bisect_right` 搜尋插入位置，接著用 :meth:`~sequence." -"insert` 於 *a* 以將 *x* 插入，並維持添加元素後的順序。" - -#: ../../library/bisect.rst:120 -msgid "Performance Notes" -msgstr "效能考量" - -#: ../../library/bisect.rst:122 -msgid "" -"When writing time sensitive code using *bisect()* and *insort()*, keep these " -"thoughts in mind:" -msgstr "" -"若在需要關注寫入時間的程式當中使用 *bisect()* 和 *insort()*，請特別注意幾個事" -"項：" - -#: ../../library/bisect.rst:125 -msgid "" -"Bisection is effective for searching ranges of values. For locating specific " -"values, dictionaries are more performant." -msgstr "" -"二分法在一段範圍的數值中做搜尋的效率較佳，但若是要存取特定數值，使用字典的表" -"現還是比較好。" - -#: ../../library/bisect.rst:128 -msgid "" -"The *insort()* functions are *O*\\ (*n*) because the logarithmic search step " -"is dominated by the linear time insertion step." -msgstr "" -"*insort()* 函式的複雜度為 *O*\\ (*n*)，因為對數搜尋是以線性時間的插入步驟所主" -"導 (dominate)。" - -#: ../../library/bisect.rst:131 -msgid "" -"The search functions are stateless and discard key function results after " -"they are used. Consequently, if the search functions are used in a loop, " -"the key function may be called again and again on the same array elements. " -"If the key function isn't fast, consider wrapping it " -"with :py:func:`functools.cache` to avoid duplicate computations. " -"Alternatively, consider searching an array of precomputed keys to locate the " -"insertion point (as shown in the examples section below)." -msgstr "" -"搜尋函式為無狀態的 (stateless)，且鍵函式會在使用過後被丟棄。因此，如果搜尋函" -"式被使用於迴圈當中，鍵函式會不斷被重複呼叫於相同的 list 元素。如果鍵函式執行" -"速度不快，請考慮將其以 :py:func:`functools.cache` 包裝起來以減少重複的計算。" -"另外，也可以透過搜尋預先計算好的鍵列表 (array of precomputed keys) 來定位插入" -"點（如下方範例所示）。" - -#: ../../library/bisect.rst:141 -msgid "" -"`Sorted Collections `_ is a " -"high performance module that uses *bisect* to managed sorted collections of " -"data." -msgstr "" -"`有序容器 (Sorted Collections) `_ 是一個使用 *bisect* 來管理資料之有序集合的高效能模組。" - -#: ../../library/bisect.rst:145 -msgid "" -"The `SortedCollection recipe `_ uses bisect to build a full-featured collection class " -"with straight-forward search methods and support for a key-function. The " -"keys are precomputed to save unnecessary calls to the key function during " -"searches." -msgstr "" -"`SortedCollection recipe `_ 使用二分法來建立一個功能完整的集合類別 (collection " -"class) 並帶有符合直覺的搜尋方法 (search methods) 與支援鍵函式。鍵會預先被計算" -"好，以減少搜尋過程中多餘的鍵函式呼叫。" - -#: ../../library/bisect.rst:153 -msgid "Searching Sorted Lists" -msgstr "搜尋一個已排序的 list" - -#: ../../library/bisect.rst:155 -msgid "" -"The above `bisect functions`_ are useful for finding insertion points but " -"can be tricky or awkward to use for common searching tasks. The following " -"five functions show how to transform them into the standard lookups for " -"sorted lists::" -msgstr "" -"上面的 `bisect functions`_ 在找到數值插入點上很有用，但一般的數值搜尋任務上就" -"不是那麼的方便。以下的五個函式展示了如何將其轉換成標準的有序列表查找函式： ::" - -#: ../../library/bisect.rst:160 -msgid "" -"def index(a, x):\n" -" 'Locate the leftmost value exactly equal to x'\n" -" i = bisect_left(a, x)\n" -" if i != len(a) and a[i] == x:\n" -" return i\n" -" raise ValueError\n" -"\n" -"def find_lt(a, x):\n" -" 'Find rightmost value less than x'\n" -" i = bisect_left(a, x)\n" -" if i:\n" -" return a[i-1]\n" -" raise ValueError\n" -"\n" -"def find_le(a, x):\n" -" 'Find rightmost value less than or equal to x'\n" -" i = bisect_right(a, x)\n" -" if i:\n" -" return a[i-1]\n" -" raise ValueError\n" -"\n" -"def find_gt(a, x):\n" -" 'Find leftmost value greater than x'\n" -" i = bisect_right(a, x)\n" -" if i != len(a):\n" -" return a[i]\n" -" raise ValueError\n" -"\n" -"def find_ge(a, x):\n" -" 'Find leftmost item greater than or equal to x'\n" -" i = bisect_left(a, x)\n" -" if i != len(a):\n" -" return a[i]\n" -" raise ValueError" -msgstr "" - -#: ../../library/bisect.rst:197 -msgid "Examples" -msgstr "範例" - -#: ../../library/bisect.rst:201 -msgid "" -"The :py:func:`~bisect.bisect` function can be useful for numeric table " -"lookups. This example uses :py:func:`~bisect.bisect` to look up a letter " -"grade for an exam score (say) based on a set of ordered numeric breakpoints: " -"90 and up is an 'A', 80 to 89 is a 'B', and so on::" -msgstr "" -":py:func:`~bisect.bisect` 函式可用於數值表中的查找 (numeric table lookup)，這" -"個範例使用 :py:func:`~bisect.bisect` 以基於一組有序的數值分界點來為一個考試成" -"績找到相對應的字母等級：90 以上是 'A'、80 到 89 為 'B'，依此類推： ::" - -#: ../../library/bisect.rst:206 -msgid "" -">>> def grade(score, breakpoints=[60, 70, 80, 90], grades='FDCBA'):\n" -"... i = bisect(breakpoints, score)\n" -"... return grades[i]\n" -"...\n" -">>> [grade(score) for score in [33, 99, 77, 70, 89, 90, 100]]\n" -"['F', 'A', 'C', 'C', 'B', 'A', 'A']" -msgstr "" -">>> def grade(score, breakpoints=[60, 70, 80, 90], grades='FDCBA'):\n" -"... i = bisect(breakpoints, score)\n" -"... return grades[i]\n" -"...\n" -">>> [grade(score) for score in [33, 99, 77, 70, 89, 90, 100]]\n" -"['F', 'A', 'C', 'C', 'B', 'A', 'A']" - -#: ../../library/bisect.rst:213 -msgid "" -"The :py:func:`~bisect.bisect` and :py:func:`~bisect.insort` functions also " -"work with lists of tuples. The *key* argument can serve to extract the " -"field used for ordering records in a table::" -msgstr "" -":py:func:`~bisect.bisect` 與 :py:func:`~bisect.insort` 函式也適用於內容為 " -"tuples（元組）的 lists，*key* 引數可被用以取出在數值表中作為排序依據的欄" -"位： ::" - -#: ../../library/bisect.rst:217 -msgid "" -">>> from collections import namedtuple\n" -">>> from operator import attrgetter\n" -">>> from bisect import bisect, insort\n" -">>> from pprint import pprint\n" -"\n" -">>> Movie = namedtuple('Movie', ('name', 'released', 'director'))\n" -"\n" -">>> movies = [\n" -"... Movie('Jaws', 1975, 'Spielberg'),\n" -"... Movie('Titanic', 1997, 'Cameron'),\n" -"... Movie('The Birds', 1963, 'Hitchcock'),\n" -"... Movie('Aliens', 1986, 'Cameron')\n" -"... ]\n" -"\n" -">>> # Find the first movie released after 1960\n" -">>> by_year = attrgetter('released')\n" -">>> movies.sort(key=by_year)\n" -">>> movies[bisect(movies, 1960, key=by_year)]\n" -"Movie(name='The Birds', released=1963, director='Hitchcock')\n" -"\n" -">>> # Insert a movie while maintaining sort order\n" -">>> romance = Movie('Love Story', 1970, 'Hiller')\n" -">>> insort(movies, romance, key=by_year)\n" -">>> pprint(movies)\n" -"[Movie(name='The Birds', released=1963, director='Hitchcock'),\n" -" Movie(name='Love Story', released=1970, director='Hiller'),\n" -" Movie(name='Jaws', released=1975, director='Spielberg'),\n" -" Movie(name='Aliens', released=1986, director='Cameron'),\n" -" Movie(name='Titanic', released=1997, director='Cameron')]" -msgstr "" -">>> from collections import namedtuple\n" -">>> from operator import attrgetter\n" -">>> from bisect import bisect, insort\n" -">>> from pprint import pprint\n" -"\n" -">>> Movie = namedtuple('Movie', ('name', 'released', 'director'))\n" -"\n" -">>> movies = [\n" -"... Movie('Jaws', 1975, 'Spielberg'),\n" -"... Movie('Titanic', 1997, 'Cameron'),\n" -"... Movie('The Birds', 1963, 'Hitchcock'),\n" -"... Movie('Aliens', 1986, 'Cameron')\n" -"... ]\n" -"\n" -">>> # 找到 1960 年後上映的第一部電影\n" -">>> by_year = attrgetter('released')\n" -">>> movies.sort(key=by_year)\n" -">>> movies[bisect(movies, 1960, key=by_year)]\n" -"Movie(name='The Birds', released=1963, director='Hitchcock')\n" -"\n" -">>> # 插入一部電影並保持排序\n" -">>> romance = Movie('Love Story', 1970, 'Hiller')\n" -">>> insort(movies, romance, key=by_year)\n" -">>> pprint(movies)\n" -"[Movie(name='The Birds', released=1963, director='Hitchcock'),\n" -" Movie(name='Love Story', released=1970, director='Hiller'),\n" -" Movie(name='Jaws', released=1975, director='Spielberg'),\n" -" Movie(name='Aliens', released=1986, director='Cameron'),\n" -" Movie(name='Titanic', released=1997, director='Cameron')]" - -#: ../../library/bisect.rst:247 -msgid "" -"If the key function is expensive, it is possible to avoid repeated function " -"calls by searching a list of precomputed keys to find the index of a record::" -msgstr "" -"如果鍵函式會消耗較多運算資源，那可以在預先計算好的鍵列表中搜尋該紀錄的索引" -"值，以減少重複的函式呼叫： ::" - -#: ../../library/bisect.rst:250 -msgid "" -">>> data = [('red', 5), ('blue', 1), ('yellow', 8), ('black', 0)]\n" -">>> data.sort(key=lambda r: r[1]) # Or use operator.itemgetter(1).\n" -">>> keys = [r[1] for r in data] # Precompute a list of keys.\n" -">>> data[bisect_left(keys, 0)]\n" -"('black', 0)\n" -">>> data[bisect_left(keys, 1)]\n" -"('blue', 1)\n" -">>> data[bisect_left(keys, 5)]\n" -"('red', 5)\n" -">>> data[bisect_left(keys, 8)]\n" -"('yellow', 8)" -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# 周 忠毅 , 2016 +# Liang-Bo Wang , 2017 +# pertertc , 2022 +# Matt Wang , 2022 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: 2023-08-01 12:53+0800\n" +"Last-Translator: Matt Wang \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" +"X-Generator: Poedit 3.3.2\n" + +#: ../../library/bisect.rst:2 +msgid ":mod:`!bisect` --- Array bisection algorithm" +msgstr ":mod:`!bisect` --- 陣列二分演算法 (Array bisection algorithm)" + +#: ../../library/bisect.rst:10 +msgid "**Source code:** :source:`Lib/bisect.py`" +msgstr "**原始碼：**\\ :source:`Lib/bisect.py`" + +#: ../../library/bisect.rst:14 +msgid "" +"This module provides support for maintaining a list in sorted order without " +"having to sort the list after each insertion. For long lists of items with " +"expensive comparison operations, this can be an improvement over linear " +"searches or frequent resorting." +msgstr "" +"這個模組維護一個已經排序過的 list ，當我們每次做完插入後不需要再次排序整個 " +"list 。一個很長的 list 的比較操作很花費時間，可以透過線性搜尋或頻繁地詢問來改" +"善。" + +#: ../../library/bisect.rst:19 +msgid "" +"The module is called :mod:`bisect` because it uses a basic bisection " +"algorithm to do its work. Unlike other bisection tools that search for a " +"specific value, the functions in this module are designed to locate an " +"insertion point. Accordingly, the functions never call " +"an :meth:`~object.__eq__` method to determine whether a value has been " +"found. Instead, the functions only call the :meth:`~object.__lt__` method " +"and will return an insertion point between values in an array." +msgstr "" +"這個模組被稱為 :mod:`bisect` 是因為它使用基本二分演算法來完成其工作。不像其它" +"搜尋特定值的二分法工具，本模組中的函式旨在定位插入點。因此，這些函式永遠不會" +"呼叫 :meth:`~object.__eq__` 方法來確認是否找到一個值。相反地，這些函式只呼" +"叫 :meth:`~object.__lt__` 方法，並在陣列中的值回傳一個插入點。" + +#: ../../library/bisect.rst:29 +msgid "" +"The functions in this module are not thread-safe. If multiple threads " +"concurrently use :mod:`bisect` functions on the same sequence, this may " +"result in undefined behaviour. Likewise, if the provided sequence is mutated " +"by a different thread while a :mod:`bisect` function is operating on it, the " +"result is undefined. For example, using :py:func:`~bisect.insort_left` on " +"the same list from multiple threads may result in the list becoming unsorted." +msgstr "" + +#: ../../library/bisect.rst:39 +msgid "The following functions are provided:" +msgstr "此模組提供下面的函式：" + +#: ../../library/bisect.rst:44 +msgid "" +"Locate the insertion point for *x* in *a* to maintain sorted order. The " +"parameters *lo* and *hi* may be used to specify a subset of the list which " +"should be considered; by default the entire list is used. If *x* is already " +"present in *a*, the insertion point will be before (to the left of) any " +"existing entries. The return value is suitable for use as the first " +"parameter to ``list.insert()`` assuming that *a* is already sorted." +msgstr "" +"在 *a* 當中找到一個位置，讓 *x* 插入後 *a* 仍然是排序好的。參數 *lo* 和 *hi* " +"用來指定 list 中應該被考慮的子區間，預設是考慮整個 list 。如果 *a* 裡面已經" +"有 *x* 出現，插入的位置會在所有 *x* 的前面（左邊）。回傳值可以被當作 " +"``list.insert()`` 的第一個參數，但列表 *a* 必須先排序過。" + +#: ../../library/bisect.rst:51 +msgid "" +"The returned insertion point *ip* partitions the array *a* into two slices " +"such that ``all(elem < x for elem in a[lo : ip])`` is true for the left " +"slice and ``all(elem >= x for elem in a[ip : hi])`` is true for the right " +"slice." +msgstr "" +"回傳的插入點 *ip* 將陣列 *a* 劃分為左右兩個切片，使得對於左切片而言 " +"``all(elem < x for elem in a[lo : ip])`` 為真，對於右切片而言 ``all(elem >= " +"x for elem in a[ip : hi])`` 為真。" + +#: ../../library/bisect.rst:56 +msgid "" +"*key* specifies a :term:`key function` of one argument that is used to " +"extract a comparison key from each element in the array. To support " +"searching complex records, the key function is not applied to the *x* value." +msgstr "" +"*key* 可指定一個單一參數的 :term:`key function`。函式將套用此 function 在陣列" +"所有元素以得到比較值來計算順位。注意此 function 只會套用在陣列中的元素，不會" +"套用在 *x*。" + +#: ../../library/bisect.rst:60 +msgid "" +"If *key* is ``None``, the elements are compared directly and no key function " +"is called." +msgstr "若 *key* 為 ``None``，元素將直接進行比較，不會呼叫任何鍵函式。" + +#: ../../library/bisect.rst:63 ../../library/bisect.rst:77 +#: ../../library/bisect.rst:95 ../../library/bisect.rst:115 +msgid "Added the *key* parameter." +msgstr "新增 *key* 參數。" + +#: ../../library/bisect.rst:70 +msgid "" +"Similar to :py:func:`~bisect.bisect_left`, but returns an insertion point " +"which comes after (to the right of) any existing entries of *x* in *a*." +msgstr "" +"類似 :py:func:`~bisect.bisect_left`，但回傳的插入位置會在所有 *a* 當中的 *x* " +"的後面（右邊）。" + +#: ../../library/bisect.rst:73 +msgid "" +"The returned insertion point *ip* partitions the array *a* into two slices " +"such that ``all(elem <= x for elem in a[lo : ip])`` is true for the left " +"slice and ``all(elem > x for elem in a[ip : hi])`` is true for the right " +"slice." +msgstr "" +"回傳的插入點 *ip* 將陣列 *a* 劃分為左右兩個切片，使得對於左切片而言 " +"``all(elem <= x for elem in a[lo : ip])`` 為真，對於右切片而言 ``all(elem > " +"x for elem in a[ip : hi])`` 為真。" + +#: ../../library/bisect.rst:83 +msgid "Insert *x* in *a* in sorted order." +msgstr "將元素 *x* 插入 list *a*，並維持順序。" + +#: ../../library/bisect.rst:85 +msgid "" +"This function first runs :py:func:`~bisect.bisect_left` to locate an " +"insertion point. Next, it runs the :meth:`~sequence.insert` method on *a* to " +"insert *x* at the appropriate position to maintain sort order." +msgstr "" +"此函式先使用 :py:func:`~bisect.bisect_left` 搜尋插入位置，接著用 :meth:`~sequence." +"insert` 於 *a* 以將 *x* 插入，並維持添加元素後的順序。" + +#: ../../library/bisect.rst:89 ../../library/bisect.rst:109 +msgid "" +"To support inserting records in a table, the *key* function (if any) is " +"applied to *x* for the search step but not for the insertion step." +msgstr "此函式只有在搜尋時會使用 *key* 函式，插入時不會。" + +#: ../../library/bisect.rst:92 ../../library/bisect.rst:112 +msgid "" +"Keep in mind that the *O*\\ (log *n*) search is dominated by the slow *O*\\ " +"(*n*) insertion step." +msgstr "" +"注意雖然搜尋是 *O*\\ (log *n*)，但插入是 *O*\\ (*n*)，因此此函式整體時間複雜" +"度是 *O*\\ (*n*)。" + +#: ../../library/bisect.rst:102 +msgid "" +"Similar to :py:func:`~bisect.insort_left`, but inserting *x* in *a* after " +"any existing entries of *x*." +msgstr "" +"類似 :py:func:`~bisect.insort_left`，但插入的位置會在所有 *a* 當中的 *x* 的後" +"面（右邊）。" + +#: ../../library/bisect.rst:105 +msgid "" +"This function first runs :py:func:`~bisect.bisect_right` to locate an " +"insertion point. Next, it runs the :meth:`~sequence.insert` method on *a* to " +"insert *x* at the appropriate position to maintain sort order." +msgstr "" +"此函式先使用 :py:func:`~bisect.bisect_right` 搜尋插入位置，接著用 :meth:`~sequence." +"insert` 於 *a* 以將 *x* 插入，並維持添加元素後的順序。" + +#: ../../library/bisect.rst:120 +msgid "Performance Notes" +msgstr "效能考量" + +#: ../../library/bisect.rst:122 +msgid "" +"When writing time sensitive code using *bisect()* and *insort()*, keep these " +"thoughts in mind:" +msgstr "" +"若在需要關注寫入時間的程式當中使用 *bisect()* 和 *insort()*，請特別注意幾個事" +"項：" + +#: ../../library/bisect.rst:125 +msgid "" +"Bisection is effective for searching ranges of values. For locating specific " +"values, dictionaries are more performant." +msgstr "" +"二分法在一段範圍的數值中做搜尋的效率較佳，但若是要存取特定數值，使用字典的表" +"現還是比較好。" + +#: ../../library/bisect.rst:128 +msgid "" +"The *insort()* functions are *O*\\ (*n*) because the logarithmic search step " +"is dominated by the linear time insertion step." +msgstr "" +"*insort()* 函式的複雜度為 *O*\\ (*n*)，因為對數搜尋是以線性時間的插入步驟所主" +"導 (dominate)。" + +#: ../../library/bisect.rst:131 +msgid "" +"The search functions are stateless and discard key function results after " +"they are used. Consequently, if the search functions are used in a loop, " +"the key function may be called again and again on the same array elements. " +"If the key function isn't fast, consider wrapping it " +"with :py:func:`functools.cache` to avoid duplicate computations. " +"Alternatively, consider searching an array of precomputed keys to locate the " +"insertion point (as shown in the examples section below)." +msgstr "" +"搜尋函式為無狀態的 (stateless)，且鍵函式會在使用過後被丟棄。因此，如果搜尋函" +"式被使用於迴圈當中，鍵函式會不斷被重複呼叫於相同的 list 元素。如果鍵函式執行" +"速度不快，請考慮將其以 :py:func:`functools.cache` 包裝起來以減少重複的計算。" +"另外，也可以透過搜尋預先計算好的鍵列表 (array of precomputed keys) 來定位插入" +"點（如下方範例所示）。" + +#: ../../library/bisect.rst:141 +msgid "" +"`Sorted Collections `_ is a " +"high performance module that uses *bisect* to managed sorted collections of " +"data." +msgstr "" +"`有序容器 (Sorted Collections) `_ 是一個使用 *bisect* 來管理資料之有序集合的高效能模組。" + +#: ../../library/bisect.rst:145 +msgid "" +"The `SortedCollection recipe `_ uses bisect to build a full-featured collection class " +"with straight-forward search methods and support for a key-function. The " +"keys are precomputed to save unnecessary calls to the key function during " +"searches." +msgstr "" +"`SortedCollection recipe `_ 使用二分法來建立一個功能完整的集合類別 (collection " +"class) 並帶有符合直覺的搜尋方法 (search methods) 與支援鍵函式。鍵會預先被計算" +"好，以減少搜尋過程中多餘的鍵函式呼叫。" + +#: ../../library/bisect.rst:153 +msgid "Searching Sorted Lists" +msgstr "搜尋一個已排序的 list" + +#: ../../library/bisect.rst:155 +msgid "" +"The above `bisect functions`_ are useful for finding insertion points but " +"can be tricky or awkward to use for common searching tasks. The following " +"five functions show how to transform them into the standard lookups for " +"sorted lists::" +msgstr "" +"上面的 `bisect functions`_ 在找到數值插入點上很有用，但一般的數值搜尋任務上就" +"不是那麼的方便。以下的五個函式展示了如何將其轉換成標準的有序列表查找函式： ::" + +#: ../../library/bisect.rst:160 +msgid "" +"def index(a, x):\n" +" 'Locate the leftmost value exactly equal to x'\n" +" i = bisect_left(a, x)\n" +" if i != len(a) and a[i] == x:\n" +" return i\n" +" raise ValueError\n" +"\n" +"def find_lt(a, x):\n" +" 'Find rightmost value less than x'\n" +" i = bisect_left(a, x)\n" +" if i:\n" +" return a[i-1]\n" +" raise ValueError\n" +"\n" +"def find_le(a, x):\n" +" 'Find rightmost value less than or equal to x'\n" +" i = bisect_right(a, x)\n" +" if i:\n" +" return a[i-1]\n" +" raise ValueError\n" +"\n" +"def find_gt(a, x):\n" +" 'Find leftmost value greater than x'\n" +" i = bisect_right(a, x)\n" +" if i != len(a):\n" +" return a[i]\n" +" raise ValueError\n" +"\n" +"def find_ge(a, x):\n" +" 'Find leftmost item greater than or equal to x'\n" +" i = bisect_left(a, x)\n" +" if i != len(a):\n" +" return a[i]\n" +" raise ValueError" +msgstr "" + +#: ../../library/bisect.rst:197 +msgid "Examples" +msgstr "範例" + +#: ../../library/bisect.rst:201 +msgid "" +"The :py:func:`~bisect.bisect` function can be useful for numeric table " +"lookups. This example uses :py:func:`~bisect.bisect` to look up a letter " +"grade for an exam score (say) based on a set of ordered numeric breakpoints: " +"90 and up is an 'A', 80 to 89 is a 'B', and so on::" +msgstr "" +":py:func:`~bisect.bisect` 函式可用於數值表中的查找 (numeric table lookup)，這" +"個範例使用 :py:func:`~bisect.bisect` 以基於一組有序的數值分界點來為一個考試成" +"績找到相對應的字母等級：90 以上是 'A'、80 到 89 為 'B'，依此類推： ::" + +#: ../../library/bisect.rst:206 +msgid "" +">>> def grade(score, breakpoints=[60, 70, 80, 90], grades='FDCBA'):\n" +"... i = bisect(breakpoints, score)\n" +"... return grades[i]\n" +"...\n" +">>> [grade(score) for score in [33, 99, 77, 70, 89, 90, 100]]\n" +"['F', 'A', 'C', 'C', 'B', 'A', 'A']" +msgstr "" +">>> def grade(score, breakpoints=[60, 70, 80, 90], grades='FDCBA'):\n" +"... i = bisect(breakpoints, score)\n" +"... return grades[i]\n" +"...\n" +">>> [grade(score) for score in [33, 99, 77, 70, 89, 90, 100]]\n" +"['F', 'A', 'C', 'C', 'B', 'A', 'A']" + +#: ../../library/bisect.rst:213 +msgid "" +"The :py:func:`~bisect.bisect` and :py:func:`~bisect.insort` functions also " +"work with lists of tuples. The *key* argument can serve to extract the " +"field used for ordering records in a table::" +msgstr "" +":py:func:`~bisect.bisect` 與 :py:func:`~bisect.insort` 函式也適用於內容為 " +"tuples（元組）的 lists，*key* 引數可被用以取出在數值表中作為排序依據的欄" +"位： ::" + +#: ../../library/bisect.rst:217 +msgid "" +">>> from collections import namedtuple\n" +">>> from operator import attrgetter\n" +">>> from bisect import bisect, insort\n" +">>> from pprint import pprint\n" +"\n" +">>> Movie = namedtuple('Movie', ('name', 'released', 'director'))\n" +"\n" +">>> movies = [\n" +"... Movie('Jaws', 1975, 'Spielberg'),\n" +"... Movie('Titanic', 1997, 'Cameron'),\n" +"... Movie('The Birds', 1963, 'Hitchcock'),\n" +"... Movie('Aliens', 1986, 'Cameron')\n" +"... ]\n" +"\n" +">>> # Find the first movie released after 1960\n" +">>> by_year = attrgetter('released')\n" +">>> movies.sort(key=by_year)\n" +">>> movies[bisect(movies, 1960, key=by_year)]\n" +"Movie(name='The Birds', released=1963, director='Hitchcock')\n" +"\n" +">>> # Insert a movie while maintaining sort order\n" +">>> romance = Movie('Love Story', 1970, 'Hiller')\n" +">>> insort(movies, romance, key=by_year)\n" +">>> pprint(movies)\n" +"[Movie(name='The Birds', released=1963, director='Hitchcock'),\n" +" Movie(name='Love Story', released=1970, director='Hiller'),\n" +" Movie(name='Jaws', released=1975, director='Spielberg'),\n" +" Movie(name='Aliens', released=1986, director='Cameron'),\n" +" Movie(name='Titanic', released=1997, director='Cameron')]" +msgstr "" +">>> from collections import namedtuple\n" +">>> from operator import attrgetter\n" +">>> from bisect import bisect, insort\n" +">>> from pprint import pprint\n" +"\n" +">>> Movie = namedtuple('Movie', ('name', 'released', 'director'))\n" +"\n" +">>> movies = [\n" +"... Movie('Jaws', 1975, 'Spielberg'),\n" +"... Movie('Titanic', 1997, 'Cameron'),\n" +"... Movie('The Birds', 1963, 'Hitchcock'),\n" +"... Movie('Aliens', 1986, 'Cameron')\n" +"... ]\n" +"\n" +">>> # 找到 1960 年後上映的第一部電影\n" +">>> by_year = attrgetter('released')\n" +">>> movies.sort(key=by_year)\n" +">>> movies[bisect(movies, 1960, key=by_year)]\n" +"Movie(name='The Birds', released=1963, director='Hitchcock')\n" +"\n" +">>> # 插入一部電影並保持排序\n" +">>> romance = Movie('Love Story', 1970, 'Hiller')\n" +">>> insort(movies, romance, key=by_year)\n" +">>> pprint(movies)\n" +"[Movie(name='The Birds', released=1963, director='Hitchcock'),\n" +" Movie(name='Love Story', released=1970, director='Hiller'),\n" +" Movie(name='Jaws', released=1975, director='Spielberg'),\n" +" Movie(name='Aliens', released=1986, director='Cameron'),\n" +" Movie(name='Titanic', released=1997, director='Cameron')]" + +#: ../../library/bisect.rst:247 +msgid "" +"If the key function is expensive, it is possible to avoid repeated function " +"calls by searching a list of precomputed keys to find the index of a record::" +msgstr "" +"如果鍵函式會消耗較多運算資源，那可以在預先計算好的鍵列表中搜尋該紀錄的索引" +"值，以減少重複的函式呼叫： ::" + +#: ../../library/bisect.rst:250 +msgid "" +">>> data = [('red', 5), ('blue', 1), ('yellow', 8), ('black', 0)]\n" +">>> data.sort(key=lambda r: r[1]) # Or use operator.itemgetter(1).\n" +">>> keys = [r[1] for r in data] # Precompute a list of keys.\n" +">>> data[bisect_left(keys, 0)]\n" +"('black', 0)\n" +">>> data[bisect_left(keys, 1)]\n" +"('blue', 1)\n" +">>> data[bisect_left(keys, 5)]\n" +"('red', 5)\n" +">>> data[bisect_left(keys, 8)]\n" +"('yellow', 8)" +msgstr "" diff --git a/library/builtins.po b/library/builtins.po index 77bd54a9de..0e54ff681d 100644 --- a/library/builtins.po +++ b/library/builtins.po @@ -1,111 +1,111 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Adrian Liaw , 2018 -# Matt Wang , 2022-2024 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-10-22 00:13+0000\n" -"PO-Revision-Date: 2022-02-15 20:55+0800\n" -"Last-Translator: Matt Wang \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" -"X-Generator: Poedit 3.0.1\n" - -#: ../../library/builtins.rst:2 -msgid ":mod:`!builtins` --- Built-in objects" -msgstr ":mod:`!builtins` --- 內建物件" - -#: ../../library/builtins.rst:9 -msgid "" -"This module provides direct access to all 'built-in' identifiers of Python; " -"for example, ``builtins.open`` is the full name for the built-in function :" -"func:`open`." -msgstr "" -"該模組提供對 Python 所有'內建'識別符號的直接存取；例如 ``builtins.open`` 是內" -"建函式 :func:`open` 的全名。" - -#: ../../library/builtins.rst:12 -msgid "" -"This module is not normally accessed explicitly by most applications, but " -"can be useful in modules that provide objects with the same name as a built-" -"in value, but in which the built-in of that name is also needed. For " -"example, in a module that wants to implement an :func:`open` function that " -"wraps the built-in :func:`open`, this module can be used directly::" -msgstr "" -"大多數應用程式通常不會顯式地存取此模組，但在提供與內建值同名之物件的模組中可" -"能很有用，不過其中還會需要內建該名稱。例如，在一個將內建 :func:`open` 包裝起" -"來以實現另一版本 :func:`open` 函式的模組中，這個模組可以直接被使用： ::" - -#: ../../library/builtins.rst:18 -msgid "" -"import builtins\n" -"\n" -"def open(path):\n" -" f = builtins.open(path, 'r')\n" -" return UpperCaser(f)\n" -"\n" -"class UpperCaser:\n" -" '''Wrapper around a file that converts output to uppercase.'''\n" -"\n" -" def __init__(self, f):\n" -" self._f = f\n" -"\n" -" def read(self, count=-1):\n" -" return self._f.read(count).upper()\n" -"\n" -" # ..." -msgstr "" -"import builtins\n" -"\n" -"def open(path):\n" -" f = builtins.open(path, 'r')\n" -" return UpperCaser(f)\n" -"\n" -"class UpperCaser:\n" -" '''將輸出轉換成大寫的檔案包裝器'''\n" -"\n" -" def __init__(self, f):\n" -" self._f = f\n" -"\n" -" def read(self, count=-1):\n" -" return self._f.read(count).upper()\n" -"\n" -" # ..." - -#: ../../library/builtins.rst:35 -msgid "" -"As an implementation detail, most modules have the name ``__builtins__`` " -"made available as part of their globals. The value of ``__builtins__`` is " -"normally either this module or the value of this module's :attr:`~object." -"__dict__` attribute. Since this is an implementation detail, it may not be " -"used by alternate implementations of Python." -msgstr "" -"有個實作細節是，大多數模組都將名稱 ``__builtins__`` 作為其全域性變數的一部分" -"以提使用。``__builtins__`` 的值通常是這個模組或者這個模組的 :attr:`~object." -"__dict__` 屬性值。由於這是一個實作細節，因此 Python 的其他實作可能不會使用" -"它。" - -#: ../../library/builtins.rst:43 -msgid ":ref:`built-in-consts`" -msgstr ":ref:`built-in-consts`" - -#: ../../library/builtins.rst:44 -msgid ":ref:`bltin-exceptions`" -msgstr ":ref:`bltin-exceptions`" - -#: ../../library/builtins.rst:45 -msgid ":ref:`built-in-funcs`" -msgstr ":ref:`built-in-funcs`" - -#: ../../library/builtins.rst:46 -msgid ":ref:`bltin-types`" -msgstr ":ref:`bltin-types`" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Adrian Liaw , 2018 +# Matt Wang , 2022-2024 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-10-22 00:13+0000\n" +"PO-Revision-Date: 2022-02-15 20:55+0800\n" +"Last-Translator: Matt Wang \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" +"X-Generator: Poedit 3.0.1\n" + +#: ../../library/builtins.rst:2 +msgid ":mod:`!builtins` --- Built-in objects" +msgstr ":mod:`!builtins` --- 內建物件" + +#: ../../library/builtins.rst:9 +msgid "" +"This module provides direct access to all 'built-in' identifiers of Python; " +"for example, ``builtins.open`` is the full name for the built-in function :" +"func:`open`." +msgstr "" +"該模組提供對 Python 所有'內建'識別符號的直接存取；例如 ``builtins.open`` 是內" +"建函式 :func:`open` 的全名。" + +#: ../../library/builtins.rst:12 +msgid "" +"This module is not normally accessed explicitly by most applications, but " +"can be useful in modules that provide objects with the same name as a built-" +"in value, but in which the built-in of that name is also needed. For " +"example, in a module that wants to implement an :func:`open` function that " +"wraps the built-in :func:`open`, this module can be used directly::" +msgstr "" +"大多數應用程式通常不會顯式地存取此模組，但在提供與內建值同名之物件的模組中可" +"能很有用，不過其中還會需要內建該名稱。例如，在一個將內建 :func:`open` 包裝起" +"來以實現另一版本 :func:`open` 函式的模組中，這個模組可以直接被使用： ::" + +#: ../../library/builtins.rst:18 +msgid "" +"import builtins\n" +"\n" +"def open(path):\n" +" f = builtins.open(path, 'r')\n" +" return UpperCaser(f)\n" +"\n" +"class UpperCaser:\n" +" '''Wrapper around a file that converts output to uppercase.'''\n" +"\n" +" def __init__(self, f):\n" +" self._f = f\n" +"\n" +" def read(self, count=-1):\n" +" return self._f.read(count).upper()\n" +"\n" +" # ..." +msgstr "" +"import builtins\n" +"\n" +"def open(path):\n" +" f = builtins.open(path, 'r')\n" +" return UpperCaser(f)\n" +"\n" +"class UpperCaser:\n" +" '''將輸出轉換成大寫的檔案包裝器'''\n" +"\n" +" def __init__(self, f):\n" +" self._f = f\n" +"\n" +" def read(self, count=-1):\n" +" return self._f.read(count).upper()\n" +"\n" +" # ..." + +#: ../../library/builtins.rst:35 +msgid "" +"As an implementation detail, most modules have the name ``__builtins__`` " +"made available as part of their globals. The value of ``__builtins__`` is " +"normally either this module or the value of this module's :attr:`~object." +"__dict__` attribute. Since this is an implementation detail, it may not be " +"used by alternate implementations of Python." +msgstr "" +"有個實作細節是，大多數模組都將名稱 ``__builtins__`` 作為其全域性變數的一部分" +"以提使用。``__builtins__`` 的值通常是這個模組或者這個模組的 :attr:`~object." +"__dict__` 屬性值。由於這是一個實作細節，因此 Python 的其他實作可能不會使用" +"它。" + +#: ../../library/builtins.rst:43 +msgid ":ref:`built-in-consts`" +msgstr ":ref:`built-in-consts`" + +#: ../../library/builtins.rst:44 +msgid ":ref:`bltin-exceptions`" +msgstr ":ref:`bltin-exceptions`" + +#: ../../library/builtins.rst:45 +msgid ":ref:`built-in-funcs`" +msgstr ":ref:`built-in-funcs`" + +#: ../../library/builtins.rst:46 +msgid ":ref:`bltin-types`" +msgstr ":ref:`bltin-types`" diff --git a/library/bz2.po b/library/bz2.po index 206e116b50..119bfcaaf5 100644 --- a/library/bz2.po +++ b/library/bz2.po @@ -1,432 +1,432 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-10 16:45+0000\n" -"PO-Revision-Date: 2018-05-23 14:40+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/bz2.rst:2 -msgid ":mod:`!bz2` --- Support for :program:`bzip2` compression" -msgstr ":mod:`!bz2` --- :program:`bzip2` 壓縮的支援" - -#: ../../library/bz2.rst:12 -msgid "**Source code:** :source:`Lib/bz2.py`" -msgstr "**原始碼：**\\ :source:`Lib/bz2.py`" - -#: ../../library/bz2.rst:16 -msgid "" -"This module provides a comprehensive interface for compressing and " -"decompressing data using the bzip2 compression algorithm." -msgstr "" - -#: ../../library/bz2.rst:19 -msgid "The :mod:`bz2` module contains:" -msgstr ":mod:`bz2` 模組包含：" - -#: ../../library/bz2.rst:21 -msgid "" -"The :func:`.open` function and :class:`BZ2File` class for reading and " -"writing compressed files." -msgstr "" - -#: ../../library/bz2.rst:23 -msgid "" -"The :class:`BZ2Compressor` and :class:`BZ2Decompressor` classes for " -"incremental (de)compression." -msgstr "" - -#: ../../library/bz2.rst:25 -msgid "" -"The :func:`compress` and :func:`decompress` functions for one-shot " -"(de)compression." -msgstr "" - -#: ../../includes/optional-module.rst:1 -msgid "" -"This is an :term:`optional module`. If it is missing from your copy of " -"CPython, look for documentation from your distributor (that is, whoever " -"provided Python to you). If you are the distributor, see :ref:`optional-" -"module-requirements`." -msgstr "" - -#: ../../library/bz2.rst:32 -msgid "(De)compression of files" -msgstr "" - -#: ../../library/bz2.rst:36 -msgid "" -"Open a bzip2-compressed file in binary or text mode, returning a :term:`file " -"object`." -msgstr "" - -#: ../../library/bz2.rst:39 -msgid "" -"As with the constructor for :class:`BZ2File`, the *filename* argument can be " -"an actual filename (a :class:`str` or :class:`bytes` object), or an existing " -"file object to read from or write to." -msgstr "" - -#: ../../library/bz2.rst:43 -msgid "" -"The *mode* argument can be any of ``'r'``, ``'rb'``, ``'w'``, ``'wb'``, " -"``'x'``, ``'xb'``, ``'a'`` or ``'ab'`` for binary mode, or ``'rt'``, " -"``'wt'``, ``'xt'``, or ``'at'`` for text mode. The default is ``'rb'``." -msgstr "" - -#: ../../library/bz2.rst:47 -msgid "" -"The *compresslevel* argument is an integer from 1 to 9, as for the :class:" -"`BZ2File` constructor." -msgstr "" - -#: ../../library/bz2.rst:50 -msgid "" -"For binary mode, this function is equivalent to the :class:`BZ2File` " -"constructor: ``BZ2File(filename, mode, compresslevel=compresslevel)``. In " -"this case, the *encoding*, *errors* and *newline* arguments must not be " -"provided." -msgstr "" - -#: ../../library/bz2.rst:55 -msgid "" -"For text mode, a :class:`BZ2File` object is created, and wrapped in an :" -"class:`io.TextIOWrapper` instance with the specified encoding, error " -"handling behavior, and line ending(s)." -msgstr "" - -#: ../../library/bz2.rst:61 ../../library/bz2.rst:177 -msgid "The ``'x'`` (exclusive creation) mode was added." -msgstr "" - -#: ../../library/bz2.rst:64 ../../library/bz2.rst:184 -msgid "Accepts a :term:`path-like object`." -msgstr "" - -#: ../../library/bz2.rst:70 -msgid "Open a bzip2-compressed file in binary mode." -msgstr "" - -#: ../../library/bz2.rst:72 -msgid "" -"If *filename* is a :class:`str` or :class:`bytes` object, open the named " -"file directly. Otherwise, *filename* should be a :term:`file object`, which " -"will be used to read or write the compressed data." -msgstr "" - -#: ../../library/bz2.rst:76 -msgid "" -"The *mode* argument can be either ``'r'`` for reading (default), ``'w'`` for " -"overwriting, ``'x'`` for exclusive creation, or ``'a'`` for appending. These " -"can equivalently be given as ``'rb'``, ``'wb'``, ``'xb'`` and ``'ab'`` " -"respectively." -msgstr "" - -#: ../../library/bz2.rst:81 -msgid "" -"If *filename* is a file object (rather than an actual file name), a mode of " -"``'w'`` does not truncate the file, and is instead equivalent to ``'a'``." -msgstr "" - -#: ../../library/bz2.rst:84 -msgid "" -"If *mode* is ``'w'`` or ``'a'``, *compresslevel* can be an integer between " -"``1`` and ``9`` specifying the level of compression: ``1`` produces the " -"least compression, and ``9`` (default) produces the most compression." -msgstr "" - -#: ../../library/bz2.rst:88 -msgid "" -"If *mode* is ``'r'``, the input file may be the concatenation of multiple " -"compressed streams." -msgstr "" - -#: ../../library/bz2.rst:91 -msgid "" -":class:`BZ2File` provides all of the members specified by the :class:`io." -"BufferedIOBase`, except for :meth:`~io.BufferedIOBase.detach` and :meth:`~io." -"IOBase.truncate`. Iteration and the :keyword:`with` statement are supported." -msgstr "" - -#: ../../library/bz2.rst:96 -msgid ":class:`BZ2File` also provides the following methods and attributes:" -msgstr ":class:`BZ2File` 也提供了以下方法和屬性：" - -#: ../../library/bz2.rst:100 -msgid "" -"Return buffered data without advancing the file position. At least one byte " -"of data will be returned (unless at EOF). The exact number of bytes returned " -"is unspecified." -msgstr "" - -#: ../../library/bz2.rst:104 -msgid "" -"While calling :meth:`peek` does not change the file position of the :class:" -"`BZ2File`, it may change the position of the underlying file object (e.g. if " -"the :class:`BZ2File` was constructed by passing a file object for " -"*filename*)." -msgstr "" - -#: ../../library/bz2.rst:113 -msgid "Return the file descriptor for the underlying file." -msgstr "" - -#: ../../library/bz2.rst:119 -msgid "Return whether the file was opened for reading." -msgstr "" - -#: ../../library/bz2.rst:125 -msgid "Return whether the file supports seeking." -msgstr "" - -#: ../../library/bz2.rst:131 -msgid "Return whether the file was opened for writing." -msgstr "" - -#: ../../library/bz2.rst:137 -msgid "" -"Read up to *size* uncompressed bytes, while trying to avoid making multiple " -"reads from the underlying stream. Reads up to a buffer's worth of data if " -"size is negative." -msgstr "" - -#: ../../library/bz2.rst:141 -msgid "Returns ``b''`` if the file is at EOF." -msgstr "" - -#: ../../library/bz2.rst:147 -msgid "Read bytes into *b*." -msgstr "" - -#: ../../library/bz2.rst:149 -msgid "Returns the number of bytes read (0 for EOF)." -msgstr "" - -#: ../../library/bz2.rst:155 -msgid "``'rb'`` for reading and ``'wb'`` for writing." -msgstr "" - -#: ../../library/bz2.rst:161 -msgid "" -"The bzip2 file name. Equivalent to the :attr:`~io.FileIO.name` attribute of " -"the underlying :term:`file object`." -msgstr "" - -#: ../../library/bz2.rst:167 -msgid "Support for the :keyword:`with` statement was added." -msgstr "" - -#: ../../library/bz2.rst:170 -msgid "" -"Support was added for *filename* being a :term:`file object` instead of an " -"actual filename." -msgstr "" - -#: ../../library/bz2.rst:174 -msgid "" -"The ``'a'`` (append) mode was added, along with support for reading multi-" -"stream files." -msgstr "" - -#: ../../library/bz2.rst:180 -msgid "" -"The :meth:`~io.BufferedIOBase.read` method now accepts an argument of " -"``None``." -msgstr "" - -#: ../../library/bz2.rst:187 -msgid "" -"The *buffering* parameter has been removed. It was ignored and deprecated " -"since Python 3.0. Pass an open file object to control how the file is opened." -msgstr "" - -#: ../../library/bz2.rst:192 -msgid "The *compresslevel* parameter became keyword-only." -msgstr "" - -#: ../../library/bz2.rst:194 -msgid "" -"This class is thread unsafe in the face of multiple simultaneous readers or " -"writers, just like its equivalent classes in :mod:`gzip` and :mod:`lzma` " -"have always been." -msgstr "" - -#: ../../library/bz2.rst:201 -msgid "Incremental (de)compression" -msgstr "" - -#: ../../library/bz2.rst:205 -msgid "" -"Create a new compressor object. This object may be used to compress data " -"incrementally. For one-shot compression, use the :func:`compress` function " -"instead." -msgstr "" - -#: ../../library/bz2.rst:209 ../../library/bz2.rst:297 -msgid "" -"*compresslevel*, if given, must be an integer between ``1`` and ``9``. The " -"default is ``9``." -msgstr "" - -#: ../../library/bz2.rst:214 -msgid "" -"Provide data to the compressor object. Returns a chunk of compressed data if " -"possible, or an empty byte string otherwise." -msgstr "" - -#: ../../library/bz2.rst:217 -msgid "" -"When you have finished providing data to the compressor, call the :meth:" -"`flush` method to finish the compression process." -msgstr "" - -#: ../../library/bz2.rst:223 -msgid "" -"Finish the compression process. Returns the compressed data left in internal " -"buffers." -msgstr "" - -#: ../../library/bz2.rst:226 -msgid "" -"The compressor object may not be used after this method has been called." -msgstr "" - -#: ../../library/bz2.rst:231 -msgid "" -"Create a new decompressor object. This object may be used to decompress data " -"incrementally. For one-shot compression, use the :func:`decompress` function " -"instead." -msgstr "" - -#: ../../library/bz2.rst:236 -msgid "" -"This class does not transparently handle inputs containing multiple " -"compressed streams, unlike :func:`decompress` and :class:`BZ2File`. If you " -"need to decompress a multi-stream input with :class:`BZ2Decompressor`, you " -"must use a new decompressor for each stream." -msgstr "" - -#: ../../library/bz2.rst:243 -msgid "" -"Decompress *data* (a :term:`bytes-like object`), returning uncompressed data " -"as bytes. Some of *data* may be buffered internally, for use in later calls " -"to :meth:`decompress`. The returned data should be concatenated with the " -"output of any previous calls to :meth:`decompress`." -msgstr "" - -#: ../../library/bz2.rst:249 -msgid "" -"If *max_length* is nonnegative, returns at most *max_length* bytes of " -"decompressed data. If this limit is reached and further output can be " -"produced, the :attr:`~.needs_input` attribute will be set to ``False``. In " -"this case, the next call to :meth:`~.decompress` may provide *data* as " -"``b''`` to obtain more of the output." -msgstr "" - -#: ../../library/bz2.rst:256 -msgid "" -"If all of the input data was decompressed and returned (either because this " -"was less than *max_length* bytes, or because *max_length* was negative), " -"the :attr:`~.needs_input` attribute will be set to ``True``." -msgstr "" - -#: ../../library/bz2.rst:261 -msgid "" -"Attempting to decompress data after the end of stream is reached raises an :" -"exc:`EOFError`. Any data found after the end of the stream is ignored and " -"saved in the :attr:`~.unused_data` attribute." -msgstr "" - -#: ../../library/bz2.rst:265 -msgid "Added the *max_length* parameter." -msgstr "新增 *max_length* 參數。" - -#: ../../library/bz2.rst:270 -msgid "``True`` if the end-of-stream marker has been reached." -msgstr "" - -#: ../../library/bz2.rst:277 -msgid "Data found after the end of the compressed stream." -msgstr "" - -#: ../../library/bz2.rst:279 -msgid "" -"If this attribute is accessed before the end of the stream has been reached, " -"its value will be ``b''``." -msgstr "" - -#: ../../library/bz2.rst:284 -msgid "" -"``False`` if the :meth:`.decompress` method can provide more decompressed " -"data before requiring new uncompressed input." -msgstr "" - -#: ../../library/bz2.rst:291 -msgid "One-shot (de)compression" -msgstr "" - -#: ../../library/bz2.rst:295 -msgid "Compress *data*, a :term:`bytes-like object `." -msgstr "" - -#: ../../library/bz2.rst:300 -msgid "For incremental compression, use a :class:`BZ2Compressor` instead." -msgstr "" - -#: ../../library/bz2.rst:305 -msgid "Decompress *data*, a :term:`bytes-like object `." -msgstr "" - -#: ../../library/bz2.rst:307 -msgid "" -"If *data* is the concatenation of multiple compressed streams, decompress " -"all of the streams." -msgstr "" - -#: ../../library/bz2.rst:310 -msgid "For incremental decompression, use a :class:`BZ2Decompressor` instead." -msgstr "" - -#: ../../library/bz2.rst:312 -msgid "Support for multi-stream inputs was added." -msgstr "" - -#: ../../library/bz2.rst:318 -msgid "Examples of usage" -msgstr "用法範例" - -#: ../../library/bz2.rst:320 -msgid "Below are some examples of typical usage of the :mod:`bz2` module." -msgstr "" - -#: ../../library/bz2.rst:322 -msgid "" -"Using :func:`compress` and :func:`decompress` to demonstrate round-trip " -"compression:" -msgstr "" - -#: ../../library/bz2.rst:340 -msgid "Using :class:`BZ2Compressor` for incremental compression:" -msgstr "" - -#: ../../library/bz2.rst:358 -msgid "" -"The example above uses a very \"nonrandom\" stream of data (a stream of " -"``b\"z\"`` chunks). Random data tends to compress poorly, while ordered, " -"repetitive data usually yields a high compression ratio." -msgstr "" - -#: ../../library/bz2.rst:362 -msgid "Writing and reading a bzip2-compressed file in binary mode:" -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-10 16:45+0000\n" +"PO-Revision-Date: 2018-05-23 14:40+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/bz2.rst:2 +msgid ":mod:`!bz2` --- Support for :program:`bzip2` compression" +msgstr ":mod:`!bz2` --- :program:`bzip2` 壓縮的支援" + +#: ../../library/bz2.rst:12 +msgid "**Source code:** :source:`Lib/bz2.py`" +msgstr "**原始碼：**\\ :source:`Lib/bz2.py`" + +#: ../../library/bz2.rst:16 +msgid "" +"This module provides a comprehensive interface for compressing and " +"decompressing data using the bzip2 compression algorithm." +msgstr "" + +#: ../../library/bz2.rst:19 +msgid "The :mod:`bz2` module contains:" +msgstr ":mod:`bz2` 模組包含：" + +#: ../../library/bz2.rst:21 +msgid "" +"The :func:`.open` function and :class:`BZ2File` class for reading and " +"writing compressed files." +msgstr "" + +#: ../../library/bz2.rst:23 +msgid "" +"The :class:`BZ2Compressor` and :class:`BZ2Decompressor` classes for " +"incremental (de)compression." +msgstr "" + +#: ../../library/bz2.rst:25 +msgid "" +"The :func:`compress` and :func:`decompress` functions for one-shot " +"(de)compression." +msgstr "" + +#: ../../includes/optional-module.rst:1 +msgid "" +"This is an :term:`optional module`. If it is missing from your copy of " +"CPython, look for documentation from your distributor (that is, whoever " +"provided Python to you). If you are the distributor, see :ref:`optional-" +"module-requirements`." +msgstr "" + +#: ../../library/bz2.rst:32 +msgid "(De)compression of files" +msgstr "" + +#: ../../library/bz2.rst:36 +msgid "" +"Open a bzip2-compressed file in binary or text mode, returning a :term:`file " +"object`." +msgstr "" + +#: ../../library/bz2.rst:39 +msgid "" +"As with the constructor for :class:`BZ2File`, the *filename* argument can be " +"an actual filename (a :class:`str` or :class:`bytes` object), or an existing " +"file object to read from or write to." +msgstr "" + +#: ../../library/bz2.rst:43 +msgid "" +"The *mode* argument can be any of ``'r'``, ``'rb'``, ``'w'``, ``'wb'``, " +"``'x'``, ``'xb'``, ``'a'`` or ``'ab'`` for binary mode, or ``'rt'``, " +"``'wt'``, ``'xt'``, or ``'at'`` for text mode. The default is ``'rb'``." +msgstr "" + +#: ../../library/bz2.rst:47 +msgid "" +"The *compresslevel* argument is an integer from 1 to 9, as for the :class:" +"`BZ2File` constructor." +msgstr "" + +#: ../../library/bz2.rst:50 +msgid "" +"For binary mode, this function is equivalent to the :class:`BZ2File` " +"constructor: ``BZ2File(filename, mode, compresslevel=compresslevel)``. In " +"this case, the *encoding*, *errors* and *newline* arguments must not be " +"provided." +msgstr "" + +#: ../../library/bz2.rst:55 +msgid "" +"For text mode, a :class:`BZ2File` object is created, and wrapped in an :" +"class:`io.TextIOWrapper` instance with the specified encoding, error " +"handling behavior, and line ending(s)." +msgstr "" + +#: ../../library/bz2.rst:61 ../../library/bz2.rst:177 +msgid "The ``'x'`` (exclusive creation) mode was added." +msgstr "" + +#: ../../library/bz2.rst:64 ../../library/bz2.rst:184 +msgid "Accepts a :term:`path-like object`." +msgstr "" + +#: ../../library/bz2.rst:70 +msgid "Open a bzip2-compressed file in binary mode." +msgstr "" + +#: ../../library/bz2.rst:72 +msgid "" +"If *filename* is a :class:`str` or :class:`bytes` object, open the named " +"file directly. Otherwise, *filename* should be a :term:`file object`, which " +"will be used to read or write the compressed data." +msgstr "" + +#: ../../library/bz2.rst:76 +msgid "" +"The *mode* argument can be either ``'r'`` for reading (default), ``'w'`` for " +"overwriting, ``'x'`` for exclusive creation, or ``'a'`` for appending. These " +"can equivalently be given as ``'rb'``, ``'wb'``, ``'xb'`` and ``'ab'`` " +"respectively." +msgstr "" + +#: ../../library/bz2.rst:81 +msgid "" +"If *filename* is a file object (rather than an actual file name), a mode of " +"``'w'`` does not truncate the file, and is instead equivalent to ``'a'``." +msgstr "" + +#: ../../library/bz2.rst:84 +msgid "" +"If *mode* is ``'w'`` or ``'a'``, *compresslevel* can be an integer between " +"``1`` and ``9`` specifying the level of compression: ``1`` produces the " +"least compression, and ``9`` (default) produces the most compression." +msgstr "" + +#: ../../library/bz2.rst:88 +msgid "" +"If *mode* is ``'r'``, the input file may be the concatenation of multiple " +"compressed streams." +msgstr "" + +#: ../../library/bz2.rst:91 +msgid "" +":class:`BZ2File` provides all of the members specified by the :class:`io." +"BufferedIOBase`, except for :meth:`~io.BufferedIOBase.detach` and :meth:`~io." +"IOBase.truncate`. Iteration and the :keyword:`with` statement are supported." +msgstr "" + +#: ../../library/bz2.rst:96 +msgid ":class:`BZ2File` also provides the following methods and attributes:" +msgstr ":class:`BZ2File` 也提供了以下方法和屬性：" + +#: ../../library/bz2.rst:100 +msgid "" +"Return buffered data without advancing the file position. At least one byte " +"of data will be returned (unless at EOF). The exact number of bytes returned " +"is unspecified." +msgstr "" + +#: ../../library/bz2.rst:104 +msgid "" +"While calling :meth:`peek` does not change the file position of the :class:" +"`BZ2File`, it may change the position of the underlying file object (e.g. if " +"the :class:`BZ2File` was constructed by passing a file object for " +"*filename*)." +msgstr "" + +#: ../../library/bz2.rst:113 +msgid "Return the file descriptor for the underlying file." +msgstr "" + +#: ../../library/bz2.rst:119 +msgid "Return whether the file was opened for reading." +msgstr "" + +#: ../../library/bz2.rst:125 +msgid "Return whether the file supports seeking." +msgstr "" + +#: ../../library/bz2.rst:131 +msgid "Return whether the file was opened for writing." +msgstr "" + +#: ../../library/bz2.rst:137 +msgid "" +"Read up to *size* uncompressed bytes, while trying to avoid making multiple " +"reads from the underlying stream. Reads up to a buffer's worth of data if " +"size is negative." +msgstr "" + +#: ../../library/bz2.rst:141 +msgid "Returns ``b''`` if the file is at EOF." +msgstr "" + +#: ../../library/bz2.rst:147 +msgid "Read bytes into *b*." +msgstr "" + +#: ../../library/bz2.rst:149 +msgid "Returns the number of bytes read (0 for EOF)." +msgstr "" + +#: ../../library/bz2.rst:155 +msgid "``'rb'`` for reading and ``'wb'`` for writing." +msgstr "" + +#: ../../library/bz2.rst:161 +msgid "" +"The bzip2 file name. Equivalent to the :attr:`~io.FileIO.name` attribute of " +"the underlying :term:`file object`." +msgstr "" + +#: ../../library/bz2.rst:167 +msgid "Support for the :keyword:`with` statement was added." +msgstr "" + +#: ../../library/bz2.rst:170 +msgid "" +"Support was added for *filename* being a :term:`file object` instead of an " +"actual filename." +msgstr "" + +#: ../../library/bz2.rst:174 +msgid "" +"The ``'a'`` (append) mode was added, along with support for reading multi-" +"stream files." +msgstr "" + +#: ../../library/bz2.rst:180 +msgid "" +"The :meth:`~io.BufferedIOBase.read` method now accepts an argument of " +"``None``." +msgstr "" + +#: ../../library/bz2.rst:187 +msgid "" +"The *buffering* parameter has been removed. It was ignored and deprecated " +"since Python 3.0. Pass an open file object to control how the file is opened." +msgstr "" + +#: ../../library/bz2.rst:192 +msgid "The *compresslevel* parameter became keyword-only." +msgstr "" + +#: ../../library/bz2.rst:194 +msgid "" +"This class is thread unsafe in the face of multiple simultaneous readers or " +"writers, just like its equivalent classes in :mod:`gzip` and :mod:`lzma` " +"have always been." +msgstr "" + +#: ../../library/bz2.rst:201 +msgid "Incremental (de)compression" +msgstr "" + +#: ../../library/bz2.rst:205 +msgid "" +"Create a new compressor object. This object may be used to compress data " +"incrementally. For one-shot compression, use the :func:`compress` function " +"instead." +msgstr "" + +#: ../../library/bz2.rst:209 ../../library/bz2.rst:297 +msgid "" +"*compresslevel*, if given, must be an integer between ``1`` and ``9``. The " +"default is ``9``." +msgstr "" + +#: ../../library/bz2.rst:214 +msgid "" +"Provide data to the compressor object. Returns a chunk of compressed data if " +"possible, or an empty byte string otherwise." +msgstr "" + +#: ../../library/bz2.rst:217 +msgid "" +"When you have finished providing data to the compressor, call the :meth:" +"`flush` method to finish the compression process." +msgstr "" + +#: ../../library/bz2.rst:223 +msgid "" +"Finish the compression process. Returns the compressed data left in internal " +"buffers." +msgstr "" + +#: ../../library/bz2.rst:226 +msgid "" +"The compressor object may not be used after this method has been called." +msgstr "" + +#: ../../library/bz2.rst:231 +msgid "" +"Create a new decompressor object. This object may be used to decompress data " +"incrementally. For one-shot compression, use the :func:`decompress` function " +"instead." +msgstr "" + +#: ../../library/bz2.rst:236 +msgid "" +"This class does not transparently handle inputs containing multiple " +"compressed streams, unlike :func:`decompress` and :class:`BZ2File`. If you " +"need to decompress a multi-stream input with :class:`BZ2Decompressor`, you " +"must use a new decompressor for each stream." +msgstr "" + +#: ../../library/bz2.rst:243 +msgid "" +"Decompress *data* (a :term:`bytes-like object`), returning uncompressed data " +"as bytes. Some of *data* may be buffered internally, for use in later calls " +"to :meth:`decompress`. The returned data should be concatenated with the " +"output of any previous calls to :meth:`decompress`." +msgstr "" + +#: ../../library/bz2.rst:249 +msgid "" +"If *max_length* is nonnegative, returns at most *max_length* bytes of " +"decompressed data. If this limit is reached and further output can be " +"produced, the :attr:`~.needs_input` attribute will be set to ``False``. In " +"this case, the next call to :meth:`~.decompress` may provide *data* as " +"``b''`` to obtain more of the output." +msgstr "" + +#: ../../library/bz2.rst:256 +msgid "" +"If all of the input data was decompressed and returned (either because this " +"was less than *max_length* bytes, or because *max_length* was negative), " +"the :attr:`~.needs_input` attribute will be set to ``True``." +msgstr "" + +#: ../../library/bz2.rst:261 +msgid "" +"Attempting to decompress data after the end of stream is reached raises an :" +"exc:`EOFError`. Any data found after the end of the stream is ignored and " +"saved in the :attr:`~.unused_data` attribute." +msgstr "" + +#: ../../library/bz2.rst:265 +msgid "Added the *max_length* parameter." +msgstr "新增 *max_length* 參數。" + +#: ../../library/bz2.rst:270 +msgid "``True`` if the end-of-stream marker has been reached." +msgstr "" + +#: ../../library/bz2.rst:277 +msgid "Data found after the end of the compressed stream." +msgstr "" + +#: ../../library/bz2.rst:279 +msgid "" +"If this attribute is accessed before the end of the stream has been reached, " +"its value will be ``b''``." +msgstr "" + +#: ../../library/bz2.rst:284 +msgid "" +"``False`` if the :meth:`.decompress` method can provide more decompressed " +"data before requiring new uncompressed input." +msgstr "" + +#: ../../library/bz2.rst:291 +msgid "One-shot (de)compression" +msgstr "" + +#: ../../library/bz2.rst:295 +msgid "Compress *data*, a :term:`bytes-like object `." +msgstr "" + +#: ../../library/bz2.rst:300 +msgid "For incremental compression, use a :class:`BZ2Compressor` instead." +msgstr "" + +#: ../../library/bz2.rst:305 +msgid "Decompress *data*, a :term:`bytes-like object `." +msgstr "" + +#: ../../library/bz2.rst:307 +msgid "" +"If *data* is the concatenation of multiple compressed streams, decompress " +"all of the streams." +msgstr "" + +#: ../../library/bz2.rst:310 +msgid "For incremental decompression, use a :class:`BZ2Decompressor` instead." +msgstr "" + +#: ../../library/bz2.rst:312 +msgid "Support for multi-stream inputs was added." +msgstr "" + +#: ../../library/bz2.rst:318 +msgid "Examples of usage" +msgstr "用法範例" + +#: ../../library/bz2.rst:320 +msgid "Below are some examples of typical usage of the :mod:`bz2` module." +msgstr "" + +#: ../../library/bz2.rst:322 +msgid "" +"Using :func:`compress` and :func:`decompress` to demonstrate round-trip " +"compression:" +msgstr "" + +#: ../../library/bz2.rst:340 +msgid "Using :class:`BZ2Compressor` for incremental compression:" +msgstr "" + +#: ../../library/bz2.rst:358 +msgid "" +"The example above uses a very \"nonrandom\" stream of data (a stream of " +"``b\"z\"`` chunks). Random data tends to compress poorly, while ordered, " +"repetitive data usually yields a high compression ratio." +msgstr "" + +#: ../../library/bz2.rst:362 +msgid "Writing and reading a bzip2-compressed file in binary mode:" +msgstr "" diff --git a/library/calendar.po b/library/calendar.po index 1a974b314f..598d93d218 100644 --- a/library/calendar.po +++ b/library/calendar.po @@ -1,895 +1,895 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: 2018-05-23 14:40+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/calendar.rst:2 -msgid ":mod:`!calendar` --- General calendar-related functions" -msgstr ":mod:`!calendar` --- 日曆相關函式" - -#: ../../library/calendar.rst:10 -msgid "**Source code:** :source:`Lib/calendar.py`" -msgstr "**原始碼：**\\ :source:`Lib/calendar.py`" - -#: ../../library/calendar.rst:14 -msgid "" -"This module allows you to output calendars like the Unix :program:`cal` " -"program, and provides additional useful functions related to the calendar. " -"By default, these calendars have Monday as the first day of the week, and " -"Sunday as the last (the European convention). Use :func:`setfirstweekday` to " -"set the first day of the week to Sunday (6) or to any other weekday. " -"Parameters that specify dates are given as integers. For related " -"functionality, see also the :mod:`datetime` and :mod:`time` modules." -msgstr "" -"這個模組讓你可以像 Unix 的 :program:`cal` 程式一樣輸出日曆，並額外提供有用的" -"日曆相關函式。這些日曆預設把週一當作一週的第一天，而週日當作最後一天（歐洲的" -"慣例）。可以使用 :func:`setfirstweekday` 設定一週的第一天為週日 (6) 或一週的" -"其它任一天，其中指定日期的參數是整數。相關功能參考 :mod:`datetime` " -"和 :mod:`time` 模組。" - -#: ../../library/calendar.rst:22 -msgid "" -"The functions and classes defined in this module use an idealized calendar, " -"the current Gregorian calendar extended indefinitely in both directions. " -"This matches the definition of the \"proleptic Gregorian\" calendar in " -"Dershowitz and Reingold's book \"Calendrical Calculations\", where it's the " -"base calendar for all computations. Zero and negative years are interpreted " -"as prescribed by the ISO 8601 standard. Year 0 is 1 BC, year -1 is 2 BC, " -"and so on." -msgstr "" -"這個模組定義的函式和類別使用理想化的日曆，也就是公曆 (Gregorian calendar) 無" -"限往前後兩個方向延伸。這符合 Dershowitz 和 Reingold 在「Calendrical " -"Calculations」這本書定義的「逆推公曆」(proleptic Gregorian)，是做所有計算的基" -"礎日曆。0 及負數年份的解讀跟 ISO 8601 標準裡規定的一樣，0 年是公元前 1 " -"年，-1 年是公元前 2 年依此類推。" - -#: ../../library/calendar.rst:33 -msgid "" -"Creates a :class:`Calendar` object. *firstweekday* is an integer specifying " -"the first day of the week. :const:`MONDAY` is ``0`` (the " -"default), :const:`SUNDAY` is ``6``." -msgstr "" -"建立 :class:`Calendar` 物件。*firstweekday* 是一個指定一週第一天的整" -"數，:const:`MONDAY` 是 ``0``\\ （預設值），:const:`SUNDAY` 是 ``6``。" - -#: ../../library/calendar.rst:36 -msgid "" -"A :class:`Calendar` object provides several methods that can be used for " -"preparing the calendar data for formatting. This class doesn't do any " -"formatting itself. This is the job of subclasses." -msgstr "" -":class:`Calendar` 物件提供一些方法來為日曆資料的格式化做準備。這個類別本身不" -"做任何格式化，這是子類別的工作。" - -#: ../../library/calendar.rst:41 -msgid ":class:`Calendar` instances have the following methods and attributes:" -msgstr ":class:`Calendar` 實例有以下方法與屬性：" - -#: ../../library/calendar.rst:45 -msgid "The first weekday as an integer (0--6)." -msgstr "" - -#: ../../library/calendar.rst:47 -msgid "" -"This property can also be set and read " -"using :meth:`~Calendar.setfirstweekday` " -"and :meth:`~Calendar.getfirstweekday` respectively." -msgstr "" - -#: ../../library/calendar.rst:53 -msgid "Return an :class:`int` for the current first weekday (0--6)." -msgstr "" - -#: ../../library/calendar.rst:55 -msgid "Identical to reading the :attr:`~Calendar.firstweekday` property." -msgstr "" - -#: ../../library/calendar.rst:59 -msgid "" -"Set the first weekday to *firstweekday*, passed as an :class:`int` (0--6)" -msgstr "" - -#: ../../library/calendar.rst:61 -msgid "Identical to setting the :attr:`~Calendar.firstweekday` property." -msgstr "" - -#: ../../library/calendar.rst:65 -msgid "" -"Return an iterator for the week day numbers that will be used for one week. " -"The first value from the iterator will be the same as the value of " -"the :attr:`~Calendar.firstweekday` property." -msgstr "" -"回傳一個以數字代表一週的每一天的疊代器 (iterator)。疊代器的第一個值" -"和 :attr:`~Calendar.firstweekday` 屬性的值一樣。" - -#: ../../library/calendar.rst:72 -msgid "" -"Return an iterator for the month *month* (1--12) in the year *year*. This " -"iterator will return all days (as :class:`datetime.date` objects) for the " -"month and all days before the start of the month or after the end of the " -"month that are required to get a complete week." -msgstr "" -"回傳一個在 *year* 年 *month* (1--12) 月的疊代器。這個疊代器會回傳該月的所有日" -"期（:class:`datetime.date` 物件）以及在該月之前及之後用來組成完整一週的日期。" - -#: ../../library/calendar.rst:80 -msgid "" -"Return an iterator for the month *month* in the year *year* similar " -"to :meth:`itermonthdates`, but not restricted by the :class:`datetime.date` " -"range. Days returned will simply be day of the month numbers. For the days " -"outside of the specified month, the day number is ``0``." -msgstr "" -"類似 :meth:`itermonthdates`，回傳一個在 *year* 年 *month* 月的疊代器，但不受" -"限於 :class:`datetime.date` 的範圍。回傳的日期單純是該月當日的數字，對於該月" -"之外的日期數字會是 ``0``。" - -#: ../../library/calendar.rst:88 -msgid "" -"Return an iterator for the month *month* in the year *year* similar " -"to :meth:`itermonthdates`, but not restricted by the :class:`datetime.date` " -"range. Days returned will be tuples consisting of a day of the month number " -"and a week day number." -msgstr "" -"類似 :meth:`itermonthdates`，回傳一個在 *year* 年 *month* 月的疊代器，但不受" -"限於 :class:`datetime.date` 的範圍。回傳的日期是一個由該月當日的數字及代表週" -"幾的數字組成的元組。" - -#: ../../library/calendar.rst:96 -msgid "" -"Return an iterator for the month *month* in the year *year* similar " -"to :meth:`itermonthdates`, but not restricted by the :class:`datetime.date` " -"range. Days returned will be tuples consisting of a year, a month and a day " -"of the month numbers." -msgstr "" -"類似 :meth:`itermonthdates`，回傳一個在 *year* 年 *month* 月的疊代器，但不受" -"限於 :class:`datetime.date` 的範圍。回傳的日期是一個由年、月、日的數字組成的" -"元組。" - -#: ../../library/calendar.rst:106 -msgid "" -"Return an iterator for the month *month* in the year *year* similar " -"to :meth:`itermonthdates`, but not restricted by the :class:`datetime.date` " -"range. Days returned will be tuples consisting of a year, a month, a day of " -"the month, and a day of the week numbers." -msgstr "" -"類似 :meth:`itermonthdates`，回傳一個在 *year* 年 *month* 月的疊代器，但不受" -"限於 :class:`datetime.date` 的範圍。回傳的日期是一個由年、月、日及代表週幾的" -"數字組成的元組。" - -#: ../../library/calendar.rst:116 -msgid "" -"Return a list of the weeks in the month *month* of the *year* as full " -"weeks. Weeks are lists of seven :class:`datetime.date` objects." -msgstr "" -"回傳一個在 *year* 年 *month* 月每一週組成的串列。每一週是一個串列，包含七" -"個 :class:`datetime.date` 物件。" - -#: ../../library/calendar.rst:122 -msgid "" -"Return a list of the weeks in the month *month* of the *year* as full " -"weeks. Weeks are lists of seven tuples of day numbers and weekday numbers." -msgstr "" -"回傳一個在 *year* 年 *month* 月每一週組成的串列。每一週是一個串列，包含七個該" -"月當日的數字及代表週幾的數字組成的元組。" - -#: ../../library/calendar.rst:129 -msgid "" -"Return a list of the weeks in the month *month* of the *year* as full " -"weeks. Weeks are lists of seven day numbers." -msgstr "" -"回傳一個在 *year* 年 *month* 月每一週組成的串列。每一週是一個串列，包含七個該" -"月當日的數字。" - -#: ../../library/calendar.rst:135 -msgid "" -"Return the data for the specified year ready for formatting. The return " -"value is a list of month rows. Each month row contains up to *width* months " -"(defaulting to 3). Each month contains between 4 and 6 weeks and each week " -"contains 1--7 days. Days are :class:`datetime.date` objects." -msgstr "" -"回傳用來格式化的指定年份的資料。回傳值是月份列的串列，每個月份列最多由 " -"*width* 個月份組成（預設為 3）。每個月份包含四到六週，每一週包含一到七天，每" -"一天則是一個 :class:`datetime.date` 物件。" - -#: ../../library/calendar.rst:143 -msgid "" -"Return the data for the specified year ready for formatting (similar " -"to :meth:`yeardatescalendar`). Entries in the week lists are tuples of day " -"numbers and weekday numbers. Day numbers outside this month are zero." -msgstr "" -"回傳用來格式化的指定年份的資料（類似 :meth:`yeardatescalendar`）。每一天是一" -"個該月當日的數字及代表週幾的數字組成的元組，該月外的日期的該月當日數字為 0。" - -#: ../../library/calendar.rst:150 -msgid "" -"Return the data for the specified year ready for formatting (similar " -"to :meth:`yeardatescalendar`). Entries in the week lists are day numbers. " -"Day numbers outside this month are zero." -msgstr "" -"回傳用來格式化的指定年份的資料（類似 :meth:`yeardatescalendar`）。每一天是一" -"個該月當日的數字，該月外的日期的該月當日數字為 0。" - -#: ../../library/calendar.rst:157 -msgid "This class can be used to generate plain text calendars." -msgstr "這個類別用來產生純文字的日曆。" - -#: ../../library/calendar.rst:159 -msgid ":class:`TextCalendar` instances have the following methods:" -msgstr ":class:`TextCalendar` 實例有以下方法：" - -#: ../../library/calendar.rst:164 -msgid "" -"Return a string representing a single day formatted with the given *width*. " -"If *theday* is ``0``, return a string of spaces of the specified width, " -"representing an empty day. The *weekday* parameter is unused." -msgstr "" - -#: ../../library/calendar.rst:171 -msgid "" -"Return a single week in a string with no newline. If *w* is provided, it " -"specifies the width of the date columns, which are centered. Depends on the " -"first weekday as specified in the constructor or set by " -"the :meth:`setfirstweekday` method." -msgstr "" - -#: ../../library/calendar.rst:179 -msgid "" -"Return a string representing the name of a single weekday formatted to the " -"specified *width*. The *weekday* parameter is an integer representing the " -"day of the week, where ``0`` is Monday and ``6`` is Sunday." -msgstr "" - -#: ../../library/calendar.rst:186 -msgid "" -"Return a string containing the header row of weekday names, formatted with " -"the given *width* for each column. The names depend on the locale settings " -"and are padded to the specified width." -msgstr "" - -#: ../../library/calendar.rst:193 -msgid "" -"Return a month's calendar in a multi-line string. If *w* is provided, it " -"specifies the width of the date columns, which are centered. If *l* is " -"given, it specifies the number of lines that each week will use. Depends on " -"the first weekday as specified in the constructor or set by " -"the :meth:`setfirstweekday` method." -msgstr "" -"以多行字串的形式回傳一個月份的日曆。如果給定 *w*，它會指定置中的日期欄的寬" -"度。如果給定 *l*，它會指定每一週使用的行數。這個日曆會依據在建構函式中指定或" -"者透過 :meth:`setfirstweekday` 方法設定的一週的第一天來輸出。" - -#: ../../library/calendar.rst:202 -msgid "" -"Return a string representing the month's name centered within the specified " -"*width*. If *withyear* is ``True``, include the year in the output. The " -"*theyear* and *themonth* parameters specify the year and month for the name " -"to be formatted respectively." -msgstr "" - -#: ../../library/calendar.rst:210 -msgid "Print a month's calendar as returned by :meth:`formatmonth`." -msgstr "印出一個月份的日曆，內容和 :meth:`formatmonth` 回傳的一樣。" - -#: ../../library/calendar.rst:215 -msgid "" -"Return a *m*-column calendar for an entire year as a multi-line string. " -"Optional parameters *w*, *l*, and *c* are for date column width, lines per " -"week, and number of spaces between month columns, respectively. Depends on " -"the first weekday as specified in the constructor or set by " -"the :meth:`setfirstweekday` method. The earliest year for which a calendar " -"can be generated is platform-dependent." -msgstr "" -"以多行字串的形式回傳有 *m* 欄的一整年的日曆。可選的參數 *w*、*l* 及 *c* 分別" -"是日期欄寬度、每週行數及月份欄中間的空白數。這個日曆會依據在建構函式中指定或" -"者透過 :meth:`setfirstweekday` 方法設定的一週的第一天來輸出。最早可以產生日曆" -"的年份會依據平台而不同。" - -#: ../../library/calendar.rst:225 -msgid "" -"Print the calendar for an entire year as returned by :meth:`formatyear`." -msgstr "印出一整年的日曆，內容和 :meth:`formatyear` 回傳的一樣。" - -#: ../../library/calendar.rst:230 -msgid "This class can be used to generate HTML calendars." -msgstr "這個類別用來產生 HTML 日曆。" - -#: ../../library/calendar.rst:233 -msgid ":class:`!HTMLCalendar` instances have the following methods:" -msgstr ":class:`!HTMLCalendar` 實例有以下方法：" - -#: ../../library/calendar.rst:237 -msgid "" -"Return a month's calendar as an HTML table. If *withyear* is true the year " -"will be included in the header, otherwise just the month name will be used." -msgstr "" -"以 HTML 表格的形式回傳一個月份的日曆。如果 *withyear* 是 true 則標題會包含年" -"份，否則只會有月份名稱。" - -#: ../../library/calendar.rst:244 -msgid "" -"Return a year's calendar as an HTML table. *width* (defaulting to 3) " -"specifies the number of months per row." -msgstr "" -"以 HTML 表格的形式回傳一整年的日曆。*width*\\ （預設為 3）指定一列有幾個月。" - -#: ../../library/calendar.rst:250 -msgid "" -"Return a year's calendar as a complete HTML page. *width* (defaulting to 3) " -"specifies the number of months per row. *css* is the name for the cascading " -"style sheet to be used. :const:`None` can be passed if no style sheet should " -"be used. *encoding* specifies the encoding to be used for the output " -"(defaulting to the system default encoding)." -msgstr "" -"以完整 HTML 頁面的形式回傳一整年的日曆。*width*\\ （預設為 3）指定一列有幾個" -"月。*css* 是要使用的 CSS (cascading style sheet) 名稱，可以給 :const:`None` " -"表示不使用任何 CSS。*encoding* 指定輸出使用的編碼（預設使用系統預設編碼）。" - -#: ../../library/calendar.rst:259 -msgid "" -"Return a month name as an HTML table row. If *withyear* is true the year " -"will be included in the row, otherwise just the month name will be used." -msgstr "" -"以 HTML 表列的形式回傳一個月份的名稱。如果 *withyear* 是 true 則該列會包含年" -"份，否則只會有月份名稱。" - -#: ../../library/calendar.rst:264 -msgid "" -":class:`!HTMLCalendar` has the following attributes you can override to " -"customize the CSS classes used by the calendar:" -msgstr ":class:`!HTMLCalendar` 可以覆寫以下屬性來客製日曆所使用的 CSS 類別：" - -#: ../../library/calendar.rst:269 -msgid "" -"A list of CSS classes used for each weekday. The default class list is::" -msgstr "對應一週每一天 CSS 類別的串列。預設的串列內容為： ::" - -#: ../../library/calendar.rst:271 -msgid "" -"cssclasses = [\"mon\", \"tue\", \"wed\", \"thu\", \"fri\", \"sat\", \"sun\"]" -msgstr "" -"cssclasses = [\"mon\", \"tue\", \"wed\", \"thu\", \"fri\", \"sat\", \"sun\"]" - -#: ../../library/calendar.rst:273 -msgid "more styles can be added for each day::" -msgstr "可以針對每一天增加更多樣式： ::" - -#: ../../library/calendar.rst:275 -msgid "" -"cssclasses = [\"mon text-bold\", \"tue\", \"wed\", \"thu\", \"fri\", " -"\"sat\", \"sun red\"]" -msgstr "" -"cssclasses = [\"mon text-bold\", \"tue\", \"wed\", \"thu\", \"fri\", " -"\"sat\", \"sun red\"]" - -#: ../../library/calendar.rst:277 -msgid "Note that the length of this list must be seven items." -msgstr "注意這個串列的長度必須是七個項目。" - -#: ../../library/calendar.rst:282 -msgid "The CSS class for a weekday occurring in the previous or coming month." -msgstr "跟當月為同一週且屬於前一個或下一個月份的日期使用的 CSS 類別。" - -#: ../../library/calendar.rst:289 -msgid "" -"A list of CSS classes used for weekday names in the header row. The default " -"is the same as :attr:`cssclasses`." -msgstr "" -"在標題列中一週每一天名稱的 CSS 類別的串列。預設內容和 :attr:`cssclasses` 相" -"同。" - -#: ../../library/calendar.rst:297 -msgid "" -"The month's head CSS class (used by :meth:`formatmonthname`). The default " -"value is ``\"month\"``." -msgstr "" -"月份標題的 CSS 類別（由 :meth:`formatmonthname` 所使用），預設值是 " -"``\"month\"``。" - -#: ../../library/calendar.rst:305 -msgid "" -"The CSS class for the whole month's table (used by :meth:`formatmonth`). The " -"default value is ``\"month\"``." -msgstr "" -"整個月份表格的 CSS 類別（由 :meth:`formatmonth` 所使用），預設值是 " -"``\"month\"``。" - -#: ../../library/calendar.rst:313 -msgid "" -"The CSS class for the whole year's table of tables (used " -"by :meth:`formatyear`). The default value is ``\"year\"``." -msgstr "" -"整年表格的 CSS 類別（由 :meth:`formatyear` 所使用），預設值是 ``\"year\"``。" - -#: ../../library/calendar.rst:321 -msgid "" -"The CSS class for the table head for the whole year (used " -"by :meth:`formatyear`). The default value is ``\"year\"``." -msgstr "" -"整年表格標題的 CSS 類別（由 :meth:`formatyear` 所使用），預設值是 " -"``\"year\"``。" - -#: ../../library/calendar.rst:327 -msgid "" -"Note that although the naming for the above described class attributes is " -"singular (e.g. ``cssclass_month`` ``cssclass_noday``), one can replace the " -"single CSS class with a space separated list of CSS classes, for example::" -msgstr "" -"注意雖然上面提到的 CSS 屬性名稱是單數（例如 ``cssclass_month``、" -"``cssclass_noday``），你可以使用多個以空格隔開的 CSS 類別取代單一 CSS 類別，" -"例如： ::" - -#: ../../library/calendar.rst:331 -msgid "\"text-bold text-red\"" -msgstr "\"text-bold text-red\"" - -#: ../../library/calendar.rst:333 -msgid "Here is an example how :class:`!HTMLCalendar` can be customized::" -msgstr "以下是客製化 :class:`!HTMLCalendar` 的範例： ::" - -#: ../../library/calendar.rst:335 -msgid "" -"class CustomHTMLCal(calendar.HTMLCalendar):\n" -" cssclasses = [style + \" text-nowrap\" for style in\n" -" calendar.HTMLCalendar.cssclasses]\n" -" cssclass_month_head = \"text-center month-head\"\n" -" cssclass_month = \"text-center month\"\n" -" cssclass_year = \"text-italic lead\"" -msgstr "" -"class CustomHTMLCal(calendar.HTMLCalendar):\n" -" cssclasses = [style + \" text-nowrap\" for style in\n" -" calendar.HTMLCalendar.cssclasses]\n" -" cssclass_month_head = \"text-center month-head\"\n" -" cssclass_month = \"text-center month\"\n" -" cssclass_year = \"text-italic lead\"" - -#: ../../library/calendar.rst:345 -msgid "" -"This subclass of :class:`TextCalendar` can be passed a locale name in the " -"constructor and will return month and weekday names in the specified locale." -msgstr "" -":class:`TextCalendar` 的子類別，可以在建構函式傳入語系名稱，它會回傳指定語系" -"的月份及一週每一天的名稱。" - -#: ../../library/calendar.rst:351 -msgid "" -"This subclass of :class:`HTMLCalendar` can be passed a locale name in the " -"constructor and will return month and weekday names in the specified locale." -msgstr "" -":class:`HTMLCalendar` 的子類別，可以在建構函式傳入語系名稱，它會回傳指定語系" -"的月份及一週每一天的名稱。" - -#: ../../library/calendar.rst:357 -msgid "" -"The constructor, :meth:`!formatweekday` and :meth:`!formatmonthname` methods " -"of these two classes temporarily change the ``LC_TIME`` locale to the given " -"*locale*. Because the current locale is a process-wide setting, they are not " -"thread-safe." -msgstr "" -"這兩個類別的建構函式、:meth:`!formatweekday` 及 :meth:`!formatmonthname` 方法" -"會把 ``LC_TIME`` 語系暫時改成給定的 *locale*。因為目前的語系是屬於整個行程 " -"(process-wide) 的設定，它們不是執行緒安全的。" - -#: ../../library/calendar.rst:363 -msgid "For simple text calendars this module provides the following functions." -msgstr "這個模組提供以下函式給單純的文字日曆使用。" - -#: ../../library/calendar.rst:367 -msgid "" -"Sets the weekday (``0`` is Monday, ``6`` is Sunday) to start each week. The " -"values :const:`MONDAY`, :const:`TUESDAY`, :const:`WEDNESDAY`, :const:`THURSDAY`, :const:`FRIDAY`, :const:`SATURDAY`, " -"and :const:`SUNDAY` are provided for convenience. For example, to set the " -"first weekday to Sunday::" -msgstr "" -"設定一週的第一天（``0`` 是週一、``6`` 是週日）。提" -"供 :const:`MONDAY`、:const:`TUESDAY`、:const:`WEDNESDAY`、:const:`THURSDAY`、:const:`FRIDAY`、:const:`SATURDAY` " -"及 :const:`SUNDAY` 可以方便設定。例如設定一週的第一天為週日： ::" - -#: ../../library/calendar.rst:372 -msgid "" -"import calendar\n" -"calendar.setfirstweekday(calendar.SUNDAY)" -msgstr "" -"import calendar\n" -"calendar.setfirstweekday(calendar.SUNDAY)" - -#: ../../library/calendar.rst:378 -msgid "Returns the current setting for the weekday to start each week." -msgstr "回傳目前設定的一週的第一天。" - -#: ../../library/calendar.rst:383 -msgid "" -"Returns :const:`True` if *year* is a leap year, otherwise :const:`False`." -msgstr "如果 *year* 是閏年回傳 :const:`True`，否則回傳 :const:`False`。" - -#: ../../library/calendar.rst:388 -msgid "" -"Returns the number of leap years in the range from *y1* to *y2* (exclusive), " -"where *y1* and *y2* are years." -msgstr "" -"回傳從 *y1* 到 *y2*\\ （不包含）間有幾個閏年，其中 *y1* 和 *y2* 是年份。" - -#: ../../library/calendar.rst:391 -msgid "This function works for ranges spanning a century change." -msgstr "這個函式也適用在跨越世紀的時間範圍。" - -#: ../../library/calendar.rst:396 -msgid "" -"Returns the day of the week (``0`` is Monday) for *year* (``1970``--...), " -"*month* (``1``--``12``), *day* (``1``--``31``)." -msgstr "" -"回傳 *year* 年 (``1970``--...) *month* 月 (``1``--``12``) *day* 日 (``1``--" -"``31``) 是週幾（``0`` 是星期一）。" - -#: ../../library/calendar.rst:402 -msgid "" -"Return a header containing abbreviated weekday names. *n* specifies the " -"width in characters for one weekday." -msgstr "回傳包含一週每一天的名稱縮寫的標題。*n* 指定每一天的字元寬度。" - -#: ../../library/calendar.rst:408 -msgid "" -"Returns weekday of first day of the month and number of days in month, for " -"the specified *year* and *month*." -msgstr "回傳指定 *year* 年 *month* 月該月第一天代表週幾的數字及該月有多少天。" - -#: ../../library/calendar.rst:414 -msgid "" -"Returns a matrix representing a month's calendar. Each row represents a " -"week; days outside of the month are represented by zeros. Each week begins " -"with Monday unless set by :func:`setfirstweekday`." -msgstr "" -"回傳代表一個月份日曆的矩陣。每一列為一週；該月以外的日期以 0 表示。每一週以週" -"一開始，除非有使用 :func:`setfirstweekday` 改變設定。" - -#: ../../library/calendar.rst:421 -msgid "Prints a month's calendar as returned by :func:`month`." -msgstr "印出一個月份的日曆，跟 :func:`month` 回傳的內容一樣。" - -#: ../../library/calendar.rst:426 -msgid "" -"Returns a month's calendar in a multi-line string using " -"the :meth:`~TextCalendar.formatmonth` of the :class:`TextCalendar` class." -msgstr "" -"以多行字串的形式回傳一個月的日曆，使用 :class:`TextCalendar` 類別" -"的 :meth:`~TextCalendar.formatmonth`。" - -#: ../../library/calendar.rst:432 -msgid "" -"Prints the calendar for an entire year as returned by :func:`calendar`." -msgstr "印出一整年的日曆，跟 :func:`calendar` 回傳的內容一樣。" - -#: ../../library/calendar.rst:437 -msgid "" -"Returns a 3-column calendar for an entire year as a multi-line string using " -"the :meth:`~TextCalendar.formatyear` of the :class:`TextCalendar` class." -msgstr "" -"以多行字串回傳三欄形式的一整年日曆，使用 :class:`TextCalendar` 類別" -"的 :meth:`~TextCalendar.formatyear`。" - -#: ../../library/calendar.rst:443 -msgid "" -"An unrelated but handy function that takes a time tuple such as returned by " -"the :func:`~time.gmtime` function in the :mod:`time` module, and returns the " -"corresponding Unix timestamp value, assuming an epoch of 1970, and the POSIX " -"encoding. In fact, :func:`time.gmtime` and :func:`timegm` are each others' " -"inverse." -msgstr "" -"一個跟日曆無關但方便的函式，它接受一個像 :mod:`time` 模組裡" -"的 :func:`~time.gmtime` 函式回傳的元組，並回傳對應的 Unix 時間戳，假設從 " -"1970 開始及 POSIX 編碼。事實上，:func:`time.gmtime` 和 :func:`timegm` 是彼此" -"相反的。" - -#: ../../library/calendar.rst:450 -msgid "The :mod:`calendar` module exports the following data attributes:" -msgstr ":mod:`calendar` 模組匯出以下資料屬性：" - -#: ../../library/calendar.rst:454 -msgid "" -"A sequence that represents the days of the week in the current locale, where " -"Monday is day number 0." -msgstr "以目前語系來表示的一週每一天名稱的序列，其中週一是第 0 天。" - -#: ../../library/calendar.rst:464 -msgid "" -"A sequence that represents the abbreviated days of the week in the current " -"locale, where Mon is day number 0." -msgstr "以目前語系來表示的一週每一天縮寫名稱的序列，其中 Mon 是第 0 天。" - -#: ../../library/calendar.rst:479 -msgid "" -"Aliases for the days of the week, where ``MONDAY`` is ``0`` and ``SUNDAY`` " -"is ``6``." -msgstr "一週每一天的別名，其中 ``MONDAY`` 是 ``0`` 而 ``SUNDAY`` 是 ``6``。" - -#: ../../library/calendar.rst:487 -msgid "" -"Enumeration defining days of the week as integer constants. The members of " -"this enumeration are exported to the module scope as :data:`MONDAY` " -"through :data:`SUNDAY`." -msgstr "" -"將一週中的幾天定義為整數常數的列舉。此列舉的成員將作為 :data:`MONDAY` " -"到 :data:`SUNDAY` 匯出到模組作用域。" - -#: ../../library/calendar.rst:496 -msgid "" -"A sequence that represents the months of the year in the current locale. " -"This follows normal convention of January being month number 1, so it has a " -"length of 13 and ``month_name[0]`` is the empty string." -msgstr "" -"以目前語系來表示的一年每個月份名稱的序列。它按照一般慣例以數字 1 代表一月，因" -"此它的長度為 13，而 ``month_name[0]`` 是空字串。" - -#: ../../library/calendar.rst:507 -msgid "" -"A sequence that represents the abbreviated months of the year in the current " -"locale. This follows normal convention of January being month number 1, so " -"it has a length of 13 and ``month_abbr[0]`` is the empty string." -msgstr "" -"以目前語系來表示的一年每個月份縮寫名稱的序列。它按照一般慣例以數字 1 代表一" -"月，因此它的長度為 13，而 ``month_abbr[0]`` 是空字串。" - -#: ../../library/calendar.rst:528 -msgid "" -"Aliases for the months of the year, where ``JANUARY`` is ``1`` and " -"``DECEMBER`` is ``12``." -msgstr "" -"一年內每個月的別名，其中 ``JANUARY`` 是 ``1`` 而 ``DECEMBER`` 是 ``12``。" - -#: ../../library/calendar.rst:536 -msgid "" -"Enumeration defining months of the year as integer constants. The members of " -"this enumeration are exported to the module scope as :data:`JANUARY` " -"through :data:`DECEMBER`." -msgstr "" -"將一年中的月份定義為整數常數的列舉。此列舉的成員將作為 :data:`JANUARY` " -"到 :data:`DECEMBER` 匯出到模組作用域。" - -#: ../../library/calendar.rst:543 -msgid "The :mod:`calendar` module defines the following exceptions:" -msgstr ":mod:`calendar` 模組定義了以下例外：" - -#: ../../library/calendar.rst:547 -msgid "" -"A subclass of :exc:`ValueError`, raised when the given month number is " -"outside of the range 1-12 (inclusive)." -msgstr "" -":exc:`ValueError` 的子類別，當給定的月份數字超出 1-12 範圍（含）時引發。" - -#: ../../library/calendar.rst:552 -msgid "The invalid month number." -msgstr "無效的月份號。" - -#: ../../library/calendar.rst:557 -msgid "" -"A subclass of :exc:`ValueError`, raised when the given weekday number is " -"outside of the range 0-6 (inclusive)." -msgstr "" -":exc:`ValueError` 的子類別，當給定的週幾的數字超出 0-6（含）範圍時引發。" - -#: ../../library/calendar.rst:562 -msgid "The invalid weekday number." -msgstr "無效的週幾編號。" - -#: ../../library/calendar.rst:567 -msgid "Module :mod:`datetime`" -msgstr ":mod:`datetime` 模組" - -#: ../../library/calendar.rst:568 -msgid "" -"Object-oriented interface to dates and times with similar functionality to " -"the :mod:`time` module." -msgstr "日期與時間的物件導向介面，和 :mod:`time` 模組有相似的功能。" - -#: ../../library/calendar.rst:571 -msgid "Module :mod:`time`" -msgstr ":mod:`time` 模組" - -#: ../../library/calendar.rst:572 -msgid "Low-level time related functions." -msgstr "底層的時間相關函式。" - -#: ../../library/calendar.rst:578 -msgid "Command-line usage" -msgstr "命令列用法" - -#: ../../library/calendar.rst:582 -msgid "" -"The :mod:`calendar` module can be executed as a script from the command line " -"to interactively print a calendar." -msgstr ":mod:`calendar` 模組可以作為腳本從命令列執行，並以互動方式列印日曆。" - -#: ../../library/calendar.rst:585 -msgid "" -"python -m calendar [-h] [-L LOCALE] [-e ENCODING] [-t {text,html}]\n" -" [-w WIDTH] [-l LINES] [-s SPACING] [-m MONTHS] [-c CSS]\n" -" [-f FIRST_WEEKDAY] [year] [month]" -msgstr "" -"python -m calendar [-h] [-L LOCALE] [-e ENCODING] [-t {text,html}]\n" -" [-w WIDTH] [-l LINES] [-s SPACING] [-m MONTHS] [-c CSS]\n" -" [-f FIRST_WEEKDAY] [year] [month]" - -#: ../../library/calendar.rst:592 -msgid "For example, to print a calendar for the year 2000:" -msgstr "例如，要列印 2000 年的日曆：" - -#: ../../library/calendar.rst:594 -msgid "" -"$ python -m calendar 2000\n" -" 2000\n" -"\n" -" January February March\n" -"Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su\n" -" 1 2 1 2 3 4 5 6 1 2 3 4 5\n" -" 3 4 5 6 7 8 9 7 8 9 10 11 12 13 6 7 8 9 10 11 12\n" -"10 11 12 13 14 15 16 14 15 16 17 18 19 20 13 14 15 16 17 18 19\n" -"17 18 19 20 21 22 23 21 22 23 24 25 26 27 20 21 22 23 24 25 26\n" -"24 25 26 27 28 29 30 28 29 27 28 29 30 31\n" -"31\n" -"\n" -" April May June\n" -"Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su\n" -" 1 2 1 2 3 4 5 6 7 1 2 3 4\n" -" 3 4 5 6 7 8 9 8 9 10 11 12 13 14 5 6 7 8 9 10 11\n" -"10 11 12 13 14 15 16 15 16 17 18 19 20 21 12 13 14 15 16 17 18\n" -"17 18 19 20 21 22 23 22 23 24 25 26 27 28 19 20 21 22 23 24 25\n" -"24 25 26 27 28 29 30 29 30 31 26 27 28 29 30\n" -"\n" -" July August September\n" -"Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su\n" -" 1 2 1 2 3 4 5 6 1 2 3\n" -" 3 4 5 6 7 8 9 7 8 9 10 11 12 13 4 5 6 7 8 9 10\n" -"10 11 12 13 14 15 16 14 15 16 17 18 19 20 11 12 13 14 15 16 17\n" -"17 18 19 20 21 22 23 21 22 23 24 25 26 27 18 19 20 21 22 23 24\n" -"24 25 26 27 28 29 30 28 29 30 31 25 26 27 28 29 30\n" -"31\n" -"\n" -" October November December\n" -"Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su\n" -" 1 1 2 3 4 5 1 2 3\n" -" 2 3 4 5 6 7 8 6 7 8 9 10 11 12 4 5 6 7 8 9 10\n" -" 9 10 11 12 13 14 15 13 14 15 16 17 18 19 11 12 13 14 15 16 17\n" -"16 17 18 19 20 21 22 20 21 22 23 24 25 26 18 19 20 21 22 23 24\n" -"23 24 25 26 27 28 29 27 28 29 30 25 26 27 28 29 30 31\n" -"30 31" -msgstr "" -"$ python -m calendar 2000\n" -" 2000\n" -"\n" -" January February March\n" -"Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su\n" -" 1 2 1 2 3 4 5 6 1 2 3 4 5\n" -" 3 4 5 6 7 8 9 7 8 9 10 11 12 13 6 7 8 9 10 11 12\n" -"10 11 12 13 14 15 16 14 15 16 17 18 19 20 13 14 15 16 17 18 19\n" -"17 18 19 20 21 22 23 21 22 23 24 25 26 27 20 21 22 23 24 25 26\n" -"24 25 26 27 28 29 30 28 29 27 28 29 30 31\n" -"31\n" -"\n" -" April May June\n" -"Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su\n" -" 1 2 1 2 3 4 5 6 7 1 2 3 4\n" -" 3 4 5 6 7 8 9 8 9 10 11 12 13 14 5 6 7 8 9 10 11\n" -"10 11 12 13 14 15 16 15 16 17 18 19 20 21 12 13 14 15 16 17 18\n" -"17 18 19 20 21 22 23 22 23 24 25 26 27 28 19 20 21 22 23 24 25\n" -"24 25 26 27 28 29 30 29 30 31 26 27 28 29 30\n" -"\n" -" July August September\n" -"Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su\n" -" 1 2 1 2 3 4 5 6 1 2 3\n" -" 3 4 5 6 7 8 9 7 8 9 10 11 12 13 4 5 6 7 8 9 10\n" -"10 11 12 13 14 15 16 14 15 16 17 18 19 20 11 12 13 14 15 16 17\n" -"17 18 19 20 21 22 23 21 22 23 24 25 26 27 18 19 20 21 22 23 24\n" -"24 25 26 27 28 29 30 28 29 30 31 25 26 27 28 29 30\n" -"31\n" -"\n" -" October November December\n" -"Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su\n" -" 1 1 2 3 4 5 1 2 3\n" -" 2 3 4 5 6 7 8 6 7 8 9 10 11 12 4 5 6 7 8 9 10\n" -" 9 10 11 12 13 14 15 13 14 15 16 17 18 19 11 12 13 14 15 16 17\n" -"16 17 18 19 20 21 22 20 21 22 23 24 25 26 18 19 20 21 22 23 24\n" -"23 24 25 26 27 28 29 27 28 29 30 25 26 27 28 29 30 31\n" -"30 31" - -#: ../../library/calendar.rst:635 -msgid "The following options are accepted:" -msgstr "接受以下選項：" - -#: ../../library/calendar.rst:642 -msgid "Show the help message and exit." -msgstr "顯示幫助訊息並退出。" - -#: ../../library/calendar.rst:647 -msgid "The locale to use for month and weekday names. Defaults to English." -msgstr "用於月份和週幾名稱的語系。預設為英語。" - -#: ../../library/calendar.rst:653 -msgid "" -"The encoding to use for output. :option:`--encoding` is required " -"if :option:`--locale` is set." -msgstr "" -"用於輸出的編碼。如有設定 :option:`--locale` 則必須給定 :option:`--encoding`。" - -#: ../../library/calendar.rst:659 -msgid "Print the calendar to the terminal as text, or as an HTML document." -msgstr "將日曆以文字或 HTML 文件的形式印出到終端機。" - -#: ../../library/calendar.rst:665 -msgid "" -"The weekday to start each week. Must be a number between 0 (Monday) and 6 " -"(Sunday). Defaults to 0." -msgstr "一週起始的日子。必須是 0（週一）到 6（週日）之間的數字。預設為 0。" - -#: ../../library/calendar.rst:673 -msgid "The year to print the calendar for. Defaults to the current year." -msgstr "印出日曆的年份。預設為目前年份。" - -#: ../../library/calendar.rst:679 -msgid "" -"The month of the specified :option:`year` to print the calendar for. Must be " -"a number between 1 and 12, and may only be used in text mode. Defaults to " -"printing a calendar for the full year." -msgstr "" -"要列印日曆的指定 :option:`year` 的月份。必須是 1 到 12 之間的數字，並且只能在" -"文字模式下使用。預設列印全年日曆。" - -#: ../../library/calendar.rst:685 -msgid "*Text-mode options:*" -msgstr "*文字模式選項：*" - -#: ../../library/calendar.rst:689 -msgid "" -"The width of the date column in terminal columns. The date is printed " -"centred in the column. Any value lower than 2 is ignored. Defaults to 2." -msgstr "" -"終端機行中日期行的寬度。日期印出在行的中央。任何小於 2 的值都會被忽略。預設" -"為 2。" - -#: ../../library/calendar.rst:697 -msgid "" -"The number of lines for each week in terminal rows. The date is printed top-" -"aligned. Any value lower than 1 is ignored. Defaults to 1." -msgstr "" -"終端機列中每週的列數。日期印出時頂部會對齊。任何小於 1 的值都會被忽略。預設" -"為 1。" - -#: ../../library/calendar.rst:705 -msgid "" -"The space between months in columns. Any value lower than 2 is ignored. " -"Defaults to 6." -msgstr "行中月份之間的間距。任何小於 2 的值都會被忽略。預設為 6。" - -#: ../../library/calendar.rst:712 -msgid "The number of months printed per row. Defaults to 3." -msgstr "每列印出的月份數量。預設為 3。" - -#: ../../library/calendar.rst:715 -msgid "" -"By default, today's date is highlighted in color and can be :ref:`controlled " -"using environment variables `." -msgstr "" - -#: ../../library/calendar.rst:719 -msgid "*HTML-mode options:*" -msgstr "*HTML 模式選項：*" - -#: ../../library/calendar.rst:723 -msgid "" -"The path of a CSS stylesheet to use for the calendar. This must either be " -"relative to the generated HTML, or an absolute HTTP or ``file:///`` URL." -msgstr "" -"用於日曆的 CSS 樣式表路徑。這必須是相對於產生之 HTML 的，或者為絕對的 HTTP " -"或 ``file:///`` URL。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: 2018-05-23 14:40+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/calendar.rst:2 +msgid ":mod:`!calendar` --- General calendar-related functions" +msgstr ":mod:`!calendar` --- 日曆相關函式" + +#: ../../library/calendar.rst:10 +msgid "**Source code:** :source:`Lib/calendar.py`" +msgstr "**原始碼：**\\ :source:`Lib/calendar.py`" + +#: ../../library/calendar.rst:14 +msgid "" +"This module allows you to output calendars like the Unix :program:`cal` " +"program, and provides additional useful functions related to the calendar. " +"By default, these calendars have Monday as the first day of the week, and " +"Sunday as the last (the European convention). Use :func:`setfirstweekday` to " +"set the first day of the week to Sunday (6) or to any other weekday. " +"Parameters that specify dates are given as integers. For related " +"functionality, see also the :mod:`datetime` and :mod:`time` modules." +msgstr "" +"這個模組讓你可以像 Unix 的 :program:`cal` 程式一樣輸出日曆，並額外提供有用的" +"日曆相關函式。這些日曆預設把週一當作一週的第一天，而週日當作最後一天（歐洲的" +"慣例）。可以使用 :func:`setfirstweekday` 設定一週的第一天為週日 (6) 或一週的" +"其它任一天，其中指定日期的參數是整數。相關功能參考 :mod:`datetime` " +"和 :mod:`time` 模組。" + +#: ../../library/calendar.rst:22 +msgid "" +"The functions and classes defined in this module use an idealized calendar, " +"the current Gregorian calendar extended indefinitely in both directions. " +"This matches the definition of the \"proleptic Gregorian\" calendar in " +"Dershowitz and Reingold's book \"Calendrical Calculations\", where it's the " +"base calendar for all computations. Zero and negative years are interpreted " +"as prescribed by the ISO 8601 standard. Year 0 is 1 BC, year -1 is 2 BC, " +"and so on." +msgstr "" +"這個模組定義的函式和類別使用理想化的日曆，也就是公曆 (Gregorian calendar) 無" +"限往前後兩個方向延伸。這符合 Dershowitz 和 Reingold 在「Calendrical " +"Calculations」這本書定義的「逆推公曆」(proleptic Gregorian)，是做所有計算的基" +"礎日曆。0 及負數年份的解讀跟 ISO 8601 標準裡規定的一樣，0 年是公元前 1 " +"年，-1 年是公元前 2 年依此類推。" + +#: ../../library/calendar.rst:33 +msgid "" +"Creates a :class:`Calendar` object. *firstweekday* is an integer specifying " +"the first day of the week. :const:`MONDAY` is ``0`` (the " +"default), :const:`SUNDAY` is ``6``." +msgstr "" +"建立 :class:`Calendar` 物件。*firstweekday* 是一個指定一週第一天的整" +"數，:const:`MONDAY` 是 ``0``\\ （預設值），:const:`SUNDAY` 是 ``6``。" + +#: ../../library/calendar.rst:36 +msgid "" +"A :class:`Calendar` object provides several methods that can be used for " +"preparing the calendar data for formatting. This class doesn't do any " +"formatting itself. This is the job of subclasses." +msgstr "" +":class:`Calendar` 物件提供一些方法來為日曆資料的格式化做準備。這個類別本身不" +"做任何格式化，這是子類別的工作。" + +#: ../../library/calendar.rst:41 +msgid ":class:`Calendar` instances have the following methods and attributes:" +msgstr ":class:`Calendar` 實例有以下方法與屬性：" + +#: ../../library/calendar.rst:45 +msgid "The first weekday as an integer (0--6)." +msgstr "" + +#: ../../library/calendar.rst:47 +msgid "" +"This property can also be set and read " +"using :meth:`~Calendar.setfirstweekday` " +"and :meth:`~Calendar.getfirstweekday` respectively." +msgstr "" + +#: ../../library/calendar.rst:53 +msgid "Return an :class:`int` for the current first weekday (0--6)." +msgstr "" + +#: ../../library/calendar.rst:55 +msgid "Identical to reading the :attr:`~Calendar.firstweekday` property." +msgstr "" + +#: ../../library/calendar.rst:59 +msgid "" +"Set the first weekday to *firstweekday*, passed as an :class:`int` (0--6)" +msgstr "" + +#: ../../library/calendar.rst:61 +msgid "Identical to setting the :attr:`~Calendar.firstweekday` property." +msgstr "" + +#: ../../library/calendar.rst:65 +msgid "" +"Return an iterator for the week day numbers that will be used for one week. " +"The first value from the iterator will be the same as the value of " +"the :attr:`~Calendar.firstweekday` property." +msgstr "" +"回傳一個以數字代表一週的每一天的疊代器 (iterator)。疊代器的第一個值" +"和 :attr:`~Calendar.firstweekday` 屬性的值一樣。" + +#: ../../library/calendar.rst:72 +msgid "" +"Return an iterator for the month *month* (1--12) in the year *year*. This " +"iterator will return all days (as :class:`datetime.date` objects) for the " +"month and all days before the start of the month or after the end of the " +"month that are required to get a complete week." +msgstr "" +"回傳一個在 *year* 年 *month* (1--12) 月的疊代器。這個疊代器會回傳該月的所有日" +"期（:class:`datetime.date` 物件）以及在該月之前及之後用來組成完整一週的日期。" + +#: ../../library/calendar.rst:80 +msgid "" +"Return an iterator for the month *month* in the year *year* similar " +"to :meth:`itermonthdates`, but not restricted by the :class:`datetime.date` " +"range. Days returned will simply be day of the month numbers. For the days " +"outside of the specified month, the day number is ``0``." +msgstr "" +"類似 :meth:`itermonthdates`，回傳一個在 *year* 年 *month* 月的疊代器，但不受" +"限於 :class:`datetime.date` 的範圍。回傳的日期單純是該月當日的數字，對於該月" +"之外的日期數字會是 ``0``。" + +#: ../../library/calendar.rst:88 +msgid "" +"Return an iterator for the month *month* in the year *year* similar " +"to :meth:`itermonthdates`, but not restricted by the :class:`datetime.date` " +"range. Days returned will be tuples consisting of a day of the month number " +"and a week day number." +msgstr "" +"類似 :meth:`itermonthdates`，回傳一個在 *year* 年 *month* 月的疊代器，但不受" +"限於 :class:`datetime.date` 的範圍。回傳的日期是一個由該月當日的數字及代表週" +"幾的數字組成的元組。" + +#: ../../library/calendar.rst:96 +msgid "" +"Return an iterator for the month *month* in the year *year* similar " +"to :meth:`itermonthdates`, but not restricted by the :class:`datetime.date` " +"range. Days returned will be tuples consisting of a year, a month and a day " +"of the month numbers." +msgstr "" +"類似 :meth:`itermonthdates`，回傳一個在 *year* 年 *month* 月的疊代器，但不受" +"限於 :class:`datetime.date` 的範圍。回傳的日期是一個由年、月、日的數字組成的" +"元組。" + +#: ../../library/calendar.rst:106 +msgid "" +"Return an iterator for the month *month* in the year *year* similar " +"to :meth:`itermonthdates`, but not restricted by the :class:`datetime.date` " +"range. Days returned will be tuples consisting of a year, a month, a day of " +"the month, and a day of the week numbers." +msgstr "" +"類似 :meth:`itermonthdates`，回傳一個在 *year* 年 *month* 月的疊代器，但不受" +"限於 :class:`datetime.date` 的範圍。回傳的日期是一個由年、月、日及代表週幾的" +"數字組成的元組。" + +#: ../../library/calendar.rst:116 +msgid "" +"Return a list of the weeks in the month *month* of the *year* as full " +"weeks. Weeks are lists of seven :class:`datetime.date` objects." +msgstr "" +"回傳一個在 *year* 年 *month* 月每一週組成的串列。每一週是一個串列，包含七" +"個 :class:`datetime.date` 物件。" + +#: ../../library/calendar.rst:122 +msgid "" +"Return a list of the weeks in the month *month* of the *year* as full " +"weeks. Weeks are lists of seven tuples of day numbers and weekday numbers." +msgstr "" +"回傳一個在 *year* 年 *month* 月每一週組成的串列。每一週是一個串列，包含七個該" +"月當日的數字及代表週幾的數字組成的元組。" + +#: ../../library/calendar.rst:129 +msgid "" +"Return a list of the weeks in the month *month* of the *year* as full " +"weeks. Weeks are lists of seven day numbers." +msgstr "" +"回傳一個在 *year* 年 *month* 月每一週組成的串列。每一週是一個串列，包含七個該" +"月當日的數字。" + +#: ../../library/calendar.rst:135 +msgid "" +"Return the data for the specified year ready for formatting. The return " +"value is a list of month rows. Each month row contains up to *width* months " +"(defaulting to 3). Each month contains between 4 and 6 weeks and each week " +"contains 1--7 days. Days are :class:`datetime.date` objects." +msgstr "" +"回傳用來格式化的指定年份的資料。回傳值是月份列的串列，每個月份列最多由 " +"*width* 個月份組成（預設為 3）。每個月份包含四到六週，每一週包含一到七天，每" +"一天則是一個 :class:`datetime.date` 物件。" + +#: ../../library/calendar.rst:143 +msgid "" +"Return the data for the specified year ready for formatting (similar " +"to :meth:`yeardatescalendar`). Entries in the week lists are tuples of day " +"numbers and weekday numbers. Day numbers outside this month are zero." +msgstr "" +"回傳用來格式化的指定年份的資料（類似 :meth:`yeardatescalendar`）。每一天是一" +"個該月當日的數字及代表週幾的數字組成的元組，該月外的日期的該月當日數字為 0。" + +#: ../../library/calendar.rst:150 +msgid "" +"Return the data for the specified year ready for formatting (similar " +"to :meth:`yeardatescalendar`). Entries in the week lists are day numbers. " +"Day numbers outside this month are zero." +msgstr "" +"回傳用來格式化的指定年份的資料（類似 :meth:`yeardatescalendar`）。每一天是一" +"個該月當日的數字，該月外的日期的該月當日數字為 0。" + +#: ../../library/calendar.rst:157 +msgid "This class can be used to generate plain text calendars." +msgstr "這個類別用來產生純文字的日曆。" + +#: ../../library/calendar.rst:159 +msgid ":class:`TextCalendar` instances have the following methods:" +msgstr ":class:`TextCalendar` 實例有以下方法：" + +#: ../../library/calendar.rst:164 +msgid "" +"Return a string representing a single day formatted with the given *width*. " +"If *theday* is ``0``, return a string of spaces of the specified width, " +"representing an empty day. The *weekday* parameter is unused." +msgstr "" + +#: ../../library/calendar.rst:171 +msgid "" +"Return a single week in a string with no newline. If *w* is provided, it " +"specifies the width of the date columns, which are centered. Depends on the " +"first weekday as specified in the constructor or set by " +"the :meth:`setfirstweekday` method." +msgstr "" + +#: ../../library/calendar.rst:179 +msgid "" +"Return a string representing the name of a single weekday formatted to the " +"specified *width*. The *weekday* parameter is an integer representing the " +"day of the week, where ``0`` is Monday and ``6`` is Sunday." +msgstr "" + +#: ../../library/calendar.rst:186 +msgid "" +"Return a string containing the header row of weekday names, formatted with " +"the given *width* for each column. The names depend on the locale settings " +"and are padded to the specified width." +msgstr "" + +#: ../../library/calendar.rst:193 +msgid "" +"Return a month's calendar in a multi-line string. If *w* is provided, it " +"specifies the width of the date columns, which are centered. If *l* is " +"given, it specifies the number of lines that each week will use. Depends on " +"the first weekday as specified in the constructor or set by " +"the :meth:`setfirstweekday` method." +msgstr "" +"以多行字串的形式回傳一個月份的日曆。如果給定 *w*，它會指定置中的日期欄的寬" +"度。如果給定 *l*，它會指定每一週使用的行數。這個日曆會依據在建構函式中指定或" +"者透過 :meth:`setfirstweekday` 方法設定的一週的第一天來輸出。" + +#: ../../library/calendar.rst:202 +msgid "" +"Return a string representing the month's name centered within the specified " +"*width*. If *withyear* is ``True``, include the year in the output. The " +"*theyear* and *themonth* parameters specify the year and month for the name " +"to be formatted respectively." +msgstr "" + +#: ../../library/calendar.rst:210 +msgid "Print a month's calendar as returned by :meth:`formatmonth`." +msgstr "印出一個月份的日曆，內容和 :meth:`formatmonth` 回傳的一樣。" + +#: ../../library/calendar.rst:215 +msgid "" +"Return a *m*-column calendar for an entire year as a multi-line string. " +"Optional parameters *w*, *l*, and *c* are for date column width, lines per " +"week, and number of spaces between month columns, respectively. Depends on " +"the first weekday as specified in the constructor or set by " +"the :meth:`setfirstweekday` method. The earliest year for which a calendar " +"can be generated is platform-dependent." +msgstr "" +"以多行字串的形式回傳有 *m* 欄的一整年的日曆。可選的參數 *w*、*l* 及 *c* 分別" +"是日期欄寬度、每週行數及月份欄中間的空白數。這個日曆會依據在建構函式中指定或" +"者透過 :meth:`setfirstweekday` 方法設定的一週的第一天來輸出。最早可以產生日曆" +"的年份會依據平台而不同。" + +#: ../../library/calendar.rst:225 +msgid "" +"Print the calendar for an entire year as returned by :meth:`formatyear`." +msgstr "印出一整年的日曆，內容和 :meth:`formatyear` 回傳的一樣。" + +#: ../../library/calendar.rst:230 +msgid "This class can be used to generate HTML calendars." +msgstr "這個類別用來產生 HTML 日曆。" + +#: ../../library/calendar.rst:233 +msgid ":class:`!HTMLCalendar` instances have the following methods:" +msgstr ":class:`!HTMLCalendar` 實例有以下方法：" + +#: ../../library/calendar.rst:237 +msgid "" +"Return a month's calendar as an HTML table. If *withyear* is true the year " +"will be included in the header, otherwise just the month name will be used." +msgstr "" +"以 HTML 表格的形式回傳一個月份的日曆。如果 *withyear* 是 true 則標題會包含年" +"份，否則只會有月份名稱。" + +#: ../../library/calendar.rst:244 +msgid "" +"Return a year's calendar as an HTML table. *width* (defaulting to 3) " +"specifies the number of months per row." +msgstr "" +"以 HTML 表格的形式回傳一整年的日曆。*width*\\ （預設為 3）指定一列有幾個月。" + +#: ../../library/calendar.rst:250 +msgid "" +"Return a year's calendar as a complete HTML page. *width* (defaulting to 3) " +"specifies the number of months per row. *css* is the name for the cascading " +"style sheet to be used. :const:`None` can be passed if no style sheet should " +"be used. *encoding* specifies the encoding to be used for the output " +"(defaulting to the system default encoding)." +msgstr "" +"以完整 HTML 頁面的形式回傳一整年的日曆。*width*\\ （預設為 3）指定一列有幾個" +"月。*css* 是要使用的 CSS (cascading style sheet) 名稱，可以給 :const:`None` " +"表示不使用任何 CSS。*encoding* 指定輸出使用的編碼（預設使用系統預設編碼）。" + +#: ../../library/calendar.rst:259 +msgid "" +"Return a month name as an HTML table row. If *withyear* is true the year " +"will be included in the row, otherwise just the month name will be used." +msgstr "" +"以 HTML 表列的形式回傳一個月份的名稱。如果 *withyear* 是 true 則該列會包含年" +"份，否則只會有月份名稱。" + +#: ../../library/calendar.rst:264 +msgid "" +":class:`!HTMLCalendar` has the following attributes you can override to " +"customize the CSS classes used by the calendar:" +msgstr ":class:`!HTMLCalendar` 可以覆寫以下屬性來客製日曆所使用的 CSS 類別：" + +#: ../../library/calendar.rst:269 +msgid "" +"A list of CSS classes used for each weekday. The default class list is::" +msgstr "對應一週每一天 CSS 類別的串列。預設的串列內容為： ::" + +#: ../../library/calendar.rst:271 +msgid "" +"cssclasses = [\"mon\", \"tue\", \"wed\", \"thu\", \"fri\", \"sat\", \"sun\"]" +msgstr "" +"cssclasses = [\"mon\", \"tue\", \"wed\", \"thu\", \"fri\", \"sat\", \"sun\"]" + +#: ../../library/calendar.rst:273 +msgid "more styles can be added for each day::" +msgstr "可以針對每一天增加更多樣式： ::" + +#: ../../library/calendar.rst:275 +msgid "" +"cssclasses = [\"mon text-bold\", \"tue\", \"wed\", \"thu\", \"fri\", " +"\"sat\", \"sun red\"]" +msgstr "" +"cssclasses = [\"mon text-bold\", \"tue\", \"wed\", \"thu\", \"fri\", " +"\"sat\", \"sun red\"]" + +#: ../../library/calendar.rst:277 +msgid "Note that the length of this list must be seven items." +msgstr "注意這個串列的長度必須是七個項目。" + +#: ../../library/calendar.rst:282 +msgid "The CSS class for a weekday occurring in the previous or coming month." +msgstr "跟當月為同一週且屬於前一個或下一個月份的日期使用的 CSS 類別。" + +#: ../../library/calendar.rst:289 +msgid "" +"A list of CSS classes used for weekday names in the header row. The default " +"is the same as :attr:`cssclasses`." +msgstr "" +"在標題列中一週每一天名稱的 CSS 類別的串列。預設內容和 :attr:`cssclasses` 相" +"同。" + +#: ../../library/calendar.rst:297 +msgid "" +"The month's head CSS class (used by :meth:`formatmonthname`). The default " +"value is ``\"month\"``." +msgstr "" +"月份標題的 CSS 類別（由 :meth:`formatmonthname` 所使用），預設值是 " +"``\"month\"``。" + +#: ../../library/calendar.rst:305 +msgid "" +"The CSS class for the whole month's table (used by :meth:`formatmonth`). The " +"default value is ``\"month\"``." +msgstr "" +"整個月份表格的 CSS 類別（由 :meth:`formatmonth` 所使用），預設值是 " +"``\"month\"``。" + +#: ../../library/calendar.rst:313 +msgid "" +"The CSS class for the whole year's table of tables (used " +"by :meth:`formatyear`). The default value is ``\"year\"``." +msgstr "" +"整年表格的 CSS 類別（由 :meth:`formatyear` 所使用），預設值是 ``\"year\"``。" + +#: ../../library/calendar.rst:321 +msgid "" +"The CSS class for the table head for the whole year (used " +"by :meth:`formatyear`). The default value is ``\"year\"``." +msgstr "" +"整年表格標題的 CSS 類別（由 :meth:`formatyear` 所使用），預設值是 " +"``\"year\"``。" + +#: ../../library/calendar.rst:327 +msgid "" +"Note that although the naming for the above described class attributes is " +"singular (e.g. ``cssclass_month`` ``cssclass_noday``), one can replace the " +"single CSS class with a space separated list of CSS classes, for example::" +msgstr "" +"注意雖然上面提到的 CSS 屬性名稱是單數（例如 ``cssclass_month``、" +"``cssclass_noday``），你可以使用多個以空格隔開的 CSS 類別取代單一 CSS 類別，" +"例如： ::" + +#: ../../library/calendar.rst:331 +msgid "\"text-bold text-red\"" +msgstr "\"text-bold text-red\"" + +#: ../../library/calendar.rst:333 +msgid "Here is an example how :class:`!HTMLCalendar` can be customized::" +msgstr "以下是客製化 :class:`!HTMLCalendar` 的範例： ::" + +#: ../../library/calendar.rst:335 +msgid "" +"class CustomHTMLCal(calendar.HTMLCalendar):\n" +" cssclasses = [style + \" text-nowrap\" for style in\n" +" calendar.HTMLCalendar.cssclasses]\n" +" cssclass_month_head = \"text-center month-head\"\n" +" cssclass_month = \"text-center month\"\n" +" cssclass_year = \"text-italic lead\"" +msgstr "" +"class CustomHTMLCal(calendar.HTMLCalendar):\n" +" cssclasses = [style + \" text-nowrap\" for style in\n" +" calendar.HTMLCalendar.cssclasses]\n" +" cssclass_month_head = \"text-center month-head\"\n" +" cssclass_month = \"text-center month\"\n" +" cssclass_year = \"text-italic lead\"" + +#: ../../library/calendar.rst:345 +msgid "" +"This subclass of :class:`TextCalendar` can be passed a locale name in the " +"constructor and will return month and weekday names in the specified locale." +msgstr "" +":class:`TextCalendar` 的子類別，可以在建構函式傳入語系名稱，它會回傳指定語系" +"的月份及一週每一天的名稱。" + +#: ../../library/calendar.rst:351 +msgid "" +"This subclass of :class:`HTMLCalendar` can be passed a locale name in the " +"constructor and will return month and weekday names in the specified locale." +msgstr "" +":class:`HTMLCalendar` 的子類別，可以在建構函式傳入語系名稱，它會回傳指定語系" +"的月份及一週每一天的名稱。" + +#: ../../library/calendar.rst:357 +msgid "" +"The constructor, :meth:`!formatweekday` and :meth:`!formatmonthname` methods " +"of these two classes temporarily change the ``LC_TIME`` locale to the given " +"*locale*. Because the current locale is a process-wide setting, they are not " +"thread-safe." +msgstr "" +"這兩個類別的建構函式、:meth:`!formatweekday` 及 :meth:`!formatmonthname` 方法" +"會把 ``LC_TIME`` 語系暫時改成給定的 *locale*。因為目前的語系是屬於整個行程 " +"(process-wide) 的設定，它們不是執行緒安全的。" + +#: ../../library/calendar.rst:363 +msgid "For simple text calendars this module provides the following functions." +msgstr "這個模組提供以下函式給單純的文字日曆使用。" + +#: ../../library/calendar.rst:367 +msgid "" +"Sets the weekday (``0`` is Monday, ``6`` is Sunday) to start each week. The " +"values :const:`MONDAY`, :const:`TUESDAY`, :const:`WEDNESDAY`, :const:`THURSDAY`, :const:`FRIDAY`, :const:`SATURDAY`, " +"and :const:`SUNDAY` are provided for convenience. For example, to set the " +"first weekday to Sunday::" +msgstr "" +"設定一週的第一天（``0`` 是週一、``6`` 是週日）。提" +"供 :const:`MONDAY`、:const:`TUESDAY`、:const:`WEDNESDAY`、:const:`THURSDAY`、:const:`FRIDAY`、:const:`SATURDAY` " +"及 :const:`SUNDAY` 可以方便設定。例如設定一週的第一天為週日： ::" + +#: ../../library/calendar.rst:372 +msgid "" +"import calendar\n" +"calendar.setfirstweekday(calendar.SUNDAY)" +msgstr "" +"import calendar\n" +"calendar.setfirstweekday(calendar.SUNDAY)" + +#: ../../library/calendar.rst:378 +msgid "Returns the current setting for the weekday to start each week." +msgstr "回傳目前設定的一週的第一天。" + +#: ../../library/calendar.rst:383 +msgid "" +"Returns :const:`True` if *year* is a leap year, otherwise :const:`False`." +msgstr "如果 *year* 是閏年回傳 :const:`True`，否則回傳 :const:`False`。" + +#: ../../library/calendar.rst:388 +msgid "" +"Returns the number of leap years in the range from *y1* to *y2* (exclusive), " +"where *y1* and *y2* are years." +msgstr "" +"回傳從 *y1* 到 *y2*\\ （不包含）間有幾個閏年，其中 *y1* 和 *y2* 是年份。" + +#: ../../library/calendar.rst:391 +msgid "This function works for ranges spanning a century change." +msgstr "這個函式也適用在跨越世紀的時間範圍。" + +#: ../../library/calendar.rst:396 +msgid "" +"Returns the day of the week (``0`` is Monday) for *year* (``1970``--...), " +"*month* (``1``--``12``), *day* (``1``--``31``)." +msgstr "" +"回傳 *year* 年 (``1970``--...) *month* 月 (``1``--``12``) *day* 日 (``1``--" +"``31``) 是週幾（``0`` 是星期一）。" + +#: ../../library/calendar.rst:402 +msgid "" +"Return a header containing abbreviated weekday names. *n* specifies the " +"width in characters for one weekday." +msgstr "回傳包含一週每一天的名稱縮寫的標題。*n* 指定每一天的字元寬度。" + +#: ../../library/calendar.rst:408 +msgid "" +"Returns weekday of first day of the month and number of days in month, for " +"the specified *year* and *month*." +msgstr "回傳指定 *year* 年 *month* 月該月第一天代表週幾的數字及該月有多少天。" + +#: ../../library/calendar.rst:414 +msgid "" +"Returns a matrix representing a month's calendar. Each row represents a " +"week; days outside of the month are represented by zeros. Each week begins " +"with Monday unless set by :func:`setfirstweekday`." +msgstr "" +"回傳代表一個月份日曆的矩陣。每一列為一週；該月以外的日期以 0 表示。每一週以週" +"一開始，除非有使用 :func:`setfirstweekday` 改變設定。" + +#: ../../library/calendar.rst:421 +msgid "Prints a month's calendar as returned by :func:`month`." +msgstr "印出一個月份的日曆，跟 :func:`month` 回傳的內容一樣。" + +#: ../../library/calendar.rst:426 +msgid "" +"Returns a month's calendar in a multi-line string using " +"the :meth:`~TextCalendar.formatmonth` of the :class:`TextCalendar` class." +msgstr "" +"以多行字串的形式回傳一個月的日曆，使用 :class:`TextCalendar` 類別" +"的 :meth:`~TextCalendar.formatmonth`。" + +#: ../../library/calendar.rst:432 +msgid "" +"Prints the calendar for an entire year as returned by :func:`calendar`." +msgstr "印出一整年的日曆，跟 :func:`calendar` 回傳的內容一樣。" + +#: ../../library/calendar.rst:437 +msgid "" +"Returns a 3-column calendar for an entire year as a multi-line string using " +"the :meth:`~TextCalendar.formatyear` of the :class:`TextCalendar` class." +msgstr "" +"以多行字串回傳三欄形式的一整年日曆，使用 :class:`TextCalendar` 類別" +"的 :meth:`~TextCalendar.formatyear`。" + +#: ../../library/calendar.rst:443 +msgid "" +"An unrelated but handy function that takes a time tuple such as returned by " +"the :func:`~time.gmtime` function in the :mod:`time` module, and returns the " +"corresponding Unix timestamp value, assuming an epoch of 1970, and the POSIX " +"encoding. In fact, :func:`time.gmtime` and :func:`timegm` are each others' " +"inverse." +msgstr "" +"一個跟日曆無關但方便的函式，它接受一個像 :mod:`time` 模組裡" +"的 :func:`~time.gmtime` 函式回傳的元組，並回傳對應的 Unix 時間戳，假設從 " +"1970 開始及 POSIX 編碼。事實上，:func:`time.gmtime` 和 :func:`timegm` 是彼此" +"相反的。" + +#: ../../library/calendar.rst:450 +msgid "The :mod:`calendar` module exports the following data attributes:" +msgstr ":mod:`calendar` 模組匯出以下資料屬性：" + +#: ../../library/calendar.rst:454 +msgid "" +"A sequence that represents the days of the week in the current locale, where " +"Monday is day number 0." +msgstr "以目前語系來表示的一週每一天名稱的序列，其中週一是第 0 天。" + +#: ../../library/calendar.rst:464 +msgid "" +"A sequence that represents the abbreviated days of the week in the current " +"locale, where Mon is day number 0." +msgstr "以目前語系來表示的一週每一天縮寫名稱的序列，其中 Mon 是第 0 天。" + +#: ../../library/calendar.rst:479 +msgid "" +"Aliases for the days of the week, where ``MONDAY`` is ``0`` and ``SUNDAY`` " +"is ``6``." +msgstr "一週每一天的別名，其中 ``MONDAY`` 是 ``0`` 而 ``SUNDAY`` 是 ``6``。" + +#: ../../library/calendar.rst:487 +msgid "" +"Enumeration defining days of the week as integer constants. The members of " +"this enumeration are exported to the module scope as :data:`MONDAY` " +"through :data:`SUNDAY`." +msgstr "" +"將一週中的幾天定義為整數常數的列舉。此列舉的成員將作為 :data:`MONDAY` " +"到 :data:`SUNDAY` 匯出到模組作用域。" + +#: ../../library/calendar.rst:496 +msgid "" +"A sequence that represents the months of the year in the current locale. " +"This follows normal convention of January being month number 1, so it has a " +"length of 13 and ``month_name[0]`` is the empty string." +msgstr "" +"以目前語系來表示的一年每個月份名稱的序列。它按照一般慣例以數字 1 代表一月，因" +"此它的長度為 13，而 ``month_name[0]`` 是空字串。" + +#: ../../library/calendar.rst:507 +msgid "" +"A sequence that represents the abbreviated months of the year in the current " +"locale. This follows normal convention of January being month number 1, so " +"it has a length of 13 and ``month_abbr[0]`` is the empty string." +msgstr "" +"以目前語系來表示的一年每個月份縮寫名稱的序列。它按照一般慣例以數字 1 代表一" +"月，因此它的長度為 13，而 ``month_abbr[0]`` 是空字串。" + +#: ../../library/calendar.rst:528 +msgid "" +"Aliases for the months of the year, where ``JANUARY`` is ``1`` and " +"``DECEMBER`` is ``12``." +msgstr "" +"一年內每個月的別名，其中 ``JANUARY`` 是 ``1`` 而 ``DECEMBER`` 是 ``12``。" + +#: ../../library/calendar.rst:536 +msgid "" +"Enumeration defining months of the year as integer constants. The members of " +"this enumeration are exported to the module scope as :data:`JANUARY` " +"through :data:`DECEMBER`." +msgstr "" +"將一年中的月份定義為整數常數的列舉。此列舉的成員將作為 :data:`JANUARY` " +"到 :data:`DECEMBER` 匯出到模組作用域。" + +#: ../../library/calendar.rst:543 +msgid "The :mod:`calendar` module defines the following exceptions:" +msgstr ":mod:`calendar` 模組定義了以下例外：" + +#: ../../library/calendar.rst:547 +msgid "" +"A subclass of :exc:`ValueError`, raised when the given month number is " +"outside of the range 1-12 (inclusive)." +msgstr "" +":exc:`ValueError` 的子類別，當給定的月份數字超出 1-12 範圍（含）時引發。" + +#: ../../library/calendar.rst:552 +msgid "The invalid month number." +msgstr "無效的月份號。" + +#: ../../library/calendar.rst:557 +msgid "" +"A subclass of :exc:`ValueError`, raised when the given weekday number is " +"outside of the range 0-6 (inclusive)." +msgstr "" +":exc:`ValueError` 的子類別，當給定的週幾的數字超出 0-6（含）範圍時引發。" + +#: ../../library/calendar.rst:562 +msgid "The invalid weekday number." +msgstr "無效的週幾編號。" + +#: ../../library/calendar.rst:567 +msgid "Module :mod:`datetime`" +msgstr ":mod:`datetime` 模組" + +#: ../../library/calendar.rst:568 +msgid "" +"Object-oriented interface to dates and times with similar functionality to " +"the :mod:`time` module." +msgstr "日期與時間的物件導向介面，和 :mod:`time` 模組有相似的功能。" + +#: ../../library/calendar.rst:571 +msgid "Module :mod:`time`" +msgstr ":mod:`time` 模組" + +#: ../../library/calendar.rst:572 +msgid "Low-level time related functions." +msgstr "底層的時間相關函式。" + +#: ../../library/calendar.rst:578 +msgid "Command-line usage" +msgstr "命令列用法" + +#: ../../library/calendar.rst:582 +msgid "" +"The :mod:`calendar` module can be executed as a script from the command line " +"to interactively print a calendar." +msgstr ":mod:`calendar` 模組可以作為腳本從命令列執行，並以互動方式列印日曆。" + +#: ../../library/calendar.rst:585 +msgid "" +"python -m calendar [-h] [-L LOCALE] [-e ENCODING] [-t {text,html}]\n" +" [-w WIDTH] [-l LINES] [-s SPACING] [-m MONTHS] [-c CSS]\n" +" [-f FIRST_WEEKDAY] [year] [month]" +msgstr "" +"python -m calendar [-h] [-L LOCALE] [-e ENCODING] [-t {text,html}]\n" +" [-w WIDTH] [-l LINES] [-s SPACING] [-m MONTHS] [-c CSS]\n" +" [-f FIRST_WEEKDAY] [year] [month]" + +#: ../../library/calendar.rst:592 +msgid "For example, to print a calendar for the year 2000:" +msgstr "例如，要列印 2000 年的日曆：" + +#: ../../library/calendar.rst:594 +msgid "" +"$ python -m calendar 2000\n" +" 2000\n" +"\n" +" January February March\n" +"Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su\n" +" 1 2 1 2 3 4 5 6 1 2 3 4 5\n" +" 3 4 5 6 7 8 9 7 8 9 10 11 12 13 6 7 8 9 10 11 12\n" +"10 11 12 13 14 15 16 14 15 16 17 18 19 20 13 14 15 16 17 18 19\n" +"17 18 19 20 21 22 23 21 22 23 24 25 26 27 20 21 22 23 24 25 26\n" +"24 25 26 27 28 29 30 28 29 27 28 29 30 31\n" +"31\n" +"\n" +" April May June\n" +"Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su\n" +" 1 2 1 2 3 4 5 6 7 1 2 3 4\n" +" 3 4 5 6 7 8 9 8 9 10 11 12 13 14 5 6 7 8 9 10 11\n" +"10 11 12 13 14 15 16 15 16 17 18 19 20 21 12 13 14 15 16 17 18\n" +"17 18 19 20 21 22 23 22 23 24 25 26 27 28 19 20 21 22 23 24 25\n" +"24 25 26 27 28 29 30 29 30 31 26 27 28 29 30\n" +"\n" +" July August September\n" +"Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su\n" +" 1 2 1 2 3 4 5 6 1 2 3\n" +" 3 4 5 6 7 8 9 7 8 9 10 11 12 13 4 5 6 7 8 9 10\n" +"10 11 12 13 14 15 16 14 15 16 17 18 19 20 11 12 13 14 15 16 17\n" +"17 18 19 20 21 22 23 21 22 23 24 25 26 27 18 19 20 21 22 23 24\n" +"24 25 26 27 28 29 30 28 29 30 31 25 26 27 28 29 30\n" +"31\n" +"\n" +" October November December\n" +"Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su\n" +" 1 1 2 3 4 5 1 2 3\n" +" 2 3 4 5 6 7 8 6 7 8 9 10 11 12 4 5 6 7 8 9 10\n" +" 9 10 11 12 13 14 15 13 14 15 16 17 18 19 11 12 13 14 15 16 17\n" +"16 17 18 19 20 21 22 20 21 22 23 24 25 26 18 19 20 21 22 23 24\n" +"23 24 25 26 27 28 29 27 28 29 30 25 26 27 28 29 30 31\n" +"30 31" +msgstr "" +"$ python -m calendar 2000\n" +" 2000\n" +"\n" +" January February March\n" +"Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su\n" +" 1 2 1 2 3 4 5 6 1 2 3 4 5\n" +" 3 4 5 6 7 8 9 7 8 9 10 11 12 13 6 7 8 9 10 11 12\n" +"10 11 12 13 14 15 16 14 15 16 17 18 19 20 13 14 15 16 17 18 19\n" +"17 18 19 20 21 22 23 21 22 23 24 25 26 27 20 21 22 23 24 25 26\n" +"24 25 26 27 28 29 30 28 29 27 28 29 30 31\n" +"31\n" +"\n" +" April May June\n" +"Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su\n" +" 1 2 1 2 3 4 5 6 7 1 2 3 4\n" +" 3 4 5 6 7 8 9 8 9 10 11 12 13 14 5 6 7 8 9 10 11\n" +"10 11 12 13 14 15 16 15 16 17 18 19 20 21 12 13 14 15 16 17 18\n" +"17 18 19 20 21 22 23 22 23 24 25 26 27 28 19 20 21 22 23 24 25\n" +"24 25 26 27 28 29 30 29 30 31 26 27 28 29 30\n" +"\n" +" July August September\n" +"Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su\n" +" 1 2 1 2 3 4 5 6 1 2 3\n" +" 3 4 5 6 7 8 9 7 8 9 10 11 12 13 4 5 6 7 8 9 10\n" +"10 11 12 13 14 15 16 14 15 16 17 18 19 20 11 12 13 14 15 16 17\n" +"17 18 19 20 21 22 23 21 22 23 24 25 26 27 18 19 20 21 22 23 24\n" +"24 25 26 27 28 29 30 28 29 30 31 25 26 27 28 29 30\n" +"31\n" +"\n" +" October November December\n" +"Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su\n" +" 1 1 2 3 4 5 1 2 3\n" +" 2 3 4 5 6 7 8 6 7 8 9 10 11 12 4 5 6 7 8 9 10\n" +" 9 10 11 12 13 14 15 13 14 15 16 17 18 19 11 12 13 14 15 16 17\n" +"16 17 18 19 20 21 22 20 21 22 23 24 25 26 18 19 20 21 22 23 24\n" +"23 24 25 26 27 28 29 27 28 29 30 25 26 27 28 29 30 31\n" +"30 31" + +#: ../../library/calendar.rst:635 +msgid "The following options are accepted:" +msgstr "接受以下選項：" + +#: ../../library/calendar.rst:642 +msgid "Show the help message and exit." +msgstr "顯示幫助訊息並退出。" + +#: ../../library/calendar.rst:647 +msgid "The locale to use for month and weekday names. Defaults to English." +msgstr "用於月份和週幾名稱的語系。預設為英語。" + +#: ../../library/calendar.rst:653 +msgid "" +"The encoding to use for output. :option:`--encoding` is required " +"if :option:`--locale` is set." +msgstr "" +"用於輸出的編碼。如有設定 :option:`--locale` 則必須給定 :option:`--encoding`。" + +#: ../../library/calendar.rst:659 +msgid "Print the calendar to the terminal as text, or as an HTML document." +msgstr "將日曆以文字或 HTML 文件的形式印出到終端機。" + +#: ../../library/calendar.rst:665 +msgid "" +"The weekday to start each week. Must be a number between 0 (Monday) and 6 " +"(Sunday). Defaults to 0." +msgstr "一週起始的日子。必須是 0（週一）到 6（週日）之間的數字。預設為 0。" + +#: ../../library/calendar.rst:673 +msgid "The year to print the calendar for. Defaults to the current year." +msgstr "印出日曆的年份。預設為目前年份。" + +#: ../../library/calendar.rst:679 +msgid "" +"The month of the specified :option:`year` to print the calendar for. Must be " +"a number between 1 and 12, and may only be used in text mode. Defaults to " +"printing a calendar for the full year." +msgstr "" +"要列印日曆的指定 :option:`year` 的月份。必須是 1 到 12 之間的數字，並且只能在" +"文字模式下使用。預設列印全年日曆。" + +#: ../../library/calendar.rst:685 +msgid "*Text-mode options:*" +msgstr "*文字模式選項：*" + +#: ../../library/calendar.rst:689 +msgid "" +"The width of the date column in terminal columns. The date is printed " +"centred in the column. Any value lower than 2 is ignored. Defaults to 2." +msgstr "" +"終端機行中日期行的寬度。日期印出在行的中央。任何小於 2 的值都會被忽略。預設" +"為 2。" + +#: ../../library/calendar.rst:697 +msgid "" +"The number of lines for each week in terminal rows. The date is printed top-" +"aligned. Any value lower than 1 is ignored. Defaults to 1." +msgstr "" +"終端機列中每週的列數。日期印出時頂部會對齊。任何小於 1 的值都會被忽略。預設" +"為 1。" + +#: ../../library/calendar.rst:705 +msgid "" +"The space between months in columns. Any value lower than 2 is ignored. " +"Defaults to 6." +msgstr "行中月份之間的間距。任何小於 2 的值都會被忽略。預設為 6。" + +#: ../../library/calendar.rst:712 +msgid "The number of months printed per row. Defaults to 3." +msgstr "每列印出的月份數量。預設為 3。" + +#: ../../library/calendar.rst:715 +msgid "" +"By default, today's date is highlighted in color and can be :ref:`controlled " +"using environment variables `." +msgstr "" + +#: ../../library/calendar.rst:719 +msgid "*HTML-mode options:*" +msgstr "*HTML 模式選項：*" + +#: ../../library/calendar.rst:723 +msgid "" +"The path of a CSS stylesheet to use for the calendar. This must either be " +"relative to the generated HTML, or an absolute HTTP or ``file:///`` URL." +msgstr "" +"用於日曆的 CSS 樣式表路徑。這必須是相對於產生之 HTML 的，或者為絕對的 HTTP " +"或 ``file:///`` URL。" diff --git a/library/cgi.po b/library/cgi.po index 0731e1b501..4cfe704b60 100644 --- a/library/cgi.po +++ b/library/cgi.po @@ -1,48 +1,48 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -#, fuzzy -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-11-18 00:15+0000\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" -"tw)\n" -"Language: zh_TW\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=UTF-8\n" -"Content-Transfer-Encoding: 8bit\n" - -#: ../../library/cgi.rst:2 -msgid ":mod:`!cgi` --- Common Gateway Interface support" -msgstr ":mod:`!cgi` --- 通用閘道器介面支援" - -#: ../../library/cgi.rst:10 -msgid "" -"This module is no longer part of the Python standard library. It was :ref:" -"`removed in Python 3.13 ` after being deprecated in " -"Python 3.11. The removal was decided in :pep:`594`." -msgstr "" -"這個模組已不再是 Python 標準函式庫的一部分。它在 Python 3.11 中被棄用，並\\ :" -"ref:`已在 Python 3.13 中被移除 `。它的移除是在 :pep:" -"`594` 中決定的。" - -#: ../../library/cgi.rst:14 -msgid "" -"A fork of the module on PyPI can be used instead: :pypi:`legacy-cgi`. This " -"is a copy of the cgi module, no longer maintained or supported by the core " -"Python team." -msgstr "" -"可以改用 PyPI 上的模組 fork：:pypi:`legacy-cgi`。這是 cgi 模組的一個副本，不" -"再由 Python 核心團隊維護或支援。" - -#: ../../library/cgi.rst:18 -msgid "" -"The last version of Python that provided the :mod:`!cgi` module was `Python " -"3.12 `_." -msgstr "" -"最後提供 :mod:`!cgi` 模組的 Python 版本是 `Python 3.12 `_。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-11-18 00:15+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" +"tw)\n" +"Language: zh_TW\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../library/cgi.rst:2 +msgid ":mod:`!cgi` --- Common Gateway Interface support" +msgstr ":mod:`!cgi` --- 通用閘道器介面支援" + +#: ../../library/cgi.rst:10 +msgid "" +"This module is no longer part of the Python standard library. It was :ref:" +"`removed in Python 3.13 ` after being deprecated in " +"Python 3.11. The removal was decided in :pep:`594`." +msgstr "" +"這個模組已不再是 Python 標準函式庫的一部分。它在 Python 3.11 中被棄用，並\\ :" +"ref:`已在 Python 3.13 中被移除 `。它的移除是在 :pep:" +"`594` 中決定的。" + +#: ../../library/cgi.rst:14 +msgid "" +"A fork of the module on PyPI can be used instead: :pypi:`legacy-cgi`. This " +"is a copy of the cgi module, no longer maintained or supported by the core " +"Python team." +msgstr "" +"可以改用 PyPI 上的模組 fork：:pypi:`legacy-cgi`。這是 cgi 模組的一個副本，不" +"再由 Python 核心團隊維護或支援。" + +#: ../../library/cgi.rst:18 +msgid "" +"The last version of Python that provided the :mod:`!cgi` module was `Python " +"3.12 `_." +msgstr "" +"最後提供 :mod:`!cgi` 模組的 Python 版本是 `Python 3.12 `_。" diff --git a/library/cgitb.po b/library/cgitb.po index 2e8508be52..91767083b3 100644 --- a/library/cgitb.po +++ b/library/cgitb.po @@ -1,48 +1,48 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -#, fuzzy -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-11-18 00:15+0000\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" -"tw)\n" -"Language: zh_TW\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=UTF-8\n" -"Content-Transfer-Encoding: 8bit\n" - -#: ../../library/cgitb.rst:2 -msgid ":mod:`!cgitb` --- Traceback manager for CGI scripts" -msgstr ":mod:`!cgitb` --- CGI 腳本的回溯管理器 (traceback manager)" - -#: ../../library/cgitb.rst:10 -msgid "" -"This module is no longer part of the Python standard library. It was :ref:" -"`removed in Python 3.13 ` after being deprecated in " -"Python 3.11. The removal was decided in :pep:`594`." -msgstr "" -"這個模組已不再是 Python 標準函式庫的一部分。它在 Python 3.11 中被棄用，並\\ :" -"ref:`已在 Python 3.13 中被移除 `。它的移除是在 :pep:" -"`594` 中決定的。" - -#: ../../library/cgitb.rst:14 -msgid "" -"A fork of the module on PyPI can now be used instead: :pypi:`legacy-cgi`. " -"This is a copy of the cgi module, no longer maintained or supported by the " -"core Python team." -msgstr "" -"可以改用 PyPI 上的模組 fork：:pypi:`legacy-cgi`。這是 cgi 模組的一個複本，不" -"再由 Python 核心團隊維護或支援。" - -#: ../../library/cgitb.rst:18 -msgid "" -"The last version of Python that provided the :mod:`!cgitb` module was " -"`Python 3.12 `_." -msgstr "" -"最後提供 :mod:`!cgitb` 模組的 Python 版本是 `Python 3.12 `_。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-11-18 00:15+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" +"tw)\n" +"Language: zh_TW\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../library/cgitb.rst:2 +msgid ":mod:`!cgitb` --- Traceback manager for CGI scripts" +msgstr ":mod:`!cgitb` --- CGI 腳本的回溯管理器 (traceback manager)" + +#: ../../library/cgitb.rst:10 +msgid "" +"This module is no longer part of the Python standard library. It was :ref:" +"`removed in Python 3.13 ` after being deprecated in " +"Python 3.11. The removal was decided in :pep:`594`." +msgstr "" +"這個模組已不再是 Python 標準函式庫的一部分。它在 Python 3.11 中被棄用，並\\ :" +"ref:`已在 Python 3.13 中被移除 `。它的移除是在 :pep:" +"`594` 中決定的。" + +#: ../../library/cgitb.rst:14 +msgid "" +"A fork of the module on PyPI can now be used instead: :pypi:`legacy-cgi`. " +"This is a copy of the cgi module, no longer maintained or supported by the " +"core Python team." +msgstr "" +"可以改用 PyPI 上的模組 fork：:pypi:`legacy-cgi`。這是 cgi 模組的一個複本，不" +"再由 Python 核心團隊維護或支援。" + +#: ../../library/cgitb.rst:18 +msgid "" +"The last version of Python that provided the :mod:`!cgitb` module was " +"`Python 3.12 `_." +msgstr "" +"最後提供 :mod:`!cgitb` 模組的 Python 版本是 `Python 3.12 `_。" diff --git a/library/chunk.po b/library/chunk.po index 2a720ed424..80566cbd35 100644 --- a/library/chunk.po +++ b/library/chunk.po @@ -1,39 +1,39 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -#, fuzzy -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-11-18 00:15+0000\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" -"tw)\n" -"Language: zh_TW\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=UTF-8\n" -"Content-Transfer-Encoding: 8bit\n" - -#: ../../library/chunk.rst:2 -msgid ":mod:`!chunk` --- Read IFF chunked data" -msgstr ":mod:`!chunk` --- 讀取 IFF 分塊資料" - -#: ../../library/chunk.rst:10 -msgid "" -"This module is no longer part of the Python standard library. It was :ref:" -"`removed in Python 3.13 ` after being deprecated in " -"Python 3.11. The removal was decided in :pep:`594`." -msgstr "" -"這個模組已不再是 Python 標準函式庫的一部分。它在 Python 3.11 中被棄用，並\\ :" -"ref:`已在 Python 3.13 中被移除 `。它的移除是在 :pep:" -"`594` 中決定的。" - -#: ../../library/chunk.rst:14 -msgid "" -"The last version of Python that provided the :mod:`!chunk` module was " -"`Python 3.12 `_." -msgstr "" -"最後提供 :mod:`!chunk` 模組的 Python 版本是 `Python 3.12 `_。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-11-18 00:15+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" +"tw)\n" +"Language: zh_TW\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../library/chunk.rst:2 +msgid ":mod:`!chunk` --- Read IFF chunked data" +msgstr ":mod:`!chunk` --- 讀取 IFF 分塊資料" + +#: ../../library/chunk.rst:10 +msgid "" +"This module is no longer part of the Python standard library. It was :ref:" +"`removed in Python 3.13 ` after being deprecated in " +"Python 3.11. The removal was decided in :pep:`594`." +msgstr "" +"這個模組已不再是 Python 標準函式庫的一部分。它在 Python 3.11 中被棄用，並\\ :" +"ref:`已在 Python 3.13 中被移除 `。它的移除是在 :pep:" +"`594` 中決定的。" + +#: ../../library/chunk.rst:14 +msgid "" +"The last version of Python that provided the :mod:`!chunk` module was " +"`Python 3.12 `_." +msgstr "" +"最後提供 :mod:`!chunk` 模組的 Python 版本是 `Python 3.12 `_。" diff --git a/library/cmath.po b/library/cmath.po index 1106996067..8f181c71f3 100644 --- a/library/cmath.po +++ b/library/cmath.po @@ -1,702 +1,702 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-10-15 00:16+0000\n" -"PO-Revision-Date: 2024-03-14 09:26+0800\n" -"Last-Translator: Enkai Huang \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" -"X-Generator: Poedit 3.4.2\n" - -#: ../../library/cmath.rst:2 -msgid ":mod:`!cmath` --- Mathematical functions for complex numbers" -msgstr ":mod:`!cmath` --- 複數的數學函式" - -#: ../../library/cmath.rst:9 -msgid "" -"This module provides access to mathematical functions for complex numbers. " -"The functions in this module accept integers, floating-point numbers or " -"complex numbers as arguments. They will also accept any Python object that " -"has either a :meth:`~object.__complex__` or a :meth:`~object.__float__` " -"method: these methods are used to convert the object to a complex or " -"floating-point number, respectively, and the function is then applied to the " -"result of the conversion." -msgstr "" -"本模組提供一些適用於複數的數學函式。本模組中的函式接受整數、浮點數或複數作為" -"引數。它們也接受任何具有 :meth:`~object.__complex__` 或 :meth:`~object." -"__float__` 方法的 Python 物件：這些方法分別用於將物件轉換為複數或浮點數，然後" -"再將函式應用於轉換後的結果。" - -#: ../../library/cmath.rst:18 -msgid "" -"For functions involving branch cuts, we have the problem of deciding how to " -"define those functions on the cut itself. Following Kahan's \"Branch cuts " -"for complex elementary functions\" paper, as well as Annex G of C99 and " -"later C standards, we use the sign of zero to distinguish one side of the " -"branch cut from the other: for a branch cut along (a portion of) the real " -"axis we look at the sign of the imaginary part, while for a branch cut along " -"the imaginary axis we look at the sign of the real part." -msgstr "" -"對於涉及分枝切割 (branch cut) 的函式，我們面臨的問題是決定如何定義在切割本身" -"上的這些函式。遵循 Kahan 的論文 \"Branch cuts for complex elementary " -"functions\"，以及 C99 的附錄 G 和後來的 C 標準，我們使用零符號來區分分枝切割" -"的兩側：對於沿著（一部分）實數軸的分枝切割，我們查看虛部的符號，而對於沿虛軸" -"的分枝切割，我們則查看實部的符號。" - -#: ../../library/cmath.rst:26 -msgid "" -"For example, the :func:`cmath.sqrt` function has a branch cut along the " -"negative real axis. An argument of ``-2-0j`` is treated as though it lies " -"*below* the branch cut, and so gives a result on the negative imaginary " -"axis::" -msgstr "" -"例如 :func:`cmath.sqrt` 函式具有一條沿負實軸的分枝切割。 引數 ``-2-0j`` 被視" -"為位於分枝切割 *下方* 處理，因此給出的結果在負虛軸上： ::" - -#: ../../library/cmath.rst:31 -msgid "" -">>> cmath.sqrt(-2-0j)\n" -"-1.4142135623730951j" -msgstr "" -">>> cmath.sqrt(-2-0j)\n" -"-1.4142135623730951j" - -#: ../../library/cmath.rst:34 -msgid "" -"But an argument of ``-2+0j`` is treated as though it lies above the branch " -"cut::" -msgstr "但是引數 ``-2+0j`` 會被當成位於分枝切割上方處理： ::" - -#: ../../library/cmath.rst:37 -msgid "" -">>> cmath.sqrt(-2+0j)\n" -"1.4142135623730951j" -msgstr "" -">>> cmath.sqrt(-2+0j)\n" -"1.4142135623730951j" - -#: ../../library/cmath.rst:42 -msgid "**Conversions to and from polar coordinates**" -msgstr "**轉換到極座標和從極座標做轉換**" - -#: ../../library/cmath.rst:44 -msgid ":func:`phase(z) `" -msgstr ":func:`phase(z) `" - -#: ../../library/cmath.rst:44 -msgid "Return the phase of *z*" -msgstr "回傳 *z* 的相位角。" - -#: ../../library/cmath.rst:45 -msgid ":func:`polar(z) `" -msgstr ":func:`polar(z) `" - -#: ../../library/cmath.rst:45 -msgid "Return the representation of *z* in polar coordinates" -msgstr "回傳 *z* 在極座標中的表達方式。" - -#: ../../library/cmath.rst:46 -msgid ":func:`rect(r, phi) `" -msgstr ":func:`rect(r, phi) `" - -#: ../../library/cmath.rst:46 -msgid "Return the complex number *z* with polar coordinates *r* and *phi*" -msgstr "透過極座標 *r* 和 *phi* 回傳複數 *z*。" - -#: ../../library/cmath.rst:48 -msgid "**Power and logarithmic functions**" -msgstr "**冪函數和對數函數**" - -#: ../../library/cmath.rst:50 -msgid ":func:`exp(z) `" -msgstr ":func:`exp(z) `" - -#: ../../library/cmath.rst:50 -msgid "Return *e* raised to the power *z*" -msgstr "回傳 *e* 的 *z* 次方。" - -#: ../../library/cmath.rst:51 -msgid ":func:`log(z[, base]) `" -msgstr ":func:`log(z[, base]) `" - -#: ../../library/cmath.rst:51 -msgid "Return the logarithm of *z* to the given *base* (*e* by default)" -msgstr "回傳 *z* 以給定 *base* 為底（預設為 *e*）的對數。" - -#: ../../library/cmath.rst:52 -msgid ":func:`log10(z) `" -msgstr ":func:`log10(z) `" - -#: ../../library/cmath.rst:52 -msgid "Return the base-10 logarithm of *z*" -msgstr "回傳 *z* 以 10 為底的對數。" - -#: ../../library/cmath.rst:53 -msgid ":func:`sqrt(z) `" -msgstr ":func:`sqrt(z) `" - -#: ../../library/cmath.rst:53 -msgid "Return the square root of *z*" -msgstr "回傳 *z* 的平方根。" - -#: ../../library/cmath.rst:55 -msgid "**Trigonometric functions**" -msgstr "**三角函數**" - -#: ../../library/cmath.rst:57 -msgid ":func:`acos(z) `" -msgstr ":func:`acos(z) `" - -#: ../../library/cmath.rst:57 -msgid "Return the arc cosine of *z*" -msgstr "回傳 *z* 的反餘弦值。" - -#: ../../library/cmath.rst:58 -msgid ":func:`asin(z) `" -msgstr ":func:`asin(z) `" - -#: ../../library/cmath.rst:58 -msgid "Return the arc sine of *z*" -msgstr "回傳 *z* 的反正弦值。" - -#: ../../library/cmath.rst:59 -msgid ":func:`atan(z) `" -msgstr ":func:`atan(z) `" - -#: ../../library/cmath.rst:59 -msgid "Return the arc tangent of *z*" -msgstr "回傳 *z* 的反正切值。" - -#: ../../library/cmath.rst:60 -msgid ":func:`cos(z) `" -msgstr ":func:`cos(z) `" - -#: ../../library/cmath.rst:60 -msgid "Return the cosine of *z*" -msgstr "回傳 *z* 的餘弦值。" - -#: ../../library/cmath.rst:61 -msgid ":func:`sin(z) `" -msgstr ":func:`sin(z) `" - -#: ../../library/cmath.rst:61 -msgid "Return the sine of *z*" -msgstr "回傳 *z* 的正弦值。" - -#: ../../library/cmath.rst:62 -msgid ":func:`tan(z) `" -msgstr ":func:`tan(z) `" - -#: ../../library/cmath.rst:62 -msgid "Return the tangent of *z*" -msgstr "回傳 *z* 的正切值。" - -#: ../../library/cmath.rst:64 -msgid "**Hyperbolic functions**" -msgstr "**雙曲函數**" - -#: ../../library/cmath.rst:66 -msgid ":func:`acosh(z) `" -msgstr ":func:`acosh(z) `" - -#: ../../library/cmath.rst:66 -msgid "Return the inverse hyperbolic cosine of *z*" -msgstr "回傳 *z* 的反雙曲餘弦值。" - -#: ../../library/cmath.rst:67 -msgid ":func:`asinh(z) `" -msgstr ":func:`asinh(z) `" - -#: ../../library/cmath.rst:67 -msgid "Return the inverse hyperbolic sine of *z*" -msgstr "回傳 *z* 的反雙曲正弦值。" - -#: ../../library/cmath.rst:68 -msgid ":func:`atanh(z) `" -msgstr ":func:`atanh(z) `" - -#: ../../library/cmath.rst:68 -msgid "Return the inverse hyperbolic tangent of *z*" -msgstr "回傳 *z* 的反雙曲正切值。" - -#: ../../library/cmath.rst:69 -msgid ":func:`cosh(z) `" -msgstr ":func:`cosh(z) `" - -#: ../../library/cmath.rst:69 -msgid "Return the hyperbolic cosine of *z*" -msgstr "回傳 *z* 的雙曲餘弦值。" - -#: ../../library/cmath.rst:70 -msgid ":func:`sinh(z) `" -msgstr ":func:`sinh(z) `" - -#: ../../library/cmath.rst:70 -msgid "Return the hyperbolic sine of *z*" -msgstr "回傳 *z* 的雙曲正弦值。" - -#: ../../library/cmath.rst:71 -msgid ":func:`tanh(z) `" -msgstr ":func:`tanh(z) `" - -#: ../../library/cmath.rst:71 -msgid "Return the hyperbolic tangent of *z*" -msgstr "回傳 *z* 的雙曲正切值。" - -#: ../../library/cmath.rst:73 -msgid "**Classification functions**" -msgstr "**分類函數**" - -#: ../../library/cmath.rst:75 -msgid ":func:`isfinite(z) `" -msgstr ":func:`isfinite(z) `" - -#: ../../library/cmath.rst:75 -msgid "Check if all components of *z* are finite" -msgstr "" - -#: ../../library/cmath.rst:76 -msgid ":func:`isinf(z) `" -msgstr ":func:`isinf(z) `" - -#: ../../library/cmath.rst:76 -msgid "Check if any component of *z* is infinite" -msgstr "" - -#: ../../library/cmath.rst:77 -msgid ":func:`isnan(z) `" -msgstr ":func:`isnan(z) `" - -#: ../../library/cmath.rst:77 -msgid "Check if any component of *z* is a NaN" -msgstr "" - -#: ../../library/cmath.rst:78 -msgid ":func:`isclose(a, b, *, rel_tol, abs_tol) `" -msgstr ":func:`isclose(a, b, *, rel_tol, abs_tol) `" - -#: ../../library/cmath.rst:78 -msgid "Check if the values *a* and *b* are close to each other" -msgstr "檢查 *a* 和 *b* 的值是否接近" - -#: ../../library/cmath.rst:80 -msgid "**Constants**" -msgstr "**常數**" - -#: ../../library/cmath.rst:82 -msgid ":data:`pi`" -msgstr ":data:`pi`" - -#: ../../library/cmath.rst:82 -msgid "*π* = 3.141592..." -msgstr "*π* = 3.141592..." - -#: ../../library/cmath.rst:83 -msgid ":data:`e`" -msgstr ":data:`e`" - -#: ../../library/cmath.rst:83 -msgid "*e* = 2.718281..." -msgstr "*e* = 2.718281..." - -#: ../../library/cmath.rst:84 -msgid ":data:`tau`" -msgstr ":data:`tau`" - -#: ../../library/cmath.rst:84 -msgid "*τ* = 2\\ *π* = 6.283185..." -msgstr "*τ* = 2\\ *π* = 6.283185..." - -#: ../../library/cmath.rst:85 -msgid ":data:`inf`" -msgstr ":data:`inf`" - -#: ../../library/cmath.rst:85 -msgid "Positive infinity" -msgstr "" - -#: ../../library/cmath.rst:86 -msgid ":data:`infj`" -msgstr ":data:`infj`" - -#: ../../library/cmath.rst:86 -msgid "Pure imaginary infinity" -msgstr "" - -#: ../../library/cmath.rst:87 -msgid ":data:`nan`" -msgstr ":data:`nan`" - -#: ../../library/cmath.rst:87 -msgid "\"Not a number\" (NaN)" -msgstr "" - -#: ../../library/cmath.rst:88 -msgid ":data:`nanj`" -msgstr ":data:`nanj`" - -#: ../../library/cmath.rst:88 -msgid "Pure imaginary NaN" -msgstr "" - -#: ../../library/cmath.rst:93 -msgid "Conversions to and from polar coordinates" -msgstr "轉換到極座標和從極座標做轉換" - -#: ../../library/cmath.rst:95 -msgid "" -"A Python complex number ``z`` is stored internally using *rectangular* or " -"*Cartesian* coordinates. It is completely determined by its *real part* ``z." -"real`` and its *imaginary part* ``z.imag``." -msgstr "" -"Python 複數 ``z`` 是用 *直角坐標* 或 *笛卡爾坐標* 儲存在內部的。它完全是由其 " -"*實部* ``z.real`` 和 *虛部* ``z.imag`` 所決定。" - -#: ../../library/cmath.rst:99 -msgid "" -"*Polar coordinates* give an alternative way to represent a complex number. " -"In polar coordinates, a complex number *z* is defined by the modulus *r* and " -"the phase angle *phi*. The modulus *r* is the distance from *z* to the " -"origin, while the phase *phi* is the counterclockwise angle, measured in " -"radians, from the positive x-axis to the line segment that joins the origin " -"to *z*." -msgstr "" -"*極座標* 提供了另一種表示複數的方法。在極座標中，複數 *z* 由絕對值 (modulus) " -"*r* 和相位角 (phase) *phi* 定義。絕對值 *r* 是從 *z* 到原點的距離，而相位角 " -"*phi* 是從正 x 軸到連接原點到 *z* 的線段的逆時針角度（以弧度為單位）。" - -#: ../../library/cmath.rst:106 -msgid "" -"The following functions can be used to convert from the native rectangular " -"coordinates to polar coordinates and back." -msgstr "以下的函式可用於原始直角座標與極座標之間的相互轉換。" - -#: ../../library/cmath.rst:111 -msgid "" -"Return the phase of *z* (also known as the *argument* of *z*), as a float. " -"``phase(z)`` is equivalent to ``math.atan2(z.imag, z.real)``. The result " -"lies in the range [-\\ *π*, *π*], and the branch cut for this operation lies " -"along the negative real axis. The sign of the result is the same as the " -"sign of ``z.imag``, even when ``z.imag`` is zero::" -msgstr "" -"以浮點數的形式回傳 *z* 的相位角（也稱為 *z* 的 *引數* ）。``phase(z)`` 等價" -"於 ``math.atan2(z.imag, z.real)``。結果將位於 [-\\ *π*, *π*] 的範圍內，且此操" -"作的分枝切割將位於負實軸上。結果的符號會與 ``z.imag`` 的符號相同，即使 ``z." -"imag`` 為零： ::" - -#: ../../library/cmath.rst:117 -msgid "" -">>> phase(-1+0j)\n" -"3.141592653589793\n" -">>> phase(-1-0j)\n" -"-3.141592653589793" -msgstr "" -">>> phase(-1+0j)\n" -"3.141592653589793\n" -">>> phase(-1-0j)\n" -"-3.141592653589793" - -#: ../../library/cmath.rst:125 -msgid "" -"The modulus (absolute value) of a complex number *z* can be computed using " -"the built-in :func:`abs` function. There is no separate :mod:`cmath` module " -"function for this operation." -msgstr "" -"複數 *z* 的絕對值可以使用內建的 :func:`abs` 函式計算。沒有單獨的 :mod:" -"`cmath` 模組函式適用於此操作。" - -#: ../../library/cmath.rst:132 -msgid "" -"Return the representation of *z* in polar coordinates. Returns a pair ``(r, " -"phi)`` where *r* is the modulus of *z* and *phi* is the phase of *z*. " -"``polar(z)`` is equivalent to ``(abs(z), phase(z))``." -msgstr "" -"回傳 *z* 在極座標中的表達方式。回傳一組數對 ``(r, phi)``， *r* 是 *z* 的絕對" -"值， *phi* 是 *z* 的相位角。 ``polar(z)`` 相當於 ``(abs(z), phase(z))``。" - -#: ../../library/cmath.rst:140 -msgid "" -"Return the complex number *z* with polar coordinates *r* and *phi*. " -"Equivalent to ``complex(r * math.cos(phi), r * math.sin(phi))``." -msgstr "" -"透過極座標 *r* 和 *phi* 回傳複數 *z*。相當於 ``complex(r * math.cos(phi), r " -"* math.sin(phi))``。" - -#: ../../library/cmath.rst:145 -msgid "Power and logarithmic functions" -msgstr "冪函數和對數函數" - -#: ../../library/cmath.rst:149 -msgid "" -"Return *e* raised to the power *z*, where *e* is the base of natural " -"logarithms." -msgstr "回傳 *e* 的 *z* 次方，其中 *e* 是自然對數的底數。" - -#: ../../library/cmath.rst:155 -msgid "" -"Return the logarithm of *z* to the given *base*. If the *base* is not " -"specified, returns the natural logarithm of *z*. There is one branch cut, " -"from 0 along the negative real axis to -∞." -msgstr "" -"回傳 *z* 給定 *base* 的對數。如果未指定 *base*，則傳回 *z* 的自然對數。存在一" -"條分枝切割，從 0 沿負實數軸到 -∞。" - -#: ../../library/cmath.rst:162 -msgid "" -"Return the base-10 logarithm of *z*. This has the same branch cut as :func:" -"`log`." -msgstr "回傳 *z* 以 10 為底的對數。它與 :func:`log` 具有相同的分枝切割。" - -#: ../../library/cmath.rst:168 -msgid "" -"Return the square root of *z*. This has the same branch cut as :func:`log`." -msgstr "回傳 *z* 的平方根。它與 :func:`log` 具有相同的分枝切割。" - -#: ../../library/cmath.rst:172 -msgid "Trigonometric functions" -msgstr "三角函數" - -#: ../../library/cmath.rst:176 -msgid "" -"Return the arc cosine of *z*. There are two branch cuts: One extends right " -"from 1 along the real axis to ∞. The other extends left from -1 along the " -"real axis to -∞." -msgstr "" -"回傳 *z* 的反餘弦值。存在兩條分枝切割：一條是從 1 沿著實數軸向右延伸到 ∞。另" -"一條從 -1 沿實數軸向左延伸到 -∞。" - -#: ../../library/cmath.rst:183 -msgid "" -"Return the arc sine of *z*. This has the same branch cuts as :func:`acos`." -msgstr "回傳 *z* 的反正弦值。它與 :func:`acos` 具有相同的分枝切割。" - -#: ../../library/cmath.rst:188 -msgid "" -"Return the arc tangent of *z*. There are two branch cuts: One extends from " -"``1j`` along the imaginary axis to ``∞j``. The other extends from ``-1j`` " -"along the imaginary axis to ``-∞j``." -msgstr "" -"回傳 *z* 的反正切值。有兩條分枝切割：一條是從 ``1j`` 沿著虛軸延伸到 ``∞j``。" -"另一條從 ``-1j`` 沿著虛軸延伸到 ``-∞j``。" - -#: ../../library/cmath.rst:195 -msgid "Return the cosine of *z*." -msgstr "回傳 *z* 的餘弦值。" - -#: ../../library/cmath.rst:200 -msgid "Return the sine of *z*." -msgstr "回傳 *z* 的正弦值。" - -#: ../../library/cmath.rst:205 -msgid "Return the tangent of *z*." -msgstr "回傳 *z* 的正切值。" - -#: ../../library/cmath.rst:209 -msgid "Hyperbolic functions" -msgstr "雙曲函數" - -#: ../../library/cmath.rst:213 -msgid "" -"Return the inverse hyperbolic cosine of *z*. There is one branch cut, " -"extending left from 1 along the real axis to -∞." -msgstr "" -"回傳 *z* 的反雙曲餘弦值。存在一條分枝切割，從 1 沿實數軸向左延伸到 -∞。" - -#: ../../library/cmath.rst:219 -msgid "" -"Return the inverse hyperbolic sine of *z*. There are two branch cuts: One " -"extends from ``1j`` along the imaginary axis to ``∞j``. The other extends " -"from ``-1j`` along the imaginary axis to ``-∞j``." -msgstr "" -"回傳 *z* 的反雙曲正弦值。存在兩條分枝切割：一條是從 ``1j`` 沿著虛軸延伸到 " -"``∞j``。另一條從 ``-1j`` 沿著虛軸延伸到 ``-∞j``。" - -#: ../../library/cmath.rst:226 -msgid "" -"Return the inverse hyperbolic tangent of *z*. There are two branch cuts: One " -"extends from ``1`` along the real axis to ``∞``. The other extends from " -"``-1`` along the real axis to ``-∞``." -msgstr "" -"回傳 *z* 的反雙曲正切值。存在兩條分枝切割：一條是從 ``1`` 沿著實數軸延伸到 " -"``∞``。另一條從 ``-1`` 沿著實數軸延伸到 ``-∞``。" - -#: ../../library/cmath.rst:233 -msgid "Return the hyperbolic cosine of *z*." -msgstr "回傳 *z* 的反雙曲餘弦值。" - -#: ../../library/cmath.rst:238 -msgid "Return the hyperbolic sine of *z*." -msgstr "回傳 *z* 的反雙曲正弦值。" - -#: ../../library/cmath.rst:243 -msgid "Return the hyperbolic tangent of *z*." -msgstr "回傳 *z* 的反雙曲正切值。" - -#: ../../library/cmath.rst:247 -msgid "Classification functions" -msgstr "分類函式" - -#: ../../library/cmath.rst:251 -msgid "" -"Return ``True`` if both the real and imaginary parts of *z* are finite, and " -"``False`` otherwise." -msgstr "如果 *z* 的實部和虛部都是有限的，則回傳 ``True``，否則回傳 ``False``。" - -#: ../../library/cmath.rst:259 -msgid "" -"Return ``True`` if either the real or the imaginary part of *z* is an " -"infinity, and ``False`` otherwise." -msgstr "如果 *z* 的實部或虛部是無窮大，則回傳 ``True``，否則回傳 ``False``。" - -#: ../../library/cmath.rst:265 -msgid "" -"Return ``True`` if either the real or the imaginary part of *z* is a NaN, " -"and ``False`` otherwise." -msgstr "如果 *z* 的實部或虛部為 NaN，則回傳 ``True``，否則回傳 ``False``。" - -#: ../../library/cmath.rst:271 -msgid "" -"Return ``True`` if the values *a* and *b* are close to each other and " -"``False`` otherwise." -msgstr "如果 *a* 和 *b* 的值相互接近，則回傳 ``True``，否則回傳 ``False``。" - -#: ../../library/cmath.rst:274 -msgid "" -"Whether or not two values are considered close is determined according to " -"given absolute and relative tolerances. If no errors occur, the result will " -"be: ``abs(a-b) <= max(rel_tol * max(abs(a), abs(b)), abs_tol)``." -msgstr "" -"兩數是否足夠接近取決於給定的絕對及相對容許偏差 (tolerance)。如果沒有錯誤發" -"生，結果將為：``abs(a-b) <= max(rel_tol * max(abs(a), abs(b)), abs_tol)``。" - -#: ../../library/cmath.rst:278 -msgid "" -"*rel_tol* is the relative tolerance -- it is the maximum allowed difference " -"between *a* and *b*, relative to the larger absolute value of *a* or *b*. " -"For example, to set a tolerance of 5%, pass ``rel_tol=0.05``. The default " -"tolerance is ``1e-09``, which assures that the two values are the same " -"within about 9 decimal digits. *rel_tol* must be nonnegative and less than " -"``1.0``." -msgstr "" -"*rel_tol* 為相對容許偏差 ── *a* 與 *b* 兩數差的最大容許值，與 *a* 及 *b* 兩數" -"的絕對值中較大者相關。例如欲設置 5% 的容許偏差，則傳入 ``rel_tol=0.05``。其預" -"設值為 ``1e-09``，該值可確保兩數於大約 9 個十進數位內相同。*rel_tol* 須不為負" -"且小於 ``1.0``。" - -#: ../../library/cmath.rst:285 -msgid "" -"*abs_tol* is the absolute tolerance; it defaults to ``0.0`` and it must be " -"nonnegative. When comparing ``x`` to ``0.0``, ``isclose(x, 0)`` is computed " -"as ``abs(x) <= rel_tol * abs(x)``, which is ``False`` for any ``x`` and " -"rel_tol less than ``1.0``. So add an appropriate positive abs_tol argument " -"to the call." -msgstr "" - -#: ../../library/cmath.rst:291 -msgid "" -"The IEEE 754 special values of ``NaN``, ``inf``, and ``-inf`` will be " -"handled according to IEEE rules. Specifically, ``NaN`` is not considered " -"close to any other value, including ``NaN``. ``inf`` and ``-inf`` are only " -"considered close to themselves." -msgstr "" -"定義於 IEEE 754 浮點標準中的特殊值 ``NaN``、``inf`` 和 ``-inf`` 會根據該標準" -"處理。更明確地說，``NaN`` 不會與包含自身在內的任何數字足夠接近，而 ``inf`` " -"及 ``-inf`` 皆只與自身接近。" - -#: ../../library/cmath.rst:300 -msgid ":pep:`485` -- A function for testing approximate equality" -msgstr ":pep:`485` ── 用於測試近似相等的函式" - -#: ../../library/cmath.rst:304 -msgid "Constants" -msgstr "常數" - -#: ../../library/cmath.rst:308 -msgid "The mathematical constant *π*, as a float." -msgstr "數學常數 *π*，作為一個浮點數。" - -#: ../../library/cmath.rst:313 -msgid "The mathematical constant *e*, as a float." -msgstr "數學常數 *e*，作為一個浮點數。" - -#: ../../library/cmath.rst:318 -msgid "The mathematical constant *τ*, as a float." -msgstr "數學常數 *τ*，作為一個浮點數。" - -#: ../../library/cmath.rst:325 -msgid "Floating-point positive infinity. Equivalent to ``float('inf')``." -msgstr "正無窮大的浮點數。相當於 ``float('inf')``。" - -#: ../../library/cmath.rst:332 -msgid "" -"Complex number with zero real part and positive infinity imaginary part. " -"Equivalent to ``complex(0.0, float('inf'))``." -msgstr "實部為零和虛部為正無窮的複數。相當於 ``complex(0.0, float('inf'))``。" - -#: ../../library/cmath.rst:340 -msgid "" -"A floating-point \"not a number\" (NaN) value. Equivalent to " -"``float('nan')``. See also :data:`math.nan`." -msgstr "浮點「非數字」 (NaN) 值。相當於 ``float('nan')``。另請參閱 :data:`math.nan`。" - -#: ../../library/cmath.rst:348 -msgid "" -"Complex number with zero real part and NaN imaginary part. Equivalent to " -"``complex(0.0, float('nan'))``." -msgstr "實部為零和虛部為 NaN 的複數。相當於 ``complex(0.0, float('nan'))``。" - -#: ../../library/cmath.rst:356 -msgid "" -"Note that the selection of functions is similar, but not identical, to that " -"in module :mod:`math`. The reason for having two modules is that some users " -"aren't interested in complex numbers, and perhaps don't even know what they " -"are. They would rather have ``math.sqrt(-1)`` raise an exception than " -"return a complex number. Also note that the functions defined in :mod:" -"`cmath` always return a complex number, even if the answer can be expressed " -"as a real number (in which case the complex number has an imaginary part of " -"zero)." -msgstr "" -"請注意，函式的選擇與模組 :mod:`math` 的類似，但並不完全相同。擁有兩個模組的原" -"因是有些用戶對複數不感興趣，甚至根本就不知道它們是什麼。他們寧願讓 ``math." -"sqrt(-1)`` 引發異常，也不願它回傳複數。另請注意， :mod:`cmath` 中所定義的函式" -"始終都會回傳複數，即使答案可以表示為實數（在這種情況下，複數的虛部為零）。" - -#: ../../library/cmath.rst:364 -msgid "" -"A note on branch cuts: They are curves along which the given function fails " -"to be continuous. They are a necessary feature of many complex functions. " -"It is assumed that if you need to compute with complex functions, you will " -"understand about branch cuts. Consult almost any (not too elementary) book " -"on complex variables for enlightenment. For information of the proper " -"choice of branch cuts for numerical purposes, a good reference should be the " -"following:" -msgstr "" -"關於分枝切割的註釋：它們是沿著給定的不連續函式的曲線。它們是許多複變函數的必" -"要特徵。假設你需要使用複變函數進行計算，你將會了解分枝切割的概念。請參閱幾乎" -"所有關於複變函數的（不是太初級的）書籍以獲得啟發。對於如何正確地基於數值目的" -"選擇分枝切割的相關訊息，以下內容應該是一個很好的參考：" - -#: ../../library/cmath.rst:374 -msgid "" -"Kahan, W: Branch cuts for complex elementary functions; or, Much ado about " -"nothing's sign bit. In Iserles, A., and Powell, M. (eds.), The state of the " -"art in numerical analysis. Clarendon Press (1987) pp165--211." -msgstr "" - -#: ../../library/cmath.rst:354 -msgid "module" -msgstr "module（模組）" - -#: ../../library/cmath.rst:354 -msgid "math" -msgstr "math（數學）" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-10-15 00:16+0000\n" +"PO-Revision-Date: 2024-03-14 09:26+0800\n" +"Last-Translator: Enkai Huang \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" +"X-Generator: Poedit 3.4.2\n" + +#: ../../library/cmath.rst:2 +msgid ":mod:`!cmath` --- Mathematical functions for complex numbers" +msgstr ":mod:`!cmath` --- 複數的數學函式" + +#: ../../library/cmath.rst:9 +msgid "" +"This module provides access to mathematical functions for complex numbers. " +"The functions in this module accept integers, floating-point numbers or " +"complex numbers as arguments. They will also accept any Python object that " +"has either a :meth:`~object.__complex__` or a :meth:`~object.__float__` " +"method: these methods are used to convert the object to a complex or " +"floating-point number, respectively, and the function is then applied to the " +"result of the conversion." +msgstr "" +"本模組提供一些適用於複數的數學函式。本模組中的函式接受整數、浮點數或複數作為" +"引數。它們也接受任何具有 :meth:`~object.__complex__` 或 :meth:`~object." +"__float__` 方法的 Python 物件：這些方法分別用於將物件轉換為複數或浮點數，然後" +"再將函式應用於轉換後的結果。" + +#: ../../library/cmath.rst:18 +msgid "" +"For functions involving branch cuts, we have the problem of deciding how to " +"define those functions on the cut itself. Following Kahan's \"Branch cuts " +"for complex elementary functions\" paper, as well as Annex G of C99 and " +"later C standards, we use the sign of zero to distinguish one side of the " +"branch cut from the other: for a branch cut along (a portion of) the real " +"axis we look at the sign of the imaginary part, while for a branch cut along " +"the imaginary axis we look at the sign of the real part." +msgstr "" +"對於涉及分枝切割 (branch cut) 的函式，我們面臨的問題是決定如何定義在切割本身" +"上的這些函式。遵循 Kahan 的論文 \"Branch cuts for complex elementary " +"functions\"，以及 C99 的附錄 G 和後來的 C 標準，我們使用零符號來區分分枝切割" +"的兩側：對於沿著（一部分）實數軸的分枝切割，我們查看虛部的符號，而對於沿虛軸" +"的分枝切割，我們則查看實部的符號。" + +#: ../../library/cmath.rst:26 +msgid "" +"For example, the :func:`cmath.sqrt` function has a branch cut along the " +"negative real axis. An argument of ``-2-0j`` is treated as though it lies " +"*below* the branch cut, and so gives a result on the negative imaginary " +"axis::" +msgstr "" +"例如 :func:`cmath.sqrt` 函式具有一條沿負實軸的分枝切割。 引數 ``-2-0j`` 被視" +"為位於分枝切割 *下方* 處理，因此給出的結果在負虛軸上： ::" + +#: ../../library/cmath.rst:31 +msgid "" +">>> cmath.sqrt(-2-0j)\n" +"-1.4142135623730951j" +msgstr "" +">>> cmath.sqrt(-2-0j)\n" +"-1.4142135623730951j" + +#: ../../library/cmath.rst:34 +msgid "" +"But an argument of ``-2+0j`` is treated as though it lies above the branch " +"cut::" +msgstr "但是引數 ``-2+0j`` 會被當成位於分枝切割上方處理： ::" + +#: ../../library/cmath.rst:37 +msgid "" +">>> cmath.sqrt(-2+0j)\n" +"1.4142135623730951j" +msgstr "" +">>> cmath.sqrt(-2+0j)\n" +"1.4142135623730951j" + +#: ../../library/cmath.rst:42 +msgid "**Conversions to and from polar coordinates**" +msgstr "**轉換到極座標和從極座標做轉換**" + +#: ../../library/cmath.rst:44 +msgid ":func:`phase(z) `" +msgstr ":func:`phase(z) `" + +#: ../../library/cmath.rst:44 +msgid "Return the phase of *z*" +msgstr "回傳 *z* 的相位角。" + +#: ../../library/cmath.rst:45 +msgid ":func:`polar(z) `" +msgstr ":func:`polar(z) `" + +#: ../../library/cmath.rst:45 +msgid "Return the representation of *z* in polar coordinates" +msgstr "回傳 *z* 在極座標中的表達方式。" + +#: ../../library/cmath.rst:46 +msgid ":func:`rect(r, phi) `" +msgstr ":func:`rect(r, phi) `" + +#: ../../library/cmath.rst:46 +msgid "Return the complex number *z* with polar coordinates *r* and *phi*" +msgstr "透過極座標 *r* 和 *phi* 回傳複數 *z*。" + +#: ../../library/cmath.rst:48 +msgid "**Power and logarithmic functions**" +msgstr "**冪函數和對數函數**" + +#: ../../library/cmath.rst:50 +msgid ":func:`exp(z) `" +msgstr ":func:`exp(z) `" + +#: ../../library/cmath.rst:50 +msgid "Return *e* raised to the power *z*" +msgstr "回傳 *e* 的 *z* 次方。" + +#: ../../library/cmath.rst:51 +msgid ":func:`log(z[, base]) `" +msgstr ":func:`log(z[, base]) `" + +#: ../../library/cmath.rst:51 +msgid "Return the logarithm of *z* to the given *base* (*e* by default)" +msgstr "回傳 *z* 以給定 *base* 為底（預設為 *e*）的對數。" + +#: ../../library/cmath.rst:52 +msgid ":func:`log10(z) `" +msgstr ":func:`log10(z) `" + +#: ../../library/cmath.rst:52 +msgid "Return the base-10 logarithm of *z*" +msgstr "回傳 *z* 以 10 為底的對數。" + +#: ../../library/cmath.rst:53 +msgid ":func:`sqrt(z) `" +msgstr ":func:`sqrt(z) `" + +#: ../../library/cmath.rst:53 +msgid "Return the square root of *z*" +msgstr "回傳 *z* 的平方根。" + +#: ../../library/cmath.rst:55 +msgid "**Trigonometric functions**" +msgstr "**三角函數**" + +#: ../../library/cmath.rst:57 +msgid ":func:`acos(z) `" +msgstr ":func:`acos(z) `" + +#: ../../library/cmath.rst:57 +msgid "Return the arc cosine of *z*" +msgstr "回傳 *z* 的反餘弦值。" + +#: ../../library/cmath.rst:58 +msgid ":func:`asin(z) `" +msgstr ":func:`asin(z) `" + +#: ../../library/cmath.rst:58 +msgid "Return the arc sine of *z*" +msgstr "回傳 *z* 的反正弦值。" + +#: ../../library/cmath.rst:59 +msgid ":func:`atan(z) `" +msgstr ":func:`atan(z) `" + +#: ../../library/cmath.rst:59 +msgid "Return the arc tangent of *z*" +msgstr "回傳 *z* 的反正切值。" + +#: ../../library/cmath.rst:60 +msgid ":func:`cos(z) `" +msgstr ":func:`cos(z) `" + +#: ../../library/cmath.rst:60 +msgid "Return the cosine of *z*" +msgstr "回傳 *z* 的餘弦值。" + +#: ../../library/cmath.rst:61 +msgid ":func:`sin(z) `" +msgstr ":func:`sin(z) `" + +#: ../../library/cmath.rst:61 +msgid "Return the sine of *z*" +msgstr "回傳 *z* 的正弦值。" + +#: ../../library/cmath.rst:62 +msgid ":func:`tan(z) `" +msgstr ":func:`tan(z) `" + +#: ../../library/cmath.rst:62 +msgid "Return the tangent of *z*" +msgstr "回傳 *z* 的正切值。" + +#: ../../library/cmath.rst:64 +msgid "**Hyperbolic functions**" +msgstr "**雙曲函數**" + +#: ../../library/cmath.rst:66 +msgid ":func:`acosh(z) `" +msgstr ":func:`acosh(z) `" + +#: ../../library/cmath.rst:66 +msgid "Return the inverse hyperbolic cosine of *z*" +msgstr "回傳 *z* 的反雙曲餘弦值。" + +#: ../../library/cmath.rst:67 +msgid ":func:`asinh(z) `" +msgstr ":func:`asinh(z) `" + +#: ../../library/cmath.rst:67 +msgid "Return the inverse hyperbolic sine of *z*" +msgstr "回傳 *z* 的反雙曲正弦值。" + +#: ../../library/cmath.rst:68 +msgid ":func:`atanh(z) `" +msgstr ":func:`atanh(z) `" + +#: ../../library/cmath.rst:68 +msgid "Return the inverse hyperbolic tangent of *z*" +msgstr "回傳 *z* 的反雙曲正切值。" + +#: ../../library/cmath.rst:69 +msgid ":func:`cosh(z) `" +msgstr ":func:`cosh(z) `" + +#: ../../library/cmath.rst:69 +msgid "Return the hyperbolic cosine of *z*" +msgstr "回傳 *z* 的雙曲餘弦值。" + +#: ../../library/cmath.rst:70 +msgid ":func:`sinh(z) `" +msgstr ":func:`sinh(z) `" + +#: ../../library/cmath.rst:70 +msgid "Return the hyperbolic sine of *z*" +msgstr "回傳 *z* 的雙曲正弦值。" + +#: ../../library/cmath.rst:71 +msgid ":func:`tanh(z) `" +msgstr ":func:`tanh(z) `" + +#: ../../library/cmath.rst:71 +msgid "Return the hyperbolic tangent of *z*" +msgstr "回傳 *z* 的雙曲正切值。" + +#: ../../library/cmath.rst:73 +msgid "**Classification functions**" +msgstr "**分類函數**" + +#: ../../library/cmath.rst:75 +msgid ":func:`isfinite(z) `" +msgstr ":func:`isfinite(z) `" + +#: ../../library/cmath.rst:75 +msgid "Check if all components of *z* are finite" +msgstr "" + +#: ../../library/cmath.rst:76 +msgid ":func:`isinf(z) `" +msgstr ":func:`isinf(z) `" + +#: ../../library/cmath.rst:76 +msgid "Check if any component of *z* is infinite" +msgstr "" + +#: ../../library/cmath.rst:77 +msgid ":func:`isnan(z) `" +msgstr ":func:`isnan(z) `" + +#: ../../library/cmath.rst:77 +msgid "Check if any component of *z* is a NaN" +msgstr "" + +#: ../../library/cmath.rst:78 +msgid ":func:`isclose(a, b, *, rel_tol, abs_tol) `" +msgstr ":func:`isclose(a, b, *, rel_tol, abs_tol) `" + +#: ../../library/cmath.rst:78 +msgid "Check if the values *a* and *b* are close to each other" +msgstr "檢查 *a* 和 *b* 的值是否接近" + +#: ../../library/cmath.rst:80 +msgid "**Constants**" +msgstr "**常數**" + +#: ../../library/cmath.rst:82 +msgid ":data:`pi`" +msgstr ":data:`pi`" + +#: ../../library/cmath.rst:82 +msgid "*π* = 3.141592..." +msgstr "*π* = 3.141592..." + +#: ../../library/cmath.rst:83 +msgid ":data:`e`" +msgstr ":data:`e`" + +#: ../../library/cmath.rst:83 +msgid "*e* = 2.718281..." +msgstr "*e* = 2.718281..." + +#: ../../library/cmath.rst:84 +msgid ":data:`tau`" +msgstr ":data:`tau`" + +#: ../../library/cmath.rst:84 +msgid "*τ* = 2\\ *π* = 6.283185..." +msgstr "*τ* = 2\\ *π* = 6.283185..." + +#: ../../library/cmath.rst:85 +msgid ":data:`inf`" +msgstr ":data:`inf`" + +#: ../../library/cmath.rst:85 +msgid "Positive infinity" +msgstr "" + +#: ../../library/cmath.rst:86 +msgid ":data:`infj`" +msgstr ":data:`infj`" + +#: ../../library/cmath.rst:86 +msgid "Pure imaginary infinity" +msgstr "" + +#: ../../library/cmath.rst:87 +msgid ":data:`nan`" +msgstr ":data:`nan`" + +#: ../../library/cmath.rst:87 +msgid "\"Not a number\" (NaN)" +msgstr "" + +#: ../../library/cmath.rst:88 +msgid ":data:`nanj`" +msgstr ":data:`nanj`" + +#: ../../library/cmath.rst:88 +msgid "Pure imaginary NaN" +msgstr "" + +#: ../../library/cmath.rst:93 +msgid "Conversions to and from polar coordinates" +msgstr "轉換到極座標和從極座標做轉換" + +#: ../../library/cmath.rst:95 +msgid "" +"A Python complex number ``z`` is stored internally using *rectangular* or " +"*Cartesian* coordinates. It is completely determined by its *real part* ``z." +"real`` and its *imaginary part* ``z.imag``." +msgstr "" +"Python 複數 ``z`` 是用 *直角坐標* 或 *笛卡爾坐標* 儲存在內部的。它完全是由其 " +"*實部* ``z.real`` 和 *虛部* ``z.imag`` 所決定。" + +#: ../../library/cmath.rst:99 +msgid "" +"*Polar coordinates* give an alternative way to represent a complex number. " +"In polar coordinates, a complex number *z* is defined by the modulus *r* and " +"the phase angle *phi*. The modulus *r* is the distance from *z* to the " +"origin, while the phase *phi* is the counterclockwise angle, measured in " +"radians, from the positive x-axis to the line segment that joins the origin " +"to *z*." +msgstr "" +"*極座標* 提供了另一種表示複數的方法。在極座標中，複數 *z* 由絕對值 (modulus) " +"*r* 和相位角 (phase) *phi* 定義。絕對值 *r* 是從 *z* 到原點的距離，而相位角 " +"*phi* 是從正 x 軸到連接原點到 *z* 的線段的逆時針角度（以弧度為單位）。" + +#: ../../library/cmath.rst:106 +msgid "" +"The following functions can be used to convert from the native rectangular " +"coordinates to polar coordinates and back." +msgstr "以下的函式可用於原始直角座標與極座標之間的相互轉換。" + +#: ../../library/cmath.rst:111 +msgid "" +"Return the phase of *z* (also known as the *argument* of *z*), as a float. " +"``phase(z)`` is equivalent to ``math.atan2(z.imag, z.real)``. The result " +"lies in the range [-\\ *π*, *π*], and the branch cut for this operation lies " +"along the negative real axis. The sign of the result is the same as the " +"sign of ``z.imag``, even when ``z.imag`` is zero::" +msgstr "" +"以浮點數的形式回傳 *z* 的相位角（也稱為 *z* 的 *引數* ）。``phase(z)`` 等價" +"於 ``math.atan2(z.imag, z.real)``。結果將位於 [-\\ *π*, *π*] 的範圍內，且此操" +"作的分枝切割將位於負實軸上。結果的符號會與 ``z.imag`` 的符號相同，即使 ``z." +"imag`` 為零： ::" + +#: ../../library/cmath.rst:117 +msgid "" +">>> phase(-1+0j)\n" +"3.141592653589793\n" +">>> phase(-1-0j)\n" +"-3.141592653589793" +msgstr "" +">>> phase(-1+0j)\n" +"3.141592653589793\n" +">>> phase(-1-0j)\n" +"-3.141592653589793" + +#: ../../library/cmath.rst:125 +msgid "" +"The modulus (absolute value) of a complex number *z* can be computed using " +"the built-in :func:`abs` function. There is no separate :mod:`cmath` module " +"function for this operation." +msgstr "" +"複數 *z* 的絕對值可以使用內建的 :func:`abs` 函式計算。沒有單獨的 :mod:" +"`cmath` 模組函式適用於此操作。" + +#: ../../library/cmath.rst:132 +msgid "" +"Return the representation of *z* in polar coordinates. Returns a pair ``(r, " +"phi)`` where *r* is the modulus of *z* and *phi* is the phase of *z*. " +"``polar(z)`` is equivalent to ``(abs(z), phase(z))``." +msgstr "" +"回傳 *z* 在極座標中的表達方式。回傳一組數對 ``(r, phi)``， *r* 是 *z* 的絕對" +"值， *phi* 是 *z* 的相位角。 ``polar(z)`` 相當於 ``(abs(z), phase(z))``。" + +#: ../../library/cmath.rst:140 +msgid "" +"Return the complex number *z* with polar coordinates *r* and *phi*. " +"Equivalent to ``complex(r * math.cos(phi), r * math.sin(phi))``." +msgstr "" +"透過極座標 *r* 和 *phi* 回傳複數 *z*。相當於 ``complex(r * math.cos(phi), r " +"* math.sin(phi))``。" + +#: ../../library/cmath.rst:145 +msgid "Power and logarithmic functions" +msgstr "冪函數和對數函數" + +#: ../../library/cmath.rst:149 +msgid "" +"Return *e* raised to the power *z*, where *e* is the base of natural " +"logarithms." +msgstr "回傳 *e* 的 *z* 次方，其中 *e* 是自然對數的底數。" + +#: ../../library/cmath.rst:155 +msgid "" +"Return the logarithm of *z* to the given *base*. If the *base* is not " +"specified, returns the natural logarithm of *z*. There is one branch cut, " +"from 0 along the negative real axis to -∞." +msgstr "" +"回傳 *z* 給定 *base* 的對數。如果未指定 *base*，則傳回 *z* 的自然對數。存在一" +"條分枝切割，從 0 沿負實數軸到 -∞。" + +#: ../../library/cmath.rst:162 +msgid "" +"Return the base-10 logarithm of *z*. This has the same branch cut as :func:" +"`log`." +msgstr "回傳 *z* 以 10 為底的對數。它與 :func:`log` 具有相同的分枝切割。" + +#: ../../library/cmath.rst:168 +msgid "" +"Return the square root of *z*. This has the same branch cut as :func:`log`." +msgstr "回傳 *z* 的平方根。它與 :func:`log` 具有相同的分枝切割。" + +#: ../../library/cmath.rst:172 +msgid "Trigonometric functions" +msgstr "三角函數" + +#: ../../library/cmath.rst:176 +msgid "" +"Return the arc cosine of *z*. There are two branch cuts: One extends right " +"from 1 along the real axis to ∞. The other extends left from -1 along the " +"real axis to -∞." +msgstr "" +"回傳 *z* 的反餘弦值。存在兩條分枝切割：一條是從 1 沿著實數軸向右延伸到 ∞。另" +"一條從 -1 沿實數軸向左延伸到 -∞。" + +#: ../../library/cmath.rst:183 +msgid "" +"Return the arc sine of *z*. This has the same branch cuts as :func:`acos`." +msgstr "回傳 *z* 的反正弦值。它與 :func:`acos` 具有相同的分枝切割。" + +#: ../../library/cmath.rst:188 +msgid "" +"Return the arc tangent of *z*. There are two branch cuts: One extends from " +"``1j`` along the imaginary axis to ``∞j``. The other extends from ``-1j`` " +"along the imaginary axis to ``-∞j``." +msgstr "" +"回傳 *z* 的反正切值。有兩條分枝切割：一條是從 ``1j`` 沿著虛軸延伸到 ``∞j``。" +"另一條從 ``-1j`` 沿著虛軸延伸到 ``-∞j``。" + +#: ../../library/cmath.rst:195 +msgid "Return the cosine of *z*." +msgstr "回傳 *z* 的餘弦值。" + +#: ../../library/cmath.rst:200 +msgid "Return the sine of *z*." +msgstr "回傳 *z* 的正弦值。" + +#: ../../library/cmath.rst:205 +msgid "Return the tangent of *z*." +msgstr "回傳 *z* 的正切值。" + +#: ../../library/cmath.rst:209 +msgid "Hyperbolic functions" +msgstr "雙曲函數" + +#: ../../library/cmath.rst:213 +msgid "" +"Return the inverse hyperbolic cosine of *z*. There is one branch cut, " +"extending left from 1 along the real axis to -∞." +msgstr "" +"回傳 *z* 的反雙曲餘弦值。存在一條分枝切割，從 1 沿實數軸向左延伸到 -∞。" + +#: ../../library/cmath.rst:219 +msgid "" +"Return the inverse hyperbolic sine of *z*. There are two branch cuts: One " +"extends from ``1j`` along the imaginary axis to ``∞j``. The other extends " +"from ``-1j`` along the imaginary axis to ``-∞j``." +msgstr "" +"回傳 *z* 的反雙曲正弦值。存在兩條分枝切割：一條是從 ``1j`` 沿著虛軸延伸到 " +"``∞j``。另一條從 ``-1j`` 沿著虛軸延伸到 ``-∞j``。" + +#: ../../library/cmath.rst:226 +msgid "" +"Return the inverse hyperbolic tangent of *z*. There are two branch cuts: One " +"extends from ``1`` along the real axis to ``∞``. The other extends from " +"``-1`` along the real axis to ``-∞``." +msgstr "" +"回傳 *z* 的反雙曲正切值。存在兩條分枝切割：一條是從 ``1`` 沿著實數軸延伸到 " +"``∞``。另一條從 ``-1`` 沿著實數軸延伸到 ``-∞``。" + +#: ../../library/cmath.rst:233 +msgid "Return the hyperbolic cosine of *z*." +msgstr "回傳 *z* 的反雙曲餘弦值。" + +#: ../../library/cmath.rst:238 +msgid "Return the hyperbolic sine of *z*." +msgstr "回傳 *z* 的反雙曲正弦值。" + +#: ../../library/cmath.rst:243 +msgid "Return the hyperbolic tangent of *z*." +msgstr "回傳 *z* 的反雙曲正切值。" + +#: ../../library/cmath.rst:247 +msgid "Classification functions" +msgstr "分類函式" + +#: ../../library/cmath.rst:251 +msgid "" +"Return ``True`` if both the real and imaginary parts of *z* are finite, and " +"``False`` otherwise." +msgstr "如果 *z* 的實部和虛部都是有限的，則回傳 ``True``，否則回傳 ``False``。" + +#: ../../library/cmath.rst:259 +msgid "" +"Return ``True`` if either the real or the imaginary part of *z* is an " +"infinity, and ``False`` otherwise." +msgstr "如果 *z* 的實部或虛部是無窮大，則回傳 ``True``，否則回傳 ``False``。" + +#: ../../library/cmath.rst:265 +msgid "" +"Return ``True`` if either the real or the imaginary part of *z* is a NaN, " +"and ``False`` otherwise." +msgstr "如果 *z* 的實部或虛部為 NaN，則回傳 ``True``，否則回傳 ``False``。" + +#: ../../library/cmath.rst:271 +msgid "" +"Return ``True`` if the values *a* and *b* are close to each other and " +"``False`` otherwise." +msgstr "如果 *a* 和 *b* 的值相互接近，則回傳 ``True``，否則回傳 ``False``。" + +#: ../../library/cmath.rst:274 +msgid "" +"Whether or not two values are considered close is determined according to " +"given absolute and relative tolerances. If no errors occur, the result will " +"be: ``abs(a-b) <= max(rel_tol * max(abs(a), abs(b)), abs_tol)``." +msgstr "" +"兩數是否足夠接近取決於給定的絕對及相對容許偏差 (tolerance)。如果沒有錯誤發" +"生，結果將為：``abs(a-b) <= max(rel_tol * max(abs(a), abs(b)), abs_tol)``。" + +#: ../../library/cmath.rst:278 +msgid "" +"*rel_tol* is the relative tolerance -- it is the maximum allowed difference " +"between *a* and *b*, relative to the larger absolute value of *a* or *b*. " +"For example, to set a tolerance of 5%, pass ``rel_tol=0.05``. The default " +"tolerance is ``1e-09``, which assures that the two values are the same " +"within about 9 decimal digits. *rel_tol* must be nonnegative and less than " +"``1.0``." +msgstr "" +"*rel_tol* 為相對容許偏差 ── *a* 與 *b* 兩數差的最大容許值，與 *a* 及 *b* 兩數" +"的絕對值中較大者相關。例如欲設置 5% 的容許偏差，則傳入 ``rel_tol=0.05``。其預" +"設值為 ``1e-09``，該值可確保兩數於大約 9 個十進數位內相同。*rel_tol* 須不為負" +"且小於 ``1.0``。" + +#: ../../library/cmath.rst:285 +msgid "" +"*abs_tol* is the absolute tolerance; it defaults to ``0.0`` and it must be " +"nonnegative. When comparing ``x`` to ``0.0``, ``isclose(x, 0)`` is computed " +"as ``abs(x) <= rel_tol * abs(x)``, which is ``False`` for any ``x`` and " +"rel_tol less than ``1.0``. So add an appropriate positive abs_tol argument " +"to the call." +msgstr "" + +#: ../../library/cmath.rst:291 +msgid "" +"The IEEE 754 special values of ``NaN``, ``inf``, and ``-inf`` will be " +"handled according to IEEE rules. Specifically, ``NaN`` is not considered " +"close to any other value, including ``NaN``. ``inf`` and ``-inf`` are only " +"considered close to themselves." +msgstr "" +"定義於 IEEE 754 浮點標準中的特殊值 ``NaN``、``inf`` 和 ``-inf`` 會根據該標準" +"處理。更明確地說，``NaN`` 不會與包含自身在內的任何數字足夠接近，而 ``inf`` " +"及 ``-inf`` 皆只與自身接近。" + +#: ../../library/cmath.rst:300 +msgid ":pep:`485` -- A function for testing approximate equality" +msgstr ":pep:`485` ── 用於測試近似相等的函式" + +#: ../../library/cmath.rst:304 +msgid "Constants" +msgstr "常數" + +#: ../../library/cmath.rst:308 +msgid "The mathematical constant *π*, as a float." +msgstr "數學常數 *π*，作為一個浮點數。" + +#: ../../library/cmath.rst:313 +msgid "The mathematical constant *e*, as a float." +msgstr "數學常數 *e*，作為一個浮點數。" + +#: ../../library/cmath.rst:318 +msgid "The mathematical constant *τ*, as a float." +msgstr "數學常數 *τ*，作為一個浮點數。" + +#: ../../library/cmath.rst:325 +msgid "Floating-point positive infinity. Equivalent to ``float('inf')``." +msgstr "正無窮大的浮點數。相當於 ``float('inf')``。" + +#: ../../library/cmath.rst:332 +msgid "" +"Complex number with zero real part and positive infinity imaginary part. " +"Equivalent to ``complex(0.0, float('inf'))``." +msgstr "實部為零和虛部為正無窮的複數。相當於 ``complex(0.0, float('inf'))``。" + +#: ../../library/cmath.rst:340 +msgid "" +"A floating-point \"not a number\" (NaN) value. Equivalent to " +"``float('nan')``. See also :data:`math.nan`." +msgstr "浮點「非數字」 (NaN) 值。相當於 ``float('nan')``。另請參閱 :data:`math.nan`。" + +#: ../../library/cmath.rst:348 +msgid "" +"Complex number with zero real part and NaN imaginary part. Equivalent to " +"``complex(0.0, float('nan'))``." +msgstr "實部為零和虛部為 NaN 的複數。相當於 ``complex(0.0, float('nan'))``。" + +#: ../../library/cmath.rst:356 +msgid "" +"Note that the selection of functions is similar, but not identical, to that " +"in module :mod:`math`. The reason for having two modules is that some users " +"aren't interested in complex numbers, and perhaps don't even know what they " +"are. They would rather have ``math.sqrt(-1)`` raise an exception than " +"return a complex number. Also note that the functions defined in :mod:" +"`cmath` always return a complex number, even if the answer can be expressed " +"as a real number (in which case the complex number has an imaginary part of " +"zero)." +msgstr "" +"請注意，函式的選擇與模組 :mod:`math` 的類似，但並不完全相同。擁有兩個模組的原" +"因是有些用戶對複數不感興趣，甚至根本就不知道它們是什麼。他們寧願讓 ``math." +"sqrt(-1)`` 引發異常，也不願它回傳複數。另請注意， :mod:`cmath` 中所定義的函式" +"始終都會回傳複數，即使答案可以表示為實數（在這種情況下，複數的虛部為零）。" + +#: ../../library/cmath.rst:364 +msgid "" +"A note on branch cuts: They are curves along which the given function fails " +"to be continuous. They are a necessary feature of many complex functions. " +"It is assumed that if you need to compute with complex functions, you will " +"understand about branch cuts. Consult almost any (not too elementary) book " +"on complex variables for enlightenment. For information of the proper " +"choice of branch cuts for numerical purposes, a good reference should be the " +"following:" +msgstr "" +"關於分枝切割的註釋：它們是沿著給定的不連續函式的曲線。它們是許多複變函數的必" +"要特徵。假設你需要使用複變函數進行計算，你將會了解分枝切割的概念。請參閱幾乎" +"所有關於複變函數的（不是太初級的）書籍以獲得啟發。對於如何正確地基於數值目的" +"選擇分枝切割的相關訊息，以下內容應該是一個很好的參考：" + +#: ../../library/cmath.rst:374 +msgid "" +"Kahan, W: Branch cuts for complex elementary functions; or, Much ado about " +"nothing's sign bit. In Iserles, A., and Powell, M. (eds.), The state of the " +"art in numerical analysis. Clarendon Press (1987) pp165--211." +msgstr "" + +#: ../../library/cmath.rst:354 +msgid "module" +msgstr "module（模組）" + +#: ../../library/cmath.rst:354 +msgid "math" +msgstr "math（數學）" diff --git a/library/cmd.po b/library/cmd.po index 5dcd7a7a48..edc3bde59e 100644 --- a/library/cmd.po +++ b/library/cmd.po @@ -1,700 +1,700 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Dr-XYZ , 2025 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-09-23 07:52+0800\n" -"PO-Revision-Date: 2025-05-19 20:25+0800\n" -"Last-Translator: Dr-XYZ \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/cmd.rst:2 -msgid ":mod:`!cmd` --- Support for line-oriented command interpreters" -msgstr ":mod:`!cmd` --- 以列為導向的命令直譯器支援" - -#: ../../library/cmd.rst:9 -msgid "**Source code:** :source:`Lib/cmd.py`" -msgstr "**原始碼：**\\ :source:`Lib/cmd.py`" - -#: ../../library/cmd.rst:13 -msgid "" -"The :class:`Cmd` class provides a simple framework for writing line-oriented " -"command interpreters. These are often useful for test harnesses, " -"administrative tools, and prototypes that will later be wrapped in a more " -"sophisticated interface." -msgstr "" -":class:`Cmd` 類別提供了一個簡單的架構，用於撰寫列導向的命令直譯器。這類直譯器" -"常用於測試控制工具、管理工具以及日後將包裝於更高階介面的原型中。" - -#: ../../library/cmd.rst:20 -msgid "" -"A :class:`Cmd` instance or subclass instance is a line-oriented interpreter " -"framework. There is no good reason to instantiate :class:`Cmd` itself; " -"rather, it's useful as a superclass of an interpreter class you define " -"yourself in order to inherit :class:`Cmd`'s methods and encapsulate action " -"methods." -msgstr "" -":class:`Cmd` 實例或其子類別實例是一種列導向的直譯器架構。通常沒有必要直接實例" -"化 :class:`Cmd` 本身；它更適合作為你自己定義的直譯器類別的父類別，讓你能繼承 :" -"class:`Cmd` 的方法，並封裝動作方法。" - -#: ../../library/cmd.rst:25 -msgid "" -"The optional argument *completekey* is the :mod:`readline` name of a " -"completion key; it defaults to :kbd:`Tab`. If *completekey* is not :const:" -"`None` and :mod:`readline` is available, command completion is done " -"automatically." -msgstr "" -"可選引數 *completekey* 是 :mod:`readline` 模組中用於自動完成的按鍵名稱；預設" -"為 :kbd:`Tab`。若 *completekey* 不為 :const:`None` 且 :mod:`readline` 可用，" -"則會自動啟用命令自動完成功能。" - -#: ../../library/cmd.rst:29 -msgid "" -"The default, ``'tab'``, is treated specially, so that it refers to the :kbd:" -"`Tab` key on every :data:`readline.backend`. Specifically, if :data:" -"`readline.backend` is ``editline``, ``Cmd`` will use ``'^I'`` instead of " -"``'tab'``. Note that other values are not treated this way, and might only " -"work with a specific backend." -msgstr "" -"預設值 ``'tab'`` 會被特殊處理，使其在所有的 :data:`readline.backend` 中皆代" -"表 :kbd:`Tab` 鍵。具體來說，若 :data:`readline.backend` 為 ``editline``，則 " -"``Cmd`` 會改用 ``'^I'`` 取代 ``'tab'``。請注意，其他值不會有此處理方式，且可" -"能僅能在特定的後端中適用。" - -#: ../../library/cmd.rst:36 -msgid "" -"The optional arguments *stdin* and *stdout* specify the input and output " -"file objects that the Cmd instance or subclass instance will use for input " -"and output. If not specified, they will default to :data:`sys.stdin` and :" -"data:`sys.stdout`." -msgstr "" -"可選引數 *stdin* 與 *stdout* 用來指定 Cmd 實例或其子類別實例所使用的輸入與輸" -"出檔案物件。若未指定，預設為 :data:`sys.stdin` 與 :data:`sys.stdout`。" - -#: ../../library/cmd.rst:41 -msgid "" -"If you want a given *stdin* to be used, make sure to set the instance's :" -"attr:`use_rawinput` attribute to ``False``, otherwise *stdin* will be " -"ignored." -msgstr "" -"若你希望使用指定的 *stdin*，請務必將該實例的 :attr:`use_rawinput` 屬性設為 " -"``False``，否則 *stdin* 會被忽略。" - -#: ../../library/cmd.rst:45 -msgid "``completekey='tab'`` is replaced by ``'^I'`` for ``editline``." -msgstr "對於 ``editline``，``completekey='tab'`` 會被替換為 ``'^I'``。" - -#: ../../library/cmd.rst:52 -msgid "Cmd Objects" -msgstr "Cmd 物件" - -#: ../../library/cmd.rst:54 -msgid "A :class:`Cmd` instance has the following methods:" -msgstr ":class:`Cmd` 實例具有以下方法：" - -#: ../../library/cmd.rst:59 -msgid "" -"Repeatedly issue a prompt, accept input, parse an initial prefix off the " -"received input, and dispatch to action methods, passing them the remainder " -"of the line as argument." -msgstr "" -"重複顯示提示字元、接收輸入、剖析接收到的輸入字串前綴，並派發給動作方法，將其" -"餘部分作為引數傳遞給它們" - -#: ../../library/cmd.rst:63 -msgid "" -"The optional argument is a banner or intro string to be issued before the " -"first prompt (this overrides the :attr:`intro` class attribute)." -msgstr "" -"此可選引數為橫幅或導言字串，會在首次顯示提示字元前輸出（此值會覆寫 :attr:" -"`intro` 類別屬性）。" - -#: ../../library/cmd.rst:66 -msgid "" -"If the :mod:`readline` module is loaded, input will automatically inherit :" -"program:`bash`\\ -like history-list editing (e.g. :kbd:`Control-P` scrolls " -"back to the last command, :kbd:`Control-N` forward to the next one, :kbd:" -"`Control-F` moves the cursor to the right non-destructively, :kbd:`Control-" -"B` moves the cursor to the left non-destructively, etc.)." -msgstr "" -"如果已載入 :mod:`readline` 模組，輸入將自動繼承類似 :program:`bash` 的歷史紀" -"錄編輯功能（例如 :kbd:`Control-P` 可向上捲動至上一個命令，:kbd:`Control-N` 向" -"下捲動至下一個命令，:kbd:`Control-F` 非破壞性地將游標向右移動，:kbd:`Control-" -"B` 非破壞性地將游標向左移動等）。" - -#: ../../library/cmd.rst:72 -msgid "An end-of-file on input is passed back as the string ``'EOF'``." -msgstr "當輸入為檔案結尾（EOF）時，會傳回字串 ``'EOF'``。" - -#: ../../library/cmd.rst:78 -msgid "" -"An interpreter instance will recognize a command name ``foo`` if and only if " -"it has a method :meth:`!do_foo`. As a special case, a line beginning with " -"the character ``'?'`` is dispatched to the method :meth:`do_help`. As " -"another special case, a line beginning with the character ``'!'`` is " -"dispatched to the method :meth:`!do_shell` (if such a method is defined)." -msgstr "" -"直譯器實例僅當存在 :meth:`!do_foo` 方法時，才會識別命令名稱 ``foo``。作為特殊" -"情況，以字元 ``'?'`` 開頭的列會被派發至 :meth:`do_help` 方法；另一個特殊情況" -"是，以字元 ``'!'`` 開頭的列會被派發至 :meth:`!do_shell` 方法（若該方法已定" -"義）。" - -#: ../../library/cmd.rst:84 -msgid "" -"This method will return when the :meth:`postcmd` method returns a true " -"value. The *stop* argument to :meth:`postcmd` is the return value from the " -"command's corresponding :meth:`!do_\\*` method." -msgstr "" -"當 :meth:`postcmd` 方法回傳真值時，此方法將會結束。傳遞給 :meth:`postcmd` 的 " -"*stop* 引數是該命令對應的 :meth:`!do_\\*` 方法的回傳值。" - -#: ../../library/cmd.rst:88 -msgid "" -"If completion is enabled, completing commands will be done automatically, " -"and completing of commands args is done by calling :meth:`!complete_foo` " -"with arguments *text*, *line*, *begidx*, and *endidx*. *text* is the string " -"prefix we are attempting to match: all returned matches must begin with it. " -"*line* is the current input line with leading whitespace removed, *begidx* " -"and *endidx* are the beginning and ending indexes of the prefix text, which " -"could be used to provide different completion depending upon which position " -"the argument is in." -msgstr "" -"如果啟用了自動完成，命令的自動完成將會自動執行，而命令引數的自動完成則是透過" -"呼叫 :meth:`!complete_foo` 方法並傳入 *text*、*line*、*begidx* 和 *endidx* 引" -"數來處理。*text* 是要比對的字串前綴：所有回傳的符合項都必須以此字串開頭。" -"*line* 是目前的輸入列（前置空白會被移除），*begidx* 和 *endidx* 則分別是前綴" -"字串的起始與結束索引，可用來根據引數所在的位置提供不同的自動完成結果。" - -#: ../../library/cmd.rst:99 -msgid "" -"All subclasses of :class:`Cmd` inherit a predefined :meth:`!do_help`. This " -"method, called with an argument ``'bar'``, invokes the corresponding method :" -"meth:`!help_bar`, and if that is not present, prints the docstring of :meth:" -"`!do_bar`, if available. With no argument, :meth:`!do_help` lists all " -"available help topics (that is, all commands with corresponding :meth:`!" -"help_\\*` methods or commands that have docstrings), and also lists any " -"undocumented commands." -msgstr "" -"所有 :class:`Cmd` 的子類別都會繼承預先定義的 :meth:`!do_help` 方法。當此方法" -"接收到引數 ``'bar'`` 時，會呼叫對應的 :meth:`!help_bar` 方法；若該方法不存" -"在，則會列印 :meth:`!do_bar` 的說明字串（若有的話）。若未提供任何引數，:meth:" -"`!do_help` 會列出所有可用的說明主題（也就是所有具有對應 :meth:`!help_\\*` 方" -"法或有說明字串的命令），並且也會列出所有尚未記錄的命令。" - -#: ../../library/cmd.rst:110 -msgid "" -"Interpret the argument as though it had been typed in response to the " -"prompt. This may be overridden, but should not normally need to be; see the :" -"meth:`precmd` and :meth:`postcmd` methods for useful execution hooks. The " -"return value is a flag indicating whether interpretation of commands by the " -"interpreter should stop. If there is a :meth:`!do_\\*` method for the " -"command *str*, the return value of that method is returned, otherwise the " -"return value from the :meth:`default` method is returned." -msgstr "" -"將引數視為在回應提示字元時所輸入的內容來直譯。這個方法可以被覆寫，但通常不需" -"要這麼做；參見 :meth:`precmd` 與 :meth:`postcmd` 方法，它們提供實用的執行勾點" -"（hook）。此方法的回傳值是一個旗標，用來指出是否應該停止直譯器對命令的直譯。" -"若有對應 *str* 命令的 :meth:`!do_\\*` 方法，則會回傳該方法的回傳值；否則，回" -"傳值將來自 :meth:`default` 方法。" - -#: ../../library/cmd.rst:121 -msgid "" -"Method called when an empty line is entered in response to the prompt. If " -"this method is not overridden, it repeats the last nonempty command entered." -msgstr "" -"在回應提示字元時輸入空白列，會呼叫此方法。若此方法未被覆寫，則會重復上一次輸" -"入的非空命令。" - -#: ../../library/cmd.rst:127 -msgid "" -"Method called on an input line when the command prefix is not recognized. If " -"this method is not overridden, it prints an error message and returns." -msgstr "" -"當輸入列中的命令前綴無法辨識時，會呼叫此方法。若此方法未被覆寫，則會輸出並回" -"傳錯誤訊息。" - -#: ../../library/cmd.rst:133 -msgid "" -"Method called to complete an input line when no command-specific :meth:`!" -"complete_\\*` method is available. By default, it returns an empty list." -msgstr "" -"當沒有對應特定命令的 :meth:`!complete_\\*` 方法時，會呼叫此方法以完成輸入列。" -"預設會回傳空串列。" - -#: ../../library/cmd.rst:139 -msgid "" -"Method called to display a list of strings as a compact set of columns. Each " -"column is only as wide as necessary. Columns are separated by two spaces for " -"readability." -msgstr "" -"此方法用來將字串串列顯示為緊湊的欄集合。每一欄的寬度僅足以容納其內容，各欄之" -"間以兩個空格分隔，以提高可讀性。" - -#: ../../library/cmd.rst:146 -msgid "" -"Hook method executed just before the command line *line* is interpreted, but " -"after the input prompt is generated and issued. This method is a stub in :" -"class:`Cmd`; it exists to be overridden by subclasses. The return value is " -"used as the command which will be executed by the :meth:`onecmd` method; " -"the :meth:`precmd` implementation may re-write the command or simply return " -"*line* unchanged." -msgstr "" -"勾點方法會在直譯命令列 *line* 前執行，但會在提示字元產生並顯示後才觸發。這個" -"方法在 :class:`Cmd` 類別中為 stub，預期由子類別覆寫。回傳值會作為 :meth:" -"`onecmd` 方法所執行的命令；:meth:`precmd` 的實作可以重寫該命令，或直接回傳未" -"變更的 *line*。" - -#: ../../library/cmd.rst:156 -msgid "" -"Hook method executed just after a command dispatch is finished. This method " -"is a stub in :class:`Cmd`; it exists to be overridden by subclasses. *line* " -"is the command line which was executed, and *stop* is a flag which indicates " -"whether execution will be terminated after the call to :meth:`postcmd`; this " -"will be the return value of the :meth:`onecmd` method. The return value of " -"this method will be used as the new value for the internal flag which " -"corresponds to *stop*; returning false will cause interpretation to continue." -msgstr "" -"勾點方法會在命令派發完成後執行。這個方法在 :class:`Cmd` 類別中為 stub，預期由" -"子類別覆寫。*line* 是剛剛執行的命令列，而 *stop* 是一個旗標，用來指出在呼叫 :" -"meth:`postcmd` 後是否應終止執行；該值即為 :meth:`onecmd` 方法的回傳值。本方法" -"的回傳值將會更新內部的 *stop* 旗標；若回傳 false，則會繼續進行直譯。" - -#: ../../library/cmd.rst:167 -msgid "" -"Hook method executed once when :meth:`cmdloop` is called. This method is a " -"stub in :class:`Cmd`; it exists to be overridden by subclasses." -msgstr "" -"當 :meth:`cmdloop` 被呼叫時，此勾點方法會執行一次。這個方法在 :class:`Cmd` 類" -"別中為 stub，預期由子類別覆寫。" - -#: ../../library/cmd.rst:173 -msgid "" -"Hook method executed once when :meth:`cmdloop` is about to return. This " -"method is a stub in :class:`Cmd`; it exists to be overridden by subclasses." -msgstr "" -"當 :meth:`cmdloop` 即將回傳時，此勾點方法會執行一次。這個方法在 :class:`Cmd` " -"類別中為 stub，預期由子類別覆寫。" - -#: ../../library/cmd.rst:177 -msgid "" -"Instances of :class:`Cmd` subclasses have some public instance variables:" -msgstr ":class:`Cmd` 子類別的實例包含一些公開的實例變數：" - -#: ../../library/cmd.rst:181 -msgid "The prompt issued to solicit input." -msgstr "用來請求輸入的提示字元。" - -#: ../../library/cmd.rst:186 -msgid "The string of characters accepted for the command prefix." -msgstr "可作為命令前綴的字元字串" - -#: ../../library/cmd.rst:191 -msgid "The last nonempty command prefix seen." -msgstr "最後一個遇到的非空命令前綴" - -#: ../../library/cmd.rst:196 -msgid "" -"A list of queued input lines. The cmdqueue list is checked in :meth:" -"`cmdloop` when new input is needed; if it is nonempty, its elements will be " -"processed in order, as if entered at the prompt." -msgstr "" -"排入佇列的輸入列串列。當 :meth:`cmdloop` 需要新輸入時，會檢查 cmdqueue 串列；" -"若不為空，其元素將依序處理，就如同它們是在提示字元中輸入的一樣。" - -#: ../../library/cmd.rst:203 -msgid "" -"A string to issue as an intro or banner. May be overridden by giving the :" -"meth:`cmdloop` method an argument." -msgstr "" -"作為簡介或橫幅的字串。可透過為 :meth:`cmdloop` 方法提供引數來覆寫此內容。" - -#: ../../library/cmd.rst:209 -msgid "" -"The header to issue if the help output has a section for documented commands." -msgstr "若說明輸出包含已記錄命令的區段，則會顯示的標頭字串。" - -#: ../../library/cmd.rst:214 -msgid "" -"The header to issue if the help output has a section for miscellaneous help " -"topics (that is, there are :meth:`!help_\\*` methods without corresponding :" -"meth:`!do_\\*` methods)." -msgstr "" -"若說明輸出包含雜項說明主題的區段（也就是存在 :meth:`!help_\\*` 方法但沒有對應" -"的 :meth:`!do_\\*` 方法），則會顯示的標頭字串。" - -#: ../../library/cmd.rst:221 -msgid "" -"The header to issue if the help output has a section for undocumented " -"commands (that is, there are :meth:`!do_\\*` methods without corresponding :" -"meth:`!help_\\*` methods)." -msgstr "" -"若說明輸出包含未記錄命令的區段（也就是存在 :meth:`!do_\\*` 方法但沒有對應的 :" -"meth:`!help_\\*` 方法），則會顯示的標頭字串。" - -#: ../../library/cmd.rst:228 -msgid "" -"The character used to draw separator lines under the help-message headers. " -"If empty, no ruler line is drawn. It defaults to ``'='``." -msgstr "" -"用於在說明訊息的標頭下方繪製分隔線的字元。若為空，則不會繪製分隔線。預設為 " -"``'='``。" - -#: ../../library/cmd.rst:234 -msgid "" -"A flag, defaulting to true. If true, :meth:`cmdloop` uses :func:`input` to " -"display a prompt and read the next command; if false, :data:`sys.stdout." -"write() ` and :data:`sys.stdin.readline() ` are used. " -"(This means that by importing :mod:`readline`, on systems that support it, " -"the interpreter will automatically support :program:`Emacs`\\ -like line " -"editing and command-history keystrokes.)" -msgstr "" -"一個旗標，預設為 true。若為 true，:meth:`cmdloop` 會使用 :func:`input` 來顯示" -"提示字元並讀取下一個命令；若為 false，則會改用 :data:`sys.stdout.write() " -"` 和 :data:`sys.stdin.readline() `。（這表示在支援的系" -"統中，透過 import :mod:`readline` module，直譯器將自動支援類似 :program:" -"`Emacs` 的列編輯與命令歷史快捷鍵。）" - -#: ../../library/cmd.rst:244 -msgid "Cmd Example" -msgstr "Cmd 範例" - -#: ../../library/cmd.rst:248 -msgid "" -"The :mod:`cmd` module is mainly useful for building custom shells that let a " -"user work with a program interactively." -msgstr "" -":mod:`cmd` module 主要用於建構自訂 shell，讓使用者能以互動方式操作程式。" - -#: ../../library/cmd.rst:251 -msgid "" -"This section presents a simple example of how to build a shell around a few " -"of the commands in the :mod:`turtle` module." -msgstr "" -"本節將示範如何以 :mod:`turtle` module 中的幾個命令為基礎，建立一個簡單的 " -"shell。" - -#: ../../library/cmd.rst:254 -msgid "" -"Basic turtle commands such as :meth:`~turtle.forward` are added to a :class:" -"`Cmd` subclass with method named :meth:`!do_forward`. The argument is " -"converted to a number and dispatched to the turtle module. The docstring is " -"used in the help utility provided by the shell." -msgstr "" -"像是 :meth:`~turtle.forward` 這樣的基本 turtle 命令，可透過新增名為 :meth:`!" -"do_forward` 的方法加入至 :class:`Cmd` 子類別中。傳入的引數會轉換為數值，並傳" -"送給 turtle 模組。該方法的說明字串會用於 shell 所提供的說明功能中。" - -#: ../../library/cmd.rst:259 -msgid "" -"The example also includes a basic record and playback facility implemented " -"with the :meth:`~Cmd.precmd` method which is responsible for converting the " -"input to lowercase and writing the commands to a file. The :meth:`!" -"do_playback` method reads the file and adds the recorded commands to the :" -"attr:`~Cmd.cmdqueue` for immediate playback::" -msgstr "" -"此範例同時包含一個簡單的錄製與重播功能，其實作方式是透過 :meth:`~Cmd.precmd` " -"方法，負責將輸入轉為小寫並寫入檔案。:meth:`!do_playback` 方法則會讀取該檔案，" -"並將錄製的命令加入 :attr:`~Cmd.cmdqueue` 中以供立即重播::" - -#: ../../library/cmd.rst:265 -msgid "" -"import cmd, sys\n" -"from turtle import *\n" -"\n" -"class TurtleShell(cmd.Cmd):\n" -" intro = 'Welcome to the turtle shell. Type help or ? to list commands." -"\\n'\n" -" prompt = '(turtle) '\n" -" file = None\n" -"\n" -" # ----- basic turtle commands -----\n" -" def do_forward(self, arg):\n" -" 'Move the turtle forward by the specified distance: FORWARD 10'\n" -" forward(*parse(arg))\n" -" def do_right(self, arg):\n" -" 'Turn turtle right by given number of degrees: RIGHT 20'\n" -" right(*parse(arg))\n" -" def do_left(self, arg):\n" -" 'Turn turtle left by given number of degrees: LEFT 90'\n" -" left(*parse(arg))\n" -" def do_goto(self, arg):\n" -" 'Move turtle to an absolute position with changing orientation. " -"GOTO 100 200'\n" -" goto(*parse(arg))\n" -" def do_home(self, arg):\n" -" 'Return turtle to the home position: HOME'\n" -" home()\n" -" def do_circle(self, arg):\n" -" 'Draw circle with given radius an options extent and steps: CIRCLE " -"50'\n" -" circle(*parse(arg))\n" -" def do_position(self, arg):\n" -" 'Print the current turtle position: POSITION'\n" -" print('Current position is %d %d\\n' % position())\n" -" def do_heading(self, arg):\n" -" 'Print the current turtle heading in degrees: HEADING'\n" -" print('Current heading is %d\\n' % (heading(),))\n" -" def do_color(self, arg):\n" -" 'Set the color: COLOR BLUE'\n" -" color(arg.lower())\n" -" def do_undo(self, arg):\n" -" 'Undo (repeatedly) the last turtle action(s): UNDO'\n" -" def do_reset(self, arg):\n" -" 'Clear the screen and return turtle to center: RESET'\n" -" reset()\n" -" def do_bye(self, arg):\n" -" 'Stop recording, close the turtle window, and exit: BYE'\n" -" print('Thank you for using Turtle')\n" -" self.close()\n" -" bye()\n" -" return True\n" -"\n" -" # ----- record and playback -----\n" -" def do_record(self, arg):\n" -" 'Save future commands to filename: RECORD rose.cmd'\n" -" self.file = open(arg, 'w')\n" -" def do_playback(self, arg):\n" -" 'Playback commands from a file: PLAYBACK rose.cmd'\n" -" self.close()\n" -" with open(arg) as f:\n" -" self.cmdqueue.extend(f.read().splitlines())\n" -" def precmd(self, line):\n" -" line = line.lower()\n" -" if self.file and 'playback' not in line:\n" -" print(line, file=self.file)\n" -" return line\n" -" def close(self):\n" -" if self.file:\n" -" self.file.close()\n" -" self.file = None\n" -"\n" -"def parse(arg):\n" -" 'Convert a series of zero or more numbers to an argument tuple'\n" -" return tuple(map(int, arg.split()))\n" -"\n" -"if __name__ == '__main__':\n" -" TurtleShell().cmdloop()" -msgstr "" -"import cmd, sys\n" -"from turtle import *\n" -"\n" -"class TurtleShell(cmd.Cmd):\n" -" intro = '歡迎來到 turtle shell。輸入 help 或 ? 來列出命令。\\n'\n" -" prompt = '(turtle) '\n" -" file = None\n" -"\n" -" # ----- 基本烏龜命令 -----\n" -" def do_forward(self, arg):\n" -" '將烏龜向前移動指定的距離： FORWARD 10'\n" -" forward(*parse(arg))\n" -" def do_right(self, arg):\n" -" '將烏龜右轉指定的角度： RIGHT 20'\n" -" right(*parse(arg))\n" -" def do_left(self, arg):\n" -" '將烏龜左轉指定的角度： LEFT 90'\n" -" left(*parse(arg))\n" -" def do_goto(self, arg):\n" -" '將烏龜移動到指定的絕對位置並改變方向。 GOTO 100 200'\n" -" goto(*parse(arg))\n" -" def do_home(self, arg):\n" -" '將烏龜返回起始位置： HOME'\n" -" home()\n" -" def do_circle(self, arg):\n" -" '畫出指定半徑、範圍和步數的圓： CIRCLE 50'\n" -" circle(*parse(arg))\n" -" def do_position(self, arg):\n" -" '顯示目前烏龜位置： POSITION'\n" -" print('目前位置是 %d %d\\n' % position())\n" -" def do_heading(self, arg):\n" -" '顯示目前烏龜方向角度： HEADING'\n" -" print('目前方向是 %d\\n' % (heading(),))\n" -" def do_color(self, arg):\n" -" '設定顏色： COLOR BLUE'\n" -" color(arg.lower())\n" -" def do_undo(self, arg):\n" -" '撤銷（重複）最後一次烏龜動作： UNDO'\n" -" def do_reset(self, arg):\n" -" '清除畫面並將烏龜返回到中心： RESET'\n" -" reset()\n" -" def do_bye(self, arg):\n" -" '停止錄製、關閉烏龜視窗並退出： BYE'\n" -" print('感謝使用 Turtle')\n" -" self.close()\n" -" bye()\n" -" return True\n" -"\n" -" # ----- 錄製與重播 -----\n" -" def do_record(self, arg):\n" -" '將未來命令儲存至檔案： RECORD rose.cmd'\n" -" self.file = open(arg, 'w')\n" -" def do_playback(self, arg):\n" -" '從檔案重播命令： PLAYBACK rose.cmd'\n" -" self.close()\n" -" with open(arg) as f:\n" -" self.cmdqueue.extend(f.read().splitlines())\n" -" def precmd(self, line):\n" -" line = line.lower()\n" -" if self.file and 'playback' not in line:\n" -" print(line, file=self.file)\n" -" return line\n" -" def close(self):\n" -" if self.file:\n" -" self.file.close()\n" -" self.file = None\n" -"\n" -"def parse(arg):\n" -" '將一串零個或多個數字轉換為引數 tuple'\n" -" return tuple(map(int, arg.split()))\n" -"\n" -"if __name__ == '__main__':\n" -" TurtleShell().cmdloop()" - -#: ../../library/cmd.rst:340 -msgid "" -"Here is a sample session with the turtle shell showing the help functions, " -"using blank lines to repeat commands, and the simple record and playback " -"facility:" -msgstr "" -"以下是與 turtle shell 的一段範例互動，展示了說明功能、使用空白列重複執行命" -"令，以及簡單的錄製與重播功能：" - -#: ../../library/cmd.rst:343 -msgid "" -"Welcome to the turtle shell. Type help or ? to list commands.\n" -"\n" -"(turtle) ?\n" -"\n" -"Documented commands (type help ):\n" -"========================================\n" -"bye color goto home playback record right\n" -"circle forward heading left position reset undo\n" -"\n" -"(turtle) help forward\n" -"Move the turtle forward by the specified distance: FORWARD 10\n" -"(turtle) record spiral.cmd\n" -"(turtle) position\n" -"Current position is 0 0\n" -"\n" -"(turtle) heading\n" -"Current heading is 0\n" -"\n" -"(turtle) reset\n" -"(turtle) circle 20\n" -"(turtle) right 30\n" -"(turtle) circle 40\n" -"(turtle) right 30\n" -"(turtle) circle 60\n" -"(turtle) right 30\n" -"(turtle) circle 80\n" -"(turtle) right 30\n" -"(turtle) circle 100\n" -"(turtle) right 30\n" -"(turtle) circle 120\n" -"(turtle) right 30\n" -"(turtle) circle 120\n" -"(turtle) heading\n" -"Current heading is 180\n" -"\n" -"(turtle) forward 100\n" -"(turtle)\n" -"(turtle) right 90\n" -"(turtle) forward 100\n" -"(turtle)\n" -"(turtle) right 90\n" -"(turtle) forward 400\n" -"(turtle) right 90\n" -"(turtle) forward 500\n" -"(turtle) right 90\n" -"(turtle) forward 400\n" -"(turtle) right 90\n" -"(turtle) forward 300\n" -"(turtle) playback spiral.cmd\n" -"Current position is 0 0\n" -"\n" -"Current heading is 0\n" -"\n" -"Current heading is 180\n" -"\n" -"(turtle) bye\n" -"Thank you for using Turtle" -msgstr "" -"歡迎來到 turtle shell。輸入 help 或 ? 來列出命令。\n" -"\n" -"(turtle) ?\n" -"\n" -"已記錄的命令（輸入 help <主題>）：\n" -"========================================\n" -"bye color goto home playback record right\n" -"circle forward heading left position reset undo\n" -"\n" -"(turtle) help forward\n" -"將烏龜向前移動指定的距離： FORWARD 10\n" -"(turtle) record spiral.cmd\n" -"(turtle) position\n" -"目前位置是 0 0\n" -"\n" -"(turtle) heading\n" -"目前方向是 0\n" -"\n" -"(turtle) reset\n" -"(turtle) circle 20\n" -"(turtle) right 30\n" -"(turtle) circle 40\n" -"(turtle) right 30\n" -"(turtle) circle 60\n" -"(turtle) right 30\n" -"(turtle) circle 80\n" -"(turtle) right 30\n" -"(turtle) circle 100\n" -"(turtle) right 30\n" -"(turtle) circle 120\n" -"(turtle) right 30\n" -"(turtle) circle 120\n" -"(turtle) heading\n" -"目前方向是 180\n" -"\n" -"(turtle) forward 100\n" -"(turtle)\n" -"(turtle) right 90\n" -"(turtle) forward 100\n" -"(turtle)\n" -"(turtle) right 90\n" -"(turtle) forward 400\n" -"(turtle) right 90\n" -"(turtle) forward 500\n" -"(turtle) right 90\n" -"(turtle) forward 400\n" -"(turtle) right 90\n" -"(turtle) forward 300\n" -"(turtle) playback spiral.cmd\n" -"目前位置是 0 0\n" -"\n" -"目前方向是 0\n" -"\n" -"目前方向是 180\n" -"\n" -"(turtle) bye\n" -"感謝使用 Turtle" - -#: ../../library/cmd.rst:74 -msgid "? (question mark)" -msgstr "? （問號）" - -#: ../../library/cmd.rst:74 -msgid "in a command interpreter" -msgstr "於 command interpreter（命令直譯器）中" - -#: ../../library/cmd.rst:74 -msgid "! (exclamation)" -msgstr "! （驚嘆號）" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Dr-XYZ , 2025 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-09-23 07:52+0800\n" +"PO-Revision-Date: 2025-05-19 20:25+0800\n" +"Last-Translator: Dr-XYZ \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/cmd.rst:2 +msgid ":mod:`!cmd` --- Support for line-oriented command interpreters" +msgstr ":mod:`!cmd` --- 以列為導向的命令直譯器支援" + +#: ../../library/cmd.rst:9 +msgid "**Source code:** :source:`Lib/cmd.py`" +msgstr "**原始碼：**\\ :source:`Lib/cmd.py`" + +#: ../../library/cmd.rst:13 +msgid "" +"The :class:`Cmd` class provides a simple framework for writing line-oriented " +"command interpreters. These are often useful for test harnesses, " +"administrative tools, and prototypes that will later be wrapped in a more " +"sophisticated interface." +msgstr "" +":class:`Cmd` 類別提供了一個簡單的架構，用於撰寫列導向的命令直譯器。這類直譯器" +"常用於測試控制工具、管理工具以及日後將包裝於更高階介面的原型中。" + +#: ../../library/cmd.rst:20 +msgid "" +"A :class:`Cmd` instance or subclass instance is a line-oriented interpreter " +"framework. There is no good reason to instantiate :class:`Cmd` itself; " +"rather, it's useful as a superclass of an interpreter class you define " +"yourself in order to inherit :class:`Cmd`'s methods and encapsulate action " +"methods." +msgstr "" +":class:`Cmd` 實例或其子類別實例是一種列導向的直譯器架構。通常沒有必要直接實例" +"化 :class:`Cmd` 本身；它更適合作為你自己定義的直譯器類別的父類別，讓你能繼承 :" +"class:`Cmd` 的方法，並封裝動作方法。" + +#: ../../library/cmd.rst:25 +msgid "" +"The optional argument *completekey* is the :mod:`readline` name of a " +"completion key; it defaults to :kbd:`Tab`. If *completekey* is not :const:" +"`None` and :mod:`readline` is available, command completion is done " +"automatically." +msgstr "" +"可選引數 *completekey* 是 :mod:`readline` 模組中用於自動完成的按鍵名稱；預設" +"為 :kbd:`Tab`。若 *completekey* 不為 :const:`None` 且 :mod:`readline` 可用，" +"則會自動啟用命令自動完成功能。" + +#: ../../library/cmd.rst:29 +msgid "" +"The default, ``'tab'``, is treated specially, so that it refers to the :kbd:" +"`Tab` key on every :data:`readline.backend`. Specifically, if :data:" +"`readline.backend` is ``editline``, ``Cmd`` will use ``'^I'`` instead of " +"``'tab'``. Note that other values are not treated this way, and might only " +"work with a specific backend." +msgstr "" +"預設值 ``'tab'`` 會被特殊處理，使其在所有的 :data:`readline.backend` 中皆代" +"表 :kbd:`Tab` 鍵。具體來說，若 :data:`readline.backend` 為 ``editline``，則 " +"``Cmd`` 會改用 ``'^I'`` 取代 ``'tab'``。請注意，其他值不會有此處理方式，且可" +"能僅能在特定的後端中適用。" + +#: ../../library/cmd.rst:36 +msgid "" +"The optional arguments *stdin* and *stdout* specify the input and output " +"file objects that the Cmd instance or subclass instance will use for input " +"and output. If not specified, they will default to :data:`sys.stdin` and :" +"data:`sys.stdout`." +msgstr "" +"可選引數 *stdin* 與 *stdout* 用來指定 Cmd 實例或其子類別實例所使用的輸入與輸" +"出檔案物件。若未指定，預設為 :data:`sys.stdin` 與 :data:`sys.stdout`。" + +#: ../../library/cmd.rst:41 +msgid "" +"If you want a given *stdin* to be used, make sure to set the instance's :" +"attr:`use_rawinput` attribute to ``False``, otherwise *stdin* will be " +"ignored." +msgstr "" +"若你希望使用指定的 *stdin*，請務必將該實例的 :attr:`use_rawinput` 屬性設為 " +"``False``，否則 *stdin* 會被忽略。" + +#: ../../library/cmd.rst:45 +msgid "``completekey='tab'`` is replaced by ``'^I'`` for ``editline``." +msgstr "對於 ``editline``，``completekey='tab'`` 會被替換為 ``'^I'``。" + +#: ../../library/cmd.rst:52 +msgid "Cmd Objects" +msgstr "Cmd 物件" + +#: ../../library/cmd.rst:54 +msgid "A :class:`Cmd` instance has the following methods:" +msgstr ":class:`Cmd` 實例具有以下方法：" + +#: ../../library/cmd.rst:59 +msgid "" +"Repeatedly issue a prompt, accept input, parse an initial prefix off the " +"received input, and dispatch to action methods, passing them the remainder " +"of the line as argument." +msgstr "" +"重複顯示提示字元、接收輸入、剖析接收到的輸入字串前綴，並派發給動作方法，將其" +"餘部分作為引數傳遞給它們" + +#: ../../library/cmd.rst:63 +msgid "" +"The optional argument is a banner or intro string to be issued before the " +"first prompt (this overrides the :attr:`intro` class attribute)." +msgstr "" +"此可選引數為橫幅或導言字串，會在首次顯示提示字元前輸出（此值會覆寫 :attr:" +"`intro` 類別屬性）。" + +#: ../../library/cmd.rst:66 +msgid "" +"If the :mod:`readline` module is loaded, input will automatically inherit :" +"program:`bash`\\ -like history-list editing (e.g. :kbd:`Control-P` scrolls " +"back to the last command, :kbd:`Control-N` forward to the next one, :kbd:" +"`Control-F` moves the cursor to the right non-destructively, :kbd:`Control-" +"B` moves the cursor to the left non-destructively, etc.)." +msgstr "" +"如果已載入 :mod:`readline` 模組，輸入將自動繼承類似 :program:`bash` 的歷史紀" +"錄編輯功能（例如 :kbd:`Control-P` 可向上捲動至上一個命令，:kbd:`Control-N` 向" +"下捲動至下一個命令，:kbd:`Control-F` 非破壞性地將游標向右移動，:kbd:`Control-" +"B` 非破壞性地將游標向左移動等）。" + +#: ../../library/cmd.rst:72 +msgid "An end-of-file on input is passed back as the string ``'EOF'``." +msgstr "當輸入為檔案結尾（EOF）時，會傳回字串 ``'EOF'``。" + +#: ../../library/cmd.rst:78 +msgid "" +"An interpreter instance will recognize a command name ``foo`` if and only if " +"it has a method :meth:`!do_foo`. As a special case, a line beginning with " +"the character ``'?'`` is dispatched to the method :meth:`do_help`. As " +"another special case, a line beginning with the character ``'!'`` is " +"dispatched to the method :meth:`!do_shell` (if such a method is defined)." +msgstr "" +"直譯器實例僅當存在 :meth:`!do_foo` 方法時，才會識別命令名稱 ``foo``。作為特殊" +"情況，以字元 ``'?'`` 開頭的列會被派發至 :meth:`do_help` 方法；另一個特殊情況" +"是，以字元 ``'!'`` 開頭的列會被派發至 :meth:`!do_shell` 方法（若該方法已定" +"義）。" + +#: ../../library/cmd.rst:84 +msgid "" +"This method will return when the :meth:`postcmd` method returns a true " +"value. The *stop* argument to :meth:`postcmd` is the return value from the " +"command's corresponding :meth:`!do_\\*` method." +msgstr "" +"當 :meth:`postcmd` 方法回傳真值時，此方法將會結束。傳遞給 :meth:`postcmd` 的 " +"*stop* 引數是該命令對應的 :meth:`!do_\\*` 方法的回傳值。" + +#: ../../library/cmd.rst:88 +msgid "" +"If completion is enabled, completing commands will be done automatically, " +"and completing of commands args is done by calling :meth:`!complete_foo` " +"with arguments *text*, *line*, *begidx*, and *endidx*. *text* is the string " +"prefix we are attempting to match: all returned matches must begin with it. " +"*line* is the current input line with leading whitespace removed, *begidx* " +"and *endidx* are the beginning and ending indexes of the prefix text, which " +"could be used to provide different completion depending upon which position " +"the argument is in." +msgstr "" +"如果啟用了自動完成，命令的自動完成將會自動執行，而命令引數的自動完成則是透過" +"呼叫 :meth:`!complete_foo` 方法並傳入 *text*、*line*、*begidx* 和 *endidx* 引" +"數來處理。*text* 是要比對的字串前綴：所有回傳的符合項都必須以此字串開頭。" +"*line* 是目前的輸入列（前置空白會被移除），*begidx* 和 *endidx* 則分別是前綴" +"字串的起始與結束索引，可用來根據引數所在的位置提供不同的自動完成結果。" + +#: ../../library/cmd.rst:99 +msgid "" +"All subclasses of :class:`Cmd` inherit a predefined :meth:`!do_help`. This " +"method, called with an argument ``'bar'``, invokes the corresponding method :" +"meth:`!help_bar`, and if that is not present, prints the docstring of :meth:" +"`!do_bar`, if available. With no argument, :meth:`!do_help` lists all " +"available help topics (that is, all commands with corresponding :meth:`!" +"help_\\*` methods or commands that have docstrings), and also lists any " +"undocumented commands." +msgstr "" +"所有 :class:`Cmd` 的子類別都會繼承預先定義的 :meth:`!do_help` 方法。當此方法" +"接收到引數 ``'bar'`` 時，會呼叫對應的 :meth:`!help_bar` 方法；若該方法不存" +"在，則會列印 :meth:`!do_bar` 的說明字串（若有的話）。若未提供任何引數，:meth:" +"`!do_help` 會列出所有可用的說明主題（也就是所有具有對應 :meth:`!help_\\*` 方" +"法或有說明字串的命令），並且也會列出所有尚未記錄的命令。" + +#: ../../library/cmd.rst:110 +msgid "" +"Interpret the argument as though it had been typed in response to the " +"prompt. This may be overridden, but should not normally need to be; see the :" +"meth:`precmd` and :meth:`postcmd` methods for useful execution hooks. The " +"return value is a flag indicating whether interpretation of commands by the " +"interpreter should stop. If there is a :meth:`!do_\\*` method for the " +"command *str*, the return value of that method is returned, otherwise the " +"return value from the :meth:`default` method is returned." +msgstr "" +"將引數視為在回應提示字元時所輸入的內容來直譯。這個方法可以被覆寫，但通常不需" +"要這麼做；參見 :meth:`precmd` 與 :meth:`postcmd` 方法，它們提供實用的執行勾點" +"（hook）。此方法的回傳值是一個旗標，用來指出是否應該停止直譯器對命令的直譯。" +"若有對應 *str* 命令的 :meth:`!do_\\*` 方法，則會回傳該方法的回傳值；否則，回" +"傳值將來自 :meth:`default` 方法。" + +#: ../../library/cmd.rst:121 +msgid "" +"Method called when an empty line is entered in response to the prompt. If " +"this method is not overridden, it repeats the last nonempty command entered." +msgstr "" +"在回應提示字元時輸入空白列，會呼叫此方法。若此方法未被覆寫，則會重復上一次輸" +"入的非空命令。" + +#: ../../library/cmd.rst:127 +msgid "" +"Method called on an input line when the command prefix is not recognized. If " +"this method is not overridden, it prints an error message and returns." +msgstr "" +"當輸入列中的命令前綴無法辨識時，會呼叫此方法。若此方法未被覆寫，則會輸出並回" +"傳錯誤訊息。" + +#: ../../library/cmd.rst:133 +msgid "" +"Method called to complete an input line when no command-specific :meth:`!" +"complete_\\*` method is available. By default, it returns an empty list." +msgstr "" +"當沒有對應特定命令的 :meth:`!complete_\\*` 方法時，會呼叫此方法以完成輸入列。" +"預設會回傳空串列。" + +#: ../../library/cmd.rst:139 +msgid "" +"Method called to display a list of strings as a compact set of columns. Each " +"column is only as wide as necessary. Columns are separated by two spaces for " +"readability." +msgstr "" +"此方法用來將字串串列顯示為緊湊的欄集合。每一欄的寬度僅足以容納其內容，各欄之" +"間以兩個空格分隔，以提高可讀性。" + +#: ../../library/cmd.rst:146 +msgid "" +"Hook method executed just before the command line *line* is interpreted, but " +"after the input prompt is generated and issued. This method is a stub in :" +"class:`Cmd`; it exists to be overridden by subclasses. The return value is " +"used as the command which will be executed by the :meth:`onecmd` method; " +"the :meth:`precmd` implementation may re-write the command or simply return " +"*line* unchanged." +msgstr "" +"勾點方法會在直譯命令列 *line* 前執行，但會在提示字元產生並顯示後才觸發。這個" +"方法在 :class:`Cmd` 類別中為 stub，預期由子類別覆寫。回傳值會作為 :meth:" +"`onecmd` 方法所執行的命令；:meth:`precmd` 的實作可以重寫該命令，或直接回傳未" +"變更的 *line*。" + +#: ../../library/cmd.rst:156 +msgid "" +"Hook method executed just after a command dispatch is finished. This method " +"is a stub in :class:`Cmd`; it exists to be overridden by subclasses. *line* " +"is the command line which was executed, and *stop* is a flag which indicates " +"whether execution will be terminated after the call to :meth:`postcmd`; this " +"will be the return value of the :meth:`onecmd` method. The return value of " +"this method will be used as the new value for the internal flag which " +"corresponds to *stop*; returning false will cause interpretation to continue." +msgstr "" +"勾點方法會在命令派發完成後執行。這個方法在 :class:`Cmd` 類別中為 stub，預期由" +"子類別覆寫。*line* 是剛剛執行的命令列，而 *stop* 是一個旗標，用來指出在呼叫 :" +"meth:`postcmd` 後是否應終止執行；該值即為 :meth:`onecmd` 方法的回傳值。本方法" +"的回傳值將會更新內部的 *stop* 旗標；若回傳 false，則會繼續進行直譯。" + +#: ../../library/cmd.rst:167 +msgid "" +"Hook method executed once when :meth:`cmdloop` is called. This method is a " +"stub in :class:`Cmd`; it exists to be overridden by subclasses." +msgstr "" +"當 :meth:`cmdloop` 被呼叫時，此勾點方法會執行一次。這個方法在 :class:`Cmd` 類" +"別中為 stub，預期由子類別覆寫。" + +#: ../../library/cmd.rst:173 +msgid "" +"Hook method executed once when :meth:`cmdloop` is about to return. This " +"method is a stub in :class:`Cmd`; it exists to be overridden by subclasses." +msgstr "" +"當 :meth:`cmdloop` 即將回傳時，此勾點方法會執行一次。這個方法在 :class:`Cmd` " +"類別中為 stub，預期由子類別覆寫。" + +#: ../../library/cmd.rst:177 +msgid "" +"Instances of :class:`Cmd` subclasses have some public instance variables:" +msgstr ":class:`Cmd` 子類別的實例包含一些公開的實例變數：" + +#: ../../library/cmd.rst:181 +msgid "The prompt issued to solicit input." +msgstr "用來請求輸入的提示字元。" + +#: ../../library/cmd.rst:186 +msgid "The string of characters accepted for the command prefix." +msgstr "可作為命令前綴的字元字串" + +#: ../../library/cmd.rst:191 +msgid "The last nonempty command prefix seen." +msgstr "最後一個遇到的非空命令前綴" + +#: ../../library/cmd.rst:196 +msgid "" +"A list of queued input lines. The cmdqueue list is checked in :meth:" +"`cmdloop` when new input is needed; if it is nonempty, its elements will be " +"processed in order, as if entered at the prompt." +msgstr "" +"排入佇列的輸入列串列。當 :meth:`cmdloop` 需要新輸入時，會檢查 cmdqueue 串列；" +"若不為空，其元素將依序處理，就如同它們是在提示字元中輸入的一樣。" + +#: ../../library/cmd.rst:203 +msgid "" +"A string to issue as an intro or banner. May be overridden by giving the :" +"meth:`cmdloop` method an argument." +msgstr "" +"作為簡介或橫幅的字串。可透過為 :meth:`cmdloop` 方法提供引數來覆寫此內容。" + +#: ../../library/cmd.rst:209 +msgid "" +"The header to issue if the help output has a section for documented commands." +msgstr "若說明輸出包含已記錄命令的區段，則會顯示的標頭字串。" + +#: ../../library/cmd.rst:214 +msgid "" +"The header to issue if the help output has a section for miscellaneous help " +"topics (that is, there are :meth:`!help_\\*` methods without corresponding :" +"meth:`!do_\\*` methods)." +msgstr "" +"若說明輸出包含雜項說明主題的區段（也就是存在 :meth:`!help_\\*` 方法但沒有對應" +"的 :meth:`!do_\\*` 方法），則會顯示的標頭字串。" + +#: ../../library/cmd.rst:221 +msgid "" +"The header to issue if the help output has a section for undocumented " +"commands (that is, there are :meth:`!do_\\*` methods without corresponding :" +"meth:`!help_\\*` methods)." +msgstr "" +"若說明輸出包含未記錄命令的區段（也就是存在 :meth:`!do_\\*` 方法但沒有對應的 :" +"meth:`!help_\\*` 方法），則會顯示的標頭字串。" + +#: ../../library/cmd.rst:228 +msgid "" +"The character used to draw separator lines under the help-message headers. " +"If empty, no ruler line is drawn. It defaults to ``'='``." +msgstr "" +"用於在說明訊息的標頭下方繪製分隔線的字元。若為空，則不會繪製分隔線。預設為 " +"``'='``。" + +#: ../../library/cmd.rst:234 +msgid "" +"A flag, defaulting to true. If true, :meth:`cmdloop` uses :func:`input` to " +"display a prompt and read the next command; if false, :data:`sys.stdout." +"write() ` and :data:`sys.stdin.readline() ` are used. " +"(This means that by importing :mod:`readline`, on systems that support it, " +"the interpreter will automatically support :program:`Emacs`\\ -like line " +"editing and command-history keystrokes.)" +msgstr "" +"一個旗標，預設為 true。若為 true，:meth:`cmdloop` 會使用 :func:`input` 來顯示" +"提示字元並讀取下一個命令；若為 false，則會改用 :data:`sys.stdout.write() " +"` 和 :data:`sys.stdin.readline() `。（這表示在支援的系" +"統中，透過 import :mod:`readline` module，直譯器將自動支援類似 :program:" +"`Emacs` 的列編輯與命令歷史快捷鍵。）" + +#: ../../library/cmd.rst:244 +msgid "Cmd Example" +msgstr "Cmd 範例" + +#: ../../library/cmd.rst:248 +msgid "" +"The :mod:`cmd` module is mainly useful for building custom shells that let a " +"user work with a program interactively." +msgstr "" +":mod:`cmd` module 主要用於建構自訂 shell，讓使用者能以互動方式操作程式。" + +#: ../../library/cmd.rst:251 +msgid "" +"This section presents a simple example of how to build a shell around a few " +"of the commands in the :mod:`turtle` module." +msgstr "" +"本節將示範如何以 :mod:`turtle` module 中的幾個命令為基礎，建立一個簡單的 " +"shell。" + +#: ../../library/cmd.rst:254 +msgid "" +"Basic turtle commands such as :meth:`~turtle.forward` are added to a :class:" +"`Cmd` subclass with method named :meth:`!do_forward`. The argument is " +"converted to a number and dispatched to the turtle module. The docstring is " +"used in the help utility provided by the shell." +msgstr "" +"像是 :meth:`~turtle.forward` 這樣的基本 turtle 命令，可透過新增名為 :meth:`!" +"do_forward` 的方法加入至 :class:`Cmd` 子類別中。傳入的引數會轉換為數值，並傳" +"送給 turtle 模組。該方法的說明字串會用於 shell 所提供的說明功能中。" + +#: ../../library/cmd.rst:259 +msgid "" +"The example also includes a basic record and playback facility implemented " +"with the :meth:`~Cmd.precmd` method which is responsible for converting the " +"input to lowercase and writing the commands to a file. The :meth:`!" +"do_playback` method reads the file and adds the recorded commands to the :" +"attr:`~Cmd.cmdqueue` for immediate playback::" +msgstr "" +"此範例同時包含一個簡單的錄製與重播功能，其實作方式是透過 :meth:`~Cmd.precmd` " +"方法，負責將輸入轉為小寫並寫入檔案。:meth:`!do_playback` 方法則會讀取該檔案，" +"並將錄製的命令加入 :attr:`~Cmd.cmdqueue` 中以供立即重播::" + +#: ../../library/cmd.rst:265 +msgid "" +"import cmd, sys\n" +"from turtle import *\n" +"\n" +"class TurtleShell(cmd.Cmd):\n" +" intro = 'Welcome to the turtle shell. Type help or ? to list commands." +"\\n'\n" +" prompt = '(turtle) '\n" +" file = None\n" +"\n" +" # ----- basic turtle commands -----\n" +" def do_forward(self, arg):\n" +" 'Move the turtle forward by the specified distance: FORWARD 10'\n" +" forward(*parse(arg))\n" +" def do_right(self, arg):\n" +" 'Turn turtle right by given number of degrees: RIGHT 20'\n" +" right(*parse(arg))\n" +" def do_left(self, arg):\n" +" 'Turn turtle left by given number of degrees: LEFT 90'\n" +" left(*parse(arg))\n" +" def do_goto(self, arg):\n" +" 'Move turtle to an absolute position with changing orientation. " +"GOTO 100 200'\n" +" goto(*parse(arg))\n" +" def do_home(self, arg):\n" +" 'Return turtle to the home position: HOME'\n" +" home()\n" +" def do_circle(self, arg):\n" +" 'Draw circle with given radius an options extent and steps: CIRCLE " +"50'\n" +" circle(*parse(arg))\n" +" def do_position(self, arg):\n" +" 'Print the current turtle position: POSITION'\n" +" print('Current position is %d %d\\n' % position())\n" +" def do_heading(self, arg):\n" +" 'Print the current turtle heading in degrees: HEADING'\n" +" print('Current heading is %d\\n' % (heading(),))\n" +" def do_color(self, arg):\n" +" 'Set the color: COLOR BLUE'\n" +" color(arg.lower())\n" +" def do_undo(self, arg):\n" +" 'Undo (repeatedly) the last turtle action(s): UNDO'\n" +" def do_reset(self, arg):\n" +" 'Clear the screen and return turtle to center: RESET'\n" +" reset()\n" +" def do_bye(self, arg):\n" +" 'Stop recording, close the turtle window, and exit: BYE'\n" +" print('Thank you for using Turtle')\n" +" self.close()\n" +" bye()\n" +" return True\n" +"\n" +" # ----- record and playback -----\n" +" def do_record(self, arg):\n" +" 'Save future commands to filename: RECORD rose.cmd'\n" +" self.file = open(arg, 'w')\n" +" def do_playback(self, arg):\n" +" 'Playback commands from a file: PLAYBACK rose.cmd'\n" +" self.close()\n" +" with open(arg) as f:\n" +" self.cmdqueue.extend(f.read().splitlines())\n" +" def precmd(self, line):\n" +" line = line.lower()\n" +" if self.file and 'playback' not in line:\n" +" print(line, file=self.file)\n" +" return line\n" +" def close(self):\n" +" if self.file:\n" +" self.file.close()\n" +" self.file = None\n" +"\n" +"def parse(arg):\n" +" 'Convert a series of zero or more numbers to an argument tuple'\n" +" return tuple(map(int, arg.split()))\n" +"\n" +"if __name__ == '__main__':\n" +" TurtleShell().cmdloop()" +msgstr "" +"import cmd, sys\n" +"from turtle import *\n" +"\n" +"class TurtleShell(cmd.Cmd):\n" +" intro = '歡迎來到 turtle shell。輸入 help 或 ? 來列出命令。\\n'\n" +" prompt = '(turtle) '\n" +" file = None\n" +"\n" +" # ----- 基本烏龜命令 -----\n" +" def do_forward(self, arg):\n" +" '將烏龜向前移動指定的距離： FORWARD 10'\n" +" forward(*parse(arg))\n" +" def do_right(self, arg):\n" +" '將烏龜右轉指定的角度： RIGHT 20'\n" +" right(*parse(arg))\n" +" def do_left(self, arg):\n" +" '將烏龜左轉指定的角度： LEFT 90'\n" +" left(*parse(arg))\n" +" def do_goto(self, arg):\n" +" '將烏龜移動到指定的絕對位置並改變方向。 GOTO 100 200'\n" +" goto(*parse(arg))\n" +" def do_home(self, arg):\n" +" '將烏龜返回起始位置： HOME'\n" +" home()\n" +" def do_circle(self, arg):\n" +" '畫出指定半徑、範圍和步數的圓： CIRCLE 50'\n" +" circle(*parse(arg))\n" +" def do_position(self, arg):\n" +" '顯示目前烏龜位置： POSITION'\n" +" print('目前位置是 %d %d\\n' % position())\n" +" def do_heading(self, arg):\n" +" '顯示目前烏龜方向角度： HEADING'\n" +" print('目前方向是 %d\\n' % (heading(),))\n" +" def do_color(self, arg):\n" +" '設定顏色： COLOR BLUE'\n" +" color(arg.lower())\n" +" def do_undo(self, arg):\n" +" '撤銷（重複）最後一次烏龜動作： UNDO'\n" +" def do_reset(self, arg):\n" +" '清除畫面並將烏龜返回到中心： RESET'\n" +" reset()\n" +" def do_bye(self, arg):\n" +" '停止錄製、關閉烏龜視窗並退出： BYE'\n" +" print('感謝使用 Turtle')\n" +" self.close()\n" +" bye()\n" +" return True\n" +"\n" +" # ----- 錄製與重播 -----\n" +" def do_record(self, arg):\n" +" '將未來命令儲存至檔案： RECORD rose.cmd'\n" +" self.file = open(arg, 'w')\n" +" def do_playback(self, arg):\n" +" '從檔案重播命令： PLAYBACK rose.cmd'\n" +" self.close()\n" +" with open(arg) as f:\n" +" self.cmdqueue.extend(f.read().splitlines())\n" +" def precmd(self, line):\n" +" line = line.lower()\n" +" if self.file and 'playback' not in line:\n" +" print(line, file=self.file)\n" +" return line\n" +" def close(self):\n" +" if self.file:\n" +" self.file.close()\n" +" self.file = None\n" +"\n" +"def parse(arg):\n" +" '將一串零個或多個數字轉換為引數 tuple'\n" +" return tuple(map(int, arg.split()))\n" +"\n" +"if __name__ == '__main__':\n" +" TurtleShell().cmdloop()" + +#: ../../library/cmd.rst:340 +msgid "" +"Here is a sample session with the turtle shell showing the help functions, " +"using blank lines to repeat commands, and the simple record and playback " +"facility:" +msgstr "" +"以下是與 turtle shell 的一段範例互動，展示了說明功能、使用空白列重複執行命" +"令，以及簡單的錄製與重播功能：" + +#: ../../library/cmd.rst:343 +msgid "" +"Welcome to the turtle shell. Type help or ? to list commands.\n" +"\n" +"(turtle) ?\n" +"\n" +"Documented commands (type help ):\n" +"========================================\n" +"bye color goto home playback record right\n" +"circle forward heading left position reset undo\n" +"\n" +"(turtle) help forward\n" +"Move the turtle forward by the specified distance: FORWARD 10\n" +"(turtle) record spiral.cmd\n" +"(turtle) position\n" +"Current position is 0 0\n" +"\n" +"(turtle) heading\n" +"Current heading is 0\n" +"\n" +"(turtle) reset\n" +"(turtle) circle 20\n" +"(turtle) right 30\n" +"(turtle) circle 40\n" +"(turtle) right 30\n" +"(turtle) circle 60\n" +"(turtle) right 30\n" +"(turtle) circle 80\n" +"(turtle) right 30\n" +"(turtle) circle 100\n" +"(turtle) right 30\n" +"(turtle) circle 120\n" +"(turtle) right 30\n" +"(turtle) circle 120\n" +"(turtle) heading\n" +"Current heading is 180\n" +"\n" +"(turtle) forward 100\n" +"(turtle)\n" +"(turtle) right 90\n" +"(turtle) forward 100\n" +"(turtle)\n" +"(turtle) right 90\n" +"(turtle) forward 400\n" +"(turtle) right 90\n" +"(turtle) forward 500\n" +"(turtle) right 90\n" +"(turtle) forward 400\n" +"(turtle) right 90\n" +"(turtle) forward 300\n" +"(turtle) playback spiral.cmd\n" +"Current position is 0 0\n" +"\n" +"Current heading is 0\n" +"\n" +"Current heading is 180\n" +"\n" +"(turtle) bye\n" +"Thank you for using Turtle" +msgstr "" +"歡迎來到 turtle shell。輸入 help 或 ? 來列出命令。\n" +"\n" +"(turtle) ?\n" +"\n" +"已記錄的命令（輸入 help <主題>）：\n" +"========================================\n" +"bye color goto home playback record right\n" +"circle forward heading left position reset undo\n" +"\n" +"(turtle) help forward\n" +"將烏龜向前移動指定的距離： FORWARD 10\n" +"(turtle) record spiral.cmd\n" +"(turtle) position\n" +"目前位置是 0 0\n" +"\n" +"(turtle) heading\n" +"目前方向是 0\n" +"\n" +"(turtle) reset\n" +"(turtle) circle 20\n" +"(turtle) right 30\n" +"(turtle) circle 40\n" +"(turtle) right 30\n" +"(turtle) circle 60\n" +"(turtle) right 30\n" +"(turtle) circle 80\n" +"(turtle) right 30\n" +"(turtle) circle 100\n" +"(turtle) right 30\n" +"(turtle) circle 120\n" +"(turtle) right 30\n" +"(turtle) circle 120\n" +"(turtle) heading\n" +"目前方向是 180\n" +"\n" +"(turtle) forward 100\n" +"(turtle)\n" +"(turtle) right 90\n" +"(turtle) forward 100\n" +"(turtle)\n" +"(turtle) right 90\n" +"(turtle) forward 400\n" +"(turtle) right 90\n" +"(turtle) forward 500\n" +"(turtle) right 90\n" +"(turtle) forward 400\n" +"(turtle) right 90\n" +"(turtle) forward 300\n" +"(turtle) playback spiral.cmd\n" +"目前位置是 0 0\n" +"\n" +"目前方向是 0\n" +"\n" +"目前方向是 180\n" +"\n" +"(turtle) bye\n" +"感謝使用 Turtle" + +#: ../../library/cmd.rst:74 +msgid "? (question mark)" +msgstr "? （問號）" + +#: ../../library/cmd.rst:74 +msgid "in a command interpreter" +msgstr "於 command interpreter（命令直譯器）中" + +#: ../../library/cmd.rst:74 +msgid "! (exclamation)" +msgstr "! （驚嘆號）" diff --git a/library/cmdline.po b/library/cmdline.po index 0c92f34f26..ebe47755ea 100644 --- a/library/cmdline.po +++ b/library/cmdline.po @@ -1,230 +1,230 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Matt Wang , 2023 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-18 00:15+0000\n" -"PO-Revision-Date: 2023-10-14 16:03+0800\n" -"Last-Translator: Matt Wang \n" -"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" -"tw)\n" -"Language: zh_TW\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=UTF-8\n" -"Content-Transfer-Encoding: 8bit\n" - -#: ../../library/cmdline.rst:5 -msgid "Modules command-line interface (CLI)" -msgstr "模組命令列介面" - -#: ../../library/cmdline.rst:7 -msgid "The following modules have a command-line interface." -msgstr "以下模組具有命令列介面。" - -#: ../../library/cmdline.rst:9 -msgid ":ref:`ast `" -msgstr ":ref:`ast `" - -#: ../../library/cmdline.rst:10 -msgid ":ref:`asyncio `" -msgstr ":ref:`asyncio `" - -#: ../../library/cmdline.rst:11 -msgid ":mod:`base64`" -msgstr ":mod:`base64`" - -#: ../../library/cmdline.rst:12 -msgid ":ref:`calendar `" -msgstr ":ref:`calendar `" - -#: ../../library/cmdline.rst:13 -msgid ":mod:`code`" -msgstr ":mod:`code`" - -#: ../../library/cmdline.rst:14 -msgid ":ref:`compileall `" -msgstr ":ref:`compileall `" - -#: ../../library/cmdline.rst:15 -msgid ":mod:`cProfile`: see :ref:`profile `" -msgstr ":mod:`cProfile`: 請見 :ref:`profile `" - -#: ../../library/cmdline.rst:16 -msgid ":ref:`dis `" -msgstr ":ref:`dis `" - -#: ../../library/cmdline.rst:17 -msgid ":ref:`doctest `" -msgstr ":ref:`doctest `" - -#: ../../library/cmdline.rst:18 -msgid ":mod:`!encodings.rot_13`" -msgstr ":mod:`!encodings.rot_13`" - -#: ../../library/cmdline.rst:19 -msgid ":ref:`ensurepip `" -msgstr ":ref:`ensurepip `" - -#: ../../library/cmdline.rst:20 -msgid ":mod:`filecmp`" -msgstr ":mod:`filecmp`" - -#: ../../library/cmdline.rst:21 -msgid ":mod:`fileinput`" -msgstr ":mod:`fileinput`" - -#: ../../library/cmdline.rst:22 -msgid ":mod:`ftplib`" -msgstr ":mod:`ftplib`" - -#: ../../library/cmdline.rst:23 -msgid ":ref:`gzip `" -msgstr ":ref:`gzip `" - -#: ../../library/cmdline.rst:24 -msgid ":ref:`http.server `" -msgstr ":ref:`http.server `" - -#: ../../library/cmdline.rst:25 -msgid ":ref:`idlelib `" -msgstr ":ref:`idlelib `" - -#: ../../library/cmdline.rst:26 -msgid ":ref:`inspect `" -msgstr ":ref:`inspect `" - -#: ../../library/cmdline.rst:27 -msgid ":ref:`json `" -msgstr ":ref:`json `" - -#: ../../library/cmdline.rst:28 -msgid ":ref:`mimetypes `" -msgstr ":ref:`mimetypes `" - -#: ../../library/cmdline.rst:29 -msgid ":ref:`pdb `" -msgstr ":ref:`pdb `" - -#: ../../library/cmdline.rst:30 -msgid ":ref:`pickle `" -msgstr ":ref:`pickle `" - -#: ../../library/cmdline.rst:31 -msgid ":ref:`pickletools `" -msgstr ":ref:`pickletools `" - -#: ../../library/cmdline.rst:32 -msgid ":ref:`platform `" -msgstr ":ref:`platform `" - -#: ../../library/cmdline.rst:33 -msgid ":mod:`poplib`" -msgstr ":mod:`poplib`" - -#: ../../library/cmdline.rst:34 -msgid ":ref:`profile `" -msgstr ":ref:`profile `" - -#: ../../library/cmdline.rst:35 -msgid ":mod:`pstats`" -msgstr ":mod:`pstats`" - -#: ../../library/cmdline.rst:36 -msgid ":ref:`py_compile `" -msgstr ":ref:`py_compile `" - -#: ../../library/cmdline.rst:37 -msgid ":mod:`pyclbr`" -msgstr ":mod:`pyclbr`" - -#: ../../library/cmdline.rst:38 -msgid ":mod:`pydoc`" -msgstr ":mod:`pydoc`" - -#: ../../library/cmdline.rst:39 -msgid ":mod:`quopri`" -msgstr ":mod:`quopri`" - -#: ../../library/cmdline.rst:40 -msgid ":ref:`random `" -msgstr ":ref:`random `" - -#: ../../library/cmdline.rst:41 -msgid ":mod:`runpy`" -msgstr ":mod:`runpy`" - -#: ../../library/cmdline.rst:42 -msgid ":ref:`site `" -msgstr ":ref:`site `" - -#: ../../library/cmdline.rst:43 -msgid ":ref:`sqlite3 `" -msgstr ":ref:`sqlite3 `" - -#: ../../library/cmdline.rst:44 -msgid ":ref:`symtable `" -msgstr ":ref:`symtable `" - -#: ../../library/cmdline.rst:45 -msgid ":ref:`sysconfig `" -msgstr ":ref:`sysconfig `" - -#: ../../library/cmdline.rst:46 -msgid ":mod:`tabnanny`" -msgstr ":mod:`tabnanny`" - -#: ../../library/cmdline.rst:47 -msgid ":ref:`tarfile `" -msgstr ":ref:`tarfile `" - -#: ../../library/cmdline.rst:48 -msgid ":mod:`!this`" -msgstr ":mod:`!this`" - -#: ../../library/cmdline.rst:49 -msgid ":ref:`timeit `" -msgstr ":ref:`timeit `" - -#: ../../library/cmdline.rst:50 -msgid ":ref:`tokenize `" -msgstr ":ref:`tokenize `" - -#: ../../library/cmdline.rst:51 -msgid ":ref:`trace `" -msgstr ":ref:`trace `" - -#: ../../library/cmdline.rst:52 -msgid ":mod:`turtledemo`" -msgstr ":mod:`turtledemo`" - -#: ../../library/cmdline.rst:53 -msgid ":ref:`unittest `" -msgstr ":ref:`unittest `" - -#: ../../library/cmdline.rst:54 -msgid ":ref:`uuid `" -msgstr ":ref:`uuid `" - -#: ../../library/cmdline.rst:55 -msgid ":ref:`venv `" -msgstr ":ref:`venv `" - -#: ../../library/cmdline.rst:56 -msgid ":ref:`webbrowser `" -msgstr ":ref:`webbrowser `" - -#: ../../library/cmdline.rst:57 -msgid ":ref:`zipapp `" -msgstr ":ref:`zipapp `" - -#: ../../library/cmdline.rst:58 -msgid ":ref:`zipfile `" -msgstr ":ref:`zipfile `" - -#: ../../library/cmdline.rst:60 -msgid "See also the :ref:`Python command-line interface `." -msgstr "另請見 :ref:`Python 命令列介面 `。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Matt Wang , 2023 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-18 00:15+0000\n" +"PO-Revision-Date: 2023-10-14 16:03+0800\n" +"Last-Translator: Matt Wang \n" +"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" +"tw)\n" +"Language: zh_TW\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../library/cmdline.rst:5 +msgid "Modules command-line interface (CLI)" +msgstr "模組命令列介面" + +#: ../../library/cmdline.rst:7 +msgid "The following modules have a command-line interface." +msgstr "以下模組具有命令列介面。" + +#: ../../library/cmdline.rst:9 +msgid ":ref:`ast `" +msgstr ":ref:`ast `" + +#: ../../library/cmdline.rst:10 +msgid ":ref:`asyncio `" +msgstr ":ref:`asyncio `" + +#: ../../library/cmdline.rst:11 +msgid ":mod:`base64`" +msgstr ":mod:`base64`" + +#: ../../library/cmdline.rst:12 +msgid ":ref:`calendar `" +msgstr ":ref:`calendar `" + +#: ../../library/cmdline.rst:13 +msgid ":mod:`code`" +msgstr ":mod:`code`" + +#: ../../library/cmdline.rst:14 +msgid ":ref:`compileall `" +msgstr ":ref:`compileall `" + +#: ../../library/cmdline.rst:15 +msgid ":mod:`cProfile`: see :ref:`profile `" +msgstr ":mod:`cProfile`: 請見 :ref:`profile `" + +#: ../../library/cmdline.rst:16 +msgid ":ref:`dis `" +msgstr ":ref:`dis `" + +#: ../../library/cmdline.rst:17 +msgid ":ref:`doctest `" +msgstr ":ref:`doctest `" + +#: ../../library/cmdline.rst:18 +msgid ":mod:`!encodings.rot_13`" +msgstr ":mod:`!encodings.rot_13`" + +#: ../../library/cmdline.rst:19 +msgid ":ref:`ensurepip `" +msgstr ":ref:`ensurepip `" + +#: ../../library/cmdline.rst:20 +msgid ":mod:`filecmp`" +msgstr ":mod:`filecmp`" + +#: ../../library/cmdline.rst:21 +msgid ":mod:`fileinput`" +msgstr ":mod:`fileinput`" + +#: ../../library/cmdline.rst:22 +msgid ":mod:`ftplib`" +msgstr ":mod:`ftplib`" + +#: ../../library/cmdline.rst:23 +msgid ":ref:`gzip `" +msgstr ":ref:`gzip `" + +#: ../../library/cmdline.rst:24 +msgid ":ref:`http.server `" +msgstr ":ref:`http.server `" + +#: ../../library/cmdline.rst:25 +msgid ":ref:`idlelib `" +msgstr ":ref:`idlelib `" + +#: ../../library/cmdline.rst:26 +msgid ":ref:`inspect `" +msgstr ":ref:`inspect `" + +#: ../../library/cmdline.rst:27 +msgid ":ref:`json `" +msgstr ":ref:`json `" + +#: ../../library/cmdline.rst:28 +msgid ":ref:`mimetypes `" +msgstr ":ref:`mimetypes `" + +#: ../../library/cmdline.rst:29 +msgid ":ref:`pdb `" +msgstr ":ref:`pdb `" + +#: ../../library/cmdline.rst:30 +msgid ":ref:`pickle `" +msgstr ":ref:`pickle `" + +#: ../../library/cmdline.rst:31 +msgid ":ref:`pickletools `" +msgstr ":ref:`pickletools `" + +#: ../../library/cmdline.rst:32 +msgid ":ref:`platform `" +msgstr ":ref:`platform `" + +#: ../../library/cmdline.rst:33 +msgid ":mod:`poplib`" +msgstr ":mod:`poplib`" + +#: ../../library/cmdline.rst:34 +msgid ":ref:`profile `" +msgstr ":ref:`profile `" + +#: ../../library/cmdline.rst:35 +msgid ":mod:`pstats`" +msgstr ":mod:`pstats`" + +#: ../../library/cmdline.rst:36 +msgid ":ref:`py_compile `" +msgstr ":ref:`py_compile `" + +#: ../../library/cmdline.rst:37 +msgid ":mod:`pyclbr`" +msgstr ":mod:`pyclbr`" + +#: ../../library/cmdline.rst:38 +msgid ":mod:`pydoc`" +msgstr ":mod:`pydoc`" + +#: ../../library/cmdline.rst:39 +msgid ":mod:`quopri`" +msgstr ":mod:`quopri`" + +#: ../../library/cmdline.rst:40 +msgid ":ref:`random `" +msgstr ":ref:`random `" + +#: ../../library/cmdline.rst:41 +msgid ":mod:`runpy`" +msgstr ":mod:`runpy`" + +#: ../../library/cmdline.rst:42 +msgid ":ref:`site `" +msgstr ":ref:`site `" + +#: ../../library/cmdline.rst:43 +msgid ":ref:`sqlite3 `" +msgstr ":ref:`sqlite3 `" + +#: ../../library/cmdline.rst:44 +msgid ":ref:`symtable `" +msgstr ":ref:`symtable `" + +#: ../../library/cmdline.rst:45 +msgid ":ref:`sysconfig `" +msgstr ":ref:`sysconfig `" + +#: ../../library/cmdline.rst:46 +msgid ":mod:`tabnanny`" +msgstr ":mod:`tabnanny`" + +#: ../../library/cmdline.rst:47 +msgid ":ref:`tarfile `" +msgstr ":ref:`tarfile `" + +#: ../../library/cmdline.rst:48 +msgid ":mod:`!this`" +msgstr ":mod:`!this`" + +#: ../../library/cmdline.rst:49 +msgid ":ref:`timeit `" +msgstr ":ref:`timeit `" + +#: ../../library/cmdline.rst:50 +msgid ":ref:`tokenize `" +msgstr ":ref:`tokenize `" + +#: ../../library/cmdline.rst:51 +msgid ":ref:`trace `" +msgstr ":ref:`trace `" + +#: ../../library/cmdline.rst:52 +msgid ":mod:`turtledemo`" +msgstr ":mod:`turtledemo`" + +#: ../../library/cmdline.rst:53 +msgid ":ref:`unittest `" +msgstr ":ref:`unittest `" + +#: ../../library/cmdline.rst:54 +msgid ":ref:`uuid `" +msgstr ":ref:`uuid `" + +#: ../../library/cmdline.rst:55 +msgid ":ref:`venv `" +msgstr ":ref:`venv `" + +#: ../../library/cmdline.rst:56 +msgid ":ref:`webbrowser `" +msgstr ":ref:`webbrowser `" + +#: ../../library/cmdline.rst:57 +msgid ":ref:`zipapp `" +msgstr ":ref:`zipapp `" + +#: ../../library/cmdline.rst:58 +msgid ":ref:`zipfile `" +msgstr ":ref:`zipfile `" + +#: ../../library/cmdline.rst:60 +msgid "See also the :ref:`Python command-line interface `." +msgstr "另請見 :ref:`Python 命令列介面 `。" diff --git a/library/cmdlinelibs.po b/library/cmdlinelibs.po index ffd411006f..23bbc6d855 100644 --- a/library/cmdlinelibs.po +++ b/library/cmdlinelibs.po @@ -1,32 +1,32 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# FIRST AUTHOR , YEAR. -# -#, fuzzy -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-08-16 00:16+0000\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" -"tw)\n" -"Language: zh_TW\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=UTF-8\n" -"Content-Transfer-Encoding: 8bit\n" - -#: ../../library/cmdlinelibs.rst:5 -msgid "Command-line interface libraries" -msgstr "命令列介面函式庫" - -#: ../../library/cmdlinelibs.rst:7 -msgid "" -"The modules described in this chapter assist with implementing command line " -"and terminal interfaces for applications." -msgstr "本章節所描述的模組協助實作應用程式的命令列與終端介面。" - -#: ../../library/cmdlinelibs.rst:10 -msgid "Here's an overview:" -msgstr "以下為概覽：" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-08-16 00:16+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" +"tw)\n" +"Language: zh_TW\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../library/cmdlinelibs.rst:5 +msgid "Command-line interface libraries" +msgstr "命令列介面函式庫" + +#: ../../library/cmdlinelibs.rst:7 +msgid "" +"The modules described in this chapter assist with implementing command line " +"and terminal interfaces for applications." +msgstr "本章節所描述的模組協助實作應用程式的命令列與終端介面。" + +#: ../../library/cmdlinelibs.rst:10 +msgid "Here's an overview:" +msgstr "以下為概覽：" diff --git a/library/code.po b/library/code.po index ab57c96d38..1b8f73c8dd 100644 --- a/library/code.po +++ b/library/code.po @@ -1,324 +1,324 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Matt Wang , 2025 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: 2025-07-13 14:40+0000\n" -"Last-Translator: Matt Wang \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/code.rst:2 -msgid ":mod:`!code` --- Interpreter base classes" -msgstr ":mod:`!code` --- 直譯器基底類別" - -#: ../../library/code.rst:7 -msgid "**Source code:** :source:`Lib/code.py`" -msgstr "**原始碼：**\\ :source:`Lib/code.py`" - -#: ../../library/code.rst:11 -msgid "" -"The ``code`` module provides facilities to implement read-eval-print loops " -"in Python. Two classes and convenience functions are included which can be " -"used to build applications which provide an interactive interpreter prompt." -msgstr "" -"``code`` 模組提供在 Python 中實作讀取-求值-印出迴圈（read-eval-print loops）" -"的設施。包含兩個類別和便利函式，可用於建立提供互動式直譯器提示的應用程式。" - -#: ../../library/code.rst:18 -msgid "" -"This class deals with parsing and interpreter state (the user's namespace); " -"it does not deal with input buffering or prompting or input file naming (the " -"filename is always passed in explicitly). The optional *locals* argument " -"specifies a mapping to use as the namespace in which code will be executed; " -"it defaults to a newly created dictionary with key ``'__name__'`` set to " -"``'__console__'`` and key ``'__doc__'`` set to ``None``." -msgstr "" -"這個類別處理剖析和直譯器狀態（使用者的命名空間）；它不處理輸入緩衝、提示或輸" -"入檔案命名（檔案名稱總是明確傳入）。可選的 *locals* 引數指定一個對映，作為執" -"行程式碼的命名空間；它預設為新建立的字典，鍵 ``'__name__'`` 設為 " -"``'__console__'`` 而鍵 ``'__doc__'`` 會設為 ``None``。" - -#: ../../library/code.rst:25 -msgid "" -"Note that functions and classes objects created under an :class:`!" -"InteractiveInterpreter` instance will belong to the namespace specified by " -"*locals*. They are only pickleable if *locals* is the namespace of an " -"existing module." -msgstr "" -"請注意，在 :class:`!InteractiveInterpreter` 實例下建立的函式和類別物件將屬於" -"由 *locals* 指定的命名空間。只有當 *locals* 是現有模組的命名空間時，它們才會" -"是可被 pickle 的。" - -#: ../../library/code.rst:34 -msgid "" -"Closely emulate the behavior of the interactive Python interpreter. This " -"class builds on :class:`InteractiveInterpreter` and adds prompting using the " -"familiar ``sys.ps1`` and ``sys.ps2``, and input buffering. If *local_exit* " -"is true, ``exit()`` and ``quit()`` in the console will not " -"raise :exc:`SystemExit`, but instead return to the calling code." -msgstr "" -"近似地模擬出互動式 Python 直譯器的行為。這個類別建立" -"在 :class:`InteractiveInterpreter` 的基礎上，並加入使用熟悉的 ``sys.ps1`` 和 " -"``sys.ps2`` 的提示，以及輸入緩衝。如果 *local_exit* 為 true，控制台中的 " -"``exit()`` 和 ``quit()`` 將不會引發 :exc:`SystemExit`，而是回傳到呼叫程式碼。" - -#: ../../library/code.rst:40 ../../library/code.rst:58 -msgid "Added *local_exit* parameter." -msgstr "新增 *local_exit* 參數。" - -#: ../../library/code.rst:45 -msgid "" -"Convenience function to run a read-eval-print loop. This creates a new " -"instance of :class:`InteractiveConsole` and sets *readfunc* to be used as " -"the :meth:`InteractiveConsole.raw_input` method, if provided. If *local* is " -"provided, it is passed to the :class:`InteractiveConsole` constructor for " -"use as the default namespace for the interpreter loop. If *local_exit* is " -"provided, it is passed to the :class:`InteractiveConsole` constructor. " -"The :meth:`~InteractiveConsole.interact` method of the instance is then run " -"with *banner* and *exitmsg* passed as the banner and exit message to use, if " -"provided. The console object is discarded after use." -msgstr "" -"執行 read-eval-print 迴圈的便利函式。這會建立一" -"個 :class:`InteractiveConsole` 的新實例，並設定 *readfunc* 以用" -"於 :meth:`InteractiveConsole.raw_input` 方法（如有提供）。如果 *local* 有被提" -"供，它會被傳給 :class:`InteractiveConsole` 的建構函式以作為直譯器迴圈的預設命" -"名空間。如果有提供 *local_exit*，它會被傳給 :class:`InteractiveConsole` 構建" -"函式。然後實例的 :meth:`~InteractiveConsole.interact` 方法會執行，並傳入 " -"*banner* 和 *exitmsg* 以作為要使用的橫幅和退出訊息（如有提供）。控制台物件在" -"使用後就會被丟棄。" - -#: ../../library/code.rst:55 -msgid "Added *exitmsg* parameter." -msgstr "新增 *exitmsg* 參數。" - -#: ../../library/code.rst:63 -msgid "" -"This function is useful for programs that want to emulate Python's " -"interpreter main loop (a.k.a. the read-eval-print loop). The tricky part is " -"to determine when the user has entered an incomplete command that can be " -"completed by entering more text (as opposed to a complete command or a " -"syntax error). This function *almost* always makes the same decision as the " -"real interpreter main loop." -msgstr "" -"這個函式對於想要模擬 Python 的直譯器主迴圈（即讀取-求值-印出迴圈）的程式很有" -"用。最棘手的部分是判斷使用者何時輸入了一個不完整的命令，而這個命令可以透過輸" -"入更多文字來完成（相對於完整的命令或語法錯誤）。這個函式\\ *幾乎*\\ 總是做出" -"與真正的直譯器主迴圈相同的判斷。" - -#: ../../library/code.rst:70 -msgid "" -"*source* is the source string; *filename* is the optional filename from " -"which source was read, defaulting to ``''``; and *symbol* is the " -"optional grammar start symbol, which should be ``'single'`` (the default), " -"``'eval'`` or ``'exec'``." -msgstr "" -"*source* 是來源字串；*filename* 是讀取來源的可選檔案名稱，預設為 " -"``''``；*symbol* 是可選的文法 (grammar) 起始符號，其應為 " -"``'single'``\\ （預設值）、``'eval'`` 或 ``'exec'``。" - -#: ../../library/code.rst:75 -msgid "" -"Returns a code object (the same as ``compile(source, filename, symbol)``) if " -"the command is complete and valid; ``None`` if the command is incomplete; " -"raises :exc:`SyntaxError` if the command is complete and contains a syntax " -"error, or raises :exc:`OverflowError` or :exc:`ValueError` if the command " -"contains an invalid literal." -msgstr "" -"如果命令完整且有效，則回傳程式碼物件（與 ``compile(source,filename,symbol)`` " -"相同）；如果命令不完整，則回傳 ``None``；如果命令完整但包含語法錯誤，則引" -"發 :exc:`SyntaxError`，如果命令包含無效的字面值 (literal)，則引" -"發 :exc:`OverflowError` 或 :exc:`ValueError`。" - -#: ../../library/code.rst:85 -msgid "Interactive Interpreter Objects" -msgstr "互動式直譯器物件" - -#: ../../library/code.rst:90 -msgid "" -"Compile and run some source in the interpreter. Arguments are the same as " -"for :func:`compile_command`; the default for *filename* is ``''``, " -"and for *symbol* is ``'single'``. One of several things can happen:" -msgstr "" -"在直譯器中編譯並執行某些原始碼。引數與 :func:`compile_command` 相同；" -"*filename* 的預設值是 ``''``，*symbol* 的預設值是 ``'single'``。有幾種" -"情況會發生：" - -#: ../../library/code.rst:94 -msgid "" -"The input is incorrect; :func:`compile_command` raised an exception " -"(:exc:`SyntaxError` or :exc:`OverflowError`). A syntax traceback will be " -"printed by calling the :meth:`showsyntaxerror` method. :meth:`runsource` " -"returns ``False``." -msgstr "" -"輸入不正確；:func:`compile_command` 會引發例外（:exc:`SyntaxError` " -"或 :exc:`OverflowError`）。語法回溯 (syntax traceback) 會透過呼" -"叫 :meth:`showsyntaxerror` 方法來印出。:meth:`runsource` 會回傳 ``False``。" - -#: ../../library/code.rst:99 -msgid "" -"The input is incomplete, and more input is required; :func:`compile_command` " -"returned ``None``. :meth:`runsource` returns ``True``." -msgstr "" -"輸入不完整，需要更多輸入；:func:`compile_command` 回傳了 " -"``None``。:meth:`runsource` 會回傳 ``True``。" - -#: ../../library/code.rst:102 -msgid "" -"The input is complete; :func:`compile_command` returned a code object. The " -"code is executed by calling the :meth:`runcode` (which also handles run-time " -"exceptions, except for :exc:`SystemExit`). :meth:`runsource` returns " -"``False``." -msgstr "" -"輸入完整；:func:`compile_command` 回傳一個程式碼物件。程式碼會透過呼" -"叫 :meth:`runcode` 執行（它也會處理執行時的例外，除 :exc:`SystemExit` 以" -"外）。:meth:`runsource` 會回傳 ``False``。" - -#: ../../library/code.rst:106 -msgid "" -"The return value can be used to decide whether to use ``sys.ps1`` or " -"``sys.ps2`` to prompt the next line." -msgstr "回傳值可用來決定是使用 ``sys.ps1`` 還是 ``sys.ps2`` 以提示下一列。" - -#: ../../library/code.rst:112 -msgid "" -"Execute a code object. When an exception occurs, :meth:`showtraceback` is " -"called to display a traceback. All exceptions are caught " -"except :exc:`SystemExit`, which is allowed to propagate." -msgstr "" -"執行程式碼物件。當例外發生時，會呼叫 :meth:`showtraceback` 來顯示回溯。除" -"了 :exc:`SystemExit` 允許繼續傳播之外，所有的例外都會被捕獲。" - -#: ../../library/code.rst:116 -msgid "" -"A note about :exc:`KeyboardInterrupt`: this exception may occur elsewhere in " -"this code, and may not always be caught. The caller should be prepared to " -"deal with it." -msgstr "" -"關於 :exc:`KeyboardInterrupt` 的注意事項：此例外可能發生在此程式碼的其他地" -"方，而且不一定會被捕獲到。呼叫者應該準備好處理它。" - -#: ../../library/code.rst:123 -msgid "" -"Display the syntax error that just occurred. This does not display a stack " -"trace because there isn't one for syntax errors. If *filename* is given, it " -"is stuffed into the exception instead of the default filename provided by " -"Python's parser, because it always uses ``''`` when reading from a " -"string. The output is written by the :meth:`write` method." -msgstr "" -"顯示剛剛發生的語法錯誤。這不會顯示堆疊追蹤 (stack trace)，因為語法錯誤沒有堆" -"疊追蹤。如果給出 *filename*，它會被塞入例外，而不是 Python 剖析器提供的預設檔" -"案名稱，因為它從字串讀取時總是使用 ``''``。輸出會由 :meth:`write` 方" -"法寫入。" - -#: ../../library/code.rst:132 -msgid "" -"Display the exception that just occurred. We remove the first stack item " -"because it is within the interpreter object implementation. The output is " -"written by the :meth:`write` method." -msgstr "" -"顯示剛剛發生的例外。我們移除第一個堆疊項目，因為它在直譯器物件的實作範圍內。" -"輸出由 :meth:`write` 方法寫入。" - -#: ../../library/code.rst:136 -msgid "" -"The full chained traceback is displayed instead of just the primary " -"traceback." -msgstr "會顯示完整的連鎖回溯記錄，而不只是主要回溯。" - -#: ../../library/code.rst:142 -msgid "" -"Write a string to the standard error stream (``sys.stderr``). Derived " -"classes should override this to provide the appropriate output handling as " -"needed." -msgstr "" -"寫入字串到標準錯誤串流 (``sys.stderr``)。衍生類別應覆寫此功能，以根據需求提供" -"適當的輸出處理。" - -#: ../../library/code.rst:149 -msgid "Interactive Console Objects" -msgstr "互動式控制台物件" - -#: ../../library/code.rst:151 -msgid "" -"The :class:`InteractiveConsole` class is a subclass " -"of :class:`InteractiveInterpreter`, and so offers all the methods of the " -"interpreter objects as well as the following additions." -msgstr "" -":class:`InteractiveConsole` 類別是 :class:`InteractiveInterpreter` 的子類別，" -"因此提供了所有直譯器物件的方法以及下列新增的功能。" - -#: ../../library/code.rst:158 -msgid "" -"Closely emulate the interactive Python console. The optional *banner* " -"argument specify the banner to print before the first interaction; by " -"default it prints a banner similar to the one printed by the standard Python " -"interpreter, followed by the class name of the console object in parentheses " -"(so as not to confuse this with the real interpreter -- since it's so " -"close!)." -msgstr "" -"近似地模擬互動式 Python 控制台。可選的 *banner* 引數指定在第一次互動之前要印" -"出的横幅；預設會印出類似標準 Python 直譯器所列印的横幅，接著是控制台物件在括" -"弧中的類別名稱 (以免與真正的直譯器混淆 -- 因為它是如此接近！)。" - -#: ../../library/code.rst:164 -msgid "" -"The optional *exitmsg* argument specifies an exit message printed when " -"exiting. Pass the empty string to suppress the exit message. If *exitmsg* is " -"not given or ``None``, a default message is printed." -msgstr "" -"可選的 *exitmsg* 引數指定退出時列印的退出訊息。傳遞空字串以抑制退出訊息。如果" -"沒有給 *exitmsg* 或 ``None``，則會印出預設訊息。" - -#: ../../library/code.rst:168 -msgid "To suppress printing any banner, pass an empty string." -msgstr "若要抑制印出任何橫幅，請傳入空字串。" - -#: ../../library/code.rst:171 -msgid "Print an exit message when exiting." -msgstr "退出時印出退出訊息。" - -#: ../../library/code.rst:177 -msgid "" -"Push a line of source text to the interpreter. The line should not have a " -"trailing newline; it may have internal newlines. The line is appended to a " -"buffer and the interpreter's :meth:`~InteractiveInterpreter.runsource` " -"method is called with the concatenated contents of the buffer as source. If " -"this indicates that the command was executed or invalid, the buffer is " -"reset; otherwise, the command is incomplete, and the buffer is left as it " -"was after the line was appended. The return value is ``True`` if more input " -"is required, ``False`` if the line was dealt with in some way (this is the " -"same as :meth:`!runsource`)." -msgstr "" -"推送一行原始文字到直譯器。這一行不應該有尾部換行符號；它可能有內部換行符號。" -"這行文字會被附加到緩衝區，並且直譯器" -"的 :meth:`~InteractiveInterpreter.runsource` 方法會被呼叫，並以緩衝區的串接內" -"容做為原始碼。如果這表示命令已執行或無效，緩衝區會被重設；否則，命令會不完" -"整，且緩衝區會保持該行被附加後的樣子。如果需要更多的輸入，回傳值是 ``True``，" -"如果該行已經以某種方式處理，回傳值是 ``False``\\ （這與 :meth:`!runsource` 相" -"同）。" - -#: ../../library/code.rst:189 -msgid "Remove any unhandled source text from the input buffer." -msgstr "從輸入緩衝區移除任何未處理的原始文字。" - -#: ../../library/code.rst:194 -msgid "" -"Write a prompt and read a line. The returned line does not include the " -"trailing newline. When the user enters the EOF key " -"sequence, :exc:`EOFError` is raised. The base implementation reads from " -"``sys.stdin``; a subclass may replace this with a different implementation." -msgstr "" -"寫入一個提示並讀取一行。回傳的行不包括尾部的換行符號。當使用者輸入 EOF 鍵序" -"時，會引發 :exc:`EOFError`。基底實作會從 ``sys.stdin`` 讀取；子類別可以用不同" -"的實作替代。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Matt Wang , 2025 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: 2025-07-13 14:40+0000\n" +"Last-Translator: Matt Wang \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/code.rst:2 +msgid ":mod:`!code` --- Interpreter base classes" +msgstr ":mod:`!code` --- 直譯器基底類別" + +#: ../../library/code.rst:7 +msgid "**Source code:** :source:`Lib/code.py`" +msgstr "**原始碼：**\\ :source:`Lib/code.py`" + +#: ../../library/code.rst:11 +msgid "" +"The ``code`` module provides facilities to implement read-eval-print loops " +"in Python. Two classes and convenience functions are included which can be " +"used to build applications which provide an interactive interpreter prompt." +msgstr "" +"``code`` 模組提供在 Python 中實作讀取-求值-印出迴圈（read-eval-print loops）" +"的設施。包含兩個類別和便利函式，可用於建立提供互動式直譯器提示的應用程式。" + +#: ../../library/code.rst:18 +msgid "" +"This class deals with parsing and interpreter state (the user's namespace); " +"it does not deal with input buffering or prompting or input file naming (the " +"filename is always passed in explicitly). The optional *locals* argument " +"specifies a mapping to use as the namespace in which code will be executed; " +"it defaults to a newly created dictionary with key ``'__name__'`` set to " +"``'__console__'`` and key ``'__doc__'`` set to ``None``." +msgstr "" +"這個類別處理剖析和直譯器狀態（使用者的命名空間）；它不處理輸入緩衝、提示或輸" +"入檔案命名（檔案名稱總是明確傳入）。可選的 *locals* 引數指定一個對映，作為執" +"行程式碼的命名空間；它預設為新建立的字典，鍵 ``'__name__'`` 設為 " +"``'__console__'`` 而鍵 ``'__doc__'`` 會設為 ``None``。" + +#: ../../library/code.rst:25 +msgid "" +"Note that functions and classes objects created under an :class:`!" +"InteractiveInterpreter` instance will belong to the namespace specified by " +"*locals*. They are only pickleable if *locals* is the namespace of an " +"existing module." +msgstr "" +"請注意，在 :class:`!InteractiveInterpreter` 實例下建立的函式和類別物件將屬於" +"由 *locals* 指定的命名空間。只有當 *locals* 是現有模組的命名空間時，它們才會" +"是可被 pickle 的。" + +#: ../../library/code.rst:34 +msgid "" +"Closely emulate the behavior of the interactive Python interpreter. This " +"class builds on :class:`InteractiveInterpreter` and adds prompting using the " +"familiar ``sys.ps1`` and ``sys.ps2``, and input buffering. If *local_exit* " +"is true, ``exit()`` and ``quit()`` in the console will not " +"raise :exc:`SystemExit`, but instead return to the calling code." +msgstr "" +"近似地模擬出互動式 Python 直譯器的行為。這個類別建立" +"在 :class:`InteractiveInterpreter` 的基礎上，並加入使用熟悉的 ``sys.ps1`` 和 " +"``sys.ps2`` 的提示，以及輸入緩衝。如果 *local_exit* 為 true，控制台中的 " +"``exit()`` 和 ``quit()`` 將不會引發 :exc:`SystemExit`，而是回傳到呼叫程式碼。" + +#: ../../library/code.rst:40 ../../library/code.rst:58 +msgid "Added *local_exit* parameter." +msgstr "新增 *local_exit* 參數。" + +#: ../../library/code.rst:45 +msgid "" +"Convenience function to run a read-eval-print loop. This creates a new " +"instance of :class:`InteractiveConsole` and sets *readfunc* to be used as " +"the :meth:`InteractiveConsole.raw_input` method, if provided. If *local* is " +"provided, it is passed to the :class:`InteractiveConsole` constructor for " +"use as the default namespace for the interpreter loop. If *local_exit* is " +"provided, it is passed to the :class:`InteractiveConsole` constructor. " +"The :meth:`~InteractiveConsole.interact` method of the instance is then run " +"with *banner* and *exitmsg* passed as the banner and exit message to use, if " +"provided. The console object is discarded after use." +msgstr "" +"執行 read-eval-print 迴圈的便利函式。這會建立一" +"個 :class:`InteractiveConsole` 的新實例，並設定 *readfunc* 以用" +"於 :meth:`InteractiveConsole.raw_input` 方法（如有提供）。如果 *local* 有被提" +"供，它會被傳給 :class:`InteractiveConsole` 的建構函式以作為直譯器迴圈的預設命" +"名空間。如果有提供 *local_exit*，它會被傳給 :class:`InteractiveConsole` 構建" +"函式。然後實例的 :meth:`~InteractiveConsole.interact` 方法會執行，並傳入 " +"*banner* 和 *exitmsg* 以作為要使用的橫幅和退出訊息（如有提供）。控制台物件在" +"使用後就會被丟棄。" + +#: ../../library/code.rst:55 +msgid "Added *exitmsg* parameter." +msgstr "新增 *exitmsg* 參數。" + +#: ../../library/code.rst:63 +msgid "" +"This function is useful for programs that want to emulate Python's " +"interpreter main loop (a.k.a. the read-eval-print loop). The tricky part is " +"to determine when the user has entered an incomplete command that can be " +"completed by entering more text (as opposed to a complete command or a " +"syntax error). This function *almost* always makes the same decision as the " +"real interpreter main loop." +msgstr "" +"這個函式對於想要模擬 Python 的直譯器主迴圈（即讀取-求值-印出迴圈）的程式很有" +"用。最棘手的部分是判斷使用者何時輸入了一個不完整的命令，而這個命令可以透過輸" +"入更多文字來完成（相對於完整的命令或語法錯誤）。這個函式\\ *幾乎*\\ 總是做出" +"與真正的直譯器主迴圈相同的判斷。" + +#: ../../library/code.rst:70 +msgid "" +"*source* is the source string; *filename* is the optional filename from " +"which source was read, defaulting to ``''``; and *symbol* is the " +"optional grammar start symbol, which should be ``'single'`` (the default), " +"``'eval'`` or ``'exec'``." +msgstr "" +"*source* 是來源字串；*filename* 是讀取來源的可選檔案名稱，預設為 " +"``''``；*symbol* 是可選的文法 (grammar) 起始符號，其應為 " +"``'single'``\\ （預設值）、``'eval'`` 或 ``'exec'``。" + +#: ../../library/code.rst:75 +msgid "" +"Returns a code object (the same as ``compile(source, filename, symbol)``) if " +"the command is complete and valid; ``None`` if the command is incomplete; " +"raises :exc:`SyntaxError` if the command is complete and contains a syntax " +"error, or raises :exc:`OverflowError` or :exc:`ValueError` if the command " +"contains an invalid literal." +msgstr "" +"如果命令完整且有效，則回傳程式碼物件（與 ``compile(source,filename,symbol)`` " +"相同）；如果命令不完整，則回傳 ``None``；如果命令完整但包含語法錯誤，則引" +"發 :exc:`SyntaxError`，如果命令包含無效的字面值 (literal)，則引" +"發 :exc:`OverflowError` 或 :exc:`ValueError`。" + +#: ../../library/code.rst:85 +msgid "Interactive Interpreter Objects" +msgstr "互動式直譯器物件" + +#: ../../library/code.rst:90 +msgid "" +"Compile and run some source in the interpreter. Arguments are the same as " +"for :func:`compile_command`; the default for *filename* is ``''``, " +"and for *symbol* is ``'single'``. One of several things can happen:" +msgstr "" +"在直譯器中編譯並執行某些原始碼。引數與 :func:`compile_command` 相同；" +"*filename* 的預設值是 ``''``，*symbol* 的預設值是 ``'single'``。有幾種" +"情況會發生：" + +#: ../../library/code.rst:94 +msgid "" +"The input is incorrect; :func:`compile_command` raised an exception " +"(:exc:`SyntaxError` or :exc:`OverflowError`). A syntax traceback will be " +"printed by calling the :meth:`showsyntaxerror` method. :meth:`runsource` " +"returns ``False``." +msgstr "" +"輸入不正確；:func:`compile_command` 會引發例外（:exc:`SyntaxError` " +"或 :exc:`OverflowError`）。語法回溯 (syntax traceback) 會透過呼" +"叫 :meth:`showsyntaxerror` 方法來印出。:meth:`runsource` 會回傳 ``False``。" + +#: ../../library/code.rst:99 +msgid "" +"The input is incomplete, and more input is required; :func:`compile_command` " +"returned ``None``. :meth:`runsource` returns ``True``." +msgstr "" +"輸入不完整，需要更多輸入；:func:`compile_command` 回傳了 " +"``None``。:meth:`runsource` 會回傳 ``True``。" + +#: ../../library/code.rst:102 +msgid "" +"The input is complete; :func:`compile_command` returned a code object. The " +"code is executed by calling the :meth:`runcode` (which also handles run-time " +"exceptions, except for :exc:`SystemExit`). :meth:`runsource` returns " +"``False``." +msgstr "" +"輸入完整；:func:`compile_command` 回傳一個程式碼物件。程式碼會透過呼" +"叫 :meth:`runcode` 執行（它也會處理執行時的例外，除 :exc:`SystemExit` 以" +"外）。:meth:`runsource` 會回傳 ``False``。" + +#: ../../library/code.rst:106 +msgid "" +"The return value can be used to decide whether to use ``sys.ps1`` or " +"``sys.ps2`` to prompt the next line." +msgstr "回傳值可用來決定是使用 ``sys.ps1`` 還是 ``sys.ps2`` 以提示下一列。" + +#: ../../library/code.rst:112 +msgid "" +"Execute a code object. When an exception occurs, :meth:`showtraceback` is " +"called to display a traceback. All exceptions are caught " +"except :exc:`SystemExit`, which is allowed to propagate." +msgstr "" +"執行程式碼物件。當例外發生時，會呼叫 :meth:`showtraceback` 來顯示回溯。除" +"了 :exc:`SystemExit` 允許繼續傳播之外，所有的例外都會被捕獲。" + +#: ../../library/code.rst:116 +msgid "" +"A note about :exc:`KeyboardInterrupt`: this exception may occur elsewhere in " +"this code, and may not always be caught. The caller should be prepared to " +"deal with it." +msgstr "" +"關於 :exc:`KeyboardInterrupt` 的注意事項：此例外可能發生在此程式碼的其他地" +"方，而且不一定會被捕獲到。呼叫者應該準備好處理它。" + +#: ../../library/code.rst:123 +msgid "" +"Display the syntax error that just occurred. This does not display a stack " +"trace because there isn't one for syntax errors. If *filename* is given, it " +"is stuffed into the exception instead of the default filename provided by " +"Python's parser, because it always uses ``''`` when reading from a " +"string. The output is written by the :meth:`write` method." +msgstr "" +"顯示剛剛發生的語法錯誤。這不會顯示堆疊追蹤 (stack trace)，因為語法錯誤沒有堆" +"疊追蹤。如果給出 *filename*，它會被塞入例外，而不是 Python 剖析器提供的預設檔" +"案名稱，因為它從字串讀取時總是使用 ``''``。輸出會由 :meth:`write` 方" +"法寫入。" + +#: ../../library/code.rst:132 +msgid "" +"Display the exception that just occurred. We remove the first stack item " +"because it is within the interpreter object implementation. The output is " +"written by the :meth:`write` method." +msgstr "" +"顯示剛剛發生的例外。我們移除第一個堆疊項目，因為它在直譯器物件的實作範圍內。" +"輸出由 :meth:`write` 方法寫入。" + +#: ../../library/code.rst:136 +msgid "" +"The full chained traceback is displayed instead of just the primary " +"traceback." +msgstr "會顯示完整的連鎖回溯記錄，而不只是主要回溯。" + +#: ../../library/code.rst:142 +msgid "" +"Write a string to the standard error stream (``sys.stderr``). Derived " +"classes should override this to provide the appropriate output handling as " +"needed." +msgstr "" +"寫入字串到標準錯誤串流 (``sys.stderr``)。衍生類別應覆寫此功能，以根據需求提供" +"適當的輸出處理。" + +#: ../../library/code.rst:149 +msgid "Interactive Console Objects" +msgstr "互動式控制台物件" + +#: ../../library/code.rst:151 +msgid "" +"The :class:`InteractiveConsole` class is a subclass " +"of :class:`InteractiveInterpreter`, and so offers all the methods of the " +"interpreter objects as well as the following additions." +msgstr "" +":class:`InteractiveConsole` 類別是 :class:`InteractiveInterpreter` 的子類別，" +"因此提供了所有直譯器物件的方法以及下列新增的功能。" + +#: ../../library/code.rst:158 +msgid "" +"Closely emulate the interactive Python console. The optional *banner* " +"argument specify the banner to print before the first interaction; by " +"default it prints a banner similar to the one printed by the standard Python " +"interpreter, followed by the class name of the console object in parentheses " +"(so as not to confuse this with the real interpreter -- since it's so " +"close!)." +msgstr "" +"近似地模擬互動式 Python 控制台。可選的 *banner* 引數指定在第一次互動之前要印" +"出的横幅；預設會印出類似標準 Python 直譯器所列印的横幅，接著是控制台物件在括" +"弧中的類別名稱 (以免與真正的直譯器混淆 -- 因為它是如此接近！)。" + +#: ../../library/code.rst:164 +msgid "" +"The optional *exitmsg* argument specifies an exit message printed when " +"exiting. Pass the empty string to suppress the exit message. If *exitmsg* is " +"not given or ``None``, a default message is printed." +msgstr "" +"可選的 *exitmsg* 引數指定退出時列印的退出訊息。傳遞空字串以抑制退出訊息。如果" +"沒有給 *exitmsg* 或 ``None``，則會印出預設訊息。" + +#: ../../library/code.rst:168 +msgid "To suppress printing any banner, pass an empty string." +msgstr "若要抑制印出任何橫幅，請傳入空字串。" + +#: ../../library/code.rst:171 +msgid "Print an exit message when exiting." +msgstr "退出時印出退出訊息。" + +#: ../../library/code.rst:177 +msgid "" +"Push a line of source text to the interpreter. The line should not have a " +"trailing newline; it may have internal newlines. The line is appended to a " +"buffer and the interpreter's :meth:`~InteractiveInterpreter.runsource` " +"method is called with the concatenated contents of the buffer as source. If " +"this indicates that the command was executed or invalid, the buffer is " +"reset; otherwise, the command is incomplete, and the buffer is left as it " +"was after the line was appended. The return value is ``True`` if more input " +"is required, ``False`` if the line was dealt with in some way (this is the " +"same as :meth:`!runsource`)." +msgstr "" +"推送一行原始文字到直譯器。這一行不應該有尾部換行符號；它可能有內部換行符號。" +"這行文字會被附加到緩衝區，並且直譯器" +"的 :meth:`~InteractiveInterpreter.runsource` 方法會被呼叫，並以緩衝區的串接內" +"容做為原始碼。如果這表示命令已執行或無效，緩衝區會被重設；否則，命令會不完" +"整，且緩衝區會保持該行被附加後的樣子。如果需要更多的輸入，回傳值是 ``True``，" +"如果該行已經以某種方式處理，回傳值是 ``False``\\ （這與 :meth:`!runsource` 相" +"同）。" + +#: ../../library/code.rst:189 +msgid "Remove any unhandled source text from the input buffer." +msgstr "從輸入緩衝區移除任何未處理的原始文字。" + +#: ../../library/code.rst:194 +msgid "" +"Write a prompt and read a line. The returned line does not include the " +"trailing newline. When the user enters the EOF key " +"sequence, :exc:`EOFError` is raised. The base implementation reads from " +"``sys.stdin``; a subclass may replace this with a different implementation." +msgstr "" +"寫入一個提示並讀取一行。回傳的行不包括尾部的換行符號。當使用者輸入 EOF 鍵序" +"時，會引發 :exc:`EOFError`。基底實作會從 ``sys.stdin`` 讀取；子類別可以用不同" +"的實作替代。" diff --git a/library/codecs.po b/library/codecs.po index f1d8d60966..b41bbb2d6e 100644 --- a/library/codecs.po +++ b/library/codecs.po @@ -1,2940 +1,2940 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-12-01 00:17+0000\n" -"PO-Revision-Date: 2018-05-23 14:40+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/codecs.rst:2 -msgid ":mod:`!codecs` --- Codec registry and base classes" -msgstr ":mod:`!codecs` --- 編解碼器註冊表和基底類別" - -#: ../../library/codecs.rst:11 -msgid "**Source code:** :source:`Lib/codecs.py`" -msgstr "**原始碼：**\\ :source:`Lib/codecs.py`" - -#: ../../library/codecs.rst:23 -msgid "" -"This module defines base classes for standard Python codecs (encoders and " -"decoders) and provides access to the internal Python codec registry, which " -"manages the codec and error handling lookup process. Most standard codecs " -"are :term:`text encodings `, which encode text to bytes (and " -"decode bytes to text), but there are also codecs provided that encode text " -"to text, and bytes to bytes. Custom codecs may encode and decode between " -"arbitrary types, but some module features are restricted to be used " -"specifically with :term:`text encodings ` or with codecs that " -"encode to :class:`bytes`." -msgstr "" - -#: ../../library/codecs.rst:33 -msgid "" -"The module defines the following functions for encoding and decoding with " -"any codec:" -msgstr "這個模組定義了以下函式，用於以任何編解碼器來編碼與解碼：" - -#: ../../library/codecs.rst:38 -msgid "Encodes *obj* using the codec registered for *encoding*." -msgstr "" - -#: ../../library/codecs.rst:40 -msgid "" -"*Errors* may be given to set the desired error handling scheme. The default " -"error handler is ``'strict'`` meaning that encoding errors raise :exc:" -"`ValueError` (or a more codec specific subclass, such as :exc:" -"`UnicodeEncodeError`). Refer to :ref:`codec-base-classes` for more " -"information on codec error handling." -msgstr "" - -#: ../../library/codecs.rst:48 -msgid "Decodes *obj* using the codec registered for *encoding*." -msgstr "" - -#: ../../library/codecs.rst:50 -msgid "" -"*Errors* may be given to set the desired error handling scheme. The default " -"error handler is ``'strict'`` meaning that decoding errors raise :exc:" -"`ValueError` (or a more codec specific subclass, such as :exc:" -"`UnicodeDecodeError`). Refer to :ref:`codec-base-classes` for more " -"information on codec error handling." -msgstr "" - -#: ../../library/codecs.rst:58 -msgid "" -"Return a mapping suitable for encoding with a custom single-byte encoding. " -"Given a :class:`str` *string* of up to 256 characters representing a " -"decoding table, returns either a compact internal mapping object " -"``EncodingMap`` or a :class:`dictionary ` mapping character ordinals " -"to byte values. Raises a :exc:`TypeError` on invalid input." -msgstr "" - -#: ../../library/codecs.rst:64 -msgid "The full details for each codec can also be looked up directly:" -msgstr "" - -#: ../../library/codecs.rst:68 -msgid "" -"Looks up the codec info in the Python codec registry and returns a :class:" -"`CodecInfo` object as defined below." -msgstr "" - -#: ../../library/codecs.rst:71 -msgid "" -"Encodings are first looked up in the registry's cache. If not found, the " -"list of registered search functions is scanned. If no :class:`CodecInfo` " -"object is found, a :exc:`LookupError` is raised. Otherwise, the :class:" -"`CodecInfo` object is stored in the cache and returned to the caller." -msgstr "" - -#: ../../library/codecs.rst:78 -msgid "" -"Codec details when looking up the codec registry. The constructor arguments " -"are stored in attributes of the same name:" -msgstr "" - -#: ../../library/codecs.rst:84 -msgid "The name of the encoding." -msgstr "編碼的名稱。" - -#: ../../library/codecs.rst:90 -msgid "" -"The stateless encoding and decoding functions. These must be functions or " -"methods which have the same interface as the :meth:`~Codec.encode` and :meth:" -"`~Codec.decode` methods of Codec instances (see :ref:`Codec Interface `). The functions or methods are expected to work in a stateless " -"mode." -msgstr "" - -#: ../../library/codecs.rst:100 -msgid "" -"Incremental encoder and decoder classes or factory functions. These have to " -"provide the interface defined by the base classes :class:" -"`IncrementalEncoder` and :class:`IncrementalDecoder`, respectively. " -"Incremental codecs can maintain state." -msgstr "" - -#: ../../library/codecs.rst:109 -msgid "" -"Stream writer and reader classes or factory functions. These have to provide " -"the interface defined by the base classes :class:`StreamWriter` and :class:" -"`StreamReader`, respectively. Stream codecs can maintain state." -msgstr "" - -#: ../../library/codecs.rst:114 -msgid "" -"To simplify access to the various codec components, the module provides " -"these additional functions which use :func:`lookup` for the codec lookup:" -msgstr "" - -#: ../../library/codecs.rst:119 -msgid "" -"Look up the codec for the given encoding and return its encoder function." -msgstr "" - -#: ../../library/codecs.rst:121 ../../library/codecs.rst:128 -#: ../../library/codecs.rst:154 ../../library/codecs.rst:162 -msgid "Raises a :exc:`LookupError` in case the encoding cannot be found." -msgstr "" - -#: ../../library/codecs.rst:126 -msgid "" -"Look up the codec for the given encoding and return its decoder function." -msgstr "" - -#: ../../library/codecs.rst:133 -msgid "" -"Look up the codec for the given encoding and return its incremental encoder " -"class or factory function." -msgstr "" - -#: ../../library/codecs.rst:136 -msgid "" -"Raises a :exc:`LookupError` in case the encoding cannot be found or the " -"codec doesn't support an incremental encoder." -msgstr "" - -#: ../../library/codecs.rst:142 -msgid "" -"Look up the codec for the given encoding and return its incremental decoder " -"class or factory function." -msgstr "" - -#: ../../library/codecs.rst:145 -msgid "" -"Raises a :exc:`LookupError` in case the encoding cannot be found or the " -"codec doesn't support an incremental decoder." -msgstr "" - -#: ../../library/codecs.rst:151 -msgid "" -"Look up the codec for the given encoding and return its :class:" -"`StreamReader` class or factory function." -msgstr "" - -#: ../../library/codecs.rst:159 -msgid "" -"Look up the codec for the given encoding and return its :class:" -"`StreamWriter` class or factory function." -msgstr "" - -#: ../../library/codecs.rst:164 -msgid "" -"Custom codecs are made available by registering a suitable codec search " -"function:" -msgstr "" - -#: ../../library/codecs.rst:169 -msgid "" -"Register a codec search function. Search functions are expected to take one " -"argument, being the encoding name in all lower case letters with hyphens and " -"spaces converted to underscores, and return a :class:`CodecInfo` object. In " -"case a search function cannot find a given encoding, it should return " -"``None``." -msgstr "" - -#: ../../library/codecs.rst:175 -msgid "Hyphens and spaces are converted to underscore." -msgstr "" - -#: ../../library/codecs.rst:181 -msgid "" -"Unregister a codec search function and clear the registry's cache. If the " -"search function is not registered, do nothing." -msgstr "" - -#: ../../library/codecs.rst:187 -msgid "" -"While the builtin :func:`open` and the associated :mod:`io` module are the " -"recommended approach for working with encoded text files, this module " -"provides additional utility functions and classes that allow the use of a " -"wider range of codecs when working with binary files:" -msgstr "" - -#: ../../library/codecs.rst:194 -msgid "" -"Open an encoded file using the given *mode* and return an instance of :class:" -"`StreamReaderWriter`, providing transparent encoding/decoding. The default " -"file mode is ``'r'``, meaning to open the file in read mode." -msgstr "" - -#: ../../library/codecs.rst:200 -msgid "" -"If *encoding* is not ``None``, then the underlying encoded files are always " -"opened in binary mode. No automatic conversion of ``'\\n'`` is done on " -"reading and writing. The *mode* argument may be any binary mode acceptable " -"to the built-in :func:`open` function; the ``'b'`` is automatically added." -msgstr "" - -#: ../../library/codecs.rst:206 -msgid "" -"*encoding* specifies the encoding which is to be used for the file. Any " -"encoding that encodes to and decodes from bytes is allowed, and the data " -"types supported by the file methods depend on the codec used." -msgstr "" - -#: ../../library/codecs.rst:210 -msgid "" -"*errors* may be given to define the error handling. It defaults to " -"``'strict'`` which causes a :exc:`ValueError` to be raised in case an " -"encoding error occurs." -msgstr "" - -#: ../../library/codecs.rst:213 -msgid "" -"*buffering* has the same meaning as for the built-in :func:`open` function. " -"It defaults to -1 which means that the default buffer size will be used." -msgstr "" - -#: ../../library/codecs.rst:216 -msgid "The ``'U'`` mode has been removed." -msgstr "已移除 ``'U'`` 模式。" - -#: ../../library/codecs.rst:221 -msgid ":func:`codecs.open` has been superseded by :func:`open`." -msgstr "" - -#: ../../library/codecs.rst:226 -msgid "" -"Return a :class:`StreamRecoder` instance, a wrapped version of *file* which " -"provides transparent transcoding. The original file is closed when the " -"wrapped version is closed." -msgstr "" - -#: ../../library/codecs.rst:230 -msgid "" -"Data written to the wrapped file is decoded according to the given " -"*data_encoding* and then written to the original file as bytes using " -"*file_encoding*. Bytes read from the original file are decoded according to " -"*file_encoding*, and the result is encoded using *data_encoding*." -msgstr "" - -#: ../../library/codecs.rst:236 -msgid "If *file_encoding* is not given, it defaults to *data_encoding*." -msgstr "" - -#: ../../library/codecs.rst:238 -msgid "" -"*errors* may be given to define the error handling. It defaults to " -"``'strict'``, which causes :exc:`ValueError` to be raised in case an " -"encoding error occurs." -msgstr "" - -#: ../../library/codecs.rst:245 -msgid "" -"Uses an incremental encoder to iteratively encode the input provided by " -"*iterator*. *iterator* must yield :class:`str` objects. This function is a :" -"term:`generator`. The *errors* argument (as well as any other keyword " -"argument) is passed through to the incremental encoder." -msgstr "" - -#: ../../library/codecs.rst:250 -msgid "" -"This function requires that the codec accept text :class:`str` objects to " -"encode. Therefore it does not support bytes-to-bytes encoders such as " -"``base64_codec``." -msgstr "" - -#: ../../library/codecs.rst:257 -msgid "" -"Uses an incremental decoder to iteratively decode the input provided by " -"*iterator*. *iterator* must yield :class:`bytes` objects. This function is " -"a :term:`generator`. The *errors* argument (as well as any other keyword " -"argument) is passed through to the incremental decoder." -msgstr "" - -#: ../../library/codecs.rst:262 -msgid "" -"This function requires that the codec accept :class:`bytes` objects to " -"decode. Therefore it does not support text-to-text encoders such as " -"``rot_13``, although ``rot_13`` may be used equivalently with :func:" -"`iterencode`." -msgstr "" - -#: ../../library/codecs.rst:270 -msgid "" -"Return a :class:`tuple` containing the raw bytes of *buffer*, a :ref:`buffer-" -"compatible object ` or :class:`str` (encoded to UTF-8 before " -"processing), and their length in bytes." -msgstr "" - -#: ../../library/codecs.rst:274 -msgid "The *errors* argument is ignored." -msgstr "忽略 *errors* 引數。" - -#: ../../library/codecs.rst:276 -msgid "" -">>> codecs.readbuffer_encode(b\"Zito\")\n" -"(b'Zito', 4)" -msgstr "" -">>> codecs.readbuffer_encode(b\"Zito\")\n" -"(b'Zito', 4)" - -#: ../../library/codecs.rst:282 -msgid "" -"The module also provides the following constants which are useful for " -"reading and writing to platform dependent files:" -msgstr "" - -#: ../../library/codecs.rst:297 -msgid "" -"These constants define various byte sequences, being Unicode byte order " -"marks (BOMs) for several encodings. They are used in UTF-16 and UTF-32 data " -"streams to indicate the byte order used, and in UTF-8 as a Unicode " -"signature. :const:`BOM_UTF16` is either :const:`BOM_UTF16_BE` or :const:" -"`BOM_UTF16_LE` depending on the platform's native byte order, :const:`BOM` " -"is an alias for :const:`BOM_UTF16`, :const:`BOM_LE` for :const:" -"`BOM_UTF16_LE` and :const:`BOM_BE` for :const:`BOM_UTF16_BE`. The others " -"represent the BOM in UTF-8 and UTF-32 encodings." -msgstr "" - -#: ../../library/codecs.rst:311 -msgid "Codec Base Classes" -msgstr "" - -#: ../../library/codecs.rst:313 -msgid "" -"The :mod:`codecs` module defines a set of base classes which define the " -"interfaces for working with codec objects, and can also be used as the basis " -"for custom codec implementations." -msgstr "" - -#: ../../library/codecs.rst:317 -msgid "" -"Each codec has to define four interfaces to make it usable as codec in " -"Python: stateless encoder, stateless decoder, stream reader and stream " -"writer. The stream reader and writers typically reuse the stateless encoder/" -"decoder to implement the file protocols. Codec authors also need to define " -"how the codec will handle encoding and decoding errors." -msgstr "" - -#: ../../library/codecs.rst:328 -msgid "Error Handlers" -msgstr "" - -#: ../../library/codecs.rst:330 -msgid "" -"To simplify and standardize error handling, codecs may implement different " -"error handling schemes by accepting the *errors* string argument:" -msgstr "" - -#: ../../library/codecs.rst:350 -msgid "" -"The following error handlers can be used with all Python :ref:`standard-" -"encodings` codecs:" -msgstr "" - -#: ../../library/codecs.rst:356 ../../library/codecs.rst:399 -#: ../../library/codecs.rst:419 -msgid "Value" -msgstr "" - -#: ../../library/codecs.rst:356 ../../library/codecs.rst:399 -#: ../../library/codecs.rst:419 ../../library/codecs.rst:1376 -#: ../../library/codecs.rst:1448 ../../library/codecs.rst:1533 -msgid "Meaning" -msgstr "含義" - -#: ../../library/codecs.rst:358 -msgid "``'strict'``" -msgstr "``'strict'``" - -#: ../../library/codecs.rst:358 -msgid "" -"Raise :exc:`UnicodeError` (or a subclass), this is the default. Implemented " -"in :func:`strict_errors`." -msgstr "" - -#: ../../library/codecs.rst:362 -msgid "``'ignore'``" -msgstr "``'ignore'``" - -#: ../../library/codecs.rst:362 -msgid "" -"Ignore the malformed data and continue without further notice. Implemented " -"in :func:`ignore_errors`." -msgstr "" - -#: ../../library/codecs.rst:366 -msgid "``'replace'``" -msgstr "``'replace'``" - -#: ../../library/codecs.rst:366 -msgid "" -"Replace with a replacement marker. On encoding, use ``?`` (ASCII character). " -"On decoding, use ``�`` (U+FFFD, the official REPLACEMENT CHARACTER). " -"Implemented in :func:`replace_errors`." -msgstr "" - -#: ../../library/codecs.rst:372 -msgid "``'backslashreplace'``" -msgstr "``'backslashreplace'``" - -#: ../../library/codecs.rst:372 -msgid "" -"Replace with backslashed escape sequences. On encoding, use hexadecimal form " -"of Unicode code point with formats :samp:`\\\\x{hh}` :samp:`\\\\u{xxxx}` :" -"samp:`\\\\U{xxxxxxxx}`. On decoding, use hexadecimal form of byte value with " -"format :samp:`\\\\x{hh}`. Implemented in :func:`backslashreplace_errors`." -msgstr "" - -#: ../../library/codecs.rst:381 -msgid "``'surrogateescape'``" -msgstr "``'surrogateescape'``" - -#: ../../library/codecs.rst:381 -msgid "" -"On decoding, replace byte with individual surrogate code ranging from " -"``U+DC80`` to ``U+DCFF``. This code will then be turned back into the same " -"byte when the ``'surrogateescape'`` error handler is used when encoding the " -"data. (See :pep:`383` for more.)" -msgstr "" - -#: ../../library/codecs.rst:395 -msgid "" -"The following error handlers are only applicable to encoding (within :term:" -"`text encodings `):" -msgstr "" - -#: ../../library/codecs.rst:401 -msgid "``'xmlcharrefreplace'``" -msgstr "``'xmlcharrefreplace'``" - -#: ../../library/codecs.rst:401 -msgid "" -"Replace with XML/HTML numeric character reference, which is a decimal form " -"of Unicode code point with format :samp:`&#{num};`. Implemented in :func:" -"`xmlcharrefreplace_errors`." -msgstr "" - -#: ../../library/codecs.rst:407 -msgid "``'namereplace'``" -msgstr "``'namereplace'``" - -#: ../../library/codecs.rst:407 -msgid "" -"Replace with ``\\N{...}`` escape sequences, what appears in the braces is " -"the Name property from Unicode Character Database. Implemented in :func:" -"`namereplace_errors`." -msgstr "" - -#: ../../library/codecs.rst:416 -msgid "" -"In addition, the following error handler is specific to the given codecs:" -msgstr "" - -#: ../../library/codecs.rst:13 ../../library/codecs.rst:419 -msgid "Codecs" -msgstr "" - -#: ../../library/codecs.rst:421 -msgid "``'surrogatepass'``" -msgstr "``'surrogatepass'``" - -#: ../../library/codecs.rst:421 -msgid "utf-8, utf-16, utf-32, utf-16-be, utf-16-le, utf-32-be, utf-32-le" -msgstr "utf-8, utf-16, utf-32, utf-16-be, utf-16-le, utf-32-be, utf-32-le" - -#: ../../library/codecs.rst:421 -msgid "" -"Allow encoding and decoding surrogate code point (``U+D800`` - ``U+DFFF``) " -"as normal code point. Otherwise these codecs treat the presence of surrogate " -"code point in :class:`str` as an error." -msgstr "" - -#: ../../library/codecs.rst:428 -msgid "The ``'surrogateescape'`` and ``'surrogatepass'`` error handlers." -msgstr "" - -#: ../../library/codecs.rst:431 -msgid "" -"The ``'surrogatepass'`` error handler now works with utf-16\\* and utf-32\\* " -"codecs." -msgstr "" - -#: ../../library/codecs.rst:435 -msgid "The ``'namereplace'`` error handler." -msgstr "" - -#: ../../library/codecs.rst:438 -msgid "" -"The ``'backslashreplace'`` error handler now works with decoding and " -"translating." -msgstr "" - -#: ../../library/codecs.rst:442 -msgid "" -"The set of allowed values can be extended by registering a new named error " -"handler:" -msgstr "" - -#: ../../library/codecs.rst:447 -msgid "" -"Register the error handling function *error_handler* under the name *name*. " -"The *error_handler* argument will be called during encoding and decoding in " -"case of an error, when *name* is specified as the errors parameter." -msgstr "" - -#: ../../library/codecs.rst:451 -msgid "" -"For encoding, *error_handler* will be called with a :exc:" -"`UnicodeEncodeError` instance, which contains information about the location " -"of the error. The error handler must either raise this or a different " -"exception, or return a tuple with a replacement for the unencodable part of " -"the input and a position where encoding should continue. The replacement may " -"be either :class:`str` or :class:`bytes`. If the replacement is bytes, the " -"encoder will simply copy them into the output buffer. If the replacement is " -"a string, the encoder will encode the replacement. Encoding continues on " -"original input at the specified position. Negative position values will be " -"treated as being relative to the end of the input string. If the resulting " -"position is out of bound an :exc:`IndexError` will be raised." -msgstr "" - -#: ../../library/codecs.rst:463 -msgid "" -"Decoding and translating works similarly, except :exc:`UnicodeDecodeError` " -"or :exc:`UnicodeTranslateError` will be passed to the handler and that the " -"replacement from the error handler will be put into the output directly." -msgstr "" - -#: ../../library/codecs.rst:468 -msgid "" -"Previously registered error handlers (including the standard error handlers) " -"can be looked up by name:" -msgstr "" - -#: ../../library/codecs.rst:473 -msgid "Return the error handler previously registered under the name *name*." -msgstr "" - -#: ../../library/codecs.rst:475 -msgid "Raises a :exc:`LookupError` in case the handler cannot be found." -msgstr "" - -#: ../../library/codecs.rst:477 -msgid "" -"The following standard error handlers are also made available as module " -"level functions:" -msgstr "" - -#: ../../library/codecs.rst:482 -msgid "Implements the ``'strict'`` error handling." -msgstr "" - -#: ../../library/codecs.rst:484 -msgid "Each encoding or decoding error raises a :exc:`UnicodeError`." -msgstr "" - -#: ../../library/codecs.rst:489 -msgid "Implements the ``'ignore'`` error handling." -msgstr "" - -#: ../../library/codecs.rst:491 -msgid "" -"Malformed data is ignored; encoding or decoding is continued without further " -"notice." -msgstr "" - -#: ../../library/codecs.rst:497 -msgid "Implements the ``'replace'`` error handling." -msgstr "" - -#: ../../library/codecs.rst:499 -msgid "" -"Substitutes ``?`` (ASCII character) for encoding errors or ``�`` (U+FFFD, " -"the official REPLACEMENT CHARACTER) for decoding errors." -msgstr "" - -#: ../../library/codecs.rst:505 -msgid "Implements the ``'backslashreplace'`` error handling." -msgstr "" - -#: ../../library/codecs.rst:507 -msgid "" -"Malformed data is replaced by a backslashed escape sequence. On encoding, " -"use the hexadecimal form of Unicode code point with formats :samp:`\\\\x{hh}" -"` :samp:`\\\\u{xxxx}` :samp:`\\\\U{xxxxxxxx}`. On decoding, use the " -"hexadecimal form of byte value with format :samp:`\\\\x{hh}`." -msgstr "" - -#: ../../library/codecs.rst:513 -msgid "Works with decoding and translating." -msgstr "" - -#: ../../library/codecs.rst:519 -msgid "" -"Implements the ``'xmlcharrefreplace'`` error handling (for encoding within :" -"term:`text encoding` only)." -msgstr "" - -#: ../../library/codecs.rst:522 -msgid "" -"The unencodable character is replaced by an appropriate XML/HTML numeric " -"character reference, which is a decimal form of Unicode code point with " -"format :samp:`&#{num};` ." -msgstr "" - -#: ../../library/codecs.rst:529 -msgid "" -"Implements the ``'namereplace'`` error handling (for encoding within :term:" -"`text encoding` only)." -msgstr "" - -#: ../../library/codecs.rst:532 -msgid "" -"The unencodable character is replaced by a ``\\N{...}`` escape sequence. The " -"set of characters that appear in the braces is the Name property from " -"Unicode Character Database. For example, the German lowercase letter ``'ß'`` " -"will be converted to byte sequence ``\\N{LATIN SMALL LETTER SHARP S}`` ." -msgstr "" - -#: ../../library/codecs.rst:543 -msgid "Stateless Encoding and Decoding" -msgstr "" - -#: ../../library/codecs.rst:545 -msgid "" -"The base :class:`Codec` class defines these methods which also define the " -"function interfaces of the stateless encoder and decoder:" -msgstr "" - -#: ../../library/codecs.rst:553 -msgid "" -"Encodes the object *input* and returns a tuple (output object, length " -"consumed). For instance, :term:`text encoding` converts a string object to a " -"bytes object using a particular character set encoding (e.g., ``cp1252`` or " -"``iso-8859-1``)." -msgstr "" - -#: ../../library/codecs.rst:558 ../../library/codecs.rst:580 -msgid "" -"The *errors* argument defines the error handling to apply. It defaults to " -"``'strict'`` handling." -msgstr "" - -#: ../../library/codecs.rst:561 -msgid "" -"The method may not store state in the :class:`Codec` instance. Use :class:" -"`StreamWriter` for codecs which have to keep state in order to make encoding " -"efficient." -msgstr "" - -#: ../../library/codecs.rst:565 -msgid "" -"The encoder must be able to handle zero length input and return an empty " -"object of the output object type in this situation." -msgstr "" - -#: ../../library/codecs.rst:571 -msgid "" -"Decodes the object *input* and returns a tuple (output object, length " -"consumed). For instance, for a :term:`text encoding`, decoding converts a " -"bytes object encoded using a particular character set encoding to a string " -"object." -msgstr "" - -#: ../../library/codecs.rst:576 -msgid "" -"For text encodings and bytes-to-bytes codecs, *input* must be a bytes object " -"or one which provides the read-only buffer interface -- for example, buffer " -"objects and memory mapped files." -msgstr "" - -#: ../../library/codecs.rst:583 -msgid "" -"The method may not store state in the :class:`Codec` instance. Use :class:" -"`StreamReader` for codecs which have to keep state in order to make decoding " -"efficient." -msgstr "" - -#: ../../library/codecs.rst:587 -msgid "" -"The decoder must be able to handle zero length input and return an empty " -"object of the output object type in this situation." -msgstr "" - -#: ../../library/codecs.rst:592 -msgid "Incremental Encoding and Decoding" -msgstr "" - -#: ../../library/codecs.rst:594 -msgid "" -"The :class:`IncrementalEncoder` and :class:`IncrementalDecoder` classes " -"provide the basic interface for incremental encoding and decoding. Encoding/" -"decoding the input isn't done with one call to the stateless encoder/decoder " -"function, but with multiple calls to the :meth:`~IncrementalEncoder.encode`/:" -"meth:`~IncrementalDecoder.decode` method of the incremental encoder/decoder. " -"The incremental encoder/decoder keeps track of the encoding/decoding process " -"during method calls." -msgstr "" - -#: ../../library/codecs.rst:602 -msgid "" -"The joined output of calls to the :meth:`~IncrementalEncoder.encode`/:meth:" -"`~IncrementalDecoder.decode` method is the same as if all the single inputs " -"were joined into one, and this input was encoded/decoded with the stateless " -"encoder/decoder." -msgstr "" - -#: ../../library/codecs.rst:611 -msgid "IncrementalEncoder Objects" -msgstr "IncrementalEncoder 物件" - -#: ../../library/codecs.rst:613 -msgid "" -"The :class:`IncrementalEncoder` class is used for encoding an input in " -"multiple steps. It defines the following methods which every incremental " -"encoder must define in order to be compatible with the Python codec registry." -msgstr "" - -#: ../../library/codecs.rst:620 -msgid "Constructor for an :class:`IncrementalEncoder` instance." -msgstr ":class:`IncrementalEncoder` 的建構函式。" - -#: ../../library/codecs.rst:622 -msgid "" -"All incremental encoders must provide this constructor interface. They are " -"free to add additional keyword arguments, but only the ones defined here are " -"used by the Python codec registry." -msgstr "" - -#: ../../library/codecs.rst:626 -msgid "" -"The :class:`IncrementalEncoder` may implement different error handling " -"schemes by providing the *errors* keyword argument. See :ref:`error-" -"handlers` for possible values." -msgstr "" - -#: ../../library/codecs.rst:630 -msgid "" -"The *errors* argument will be assigned to an attribute of the same name. " -"Assigning to this attribute makes it possible to switch between different " -"error handling strategies during the lifetime of the :class:" -"`IncrementalEncoder` object." -msgstr "" - -#: ../../library/codecs.rst:638 -msgid "" -"Encodes *object* (taking the current state of the encoder into account) and " -"returns the resulting encoded object. If this is the last call to :meth:" -"`encode` *final* must be true (the default is false)." -msgstr "" - -#: ../../library/codecs.rst:645 -msgid "" -"Reset the encoder to the initial state. The output is discarded: call ``." -"encode(object, final=True)``, passing an empty byte or text string if " -"necessary, to reset the encoder and to get the output." -msgstr "" - -#: ../../library/codecs.rst:652 -msgid "" -"Return the current state of the encoder which must be an integer. The " -"implementation should make sure that ``0`` is the most common state. (States " -"that are more complicated than integers can be converted into an integer by " -"marshaling/pickling the state and encoding the bytes of the resulting string " -"into an integer.)" -msgstr "" - -#: ../../library/codecs.rst:661 -msgid "" -"Set the state of the encoder to *state*. *state* must be an encoder state " -"returned by :meth:`getstate`." -msgstr "" - -#: ../../library/codecs.rst:668 -msgid "IncrementalDecoder Objects" -msgstr "IncrementalDecoder 物件" - -#: ../../library/codecs.rst:670 -msgid "" -"The :class:`IncrementalDecoder` class is used for decoding an input in " -"multiple steps. It defines the following methods which every incremental " -"decoder must define in order to be compatible with the Python codec registry." -msgstr "" - -#: ../../library/codecs.rst:677 -msgid "Constructor for an :class:`IncrementalDecoder` instance." -msgstr ":class:`IncrementalDecoder` 的建構函式。" - -#: ../../library/codecs.rst:679 -msgid "" -"All incremental decoders must provide this constructor interface. They are " -"free to add additional keyword arguments, but only the ones defined here are " -"used by the Python codec registry." -msgstr "" - -#: ../../library/codecs.rst:683 -msgid "" -"The :class:`IncrementalDecoder` may implement different error handling " -"schemes by providing the *errors* keyword argument. See :ref:`error-" -"handlers` for possible values." -msgstr "" - -#: ../../library/codecs.rst:687 -msgid "" -"The *errors* argument will be assigned to an attribute of the same name. " -"Assigning to this attribute makes it possible to switch between different " -"error handling strategies during the lifetime of the :class:" -"`IncrementalDecoder` object." -msgstr "" - -#: ../../library/codecs.rst:695 -msgid "" -"Decodes *object* (taking the current state of the decoder into account) and " -"returns the resulting decoded object. If this is the last call to :meth:" -"`decode` *final* must be true (the default is false). If *final* is true the " -"decoder must decode the input completely and must flush all buffers. If this " -"isn't possible (e.g. because of incomplete byte sequences at the end of the " -"input) it must initiate error handling just like in the stateless case " -"(which might raise an exception)." -msgstr "" - -#: ../../library/codecs.rst:706 -msgid "Reset the decoder to the initial state." -msgstr "將解碼器重設到初始狀態。" - -#: ../../library/codecs.rst:711 -msgid "" -"Return the current state of the decoder. This must be a tuple with two " -"items, the first must be the buffer containing the still undecoded input. " -"The second must be an integer and can be additional state info. (The " -"implementation should make sure that ``0`` is the most common additional " -"state info.) If this additional state info is ``0`` it must be possible to " -"set the decoder to the state which has no input buffered and ``0`` as the " -"additional state info, so that feeding the previously buffered input to the " -"decoder returns it to the previous state without producing any output. " -"(Additional state info that is more complicated than integers can be " -"converted into an integer by marshaling/pickling the info and encoding the " -"bytes of the resulting string into an integer.)" -msgstr "" - -#: ../../library/codecs.rst:726 -msgid "" -"Set the state of the decoder to *state*. *state* must be a decoder state " -"returned by :meth:`getstate`." -msgstr "" - -#: ../../library/codecs.rst:731 -msgid "Stream Encoding and Decoding" -msgstr "串流編碼和解碼" - -#: ../../library/codecs.rst:734 -msgid "" -"The :class:`StreamWriter` and :class:`StreamReader` classes provide generic " -"working interfaces which can be used to implement new encoding submodules " -"very easily. See :mod:`!encodings.utf_8` for an example of how this is done." -msgstr "" - -#: ../../library/codecs.rst:742 -msgid "StreamWriter Objects" -msgstr "StreamWriter 物件" - -#: ../../library/codecs.rst:744 -msgid "" -"The :class:`StreamWriter` class is a subclass of :class:`Codec` and defines " -"the following methods which every stream writer must define in order to be " -"compatible with the Python codec registry." -msgstr "" - -#: ../../library/codecs.rst:751 -msgid "Constructor for a :class:`StreamWriter` instance." -msgstr ":class:`StreamWriter` 的建構函式。" - -#: ../../library/codecs.rst:753 -msgid "" -"All stream writers must provide this constructor interface. They are free to " -"add additional keyword arguments, but only the ones defined here are used by " -"the Python codec registry." -msgstr "" - -#: ../../library/codecs.rst:757 -msgid "" -"The *stream* argument must be a file-like object open for writing text or " -"binary data, as appropriate for the specific codec." -msgstr "" - -#: ../../library/codecs.rst:760 -msgid "" -"The :class:`StreamWriter` may implement different error handling schemes by " -"providing the *errors* keyword argument. See :ref:`error-handlers` for the " -"standard error handlers the underlying stream codec may support." -msgstr "" - -#: ../../library/codecs.rst:764 -msgid "" -"The *errors* argument will be assigned to an attribute of the same name. " -"Assigning to this attribute makes it possible to switch between different " -"error handling strategies during the lifetime of the :class:`StreamWriter` " -"object." -msgstr "" - -#: ../../library/codecs.rst:770 -msgid "Writes the object's contents encoded to the stream." -msgstr "" - -#: ../../library/codecs.rst:775 -msgid "" -"Writes the concatenated iterable of strings to the stream (possibly by " -"reusing the :meth:`write` method). Infinite or very large iterables are not " -"supported. The standard bytes-to-bytes codecs do not support this method." -msgstr "" - -#: ../../library/codecs.rst:783 ../../library/codecs.rst:878 -msgid "Resets the codec buffers used for keeping internal state." -msgstr "" - -#: ../../library/codecs.rst:785 -msgid "" -"Calling this method should ensure that the data on the output is put into a " -"clean state that allows appending of new fresh data without having to rescan " -"the whole stream to recover state." -msgstr "" - -#: ../../library/codecs.rst:790 -msgid "" -"In addition to the above methods, the :class:`StreamWriter` must also " -"inherit all other methods and attributes from the underlying stream." -msgstr "" - -#: ../../library/codecs.rst:797 -msgid "StreamReader Objects" -msgstr "StreamReader 物件" - -#: ../../library/codecs.rst:799 -msgid "" -"The :class:`StreamReader` class is a subclass of :class:`Codec` and defines " -"the following methods which every stream reader must define in order to be " -"compatible with the Python codec registry." -msgstr "" - -#: ../../library/codecs.rst:806 -msgid "Constructor for a :class:`StreamReader` instance." -msgstr ":class:`StreamReader` 的建構函式。" - -#: ../../library/codecs.rst:808 -msgid "" -"All stream readers must provide this constructor interface. They are free to " -"add additional keyword arguments, but only the ones defined here are used by " -"the Python codec registry." -msgstr "" - -#: ../../library/codecs.rst:812 -msgid "" -"The *stream* argument must be a file-like object open for reading text or " -"binary data, as appropriate for the specific codec." -msgstr "" - -#: ../../library/codecs.rst:815 -msgid "" -"The :class:`StreamReader` may implement different error handling schemes by " -"providing the *errors* keyword argument. See :ref:`error-handlers` for the " -"standard error handlers the underlying stream codec may support." -msgstr "" - -#: ../../library/codecs.rst:819 -msgid "" -"The *errors* argument will be assigned to an attribute of the same name. " -"Assigning to this attribute makes it possible to switch between different " -"error handling strategies during the lifetime of the :class:`StreamReader` " -"object." -msgstr "" - -#: ../../library/codecs.rst:823 -msgid "" -"The set of allowed values for the *errors* argument can be extended with :" -"func:`register_error`." -msgstr "" - -#: ../../library/codecs.rst:829 -msgid "Decodes data from the stream and returns the resulting object." -msgstr "" - -#: ../../library/codecs.rst:831 -msgid "" -"The *chars* argument indicates the number of decoded code points or bytes to " -"return. The :func:`read` method will never return more data than requested, " -"but it might return less, if there is not enough available." -msgstr "" - -#: ../../library/codecs.rst:836 -msgid "" -"The *size* argument indicates the approximate maximum number of encoded " -"bytes or code points to read for decoding. The decoder can modify this " -"setting as appropriate. The default value -1 indicates to read and decode as " -"much as possible. This parameter is intended to prevent having to decode " -"huge files in one step." -msgstr "" - -#: ../../library/codecs.rst:843 -msgid "" -"The *firstline* flag indicates that it would be sufficient to only return " -"the first line, if there are decoding errors on later lines." -msgstr "" - -#: ../../library/codecs.rst:847 -msgid "" -"The method should use a greedy read strategy meaning that it should read as " -"much data as is allowed within the definition of the encoding and the given " -"size, e.g. if optional encoding endings or state markers are available on " -"the stream, these should be read too." -msgstr "" - -#: ../../library/codecs.rst:855 -msgid "Read one line from the input stream and return the decoded data." -msgstr "" - -#: ../../library/codecs.rst:857 -msgid "" -"*size*, if given, is passed as size argument to the stream's :meth:`read` " -"method." -msgstr "" - -#: ../../library/codecs.rst:860 -msgid "" -"If *keepends* is false line-endings will be stripped from the lines returned." -msgstr "" - -#: ../../library/codecs.rst:866 -msgid "" -"Read all lines available on the input stream and return them as a list of " -"lines." -msgstr "" - -#: ../../library/codecs.rst:869 -msgid "" -"Line-endings are implemented using the codec's :meth:`decode` method and are " -"included in the list entries if *keepends* is true." -msgstr "" - -#: ../../library/codecs.rst:872 -msgid "" -"*sizehint*, if given, is passed as the *size* argument to the stream's :meth:" -"`read` method." -msgstr "" - -#: ../../library/codecs.rst:880 -msgid "" -"Note that no stream repositioning should take place. This method is " -"primarily intended to be able to recover from decoding errors." -msgstr "" - -#: ../../library/codecs.rst:884 -msgid "" -"In addition to the above methods, the :class:`StreamReader` must also " -"inherit all other methods and attributes from the underlying stream." -msgstr "" - -#: ../../library/codecs.rst:890 -msgid "StreamReaderWriter Objects" -msgstr "StreamReaderWriter 物件" - -#: ../../library/codecs.rst:892 -msgid "" -"The :class:`StreamReaderWriter` is a convenience class that allows wrapping " -"streams which work in both read and write modes." -msgstr "" - -#: ../../library/codecs.rst:895 ../../library/codecs.rst:919 -msgid "" -"The design is such that one can use the factory functions returned by the :" -"func:`lookup` function to construct the instance." -msgstr "" - -#: ../../library/codecs.rst:901 -msgid "" -"Creates a :class:`StreamReaderWriter` instance. *stream* must be a file-like " -"object. *Reader* and *Writer* must be factory functions or classes providing " -"the :class:`StreamReader` and :class:`StreamWriter` interface resp. Error " -"handling is done in the same way as defined for the stream readers and " -"writers." -msgstr "" - -#: ../../library/codecs.rst:906 -msgid "" -":class:`StreamReaderWriter` instances define the combined interfaces of :" -"class:`StreamReader` and :class:`StreamWriter` classes. They inherit all " -"other methods and attributes from the underlying stream." -msgstr "" - -#: ../../library/codecs.rst:914 -msgid "StreamRecoder Objects" -msgstr "StreamRecoder 物件" - -#: ../../library/codecs.rst:916 -msgid "" -"The :class:`StreamRecoder` translates data from one encoding to another, " -"which is sometimes useful when dealing with different encoding environments." -msgstr "" - -#: ../../library/codecs.rst:925 -msgid "" -"Creates a :class:`StreamRecoder` instance which implements a two-way " -"conversion: *encode* and *decode* work on the frontend — the data visible to " -"code calling :meth:`~StreamReader.read` and :meth:`~StreamWriter.write`, " -"while *Reader* and *Writer* work on the backend — the data in *stream*." -msgstr "" - -#: ../../library/codecs.rst:931 -msgid "" -"You can use these objects to do transparent transcodings, e.g., from Latin-1 " -"to UTF-8 and back." -msgstr "" - -#: ../../library/codecs.rst:934 -msgid "The *stream* argument must be a file-like object." -msgstr "*stream* 引數必須是類檔案物件。" - -#: ../../library/codecs.rst:936 -msgid "" -"The *encode* and *decode* arguments must adhere to the :class:`Codec` " -"interface. *Reader* and *Writer* must be factory functions or classes " -"providing objects of the :class:`StreamReader` and :class:`StreamWriter` " -"interface respectively." -msgstr "" - -#: ../../library/codecs.rst:941 -msgid "" -"Error handling is done in the same way as defined for the stream readers and " -"writers." -msgstr "" - -#: ../../library/codecs.rst:945 -msgid "" -":class:`StreamRecoder` instances define the combined interfaces of :class:" -"`StreamReader` and :class:`StreamWriter` classes. They inherit all other " -"methods and attributes from the underlying stream." -msgstr "" - -#: ../../library/codecs.rst:953 -msgid "Encodings and Unicode" -msgstr "編碼和 Unicode" - -#: ../../library/codecs.rst:955 -msgid "" -"Strings are stored internally as sequences of code points in range " -"``U+0000``--``U+10FFFF``. (See :pep:`393` for more details about the " -"implementation.) Once a string object is used outside of CPU and memory, " -"endianness and how these arrays are stored as bytes become an issue. As with " -"other codecs, serialising a string into a sequence of bytes is known as " -"*encoding*, and recreating the string from the sequence of bytes is known as " -"*decoding*. There are a variety of different text serialisation codecs, " -"which are collectivity referred to as :term:`text encodings `." -msgstr "" - -#: ../../library/codecs.rst:965 -msgid "" -"The simplest text encoding (called ``'latin-1'`` or ``'iso-8859-1'``) maps " -"the code points 0--255 to the bytes ``0x0``--``0xff``, which means that a " -"string object that contains code points above ``U+00FF`` can't be encoded " -"with this codec. Doing so will raise a :exc:`UnicodeEncodeError` that looks " -"like the following (although the details of the error message may differ): " -"``UnicodeEncodeError: 'latin-1' codec can't encode character '\\u1234' in " -"position 3: ordinal not in range(256)``." -msgstr "" - -#: ../../library/codecs.rst:973 -msgid "" -"There's another group of encodings (the so called charmap encodings) that " -"choose a different subset of all Unicode code points and how these code " -"points are mapped to the bytes ``0x0``--``0xff``. To see how this is done " -"simply open e.g. :file:`encodings/cp1252.py` (which is an encoding that is " -"used primarily on Windows). There's a string constant with 256 characters " -"that shows you which character is mapped to which byte value." -msgstr "" - -#: ../../library/codecs.rst:980 -msgid "" -"All of these encodings can only encode 256 of the 1114112 code points " -"defined in Unicode. A simple and straightforward way that can store each " -"Unicode code point, is to store each code point as four consecutive bytes. " -"There are two possibilities: store the bytes in big endian or in little " -"endian order. These two encodings are called ``UTF-32-BE`` and ``UTF-32-LE`` " -"respectively. Their disadvantage is that if, for example, you use ``UTF-32-" -"BE`` on a little endian machine you will always have to swap bytes on " -"encoding and decoding. Python's ``UTF-16`` and ``UTF-32`` codecs avoid this " -"problem by using the platform's native byte order when no BOM is present. " -"Python follows prevailing platform practice, so native-endian data round-" -"trips without redundant byte swapping, even though the Unicode Standard " -"defaults to big-endian when the byte order is unspecified. When these bytes " -"are read by a CPU with a different endianness, the bytes have to be swapped. " -"To be able to detect the endianness of a ``UTF-16`` or ``UTF-32`` byte " -"sequence, a BOM (\"Byte Order Mark\") is used. This is the Unicode character " -"``U+FEFF``. This character can be prepended to every ``UTF-16`` or " -"``UTF-32`` byte sequence. The byte swapped version of this character " -"(``0xFFFE``) is an illegal character that may not appear in a Unicode text. " -"When the first character of a ``UTF-16`` or ``UTF-32`` byte sequence is " -"``U+FFFE``, the bytes have to be swapped on decoding." -msgstr "" - -#: ../../library/codecs.rst:1001 -msgid "" -"Unfortunately the character ``U+FEFF`` had a second purpose as a ``ZERO " -"WIDTH NO-BREAK SPACE``: a character that has no width and doesn't allow a " -"word to be split. It can e.g. be used to give hints to a ligature algorithm. " -"With Unicode 4.0 using ``U+FEFF`` as a ``ZERO WIDTH NO-BREAK SPACE`` has " -"been deprecated (with ``U+2060`` (``WORD JOINER``) assuming this role). " -"Nevertheless Unicode software still must be able to handle ``U+FEFF`` in " -"both roles: as a BOM it's a device to determine the storage layout of the " -"encoded bytes, and vanishes once the byte sequence has been decoded into a " -"string; as a ``ZERO WIDTH NO-BREAK SPACE`` it's a normal character that will " -"be decoded like any other." -msgstr "" - -#: ../../library/codecs.rst:1011 -msgid "" -"There's another encoding that is able to encode the full range of Unicode " -"characters: UTF-8. UTF-8 is an 8-bit encoding, which means there are no " -"issues with byte order in UTF-8. Each byte in a UTF-8 byte sequence consists " -"of two parts: marker bits (the most significant bits) and payload bits. The " -"marker bits are a sequence of zero to four ``1`` bits followed by a ``0`` " -"bit. Unicode characters are encoded like this (with x being payload bits, " -"which when concatenated give the Unicode character):" -msgstr "" - -#: ../../library/codecs.rst:1020 -msgid "Range" -msgstr "" - -#: ../../library/codecs.rst:1020 -msgid "Encoding" -msgstr "" - -#: ../../library/codecs.rst:1022 -msgid "``U-00000000`` ... ``U-0000007F``" -msgstr "``U-00000000`` ... ``U-0000007F``" - -#: ../../library/codecs.rst:1022 -msgid "0xxxxxxx" -msgstr "0xxxxxxx" - -#: ../../library/codecs.rst:1024 -msgid "``U-00000080`` ... ``U-000007FF``" -msgstr "``U-00000080`` ... ``U-000007FF``" - -#: ../../library/codecs.rst:1024 -msgid "110xxxxx 10xxxxxx" -msgstr "110xxxxx 10xxxxxx" - -#: ../../library/codecs.rst:1026 -msgid "``U-00000800`` ... ``U-0000FFFF``" -msgstr "``U-00000800`` ... ``U-0000FFFF``" - -#: ../../library/codecs.rst:1026 -msgid "1110xxxx 10xxxxxx 10xxxxxx" -msgstr "1110xxxx 10xxxxxx 10xxxxxx" - -#: ../../library/codecs.rst:1028 -msgid "``U-00010000`` ... ``U-0010FFFF``" -msgstr "``U-00010000`` ... ``U-0010FFFF``" - -#: ../../library/codecs.rst:1028 -msgid "11110xxx 10xxxxxx 10xxxxxx 10xxxxxx" -msgstr "11110xxx 10xxxxxx 10xxxxxx 10xxxxxx" - -#: ../../library/codecs.rst:1031 -msgid "" -"The least significant bit of the Unicode character is the rightmost x bit." -msgstr "" - -#: ../../library/codecs.rst:1033 -msgid "" -"As UTF-8 is an 8-bit encoding no BOM is required and any ``U+FEFF`` " -"character in the decoded string (even if it's the first character) is " -"treated as a ``ZERO WIDTH NO-BREAK SPACE``." -msgstr "" - -#: ../../library/codecs.rst:1037 -msgid "" -"Without external information it's impossible to reliably determine which " -"encoding was used for encoding a string. Each charmap encoding can decode " -"any random byte sequence. However that's not possible with UTF-8, as UTF-8 " -"byte sequences have a structure that doesn't allow arbitrary byte sequences. " -"To increase the reliability with which a UTF-8 encoding can be detected, " -"Microsoft invented a variant of UTF-8 (that Python calls ``\"utf-8-sig\"``) " -"for its Notepad program: Before any of the Unicode characters is written to " -"the file, a UTF-8 encoded BOM (which looks like this as a byte sequence: " -"``0xef``, ``0xbb``, ``0xbf``) is written. As it's rather improbable that any " -"charmap encoded file starts with these byte values (which would e.g. map to" -msgstr "" - -#: ../../library/codecs.rst:1049 -msgid "LATIN SMALL LETTER I WITH DIAERESIS" -msgstr "" - -#: ../../library/codecs.rst:1050 -msgid "RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK" -msgstr "" - -#: ../../library/codecs.rst:1051 -msgid "INVERTED QUESTION MARK" -msgstr "" - -#: ../../library/codecs.rst:1053 -msgid "" -"in iso-8859-1), this increases the probability that a ``utf-8-sig`` encoding " -"can be correctly guessed from the byte sequence. So here the BOM is not used " -"to be able to determine the byte order used for generating the byte " -"sequence, but as a signature that helps in guessing the encoding. On " -"encoding the utf-8-sig codec will write ``0xef``, ``0xbb``, ``0xbf`` as the " -"first three bytes to the file. On decoding ``utf-8-sig`` will skip those " -"three bytes if they appear as the first three bytes in the file. In UTF-8, " -"the use of the BOM is discouraged and should generally be avoided." -msgstr "" - -#: ../../library/codecs.rst:1066 -msgid "Standard Encodings" -msgstr "標準編碼" - -#: ../../library/codecs.rst:1068 -msgid "" -"Python comes with a number of codecs built-in, either implemented as C " -"functions or with dictionaries as mapping tables. The following table lists " -"the codecs by name, together with a few common aliases, and the languages " -"for which the encoding is likely used. Neither the list of aliases nor the " -"list of languages is meant to be exhaustive. Notice that spelling " -"alternatives that only differ in case or use a hyphen instead of an " -"underscore are also valid aliases because they are equivalent when " -"normalized by :func:`~encodings.normalize_encoding`. For example, " -"``'utf-8'`` is a valid alias for the ``'utf_8'`` codec." -msgstr "" - -#: ../../library/codecs.rst:1080 -msgid "" -"The below table lists the most common aliases, for a complete list refer to " -"the source :source:`aliases.py ` file." -msgstr "" - -#: ../../library/codecs.rst:1083 -msgid "" -"On Windows, ``cpXXX`` codecs are available for all code pages. But only " -"codecs listed in the following table are guarantead to exist on other " -"platforms." -msgstr "" - -#: ../../library/codecs.rst:1089 -msgid "" -"Some common encodings can bypass the codecs lookup machinery to improve " -"performance. These optimization opportunities are only recognized by CPython " -"for a limited set of (case insensitive) aliases: utf-8, utf8, latin-1, " -"latin1, iso-8859-1, iso8859-1, mbcs (Windows only), ascii, us-ascii, utf-16, " -"utf16, utf-32, utf32, and the same using underscores instead of dashes. " -"Using alternative aliases for these encodings may result in slower execution." -msgstr "" - -#: ../../library/codecs.rst:1097 -msgid "Optimization opportunity recognized for us-ascii." -msgstr "" - -#: ../../library/codecs.rst:1100 -msgid "" -"Many of the character sets support the same languages. They vary in " -"individual characters (e.g. whether the EURO SIGN is supported or not), and " -"in the assignment of characters to code positions. For the European " -"languages in particular, the following variants typically exist:" -msgstr "" - -#: ../../library/codecs.rst:1105 -msgid "an ISO 8859 codeset" -msgstr "" - -#: ../../library/codecs.rst:1107 -msgid "" -"a Microsoft Windows code page, which is typically derived from an 8859 " -"codeset, but replaces control characters with additional graphic characters" -msgstr "" - -#: ../../library/codecs.rst:1110 -msgid "an IBM EBCDIC code page" -msgstr "" - -#: ../../library/codecs.rst:1112 -msgid "an IBM PC code page, which is ASCII compatible" -msgstr "" - -#: ../../library/codecs.rst:1117 ../../library/codecs.rst:1376 -#: ../../library/codecs.rst:1448 ../../library/codecs.rst:1533 -msgid "Codec" -msgstr "" - -#: ../../library/codecs.rst:1117 ../../library/codecs.rst:1376 -#: ../../library/codecs.rst:1448 ../../library/codecs.rst:1533 -msgid "Aliases" -msgstr "" - -#: ../../library/codecs.rst:1117 -msgid "Languages" -msgstr "語言" - -#: ../../library/codecs.rst:1119 -msgid "ascii" -msgstr "ascii" - -#: ../../library/codecs.rst:1119 -msgid "646, us-ascii" -msgstr "646, us-ascii" - -#: ../../library/codecs.rst:1119 ../../library/codecs.rst:1125 -#: ../../library/codecs.rst:1133 -msgid "English" -msgstr "英文" - -#: ../../library/codecs.rst:1121 -msgid "big5" -msgstr "big5" - -#: ../../library/codecs.rst:1121 -msgid "big5-tw, csbig5" -msgstr "big5-tw, csbig5" - -#: ../../library/codecs.rst:1121 ../../library/codecs.rst:1123 -#: ../../library/codecs.rst:1182 -msgid "Traditional Chinese" -msgstr "繁體中文" - -#: ../../library/codecs.rst:1123 -msgid "big5hkscs" -msgstr "big5hkscs" - -#: ../../library/codecs.rst:1123 -msgid "big5-hkscs, hkscs" -msgstr "big5-hkscs, hkscs" - -#: ../../library/codecs.rst:1125 -msgid "cp037" -msgstr "cp037" - -#: ../../library/codecs.rst:1125 -msgid "IBM037, IBM039" -msgstr "IBM037, IBM039" - -#: ../../library/codecs.rst:1127 -msgid "cp273" -msgstr "cp273" - -#: ../../library/codecs.rst:1127 -msgid "273, IBM273, csIBM273" -msgstr "273, IBM273, csIBM273" - -#: ../../library/codecs.rst:1127 -msgid "German" -msgstr "德文" - -#: ../../library/codecs.rst:1131 -msgid "cp424" -msgstr "cp424" - -#: ../../library/codecs.rst:1131 -msgid "EBCDIC-CP-HE, IBM424" -msgstr "EBCDIC-CP-HE, IBM424" - -#: ../../library/codecs.rst:1131 ../../library/codecs.rst:1151 -#: ../../library/codecs.rst:1161 ../../library/codecs.rst:1205 -#: ../../library/codecs.rst:1268 -msgid "Hebrew" -msgstr "希伯來文" - -#: ../../library/codecs.rst:1133 -msgid "cp437" -msgstr "cp437" - -#: ../../library/codecs.rst:1133 -msgid "437, IBM437" -msgstr "437, IBM437" - -#: ../../library/codecs.rst:1135 -msgid "cp500" -msgstr "cp500" - -#: ../../library/codecs.rst:1135 -msgid "EBCDIC-CP-BE, EBCDIC-CP-CH, IBM500" -msgstr "EBCDIC-CP-BE, EBCDIC-CP-CH, IBM500" - -#: ../../library/codecs.rst:1135 ../../library/codecs.rst:1144 -#: ../../library/codecs.rst:1155 ../../library/codecs.rst:1192 -#: ../../library/codecs.rst:1199 ../../library/codecs.rst:1252 -#: ../../library/codecs.rst:1280 ../../library/codecs.rst:1308 -msgid "Western Europe" -msgstr "" - -#: ../../library/codecs.rst:1138 -msgid "cp720" -msgstr "cp720" - -#: ../../library/codecs.rst:1138 ../../library/codecs.rst:1165 -#: ../../library/codecs.rst:1207 ../../library/codecs.rst:1264 -msgid "Arabic" -msgstr "阿拉伯文" - -#: ../../library/codecs.rst:1140 -msgid "cp737" -msgstr "cp737" - -#: ../../library/codecs.rst:1140 ../../library/codecs.rst:1171 -#: ../../library/codecs.rst:1175 ../../library/codecs.rst:1201 -#: ../../library/codecs.rst:1266 ../../library/codecs.rst:1301 -msgid "Greek" -msgstr "希臘文" - -#: ../../library/codecs.rst:1142 -msgid "cp775" -msgstr "cp775" - -#: ../../library/codecs.rst:1142 -msgid "IBM775" -msgstr "IBM775" - -#: ../../library/codecs.rst:1142 ../../library/codecs.rst:1209 -#: ../../library/codecs.rst:1276 -msgid "Baltic languages" -msgstr "" - -#: ../../library/codecs.rst:1144 -msgid "cp850" -msgstr "cp850" - -#: ../../library/codecs.rst:1144 -msgid "850, IBM850" -msgstr "850, IBM850" - -#: ../../library/codecs.rst:1146 -msgid "cp852" -msgstr "cp852" - -#: ../../library/codecs.rst:1146 -msgid "852, IBM852" -msgstr "852, IBM852" - -#: ../../library/codecs.rst:1146 ../../library/codecs.rst:1194 -#: ../../library/codecs.rst:1255 ../../library/codecs.rst:1305 -msgid "Central and Eastern Europe" -msgstr "" - -#: ../../library/codecs.rst:1148 -msgid "cp855" -msgstr "cp855" - -#: ../../library/codecs.rst:1148 -msgid "855, IBM855" -msgstr "855, IBM855" - -#: ../../library/codecs.rst:1148 ../../library/codecs.rst:1196 -#: ../../library/codecs.rst:1261 ../../library/codecs.rst:1298 -msgid "Belarusian, Bulgarian, Macedonian, Russian, Serbian" -msgstr "" - -#: ../../library/codecs.rst:1151 -msgid "cp856" -msgstr "cp856" - -#: ../../library/codecs.rst:1153 -msgid "cp857" -msgstr "cp857" - -#: ../../library/codecs.rst:1153 -msgid "857, IBM857" -msgstr "857, IBM857" - -#: ../../library/codecs.rst:1153 ../../library/codecs.rst:1186 -#: ../../library/codecs.rst:1203 ../../library/codecs.rst:1270 -#: ../../library/codecs.rst:1310 -msgid "Turkish" -msgstr "土耳其文" - -#: ../../library/codecs.rst:1155 -msgid "cp858" -msgstr "cp858" - -#: ../../library/codecs.rst:1155 -msgid "858, IBM858" -msgstr "858, IBM858" - -#: ../../library/codecs.rst:1157 -msgid "cp860" -msgstr "cp860" - -#: ../../library/codecs.rst:1157 -msgid "860, IBM860" -msgstr "860, IBM860" - -#: ../../library/codecs.rst:1157 -msgid "Portuguese" -msgstr "" - -#: ../../library/codecs.rst:1159 -msgid "cp861" -msgstr "cp861" - -#: ../../library/codecs.rst:1159 -msgid "861, CP-IS, IBM861" -msgstr "861, CP-IS, IBM861" - -#: ../../library/codecs.rst:1159 ../../library/codecs.rst:1303 -msgid "Icelandic" -msgstr "" - -#: ../../library/codecs.rst:1161 -msgid "cp862" -msgstr "cp862" - -#: ../../library/codecs.rst:1161 -msgid "862, IBM862" -msgstr "862, IBM862" - -#: ../../library/codecs.rst:1163 -msgid "cp863" -msgstr "cp863" - -#: ../../library/codecs.rst:1163 -msgid "863, IBM863" -msgstr "863, IBM863" - -#: ../../library/codecs.rst:1163 -msgid "Canadian" -msgstr "" - -#: ../../library/codecs.rst:1165 -msgid "cp864" -msgstr "cp864" - -#: ../../library/codecs.rst:1165 -msgid "IBM864" -msgstr "IBM864" - -#: ../../library/codecs.rst:1167 -msgid "cp865" -msgstr "cp865" - -#: ../../library/codecs.rst:1167 -msgid "865, IBM865" -msgstr "865, IBM865" - -#: ../../library/codecs.rst:1167 -msgid "Danish, Norwegian" -msgstr "" - -#: ../../library/codecs.rst:1169 -msgid "cp866" -msgstr "cp866" - -#: ../../library/codecs.rst:1169 -msgid "866, IBM866" -msgstr "866, IBM866" - -#: ../../library/codecs.rst:1169 ../../library/codecs.rst:1286 -msgid "Russian" -msgstr "俄羅斯文" - -#: ../../library/codecs.rst:1171 -msgid "cp869" -msgstr "cp869" - -#: ../../library/codecs.rst:1171 -msgid "869, CP-GR, IBM869" -msgstr "869, CP-GR, IBM869" - -#: ../../library/codecs.rst:1173 -msgid "cp874" -msgstr "cp874" - -#: ../../library/codecs.rst:1173 -msgid "Thai" -msgstr "泰文" - -#: ../../library/codecs.rst:1175 -msgid "cp875" -msgstr "cp875" - -#: ../../library/codecs.rst:1177 -msgid "cp932" -msgstr "cp932" - -#: ../../library/codecs.rst:1177 -msgid "932, ms932, mskanji, ms-kanji, windows-31j" -msgstr "932, ms932, mskanji, ms-kanji, windows-31j" - -#: ../../library/codecs.rst:1177 ../../library/codecs.rst:1213 -#: ../../library/codecs.rst:1215 ../../library/codecs.rst:1217 -#: ../../library/codecs.rst:1234 ../../library/codecs.rst:1237 -#: ../../library/codecs.rst:1242 ../../library/codecs.rst:1245 -#: ../../library/codecs.rst:1247 ../../library/codecs.rst:1315 -#: ../../library/codecs.rst:1318 ../../library/codecs.rst:1321 -msgid "Japanese" -msgstr "日文" - -#: ../../library/codecs.rst:1180 -msgid "cp949" -msgstr "cp949" - -#: ../../library/codecs.rst:1180 -msgid "949, ms949, uhc" -msgstr "949, ms949, uhc" - -#: ../../library/codecs.rst:1180 ../../library/codecs.rst:1219 -#: ../../library/codecs.rst:1249 ../../library/codecs.rst:1284 -msgid "Korean" -msgstr "韓文" - -#: ../../library/codecs.rst:1182 -msgid "cp950" -msgstr "cp950" - -#: ../../library/codecs.rst:1182 -msgid "950, ms950" -msgstr "950, ms950" - -#: ../../library/codecs.rst:1184 -msgid "cp1006" -msgstr "cp1006" - -#: ../../library/codecs.rst:1184 -msgid "Urdu" -msgstr "" - -#: ../../library/codecs.rst:1186 -msgid "cp1026" -msgstr "cp1026" - -#: ../../library/codecs.rst:1186 -msgid "ibm1026" -msgstr "ibm1026" - -#: ../../library/codecs.rst:1188 -msgid "cp1125" -msgstr "cp1125" - -#: ../../library/codecs.rst:1188 -msgid "1125, ibm1125, cp866u, ruscii" -msgstr "1125, ibm1125, cp866u, ruscii" - -#: ../../library/codecs.rst:1188 ../../library/codecs.rst:1292 -msgid "Ukrainian" -msgstr "烏克蘭文" - -#: ../../library/codecs.rst:1192 -msgid "cp1140" -msgstr "cp1140" - -#: ../../library/codecs.rst:1192 -msgid "ibm1140" -msgstr "ibm1140" - -#: ../../library/codecs.rst:1194 -msgid "cp1250" -msgstr "cp1250" - -#: ../../library/codecs.rst:1194 -msgid "windows-1250" -msgstr "windows-1250" - -#: ../../library/codecs.rst:1196 -msgid "cp1251" -msgstr "cp1251" - -#: ../../library/codecs.rst:1196 -msgid "windows-1251" -msgstr "windows-1251" - -#: ../../library/codecs.rst:1199 -msgid "cp1252" -msgstr "cp1252" - -#: ../../library/codecs.rst:1199 -msgid "windows-1252" -msgstr "windows-1252" - -#: ../../library/codecs.rst:1201 -msgid "cp1253" -msgstr "cp1253" - -#: ../../library/codecs.rst:1201 -msgid "windows-1253" -msgstr "windows-1253" - -#: ../../library/codecs.rst:1203 -msgid "cp1254" -msgstr "cp1254" - -#: ../../library/codecs.rst:1203 -msgid "windows-1254" -msgstr "windows-1254" - -#: ../../library/codecs.rst:1205 -msgid "cp1255" -msgstr "cp1255" - -#: ../../library/codecs.rst:1205 -msgid "windows-1255" -msgstr "windows-1255" - -#: ../../library/codecs.rst:1207 -msgid "cp1256" -msgstr "cp1256" - -#: ../../library/codecs.rst:1207 -msgid "windows-1256" -msgstr "windows-1256" - -#: ../../library/codecs.rst:1209 -msgid "cp1257" -msgstr "cp1257" - -#: ../../library/codecs.rst:1209 -msgid "windows-1257" -msgstr "windows-1257" - -#: ../../library/codecs.rst:1211 -msgid "cp1258" -msgstr "cp1258" - -#: ../../library/codecs.rst:1211 -msgid "windows-1258" -msgstr "windows-1258" - -#: ../../library/codecs.rst:1211 -msgid "Vietnamese" -msgstr "越南文" - -#: ../../library/codecs.rst:1213 -msgid "euc_jp" -msgstr "euc_jp" - -#: ../../library/codecs.rst:1213 -msgid "eucjp, ujis, u-jis" -msgstr "eucjp, ujis, u-jis" - -#: ../../library/codecs.rst:1215 -msgid "euc_jis_2004" -msgstr "euc_jis_2004" - -#: ../../library/codecs.rst:1215 -msgid "jisx0213, eucjis2004" -msgstr "jisx0213, eucjis2004" - -#: ../../library/codecs.rst:1217 -msgid "euc_jisx0213" -msgstr "euc_jisx0213" - -#: ../../library/codecs.rst:1217 -msgid "eucjisx0213" -msgstr "eucjisx0213" - -#: ../../library/codecs.rst:1219 -msgid "euc_kr" -msgstr "euc_kr" - -#: ../../library/codecs.rst:1219 -msgid "euckr, korean, ksc5601, ks_c-5601, ks_c-5601-1987, ksx1001, ks_x-1001" -msgstr "euckr, korean, ksc5601, ks_c-5601, ks_c-5601-1987, ksx1001, ks_x-1001" - -#: ../../library/codecs.rst:1223 -msgid "gb2312" -msgstr "gb2312" - -#: ../../library/codecs.rst:1223 -msgid "" -"chinese, csiso58gb231280, euc-cn, euccn, eucgb2312-cn, gb2312-1980, " -"gb2312-80, iso-ir-58" -msgstr "" -"chinese, csiso58gb231280, euc-cn, euccn, eucgb2312-cn, gb2312-1980, " -"gb2312-80, iso-ir-58" - -#: ../../library/codecs.rst:1223 ../../library/codecs.rst:1232 -msgid "Simplified Chinese" -msgstr "簡體中文" - -#: ../../library/codecs.rst:1228 -msgid "gbk" -msgstr "gbk" - -#: ../../library/codecs.rst:1228 -msgid "936, cp936, ms936" -msgstr "936, cp936, ms936" - -#: ../../library/codecs.rst:1228 ../../library/codecs.rst:1230 -msgid "Unified Chinese" -msgstr "" - -#: ../../library/codecs.rst:1230 -msgid "gb18030" -msgstr "gb18030" - -#: ../../library/codecs.rst:1230 -msgid "gb18030-2000" -msgstr "gb18030-2000" - -#: ../../library/codecs.rst:1232 -msgid "hz" -msgstr "hz" - -#: ../../library/codecs.rst:1232 -msgid "hzgb, hz-gb, hz-gb-2312" -msgstr "hzgb, hz-gb, hz-gb-2312" - -#: ../../library/codecs.rst:1234 -msgid "iso2022_jp" -msgstr "iso2022_jp" - -#: ../../library/codecs.rst:1234 -msgid "csiso2022jp, iso2022jp, iso-2022-jp" -msgstr "csiso2022jp, iso2022jp, iso-2022-jp" - -#: ../../library/codecs.rst:1237 -msgid "iso2022_jp_1" -msgstr "iso2022_jp_1" - -#: ../../library/codecs.rst:1237 -msgid "iso2022jp-1, iso-2022-jp-1" -msgstr "iso2022jp-1, iso-2022-jp-1" - -#: ../../library/codecs.rst:1239 -msgid "iso2022_jp_2" -msgstr "iso2022_jp_2" - -#: ../../library/codecs.rst:1239 -msgid "iso2022jp-2, iso-2022-jp-2" -msgstr "iso2022jp-2, iso-2022-jp-2" - -#: ../../library/codecs.rst:1239 -msgid "Japanese, Korean, Simplified Chinese, Western Europe, Greek" -msgstr "" - -#: ../../library/codecs.rst:1242 -msgid "iso2022_jp_2004" -msgstr "iso2022_jp_2004" - -#: ../../library/codecs.rst:1242 -msgid "iso2022jp-2004, iso-2022-jp-2004" -msgstr "iso2022jp-2004, iso-2022-jp-2004" - -#: ../../library/codecs.rst:1245 -msgid "iso2022_jp_3" -msgstr "iso2022_jp_3" - -#: ../../library/codecs.rst:1245 -msgid "iso2022jp-3, iso-2022-jp-3" -msgstr "iso2022jp-3, iso-2022-jp-3" - -#: ../../library/codecs.rst:1247 -msgid "iso2022_jp_ext" -msgstr "iso2022_jp_ext" - -#: ../../library/codecs.rst:1247 -msgid "iso2022jp-ext, iso-2022-jp-ext" -msgstr "iso2022jp-ext, iso-2022-jp-ext" - -#: ../../library/codecs.rst:1249 -msgid "iso2022_kr" -msgstr "iso2022_kr" - -#: ../../library/codecs.rst:1249 -msgid "csiso2022kr, iso2022kr, iso-2022-kr" -msgstr "csiso2022kr, iso2022kr, iso-2022-kr" - -#: ../../library/codecs.rst:1252 -msgid "latin_1" -msgstr "latin_1" - -#: ../../library/codecs.rst:1252 -msgid "iso-8859-1, iso8859-1, 8859, cp819, latin, latin1, L1" -msgstr "iso-8859-1, iso8859-1, 8859, cp819, latin, latin1, L1" - -#: ../../library/codecs.rst:1255 -msgid "iso8859_2" -msgstr "iso8859_2" - -#: ../../library/codecs.rst:1255 -msgid "iso-8859-2, latin2, L2" -msgstr "iso-8859-2, latin2, L2" - -#: ../../library/codecs.rst:1257 -msgid "iso8859_3" -msgstr "iso8859_3" - -#: ../../library/codecs.rst:1257 -msgid "iso-8859-3, latin3, L3" -msgstr "iso-8859-3, latin3, L3" - -#: ../../library/codecs.rst:1257 -msgid "Esperanto, Maltese" -msgstr "" - -#: ../../library/codecs.rst:1259 -msgid "iso8859_4" -msgstr "iso8859_4" - -#: ../../library/codecs.rst:1259 -msgid "iso-8859-4, latin4, L4" -msgstr "iso-8859-4, latin4, L4" - -#: ../../library/codecs.rst:1259 -msgid "Northern Europe" -msgstr "" - -#: ../../library/codecs.rst:1261 -msgid "iso8859_5" -msgstr "iso8859_5" - -#: ../../library/codecs.rst:1261 -msgid "iso-8859-5, cyrillic" -msgstr "iso-8859-5, cyrillic" - -#: ../../library/codecs.rst:1264 -msgid "iso8859_6" -msgstr "iso8859_6" - -#: ../../library/codecs.rst:1264 -msgid "iso-8859-6, arabic" -msgstr "iso-8859-6, arabic" - -#: ../../library/codecs.rst:1266 -msgid "iso8859_7" -msgstr "iso8859_7" - -#: ../../library/codecs.rst:1266 -msgid "iso-8859-7, greek, greek8" -msgstr "iso-8859-7, greek, greek8" - -#: ../../library/codecs.rst:1268 -msgid "iso8859_8" -msgstr "iso8859_8" - -#: ../../library/codecs.rst:1268 -msgid "iso-8859-8, hebrew" -msgstr "iso-8859-8, hebrew" - -#: ../../library/codecs.rst:1270 -msgid "iso8859_9" -msgstr "iso8859_9" - -#: ../../library/codecs.rst:1270 -msgid "iso-8859-9, latin5, L5" -msgstr "iso-8859-9, latin5, L5" - -#: ../../library/codecs.rst:1272 -msgid "iso8859_10" -msgstr "iso8859_10" - -#: ../../library/codecs.rst:1272 -msgid "iso-8859-10, latin6, L6" -msgstr "iso-8859-10, latin6, L6" - -#: ../../library/codecs.rst:1272 -msgid "Nordic languages" -msgstr "" - -#: ../../library/codecs.rst:1274 -msgid "iso8859_11" -msgstr "iso8859_11" - -#: ../../library/codecs.rst:1274 -msgid "iso-8859-11, thai" -msgstr "iso-8859-11, thai" - -#: ../../library/codecs.rst:1274 -msgid "Thai languages" -msgstr "泰語" - -#: ../../library/codecs.rst:1276 -msgid "iso8859_13" -msgstr "iso8859_13" - -#: ../../library/codecs.rst:1276 -msgid "iso-8859-13, latin7, L7" -msgstr "iso-8859-13, latin7, L7" - -#: ../../library/codecs.rst:1278 -msgid "iso8859_14" -msgstr "iso8859_14" - -#: ../../library/codecs.rst:1278 -msgid "iso-8859-14, latin8, L8" -msgstr "iso-8859-14, latin8, L8" - -#: ../../library/codecs.rst:1278 -msgid "Celtic languages" -msgstr "" - -#: ../../library/codecs.rst:1280 -msgid "iso8859_15" -msgstr "iso8859_15" - -#: ../../library/codecs.rst:1280 -msgid "iso-8859-15, latin9, L9" -msgstr "iso-8859-15, latin9, L9" - -#: ../../library/codecs.rst:1282 -msgid "iso8859_16" -msgstr "iso8859_16" - -#: ../../library/codecs.rst:1282 -msgid "iso-8859-16, latin10, L10" -msgstr "iso-8859-16, latin10, L10" - -#: ../../library/codecs.rst:1282 -msgid "South-Eastern Europe" -msgstr "" - -#: ../../library/codecs.rst:1284 -msgid "johab" -msgstr "" - -#: ../../library/codecs.rst:1284 -msgid "cp1361, ms1361" -msgstr "cp1361, ms1361" - -#: ../../library/codecs.rst:1286 -msgid "koi8_r" -msgstr "koi8_r" - -#: ../../library/codecs.rst:1288 -msgid "koi8_t" -msgstr "koi8_t" - -#: ../../library/codecs.rst:1288 -msgid "Tajik" -msgstr "" - -#: ../../library/codecs.rst:1292 -msgid "koi8_u" -msgstr "koi8_u" - -#: ../../library/codecs.rst:1294 -msgid "kz1048" -msgstr "kz1048" - -#: ../../library/codecs.rst:1294 -msgid "kz_1048, strk1048_2002, rk1048" -msgstr "kz_1048, strk1048_2002, rk1048" - -#: ../../library/codecs.rst:1294 ../../library/codecs.rst:1312 -msgid "Kazakh" -msgstr "" - -#: ../../library/codecs.rst:1298 -msgid "mac_cyrillic" -msgstr "mac_cyrillic" - -#: ../../library/codecs.rst:1298 -msgid "maccyrillic" -msgstr "" - -#: ../../library/codecs.rst:1301 -msgid "mac_greek" -msgstr "mac_greek" - -#: ../../library/codecs.rst:1301 -msgid "macgreek" -msgstr "" - -#: ../../library/codecs.rst:1303 -msgid "mac_iceland" -msgstr "mac_iceland" - -#: ../../library/codecs.rst:1303 -msgid "maciceland" -msgstr "" - -#: ../../library/codecs.rst:1305 -msgid "mac_latin2" -msgstr "mac_latin2" - -#: ../../library/codecs.rst:1305 -msgid "maclatin2, maccentraleurope, mac_centeuro" -msgstr "maclatin2, maccentraleurope, mac_centeuro" - -#: ../../library/codecs.rst:1308 -msgid "mac_roman" -msgstr "mac_roman" - -#: ../../library/codecs.rst:1308 -msgid "macroman, macintosh" -msgstr "macroman, macintosh" - -#: ../../library/codecs.rst:1310 -msgid "mac_turkish" -msgstr "mac_turkish" - -#: ../../library/codecs.rst:1310 -msgid "macturkish" -msgstr "" - -#: ../../library/codecs.rst:1312 -msgid "ptcp154" -msgstr "ptcp154" - -#: ../../library/codecs.rst:1312 -msgid "csptcp154, pt154, cp154, cyrillic-asian" -msgstr "csptcp154, pt154, cp154, cyrillic-asian" - -#: ../../library/codecs.rst:1315 -msgid "shift_jis" -msgstr "shift_jis" - -#: ../../library/codecs.rst:1315 -msgid "csshiftjis, shiftjis, sjis, s_jis" -msgstr "csshiftjis, shiftjis, sjis, s_jis" - -#: ../../library/codecs.rst:1318 -msgid "shift_jis_2004" -msgstr "shift_jis_2004" - -#: ../../library/codecs.rst:1318 -msgid "shiftjis2004, sjis_2004, sjis2004" -msgstr "shiftjis2004, sjis_2004, sjis2004" - -#: ../../library/codecs.rst:1321 -msgid "shift_jisx0213" -msgstr "shift_jisx0213" - -#: ../../library/codecs.rst:1321 -msgid "shiftjisx0213, sjisx0213, s_jisx0213" -msgstr "shiftjisx0213, sjisx0213, s_jisx0213" - -#: ../../library/codecs.rst:1324 -msgid "utf_32" -msgstr "utf_32" - -#: ../../library/codecs.rst:1324 -msgid "U32, utf32" -msgstr "U32, utf32" - -#: ../../library/codecs.rst:1324 ../../library/codecs.rst:1326 -#: ../../library/codecs.rst:1328 ../../library/codecs.rst:1330 -#: ../../library/codecs.rst:1332 ../../library/codecs.rst:1334 -#: ../../library/codecs.rst:1336 ../../library/codecs.rst:1338 -#: ../../library/codecs.rst:1340 -msgid "all languages" -msgstr "" - -#: ../../library/codecs.rst:1326 -msgid "utf_32_be" -msgstr "utf_32_be" - -#: ../../library/codecs.rst:1326 -msgid "UTF-32BE" -msgstr "UTF-32BE" - -#: ../../library/codecs.rst:1328 -msgid "utf_32_le" -msgstr "utf_32_le" - -#: ../../library/codecs.rst:1328 -msgid "UTF-32LE" -msgstr "UTF-32LE" - -#: ../../library/codecs.rst:1330 -msgid "utf_16" -msgstr "utf_16" - -#: ../../library/codecs.rst:1330 -msgid "U16, utf16" -msgstr "U16, utf16" - -#: ../../library/codecs.rst:1332 -msgid "utf_16_be" -msgstr "utf_16_be" - -#: ../../library/codecs.rst:1332 -msgid "UTF-16BE" -msgstr "UTF-16BE" - -#: ../../library/codecs.rst:1334 -msgid "utf_16_le" -msgstr "utf_16_le" - -#: ../../library/codecs.rst:1334 -msgid "UTF-16LE" -msgstr "UTF-16LE" - -#: ../../library/codecs.rst:1336 -msgid "utf_7" -msgstr "utf_7" - -#: ../../library/codecs.rst:1336 -msgid "U7, unicode-1-1-utf-7" -msgstr "U7, unicode-1-1-utf-7" - -#: ../../library/codecs.rst:1338 -msgid "utf_8" -msgstr "utf_8" - -#: ../../library/codecs.rst:1338 -msgid "U8, UTF, utf8, cp65001" -msgstr "U8, UTF, utf8, cp65001" - -#: ../../library/codecs.rst:1340 -msgid "utf_8_sig" -msgstr "utf_8_sig" - -#: ../../library/codecs.rst:1343 -msgid "" -"The utf-16\\* and utf-32\\* encoders no longer allow surrogate code points " -"(``U+D800``--``U+DFFF``) to be encoded. The utf-32\\* decoders no longer " -"decode byte sequences that correspond to surrogate code points." -msgstr "" - -#: ../../library/codecs.rst:1349 -msgid "``cp65001`` is now an alias to ``utf_8``." -msgstr "``cp65001`` 現在是 ``utf_8`` 的別名。" - -#: ../../library/codecs.rst:1352 -msgid "On Windows, ``cpXXX`` codecs are now available for all code pages." -msgstr "" - -#: ../../library/codecs.rst:1357 -msgid "Python Specific Encodings" -msgstr "" - -#: ../../library/codecs.rst:1359 -msgid "" -"A number of predefined codecs are specific to Python, so their codec names " -"have no meaning outside Python. These are listed in the tables below based " -"on the expected input and output types (note that while text encodings are " -"the most common use case for codecs, the underlying codec infrastructure " -"supports arbitrary data transforms rather than just text encodings). For " -"asymmetric codecs, the stated meaning describes the encoding direction." -msgstr "" - -#: ../../library/codecs.rst:1367 -msgid "Text Encodings" -msgstr "" - -#: ../../library/codecs.rst:1369 -msgid "" -"The following codecs provide :class:`str` to :class:`bytes` encoding and :" -"term:`bytes-like object` to :class:`str` decoding, similar to the Unicode " -"text encodings." -msgstr "" - -#: ../../library/codecs.rst:1378 -msgid "idna" -msgstr "idna" - -#: ../../library/codecs.rst:1378 -msgid "" -"Implement :rfc:`3490`, see also :mod:`encodings.idna`. Only " -"``errors='strict'`` is supported." -msgstr "" - -#: ../../library/codecs.rst:1384 -msgid "mbcs" -msgstr "mbcs" - -#: ../../library/codecs.rst:1384 -msgid "ansi, dbcs" -msgstr "ansi, dbcs" - -#: ../../library/codecs.rst:1384 -msgid "" -"Windows only: Encode the operand according to the ANSI codepage (CP_ACP)." -msgstr "" - -#: ../../library/codecs.rst:1388 -msgid "oem" -msgstr "oem" - -#: ../../library/codecs.rst:1388 -msgid "" -"Windows only: Encode the operand according to the OEM codepage (CP_OEMCP)." -msgstr "" - -#: ../../library/codecs.rst:1394 -msgid "palmos" -msgstr "" - -#: ../../library/codecs.rst:1394 -msgid "Encoding of PalmOS 3.5." -msgstr "" - -#: ../../library/codecs.rst:1396 -msgid "punycode" -msgstr "" - -#: ../../library/codecs.rst:1396 -msgid "Implement :rfc:`3492`. Stateful codecs are not supported." -msgstr "" - -#: ../../library/codecs.rst:1400 -msgid "raw_unicode_escape" -msgstr "raw_unicode_escape" - -#: ../../library/codecs.rst:1400 -msgid "" -"Latin-1 encoding with :samp:`\\\\u{XXXX}` and :samp:`\\\\U{XXXXXXXX}` for " -"other code points. Existing backslashes are not escaped in any way. It is " -"used in the Python pickle protocol." -msgstr "" - -#: ../../library/codecs.rst:1410 -msgid "undefined" -msgstr "" - -#: ../../library/codecs.rst:1410 -msgid "This Codec should only be used for testing purposes." -msgstr "" - -#: ../../library/codecs.rst:1414 -msgid "" -"Raise an exception for all conversions, even empty strings. The error " -"handler is ignored." -msgstr "" - -#: ../../library/codecs.rst:1419 -msgid "unicode_escape" -msgstr "unicode_escape" - -#: ../../library/codecs.rst:1419 -msgid "" -"Encoding suitable as the contents of a Unicode literal in ASCII-encoded " -"Python source code, except that quotes are not escaped. Decode from Latin-1 " -"source code. Beware that Python source code actually uses UTF-8 by default." -msgstr "" - -#: ../../library/codecs.rst:1431 -msgid "\"unicode_internal\" codec is removed." -msgstr "" - -#: ../../library/codecs.rst:1438 -msgid "Binary Transforms" -msgstr "" - -#: ../../library/codecs.rst:1440 -msgid "" -"The following codecs provide binary transforms: :term:`bytes-like object` " -"to :class:`bytes` mappings. They are not supported by :meth:`bytes.decode` " -"(which only produces :class:`str` output)." -msgstr "" - -#: ../../library/codecs.rst:1448 -msgid "Encoder / decoder" -msgstr "" - -#: ../../library/codecs.rst:1450 -msgid "base64_codec [#b64]_" -msgstr "base64_codec [#b64]_" - -#: ../../library/codecs.rst:1450 -msgid "base64, base_64" -msgstr "base64, base_64" - -#: ../../library/codecs.rst:1450 -msgid "" -"Convert the operand to multiline MIME base64 (the result always includes a " -"trailing ``'\\n'``)." -msgstr "" - -#: ../../library/codecs.rst:1455 -msgid "" -"accepts any :term:`bytes-like object` as input for encoding and decoding" -msgstr "" - -#: ../../library/codecs.rst:1450 -msgid ":meth:`base64.encodebytes` / :meth:`base64.decodebytes`" -msgstr ":meth:`base64.encodebytes` / :meth:`base64.decodebytes`" - -#: ../../library/codecs.rst:1461 -msgid "bz2_codec" -msgstr "bz2_codec" - -#: ../../library/codecs.rst:1461 -msgid "bz2" -msgstr "bz2" - -#: ../../library/codecs.rst:1461 -msgid "Compress the operand using bz2." -msgstr "" - -#: ../../library/codecs.rst:1461 -msgid ":meth:`bz2.compress` / :meth:`bz2.decompress`" -msgstr ":meth:`bz2.compress` / :meth:`bz2.decompress`" - -#: ../../library/codecs.rst:1464 -msgid "hex_codec" -msgstr "hex_codec" - -#: ../../library/codecs.rst:1464 -msgid "hex" -msgstr "hex" - -#: ../../library/codecs.rst:1464 -msgid "" -"Convert the operand to hexadecimal representation, with two digits per byte." -msgstr "" - -#: ../../library/codecs.rst:1464 -msgid ":meth:`binascii.b2a_hex` / :meth:`binascii.a2b_hex`" -msgstr ":meth:`binascii.b2a_hex` / :meth:`binascii.a2b_hex`" - -#: ../../library/codecs.rst:1469 -msgid "quopri_codec" -msgstr "quopri_codec" - -#: ../../library/codecs.rst:1469 -msgid "quopri, quotedprintable, quoted_printable" -msgstr "quopri, quotedprintable, quoted_printable" - -#: ../../library/codecs.rst:1469 -msgid "Convert the operand to MIME quoted printable." -msgstr "" - -#: ../../library/codecs.rst:1469 -msgid ":meth:`quopri.encode` with ``quotetabs=True`` / :meth:`quopri.decode`" -msgstr ":meth:`quopri.encode` with ``quotetabs=True`` / :meth:`quopri.decode`" - -#: ../../library/codecs.rst:1473 -msgid "uu_codec" -msgstr "uu_codec" - -#: ../../library/codecs.rst:1473 -msgid "uu" -msgstr "uu" - -#: ../../library/codecs.rst:1473 -msgid "Convert the operand using uuencode." -msgstr "" - -#: ../../library/codecs.rst:1476 -msgid "zlib_codec" -msgstr "zlib_codec" - -#: ../../library/codecs.rst:1476 -msgid "zip, zlib" -msgstr "zip, zlib" - -#: ../../library/codecs.rst:1476 -msgid "Compress the operand using gzip." -msgstr "" - -#: ../../library/codecs.rst:1476 -msgid ":meth:`zlib.compress` / :meth:`zlib.decompress`" -msgstr ":meth:`zlib.compress` / :meth:`zlib.decompress`" - -#: ../../library/codecs.rst:1480 -msgid "" -"In addition to :term:`bytes-like objects `, " -"``'base64_codec'`` also accepts ASCII-only instances of :class:`str` for " -"decoding" -msgstr "" - -#: ../../library/codecs.rst:1484 -msgid "Restoration of the binary transforms." -msgstr "" - -#: ../../library/codecs.rst:1487 -msgid "Restoration of the aliases for the binary transforms." -msgstr "" - -#: ../../library/codecs.rst:1494 -msgid "Standalone Codec Functions" -msgstr "" - -#: ../../library/codecs.rst:1496 -msgid "" -"The following functions provide encoding and decoding functionality similar " -"to codecs, but are not available as named codecs through :func:`codecs." -"encode` or :func:`codecs.decode`. They are used internally (for example, by :" -"mod:`pickle`) and behave similarly to the ``string_escape`` codec that was " -"removed in Python 3." -msgstr "" - -#: ../../library/codecs.rst:1503 -msgid "" -"Encode *input* using escape sequences. Similar to how :func:`repr` on bytes " -"produces escaped byte values." -msgstr "" - -#: ../../library/codecs.rst:1506 -msgid "*input* must be a :class:`bytes` object." -msgstr "" - -#: ../../library/codecs.rst:1508 ../../library/codecs.rst:1517 -msgid "" -"Returns a tuple ``(output, length)`` where *output* is a :class:`bytes` " -"object and *length* is the number of bytes consumed." -msgstr "" - -#: ../../library/codecs.rst:1513 -msgid "Decode *input* from escape sequences back to the original bytes." -msgstr "" - -#: ../../library/codecs.rst:1515 -msgid "*input* must be a :term:`bytes-like object`." -msgstr "*input* 必須是個 :term:`bytes-like object`。" - -#: ../../library/codecs.rst:1524 -msgid "Text Transforms" -msgstr "" - -#: ../../library/codecs.rst:1526 -msgid "" -"The following codec provides a text transform: a :class:`str` to :class:" -"`str` mapping. It is not supported by :meth:`str.encode` (which only " -"produces :class:`bytes` output)." -msgstr "" - -#: ../../library/codecs.rst:1535 -msgid "rot_13" -msgstr "rot_13" - -#: ../../library/codecs.rst:1535 -msgid "rot13" -msgstr "" - -#: ../../library/codecs.rst:1535 -msgid "Return the Caesar-cypher encryption of the operand." -msgstr "" - -#: ../../library/codecs.rst:1540 -msgid "Restoration of the ``rot_13`` text transform." -msgstr "" - -#: ../../library/codecs.rst:1543 -msgid "Restoration of the ``rot13`` alias." -msgstr "" - -#: ../../library/codecs.rst:1548 -msgid ":mod:`encodings` --- Encodings package" -msgstr "" - -#: ../../library/codecs.rst:1553 -msgid "This module implements the following functions:" -msgstr "" - -#: ../../library/codecs.rst:1557 -msgid "Normalize encoding name *encoding*." -msgstr "" - -#: ../../library/codecs.rst:1559 -msgid "" -"Normalization works as follows: all non-alphanumeric characters except the " -"dot used for Python package names are collapsed and replaced with a single " -"underscore, leading and trailing underscores are removed. For example, ``' " -"-;#'`` becomes ``'_'``." -msgstr "" - -#: ../../library/codecs.rst:1564 -msgid "Note that *encoding* should be ASCII only." -msgstr "" - -#: ../../library/codecs.rst:1568 -msgid "" -"The following functions should not be used directly, except for testing " -"purposes; :func:`codecs.lookup` should be used instead." -msgstr "" - -#: ../../library/codecs.rst:1574 -msgid "" -"Search for the codec module corresponding to the given encoding name " -"*encoding*." -msgstr "" - -#: ../../library/codecs.rst:1577 -msgid "" -"This function first normalizes the *encoding* using :func:" -"`normalize_encoding`, then looks for a corresponding alias. It attempts to " -"import a codec module from the encodings package using either the alias or " -"the normalized name. If the module is found and defines a valid " -"``getregentry()`` function that returns a :class:`codecs.CodecInfo` object, " -"the codec is cached and returned." -msgstr "" - -#: ../../library/codecs.rst:1584 -msgid "" -"If the codec module defines a ``getaliases()`` function any returned aliases " -"are registered for future use." -msgstr "" - -#: ../../library/codecs.rst:1590 -msgid "" -"Search for a Windows code page encoding *encoding* of the form ``cpXXXX``." -msgstr "" - -#: ../../library/codecs.rst:1592 -msgid "" -"If the code page is valid and supported, return a :class:`codecs.CodecInfo` " -"object for it." -msgstr "" - -#: ../../library/codecs.rst:1595 ../../library/codecs.rst:1681 -msgid "Availability" -msgstr "可用性" - -#: ../../library/codecs.rst:1600 -msgid "This module implements the following exception:" -msgstr "" - -#: ../../library/codecs.rst:1604 -msgid "Raised when a codec is invalid or incompatible." -msgstr "" - -#: ../../library/codecs.rst:1608 -msgid "" -":mod:`encodings.idna` --- Internationalized Domain Names in Applications" -msgstr "" - -#: ../../library/codecs.rst:1614 -msgid "" -"This module implements :rfc:`3490` (Internationalized Domain Names in " -"Applications) and :rfc:`3492` (Nameprep: A Stringprep Profile for " -"Internationalized Domain Names (IDN)). It builds upon the ``punycode`` " -"encoding and :mod:`stringprep`." -msgstr "" - -#: ../../library/codecs.rst:1619 -msgid "" -"If you need the IDNA 2008 standard from :rfc:`5891` and :rfc:`5895`, use the " -"third-party :pypi:`idna` module." -msgstr "" - -#: ../../library/codecs.rst:1622 -msgid "" -"These RFCs together define a protocol to support non-ASCII characters in " -"domain names. A domain name containing non-ASCII characters (such as ``www." -"Alliancefrançaise.nu``) is converted into an ASCII-compatible encoding (ACE, " -"such as ``www.xn--alliancefranaise-npb.nu``). The ACE form of the domain " -"name is then used in all places where arbitrary characters are not allowed " -"by the protocol, such as DNS queries, HTTP :mailheader:`Host` fields, and so " -"on. This conversion is carried out in the application; if possible invisible " -"to the user: The application should transparently convert Unicode domain " -"labels to IDNA on the wire, and convert back ACE labels to Unicode before " -"presenting them to the user." -msgstr "" - -#: ../../library/codecs.rst:1633 -msgid "" -"Python supports this conversion in several ways: the ``idna`` codec " -"performs conversion between Unicode and ACE, separating an input string into " -"labels based on the separator characters defined in :rfc:`section 3.1 of RFC " -"3490 <3490#section-3.1>` and converting each label to ACE as required, and " -"conversely separating an input byte string into labels based on the ``.`` " -"separator and converting any ACE labels found into unicode. Furthermore, " -"the :mod:`socket` module transparently converts Unicode host names to ACE, " -"so that applications need not be concerned about converting host names " -"themselves when they pass them to the socket module. On top of that, modules " -"that have host names as function parameters, such as :mod:`http.client` and :" -"mod:`ftplib`, accept Unicode host names (:mod:`http.client` then also " -"transparently sends an IDNA hostname in the :mailheader:`Host` field if it " -"sends that field at all)." -msgstr "" - -#: ../../library/codecs.rst:1646 -msgid "" -"When receiving host names from the wire (such as in reverse name lookup), no " -"automatic conversion to Unicode is performed: applications wishing to " -"present such host names to the user should decode them to Unicode." -msgstr "" - -#: ../../library/codecs.rst:1650 -msgid "" -"The module :mod:`encodings.idna` also implements the nameprep procedure, " -"which performs certain normalizations on host names, to achieve case-" -"insensitivity of international domain names, and to unify similar " -"characters. The nameprep functions can be used directly if desired." -msgstr "" - -#: ../../library/codecs.rst:1658 -msgid "" -"Return the nameprepped version of *label*. The implementation currently " -"assumes query strings, so ``AllowUnassigned`` is true." -msgstr "" - -#: ../../library/codecs.rst:1664 -msgid "" -"Convert a label to ASCII, as specified in :rfc:`3490`. ``UseSTD3ASCIIRules`` " -"is assumed to be false." -msgstr "" - -#: ../../library/codecs.rst:1670 -msgid "Convert a label to Unicode, as specified in :rfc:`3490`." -msgstr "" - -#: ../../library/codecs.rst:1674 -msgid ":mod:`encodings.mbcs` --- Windows ANSI codepage" -msgstr ":mod:`encodings.mbcs` --- Windows ANSI 碼頁" - -#: ../../library/codecs.rst:1679 -msgid "This module implements the ANSI codepage (CP_ACP)." -msgstr "這個模組實作了 ANSI 碼頁 (CP_ACP)。" - -#: ../../library/codecs.rst:1683 -msgid "" -"Before 3.2, the *errors* argument was ignored; ``'replace'`` was always used " -"to encode, and ``'ignore'`` to decode." -msgstr "" - -#: ../../library/codecs.rst:1687 -msgid "Support any error handler." -msgstr "" - -#: ../../library/codecs.rst:1692 -msgid ":mod:`encodings.utf_8_sig` --- UTF-8 codec with BOM signature" -msgstr "" - -#: ../../library/codecs.rst:1698 -msgid "" -"This module implements a variant of the UTF-8 codec. On encoding, a UTF-8 " -"encoded BOM will be prepended to the UTF-8 encoded bytes. For the stateful " -"encoder this is only done once (on the first write to the byte stream). On " -"decoding, an optional UTF-8 encoded BOM at the start of the data will be " -"skipped." -msgstr "" - -#: ../../library/codecs.rst:13 -msgid "Unicode" -msgstr "Unicode" - -#: ../../library/codecs.rst:13 -msgid "encode" -msgstr "encode（編碼）" - -#: ../../library/codecs.rst:13 -msgid "decode" -msgstr "decode（解碼）" - -#: ../../library/codecs.rst:13 -msgid "streams" -msgstr "streams（串流）" - -#: ../../library/codecs.rst:13 -msgid "stackable" -msgstr "stackable（可堆疊）" - -#: ../../library/codecs.rst:338 -msgid "strict" -msgstr "strict" - -#: ../../library/codecs.rst:338 ../../library/codecs.rst:390 -#: ../../library/codecs.rst:413 -msgid "error handler's name" -msgstr "error handler's name（錯誤處理器名稱）" - -#: ../../library/codecs.rst:338 -msgid "ignore" -msgstr "ignore" - -#: ../../library/codecs.rst:338 -msgid "replace" -msgstr "replace" - -#: ../../library/codecs.rst:338 -msgid "backslashreplace" -msgstr "backslashreplace" - -#: ../../library/codecs.rst:338 -msgid "surrogateescape" -msgstr "surrogateescape" - -#: ../../library/codecs.rst:338 -msgid "? (question mark)" -msgstr "? （問號）" - -#: ../../library/codecs.rst:338 -msgid "replacement character" -msgstr "replacement character（替代字元）" - -#: ../../library/codecs.rst:338 -msgid "\\ (backslash)" -msgstr "\\ （反斜線）" - -#: ../../library/codecs.rst:338 ../../library/codecs.rst:390 -msgid "escape sequence" -msgstr "escape sequence（跳脫序列）" - -#: ../../library/codecs.rst:338 -msgid "\\x" -msgstr "\\x" - -#: ../../library/codecs.rst:338 -msgid "\\u" -msgstr "\\u" - -#: ../../library/codecs.rst:338 -msgid "\\U" -msgstr "\\U" - -#: ../../library/codecs.rst:390 -msgid "xmlcharrefreplace" -msgstr "xmlcharrefreplace" - -#: ../../library/codecs.rst:390 -msgid "namereplace" -msgstr "namereplace" - -#: ../../library/codecs.rst:390 -msgid "\\N" -msgstr "\\N" - -#: ../../library/codecs.rst:413 -msgid "surrogatepass" -msgstr "surrogatepass" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-12-01 00:17+0000\n" +"PO-Revision-Date: 2018-05-23 14:40+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/codecs.rst:2 +msgid ":mod:`!codecs` --- Codec registry and base classes" +msgstr ":mod:`!codecs` --- 編解碼器註冊表和基底類別" + +#: ../../library/codecs.rst:11 +msgid "**Source code:** :source:`Lib/codecs.py`" +msgstr "**原始碼：**\\ :source:`Lib/codecs.py`" + +#: ../../library/codecs.rst:23 +msgid "" +"This module defines base classes for standard Python codecs (encoders and " +"decoders) and provides access to the internal Python codec registry, which " +"manages the codec and error handling lookup process. Most standard codecs " +"are :term:`text encodings `, which encode text to bytes (and " +"decode bytes to text), but there are also codecs provided that encode text " +"to text, and bytes to bytes. Custom codecs may encode and decode between " +"arbitrary types, but some module features are restricted to be used " +"specifically with :term:`text encodings ` or with codecs that " +"encode to :class:`bytes`." +msgstr "" + +#: ../../library/codecs.rst:33 +msgid "" +"The module defines the following functions for encoding and decoding with " +"any codec:" +msgstr "這個模組定義了以下函式，用於以任何編解碼器來編碼與解碼：" + +#: ../../library/codecs.rst:38 +msgid "Encodes *obj* using the codec registered for *encoding*." +msgstr "" + +#: ../../library/codecs.rst:40 +msgid "" +"*Errors* may be given to set the desired error handling scheme. The default " +"error handler is ``'strict'`` meaning that encoding errors raise :exc:" +"`ValueError` (or a more codec specific subclass, such as :exc:" +"`UnicodeEncodeError`). Refer to :ref:`codec-base-classes` for more " +"information on codec error handling." +msgstr "" + +#: ../../library/codecs.rst:48 +msgid "Decodes *obj* using the codec registered for *encoding*." +msgstr "" + +#: ../../library/codecs.rst:50 +msgid "" +"*Errors* may be given to set the desired error handling scheme. The default " +"error handler is ``'strict'`` meaning that decoding errors raise :exc:" +"`ValueError` (or a more codec specific subclass, such as :exc:" +"`UnicodeDecodeError`). Refer to :ref:`codec-base-classes` for more " +"information on codec error handling." +msgstr "" + +#: ../../library/codecs.rst:58 +msgid "" +"Return a mapping suitable for encoding with a custom single-byte encoding. " +"Given a :class:`str` *string* of up to 256 characters representing a " +"decoding table, returns either a compact internal mapping object " +"``EncodingMap`` or a :class:`dictionary ` mapping character ordinals " +"to byte values. Raises a :exc:`TypeError` on invalid input." +msgstr "" + +#: ../../library/codecs.rst:64 +msgid "The full details for each codec can also be looked up directly:" +msgstr "" + +#: ../../library/codecs.rst:68 +msgid "" +"Looks up the codec info in the Python codec registry and returns a :class:" +"`CodecInfo` object as defined below." +msgstr "" + +#: ../../library/codecs.rst:71 +msgid "" +"Encodings are first looked up in the registry's cache. If not found, the " +"list of registered search functions is scanned. If no :class:`CodecInfo` " +"object is found, a :exc:`LookupError` is raised. Otherwise, the :class:" +"`CodecInfo` object is stored in the cache and returned to the caller." +msgstr "" + +#: ../../library/codecs.rst:78 +msgid "" +"Codec details when looking up the codec registry. The constructor arguments " +"are stored in attributes of the same name:" +msgstr "" + +#: ../../library/codecs.rst:84 +msgid "The name of the encoding." +msgstr "編碼的名稱。" + +#: ../../library/codecs.rst:90 +msgid "" +"The stateless encoding and decoding functions. These must be functions or " +"methods which have the same interface as the :meth:`~Codec.encode` and :meth:" +"`~Codec.decode` methods of Codec instances (see :ref:`Codec Interface `). The functions or methods are expected to work in a stateless " +"mode." +msgstr "" + +#: ../../library/codecs.rst:100 +msgid "" +"Incremental encoder and decoder classes or factory functions. These have to " +"provide the interface defined by the base classes :class:" +"`IncrementalEncoder` and :class:`IncrementalDecoder`, respectively. " +"Incremental codecs can maintain state." +msgstr "" + +#: ../../library/codecs.rst:109 +msgid "" +"Stream writer and reader classes or factory functions. These have to provide " +"the interface defined by the base classes :class:`StreamWriter` and :class:" +"`StreamReader`, respectively. Stream codecs can maintain state." +msgstr "" + +#: ../../library/codecs.rst:114 +msgid "" +"To simplify access to the various codec components, the module provides " +"these additional functions which use :func:`lookup` for the codec lookup:" +msgstr "" + +#: ../../library/codecs.rst:119 +msgid "" +"Look up the codec for the given encoding and return its encoder function." +msgstr "" + +#: ../../library/codecs.rst:121 ../../library/codecs.rst:128 +#: ../../library/codecs.rst:154 ../../library/codecs.rst:162 +msgid "Raises a :exc:`LookupError` in case the encoding cannot be found." +msgstr "" + +#: ../../library/codecs.rst:126 +msgid "" +"Look up the codec for the given encoding and return its decoder function." +msgstr "" + +#: ../../library/codecs.rst:133 +msgid "" +"Look up the codec for the given encoding and return its incremental encoder " +"class or factory function." +msgstr "" + +#: ../../library/codecs.rst:136 +msgid "" +"Raises a :exc:`LookupError` in case the encoding cannot be found or the " +"codec doesn't support an incremental encoder." +msgstr "" + +#: ../../library/codecs.rst:142 +msgid "" +"Look up the codec for the given encoding and return its incremental decoder " +"class or factory function." +msgstr "" + +#: ../../library/codecs.rst:145 +msgid "" +"Raises a :exc:`LookupError` in case the encoding cannot be found or the " +"codec doesn't support an incremental decoder." +msgstr "" + +#: ../../library/codecs.rst:151 +msgid "" +"Look up the codec for the given encoding and return its :class:" +"`StreamReader` class or factory function." +msgstr "" + +#: ../../library/codecs.rst:159 +msgid "" +"Look up the codec for the given encoding and return its :class:" +"`StreamWriter` class or factory function." +msgstr "" + +#: ../../library/codecs.rst:164 +msgid "" +"Custom codecs are made available by registering a suitable codec search " +"function:" +msgstr "" + +#: ../../library/codecs.rst:169 +msgid "" +"Register a codec search function. Search functions are expected to take one " +"argument, being the encoding name in all lower case letters with hyphens and " +"spaces converted to underscores, and return a :class:`CodecInfo` object. In " +"case a search function cannot find a given encoding, it should return " +"``None``." +msgstr "" + +#: ../../library/codecs.rst:175 +msgid "Hyphens and spaces are converted to underscore." +msgstr "" + +#: ../../library/codecs.rst:181 +msgid "" +"Unregister a codec search function and clear the registry's cache. If the " +"search function is not registered, do nothing." +msgstr "" + +#: ../../library/codecs.rst:187 +msgid "" +"While the builtin :func:`open` and the associated :mod:`io` module are the " +"recommended approach for working with encoded text files, this module " +"provides additional utility functions and classes that allow the use of a " +"wider range of codecs when working with binary files:" +msgstr "" + +#: ../../library/codecs.rst:194 +msgid "" +"Open an encoded file using the given *mode* and return an instance of :class:" +"`StreamReaderWriter`, providing transparent encoding/decoding. The default " +"file mode is ``'r'``, meaning to open the file in read mode." +msgstr "" + +#: ../../library/codecs.rst:200 +msgid "" +"If *encoding* is not ``None``, then the underlying encoded files are always " +"opened in binary mode. No automatic conversion of ``'\\n'`` is done on " +"reading and writing. The *mode* argument may be any binary mode acceptable " +"to the built-in :func:`open` function; the ``'b'`` is automatically added." +msgstr "" + +#: ../../library/codecs.rst:206 +msgid "" +"*encoding* specifies the encoding which is to be used for the file. Any " +"encoding that encodes to and decodes from bytes is allowed, and the data " +"types supported by the file methods depend on the codec used." +msgstr "" + +#: ../../library/codecs.rst:210 +msgid "" +"*errors* may be given to define the error handling. It defaults to " +"``'strict'`` which causes a :exc:`ValueError` to be raised in case an " +"encoding error occurs." +msgstr "" + +#: ../../library/codecs.rst:213 +msgid "" +"*buffering* has the same meaning as for the built-in :func:`open` function. " +"It defaults to -1 which means that the default buffer size will be used." +msgstr "" + +#: ../../library/codecs.rst:216 +msgid "The ``'U'`` mode has been removed." +msgstr "已移除 ``'U'`` 模式。" + +#: ../../library/codecs.rst:221 +msgid ":func:`codecs.open` has been superseded by :func:`open`." +msgstr "" + +#: ../../library/codecs.rst:226 +msgid "" +"Return a :class:`StreamRecoder` instance, a wrapped version of *file* which " +"provides transparent transcoding. The original file is closed when the " +"wrapped version is closed." +msgstr "" + +#: ../../library/codecs.rst:230 +msgid "" +"Data written to the wrapped file is decoded according to the given " +"*data_encoding* and then written to the original file as bytes using " +"*file_encoding*. Bytes read from the original file are decoded according to " +"*file_encoding*, and the result is encoded using *data_encoding*." +msgstr "" + +#: ../../library/codecs.rst:236 +msgid "If *file_encoding* is not given, it defaults to *data_encoding*." +msgstr "" + +#: ../../library/codecs.rst:238 +msgid "" +"*errors* may be given to define the error handling. It defaults to " +"``'strict'``, which causes :exc:`ValueError` to be raised in case an " +"encoding error occurs." +msgstr "" + +#: ../../library/codecs.rst:245 +msgid "" +"Uses an incremental encoder to iteratively encode the input provided by " +"*iterator*. *iterator* must yield :class:`str` objects. This function is a :" +"term:`generator`. The *errors* argument (as well as any other keyword " +"argument) is passed through to the incremental encoder." +msgstr "" + +#: ../../library/codecs.rst:250 +msgid "" +"This function requires that the codec accept text :class:`str` objects to " +"encode. Therefore it does not support bytes-to-bytes encoders such as " +"``base64_codec``." +msgstr "" + +#: ../../library/codecs.rst:257 +msgid "" +"Uses an incremental decoder to iteratively decode the input provided by " +"*iterator*. *iterator* must yield :class:`bytes` objects. This function is " +"a :term:`generator`. The *errors* argument (as well as any other keyword " +"argument) is passed through to the incremental decoder." +msgstr "" + +#: ../../library/codecs.rst:262 +msgid "" +"This function requires that the codec accept :class:`bytes` objects to " +"decode. Therefore it does not support text-to-text encoders such as " +"``rot_13``, although ``rot_13`` may be used equivalently with :func:" +"`iterencode`." +msgstr "" + +#: ../../library/codecs.rst:270 +msgid "" +"Return a :class:`tuple` containing the raw bytes of *buffer*, a :ref:`buffer-" +"compatible object ` or :class:`str` (encoded to UTF-8 before " +"processing), and their length in bytes." +msgstr "" + +#: ../../library/codecs.rst:274 +msgid "The *errors* argument is ignored." +msgstr "忽略 *errors* 引數。" + +#: ../../library/codecs.rst:276 +msgid "" +">>> codecs.readbuffer_encode(b\"Zito\")\n" +"(b'Zito', 4)" +msgstr "" +">>> codecs.readbuffer_encode(b\"Zito\")\n" +"(b'Zito', 4)" + +#: ../../library/codecs.rst:282 +msgid "" +"The module also provides the following constants which are useful for " +"reading and writing to platform dependent files:" +msgstr "" + +#: ../../library/codecs.rst:297 +msgid "" +"These constants define various byte sequences, being Unicode byte order " +"marks (BOMs) for several encodings. They are used in UTF-16 and UTF-32 data " +"streams to indicate the byte order used, and in UTF-8 as a Unicode " +"signature. :const:`BOM_UTF16` is either :const:`BOM_UTF16_BE` or :const:" +"`BOM_UTF16_LE` depending on the platform's native byte order, :const:`BOM` " +"is an alias for :const:`BOM_UTF16`, :const:`BOM_LE` for :const:" +"`BOM_UTF16_LE` and :const:`BOM_BE` for :const:`BOM_UTF16_BE`. The others " +"represent the BOM in UTF-8 and UTF-32 encodings." +msgstr "" + +#: ../../library/codecs.rst:311 +msgid "Codec Base Classes" +msgstr "" + +#: ../../library/codecs.rst:313 +msgid "" +"The :mod:`codecs` module defines a set of base classes which define the " +"interfaces for working with codec objects, and can also be used as the basis " +"for custom codec implementations." +msgstr "" + +#: ../../library/codecs.rst:317 +msgid "" +"Each codec has to define four interfaces to make it usable as codec in " +"Python: stateless encoder, stateless decoder, stream reader and stream " +"writer. The stream reader and writers typically reuse the stateless encoder/" +"decoder to implement the file protocols. Codec authors also need to define " +"how the codec will handle encoding and decoding errors." +msgstr "" + +#: ../../library/codecs.rst:328 +msgid "Error Handlers" +msgstr "" + +#: ../../library/codecs.rst:330 +msgid "" +"To simplify and standardize error handling, codecs may implement different " +"error handling schemes by accepting the *errors* string argument:" +msgstr "" + +#: ../../library/codecs.rst:350 +msgid "" +"The following error handlers can be used with all Python :ref:`standard-" +"encodings` codecs:" +msgstr "" + +#: ../../library/codecs.rst:356 ../../library/codecs.rst:399 +#: ../../library/codecs.rst:419 +msgid "Value" +msgstr "" + +#: ../../library/codecs.rst:356 ../../library/codecs.rst:399 +#: ../../library/codecs.rst:419 ../../library/codecs.rst:1376 +#: ../../library/codecs.rst:1448 ../../library/codecs.rst:1533 +msgid "Meaning" +msgstr "含義" + +#: ../../library/codecs.rst:358 +msgid "``'strict'``" +msgstr "``'strict'``" + +#: ../../library/codecs.rst:358 +msgid "" +"Raise :exc:`UnicodeError` (or a subclass), this is the default. Implemented " +"in :func:`strict_errors`." +msgstr "" + +#: ../../library/codecs.rst:362 +msgid "``'ignore'``" +msgstr "``'ignore'``" + +#: ../../library/codecs.rst:362 +msgid "" +"Ignore the malformed data and continue without further notice. Implemented " +"in :func:`ignore_errors`." +msgstr "" + +#: ../../library/codecs.rst:366 +msgid "``'replace'``" +msgstr "``'replace'``" + +#: ../../library/codecs.rst:366 +msgid "" +"Replace with a replacement marker. On encoding, use ``?`` (ASCII character). " +"On decoding, use ``�`` (U+FFFD, the official REPLACEMENT CHARACTER). " +"Implemented in :func:`replace_errors`." +msgstr "" + +#: ../../library/codecs.rst:372 +msgid "``'backslashreplace'``" +msgstr "``'backslashreplace'``" + +#: ../../library/codecs.rst:372 +msgid "" +"Replace with backslashed escape sequences. On encoding, use hexadecimal form " +"of Unicode code point with formats :samp:`\\\\x{hh}` :samp:`\\\\u{xxxx}` :" +"samp:`\\\\U{xxxxxxxx}`. On decoding, use hexadecimal form of byte value with " +"format :samp:`\\\\x{hh}`. Implemented in :func:`backslashreplace_errors`." +msgstr "" + +#: ../../library/codecs.rst:381 +msgid "``'surrogateescape'``" +msgstr "``'surrogateescape'``" + +#: ../../library/codecs.rst:381 +msgid "" +"On decoding, replace byte with individual surrogate code ranging from " +"``U+DC80`` to ``U+DCFF``. This code will then be turned back into the same " +"byte when the ``'surrogateescape'`` error handler is used when encoding the " +"data. (See :pep:`383` for more.)" +msgstr "" + +#: ../../library/codecs.rst:395 +msgid "" +"The following error handlers are only applicable to encoding (within :term:" +"`text encodings `):" +msgstr "" + +#: ../../library/codecs.rst:401 +msgid "``'xmlcharrefreplace'``" +msgstr "``'xmlcharrefreplace'``" + +#: ../../library/codecs.rst:401 +msgid "" +"Replace with XML/HTML numeric character reference, which is a decimal form " +"of Unicode code point with format :samp:`&#{num};`. Implemented in :func:" +"`xmlcharrefreplace_errors`." +msgstr "" + +#: ../../library/codecs.rst:407 +msgid "``'namereplace'``" +msgstr "``'namereplace'``" + +#: ../../library/codecs.rst:407 +msgid "" +"Replace with ``\\N{...}`` escape sequences, what appears in the braces is " +"the Name property from Unicode Character Database. Implemented in :func:" +"`namereplace_errors`." +msgstr "" + +#: ../../library/codecs.rst:416 +msgid "" +"In addition, the following error handler is specific to the given codecs:" +msgstr "" + +#: ../../library/codecs.rst:13 ../../library/codecs.rst:419 +msgid "Codecs" +msgstr "" + +#: ../../library/codecs.rst:421 +msgid "``'surrogatepass'``" +msgstr "``'surrogatepass'``" + +#: ../../library/codecs.rst:421 +msgid "utf-8, utf-16, utf-32, utf-16-be, utf-16-le, utf-32-be, utf-32-le" +msgstr "utf-8, utf-16, utf-32, utf-16-be, utf-16-le, utf-32-be, utf-32-le" + +#: ../../library/codecs.rst:421 +msgid "" +"Allow encoding and decoding surrogate code point (``U+D800`` - ``U+DFFF``) " +"as normal code point. Otherwise these codecs treat the presence of surrogate " +"code point in :class:`str` as an error." +msgstr "" + +#: ../../library/codecs.rst:428 +msgid "The ``'surrogateescape'`` and ``'surrogatepass'`` error handlers." +msgstr "" + +#: ../../library/codecs.rst:431 +msgid "" +"The ``'surrogatepass'`` error handler now works with utf-16\\* and utf-32\\* " +"codecs." +msgstr "" + +#: ../../library/codecs.rst:435 +msgid "The ``'namereplace'`` error handler." +msgstr "" + +#: ../../library/codecs.rst:438 +msgid "" +"The ``'backslashreplace'`` error handler now works with decoding and " +"translating." +msgstr "" + +#: ../../library/codecs.rst:442 +msgid "" +"The set of allowed values can be extended by registering a new named error " +"handler:" +msgstr "" + +#: ../../library/codecs.rst:447 +msgid "" +"Register the error handling function *error_handler* under the name *name*. " +"The *error_handler* argument will be called during encoding and decoding in " +"case of an error, when *name* is specified as the errors parameter." +msgstr "" + +#: ../../library/codecs.rst:451 +msgid "" +"For encoding, *error_handler* will be called with a :exc:" +"`UnicodeEncodeError` instance, which contains information about the location " +"of the error. The error handler must either raise this or a different " +"exception, or return a tuple with a replacement for the unencodable part of " +"the input and a position where encoding should continue. The replacement may " +"be either :class:`str` or :class:`bytes`. If the replacement is bytes, the " +"encoder will simply copy them into the output buffer. If the replacement is " +"a string, the encoder will encode the replacement. Encoding continues on " +"original input at the specified position. Negative position values will be " +"treated as being relative to the end of the input string. If the resulting " +"position is out of bound an :exc:`IndexError` will be raised." +msgstr "" + +#: ../../library/codecs.rst:463 +msgid "" +"Decoding and translating works similarly, except :exc:`UnicodeDecodeError` " +"or :exc:`UnicodeTranslateError` will be passed to the handler and that the " +"replacement from the error handler will be put into the output directly." +msgstr "" + +#: ../../library/codecs.rst:468 +msgid "" +"Previously registered error handlers (including the standard error handlers) " +"can be looked up by name:" +msgstr "" + +#: ../../library/codecs.rst:473 +msgid "Return the error handler previously registered under the name *name*." +msgstr "" + +#: ../../library/codecs.rst:475 +msgid "Raises a :exc:`LookupError` in case the handler cannot be found." +msgstr "" + +#: ../../library/codecs.rst:477 +msgid "" +"The following standard error handlers are also made available as module " +"level functions:" +msgstr "" + +#: ../../library/codecs.rst:482 +msgid "Implements the ``'strict'`` error handling." +msgstr "" + +#: ../../library/codecs.rst:484 +msgid "Each encoding or decoding error raises a :exc:`UnicodeError`." +msgstr "" + +#: ../../library/codecs.rst:489 +msgid "Implements the ``'ignore'`` error handling." +msgstr "" + +#: ../../library/codecs.rst:491 +msgid "" +"Malformed data is ignored; encoding or decoding is continued without further " +"notice." +msgstr "" + +#: ../../library/codecs.rst:497 +msgid "Implements the ``'replace'`` error handling." +msgstr "" + +#: ../../library/codecs.rst:499 +msgid "" +"Substitutes ``?`` (ASCII character) for encoding errors or ``�`` (U+FFFD, " +"the official REPLACEMENT CHARACTER) for decoding errors." +msgstr "" + +#: ../../library/codecs.rst:505 +msgid "Implements the ``'backslashreplace'`` error handling." +msgstr "" + +#: ../../library/codecs.rst:507 +msgid "" +"Malformed data is replaced by a backslashed escape sequence. On encoding, " +"use the hexadecimal form of Unicode code point with formats :samp:`\\\\x{hh}" +"` :samp:`\\\\u{xxxx}` :samp:`\\\\U{xxxxxxxx}`. On decoding, use the " +"hexadecimal form of byte value with format :samp:`\\\\x{hh}`." +msgstr "" + +#: ../../library/codecs.rst:513 +msgid "Works with decoding and translating." +msgstr "" + +#: ../../library/codecs.rst:519 +msgid "" +"Implements the ``'xmlcharrefreplace'`` error handling (for encoding within :" +"term:`text encoding` only)." +msgstr "" + +#: ../../library/codecs.rst:522 +msgid "" +"The unencodable character is replaced by an appropriate XML/HTML numeric " +"character reference, which is a decimal form of Unicode code point with " +"format :samp:`&#{num};` ." +msgstr "" + +#: ../../library/codecs.rst:529 +msgid "" +"Implements the ``'namereplace'`` error handling (for encoding within :term:" +"`text encoding` only)." +msgstr "" + +#: ../../library/codecs.rst:532 +msgid "" +"The unencodable character is replaced by a ``\\N{...}`` escape sequence. The " +"set of characters that appear in the braces is the Name property from " +"Unicode Character Database. For example, the German lowercase letter ``'ß'`` " +"will be converted to byte sequence ``\\N{LATIN SMALL LETTER SHARP S}`` ." +msgstr "" + +#: ../../library/codecs.rst:543 +msgid "Stateless Encoding and Decoding" +msgstr "" + +#: ../../library/codecs.rst:545 +msgid "" +"The base :class:`Codec` class defines these methods which also define the " +"function interfaces of the stateless encoder and decoder:" +msgstr "" + +#: ../../library/codecs.rst:553 +msgid "" +"Encodes the object *input* and returns a tuple (output object, length " +"consumed). For instance, :term:`text encoding` converts a string object to a " +"bytes object using a particular character set encoding (e.g., ``cp1252`` or " +"``iso-8859-1``)." +msgstr "" + +#: ../../library/codecs.rst:558 ../../library/codecs.rst:580 +msgid "" +"The *errors* argument defines the error handling to apply. It defaults to " +"``'strict'`` handling." +msgstr "" + +#: ../../library/codecs.rst:561 +msgid "" +"The method may not store state in the :class:`Codec` instance. Use :class:" +"`StreamWriter` for codecs which have to keep state in order to make encoding " +"efficient." +msgstr "" + +#: ../../library/codecs.rst:565 +msgid "" +"The encoder must be able to handle zero length input and return an empty " +"object of the output object type in this situation." +msgstr "" + +#: ../../library/codecs.rst:571 +msgid "" +"Decodes the object *input* and returns a tuple (output object, length " +"consumed). For instance, for a :term:`text encoding`, decoding converts a " +"bytes object encoded using a particular character set encoding to a string " +"object." +msgstr "" + +#: ../../library/codecs.rst:576 +msgid "" +"For text encodings and bytes-to-bytes codecs, *input* must be a bytes object " +"or one which provides the read-only buffer interface -- for example, buffer " +"objects and memory mapped files." +msgstr "" + +#: ../../library/codecs.rst:583 +msgid "" +"The method may not store state in the :class:`Codec` instance. Use :class:" +"`StreamReader` for codecs which have to keep state in order to make decoding " +"efficient." +msgstr "" + +#: ../../library/codecs.rst:587 +msgid "" +"The decoder must be able to handle zero length input and return an empty " +"object of the output object type in this situation." +msgstr "" + +#: ../../library/codecs.rst:592 +msgid "Incremental Encoding and Decoding" +msgstr "" + +#: ../../library/codecs.rst:594 +msgid "" +"The :class:`IncrementalEncoder` and :class:`IncrementalDecoder` classes " +"provide the basic interface for incremental encoding and decoding. Encoding/" +"decoding the input isn't done with one call to the stateless encoder/decoder " +"function, but with multiple calls to the :meth:`~IncrementalEncoder.encode`/:" +"meth:`~IncrementalDecoder.decode` method of the incremental encoder/decoder. " +"The incremental encoder/decoder keeps track of the encoding/decoding process " +"during method calls." +msgstr "" + +#: ../../library/codecs.rst:602 +msgid "" +"The joined output of calls to the :meth:`~IncrementalEncoder.encode`/:meth:" +"`~IncrementalDecoder.decode` method is the same as if all the single inputs " +"were joined into one, and this input was encoded/decoded with the stateless " +"encoder/decoder." +msgstr "" + +#: ../../library/codecs.rst:611 +msgid "IncrementalEncoder Objects" +msgstr "IncrementalEncoder 物件" + +#: ../../library/codecs.rst:613 +msgid "" +"The :class:`IncrementalEncoder` class is used for encoding an input in " +"multiple steps. It defines the following methods which every incremental " +"encoder must define in order to be compatible with the Python codec registry." +msgstr "" + +#: ../../library/codecs.rst:620 +msgid "Constructor for an :class:`IncrementalEncoder` instance." +msgstr ":class:`IncrementalEncoder` 的建構函式。" + +#: ../../library/codecs.rst:622 +msgid "" +"All incremental encoders must provide this constructor interface. They are " +"free to add additional keyword arguments, but only the ones defined here are " +"used by the Python codec registry." +msgstr "" + +#: ../../library/codecs.rst:626 +msgid "" +"The :class:`IncrementalEncoder` may implement different error handling " +"schemes by providing the *errors* keyword argument. See :ref:`error-" +"handlers` for possible values." +msgstr "" + +#: ../../library/codecs.rst:630 +msgid "" +"The *errors* argument will be assigned to an attribute of the same name. " +"Assigning to this attribute makes it possible to switch between different " +"error handling strategies during the lifetime of the :class:" +"`IncrementalEncoder` object." +msgstr "" + +#: ../../library/codecs.rst:638 +msgid "" +"Encodes *object* (taking the current state of the encoder into account) and " +"returns the resulting encoded object. If this is the last call to :meth:" +"`encode` *final* must be true (the default is false)." +msgstr "" + +#: ../../library/codecs.rst:645 +msgid "" +"Reset the encoder to the initial state. The output is discarded: call ``." +"encode(object, final=True)``, passing an empty byte or text string if " +"necessary, to reset the encoder and to get the output." +msgstr "" + +#: ../../library/codecs.rst:652 +msgid "" +"Return the current state of the encoder which must be an integer. The " +"implementation should make sure that ``0`` is the most common state. (States " +"that are more complicated than integers can be converted into an integer by " +"marshaling/pickling the state and encoding the bytes of the resulting string " +"into an integer.)" +msgstr "" + +#: ../../library/codecs.rst:661 +msgid "" +"Set the state of the encoder to *state*. *state* must be an encoder state " +"returned by :meth:`getstate`." +msgstr "" + +#: ../../library/codecs.rst:668 +msgid "IncrementalDecoder Objects" +msgstr "IncrementalDecoder 物件" + +#: ../../library/codecs.rst:670 +msgid "" +"The :class:`IncrementalDecoder` class is used for decoding an input in " +"multiple steps. It defines the following methods which every incremental " +"decoder must define in order to be compatible with the Python codec registry." +msgstr "" + +#: ../../library/codecs.rst:677 +msgid "Constructor for an :class:`IncrementalDecoder` instance." +msgstr ":class:`IncrementalDecoder` 的建構函式。" + +#: ../../library/codecs.rst:679 +msgid "" +"All incremental decoders must provide this constructor interface. They are " +"free to add additional keyword arguments, but only the ones defined here are " +"used by the Python codec registry." +msgstr "" + +#: ../../library/codecs.rst:683 +msgid "" +"The :class:`IncrementalDecoder` may implement different error handling " +"schemes by providing the *errors* keyword argument. See :ref:`error-" +"handlers` for possible values." +msgstr "" + +#: ../../library/codecs.rst:687 +msgid "" +"The *errors* argument will be assigned to an attribute of the same name. " +"Assigning to this attribute makes it possible to switch between different " +"error handling strategies during the lifetime of the :class:" +"`IncrementalDecoder` object." +msgstr "" + +#: ../../library/codecs.rst:695 +msgid "" +"Decodes *object* (taking the current state of the decoder into account) and " +"returns the resulting decoded object. If this is the last call to :meth:" +"`decode` *final* must be true (the default is false). If *final* is true the " +"decoder must decode the input completely and must flush all buffers. If this " +"isn't possible (e.g. because of incomplete byte sequences at the end of the " +"input) it must initiate error handling just like in the stateless case " +"(which might raise an exception)." +msgstr "" + +#: ../../library/codecs.rst:706 +msgid "Reset the decoder to the initial state." +msgstr "將解碼器重設到初始狀態。" + +#: ../../library/codecs.rst:711 +msgid "" +"Return the current state of the decoder. This must be a tuple with two " +"items, the first must be the buffer containing the still undecoded input. " +"The second must be an integer and can be additional state info. (The " +"implementation should make sure that ``0`` is the most common additional " +"state info.) If this additional state info is ``0`` it must be possible to " +"set the decoder to the state which has no input buffered and ``0`` as the " +"additional state info, so that feeding the previously buffered input to the " +"decoder returns it to the previous state without producing any output. " +"(Additional state info that is more complicated than integers can be " +"converted into an integer by marshaling/pickling the info and encoding the " +"bytes of the resulting string into an integer.)" +msgstr "" + +#: ../../library/codecs.rst:726 +msgid "" +"Set the state of the decoder to *state*. *state* must be a decoder state " +"returned by :meth:`getstate`." +msgstr "" + +#: ../../library/codecs.rst:731 +msgid "Stream Encoding and Decoding" +msgstr "串流編碼和解碼" + +#: ../../library/codecs.rst:734 +msgid "" +"The :class:`StreamWriter` and :class:`StreamReader` classes provide generic " +"working interfaces which can be used to implement new encoding submodules " +"very easily. See :mod:`!encodings.utf_8` for an example of how this is done." +msgstr "" + +#: ../../library/codecs.rst:742 +msgid "StreamWriter Objects" +msgstr "StreamWriter 物件" + +#: ../../library/codecs.rst:744 +msgid "" +"The :class:`StreamWriter` class is a subclass of :class:`Codec` and defines " +"the following methods which every stream writer must define in order to be " +"compatible with the Python codec registry." +msgstr "" + +#: ../../library/codecs.rst:751 +msgid "Constructor for a :class:`StreamWriter` instance." +msgstr ":class:`StreamWriter` 的建構函式。" + +#: ../../library/codecs.rst:753 +msgid "" +"All stream writers must provide this constructor interface. They are free to " +"add additional keyword arguments, but only the ones defined here are used by " +"the Python codec registry." +msgstr "" + +#: ../../library/codecs.rst:757 +msgid "" +"The *stream* argument must be a file-like object open for writing text or " +"binary data, as appropriate for the specific codec." +msgstr "" + +#: ../../library/codecs.rst:760 +msgid "" +"The :class:`StreamWriter` may implement different error handling schemes by " +"providing the *errors* keyword argument. See :ref:`error-handlers` for the " +"standard error handlers the underlying stream codec may support." +msgstr "" + +#: ../../library/codecs.rst:764 +msgid "" +"The *errors* argument will be assigned to an attribute of the same name. " +"Assigning to this attribute makes it possible to switch between different " +"error handling strategies during the lifetime of the :class:`StreamWriter` " +"object." +msgstr "" + +#: ../../library/codecs.rst:770 +msgid "Writes the object's contents encoded to the stream." +msgstr "" + +#: ../../library/codecs.rst:775 +msgid "" +"Writes the concatenated iterable of strings to the stream (possibly by " +"reusing the :meth:`write` method). Infinite or very large iterables are not " +"supported. The standard bytes-to-bytes codecs do not support this method." +msgstr "" + +#: ../../library/codecs.rst:783 ../../library/codecs.rst:878 +msgid "Resets the codec buffers used for keeping internal state." +msgstr "" + +#: ../../library/codecs.rst:785 +msgid "" +"Calling this method should ensure that the data on the output is put into a " +"clean state that allows appending of new fresh data without having to rescan " +"the whole stream to recover state." +msgstr "" + +#: ../../library/codecs.rst:790 +msgid "" +"In addition to the above methods, the :class:`StreamWriter` must also " +"inherit all other methods and attributes from the underlying stream." +msgstr "" + +#: ../../library/codecs.rst:797 +msgid "StreamReader Objects" +msgstr "StreamReader 物件" + +#: ../../library/codecs.rst:799 +msgid "" +"The :class:`StreamReader` class is a subclass of :class:`Codec` and defines " +"the following methods which every stream reader must define in order to be " +"compatible with the Python codec registry." +msgstr "" + +#: ../../library/codecs.rst:806 +msgid "Constructor for a :class:`StreamReader` instance." +msgstr ":class:`StreamReader` 的建構函式。" + +#: ../../library/codecs.rst:808 +msgid "" +"All stream readers must provide this constructor interface. They are free to " +"add additional keyword arguments, but only the ones defined here are used by " +"the Python codec registry." +msgstr "" + +#: ../../library/codecs.rst:812 +msgid "" +"The *stream* argument must be a file-like object open for reading text or " +"binary data, as appropriate for the specific codec." +msgstr "" + +#: ../../library/codecs.rst:815 +msgid "" +"The :class:`StreamReader` may implement different error handling schemes by " +"providing the *errors* keyword argument. See :ref:`error-handlers` for the " +"standard error handlers the underlying stream codec may support." +msgstr "" + +#: ../../library/codecs.rst:819 +msgid "" +"The *errors* argument will be assigned to an attribute of the same name. " +"Assigning to this attribute makes it possible to switch between different " +"error handling strategies during the lifetime of the :class:`StreamReader` " +"object." +msgstr "" + +#: ../../library/codecs.rst:823 +msgid "" +"The set of allowed values for the *errors* argument can be extended with :" +"func:`register_error`." +msgstr "" + +#: ../../library/codecs.rst:829 +msgid "Decodes data from the stream and returns the resulting object." +msgstr "" + +#: ../../library/codecs.rst:831 +msgid "" +"The *chars* argument indicates the number of decoded code points or bytes to " +"return. The :func:`read` method will never return more data than requested, " +"but it might return less, if there is not enough available." +msgstr "" + +#: ../../library/codecs.rst:836 +msgid "" +"The *size* argument indicates the approximate maximum number of encoded " +"bytes or code points to read for decoding. The decoder can modify this " +"setting as appropriate. The default value -1 indicates to read and decode as " +"much as possible. This parameter is intended to prevent having to decode " +"huge files in one step." +msgstr "" + +#: ../../library/codecs.rst:843 +msgid "" +"The *firstline* flag indicates that it would be sufficient to only return " +"the first line, if there are decoding errors on later lines." +msgstr "" + +#: ../../library/codecs.rst:847 +msgid "" +"The method should use a greedy read strategy meaning that it should read as " +"much data as is allowed within the definition of the encoding and the given " +"size, e.g. if optional encoding endings or state markers are available on " +"the stream, these should be read too." +msgstr "" + +#: ../../library/codecs.rst:855 +msgid "Read one line from the input stream and return the decoded data." +msgstr "" + +#: ../../library/codecs.rst:857 +msgid "" +"*size*, if given, is passed as size argument to the stream's :meth:`read` " +"method." +msgstr "" + +#: ../../library/codecs.rst:860 +msgid "" +"If *keepends* is false line-endings will be stripped from the lines returned." +msgstr "" + +#: ../../library/codecs.rst:866 +msgid "" +"Read all lines available on the input stream and return them as a list of " +"lines." +msgstr "" + +#: ../../library/codecs.rst:869 +msgid "" +"Line-endings are implemented using the codec's :meth:`decode` method and are " +"included in the list entries if *keepends* is true." +msgstr "" + +#: ../../library/codecs.rst:872 +msgid "" +"*sizehint*, if given, is passed as the *size* argument to the stream's :meth:" +"`read` method." +msgstr "" + +#: ../../library/codecs.rst:880 +msgid "" +"Note that no stream repositioning should take place. This method is " +"primarily intended to be able to recover from decoding errors." +msgstr "" + +#: ../../library/codecs.rst:884 +msgid "" +"In addition to the above methods, the :class:`StreamReader` must also " +"inherit all other methods and attributes from the underlying stream." +msgstr "" + +#: ../../library/codecs.rst:890 +msgid "StreamReaderWriter Objects" +msgstr "StreamReaderWriter 物件" + +#: ../../library/codecs.rst:892 +msgid "" +"The :class:`StreamReaderWriter` is a convenience class that allows wrapping " +"streams which work in both read and write modes." +msgstr "" + +#: ../../library/codecs.rst:895 ../../library/codecs.rst:919 +msgid "" +"The design is such that one can use the factory functions returned by the :" +"func:`lookup` function to construct the instance." +msgstr "" + +#: ../../library/codecs.rst:901 +msgid "" +"Creates a :class:`StreamReaderWriter` instance. *stream* must be a file-like " +"object. *Reader* and *Writer* must be factory functions or classes providing " +"the :class:`StreamReader` and :class:`StreamWriter` interface resp. Error " +"handling is done in the same way as defined for the stream readers and " +"writers." +msgstr "" + +#: ../../library/codecs.rst:906 +msgid "" +":class:`StreamReaderWriter` instances define the combined interfaces of :" +"class:`StreamReader` and :class:`StreamWriter` classes. They inherit all " +"other methods and attributes from the underlying stream." +msgstr "" + +#: ../../library/codecs.rst:914 +msgid "StreamRecoder Objects" +msgstr "StreamRecoder 物件" + +#: ../../library/codecs.rst:916 +msgid "" +"The :class:`StreamRecoder` translates data from one encoding to another, " +"which is sometimes useful when dealing with different encoding environments." +msgstr "" + +#: ../../library/codecs.rst:925 +msgid "" +"Creates a :class:`StreamRecoder` instance which implements a two-way " +"conversion: *encode* and *decode* work on the frontend — the data visible to " +"code calling :meth:`~StreamReader.read` and :meth:`~StreamWriter.write`, " +"while *Reader* and *Writer* work on the backend — the data in *stream*." +msgstr "" + +#: ../../library/codecs.rst:931 +msgid "" +"You can use these objects to do transparent transcodings, e.g., from Latin-1 " +"to UTF-8 and back." +msgstr "" + +#: ../../library/codecs.rst:934 +msgid "The *stream* argument must be a file-like object." +msgstr "*stream* 引數必須是類檔案物件。" + +#: ../../library/codecs.rst:936 +msgid "" +"The *encode* and *decode* arguments must adhere to the :class:`Codec` " +"interface. *Reader* and *Writer* must be factory functions or classes " +"providing objects of the :class:`StreamReader` and :class:`StreamWriter` " +"interface respectively." +msgstr "" + +#: ../../library/codecs.rst:941 +msgid "" +"Error handling is done in the same way as defined for the stream readers and " +"writers." +msgstr "" + +#: ../../library/codecs.rst:945 +msgid "" +":class:`StreamRecoder` instances define the combined interfaces of :class:" +"`StreamReader` and :class:`StreamWriter` classes. They inherit all other " +"methods and attributes from the underlying stream." +msgstr "" + +#: ../../library/codecs.rst:953 +msgid "Encodings and Unicode" +msgstr "編碼和 Unicode" + +#: ../../library/codecs.rst:955 +msgid "" +"Strings are stored internally as sequences of code points in range " +"``U+0000``--``U+10FFFF``. (See :pep:`393` for more details about the " +"implementation.) Once a string object is used outside of CPU and memory, " +"endianness and how these arrays are stored as bytes become an issue. As with " +"other codecs, serialising a string into a sequence of bytes is known as " +"*encoding*, and recreating the string from the sequence of bytes is known as " +"*decoding*. There are a variety of different text serialisation codecs, " +"which are collectivity referred to as :term:`text encodings `." +msgstr "" + +#: ../../library/codecs.rst:965 +msgid "" +"The simplest text encoding (called ``'latin-1'`` or ``'iso-8859-1'``) maps " +"the code points 0--255 to the bytes ``0x0``--``0xff``, which means that a " +"string object that contains code points above ``U+00FF`` can't be encoded " +"with this codec. Doing so will raise a :exc:`UnicodeEncodeError` that looks " +"like the following (although the details of the error message may differ): " +"``UnicodeEncodeError: 'latin-1' codec can't encode character '\\u1234' in " +"position 3: ordinal not in range(256)``." +msgstr "" + +#: ../../library/codecs.rst:973 +msgid "" +"There's another group of encodings (the so called charmap encodings) that " +"choose a different subset of all Unicode code points and how these code " +"points are mapped to the bytes ``0x0``--``0xff``. To see how this is done " +"simply open e.g. :file:`encodings/cp1252.py` (which is an encoding that is " +"used primarily on Windows). There's a string constant with 256 characters " +"that shows you which character is mapped to which byte value." +msgstr "" + +#: ../../library/codecs.rst:980 +msgid "" +"All of these encodings can only encode 256 of the 1114112 code points " +"defined in Unicode. A simple and straightforward way that can store each " +"Unicode code point, is to store each code point as four consecutive bytes. " +"There are two possibilities: store the bytes in big endian or in little " +"endian order. These two encodings are called ``UTF-32-BE`` and ``UTF-32-LE`` " +"respectively. Their disadvantage is that if, for example, you use ``UTF-32-" +"BE`` on a little endian machine you will always have to swap bytes on " +"encoding and decoding. Python's ``UTF-16`` and ``UTF-32`` codecs avoid this " +"problem by using the platform's native byte order when no BOM is present. " +"Python follows prevailing platform practice, so native-endian data round-" +"trips without redundant byte swapping, even though the Unicode Standard " +"defaults to big-endian when the byte order is unspecified. When these bytes " +"are read by a CPU with a different endianness, the bytes have to be swapped. " +"To be able to detect the endianness of a ``UTF-16`` or ``UTF-32`` byte " +"sequence, a BOM (\"Byte Order Mark\") is used. This is the Unicode character " +"``U+FEFF``. This character can be prepended to every ``UTF-16`` or " +"``UTF-32`` byte sequence. The byte swapped version of this character " +"(``0xFFFE``) is an illegal character that may not appear in a Unicode text. " +"When the first character of a ``UTF-16`` or ``UTF-32`` byte sequence is " +"``U+FFFE``, the bytes have to be swapped on decoding." +msgstr "" + +#: ../../library/codecs.rst:1001 +msgid "" +"Unfortunately the character ``U+FEFF`` had a second purpose as a ``ZERO " +"WIDTH NO-BREAK SPACE``: a character that has no width and doesn't allow a " +"word to be split. It can e.g. be used to give hints to a ligature algorithm. " +"With Unicode 4.0 using ``U+FEFF`` as a ``ZERO WIDTH NO-BREAK SPACE`` has " +"been deprecated (with ``U+2060`` (``WORD JOINER``) assuming this role). " +"Nevertheless Unicode software still must be able to handle ``U+FEFF`` in " +"both roles: as a BOM it's a device to determine the storage layout of the " +"encoded bytes, and vanishes once the byte sequence has been decoded into a " +"string; as a ``ZERO WIDTH NO-BREAK SPACE`` it's a normal character that will " +"be decoded like any other." +msgstr "" + +#: ../../library/codecs.rst:1011 +msgid "" +"There's another encoding that is able to encode the full range of Unicode " +"characters: UTF-8. UTF-8 is an 8-bit encoding, which means there are no " +"issues with byte order in UTF-8. Each byte in a UTF-8 byte sequence consists " +"of two parts: marker bits (the most significant bits) and payload bits. The " +"marker bits are a sequence of zero to four ``1`` bits followed by a ``0`` " +"bit. Unicode characters are encoded like this (with x being payload bits, " +"which when concatenated give the Unicode character):" +msgstr "" + +#: ../../library/codecs.rst:1020 +msgid "Range" +msgstr "" + +#: ../../library/codecs.rst:1020 +msgid "Encoding" +msgstr "" + +#: ../../library/codecs.rst:1022 +msgid "``U-00000000`` ... ``U-0000007F``" +msgstr "``U-00000000`` ... ``U-0000007F``" + +#: ../../library/codecs.rst:1022 +msgid "0xxxxxxx" +msgstr "0xxxxxxx" + +#: ../../library/codecs.rst:1024 +msgid "``U-00000080`` ... ``U-000007FF``" +msgstr "``U-00000080`` ... ``U-000007FF``" + +#: ../../library/codecs.rst:1024 +msgid "110xxxxx 10xxxxxx" +msgstr "110xxxxx 10xxxxxx" + +#: ../../library/codecs.rst:1026 +msgid "``U-00000800`` ... ``U-0000FFFF``" +msgstr "``U-00000800`` ... ``U-0000FFFF``" + +#: ../../library/codecs.rst:1026 +msgid "1110xxxx 10xxxxxx 10xxxxxx" +msgstr "1110xxxx 10xxxxxx 10xxxxxx" + +#: ../../library/codecs.rst:1028 +msgid "``U-00010000`` ... ``U-0010FFFF``" +msgstr "``U-00010000`` ... ``U-0010FFFF``" + +#: ../../library/codecs.rst:1028 +msgid "11110xxx 10xxxxxx 10xxxxxx 10xxxxxx" +msgstr "11110xxx 10xxxxxx 10xxxxxx 10xxxxxx" + +#: ../../library/codecs.rst:1031 +msgid "" +"The least significant bit of the Unicode character is the rightmost x bit." +msgstr "" + +#: ../../library/codecs.rst:1033 +msgid "" +"As UTF-8 is an 8-bit encoding no BOM is required and any ``U+FEFF`` " +"character in the decoded string (even if it's the first character) is " +"treated as a ``ZERO WIDTH NO-BREAK SPACE``." +msgstr "" + +#: ../../library/codecs.rst:1037 +msgid "" +"Without external information it's impossible to reliably determine which " +"encoding was used for encoding a string. Each charmap encoding can decode " +"any random byte sequence. However that's not possible with UTF-8, as UTF-8 " +"byte sequences have a structure that doesn't allow arbitrary byte sequences. " +"To increase the reliability with which a UTF-8 encoding can be detected, " +"Microsoft invented a variant of UTF-8 (that Python calls ``\"utf-8-sig\"``) " +"for its Notepad program: Before any of the Unicode characters is written to " +"the file, a UTF-8 encoded BOM (which looks like this as a byte sequence: " +"``0xef``, ``0xbb``, ``0xbf``) is written. As it's rather improbable that any " +"charmap encoded file starts with these byte values (which would e.g. map to" +msgstr "" + +#: ../../library/codecs.rst:1049 +msgid "LATIN SMALL LETTER I WITH DIAERESIS" +msgstr "" + +#: ../../library/codecs.rst:1050 +msgid "RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK" +msgstr "" + +#: ../../library/codecs.rst:1051 +msgid "INVERTED QUESTION MARK" +msgstr "" + +#: ../../library/codecs.rst:1053 +msgid "" +"in iso-8859-1), this increases the probability that a ``utf-8-sig`` encoding " +"can be correctly guessed from the byte sequence. So here the BOM is not used " +"to be able to determine the byte order used for generating the byte " +"sequence, but as a signature that helps in guessing the encoding. On " +"encoding the utf-8-sig codec will write ``0xef``, ``0xbb``, ``0xbf`` as the " +"first three bytes to the file. On decoding ``utf-8-sig`` will skip those " +"three bytes if they appear as the first three bytes in the file. In UTF-8, " +"the use of the BOM is discouraged and should generally be avoided." +msgstr "" + +#: ../../library/codecs.rst:1066 +msgid "Standard Encodings" +msgstr "標準編碼" + +#: ../../library/codecs.rst:1068 +msgid "" +"Python comes with a number of codecs built-in, either implemented as C " +"functions or with dictionaries as mapping tables. The following table lists " +"the codecs by name, together with a few common aliases, and the languages " +"for which the encoding is likely used. Neither the list of aliases nor the " +"list of languages is meant to be exhaustive. Notice that spelling " +"alternatives that only differ in case or use a hyphen instead of an " +"underscore are also valid aliases because they are equivalent when " +"normalized by :func:`~encodings.normalize_encoding`. For example, " +"``'utf-8'`` is a valid alias for the ``'utf_8'`` codec." +msgstr "" + +#: ../../library/codecs.rst:1080 +msgid "" +"The below table lists the most common aliases, for a complete list refer to " +"the source :source:`aliases.py ` file." +msgstr "" + +#: ../../library/codecs.rst:1083 +msgid "" +"On Windows, ``cpXXX`` codecs are available for all code pages. But only " +"codecs listed in the following table are guarantead to exist on other " +"platforms." +msgstr "" + +#: ../../library/codecs.rst:1089 +msgid "" +"Some common encodings can bypass the codecs lookup machinery to improve " +"performance. These optimization opportunities are only recognized by CPython " +"for a limited set of (case insensitive) aliases: utf-8, utf8, latin-1, " +"latin1, iso-8859-1, iso8859-1, mbcs (Windows only), ascii, us-ascii, utf-16, " +"utf16, utf-32, utf32, and the same using underscores instead of dashes. " +"Using alternative aliases for these encodings may result in slower execution." +msgstr "" + +#: ../../library/codecs.rst:1097 +msgid "Optimization opportunity recognized for us-ascii." +msgstr "" + +#: ../../library/codecs.rst:1100 +msgid "" +"Many of the character sets support the same languages. They vary in " +"individual characters (e.g. whether the EURO SIGN is supported or not), and " +"in the assignment of characters to code positions. For the European " +"languages in particular, the following variants typically exist:" +msgstr "" + +#: ../../library/codecs.rst:1105 +msgid "an ISO 8859 codeset" +msgstr "" + +#: ../../library/codecs.rst:1107 +msgid "" +"a Microsoft Windows code page, which is typically derived from an 8859 " +"codeset, but replaces control characters with additional graphic characters" +msgstr "" + +#: ../../library/codecs.rst:1110 +msgid "an IBM EBCDIC code page" +msgstr "" + +#: ../../library/codecs.rst:1112 +msgid "an IBM PC code page, which is ASCII compatible" +msgstr "" + +#: ../../library/codecs.rst:1117 ../../library/codecs.rst:1376 +#: ../../library/codecs.rst:1448 ../../library/codecs.rst:1533 +msgid "Codec" +msgstr "" + +#: ../../library/codecs.rst:1117 ../../library/codecs.rst:1376 +#: ../../library/codecs.rst:1448 ../../library/codecs.rst:1533 +msgid "Aliases" +msgstr "" + +#: ../../library/codecs.rst:1117 +msgid "Languages" +msgstr "語言" + +#: ../../library/codecs.rst:1119 +msgid "ascii" +msgstr "ascii" + +#: ../../library/codecs.rst:1119 +msgid "646, us-ascii" +msgstr "646, us-ascii" + +#: ../../library/codecs.rst:1119 ../../library/codecs.rst:1125 +#: ../../library/codecs.rst:1133 +msgid "English" +msgstr "英文" + +#: ../../library/codecs.rst:1121 +msgid "big5" +msgstr "big5" + +#: ../../library/codecs.rst:1121 +msgid "big5-tw, csbig5" +msgstr "big5-tw, csbig5" + +#: ../../library/codecs.rst:1121 ../../library/codecs.rst:1123 +#: ../../library/codecs.rst:1182 +msgid "Traditional Chinese" +msgstr "繁體中文" + +#: ../../library/codecs.rst:1123 +msgid "big5hkscs" +msgstr "big5hkscs" + +#: ../../library/codecs.rst:1123 +msgid "big5-hkscs, hkscs" +msgstr "big5-hkscs, hkscs" + +#: ../../library/codecs.rst:1125 +msgid "cp037" +msgstr "cp037" + +#: ../../library/codecs.rst:1125 +msgid "IBM037, IBM039" +msgstr "IBM037, IBM039" + +#: ../../library/codecs.rst:1127 +msgid "cp273" +msgstr "cp273" + +#: ../../library/codecs.rst:1127 +msgid "273, IBM273, csIBM273" +msgstr "273, IBM273, csIBM273" + +#: ../../library/codecs.rst:1127 +msgid "German" +msgstr "德文" + +#: ../../library/codecs.rst:1131 +msgid "cp424" +msgstr "cp424" + +#: ../../library/codecs.rst:1131 +msgid "EBCDIC-CP-HE, IBM424" +msgstr "EBCDIC-CP-HE, IBM424" + +#: ../../library/codecs.rst:1131 ../../library/codecs.rst:1151 +#: ../../library/codecs.rst:1161 ../../library/codecs.rst:1205 +#: ../../library/codecs.rst:1268 +msgid "Hebrew" +msgstr "希伯來文" + +#: ../../library/codecs.rst:1133 +msgid "cp437" +msgstr "cp437" + +#: ../../library/codecs.rst:1133 +msgid "437, IBM437" +msgstr "437, IBM437" + +#: ../../library/codecs.rst:1135 +msgid "cp500" +msgstr "cp500" + +#: ../../library/codecs.rst:1135 +msgid "EBCDIC-CP-BE, EBCDIC-CP-CH, IBM500" +msgstr "EBCDIC-CP-BE, EBCDIC-CP-CH, IBM500" + +#: ../../library/codecs.rst:1135 ../../library/codecs.rst:1144 +#: ../../library/codecs.rst:1155 ../../library/codecs.rst:1192 +#: ../../library/codecs.rst:1199 ../../library/codecs.rst:1252 +#: ../../library/codecs.rst:1280 ../../library/codecs.rst:1308 +msgid "Western Europe" +msgstr "" + +#: ../../library/codecs.rst:1138 +msgid "cp720" +msgstr "cp720" + +#: ../../library/codecs.rst:1138 ../../library/codecs.rst:1165 +#: ../../library/codecs.rst:1207 ../../library/codecs.rst:1264 +msgid "Arabic" +msgstr "阿拉伯文" + +#: ../../library/codecs.rst:1140 +msgid "cp737" +msgstr "cp737" + +#: ../../library/codecs.rst:1140 ../../library/codecs.rst:1171 +#: ../../library/codecs.rst:1175 ../../library/codecs.rst:1201 +#: ../../library/codecs.rst:1266 ../../library/codecs.rst:1301 +msgid "Greek" +msgstr "希臘文" + +#: ../../library/codecs.rst:1142 +msgid "cp775" +msgstr "cp775" + +#: ../../library/codecs.rst:1142 +msgid "IBM775" +msgstr "IBM775" + +#: ../../library/codecs.rst:1142 ../../library/codecs.rst:1209 +#: ../../library/codecs.rst:1276 +msgid "Baltic languages" +msgstr "" + +#: ../../library/codecs.rst:1144 +msgid "cp850" +msgstr "cp850" + +#: ../../library/codecs.rst:1144 +msgid "850, IBM850" +msgstr "850, IBM850" + +#: ../../library/codecs.rst:1146 +msgid "cp852" +msgstr "cp852" + +#: ../../library/codecs.rst:1146 +msgid "852, IBM852" +msgstr "852, IBM852" + +#: ../../library/codecs.rst:1146 ../../library/codecs.rst:1194 +#: ../../library/codecs.rst:1255 ../../library/codecs.rst:1305 +msgid "Central and Eastern Europe" +msgstr "" + +#: ../../library/codecs.rst:1148 +msgid "cp855" +msgstr "cp855" + +#: ../../library/codecs.rst:1148 +msgid "855, IBM855" +msgstr "855, IBM855" + +#: ../../library/codecs.rst:1148 ../../library/codecs.rst:1196 +#: ../../library/codecs.rst:1261 ../../library/codecs.rst:1298 +msgid "Belarusian, Bulgarian, Macedonian, Russian, Serbian" +msgstr "" + +#: ../../library/codecs.rst:1151 +msgid "cp856" +msgstr "cp856" + +#: ../../library/codecs.rst:1153 +msgid "cp857" +msgstr "cp857" + +#: ../../library/codecs.rst:1153 +msgid "857, IBM857" +msgstr "857, IBM857" + +#: ../../library/codecs.rst:1153 ../../library/codecs.rst:1186 +#: ../../library/codecs.rst:1203 ../../library/codecs.rst:1270 +#: ../../library/codecs.rst:1310 +msgid "Turkish" +msgstr "土耳其文" + +#: ../../library/codecs.rst:1155 +msgid "cp858" +msgstr "cp858" + +#: ../../library/codecs.rst:1155 +msgid "858, IBM858" +msgstr "858, IBM858" + +#: ../../library/codecs.rst:1157 +msgid "cp860" +msgstr "cp860" + +#: ../../library/codecs.rst:1157 +msgid "860, IBM860" +msgstr "860, IBM860" + +#: ../../library/codecs.rst:1157 +msgid "Portuguese" +msgstr "" + +#: ../../library/codecs.rst:1159 +msgid "cp861" +msgstr "cp861" + +#: ../../library/codecs.rst:1159 +msgid "861, CP-IS, IBM861" +msgstr "861, CP-IS, IBM861" + +#: ../../library/codecs.rst:1159 ../../library/codecs.rst:1303 +msgid "Icelandic" +msgstr "" + +#: ../../library/codecs.rst:1161 +msgid "cp862" +msgstr "cp862" + +#: ../../library/codecs.rst:1161 +msgid "862, IBM862" +msgstr "862, IBM862" + +#: ../../library/codecs.rst:1163 +msgid "cp863" +msgstr "cp863" + +#: ../../library/codecs.rst:1163 +msgid "863, IBM863" +msgstr "863, IBM863" + +#: ../../library/codecs.rst:1163 +msgid "Canadian" +msgstr "" + +#: ../../library/codecs.rst:1165 +msgid "cp864" +msgstr "cp864" + +#: ../../library/codecs.rst:1165 +msgid "IBM864" +msgstr "IBM864" + +#: ../../library/codecs.rst:1167 +msgid "cp865" +msgstr "cp865" + +#: ../../library/codecs.rst:1167 +msgid "865, IBM865" +msgstr "865, IBM865" + +#: ../../library/codecs.rst:1167 +msgid "Danish, Norwegian" +msgstr "" + +#: ../../library/codecs.rst:1169 +msgid "cp866" +msgstr "cp866" + +#: ../../library/codecs.rst:1169 +msgid "866, IBM866" +msgstr "866, IBM866" + +#: ../../library/codecs.rst:1169 ../../library/codecs.rst:1286 +msgid "Russian" +msgstr "俄羅斯文" + +#: ../../library/codecs.rst:1171 +msgid "cp869" +msgstr "cp869" + +#: ../../library/codecs.rst:1171 +msgid "869, CP-GR, IBM869" +msgstr "869, CP-GR, IBM869" + +#: ../../library/codecs.rst:1173 +msgid "cp874" +msgstr "cp874" + +#: ../../library/codecs.rst:1173 +msgid "Thai" +msgstr "泰文" + +#: ../../library/codecs.rst:1175 +msgid "cp875" +msgstr "cp875" + +#: ../../library/codecs.rst:1177 +msgid "cp932" +msgstr "cp932" + +#: ../../library/codecs.rst:1177 +msgid "932, ms932, mskanji, ms-kanji, windows-31j" +msgstr "932, ms932, mskanji, ms-kanji, windows-31j" + +#: ../../library/codecs.rst:1177 ../../library/codecs.rst:1213 +#: ../../library/codecs.rst:1215 ../../library/codecs.rst:1217 +#: ../../library/codecs.rst:1234 ../../library/codecs.rst:1237 +#: ../../library/codecs.rst:1242 ../../library/codecs.rst:1245 +#: ../../library/codecs.rst:1247 ../../library/codecs.rst:1315 +#: ../../library/codecs.rst:1318 ../../library/codecs.rst:1321 +msgid "Japanese" +msgstr "日文" + +#: ../../library/codecs.rst:1180 +msgid "cp949" +msgstr "cp949" + +#: ../../library/codecs.rst:1180 +msgid "949, ms949, uhc" +msgstr "949, ms949, uhc" + +#: ../../library/codecs.rst:1180 ../../library/codecs.rst:1219 +#: ../../library/codecs.rst:1249 ../../library/codecs.rst:1284 +msgid "Korean" +msgstr "韓文" + +#: ../../library/codecs.rst:1182 +msgid "cp950" +msgstr "cp950" + +#: ../../library/codecs.rst:1182 +msgid "950, ms950" +msgstr "950, ms950" + +#: ../../library/codecs.rst:1184 +msgid "cp1006" +msgstr "cp1006" + +#: ../../library/codecs.rst:1184 +msgid "Urdu" +msgstr "" + +#: ../../library/codecs.rst:1186 +msgid "cp1026" +msgstr "cp1026" + +#: ../../library/codecs.rst:1186 +msgid "ibm1026" +msgstr "ibm1026" + +#: ../../library/codecs.rst:1188 +msgid "cp1125" +msgstr "cp1125" + +#: ../../library/codecs.rst:1188 +msgid "1125, ibm1125, cp866u, ruscii" +msgstr "1125, ibm1125, cp866u, ruscii" + +#: ../../library/codecs.rst:1188 ../../library/codecs.rst:1292 +msgid "Ukrainian" +msgstr "烏克蘭文" + +#: ../../library/codecs.rst:1192 +msgid "cp1140" +msgstr "cp1140" + +#: ../../library/codecs.rst:1192 +msgid "ibm1140" +msgstr "ibm1140" + +#: ../../library/codecs.rst:1194 +msgid "cp1250" +msgstr "cp1250" + +#: ../../library/codecs.rst:1194 +msgid "windows-1250" +msgstr "windows-1250" + +#: ../../library/codecs.rst:1196 +msgid "cp1251" +msgstr "cp1251" + +#: ../../library/codecs.rst:1196 +msgid "windows-1251" +msgstr "windows-1251" + +#: ../../library/codecs.rst:1199 +msgid "cp1252" +msgstr "cp1252" + +#: ../../library/codecs.rst:1199 +msgid "windows-1252" +msgstr "windows-1252" + +#: ../../library/codecs.rst:1201 +msgid "cp1253" +msgstr "cp1253" + +#: ../../library/codecs.rst:1201 +msgid "windows-1253" +msgstr "windows-1253" + +#: ../../library/codecs.rst:1203 +msgid "cp1254" +msgstr "cp1254" + +#: ../../library/codecs.rst:1203 +msgid "windows-1254" +msgstr "windows-1254" + +#: ../../library/codecs.rst:1205 +msgid "cp1255" +msgstr "cp1255" + +#: ../../library/codecs.rst:1205 +msgid "windows-1255" +msgstr "windows-1255" + +#: ../../library/codecs.rst:1207 +msgid "cp1256" +msgstr "cp1256" + +#: ../../library/codecs.rst:1207 +msgid "windows-1256" +msgstr "windows-1256" + +#: ../../library/codecs.rst:1209 +msgid "cp1257" +msgstr "cp1257" + +#: ../../library/codecs.rst:1209 +msgid "windows-1257" +msgstr "windows-1257" + +#: ../../library/codecs.rst:1211 +msgid "cp1258" +msgstr "cp1258" + +#: ../../library/codecs.rst:1211 +msgid "windows-1258" +msgstr "windows-1258" + +#: ../../library/codecs.rst:1211 +msgid "Vietnamese" +msgstr "越南文" + +#: ../../library/codecs.rst:1213 +msgid "euc_jp" +msgstr "euc_jp" + +#: ../../library/codecs.rst:1213 +msgid "eucjp, ujis, u-jis" +msgstr "eucjp, ujis, u-jis" + +#: ../../library/codecs.rst:1215 +msgid "euc_jis_2004" +msgstr "euc_jis_2004" + +#: ../../library/codecs.rst:1215 +msgid "jisx0213, eucjis2004" +msgstr "jisx0213, eucjis2004" + +#: ../../library/codecs.rst:1217 +msgid "euc_jisx0213" +msgstr "euc_jisx0213" + +#: ../../library/codecs.rst:1217 +msgid "eucjisx0213" +msgstr "eucjisx0213" + +#: ../../library/codecs.rst:1219 +msgid "euc_kr" +msgstr "euc_kr" + +#: ../../library/codecs.rst:1219 +msgid "euckr, korean, ksc5601, ks_c-5601, ks_c-5601-1987, ksx1001, ks_x-1001" +msgstr "euckr, korean, ksc5601, ks_c-5601, ks_c-5601-1987, ksx1001, ks_x-1001" + +#: ../../library/codecs.rst:1223 +msgid "gb2312" +msgstr "gb2312" + +#: ../../library/codecs.rst:1223 +msgid "" +"chinese, csiso58gb231280, euc-cn, euccn, eucgb2312-cn, gb2312-1980, " +"gb2312-80, iso-ir-58" +msgstr "" +"chinese, csiso58gb231280, euc-cn, euccn, eucgb2312-cn, gb2312-1980, " +"gb2312-80, iso-ir-58" + +#: ../../library/codecs.rst:1223 ../../library/codecs.rst:1232 +msgid "Simplified Chinese" +msgstr "簡體中文" + +#: ../../library/codecs.rst:1228 +msgid "gbk" +msgstr "gbk" + +#: ../../library/codecs.rst:1228 +msgid "936, cp936, ms936" +msgstr "936, cp936, ms936" + +#: ../../library/codecs.rst:1228 ../../library/codecs.rst:1230 +msgid "Unified Chinese" +msgstr "" + +#: ../../library/codecs.rst:1230 +msgid "gb18030" +msgstr "gb18030" + +#: ../../library/codecs.rst:1230 +msgid "gb18030-2000" +msgstr "gb18030-2000" + +#: ../../library/codecs.rst:1232 +msgid "hz" +msgstr "hz" + +#: ../../library/codecs.rst:1232 +msgid "hzgb, hz-gb, hz-gb-2312" +msgstr "hzgb, hz-gb, hz-gb-2312" + +#: ../../library/codecs.rst:1234 +msgid "iso2022_jp" +msgstr "iso2022_jp" + +#: ../../library/codecs.rst:1234 +msgid "csiso2022jp, iso2022jp, iso-2022-jp" +msgstr "csiso2022jp, iso2022jp, iso-2022-jp" + +#: ../../library/codecs.rst:1237 +msgid "iso2022_jp_1" +msgstr "iso2022_jp_1" + +#: ../../library/codecs.rst:1237 +msgid "iso2022jp-1, iso-2022-jp-1" +msgstr "iso2022jp-1, iso-2022-jp-1" + +#: ../../library/codecs.rst:1239 +msgid "iso2022_jp_2" +msgstr "iso2022_jp_2" + +#: ../../library/codecs.rst:1239 +msgid "iso2022jp-2, iso-2022-jp-2" +msgstr "iso2022jp-2, iso-2022-jp-2" + +#: ../../library/codecs.rst:1239 +msgid "Japanese, Korean, Simplified Chinese, Western Europe, Greek" +msgstr "" + +#: ../../library/codecs.rst:1242 +msgid "iso2022_jp_2004" +msgstr "iso2022_jp_2004" + +#: ../../library/codecs.rst:1242 +msgid "iso2022jp-2004, iso-2022-jp-2004" +msgstr "iso2022jp-2004, iso-2022-jp-2004" + +#: ../../library/codecs.rst:1245 +msgid "iso2022_jp_3" +msgstr "iso2022_jp_3" + +#: ../../library/codecs.rst:1245 +msgid "iso2022jp-3, iso-2022-jp-3" +msgstr "iso2022jp-3, iso-2022-jp-3" + +#: ../../library/codecs.rst:1247 +msgid "iso2022_jp_ext" +msgstr "iso2022_jp_ext" + +#: ../../library/codecs.rst:1247 +msgid "iso2022jp-ext, iso-2022-jp-ext" +msgstr "iso2022jp-ext, iso-2022-jp-ext" + +#: ../../library/codecs.rst:1249 +msgid "iso2022_kr" +msgstr "iso2022_kr" + +#: ../../library/codecs.rst:1249 +msgid "csiso2022kr, iso2022kr, iso-2022-kr" +msgstr "csiso2022kr, iso2022kr, iso-2022-kr" + +#: ../../library/codecs.rst:1252 +msgid "latin_1" +msgstr "latin_1" + +#: ../../library/codecs.rst:1252 +msgid "iso-8859-1, iso8859-1, 8859, cp819, latin, latin1, L1" +msgstr "iso-8859-1, iso8859-1, 8859, cp819, latin, latin1, L1" + +#: ../../library/codecs.rst:1255 +msgid "iso8859_2" +msgstr "iso8859_2" + +#: ../../library/codecs.rst:1255 +msgid "iso-8859-2, latin2, L2" +msgstr "iso-8859-2, latin2, L2" + +#: ../../library/codecs.rst:1257 +msgid "iso8859_3" +msgstr "iso8859_3" + +#: ../../library/codecs.rst:1257 +msgid "iso-8859-3, latin3, L3" +msgstr "iso-8859-3, latin3, L3" + +#: ../../library/codecs.rst:1257 +msgid "Esperanto, Maltese" +msgstr "" + +#: ../../library/codecs.rst:1259 +msgid "iso8859_4" +msgstr "iso8859_4" + +#: ../../library/codecs.rst:1259 +msgid "iso-8859-4, latin4, L4" +msgstr "iso-8859-4, latin4, L4" + +#: ../../library/codecs.rst:1259 +msgid "Northern Europe" +msgstr "" + +#: ../../library/codecs.rst:1261 +msgid "iso8859_5" +msgstr "iso8859_5" + +#: ../../library/codecs.rst:1261 +msgid "iso-8859-5, cyrillic" +msgstr "iso-8859-5, cyrillic" + +#: ../../library/codecs.rst:1264 +msgid "iso8859_6" +msgstr "iso8859_6" + +#: ../../library/codecs.rst:1264 +msgid "iso-8859-6, arabic" +msgstr "iso-8859-6, arabic" + +#: ../../library/codecs.rst:1266 +msgid "iso8859_7" +msgstr "iso8859_7" + +#: ../../library/codecs.rst:1266 +msgid "iso-8859-7, greek, greek8" +msgstr "iso-8859-7, greek, greek8" + +#: ../../library/codecs.rst:1268 +msgid "iso8859_8" +msgstr "iso8859_8" + +#: ../../library/codecs.rst:1268 +msgid "iso-8859-8, hebrew" +msgstr "iso-8859-8, hebrew" + +#: ../../library/codecs.rst:1270 +msgid "iso8859_9" +msgstr "iso8859_9" + +#: ../../library/codecs.rst:1270 +msgid "iso-8859-9, latin5, L5" +msgstr "iso-8859-9, latin5, L5" + +#: ../../library/codecs.rst:1272 +msgid "iso8859_10" +msgstr "iso8859_10" + +#: ../../library/codecs.rst:1272 +msgid "iso-8859-10, latin6, L6" +msgstr "iso-8859-10, latin6, L6" + +#: ../../library/codecs.rst:1272 +msgid "Nordic languages" +msgstr "" + +#: ../../library/codecs.rst:1274 +msgid "iso8859_11" +msgstr "iso8859_11" + +#: ../../library/codecs.rst:1274 +msgid "iso-8859-11, thai" +msgstr "iso-8859-11, thai" + +#: ../../library/codecs.rst:1274 +msgid "Thai languages" +msgstr "泰語" + +#: ../../library/codecs.rst:1276 +msgid "iso8859_13" +msgstr "iso8859_13" + +#: ../../library/codecs.rst:1276 +msgid "iso-8859-13, latin7, L7" +msgstr "iso-8859-13, latin7, L7" + +#: ../../library/codecs.rst:1278 +msgid "iso8859_14" +msgstr "iso8859_14" + +#: ../../library/codecs.rst:1278 +msgid "iso-8859-14, latin8, L8" +msgstr "iso-8859-14, latin8, L8" + +#: ../../library/codecs.rst:1278 +msgid "Celtic languages" +msgstr "" + +#: ../../library/codecs.rst:1280 +msgid "iso8859_15" +msgstr "iso8859_15" + +#: ../../library/codecs.rst:1280 +msgid "iso-8859-15, latin9, L9" +msgstr "iso-8859-15, latin9, L9" + +#: ../../library/codecs.rst:1282 +msgid "iso8859_16" +msgstr "iso8859_16" + +#: ../../library/codecs.rst:1282 +msgid "iso-8859-16, latin10, L10" +msgstr "iso-8859-16, latin10, L10" + +#: ../../library/codecs.rst:1282 +msgid "South-Eastern Europe" +msgstr "" + +#: ../../library/codecs.rst:1284 +msgid "johab" +msgstr "" + +#: ../../library/codecs.rst:1284 +msgid "cp1361, ms1361" +msgstr "cp1361, ms1361" + +#: ../../library/codecs.rst:1286 +msgid "koi8_r" +msgstr "koi8_r" + +#: ../../library/codecs.rst:1288 +msgid "koi8_t" +msgstr "koi8_t" + +#: ../../library/codecs.rst:1288 +msgid "Tajik" +msgstr "" + +#: ../../library/codecs.rst:1292 +msgid "koi8_u" +msgstr "koi8_u" + +#: ../../library/codecs.rst:1294 +msgid "kz1048" +msgstr "kz1048" + +#: ../../library/codecs.rst:1294 +msgid "kz_1048, strk1048_2002, rk1048" +msgstr "kz_1048, strk1048_2002, rk1048" + +#: ../../library/codecs.rst:1294 ../../library/codecs.rst:1312 +msgid "Kazakh" +msgstr "" + +#: ../../library/codecs.rst:1298 +msgid "mac_cyrillic" +msgstr "mac_cyrillic" + +#: ../../library/codecs.rst:1298 +msgid "maccyrillic" +msgstr "" + +#: ../../library/codecs.rst:1301 +msgid "mac_greek" +msgstr "mac_greek" + +#: ../../library/codecs.rst:1301 +msgid "macgreek" +msgstr "" + +#: ../../library/codecs.rst:1303 +msgid "mac_iceland" +msgstr "mac_iceland" + +#: ../../library/codecs.rst:1303 +msgid "maciceland" +msgstr "" + +#: ../../library/codecs.rst:1305 +msgid "mac_latin2" +msgstr "mac_latin2" + +#: ../../library/codecs.rst:1305 +msgid "maclatin2, maccentraleurope, mac_centeuro" +msgstr "maclatin2, maccentraleurope, mac_centeuro" + +#: ../../library/codecs.rst:1308 +msgid "mac_roman" +msgstr "mac_roman" + +#: ../../library/codecs.rst:1308 +msgid "macroman, macintosh" +msgstr "macroman, macintosh" + +#: ../../library/codecs.rst:1310 +msgid "mac_turkish" +msgstr "mac_turkish" + +#: ../../library/codecs.rst:1310 +msgid "macturkish" +msgstr "" + +#: ../../library/codecs.rst:1312 +msgid "ptcp154" +msgstr "ptcp154" + +#: ../../library/codecs.rst:1312 +msgid "csptcp154, pt154, cp154, cyrillic-asian" +msgstr "csptcp154, pt154, cp154, cyrillic-asian" + +#: ../../library/codecs.rst:1315 +msgid "shift_jis" +msgstr "shift_jis" + +#: ../../library/codecs.rst:1315 +msgid "csshiftjis, shiftjis, sjis, s_jis" +msgstr "csshiftjis, shiftjis, sjis, s_jis" + +#: ../../library/codecs.rst:1318 +msgid "shift_jis_2004" +msgstr "shift_jis_2004" + +#: ../../library/codecs.rst:1318 +msgid "shiftjis2004, sjis_2004, sjis2004" +msgstr "shiftjis2004, sjis_2004, sjis2004" + +#: ../../library/codecs.rst:1321 +msgid "shift_jisx0213" +msgstr "shift_jisx0213" + +#: ../../library/codecs.rst:1321 +msgid "shiftjisx0213, sjisx0213, s_jisx0213" +msgstr "shiftjisx0213, sjisx0213, s_jisx0213" + +#: ../../library/codecs.rst:1324 +msgid "utf_32" +msgstr "utf_32" + +#: ../../library/codecs.rst:1324 +msgid "U32, utf32" +msgstr "U32, utf32" + +#: ../../library/codecs.rst:1324 ../../library/codecs.rst:1326 +#: ../../library/codecs.rst:1328 ../../library/codecs.rst:1330 +#: ../../library/codecs.rst:1332 ../../library/codecs.rst:1334 +#: ../../library/codecs.rst:1336 ../../library/codecs.rst:1338 +#: ../../library/codecs.rst:1340 +msgid "all languages" +msgstr "" + +#: ../../library/codecs.rst:1326 +msgid "utf_32_be" +msgstr "utf_32_be" + +#: ../../library/codecs.rst:1326 +msgid "UTF-32BE" +msgstr "UTF-32BE" + +#: ../../library/codecs.rst:1328 +msgid "utf_32_le" +msgstr "utf_32_le" + +#: ../../library/codecs.rst:1328 +msgid "UTF-32LE" +msgstr "UTF-32LE" + +#: ../../library/codecs.rst:1330 +msgid "utf_16" +msgstr "utf_16" + +#: ../../library/codecs.rst:1330 +msgid "U16, utf16" +msgstr "U16, utf16" + +#: ../../library/codecs.rst:1332 +msgid "utf_16_be" +msgstr "utf_16_be" + +#: ../../library/codecs.rst:1332 +msgid "UTF-16BE" +msgstr "UTF-16BE" + +#: ../../library/codecs.rst:1334 +msgid "utf_16_le" +msgstr "utf_16_le" + +#: ../../library/codecs.rst:1334 +msgid "UTF-16LE" +msgstr "UTF-16LE" + +#: ../../library/codecs.rst:1336 +msgid "utf_7" +msgstr "utf_7" + +#: ../../library/codecs.rst:1336 +msgid "U7, unicode-1-1-utf-7" +msgstr "U7, unicode-1-1-utf-7" + +#: ../../library/codecs.rst:1338 +msgid "utf_8" +msgstr "utf_8" + +#: ../../library/codecs.rst:1338 +msgid "U8, UTF, utf8, cp65001" +msgstr "U8, UTF, utf8, cp65001" + +#: ../../library/codecs.rst:1340 +msgid "utf_8_sig" +msgstr "utf_8_sig" + +#: ../../library/codecs.rst:1343 +msgid "" +"The utf-16\\* and utf-32\\* encoders no longer allow surrogate code points " +"(``U+D800``--``U+DFFF``) to be encoded. The utf-32\\* decoders no longer " +"decode byte sequences that correspond to surrogate code points." +msgstr "" + +#: ../../library/codecs.rst:1349 +msgid "``cp65001`` is now an alias to ``utf_8``." +msgstr "``cp65001`` 現在是 ``utf_8`` 的別名。" + +#: ../../library/codecs.rst:1352 +msgid "On Windows, ``cpXXX`` codecs are now available for all code pages." +msgstr "" + +#: ../../library/codecs.rst:1357 +msgid "Python Specific Encodings" +msgstr "" + +#: ../../library/codecs.rst:1359 +msgid "" +"A number of predefined codecs are specific to Python, so their codec names " +"have no meaning outside Python. These are listed in the tables below based " +"on the expected input and output types (note that while text encodings are " +"the most common use case for codecs, the underlying codec infrastructure " +"supports arbitrary data transforms rather than just text encodings). For " +"asymmetric codecs, the stated meaning describes the encoding direction." +msgstr "" + +#: ../../library/codecs.rst:1367 +msgid "Text Encodings" +msgstr "" + +#: ../../library/codecs.rst:1369 +msgid "" +"The following codecs provide :class:`str` to :class:`bytes` encoding and :" +"term:`bytes-like object` to :class:`str` decoding, similar to the Unicode " +"text encodings." +msgstr "" + +#: ../../library/codecs.rst:1378 +msgid "idna" +msgstr "idna" + +#: ../../library/codecs.rst:1378 +msgid "" +"Implement :rfc:`3490`, see also :mod:`encodings.idna`. Only " +"``errors='strict'`` is supported." +msgstr "" + +#: ../../library/codecs.rst:1384 +msgid "mbcs" +msgstr "mbcs" + +#: ../../library/codecs.rst:1384 +msgid "ansi, dbcs" +msgstr "ansi, dbcs" + +#: ../../library/codecs.rst:1384 +msgid "" +"Windows only: Encode the operand according to the ANSI codepage (CP_ACP)." +msgstr "" + +#: ../../library/codecs.rst:1388 +msgid "oem" +msgstr "oem" + +#: ../../library/codecs.rst:1388 +msgid "" +"Windows only: Encode the operand according to the OEM codepage (CP_OEMCP)." +msgstr "" + +#: ../../library/codecs.rst:1394 +msgid "palmos" +msgstr "" + +#: ../../library/codecs.rst:1394 +msgid "Encoding of PalmOS 3.5." +msgstr "" + +#: ../../library/codecs.rst:1396 +msgid "punycode" +msgstr "" + +#: ../../library/codecs.rst:1396 +msgid "Implement :rfc:`3492`. Stateful codecs are not supported." +msgstr "" + +#: ../../library/codecs.rst:1400 +msgid "raw_unicode_escape" +msgstr "raw_unicode_escape" + +#: ../../library/codecs.rst:1400 +msgid "" +"Latin-1 encoding with :samp:`\\\\u{XXXX}` and :samp:`\\\\U{XXXXXXXX}` for " +"other code points. Existing backslashes are not escaped in any way. It is " +"used in the Python pickle protocol." +msgstr "" + +#: ../../library/codecs.rst:1410 +msgid "undefined" +msgstr "" + +#: ../../library/codecs.rst:1410 +msgid "This Codec should only be used for testing purposes." +msgstr "" + +#: ../../library/codecs.rst:1414 +msgid "" +"Raise an exception for all conversions, even empty strings. The error " +"handler is ignored." +msgstr "" + +#: ../../library/codecs.rst:1419 +msgid "unicode_escape" +msgstr "unicode_escape" + +#: ../../library/codecs.rst:1419 +msgid "" +"Encoding suitable as the contents of a Unicode literal in ASCII-encoded " +"Python source code, except that quotes are not escaped. Decode from Latin-1 " +"source code. Beware that Python source code actually uses UTF-8 by default." +msgstr "" + +#: ../../library/codecs.rst:1431 +msgid "\"unicode_internal\" codec is removed." +msgstr "" + +#: ../../library/codecs.rst:1438 +msgid "Binary Transforms" +msgstr "" + +#: ../../library/codecs.rst:1440 +msgid "" +"The following codecs provide binary transforms: :term:`bytes-like object` " +"to :class:`bytes` mappings. They are not supported by :meth:`bytes.decode` " +"(which only produces :class:`str` output)." +msgstr "" + +#: ../../library/codecs.rst:1448 +msgid "Encoder / decoder" +msgstr "" + +#: ../../library/codecs.rst:1450 +msgid "base64_codec [#b64]_" +msgstr "base64_codec [#b64]_" + +#: ../../library/codecs.rst:1450 +msgid "base64, base_64" +msgstr "base64, base_64" + +#: ../../library/codecs.rst:1450 +msgid "" +"Convert the operand to multiline MIME base64 (the result always includes a " +"trailing ``'\\n'``)." +msgstr "" + +#: ../../library/codecs.rst:1455 +msgid "" +"accepts any :term:`bytes-like object` as input for encoding and decoding" +msgstr "" + +#: ../../library/codecs.rst:1450 +msgid ":meth:`base64.encodebytes` / :meth:`base64.decodebytes`" +msgstr ":meth:`base64.encodebytes` / :meth:`base64.decodebytes`" + +#: ../../library/codecs.rst:1461 +msgid "bz2_codec" +msgstr "bz2_codec" + +#: ../../library/codecs.rst:1461 +msgid "bz2" +msgstr "bz2" + +#: ../../library/codecs.rst:1461 +msgid "Compress the operand using bz2." +msgstr "" + +#: ../../library/codecs.rst:1461 +msgid ":meth:`bz2.compress` / :meth:`bz2.decompress`" +msgstr ":meth:`bz2.compress` / :meth:`bz2.decompress`" + +#: ../../library/codecs.rst:1464 +msgid "hex_codec" +msgstr "hex_codec" + +#: ../../library/codecs.rst:1464 +msgid "hex" +msgstr "hex" + +#: ../../library/codecs.rst:1464 +msgid "" +"Convert the operand to hexadecimal representation, with two digits per byte." +msgstr "" + +#: ../../library/codecs.rst:1464 +msgid ":meth:`binascii.b2a_hex` / :meth:`binascii.a2b_hex`" +msgstr ":meth:`binascii.b2a_hex` / :meth:`binascii.a2b_hex`" + +#: ../../library/codecs.rst:1469 +msgid "quopri_codec" +msgstr "quopri_codec" + +#: ../../library/codecs.rst:1469 +msgid "quopri, quotedprintable, quoted_printable" +msgstr "quopri, quotedprintable, quoted_printable" + +#: ../../library/codecs.rst:1469 +msgid "Convert the operand to MIME quoted printable." +msgstr "" + +#: ../../library/codecs.rst:1469 +msgid ":meth:`quopri.encode` with ``quotetabs=True`` / :meth:`quopri.decode`" +msgstr ":meth:`quopri.encode` with ``quotetabs=True`` / :meth:`quopri.decode`" + +#: ../../library/codecs.rst:1473 +msgid "uu_codec" +msgstr "uu_codec" + +#: ../../library/codecs.rst:1473 +msgid "uu" +msgstr "uu" + +#: ../../library/codecs.rst:1473 +msgid "Convert the operand using uuencode." +msgstr "" + +#: ../../library/codecs.rst:1476 +msgid "zlib_codec" +msgstr "zlib_codec" + +#: ../../library/codecs.rst:1476 +msgid "zip, zlib" +msgstr "zip, zlib" + +#: ../../library/codecs.rst:1476 +msgid "Compress the operand using gzip." +msgstr "" + +#: ../../library/codecs.rst:1476 +msgid ":meth:`zlib.compress` / :meth:`zlib.decompress`" +msgstr ":meth:`zlib.compress` / :meth:`zlib.decompress`" + +#: ../../library/codecs.rst:1480 +msgid "" +"In addition to :term:`bytes-like objects `, " +"``'base64_codec'`` also accepts ASCII-only instances of :class:`str` for " +"decoding" +msgstr "" + +#: ../../library/codecs.rst:1484 +msgid "Restoration of the binary transforms." +msgstr "" + +#: ../../library/codecs.rst:1487 +msgid "Restoration of the aliases for the binary transforms." +msgstr "" + +#: ../../library/codecs.rst:1494 +msgid "Standalone Codec Functions" +msgstr "" + +#: ../../library/codecs.rst:1496 +msgid "" +"The following functions provide encoding and decoding functionality similar " +"to codecs, but are not available as named codecs through :func:`codecs." +"encode` or :func:`codecs.decode`. They are used internally (for example, by :" +"mod:`pickle`) and behave similarly to the ``string_escape`` codec that was " +"removed in Python 3." +msgstr "" + +#: ../../library/codecs.rst:1503 +msgid "" +"Encode *input* using escape sequences. Similar to how :func:`repr` on bytes " +"produces escaped byte values." +msgstr "" + +#: ../../library/codecs.rst:1506 +msgid "*input* must be a :class:`bytes` object." +msgstr "" + +#: ../../library/codecs.rst:1508 ../../library/codecs.rst:1517 +msgid "" +"Returns a tuple ``(output, length)`` where *output* is a :class:`bytes` " +"object and *length* is the number of bytes consumed." +msgstr "" + +#: ../../library/codecs.rst:1513 +msgid "Decode *input* from escape sequences back to the original bytes." +msgstr "" + +#: ../../library/codecs.rst:1515 +msgid "*input* must be a :term:`bytes-like object`." +msgstr "*input* 必須是個 :term:`bytes-like object`。" + +#: ../../library/codecs.rst:1524 +msgid "Text Transforms" +msgstr "" + +#: ../../library/codecs.rst:1526 +msgid "" +"The following codec provides a text transform: a :class:`str` to :class:" +"`str` mapping. It is not supported by :meth:`str.encode` (which only " +"produces :class:`bytes` output)." +msgstr "" + +#: ../../library/codecs.rst:1535 +msgid "rot_13" +msgstr "rot_13" + +#: ../../library/codecs.rst:1535 +msgid "rot13" +msgstr "" + +#: ../../library/codecs.rst:1535 +msgid "Return the Caesar-cypher encryption of the operand." +msgstr "" + +#: ../../library/codecs.rst:1540 +msgid "Restoration of the ``rot_13`` text transform." +msgstr "" + +#: ../../library/codecs.rst:1543 +msgid "Restoration of the ``rot13`` alias." +msgstr "" + +#: ../../library/codecs.rst:1548 +msgid ":mod:`encodings` --- Encodings package" +msgstr "" + +#: ../../library/codecs.rst:1553 +msgid "This module implements the following functions:" +msgstr "" + +#: ../../library/codecs.rst:1557 +msgid "Normalize encoding name *encoding*." +msgstr "" + +#: ../../library/codecs.rst:1559 +msgid "" +"Normalization works as follows: all non-alphanumeric characters except the " +"dot used for Python package names are collapsed and replaced with a single " +"underscore, leading and trailing underscores are removed. For example, ``' " +"-;#'`` becomes ``'_'``." +msgstr "" + +#: ../../library/codecs.rst:1564 +msgid "Note that *encoding* should be ASCII only." +msgstr "" + +#: ../../library/codecs.rst:1568 +msgid "" +"The following functions should not be used directly, except for testing " +"purposes; :func:`codecs.lookup` should be used instead." +msgstr "" + +#: ../../library/codecs.rst:1574 +msgid "" +"Search for the codec module corresponding to the given encoding name " +"*encoding*." +msgstr "" + +#: ../../library/codecs.rst:1577 +msgid "" +"This function first normalizes the *encoding* using :func:" +"`normalize_encoding`, then looks for a corresponding alias. It attempts to " +"import a codec module from the encodings package using either the alias or " +"the normalized name. If the module is found and defines a valid " +"``getregentry()`` function that returns a :class:`codecs.CodecInfo` object, " +"the codec is cached and returned." +msgstr "" + +#: ../../library/codecs.rst:1584 +msgid "" +"If the codec module defines a ``getaliases()`` function any returned aliases " +"are registered for future use." +msgstr "" + +#: ../../library/codecs.rst:1590 +msgid "" +"Search for a Windows code page encoding *encoding* of the form ``cpXXXX``." +msgstr "" + +#: ../../library/codecs.rst:1592 +msgid "" +"If the code page is valid and supported, return a :class:`codecs.CodecInfo` " +"object for it." +msgstr "" + +#: ../../library/codecs.rst:1595 ../../library/codecs.rst:1681 +msgid "Availability" +msgstr "可用性" + +#: ../../library/codecs.rst:1600 +msgid "This module implements the following exception:" +msgstr "" + +#: ../../library/codecs.rst:1604 +msgid "Raised when a codec is invalid or incompatible." +msgstr "" + +#: ../../library/codecs.rst:1608 +msgid "" +":mod:`encodings.idna` --- Internationalized Domain Names in Applications" +msgstr "" + +#: ../../library/codecs.rst:1614 +msgid "" +"This module implements :rfc:`3490` (Internationalized Domain Names in " +"Applications) and :rfc:`3492` (Nameprep: A Stringprep Profile for " +"Internationalized Domain Names (IDN)). It builds upon the ``punycode`` " +"encoding and :mod:`stringprep`." +msgstr "" + +#: ../../library/codecs.rst:1619 +msgid "" +"If you need the IDNA 2008 standard from :rfc:`5891` and :rfc:`5895`, use the " +"third-party :pypi:`idna` module." +msgstr "" + +#: ../../library/codecs.rst:1622 +msgid "" +"These RFCs together define a protocol to support non-ASCII characters in " +"domain names. A domain name containing non-ASCII characters (such as ``www." +"Alliancefrançaise.nu``) is converted into an ASCII-compatible encoding (ACE, " +"such as ``www.xn--alliancefranaise-npb.nu``). The ACE form of the domain " +"name is then used in all places where arbitrary characters are not allowed " +"by the protocol, such as DNS queries, HTTP :mailheader:`Host` fields, and so " +"on. This conversion is carried out in the application; if possible invisible " +"to the user: The application should transparently convert Unicode domain " +"labels to IDNA on the wire, and convert back ACE labels to Unicode before " +"presenting them to the user." +msgstr "" + +#: ../../library/codecs.rst:1633 +msgid "" +"Python supports this conversion in several ways: the ``idna`` codec " +"performs conversion between Unicode and ACE, separating an input string into " +"labels based on the separator characters defined in :rfc:`section 3.1 of RFC " +"3490 <3490#section-3.1>` and converting each label to ACE as required, and " +"conversely separating an input byte string into labels based on the ``.`` " +"separator and converting any ACE labels found into unicode. Furthermore, " +"the :mod:`socket` module transparently converts Unicode host names to ACE, " +"so that applications need not be concerned about converting host names " +"themselves when they pass them to the socket module. On top of that, modules " +"that have host names as function parameters, such as :mod:`http.client` and :" +"mod:`ftplib`, accept Unicode host names (:mod:`http.client` then also " +"transparently sends an IDNA hostname in the :mailheader:`Host` field if it " +"sends that field at all)." +msgstr "" + +#: ../../library/codecs.rst:1646 +msgid "" +"When receiving host names from the wire (such as in reverse name lookup), no " +"automatic conversion to Unicode is performed: applications wishing to " +"present such host names to the user should decode them to Unicode." +msgstr "" + +#: ../../library/codecs.rst:1650 +msgid "" +"The module :mod:`encodings.idna` also implements the nameprep procedure, " +"which performs certain normalizations on host names, to achieve case-" +"insensitivity of international domain names, and to unify similar " +"characters. The nameprep functions can be used directly if desired." +msgstr "" + +#: ../../library/codecs.rst:1658 +msgid "" +"Return the nameprepped version of *label*. The implementation currently " +"assumes query strings, so ``AllowUnassigned`` is true." +msgstr "" + +#: ../../library/codecs.rst:1664 +msgid "" +"Convert a label to ASCII, as specified in :rfc:`3490`. ``UseSTD3ASCIIRules`` " +"is assumed to be false." +msgstr "" + +#: ../../library/codecs.rst:1670 +msgid "Convert a label to Unicode, as specified in :rfc:`3490`." +msgstr "" + +#: ../../library/codecs.rst:1674 +msgid ":mod:`encodings.mbcs` --- Windows ANSI codepage" +msgstr ":mod:`encodings.mbcs` --- Windows ANSI 碼頁" + +#: ../../library/codecs.rst:1679 +msgid "This module implements the ANSI codepage (CP_ACP)." +msgstr "這個模組實作了 ANSI 碼頁 (CP_ACP)。" + +#: ../../library/codecs.rst:1683 +msgid "" +"Before 3.2, the *errors* argument was ignored; ``'replace'`` was always used " +"to encode, and ``'ignore'`` to decode." +msgstr "" + +#: ../../library/codecs.rst:1687 +msgid "Support any error handler." +msgstr "" + +#: ../../library/codecs.rst:1692 +msgid ":mod:`encodings.utf_8_sig` --- UTF-8 codec with BOM signature" +msgstr "" + +#: ../../library/codecs.rst:1698 +msgid "" +"This module implements a variant of the UTF-8 codec. On encoding, a UTF-8 " +"encoded BOM will be prepended to the UTF-8 encoded bytes. For the stateful " +"encoder this is only done once (on the first write to the byte stream). On " +"decoding, an optional UTF-8 encoded BOM at the start of the data will be " +"skipped." +msgstr "" + +#: ../../library/codecs.rst:13 +msgid "Unicode" +msgstr "Unicode" + +#: ../../library/codecs.rst:13 +msgid "encode" +msgstr "encode（編碼）" + +#: ../../library/codecs.rst:13 +msgid "decode" +msgstr "decode（解碼）" + +#: ../../library/codecs.rst:13 +msgid "streams" +msgstr "streams（串流）" + +#: ../../library/codecs.rst:13 +msgid "stackable" +msgstr "stackable（可堆疊）" + +#: ../../library/codecs.rst:338 +msgid "strict" +msgstr "strict" + +#: ../../library/codecs.rst:338 ../../library/codecs.rst:390 +#: ../../library/codecs.rst:413 +msgid "error handler's name" +msgstr "error handler's name（錯誤處理器名稱）" + +#: ../../library/codecs.rst:338 +msgid "ignore" +msgstr "ignore" + +#: ../../library/codecs.rst:338 +msgid "replace" +msgstr "replace" + +#: ../../library/codecs.rst:338 +msgid "backslashreplace" +msgstr "backslashreplace" + +#: ../../library/codecs.rst:338 +msgid "surrogateescape" +msgstr "surrogateescape" + +#: ../../library/codecs.rst:338 +msgid "? (question mark)" +msgstr "? （問號）" + +#: ../../library/codecs.rst:338 +msgid "replacement character" +msgstr "replacement character（替代字元）" + +#: ../../library/codecs.rst:338 +msgid "\\ (backslash)" +msgstr "\\ （反斜線）" + +#: ../../library/codecs.rst:338 ../../library/codecs.rst:390 +msgid "escape sequence" +msgstr "escape sequence（跳脫序列）" + +#: ../../library/codecs.rst:338 +msgid "\\x" +msgstr "\\x" + +#: ../../library/codecs.rst:338 +msgid "\\u" +msgstr "\\u" + +#: ../../library/codecs.rst:338 +msgid "\\U" +msgstr "\\U" + +#: ../../library/codecs.rst:390 +msgid "xmlcharrefreplace" +msgstr "xmlcharrefreplace" + +#: ../../library/codecs.rst:390 +msgid "namereplace" +msgstr "namereplace" + +#: ../../library/codecs.rst:390 +msgid "\\N" +msgstr "\\N" + +#: ../../library/codecs.rst:413 +msgid "surrogatepass" +msgstr "surrogatepass" diff --git a/library/codeop.po b/library/codeop.po index 61d65f1399..7457f9b49d 100644 --- a/library/codeop.po +++ b/library/codeop.po @@ -1,143 +1,143 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Liang-Bo Wang , 2016 -# Matt Wang , 2024 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-05-09 00:03+0000\n" -"PO-Revision-Date: 2024-09-24 20:28+0000\n" -"Last-Translator: Matt Wang \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/codeop.rst:2 -msgid ":mod:`!codeop` --- Compile Python code" -msgstr ":mod:`!codeop` --- 編譯 Python 程式碼" - -#: ../../library/codeop.rst:10 -msgid "**Source code:** :source:`Lib/codeop.py`" -msgstr "**原始碼：**\\ :source:`Lib/codeop.py`" - -#: ../../library/codeop.rst:14 -msgid "" -"The :mod:`codeop` module provides utilities upon which the Python read-eval-" -"print loop can be emulated, as is done in the :mod:`code` module. As a " -"result, you probably don't want to use the module directly; if you want to " -"include such a loop in your program you probably want to use the :mod:`code` " -"module instead." -msgstr "" -":mod:`codeop` 模組提供了可以模擬 Python read-eval-print 循環的工具程式 " -"(utilities)，就像在 :mod:`code` 模組中所做的那樣。因此你可能不想直接使用該模" -"組；如果你想在程式中包含這樣的循環，你可能需要使用 :mod:`code` 模組。" - -#: ../../library/codeop.rst:20 -msgid "There are two parts to this job:" -msgstr "這個任務有兩個部分：" - -#: ../../library/codeop.rst:22 -msgid "" -"Being able to tell if a line of input completes a Python statement: in " -"short, telling whether to print '``>>>``' or '``...``' next." -msgstr "" -"能夠判斷一列輸入是否完成了一項 Python 陳述式：簡而言之，判斷接下來是列印 " -"'``>>>``' 還是 '``...``'。" - -#: ../../library/codeop.rst:25 -msgid "" -"Remembering which future statements the user has entered, so subsequent " -"input can be compiled with these in effect." -msgstr "" -"記住使用者輸入了哪些未來陳述式，以便後續輸入可以在這些陳述式生效的情況下進行" -"編譯。" - -#: ../../library/codeop.rst:28 -msgid "" -"The :mod:`codeop` module provides a way of doing each of these things, and a " -"way of doing them both." -msgstr "" -":mod:`codeop` 模組提供了一種完成上述每項任務的方法，以及同時完成這兩項任務的" -"方法。" - -#: ../../library/codeop.rst:31 -msgid "To do just the former:" -msgstr "只做前者：" - -#: ../../library/codeop.rst:35 -msgid "" -"Tries to compile *source*, which should be a string of Python code and " -"return a code object if *source* is valid Python code. In that case, the " -"filename attribute of the code object will be *filename*, which defaults to " -"``''``. Returns ``None`` if *source* is *not* valid Python code, but " -"is a prefix of valid Python code." -msgstr "" -"嘗試編譯 *source*，它應該是 Python 程式碼的字串，如果 *source* 是有效的 " -"Python 程式碼，則回傳一個程式碼物件 (code object)。在這種情況下，程式碼物件的" -"檔案名稱屬性將為 *filename*，預設為 ``''``。如果 *source* 不是有效的 " -"Python 程式碼，而是有效 Python 程式碼的前綴，則回傳 ``None``。" - -#: ../../library/codeop.rst:41 -msgid "" -"If there is a problem with *source*, an exception will be raised. :exc:" -"`SyntaxError` is raised if there is invalid Python syntax, and :exc:" -"`OverflowError` or :exc:`ValueError` if there is an invalid literal." -msgstr "" -"如果 *source* 有問題，就會引發例外。如果存在無效的 Python 語法則會引發 :exc:" -"`SyntaxError`；如果存在無效的文字 (literal)，則會引發 :exc:`OverflowError` " -"或 :exc:`ValueError`。" - -#: ../../library/codeop.rst:45 -msgid "" -"The *symbol* argument determines whether *source* is compiled as a statement " -"(``'single'``, the default), as a sequence of :term:`statement` (``'exec'``) " -"or as an :term:`expression` (``'eval'``). Any other value will cause :exc:" -"`ValueError` to be raised." -msgstr "" -"*symbol* 引數決定 *source* 是否編譯為陳述式（``'single'``，為預設值）、為\\ :" -"term:`陳述式 `\\ 序列 (``'exec'``) 或為\\ :term:`運算式 " -"` (``'eval'``)。任何其他值都會導致引發 :exc:`ValueError`。" - -#: ../../library/codeop.rst:52 -msgid "" -"It is possible (but not likely) that the parser stops parsing with a " -"successful outcome before reaching the end of the source; in this case, " -"trailing symbols may be ignored instead of causing an error. For example, a " -"backslash followed by two newlines may be followed by arbitrary garbage. " -"This will be fixed once the API for the parser is better." -msgstr "" -"剖析器 (parser) 有可能（但通常不會）在到達原始碼的結尾之前停止剖析並獲得成功" -"的結果；在這種情況下，尾隨符號可能會被忽略而不是導致錯誤。例如，反斜線後面加" -"上兩個換行符號後可以是任意的無意義符號。這個問題在未來會因為剖析器 API 的改善" -"而被解決。" - -#: ../../library/codeop.rst:61 -msgid "" -"Instances of this class have :meth:`~object.__call__` methods identical in " -"signature to the built-in function :func:`compile`, but with the difference " -"that if the instance compiles program text containing a :mod:`__future__` " -"statement, the instance 'remembers' and compiles all subsequent program " -"texts with the statement in force." -msgstr "" -"此類別的實例具有 :meth:`~object.__call__` 方法，其簽名與內建函式 :func:" -"`compile` 相同，區別在於如果實例編譯包含 :mod:`__future__` 陳述式的程式文本，" -"實例會「記住」並使用該陳述式開始編譯所有後續程式文本。" - -#: ../../library/codeop.rst:70 -msgid "" -"Instances of this class have :meth:`~object.__call__` methods identical in " -"signature to :func:`compile_command`; the difference is that if the instance " -"compiles program text containing a :mod:`__future__` statement, the instance " -"'remembers' and compiles all subsequent program texts with the statement in " -"force." -msgstr "" -"此類別的實例具有 :meth:`~object.__call__` 方法，其簽名與內建函式 :func:" -"`compile_command` 相同，區別在於如果實例編譯包含 :mod:`__future__` 陳述式的程" -"式文本，實例會「記住」並使用該陳述式開始編譯所有後續程式文本。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Liang-Bo Wang , 2016 +# Matt Wang , 2024 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-05-09 00:03+0000\n" +"PO-Revision-Date: 2024-09-24 20:28+0000\n" +"Last-Translator: Matt Wang \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/codeop.rst:2 +msgid ":mod:`!codeop` --- Compile Python code" +msgstr ":mod:`!codeop` --- 編譯 Python 程式碼" + +#: ../../library/codeop.rst:10 +msgid "**Source code:** :source:`Lib/codeop.py`" +msgstr "**原始碼：**\\ :source:`Lib/codeop.py`" + +#: ../../library/codeop.rst:14 +msgid "" +"The :mod:`codeop` module provides utilities upon which the Python read-eval-" +"print loop can be emulated, as is done in the :mod:`code` module. As a " +"result, you probably don't want to use the module directly; if you want to " +"include such a loop in your program you probably want to use the :mod:`code` " +"module instead." +msgstr "" +":mod:`codeop` 模組提供了可以模擬 Python read-eval-print 循環的工具程式 " +"(utilities)，就像在 :mod:`code` 模組中所做的那樣。因此你可能不想直接使用該模" +"組；如果你想在程式中包含這樣的循環，你可能需要使用 :mod:`code` 模組。" + +#: ../../library/codeop.rst:20 +msgid "There are two parts to this job:" +msgstr "這個任務有兩個部分：" + +#: ../../library/codeop.rst:22 +msgid "" +"Being able to tell if a line of input completes a Python statement: in " +"short, telling whether to print '``>>>``' or '``...``' next." +msgstr "" +"能夠判斷一列輸入是否完成了一項 Python 陳述式：簡而言之，判斷接下來是列印 " +"'``>>>``' 還是 '``...``'。" + +#: ../../library/codeop.rst:25 +msgid "" +"Remembering which future statements the user has entered, so subsequent " +"input can be compiled with these in effect." +msgstr "" +"記住使用者輸入了哪些未來陳述式，以便後續輸入可以在這些陳述式生效的情況下進行" +"編譯。" + +#: ../../library/codeop.rst:28 +msgid "" +"The :mod:`codeop` module provides a way of doing each of these things, and a " +"way of doing them both." +msgstr "" +":mod:`codeop` 模組提供了一種完成上述每項任務的方法，以及同時完成這兩項任務的" +"方法。" + +#: ../../library/codeop.rst:31 +msgid "To do just the former:" +msgstr "只做前者：" + +#: ../../library/codeop.rst:35 +msgid "" +"Tries to compile *source*, which should be a string of Python code and " +"return a code object if *source* is valid Python code. In that case, the " +"filename attribute of the code object will be *filename*, which defaults to " +"``''``. Returns ``None`` if *source* is *not* valid Python code, but " +"is a prefix of valid Python code." +msgstr "" +"嘗試編譯 *source*，它應該是 Python 程式碼的字串，如果 *source* 是有效的 " +"Python 程式碼，則回傳一個程式碼物件 (code object)。在這種情況下，程式碼物件的" +"檔案名稱屬性將為 *filename*，預設為 ``''``。如果 *source* 不是有效的 " +"Python 程式碼，而是有效 Python 程式碼的前綴，則回傳 ``None``。" + +#: ../../library/codeop.rst:41 +msgid "" +"If there is a problem with *source*, an exception will be raised. :exc:" +"`SyntaxError` is raised if there is invalid Python syntax, and :exc:" +"`OverflowError` or :exc:`ValueError` if there is an invalid literal." +msgstr "" +"如果 *source* 有問題，就會引發例外。如果存在無效的 Python 語法則會引發 :exc:" +"`SyntaxError`；如果存在無效的文字 (literal)，則會引發 :exc:`OverflowError` " +"或 :exc:`ValueError`。" + +#: ../../library/codeop.rst:45 +msgid "" +"The *symbol* argument determines whether *source* is compiled as a statement " +"(``'single'``, the default), as a sequence of :term:`statement` (``'exec'``) " +"or as an :term:`expression` (``'eval'``). Any other value will cause :exc:" +"`ValueError` to be raised." +msgstr "" +"*symbol* 引數決定 *source* 是否編譯為陳述式（``'single'``，為預設值）、為\\ :" +"term:`陳述式 `\\ 序列 (``'exec'``) 或為\\ :term:`運算式 " +"` (``'eval'``)。任何其他值都會導致引發 :exc:`ValueError`。" + +#: ../../library/codeop.rst:52 +msgid "" +"It is possible (but not likely) that the parser stops parsing with a " +"successful outcome before reaching the end of the source; in this case, " +"trailing symbols may be ignored instead of causing an error. For example, a " +"backslash followed by two newlines may be followed by arbitrary garbage. " +"This will be fixed once the API for the parser is better." +msgstr "" +"剖析器 (parser) 有可能（但通常不會）在到達原始碼的結尾之前停止剖析並獲得成功" +"的結果；在這種情況下，尾隨符號可能會被忽略而不是導致錯誤。例如，反斜線後面加" +"上兩個換行符號後可以是任意的無意義符號。這個問題在未來會因為剖析器 API 的改善" +"而被解決。" + +#: ../../library/codeop.rst:61 +msgid "" +"Instances of this class have :meth:`~object.__call__` methods identical in " +"signature to the built-in function :func:`compile`, but with the difference " +"that if the instance compiles program text containing a :mod:`__future__` " +"statement, the instance 'remembers' and compiles all subsequent program " +"texts with the statement in force." +msgstr "" +"此類別的實例具有 :meth:`~object.__call__` 方法，其簽名與內建函式 :func:" +"`compile` 相同，區別在於如果實例編譯包含 :mod:`__future__` 陳述式的程式文本，" +"實例會「記住」並使用該陳述式開始編譯所有後續程式文本。" + +#: ../../library/codeop.rst:70 +msgid "" +"Instances of this class have :meth:`~object.__call__` methods identical in " +"signature to :func:`compile_command`; the difference is that if the instance " +"compiles program text containing a :mod:`__future__` statement, the instance " +"'remembers' and compiles all subsequent program texts with the statement in " +"force." +msgstr "" +"此類別的實例具有 :meth:`~object.__call__` 方法，其簽名與內建函式 :func:" +"`compile_command` 相同，區別在於如果實例編譯包含 :mod:`__future__` 陳述式的程" +"式文本，實例會「記住」並使用該陳述式開始編譯所有後續程式文本。" diff --git a/library/collections.abc.po b/library/collections.abc.po index b999edb5cc..aa647a4166 100644 --- a/library/collections.abc.po +++ b/library/collections.abc.po @@ -1,834 +1,834 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-10-08 00:15+0000\n" -"PO-Revision-Date: 2018-05-23 14:41+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/collections.abc.rst:2 -msgid ":mod:`!collections.abc` --- Abstract Base Classes for Containers" -msgstr ":mod:`!collections.abc` --- 容器的抽象基底類別" - -#: ../../library/collections.abc.rst:10 -msgid "Formerly, this module was part of the :mod:`collections` module." -msgstr "過去此模組是 :mod:`collections` 模組的一部分。" - -#: ../../library/collections.abc.rst:13 -msgid "**Source code:** :source:`Lib/_collections_abc.py`" -msgstr "**原始碼：**\\ :source:`Lib/_collections_abc.py`" - -#: ../../library/collections.abc.rst:23 -msgid "" -"This module provides :term:`abstract base classes ` " -"that can be used to test whether a class provides a particular interface; " -"for example, whether it is :term:`hashable` or whether it is a :term:" -"`mapping`." -msgstr "" - -#: ../../library/collections.abc.rst:27 -msgid "" -"An :func:`issubclass` or :func:`isinstance` test for an interface works in " -"one of three ways." -msgstr "" - -#: ../../library/collections.abc.rst:30 -msgid "" -"A newly written class can inherit directly from one of the abstract base " -"classes. The class must supply the required abstract methods. The " -"remaining mixin methods come from inheritance and can be overridden if " -"desired. Other methods may be added as needed:" -msgstr "" - -#: ../../library/collections.abc.rst:35 -msgid "" -"class C(Sequence): # Direct inheritance\n" -" def __init__(self): ... # Extra method not required by the " -"ABC\n" -" def __getitem__(self, index): ... # Required abstract method\n" -" def __len__(self): ... # Required abstract method\n" -" def count(self, value): ... # Optionally override a mixin method" -msgstr "" - -#: ../../library/collections.abc.rst:43 -msgid "" -">>> issubclass(C, Sequence)\n" -"True\n" -">>> isinstance(C(), Sequence)\n" -"True" -msgstr "" -">>> issubclass(C, Sequence)\n" -"True\n" -">>> isinstance(C(), Sequence)\n" -"True" - -#: ../../library/collections.abc.rst:50 -msgid "" -"Existing classes and built-in classes can be registered as \"virtual " -"subclasses\" of the ABCs. Those classes should define the full API " -"including all of the abstract methods and all of the mixin methods. This " -"lets users rely on :func:`issubclass` or :func:`isinstance` tests to " -"determine whether the full interface is supported. The exception to this " -"rule is for methods that are automatically inferred from the rest of the API:" -msgstr "" - -#: ../../library/collections.abc.rst:58 -msgid "" -"class D: # No inheritance\n" -" def __init__(self): ... # Extra method not required by the " -"ABC\n" -" def __getitem__(self, index): ... # Abstract method\n" -" def __len__(self): ... # Abstract method\n" -" def count(self, value): ... # Mixin method\n" -" def index(self, value): ... # Mixin method\n" -"\n" -"Sequence.register(D) # Register instead of inherit" -msgstr "" - -#: ../../library/collections.abc.rst:69 -msgid "" -">>> issubclass(D, Sequence)\n" -"True\n" -">>> isinstance(D(), Sequence)\n" -"True" -msgstr "" -">>> issubclass(D, Sequence)\n" -"True\n" -">>> isinstance(D(), Sequence)\n" -"True" - -#: ../../library/collections.abc.rst:76 -msgid "" -"In this example, class :class:`!D` does not need to define ``__contains__``, " -"``__iter__``, and ``__reversed__`` because the :ref:`in-operator " -"`, the :term:`iteration ` logic, and the :func:" -"`reversed` function automatically fall back to using ``__getitem__`` and " -"``__len__``." -msgstr "" - -#: ../../library/collections.abc.rst:82 -msgid "" -"Some simple interfaces are directly recognizable by the presence of the " -"required methods (unless those methods have been set to :const:`None`):" -msgstr "" - -#: ../../library/collections.abc.rst:85 -msgid "" -"class E:\n" -" def __iter__(self): ...\n" -" def __next__(self): ..." -msgstr "" -"class E:\n" -" def __iter__(self): ...\n" -" def __next__(self): ..." - -#: ../../library/collections.abc.rst:91 -msgid "" -">>> issubclass(E, Iterable)\n" -"True\n" -">>> isinstance(E(), Iterable)\n" -"True" -msgstr "" -">>> issubclass(E, Iterable)\n" -"True\n" -">>> isinstance(E(), Iterable)\n" -"True" - -#: ../../library/collections.abc.rst:98 -msgid "" -"Complex interfaces do not support this last technique because an interface " -"is more than just the presence of method names. Interfaces specify " -"semantics and relationships between methods that cannot be inferred solely " -"from the presence of specific method names. For example, knowing that a " -"class supplies ``__getitem__``, ``__len__``, and ``__iter__`` is " -"insufficient for distinguishing a :class:`Sequence` from a :class:`Mapping`." -msgstr "" - -#: ../../library/collections.abc.rst:106 -msgid "" -"These abstract classes now support ``[]``. See :ref:`types-genericalias` " -"and :pep:`585`." -msgstr "" - -#: ../../library/collections.abc.rst:113 -msgid "Collections Abstract Base Classes" -msgstr "" - -#: ../../library/collections.abc.rst:115 -msgid "" -"The collections module offers the following :term:`ABCs `:" -msgstr "" - -#: ../../library/collections.abc.rst:120 -msgid "ABC" -msgstr "ABC" - -#: ../../library/collections.abc.rst:120 -msgid "Inherits from" -msgstr "" - -#: ../../library/collections.abc.rst:120 -msgid "Abstract Methods" -msgstr "抽象方法" - -#: ../../library/collections.abc.rst:120 -msgid "Mixin Methods" -msgstr "" - -#: ../../library/collections.abc.rst:122 -msgid ":class:`Container` [1]_" -msgstr ":class:`Container` [1]_" - -#: ../../library/collections.abc.rst:122 -msgid "``__contains__``" -msgstr "``__contains__``" - -#: ../../library/collections.abc.rst:123 -msgid ":class:`Hashable` [1]_" -msgstr ":class:`Hashable` [1]_" - -#: ../../library/collections.abc.rst:123 -msgid "``__hash__``" -msgstr "``__hash__``" - -#: ../../library/collections.abc.rst:124 -msgid ":class:`Iterable` [1]_ [2]_" -msgstr ":class:`Iterable` [1]_ [2]_" - -#: ../../library/collections.abc.rst:124 ../../library/collections.abc.rst:125 -msgid "``__iter__``" -msgstr "``__iter__``" - -#: ../../library/collections.abc.rst:125 -msgid ":class:`Iterator` [1]_" -msgstr ":class:`Iterator` [1]_" - -#: ../../library/collections.abc.rst:125 ../../library/collections.abc.rst:126 -msgid ":class:`Iterable`" -msgstr ":class:`Iterable`" - -#: ../../library/collections.abc.rst:125 -msgid "``__next__``" -msgstr "``__next__``" - -#: ../../library/collections.abc.rst:126 -msgid ":class:`Reversible` [1]_" -msgstr ":class:`Reversible` [1]_" - -#: ../../library/collections.abc.rst:126 -msgid "``__reversed__``" -msgstr "``__reversed__``" - -#: ../../library/collections.abc.rst:127 -msgid ":class:`Generator` [1]_" -msgstr ":class:`Generator` [1]_" - -#: ../../library/collections.abc.rst:127 -msgid ":class:`Iterator`" -msgstr ":class:`Iterator`" - -#: ../../library/collections.abc.rst:127 ../../library/collections.abc.rst:176 -msgid "``send``, ``throw``" -msgstr "``send``、``throw``" - -#: ../../library/collections.abc.rst:127 -msgid "``close``, ``__iter__``, ``__next__``" -msgstr "``close``、``__iter__``、``__next__``" - -#: ../../library/collections.abc.rst:128 -msgid ":class:`Sized` [1]_" -msgstr ":class:`Sized` [1]_" - -#: ../../library/collections.abc.rst:128 -msgid "``__len__``" -msgstr "``__len__``" - -#: ../../library/collections.abc.rst:129 -msgid ":class:`Callable` [1]_" -msgstr ":class:`Callable` [1]_" - -#: ../../library/collections.abc.rst:129 -msgid "``__call__``" -msgstr "``__call__``" - -#: ../../library/collections.abc.rst:130 -msgid ":class:`Collection` [1]_" -msgstr ":class:`Collection` [1]_" - -#: ../../library/collections.abc.rst:130 -msgid ":class:`Sized`, :class:`Iterable`, :class:`Container`" -msgstr ":class:`Sized`、:class:`Iterable`、:class:`Container`" - -#: ../../library/collections.abc.rst:130 ../../library/collections.abc.rst:146 -msgid "``__contains__``, ``__iter__``, ``__len__``" -msgstr "``__contains__``、``__iter__``、``__len__``" - -#: ../../library/collections.abc.rst:134 ../../library/collections.abc.rst:137 -#: ../../library/collections.abc.rst:143 -msgid ":class:`Sequence`" -msgstr ":class:`Sequence`" - -#: ../../library/collections.abc.rst:134 -msgid ":class:`Reversible`, :class:`Collection`" -msgstr ":class:`Reversible`, :class:`Collection`" - -#: ../../library/collections.abc.rst:134 ../../library/collections.abc.rst:143 -msgid "``__getitem__``, ``__len__``" -msgstr "``__getitem__``、``__len__``" - -#: ../../library/collections.abc.rst:134 -msgid "" -"``__contains__``, ``__iter__``, ``__reversed__``, ``index``, and ``count``" -msgstr "" -"``__contains__``、``__iter__``、``__reversed__``、``index`` 和 ``count``" - -#: ../../library/collections.abc.rst:137 -msgid ":class:`MutableSequence`" -msgstr ":class:`MutableSequence`" - -#: ../../library/collections.abc.rst:137 -msgid "" -"``__getitem__``, ``__setitem__``, ``__delitem__``, ``__len__``, ``insert``" -msgstr "" -"``__getitem__``、``__setitem__``、``__delitem__``、``__len__``、``insert``" - -#: ../../library/collections.abc.rst:137 -msgid "" -"Inherited :class:`Sequence` methods and ``append``, ``clear``, ``reverse``, " -"``extend``, ``pop``, ``remove``, and ``__iadd__``" -msgstr "" -"繼承 :class:`Sequence` 方法和 ``append``、``clear``、``reverse``、``extend``、" -"``pop``、``remove`` 和 ``__iadd__``" - -#: ../../library/collections.abc.rst:143 -msgid ":class:`ByteString`" -msgstr ":class:`ByteString`" - -#: ../../library/collections.abc.rst:143 -msgid "Inherited :class:`Sequence` methods" -msgstr ":class:`Sequence` 的繼承方法" - -#: ../../library/collections.abc.rst:146 ../../library/collections.abc.rst:151 -msgid ":class:`Set`" -msgstr ":class:`Set`" - -#: ../../library/collections.abc.rst:146 ../../library/collections.abc.rst:157 -msgid ":class:`Collection`" -msgstr ":class:`Collection`" - -#: ../../library/collections.abc.rst:146 -msgid "" -"``__le__``, ``__lt__``, ``__eq__``, ``__ne__``, ``__gt__``, ``__ge__``, " -"``__and__``, ``__or__``, ``__sub__``, ``__rsub__``, ``__xor__``, " -"``__rxor__`` and ``isdisjoint``" -msgstr "" -"``__le__``、``__lt__``、``__eq__``、``__ne__``、``__gt__``、``__ge__``、" -"``__and__``、``__or__``、``__sub__``、``__rsub__``、``__xor__``、" -"``__rxor__`` 和 ``isdisjoint``" - -#: ../../library/collections.abc.rst:151 -msgid ":class:`MutableSet`" -msgstr ":class:`MutableSet`" - -#: ../../library/collections.abc.rst:151 -msgid "``__contains__``, ``__iter__``, ``__len__``, ``add``, ``discard``" -msgstr "``__contains__``、``__iter__``、``__len__``、``add``、``discard``" - -#: ../../library/collections.abc.rst:151 -msgid "" -"Inherited :class:`Set` methods and ``clear``, ``pop``, ``remove``, " -"``__ior__``, ``__iand__``, ``__ixor__``, and ``__isub__``" -msgstr "" - -#: ../../library/collections.abc.rst:157 ../../library/collections.abc.rst:161 -msgid ":class:`Mapping`" -msgstr ":class:`Mapping`" - -#: ../../library/collections.abc.rst:157 -msgid "``__getitem__``, ``__iter__``, ``__len__``" -msgstr "``__getitem__``、``__iter__``、``__len__``" - -#: ../../library/collections.abc.rst:157 -msgid "" -"``__contains__``, ``keys``, ``items``, ``values``, ``get``, ``__eq__``, and " -"``__ne__``" -msgstr "" -"``__contains__``、``keys``、``items``、``values``、``get``、``__eq__`` 和 " -"``__ne__``" - -#: ../../library/collections.abc.rst:161 -msgid ":class:`MutableMapping`" -msgstr ":class:`MutableMapping`" - -#: ../../library/collections.abc.rst:161 -msgid "" -"``__getitem__``, ``__setitem__``, ``__delitem__``, ``__iter__``, ``__len__``" -msgstr "" -"``__getitem__``、``__setitem__``、``__delitem__``、``__iter__``、``__len__``" - -#: ../../library/collections.abc.rst:161 -msgid "" -"Inherited :class:`Mapping` methods and ``pop``, ``popitem``, ``clear``, " -"``update``, and ``setdefault``" -msgstr "" - -#: ../../library/collections.abc.rst:168 -msgid ":class:`MappingView`" -msgstr ":class:`MappingView`" - -#: ../../library/collections.abc.rst:168 -msgid ":class:`Sized`" -msgstr ":class:`Sized`" - -#: ../../library/collections.abc.rst:168 -msgid "``__init__``, ``__len__`` and ``__repr__``" -msgstr "``__init__``、``__len__`` 和 ``__repr__``" - -#: ../../library/collections.abc.rst:169 -msgid ":class:`ItemsView`" -msgstr ":class:`ItemsView`" - -#: ../../library/collections.abc.rst:169 ../../library/collections.abc.rst:171 -msgid ":class:`MappingView`, :class:`Set`" -msgstr ":class:`MappingView`、:class:`Set`" - -#: ../../library/collections.abc.rst:169 ../../library/collections.abc.rst:171 -#: ../../library/collections.abc.rst:173 -msgid "``__contains__``, ``__iter__``" -msgstr "``__contains__``、``__iter__``" - -#: ../../library/collections.abc.rst:171 -msgid ":class:`KeysView`" -msgstr ":class:`KeysView`" - -#: ../../library/collections.abc.rst:173 -msgid ":class:`ValuesView`" -msgstr ":class:`ValuesView`" - -#: ../../library/collections.abc.rst:173 -msgid ":class:`MappingView`, :class:`Collection`" -msgstr ":class:`MappingView`、:class:`Collection`" - -#: ../../library/collections.abc.rst:175 -msgid ":class:`Awaitable` [1]_" -msgstr ":class:`Awaitable` [1]_" - -#: ../../library/collections.abc.rst:175 -msgid "``__await__``" -msgstr "``__await__``" - -#: ../../library/collections.abc.rst:176 -msgid ":class:`Coroutine` [1]_" -msgstr ":class:`Coroutine` [1]_" - -#: ../../library/collections.abc.rst:176 -msgid ":class:`Awaitable`" -msgstr ":class:`Awaitable`" - -#: ../../library/collections.abc.rst:176 -msgid "``close``" -msgstr "``close``" - -#: ../../library/collections.abc.rst:177 -msgid ":class:`AsyncIterable` [1]_" -msgstr ":class:`AsyncIterable` [1]_" - -#: ../../library/collections.abc.rst:177 ../../library/collections.abc.rst:178 -msgid "``__aiter__``" -msgstr "``__aiter__``" - -#: ../../library/collections.abc.rst:178 -msgid ":class:`AsyncIterator` [1]_" -msgstr ":class:`AsyncIterator` [1]_" - -#: ../../library/collections.abc.rst:178 -msgid ":class:`AsyncIterable`" -msgstr ":class:`AsyncIterable`" - -#: ../../library/collections.abc.rst:178 -msgid "``__anext__``" -msgstr "``__anext__``" - -#: ../../library/collections.abc.rst:179 -msgid ":class:`AsyncGenerator` [1]_" -msgstr ":class:`AsyncGenerator` [1]_" - -#: ../../library/collections.abc.rst:179 -msgid ":class:`AsyncIterator`" -msgstr ":class:`AsyncIterator`" - -#: ../../library/collections.abc.rst:179 -msgid "``asend``, ``athrow``" -msgstr "``asend``、``athrow``" - -#: ../../library/collections.abc.rst:179 -msgid "``aclose``, ``__aiter__``, ``__anext__``" -msgstr "``aclose``、``__aiter__``、``__anext__``" - -#: ../../library/collections.abc.rst:180 -msgid ":class:`Buffer` [1]_" -msgstr ":class:`Buffer` [1]_" - -#: ../../library/collections.abc.rst:180 -msgid "``__buffer__``" -msgstr "``__buffer__``" - -#: ../../library/collections.abc.rst:185 -msgid "Footnotes" -msgstr "註腳" - -#: ../../library/collections.abc.rst:186 -msgid "" -"These ABCs override :meth:`~abc.ABCMeta.__subclasshook__` to support testing " -"an interface by verifying the required methods are present and have not been " -"set to :const:`None`. This only works for simple interfaces. More complex " -"interfaces require registration or direct subclassing." -msgstr "" - -#: ../../library/collections.abc.rst:192 -msgid "" -"Checking ``isinstance(obj, Iterable)`` detects classes that are registered " -"as :class:`Iterable` or that have an :meth:`~container.__iter__` method, but " -"it does not detect classes that iterate with the :meth:`~object.__getitem__` " -"method. The only reliable way to determine whether an object is :term:" -"`iterable` is to call ``iter(obj)``." -msgstr "" - -#: ../../library/collections.abc.rst:200 -msgid "Collections Abstract Base Classes -- Detailed Descriptions" -msgstr "集合抽象基底類別的詳細描述" - -#: ../../library/collections.abc.rst:205 -msgid "ABC for classes that provide the :meth:`~object.__contains__` method." -msgstr "有提供 :meth:`~object.__contains__` 方法之類別的 ABC。" - -#: ../../library/collections.abc.rst:209 -msgid "ABC for classes that provide the :meth:`~object.__hash__` method." -msgstr "有提供 :meth:`~object.__hash__` 方法之類別的 ABC。" - -#: ../../library/collections.abc.rst:213 -msgid "ABC for classes that provide the :meth:`~object.__len__` method." -msgstr "有提供 :meth:`~object.__len__` 方法之類別的 ABC。" - -#: ../../library/collections.abc.rst:217 -msgid "ABC for classes that provide the :meth:`~object.__call__` method." -msgstr "有提供 :meth:`~object.__call__` 方法之類別的 ABC。" - -#: ../../library/collections.abc.rst:219 -msgid "" -"See :ref:`annotating-callables` for details on how to use :class:`!Callable` " -"in type annotations." -msgstr "" - -#: ../../library/collections.abc.rst:224 -msgid "ABC for classes that provide the :meth:`~container.__iter__` method." -msgstr "有提供 :meth:`~container.__iter__` 方法之類別的 ABC。" - -#: ../../library/collections.abc.rst:226 -msgid "" -"Checking ``isinstance(obj, Iterable)`` detects classes that are registered " -"as :class:`Iterable` or that have an :meth:`~container.__iter__` method, but " -"it does not detect classes that iterate with the :meth:`~object.__getitem__` " -"method. The only reliable way to determine whether an object is :term:" -"`iterable` is to call ``iter(obj)``." -msgstr "" - -#: ../../library/collections.abc.rst:235 -msgid "ABC for sized iterable container classes." -msgstr "" - -#: ../../library/collections.abc.rst:241 -msgid "" -"ABC for classes that provide the :meth:`~iterator.__iter__` and :meth:" -"`~iterator.__next__` methods. See also the definition of :term:`iterator`." -msgstr "" -"有提供 :meth:`~iterator.__iter__` 和 :meth:`~iterator.__next__` 方法之類別的 ABC。" -"另請參閱 :term:`iterator` 的定義。" - -#: ../../library/collections.abc.rst:247 -msgid "" -"ABC for iterable classes that also provide the :meth:`~object.__reversed__` " -"method." -msgstr "" -"亦有提供 :meth:`~object.__reversed__` 方法之可疊代類別的 ABC。" - -#: ../../library/collections.abc.rst:254 -msgid "" -"ABC for :term:`generator` classes that implement the protocol defined in :" -"pep:`342` that extends :term:`iterators ` with the :meth:" -"`~generator.send`, :meth:`~generator.throw` and :meth:`~generator.close` " -"methods." -msgstr "" - -#: ../../library/collections.abc.rst:259 -msgid "" -"See :ref:`annotating-generators-and-coroutines` for details on using :class:" -"`!Generator` in type annotations." -msgstr "" - -#: ../../library/collections.abc.rst:268 -msgid "ABCs for read-only and mutable :term:`sequences `." -msgstr "唯讀且可變\\ :term:`序列 `\\ 的 ABC。" - -#: ../../library/collections.abc.rst:270 -msgid "" -"Implementation note: Some of the mixin methods, such as :meth:`~container." -"__iter__`, :meth:`~object.__reversed__`, and :meth:`~sequence.index` make " -"repeated calls to the underlying :meth:`~object.__getitem__` method. " -"Consequently, if :meth:`~object.__getitem__` is implemented with constant " -"access speed, the mixin methods will have linear performance; however, if " -"the underlying method is linear (as it would be with a linked list), the " -"mixins will have quadratic performance and will likely need to be overridden." -msgstr "" - -#: ../../library/collections.abc.rst:282 -msgid "Return first index of *value*." -msgstr "回傳 *value* 的第一個索引。" - -#: ../../library/collections.abc.rst:284 -msgid "Raises :exc:`ValueError` if the value is not present." -msgstr "如果找不到該值，則引發 :exc:`ValueError`。" - -#: ../../library/collections.abc.rst:286 -msgid "" -"Supporting the *start* and *stop* arguments is optional, but recommended." -msgstr "建議要支援 *start* 和 *stop* 引數，但並非必要。" - -#: ../../library/collections.abc.rst:288 -msgid "" -"The :meth:`~sequence.index` method gained support for the *stop* and *start* " -"arguments." -msgstr "" - -#: ../../library/collections.abc.rst:292 -msgid "The :class:`ByteString` ABC has been deprecated." -msgstr ":class:`ByteString` ABC 已被棄用。" - -#: ../../library/collections.abc.rst:295 -msgid "" -"Use ``isinstance(obj, collections.abc.Buffer)`` to test if ``obj`` " -"implements the :ref:`buffer protocol ` at runtime. For use in " -"type annotations, either use :class:`Buffer` or a union that explicitly " -"specifies the types your code supports (e.g., ``bytes | bytearray | " -"memoryview``)." -msgstr "" - -#: ../../library/collections.abc.rst:301 -msgid "" -":class:`!ByteString` was originally intended to be an abstract class that " -"would serve as a supertype of both :class:`bytes` and :class:`bytearray`. " -"However, since the ABC never had any methods, knowing that an object was an " -"instance of :class:`!ByteString` never actually told you anything useful " -"about the object. Other common buffer types such as :class:`memoryview` were " -"also never understood as subtypes of :class:`!ByteString` (either at runtime " -"or by static type checkers)." -msgstr "" -":class:`!ByteString` 最初被設計為一個抽象類別，以作為 :class:`bytes` 和 :class:`bytearray` " -"的超型別 (supertype)。然而由於 ABC 從未擁有任何方法，知道一個物件是 :class:`!ByteString` 的" -"實例從未真正告訴你任何關於該物件的有用資訊。其他常見的緩衝區型別如 :class:`memoryview` " -"也從未被理解為 :class:`!ByteString` 的子型別（無論是在 runtime 還是由靜態型別檢查器）。" - -#: ../../library/collections.abc.rst:309 -msgid "See :pep:`PEP 688 <688#current-options>` for more details." -msgstr "更多詳細資訊請參閱 :pep:`PEP 688 <688#current-options>`。" - -#: ../../library/collections.abc.rst:314 -msgid "ABCs for read-only and mutable :ref:`sets `." -msgstr "唯讀且可變\\ :ref:`集合 `\\ 的 ABC。" - -#: ../../library/collections.abc.rst:319 -msgid "ABCs for read-only and mutable :term:`mappings `." -msgstr "唯讀且可變\\ :term:`對映 `\\ 的 ABC。" - -#: ../../library/collections.abc.rst:326 -msgid "" -"ABCs for mapping, items, keys, and values :term:`views `." -msgstr "" - -#: ../../library/collections.abc.rst:330 -msgid "" -"ABC for :term:`awaitable` objects, which can be used in :keyword:`await` " -"expressions. Custom implementations must provide the :meth:`~object." -"__await__` method." -msgstr "" - -#: ../../library/collections.abc.rst:334 -msgid "" -":term:`Coroutine ` objects and instances of the :class:" -"`~collections.abc.Coroutine` ABC are all instances of this ABC." -msgstr "" - -#: ../../library/collections.abc.rst:338 -msgid "" -"In CPython, generator-based coroutines (:term:`generators ` " -"decorated with :deco:`types.coroutine`) are *awaitables*, even though they " -"do not have an :meth:`~object.__await__` method. Using ``isinstance(gencoro, " -"Awaitable)`` for them will return ``False``. Use :func:`inspect.isawaitable` " -"to detect them." -msgstr "" - -#: ../../library/collections.abc.rst:348 -msgid "" -"ABC for :term:`coroutine` compatible classes. These implement the following " -"methods, defined in :ref:`coroutine-objects`: :meth:`~coroutine.send`, :meth:" -"`~coroutine.throw`, and :meth:`~coroutine.close`. Custom implementations " -"must also implement :meth:`~object.__await__`. All :class:`Coroutine` " -"instances are also instances of :class:`Awaitable`." -msgstr "" - -#: ../../library/collections.abc.rst:356 -msgid "" -"In CPython, generator-based coroutines (:term:`generators ` " -"decorated with :deco:`types.coroutine`) are *awaitables*, even though they " -"do not have an :meth:`~object.__await__` method. Using ``isinstance(gencoro, " -"Coroutine)`` for them will return ``False``. Use :func:`inspect.isawaitable` " -"to detect them." -msgstr "" - -#: ../../library/collections.abc.rst:362 -msgid "" -"See :ref:`annotating-generators-and-coroutines` for details on using :class:" -"`!Coroutine` in type annotations. The variance and order of type parameters " -"correspond to those of :class:`Generator`." -msgstr "" - -#: ../../library/collections.abc.rst:371 -msgid "" -"ABC for classes that provide an ``__aiter__`` method. See also the " -"definition of :term:`asynchronous iterable`." -msgstr "" - -#: ../../library/collections.abc.rst:378 -msgid "" -"ABC for classes that provide ``__aiter__`` and ``__anext__`` methods. See " -"also the definition of :term:`asynchronous iterator`." -msgstr "" - -#: ../../library/collections.abc.rst:385 -msgid "" -"ABC for :term:`asynchronous generator` classes that implement the protocol " -"defined in :pep:`525` and :pep:`492`." -msgstr "" - -#: ../../library/collections.abc.rst:388 -msgid "" -"See :ref:`annotating-generators-and-coroutines` for details on using :class:" -"`!AsyncGenerator` in type annotations." -msgstr "" - -#: ../../library/collections.abc.rst:395 -msgid "" -"ABC for classes that provide the :meth:`~object.__buffer__` method, " -"implementing the :ref:`buffer protocol `. See :pep:`688`." -msgstr "" - -#: ../../library/collections.abc.rst:401 -msgid "Examples and Recipes" -msgstr "" - -#: ../../library/collections.abc.rst:403 -msgid "" -"ABCs allow us to ask classes or instances if they provide particular " -"functionality, for example::" -msgstr "" - -#: ../../library/collections.abc.rst:406 -msgid "" -"size = None\n" -"if isinstance(myvar, collections.abc.Sized):\n" -" size = len(myvar)" -msgstr "" -"size = None\n" -"if isinstance(myvar, collections.abc.Sized):\n" -" size = len(myvar)" - -#: ../../library/collections.abc.rst:410 -msgid "" -"Several of the ABCs are also useful as mixins that make it easier to develop " -"classes supporting container APIs. For example, to write a class supporting " -"the full :class:`Set` API, it is only necessary to supply the three " -"underlying abstract methods: :meth:`~object.__contains__`, :meth:`~container." -"__iter__`, and :meth:`~object.__len__`. The ABC supplies the remaining " -"methods such as :meth:`!__and__` and :meth:`~frozenset.isdisjoint`::" -msgstr "" - -#: ../../library/collections.abc.rst:417 -msgid "" -"class ListBasedSet(collections.abc.Set):\n" -" ''' Alternate set implementation favoring space over speed\n" -" and not requiring the set elements to be hashable. '''\n" -" def __init__(self, iterable):\n" -" self.elements = lst = []\n" -" for value in iterable:\n" -" if value not in lst:\n" -" lst.append(value)\n" -"\n" -" def __iter__(self):\n" -" return iter(self.elements)\n" -"\n" -" def __contains__(self, value):\n" -" return value in self.elements\n" -"\n" -" def __len__(self):\n" -" return len(self.elements)\n" -"\n" -"s1 = ListBasedSet('abcdef')\n" -"s2 = ListBasedSet('defghi')\n" -"overlap = s1 & s2 # The __and__() method is supported " -"automatically" -msgstr "" - -#: ../../library/collections.abc.rst:439 -msgid "Notes on using :class:`Set` and :class:`MutableSet` as a mixin:" -msgstr "" - -#: ../../library/collections.abc.rst:442 -msgid "" -"Since some set operations create new sets, the default mixin methods need a " -"way to create new instances from an :term:`iterable`. The class constructor " -"is assumed to have a signature in the form ``ClassName(iterable)``. That " -"assumption is factored-out to an internal :class:`classmethod` called :meth:" -"`!_from_iterable` which calls ``cls(iterable)`` to produce a new set. If " -"the :class:`Set` mixin is being used in a class with a different constructor " -"signature, you will need to override :meth:`!_from_iterable` with a " -"classmethod or regular method that can construct new instances from an " -"iterable argument." -msgstr "" - -#: ../../library/collections.abc.rst:453 -msgid "" -"To override the comparisons (presumably for speed, as the semantics are " -"fixed), redefine :meth:`~object.__le__` and :meth:`~object.__ge__`, then the " -"other operations will automatically follow suit." -msgstr "" - -#: ../../library/collections.abc.rst:459 -msgid "" -"The :class:`Set` mixin provides a :meth:`!_hash` method to compute a hash " -"value for the set; however, :meth:`~object.__hash__` is not defined because " -"not all sets are :term:`hashable` or immutable. To add set hashability " -"using mixins, inherit from both :meth:`Set` and :meth:`Hashable`, then " -"define ``__hash__ = Set._hash``." -msgstr "" - -#: ../../library/collections.abc.rst:467 -msgid "" -"`OrderedSet recipe `_ for an " -"example built on :class:`MutableSet`." -msgstr "" - -#: ../../library/collections.abc.rst:470 -msgid "For more about ABCs, see the :mod:`abc` module and :pep:`3119`." -msgstr "關於 ABC 的更多資訊請見 :mod:`abc` module 和 :pep:`3119`。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-10-08 00:15+0000\n" +"PO-Revision-Date: 2018-05-23 14:41+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/collections.abc.rst:2 +msgid ":mod:`!collections.abc` --- Abstract Base Classes for Containers" +msgstr ":mod:`!collections.abc` --- 容器的抽象基底類別" + +#: ../../library/collections.abc.rst:10 +msgid "Formerly, this module was part of the :mod:`collections` module." +msgstr "過去此模組是 :mod:`collections` 模組的一部分。" + +#: ../../library/collections.abc.rst:13 +msgid "**Source code:** :source:`Lib/_collections_abc.py`" +msgstr "**原始碼：**\\ :source:`Lib/_collections_abc.py`" + +#: ../../library/collections.abc.rst:23 +msgid "" +"This module provides :term:`abstract base classes ` " +"that can be used to test whether a class provides a particular interface; " +"for example, whether it is :term:`hashable` or whether it is a :term:" +"`mapping`." +msgstr "" + +#: ../../library/collections.abc.rst:27 +msgid "" +"An :func:`issubclass` or :func:`isinstance` test for an interface works in " +"one of three ways." +msgstr "" + +#: ../../library/collections.abc.rst:30 +msgid "" +"A newly written class can inherit directly from one of the abstract base " +"classes. The class must supply the required abstract methods. The " +"remaining mixin methods come from inheritance and can be overridden if " +"desired. Other methods may be added as needed:" +msgstr "" + +#: ../../library/collections.abc.rst:35 +msgid "" +"class C(Sequence): # Direct inheritance\n" +" def __init__(self): ... # Extra method not required by the " +"ABC\n" +" def __getitem__(self, index): ... # Required abstract method\n" +" def __len__(self): ... # Required abstract method\n" +" def count(self, value): ... # Optionally override a mixin method" +msgstr "" + +#: ../../library/collections.abc.rst:43 +msgid "" +">>> issubclass(C, Sequence)\n" +"True\n" +">>> isinstance(C(), Sequence)\n" +"True" +msgstr "" +">>> issubclass(C, Sequence)\n" +"True\n" +">>> isinstance(C(), Sequence)\n" +"True" + +#: ../../library/collections.abc.rst:50 +msgid "" +"Existing classes and built-in classes can be registered as \"virtual " +"subclasses\" of the ABCs. Those classes should define the full API " +"including all of the abstract methods and all of the mixin methods. This " +"lets users rely on :func:`issubclass` or :func:`isinstance` tests to " +"determine whether the full interface is supported. The exception to this " +"rule is for methods that are automatically inferred from the rest of the API:" +msgstr "" + +#: ../../library/collections.abc.rst:58 +msgid "" +"class D: # No inheritance\n" +" def __init__(self): ... # Extra method not required by the " +"ABC\n" +" def __getitem__(self, index): ... # Abstract method\n" +" def __len__(self): ... # Abstract method\n" +" def count(self, value): ... # Mixin method\n" +" def index(self, value): ... # Mixin method\n" +"\n" +"Sequence.register(D) # Register instead of inherit" +msgstr "" + +#: ../../library/collections.abc.rst:69 +msgid "" +">>> issubclass(D, Sequence)\n" +"True\n" +">>> isinstance(D(), Sequence)\n" +"True" +msgstr "" +">>> issubclass(D, Sequence)\n" +"True\n" +">>> isinstance(D(), Sequence)\n" +"True" + +#: ../../library/collections.abc.rst:76 +msgid "" +"In this example, class :class:`!D` does not need to define ``__contains__``, " +"``__iter__``, and ``__reversed__`` because the :ref:`in-operator " +"`, the :term:`iteration ` logic, and the :func:" +"`reversed` function automatically fall back to using ``__getitem__`` and " +"``__len__``." +msgstr "" + +#: ../../library/collections.abc.rst:82 +msgid "" +"Some simple interfaces are directly recognizable by the presence of the " +"required methods (unless those methods have been set to :const:`None`):" +msgstr "" + +#: ../../library/collections.abc.rst:85 +msgid "" +"class E:\n" +" def __iter__(self): ...\n" +" def __next__(self): ..." +msgstr "" +"class E:\n" +" def __iter__(self): ...\n" +" def __next__(self): ..." + +#: ../../library/collections.abc.rst:91 +msgid "" +">>> issubclass(E, Iterable)\n" +"True\n" +">>> isinstance(E(), Iterable)\n" +"True" +msgstr "" +">>> issubclass(E, Iterable)\n" +"True\n" +">>> isinstance(E(), Iterable)\n" +"True" + +#: ../../library/collections.abc.rst:98 +msgid "" +"Complex interfaces do not support this last technique because an interface " +"is more than just the presence of method names. Interfaces specify " +"semantics and relationships between methods that cannot be inferred solely " +"from the presence of specific method names. For example, knowing that a " +"class supplies ``__getitem__``, ``__len__``, and ``__iter__`` is " +"insufficient for distinguishing a :class:`Sequence` from a :class:`Mapping`." +msgstr "" + +#: ../../library/collections.abc.rst:106 +msgid "" +"These abstract classes now support ``[]``. See :ref:`types-genericalias` " +"and :pep:`585`." +msgstr "" + +#: ../../library/collections.abc.rst:113 +msgid "Collections Abstract Base Classes" +msgstr "" + +#: ../../library/collections.abc.rst:115 +msgid "" +"The collections module offers the following :term:`ABCs `:" +msgstr "" + +#: ../../library/collections.abc.rst:120 +msgid "ABC" +msgstr "ABC" + +#: ../../library/collections.abc.rst:120 +msgid "Inherits from" +msgstr "" + +#: ../../library/collections.abc.rst:120 +msgid "Abstract Methods" +msgstr "抽象方法" + +#: ../../library/collections.abc.rst:120 +msgid "Mixin Methods" +msgstr "" + +#: ../../library/collections.abc.rst:122 +msgid ":class:`Container` [1]_" +msgstr ":class:`Container` [1]_" + +#: ../../library/collections.abc.rst:122 +msgid "``__contains__``" +msgstr "``__contains__``" + +#: ../../library/collections.abc.rst:123 +msgid ":class:`Hashable` [1]_" +msgstr ":class:`Hashable` [1]_" + +#: ../../library/collections.abc.rst:123 +msgid "``__hash__``" +msgstr "``__hash__``" + +#: ../../library/collections.abc.rst:124 +msgid ":class:`Iterable` [1]_ [2]_" +msgstr ":class:`Iterable` [1]_ [2]_" + +#: ../../library/collections.abc.rst:124 ../../library/collections.abc.rst:125 +msgid "``__iter__``" +msgstr "``__iter__``" + +#: ../../library/collections.abc.rst:125 +msgid ":class:`Iterator` [1]_" +msgstr ":class:`Iterator` [1]_" + +#: ../../library/collections.abc.rst:125 ../../library/collections.abc.rst:126 +msgid ":class:`Iterable`" +msgstr ":class:`Iterable`" + +#: ../../library/collections.abc.rst:125 +msgid "``__next__``" +msgstr "``__next__``" + +#: ../../library/collections.abc.rst:126 +msgid ":class:`Reversible` [1]_" +msgstr ":class:`Reversible` [1]_" + +#: ../../library/collections.abc.rst:126 +msgid "``__reversed__``" +msgstr "``__reversed__``" + +#: ../../library/collections.abc.rst:127 +msgid ":class:`Generator` [1]_" +msgstr ":class:`Generator` [1]_" + +#: ../../library/collections.abc.rst:127 +msgid ":class:`Iterator`" +msgstr ":class:`Iterator`" + +#: ../../library/collections.abc.rst:127 ../../library/collections.abc.rst:176 +msgid "``send``, ``throw``" +msgstr "``send``、``throw``" + +#: ../../library/collections.abc.rst:127 +msgid "``close``, ``__iter__``, ``__next__``" +msgstr "``close``、``__iter__``、``__next__``" + +#: ../../library/collections.abc.rst:128 +msgid ":class:`Sized` [1]_" +msgstr ":class:`Sized` [1]_" + +#: ../../library/collections.abc.rst:128 +msgid "``__len__``" +msgstr "``__len__``" + +#: ../../library/collections.abc.rst:129 +msgid ":class:`Callable` [1]_" +msgstr ":class:`Callable` [1]_" + +#: ../../library/collections.abc.rst:129 +msgid "``__call__``" +msgstr "``__call__``" + +#: ../../library/collections.abc.rst:130 +msgid ":class:`Collection` [1]_" +msgstr ":class:`Collection` [1]_" + +#: ../../library/collections.abc.rst:130 +msgid ":class:`Sized`, :class:`Iterable`, :class:`Container`" +msgstr ":class:`Sized`、:class:`Iterable`、:class:`Container`" + +#: ../../library/collections.abc.rst:130 ../../library/collections.abc.rst:146 +msgid "``__contains__``, ``__iter__``, ``__len__``" +msgstr "``__contains__``、``__iter__``、``__len__``" + +#: ../../library/collections.abc.rst:134 ../../library/collections.abc.rst:137 +#: ../../library/collections.abc.rst:143 +msgid ":class:`Sequence`" +msgstr ":class:`Sequence`" + +#: ../../library/collections.abc.rst:134 +msgid ":class:`Reversible`, :class:`Collection`" +msgstr ":class:`Reversible`, :class:`Collection`" + +#: ../../library/collections.abc.rst:134 ../../library/collections.abc.rst:143 +msgid "``__getitem__``, ``__len__``" +msgstr "``__getitem__``、``__len__``" + +#: ../../library/collections.abc.rst:134 +msgid "" +"``__contains__``, ``__iter__``, ``__reversed__``, ``index``, and ``count``" +msgstr "" +"``__contains__``、``__iter__``、``__reversed__``、``index`` 和 ``count``" + +#: ../../library/collections.abc.rst:137 +msgid ":class:`MutableSequence`" +msgstr ":class:`MutableSequence`" + +#: ../../library/collections.abc.rst:137 +msgid "" +"``__getitem__``, ``__setitem__``, ``__delitem__``, ``__len__``, ``insert``" +msgstr "" +"``__getitem__``、``__setitem__``、``__delitem__``、``__len__``、``insert``" + +#: ../../library/collections.abc.rst:137 +msgid "" +"Inherited :class:`Sequence` methods and ``append``, ``clear``, ``reverse``, " +"``extend``, ``pop``, ``remove``, and ``__iadd__``" +msgstr "" +"繼承 :class:`Sequence` 方法和 ``append``、``clear``、``reverse``、``extend``、" +"``pop``、``remove`` 和 ``__iadd__``" + +#: ../../library/collections.abc.rst:143 +msgid ":class:`ByteString`" +msgstr ":class:`ByteString`" + +#: ../../library/collections.abc.rst:143 +msgid "Inherited :class:`Sequence` methods" +msgstr ":class:`Sequence` 的繼承方法" + +#: ../../library/collections.abc.rst:146 ../../library/collections.abc.rst:151 +msgid ":class:`Set`" +msgstr ":class:`Set`" + +#: ../../library/collections.abc.rst:146 ../../library/collections.abc.rst:157 +msgid ":class:`Collection`" +msgstr ":class:`Collection`" + +#: ../../library/collections.abc.rst:146 +msgid "" +"``__le__``, ``__lt__``, ``__eq__``, ``__ne__``, ``__gt__``, ``__ge__``, " +"``__and__``, ``__or__``, ``__sub__``, ``__rsub__``, ``__xor__``, " +"``__rxor__`` and ``isdisjoint``" +msgstr "" +"``__le__``、``__lt__``、``__eq__``、``__ne__``、``__gt__``、``__ge__``、" +"``__and__``、``__or__``、``__sub__``、``__rsub__``、``__xor__``、" +"``__rxor__`` 和 ``isdisjoint``" + +#: ../../library/collections.abc.rst:151 +msgid ":class:`MutableSet`" +msgstr ":class:`MutableSet`" + +#: ../../library/collections.abc.rst:151 +msgid "``__contains__``, ``__iter__``, ``__len__``, ``add``, ``discard``" +msgstr "``__contains__``、``__iter__``、``__len__``、``add``、``discard``" + +#: ../../library/collections.abc.rst:151 +msgid "" +"Inherited :class:`Set` methods and ``clear``, ``pop``, ``remove``, " +"``__ior__``, ``__iand__``, ``__ixor__``, and ``__isub__``" +msgstr "" + +#: ../../library/collections.abc.rst:157 ../../library/collections.abc.rst:161 +msgid ":class:`Mapping`" +msgstr ":class:`Mapping`" + +#: ../../library/collections.abc.rst:157 +msgid "``__getitem__``, ``__iter__``, ``__len__``" +msgstr "``__getitem__``、``__iter__``、``__len__``" + +#: ../../library/collections.abc.rst:157 +msgid "" +"``__contains__``, ``keys``, ``items``, ``values``, ``get``, ``__eq__``, and " +"``__ne__``" +msgstr "" +"``__contains__``、``keys``、``items``、``values``、``get``、``__eq__`` 和 " +"``__ne__``" + +#: ../../library/collections.abc.rst:161 +msgid ":class:`MutableMapping`" +msgstr ":class:`MutableMapping`" + +#: ../../library/collections.abc.rst:161 +msgid "" +"``__getitem__``, ``__setitem__``, ``__delitem__``, ``__iter__``, ``__len__``" +msgstr "" +"``__getitem__``、``__setitem__``、``__delitem__``、``__iter__``、``__len__``" + +#: ../../library/collections.abc.rst:161 +msgid "" +"Inherited :class:`Mapping` methods and ``pop``, ``popitem``, ``clear``, " +"``update``, and ``setdefault``" +msgstr "" + +#: ../../library/collections.abc.rst:168 +msgid ":class:`MappingView`" +msgstr ":class:`MappingView`" + +#: ../../library/collections.abc.rst:168 +msgid ":class:`Sized`" +msgstr ":class:`Sized`" + +#: ../../library/collections.abc.rst:168 +msgid "``__init__``, ``__len__`` and ``__repr__``" +msgstr "``__init__``、``__len__`` 和 ``__repr__``" + +#: ../../library/collections.abc.rst:169 +msgid ":class:`ItemsView`" +msgstr ":class:`ItemsView`" + +#: ../../library/collections.abc.rst:169 ../../library/collections.abc.rst:171 +msgid ":class:`MappingView`, :class:`Set`" +msgstr ":class:`MappingView`、:class:`Set`" + +#: ../../library/collections.abc.rst:169 ../../library/collections.abc.rst:171 +#: ../../library/collections.abc.rst:173 +msgid "``__contains__``, ``__iter__``" +msgstr "``__contains__``、``__iter__``" + +#: ../../library/collections.abc.rst:171 +msgid ":class:`KeysView`" +msgstr ":class:`KeysView`" + +#: ../../library/collections.abc.rst:173 +msgid ":class:`ValuesView`" +msgstr ":class:`ValuesView`" + +#: ../../library/collections.abc.rst:173 +msgid ":class:`MappingView`, :class:`Collection`" +msgstr ":class:`MappingView`、:class:`Collection`" + +#: ../../library/collections.abc.rst:175 +msgid ":class:`Awaitable` [1]_" +msgstr ":class:`Awaitable` [1]_" + +#: ../../library/collections.abc.rst:175 +msgid "``__await__``" +msgstr "``__await__``" + +#: ../../library/collections.abc.rst:176 +msgid ":class:`Coroutine` [1]_" +msgstr ":class:`Coroutine` [1]_" + +#: ../../library/collections.abc.rst:176 +msgid ":class:`Awaitable`" +msgstr ":class:`Awaitable`" + +#: ../../library/collections.abc.rst:176 +msgid "``close``" +msgstr "``close``" + +#: ../../library/collections.abc.rst:177 +msgid ":class:`AsyncIterable` [1]_" +msgstr ":class:`AsyncIterable` [1]_" + +#: ../../library/collections.abc.rst:177 ../../library/collections.abc.rst:178 +msgid "``__aiter__``" +msgstr "``__aiter__``" + +#: ../../library/collections.abc.rst:178 +msgid ":class:`AsyncIterator` [1]_" +msgstr ":class:`AsyncIterator` [1]_" + +#: ../../library/collections.abc.rst:178 +msgid ":class:`AsyncIterable`" +msgstr ":class:`AsyncIterable`" + +#: ../../library/collections.abc.rst:178 +msgid "``__anext__``" +msgstr "``__anext__``" + +#: ../../library/collections.abc.rst:179 +msgid ":class:`AsyncGenerator` [1]_" +msgstr ":class:`AsyncGenerator` [1]_" + +#: ../../library/collections.abc.rst:179 +msgid ":class:`AsyncIterator`" +msgstr ":class:`AsyncIterator`" + +#: ../../library/collections.abc.rst:179 +msgid "``asend``, ``athrow``" +msgstr "``asend``、``athrow``" + +#: ../../library/collections.abc.rst:179 +msgid "``aclose``, ``__aiter__``, ``__anext__``" +msgstr "``aclose``、``__aiter__``、``__anext__``" + +#: ../../library/collections.abc.rst:180 +msgid ":class:`Buffer` [1]_" +msgstr ":class:`Buffer` [1]_" + +#: ../../library/collections.abc.rst:180 +msgid "``__buffer__``" +msgstr "``__buffer__``" + +#: ../../library/collections.abc.rst:185 +msgid "Footnotes" +msgstr "註腳" + +#: ../../library/collections.abc.rst:186 +msgid "" +"These ABCs override :meth:`~abc.ABCMeta.__subclasshook__` to support testing " +"an interface by verifying the required methods are present and have not been " +"set to :const:`None`. This only works for simple interfaces. More complex " +"interfaces require registration or direct subclassing." +msgstr "" + +#: ../../library/collections.abc.rst:192 +msgid "" +"Checking ``isinstance(obj, Iterable)`` detects classes that are registered " +"as :class:`Iterable` or that have an :meth:`~container.__iter__` method, but " +"it does not detect classes that iterate with the :meth:`~object.__getitem__` " +"method. The only reliable way to determine whether an object is :term:" +"`iterable` is to call ``iter(obj)``." +msgstr "" + +#: ../../library/collections.abc.rst:200 +msgid "Collections Abstract Base Classes -- Detailed Descriptions" +msgstr "集合抽象基底類別的詳細描述" + +#: ../../library/collections.abc.rst:205 +msgid "ABC for classes that provide the :meth:`~object.__contains__` method." +msgstr "有提供 :meth:`~object.__contains__` 方法之類別的 ABC。" + +#: ../../library/collections.abc.rst:209 +msgid "ABC for classes that provide the :meth:`~object.__hash__` method." +msgstr "有提供 :meth:`~object.__hash__` 方法之類別的 ABC。" + +#: ../../library/collections.abc.rst:213 +msgid "ABC for classes that provide the :meth:`~object.__len__` method." +msgstr "有提供 :meth:`~object.__len__` 方法之類別的 ABC。" + +#: ../../library/collections.abc.rst:217 +msgid "ABC for classes that provide the :meth:`~object.__call__` method." +msgstr "有提供 :meth:`~object.__call__` 方法之類別的 ABC。" + +#: ../../library/collections.abc.rst:219 +msgid "" +"See :ref:`annotating-callables` for details on how to use :class:`!Callable` " +"in type annotations." +msgstr "" + +#: ../../library/collections.abc.rst:224 +msgid "ABC for classes that provide the :meth:`~container.__iter__` method." +msgstr "有提供 :meth:`~container.__iter__` 方法之類別的 ABC。" + +#: ../../library/collections.abc.rst:226 +msgid "" +"Checking ``isinstance(obj, Iterable)`` detects classes that are registered " +"as :class:`Iterable` or that have an :meth:`~container.__iter__` method, but " +"it does not detect classes that iterate with the :meth:`~object.__getitem__` " +"method. The only reliable way to determine whether an object is :term:" +"`iterable` is to call ``iter(obj)``." +msgstr "" + +#: ../../library/collections.abc.rst:235 +msgid "ABC for sized iterable container classes." +msgstr "" + +#: ../../library/collections.abc.rst:241 +msgid "" +"ABC for classes that provide the :meth:`~iterator.__iter__` and :meth:" +"`~iterator.__next__` methods. See also the definition of :term:`iterator`." +msgstr "" +"有提供 :meth:`~iterator.__iter__` 和 :meth:`~iterator.__next__` 方法之類別的 ABC。" +"另請參閱 :term:`iterator` 的定義。" + +#: ../../library/collections.abc.rst:247 +msgid "" +"ABC for iterable classes that also provide the :meth:`~object.__reversed__` " +"method." +msgstr "" +"亦有提供 :meth:`~object.__reversed__` 方法之可疊代類別的 ABC。" + +#: ../../library/collections.abc.rst:254 +msgid "" +"ABC for :term:`generator` classes that implement the protocol defined in :" +"pep:`342` that extends :term:`iterators ` with the :meth:" +"`~generator.send`, :meth:`~generator.throw` and :meth:`~generator.close` " +"methods." +msgstr "" + +#: ../../library/collections.abc.rst:259 +msgid "" +"See :ref:`annotating-generators-and-coroutines` for details on using :class:" +"`!Generator` in type annotations." +msgstr "" + +#: ../../library/collections.abc.rst:268 +msgid "ABCs for read-only and mutable :term:`sequences `." +msgstr "唯讀且可變\\ :term:`序列 `\\ 的 ABC。" + +#: ../../library/collections.abc.rst:270 +msgid "" +"Implementation note: Some of the mixin methods, such as :meth:`~container." +"__iter__`, :meth:`~object.__reversed__`, and :meth:`~sequence.index` make " +"repeated calls to the underlying :meth:`~object.__getitem__` method. " +"Consequently, if :meth:`~object.__getitem__` is implemented with constant " +"access speed, the mixin methods will have linear performance; however, if " +"the underlying method is linear (as it would be with a linked list), the " +"mixins will have quadratic performance and will likely need to be overridden." +msgstr "" + +#: ../../library/collections.abc.rst:282 +msgid "Return first index of *value*." +msgstr "回傳 *value* 的第一個索引。" + +#: ../../library/collections.abc.rst:284 +msgid "Raises :exc:`ValueError` if the value is not present." +msgstr "如果找不到該值，則引發 :exc:`ValueError`。" + +#: ../../library/collections.abc.rst:286 +msgid "" +"Supporting the *start* and *stop* arguments is optional, but recommended." +msgstr "建議要支援 *start* 和 *stop* 引數，但並非必要。" + +#: ../../library/collections.abc.rst:288 +msgid "" +"The :meth:`~sequence.index` method gained support for the *stop* and *start* " +"arguments." +msgstr "" + +#: ../../library/collections.abc.rst:292 +msgid "The :class:`ByteString` ABC has been deprecated." +msgstr ":class:`ByteString` ABC 已被棄用。" + +#: ../../library/collections.abc.rst:295 +msgid "" +"Use ``isinstance(obj, collections.abc.Buffer)`` to test if ``obj`` " +"implements the :ref:`buffer protocol ` at runtime. For use in " +"type annotations, either use :class:`Buffer` or a union that explicitly " +"specifies the types your code supports (e.g., ``bytes | bytearray | " +"memoryview``)." +msgstr "" + +#: ../../library/collections.abc.rst:301 +msgid "" +":class:`!ByteString` was originally intended to be an abstract class that " +"would serve as a supertype of both :class:`bytes` and :class:`bytearray`. " +"However, since the ABC never had any methods, knowing that an object was an " +"instance of :class:`!ByteString` never actually told you anything useful " +"about the object. Other common buffer types such as :class:`memoryview` were " +"also never understood as subtypes of :class:`!ByteString` (either at runtime " +"or by static type checkers)." +msgstr "" +":class:`!ByteString` 最初被設計為一個抽象類別，以作為 :class:`bytes` 和 :class:`bytearray` " +"的超型別 (supertype)。然而由於 ABC 從未擁有任何方法，知道一個物件是 :class:`!ByteString` 的" +"實例從未真正告訴你任何關於該物件的有用資訊。其他常見的緩衝區型別如 :class:`memoryview` " +"也從未被理解為 :class:`!ByteString` 的子型別（無論是在 runtime 還是由靜態型別檢查器）。" + +#: ../../library/collections.abc.rst:309 +msgid "See :pep:`PEP 688 <688#current-options>` for more details." +msgstr "更多詳細資訊請參閱 :pep:`PEP 688 <688#current-options>`。" + +#: ../../library/collections.abc.rst:314 +msgid "ABCs for read-only and mutable :ref:`sets `." +msgstr "唯讀且可變\\ :ref:`集合 `\\ 的 ABC。" + +#: ../../library/collections.abc.rst:319 +msgid "ABCs for read-only and mutable :term:`mappings `." +msgstr "唯讀且可變\\ :term:`對映 `\\ 的 ABC。" + +#: ../../library/collections.abc.rst:326 +msgid "" +"ABCs for mapping, items, keys, and values :term:`views `." +msgstr "" + +#: ../../library/collections.abc.rst:330 +msgid "" +"ABC for :term:`awaitable` objects, which can be used in :keyword:`await` " +"expressions. Custom implementations must provide the :meth:`~object." +"__await__` method." +msgstr "" + +#: ../../library/collections.abc.rst:334 +msgid "" +":term:`Coroutine ` objects and instances of the :class:" +"`~collections.abc.Coroutine` ABC are all instances of this ABC." +msgstr "" + +#: ../../library/collections.abc.rst:338 +msgid "" +"In CPython, generator-based coroutines (:term:`generators ` " +"decorated with :deco:`types.coroutine`) are *awaitables*, even though they " +"do not have an :meth:`~object.__await__` method. Using ``isinstance(gencoro, " +"Awaitable)`` for them will return ``False``. Use :func:`inspect.isawaitable` " +"to detect them." +msgstr "" + +#: ../../library/collections.abc.rst:348 +msgid "" +"ABC for :term:`coroutine` compatible classes. These implement the following " +"methods, defined in :ref:`coroutine-objects`: :meth:`~coroutine.send`, :meth:" +"`~coroutine.throw`, and :meth:`~coroutine.close`. Custom implementations " +"must also implement :meth:`~object.__await__`. All :class:`Coroutine` " +"instances are also instances of :class:`Awaitable`." +msgstr "" + +#: ../../library/collections.abc.rst:356 +msgid "" +"In CPython, generator-based coroutines (:term:`generators ` " +"decorated with :deco:`types.coroutine`) are *awaitables*, even though they " +"do not have an :meth:`~object.__await__` method. Using ``isinstance(gencoro, " +"Coroutine)`` for them will return ``False``. Use :func:`inspect.isawaitable` " +"to detect them." +msgstr "" + +#: ../../library/collections.abc.rst:362 +msgid "" +"See :ref:`annotating-generators-and-coroutines` for details on using :class:" +"`!Coroutine` in type annotations. The variance and order of type parameters " +"correspond to those of :class:`Generator`." +msgstr "" + +#: ../../library/collections.abc.rst:371 +msgid "" +"ABC for classes that provide an ``__aiter__`` method. See also the " +"definition of :term:`asynchronous iterable`." +msgstr "" + +#: ../../library/collections.abc.rst:378 +msgid "" +"ABC for classes that provide ``__aiter__`` and ``__anext__`` methods. See " +"also the definition of :term:`asynchronous iterator`." +msgstr "" + +#: ../../library/collections.abc.rst:385 +msgid "" +"ABC for :term:`asynchronous generator` classes that implement the protocol " +"defined in :pep:`525` and :pep:`492`." +msgstr "" + +#: ../../library/collections.abc.rst:388 +msgid "" +"See :ref:`annotating-generators-and-coroutines` for details on using :class:" +"`!AsyncGenerator` in type annotations." +msgstr "" + +#: ../../library/collections.abc.rst:395 +msgid "" +"ABC for classes that provide the :meth:`~object.__buffer__` method, " +"implementing the :ref:`buffer protocol `. See :pep:`688`." +msgstr "" + +#: ../../library/collections.abc.rst:401 +msgid "Examples and Recipes" +msgstr "" + +#: ../../library/collections.abc.rst:403 +msgid "" +"ABCs allow us to ask classes or instances if they provide particular " +"functionality, for example::" +msgstr "" + +#: ../../library/collections.abc.rst:406 +msgid "" +"size = None\n" +"if isinstance(myvar, collections.abc.Sized):\n" +" size = len(myvar)" +msgstr "" +"size = None\n" +"if isinstance(myvar, collections.abc.Sized):\n" +" size = len(myvar)" + +#: ../../library/collections.abc.rst:410 +msgid "" +"Several of the ABCs are also useful as mixins that make it easier to develop " +"classes supporting container APIs. For example, to write a class supporting " +"the full :class:`Set` API, it is only necessary to supply the three " +"underlying abstract methods: :meth:`~object.__contains__`, :meth:`~container." +"__iter__`, and :meth:`~object.__len__`. The ABC supplies the remaining " +"methods such as :meth:`!__and__` and :meth:`~frozenset.isdisjoint`::" +msgstr "" + +#: ../../library/collections.abc.rst:417 +msgid "" +"class ListBasedSet(collections.abc.Set):\n" +" ''' Alternate set implementation favoring space over speed\n" +" and not requiring the set elements to be hashable. '''\n" +" def __init__(self, iterable):\n" +" self.elements = lst = []\n" +" for value in iterable:\n" +" if value not in lst:\n" +" lst.append(value)\n" +"\n" +" def __iter__(self):\n" +" return iter(self.elements)\n" +"\n" +" def __contains__(self, value):\n" +" return value in self.elements\n" +"\n" +" def __len__(self):\n" +" return len(self.elements)\n" +"\n" +"s1 = ListBasedSet('abcdef')\n" +"s2 = ListBasedSet('defghi')\n" +"overlap = s1 & s2 # The __and__() method is supported " +"automatically" +msgstr "" + +#: ../../library/collections.abc.rst:439 +msgid "Notes on using :class:`Set` and :class:`MutableSet` as a mixin:" +msgstr "" + +#: ../../library/collections.abc.rst:442 +msgid "" +"Since some set operations create new sets, the default mixin methods need a " +"way to create new instances from an :term:`iterable`. The class constructor " +"is assumed to have a signature in the form ``ClassName(iterable)``. That " +"assumption is factored-out to an internal :class:`classmethod` called :meth:" +"`!_from_iterable` which calls ``cls(iterable)`` to produce a new set. If " +"the :class:`Set` mixin is being used in a class with a different constructor " +"signature, you will need to override :meth:`!_from_iterable` with a " +"classmethod or regular method that can construct new instances from an " +"iterable argument." +msgstr "" + +#: ../../library/collections.abc.rst:453 +msgid "" +"To override the comparisons (presumably for speed, as the semantics are " +"fixed), redefine :meth:`~object.__le__` and :meth:`~object.__ge__`, then the " +"other operations will automatically follow suit." +msgstr "" + +#: ../../library/collections.abc.rst:459 +msgid "" +"The :class:`Set` mixin provides a :meth:`!_hash` method to compute a hash " +"value for the set; however, :meth:`~object.__hash__` is not defined because " +"not all sets are :term:`hashable` or immutable. To add set hashability " +"using mixins, inherit from both :meth:`Set` and :meth:`Hashable`, then " +"define ``__hash__ = Set._hash``." +msgstr "" + +#: ../../library/collections.abc.rst:467 +msgid "" +"`OrderedSet recipe `_ for an " +"example built on :class:`MutableSet`." +msgstr "" + +#: ../../library/collections.abc.rst:470 +msgid "For more about ABCs, see the :mod:`abc` module and :pep:`3119`." +msgstr "關於 ABC 的更多資訊請見 :mod:`abc` module 和 :pep:`3119`。" diff --git a/library/collections.po b/library/collections.po index 666c6f13b4..7d2b21367a 100644 --- a/library/collections.po +++ b/library/collections.po @@ -1,2204 +1,2204 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# 周 忠毅 , 2016 -# Adrian Liaw , 2018 -# Matt Wang , 2022-2024 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-10 20:44+0800\n" -"PO-Revision-Date: 2024-01-22 21:42+0800\n" -"Last-Translator: Matt Wang \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" -"X-Generator: Poedit 3.4.1\n" - -#: ../../library/collections.rst:2 -msgid ":mod:`!collections` --- Container datatypes" -msgstr ":mod:`!collections` --- 容器資料型別" - -#: ../../library/collections.rst:10 -msgid "**Source code:** :source:`Lib/collections/__init__.py`" -msgstr "**原始碼：**\\ :source:`Lib/collections/__init__.py`" - -#: ../../library/collections.rst:20 -msgid "" -"This module implements specialized container datatypes providing " -"alternatives to Python's general purpose built-in " -"containers, :class:`dict`, :class:`list`, :class:`set`, and :class:`tuple`." -msgstr "" -"這個模組實作了一些特別的容器資料型別，用來替代 Python 一般內建的容器，例" -"如 :class:`dict`\\ （字典）、:class:`list`\\ （串列）、:class:`set`\\ （集" -"合）和 :class:`tuple`\\ （元組）。" - -#: ../../library/collections.rst:25 -msgid ":func:`namedtuple`" -msgstr ":func:`namedtuple`" - -#: ../../library/collections.rst:25 -msgid "factory function for creating tuple subclasses with named fields" -msgstr "用來建立具名欄位的 tuple 子類別的工廠函式" - -#: ../../library/collections.rst:26 -msgid ":class:`deque`" -msgstr ":class:`deque`" - -#: ../../library/collections.rst:26 -msgid "list-like container with fast appends and pops on either end" -msgstr "" -"一個類似 list 的容器，可以快速的在頭尾加入 (append) 元素與移除 (pop) 元素" - -#: ../../library/collections.rst:27 -msgid ":class:`ChainMap`" -msgstr ":class:`ChainMap`" - -#: ../../library/collections.rst:27 -msgid "dict-like class for creating a single view of multiple mappings" -msgstr "一個類似 dict 的類別，用來為多個對映 (mapping) 建立單一的視圖 (view)" - -#: ../../library/collections.rst:28 -msgid ":class:`Counter`" -msgstr ":class:`Counter`" - -#: ../../library/collections.rst:28 -msgid "dict subclass for counting :term:`hashable` objects" -msgstr "dict 的子類別，用來計算\\ :term:`可雜湊 `\\ 物件的數量" - -#: ../../library/collections.rst:29 -msgid ":class:`OrderedDict`" -msgstr ":class:`OrderedDict`" - -#: ../../library/collections.rst:29 -msgid "dict subclass that remembers the order entries were added" -msgstr "dict 的子類別，會記錄物件被加入的順序" - -#: ../../library/collections.rst:30 -msgid ":class:`defaultdict`" -msgstr ":class:`defaultdict`" - -#: ../../library/collections.rst:30 -msgid "dict subclass that calls a factory function to supply missing values" -msgstr "dict 的子類別，當值不存在 dict 中時會呼叫一個提供預設值的工廠函式" - -#: ../../library/collections.rst:31 -msgid ":class:`UserDict`" -msgstr ":class:`UserDict`" - -#: ../../library/collections.rst:31 -msgid "wrapper around dictionary objects for easier dict subclassing" -msgstr "dict 物件的包裝器 (wrapper)，簡化了 dict 的子類別化過程" - -#: ../../library/collections.rst:32 -msgid ":class:`UserList`" -msgstr ":class:`UserList`" - -#: ../../library/collections.rst:32 -msgid "wrapper around list objects for easier list subclassing" -msgstr "list 物件的包裝器，簡化了 list 的子類別化過程" - -#: ../../library/collections.rst:33 -msgid ":class:`UserString`" -msgstr ":class:`UserString`" - -#: ../../library/collections.rst:33 -msgid "wrapper around string objects for easier string subclassing" -msgstr "字串物件的包裝器，簡化了字串的子類別化過程" - -#: ../../library/collections.rst:38 -msgid ":class:`ChainMap` objects" -msgstr ":class:`ChainMap` 物件" - -#: ../../library/collections.rst:42 -msgid "" -"A :class:`ChainMap` class is provided for quickly linking a number of " -"mappings so they can be treated as a single unit. It is often much faster " -"than creating a new dictionary and running multiple :meth:`~dict.update` " -"calls." -msgstr "" -":class:`ChainMap`\\ （對映鏈結）類別的目的是快速將數個對映連結在一起，讓它們" -"可以被當作一個單元來處理。它通常會比建立一個新的字典並多次呼" -"叫 :meth:`~dict.update` 來得更快。" - -#: ../../library/collections.rst:46 -msgid "" -"The class can be used to simulate nested scopes and is useful in templating." -msgstr "" -"這個類別可用於模擬巢狀作用域 (nested scopes)，且在模板化 (templating) 時能派" -"上用場。" - -#: ../../library/collections.rst:50 -msgid "" -"A :class:`ChainMap` groups multiple dicts or other mappings together to " -"create a single, updateable view. If no *maps* are specified, a single " -"empty dictionary is provided so that a new chain always has at least one " -"mapping." -msgstr "" -"一個 :class:`ChainMap` 將多個 dict 或其他對映組合在一起，建立一個獨立、可更新" -"的視圖。如果沒有指定 *maps*，預設會提供一個空字典讓每個新鏈結都至少有一個對" -"映。" - -#: ../../library/collections.rst:54 -msgid "" -"The underlying mappings are stored in a list. That list is public and can " -"be accessed or updated using the *maps* attribute. There is no other state." -msgstr "" -"底層的對映儲存於一個 list 中，這個 list 是公開的且可透過 *maps* 屬性存取或更" -"新，沒有其他狀態 (state)。" - -#: ../../library/collections.rst:57 -msgid "" -"Lookups search the underlying mappings successively until a key is found. " -"In contrast, writes, updates, and deletions only operate on the first " -"mapping." -msgstr "" -"檢索 (lookup) 陸續查詢底層對映，直到鍵被找到，然而讀取、更新和刪除就只會對第" -"一個對映操作。" - -#: ../../library/collections.rst:60 -msgid "" -"A :class:`ChainMap` incorporates the underlying mappings by reference. So, " -"if one of the underlying mappings gets updated, those changes will be " -"reflected in :class:`ChainMap`." -msgstr "" -":class:`ChainMap` 透過參照將底層對映合併，所以當一個底層對映被更新，這些改變" -"也會反映到 :class:`ChainMap`。" - -#: ../../library/collections.rst:64 -msgid "" -"All of the usual dictionary methods are supported. In addition, there is a " -"*maps* attribute, a method for creating new subcontexts, and a property for " -"accessing all but the first mapping:" -msgstr "" -"所有常見的字典方法都有支援。此外，還有一個 *maps* 屬性 (attribute)、一個建立" -"子上下文 (subcontext) 的方法、和一個能夠存取除了第一個以外其他所有對映的特性 " -"(property)：" - -#: ../../library/collections.rst:70 -msgid "" -"A user updateable list of mappings. The list is ordered from first-searched " -"to last-searched. It is the only stored state and can be modified to change " -"which mappings are searched. The list should always contain at least one " -"mapping." -msgstr "" -"一個可被更新的對映列表，這個列表是按照被搜尋的順序來排列，在 ChainMap 中它是" -"唯一被儲存的狀態，可被修改來變換搜尋順序。回傳的列表都至少包含一個對映。" - -#: ../../library/collections.rst:77 -msgid "" -"Returns a new :class:`ChainMap` containing a new map followed by all of the " -"maps in the current instance. If ``m`` is specified, it becomes the new map " -"at the front of the list of mappings; if not specified, an empty dict is " -"used, so that a call to ``d.new_child()`` is equivalent to: ``ChainMap({}, " -"*d.maps)``. If any keyword arguments are specified, they update passed map " -"or new empty dict. This method is used for creating subcontexts that can be " -"updated without altering values in any of the parent mappings." -msgstr "" -"回傳包含一個新對映的 :class:`ChainMap`， 新對映後面接著目前實例的所有現存對" -"映。如果有給定 ``m``，``m`` 會成為那個最前面的新對映；若沒有指定，則會加上一" -"個空 dict，如此一來呼叫 ``d.new_child()`` 就等同於 ``ChainMap({}, " -"*d.maps)``。這個方法用於建立子上下文，而保持父對映的不變。" - -#: ../../library/collections.rst:86 -msgid "The optional ``m`` parameter was added." -msgstr "加入可選參數 ``m``。" - -#: ../../library/collections.rst:89 -msgid "Keyword arguments support was added." -msgstr "增加了對關鍵字引數的支援。" - -#: ../../library/collections.rst:94 -msgid "" -"Property returning a new :class:`ChainMap` containing all of the maps in the " -"current instance except the first one. This is useful for skipping the " -"first map in the search. Use cases are similar to those for " -"the :keyword:`nonlocal` keyword used in :term:`nested scopes `. The use cases also parallel those for the built-in :func:`super` " -"function. A reference to ``d.parents`` is equivalent to: " -"``ChainMap(*d.maps[1:])``." -msgstr "" -"回傳一個包含除了第一個以外所有其他對映的新 :class:`ChainMap` 的特性，可用於需" -"要跳過第一個對映的搜尋。使用情境類似於在\\ :term:`巢狀作用域 `\\ 當中使用 :keyword:`nonlocal` 關鍵字，也可與內建函式 :func:`super` " -"做類比。引用 ``d.parents`` 等同於 ``ChainMap(*d.maps[1:])``。" - -#: ../../library/collections.rst:102 -msgid "" -"Note, the iteration order of a :class:`ChainMap` is determined by scanning " -"the mappings last to first::" -msgstr "注意，一個 :class:`ChainMap` 的疊代順序是透過由後往前掃描對映而定： ::" - -#: ../../library/collections.rst:105 -msgid "" -">>> baseline = {'music': 'bach', 'art': 'rembrandt'}\n" -">>> adjustments = {'art': 'van gogh', 'opera': 'carmen'}\n" -">>> list(ChainMap(adjustments, baseline))\n" -"['music', 'art', 'opera']" -msgstr "" -">>> baseline = {'music': 'bach', 'art': 'rembrandt'}\n" -">>> adjustments = {'art': 'van gogh', 'opera': 'carmen'}\n" -">>> list(ChainMap(adjustments, baseline))\n" -"['music', 'art', 'opera']" - -#: ../../library/collections.rst:110 -msgid "" -"This gives the same ordering as a series of :meth:`dict.update` calls " -"starting with the last mapping::" -msgstr "這和呼叫 :meth:`dict.update` 結果的順序一樣是從最後一個對映開始： ::" - -#: ../../library/collections.rst:113 -msgid "" -">>> combined = baseline.copy()\n" -">>> combined.update(adjustments)\n" -">>> list(combined)\n" -"['music', 'art', 'opera']" -msgstr "" -">>> combined = baseline.copy()\n" -">>> combined.update(adjustments)\n" -">>> list(combined)\n" -"['music', 'art', 'opera']" - -#: ../../library/collections.rst:118 -msgid "Added support for ``|`` and ``|=`` operators, specified in :pep:`584`." -msgstr "支援 ``|`` 和 ``|=`` 運算子，詳見 :pep:`584`。" - -#: ../../library/collections.rst:123 -msgid "" -"The `MultiContext class `_ in the Enthought `CodeTools package " -"`_ has options to support writing to " -"any mapping in the chain." -msgstr "" -"Enthought `CodeTools package `_ 中的 " -"`MultiContext class `_ 支援在鏈中選定任意對映寫入。" - -#: ../../library/collections.rst:129 -msgid "" -"Django's `Context class `_ for templating is a read-only chain of mappings. It " -"also features pushing and popping of contexts similar to " -"the :meth:`~collections.ChainMap.new_child` method and " -"the :attr:`~collections.ChainMap.parents` property." -msgstr "" -"Django 中用於模板的 `Context class `_ 是唯讀的對映鏈，也具有加入 (push) 和移除 " -"(pop) 上下文的功能，與 :meth:`~collections.ChainMap.new_child` 方法" -"和 :attr:`~collections.ChainMap.parents` 特性類似。" - -#: ../../library/collections.rst:136 -msgid "" -"The `Nested Contexts recipe `_ has options to control " -"whether writes and other mutations apply only to the first mapping or to any " -"mapping in the chain." -msgstr "" -"`Nested Contexts recipe `_ 提供了控制是否只對鏈中第一個或其他對" -"映做寫入或其他操作的選項。" - -#: ../../library/collections.rst:141 -msgid "" -"A `greatly simplified read-only version of Chainmap `_." -msgstr "" -"一個\\ `極度簡化、維讀版本的 Chainmap `_。" - -#: ../../library/collections.rst:146 -msgid ":class:`ChainMap` Examples and Recipes" -msgstr ":class:`ChainMap` 範例和用法" - -#: ../../library/collections.rst:148 -msgid "This section shows various approaches to working with chained maps." -msgstr "此章節提供了多種操作 ChainMap 的案例。" - -#: ../../library/collections.rst:151 -msgid "Example of simulating Python's internal lookup chain::" -msgstr "模擬 Python 內部檢索鏈結的例子： ::" - -#: ../../library/collections.rst:153 -msgid "" -"import builtins\n" -"pylookup = ChainMap(locals(), globals(), vars(builtins))" -msgstr "" -"import builtins\n" -"pylookup = ChainMap(locals(), globals(), vars(builtins))" - -#: ../../library/collections.rst:156 -msgid "" -"Example of letting user specified command-line arguments take precedence " -"over environment variables which in turn take precedence over default " -"values::" -msgstr "讓使用者指定的命令列引數優先於環境變數、再優先於預設值的範例： ::" - -#: ../../library/collections.rst:159 -msgid "" -"import os, argparse\n" -"\n" -"defaults = {'color': 'red', 'user': 'guest'}\n" -"\n" -"parser = argparse.ArgumentParser()\n" -"parser.add_argument('-u', '--user')\n" -"parser.add_argument('-c', '--color')\n" -"namespace = parser.parse_args()\n" -"command_line_args = {k: v for k, v in vars(namespace).items() if v is not " -"None}\n" -"\n" -"combined = ChainMap(command_line_args, os.environ, defaults)\n" -"print(combined['color'])\n" -"print(combined['user'])" -msgstr "" -"import os, argparse\n" -"\n" -"defaults = {'color': 'red', 'user': 'guest'}\n" -"\n" -"parser = argparse.ArgumentParser()\n" -"parser.add_argument('-u', '--user')\n" -"parser.add_argument('-c', '--color')\n" -"namespace = parser.parse_args()\n" -"command_line_args = {k: v for k, v in vars(namespace).items() if v is not " -"None}\n" -"\n" -"combined = ChainMap(command_line_args, os.environ, defaults)\n" -"print(combined['color'])\n" -"print(combined['user'])" - -#: ../../library/collections.rst:173 -msgid "" -"Example patterns for using the :class:`ChainMap` class to simulate nested " -"contexts::" -msgstr "用 :class:`ChainMap` 類別模擬巢狀上下文的範例模式： ::" - -#: ../../library/collections.rst:176 -msgid "" -"c = ChainMap() # Create root context\n" -"d = c.new_child() # Create nested child context\n" -"e = c.new_child() # Child of c, independent from d\n" -"e.maps[0] # Current context dictionary -- like Python's " -"locals()\n" -"e.maps[-1] # Root context -- like Python's globals()\n" -"e.parents # Enclosing context chain -- like Python's nonlocals\n" -"\n" -"d['x'] = 1 # Set value in current context\n" -"d['x'] # Get first key in the chain of contexts\n" -"del d['x'] # Delete from current context\n" -"list(d) # All nested values\n" -"k in d # Check all nested values\n" -"len(d) # Number of nested values\n" -"d.items() # All nested items\n" -"dict(d) # Flatten into a regular dictionary" -msgstr "" - -#: ../../library/collections.rst:192 -msgid "" -"The :class:`ChainMap` class only makes updates (writes and deletions) to the " -"first mapping in the chain while lookups will search the full chain. " -"However, if deep writes and deletions are desired, it is easy to make a " -"subclass that updates keys found deeper in the chain::" -msgstr "" -":class:`ChainMap` 類別只對鏈結中第一個對映來做寫入或刪除，但檢索則會掃過整個" -"鏈結。但如果需要對更深層的鍵寫入或刪除，透過定義一個子類別來實作也不困難： ::" - -#: ../../library/collections.rst:197 -msgid "" -"class DeepChainMap(ChainMap):\n" -" 'Variant of ChainMap that allows direct updates to inner scopes'\n" -"\n" -" def __setitem__(self, key, value):\n" -" for mapping in self.maps:\n" -" if key in mapping:\n" -" mapping[key] = value\n" -" return\n" -" self.maps[0][key] = value\n" -"\n" -" def __delitem__(self, key):\n" -" for mapping in self.maps:\n" -" if key in mapping:\n" -" del mapping[key]\n" -" return\n" -" raise KeyError(key)\n" -"\n" -">>> d = DeepChainMap({'zebra': 'black'}, {'elephant': 'blue'}, {'lion': " -"'yellow'})\n" -">>> d['lion'] = 'orange' # update an existing key two levels down\n" -">>> d['snake'] = 'red' # new keys get added to the topmost dict\n" -">>> del d['elephant'] # remove an existing key one level down\n" -">>> d # display result\n" -"DeepChainMap({'zebra': 'black', 'snake': 'red'}, {}, {'lion': 'orange'})" -msgstr "" - -#: ../../library/collections.rst:223 -msgid ":class:`Counter` objects" -msgstr ":class:`Counter` 物件" - -#: ../../library/collections.rst:225 -msgid "" -"A counter tool is provided to support convenient and rapid tallies. For " -"example::" -msgstr "提供一個支援方便且快速計數的計數器工具，例如： ::" - -#: ../../library/collections.rst:228 -msgid "" -">>> # Tally occurrences of words in a list\n" -">>> cnt = Counter()\n" -">>> for word in ['red', 'blue', 'red', 'green', 'blue', 'blue']:\n" -"... cnt[word] += 1\n" -"...\n" -">>> cnt\n" -"Counter({'blue': 3, 'red': 2, 'green': 1})\n" -"\n" -">>> # Find the ten most common words in Hamlet\n" -">>> import re\n" -">>> words = re.findall(r'\\w+', open('hamlet.txt').read().lower())\n" -">>> Counter(words).most_common(10)\n" -"[('the', 1143), ('and', 966), ('to', 762), ('of', 669), ('i', 631),\n" -" ('you', 554), ('a', 546), ('my', 514), ('hamlet', 471), ('in', 451)]" -msgstr "" - -#: ../../library/collections.rst:245 -msgid "" -"A :class:`Counter` is a :class:`dict` subclass for counting :term:`hashable` " -"objects. It is a collection where elements are stored as dictionary keys and " -"their counts are stored as dictionary values. Counts are allowed to be any " -"integer value including zero or negative counts. The :class:`Counter` class " -"is similar to bags or multisets in other languages." -msgstr "" -":class:`Counter` 是 :class:`dict` 的子類別，用來計算\\ :term:`可雜湊 " -"`\\ 物件的數量。它是將物件與其計數作為字典的鍵值對儲存的集合容器。" -"計數可以是包含 0 與負數的任何整數值。:class:`Counter` 類別類似其他程式語言中" -"的 bags 或 multisets。" - -#: ../../library/collections.rst:251 -msgid "" -"Elements are counted from an *iterable* or initialized from another " -"*mapping* (or counter):" -msgstr "" -"被計數的元素來自一個 *iterable* 或是被其他的 *mapping*\\ （或 Counter）初始" -"化：" - -#: ../../library/collections.rst:259 -msgid "" -"Counter objects have a dictionary interface except that they return a zero " -"count for missing items instead of raising a :exc:`KeyError`:" -msgstr "" -"Counter 物件擁有一個字典的使用介面，除了遇到 Counter 中沒有的值時會回傳計數 " -"0 取代 :exc:`KeyError` 這點不同：" - -#: ../../library/collections.rst:266 -msgid "" -"Setting a count to zero does not remove an element from a counter. Use " -"``del`` to remove it entirely:" -msgstr "" -"將一個值的計數設為 0 並不會真的從 Counter 中刪除這個元素，要使用 ``del`` 來將" -"其刪除：" - -#: ../../library/collections.rst:274 -msgid "" -"As a :class:`dict` subclass, :class:`Counter` inherited the capability to " -"remember insertion order. Math operations on *Counter* objects also " -"preserve order. Results are ordered according to when an element is first " -"encountered in the left operand and then by the order encountered in the " -"right operand." -msgstr "" -"作為 :class:`dict` 的子類別，:class:`Counter` 繼承了記憶插入順序的功能。對 " -"*Counter* 做數學運算後同樣保留順序性，其結果是依照各個元素在運算元左邊出現的" -"時間先後、再按照運算元右邊出現的時間先後來排列。" - -#: ../../library/collections.rst:280 -msgid "" -"Counter objects support additional methods beyond those available for all " -"dictionaries:" -msgstr "除了字典原本就有的方法外，Counter 物件額外支援數個新方法：" - -#: ../../library/collections.rst:285 -msgid "" -"Return an iterator over elements repeating each as many times as its count. " -"Elements are returned in the order first encountered. If an element's count " -"is less than one, :meth:`elements` will ignore it." -msgstr "" -"回傳每個元素都重複出現計算次數的 iterator（疊代器）物件，其中元素的回傳順序是" -"依照各元素首次出現的時間先後。如果元素的出現次數小於 1，:meth:`elements` 方法" -"會忽略這些元素。" - -#: ../../library/collections.rst:295 -msgid "" -"Return a list of the *n* most common elements and their counts from the most " -"common to the least. If *n* is omitted or ``None``, :meth:`most_common` " -"returns *all* elements in the counter. Elements with equal counts are " -"ordered in the order first encountered:" -msgstr "" -"回傳一個 list，包含出現最多次的 *n* 個元素及其出現次數，並按照出現次數排序。" -"如果 *n* 被省略或者為 ``None``，:meth:`most_common` 會回傳\\ *所有* counter " -"中的元素。出現次數相同的元素會按照首次出現的時間先後來排列：" - -#: ../../library/collections.rst:305 -msgid "" -"Elements are subtracted from an *iterable* or from another *mapping* (or " -"counter). Like :meth:`dict.update` but subtracts counts instead of " -"replacing them. Both inputs and outputs may be zero or negative." -msgstr "" -"減去自一個 *iterable* 或另一個\\ *對映*\\ （或 Counter）中的計數元素，行為類" -"似 :meth:`dict.update` 但是是為了減去計數而非取代其值。輸入和輸出都可以是 0 " -"或是負數。" - -#: ../../library/collections.rst:319 -msgid "Compute the sum of the counts." -msgstr "計算總計數值。" - -#: ../../library/collections.rst:327 -msgid "" -"The usual dictionary methods are available for :class:`Counter` objects " -"except for two which work differently for counters." -msgstr "" -"通常來說字典方法也可以用於 :class:`Counter` 物件，除了以下兩個作用方式與計數" -"器不同。" - -#: ../../library/collections.rst:332 -msgid "This class method is not implemented for :class:`Counter` objects." -msgstr "此類別方法沒有被實作於 :class:`Counter` 物件中。" - -#: ../../library/collections.rst:336 -msgid "" -"Elements are counted from an *iterable* or added-in from another *mapping* " -"(or counter). Like :meth:`dict.update` but adds counts instead of replacing " -"them. Also, the *iterable* is expected to be a sequence of elements, not a " -"sequence of ``(key, value)`` pairs." -msgstr "" -"加上自一個 *iterable* 計算出的計數或加上另一個 *mapping*\\ （或 Counter）中的" -"計數，行為類似 :meth:`dict.update` 但是是為了加上計數而非取代其值。另外，" -"*iterable* 需要是一串將被計算個數元素的序列，而非元素為 ``(key, value)`` 形式" -"的序列。" - -#: ../../library/collections.rst:341 -msgid "" -"Counters support rich comparison operators for equality, subset, and " -"superset relationships: ``==``, ``!=``, ``<``, ``<=``, ``>``, ``>=``. All of " -"those tests treat missing elements as having zero counts so that " -"``Counter(a=1) == Counter(a=1, b=0)`` returns true." -msgstr "" -"Counter 支援相等性、子集和超集關係的 rich comparison 運算子：``==``、``!=``、" -"``<``、``<=``、``>``、``>=``。這些檢測會將不存在的元素之計數值當作零，因此 " -"``Counter(a=1) == Counter(a=1, b=0)`` 將回傳真值。" - -#: ../../library/collections.rst:346 -msgid "Rich comparison operations were added." -msgstr "增加了 rich comparison 運算。" - -#: ../../library/collections.rst:349 -msgid "" -"In equality tests, missing elements are treated as having zero counts. " -"Formerly, ``Counter(a=3)`` and ``Counter(a=3, b=0)`` were considered " -"distinct." -msgstr "" -"在相等性運算中，不存在的元素之計數值會被當作零。在此之前，``Counter(a=3)`` " -"和 ``Counter(a=3, b=0)`` 被視為不同。" - -#: ../../library/collections.rst:354 -msgid "Common patterns for working with :class:`Counter` objects::" -msgstr "使用 :class:`Counter` 物件的常見使用模式： ::" - -#: ../../library/collections.rst:356 -msgid "" -"c.total() # total of all counts\n" -"c.clear() # reset all counts\n" -"list(c) # list unique elements\n" -"set(c) # convert to a set\n" -"dict(c) # convert to a regular dictionary\n" -"c.items() # access the (elem, cnt) pairs\n" -"Counter(dict(list_of_pairs)) # convert from a list of (elem, cnt) pairs\n" -"c.most_common()[:-n-1:-1] # n least common elements\n" -"+c # remove zero and negative counts" -msgstr "" - -#: ../../library/collections.rst:366 -msgid "" -"Several mathematical operations are provided for combining :class:`Counter` " -"objects to produce multisets (counters that have counts greater than zero). " -"Addition and subtraction combine counters by adding or subtracting the " -"counts of corresponding elements. Intersection and union return the minimum " -"and maximum of corresponding counts. Equality and inclusion compare " -"corresponding counts. Each operation can accept inputs with signed counts, " -"but the output will exclude results with counts of zero or less." -msgstr "" -"為結合多個 :class:`Counter` 物件以產生 multiset（多重集合，擁有大於 0 計數元" -"素的計數器），有提供了幾種數學操作。加法和減法是根據各個對應元素分別將 " -"Counter 加上和減去計數，交集和聯集分別回傳各個元素最小和最大計數，相等性與包" -"含性運算則會比較對應的計數。每一個操作都可以接受輸入帶有正負號的計數，但輸出" -"的 Counter 則會將擁有小於或等於 0 計數的元素剔除。" - -#: ../../library/collections.rst:374 -msgid "" -">>> c = Counter(a=3, b=1)\n" -">>> d = Counter(a=1, b=2)\n" -">>> c + d # add two counters together: c[x] + d[x]\n" -"Counter({'a': 4, 'b': 3})\n" -">>> c - d # subtract (keeping only positive counts)\n" -"Counter({'a': 2})\n" -">>> c & d # intersection: min(c[x], d[x])\n" -"Counter({'a': 1, 'b': 1})\n" -">>> c | d # union: max(c[x], d[x])\n" -"Counter({'a': 3, 'b': 2})\n" -">>> c == d # equality: c[x] == d[x]\n" -"False\n" -">>> c <= d # inclusion: c[x] <= d[x]\n" -"False" -msgstr "" - -#: ../../library/collections.rst:391 -msgid "" -"Unary addition and subtraction are shortcuts for adding an empty counter or " -"subtracting from an empty counter." -msgstr "加減法的一元運算子分別是加上空的 Counter 和從空 Counter 減去的簡寫。" - -#: ../../library/collections.rst:400 -msgid "" -"Added support for unary plus, unary minus, and in-place multiset operations." -msgstr "開始支援加減一元運算子和 multiset 的原地 (in-place) 操作。" - -#: ../../library/collections.rst:405 -msgid "" -"Counters were primarily designed to work with positive integers to represent " -"running counts; however, care was taken to not unnecessarily preclude use " -"cases needing other types or negative values. To help with those use cases, " -"this section documents the minimum range and type restrictions." -msgstr "" -"Counter 主要是被設計來操作正整數以當作使用中的計數，但為了某些會用到計數之值" -"為負數或為其他型別的案例中，Counter 也小心地被設計成不會預先排除這些特殊元" -"素。為了輔助使用於上述案例，這一小節記錄了最小範圍和型別限制。" - -#: ../../library/collections.rst:410 -msgid "" -"The :class:`Counter` class itself is a dictionary subclass with no " -"restrictions on its keys and values. The values are intended to be numbers " -"representing counts, but you *could* store anything in the value field." -msgstr "" -":class:`Counter` 類別本身是字典的子類別，且不限制其鍵與值。值被用來表示計數，" -"但實際上你\\ *可以*\\ 儲存任何值。" - -#: ../../library/collections.rst:414 -msgid "" -"The :meth:`~Counter.most_common` method requires only that the values be " -"orderable." -msgstr "使用 :meth:`~Counter.most_common` 方法的唯一條件是其值要是可被排序的。" - -#: ../../library/collections.rst:416 -msgid "" -"For in-place operations such as ``c[key] += 1``, the value type need only " -"support addition and subtraction. So fractions, floats, and decimals would " -"work and negative values are supported. The same is also true " -"for :meth:`~Counter.update` and :meth:`~Counter.subtract` which allow " -"negative and zero values for both inputs and outputs." -msgstr "" -"像是 ``c[key] += 1`` 的原地操作中，其值之型別只必須支援加減，所以分數、浮點" -"數、十進位數與其負值都可以使用。同理，:meth:`~Counter.update` " -"和 :meth:`~Counter.subtract` 也都允許 0 或負值為輸入或輸出。" - -#: ../../library/collections.rst:422 -msgid "" -"The multiset methods are designed only for use cases with positive values. " -"The inputs may be negative or zero, but only outputs with positive values " -"are created. There are no type restrictions, but the value type needs to " -"support addition, subtraction, and comparison." -msgstr "" -"Multiset 相關方法只為了處理正值而設計，其輸入允許是 0 或負值但只有正值會被輸" -"出。並無型別限制，但其值的型別須支援加、減及比較運算。" - -#: ../../library/collections.rst:427 -msgid "" -"The :meth:`~Counter.elements` method requires integer counts. It ignores " -"zero and negative counts." -msgstr ":meth:`~Counter.elements` 方法需要其計數為正值，如為 0 或負值則忽略。" - -#: ../../library/collections.rst:432 -msgid "" -"`Bag class `_ in Smalltalk." -msgstr "" -"Smalltalk 中的 `Bag class `_。" - -#: ../../library/collections.rst:435 -msgid "" -"Wikipedia entry for `Multisets `_." -msgstr "" -"維基百科上的\\ `多重集合 `_\\ 條目。" - -#: ../../library/collections.rst:437 -msgid "" -"`C++ multisets `_ tutorial with examples." -msgstr "" -"`C++ multisets `_ 教學與範例。" - -#: ../../library/collections.rst:440 -msgid "" -"For mathematical operations on multisets and their use cases, see *Knuth, " -"Donald. The Art of Computer Programming Volume II, Section 4.6.3, Exercise " -"19*." -msgstr "" -"Multiset 的數學運算及其使用時機，參考 *Knuth, Donald. The Art of Computer " -"Programming Volume II, Section 4.6.3, Exercise 19*。" - -#: ../../library/collections.rst:444 -msgid "" -"To enumerate all distinct multisets of a given size over a given set of " -"elements, see :func:`itertools.combinations_with_replacement`::" -msgstr "" -"若要根據給定的元素集合來列舉出所有不重複且擁有指定元素數量的 multiset，請" -"見 :func:`itertools.combinations_with_replacement`： ::" - -#: ../../library/collections.rst:447 -msgid "" -"map(Counter, combinations_with_replacement('ABC', 2)) # --> AA AB AC BB BC CC" -msgstr "" -"map(Counter, combinations_with_replacement('ABC', 2)) # --> AA AB AC BB BC CC" - -#: ../../library/collections.rst:451 -msgid ":class:`deque` objects" -msgstr ":class:`deque` 物件" - -#: ../../library/collections.rst:455 -msgid "" -"Returns a new deque object initialized left-to-right (using :meth:`append`) " -"with data from *iterable*. If *iterable* is not specified, the new deque is " -"empty." -msgstr "" -"回傳一個新的 deque（雙端佇列）物件，將 *iterable* 中的資料由左至右（使" -"用 :meth:`append`\\ ）加入來做初始化。如果 *iterable* 並未給定，回傳的則是一" -"個空的 deque。" - -#: ../../library/collections.rst:458 -msgid "" -"Deques are a generalization of stacks and queues (the name is pronounced " -"\"deck\" and is short for \"double-ended queue\"). Deques support thread-" -"safe, memory efficient appends and pops from either side of the deque with " -"approximately the same *O*\\ (1) performance in either direction." -msgstr "" -"Deque（發音為 \"deck\"，為 \"double-ended queue\" 的簡稱）為 stack 和 queue " -"的一般化。deque 支援執行緒安全 (thread-safe)，且能夠有效率地節省記憶體在頭和" -"尾加入和移除元素，兩個方向的表現都大致為 *O*\\ (1) 複雜度。" - -#: ../../library/collections.rst:463 -msgid "" -"Though :class:`list` objects support similar operations, they are optimized " -"for fast fixed-length operations and incur *O*\\ (*n*) memory movement costs " -"for ``pop(0)`` and ``insert(0, v)`` operations which change both the size " -"and position of the underlying data representation." -msgstr "" -"雖然 :class:`list` 物件也支援類似操作，但 list 優化了長度固定時的操作，而會改" -"變底層資料的長度及位置的 ``pop(0)`` 和 ``insert(0, v)`` 操作，記憶體移動則為 " -"*O*\\ (*n*) 複雜度。" - -#: ../../library/collections.rst:469 -msgid "" -"If *maxlen* is not specified or is ``None``, deques may grow to an arbitrary " -"length. Otherwise, the deque is bounded to the specified maximum length. " -"Once a bounded length deque is full, when new items are added, a " -"corresponding number of items are discarded from the opposite end. Bounded " -"length deques provide functionality similar to the ``tail`` filter in Unix. " -"They are also useful for tracking transactions and other pools of data where " -"only the most recent activity is of interest." -msgstr "" -"如果 *maxlen* 沒有給定或者為 ``None``，deque 可以增長到任意長度；但若有給定的" -"話，deque 的最大長度就會被限制。一個被限制長度的 deque 一但滿了，若在一端加入" -"數個新元素，則同時會在另一端移除相同數量的元素。限定長度的 deque 提供了和 " -"Unix ``tail`` filter 類似的功能，可用於追蹤使用者在意的那些最新執行事項或數據" -"源。" - -#: ../../library/collections.rst:478 -msgid "Deque objects support the following methods:" -msgstr "Deque 物件支援以下方法：" - -#: ../../library/collections.rst:482 -msgid "Add *x* to the right side of the deque." -msgstr "將 *x* 自 deque 的右側加入。" - -#: ../../library/collections.rst:487 -msgid "Add *x* to the left side of the deque." -msgstr "將 *x* 自 deque 的左側加入。" - -#: ../../library/collections.rst:492 -msgid "Remove all elements from the deque leaving it with length 0." -msgstr "將所有元素從 deque 中移除，使其長度為 0。" - -#: ../../library/collections.rst:497 -msgid "Create a shallow copy of the deque." -msgstr "建立一個 deque 的淺複製 (shallow copy)。" - -#: ../../library/collections.rst:504 -msgid "Count the number of deque elements equal to *x*." -msgstr "計算 deque 內元素為 *x* 的個數。" - -#: ../../library/collections.rst:511 -msgid "" -"Extend the right side of the deque by appending elements from the iterable " -"argument." -msgstr "將 iterable 引數加入 deque 的右側。" - -#: ../../library/collections.rst:517 -msgid "" -"Extend the left side of the deque by appending elements from *iterable*. " -"Note, the series of left appends results in reversing the order of elements " -"in the iterable argument." -msgstr "" -"將 iterable 引數加入 deque 的左側。要注意的是，加入後的元素順序和 iterable 參" -"數是相反的。" - -#: ../../library/collections.rst:524 -msgid "" -"Return the position of *x* in the deque (at or after index *start* and " -"before index *stop*). Returns the first match or raises :exc:`ValueError` " -"if not found." -msgstr "" -"回傳 deque 中 *x* 的位置（或在索引 *start* 之後、索引 *stop* 之前的位置）。回" -"傳第一個匹配的位置，如果沒找到就引發 :exc:`ValueError`。" - -#: ../../library/collections.rst:533 -msgid "Insert *x* into the deque at position *i*." -msgstr "在 deque 位置 *i* 中插入 *x*。" - -#: ../../library/collections.rst:535 -msgid "" -"If the insertion would cause a bounded deque to grow beyond *maxlen*, " -"an :exc:`IndexError` is raised." -msgstr "" -"如果此插入操作導致 deque 超過其長度上限 *maxlen* 的話，會引" -"發 :exc:`IndexError` 例外。" - -#: ../../library/collections.rst:543 -msgid "" -"Remove and return an element from the right side of the deque. If no " -"elements are present, raises an :exc:`IndexError`." -msgstr "" -"移除並回傳 deque 的最右側元素，若本來就沒有任何元素，則會引" -"發 :exc:`IndexError`。" - -#: ../../library/collections.rst:549 -msgid "" -"Remove and return an element from the left side of the deque. If no elements " -"are present, raises an :exc:`IndexError`." -msgstr "" -"移除並回傳 deque 的最左側元素，若本來就沒有任何元素，則會引" -"發 :exc:`IndexError`。" - -#: ../../library/collections.rst:555 -msgid "" -"Remove the first occurrence of *value*. If not found, raises " -"a :exc:`ValueError`." -msgstr "移除第一個出現的 *value*，如果沒找到的話就引發一個 :exc:`ValueError`。" - -#: ../../library/collections.rst:561 -msgid "Reverse the elements of the deque in-place and then return ``None``." -msgstr "將 deque 中的元素原地 (in-place) 倒序排列並回傳 ``None``。" - -#: ../../library/collections.rst:568 -msgid "" -"Rotate the deque *n* steps to the right. If *n* is negative, rotate to the " -"left." -msgstr "將 deque 向右輪轉 *n* 步。若 *n* 為負值則向左輪轉。" - -#: ../../library/collections.rst:571 -msgid "" -"When the deque is not empty, rotating one step to the right is equivalent to " -"``d.appendleft(d.pop())``, and rotating one step to the left is equivalent " -"to ``d.append(d.popleft())``." -msgstr "" -"當 deque 不是空的，向右輪轉一步和 ``d.appendleft(d.pop())`` 有相同意義，而向" -"左輪轉亦等價於 ``d.append(d.popleft())``。" - -#: ../../library/collections.rst:576 -msgid "Deque objects also provide one read-only attribute:" -msgstr "Deque 物件也提供了一個唯讀屬性：" - -#: ../../library/collections.rst:580 -msgid "Maximum size of a deque or ``None`` if unbounded." -msgstr "Deque 的最大長度，如果不限制長度的話則為 ``None``。" - -#: ../../library/collections.rst:585 -msgid "" -"In addition to the above, deques support iteration, pickling, ``len(d)``, " -"``reversed(d)``, ``copy.copy(d)``, ``copy.deepcopy(d)``, membership testing " -"with the :keyword:`in` operator, and subscript references such as ``d[0]`` " -"to access the first element. Indexed access is *O*\\ (1) at both ends but " -"slows to *O*\\ (*n*) in the middle. For fast random access, use lists " -"instead." -msgstr "" -"除了以上使用方式，deque 亦支援了疊代、pickle、``len(d)``、``reversed(d)``、" -"``copy.copy(d)``、``copy.deepcopy(d)``、用 :keyword:`in` 運算子來作隸屬資格檢" -"測以及像是 ``d[0]`` 的標號引用來取得第一個元素。在兩端做索引存取的複雜度為 " -"*O*\\ (1) 但越靠近中間則減慢至 *O*\\ (*n*)。若想要隨機而快速的存取，使用 " -"list 會較為合適。" - -#: ../../library/collections.rst:591 -msgid "" -"Starting in version 3.5, deques support ``__add__()``, ``__mul__()``, and " -"``__imul__()``." -msgstr "" -"自從 3.5 版本起，deque 開始支援 ``__add__()``、``__mul__()`` 和 " -"``__imul__()``。" - -#: ../../library/collections.rst:594 -msgid "Example:" -msgstr "範例：" - -#: ../../library/collections.rst:596 -msgid "" -">>> from collections import deque\n" -">>> d = deque('ghi') # make a new deque with three items\n" -">>> for elem in d: # iterate over the deque's elements\n" -"... print(elem.upper())\n" -"G\n" -"H\n" -"I\n" -"\n" -">>> d.append('j') # add a new entry to the right side\n" -">>> d.appendleft('f') # add a new entry to the left side\n" -">>> d # show the representation of the deque\n" -"deque(['f', 'g', 'h', 'i', 'j'])\n" -"\n" -">>> d.pop() # return and remove the rightmost item\n" -"'j'\n" -">>> d.popleft() # return and remove the leftmost item\n" -"'f'\n" -">>> list(d) # list the contents of the deque\n" -"['g', 'h', 'i']\n" -">>> d[0] # peek at leftmost item\n" -"'g'\n" -">>> d[-1] # peek at rightmost item\n" -"'i'\n" -"\n" -">>> list(reversed(d)) # list the contents of a deque in " -"reverse\n" -"['i', 'h', 'g']\n" -">>> 'h' in d # search the deque\n" -"True\n" -">>> d.extend('jkl') # add multiple elements at once\n" -">>> d\n" -"deque(['g', 'h', 'i', 'j', 'k', 'l'])\n" -">>> d.rotate(1) # right rotation\n" -">>> d\n" -"deque(['l', 'g', 'h', 'i', 'j', 'k'])\n" -">>> d.rotate(-1) # left rotation\n" -">>> d\n" -"deque(['g', 'h', 'i', 'j', 'k', 'l'])\n" -"\n" -">>> deque(reversed(d)) # make a new deque in reverse order\n" -"deque(['l', 'k', 'j', 'i', 'h', 'g'])\n" -">>> d.clear() # empty the deque\n" -">>> d.pop() # cannot pop from an empty deque\n" -"Traceback (most recent call last):\n" -" File \"\", line 1, in -toplevel-\n" -" d.pop()\n" -"IndexError: pop from an empty deque\n" -"\n" -">>> d.extendleft('abc') # extendleft() reverses the input " -"order\n" -">>> d\n" -"deque(['c', 'b', 'a'])" -msgstr "" - -#: ../../library/collections.rst:651 -msgid ":class:`deque` Recipes" -msgstr ":class:`deque` 用法" - -#: ../../library/collections.rst:653 -msgid "This section shows various approaches to working with deques." -msgstr "這一章節提供了多種操作 deque 的案例。" - -#: ../../library/collections.rst:655 -msgid "" -"Bounded length deques provide functionality similar to the ``tail`` filter " -"in Unix::" -msgstr "被限制長度的 deque 功能類似 Unix 中的 ``tail`` filter： ::" - -#: ../../library/collections.rst:658 -msgid "" -"def tail(filename, n=10):\n" -" 'Return the last n lines of a file'\n" -" with open(filename) as f:\n" -" return deque(f, n)" -msgstr "" -"def tail(filename, n=10):\n" -" '回傳檔案的最後 n 行'\n" -" with open(filename) as f:\n" -" return deque(f, n)" - -#: ../../library/collections.rst:663 -msgid "" -"Another approach to using deques is to maintain a sequence of recently added " -"elements by appending to the right and popping to the left::" -msgstr "另一用法是透過從右邊加入、從左邊移除來維護最近加入元素的 list： ::" - -#: ../../library/collections.rst:666 -msgid "" -"def moving_average(iterable, n=3):\n" -" # moving_average([40, 30, 50, 46, 39, 44]) --> 40.0 42.0 45.0 43.0\n" -" # https://en.wikipedia.org/wiki/Moving_average\n" -" it = iter(iterable)\n" -" d = deque(itertools.islice(it, n-1))\n" -" d.appendleft(0)\n" -" s = sum(d)\n" -" for elem in it:\n" -" s += elem - d.popleft()\n" -" d.append(elem)\n" -" yield s / n" -msgstr "" - -#: ../../library/collections.rst:678 -msgid "" -"A `round-robin scheduler `_ can be implemented with input iterators stored in " -"a :class:`deque`. Values are yielded from the active iterator in position " -"zero. If that iterator is exhausted, it can be removed " -"with :meth:`~deque.popleft`; otherwise, it can be cycled back to the end " -"with the :meth:`~deque.rotate` method::" -msgstr "" -"一個\\ `輪詢調度器 `_\\ 可以透過在 :class:`deque` 中放入 iterator 來實現，值自" -"目前 iterator 的位置 0 取出，如果 iterator 已經消耗完畢就" -"用 :meth:`~deque.popleft` 將其從佇列中移除，否則利用 :meth:`~deque.rotate` 來" -"將其移至佇列尾端： ::" - -#: ../../library/collections.rst:685 -msgid "" -"def roundrobin(*iterables):\n" -" \"roundrobin('ABC', 'D', 'EF') --> A D E B F C\"\n" -" iterators = deque(map(iter, iterables))\n" -" while iterators:\n" -" try:\n" -" while True:\n" -" yield next(iterators[0])\n" -" iterators.rotate(-1)\n" -" except StopIteration:\n" -" # Remove an exhausted iterator.\n" -" iterators.popleft()" -msgstr "" -"def roundrobin(*iterables):\n" -" \"roundrobin('ABC', 'D', 'EF') --> A D E B F C\"\n" -" iterators = deque(map(iter, iterables))\n" -" while iterators:\n" -" try:\n" -" while True:\n" -" yield next(iterators[0])\n" -" iterators.rotate(-1)\n" -" except StopIteration:\n" -" # 移除耗盡的疊代器。\n" -" iterators.popleft()" - -#: ../../library/collections.rst:697 -msgid "" -"The :meth:`~deque.rotate` method provides a way to implement :class:`deque` " -"slicing and deletion. For example, a pure Python implementation of ``del " -"d[n]`` relies on the ``rotate()`` method to position elements to be popped::" -msgstr "" -":meth:`~deque.rotate` 提供了可以用來實作 :class:`deque` 切片和刪除的方法。舉" -"例來說，用純 Python 實作 ``del d[n]`` 需要用 ``rotate()`` 來定位要被移除的元" -"素： ::" - -#: ../../library/collections.rst:701 -msgid "" -"def delete_nth(d, n):\n" -" d.rotate(-n)\n" -" d.popleft()\n" -" d.rotate(n)" -msgstr "" -"def delete_nth(d, n):\n" -" d.rotate(-n)\n" -" d.popleft()\n" -" d.rotate(n)" - -#: ../../library/collections.rst:706 -msgid "" -"To implement :class:`deque` slicing, use a similar approach " -"applying :meth:`~deque.rotate` to bring a target element to the left side of " -"the deque. Remove old entries with :meth:`~deque.popleft`, add new entries " -"with :meth:`~deque.extend`, and then reverse the rotation. With minor " -"variations on that approach, it is easy to implement Forth style stack " -"manipulations such as ``dup``, ``drop``, ``swap``, ``over``, ``pick``, " -"``rot``, and ``roll``." -msgstr "" -"要實現 :class:`deque` 切片，可使用近似以下方法：使用 :meth:`~deque.rotate` 來" -"將目標元素移動到 deque 最左側，用 :meth:`~deque.popleft` 移除舊元素並" -"用 :meth:`~deque.extend` 加入新元素，最後再反向 rotate。在這個方法上做小小的" -"更動就能簡單地實現 Forth 風格的 stack 操作，例如 ``dup``、``drop``、" -"``swap``、``over``、``pick``、``rot`` 和 ``roll``。" - -#: ../../library/collections.rst:716 -msgid ":class:`defaultdict` objects" -msgstr ":class:`defaultdict` 物件" - -#: ../../library/collections.rst:720 -msgid "" -"Return a new dictionary-like object. :class:`defaultdict` is a subclass of " -"the built-in :class:`dict` class. It overrides one method and adds one " -"writable instance variable. The remaining functionality is the same as for " -"the :class:`dict` class and is not documented here." -msgstr "" -"回傳一個新的類似字典的物件。:class:`defaultdict` 是內建類別 :class:`dict` 的" -"子類別。它覆蓋掉了一個方法並添加了一個可寫入的實例變數。其餘功能" -"與 :class:`dict` 相同，此文件不再複述。" - -#: ../../library/collections.rst:725 -msgid "" -"The first argument provides the initial value for " -"the :attr:`default_factory` attribute; it defaults to ``None``. All " -"remaining arguments are treated the same as if they were passed to " -"the :class:`dict` constructor, including keyword arguments." -msgstr "" -"第一個引數為 :attr:`default_factory` 屬性提供了初始值，他被預設為 ``None``，" -"所有其他的引數（包括關鍵字引數）都會被傳遞給 :class:`dict` 的建構函式 " -"(constructor)。" - -#: ../../library/collections.rst:731 -msgid "" -":class:`defaultdict` objects support the following method in addition to the " -"standard :class:`dict` operations:" -msgstr ":class:`defaultdict` 物件支援以下 :class:`dict` 所沒有的方法：" - -#: ../../library/collections.rst:736 -msgid "" -"If the :attr:`default_factory` attribute is ``None``, this raises " -"a :exc:`KeyError` exception with the *key* as argument." -msgstr "" -"如果 :attr:`default_factory` 屬性為 ``None``，呼叫此方法會引發一個附帶引數 " -"*key* 的 :exc:`KeyError` 例外。" - -#: ../../library/collections.rst:739 -msgid "" -"If :attr:`default_factory` is not ``None``, it is called without arguments " -"to provide a default value for the given *key*, this value is inserted in " -"the dictionary for the *key*, and returned." -msgstr "" -"如果 :attr:`default_factory` 不為 ``None``，它會不帶引數地被呼叫來為給定的 " -"*key* 提供一個預設值，這個值和 *key* 被作為鍵值對來插入到字典中，並且被此方法" -"所回傳。" - -#: ../../library/collections.rst:743 -msgid "" -"If calling :attr:`default_factory` raises an exception this exception is " -"propagated unchanged." -msgstr "" -"如果呼叫 :attr:`default_factory` 時發生例外，則該例外將會保持不變地向外傳遞。" - -#: ../../library/collections.rst:746 -msgid "" -"This method is called by the :meth:`~object.__getitem__` method of " -"the :class:`dict` class when the requested key is not found; whatever it " -"returns or raises is then returned or raised by :meth:`~object.__getitem__`." -msgstr "" -"在無法找到所要求的鍵時，此方法會被 :class:`dict` 類別" -"的 :meth:`~object.__getitem__` 方法呼叫。無論此方法回傳了值還是引發了例外，都" -"會被 :meth:`~object.__getitem__` 所傳遞。" - -#: ../../library/collections.rst:750 -msgid "" -"Note that :meth:`__missing__` is *not* called for any operations " -"besides :meth:`~object.__getitem__`. This means that :meth:`~dict.get` will, " -"like normal dictionaries, return ``None`` as a default rather than " -"using :attr:`default_factory`." -msgstr "" -"注意，:meth:`__missing__` *不會*\\ 被 :meth:`~object.__getitem__` 以外的其他" -"方法呼叫，這意味著 :meth:`~dict.get` 會像一般的 dict 那樣回傳 ``None`` 做為預" -"設值，而非使用 :attr:`default_factory`。" - -#: ../../library/collections.rst:756 -msgid ":class:`defaultdict` objects support the following instance variable:" -msgstr ":class:`defaultdict` 物件支援以下實例變數：" - -#: ../../library/collections.rst:761 -msgid "" -"This attribute is used by the :meth:`~defaultdict.__missing__` method; it is " -"initialized from the first argument to the constructor, if present, or to " -"``None``, if absent." -msgstr "" -"此屬性為 :meth:`~defaultdict.__missing__` 方法所使用。如果有引數被傳入建構函式，則此屬性會" -"被初始化成第一個引數，如未提供引數則被初始化為 ``None``。" - -#: ../../library/collections.rst:765 ../../library/collections.rst:1192 -msgid "" -"Added merge (``|``) and update (``|=``) operators, specified in :pep:`584`." -msgstr "新增合併 (``|``) 和更新 (``|=``) 運算子，請見 :pep:`584`。" - -#: ../../library/collections.rst:771 -msgid ":class:`defaultdict` Examples" -msgstr ":class:`defaultdict` 範例" - -#: ../../library/collections.rst:773 -msgid "" -"Using :class:`list` as the :attr:`~defaultdict.default_factory`, it is easy " -"to group a sequence of key-value pairs into a dictionary of lists:" -msgstr "" -"使用 :class:`list` 作為 :attr:`~defaultdict.default_factory` 可以很輕鬆地將鍵" -"值對序列轉換為包含 list 之字典：" - -#: ../../library/collections.rst:784 -msgid "" -"When each key is encountered for the first time, it is not already in the " -"mapping; so an entry is automatically created using " -"the :attr:`~defaultdict.default_factory` function which returns an " -"empty :class:`list`. The :meth:`list.append` operation then attaches the " -"value to the new list. When keys are encountered again, the look-up " -"proceeds normally (returning the list for that key) and " -"the :meth:`list.append` operation adds another value to the list. This " -"technique is simpler and faster than an equivalent technique " -"using :meth:`dict.setdefault`:" -msgstr "" -"當每個鍵第一次被存取時，它還沒有存在於對映中，所以會自動呼" -"叫 :attr:`~defaultdict.default_factory` 方法來回傳一個空的 :class:`list` 以建" -"立一個條目，:meth:`list.append` 操作後續會再新增值到這個新的列表裡。當再次存" -"取該鍵時，就如普通字典般操作（回傳該鍵所對應到的 list），:meth:`list.append` " -"也會新增另一個值到 list 中。和使用與其等價的 :meth:`dict.setdefault` 相比，這" -"個技巧更加快速和簡單：" - -#: ../../library/collections.rst:799 -msgid "" -"Setting the :attr:`~defaultdict.default_factory` to :class:`int` makes " -"the :class:`defaultdict` useful for counting (like a bag or multiset in " -"other languages):" -msgstr "" -"設定 :attr:`~defaultdict.default_factory` 為 :class:`int` 使" -"得 :class:`defaultdict` 可被用於計數（類似其他語言中的 bag 或 multiset）：" - -#: ../../library/collections.rst:811 -msgid "" -"When a letter is first encountered, it is missing from the mapping, so " -"the :attr:`~defaultdict.default_factory` function calls :func:`int` to " -"supply a default count of zero. The increment operation then builds up the " -"count for each letter." -msgstr "" -"當一個字母首次被存取時，它並不存在於對映中，" -"則 :attr:`~defaultdict.default_factory` 函式會呼叫 :func:`int` 來提供一個整" -"數 0 作為預設值。後續的增加操作繼續對每個字母做計數。" - -#: ../../library/collections.rst:815 -msgid "" -"The function :func:`int` which always returns zero is just a special case of " -"constant functions. A faster and more flexible way to create constant " -"functions is to use a lambda function which can supply any constant value " -"(not just zero):" -msgstr "" -"函式 :func:`int` 總是回傳 0，這是常數函式的特殊情況。一個更快、更有彈性的方法" -"是使用 lambda 函式來提供任何常數值（不用一定要是 0）：" - -#: ../../library/collections.rst:828 -msgid "" -"Setting the :attr:`~defaultdict.default_factory` to :class:`set` makes " -"the :class:`defaultdict` useful for building a dictionary of sets:" -msgstr "" -"將 :attr:`~defaultdict.default_factory` 設為 :class:`set` " -"使 :class:`defaultdict` 可用於構建一個值為 set 的字典：" - -#: ../../library/collections.rst:841 -msgid ":func:`namedtuple` Factory Function for Tuples with Named Fields" -msgstr ":func:`namedtuple` 擁有具名欄位之 tuple 的工廠函式" - -#: ../../library/collections.rst:843 -msgid "" -"Named tuples assign meaning to each position in a tuple and allow for more " -"readable, self-documenting code. They can be used wherever regular tuples " -"are used, and they add the ability to access fields by name instead of " -"position index." -msgstr "" -"Named tuple（具名元組）賦予 tuple 中各個位置意義，使程式碼更有可讀性與自我文" -"件性。它們可以用於任何普通 tuple 可使用的場合，賦予其透過名稱（而非位置索引）" -"來存取欄位的能力。" - -#: ../../library/collections.rst:849 -msgid "" -"Returns a new tuple subclass named *typename*. The new subclass is used to " -"create tuple-like objects that have fields accessible by attribute lookup as " -"well as being indexable and iterable. Instances of the subclass also have a " -"helpful docstring (with *typename* and *field_names*) and a " -"helpful :meth:`~object.__repr__` method which lists the tuple contents in a " -"``name=value`` format." -msgstr "" -"回傳一個名為 *typename* 的新 tuple 子類別。這個新的子類別被用於建立類似 " -"tuple 的物件，可以透過屬性名稱來存取欄位，它同時也是可索引 (indexable) 和可疊" -"代的 (iterable)。子類別實例同樣有文件字串 (docstring)（有類別名稱 *typename* " -"和欄位名 *field_names*）和一個好用的 :meth:`~object.__repr__` 方法，可將 " -"tuple 內容以 ``name=value`` 格式列出。" - -#: ../../library/collections.rst:856 -msgid "" -"The *field_names* are a sequence of strings such as ``['x', 'y']``. " -"Alternatively, *field_names* can be a single string with each fieldname " -"separated by whitespace and/or commas, for example ``'x y'`` or ``'x, y'``." -msgstr "" -"*field_names* 是一個像 ``['x', 'y']`` 一樣的字串序列。*field_names* 也可以是" -"一個用空白或逗號分隔各個欄位名稱的字串，比如 ``'x y'`` 或者 ``'x, y'``。" - -#: ../../library/collections.rst:860 -msgid "" -"Any valid Python identifier may be used for a fieldname except for names " -"starting with an underscore. Valid identifiers consist of letters, digits, " -"and underscores but do not start with a digit or underscore and cannot be " -"a :mod:`keyword` such as *class*, *for*, *return*, *global*, *pass*, or " -"*raise*." -msgstr "" -"除了底線開頭以外的其他任何有效 Python 識別字 (identifier) 都可以作為欄位名" -"稱，有效識別字由字母、數字、底線所組成，但不能是數字或底線開頭，也不能是關鍵" -"詞 :mod:`keyword`，例如 *class*、*for*、*return*、*global*、*pass* 或 " -"*raise*。" - -#: ../../library/collections.rst:866 -msgid "" -"If *rename* is true, invalid fieldnames are automatically replaced with " -"positional names. For example, ``['abc', 'def', 'ghi', 'abc']`` is " -"converted to ``['abc', '_1', 'ghi', '_3']``, eliminating the keyword ``def`` " -"and the duplicate fieldname ``abc``." -msgstr "" -"如果 *rename* 為真值，無效的欄位名稱會自動被位置名稱取代。比如 ``['abc', " -"'def', 'ghi', 'abc']`` 會被轉換成 ``['abc', '_1', 'ghi', '_3']``，移除了關鍵" -"字 ``def`` 和重複欄位名 ``abc``。" - -#: ../../library/collections.rst:871 -msgid "" -"*defaults* can be ``None`` or an :term:`iterable` of default values. Since " -"fields with a default value must come after any fields without a default, " -"the *defaults* are applied to the rightmost parameters. For example, if the " -"fieldnames are ``['x', 'y', 'z']`` and the defaults are ``(1, 2)``, then " -"``x`` will be a required argument, ``y`` will default to ``1``, and ``z`` " -"will default to ``2``." -msgstr "" -"*defaults* 可以為 ``None`` 或者是一個預設值的 :term:`iterable`。因為有預設值" -"的欄位必須出現在那些沒有預設值的欄位之後，*defaults* 是被應用在右側的引數。例" -"如 fieldnames 為 ``['x', 'y', 'z']`` 且 defaults 為 ``(1, 2)``，那麼 ``x`` 就" -"必須被給定一個引數，``y`` 被預設為 ``1``，``z`` 則被預設為 ``2``。" - -#: ../../library/collections.rst:878 -msgid "" -"If *module* is defined, the :attr:`~type.__module__` attribute of the named " -"tuple is set to that value." -msgstr "" -"如果 *module* 值有被定義，named tuple 的 :attr:`~type.__module__` 屬性就被設" -"定為該值。" - -#: ../../library/collections.rst:881 -msgid "" -"Named tuple instances do not have per-instance dictionaries, so they are " -"lightweight and require no more memory than regular tuples." -msgstr "" -"Named tuple 實例中沒有字典，所以它們更加輕量，且和一般 tuple 相比佔用更少記憶" -"體。" - -#: ../../library/collections.rst:884 -msgid "" -"To support pickling, the named tuple class should be assigned to a variable " -"that matches *typename*." -msgstr "要支援 pickle，應將 named tuple 類別賦值給一個符合 *typename* 的變數。" - -#: ../../library/collections.rst:887 -msgid "Added support for *rename*." -msgstr "新增對於 *rename* 的支援。" - -#: ../../library/collections.rst:890 -msgid "" -"The *verbose* and *rename* parameters became :ref:`keyword-only arguments " -"`." -msgstr "" -"*verbose* 和 *rename* 參數成為\\ :ref:`僅限關鍵字引數 `。" - -#: ../../library/collections.rst:894 -msgid "Added the *module* parameter." -msgstr "新增 *module* 參數。" - -#: ../../library/collections.rst:897 -msgid "Removed the *verbose* parameter and the :attr:`!_source` attribute." -msgstr "移除 *verbose* 參數和 :attr:`!_source` 屬性。" - -#: ../../library/collections.rst:900 -msgid "" -"Added the *defaults* parameter and " -"the :attr:`~somenamedtuple._field_defaults` attribute." -msgstr "新增 *defaults* 參數和 :attr:`~somenamedtuple._field_defaults` 屬性。" - -#: ../../library/collections.rst:904 -msgid "" -">>> # Basic example\n" -">>> Point = namedtuple('Point', ['x', 'y'])\n" -">>> p = Point(11, y=22) # instantiate with positional or keyword " -"arguments\n" -">>> p[0] + p[1] # indexable like the plain tuple (11, 22)\n" -"33\n" -">>> x, y = p # unpack like a regular tuple\n" -">>> x, y\n" -"(11, 22)\n" -">>> p.x + p.y # fields also accessible by name\n" -"33\n" -">>> p # readable __repr__ with a name=value style\n" -"Point(x=11, y=22)" -msgstr "" - -#: ../../library/collections.rst:920 -msgid "" -"Named tuples are especially useful for assigning field names to result " -"tuples returned by the :mod:`csv` or :mod:`sqlite3` modules::" -msgstr "" -"Named tuple 在賦予欄位名稱於 :mod:`csv` 或 :mod:`sqlite3` 模組回傳之 tuple 時" -"相當有用： ::" - -#: ../../library/collections.rst:923 -msgid "" -"EmployeeRecord = namedtuple('EmployeeRecord', 'name, age, title, department, " -"paygrade')\n" -"\n" -"import csv\n" -"for emp in map(EmployeeRecord._make, csv.reader(open(\"employees.csv\", " -"\"rb\"))):\n" -" print(emp.name, emp.title)\n" -"\n" -"import sqlite3\n" -"conn = sqlite3.connect('/companydata')\n" -"cursor = conn.cursor()\n" -"cursor.execute('SELECT name, age, title, department, paygrade FROM " -"employees')\n" -"for emp in map(EmployeeRecord._make, cursor.fetchall()):\n" -" print(emp.name, emp.title)" -msgstr "" -"EmployeeRecord = namedtuple('EmployeeRecord', 'name, age, title, department, " -"paygrade')\n" -"\n" -"import csv\n" -"for emp in map(EmployeeRecord._make, csv.reader(open(\"employees.csv\", " -"\"rb\"))):\n" -" print(emp.name, emp.title)\n" -"\n" -"import sqlite3\n" -"conn = sqlite3.connect('/companydata')\n" -"cursor = conn.cursor()\n" -"cursor.execute('SELECT name, age, title, department, paygrade FROM " -"employees')\n" -"for emp in map(EmployeeRecord._make, cursor.fetchall()):\n" -" print(emp.name, emp.title)" - -#: ../../library/collections.rst:936 -msgid "" -"In addition to the methods inherited from tuples, named tuples support three " -"additional methods and two attributes. To prevent conflicts with field " -"names, the method and attribute names start with an underscore." -msgstr "" -"除了繼承自 tuple 的方法，named tuple 還支援三個額外的方法和兩個屬性。為了防止" -"欄位名稱有衝突，方法和屬性的名稱以底線開頭。" - -#: ../../library/collections.rst:942 -msgid "" -"Class method that makes a new instance from an existing sequence or iterable." -msgstr "從已存在的序列或可疊代物件建立一個新實例的類別方法。" - -#: ../../library/collections.rst:944 -msgid "" -">>> t = [11, 22]\n" -">>> Point._make(t)\n" -"Point(x=11, y=22)" -msgstr "" -">>> t = [11, 22]\n" -">>> Point._make(t)\n" -"Point(x=11, y=22)" - -#: ../../library/collections.rst:952 -msgid "" -"Return a new :class:`dict` which maps field names to their corresponding " -"values:" -msgstr "回傳一個將欄位名稱對映至對應值的 :class:`dict`：" - -#: ../../library/collections.rst:955 -msgid "" -">>> p = Point(x=11, y=22)\n" -">>> p._asdict()\n" -"{'x': 11, 'y': 22}" -msgstr "" -">>> p = Point(x=11, y=22)\n" -">>> p._asdict()\n" -"{'x': 11, 'y': 22}" - -#: ../../library/collections.rst:961 -msgid "Returns an :class:`OrderedDict` instead of a regular :class:`dict`." -msgstr "回傳一個 :class:`OrderedDict` 而非 :class:`dict`。" - -#: ../../library/collections.rst:964 -msgid "" -"Returns a regular :class:`dict` instead of an :class:`OrderedDict`. As of " -"Python 3.7, regular dicts are guaranteed to be ordered. If the extra " -"features of :class:`OrderedDict` are required, the suggested remediation is " -"to cast the result to the desired type: ``OrderedDict(nt._asdict())``." -msgstr "" -"回傳一個常規 :class:`dict` 而非 :class:`OrderedDict`，自從 Python 3.7 開始，" -"dict 已經保證有順序性，如果需要 :class:`OrderedDict` 所專屬的特性，推薦的解法" -"是將結果專換成所需的類型：``OrderedDict(nt._asdict())``。" - -#: ../../library/collections.rst:973 -msgid "" -"Return a new instance of the named tuple replacing specified fields with new " -"values::" -msgstr "回傳一個新的 named tuple 實例，並將指定欄位替換為新的值： ::" - -#: ../../library/collections.rst:976 -msgid "" -">>> p = Point(x=11, y=22)\n" -">>> p._replace(x=33)\n" -"Point(x=33, y=22)\n" -"\n" -">>> for partnum, record in inventory.items():\n" -"... inventory[partnum] = record._replace(price=newprices[partnum], " -"timestamp=time.now())" -msgstr "" -">>> p = Point(x=11, y=22)\n" -">>> p._replace(x=33)\n" -"Point(x=33, y=22)\n" -"\n" -">>> for partnum, record in inventory.items():\n" -"... inventory[partnum] = record._replace(price=newprices[partnum], " -"timestamp=time.now())" - -#: ../../library/collections.rst:983 -msgid "" -"Named tuples are also supported by generic function :func:`copy.replace`." -msgstr "" - -#: ../../library/collections.rst:985 -msgid "" -"Raise :exc:`TypeError` instead of :exc:`ValueError` for invalid keyword " -"arguments." -msgstr "" - -#: ../../library/collections.rst:991 -msgid "" -"Tuple of strings listing the field names. Useful for introspection and for " -"creating new named tuple types from existing named tuples." -msgstr "" -"列出 tuple 欄位名稱的字串，用於自我檢查或是從現有 named tuple 建立一個新的 " -"named tuple 型別。" - -#: ../../library/collections.rst:994 -msgid "" -">>> p._fields # view the field names\n" -"('x', 'y')\n" -"\n" -">>> Color = namedtuple('Color', 'red green blue')\n" -">>> Pixel = namedtuple('Pixel', Point._fields + Color._fields)\n" -">>> Pixel(11, 22, 128, 255, 0)\n" -"Pixel(x=11, y=22, red=128, green=255, blue=0)" -msgstr "" -">>> p._fields # 查看欄位名稱\n" -"('x', 'y')\n" -"\n" -">>> Color = namedtuple('Color', 'red green blue')\n" -">>> Pixel = namedtuple('Pixel', Point._fields + Color._fields)\n" -">>> Pixel(11, 22, 128, 255, 0)\n" -"Pixel(x=11, y=22, red=128, green=255, blue=0)" - -#: ../../library/collections.rst:1006 -msgid "Dictionary mapping field names to default values." -msgstr "將欄位名稱對映至預設值的字典。" - -#: ../../library/collections.rst:1008 -msgid "" -">>> Account = namedtuple('Account', ['type', 'balance'], defaults=[0])\n" -">>> Account._field_defaults\n" -"{'balance': 0}\n" -">>> Account('premium')\n" -"Account(type='premium', balance=0)" -msgstr "" -">>> Account = namedtuple('Account', ['type', 'balance'], defaults=[0])\n" -">>> Account._field_defaults\n" -"{'balance': 0}\n" -">>> Account('premium')\n" -"Account(type='premium', balance=0)" - -#: ../../library/collections.rst:1016 -msgid "" -"To retrieve a field whose name is stored in a string, use " -"the :func:`getattr` function:" -msgstr "要取得這個名稱存於字串的欄位，要使用 :func:`getattr` 函式：" - -#: ../../library/collections.rst:1022 -msgid "" -"To convert a dictionary to a named tuple, use the double-star-operator (as " -"described in :ref:`tut-unpacking-arguments`):" -msgstr "" -"（如\\ :ref:`tut-unpacking-arguments`\\ 所述）將一個字典轉換成 named tuple，" -"要使用 \\*\\* 雙星號運算子：" - -#: ../../library/collections.rst:1029 -msgid "" -"Since a named tuple is a regular Python class, it is easy to add or change " -"functionality with a subclass. Here is how to add a calculated field and a " -"fixed-width print format:" -msgstr "" -"因為一個 named tuple 是一個常規的 Python 類別，我們可以很容易的透過子類別來新" -"增或更改功能，以下是如何新增一個計算得到的欄位和固定寬度的輸出列印格式：" - -#: ../../library/collections.rst:1033 -msgid "" -">>> class Point(namedtuple('Point', ['x', 'y'])):\n" -"... __slots__ = ()\n" -"... @property\n" -"... def hypot(self):\n" -"... return (self.x ** 2 + self.y ** 2) ** 0.5\n" -"... def __str__(self):\n" -"... return 'Point: x=%6.3f y=%6.3f hypot=%6.3f' % (self.x, self.y, " -"self.hypot)\n" -"\n" -">>> for p in Point(3, 4), Point(14, 5/7):\n" -"... print(p)\n" -"Point: x= 3.000 y= 4.000 hypot= 5.000\n" -"Point: x=14.000 y= 0.714 hypot=14.018" -msgstr "" -">>> class Point(namedtuple('Point', ['x', 'y'])):\n" -"... __slots__ = ()\n" -"... @property\n" -"... def hypot(self):\n" -"... return (self.x ** 2 + self.y ** 2) ** 0.5\n" -"... def __str__(self):\n" -"... return 'Point: x=%6.3f y=%6.3f hypot=%6.3f' % (self.x, self.y, " -"self.hypot)\n" -"\n" -">>> for p in Point(3, 4), Point(14, 5/7):\n" -"... print(p)\n" -"Point: x= 3.000 y= 4.000 hypot= 5.000\n" -"Point: x=14.000 y= 0.714 hypot=14.018" - -#: ../../library/collections.rst:1048 -msgid "" -"The subclass shown above sets ``__slots__`` to an empty tuple. This helps " -"keep memory requirements low by preventing the creation of instance " -"dictionaries." -msgstr "" -"上面的子類別將 ``__slots__`` 設定為空 tuple，這樣一來就防止了字典實例被建立，" -"因而保持了較低的記憶體用量。" - -#: ../../library/collections.rst:1051 -msgid "" -"Subclassing is not useful for adding new, stored fields. Instead, simply " -"create a new named tuple type from the :attr:`~somenamedtuple._fields` " -"attribute:" -msgstr "" -"子類別化無法用於增加新的、已被儲存的欄位，應當透" -"過 :attr:`~somenamedtuple._fields` 屬性以建立一個新的 named tuple 來實現：" - -#: ../../library/collections.rst:1056 -msgid "" -"Docstrings can be customized by making direct assignments to the ``__doc__`` " -"fields:" -msgstr "透過直接賦值給 ``__doc__``，可以自訂說明文件字串：" - -#: ../../library/collections.rst:1065 -msgid "Property docstrings became writeable." -msgstr "文件字串屬性變成可寫入。" - -#: ../../library/collections.rst:1070 -msgid "" -"See :class:`typing.NamedTuple` for a way to add type hints for named " -"tuples. It also provides an elegant notation using the :keyword:`class` " -"keyword::" -msgstr "" -"關於為 named tuple 新增型別提示的方法，請參閱 :class:`typing.NamedTuple`，它" -"運用 :keyword:`class` 關鍵字以提供了一個簡潔的表示法： ::" - -#: ../../library/collections.rst:1074 -msgid "" -"class Component(NamedTuple):\n" -" part_number: int\n" -" weight: float\n" -" description: Optional[str] = None" -msgstr "" -"class Component(NamedTuple):\n" -" part_number: int\n" -" weight: float\n" -" description: Optional[str] = None" - -#: ../../library/collections.rst:1079 -msgid "" -"See :meth:`types.SimpleNamespace` for a mutable namespace based on an " -"underlying dictionary instead of a tuple." -msgstr "" -"關於以 dict 而非 tuple 為底層的可變命名空間，請參" -"考 :meth:`types.SimpleNamespace`。" - -#: ../../library/collections.rst:1082 -msgid "" -"The :mod:`dataclasses` module provides a decorator and functions for " -"automatically adding generated special methods to user-defined classes." -msgstr "" -":mod:`dataclasses` 模組提供了一個裝飾器和一些函式，用於自動將被生成的特殊方法" -"新增到使用者定義的類別中。" - -#: ../../library/collections.rst:1087 -msgid ":class:`OrderedDict` objects" -msgstr ":class:`OrderedDict` 物件" - -#: ../../library/collections.rst:1089 -msgid "" -"Ordered dictionaries are just like regular dictionaries but have some extra " -"capabilities relating to ordering operations. They have become less " -"important now that the built-in :class:`dict` class gained the ability to " -"remember insertion order (this new behavior became guaranteed in Python 3.7)." -msgstr "" -"Ordered dictionary（有序字典）就像常規字典一樣，但有一些與排序操作相關的額外" -"功能，但由於內建的 :class:`dict` 類別現在已經有記憶插入順序的能力（Python " -"3.7 中確保了這種新行為），它們變得不那麼重要了。" - -#: ../../library/collections.rst:1095 -msgid "Some differences from :class:`dict` still remain:" -msgstr "仍存在一些與 :class:`dict` 的不同之處：" - -#: ../../library/collections.rst:1097 -msgid "" -"The regular :class:`dict` was designed to be very good at mapping " -"operations. Tracking insertion order was secondary." -msgstr "" -"常規的 :class:`dict` 被設計成非常擅長於對映相關操作，追蹤插入的順序為次要目" -"標。" - -#: ../../library/collections.rst:1100 -msgid "" -"The :class:`OrderedDict` was designed to be good at reordering operations. " -"Space efficiency, iteration speed, and the performance of update operations " -"were secondary." -msgstr "" -":class:`OrderedDict` 則被設計成擅長於重新排序相關的操作，空間效率、疊代速度和" -"更新操作的效能則為次要設計目標。" - -#: ../../library/collections.rst:1104 -msgid "" -"The :class:`OrderedDict` algorithm can handle frequent reordering operations " -"better than :class:`dict`. As shown in the recipes below, this makes it " -"suitable for implementing various kinds of LRU caches." -msgstr "" -":class:`OrderedDict` 比起 :class:`dict` 更適合處理頻繁的重新排序操作，如在下" -"方用法中所示，這讓它適合用於多種 LRU cache 的實作中。" - -#: ../../library/collections.rst:1108 -msgid "" -"The equality operation for :class:`OrderedDict` checks for matching order." -msgstr ":class:`OrderedDict` 之相等性運算會檢查順序是否相同。" - -#: ../../library/collections.rst:1110 -msgid "" -"A regular :class:`dict` can emulate the order sensitive equality test with " -"``p == q and all(k1 == k2 for k1, k2 in zip(p, q))``." -msgstr "" -"一個一般的 :class:`dict` 可以用 ``p == q and all(k1 == k2 for k1, k2 in " -"zip(p, q))`` 來效仿有檢查順序的相等性運算。" - -#: ../../library/collections.rst:1113 -msgid "" -"The :meth:`~OrderedDict.popitem` method of :class:`OrderedDict` has a " -"different signature. It accepts an optional argument to specify which item " -"is popped." -msgstr "" -":class:`OrderedDict` 類別的 :meth:`~OrderedDict.popitem` 方法有不同的函式簽" -"名 (signature)，它接受傳入一個選擇性引數來指定要移除哪個元素。" - -#: ../../library/collections.rst:1116 -msgid "" -"A regular :class:`dict` can emulate OrderedDict's ``od.popitem(last=True)`` " -"with ``d.popitem()`` which is guaranteed to pop the rightmost (last) item." -msgstr "" -"一個一般的 :class:`dict` 可以用 ``d.popitem()`` 來效仿 OrderedDict 的 " -"``od.popitem(last=True)``，這保證會移除最右邊（最後一個）的元素。" - -#: ../../library/collections.rst:1119 -msgid "" -"A regular :class:`dict` can emulate OrderedDict's ``od.popitem(last=False)`` " -"with ``(k := next(iter(d)), d.pop(k))`` which will return and remove the " -"leftmost (first) item if it exists." -msgstr "" -"一個一般的 :class:`dict` 可以用 ``(k := next(iter(d)), d.pop(k))`` 來效仿 " -"OrderedDict 的 ``od.popitem(last=False)``，若最左邊（第一個）的元素存在，則將" -"其回傳並移除。" - -#: ../../library/collections.rst:1123 -msgid "" -":class:`OrderedDict` has a :meth:`~OrderedDict.move_to_end` method to " -"efficiently reposition an element to an endpoint." -msgstr "" -":class:`OrderedDict` 有個 :meth:`~OrderedDict.move_to_end` 方法可有效率地將一" -"個元素重新排列到任一端。" - -#: ../../library/collections.rst:1126 -msgid "" -"A regular :class:`dict` can emulate OrderedDict's ``od.move_to_end(k, " -"last=True)`` with ``d[k] = d.pop(k)`` which will move the key and its " -"associated value to the rightmost (last) position." -msgstr "" -"一個一般的 :class:`dict` 可以用 ``d[k] = d.pop(k)`` 來效仿 OrderedDict 的 " -"``od.move_to_end(k, last=True)``，這會將該鍵與其對應到的值移動至最右（最後" -"面）的位置。" - -#: ../../library/collections.rst:1130 -msgid "" -"A regular :class:`dict` does not have an efficient equivalent for " -"OrderedDict's ``od.move_to_end(k, last=False)`` which moves the key and its " -"associated value to the leftmost (first) position." -msgstr "" -"一個一般的 :class:`dict` 沒有和 OrderedDict 的 ``od.move_to_end(k, " -"last=False)`` 等價的有效方式，這是將鍵與其對應到的值移動至最左（最前面）位置" -"的方法。" - -#: ../../library/collections.rst:1134 -msgid "" -"Until Python 3.8, :class:`dict` lacked a :meth:`~object.__reversed__` method." -msgstr "" -"在 Python 3.8 之前，:class:`dict` 並沒有 :meth:`~object.__reversed__` 方法。" - -#: ../../library/collections.rst:1139 -msgid "" -"Return an instance of a :class:`dict` subclass that has methods specialized " -"for rearranging dictionary order." -msgstr "" -"回傳一個 :class:`dict` 子類別的實例，它具有專門用於重新排列字典順序的方法。" - -#: ../../library/collections.rst:1146 -msgid "" -"The :meth:`popitem` method for ordered dictionaries returns and removes a " -"(key, value) pair. The pairs are returned in :abbr:`LIFO (last-in, first-" -"out)` order if *last* is true or :abbr:`FIFO (first-in, first-out)` order if " -"false." -msgstr "" -"Ordered dictionary 的 :meth:`popitem` 方法移除並回傳一個鍵值 (key, value) " -"對。如果 *last* 為真值，則按 :abbr:`LIFO (last-in, first-out)` 後進先出的順序" -"回傳鍵值對，否則就按 :abbr:`FIFO (first-in, first-out)` 先進先出的順序回傳鍵" -"值對。" - -#: ../../library/collections.rst:1153 -msgid "" -"Move an existing *key* to either end of an ordered dictionary. The item is " -"moved to the right end if *last* is true (the default) or to the beginning " -"if *last* is false. Raises :exc:`KeyError` if the *key* does not exist:" -msgstr "" -"將現有的 *key* 移動到 ordered dictionary 的任一端。如果 *last* 為真值（此為預" -"設值）則將元素移至右端；如果 *last* 為假值則將元素移至左端。如果 *key* 不存在" -"則會引發 :exc:`KeyError`：" - -#: ../../library/collections.rst:1158 -msgid "" -">>> d = OrderedDict.fromkeys('abcde')\n" -">>> d.move_to_end('b')\n" -">>> ''.join(d)\n" -"'acdeb'\n" -">>> d.move_to_end('b', last=False)\n" -">>> ''.join(d)\n" -"'bacde'" -msgstr "" -">>> d = OrderedDict.fromkeys('abcde')\n" -">>> d.move_to_end('b')\n" -">>> ''.join(d)\n" -"'acdeb'\n" -">>> d.move_to_end('b', last=False)\n" -">>> ''.join(d)\n" -"'bacde'" - -#: ../../library/collections.rst:1170 -msgid "" -"In addition to the usual mapping methods, ordered dictionaries also support " -"reverse iteration using :func:`reversed`." -msgstr "" -"除了普通的對映方法，ordered dictionary 還支援了透過 :func:`reversed` 來做倒序" -"疊代。" - -#: ../../library/collections.rst:1175 -msgid "" -"Equality tests between :class:`OrderedDict` objects are order-sensitive and " -"are roughly equivalent to ``list(od1.items())==list(od2.items())``." -msgstr "" -":class:`OrderedDict` 物件之間的相等性運算是會檢查順序是否相同的，大致等價於 " -"``list(od1.items())==list(od2.items())``。" - -#: ../../library/collections.rst:1178 -msgid "" -"Equality tests between :class:`OrderedDict` objects and " -"other :class:`~collections.abc.Mapping` objects are order-insensitive like " -"regular dictionaries. This allows :class:`OrderedDict` objects to be " -"substituted anywhere a regular dictionary is used." -msgstr "" -":class:`OrderedDict` 物件和其他 :class:`~collections.abc.Mapping` 物件間的相" -"等性運算則像普通字典一樣不考慮順序性，這使得 :class:`OrderedDict` 可於任何字" -"典可使用的時機中被替換掉。" - -#: ../../library/collections.rst:1183 -msgid "" -"The items, keys, and values :term:`views ` " -"of :class:`OrderedDict` now support reverse iteration using :func:`reversed`." -msgstr "" -":class:`OrderedDict` 的項 (item)、鍵與值之\\ :term:`視圖 `\\ 現在可透過 :func:`reversed` 來倒序疊代。" - -#: ../../library/collections.rst:1187 -msgid "" -"With the acceptance of :pep:`468`, order is retained for keyword arguments " -"passed to the :class:`OrderedDict` constructor and its :meth:`~dict.update` " -"method." -msgstr "" -"隨著 :pep:`468` 被核可，被傳入給 :class:`OrderedDict` 建構函式與" -"其 :meth:`~dict.update` 方法的關鍵字引數之順序被保留了下來。" - -#: ../../library/collections.rst:1197 -msgid ":class:`OrderedDict` Examples and Recipes" -msgstr ":class:`OrderedDict` 範例與用法" - -#: ../../library/collections.rst:1199 -msgid "" -"It is straightforward to create an ordered dictionary variant that remembers " -"the order the keys were *last* inserted. If a new entry overwrites an " -"existing entry, the original insertion position is changed and moved to the " -"end::" -msgstr "" -"建立一個能夠記住鍵\\ *最後*\\ 插入順序的 ordered dictionary 變體很簡單。如果" -"新條目覆蓋了現有條目，則原本插入位置會被更改並移動至末端： ::" - -#: ../../library/collections.rst:1204 -msgid "" -"class LastUpdatedOrderedDict(OrderedDict):\n" -" 'Store items in the order the keys were last added'\n" -"\n" -" def __setitem__(self, key, value):\n" -" super().__setitem__(key, value)\n" -" self.move_to_end(key)" -msgstr "" - -#: ../../library/collections.rst:1211 -msgid "" -"An :class:`OrderedDict` would also be useful for implementing variants " -"of :func:`functools.lru_cache`:" -msgstr "" -":class:`OrderedDict` 在實現一個 :func:`functools.lru_cache` 的變形版本時也非" -"常有用：" - -#: ../../library/collections.rst:1214 -msgid "" -"from collections import OrderedDict\n" -"from time import time\n" -"\n" -"class TimeBoundedLRU:\n" -" \"LRU Cache that invalidates and refreshes old entries.\"\n" -"\n" -" def __init__(self, func, maxsize=128, maxage=30):\n" -" self.cache = OrderedDict() # { args : (timestamp, result)}\n" -" self.func = func\n" -" self.maxsize = maxsize\n" -" self.maxage = maxage\n" -"\n" -" def __call__(self, *args):\n" -" if args in self.cache:\n" -" self.cache.move_to_end(args)\n" -" timestamp, result = self.cache[args]\n" -" if time() - timestamp <= self.maxage:\n" -" return result\n" -" result = self.func(*args)\n" -" self.cache[args] = time(), result\n" -" if len(self.cache) > self.maxsize:\n" -" self.cache.popitem(last=False)\n" -" return result" -msgstr "" - -#: ../../library/collections.rst:1241 -msgid "" -"class MultiHitLRUCache:\n" -" \"\"\" LRU cache that defers caching a result until\n" -" it has been requested multiple times.\n" -"\n" -" To avoid flushing the LRU cache with one-time requests,\n" -" we don't cache until a request has been made more than once.\n" -"\n" -" \"\"\"\n" -"\n" -" def __init__(self, func, maxsize=128, maxrequests=4096, cache_after=1):\n" -" self.requests = OrderedDict() # { uncached_key : request_count }\n" -" self.cache = OrderedDict() # { cached_key : function_result }\n" -" self.func = func\n" -" self.maxrequests = maxrequests # max number of uncached requests\n" -" self.maxsize = maxsize # max number of stored return " -"values\n" -" self.cache_after = cache_after\n" -"\n" -" def __call__(self, *args):\n" -" if args in self.cache:\n" -" self.cache.move_to_end(args)\n" -" return self.cache[args]\n" -" result = self.func(*args)\n" -" self.requests[args] = self.requests.get(args, 0) + 1\n" -" if self.requests[args] <= self.cache_after:\n" -" self.requests.move_to_end(args)\n" -" if len(self.requests) > self.maxrequests:\n" -" self.requests.popitem(last=False)\n" -" else:\n" -" self.requests.pop(args, None)\n" -" self.cache[args] = result\n" -" if len(self.cache) > self.maxsize:\n" -" self.cache.popitem(last=False)\n" -" return result" -msgstr "" - -#: ../../library/collections.rst:1310 -msgid ":class:`UserDict` objects" -msgstr ":class:`UserDict` 物件" - -#: ../../library/collections.rst:1312 -msgid "" -"The class, :class:`UserDict` acts as a wrapper around dictionary objects. " -"The need for this class has been partially supplanted by the ability to " -"subclass directly from :class:`dict`; however, this class can be easier to " -"work with because the underlying dictionary is accessible as an attribute." -msgstr "" -":class:`UserDict` 類別是作為 dict 物件的包裝器。因為已經可以直接" -"自 :class:`dict` 建立子類別，這個類別的需求已部分被滿足，不過這個類別使用起來" -"更方便，因為被包裝的字典可以作為其屬性來存取。" - -#: ../../library/collections.rst:1320 -msgid "" -"Class that simulates a dictionary. The instance's contents are kept in a " -"regular dictionary, which is accessible via the :attr:`data` attribute " -"of :class:`UserDict` instances. If *initialdata* is provided, :attr:`data` " -"is initialized with its contents; note that a reference to *initialdata* " -"will not be kept, allowing it to be used for other purposes." -msgstr "" -"模擬字典的類別。實例的內容被存於一個字典，可透過 :class:`UserDict` " -"的 :attr:`data` 屬性來做存取。如果有提供 *initialdata*，:attr:`data` 屬性會被" -"初始化為其值；要注意指到 *initialdata* 的參照不會被保留，使其可被用於其他目" -"的。" - -#: ../../library/collections.rst:1326 -msgid "" -"In addition to supporting the methods and operations of " -"mappings, :class:`UserDict` instances provide the following attribute:" -msgstr "" -"除了支援作為對映所需的方法與操作，:class:`UserDict` 實例提供了以下屬性：" - -#: ../../library/collections.rst:1331 -msgid "" -"A real dictionary used to store the contents of the :class:`UserDict` class." -msgstr "一個真實的字典，用於儲存 :class:`UserDict` 類別的資料內容。" - -#: ../../library/collections.rst:1337 -msgid ":class:`UserList` objects" -msgstr ":class:`UserList` 物件" - -#: ../../library/collections.rst:1339 -msgid "" -"This class acts as a wrapper around list objects. It is a useful base class " -"for your own list-like classes which can inherit from them and override " -"existing methods or add new ones. In this way, one can add new behaviors to " -"lists." -msgstr "" -"此類別是 list 物件的包裝器。它是個方便的基礎類別，可繼承它並覆寫現有方法或加" -"入新方法來定義你所需的一個類似於 list 的類別。如此一來，我們可以為 list 加入" -"新的特性。" - -#: ../../library/collections.rst:1344 -msgid "" -"The need for this class has been partially supplanted by the ability to " -"subclass directly from :class:`list`; however, this class can be easier to " -"work with because the underlying list is accessible as an attribute." -msgstr "" -"因為已經可以直接自 :class:`list` 建立子類別，這個類別的需求已部分被滿足，不過" -"這個類別使用起來更方便，因為被包裝的 list 可以作為其屬性來存取。" - -#: ../../library/collections.rst:1350 -msgid "" -"Class that simulates a list. The instance's contents are kept in a regular " -"list, which is accessible via the :attr:`data` attribute " -"of :class:`UserList` instances. The instance's contents are initially set " -"to a copy of *list*, defaulting to the empty list ``[]``. *list* can be any " -"iterable, for example a real Python list or a :class:`UserList` object." -msgstr "" -"模擬 list 的類別。實例的內容被存於一個 list，可透過 :class:`UserList` " -"的 :attr:`data` 屬性來做存取。實例內容被初始化為 *list* 的複製，預設為一個空" -"的 list ``[]``。*list* 可以是任何 iterable，例如一個真實的 Python list 或是一" -"個 :class:`UserList` 物件。" - -#: ../../library/collections.rst:1356 -msgid "" -"In addition to supporting the methods and operations of mutable " -"sequences, :class:`UserList` instances provide the following attribute:" -msgstr "除了支援可變序列的方法與操作，:class:`UserList` 實例提供了以下屬性：" - -#: ../../library/collections.rst:1361 -msgid "" -"A real :class:`list` object used to store the contents of " -"the :class:`UserList` class." -msgstr "" -"一個真實的 :class:`list` 物件，用於儲存 :class:`UserList` 類別的資料內容。" - -#: ../../library/collections.rst:1364 -msgid "" -"**Subclassing requirements:** Subclasses of :class:`UserList` are expected " -"to offer a constructor which can be called with either no arguments or one " -"argument. List operations which return a new sequence attempt to create an " -"instance of the actual implementation class. To do so, it assumes that the " -"constructor can be called with a single parameter, which is a sequence " -"object used as a data source." -msgstr "" -"**子類別化的條件：**\\ :class:`UserList` 的子類別應該要提供一個不需要引數或一" -"個引數的建構函式。回傳一個新序列的 list 操作會從那些實作出來的類別建立一個實" -"例，為了達成上述目的，它假設建構函式可傳入單一參數來呼叫，該參數即是做為數據" -"來源的一個序列物件。" - -#: ../../library/collections.rst:1371 -msgid "" -"If a derived class does not wish to comply with this requirement, all of the " -"special methods supported by this class will need to be overridden; please " -"consult the sources for information about the methods which need to be " -"provided in that case." -msgstr "" -"如果希望一個自此獲得的子類別不遵從上述要求，那所有該類別支援的特殊方法則必須" -"被覆寫；請參考原始碼來理解在這情況下哪些方法是必須提供的。" - -#: ../../library/collections.rst:1377 -msgid ":class:`UserString` objects" -msgstr ":class:`UserString` 物件" - -#: ../../library/collections.rst:1379 -msgid "" -"The class, :class:`UserString` acts as a wrapper around string objects. The " -"need for this class has been partially supplanted by the ability to subclass " -"directly from :class:`str`; however, this class can be easier to work with " -"because the underlying string is accessible as an attribute." -msgstr "" -":class:`UserString` 類別是字串物件的包裝器，因為已經可以從 :class:`str` 直接" -"建立子類別，這個類別的需求已經部分被滿足，不過這個類別使用起來更方便，因為被" -"包裝的字串可以作為其屬性來存取。" - -#: ../../library/collections.rst:1387 -msgid "" -"Class that simulates a string object. The instance's content is kept in a " -"regular string object, which is accessible via the :attr:`data` attribute " -"of :class:`UserString` instances. The instance's contents are initially set " -"to a copy of *seq*. The *seq* argument can be any object which can be " -"converted into a string using the built-in :func:`str` function." -msgstr "" -"模擬字串物件的類別。實例的內容被存於一個字串物件，可透過 :class:`UserString` " -"的 :attr:`data` 屬性來做存取。實例內容被初始化為 *seq* 的複製，*seq* 引數可以" -"是任何可被內建函式 :func:`str` 轉換成字串的物件。" - -#: ../../library/collections.rst:1394 -msgid "" -"In addition to supporting the methods and operations of " -"strings, :class:`UserString` instances provide the following attribute:" -msgstr "" -"除了支援字串的方法和操作以外，:class:`UserString` 實例也提供了以下屬性：" - -#: ../../library/collections.rst:1399 -msgid "" -"A real :class:`str` object used to store the contents of " -"the :class:`UserString` class." -msgstr "" -"一個真實的 :class:`str` 物件，用來儲存 :class:`UserString` 類別的資料內容。" - -#: ../../library/collections.rst:1402 -msgid "" -"New methods ``__getnewargs__``, ``__rmod__``, ``casefold``, ``format_map``, " -"``isprintable``, and ``maketrans``." -msgstr "" -"新增方法 ``__getnewargs__``、``__rmod__``、``casefold``、``format_map``、" -"``isprintable`` 以及 ``maketrans``。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# 周 忠毅 , 2016 +# Adrian Liaw , 2018 +# Matt Wang , 2022-2024 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-10 20:44+0800\n" +"PO-Revision-Date: 2024-01-22 21:42+0800\n" +"Last-Translator: Matt Wang \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" +"X-Generator: Poedit 3.4.1\n" + +#: ../../library/collections.rst:2 +msgid ":mod:`!collections` --- Container datatypes" +msgstr ":mod:`!collections` --- 容器資料型別" + +#: ../../library/collections.rst:10 +msgid "**Source code:** :source:`Lib/collections/__init__.py`" +msgstr "**原始碼：**\\ :source:`Lib/collections/__init__.py`" + +#: ../../library/collections.rst:20 +msgid "" +"This module implements specialized container datatypes providing " +"alternatives to Python's general purpose built-in " +"containers, :class:`dict`, :class:`list`, :class:`set`, and :class:`tuple`." +msgstr "" +"這個模組實作了一些特別的容器資料型別，用來替代 Python 一般內建的容器，例" +"如 :class:`dict`\\ （字典）、:class:`list`\\ （串列）、:class:`set`\\ （集" +"合）和 :class:`tuple`\\ （元組）。" + +#: ../../library/collections.rst:25 +msgid ":func:`namedtuple`" +msgstr ":func:`namedtuple`" + +#: ../../library/collections.rst:25 +msgid "factory function for creating tuple subclasses with named fields" +msgstr "用來建立具名欄位的 tuple 子類別的工廠函式" + +#: ../../library/collections.rst:26 +msgid ":class:`deque`" +msgstr ":class:`deque`" + +#: ../../library/collections.rst:26 +msgid "list-like container with fast appends and pops on either end" +msgstr "" +"一個類似 list 的容器，可以快速的在頭尾加入 (append) 元素與移除 (pop) 元素" + +#: ../../library/collections.rst:27 +msgid ":class:`ChainMap`" +msgstr ":class:`ChainMap`" + +#: ../../library/collections.rst:27 +msgid "dict-like class for creating a single view of multiple mappings" +msgstr "一個類似 dict 的類別，用來為多個對映 (mapping) 建立單一的視圖 (view)" + +#: ../../library/collections.rst:28 +msgid ":class:`Counter`" +msgstr ":class:`Counter`" + +#: ../../library/collections.rst:28 +msgid "dict subclass for counting :term:`hashable` objects" +msgstr "dict 的子類別，用來計算\\ :term:`可雜湊 `\\ 物件的數量" + +#: ../../library/collections.rst:29 +msgid ":class:`OrderedDict`" +msgstr ":class:`OrderedDict`" + +#: ../../library/collections.rst:29 +msgid "dict subclass that remembers the order entries were added" +msgstr "dict 的子類別，會記錄物件被加入的順序" + +#: ../../library/collections.rst:30 +msgid ":class:`defaultdict`" +msgstr ":class:`defaultdict`" + +#: ../../library/collections.rst:30 +msgid "dict subclass that calls a factory function to supply missing values" +msgstr "dict 的子類別，當值不存在 dict 中時會呼叫一個提供預設值的工廠函式" + +#: ../../library/collections.rst:31 +msgid ":class:`UserDict`" +msgstr ":class:`UserDict`" + +#: ../../library/collections.rst:31 +msgid "wrapper around dictionary objects for easier dict subclassing" +msgstr "dict 物件的包裝器 (wrapper)，簡化了 dict 的子類別化過程" + +#: ../../library/collections.rst:32 +msgid ":class:`UserList`" +msgstr ":class:`UserList`" + +#: ../../library/collections.rst:32 +msgid "wrapper around list objects for easier list subclassing" +msgstr "list 物件的包裝器，簡化了 list 的子類別化過程" + +#: ../../library/collections.rst:33 +msgid ":class:`UserString`" +msgstr ":class:`UserString`" + +#: ../../library/collections.rst:33 +msgid "wrapper around string objects for easier string subclassing" +msgstr "字串物件的包裝器，簡化了字串的子類別化過程" + +#: ../../library/collections.rst:38 +msgid ":class:`ChainMap` objects" +msgstr ":class:`ChainMap` 物件" + +#: ../../library/collections.rst:42 +msgid "" +"A :class:`ChainMap` class is provided for quickly linking a number of " +"mappings so they can be treated as a single unit. It is often much faster " +"than creating a new dictionary and running multiple :meth:`~dict.update` " +"calls." +msgstr "" +":class:`ChainMap`\\ （對映鏈結）類別的目的是快速將數個對映連結在一起，讓它們" +"可以被當作一個單元來處理。它通常會比建立一個新的字典並多次呼" +"叫 :meth:`~dict.update` 來得更快。" + +#: ../../library/collections.rst:46 +msgid "" +"The class can be used to simulate nested scopes and is useful in templating." +msgstr "" +"這個類別可用於模擬巢狀作用域 (nested scopes)，且在模板化 (templating) 時能派" +"上用場。" + +#: ../../library/collections.rst:50 +msgid "" +"A :class:`ChainMap` groups multiple dicts or other mappings together to " +"create a single, updateable view. If no *maps* are specified, a single " +"empty dictionary is provided so that a new chain always has at least one " +"mapping." +msgstr "" +"一個 :class:`ChainMap` 將多個 dict 或其他對映組合在一起，建立一個獨立、可更新" +"的視圖。如果沒有指定 *maps*，預設會提供一個空字典讓每個新鏈結都至少有一個對" +"映。" + +#: ../../library/collections.rst:54 +msgid "" +"The underlying mappings are stored in a list. That list is public and can " +"be accessed or updated using the *maps* attribute. There is no other state." +msgstr "" +"底層的對映儲存於一個 list 中，這個 list 是公開的且可透過 *maps* 屬性存取或更" +"新，沒有其他狀態 (state)。" + +#: ../../library/collections.rst:57 +msgid "" +"Lookups search the underlying mappings successively until a key is found. " +"In contrast, writes, updates, and deletions only operate on the first " +"mapping." +msgstr "" +"檢索 (lookup) 陸續查詢底層對映，直到鍵被找到，然而讀取、更新和刪除就只會對第" +"一個對映操作。" + +#: ../../library/collections.rst:60 +msgid "" +"A :class:`ChainMap` incorporates the underlying mappings by reference. So, " +"if one of the underlying mappings gets updated, those changes will be " +"reflected in :class:`ChainMap`." +msgstr "" +":class:`ChainMap` 透過參照將底層對映合併，所以當一個底層對映被更新，這些改變" +"也會反映到 :class:`ChainMap`。" + +#: ../../library/collections.rst:64 +msgid "" +"All of the usual dictionary methods are supported. In addition, there is a " +"*maps* attribute, a method for creating new subcontexts, and a property for " +"accessing all but the first mapping:" +msgstr "" +"所有常見的字典方法都有支援。此外，還有一個 *maps* 屬性 (attribute)、一個建立" +"子上下文 (subcontext) 的方法、和一個能夠存取除了第一個以外其他所有對映的特性 " +"(property)：" + +#: ../../library/collections.rst:70 +msgid "" +"A user updateable list of mappings. The list is ordered from first-searched " +"to last-searched. It is the only stored state and can be modified to change " +"which mappings are searched. The list should always contain at least one " +"mapping." +msgstr "" +"一個可被更新的對映列表，這個列表是按照被搜尋的順序來排列，在 ChainMap 中它是" +"唯一被儲存的狀態，可被修改來變換搜尋順序。回傳的列表都至少包含一個對映。" + +#: ../../library/collections.rst:77 +msgid "" +"Returns a new :class:`ChainMap` containing a new map followed by all of the " +"maps in the current instance. If ``m`` is specified, it becomes the new map " +"at the front of the list of mappings; if not specified, an empty dict is " +"used, so that a call to ``d.new_child()`` is equivalent to: ``ChainMap({}, " +"*d.maps)``. If any keyword arguments are specified, they update passed map " +"or new empty dict. This method is used for creating subcontexts that can be " +"updated without altering values in any of the parent mappings." +msgstr "" +"回傳包含一個新對映的 :class:`ChainMap`， 新對映後面接著目前實例的所有現存對" +"映。如果有給定 ``m``，``m`` 會成為那個最前面的新對映；若沒有指定，則會加上一" +"個空 dict，如此一來呼叫 ``d.new_child()`` 就等同於 ``ChainMap({}, " +"*d.maps)``。這個方法用於建立子上下文，而保持父對映的不變。" + +#: ../../library/collections.rst:86 +msgid "The optional ``m`` parameter was added." +msgstr "加入可選參數 ``m``。" + +#: ../../library/collections.rst:89 +msgid "Keyword arguments support was added." +msgstr "增加了對關鍵字引數的支援。" + +#: ../../library/collections.rst:94 +msgid "" +"Property returning a new :class:`ChainMap` containing all of the maps in the " +"current instance except the first one. This is useful for skipping the " +"first map in the search. Use cases are similar to those for " +"the :keyword:`nonlocal` keyword used in :term:`nested scopes `. The use cases also parallel those for the built-in :func:`super` " +"function. A reference to ``d.parents`` is equivalent to: " +"``ChainMap(*d.maps[1:])``." +msgstr "" +"回傳一個包含除了第一個以外所有其他對映的新 :class:`ChainMap` 的特性，可用於需" +"要跳過第一個對映的搜尋。使用情境類似於在\\ :term:`巢狀作用域 `\\ 當中使用 :keyword:`nonlocal` 關鍵字，也可與內建函式 :func:`super` " +"做類比。引用 ``d.parents`` 等同於 ``ChainMap(*d.maps[1:])``。" + +#: ../../library/collections.rst:102 +msgid "" +"Note, the iteration order of a :class:`ChainMap` is determined by scanning " +"the mappings last to first::" +msgstr "注意，一個 :class:`ChainMap` 的疊代順序是透過由後往前掃描對映而定： ::" + +#: ../../library/collections.rst:105 +msgid "" +">>> baseline = {'music': 'bach', 'art': 'rembrandt'}\n" +">>> adjustments = {'art': 'van gogh', 'opera': 'carmen'}\n" +">>> list(ChainMap(adjustments, baseline))\n" +"['music', 'art', 'opera']" +msgstr "" +">>> baseline = {'music': 'bach', 'art': 'rembrandt'}\n" +">>> adjustments = {'art': 'van gogh', 'opera': 'carmen'}\n" +">>> list(ChainMap(adjustments, baseline))\n" +"['music', 'art', 'opera']" + +#: ../../library/collections.rst:110 +msgid "" +"This gives the same ordering as a series of :meth:`dict.update` calls " +"starting with the last mapping::" +msgstr "這和呼叫 :meth:`dict.update` 結果的順序一樣是從最後一個對映開始： ::" + +#: ../../library/collections.rst:113 +msgid "" +">>> combined = baseline.copy()\n" +">>> combined.update(adjustments)\n" +">>> list(combined)\n" +"['music', 'art', 'opera']" +msgstr "" +">>> combined = baseline.copy()\n" +">>> combined.update(adjustments)\n" +">>> list(combined)\n" +"['music', 'art', 'opera']" + +#: ../../library/collections.rst:118 +msgid "Added support for ``|`` and ``|=`` operators, specified in :pep:`584`." +msgstr "支援 ``|`` 和 ``|=`` 運算子，詳見 :pep:`584`。" + +#: ../../library/collections.rst:123 +msgid "" +"The `MultiContext class `_ in the Enthought `CodeTools package " +"`_ has options to support writing to " +"any mapping in the chain." +msgstr "" +"Enthought `CodeTools package `_ 中的 " +"`MultiContext class `_ 支援在鏈中選定任意對映寫入。" + +#: ../../library/collections.rst:129 +msgid "" +"Django's `Context class `_ for templating is a read-only chain of mappings. It " +"also features pushing and popping of contexts similar to " +"the :meth:`~collections.ChainMap.new_child` method and " +"the :attr:`~collections.ChainMap.parents` property." +msgstr "" +"Django 中用於模板的 `Context class `_ 是唯讀的對映鏈，也具有加入 (push) 和移除 " +"(pop) 上下文的功能，與 :meth:`~collections.ChainMap.new_child` 方法" +"和 :attr:`~collections.ChainMap.parents` 特性類似。" + +#: ../../library/collections.rst:136 +msgid "" +"The `Nested Contexts recipe `_ has options to control " +"whether writes and other mutations apply only to the first mapping or to any " +"mapping in the chain." +msgstr "" +"`Nested Contexts recipe `_ 提供了控制是否只對鏈中第一個或其他對" +"映做寫入或其他操作的選項。" + +#: ../../library/collections.rst:141 +msgid "" +"A `greatly simplified read-only version of Chainmap `_." +msgstr "" +"一個\\ `極度簡化、維讀版本的 Chainmap `_。" + +#: ../../library/collections.rst:146 +msgid ":class:`ChainMap` Examples and Recipes" +msgstr ":class:`ChainMap` 範例和用法" + +#: ../../library/collections.rst:148 +msgid "This section shows various approaches to working with chained maps." +msgstr "此章節提供了多種操作 ChainMap 的案例。" + +#: ../../library/collections.rst:151 +msgid "Example of simulating Python's internal lookup chain::" +msgstr "模擬 Python 內部檢索鏈結的例子： ::" + +#: ../../library/collections.rst:153 +msgid "" +"import builtins\n" +"pylookup = ChainMap(locals(), globals(), vars(builtins))" +msgstr "" +"import builtins\n" +"pylookup = ChainMap(locals(), globals(), vars(builtins))" + +#: ../../library/collections.rst:156 +msgid "" +"Example of letting user specified command-line arguments take precedence " +"over environment variables which in turn take precedence over default " +"values::" +msgstr "讓使用者指定的命令列引數優先於環境變數、再優先於預設值的範例： ::" + +#: ../../library/collections.rst:159 +msgid "" +"import os, argparse\n" +"\n" +"defaults = {'color': 'red', 'user': 'guest'}\n" +"\n" +"parser = argparse.ArgumentParser()\n" +"parser.add_argument('-u', '--user')\n" +"parser.add_argument('-c', '--color')\n" +"namespace = parser.parse_args()\n" +"command_line_args = {k: v for k, v in vars(namespace).items() if v is not " +"None}\n" +"\n" +"combined = ChainMap(command_line_args, os.environ, defaults)\n" +"print(combined['color'])\n" +"print(combined['user'])" +msgstr "" +"import os, argparse\n" +"\n" +"defaults = {'color': 'red', 'user': 'guest'}\n" +"\n" +"parser = argparse.ArgumentParser()\n" +"parser.add_argument('-u', '--user')\n" +"parser.add_argument('-c', '--color')\n" +"namespace = parser.parse_args()\n" +"command_line_args = {k: v for k, v in vars(namespace).items() if v is not " +"None}\n" +"\n" +"combined = ChainMap(command_line_args, os.environ, defaults)\n" +"print(combined['color'])\n" +"print(combined['user'])" + +#: ../../library/collections.rst:173 +msgid "" +"Example patterns for using the :class:`ChainMap` class to simulate nested " +"contexts::" +msgstr "用 :class:`ChainMap` 類別模擬巢狀上下文的範例模式： ::" + +#: ../../library/collections.rst:176 +msgid "" +"c = ChainMap() # Create root context\n" +"d = c.new_child() # Create nested child context\n" +"e = c.new_child() # Child of c, independent from d\n" +"e.maps[0] # Current context dictionary -- like Python's " +"locals()\n" +"e.maps[-1] # Root context -- like Python's globals()\n" +"e.parents # Enclosing context chain -- like Python's nonlocals\n" +"\n" +"d['x'] = 1 # Set value in current context\n" +"d['x'] # Get first key in the chain of contexts\n" +"del d['x'] # Delete from current context\n" +"list(d) # All nested values\n" +"k in d # Check all nested values\n" +"len(d) # Number of nested values\n" +"d.items() # All nested items\n" +"dict(d) # Flatten into a regular dictionary" +msgstr "" + +#: ../../library/collections.rst:192 +msgid "" +"The :class:`ChainMap` class only makes updates (writes and deletions) to the " +"first mapping in the chain while lookups will search the full chain. " +"However, if deep writes and deletions are desired, it is easy to make a " +"subclass that updates keys found deeper in the chain::" +msgstr "" +":class:`ChainMap` 類別只對鏈結中第一個對映來做寫入或刪除，但檢索則會掃過整個" +"鏈結。但如果需要對更深層的鍵寫入或刪除，透過定義一個子類別來實作也不困難： ::" + +#: ../../library/collections.rst:197 +msgid "" +"class DeepChainMap(ChainMap):\n" +" 'Variant of ChainMap that allows direct updates to inner scopes'\n" +"\n" +" def __setitem__(self, key, value):\n" +" for mapping in self.maps:\n" +" if key in mapping:\n" +" mapping[key] = value\n" +" return\n" +" self.maps[0][key] = value\n" +"\n" +" def __delitem__(self, key):\n" +" for mapping in self.maps:\n" +" if key in mapping:\n" +" del mapping[key]\n" +" return\n" +" raise KeyError(key)\n" +"\n" +">>> d = DeepChainMap({'zebra': 'black'}, {'elephant': 'blue'}, {'lion': " +"'yellow'})\n" +">>> d['lion'] = 'orange' # update an existing key two levels down\n" +">>> d['snake'] = 'red' # new keys get added to the topmost dict\n" +">>> del d['elephant'] # remove an existing key one level down\n" +">>> d # display result\n" +"DeepChainMap({'zebra': 'black', 'snake': 'red'}, {}, {'lion': 'orange'})" +msgstr "" + +#: ../../library/collections.rst:223 +msgid ":class:`Counter` objects" +msgstr ":class:`Counter` 物件" + +#: ../../library/collections.rst:225 +msgid "" +"A counter tool is provided to support convenient and rapid tallies. For " +"example::" +msgstr "提供一個支援方便且快速計數的計數器工具，例如： ::" + +#: ../../library/collections.rst:228 +msgid "" +">>> # Tally occurrences of words in a list\n" +">>> cnt = Counter()\n" +">>> for word in ['red', 'blue', 'red', 'green', 'blue', 'blue']:\n" +"... cnt[word] += 1\n" +"...\n" +">>> cnt\n" +"Counter({'blue': 3, 'red': 2, 'green': 1})\n" +"\n" +">>> # Find the ten most common words in Hamlet\n" +">>> import re\n" +">>> words = re.findall(r'\\w+', open('hamlet.txt').read().lower())\n" +">>> Counter(words).most_common(10)\n" +"[('the', 1143), ('and', 966), ('to', 762), ('of', 669), ('i', 631),\n" +" ('you', 554), ('a', 546), ('my', 514), ('hamlet', 471), ('in', 451)]" +msgstr "" + +#: ../../library/collections.rst:245 +msgid "" +"A :class:`Counter` is a :class:`dict` subclass for counting :term:`hashable` " +"objects. It is a collection where elements are stored as dictionary keys and " +"their counts are stored as dictionary values. Counts are allowed to be any " +"integer value including zero or negative counts. The :class:`Counter` class " +"is similar to bags or multisets in other languages." +msgstr "" +":class:`Counter` 是 :class:`dict` 的子類別，用來計算\\ :term:`可雜湊 " +"`\\ 物件的數量。它是將物件與其計數作為字典的鍵值對儲存的集合容器。" +"計數可以是包含 0 與負數的任何整數值。:class:`Counter` 類別類似其他程式語言中" +"的 bags 或 multisets。" + +#: ../../library/collections.rst:251 +msgid "" +"Elements are counted from an *iterable* or initialized from another " +"*mapping* (or counter):" +msgstr "" +"被計數的元素來自一個 *iterable* 或是被其他的 *mapping*\\ （或 Counter）初始" +"化：" + +#: ../../library/collections.rst:259 +msgid "" +"Counter objects have a dictionary interface except that they return a zero " +"count for missing items instead of raising a :exc:`KeyError`:" +msgstr "" +"Counter 物件擁有一個字典的使用介面，除了遇到 Counter 中沒有的值時會回傳計數 " +"0 取代 :exc:`KeyError` 這點不同：" + +#: ../../library/collections.rst:266 +msgid "" +"Setting a count to zero does not remove an element from a counter. Use " +"``del`` to remove it entirely:" +msgstr "" +"將一個值的計數設為 0 並不會真的從 Counter 中刪除這個元素，要使用 ``del`` 來將" +"其刪除：" + +#: ../../library/collections.rst:274 +msgid "" +"As a :class:`dict` subclass, :class:`Counter` inherited the capability to " +"remember insertion order. Math operations on *Counter* objects also " +"preserve order. Results are ordered according to when an element is first " +"encountered in the left operand and then by the order encountered in the " +"right operand." +msgstr "" +"作為 :class:`dict` 的子類別，:class:`Counter` 繼承了記憶插入順序的功能。對 " +"*Counter* 做數學運算後同樣保留順序性，其結果是依照各個元素在運算元左邊出現的" +"時間先後、再按照運算元右邊出現的時間先後來排列。" + +#: ../../library/collections.rst:280 +msgid "" +"Counter objects support additional methods beyond those available for all " +"dictionaries:" +msgstr "除了字典原本就有的方法外，Counter 物件額外支援數個新方法：" + +#: ../../library/collections.rst:285 +msgid "" +"Return an iterator over elements repeating each as many times as its count. " +"Elements are returned in the order first encountered. If an element's count " +"is less than one, :meth:`elements` will ignore it." +msgstr "" +"回傳每個元素都重複出現計算次數的 iterator（疊代器）物件，其中元素的回傳順序是" +"依照各元素首次出現的時間先後。如果元素的出現次數小於 1，:meth:`elements` 方法" +"會忽略這些元素。" + +#: ../../library/collections.rst:295 +msgid "" +"Return a list of the *n* most common elements and their counts from the most " +"common to the least. If *n* is omitted or ``None``, :meth:`most_common` " +"returns *all* elements in the counter. Elements with equal counts are " +"ordered in the order first encountered:" +msgstr "" +"回傳一個 list，包含出現最多次的 *n* 個元素及其出現次數，並按照出現次數排序。" +"如果 *n* 被省略或者為 ``None``，:meth:`most_common` 會回傳\\ *所有* counter " +"中的元素。出現次數相同的元素會按照首次出現的時間先後來排列：" + +#: ../../library/collections.rst:305 +msgid "" +"Elements are subtracted from an *iterable* or from another *mapping* (or " +"counter). Like :meth:`dict.update` but subtracts counts instead of " +"replacing them. Both inputs and outputs may be zero or negative." +msgstr "" +"減去自一個 *iterable* 或另一個\\ *對映*\\ （或 Counter）中的計數元素，行為類" +"似 :meth:`dict.update` 但是是為了減去計數而非取代其值。輸入和輸出都可以是 0 " +"或是負數。" + +#: ../../library/collections.rst:319 +msgid "Compute the sum of the counts." +msgstr "計算總計數值。" + +#: ../../library/collections.rst:327 +msgid "" +"The usual dictionary methods are available for :class:`Counter` objects " +"except for two which work differently for counters." +msgstr "" +"通常來說字典方法也可以用於 :class:`Counter` 物件，除了以下兩個作用方式與計數" +"器不同。" + +#: ../../library/collections.rst:332 +msgid "This class method is not implemented for :class:`Counter` objects." +msgstr "此類別方法沒有被實作於 :class:`Counter` 物件中。" + +#: ../../library/collections.rst:336 +msgid "" +"Elements are counted from an *iterable* or added-in from another *mapping* " +"(or counter). Like :meth:`dict.update` but adds counts instead of replacing " +"them. Also, the *iterable* is expected to be a sequence of elements, not a " +"sequence of ``(key, value)`` pairs." +msgstr "" +"加上自一個 *iterable* 計算出的計數或加上另一個 *mapping*\\ （或 Counter）中的" +"計數，行為類似 :meth:`dict.update` 但是是為了加上計數而非取代其值。另外，" +"*iterable* 需要是一串將被計算個數元素的序列，而非元素為 ``(key, value)`` 形式" +"的序列。" + +#: ../../library/collections.rst:341 +msgid "" +"Counters support rich comparison operators for equality, subset, and " +"superset relationships: ``==``, ``!=``, ``<``, ``<=``, ``>``, ``>=``. All of " +"those tests treat missing elements as having zero counts so that " +"``Counter(a=1) == Counter(a=1, b=0)`` returns true." +msgstr "" +"Counter 支援相等性、子集和超集關係的 rich comparison 運算子：``==``、``!=``、" +"``<``、``<=``、``>``、``>=``。這些檢測會將不存在的元素之計數值當作零，因此 " +"``Counter(a=1) == Counter(a=1, b=0)`` 將回傳真值。" + +#: ../../library/collections.rst:346 +msgid "Rich comparison operations were added." +msgstr "增加了 rich comparison 運算。" + +#: ../../library/collections.rst:349 +msgid "" +"In equality tests, missing elements are treated as having zero counts. " +"Formerly, ``Counter(a=3)`` and ``Counter(a=3, b=0)`` were considered " +"distinct." +msgstr "" +"在相等性運算中，不存在的元素之計數值會被當作零。在此之前，``Counter(a=3)`` " +"和 ``Counter(a=3, b=0)`` 被視為不同。" + +#: ../../library/collections.rst:354 +msgid "Common patterns for working with :class:`Counter` objects::" +msgstr "使用 :class:`Counter` 物件的常見使用模式： ::" + +#: ../../library/collections.rst:356 +msgid "" +"c.total() # total of all counts\n" +"c.clear() # reset all counts\n" +"list(c) # list unique elements\n" +"set(c) # convert to a set\n" +"dict(c) # convert to a regular dictionary\n" +"c.items() # access the (elem, cnt) pairs\n" +"Counter(dict(list_of_pairs)) # convert from a list of (elem, cnt) pairs\n" +"c.most_common()[:-n-1:-1] # n least common elements\n" +"+c # remove zero and negative counts" +msgstr "" + +#: ../../library/collections.rst:366 +msgid "" +"Several mathematical operations are provided for combining :class:`Counter` " +"objects to produce multisets (counters that have counts greater than zero). " +"Addition and subtraction combine counters by adding or subtracting the " +"counts of corresponding elements. Intersection and union return the minimum " +"and maximum of corresponding counts. Equality and inclusion compare " +"corresponding counts. Each operation can accept inputs with signed counts, " +"but the output will exclude results with counts of zero or less." +msgstr "" +"為結合多個 :class:`Counter` 物件以產生 multiset（多重集合，擁有大於 0 計數元" +"素的計數器），有提供了幾種數學操作。加法和減法是根據各個對應元素分別將 " +"Counter 加上和減去計數，交集和聯集分別回傳各個元素最小和最大計數，相等性與包" +"含性運算則會比較對應的計數。每一個操作都可以接受輸入帶有正負號的計數，但輸出" +"的 Counter 則會將擁有小於或等於 0 計數的元素剔除。" + +#: ../../library/collections.rst:374 +msgid "" +">>> c = Counter(a=3, b=1)\n" +">>> d = Counter(a=1, b=2)\n" +">>> c + d # add two counters together: c[x] + d[x]\n" +"Counter({'a': 4, 'b': 3})\n" +">>> c - d # subtract (keeping only positive counts)\n" +"Counter({'a': 2})\n" +">>> c & d # intersection: min(c[x], d[x])\n" +"Counter({'a': 1, 'b': 1})\n" +">>> c | d # union: max(c[x], d[x])\n" +"Counter({'a': 3, 'b': 2})\n" +">>> c == d # equality: c[x] == d[x]\n" +"False\n" +">>> c <= d # inclusion: c[x] <= d[x]\n" +"False" +msgstr "" + +#: ../../library/collections.rst:391 +msgid "" +"Unary addition and subtraction are shortcuts for adding an empty counter or " +"subtracting from an empty counter." +msgstr "加減法的一元運算子分別是加上空的 Counter 和從空 Counter 減去的簡寫。" + +#: ../../library/collections.rst:400 +msgid "" +"Added support for unary plus, unary minus, and in-place multiset operations." +msgstr "開始支援加減一元運算子和 multiset 的原地 (in-place) 操作。" + +#: ../../library/collections.rst:405 +msgid "" +"Counters were primarily designed to work with positive integers to represent " +"running counts; however, care was taken to not unnecessarily preclude use " +"cases needing other types or negative values. To help with those use cases, " +"this section documents the minimum range and type restrictions." +msgstr "" +"Counter 主要是被設計來操作正整數以當作使用中的計數，但為了某些會用到計數之值" +"為負數或為其他型別的案例中，Counter 也小心地被設計成不會預先排除這些特殊元" +"素。為了輔助使用於上述案例，這一小節記錄了最小範圍和型別限制。" + +#: ../../library/collections.rst:410 +msgid "" +"The :class:`Counter` class itself is a dictionary subclass with no " +"restrictions on its keys and values. The values are intended to be numbers " +"representing counts, but you *could* store anything in the value field." +msgstr "" +":class:`Counter` 類別本身是字典的子類別，且不限制其鍵與值。值被用來表示計數，" +"但實際上你\\ *可以*\\ 儲存任何值。" + +#: ../../library/collections.rst:414 +msgid "" +"The :meth:`~Counter.most_common` method requires only that the values be " +"orderable." +msgstr "使用 :meth:`~Counter.most_common` 方法的唯一條件是其值要是可被排序的。" + +#: ../../library/collections.rst:416 +msgid "" +"For in-place operations such as ``c[key] += 1``, the value type need only " +"support addition and subtraction. So fractions, floats, and decimals would " +"work and negative values are supported. The same is also true " +"for :meth:`~Counter.update` and :meth:`~Counter.subtract` which allow " +"negative and zero values for both inputs and outputs." +msgstr "" +"像是 ``c[key] += 1`` 的原地操作中，其值之型別只必須支援加減，所以分數、浮點" +"數、十進位數與其負值都可以使用。同理，:meth:`~Counter.update` " +"和 :meth:`~Counter.subtract` 也都允許 0 或負值為輸入或輸出。" + +#: ../../library/collections.rst:422 +msgid "" +"The multiset methods are designed only for use cases with positive values. " +"The inputs may be negative or zero, but only outputs with positive values " +"are created. There are no type restrictions, but the value type needs to " +"support addition, subtraction, and comparison." +msgstr "" +"Multiset 相關方法只為了處理正值而設計，其輸入允許是 0 或負值但只有正值會被輸" +"出。並無型別限制，但其值的型別須支援加、減及比較運算。" + +#: ../../library/collections.rst:427 +msgid "" +"The :meth:`~Counter.elements` method requires integer counts. It ignores " +"zero and negative counts." +msgstr ":meth:`~Counter.elements` 方法需要其計數為正值，如為 0 或負值則忽略。" + +#: ../../library/collections.rst:432 +msgid "" +"`Bag class `_ in Smalltalk." +msgstr "" +"Smalltalk 中的 `Bag class `_。" + +#: ../../library/collections.rst:435 +msgid "" +"Wikipedia entry for `Multisets `_." +msgstr "" +"維基百科上的\\ `多重集合 `_\\ 條目。" + +#: ../../library/collections.rst:437 +msgid "" +"`C++ multisets `_ tutorial with examples." +msgstr "" +"`C++ multisets `_ 教學與範例。" + +#: ../../library/collections.rst:440 +msgid "" +"For mathematical operations on multisets and their use cases, see *Knuth, " +"Donald. The Art of Computer Programming Volume II, Section 4.6.3, Exercise " +"19*." +msgstr "" +"Multiset 的數學運算及其使用時機，參考 *Knuth, Donald. The Art of Computer " +"Programming Volume II, Section 4.6.3, Exercise 19*。" + +#: ../../library/collections.rst:444 +msgid "" +"To enumerate all distinct multisets of a given size over a given set of " +"elements, see :func:`itertools.combinations_with_replacement`::" +msgstr "" +"若要根據給定的元素集合來列舉出所有不重複且擁有指定元素數量的 multiset，請" +"見 :func:`itertools.combinations_with_replacement`： ::" + +#: ../../library/collections.rst:447 +msgid "" +"map(Counter, combinations_with_replacement('ABC', 2)) # --> AA AB AC BB BC CC" +msgstr "" +"map(Counter, combinations_with_replacement('ABC', 2)) # --> AA AB AC BB BC CC" + +#: ../../library/collections.rst:451 +msgid ":class:`deque` objects" +msgstr ":class:`deque` 物件" + +#: ../../library/collections.rst:455 +msgid "" +"Returns a new deque object initialized left-to-right (using :meth:`append`) " +"with data from *iterable*. If *iterable* is not specified, the new deque is " +"empty." +msgstr "" +"回傳一個新的 deque（雙端佇列）物件，將 *iterable* 中的資料由左至右（使" +"用 :meth:`append`\\ ）加入來做初始化。如果 *iterable* 並未給定，回傳的則是一" +"個空的 deque。" + +#: ../../library/collections.rst:458 +msgid "" +"Deques are a generalization of stacks and queues (the name is pronounced " +"\"deck\" and is short for \"double-ended queue\"). Deques support thread-" +"safe, memory efficient appends and pops from either side of the deque with " +"approximately the same *O*\\ (1) performance in either direction." +msgstr "" +"Deque（發音為 \"deck\"，為 \"double-ended queue\" 的簡稱）為 stack 和 queue " +"的一般化。deque 支援執行緒安全 (thread-safe)，且能夠有效率地節省記憶體在頭和" +"尾加入和移除元素，兩個方向的表現都大致為 *O*\\ (1) 複雜度。" + +#: ../../library/collections.rst:463 +msgid "" +"Though :class:`list` objects support similar operations, they are optimized " +"for fast fixed-length operations and incur *O*\\ (*n*) memory movement costs " +"for ``pop(0)`` and ``insert(0, v)`` operations which change both the size " +"and position of the underlying data representation." +msgstr "" +"雖然 :class:`list` 物件也支援類似操作，但 list 優化了長度固定時的操作，而會改" +"變底層資料的長度及位置的 ``pop(0)`` 和 ``insert(0, v)`` 操作，記憶體移動則為 " +"*O*\\ (*n*) 複雜度。" + +#: ../../library/collections.rst:469 +msgid "" +"If *maxlen* is not specified or is ``None``, deques may grow to an arbitrary " +"length. Otherwise, the deque is bounded to the specified maximum length. " +"Once a bounded length deque is full, when new items are added, a " +"corresponding number of items are discarded from the opposite end. Bounded " +"length deques provide functionality similar to the ``tail`` filter in Unix. " +"They are also useful for tracking transactions and other pools of data where " +"only the most recent activity is of interest." +msgstr "" +"如果 *maxlen* 沒有給定或者為 ``None``，deque 可以增長到任意長度；但若有給定的" +"話，deque 的最大長度就會被限制。一個被限制長度的 deque 一但滿了，若在一端加入" +"數個新元素，則同時會在另一端移除相同數量的元素。限定長度的 deque 提供了和 " +"Unix ``tail`` filter 類似的功能，可用於追蹤使用者在意的那些最新執行事項或數據" +"源。" + +#: ../../library/collections.rst:478 +msgid "Deque objects support the following methods:" +msgstr "Deque 物件支援以下方法：" + +#: ../../library/collections.rst:482 +msgid "Add *x* to the right side of the deque." +msgstr "將 *x* 自 deque 的右側加入。" + +#: ../../library/collections.rst:487 +msgid "Add *x* to the left side of the deque." +msgstr "將 *x* 自 deque 的左側加入。" + +#: ../../library/collections.rst:492 +msgid "Remove all elements from the deque leaving it with length 0." +msgstr "將所有元素從 deque 中移除，使其長度為 0。" + +#: ../../library/collections.rst:497 +msgid "Create a shallow copy of the deque." +msgstr "建立一個 deque 的淺複製 (shallow copy)。" + +#: ../../library/collections.rst:504 +msgid "Count the number of deque elements equal to *x*." +msgstr "計算 deque 內元素為 *x* 的個數。" + +#: ../../library/collections.rst:511 +msgid "" +"Extend the right side of the deque by appending elements from the iterable " +"argument." +msgstr "將 iterable 引數加入 deque 的右側。" + +#: ../../library/collections.rst:517 +msgid "" +"Extend the left side of the deque by appending elements from *iterable*. " +"Note, the series of left appends results in reversing the order of elements " +"in the iterable argument." +msgstr "" +"將 iterable 引數加入 deque 的左側。要注意的是，加入後的元素順序和 iterable 參" +"數是相反的。" + +#: ../../library/collections.rst:524 +msgid "" +"Return the position of *x* in the deque (at or after index *start* and " +"before index *stop*). Returns the first match or raises :exc:`ValueError` " +"if not found." +msgstr "" +"回傳 deque 中 *x* 的位置（或在索引 *start* 之後、索引 *stop* 之前的位置）。回" +"傳第一個匹配的位置，如果沒找到就引發 :exc:`ValueError`。" + +#: ../../library/collections.rst:533 +msgid "Insert *x* into the deque at position *i*." +msgstr "在 deque 位置 *i* 中插入 *x*。" + +#: ../../library/collections.rst:535 +msgid "" +"If the insertion would cause a bounded deque to grow beyond *maxlen*, " +"an :exc:`IndexError` is raised." +msgstr "" +"如果此插入操作導致 deque 超過其長度上限 *maxlen* 的話，會引" +"發 :exc:`IndexError` 例外。" + +#: ../../library/collections.rst:543 +msgid "" +"Remove and return an element from the right side of the deque. If no " +"elements are present, raises an :exc:`IndexError`." +msgstr "" +"移除並回傳 deque 的最右側元素，若本來就沒有任何元素，則會引" +"發 :exc:`IndexError`。" + +#: ../../library/collections.rst:549 +msgid "" +"Remove and return an element from the left side of the deque. If no elements " +"are present, raises an :exc:`IndexError`." +msgstr "" +"移除並回傳 deque 的最左側元素，若本來就沒有任何元素，則會引" +"發 :exc:`IndexError`。" + +#: ../../library/collections.rst:555 +msgid "" +"Remove the first occurrence of *value*. If not found, raises " +"a :exc:`ValueError`." +msgstr "移除第一個出現的 *value*，如果沒找到的話就引發一個 :exc:`ValueError`。" + +#: ../../library/collections.rst:561 +msgid "Reverse the elements of the deque in-place and then return ``None``." +msgstr "將 deque 中的元素原地 (in-place) 倒序排列並回傳 ``None``。" + +#: ../../library/collections.rst:568 +msgid "" +"Rotate the deque *n* steps to the right. If *n* is negative, rotate to the " +"left." +msgstr "將 deque 向右輪轉 *n* 步。若 *n* 為負值則向左輪轉。" + +#: ../../library/collections.rst:571 +msgid "" +"When the deque is not empty, rotating one step to the right is equivalent to " +"``d.appendleft(d.pop())``, and rotating one step to the left is equivalent " +"to ``d.append(d.popleft())``." +msgstr "" +"當 deque 不是空的，向右輪轉一步和 ``d.appendleft(d.pop())`` 有相同意義，而向" +"左輪轉亦等價於 ``d.append(d.popleft())``。" + +#: ../../library/collections.rst:576 +msgid "Deque objects also provide one read-only attribute:" +msgstr "Deque 物件也提供了一個唯讀屬性：" + +#: ../../library/collections.rst:580 +msgid "Maximum size of a deque or ``None`` if unbounded." +msgstr "Deque 的最大長度，如果不限制長度的話則為 ``None``。" + +#: ../../library/collections.rst:585 +msgid "" +"In addition to the above, deques support iteration, pickling, ``len(d)``, " +"``reversed(d)``, ``copy.copy(d)``, ``copy.deepcopy(d)``, membership testing " +"with the :keyword:`in` operator, and subscript references such as ``d[0]`` " +"to access the first element. Indexed access is *O*\\ (1) at both ends but " +"slows to *O*\\ (*n*) in the middle. For fast random access, use lists " +"instead." +msgstr "" +"除了以上使用方式，deque 亦支援了疊代、pickle、``len(d)``、``reversed(d)``、" +"``copy.copy(d)``、``copy.deepcopy(d)``、用 :keyword:`in` 運算子來作隸屬資格檢" +"測以及像是 ``d[0]`` 的標號引用來取得第一個元素。在兩端做索引存取的複雜度為 " +"*O*\\ (1) 但越靠近中間則減慢至 *O*\\ (*n*)。若想要隨機而快速的存取，使用 " +"list 會較為合適。" + +#: ../../library/collections.rst:591 +msgid "" +"Starting in version 3.5, deques support ``__add__()``, ``__mul__()``, and " +"``__imul__()``." +msgstr "" +"自從 3.5 版本起，deque 開始支援 ``__add__()``、``__mul__()`` 和 " +"``__imul__()``。" + +#: ../../library/collections.rst:594 +msgid "Example:" +msgstr "範例：" + +#: ../../library/collections.rst:596 +msgid "" +">>> from collections import deque\n" +">>> d = deque('ghi') # make a new deque with three items\n" +">>> for elem in d: # iterate over the deque's elements\n" +"... print(elem.upper())\n" +"G\n" +"H\n" +"I\n" +"\n" +">>> d.append('j') # add a new entry to the right side\n" +">>> d.appendleft('f') # add a new entry to the left side\n" +">>> d # show the representation of the deque\n" +"deque(['f', 'g', 'h', 'i', 'j'])\n" +"\n" +">>> d.pop() # return and remove the rightmost item\n" +"'j'\n" +">>> d.popleft() # return and remove the leftmost item\n" +"'f'\n" +">>> list(d) # list the contents of the deque\n" +"['g', 'h', 'i']\n" +">>> d[0] # peek at leftmost item\n" +"'g'\n" +">>> d[-1] # peek at rightmost item\n" +"'i'\n" +"\n" +">>> list(reversed(d)) # list the contents of a deque in " +"reverse\n" +"['i', 'h', 'g']\n" +">>> 'h' in d # search the deque\n" +"True\n" +">>> d.extend('jkl') # add multiple elements at once\n" +">>> d\n" +"deque(['g', 'h', 'i', 'j', 'k', 'l'])\n" +">>> d.rotate(1) # right rotation\n" +">>> d\n" +"deque(['l', 'g', 'h', 'i', 'j', 'k'])\n" +">>> d.rotate(-1) # left rotation\n" +">>> d\n" +"deque(['g', 'h', 'i', 'j', 'k', 'l'])\n" +"\n" +">>> deque(reversed(d)) # make a new deque in reverse order\n" +"deque(['l', 'k', 'j', 'i', 'h', 'g'])\n" +">>> d.clear() # empty the deque\n" +">>> d.pop() # cannot pop from an empty deque\n" +"Traceback (most recent call last):\n" +" File \"\", line 1, in -toplevel-\n" +" d.pop()\n" +"IndexError: pop from an empty deque\n" +"\n" +">>> d.extendleft('abc') # extendleft() reverses the input " +"order\n" +">>> d\n" +"deque(['c', 'b', 'a'])" +msgstr "" + +#: ../../library/collections.rst:651 +msgid ":class:`deque` Recipes" +msgstr ":class:`deque` 用法" + +#: ../../library/collections.rst:653 +msgid "This section shows various approaches to working with deques." +msgstr "這一章節提供了多種操作 deque 的案例。" + +#: ../../library/collections.rst:655 +msgid "" +"Bounded length deques provide functionality similar to the ``tail`` filter " +"in Unix::" +msgstr "被限制長度的 deque 功能類似 Unix 中的 ``tail`` filter： ::" + +#: ../../library/collections.rst:658 +msgid "" +"def tail(filename, n=10):\n" +" 'Return the last n lines of a file'\n" +" with open(filename) as f:\n" +" return deque(f, n)" +msgstr "" +"def tail(filename, n=10):\n" +" '回傳檔案的最後 n 行'\n" +" with open(filename) as f:\n" +" return deque(f, n)" + +#: ../../library/collections.rst:663 +msgid "" +"Another approach to using deques is to maintain a sequence of recently added " +"elements by appending to the right and popping to the left::" +msgstr "另一用法是透過從右邊加入、從左邊移除來維護最近加入元素的 list： ::" + +#: ../../library/collections.rst:666 +msgid "" +"def moving_average(iterable, n=3):\n" +" # moving_average([40, 30, 50, 46, 39, 44]) --> 40.0 42.0 45.0 43.0\n" +" # https://en.wikipedia.org/wiki/Moving_average\n" +" it = iter(iterable)\n" +" d = deque(itertools.islice(it, n-1))\n" +" d.appendleft(0)\n" +" s = sum(d)\n" +" for elem in it:\n" +" s += elem - d.popleft()\n" +" d.append(elem)\n" +" yield s / n" +msgstr "" + +#: ../../library/collections.rst:678 +msgid "" +"A `round-robin scheduler `_ can be implemented with input iterators stored in " +"a :class:`deque`. Values are yielded from the active iterator in position " +"zero. If that iterator is exhausted, it can be removed " +"with :meth:`~deque.popleft`; otherwise, it can be cycled back to the end " +"with the :meth:`~deque.rotate` method::" +msgstr "" +"一個\\ `輪詢調度器 `_\\ 可以透過在 :class:`deque` 中放入 iterator 來實現，值自" +"目前 iterator 的位置 0 取出，如果 iterator 已經消耗完畢就" +"用 :meth:`~deque.popleft` 將其從佇列中移除，否則利用 :meth:`~deque.rotate` 來" +"將其移至佇列尾端： ::" + +#: ../../library/collections.rst:685 +msgid "" +"def roundrobin(*iterables):\n" +" \"roundrobin('ABC', 'D', 'EF') --> A D E B F C\"\n" +" iterators = deque(map(iter, iterables))\n" +" while iterators:\n" +" try:\n" +" while True:\n" +" yield next(iterators[0])\n" +" iterators.rotate(-1)\n" +" except StopIteration:\n" +" # Remove an exhausted iterator.\n" +" iterators.popleft()" +msgstr "" +"def roundrobin(*iterables):\n" +" \"roundrobin('ABC', 'D', 'EF') --> A D E B F C\"\n" +" iterators = deque(map(iter, iterables))\n" +" while iterators:\n" +" try:\n" +" while True:\n" +" yield next(iterators[0])\n" +" iterators.rotate(-1)\n" +" except StopIteration:\n" +" # 移除耗盡的疊代器。\n" +" iterators.popleft()" + +#: ../../library/collections.rst:697 +msgid "" +"The :meth:`~deque.rotate` method provides a way to implement :class:`deque` " +"slicing and deletion. For example, a pure Python implementation of ``del " +"d[n]`` relies on the ``rotate()`` method to position elements to be popped::" +msgstr "" +":meth:`~deque.rotate` 提供了可以用來實作 :class:`deque` 切片和刪除的方法。舉" +"例來說，用純 Python 實作 ``del d[n]`` 需要用 ``rotate()`` 來定位要被移除的元" +"素： ::" + +#: ../../library/collections.rst:701 +msgid "" +"def delete_nth(d, n):\n" +" d.rotate(-n)\n" +" d.popleft()\n" +" d.rotate(n)" +msgstr "" +"def delete_nth(d, n):\n" +" d.rotate(-n)\n" +" d.popleft()\n" +" d.rotate(n)" + +#: ../../library/collections.rst:706 +msgid "" +"To implement :class:`deque` slicing, use a similar approach " +"applying :meth:`~deque.rotate` to bring a target element to the left side of " +"the deque. Remove old entries with :meth:`~deque.popleft`, add new entries " +"with :meth:`~deque.extend`, and then reverse the rotation. With minor " +"variations on that approach, it is easy to implement Forth style stack " +"manipulations such as ``dup``, ``drop``, ``swap``, ``over``, ``pick``, " +"``rot``, and ``roll``." +msgstr "" +"要實現 :class:`deque` 切片，可使用近似以下方法：使用 :meth:`~deque.rotate` 來" +"將目標元素移動到 deque 最左側，用 :meth:`~deque.popleft` 移除舊元素並" +"用 :meth:`~deque.extend` 加入新元素，最後再反向 rotate。在這個方法上做小小的" +"更動就能簡單地實現 Forth 風格的 stack 操作，例如 ``dup``、``drop``、" +"``swap``、``over``、``pick``、``rot`` 和 ``roll``。" + +#: ../../library/collections.rst:716 +msgid ":class:`defaultdict` objects" +msgstr ":class:`defaultdict` 物件" + +#: ../../library/collections.rst:720 +msgid "" +"Return a new dictionary-like object. :class:`defaultdict` is a subclass of " +"the built-in :class:`dict` class. It overrides one method and adds one " +"writable instance variable. The remaining functionality is the same as for " +"the :class:`dict` class and is not documented here." +msgstr "" +"回傳一個新的類似字典的物件。:class:`defaultdict` 是內建類別 :class:`dict` 的" +"子類別。它覆蓋掉了一個方法並添加了一個可寫入的實例變數。其餘功能" +"與 :class:`dict` 相同，此文件不再複述。" + +#: ../../library/collections.rst:725 +msgid "" +"The first argument provides the initial value for " +"the :attr:`default_factory` attribute; it defaults to ``None``. All " +"remaining arguments are treated the same as if they were passed to " +"the :class:`dict` constructor, including keyword arguments." +msgstr "" +"第一個引數為 :attr:`default_factory` 屬性提供了初始值，他被預設為 ``None``，" +"所有其他的引數（包括關鍵字引數）都會被傳遞給 :class:`dict` 的建構函式 " +"(constructor)。" + +#: ../../library/collections.rst:731 +msgid "" +":class:`defaultdict` objects support the following method in addition to the " +"standard :class:`dict` operations:" +msgstr ":class:`defaultdict` 物件支援以下 :class:`dict` 所沒有的方法：" + +#: ../../library/collections.rst:736 +msgid "" +"If the :attr:`default_factory` attribute is ``None``, this raises " +"a :exc:`KeyError` exception with the *key* as argument." +msgstr "" +"如果 :attr:`default_factory` 屬性為 ``None``，呼叫此方法會引發一個附帶引數 " +"*key* 的 :exc:`KeyError` 例外。" + +#: ../../library/collections.rst:739 +msgid "" +"If :attr:`default_factory` is not ``None``, it is called without arguments " +"to provide a default value for the given *key*, this value is inserted in " +"the dictionary for the *key*, and returned." +msgstr "" +"如果 :attr:`default_factory` 不為 ``None``，它會不帶引數地被呼叫來為給定的 " +"*key* 提供一個預設值，這個值和 *key* 被作為鍵值對來插入到字典中，並且被此方法" +"所回傳。" + +#: ../../library/collections.rst:743 +msgid "" +"If calling :attr:`default_factory` raises an exception this exception is " +"propagated unchanged." +msgstr "" +"如果呼叫 :attr:`default_factory` 時發生例外，則該例外將會保持不變地向外傳遞。" + +#: ../../library/collections.rst:746 +msgid "" +"This method is called by the :meth:`~object.__getitem__` method of " +"the :class:`dict` class when the requested key is not found; whatever it " +"returns or raises is then returned or raised by :meth:`~object.__getitem__`." +msgstr "" +"在無法找到所要求的鍵時，此方法會被 :class:`dict` 類別" +"的 :meth:`~object.__getitem__` 方法呼叫。無論此方法回傳了值還是引發了例外，都" +"會被 :meth:`~object.__getitem__` 所傳遞。" + +#: ../../library/collections.rst:750 +msgid "" +"Note that :meth:`__missing__` is *not* called for any operations " +"besides :meth:`~object.__getitem__`. This means that :meth:`~dict.get` will, " +"like normal dictionaries, return ``None`` as a default rather than " +"using :attr:`default_factory`." +msgstr "" +"注意，:meth:`__missing__` *不會*\\ 被 :meth:`~object.__getitem__` 以外的其他" +"方法呼叫，這意味著 :meth:`~dict.get` 會像一般的 dict 那樣回傳 ``None`` 做為預" +"設值，而非使用 :attr:`default_factory`。" + +#: ../../library/collections.rst:756 +msgid ":class:`defaultdict` objects support the following instance variable:" +msgstr ":class:`defaultdict` 物件支援以下實例變數：" + +#: ../../library/collections.rst:761 +msgid "" +"This attribute is used by the :meth:`~defaultdict.__missing__` method; it is " +"initialized from the first argument to the constructor, if present, or to " +"``None``, if absent." +msgstr "" +"此屬性為 :meth:`~defaultdict.__missing__` 方法所使用。如果有引數被傳入建構函式，則此屬性會" +"被初始化成第一個引數，如未提供引數則被初始化為 ``None``。" + +#: ../../library/collections.rst:765 ../../library/collections.rst:1192 +msgid "" +"Added merge (``|``) and update (``|=``) operators, specified in :pep:`584`." +msgstr "新增合併 (``|``) 和更新 (``|=``) 運算子，請見 :pep:`584`。" + +#: ../../library/collections.rst:771 +msgid ":class:`defaultdict` Examples" +msgstr ":class:`defaultdict` 範例" + +#: ../../library/collections.rst:773 +msgid "" +"Using :class:`list` as the :attr:`~defaultdict.default_factory`, it is easy " +"to group a sequence of key-value pairs into a dictionary of lists:" +msgstr "" +"使用 :class:`list` 作為 :attr:`~defaultdict.default_factory` 可以很輕鬆地將鍵" +"值對序列轉換為包含 list 之字典：" + +#: ../../library/collections.rst:784 +msgid "" +"When each key is encountered for the first time, it is not already in the " +"mapping; so an entry is automatically created using " +"the :attr:`~defaultdict.default_factory` function which returns an " +"empty :class:`list`. The :meth:`list.append` operation then attaches the " +"value to the new list. When keys are encountered again, the look-up " +"proceeds normally (returning the list for that key) and " +"the :meth:`list.append` operation adds another value to the list. This " +"technique is simpler and faster than an equivalent technique " +"using :meth:`dict.setdefault`:" +msgstr "" +"當每個鍵第一次被存取時，它還沒有存在於對映中，所以會自動呼" +"叫 :attr:`~defaultdict.default_factory` 方法來回傳一個空的 :class:`list` 以建" +"立一個條目，:meth:`list.append` 操作後續會再新增值到這個新的列表裡。當再次存" +"取該鍵時，就如普通字典般操作（回傳該鍵所對應到的 list），:meth:`list.append` " +"也會新增另一個值到 list 中。和使用與其等價的 :meth:`dict.setdefault` 相比，這" +"個技巧更加快速和簡單：" + +#: ../../library/collections.rst:799 +msgid "" +"Setting the :attr:`~defaultdict.default_factory` to :class:`int` makes " +"the :class:`defaultdict` useful for counting (like a bag or multiset in " +"other languages):" +msgstr "" +"設定 :attr:`~defaultdict.default_factory` 為 :class:`int` 使" +"得 :class:`defaultdict` 可被用於計數（類似其他語言中的 bag 或 multiset）：" + +#: ../../library/collections.rst:811 +msgid "" +"When a letter is first encountered, it is missing from the mapping, so " +"the :attr:`~defaultdict.default_factory` function calls :func:`int` to " +"supply a default count of zero. The increment operation then builds up the " +"count for each letter." +msgstr "" +"當一個字母首次被存取時，它並不存在於對映中，" +"則 :attr:`~defaultdict.default_factory` 函式會呼叫 :func:`int` 來提供一個整" +"數 0 作為預設值。後續的增加操作繼續對每個字母做計數。" + +#: ../../library/collections.rst:815 +msgid "" +"The function :func:`int` which always returns zero is just a special case of " +"constant functions. A faster and more flexible way to create constant " +"functions is to use a lambda function which can supply any constant value " +"(not just zero):" +msgstr "" +"函式 :func:`int` 總是回傳 0，這是常數函式的特殊情況。一個更快、更有彈性的方法" +"是使用 lambda 函式來提供任何常數值（不用一定要是 0）：" + +#: ../../library/collections.rst:828 +msgid "" +"Setting the :attr:`~defaultdict.default_factory` to :class:`set` makes " +"the :class:`defaultdict` useful for building a dictionary of sets:" +msgstr "" +"將 :attr:`~defaultdict.default_factory` 設為 :class:`set` " +"使 :class:`defaultdict` 可用於構建一個值為 set 的字典：" + +#: ../../library/collections.rst:841 +msgid ":func:`namedtuple` Factory Function for Tuples with Named Fields" +msgstr ":func:`namedtuple` 擁有具名欄位之 tuple 的工廠函式" + +#: ../../library/collections.rst:843 +msgid "" +"Named tuples assign meaning to each position in a tuple and allow for more " +"readable, self-documenting code. They can be used wherever regular tuples " +"are used, and they add the ability to access fields by name instead of " +"position index." +msgstr "" +"Named tuple（具名元組）賦予 tuple 中各個位置意義，使程式碼更有可讀性與自我文" +"件性。它們可以用於任何普通 tuple 可使用的場合，賦予其透過名稱（而非位置索引）" +"來存取欄位的能力。" + +#: ../../library/collections.rst:849 +msgid "" +"Returns a new tuple subclass named *typename*. The new subclass is used to " +"create tuple-like objects that have fields accessible by attribute lookup as " +"well as being indexable and iterable. Instances of the subclass also have a " +"helpful docstring (with *typename* and *field_names*) and a " +"helpful :meth:`~object.__repr__` method which lists the tuple contents in a " +"``name=value`` format." +msgstr "" +"回傳一個名為 *typename* 的新 tuple 子類別。這個新的子類別被用於建立類似 " +"tuple 的物件，可以透過屬性名稱來存取欄位，它同時也是可索引 (indexable) 和可疊" +"代的 (iterable)。子類別實例同樣有文件字串 (docstring)（有類別名稱 *typename* " +"和欄位名 *field_names*）和一個好用的 :meth:`~object.__repr__` 方法，可將 " +"tuple 內容以 ``name=value`` 格式列出。" + +#: ../../library/collections.rst:856 +msgid "" +"The *field_names* are a sequence of strings such as ``['x', 'y']``. " +"Alternatively, *field_names* can be a single string with each fieldname " +"separated by whitespace and/or commas, for example ``'x y'`` or ``'x, y'``." +msgstr "" +"*field_names* 是一個像 ``['x', 'y']`` 一樣的字串序列。*field_names* 也可以是" +"一個用空白或逗號分隔各個欄位名稱的字串，比如 ``'x y'`` 或者 ``'x, y'``。" + +#: ../../library/collections.rst:860 +msgid "" +"Any valid Python identifier may be used for a fieldname except for names " +"starting with an underscore. Valid identifiers consist of letters, digits, " +"and underscores but do not start with a digit or underscore and cannot be " +"a :mod:`keyword` such as *class*, *for*, *return*, *global*, *pass*, or " +"*raise*." +msgstr "" +"除了底線開頭以外的其他任何有效 Python 識別字 (identifier) 都可以作為欄位名" +"稱，有效識別字由字母、數字、底線所組成，但不能是數字或底線開頭，也不能是關鍵" +"詞 :mod:`keyword`，例如 *class*、*for*、*return*、*global*、*pass* 或 " +"*raise*。" + +#: ../../library/collections.rst:866 +msgid "" +"If *rename* is true, invalid fieldnames are automatically replaced with " +"positional names. For example, ``['abc', 'def', 'ghi', 'abc']`` is " +"converted to ``['abc', '_1', 'ghi', '_3']``, eliminating the keyword ``def`` " +"and the duplicate fieldname ``abc``." +msgstr "" +"如果 *rename* 為真值，無效的欄位名稱會自動被位置名稱取代。比如 ``['abc', " +"'def', 'ghi', 'abc']`` 會被轉換成 ``['abc', '_1', 'ghi', '_3']``，移除了關鍵" +"字 ``def`` 和重複欄位名 ``abc``。" + +#: ../../library/collections.rst:871 +msgid "" +"*defaults* can be ``None`` or an :term:`iterable` of default values. Since " +"fields with a default value must come after any fields without a default, " +"the *defaults* are applied to the rightmost parameters. For example, if the " +"fieldnames are ``['x', 'y', 'z']`` and the defaults are ``(1, 2)``, then " +"``x`` will be a required argument, ``y`` will default to ``1``, and ``z`` " +"will default to ``2``." +msgstr "" +"*defaults* 可以為 ``None`` 或者是一個預設值的 :term:`iterable`。因為有預設值" +"的欄位必須出現在那些沒有預設值的欄位之後，*defaults* 是被應用在右側的引數。例" +"如 fieldnames 為 ``['x', 'y', 'z']`` 且 defaults 為 ``(1, 2)``，那麼 ``x`` 就" +"必須被給定一個引數，``y`` 被預設為 ``1``，``z`` 則被預設為 ``2``。" + +#: ../../library/collections.rst:878 +msgid "" +"If *module* is defined, the :attr:`~type.__module__` attribute of the named " +"tuple is set to that value." +msgstr "" +"如果 *module* 值有被定義，named tuple 的 :attr:`~type.__module__` 屬性就被設" +"定為該值。" + +#: ../../library/collections.rst:881 +msgid "" +"Named tuple instances do not have per-instance dictionaries, so they are " +"lightweight and require no more memory than regular tuples." +msgstr "" +"Named tuple 實例中沒有字典，所以它們更加輕量，且和一般 tuple 相比佔用更少記憶" +"體。" + +#: ../../library/collections.rst:884 +msgid "" +"To support pickling, the named tuple class should be assigned to a variable " +"that matches *typename*." +msgstr "要支援 pickle，應將 named tuple 類別賦值給一個符合 *typename* 的變數。" + +#: ../../library/collections.rst:887 +msgid "Added support for *rename*." +msgstr "新增對於 *rename* 的支援。" + +#: ../../library/collections.rst:890 +msgid "" +"The *verbose* and *rename* parameters became :ref:`keyword-only arguments " +"`." +msgstr "" +"*verbose* 和 *rename* 參數成為\\ :ref:`僅限關鍵字引數 `。" + +#: ../../library/collections.rst:894 +msgid "Added the *module* parameter." +msgstr "新增 *module* 參數。" + +#: ../../library/collections.rst:897 +msgid "Removed the *verbose* parameter and the :attr:`!_source` attribute." +msgstr "移除 *verbose* 參數和 :attr:`!_source` 屬性。" + +#: ../../library/collections.rst:900 +msgid "" +"Added the *defaults* parameter and " +"the :attr:`~somenamedtuple._field_defaults` attribute." +msgstr "新增 *defaults* 參數和 :attr:`~somenamedtuple._field_defaults` 屬性。" + +#: ../../library/collections.rst:904 +msgid "" +">>> # Basic example\n" +">>> Point = namedtuple('Point', ['x', 'y'])\n" +">>> p = Point(11, y=22) # instantiate with positional or keyword " +"arguments\n" +">>> p[0] + p[1] # indexable like the plain tuple (11, 22)\n" +"33\n" +">>> x, y = p # unpack like a regular tuple\n" +">>> x, y\n" +"(11, 22)\n" +">>> p.x + p.y # fields also accessible by name\n" +"33\n" +">>> p # readable __repr__ with a name=value style\n" +"Point(x=11, y=22)" +msgstr "" + +#: ../../library/collections.rst:920 +msgid "" +"Named tuples are especially useful for assigning field names to result " +"tuples returned by the :mod:`csv` or :mod:`sqlite3` modules::" +msgstr "" +"Named tuple 在賦予欄位名稱於 :mod:`csv` 或 :mod:`sqlite3` 模組回傳之 tuple 時" +"相當有用： ::" + +#: ../../library/collections.rst:923 +msgid "" +"EmployeeRecord = namedtuple('EmployeeRecord', 'name, age, title, department, " +"paygrade')\n" +"\n" +"import csv\n" +"for emp in map(EmployeeRecord._make, csv.reader(open(\"employees.csv\", " +"\"rb\"))):\n" +" print(emp.name, emp.title)\n" +"\n" +"import sqlite3\n" +"conn = sqlite3.connect('/companydata')\n" +"cursor = conn.cursor()\n" +"cursor.execute('SELECT name, age, title, department, paygrade FROM " +"employees')\n" +"for emp in map(EmployeeRecord._make, cursor.fetchall()):\n" +" print(emp.name, emp.title)" +msgstr "" +"EmployeeRecord = namedtuple('EmployeeRecord', 'name, age, title, department, " +"paygrade')\n" +"\n" +"import csv\n" +"for emp in map(EmployeeRecord._make, csv.reader(open(\"employees.csv\", " +"\"rb\"))):\n" +" print(emp.name, emp.title)\n" +"\n" +"import sqlite3\n" +"conn = sqlite3.connect('/companydata')\n" +"cursor = conn.cursor()\n" +"cursor.execute('SELECT name, age, title, department, paygrade FROM " +"employees')\n" +"for emp in map(EmployeeRecord._make, cursor.fetchall()):\n" +" print(emp.name, emp.title)" + +#: ../../library/collections.rst:936 +msgid "" +"In addition to the methods inherited from tuples, named tuples support three " +"additional methods and two attributes. To prevent conflicts with field " +"names, the method and attribute names start with an underscore." +msgstr "" +"除了繼承自 tuple 的方法，named tuple 還支援三個額外的方法和兩個屬性。為了防止" +"欄位名稱有衝突，方法和屬性的名稱以底線開頭。" + +#: ../../library/collections.rst:942 +msgid "" +"Class method that makes a new instance from an existing sequence or iterable." +msgstr "從已存在的序列或可疊代物件建立一個新實例的類別方法。" + +#: ../../library/collections.rst:944 +msgid "" +">>> t = [11, 22]\n" +">>> Point._make(t)\n" +"Point(x=11, y=22)" +msgstr "" +">>> t = [11, 22]\n" +">>> Point._make(t)\n" +"Point(x=11, y=22)" + +#: ../../library/collections.rst:952 +msgid "" +"Return a new :class:`dict` which maps field names to their corresponding " +"values:" +msgstr "回傳一個將欄位名稱對映至對應值的 :class:`dict`：" + +#: ../../library/collections.rst:955 +msgid "" +">>> p = Point(x=11, y=22)\n" +">>> p._asdict()\n" +"{'x': 11, 'y': 22}" +msgstr "" +">>> p = Point(x=11, y=22)\n" +">>> p._asdict()\n" +"{'x': 11, 'y': 22}" + +#: ../../library/collections.rst:961 +msgid "Returns an :class:`OrderedDict` instead of a regular :class:`dict`." +msgstr "回傳一個 :class:`OrderedDict` 而非 :class:`dict`。" + +#: ../../library/collections.rst:964 +msgid "" +"Returns a regular :class:`dict` instead of an :class:`OrderedDict`. As of " +"Python 3.7, regular dicts are guaranteed to be ordered. If the extra " +"features of :class:`OrderedDict` are required, the suggested remediation is " +"to cast the result to the desired type: ``OrderedDict(nt._asdict())``." +msgstr "" +"回傳一個常規 :class:`dict` 而非 :class:`OrderedDict`，自從 Python 3.7 開始，" +"dict 已經保證有順序性，如果需要 :class:`OrderedDict` 所專屬的特性，推薦的解法" +"是將結果專換成所需的類型：``OrderedDict(nt._asdict())``。" + +#: ../../library/collections.rst:973 +msgid "" +"Return a new instance of the named tuple replacing specified fields with new " +"values::" +msgstr "回傳一個新的 named tuple 實例，並將指定欄位替換為新的值： ::" + +#: ../../library/collections.rst:976 +msgid "" +">>> p = Point(x=11, y=22)\n" +">>> p._replace(x=33)\n" +"Point(x=33, y=22)\n" +"\n" +">>> for partnum, record in inventory.items():\n" +"... inventory[partnum] = record._replace(price=newprices[partnum], " +"timestamp=time.now())" +msgstr "" +">>> p = Point(x=11, y=22)\n" +">>> p._replace(x=33)\n" +"Point(x=33, y=22)\n" +"\n" +">>> for partnum, record in inventory.items():\n" +"... inventory[partnum] = record._replace(price=newprices[partnum], " +"timestamp=time.now())" + +#: ../../library/collections.rst:983 +msgid "" +"Named tuples are also supported by generic function :func:`copy.replace`." +msgstr "" + +#: ../../library/collections.rst:985 +msgid "" +"Raise :exc:`TypeError` instead of :exc:`ValueError` for invalid keyword " +"arguments." +msgstr "" + +#: ../../library/collections.rst:991 +msgid "" +"Tuple of strings listing the field names. Useful for introspection and for " +"creating new named tuple types from existing named tuples." +msgstr "" +"列出 tuple 欄位名稱的字串，用於自我檢查或是從現有 named tuple 建立一個新的 " +"named tuple 型別。" + +#: ../../library/collections.rst:994 +msgid "" +">>> p._fields # view the field names\n" +"('x', 'y')\n" +"\n" +">>> Color = namedtuple('Color', 'red green blue')\n" +">>> Pixel = namedtuple('Pixel', Point._fields + Color._fields)\n" +">>> Pixel(11, 22, 128, 255, 0)\n" +"Pixel(x=11, y=22, red=128, green=255, blue=0)" +msgstr "" +">>> p._fields # 查看欄位名稱\n" +"('x', 'y')\n" +"\n" +">>> Color = namedtuple('Color', 'red green blue')\n" +">>> Pixel = namedtuple('Pixel', Point._fields + Color._fields)\n" +">>> Pixel(11, 22, 128, 255, 0)\n" +"Pixel(x=11, y=22, red=128, green=255, blue=0)" + +#: ../../library/collections.rst:1006 +msgid "Dictionary mapping field names to default values." +msgstr "將欄位名稱對映至預設值的字典。" + +#: ../../library/collections.rst:1008 +msgid "" +">>> Account = namedtuple('Account', ['type', 'balance'], defaults=[0])\n" +">>> Account._field_defaults\n" +"{'balance': 0}\n" +">>> Account('premium')\n" +"Account(type='premium', balance=0)" +msgstr "" +">>> Account = namedtuple('Account', ['type', 'balance'], defaults=[0])\n" +">>> Account._field_defaults\n" +"{'balance': 0}\n" +">>> Account('premium')\n" +"Account(type='premium', balance=0)" + +#: ../../library/collections.rst:1016 +msgid "" +"To retrieve a field whose name is stored in a string, use " +"the :func:`getattr` function:" +msgstr "要取得這個名稱存於字串的欄位，要使用 :func:`getattr` 函式：" + +#: ../../library/collections.rst:1022 +msgid "" +"To convert a dictionary to a named tuple, use the double-star-operator (as " +"described in :ref:`tut-unpacking-arguments`):" +msgstr "" +"（如\\ :ref:`tut-unpacking-arguments`\\ 所述）將一個字典轉換成 named tuple，" +"要使用 \\*\\* 雙星號運算子：" + +#: ../../library/collections.rst:1029 +msgid "" +"Since a named tuple is a regular Python class, it is easy to add or change " +"functionality with a subclass. Here is how to add a calculated field and a " +"fixed-width print format:" +msgstr "" +"因為一個 named tuple 是一個常規的 Python 類別，我們可以很容易的透過子類別來新" +"增或更改功能，以下是如何新增一個計算得到的欄位和固定寬度的輸出列印格式：" + +#: ../../library/collections.rst:1033 +msgid "" +">>> class Point(namedtuple('Point', ['x', 'y'])):\n" +"... __slots__ = ()\n" +"... @property\n" +"... def hypot(self):\n" +"... return (self.x ** 2 + self.y ** 2) ** 0.5\n" +"... def __str__(self):\n" +"... return 'Point: x=%6.3f y=%6.3f hypot=%6.3f' % (self.x, self.y, " +"self.hypot)\n" +"\n" +">>> for p in Point(3, 4), Point(14, 5/7):\n" +"... print(p)\n" +"Point: x= 3.000 y= 4.000 hypot= 5.000\n" +"Point: x=14.000 y= 0.714 hypot=14.018" +msgstr "" +">>> class Point(namedtuple('Point', ['x', 'y'])):\n" +"... __slots__ = ()\n" +"... @property\n" +"... def hypot(self):\n" +"... return (self.x ** 2 + self.y ** 2) ** 0.5\n" +"... def __str__(self):\n" +"... return 'Point: x=%6.3f y=%6.3f hypot=%6.3f' % (self.x, self.y, " +"self.hypot)\n" +"\n" +">>> for p in Point(3, 4), Point(14, 5/7):\n" +"... print(p)\n" +"Point: x= 3.000 y= 4.000 hypot= 5.000\n" +"Point: x=14.000 y= 0.714 hypot=14.018" + +#: ../../library/collections.rst:1048 +msgid "" +"The subclass shown above sets ``__slots__`` to an empty tuple. This helps " +"keep memory requirements low by preventing the creation of instance " +"dictionaries." +msgstr "" +"上面的子類別將 ``__slots__`` 設定為空 tuple，這樣一來就防止了字典實例被建立，" +"因而保持了較低的記憶體用量。" + +#: ../../library/collections.rst:1051 +msgid "" +"Subclassing is not useful for adding new, stored fields. Instead, simply " +"create a new named tuple type from the :attr:`~somenamedtuple._fields` " +"attribute:" +msgstr "" +"子類別化無法用於增加新的、已被儲存的欄位，應當透" +"過 :attr:`~somenamedtuple._fields` 屬性以建立一個新的 named tuple 來實現：" + +#: ../../library/collections.rst:1056 +msgid "" +"Docstrings can be customized by making direct assignments to the ``__doc__`` " +"fields:" +msgstr "透過直接賦值給 ``__doc__``，可以自訂說明文件字串：" + +#: ../../library/collections.rst:1065 +msgid "Property docstrings became writeable." +msgstr "文件字串屬性變成可寫入。" + +#: ../../library/collections.rst:1070 +msgid "" +"See :class:`typing.NamedTuple` for a way to add type hints for named " +"tuples. It also provides an elegant notation using the :keyword:`class` " +"keyword::" +msgstr "" +"關於為 named tuple 新增型別提示的方法，請參閱 :class:`typing.NamedTuple`，它" +"運用 :keyword:`class` 關鍵字以提供了一個簡潔的表示法： ::" + +#: ../../library/collections.rst:1074 +msgid "" +"class Component(NamedTuple):\n" +" part_number: int\n" +" weight: float\n" +" description: Optional[str] = None" +msgstr "" +"class Component(NamedTuple):\n" +" part_number: int\n" +" weight: float\n" +" description: Optional[str] = None" + +#: ../../library/collections.rst:1079 +msgid "" +"See :meth:`types.SimpleNamespace` for a mutable namespace based on an " +"underlying dictionary instead of a tuple." +msgstr "" +"關於以 dict 而非 tuple 為底層的可變命名空間，請參" +"考 :meth:`types.SimpleNamespace`。" + +#: ../../library/collections.rst:1082 +msgid "" +"The :mod:`dataclasses` module provides a decorator and functions for " +"automatically adding generated special methods to user-defined classes." +msgstr "" +":mod:`dataclasses` 模組提供了一個裝飾器和一些函式，用於自動將被生成的特殊方法" +"新增到使用者定義的類別中。" + +#: ../../library/collections.rst:1087 +msgid ":class:`OrderedDict` objects" +msgstr ":class:`OrderedDict` 物件" + +#: ../../library/collections.rst:1089 +msgid "" +"Ordered dictionaries are just like regular dictionaries but have some extra " +"capabilities relating to ordering operations. They have become less " +"important now that the built-in :class:`dict` class gained the ability to " +"remember insertion order (this new behavior became guaranteed in Python 3.7)." +msgstr "" +"Ordered dictionary（有序字典）就像常規字典一樣，但有一些與排序操作相關的額外" +"功能，但由於內建的 :class:`dict` 類別現在已經有記憶插入順序的能力（Python " +"3.7 中確保了這種新行為），它們變得不那麼重要了。" + +#: ../../library/collections.rst:1095 +msgid "Some differences from :class:`dict` still remain:" +msgstr "仍存在一些與 :class:`dict` 的不同之處：" + +#: ../../library/collections.rst:1097 +msgid "" +"The regular :class:`dict` was designed to be very good at mapping " +"operations. Tracking insertion order was secondary." +msgstr "" +"常規的 :class:`dict` 被設計成非常擅長於對映相關操作，追蹤插入的順序為次要目" +"標。" + +#: ../../library/collections.rst:1100 +msgid "" +"The :class:`OrderedDict` was designed to be good at reordering operations. " +"Space efficiency, iteration speed, and the performance of update operations " +"were secondary." +msgstr "" +":class:`OrderedDict` 則被設計成擅長於重新排序相關的操作，空間效率、疊代速度和" +"更新操作的效能則為次要設計目標。" + +#: ../../library/collections.rst:1104 +msgid "" +"The :class:`OrderedDict` algorithm can handle frequent reordering operations " +"better than :class:`dict`. As shown in the recipes below, this makes it " +"suitable for implementing various kinds of LRU caches." +msgstr "" +":class:`OrderedDict` 比起 :class:`dict` 更適合處理頻繁的重新排序操作，如在下" +"方用法中所示，這讓它適合用於多種 LRU cache 的實作中。" + +#: ../../library/collections.rst:1108 +msgid "" +"The equality operation for :class:`OrderedDict` checks for matching order." +msgstr ":class:`OrderedDict` 之相等性運算會檢查順序是否相同。" + +#: ../../library/collections.rst:1110 +msgid "" +"A regular :class:`dict` can emulate the order sensitive equality test with " +"``p == q and all(k1 == k2 for k1, k2 in zip(p, q))``." +msgstr "" +"一個一般的 :class:`dict` 可以用 ``p == q and all(k1 == k2 for k1, k2 in " +"zip(p, q))`` 來效仿有檢查順序的相等性運算。" + +#: ../../library/collections.rst:1113 +msgid "" +"The :meth:`~OrderedDict.popitem` method of :class:`OrderedDict` has a " +"different signature. It accepts an optional argument to specify which item " +"is popped." +msgstr "" +":class:`OrderedDict` 類別的 :meth:`~OrderedDict.popitem` 方法有不同的函式簽" +"名 (signature)，它接受傳入一個選擇性引數來指定要移除哪個元素。" + +#: ../../library/collections.rst:1116 +msgid "" +"A regular :class:`dict` can emulate OrderedDict's ``od.popitem(last=True)`` " +"with ``d.popitem()`` which is guaranteed to pop the rightmost (last) item." +msgstr "" +"一個一般的 :class:`dict` 可以用 ``d.popitem()`` 來效仿 OrderedDict 的 " +"``od.popitem(last=True)``，這保證會移除最右邊（最後一個）的元素。" + +#: ../../library/collections.rst:1119 +msgid "" +"A regular :class:`dict` can emulate OrderedDict's ``od.popitem(last=False)`` " +"with ``(k := next(iter(d)), d.pop(k))`` which will return and remove the " +"leftmost (first) item if it exists." +msgstr "" +"一個一般的 :class:`dict` 可以用 ``(k := next(iter(d)), d.pop(k))`` 來效仿 " +"OrderedDict 的 ``od.popitem(last=False)``，若最左邊（第一個）的元素存在，則將" +"其回傳並移除。" + +#: ../../library/collections.rst:1123 +msgid "" +":class:`OrderedDict` has a :meth:`~OrderedDict.move_to_end` method to " +"efficiently reposition an element to an endpoint." +msgstr "" +":class:`OrderedDict` 有個 :meth:`~OrderedDict.move_to_end` 方法可有效率地將一" +"個元素重新排列到任一端。" + +#: ../../library/collections.rst:1126 +msgid "" +"A regular :class:`dict` can emulate OrderedDict's ``od.move_to_end(k, " +"last=True)`` with ``d[k] = d.pop(k)`` which will move the key and its " +"associated value to the rightmost (last) position." +msgstr "" +"一個一般的 :class:`dict` 可以用 ``d[k] = d.pop(k)`` 來效仿 OrderedDict 的 " +"``od.move_to_end(k, last=True)``，這會將該鍵與其對應到的值移動至最右（最後" +"面）的位置。" + +#: ../../library/collections.rst:1130 +msgid "" +"A regular :class:`dict` does not have an efficient equivalent for " +"OrderedDict's ``od.move_to_end(k, last=False)`` which moves the key and its " +"associated value to the leftmost (first) position." +msgstr "" +"一個一般的 :class:`dict` 沒有和 OrderedDict 的 ``od.move_to_end(k, " +"last=False)`` 等價的有效方式，這是將鍵與其對應到的值移動至最左（最前面）位置" +"的方法。" + +#: ../../library/collections.rst:1134 +msgid "" +"Until Python 3.8, :class:`dict` lacked a :meth:`~object.__reversed__` method." +msgstr "" +"在 Python 3.8 之前，:class:`dict` 並沒有 :meth:`~object.__reversed__` 方法。" + +#: ../../library/collections.rst:1139 +msgid "" +"Return an instance of a :class:`dict` subclass that has methods specialized " +"for rearranging dictionary order." +msgstr "" +"回傳一個 :class:`dict` 子類別的實例，它具有專門用於重新排列字典順序的方法。" + +#: ../../library/collections.rst:1146 +msgid "" +"The :meth:`popitem` method for ordered dictionaries returns and removes a " +"(key, value) pair. The pairs are returned in :abbr:`LIFO (last-in, first-" +"out)` order if *last* is true or :abbr:`FIFO (first-in, first-out)` order if " +"false." +msgstr "" +"Ordered dictionary 的 :meth:`popitem` 方法移除並回傳一個鍵值 (key, value) " +"對。如果 *last* 為真值，則按 :abbr:`LIFO (last-in, first-out)` 後進先出的順序" +"回傳鍵值對，否則就按 :abbr:`FIFO (first-in, first-out)` 先進先出的順序回傳鍵" +"值對。" + +#: ../../library/collections.rst:1153 +msgid "" +"Move an existing *key* to either end of an ordered dictionary. The item is " +"moved to the right end if *last* is true (the default) or to the beginning " +"if *last* is false. Raises :exc:`KeyError` if the *key* does not exist:" +msgstr "" +"將現有的 *key* 移動到 ordered dictionary 的任一端。如果 *last* 為真值（此為預" +"設值）則將元素移至右端；如果 *last* 為假值則將元素移至左端。如果 *key* 不存在" +"則會引發 :exc:`KeyError`：" + +#: ../../library/collections.rst:1158 +msgid "" +">>> d = OrderedDict.fromkeys('abcde')\n" +">>> d.move_to_end('b')\n" +">>> ''.join(d)\n" +"'acdeb'\n" +">>> d.move_to_end('b', last=False)\n" +">>> ''.join(d)\n" +"'bacde'" +msgstr "" +">>> d = OrderedDict.fromkeys('abcde')\n" +">>> d.move_to_end('b')\n" +">>> ''.join(d)\n" +"'acdeb'\n" +">>> d.move_to_end('b', last=False)\n" +">>> ''.join(d)\n" +"'bacde'" + +#: ../../library/collections.rst:1170 +msgid "" +"In addition to the usual mapping methods, ordered dictionaries also support " +"reverse iteration using :func:`reversed`." +msgstr "" +"除了普通的對映方法，ordered dictionary 還支援了透過 :func:`reversed` 來做倒序" +"疊代。" + +#: ../../library/collections.rst:1175 +msgid "" +"Equality tests between :class:`OrderedDict` objects are order-sensitive and " +"are roughly equivalent to ``list(od1.items())==list(od2.items())``." +msgstr "" +":class:`OrderedDict` 物件之間的相等性運算是會檢查順序是否相同的，大致等價於 " +"``list(od1.items())==list(od2.items())``。" + +#: ../../library/collections.rst:1178 +msgid "" +"Equality tests between :class:`OrderedDict` objects and " +"other :class:`~collections.abc.Mapping` objects are order-insensitive like " +"regular dictionaries. This allows :class:`OrderedDict` objects to be " +"substituted anywhere a regular dictionary is used." +msgstr "" +":class:`OrderedDict` 物件和其他 :class:`~collections.abc.Mapping` 物件間的相" +"等性運算則像普通字典一樣不考慮順序性，這使得 :class:`OrderedDict` 可於任何字" +"典可使用的時機中被替換掉。" + +#: ../../library/collections.rst:1183 +msgid "" +"The items, keys, and values :term:`views ` " +"of :class:`OrderedDict` now support reverse iteration using :func:`reversed`." +msgstr "" +":class:`OrderedDict` 的項 (item)、鍵與值之\\ :term:`視圖 `\\ 現在可透過 :func:`reversed` 來倒序疊代。" + +#: ../../library/collections.rst:1187 +msgid "" +"With the acceptance of :pep:`468`, order is retained for keyword arguments " +"passed to the :class:`OrderedDict` constructor and its :meth:`~dict.update` " +"method." +msgstr "" +"隨著 :pep:`468` 被核可，被傳入給 :class:`OrderedDict` 建構函式與" +"其 :meth:`~dict.update` 方法的關鍵字引數之順序被保留了下來。" + +#: ../../library/collections.rst:1197 +msgid ":class:`OrderedDict` Examples and Recipes" +msgstr ":class:`OrderedDict` 範例與用法" + +#: ../../library/collections.rst:1199 +msgid "" +"It is straightforward to create an ordered dictionary variant that remembers " +"the order the keys were *last* inserted. If a new entry overwrites an " +"existing entry, the original insertion position is changed and moved to the " +"end::" +msgstr "" +"建立一個能夠記住鍵\\ *最後*\\ 插入順序的 ordered dictionary 變體很簡單。如果" +"新條目覆蓋了現有條目，則原本插入位置會被更改並移動至末端： ::" + +#: ../../library/collections.rst:1204 +msgid "" +"class LastUpdatedOrderedDict(OrderedDict):\n" +" 'Store items in the order the keys were last added'\n" +"\n" +" def __setitem__(self, key, value):\n" +" super().__setitem__(key, value)\n" +" self.move_to_end(key)" +msgstr "" + +#: ../../library/collections.rst:1211 +msgid "" +"An :class:`OrderedDict` would also be useful for implementing variants " +"of :func:`functools.lru_cache`:" +msgstr "" +":class:`OrderedDict` 在實現一個 :func:`functools.lru_cache` 的變形版本時也非" +"常有用：" + +#: ../../library/collections.rst:1214 +msgid "" +"from collections import OrderedDict\n" +"from time import time\n" +"\n" +"class TimeBoundedLRU:\n" +" \"LRU Cache that invalidates and refreshes old entries.\"\n" +"\n" +" def __init__(self, func, maxsize=128, maxage=30):\n" +" self.cache = OrderedDict() # { args : (timestamp, result)}\n" +" self.func = func\n" +" self.maxsize = maxsize\n" +" self.maxage = maxage\n" +"\n" +" def __call__(self, *args):\n" +" if args in self.cache:\n" +" self.cache.move_to_end(args)\n" +" timestamp, result = self.cache[args]\n" +" if time() - timestamp <= self.maxage:\n" +" return result\n" +" result = self.func(*args)\n" +" self.cache[args] = time(), result\n" +" if len(self.cache) > self.maxsize:\n" +" self.cache.popitem(last=False)\n" +" return result" +msgstr "" + +#: ../../library/collections.rst:1241 +msgid "" +"class MultiHitLRUCache:\n" +" \"\"\" LRU cache that defers caching a result until\n" +" it has been requested multiple times.\n" +"\n" +" To avoid flushing the LRU cache with one-time requests,\n" +" we don't cache until a request has been made more than once.\n" +"\n" +" \"\"\"\n" +"\n" +" def __init__(self, func, maxsize=128, maxrequests=4096, cache_after=1):\n" +" self.requests = OrderedDict() # { uncached_key : request_count }\n" +" self.cache = OrderedDict() # { cached_key : function_result }\n" +" self.func = func\n" +" self.maxrequests = maxrequests # max number of uncached requests\n" +" self.maxsize = maxsize # max number of stored return " +"values\n" +" self.cache_after = cache_after\n" +"\n" +" def __call__(self, *args):\n" +" if args in self.cache:\n" +" self.cache.move_to_end(args)\n" +" return self.cache[args]\n" +" result = self.func(*args)\n" +" self.requests[args] = self.requests.get(args, 0) + 1\n" +" if self.requests[args] <= self.cache_after:\n" +" self.requests.move_to_end(args)\n" +" if len(self.requests) > self.maxrequests:\n" +" self.requests.popitem(last=False)\n" +" else:\n" +" self.requests.pop(args, None)\n" +" self.cache[args] = result\n" +" if len(self.cache) > self.maxsize:\n" +" self.cache.popitem(last=False)\n" +" return result" +msgstr "" + +#: ../../library/collections.rst:1310 +msgid ":class:`UserDict` objects" +msgstr ":class:`UserDict` 物件" + +#: ../../library/collections.rst:1312 +msgid "" +"The class, :class:`UserDict` acts as a wrapper around dictionary objects. " +"The need for this class has been partially supplanted by the ability to " +"subclass directly from :class:`dict`; however, this class can be easier to " +"work with because the underlying dictionary is accessible as an attribute." +msgstr "" +":class:`UserDict` 類別是作為 dict 物件的包裝器。因為已經可以直接" +"自 :class:`dict` 建立子類別，這個類別的需求已部分被滿足，不過這個類別使用起來" +"更方便，因為被包裝的字典可以作為其屬性來存取。" + +#: ../../library/collections.rst:1320 +msgid "" +"Class that simulates a dictionary. The instance's contents are kept in a " +"regular dictionary, which is accessible via the :attr:`data` attribute " +"of :class:`UserDict` instances. If *initialdata* is provided, :attr:`data` " +"is initialized with its contents; note that a reference to *initialdata* " +"will not be kept, allowing it to be used for other purposes." +msgstr "" +"模擬字典的類別。實例的內容被存於一個字典，可透過 :class:`UserDict` " +"的 :attr:`data` 屬性來做存取。如果有提供 *initialdata*，:attr:`data` 屬性會被" +"初始化為其值；要注意指到 *initialdata* 的參照不會被保留，使其可被用於其他目" +"的。" + +#: ../../library/collections.rst:1326 +msgid "" +"In addition to supporting the methods and operations of " +"mappings, :class:`UserDict` instances provide the following attribute:" +msgstr "" +"除了支援作為對映所需的方法與操作，:class:`UserDict` 實例提供了以下屬性：" + +#: ../../library/collections.rst:1331 +msgid "" +"A real dictionary used to store the contents of the :class:`UserDict` class." +msgstr "一個真實的字典，用於儲存 :class:`UserDict` 類別的資料內容。" + +#: ../../library/collections.rst:1337 +msgid ":class:`UserList` objects" +msgstr ":class:`UserList` 物件" + +#: ../../library/collections.rst:1339 +msgid "" +"This class acts as a wrapper around list objects. It is a useful base class " +"for your own list-like classes which can inherit from them and override " +"existing methods or add new ones. In this way, one can add new behaviors to " +"lists." +msgstr "" +"此類別是 list 物件的包裝器。它是個方便的基礎類別，可繼承它並覆寫現有方法或加" +"入新方法來定義你所需的一個類似於 list 的類別。如此一來，我們可以為 list 加入" +"新的特性。" + +#: ../../library/collections.rst:1344 +msgid "" +"The need for this class has been partially supplanted by the ability to " +"subclass directly from :class:`list`; however, this class can be easier to " +"work with because the underlying list is accessible as an attribute." +msgstr "" +"因為已經可以直接自 :class:`list` 建立子類別，這個類別的需求已部分被滿足，不過" +"這個類別使用起來更方便，因為被包裝的 list 可以作為其屬性來存取。" + +#: ../../library/collections.rst:1350 +msgid "" +"Class that simulates a list. The instance's contents are kept in a regular " +"list, which is accessible via the :attr:`data` attribute " +"of :class:`UserList` instances. The instance's contents are initially set " +"to a copy of *list*, defaulting to the empty list ``[]``. *list* can be any " +"iterable, for example a real Python list or a :class:`UserList` object." +msgstr "" +"模擬 list 的類別。實例的內容被存於一個 list，可透過 :class:`UserList` " +"的 :attr:`data` 屬性來做存取。實例內容被初始化為 *list* 的複製，預設為一個空" +"的 list ``[]``。*list* 可以是任何 iterable，例如一個真實的 Python list 或是一" +"個 :class:`UserList` 物件。" + +#: ../../library/collections.rst:1356 +msgid "" +"In addition to supporting the methods and operations of mutable " +"sequences, :class:`UserList` instances provide the following attribute:" +msgstr "除了支援可變序列的方法與操作，:class:`UserList` 實例提供了以下屬性：" + +#: ../../library/collections.rst:1361 +msgid "" +"A real :class:`list` object used to store the contents of " +"the :class:`UserList` class." +msgstr "" +"一個真實的 :class:`list` 物件，用於儲存 :class:`UserList` 類別的資料內容。" + +#: ../../library/collections.rst:1364 +msgid "" +"**Subclassing requirements:** Subclasses of :class:`UserList` are expected " +"to offer a constructor which can be called with either no arguments or one " +"argument. List operations which return a new sequence attempt to create an " +"instance of the actual implementation class. To do so, it assumes that the " +"constructor can be called with a single parameter, which is a sequence " +"object used as a data source." +msgstr "" +"**子類別化的條件：**\\ :class:`UserList` 的子類別應該要提供一個不需要引數或一" +"個引數的建構函式。回傳一個新序列的 list 操作會從那些實作出來的類別建立一個實" +"例，為了達成上述目的，它假設建構函式可傳入單一參數來呼叫，該參數即是做為數據" +"來源的一個序列物件。" + +#: ../../library/collections.rst:1371 +msgid "" +"If a derived class does not wish to comply with this requirement, all of the " +"special methods supported by this class will need to be overridden; please " +"consult the sources for information about the methods which need to be " +"provided in that case." +msgstr "" +"如果希望一個自此獲得的子類別不遵從上述要求，那所有該類別支援的特殊方法則必須" +"被覆寫；請參考原始碼來理解在這情況下哪些方法是必須提供的。" + +#: ../../library/collections.rst:1377 +msgid ":class:`UserString` objects" +msgstr ":class:`UserString` 物件" + +#: ../../library/collections.rst:1379 +msgid "" +"The class, :class:`UserString` acts as a wrapper around string objects. The " +"need for this class has been partially supplanted by the ability to subclass " +"directly from :class:`str`; however, this class can be easier to work with " +"because the underlying string is accessible as an attribute." +msgstr "" +":class:`UserString` 類別是字串物件的包裝器，因為已經可以從 :class:`str` 直接" +"建立子類別，這個類別的需求已經部分被滿足，不過這個類別使用起來更方便，因為被" +"包裝的字串可以作為其屬性來存取。" + +#: ../../library/collections.rst:1387 +msgid "" +"Class that simulates a string object. The instance's content is kept in a " +"regular string object, which is accessible via the :attr:`data` attribute " +"of :class:`UserString` instances. The instance's contents are initially set " +"to a copy of *seq*. The *seq* argument can be any object which can be " +"converted into a string using the built-in :func:`str` function." +msgstr "" +"模擬字串物件的類別。實例的內容被存於一個字串物件，可透過 :class:`UserString` " +"的 :attr:`data` 屬性來做存取。實例內容被初始化為 *seq* 的複製，*seq* 引數可以" +"是任何可被內建函式 :func:`str` 轉換成字串的物件。" + +#: ../../library/collections.rst:1394 +msgid "" +"In addition to supporting the methods and operations of " +"strings, :class:`UserString` instances provide the following attribute:" +msgstr "" +"除了支援字串的方法和操作以外，:class:`UserString` 實例也提供了以下屬性：" + +#: ../../library/collections.rst:1399 +msgid "" +"A real :class:`str` object used to store the contents of " +"the :class:`UserString` class." +msgstr "" +"一個真實的 :class:`str` 物件，用來儲存 :class:`UserString` 類別的資料內容。" + +#: ../../library/collections.rst:1402 +msgid "" +"New methods ``__getnewargs__``, ``__rmod__``, ``casefold``, ``format_map``, " +"``isprintable``, and ``maketrans``." +msgstr "" +"新增方法 ``__getnewargs__``、``__rmod__``、``casefold``、``format_map``、" +"``isprintable`` 以及 ``maketrans``。" diff --git a/library/colorsys.po b/library/colorsys.po index 2259120e20..506e4e3ec8 100644 --- a/library/colorsys.po +++ b/library/colorsys.po @@ -1,100 +1,100 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Liang-Bo Wang , 2016 -# Matt Wang , 2022 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-09-03 11:11+0800\n" -"PO-Revision-Date: 2022-02-15 20:58+0800\n" -"Last-Translator: Matt Wang \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" -"X-Generator: Poedit 3.0.1\n" - -#: ../../library/colorsys.rst:2 -msgid ":mod:`!colorsys` --- Conversions between color systems" -msgstr ":mod:`!colorsys` --- 顏色系統間的轉換" - -#: ../../library/colorsys.rst:9 -msgid "**Source code:** :source:`Lib/colorsys.py`" -msgstr "**原始碼：**\\ :source:`Lib/colorsys.py`" - -#: ../../library/colorsys.rst:13 -msgid "" -"The :mod:`colorsys` module defines bidirectional conversions of color values " -"between colors expressed in the RGB (Red Green Blue) color space used in " -"computer monitors and three other coordinate systems: YIQ, HLS (Hue " -"Lightness Saturation) and HSV (Hue Saturation Value). Coordinates in all of " -"these color spaces are floating-point values. In the YIQ space, the Y " -"coordinate is between 0 and 1, but the I and Q coordinates can be positive " -"or negative. In all other spaces, the coordinates are all between 0 and 1." -msgstr "" -":mod:`colorsys` 模組 (module) 定義了電腦顯示器所用的 RGB （紅綠藍）色彩空間與" -"三種其他色彩座標系統：YIQ、HLS (色相、亮度、飽和度) 和 HSV (色相、 飽和度、 " -"明度) 所表示的顏色值之間的雙向轉換。所有這些色彩空間的座標都使用浮點數值 " -"(floating-point) 來表示。在 YIQ 空間中，Y 座標值為 0 和 1 之間，而 I 和 Q 座" -"標均可以為正數或負數。在所有其他空間中，座標值均為 0 和 1 之間。" - -#: ../../library/colorsys.rst:23 -msgid "" -"More information about color spaces can be found at https://poynton.ca/" -"ColorFAQ.html and https://www.cambridgeincolour.com/tutorials/color-spaces." -"htm." -msgstr "" -"有關色彩空間的更多資訊請見 https://poynton.ca/ColorFAQ.html 和 https://www." -"cambridgeincolour.com/tutorials/color-spaces.htm。" - -#: ../../library/colorsys.rst:27 -msgid "The :mod:`colorsys` module defines the following functions:" -msgstr ":mod:`colorsys` 模組定義了以下函式：" - -#: ../../library/colorsys.rst:32 -msgid "Convert the color from RGB coordinates to YIQ coordinates." -msgstr "將顏色自 RGB 座標轉換至 YIQ 座標。" - -#: ../../library/colorsys.rst:37 -msgid "Convert the color from YIQ coordinates to RGB coordinates." -msgstr "將顏色自 YIQ 座標轉換至 RGB 座標。" - -#: ../../library/colorsys.rst:42 -msgid "Convert the color from RGB coordinates to HLS coordinates." -msgstr "將顏色自 RGB 座標轉換至 HLS 座標。" - -#: ../../library/colorsys.rst:47 -msgid "Convert the color from HLS coordinates to RGB coordinates." -msgstr "將顏色自 HLS 座標轉換至 RGB 座標。" - -#: ../../library/colorsys.rst:52 -msgid "Convert the color from RGB coordinates to HSV coordinates." -msgstr "將顏色自 RGB 座標轉換至 HSV 座標。" - -#: ../../library/colorsys.rst:57 -msgid "Convert the color from HSV coordinates to RGB coordinates." -msgstr "將顏色自 HSV 座標轉換至 RGB 座標。" - -#: ../../library/colorsys.rst:59 -msgid "Example::" -msgstr "範例： ::" - -#: ../../library/colorsys.rst:61 -msgid "" -">>> import colorsys\n" -">>> colorsys.rgb_to_hsv(0.2, 0.4, 0.4)\n" -"(0.5, 0.5, 0.4)\n" -">>> colorsys.hsv_to_rgb(0.5, 0.5, 0.4)\n" -"(0.2, 0.4, 0.4)" -msgstr "" -">>> import colorsys\n" -">>> colorsys.rgb_to_hsv(0.2, 0.4, 0.4)\n" -"(0.5, 0.5, 0.4)\n" -">>> colorsys.hsv_to_rgb(0.5, 0.5, 0.4)\n" -"(0.2, 0.4, 0.4)" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Liang-Bo Wang , 2016 +# Matt Wang , 2022 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-09-03 11:11+0800\n" +"PO-Revision-Date: 2022-02-15 20:58+0800\n" +"Last-Translator: Matt Wang \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" +"X-Generator: Poedit 3.0.1\n" + +#: ../../library/colorsys.rst:2 +msgid ":mod:`!colorsys` --- Conversions between color systems" +msgstr ":mod:`!colorsys` --- 顏色系統間的轉換" + +#: ../../library/colorsys.rst:9 +msgid "**Source code:** :source:`Lib/colorsys.py`" +msgstr "**原始碼：**\\ :source:`Lib/colorsys.py`" + +#: ../../library/colorsys.rst:13 +msgid "" +"The :mod:`colorsys` module defines bidirectional conversions of color values " +"between colors expressed in the RGB (Red Green Blue) color space used in " +"computer monitors and three other coordinate systems: YIQ, HLS (Hue " +"Lightness Saturation) and HSV (Hue Saturation Value). Coordinates in all of " +"these color spaces are floating-point values. In the YIQ space, the Y " +"coordinate is between 0 and 1, but the I and Q coordinates can be positive " +"or negative. In all other spaces, the coordinates are all between 0 and 1." +msgstr "" +":mod:`colorsys` 模組 (module) 定義了電腦顯示器所用的 RGB （紅綠藍）色彩空間與" +"三種其他色彩座標系統：YIQ、HLS (色相、亮度、飽和度) 和 HSV (色相、 飽和度、 " +"明度) 所表示的顏色值之間的雙向轉換。所有這些色彩空間的座標都使用浮點數值 " +"(floating-point) 來表示。在 YIQ 空間中，Y 座標值為 0 和 1 之間，而 I 和 Q 座" +"標均可以為正數或負數。在所有其他空間中，座標值均為 0 和 1 之間。" + +#: ../../library/colorsys.rst:23 +msgid "" +"More information about color spaces can be found at https://poynton.ca/" +"ColorFAQ.html and https://www.cambridgeincolour.com/tutorials/color-spaces." +"htm." +msgstr "" +"有關色彩空間的更多資訊請見 https://poynton.ca/ColorFAQ.html 和 https://www." +"cambridgeincolour.com/tutorials/color-spaces.htm。" + +#: ../../library/colorsys.rst:27 +msgid "The :mod:`colorsys` module defines the following functions:" +msgstr ":mod:`colorsys` 模組定義了以下函式：" + +#: ../../library/colorsys.rst:32 +msgid "Convert the color from RGB coordinates to YIQ coordinates." +msgstr "將顏色自 RGB 座標轉換至 YIQ 座標。" + +#: ../../library/colorsys.rst:37 +msgid "Convert the color from YIQ coordinates to RGB coordinates." +msgstr "將顏色自 YIQ 座標轉換至 RGB 座標。" + +#: ../../library/colorsys.rst:42 +msgid "Convert the color from RGB coordinates to HLS coordinates." +msgstr "將顏色自 RGB 座標轉換至 HLS 座標。" + +#: ../../library/colorsys.rst:47 +msgid "Convert the color from HLS coordinates to RGB coordinates." +msgstr "將顏色自 HLS 座標轉換至 RGB 座標。" + +#: ../../library/colorsys.rst:52 +msgid "Convert the color from RGB coordinates to HSV coordinates." +msgstr "將顏色自 RGB 座標轉換至 HSV 座標。" + +#: ../../library/colorsys.rst:57 +msgid "Convert the color from HSV coordinates to RGB coordinates." +msgstr "將顏色自 HSV 座標轉換至 RGB 座標。" + +#: ../../library/colorsys.rst:59 +msgid "Example::" +msgstr "範例： ::" + +#: ../../library/colorsys.rst:61 +msgid "" +">>> import colorsys\n" +">>> colorsys.rgb_to_hsv(0.2, 0.4, 0.4)\n" +"(0.5, 0.5, 0.4)\n" +">>> colorsys.hsv_to_rgb(0.5, 0.5, 0.4)\n" +"(0.2, 0.4, 0.4)" +msgstr "" +">>> import colorsys\n" +">>> colorsys.rgb_to_hsv(0.2, 0.4, 0.4)\n" +"(0.5, 0.5, 0.4)\n" +">>> colorsys.hsv_to_rgb(0.5, 0.5, 0.4)\n" +"(0.2, 0.4, 0.4)" diff --git a/library/compileall.po b/library/compileall.po index 221b9ee0d5..64bcef54de 100644 --- a/library/compileall.po +++ b/library/compileall.po @@ -1,437 +1,437 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-06-27 07:36+0000\n" -"PO-Revision-Date: 2018-05-23 14:41+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/compileall.rst:2 -msgid ":mod:`!compileall` --- Byte-compile Python libraries" -msgstr ":mod:`!compileall` --- 位元組編譯 Python 函式庫" - -#: ../../library/compileall.rst:7 -msgid "**Source code:** :source:`Lib/compileall.py`" -msgstr "**原始碼：**\\ :source:`Lib/compileall.py`" - -#: ../../library/compileall.rst:11 -msgid "" -"This module provides some utility functions to support installing Python " -"libraries. These functions compile Python source files in a directory tree. " -"This module can be used to create the cached byte-code files at library " -"installation time, which makes them available for use even by users who " -"don't have write permission to the library directories." -msgstr "" - -#: ../../includes/wasm-notavail.rst:3 -msgid "Availability" -msgstr "可用性" - -#: ../../includes/wasm-notavail.rst:5 -msgid "" -"This module does not work or is not available on WebAssembly. See :ref:`wasm-" -"availability` for more information." -msgstr "" -"此模組在 WebAssembly 平台上不起作用或無法使用。更多資訊請參閱 :ref:`wasm-" -"availability`。" - -#: ../../library/compileall.rst:22 -msgid "Command-line use" -msgstr "" - -#: ../../library/compileall.rst:24 -msgid "" -"This module can work as a script (using :program:`python -m compileall`) to " -"compile Python sources." -msgstr "" - -#: ../../library/compileall.rst:32 -msgid "" -"Positional arguments are files to compile or directories that contain source " -"files, traversed recursively. If no argument is given, behave as if the " -"command line was :samp:`-l {}`." -msgstr "" - -#: ../../library/compileall.rst:38 -msgid "" -"Do not recurse into subdirectories, only compile source code files directly " -"contained in the named or implied directories." -msgstr "" - -#: ../../library/compileall.rst:43 -msgid "Force rebuild even if timestamps are up-to-date." -msgstr "" - -#: ../../library/compileall.rst:47 -msgid "" -"Do not print the list of files compiled. If passed once, error messages will " -"still be printed. If passed twice (``-qq``), all output is suppressed." -msgstr "" - -#: ../../library/compileall.rst:52 -msgid "" -"Directory prepended to the path to each file being compiled. This will " -"appear in compilation time tracebacks, and is also compiled in to the byte-" -"code file, where it will be used in tracebacks and other messages in cases " -"where the source file does not exist at the time the byte-code file is " -"executed." -msgstr "" - -#: ../../library/compileall.rst:60 -msgid "" -"Remove the given prefix from paths recorded in the ``.pyc`` files. Paths are " -"made relative to the prefix." -msgstr "" - -#: ../../library/compileall.rst:63 -msgid "This option can be used with ``-p`` but not with ``-d``." -msgstr "" - -#: ../../library/compileall.rst:67 -msgid "" -"Prepend the given prefix to paths recorded in the ``.pyc`` files. Use ``-p /" -"`` to make the paths absolute." -msgstr "" - -#: ../../library/compileall.rst:70 -msgid "This option can be used with ``-s`` but not with ``-d``." -msgstr "" - -#: ../../library/compileall.rst:74 -msgid "" -"regex is used to search the full path to each file considered for " -"compilation, and if the regex produces a match, the file is skipped." -msgstr "" - -#: ../../library/compileall.rst:79 -msgid "" -"Read the file ``list`` and add each line that it contains to the list of " -"files and directories to compile. If ``list`` is ``-``, read lines from " -"``stdin``." -msgstr "" - -#: ../../library/compileall.rst:85 -msgid "" -"Write the byte-code files to their legacy locations and names, which may " -"overwrite byte-code files created by another version of Python. The default " -"is to write files to their :pep:`3147` locations and names, which allows " -"byte-code files from multiple versions of Python to coexist." -msgstr "" - -#: ../../library/compileall.rst:92 -msgid "" -"Control the maximum recursion level for subdirectories. If this is given, " -"then ``-l`` option will not be taken into account. :program:`python -m " -"compileall -r 0` is equivalent to :program:`python -m compileall " -" -l`." -msgstr "" - -#: ../../library/compileall.rst:99 -msgid "" -"Use *N* workers to compile the files within the given directory. If ``0`` is " -"used, then the result of :func:`os.process_cpu_count` will be used." -msgstr "" - -#: ../../library/compileall.rst:105 -msgid "" -"Control how the generated byte-code files are invalidated at runtime. The " -"``timestamp`` value, means that ``.pyc`` files with the source timestamp and " -"size embedded will be generated. The ``checked-hash`` and ``unchecked-hash`` " -"values cause hash-based pycs to be generated. Hash-based pycs embed a hash " -"of the source file contents rather than a timestamp. See :ref:`pyc-" -"invalidation` for more information on how Python validates bytecode cache " -"files at runtime. The default is ``timestamp`` if the :envvar:" -"`SOURCE_DATE_EPOCH` environment variable is not set, and ``checked-hash`` if " -"the ``SOURCE_DATE_EPOCH`` environment variable is set." -msgstr "" - -#: ../../library/compileall.rst:118 -msgid "" -"Compile with the given optimization level. May be used multiple times to " -"compile for multiple levels at a time (for example, ``compileall -o 1 -o " -"2``)." -msgstr "" - -#: ../../library/compileall.rst:124 -msgid "Ignore symlinks pointing outside the given directory." -msgstr "" - -#: ../../library/compileall.rst:128 -msgid "" -"If two ``.pyc`` files with different optimization level have the same " -"content, use hard links to consolidate duplicate files." -msgstr "" - -#: ../../library/compileall.rst:131 -msgid "Added the ``-i``, ``-b`` and ``-h`` options." -msgstr "新增選項 ``-i``、``-b`` 與 ``-h``。" - -#: ../../library/compileall.rst:134 -msgid "" -"Added the ``-j``, ``-r``, and ``-qq`` options. ``-q`` option was changed " -"to a multilevel value. ``-b`` will always produce a byte-code file ending " -"in ``.pyc``, never ``.pyo``." -msgstr "" - -#: ../../library/compileall.rst:139 -msgid "Added the ``--invalidation-mode`` option." -msgstr "新增選項 ``--invalidation-mode``。" - -#: ../../library/compileall.rst:142 -msgid "" -"Added the ``-s``, ``-p``, ``-e`` and ``--hardlink-dupes`` options. Raised " -"the default recursion limit from 10 to :py:func:`sys.getrecursionlimit()`. " -"Added the possibility to specify the ``-o`` option multiple times." -msgstr "" - -#: ../../library/compileall.rst:149 -msgid "" -"There is no command-line option to control the optimization level used by " -"the :func:`compile` function, because the Python interpreter itself already " -"provides the option: :program:`python -O -m compileall`." -msgstr "" - -#: ../../library/compileall.rst:153 -msgid "" -"Similarly, the :func:`compile` function respects the :data:`sys." -"pycache_prefix` setting. The generated bytecode cache will only be useful " -"if :func:`compile` is run with the same :data:`sys.pycache_prefix` (if any) " -"that will be used at runtime." -msgstr "" - -#: ../../library/compileall.rst:159 -msgid "Public functions" -msgstr "" - -#: ../../library/compileall.rst:163 -msgid "" -"Recursively descend the directory tree named by *dir*, compiling all :file:`." -"py` files along the way. Return a true value if all the files compiled " -"successfully, and a false value otherwise." -msgstr "" - -#: ../../library/compileall.rst:167 -msgid "" -"The *maxlevels* parameter is used to limit the depth of the recursion; it " -"defaults to ``sys.getrecursionlimit()``." -msgstr "" - -#: ../../library/compileall.rst:170 -msgid "" -"If *ddir* is given, it is prepended to the path to each file being compiled " -"for use in compilation time tracebacks, and is also compiled in to the byte-" -"code file, where it will be used in tracebacks and other messages in cases " -"where the source file does not exist at the time the byte-code file is " -"executed." -msgstr "" - -#: ../../library/compileall.rst:176 -msgid "" -"If *force* is true, modules are re-compiled even if the timestamps are up to " -"date." -msgstr "" - -#: ../../library/compileall.rst:179 -msgid "" -"If *rx* is given, its ``search`` method is called on the complete path to " -"each file considered for compilation, and if it returns a true value, the " -"file is skipped. This can be used to exclude files matching a regular " -"expression, given as a :ref:`re.Pattern ` object." -msgstr "" - -#: ../../library/compileall.rst:184 ../../library/compileall.rst:261 -msgid "" -"If *quiet* is ``False`` or ``0`` (the default), the filenames and other " -"information are printed to standard out. Set to ``1``, only errors are " -"printed. Set to ``2``, all output is suppressed." -msgstr "" - -#: ../../library/compileall.rst:188 ../../library/compileall.rst:265 -msgid "" -"If *legacy* is true, byte-code files are written to their legacy locations " -"and names, which may overwrite byte-code files created by another version of " -"Python. The default is to write files to their :pep:`3147` locations and " -"names, which allows byte-code files from multiple versions of Python to " -"coexist." -msgstr "" - -#: ../../library/compileall.rst:194 ../../library/compileall.rst:271 -msgid "" -"*optimize* specifies the optimization level for the compiler. It is passed " -"to the built-in :func:`compile` function. Accepts also a sequence of " -"optimization levels which lead to multiple compilations of one :file:`.py` " -"file in one call." -msgstr "" - -#: ../../library/compileall.rst:198 -msgid "" -"The argument *workers* specifies how many workers are used to compile files " -"in parallel. The default is to not use multiple workers. If the platform " -"can't use multiple workers and *workers* argument is given, then sequential " -"compilation will be used as a fallback. If *workers* is 0, the number of " -"cores in the system is used. If *workers* is lower than ``0``, a :exc:" -"`ValueError` will be raised." -msgstr "" - -#: ../../library/compileall.rst:205 ../../library/compileall.rst:275 -msgid "" -"*invalidation_mode* should be a member of the :class:`py_compile." -"PycInvalidationMode` enum and controls how the generated pycs are " -"invalidated at runtime." -msgstr "" - -#: ../../library/compileall.rst:209 ../../library/compileall.rst:279 -msgid "" -"The *stripdir*, *prependdir* and *limit_sl_dest* arguments correspond to the " -"``-s``, ``-p`` and ``-e`` options described above. They may be specified as " -"``str`` or :py:class:`os.PathLike`." -msgstr "" - -#: ../../library/compileall.rst:213 ../../library/compileall.rst:283 -msgid "" -"If *hardlink_dupes* is true and two ``.pyc`` files with different " -"optimization level have the same content, use hard links to consolidate " -"duplicate files." -msgstr "" - -#: ../../library/compileall.rst:216 ../../library/compileall.rst:314 -msgid "Added the *legacy* and *optimize* parameter." -msgstr "新增 *legacy* 與 *optimize* 參數。" - -#: ../../library/compileall.rst:219 -msgid "Added the *workers* parameter." -msgstr "新增 *workers* 參數。" - -#: ../../library/compileall.rst:222 ../../library/compileall.rst:288 -#: ../../library/compileall.rst:317 -msgid "*quiet* parameter was changed to a multilevel value." -msgstr "" - -#: ../../library/compileall.rst:225 ../../library/compileall.rst:291 -#: ../../library/compileall.rst:320 -msgid "" -"The *legacy* parameter only writes out ``.pyc`` files, not ``.pyo`` files no " -"matter what the value of *optimize* is." -msgstr "" - -#: ../../library/compileall.rst:229 -msgid "Accepts a :term:`path-like object`." -msgstr "" - -#: ../../library/compileall.rst:232 ../../library/compileall.rst:295 -#: ../../library/compileall.rst:324 -msgid "The *invalidation_mode* parameter was added." -msgstr "新增 *invalidation_mode* 參數。" - -#: ../../library/compileall.rst:235 ../../library/compileall.rst:298 -#: ../../library/compileall.rst:327 -msgid "" -"The *invalidation_mode* parameter's default value is updated to ``None``." -msgstr "新增 *invalidation_mode* 參數的預設值被更新為 ``None``。" - -#: ../../library/compileall.rst:238 -msgid "Setting *workers* to 0 now chooses the optimal number of cores." -msgstr "" - -#: ../../library/compileall.rst:241 -msgid "" -"Added *stripdir*, *prependdir*, *limit_sl_dest* and *hardlink_dupes* " -"arguments. Default value of *maxlevels* was changed from ``10`` to ``sys." -"getrecursionlimit()``" -msgstr "" - -#: ../../library/compileall.rst:247 -msgid "" -"Compile the file with path *fullname*. Return a true value if the file " -"compiled successfully, and a false value otherwise." -msgstr "" - -#: ../../library/compileall.rst:250 -msgid "" -"If *ddir* is given, it is prepended to the path to the file being compiled " -"for use in compilation time tracebacks, and is also compiled in to the byte-" -"code file, where it will be used in tracebacks and other messages in cases " -"where the source file does not exist at the time the byte-code file is " -"executed." -msgstr "" - -#: ../../library/compileall.rst:256 -msgid "" -"If *rx* is given, its ``search`` method is passed the full path name to the " -"file being compiled, and if it returns a true value, the file is not " -"compiled and ``True`` is returned. This can be used to exclude files " -"matching a regular expression, given as a :ref:`re.Pattern ` " -"object." -msgstr "" - -#: ../../library/compileall.rst:301 -msgid "" -"Added *stripdir*, *prependdir*, *limit_sl_dest* and *hardlink_dupes* " -"arguments." -msgstr "" - -#: ../../library/compileall.rst:306 -msgid "" -"Byte-compile all the :file:`.py` files found along ``sys.path``. Return a " -"true value if all the files compiled successfully, and a false value " -"otherwise." -msgstr "" - -#: ../../library/compileall.rst:309 -msgid "" -"If *skip_curdir* is true (the default), the current directory is not " -"included in the search. All other parameters are passed to the :func:" -"`compile_dir` function. Note that unlike the other compile functions, " -"``maxlevels`` defaults to ``0``." -msgstr "" - -#: ../../library/compileall.rst:330 -msgid "" -"To force a recompile of all the :file:`.py` files in the :file:`Lib/` " -"subdirectory and all its subdirectories::" -msgstr "" - -#: ../../library/compileall.rst:333 -msgid "" -"import compileall\n" -"\n" -"compileall.compile_dir('Lib/', force=True)\n" -"\n" -"# Perform same compilation, excluding files in .svn directories.\n" -"import re\n" -"compileall.compile_dir('Lib/', rx=re.compile(r'[/\\\\][.]svn'), force=True)\n" -"\n" -"# pathlib.Path objects can also be used.\n" -"import pathlib\n" -"compileall.compile_dir(pathlib.Path('Lib/'), force=True)" -msgstr "" -"import compileall\n" -"\n" -"compileall.compile_dir('Lib/', force=True)\n" -"\n" -"# 執行相同的編譯，但排除 .svn 目錄中的檔案。\n" -"import re\n" -"compileall.compile_dir('Lib/', rx=re.compile(r'[/\\\\][.]svn'), force=True)\n" -"\n" -"# pathlib.Path 物件也可以使用。\n" -"import pathlib\n" -"compileall.compile_dir(pathlib.Path('Lib/'), force=True)" - -#: ../../library/compileall.rst:347 -msgid "Module :mod:`py_compile`" -msgstr ":mod:`py_compile` 模組" - -#: ../../library/compileall.rst:348 -msgid "Byte-compile a single source file." -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-06-27 07:36+0000\n" +"PO-Revision-Date: 2018-05-23 14:41+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/compileall.rst:2 +msgid ":mod:`!compileall` --- Byte-compile Python libraries" +msgstr ":mod:`!compileall` --- 位元組編譯 Python 函式庫" + +#: ../../library/compileall.rst:7 +msgid "**Source code:** :source:`Lib/compileall.py`" +msgstr "**原始碼：**\\ :source:`Lib/compileall.py`" + +#: ../../library/compileall.rst:11 +msgid "" +"This module provides some utility functions to support installing Python " +"libraries. These functions compile Python source files in a directory tree. " +"This module can be used to create the cached byte-code files at library " +"installation time, which makes them available for use even by users who " +"don't have write permission to the library directories." +msgstr "" + +#: ../../includes/wasm-notavail.rst:3 +msgid "Availability" +msgstr "可用性" + +#: ../../includes/wasm-notavail.rst:5 +msgid "" +"This module does not work or is not available on WebAssembly. See :ref:`wasm-" +"availability` for more information." +msgstr "" +"此模組在 WebAssembly 平台上不起作用或無法使用。更多資訊請參閱 :ref:`wasm-" +"availability`。" + +#: ../../library/compileall.rst:22 +msgid "Command-line use" +msgstr "" + +#: ../../library/compileall.rst:24 +msgid "" +"This module can work as a script (using :program:`python -m compileall`) to " +"compile Python sources." +msgstr "" + +#: ../../library/compileall.rst:32 +msgid "" +"Positional arguments are files to compile or directories that contain source " +"files, traversed recursively. If no argument is given, behave as if the " +"command line was :samp:`-l {}`." +msgstr "" + +#: ../../library/compileall.rst:38 +msgid "" +"Do not recurse into subdirectories, only compile source code files directly " +"contained in the named or implied directories." +msgstr "" + +#: ../../library/compileall.rst:43 +msgid "Force rebuild even if timestamps are up-to-date." +msgstr "" + +#: ../../library/compileall.rst:47 +msgid "" +"Do not print the list of files compiled. If passed once, error messages will " +"still be printed. If passed twice (``-qq``), all output is suppressed." +msgstr "" + +#: ../../library/compileall.rst:52 +msgid "" +"Directory prepended to the path to each file being compiled. This will " +"appear in compilation time tracebacks, and is also compiled in to the byte-" +"code file, where it will be used in tracebacks and other messages in cases " +"where the source file does not exist at the time the byte-code file is " +"executed." +msgstr "" + +#: ../../library/compileall.rst:60 +msgid "" +"Remove the given prefix from paths recorded in the ``.pyc`` files. Paths are " +"made relative to the prefix." +msgstr "" + +#: ../../library/compileall.rst:63 +msgid "This option can be used with ``-p`` but not with ``-d``." +msgstr "" + +#: ../../library/compileall.rst:67 +msgid "" +"Prepend the given prefix to paths recorded in the ``.pyc`` files. Use ``-p /" +"`` to make the paths absolute." +msgstr "" + +#: ../../library/compileall.rst:70 +msgid "This option can be used with ``-s`` but not with ``-d``." +msgstr "" + +#: ../../library/compileall.rst:74 +msgid "" +"regex is used to search the full path to each file considered for " +"compilation, and if the regex produces a match, the file is skipped." +msgstr "" + +#: ../../library/compileall.rst:79 +msgid "" +"Read the file ``list`` and add each line that it contains to the list of " +"files and directories to compile. If ``list`` is ``-``, read lines from " +"``stdin``." +msgstr "" + +#: ../../library/compileall.rst:85 +msgid "" +"Write the byte-code files to their legacy locations and names, which may " +"overwrite byte-code files created by another version of Python. The default " +"is to write files to their :pep:`3147` locations and names, which allows " +"byte-code files from multiple versions of Python to coexist." +msgstr "" + +#: ../../library/compileall.rst:92 +msgid "" +"Control the maximum recursion level for subdirectories. If this is given, " +"then ``-l`` option will not be taken into account. :program:`python -m " +"compileall -r 0` is equivalent to :program:`python -m compileall " +" -l`." +msgstr "" + +#: ../../library/compileall.rst:99 +msgid "" +"Use *N* workers to compile the files within the given directory. If ``0`` is " +"used, then the result of :func:`os.process_cpu_count` will be used." +msgstr "" + +#: ../../library/compileall.rst:105 +msgid "" +"Control how the generated byte-code files are invalidated at runtime. The " +"``timestamp`` value, means that ``.pyc`` files with the source timestamp and " +"size embedded will be generated. The ``checked-hash`` and ``unchecked-hash`` " +"values cause hash-based pycs to be generated. Hash-based pycs embed a hash " +"of the source file contents rather than a timestamp. See :ref:`pyc-" +"invalidation` for more information on how Python validates bytecode cache " +"files at runtime. The default is ``timestamp`` if the :envvar:" +"`SOURCE_DATE_EPOCH` environment variable is not set, and ``checked-hash`` if " +"the ``SOURCE_DATE_EPOCH`` environment variable is set." +msgstr "" + +#: ../../library/compileall.rst:118 +msgid "" +"Compile with the given optimization level. May be used multiple times to " +"compile for multiple levels at a time (for example, ``compileall -o 1 -o " +"2``)." +msgstr "" + +#: ../../library/compileall.rst:124 +msgid "Ignore symlinks pointing outside the given directory." +msgstr "" + +#: ../../library/compileall.rst:128 +msgid "" +"If two ``.pyc`` files with different optimization level have the same " +"content, use hard links to consolidate duplicate files." +msgstr "" + +#: ../../library/compileall.rst:131 +msgid "Added the ``-i``, ``-b`` and ``-h`` options." +msgstr "新增選項 ``-i``、``-b`` 與 ``-h``。" + +#: ../../library/compileall.rst:134 +msgid "" +"Added the ``-j``, ``-r``, and ``-qq`` options. ``-q`` option was changed " +"to a multilevel value. ``-b`` will always produce a byte-code file ending " +"in ``.pyc``, never ``.pyo``." +msgstr "" + +#: ../../library/compileall.rst:139 +msgid "Added the ``--invalidation-mode`` option." +msgstr "新增選項 ``--invalidation-mode``。" + +#: ../../library/compileall.rst:142 +msgid "" +"Added the ``-s``, ``-p``, ``-e`` and ``--hardlink-dupes`` options. Raised " +"the default recursion limit from 10 to :py:func:`sys.getrecursionlimit()`. " +"Added the possibility to specify the ``-o`` option multiple times." +msgstr "" + +#: ../../library/compileall.rst:149 +msgid "" +"There is no command-line option to control the optimization level used by " +"the :func:`compile` function, because the Python interpreter itself already " +"provides the option: :program:`python -O -m compileall`." +msgstr "" + +#: ../../library/compileall.rst:153 +msgid "" +"Similarly, the :func:`compile` function respects the :data:`sys." +"pycache_prefix` setting. The generated bytecode cache will only be useful " +"if :func:`compile` is run with the same :data:`sys.pycache_prefix` (if any) " +"that will be used at runtime." +msgstr "" + +#: ../../library/compileall.rst:159 +msgid "Public functions" +msgstr "" + +#: ../../library/compileall.rst:163 +msgid "" +"Recursively descend the directory tree named by *dir*, compiling all :file:`." +"py` files along the way. Return a true value if all the files compiled " +"successfully, and a false value otherwise." +msgstr "" + +#: ../../library/compileall.rst:167 +msgid "" +"The *maxlevels* parameter is used to limit the depth of the recursion; it " +"defaults to ``sys.getrecursionlimit()``." +msgstr "" + +#: ../../library/compileall.rst:170 +msgid "" +"If *ddir* is given, it is prepended to the path to each file being compiled " +"for use in compilation time tracebacks, and is also compiled in to the byte-" +"code file, where it will be used in tracebacks and other messages in cases " +"where the source file does not exist at the time the byte-code file is " +"executed." +msgstr "" + +#: ../../library/compileall.rst:176 +msgid "" +"If *force* is true, modules are re-compiled even if the timestamps are up to " +"date." +msgstr "" + +#: ../../library/compileall.rst:179 +msgid "" +"If *rx* is given, its ``search`` method is called on the complete path to " +"each file considered for compilation, and if it returns a true value, the " +"file is skipped. This can be used to exclude files matching a regular " +"expression, given as a :ref:`re.Pattern ` object." +msgstr "" + +#: ../../library/compileall.rst:184 ../../library/compileall.rst:261 +msgid "" +"If *quiet* is ``False`` or ``0`` (the default), the filenames and other " +"information are printed to standard out. Set to ``1``, only errors are " +"printed. Set to ``2``, all output is suppressed." +msgstr "" + +#: ../../library/compileall.rst:188 ../../library/compileall.rst:265 +msgid "" +"If *legacy* is true, byte-code files are written to their legacy locations " +"and names, which may overwrite byte-code files created by another version of " +"Python. The default is to write files to their :pep:`3147` locations and " +"names, which allows byte-code files from multiple versions of Python to " +"coexist." +msgstr "" + +#: ../../library/compileall.rst:194 ../../library/compileall.rst:271 +msgid "" +"*optimize* specifies the optimization level for the compiler. It is passed " +"to the built-in :func:`compile` function. Accepts also a sequence of " +"optimization levels which lead to multiple compilations of one :file:`.py` " +"file in one call." +msgstr "" + +#: ../../library/compileall.rst:198 +msgid "" +"The argument *workers* specifies how many workers are used to compile files " +"in parallel. The default is to not use multiple workers. If the platform " +"can't use multiple workers and *workers* argument is given, then sequential " +"compilation will be used as a fallback. If *workers* is 0, the number of " +"cores in the system is used. If *workers* is lower than ``0``, a :exc:" +"`ValueError` will be raised." +msgstr "" + +#: ../../library/compileall.rst:205 ../../library/compileall.rst:275 +msgid "" +"*invalidation_mode* should be a member of the :class:`py_compile." +"PycInvalidationMode` enum and controls how the generated pycs are " +"invalidated at runtime." +msgstr "" + +#: ../../library/compileall.rst:209 ../../library/compileall.rst:279 +msgid "" +"The *stripdir*, *prependdir* and *limit_sl_dest* arguments correspond to the " +"``-s``, ``-p`` and ``-e`` options described above. They may be specified as " +"``str`` or :py:class:`os.PathLike`." +msgstr "" + +#: ../../library/compileall.rst:213 ../../library/compileall.rst:283 +msgid "" +"If *hardlink_dupes* is true and two ``.pyc`` files with different " +"optimization level have the same content, use hard links to consolidate " +"duplicate files." +msgstr "" + +#: ../../library/compileall.rst:216 ../../library/compileall.rst:314 +msgid "Added the *legacy* and *optimize* parameter." +msgstr "新增 *legacy* 與 *optimize* 參數。" + +#: ../../library/compileall.rst:219 +msgid "Added the *workers* parameter." +msgstr "新增 *workers* 參數。" + +#: ../../library/compileall.rst:222 ../../library/compileall.rst:288 +#: ../../library/compileall.rst:317 +msgid "*quiet* parameter was changed to a multilevel value." +msgstr "" + +#: ../../library/compileall.rst:225 ../../library/compileall.rst:291 +#: ../../library/compileall.rst:320 +msgid "" +"The *legacy* parameter only writes out ``.pyc`` files, not ``.pyo`` files no " +"matter what the value of *optimize* is." +msgstr "" + +#: ../../library/compileall.rst:229 +msgid "Accepts a :term:`path-like object`." +msgstr "" + +#: ../../library/compileall.rst:232 ../../library/compileall.rst:295 +#: ../../library/compileall.rst:324 +msgid "The *invalidation_mode* parameter was added." +msgstr "新增 *invalidation_mode* 參數。" + +#: ../../library/compileall.rst:235 ../../library/compileall.rst:298 +#: ../../library/compileall.rst:327 +msgid "" +"The *invalidation_mode* parameter's default value is updated to ``None``." +msgstr "新增 *invalidation_mode* 參數的預設值被更新為 ``None``。" + +#: ../../library/compileall.rst:238 +msgid "Setting *workers* to 0 now chooses the optimal number of cores." +msgstr "" + +#: ../../library/compileall.rst:241 +msgid "" +"Added *stripdir*, *prependdir*, *limit_sl_dest* and *hardlink_dupes* " +"arguments. Default value of *maxlevels* was changed from ``10`` to ``sys." +"getrecursionlimit()``" +msgstr "" + +#: ../../library/compileall.rst:247 +msgid "" +"Compile the file with path *fullname*. Return a true value if the file " +"compiled successfully, and a false value otherwise." +msgstr "" + +#: ../../library/compileall.rst:250 +msgid "" +"If *ddir* is given, it is prepended to the path to the file being compiled " +"for use in compilation time tracebacks, and is also compiled in to the byte-" +"code file, where it will be used in tracebacks and other messages in cases " +"where the source file does not exist at the time the byte-code file is " +"executed." +msgstr "" + +#: ../../library/compileall.rst:256 +msgid "" +"If *rx* is given, its ``search`` method is passed the full path name to the " +"file being compiled, and if it returns a true value, the file is not " +"compiled and ``True`` is returned. This can be used to exclude files " +"matching a regular expression, given as a :ref:`re.Pattern ` " +"object." +msgstr "" + +#: ../../library/compileall.rst:301 +msgid "" +"Added *stripdir*, *prependdir*, *limit_sl_dest* and *hardlink_dupes* " +"arguments." +msgstr "" + +#: ../../library/compileall.rst:306 +msgid "" +"Byte-compile all the :file:`.py` files found along ``sys.path``. Return a " +"true value if all the files compiled successfully, and a false value " +"otherwise." +msgstr "" + +#: ../../library/compileall.rst:309 +msgid "" +"If *skip_curdir* is true (the default), the current directory is not " +"included in the search. All other parameters are passed to the :func:" +"`compile_dir` function. Note that unlike the other compile functions, " +"``maxlevels`` defaults to ``0``." +msgstr "" + +#: ../../library/compileall.rst:330 +msgid "" +"To force a recompile of all the :file:`.py` files in the :file:`Lib/` " +"subdirectory and all its subdirectories::" +msgstr "" + +#: ../../library/compileall.rst:333 +msgid "" +"import compileall\n" +"\n" +"compileall.compile_dir('Lib/', force=True)\n" +"\n" +"# Perform same compilation, excluding files in .svn directories.\n" +"import re\n" +"compileall.compile_dir('Lib/', rx=re.compile(r'[/\\\\][.]svn'), force=True)\n" +"\n" +"# pathlib.Path objects can also be used.\n" +"import pathlib\n" +"compileall.compile_dir(pathlib.Path('Lib/'), force=True)" +msgstr "" +"import compileall\n" +"\n" +"compileall.compile_dir('Lib/', force=True)\n" +"\n" +"# 執行相同的編譯，但排除 .svn 目錄中的檔案。\n" +"import re\n" +"compileall.compile_dir('Lib/', rx=re.compile(r'[/\\\\][.]svn'), force=True)\n" +"\n" +"# pathlib.Path 物件也可以使用。\n" +"import pathlib\n" +"compileall.compile_dir(pathlib.Path('Lib/'), force=True)" + +#: ../../library/compileall.rst:347 +msgid "Module :mod:`py_compile`" +msgstr ":mod:`py_compile` 模組" + +#: ../../library/compileall.rst:348 +msgid "Byte-compile a single source file." +msgstr "" diff --git a/library/compression.po b/library/compression.po index db9321737a..6a8e69bc62 100644 --- a/library/compression.po +++ b/library/compression.po @@ -1,55 +1,55 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# FIRST AUTHOR , YEAR. -# -#, fuzzy -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-10-05 00:16+0000\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language-Team: LANGUAGE \n" -"Language: zh_TW\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=UTF-8\n" -"Content-Transfer-Encoding: 8bit\n" - -#: ../../library/compression.rst:2 -msgid "The :mod:`!compression` package" -msgstr ":mod:`!compression` 套件" - -#: ../../library/compression.rst:8 -msgid "" -"The :mod:`!compression` package contains the canonical compression modules " -"containing interfaces to several different compression algorithms. Some of " -"these modules have historically been available as separate modules; those " -"will continue to be available under their original names for compatibility " -"reasons, and will not be removed without a deprecation cycle. The use of " -"modules in :mod:`!compression` is encouraged where practical." -msgstr "" -":mod:`!compression` 套件包含了有多種不同壓縮演算法介面的標準壓縮模組。其中一些模組過去" -"是以獨立模組的形式提供；為了相容性考量，這些模組將繼續以其原始名稱提供，並且不會在沒有經過" -"棄用週期的情況下被移除。建議在可行的情況下盡量先使用 :mod:`!compression` 中的模組。" - -#: ../../library/compression.rst:15 -msgid ":mod:`!compression.bz2` -- Re-exports :mod:`bz2`" -msgstr ":mod:`!compression.bz2` -- 重新匯出 :mod:`bz2`" - -#: ../../library/compression.rst:16 -msgid ":mod:`!compression.gzip` -- Re-exports :mod:`gzip`" -msgstr ":mod:`!compression.gzip` -- 重新匯出 :mod:`gzip`" - -#: ../../library/compression.rst:17 -msgid ":mod:`!compression.lzma` -- Re-exports :mod:`lzma`" -msgstr ":mod:`!compression.lzma` -- 重新匯出 :mod:`lzma`" - -#: ../../library/compression.rst:18 -msgid ":mod:`!compression.zlib` -- Re-exports :mod:`zlib`" -msgstr ":mod:`!compression.zlib` -- 重新匯出 :mod:`zlib`" - -#: ../../library/compression.rst:19 -msgid "" -":mod:`compression.zstd` -- Wrapper for the Zstandard compression library" -msgstr ":mod:`compression.zstd` -- Zstandard 壓縮函式庫的包裝器" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-10-05 00:16+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"Language: zh_TW\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../library/compression.rst:2 +msgid "The :mod:`!compression` package" +msgstr ":mod:`!compression` 套件" + +#: ../../library/compression.rst:8 +msgid "" +"The :mod:`!compression` package contains the canonical compression modules " +"containing interfaces to several different compression algorithms. Some of " +"these modules have historically been available as separate modules; those " +"will continue to be available under their original names for compatibility " +"reasons, and will not be removed without a deprecation cycle. The use of " +"modules in :mod:`!compression` is encouraged where practical." +msgstr "" +":mod:`!compression` 套件包含了有多種不同壓縮演算法介面的標準壓縮模組。其中一些模組過去" +"是以獨立模組的形式提供；為了相容性考量，這些模組將繼續以其原始名稱提供，並且不會在沒有經過" +"棄用週期的情況下被移除。建議在可行的情況下盡量先使用 :mod:`!compression` 中的模組。" + +#: ../../library/compression.rst:15 +msgid ":mod:`!compression.bz2` -- Re-exports :mod:`bz2`" +msgstr ":mod:`!compression.bz2` -- 重新匯出 :mod:`bz2`" + +#: ../../library/compression.rst:16 +msgid ":mod:`!compression.gzip` -- Re-exports :mod:`gzip`" +msgstr ":mod:`!compression.gzip` -- 重新匯出 :mod:`gzip`" + +#: ../../library/compression.rst:17 +msgid ":mod:`!compression.lzma` -- Re-exports :mod:`lzma`" +msgstr ":mod:`!compression.lzma` -- 重新匯出 :mod:`lzma`" + +#: ../../library/compression.rst:18 +msgid ":mod:`!compression.zlib` -- Re-exports :mod:`zlib`" +msgstr ":mod:`!compression.zlib` -- 重新匯出 :mod:`zlib`" + +#: ../../library/compression.rst:19 +msgid "" +":mod:`compression.zstd` -- Wrapper for the Zstandard compression library" +msgstr ":mod:`compression.zstd` -- Zstandard 壓縮函式庫的包裝器" diff --git a/library/compression.zstd.po b/library/compression.zstd.po index 9e42a61c1c..c62d1d3436 100644 --- a/library/compression.zstd.po +++ b/library/compression.zstd.po @@ -1,1198 +1,1198 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# FIRST AUTHOR , YEAR. -# -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2026-01-06 00:19+0000\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language-Team: LANGUAGE \n" -"Language: zh_TW\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=UTF-8\n" -"Content-Transfer-Encoding: 8bit\n" - -#: ../../library/compression.zstd.rst:2 -msgid "" -":mod:`!compression.zstd` --- Compression compatible with the Zstandard format" -msgstr ":mod:`!compression.zstd` --- 與 Zstandard 格式相容的壓縮" - -#: ../../library/compression.zstd.rst:10 -msgid "**Source code:** :source:`Lib/compression/zstd/__init__.py`" -msgstr "**原始碼：**\\ :source:`Lib/compression/zstd/__init__.py`" - -#: ../../library/compression.zstd.rst:14 -msgid "" -"This module provides classes and functions for compressing and decompressing " -"data using the Zstandard (or *zstd*) compression algorithm. The `zstd manual " -"`__ describes " -"Zstandard as \"a fast lossless compression algorithm, targeting real-time " -"compression scenarios at zlib-level and better compression ratios.\" Also " -"included is a file interface that supports reading and writing the contents " -"of ``.zst`` files created by the :program:`zstd` utility, as well as raw " -"zstd compressed streams." -msgstr "" - -#: ../../library/compression.zstd.rst:23 -msgid "The :mod:`!compression.zstd` module contains:" -msgstr ":mod:`!compression.zstd` 模組包含：" - -#: ../../library/compression.zstd.rst:25 -msgid "" -"The :func:`.open` function and :class:`ZstdFile` class for reading and " -"writing compressed files." -msgstr "" - -#: ../../library/compression.zstd.rst:27 -msgid "" -"The :class:`ZstdCompressor` and :class:`ZstdDecompressor` classes for " -"incremental (de)compression." -msgstr "" - -#: ../../library/compression.zstd.rst:29 -msgid "" -"The :func:`compress` and :func:`decompress` functions for one-shot " -"(de)compression." -msgstr "" - -#: ../../library/compression.zstd.rst:31 -msgid "" -"The :func:`train_dict` and :func:`finalize_dict` functions and the :class:" -"`ZstdDict` class to train and manage Zstandard dictionaries." -msgstr "" - -#: ../../library/compression.zstd.rst:33 -msgid "" -"The :class:`CompressionParameter`, :class:`DecompressionParameter`, and :" -"class:`Strategy` classes for setting advanced (de)compression parameters." -msgstr "" - -#: ../../includes/optional-module.rst:1 -msgid "" -"This is an :term:`optional module`. If it is missing from your copy of " -"CPython, look for documentation from your distributor (that is, whoever " -"provided Python to you). If you are the distributor, see :ref:`optional-" -"module-requirements`." -msgstr "" - -#: ../../library/compression.zstd.rst:40 -msgid "Exceptions" -msgstr "例外" - -#: ../../library/compression.zstd.rst:44 -msgid "" -"This exception is raised when an error occurs during compression or " -"decompression, or while initializing the (de)compressor state." -msgstr "" - -#: ../../library/compression.zstd.rst:49 -msgid "Reading and writing compressed files" -msgstr "" - -#: ../../library/compression.zstd.rst:54 -msgid "" -"Open a Zstandard-compressed file in binary or text mode, returning a :term:" -"`file object`." -msgstr "" - -#: ../../library/compression.zstd.rst:57 -msgid "" -"The *file* argument can be either a file name (given as a :class:`str`, :" -"class:`bytes` or :term:`path-like ` object), in which case " -"the named file is opened, or it can be an existing file object to read from " -"or write to." -msgstr "" - -#: ../../library/compression.zstd.rst:62 -msgid "" -"The mode argument can be either ``'rb'`` for reading (default), ``'wb'`` for " -"overwriting, ``'ab'`` for appending, or ``'xb'`` for exclusive creation. " -"These can equivalently be given as ``'r'``, ``'w'``, ``'a'``, and ``'x'`` " -"respectively. You may also open in text mode with ``'rt'``, ``'wt'``, " -"``'at'``, and ``'xt'`` respectively." -msgstr "" - -#: ../../library/compression.zstd.rst:68 ../../library/compression.zstd.rst:112 -msgid "" -"When reading, the *options* argument can be a dictionary providing advanced " -"decompression parameters; see :class:`DecompressionParameter` for detailed " -"information about supported parameters. The *zstd_dict* argument is a :class:" -"`ZstdDict` instance to be used during decompression. When reading, if the " -"*level* argument is not None, a :exc:`!TypeError` will be raised." -msgstr "" - -#: ../../library/compression.zstd.rst:75 -msgid "" -"When writing, the *options* argument can be a dictionary providing advanced " -"compression parameters; see :class:`CompressionParameter` for detailed " -"information about supported parameters. The *level* argument is the " -"compression level to use when writing compressed data. Only one of *level* " -"or *options* may be non-None. The *zstd_dict* argument is a :class:" -"`ZstdDict` instance to be used during compression." -msgstr "" - -#: ../../library/compression.zstd.rst:83 -msgid "" -"In binary mode, this function is equivalent to the :class:`ZstdFile` " -"constructor: ``ZstdFile(file, mode, ...)``. In this case, the *encoding*, " -"*errors*, and *newline* parameters must not be provided." -msgstr "" - -#: ../../library/compression.zstd.rst:87 -msgid "" -"In text mode, a :class:`ZstdFile` object is created, and wrapped in an :" -"class:`io.TextIOWrapper` instance with the specified encoding, error " -"handling behavior, and line endings." -msgstr "" - -#: ../../library/compression.zstd.rst:95 -msgid "Open a Zstandard-compressed file in binary mode." -msgstr "" - -#: ../../library/compression.zstd.rst:97 -msgid "" -"A :class:`ZstdFile` can wrap an already-open :term:`file object`, or operate " -"directly on a named file. The *file* argument specifies either the file " -"object to wrap, or the name of the file to open (as a :class:`str`, :class:" -"`bytes` or :term:`path-like ` object). If wrapping an " -"existing file object, the wrapped file will not be closed when the :class:" -"`ZstdFile` is closed." -msgstr "" - -#: ../../library/compression.zstd.rst:104 -msgid "" -"The *mode* argument can be either ``'rb'`` for reading (default), ``'wb'`` " -"for overwriting, ``'xb'`` for exclusive creation, or ``'ab'`` for appending. " -"These can equivalently be given as ``'r'``, ``'w'``, ``'x'`` and ``'a'`` " -"respectively." -msgstr "" - -#: ../../library/compression.zstd.rst:109 -msgid "" -"If *file* is a file object (rather than an actual file name), a mode of " -"``'w'`` does not truncate the file, and is instead equivalent to ``'a'``." -msgstr "" - -#: ../../library/compression.zstd.rst:119 -msgid "" -"When writing, the *options* argument can be a dictionary providing advanced " -"compression parameters; see :class:`CompressionParameter` for detailed " -"information about supported parameters. The *level* argument is the " -"compression level to use when writing compressed data. Only one of *level* " -"or *options* may be passed. The *zstd_dict* argument is a :class:`ZstdDict` " -"instance to be used during compression." -msgstr "" - -#: ../../library/compression.zstd.rst:127 -msgid "" -":class:`!ZstdFile` supports all the members specified by :class:`io." -"BufferedIOBase`, except for :meth:`~io.BufferedIOBase.detach` and :meth:`~io." -"IOBase.truncate`. Iteration and the :keyword:`with` statement are supported." -msgstr "" - -#: ../../library/compression.zstd.rst:132 -msgid "The following method and attributes are also provided:" -msgstr "" - -#: ../../library/compression.zstd.rst:136 -msgid "" -"Return buffered data without advancing the file position. At least one byte " -"of data will be returned, unless EOF has been reached. The exact number of " -"bytes returned is unspecified (the *size* argument is ignored)." -msgstr "" - -#: ../../library/compression.zstd.rst:140 -msgid "" -"While calling :meth:`peek` does not change the file position of the :class:" -"`ZstdFile`, it may change the position of the underlying file object (for " -"example, if the :class:`ZstdFile` was constructed by passing a file object " -"for *file*)." -msgstr "" - -#: ../../library/compression.zstd.rst:147 -msgid "``'rb'`` for reading and ``'wb'`` for writing." -msgstr "" - -#: ../../library/compression.zstd.rst:151 -msgid "" -"The name of the Zstandard file. Equivalent to the :attr:`~io.FileIO.name` " -"attribute of the underlying :term:`file object`." -msgstr "" - -#: ../../library/compression.zstd.rst:156 -msgid "Compressing and decompressing data in memory" -msgstr "" - -#: ../../library/compression.zstd.rst:160 -msgid "" -"Compress *data* (a :term:`bytes-like object`), returning the compressed data " -"as a :class:`bytes` object." -msgstr "" - -#: ../../library/compression.zstd.rst:163 -#: ../../library/compression.zstd.rst:207 -msgid "" -"The *level* argument is an integer controlling the level of compression. " -"*level* is an alternative to setting :attr:`CompressionParameter." -"compression_level` in *options*. Use :meth:`~CompressionParameter.bounds` " -"on :attr:`~CompressionParameter.compression_level` to get the values that " -"can be passed for *level*. If advanced compression options are needed, the " -"*level* argument must be omitted and in the *options* dictionary the :attr:`!" -"CompressionParameter.compression_level` parameter should be set." -msgstr "" - -#: ../../library/compression.zstd.rst:172 -#: ../../library/compression.zstd.rst:216 -msgid "" -"The *options* argument is a Python dictionary containing advanced " -"compression parameters. The valid keys and values for compression parameters " -"are documented as part of the :class:`CompressionParameter` documentation." -msgstr "" - -#: ../../library/compression.zstd.rst:176 -msgid "" -"The *zstd_dict* argument is an instance of :class:`ZstdDict` containing " -"trained data to improve compression efficiency. The function :func:" -"`train_dict` can be used to generate a Zstandard dictionary." -msgstr "" - -#: ../../library/compression.zstd.rst:183 -msgid "" -"Decompress *data* (a :term:`bytes-like object`), returning the uncompressed " -"data as a :class:`bytes` object." -msgstr "" - -#: ../../library/compression.zstd.rst:186 -#: ../../library/compression.zstd.rst:308 -msgid "" -"The *options* argument is a Python dictionary containing advanced " -"decompression parameters. The valid keys and values for compression " -"parameters are documented as part of the :class:`DecompressionParameter` " -"documentation." -msgstr "" - -#: ../../library/compression.zstd.rst:191 -#: ../../library/compression.zstd.rst:313 -msgid "" -"The *zstd_dict* argument is an instance of :class:`ZstdDict` containing " -"trained data used during compression. This must be the same Zstandard " -"dictionary used during compression." -msgstr "" - -#: ../../library/compression.zstd.rst:195 -msgid "" -"If *data* is the concatenation of multiple distinct compressed frames, " -"decompress all of these frames, and return the concatenation of the results." -msgstr "" - -#: ../../library/compression.zstd.rst:201 -msgid "" -"Create a compressor object, which can be used to compress data incrementally." -msgstr "" - -#: ../../library/compression.zstd.rst:204 -msgid "" -"For a more convenient way of compressing a single chunk of data, see the " -"module-level function :func:`compress`." -msgstr "" - -#: ../../library/compression.zstd.rst:220 -msgid "" -"The *zstd_dict* argument is an optional instance of :class:`ZstdDict` " -"containing trained data to improve compression efficiency. The function :" -"func:`train_dict` can be used to generate a Zstandard dictionary." -msgstr "" - -#: ../../library/compression.zstd.rst:227 -msgid "" -"Compress *data* (a :term:`bytes-like object`), returning a :class:`bytes` " -"object with compressed data if possible, or otherwise an empty :class:`!" -"bytes` object. Some of *data* may be buffered internally, for use in later " -"calls to :meth:`!compress` and :meth:`~.flush`. The returned data should be " -"concatenated with the output of any previous calls to :meth:`~.compress`." -msgstr "" - -#: ../../library/compression.zstd.rst:234 -msgid "" -"The *mode* argument is a :class:`ZstdCompressor` attribute, either :attr:`~." -"CONTINUE`, :attr:`~.FLUSH_BLOCK`, or :attr:`~.FLUSH_FRAME`." -msgstr "" - -#: ../../library/compression.zstd.rst:238 -msgid "" -"When all data has been provided to the compressor, call the :meth:`~.flush` " -"method to finish the compression process. If :meth:`~.compress` is called " -"with *mode* set to :attr:`~.FLUSH_FRAME`, :meth:`~.flush` should not be " -"called, as it would write out a new empty frame." -msgstr "" - -#: ../../library/compression.zstd.rst:246 -msgid "" -"Finish the compression process, returning a :class:`bytes` object containing " -"any data stored in the compressor's internal buffers." -msgstr "" - -#: ../../library/compression.zstd.rst:249 -msgid "" -"The *mode* argument is a :class:`ZstdCompressor` attribute, either :attr:`~." -"FLUSH_BLOCK`, or :attr:`~.FLUSH_FRAME`." -msgstr "" - -#: ../../library/compression.zstd.rst:254 -msgid "" -"Specify the amount of uncompressed data *size* that will be provided for the " -"next frame. *size* will be written into the frame header of the next frame " -"unless :attr:`CompressionParameter.content_size_flag` is ``False`` or ``0``. " -"A size of ``0`` means that the frame is empty. If *size* is ``None``, the " -"frame header will omit the frame size. Frames that include the uncompressed " -"data size require less memory to decompress, especially at higher " -"compression levels." -msgstr "" - -#: ../../library/compression.zstd.rst:262 -msgid "" -"If :attr:`last_mode` is not :attr:`FLUSH_FRAME`, a :exc:`ValueError` is " -"raised as the compressor is not at the start of a frame. If the pledged size " -"does not match the actual size of data provided to :meth:`.compress`, future " -"calls to :meth:`!compress` or :meth:`flush` may raise :exc:`ZstdError` and " -"the last chunk of data may be lost." -msgstr "" - -#: ../../library/compression.zstd.rst:269 -msgid "" -"After :meth:`flush` or :meth:`.compress` are called with mode :attr:" -"`FLUSH_FRAME`, the next frame will not include the frame size into the " -"header unless :meth:`!set_pledged_input_size` is called again." -msgstr "" - -#: ../../library/compression.zstd.rst:275 -msgid "" -"Collect more data for compression, which may or may not generate output " -"immediately. This mode optimizes the compression ratio by maximizing the " -"amount of data per block and frame." -msgstr "" - -#: ../../library/compression.zstd.rst:281 -msgid "" -"Complete and write a block to the data stream. The data returned so far can " -"be immediately decompressed. Past data can still be referenced in future " -"blocks generated by calls to :meth:`~.compress`, improving compression." -msgstr "" - -#: ../../library/compression.zstd.rst:288 -msgid "" -"Complete and write out a frame. Future data provided to :meth:`~.compress` " -"will be written into a new frame and *cannot* reference past data." -msgstr "" - -#: ../../library/compression.zstd.rst:294 -msgid "" -"The last mode passed to either :meth:`~.compress` or :meth:`~.flush`. The " -"value can be one of :attr:`~.CONTINUE`, :attr:`~.FLUSH_BLOCK`, or :attr:`~." -"FLUSH_FRAME`. The initial value is :attr:`~.FLUSH_FRAME`, signifying that " -"the compressor is at the start of a new frame." -msgstr "" - -#: ../../library/compression.zstd.rst:302 -msgid "" -"Create a decompressor object, which can be used to decompress data " -"incrementally." -msgstr "" - -#: ../../library/compression.zstd.rst:305 -msgid "" -"For a more convenient way of decompressing an entire compressed stream at " -"once, see the module-level function :func:`decompress`." -msgstr "" - -#: ../../library/compression.zstd.rst:318 -msgid "" -"This class does not transparently handle inputs containing multiple " -"compressed frames, unlike the :func:`decompress` function and :class:" -"`ZstdFile` class. To decompress a multi-frame input, you should use :func:" -"`decompress`, :class:`ZstdFile` if working with a :term:`file object`, or " -"multiple :class:`!ZstdDecompressor` instances." -msgstr "" - -#: ../../library/compression.zstd.rst:326 -msgid "" -"Decompress *data* (a :term:`bytes-like object`), returning uncompressed data " -"as bytes. Some of *data* may be buffered internally, for use in later calls " -"to :meth:`!decompress`. The returned data should be concatenated with the " -"output of any previous calls to :meth:`!decompress`." -msgstr "" - -#: ../../library/compression.zstd.rst:332 -msgid "" -"If *max_length* is non-negative, the method returns at most *max_length* " -"bytes of decompressed data. If this limit is reached and further output can " -"be produced, the :attr:`~.needs_input` attribute will be set to ``False``. " -"In this case, the next call to :meth:`~.decompress` may provide *data* as " -"``b''`` to obtain more of the output." -msgstr "" - -#: ../../library/compression.zstd.rst:339 -msgid "" -"If all of the input data was decompressed and returned (either because this " -"was less than *max_length* bytes, or because *max_length* was negative), " -"the :attr:`~.needs_input` attribute will be set to ``True``." -msgstr "" - -#: ../../library/compression.zstd.rst:344 -msgid "" -"Attempting to decompress data after the end of a frame will raise a :exc:" -"`ZstdError`. Any data found after the end of the frame is ignored and saved " -"in the :attr:`~.unused_data` attribute." -msgstr "" - -#: ../../library/compression.zstd.rst:350 -msgid "``True`` if the end-of-stream marker has been reached." -msgstr "" - -#: ../../library/compression.zstd.rst:354 -msgid "Data found after the end of the compressed stream." -msgstr "" - -#: ../../library/compression.zstd.rst:356 -msgid "Before the end of the stream is reached, this will be ``b''``." -msgstr "" - -#: ../../library/compression.zstd.rst:360 -msgid "" -"``False`` if the :meth:`.decompress` method can provide more decompressed " -"data before requiring new compressed input." -msgstr "" - -#: ../../library/compression.zstd.rst:365 -msgid "Zstandard dictionaries" -msgstr "Zstandard 字典" - -#: ../../library/compression.zstd.rst:370 -msgid "" -"Train a Zstandard dictionary, returning a :class:`ZstdDict` instance. " -"Zstandard dictionaries enable more efficient compression of smaller sizes of " -"data, which is traditionally difficult to compress due to less repetition. " -"If you are compressing multiple similar groups of data (such as similar " -"files), Zstandard dictionaries can improve compression ratios and speed " -"significantly." -msgstr "" - -#: ../../library/compression.zstd.rst:377 -msgid "" -"The *samples* argument (an iterable of :class:`bytes` objects), is the " -"population of samples used to train the Zstandard dictionary." -msgstr "" - -#: ../../library/compression.zstd.rst:380 -msgid "" -"The *dict_size* argument, an integer, is the maximum size (in bytes) the " -"Zstandard dictionary should be. The Zstandard documentation suggests an " -"absolute maximum of no more than 100 KB, but the maximum can often be " -"smaller depending on the data. Larger dictionaries generally slow down " -"compression, but improve compression ratios. Smaller dictionaries lead to " -"faster compression, but reduce the compression ratio." -msgstr "" - -#: ../../library/compression.zstd.rst:390 -msgid "" -"An advanced function for converting a \"raw content\" Zstandard dictionary " -"into a regular Zstandard dictionary. \"Raw content\" dictionaries are a " -"sequence of bytes that do not need to follow the structure of a normal " -"Zstandard dictionary." -msgstr "" - -#: ../../library/compression.zstd.rst:395 -msgid "" -"The *zstd_dict* argument is a :class:`ZstdDict` instance with the :attr:" -"`~ZstdDict.dict_content` containing the raw dictionary contents." -msgstr "" - -#: ../../library/compression.zstd.rst:398 -msgid "" -"The *samples* argument (an iterable of :class:`bytes` objects), contains " -"sample data for generating the Zstandard dictionary." -msgstr "" - -#: ../../library/compression.zstd.rst:401 -msgid "" -"The *dict_size* argument, an integer, is the maximum size (in bytes) the " -"Zstandard dictionary should be. See :func:`train_dict` for suggestions on " -"the maximum dictionary size." -msgstr "" - -#: ../../library/compression.zstd.rst:405 -msgid "" -"The *level* argument (an integer) is the compression level expected to be " -"passed to the compressors using this dictionary. The dictionary information " -"varies for each compression level, so tuning for the proper compression " -"level can make compression more efficient." -msgstr "" - -#: ../../library/compression.zstd.rst:413 -msgid "" -"A wrapper around Zstandard dictionaries. Dictionaries can be used to improve " -"the compression of many small chunks of data. Use :func:`train_dict` if you " -"need to train a new dictionary from sample data." -msgstr "" - -#: ../../library/compression.zstd.rst:417 -msgid "" -"The *dict_content* argument (a :term:`bytes-like object`), is the already " -"trained dictionary information." -msgstr "" - -#: ../../library/compression.zstd.rst:420 -msgid "" -"The *is_raw* argument, a boolean, is an advanced parameter controlling the " -"meaning of *dict_content*. ``True`` means *dict_content* is a \"raw " -"content\" dictionary, without any format restrictions. ``False`` means " -"*dict_content* is an ordinary Zstandard dictionary, created from Zstandard " -"functions, for example, :func:`train_dict` or the external :program:`zstd` " -"CLI." -msgstr "" - -#: ../../library/compression.zstd.rst:426 -msgid "" -"When passing a :class:`!ZstdDict` to a function, the :attr:`!" -"as_digested_dict` and :attr:`!as_undigested_dict` attributes can control how " -"the dictionary is loaded by passing them as the ``zstd_dict`` argument, for " -"example, ``compress(data, zstd_dict=zd.as_digested_dict)``. Digesting a " -"dictionary is a costly operation that occurs when loading a Zstandard " -"dictionary. When making multiple calls to compression or decompression, " -"passing a digested dictionary will reduce the overhead of loading the " -"dictionary." -msgstr "" - -#: ../../library/compression.zstd.rst:435 -msgid "Difference for compression" -msgstr "" - -#: ../../library/compression.zstd.rst:440 -msgid "Digested dictionary" -msgstr "" - -#: ../../library/compression.zstd.rst:441 -msgid "Undigested dictionary" -msgstr "" - -#: ../../library/compression.zstd.rst:442 -msgid "" -"Advanced parameters of the compressor which may be overridden by the " -"dictionary's parameters" -msgstr "" - -#: ../../library/compression.zstd.rst:444 -msgid "" -"``window_log``, ``hash_log``, ``chain_log``, ``search_log``, ``min_match``, " -"``target_length``, ``strategy``, ``enable_long_distance_matching``, " -"``ldm_hash_log``, ``ldm_min_match``, ``ldm_bucket_size_log``, " -"``ldm_hash_rate_log``, and some non-public parameters." -msgstr "" - -#: ../../library/compression.zstd.rst:449 -msgid "None" -msgstr "" - -#: ../../library/compression.zstd.rst:450 -msgid ":class:`!ZstdDict` internally caches the dictionary" -msgstr "" - -#: ../../library/compression.zstd.rst:451 -msgid "" -"Yes. It's faster when loading a digested dictionary again with the same " -"compression level." -msgstr "" - -#: ../../library/compression.zstd.rst:453 -msgid "" -"No. If you wish to load an undigested dictionary multiple times, consider " -"reusing a compressor object." -msgstr "" - -#: ../../library/compression.zstd.rst:456 -msgid "" -"If passing a :class:`!ZstdDict` without any attribute, an undigested " -"dictionary is passed by default when compressing and a digested dictionary " -"is generated if necessary and passed by default when decompressing." -msgstr "" - -#: ../../library/compression.zstd.rst:462 -msgid "" -"The content of the Zstandard dictionary, a ``bytes`` object. It's the same " -"as the *dict_content* argument in the ``__init__`` method. It can be used " -"with other programs, such as the ``zstd`` CLI program." -msgstr "" - -#: ../../library/compression.zstd.rst:468 -msgid "Identifier of the Zstandard dictionary, a non-negative int value." -msgstr "" - -#: ../../library/compression.zstd.rst:470 -msgid "" -"Non-zero means the dictionary is ordinary, created by Zstandard functions " -"and following the Zstandard format." -msgstr "" - -#: ../../library/compression.zstd.rst:473 -msgid "" -"``0`` means a \"raw content\" dictionary, free of any format restriction, " -"used for advanced users." -msgstr "" - -#: ../../library/compression.zstd.rst:478 -msgid "" -"The meaning of ``0`` for :attr:`!ZstdDict.dict_id` is different from the " -"``dictionary_id`` attribute to the :func:`get_frame_info` function." -msgstr "" - -#: ../../library/compression.zstd.rst:484 -msgid "Load as a digested dictionary." -msgstr "" - -#: ../../library/compression.zstd.rst:488 -msgid "Load as an undigested dictionary." -msgstr "" - -#: ../../library/compression.zstd.rst:492 -msgid "Advanced parameter control" -msgstr "" - -#: ../../library/compression.zstd.rst:496 -msgid "" -"An :class:`~enum.IntEnum` containing the advanced compression parameter keys " -"that can be used when compressing data." -msgstr "" - -#: ../../library/compression.zstd.rst:499 -#: ../../library/compression.zstd.rst:733 -msgid "" -"The :meth:`~.bounds` method can be used on any attribute to get the valid " -"values for that parameter." -msgstr "" - -#: ../../library/compression.zstd.rst:502 -msgid "" -"Parameters are optional; any omitted parameter will have it's value selected " -"automatically." -msgstr "" - -#: ../../library/compression.zstd.rst:505 -msgid "" -"Example getting the lower and upper bound of :attr:`~.compression_level`::" -msgstr "" - -#: ../../library/compression.zstd.rst:507 -msgid "lower, upper = CompressionParameter.compression_level.bounds()" -msgstr "" - -#: ../../library/compression.zstd.rst:509 -msgid "Example setting the :attr:`~.window_log` to the maximum size::" -msgstr "" - -#: ../../library/compression.zstd.rst:511 -msgid "" -"_lower, upper = CompressionParameter.window_log.bounds()\n" -"options = {CompressionParameter.window_log: upper}\n" -"compress(b'venezuelan beaver cheese', options=options)" -msgstr "" - -#: ../../library/compression.zstd.rst:517 -msgid "" -"Return the tuple of int bounds, ``(lower, upper)``, of a compression " -"parameter. This method should be called on the attribute you wish to " -"retrieve the bounds of. For example, to get the valid values for :attr:`~." -"compression_level`, one may check the result of ``CompressionParameter." -"compression_level.bounds()``." -msgstr "" - -#: ../../library/compression.zstd.rst:523 -#: ../../library/compression.zstd.rst:751 -msgid "Both the lower and upper bounds are inclusive." -msgstr "" - -#: ../../library/compression.zstd.rst:527 -msgid "" -"A high-level means of setting other compression parameters that affect the " -"speed and ratio of compressing data." -msgstr "" - -#: ../../library/compression.zstd.rst:530 -msgid "" -"Regular compression levels are greater than ``0``. Values greater than " -"``20`` are considered \"ultra\" compression and require more memory than " -"other levels. Negative values can be used to trade off faster compression " -"for worse compression ratios." -msgstr "" - -#: ../../library/compression.zstd.rst:535 -msgid "Setting the level to zero uses :attr:`COMPRESSION_LEVEL_DEFAULT`." -msgstr "" - -#: ../../library/compression.zstd.rst:539 -msgid "" -"Maximum allowed back-reference distance the compressor can use when " -"compressing data, expressed as power of two, ``1 << window_log`` bytes. This " -"parameter greatly influences the memory usage of compression. Higher values " -"require more memory but gain better compression values." -msgstr "" - -#: ../../library/compression.zstd.rst:544 -#: ../../library/compression.zstd.rst:553 -#: ../../library/compression.zstd.rst:564 -#: ../../library/compression.zstd.rst:572 -#: ../../library/compression.zstd.rst:583 -#: ../../library/compression.zstd.rst:598 -#: ../../library/compression.zstd.rst:629 -#: ../../library/compression.zstd.rst:636 -#: ../../library/compression.zstd.rst:644 -#: ../../library/compression.zstd.rst:652 -#: ../../library/compression.zstd.rst:711 -#: ../../library/compression.zstd.rst:760 -msgid "A value of zero causes the value to be selected automatically." -msgstr "" - -#: ../../library/compression.zstd.rst:548 -msgid "" -"Size of the initial probe table, as a power of two. The resulting memory " -"usage is ``1 << (hash_log+2)`` bytes. Larger tables improve compression " -"ratio of strategies <= :attr:`~Strategy.dfast`, and improve compression " -"speed of strategies > :attr:`~Strategy.dfast`." -msgstr "" - -#: ../../library/compression.zstd.rst:557 -msgid "" -"Size of the multi-probe search table, as a power of two. The resulting " -"memory usage is ``1 << (chain_log+2)`` bytes. Larger tables result in better " -"and slower compression. This parameter has no effect for the :attr:" -"`~Strategy.fast` strategy. It's still useful when using :attr:`~Strategy." -"dfast` strategy, in which case it defines a secondary probe table." -msgstr "" - -#: ../../library/compression.zstd.rst:568 -msgid "" -"Number of search attempts, as a power of two. More attempts result in better " -"and slower compression. This parameter is useless for :attr:`~Strategy.fast` " -"and :attr:`~Strategy.dfast` strategies." -msgstr "" - -#: ../../library/compression.zstd.rst:576 -msgid "" -"Minimum size of searched matches. Larger values increase compression and " -"decompression speed, but decrease ratio. Note that Zstandard can still find " -"matches of smaller size, it just tweaks its search algorithm to look for " -"this size and larger. For all strategies < :attr:`~Strategy.btopt`, the " -"effective minimum is ``4``; for all strategies > :attr:`~Strategy.fast`, the " -"effective maximum is ``6``." -msgstr "" - -#: ../../library/compression.zstd.rst:587 -msgid "The impact of this field depends on the selected :class:`Strategy`." -msgstr "" - -#: ../../library/compression.zstd.rst:589 -msgid "" -"For strategies :attr:`~Strategy.btopt`, :attr:`~Strategy.btultra` and :attr:" -"`~Strategy.btultra2`, the value is the length of a match considered \"good " -"enough\" to stop searching. Larger values make compression ratios better, " -"but compresses slower." -msgstr "" - -#: ../../library/compression.zstd.rst:594 -msgid "" -"For strategy :attr:`~Strategy.fast`, it is the distance between match " -"sampling. Larger values make compression faster, but with a worse " -"compression ratio." -msgstr "" - -#: ../../library/compression.zstd.rst:602 -msgid "" -"The higher the value of selected strategy, the more complex the compression " -"technique used by zstd, resulting in higher compression ratios but slower " -"compression." -msgstr "" - -#: ../../library/compression.zstd.rst:606 -msgid ":class:`Strategy`" -msgstr ":class:`Strategy`" - -#: ../../library/compression.zstd.rst:610 -msgid "" -"Long distance matching can be used to improve compression for large inputs " -"by finding large matches at greater distances. It increases memory usage and " -"window size." -msgstr "" - -#: ../../library/compression.zstd.rst:614 -msgid "" -"``True`` or ``1`` enable long distance matching while ``False`` or ``0`` " -"disable it." -msgstr "" - -#: ../../library/compression.zstd.rst:617 -msgid "" -"Enabling this parameter increases default :attr:`~CompressionParameter." -"window_log` to 128 MiB except when expressly set to a different value. This " -"setting is enabled by default if :attr:`!window_log` >= 128 MiB and the " -"compression strategy >= :attr:`~Strategy.btopt` (compression level 16+)." -msgstr "" - -#: ../../library/compression.zstd.rst:625 -msgid "" -"Size of the table for long distance matching, as a power of two. Larger " -"values increase memory usage and compression ratio, but decrease compression " -"speed." -msgstr "" - -#: ../../library/compression.zstd.rst:633 -msgid "" -"Minimum match size for long distance matcher. Larger or too small values can " -"often decrease the compression ratio." -msgstr "" - -#: ../../library/compression.zstd.rst:640 -msgid "" -"Log size of each bucket in the long distance matcher hash table for " -"collision resolution. Larger values improve collision resolution but " -"decrease compression speed." -msgstr "" - -#: ../../library/compression.zstd.rst:648 -msgid "" -"Frequency of inserting/looking up entries into the long distance matcher " -"hash table. Larger values improve compression speed. Deviating far from the " -"default value will likely result in a compression ratio decrease." -msgstr "" - -#: ../../library/compression.zstd.rst:656 -msgid "" -"Write the size of the data to be compressed into the Zstandard frame header " -"when known prior to compressing." -msgstr "" - -#: ../../library/compression.zstd.rst:659 -msgid "This flag only takes effect under the following scenarios:" -msgstr "" - -#: ../../library/compression.zstd.rst:661 -msgid "Calling :func:`compress` for one-shot compression" -msgstr "" - -#: ../../library/compression.zstd.rst:662 -msgid "" -"Providing all of the data to be compressed in the frame in a single :meth:" -"`ZstdCompressor.compress` call, with the :attr:`ZstdCompressor.FLUSH_FRAME` " -"mode." -msgstr "" - -#: ../../library/compression.zstd.rst:665 -msgid "" -"Calling :meth:`ZstdCompressor.set_pledged_input_size` with the exact amount " -"of data that will be provided to the compressor prior to any calls to :meth:" -"`ZstdCompressor.compress` for the current frame. :meth:`!ZstdCompressor." -"set_pledged_input_size` must be called for each new frame." -msgstr "" - -#: ../../library/compression.zstd.rst:671 -msgid "" -"All other compression calls may not write the size information into the " -"frame header." -msgstr "" - -#: ../../library/compression.zstd.rst:674 -msgid "" -"``True`` or ``1`` enable the content size flag while ``False`` or ``0`` " -"disable it." -msgstr "" - -#: ../../library/compression.zstd.rst:679 -msgid "" -"A four-byte checksum using XXHash64 of the uncompressed content is written " -"at the end of each frame. Zstandard's decompression code verifies the " -"checksum. If there is a mismatch a :class:`ZstdError` exception is raised." -msgstr "" - -#: ../../library/compression.zstd.rst:684 -msgid "" -"``True`` or ``1`` enable checksum generation while ``False`` or ``0`` " -"disable it." -msgstr "" - -#: ../../library/compression.zstd.rst:689 -msgid "" -"When compressing with a :class:`ZstdDict`, the dictionary's ID is written " -"into the frame header." -msgstr "" - -#: ../../library/compression.zstd.rst:692 -msgid "" -"``True`` or ``1`` enable storing the dictionary ID while ``False`` or ``0`` " -"disable it." -msgstr "" - -#: ../../library/compression.zstd.rst:697 -msgid "" -"Select how many threads will be spawned to compress in parallel. When :attr:" -"`!nb_workers` > 0, enables multi-threaded compression, a value of ``1`` " -"means \"one-thread multi-threaded mode\". More workers improve speed, but " -"also increase memory usage and slightly reduce compression ratio." -msgstr "" - -#: ../../library/compression.zstd.rst:702 -msgid "A value of zero disables multi-threading." -msgstr "" - -#: ../../library/compression.zstd.rst:706 -msgid "" -"Size of a compression job, in bytes. This value is enforced only when :attr:" -"`~CompressionParameter.nb_workers` >= 1. Each compression job is completed " -"in parallel, so this value can indirectly impact the number of active " -"threads." -msgstr "" - -#: ../../library/compression.zstd.rst:715 -msgid "" -"Sets how much data is reloaded from previous jobs (threads) for new jobs to " -"be used by the look behind window during compression. This value is only " -"used when :attr:`~CompressionParameter.nb_workers` >= 1. Acceptable values " -"vary from 0 to 9." -msgstr "" - -#: ../../library/compression.zstd.rst:720 -msgid "0 means dynamically set the overlap amount" -msgstr "" - -#: ../../library/compression.zstd.rst:721 -msgid "1 means no overlap" -msgstr "" - -#: ../../library/compression.zstd.rst:722 -msgid "9 means use a full window size from the previous job" -msgstr "" - -#: ../../library/compression.zstd.rst:724 -msgid "" -"Each increment halves/doubles the overlap size. \"8\" means an overlap of " -"``window_size/2``, \"7\" means an overlap of ``window_size/4``, etc." -msgstr "" - -#: ../../library/compression.zstd.rst:729 -msgid "" -"An :class:`~enum.IntEnum` containing the advanced decompression parameter " -"keys that can be used when decompressing data. Parameters are optional; any " -"omitted parameter will have it's value selected automatically." -msgstr "" - -#: ../../library/compression.zstd.rst:736 -msgid "Example setting the :attr:`~.window_log_max` to the maximum size::" -msgstr "" - -#: ../../library/compression.zstd.rst:738 -msgid "" -"data = compress(b'Some very long buffer of bytes...')\n" -"\n" -"_lower, upper = DecompressionParameter.window_log_max.bounds()\n" -"\n" -"options = {DecompressionParameter.window_log_max: upper}\n" -"decompress(data, options=options)" -msgstr "" -"data = compress(b'Some very long buffer of bytes...')\n" -"\n" -"_lower, upper = DecompressionParameter.window_log_max.bounds()\n" -"\n" -"options = {DecompressionParameter.window_log_max: upper}\n" -"decompress(data, options=options)" - -#: ../../library/compression.zstd.rst:747 -msgid "" -"Return the tuple of int bounds, ``(lower, upper)``, of a decompression " -"parameter. This method should be called on the attribute you wish to " -"retrieve the bounds of." -msgstr "" - -#: ../../library/compression.zstd.rst:755 -msgid "" -"The base-two logarithm of the maximum size of the window used during " -"decompression. This can be useful to limit the amount of memory used when " -"decompressing data. A larger maximum window size leads to faster " -"decompression." -msgstr "" - -#: ../../library/compression.zstd.rst:765 -msgid "" -"An :class:`~enum.IntEnum` containing strategies for compression. Higher-" -"numbered strategies correspond to more complex and slower compression." -msgstr "" - -#: ../../library/compression.zstd.rst:771 -msgid "" -"The values of attributes of :class:`!Strategy` are not necessarily stable " -"across zstd versions. Only the ordering of the attributes may be relied " -"upon. The attributes are listed below in order." -msgstr "" - -#: ../../library/compression.zstd.rst:775 -msgid "The following strategies are available:" -msgstr "" - -#: ../../library/compression.zstd.rst:797 -msgid "Miscellaneous" -msgstr "" - -#: ../../library/compression.zstd.rst:801 -msgid "" -"Retrieve a :class:`FrameInfo` object containing metadata about a Zstandard " -"frame. Frames contain metadata related to the compressed data they hold." -msgstr "" - -#: ../../library/compression.zstd.rst:807 -msgid "Metadata related to a Zstandard frame." -msgstr "" - -#: ../../library/compression.zstd.rst:811 -msgid "The size of the decompressed contents of the frame." -msgstr "" - -#: ../../library/compression.zstd.rst:815 -msgid "" -"An integer representing the Zstandard dictionary ID needed for decompressing " -"the frame. ``0`` means the dictionary ID was not recorded in the frame " -"header. This may mean that a Zstandard dictionary is not needed, or that the " -"ID of a required dictionary was not recorded." -msgstr "" - -#: ../../library/compression.zstd.rst:823 -msgid "The default compression level for Zstandard: ``3``." -msgstr "" - -#: ../../library/compression.zstd.rst:828 -msgid "" -"Version number of the runtime zstd library as a tuple of integers (major, " -"minor, release)." -msgstr "" - -#: ../../library/compression.zstd.rst:833 -msgid "Examples" -msgstr "範例" - -#: ../../library/compression.zstd.rst:835 -msgid "Reading in a compressed file:" -msgstr "讀取壓縮檔案：" - -#: ../../library/compression.zstd.rst:837 -msgid "" -"from compression import zstd\n" -"\n" -"with zstd.open(\"file.zst\") as f:\n" -" file_content = f.read()" -msgstr "" -"from compression import zstd\n" -"\n" -"with zstd.open(\"file.zst\") as f:\n" -" file_content = f.read()" - -#: ../../library/compression.zstd.rst:844 -msgid "Creating a compressed file:" -msgstr "" - -#: ../../library/compression.zstd.rst:846 -msgid "" -"from compression import zstd\n" -"\n" -"data = b\"Insert Data Here\"\n" -"with zstd.open(\"file.zst\", \"w\") as f:\n" -" f.write(data)" -msgstr "" -"from compression import zstd\n" -"\n" -"data = b\"Insert Data Here\"\n" -"with zstd.open(\"file.zst\", \"w\") as f:\n" -" f.write(data)" - -#: ../../library/compression.zstd.rst:854 -msgid "Compressing data in memory:" -msgstr "" - -#: ../../library/compression.zstd.rst:856 -msgid "" -"from compression import zstd\n" -"\n" -"data_in = b\"Insert Data Here\"\n" -"data_out = zstd.compress(data_in)" -msgstr "" -"from compression import zstd\n" -"\n" -"data_in = b\"Insert Data Here\"\n" -"data_out = zstd.compress(data_in)" - -#: ../../library/compression.zstd.rst:863 -msgid "Incremental compression:" -msgstr "" - -#: ../../library/compression.zstd.rst:865 -msgid "" -"from compression import zstd\n" -"\n" -"comp = zstd.ZstdCompressor()\n" -"out1 = comp.compress(b\"Some data\\n\")\n" -"out2 = comp.compress(b\"Another piece of data\\n\")\n" -"out3 = comp.compress(b\"Even more data\\n\")\n" -"out4 = comp.flush()\n" -"# Concatenate all the partial results:\n" -"result = b\"\".join([out1, out2, out3, out4])" -msgstr "" -"from compression import zstd\n" -"\n" -"comp = zstd.ZstdCompressor()\n" -"out1 = comp.compress(b\"Some data\\n\")\n" -"out2 = comp.compress(b\"Another piece of data\\n\")\n" -"out3 = comp.compress(b\"Even more data\\n\")\n" -"out4 = comp.flush()\n" -"# Concatenate all the partial results:\n" -"result = b\"\".join([out1, out2, out3, out4])" - -#: ../../library/compression.zstd.rst:877 -msgid "Writing compressed data to an already-open file:" -msgstr "" - -#: ../../library/compression.zstd.rst:879 -msgid "" -"from compression import zstd\n" -"\n" -"with open(\"myfile\", \"wb\") as f:\n" -" f.write(b\"This data will not be compressed\\n\")\n" -" with zstd.open(f, \"w\") as zstf:\n" -" zstf.write(b\"This *will* be compressed\\n\")\n" -" f.write(b\"Not compressed\\n\")" -msgstr "" -"from compression import zstd\n" -"\n" -"with open(\"myfile\", \"wb\") as f:\n" -" f.write(b\"This data will not be compressed\\n\")\n" -" with zstd.open(f, \"w\") as zstf:\n" -" zstf.write(b\"This *will* be compressed\\n\")\n" -" f.write(b\"Not compressed\\n\")" - -#: ../../library/compression.zstd.rst:889 -msgid "Creating a compressed file using compression parameters:" -msgstr "" - -#: ../../library/compression.zstd.rst:891 -msgid "" -"from compression import zstd\n" -"\n" -"options = {\n" -" zstd.CompressionParameter.checksum_flag: 1\n" -"}\n" -"with zstd.open(\"file.zst\", \"w\", options=options) as f:\n" -" f.write(b\"Mind if I squeeze in?\")" -msgstr "" -"from compression import zstd\n" -"\n" -"options = {\n" -" zstd.CompressionParameter.checksum_flag: 1\n" -"}\n" -"with zstd.open(\"file.zst\", \"w\", options=options) as f:\n" -" f.write(b\"Mind if I squeeze in?\")" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# FIRST AUTHOR , YEAR. +# +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-01-06 00:19+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"Language: zh_TW\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../library/compression.zstd.rst:2 +msgid "" +":mod:`!compression.zstd` --- Compression compatible with the Zstandard format" +msgstr ":mod:`!compression.zstd` --- 與 Zstandard 格式相容的壓縮" + +#: ../../library/compression.zstd.rst:10 +msgid "**Source code:** :source:`Lib/compression/zstd/__init__.py`" +msgstr "**原始碼：**\\ :source:`Lib/compression/zstd/__init__.py`" + +#: ../../library/compression.zstd.rst:14 +msgid "" +"This module provides classes and functions for compressing and decompressing " +"data using the Zstandard (or *zstd*) compression algorithm. The `zstd manual " +"`__ describes " +"Zstandard as \"a fast lossless compression algorithm, targeting real-time " +"compression scenarios at zlib-level and better compression ratios.\" Also " +"included is a file interface that supports reading and writing the contents " +"of ``.zst`` files created by the :program:`zstd` utility, as well as raw " +"zstd compressed streams." +msgstr "" + +#: ../../library/compression.zstd.rst:23 +msgid "The :mod:`!compression.zstd` module contains:" +msgstr ":mod:`!compression.zstd` 模組包含：" + +#: ../../library/compression.zstd.rst:25 +msgid "" +"The :func:`.open` function and :class:`ZstdFile` class for reading and " +"writing compressed files." +msgstr "" + +#: ../../library/compression.zstd.rst:27 +msgid "" +"The :class:`ZstdCompressor` and :class:`ZstdDecompressor` classes for " +"incremental (de)compression." +msgstr "" + +#: ../../library/compression.zstd.rst:29 +msgid "" +"The :func:`compress` and :func:`decompress` functions for one-shot " +"(de)compression." +msgstr "" + +#: ../../library/compression.zstd.rst:31 +msgid "" +"The :func:`train_dict` and :func:`finalize_dict` functions and the :class:" +"`ZstdDict` class to train and manage Zstandard dictionaries." +msgstr "" + +#: ../../library/compression.zstd.rst:33 +msgid "" +"The :class:`CompressionParameter`, :class:`DecompressionParameter`, and :" +"class:`Strategy` classes for setting advanced (de)compression parameters." +msgstr "" + +#: ../../includes/optional-module.rst:1 +msgid "" +"This is an :term:`optional module`. If it is missing from your copy of " +"CPython, look for documentation from your distributor (that is, whoever " +"provided Python to you). If you are the distributor, see :ref:`optional-" +"module-requirements`." +msgstr "" + +#: ../../library/compression.zstd.rst:40 +msgid "Exceptions" +msgstr "例外" + +#: ../../library/compression.zstd.rst:44 +msgid "" +"This exception is raised when an error occurs during compression or " +"decompression, or while initializing the (de)compressor state." +msgstr "" + +#: ../../library/compression.zstd.rst:49 +msgid "Reading and writing compressed files" +msgstr "" + +#: ../../library/compression.zstd.rst:54 +msgid "" +"Open a Zstandard-compressed file in binary or text mode, returning a :term:" +"`file object`." +msgstr "" + +#: ../../library/compression.zstd.rst:57 +msgid "" +"The *file* argument can be either a file name (given as a :class:`str`, :" +"class:`bytes` or :term:`path-like ` object), in which case " +"the named file is opened, or it can be an existing file object to read from " +"or write to." +msgstr "" + +#: ../../library/compression.zstd.rst:62 +msgid "" +"The mode argument can be either ``'rb'`` for reading (default), ``'wb'`` for " +"overwriting, ``'ab'`` for appending, or ``'xb'`` for exclusive creation. " +"These can equivalently be given as ``'r'``, ``'w'``, ``'a'``, and ``'x'`` " +"respectively. You may also open in text mode with ``'rt'``, ``'wt'``, " +"``'at'``, and ``'xt'`` respectively." +msgstr "" + +#: ../../library/compression.zstd.rst:68 ../../library/compression.zstd.rst:112 +msgid "" +"When reading, the *options* argument can be a dictionary providing advanced " +"decompression parameters; see :class:`DecompressionParameter` for detailed " +"information about supported parameters. The *zstd_dict* argument is a :class:" +"`ZstdDict` instance to be used during decompression. When reading, if the " +"*level* argument is not None, a :exc:`!TypeError` will be raised." +msgstr "" + +#: ../../library/compression.zstd.rst:75 +msgid "" +"When writing, the *options* argument can be a dictionary providing advanced " +"compression parameters; see :class:`CompressionParameter` for detailed " +"information about supported parameters. The *level* argument is the " +"compression level to use when writing compressed data. Only one of *level* " +"or *options* may be non-None. The *zstd_dict* argument is a :class:" +"`ZstdDict` instance to be used during compression." +msgstr "" + +#: ../../library/compression.zstd.rst:83 +msgid "" +"In binary mode, this function is equivalent to the :class:`ZstdFile` " +"constructor: ``ZstdFile(file, mode, ...)``. In this case, the *encoding*, " +"*errors*, and *newline* parameters must not be provided." +msgstr "" + +#: ../../library/compression.zstd.rst:87 +msgid "" +"In text mode, a :class:`ZstdFile` object is created, and wrapped in an :" +"class:`io.TextIOWrapper` instance with the specified encoding, error " +"handling behavior, and line endings." +msgstr "" + +#: ../../library/compression.zstd.rst:95 +msgid "Open a Zstandard-compressed file in binary mode." +msgstr "" + +#: ../../library/compression.zstd.rst:97 +msgid "" +"A :class:`ZstdFile` can wrap an already-open :term:`file object`, or operate " +"directly on a named file. The *file* argument specifies either the file " +"object to wrap, or the name of the file to open (as a :class:`str`, :class:" +"`bytes` or :term:`path-like ` object). If wrapping an " +"existing file object, the wrapped file will not be closed when the :class:" +"`ZstdFile` is closed." +msgstr "" + +#: ../../library/compression.zstd.rst:104 +msgid "" +"The *mode* argument can be either ``'rb'`` for reading (default), ``'wb'`` " +"for overwriting, ``'xb'`` for exclusive creation, or ``'ab'`` for appending. " +"These can equivalently be given as ``'r'``, ``'w'``, ``'x'`` and ``'a'`` " +"respectively." +msgstr "" + +#: ../../library/compression.zstd.rst:109 +msgid "" +"If *file* is a file object (rather than an actual file name), a mode of " +"``'w'`` does not truncate the file, and is instead equivalent to ``'a'``." +msgstr "" + +#: ../../library/compression.zstd.rst:119 +msgid "" +"When writing, the *options* argument can be a dictionary providing advanced " +"compression parameters; see :class:`CompressionParameter` for detailed " +"information about supported parameters. The *level* argument is the " +"compression level to use when writing compressed data. Only one of *level* " +"or *options* may be passed. The *zstd_dict* argument is a :class:`ZstdDict` " +"instance to be used during compression." +msgstr "" + +#: ../../library/compression.zstd.rst:127 +msgid "" +":class:`!ZstdFile` supports all the members specified by :class:`io." +"BufferedIOBase`, except for :meth:`~io.BufferedIOBase.detach` and :meth:`~io." +"IOBase.truncate`. Iteration and the :keyword:`with` statement are supported." +msgstr "" + +#: ../../library/compression.zstd.rst:132 +msgid "The following method and attributes are also provided:" +msgstr "" + +#: ../../library/compression.zstd.rst:136 +msgid "" +"Return buffered data without advancing the file position. At least one byte " +"of data will be returned, unless EOF has been reached. The exact number of " +"bytes returned is unspecified (the *size* argument is ignored)." +msgstr "" + +#: ../../library/compression.zstd.rst:140 +msgid "" +"While calling :meth:`peek` does not change the file position of the :class:" +"`ZstdFile`, it may change the position of the underlying file object (for " +"example, if the :class:`ZstdFile` was constructed by passing a file object " +"for *file*)." +msgstr "" + +#: ../../library/compression.zstd.rst:147 +msgid "``'rb'`` for reading and ``'wb'`` for writing." +msgstr "" + +#: ../../library/compression.zstd.rst:151 +msgid "" +"The name of the Zstandard file. Equivalent to the :attr:`~io.FileIO.name` " +"attribute of the underlying :term:`file object`." +msgstr "" + +#: ../../library/compression.zstd.rst:156 +msgid "Compressing and decompressing data in memory" +msgstr "" + +#: ../../library/compression.zstd.rst:160 +msgid "" +"Compress *data* (a :term:`bytes-like object`), returning the compressed data " +"as a :class:`bytes` object." +msgstr "" + +#: ../../library/compression.zstd.rst:163 +#: ../../library/compression.zstd.rst:207 +msgid "" +"The *level* argument is an integer controlling the level of compression. " +"*level* is an alternative to setting :attr:`CompressionParameter." +"compression_level` in *options*. Use :meth:`~CompressionParameter.bounds` " +"on :attr:`~CompressionParameter.compression_level` to get the values that " +"can be passed for *level*. If advanced compression options are needed, the " +"*level* argument must be omitted and in the *options* dictionary the :attr:`!" +"CompressionParameter.compression_level` parameter should be set." +msgstr "" + +#: ../../library/compression.zstd.rst:172 +#: ../../library/compression.zstd.rst:216 +msgid "" +"The *options* argument is a Python dictionary containing advanced " +"compression parameters. The valid keys and values for compression parameters " +"are documented as part of the :class:`CompressionParameter` documentation." +msgstr "" + +#: ../../library/compression.zstd.rst:176 +msgid "" +"The *zstd_dict* argument is an instance of :class:`ZstdDict` containing " +"trained data to improve compression efficiency. The function :func:" +"`train_dict` can be used to generate a Zstandard dictionary." +msgstr "" + +#: ../../library/compression.zstd.rst:183 +msgid "" +"Decompress *data* (a :term:`bytes-like object`), returning the uncompressed " +"data as a :class:`bytes` object." +msgstr "" + +#: ../../library/compression.zstd.rst:186 +#: ../../library/compression.zstd.rst:308 +msgid "" +"The *options* argument is a Python dictionary containing advanced " +"decompression parameters. The valid keys and values for compression " +"parameters are documented as part of the :class:`DecompressionParameter` " +"documentation." +msgstr "" + +#: ../../library/compression.zstd.rst:191 +#: ../../library/compression.zstd.rst:313 +msgid "" +"The *zstd_dict* argument is an instance of :class:`ZstdDict` containing " +"trained data used during compression. This must be the same Zstandard " +"dictionary used during compression." +msgstr "" + +#: ../../library/compression.zstd.rst:195 +msgid "" +"If *data* is the concatenation of multiple distinct compressed frames, " +"decompress all of these frames, and return the concatenation of the results." +msgstr "" + +#: ../../library/compression.zstd.rst:201 +msgid "" +"Create a compressor object, which can be used to compress data incrementally." +msgstr "" + +#: ../../library/compression.zstd.rst:204 +msgid "" +"For a more convenient way of compressing a single chunk of data, see the " +"module-level function :func:`compress`." +msgstr "" + +#: ../../library/compression.zstd.rst:220 +msgid "" +"The *zstd_dict* argument is an optional instance of :class:`ZstdDict` " +"containing trained data to improve compression efficiency. The function :" +"func:`train_dict` can be used to generate a Zstandard dictionary." +msgstr "" + +#: ../../library/compression.zstd.rst:227 +msgid "" +"Compress *data* (a :term:`bytes-like object`), returning a :class:`bytes` " +"object with compressed data if possible, or otherwise an empty :class:`!" +"bytes` object. Some of *data* may be buffered internally, for use in later " +"calls to :meth:`!compress` and :meth:`~.flush`. The returned data should be " +"concatenated with the output of any previous calls to :meth:`~.compress`." +msgstr "" + +#: ../../library/compression.zstd.rst:234 +msgid "" +"The *mode* argument is a :class:`ZstdCompressor` attribute, either :attr:`~." +"CONTINUE`, :attr:`~.FLUSH_BLOCK`, or :attr:`~.FLUSH_FRAME`." +msgstr "" + +#: ../../library/compression.zstd.rst:238 +msgid "" +"When all data has been provided to the compressor, call the :meth:`~.flush` " +"method to finish the compression process. If :meth:`~.compress` is called " +"with *mode* set to :attr:`~.FLUSH_FRAME`, :meth:`~.flush` should not be " +"called, as it would write out a new empty frame." +msgstr "" + +#: ../../library/compression.zstd.rst:246 +msgid "" +"Finish the compression process, returning a :class:`bytes` object containing " +"any data stored in the compressor's internal buffers." +msgstr "" + +#: ../../library/compression.zstd.rst:249 +msgid "" +"The *mode* argument is a :class:`ZstdCompressor` attribute, either :attr:`~." +"FLUSH_BLOCK`, or :attr:`~.FLUSH_FRAME`." +msgstr "" + +#: ../../library/compression.zstd.rst:254 +msgid "" +"Specify the amount of uncompressed data *size* that will be provided for the " +"next frame. *size* will be written into the frame header of the next frame " +"unless :attr:`CompressionParameter.content_size_flag` is ``False`` or ``0``. " +"A size of ``0`` means that the frame is empty. If *size* is ``None``, the " +"frame header will omit the frame size. Frames that include the uncompressed " +"data size require less memory to decompress, especially at higher " +"compression levels." +msgstr "" + +#: ../../library/compression.zstd.rst:262 +msgid "" +"If :attr:`last_mode` is not :attr:`FLUSH_FRAME`, a :exc:`ValueError` is " +"raised as the compressor is not at the start of a frame. If the pledged size " +"does not match the actual size of data provided to :meth:`.compress`, future " +"calls to :meth:`!compress` or :meth:`flush` may raise :exc:`ZstdError` and " +"the last chunk of data may be lost." +msgstr "" + +#: ../../library/compression.zstd.rst:269 +msgid "" +"After :meth:`flush` or :meth:`.compress` are called with mode :attr:" +"`FLUSH_FRAME`, the next frame will not include the frame size into the " +"header unless :meth:`!set_pledged_input_size` is called again." +msgstr "" + +#: ../../library/compression.zstd.rst:275 +msgid "" +"Collect more data for compression, which may or may not generate output " +"immediately. This mode optimizes the compression ratio by maximizing the " +"amount of data per block and frame." +msgstr "" + +#: ../../library/compression.zstd.rst:281 +msgid "" +"Complete and write a block to the data stream. The data returned so far can " +"be immediately decompressed. Past data can still be referenced in future " +"blocks generated by calls to :meth:`~.compress`, improving compression." +msgstr "" + +#: ../../library/compression.zstd.rst:288 +msgid "" +"Complete and write out a frame. Future data provided to :meth:`~.compress` " +"will be written into a new frame and *cannot* reference past data." +msgstr "" + +#: ../../library/compression.zstd.rst:294 +msgid "" +"The last mode passed to either :meth:`~.compress` or :meth:`~.flush`. The " +"value can be one of :attr:`~.CONTINUE`, :attr:`~.FLUSH_BLOCK`, or :attr:`~." +"FLUSH_FRAME`. The initial value is :attr:`~.FLUSH_FRAME`, signifying that " +"the compressor is at the start of a new frame." +msgstr "" + +#: ../../library/compression.zstd.rst:302 +msgid "" +"Create a decompressor object, which can be used to decompress data " +"incrementally." +msgstr "" + +#: ../../library/compression.zstd.rst:305 +msgid "" +"For a more convenient way of decompressing an entire compressed stream at " +"once, see the module-level function :func:`decompress`." +msgstr "" + +#: ../../library/compression.zstd.rst:318 +msgid "" +"This class does not transparently handle inputs containing multiple " +"compressed frames, unlike the :func:`decompress` function and :class:" +"`ZstdFile` class. To decompress a multi-frame input, you should use :func:" +"`decompress`, :class:`ZstdFile` if working with a :term:`file object`, or " +"multiple :class:`!ZstdDecompressor` instances." +msgstr "" + +#: ../../library/compression.zstd.rst:326 +msgid "" +"Decompress *data* (a :term:`bytes-like object`), returning uncompressed data " +"as bytes. Some of *data* may be buffered internally, for use in later calls " +"to :meth:`!decompress`. The returned data should be concatenated with the " +"output of any previous calls to :meth:`!decompress`." +msgstr "" + +#: ../../library/compression.zstd.rst:332 +msgid "" +"If *max_length* is non-negative, the method returns at most *max_length* " +"bytes of decompressed data. If this limit is reached and further output can " +"be produced, the :attr:`~.needs_input` attribute will be set to ``False``. " +"In this case, the next call to :meth:`~.decompress` may provide *data* as " +"``b''`` to obtain more of the output." +msgstr "" + +#: ../../library/compression.zstd.rst:339 +msgid "" +"If all of the input data was decompressed and returned (either because this " +"was less than *max_length* bytes, or because *max_length* was negative), " +"the :attr:`~.needs_input` attribute will be set to ``True``." +msgstr "" + +#: ../../library/compression.zstd.rst:344 +msgid "" +"Attempting to decompress data after the end of a frame will raise a :exc:" +"`ZstdError`. Any data found after the end of the frame is ignored and saved " +"in the :attr:`~.unused_data` attribute." +msgstr "" + +#: ../../library/compression.zstd.rst:350 +msgid "``True`` if the end-of-stream marker has been reached." +msgstr "" + +#: ../../library/compression.zstd.rst:354 +msgid "Data found after the end of the compressed stream." +msgstr "" + +#: ../../library/compression.zstd.rst:356 +msgid "Before the end of the stream is reached, this will be ``b''``." +msgstr "" + +#: ../../library/compression.zstd.rst:360 +msgid "" +"``False`` if the :meth:`.decompress` method can provide more decompressed " +"data before requiring new compressed input." +msgstr "" + +#: ../../library/compression.zstd.rst:365 +msgid "Zstandard dictionaries" +msgstr "Zstandard 字典" + +#: ../../library/compression.zstd.rst:370 +msgid "" +"Train a Zstandard dictionary, returning a :class:`ZstdDict` instance. " +"Zstandard dictionaries enable more efficient compression of smaller sizes of " +"data, which is traditionally difficult to compress due to less repetition. " +"If you are compressing multiple similar groups of data (such as similar " +"files), Zstandard dictionaries can improve compression ratios and speed " +"significantly." +msgstr "" + +#: ../../library/compression.zstd.rst:377 +msgid "" +"The *samples* argument (an iterable of :class:`bytes` objects), is the " +"population of samples used to train the Zstandard dictionary." +msgstr "" + +#: ../../library/compression.zstd.rst:380 +msgid "" +"The *dict_size* argument, an integer, is the maximum size (in bytes) the " +"Zstandard dictionary should be. The Zstandard documentation suggests an " +"absolute maximum of no more than 100 KB, but the maximum can often be " +"smaller depending on the data. Larger dictionaries generally slow down " +"compression, but improve compression ratios. Smaller dictionaries lead to " +"faster compression, but reduce the compression ratio." +msgstr "" + +#: ../../library/compression.zstd.rst:390 +msgid "" +"An advanced function for converting a \"raw content\" Zstandard dictionary " +"into a regular Zstandard dictionary. \"Raw content\" dictionaries are a " +"sequence of bytes that do not need to follow the structure of a normal " +"Zstandard dictionary." +msgstr "" + +#: ../../library/compression.zstd.rst:395 +msgid "" +"The *zstd_dict* argument is a :class:`ZstdDict` instance with the :attr:" +"`~ZstdDict.dict_content` containing the raw dictionary contents." +msgstr "" + +#: ../../library/compression.zstd.rst:398 +msgid "" +"The *samples* argument (an iterable of :class:`bytes` objects), contains " +"sample data for generating the Zstandard dictionary." +msgstr "" + +#: ../../library/compression.zstd.rst:401 +msgid "" +"The *dict_size* argument, an integer, is the maximum size (in bytes) the " +"Zstandard dictionary should be. See :func:`train_dict` for suggestions on " +"the maximum dictionary size." +msgstr "" + +#: ../../library/compression.zstd.rst:405 +msgid "" +"The *level* argument (an integer) is the compression level expected to be " +"passed to the compressors using this dictionary. The dictionary information " +"varies for each compression level, so tuning for the proper compression " +"level can make compression more efficient." +msgstr "" + +#: ../../library/compression.zstd.rst:413 +msgid "" +"A wrapper around Zstandard dictionaries. Dictionaries can be used to improve " +"the compression of many small chunks of data. Use :func:`train_dict` if you " +"need to train a new dictionary from sample data." +msgstr "" + +#: ../../library/compression.zstd.rst:417 +msgid "" +"The *dict_content* argument (a :term:`bytes-like object`), is the already " +"trained dictionary information." +msgstr "" + +#: ../../library/compression.zstd.rst:420 +msgid "" +"The *is_raw* argument, a boolean, is an advanced parameter controlling the " +"meaning of *dict_content*. ``True`` means *dict_content* is a \"raw " +"content\" dictionary, without any format restrictions. ``False`` means " +"*dict_content* is an ordinary Zstandard dictionary, created from Zstandard " +"functions, for example, :func:`train_dict` or the external :program:`zstd` " +"CLI." +msgstr "" + +#: ../../library/compression.zstd.rst:426 +msgid "" +"When passing a :class:`!ZstdDict` to a function, the :attr:`!" +"as_digested_dict` and :attr:`!as_undigested_dict` attributes can control how " +"the dictionary is loaded by passing them as the ``zstd_dict`` argument, for " +"example, ``compress(data, zstd_dict=zd.as_digested_dict)``. Digesting a " +"dictionary is a costly operation that occurs when loading a Zstandard " +"dictionary. When making multiple calls to compression or decompression, " +"passing a digested dictionary will reduce the overhead of loading the " +"dictionary." +msgstr "" + +#: ../../library/compression.zstd.rst:435 +msgid "Difference for compression" +msgstr "" + +#: ../../library/compression.zstd.rst:440 +msgid "Digested dictionary" +msgstr "" + +#: ../../library/compression.zstd.rst:441 +msgid "Undigested dictionary" +msgstr "" + +#: ../../library/compression.zstd.rst:442 +msgid "" +"Advanced parameters of the compressor which may be overridden by the " +"dictionary's parameters" +msgstr "" + +#: ../../library/compression.zstd.rst:444 +msgid "" +"``window_log``, ``hash_log``, ``chain_log``, ``search_log``, ``min_match``, " +"``target_length``, ``strategy``, ``enable_long_distance_matching``, " +"``ldm_hash_log``, ``ldm_min_match``, ``ldm_bucket_size_log``, " +"``ldm_hash_rate_log``, and some non-public parameters." +msgstr "" + +#: ../../library/compression.zstd.rst:449 +msgid "None" +msgstr "" + +#: ../../library/compression.zstd.rst:450 +msgid ":class:`!ZstdDict` internally caches the dictionary" +msgstr "" + +#: ../../library/compression.zstd.rst:451 +msgid "" +"Yes. It's faster when loading a digested dictionary again with the same " +"compression level." +msgstr "" + +#: ../../library/compression.zstd.rst:453 +msgid "" +"No. If you wish to load an undigested dictionary multiple times, consider " +"reusing a compressor object." +msgstr "" + +#: ../../library/compression.zstd.rst:456 +msgid "" +"If passing a :class:`!ZstdDict` without any attribute, an undigested " +"dictionary is passed by default when compressing and a digested dictionary " +"is generated if necessary and passed by default when decompressing." +msgstr "" + +#: ../../library/compression.zstd.rst:462 +msgid "" +"The content of the Zstandard dictionary, a ``bytes`` object. It's the same " +"as the *dict_content* argument in the ``__init__`` method. It can be used " +"with other programs, such as the ``zstd`` CLI program." +msgstr "" + +#: ../../library/compression.zstd.rst:468 +msgid "Identifier of the Zstandard dictionary, a non-negative int value." +msgstr "" + +#: ../../library/compression.zstd.rst:470 +msgid "" +"Non-zero means the dictionary is ordinary, created by Zstandard functions " +"and following the Zstandard format." +msgstr "" + +#: ../../library/compression.zstd.rst:473 +msgid "" +"``0`` means a \"raw content\" dictionary, free of any format restriction, " +"used for advanced users." +msgstr "" + +#: ../../library/compression.zstd.rst:478 +msgid "" +"The meaning of ``0`` for :attr:`!ZstdDict.dict_id` is different from the " +"``dictionary_id`` attribute to the :func:`get_frame_info` function." +msgstr "" + +#: ../../library/compression.zstd.rst:484 +msgid "Load as a digested dictionary." +msgstr "" + +#: ../../library/compression.zstd.rst:488 +msgid "Load as an undigested dictionary." +msgstr "" + +#: ../../library/compression.zstd.rst:492 +msgid "Advanced parameter control" +msgstr "" + +#: ../../library/compression.zstd.rst:496 +msgid "" +"An :class:`~enum.IntEnum` containing the advanced compression parameter keys " +"that can be used when compressing data." +msgstr "" + +#: ../../library/compression.zstd.rst:499 +#: ../../library/compression.zstd.rst:733 +msgid "" +"The :meth:`~.bounds` method can be used on any attribute to get the valid " +"values for that parameter." +msgstr "" + +#: ../../library/compression.zstd.rst:502 +msgid "" +"Parameters are optional; any omitted parameter will have it's value selected " +"automatically." +msgstr "" + +#: ../../library/compression.zstd.rst:505 +msgid "" +"Example getting the lower and upper bound of :attr:`~.compression_level`::" +msgstr "" + +#: ../../library/compression.zstd.rst:507 +msgid "lower, upper = CompressionParameter.compression_level.bounds()" +msgstr "" + +#: ../../library/compression.zstd.rst:509 +msgid "Example setting the :attr:`~.window_log` to the maximum size::" +msgstr "" + +#: ../../library/compression.zstd.rst:511 +msgid "" +"_lower, upper = CompressionParameter.window_log.bounds()\n" +"options = {CompressionParameter.window_log: upper}\n" +"compress(b'venezuelan beaver cheese', options=options)" +msgstr "" + +#: ../../library/compression.zstd.rst:517 +msgid "" +"Return the tuple of int bounds, ``(lower, upper)``, of a compression " +"parameter. This method should be called on the attribute you wish to " +"retrieve the bounds of. For example, to get the valid values for :attr:`~." +"compression_level`, one may check the result of ``CompressionParameter." +"compression_level.bounds()``." +msgstr "" + +#: ../../library/compression.zstd.rst:523 +#: ../../library/compression.zstd.rst:751 +msgid "Both the lower and upper bounds are inclusive." +msgstr "" + +#: ../../library/compression.zstd.rst:527 +msgid "" +"A high-level means of setting other compression parameters that affect the " +"speed and ratio of compressing data." +msgstr "" + +#: ../../library/compression.zstd.rst:530 +msgid "" +"Regular compression levels are greater than ``0``. Values greater than " +"``20`` are considered \"ultra\" compression and require more memory than " +"other levels. Negative values can be used to trade off faster compression " +"for worse compression ratios." +msgstr "" + +#: ../../library/compression.zstd.rst:535 +msgid "Setting the level to zero uses :attr:`COMPRESSION_LEVEL_DEFAULT`." +msgstr "" + +#: ../../library/compression.zstd.rst:539 +msgid "" +"Maximum allowed back-reference distance the compressor can use when " +"compressing data, expressed as power of two, ``1 << window_log`` bytes. This " +"parameter greatly influences the memory usage of compression. Higher values " +"require more memory but gain better compression values." +msgstr "" + +#: ../../library/compression.zstd.rst:544 +#: ../../library/compression.zstd.rst:553 +#: ../../library/compression.zstd.rst:564 +#: ../../library/compression.zstd.rst:572 +#: ../../library/compression.zstd.rst:583 +#: ../../library/compression.zstd.rst:598 +#: ../../library/compression.zstd.rst:629 +#: ../../library/compression.zstd.rst:636 +#: ../../library/compression.zstd.rst:644 +#: ../../library/compression.zstd.rst:652 +#: ../../library/compression.zstd.rst:711 +#: ../../library/compression.zstd.rst:760 +msgid "A value of zero causes the value to be selected automatically." +msgstr "" + +#: ../../library/compression.zstd.rst:548 +msgid "" +"Size of the initial probe table, as a power of two. The resulting memory " +"usage is ``1 << (hash_log+2)`` bytes. Larger tables improve compression " +"ratio of strategies <= :attr:`~Strategy.dfast`, and improve compression " +"speed of strategies > :attr:`~Strategy.dfast`." +msgstr "" + +#: ../../library/compression.zstd.rst:557 +msgid "" +"Size of the multi-probe search table, as a power of two. The resulting " +"memory usage is ``1 << (chain_log+2)`` bytes. Larger tables result in better " +"and slower compression. This parameter has no effect for the :attr:" +"`~Strategy.fast` strategy. It's still useful when using :attr:`~Strategy." +"dfast` strategy, in which case it defines a secondary probe table." +msgstr "" + +#: ../../library/compression.zstd.rst:568 +msgid "" +"Number of search attempts, as a power of two. More attempts result in better " +"and slower compression. This parameter is useless for :attr:`~Strategy.fast` " +"and :attr:`~Strategy.dfast` strategies." +msgstr "" + +#: ../../library/compression.zstd.rst:576 +msgid "" +"Minimum size of searched matches. Larger values increase compression and " +"decompression speed, but decrease ratio. Note that Zstandard can still find " +"matches of smaller size, it just tweaks its search algorithm to look for " +"this size and larger. For all strategies < :attr:`~Strategy.btopt`, the " +"effective minimum is ``4``; for all strategies > :attr:`~Strategy.fast`, the " +"effective maximum is ``6``." +msgstr "" + +#: ../../library/compression.zstd.rst:587 +msgid "The impact of this field depends on the selected :class:`Strategy`." +msgstr "" + +#: ../../library/compression.zstd.rst:589 +msgid "" +"For strategies :attr:`~Strategy.btopt`, :attr:`~Strategy.btultra` and :attr:" +"`~Strategy.btultra2`, the value is the length of a match considered \"good " +"enough\" to stop searching. Larger values make compression ratios better, " +"but compresses slower." +msgstr "" + +#: ../../library/compression.zstd.rst:594 +msgid "" +"For strategy :attr:`~Strategy.fast`, it is the distance between match " +"sampling. Larger values make compression faster, but with a worse " +"compression ratio." +msgstr "" + +#: ../../library/compression.zstd.rst:602 +msgid "" +"The higher the value of selected strategy, the more complex the compression " +"technique used by zstd, resulting in higher compression ratios but slower " +"compression." +msgstr "" + +#: ../../library/compression.zstd.rst:606 +msgid ":class:`Strategy`" +msgstr ":class:`Strategy`" + +#: ../../library/compression.zstd.rst:610 +msgid "" +"Long distance matching can be used to improve compression for large inputs " +"by finding large matches at greater distances. It increases memory usage and " +"window size." +msgstr "" + +#: ../../library/compression.zstd.rst:614 +msgid "" +"``True`` or ``1`` enable long distance matching while ``False`` or ``0`` " +"disable it." +msgstr "" + +#: ../../library/compression.zstd.rst:617 +msgid "" +"Enabling this parameter increases default :attr:`~CompressionParameter." +"window_log` to 128 MiB except when expressly set to a different value. This " +"setting is enabled by default if :attr:`!window_log` >= 128 MiB and the " +"compression strategy >= :attr:`~Strategy.btopt` (compression level 16+)." +msgstr "" + +#: ../../library/compression.zstd.rst:625 +msgid "" +"Size of the table for long distance matching, as a power of two. Larger " +"values increase memory usage and compression ratio, but decrease compression " +"speed." +msgstr "" + +#: ../../library/compression.zstd.rst:633 +msgid "" +"Minimum match size for long distance matcher. Larger or too small values can " +"often decrease the compression ratio." +msgstr "" + +#: ../../library/compression.zstd.rst:640 +msgid "" +"Log size of each bucket in the long distance matcher hash table for " +"collision resolution. Larger values improve collision resolution but " +"decrease compression speed." +msgstr "" + +#: ../../library/compression.zstd.rst:648 +msgid "" +"Frequency of inserting/looking up entries into the long distance matcher " +"hash table. Larger values improve compression speed. Deviating far from the " +"default value will likely result in a compression ratio decrease." +msgstr "" + +#: ../../library/compression.zstd.rst:656 +msgid "" +"Write the size of the data to be compressed into the Zstandard frame header " +"when known prior to compressing." +msgstr "" + +#: ../../library/compression.zstd.rst:659 +msgid "This flag only takes effect under the following scenarios:" +msgstr "" + +#: ../../library/compression.zstd.rst:661 +msgid "Calling :func:`compress` for one-shot compression" +msgstr "" + +#: ../../library/compression.zstd.rst:662 +msgid "" +"Providing all of the data to be compressed in the frame in a single :meth:" +"`ZstdCompressor.compress` call, with the :attr:`ZstdCompressor.FLUSH_FRAME` " +"mode." +msgstr "" + +#: ../../library/compression.zstd.rst:665 +msgid "" +"Calling :meth:`ZstdCompressor.set_pledged_input_size` with the exact amount " +"of data that will be provided to the compressor prior to any calls to :meth:" +"`ZstdCompressor.compress` for the current frame. :meth:`!ZstdCompressor." +"set_pledged_input_size` must be called for each new frame." +msgstr "" + +#: ../../library/compression.zstd.rst:671 +msgid "" +"All other compression calls may not write the size information into the " +"frame header." +msgstr "" + +#: ../../library/compression.zstd.rst:674 +msgid "" +"``True`` or ``1`` enable the content size flag while ``False`` or ``0`` " +"disable it." +msgstr "" + +#: ../../library/compression.zstd.rst:679 +msgid "" +"A four-byte checksum using XXHash64 of the uncompressed content is written " +"at the end of each frame. Zstandard's decompression code verifies the " +"checksum. If there is a mismatch a :class:`ZstdError` exception is raised." +msgstr "" + +#: ../../library/compression.zstd.rst:684 +msgid "" +"``True`` or ``1`` enable checksum generation while ``False`` or ``0`` " +"disable it." +msgstr "" + +#: ../../library/compression.zstd.rst:689 +msgid "" +"When compressing with a :class:`ZstdDict`, the dictionary's ID is written " +"into the frame header." +msgstr "" + +#: ../../library/compression.zstd.rst:692 +msgid "" +"``True`` or ``1`` enable storing the dictionary ID while ``False`` or ``0`` " +"disable it." +msgstr "" + +#: ../../library/compression.zstd.rst:697 +msgid "" +"Select how many threads will be spawned to compress in parallel. When :attr:" +"`!nb_workers` > 0, enables multi-threaded compression, a value of ``1`` " +"means \"one-thread multi-threaded mode\". More workers improve speed, but " +"also increase memory usage and slightly reduce compression ratio." +msgstr "" + +#: ../../library/compression.zstd.rst:702 +msgid "A value of zero disables multi-threading." +msgstr "" + +#: ../../library/compression.zstd.rst:706 +msgid "" +"Size of a compression job, in bytes. This value is enforced only when :attr:" +"`~CompressionParameter.nb_workers` >= 1. Each compression job is completed " +"in parallel, so this value can indirectly impact the number of active " +"threads." +msgstr "" + +#: ../../library/compression.zstd.rst:715 +msgid "" +"Sets how much data is reloaded from previous jobs (threads) for new jobs to " +"be used by the look behind window during compression. This value is only " +"used when :attr:`~CompressionParameter.nb_workers` >= 1. Acceptable values " +"vary from 0 to 9." +msgstr "" + +#: ../../library/compression.zstd.rst:720 +msgid "0 means dynamically set the overlap amount" +msgstr "" + +#: ../../library/compression.zstd.rst:721 +msgid "1 means no overlap" +msgstr "" + +#: ../../library/compression.zstd.rst:722 +msgid "9 means use a full window size from the previous job" +msgstr "" + +#: ../../library/compression.zstd.rst:724 +msgid "" +"Each increment halves/doubles the overlap size. \"8\" means an overlap of " +"``window_size/2``, \"7\" means an overlap of ``window_size/4``, etc." +msgstr "" + +#: ../../library/compression.zstd.rst:729 +msgid "" +"An :class:`~enum.IntEnum` containing the advanced decompression parameter " +"keys that can be used when decompressing data. Parameters are optional; any " +"omitted parameter will have it's value selected automatically." +msgstr "" + +#: ../../library/compression.zstd.rst:736 +msgid "Example setting the :attr:`~.window_log_max` to the maximum size::" +msgstr "" + +#: ../../library/compression.zstd.rst:738 +msgid "" +"data = compress(b'Some very long buffer of bytes...')\n" +"\n" +"_lower, upper = DecompressionParameter.window_log_max.bounds()\n" +"\n" +"options = {DecompressionParameter.window_log_max: upper}\n" +"decompress(data, options=options)" +msgstr "" +"data = compress(b'Some very long buffer of bytes...')\n" +"\n" +"_lower, upper = DecompressionParameter.window_log_max.bounds()\n" +"\n" +"options = {DecompressionParameter.window_log_max: upper}\n" +"decompress(data, options=options)" + +#: ../../library/compression.zstd.rst:747 +msgid "" +"Return the tuple of int bounds, ``(lower, upper)``, of a decompression " +"parameter. This method should be called on the attribute you wish to " +"retrieve the bounds of." +msgstr "" + +#: ../../library/compression.zstd.rst:755 +msgid "" +"The base-two logarithm of the maximum size of the window used during " +"decompression. This can be useful to limit the amount of memory used when " +"decompressing data. A larger maximum window size leads to faster " +"decompression." +msgstr "" + +#: ../../library/compression.zstd.rst:765 +msgid "" +"An :class:`~enum.IntEnum` containing strategies for compression. Higher-" +"numbered strategies correspond to more complex and slower compression." +msgstr "" + +#: ../../library/compression.zstd.rst:771 +msgid "" +"The values of attributes of :class:`!Strategy` are not necessarily stable " +"across zstd versions. Only the ordering of the attributes may be relied " +"upon. The attributes are listed below in order." +msgstr "" + +#: ../../library/compression.zstd.rst:775 +msgid "The following strategies are available:" +msgstr "" + +#: ../../library/compression.zstd.rst:797 +msgid "Miscellaneous" +msgstr "" + +#: ../../library/compression.zstd.rst:801 +msgid "" +"Retrieve a :class:`FrameInfo` object containing metadata about a Zstandard " +"frame. Frames contain metadata related to the compressed data they hold." +msgstr "" + +#: ../../library/compression.zstd.rst:807 +msgid "Metadata related to a Zstandard frame." +msgstr "" + +#: ../../library/compression.zstd.rst:811 +msgid "The size of the decompressed contents of the frame." +msgstr "" + +#: ../../library/compression.zstd.rst:815 +msgid "" +"An integer representing the Zstandard dictionary ID needed for decompressing " +"the frame. ``0`` means the dictionary ID was not recorded in the frame " +"header. This may mean that a Zstandard dictionary is not needed, or that the " +"ID of a required dictionary was not recorded." +msgstr "" + +#: ../../library/compression.zstd.rst:823 +msgid "The default compression level for Zstandard: ``3``." +msgstr "" + +#: ../../library/compression.zstd.rst:828 +msgid "" +"Version number of the runtime zstd library as a tuple of integers (major, " +"minor, release)." +msgstr "" + +#: ../../library/compression.zstd.rst:833 +msgid "Examples" +msgstr "範例" + +#: ../../library/compression.zstd.rst:835 +msgid "Reading in a compressed file:" +msgstr "讀取壓縮檔案：" + +#: ../../library/compression.zstd.rst:837 +msgid "" +"from compression import zstd\n" +"\n" +"with zstd.open(\"file.zst\") as f:\n" +" file_content = f.read()" +msgstr "" +"from compression import zstd\n" +"\n" +"with zstd.open(\"file.zst\") as f:\n" +" file_content = f.read()" + +#: ../../library/compression.zstd.rst:844 +msgid "Creating a compressed file:" +msgstr "" + +#: ../../library/compression.zstd.rst:846 +msgid "" +"from compression import zstd\n" +"\n" +"data = b\"Insert Data Here\"\n" +"with zstd.open(\"file.zst\", \"w\") as f:\n" +" f.write(data)" +msgstr "" +"from compression import zstd\n" +"\n" +"data = b\"Insert Data Here\"\n" +"with zstd.open(\"file.zst\", \"w\") as f:\n" +" f.write(data)" + +#: ../../library/compression.zstd.rst:854 +msgid "Compressing data in memory:" +msgstr "" + +#: ../../library/compression.zstd.rst:856 +msgid "" +"from compression import zstd\n" +"\n" +"data_in = b\"Insert Data Here\"\n" +"data_out = zstd.compress(data_in)" +msgstr "" +"from compression import zstd\n" +"\n" +"data_in = b\"Insert Data Here\"\n" +"data_out = zstd.compress(data_in)" + +#: ../../library/compression.zstd.rst:863 +msgid "Incremental compression:" +msgstr "" + +#: ../../library/compression.zstd.rst:865 +msgid "" +"from compression import zstd\n" +"\n" +"comp = zstd.ZstdCompressor()\n" +"out1 = comp.compress(b\"Some data\\n\")\n" +"out2 = comp.compress(b\"Another piece of data\\n\")\n" +"out3 = comp.compress(b\"Even more data\\n\")\n" +"out4 = comp.flush()\n" +"# Concatenate all the partial results:\n" +"result = b\"\".join([out1, out2, out3, out4])" +msgstr "" +"from compression import zstd\n" +"\n" +"comp = zstd.ZstdCompressor()\n" +"out1 = comp.compress(b\"Some data\\n\")\n" +"out2 = comp.compress(b\"Another piece of data\\n\")\n" +"out3 = comp.compress(b\"Even more data\\n\")\n" +"out4 = comp.flush()\n" +"# Concatenate all the partial results:\n" +"result = b\"\".join([out1, out2, out3, out4])" + +#: ../../library/compression.zstd.rst:877 +msgid "Writing compressed data to an already-open file:" +msgstr "" + +#: ../../library/compression.zstd.rst:879 +msgid "" +"from compression import zstd\n" +"\n" +"with open(\"myfile\", \"wb\") as f:\n" +" f.write(b\"This data will not be compressed\\n\")\n" +" with zstd.open(f, \"w\") as zstf:\n" +" zstf.write(b\"This *will* be compressed\\n\")\n" +" f.write(b\"Not compressed\\n\")" +msgstr "" +"from compression import zstd\n" +"\n" +"with open(\"myfile\", \"wb\") as f:\n" +" f.write(b\"This data will not be compressed\\n\")\n" +" with zstd.open(f, \"w\") as zstf:\n" +" zstf.write(b\"This *will* be compressed\\n\")\n" +" f.write(b\"Not compressed\\n\")" + +#: ../../library/compression.zstd.rst:889 +msgid "Creating a compressed file using compression parameters:" +msgstr "" + +#: ../../library/compression.zstd.rst:891 +msgid "" +"from compression import zstd\n" +"\n" +"options = {\n" +" zstd.CompressionParameter.checksum_flag: 1\n" +"}\n" +"with zstd.open(\"file.zst\", \"w\", options=options) as f:\n" +" f.write(b\"Mind if I squeeze in?\")" +msgstr "" +"from compression import zstd\n" +"\n" +"options = {\n" +" zstd.CompressionParameter.checksum_flag: 1\n" +"}\n" +"with zstd.open(\"file.zst\", \"w\", options=options) as f:\n" +" f.write(b\"Mind if I squeeze in?\")" diff --git a/library/concurrency.po b/library/concurrency.po index aee93b82e7..598d2ded16 100644 --- a/library/concurrency.po +++ b/library/concurrency.po @@ -1,40 +1,40 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Matt Wang , 2021 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: 2021-11-23 13:36+0800\n" -"Last-Translator: Matt Wang \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" -"X-Generator: Poedit 3.0\n" - -#: ../../library/concurrency.rst:5 -msgid "Concurrent Execution" -msgstr "並行執行 (Concurrent Execution)" - -#: ../../library/concurrency.rst:7 -msgid "" -"The modules described in this chapter provide support for concurrent " -"execution of code. The appropriate choice of tool will depend on the task to " -"be executed (CPU bound vs IO bound) and preferred style of development " -"(event driven cooperative multitasking vs preemptive multitasking). Here's " -"an overview:" -msgstr "" -"本章節描述的模組在程式的並行執行上提供支援。選擇要使用哪一個工具則取決於是執" -"行什麼樣的任務（CPU 密集或 IO 密集）與偏好的開發風格（事件驅動協作式多工處理" -"或搶占式多工處理）。以下為此章節總覽：" - -#: ../../library/concurrency.rst:28 -msgid "The following are support modules for some of the above services:" -msgstr "以下是支援部份上述服務的模組：" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Matt Wang , 2021 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: 2021-11-23 13:36+0800\n" +"Last-Translator: Matt Wang \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" +"X-Generator: Poedit 3.0\n" + +#: ../../library/concurrency.rst:5 +msgid "Concurrent Execution" +msgstr "並行執行 (Concurrent Execution)" + +#: ../../library/concurrency.rst:7 +msgid "" +"The modules described in this chapter provide support for concurrent " +"execution of code. The appropriate choice of tool will depend on the task to " +"be executed (CPU bound vs IO bound) and preferred style of development " +"(event driven cooperative multitasking vs preemptive multitasking). Here's " +"an overview:" +msgstr "" +"本章節描述的模組在程式的並行執行上提供支援。選擇要使用哪一個工具則取決於是執" +"行什麼樣的任務（CPU 密集或 IO 密集）與偏好的開發風格（事件驅動協作式多工處理" +"或搶占式多工處理）。以下為此章節總覽：" + +#: ../../library/concurrency.rst:28 +msgid "The following are support modules for some of the above services:" +msgstr "以下是支援部份上述服務的模組：" diff --git a/library/concurrent.futures.po b/library/concurrent.futures.po index 00947fbd24..383fb55187 100644 --- a/library/concurrent.futures.po +++ b/library/concurrent.futures.po @@ -1,1152 +1,1152 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Matt Wang , 2023-2024 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2026-01-11 00:17+0000\n" -"PO-Revision-Date: 2023-01-24 03:33+0800\n" -"Last-Translator: Matt Wang \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" -"X-Generator: Poedit 3.2.2\n" - -#: ../../library/concurrent.futures.rst:2 -msgid ":mod:`!concurrent.futures` --- Launching parallel tasks" -msgstr ":mod:`!concurrent.futures` --- 啟動平行任務" - -#: ../../library/concurrent.futures.rst:9 -msgid "" -"**Source code:** :source:`Lib/concurrent/futures/thread.py`, :source:`Lib/" -"concurrent/futures/process.py`, and :source:`Lib/concurrent/futures/" -"interpreter.py`" -msgstr "" -"**原始碼：**\\ :source:`Lib/concurrent/futures/thread.py`、:source:`Lib/" -"concurrent/futures/process.py` 與 :source:`Lib/concurrent/futures/" -"interpreter.py`" - -#: ../../library/concurrent.futures.rst:15 -msgid "" -"The :mod:`concurrent.futures` module provides a high-level interface for " -"asynchronously executing callables." -msgstr "" -":mod:`concurrent.futures` 模組提供了一個高階介面來非同步地 (asynchronously) " -"執行可呼叫物件 (callable) 。" - -#: ../../library/concurrent.futures.rst:18 -msgid "" -"The asynchronous execution can be performed with threads, using :class:" -"`ThreadPoolExecutor` or :class:`InterpreterPoolExecutor`, or separate " -"processes, using :class:`ProcessPoolExecutor`. Each implements the same " -"interface, which is defined by the abstract :class:`Executor` class." -msgstr "" -"非同步執行可以透過 :class:`ThreadPoolExecutor` 或 :class:" -"`InterpreterPoolExecutor` 來使用執行緒 (thread) 執行，或透過 :class:" -"`ProcessPoolExecutor` 來使用單獨行程 (process) 執行。兩者都實作了相同的介面，" -"該介面由抽象的 :class:`Executor` 類別定義。" - -#: ../../library/concurrent.futures.rst:24 -msgid "" -":class:`concurrent.futures.Future` must not be confused with :class:`asyncio." -"Future`, which is designed for use with :mod:`asyncio` tasks and coroutines. " -"See the :doc:`asyncio's Future ` documentation for a " -"detailed comparison of the two." -msgstr "" - -#: ../../includes/wasm-notavail.rst:3 -msgid "Availability" -msgstr "可用性" - -#: ../../includes/wasm-notavail.rst:5 -msgid "" -"This module does not work or is not available on WebAssembly. See :ref:`wasm-" -"availability` for more information." -msgstr "" -"此模組在 WebAssembly 平台上不起作用或無法使用。更多資訊請參閱 :ref:`wasm-" -"availability`。" - -#: ../../library/concurrent.futures.rst:32 -msgid "Executor Objects" -msgstr "Executor 物件" - -#: ../../library/concurrent.futures.rst:36 -msgid "" -"An abstract class that provides methods to execute calls asynchronously. It " -"should not be used directly, but through its concrete subclasses." -msgstr "" -"提供非同步執行呼叫方法的抽象類別。不應直接使用它，而應透過其具體子類別來使" -"用。" - -#: ../../library/concurrent.futures.rst:41 -msgid "" -"Schedules the callable, *fn*, to be executed as ``fn(*args, **kwargs)`` and " -"returns a :class:`Future` object representing the execution of the " -"callable. ::" -msgstr "" -"為可呼叫物件 *fn* 排程來以 ``fn(*args, **kwargs)`` 的形式執行並回傳一個表示可" -"呼叫的執行的 :class:`Future` 物件。 ::" - -#: ../../library/concurrent.futures.rst:45 -msgid "" -"with ThreadPoolExecutor(max_workers=1) as executor:\n" -" future = executor.submit(pow, 323, 1235)\n" -" print(future.result())" -msgstr "" -"with ThreadPoolExecutor(max_workers=1) as executor:\n" -" future = executor.submit(pow, 323, 1235)\n" -" print(future.result())" - -#: ../../library/concurrent.futures.rst:51 -msgid "Similar to :func:`map(fn, *iterables) ` except:" -msgstr "類似於 :func:`map(fn, *iterables) `，除了：" - -#: ../../library/concurrent.futures.rst:53 -msgid "" -"The *iterables* are collected immediately rather than lazily, unless a " -"*buffersize* is specified to limit the number of submitted tasks whose " -"results have not yet been yielded. If the buffer is full, iteration over the " -"*iterables* pauses until a result is yielded from the buffer." -msgstr "" - -#: ../../library/concurrent.futures.rst:58 -msgid "" -"*fn* is executed asynchronously and several calls to *fn* may be made " -"concurrently." -msgstr "*fn* 是非同步執行的，並且對 *fn* 的多次呼叫可以並行處理。" - -#: ../../library/concurrent.futures.rst:61 -msgid "" -"The returned iterator raises a :exc:`TimeoutError` if :meth:`~iterator." -"__next__` is called and the result isn't available after *timeout* seconds " -"from the original call to :meth:`Executor.map`. *timeout* can be an int or a " -"float. If *timeout* is not specified or ``None``, there is no limit to the " -"wait time." -msgstr "" -"如果 :meth:`~iterator.__next__` 被呼叫，且在原先呼叫 :meth:`Executor.map` 的 " -"*timeout* 秒後結果仍不可用，回傳的疊代器就會引發 :exc:`TimeoutError`。" -"*timeout* 可以是整數或浮點數。如果未指定 *timeout* 或為 ``None``，則等待時間" -"就不會有限制。" - -#: ../../library/concurrent.futures.rst:67 -msgid "" -"If a *fn* call raises an exception, then that exception will be raised when " -"its value is retrieved from the iterator." -msgstr "如果 *fn* 呼叫引發例外，則當從疊代器中檢索到它的值時將引發該例外。" - -#: ../../library/concurrent.futures.rst:70 -msgid "" -"When using :class:`ProcessPoolExecutor`, this method chops *iterables* into " -"a number of chunks which it submits to the pool as separate tasks. The " -"(approximate) size of these chunks can be specified by setting *chunksize* " -"to a positive integer. For very long iterables, using a large value for " -"*chunksize* can significantly improve performance compared to the default " -"size of 1. With :class:`ThreadPoolExecutor` and :class:" -"`InterpreterPoolExecutor`, *chunksize* has no effect." -msgstr "" -"使用 :class:`ProcessPoolExecutor` 時，此方法將 *iterables* 分成許多分塊 " -"(chunks)，並將其作為獨立的任務來提交給池 (pool)。可以透過將 *chunksize* 設定" -"為正整數來指定這些分塊的（約略）大小。對於非常長的可疊代物件，*chunksize* 使" -"用較大的值（與預設大小 1 相比）可以顯著提高性能。對於 :class:" -"`ThreadPoolExecutor` 和 :class:`InterpreterPoolExecutor`，*chunksize* 無效。" - -#: ../../library/concurrent.futures.rst:79 -msgid "Added the *chunksize* parameter." -msgstr "新增 *chunksize* 參數。" - -#: ../../library/concurrent.futures.rst:82 -msgid "Added the *buffersize* parameter." -msgstr "新增 *buffersize* 參數。" - -#: ../../library/concurrent.futures.rst:87 -msgid "" -"Signal the executor that it should free any resources that it is using when " -"the currently pending futures are done executing. Calls to :meth:`Executor." -"submit` and :meth:`Executor.map` made after shutdown will raise :exc:" -"`RuntimeError`." -msgstr "" -"向 executor 發出訊號 (signal)，表明它應該在目前未定 (pending) 的 future 完成" -"執行時釋放它正在使用的任何資源。在關閉後呼叫 :meth:`Executor.submit` 和 :" -"meth:`Executor.map` 將引發 :exc:`RuntimeError`。" - -#: ../../library/concurrent.futures.rst:92 -msgid "" -"If *wait* is ``True`` then this method will not return until all the pending " -"futures are done executing and the resources associated with the executor " -"have been freed. If *wait* is ``False`` then this method will return " -"immediately and the resources associated with the executor will be freed " -"when all pending futures are done executing. Regardless of the value of " -"*wait*, the entire Python program will not exit until all pending futures " -"are done executing." -msgstr "" -"如果 *wait* 為 ``True`` 則此方法將不會回傳，直到所有未定的 futures 完成執行並" -"且與 executor 關聯的資源都被釋放。如果 *wait* 為 ``False`` 則此方法將立即回" -"傳，並且當所有未定的 future 執行完畢時，與 executor 關聯的資源將被釋放。不管 " -"*wait* 的值如何，整個 Python 程式都不會退出，直到所有未定的 futures 執行完" -"畢。" - -#: ../../library/concurrent.futures.rst:100 -msgid "" -"If *cancel_futures* is ``True``, this method will cancel all pending futures " -"that the executor has not started running. Any futures that are completed or " -"running won't be cancelled, regardless of the value of *cancel_futures*." -msgstr "" -"如果 *cancel_futures* 為 ``True``，此方法將取消 executor 尚未開始運行的所有未" -"定 future。無論 *cancel_futures* 的值如何，任何已完成或正在運行的 future 都不" -"會被取消。" - -#: ../../library/concurrent.futures.rst:105 -msgid "" -"If both *cancel_futures* and *wait* are ``True``, all futures that the " -"executor has started running will be completed prior to this method " -"returning. The remaining futures are cancelled." -msgstr "" -"如果 *cancel_futures* 和 *wait* 都為 ``True``，則 executor 已開始運行的所有 " -"future 將在此方法回傳之前完成。剩餘的 future 被取消。" - -#: ../../library/concurrent.futures.rst:109 -msgid "" -"You can avoid having to call this method explicitly if you use the executor " -"as a :term:`context manager` via the :keyword:`with` statement, which will " -"shutdown the :class:`Executor` (waiting as if :meth:`Executor.shutdown` were " -"called with *wait* set to ``True``)::" -msgstr "" -"如果使用 :keyword:`with` 陳述式來將 executor 用作 :term:`context manager`，那" -"你就可以不用明確地呼叫此方法，這將會自己關閉 :class:`Executor`\\（如同呼叫 :" -"meth:`Executor.shutdown` 時 *wait* 被設定為 ``True`` 般等待）： ::" - -#: ../../library/concurrent.futures.rst:114 -msgid "" -"import shutil\n" -"with ThreadPoolExecutor(max_workers=4) as e:\n" -" e.submit(shutil.copy, 'src1.txt', 'dest1.txt')\n" -" e.submit(shutil.copy, 'src2.txt', 'dest2.txt')\n" -" e.submit(shutil.copy, 'src3.txt', 'dest3.txt')\n" -" e.submit(shutil.copy, 'src4.txt', 'dest4.txt')" -msgstr "" -"import shutil\n" -"with ThreadPoolExecutor(max_workers=4) as e:\n" -" e.submit(shutil.copy, 'src1.txt', 'dest1.txt')\n" -" e.submit(shutil.copy, 'src2.txt', 'dest2.txt')\n" -" e.submit(shutil.copy, 'src3.txt', 'dest3.txt')\n" -" e.submit(shutil.copy, 'src4.txt', 'dest4.txt')" - -#: ../../library/concurrent.futures.rst:121 -msgid "Added *cancel_futures*." -msgstr "新增 *cancel_futures*。" - -#: ../../library/concurrent.futures.rst:126 -msgid "ThreadPoolExecutor" -msgstr "ThreadPoolExecutor" - -#: ../../library/concurrent.futures.rst:128 -msgid "" -":class:`ThreadPoolExecutor` is an :class:`Executor` subclass that uses a " -"pool of threads to execute calls asynchronously." -msgstr "" -":class:`ThreadPoolExecutor` 是一個 :class:`Executor` 子類別，它使用執行緒池來" -"非同步地執行呼叫。" - -#: ../../library/concurrent.futures.rst:131 -msgid "" -"Deadlocks can occur when the callable associated with a :class:`Future` " -"waits on the results of another :class:`Future`. For example::" -msgstr "" -"當與 :class:`Future` 關聯的可呼叫物件等待另一個 :class:`Future` 的結果時，可" -"能會發生死鎖 (deadlock)。例如： ::" - -#: ../../library/concurrent.futures.rst:134 -msgid "" -"import time\n" -"def wait_on_b():\n" -" time.sleep(5)\n" -" print(b.result()) # b will never complete because it is waiting on a.\n" -" return 5\n" -"\n" -"def wait_on_a():\n" -" time.sleep(5)\n" -" print(a.result()) # a will never complete because it is waiting on b.\n" -" return 6\n" -"\n" -"\n" -"executor = ThreadPoolExecutor(max_workers=2)\n" -"a = executor.submit(wait_on_b)\n" -"b = executor.submit(wait_on_a)" -msgstr "" -"import time\n" -"def wait_on_b():\n" -" time.sleep(5)\n" -" print(b.result()) # b 永遠不會完成，因為它正在等待 a。\n" -" return 5\n" -"\n" -"def wait_on_a():\n" -" time.sleep(5)\n" -" print(a.result()) # a 永遠不會完成，因為它正在等待 b。\n" -" return 6\n" -"\n" -"\n" -"executor = ThreadPoolExecutor(max_workers=2)\n" -"a = executor.submit(wait_on_b)\n" -"b = executor.submit(wait_on_a)" - -#: ../../library/concurrent.futures.rst:150 -msgid "And::" -msgstr "和： ::" - -#: ../../library/concurrent.futures.rst:152 -msgid "" -"def wait_on_future():\n" -" f = executor.submit(pow, 5, 2)\n" -" # This will never complete because there is only one worker thread and\n" -" # it is executing this function.\n" -" print(f.result())\n" -"\n" -"executor = ThreadPoolExecutor(max_workers=1)\n" -"executor.submit(wait_on_future)" -msgstr "" -"def wait_on_future():\n" -" f = executor.submit(pow, 5, 2)\n" -" # 這將永遠不會完成，因為只有一個工作執行緒且\n" -" # 它正在執行這個函式。\n" -" print(f.result())\n" -"\n" -"executor = ThreadPoolExecutor(max_workers=1)\n" -"executor.submit(wait_on_future)" - -#: ../../library/concurrent.futures.rst:164 -msgid "" -"An :class:`Executor` subclass that uses a pool of at most *max_workers* " -"threads to execute calls asynchronously." -msgstr "" -"一個 :class:`Executor` 子類別，它使用最多有 *max_workers* 個執行緒的池來非同" -"步地執行呼叫。" - -#: ../../library/concurrent.futures.rst:167 -msgid "" -"All threads enqueued to ``ThreadPoolExecutor`` will be joined before the " -"interpreter can exit. Note that the exit handler which does this is executed " -"*before* any exit handlers added using ``atexit``. This means exceptions in " -"the main thread must be caught and handled in order to signal threads to " -"exit gracefully. For this reason, it is recommended that " -"``ThreadPoolExecutor`` not be used for long-running tasks." -msgstr "" -"所有排隊到 ``ThreadPoolExecutor`` 的執行緒都將在直譯器退出之前加入。請注意，" -"執行此操作的退出處理程式會在任何使用 ``atexit`` 新增的退出處理程式\\ *之前" -"*\\ 執行。這意味著必須捕獲並處理主執行緒中的例外，以便向執行緒發出訊號來正常" -"退出 (gracefully exit)。因此，建議不要將 ``ThreadPoolExecutor`` 用於長時間運" -"行的任務。" - -#: ../../library/concurrent.futures.rst:174 -msgid "" -"*initializer* is an optional callable that is called at the start of each " -"worker thread; *initargs* is a tuple of arguments passed to the " -"initializer. Should *initializer* raise an exception, all currently pending " -"jobs will raise a :exc:`~concurrent.futures.thread.BrokenThreadPool`, as " -"well as any attempt to submit more jobs to the pool." -msgstr "" -"*initializer* 是一個可選的可呼叫物件，在每個工作執行緒開始時呼叫； " -"*initargs* 是傳遞給 initializer 的引數元組 (tuple)。如果 *initializer* 引發例" -"外，所有目前未定的作業以及任何向池中提交 (submit) 更多作業的嘗試都將引發 :" -"exc:`~concurrent.futures.thread.BrokenThreadPool`。" - -#: ../../library/concurrent.futures.rst:180 -msgid "" -"If *max_workers* is ``None`` or not given, it will default to the number of " -"processors on the machine, multiplied by ``5``, assuming that :class:" -"`ThreadPoolExecutor` is often used to overlap I/O instead of CPU work and " -"the number of workers should be higher than the number of workers for :class:" -"`ProcessPoolExecutor`." -msgstr "" -"如果 *max_workers* 為 ``None`` 或未給定，它將預設為機器上的處理器數量乘以 " -"``5``，這假定了 :class:`ThreadPoolExecutor` 通常用於 I/O 重疊而非 CPU 密集的" -"作業，並且 worker 的數量應該高於 :class:`ProcessPoolExecutor` 的 worker 數" -"量。" - -#: ../../library/concurrent.futures.rst:188 -msgid "" -"Added the *thread_name_prefix* parameter to allow users to control the :" -"class:`threading.Thread` names for worker threads created by the pool for " -"easier debugging." -msgstr "" -"新增 *thread_name_prefix* 參數以允許使用者控制由池所建立的工作執行緒 (worker " -"thread) 的 :class:`threading.Thread` 名稱，以便於除錯。" - -#: ../../library/concurrent.futures.rst:193 -#: ../../library/concurrent.futures.rst:403 -msgid "Added the *initializer* and *initargs* arguments." -msgstr "新增 *initializer* 與 *initargs* 引數。" - -#: ../../library/concurrent.futures.rst:196 -msgid "" -"Default value of *max_workers* is changed to ``min(32, os.cpu_count() + " -"4)``. This default value preserves at least 5 workers for I/O bound tasks. " -"It utilizes at most 32 CPU cores for CPU bound tasks which release the GIL. " -"And it avoids using very large resources implicitly on many-core machines." -msgstr "" -"*max_workers* 的預設值改為 ``min(32, os.cpu_count() + 4)``。此預設值為 I/O 密" -"集任務至少保留了 5 個 worker。它最多使用 32 個 CPU 核心來執行CPU 密集任務，以" -"釋放 GIL。並且它避免了在多核機器上隱晦地使用非常大量的資源。" - -#: ../../library/concurrent.futures.rst:202 -msgid "" -"ThreadPoolExecutor now reuses idle worker threads before starting " -"*max_workers* worker threads too." -msgstr "" -"ThreadPoolExecutor 現在在啟動 *max_workers* 工作執行緒之前會重用 (reuse) 空閒" -"的工作執行緒。" - -#: ../../library/concurrent.futures.rst:205 -msgid "" -"Default value of *max_workers* is changed to ``min(32, (os." -"process_cpu_count() or 1) + 4)``." -msgstr "" -"*max_workers* 的預設值被改為 ``min(32, (os.process_cpu_count() or 1) + 4)``。" - -#: ../../library/concurrent.futures.rst:213 -msgid "ThreadPoolExecutor Example" -msgstr "ThreadPoolExecutor 範例" - -#: ../../library/concurrent.futures.rst:216 -msgid "" -"import concurrent.futures\n" -"import urllib.request\n" -"\n" -"URLS = ['http://www.foxnews.com/',\n" -" 'http://www.cnn.com/',\n" -" 'http://europe.wsj.com/',\n" -" 'http://www.bbc.co.uk/',\n" -" 'http://nonexistent-subdomain.python.org/']\n" -"\n" -"# Retrieve a single page and report the URL and contents\n" -"def load_url(url, timeout):\n" -" with urllib.request.urlopen(url, timeout=timeout) as conn:\n" -" return conn.read()\n" -"\n" -"# We can use a with statement to ensure threads are cleaned up promptly\n" -"with concurrent.futures.ThreadPoolExecutor(max_workers=5) as executor:\n" -" # Start the load operations and mark each future with its URL\n" -" future_to_url = {executor.submit(load_url, url, 60): url for url in " -"URLS}\n" -" for future in concurrent.futures.as_completed(future_to_url):\n" -" url = future_to_url[future]\n" -" try:\n" -" data = future.result()\n" -" except Exception as exc:\n" -" print('%r generated an exception: %s' % (url, exc))\n" -" else:\n" -" print('%r page is %d bytes' % (url, len(data)))" -msgstr "" - -#: ../../library/concurrent.futures.rst:245 -msgid "InterpreterPoolExecutor" -msgstr "InterpreterPoolExecutor" - -#: ../../library/concurrent.futures.rst:249 -msgid "" -"The :class:`InterpreterPoolExecutor` class uses a pool of interpreters to " -"execute calls asynchronously. It is a :class:`ThreadPoolExecutor` subclass, " -"which means each worker is running in its own thread. The difference here is " -"that each worker has its own interpreter, and runs each task using that " -"interpreter." -msgstr "" - -#: ../../library/concurrent.futures.rst:255 -msgid "" -"The biggest benefit to using interpreters instead of only threads is true " -"multi-core parallelism. Each interpreter has its own :term:`Global " -"Interpreter Lock `, so code running in one " -"interpreter can run on one CPU core, while code in another interpreter runs " -"unblocked on a different core." -msgstr "" - -#: ../../library/concurrent.futures.rst:261 -msgid "" -"The tradeoff is that writing concurrent code for use with multiple " -"interpreters can take extra effort. However, this is because it forces you " -"to be deliberate about how and when interpreters interact, and to be " -"explicit about what data is shared between interpreters. This results in " -"several benefits that help balance the extra effort, including true multi-" -"core parallelism, For example, code written this way can make it easier to " -"reason about concurrency. Another major benefit is that you don't have to " -"deal with several of the big pain points of using threads, like race " -"conditions." -msgstr "" - -#: ../../library/concurrent.futures.rst:271 -msgid "" -"Each worker's interpreter is isolated from all the other interpreters. " -"\"Isolated\" means each interpreter has its own runtime state and operates " -"completely independently. For example, if you redirect :data:`sys.stdout` " -"in one interpreter, it will not be automatically redirected to any other " -"interpreter. If you import a module in one interpreter, it is not " -"automatically imported in any other. You would need to import the module " -"separately in interpreter where you need it. In fact, each module imported " -"in an interpreter is a completely separate object from the same module in a " -"different interpreter, including :mod:`sys`, :mod:`builtins`, and even " -"``__main__``." -msgstr "" - -#: ../../library/concurrent.futures.rst:283 -msgid "" -"Isolation means a mutable object, or other data, cannot be used by more than " -"one interpreter at the same time. That effectively means interpreters " -"cannot actually share such objects or data. Instead, each interpreter must " -"have its own copy, and you will have to synchronize any changes between the " -"copies manually. Immutable objects and data, like the builtin singletons, " -"strings, and tuples of immutable objects, don't have these limitations." -msgstr "" - -#: ../../library/concurrent.futures.rst:291 -msgid "" -"Communicating and synchronizing between interpreters is most effectively " -"done using dedicated tools, like those proposed in :pep:`734`. One less " -"efficient alternative is to serialize with :mod:`pickle` and then send the " -"bytes over a shared :mod:`socket ` or :func:`pipe `." -msgstr "" - -#: ../../library/concurrent.futures.rst:299 -msgid "" -"A :class:`ThreadPoolExecutor` subclass that executes calls asynchronously " -"using a pool of at most *max_workers* threads. Each thread runs tasks in " -"its own interpreter. The worker interpreters are isolated from each other, " -"which means each has its own runtime state and that they can't share any " -"mutable objects or other data. Each interpreter has its own :term:`Global " -"Interpreter Lock `, which means code run with this " -"executor has true multi-core parallelism." -msgstr "" - -#: ../../library/concurrent.futures.rst:307 -msgid "" -"The optional *initializer* and *initargs* arguments have the same meaning as " -"for :class:`!ThreadPoolExecutor`: the initializer is run when each worker is " -"created, though in this case it is run in the worker's interpreter. The " -"executor serializes the *initializer* and *initargs* using :mod:`pickle` " -"when sending them to the worker's interpreter." -msgstr "" - -#: ../../library/concurrent.futures.rst:315 -msgid "" -"The executor may replace uncaught exceptions from *initializer* with :class:" -"`~concurrent.interpreters.ExecutionFailed`." -msgstr "" - -#: ../../library/concurrent.futures.rst:318 -msgid "Other caveats from parent :class:`ThreadPoolExecutor` apply here." -msgstr "" - -#: ../../library/concurrent.futures.rst:320 -msgid "" -":meth:`~Executor.submit` and :meth:`~Executor.map` work like normal, except " -"the worker serializes the callable and arguments using :mod:`pickle` when " -"sending them to its interpreter. The worker likewise serializes the return " -"value when sending it back." -msgstr "" - -#: ../../library/concurrent.futures.rst:325 -msgid "" -"When a worker's current task raises an uncaught exception, the worker always " -"tries to preserve the exception as-is. If that is successful then it also " -"sets the ``__cause__`` to a corresponding :class:`~concurrent.interpreters." -"ExecutionFailed` instance, which contains a summary of the original " -"exception. In the uncommon case that the worker is not able to preserve the " -"original as-is then it directly preserves the corresponding :class:" -"`~concurrent.interpreters.ExecutionFailed` instance instead." -msgstr "" - -#: ../../library/concurrent.futures.rst:337 -msgid "ProcessPoolExecutor" -msgstr "ProcessPoolExecutor" - -#: ../../library/concurrent.futures.rst:339 -msgid "" -"The :class:`ProcessPoolExecutor` class is an :class:`Executor` subclass that " -"uses a pool of processes to execute calls asynchronously. :class:" -"`ProcessPoolExecutor` uses the :mod:`multiprocessing` module, which allows " -"it to side-step the :term:`Global Interpreter Lock ` but also means that only picklable objects can be executed and " -"returned." -msgstr "" -":class:`ProcessPoolExecutor` 類別是一個 :class:`Executor` 的子類別，它使用行" -"程池來非同步地執行呼叫。:class:`ProcessPoolExecutor` 使用了 :mod:" -"`multiprocessing` 模組，這允許它避開\\ :term:`全域直譯器鎖 (Global " -"Interpreter Lock) `，但也意味著只能執行和回傳可被 " -"pickle 的 (picklable) 物件。" - -#: ../../library/concurrent.futures.rst:346 -msgid "" -"The ``__main__`` module must be importable by worker subprocesses. This " -"means that :class:`ProcessPoolExecutor` will not work in the interactive " -"interpreter." -msgstr "" -"``__main__`` 模組必須可以被工作子行程 (worker subprocess) 引入。這意味著 :" -"class:`ProcessPoolExecutor` 將無法在交互式直譯器 (interactive interpreter) 中" -"工作。" - -#: ../../library/concurrent.futures.rst:349 -msgid "" -"Calling :class:`Executor` or :class:`Future` methods from a callable " -"submitted to a :class:`ProcessPoolExecutor` will result in deadlock." -msgstr "" -"從提交給 :class:`ProcessPoolExecutor` 的可呼叫物件中呼叫 :class:`Executor` " -"或 :class:`Future` 方法將導致死鎖。" - -#: ../../library/concurrent.futures.rst:352 -msgid "" -"Note that the restrictions on functions and arguments needing to picklable " -"as per :class:`multiprocessing.Process` apply when using :meth:`~Executor." -"submit` and :meth:`~Executor.map` on a :class:`ProcessPoolExecutor`. A " -"function defined in a REPL or a lambda should not be expected to work." -msgstr "" - -#: ../../library/concurrent.futures.rst:359 -msgid "" -"An :class:`Executor` subclass that executes calls asynchronously using a " -"pool of at most *max_workers* processes. If *max_workers* is ``None`` or " -"not given, it will default to :func:`os.process_cpu_count`. If *max_workers* " -"is less than or equal to ``0``, then a :exc:`ValueError` will be raised. On " -"Windows, *max_workers* must be less than or equal to ``61``. If it is not " -"then :exc:`ValueError` will be raised. If *max_workers* is ``None``, then " -"the default chosen will be at most ``61``, even if more processors are " -"available. *mp_context* can be a :mod:`multiprocessing` context or ``None``. " -"It will be used to launch the workers. If *mp_context* is ``None`` or not " -"given, the default :mod:`multiprocessing` context is used. See :ref:" -"`multiprocessing-start-methods`." -msgstr "" -"一個 :class:`Executor` 子類別，它使用了最多有 *max_workers* 個行程的池來非同" -"步地執行呼叫。如果 *max_workers* 為 ``None`` 或未給定，它將被預設為 :func:" -"`os.process_cpu_count`。如果 *max_workers* 小於或等於 ``0``，則會引發 :exc:" -"`ValueError`。在 Windows 上，*max_workers* 必須小於或等於 ``61``。如果不是，" -"則會引發 :exc:`ValueError`。如果 *max_workers* 為 ``None``，則預設選擇最多為 " -"``61``，即便有更多處理器可用。*mp_context* 可以是 :mod:`multiprocessing` 情" -"境 (context) 或 ``None``。它將用於啟動 worker。如果 *mp_context* 為 ``None`` " -"或未給定，則使用預設的 :mod:`multiprocessing` 情境。請見 :ref:" -"`multiprocessing-start-methods`。" - -#: ../../library/concurrent.futures.rst:373 -msgid "" -"*initializer* is an optional callable that is called at the start of each " -"worker process; *initargs* is a tuple of arguments passed to the " -"initializer. Should *initializer* raise an exception, all currently pending " -"jobs will raise a :exc:`~concurrent.futures.process.BrokenProcessPool`, as " -"well as any attempt to submit more jobs to the pool." -msgstr "" -"*initializer* 是一個可選的可呼叫物件，在每個工作行程 (worker process) 開始時" -"呼叫；*initargs* 是傳遞給 initializer 的引數元組。如果 *initializer* 引發例" -"外，所有目前未定的作業以及任何向池中提交更多作業的嘗試都將引發 :exc:" -"`~concurrent.futures.process.BrokenProcessPool`。" - -#: ../../library/concurrent.futures.rst:379 -msgid "" -"*max_tasks_per_child* is an optional argument that specifies the maximum " -"number of tasks a single process can execute before it will exit and be " -"replaced with a fresh worker process. By default *max_tasks_per_child* is " -"``None`` which means worker processes will live as long as the pool. When a " -"max is specified, the \"spawn\" multiprocessing start method will be used by " -"default in absence of a *mp_context* parameter. This feature is incompatible " -"with the \"fork\" start method." -msgstr "" -"*max_tasks_per_child* 是一個可選引數，它指定單個行程在退出並被新的工作行程替" -"換之前可以執行的最大任務數。預設情況下 *max_tasks_per_child* 是 ``None``，這" -"意味著工作行程的生命週期將與池一樣長。當指定最大值時，在沒有 *mp_context* 參" -"數的情況下，將預設使用 \"spawn\" 做為 multiprocessing 啟動方法。此功能與 " -"\"fork\" 啟動方法不相容。" - -#: ../../library/concurrent.futures.rst:388 -msgid "" -"Bugs have been reported when using the *max_tasks_per_child* feature that " -"can result in the :class:`ProcessPoolExecutor` hanging in some " -"circumstances. Follow its eventual resolution in :gh:`115634`." -msgstr "" - -#: ../../library/concurrent.futures.rst:392 -msgid "" -"When one of the worker processes terminates abruptly, a :exc:`~concurrent." -"futures.process.BrokenProcessPool` error is now raised. Previously, " -"behaviour was undefined but operations on the executor or its futures would " -"often freeze or deadlock." -msgstr "" -"當其中一個工作行程突然終止時，現在會引發 :exc:`~concurrent.futures.process." -"BrokenProcessPool` 錯誤。在過去，此行為是未定義的 (undefined)，但對 executor " -"或其 future 的操作經常會發生凍結或死鎖。" - -#: ../../library/concurrent.futures.rst:399 -msgid "" -"The *mp_context* argument was added to allow users to control the " -"start_method for worker processes created by the pool." -msgstr "" -"新增了 *mp_context* 引數以允許使用者控制由池所建立的工作行程的 start_method。" - -#: ../../library/concurrent.futures.rst:405 -msgid "" -"The *max_tasks_per_child* argument was added to allow users to control the " -"lifetime of workers in the pool." -msgstr "" -"新增了 *max_tasks_per_child* 引數以允許使用者控制池中 worker 的生命週期。" - -#: ../../library/concurrent.futures.rst:409 -msgid "" -"On POSIX systems, if your application has multiple threads and the :mod:" -"`multiprocessing` context uses the ``\"fork\"`` start method: The :func:`os." -"fork` function called internally to spawn workers may raise a :exc:" -"`DeprecationWarning`. Pass a *mp_context* configured to use a different " -"start method. See the :func:`os.fork` documentation for further explanation." -msgstr "" -"在 POSIX 系統上，如果你的應用程式有多個執行緒並且 :mod:`multiprocessing` 情境" -"使用了 ``\"fork\"`` 啟動方法：內部呼叫以產生 worker 的 :func:`os.fork` 函式可" -"能會引發 :exc:`DeprecationWarning`。傳遞一個 *mp_context* 以配置為使用不同的" -"啟動方法。更多說明請參閱 :func:`os.fork` 文件。" - -#: ../../library/concurrent.futures.rst:417 -msgid "" -"*max_workers* uses :func:`os.process_cpu_count` by default, instead of :func:" -"`os.cpu_count`." -msgstr "" - -#: ../../library/concurrent.futures.rst:421 -msgid "" -"The default process start method (see :ref:`multiprocessing-start-methods`) " -"changed away from *fork*. If you require the *fork* start method for :class:" -"`ProcessPoolExecutor` you must explicitly pass ``mp_context=multiprocessing." -"get_context(\"fork\")``." -msgstr "" - -#: ../../library/concurrent.futures.rst:429 -msgid "" -"Attempt to terminate all living worker processes immediately by calling :" -"meth:`Process.terminate ` on each of " -"them. Internally, it will also call :meth:`Executor.shutdown` to ensure that " -"all other resources associated with the executor are freed." -msgstr "" - -#: ../../library/concurrent.futures.rst:434 -#: ../../library/concurrent.futures.rst:446 -msgid "" -"After calling this method the caller should no longer submit tasks to the " -"executor." -msgstr "" - -#: ../../library/concurrent.futures.rst:441 -msgid "" -"Attempt to kill all living worker processes immediately by calling :meth:" -"`Process.kill ` on each of them. Internally, " -"it will also call :meth:`Executor.shutdown` to ensure that all other " -"resources associated with the executor are freed." -msgstr "" - -#: ../../library/concurrent.futures.rst:454 -msgid "ProcessPoolExecutor Example" -msgstr "ProcessPoolExecutor 範例" - -#: ../../library/concurrent.futures.rst:457 -msgid "" -"import concurrent.futures\n" -"import math\n" -"\n" -"PRIMES = [\n" -" 112272535095293,\n" -" 112582705942171,\n" -" 112272535095293,\n" -" 115280095190773,\n" -" 115797848077099,\n" -" 1099726899285419]\n" -"\n" -"def is_prime(n):\n" -" if n < 2:\n" -" return False\n" -" if n == 2:\n" -" return True\n" -" if n % 2 == 0:\n" -" return False\n" -"\n" -" sqrt_n = int(math.floor(math.sqrt(n)))\n" -" for i in range(3, sqrt_n + 1, 2):\n" -" if n % i == 0:\n" -" return False\n" -" return True\n" -"\n" -"def main():\n" -" with concurrent.futures.ProcessPoolExecutor() as executor:\n" -" for number, prime in zip(PRIMES, executor.map(is_prime, PRIMES)):\n" -" print('%d is prime: %s' % (number, prime))\n" -"\n" -"if __name__ == '__main__':\n" -" main()" -msgstr "" -"import concurrent.futures\n" -"import math\n" -"\n" -"PRIMES = [\n" -" 112272535095293,\n" -" 112582705942171,\n" -" 112272535095293,\n" -" 115280095190773,\n" -" 115797848077099,\n" -" 1099726899285419]\n" -"\n" -"def is_prime(n):\n" -" if n < 2:\n" -" return False\n" -" if n == 2:\n" -" return True\n" -" if n % 2 == 0:\n" -" return False\n" -"\n" -" sqrt_n = int(math.floor(math.sqrt(n)))\n" -" for i in range(3, sqrt_n + 1, 2):\n" -" if n % i == 0:\n" -" return False\n" -" return True\n" -"\n" -"def main():\n" -" with concurrent.futures.ProcessPoolExecutor() as executor:\n" -" for number, prime in zip(PRIMES, executor.map(is_prime, PRIMES)):\n" -" print('%d is prime: %s' % (number, prime))\n" -"\n" -"if __name__ == '__main__':\n" -" main()" - -#: ../../library/concurrent.futures.rst:492 -msgid "Future Objects" -msgstr "Future 物件" - -#: ../../library/concurrent.futures.rst:494 -msgid "" -"The :class:`Future` class encapsulates the asynchronous execution of a " -"callable. :class:`Future` instances are created by :meth:`Executor.submit`." -msgstr "" -":class:`Future` 類別封裝了可呼叫物件的非同步執行。:class:`Future` 實例由 :" -"meth:`Executor.submit` 建立。" - -#: ../../library/concurrent.futures.rst:499 -msgid "" -"Encapsulates the asynchronous execution of a callable. :class:`Future` " -"instances are created by :meth:`Executor.submit` and should not be created " -"directly except for testing." -msgstr "" -"封裝可呼叫物件的非同步執行。:class:`Future` 實例由 :meth:`Executor.submit` 建" -"立，且除測試外不應直接建立。" - -#: ../../library/concurrent.futures.rst:505 -msgid "" -"Attempt to cancel the call. If the call is currently being executed or " -"finished running and cannot be cancelled then the method will return " -"``False``, otherwise the call will be cancelled and the method will return " -"``True``." -msgstr "" -"嘗試取消呼叫。如果呼叫目前正在執行或已完成運行且無法取消，則該方法將回傳 " -"``False``，否則呼叫將被取消並且該方法將回傳 ``True``。" - -#: ../../library/concurrent.futures.rst:512 -msgid "Return ``True`` if the call was successfully cancelled." -msgstr "如果該呼叫成功被取消，則回傳 ``True``。" - -#: ../../library/concurrent.futures.rst:516 -msgid "" -"Return ``True`` if the call is currently being executed and cannot be " -"cancelled." -msgstr "如果呼叫正在執行且無法取消，則回傳 ``True``。" - -#: ../../library/concurrent.futures.rst:521 -msgid "" -"Return ``True`` if the call was successfully cancelled or finished running." -msgstr "如果呼叫成功被取消或結束運行，則回傳 ``True``。" - -#: ../../library/concurrent.futures.rst:526 -msgid "" -"Return the value returned by the call. If the call hasn't yet completed then " -"this method will wait up to *timeout* seconds. If the call hasn't completed " -"in *timeout* seconds, then a :exc:`TimeoutError` will be raised. *timeout* " -"can be an int or float. If *timeout* is not specified or ``None``, there is " -"no limit to the wait time." -msgstr "" -"回傳該呼叫回傳的值。如果呼叫尚未完成，則此方法將等待至多 *timeout* 秒。如果呼" -"叫在 *timeout* 秒內未完成，則會引發 :exc:`TimeoutError`。*timeout* 可以是整數" -"或浮點數。如果未指定 *timeout* 或為 ``None``，則等待時間就不會有限制。" - -#: ../../library/concurrent.futures.rst:533 -#: ../../library/concurrent.futures.rst:547 -msgid "" -"If the future is cancelled before completing then :exc:`.CancelledError` " -"will be raised." -msgstr "如果 future 在完成之前被取消，那麼 :exc:`.CancelledError` 將被引發。" - -#: ../../library/concurrent.futures.rst:536 -msgid "" -"If the call raised an exception, this method will raise the same exception." -msgstr "如果該呼叫引發了例外，此方法將引發相同的例外。" - -#: ../../library/concurrent.futures.rst:540 -msgid "" -"Return the exception raised by the call. If the call hasn't yet completed " -"then this method will wait up to *timeout* seconds. If the call hasn't " -"completed in *timeout* seconds, then a :exc:`TimeoutError` will be raised. " -"*timeout* can be an int or float. If *timeout* is not specified or " -"``None``, there is no limit to the wait time." -msgstr "" -"回傳該呼叫引發的例外。如果呼叫尚未完成，則此方法將等待至多 *timeout* 秒。如果" -"呼叫在 *timeout* 秒內未完成，則會引發 :exc:`TimeoutError`。 *timeout* 可以是" -"整數或浮點數。如果未指定 *timeout* 或為 ``None``，則等待時間就不會有限制。" - -#: ../../library/concurrent.futures.rst:550 -msgid "If the call completed without raising, ``None`` is returned." -msgstr "如果呼叫在沒有引發的情況下完成，則回傳 ``None``。" - -#: ../../library/concurrent.futures.rst:554 -msgid "" -"Attaches the callable *fn* to the future. *fn* will be called, with the " -"future as its only argument, when the future is cancelled or finishes " -"running." -msgstr "" -"將可呼叫的 *fn* 附加到 future 上。當 future 被取消或完成運行時，*fn* 將被以 " -"future 作為其唯一引數來呼叫。" - -#: ../../library/concurrent.futures.rst:558 -msgid "" -"Added callables are called in the order that they were added and are always " -"called in a thread belonging to the process that added them. If the " -"callable raises an :exc:`Exception` subclass, it will be logged and " -"ignored. If the callable raises a :exc:`BaseException` subclass, the " -"behavior is undefined." -msgstr "" -"新增的可呼叫物件按新增順序呼叫，並且始終在屬於新增它們的行程的執行緒中呼叫。" -"如果可呼叫物件引發 :exc:`Exception` 子類別，它將被記錄 (log) 並忽略。如果可呼" -"叫物件引發 :exc:`BaseException` 子類別，該行為未定義。" - -#: ../../library/concurrent.futures.rst:564 -msgid "" -"If the future has already completed or been cancelled, *fn* will be called " -"immediately." -msgstr "如果 future 已經完成或被取消，*fn* 將立即被呼叫。" - -#: ../../library/concurrent.futures.rst:567 -msgid "" -"The following :class:`Future` methods are meant for use in unit tests and :" -"class:`Executor` implementations." -msgstr "以下 :class:`Future` 方法旨在用於單元測試和 :class:`Executor` 實作。" - -#: ../../library/concurrent.futures.rst:572 -msgid "" -"This method should only be called by :class:`Executor` implementations " -"before executing the work associated with the :class:`Future` and by unit " -"tests." -msgstr "" -"此方法只能在與 :class:`Future` 關聯的工作被執行之前於 :class:`Executor` 實作" -"中呼叫，或者在單元測試中呼叫。" - -#: ../../library/concurrent.futures.rst:576 -msgid "" -"If the method returns ``False`` then the :class:`Future` was cancelled, i." -"e. :meth:`Future.cancel` was called and returned ``True``. Any threads " -"waiting on the :class:`Future` completing (i.e. through :func:`as_completed` " -"or :func:`wait`) will be woken up." -msgstr "" -"如果該方法回傳 ``False`` 則 :class:`Future` 已被取消，即 :meth:`Future." -"cancel` 被呼叫並回傳 ``True``。任何等待 :class:`Future` 完成的執行緒（即透" -"過 :func:`as_completed` 或 :func:`wait`）將被喚醒。" - -#: ../../library/concurrent.futures.rst:581 -msgid "" -"If the method returns ``True`` then the :class:`Future` was not cancelled " -"and has been put in the running state, i.e. calls to :meth:`Future.running` " -"will return ``True``." -msgstr "" -"如果該方法回傳 ``True`` 則代表 :class:`Future` 未被取消並已進入運行狀態，意即" -"呼叫 :meth:`Future.running` 將回傳 ``True``。" - -#: ../../library/concurrent.futures.rst:585 -msgid "" -"This method can only be called once and cannot be called after :meth:`Future." -"set_result` or :meth:`Future.set_exception` have been called." -msgstr "" -"此方法只能呼叫一次，且不能在呼叫 :meth:`Future.set_result` 或 :meth:`Future." -"set_exception` 之後呼叫。" - -#: ../../library/concurrent.futures.rst:591 -msgid "" -"Sets the result of the work associated with the :class:`Future` to *result*." -msgstr "將與 :class:`Future` 關聯的工作結果設定為 *result*。" - -#: ../../library/concurrent.futures.rst:594 -#: ../../library/concurrent.futures.rst:607 -msgid "" -"This method should only be used by :class:`Executor` implementations and " -"unit tests." -msgstr "此方法只能在 :class:`Executor` 實作中和單元測試中使用。" - -#: ../../library/concurrent.futures.rst:597 -#: ../../library/concurrent.futures.rst:610 -msgid "" -"This method raises :exc:`concurrent.futures.InvalidStateError` if the :class:" -"`Future` is already done." -msgstr "" -"如果 :class:`Future` 已經完成，此方法會引發 :exc:`concurrent.futures." -"InvalidStateError`。" - -#: ../../library/concurrent.futures.rst:604 -msgid "" -"Sets the result of the work associated with the :class:`Future` to the :" -"class:`Exception` *exception*." -msgstr "" -"將與 :class:`Future` 關聯的工作結果設定為 :class:`Exception` *exception*。" - -#: ../../library/concurrent.futures.rst:616 -msgid "Module Functions" -msgstr "模組函式" - -#: ../../library/concurrent.futures.rst:620 -msgid "" -"Wait for the :class:`Future` instances (possibly created by different :class:" -"`Executor` instances) given by *fs* to complete. Duplicate futures given to " -"*fs* are removed and will be returned only once. Returns a named 2-tuple of " -"sets. The first set, named ``done``, contains the futures that completed " -"(finished or cancelled futures) before the wait completed. The second set, " -"named ``not_done``, contains the futures that did not complete (pending or " -"running futures)." -msgstr "" -"等待 *fs* 給定的 :class:`Future` 實例（可能由不同的 :class:`Executor` 實例建" -"立）完成。提供給 *fs* 的重複 future 將被刪除，並且只會回傳一次。回傳一個集合" -"的附名二元組 (named 2-tuple of sets)。第一組名為 ``done``，包含在等待完成之前" -"完成的 future（已完成或被取消的 future）。第二組名為 ``not_done``，包含未完成" -"的 future（未定或運行中的 future）。" - -#: ../../library/concurrent.futures.rst:628 -msgid "" -"*timeout* can be used to control the maximum number of seconds to wait " -"before returning. *timeout* can be an int or float. If *timeout* is not " -"specified or ``None``, there is no limit to the wait time." -msgstr "" -"*timeout* 可用於控制回傳前等待的最大秒數。*timeout* 可以是整數或浮點數。如果" -"未指定 *timeout* 或為 ``None``，則等待時間就沒有限制。" - -#: ../../library/concurrent.futures.rst:632 -msgid "" -"*return_when* indicates when this function should return. It must be one of " -"the following constants:" -msgstr "*return_when* 表示此函式應回傳的時間。它必須是以下常數之一：" - -#: ../../library/concurrent.futures.rst:638 -msgid "Constant" -msgstr "常數" - -#: ../../library/concurrent.futures.rst:639 -msgid "Description" -msgstr "描述" - -#: ../../library/concurrent.futures.rst:642 -msgid "The function will return when any future finishes or is cancelled." -msgstr "當任何 future 完成或被取消時，該函式就會回傳。" - -#: ../../library/concurrent.futures.rst:645 -msgid "" -"The function will return when any future finishes by raising an exception. " -"If no future raises an exception then it is equivalent to :const:" -"`ALL_COMPLETED`." -msgstr "" -"該函式會在任何 future 透過引發例外而完結時回傳。如果 future 沒有引發例外，那" -"麼它等同於 :const:`ALL_COMPLETED`。" - -#: ../../library/concurrent.futures.rst:650 -msgid "The function will return when all futures finish or are cancelled." -msgstr "當所有 future 都完成或被取消時，該函式才會回傳。" - -#: ../../library/concurrent.futures.rst:654 -msgid "" -"Returns an iterator over the :class:`Future` instances (possibly created by " -"different :class:`Executor` instances) given by *fs* that yields futures as " -"they complete (finished or cancelled futures). Any futures given by *fs* " -"that are duplicated will be returned once. Any futures that completed " -"before :func:`as_completed` is called will be yielded first. The returned " -"iterator raises a :exc:`TimeoutError` if :meth:`~iterator.__next__` is " -"called and the result isn't available after *timeout* seconds from the " -"original call to :func:`as_completed`. *timeout* can be an int or float. If " -"*timeout* is not specified or ``None``, there is no limit to the wait time." -msgstr "" -"回傳由 *fs* 給定的 :class:`Future` 實例（可能由不同的 :class:`Executor` 實例" -"建立）的疊代器，它在完成時產生 future（已完成或被取消的 future）。*fs* 給定的" -"任何重複的 future 將只被回傳一次。呼叫 :func:`as_completed` 之前完成的任何 " -"future 將首先產生。如果 :meth:`~iterator.__next__` 被呼叫，並且在原先呼叫 :" -"func:`as_completed` 的 *timeout* 秒後結果仍不可用，則回傳的疊代器會引發 :exc:" -"`TimeoutError`。*timeout* 可以是整數或浮點數。如果未指定 *timeout* 或為 " -"``None``，則等待時間就沒有限制。" - -#: ../../library/concurrent.futures.rst:667 -msgid ":pep:`3148` -- futures - execute computations asynchronously" -msgstr ":pep:`3148` -- futures - 非同步地執行運算" - -#: ../../library/concurrent.futures.rst:668 -msgid "" -"The proposal which described this feature for inclusion in the Python " -"standard library." -msgstr "描述此功能並提出被包含於 Python 標準函式庫中的提案。" - -#: ../../library/concurrent.futures.rst:673 -msgid "Exception classes" -msgstr "例外類別" - -#: ../../library/concurrent.futures.rst:679 -msgid "Raised when a future is cancelled." -msgstr "當 future 被取消時引發。" - -#: ../../library/concurrent.futures.rst:683 -msgid "" -"A deprecated alias of :exc:`TimeoutError`, raised when a future operation " -"exceeds the given timeout." -msgstr "" -":exc:`TimeoutError` 的棄用別名，在 future 操作超過給定超時 (timeout) 時引發。" - -#: ../../library/concurrent.futures.rst:688 -msgid "This class was made an alias of :exc:`TimeoutError`." -msgstr "這個類別是 :exc:`TimeoutError` 的別名。" - -#: ../../library/concurrent.futures.rst:693 -msgid "" -"Derived from :exc:`RuntimeError`, this exception class is raised when an " -"executor is broken for some reason, and cannot be used to submit or execute " -"new tasks." -msgstr "" -"衍生自 :exc:`RuntimeError`，當執行器因某種原因損壞時會引發此例外類別，並且不" -"能用於提交或執行新任務。" - -#: ../../library/concurrent.futures.rst:701 -msgid "" -"Raised when an operation is performed on a future that is not allowed in the " -"current state." -msgstr "目前狀態下不允許的 future 操作被執行時而引發。" - -#: ../../library/concurrent.futures.rst:710 -msgid "" -"Derived from :exc:`~concurrent.futures.BrokenExecutor`, this exception class " -"is raised when one of the workers of a :class:`~concurrent.futures." -"ThreadPoolExecutor` has failed initializing." -msgstr "" -"衍生自 :exc:`~concurrent.futures.BrokenExecutor`，當 :class:`~concurrent." -"futures.ThreadPoolExecutor` 的其中一個 worker 初始化失敗時會引發此例外類別。" - -#: ../../library/concurrent.futures.rst:721 -msgid "" -"Derived from :exc:`~concurrent.futures.thread.BrokenThreadPool`, this " -"exception class is raised when one of the workers of a :class:`~concurrent." -"futures.InterpreterPoolExecutor` has failed initializing." -msgstr "" -"衍生自 :exc:`~concurrent.futures.thread.BrokenThreadPool`，當 :class:" -"`~concurrent.futures.InterpreterPoolExecutor` 的其中一個 worker 初始化失敗時" -"會引發此例外類別。" - -#: ../../library/concurrent.futures.rst:732 -msgid "" -"Derived from :exc:`~concurrent.futures.BrokenExecutor` (formerly :exc:" -"`RuntimeError`), this exception class is raised when one of the workers of " -"a :class:`~concurrent.futures.ProcessPoolExecutor` has terminated in a non-" -"clean fashion (for example, if it was killed from the outside)." -msgstr "" -"衍生自 :exc:`~concurrent.futures.BrokenExecutor`\\（以前為 :exc:" -"`RuntimeError`），當 :class:`~concurrent.futures.ProcessPoolExecutor` 的其中" -"一個 worker 以不乾淨的方式終止時將引發此例外類別（例如它是從外面被 kill 掉" -"的）。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Matt Wang , 2023-2024 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-01-11 00:17+0000\n" +"PO-Revision-Date: 2023-01-24 03:33+0800\n" +"Last-Translator: Matt Wang \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" +"X-Generator: Poedit 3.2.2\n" + +#: ../../library/concurrent.futures.rst:2 +msgid ":mod:`!concurrent.futures` --- Launching parallel tasks" +msgstr ":mod:`!concurrent.futures` --- 啟動平行任務" + +#: ../../library/concurrent.futures.rst:9 +msgid "" +"**Source code:** :source:`Lib/concurrent/futures/thread.py`, :source:`Lib/" +"concurrent/futures/process.py`, and :source:`Lib/concurrent/futures/" +"interpreter.py`" +msgstr "" +"**原始碼：**\\ :source:`Lib/concurrent/futures/thread.py`、:source:`Lib/" +"concurrent/futures/process.py` 與 :source:`Lib/concurrent/futures/" +"interpreter.py`" + +#: ../../library/concurrent.futures.rst:15 +msgid "" +"The :mod:`concurrent.futures` module provides a high-level interface for " +"asynchronously executing callables." +msgstr "" +":mod:`concurrent.futures` 模組提供了一個高階介面來非同步地 (asynchronously) " +"執行可呼叫物件 (callable) 。" + +#: ../../library/concurrent.futures.rst:18 +msgid "" +"The asynchronous execution can be performed with threads, using :class:" +"`ThreadPoolExecutor` or :class:`InterpreterPoolExecutor`, or separate " +"processes, using :class:`ProcessPoolExecutor`. Each implements the same " +"interface, which is defined by the abstract :class:`Executor` class." +msgstr "" +"非同步執行可以透過 :class:`ThreadPoolExecutor` 或 :class:" +"`InterpreterPoolExecutor` 來使用執行緒 (thread) 執行，或透過 :class:" +"`ProcessPoolExecutor` 來使用單獨行程 (process) 執行。兩者都實作了相同的介面，" +"該介面由抽象的 :class:`Executor` 類別定義。" + +#: ../../library/concurrent.futures.rst:24 +msgid "" +":class:`concurrent.futures.Future` must not be confused with :class:`asyncio." +"Future`, which is designed for use with :mod:`asyncio` tasks and coroutines. " +"See the :doc:`asyncio's Future ` documentation for a " +"detailed comparison of the two." +msgstr "" + +#: ../../includes/wasm-notavail.rst:3 +msgid "Availability" +msgstr "可用性" + +#: ../../includes/wasm-notavail.rst:5 +msgid "" +"This module does not work or is not available on WebAssembly. See :ref:`wasm-" +"availability` for more information." +msgstr "" +"此模組在 WebAssembly 平台上不起作用或無法使用。更多資訊請參閱 :ref:`wasm-" +"availability`。" + +#: ../../library/concurrent.futures.rst:32 +msgid "Executor Objects" +msgstr "Executor 物件" + +#: ../../library/concurrent.futures.rst:36 +msgid "" +"An abstract class that provides methods to execute calls asynchronously. It " +"should not be used directly, but through its concrete subclasses." +msgstr "" +"提供非同步執行呼叫方法的抽象類別。不應直接使用它，而應透過其具體子類別來使" +"用。" + +#: ../../library/concurrent.futures.rst:41 +msgid "" +"Schedules the callable, *fn*, to be executed as ``fn(*args, **kwargs)`` and " +"returns a :class:`Future` object representing the execution of the " +"callable. ::" +msgstr "" +"為可呼叫物件 *fn* 排程來以 ``fn(*args, **kwargs)`` 的形式執行並回傳一個表示可" +"呼叫的執行的 :class:`Future` 物件。 ::" + +#: ../../library/concurrent.futures.rst:45 +msgid "" +"with ThreadPoolExecutor(max_workers=1) as executor:\n" +" future = executor.submit(pow, 323, 1235)\n" +" print(future.result())" +msgstr "" +"with ThreadPoolExecutor(max_workers=1) as executor:\n" +" future = executor.submit(pow, 323, 1235)\n" +" print(future.result())" + +#: ../../library/concurrent.futures.rst:51 +msgid "Similar to :func:`map(fn, *iterables) ` except:" +msgstr "類似於 :func:`map(fn, *iterables) `，除了：" + +#: ../../library/concurrent.futures.rst:53 +msgid "" +"The *iterables* are collected immediately rather than lazily, unless a " +"*buffersize* is specified to limit the number of submitted tasks whose " +"results have not yet been yielded. If the buffer is full, iteration over the " +"*iterables* pauses until a result is yielded from the buffer." +msgstr "" + +#: ../../library/concurrent.futures.rst:58 +msgid "" +"*fn* is executed asynchronously and several calls to *fn* may be made " +"concurrently." +msgstr "*fn* 是非同步執行的，並且對 *fn* 的多次呼叫可以並行處理。" + +#: ../../library/concurrent.futures.rst:61 +msgid "" +"The returned iterator raises a :exc:`TimeoutError` if :meth:`~iterator." +"__next__` is called and the result isn't available after *timeout* seconds " +"from the original call to :meth:`Executor.map`. *timeout* can be an int or a " +"float. If *timeout* is not specified or ``None``, there is no limit to the " +"wait time." +msgstr "" +"如果 :meth:`~iterator.__next__` 被呼叫，且在原先呼叫 :meth:`Executor.map` 的 " +"*timeout* 秒後結果仍不可用，回傳的疊代器就會引發 :exc:`TimeoutError`。" +"*timeout* 可以是整數或浮點數。如果未指定 *timeout* 或為 ``None``，則等待時間" +"就不會有限制。" + +#: ../../library/concurrent.futures.rst:67 +msgid "" +"If a *fn* call raises an exception, then that exception will be raised when " +"its value is retrieved from the iterator." +msgstr "如果 *fn* 呼叫引發例外，則當從疊代器中檢索到它的值時將引發該例外。" + +#: ../../library/concurrent.futures.rst:70 +msgid "" +"When using :class:`ProcessPoolExecutor`, this method chops *iterables* into " +"a number of chunks which it submits to the pool as separate tasks. The " +"(approximate) size of these chunks can be specified by setting *chunksize* " +"to a positive integer. For very long iterables, using a large value for " +"*chunksize* can significantly improve performance compared to the default " +"size of 1. With :class:`ThreadPoolExecutor` and :class:" +"`InterpreterPoolExecutor`, *chunksize* has no effect." +msgstr "" +"使用 :class:`ProcessPoolExecutor` 時，此方法將 *iterables* 分成許多分塊 " +"(chunks)，並將其作為獨立的任務來提交給池 (pool)。可以透過將 *chunksize* 設定" +"為正整數來指定這些分塊的（約略）大小。對於非常長的可疊代物件，*chunksize* 使" +"用較大的值（與預設大小 1 相比）可以顯著提高性能。對於 :class:" +"`ThreadPoolExecutor` 和 :class:`InterpreterPoolExecutor`，*chunksize* 無效。" + +#: ../../library/concurrent.futures.rst:79 +msgid "Added the *chunksize* parameter." +msgstr "新增 *chunksize* 參數。" + +#: ../../library/concurrent.futures.rst:82 +msgid "Added the *buffersize* parameter." +msgstr "新增 *buffersize* 參數。" + +#: ../../library/concurrent.futures.rst:87 +msgid "" +"Signal the executor that it should free any resources that it is using when " +"the currently pending futures are done executing. Calls to :meth:`Executor." +"submit` and :meth:`Executor.map` made after shutdown will raise :exc:" +"`RuntimeError`." +msgstr "" +"向 executor 發出訊號 (signal)，表明它應該在目前未定 (pending) 的 future 完成" +"執行時釋放它正在使用的任何資源。在關閉後呼叫 :meth:`Executor.submit` 和 :" +"meth:`Executor.map` 將引發 :exc:`RuntimeError`。" + +#: ../../library/concurrent.futures.rst:92 +msgid "" +"If *wait* is ``True`` then this method will not return until all the pending " +"futures are done executing and the resources associated with the executor " +"have been freed. If *wait* is ``False`` then this method will return " +"immediately and the resources associated with the executor will be freed " +"when all pending futures are done executing. Regardless of the value of " +"*wait*, the entire Python program will not exit until all pending futures " +"are done executing." +msgstr "" +"如果 *wait* 為 ``True`` 則此方法將不會回傳，直到所有未定的 futures 完成執行並" +"且與 executor 關聯的資源都被釋放。如果 *wait* 為 ``False`` 則此方法將立即回" +"傳，並且當所有未定的 future 執行完畢時，與 executor 關聯的資源將被釋放。不管 " +"*wait* 的值如何，整個 Python 程式都不會退出，直到所有未定的 futures 執行完" +"畢。" + +#: ../../library/concurrent.futures.rst:100 +msgid "" +"If *cancel_futures* is ``True``, this method will cancel all pending futures " +"that the executor has not started running. Any futures that are completed or " +"running won't be cancelled, regardless of the value of *cancel_futures*." +msgstr "" +"如果 *cancel_futures* 為 ``True``，此方法將取消 executor 尚未開始運行的所有未" +"定 future。無論 *cancel_futures* 的值如何，任何已完成或正在運行的 future 都不" +"會被取消。" + +#: ../../library/concurrent.futures.rst:105 +msgid "" +"If both *cancel_futures* and *wait* are ``True``, all futures that the " +"executor has started running will be completed prior to this method " +"returning. The remaining futures are cancelled." +msgstr "" +"如果 *cancel_futures* 和 *wait* 都為 ``True``，則 executor 已開始運行的所有 " +"future 將在此方法回傳之前完成。剩餘的 future 被取消。" + +#: ../../library/concurrent.futures.rst:109 +msgid "" +"You can avoid having to call this method explicitly if you use the executor " +"as a :term:`context manager` via the :keyword:`with` statement, which will " +"shutdown the :class:`Executor` (waiting as if :meth:`Executor.shutdown` were " +"called with *wait* set to ``True``)::" +msgstr "" +"如果使用 :keyword:`with` 陳述式來將 executor 用作 :term:`context manager`，那" +"你就可以不用明確地呼叫此方法，這將會自己關閉 :class:`Executor`\\（如同呼叫 :" +"meth:`Executor.shutdown` 時 *wait* 被設定為 ``True`` 般等待）： ::" + +#: ../../library/concurrent.futures.rst:114 +msgid "" +"import shutil\n" +"with ThreadPoolExecutor(max_workers=4) as e:\n" +" e.submit(shutil.copy, 'src1.txt', 'dest1.txt')\n" +" e.submit(shutil.copy, 'src2.txt', 'dest2.txt')\n" +" e.submit(shutil.copy, 'src3.txt', 'dest3.txt')\n" +" e.submit(shutil.copy, 'src4.txt', 'dest4.txt')" +msgstr "" +"import shutil\n" +"with ThreadPoolExecutor(max_workers=4) as e:\n" +" e.submit(shutil.copy, 'src1.txt', 'dest1.txt')\n" +" e.submit(shutil.copy, 'src2.txt', 'dest2.txt')\n" +" e.submit(shutil.copy, 'src3.txt', 'dest3.txt')\n" +" e.submit(shutil.copy, 'src4.txt', 'dest4.txt')" + +#: ../../library/concurrent.futures.rst:121 +msgid "Added *cancel_futures*." +msgstr "新增 *cancel_futures*。" + +#: ../../library/concurrent.futures.rst:126 +msgid "ThreadPoolExecutor" +msgstr "ThreadPoolExecutor" + +#: ../../library/concurrent.futures.rst:128 +msgid "" +":class:`ThreadPoolExecutor` is an :class:`Executor` subclass that uses a " +"pool of threads to execute calls asynchronously." +msgstr "" +":class:`ThreadPoolExecutor` 是一個 :class:`Executor` 子類別，它使用執行緒池來" +"非同步地執行呼叫。" + +#: ../../library/concurrent.futures.rst:131 +msgid "" +"Deadlocks can occur when the callable associated with a :class:`Future` " +"waits on the results of another :class:`Future`. For example::" +msgstr "" +"當與 :class:`Future` 關聯的可呼叫物件等待另一個 :class:`Future` 的結果時，可" +"能會發生死鎖 (deadlock)。例如： ::" + +#: ../../library/concurrent.futures.rst:134 +msgid "" +"import time\n" +"def wait_on_b():\n" +" time.sleep(5)\n" +" print(b.result()) # b will never complete because it is waiting on a.\n" +" return 5\n" +"\n" +"def wait_on_a():\n" +" time.sleep(5)\n" +" print(a.result()) # a will never complete because it is waiting on b.\n" +" return 6\n" +"\n" +"\n" +"executor = ThreadPoolExecutor(max_workers=2)\n" +"a = executor.submit(wait_on_b)\n" +"b = executor.submit(wait_on_a)" +msgstr "" +"import time\n" +"def wait_on_b():\n" +" time.sleep(5)\n" +" print(b.result()) # b 永遠不會完成，因為它正在等待 a。\n" +" return 5\n" +"\n" +"def wait_on_a():\n" +" time.sleep(5)\n" +" print(a.result()) # a 永遠不會完成，因為它正在等待 b。\n" +" return 6\n" +"\n" +"\n" +"executor = ThreadPoolExecutor(max_workers=2)\n" +"a = executor.submit(wait_on_b)\n" +"b = executor.submit(wait_on_a)" + +#: ../../library/concurrent.futures.rst:150 +msgid "And::" +msgstr "和： ::" + +#: ../../library/concurrent.futures.rst:152 +msgid "" +"def wait_on_future():\n" +" f = executor.submit(pow, 5, 2)\n" +" # This will never complete because there is only one worker thread and\n" +" # it is executing this function.\n" +" print(f.result())\n" +"\n" +"executor = ThreadPoolExecutor(max_workers=1)\n" +"executor.submit(wait_on_future)" +msgstr "" +"def wait_on_future():\n" +" f = executor.submit(pow, 5, 2)\n" +" # 這將永遠不會完成，因為只有一個工作執行緒且\n" +" # 它正在執行這個函式。\n" +" print(f.result())\n" +"\n" +"executor = ThreadPoolExecutor(max_workers=1)\n" +"executor.submit(wait_on_future)" + +#: ../../library/concurrent.futures.rst:164 +msgid "" +"An :class:`Executor` subclass that uses a pool of at most *max_workers* " +"threads to execute calls asynchronously." +msgstr "" +"一個 :class:`Executor` 子類別，它使用最多有 *max_workers* 個執行緒的池來非同" +"步地執行呼叫。" + +#: ../../library/concurrent.futures.rst:167 +msgid "" +"All threads enqueued to ``ThreadPoolExecutor`` will be joined before the " +"interpreter can exit. Note that the exit handler which does this is executed " +"*before* any exit handlers added using ``atexit``. This means exceptions in " +"the main thread must be caught and handled in order to signal threads to " +"exit gracefully. For this reason, it is recommended that " +"``ThreadPoolExecutor`` not be used for long-running tasks." +msgstr "" +"所有排隊到 ``ThreadPoolExecutor`` 的執行緒都將在直譯器退出之前加入。請注意，" +"執行此操作的退出處理程式會在任何使用 ``atexit`` 新增的退出處理程式\\ *之前" +"*\\ 執行。這意味著必須捕獲並處理主執行緒中的例外，以便向執行緒發出訊號來正常" +"退出 (gracefully exit)。因此，建議不要將 ``ThreadPoolExecutor`` 用於長時間運" +"行的任務。" + +#: ../../library/concurrent.futures.rst:174 +msgid "" +"*initializer* is an optional callable that is called at the start of each " +"worker thread; *initargs* is a tuple of arguments passed to the " +"initializer. Should *initializer* raise an exception, all currently pending " +"jobs will raise a :exc:`~concurrent.futures.thread.BrokenThreadPool`, as " +"well as any attempt to submit more jobs to the pool." +msgstr "" +"*initializer* 是一個可選的可呼叫物件，在每個工作執行緒開始時呼叫； " +"*initargs* 是傳遞給 initializer 的引數元組 (tuple)。如果 *initializer* 引發例" +"外，所有目前未定的作業以及任何向池中提交 (submit) 更多作業的嘗試都將引發 :" +"exc:`~concurrent.futures.thread.BrokenThreadPool`。" + +#: ../../library/concurrent.futures.rst:180 +msgid "" +"If *max_workers* is ``None`` or not given, it will default to the number of " +"processors on the machine, multiplied by ``5``, assuming that :class:" +"`ThreadPoolExecutor` is often used to overlap I/O instead of CPU work and " +"the number of workers should be higher than the number of workers for :class:" +"`ProcessPoolExecutor`." +msgstr "" +"如果 *max_workers* 為 ``None`` 或未給定，它將預設為機器上的處理器數量乘以 " +"``5``，這假定了 :class:`ThreadPoolExecutor` 通常用於 I/O 重疊而非 CPU 密集的" +"作業，並且 worker 的數量應該高於 :class:`ProcessPoolExecutor` 的 worker 數" +"量。" + +#: ../../library/concurrent.futures.rst:188 +msgid "" +"Added the *thread_name_prefix* parameter to allow users to control the :" +"class:`threading.Thread` names for worker threads created by the pool for " +"easier debugging." +msgstr "" +"新增 *thread_name_prefix* 參數以允許使用者控制由池所建立的工作執行緒 (worker " +"thread) 的 :class:`threading.Thread` 名稱，以便於除錯。" + +#: ../../library/concurrent.futures.rst:193 +#: ../../library/concurrent.futures.rst:403 +msgid "Added the *initializer* and *initargs* arguments." +msgstr "新增 *initializer* 與 *initargs* 引數。" + +#: ../../library/concurrent.futures.rst:196 +msgid "" +"Default value of *max_workers* is changed to ``min(32, os.cpu_count() + " +"4)``. This default value preserves at least 5 workers for I/O bound tasks. " +"It utilizes at most 32 CPU cores for CPU bound tasks which release the GIL. " +"And it avoids using very large resources implicitly on many-core machines." +msgstr "" +"*max_workers* 的預設值改為 ``min(32, os.cpu_count() + 4)``。此預設值為 I/O 密" +"集任務至少保留了 5 個 worker。它最多使用 32 個 CPU 核心來執行CPU 密集任務，以" +"釋放 GIL。並且它避免了在多核機器上隱晦地使用非常大量的資源。" + +#: ../../library/concurrent.futures.rst:202 +msgid "" +"ThreadPoolExecutor now reuses idle worker threads before starting " +"*max_workers* worker threads too." +msgstr "" +"ThreadPoolExecutor 現在在啟動 *max_workers* 工作執行緒之前會重用 (reuse) 空閒" +"的工作執行緒。" + +#: ../../library/concurrent.futures.rst:205 +msgid "" +"Default value of *max_workers* is changed to ``min(32, (os." +"process_cpu_count() or 1) + 4)``." +msgstr "" +"*max_workers* 的預設值被改為 ``min(32, (os.process_cpu_count() or 1) + 4)``。" + +#: ../../library/concurrent.futures.rst:213 +msgid "ThreadPoolExecutor Example" +msgstr "ThreadPoolExecutor 範例" + +#: ../../library/concurrent.futures.rst:216 +msgid "" +"import concurrent.futures\n" +"import urllib.request\n" +"\n" +"URLS = ['http://www.foxnews.com/',\n" +" 'http://www.cnn.com/',\n" +" 'http://europe.wsj.com/',\n" +" 'http://www.bbc.co.uk/',\n" +" 'http://nonexistent-subdomain.python.org/']\n" +"\n" +"# Retrieve a single page and report the URL and contents\n" +"def load_url(url, timeout):\n" +" with urllib.request.urlopen(url, timeout=timeout) as conn:\n" +" return conn.read()\n" +"\n" +"# We can use a with statement to ensure threads are cleaned up promptly\n" +"with concurrent.futures.ThreadPoolExecutor(max_workers=5) as executor:\n" +" # Start the load operations and mark each future with its URL\n" +" future_to_url = {executor.submit(load_url, url, 60): url for url in " +"URLS}\n" +" for future in concurrent.futures.as_completed(future_to_url):\n" +" url = future_to_url[future]\n" +" try:\n" +" data = future.result()\n" +" except Exception as exc:\n" +" print('%r generated an exception: %s' % (url, exc))\n" +" else:\n" +" print('%r page is %d bytes' % (url, len(data)))" +msgstr "" + +#: ../../library/concurrent.futures.rst:245 +msgid "InterpreterPoolExecutor" +msgstr "InterpreterPoolExecutor" + +#: ../../library/concurrent.futures.rst:249 +msgid "" +"The :class:`InterpreterPoolExecutor` class uses a pool of interpreters to " +"execute calls asynchronously. It is a :class:`ThreadPoolExecutor` subclass, " +"which means each worker is running in its own thread. The difference here is " +"that each worker has its own interpreter, and runs each task using that " +"interpreter." +msgstr "" + +#: ../../library/concurrent.futures.rst:255 +msgid "" +"The biggest benefit to using interpreters instead of only threads is true " +"multi-core parallelism. Each interpreter has its own :term:`Global " +"Interpreter Lock `, so code running in one " +"interpreter can run on one CPU core, while code in another interpreter runs " +"unblocked on a different core." +msgstr "" + +#: ../../library/concurrent.futures.rst:261 +msgid "" +"The tradeoff is that writing concurrent code for use with multiple " +"interpreters can take extra effort. However, this is because it forces you " +"to be deliberate about how and when interpreters interact, and to be " +"explicit about what data is shared between interpreters. This results in " +"several benefits that help balance the extra effort, including true multi-" +"core parallelism, For example, code written this way can make it easier to " +"reason about concurrency. Another major benefit is that you don't have to " +"deal with several of the big pain points of using threads, like race " +"conditions." +msgstr "" + +#: ../../library/concurrent.futures.rst:271 +msgid "" +"Each worker's interpreter is isolated from all the other interpreters. " +"\"Isolated\" means each interpreter has its own runtime state and operates " +"completely independently. For example, if you redirect :data:`sys.stdout` " +"in one interpreter, it will not be automatically redirected to any other " +"interpreter. If you import a module in one interpreter, it is not " +"automatically imported in any other. You would need to import the module " +"separately in interpreter where you need it. In fact, each module imported " +"in an interpreter is a completely separate object from the same module in a " +"different interpreter, including :mod:`sys`, :mod:`builtins`, and even " +"``__main__``." +msgstr "" + +#: ../../library/concurrent.futures.rst:283 +msgid "" +"Isolation means a mutable object, or other data, cannot be used by more than " +"one interpreter at the same time. That effectively means interpreters " +"cannot actually share such objects or data. Instead, each interpreter must " +"have its own copy, and you will have to synchronize any changes between the " +"copies manually. Immutable objects and data, like the builtin singletons, " +"strings, and tuples of immutable objects, don't have these limitations." +msgstr "" + +#: ../../library/concurrent.futures.rst:291 +msgid "" +"Communicating and synchronizing between interpreters is most effectively " +"done using dedicated tools, like those proposed in :pep:`734`. One less " +"efficient alternative is to serialize with :mod:`pickle` and then send the " +"bytes over a shared :mod:`socket ` or :func:`pipe `." +msgstr "" + +#: ../../library/concurrent.futures.rst:299 +msgid "" +"A :class:`ThreadPoolExecutor` subclass that executes calls asynchronously " +"using a pool of at most *max_workers* threads. Each thread runs tasks in " +"its own interpreter. The worker interpreters are isolated from each other, " +"which means each has its own runtime state and that they can't share any " +"mutable objects or other data. Each interpreter has its own :term:`Global " +"Interpreter Lock `, which means code run with this " +"executor has true multi-core parallelism." +msgstr "" + +#: ../../library/concurrent.futures.rst:307 +msgid "" +"The optional *initializer* and *initargs* arguments have the same meaning as " +"for :class:`!ThreadPoolExecutor`: the initializer is run when each worker is " +"created, though in this case it is run in the worker's interpreter. The " +"executor serializes the *initializer* and *initargs* using :mod:`pickle` " +"when sending them to the worker's interpreter." +msgstr "" + +#: ../../library/concurrent.futures.rst:315 +msgid "" +"The executor may replace uncaught exceptions from *initializer* with :class:" +"`~concurrent.interpreters.ExecutionFailed`." +msgstr "" + +#: ../../library/concurrent.futures.rst:318 +msgid "Other caveats from parent :class:`ThreadPoolExecutor` apply here." +msgstr "" + +#: ../../library/concurrent.futures.rst:320 +msgid "" +":meth:`~Executor.submit` and :meth:`~Executor.map` work like normal, except " +"the worker serializes the callable and arguments using :mod:`pickle` when " +"sending them to its interpreter. The worker likewise serializes the return " +"value when sending it back." +msgstr "" + +#: ../../library/concurrent.futures.rst:325 +msgid "" +"When a worker's current task raises an uncaught exception, the worker always " +"tries to preserve the exception as-is. If that is successful then it also " +"sets the ``__cause__`` to a corresponding :class:`~concurrent.interpreters." +"ExecutionFailed` instance, which contains a summary of the original " +"exception. In the uncommon case that the worker is not able to preserve the " +"original as-is then it directly preserves the corresponding :class:" +"`~concurrent.interpreters.ExecutionFailed` instance instead." +msgstr "" + +#: ../../library/concurrent.futures.rst:337 +msgid "ProcessPoolExecutor" +msgstr "ProcessPoolExecutor" + +#: ../../library/concurrent.futures.rst:339 +msgid "" +"The :class:`ProcessPoolExecutor` class is an :class:`Executor` subclass that " +"uses a pool of processes to execute calls asynchronously. :class:" +"`ProcessPoolExecutor` uses the :mod:`multiprocessing` module, which allows " +"it to side-step the :term:`Global Interpreter Lock ` but also means that only picklable objects can be executed and " +"returned." +msgstr "" +":class:`ProcessPoolExecutor` 類別是一個 :class:`Executor` 的子類別，它使用行" +"程池來非同步地執行呼叫。:class:`ProcessPoolExecutor` 使用了 :mod:" +"`multiprocessing` 模組，這允許它避開\\ :term:`全域直譯器鎖 (Global " +"Interpreter Lock) `，但也意味著只能執行和回傳可被 " +"pickle 的 (picklable) 物件。" + +#: ../../library/concurrent.futures.rst:346 +msgid "" +"The ``__main__`` module must be importable by worker subprocesses. This " +"means that :class:`ProcessPoolExecutor` will not work in the interactive " +"interpreter." +msgstr "" +"``__main__`` 模組必須可以被工作子行程 (worker subprocess) 引入。這意味著 :" +"class:`ProcessPoolExecutor` 將無法在交互式直譯器 (interactive interpreter) 中" +"工作。" + +#: ../../library/concurrent.futures.rst:349 +msgid "" +"Calling :class:`Executor` or :class:`Future` methods from a callable " +"submitted to a :class:`ProcessPoolExecutor` will result in deadlock." +msgstr "" +"從提交給 :class:`ProcessPoolExecutor` 的可呼叫物件中呼叫 :class:`Executor` " +"或 :class:`Future` 方法將導致死鎖。" + +#: ../../library/concurrent.futures.rst:352 +msgid "" +"Note that the restrictions on functions and arguments needing to picklable " +"as per :class:`multiprocessing.Process` apply when using :meth:`~Executor." +"submit` and :meth:`~Executor.map` on a :class:`ProcessPoolExecutor`. A " +"function defined in a REPL or a lambda should not be expected to work." +msgstr "" + +#: ../../library/concurrent.futures.rst:359 +msgid "" +"An :class:`Executor` subclass that executes calls asynchronously using a " +"pool of at most *max_workers* processes. If *max_workers* is ``None`` or " +"not given, it will default to :func:`os.process_cpu_count`. If *max_workers* " +"is less than or equal to ``0``, then a :exc:`ValueError` will be raised. On " +"Windows, *max_workers* must be less than or equal to ``61``. If it is not " +"then :exc:`ValueError` will be raised. If *max_workers* is ``None``, then " +"the default chosen will be at most ``61``, even if more processors are " +"available. *mp_context* can be a :mod:`multiprocessing` context or ``None``. " +"It will be used to launch the workers. If *mp_context* is ``None`` or not " +"given, the default :mod:`multiprocessing` context is used. See :ref:" +"`multiprocessing-start-methods`." +msgstr "" +"一個 :class:`Executor` 子類別，它使用了最多有 *max_workers* 個行程的池來非同" +"步地執行呼叫。如果 *max_workers* 為 ``None`` 或未給定，它將被預設為 :func:" +"`os.process_cpu_count`。如果 *max_workers* 小於或等於 ``0``，則會引發 :exc:" +"`ValueError`。在 Windows 上，*max_workers* 必須小於或等於 ``61``。如果不是，" +"則會引發 :exc:`ValueError`。如果 *max_workers* 為 ``None``，則預設選擇最多為 " +"``61``，即便有更多處理器可用。*mp_context* 可以是 :mod:`multiprocessing` 情" +"境 (context) 或 ``None``。它將用於啟動 worker。如果 *mp_context* 為 ``None`` " +"或未給定，則使用預設的 :mod:`multiprocessing` 情境。請見 :ref:" +"`multiprocessing-start-methods`。" + +#: ../../library/concurrent.futures.rst:373 +msgid "" +"*initializer* is an optional callable that is called at the start of each " +"worker process; *initargs* is a tuple of arguments passed to the " +"initializer. Should *initializer* raise an exception, all currently pending " +"jobs will raise a :exc:`~concurrent.futures.process.BrokenProcessPool`, as " +"well as any attempt to submit more jobs to the pool." +msgstr "" +"*initializer* 是一個可選的可呼叫物件，在每個工作行程 (worker process) 開始時" +"呼叫；*initargs* 是傳遞給 initializer 的引數元組。如果 *initializer* 引發例" +"外，所有目前未定的作業以及任何向池中提交更多作業的嘗試都將引發 :exc:" +"`~concurrent.futures.process.BrokenProcessPool`。" + +#: ../../library/concurrent.futures.rst:379 +msgid "" +"*max_tasks_per_child* is an optional argument that specifies the maximum " +"number of tasks a single process can execute before it will exit and be " +"replaced with a fresh worker process. By default *max_tasks_per_child* is " +"``None`` which means worker processes will live as long as the pool. When a " +"max is specified, the \"spawn\" multiprocessing start method will be used by " +"default in absence of a *mp_context* parameter. This feature is incompatible " +"with the \"fork\" start method." +msgstr "" +"*max_tasks_per_child* 是一個可選引數，它指定單個行程在退出並被新的工作行程替" +"換之前可以執行的最大任務數。預設情況下 *max_tasks_per_child* 是 ``None``，這" +"意味著工作行程的生命週期將與池一樣長。當指定最大值時，在沒有 *mp_context* 參" +"數的情況下，將預設使用 \"spawn\" 做為 multiprocessing 啟動方法。此功能與 " +"\"fork\" 啟動方法不相容。" + +#: ../../library/concurrent.futures.rst:388 +msgid "" +"Bugs have been reported when using the *max_tasks_per_child* feature that " +"can result in the :class:`ProcessPoolExecutor` hanging in some " +"circumstances. Follow its eventual resolution in :gh:`115634`." +msgstr "" + +#: ../../library/concurrent.futures.rst:392 +msgid "" +"When one of the worker processes terminates abruptly, a :exc:`~concurrent." +"futures.process.BrokenProcessPool` error is now raised. Previously, " +"behaviour was undefined but operations on the executor or its futures would " +"often freeze or deadlock." +msgstr "" +"當其中一個工作行程突然終止時，現在會引發 :exc:`~concurrent.futures.process." +"BrokenProcessPool` 錯誤。在過去，此行為是未定義的 (undefined)，但對 executor " +"或其 future 的操作經常會發生凍結或死鎖。" + +#: ../../library/concurrent.futures.rst:399 +msgid "" +"The *mp_context* argument was added to allow users to control the " +"start_method for worker processes created by the pool." +msgstr "" +"新增了 *mp_context* 引數以允許使用者控制由池所建立的工作行程的 start_method。" + +#: ../../library/concurrent.futures.rst:405 +msgid "" +"The *max_tasks_per_child* argument was added to allow users to control the " +"lifetime of workers in the pool." +msgstr "" +"新增了 *max_tasks_per_child* 引數以允許使用者控制池中 worker 的生命週期。" + +#: ../../library/concurrent.futures.rst:409 +msgid "" +"On POSIX systems, if your application has multiple threads and the :mod:" +"`multiprocessing` context uses the ``\"fork\"`` start method: The :func:`os." +"fork` function called internally to spawn workers may raise a :exc:" +"`DeprecationWarning`. Pass a *mp_context* configured to use a different " +"start method. See the :func:`os.fork` documentation for further explanation." +msgstr "" +"在 POSIX 系統上，如果你的應用程式有多個執行緒並且 :mod:`multiprocessing` 情境" +"使用了 ``\"fork\"`` 啟動方法：內部呼叫以產生 worker 的 :func:`os.fork` 函式可" +"能會引發 :exc:`DeprecationWarning`。傳遞一個 *mp_context* 以配置為使用不同的" +"啟動方法。更多說明請參閱 :func:`os.fork` 文件。" + +#: ../../library/concurrent.futures.rst:417 +msgid "" +"*max_workers* uses :func:`os.process_cpu_count` by default, instead of :func:" +"`os.cpu_count`." +msgstr "" + +#: ../../library/concurrent.futures.rst:421 +msgid "" +"The default process start method (see :ref:`multiprocessing-start-methods`) " +"changed away from *fork*. If you require the *fork* start method for :class:" +"`ProcessPoolExecutor` you must explicitly pass ``mp_context=multiprocessing." +"get_context(\"fork\")``." +msgstr "" + +#: ../../library/concurrent.futures.rst:429 +msgid "" +"Attempt to terminate all living worker processes immediately by calling :" +"meth:`Process.terminate ` on each of " +"them. Internally, it will also call :meth:`Executor.shutdown` to ensure that " +"all other resources associated with the executor are freed." +msgstr "" + +#: ../../library/concurrent.futures.rst:434 +#: ../../library/concurrent.futures.rst:446 +msgid "" +"After calling this method the caller should no longer submit tasks to the " +"executor." +msgstr "" + +#: ../../library/concurrent.futures.rst:441 +msgid "" +"Attempt to kill all living worker processes immediately by calling :meth:" +"`Process.kill ` on each of them. Internally, " +"it will also call :meth:`Executor.shutdown` to ensure that all other " +"resources associated with the executor are freed." +msgstr "" + +#: ../../library/concurrent.futures.rst:454 +msgid "ProcessPoolExecutor Example" +msgstr "ProcessPoolExecutor 範例" + +#: ../../library/concurrent.futures.rst:457 +msgid "" +"import concurrent.futures\n" +"import math\n" +"\n" +"PRIMES = [\n" +" 112272535095293,\n" +" 112582705942171,\n" +" 112272535095293,\n" +" 115280095190773,\n" +" 115797848077099,\n" +" 1099726899285419]\n" +"\n" +"def is_prime(n):\n" +" if n < 2:\n" +" return False\n" +" if n == 2:\n" +" return True\n" +" if n % 2 == 0:\n" +" return False\n" +"\n" +" sqrt_n = int(math.floor(math.sqrt(n)))\n" +" for i in range(3, sqrt_n + 1, 2):\n" +" if n % i == 0:\n" +" return False\n" +" return True\n" +"\n" +"def main():\n" +" with concurrent.futures.ProcessPoolExecutor() as executor:\n" +" for number, prime in zip(PRIMES, executor.map(is_prime, PRIMES)):\n" +" print('%d is prime: %s' % (number, prime))\n" +"\n" +"if __name__ == '__main__':\n" +" main()" +msgstr "" +"import concurrent.futures\n" +"import math\n" +"\n" +"PRIMES = [\n" +" 112272535095293,\n" +" 112582705942171,\n" +" 112272535095293,\n" +" 115280095190773,\n" +" 115797848077099,\n" +" 1099726899285419]\n" +"\n" +"def is_prime(n):\n" +" if n < 2:\n" +" return False\n" +" if n == 2:\n" +" return True\n" +" if n % 2 == 0:\n" +" return False\n" +"\n" +" sqrt_n = int(math.floor(math.sqrt(n)))\n" +" for i in range(3, sqrt_n + 1, 2):\n" +" if n % i == 0:\n" +" return False\n" +" return True\n" +"\n" +"def main():\n" +" with concurrent.futures.ProcessPoolExecutor() as executor:\n" +" for number, prime in zip(PRIMES, executor.map(is_prime, PRIMES)):\n" +" print('%d is prime: %s' % (number, prime))\n" +"\n" +"if __name__ == '__main__':\n" +" main()" + +#: ../../library/concurrent.futures.rst:492 +msgid "Future Objects" +msgstr "Future 物件" + +#: ../../library/concurrent.futures.rst:494 +msgid "" +"The :class:`Future` class encapsulates the asynchronous execution of a " +"callable. :class:`Future` instances are created by :meth:`Executor.submit`." +msgstr "" +":class:`Future` 類別封裝了可呼叫物件的非同步執行。:class:`Future` 實例由 :" +"meth:`Executor.submit` 建立。" + +#: ../../library/concurrent.futures.rst:499 +msgid "" +"Encapsulates the asynchronous execution of a callable. :class:`Future` " +"instances are created by :meth:`Executor.submit` and should not be created " +"directly except for testing." +msgstr "" +"封裝可呼叫物件的非同步執行。:class:`Future` 實例由 :meth:`Executor.submit` 建" +"立，且除測試外不應直接建立。" + +#: ../../library/concurrent.futures.rst:505 +msgid "" +"Attempt to cancel the call. If the call is currently being executed or " +"finished running and cannot be cancelled then the method will return " +"``False``, otherwise the call will be cancelled and the method will return " +"``True``." +msgstr "" +"嘗試取消呼叫。如果呼叫目前正在執行或已完成運行且無法取消，則該方法將回傳 " +"``False``，否則呼叫將被取消並且該方法將回傳 ``True``。" + +#: ../../library/concurrent.futures.rst:512 +msgid "Return ``True`` if the call was successfully cancelled." +msgstr "如果該呼叫成功被取消，則回傳 ``True``。" + +#: ../../library/concurrent.futures.rst:516 +msgid "" +"Return ``True`` if the call is currently being executed and cannot be " +"cancelled." +msgstr "如果呼叫正在執行且無法取消，則回傳 ``True``。" + +#: ../../library/concurrent.futures.rst:521 +msgid "" +"Return ``True`` if the call was successfully cancelled or finished running." +msgstr "如果呼叫成功被取消或結束運行，則回傳 ``True``。" + +#: ../../library/concurrent.futures.rst:526 +msgid "" +"Return the value returned by the call. If the call hasn't yet completed then " +"this method will wait up to *timeout* seconds. If the call hasn't completed " +"in *timeout* seconds, then a :exc:`TimeoutError` will be raised. *timeout* " +"can be an int or float. If *timeout* is not specified or ``None``, there is " +"no limit to the wait time." +msgstr "" +"回傳該呼叫回傳的值。如果呼叫尚未完成，則此方法將等待至多 *timeout* 秒。如果呼" +"叫在 *timeout* 秒內未完成，則會引發 :exc:`TimeoutError`。*timeout* 可以是整數" +"或浮點數。如果未指定 *timeout* 或為 ``None``，則等待時間就不會有限制。" + +#: ../../library/concurrent.futures.rst:533 +#: ../../library/concurrent.futures.rst:547 +msgid "" +"If the future is cancelled before completing then :exc:`.CancelledError` " +"will be raised." +msgstr "如果 future 在完成之前被取消，那麼 :exc:`.CancelledError` 將被引發。" + +#: ../../library/concurrent.futures.rst:536 +msgid "" +"If the call raised an exception, this method will raise the same exception." +msgstr "如果該呼叫引發了例外，此方法將引發相同的例外。" + +#: ../../library/concurrent.futures.rst:540 +msgid "" +"Return the exception raised by the call. If the call hasn't yet completed " +"then this method will wait up to *timeout* seconds. If the call hasn't " +"completed in *timeout* seconds, then a :exc:`TimeoutError` will be raised. " +"*timeout* can be an int or float. If *timeout* is not specified or " +"``None``, there is no limit to the wait time." +msgstr "" +"回傳該呼叫引發的例外。如果呼叫尚未完成，則此方法將等待至多 *timeout* 秒。如果" +"呼叫在 *timeout* 秒內未完成，則會引發 :exc:`TimeoutError`。 *timeout* 可以是" +"整數或浮點數。如果未指定 *timeout* 或為 ``None``，則等待時間就不會有限制。" + +#: ../../library/concurrent.futures.rst:550 +msgid "If the call completed without raising, ``None`` is returned." +msgstr "如果呼叫在沒有引發的情況下完成，則回傳 ``None``。" + +#: ../../library/concurrent.futures.rst:554 +msgid "" +"Attaches the callable *fn* to the future. *fn* will be called, with the " +"future as its only argument, when the future is cancelled or finishes " +"running." +msgstr "" +"將可呼叫的 *fn* 附加到 future 上。當 future 被取消或完成運行時，*fn* 將被以 " +"future 作為其唯一引數來呼叫。" + +#: ../../library/concurrent.futures.rst:558 +msgid "" +"Added callables are called in the order that they were added and are always " +"called in a thread belonging to the process that added them. If the " +"callable raises an :exc:`Exception` subclass, it will be logged and " +"ignored. If the callable raises a :exc:`BaseException` subclass, the " +"behavior is undefined." +msgstr "" +"新增的可呼叫物件按新增順序呼叫，並且始終在屬於新增它們的行程的執行緒中呼叫。" +"如果可呼叫物件引發 :exc:`Exception` 子類別，它將被記錄 (log) 並忽略。如果可呼" +"叫物件引發 :exc:`BaseException` 子類別，該行為未定義。" + +#: ../../library/concurrent.futures.rst:564 +msgid "" +"If the future has already completed or been cancelled, *fn* will be called " +"immediately." +msgstr "如果 future 已經完成或被取消，*fn* 將立即被呼叫。" + +#: ../../library/concurrent.futures.rst:567 +msgid "" +"The following :class:`Future` methods are meant for use in unit tests and :" +"class:`Executor` implementations." +msgstr "以下 :class:`Future` 方法旨在用於單元測試和 :class:`Executor` 實作。" + +#: ../../library/concurrent.futures.rst:572 +msgid "" +"This method should only be called by :class:`Executor` implementations " +"before executing the work associated with the :class:`Future` and by unit " +"tests." +msgstr "" +"此方法只能在與 :class:`Future` 關聯的工作被執行之前於 :class:`Executor` 實作" +"中呼叫，或者在單元測試中呼叫。" + +#: ../../library/concurrent.futures.rst:576 +msgid "" +"If the method returns ``False`` then the :class:`Future` was cancelled, i." +"e. :meth:`Future.cancel` was called and returned ``True``. Any threads " +"waiting on the :class:`Future` completing (i.e. through :func:`as_completed` " +"or :func:`wait`) will be woken up." +msgstr "" +"如果該方法回傳 ``False`` 則 :class:`Future` 已被取消，即 :meth:`Future." +"cancel` 被呼叫並回傳 ``True``。任何等待 :class:`Future` 完成的執行緒（即透" +"過 :func:`as_completed` 或 :func:`wait`）將被喚醒。" + +#: ../../library/concurrent.futures.rst:581 +msgid "" +"If the method returns ``True`` then the :class:`Future` was not cancelled " +"and has been put in the running state, i.e. calls to :meth:`Future.running` " +"will return ``True``." +msgstr "" +"如果該方法回傳 ``True`` 則代表 :class:`Future` 未被取消並已進入運行狀態，意即" +"呼叫 :meth:`Future.running` 將回傳 ``True``。" + +#: ../../library/concurrent.futures.rst:585 +msgid "" +"This method can only be called once and cannot be called after :meth:`Future." +"set_result` or :meth:`Future.set_exception` have been called." +msgstr "" +"此方法只能呼叫一次，且不能在呼叫 :meth:`Future.set_result` 或 :meth:`Future." +"set_exception` 之後呼叫。" + +#: ../../library/concurrent.futures.rst:591 +msgid "" +"Sets the result of the work associated with the :class:`Future` to *result*." +msgstr "將與 :class:`Future` 關聯的工作結果設定為 *result*。" + +#: ../../library/concurrent.futures.rst:594 +#: ../../library/concurrent.futures.rst:607 +msgid "" +"This method should only be used by :class:`Executor` implementations and " +"unit tests." +msgstr "此方法只能在 :class:`Executor` 實作中和單元測試中使用。" + +#: ../../library/concurrent.futures.rst:597 +#: ../../library/concurrent.futures.rst:610 +msgid "" +"This method raises :exc:`concurrent.futures.InvalidStateError` if the :class:" +"`Future` is already done." +msgstr "" +"如果 :class:`Future` 已經完成，此方法會引發 :exc:`concurrent.futures." +"InvalidStateError`。" + +#: ../../library/concurrent.futures.rst:604 +msgid "" +"Sets the result of the work associated with the :class:`Future` to the :" +"class:`Exception` *exception*." +msgstr "" +"將與 :class:`Future` 關聯的工作結果設定為 :class:`Exception` *exception*。" + +#: ../../library/concurrent.futures.rst:616 +msgid "Module Functions" +msgstr "模組函式" + +#: ../../library/concurrent.futures.rst:620 +msgid "" +"Wait for the :class:`Future` instances (possibly created by different :class:" +"`Executor` instances) given by *fs* to complete. Duplicate futures given to " +"*fs* are removed and will be returned only once. Returns a named 2-tuple of " +"sets. The first set, named ``done``, contains the futures that completed " +"(finished or cancelled futures) before the wait completed. The second set, " +"named ``not_done``, contains the futures that did not complete (pending or " +"running futures)." +msgstr "" +"等待 *fs* 給定的 :class:`Future` 實例（可能由不同的 :class:`Executor` 實例建" +"立）完成。提供給 *fs* 的重複 future 將被刪除，並且只會回傳一次。回傳一個集合" +"的附名二元組 (named 2-tuple of sets)。第一組名為 ``done``，包含在等待完成之前" +"完成的 future（已完成或被取消的 future）。第二組名為 ``not_done``，包含未完成" +"的 future（未定或運行中的 future）。" + +#: ../../library/concurrent.futures.rst:628 +msgid "" +"*timeout* can be used to control the maximum number of seconds to wait " +"before returning. *timeout* can be an int or float. If *timeout* is not " +"specified or ``None``, there is no limit to the wait time." +msgstr "" +"*timeout* 可用於控制回傳前等待的最大秒數。*timeout* 可以是整數或浮點數。如果" +"未指定 *timeout* 或為 ``None``，則等待時間就沒有限制。" + +#: ../../library/concurrent.futures.rst:632 +msgid "" +"*return_when* indicates when this function should return. It must be one of " +"the following constants:" +msgstr "*return_when* 表示此函式應回傳的時間。它必須是以下常數之一：" + +#: ../../library/concurrent.futures.rst:638 +msgid "Constant" +msgstr "常數" + +#: ../../library/concurrent.futures.rst:639 +msgid "Description" +msgstr "描述" + +#: ../../library/concurrent.futures.rst:642 +msgid "The function will return when any future finishes or is cancelled." +msgstr "當任何 future 完成或被取消時，該函式就會回傳。" + +#: ../../library/concurrent.futures.rst:645 +msgid "" +"The function will return when any future finishes by raising an exception. " +"If no future raises an exception then it is equivalent to :const:" +"`ALL_COMPLETED`." +msgstr "" +"該函式會在任何 future 透過引發例外而完結時回傳。如果 future 沒有引發例外，那" +"麼它等同於 :const:`ALL_COMPLETED`。" + +#: ../../library/concurrent.futures.rst:650 +msgid "The function will return when all futures finish or are cancelled." +msgstr "當所有 future 都完成或被取消時，該函式才會回傳。" + +#: ../../library/concurrent.futures.rst:654 +msgid "" +"Returns an iterator over the :class:`Future` instances (possibly created by " +"different :class:`Executor` instances) given by *fs* that yields futures as " +"they complete (finished or cancelled futures). Any futures given by *fs* " +"that are duplicated will be returned once. Any futures that completed " +"before :func:`as_completed` is called will be yielded first. The returned " +"iterator raises a :exc:`TimeoutError` if :meth:`~iterator.__next__` is " +"called and the result isn't available after *timeout* seconds from the " +"original call to :func:`as_completed`. *timeout* can be an int or float. If " +"*timeout* is not specified or ``None``, there is no limit to the wait time." +msgstr "" +"回傳由 *fs* 給定的 :class:`Future` 實例（可能由不同的 :class:`Executor` 實例" +"建立）的疊代器，它在完成時產生 future（已完成或被取消的 future）。*fs* 給定的" +"任何重複的 future 將只被回傳一次。呼叫 :func:`as_completed` 之前完成的任何 " +"future 將首先產生。如果 :meth:`~iterator.__next__` 被呼叫，並且在原先呼叫 :" +"func:`as_completed` 的 *timeout* 秒後結果仍不可用，則回傳的疊代器會引發 :exc:" +"`TimeoutError`。*timeout* 可以是整數或浮點數。如果未指定 *timeout* 或為 " +"``None``，則等待時間就沒有限制。" + +#: ../../library/concurrent.futures.rst:667 +msgid ":pep:`3148` -- futures - execute computations asynchronously" +msgstr ":pep:`3148` -- futures - 非同步地執行運算" + +#: ../../library/concurrent.futures.rst:668 +msgid "" +"The proposal which described this feature for inclusion in the Python " +"standard library." +msgstr "描述此功能並提出被包含於 Python 標準函式庫中的提案。" + +#: ../../library/concurrent.futures.rst:673 +msgid "Exception classes" +msgstr "例外類別" + +#: ../../library/concurrent.futures.rst:679 +msgid "Raised when a future is cancelled." +msgstr "當 future 被取消時引發。" + +#: ../../library/concurrent.futures.rst:683 +msgid "" +"A deprecated alias of :exc:`TimeoutError`, raised when a future operation " +"exceeds the given timeout." +msgstr "" +":exc:`TimeoutError` 的棄用別名，在 future 操作超過給定超時 (timeout) 時引發。" + +#: ../../library/concurrent.futures.rst:688 +msgid "This class was made an alias of :exc:`TimeoutError`." +msgstr "這個類別是 :exc:`TimeoutError` 的別名。" + +#: ../../library/concurrent.futures.rst:693 +msgid "" +"Derived from :exc:`RuntimeError`, this exception class is raised when an " +"executor is broken for some reason, and cannot be used to submit or execute " +"new tasks." +msgstr "" +"衍生自 :exc:`RuntimeError`，當執行器因某種原因損壞時會引發此例外類別，並且不" +"能用於提交或執行新任務。" + +#: ../../library/concurrent.futures.rst:701 +msgid "" +"Raised when an operation is performed on a future that is not allowed in the " +"current state." +msgstr "目前狀態下不允許的 future 操作被執行時而引發。" + +#: ../../library/concurrent.futures.rst:710 +msgid "" +"Derived from :exc:`~concurrent.futures.BrokenExecutor`, this exception class " +"is raised when one of the workers of a :class:`~concurrent.futures." +"ThreadPoolExecutor` has failed initializing." +msgstr "" +"衍生自 :exc:`~concurrent.futures.BrokenExecutor`，當 :class:`~concurrent." +"futures.ThreadPoolExecutor` 的其中一個 worker 初始化失敗時會引發此例外類別。" + +#: ../../library/concurrent.futures.rst:721 +msgid "" +"Derived from :exc:`~concurrent.futures.thread.BrokenThreadPool`, this " +"exception class is raised when one of the workers of a :class:`~concurrent." +"futures.InterpreterPoolExecutor` has failed initializing." +msgstr "" +"衍生自 :exc:`~concurrent.futures.thread.BrokenThreadPool`，當 :class:" +"`~concurrent.futures.InterpreterPoolExecutor` 的其中一個 worker 初始化失敗時" +"會引發此例外類別。" + +#: ../../library/concurrent.futures.rst:732 +msgid "" +"Derived from :exc:`~concurrent.futures.BrokenExecutor` (formerly :exc:" +"`RuntimeError`), this exception class is raised when one of the workers of " +"a :class:`~concurrent.futures.ProcessPoolExecutor` has terminated in a non-" +"clean fashion (for example, if it was killed from the outside)." +msgstr "" +"衍生自 :exc:`~concurrent.futures.BrokenExecutor`\\（以前為 :exc:" +"`RuntimeError`），當 :class:`~concurrent.futures.ProcessPoolExecutor` 的其中" +"一個 worker 以不乾淨的方式終止時將引發此例外類別（例如它是從外面被 kill 掉" +"的）。" diff --git a/library/concurrent.interpreters.po b/library/concurrent.interpreters.po index cd8cbd637f..e7e773a1c9 100644 --- a/library/concurrent.interpreters.po +++ b/library/concurrent.interpreters.po @@ -1,523 +1,523 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# FIRST AUTHOR , YEAR. -# -#, fuzzy -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-07 00:14+0000\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language-Team: LANGUAGE \n" -"Language: zh_TW\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=UTF-8\n" -"Content-Transfer-Encoding: 8bit\n" - -#: ../../library/concurrent.interpreters.rst:2 -msgid "" -":mod:`!concurrent.interpreters` --- Multiple interpreters in the same process" -msgstr ":mod:`!concurrent.interpreters` --- 在同一個行程中使用多個直譯器" - -#: ../../library/concurrent.interpreters.rst:12 -msgid "**Source code:** :source:`Lib/concurrent/interpreters`" -msgstr "**原始碼：**\\ :source:`Lib/concurrent/interpreters`" - -#: ../../library/concurrent.interpreters.rst:16 -msgid "" -"The :mod:`!concurrent.interpreters` module constructs higher-level " -"interfaces on top of the lower level :mod:`!_interpreters` module." -msgstr "" - -#: ../../library/concurrent.interpreters.rst:19 -msgid "" -"The module is primarily meant to provide a basic API for managing " -"interpreters (AKA \"subinterpreters\") and running things in them. Running " -"mostly involves switching to an interpreter (in the current thread) and " -"calling a function in that execution context." -msgstr "" - -#: ../../library/concurrent.interpreters.rst:24 -msgid "" -"For concurrency, interpreters themselves (and this module) don't provide " -"much more than isolation, which on its own isn't useful. Actual concurrency " -"is available separately through :mod:`threads ` See `below " -"`_" -msgstr "" - -#: ../../library/concurrent.interpreters.rst:31 -msgid ":class:`~concurrent.futures.InterpreterPoolExecutor`" -msgstr ":class:`~concurrent.futures.InterpreterPoolExecutor`" - -#: ../../library/concurrent.interpreters.rst:32 -msgid "Combines threads with interpreters in a familiar interface." -msgstr "" - -#: ../../library/concurrent.interpreters.rst:36 -msgid ":ref:`isolating-extensions-howto`" -msgstr ":ref:`isolating-extensions-howto`" - -#: ../../library/concurrent.interpreters.rst:37 -msgid "How to update an extension module to support multiple interpreters." -msgstr "" - -#: ../../library/concurrent.interpreters.rst:39 -msgid ":pep:`554`" -msgstr ":pep:`554`" - -#: ../../library/concurrent.interpreters.rst:41 -msgid ":pep:`734`" -msgstr ":pep:`734`" - -#: ../../library/concurrent.interpreters.rst:43 -msgid ":pep:`684`" -msgstr ":pep:`684`" - -#: ../../includes/wasm-notavail.rst:3 -msgid "Availability" -msgstr "可用性" - -#: ../../includes/wasm-notavail.rst:5 -msgid "" -"This module does not work or is not available on WebAssembly. See :ref:`wasm-" -"availability` for more information." -msgstr "" - -#: ../../library/concurrent.interpreters.rst:51 -msgid "Key details" -msgstr "" - -#: ../../library/concurrent.interpreters.rst:53 -msgid "" -"Before we dive in further, there are a small number of details to keep in " -"mind about using multiple interpreters:" -msgstr "" - -#: ../../library/concurrent.interpreters.rst:56 -msgid "`isolated `_, by default" -msgstr "" - -#: ../../library/concurrent.interpreters.rst:57 -msgid "no implicit threads" -msgstr "" - -#: ../../library/concurrent.interpreters.rst:58 -msgid "not all PyPI packages support use in multiple interpreters yet" -msgstr "" - -#: ../../library/concurrent.interpreters.rst:66 -msgid "Introduction" -msgstr "" - -#: ../../library/concurrent.interpreters.rst:68 -msgid "" -"An \"interpreter\" is effectively the execution context of the Python " -"runtime. It contains all of the state the runtime needs to execute a " -"program. This includes things like the import state and builtins. (Each " -"thread, even if there's only the main thread, has some extra runtime state, " -"in addition to the current interpreter, related to the current exception and " -"the bytecode eval loop.)" -msgstr "" - -#: ../../library/concurrent.interpreters.rst:75 -msgid "" -"The concept and functionality of the interpreter have been a part of Python " -"since version 2.2, but the feature was only available through the C-API and " -"not well known, and the `isolation `_ was relatively " -"incomplete until version 3.12." -msgstr "" - -#: ../../library/concurrent.interpreters.rst:83 -msgid "Multiple Interpreters and Isolation" -msgstr "" - -#: ../../library/concurrent.interpreters.rst:85 -msgid "" -"A Python implementation may support using multiple interpreters in the same " -"process. CPython has this support. Each interpreter is effectively " -"isolated from the others (with a limited number of carefully managed process-" -"global exceptions to the rule)." -msgstr "" - -#: ../../library/concurrent.interpreters.rst:90 -msgid "" -"That isolation is primarily useful as a strong separation between distinct " -"logical components of a program, where you want to have careful control of " -"how those components interact." -msgstr "" - -#: ../../library/concurrent.interpreters.rst:96 -msgid "" -"Interpreters in the same process can technically never be strictly isolated " -"from one another since there are few restrictions on memory access within " -"the same process. The Python runtime makes a best effort at isolation but " -"extension modules may easily violate that. Therefore, do not use multiple " -"interpreters in security-sensitive situations, where they shouldn't have " -"access to each other's data." -msgstr "" - -#: ../../library/concurrent.interpreters.rst:104 -msgid "Running in an Interpreter" -msgstr "" - -#: ../../library/concurrent.interpreters.rst:106 -msgid "" -"Running in a different interpreter involves switching to it in the current " -"thread and then calling some function. The runtime will execute the " -"function using the current interpreter's state. The :mod:`!concurrent." -"interpreters` module provides a basic API for creating and managing " -"interpreters, as well as the switch-and-call operation." -msgstr "" - -#: ../../library/concurrent.interpreters.rst:113 -msgid "" -"No other threads are automatically started for the operation. There is `a " -"helper `_ for that though. There is another " -"dedicated helper for calling the builtin :func:`exec` in an interpreter." -msgstr "" - -#: ../../library/concurrent.interpreters.rst:118 -msgid "" -"When :func:`exec` (or :func:`eval`) are called in an interpreter, they run " -"using the interpreter's :mod:`!__main__` module as the \"globals\" " -"namespace. The same is true for functions that aren't associated with any " -"module. This is the same as how scripts invoked from the command-line run " -"in the :mod:`!__main__` module." -msgstr "" - -#: ../../library/concurrent.interpreters.rst:128 -msgid "Concurrency and Parallelism" -msgstr "" - -#: ../../library/concurrent.interpreters.rst:130 -msgid "" -"As noted earlier, interpreters do not provide any concurrency on their own. " -"They strictly represent the isolated execution context the runtime will use " -"*in the current thread*. That isolation makes them similar to processes, " -"but they still enjoy in-process efficiency, like threads." -msgstr "" - -#: ../../library/concurrent.interpreters.rst:136 -msgid "" -"All that said, interpreters do naturally support certain flavors of " -"concurrency. There's a powerful side effect of that isolation. It enables a " -"different approach to concurrency than you can take with async or threads. " -"It's a similar concurrency model to CSP or the actor model, a model which is " -"relatively easy to reason about." -msgstr "" - -#: ../../library/concurrent.interpreters.rst:143 -msgid "" -"You can take advantage of that concurrency model in a single thread, " -"switching back and forth between interpreters, Stackless-style. However, " -"this model is more useful when you combine interpreters with multiple " -"threads. This mostly involves starting a new thread, where you switch to " -"another interpreter and run what you want there." -msgstr "" - -#: ../../library/concurrent.interpreters.rst:149 -msgid "" -"Each actual thread in Python, even if you're only running in the main " -"thread, has its own *current* execution context. Multiple threads can use " -"the same interpreter or different ones." -msgstr "" - -#: ../../library/concurrent.interpreters.rst:153 -msgid "" -"At a high level, you can think of the combination of threads and " -"interpreters as threads with opt-in sharing." -msgstr "" - -#: ../../library/concurrent.interpreters.rst:156 -msgid "" -"As a significant bonus, interpreters are sufficiently isolated that they do " -"not share the :term:`GIL`, which means combining threads with multiple " -"interpreters enables full multi-core parallelism. (This has been the case " -"since Python 3.12.)" -msgstr "" - -#: ../../library/concurrent.interpreters.rst:162 -msgid "Communication Between Interpreters" -msgstr "直譯器之間的溝通" - -#: ../../library/concurrent.interpreters.rst:164 -msgid "" -"In practice, multiple interpreters are useful only if we have a way to " -"communicate between them. This usually involves some form of message " -"passing, but can even mean sharing data in some carefully managed way." -msgstr "" - -#: ../../library/concurrent.interpreters.rst:169 -msgid "" -"With this in mind, the :mod:`!concurrent.interpreters` module provides a :" -"class:`queue.Queue` implementation, available through :func:`create_queue`." -msgstr "" - -#: ../../library/concurrent.interpreters.rst:176 -msgid "\"Sharing\" Objects" -msgstr "" - -#: ../../library/concurrent.interpreters.rst:178 -msgid "" -"Any data actually shared between interpreters loses the thread-safety " -"provided by the :term:`GIL`. There are various options for dealing with " -"this in extension modules. However, from Python code the lack of thread-" -"safety means objects can't actually be shared, with a few exceptions. " -"Instead, a copy must be created, which means mutable objects won't stay in " -"sync." -msgstr "" - -#: ../../library/concurrent.interpreters.rst:185 -msgid "" -"By default, most objects are copied with :mod:`pickle` when they are passed " -"to another interpreter. Nearly all of the immutable builtin objects are " -"either directly shared or copied efficiently. For example:" -msgstr "" - -#: ../../library/concurrent.interpreters.rst:189 -msgid ":const:`None`" -msgstr ":const:`None`" - -#: ../../library/concurrent.interpreters.rst:190 -msgid ":class:`bool` (:const:`True` and :const:`False`)" -msgstr ":class:`bool`\\ （:const:`True` 和 :const:`False`）" - -#: ../../library/concurrent.interpreters.rst:191 -msgid ":class:`bytes`" -msgstr ":class:`bytes`" - -#: ../../library/concurrent.interpreters.rst:192 -msgid ":class:`str`" -msgstr ":class:`str`" - -#: ../../library/concurrent.interpreters.rst:193 -msgid ":class:`int`" -msgstr ":class:`int`" - -#: ../../library/concurrent.interpreters.rst:194 -msgid ":class:`float`" -msgstr ":class:`float`" - -#: ../../library/concurrent.interpreters.rst:195 -msgid ":class:`tuple` (of similarly supported objects)" -msgstr "" - -#: ../../library/concurrent.interpreters.rst:197 -msgid "" -"There is a small number of Python types that actually share mutable data " -"between interpreters:" -msgstr "" - -#: ../../library/concurrent.interpreters.rst:200 -msgid ":class:`memoryview`" -msgstr ":class:`memoryview`" - -#: ../../library/concurrent.interpreters.rst:201 -msgid ":class:`Queue`" -msgstr ":class:`Queue`" - -#: ../../library/concurrent.interpreters.rst:205 -msgid "Reference" -msgstr "" - -#: ../../library/concurrent.interpreters.rst:207 -msgid "This module defines the following functions:" -msgstr "" - -#: ../../library/concurrent.interpreters.rst:211 -msgid "" -"Return a :class:`list` of :class:`Interpreter` objects, one for each " -"existing interpreter." -msgstr "" - -#: ../../library/concurrent.interpreters.rst:216 -msgid "" -"Return an :class:`Interpreter` object for the currently running interpreter." -msgstr "" - -#: ../../library/concurrent.interpreters.rst:221 -msgid "" -"Return an :class:`Interpreter` object for the main interpreter. This is the " -"interpreter the runtime created to run the :term:`REPL` or the script given " -"at the command-line. It is usually the only one." -msgstr "" - -#: ../../library/concurrent.interpreters.rst:227 -msgid "" -"Initialize a new (idle) Python interpreter and return a :class:`Interpreter` " -"object for it." -msgstr "" - -#: ../../library/concurrent.interpreters.rst:232 -msgid "" -"Initialize a new cross-interpreter queue and return a :class:`Queue` object " -"for it." -msgstr "" - -#: ../../library/concurrent.interpreters.rst:237 -msgid "Interpreter objects" -msgstr "" - -#: ../../library/concurrent.interpreters.rst:241 -msgid "A single interpreter in the current process." -msgstr "" - -#: ../../library/concurrent.interpreters.rst:243 -msgid "" -"Generally, :class:`Interpreter` shouldn't be called directly. Instead, use :" -"func:`create` or one of the other module functions." -msgstr "" - -#: ../../library/concurrent.interpreters.rst:248 -#: ../../library/concurrent.interpreters.rst:254 -#: ../../library/concurrent.interpreters.rst:333 -msgid "(read-only)" -msgstr "" - -#: ../../library/concurrent.interpreters.rst:250 -msgid "The underlying interpreter's ID." -msgstr "" - -#: ../../library/concurrent.interpreters.rst:256 -msgid "A string describing where the interpreter came from." -msgstr "" - -#: ../../library/concurrent.interpreters.rst:260 -msgid "" -"Return ``True`` if the interpreter is currently executing code in its :mod:`!" -"__main__` module and ``False`` otherwise." -msgstr "" - -#: ../../library/concurrent.interpreters.rst:265 -msgid "Finalize and destroy the interpreter." -msgstr "" - -#: ../../library/concurrent.interpreters.rst:269 -msgid "Bind objects in the interpreter's :mod:`!__main__` module." -msgstr "" - -#: ../../library/concurrent.interpreters.rst:271 -#: ../../library/concurrent.interpreters.rst:328 -msgid "" -"Some objects are actually shared and some are copied efficiently, but most " -"are copied via :mod:`pickle`. See :ref:`interp-object-sharing`." -msgstr "" - -#: ../../library/concurrent.interpreters.rst:276 -msgid "Run the given source code in the interpreter (in the current thread)." -msgstr "" - -#: ../../library/concurrent.interpreters.rst:280 -msgid "" -"Return the result of calling running the given function in the interpreter " -"(in the current thread)." -msgstr "" - -#: ../../library/concurrent.interpreters.rst:287 -msgid "Run the given function in the interpreter (in a new thread)." -msgstr "" - -#: ../../library/concurrent.interpreters.rst:290 -msgid "Exceptions" -msgstr "例外" - -#: ../../library/concurrent.interpreters.rst:294 -msgid "" -"This exception, a subclass of :exc:`Exception`, is raised when an " -"interpreter-related error happens." -msgstr "" - -#: ../../library/concurrent.interpreters.rst:299 -msgid "" -"This exception, a subclass of :exc:`InterpreterError`, is raised when the " -"targeted interpreter no longer exists." -msgstr "" - -#: ../../library/concurrent.interpreters.rst:304 -msgid "" -"This exception, a subclass of :exc:`InterpreterError`, is raised when the " -"running code raised an uncaught exception." -msgstr "" - -#: ../../library/concurrent.interpreters.rst:309 -msgid "A basic snapshot of the exception raised in the other interpreter." -msgstr "" - -#: ../../library/concurrent.interpreters.rst:315 -msgid "" -"This exception, a subclass of :exc:`TypeError`, is raised when an object " -"cannot be sent to another interpreter." -msgstr "" - -#: ../../library/concurrent.interpreters.rst:320 -msgid "Communicating Between Interpreters" -msgstr "在直譯器之間溝通" - -#: ../../library/concurrent.interpreters.rst:324 -msgid "" -"A wrapper around a low-level, cross-interpreter queue, which implements the :" -"class:`queue.Queue` interface. The underlying queue can only be created " -"through :func:`create_queue`." -msgstr "" - -#: ../../library/concurrent.interpreters.rst:335 -msgid "The queue's ID." -msgstr "" - -#: ../../library/concurrent.interpreters.rst:340 -msgid "" -"This exception, a subclass of :exc:`queue.Empty`, is raised from :meth:`!" -"Queue.get` and :meth:`!Queue.get_nowait` when the queue is empty." -msgstr "" - -#: ../../library/concurrent.interpreters.rst:346 -msgid "" -"This exception, a subclass of :exc:`queue.Full`, is raised from :meth:`!" -"Queue.put` and :meth:`!Queue.put_nowait` when the queue is full." -msgstr "" - -#: ../../library/concurrent.interpreters.rst:352 -msgid "Basic usage" -msgstr "基本用法" - -#: ../../library/concurrent.interpreters.rst:354 -msgid "Creating an interpreter and running code in it::" -msgstr "建立一個直譯器並在其中運行程式碼： ::" - -#: ../../library/concurrent.interpreters.rst:356 -msgid "" -"from concurrent import interpreters\n" -"\n" -"interp = interpreters.create()\n" -"\n" -"# Run in the current OS thread.\n" -"\n" -"interp.exec('print(\"spam!\")')\n" -"\n" -"interp.exec(\"\"\"if True:\n" -" print('spam!')\n" -" \"\"\")\n" -"\n" -"from textwrap import dedent\n" -"interp.exec(dedent(\"\"\"\n" -" print('spam!')\n" -" \"\"\"))\n" -"\n" -"def run(arg):\n" -" return arg\n" -"\n" -"res = interp.call(run, 'spam!')\n" -"print(res)\n" -"\n" -"def run():\n" -" print('spam!')\n" -"\n" -"interp.call(run)\n" -"\n" -"# Run in new OS thread.\n" -"\n" -"t = interp.call_in_thread(run)\n" -"t.join()" -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-07 00:14+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"Language: zh_TW\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../library/concurrent.interpreters.rst:2 +msgid "" +":mod:`!concurrent.interpreters` --- Multiple interpreters in the same process" +msgstr ":mod:`!concurrent.interpreters` --- 在同一個行程中使用多個直譯器" + +#: ../../library/concurrent.interpreters.rst:12 +msgid "**Source code:** :source:`Lib/concurrent/interpreters`" +msgstr "**原始碼：**\\ :source:`Lib/concurrent/interpreters`" + +#: ../../library/concurrent.interpreters.rst:16 +msgid "" +"The :mod:`!concurrent.interpreters` module constructs higher-level " +"interfaces on top of the lower level :mod:`!_interpreters` module." +msgstr "" + +#: ../../library/concurrent.interpreters.rst:19 +msgid "" +"The module is primarily meant to provide a basic API for managing " +"interpreters (AKA \"subinterpreters\") and running things in them. Running " +"mostly involves switching to an interpreter (in the current thread) and " +"calling a function in that execution context." +msgstr "" + +#: ../../library/concurrent.interpreters.rst:24 +msgid "" +"For concurrency, interpreters themselves (and this module) don't provide " +"much more than isolation, which on its own isn't useful. Actual concurrency " +"is available separately through :mod:`threads ` See `below " +"`_" +msgstr "" + +#: ../../library/concurrent.interpreters.rst:31 +msgid ":class:`~concurrent.futures.InterpreterPoolExecutor`" +msgstr ":class:`~concurrent.futures.InterpreterPoolExecutor`" + +#: ../../library/concurrent.interpreters.rst:32 +msgid "Combines threads with interpreters in a familiar interface." +msgstr "" + +#: ../../library/concurrent.interpreters.rst:36 +msgid ":ref:`isolating-extensions-howto`" +msgstr ":ref:`isolating-extensions-howto`" + +#: ../../library/concurrent.interpreters.rst:37 +msgid "How to update an extension module to support multiple interpreters." +msgstr "" + +#: ../../library/concurrent.interpreters.rst:39 +msgid ":pep:`554`" +msgstr ":pep:`554`" + +#: ../../library/concurrent.interpreters.rst:41 +msgid ":pep:`734`" +msgstr ":pep:`734`" + +#: ../../library/concurrent.interpreters.rst:43 +msgid ":pep:`684`" +msgstr ":pep:`684`" + +#: ../../includes/wasm-notavail.rst:3 +msgid "Availability" +msgstr "可用性" + +#: ../../includes/wasm-notavail.rst:5 +msgid "" +"This module does not work or is not available on WebAssembly. See :ref:`wasm-" +"availability` for more information." +msgstr "" + +#: ../../library/concurrent.interpreters.rst:51 +msgid "Key details" +msgstr "" + +#: ../../library/concurrent.interpreters.rst:53 +msgid "" +"Before we dive in further, there are a small number of details to keep in " +"mind about using multiple interpreters:" +msgstr "" + +#: ../../library/concurrent.interpreters.rst:56 +msgid "`isolated `_, by default" +msgstr "" + +#: ../../library/concurrent.interpreters.rst:57 +msgid "no implicit threads" +msgstr "" + +#: ../../library/concurrent.interpreters.rst:58 +msgid "not all PyPI packages support use in multiple interpreters yet" +msgstr "" + +#: ../../library/concurrent.interpreters.rst:66 +msgid "Introduction" +msgstr "" + +#: ../../library/concurrent.interpreters.rst:68 +msgid "" +"An \"interpreter\" is effectively the execution context of the Python " +"runtime. It contains all of the state the runtime needs to execute a " +"program. This includes things like the import state and builtins. (Each " +"thread, even if there's only the main thread, has some extra runtime state, " +"in addition to the current interpreter, related to the current exception and " +"the bytecode eval loop.)" +msgstr "" + +#: ../../library/concurrent.interpreters.rst:75 +msgid "" +"The concept and functionality of the interpreter have been a part of Python " +"since version 2.2, but the feature was only available through the C-API and " +"not well known, and the `isolation `_ was relatively " +"incomplete until version 3.12." +msgstr "" + +#: ../../library/concurrent.interpreters.rst:83 +msgid "Multiple Interpreters and Isolation" +msgstr "" + +#: ../../library/concurrent.interpreters.rst:85 +msgid "" +"A Python implementation may support using multiple interpreters in the same " +"process. CPython has this support. Each interpreter is effectively " +"isolated from the others (with a limited number of carefully managed process-" +"global exceptions to the rule)." +msgstr "" + +#: ../../library/concurrent.interpreters.rst:90 +msgid "" +"That isolation is primarily useful as a strong separation between distinct " +"logical components of a program, where you want to have careful control of " +"how those components interact." +msgstr "" + +#: ../../library/concurrent.interpreters.rst:96 +msgid "" +"Interpreters in the same process can technically never be strictly isolated " +"from one another since there are few restrictions on memory access within " +"the same process. The Python runtime makes a best effort at isolation but " +"extension modules may easily violate that. Therefore, do not use multiple " +"interpreters in security-sensitive situations, where they shouldn't have " +"access to each other's data." +msgstr "" + +#: ../../library/concurrent.interpreters.rst:104 +msgid "Running in an Interpreter" +msgstr "" + +#: ../../library/concurrent.interpreters.rst:106 +msgid "" +"Running in a different interpreter involves switching to it in the current " +"thread and then calling some function. The runtime will execute the " +"function using the current interpreter's state. The :mod:`!concurrent." +"interpreters` module provides a basic API for creating and managing " +"interpreters, as well as the switch-and-call operation." +msgstr "" + +#: ../../library/concurrent.interpreters.rst:113 +msgid "" +"No other threads are automatically started for the operation. There is `a " +"helper `_ for that though. There is another " +"dedicated helper for calling the builtin :func:`exec` in an interpreter." +msgstr "" + +#: ../../library/concurrent.interpreters.rst:118 +msgid "" +"When :func:`exec` (or :func:`eval`) are called in an interpreter, they run " +"using the interpreter's :mod:`!__main__` module as the \"globals\" " +"namespace. The same is true for functions that aren't associated with any " +"module. This is the same as how scripts invoked from the command-line run " +"in the :mod:`!__main__` module." +msgstr "" + +#: ../../library/concurrent.interpreters.rst:128 +msgid "Concurrency and Parallelism" +msgstr "" + +#: ../../library/concurrent.interpreters.rst:130 +msgid "" +"As noted earlier, interpreters do not provide any concurrency on their own. " +"They strictly represent the isolated execution context the runtime will use " +"*in the current thread*. That isolation makes them similar to processes, " +"but they still enjoy in-process efficiency, like threads." +msgstr "" + +#: ../../library/concurrent.interpreters.rst:136 +msgid "" +"All that said, interpreters do naturally support certain flavors of " +"concurrency. There's a powerful side effect of that isolation. It enables a " +"different approach to concurrency than you can take with async or threads. " +"It's a similar concurrency model to CSP or the actor model, a model which is " +"relatively easy to reason about." +msgstr "" + +#: ../../library/concurrent.interpreters.rst:143 +msgid "" +"You can take advantage of that concurrency model in a single thread, " +"switching back and forth between interpreters, Stackless-style. However, " +"this model is more useful when you combine interpreters with multiple " +"threads. This mostly involves starting a new thread, where you switch to " +"another interpreter and run what you want there." +msgstr "" + +#: ../../library/concurrent.interpreters.rst:149 +msgid "" +"Each actual thread in Python, even if you're only running in the main " +"thread, has its own *current* execution context. Multiple threads can use " +"the same interpreter or different ones." +msgstr "" + +#: ../../library/concurrent.interpreters.rst:153 +msgid "" +"At a high level, you can think of the combination of threads and " +"interpreters as threads with opt-in sharing." +msgstr "" + +#: ../../library/concurrent.interpreters.rst:156 +msgid "" +"As a significant bonus, interpreters are sufficiently isolated that they do " +"not share the :term:`GIL`, which means combining threads with multiple " +"interpreters enables full multi-core parallelism. (This has been the case " +"since Python 3.12.)" +msgstr "" + +#: ../../library/concurrent.interpreters.rst:162 +msgid "Communication Between Interpreters" +msgstr "直譯器之間的溝通" + +#: ../../library/concurrent.interpreters.rst:164 +msgid "" +"In practice, multiple interpreters are useful only if we have a way to " +"communicate between them. This usually involves some form of message " +"passing, but can even mean sharing data in some carefully managed way." +msgstr "" + +#: ../../library/concurrent.interpreters.rst:169 +msgid "" +"With this in mind, the :mod:`!concurrent.interpreters` module provides a :" +"class:`queue.Queue` implementation, available through :func:`create_queue`." +msgstr "" + +#: ../../library/concurrent.interpreters.rst:176 +msgid "\"Sharing\" Objects" +msgstr "" + +#: ../../library/concurrent.interpreters.rst:178 +msgid "" +"Any data actually shared between interpreters loses the thread-safety " +"provided by the :term:`GIL`. There are various options for dealing with " +"this in extension modules. However, from Python code the lack of thread-" +"safety means objects can't actually be shared, with a few exceptions. " +"Instead, a copy must be created, which means mutable objects won't stay in " +"sync." +msgstr "" + +#: ../../library/concurrent.interpreters.rst:185 +msgid "" +"By default, most objects are copied with :mod:`pickle` when they are passed " +"to another interpreter. Nearly all of the immutable builtin objects are " +"either directly shared or copied efficiently. For example:" +msgstr "" + +#: ../../library/concurrent.interpreters.rst:189 +msgid ":const:`None`" +msgstr ":const:`None`" + +#: ../../library/concurrent.interpreters.rst:190 +msgid ":class:`bool` (:const:`True` and :const:`False`)" +msgstr ":class:`bool`\\ （:const:`True` 和 :const:`False`）" + +#: ../../library/concurrent.interpreters.rst:191 +msgid ":class:`bytes`" +msgstr ":class:`bytes`" + +#: ../../library/concurrent.interpreters.rst:192 +msgid ":class:`str`" +msgstr ":class:`str`" + +#: ../../library/concurrent.interpreters.rst:193 +msgid ":class:`int`" +msgstr ":class:`int`" + +#: ../../library/concurrent.interpreters.rst:194 +msgid ":class:`float`" +msgstr ":class:`float`" + +#: ../../library/concurrent.interpreters.rst:195 +msgid ":class:`tuple` (of similarly supported objects)" +msgstr "" + +#: ../../library/concurrent.interpreters.rst:197 +msgid "" +"There is a small number of Python types that actually share mutable data " +"between interpreters:" +msgstr "" + +#: ../../library/concurrent.interpreters.rst:200 +msgid ":class:`memoryview`" +msgstr ":class:`memoryview`" + +#: ../../library/concurrent.interpreters.rst:201 +msgid ":class:`Queue`" +msgstr ":class:`Queue`" + +#: ../../library/concurrent.interpreters.rst:205 +msgid "Reference" +msgstr "" + +#: ../../library/concurrent.interpreters.rst:207 +msgid "This module defines the following functions:" +msgstr "" + +#: ../../library/concurrent.interpreters.rst:211 +msgid "" +"Return a :class:`list` of :class:`Interpreter` objects, one for each " +"existing interpreter." +msgstr "" + +#: ../../library/concurrent.interpreters.rst:216 +msgid "" +"Return an :class:`Interpreter` object for the currently running interpreter." +msgstr "" + +#: ../../library/concurrent.interpreters.rst:221 +msgid "" +"Return an :class:`Interpreter` object for the main interpreter. This is the " +"interpreter the runtime created to run the :term:`REPL` or the script given " +"at the command-line. It is usually the only one." +msgstr "" + +#: ../../library/concurrent.interpreters.rst:227 +msgid "" +"Initialize a new (idle) Python interpreter and return a :class:`Interpreter` " +"object for it." +msgstr "" + +#: ../../library/concurrent.interpreters.rst:232 +msgid "" +"Initialize a new cross-interpreter queue and return a :class:`Queue` object " +"for it." +msgstr "" + +#: ../../library/concurrent.interpreters.rst:237 +msgid "Interpreter objects" +msgstr "" + +#: ../../library/concurrent.interpreters.rst:241 +msgid "A single interpreter in the current process." +msgstr "" + +#: ../../library/concurrent.interpreters.rst:243 +msgid "" +"Generally, :class:`Interpreter` shouldn't be called directly. Instead, use :" +"func:`create` or one of the other module functions." +msgstr "" + +#: ../../library/concurrent.interpreters.rst:248 +#: ../../library/concurrent.interpreters.rst:254 +#: ../../library/concurrent.interpreters.rst:333 +msgid "(read-only)" +msgstr "" + +#: ../../library/concurrent.interpreters.rst:250 +msgid "The underlying interpreter's ID." +msgstr "" + +#: ../../library/concurrent.interpreters.rst:256 +msgid "A string describing where the interpreter came from." +msgstr "" + +#: ../../library/concurrent.interpreters.rst:260 +msgid "" +"Return ``True`` if the interpreter is currently executing code in its :mod:`!" +"__main__` module and ``False`` otherwise." +msgstr "" + +#: ../../library/concurrent.interpreters.rst:265 +msgid "Finalize and destroy the interpreter." +msgstr "" + +#: ../../library/concurrent.interpreters.rst:269 +msgid "Bind objects in the interpreter's :mod:`!__main__` module." +msgstr "" + +#: ../../library/concurrent.interpreters.rst:271 +#: ../../library/concurrent.interpreters.rst:328 +msgid "" +"Some objects are actually shared and some are copied efficiently, but most " +"are copied via :mod:`pickle`. See :ref:`interp-object-sharing`." +msgstr "" + +#: ../../library/concurrent.interpreters.rst:276 +msgid "Run the given source code in the interpreter (in the current thread)." +msgstr "" + +#: ../../library/concurrent.interpreters.rst:280 +msgid "" +"Return the result of calling running the given function in the interpreter " +"(in the current thread)." +msgstr "" + +#: ../../library/concurrent.interpreters.rst:287 +msgid "Run the given function in the interpreter (in a new thread)." +msgstr "" + +#: ../../library/concurrent.interpreters.rst:290 +msgid "Exceptions" +msgstr "例外" + +#: ../../library/concurrent.interpreters.rst:294 +msgid "" +"This exception, a subclass of :exc:`Exception`, is raised when an " +"interpreter-related error happens." +msgstr "" + +#: ../../library/concurrent.interpreters.rst:299 +msgid "" +"This exception, a subclass of :exc:`InterpreterError`, is raised when the " +"targeted interpreter no longer exists." +msgstr "" + +#: ../../library/concurrent.interpreters.rst:304 +msgid "" +"This exception, a subclass of :exc:`InterpreterError`, is raised when the " +"running code raised an uncaught exception." +msgstr "" + +#: ../../library/concurrent.interpreters.rst:309 +msgid "A basic snapshot of the exception raised in the other interpreter." +msgstr "" + +#: ../../library/concurrent.interpreters.rst:315 +msgid "" +"This exception, a subclass of :exc:`TypeError`, is raised when an object " +"cannot be sent to another interpreter." +msgstr "" + +#: ../../library/concurrent.interpreters.rst:320 +msgid "Communicating Between Interpreters" +msgstr "在直譯器之間溝通" + +#: ../../library/concurrent.interpreters.rst:324 +msgid "" +"A wrapper around a low-level, cross-interpreter queue, which implements the :" +"class:`queue.Queue` interface. The underlying queue can only be created " +"through :func:`create_queue`." +msgstr "" + +#: ../../library/concurrent.interpreters.rst:335 +msgid "The queue's ID." +msgstr "" + +#: ../../library/concurrent.interpreters.rst:340 +msgid "" +"This exception, a subclass of :exc:`queue.Empty`, is raised from :meth:`!" +"Queue.get` and :meth:`!Queue.get_nowait` when the queue is empty." +msgstr "" + +#: ../../library/concurrent.interpreters.rst:346 +msgid "" +"This exception, a subclass of :exc:`queue.Full`, is raised from :meth:`!" +"Queue.put` and :meth:`!Queue.put_nowait` when the queue is full." +msgstr "" + +#: ../../library/concurrent.interpreters.rst:352 +msgid "Basic usage" +msgstr "基本用法" + +#: ../../library/concurrent.interpreters.rst:354 +msgid "Creating an interpreter and running code in it::" +msgstr "建立一個直譯器並在其中運行程式碼： ::" + +#: ../../library/concurrent.interpreters.rst:356 +msgid "" +"from concurrent import interpreters\n" +"\n" +"interp = interpreters.create()\n" +"\n" +"# Run in the current OS thread.\n" +"\n" +"interp.exec('print(\"spam!\")')\n" +"\n" +"interp.exec(\"\"\"if True:\n" +" print('spam!')\n" +" \"\"\")\n" +"\n" +"from textwrap import dedent\n" +"interp.exec(dedent(\"\"\"\n" +" print('spam!')\n" +" \"\"\"))\n" +"\n" +"def run(arg):\n" +" return arg\n" +"\n" +"res = interp.call(run, 'spam!')\n" +"print(res)\n" +"\n" +"def run():\n" +" print('spam!')\n" +"\n" +"interp.call(run)\n" +"\n" +"# Run in new OS thread.\n" +"\n" +"t = interp.call_in_thread(run)\n" +"t.join()" +msgstr "" diff --git a/library/concurrent.po b/library/concurrent.po index 109a8dc417..a7cbaa581d 100644 --- a/library/concurrent.po +++ b/library/concurrent.po @@ -1,37 +1,37 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Matt Wang , 2021 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: 2015-12-09 17:51+0000\n" -"Last-Translator: Matt Wang \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/concurrent.rst:2 -msgid "The :mod:`!concurrent` package" -msgstr ":mod:`!concurrent` 套件" - -#: ../../library/concurrent.rst:4 -msgid "This package contains the following modules:" -msgstr "此套件包含下列模組：" - -#: ../../library/concurrent.rst:6 -msgid ":mod:`concurrent.futures` -- Launching parallel tasks" -msgstr ":mod:`concurrent.futures` -- 啟動平行任務" - -#: ../../library/concurrent.rst:7 -msgid "" -":mod:`concurrent.interpreters` -- Multiple interpreters in the same process" -msgstr "" -":mod:`concurrent.interpreters` -- 在同一行程中使用多個直譯器" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Matt Wang , 2021 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: 2015-12-09 17:51+0000\n" +"Last-Translator: Matt Wang \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/concurrent.rst:2 +msgid "The :mod:`!concurrent` package" +msgstr ":mod:`!concurrent` 套件" + +#: ../../library/concurrent.rst:4 +msgid "This package contains the following modules:" +msgstr "此套件包含下列模組：" + +#: ../../library/concurrent.rst:6 +msgid ":mod:`concurrent.futures` -- Launching parallel tasks" +msgstr ":mod:`concurrent.futures` -- 啟動平行任務" + +#: ../../library/concurrent.rst:7 +msgid "" +":mod:`concurrent.interpreters` -- Multiple interpreters in the same process" +msgstr "" +":mod:`concurrent.interpreters` -- 在同一行程中使用多個直譯器" diff --git a/library/configparser.po b/library/configparser.po index 7354b91f23..bc3fb2cc09 100644 --- a/library/configparser.po +++ b/library/configparser.po @@ -1,2008 +1,2008 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: 2018-05-23 14:41+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/configparser.rst:2 -msgid ":mod:`!configparser` --- Configuration file parser" -msgstr ":mod:`!configparser` --- 設定檔剖析器" - -#: ../../library/configparser.rst:14 -msgid "**Source code:** :source:`Lib/configparser.py`" -msgstr "**原始碼：**\\ :source:`Lib/configparser.py`" - -#: ../../library/configparser.rst:24 -msgid "" -"This module provides the :class:`ConfigParser` class which implements a " -"basic configuration language which provides a structure similar to what's " -"found in Microsoft Windows INI files. You can use this to write Python " -"programs which can be customized by end users easily." -msgstr "" - -#: ../../library/configparser.rst:31 -msgid "" -"This library does *not* interpret or write the value-type prefixes used in " -"the Windows Registry extended version of INI syntax." -msgstr "" - -#: ../../library/configparser.rst:36 -msgid "Module :mod:`tomllib`" -msgstr ":mod:`tomllib` 模組" - -#: ../../library/configparser.rst:37 -msgid "" -"TOML is a well-specified format for application configuration files. It is " -"specifically designed to be an improved version of INI." -msgstr "" - -#: ../../library/configparser.rst:40 -msgid "Module :mod:`shlex`" -msgstr ":mod:`shlex` 模組" - -#: ../../library/configparser.rst:41 -msgid "" -"Support for creating Unix shell-like mini-languages which can also be used " -"for application configuration files." -msgstr "" - -#: ../../library/configparser.rst:44 -msgid "Module :mod:`json`" -msgstr ":mod:`json` 模組" - -#: ../../library/configparser.rst:45 -msgid "" -"The ``json`` module implements a subset of JavaScript syntax which is " -"sometimes used for configuration, but does not support comments." -msgstr "" - -#: ../../library/configparser.rst:61 -msgid "Quick Start" -msgstr "" - -#: ../../library/configparser.rst:63 -msgid "Let's take a very basic configuration file that looks like this:" -msgstr "" - -#: ../../library/configparser.rst:65 -msgid "" -"[DEFAULT]\n" -"ServerAliveInterval = 45\n" -"Compression = yes\n" -"CompressionLevel = 9\n" -"ForwardX11 = yes\n" -"\n" -"[forge.example]\n" -"User = hg\n" -"\n" -"[topsecret.server.example]\n" -"Port = 50022\n" -"ForwardX11 = no" -msgstr "" -"[DEFAULT]\n" -"ServerAliveInterval = 45\n" -"Compression = yes\n" -"CompressionLevel = 9\n" -"ForwardX11 = yes\n" -"\n" -"[forge.example]\n" -"User = hg\n" -"\n" -"[topsecret.server.example]\n" -"Port = 50022\n" -"ForwardX11 = no" - -#: ../../library/configparser.rst:80 -msgid "" -"The structure of INI files is described `in the following section " -"<#supported-ini-file-structure>`_. Essentially, the file consists of " -"sections, each of which contains keys with values. :mod:`configparser` " -"classes can read and write such files. Let's start by creating the above " -"configuration file programmatically." -msgstr "" - -#: ../../library/configparser.rst:86 -msgid "" -">>> import configparser\n" -">>> config = configparser.ConfigParser()\n" -">>> config['DEFAULT'] = {'ServerAliveInterval': '45',\n" -"... 'Compression': 'yes',\n" -"... 'CompressionLevel': '9'}\n" -">>> config['forge.example'] = {}\n" -">>> config['forge.example']['User'] = 'hg'\n" -">>> config['topsecret.server.example'] = {}\n" -">>> topsecret = config['topsecret.server.example']\n" -">>> topsecret['Port'] = '50022' # mutates the parser\n" -">>> topsecret['ForwardX11'] = 'no' # same here\n" -">>> config['DEFAULT']['ForwardX11'] = 'yes'\n" -">>> with open('example.ini', 'w') as configfile:\n" -"... config.write(configfile)\n" -"..." -msgstr "" -">>> import configparser\n" -">>> config = configparser.ConfigParser()\n" -">>> config['DEFAULT'] = {'ServerAliveInterval': '45',\n" -"... 'Compression': 'yes',\n" -"... 'CompressionLevel': '9'}\n" -">>> config['forge.example'] = {}\n" -">>> config['forge.example']['User'] = 'hg'\n" -">>> config['topsecret.server.example'] = {}\n" -">>> topsecret = config['topsecret.server.example']\n" -">>> topsecret['Port'] = '50022' # mutates the parser\n" -">>> topsecret['ForwardX11'] = 'no' # same here\n" -">>> config['DEFAULT']['ForwardX11'] = 'yes'\n" -">>> with open('example.ini', 'w') as configfile:\n" -"... config.write(configfile)\n" -"..." - -#: ../../library/configparser.rst:104 -msgid "" -"As you can see, we can treat a config parser much like a dictionary. There " -"are differences, `outlined later <#mapping-protocol-access>`_, but the " -"behavior is very close to what you would expect from a dictionary." -msgstr "" - -#: ../../library/configparser.rst:108 -msgid "" -"Now that we have created and saved a configuration file, let's read it back " -"and explore the data it holds." -msgstr "" - -#: ../../library/configparser.rst:111 -msgid "" -">>> config = configparser.ConfigParser()\n" -">>> config.sections()\n" -"[]\n" -">>> config.read('example.ini')\n" -"['example.ini']\n" -">>> config.sections()\n" -"['forge.example', 'topsecret.server.example']\n" -">>> 'forge.example' in config\n" -"True\n" -">>> 'python.org' in config\n" -"False\n" -">>> config['forge.example']['User']\n" -"'hg'\n" -">>> config['DEFAULT']['Compression']\n" -"'yes'\n" -">>> topsecret = config['topsecret.server.example']\n" -">>> topsecret['ForwardX11']\n" -"'no'\n" -">>> topsecret['Port']\n" -"'50022'\n" -">>> for key in config['forge.example']:\n" -"... print(key)\n" -"user\n" -"compressionlevel\n" -"serveraliveinterval\n" -"compression\n" -"forwardx11\n" -">>> config['forge.example']['ForwardX11']\n" -"'yes'" -msgstr "" -">>> config = configparser.ConfigParser()\n" -">>> config.sections()\n" -"[]\n" -">>> config.read('example.ini')\n" -"['example.ini']\n" -">>> config.sections()\n" -"['forge.example', 'topsecret.server.example']\n" -">>> 'forge.example' in config\n" -"True\n" -">>> 'python.org' in config\n" -"False\n" -">>> config['forge.example']['User']\n" -"'hg'\n" -">>> config['DEFAULT']['Compression']\n" -"'yes'\n" -">>> topsecret = config['topsecret.server.example']\n" -">>> topsecret['ForwardX11']\n" -"'no'\n" -">>> topsecret['Port']\n" -"'50022'\n" -">>> for key in config['forge.example']:\n" -"... print(key)\n" -"user\n" -"compressionlevel\n" -"serveraliveinterval\n" -"compression\n" -"forwardx11\n" -">>> config['forge.example']['ForwardX11']\n" -"'yes'" - -#: ../../library/configparser.rst:143 -msgid "" -"As we can see above, the API is pretty straightforward. The only bit of " -"magic involves the ``DEFAULT`` section which provides default values for all " -"other sections [1]_. Note also that keys in sections are case-insensitive " -"and stored in lowercase [1]_." -msgstr "" - -#: ../../library/configparser.rst:148 ../../library/configparser.rst:1003 -msgid "" -"It is possible to read several configurations into a " -"single :class:`ConfigParser`, where the most recently added configuration " -"has the highest priority. Any conflicting keys are taken from the more " -"recent configuration while the previously existing keys are retained. The " -"example below reads in an ``override.ini`` file, which will override any " -"conflicting keys from the ``example.ini`` file." -msgstr "" - -#: ../../library/configparser.rst:155 ../../library/configparser.rst:1010 -msgid "" -"[DEFAULT]\n" -"ServerAliveInterval = -1" -msgstr "" -"[DEFAULT]\n" -"ServerAliveInterval = -1" - -#: ../../library/configparser.rst:160 ../../library/configparser.rst:1015 -msgid "" -">>> config_override = configparser.ConfigParser()\n" -">>> config_override['DEFAULT'] = {'ServerAliveInterval': '-1'}\n" -">>> with open('override.ini', 'w') as configfile:\n" -"... config_override.write(configfile)\n" -"...\n" -">>> config_override = configparser.ConfigParser()\n" -">>> config_override.read(['example.ini', 'override.ini'])\n" -"['example.ini', 'override.ini']\n" -">>> print(config_override.get('DEFAULT', 'ServerAliveInterval'))\n" -"-1" -msgstr "" -">>> config_override = configparser.ConfigParser()\n" -">>> config_override['DEFAULT'] = {'ServerAliveInterval': '-1'}\n" -">>> with open('override.ini', 'w') as configfile:\n" -"... config_override.write(configfile)\n" -"...\n" -">>> config_override = configparser.ConfigParser()\n" -">>> config_override.read(['example.ini', 'override.ini'])\n" -"['example.ini', 'override.ini']\n" -">>> print(config_override.get('DEFAULT', 'ServerAliveInterval'))\n" -"-1" - -#: ../../library/configparser.rst:174 -msgid "" -"This behaviour is equivalent to a :meth:`ConfigParser.read` call with " -"several files passed to the *filenames* parameter." -msgstr "" - -#: ../../library/configparser.rst:179 -msgid "Supported Datatypes" -msgstr "" - -#: ../../library/configparser.rst:181 -msgid "" -"Config parsers do not guess datatypes of values in configuration files, " -"always storing them internally as strings. This means that if you need " -"other datatypes, you should convert on your own:" -msgstr "" - -#: ../../library/configparser.rst:185 -msgid "" -">>> int(topsecret['Port'])\n" -"50022\n" -">>> float(topsecret['CompressionLevel'])\n" -"9.0" -msgstr "" -">>> int(topsecret['Port'])\n" -"50022\n" -">>> float(topsecret['CompressionLevel'])\n" -"9.0" - -#: ../../library/configparser.rst:192 -msgid "" -"Since this task is so common, config parsers provide a range of handy getter " -"methods to handle integers, floats and booleans. The last one is the most " -"interesting because simply passing the value to ``bool()`` would do no good " -"since ``bool('False')`` is still ``True``. This is why config parsers also " -"provide :meth:`~ConfigParser.getboolean`. This method is case-insensitive " -"and recognizes Boolean values from ``'yes'``/``'no'``, ``'on'``/``'off'``, " -"``'true'``/``'false'`` and ``'1'``/``'0'`` [1]_. For example:" -msgstr "" - -#: ../../library/configparser.rst:200 -msgid "" -">>> topsecret.getboolean('ForwardX11')\n" -"False\n" -">>> config['forge.example'].getboolean('ForwardX11')\n" -"True\n" -">>> config.getboolean('forge.example', 'Compression')\n" -"True" -msgstr "" -">>> topsecret.getboolean('ForwardX11')\n" -"False\n" -">>> config['forge.example'].getboolean('ForwardX11')\n" -"True\n" -">>> config.getboolean('forge.example', 'Compression')\n" -"True" - -#: ../../library/configparser.rst:209 -msgid "" -"Apart from :meth:`~ConfigParser.getboolean`, config parsers also provide " -"equivalent :meth:`~ConfigParser.getint` and :meth:`~ConfigParser.getfloat` " -"methods. You can register your own converters and customize the provided " -"ones. [1]_" -msgstr "" - -#: ../../library/configparser.rst:215 -msgid "Fallback Values" -msgstr "" - -#: ../../library/configparser.rst:217 -msgid "" -"As with a dictionary, you can use a section's :meth:`~ConfigParser.get` " -"method to provide fallback values:" -msgstr "" - -#: ../../library/configparser.rst:220 -msgid "" -">>> topsecret.get('Port')\n" -"'50022'\n" -">>> topsecret.get('CompressionLevel')\n" -"'9'\n" -">>> topsecret.get('Cipher')\n" -">>> topsecret.get('Cipher', '3des-cbc')\n" -"'3des-cbc'" -msgstr "" -">>> topsecret.get('Port')\n" -"'50022'\n" -">>> topsecret.get('CompressionLevel')\n" -"'9'\n" -">>> topsecret.get('Cipher')\n" -">>> topsecret.get('Cipher', '3des-cbc')\n" -"'3des-cbc'" - -#: ../../library/configparser.rst:230 -msgid "" -"Please note that default values have precedence over fallback values. For " -"instance, in our example the ``'CompressionLevel'`` key was specified only " -"in the ``'DEFAULT'`` section. If we try to get it from the section " -"``'topsecret.server.example'``, we will always get the default, even if we " -"specify a fallback:" -msgstr "" - -#: ../../library/configparser.rst:236 -msgid "" -">>> topsecret.get('CompressionLevel', '3')\n" -"'9'" -msgstr "" -">>> topsecret.get('CompressionLevel', '3')\n" -"'9'" - -#: ../../library/configparser.rst:241 -msgid "" -"One more thing to be aware of is that the parser-" -"level :meth:`~ConfigParser.get` method provides a custom, more complex " -"interface, maintained for backwards compatibility. When using this method, " -"a fallback value can be provided via the ``fallback`` keyword-only argument:" -msgstr "" - -#: ../../library/configparser.rst:246 -msgid "" -">>> config.get('forge.example', 'monster',\n" -"... fallback='No such things as monsters')\n" -"'No such things as monsters'" -msgstr "" -">>> config.get('forge.example', 'monster',\n" -"... fallback='No such things as monsters')\n" -"'No such things as monsters'" - -#: ../../library/configparser.rst:252 -msgid "" -"The same ``fallback`` argument can be used with " -"the :meth:`~ConfigParser.getint`, :meth:`~ConfigParser.getfloat` " -"and :meth:`~ConfigParser.getboolean` methods, for example:" -msgstr "" - -#: ../../library/configparser.rst:256 -msgid "" -">>> 'BatchMode' in topsecret\n" -"False\n" -">>> topsecret.getboolean('BatchMode', fallback=True)\n" -"True\n" -">>> config['DEFAULT']['BatchMode'] = 'no'\n" -">>> topsecret.getboolean('BatchMode', fallback=True)\n" -"False" -msgstr "" -">>> 'BatchMode' in topsecret\n" -"False\n" -">>> topsecret.getboolean('BatchMode', fallback=True)\n" -"True\n" -">>> config['DEFAULT']['BatchMode'] = 'no'\n" -">>> topsecret.getboolean('BatchMode', fallback=True)\n" -"False" - -#: ../../library/configparser.rst:268 -msgid "Supported INI File Structure" -msgstr "支援的 INI 檔案結構" - -#: ../../library/configparser.rst:270 -msgid "" -"A configuration file consists of sections, each led by a ``[section]`` " -"header, followed by key/value entries separated by a specific string (``=`` " -"or ``:`` by default [1]_). By default, section names are case sensitive but " -"keys are not [1]_. Leading and trailing whitespace is removed from keys and " -"values. Values can be omitted if the parser is configured to allow it [1]_, " -"in which case the key/value delimiter may also be left out. Values can also " -"span multiple lines, as long as they are indented deeper than the first line " -"of the value. Depending on the parser's mode, blank lines may be treated as " -"parts of multiline values or ignored." -msgstr "" - -#: ../../library/configparser.rst:280 -msgid "" -"By default, a valid section name can be any string that does not contain '\\" -"\\n'. To change this, see :attr:`ConfigParser.SECTCRE`." -msgstr "" - -#: ../../library/configparser.rst:283 -msgid "" -"The first section name may be omitted if the parser is configured to allow " -"an unnamed top level section with ``allow_unnamed_section=True``. In this " -"case, the keys/values may be retrieved by :const:`UNNAMED_SECTION` as in " -"``config[UNNAMED_SECTION]``." -msgstr "" - -#: ../../library/configparser.rst:288 -msgid "" -"Configuration files may include comments, prefixed by specific characters " -"(``#`` and ``;`` by default [1]_). Comments may appear on their own on an " -"otherwise empty line, possibly indented. [1]_" -msgstr "" - -#: ../../library/configparser.rst:292 ../../library/configparser.rst:376 -msgid "For example:" -msgstr "舉例來說：" - -#: ../../library/configparser.rst:294 -msgid "" -"[Simple Values]\n" -"key=value\n" -"spaces in keys=allowed\n" -"spaces in values=allowed as well\n" -"spaces around the delimiter = obviously\n" -"you can also use : to delimit keys from values\n" -"\n" -"[All Values Are Strings]\n" -"values like this: 1000000\n" -"or this: 3.14159265359\n" -"are they treated as numbers? : no\n" -"integers, floats and booleans are held as: strings\n" -"can use the API to get converted values directly: true\n" -"\n" -"[Multiline Values]\n" -"chorus: I'm a lumberjack, and I'm okay\n" -" I sleep all night and I work all day\n" -"\n" -"[No Values]\n" -"key_without_value\n" -"empty string value here =\n" -"\n" -"[You can use comments]\n" -"# like this\n" -"; or this\n" -"\n" -"# By default only in an empty line.\n" -"# Inline comments can be harmful because they prevent users\n" -"# from using the delimiting characters as parts of values.\n" -"# That being said, this can be customized.\n" -"\n" -" [Sections Can Be Indented]\n" -" can_values_be_as_well = True\n" -" does_that_mean_anything_special = False\n" -" purpose = formatting for readability\n" -" multiline_values = are\n" -" handled just fine as\n" -" long as they are indented\n" -" deeper than the first line\n" -" of a value\n" -" # Did I mention we can indent comments, too?" -msgstr "" - -#: ../../library/configparser.rst:342 -msgid "Unnamed Sections" -msgstr "" - -#: ../../library/configparser.rst:344 -msgid "" -"The name of the first section (or unique) may be omitted and values " -"retrieved by the :const:`UNNAMED_SECTION` attribute." -msgstr "" - -#: ../../library/configparser.rst:347 -msgid "" -">>> config = \"\"\"\n" -"... option = value\n" -"...\n" -"... [ Section 2 ]\n" -"... another = val\n" -"... \"\"\"\n" -">>> unnamed = configparser.ConfigParser(allow_unnamed_section=True)\n" -">>> unnamed.read_string(config)\n" -">>> unnamed.get(configparser.UNNAMED_SECTION, 'option')\n" -"'value'" -msgstr "" -">>> config = \"\"\"\n" -"... option = value\n" -"...\n" -"... [ Section 2 ]\n" -"... another = val\n" -"... \"\"\"\n" -">>> unnamed = configparser.ConfigParser(allow_unnamed_section=True)\n" -">>> unnamed.read_string(config)\n" -">>> unnamed.get(configparser.UNNAMED_SECTION, 'option')\n" -"'value'" - -#: ../../library/configparser.rst:361 -msgid "Interpolation of values" -msgstr "" - -#: ../../library/configparser.rst:363 -msgid "" -"On top of the core functionality, :class:`ConfigParser` supports " -"interpolation. This means values can be preprocessed before returning them " -"from ``get()`` calls." -msgstr "" - -#: ../../library/configparser.rst:371 -msgid "" -"The default implementation used by :class:`ConfigParser`. It enables values " -"to contain format strings which refer to other values in the same section, " -"or values in the special default section [1]_. Additional default values " -"can be provided on initialization." -msgstr "" - -#: ../../library/configparser.rst:378 -msgid "" -"[Paths]\n" -"home_dir: /Users\n" -"my_dir: %(home_dir)s/lumberjack\n" -"my_pictures: %(my_dir)s/Pictures\n" -"\n" -"[Escape]\n" -"# use a %% to escape the % sign (% is the only character that needs to be " -"escaped):\n" -"gain: 80%%" -msgstr "" - -#: ../../library/configparser.rst:389 -msgid "" -"In the example above, :class:`ConfigParser` with *interpolation* set to " -"``BasicInterpolation()`` would resolve ``%(home_dir)s`` to the value of " -"``home_dir`` (``/Users`` in this case). ``%(my_dir)s`` in effect would " -"resolve to ``/Users/lumberjack``. All interpolations are done on demand so " -"keys used in the chain of references do not have to be specified in any " -"specific order in the configuration file." -msgstr "" - -#: ../../library/configparser.rst:396 -msgid "" -"With ``interpolation`` set to ``None``, the parser would simply return ``%" -"(my_dir)s/Pictures`` as the value of ``my_pictures`` and ``%(home_dir)s/" -"lumberjack`` as the value of ``my_dir``." -msgstr "" - -#: ../../library/configparser.rst:404 -msgid "" -"An alternative handler for interpolation which implements a more advanced " -"syntax, used for instance in ``zc.buildout``. Extended interpolation is " -"using ``${section:option}`` to denote a value from a foreign section. " -"Interpolation can span multiple levels. For convenience, if the " -"``section:`` part is omitted, interpolation defaults to the current section " -"(and possibly the default values from the special section)." -msgstr "" - -#: ../../library/configparser.rst:411 -msgid "" -"For example, the configuration specified above with basic interpolation, " -"would look like this with extended interpolation:" -msgstr "" - -#: ../../library/configparser.rst:414 -msgid "" -"[Paths]\n" -"home_dir: /Users\n" -"my_dir: ${home_dir}/lumberjack\n" -"my_pictures: ${my_dir}/Pictures\n" -"\n" -"[Escape]\n" -"# use a $$ to escape the $ sign ($ is the only character that needs to be " -"escaped):\n" -"cost: $$80" -msgstr "" - -#: ../../library/configparser.rst:425 -msgid "Values from other sections can be fetched as well:" -msgstr "" - -#: ../../library/configparser.rst:427 -msgid "" -"[Common]\n" -"home_dir: /Users\n" -"library_dir: /Library\n" -"system_dir: /System\n" -"macports_dir: /opt/local\n" -"\n" -"[Frameworks]\n" -"Python: 3.2\n" -"path: ${Common:system_dir}/Library/Frameworks/\n" -"\n" -"[Arthur]\n" -"nickname: Two Sheds\n" -"last_name: Jackson\n" -"my_dir: ${Common:home_dir}/twosheds\n" -"my_pictures: ${my_dir}/Pictures\n" -"python_dir: ${Frameworks:path}/Python/Versions/${Frameworks:Python}" -msgstr "" -"[Common]\n" -"home_dir: /Users\n" -"library_dir: /Library\n" -"system_dir: /System\n" -"macports_dir: /opt/local\n" -"\n" -"[Frameworks]\n" -"Python: 3.2\n" -"path: ${Common:system_dir}/Library/Frameworks/\n" -"\n" -"[Arthur]\n" -"nickname: Two Sheds\n" -"last_name: Jackson\n" -"my_dir: ${Common:home_dir}/twosheds\n" -"my_pictures: ${my_dir}/Pictures\n" -"python_dir: ${Frameworks:path}/Python/Versions/${Frameworks:Python}" - -#: ../../library/configparser.rst:447 -msgid "Mapping Protocol Access" -msgstr "" - -#: ../../library/configparser.rst:451 -msgid "" -"Mapping protocol access is a generic name for functionality that enables " -"using custom objects as if they were dictionaries. In case " -"of :mod:`configparser`, the mapping interface implementation is using the " -"``parser['section']['option']`` notation." -msgstr "" - -#: ../../library/configparser.rst:456 -msgid "" -"``parser['section']`` in particular returns a proxy for the section's data " -"in the parser. This means that the values are not copied but they are taken " -"from the original parser on demand. What's even more important is that when " -"values are changed on a section proxy, they are actually mutated in the " -"original parser." -msgstr "" - -#: ../../library/configparser.rst:462 -msgid "" -":mod:`configparser` objects behave as close to actual dictionaries as " -"possible. The mapping interface is complete and adheres to " -"the :class:`~collections.abc.MutableMapping` ABC. However, there are a few " -"differences that should be taken into account:" -msgstr "" - -#: ../../library/configparser.rst:467 -msgid "" -"By default, all keys in sections are accessible in a case-insensitive manner " -"[1]_. E.g. ``for option in parser[\"section\"]`` yields only " -"``optionxform``'ed option key names. This means lowercased keys by " -"default. At the same time, for a section that holds the key ``'a'``, both " -"expressions return ``True``::" -msgstr "" - -#: ../../library/configparser.rst:472 -msgid "" -"\"a\" in parser[\"section\"]\n" -"\"A\" in parser[\"section\"]" -msgstr "" -"\"a\" in parser[\"section\"]\n" -"\"A\" in parser[\"section\"]" - -#: ../../library/configparser.rst:475 -msgid "" -"All sections include ``DEFAULTSECT`` values as well which means that " -"``.clear()`` on a section may not leave the section visibly empty. This is " -"because default values cannot be deleted from the section (because " -"technically they are not there). If they are overridden in the section, " -"deleting causes the default value to be visible again. Trying to delete a " -"default value causes a :exc:`KeyError`." -msgstr "" - -#: ../../library/configparser.rst:482 -msgid "``DEFAULTSECT`` cannot be removed from the parser:" -msgstr "``DEFAULTSECT`` 不能從剖析器中移除：" - -#: ../../library/configparser.rst:484 -msgid "trying to delete it raises :exc:`ValueError`," -msgstr "嘗試刪除它會引發 :exc:`ValueError`，" - -#: ../../library/configparser.rst:486 -msgid "``parser.clear()`` leaves it intact," -msgstr "``parser.clear()`` 會保持它不變，" - -#: ../../library/configparser.rst:488 -msgid "``parser.popitem()`` never returns it." -msgstr "``parser.popitem()`` 永遠不會回傳它。" - -#: ../../library/configparser.rst:490 -msgid "" -"``parser.get(section, option, **kwargs)`` - the second argument is **not** a " -"fallback value. Note however that the section-level ``get()`` methods are " -"compatible both with the mapping protocol and the classic configparser API." -msgstr "" - -#: ../../library/configparser.rst:494 -msgid "" -"``parser.items()`` is compatible with the mapping protocol (returns a list " -"of *section_name*, *section_proxy* pairs including the DEFAULTSECT). " -"However, this method can also be invoked with arguments: " -"``parser.items(section, raw, vars)``. The latter call returns a list of " -"*option*, *value* pairs for a specified ``section``, with all interpolations " -"expanded (unless ``raw=True`` is provided)." -msgstr "" - -#: ../../library/configparser.rst:501 -msgid "" -"The mapping protocol is implemented on top of the existing legacy API so " -"that subclasses overriding the original interface still should have mappings " -"working as expected." -msgstr "" - -#: ../../library/configparser.rst:507 -msgid "Customizing Parser Behaviour" -msgstr "" - -#: ../../library/configparser.rst:509 -msgid "" -"There are nearly as many INI format variants as there are applications using " -"it. :mod:`configparser` goes a long way to provide support for the largest " -"sensible set of INI styles available. The default functionality is mainly " -"dictated by historical background and it's very likely that you will want to " -"customize some of the features." -msgstr "" - -#: ../../library/configparser.rst:515 -msgid "" -"The most common way to change the way a specific config parser works is to " -"use the :meth:`!__init__` options:" -msgstr "" - -#: ../../library/configparser.rst:518 -msgid "*defaults*, default value: ``None``" -msgstr "" - -#: ../../library/configparser.rst:520 -msgid "" -"This option accepts a dictionary of key-value pairs which will be initially " -"put in the ``DEFAULT`` section. This makes for an elegant way to support " -"concise configuration files that don't specify values which are the same as " -"the documented default." -msgstr "" - -#: ../../library/configparser.rst:525 -msgid "" -"Hint: if you want to specify default values for a specific section, " -"use :meth:`~ConfigParser.read_dict` before you read the actual file." -msgstr "" - -#: ../../library/configparser.rst:528 -msgid "*dict_type*, default value: :class:`dict`" -msgstr "" - -#: ../../library/configparser.rst:530 -msgid "" -"This option has a major impact on how the mapping protocol will behave and " -"how the written configuration files look. With the standard dictionary, " -"every section is stored in the order they were added to the parser. Same " -"goes for options within sections." -msgstr "" - -#: ../../library/configparser.rst:535 -msgid "" -"An alternative dictionary type can be used for example to sort sections and " -"options on write-back." -msgstr "" - -#: ../../library/configparser.rst:538 -msgid "" -"Please note: there are ways to add a set of key-value pairs in a single " -"operation. When you use a regular dictionary in those operations, the order " -"of the keys will be ordered. For example:" -msgstr "" - -#: ../../library/configparser.rst:542 -msgid "" -">>> parser = configparser.ConfigParser()\n" -">>> parser.read_dict({'section1': {'key1': 'value1',\n" -"... 'key2': 'value2',\n" -"... 'key3': 'value3'},\n" -"... 'section2': {'keyA': 'valueA',\n" -"... 'keyB': 'valueB',\n" -"... 'keyC': 'valueC'},\n" -"... 'section3': {'foo': 'x',\n" -"... 'bar': 'y',\n" -"... 'baz': 'z'}\n" -"... })\n" -">>> parser.sections()\n" -"['section1', 'section2', 'section3']\n" -">>> [option for option in parser['section3']]\n" -"['foo', 'bar', 'baz']" -msgstr "" -">>> parser = configparser.ConfigParser()\n" -">>> parser.read_dict({'section1': {'key1': 'value1',\n" -"... 'key2': 'value2',\n" -"... 'key3': 'value3'},\n" -"... 'section2': {'keyA': 'valueA',\n" -"... 'keyB': 'valueB',\n" -"... 'keyC': 'valueC'},\n" -"... 'section3': {'foo': 'x',\n" -"... 'bar': 'y',\n" -"... 'baz': 'z'}\n" -"... })\n" -">>> parser.sections()\n" -"['section1', 'section2', 'section3']\n" -">>> [option for option in parser['section3']]\n" -"['foo', 'bar', 'baz']" - -#: ../../library/configparser.rst:560 -msgid "*allow_no_value*, default value: ``False``" -msgstr "" - -#: ../../library/configparser.rst:562 -msgid "" -"Some configuration files are known to include settings without values, but " -"which otherwise conform to the syntax supported by :mod:`configparser`. The " -"*allow_no_value* parameter to the constructor can be used to indicate that " -"such values should be accepted:" -msgstr "" - -#: ../../library/configparser.rst:567 -msgid "" -">>> import configparser\n" -"\n" -">>> sample_config = \"\"\"\n" -"... [mysqld]\n" -"... user = mysql\n" -"... pid-file = /var/run/mysqld/mysqld.pid\n" -"... skip-external-locking\n" -"... old_passwords = 1\n" -"... skip-bdb\n" -"... # we don't need ACID today\n" -"... skip-innodb\n" -"... \"\"\"\n" -">>> config = configparser.ConfigParser(allow_no_value=True)\n" -">>> config.read_string(sample_config)\n" -"\n" -">>> # Settings with values are treated as before:\n" -">>> config[\"mysqld\"][\"user\"]\n" -"'mysql'\n" -"\n" -">>> # Settings without values provide None:\n" -">>> config[\"mysqld\"][\"skip-bdb\"]\n" -"\n" -">>> # Settings which aren't specified still raise an error:\n" -">>> config[\"mysqld\"][\"does-not-exist\"]\n" -"Traceback (most recent call last):\n" -" ...\n" -"KeyError: 'does-not-exist'" -msgstr "" - -#: ../../library/configparser.rst:597 -msgid "*delimiters*, default value: ``('=', ':')``" -msgstr "" - -#: ../../library/configparser.rst:599 -msgid "" -"Delimiters are substrings that delimit keys from values within a section. " -"The first occurrence of a delimiting substring on a line is considered a " -"delimiter. This means values (but not keys) can contain the delimiters." -msgstr "" - -#: ../../library/configparser.rst:603 -msgid "" -"See also the *space_around_delimiters* argument " -"to :meth:`ConfigParser.write`." -msgstr "" - -#: ../../library/configparser.rst:606 -msgid "*comment_prefixes*, default value: ``('#', ';')``" -msgstr "" - -#: ../../library/configparser.rst:608 -msgid "*inline_comment_prefixes*, default value: ``None``" -msgstr "" - -#: ../../library/configparser.rst:610 -msgid "" -"Comment prefixes are strings that indicate the start of a valid comment " -"within a config file. *comment_prefixes* are used only on otherwise empty " -"lines (optionally indented) whereas *inline_comment_prefixes* can be used " -"after every valid value (e.g. section names, options and empty lines as " -"well). By default inline comments are disabled and ``'#'`` and ``';'`` are " -"used as prefixes for whole line comments." -msgstr "" - -#: ../../library/configparser.rst:617 -msgid "" -"In previous versions of :mod:`configparser` behaviour matched " -"``comment_prefixes=('#',';')`` and ``inline_comment_prefixes=(';',)``." -msgstr "" - -#: ../../library/configparser.rst:621 -msgid "" -"Please note that config parsers don't support escaping of comment prefixes " -"so using *inline_comment_prefixes* may prevent users from specifying option " -"values with characters used as comment prefixes. When in doubt, avoid " -"setting *inline_comment_prefixes*. In any circumstances, the only way of " -"storing comment prefix characters at the beginning of a line in multiline " -"values is to interpolate the prefix, for example::" -msgstr "" - -#: ../../library/configparser.rst:628 -msgid "" -">>> from configparser import ConfigParser, ExtendedInterpolation\n" -">>> parser = ConfigParser(interpolation=ExtendedInterpolation())\n" -">>> # the default BasicInterpolation could be used as well\n" -">>> parser.read_string(\"\"\"\n" -"... [DEFAULT]\n" -"... hash = #\n" -"...\n" -"... [hashes]\n" -"... shebang =\n" -"... ${hash}!/usr/bin/env python\n" -"... ${hash} -*- coding: utf-8 -*-\n" -"...\n" -"... extensions =\n" -"... enabled_extension\n" -"... another_extension\n" -"... #disabled_by_comment\n" -"... yet_another_extension\n" -"...\n" -"... interpolation not necessary = if # is not at line start\n" -"... even in multiline values = line #1\n" -"... line #2\n" -"... line #3\n" -"... \"\"\")\n" -">>> print(parser['hashes']['shebang'])\n" -"\n" -"#!/usr/bin/env python\n" -"# -*- coding: utf-8 -*-\n" -">>> print(parser['hashes']['extensions'])\n" -"\n" -"enabled_extension\n" -"another_extension\n" -"yet_another_extension\n" -">>> print(parser['hashes']['interpolation not necessary'])\n" -"if # is not at line start\n" -">>> print(parser['hashes']['even in multiline values'])\n" -"line #1\n" -"line #2\n" -"line #3" -msgstr "" - -#: ../../library/configparser.rst:667 -msgid "*strict*, default value: ``True``" -msgstr "" - -#: ../../library/configparser.rst:669 -msgid "" -"When set to ``True``, the parser will not allow for any section or option " -"duplicates while reading from a single source " -"(using :meth:`~ConfigParser.read_file`, :meth:`~ConfigParser.read_string` " -"or :meth:`~ConfigParser.read_dict`). It is recommended to use strict " -"parsers in new applications." -msgstr "" - -#: ../../library/configparser.rst:674 -msgid "" -"In previous versions of :mod:`configparser` behaviour matched " -"``strict=False``." -msgstr "" - -#: ../../library/configparser.rst:678 -msgid "*empty_lines_in_values*, default value: ``True``" -msgstr "" - -#: ../../library/configparser.rst:680 -msgid "" -"In config parsers, values can span multiple lines as long as they are " -"indented more than the key that holds them. By default parsers also let " -"empty lines to be parts of values. At the same time, keys can be " -"arbitrarily indented themselves to improve readability. In consequence, " -"when configuration files get big and complex, it is easy for the user to " -"lose track of the file structure. Take for instance:" -msgstr "" - -#: ../../library/configparser.rst:687 -msgid "" -"[Section]\n" -"key = multiline\n" -" value with a gotcha\n" -"\n" -" this = is still a part of the multiline value of 'key'" -msgstr "" -"[Section]\n" -"key = multiline\n" -" value with a gotcha\n" -"\n" -" this = is still a part of the multiline value of 'key'" - -#: ../../library/configparser.rst:695 -msgid "" -"This can be especially problematic for the user to see if she's using a " -"proportional font to edit the file. That is why when your application does " -"not need values with empty lines, you should consider disallowing them. " -"This will make empty lines split keys every time. In the example above, it " -"would produce two keys, ``key`` and ``this``." -msgstr "" - -#: ../../library/configparser.rst:701 -msgid "" -"*default_section*, default value: ``configparser.DEFAULTSECT`` (that is: " -"``\"DEFAULT\"``)" -msgstr "" - -#: ../../library/configparser.rst:704 -msgid "" -"The convention of allowing a special section of default values for other " -"sections or interpolation purposes is a powerful concept of this library, " -"letting users create complex declarative configurations. This section is " -"normally called ``\"DEFAULT\"`` but this can be customized to point to any " -"other valid section name. Some typical values include: ``\"general\"`` or " -"``\"common\"``. The name provided is used for recognizing default sections " -"when reading from any source and is used when writing configuration back to " -"a file. Its current value can be retrieved using the " -"``parser_instance.default_section`` attribute and may be modified at runtime " -"(i.e. to convert files from one format to another)." -msgstr "" - -#: ../../library/configparser.rst:715 -msgid "*interpolation*, default value: ``configparser.BasicInterpolation``" -msgstr "" - -#: ../../library/configparser.rst:717 -msgid "" -"Interpolation behaviour may be customized by providing a custom handler " -"through the *interpolation* argument. ``None`` can be used to turn off " -"interpolation completely, ``ExtendedInterpolation()`` provides a more " -"advanced variant inspired by ``zc.buildout``. More on the subject in the " -"`dedicated documentation section <#interpolation-of-" -"values>`_. :class:`RawConfigParser` has a default value of ``None``." -msgstr "" - -#: ../../library/configparser.rst:724 -msgid "*converters*, default value: not set" -msgstr "" - -#: ../../library/configparser.rst:726 -msgid "" -"Config parsers provide option value getters that perform type conversion. " -"By default :meth:`~ConfigParser.getint`, :meth:`~ConfigParser.getfloat`, " -"and :meth:`~ConfigParser.getboolean` are implemented. Should other getters " -"be desirable, users may define them in a subclass or pass a dictionary where " -"each key is a name of the converter and each value is a callable " -"implementing said conversion. For instance, passing ``{'decimal': " -"decimal.Decimal}`` would add :meth:`!getdecimal` on both the parser object " -"and all section proxies. In other words, it will be possible to write both " -"``parser_instance.getdecimal('section', 'key', fallback=0)`` and " -"``parser_instance['section'].getdecimal('key', 0)``." -msgstr "" - -#: ../../library/configparser.rst:737 -msgid "" -"If the converter needs to access the state of the parser, it can be " -"implemented as a method on a config parser subclass. If the name of this " -"method starts with ``get``, it will be available on all section proxies, in " -"the dict-compatible form (see the ``getdecimal()`` example above)." -msgstr "" - -#: ../../library/configparser.rst:742 -msgid "" -"More advanced customization may be achieved by overriding default values of " -"these parser attributes. The defaults are defined on the classes, so they " -"may be overridden by subclasses or by attribute assignment." -msgstr "" - -#: ../../library/configparser.rst:748 -msgid "" -"By default when using :meth:`~ConfigParser.getboolean`, config parsers " -"consider the following values ``True``: ``'1'``, ``'yes'``, ``'true'``, " -"``'on'`` and the following values ``False``: ``'0'``, ``'no'``, ``'false'``, " -"``'off'``. You can override this by specifying a custom dictionary of " -"strings and their Boolean outcomes. For example:" -msgstr "" - -#: ../../library/configparser.rst:754 -msgid "" -">>> custom = configparser.ConfigParser()\n" -">>> custom['section1'] = {'funky': 'nope'}\n" -">>> custom['section1'].getboolean('funky')\n" -"Traceback (most recent call last):\n" -"...\n" -"ValueError: Not a boolean: nope\n" -">>> custom.BOOLEAN_STATES = {'sure': True, 'nope': False}\n" -">>> custom['section1'].getboolean('funky')\n" -"False" -msgstr "" -">>> custom = configparser.ConfigParser()\n" -">>> custom['section1'] = {'funky': 'nope'}\n" -">>> custom['section1'].getboolean('funky')\n" -"Traceback (most recent call last):\n" -"...\n" -"ValueError: Not a boolean: nope\n" -">>> custom.BOOLEAN_STATES = {'sure': True, 'nope': False}\n" -">>> custom['section1'].getboolean('funky')\n" -"False" - -#: ../../library/configparser.rst:766 -msgid "" -"Other typical Boolean pairs include ``accept``/``reject`` or ``enabled``/" -"``disabled``." -msgstr "" - -#: ../../library/configparser.rst:772 -msgid "" -"This method transforms option names on every read, get, or set operation. " -"The default converts the name to lowercase. This also means that when a " -"configuration file gets written, all keys will be lowercase. Override this " -"method if that's unsuitable. For example:" -msgstr "" - -#: ../../library/configparser.rst:778 -msgid "" -">>> config = \"\"\"\n" -"... [Section1]\n" -"... Key = Value\n" -"...\n" -"... [Section2]\n" -"... AnotherKey = Value\n" -"... \"\"\"\n" -">>> typical = configparser.ConfigParser()\n" -">>> typical.read_string(config)\n" -">>> list(typical['Section1'].keys())\n" -"['key']\n" -">>> list(typical['Section2'].keys())\n" -"['anotherkey']\n" -">>> custom = configparser.RawConfigParser()\n" -">>> custom.optionxform = lambda option: option\n" -">>> custom.read_string(config)\n" -">>> list(custom['Section1'].keys())\n" -"['Key']\n" -">>> list(custom['Section2'].keys())\n" -"['AnotherKey']" -msgstr "" -">>> config = \"\"\"\n" -"... [Section1]\n" -"... Key = Value\n" -"...\n" -"... [Section2]\n" -"... AnotherKey = Value\n" -"... \"\"\"\n" -">>> typical = configparser.ConfigParser()\n" -">>> typical.read_string(config)\n" -">>> list(typical['Section1'].keys())\n" -"['key']\n" -">>> list(typical['Section2'].keys())\n" -"['anotherkey']\n" -">>> custom = configparser.RawConfigParser()\n" -">>> custom.optionxform = lambda option: option\n" -">>> custom.read_string(config)\n" -">>> list(custom['Section1'].keys())\n" -"['Key']\n" -">>> list(custom['Section2'].keys())\n" -"['AnotherKey']" - -#: ../../library/configparser.rst:802 -msgid "" -"The optionxform function transforms option names to a canonical form. This " -"should be an idempotent function: if the name is already in canonical form, " -"it should be returned unchanged." -msgstr "" - -#: ../../library/configparser.rst:809 -msgid "" -"A compiled regular expression used to parse section headers. The default " -"matches ``[section]`` to the name ``\"section\"``. Whitespace is considered " -"part of the section name, thus ``[ larch ]`` will be read as a section of " -"name ``\" larch \"``. Override this attribute if that's unsuitable. For " -"example:" -msgstr "" - -#: ../../library/configparser.rst:815 -msgid "" -">>> import re\n" -">>> config = \"\"\"\n" -"... [Section 1]\n" -"... option = value\n" -"...\n" -"... [ Section 2 ]\n" -"... another = val\n" -"... \"\"\"\n" -">>> typical = configparser.ConfigParser()\n" -">>> typical.read_string(config)\n" -">>> typical.sections()\n" -"['Section 1', ' Section 2 ']\n" -">>> custom = configparser.ConfigParser()\n" -">>> custom.SECTCRE = re.compile(r\"\\[ *(?P
[^]]+?) *\\]\")\n" -">>> custom.read_string(config)\n" -">>> custom.sections()\n" -"['Section 1', 'Section 2']" -msgstr "" -">>> import re\n" -">>> config = \"\"\"\n" -"... [Section 1]\n" -"... option = value\n" -"...\n" -"... [ Section 2 ]\n" -"... another = val\n" -"... \"\"\"\n" -">>> typical = configparser.ConfigParser()\n" -">>> typical.read_string(config)\n" -">>> typical.sections()\n" -"['Section 1', ' Section 2 ']\n" -">>> custom = configparser.ConfigParser()\n" -">>> custom.SECTCRE = re.compile(r\"\\[ *(?P
[^]]+?) *\\]\")\n" -">>> custom.read_string(config)\n" -">>> custom.sections()\n" -"['Section 1', 'Section 2']" - -#: ../../library/configparser.rst:837 -msgid "" -"While ConfigParser objects also use an ``OPTCRE`` attribute for recognizing " -"option lines, it's not recommended to override it because that would " -"interfere with constructor options *allow_no_value* and *delimiters*." -msgstr "" - -#: ../../library/configparser.rst:843 -msgid "Legacy API Examples" -msgstr "" - -#: ../../library/configparser.rst:845 -msgid "" -"Mainly because of backwards compatibility concerns, :mod:`configparser` " -"provides also a legacy API with explicit ``get``/``set`` methods. While " -"there are valid use cases for the methods outlined below, mapping protocol " -"access is preferred for new projects. The legacy API is at times more " -"advanced, low-level and downright counterintuitive." -msgstr "" - -#: ../../library/configparser.rst:851 -msgid "An example of writing to a configuration file::" -msgstr "" - -#: ../../library/configparser.rst:853 -msgid "" -"import configparser\n" -"\n" -"config = configparser.RawConfigParser()\n" -"\n" -"# Please note that using RawConfigParser's set functions, you can assign\n" -"# non-string values to keys internally, but will receive an error when\n" -"# attempting to write to a file or when you get it in non-raw mode. Setting\n" -"# values using the mapping protocol or ConfigParser's set() does not allow\n" -"# such assignments to take place.\n" -"config.add_section('Section1')\n" -"config.set('Section1', 'an_int', '15')\n" -"config.set('Section1', 'a_bool', 'true')\n" -"config.set('Section1', 'a_float', '3.1415')\n" -"config.set('Section1', 'baz', 'fun')\n" -"config.set('Section1', 'bar', 'Python')\n" -"config.set('Section1', 'foo', '%(bar)s is %(baz)s!')\n" -"\n" -"# Writing our configuration file to 'example.cfg'\n" -"with open('example.cfg', 'w') as configfile:\n" -" config.write(configfile)" -msgstr "" - -#: ../../library/configparser.rst:874 -msgid "An example of reading the configuration file again::" -msgstr "" - -#: ../../library/configparser.rst:876 -msgid "" -"import configparser\n" -"\n" -"config = configparser.RawConfigParser()\n" -"config.read('example.cfg')\n" -"\n" -"# getfloat() raises an exception if the value is not a float\n" -"# getint() and getboolean() also do this for their respective types\n" -"a_float = config.getfloat('Section1', 'a_float')\n" -"an_int = config.getint('Section1', 'an_int')\n" -"print(a_float + an_int)\n" -"\n" -"# Notice that the next output does not interpolate '%(bar)s' or '%(baz)s'.\n" -"# This is because we are using a RawConfigParser().\n" -"if config.getboolean('Section1', 'a_bool'):\n" -" print(config.get('Section1', 'foo'))" -msgstr "" - -#: ../../library/configparser.rst:892 -msgid "To get interpolation, use :class:`ConfigParser`::" -msgstr "" - -#: ../../library/configparser.rst:894 -msgid "" -"import configparser\n" -"\n" -"cfg = configparser.ConfigParser()\n" -"cfg.read('example.cfg')\n" -"\n" -"# Set the optional *raw* argument of get() to True if you wish to disable\n" -"# interpolation in a single get operation.\n" -"print(cfg.get('Section1', 'foo', raw=False)) # -> \"Python is fun!\"\n" -"print(cfg.get('Section1', 'foo', raw=True)) # -> \"%(bar)s is %(baz)s!\"\n" -"\n" -"# The optional *vars* argument is a dict with members that will take\n" -"# precedence in interpolation.\n" -"print(cfg.get('Section1', 'foo', vars={'bar': 'Documentation',\n" -" 'baz': 'evil'}))\n" -"\n" -"# The optional *fallback* argument can be used to provide a fallback value\n" -"print(cfg.get('Section1', 'foo'))\n" -" # -> \"Python is fun!\"\n" -"\n" -"print(cfg.get('Section1', 'foo', fallback='Monty is not.'))\n" -" # -> \"Python is fun!\"\n" -"\n" -"print(cfg.get('Section1', 'monster', fallback='No such things as " -"monsters.'))\n" -" # -> \"No such things as monsters.\"\n" -"\n" -"# A bare print(cfg.get('Section1', 'monster')) would raise NoOptionError\n" -"# but we can also use:\n" -"\n" -"print(cfg.get('Section1', 'monster', fallback=None))\n" -" # -> None" -msgstr "" - -#: ../../library/configparser.rst:925 -msgid "" -"Default values are available in both types of ConfigParsers. They are used " -"in interpolation if an option used is not defined elsewhere. ::" -msgstr "" - -#: ../../library/configparser.rst:928 -msgid "" -"import configparser\n" -"\n" -"# New instance with 'bar' and 'baz' defaulting to 'Life' and 'hard' each\n" -"config = configparser.ConfigParser({'bar': 'Life', 'baz': 'hard'})\n" -"config.read('example.cfg')\n" -"\n" -"print(config.get('Section1', 'foo')) # -> \"Python is fun!\"\n" -"config.remove_option('Section1', 'bar')\n" -"config.remove_option('Section1', 'baz')\n" -"print(config.get('Section1', 'foo')) # -> \"Life is hard!\"" -msgstr "" - -#: ../../library/configparser.rst:943 -msgid "ConfigParser Objects" -msgstr "ConfigParser 物件" - -#: ../../library/configparser.rst:953 -msgid "" -"The main configuration parser. When *defaults* is given, it is initialized " -"into the dictionary of intrinsic defaults. When *dict_type* is given, it " -"will be used to create the dictionary objects for the list of sections, for " -"the options within a section, and for the default values." -msgstr "" - -#: ../../library/configparser.rst:958 -msgid "" -"When *delimiters* is given, it is used as the set of substrings that divide " -"keys from values. When *comment_prefixes* is given, it will be used as the " -"set of substrings that prefix comments in otherwise empty lines. Comments " -"can be indented. When *inline_comment_prefixes* is given, it will be used " -"as the set of substrings that prefix comments in non-empty lines." -msgstr "" - -#: ../../library/configparser.rst:964 -msgid "" -"When *strict* is ``True`` (the default), the parser won't allow for any " -"section or option duplicates while reading from a single source (file, " -"string or dictionary), raising :exc:`DuplicateSectionError` " -"or :exc:`DuplicateOptionError`. When *empty_lines_in_values* is ``False`` " -"(default: ``True``), each empty line marks the end of an option. Otherwise, " -"internal empty lines of a multiline option are kept as part of the value. " -"When *allow_no_value* is ``True`` (default: ``False``), options without " -"values are accepted; the value held for these is ``None`` and they are " -"serialized without the trailing delimiter." -msgstr "" - -#: ../../library/configparser.rst:974 -msgid "" -"When *default_section* is given, it specifies the name for the special " -"section holding default values for other sections and interpolation purposes " -"(normally named ``\"DEFAULT\"``). This value can be retrieved and changed " -"at runtime using the ``default_section`` instance attribute. This won't re-" -"evaluate an already parsed config file, but will be used when writing parsed " -"settings to a new config file." -msgstr "" - -#: ../../library/configparser.rst:981 -msgid "" -"Interpolation behaviour may be customized by providing a custom handler " -"through the *interpolation* argument. ``None`` can be used to turn off " -"interpolation completely, ``ExtendedInterpolation()`` provides a more " -"advanced variant inspired by ``zc.buildout``. More on the subject in the " -"`dedicated documentation section <#interpolation-of-values>`_." -msgstr "" - -#: ../../library/configparser.rst:987 -msgid "" -"All option names used in interpolation will be passed through " -"the :meth:`optionxform` method just like any other option name reference. " -"For example, using the default implementation of :meth:`optionxform` (which " -"converts option names to lower case), the values ``foo %(bar)s`` and ``foo %" -"(BAR)s`` are equivalent." -msgstr "" - -#: ../../library/configparser.rst:993 -msgid "" -"When *converters* is given, it should be a dictionary where each key " -"represents the name of a type converter and each value is a callable " -"implementing the conversion from string to the desired datatype. Every " -"converter gets its own corresponding :meth:`!get*` method on the parser " -"object and section proxies." -msgstr "" - -#: ../../library/configparser.rst:999 -msgid "" -"When *allow_unnamed_section* is ``True`` (default: ``False``), the first " -"section name can be omitted. See the `\"Unnamed Sections\" section <#unnamed-" -"sections>`_." -msgstr "" - -#: ../../library/configparser.rst:1028 -msgid "The default *dict_type* is :class:`collections.OrderedDict`." -msgstr "預設的 *dict_type* 是 :class:`collections.OrderedDict`。" - -#: ../../library/configparser.rst:1031 ../../library/configparser.rst:1324 -msgid "" -"*allow_no_value*, *delimiters*, *comment_prefixes*, *strict*, " -"*empty_lines_in_values*, *default_section* and *interpolation* were added." -msgstr "" - -#: ../../library/configparser.rst:1036 ../../library/configparser.rst:1329 -msgid "The *converters* argument was added." -msgstr "新增 *converters* 引數。" - -#: ../../library/configparser.rst:1039 -msgid "" -"The *defaults* argument is read with :meth:`read_dict`, providing consistent " -"behavior across the parser: non-string keys and values are implicitly " -"converted to strings." -msgstr "" - -#: ../../library/configparser.rst:1044 ../../library/configparser.rst:1332 -msgid "" -"The default *dict_type* is :class:`dict`, since it now preserves insertion " -"order." -msgstr "" - -#: ../../library/configparser.rst:1048 -msgid "" -"Raise a :exc:`MultilineContinuationError` when *allow_no_value* is ``True``, " -"and a key without a value is continued with an indented line." -msgstr "" - -#: ../../library/configparser.rst:1052 ../../library/configparser.rst:1336 -msgid "The *allow_unnamed_section* argument was added." -msgstr "新增 *allow_unnamed_section* 引數。" - -#: ../../library/configparser.rst:1057 -msgid "Return a dictionary containing the instance-wide defaults." -msgstr "回傳包含整個實例預設值的字典。" - -#: ../../library/configparser.rst:1062 -msgid "" -"Return a list of the sections available; the *default section* is not " -"included in the list." -msgstr "" - -#: ../../library/configparser.rst:1068 -msgid "" -"Add a section named *section* to the instance. If a section by the given " -"name already exists, :exc:`DuplicateSectionError` is raised. If the " -"*default section* name is passed, :exc:`ValueError` is raised. The name of " -"the section must be a string; if not, :exc:`TypeError` is raised." -msgstr "" - -#: ../../library/configparser.rst:1073 -msgid "Non-string section names raise :exc:`TypeError`." -msgstr "" - -#: ../../library/configparser.rst:1079 -msgid "" -"Indicates whether the named *section* is present in the configuration. The " -"*default section* is not acknowledged." -msgstr "" - -#: ../../library/configparser.rst:1085 -msgid "Return a list of options available in the specified *section*." -msgstr "" - -#: ../../library/configparser.rst:1090 -msgid "" -"If the given *section* exists, and contains the given *option*, " -"return :const:`True`; otherwise return :const:`False`. If the specified " -"*section* is :const:`None` or an empty string, DEFAULT is assumed." -msgstr "" - -#: ../../library/configparser.rst:1097 -msgid "" -"Attempt to read and parse an iterable of filenames, returning a list of " -"filenames which were successfully parsed." -msgstr "" - -#: ../../library/configparser.rst:1100 -msgid "" -"If *filenames* is a string, a :class:`bytes` object or a :term:`path-like " -"object`, it is treated as a single filename. If a file named in *filenames* " -"cannot be opened, that file will be ignored. This is designed so that you " -"can specify an iterable of potential configuration file locations (for " -"example, the current directory, the user's home directory, and some system-" -"wide directory), and all existing configuration files in the iterable will " -"be read." -msgstr "" - -#: ../../library/configparser.rst:1109 -msgid "" -"If none of the named files exist, the :class:`ConfigParser` instance will " -"contain an empty dataset. An application which requires initial values to " -"be loaded from a file should load the required file or files " -"using :meth:`read_file` before calling :meth:`read` for any optional files::" -msgstr "" - -#: ../../library/configparser.rst:1115 -msgid "" -"import configparser, os\n" -"\n" -"config = configparser.ConfigParser()\n" -"config.read_file(open('defaults.cfg'))\n" -"config.read(['site.cfg', os.path.expanduser('~/.myapp.cfg')],\n" -" encoding='cp1250')" -msgstr "" -"import configparser, os\n" -"\n" -"config = configparser.ConfigParser()\n" -"config.read_file(open('defaults.cfg'))\n" -"config.read(['site.cfg', os.path.expanduser('~/.myapp.cfg')],\n" -" encoding='cp1250')" - -#: ../../library/configparser.rst:1122 -msgid "" -"Added the *encoding* parameter. Previously, all files were read using the " -"default encoding for :func:`open`." -msgstr "" - -#: ../../library/configparser.rst:1126 -msgid "The *filenames* parameter accepts a :term:`path-like object`." -msgstr "" - -#: ../../library/configparser.rst:1129 -msgid "The *filenames* parameter accepts a :class:`bytes` object." -msgstr "" - -#: ../../library/configparser.rst:1135 -msgid "" -"Read and parse configuration data from *f* which must be an iterable " -"yielding Unicode strings (for example files opened in text mode)." -msgstr "" - -#: ../../library/configparser.rst:1138 -msgid "" -"Optional argument *source* specifies the name of the file being read. If " -"not given and *f* has a :attr:`!name` attribute, that is used for *source*; " -"the default is ``''``." -msgstr "" - -#: ../../library/configparser.rst:1142 -msgid "Replaces :meth:`!readfp`." -msgstr "取代 :meth:`!readfp`。" - -#: ../../library/configparser.rst:1147 -msgid "Parse configuration data from a string." -msgstr "" - -#: ../../library/configparser.rst:1149 -msgid "" -"Optional argument *source* specifies a context-specific name of the string " -"passed. If not given, ``''`` is used. This should commonly be a " -"filesystem path or a URL." -msgstr "" - -#: ../../library/configparser.rst:1158 -msgid "" -"Load configuration from any object that provides a dict-like ``items()`` " -"method. Keys are section names, values are dictionaries with keys and " -"values that should be present in the section. If the used dictionary type " -"preserves order, sections and their keys will be added in order. Values are " -"automatically converted to strings." -msgstr "" - -#: ../../library/configparser.rst:1164 -msgid "" -"Optional argument *source* specifies a context-specific name of the " -"dictionary passed. If not given, ```` is used." -msgstr "" - -#: ../../library/configparser.rst:1167 -msgid "This method can be used to copy state between parsers." -msgstr "" - -#: ../../library/configparser.rst:1174 -msgid "" -"Get an *option* value for the named *section*. If *vars* is provided, it " -"must be a dictionary. The *option* is looked up in *vars* (if provided), " -"*section*, and in *DEFAULTSECT* in that order. If the key is not found and " -"*fallback* is provided, it is used as a fallback value. ``None`` can be " -"provided as a *fallback* value." -msgstr "" - -#: ../../library/configparser.rst:1180 -msgid "" -"All the ``'%'`` interpolations are expanded in the return values, unless the " -"*raw* argument is true. Values for interpolation keys are looked up in the " -"same manner as the option." -msgstr "" - -#: ../../library/configparser.rst:1184 -msgid "" -"Arguments *raw*, *vars* and *fallback* are keyword only to protect users " -"from trying to use the third argument as the *fallback* fallback (especially " -"when using the mapping protocol)." -msgstr "" - -#: ../../library/configparser.rst:1192 -msgid "" -"A convenience method which coerces the *option* in the specified *section* " -"to an integer. See :meth:`get` for explanation of *raw*, *vars* and " -"*fallback*." -msgstr "" - -#: ../../library/configparser.rst:1199 -msgid "" -"A convenience method which coerces the *option* in the specified *section* " -"to a floating-point number. See :meth:`get` for explanation of *raw*, " -"*vars* and *fallback*." -msgstr "" - -#: ../../library/configparser.rst:1206 -msgid "" -"A convenience method which coerces the *option* in the specified *section* " -"to a Boolean value. Note that the accepted values for the option are " -"``'1'``, ``'yes'``, ``'true'``, and ``'on'``, which cause this method to " -"return ``True``, and ``'0'``, ``'no'``, ``'false'``, and ``'off'``, which " -"cause it to return ``False``. These string values are checked in a case-" -"insensitive manner. Any other value will cause it to " -"raise :exc:`ValueError`. See :meth:`get` for explanation of *raw*, *vars* " -"and *fallback*." -msgstr "" - -#: ../../library/configparser.rst:1219 -msgid "" -"When *section* is not given, return a list of *section_name*, " -"*section_proxy* pairs, including DEFAULTSECT." -msgstr "" - -#: ../../library/configparser.rst:1222 -msgid "" -"Otherwise, return a list of *name*, *value* pairs for the options in the " -"given *section*. Optional arguments have the same meaning as for " -"the :meth:`get` method." -msgstr "" - -#: ../../library/configparser.rst:1226 -msgid "" -"Items present in *vars* no longer appear in the result. The previous " -"behaviour mixed actual parser options with variables provided for " -"interpolation." -msgstr "" - -#: ../../library/configparser.rst:1234 -msgid "" -"If the given section exists, set the given option to the specified value; " -"otherwise raise :exc:`NoSectionError`. *option* and *value* must be " -"strings; if not, :exc:`TypeError` is raised." -msgstr "" - -#: ../../library/configparser.rst:1241 -msgid "" -"Write a representation of the configuration to the specified :term:`file " -"object`, which must be opened in text mode (accepting strings). This " -"representation can be parsed by a future :meth:`read` call. If " -"*space_around_delimiters* is true, delimiters between keys and values are " -"surrounded by spaces." -msgstr "" - -#: ../../library/configparser.rst:1247 -msgid "" -"Raises InvalidWriteError if this would write a representation which cannot " -"be accurately parsed by a future :meth:`read` call from this parser." -msgstr "" - -#: ../../library/configparser.rst:1253 -msgid "" -"Comments in the original configuration file are not preserved when writing " -"the configuration back. What is considered a comment, depends on the given " -"values for *comment_prefix* and *inline_comment_prefix*." -msgstr "" - -#: ../../library/configparser.rst:1261 -msgid "" -"Remove the specified *option* from the specified *section*. If the section " -"does not exist, raise :exc:`NoSectionError`. If the option existed to be " -"removed, return :const:`True`; otherwise return :const:`False`." -msgstr "" - -#: ../../library/configparser.rst:1269 -msgid "" -"Remove the specified *section* from the configuration. If the section in " -"fact existed, return ``True``. Otherwise return ``False``." -msgstr "" - -#: ../../library/configparser.rst:1275 -msgid "" -"Transforms the option name *option* as found in an input file or as passed " -"in by client code to the form that should be used in the internal " -"structures. The default implementation returns a lower-case version of " -"*option*; subclasses may override this or client code can set an attribute " -"of this name on instances to affect this behavior." -msgstr "" - -#: ../../library/configparser.rst:1281 -msgid "" -"You don't need to subclass the parser to use this method, you can also set " -"it on an instance, to a function that takes a string argument and returns a " -"string. Setting it to ``str``, for example, would make option names case " -"sensitive::" -msgstr "" - -#: ../../library/configparser.rst:1286 -msgid "" -"cfgparser = ConfigParser()\n" -"cfgparser.optionxform = str" -msgstr "" -"cfgparser = ConfigParser()\n" -"cfgparser.optionxform = str" - -#: ../../library/configparser.rst:1289 -msgid "" -"Note that when reading configuration files, whitespace around the option " -"names is stripped before :meth:`optionxform` is called." -msgstr "" - -#: ../../library/configparser.rst:1295 -msgid "" -"A special object representing a section name used to reference the unnamed " -"section (see :ref:`unnamed-sections`)." -msgstr "" - -#: ../../library/configparser.rst:1300 -msgid "" -"The maximum depth for recursive interpolation " -"for :meth:`~configparser.ConfigParser.get` when the *raw* parameter is " -"false. This is relevant only when the default *interpolation* is used." -msgstr "" - -#: ../../library/configparser.rst:1308 -msgid "RawConfigParser Objects" -msgstr "RawConfigParser 物件" - -#: ../../library/configparser.rst:1319 -msgid "" -"Legacy variant of the :class:`ConfigParser`. It has interpolation disabled " -"by default and allows for non-string section names, option names, and values " -"via its unsafe ``add_section`` and ``set`` methods, as well as the legacy " -"``defaults=`` keyword argument handling." -msgstr "" - -#: ../../library/configparser.rst:1340 -msgid "" -"Consider using :class:`ConfigParser` instead which checks types of the " -"values to be stored internally. If you don't want interpolation, you can " -"use ``ConfigParser(interpolation=None)``." -msgstr "" - -#: ../../library/configparser.rst:1347 -msgid "" -"Add a section named *section* or :const:`UNNAMED_SECTION` to the instance." -msgstr "" - -#: ../../library/configparser.rst:1349 -msgid "" -"If the given section already exists, :exc:`DuplicateSectionError` is raised. " -"If the *default section* name is passed, :exc:`ValueError` is raised. " -"If :const:`UNNAMED_SECTION` is passed and support is " -"disabled, :exc:`UnnamedSectionDisabledError` is raised." -msgstr "" - -#: ../../library/configparser.rst:1354 -msgid "" -"Type of *section* is not checked which lets users create non-string named " -"sections. This behaviour is unsupported and may cause internal errors." -msgstr "" - -#: ../../library/configparser.rst:1357 -msgid "Added support for :const:`UNNAMED_SECTION`." -msgstr "新增對 :const:`UNNAMED_SECTION` 的支援。" - -#: ../../library/configparser.rst:1363 -msgid "" -"If the given section exists, set the given option to the specified value; " -"otherwise raise :exc:`NoSectionError`. While it is possible to " -"use :class:`RawConfigParser` (or :class:`ConfigParser` with *raw* parameters " -"set to true) for *internal* storage of non-string values, full functionality " -"(including interpolation and output to files) can only be achieved using " -"string values." -msgstr "" - -#: ../../library/configparser.rst:1370 -msgid "" -"This method lets users assign non-string values to keys internally. This " -"behaviour is unsupported and will cause errors when attempting to write to a " -"file or get it in non-raw mode. **Use the mapping protocol API** which does " -"not allow such assignments to take place." -msgstr "" - -#: ../../library/configparser.rst:1377 -msgid "Exceptions" -msgstr "例外" - -#: ../../library/configparser.rst:1381 -msgid "Base class for all other :mod:`configparser` exceptions." -msgstr "" - -#: ../../library/configparser.rst:1386 -msgid "Exception raised when a specified section is not found." -msgstr "" - -#: ../../library/configparser.rst:1391 -msgid "" -"Exception raised if :meth:`~ConfigParser.add_section` is called with the " -"name of a section that is already present or in strict parsers when a " -"section if found more than once in a single input file, string or dictionary." -msgstr "" - -#: ../../library/configparser.rst:1395 -msgid "" -"Added the optional *source* and *lineno* attributes and parameters " -"to :meth:`!__init__`." -msgstr "" - -#: ../../library/configparser.rst:1402 -msgid "" -"Exception raised by strict parsers if a single option appears twice during " -"reading from a single file, string or dictionary. This catches misspellings " -"and case sensitivity-related errors, e.g. a dictionary may have two keys " -"representing the same case-insensitive configuration key." -msgstr "" - -#: ../../library/configparser.rst:1410 -msgid "" -"Exception raised when a specified option is not found in the specified " -"section." -msgstr "" - -#: ../../library/configparser.rst:1416 -msgid "" -"Base class for exceptions raised when problems occur performing string " -"interpolation." -msgstr "" - -#: ../../library/configparser.rst:1422 -msgid "" -"Exception raised when string interpolation cannot be completed because the " -"number of iterations exceeds :const:`MAX_INTERPOLATION_DEPTH`. Subclass " -"of :exc:`InterpolationError`." -msgstr "" - -#: ../../library/configparser.rst:1429 -msgid "" -"Exception raised when an option referenced from a value does not exist. " -"Subclass of :exc:`InterpolationError`." -msgstr "" - -#: ../../library/configparser.rst:1435 -msgid "" -"Exception raised when the source text into which substitutions are made does " -"not conform to the required syntax. Subclass of :exc:`InterpolationError`." -msgstr "" - -#: ../../library/configparser.rst:1441 -msgid "" -"Exception raised when attempting to parse a file which has no section " -"headers." -msgstr "" - -#: ../../library/configparser.rst:1446 -msgid "Exception raised when errors occur attempting to parse a file." -msgstr "" - -#: ../../library/configparser.rst:1448 -msgid "" -"The ``filename`` attribute and :meth:`!__init__` constructor argument were " -"removed. They have been available using the name ``source`` since 3.2." -msgstr "" - -#: ../../library/configparser.rst:1454 -msgid "" -"Exception raised when a key without a corresponding value is continued with " -"an indented line." -msgstr "" - -#: ../../library/configparser.rst:1461 -msgid "" -"Exception raised when attempting to use the :const:`UNNAMED_SECTION` without " -"enabling it." -msgstr "" - -#: ../../library/configparser.rst:1468 -msgid "" -"Exception raised when an attempted :meth:`ConfigParser.write` would not be " -"parsed accurately with a future :meth:`ConfigParser.read` call." -msgstr "" - -#: ../../library/configparser.rst:1471 -msgid "" -"Ex: Writing a key beginning with the :attr:`ConfigParser.SECTCRE` pattern " -"would parse as a section header when read. Attempting to write this will " -"raise this exception." -msgstr "" - -#: ../../library/configparser.rst:1478 -msgid "Footnotes" -msgstr "註腳" - -#: ../../library/configparser.rst:1479 -msgid "" -"Config parsers allow for heavy customization. If you are interested in " -"changing the behaviour outlined by the footnote reference, consult the " -"`Customizing Parser Behaviour`_ section." -msgstr "" - -#: ../../library/configparser.rst:16 -msgid ".ini" -msgstr ".ini" - -#: ../../library/configparser.rst:16 -msgid "file" -msgstr "file（檔案）" - -#: ../../library/configparser.rst:16 -msgid "configuration" -msgstr "configuration（設定）" - -#: ../../library/configparser.rst:16 -msgid "ini file" -msgstr "ini file（ini 檔案）" - -#: ../../library/configparser.rst:16 -msgid "Windows ini file" -msgstr "Windows ini file（Windows ini 檔案）" - -#: ../../library/configparser.rst:367 -msgid "% (percent)" -msgstr "% （百分號）" - -#: ../../library/configparser.rst:367 ../../library/configparser.rst:400 -msgid "interpolation in configuration files" -msgstr "interpolation in configuration files（設定檔中的插值）" - -#: ../../library/configparser.rst:400 -msgid "$ (dollar)" -msgstr "$ （金錢符號）" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: 2018-05-23 14:41+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/configparser.rst:2 +msgid ":mod:`!configparser` --- Configuration file parser" +msgstr ":mod:`!configparser` --- 設定檔剖析器" + +#: ../../library/configparser.rst:14 +msgid "**Source code:** :source:`Lib/configparser.py`" +msgstr "**原始碼：**\\ :source:`Lib/configparser.py`" + +#: ../../library/configparser.rst:24 +msgid "" +"This module provides the :class:`ConfigParser` class which implements a " +"basic configuration language which provides a structure similar to what's " +"found in Microsoft Windows INI files. You can use this to write Python " +"programs which can be customized by end users easily." +msgstr "" + +#: ../../library/configparser.rst:31 +msgid "" +"This library does *not* interpret or write the value-type prefixes used in " +"the Windows Registry extended version of INI syntax." +msgstr "" + +#: ../../library/configparser.rst:36 +msgid "Module :mod:`tomllib`" +msgstr ":mod:`tomllib` 模組" + +#: ../../library/configparser.rst:37 +msgid "" +"TOML is a well-specified format for application configuration files. It is " +"specifically designed to be an improved version of INI." +msgstr "" + +#: ../../library/configparser.rst:40 +msgid "Module :mod:`shlex`" +msgstr ":mod:`shlex` 模組" + +#: ../../library/configparser.rst:41 +msgid "" +"Support for creating Unix shell-like mini-languages which can also be used " +"for application configuration files." +msgstr "" + +#: ../../library/configparser.rst:44 +msgid "Module :mod:`json`" +msgstr ":mod:`json` 模組" + +#: ../../library/configparser.rst:45 +msgid "" +"The ``json`` module implements a subset of JavaScript syntax which is " +"sometimes used for configuration, but does not support comments." +msgstr "" + +#: ../../library/configparser.rst:61 +msgid "Quick Start" +msgstr "" + +#: ../../library/configparser.rst:63 +msgid "Let's take a very basic configuration file that looks like this:" +msgstr "" + +#: ../../library/configparser.rst:65 +msgid "" +"[DEFAULT]\n" +"ServerAliveInterval = 45\n" +"Compression = yes\n" +"CompressionLevel = 9\n" +"ForwardX11 = yes\n" +"\n" +"[forge.example]\n" +"User = hg\n" +"\n" +"[topsecret.server.example]\n" +"Port = 50022\n" +"ForwardX11 = no" +msgstr "" +"[DEFAULT]\n" +"ServerAliveInterval = 45\n" +"Compression = yes\n" +"CompressionLevel = 9\n" +"ForwardX11 = yes\n" +"\n" +"[forge.example]\n" +"User = hg\n" +"\n" +"[topsecret.server.example]\n" +"Port = 50022\n" +"ForwardX11 = no" + +#: ../../library/configparser.rst:80 +msgid "" +"The structure of INI files is described `in the following section " +"<#supported-ini-file-structure>`_. Essentially, the file consists of " +"sections, each of which contains keys with values. :mod:`configparser` " +"classes can read and write such files. Let's start by creating the above " +"configuration file programmatically." +msgstr "" + +#: ../../library/configparser.rst:86 +msgid "" +">>> import configparser\n" +">>> config = configparser.ConfigParser()\n" +">>> config['DEFAULT'] = {'ServerAliveInterval': '45',\n" +"... 'Compression': 'yes',\n" +"... 'CompressionLevel': '9'}\n" +">>> config['forge.example'] = {}\n" +">>> config['forge.example']['User'] = 'hg'\n" +">>> config['topsecret.server.example'] = {}\n" +">>> topsecret = config['topsecret.server.example']\n" +">>> topsecret['Port'] = '50022' # mutates the parser\n" +">>> topsecret['ForwardX11'] = 'no' # same here\n" +">>> config['DEFAULT']['ForwardX11'] = 'yes'\n" +">>> with open('example.ini', 'w') as configfile:\n" +"... config.write(configfile)\n" +"..." +msgstr "" +">>> import configparser\n" +">>> config = configparser.ConfigParser()\n" +">>> config['DEFAULT'] = {'ServerAliveInterval': '45',\n" +"... 'Compression': 'yes',\n" +"... 'CompressionLevel': '9'}\n" +">>> config['forge.example'] = {}\n" +">>> config['forge.example']['User'] = 'hg'\n" +">>> config['topsecret.server.example'] = {}\n" +">>> topsecret = config['topsecret.server.example']\n" +">>> topsecret['Port'] = '50022' # mutates the parser\n" +">>> topsecret['ForwardX11'] = 'no' # same here\n" +">>> config['DEFAULT']['ForwardX11'] = 'yes'\n" +">>> with open('example.ini', 'w') as configfile:\n" +"... config.write(configfile)\n" +"..." + +#: ../../library/configparser.rst:104 +msgid "" +"As you can see, we can treat a config parser much like a dictionary. There " +"are differences, `outlined later <#mapping-protocol-access>`_, but the " +"behavior is very close to what you would expect from a dictionary." +msgstr "" + +#: ../../library/configparser.rst:108 +msgid "" +"Now that we have created and saved a configuration file, let's read it back " +"and explore the data it holds." +msgstr "" + +#: ../../library/configparser.rst:111 +msgid "" +">>> config = configparser.ConfigParser()\n" +">>> config.sections()\n" +"[]\n" +">>> config.read('example.ini')\n" +"['example.ini']\n" +">>> config.sections()\n" +"['forge.example', 'topsecret.server.example']\n" +">>> 'forge.example' in config\n" +"True\n" +">>> 'python.org' in config\n" +"False\n" +">>> config['forge.example']['User']\n" +"'hg'\n" +">>> config['DEFAULT']['Compression']\n" +"'yes'\n" +">>> topsecret = config['topsecret.server.example']\n" +">>> topsecret['ForwardX11']\n" +"'no'\n" +">>> topsecret['Port']\n" +"'50022'\n" +">>> for key in config['forge.example']:\n" +"... print(key)\n" +"user\n" +"compressionlevel\n" +"serveraliveinterval\n" +"compression\n" +"forwardx11\n" +">>> config['forge.example']['ForwardX11']\n" +"'yes'" +msgstr "" +">>> config = configparser.ConfigParser()\n" +">>> config.sections()\n" +"[]\n" +">>> config.read('example.ini')\n" +"['example.ini']\n" +">>> config.sections()\n" +"['forge.example', 'topsecret.server.example']\n" +">>> 'forge.example' in config\n" +"True\n" +">>> 'python.org' in config\n" +"False\n" +">>> config['forge.example']['User']\n" +"'hg'\n" +">>> config['DEFAULT']['Compression']\n" +"'yes'\n" +">>> topsecret = config['topsecret.server.example']\n" +">>> topsecret['ForwardX11']\n" +"'no'\n" +">>> topsecret['Port']\n" +"'50022'\n" +">>> for key in config['forge.example']:\n" +"... print(key)\n" +"user\n" +"compressionlevel\n" +"serveraliveinterval\n" +"compression\n" +"forwardx11\n" +">>> config['forge.example']['ForwardX11']\n" +"'yes'" + +#: ../../library/configparser.rst:143 +msgid "" +"As we can see above, the API is pretty straightforward. The only bit of " +"magic involves the ``DEFAULT`` section which provides default values for all " +"other sections [1]_. Note also that keys in sections are case-insensitive " +"and stored in lowercase [1]_." +msgstr "" + +#: ../../library/configparser.rst:148 ../../library/configparser.rst:1003 +msgid "" +"It is possible to read several configurations into a " +"single :class:`ConfigParser`, where the most recently added configuration " +"has the highest priority. Any conflicting keys are taken from the more " +"recent configuration while the previously existing keys are retained. The " +"example below reads in an ``override.ini`` file, which will override any " +"conflicting keys from the ``example.ini`` file." +msgstr "" + +#: ../../library/configparser.rst:155 ../../library/configparser.rst:1010 +msgid "" +"[DEFAULT]\n" +"ServerAliveInterval = -1" +msgstr "" +"[DEFAULT]\n" +"ServerAliveInterval = -1" + +#: ../../library/configparser.rst:160 ../../library/configparser.rst:1015 +msgid "" +">>> config_override = configparser.ConfigParser()\n" +">>> config_override['DEFAULT'] = {'ServerAliveInterval': '-1'}\n" +">>> with open('override.ini', 'w') as configfile:\n" +"... config_override.write(configfile)\n" +"...\n" +">>> config_override = configparser.ConfigParser()\n" +">>> config_override.read(['example.ini', 'override.ini'])\n" +"['example.ini', 'override.ini']\n" +">>> print(config_override.get('DEFAULT', 'ServerAliveInterval'))\n" +"-1" +msgstr "" +">>> config_override = configparser.ConfigParser()\n" +">>> config_override['DEFAULT'] = {'ServerAliveInterval': '-1'}\n" +">>> with open('override.ini', 'w') as configfile:\n" +"... config_override.write(configfile)\n" +"...\n" +">>> config_override = configparser.ConfigParser()\n" +">>> config_override.read(['example.ini', 'override.ini'])\n" +"['example.ini', 'override.ini']\n" +">>> print(config_override.get('DEFAULT', 'ServerAliveInterval'))\n" +"-1" + +#: ../../library/configparser.rst:174 +msgid "" +"This behaviour is equivalent to a :meth:`ConfigParser.read` call with " +"several files passed to the *filenames* parameter." +msgstr "" + +#: ../../library/configparser.rst:179 +msgid "Supported Datatypes" +msgstr "" + +#: ../../library/configparser.rst:181 +msgid "" +"Config parsers do not guess datatypes of values in configuration files, " +"always storing them internally as strings. This means that if you need " +"other datatypes, you should convert on your own:" +msgstr "" + +#: ../../library/configparser.rst:185 +msgid "" +">>> int(topsecret['Port'])\n" +"50022\n" +">>> float(topsecret['CompressionLevel'])\n" +"9.0" +msgstr "" +">>> int(topsecret['Port'])\n" +"50022\n" +">>> float(topsecret['CompressionLevel'])\n" +"9.0" + +#: ../../library/configparser.rst:192 +msgid "" +"Since this task is so common, config parsers provide a range of handy getter " +"methods to handle integers, floats and booleans. The last one is the most " +"interesting because simply passing the value to ``bool()`` would do no good " +"since ``bool('False')`` is still ``True``. This is why config parsers also " +"provide :meth:`~ConfigParser.getboolean`. This method is case-insensitive " +"and recognizes Boolean values from ``'yes'``/``'no'``, ``'on'``/``'off'``, " +"``'true'``/``'false'`` and ``'1'``/``'0'`` [1]_. For example:" +msgstr "" + +#: ../../library/configparser.rst:200 +msgid "" +">>> topsecret.getboolean('ForwardX11')\n" +"False\n" +">>> config['forge.example'].getboolean('ForwardX11')\n" +"True\n" +">>> config.getboolean('forge.example', 'Compression')\n" +"True" +msgstr "" +">>> topsecret.getboolean('ForwardX11')\n" +"False\n" +">>> config['forge.example'].getboolean('ForwardX11')\n" +"True\n" +">>> config.getboolean('forge.example', 'Compression')\n" +"True" + +#: ../../library/configparser.rst:209 +msgid "" +"Apart from :meth:`~ConfigParser.getboolean`, config parsers also provide " +"equivalent :meth:`~ConfigParser.getint` and :meth:`~ConfigParser.getfloat` " +"methods. You can register your own converters and customize the provided " +"ones. [1]_" +msgstr "" + +#: ../../library/configparser.rst:215 +msgid "Fallback Values" +msgstr "" + +#: ../../library/configparser.rst:217 +msgid "" +"As with a dictionary, you can use a section's :meth:`~ConfigParser.get` " +"method to provide fallback values:" +msgstr "" + +#: ../../library/configparser.rst:220 +msgid "" +">>> topsecret.get('Port')\n" +"'50022'\n" +">>> topsecret.get('CompressionLevel')\n" +"'9'\n" +">>> topsecret.get('Cipher')\n" +">>> topsecret.get('Cipher', '3des-cbc')\n" +"'3des-cbc'" +msgstr "" +">>> topsecret.get('Port')\n" +"'50022'\n" +">>> topsecret.get('CompressionLevel')\n" +"'9'\n" +">>> topsecret.get('Cipher')\n" +">>> topsecret.get('Cipher', '3des-cbc')\n" +"'3des-cbc'" + +#: ../../library/configparser.rst:230 +msgid "" +"Please note that default values have precedence over fallback values. For " +"instance, in our example the ``'CompressionLevel'`` key was specified only " +"in the ``'DEFAULT'`` section. If we try to get it from the section " +"``'topsecret.server.example'``, we will always get the default, even if we " +"specify a fallback:" +msgstr "" + +#: ../../library/configparser.rst:236 +msgid "" +">>> topsecret.get('CompressionLevel', '3')\n" +"'9'" +msgstr "" +">>> topsecret.get('CompressionLevel', '3')\n" +"'9'" + +#: ../../library/configparser.rst:241 +msgid "" +"One more thing to be aware of is that the parser-" +"level :meth:`~ConfigParser.get` method provides a custom, more complex " +"interface, maintained for backwards compatibility. When using this method, " +"a fallback value can be provided via the ``fallback`` keyword-only argument:" +msgstr "" + +#: ../../library/configparser.rst:246 +msgid "" +">>> config.get('forge.example', 'monster',\n" +"... fallback='No such things as monsters')\n" +"'No such things as monsters'" +msgstr "" +">>> config.get('forge.example', 'monster',\n" +"... fallback='No such things as monsters')\n" +"'No such things as monsters'" + +#: ../../library/configparser.rst:252 +msgid "" +"The same ``fallback`` argument can be used with " +"the :meth:`~ConfigParser.getint`, :meth:`~ConfigParser.getfloat` " +"and :meth:`~ConfigParser.getboolean` methods, for example:" +msgstr "" + +#: ../../library/configparser.rst:256 +msgid "" +">>> 'BatchMode' in topsecret\n" +"False\n" +">>> topsecret.getboolean('BatchMode', fallback=True)\n" +"True\n" +">>> config['DEFAULT']['BatchMode'] = 'no'\n" +">>> topsecret.getboolean('BatchMode', fallback=True)\n" +"False" +msgstr "" +">>> 'BatchMode' in topsecret\n" +"False\n" +">>> topsecret.getboolean('BatchMode', fallback=True)\n" +"True\n" +">>> config['DEFAULT']['BatchMode'] = 'no'\n" +">>> topsecret.getboolean('BatchMode', fallback=True)\n" +"False" + +#: ../../library/configparser.rst:268 +msgid "Supported INI File Structure" +msgstr "支援的 INI 檔案結構" + +#: ../../library/configparser.rst:270 +msgid "" +"A configuration file consists of sections, each led by a ``[section]`` " +"header, followed by key/value entries separated by a specific string (``=`` " +"or ``:`` by default [1]_). By default, section names are case sensitive but " +"keys are not [1]_. Leading and trailing whitespace is removed from keys and " +"values. Values can be omitted if the parser is configured to allow it [1]_, " +"in which case the key/value delimiter may also be left out. Values can also " +"span multiple lines, as long as they are indented deeper than the first line " +"of the value. Depending on the parser's mode, blank lines may be treated as " +"parts of multiline values or ignored." +msgstr "" + +#: ../../library/configparser.rst:280 +msgid "" +"By default, a valid section name can be any string that does not contain '\\" +"\\n'. To change this, see :attr:`ConfigParser.SECTCRE`." +msgstr "" + +#: ../../library/configparser.rst:283 +msgid "" +"The first section name may be omitted if the parser is configured to allow " +"an unnamed top level section with ``allow_unnamed_section=True``. In this " +"case, the keys/values may be retrieved by :const:`UNNAMED_SECTION` as in " +"``config[UNNAMED_SECTION]``." +msgstr "" + +#: ../../library/configparser.rst:288 +msgid "" +"Configuration files may include comments, prefixed by specific characters " +"(``#`` and ``;`` by default [1]_). Comments may appear on their own on an " +"otherwise empty line, possibly indented. [1]_" +msgstr "" + +#: ../../library/configparser.rst:292 ../../library/configparser.rst:376 +msgid "For example:" +msgstr "舉例來說：" + +#: ../../library/configparser.rst:294 +msgid "" +"[Simple Values]\n" +"key=value\n" +"spaces in keys=allowed\n" +"spaces in values=allowed as well\n" +"spaces around the delimiter = obviously\n" +"you can also use : to delimit keys from values\n" +"\n" +"[All Values Are Strings]\n" +"values like this: 1000000\n" +"or this: 3.14159265359\n" +"are they treated as numbers? : no\n" +"integers, floats and booleans are held as: strings\n" +"can use the API to get converted values directly: true\n" +"\n" +"[Multiline Values]\n" +"chorus: I'm a lumberjack, and I'm okay\n" +" I sleep all night and I work all day\n" +"\n" +"[No Values]\n" +"key_without_value\n" +"empty string value here =\n" +"\n" +"[You can use comments]\n" +"# like this\n" +"; or this\n" +"\n" +"# By default only in an empty line.\n" +"# Inline comments can be harmful because they prevent users\n" +"# from using the delimiting characters as parts of values.\n" +"# That being said, this can be customized.\n" +"\n" +" [Sections Can Be Indented]\n" +" can_values_be_as_well = True\n" +" does_that_mean_anything_special = False\n" +" purpose = formatting for readability\n" +" multiline_values = are\n" +" handled just fine as\n" +" long as they are indented\n" +" deeper than the first line\n" +" of a value\n" +" # Did I mention we can indent comments, too?" +msgstr "" + +#: ../../library/configparser.rst:342 +msgid "Unnamed Sections" +msgstr "" + +#: ../../library/configparser.rst:344 +msgid "" +"The name of the first section (or unique) may be omitted and values " +"retrieved by the :const:`UNNAMED_SECTION` attribute." +msgstr "" + +#: ../../library/configparser.rst:347 +msgid "" +">>> config = \"\"\"\n" +"... option = value\n" +"...\n" +"... [ Section 2 ]\n" +"... another = val\n" +"... \"\"\"\n" +">>> unnamed = configparser.ConfigParser(allow_unnamed_section=True)\n" +">>> unnamed.read_string(config)\n" +">>> unnamed.get(configparser.UNNAMED_SECTION, 'option')\n" +"'value'" +msgstr "" +">>> config = \"\"\"\n" +"... option = value\n" +"...\n" +"... [ Section 2 ]\n" +"... another = val\n" +"... \"\"\"\n" +">>> unnamed = configparser.ConfigParser(allow_unnamed_section=True)\n" +">>> unnamed.read_string(config)\n" +">>> unnamed.get(configparser.UNNAMED_SECTION, 'option')\n" +"'value'" + +#: ../../library/configparser.rst:361 +msgid "Interpolation of values" +msgstr "" + +#: ../../library/configparser.rst:363 +msgid "" +"On top of the core functionality, :class:`ConfigParser` supports " +"interpolation. This means values can be preprocessed before returning them " +"from ``get()`` calls." +msgstr "" + +#: ../../library/configparser.rst:371 +msgid "" +"The default implementation used by :class:`ConfigParser`. It enables values " +"to contain format strings which refer to other values in the same section, " +"or values in the special default section [1]_. Additional default values " +"can be provided on initialization." +msgstr "" + +#: ../../library/configparser.rst:378 +msgid "" +"[Paths]\n" +"home_dir: /Users\n" +"my_dir: %(home_dir)s/lumberjack\n" +"my_pictures: %(my_dir)s/Pictures\n" +"\n" +"[Escape]\n" +"# use a %% to escape the % sign (% is the only character that needs to be " +"escaped):\n" +"gain: 80%%" +msgstr "" + +#: ../../library/configparser.rst:389 +msgid "" +"In the example above, :class:`ConfigParser` with *interpolation* set to " +"``BasicInterpolation()`` would resolve ``%(home_dir)s`` to the value of " +"``home_dir`` (``/Users`` in this case). ``%(my_dir)s`` in effect would " +"resolve to ``/Users/lumberjack``. All interpolations are done on demand so " +"keys used in the chain of references do not have to be specified in any " +"specific order in the configuration file." +msgstr "" + +#: ../../library/configparser.rst:396 +msgid "" +"With ``interpolation`` set to ``None``, the parser would simply return ``%" +"(my_dir)s/Pictures`` as the value of ``my_pictures`` and ``%(home_dir)s/" +"lumberjack`` as the value of ``my_dir``." +msgstr "" + +#: ../../library/configparser.rst:404 +msgid "" +"An alternative handler for interpolation which implements a more advanced " +"syntax, used for instance in ``zc.buildout``. Extended interpolation is " +"using ``${section:option}`` to denote a value from a foreign section. " +"Interpolation can span multiple levels. For convenience, if the " +"``section:`` part is omitted, interpolation defaults to the current section " +"(and possibly the default values from the special section)." +msgstr "" + +#: ../../library/configparser.rst:411 +msgid "" +"For example, the configuration specified above with basic interpolation, " +"would look like this with extended interpolation:" +msgstr "" + +#: ../../library/configparser.rst:414 +msgid "" +"[Paths]\n" +"home_dir: /Users\n" +"my_dir: ${home_dir}/lumberjack\n" +"my_pictures: ${my_dir}/Pictures\n" +"\n" +"[Escape]\n" +"# use a $$ to escape the $ sign ($ is the only character that needs to be " +"escaped):\n" +"cost: $$80" +msgstr "" + +#: ../../library/configparser.rst:425 +msgid "Values from other sections can be fetched as well:" +msgstr "" + +#: ../../library/configparser.rst:427 +msgid "" +"[Common]\n" +"home_dir: /Users\n" +"library_dir: /Library\n" +"system_dir: /System\n" +"macports_dir: /opt/local\n" +"\n" +"[Frameworks]\n" +"Python: 3.2\n" +"path: ${Common:system_dir}/Library/Frameworks/\n" +"\n" +"[Arthur]\n" +"nickname: Two Sheds\n" +"last_name: Jackson\n" +"my_dir: ${Common:home_dir}/twosheds\n" +"my_pictures: ${my_dir}/Pictures\n" +"python_dir: ${Frameworks:path}/Python/Versions/${Frameworks:Python}" +msgstr "" +"[Common]\n" +"home_dir: /Users\n" +"library_dir: /Library\n" +"system_dir: /System\n" +"macports_dir: /opt/local\n" +"\n" +"[Frameworks]\n" +"Python: 3.2\n" +"path: ${Common:system_dir}/Library/Frameworks/\n" +"\n" +"[Arthur]\n" +"nickname: Two Sheds\n" +"last_name: Jackson\n" +"my_dir: ${Common:home_dir}/twosheds\n" +"my_pictures: ${my_dir}/Pictures\n" +"python_dir: ${Frameworks:path}/Python/Versions/${Frameworks:Python}" + +#: ../../library/configparser.rst:447 +msgid "Mapping Protocol Access" +msgstr "" + +#: ../../library/configparser.rst:451 +msgid "" +"Mapping protocol access is a generic name for functionality that enables " +"using custom objects as if they were dictionaries. In case " +"of :mod:`configparser`, the mapping interface implementation is using the " +"``parser['section']['option']`` notation." +msgstr "" + +#: ../../library/configparser.rst:456 +msgid "" +"``parser['section']`` in particular returns a proxy for the section's data " +"in the parser. This means that the values are not copied but they are taken " +"from the original parser on demand. What's even more important is that when " +"values are changed on a section proxy, they are actually mutated in the " +"original parser." +msgstr "" + +#: ../../library/configparser.rst:462 +msgid "" +":mod:`configparser` objects behave as close to actual dictionaries as " +"possible. The mapping interface is complete and adheres to " +"the :class:`~collections.abc.MutableMapping` ABC. However, there are a few " +"differences that should be taken into account:" +msgstr "" + +#: ../../library/configparser.rst:467 +msgid "" +"By default, all keys in sections are accessible in a case-insensitive manner " +"[1]_. E.g. ``for option in parser[\"section\"]`` yields only " +"``optionxform``'ed option key names. This means lowercased keys by " +"default. At the same time, for a section that holds the key ``'a'``, both " +"expressions return ``True``::" +msgstr "" + +#: ../../library/configparser.rst:472 +msgid "" +"\"a\" in parser[\"section\"]\n" +"\"A\" in parser[\"section\"]" +msgstr "" +"\"a\" in parser[\"section\"]\n" +"\"A\" in parser[\"section\"]" + +#: ../../library/configparser.rst:475 +msgid "" +"All sections include ``DEFAULTSECT`` values as well which means that " +"``.clear()`` on a section may not leave the section visibly empty. This is " +"because default values cannot be deleted from the section (because " +"technically they are not there). If they are overridden in the section, " +"deleting causes the default value to be visible again. Trying to delete a " +"default value causes a :exc:`KeyError`." +msgstr "" + +#: ../../library/configparser.rst:482 +msgid "``DEFAULTSECT`` cannot be removed from the parser:" +msgstr "``DEFAULTSECT`` 不能從剖析器中移除：" + +#: ../../library/configparser.rst:484 +msgid "trying to delete it raises :exc:`ValueError`," +msgstr "嘗試刪除它會引發 :exc:`ValueError`，" + +#: ../../library/configparser.rst:486 +msgid "``parser.clear()`` leaves it intact," +msgstr "``parser.clear()`` 會保持它不變，" + +#: ../../library/configparser.rst:488 +msgid "``parser.popitem()`` never returns it." +msgstr "``parser.popitem()`` 永遠不會回傳它。" + +#: ../../library/configparser.rst:490 +msgid "" +"``parser.get(section, option, **kwargs)`` - the second argument is **not** a " +"fallback value. Note however that the section-level ``get()`` methods are " +"compatible both with the mapping protocol and the classic configparser API." +msgstr "" + +#: ../../library/configparser.rst:494 +msgid "" +"``parser.items()`` is compatible with the mapping protocol (returns a list " +"of *section_name*, *section_proxy* pairs including the DEFAULTSECT). " +"However, this method can also be invoked with arguments: " +"``parser.items(section, raw, vars)``. The latter call returns a list of " +"*option*, *value* pairs for a specified ``section``, with all interpolations " +"expanded (unless ``raw=True`` is provided)." +msgstr "" + +#: ../../library/configparser.rst:501 +msgid "" +"The mapping protocol is implemented on top of the existing legacy API so " +"that subclasses overriding the original interface still should have mappings " +"working as expected." +msgstr "" + +#: ../../library/configparser.rst:507 +msgid "Customizing Parser Behaviour" +msgstr "" + +#: ../../library/configparser.rst:509 +msgid "" +"There are nearly as many INI format variants as there are applications using " +"it. :mod:`configparser` goes a long way to provide support for the largest " +"sensible set of INI styles available. The default functionality is mainly " +"dictated by historical background and it's very likely that you will want to " +"customize some of the features." +msgstr "" + +#: ../../library/configparser.rst:515 +msgid "" +"The most common way to change the way a specific config parser works is to " +"use the :meth:`!__init__` options:" +msgstr "" + +#: ../../library/configparser.rst:518 +msgid "*defaults*, default value: ``None``" +msgstr "" + +#: ../../library/configparser.rst:520 +msgid "" +"This option accepts a dictionary of key-value pairs which will be initially " +"put in the ``DEFAULT`` section. This makes for an elegant way to support " +"concise configuration files that don't specify values which are the same as " +"the documented default." +msgstr "" + +#: ../../library/configparser.rst:525 +msgid "" +"Hint: if you want to specify default values for a specific section, " +"use :meth:`~ConfigParser.read_dict` before you read the actual file." +msgstr "" + +#: ../../library/configparser.rst:528 +msgid "*dict_type*, default value: :class:`dict`" +msgstr "" + +#: ../../library/configparser.rst:530 +msgid "" +"This option has a major impact on how the mapping protocol will behave and " +"how the written configuration files look. With the standard dictionary, " +"every section is stored in the order they were added to the parser. Same " +"goes for options within sections." +msgstr "" + +#: ../../library/configparser.rst:535 +msgid "" +"An alternative dictionary type can be used for example to sort sections and " +"options on write-back." +msgstr "" + +#: ../../library/configparser.rst:538 +msgid "" +"Please note: there are ways to add a set of key-value pairs in a single " +"operation. When you use a regular dictionary in those operations, the order " +"of the keys will be ordered. For example:" +msgstr "" + +#: ../../library/configparser.rst:542 +msgid "" +">>> parser = configparser.ConfigParser()\n" +">>> parser.read_dict({'section1': {'key1': 'value1',\n" +"... 'key2': 'value2',\n" +"... 'key3': 'value3'},\n" +"... 'section2': {'keyA': 'valueA',\n" +"... 'keyB': 'valueB',\n" +"... 'keyC': 'valueC'},\n" +"... 'section3': {'foo': 'x',\n" +"... 'bar': 'y',\n" +"... 'baz': 'z'}\n" +"... })\n" +">>> parser.sections()\n" +"['section1', 'section2', 'section3']\n" +">>> [option for option in parser['section3']]\n" +"['foo', 'bar', 'baz']" +msgstr "" +">>> parser = configparser.ConfigParser()\n" +">>> parser.read_dict({'section1': {'key1': 'value1',\n" +"... 'key2': 'value2',\n" +"... 'key3': 'value3'},\n" +"... 'section2': {'keyA': 'valueA',\n" +"... 'keyB': 'valueB',\n" +"... 'keyC': 'valueC'},\n" +"... 'section3': {'foo': 'x',\n" +"... 'bar': 'y',\n" +"... 'baz': 'z'}\n" +"... })\n" +">>> parser.sections()\n" +"['section1', 'section2', 'section3']\n" +">>> [option for option in parser['section3']]\n" +"['foo', 'bar', 'baz']" + +#: ../../library/configparser.rst:560 +msgid "*allow_no_value*, default value: ``False``" +msgstr "" + +#: ../../library/configparser.rst:562 +msgid "" +"Some configuration files are known to include settings without values, but " +"which otherwise conform to the syntax supported by :mod:`configparser`. The " +"*allow_no_value* parameter to the constructor can be used to indicate that " +"such values should be accepted:" +msgstr "" + +#: ../../library/configparser.rst:567 +msgid "" +">>> import configparser\n" +"\n" +">>> sample_config = \"\"\"\n" +"... [mysqld]\n" +"... user = mysql\n" +"... pid-file = /var/run/mysqld/mysqld.pid\n" +"... skip-external-locking\n" +"... old_passwords = 1\n" +"... skip-bdb\n" +"... # we don't need ACID today\n" +"... skip-innodb\n" +"... \"\"\"\n" +">>> config = configparser.ConfigParser(allow_no_value=True)\n" +">>> config.read_string(sample_config)\n" +"\n" +">>> # Settings with values are treated as before:\n" +">>> config[\"mysqld\"][\"user\"]\n" +"'mysql'\n" +"\n" +">>> # Settings without values provide None:\n" +">>> config[\"mysqld\"][\"skip-bdb\"]\n" +"\n" +">>> # Settings which aren't specified still raise an error:\n" +">>> config[\"mysqld\"][\"does-not-exist\"]\n" +"Traceback (most recent call last):\n" +" ...\n" +"KeyError: 'does-not-exist'" +msgstr "" + +#: ../../library/configparser.rst:597 +msgid "*delimiters*, default value: ``('=', ':')``" +msgstr "" + +#: ../../library/configparser.rst:599 +msgid "" +"Delimiters are substrings that delimit keys from values within a section. " +"The first occurrence of a delimiting substring on a line is considered a " +"delimiter. This means values (but not keys) can contain the delimiters." +msgstr "" + +#: ../../library/configparser.rst:603 +msgid "" +"See also the *space_around_delimiters* argument " +"to :meth:`ConfigParser.write`." +msgstr "" + +#: ../../library/configparser.rst:606 +msgid "*comment_prefixes*, default value: ``('#', ';')``" +msgstr "" + +#: ../../library/configparser.rst:608 +msgid "*inline_comment_prefixes*, default value: ``None``" +msgstr "" + +#: ../../library/configparser.rst:610 +msgid "" +"Comment prefixes are strings that indicate the start of a valid comment " +"within a config file. *comment_prefixes* are used only on otherwise empty " +"lines (optionally indented) whereas *inline_comment_prefixes* can be used " +"after every valid value (e.g. section names, options and empty lines as " +"well). By default inline comments are disabled and ``'#'`` and ``';'`` are " +"used as prefixes for whole line comments." +msgstr "" + +#: ../../library/configparser.rst:617 +msgid "" +"In previous versions of :mod:`configparser` behaviour matched " +"``comment_prefixes=('#',';')`` and ``inline_comment_prefixes=(';',)``." +msgstr "" + +#: ../../library/configparser.rst:621 +msgid "" +"Please note that config parsers don't support escaping of comment prefixes " +"so using *inline_comment_prefixes* may prevent users from specifying option " +"values with characters used as comment prefixes. When in doubt, avoid " +"setting *inline_comment_prefixes*. In any circumstances, the only way of " +"storing comment prefix characters at the beginning of a line in multiline " +"values is to interpolate the prefix, for example::" +msgstr "" + +#: ../../library/configparser.rst:628 +msgid "" +">>> from configparser import ConfigParser, ExtendedInterpolation\n" +">>> parser = ConfigParser(interpolation=ExtendedInterpolation())\n" +">>> # the default BasicInterpolation could be used as well\n" +">>> parser.read_string(\"\"\"\n" +"... [DEFAULT]\n" +"... hash = #\n" +"...\n" +"... [hashes]\n" +"... shebang =\n" +"... ${hash}!/usr/bin/env python\n" +"... ${hash} -*- coding: utf-8 -*-\n" +"...\n" +"... extensions =\n" +"... enabled_extension\n" +"... another_extension\n" +"... #disabled_by_comment\n" +"... yet_another_extension\n" +"...\n" +"... interpolation not necessary = if # is not at line start\n" +"... even in multiline values = line #1\n" +"... line #2\n" +"... line #3\n" +"... \"\"\")\n" +">>> print(parser['hashes']['shebang'])\n" +"\n" +"#!/usr/bin/env python\n" +"# -*- coding: utf-8 -*-\n" +">>> print(parser['hashes']['extensions'])\n" +"\n" +"enabled_extension\n" +"another_extension\n" +"yet_another_extension\n" +">>> print(parser['hashes']['interpolation not necessary'])\n" +"if # is not at line start\n" +">>> print(parser['hashes']['even in multiline values'])\n" +"line #1\n" +"line #2\n" +"line #3" +msgstr "" + +#: ../../library/configparser.rst:667 +msgid "*strict*, default value: ``True``" +msgstr "" + +#: ../../library/configparser.rst:669 +msgid "" +"When set to ``True``, the parser will not allow for any section or option " +"duplicates while reading from a single source " +"(using :meth:`~ConfigParser.read_file`, :meth:`~ConfigParser.read_string` " +"or :meth:`~ConfigParser.read_dict`). It is recommended to use strict " +"parsers in new applications." +msgstr "" + +#: ../../library/configparser.rst:674 +msgid "" +"In previous versions of :mod:`configparser` behaviour matched " +"``strict=False``." +msgstr "" + +#: ../../library/configparser.rst:678 +msgid "*empty_lines_in_values*, default value: ``True``" +msgstr "" + +#: ../../library/configparser.rst:680 +msgid "" +"In config parsers, values can span multiple lines as long as they are " +"indented more than the key that holds them. By default parsers also let " +"empty lines to be parts of values. At the same time, keys can be " +"arbitrarily indented themselves to improve readability. In consequence, " +"when configuration files get big and complex, it is easy for the user to " +"lose track of the file structure. Take for instance:" +msgstr "" + +#: ../../library/configparser.rst:687 +msgid "" +"[Section]\n" +"key = multiline\n" +" value with a gotcha\n" +"\n" +" this = is still a part of the multiline value of 'key'" +msgstr "" +"[Section]\n" +"key = multiline\n" +" value with a gotcha\n" +"\n" +" this = is still a part of the multiline value of 'key'" + +#: ../../library/configparser.rst:695 +msgid "" +"This can be especially problematic for the user to see if she's using a " +"proportional font to edit the file. That is why when your application does " +"not need values with empty lines, you should consider disallowing them. " +"This will make empty lines split keys every time. In the example above, it " +"would produce two keys, ``key`` and ``this``." +msgstr "" + +#: ../../library/configparser.rst:701 +msgid "" +"*default_section*, default value: ``configparser.DEFAULTSECT`` (that is: " +"``\"DEFAULT\"``)" +msgstr "" + +#: ../../library/configparser.rst:704 +msgid "" +"The convention of allowing a special section of default values for other " +"sections or interpolation purposes is a powerful concept of this library, " +"letting users create complex declarative configurations. This section is " +"normally called ``\"DEFAULT\"`` but this can be customized to point to any " +"other valid section name. Some typical values include: ``\"general\"`` or " +"``\"common\"``. The name provided is used for recognizing default sections " +"when reading from any source and is used when writing configuration back to " +"a file. Its current value can be retrieved using the " +"``parser_instance.default_section`` attribute and may be modified at runtime " +"(i.e. to convert files from one format to another)." +msgstr "" + +#: ../../library/configparser.rst:715 +msgid "*interpolation*, default value: ``configparser.BasicInterpolation``" +msgstr "" + +#: ../../library/configparser.rst:717 +msgid "" +"Interpolation behaviour may be customized by providing a custom handler " +"through the *interpolation* argument. ``None`` can be used to turn off " +"interpolation completely, ``ExtendedInterpolation()`` provides a more " +"advanced variant inspired by ``zc.buildout``. More on the subject in the " +"`dedicated documentation section <#interpolation-of-" +"values>`_. :class:`RawConfigParser` has a default value of ``None``." +msgstr "" + +#: ../../library/configparser.rst:724 +msgid "*converters*, default value: not set" +msgstr "" + +#: ../../library/configparser.rst:726 +msgid "" +"Config parsers provide option value getters that perform type conversion. " +"By default :meth:`~ConfigParser.getint`, :meth:`~ConfigParser.getfloat`, " +"and :meth:`~ConfigParser.getboolean` are implemented. Should other getters " +"be desirable, users may define them in a subclass or pass a dictionary where " +"each key is a name of the converter and each value is a callable " +"implementing said conversion. For instance, passing ``{'decimal': " +"decimal.Decimal}`` would add :meth:`!getdecimal` on both the parser object " +"and all section proxies. In other words, it will be possible to write both " +"``parser_instance.getdecimal('section', 'key', fallback=0)`` and " +"``parser_instance['section'].getdecimal('key', 0)``." +msgstr "" + +#: ../../library/configparser.rst:737 +msgid "" +"If the converter needs to access the state of the parser, it can be " +"implemented as a method on a config parser subclass. If the name of this " +"method starts with ``get``, it will be available on all section proxies, in " +"the dict-compatible form (see the ``getdecimal()`` example above)." +msgstr "" + +#: ../../library/configparser.rst:742 +msgid "" +"More advanced customization may be achieved by overriding default values of " +"these parser attributes. The defaults are defined on the classes, so they " +"may be overridden by subclasses or by attribute assignment." +msgstr "" + +#: ../../library/configparser.rst:748 +msgid "" +"By default when using :meth:`~ConfigParser.getboolean`, config parsers " +"consider the following values ``True``: ``'1'``, ``'yes'``, ``'true'``, " +"``'on'`` and the following values ``False``: ``'0'``, ``'no'``, ``'false'``, " +"``'off'``. You can override this by specifying a custom dictionary of " +"strings and their Boolean outcomes. For example:" +msgstr "" + +#: ../../library/configparser.rst:754 +msgid "" +">>> custom = configparser.ConfigParser()\n" +">>> custom['section1'] = {'funky': 'nope'}\n" +">>> custom['section1'].getboolean('funky')\n" +"Traceback (most recent call last):\n" +"...\n" +"ValueError: Not a boolean: nope\n" +">>> custom.BOOLEAN_STATES = {'sure': True, 'nope': False}\n" +">>> custom['section1'].getboolean('funky')\n" +"False" +msgstr "" +">>> custom = configparser.ConfigParser()\n" +">>> custom['section1'] = {'funky': 'nope'}\n" +">>> custom['section1'].getboolean('funky')\n" +"Traceback (most recent call last):\n" +"...\n" +"ValueError: Not a boolean: nope\n" +">>> custom.BOOLEAN_STATES = {'sure': True, 'nope': False}\n" +">>> custom['section1'].getboolean('funky')\n" +"False" + +#: ../../library/configparser.rst:766 +msgid "" +"Other typical Boolean pairs include ``accept``/``reject`` or ``enabled``/" +"``disabled``." +msgstr "" + +#: ../../library/configparser.rst:772 +msgid "" +"This method transforms option names on every read, get, or set operation. " +"The default converts the name to lowercase. This also means that when a " +"configuration file gets written, all keys will be lowercase. Override this " +"method if that's unsuitable. For example:" +msgstr "" + +#: ../../library/configparser.rst:778 +msgid "" +">>> config = \"\"\"\n" +"... [Section1]\n" +"... Key = Value\n" +"...\n" +"... [Section2]\n" +"... AnotherKey = Value\n" +"... \"\"\"\n" +">>> typical = configparser.ConfigParser()\n" +">>> typical.read_string(config)\n" +">>> list(typical['Section1'].keys())\n" +"['key']\n" +">>> list(typical['Section2'].keys())\n" +"['anotherkey']\n" +">>> custom = configparser.RawConfigParser()\n" +">>> custom.optionxform = lambda option: option\n" +">>> custom.read_string(config)\n" +">>> list(custom['Section1'].keys())\n" +"['Key']\n" +">>> list(custom['Section2'].keys())\n" +"['AnotherKey']" +msgstr "" +">>> config = \"\"\"\n" +"... [Section1]\n" +"... Key = Value\n" +"...\n" +"... [Section2]\n" +"... AnotherKey = Value\n" +"... \"\"\"\n" +">>> typical = configparser.ConfigParser()\n" +">>> typical.read_string(config)\n" +">>> list(typical['Section1'].keys())\n" +"['key']\n" +">>> list(typical['Section2'].keys())\n" +"['anotherkey']\n" +">>> custom = configparser.RawConfigParser()\n" +">>> custom.optionxform = lambda option: option\n" +">>> custom.read_string(config)\n" +">>> list(custom['Section1'].keys())\n" +"['Key']\n" +">>> list(custom['Section2'].keys())\n" +"['AnotherKey']" + +#: ../../library/configparser.rst:802 +msgid "" +"The optionxform function transforms option names to a canonical form. This " +"should be an idempotent function: if the name is already in canonical form, " +"it should be returned unchanged." +msgstr "" + +#: ../../library/configparser.rst:809 +msgid "" +"A compiled regular expression used to parse section headers. The default " +"matches ``[section]`` to the name ``\"section\"``. Whitespace is considered " +"part of the section name, thus ``[ larch ]`` will be read as a section of " +"name ``\" larch \"``. Override this attribute if that's unsuitable. For " +"example:" +msgstr "" + +#: ../../library/configparser.rst:815 +msgid "" +">>> import re\n" +">>> config = \"\"\"\n" +"... [Section 1]\n" +"... option = value\n" +"...\n" +"... [ Section 2 ]\n" +"... another = val\n" +"... \"\"\"\n" +">>> typical = configparser.ConfigParser()\n" +">>> typical.read_string(config)\n" +">>> typical.sections()\n" +"['Section 1', ' Section 2 ']\n" +">>> custom = configparser.ConfigParser()\n" +">>> custom.SECTCRE = re.compile(r\"\\[ *(?P
[^]]+?) *\\]\")\n" +">>> custom.read_string(config)\n" +">>> custom.sections()\n" +"['Section 1', 'Section 2']" +msgstr "" +">>> import re\n" +">>> config = \"\"\"\n" +"... [Section 1]\n" +"... option = value\n" +"...\n" +"... [ Section 2 ]\n" +"... another = val\n" +"... \"\"\"\n" +">>> typical = configparser.ConfigParser()\n" +">>> typical.read_string(config)\n" +">>> typical.sections()\n" +"['Section 1', ' Section 2 ']\n" +">>> custom = configparser.ConfigParser()\n" +">>> custom.SECTCRE = re.compile(r\"\\[ *(?P
[^]]+?) *\\]\")\n" +">>> custom.read_string(config)\n" +">>> custom.sections()\n" +"['Section 1', 'Section 2']" + +#: ../../library/configparser.rst:837 +msgid "" +"While ConfigParser objects also use an ``OPTCRE`` attribute for recognizing " +"option lines, it's not recommended to override it because that would " +"interfere with constructor options *allow_no_value* and *delimiters*." +msgstr "" + +#: ../../library/configparser.rst:843 +msgid "Legacy API Examples" +msgstr "" + +#: ../../library/configparser.rst:845 +msgid "" +"Mainly because of backwards compatibility concerns, :mod:`configparser` " +"provides also a legacy API with explicit ``get``/``set`` methods. While " +"there are valid use cases for the methods outlined below, mapping protocol " +"access is preferred for new projects. The legacy API is at times more " +"advanced, low-level and downright counterintuitive." +msgstr "" + +#: ../../library/configparser.rst:851 +msgid "An example of writing to a configuration file::" +msgstr "" + +#: ../../library/configparser.rst:853 +msgid "" +"import configparser\n" +"\n" +"config = configparser.RawConfigParser()\n" +"\n" +"# Please note that using RawConfigParser's set functions, you can assign\n" +"# non-string values to keys internally, but will receive an error when\n" +"# attempting to write to a file or when you get it in non-raw mode. Setting\n" +"# values using the mapping protocol or ConfigParser's set() does not allow\n" +"# such assignments to take place.\n" +"config.add_section('Section1')\n" +"config.set('Section1', 'an_int', '15')\n" +"config.set('Section1', 'a_bool', 'true')\n" +"config.set('Section1', 'a_float', '3.1415')\n" +"config.set('Section1', 'baz', 'fun')\n" +"config.set('Section1', 'bar', 'Python')\n" +"config.set('Section1', 'foo', '%(bar)s is %(baz)s!')\n" +"\n" +"# Writing our configuration file to 'example.cfg'\n" +"with open('example.cfg', 'w') as configfile:\n" +" config.write(configfile)" +msgstr "" + +#: ../../library/configparser.rst:874 +msgid "An example of reading the configuration file again::" +msgstr "" + +#: ../../library/configparser.rst:876 +msgid "" +"import configparser\n" +"\n" +"config = configparser.RawConfigParser()\n" +"config.read('example.cfg')\n" +"\n" +"# getfloat() raises an exception if the value is not a float\n" +"# getint() and getboolean() also do this for their respective types\n" +"a_float = config.getfloat('Section1', 'a_float')\n" +"an_int = config.getint('Section1', 'an_int')\n" +"print(a_float + an_int)\n" +"\n" +"# Notice that the next output does not interpolate '%(bar)s' or '%(baz)s'.\n" +"# This is because we are using a RawConfigParser().\n" +"if config.getboolean('Section1', 'a_bool'):\n" +" print(config.get('Section1', 'foo'))" +msgstr "" + +#: ../../library/configparser.rst:892 +msgid "To get interpolation, use :class:`ConfigParser`::" +msgstr "" + +#: ../../library/configparser.rst:894 +msgid "" +"import configparser\n" +"\n" +"cfg = configparser.ConfigParser()\n" +"cfg.read('example.cfg')\n" +"\n" +"# Set the optional *raw* argument of get() to True if you wish to disable\n" +"# interpolation in a single get operation.\n" +"print(cfg.get('Section1', 'foo', raw=False)) # -> \"Python is fun!\"\n" +"print(cfg.get('Section1', 'foo', raw=True)) # -> \"%(bar)s is %(baz)s!\"\n" +"\n" +"# The optional *vars* argument is a dict with members that will take\n" +"# precedence in interpolation.\n" +"print(cfg.get('Section1', 'foo', vars={'bar': 'Documentation',\n" +" 'baz': 'evil'}))\n" +"\n" +"# The optional *fallback* argument can be used to provide a fallback value\n" +"print(cfg.get('Section1', 'foo'))\n" +" # -> \"Python is fun!\"\n" +"\n" +"print(cfg.get('Section1', 'foo', fallback='Monty is not.'))\n" +" # -> \"Python is fun!\"\n" +"\n" +"print(cfg.get('Section1', 'monster', fallback='No such things as " +"monsters.'))\n" +" # -> \"No such things as monsters.\"\n" +"\n" +"# A bare print(cfg.get('Section1', 'monster')) would raise NoOptionError\n" +"# but we can also use:\n" +"\n" +"print(cfg.get('Section1', 'monster', fallback=None))\n" +" # -> None" +msgstr "" + +#: ../../library/configparser.rst:925 +msgid "" +"Default values are available in both types of ConfigParsers. They are used " +"in interpolation if an option used is not defined elsewhere. ::" +msgstr "" + +#: ../../library/configparser.rst:928 +msgid "" +"import configparser\n" +"\n" +"# New instance with 'bar' and 'baz' defaulting to 'Life' and 'hard' each\n" +"config = configparser.ConfigParser({'bar': 'Life', 'baz': 'hard'})\n" +"config.read('example.cfg')\n" +"\n" +"print(config.get('Section1', 'foo')) # -> \"Python is fun!\"\n" +"config.remove_option('Section1', 'bar')\n" +"config.remove_option('Section1', 'baz')\n" +"print(config.get('Section1', 'foo')) # -> \"Life is hard!\"" +msgstr "" + +#: ../../library/configparser.rst:943 +msgid "ConfigParser Objects" +msgstr "ConfigParser 物件" + +#: ../../library/configparser.rst:953 +msgid "" +"The main configuration parser. When *defaults* is given, it is initialized " +"into the dictionary of intrinsic defaults. When *dict_type* is given, it " +"will be used to create the dictionary objects for the list of sections, for " +"the options within a section, and for the default values." +msgstr "" + +#: ../../library/configparser.rst:958 +msgid "" +"When *delimiters* is given, it is used as the set of substrings that divide " +"keys from values. When *comment_prefixes* is given, it will be used as the " +"set of substrings that prefix comments in otherwise empty lines. Comments " +"can be indented. When *inline_comment_prefixes* is given, it will be used " +"as the set of substrings that prefix comments in non-empty lines." +msgstr "" + +#: ../../library/configparser.rst:964 +msgid "" +"When *strict* is ``True`` (the default), the parser won't allow for any " +"section or option duplicates while reading from a single source (file, " +"string or dictionary), raising :exc:`DuplicateSectionError` " +"or :exc:`DuplicateOptionError`. When *empty_lines_in_values* is ``False`` " +"(default: ``True``), each empty line marks the end of an option. Otherwise, " +"internal empty lines of a multiline option are kept as part of the value. " +"When *allow_no_value* is ``True`` (default: ``False``), options without " +"values are accepted; the value held for these is ``None`` and they are " +"serialized without the trailing delimiter." +msgstr "" + +#: ../../library/configparser.rst:974 +msgid "" +"When *default_section* is given, it specifies the name for the special " +"section holding default values for other sections and interpolation purposes " +"(normally named ``\"DEFAULT\"``). This value can be retrieved and changed " +"at runtime using the ``default_section`` instance attribute. This won't re-" +"evaluate an already parsed config file, but will be used when writing parsed " +"settings to a new config file." +msgstr "" + +#: ../../library/configparser.rst:981 +msgid "" +"Interpolation behaviour may be customized by providing a custom handler " +"through the *interpolation* argument. ``None`` can be used to turn off " +"interpolation completely, ``ExtendedInterpolation()`` provides a more " +"advanced variant inspired by ``zc.buildout``. More on the subject in the " +"`dedicated documentation section <#interpolation-of-values>`_." +msgstr "" + +#: ../../library/configparser.rst:987 +msgid "" +"All option names used in interpolation will be passed through " +"the :meth:`optionxform` method just like any other option name reference. " +"For example, using the default implementation of :meth:`optionxform` (which " +"converts option names to lower case), the values ``foo %(bar)s`` and ``foo %" +"(BAR)s`` are equivalent." +msgstr "" + +#: ../../library/configparser.rst:993 +msgid "" +"When *converters* is given, it should be a dictionary where each key " +"represents the name of a type converter and each value is a callable " +"implementing the conversion from string to the desired datatype. Every " +"converter gets its own corresponding :meth:`!get*` method on the parser " +"object and section proxies." +msgstr "" + +#: ../../library/configparser.rst:999 +msgid "" +"When *allow_unnamed_section* is ``True`` (default: ``False``), the first " +"section name can be omitted. See the `\"Unnamed Sections\" section <#unnamed-" +"sections>`_." +msgstr "" + +#: ../../library/configparser.rst:1028 +msgid "The default *dict_type* is :class:`collections.OrderedDict`." +msgstr "預設的 *dict_type* 是 :class:`collections.OrderedDict`。" + +#: ../../library/configparser.rst:1031 ../../library/configparser.rst:1324 +msgid "" +"*allow_no_value*, *delimiters*, *comment_prefixes*, *strict*, " +"*empty_lines_in_values*, *default_section* and *interpolation* were added." +msgstr "" + +#: ../../library/configparser.rst:1036 ../../library/configparser.rst:1329 +msgid "The *converters* argument was added." +msgstr "新增 *converters* 引數。" + +#: ../../library/configparser.rst:1039 +msgid "" +"The *defaults* argument is read with :meth:`read_dict`, providing consistent " +"behavior across the parser: non-string keys and values are implicitly " +"converted to strings." +msgstr "" + +#: ../../library/configparser.rst:1044 ../../library/configparser.rst:1332 +msgid "" +"The default *dict_type* is :class:`dict`, since it now preserves insertion " +"order." +msgstr "" + +#: ../../library/configparser.rst:1048 +msgid "" +"Raise a :exc:`MultilineContinuationError` when *allow_no_value* is ``True``, " +"and a key without a value is continued with an indented line." +msgstr "" + +#: ../../library/configparser.rst:1052 ../../library/configparser.rst:1336 +msgid "The *allow_unnamed_section* argument was added." +msgstr "新增 *allow_unnamed_section* 引數。" + +#: ../../library/configparser.rst:1057 +msgid "Return a dictionary containing the instance-wide defaults." +msgstr "回傳包含整個實例預設值的字典。" + +#: ../../library/configparser.rst:1062 +msgid "" +"Return a list of the sections available; the *default section* is not " +"included in the list." +msgstr "" + +#: ../../library/configparser.rst:1068 +msgid "" +"Add a section named *section* to the instance. If a section by the given " +"name already exists, :exc:`DuplicateSectionError` is raised. If the " +"*default section* name is passed, :exc:`ValueError` is raised. The name of " +"the section must be a string; if not, :exc:`TypeError` is raised." +msgstr "" + +#: ../../library/configparser.rst:1073 +msgid "Non-string section names raise :exc:`TypeError`." +msgstr "" + +#: ../../library/configparser.rst:1079 +msgid "" +"Indicates whether the named *section* is present in the configuration. The " +"*default section* is not acknowledged." +msgstr "" + +#: ../../library/configparser.rst:1085 +msgid "Return a list of options available in the specified *section*." +msgstr "" + +#: ../../library/configparser.rst:1090 +msgid "" +"If the given *section* exists, and contains the given *option*, " +"return :const:`True`; otherwise return :const:`False`. If the specified " +"*section* is :const:`None` or an empty string, DEFAULT is assumed." +msgstr "" + +#: ../../library/configparser.rst:1097 +msgid "" +"Attempt to read and parse an iterable of filenames, returning a list of " +"filenames which were successfully parsed." +msgstr "" + +#: ../../library/configparser.rst:1100 +msgid "" +"If *filenames* is a string, a :class:`bytes` object or a :term:`path-like " +"object`, it is treated as a single filename. If a file named in *filenames* " +"cannot be opened, that file will be ignored. This is designed so that you " +"can specify an iterable of potential configuration file locations (for " +"example, the current directory, the user's home directory, and some system-" +"wide directory), and all existing configuration files in the iterable will " +"be read." +msgstr "" + +#: ../../library/configparser.rst:1109 +msgid "" +"If none of the named files exist, the :class:`ConfigParser` instance will " +"contain an empty dataset. An application which requires initial values to " +"be loaded from a file should load the required file or files " +"using :meth:`read_file` before calling :meth:`read` for any optional files::" +msgstr "" + +#: ../../library/configparser.rst:1115 +msgid "" +"import configparser, os\n" +"\n" +"config = configparser.ConfigParser()\n" +"config.read_file(open('defaults.cfg'))\n" +"config.read(['site.cfg', os.path.expanduser('~/.myapp.cfg')],\n" +" encoding='cp1250')" +msgstr "" +"import configparser, os\n" +"\n" +"config = configparser.ConfigParser()\n" +"config.read_file(open('defaults.cfg'))\n" +"config.read(['site.cfg', os.path.expanduser('~/.myapp.cfg')],\n" +" encoding='cp1250')" + +#: ../../library/configparser.rst:1122 +msgid "" +"Added the *encoding* parameter. Previously, all files were read using the " +"default encoding for :func:`open`." +msgstr "" + +#: ../../library/configparser.rst:1126 +msgid "The *filenames* parameter accepts a :term:`path-like object`." +msgstr "" + +#: ../../library/configparser.rst:1129 +msgid "The *filenames* parameter accepts a :class:`bytes` object." +msgstr "" + +#: ../../library/configparser.rst:1135 +msgid "" +"Read and parse configuration data from *f* which must be an iterable " +"yielding Unicode strings (for example files opened in text mode)." +msgstr "" + +#: ../../library/configparser.rst:1138 +msgid "" +"Optional argument *source* specifies the name of the file being read. If " +"not given and *f* has a :attr:`!name` attribute, that is used for *source*; " +"the default is ``''``." +msgstr "" + +#: ../../library/configparser.rst:1142 +msgid "Replaces :meth:`!readfp`." +msgstr "取代 :meth:`!readfp`。" + +#: ../../library/configparser.rst:1147 +msgid "Parse configuration data from a string." +msgstr "" + +#: ../../library/configparser.rst:1149 +msgid "" +"Optional argument *source* specifies a context-specific name of the string " +"passed. If not given, ``''`` is used. This should commonly be a " +"filesystem path or a URL." +msgstr "" + +#: ../../library/configparser.rst:1158 +msgid "" +"Load configuration from any object that provides a dict-like ``items()`` " +"method. Keys are section names, values are dictionaries with keys and " +"values that should be present in the section. If the used dictionary type " +"preserves order, sections and their keys will be added in order. Values are " +"automatically converted to strings." +msgstr "" + +#: ../../library/configparser.rst:1164 +msgid "" +"Optional argument *source* specifies a context-specific name of the " +"dictionary passed. If not given, ```` is used." +msgstr "" + +#: ../../library/configparser.rst:1167 +msgid "This method can be used to copy state between parsers." +msgstr "" + +#: ../../library/configparser.rst:1174 +msgid "" +"Get an *option* value for the named *section*. If *vars* is provided, it " +"must be a dictionary. The *option* is looked up in *vars* (if provided), " +"*section*, and in *DEFAULTSECT* in that order. If the key is not found and " +"*fallback* is provided, it is used as a fallback value. ``None`` can be " +"provided as a *fallback* value." +msgstr "" + +#: ../../library/configparser.rst:1180 +msgid "" +"All the ``'%'`` interpolations are expanded in the return values, unless the " +"*raw* argument is true. Values for interpolation keys are looked up in the " +"same manner as the option." +msgstr "" + +#: ../../library/configparser.rst:1184 +msgid "" +"Arguments *raw*, *vars* and *fallback* are keyword only to protect users " +"from trying to use the third argument as the *fallback* fallback (especially " +"when using the mapping protocol)." +msgstr "" + +#: ../../library/configparser.rst:1192 +msgid "" +"A convenience method which coerces the *option* in the specified *section* " +"to an integer. See :meth:`get` for explanation of *raw*, *vars* and " +"*fallback*." +msgstr "" + +#: ../../library/configparser.rst:1199 +msgid "" +"A convenience method which coerces the *option* in the specified *section* " +"to a floating-point number. See :meth:`get` for explanation of *raw*, " +"*vars* and *fallback*." +msgstr "" + +#: ../../library/configparser.rst:1206 +msgid "" +"A convenience method which coerces the *option* in the specified *section* " +"to a Boolean value. Note that the accepted values for the option are " +"``'1'``, ``'yes'``, ``'true'``, and ``'on'``, which cause this method to " +"return ``True``, and ``'0'``, ``'no'``, ``'false'``, and ``'off'``, which " +"cause it to return ``False``. These string values are checked in a case-" +"insensitive manner. Any other value will cause it to " +"raise :exc:`ValueError`. See :meth:`get` for explanation of *raw*, *vars* " +"and *fallback*." +msgstr "" + +#: ../../library/configparser.rst:1219 +msgid "" +"When *section* is not given, return a list of *section_name*, " +"*section_proxy* pairs, including DEFAULTSECT." +msgstr "" + +#: ../../library/configparser.rst:1222 +msgid "" +"Otherwise, return a list of *name*, *value* pairs for the options in the " +"given *section*. Optional arguments have the same meaning as for " +"the :meth:`get` method." +msgstr "" + +#: ../../library/configparser.rst:1226 +msgid "" +"Items present in *vars* no longer appear in the result. The previous " +"behaviour mixed actual parser options with variables provided for " +"interpolation." +msgstr "" + +#: ../../library/configparser.rst:1234 +msgid "" +"If the given section exists, set the given option to the specified value; " +"otherwise raise :exc:`NoSectionError`. *option* and *value* must be " +"strings; if not, :exc:`TypeError` is raised." +msgstr "" + +#: ../../library/configparser.rst:1241 +msgid "" +"Write a representation of the configuration to the specified :term:`file " +"object`, which must be opened in text mode (accepting strings). This " +"representation can be parsed by a future :meth:`read` call. If " +"*space_around_delimiters* is true, delimiters between keys and values are " +"surrounded by spaces." +msgstr "" + +#: ../../library/configparser.rst:1247 +msgid "" +"Raises InvalidWriteError if this would write a representation which cannot " +"be accurately parsed by a future :meth:`read` call from this parser." +msgstr "" + +#: ../../library/configparser.rst:1253 +msgid "" +"Comments in the original configuration file are not preserved when writing " +"the configuration back. What is considered a comment, depends on the given " +"values for *comment_prefix* and *inline_comment_prefix*." +msgstr "" + +#: ../../library/configparser.rst:1261 +msgid "" +"Remove the specified *option* from the specified *section*. If the section " +"does not exist, raise :exc:`NoSectionError`. If the option existed to be " +"removed, return :const:`True`; otherwise return :const:`False`." +msgstr "" + +#: ../../library/configparser.rst:1269 +msgid "" +"Remove the specified *section* from the configuration. If the section in " +"fact existed, return ``True``. Otherwise return ``False``." +msgstr "" + +#: ../../library/configparser.rst:1275 +msgid "" +"Transforms the option name *option* as found in an input file or as passed " +"in by client code to the form that should be used in the internal " +"structures. The default implementation returns a lower-case version of " +"*option*; subclasses may override this or client code can set an attribute " +"of this name on instances to affect this behavior." +msgstr "" + +#: ../../library/configparser.rst:1281 +msgid "" +"You don't need to subclass the parser to use this method, you can also set " +"it on an instance, to a function that takes a string argument and returns a " +"string. Setting it to ``str``, for example, would make option names case " +"sensitive::" +msgstr "" + +#: ../../library/configparser.rst:1286 +msgid "" +"cfgparser = ConfigParser()\n" +"cfgparser.optionxform = str" +msgstr "" +"cfgparser = ConfigParser()\n" +"cfgparser.optionxform = str" + +#: ../../library/configparser.rst:1289 +msgid "" +"Note that when reading configuration files, whitespace around the option " +"names is stripped before :meth:`optionxform` is called." +msgstr "" + +#: ../../library/configparser.rst:1295 +msgid "" +"A special object representing a section name used to reference the unnamed " +"section (see :ref:`unnamed-sections`)." +msgstr "" + +#: ../../library/configparser.rst:1300 +msgid "" +"The maximum depth for recursive interpolation " +"for :meth:`~configparser.ConfigParser.get` when the *raw* parameter is " +"false. This is relevant only when the default *interpolation* is used." +msgstr "" + +#: ../../library/configparser.rst:1308 +msgid "RawConfigParser Objects" +msgstr "RawConfigParser 物件" + +#: ../../library/configparser.rst:1319 +msgid "" +"Legacy variant of the :class:`ConfigParser`. It has interpolation disabled " +"by default and allows for non-string section names, option names, and values " +"via its unsafe ``add_section`` and ``set`` methods, as well as the legacy " +"``defaults=`` keyword argument handling." +msgstr "" + +#: ../../library/configparser.rst:1340 +msgid "" +"Consider using :class:`ConfigParser` instead which checks types of the " +"values to be stored internally. If you don't want interpolation, you can " +"use ``ConfigParser(interpolation=None)``." +msgstr "" + +#: ../../library/configparser.rst:1347 +msgid "" +"Add a section named *section* or :const:`UNNAMED_SECTION` to the instance." +msgstr "" + +#: ../../library/configparser.rst:1349 +msgid "" +"If the given section already exists, :exc:`DuplicateSectionError` is raised. " +"If the *default section* name is passed, :exc:`ValueError` is raised. " +"If :const:`UNNAMED_SECTION` is passed and support is " +"disabled, :exc:`UnnamedSectionDisabledError` is raised." +msgstr "" + +#: ../../library/configparser.rst:1354 +msgid "" +"Type of *section* is not checked which lets users create non-string named " +"sections. This behaviour is unsupported and may cause internal errors." +msgstr "" + +#: ../../library/configparser.rst:1357 +msgid "Added support for :const:`UNNAMED_SECTION`." +msgstr "新增對 :const:`UNNAMED_SECTION` 的支援。" + +#: ../../library/configparser.rst:1363 +msgid "" +"If the given section exists, set the given option to the specified value; " +"otherwise raise :exc:`NoSectionError`. While it is possible to " +"use :class:`RawConfigParser` (or :class:`ConfigParser` with *raw* parameters " +"set to true) for *internal* storage of non-string values, full functionality " +"(including interpolation and output to files) can only be achieved using " +"string values." +msgstr "" + +#: ../../library/configparser.rst:1370 +msgid "" +"This method lets users assign non-string values to keys internally. This " +"behaviour is unsupported and will cause errors when attempting to write to a " +"file or get it in non-raw mode. **Use the mapping protocol API** which does " +"not allow such assignments to take place." +msgstr "" + +#: ../../library/configparser.rst:1377 +msgid "Exceptions" +msgstr "例外" + +#: ../../library/configparser.rst:1381 +msgid "Base class for all other :mod:`configparser` exceptions." +msgstr "" + +#: ../../library/configparser.rst:1386 +msgid "Exception raised when a specified section is not found." +msgstr "" + +#: ../../library/configparser.rst:1391 +msgid "" +"Exception raised if :meth:`~ConfigParser.add_section` is called with the " +"name of a section that is already present or in strict parsers when a " +"section if found more than once in a single input file, string or dictionary." +msgstr "" + +#: ../../library/configparser.rst:1395 +msgid "" +"Added the optional *source* and *lineno* attributes and parameters " +"to :meth:`!__init__`." +msgstr "" + +#: ../../library/configparser.rst:1402 +msgid "" +"Exception raised by strict parsers if a single option appears twice during " +"reading from a single file, string or dictionary. This catches misspellings " +"and case sensitivity-related errors, e.g. a dictionary may have two keys " +"representing the same case-insensitive configuration key." +msgstr "" + +#: ../../library/configparser.rst:1410 +msgid "" +"Exception raised when a specified option is not found in the specified " +"section." +msgstr "" + +#: ../../library/configparser.rst:1416 +msgid "" +"Base class for exceptions raised when problems occur performing string " +"interpolation." +msgstr "" + +#: ../../library/configparser.rst:1422 +msgid "" +"Exception raised when string interpolation cannot be completed because the " +"number of iterations exceeds :const:`MAX_INTERPOLATION_DEPTH`. Subclass " +"of :exc:`InterpolationError`." +msgstr "" + +#: ../../library/configparser.rst:1429 +msgid "" +"Exception raised when an option referenced from a value does not exist. " +"Subclass of :exc:`InterpolationError`." +msgstr "" + +#: ../../library/configparser.rst:1435 +msgid "" +"Exception raised when the source text into which substitutions are made does " +"not conform to the required syntax. Subclass of :exc:`InterpolationError`." +msgstr "" + +#: ../../library/configparser.rst:1441 +msgid "" +"Exception raised when attempting to parse a file which has no section " +"headers." +msgstr "" + +#: ../../library/configparser.rst:1446 +msgid "Exception raised when errors occur attempting to parse a file." +msgstr "" + +#: ../../library/configparser.rst:1448 +msgid "" +"The ``filename`` attribute and :meth:`!__init__` constructor argument were " +"removed. They have been available using the name ``source`` since 3.2." +msgstr "" + +#: ../../library/configparser.rst:1454 +msgid "" +"Exception raised when a key without a corresponding value is continued with " +"an indented line." +msgstr "" + +#: ../../library/configparser.rst:1461 +msgid "" +"Exception raised when attempting to use the :const:`UNNAMED_SECTION` without " +"enabling it." +msgstr "" + +#: ../../library/configparser.rst:1468 +msgid "" +"Exception raised when an attempted :meth:`ConfigParser.write` would not be " +"parsed accurately with a future :meth:`ConfigParser.read` call." +msgstr "" + +#: ../../library/configparser.rst:1471 +msgid "" +"Ex: Writing a key beginning with the :attr:`ConfigParser.SECTCRE` pattern " +"would parse as a section header when read. Attempting to write this will " +"raise this exception." +msgstr "" + +#: ../../library/configparser.rst:1478 +msgid "Footnotes" +msgstr "註腳" + +#: ../../library/configparser.rst:1479 +msgid "" +"Config parsers allow for heavy customization. If you are interested in " +"changing the behaviour outlined by the footnote reference, consult the " +"`Customizing Parser Behaviour`_ section." +msgstr "" + +#: ../../library/configparser.rst:16 +msgid ".ini" +msgstr ".ini" + +#: ../../library/configparser.rst:16 +msgid "file" +msgstr "file（檔案）" + +#: ../../library/configparser.rst:16 +msgid "configuration" +msgstr "configuration（設定）" + +#: ../../library/configparser.rst:16 +msgid "ini file" +msgstr "ini file（ini 檔案）" + +#: ../../library/configparser.rst:16 +msgid "Windows ini file" +msgstr "Windows ini file（Windows ini 檔案）" + +#: ../../library/configparser.rst:367 +msgid "% (percent)" +msgstr "% （百分號）" + +#: ../../library/configparser.rst:367 ../../library/configparser.rst:400 +msgid "interpolation in configuration files" +msgstr "interpolation in configuration files（設定檔中的插值）" + +#: ../../library/configparser.rst:400 +msgid "$ (dollar)" +msgstr "$ （金錢符號）" diff --git a/library/constants.po b/library/constants.po index ec45a2b3ab..982948a4b2 100644 --- a/library/constants.po +++ b/library/constants.po @@ -1,207 +1,207 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Adrian Liaw, 2020 -# Leon H., 2017 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-12 00:14+0000\n" -"PO-Revision-Date: 2021-11-19 23:36+0800\n" -"Last-Translator: Jordan Su \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" -"X-Generator: Poedit 3.0\n" - -#: ../../library/constants.rst:4 -msgid "Built-in Constants" -msgstr "內建常數" - -#: ../../library/constants.rst:6 -msgid "A small number of constants live in the built-in namespace. They are:" -msgstr "有一小部分的常數存在於內建命名空間中。他們是：" - -#: ../../library/constants.rst:10 -msgid "" -"The false value of the :class:`bool` type. Assignments to ``False`` are " -"illegal and raise a :exc:`SyntaxError`." -msgstr "" -"在 :class:`bool` 型別中的 false 值。對於 ``False`` 的賦值是不合法的，並且會拋" -"出 :exc:`SyntaxError`。" - -#: ../../library/constants.rst:16 -msgid "" -"The true value of the :class:`bool` type. Assignments to ``True`` are " -"illegal and raise a :exc:`SyntaxError`." -msgstr "" -"在 :class:`bool` 型別中的 true 值。對於 ``True`` 的賦值是不合法的，並且會拋" -"出 :exc:`SyntaxError`。" - -#: ../../library/constants.rst:22 -msgid "" -"An object frequently used to represent the absence of a value, as when " -"default arguments are not passed to a function. Assignments to ``None`` are " -"illegal and raise a :exc:`SyntaxError`. ``None`` is the sole instance of " -"the :data:`~types.NoneType` type." -msgstr "" -"型別 ``NoneType`` 的唯一值。``None`` 經常被使用來表達缺少值，例如未傳送預設的" -"引數至函式時，相對應參數即會被賦予 ``None``。對於 ``None`` 的賦值是不合法的，" -"並且會拋出 :exc:`SyntaxError`。``None`` 是型別 :data:`~types.NoneType` 的唯一" -"實例。" - -#: ../../library/constants.rst:30 -msgid "" -"A special value which should be returned by the binary special methods (e." -"g. :meth:`~object.__eq__`, :meth:`~object.__lt__`, :meth:`~object.__add__`, :" -"meth:`~object.__rsub__`, etc.) to indicate that the operation is not " -"implemented with respect to the other type; may be returned by the in-place " -"binary special methods (e.g. :meth:`~object.__imul__`, :meth:`~object." -"__iand__`, etc.) for the same purpose. It should not be evaluated in a " -"boolean context. :data:`!NotImplemented` is the sole instance of the :data:" -"`types.NotImplementedType` type." -msgstr "" -"會被二元特殊方法 (binary special methods)（如：:meth:`~object.__eq__`、:meth:" -"`~object.__lt__`、:meth:`~object.__add__`、:meth:`~object.__rsub__` 等）所回" -"傳的特殊值，代表著該運算沒有針對其他型別的實作。同理也可以被原地二元特殊方法 " -"(in-place binary special methods) （如：:meth:`~object.__imul__`、:meth:" -"`~object.__iand__` 等）回傳。它不應該被作為 boolean（布林）來解讀。:data:`!" -"NotImplemented` 是型別 :data:`types.NotImplementedType` 的唯一實例。" - -#: ../../library/constants.rst:40 -msgid "" -"When a binary (or in-place) method returns :data:`!NotImplemented` the " -"interpreter will try the reflected operation on the other type (or some " -"other fallback, depending on the operator). If all attempts return :data:`!" -"NotImplemented`, the interpreter will raise an appropriate exception. " -"Incorrectly returning :data:`!NotImplemented` will result in a misleading " -"error message or the :data:`!NotImplemented` value being returned to Python " -"code." -msgstr "" -"當一個二元 (binary) 或原地 (in-place) 方法回傳 :data:`!NotImplemented`，直譯" -"器會嘗試反映該操作到其他型別（或是其他後備 (fallback)，取決於是哪種運算子）。" -"如果所有的常識都回傳 :data:`!NotImplemented`，直譯器會拋出適當的例外。不正確" -"的回傳 :data:`!NotImplemented` 會造成誤導的錯誤訊息或是 :data:`!" -"NotImplemented` 值被傳回到 Python 程式碼中。" - -#: ../../library/constants.rst:47 -msgid "See :ref:`implementing-the-arithmetic-operations` for examples." -msgstr "請參見 :ref:`implementing-the-arithmetic-operations` 以找到更多範例。" - -#: ../../library/constants.rst:51 -msgid "" -":data:`!NotImplemented` and :exc:`!NotImplementedError` are not " -"interchangeable. This constant should only be used as described above; see :" -"exc:`NotImplementedError` for details on correct usage of the exception." -msgstr "" -":data:`!NotImplemented` 與 :exc:`!NotImplementedError` 並不一樣且不可互換。這" -"個常數只能用於上述的情況；欲知更多如何正確使用它們的細節，請參見 :exc:" -"`NotImplementedError`。" - -#: ../../library/constants.rst:56 -msgid "Evaluating :data:`!NotImplemented` in a boolean context was deprecated." -msgstr "在 boolean（布林）上下文中對 :data:`!NotImplemented` 求值的操作已被棄用。" - -#: ../../library/constants.rst:59 -msgid "" -"Evaluating :data:`!NotImplemented` in a boolean context now raises a :exc:" -"`TypeError`. It previously evaluated to :const:`True` and emitted a :exc:" -"`DeprecationWarning` since Python 3.9." -msgstr "" -"在 boolean 上下文中解讀 :data:`!NotImplemented` 現在會引發 :exc:" -"`TypeError`。過去自 Python 3.9 以來，這會被解讀成 :const:`True`，並發出 :exc:" -"`DeprecationWarning`" - -#: ../../library/constants.rst:68 -msgid "" -"The same as the ellipsis literal \"``...``\", an object frequently used to " -"indicate that something is omitted. Assignment to ``Ellipsis`` is possible, " -"but assignment to ``...`` raises a :exc:`SyntaxError`. ``Ellipsis`` is the " -"sole instance of the :data:`types.EllipsisType` type." -msgstr "" -"與刪節號 \"``...``\" 字面相同，是一個經常被用來表示某些東西被省略的物件。對於 " -"``Ellipsis`` 的賦值是可能的，但對於 ``...`` 的賦值會引發 :exc:`SyntaxError`。" -"``Ellipsis`` 是型別 :data:`types.EllipsisType` 的唯一實例。" - -#: ../../library/constants.rst:76 -msgid "" -"This constant is true if Python was not started with an :option:`-O` option. " -"See also the :keyword:`assert` statement." -msgstr "" -"如果 Python 沒有被以 :option:`-O` 選項啟動，則此常數為 true。請參見 :keyword:" -"`assert` 陳述式。" - -#: ../../library/constants.rst:82 -msgid "" -"The names :data:`None`, :data:`False`, :data:`True` and :data:`__debug__` " -"cannot be reassigned (assignments to them, even as an attribute name, raise :" -"exc:`SyntaxError`), so they can be considered \"true\" constants." -msgstr "" -":data:`None`，:data:`False`，:data:`True`，以及 :data:`__debug__` 都是不能被" -"重新賦值的（任何對它們的賦值，即使是屬性的名稱，也會拋出 :exc:" -"`SyntaxError`）。因此，它們可以被視為”真正的”常數。" - -#: ../../library/constants.rst:90 -msgid "Constants added by the :mod:`site` module" -msgstr "由 :mod:`site` module（模組）所添增的常數" - -#: ../../library/constants.rst:92 -msgid "" -"The :mod:`site` module (which is imported automatically during startup, " -"except if the :option:`-S` command-line option is given) adds several " -"constants to the built-in namespace. They are useful for the interactive " -"interpreter shell and should not be used in programs." -msgstr "" -":mod:`site` module（模組）（在啟動期間自動 import ，除非有給予 :option:`-S` " -"指令行選項）會添增一些常數到內建命名空間 (built-in namespace) 中。它們在互動" -"式直譯器中是很有幫助的，但不應該在程式 (programs) 中被使用。" - -#: ../../library/constants.rst:100 -msgid "" -"Objects that when printed, print a message like \"Use quit() or Ctrl-D (i.e. " -"EOF) to exit\", and when accessed directly in the interactive interpreter or " -"called as functions, raise :exc:`SystemExit` with the specified exit code." -msgstr "" -"當印出物件時，會印出一個訊息：\"Use quit() or Ctrl-D (i.e. EOF) to exit\"。當" -"直接在互動式直譯器中存取或作為函式呼叫時，會引發 :exc:`SystemExit` 並帶有指定" -"的返回碼（exit code）。" - -#: ../../library/constants.rst:108 -msgid "" -"Object that when printed, prints the message \"Type help() for interactive " -"help, or help(object) for help about object.\", and when accessed directly " -"in the interactive interpreter, invokes the built-in help system (see :func:" -"`help`)." -msgstr "" -"當印出此物件時，會印出訊息 \"Type help() for interactive help, or " -"help(object) for help about object.\"，並在互動式直譯器中直接存取時，會叫用內" -"建的幫助系統（參見 :func:`help`）。" - -#: ../../library/constants.rst:116 -msgid "" -"Objects that when printed or called, print the text of copyright or credits, " -"respectively." -msgstr "當印出或是呼叫此物件時，分別會印出版權與致謝的文字。" - -#: ../../library/constants.rst:121 -msgid "" -"Object that when printed, prints the message \"Type license() to see the " -"full license text\", and when called, displays the full license text in a " -"pager-like fashion (one screen at a time)." -msgstr "" -"當印出此物件時，會印出訊息 \"Type license() to see the full license text\"，" -"並在呼叫時以分頁形式印出完整的許可證文字（一次一整個畫面）。" - -#: ../../library/constants.rst:65 -msgid "..." -msgstr "..." - -#: ../../library/constants.rst:65 -msgid "ellipsis literal" -msgstr "ellipsis literal（刪節號字面值）" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Adrian Liaw, 2020 +# Leon H., 2017 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-12 00:14+0000\n" +"PO-Revision-Date: 2021-11-19 23:36+0800\n" +"Last-Translator: Jordan Su \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" +"X-Generator: Poedit 3.0\n" + +#: ../../library/constants.rst:4 +msgid "Built-in Constants" +msgstr "內建常數" + +#: ../../library/constants.rst:6 +msgid "A small number of constants live in the built-in namespace. They are:" +msgstr "有一小部分的常數存在於內建命名空間中。他們是：" + +#: ../../library/constants.rst:10 +msgid "" +"The false value of the :class:`bool` type. Assignments to ``False`` are " +"illegal and raise a :exc:`SyntaxError`." +msgstr "" +"在 :class:`bool` 型別中的 false 值。對於 ``False`` 的賦值是不合法的，並且會拋" +"出 :exc:`SyntaxError`。" + +#: ../../library/constants.rst:16 +msgid "" +"The true value of the :class:`bool` type. Assignments to ``True`` are " +"illegal and raise a :exc:`SyntaxError`." +msgstr "" +"在 :class:`bool` 型別中的 true 值。對於 ``True`` 的賦值是不合法的，並且會拋" +"出 :exc:`SyntaxError`。" + +#: ../../library/constants.rst:22 +msgid "" +"An object frequently used to represent the absence of a value, as when " +"default arguments are not passed to a function. Assignments to ``None`` are " +"illegal and raise a :exc:`SyntaxError`. ``None`` is the sole instance of " +"the :data:`~types.NoneType` type." +msgstr "" +"型別 ``NoneType`` 的唯一值。``None`` 經常被使用來表達缺少值，例如未傳送預設的" +"引數至函式時，相對應參數即會被賦予 ``None``。對於 ``None`` 的賦值是不合法的，" +"並且會拋出 :exc:`SyntaxError`。``None`` 是型別 :data:`~types.NoneType` 的唯一" +"實例。" + +#: ../../library/constants.rst:30 +msgid "" +"A special value which should be returned by the binary special methods (e." +"g. :meth:`~object.__eq__`, :meth:`~object.__lt__`, :meth:`~object.__add__`, :" +"meth:`~object.__rsub__`, etc.) to indicate that the operation is not " +"implemented with respect to the other type; may be returned by the in-place " +"binary special methods (e.g. :meth:`~object.__imul__`, :meth:`~object." +"__iand__`, etc.) for the same purpose. It should not be evaluated in a " +"boolean context. :data:`!NotImplemented` is the sole instance of the :data:" +"`types.NotImplementedType` type." +msgstr "" +"會被二元特殊方法 (binary special methods)（如：:meth:`~object.__eq__`、:meth:" +"`~object.__lt__`、:meth:`~object.__add__`、:meth:`~object.__rsub__` 等）所回" +"傳的特殊值，代表著該運算沒有針對其他型別的實作。同理也可以被原地二元特殊方法 " +"(in-place binary special methods) （如：:meth:`~object.__imul__`、:meth:" +"`~object.__iand__` 等）回傳。它不應該被作為 boolean（布林）來解讀。:data:`!" +"NotImplemented` 是型別 :data:`types.NotImplementedType` 的唯一實例。" + +#: ../../library/constants.rst:40 +msgid "" +"When a binary (or in-place) method returns :data:`!NotImplemented` the " +"interpreter will try the reflected operation on the other type (or some " +"other fallback, depending on the operator). If all attempts return :data:`!" +"NotImplemented`, the interpreter will raise an appropriate exception. " +"Incorrectly returning :data:`!NotImplemented` will result in a misleading " +"error message or the :data:`!NotImplemented` value being returned to Python " +"code." +msgstr "" +"當一個二元 (binary) 或原地 (in-place) 方法回傳 :data:`!NotImplemented`，直譯" +"器會嘗試反映該操作到其他型別（或是其他後備 (fallback)，取決於是哪種運算子）。" +"如果所有的常識都回傳 :data:`!NotImplemented`，直譯器會拋出適當的例外。不正確" +"的回傳 :data:`!NotImplemented` 會造成誤導的錯誤訊息或是 :data:`!" +"NotImplemented` 值被傳回到 Python 程式碼中。" + +#: ../../library/constants.rst:47 +msgid "See :ref:`implementing-the-arithmetic-operations` for examples." +msgstr "請參見 :ref:`implementing-the-arithmetic-operations` 以找到更多範例。" + +#: ../../library/constants.rst:51 +msgid "" +":data:`!NotImplemented` and :exc:`!NotImplementedError` are not " +"interchangeable. This constant should only be used as described above; see :" +"exc:`NotImplementedError` for details on correct usage of the exception." +msgstr "" +":data:`!NotImplemented` 與 :exc:`!NotImplementedError` 並不一樣且不可互換。這" +"個常數只能用於上述的情況；欲知更多如何正確使用它們的細節，請參見 :exc:" +"`NotImplementedError`。" + +#: ../../library/constants.rst:56 +msgid "Evaluating :data:`!NotImplemented` in a boolean context was deprecated." +msgstr "在 boolean（布林）上下文中對 :data:`!NotImplemented` 求值的操作已被棄用。" + +#: ../../library/constants.rst:59 +msgid "" +"Evaluating :data:`!NotImplemented` in a boolean context now raises a :exc:" +"`TypeError`. It previously evaluated to :const:`True` and emitted a :exc:" +"`DeprecationWarning` since Python 3.9." +msgstr "" +"在 boolean 上下文中解讀 :data:`!NotImplemented` 現在會引發 :exc:" +"`TypeError`。過去自 Python 3.9 以來，這會被解讀成 :const:`True`，並發出 :exc:" +"`DeprecationWarning`" + +#: ../../library/constants.rst:68 +msgid "" +"The same as the ellipsis literal \"``...``\", an object frequently used to " +"indicate that something is omitted. Assignment to ``Ellipsis`` is possible, " +"but assignment to ``...`` raises a :exc:`SyntaxError`. ``Ellipsis`` is the " +"sole instance of the :data:`types.EllipsisType` type." +msgstr "" +"與刪節號 \"``...``\" 字面相同，是一個經常被用來表示某些東西被省略的物件。對於 " +"``Ellipsis`` 的賦值是可能的，但對於 ``...`` 的賦值會引發 :exc:`SyntaxError`。" +"``Ellipsis`` 是型別 :data:`types.EllipsisType` 的唯一實例。" + +#: ../../library/constants.rst:76 +msgid "" +"This constant is true if Python was not started with an :option:`-O` option. " +"See also the :keyword:`assert` statement." +msgstr "" +"如果 Python 沒有被以 :option:`-O` 選項啟動，則此常數為 true。請參見 :keyword:" +"`assert` 陳述式。" + +#: ../../library/constants.rst:82 +msgid "" +"The names :data:`None`, :data:`False`, :data:`True` and :data:`__debug__` " +"cannot be reassigned (assignments to them, even as an attribute name, raise :" +"exc:`SyntaxError`), so they can be considered \"true\" constants." +msgstr "" +":data:`None`，:data:`False`，:data:`True`，以及 :data:`__debug__` 都是不能被" +"重新賦值的（任何對它們的賦值，即使是屬性的名稱，也會拋出 :exc:" +"`SyntaxError`）。因此，它們可以被視為”真正的”常數。" + +#: ../../library/constants.rst:90 +msgid "Constants added by the :mod:`site` module" +msgstr "由 :mod:`site` module（模組）所添增的常數" + +#: ../../library/constants.rst:92 +msgid "" +"The :mod:`site` module (which is imported automatically during startup, " +"except if the :option:`-S` command-line option is given) adds several " +"constants to the built-in namespace. They are useful for the interactive " +"interpreter shell and should not be used in programs." +msgstr "" +":mod:`site` module（模組）（在啟動期間自動 import ，除非有給予 :option:`-S` " +"指令行選項）會添增一些常數到內建命名空間 (built-in namespace) 中。它們在互動" +"式直譯器中是很有幫助的，但不應該在程式 (programs) 中被使用。" + +#: ../../library/constants.rst:100 +msgid "" +"Objects that when printed, print a message like \"Use quit() or Ctrl-D (i.e. " +"EOF) to exit\", and when accessed directly in the interactive interpreter or " +"called as functions, raise :exc:`SystemExit` with the specified exit code." +msgstr "" +"當印出物件時，會印出一個訊息：\"Use quit() or Ctrl-D (i.e. EOF) to exit\"。當" +"直接在互動式直譯器中存取或作為函式呼叫時，會引發 :exc:`SystemExit` 並帶有指定" +"的返回碼（exit code）。" + +#: ../../library/constants.rst:108 +msgid "" +"Object that when printed, prints the message \"Type help() for interactive " +"help, or help(object) for help about object.\", and when accessed directly " +"in the interactive interpreter, invokes the built-in help system (see :func:" +"`help`)." +msgstr "" +"當印出此物件時，會印出訊息 \"Type help() for interactive help, or " +"help(object) for help about object.\"，並在互動式直譯器中直接存取時，會叫用內" +"建的幫助系統（參見 :func:`help`）。" + +#: ../../library/constants.rst:116 +msgid "" +"Objects that when printed or called, print the text of copyright or credits, " +"respectively." +msgstr "當印出或是呼叫此物件時，分別會印出版權與致謝的文字。" + +#: ../../library/constants.rst:121 +msgid "" +"Object that when printed, prints the message \"Type license() to see the " +"full license text\", and when called, displays the full license text in a " +"pager-like fashion (one screen at a time)." +msgstr "" +"當印出此物件時，會印出訊息 \"Type license() to see the full license text\"，" +"並在呼叫時以分頁形式印出完整的許可證文字（一次一整個畫面）。" + +#: ../../library/constants.rst:65 +msgid "..." +msgstr "..." + +#: ../../library/constants.rst:65 +msgid "ellipsis literal" +msgstr "ellipsis literal（刪節號字面值）" diff --git a/library/contextlib.po b/library/contextlib.po index 95c6fea015..17eed4b32d 100644 --- a/library/contextlib.po +++ b/library/contextlib.po @@ -1,1676 +1,1676 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-04-11 00:15+0000\n" -"PO-Revision-Date: 2018-05-23 14:41+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/contextlib.rst:2 -msgid "" -":mod:`!contextlib` --- Utilities for :keyword:`!with`\\ -statement contexts" -msgstr ":mod:`!contextlib` --- :keyword:`!with` 陳述式工具程式" - -#: ../../library/contextlib.rst:7 -msgid "**Source code:** :source:`Lib/contextlib.py`" -msgstr "**原始碼：**\\ :source:`Lib/contextlib.py`" - -#: ../../library/contextlib.rst:11 -msgid "" -"This module provides utilities for common tasks involving " -"the :keyword:`with` statement. For more information see " -"also :ref:`typecontextmanager` and :ref:`context-managers`." -msgstr "" - -#: ../../library/contextlib.rst:17 -msgid "Utilities" -msgstr "" - -#: ../../library/contextlib.rst:19 -msgid "Functions and classes provided:" -msgstr "" - -#: ../../library/contextlib.rst:23 -msgid "" -"An :term:`abstract base class` for classes that " -"implement :meth:`object.__enter__` and :meth:`object.__exit__`. A default " -"implementation for :meth:`object.__enter__` is provided which returns " -"``self`` while :meth:`object.__exit__` is an abstract method which by " -"default returns ``None``. See also the definition " -"of :ref:`typecontextmanager`." -msgstr "" - -#: ../../library/contextlib.rst:34 -msgid "" -"An :term:`abstract base class` for classes that " -"implement :meth:`object.__aenter__` and :meth:`object.__aexit__`. A default " -"implementation for :meth:`object.__aenter__` is provided which returns " -"``self`` while :meth:`object.__aexit__` is an abstract method which by " -"default returns ``None``. See also the definition of :ref:`async-context-" -"managers`." -msgstr "" - -#: ../../library/contextlib.rst:46 -msgid "" -"This function is a :term:`decorator` that can be used to define a factory " -"function for :keyword:`with` statement context managers, without needing to " -"create a class or separate :meth:`~object.__enter__` " -"and :meth:`~object.__exit__` methods." -msgstr "" - -#: ../../library/contextlib.rst:50 -msgid "" -"While many objects natively support use in with statements, sometimes a " -"resource needs to be managed that isn't a context manager in its own right, " -"and doesn't implement a ``close()`` method for use with " -"``contextlib.closing``." -msgstr "" - -#: ../../library/contextlib.rst:54 -msgid "" -"An abstract example would be the following to ensure correct resource " -"management::" -msgstr "" - -#: ../../library/contextlib.rst:57 -msgid "" -"from contextlib import contextmanager\n" -"\n" -"@contextmanager\n" -"def managed_resource(*args, **kwds):\n" -" # Code to acquire resource, e.g.:\n" -" resource = acquire_resource(*args, **kwds)\n" -" try:\n" -" yield resource\n" -" finally:\n" -" # Code to release resource, e.g.:\n" -" release_resource(resource)" -msgstr "" - -#: ../../library/contextlib.rst:69 -msgid "The function can then be used like this::" -msgstr "" - -#: ../../library/contextlib.rst:71 -msgid "" -">>> with managed_resource(timeout=3600) as resource:\n" -"... # Resource is released at the end of this block,\n" -"... # even if code in the block raises an exception" -msgstr "" - -#: ../../library/contextlib.rst:75 -msgid "" -"The function being decorated must return a :term:`generator`-iterator when " -"called. This iterator must yield exactly one value, which will be bound to " -"the targets in the :keyword:`with` statement's :keyword:`!as` clause, if any." -msgstr "" - -#: ../../library/contextlib.rst:79 -msgid "" -"At the point where the generator yields, the block nested in " -"the :keyword:`with` statement is executed. The generator is then resumed " -"after the block is exited. If an unhandled exception occurs in the block, it " -"is reraised inside the generator at the point where the yield occurred. " -"Thus, you can use a :keyword:`try`...\\ :keyword:`except`..." -"\\ :keyword:`finally` statement to trap the error (if any), or ensure that " -"some cleanup takes place. If an exception is trapped merely in order to log " -"it or to perform some action (rather than to suppress it entirely), the " -"generator must reraise that exception. Otherwise the generator context " -"manager will indicate to the :keyword:`!with` statement that the exception " -"has been handled, and execution will resume with the statement immediately " -"following the :keyword:`!with` statement." -msgstr "" - -#: ../../library/contextlib.rst:91 -msgid "" -":func:`contextmanager` uses :class:`ContextDecorator` so the context " -"managers it creates can be used as decorators as well as in :keyword:`with` " -"statements. When used as a decorator, a new generator instance is implicitly " -"created on each function call (this allows the otherwise \"one-shot\" " -"context managers created by :func:`contextmanager` to meet the requirement " -"that context managers support multiple invocations in order to be used as " -"decorators)." -msgstr "" - -#: ../../library/contextlib.rst:98 -msgid "Use of :class:`ContextDecorator`." -msgstr "" - -#: ../../library/contextlib.rst:104 -msgid "" -"Similar to :func:`~contextlib.contextmanager`, but creates " -"an :ref:`asynchronous context manager `." -msgstr "" - -#: ../../library/contextlib.rst:107 -msgid "" -"This function is a :term:`decorator` that can be used to define a factory " -"function for :keyword:`async with` statement asynchronous context managers, " -"without needing to create a class or separate :meth:`~object.__aenter__` " -"and :meth:`~object.__aexit__` methods. It must be applied to " -"an :term:`asynchronous generator` function." -msgstr "" - -#: ../../library/contextlib.rst:113 -msgid "A simple example::" -msgstr "一個簡單範例： ::" - -#: ../../library/contextlib.rst:115 -msgid "" -"from contextlib import asynccontextmanager\n" -"\n" -"@asynccontextmanager\n" -"async def get_connection():\n" -" conn = await acquire_db_connection()\n" -" try:\n" -" yield conn\n" -" finally:\n" -" await release_db_connection(conn)\n" -"\n" -"async def get_all_users():\n" -" async with get_connection() as conn:\n" -" return conn.query('SELECT ...')" -msgstr "" -"from contextlib import asynccontextmanager\n" -"\n" -"@asynccontextmanager\n" -"async def get_connection():\n" -" conn = await acquire_db_connection()\n" -" try:\n" -" yield conn\n" -" finally:\n" -" await release_db_connection(conn)\n" -"\n" -"async def get_all_users():\n" -" async with get_connection() as conn:\n" -" return conn.query('SELECT ...')" - -#: ../../library/contextlib.rst:131 -msgid "" -"Context managers defined with :func:`asynccontextmanager` can be used either " -"as decorators or with :keyword:`async with` statements::" -msgstr "" - -#: ../../library/contextlib.rst:134 -msgid "" -"import time\n" -"from contextlib import asynccontextmanager\n" -"\n" -"@asynccontextmanager\n" -"async def timeit():\n" -" now = time.monotonic()\n" -" try:\n" -" yield\n" -" finally:\n" -" print(f'it took {time.monotonic() - now}s to run')\n" -"\n" -"@timeit()\n" -"async def main():\n" -" # ... async code ..." -msgstr "" - -#: ../../library/contextlib.rst:149 -msgid "" -"When used as a decorator, a new generator instance is implicitly created on " -"each function call. This allows the otherwise \"one-shot\" context managers " -"created by :func:`asynccontextmanager` to meet the requirement that context " -"managers support multiple invocations in order to be used as decorators." -msgstr "" - -#: ../../library/contextlib.rst:154 -msgid "" -"Async context managers created with :func:`asynccontextmanager` can be used " -"as decorators." -msgstr "" - -#: ../../library/contextlib.rst:161 -msgid "" -"Return a context manager that closes *thing* upon completion of the block. " -"This is basically equivalent to::" -msgstr "" - -#: ../../library/contextlib.rst:164 -msgid "" -"from contextlib import contextmanager\n" -"\n" -"@contextmanager\n" -"def closing(thing):\n" -" try:\n" -" yield thing\n" -" finally:\n" -" thing.close()" -msgstr "" -"from contextlib import contextmanager\n" -"\n" -"@contextmanager\n" -"def closing(thing):\n" -" try:\n" -" yield thing\n" -" finally:\n" -" thing.close()" - -#: ../../library/contextlib.rst:173 -msgid "And lets you write code like this::" -msgstr "" - -#: ../../library/contextlib.rst:175 -msgid "" -"from contextlib import closing\n" -"from urllib.request import urlopen\n" -"\n" -"with closing(urlopen('https://www.python.org')) as page:\n" -" for line in page:\n" -" print(line)" -msgstr "" -"from contextlib import closing\n" -"from urllib.request import urlopen\n" -"\n" -"with closing(urlopen('https://www.python.org')) as page:\n" -" for line in page:\n" -" print(line)" - -#: ../../library/contextlib.rst:182 -msgid "" -"without needing to explicitly close ``page``. Even if an error occurs, " -"``page.close()`` will be called when the :keyword:`with` block is exited." -msgstr "" - -#: ../../library/contextlib.rst:187 -msgid "" -"Most types managing resources support the :term:`context manager` protocol, " -"which closes *thing* on leaving the :keyword:`with` statement. As " -"such, :func:`!closing` is most useful for third party types that don't " -"support context managers. This example is purely for illustration purposes, " -"as :func:`~urllib.request.urlopen` would normally be used in a context " -"manager." -msgstr "" - -#: ../../library/contextlib.rst:196 -msgid "" -"Return an async context manager that calls the ``aclose()`` method of " -"*thing* upon completion of the block. This is basically equivalent to::" -msgstr "" - -#: ../../library/contextlib.rst:199 -msgid "" -"from contextlib import asynccontextmanager\n" -"\n" -"@asynccontextmanager\n" -"async def aclosing(thing):\n" -" try:\n" -" yield thing\n" -" finally:\n" -" await thing.aclose()" -msgstr "" -"from contextlib import asynccontextmanager\n" -"\n" -"@asynccontextmanager\n" -"async def aclosing(thing):\n" -" try:\n" -" yield thing\n" -" finally:\n" -" await thing.aclose()" - -#: ../../library/contextlib.rst:208 -msgid "" -"Significantly, ``aclosing()`` supports deterministic cleanup of async " -"generators when they happen to exit early by :keyword:`break` or an " -"exception. For example::" -msgstr "" - -#: ../../library/contextlib.rst:212 -msgid "" -"from contextlib import aclosing\n" -"\n" -"async with aclosing(my_generator()) as values:\n" -" async for value in values:\n" -" if value == 42:\n" -" break" -msgstr "" -"from contextlib import aclosing\n" -"\n" -"async with aclosing(my_generator()) as values:\n" -" async for value in values:\n" -" if value == 42:\n" -" break" - -#: ../../library/contextlib.rst:219 -msgid "" -"This pattern ensures that the generator's async exit code is executed in the " -"same context as its iterations (so that exceptions and context variables " -"work as expected, and the exit code isn't run after the lifetime of some " -"task it depends on)." -msgstr "" - -#: ../../library/contextlib.rst:231 -msgid "" -"Return a context manager that returns *enter_result* from ``__enter__``, but " -"otherwise does nothing. It is intended to be used as a stand-in for an " -"optional context manager, for example::" -msgstr "" - -#: ../../library/contextlib.rst:235 -msgid "" -"def myfunction(arg, ignore_exceptions=False):\n" -" if ignore_exceptions:\n" -" # Use suppress to ignore all exceptions.\n" -" cm = contextlib.suppress(Exception)\n" -" else:\n" -" # Do not ignore any exceptions, cm has no effect.\n" -" cm = contextlib.nullcontext()\n" -" with cm:\n" -" # Do something" -msgstr "" - -#: ../../library/contextlib.rst:245 -msgid "An example using *enter_result*::" -msgstr "一個使用 *enter_result* 的範例： ::" - -#: ../../library/contextlib.rst:247 -msgid "" -"def process_file(file_or_path):\n" -" if isinstance(file_or_path, str):\n" -" # If string, open file\n" -" cm = open(file_or_path)\n" -" else:\n" -" # Caller is responsible for closing file\n" -" cm = nullcontext(file_or_path)\n" -"\n" -" with cm as file:\n" -" # Perform processing on the file" -msgstr "" - -#: ../../library/contextlib.rst:258 -msgid "" -"It can also be used as a stand-in for :ref:`asynchronous context managers " -"`::" -msgstr "" - -#: ../../library/contextlib.rst:261 -msgid "" -"async def send_http(session=None):\n" -" if not session:\n" -" # If no http session, create it with aiohttp\n" -" cm = aiohttp.ClientSession()\n" -" else:\n" -" # Caller is responsible for closing the session\n" -" cm = nullcontext(session)\n" -"\n" -" async with cm as session:\n" -" # Send http requests with session" -msgstr "" - -#: ../../library/contextlib.rst:274 -msgid ":term:`asynchronous context manager` support was added." -msgstr "" - -#: ../../library/contextlib.rst:281 -msgid "" -"Return a context manager that suppresses any of the specified exceptions if " -"they occur in the body of a :keyword:`!with` statement and then resumes " -"execution with the first statement following the end of the :keyword:`!with` " -"statement." -msgstr "" - -#: ../../library/contextlib.rst:286 -msgid "" -"As with any other mechanism that completely suppresses exceptions, this " -"context manager should be used only to cover very specific errors where " -"silently continuing with program execution is known to be the right thing to " -"do." -msgstr "" - -#: ../../library/contextlib.rst:291 -msgid "For example::" -msgstr "舉例來說： ::" - -#: ../../library/contextlib.rst:293 -msgid "" -"from contextlib import suppress\n" -"\n" -"with suppress(FileNotFoundError):\n" -" os.remove('somefile.tmp')\n" -"\n" -"with suppress(FileNotFoundError):\n" -" os.remove('someotherfile.tmp')" -msgstr "" -"from contextlib import suppress\n" -"\n" -"with suppress(FileNotFoundError):\n" -" os.remove('somefile.tmp')\n" -"\n" -"with suppress(FileNotFoundError):\n" -" os.remove('someotherfile.tmp')" - -#: ../../library/contextlib.rst:301 -msgid "This code is equivalent to::" -msgstr "" - -#: ../../library/contextlib.rst:303 -msgid "" -"try:\n" -" os.remove('somefile.tmp')\n" -"except FileNotFoundError:\n" -" pass\n" -"\n" -"try:\n" -" os.remove('someotherfile.tmp')\n" -"except FileNotFoundError:\n" -" pass" -msgstr "" -"try:\n" -" os.remove('somefile.tmp')\n" -"except FileNotFoundError:\n" -" pass\n" -"\n" -"try:\n" -" os.remove('someotherfile.tmp')\n" -"except FileNotFoundError:\n" -" pass" - -#: ../../library/contextlib.rst:313 ../../library/contextlib.rst:362 -#: ../../library/contextlib.rst:372 ../../library/contextlib.rst:389 -msgid "This context manager is :ref:`reentrant `." -msgstr "" - -#: ../../library/contextlib.rst:315 -msgid "" -"If the code within the :keyword:`!with` block raises " -"a :exc:`BaseExceptionGroup`, suppressed exceptions are removed from the " -"group. Any exceptions of the group which are not suppressed are re-raised " -"in a new group which is created using the original " -"group's :meth:`~BaseExceptionGroup.derive` method." -msgstr "" - -#: ../../library/contextlib.rst:323 -msgid "" -"``suppress`` now supports suppressing exceptions raised as part of " -"a :exc:`BaseExceptionGroup`." -msgstr "" - -#: ../../library/contextlib.rst:329 -msgid "" -"Context manager for temporarily redirecting :data:`sys.stdout` to another " -"file or file-like object." -msgstr "" - -#: ../../library/contextlib.rst:332 -msgid "" -"This tool adds flexibility to existing functions or classes whose output is " -"hardwired to stdout." -msgstr "" - -#: ../../library/contextlib.rst:335 -msgid "" -"For example, the output of :func:`help` normally is sent to *sys.stdout*. " -"You can capture that output in a string by redirecting the output to " -"an :class:`io.StringIO` object. The replacement stream is returned from the " -"``__enter__`` method and so is available as the target of " -"the :keyword:`with` statement::" -msgstr "" - -#: ../../library/contextlib.rst:341 -msgid "" -"with redirect_stdout(io.StringIO()) as f:\n" -" help(pow)\n" -"s = f.getvalue()" -msgstr "" -"with redirect_stdout(io.StringIO()) as f:\n" -" help(pow)\n" -"s = f.getvalue()" - -#: ../../library/contextlib.rst:345 -msgid "" -"To send the output of :func:`help` to a file on disk, redirect the output to " -"a regular file::" -msgstr "" - -#: ../../library/contextlib.rst:348 -msgid "" -"with open('help.txt', 'w') as f:\n" -" with redirect_stdout(f):\n" -" help(pow)" -msgstr "" -"with open('help.txt', 'w') as f:\n" -" with redirect_stdout(f):\n" -" help(pow)" - -#: ../../library/contextlib.rst:352 -msgid "To send the output of :func:`help` to *sys.stderr*::" -msgstr "" - -#: ../../library/contextlib.rst:354 -msgid "" -"with redirect_stdout(sys.stderr):\n" -" help(pow)" -msgstr "" -"with redirect_stdout(sys.stderr):\n" -" help(pow)" - -#: ../../library/contextlib.rst:357 -msgid "" -"Note that the global side effect on :data:`sys.stdout` means that this " -"context manager is not suitable for use in library code and most threaded " -"applications. It also has no effect on the output of subprocesses. However, " -"it is still a useful approach for many utility scripts." -msgstr "" - -#: ../../library/contextlib.rst:369 -msgid "" -"Similar to :func:`~contextlib.redirect_stdout` but " -"redirecting :data:`sys.stderr` to another file or file-like object." -msgstr "" - -#: ../../library/contextlib.rst:379 -msgid "" -"Non parallel-safe context manager to change the current working directory. " -"As this changes a global state, the working directory, it is not suitable " -"for use in most threaded or async contexts. It is also not suitable for most " -"non-linear code execution, like generators, where the program execution is " -"temporarily relinquished -- unless explicitly desired, you should not yield " -"when this context manager is active." -msgstr "" - -#: ../../library/contextlib.rst:386 -msgid "" -"This is a simple wrapper around :func:`~os.chdir`, it changes the current " -"working directory upon entering and restores the old one on exit." -msgstr "" - -#: ../../library/contextlib.rst:396 -msgid "" -"A base class that enables a context manager to also be used as a decorator." -msgstr "" - -#: ../../library/contextlib.rst:398 -msgid "" -"Context managers inheriting from ``ContextDecorator`` have to implement " -"``__enter__`` and ``__exit__`` as normal. ``__exit__`` retains its optional " -"exception handling even when used as a decorator." -msgstr "" - -#: ../../library/contextlib.rst:402 -msgid "" -"``ContextDecorator`` is used by :func:`contextmanager`, so you get this " -"functionality automatically." -msgstr "" - -#: ../../library/contextlib.rst:405 -msgid "Example of ``ContextDecorator``::" -msgstr "``ContextDecorator`` 範例： ::" - -#: ../../library/contextlib.rst:407 -msgid "" -"from contextlib import ContextDecorator\n" -"\n" -"class mycontext(ContextDecorator):\n" -" def __enter__(self):\n" -" print('Starting')\n" -" return self\n" -"\n" -" def __exit__(self, *exc):\n" -" print('Finishing')\n" -" return False" -msgstr "" -"from contextlib import ContextDecorator\n" -"\n" -"class mycontext(ContextDecorator):\n" -" def __enter__(self):\n" -" print('Starting')\n" -" return self\n" -"\n" -" def __exit__(self, *exc):\n" -" print('Finishing')\n" -" return False" - -#: ../../library/contextlib.rst:418 ../../library/contextlib.rst:490 -msgid "The class can then be used like this::" -msgstr "這個類別可以這樣使用： ::" - -#: ../../library/contextlib.rst:420 -msgid "" -">>> @mycontext()\n" -"... def function():\n" -"... print('The bit in the middle')\n" -"...\n" -">>> function()\n" -"Starting\n" -"The bit in the middle\n" -"Finishing\n" -"\n" -">>> with mycontext():\n" -"... print('The bit in the middle')\n" -"...\n" -"Starting\n" -"The bit in the middle\n" -"Finishing" -msgstr "" -">>> @mycontext()\n" -"... def function():\n" -"... print('The bit in the middle')\n" -"...\n" -">>> function()\n" -"Starting\n" -"The bit in the middle\n" -"Finishing\n" -"\n" -">>> with mycontext():\n" -"... print('The bit in the middle')\n" -"...\n" -"Starting\n" -"The bit in the middle\n" -"Finishing" - -#: ../../library/contextlib.rst:436 -msgid "" -"This change is just syntactic sugar for any construct of the following form::" -msgstr "這個變更只是以下形式的語法糖： ::" - -#: ../../library/contextlib.rst:438 -msgid "" -"def f():\n" -" with cm():\n" -" # Do stuff" -msgstr "" -"def f():\n" -" with cm():\n" -" # Do stuff" - -#: ../../library/contextlib.rst:442 -msgid "``ContextDecorator`` lets you instead write::" -msgstr "``ContextDecorator`` 讓你可以改寫成： ::" - -#: ../../library/contextlib.rst:444 -msgid "" -"@cm()\n" -"def f():\n" -" # Do stuff" -msgstr "" -"@cm()\n" -"def f():\n" -" # Do stuff" - -#: ../../library/contextlib.rst:448 -msgid "" -"It makes it clear that the ``cm`` applies to the whole function, rather than " -"just a piece of it (and saving an indentation level is nice, too)." -msgstr "" - -#: ../../library/contextlib.rst:451 -msgid "" -"Existing context managers that already have a base class can be extended by " -"using ``ContextDecorator`` as a mixin class::" -msgstr "" - -#: ../../library/contextlib.rst:454 -msgid "" -"from contextlib import ContextDecorator\n" -"\n" -"class mycontext(ContextBaseClass, ContextDecorator):\n" -" def __enter__(self):\n" -" return self\n" -"\n" -" def __exit__(self, *exc):\n" -" return False" -msgstr "" -"from contextlib import ContextDecorator\n" -"\n" -"class mycontext(ContextBaseClass, ContextDecorator):\n" -" def __enter__(self):\n" -" return self\n" -"\n" -" def __exit__(self, *exc):\n" -" return False" - -#: ../../library/contextlib.rst:464 -msgid "" -"As the decorated function must be able to be called multiple times, the " -"underlying context manager must support use in multiple :keyword:`with` " -"statements. If this is not the case, then the original construct with the " -"explicit :keyword:`!with` statement inside the function should be used." -msgstr "" - -#: ../../library/contextlib.rst:474 -msgid "" -"Similar to :class:`ContextDecorator` but only for asynchronous functions." -msgstr "和 :class:`ContextDecorator` 類似，但僅用於非同步函式。" - -#: ../../library/contextlib.rst:476 -msgid "Example of ``AsyncContextDecorator``::" -msgstr "``AsyncContextDecorator`` 範例： ::" - -#: ../../library/contextlib.rst:478 -msgid "" -"from asyncio import run\n" -"from contextlib import AsyncContextDecorator\n" -"\n" -"class mycontext(AsyncContextDecorator):\n" -" async def __aenter__(self):\n" -" print('Starting')\n" -" return self\n" -"\n" -" async def __aexit__(self, *exc):\n" -" print('Finishing')\n" -" return False" -msgstr "" -"from asyncio import run\n" -"from contextlib import AsyncContextDecorator\n" -"\n" -"class mycontext(AsyncContextDecorator):\n" -" async def __aenter__(self):\n" -" print('Starting')\n" -" return self\n" -"\n" -" async def __aexit__(self, *exc):\n" -" print('Finishing')\n" -" return False" - -#: ../../library/contextlib.rst:492 -msgid "" -">>> @mycontext()\n" -"... async def function():\n" -"... print('The bit in the middle')\n" -"...\n" -">>> run(function())\n" -"Starting\n" -"The bit in the middle\n" -"Finishing\n" -"\n" -">>> async def function():\n" -"... async with mycontext():\n" -"... print('The bit in the middle')\n" -"...\n" -">>> run(function())\n" -"Starting\n" -"The bit in the middle\n" -"Finishing" -msgstr "" -">>> @mycontext()\n" -"... async def function():\n" -"... print('The bit in the middle')\n" -"...\n" -">>> run(function())\n" -"Starting\n" -"The bit in the middle\n" -"Finishing\n" -"\n" -">>> async def function():\n" -"... async with mycontext():\n" -"... print('The bit in the middle')\n" -"...\n" -">>> run(function())\n" -"Starting\n" -"The bit in the middle\n" -"Finishing" - -#: ../../library/contextlib.rst:515 -msgid "" -"A context manager that is designed to make it easy to programmatically " -"combine other context managers and cleanup functions, especially those that " -"are optional or otherwise driven by input data." -msgstr "" - -#: ../../library/contextlib.rst:519 -msgid "" -"For example, a set of files may easily be handled in a single with statement " -"as follows::" -msgstr "" - -#: ../../library/contextlib.rst:522 -msgid "" -"with ExitStack() as stack:\n" -" files = [stack.enter_context(open(fname)) for fname in filenames]\n" -" # All opened files will automatically be closed at the end of\n" -" # the with statement, even if attempts to open files later\n" -" # in the list raise an exception" -msgstr "" - -#: ../../library/contextlib.rst:528 -msgid "" -"The :meth:`~object.__enter__` method returns the :class:`ExitStack` " -"instance, and performs no additional operations." -msgstr "" - -#: ../../library/contextlib.rst:531 -msgid "" -"Each instance maintains a stack of registered callbacks that are called in " -"reverse order when the instance is closed (either explicitly or implicitly " -"at the end of a :keyword:`with` statement). Note that callbacks are *not* " -"invoked implicitly when the context stack instance is garbage collected." -msgstr "" - -#: ../../library/contextlib.rst:536 -msgid "" -"This stack model is used so that context managers that acquire their " -"resources in their ``__init__`` method (such as file objects) can be handled " -"correctly." -msgstr "" - -#: ../../library/contextlib.rst:540 -msgid "" -"Since registered callbacks are invoked in the reverse order of registration, " -"this ends up behaving as if multiple nested :keyword:`with` statements had " -"been used with the registered set of callbacks. This even extends to " -"exception handling - if an inner callback suppresses or replaces an " -"exception, then outer callbacks will be passed arguments based on that " -"updated state." -msgstr "" - -#: ../../library/contextlib.rst:547 -msgid "" -"This is a relatively low level API that takes care of the details of " -"correctly unwinding the stack of exit callbacks. It provides a suitable " -"foundation for higher level context managers that manipulate the exit stack " -"in application specific ways." -msgstr "" - -#: ../../library/contextlib.rst:556 -msgid "" -"Enters a new context manager and adds its :meth:`~object.__exit__` method to " -"the callback stack. The return value is the result of the context manager's " -"own :meth:`~object.__enter__` method." -msgstr "" - -#: ../../library/contextlib.rst:560 -msgid "" -"These context managers may suppress exceptions just as they normally would " -"if used directly as part of a :keyword:`with` statement." -msgstr "" - -#: ../../library/contextlib.rst:563 -msgid "" -"Raises :exc:`TypeError` instead of :exc:`AttributeError` if *cm* is not a " -"context manager." -msgstr "" - -#: ../../library/contextlib.rst:569 -msgid "" -"Adds a context manager's :meth:`~object.__exit__` method to the callback " -"stack." -msgstr "" - -#: ../../library/contextlib.rst:571 -msgid "" -"As ``__enter__`` is *not* invoked, this method can be used to cover part of " -"an :meth:`~object.__enter__` implementation with a context manager's " -"own :meth:`~object.__exit__` method." -msgstr "" - -#: ../../library/contextlib.rst:575 -msgid "" -"If passed an object that is not a context manager, this method assumes it is " -"a callback with the same signature as a context " -"manager's :meth:`~object.__exit__` method and adds it directly to the " -"callback stack." -msgstr "" - -#: ../../library/contextlib.rst:579 -msgid "" -"By returning true values, these callbacks can suppress exceptions the same " -"way context manager :meth:`~object.__exit__` methods can." -msgstr "" - -#: ../../library/contextlib.rst:582 -msgid "" -"The passed in object is returned from the function, allowing this method to " -"be used as a function decorator." -msgstr "" - -#: ../../library/contextlib.rst:587 -msgid "" -"Accepts an arbitrary callback function and arguments and adds it to the " -"callback stack." -msgstr "" - -#: ../../library/contextlib.rst:590 -msgid "" -"Unlike the other methods, callbacks added this way cannot suppress " -"exceptions (as they are never passed the exception details)." -msgstr "" - -#: ../../library/contextlib.rst:593 -msgid "" -"The passed in callback is returned from the function, allowing this method " -"to be used as a function decorator." -msgstr "" - -#: ../../library/contextlib.rst:598 -msgid "" -"Transfers the callback stack to a fresh :class:`ExitStack` instance and " -"returns it. No callbacks are invoked by this operation - instead, they will " -"now be invoked when the new stack is closed (either explicitly or implicitly " -"at the end of a :keyword:`with` statement)." -msgstr "" - -#: ../../library/contextlib.rst:603 -msgid "" -"For example, a group of files can be opened as an \"all or nothing\" " -"operation as follows::" -msgstr "" - -#: ../../library/contextlib.rst:606 -msgid "" -"with ExitStack() as stack:\n" -" files = [stack.enter_context(open(fname)) for fname in filenames]\n" -" # Hold onto the close method, but don't call it yet.\n" -" close_files = stack.pop_all().close\n" -" # If opening any file fails, all previously opened files will be\n" -" # closed automatically. If all files are opened successfully,\n" -" # they will remain open even after the with statement ends.\n" -" # close_files() can then be invoked explicitly to close them all." -msgstr "" - -#: ../../library/contextlib.rst:617 -msgid "" -"Immediately unwinds the callback stack, invoking callbacks in the reverse " -"order of registration. For any context managers and exit callbacks " -"registered, the arguments passed in will indicate that no exception occurred." -msgstr "" - -#: ../../library/contextlib.rst:624 -msgid "" -"An :ref:`asynchronous context manager `, similar " -"to :class:`ExitStack`, that supports combining both synchronous and " -"asynchronous context managers, as well as having coroutines for cleanup " -"logic." -msgstr "" - -#: ../../library/contextlib.rst:629 -msgid "" -"The :meth:`~ExitStack.close` method is not implemented; :meth:`aclose` must " -"be used instead." -msgstr "" - -#: ../../library/contextlib.rst:635 -msgid "" -"Similar to :meth:`ExitStack.enter_context` but expects an asynchronous " -"context manager." -msgstr "" - -#: ../../library/contextlib.rst:638 -msgid "" -"Raises :exc:`TypeError` instead of :exc:`AttributeError` if *cm* is not an " -"asynchronous context manager." -msgstr "" - -#: ../../library/contextlib.rst:644 -msgid "" -"Similar to :meth:`ExitStack.push` but expects either an asynchronous context " -"manager or a coroutine function." -msgstr "" - -#: ../../library/contextlib.rst:649 -msgid "Similar to :meth:`ExitStack.callback` but expects a coroutine function." -msgstr "和 :meth:`ExitStack.callback` 類似，但預期接受一個協程函式。" - -#: ../../library/contextlib.rst:654 -msgid "Similar to :meth:`ExitStack.close` but properly handles awaitables." -msgstr "和 :meth:`ExitStack.close` 類似，但能夠正確處理可等待物件。" - -#: ../../library/contextlib.rst:656 -msgid "Continuing the example for :func:`asynccontextmanager`::" -msgstr "延續 :func:`asynccontextmanager` 的範例： ::" - -#: ../../library/contextlib.rst:658 -msgid "" -"async with AsyncExitStack() as stack:\n" -" connections = [await stack.enter_async_context(get_connection())\n" -" for i in range(5)]\n" -" # All opened connections will automatically be released at the end of\n" -" # the async with statement, even if attempts to open a connection\n" -" # later in the list raise an exception." -msgstr "" - -#: ../../library/contextlib.rst:668 -msgid "Examples and Recipes" -msgstr "" - -#: ../../library/contextlib.rst:670 -msgid "" -"This section describes some examples and recipes for making effective use of " -"the tools provided by :mod:`contextlib`." -msgstr "" - -#: ../../library/contextlib.rst:675 -msgid "Supporting a variable number of context managers" -msgstr "" - -#: ../../library/contextlib.rst:677 -msgid "" -"The primary use case for :class:`ExitStack` is the one given in the class " -"documentation: supporting a variable number of context managers and other " -"cleanup operations in a single :keyword:`with` statement. The variability " -"may come from the number of context managers needed being driven by user " -"input (such as opening a user specified collection of files), or from some " -"of the context managers being optional::" -msgstr "" - -#: ../../library/contextlib.rst:684 -msgid "" -"with ExitStack() as stack:\n" -" for resource in resources:\n" -" stack.enter_context(resource)\n" -" if need_special_resource():\n" -" special = acquire_special_resource()\n" -" stack.callback(release_special_resource, special)\n" -" # Perform operations that use the acquired resources" -msgstr "" - -#: ../../library/contextlib.rst:692 -msgid "" -"As shown, :class:`ExitStack` also makes it quite easy to use :keyword:`with` " -"statements to manage arbitrary resources that don't natively support the " -"context management protocol." -msgstr "" - -#: ../../library/contextlib.rst:698 -msgid "Catching exceptions from ``__enter__`` methods" -msgstr "" - -#: ../../library/contextlib.rst:700 -msgid "" -"It is occasionally desirable to catch exceptions from an ``__enter__`` " -"method implementation, *without* inadvertently catching exceptions from " -"the :keyword:`with` statement body or the context manager's ``__exit__`` " -"method. By using :class:`ExitStack` the steps in the context management " -"protocol can be separated slightly in order to allow this::" -msgstr "" - -#: ../../library/contextlib.rst:706 -msgid "" -"stack = ExitStack()\n" -"try:\n" -" x = stack.enter_context(cm)\n" -"except Exception:\n" -" # handle __enter__ exception\n" -"else:\n" -" with stack:\n" -" # Handle normal case" -msgstr "" - -#: ../../library/contextlib.rst:715 -msgid "" -"Actually needing to do this is likely to indicate that the underlying API " -"should be providing a direct resource management interface for use " -"with :keyword:`try`/:keyword:`except`/:keyword:`finally` statements, but not " -"all APIs are well designed in that regard. When a context manager is the " -"only resource management API provided, then :class:`ExitStack` can make it " -"easier to handle various situations that can't be handled directly in " -"a :keyword:`with` statement." -msgstr "" - -#: ../../library/contextlib.rst:725 -msgid "Cleaning up in an ``__enter__`` implementation" -msgstr "" - -#: ../../library/contextlib.rst:727 -msgid "" -"As noted in the documentation of :meth:`ExitStack.push`, this method can be " -"useful in cleaning up an already allocated resource if later steps in " -"the :meth:`~object.__enter__` implementation fail." -msgstr "" - -#: ../../library/contextlib.rst:731 -msgid "" -"Here's an example of doing this for a context manager that accepts resource " -"acquisition and release functions, along with an optional validation " -"function, and maps them to the context management protocol::" -msgstr "" - -#: ../../library/contextlib.rst:735 -msgid "" -"from contextlib import contextmanager, AbstractContextManager, ExitStack\n" -"\n" -"class ResourceManager(AbstractContextManager):\n" -"\n" -" def __init__(self, acquire_resource, release_resource, " -"check_resource_ok=None):\n" -" self.acquire_resource = acquire_resource\n" -" self.release_resource = release_resource\n" -" if check_resource_ok is None:\n" -" def check_resource_ok(resource):\n" -" return True\n" -" self.check_resource_ok = check_resource_ok\n" -"\n" -" @contextmanager\n" -" def _cleanup_on_error(self):\n" -" with ExitStack() as stack:\n" -" stack.push(self)\n" -" yield\n" -" # The validation check passed and didn't raise an exception\n" -" # Accordingly, we want to keep the resource, and pass it\n" -" # back to our caller\n" -" stack.pop_all()\n" -"\n" -" def __enter__(self):\n" -" resource = self.acquire_resource()\n" -" with self._cleanup_on_error():\n" -" if not self.check_resource_ok(resource):\n" -" msg = \"Failed validation for {!r}\"\n" -" raise RuntimeError(msg.format(resource))\n" -" return resource\n" -"\n" -" def __exit__(self, *exc_details):\n" -" # We don't need to duplicate any of our resource release logic\n" -" self.release_resource()" -msgstr "" - -#: ../../library/contextlib.rst:771 -msgid "Replacing any use of ``try-finally`` and flag variables" -msgstr "" - -#: ../../library/contextlib.rst:773 -msgid "" -"A pattern you will sometimes see is a ``try-finally`` statement with a flag " -"variable to indicate whether or not the body of the ``finally`` clause " -"should be executed. In its simplest form (that can't already be handled just " -"by using an ``except`` clause instead), it looks something like this::" -msgstr "" - -#: ../../library/contextlib.rst:778 -msgid "" -"cleanup_needed = True\n" -"try:\n" -" result = perform_operation()\n" -" if result:\n" -" cleanup_needed = False\n" -"finally:\n" -" if cleanup_needed:\n" -" cleanup_resources()" -msgstr "" -"cleanup_needed = True\n" -"try:\n" -" result = perform_operation()\n" -" if result:\n" -" cleanup_needed = False\n" -"finally:\n" -" if cleanup_needed:\n" -" cleanup_resources()" - -#: ../../library/contextlib.rst:787 -msgid "" -"As with any ``try`` statement based code, this can cause problems for " -"development and review, because the setup code and the cleanup code can end " -"up being separated by arbitrarily long sections of code." -msgstr "" - -#: ../../library/contextlib.rst:791 -msgid "" -":class:`ExitStack` makes it possible to instead register a callback for " -"execution at the end of a ``with`` statement, and then later decide to skip " -"executing that callback::" -msgstr "" - -#: ../../library/contextlib.rst:795 -msgid "" -"from contextlib import ExitStack\n" -"\n" -"with ExitStack() as stack:\n" -" stack.callback(cleanup_resources)\n" -" result = perform_operation()\n" -" if result:\n" -" stack.pop_all()" -msgstr "" -"from contextlib import ExitStack\n" -"\n" -"with ExitStack() as stack:\n" -" stack.callback(cleanup_resources)\n" -" result = perform_operation()\n" -" if result:\n" -" stack.pop_all()" - -#: ../../library/contextlib.rst:803 -msgid "" -"This allows the intended cleanup behaviour to be made explicit up front, " -"rather than requiring a separate flag variable." -msgstr "" - -#: ../../library/contextlib.rst:806 -msgid "" -"If a particular application uses this pattern a lot, it can be simplified " -"even further by means of a small helper class::" -msgstr "" - -#: ../../library/contextlib.rst:809 -msgid "" -"from contextlib import ExitStack\n" -"\n" -"class Callback(ExitStack):\n" -" def __init__(self, callback, /, *args, **kwds):\n" -" super().__init__()\n" -" self.callback(callback, *args, **kwds)\n" -"\n" -" def cancel(self):\n" -" self.pop_all()\n" -"\n" -"with Callback(cleanup_resources) as cb:\n" -" result = perform_operation()\n" -" if result:\n" -" cb.cancel()" -msgstr "" -"from contextlib import ExitStack\n" -"\n" -"class Callback(ExitStack):\n" -" def __init__(self, callback, /, *args, **kwds):\n" -" super().__init__()\n" -" self.callback(callback, *args, **kwds)\n" -"\n" -" def cancel(self):\n" -" self.pop_all()\n" -"\n" -"with Callback(cleanup_resources) as cb:\n" -" result = perform_operation()\n" -" if result:\n" -" cb.cancel()" - -#: ../../library/contextlib.rst:824 -msgid "" -"If the resource cleanup isn't already neatly bundled into a standalone " -"function, then it is still possible to use the decorator form " -"of :meth:`ExitStack.callback` to declare the resource cleanup in advance::" -msgstr "" - -#: ../../library/contextlib.rst:829 -msgid "" -"from contextlib import ExitStack\n" -"\n" -"with ExitStack() as stack:\n" -" @stack.callback\n" -" def cleanup_resources():\n" -" ...\n" -" result = perform_operation()\n" -" if result:\n" -" stack.pop_all()" -msgstr "" -"from contextlib import ExitStack\n" -"\n" -"with ExitStack() as stack:\n" -" @stack.callback\n" -" def cleanup_resources():\n" -" ...\n" -" result = perform_operation()\n" -" if result:\n" -" stack.pop_all()" - -#: ../../library/contextlib.rst:839 -msgid "" -"Due to the way the decorator protocol works, a callback function declared " -"this way cannot take any parameters. Instead, any resources to be released " -"must be accessed as closure variables." -msgstr "" - -#: ../../library/contextlib.rst:845 -msgid "Using a context manager as a function decorator" -msgstr "" - -#: ../../library/contextlib.rst:847 -msgid "" -":class:`ContextDecorator` makes it possible to use a context manager in both " -"an ordinary ``with`` statement and also as a function decorator." -msgstr "" - -#: ../../library/contextlib.rst:850 -msgid "" -"For example, it is sometimes useful to wrap functions or groups of " -"statements with a logger that can track the time of entry and time of exit. " -"Rather than writing both a function decorator and a context manager for the " -"task, inheriting from :class:`ContextDecorator` provides both capabilities " -"in a single definition::" -msgstr "" - -#: ../../library/contextlib.rst:856 -msgid "" -"from contextlib import ContextDecorator\n" -"import logging\n" -"\n" -"logging.basicConfig(level=logging.INFO)\n" -"\n" -"class track_entry_and_exit(ContextDecorator):\n" -" def __init__(self, name):\n" -" self.name = name\n" -"\n" -" def __enter__(self):\n" -" logging.info('Entering: %s', self.name)\n" -"\n" -" def __exit__(self, exc_type, exc, exc_tb):\n" -" logging.info('Exiting: %s', self.name)" -msgstr "" -"from contextlib import ContextDecorator\n" -"import logging\n" -"\n" -"logging.basicConfig(level=logging.INFO)\n" -"\n" -"class track_entry_and_exit(ContextDecorator):\n" -" def __init__(self, name):\n" -" self.name = name\n" -"\n" -" def __enter__(self):\n" -" logging.info('Entering: %s', self.name)\n" -"\n" -" def __exit__(self, exc_type, exc, exc_tb):\n" -" logging.info('Exiting: %s', self.name)" - -#: ../../library/contextlib.rst:871 -msgid "Instances of this class can be used as both a context manager::" -msgstr "" - -#: ../../library/contextlib.rst:873 -msgid "" -"with track_entry_and_exit('widget loader'):\n" -" print('Some time consuming activity goes here')\n" -" load_widget()" -msgstr "" -"with track_entry_and_exit('widget loader'):\n" -" print('Some time consuming activity goes here')\n" -" load_widget()" - -#: ../../library/contextlib.rst:877 -msgid "And also as a function decorator::" -msgstr "" - -#: ../../library/contextlib.rst:879 -msgid "" -"@track_entry_and_exit('widget loader')\n" -"def activity():\n" -" print('Some time consuming activity goes here')\n" -" load_widget()" -msgstr "" -"@track_entry_and_exit('widget loader')\n" -"def activity():\n" -" print('Some time consuming activity goes here')\n" -" load_widget()" - -#: ../../library/contextlib.rst:884 -msgid "" -"Note that there is one additional limitation when using context managers as " -"function decorators: there's no way to access the return value " -"of :meth:`~object.__enter__`. If that value is needed, then it is still " -"necessary to use an explicit ``with`` statement." -msgstr "" - -#: ../../library/contextlib.rst:891 -msgid ":pep:`343` - The \"with\" statement" -msgstr ":pep:`343` - \"with\" 陳述式" - -#: ../../library/contextlib.rst:892 -msgid "" -"The specification, background, and examples for the Python :keyword:`with` " -"statement." -msgstr "" - -#: ../../library/contextlib.rst:898 -msgid "Single use, reusable and reentrant context managers" -msgstr "" - -#: ../../library/contextlib.rst:900 -msgid "" -"Most context managers are written in a way that means they can only be used " -"effectively in a :keyword:`with` statement once. These single use context " -"managers must be created afresh each time they're used - attempting to use " -"them a second time will trigger an exception or otherwise not work correctly." -msgstr "" - -#: ../../library/contextlib.rst:906 -msgid "" -"This common limitation means that it is generally advisable to create " -"context managers directly in the header of the :keyword:`with` statement " -"where they are used (as shown in all of the usage examples above)." -msgstr "" - -#: ../../library/contextlib.rst:910 -msgid "" -"Files are an example of effectively single use context managers, since the " -"first :keyword:`with` statement will close the file, preventing any further " -"IO operations using that file object." -msgstr "" - -#: ../../library/contextlib.rst:914 -msgid "" -"Context managers created using :func:`contextmanager` are also single use " -"context managers, and will complain about the underlying generator failing " -"to yield if an attempt is made to use them a second time::" -msgstr "" - -#: ../../library/contextlib.rst:918 -msgid "" -">>> from contextlib import contextmanager\n" -">>> @contextmanager\n" -"... def singleuse():\n" -"... print(\"Before\")\n" -"... yield\n" -"... print(\"After\")\n" -"...\n" -">>> cm = singleuse()\n" -">>> with cm:\n" -"... pass\n" -"...\n" -"Before\n" -"After\n" -">>> with cm:\n" -"... pass\n" -"...\n" -"Traceback (most recent call last):\n" -" ...\n" -"RuntimeError: generator didn't yield" -msgstr "" -">>> from contextlib import contextmanager\n" -">>> @contextmanager\n" -"... def singleuse():\n" -"... print(\"Before\")\n" -"... yield\n" -"... print(\"After\")\n" -"...\n" -">>> cm = singleuse()\n" -">>> with cm:\n" -"... pass\n" -"...\n" -"Before\n" -"After\n" -">>> with cm:\n" -"... pass\n" -"...\n" -"Traceback (most recent call last):\n" -" ...\n" -"RuntimeError: generator didn't yield" - -#: ../../library/contextlib.rst:942 -msgid "Reentrant context managers" -msgstr "" - -#: ../../library/contextlib.rst:944 -msgid "" -"More sophisticated context managers may be \"reentrant\". These context " -"managers can not only be used in multiple :keyword:`with` statements, but " -"may also be used *inside* a :keyword:`!with` statement that is already using " -"the same context manager." -msgstr "" - -#: ../../library/contextlib.rst:949 -msgid "" -":class:`threading.RLock` is an example of a reentrant context manager, as " -"are :func:`suppress`, :func:`redirect_stdout`, and :func:`chdir`. Here's a " -"very simple example of reentrant use::" -msgstr "" - -#: ../../library/contextlib.rst:953 -msgid "" -">>> from contextlib import redirect_stdout\n" -">>> from io import StringIO\n" -">>> stream = StringIO()\n" -">>> write_to_stream = redirect_stdout(stream)\n" -">>> with write_to_stream:\n" -"... print(\"This is written to the stream rather than stdout\")\n" -"... with write_to_stream:\n" -"... print(\"This is also written to the stream\")\n" -"...\n" -">>> print(\"This is written directly to stdout\")\n" -"This is written directly to stdout\n" -">>> print(stream.getvalue())\n" -"This is written to the stream rather than stdout\n" -"This is also written to the stream" -msgstr "" -">>> from contextlib import redirect_stdout\n" -">>> from io import StringIO\n" -">>> stream = StringIO()\n" -">>> write_to_stream = redirect_stdout(stream)\n" -">>> with write_to_stream:\n" -"... print(\"This is written to the stream rather than stdout\")\n" -"... with write_to_stream:\n" -"... print(\"This is also written to the stream\")\n" -"...\n" -">>> print(\"This is written directly to stdout\")\n" -"This is written directly to stdout\n" -">>> print(stream.getvalue())\n" -"This is written to the stream rather than stdout\n" -"This is also written to the stream" - -#: ../../library/contextlib.rst:968 -msgid "" -"Real world examples of reentrancy are more likely to involve multiple " -"functions calling each other and hence be far more complicated than this " -"example." -msgstr "" - -#: ../../library/contextlib.rst:972 -msgid "" -"Note also that being reentrant is *not* the same thing as being thread " -"safe. :func:`redirect_stdout`, for example, is definitely not thread safe, " -"as it makes a global modification to the system state by " -"binding :data:`sys.stdout` to a different stream." -msgstr "" - -#: ../../library/contextlib.rst:981 -msgid "Reusable context managers" -msgstr "" - -#: ../../library/contextlib.rst:983 -msgid "" -"Distinct from both single use and reentrant context managers are " -"\"reusable\" context managers (or, to be completely explicit, \"reusable, " -"but not reentrant\" context managers, since reentrant context managers are " -"also reusable). These context managers support being used multiple times, " -"but will fail (or otherwise not work correctly) if the specific context " -"manager instance has already been used in a containing with statement." -msgstr "" - -#: ../../library/contextlib.rst:990 -msgid "" -":class:`threading.Lock` is an example of a reusable, but not reentrant, " -"context manager (for a reentrant lock, it is necessary to " -"use :class:`threading.RLock` instead)." -msgstr "" - -#: ../../library/contextlib.rst:994 -msgid "" -"Another example of a reusable, but not reentrant, context manager " -"is :class:`ExitStack`, as it invokes *all* currently registered callbacks " -"when leaving any with statement, regardless of where those callbacks were " -"added::" -msgstr "" - -#: ../../library/contextlib.rst:999 -msgid "" -">>> from contextlib import ExitStack\n" -">>> stack = ExitStack()\n" -">>> with stack:\n" -"... stack.callback(print, \"Callback: from first context\")\n" -"... print(\"Leaving first context\")\n" -"...\n" -"Leaving first context\n" -"Callback: from first context\n" -">>> with stack:\n" -"... stack.callback(print, \"Callback: from second context\")\n" -"... print(\"Leaving second context\")\n" -"...\n" -"Leaving second context\n" -"Callback: from second context\n" -">>> with stack:\n" -"... stack.callback(print, \"Callback: from outer context\")\n" -"... with stack:\n" -"... stack.callback(print, \"Callback: from inner context\")\n" -"... print(\"Leaving inner context\")\n" -"... print(\"Leaving outer context\")\n" -"...\n" -"Leaving inner context\n" -"Callback: from inner context\n" -"Callback: from outer context\n" -"Leaving outer context" -msgstr "" -">>> from contextlib import ExitStack\n" -">>> stack = ExitStack()\n" -">>> with stack:\n" -"... stack.callback(print, \"Callback: from first context\")\n" -"... print(\"Leaving first context\")\n" -"...\n" -"Leaving first context\n" -"Callback: from first context\n" -">>> with stack:\n" -"... stack.callback(print, \"Callback: from second context\")\n" -"... print(\"Leaving second context\")\n" -"...\n" -"Leaving second context\n" -"Callback: from second context\n" -">>> with stack:\n" -"... stack.callback(print, \"Callback: from outer context\")\n" -"... with stack:\n" -"... stack.callback(print, \"Callback: from inner context\")\n" -"... print(\"Leaving inner context\")\n" -"... print(\"Leaving outer context\")\n" -"...\n" -"Leaving inner context\n" -"Callback: from inner context\n" -"Callback: from outer context\n" -"Leaving outer context" - -#: ../../library/contextlib.rst:1025 -msgid "" -"As the output from the example shows, reusing a single stack object across " -"multiple with statements works correctly, but attempting to nest them will " -"cause the stack to be cleared at the end of the innermost with statement, " -"which is unlikely to be desirable behaviour." -msgstr "" - -#: ../../library/contextlib.rst:1030 -msgid "" -"Using separate :class:`ExitStack` instances instead of reusing a single " -"instance avoids that problem::" -msgstr "" - -#: ../../library/contextlib.rst:1033 -msgid "" -">>> from contextlib import ExitStack\n" -">>> with ExitStack() as outer_stack:\n" -"... outer_stack.callback(print, \"Callback: from outer context\")\n" -"... with ExitStack() as inner_stack:\n" -"... inner_stack.callback(print, \"Callback: from inner context\")\n" -"... print(\"Leaving inner context\")\n" -"... print(\"Leaving outer context\")\n" -"...\n" -"Leaving inner context\n" -"Callback: from inner context\n" -"Leaving outer context\n" -"Callback: from outer context" -msgstr "" -">>> from contextlib import ExitStack\n" -">>> with ExitStack() as outer_stack:\n" -"... outer_stack.callback(print, \"Callback: from outer context\")\n" -"... with ExitStack() as inner_stack:\n" -"... inner_stack.callback(print, \"Callback: from inner context\")\n" -"... print(\"Leaving inner context\")\n" -"... print(\"Leaving outer context\")\n" -"...\n" -"Leaving inner context\n" -"Callback: from inner context\n" -"Leaving outer context\n" -"Callback: from outer context" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-04-11 00:15+0000\n" +"PO-Revision-Date: 2018-05-23 14:41+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/contextlib.rst:2 +msgid "" +":mod:`!contextlib` --- Utilities for :keyword:`!with`\\ -statement contexts" +msgstr ":mod:`!contextlib` --- :keyword:`!with` 陳述式工具程式" + +#: ../../library/contextlib.rst:7 +msgid "**Source code:** :source:`Lib/contextlib.py`" +msgstr "**原始碼：**\\ :source:`Lib/contextlib.py`" + +#: ../../library/contextlib.rst:11 +msgid "" +"This module provides utilities for common tasks involving " +"the :keyword:`with` statement. For more information see " +"also :ref:`typecontextmanager` and :ref:`context-managers`." +msgstr "" + +#: ../../library/contextlib.rst:17 +msgid "Utilities" +msgstr "" + +#: ../../library/contextlib.rst:19 +msgid "Functions and classes provided:" +msgstr "" + +#: ../../library/contextlib.rst:23 +msgid "" +"An :term:`abstract base class` for classes that " +"implement :meth:`object.__enter__` and :meth:`object.__exit__`. A default " +"implementation for :meth:`object.__enter__` is provided which returns " +"``self`` while :meth:`object.__exit__` is an abstract method which by " +"default returns ``None``. See also the definition " +"of :ref:`typecontextmanager`." +msgstr "" + +#: ../../library/contextlib.rst:34 +msgid "" +"An :term:`abstract base class` for classes that " +"implement :meth:`object.__aenter__` and :meth:`object.__aexit__`. A default " +"implementation for :meth:`object.__aenter__` is provided which returns " +"``self`` while :meth:`object.__aexit__` is an abstract method which by " +"default returns ``None``. See also the definition of :ref:`async-context-" +"managers`." +msgstr "" + +#: ../../library/contextlib.rst:46 +msgid "" +"This function is a :term:`decorator` that can be used to define a factory " +"function for :keyword:`with` statement context managers, without needing to " +"create a class or separate :meth:`~object.__enter__` " +"and :meth:`~object.__exit__` methods." +msgstr "" + +#: ../../library/contextlib.rst:50 +msgid "" +"While many objects natively support use in with statements, sometimes a " +"resource needs to be managed that isn't a context manager in its own right, " +"and doesn't implement a ``close()`` method for use with " +"``contextlib.closing``." +msgstr "" + +#: ../../library/contextlib.rst:54 +msgid "" +"An abstract example would be the following to ensure correct resource " +"management::" +msgstr "" + +#: ../../library/contextlib.rst:57 +msgid "" +"from contextlib import contextmanager\n" +"\n" +"@contextmanager\n" +"def managed_resource(*args, **kwds):\n" +" # Code to acquire resource, e.g.:\n" +" resource = acquire_resource(*args, **kwds)\n" +" try:\n" +" yield resource\n" +" finally:\n" +" # Code to release resource, e.g.:\n" +" release_resource(resource)" +msgstr "" + +#: ../../library/contextlib.rst:69 +msgid "The function can then be used like this::" +msgstr "" + +#: ../../library/contextlib.rst:71 +msgid "" +">>> with managed_resource(timeout=3600) as resource:\n" +"... # Resource is released at the end of this block,\n" +"... # even if code in the block raises an exception" +msgstr "" + +#: ../../library/contextlib.rst:75 +msgid "" +"The function being decorated must return a :term:`generator`-iterator when " +"called. This iterator must yield exactly one value, which will be bound to " +"the targets in the :keyword:`with` statement's :keyword:`!as` clause, if any." +msgstr "" + +#: ../../library/contextlib.rst:79 +msgid "" +"At the point where the generator yields, the block nested in " +"the :keyword:`with` statement is executed. The generator is then resumed " +"after the block is exited. If an unhandled exception occurs in the block, it " +"is reraised inside the generator at the point where the yield occurred. " +"Thus, you can use a :keyword:`try`...\\ :keyword:`except`..." +"\\ :keyword:`finally` statement to trap the error (if any), or ensure that " +"some cleanup takes place. If an exception is trapped merely in order to log " +"it or to perform some action (rather than to suppress it entirely), the " +"generator must reraise that exception. Otherwise the generator context " +"manager will indicate to the :keyword:`!with` statement that the exception " +"has been handled, and execution will resume with the statement immediately " +"following the :keyword:`!with` statement." +msgstr "" + +#: ../../library/contextlib.rst:91 +msgid "" +":func:`contextmanager` uses :class:`ContextDecorator` so the context " +"managers it creates can be used as decorators as well as in :keyword:`with` " +"statements. When used as a decorator, a new generator instance is implicitly " +"created on each function call (this allows the otherwise \"one-shot\" " +"context managers created by :func:`contextmanager` to meet the requirement " +"that context managers support multiple invocations in order to be used as " +"decorators)." +msgstr "" + +#: ../../library/contextlib.rst:98 +msgid "Use of :class:`ContextDecorator`." +msgstr "" + +#: ../../library/contextlib.rst:104 +msgid "" +"Similar to :func:`~contextlib.contextmanager`, but creates " +"an :ref:`asynchronous context manager `." +msgstr "" + +#: ../../library/contextlib.rst:107 +msgid "" +"This function is a :term:`decorator` that can be used to define a factory " +"function for :keyword:`async with` statement asynchronous context managers, " +"without needing to create a class or separate :meth:`~object.__aenter__` " +"and :meth:`~object.__aexit__` methods. It must be applied to " +"an :term:`asynchronous generator` function." +msgstr "" + +#: ../../library/contextlib.rst:113 +msgid "A simple example::" +msgstr "一個簡單範例： ::" + +#: ../../library/contextlib.rst:115 +msgid "" +"from contextlib import asynccontextmanager\n" +"\n" +"@asynccontextmanager\n" +"async def get_connection():\n" +" conn = await acquire_db_connection()\n" +" try:\n" +" yield conn\n" +" finally:\n" +" await release_db_connection(conn)\n" +"\n" +"async def get_all_users():\n" +" async with get_connection() as conn:\n" +" return conn.query('SELECT ...')" +msgstr "" +"from contextlib import asynccontextmanager\n" +"\n" +"@asynccontextmanager\n" +"async def get_connection():\n" +" conn = await acquire_db_connection()\n" +" try:\n" +" yield conn\n" +" finally:\n" +" await release_db_connection(conn)\n" +"\n" +"async def get_all_users():\n" +" async with get_connection() as conn:\n" +" return conn.query('SELECT ...')" + +#: ../../library/contextlib.rst:131 +msgid "" +"Context managers defined with :func:`asynccontextmanager` can be used either " +"as decorators or with :keyword:`async with` statements::" +msgstr "" + +#: ../../library/contextlib.rst:134 +msgid "" +"import time\n" +"from contextlib import asynccontextmanager\n" +"\n" +"@asynccontextmanager\n" +"async def timeit():\n" +" now = time.monotonic()\n" +" try:\n" +" yield\n" +" finally:\n" +" print(f'it took {time.monotonic() - now}s to run')\n" +"\n" +"@timeit()\n" +"async def main():\n" +" # ... async code ..." +msgstr "" + +#: ../../library/contextlib.rst:149 +msgid "" +"When used as a decorator, a new generator instance is implicitly created on " +"each function call. This allows the otherwise \"one-shot\" context managers " +"created by :func:`asynccontextmanager` to meet the requirement that context " +"managers support multiple invocations in order to be used as decorators." +msgstr "" + +#: ../../library/contextlib.rst:154 +msgid "" +"Async context managers created with :func:`asynccontextmanager` can be used " +"as decorators." +msgstr "" + +#: ../../library/contextlib.rst:161 +msgid "" +"Return a context manager that closes *thing* upon completion of the block. " +"This is basically equivalent to::" +msgstr "" + +#: ../../library/contextlib.rst:164 +msgid "" +"from contextlib import contextmanager\n" +"\n" +"@contextmanager\n" +"def closing(thing):\n" +" try:\n" +" yield thing\n" +" finally:\n" +" thing.close()" +msgstr "" +"from contextlib import contextmanager\n" +"\n" +"@contextmanager\n" +"def closing(thing):\n" +" try:\n" +" yield thing\n" +" finally:\n" +" thing.close()" + +#: ../../library/contextlib.rst:173 +msgid "And lets you write code like this::" +msgstr "" + +#: ../../library/contextlib.rst:175 +msgid "" +"from contextlib import closing\n" +"from urllib.request import urlopen\n" +"\n" +"with closing(urlopen('https://www.python.org')) as page:\n" +" for line in page:\n" +" print(line)" +msgstr "" +"from contextlib import closing\n" +"from urllib.request import urlopen\n" +"\n" +"with closing(urlopen('https://www.python.org')) as page:\n" +" for line in page:\n" +" print(line)" + +#: ../../library/contextlib.rst:182 +msgid "" +"without needing to explicitly close ``page``. Even if an error occurs, " +"``page.close()`` will be called when the :keyword:`with` block is exited." +msgstr "" + +#: ../../library/contextlib.rst:187 +msgid "" +"Most types managing resources support the :term:`context manager` protocol, " +"which closes *thing* on leaving the :keyword:`with` statement. As " +"such, :func:`!closing` is most useful for third party types that don't " +"support context managers. This example is purely for illustration purposes, " +"as :func:`~urllib.request.urlopen` would normally be used in a context " +"manager." +msgstr "" + +#: ../../library/contextlib.rst:196 +msgid "" +"Return an async context manager that calls the ``aclose()`` method of " +"*thing* upon completion of the block. This is basically equivalent to::" +msgstr "" + +#: ../../library/contextlib.rst:199 +msgid "" +"from contextlib import asynccontextmanager\n" +"\n" +"@asynccontextmanager\n" +"async def aclosing(thing):\n" +" try:\n" +" yield thing\n" +" finally:\n" +" await thing.aclose()" +msgstr "" +"from contextlib import asynccontextmanager\n" +"\n" +"@asynccontextmanager\n" +"async def aclosing(thing):\n" +" try:\n" +" yield thing\n" +" finally:\n" +" await thing.aclose()" + +#: ../../library/contextlib.rst:208 +msgid "" +"Significantly, ``aclosing()`` supports deterministic cleanup of async " +"generators when they happen to exit early by :keyword:`break` or an " +"exception. For example::" +msgstr "" + +#: ../../library/contextlib.rst:212 +msgid "" +"from contextlib import aclosing\n" +"\n" +"async with aclosing(my_generator()) as values:\n" +" async for value in values:\n" +" if value == 42:\n" +" break" +msgstr "" +"from contextlib import aclosing\n" +"\n" +"async with aclosing(my_generator()) as values:\n" +" async for value in values:\n" +" if value == 42:\n" +" break" + +#: ../../library/contextlib.rst:219 +msgid "" +"This pattern ensures that the generator's async exit code is executed in the " +"same context as its iterations (so that exceptions and context variables " +"work as expected, and the exit code isn't run after the lifetime of some " +"task it depends on)." +msgstr "" + +#: ../../library/contextlib.rst:231 +msgid "" +"Return a context manager that returns *enter_result* from ``__enter__``, but " +"otherwise does nothing. It is intended to be used as a stand-in for an " +"optional context manager, for example::" +msgstr "" + +#: ../../library/contextlib.rst:235 +msgid "" +"def myfunction(arg, ignore_exceptions=False):\n" +" if ignore_exceptions:\n" +" # Use suppress to ignore all exceptions.\n" +" cm = contextlib.suppress(Exception)\n" +" else:\n" +" # Do not ignore any exceptions, cm has no effect.\n" +" cm = contextlib.nullcontext()\n" +" with cm:\n" +" # Do something" +msgstr "" + +#: ../../library/contextlib.rst:245 +msgid "An example using *enter_result*::" +msgstr "一個使用 *enter_result* 的範例： ::" + +#: ../../library/contextlib.rst:247 +msgid "" +"def process_file(file_or_path):\n" +" if isinstance(file_or_path, str):\n" +" # If string, open file\n" +" cm = open(file_or_path)\n" +" else:\n" +" # Caller is responsible for closing file\n" +" cm = nullcontext(file_or_path)\n" +"\n" +" with cm as file:\n" +" # Perform processing on the file" +msgstr "" + +#: ../../library/contextlib.rst:258 +msgid "" +"It can also be used as a stand-in for :ref:`asynchronous context managers " +"`::" +msgstr "" + +#: ../../library/contextlib.rst:261 +msgid "" +"async def send_http(session=None):\n" +" if not session:\n" +" # If no http session, create it with aiohttp\n" +" cm = aiohttp.ClientSession()\n" +" else:\n" +" # Caller is responsible for closing the session\n" +" cm = nullcontext(session)\n" +"\n" +" async with cm as session:\n" +" # Send http requests with session" +msgstr "" + +#: ../../library/contextlib.rst:274 +msgid ":term:`asynchronous context manager` support was added." +msgstr "" + +#: ../../library/contextlib.rst:281 +msgid "" +"Return a context manager that suppresses any of the specified exceptions if " +"they occur in the body of a :keyword:`!with` statement and then resumes " +"execution with the first statement following the end of the :keyword:`!with` " +"statement." +msgstr "" + +#: ../../library/contextlib.rst:286 +msgid "" +"As with any other mechanism that completely suppresses exceptions, this " +"context manager should be used only to cover very specific errors where " +"silently continuing with program execution is known to be the right thing to " +"do." +msgstr "" + +#: ../../library/contextlib.rst:291 +msgid "For example::" +msgstr "舉例來說： ::" + +#: ../../library/contextlib.rst:293 +msgid "" +"from contextlib import suppress\n" +"\n" +"with suppress(FileNotFoundError):\n" +" os.remove('somefile.tmp')\n" +"\n" +"with suppress(FileNotFoundError):\n" +" os.remove('someotherfile.tmp')" +msgstr "" +"from contextlib import suppress\n" +"\n" +"with suppress(FileNotFoundError):\n" +" os.remove('somefile.tmp')\n" +"\n" +"with suppress(FileNotFoundError):\n" +" os.remove('someotherfile.tmp')" + +#: ../../library/contextlib.rst:301 +msgid "This code is equivalent to::" +msgstr "" + +#: ../../library/contextlib.rst:303 +msgid "" +"try:\n" +" os.remove('somefile.tmp')\n" +"except FileNotFoundError:\n" +" pass\n" +"\n" +"try:\n" +" os.remove('someotherfile.tmp')\n" +"except FileNotFoundError:\n" +" pass" +msgstr "" +"try:\n" +" os.remove('somefile.tmp')\n" +"except FileNotFoundError:\n" +" pass\n" +"\n" +"try:\n" +" os.remove('someotherfile.tmp')\n" +"except FileNotFoundError:\n" +" pass" + +#: ../../library/contextlib.rst:313 ../../library/contextlib.rst:362 +#: ../../library/contextlib.rst:372 ../../library/contextlib.rst:389 +msgid "This context manager is :ref:`reentrant `." +msgstr "" + +#: ../../library/contextlib.rst:315 +msgid "" +"If the code within the :keyword:`!with` block raises " +"a :exc:`BaseExceptionGroup`, suppressed exceptions are removed from the " +"group. Any exceptions of the group which are not suppressed are re-raised " +"in a new group which is created using the original " +"group's :meth:`~BaseExceptionGroup.derive` method." +msgstr "" + +#: ../../library/contextlib.rst:323 +msgid "" +"``suppress`` now supports suppressing exceptions raised as part of " +"a :exc:`BaseExceptionGroup`." +msgstr "" + +#: ../../library/contextlib.rst:329 +msgid "" +"Context manager for temporarily redirecting :data:`sys.stdout` to another " +"file or file-like object." +msgstr "" + +#: ../../library/contextlib.rst:332 +msgid "" +"This tool adds flexibility to existing functions or classes whose output is " +"hardwired to stdout." +msgstr "" + +#: ../../library/contextlib.rst:335 +msgid "" +"For example, the output of :func:`help` normally is sent to *sys.stdout*. " +"You can capture that output in a string by redirecting the output to " +"an :class:`io.StringIO` object. The replacement stream is returned from the " +"``__enter__`` method and so is available as the target of " +"the :keyword:`with` statement::" +msgstr "" + +#: ../../library/contextlib.rst:341 +msgid "" +"with redirect_stdout(io.StringIO()) as f:\n" +" help(pow)\n" +"s = f.getvalue()" +msgstr "" +"with redirect_stdout(io.StringIO()) as f:\n" +" help(pow)\n" +"s = f.getvalue()" + +#: ../../library/contextlib.rst:345 +msgid "" +"To send the output of :func:`help` to a file on disk, redirect the output to " +"a regular file::" +msgstr "" + +#: ../../library/contextlib.rst:348 +msgid "" +"with open('help.txt', 'w') as f:\n" +" with redirect_stdout(f):\n" +" help(pow)" +msgstr "" +"with open('help.txt', 'w') as f:\n" +" with redirect_stdout(f):\n" +" help(pow)" + +#: ../../library/contextlib.rst:352 +msgid "To send the output of :func:`help` to *sys.stderr*::" +msgstr "" + +#: ../../library/contextlib.rst:354 +msgid "" +"with redirect_stdout(sys.stderr):\n" +" help(pow)" +msgstr "" +"with redirect_stdout(sys.stderr):\n" +" help(pow)" + +#: ../../library/contextlib.rst:357 +msgid "" +"Note that the global side effect on :data:`sys.stdout` means that this " +"context manager is not suitable for use in library code and most threaded " +"applications. It also has no effect on the output of subprocesses. However, " +"it is still a useful approach for many utility scripts." +msgstr "" + +#: ../../library/contextlib.rst:369 +msgid "" +"Similar to :func:`~contextlib.redirect_stdout` but " +"redirecting :data:`sys.stderr` to another file or file-like object." +msgstr "" + +#: ../../library/contextlib.rst:379 +msgid "" +"Non parallel-safe context manager to change the current working directory. " +"As this changes a global state, the working directory, it is not suitable " +"for use in most threaded or async contexts. It is also not suitable for most " +"non-linear code execution, like generators, where the program execution is " +"temporarily relinquished -- unless explicitly desired, you should not yield " +"when this context manager is active." +msgstr "" + +#: ../../library/contextlib.rst:386 +msgid "" +"This is a simple wrapper around :func:`~os.chdir`, it changes the current " +"working directory upon entering and restores the old one on exit." +msgstr "" + +#: ../../library/contextlib.rst:396 +msgid "" +"A base class that enables a context manager to also be used as a decorator." +msgstr "" + +#: ../../library/contextlib.rst:398 +msgid "" +"Context managers inheriting from ``ContextDecorator`` have to implement " +"``__enter__`` and ``__exit__`` as normal. ``__exit__`` retains its optional " +"exception handling even when used as a decorator." +msgstr "" + +#: ../../library/contextlib.rst:402 +msgid "" +"``ContextDecorator`` is used by :func:`contextmanager`, so you get this " +"functionality automatically." +msgstr "" + +#: ../../library/contextlib.rst:405 +msgid "Example of ``ContextDecorator``::" +msgstr "``ContextDecorator`` 範例： ::" + +#: ../../library/contextlib.rst:407 +msgid "" +"from contextlib import ContextDecorator\n" +"\n" +"class mycontext(ContextDecorator):\n" +" def __enter__(self):\n" +" print('Starting')\n" +" return self\n" +"\n" +" def __exit__(self, *exc):\n" +" print('Finishing')\n" +" return False" +msgstr "" +"from contextlib import ContextDecorator\n" +"\n" +"class mycontext(ContextDecorator):\n" +" def __enter__(self):\n" +" print('Starting')\n" +" return self\n" +"\n" +" def __exit__(self, *exc):\n" +" print('Finishing')\n" +" return False" + +#: ../../library/contextlib.rst:418 ../../library/contextlib.rst:490 +msgid "The class can then be used like this::" +msgstr "這個類別可以這樣使用： ::" + +#: ../../library/contextlib.rst:420 +msgid "" +">>> @mycontext()\n" +"... def function():\n" +"... print('The bit in the middle')\n" +"...\n" +">>> function()\n" +"Starting\n" +"The bit in the middle\n" +"Finishing\n" +"\n" +">>> with mycontext():\n" +"... print('The bit in the middle')\n" +"...\n" +"Starting\n" +"The bit in the middle\n" +"Finishing" +msgstr "" +">>> @mycontext()\n" +"... def function():\n" +"... print('The bit in the middle')\n" +"...\n" +">>> function()\n" +"Starting\n" +"The bit in the middle\n" +"Finishing\n" +"\n" +">>> with mycontext():\n" +"... print('The bit in the middle')\n" +"...\n" +"Starting\n" +"The bit in the middle\n" +"Finishing" + +#: ../../library/contextlib.rst:436 +msgid "" +"This change is just syntactic sugar for any construct of the following form::" +msgstr "這個變更只是以下形式的語法糖： ::" + +#: ../../library/contextlib.rst:438 +msgid "" +"def f():\n" +" with cm():\n" +" # Do stuff" +msgstr "" +"def f():\n" +" with cm():\n" +" # Do stuff" + +#: ../../library/contextlib.rst:442 +msgid "``ContextDecorator`` lets you instead write::" +msgstr "``ContextDecorator`` 讓你可以改寫成： ::" + +#: ../../library/contextlib.rst:444 +msgid "" +"@cm()\n" +"def f():\n" +" # Do stuff" +msgstr "" +"@cm()\n" +"def f():\n" +" # Do stuff" + +#: ../../library/contextlib.rst:448 +msgid "" +"It makes it clear that the ``cm`` applies to the whole function, rather than " +"just a piece of it (and saving an indentation level is nice, too)." +msgstr "" + +#: ../../library/contextlib.rst:451 +msgid "" +"Existing context managers that already have a base class can be extended by " +"using ``ContextDecorator`` as a mixin class::" +msgstr "" + +#: ../../library/contextlib.rst:454 +msgid "" +"from contextlib import ContextDecorator\n" +"\n" +"class mycontext(ContextBaseClass, ContextDecorator):\n" +" def __enter__(self):\n" +" return self\n" +"\n" +" def __exit__(self, *exc):\n" +" return False" +msgstr "" +"from contextlib import ContextDecorator\n" +"\n" +"class mycontext(ContextBaseClass, ContextDecorator):\n" +" def __enter__(self):\n" +" return self\n" +"\n" +" def __exit__(self, *exc):\n" +" return False" + +#: ../../library/contextlib.rst:464 +msgid "" +"As the decorated function must be able to be called multiple times, the " +"underlying context manager must support use in multiple :keyword:`with` " +"statements. If this is not the case, then the original construct with the " +"explicit :keyword:`!with` statement inside the function should be used." +msgstr "" + +#: ../../library/contextlib.rst:474 +msgid "" +"Similar to :class:`ContextDecorator` but only for asynchronous functions." +msgstr "和 :class:`ContextDecorator` 類似，但僅用於非同步函式。" + +#: ../../library/contextlib.rst:476 +msgid "Example of ``AsyncContextDecorator``::" +msgstr "``AsyncContextDecorator`` 範例： ::" + +#: ../../library/contextlib.rst:478 +msgid "" +"from asyncio import run\n" +"from contextlib import AsyncContextDecorator\n" +"\n" +"class mycontext(AsyncContextDecorator):\n" +" async def __aenter__(self):\n" +" print('Starting')\n" +" return self\n" +"\n" +" async def __aexit__(self, *exc):\n" +" print('Finishing')\n" +" return False" +msgstr "" +"from asyncio import run\n" +"from contextlib import AsyncContextDecorator\n" +"\n" +"class mycontext(AsyncContextDecorator):\n" +" async def __aenter__(self):\n" +" print('Starting')\n" +" return self\n" +"\n" +" async def __aexit__(self, *exc):\n" +" print('Finishing')\n" +" return False" + +#: ../../library/contextlib.rst:492 +msgid "" +">>> @mycontext()\n" +"... async def function():\n" +"... print('The bit in the middle')\n" +"...\n" +">>> run(function())\n" +"Starting\n" +"The bit in the middle\n" +"Finishing\n" +"\n" +">>> async def function():\n" +"... async with mycontext():\n" +"... print('The bit in the middle')\n" +"...\n" +">>> run(function())\n" +"Starting\n" +"The bit in the middle\n" +"Finishing" +msgstr "" +">>> @mycontext()\n" +"... async def function():\n" +"... print('The bit in the middle')\n" +"...\n" +">>> run(function())\n" +"Starting\n" +"The bit in the middle\n" +"Finishing\n" +"\n" +">>> async def function():\n" +"... async with mycontext():\n" +"... print('The bit in the middle')\n" +"...\n" +">>> run(function())\n" +"Starting\n" +"The bit in the middle\n" +"Finishing" + +#: ../../library/contextlib.rst:515 +msgid "" +"A context manager that is designed to make it easy to programmatically " +"combine other context managers and cleanup functions, especially those that " +"are optional or otherwise driven by input data." +msgstr "" + +#: ../../library/contextlib.rst:519 +msgid "" +"For example, a set of files may easily be handled in a single with statement " +"as follows::" +msgstr "" + +#: ../../library/contextlib.rst:522 +msgid "" +"with ExitStack() as stack:\n" +" files = [stack.enter_context(open(fname)) for fname in filenames]\n" +" # All opened files will automatically be closed at the end of\n" +" # the with statement, even if attempts to open files later\n" +" # in the list raise an exception" +msgstr "" + +#: ../../library/contextlib.rst:528 +msgid "" +"The :meth:`~object.__enter__` method returns the :class:`ExitStack` " +"instance, and performs no additional operations." +msgstr "" + +#: ../../library/contextlib.rst:531 +msgid "" +"Each instance maintains a stack of registered callbacks that are called in " +"reverse order when the instance is closed (either explicitly or implicitly " +"at the end of a :keyword:`with` statement). Note that callbacks are *not* " +"invoked implicitly when the context stack instance is garbage collected." +msgstr "" + +#: ../../library/contextlib.rst:536 +msgid "" +"This stack model is used so that context managers that acquire their " +"resources in their ``__init__`` method (such as file objects) can be handled " +"correctly." +msgstr "" + +#: ../../library/contextlib.rst:540 +msgid "" +"Since registered callbacks are invoked in the reverse order of registration, " +"this ends up behaving as if multiple nested :keyword:`with` statements had " +"been used with the registered set of callbacks. This even extends to " +"exception handling - if an inner callback suppresses or replaces an " +"exception, then outer callbacks will be passed arguments based on that " +"updated state." +msgstr "" + +#: ../../library/contextlib.rst:547 +msgid "" +"This is a relatively low level API that takes care of the details of " +"correctly unwinding the stack of exit callbacks. It provides a suitable " +"foundation for higher level context managers that manipulate the exit stack " +"in application specific ways." +msgstr "" + +#: ../../library/contextlib.rst:556 +msgid "" +"Enters a new context manager and adds its :meth:`~object.__exit__` method to " +"the callback stack. The return value is the result of the context manager's " +"own :meth:`~object.__enter__` method." +msgstr "" + +#: ../../library/contextlib.rst:560 +msgid "" +"These context managers may suppress exceptions just as they normally would " +"if used directly as part of a :keyword:`with` statement." +msgstr "" + +#: ../../library/contextlib.rst:563 +msgid "" +"Raises :exc:`TypeError` instead of :exc:`AttributeError` if *cm* is not a " +"context manager." +msgstr "" + +#: ../../library/contextlib.rst:569 +msgid "" +"Adds a context manager's :meth:`~object.__exit__` method to the callback " +"stack." +msgstr "" + +#: ../../library/contextlib.rst:571 +msgid "" +"As ``__enter__`` is *not* invoked, this method can be used to cover part of " +"an :meth:`~object.__enter__` implementation with a context manager's " +"own :meth:`~object.__exit__` method." +msgstr "" + +#: ../../library/contextlib.rst:575 +msgid "" +"If passed an object that is not a context manager, this method assumes it is " +"a callback with the same signature as a context " +"manager's :meth:`~object.__exit__` method and adds it directly to the " +"callback stack." +msgstr "" + +#: ../../library/contextlib.rst:579 +msgid "" +"By returning true values, these callbacks can suppress exceptions the same " +"way context manager :meth:`~object.__exit__` methods can." +msgstr "" + +#: ../../library/contextlib.rst:582 +msgid "" +"The passed in object is returned from the function, allowing this method to " +"be used as a function decorator." +msgstr "" + +#: ../../library/contextlib.rst:587 +msgid "" +"Accepts an arbitrary callback function and arguments and adds it to the " +"callback stack." +msgstr "" + +#: ../../library/contextlib.rst:590 +msgid "" +"Unlike the other methods, callbacks added this way cannot suppress " +"exceptions (as they are never passed the exception details)." +msgstr "" + +#: ../../library/contextlib.rst:593 +msgid "" +"The passed in callback is returned from the function, allowing this method " +"to be used as a function decorator." +msgstr "" + +#: ../../library/contextlib.rst:598 +msgid "" +"Transfers the callback stack to a fresh :class:`ExitStack` instance and " +"returns it. No callbacks are invoked by this operation - instead, they will " +"now be invoked when the new stack is closed (either explicitly or implicitly " +"at the end of a :keyword:`with` statement)." +msgstr "" + +#: ../../library/contextlib.rst:603 +msgid "" +"For example, a group of files can be opened as an \"all or nothing\" " +"operation as follows::" +msgstr "" + +#: ../../library/contextlib.rst:606 +msgid "" +"with ExitStack() as stack:\n" +" files = [stack.enter_context(open(fname)) for fname in filenames]\n" +" # Hold onto the close method, but don't call it yet.\n" +" close_files = stack.pop_all().close\n" +" # If opening any file fails, all previously opened files will be\n" +" # closed automatically. If all files are opened successfully,\n" +" # they will remain open even after the with statement ends.\n" +" # close_files() can then be invoked explicitly to close them all." +msgstr "" + +#: ../../library/contextlib.rst:617 +msgid "" +"Immediately unwinds the callback stack, invoking callbacks in the reverse " +"order of registration. For any context managers and exit callbacks " +"registered, the arguments passed in will indicate that no exception occurred." +msgstr "" + +#: ../../library/contextlib.rst:624 +msgid "" +"An :ref:`asynchronous context manager `, similar " +"to :class:`ExitStack`, that supports combining both synchronous and " +"asynchronous context managers, as well as having coroutines for cleanup " +"logic." +msgstr "" + +#: ../../library/contextlib.rst:629 +msgid "" +"The :meth:`~ExitStack.close` method is not implemented; :meth:`aclose` must " +"be used instead." +msgstr "" + +#: ../../library/contextlib.rst:635 +msgid "" +"Similar to :meth:`ExitStack.enter_context` but expects an asynchronous " +"context manager." +msgstr "" + +#: ../../library/contextlib.rst:638 +msgid "" +"Raises :exc:`TypeError` instead of :exc:`AttributeError` if *cm* is not an " +"asynchronous context manager." +msgstr "" + +#: ../../library/contextlib.rst:644 +msgid "" +"Similar to :meth:`ExitStack.push` but expects either an asynchronous context " +"manager or a coroutine function." +msgstr "" + +#: ../../library/contextlib.rst:649 +msgid "Similar to :meth:`ExitStack.callback` but expects a coroutine function." +msgstr "和 :meth:`ExitStack.callback` 類似，但預期接受一個協程函式。" + +#: ../../library/contextlib.rst:654 +msgid "Similar to :meth:`ExitStack.close` but properly handles awaitables." +msgstr "和 :meth:`ExitStack.close` 類似，但能夠正確處理可等待物件。" + +#: ../../library/contextlib.rst:656 +msgid "Continuing the example for :func:`asynccontextmanager`::" +msgstr "延續 :func:`asynccontextmanager` 的範例： ::" + +#: ../../library/contextlib.rst:658 +msgid "" +"async with AsyncExitStack() as stack:\n" +" connections = [await stack.enter_async_context(get_connection())\n" +" for i in range(5)]\n" +" # All opened connections will automatically be released at the end of\n" +" # the async with statement, even if attempts to open a connection\n" +" # later in the list raise an exception." +msgstr "" + +#: ../../library/contextlib.rst:668 +msgid "Examples and Recipes" +msgstr "" + +#: ../../library/contextlib.rst:670 +msgid "" +"This section describes some examples and recipes for making effective use of " +"the tools provided by :mod:`contextlib`." +msgstr "" + +#: ../../library/contextlib.rst:675 +msgid "Supporting a variable number of context managers" +msgstr "" + +#: ../../library/contextlib.rst:677 +msgid "" +"The primary use case for :class:`ExitStack` is the one given in the class " +"documentation: supporting a variable number of context managers and other " +"cleanup operations in a single :keyword:`with` statement. The variability " +"may come from the number of context managers needed being driven by user " +"input (such as opening a user specified collection of files), or from some " +"of the context managers being optional::" +msgstr "" + +#: ../../library/contextlib.rst:684 +msgid "" +"with ExitStack() as stack:\n" +" for resource in resources:\n" +" stack.enter_context(resource)\n" +" if need_special_resource():\n" +" special = acquire_special_resource()\n" +" stack.callback(release_special_resource, special)\n" +" # Perform operations that use the acquired resources" +msgstr "" + +#: ../../library/contextlib.rst:692 +msgid "" +"As shown, :class:`ExitStack` also makes it quite easy to use :keyword:`with` " +"statements to manage arbitrary resources that don't natively support the " +"context management protocol." +msgstr "" + +#: ../../library/contextlib.rst:698 +msgid "Catching exceptions from ``__enter__`` methods" +msgstr "" + +#: ../../library/contextlib.rst:700 +msgid "" +"It is occasionally desirable to catch exceptions from an ``__enter__`` " +"method implementation, *without* inadvertently catching exceptions from " +"the :keyword:`with` statement body or the context manager's ``__exit__`` " +"method. By using :class:`ExitStack` the steps in the context management " +"protocol can be separated slightly in order to allow this::" +msgstr "" + +#: ../../library/contextlib.rst:706 +msgid "" +"stack = ExitStack()\n" +"try:\n" +" x = stack.enter_context(cm)\n" +"except Exception:\n" +" # handle __enter__ exception\n" +"else:\n" +" with stack:\n" +" # Handle normal case" +msgstr "" + +#: ../../library/contextlib.rst:715 +msgid "" +"Actually needing to do this is likely to indicate that the underlying API " +"should be providing a direct resource management interface for use " +"with :keyword:`try`/:keyword:`except`/:keyword:`finally` statements, but not " +"all APIs are well designed in that regard. When a context manager is the " +"only resource management API provided, then :class:`ExitStack` can make it " +"easier to handle various situations that can't be handled directly in " +"a :keyword:`with` statement." +msgstr "" + +#: ../../library/contextlib.rst:725 +msgid "Cleaning up in an ``__enter__`` implementation" +msgstr "" + +#: ../../library/contextlib.rst:727 +msgid "" +"As noted in the documentation of :meth:`ExitStack.push`, this method can be " +"useful in cleaning up an already allocated resource if later steps in " +"the :meth:`~object.__enter__` implementation fail." +msgstr "" + +#: ../../library/contextlib.rst:731 +msgid "" +"Here's an example of doing this for a context manager that accepts resource " +"acquisition and release functions, along with an optional validation " +"function, and maps them to the context management protocol::" +msgstr "" + +#: ../../library/contextlib.rst:735 +msgid "" +"from contextlib import contextmanager, AbstractContextManager, ExitStack\n" +"\n" +"class ResourceManager(AbstractContextManager):\n" +"\n" +" def __init__(self, acquire_resource, release_resource, " +"check_resource_ok=None):\n" +" self.acquire_resource = acquire_resource\n" +" self.release_resource = release_resource\n" +" if check_resource_ok is None:\n" +" def check_resource_ok(resource):\n" +" return True\n" +" self.check_resource_ok = check_resource_ok\n" +"\n" +" @contextmanager\n" +" def _cleanup_on_error(self):\n" +" with ExitStack() as stack:\n" +" stack.push(self)\n" +" yield\n" +" # The validation check passed and didn't raise an exception\n" +" # Accordingly, we want to keep the resource, and pass it\n" +" # back to our caller\n" +" stack.pop_all()\n" +"\n" +" def __enter__(self):\n" +" resource = self.acquire_resource()\n" +" with self._cleanup_on_error():\n" +" if not self.check_resource_ok(resource):\n" +" msg = \"Failed validation for {!r}\"\n" +" raise RuntimeError(msg.format(resource))\n" +" return resource\n" +"\n" +" def __exit__(self, *exc_details):\n" +" # We don't need to duplicate any of our resource release logic\n" +" self.release_resource()" +msgstr "" + +#: ../../library/contextlib.rst:771 +msgid "Replacing any use of ``try-finally`` and flag variables" +msgstr "" + +#: ../../library/contextlib.rst:773 +msgid "" +"A pattern you will sometimes see is a ``try-finally`` statement with a flag " +"variable to indicate whether or not the body of the ``finally`` clause " +"should be executed. In its simplest form (that can't already be handled just " +"by using an ``except`` clause instead), it looks something like this::" +msgstr "" + +#: ../../library/contextlib.rst:778 +msgid "" +"cleanup_needed = True\n" +"try:\n" +" result = perform_operation()\n" +" if result:\n" +" cleanup_needed = False\n" +"finally:\n" +" if cleanup_needed:\n" +" cleanup_resources()" +msgstr "" +"cleanup_needed = True\n" +"try:\n" +" result = perform_operation()\n" +" if result:\n" +" cleanup_needed = False\n" +"finally:\n" +" if cleanup_needed:\n" +" cleanup_resources()" + +#: ../../library/contextlib.rst:787 +msgid "" +"As with any ``try`` statement based code, this can cause problems for " +"development and review, because the setup code and the cleanup code can end " +"up being separated by arbitrarily long sections of code." +msgstr "" + +#: ../../library/contextlib.rst:791 +msgid "" +":class:`ExitStack` makes it possible to instead register a callback for " +"execution at the end of a ``with`` statement, and then later decide to skip " +"executing that callback::" +msgstr "" + +#: ../../library/contextlib.rst:795 +msgid "" +"from contextlib import ExitStack\n" +"\n" +"with ExitStack() as stack:\n" +" stack.callback(cleanup_resources)\n" +" result = perform_operation()\n" +" if result:\n" +" stack.pop_all()" +msgstr "" +"from contextlib import ExitStack\n" +"\n" +"with ExitStack() as stack:\n" +" stack.callback(cleanup_resources)\n" +" result = perform_operation()\n" +" if result:\n" +" stack.pop_all()" + +#: ../../library/contextlib.rst:803 +msgid "" +"This allows the intended cleanup behaviour to be made explicit up front, " +"rather than requiring a separate flag variable." +msgstr "" + +#: ../../library/contextlib.rst:806 +msgid "" +"If a particular application uses this pattern a lot, it can be simplified " +"even further by means of a small helper class::" +msgstr "" + +#: ../../library/contextlib.rst:809 +msgid "" +"from contextlib import ExitStack\n" +"\n" +"class Callback(ExitStack):\n" +" def __init__(self, callback, /, *args, **kwds):\n" +" super().__init__()\n" +" self.callback(callback, *args, **kwds)\n" +"\n" +" def cancel(self):\n" +" self.pop_all()\n" +"\n" +"with Callback(cleanup_resources) as cb:\n" +" result = perform_operation()\n" +" if result:\n" +" cb.cancel()" +msgstr "" +"from contextlib import ExitStack\n" +"\n" +"class Callback(ExitStack):\n" +" def __init__(self, callback, /, *args, **kwds):\n" +" super().__init__()\n" +" self.callback(callback, *args, **kwds)\n" +"\n" +" def cancel(self):\n" +" self.pop_all()\n" +"\n" +"with Callback(cleanup_resources) as cb:\n" +" result = perform_operation()\n" +" if result:\n" +" cb.cancel()" + +#: ../../library/contextlib.rst:824 +msgid "" +"If the resource cleanup isn't already neatly bundled into a standalone " +"function, then it is still possible to use the decorator form " +"of :meth:`ExitStack.callback` to declare the resource cleanup in advance::" +msgstr "" + +#: ../../library/contextlib.rst:829 +msgid "" +"from contextlib import ExitStack\n" +"\n" +"with ExitStack() as stack:\n" +" @stack.callback\n" +" def cleanup_resources():\n" +" ...\n" +" result = perform_operation()\n" +" if result:\n" +" stack.pop_all()" +msgstr "" +"from contextlib import ExitStack\n" +"\n" +"with ExitStack() as stack:\n" +" @stack.callback\n" +" def cleanup_resources():\n" +" ...\n" +" result = perform_operation()\n" +" if result:\n" +" stack.pop_all()" + +#: ../../library/contextlib.rst:839 +msgid "" +"Due to the way the decorator protocol works, a callback function declared " +"this way cannot take any parameters. Instead, any resources to be released " +"must be accessed as closure variables." +msgstr "" + +#: ../../library/contextlib.rst:845 +msgid "Using a context manager as a function decorator" +msgstr "" + +#: ../../library/contextlib.rst:847 +msgid "" +":class:`ContextDecorator` makes it possible to use a context manager in both " +"an ordinary ``with`` statement and also as a function decorator." +msgstr "" + +#: ../../library/contextlib.rst:850 +msgid "" +"For example, it is sometimes useful to wrap functions or groups of " +"statements with a logger that can track the time of entry and time of exit. " +"Rather than writing both a function decorator and a context manager for the " +"task, inheriting from :class:`ContextDecorator` provides both capabilities " +"in a single definition::" +msgstr "" + +#: ../../library/contextlib.rst:856 +msgid "" +"from contextlib import ContextDecorator\n" +"import logging\n" +"\n" +"logging.basicConfig(level=logging.INFO)\n" +"\n" +"class track_entry_and_exit(ContextDecorator):\n" +" def __init__(self, name):\n" +" self.name = name\n" +"\n" +" def __enter__(self):\n" +" logging.info('Entering: %s', self.name)\n" +"\n" +" def __exit__(self, exc_type, exc, exc_tb):\n" +" logging.info('Exiting: %s', self.name)" +msgstr "" +"from contextlib import ContextDecorator\n" +"import logging\n" +"\n" +"logging.basicConfig(level=logging.INFO)\n" +"\n" +"class track_entry_and_exit(ContextDecorator):\n" +" def __init__(self, name):\n" +" self.name = name\n" +"\n" +" def __enter__(self):\n" +" logging.info('Entering: %s', self.name)\n" +"\n" +" def __exit__(self, exc_type, exc, exc_tb):\n" +" logging.info('Exiting: %s', self.name)" + +#: ../../library/contextlib.rst:871 +msgid "Instances of this class can be used as both a context manager::" +msgstr "" + +#: ../../library/contextlib.rst:873 +msgid "" +"with track_entry_and_exit('widget loader'):\n" +" print('Some time consuming activity goes here')\n" +" load_widget()" +msgstr "" +"with track_entry_and_exit('widget loader'):\n" +" print('Some time consuming activity goes here')\n" +" load_widget()" + +#: ../../library/contextlib.rst:877 +msgid "And also as a function decorator::" +msgstr "" + +#: ../../library/contextlib.rst:879 +msgid "" +"@track_entry_and_exit('widget loader')\n" +"def activity():\n" +" print('Some time consuming activity goes here')\n" +" load_widget()" +msgstr "" +"@track_entry_and_exit('widget loader')\n" +"def activity():\n" +" print('Some time consuming activity goes here')\n" +" load_widget()" + +#: ../../library/contextlib.rst:884 +msgid "" +"Note that there is one additional limitation when using context managers as " +"function decorators: there's no way to access the return value " +"of :meth:`~object.__enter__`. If that value is needed, then it is still " +"necessary to use an explicit ``with`` statement." +msgstr "" + +#: ../../library/contextlib.rst:891 +msgid ":pep:`343` - The \"with\" statement" +msgstr ":pep:`343` - \"with\" 陳述式" + +#: ../../library/contextlib.rst:892 +msgid "" +"The specification, background, and examples for the Python :keyword:`with` " +"statement." +msgstr "" + +#: ../../library/contextlib.rst:898 +msgid "Single use, reusable and reentrant context managers" +msgstr "" + +#: ../../library/contextlib.rst:900 +msgid "" +"Most context managers are written in a way that means they can only be used " +"effectively in a :keyword:`with` statement once. These single use context " +"managers must be created afresh each time they're used - attempting to use " +"them a second time will trigger an exception or otherwise not work correctly." +msgstr "" + +#: ../../library/contextlib.rst:906 +msgid "" +"This common limitation means that it is generally advisable to create " +"context managers directly in the header of the :keyword:`with` statement " +"where they are used (as shown in all of the usage examples above)." +msgstr "" + +#: ../../library/contextlib.rst:910 +msgid "" +"Files are an example of effectively single use context managers, since the " +"first :keyword:`with` statement will close the file, preventing any further " +"IO operations using that file object." +msgstr "" + +#: ../../library/contextlib.rst:914 +msgid "" +"Context managers created using :func:`contextmanager` are also single use " +"context managers, and will complain about the underlying generator failing " +"to yield if an attempt is made to use them a second time::" +msgstr "" + +#: ../../library/contextlib.rst:918 +msgid "" +">>> from contextlib import contextmanager\n" +">>> @contextmanager\n" +"... def singleuse():\n" +"... print(\"Before\")\n" +"... yield\n" +"... print(\"After\")\n" +"...\n" +">>> cm = singleuse()\n" +">>> with cm:\n" +"... pass\n" +"...\n" +"Before\n" +"After\n" +">>> with cm:\n" +"... pass\n" +"...\n" +"Traceback (most recent call last):\n" +" ...\n" +"RuntimeError: generator didn't yield" +msgstr "" +">>> from contextlib import contextmanager\n" +">>> @contextmanager\n" +"... def singleuse():\n" +"... print(\"Before\")\n" +"... yield\n" +"... print(\"After\")\n" +"...\n" +">>> cm = singleuse()\n" +">>> with cm:\n" +"... pass\n" +"...\n" +"Before\n" +"After\n" +">>> with cm:\n" +"... pass\n" +"...\n" +"Traceback (most recent call last):\n" +" ...\n" +"RuntimeError: generator didn't yield" + +#: ../../library/contextlib.rst:942 +msgid "Reentrant context managers" +msgstr "" + +#: ../../library/contextlib.rst:944 +msgid "" +"More sophisticated context managers may be \"reentrant\". These context " +"managers can not only be used in multiple :keyword:`with` statements, but " +"may also be used *inside* a :keyword:`!with` statement that is already using " +"the same context manager." +msgstr "" + +#: ../../library/contextlib.rst:949 +msgid "" +":class:`threading.RLock` is an example of a reentrant context manager, as " +"are :func:`suppress`, :func:`redirect_stdout`, and :func:`chdir`. Here's a " +"very simple example of reentrant use::" +msgstr "" + +#: ../../library/contextlib.rst:953 +msgid "" +">>> from contextlib import redirect_stdout\n" +">>> from io import StringIO\n" +">>> stream = StringIO()\n" +">>> write_to_stream = redirect_stdout(stream)\n" +">>> with write_to_stream:\n" +"... print(\"This is written to the stream rather than stdout\")\n" +"... with write_to_stream:\n" +"... print(\"This is also written to the stream\")\n" +"...\n" +">>> print(\"This is written directly to stdout\")\n" +"This is written directly to stdout\n" +">>> print(stream.getvalue())\n" +"This is written to the stream rather than stdout\n" +"This is also written to the stream" +msgstr "" +">>> from contextlib import redirect_stdout\n" +">>> from io import StringIO\n" +">>> stream = StringIO()\n" +">>> write_to_stream = redirect_stdout(stream)\n" +">>> with write_to_stream:\n" +"... print(\"This is written to the stream rather than stdout\")\n" +"... with write_to_stream:\n" +"... print(\"This is also written to the stream\")\n" +"...\n" +">>> print(\"This is written directly to stdout\")\n" +"This is written directly to stdout\n" +">>> print(stream.getvalue())\n" +"This is written to the stream rather than stdout\n" +"This is also written to the stream" + +#: ../../library/contextlib.rst:968 +msgid "" +"Real world examples of reentrancy are more likely to involve multiple " +"functions calling each other and hence be far more complicated than this " +"example." +msgstr "" + +#: ../../library/contextlib.rst:972 +msgid "" +"Note also that being reentrant is *not* the same thing as being thread " +"safe. :func:`redirect_stdout`, for example, is definitely not thread safe, " +"as it makes a global modification to the system state by " +"binding :data:`sys.stdout` to a different stream." +msgstr "" + +#: ../../library/contextlib.rst:981 +msgid "Reusable context managers" +msgstr "" + +#: ../../library/contextlib.rst:983 +msgid "" +"Distinct from both single use and reentrant context managers are " +"\"reusable\" context managers (or, to be completely explicit, \"reusable, " +"but not reentrant\" context managers, since reentrant context managers are " +"also reusable). These context managers support being used multiple times, " +"but will fail (or otherwise not work correctly) if the specific context " +"manager instance has already been used in a containing with statement." +msgstr "" + +#: ../../library/contextlib.rst:990 +msgid "" +":class:`threading.Lock` is an example of a reusable, but not reentrant, " +"context manager (for a reentrant lock, it is necessary to " +"use :class:`threading.RLock` instead)." +msgstr "" + +#: ../../library/contextlib.rst:994 +msgid "" +"Another example of a reusable, but not reentrant, context manager " +"is :class:`ExitStack`, as it invokes *all* currently registered callbacks " +"when leaving any with statement, regardless of where those callbacks were " +"added::" +msgstr "" + +#: ../../library/contextlib.rst:999 +msgid "" +">>> from contextlib import ExitStack\n" +">>> stack = ExitStack()\n" +">>> with stack:\n" +"... stack.callback(print, \"Callback: from first context\")\n" +"... print(\"Leaving first context\")\n" +"...\n" +"Leaving first context\n" +"Callback: from first context\n" +">>> with stack:\n" +"... stack.callback(print, \"Callback: from second context\")\n" +"... print(\"Leaving second context\")\n" +"...\n" +"Leaving second context\n" +"Callback: from second context\n" +">>> with stack:\n" +"... stack.callback(print, \"Callback: from outer context\")\n" +"... with stack:\n" +"... stack.callback(print, \"Callback: from inner context\")\n" +"... print(\"Leaving inner context\")\n" +"... print(\"Leaving outer context\")\n" +"...\n" +"Leaving inner context\n" +"Callback: from inner context\n" +"Callback: from outer context\n" +"Leaving outer context" +msgstr "" +">>> from contextlib import ExitStack\n" +">>> stack = ExitStack()\n" +">>> with stack:\n" +"... stack.callback(print, \"Callback: from first context\")\n" +"... print(\"Leaving first context\")\n" +"...\n" +"Leaving first context\n" +"Callback: from first context\n" +">>> with stack:\n" +"... stack.callback(print, \"Callback: from second context\")\n" +"... print(\"Leaving second context\")\n" +"...\n" +"Leaving second context\n" +"Callback: from second context\n" +">>> with stack:\n" +"... stack.callback(print, \"Callback: from outer context\")\n" +"... with stack:\n" +"... stack.callback(print, \"Callback: from inner context\")\n" +"... print(\"Leaving inner context\")\n" +"... print(\"Leaving outer context\")\n" +"...\n" +"Leaving inner context\n" +"Callback: from inner context\n" +"Callback: from outer context\n" +"Leaving outer context" + +#: ../../library/contextlib.rst:1025 +msgid "" +"As the output from the example shows, reusing a single stack object across " +"multiple with statements works correctly, but attempting to nest them will " +"cause the stack to be cleared at the end of the innermost with statement, " +"which is unlikely to be desirable behaviour." +msgstr "" + +#: ../../library/contextlib.rst:1030 +msgid "" +"Using separate :class:`ExitStack` instances instead of reusing a single " +"instance avoids that problem::" +msgstr "" + +#: ../../library/contextlib.rst:1033 +msgid "" +">>> from contextlib import ExitStack\n" +">>> with ExitStack() as outer_stack:\n" +"... outer_stack.callback(print, \"Callback: from outer context\")\n" +"... with ExitStack() as inner_stack:\n" +"... inner_stack.callback(print, \"Callback: from inner context\")\n" +"... print(\"Leaving inner context\")\n" +"... print(\"Leaving outer context\")\n" +"...\n" +"Leaving inner context\n" +"Callback: from inner context\n" +"Leaving outer context\n" +"Callback: from outer context" +msgstr "" +">>> from contextlib import ExitStack\n" +">>> with ExitStack() as outer_stack:\n" +"... outer_stack.callback(print, \"Callback: from outer context\")\n" +"... with ExitStack() as inner_stack:\n" +"... inner_stack.callback(print, \"Callback: from inner context\")\n" +"... print(\"Leaving inner context\")\n" +"... print(\"Leaving outer context\")\n" +"...\n" +"Leaving inner context\n" +"Callback: from inner context\n" +"Leaving outer context\n" +"Callback: from outer context" diff --git a/library/contextvars.po b/library/contextvars.po index e696043c84..e943b11cb5 100644 --- a/library/contextvars.po +++ b/library/contextvars.po @@ -1,559 +1,559 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: 2025-07-30 22:06+0800\n" -"Last-Translator: \n" -"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" -"tw)\n" -"Language: zh_TW\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=UTF-8\n" -"Content-Transfer-Encoding: 8bit\n" -"X-Generator: Poedit 3.6\n" - -#: ../../library/contextvars.rst:2 -msgid ":mod:`!contextvars` --- Context Variables" -msgstr ":mod:`!contextvars` --- 情境變數" - -#: ../../library/contextvars.rst:11 -msgid "" -"This module provides APIs to manage, store, and access context-local state. " -"The :class:`~contextvars.ContextVar` class is used to declare and work with " -"*Context Variables*. The :func:`~contextvars.copy_context` function and " -"the :class:`~contextvars.Context` class should be used to manage the current " -"context in asynchronous frameworks." -msgstr "" -"本模組供 API 來管理、儲存及存取單一情境各自的狀態（context-local state）。 " -"用 :class:`~contextvars.ContextVar` 類別宣告和處理\\ *情境變數" -"*。 :func:`~contextvars.copy_context` 函式和 :class:`~contextvars.Context` 類" -"別應在非同步框架中管理目前的情境。" - -#: ../../library/contextvars.rst:17 -msgid "" -"Context managers that have state should use Context Variables instead " -"of :func:`threading.local` to prevent their state from bleeding to other " -"code unexpectedly, when used in concurrent code." -msgstr "" -"帶有狀態的 Context Manager 應該使用情境變數，而不是 :func:`threading.local`，" -"才能防止它們的狀態在並行（concurrent）程式碼中使用時意外外溢並干擾到其他程式" -"碼。" - -#: ../../library/contextvars.rst:21 -msgid "See also :pep:`567` for additional details." -msgstr "其他詳細資訊，請參閱 :pep:`567`。" - -#: ../../library/contextvars.rst:27 -msgid "Context Variables" -msgstr "情境變數" - -#: ../../library/contextvars.rst:31 -msgid "This class is used to declare a new Context Variable, e.g.::" -msgstr "此類別用在宣告新的情境變數，例如：" - -#: ../../library/contextvars.rst:33 -msgid "var: ContextVar[int] = ContextVar('var', default=42)" -msgstr "var: ContextVar[int] = ContextVar('var', default=42)" - -#: ../../library/contextvars.rst:35 -msgid "" -"The required *name* parameter is used for introspection and debug purposes." -msgstr "必要參數 *name* 用於自我檢查（introspection）和除錯。" - -#: ../../library/contextvars.rst:38 -msgid "" -"The optional keyword-only *default* parameter is returned " -"by :meth:`ContextVar.get` when no value for the variable is found in the " -"current context." -msgstr "" -"當在目前的情境中找不到變數的值時，:meth:`ContextVar.get` 會回傳可選的僅限關鍵" -"字參數 *default*。" - -#: ../../library/contextvars.rst:42 -msgid "" -"**Important:** Context Variables should be created at the top module level " -"and never in closures. :class:`Context` objects hold strong references to " -"context variables which prevents context variables from being properly " -"garbage collected." -msgstr "" -"**重要：**\\ 情境變數應該在最頂端的模組層級建立，絕對不要在閉包（closure）中" -"建立。 :class:`Context` 物件持有情境變數的強參照，這會阻止情境變數被正確地垃" -"圾回收（garbage collected）。" - -#: ../../library/contextvars.rst:49 -msgid "The name of the variable. This is a read-only property." -msgstr "這個變數的名稱。這是一個唯讀屬性。" - -#: ../../library/contextvars.rst:55 -msgid "Return a value for the context variable for the current context." -msgstr "回傳目前情境的情境變數值。" - -#: ../../library/contextvars.rst:57 -msgid "" -"If there is no value for the variable in the current context, the method " -"will:" -msgstr "如果在目前情境中沒有變數的值，此方法將：" - -#: ../../library/contextvars.rst:60 -msgid "" -"return the value of the *default* argument of the method, if provided; or" -msgstr "回傳方法的 *default* 引數值（如果有的話）；否則" - -#: ../../library/contextvars.rst:63 -msgid "" -"return the default value for the context variable, if it was created with " -"one; or" -msgstr "回傳情境變數的預設值（如果建立情境變數時有指定預設值的話）；否則" - -#: ../../library/contextvars.rst:66 -msgid "raise a :exc:`LookupError`." -msgstr "會引發一個 :exc:`LookupError`。" - -#: ../../library/contextvars.rst:70 -msgid "" -"Call to set a new value for the context variable in the current context." -msgstr "在目前的情境中，呼叫以設定情境變數的新值。" - -#: ../../library/contextvars.rst:73 -msgid "" -"The required *value* argument is the new value for the context variable." -msgstr "*value* 屬必要引數，是情境變數的新值。" - -#: ../../library/contextvars.rst:76 -msgid "" -"Returns a :class:`~contextvars.Token` object that can be used to restore the " -"variable to its previous value via the :meth:`ContextVar.reset` method." -msgstr "" -"回傳一個 :class:`~contextvars.Token` 物件，該物件可透" -"過 :meth:`ContextVar.reset` 方法，用來將變數還原到之前的值。" - -#: ../../library/contextvars.rst:82 -msgid "" -"Reset the context variable to the value it had before " -"the :meth:`ContextVar.set` that created the *token* was used." -msgstr "將情境變數重設為使用 :meth:`ContextVar.set` 建立 *token* 前的值。" - -#: ../../library/contextvars.rst:85 -msgid "For example::" -msgstr "舉例來說： ::" - -#: ../../library/contextvars.rst:87 -msgid "" -"var = ContextVar('var')\n" -"\n" -"token = var.set('new value')\n" -"# code that uses 'var'; var.get() returns 'new value'.\n" -"var.reset(token)\n" -"\n" -"# After the reset call the var has no value again, so\n" -"# var.get() would raise a LookupError." -msgstr "" -"var = ContextVar('var')\n" -"\n" -"token = var.set('new value')\n" -"# 使用 'var' 的程式碼；var.get() 回傳 'new value'。\n" -"var.reset(token)\n" -"\n" -"# 在重設呼叫之後，var 又沒有值了，所以\n" -"# var.get() 會引發 LookupError。" - -#: ../../library/contextvars.rst:99 -msgid "" -"*Token* objects are returned by the :meth:`ContextVar.set` method. They can " -"be passed to the :meth:`ContextVar.reset` method to revert the value of the " -"variable to what it was before the corresponding *set*." -msgstr "" -"*Token* 物件由 :meth:`ContextVar.set` 方法回傳，可以傳遞" -"給 :meth:`ContextVar.reset` 方法，用以將變數的值還原為相對應的 *set* 之前的" -"值。" - -#: ../../library/contextvars.rst:104 -msgid "" -"The token supports :ref:`context manager protocol ` to " -"restore the corresponding context variable value at the exit " -"from :keyword:`with` block::" -msgstr "" - -#: ../../library/contextvars.rst:108 -msgid "" -"var = ContextVar('var', default='default value')\n" -"\n" -"with var.set('new value'):\n" -" assert var.get() == 'new value'\n" -"\n" -"assert var.get() == 'default value'" -msgstr "" -"var = ContextVar('var', default='default value')\n" -"\n" -"with var.set('new value'):\n" -" assert var.get() == 'new value'\n" -"\n" -"assert var.get() == 'default value'" - -#: ../../library/contextvars.rst:117 -msgid "Added support for usage as a context manager." -msgstr "新增對用作情境管理器的支援。" - -#: ../../library/contextvars.rst:121 -msgid "" -"A read-only property. Points to the :class:`ContextVar` object that created " -"the token." -msgstr "唯讀屬性。 指向建立 token 的 :class:`ContextVar` 物件。" - -#: ../../library/contextvars.rst:126 -msgid "" -"A read-only property. Set to the value the variable had before " -"the :meth:`ContextVar.set` method call that created the token. It points " -"to :attr:`Token.MISSING` if the variable was not set before the call." -msgstr "" -"唯讀屬性。 值為變數在呼叫 :meth:`ContextVar.set` 方法之前的值。如果變數在呼叫" -"前沒有設定，則指向 :attr:`Token.MISSING`。" - -#: ../../library/contextvars.rst:133 -msgid "A marker object used by :attr:`Token.old_value`." -msgstr "由 :attr:`Token.old_value` 使用的標記物件。" - -#: ../../library/contextvars.rst:137 -msgid "Manual Context Management" -msgstr "手動情境管理" - -#: ../../library/contextvars.rst:141 -msgid "Returns a copy of the current :class:`~contextvars.Context` object." -msgstr "回傳目前 :class:`~contextvars.Context` 物件的複本（copy）。" - -#: ../../library/contextvars.rst:143 -msgid "" -"The following snippet gets a copy of the current context and prints all " -"variables and their values that are set in it::" -msgstr "" -"以下程式碼片段會取得目前情境的複本，並顯示在其中設定的所有變數及其值：::" - -#: ../../library/contextvars.rst:146 -msgid "" -"ctx: Context = copy_context()\n" -"print(list(ctx.items()))" -msgstr "" -"ctx: Context = copy_context()\n" -"print(list(ctx.items()))" - -#: ../../library/contextvars.rst:149 -msgid "" -"The function has an *O*\\ (1) complexity, i.e. works equally fast for " -"contexts with a few context variables and for contexts that have a lot of " -"them." -msgstr "" -"這個函式具有 *O*\\ (1) 的複雜度，也就是說，對於只有少許情境變數的情境和有大量" -"情境變數的情境，速度都一樣快。" - -#: ../../library/contextvars.rst:156 -msgid "A mapping of :class:`ContextVars ` to their values." -msgstr ":class:`ContextVars` 到其值的映射。" - -#: ../../library/contextvars.rst:158 -msgid "" -"``Context()`` creates an empty context with no values in it. To get a copy " -"of the current context use the :func:`~contextvars.copy_context` function." -msgstr "" -"``Context()`` 會建立一個沒有值的空情境。要取得目前情境的複本，請使" -"用 :func:`~contextvars.copy_context` 函式。" - -#: ../../library/contextvars.rst:162 -msgid "" -"Each thread has its own effective stack of :class:`!Context` objects. " -"The :term:`current context` is the :class:`!Context` object at the top of " -"the current thread's stack. All :class:`!Context` objects in the stacks are " -"considered to be *entered*." -msgstr "" -"每個執行緒都有自己的 :class:`!Context` 物件中目前主控中的堆疊" -"（stack）。:term:`current context` 是目前執行緒堆疊頂端的 :class:`!Context` " -"物件。 堆疊中的所有 :class:`!Context` 物件都被視為\\ *已進入*。" - -#: ../../library/contextvars.rst:167 -msgid "" -"*Entering* a context, which can be done by calling its :meth:`~Context.run` " -"method, makes the context the current context by pushing it onto the top of " -"the current thread's context stack." -msgstr "" -"*進入*\\ 一個情境，可以藉由呼叫其 :meth:`~Context.run` 方法來完成，此\\ *進入" -"*\\ 的動作會將一情境推到目前執行緒的情境堆疊的頂端，使該情境成為目前的情境。" - -#: ../../library/contextvars.rst:171 -msgid "" -"*Exiting* from the current context, which can be done by returning from the " -"callback passed to the :meth:`~Context.run` method, restores the current " -"context to what it was before the context was entered by popping the context " -"off the top of the context stack." -msgstr "" -"如果你傳遞給 :meth:`~Context.run` 方法的回呼函式（callback functions），該函" -"式回傳之後，就會自動\\ *退出*\\ 目前的情境，這會將目前的情境還原到進入情境之" -"前的狀態，方法是將情境從情境堆疊的頂端彈出。" - -#: ../../library/contextvars.rst:176 -msgid "" -"Since each thread has its own context stack, :class:`ContextVar` objects " -"behave in a similar fashion to :func:`threading.local` when values are " -"assigned in different threads." -msgstr "" -"因為每個執行緒都有自己的情境堆疊，當值在不同的執行緒中被指定" -"時， :class:`ContextVar` 物件的行為與 :func:`threading.local` 相似。" - -#: ../../library/contextvars.rst:180 -msgid "" -"Attempting to enter an already entered context, including contexts entered " -"in other threads, raises a :exc:`RuntimeError`." -msgstr "" -"嘗試進入已進入的情境，包括在其他執行緒中進入的情境，會引" -"發 :exc:`RuntimeError`。" - -#: ../../library/contextvars.rst:183 -msgid "After exiting a context, it can later be re-entered (from any thread)." -msgstr "退出情境後，之後可以重新進入（從任何執行緒）。" - -#: ../../library/contextvars.rst:185 -msgid "" -"Any changes to :class:`ContextVar` values via the :meth:`ContextVar.set` " -"method are recorded in the current context. The :meth:`ContextVar.get` " -"method returns the value associated with the current context. Exiting a " -"context effectively reverts any changes made to context variables while the " -"context was entered (if needed, the values can be restored by re-entering " -"the context)." -msgstr "" -"任何透過 :meth:`ContextVar.set` 方法對 :class:`ContextVar` 值的改變都會記錄在" -"目前的情境中。 :meth:`ContextVar.get` 方法回傳與目前情境相關的值。 退出情境" -"實際造成的效果會像是將其在進入情境時對情境變數所做的任何變一一彈出並還原（如" -"果需要，可以透過重新進入情境來還原值）。" - -#: ../../library/contextvars.rst:192 -msgid "Context implements the :class:`collections.abc.Mapping` interface." -msgstr "情境（Context）實作了 :class:`collections.abc.Mapping` 介面。" - -#: ../../library/contextvars.rst:196 -msgid "" -"Enters the Context, executes ``callable(*args, **kwargs)``, then exits the " -"Context. Returns *callable*'s return value, or propagates an exception if " -"one occurred." -msgstr "" -"進入 Context，執行 ``callable(*args, **kwargs)``，然後退出 Context。 回傳 " -"*callable* 的回傳值，如果發生例外（exception），則傳播例外。" - -#: ../../library/contextvars.rst:200 -msgid "Example:" -msgstr "例如：" - -#: ../../library/contextvars.rst:202 -msgid "" -"import contextvars\n" -"\n" -"var = contextvars.ContextVar('var')\n" -"var.set('spam')\n" -"print(var.get()) # 'spam'\n" -"\n" -"ctx = contextvars.copy_context()\n" -"\n" -"def main():\n" -" # 'var' was set to 'spam' before\n" -" # calling 'copy_context()' and 'ctx.run(main)', so:\n" -" print(var.get()) # 'spam'\n" -" print(ctx[var]) # 'spam'\n" -"\n" -" var.set('ham')\n" -"\n" -" # Now, after setting 'var' to 'ham':\n" -" print(var.get()) # 'ham'\n" -" print(ctx[var]) # 'ham'\n" -"\n" -"# Any changes that the 'main' function makes to 'var'\n" -"# will be contained in 'ctx'.\n" -"ctx.run(main)\n" -"\n" -"# The 'main()' function was run in the 'ctx' context,\n" -"# so changes to 'var' are contained in it:\n" -"print(ctx[var]) # 'ham'\n" -"\n" -"# However, outside of 'ctx', 'var' is still set to 'spam':\n" -"print(var.get()) # 'spam'" -msgstr "" -"import contextvars\n" -"\n" -"var = contextvars.ContextVar('var')\n" -"var.set('spam')\n" -"print(var.get()) # 'spam'\n" -"\n" -"ctx = contextvars.copy_context()\n" -"\n" -"def main():\n" -" # 'var' 之前被設成 'spam'\n" -" # 呼叫 'copy_context()' 和 'ctx.run(main)'，所以：\n" -" print(var.get()) # 'spam'\n" -" print(ctx[var]) # 'spam'\n" -"\n" -" var.set('ham')\n" -"\n" -" # 現在, 在把 'var' 的值設成 'ham' 後:\n" -" print(var.get()) # 'ham'\n" -" print(ctx[var]) # 'ham'\n" -"\n" -"# 'main' 函式對 'var' 所做的任何變更都會\n" -"# 包含在 'ctx 裡：.\n" -"ctx.run(main)\n" -"\n" -"# 'main()' 函式是在 'ctx' 情境中執行，\n" -"# 所以對 'var' 的變更會保存在 'ctx' 中：\n" -"print(ctx[var]) # 'ham'\n" -"\n" -"# 但是，在 'ctx' 外, 'var' 的值仍然是 'spam':\n" -"print(var.get()) # 'spam'" - -#: ../../library/contextvars.rst:248 -msgid "Return a shallow copy of the context object." -msgstr "回傳情境物件的淺層複本（shallow copy）。" - -#: ../../library/contextvars.rst:252 -msgid "" -"Return ``True`` if the *context* has a value for *var* set; return ``False`` " -"otherwise." -msgstr "" -"如果\\ *情境*\\ 裡面有 *var* 的值，則回傳 ``True``，否則回傳 ``False``。" - -#: ../../library/contextvars.rst:257 -msgid "" -"Return the value of the *var* :class:`ContextVar` variable. If the variable " -"is not set in the context object, a :exc:`KeyError` is raised." -msgstr "" -"回傳 *var* :class:`ContextVar` 變數的值。如果該變數並沒有在情境物件中設定，則" -"會引發 :exc:`KeyError` 錯誤。" - -#: ../../library/contextvars.rst:263 -msgid "" -"Return the value for *var* if *var* has the value in the context object. " -"Return *default* otherwise. If *default* is not given, return ``None``." -msgstr "" -"如果 *var* 的值在情境物件中，則回傳 *var* 的值。否則回傳 *default*。如果沒有 " -"*default* 值，則回傳 ``None``。" - -#: ../../library/contextvars.rst:269 -msgid "Return an iterator over the variables stored in the context object." -msgstr "回傳儲存於情境物件中變數的疊代器。" - -#: ../../library/contextvars.rst:274 -msgid "Return the number of variables set in the context object." -msgstr "回傳情境物件中的變數個數。" - -#: ../../library/contextvars.rst:278 -msgid "Return a list of all variables in the context object." -msgstr "回傳情境物件中所有變數的串列。" - -#: ../../library/contextvars.rst:282 -msgid "Return a list of all variables' values in the context object." -msgstr "回傳情境物件中所有變數的值的串列。" - -#: ../../library/contextvars.rst:287 -msgid "" -"Return a list of 2-tuples containing all variables and their values in the " -"context object." -msgstr "回傳情境物件中所有變數與其值的 2-元組（2-tuples）的串列。" - -#: ../../library/contextvars.rst:292 -msgid "asyncio support" -msgstr "對 asyncio 的支援" - -#: ../../library/contextvars.rst:294 -msgid "" -"Context variables are natively supported in :mod:`asyncio` and are ready to " -"be used without any extra configuration. For example, here is a simple echo " -"server, that uses a context variable to make the address of a remote client " -"available in the Task that handles that client::" -msgstr "" -":mod:`asyncio` 原生支援情境變數，不需任何額外設定。 舉例來說，以下是一個簡單" -"的 echo 伺服器，使用情境變數讓遠端用戶端的位址在處理該用戶端的任務中可用：" - -#: ../../library/contextvars.rst:300 -msgid "" -"import asyncio\n" -"import contextvars\n" -"\n" -"client_addr_var = contextvars.ContextVar('client_addr')\n" -"\n" -"def render_goodbye():\n" -" # The address of the currently handled client can be accessed\n" -" # without passing it explicitly to this function.\n" -"\n" -" client_addr = client_addr_var.get()\n" -" return f'Good bye, client @ {client_addr}\\r\\n'.encode()\n" -"\n" -"async def handle_request(reader, writer):\n" -" addr = writer.transport.get_extra_info('socket').getpeername()\n" -" client_addr_var.set(addr)\n" -"\n" -" # In any code that we call is now possible to get\n" -" # client's address by calling 'client_addr_var.get()'.\n" -"\n" -" while True:\n" -" line = await reader.readline()\n" -" print(line)\n" -" if not line.strip():\n" -" break\n" -"\n" -" writer.write(b'HTTP/1.1 200 OK\\r\\n') # status line\n" -" writer.write(b'\\r\\n') # headers\n" -" writer.write(render_goodbye()) # body\n" -" writer.close()\n" -"\n" -"async def main():\n" -" srv = await asyncio.start_server(\n" -" handle_request, '127.0.0.1', 8081)\n" -"\n" -" async with srv:\n" -" await srv.serve_forever()\n" -"\n" -"asyncio.run(main())\n" -"\n" -"# To test it you can use telnet or curl:\n" -"# telnet 127.0.0.1 8081\n" -"# curl 127.0.0.1:8081" -msgstr "" -"import asyncio\n" -"import contextvars\n" -"\n" -"client_addr_var = contextvars.ContextVar('client_addr')\n" -"\n" -"def render_goodbye():\n" -" # 即使不把目前處理中的用戶端（client）傳入此函式\n" -" # 仍可取得其位址\n" -"\n" -" client_addr = client_addr_var.get()\n" -" return f'Good bye, client @ {client_addr}\\r\\n'.encode()\n" -"\n" -"async def handle_request(reader, writer):\n" -" addr = writer.transport.get_extra_info('socket').getpeername()\n" -" client_addr_var.set(addr)\n" -"\n" -" # 在任何我們呼叫的程式碼中，都可以\n" -" # 呼叫 'client_addr_var.get()' 來取得用戶端的位址\n" -"\n" -" while True:\n" -" line = await reader.readline()\n" -" print(line)\n" -" if not line.strip():\n" -" break\n" -"\n" -" writer.write(b'HTTP/1.1 200 OK\\r\\n') # status line\n" -" writer.write(b'\\r\\n') # headers\n" -" writer.write(render_goodbye()) # body\n" -" writer.close()\n" -"\n" -"async def main():\n" -" srv = await asyncio.start_server(\n" -" handle_request, '127.0.0.1', 8081)\n" -"\n" -" async with srv:\n" -" await srv.serve_forever()\n" -"\n" -"asyncio.run(main())\n" -"\n" -"# 你可以使用 telnet 或 curl 測試:\n" -"# telnet 127.0.0.1 8081\n" -"# curl 127.0.0.1:8081" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: 2025-07-30 22:06+0800\n" +"Last-Translator: \n" +"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" +"tw)\n" +"Language: zh_TW\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"X-Generator: Poedit 3.6\n" + +#: ../../library/contextvars.rst:2 +msgid ":mod:`!contextvars` --- Context Variables" +msgstr ":mod:`!contextvars` --- 情境變數" + +#: ../../library/contextvars.rst:11 +msgid "" +"This module provides APIs to manage, store, and access context-local state. " +"The :class:`~contextvars.ContextVar` class is used to declare and work with " +"*Context Variables*. The :func:`~contextvars.copy_context` function and " +"the :class:`~contextvars.Context` class should be used to manage the current " +"context in asynchronous frameworks." +msgstr "" +"本模組供 API 來管理、儲存及存取單一情境各自的狀態（context-local state）。 " +"用 :class:`~contextvars.ContextVar` 類別宣告和處理\\ *情境變數" +"*。 :func:`~contextvars.copy_context` 函式和 :class:`~contextvars.Context` 類" +"別應在非同步框架中管理目前的情境。" + +#: ../../library/contextvars.rst:17 +msgid "" +"Context managers that have state should use Context Variables instead " +"of :func:`threading.local` to prevent their state from bleeding to other " +"code unexpectedly, when used in concurrent code." +msgstr "" +"帶有狀態的 Context Manager 應該使用情境變數，而不是 :func:`threading.local`，" +"才能防止它們的狀態在並行（concurrent）程式碼中使用時意外外溢並干擾到其他程式" +"碼。" + +#: ../../library/contextvars.rst:21 +msgid "See also :pep:`567` for additional details." +msgstr "其他詳細資訊，請參閱 :pep:`567`。" + +#: ../../library/contextvars.rst:27 +msgid "Context Variables" +msgstr "情境變數" + +#: ../../library/contextvars.rst:31 +msgid "This class is used to declare a new Context Variable, e.g.::" +msgstr "此類別用在宣告新的情境變數，例如：" + +#: ../../library/contextvars.rst:33 +msgid "var: ContextVar[int] = ContextVar('var', default=42)" +msgstr "var: ContextVar[int] = ContextVar('var', default=42)" + +#: ../../library/contextvars.rst:35 +msgid "" +"The required *name* parameter is used for introspection and debug purposes." +msgstr "必要參數 *name* 用於自我檢查（introspection）和除錯。" + +#: ../../library/contextvars.rst:38 +msgid "" +"The optional keyword-only *default* parameter is returned " +"by :meth:`ContextVar.get` when no value for the variable is found in the " +"current context." +msgstr "" +"當在目前的情境中找不到變數的值時，:meth:`ContextVar.get` 會回傳可選的僅限關鍵" +"字參數 *default*。" + +#: ../../library/contextvars.rst:42 +msgid "" +"**Important:** Context Variables should be created at the top module level " +"and never in closures. :class:`Context` objects hold strong references to " +"context variables which prevents context variables from being properly " +"garbage collected." +msgstr "" +"**重要：**\\ 情境變數應該在最頂端的模組層級建立，絕對不要在閉包（closure）中" +"建立。 :class:`Context` 物件持有情境變數的強參照，這會阻止情境變數被正確地垃" +"圾回收（garbage collected）。" + +#: ../../library/contextvars.rst:49 +msgid "The name of the variable. This is a read-only property." +msgstr "這個變數的名稱。這是一個唯讀屬性。" + +#: ../../library/contextvars.rst:55 +msgid "Return a value for the context variable for the current context." +msgstr "回傳目前情境的情境變數值。" + +#: ../../library/contextvars.rst:57 +msgid "" +"If there is no value for the variable in the current context, the method " +"will:" +msgstr "如果在目前情境中沒有變數的值，此方法將：" + +#: ../../library/contextvars.rst:60 +msgid "" +"return the value of the *default* argument of the method, if provided; or" +msgstr "回傳方法的 *default* 引數值（如果有的話）；否則" + +#: ../../library/contextvars.rst:63 +msgid "" +"return the default value for the context variable, if it was created with " +"one; or" +msgstr "回傳情境變數的預設值（如果建立情境變數時有指定預設值的話）；否則" + +#: ../../library/contextvars.rst:66 +msgid "raise a :exc:`LookupError`." +msgstr "會引發一個 :exc:`LookupError`。" + +#: ../../library/contextvars.rst:70 +msgid "" +"Call to set a new value for the context variable in the current context." +msgstr "在目前的情境中，呼叫以設定情境變數的新值。" + +#: ../../library/contextvars.rst:73 +msgid "" +"The required *value* argument is the new value for the context variable." +msgstr "*value* 屬必要引數，是情境變數的新值。" + +#: ../../library/contextvars.rst:76 +msgid "" +"Returns a :class:`~contextvars.Token` object that can be used to restore the " +"variable to its previous value via the :meth:`ContextVar.reset` method." +msgstr "" +"回傳一個 :class:`~contextvars.Token` 物件，該物件可透" +"過 :meth:`ContextVar.reset` 方法，用來將變數還原到之前的值。" + +#: ../../library/contextvars.rst:82 +msgid "" +"Reset the context variable to the value it had before " +"the :meth:`ContextVar.set` that created the *token* was used." +msgstr "將情境變數重設為使用 :meth:`ContextVar.set` 建立 *token* 前的值。" + +#: ../../library/contextvars.rst:85 +msgid "For example::" +msgstr "舉例來說： ::" + +#: ../../library/contextvars.rst:87 +msgid "" +"var = ContextVar('var')\n" +"\n" +"token = var.set('new value')\n" +"# code that uses 'var'; var.get() returns 'new value'.\n" +"var.reset(token)\n" +"\n" +"# After the reset call the var has no value again, so\n" +"# var.get() would raise a LookupError." +msgstr "" +"var = ContextVar('var')\n" +"\n" +"token = var.set('new value')\n" +"# 使用 'var' 的程式碼；var.get() 回傳 'new value'。\n" +"var.reset(token)\n" +"\n" +"# 在重設呼叫之後，var 又沒有值了，所以\n" +"# var.get() 會引發 LookupError。" + +#: ../../library/contextvars.rst:99 +msgid "" +"*Token* objects are returned by the :meth:`ContextVar.set` method. They can " +"be passed to the :meth:`ContextVar.reset` method to revert the value of the " +"variable to what it was before the corresponding *set*." +msgstr "" +"*Token* 物件由 :meth:`ContextVar.set` 方法回傳，可以傳遞" +"給 :meth:`ContextVar.reset` 方法，用以將變數的值還原為相對應的 *set* 之前的" +"值。" + +#: ../../library/contextvars.rst:104 +msgid "" +"The token supports :ref:`context manager protocol ` to " +"restore the corresponding context variable value at the exit " +"from :keyword:`with` block::" +msgstr "" + +#: ../../library/contextvars.rst:108 +msgid "" +"var = ContextVar('var', default='default value')\n" +"\n" +"with var.set('new value'):\n" +" assert var.get() == 'new value'\n" +"\n" +"assert var.get() == 'default value'" +msgstr "" +"var = ContextVar('var', default='default value')\n" +"\n" +"with var.set('new value'):\n" +" assert var.get() == 'new value'\n" +"\n" +"assert var.get() == 'default value'" + +#: ../../library/contextvars.rst:117 +msgid "Added support for usage as a context manager." +msgstr "新增對用作情境管理器的支援。" + +#: ../../library/contextvars.rst:121 +msgid "" +"A read-only property. Points to the :class:`ContextVar` object that created " +"the token." +msgstr "唯讀屬性。 指向建立 token 的 :class:`ContextVar` 物件。" + +#: ../../library/contextvars.rst:126 +msgid "" +"A read-only property. Set to the value the variable had before " +"the :meth:`ContextVar.set` method call that created the token. It points " +"to :attr:`Token.MISSING` if the variable was not set before the call." +msgstr "" +"唯讀屬性。 值為變數在呼叫 :meth:`ContextVar.set` 方法之前的值。如果變數在呼叫" +"前沒有設定，則指向 :attr:`Token.MISSING`。" + +#: ../../library/contextvars.rst:133 +msgid "A marker object used by :attr:`Token.old_value`." +msgstr "由 :attr:`Token.old_value` 使用的標記物件。" + +#: ../../library/contextvars.rst:137 +msgid "Manual Context Management" +msgstr "手動情境管理" + +#: ../../library/contextvars.rst:141 +msgid "Returns a copy of the current :class:`~contextvars.Context` object." +msgstr "回傳目前 :class:`~contextvars.Context` 物件的複本（copy）。" + +#: ../../library/contextvars.rst:143 +msgid "" +"The following snippet gets a copy of the current context and prints all " +"variables and their values that are set in it::" +msgstr "" +"以下程式碼片段會取得目前情境的複本，並顯示在其中設定的所有變數及其值：::" + +#: ../../library/contextvars.rst:146 +msgid "" +"ctx: Context = copy_context()\n" +"print(list(ctx.items()))" +msgstr "" +"ctx: Context = copy_context()\n" +"print(list(ctx.items()))" + +#: ../../library/contextvars.rst:149 +msgid "" +"The function has an *O*\\ (1) complexity, i.e. works equally fast for " +"contexts with a few context variables and for contexts that have a lot of " +"them." +msgstr "" +"這個函式具有 *O*\\ (1) 的複雜度，也就是說，對於只有少許情境變數的情境和有大量" +"情境變數的情境，速度都一樣快。" + +#: ../../library/contextvars.rst:156 +msgid "A mapping of :class:`ContextVars ` to their values." +msgstr ":class:`ContextVars` 到其值的映射。" + +#: ../../library/contextvars.rst:158 +msgid "" +"``Context()`` creates an empty context with no values in it. To get a copy " +"of the current context use the :func:`~contextvars.copy_context` function." +msgstr "" +"``Context()`` 會建立一個沒有值的空情境。要取得目前情境的複本，請使" +"用 :func:`~contextvars.copy_context` 函式。" + +#: ../../library/contextvars.rst:162 +msgid "" +"Each thread has its own effective stack of :class:`!Context` objects. " +"The :term:`current context` is the :class:`!Context` object at the top of " +"the current thread's stack. All :class:`!Context` objects in the stacks are " +"considered to be *entered*." +msgstr "" +"每個執行緒都有自己的 :class:`!Context` 物件中目前主控中的堆疊" +"（stack）。:term:`current context` 是目前執行緒堆疊頂端的 :class:`!Context` " +"物件。 堆疊中的所有 :class:`!Context` 物件都被視為\\ *已進入*。" + +#: ../../library/contextvars.rst:167 +msgid "" +"*Entering* a context, which can be done by calling its :meth:`~Context.run` " +"method, makes the context the current context by pushing it onto the top of " +"the current thread's context stack." +msgstr "" +"*進入*\\ 一個情境，可以藉由呼叫其 :meth:`~Context.run` 方法來完成，此\\ *進入" +"*\\ 的動作會將一情境推到目前執行緒的情境堆疊的頂端，使該情境成為目前的情境。" + +#: ../../library/contextvars.rst:171 +msgid "" +"*Exiting* from the current context, which can be done by returning from the " +"callback passed to the :meth:`~Context.run` method, restores the current " +"context to what it was before the context was entered by popping the context " +"off the top of the context stack." +msgstr "" +"如果你傳遞給 :meth:`~Context.run` 方法的回呼函式（callback functions），該函" +"式回傳之後，就會自動\\ *退出*\\ 目前的情境，這會將目前的情境還原到進入情境之" +"前的狀態，方法是將情境從情境堆疊的頂端彈出。" + +#: ../../library/contextvars.rst:176 +msgid "" +"Since each thread has its own context stack, :class:`ContextVar` objects " +"behave in a similar fashion to :func:`threading.local` when values are " +"assigned in different threads." +msgstr "" +"因為每個執行緒都有自己的情境堆疊，當值在不同的執行緒中被指定" +"時， :class:`ContextVar` 物件的行為與 :func:`threading.local` 相似。" + +#: ../../library/contextvars.rst:180 +msgid "" +"Attempting to enter an already entered context, including contexts entered " +"in other threads, raises a :exc:`RuntimeError`." +msgstr "" +"嘗試進入已進入的情境，包括在其他執行緒中進入的情境，會引" +"發 :exc:`RuntimeError`。" + +#: ../../library/contextvars.rst:183 +msgid "After exiting a context, it can later be re-entered (from any thread)." +msgstr "退出情境後，之後可以重新進入（從任何執行緒）。" + +#: ../../library/contextvars.rst:185 +msgid "" +"Any changes to :class:`ContextVar` values via the :meth:`ContextVar.set` " +"method are recorded in the current context. The :meth:`ContextVar.get` " +"method returns the value associated with the current context. Exiting a " +"context effectively reverts any changes made to context variables while the " +"context was entered (if needed, the values can be restored by re-entering " +"the context)." +msgstr "" +"任何透過 :meth:`ContextVar.set` 方法對 :class:`ContextVar` 值的改變都會記錄在" +"目前的情境中。 :meth:`ContextVar.get` 方法回傳與目前情境相關的值。 退出情境" +"實際造成的效果會像是將其在進入情境時對情境變數所做的任何變一一彈出並還原（如" +"果需要，可以透過重新進入情境來還原值）。" + +#: ../../library/contextvars.rst:192 +msgid "Context implements the :class:`collections.abc.Mapping` interface." +msgstr "情境（Context）實作了 :class:`collections.abc.Mapping` 介面。" + +#: ../../library/contextvars.rst:196 +msgid "" +"Enters the Context, executes ``callable(*args, **kwargs)``, then exits the " +"Context. Returns *callable*'s return value, or propagates an exception if " +"one occurred." +msgstr "" +"進入 Context，執行 ``callable(*args, **kwargs)``，然後退出 Context。 回傳 " +"*callable* 的回傳值，如果發生例外（exception），則傳播例外。" + +#: ../../library/contextvars.rst:200 +msgid "Example:" +msgstr "例如：" + +#: ../../library/contextvars.rst:202 +msgid "" +"import contextvars\n" +"\n" +"var = contextvars.ContextVar('var')\n" +"var.set('spam')\n" +"print(var.get()) # 'spam'\n" +"\n" +"ctx = contextvars.copy_context()\n" +"\n" +"def main():\n" +" # 'var' was set to 'spam' before\n" +" # calling 'copy_context()' and 'ctx.run(main)', so:\n" +" print(var.get()) # 'spam'\n" +" print(ctx[var]) # 'spam'\n" +"\n" +" var.set('ham')\n" +"\n" +" # Now, after setting 'var' to 'ham':\n" +" print(var.get()) # 'ham'\n" +" print(ctx[var]) # 'ham'\n" +"\n" +"# Any changes that the 'main' function makes to 'var'\n" +"# will be contained in 'ctx'.\n" +"ctx.run(main)\n" +"\n" +"# The 'main()' function was run in the 'ctx' context,\n" +"# so changes to 'var' are contained in it:\n" +"print(ctx[var]) # 'ham'\n" +"\n" +"# However, outside of 'ctx', 'var' is still set to 'spam':\n" +"print(var.get()) # 'spam'" +msgstr "" +"import contextvars\n" +"\n" +"var = contextvars.ContextVar('var')\n" +"var.set('spam')\n" +"print(var.get()) # 'spam'\n" +"\n" +"ctx = contextvars.copy_context()\n" +"\n" +"def main():\n" +" # 'var' 之前被設成 'spam'\n" +" # 呼叫 'copy_context()' 和 'ctx.run(main)'，所以：\n" +" print(var.get()) # 'spam'\n" +" print(ctx[var]) # 'spam'\n" +"\n" +" var.set('ham')\n" +"\n" +" # 現在, 在把 'var' 的值設成 'ham' 後:\n" +" print(var.get()) # 'ham'\n" +" print(ctx[var]) # 'ham'\n" +"\n" +"# 'main' 函式對 'var' 所做的任何變更都會\n" +"# 包含在 'ctx 裡：.\n" +"ctx.run(main)\n" +"\n" +"# 'main()' 函式是在 'ctx' 情境中執行，\n" +"# 所以對 'var' 的變更會保存在 'ctx' 中：\n" +"print(ctx[var]) # 'ham'\n" +"\n" +"# 但是，在 'ctx' 外, 'var' 的值仍然是 'spam':\n" +"print(var.get()) # 'spam'" + +#: ../../library/contextvars.rst:248 +msgid "Return a shallow copy of the context object." +msgstr "回傳情境物件的淺層複本（shallow copy）。" + +#: ../../library/contextvars.rst:252 +msgid "" +"Return ``True`` if the *context* has a value for *var* set; return ``False`` " +"otherwise." +msgstr "" +"如果\\ *情境*\\ 裡面有 *var* 的值，則回傳 ``True``，否則回傳 ``False``。" + +#: ../../library/contextvars.rst:257 +msgid "" +"Return the value of the *var* :class:`ContextVar` variable. If the variable " +"is not set in the context object, a :exc:`KeyError` is raised." +msgstr "" +"回傳 *var* :class:`ContextVar` 變數的值。如果該變數並沒有在情境物件中設定，則" +"會引發 :exc:`KeyError` 錯誤。" + +#: ../../library/contextvars.rst:263 +msgid "" +"Return the value for *var* if *var* has the value in the context object. " +"Return *default* otherwise. If *default* is not given, return ``None``." +msgstr "" +"如果 *var* 的值在情境物件中，則回傳 *var* 的值。否則回傳 *default*。如果沒有 " +"*default* 值，則回傳 ``None``。" + +#: ../../library/contextvars.rst:269 +msgid "Return an iterator over the variables stored in the context object." +msgstr "回傳儲存於情境物件中變數的疊代器。" + +#: ../../library/contextvars.rst:274 +msgid "Return the number of variables set in the context object." +msgstr "回傳情境物件中的變數個數。" + +#: ../../library/contextvars.rst:278 +msgid "Return a list of all variables in the context object." +msgstr "回傳情境物件中所有變數的串列。" + +#: ../../library/contextvars.rst:282 +msgid "Return a list of all variables' values in the context object." +msgstr "回傳情境物件中所有變數的值的串列。" + +#: ../../library/contextvars.rst:287 +msgid "" +"Return a list of 2-tuples containing all variables and their values in the " +"context object." +msgstr "回傳情境物件中所有變數與其值的 2-元組（2-tuples）的串列。" + +#: ../../library/contextvars.rst:292 +msgid "asyncio support" +msgstr "對 asyncio 的支援" + +#: ../../library/contextvars.rst:294 +msgid "" +"Context variables are natively supported in :mod:`asyncio` and are ready to " +"be used without any extra configuration. For example, here is a simple echo " +"server, that uses a context variable to make the address of a remote client " +"available in the Task that handles that client::" +msgstr "" +":mod:`asyncio` 原生支援情境變數，不需任何額外設定。 舉例來說，以下是一個簡單" +"的 echo 伺服器，使用情境變數讓遠端用戶端的位址在處理該用戶端的任務中可用：" + +#: ../../library/contextvars.rst:300 +msgid "" +"import asyncio\n" +"import contextvars\n" +"\n" +"client_addr_var = contextvars.ContextVar('client_addr')\n" +"\n" +"def render_goodbye():\n" +" # The address of the currently handled client can be accessed\n" +" # without passing it explicitly to this function.\n" +"\n" +" client_addr = client_addr_var.get()\n" +" return f'Good bye, client @ {client_addr}\\r\\n'.encode()\n" +"\n" +"async def handle_request(reader, writer):\n" +" addr = writer.transport.get_extra_info('socket').getpeername()\n" +" client_addr_var.set(addr)\n" +"\n" +" # In any code that we call is now possible to get\n" +" # client's address by calling 'client_addr_var.get()'.\n" +"\n" +" while True:\n" +" line = await reader.readline()\n" +" print(line)\n" +" if not line.strip():\n" +" break\n" +"\n" +" writer.write(b'HTTP/1.1 200 OK\\r\\n') # status line\n" +" writer.write(b'\\r\\n') # headers\n" +" writer.write(render_goodbye()) # body\n" +" writer.close()\n" +"\n" +"async def main():\n" +" srv = await asyncio.start_server(\n" +" handle_request, '127.0.0.1', 8081)\n" +"\n" +" async with srv:\n" +" await srv.serve_forever()\n" +"\n" +"asyncio.run(main())\n" +"\n" +"# To test it you can use telnet or curl:\n" +"# telnet 127.0.0.1 8081\n" +"# curl 127.0.0.1:8081" +msgstr "" +"import asyncio\n" +"import contextvars\n" +"\n" +"client_addr_var = contextvars.ContextVar('client_addr')\n" +"\n" +"def render_goodbye():\n" +" # 即使不把目前處理中的用戶端（client）傳入此函式\n" +" # 仍可取得其位址\n" +"\n" +" client_addr = client_addr_var.get()\n" +" return f'Good bye, client @ {client_addr}\\r\\n'.encode()\n" +"\n" +"async def handle_request(reader, writer):\n" +" addr = writer.transport.get_extra_info('socket').getpeername()\n" +" client_addr_var.set(addr)\n" +"\n" +" # 在任何我們呼叫的程式碼中，都可以\n" +" # 呼叫 'client_addr_var.get()' 來取得用戶端的位址\n" +"\n" +" while True:\n" +" line = await reader.readline()\n" +" print(line)\n" +" if not line.strip():\n" +" break\n" +"\n" +" writer.write(b'HTTP/1.1 200 OK\\r\\n') # status line\n" +" writer.write(b'\\r\\n') # headers\n" +" writer.write(render_goodbye()) # body\n" +" writer.close()\n" +"\n" +"async def main():\n" +" srv = await asyncio.start_server(\n" +" handle_request, '127.0.0.1', 8081)\n" +"\n" +" async with srv:\n" +" await srv.serve_forever()\n" +"\n" +"asyncio.run(main())\n" +"\n" +"# 你可以使用 telnet 或 curl 測試:\n" +"# telnet 127.0.0.1 8081\n" +"# curl 127.0.0.1:8081" diff --git a/library/copy.po b/library/copy.po index 0d7aa89b79..9547b33835 100644 --- a/library/copy.po +++ b/library/copy.po @@ -1,229 +1,229 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Adrian Liaw , 2018 -# Matt Wang , 2022 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-06-27 07:36+0000\n" -"PO-Revision-Date: 2022-01-20 18:49+0800\n" -"Last-Translator: Matt Wang \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" -"X-Generator: Poedit 3.0.1\n" - -#: ../../library/copy.rst:2 -msgid ":mod:`!copy` --- Shallow and deep copy operations" -msgstr ":mod:`!copy` --- 淺層 (shallow) 和深層 (deep) 複製操作" - -#: ../../library/copy.rst:7 -msgid "**Source code:** :source:`Lib/copy.py`" -msgstr "**原始碼：**\\ :source:`Lib/copy.py`" - -#: ../../library/copy.rst:11 -msgid "" -"Assignment statements in Python do not copy objects, they create bindings " -"between a target and an object. For collections that are mutable or contain " -"mutable items, a copy is sometimes needed so one can change one copy without " -"changing the other. This module provides generic shallow and deep copy " -"operations (explained below)." -msgstr "" -"Python 的賦值陳述式不複製物件，而是建立目標和物件的繫結 (binding) 關係。對於" -"可變 (mutable) 或包含可變項目 (mutable item) 的集合，有時會需要一份副本來改變" -"特定副本，而不必改變其他副本。本模組提供了通用的淺層複製和深層複製操作（如下" -"所述）。" - -#: ../../library/copy.rst:18 -msgid "Interface summary:" -msgstr "介面摘要：" - -#: ../../library/copy.rst:22 -msgid "Return a shallow copy of *obj*." -msgstr "回傳 *obj* 的淺層複製。" - -#: ../../library/copy.rst:27 -msgid "Return a deep copy of *obj*." -msgstr "回傳 *obj* 的深層複製。" - -#: ../../library/copy.rst:32 -msgid "" -"Creates a new object of the same type as *obj*, replacing fields with values " -"from *changes*." -msgstr "" - -#: ../../library/copy.rst:40 -msgid "Raised for module specific errors." -msgstr "引發針對特定模組的錯誤。" - -#: ../../library/copy.rst:44 -msgid "" -"The difference between shallow and deep copying is only relevant for " -"compound objects (objects that contain other objects, like lists or class " -"instances):" -msgstr "" -"淺層與深層複製的區別僅與複合物件（即包含 list 或類別的實例等其他物件的物件）" -"相關：" - -#: ../../library/copy.rst:47 -msgid "" -"A *shallow copy* constructs a new compound object and then (to the extent " -"possible) inserts *references* into it to the objects found in the original." -msgstr "" -"*淺層複製*\\ 建構一個新的複合物件，然後（在儘可能的範圍內）將原始物件中找到的" -"物件的\\ *參照*\\ 插入其中。" - -#: ../../library/copy.rst:50 -msgid "" -"A *deep copy* constructs a new compound object and then, recursively, " -"inserts *copies* into it of the objects found in the original." -msgstr "" -"*深層複製*\\ 建構一個新的複合物件，然後遞迴地將在原始物件裡找到的物件的\\ *副" -"本*\\ 插入其中。" - -#: ../../library/copy.rst:53 -msgid "" -"Two problems often exist with deep copy operations that don't exist with " -"shallow copy operations:" -msgstr "深層複製操作通常存在兩個問題，而淺層複製操作並不存在這些問題：" - -#: ../../library/copy.rst:56 -msgid "" -"Recursive objects (compound objects that, directly or indirectly, contain a " -"reference to themselves) may cause a recursive loop." -msgstr "遞迴物件（直接或間接包含對自身參照的複合物件）可能會導致遞迴迴圈。" - -#: ../../library/copy.rst:59 -msgid "" -"Because deep copy copies everything it may copy too much, such as data which " -"is intended to be shared between copies." -msgstr "" -"由於深層複製會複製所有內容，因此可能會有過多複製（例如應該在副本之間共享的資" -"料）。" - -#: ../../library/copy.rst:62 -msgid "The :func:`deepcopy` function avoids these problems by:" -msgstr ":func:`deepcopy` 函式用以下方式避免了這些問題：" - -#: ../../library/copy.rst:64 -msgid "" -"keeping a ``memo`` dictionary of objects already copied during the current " -"copying pass; and" -msgstr "保留在目前複製過程中已複製的物件的 ``memo`` 字典；以及" - -#: ../../library/copy.rst:67 -msgid "" -"letting user-defined classes override the copying operation or the set of " -"components copied." -msgstr "允許使用者定義的類別複寫 (override) 複製操作或複製的元件集合。" - -#: ../../library/copy.rst:70 -msgid "" -"This module does not copy types like module, method, stack trace, stack " -"frame, file, socket, window, or any similar types. It does \"copy\" " -"functions and classes (shallow and deeply), by returning the original object " -"unchanged; this is compatible with the way these are treated by the :mod:" -"`pickle` module." -msgstr "" -"該模組不複製模組、方法、堆疊追蹤（stack trace）、堆疊框（stack frame）、檔" -"案、socket、視窗、陣列以及任何類似的型別。它透過不變更原始物件並將其回傳來" -"（淺層或深層地）\"複製\"函式和類別；這與 :mod:`pickle` 模組處理這類問題的方式" -"是相似的。" - -#: ../../library/copy.rst:75 -msgid "" -"Shallow copies of dictionaries can be made using :meth:`dict.copy`, and of " -"lists by assigning a slice of the entire list, for example, ``copied_list = " -"original_list[:]``." -msgstr "" -"字典的淺層複製可以使用 :meth:`dict.copy`\\，而 list 的淺層複製可以透過賦值整" -"個 list 的切片 (slice) 完成，例如，``copied_list = original_list[:]``。" - -#: ../../library/copy.rst:81 -msgid "" -"Classes can use the same interfaces to control copying that they use to " -"control pickling. See the description of module :mod:`pickle` for " -"information on these methods. In fact, the :mod:`copy` module uses the " -"registered pickle functions from the :mod:`copyreg` module." -msgstr "" -"類別可以使用與操作 pickle 相同的介面來控制複製操作，關於這些方法的描述資訊請" -"參考 :mod:`pickle` 模組。實際上，:mod:`copy` 模組使用的正是從 :mod:`copyreg` " -"模組中註冊的 pickle 函式。" - -#: ../../library/copy.rst:92 -msgid "" -"In order for a class to define its own copy implementation, it can define " -"special methods :meth:`~object.__copy__` and :meth:`~object.__deepcopy__`." -msgstr "" - -#: ../../library/copy.rst:98 -msgid "" -"Called to implement the shallow copy operation; no additional arguments are " -"passed." -msgstr "" - -#: ../../library/copy.rst:104 -msgid "" -"Called to implement the deep copy operation; it is passed one argument, the " -"*memo* dictionary. If the ``__deepcopy__`` implementation needs to make a " -"deep copy of a component, it should call the :func:`~copy.deepcopy` function " -"with the component as first argument and the *memo* dictionary as second " -"argument. The *memo* dictionary should be treated as an opaque object." -msgstr "" -"用來實作深層複製操作；它會傳遞一個引數，即 *memo* 字典。如果 " -"``__deepcopy__`` 實現需要建立一個元件的深層複製，它應當呼叫 :func:`~copy." -"deepcopy` 函式並以該元件作為第一個引數、以該 *memo* 字典作為第二個引數。*memo* " -"字典應當被當作不透明物件 (opaque object) 來處理" - -#: ../../library/copy.rst:114 -msgid "" -"Function :func:`!copy.replace` is more limited than :func:`~copy.copy` and :" -"func:`~copy.deepcopy`, and only supports named tuples created by :func:" -"`~collections.namedtuple`, :mod:`dataclasses`, and other classes which " -"define method :meth:`~object.__replace__`." -msgstr "" - -#: ../../library/copy.rst:122 -msgid "" -"This method should create a new object of the same type, replacing fields " -"with values from *changes*." -msgstr "" - -#: ../../library/copy.rst:130 -msgid "Module :mod:`pickle`" -msgstr ":mod:`pickle` 模組" - -#: ../../library/copy.rst:131 -msgid "" -"Discussion of the special methods used to support object state retrieval and " -"restoration." -msgstr "" -"支援物件之狀態檢索 (state retrieval) 和恢復 (restoration) 相關特殊方法的討" -"論。" - -#: ../../library/copy.rst:79 -msgid "module" -msgstr "module（模組）" - -#: ../../library/copy.rst:79 -msgid "pickle" -msgstr "pickle" - -#: ../../library/copy.rst:86 -msgid "__copy__() (copy protocol)" -msgstr "__copy__() （複製協定）" - -#: ../../library/copy.rst:86 -msgid "__deepcopy__() (copy protocol)" -msgstr "__deepcopy__() （複製協定）" - -#: ../../library/copy.rst:111 -msgid "__replace__() (replace protocol)" -msgstr "__replace__() （取代協定）" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Adrian Liaw , 2018 +# Matt Wang , 2022 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-06-27 07:36+0000\n" +"PO-Revision-Date: 2022-01-20 18:49+0800\n" +"Last-Translator: Matt Wang \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" +"X-Generator: Poedit 3.0.1\n" + +#: ../../library/copy.rst:2 +msgid ":mod:`!copy` --- Shallow and deep copy operations" +msgstr ":mod:`!copy` --- 淺層 (shallow) 和深層 (deep) 複製操作" + +#: ../../library/copy.rst:7 +msgid "**Source code:** :source:`Lib/copy.py`" +msgstr "**原始碼：**\\ :source:`Lib/copy.py`" + +#: ../../library/copy.rst:11 +msgid "" +"Assignment statements in Python do not copy objects, they create bindings " +"between a target and an object. For collections that are mutable or contain " +"mutable items, a copy is sometimes needed so one can change one copy without " +"changing the other. This module provides generic shallow and deep copy " +"operations (explained below)." +msgstr "" +"Python 的賦值陳述式不複製物件，而是建立目標和物件的繫結 (binding) 關係。對於" +"可變 (mutable) 或包含可變項目 (mutable item) 的集合，有時會需要一份副本來改變" +"特定副本，而不必改變其他副本。本模組提供了通用的淺層複製和深層複製操作（如下" +"所述）。" + +#: ../../library/copy.rst:18 +msgid "Interface summary:" +msgstr "介面摘要：" + +#: ../../library/copy.rst:22 +msgid "Return a shallow copy of *obj*." +msgstr "回傳 *obj* 的淺層複製。" + +#: ../../library/copy.rst:27 +msgid "Return a deep copy of *obj*." +msgstr "回傳 *obj* 的深層複製。" + +#: ../../library/copy.rst:32 +msgid "" +"Creates a new object of the same type as *obj*, replacing fields with values " +"from *changes*." +msgstr "" + +#: ../../library/copy.rst:40 +msgid "Raised for module specific errors." +msgstr "引發針對特定模組的錯誤。" + +#: ../../library/copy.rst:44 +msgid "" +"The difference between shallow and deep copying is only relevant for " +"compound objects (objects that contain other objects, like lists or class " +"instances):" +msgstr "" +"淺層與深層複製的區別僅與複合物件（即包含 list 或類別的實例等其他物件的物件）" +"相關：" + +#: ../../library/copy.rst:47 +msgid "" +"A *shallow copy* constructs a new compound object and then (to the extent " +"possible) inserts *references* into it to the objects found in the original." +msgstr "" +"*淺層複製*\\ 建構一個新的複合物件，然後（在儘可能的範圍內）將原始物件中找到的" +"物件的\\ *參照*\\ 插入其中。" + +#: ../../library/copy.rst:50 +msgid "" +"A *deep copy* constructs a new compound object and then, recursively, " +"inserts *copies* into it of the objects found in the original." +msgstr "" +"*深層複製*\\ 建構一個新的複合物件，然後遞迴地將在原始物件裡找到的物件的\\ *副" +"本*\\ 插入其中。" + +#: ../../library/copy.rst:53 +msgid "" +"Two problems often exist with deep copy operations that don't exist with " +"shallow copy operations:" +msgstr "深層複製操作通常存在兩個問題，而淺層複製操作並不存在這些問題：" + +#: ../../library/copy.rst:56 +msgid "" +"Recursive objects (compound objects that, directly or indirectly, contain a " +"reference to themselves) may cause a recursive loop." +msgstr "遞迴物件（直接或間接包含對自身參照的複合物件）可能會導致遞迴迴圈。" + +#: ../../library/copy.rst:59 +msgid "" +"Because deep copy copies everything it may copy too much, such as data which " +"is intended to be shared between copies." +msgstr "" +"由於深層複製會複製所有內容，因此可能會有過多複製（例如應該在副本之間共享的資" +"料）。" + +#: ../../library/copy.rst:62 +msgid "The :func:`deepcopy` function avoids these problems by:" +msgstr ":func:`deepcopy` 函式用以下方式避免了這些問題：" + +#: ../../library/copy.rst:64 +msgid "" +"keeping a ``memo`` dictionary of objects already copied during the current " +"copying pass; and" +msgstr "保留在目前複製過程中已複製的物件的 ``memo`` 字典；以及" + +#: ../../library/copy.rst:67 +msgid "" +"letting user-defined classes override the copying operation or the set of " +"components copied." +msgstr "允許使用者定義的類別複寫 (override) 複製操作或複製的元件集合。" + +#: ../../library/copy.rst:70 +msgid "" +"This module does not copy types like module, method, stack trace, stack " +"frame, file, socket, window, or any similar types. It does \"copy\" " +"functions and classes (shallow and deeply), by returning the original object " +"unchanged; this is compatible with the way these are treated by the :mod:" +"`pickle` module." +msgstr "" +"該模組不複製模組、方法、堆疊追蹤（stack trace）、堆疊框（stack frame）、檔" +"案、socket、視窗、陣列以及任何類似的型別。它透過不變更原始物件並將其回傳來" +"（淺層或深層地）\"複製\"函式和類別；這與 :mod:`pickle` 模組處理這類問題的方式" +"是相似的。" + +#: ../../library/copy.rst:75 +msgid "" +"Shallow copies of dictionaries can be made using :meth:`dict.copy`, and of " +"lists by assigning a slice of the entire list, for example, ``copied_list = " +"original_list[:]``." +msgstr "" +"字典的淺層複製可以使用 :meth:`dict.copy`\\，而 list 的淺層複製可以透過賦值整" +"個 list 的切片 (slice) 完成，例如，``copied_list = original_list[:]``。" + +#: ../../library/copy.rst:81 +msgid "" +"Classes can use the same interfaces to control copying that they use to " +"control pickling. See the description of module :mod:`pickle` for " +"information on these methods. In fact, the :mod:`copy` module uses the " +"registered pickle functions from the :mod:`copyreg` module." +msgstr "" +"類別可以使用與操作 pickle 相同的介面來控制複製操作，關於這些方法的描述資訊請" +"參考 :mod:`pickle` 模組。實際上，:mod:`copy` 模組使用的正是從 :mod:`copyreg` " +"模組中註冊的 pickle 函式。" + +#: ../../library/copy.rst:92 +msgid "" +"In order for a class to define its own copy implementation, it can define " +"special methods :meth:`~object.__copy__` and :meth:`~object.__deepcopy__`." +msgstr "" + +#: ../../library/copy.rst:98 +msgid "" +"Called to implement the shallow copy operation; no additional arguments are " +"passed." +msgstr "" + +#: ../../library/copy.rst:104 +msgid "" +"Called to implement the deep copy operation; it is passed one argument, the " +"*memo* dictionary. If the ``__deepcopy__`` implementation needs to make a " +"deep copy of a component, it should call the :func:`~copy.deepcopy` function " +"with the component as first argument and the *memo* dictionary as second " +"argument. The *memo* dictionary should be treated as an opaque object." +msgstr "" +"用來實作深層複製操作；它會傳遞一個引數，即 *memo* 字典。如果 " +"``__deepcopy__`` 實現需要建立一個元件的深層複製，它應當呼叫 :func:`~copy." +"deepcopy` 函式並以該元件作為第一個引數、以該 *memo* 字典作為第二個引數。*memo* " +"字典應當被當作不透明物件 (opaque object) 來處理" + +#: ../../library/copy.rst:114 +msgid "" +"Function :func:`!copy.replace` is more limited than :func:`~copy.copy` and :" +"func:`~copy.deepcopy`, and only supports named tuples created by :func:" +"`~collections.namedtuple`, :mod:`dataclasses`, and other classes which " +"define method :meth:`~object.__replace__`." +msgstr "" + +#: ../../library/copy.rst:122 +msgid "" +"This method should create a new object of the same type, replacing fields " +"with values from *changes*." +msgstr "" + +#: ../../library/copy.rst:130 +msgid "Module :mod:`pickle`" +msgstr ":mod:`pickle` 模組" + +#: ../../library/copy.rst:131 +msgid "" +"Discussion of the special methods used to support object state retrieval and " +"restoration." +msgstr "" +"支援物件之狀態檢索 (state retrieval) 和恢復 (restoration) 相關特殊方法的討" +"論。" + +#: ../../library/copy.rst:79 +msgid "module" +msgstr "module（模組）" + +#: ../../library/copy.rst:79 +msgid "pickle" +msgstr "pickle" + +#: ../../library/copy.rst:86 +msgid "__copy__() (copy protocol)" +msgstr "__copy__() （複製協定）" + +#: ../../library/copy.rst:86 +msgid "__deepcopy__() (copy protocol)" +msgstr "__deepcopy__() （複製協定）" + +#: ../../library/copy.rst:111 +msgid "__replace__() (replace protocol)" +msgstr "__replace__() （取代協定）" diff --git a/library/copyreg.po b/library/copyreg.po index eb99e7b7fc..ca5e45bd19 100644 --- a/library/copyreg.po +++ b/library/copyreg.po @@ -1,99 +1,99 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Liang-Bo Wang , 2016 -# Matt Wang , 2023 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-05-09 00:03+0000\n" -"PO-Revision-Date: 2023-12-29 00:29+0000\n" -"Last-Translator: Matt Wang \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/copyreg.rst:2 -msgid ":mod:`!copyreg` --- Register :mod:`!pickle` support functions" -msgstr ":mod:`!copyreg` --- 註冊 :mod:`pickle` 支援函式" - -#: ../../library/copyreg.rst:7 -msgid "**Source code:** :source:`Lib/copyreg.py`" -msgstr "**原始碼：**\\ :source:`Lib/copyreg.py`" - -#: ../../library/copyreg.rst:15 -msgid "" -"The :mod:`copyreg` module offers a way to define functions used while " -"pickling specific objects. The :mod:`pickle` and :mod:`copy` modules use " -"those functions when pickling/copying those objects. The module provides " -"configuration information about object constructors which are not classes. " -"Such constructors may be factory functions or class instances." -msgstr "" -":mod:`copyreg` 模組提供了一種用以定義在 pickle 特定物件時使用之函式的方式。:" -"mod:`pickle` 和 :mod:`copy` 模組在 pickle/copy 這些物件時使用這些函式。此模組" -"提供有關非類別物件之建構函式的配置資訊。此類建構函式可以是工廠函式 (factory " -"function) 或類別實例。" - -#: ../../library/copyreg.rst:24 -msgid "" -"Declares *object* to be a valid constructor. If *object* is not callable " -"(and hence not valid as a constructor), raises :exc:`TypeError`." -msgstr "" -"宣告 *object* 是一個有效的建構函式。如果 *object* 不可呼叫（因此不可作為有效" -"的建構函式），則會引發 :exc:`TypeError`。" - -#: ../../library/copyreg.rst:30 -msgid "" -"Declares that *function* should be used as a \"reduction\" function for " -"objects of type *type*. *function* must return either a string or a tuple " -"containing between two and six elements. See the :attr:`~pickle.Pickler." -"dispatch_table` for more details on the interface of *function*." -msgstr "" -"宣告 *function* 應該用作 *type* 型別之物件的「歸約 (\"reduction\")」函式。" -"*function* 必須回傳字串或包含 2 到 6 個元素的元組。有關 *function* 介面的更多" -"詳細資訊，請參閱 :attr:`~pickle.Pickler.dispatch_table`。" - -#: ../../library/copyreg.rst:35 -msgid "" -"The *constructor_ob* parameter is a legacy feature and is now ignored, but " -"if passed it must be a callable." -msgstr "" -"*constructor_ob* 參數是一個遺留功能，現在已被忽略，但如果要傳遞它的話則必須是" -"個可呼叫物件。" - -#: ../../library/copyreg.rst:38 -msgid "" -"Note that the :attr:`~pickle.Pickler.dispatch_table` attribute of a pickler " -"object or subclass of :class:`pickle.Pickler` can also be used for declaring " -"reduction functions." -msgstr "" -"請注意，pickler 物件或 :class:`pickle.Pickler` 子類別的 :attr:`~pickle." -"Pickler.dispatch_table` 屬性也可用於宣告歸約函式。" - -#: ../../library/copyreg.rst:43 -msgid "Example" -msgstr "範例" - -#: ../../library/copyreg.rst:45 -msgid "" -"The example below would like to show how to register a pickle function and " -"how it will be used:" -msgstr "下面範例展示如何註冊一個 pickle 函式以及如何使用它：" - -#: ../../library/copyreg.rst:9 -msgid "module" -msgstr "module（模組）" - -#: ../../library/copyreg.rst:9 -msgid "pickle" -msgstr "pickle" - -#: ../../library/copyreg.rst:9 -msgid "copy" -msgstr "copy（複製）" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Liang-Bo Wang , 2016 +# Matt Wang , 2023 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-05-09 00:03+0000\n" +"PO-Revision-Date: 2023-12-29 00:29+0000\n" +"Last-Translator: Matt Wang \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/copyreg.rst:2 +msgid ":mod:`!copyreg` --- Register :mod:`!pickle` support functions" +msgstr ":mod:`!copyreg` --- 註冊 :mod:`pickle` 支援函式" + +#: ../../library/copyreg.rst:7 +msgid "**Source code:** :source:`Lib/copyreg.py`" +msgstr "**原始碼：**\\ :source:`Lib/copyreg.py`" + +#: ../../library/copyreg.rst:15 +msgid "" +"The :mod:`copyreg` module offers a way to define functions used while " +"pickling specific objects. The :mod:`pickle` and :mod:`copy` modules use " +"those functions when pickling/copying those objects. The module provides " +"configuration information about object constructors which are not classes. " +"Such constructors may be factory functions or class instances." +msgstr "" +":mod:`copyreg` 模組提供了一種用以定義在 pickle 特定物件時使用之函式的方式。:" +"mod:`pickle` 和 :mod:`copy` 模組在 pickle/copy 這些物件時使用這些函式。此模組" +"提供有關非類別物件之建構函式的配置資訊。此類建構函式可以是工廠函式 (factory " +"function) 或類別實例。" + +#: ../../library/copyreg.rst:24 +msgid "" +"Declares *object* to be a valid constructor. If *object* is not callable " +"(and hence not valid as a constructor), raises :exc:`TypeError`." +msgstr "" +"宣告 *object* 是一個有效的建構函式。如果 *object* 不可呼叫（因此不可作為有效" +"的建構函式），則會引發 :exc:`TypeError`。" + +#: ../../library/copyreg.rst:30 +msgid "" +"Declares that *function* should be used as a \"reduction\" function for " +"objects of type *type*. *function* must return either a string or a tuple " +"containing between two and six elements. See the :attr:`~pickle.Pickler." +"dispatch_table` for more details on the interface of *function*." +msgstr "" +"宣告 *function* 應該用作 *type* 型別之物件的「歸約 (\"reduction\")」函式。" +"*function* 必須回傳字串或包含 2 到 6 個元素的元組。有關 *function* 介面的更多" +"詳細資訊，請參閱 :attr:`~pickle.Pickler.dispatch_table`。" + +#: ../../library/copyreg.rst:35 +msgid "" +"The *constructor_ob* parameter is a legacy feature and is now ignored, but " +"if passed it must be a callable." +msgstr "" +"*constructor_ob* 參數是一個遺留功能，現在已被忽略，但如果要傳遞它的話則必須是" +"個可呼叫物件。" + +#: ../../library/copyreg.rst:38 +msgid "" +"Note that the :attr:`~pickle.Pickler.dispatch_table` attribute of a pickler " +"object or subclass of :class:`pickle.Pickler` can also be used for declaring " +"reduction functions." +msgstr "" +"請注意，pickler 物件或 :class:`pickle.Pickler` 子類別的 :attr:`~pickle." +"Pickler.dispatch_table` 屬性也可用於宣告歸約函式。" + +#: ../../library/copyreg.rst:43 +msgid "Example" +msgstr "範例" + +#: ../../library/copyreg.rst:45 +msgid "" +"The example below would like to show how to register a pickle function and " +"how it will be used:" +msgstr "下面範例展示如何註冊一個 pickle 函式以及如何使用它：" + +#: ../../library/copyreg.rst:9 +msgid "module" +msgstr "module（模組）" + +#: ../../library/copyreg.rst:9 +msgid "pickle" +msgstr "pickle" + +#: ../../library/copyreg.rst:9 +msgid "copy" +msgstr "copy（複製）" diff --git a/library/crypt.po b/library/crypt.po index 07db5a7c63..fc0bbefae0 100644 --- a/library/crypt.po +++ b/library/crypt.po @@ -1,50 +1,50 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -#, fuzzy -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-10-10 00:15+0000\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" -"tw)\n" -"Language: zh_TW\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=UTF-8\n" -"Content-Transfer-Encoding: 8bit\n" - -#: ../../library/crypt.rst:2 -msgid ":mod:`!crypt` --- Function to check Unix passwords" -msgstr ":mod:`!crypt` --- 用於檢查 Unix 密碼的函式" - -#: ../../library/crypt.rst:10 -msgid "" -"This module is no longer part of the Python standard library. It was :ref:" -"`removed in Python 3.13 ` after being deprecated in " -"Python 3.11. The removal was decided in :pep:`594`." -msgstr "" -"這個模組已不再是 Python 標準函式庫的一部分。它在 Python 3.11 中被棄用，並\\ :" -"ref:`已在 Python 3.13 中被移除 `。它的移除是在 :pep:" -"`594` 中決定的。" - -#: ../../library/crypt.rst:14 -msgid "" -"Applications can use the :mod:`hashlib` module from the standard library. " -"Other possible replacements are third-party libraries from PyPI: :pypi:" -"`legacycrypt`, :pypi:`bcrypt`, or :pypi:`argon2-cffi`. These are not " -"supported or maintained by the Python core team." -msgstr "" -"應用程式可以改用標準函式庫中的 :mod:`hashlib` 模組。其他可能的替代方案是 " -"PyPI 上的第三方庫：:pypi:`legacycrypt`、:pypi:`bcrypt` 或 :pypi:`argon2-cffi`" -"。這些函式庫並不受 Python 核心團隊支援或維護。" - -#: ../../library/crypt.rst:19 -msgid "" -"The last version of Python that provided the :mod:`!crypt` module was " -"`Python 3.12 `_." -msgstr "" -"最後提供 :mod:`!crypt` 模組的 Python 版本是 `Python 3.12 `_。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-10-10 00:15+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" +"tw)\n" +"Language: zh_TW\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../library/crypt.rst:2 +msgid ":mod:`!crypt` --- Function to check Unix passwords" +msgstr ":mod:`!crypt` --- 用於檢查 Unix 密碼的函式" + +#: ../../library/crypt.rst:10 +msgid "" +"This module is no longer part of the Python standard library. It was :ref:" +"`removed in Python 3.13 ` after being deprecated in " +"Python 3.11. The removal was decided in :pep:`594`." +msgstr "" +"這個模組已不再是 Python 標準函式庫的一部分。它在 Python 3.11 中被棄用，並\\ :" +"ref:`已在 Python 3.13 中被移除 `。它的移除是在 :pep:" +"`594` 中決定的。" + +#: ../../library/crypt.rst:14 +msgid "" +"Applications can use the :mod:`hashlib` module from the standard library. " +"Other possible replacements are third-party libraries from PyPI: :pypi:" +"`legacycrypt`, :pypi:`bcrypt`, or :pypi:`argon2-cffi`. These are not " +"supported or maintained by the Python core team." +msgstr "" +"應用程式可以改用標準函式庫中的 :mod:`hashlib` 模組。其他可能的替代方案是 " +"PyPI 上的第三方庫：:pypi:`legacycrypt`、:pypi:`bcrypt` 或 :pypi:`argon2-cffi`" +"。這些函式庫並不受 Python 核心團隊支援或維護。" + +#: ../../library/crypt.rst:19 +msgid "" +"The last version of Python that provided the :mod:`!crypt` module was " +"`Python 3.12 `_." +msgstr "" +"最後提供 :mod:`!crypt` 模組的 Python 版本是 `Python 3.12 `_。" diff --git a/library/crypto.po b/library/crypto.po index 86e4a6c1df..08ecaa1625 100644 --- a/library/crypto.po +++ b/library/crypto.po @@ -1,37 +1,37 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Matt Wang , 2022 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-09-23 07:52+0800\n" -"PO-Revision-Date: 2022-02-15 18:06+0800\n" -"Last-Translator: Matt Wang \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" -"X-Generator: Poedit 3.0.1\n" - -#: ../../library/crypto.rst:5 -msgid "Cryptographic Services" -msgstr "加密服務" - -#: ../../library/crypto.rst:9 -msgid "" -"The modules described in this chapter implement various algorithms of a " -"cryptographic nature. They are available at the discretion of the " -"installation. Here's an overview:" -msgstr "" -"本章所描述的模組實作了多種加密演算法。它們可以在安裝時選擇是否一同安裝。以下" -"為概述：" - -#: ../../library/crypto.rst:7 -msgid "cryptography" -msgstr "cryptography（密碼學）" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Matt Wang , 2022 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-09-23 07:52+0800\n" +"PO-Revision-Date: 2022-02-15 18:06+0800\n" +"Last-Translator: Matt Wang \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" +"X-Generator: Poedit 3.0.1\n" + +#: ../../library/crypto.rst:5 +msgid "Cryptographic Services" +msgstr "加密服務" + +#: ../../library/crypto.rst:9 +msgid "" +"The modules described in this chapter implement various algorithms of a " +"cryptographic nature. They are available at the discretion of the " +"installation. Here's an overview:" +msgstr "" +"本章所描述的模組實作了多種加密演算法。它們可以在安裝時選擇是否一同安裝。以下" +"為概述：" + +#: ../../library/crypto.rst:7 +msgid "cryptography" +msgstr "cryptography（密碼學）" diff --git a/library/csv.po b/library/csv.po index a88e275851..89a9305b20 100644 --- a/library/csv.po +++ b/library/csv.po @@ -1,1067 +1,1067 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-12 00:16+0000\n" -"PO-Revision-Date: 2023-11-08 15:06+0800\n" -"Last-Translator: RockLeon \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" -"X-Generator: Poedit 3.4\n" - -#: ../../library/csv.rst:2 -msgid ":mod:`!csv` --- CSV File Reading and Writing" -msgstr ":mod:`!csv` --- CSV 檔案讀取及寫入" - -#: ../../library/csv.rst:9 -msgid "**Source code:** :source:`Lib/csv.py`" -msgstr "**原始碼：**\\ :source:`Lib/csv.py`" - -#: ../../library/csv.rst:17 -msgid "" -"The so-called CSV (Comma Separated Values) format is the most common import " -"and export format for spreadsheets and databases. CSV format was used for " -"many years prior to attempts to describe the format in a standardized way " -"in :rfc:`4180`. The lack of a well-defined standard means that subtle " -"differences often exist in the data produced and consumed by different " -"applications. These differences can make it annoying to process CSV files " -"from multiple sources. Still, while the delimiters and quoting characters " -"vary, the overall format is similar enough that it is possible to write a " -"single module which can efficiently manipulate such data, hiding the details " -"of reading and writing the data from the programmer." -msgstr "" -"所謂的 CSV (Comma Separated Values) 檔案格式是試算表及資料庫中最常見的匯入、" -"匯出檔案格式。在嘗試以 :rfc:`4180` 中的標準化方式來描述格式之前，CSV 格式已經" -"使用了許多年。由於缺少一個完善定義的標準，意味著各個不同的應用程式會在資料產" -"生及銷毀時有微妙的差別。這些不同之處使得從不同資料來源處理 CSV 檔案時會非常擾" -"人。儘管如此，雖然分隔符號和引號字元有所不同，整體的格式非常相似，可以寫個單" -"一模組來高效率的操作這樣的資料，讓程式設計師可以隱藏讀取及寫入資料的細節。" - -#: ../../library/csv.rst:28 -msgid "" -"The :mod:`csv` module implements classes to read and write tabular data in " -"CSV format. It allows programmers to say, \"write this data in the format " -"preferred by Excel,\" or \"read data from this file which was generated by " -"Excel,\" without knowing the precise details of the CSV format used by " -"Excel. Programmers can also describe the CSV formats understood by other " -"applications or define their own special-purpose CSV formats." -msgstr "" -":mod:`csv` 模組實作透過 class 去讀取、寫入 CSV 格式的表格資料。它讓程式設計師" -"可以說出：「以 Excel 為首選並寫入該種格式的資料」或是「從 Excel 產生的檔案來" -"讀取資料」，且無需知道這是 Excel 所使用的 CSV 格式等精確的細節。程式設計師也" -"可以描述其他應用程式所理解的 CSV 格式或他們自行定義具有特殊意義的 CSV 格式。" - -#: ../../library/csv.rst:35 -msgid "" -"The :mod:`csv` module's :class:`reader` and :class:`writer` objects read and " -"write sequences. Programmers can also read and write data in dictionary " -"form using the :class:`DictReader` and :class:`DictWriter` classes." -msgstr "" -":mod:`csv` 模組的 :class:`reader` 及 :class:`writer` 物件可以讀取及寫入序列。" -"程式設計師也可以透過 :class:`DictReader` 及 :class:`DictWriter` class（類別）" -"使用 dictionary （字典）讀取及寫入資料。" - -#: ../../library/csv.rst:41 -msgid ":pep:`305` - CSV File API" -msgstr ":pep:`305` - CSV 檔案 API" - -#: ../../library/csv.rst:42 -msgid "The Python Enhancement Proposal which proposed this addition to Python." -msgstr "Python Enhancement Proposal (PEP) 所提出的 Python 附加功能。" - -#: ../../library/csv.rst:48 -msgid "Module Contents" -msgstr "模組內容" - -#: ../../library/csv.rst:50 -msgid "The :mod:`csv` module defines the following functions:" -msgstr ":mod:`csv` 模組定義了以下函式：" - -#: ../../library/csv.rst:58 -msgid "" -"Return a :ref:`reader object ` that will process lines from " -"the given *csvfile*. A csvfile must be an iterable of strings, each in the " -"reader's defined csv format. A csvfile is most commonly a file-like object " -"or list. If *csvfile* is a file object, it should be opened with " -"``newline=''``. [1]_ An optional *dialect* parameter can be given which is " -"used to define a set of parameters specific to a particular CSV dialect. It " -"may be an instance of a subclass of the :class:`Dialect` class or one of the " -"strings returned by the :func:`list_dialects` function. The other optional " -"*fmtparams* keyword arguments can be given to override individual formatting " -"parameters in the current dialect. For full details about the dialect and " -"formatting parameters, see section :ref:`csv-fmt-params`." -msgstr "" -"回傳一個\\ :ref:`讀取器物件 (reader object) ` 並處理在指定的 " -"*csvfile* 中的每一行，csvfile 必須是字串的可疊代物件 (iterable of strings)，" -"其中每個字串都要是讀取器所定義的 csv 格式，csvfile 通常是個類檔案物件或者 " -"list。如果 *csvfile* 是個檔案物件，則需開啟時使用 ``newline=''``。 [1]_ " -"*dialect* 為一個可選填的參數，可以用為特定的 CSV dialect（方言） 定義一組參" -"數。它可能為 :class:`Dialect` 的一個子類別 (subclass) 的實例或是由 :func:" -"`list_dialects` 函式回傳的多個字串中的其中之一。另一個可選填的關鍵字引數 " -"*fmtparams* 可以在這個 dialect 中覆寫 (override) 個別的格式化參數 " -"(formatting parameter)。關於 dialect 及格式化參數的完整說明，請見段落 :ref:" -"`csv-fmt-params`。" - -#: ../../library/csv.rst:72 -msgid "" -"Each row read from the csv file is returned as a list of strings. No " -"automatic data type conversion is performed unless the :data:" -"`QUOTE_NONNUMERIC` format option is specified (in which case unquoted fields " -"are transformed into floats)." -msgstr "" -"從 CSV 檔案讀取的每一列會回傳為一個字串列表。除非格式選項 :data:" -"`QUOTE_NONNUMERIC` 有被指定（在這個情況之下，沒有引號的欄位都會被轉換成浮點" -"數），否則不會進行自動資料型別轉換。" - -#: ../../library/csv.rst:76 ../../library/csv.rst:106 ../../library/csv.rst:182 -#: ../../library/csv.rst:220 -msgid "A short usage example::" -msgstr "一個簡短的用法範例： ::" - -#: ../../library/csv.rst:78 -msgid "" -">>> import csv\n" -">>> with open('eggs.csv', newline='') as csvfile:\n" -"... spamreader = csv.reader(csvfile, delimiter=' ', quotechar='|')\n" -"... for row in spamreader:\n" -"... print(', '.join(row))\n" -"Spam, Spam, Spam, Spam, Spam, Baked Beans\n" -"Spam, Lovely Spam, Wonderful Spam" -msgstr "" -">>> import csv\n" -">>> with open('eggs.csv', newline='') as csvfile:\n" -"... spamreader = csv.reader(csvfile, delimiter=' ', quotechar='|')\n" -"... for row in spamreader:\n" -"... print(', '.join(row))\n" -"Spam, Spam, Spam, Spam, Spam, Baked Beans\n" -"Spam, Lovely Spam, Wonderful Spam" - -#: ../../library/csv.rst:89 -msgid "" -"Return a writer object responsible for converting the user's data into " -"delimited strings on the given file-like object. *csvfile* can be any " -"object with a :meth:`~io.TextIOBase.write` method. If *csvfile* is a file " -"object, it should be opened with ``newline=''`` [1]_. An optional *dialect* " -"parameter can be given which is used to define a set of parameters specific " -"to a particular CSV dialect. It may be an instance of a subclass of the :" -"class:`Dialect` class or one of the strings returned by the :func:" -"`list_dialects` function. The other optional *fmtparams* keyword arguments " -"can be given to override individual formatting parameters in the current " -"dialect. For full details about dialects and formatting parameters, see " -"the :ref:`csv-fmt-params` section. To make it as easy as possible to " -"interface with modules which implement the DB API, the value :const:`None` " -"is written as the empty string. While this isn't a reversible " -"transformation, it makes it easier to dump SQL NULL data values to CSV files " -"without preprocessing the data returned from a ``cursor.fetch*`` call. All " -"other non-string data are stringified with :func:`str` before being written." -msgstr "" -"回傳一個寫入器物件 (writer object)，其負責在給定的類檔案物件 (file-like " -"object) 上將使用者的資料轉換為分隔字串 (delimited string)。*csvfile* 可以為具" -"有 :meth:`~io.TextIOBase.write` method 的任何物件。若 *csvfile* 為一個檔案物" -"件，它應該使用 ``newline=''`` 開啟 [1]_ 。*dialect* 為一個可選填的參數，可以" -"用為特定的 CSV dialect 定義一組參數。它可能為 :class:`Dialect` 的一個子類別的" -"實例或是由 :func:`list_dialects` 函式回傳的多個字串中的其中之一。另一個可選填" -"的關鍵字引數 *fmtparams* 可以在這個 dialect 中覆寫個別的格式化參數。關於 " -"dialect 及格式化參數的完整說明，請見段落 :ref:`csv-fmt-params`。為了更容易與" -"有實作 DB API 的模組互相接合，:const:`None` 值會被寫成空字串。雖然這不是一個" -"可逆的變換，這使得dump （傾印） SQL NULL 資料值到 CSV 檔案上就無需讓 " -"``cursor.fetch*`` 呼叫回傳的資料進行預處理 (preprocessing)。其餘非字串的資料" -"則會在寫入之前用 :func:`str` 函式進行字串化 (stringify)。" - -#: ../../library/csv.rst:108 -msgid "" -"import csv\n" -"with open('eggs.csv', 'w', newline='') as csvfile:\n" -" spamwriter = csv.writer(csvfile, delimiter=' ',\n" -" quotechar='|', quoting=csv.QUOTE_MINIMAL)\n" -" spamwriter.writerow(['Spam'] * 5 + ['Baked Beans'])\n" -" spamwriter.writerow(['Spam', 'Lovely Spam', 'Wonderful Spam'])" -msgstr "" -"import csv\n" -"with open('eggs.csv', 'w', newline='') as csvfile:\n" -" spamwriter = csv.writer(csvfile, delimiter=' ',\n" -" quotechar='|', quoting=csv.QUOTE_MINIMAL)\n" -" spamwriter.writerow(['Spam'] * 5 + ['Baked Beans'])\n" -" spamwriter.writerow(['Spam', 'Lovely Spam', 'Wonderful Spam'])" - -#: ../../library/csv.rst:118 -msgid "" -"Associate *dialect* with *name*. *name* must be a string. The dialect can " -"be specified either by passing a sub-class of :class:`Dialect`, or by " -"*fmtparams* keyword arguments, or both, with keyword arguments overriding " -"parameters of the dialect. For full details about dialects and formatting " -"parameters, see section :ref:`csv-fmt-params`." -msgstr "" -"將 *dialect* 與 *name* 進行關聯 (associate)。*name* 必須為字串。這個 dialect " -"可以透過傳遞 :class:`Dialect` 的子類別進行指定；或是關鍵字引數 *fmtparams*；" -"或是以上兩者皆是，並透過關鍵字引數來覆寫 dialect 的參數。關於 dialect 及格式" -"化參數的完整說明，請見段落 :ref:`csv-fmt-params`。" - -#: ../../library/csv.rst:127 -msgid "" -"Delete the dialect associated with *name* from the dialect registry. An :" -"exc:`Error` is raised if *name* is not a registered dialect name." -msgstr "" -"從 dialect 註冊表 (registry) 中，刪除與 *name* 關聯的 dialect。若 *name* 如果" -"不是註冊的 dialect 名稱，則會產生一個 :exc:`Error`。" - -#: ../../library/csv.rst:133 -msgid "" -"Return the dialect associated with *name*. An :exc:`Error` is raised if " -"*name* is not a registered dialect name. This function returns an " -"immutable :class:`Dialect`." -msgstr "" -"回傳一個與 *name* 關聯的 dialect。若 *name* 如果不是註冊的 dialect 名稱，則會" -"產生一個 :exc:`Error`。這個函式會回傳一個 immutable （不可變物件） :class:" -"`Dialect`。" - -#: ../../library/csv.rst:139 -msgid "Return the names of all registered dialects." -msgstr "回傳所有已註冊的 dialect 名稱。" - -#: ../../library/csv.rst:145 -msgid "" -"Returns the current maximum field size allowed by the parser. If *new_limit* " -"is given, this becomes the new limit." -msgstr "" -"回傳目前的剖析器 (parser) 允許的最大字串大小。如果 *new_limit* 被給定，則會變" -"成新的最大字串大小。" - -#: ../../library/csv.rst:149 -msgid "The :mod:`csv` module defines the following classes:" -msgstr ":mod:`csv` 模組定義了下列的類別：" - -#: ../../library/csv.rst:154 -msgid "" -"Create an object that operates like a regular reader but maps the " -"information in each row to a :class:`dict` whose keys are given by the " -"optional *fieldnames* parameter." -msgstr "" -"建立一個物件，其運作上就像一般的讀取器，但可以將每一列資訊 map （對映） 到 :" -"class:`dict` 中，可以透過選填的參數 *fieldnames* 設定 key。" - -#: ../../library/csv.rst:158 -msgid "" -"The *fieldnames* parameter is a :term:`sequence`. If *fieldnames* is " -"omitted, the values in the first row of file *f* will be used as the " -"fieldnames and will be omitted from the results. If *fieldnames* is " -"provided, they will be used and the first row will be included in the " -"results. Regardless of how the fieldnames are determined, the dictionary " -"preserves their original ordering." -msgstr "" -"參數 *fieldnames* 是一個 :term:`sequence`。如果 *fieldnames* 被省略了，檔案 " -"*f* 中第一列的值會被當作欄位標題，且於結果中會被省略。如果 *fieldname* 有提" -"供，它們就會被使用，且第一列會被包含在結果中。不管欄位標題是如何決定的，" -"dictionary 都會保留原始的排序。" - -#: ../../library/csv.rst:165 -msgid "" -"If a row has more fields than fieldnames, the remaining data is put in a " -"list and stored with the fieldname specified by *restkey* (which defaults to " -"``None``). If a non-blank row has fewer fields than fieldnames, the missing " -"values are filled-in with the value of *restval* (which defaults to " -"``None``)." -msgstr "" -"如果一列資料中的欄位比欄位標題還多，其餘的資料及以 *restkey* （預設為 " -"``None``）特指的欄位標題會放入列表當中並儲存。如果一個非空的 (non-blank) 列中" -"的欄位比欄位標題還少，缺少的值則會填入 *restval* （預設為 ``None``）的值。" - -#: ../../library/csv.rst:171 -msgid "" -"All other optional or keyword arguments are passed to the underlying :class:" -"`reader` instance." -msgstr "所有其他選填的引數或關鍵字引數皆會傳遞至下層的 :class:`reader` 實例。" - -#: ../../library/csv.rst:174 ../../library/csv.rst:218 -msgid "" -"If the argument passed to *fieldnames* is an iterator, it will be coerced to " -"a :class:`list`." -msgstr "" -"如果傳遞至 *fieldnames* 的引數是個疊代器，則會被迫成為一個 :class:`list`。" - -#: ../../library/csv.rst:176 -msgid "Returned rows are now of type :class:`OrderedDict`." -msgstr "回傳的列已成為型別 :class:`OrderedDict`。" - -#: ../../library/csv.rst:179 -msgid "Returned rows are now of type :class:`dict`." -msgstr "回傳的列已成為型別 :class:`dict`。" - -#: ../../library/csv.rst:184 -msgid "" -">>> import csv\n" -">>> with open('names.csv', newline='') as csvfile:\n" -"... reader = csv.DictReader(csvfile)\n" -"... for row in reader:\n" -"... print(row['first_name'], row['last_name'])\n" -"...\n" -"Eric Idle\n" -"John Cleese\n" -"\n" -">>> print(row)\n" -"{'first_name': 'John', 'last_name': 'Cleese'}" -msgstr "" -">>> import csv\n" -">>> with open('names.csv', newline='') as csvfile:\n" -"... reader = csv.DictReader(csvfile)\n" -"... for row in reader:\n" -"... print(row['first_name'], row['last_name'])\n" -"...\n" -"Eric Idle\n" -"John Cleese\n" -"\n" -">>> print(row)\n" -"{'first_name': 'John', 'last_name': 'Cleese'}" - -#: ../../library/csv.rst:200 -msgid "" -"Create an object which operates like a regular writer but maps dictionaries " -"onto output rows. The *fieldnames* parameter is a :mod:`sequence " -"` of keys that identify the order in which values in the " -"dictionary passed to the :meth:`~csvwriter.writerow` method are written to " -"file *f*. The optional *restval* parameter specifies the value to be " -"written if the dictionary is missing a key in *fieldnames*. If the " -"dictionary passed to the :meth:`~csvwriter.writerow` method contains a key " -"not found in *fieldnames*, the optional *extrasaction* parameter indicates " -"what action to take. If it is set to ``'raise'``, the default value, a :exc:" -"`ValueError` is raised. If it is set to ``'ignore'``, extra values in the " -"dictionary are ignored. Any other optional or keyword arguments are passed " -"to the underlying :class:`writer` instance." -msgstr "" -"建立一個物件，其運作上就像一般的寫入器，但可以將 dictionary map 到輸出的列" -"上。參數 *fieldnames* 是一個鍵值的 :mod:`sequence ` 且可以辨" -"識 dictionary 中傳遞至 :meth:`~csvwriter.writerow` method 寫入至檔案 *f* 中的" -"值。如果 dictionary 中缺少了 *fieldnames* 的鍵值，則會寫入選填的參數 " -"*restval* 的值。如果傳遞至 :meth:`~csvwriter.writerow` method 的 dictionary " -"包含了一個 *fieldnames* 中不存在的鍵值，選填的參數 *extrasaction* 可以指出該" -"執行的動作。如果它被設定為 ``'raise'``，預設會觸發 :exc:`ValueError`。如果它" -"被設定為 ``'ignore'``，dictionary 中額外的值會被忽略。其他選填的引數或關鍵字" -"引數皆會傳遞至下層的 :class:`writer` 實例。" - -#: ../../library/csv.rst:215 -msgid "" -"Note that unlike the :class:`DictReader` class, the *fieldnames* parameter " -"of the :class:`DictWriter` class is not optional." -msgstr "" -"請記得這不像類別 :class:`DictReader`，在類別 :class:`DictWriter` 中，參數 " -"*fieldnames* 並不是選填的。" - -#: ../../library/csv.rst:222 -msgid "" -"import csv\n" -"\n" -"with open('names.csv', 'w', newline='') as csvfile:\n" -" fieldnames = ['first_name', 'last_name']\n" -" writer = csv.DictWriter(csvfile, fieldnames=fieldnames)\n" -"\n" -" writer.writeheader()\n" -" writer.writerow({'first_name': 'Baked', 'last_name': 'Beans'})\n" -" writer.writerow({'first_name': 'Lovely', 'last_name': 'Spam'})\n" -" writer.writerow({'first_name': 'Wonderful', 'last_name': 'Spam'})" -msgstr "" -"import csv\n" -"\n" -"with open('names.csv', 'w', newline='') as csvfile:\n" -" fieldnames = ['first_name', 'last_name']\n" -" writer = csv.DictWriter(csvfile, fieldnames=fieldnames)\n" -"\n" -" writer.writeheader()\n" -" writer.writerow({'first_name': 'Baked', 'last_name': 'Beans'})\n" -" writer.writerow({'first_name': 'Lovely', 'last_name': 'Spam'})\n" -" writer.writerow({'first_name': 'Wonderful', 'last_name': 'Spam'})" - -#: ../../library/csv.rst:236 -msgid "" -"The :class:`Dialect` class is a container class whose attributes contain " -"information for how to handle doublequotes, whitespace, delimiters, etc. Due " -"to the lack of a strict CSV specification, different applications produce " -"subtly different CSV data. :class:`Dialect` instances define how :class:" -"`reader` and :class:`writer` instances behave." -msgstr "" -"類別 :class:`Dialect` 是一個容器類別，其屬性 (attribute) 包含如何處理雙引號、" -"空白、分隔符號等資訊。由於缺少一個嚴謹的 CSV 技術規範，不同的應用程式會產出有" -"巧妙不同的 CSV 資料。:class:`Dialect` 實例定義了 :class:`reader` 以及 :class:" -"`writer` 的實例該如何表示。" - -#: ../../library/csv.rst:242 -msgid "" -"All available :class:`Dialect` names are returned by :func:`list_dialects`, " -"and they can be registered with specific :class:`reader` and :class:`writer` " -"classes through their initializer (``__init__``) functions like this::" -msgstr "" -"所有可用的 :class:`Dialect` 名稱會透過 :func:`list_dialects` 回傳，且它們可以" -"透過特定 :class:`reader` 及 :class:`writer` 類別的初始器 (initializer, " -"``__init__``) 函式進行註冊，就像這樣： ::" - -#: ../../library/csv.rst:246 -msgid "" -"import csv\n" -"\n" -"with open('students.csv', 'w', newline='') as csvfile:\n" -" writer = csv.writer(csvfile, dialect='unix')" -msgstr "" -"import csv\n" -"\n" -"with open('students.csv', 'w', newline='') as csvfile:\n" -" writer = csv.writer(csvfile, dialect='unix')" - -#: ../../library/csv.rst:254 -msgid "" -"The :class:`excel` class defines the usual properties of an Excel-generated " -"CSV file. It is registered with the dialect name ``'excel'``." -msgstr "" -"類別 :class:`excel` 定義了透過 Excel 產生的 CSV 檔案的慣用屬性。它被註冊的 " -"dialect 名稱為 ``'excel'``。" - -#: ../../library/csv.rst:260 -msgid "" -"The :class:`excel_tab` class defines the usual properties of an Excel-" -"generated TAB-delimited file. It is registered with the dialect name " -"``'excel-tab'``." -msgstr "" -"類別 :class:`excel_tab` 定義了透過 Excel 產生並以 Tab 作為分隔的 CSV 檔案的慣" -"用屬性。它被註冊的 dialect 名稱為 ``'excel-tab'``。" - -#: ../../library/csv.rst:266 -msgid "" -"The :class:`unix_dialect` class defines the usual properties of a CSV file " -"generated on UNIX systems, i.e. using ``'\\n'`` as line terminator and " -"quoting all fields. It is registered with the dialect name ``'unix'``." -msgstr "" -"類別 :class:`unix_dialect` 定義了透過 UNIX 系統產生的 CSV 檔案的慣用屬性，換" -"句話說，使用 ``'\\n'`` 作為換行符號且所有欄位都被引號包覆起來。它被註冊的 " -"dialect 名稱為 ``'unix'``。" - -#: ../../library/csv.rst:275 -msgid "The :class:`Sniffer` class is used to deduce the format of a CSV file." -msgstr "類別 :class:`Sniffer` 被用來推斷 CSV 檔案的格式。" - -#: ../../library/csv.rst:277 -msgid "The :class:`Sniffer` class provides two methods:" -msgstr "類別 :class:`Sniffer` 提供了兩個 method：" - -#: ../../library/csv.rst:281 -msgid "" -"Analyze the given *sample* and return a :class:`Dialect` subclass reflecting " -"the parameters found. If the optional *delimiters* parameter is given, it " -"is interpreted as a string containing possible valid delimiter characters." -msgstr "" -"分析給定的 *sample* 且回傳一個 :class:`Dialect` 子類別，反應出找到的格式參" -"數。如果給定選填的參數 *delimiters*，它會被解釋為一個字串且含有可能、有效的分" -"隔字元。" - -#: ../../library/csv.rst:289 -msgid "" -"Analyze the sample text (presumed to be in CSV format) and return :const:" -"`True` if the first row appears to be a series of column headers. Inspecting " -"each column, one of two key criteria will be considered to estimate if the " -"sample contains a header:" -msgstr "" -"如果第一列的文字顯示將作為一系列的欄位標題，會分析 sample 文字（假定他是 CSV " -"格式）並回傳 :const:`True`。檢查每一欄時，會考慮是否滿足兩個關鍵標準其中之" -"一，判斷 sample 是否包含標題：" - -#: ../../library/csv.rst:294 -msgid "the second through n-th rows contain numeric values" -msgstr "第二列至第 n 列包含數字" - -#: ../../library/csv.rst:295 -msgid "" -"the second through n-th rows contain strings where at least one value's " -"length differs from that of the putative header of that column." -msgstr "" -"第二列到第 n 列包含的字串中至少有一個值的長度與該行的假定標題的長度不同。" - -#: ../../library/csv.rst:298 -msgid "" -"Twenty-one rows after the header are sampled; if more than half of the " -"columns + rows meet the criteria, :const:`True` is returned." -msgstr "" -"對標頭之後的二十一個列進行取樣；如果超過一半的行及列滿足條件，則回傳 :const:" -"`True`。" - -#: ../../library/csv.rst:303 -msgid "" -"This method is a rough heuristic and may produce both false positives and " -"negatives." -msgstr "" -"此方法是一個粗略的啟發，可能會產生偽陽性及偽陰性 (false positives and " -"negatives)。" - -#: ../../library/csv.rst:306 -msgid "An example for :class:`Sniffer` use::" -msgstr "一個 :class:`Sniffer` 的使用範例： ::" - -#: ../../library/csv.rst:308 -msgid "" -"with open('example.csv', newline='') as csvfile:\n" -" dialect = csv.Sniffer().sniff(csvfile.read(1024))\n" -" csvfile.seek(0)\n" -" reader = csv.reader(csvfile, dialect)\n" -" # ... process CSV file contents here ..." -msgstr "" -"with open('example.csv', newline='') as csvfile:\n" -" dialect = csv.Sniffer().sniff(csvfile.read(1024))\n" -" csvfile.seek(0)\n" -" reader = csv.reader(csvfile, dialect)\n" -" # ... 在這邊處理 CSV 檔案 ..." - -#: ../../library/csv.rst:317 -msgid "The :mod:`csv` module defines the following constants:" -msgstr ":mod:`csv` 模組定義了以下常數：" - -#: ../../library/csv.rst:321 -msgid "Instructs :class:`writer` objects to quote all fields." -msgstr "引導 :class:`writer` 物件引用所有欄位。" - -#: ../../library/csv.rst:326 -msgid "" -"Instructs :class:`writer` objects to only quote those fields which contain " -"special characters such as *delimiter*, *quotechar*, ``'\\r'``, ``'\\n'`` or " -"any of the characters in *lineterminator*." -msgstr "" -"引導 :class:`writer` 物件只引用包含特殊字元的欄位，例如：*delimiter*、" -"*quotechar*、``'\\r'``、``'\\n'`` 或是 *lineterminator* 的其他字元。" - -#: ../../library/csv.rst:333 -msgid "Instructs :class:`writer` objects to quote all non-numeric fields." -msgstr "引導 :class:`writer` 物件引用所有非數字的欄位。" - -#: ../../library/csv.rst:335 -msgid "" -"Instructs :class:`reader` objects to convert all non-quoted fields to type :" -"class:`float`." -msgstr "引導 :class:`reader` 物件轉換所有非引用的欄位為 :class:`float`。" - -#: ../../library/csv.rst:338 -msgid "" -"Some numeric types, such as :class:`bool`, :class:`~fractions.Fraction`, or :" -"class:`~enum.IntEnum`, have a string representation that cannot be converted " -"to :class:`float`. They cannot be read in the :data:`QUOTE_NONNUMERIC` and :" -"data:`QUOTE_STRINGS` modes." -msgstr "" - -#: ../../library/csv.rst:346 -msgid "" -"Instructs :class:`writer` objects to never quote fields. When the current " -"*delimiter*, *quotechar*, *escapechar*, ``'\\r'``, ``'\\n'`` or any of the " -"characters in *lineterminator* occurs in output data it is preceded by the " -"current *escapechar* character. If *escapechar* is not set, the writer will " -"raise :exc:`Error` if any characters that require escaping are encountered. " -"Set *quotechar* to ``None`` to prevent its escaping." -msgstr "" -"引導 :class:`writer` 物件不得引用欄位。當目前的 *delimiter*、*quotechar*、" -"``'\\r'``、``'\\n'`` 或是 *lineterminator* 的其他字元出現在輸出資料時，在他之" -"前的字元是目前的 *escapechar*。如果沒有設定 *escapechar*，若遇到任何字元需要" -"逸出，寫入器則會引發 :exc:`Error`。設定 *quotechar* 為 ``None`` 以防止逸出。" - -#: ../../library/csv.rst:354 -msgid "" -"Instructs :class:`reader` objects to perform no special processing of quote " -"characters." -msgstr "引導 :class:`reader` 物件不對引號進行特別處理。" - -#: ../../library/csv.rst:358 -msgid "" -"Instructs :class:`writer` objects to quote all fields which are not " -"``None``. This is similar to :data:`QUOTE_ALL`, except that if a field " -"value is ``None`` an empty (unquoted) string is written." -msgstr "" -"引導 :class:`writer` 物件引用所有非 ``None`` 的欄位。這與 :data:`QUOTE_ALL` " -"相似，除非如果欄位值為 ``None``，該欄位則被寫成空（沒有引號）字串。" - -#: ../../library/csv.rst:362 -msgid "" -"Instructs :class:`reader` objects to interpret an empty (unquoted) field as " -"``None`` and to otherwise behave as :data:`QUOTE_ALL`." -msgstr "" -"引導 :class:`reader` 物件將空（沒有引號）欄位直譯 (interpret) 為 ``None``，否" -"則會和 :data:`QUOTE_ALL` 有相同的表現方式。" - -#: ../../library/csv.rst:369 -msgid "" -"Instructs :class:`writer` objects to always place quotes around fields which " -"are strings. This is similar to :data:`QUOTE_NONNUMERIC`, except that if a " -"field value is ``None`` an empty (unquoted) string is written." -msgstr "" -"引導 :class:`writer` 物件永遠在字串的欄位前後放置引號。這與 :data:" -"`QUOTE_NONNUMERIC` 相似，除非如果欄位值為 ``None``，該欄位則被寫成空（沒有引" -"號）字串。" - -#: ../../library/csv.rst:373 -msgid "" -"Instructs :class:`reader` objects to interpret an empty (unquoted) string as " -"``None`` and to otherwise behave as :data:`QUOTE_NONNUMERIC`." -msgstr "" -"引導 :class:`reader` 物件將空（沒有引號）字串直譯為 ``None``，否則會和 :data:" -"`QUOTE_NONNUMERIC` 有相同的表現方式。" - -#: ../../library/csv.rst:378 -msgid "The :mod:`csv` module defines the following exception:" -msgstr ":mod:`csv` 模組定義下列例外：" - -#: ../../library/csv.rst:383 -msgid "Raised by any of the functions when an error is detected." -msgstr "當偵測到錯誤時，任何函式都可以引發。" - -#: ../../library/csv.rst:388 -msgid "Dialects and Formatting Parameters" -msgstr "Dialect 與格式參數" - -#: ../../library/csv.rst:390 -msgid "" -"To make it easier to specify the format of input and output records, " -"specific formatting parameters are grouped together into dialects. A " -"dialect is a subclass of the :class:`Dialect` class containing various " -"attributes describing the format of the CSV file. When creating :class:" -"`reader` or :class:`writer` objects, the programmer can specify a string or " -"a subclass of the :class:`Dialect` class as the dialect parameter. In " -"addition to, or instead of, the *dialect* parameter, the programmer can also " -"specify individual formatting parameters, which have the same names as the " -"attributes defined below for the :class:`Dialect` class." -msgstr "" -"為了讓指定輸入及輸出紀錄的格式更方便，特定的格式化參數會被組成 dialect。一個 " -"dialect 是 :class:`Dialect` class 的子類別，其包含多個描述 CSV 檔案格式的多個" -"屬性。當建立 :class:`reader` 或 :class:`writer` 物件時，程式設計師可以指定一" -"個字串或是一個 :class:`Dialect` 的子類別作為 dialect 參數。此外，或是作為替" -"代，在\\ *dialect*\\ 參數中，程式設計師可以指定個別的格式化參數，其與 :class:" -"`Dialect` 類別定義的屬性具有相同的名字。" - -#: ../../library/csv.rst:400 -msgid "Dialects support the following attributes:" -msgstr "Dialect 支援下列屬性：" - -#: ../../library/csv.rst:405 -msgid "" -"A one-character string used to separate fields. It defaults to ``','``." -msgstr "一個單一字元 (one-character) 的字串可已用來分割欄位。預設為 ``','``。" - -#: ../../library/csv.rst:410 -msgid "" -"Controls how instances of *quotechar* appearing inside a field should " -"themselves be quoted. When :const:`True`, the character is doubled. When :" -"const:`False`, the *escapechar* is used as a prefix to the *quotechar*. It " -"defaults to :const:`True`." -msgstr "" -"控制 *quotechar* 的實例何時出現在欄位之中，並讓它們自己被放在引號之內。當屬性" -"為 :const:`True`，字元會是雙引號。若為 :const:`False`，在 *quotechar* 之前會" -"先使用 *escapechar* 作為前綴字。預設為 :const:`True`。" - -#: ../../library/csv.rst:415 -msgid "" -"On output, if *doublequote* is :const:`False` and no *escapechar* is set, :" -"exc:`Error` is raised if a *quotechar* is found in a field." -msgstr "" -"在輸出時，若 *doublequote* 是 :const:`False` 且\\ *逸出字元*\\ 沒有被設定，當" -"一個\\ *引號*\\ 在欄位中被發現時，:exc:`Error` 會被引發。" - -#: ../../library/csv.rst:421 -msgid "" -"A one-character string used by the writer to escape characters that require " -"escaping:" -msgstr "一個單一字元的字串，會被寫入器用來逸出需要逸出的字元：" - -#: ../../library/csv.rst:424 -msgid "" -"the *delimiter*, the *quotechar*, ``'\\r'``, ``'\\n'`` and any of the " -"characters in *lineterminator* are escaped if *quoting* is set to :const:" -"`QUOTE_NONE`;" -msgstr "" - -#: ../../library/csv.rst:427 -msgid "the *quotechar* is escaped if *doublequote* is :const:`False`;" -msgstr "" - -#: ../../library/csv.rst:428 -msgid "the *escapechar* itself." -msgstr "*escapechar* 本身。" - -#: ../../library/csv.rst:430 -msgid "" -"On reading, the *escapechar* removes any special meaning from the following " -"character. It defaults to :const:`None`, which disables escaping." -msgstr "" -"在讀取時，*escapechar* 會移除後面字元的任何特殊意義。預設為 :const:`None`，表" -"示禁止逸出。" - -#: ../../library/csv.rst:433 -msgid "An empty *escapechar* is not allowed." -msgstr "*escapechar* 為空是不被接受的。" - -#: ../../library/csv.rst:438 -msgid "" -"The string used to terminate lines produced by the :class:`writer`. It " -"defaults to ``'\\r\\n'``." -msgstr "由 :class:`writer` 產生被用來分行的字串。預設為 ``'\\r\\n'``。" - -#: ../../library/csv.rst:443 -msgid "" -"The :class:`reader` is hard-coded to recognise either ``'\\r'`` or ``'\\n'`` " -"as end-of-line, and ignores *lineterminator*. This behavior may change in " -"the future." -msgstr "" -":class:`reader` 是 hard-coded 辨別 ``'\\r'`` or ``'\\n'`` 作為行尾 (end-of-" -"line)，並忽略\\ *lineterminator*。未來可能會改變這個行為。" - -#: ../../library/csv.rst:450 -msgid "" -"A one-character string used to quote fields containing special characters, " -"such as the *delimiter* or the *quotechar*, or which contain new-line " -"characters (``'\\r'``, ``'\\n'`` or any of the characters in " -"*lineterminator*). It defaults to ``'\"'``. Can be set to ``None`` to " -"prevent escaping ``'\"'`` if *quoting* is set to :const:`QUOTE_NONE`." -msgstr "" -"一個單一字元的字串被用於引用包含特殊字元的欄位，像是 *delimiter*、" -"*quotechar* 或是換行字元（``'\\r'``、``'\\n'`` 或是 *lineterminator* 的任一字" -"元）。預設為 ``'\"'``。如果 *quoting* 設定為 :const:`QUOTE_NONE`，可以設定為 " -"``None`` 以防止逸出 ``'\"'``。" - -#: ../../library/csv.rst:457 -msgid "An empty *quotechar* is not allowed." -msgstr "*quotechar* 為空是不被允許的。" - -#: ../../library/csv.rst:462 -msgid "" -"Controls when quotes should be generated by the writer and recognised by the " -"reader. It can take on any of the :ref:`QUOTE_\\* constants ` and defaults to :const:`QUOTE_MINIMAL` if *quotechar* is not " -"``None``, and :const:`QUOTE_NONE` otherwise." -msgstr "" -"控制 writer 何時產生引號，以及 reader 如何辨識引號。如 *quotechar* 不為 " -"``None``，則可以使用任何 :ref:`QUOTE_\\* 常數 `\\ 且預設為 :" -"const:`QUOTE_MINIMAL`。否則預設為 :const:`QUOTE_NONE`。" - -#: ../../library/csv.rst:470 -msgid "" -"When :const:`True`, spaces immediately following the *delimiter* are " -"ignored. The default is :const:`False`. When combining ``delimiter=' '`` " -"with ``skipinitialspace=True``, unquoted empty fields are not allowed." -msgstr "" -"若為 :const:`True`，在緊接著\\ *delimiter*\\ 後的空格會被忽略。預設為 :const:" -"`False`。當結合 ``delimiter=' '`` 與 ``skipinitialspace=True`` 時，不允許沒有" -"引號的空欄位。" - -#: ../../library/csv.rst:477 -msgid "" -"When ``True``, raise exception :exc:`Error` on bad CSV input. The default is " -"``False``." -msgstr "" -"若為 ``True``，若有錯誤的 CSV 輸入則會引發 :exc:`Error`。預設為 ``False``。" - -#: ../../library/csv.rst:483 -msgid "Reader Objects" -msgstr "讀取器物件" - -#: ../../library/csv.rst:485 -msgid "" -"Reader objects (:class:`DictReader` instances and objects returned by the :" -"func:`reader` function) have the following public methods:" -msgstr "" -"讀取器物件（:func:`reader` 函式回傳的 :class:`DictReader` 實例與物件）有下列" -"公開方法 (public method)：" - -#: ../../library/csv.rst:490 -msgid "" -"Return the next row of the reader's iterable object as a list (if the object " -"was returned from :func:`reader`) or a dict (if it is a :class:`DictReader` " -"instance), parsed according to the current :class:`Dialect`. Usually you " -"should call this as ``next(reader)``." -msgstr "" -"回傳一個列表為讀入器的可疊代物件的下一列內容（若該物件是由 :func:`reader` 回" -"傳）或是一個 dict（若為 :class:`DictReader` 實例），會依據目前的 :class:" -"`Dialect` 進行剖析。通常會用 ``next(reader)`` 來進行呼叫。" - -#: ../../library/csv.rst:496 -msgid "Reader objects have the following public attributes:" -msgstr "讀取器物件有下列公開屬性 (public attributes)：" - -#: ../../library/csv.rst:500 -msgid "A read-only description of the dialect in use by the parser." -msgstr "dialect 的唯讀敘述，會被剖析器使用。" - -#: ../../library/csv.rst:505 -msgid "" -"The number of lines read from the source iterator. This is not the same as " -"the number of records returned, as records can span multiple lines." -msgstr "來源疊代器所讀取的行數。這與回傳的紀錄數不同，因為可以進行跨行紀錄。" - -#: ../../library/csv.rst:509 -msgid "DictReader objects have the following public attribute:" -msgstr "DictReader 物件有下列公開屬性：" - -#: ../../library/csv.rst:513 -msgid "" -"If not passed as a parameter when creating the object, this attribute is " -"initialized upon first access or when the first record is read from the file." -msgstr "" -"若在建立物件時沒有作為參數傳遞，這個屬性會在第一次存取之前或是第一筆資料被讀" -"取之前進行初始化 (initialize)。" - -#: ../../library/csv.rst:520 -msgid "Writer Objects" -msgstr "寫入器物件" - -#: ../../library/csv.rst:522 -msgid "" -":class:`writer` objects (:class:`DictWriter` instances and objects returned " -"by the :func:`writer` function) have the following public methods. A *row* " -"must be an iterable of strings or numbers for :class:`writer` objects and a " -"dictionary mapping fieldnames to strings or numbers (by passing them " -"through :func:`str` first) for :class:`DictWriter` objects. Note that " -"complex numbers are written out surrounded by parens. This may cause some " -"problems for other programs which read CSV files (assuming they support " -"complex numbers at all)." -msgstr "" -":class:`writer` 物件（:func:`writer` 函式回傳的 :class:`DictWriter` 實例與物" -"件）有下列公開方法。對於 :class:`writer` 物件而言，一個\\ *列*\\ 中必須為一個" -"可疊代的字串或是數字；對於 :class:`DictWriter` 物件而言，則必須為一個 " -"dictionary ，且可以對應欄位標題至字串或數字（會先透過 :func:`str` 進行傳" -"遞）。請注意，在寫入複數 (complex number) 時會用小括號 (parens) 包起來。這可" -"能在其他程式讀取 CSV 檔案時導致某些問題（假設他們完全支援複雜數字）。" - -#: ../../library/csv.rst:533 -msgid "" -"Write the *row* parameter to the writer's file object, formatted according " -"to the current :class:`Dialect`. Return the return value of the call to the " -"*write* method of the underlying file object." -msgstr "" -"將參數 *row* 寫入至寫入器的檔案物件中，並依照目前的 :class:`Dialect` 進行格式" -"化。回傳下層檔案物件 *write* 方法的回傳值。" - -#: ../../library/csv.rst:537 -msgid "Added support of arbitrary iterables." -msgstr "新增對任意可疊代物件 (arbitrary iterables) 的支援。" - -#: ../../library/csv.rst:542 -msgid "" -"Write all elements in *rows* (an iterable of *row* objects as described " -"above) to the writer's file object, formatted according to the current " -"dialect." -msgstr "" -"將 *rows* 中所有元素（為上述的一個可疊代的 *row* 物件）寫入至寫入器的檔案物件" -"中，並依照目前的 dialect 進行格式化。" - -#: ../../library/csv.rst:546 -msgid "Writer objects have the following public attribute:" -msgstr "寫入器物件有下列公開屬性：" - -#: ../../library/csv.rst:551 -msgid "A read-only description of the dialect in use by the writer." -msgstr "dialect 的唯讀敘述，會被寫入器使用。" - -#: ../../library/csv.rst:554 -msgid "DictWriter objects have the following public method:" -msgstr "DictWriter 物件有下列公開方法：" - -#: ../../library/csv.rst:559 -msgid "" -"Write a row with the field names (as specified in the constructor) to the " -"writer's file object, formatted according to the current dialect. Return the " -"return value of the :meth:`csvwriter.writerow` call used internally." -msgstr "" -"將具欄位標題的一列（於建構函式 (constructor) 中指定的）寫入至寫入器的檔案物件" -"中，並依照目前的 dialect 進行格式化。回傳內部呼叫 :meth:`csvwriter.writerow` " -"的回傳值。" - -#: ../../library/csv.rst:564 -msgid "" -":meth:`writeheader` now also returns the value returned by the :meth:" -"`csvwriter.writerow` method it uses internally." -msgstr "" -":meth:`writeheader` 現在也會回傳內部呼叫 :meth:`csvwriter.writerow` 的回傳" -"值。" - -#: ../../library/csv.rst:572 -msgid "Examples" -msgstr "範例" - -#: ../../library/csv.rst:574 -msgid "The simplest example of reading a CSV file::" -msgstr "最簡單的讀取 CSV 檔案範例： ::" - -#: ../../library/csv.rst:576 -msgid "" -"import csv\n" -"with open('some.csv', newline='') as f:\n" -" reader = csv.reader(f)\n" -" for row in reader:\n" -" print(row)" -msgstr "" -"import csv\n" -"with open('some.csv', newline='') as f:\n" -" reader = csv.reader(f)\n" -" for row in reader:\n" -" print(row)" - -#: ../../library/csv.rst:582 -msgid "Reading a file with an alternate format::" -msgstr "讀取一個其他格式的檔案： ::" - -#: ../../library/csv.rst:584 -msgid "" -"import csv\n" -"with open('passwd', newline='') as f:\n" -" reader = csv.reader(f, delimiter=':', quoting=csv.QUOTE_NONE)\n" -" for row in reader:\n" -" print(row)" -msgstr "" -"import csv\n" -"with open('passwd', newline='') as f:\n" -" reader = csv.reader(f, delimiter=':', quoting=csv.QUOTE_NONE)\n" -" for row in reader:\n" -" print(row)" - -#: ../../library/csv.rst:590 -msgid "The corresponding simplest possible writing example is::" -msgstr "相對最簡單、可行的寫入範例為： ::" - -#: ../../library/csv.rst:592 -msgid "" -"import csv\n" -"with open('some.csv', 'w', newline='') as f:\n" -" writer = csv.writer(f)\n" -" writer.writerows(someiterable)" -msgstr "" -"import csv\n" -"with open('some.csv', 'w', newline='') as f:\n" -" writer = csv.writer(f)\n" -" writer.writerows(someiterable)" - -#: ../../library/csv.rst:597 -msgid "" -"Since :func:`open` is used to open a CSV file for reading, the file will by " -"default be decoded into unicode using the system default encoding (see :func:" -"`locale.getencoding`). To decode a file using a different encoding, use the " -"``encoding`` argument of open::" -msgstr "" -"當 :func:`open` 被使用於開啟並讀取一個 CSV 檔案，該檔案會預設使用系統預設的編" -"碼格式（請見 :func:`locale.getencoding`），並解碼為 unicode。若要使用不同編碼" -"格式進行檔案解碼，請使用 open 函式的 ``encoding`` 引數： ::" - -#: ../../library/csv.rst:602 -msgid "" -"import csv\n" -"with open('some.csv', newline='', encoding='utf-8') as f:\n" -" reader = csv.reader(f)\n" -" for row in reader:\n" -" print(row)" -msgstr "" -"import csv\n" -"with open('some.csv', newline='', encoding='utf-8') as f:\n" -" reader = csv.reader(f)\n" -" for row in reader:\n" -" print(row)" - -#: ../../library/csv.rst:608 -msgid "" -"The same applies to writing in something other than the system default " -"encoding: specify the encoding argument when opening the output file." -msgstr "" -"同理可以應用到使用不同編碼格式進行寫入：當開啟輸出檔案時，指定 ``encoding`` " -"引數。" - -#: ../../library/csv.rst:611 -msgid "Registering a new dialect::" -msgstr "註冊一個新的 dialect ： ::" - -#: ../../library/csv.rst:613 -msgid "" -"import csv\n" -"csv.register_dialect('unixpwd', delimiter=':', quoting=csv.QUOTE_NONE)\n" -"with open('passwd', newline='') as f:\n" -" reader = csv.reader(f, 'unixpwd')" -msgstr "" -"import csv\n" -"csv.register_dialect('unixpwd', delimiter=':', quoting=csv.QUOTE_NONE)\n" -"with open('passwd', newline='') as f:\n" -" reader = csv.reader(f, 'unixpwd')" - -#: ../../library/csv.rst:618 -msgid "" -"A slightly more advanced use of the reader --- catching and reporting " -"errors::" -msgstr "稍微進階的讀取器用法 -- 擷取及回報錯誤： ::" - -#: ../../library/csv.rst:620 -msgid "" -"import csv, sys\n" -"filename = 'some.csv'\n" -"with open(filename, newline='') as f:\n" -" reader = csv.reader(f)\n" -" try:\n" -" for row in reader:\n" -" print(row)\n" -" except csv.Error as e:\n" -" sys.exit(f'file {filename}, line {reader.line_num}: {e}')" -msgstr "" -"import csv, sys\n" -"filename = 'some.csv'\n" -"with open(filename, newline='') as f:\n" -" reader = csv.reader(f)\n" -" try:\n" -" for row in reader:\n" -" print(row)\n" -" except csv.Error as e:\n" -" sys.exit(f'file {filename}, line {reader.line_num}: {e}')" - -#: ../../library/csv.rst:630 -msgid "" -"And while the module doesn't directly support parsing strings, it can easily " -"be done::" -msgstr "而當模組無法直接支援剖析字串時，仍可以輕鬆的解決： ::" - -#: ../../library/csv.rst:633 -msgid "" -"import csv\n" -"for row in csv.reader(['one,two,three']):\n" -" print(row)" -msgstr "" -"import csv\n" -"for row in csv.reader(['one,two,three']):\n" -" print(row)" - -#: ../../library/csv.rst:639 -msgid "Footnotes" -msgstr "註解" - -#: ../../library/csv.rst:640 -msgid "" -"If ``newline=''`` is not specified, newlines embedded inside quoted fields " -"will not be interpreted correctly, and on platforms that use ``\\r\\n`` line " -"endings on write an extra ``\\r`` will be added. It should always be safe " -"to specify ``newline=''``, since the csv module does its own (:term:" -"`universal `) newline handling." -msgstr "" -"如果 ``newline=''`` 沒有被指定，則嵌入引號中的換行符號不會被正確直譯，使用 " -"``\\r\\n`` 行尾 (line ending) 的平台會寫入額外的 ``\\r``。自從 csv 模組有自" -"己 (:term:`統一的 `) 換行處理方式，因此指定 " -"``newline=''`` 會永遠是安全的。" - -#: ../../library/csv.rst:11 -msgid "csv" -msgstr "csv" - -#: ../../library/csv.rst:11 -msgid "data" -msgstr "data（資料）" - -#: ../../library/csv.rst:11 -msgid "tabular" -msgstr "tabular（表格）" - -#: ../../library/csv.rst:53 -msgid "universal newlines" -msgstr "universal newlines" - -#: ../../library/csv.rst:53 -msgid "csv.reader function" -msgstr "csv.reader 函式" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-12 00:16+0000\n" +"PO-Revision-Date: 2023-11-08 15:06+0800\n" +"Last-Translator: RockLeon \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" +"X-Generator: Poedit 3.4\n" + +#: ../../library/csv.rst:2 +msgid ":mod:`!csv` --- CSV File Reading and Writing" +msgstr ":mod:`!csv` --- CSV 檔案讀取及寫入" + +#: ../../library/csv.rst:9 +msgid "**Source code:** :source:`Lib/csv.py`" +msgstr "**原始碼：**\\ :source:`Lib/csv.py`" + +#: ../../library/csv.rst:17 +msgid "" +"The so-called CSV (Comma Separated Values) format is the most common import " +"and export format for spreadsheets and databases. CSV format was used for " +"many years prior to attempts to describe the format in a standardized way " +"in :rfc:`4180`. The lack of a well-defined standard means that subtle " +"differences often exist in the data produced and consumed by different " +"applications. These differences can make it annoying to process CSV files " +"from multiple sources. Still, while the delimiters and quoting characters " +"vary, the overall format is similar enough that it is possible to write a " +"single module which can efficiently manipulate such data, hiding the details " +"of reading and writing the data from the programmer." +msgstr "" +"所謂的 CSV (Comma Separated Values) 檔案格式是試算表及資料庫中最常見的匯入、" +"匯出檔案格式。在嘗試以 :rfc:`4180` 中的標準化方式來描述格式之前，CSV 格式已經" +"使用了許多年。由於缺少一個完善定義的標準，意味著各個不同的應用程式會在資料產" +"生及銷毀時有微妙的差別。這些不同之處使得從不同資料來源處理 CSV 檔案時會非常擾" +"人。儘管如此，雖然分隔符號和引號字元有所不同，整體的格式非常相似，可以寫個單" +"一模組來高效率的操作這樣的資料，讓程式設計師可以隱藏讀取及寫入資料的細節。" + +#: ../../library/csv.rst:28 +msgid "" +"The :mod:`csv` module implements classes to read and write tabular data in " +"CSV format. It allows programmers to say, \"write this data in the format " +"preferred by Excel,\" or \"read data from this file which was generated by " +"Excel,\" without knowing the precise details of the CSV format used by " +"Excel. Programmers can also describe the CSV formats understood by other " +"applications or define their own special-purpose CSV formats." +msgstr "" +":mod:`csv` 模組實作透過 class 去讀取、寫入 CSV 格式的表格資料。它讓程式設計師" +"可以說出：「以 Excel 為首選並寫入該種格式的資料」或是「從 Excel 產生的檔案來" +"讀取資料」，且無需知道這是 Excel 所使用的 CSV 格式等精確的細節。程式設計師也" +"可以描述其他應用程式所理解的 CSV 格式或他們自行定義具有特殊意義的 CSV 格式。" + +#: ../../library/csv.rst:35 +msgid "" +"The :mod:`csv` module's :class:`reader` and :class:`writer` objects read and " +"write sequences. Programmers can also read and write data in dictionary " +"form using the :class:`DictReader` and :class:`DictWriter` classes." +msgstr "" +":mod:`csv` 模組的 :class:`reader` 及 :class:`writer` 物件可以讀取及寫入序列。" +"程式設計師也可以透過 :class:`DictReader` 及 :class:`DictWriter` class（類別）" +"使用 dictionary （字典）讀取及寫入資料。" + +#: ../../library/csv.rst:41 +msgid ":pep:`305` - CSV File API" +msgstr ":pep:`305` - CSV 檔案 API" + +#: ../../library/csv.rst:42 +msgid "The Python Enhancement Proposal which proposed this addition to Python." +msgstr "Python Enhancement Proposal (PEP) 所提出的 Python 附加功能。" + +#: ../../library/csv.rst:48 +msgid "Module Contents" +msgstr "模組內容" + +#: ../../library/csv.rst:50 +msgid "The :mod:`csv` module defines the following functions:" +msgstr ":mod:`csv` 模組定義了以下函式：" + +#: ../../library/csv.rst:58 +msgid "" +"Return a :ref:`reader object ` that will process lines from " +"the given *csvfile*. A csvfile must be an iterable of strings, each in the " +"reader's defined csv format. A csvfile is most commonly a file-like object " +"or list. If *csvfile* is a file object, it should be opened with " +"``newline=''``. [1]_ An optional *dialect* parameter can be given which is " +"used to define a set of parameters specific to a particular CSV dialect. It " +"may be an instance of a subclass of the :class:`Dialect` class or one of the " +"strings returned by the :func:`list_dialects` function. The other optional " +"*fmtparams* keyword arguments can be given to override individual formatting " +"parameters in the current dialect. For full details about the dialect and " +"formatting parameters, see section :ref:`csv-fmt-params`." +msgstr "" +"回傳一個\\ :ref:`讀取器物件 (reader object) ` 並處理在指定的 " +"*csvfile* 中的每一行，csvfile 必須是字串的可疊代物件 (iterable of strings)，" +"其中每個字串都要是讀取器所定義的 csv 格式，csvfile 通常是個類檔案物件或者 " +"list。如果 *csvfile* 是個檔案物件，則需開啟時使用 ``newline=''``。 [1]_ " +"*dialect* 為一個可選填的參數，可以用為特定的 CSV dialect（方言） 定義一組參" +"數。它可能為 :class:`Dialect` 的一個子類別 (subclass) 的實例或是由 :func:" +"`list_dialects` 函式回傳的多個字串中的其中之一。另一個可選填的關鍵字引數 " +"*fmtparams* 可以在這個 dialect 中覆寫 (override) 個別的格式化參數 " +"(formatting parameter)。關於 dialect 及格式化參數的完整說明，請見段落 :ref:" +"`csv-fmt-params`。" + +#: ../../library/csv.rst:72 +msgid "" +"Each row read from the csv file is returned as a list of strings. No " +"automatic data type conversion is performed unless the :data:" +"`QUOTE_NONNUMERIC` format option is specified (in which case unquoted fields " +"are transformed into floats)." +msgstr "" +"從 CSV 檔案讀取的每一列會回傳為一個字串列表。除非格式選項 :data:" +"`QUOTE_NONNUMERIC` 有被指定（在這個情況之下，沒有引號的欄位都會被轉換成浮點" +"數），否則不會進行自動資料型別轉換。" + +#: ../../library/csv.rst:76 ../../library/csv.rst:106 ../../library/csv.rst:182 +#: ../../library/csv.rst:220 +msgid "A short usage example::" +msgstr "一個簡短的用法範例： ::" + +#: ../../library/csv.rst:78 +msgid "" +">>> import csv\n" +">>> with open('eggs.csv', newline='') as csvfile:\n" +"... spamreader = csv.reader(csvfile, delimiter=' ', quotechar='|')\n" +"... for row in spamreader:\n" +"... print(', '.join(row))\n" +"Spam, Spam, Spam, Spam, Spam, Baked Beans\n" +"Spam, Lovely Spam, Wonderful Spam" +msgstr "" +">>> import csv\n" +">>> with open('eggs.csv', newline='') as csvfile:\n" +"... spamreader = csv.reader(csvfile, delimiter=' ', quotechar='|')\n" +"... for row in spamreader:\n" +"... print(', '.join(row))\n" +"Spam, Spam, Spam, Spam, Spam, Baked Beans\n" +"Spam, Lovely Spam, Wonderful Spam" + +#: ../../library/csv.rst:89 +msgid "" +"Return a writer object responsible for converting the user's data into " +"delimited strings on the given file-like object. *csvfile* can be any " +"object with a :meth:`~io.TextIOBase.write` method. If *csvfile* is a file " +"object, it should be opened with ``newline=''`` [1]_. An optional *dialect* " +"parameter can be given which is used to define a set of parameters specific " +"to a particular CSV dialect. It may be an instance of a subclass of the :" +"class:`Dialect` class or one of the strings returned by the :func:" +"`list_dialects` function. The other optional *fmtparams* keyword arguments " +"can be given to override individual formatting parameters in the current " +"dialect. For full details about dialects and formatting parameters, see " +"the :ref:`csv-fmt-params` section. To make it as easy as possible to " +"interface with modules which implement the DB API, the value :const:`None` " +"is written as the empty string. While this isn't a reversible " +"transformation, it makes it easier to dump SQL NULL data values to CSV files " +"without preprocessing the data returned from a ``cursor.fetch*`` call. All " +"other non-string data are stringified with :func:`str` before being written." +msgstr "" +"回傳一個寫入器物件 (writer object)，其負責在給定的類檔案物件 (file-like " +"object) 上將使用者的資料轉換為分隔字串 (delimited string)。*csvfile* 可以為具" +"有 :meth:`~io.TextIOBase.write` method 的任何物件。若 *csvfile* 為一個檔案物" +"件，它應該使用 ``newline=''`` 開啟 [1]_ 。*dialect* 為一個可選填的參數，可以" +"用為特定的 CSV dialect 定義一組參數。它可能為 :class:`Dialect` 的一個子類別的" +"實例或是由 :func:`list_dialects` 函式回傳的多個字串中的其中之一。另一個可選填" +"的關鍵字引數 *fmtparams* 可以在這個 dialect 中覆寫個別的格式化參數。關於 " +"dialect 及格式化參數的完整說明，請見段落 :ref:`csv-fmt-params`。為了更容易與" +"有實作 DB API 的模組互相接合，:const:`None` 值會被寫成空字串。雖然這不是一個" +"可逆的變換，這使得dump （傾印） SQL NULL 資料值到 CSV 檔案上就無需讓 " +"``cursor.fetch*`` 呼叫回傳的資料進行預處理 (preprocessing)。其餘非字串的資料" +"則會在寫入之前用 :func:`str` 函式進行字串化 (stringify)。" + +#: ../../library/csv.rst:108 +msgid "" +"import csv\n" +"with open('eggs.csv', 'w', newline='') as csvfile:\n" +" spamwriter = csv.writer(csvfile, delimiter=' ',\n" +" quotechar='|', quoting=csv.QUOTE_MINIMAL)\n" +" spamwriter.writerow(['Spam'] * 5 + ['Baked Beans'])\n" +" spamwriter.writerow(['Spam', 'Lovely Spam', 'Wonderful Spam'])" +msgstr "" +"import csv\n" +"with open('eggs.csv', 'w', newline='') as csvfile:\n" +" spamwriter = csv.writer(csvfile, delimiter=' ',\n" +" quotechar='|', quoting=csv.QUOTE_MINIMAL)\n" +" spamwriter.writerow(['Spam'] * 5 + ['Baked Beans'])\n" +" spamwriter.writerow(['Spam', 'Lovely Spam', 'Wonderful Spam'])" + +#: ../../library/csv.rst:118 +msgid "" +"Associate *dialect* with *name*. *name* must be a string. The dialect can " +"be specified either by passing a sub-class of :class:`Dialect`, or by " +"*fmtparams* keyword arguments, or both, with keyword arguments overriding " +"parameters of the dialect. For full details about dialects and formatting " +"parameters, see section :ref:`csv-fmt-params`." +msgstr "" +"將 *dialect* 與 *name* 進行關聯 (associate)。*name* 必須為字串。這個 dialect " +"可以透過傳遞 :class:`Dialect` 的子類別進行指定；或是關鍵字引數 *fmtparams*；" +"或是以上兩者皆是，並透過關鍵字引數來覆寫 dialect 的參數。關於 dialect 及格式" +"化參數的完整說明，請見段落 :ref:`csv-fmt-params`。" + +#: ../../library/csv.rst:127 +msgid "" +"Delete the dialect associated with *name* from the dialect registry. An :" +"exc:`Error` is raised if *name* is not a registered dialect name." +msgstr "" +"從 dialect 註冊表 (registry) 中，刪除與 *name* 關聯的 dialect。若 *name* 如果" +"不是註冊的 dialect 名稱，則會產生一個 :exc:`Error`。" + +#: ../../library/csv.rst:133 +msgid "" +"Return the dialect associated with *name*. An :exc:`Error` is raised if " +"*name* is not a registered dialect name. This function returns an " +"immutable :class:`Dialect`." +msgstr "" +"回傳一個與 *name* 關聯的 dialect。若 *name* 如果不是註冊的 dialect 名稱，則會" +"產生一個 :exc:`Error`。這個函式會回傳一個 immutable （不可變物件） :class:" +"`Dialect`。" + +#: ../../library/csv.rst:139 +msgid "Return the names of all registered dialects." +msgstr "回傳所有已註冊的 dialect 名稱。" + +#: ../../library/csv.rst:145 +msgid "" +"Returns the current maximum field size allowed by the parser. If *new_limit* " +"is given, this becomes the new limit." +msgstr "" +"回傳目前的剖析器 (parser) 允許的最大字串大小。如果 *new_limit* 被給定，則會變" +"成新的最大字串大小。" + +#: ../../library/csv.rst:149 +msgid "The :mod:`csv` module defines the following classes:" +msgstr ":mod:`csv` 模組定義了下列的類別：" + +#: ../../library/csv.rst:154 +msgid "" +"Create an object that operates like a regular reader but maps the " +"information in each row to a :class:`dict` whose keys are given by the " +"optional *fieldnames* parameter." +msgstr "" +"建立一個物件，其運作上就像一般的讀取器，但可以將每一列資訊 map （對映） 到 :" +"class:`dict` 中，可以透過選填的參數 *fieldnames* 設定 key。" + +#: ../../library/csv.rst:158 +msgid "" +"The *fieldnames* parameter is a :term:`sequence`. If *fieldnames* is " +"omitted, the values in the first row of file *f* will be used as the " +"fieldnames and will be omitted from the results. If *fieldnames* is " +"provided, they will be used and the first row will be included in the " +"results. Regardless of how the fieldnames are determined, the dictionary " +"preserves their original ordering." +msgstr "" +"參數 *fieldnames* 是一個 :term:`sequence`。如果 *fieldnames* 被省略了，檔案 " +"*f* 中第一列的值會被當作欄位標題，且於結果中會被省略。如果 *fieldname* 有提" +"供，它們就會被使用，且第一列會被包含在結果中。不管欄位標題是如何決定的，" +"dictionary 都會保留原始的排序。" + +#: ../../library/csv.rst:165 +msgid "" +"If a row has more fields than fieldnames, the remaining data is put in a " +"list and stored with the fieldname specified by *restkey* (which defaults to " +"``None``). If a non-blank row has fewer fields than fieldnames, the missing " +"values are filled-in with the value of *restval* (which defaults to " +"``None``)." +msgstr "" +"如果一列資料中的欄位比欄位標題還多，其餘的資料及以 *restkey* （預設為 " +"``None``）特指的欄位標題會放入列表當中並儲存。如果一個非空的 (non-blank) 列中" +"的欄位比欄位標題還少，缺少的值則會填入 *restval* （預設為 ``None``）的值。" + +#: ../../library/csv.rst:171 +msgid "" +"All other optional or keyword arguments are passed to the underlying :class:" +"`reader` instance." +msgstr "所有其他選填的引數或關鍵字引數皆會傳遞至下層的 :class:`reader` 實例。" + +#: ../../library/csv.rst:174 ../../library/csv.rst:218 +msgid "" +"If the argument passed to *fieldnames* is an iterator, it will be coerced to " +"a :class:`list`." +msgstr "" +"如果傳遞至 *fieldnames* 的引數是個疊代器，則會被迫成為一個 :class:`list`。" + +#: ../../library/csv.rst:176 +msgid "Returned rows are now of type :class:`OrderedDict`." +msgstr "回傳的列已成為型別 :class:`OrderedDict`。" + +#: ../../library/csv.rst:179 +msgid "Returned rows are now of type :class:`dict`." +msgstr "回傳的列已成為型別 :class:`dict`。" + +#: ../../library/csv.rst:184 +msgid "" +">>> import csv\n" +">>> with open('names.csv', newline='') as csvfile:\n" +"... reader = csv.DictReader(csvfile)\n" +"... for row in reader:\n" +"... print(row['first_name'], row['last_name'])\n" +"...\n" +"Eric Idle\n" +"John Cleese\n" +"\n" +">>> print(row)\n" +"{'first_name': 'John', 'last_name': 'Cleese'}" +msgstr "" +">>> import csv\n" +">>> with open('names.csv', newline='') as csvfile:\n" +"... reader = csv.DictReader(csvfile)\n" +"... for row in reader:\n" +"... print(row['first_name'], row['last_name'])\n" +"...\n" +"Eric Idle\n" +"John Cleese\n" +"\n" +">>> print(row)\n" +"{'first_name': 'John', 'last_name': 'Cleese'}" + +#: ../../library/csv.rst:200 +msgid "" +"Create an object which operates like a regular writer but maps dictionaries " +"onto output rows. The *fieldnames* parameter is a :mod:`sequence " +"` of keys that identify the order in which values in the " +"dictionary passed to the :meth:`~csvwriter.writerow` method are written to " +"file *f*. The optional *restval* parameter specifies the value to be " +"written if the dictionary is missing a key in *fieldnames*. If the " +"dictionary passed to the :meth:`~csvwriter.writerow` method contains a key " +"not found in *fieldnames*, the optional *extrasaction* parameter indicates " +"what action to take. If it is set to ``'raise'``, the default value, a :exc:" +"`ValueError` is raised. If it is set to ``'ignore'``, extra values in the " +"dictionary are ignored. Any other optional or keyword arguments are passed " +"to the underlying :class:`writer` instance." +msgstr "" +"建立一個物件，其運作上就像一般的寫入器，但可以將 dictionary map 到輸出的列" +"上。參數 *fieldnames* 是一個鍵值的 :mod:`sequence ` 且可以辨" +"識 dictionary 中傳遞至 :meth:`~csvwriter.writerow` method 寫入至檔案 *f* 中的" +"值。如果 dictionary 中缺少了 *fieldnames* 的鍵值，則會寫入選填的參數 " +"*restval* 的值。如果傳遞至 :meth:`~csvwriter.writerow` method 的 dictionary " +"包含了一個 *fieldnames* 中不存在的鍵值，選填的參數 *extrasaction* 可以指出該" +"執行的動作。如果它被設定為 ``'raise'``，預設會觸發 :exc:`ValueError`。如果它" +"被設定為 ``'ignore'``，dictionary 中額外的值會被忽略。其他選填的引數或關鍵字" +"引數皆會傳遞至下層的 :class:`writer` 實例。" + +#: ../../library/csv.rst:215 +msgid "" +"Note that unlike the :class:`DictReader` class, the *fieldnames* parameter " +"of the :class:`DictWriter` class is not optional." +msgstr "" +"請記得這不像類別 :class:`DictReader`，在類別 :class:`DictWriter` 中，參數 " +"*fieldnames* 並不是選填的。" + +#: ../../library/csv.rst:222 +msgid "" +"import csv\n" +"\n" +"with open('names.csv', 'w', newline='') as csvfile:\n" +" fieldnames = ['first_name', 'last_name']\n" +" writer = csv.DictWriter(csvfile, fieldnames=fieldnames)\n" +"\n" +" writer.writeheader()\n" +" writer.writerow({'first_name': 'Baked', 'last_name': 'Beans'})\n" +" writer.writerow({'first_name': 'Lovely', 'last_name': 'Spam'})\n" +" writer.writerow({'first_name': 'Wonderful', 'last_name': 'Spam'})" +msgstr "" +"import csv\n" +"\n" +"with open('names.csv', 'w', newline='') as csvfile:\n" +" fieldnames = ['first_name', 'last_name']\n" +" writer = csv.DictWriter(csvfile, fieldnames=fieldnames)\n" +"\n" +" writer.writeheader()\n" +" writer.writerow({'first_name': 'Baked', 'last_name': 'Beans'})\n" +" writer.writerow({'first_name': 'Lovely', 'last_name': 'Spam'})\n" +" writer.writerow({'first_name': 'Wonderful', 'last_name': 'Spam'})" + +#: ../../library/csv.rst:236 +msgid "" +"The :class:`Dialect` class is a container class whose attributes contain " +"information for how to handle doublequotes, whitespace, delimiters, etc. Due " +"to the lack of a strict CSV specification, different applications produce " +"subtly different CSV data. :class:`Dialect` instances define how :class:" +"`reader` and :class:`writer` instances behave." +msgstr "" +"類別 :class:`Dialect` 是一個容器類別，其屬性 (attribute) 包含如何處理雙引號、" +"空白、分隔符號等資訊。由於缺少一個嚴謹的 CSV 技術規範，不同的應用程式會產出有" +"巧妙不同的 CSV 資料。:class:`Dialect` 實例定義了 :class:`reader` 以及 :class:" +"`writer` 的實例該如何表示。" + +#: ../../library/csv.rst:242 +msgid "" +"All available :class:`Dialect` names are returned by :func:`list_dialects`, " +"and they can be registered with specific :class:`reader` and :class:`writer` " +"classes through their initializer (``__init__``) functions like this::" +msgstr "" +"所有可用的 :class:`Dialect` 名稱會透過 :func:`list_dialects` 回傳，且它們可以" +"透過特定 :class:`reader` 及 :class:`writer` 類別的初始器 (initializer, " +"``__init__``) 函式進行註冊，就像這樣： ::" + +#: ../../library/csv.rst:246 +msgid "" +"import csv\n" +"\n" +"with open('students.csv', 'w', newline='') as csvfile:\n" +" writer = csv.writer(csvfile, dialect='unix')" +msgstr "" +"import csv\n" +"\n" +"with open('students.csv', 'w', newline='') as csvfile:\n" +" writer = csv.writer(csvfile, dialect='unix')" + +#: ../../library/csv.rst:254 +msgid "" +"The :class:`excel` class defines the usual properties of an Excel-generated " +"CSV file. It is registered with the dialect name ``'excel'``." +msgstr "" +"類別 :class:`excel` 定義了透過 Excel 產生的 CSV 檔案的慣用屬性。它被註冊的 " +"dialect 名稱為 ``'excel'``。" + +#: ../../library/csv.rst:260 +msgid "" +"The :class:`excel_tab` class defines the usual properties of an Excel-" +"generated TAB-delimited file. It is registered with the dialect name " +"``'excel-tab'``." +msgstr "" +"類別 :class:`excel_tab` 定義了透過 Excel 產生並以 Tab 作為分隔的 CSV 檔案的慣" +"用屬性。它被註冊的 dialect 名稱為 ``'excel-tab'``。" + +#: ../../library/csv.rst:266 +msgid "" +"The :class:`unix_dialect` class defines the usual properties of a CSV file " +"generated on UNIX systems, i.e. using ``'\\n'`` as line terminator and " +"quoting all fields. It is registered with the dialect name ``'unix'``." +msgstr "" +"類別 :class:`unix_dialect` 定義了透過 UNIX 系統產生的 CSV 檔案的慣用屬性，換" +"句話說，使用 ``'\\n'`` 作為換行符號且所有欄位都被引號包覆起來。它被註冊的 " +"dialect 名稱為 ``'unix'``。" + +#: ../../library/csv.rst:275 +msgid "The :class:`Sniffer` class is used to deduce the format of a CSV file." +msgstr "類別 :class:`Sniffer` 被用來推斷 CSV 檔案的格式。" + +#: ../../library/csv.rst:277 +msgid "The :class:`Sniffer` class provides two methods:" +msgstr "類別 :class:`Sniffer` 提供了兩個 method：" + +#: ../../library/csv.rst:281 +msgid "" +"Analyze the given *sample* and return a :class:`Dialect` subclass reflecting " +"the parameters found. If the optional *delimiters* parameter is given, it " +"is interpreted as a string containing possible valid delimiter characters." +msgstr "" +"分析給定的 *sample* 且回傳一個 :class:`Dialect` 子類別，反應出找到的格式參" +"數。如果給定選填的參數 *delimiters*，它會被解釋為一個字串且含有可能、有效的分" +"隔字元。" + +#: ../../library/csv.rst:289 +msgid "" +"Analyze the sample text (presumed to be in CSV format) and return :const:" +"`True` if the first row appears to be a series of column headers. Inspecting " +"each column, one of two key criteria will be considered to estimate if the " +"sample contains a header:" +msgstr "" +"如果第一列的文字顯示將作為一系列的欄位標題，會分析 sample 文字（假定他是 CSV " +"格式）並回傳 :const:`True`。檢查每一欄時，會考慮是否滿足兩個關鍵標準其中之" +"一，判斷 sample 是否包含標題：" + +#: ../../library/csv.rst:294 +msgid "the second through n-th rows contain numeric values" +msgstr "第二列至第 n 列包含數字" + +#: ../../library/csv.rst:295 +msgid "" +"the second through n-th rows contain strings where at least one value's " +"length differs from that of the putative header of that column." +msgstr "" +"第二列到第 n 列包含的字串中至少有一個值的長度與該行的假定標題的長度不同。" + +#: ../../library/csv.rst:298 +msgid "" +"Twenty-one rows after the header are sampled; if more than half of the " +"columns + rows meet the criteria, :const:`True` is returned." +msgstr "" +"對標頭之後的二十一個列進行取樣；如果超過一半的行及列滿足條件，則回傳 :const:" +"`True`。" + +#: ../../library/csv.rst:303 +msgid "" +"This method is a rough heuristic and may produce both false positives and " +"negatives." +msgstr "" +"此方法是一個粗略的啟發，可能會產生偽陽性及偽陰性 (false positives and " +"negatives)。" + +#: ../../library/csv.rst:306 +msgid "An example for :class:`Sniffer` use::" +msgstr "一個 :class:`Sniffer` 的使用範例： ::" + +#: ../../library/csv.rst:308 +msgid "" +"with open('example.csv', newline='') as csvfile:\n" +" dialect = csv.Sniffer().sniff(csvfile.read(1024))\n" +" csvfile.seek(0)\n" +" reader = csv.reader(csvfile, dialect)\n" +" # ... process CSV file contents here ..." +msgstr "" +"with open('example.csv', newline='') as csvfile:\n" +" dialect = csv.Sniffer().sniff(csvfile.read(1024))\n" +" csvfile.seek(0)\n" +" reader = csv.reader(csvfile, dialect)\n" +" # ... 在這邊處理 CSV 檔案 ..." + +#: ../../library/csv.rst:317 +msgid "The :mod:`csv` module defines the following constants:" +msgstr ":mod:`csv` 模組定義了以下常數：" + +#: ../../library/csv.rst:321 +msgid "Instructs :class:`writer` objects to quote all fields." +msgstr "引導 :class:`writer` 物件引用所有欄位。" + +#: ../../library/csv.rst:326 +msgid "" +"Instructs :class:`writer` objects to only quote those fields which contain " +"special characters such as *delimiter*, *quotechar*, ``'\\r'``, ``'\\n'`` or " +"any of the characters in *lineterminator*." +msgstr "" +"引導 :class:`writer` 物件只引用包含特殊字元的欄位，例如：*delimiter*、" +"*quotechar*、``'\\r'``、``'\\n'`` 或是 *lineterminator* 的其他字元。" + +#: ../../library/csv.rst:333 +msgid "Instructs :class:`writer` objects to quote all non-numeric fields." +msgstr "引導 :class:`writer` 物件引用所有非數字的欄位。" + +#: ../../library/csv.rst:335 +msgid "" +"Instructs :class:`reader` objects to convert all non-quoted fields to type :" +"class:`float`." +msgstr "引導 :class:`reader` 物件轉換所有非引用的欄位為 :class:`float`。" + +#: ../../library/csv.rst:338 +msgid "" +"Some numeric types, such as :class:`bool`, :class:`~fractions.Fraction`, or :" +"class:`~enum.IntEnum`, have a string representation that cannot be converted " +"to :class:`float`. They cannot be read in the :data:`QUOTE_NONNUMERIC` and :" +"data:`QUOTE_STRINGS` modes." +msgstr "" + +#: ../../library/csv.rst:346 +msgid "" +"Instructs :class:`writer` objects to never quote fields. When the current " +"*delimiter*, *quotechar*, *escapechar*, ``'\\r'``, ``'\\n'`` or any of the " +"characters in *lineterminator* occurs in output data it is preceded by the " +"current *escapechar* character. If *escapechar* is not set, the writer will " +"raise :exc:`Error` if any characters that require escaping are encountered. " +"Set *quotechar* to ``None`` to prevent its escaping." +msgstr "" +"引導 :class:`writer` 物件不得引用欄位。當目前的 *delimiter*、*quotechar*、" +"``'\\r'``、``'\\n'`` 或是 *lineterminator* 的其他字元出現在輸出資料時，在他之" +"前的字元是目前的 *escapechar*。如果沒有設定 *escapechar*，若遇到任何字元需要" +"逸出，寫入器則會引發 :exc:`Error`。設定 *quotechar* 為 ``None`` 以防止逸出。" + +#: ../../library/csv.rst:354 +msgid "" +"Instructs :class:`reader` objects to perform no special processing of quote " +"characters." +msgstr "引導 :class:`reader` 物件不對引號進行特別處理。" + +#: ../../library/csv.rst:358 +msgid "" +"Instructs :class:`writer` objects to quote all fields which are not " +"``None``. This is similar to :data:`QUOTE_ALL`, except that if a field " +"value is ``None`` an empty (unquoted) string is written." +msgstr "" +"引導 :class:`writer` 物件引用所有非 ``None`` 的欄位。這與 :data:`QUOTE_ALL` " +"相似，除非如果欄位值為 ``None``，該欄位則被寫成空（沒有引號）字串。" + +#: ../../library/csv.rst:362 +msgid "" +"Instructs :class:`reader` objects to interpret an empty (unquoted) field as " +"``None`` and to otherwise behave as :data:`QUOTE_ALL`." +msgstr "" +"引導 :class:`reader` 物件將空（沒有引號）欄位直譯 (interpret) 為 ``None``，否" +"則會和 :data:`QUOTE_ALL` 有相同的表現方式。" + +#: ../../library/csv.rst:369 +msgid "" +"Instructs :class:`writer` objects to always place quotes around fields which " +"are strings. This is similar to :data:`QUOTE_NONNUMERIC`, except that if a " +"field value is ``None`` an empty (unquoted) string is written." +msgstr "" +"引導 :class:`writer` 物件永遠在字串的欄位前後放置引號。這與 :data:" +"`QUOTE_NONNUMERIC` 相似，除非如果欄位值為 ``None``，該欄位則被寫成空（沒有引" +"號）字串。" + +#: ../../library/csv.rst:373 +msgid "" +"Instructs :class:`reader` objects to interpret an empty (unquoted) string as " +"``None`` and to otherwise behave as :data:`QUOTE_NONNUMERIC`." +msgstr "" +"引導 :class:`reader` 物件將空（沒有引號）字串直譯為 ``None``，否則會和 :data:" +"`QUOTE_NONNUMERIC` 有相同的表現方式。" + +#: ../../library/csv.rst:378 +msgid "The :mod:`csv` module defines the following exception:" +msgstr ":mod:`csv` 模組定義下列例外：" + +#: ../../library/csv.rst:383 +msgid "Raised by any of the functions when an error is detected." +msgstr "當偵測到錯誤時，任何函式都可以引發。" + +#: ../../library/csv.rst:388 +msgid "Dialects and Formatting Parameters" +msgstr "Dialect 與格式參數" + +#: ../../library/csv.rst:390 +msgid "" +"To make it easier to specify the format of input and output records, " +"specific formatting parameters are grouped together into dialects. A " +"dialect is a subclass of the :class:`Dialect` class containing various " +"attributes describing the format of the CSV file. When creating :class:" +"`reader` or :class:`writer` objects, the programmer can specify a string or " +"a subclass of the :class:`Dialect` class as the dialect parameter. In " +"addition to, or instead of, the *dialect* parameter, the programmer can also " +"specify individual formatting parameters, which have the same names as the " +"attributes defined below for the :class:`Dialect` class." +msgstr "" +"為了讓指定輸入及輸出紀錄的格式更方便，特定的格式化參數會被組成 dialect。一個 " +"dialect 是 :class:`Dialect` class 的子類別，其包含多個描述 CSV 檔案格式的多個" +"屬性。當建立 :class:`reader` 或 :class:`writer` 物件時，程式設計師可以指定一" +"個字串或是一個 :class:`Dialect` 的子類別作為 dialect 參數。此外，或是作為替" +"代，在\\ *dialect*\\ 參數中，程式設計師可以指定個別的格式化參數，其與 :class:" +"`Dialect` 類別定義的屬性具有相同的名字。" + +#: ../../library/csv.rst:400 +msgid "Dialects support the following attributes:" +msgstr "Dialect 支援下列屬性：" + +#: ../../library/csv.rst:405 +msgid "" +"A one-character string used to separate fields. It defaults to ``','``." +msgstr "一個單一字元 (one-character) 的字串可已用來分割欄位。預設為 ``','``。" + +#: ../../library/csv.rst:410 +msgid "" +"Controls how instances of *quotechar* appearing inside a field should " +"themselves be quoted. When :const:`True`, the character is doubled. When :" +"const:`False`, the *escapechar* is used as a prefix to the *quotechar*. It " +"defaults to :const:`True`." +msgstr "" +"控制 *quotechar* 的實例何時出現在欄位之中，並讓它們自己被放在引號之內。當屬性" +"為 :const:`True`，字元會是雙引號。若為 :const:`False`，在 *quotechar* 之前會" +"先使用 *escapechar* 作為前綴字。預設為 :const:`True`。" + +#: ../../library/csv.rst:415 +msgid "" +"On output, if *doublequote* is :const:`False` and no *escapechar* is set, :" +"exc:`Error` is raised if a *quotechar* is found in a field." +msgstr "" +"在輸出時，若 *doublequote* 是 :const:`False` 且\\ *逸出字元*\\ 沒有被設定，當" +"一個\\ *引號*\\ 在欄位中被發現時，:exc:`Error` 會被引發。" + +#: ../../library/csv.rst:421 +msgid "" +"A one-character string used by the writer to escape characters that require " +"escaping:" +msgstr "一個單一字元的字串，會被寫入器用來逸出需要逸出的字元：" + +#: ../../library/csv.rst:424 +msgid "" +"the *delimiter*, the *quotechar*, ``'\\r'``, ``'\\n'`` and any of the " +"characters in *lineterminator* are escaped if *quoting* is set to :const:" +"`QUOTE_NONE`;" +msgstr "" + +#: ../../library/csv.rst:427 +msgid "the *quotechar* is escaped if *doublequote* is :const:`False`;" +msgstr "" + +#: ../../library/csv.rst:428 +msgid "the *escapechar* itself." +msgstr "*escapechar* 本身。" + +#: ../../library/csv.rst:430 +msgid "" +"On reading, the *escapechar* removes any special meaning from the following " +"character. It defaults to :const:`None`, which disables escaping." +msgstr "" +"在讀取時，*escapechar* 會移除後面字元的任何特殊意義。預設為 :const:`None`，表" +"示禁止逸出。" + +#: ../../library/csv.rst:433 +msgid "An empty *escapechar* is not allowed." +msgstr "*escapechar* 為空是不被接受的。" + +#: ../../library/csv.rst:438 +msgid "" +"The string used to terminate lines produced by the :class:`writer`. It " +"defaults to ``'\\r\\n'``." +msgstr "由 :class:`writer` 產生被用來分行的字串。預設為 ``'\\r\\n'``。" + +#: ../../library/csv.rst:443 +msgid "" +"The :class:`reader` is hard-coded to recognise either ``'\\r'`` or ``'\\n'`` " +"as end-of-line, and ignores *lineterminator*. This behavior may change in " +"the future." +msgstr "" +":class:`reader` 是 hard-coded 辨別 ``'\\r'`` or ``'\\n'`` 作為行尾 (end-of-" +"line)，並忽略\\ *lineterminator*。未來可能會改變這個行為。" + +#: ../../library/csv.rst:450 +msgid "" +"A one-character string used to quote fields containing special characters, " +"such as the *delimiter* or the *quotechar*, or which contain new-line " +"characters (``'\\r'``, ``'\\n'`` or any of the characters in " +"*lineterminator*). It defaults to ``'\"'``. Can be set to ``None`` to " +"prevent escaping ``'\"'`` if *quoting* is set to :const:`QUOTE_NONE`." +msgstr "" +"一個單一字元的字串被用於引用包含特殊字元的欄位，像是 *delimiter*、" +"*quotechar* 或是換行字元（``'\\r'``、``'\\n'`` 或是 *lineterminator* 的任一字" +"元）。預設為 ``'\"'``。如果 *quoting* 設定為 :const:`QUOTE_NONE`，可以設定為 " +"``None`` 以防止逸出 ``'\"'``。" + +#: ../../library/csv.rst:457 +msgid "An empty *quotechar* is not allowed." +msgstr "*quotechar* 為空是不被允許的。" + +#: ../../library/csv.rst:462 +msgid "" +"Controls when quotes should be generated by the writer and recognised by the " +"reader. It can take on any of the :ref:`QUOTE_\\* constants ` and defaults to :const:`QUOTE_MINIMAL` if *quotechar* is not " +"``None``, and :const:`QUOTE_NONE` otherwise." +msgstr "" +"控制 writer 何時產生引號，以及 reader 如何辨識引號。如 *quotechar* 不為 " +"``None``，則可以使用任何 :ref:`QUOTE_\\* 常數 `\\ 且預設為 :" +"const:`QUOTE_MINIMAL`。否則預設為 :const:`QUOTE_NONE`。" + +#: ../../library/csv.rst:470 +msgid "" +"When :const:`True`, spaces immediately following the *delimiter* are " +"ignored. The default is :const:`False`. When combining ``delimiter=' '`` " +"with ``skipinitialspace=True``, unquoted empty fields are not allowed." +msgstr "" +"若為 :const:`True`，在緊接著\\ *delimiter*\\ 後的空格會被忽略。預設為 :const:" +"`False`。當結合 ``delimiter=' '`` 與 ``skipinitialspace=True`` 時，不允許沒有" +"引號的空欄位。" + +#: ../../library/csv.rst:477 +msgid "" +"When ``True``, raise exception :exc:`Error` on bad CSV input. The default is " +"``False``." +msgstr "" +"若為 ``True``，若有錯誤的 CSV 輸入則會引發 :exc:`Error`。預設為 ``False``。" + +#: ../../library/csv.rst:483 +msgid "Reader Objects" +msgstr "讀取器物件" + +#: ../../library/csv.rst:485 +msgid "" +"Reader objects (:class:`DictReader` instances and objects returned by the :" +"func:`reader` function) have the following public methods:" +msgstr "" +"讀取器物件（:func:`reader` 函式回傳的 :class:`DictReader` 實例與物件）有下列" +"公開方法 (public method)：" + +#: ../../library/csv.rst:490 +msgid "" +"Return the next row of the reader's iterable object as a list (if the object " +"was returned from :func:`reader`) or a dict (if it is a :class:`DictReader` " +"instance), parsed according to the current :class:`Dialect`. Usually you " +"should call this as ``next(reader)``." +msgstr "" +"回傳一個列表為讀入器的可疊代物件的下一列內容（若該物件是由 :func:`reader` 回" +"傳）或是一個 dict（若為 :class:`DictReader` 實例），會依據目前的 :class:" +"`Dialect` 進行剖析。通常會用 ``next(reader)`` 來進行呼叫。" + +#: ../../library/csv.rst:496 +msgid "Reader objects have the following public attributes:" +msgstr "讀取器物件有下列公開屬性 (public attributes)：" + +#: ../../library/csv.rst:500 +msgid "A read-only description of the dialect in use by the parser." +msgstr "dialect 的唯讀敘述，會被剖析器使用。" + +#: ../../library/csv.rst:505 +msgid "" +"The number of lines read from the source iterator. This is not the same as " +"the number of records returned, as records can span multiple lines." +msgstr "來源疊代器所讀取的行數。這與回傳的紀錄數不同，因為可以進行跨行紀錄。" + +#: ../../library/csv.rst:509 +msgid "DictReader objects have the following public attribute:" +msgstr "DictReader 物件有下列公開屬性：" + +#: ../../library/csv.rst:513 +msgid "" +"If not passed as a parameter when creating the object, this attribute is " +"initialized upon first access or when the first record is read from the file." +msgstr "" +"若在建立物件時沒有作為參數傳遞，這個屬性會在第一次存取之前或是第一筆資料被讀" +"取之前進行初始化 (initialize)。" + +#: ../../library/csv.rst:520 +msgid "Writer Objects" +msgstr "寫入器物件" + +#: ../../library/csv.rst:522 +msgid "" +":class:`writer` objects (:class:`DictWriter` instances and objects returned " +"by the :func:`writer` function) have the following public methods. A *row* " +"must be an iterable of strings or numbers for :class:`writer` objects and a " +"dictionary mapping fieldnames to strings or numbers (by passing them " +"through :func:`str` first) for :class:`DictWriter` objects. Note that " +"complex numbers are written out surrounded by parens. This may cause some " +"problems for other programs which read CSV files (assuming they support " +"complex numbers at all)." +msgstr "" +":class:`writer` 物件（:func:`writer` 函式回傳的 :class:`DictWriter` 實例與物" +"件）有下列公開方法。對於 :class:`writer` 物件而言，一個\\ *列*\\ 中必須為一個" +"可疊代的字串或是數字；對於 :class:`DictWriter` 物件而言，則必須為一個 " +"dictionary ，且可以對應欄位標題至字串或數字（會先透過 :func:`str` 進行傳" +"遞）。請注意，在寫入複數 (complex number) 時會用小括號 (parens) 包起來。這可" +"能在其他程式讀取 CSV 檔案時導致某些問題（假設他們完全支援複雜數字）。" + +#: ../../library/csv.rst:533 +msgid "" +"Write the *row* parameter to the writer's file object, formatted according " +"to the current :class:`Dialect`. Return the return value of the call to the " +"*write* method of the underlying file object." +msgstr "" +"將參數 *row* 寫入至寫入器的檔案物件中，並依照目前的 :class:`Dialect` 進行格式" +"化。回傳下層檔案物件 *write* 方法的回傳值。" + +#: ../../library/csv.rst:537 +msgid "Added support of arbitrary iterables." +msgstr "新增對任意可疊代物件 (arbitrary iterables) 的支援。" + +#: ../../library/csv.rst:542 +msgid "" +"Write all elements in *rows* (an iterable of *row* objects as described " +"above) to the writer's file object, formatted according to the current " +"dialect." +msgstr "" +"將 *rows* 中所有元素（為上述的一個可疊代的 *row* 物件）寫入至寫入器的檔案物件" +"中，並依照目前的 dialect 進行格式化。" + +#: ../../library/csv.rst:546 +msgid "Writer objects have the following public attribute:" +msgstr "寫入器物件有下列公開屬性：" + +#: ../../library/csv.rst:551 +msgid "A read-only description of the dialect in use by the writer." +msgstr "dialect 的唯讀敘述，會被寫入器使用。" + +#: ../../library/csv.rst:554 +msgid "DictWriter objects have the following public method:" +msgstr "DictWriter 物件有下列公開方法：" + +#: ../../library/csv.rst:559 +msgid "" +"Write a row with the field names (as specified in the constructor) to the " +"writer's file object, formatted according to the current dialect. Return the " +"return value of the :meth:`csvwriter.writerow` call used internally." +msgstr "" +"將具欄位標題的一列（於建構函式 (constructor) 中指定的）寫入至寫入器的檔案物件" +"中，並依照目前的 dialect 進行格式化。回傳內部呼叫 :meth:`csvwriter.writerow` " +"的回傳值。" + +#: ../../library/csv.rst:564 +msgid "" +":meth:`writeheader` now also returns the value returned by the :meth:" +"`csvwriter.writerow` method it uses internally." +msgstr "" +":meth:`writeheader` 現在也會回傳內部呼叫 :meth:`csvwriter.writerow` 的回傳" +"值。" + +#: ../../library/csv.rst:572 +msgid "Examples" +msgstr "範例" + +#: ../../library/csv.rst:574 +msgid "The simplest example of reading a CSV file::" +msgstr "最簡單的讀取 CSV 檔案範例： ::" + +#: ../../library/csv.rst:576 +msgid "" +"import csv\n" +"with open('some.csv', newline='') as f:\n" +" reader = csv.reader(f)\n" +" for row in reader:\n" +" print(row)" +msgstr "" +"import csv\n" +"with open('some.csv', newline='') as f:\n" +" reader = csv.reader(f)\n" +" for row in reader:\n" +" print(row)" + +#: ../../library/csv.rst:582 +msgid "Reading a file with an alternate format::" +msgstr "讀取一個其他格式的檔案： ::" + +#: ../../library/csv.rst:584 +msgid "" +"import csv\n" +"with open('passwd', newline='') as f:\n" +" reader = csv.reader(f, delimiter=':', quoting=csv.QUOTE_NONE)\n" +" for row in reader:\n" +" print(row)" +msgstr "" +"import csv\n" +"with open('passwd', newline='') as f:\n" +" reader = csv.reader(f, delimiter=':', quoting=csv.QUOTE_NONE)\n" +" for row in reader:\n" +" print(row)" + +#: ../../library/csv.rst:590 +msgid "The corresponding simplest possible writing example is::" +msgstr "相對最簡單、可行的寫入範例為： ::" + +#: ../../library/csv.rst:592 +msgid "" +"import csv\n" +"with open('some.csv', 'w', newline='') as f:\n" +" writer = csv.writer(f)\n" +" writer.writerows(someiterable)" +msgstr "" +"import csv\n" +"with open('some.csv', 'w', newline='') as f:\n" +" writer = csv.writer(f)\n" +" writer.writerows(someiterable)" + +#: ../../library/csv.rst:597 +msgid "" +"Since :func:`open` is used to open a CSV file for reading, the file will by " +"default be decoded into unicode using the system default encoding (see :func:" +"`locale.getencoding`). To decode a file using a different encoding, use the " +"``encoding`` argument of open::" +msgstr "" +"當 :func:`open` 被使用於開啟並讀取一個 CSV 檔案，該檔案會預設使用系統預設的編" +"碼格式（請見 :func:`locale.getencoding`），並解碼為 unicode。若要使用不同編碼" +"格式進行檔案解碼，請使用 open 函式的 ``encoding`` 引數： ::" + +#: ../../library/csv.rst:602 +msgid "" +"import csv\n" +"with open('some.csv', newline='', encoding='utf-8') as f:\n" +" reader = csv.reader(f)\n" +" for row in reader:\n" +" print(row)" +msgstr "" +"import csv\n" +"with open('some.csv', newline='', encoding='utf-8') as f:\n" +" reader = csv.reader(f)\n" +" for row in reader:\n" +" print(row)" + +#: ../../library/csv.rst:608 +msgid "" +"The same applies to writing in something other than the system default " +"encoding: specify the encoding argument when opening the output file." +msgstr "" +"同理可以應用到使用不同編碼格式進行寫入：當開啟輸出檔案時，指定 ``encoding`` " +"引數。" + +#: ../../library/csv.rst:611 +msgid "Registering a new dialect::" +msgstr "註冊一個新的 dialect ： ::" + +#: ../../library/csv.rst:613 +msgid "" +"import csv\n" +"csv.register_dialect('unixpwd', delimiter=':', quoting=csv.QUOTE_NONE)\n" +"with open('passwd', newline='') as f:\n" +" reader = csv.reader(f, 'unixpwd')" +msgstr "" +"import csv\n" +"csv.register_dialect('unixpwd', delimiter=':', quoting=csv.QUOTE_NONE)\n" +"with open('passwd', newline='') as f:\n" +" reader = csv.reader(f, 'unixpwd')" + +#: ../../library/csv.rst:618 +msgid "" +"A slightly more advanced use of the reader --- catching and reporting " +"errors::" +msgstr "稍微進階的讀取器用法 -- 擷取及回報錯誤： ::" + +#: ../../library/csv.rst:620 +msgid "" +"import csv, sys\n" +"filename = 'some.csv'\n" +"with open(filename, newline='') as f:\n" +" reader = csv.reader(f)\n" +" try:\n" +" for row in reader:\n" +" print(row)\n" +" except csv.Error as e:\n" +" sys.exit(f'file {filename}, line {reader.line_num}: {e}')" +msgstr "" +"import csv, sys\n" +"filename = 'some.csv'\n" +"with open(filename, newline='') as f:\n" +" reader = csv.reader(f)\n" +" try:\n" +" for row in reader:\n" +" print(row)\n" +" except csv.Error as e:\n" +" sys.exit(f'file {filename}, line {reader.line_num}: {e}')" + +#: ../../library/csv.rst:630 +msgid "" +"And while the module doesn't directly support parsing strings, it can easily " +"be done::" +msgstr "而當模組無法直接支援剖析字串時，仍可以輕鬆的解決： ::" + +#: ../../library/csv.rst:633 +msgid "" +"import csv\n" +"for row in csv.reader(['one,two,three']):\n" +" print(row)" +msgstr "" +"import csv\n" +"for row in csv.reader(['one,two,three']):\n" +" print(row)" + +#: ../../library/csv.rst:639 +msgid "Footnotes" +msgstr "註解" + +#: ../../library/csv.rst:640 +msgid "" +"If ``newline=''`` is not specified, newlines embedded inside quoted fields " +"will not be interpreted correctly, and on platforms that use ``\\r\\n`` line " +"endings on write an extra ``\\r`` will be added. It should always be safe " +"to specify ``newline=''``, since the csv module does its own (:term:" +"`universal `) newline handling." +msgstr "" +"如果 ``newline=''`` 沒有被指定，則嵌入引號中的換行符號不會被正確直譯，使用 " +"``\\r\\n`` 行尾 (line ending) 的平台會寫入額外的 ``\\r``。自從 csv 模組有自" +"己 (:term:`統一的 `) 換行處理方式，因此指定 " +"``newline=''`` 會永遠是安全的。" + +#: ../../library/csv.rst:11 +msgid "csv" +msgstr "csv" + +#: ../../library/csv.rst:11 +msgid "data" +msgstr "data（資料）" + +#: ../../library/csv.rst:11 +msgid "tabular" +msgstr "tabular（表格）" + +#: ../../library/csv.rst:53 +msgid "universal newlines" +msgstr "universal newlines" + +#: ../../library/csv.rst:53 +msgid "csv.reader function" +msgstr "csv.reader 函式" diff --git a/library/ctypes.po b/library/ctypes.po index 85c879ff7b..3064cb1d04 100644 --- a/library/ctypes.po +++ b/library/ctypes.po @@ -1,4918 +1,4918 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-12-17 00:14+0000\n" -"PO-Revision-Date: 2023-04-26 02:59+0800\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" -"X-Generator: Poedit 3.2.2\n" - -#: ../../library/ctypes.rst:2 -msgid ":mod:`!ctypes` --- A foreign function library for Python" -msgstr ":mod:`!ctypes` --- 用於 Python 的外部函式庫" - -#: ../../library/ctypes.rst:9 -msgid "**Source code:** :source:`Lib/ctypes`" -msgstr "**原始碼：**\\ :source:`Lib/ctypes`" - -#: ../../library/ctypes.rst:13 -msgid "" -":mod:`ctypes` is a foreign function library for Python. It provides C " -"compatible data types, and allows calling functions in DLLs or shared " -"libraries. It can be used to wrap these libraries in pure Python." -msgstr "" - -#: ../../includes/optional-module.rst:1 -msgid "" -"This is an :term:`optional module`. If it is missing from your copy of " -"CPython, look for documentation from your distributor (that is, whoever " -"provided Python to you). If you are the distributor, see :ref:`optional-" -"module-requirements`." -msgstr "" - -#: ../../library/ctypes.rst:23 -msgid "ctypes tutorial" -msgstr "ctypes 教學" - -#: ../../library/ctypes.rst:25 -msgid "" -"Note: The code samples in this tutorial use :mod:`doctest` to make sure that " -"they actually work. Since some code samples behave differently under Linux, " -"Windows, or macOS, they contain doctest directives in comments." -msgstr "" - -#: ../../library/ctypes.rst:29 -msgid "" -"Note: Some code samples reference the ctypes :class:`c_int` type. On " -"platforms where ``sizeof(long) == sizeof(int)`` it is an alias to :class:" -"`c_long`. So, you should not be confused if :class:`c_long` is printed if " -"you would expect :class:`c_int` --- they are actually the same type." -msgstr "" - -#: ../../library/ctypes.rst:37 -msgid "Loading dynamic link libraries" -msgstr "" - -#: ../../library/ctypes.rst:39 -msgid "" -":mod:`ctypes` exports the *cdll*, and on Windows *windll* and *oledll* " -"objects, for loading dynamic link libraries." -msgstr "" - -#: ../../library/ctypes.rst:42 -msgid "" -"You load libraries by accessing them as attributes of these objects. *cdll* " -"loads libraries which export functions using the standard ``cdecl`` calling " -"convention, while *windll* libraries call functions using the ``stdcall`` " -"calling convention. *oledll* also uses the ``stdcall`` calling convention, " -"and assumes the functions return a Windows :c:type:`!HRESULT` error code. " -"The error code is used to automatically raise an :class:`OSError` exception " -"when the function call fails." -msgstr "" - -#: ../../library/ctypes.rst:50 -msgid "" -"Windows errors used to raise :exc:`WindowsError`, which is now an alias of :" -"exc:`OSError`." -msgstr "" - -#: ../../library/ctypes.rst:55 -msgid "" -"Here are some examples for Windows. Note that ``msvcrt`` is the MS standard " -"C library containing most standard C functions, and uses the ``cdecl`` " -"calling convention::" -msgstr "" - -#: ../../library/ctypes.rst:59 -msgid "" -">>> from ctypes import *\n" -">>> print(windll.kernel32)\n" -"\n" -">>> print(cdll.msvcrt)\n" -"\n" -">>> libc = cdll.msvcrt\n" -">>>" -msgstr "" -">>> from ctypes import *\n" -">>> print(windll.kernel32)\n" -"\n" -">>> print(cdll.msvcrt)\n" -"\n" -">>> libc = cdll.msvcrt\n" -">>>" - -#: ../../library/ctypes.rst:67 -msgid "Windows appends the usual ``.dll`` file suffix automatically." -msgstr "" - -#: ../../library/ctypes.rst:70 -msgid "" -"Accessing the standard C library through ``cdll.msvcrt`` will use an " -"outdated version of the library that may be incompatible with the one being " -"used by Python. Where possible, use native Python functionality, or else " -"import and use the ``msvcrt`` module." -msgstr "" - -#: ../../library/ctypes.rst:75 -msgid "" -"On Linux, it is required to specify the filename *including* the extension " -"to load a library, so attribute access can not be used to load libraries. " -"Either the :meth:`~LibraryLoader.LoadLibrary` method of the dll loaders " -"should be used, or you should load the library by creating an instance of " -"CDLL by calling the constructor::" -msgstr "" - -#: ../../library/ctypes.rst:81 -msgid "" -">>> cdll.LoadLibrary(\"libc.so.6\")\n" -"\n" -">>> libc = CDLL(\"libc.so.6\")\n" -">>> libc\n" -"\n" -">>>" -msgstr "" -">>> cdll.LoadLibrary(\"libc.so.6\")\n" -"\n" -">>> libc = CDLL(\"libc.so.6\")\n" -">>> libc\n" -"\n" -">>>" - -#: ../../library/ctypes.rst:94 -msgid "Accessing functions from loaded dlls" -msgstr "" - -#: ../../library/ctypes.rst:96 -msgid "Functions are accessed as attributes of dll objects::" -msgstr "" - -#: ../../library/ctypes.rst:98 -msgid "" -">>> libc.printf\n" -"<_FuncPtr object at 0x...>\n" -">>> print(windll.kernel32.GetModuleHandleA)\n" -"<_FuncPtr object at 0x...>\n" -">>> print(windll.kernel32.MyOwnFunction)\n" -"Traceback (most recent call last):\n" -" File \"\", line 1, in \n" -" File \"ctypes.py\", line 239, in __getattr__\n" -" func = _StdcallFuncPtr(name, self)\n" -"AttributeError: function 'MyOwnFunction' not found\n" -">>>" -msgstr "" -">>> libc.printf\n" -"<_FuncPtr object at 0x...>\n" -">>> print(windll.kernel32.GetModuleHandleA)\n" -"<_FuncPtr object at 0x...>\n" -">>> print(windll.kernel32.MyOwnFunction)\n" -"Traceback (most recent call last):\n" -" File \"\", line 1, in \n" -" File \"ctypes.py\", line 239, in __getattr__\n" -" func = _StdcallFuncPtr(name, self)\n" -"AttributeError: function 'MyOwnFunction' not found\n" -">>>" - -#: ../../library/ctypes.rst:110 -msgid "" -"Note that win32 system dlls like ``kernel32`` and ``user32`` often export " -"ANSI as well as UNICODE versions of a function. The UNICODE version is " -"exported with a ``W`` appended to the name, while the ANSI version is " -"exported with an ``A`` appended to the name. The win32 ``GetModuleHandle`` " -"function, which returns a *module handle* for a given module name, has the " -"following C prototype, and a macro is used to expose one of them as " -"``GetModuleHandle`` depending on whether UNICODE is defined or not::" -msgstr "" - -#: ../../library/ctypes.rst:118 -msgid "" -"/* ANSI version */\n" -"HMODULE GetModuleHandleA(LPCSTR lpModuleName);\n" -"/* UNICODE version */\n" -"HMODULE GetModuleHandleW(LPCWSTR lpModuleName);" -msgstr "" -"/* ANSI 版本 */\n" -"HMODULE GetModuleHandleA(LPCSTR lpModuleName);\n" -"/* UNICODE 版本 */\n" -"HMODULE GetModuleHandleW(LPCWSTR lpModuleName);" - -#: ../../library/ctypes.rst:123 -msgid "" -"*windll* does not try to select one of them by magic, you must access the " -"version you need by specifying ``GetModuleHandleA`` or ``GetModuleHandleW`` " -"explicitly, and then call it with bytes or string objects respectively." -msgstr "" - -#: ../../library/ctypes.rst:127 -msgid "" -"Sometimes, dlls export functions with names which aren't valid Python " -"identifiers, like ``\"??2@YAPAXI@Z\"``. In this case you have to use :func:" -"`getattr` to retrieve the function::" -msgstr "" - -#: ../../library/ctypes.rst:131 -msgid "" -">>> getattr(cdll.msvcrt, \"??2@YAPAXI@Z\")\n" -"<_FuncPtr object at 0x...>\n" -">>>" -msgstr "" -">>> getattr(cdll.msvcrt, \"??2@YAPAXI@Z\")\n" -"<_FuncPtr object at 0x...>\n" -">>>" - -#: ../../library/ctypes.rst:135 -msgid "" -"On Windows, some dlls export functions not by name but by ordinal. These " -"functions can be accessed by indexing the dll object with the ordinal " -"number::" -msgstr "" - -#: ../../library/ctypes.rst:138 -msgid "" -">>> cdll.kernel32[1]\n" -"<_FuncPtr object at 0x...>\n" -">>> cdll.kernel32[0]\n" -"Traceback (most recent call last):\n" -" File \"\", line 1, in \n" -" File \"ctypes.py\", line 310, in __getitem__\n" -" func = _StdcallFuncPtr(name, self)\n" -"AttributeError: function ordinal 0 not found\n" -">>>" -msgstr "" -">>> cdll.kernel32[1]\n" -"<_FuncPtr object at 0x...>\n" -">>> cdll.kernel32[0]\n" -"Traceback (most recent call last):\n" -" File \"\", line 1, in \n" -" File \"ctypes.py\", line 310, in __getitem__\n" -" func = _StdcallFuncPtr(name, self)\n" -"AttributeError: function ordinal 0 not found\n" -">>>" - -#: ../../library/ctypes.rst:152 -msgid "Calling functions" -msgstr "呼叫函式" - -#: ../../library/ctypes.rst:154 -msgid "" -"You can call these functions like any other Python callable. This example " -"uses the ``rand()`` function, which takes no arguments and returns a pseudo-" -"random integer::" -msgstr "" - -#: ../../library/ctypes.rst:157 -msgid "" -">>> print(libc.rand())\n" -"1804289383" -msgstr "" -">>> print(libc.rand())\n" -"1804289383" - -#: ../../library/ctypes.rst:160 -msgid "" -"On Windows, you can call the ``GetModuleHandleA()`` function, which returns " -"a win32 module handle (passing ``None`` as single argument to call it with a " -"``NULL`` pointer)::" -msgstr "" - -#: ../../library/ctypes.rst:163 -msgid "" -">>> print(hex(windll.kernel32.GetModuleHandleA(None)))\n" -"0x1d000000\n" -">>>" -msgstr "" -">>> print(hex(windll.kernel32.GetModuleHandleA(None)))\n" -"0x1d000000\n" -">>>" - -#: ../../library/ctypes.rst:167 -msgid "" -":exc:`ValueError` is raised when you call an ``stdcall`` function with the " -"``cdecl`` calling convention, or vice versa::" -msgstr "" - -#: ../../library/ctypes.rst:170 -msgid "" -">>> cdll.kernel32.GetModuleHandleA(None)\n" -"Traceback (most recent call last):\n" -" File \"\", line 1, in \n" -"ValueError: Procedure probably called with not enough arguments (4 bytes " -"missing)\n" -">>>\n" -"\n" -">>> windll.msvcrt.printf(b\"spam\")\n" -"Traceback (most recent call last):\n" -" File \"\", line 1, in \n" -"ValueError: Procedure probably called with too many arguments (4 bytes in " -"excess)\n" -">>>" -msgstr "" -">>> cdll.kernel32.GetModuleHandleA(None)\n" -"Traceback (most recent call last):\n" -" File \"\", line 1, in \n" -"ValueError: Procedure probably called with not enough arguments (4 bytes " -"missing)\n" -">>>\n" -"\n" -">>> windll.msvcrt.printf(b\"spam\")\n" -"Traceback (most recent call last):\n" -" File \"\", line 1, in \n" -"ValueError: Procedure probably called with too many arguments (4 bytes in " -"excess)\n" -">>>" - -#: ../../library/ctypes.rst:182 -msgid "" -"To find out the correct calling convention you have to look into the C " -"header file or the documentation for the function you want to call." -msgstr "" - -#: ../../library/ctypes.rst:185 -msgid "" -"On Windows, :mod:`ctypes` uses win32 structured exception handling to " -"prevent crashes from general protection faults when functions are called " -"with invalid argument values::" -msgstr "" - -#: ../../library/ctypes.rst:189 -msgid "" -">>> windll.kernel32.GetModuleHandleA(32)\n" -"Traceback (most recent call last):\n" -" File \"\", line 1, in \n" -"OSError: exception: access violation reading 0x00000020\n" -">>>" -msgstr "" -">>> windll.kernel32.GetModuleHandleA(32)\n" -"Traceback (most recent call last):\n" -" File \"\", line 1, in \n" -"OSError: exception: access violation reading 0x00000020\n" -">>>" - -#: ../../library/ctypes.rst:195 -msgid "" -"There are, however, enough ways to crash Python with :mod:`ctypes`, so you " -"should be careful anyway. The :mod:`faulthandler` module can be helpful in " -"debugging crashes (e.g. from segmentation faults produced by erroneous C " -"library calls)." -msgstr "" - -#: ../../library/ctypes.rst:200 -msgid "" -"``None``, integers, bytes objects and (unicode) strings are the only native " -"Python objects that can directly be used as parameters in these function " -"calls. ``None`` is passed as a C ``NULL`` pointer, bytes objects and strings " -"are passed as pointer to the memory block that contains their data (:c:expr:" -"`char *` or :c:expr:`wchar_t *`). Python integers are passed as the " -"platform's default C :c:expr:`int` type, their value is masked to fit into " -"the C type." -msgstr "" - -#: ../../library/ctypes.rst:207 -msgid "" -"Before we move on calling functions with other parameter types, we have to " -"learn more about :mod:`ctypes` data types." -msgstr "" - -#: ../../library/ctypes.rst:214 ../../library/ctypes.rst:2433 -msgid "Fundamental data types" -msgstr "" - -#: ../../library/ctypes.rst:216 -msgid ":mod:`ctypes` defines a number of primitive C compatible data types:" -msgstr "" - -#: ../../library/ctypes.rst:219 ../../library/ctypes.rst:291 -msgid "ctypes type" -msgstr "ctypes 型別" - -#: ../../library/ctypes.rst:219 ../../library/ctypes.rst:291 -msgid "C type" -msgstr "C 型別" - -#: ../../library/ctypes.rst:219 ../../library/ctypes.rst:291 -msgid "Python type" -msgstr "Python 型別" - -#: ../../library/ctypes.rst:221 -msgid ":class:`c_bool`" -msgstr ":class:`c_bool`" - -#: ../../library/ctypes.rst:221 -msgid ":c:expr:`_Bool`" -msgstr ":c:expr:`_Bool`" - -#: ../../library/ctypes.rst:221 -msgid "bool (1)" -msgstr "bool (1)" - -#: ../../library/ctypes.rst:223 -msgid ":class:`c_char`" -msgstr ":class:`c_char`" - -#: ../../library/ctypes.rst:223 ../../library/ctypes.rst:227 -msgid ":c:expr:`char`" -msgstr ":c:expr:`char`" - -#: ../../library/ctypes.rst:223 -msgid "1-character bytes object" -msgstr "" - -#: ../../library/ctypes.rst:225 -msgid ":class:`c_wchar`" -msgstr ":class:`c_wchar`" - -#: ../../library/ctypes.rst:225 -msgid ":c:type:`wchar_t`" -msgstr ":c:type:`wchar_t`" - -#: ../../library/ctypes.rst:225 -msgid "1-character string" -msgstr "" - -#: ../../library/ctypes.rst:227 -msgid ":class:`c_byte`" -msgstr ":class:`c_byte`" - -#: ../../library/ctypes.rst:227 ../../library/ctypes.rst:229 -#: ../../library/ctypes.rst:231 ../../library/ctypes.rst:233 -#: ../../library/ctypes.rst:235 ../../library/ctypes.rst:237 -#: ../../library/ctypes.rst:239 ../../library/ctypes.rst:241 -#: ../../library/ctypes.rst:243 ../../library/ctypes.rst:245 -#: ../../library/ctypes.rst:247 ../../library/ctypes.rst:249 -#: ../../library/ctypes.rst:251 ../../library/ctypes.rst:253 -#: ../../library/ctypes.rst:255 ../../library/ctypes.rst:257 -#: ../../library/ctypes.rst:259 ../../library/ctypes.rst:261 -#: ../../library/ctypes.rst:264 ../../library/ctypes.rst:266 -#: ../../library/ctypes.rst:269 -msgid "int" -msgstr "int" - -#: ../../library/ctypes.rst:229 -msgid ":class:`c_ubyte`" -msgstr ":class:`c_ubyte`" - -#: ../../library/ctypes.rst:229 -msgid ":c:expr:`unsigned char`" -msgstr ":c:expr:`unsigned char`" - -#: ../../library/ctypes.rst:231 -msgid ":class:`c_short`" -msgstr ":class:`c_short`" - -#: ../../library/ctypes.rst:231 -msgid ":c:expr:`short`" -msgstr ":c:expr:`short`" - -#: ../../library/ctypes.rst:233 -msgid ":class:`c_ushort`" -msgstr ":class:`c_ushort`" - -#: ../../library/ctypes.rst:233 -msgid ":c:expr:`unsigned short`" -msgstr ":c:expr:`unsigned short`" - -#: ../../library/ctypes.rst:235 -msgid ":class:`c_int`" -msgstr ":class:`c_int`" - -#: ../../library/ctypes.rst:235 -msgid ":c:expr:`int`" -msgstr ":c:expr:`int`" - -#: ../../library/ctypes.rst:237 -msgid ":class:`c_int8`" -msgstr ":class:`c_int8`" - -#: ../../library/ctypes.rst:237 -msgid ":c:type:`int8_t`" -msgstr ":c:type:`int8_t`" - -#: ../../library/ctypes.rst:239 -msgid ":class:`c_int16`" -msgstr ":class:`c_int16`" - -#: ../../library/ctypes.rst:239 -msgid ":c:type:`int16_t`" -msgstr ":c:type:`int16_t`" - -#: ../../library/ctypes.rst:241 -msgid ":class:`c_int32`" -msgstr ":class:`c_int32`" - -#: ../../library/ctypes.rst:241 -msgid ":c:type:`int32_t`" -msgstr ":c:type:`int32_t`" - -#: ../../library/ctypes.rst:243 -msgid ":class:`c_int64`" -msgstr ":class:`c_int64`" - -#: ../../library/ctypes.rst:243 -msgid ":c:type:`int64_t`" -msgstr ":c:type:`int64_t`" - -#: ../../library/ctypes.rst:245 -msgid ":class:`c_uint`" -msgstr ":class:`c_uint`" - -#: ../../library/ctypes.rst:245 -msgid ":c:expr:`unsigned int`" -msgstr ":c:expr:`unsigned int`" - -#: ../../library/ctypes.rst:247 -msgid ":class:`c_uint8`" -msgstr ":class:`c_uint8`" - -#: ../../library/ctypes.rst:247 -msgid ":c:type:`uint8_t`" -msgstr ":c:type:`uint8_t`" - -#: ../../library/ctypes.rst:249 -msgid ":class:`c_uint16`" -msgstr ":class:`c_uint16`" - -#: ../../library/ctypes.rst:249 -msgid ":c:type:`uint16_t`" -msgstr ":c:type:`uint16_t`" - -#: ../../library/ctypes.rst:251 -msgid ":class:`c_uint32`" -msgstr ":class:`c_uint32`" - -#: ../../library/ctypes.rst:251 -msgid ":c:type:`uint32_t`" -msgstr ":c:type:`uint32_t`" - -#: ../../library/ctypes.rst:253 -msgid ":class:`c_uint64`" -msgstr ":class:`c_uint64`" - -#: ../../library/ctypes.rst:253 -msgid ":c:type:`uint64_t`" -msgstr ":c:type:`uint64_t`" - -#: ../../library/ctypes.rst:255 -msgid ":class:`c_long`" -msgstr ":class:`c_long`" - -#: ../../library/ctypes.rst:255 -msgid ":c:expr:`long`" -msgstr ":c:expr:`long`" - -#: ../../library/ctypes.rst:257 -msgid ":class:`c_ulong`" -msgstr ":class:`c_ulong`" - -#: ../../library/ctypes.rst:257 -msgid ":c:expr:`unsigned long`" -msgstr ":c:expr:`unsigned long`" - -#: ../../library/ctypes.rst:259 -msgid ":class:`c_longlong`" -msgstr ":class:`c_longlong`" - -#: ../../library/ctypes.rst:259 -msgid ":c:expr:`__int64` or :c:expr:`long long`" -msgstr ":c:expr:`__int64` 或 :c:expr:`long long`" - -#: ../../library/ctypes.rst:261 -msgid ":class:`c_ulonglong`" -msgstr ":class:`c_ulonglong`" - -#: ../../library/ctypes.rst:261 -msgid ":c:expr:`unsigned __int64` or :c:expr:`unsigned long long`" -msgstr ":c:expr:`unsigned __int64` 或 :c:expr:`unsigned long long`" - -#: ../../library/ctypes.rst:264 -msgid ":class:`c_size_t`" -msgstr ":class:`c_size_t`" - -#: ../../library/ctypes.rst:264 -msgid ":c:type:`size_t`" -msgstr ":c:type:`size_t`" - -#: ../../library/ctypes.rst:266 -msgid ":class:`c_ssize_t`" -msgstr ":class:`c_ssize_t`" - -#: ../../library/ctypes.rst:266 -msgid ":c:type:`ssize_t` or :c:expr:`Py_ssize_t`" -msgstr ":c:type:`ssize_t` 或 :c:expr:`Py_ssize_t`" - -#: ../../library/ctypes.rst:269 -msgid ":class:`c_time_t`" -msgstr ":class:`c_time_t`" - -#: ../../library/ctypes.rst:269 -msgid ":c:type:`time_t`" -msgstr ":c:type:`time_t`" - -#: ../../library/ctypes.rst:271 -msgid ":class:`c_float`" -msgstr ":class:`c_float`" - -#: ../../library/ctypes.rst:271 -msgid ":c:expr:`float`" -msgstr ":c:expr:`float`" - -#: ../../library/ctypes.rst:271 ../../library/ctypes.rst:273 -#: ../../library/ctypes.rst:275 -msgid "float" -msgstr "float" - -#: ../../library/ctypes.rst:273 -msgid ":class:`c_double`" -msgstr ":class:`c_double`" - -#: ../../library/ctypes.rst:273 -msgid ":c:expr:`double`" -msgstr ":c:expr:`double`" - -#: ../../library/ctypes.rst:275 -msgid ":class:`c_longdouble`" -msgstr ":class:`c_longdouble`" - -#: ../../library/ctypes.rst:275 -msgid ":c:expr:`long double`" -msgstr ":c:expr:`long double`" - -#: ../../library/ctypes.rst:277 -msgid ":class:`c_char_p`" -msgstr ":class:`c_char_p`" - -#: ../../library/ctypes.rst:277 -msgid ":c:expr:`char *` (NUL terminated)" -msgstr "" - -#: ../../library/ctypes.rst:277 -msgid "bytes object or ``None``" -msgstr "位元組物件或 ``None``" - -#: ../../library/ctypes.rst:279 -msgid ":class:`c_wchar_p`" -msgstr ":class:`c_wchar_p`" - -#: ../../library/ctypes.rst:279 -msgid ":c:expr:`wchar_t *` (NUL terminated)" -msgstr "" - -#: ../../library/ctypes.rst:279 -msgid "string or ``None``" -msgstr "字串或 ``None``" - -#: ../../library/ctypes.rst:281 -msgid ":class:`c_void_p`" -msgstr ":class:`c_void_p`" - -#: ../../library/ctypes.rst:281 -msgid ":c:expr:`void *`" -msgstr ":c:expr:`void *`" - -#: ../../library/ctypes.rst:281 -msgid "int or ``None``" -msgstr "" - -#: ../../library/ctypes.rst:285 -msgid "The constructor accepts any object with a truth value." -msgstr "" - -#: ../../library/ctypes.rst:287 -msgid "" -"Additionally, if IEC 60559 compatible complex arithmetic (Annex G) is " -"supported in both C and ``libffi``, the following complex types are " -"available:" -msgstr "" - -#: ../../library/ctypes.rst:293 -msgid ":class:`c_float_complex`" -msgstr ":class:`c_float_complex`" - -#: ../../library/ctypes.rst:293 -msgid ":c:expr:`float complex`" -msgstr ":c:expr:`float complex`" - -#: ../../library/ctypes.rst:293 ../../library/ctypes.rst:295 -#: ../../library/ctypes.rst:297 -msgid "complex" -msgstr "" - -#: ../../library/ctypes.rst:295 -msgid ":class:`c_double_complex`" -msgstr ":class:`c_double_complex`" - -#: ../../library/ctypes.rst:295 -msgid ":c:expr:`double complex`" -msgstr ":c:expr:`double complex`" - -#: ../../library/ctypes.rst:297 -msgid ":class:`c_longdouble_complex`" -msgstr ":class:`c_longdouble_complex`" - -#: ../../library/ctypes.rst:297 -msgid ":c:expr:`long double complex`" -msgstr ":c:expr:`long double complex`" - -#: ../../library/ctypes.rst:301 -msgid "" -"All these types can be created by calling them with an optional initializer " -"of the correct type and value::" -msgstr "" - -#: ../../library/ctypes.rst:304 -msgid "" -">>> c_int()\n" -"c_long(0)\n" -">>> c_wchar_p(\"Hello, World\")\n" -"c_wchar_p(140018365411392)\n" -">>> c_ushort(-3)\n" -"c_ushort(65533)\n" -">>>" -msgstr "" -">>> c_int()\n" -"c_long(0)\n" -">>> c_wchar_p(\"Hello, World\")\n" -"c_wchar_p(140018365411392)\n" -">>> c_ushort(-3)\n" -"c_ushort(65533)\n" -">>>" - -#: ../../library/ctypes.rst:312 -msgid "" -"Since these types are mutable, their value can also be changed afterwards::" -msgstr "" - -#: ../../library/ctypes.rst:314 -msgid "" -">>> i = c_int(42)\n" -">>> print(i)\n" -"c_long(42)\n" -">>> print(i.value)\n" -"42\n" -">>> i.value = -99\n" -">>> print(i.value)\n" -"-99\n" -">>>" -msgstr "" -">>> i = c_int(42)\n" -">>> print(i)\n" -"c_long(42)\n" -">>> print(i.value)\n" -"42\n" -">>> i.value = -99\n" -">>> print(i.value)\n" -"-99\n" -">>>" - -#: ../../library/ctypes.rst:324 -msgid "" -"Assigning a new value to instances of the pointer types :class:`c_char_p`, :" -"class:`c_wchar_p`, and :class:`c_void_p` changes the *memory location* they " -"point to, *not the contents* of the memory block (of course not, because " -"Python string objects are immutable)::" -msgstr "" - -#: ../../library/ctypes.rst:329 -msgid "" -">>> s = \"Hello, World\"\n" -">>> c_s = c_wchar_p(s)\n" -">>> print(c_s)\n" -"c_wchar_p(139966785747344)\n" -">>> print(c_s.value)\n" -"Hello World\n" -">>> c_s.value = \"Hi, there\"\n" -">>> print(c_s) # the memory location has changed\n" -"c_wchar_p(139966783348904)\n" -">>> print(c_s.value)\n" -"Hi, there\n" -">>> print(s) # first object is unchanged\n" -"Hello, World\n" -">>>" -msgstr "" -">>> s = \"Hello, World\"\n" -">>> c_s = c_wchar_p(s)\n" -">>> print(c_s)\n" -"c_wchar_p(139966785747344)\n" -">>> print(c_s.value)\n" -"Hello World\n" -">>> c_s.value = \"Hi, there\"\n" -">>> print(c_s) # 記憶體位置已改變\n" -"c_wchar_p(139966783348904)\n" -">>> print(c_s.value)\n" -"Hi, there\n" -">>> print(s) # 第一個物件未改變\n" -"Hello, World\n" -">>>" - -#: ../../library/ctypes.rst:344 -msgid "" -"You should be careful, however, not to pass them to functions expecting " -"pointers to mutable memory. If you need mutable memory blocks, ctypes has a :" -"func:`create_string_buffer` function which creates these in various ways. " -"The current memory block contents can be accessed (or changed) with the " -"``raw`` property; if you want to access it as NUL terminated string, use the " -"``value`` property::" -msgstr "" - -#: ../../library/ctypes.rst:351 -msgid "" -">>> from ctypes import *\n" -">>> p = create_string_buffer(3) # create a 3 byte buffer, " -"initialized to NUL bytes\n" -">>> print(sizeof(p), repr(p.raw))\n" -"3 b'\\x00\\x00\\x00'\n" -">>> p = create_string_buffer(b\"Hello\") # create a buffer containing a " -"NUL terminated string\n" -">>> print(sizeof(p), repr(p.raw))\n" -"6 b'Hello\\x00'\n" -">>> print(repr(p.value))\n" -"b'Hello'\n" -">>> p = create_string_buffer(b\"Hello\", 10) # create a 10 byte buffer\n" -">>> print(sizeof(p), repr(p.raw))\n" -"10 b'Hello\\x00\\x00\\x00\\x00\\x00'\n" -">>> p.value = b\"Hi\"\n" -">>> print(sizeof(p), repr(p.raw))\n" -"10 b'Hi\\x00lo\\x00\\x00\\x00\\x00\\x00'\n" -">>>" -msgstr "" - -#: ../../library/ctypes.rst:368 -msgid "" -"The :func:`create_string_buffer` function replaces the old :func:`!c_buffer` " -"function (which is still available as an alias). To create a mutable memory " -"block containing unicode characters of the C type :c:type:`wchar_t`, use " -"the :func:`create_unicode_buffer` function." -msgstr "" - -#: ../../library/ctypes.rst:377 -msgid "Calling functions, continued" -msgstr "" - -#: ../../library/ctypes.rst:379 -msgid "" -"Note that printf prints to the real standard output channel, *not* to :data:" -"`sys.stdout`, so these examples will only work at the console prompt, not " -"from within *IDLE* or *PythonWin*::" -msgstr "" - -#: ../../library/ctypes.rst:383 -msgid "" -">>> printf = libc.printf\n" -">>> printf(b\"Hello, %s\\n\", b\"World!\")\n" -"Hello, World!\n" -"14\n" -">>> printf(b\"Hello, %S\\n\", \"World!\")\n" -"Hello, World!\n" -"14\n" -">>> printf(b\"%d bottles of beer\\n\", 42)\n" -"42 bottles of beer\n" -"19\n" -">>> printf(b\"%f bottles of beer\\n\", 42.5)\n" -"Traceback (most recent call last):\n" -" File \"\", line 1, in \n" -"ctypes.ArgumentError: argument 2: TypeError: Don't know how to convert " -"parameter 2\n" -">>>" -msgstr "" -">>> printf = libc.printf\n" -">>> printf(b\"Hello, %s\\n\", b\"World!\")\n" -"Hello, World!\n" -"14\n" -">>> printf(b\"Hello, %S\\n\", \"World!\")\n" -"Hello, World!\n" -"14\n" -">>> printf(b\"%d bottles of beer\\n\", 42)\n" -"42 bottles of beer\n" -"19\n" -">>> printf(b\"%f bottles of beer\\n\", 42.5)\n" -"Traceback (most recent call last):\n" -" File \"\", line 1, in \n" -"ctypes.ArgumentError: argument 2: TypeError: Don't know how to convert " -"parameter 2\n" -">>>" - -#: ../../library/ctypes.rst:399 -msgid "" -"As has been mentioned before, all Python types except integers, strings, and " -"bytes objects have to be wrapped in their corresponding :mod:`ctypes` type, " -"so that they can be converted to the required C data type::" -msgstr "" - -#: ../../library/ctypes.rst:403 -msgid "" -">>> printf(b\"An int %d, a double %f\\n\", 1234, c_double(3.14))\n" -"An int 1234, a double 3.140000\n" -"31\n" -">>>" -msgstr "" -">>> printf(b\"An int %d, a double %f\\n\", 1234, c_double(3.14))\n" -"An int 1234, a double 3.140000\n" -"31\n" -">>>" - -#: ../../library/ctypes.rst:411 -msgid "Calling variadic functions" -msgstr "" - -#: ../../library/ctypes.rst:413 -msgid "" -"On a lot of platforms calling variadic functions through ctypes is exactly " -"the same as calling functions with a fixed number of parameters. On some " -"platforms, and in particular ARM64 for Apple Platforms, the calling " -"convention for variadic functions is different than that for regular " -"functions." -msgstr "" - -#: ../../library/ctypes.rst:418 -msgid "" -"On those platforms it is required to specify the :attr:`~_CFuncPtr.argtypes` " -"attribute for the regular, non-variadic, function arguments:" -msgstr "" - -#: ../../library/ctypes.rst:421 -msgid "libc.printf.argtypes = [ctypes.c_char_p]" -msgstr "libc.printf.argtypes = [ctypes.c_char_p]" - -#: ../../library/ctypes.rst:425 -msgid "" -"Because specifying the attribute does not inhibit portability it is advised " -"to always specify :attr:`~_CFuncPtr.argtypes` for all variadic functions." -msgstr "" - -#: ../../library/ctypes.rst:432 -msgid "Calling functions with your own custom data types" -msgstr "" - -#: ../../library/ctypes.rst:434 -msgid "" -"You can also customize :mod:`ctypes` argument conversion to allow instances " -"of your own classes be used as function arguments. :mod:`ctypes` looks for " -"an :attr:`!_as_parameter_` attribute and uses this as the function argument. " -"The attribute must be an integer, string, bytes, a :mod:`ctypes` instance, " -"or an object with an :attr:`!_as_parameter_` attribute::" -msgstr "" - -#: ../../library/ctypes.rst:440 -msgid "" -">>> class Bottles:\n" -"... def __init__(self, number):\n" -"... self._as_parameter_ = number\n" -"...\n" -">>> bottles = Bottles(42)\n" -">>> printf(b\"%d bottles of beer\\n\", bottles)\n" -"42 bottles of beer\n" -"19\n" -">>>" -msgstr "" -">>> class Bottles:\n" -"... def __init__(self, number):\n" -"... self._as_parameter_ = number\n" -"...\n" -">>> bottles = Bottles(42)\n" -">>> printf(b\"%d bottles of beer\\n\", bottles)\n" -"42 bottles of beer\n" -"19\n" -">>>" - -#: ../../library/ctypes.rst:450 -msgid "" -"If you don't want to store the instance's data in the :attr:`!" -"_as_parameter_` instance variable, you could define a :class:`property` " -"which makes the attribute available on request." -msgstr "" - -#: ../../library/ctypes.rst:458 -msgid "Specifying the required argument types (function prototypes)" -msgstr "" - -#: ../../library/ctypes.rst:460 -msgid "" -"It is possible to specify the required argument types of functions exported " -"from DLLs by setting the :attr:`~_CFuncPtr.argtypes` attribute." -msgstr "" - -#: ../../library/ctypes.rst:463 -msgid "" -":attr:`~_CFuncPtr.argtypes` must be a sequence of C data types (the :func:`!" -"printf` function is probably not a good example here, because it takes a " -"variable number and different types of parameters depending on the format " -"string, on the other hand this is quite handy to experiment with this " -"feature)::" -msgstr "" - -#: ../../library/ctypes.rst:468 -msgid "" -">>> printf.argtypes = [c_char_p, c_char_p, c_int, c_double]\n" -">>> printf(b\"String '%s', Int %d, Double %f\\n\", b\"Hi\", 10, 2.2)\n" -"String 'Hi', Int 10, Double 2.200000\n" -"37\n" -">>>" -msgstr "" -">>> printf.argtypes = [c_char_p, c_char_p, c_int, c_double]\n" -">>> printf(b\"String '%s', Int %d, Double %f\\n\", b\"Hi\", 10, 2.2)\n" -"String 'Hi', Int 10, Double 2.200000\n" -"37\n" -">>>" - -#: ../../library/ctypes.rst:474 -msgid "" -"Specifying a format protects against incompatible argument types (just as a " -"prototype for a C function), and tries to convert the arguments to valid " -"types::" -msgstr "" - -#: ../../library/ctypes.rst:477 -msgid "" -">>> printf(b\"%d %d %d\", 1, 2, 3)\n" -"Traceback (most recent call last):\n" -" File \"\", line 1, in \n" -"ctypes.ArgumentError: argument 2: TypeError: 'int' object cannot be " -"interpreted as ctypes.c_char_p\n" -">>> printf(b\"%s %d %f\\n\", b\"X\", 2, 3)\n" -"X 2 3.000000\n" -"13\n" -">>>" -msgstr "" -">>> printf(b\"%d %d %d\", 1, 2, 3)\n" -"Traceback (most recent call last):\n" -" File \"\", line 1, in \n" -"ctypes.ArgumentError: argument 2: TypeError: 'int' object cannot be " -"interpreted as ctypes.c_char_p\n" -">>> printf(b\"%s %d %f\\n\", b\"X\", 2, 3)\n" -"X 2 3.000000\n" -"13\n" -">>>" - -#: ../../library/ctypes.rst:486 -msgid "" -"If you have defined your own classes which you pass to function calls, you " -"have to implement a :meth:`~_CData.from_param` class method for them to be " -"able to use them in the :attr:`~_CFuncPtr.argtypes` sequence. The :meth:" -"`~_CData.from_param` class method receives the Python object passed to the " -"function call, it should do a typecheck or whatever is needed to make sure " -"this object is acceptable, and then return the object itself, its :attr:`!" -"_as_parameter_` attribute, or whatever you want to pass as the C function " -"argument in this case. Again, the result should be an integer, string, " -"bytes, a :mod:`ctypes` instance, or an object with an :attr:`!" -"_as_parameter_` attribute." -msgstr "" - -#: ../../library/ctypes.rst:500 -msgid "Return types" -msgstr "" - -#: ../../library/ctypes.rst:510 -msgid "" -"By default functions are assumed to return the C :c:expr:`int` type. Other " -"return types can be specified by setting the :attr:`~_CFuncPtr.restype` " -"attribute of the function object." -msgstr "" - -#: ../../library/ctypes.rst:514 -msgid "" -"The C prototype of :c:func:`time` is ``time_t time(time_t *)``. Because :c:" -"type:`time_t` might be of a different type than the default return type :c:" -"expr:`int`, you should specify the :attr:`!restype` attribute::" -msgstr "" - -#: ../../library/ctypes.rst:518 -msgid ">>> libc.time.restype = c_time_t" -msgstr ">>> libc.time.restype = c_time_t" - -#: ../../library/ctypes.rst:520 -msgid "The argument types can be specified using :attr:`~_CFuncPtr.argtypes`::" -msgstr "" - -#: ../../library/ctypes.rst:522 -msgid ">>> libc.time.argtypes = (POINTER(c_time_t),)" -msgstr ">>> libc.time.argtypes = (POINTER(c_time_t),)" - -#: ../../library/ctypes.rst:524 -msgid "" -"To call the function with a ``NULL`` pointer as first argument, use " -"``None``::" -msgstr "" - -#: ../../library/ctypes.rst:526 -msgid "" -">>> print(libc.time(None))\n" -"1150640792" -msgstr "" -">>> print(libc.time(None))\n" -"1150640792" - -#: ../../library/ctypes.rst:529 -msgid "" -"Here is a more advanced example, it uses the :func:`!strchr` function, which " -"expects a string pointer and a char, and returns a pointer to a string::" -msgstr "" - -#: ../../library/ctypes.rst:532 -msgid "" -">>> strchr = libc.strchr\n" -">>> strchr(b\"abcdef\", ord(\"d\"))\n" -"8059983\n" -">>> strchr.restype = c_char_p # c_char_p is a pointer to a string\n" -">>> strchr(b\"abcdef\", ord(\"d\"))\n" -"b'def'\n" -">>> print(strchr(b\"abcdef\", ord(\"x\")))\n" -"None\n" -">>>" -msgstr "" -">>> strchr = libc.strchr\n" -">>> strchr(b\"abcdef\", ord(\"d\"))\n" -"8059983\n" -">>> strchr.restype = c_char_p # c_char_p 一個字串的指標\n" -">>> strchr(b\"abcdef\", ord(\"d\"))\n" -"b'def'\n" -">>> print(strchr(b\"abcdef\", ord(\"x\")))\n" -"None\n" -">>>" - -#: ../../library/ctypes.rst:542 -msgid "" -"If you want to avoid the :func:`ord(\"x\") ` calls above, you can set " -"the :attr:`~_CFuncPtr.argtypes` attribute, and the second argument will be " -"converted from a single character Python bytes object into a C char:" -msgstr "" - -#: ../../library/ctypes.rst:546 -msgid "" -">>> strchr.restype = c_char_p\n" -">>> strchr.argtypes = [c_char_p, c_char]\n" -">>> strchr(b\"abcdef\", b\"d\")\n" -"b'def'\n" -">>> strchr(b\"abcdef\", b\"def\")\n" -"Traceback (most recent call last):\n" -"ctypes.ArgumentError: argument 2: TypeError: one character bytes, bytearray " -"or integer expected\n" -">>> print(strchr(b\"abcdef\", b\"x\"))\n" -"None\n" -">>> strchr(b\"abcdef\", b\"d\")\n" -"b'def'\n" -">>>" -msgstr "" -">>> strchr.restype = c_char_p\n" -">>> strchr.argtypes = [c_char_p, c_char]\n" -">>> strchr(b\"abcdef\", b\"d\")\n" -"b'def'\n" -">>> strchr(b\"abcdef\", b\"def\")\n" -"Traceback (most recent call last):\n" -"ctypes.ArgumentError: argument 2: TypeError: one character bytes, bytearray " -"or integer expected\n" -">>> print(strchr(b\"abcdef\", b\"x\"))\n" -"None\n" -">>> strchr(b\"abcdef\", b\"d\")\n" -"b'def'\n" -">>>" - -#: ../../library/ctypes.rst:561 -msgid "" -"You can also use a callable Python object (a function or a class for " -"example) as the :attr:`~_CFuncPtr.restype` attribute, if the foreign " -"function returns an integer. The callable will be called with the *integer* " -"the C function returns, and the result of this call will be used as the " -"result of your function call. This is useful to check for error return " -"values and automatically raise an exception::" -msgstr "" - -#: ../../library/ctypes.rst:567 -msgid "" -">>> GetModuleHandle = windll.kernel32.GetModuleHandleA\n" -">>> def ValidHandle(value):\n" -"... if value == 0:\n" -"... raise WinError()\n" -"... return value\n" -"...\n" -">>>\n" -">>> GetModuleHandle.restype = ValidHandle\n" -">>> GetModuleHandle(None)\n" -"486539264\n" -">>> GetModuleHandle(\"something silly\")\n" -"Traceback (most recent call last):\n" -" File \"\", line 1, in \n" -" File \"\", line 3, in ValidHandle\n" -"OSError: [Errno 126] The specified module could not be found.\n" -">>>" -msgstr "" -">>> GetModuleHandle = windll.kernel32.GetModuleHandleA\n" -">>> def ValidHandle(value):\n" -"... if value == 0:\n" -"... raise WinError()\n" -"... return value\n" -"...\n" -">>>\n" -">>> GetModuleHandle.restype = ValidHandle\n" -">>> GetModuleHandle(None)\n" -"486539264\n" -">>> GetModuleHandle(\"something silly\")\n" -"Traceback (most recent call last):\n" -" File \"\", line 1, in \n" -" File \"\", line 3, in ValidHandle\n" -"OSError: [Errno 126] The specified module could not be found.\n" -">>>" - -#: ../../library/ctypes.rst:584 -msgid "" -"``WinError`` is a function which will call Windows ``FormatMessage()`` api " -"to get the string representation of an error code, and *returns* an " -"exception. ``WinError`` takes an optional error code parameter, if no one is " -"used, it calls :func:`GetLastError` to retrieve it." -msgstr "" - -#: ../../library/ctypes.rst:589 -msgid "" -"Please note that a much more powerful error checking mechanism is available " -"through the :attr:`~_CFuncPtr.errcheck` attribute; see the reference manual " -"for details." -msgstr "" - -#: ../../library/ctypes.rst:597 -msgid "Passing pointers (or: passing parameters by reference)" -msgstr "" - -#: ../../library/ctypes.rst:599 -msgid "" -"Sometimes a C api function expects a *pointer* to a data type as parameter, " -"probably to write into the corresponding location, or if the data is too " -"large to be passed by value. This is also known as *passing parameters by " -"reference*." -msgstr "" - -#: ../../library/ctypes.rst:603 -msgid "" -":mod:`ctypes` exports the :func:`byref` function which is used to pass " -"parameters by reference. The same effect can be achieved with the :func:" -"`pointer` function, although :func:`pointer` does a lot more work since it " -"constructs a real pointer object, so it is faster to use :func:`byref` if " -"you don't need the pointer object in Python itself::" -msgstr "" - -#: ../../library/ctypes.rst:609 -msgid "" -">>> i = c_int()\n" -">>> f = c_float()\n" -">>> s = create_string_buffer(b'\\000' * 32)\n" -">>> print(i.value, f.value, repr(s.value))\n" -"0 0.0 b''\n" -">>> libc.sscanf(b\"1 3.14 Hello\", b\"%d %f %s\",\n" -"... byref(i), byref(f), s)\n" -"3\n" -">>> print(i.value, f.value, repr(s.value))\n" -"1 3.1400001049 b'Hello'\n" -">>>" -msgstr "" -">>> i = c_int()\n" -">>> f = c_float()\n" -">>> s = create_string_buffer(b'\\000' * 32)\n" -">>> print(i.value, f.value, repr(s.value))\n" -"0 0.0 b''\n" -">>> libc.sscanf(b\"1 3.14 Hello\", b\"%d %f %s\",\n" -"... byref(i), byref(f), s)\n" -"3\n" -">>> print(i.value, f.value, repr(s.value))\n" -"1 3.1400001049 b'Hello'\n" -">>>" - -#: ../../library/ctypes.rst:625 -msgid "Structures and unions" -msgstr "" - -#: ../../library/ctypes.rst:627 -msgid "" -"Structures and unions must derive from the :class:`Structure` and :class:" -"`Union` base classes which are defined in the :mod:`ctypes` module. Each " -"subclass must define a :attr:`~Structure._fields_` attribute. :attr:`!" -"_fields_` must be a list of *2-tuples*, containing a *field name* and a " -"*field type*." -msgstr "" - -#: ../../library/ctypes.rst:632 -msgid "" -"The field type must be a :mod:`ctypes` type like :class:`c_int`, or any " -"other derived :mod:`ctypes` type: structure, union, array, pointer." -msgstr "" - -#: ../../library/ctypes.rst:635 -msgid "" -"Here is a simple example of a POINT structure, which contains two integers " -"named *x* and *y*, and also shows how to initialize a structure in the " -"constructor::" -msgstr "" - -#: ../../library/ctypes.rst:638 -msgid "" -">>> from ctypes import *\n" -">>> class POINT(Structure):\n" -"... _fields_ = [(\"x\", c_int),\n" -"... (\"y\", c_int)]\n" -"...\n" -">>> point = POINT(10, 20)\n" -">>> print(point.x, point.y)\n" -"10 20\n" -">>> point = POINT(y=5)\n" -">>> print(point.x, point.y)\n" -"0 5\n" -">>> POINT(1, 2, 3)\n" -"Traceback (most recent call last):\n" -" File \"\", line 1, in \n" -"TypeError: too many initializers\n" -">>>" -msgstr "" -">>> from ctypes import *\n" -">>> class POINT(Structure):\n" -"... _fields_ = [(\"x\", c_int),\n" -"... (\"y\", c_int)]\n" -"...\n" -">>> point = POINT(10, 20)\n" -">>> print(point.x, point.y)\n" -"10 20\n" -">>> point = POINT(y=5)\n" -">>> print(point.x, point.y)\n" -"0 5\n" -">>> POINT(1, 2, 3)\n" -"Traceback (most recent call last):\n" -" File \"\", line 1, in \n" -"TypeError: too many initializers\n" -">>>" - -#: ../../library/ctypes.rst:655 -msgid "" -"You can, however, build much more complicated structures. A structure can " -"itself contain other structures by using a structure as a field type." -msgstr "" - -#: ../../library/ctypes.rst:658 -msgid "" -"Here is a RECT structure which contains two POINTs named *upperleft* and " -"*lowerright*::" -msgstr "" - -#: ../../library/ctypes.rst:661 -msgid "" -">>> class RECT(Structure):\n" -"... _fields_ = [(\"upperleft\", POINT),\n" -"... (\"lowerright\", POINT)]\n" -"...\n" -">>> rc = RECT(point)\n" -">>> print(rc.upperleft.x, rc.upperleft.y)\n" -"0 5\n" -">>> print(rc.lowerright.x, rc.lowerright.y)\n" -"0 0\n" -">>>" -msgstr "" -">>> class RECT(Structure):\n" -"... _fields_ = [(\"upperleft\", POINT),\n" -"... (\"lowerright\", POINT)]\n" -"...\n" -">>> rc = RECT(point)\n" -">>> print(rc.upperleft.x, rc.upperleft.y)\n" -"0 5\n" -">>> print(rc.lowerright.x, rc.lowerright.y)\n" -"0 0\n" -">>>" - -#: ../../library/ctypes.rst:672 -msgid "" -"Nested structures can also be initialized in the constructor in several " -"ways::" -msgstr "" - -#: ../../library/ctypes.rst:674 -msgid "" -">>> r = RECT(POINT(1, 2), POINT(3, 4))\n" -">>> r = RECT((1, 2), (3, 4))" -msgstr "" -">>> r = RECT(POINT(1, 2), POINT(3, 4))\n" -">>> r = RECT((1, 2), (3, 4))" - -#: ../../library/ctypes.rst:677 -msgid "" -"Field :term:`descriptor`\\s can be retrieved from the *class*, they are " -"useful for debugging because they can provide useful information. See :class:" -"`CField`::" -msgstr "" - -#: ../../library/ctypes.rst:681 -msgid "" -">>> POINT.x\n" -"\n" -">>> POINT.y\n" -"\n" -">>>" -msgstr "" -">>> POINT.x\n" -"\n" -">>> POINT.y\n" -"\n" -">>>" - -#: ../../library/ctypes.rst:692 -msgid "" -":mod:`ctypes` does not support passing unions or structures with bit-fields " -"to functions by value. While this may work on 32-bit x86, it's not " -"guaranteed by the library to work in the general case. Unions and " -"structures with bit-fields should always be passed to functions by pointer." -msgstr "" - -#: ../../library/ctypes.rst:698 -msgid "Structure/union layout, alignment and byte order" -msgstr "" - -#: ../../library/ctypes.rst:700 -msgid "" -"By default, Structure and Union fields are laid out in the same way the C " -"compiler does it. It is possible to override this behavior entirely by " -"specifying a :attr:`~Structure._layout_` class attribute in the subclass " -"definition; see the attribute documentation for details." -msgstr "" - -#: ../../library/ctypes.rst:705 -msgid "" -"It is possible to specify the maximum alignment for the fields and/or for " -"the structure itself by setting the class attributes :attr:`~Structure." -"_pack_` and/or :attr:`~Structure._align_`, respectively. See the attribute " -"documentation for details." -msgstr "" - -#: ../../library/ctypes.rst:710 -msgid "" -":mod:`ctypes` uses the native byte order for Structures and Unions. To " -"build structures with non-native byte order, you can use one of the :class:" -"`BigEndianStructure`, :class:`LittleEndianStructure`, :class:" -"`BigEndianUnion`, and :class:`LittleEndianUnion` base classes. These " -"classes cannot contain pointer fields." -msgstr "" - -#: ../../library/ctypes.rst:720 -msgid "Bit fields in structures and unions" -msgstr "" - -#: ../../library/ctypes.rst:722 -msgid "" -"It is possible to create structures and unions containing bit fields. Bit " -"fields are only possible for integer fields, the bit width is specified as " -"the third item in the :attr:`~Structure._fields_` tuples::" -msgstr "" - -#: ../../library/ctypes.rst:726 -msgid "" -">>> class Int(Structure):\n" -"... _fields_ = [(\"first_16\", c_int, 16),\n" -"... (\"second_16\", c_int, 16)]\n" -"...\n" -">>> print(Int.first_16)\n" -"\n" -">>> print(Int.second_16)\n" -"" -msgstr "" -">>> class Int(Structure):\n" -"... _fields_ = [(\"first_16\", c_int, 16),\n" -"... (\"second_16\", c_int, 16)]\n" -"...\n" -">>> print(Int.first_16)\n" -"\n" -">>> print(Int.second_16)\n" -"" - -#: ../../library/ctypes.rst:735 -msgid "" -"It is important to note that bit field allocation and layout in memory are " -"not defined as a C standard; their implementation is compiler-specific. By " -"default, Python will attempt to match the behavior of a \"native\" compiler " -"for the current platform. See the :attr:`~Structure._layout_` attribute for " -"details on the default behavior and how to change it." -msgstr "" - -#: ../../library/ctypes.rst:746 -msgid "Arrays" -msgstr "" - -#: ../../library/ctypes.rst:748 -msgid "" -"Arrays are sequences, containing a fixed number of instances of the same " -"type." -msgstr "" - -#: ../../library/ctypes.rst:750 -msgid "" -"The recommended way to create array types is by multiplying a data type with " -"a positive integer::" -msgstr "" - -#: ../../library/ctypes.rst:753 -msgid "TenPointsArrayType = POINT * 10" -msgstr "" - -#: ../../library/ctypes.rst:755 -msgid "" -"Here is an example of a somewhat artificial data type, a structure " -"containing 4 POINTs among other stuff::" -msgstr "" - -#: ../../library/ctypes.rst:758 -msgid "" -">>> from ctypes import *\n" -">>> class POINT(Structure):\n" -"... _fields_ = (\"x\", c_int), (\"y\", c_int)\n" -"...\n" -">>> class MyStruct(Structure):\n" -"... _fields_ = [(\"a\", c_int),\n" -"... (\"b\", c_float),\n" -"... (\"point_array\", POINT * 4)]\n" -">>>\n" -">>> print(len(MyStruct().point_array))\n" -"4\n" -">>>" -msgstr "" -">>> from ctypes import *\n" -">>> class POINT(Structure):\n" -"... _fields_ = (\"x\", c_int), (\"y\", c_int)\n" -"...\n" -">>> class MyStruct(Structure):\n" -"... _fields_ = [(\"a\", c_int),\n" -"... (\"b\", c_float),\n" -"... (\"point_array\", POINT * 4)]\n" -">>>\n" -">>> print(len(MyStruct().point_array))\n" -"4\n" -">>>" - -#: ../../library/ctypes.rst:771 -msgid "Instances are created in the usual way, by calling the class::" -msgstr "" - -#: ../../library/ctypes.rst:773 -msgid "" -"arr = TenPointsArrayType()\n" -"for pt in arr:\n" -" print(pt.x, pt.y)" -msgstr "" -"arr = TenPointsArrayType()\n" -"for pt in arr:\n" -" print(pt.x, pt.y)" - -#: ../../library/ctypes.rst:777 -msgid "" -"The above code print a series of ``0 0`` lines, because the array contents " -"is initialized to zeros." -msgstr "" - -#: ../../library/ctypes.rst:780 -msgid "Initializers of the correct type can also be specified::" -msgstr "" - -#: ../../library/ctypes.rst:782 -msgid "" -">>> from ctypes import *\n" -">>> TenIntegers = c_int * 10\n" -">>> ii = TenIntegers(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)\n" -">>> print(ii)\n" -"\n" -">>> for i in ii: print(i, end=\" \")\n" -"...\n" -"1 2 3 4 5 6 7 8 9 10\n" -">>>" -msgstr "" -">>> from ctypes import *\n" -">>> TenIntegers = c_int * 10\n" -">>> ii = TenIntegers(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)\n" -">>> print(ii)\n" -"\n" -">>> for i in ii: print(i, end=\" \")\n" -"...\n" -"1 2 3 4 5 6 7 8 9 10\n" -">>>" - -#: ../../library/ctypes.rst:796 -msgid "Pointers" -msgstr "指標" - -#: ../../library/ctypes.rst:798 -msgid "" -"Pointer instances are created by calling the :func:`pointer` function on a :" -"mod:`ctypes` type::" -msgstr "" - -#: ../../library/ctypes.rst:801 -msgid "" -">>> from ctypes import *\n" -">>> i = c_int(42)\n" -">>> pi = pointer(i)\n" -">>>" -msgstr "" -">>> from ctypes import *\n" -">>> i = c_int(42)\n" -">>> pi = pointer(i)\n" -">>>" - -#: ../../library/ctypes.rst:806 -msgid "" -"Pointer instances have a :attr:`~_Pointer.contents` attribute which returns " -"the object to which the pointer points, the ``i`` object above::" -msgstr "" - -#: ../../library/ctypes.rst:809 -msgid "" -">>> pi.contents\n" -"c_long(42)\n" -">>>" -msgstr "" -">>> pi.contents\n" -"c_long(42)\n" -">>>" - -#: ../../library/ctypes.rst:813 -msgid "" -"Note that :mod:`ctypes` does not have OOR (original object return), it " -"constructs a new, equivalent object each time you retrieve an attribute::" -msgstr "" - -#: ../../library/ctypes.rst:816 -msgid "" -">>> pi.contents is i\n" -"False\n" -">>> pi.contents is pi.contents\n" -"False\n" -">>>" -msgstr "" -">>> pi.contents is i\n" -"False\n" -">>> pi.contents is pi.contents\n" -"False\n" -">>>" - -#: ../../library/ctypes.rst:822 -msgid "" -"Assigning another :class:`c_int` instance to the pointer's contents " -"attribute would cause the pointer to point to the memory location where this " -"is stored::" -msgstr "" - -#: ../../library/ctypes.rst:825 -msgid "" -">>> i = c_int(99)\n" -">>> pi.contents = i\n" -">>> pi.contents\n" -"c_long(99)\n" -">>>" -msgstr "" -">>> i = c_int(99)\n" -">>> pi.contents = i\n" -">>> pi.contents\n" -"c_long(99)\n" -">>>" - -#: ../../library/ctypes.rst:834 -msgid "Pointer instances can also be indexed with integers::" -msgstr "" - -#: ../../library/ctypes.rst:836 -msgid "" -">>> pi[0]\n" -"99\n" -">>>" -msgstr "" -">>> pi[0]\n" -"99\n" -">>>" - -#: ../../library/ctypes.rst:840 -msgid "Assigning to an integer index changes the pointed to value::" -msgstr "" - -#: ../../library/ctypes.rst:842 -msgid "" -">>> print(i)\n" -"c_long(99)\n" -">>> pi[0] = 22\n" -">>> print(i)\n" -"c_long(22)\n" -">>>" -msgstr "" -">>> print(i)\n" -"c_long(99)\n" -">>> pi[0] = 22\n" -">>> print(i)\n" -"c_long(22)\n" -">>>" - -#: ../../library/ctypes.rst:849 -msgid "" -"It is also possible to use indexes different from 0, but you must know what " -"you're doing, just as in C: You can access or change arbitrary memory " -"locations. Generally you only use this feature if you receive a pointer from " -"a C function, and you *know* that the pointer actually points to an array " -"instead of a single item." -msgstr "" - -#: ../../library/ctypes.rst:855 -msgid "" -"Behind the scenes, the :func:`pointer` function does more than simply create " -"pointer instances, it has to create pointer *types* first. This is done with " -"the :func:`POINTER` function, which accepts any :mod:`ctypes` type, and " -"returns a new type::" -msgstr "" - -#: ../../library/ctypes.rst:860 -msgid "" -">>> PI = POINTER(c_int)\n" -">>> PI\n" -"\n" -">>> PI(42)\n" -"Traceback (most recent call last):\n" -" File \"\", line 1, in \n" -"TypeError: expected c_long instead of int\n" -">>> PI(c_int(42))\n" -"\n" -">>>" -msgstr "" -">>> PI = POINTER(c_int)\n" -">>> PI\n" -"\n" -">>> PI(42)\n" -"Traceback (most recent call last):\n" -" File \"\", line 1, in \n" -"TypeError: expected c_long instead of int\n" -">>> PI(c_int(42))\n" -"\n" -">>>" - -#: ../../library/ctypes.rst:871 -msgid "" -"Calling the pointer type without an argument creates a ``NULL`` pointer. " -"``NULL`` pointers have a ``False`` boolean value::" -msgstr "" - -#: ../../library/ctypes.rst:874 -msgid "" -">>> null_ptr = POINTER(c_int)()\n" -">>> print(bool(null_ptr))\n" -"False\n" -">>>" -msgstr "" -">>> null_ptr = POINTER(c_int)()\n" -">>> print(bool(null_ptr))\n" -"False\n" -">>>" - -#: ../../library/ctypes.rst:879 -msgid "" -":mod:`ctypes` checks for ``NULL`` when dereferencing pointers (but " -"dereferencing invalid non-\\ ``NULL`` pointers would crash Python)::" -msgstr "" - -#: ../../library/ctypes.rst:882 -msgid "" -">>> null_ptr[0]\n" -"Traceback (most recent call last):\n" -" ....\n" -"ValueError: NULL pointer access\n" -">>>\n" -"\n" -">>> null_ptr[0] = 1234\n" -"Traceback (most recent call last):\n" -" ....\n" -"ValueError: NULL pointer access\n" -">>>" -msgstr "" -">>> null_ptr[0]\n" -"Traceback (most recent call last):\n" -" ....\n" -"ValueError: NULL pointer access\n" -">>>\n" -"\n" -">>> null_ptr[0] = 1234\n" -"Traceback (most recent call last):\n" -" ....\n" -"ValueError: NULL pointer access\n" -">>>" - -#: ../../library/ctypes.rst:897 -msgid "Thread safety without the GIL" -msgstr "" - -#: ../../library/ctypes.rst:899 -msgid "" -"From Python 3.13 onward, the :term:`GIL` can be disabled on :term:`free " -"threaded ` builds. In ctypes, reads and writes to a single " -"object concurrently is safe, but not across multiple objects:" -msgstr "" - -#: ../../library/ctypes.rst:902 -msgid "" -">>> number = c_int(42)\n" -">>> pointer_a = pointer(number)\n" -">>> pointer_b = pointer(number)" -msgstr "" -">>> number = c_int(42)\n" -">>> pointer_a = pointer(number)\n" -">>> pointer_b = pointer(number)" - -#: ../../library/ctypes.rst:908 -msgid "" -"In the above, it's only safe for one object to read and write to the address " -"at once if the GIL is disabled. So, ``pointer_a`` can be shared and written " -"to across multiple threads, but only if ``pointer_b`` is not also attempting " -"to do the same. If this is an issue, consider using a :class:`threading." -"Lock` to synchronize access to memory:" -msgstr "" - -#: ../../library/ctypes.rst:913 -msgid "" -">>> import threading\n" -">>> lock = threading.Lock()\n" -">>> # Thread 1\n" -">>> with lock:\n" -"... pointer_a.contents = 24\n" -">>> # Thread 2\n" -">>> with lock:\n" -"... pointer_b.contents = 42" -msgstr "" -">>> import threading\n" -">>> lock = threading.Lock()\n" -">>> # 執行緒 1\n" -">>> with lock:\n" -"... pointer_a.contents = 24\n" -">>> # 執行緒 2\n" -">>> with lock:\n" -"... pointer_b.contents = 42" - -#: ../../library/ctypes.rst:928 -msgid "Type conversions" -msgstr "" - -#: ../../library/ctypes.rst:930 -msgid "" -"Usually, ctypes does strict type checking. This means, if you have " -"``POINTER(c_int)`` in the :attr:`~_CFuncPtr.argtypes` list of a function or " -"as the type of a member field in a structure definition, only instances of " -"exactly the same type are accepted. There are some exceptions to this rule, " -"where ctypes accepts other objects. For example, you can pass compatible " -"array instances instead of pointer types. So, for ``POINTER(c_int)``, " -"ctypes accepts an array of c_int::" -msgstr "" - -#: ../../library/ctypes.rst:937 -msgid "" -">>> class Bar(Structure):\n" -"... _fields_ = [(\"count\", c_int), (\"values\", POINTER(c_int))]\n" -"...\n" -">>> bar = Bar()\n" -">>> bar.values = (c_int * 3)(1, 2, 3)\n" -">>> bar.count = 3\n" -">>> for i in range(bar.count):\n" -"... print(bar.values[i])\n" -"...\n" -"1\n" -"2\n" -"3\n" -">>>" -msgstr "" -">>> class Bar(Structure):\n" -"... _fields_ = [(\"count\", c_int), (\"values\", POINTER(c_int))]\n" -"...\n" -">>> bar = Bar()\n" -">>> bar.values = (c_int * 3)(1, 2, 3)\n" -">>> bar.count = 3\n" -">>> for i in range(bar.count):\n" -"... print(bar.values[i])\n" -"...\n" -"1\n" -"2\n" -"3\n" -">>>" - -#: ../../library/ctypes.rst:951 -msgid "" -"In addition, if a function argument is explicitly declared to be a pointer " -"type (such as ``POINTER(c_int)``) in :attr:`~_CFuncPtr.argtypes`, an object " -"of the pointed type (``c_int`` in this case) can be passed to the function. " -"ctypes will apply the required :func:`byref` conversion in this case " -"automatically." -msgstr "" - -#: ../../library/ctypes.rst:956 -msgid "To set a POINTER type field to ``NULL``, you can assign ``None``::" -msgstr "" - -#: ../../library/ctypes.rst:958 -msgid "" -">>> bar.values = None\n" -">>>" -msgstr "" -">>> bar.values = None\n" -">>>" - -#: ../../library/ctypes.rst:963 -msgid "" -"Sometimes you have instances of incompatible types. In C, you can cast one " -"type into another type. :mod:`ctypes` provides a :func:`cast` function " -"which can be used in the same way. The ``Bar`` structure defined above " -"accepts ``POINTER(c_int)`` pointers or :class:`c_int` arrays for its " -"``values`` field, but not instances of other types::" -msgstr "" - -#: ../../library/ctypes.rst:969 -msgid "" -">>> bar.values = (c_byte * 4)()\n" -"Traceback (most recent call last):\n" -" File \"\", line 1, in \n" -"TypeError: incompatible types, c_byte_Array_4 instance instead of LP_c_long " -"instance\n" -">>>" -msgstr "" -">>> bar.values = (c_byte * 4)()\n" -"Traceback (most recent call last):\n" -" File \"\", line 1, in \n" -"TypeError: incompatible types, c_byte_Array_4 instance instead of LP_c_long " -"instance\n" -">>>" - -#: ../../library/ctypes.rst:975 -msgid "For these cases, the :func:`cast` function is handy." -msgstr "" - -#: ../../library/ctypes.rst:977 -msgid "" -"The :func:`cast` function can be used to cast a ctypes instance into a " -"pointer to a different ctypes data type. :func:`cast` takes two parameters, " -"a ctypes object that is or can be converted to a pointer of some kind, and a " -"ctypes pointer type. It returns an instance of the second argument, which " -"references the same memory block as the first argument::" -msgstr "" - -#: ../../library/ctypes.rst:983 -msgid "" -">>> a = (c_byte * 4)()\n" -">>> cast(a, POINTER(c_int))\n" -"\n" -">>>" -msgstr "" -">>> a = (c_byte * 4)()\n" -">>> cast(a, POINTER(c_int))\n" -"\n" -">>>" - -#: ../../library/ctypes.rst:988 -msgid "" -"So, :func:`cast` can be used to assign to the ``values`` field of ``Bar`` " -"the structure::" -msgstr "" - -#: ../../library/ctypes.rst:991 -msgid "" -">>> bar = Bar()\n" -">>> bar.values = cast((c_byte * 4)(), POINTER(c_int))\n" -">>> print(bar.values[0])\n" -"0\n" -">>>" -msgstr "" -">>> bar = Bar()\n" -">>> bar.values = cast((c_byte * 4)(), POINTER(c_int))\n" -">>> print(bar.values[0])\n" -"0\n" -">>>" - -#: ../../library/ctypes.rst:1001 -msgid "Incomplete Types" -msgstr "" - -#: ../../library/ctypes.rst:1003 -msgid "" -"*Incomplete Types* are structures, unions or arrays whose members are not " -"yet specified. In C, they are specified by forward declarations, which are " -"defined later::" -msgstr "" - -#: ../../library/ctypes.rst:1007 -msgid "" -"struct cell; /* forward declaration */\n" -"\n" -"struct cell {\n" -" char *name;\n" -" struct cell *next;\n" -"};" -msgstr "" - -#: ../../library/ctypes.rst:1014 -msgid "" -"The straightforward translation into ctypes code would be this, but it does " -"not work::" -msgstr "" - -#: ../../library/ctypes.rst:1017 -msgid "" -">>> class cell(Structure):\n" -"... _fields_ = [(\"name\", c_char_p),\n" -"... (\"next\", POINTER(cell))]\n" -"...\n" -"Traceback (most recent call last):\n" -" File \"\", line 1, in \n" -" File \"\", line 2, in cell\n" -"NameError: name 'cell' is not defined\n" -">>>" -msgstr "" -">>> class cell(Structure):\n" -"... _fields_ = [(\"name\", c_char_p),\n" -"... (\"next\", POINTER(cell))]\n" -"...\n" -"Traceback (most recent call last):\n" -" File \"\", line 1, in \n" -" File \"\", line 2, in cell\n" -"NameError: name 'cell' is not defined\n" -">>>" - -#: ../../library/ctypes.rst:1027 -msgid "" -"because the new ``class cell`` is not available in the class statement " -"itself. In :mod:`ctypes`, we can define the ``cell`` class and set the :attr:" -"`~Structure._fields_` attribute later, after the class statement::" -msgstr "" - -#: ../../library/ctypes.rst:1031 -msgid "" -">>> from ctypes import *\n" -">>> class cell(Structure):\n" -"... pass\n" -"...\n" -">>> cell._fields_ = [(\"name\", c_char_p),\n" -"... (\"next\", POINTER(cell))]\n" -">>>" -msgstr "" -">>> from ctypes import *\n" -">>> class cell(Structure):\n" -"... pass\n" -"...\n" -">>> cell._fields_ = [(\"name\", c_char_p),\n" -"... (\"next\", POINTER(cell))]\n" -">>>" - -#: ../../library/ctypes.rst:1039 -msgid "" -"Let's try it. We create two instances of ``cell``, and let them point to " -"each other, and finally follow the pointer chain a few times::" -msgstr "" - -#: ../../library/ctypes.rst:1042 -msgid "" -">>> c1 = cell()\n" -">>> c1.name = b\"foo\"\n" -">>> c2 = cell()\n" -">>> c2.name = b\"bar\"\n" -">>> c1.next = pointer(c2)\n" -">>> c2.next = pointer(c1)\n" -">>> p = c1\n" -">>> for i in range(8):\n" -"... print(p.name, end=\" \")\n" -"... p = p.next[0]\n" -"...\n" -"foo bar foo bar foo bar foo bar\n" -">>>" -msgstr "" -">>> c1 = cell()\n" -">>> c1.name = b\"foo\"\n" -">>> c2 = cell()\n" -">>> c2.name = b\"bar\"\n" -">>> c1.next = pointer(c2)\n" -">>> c2.next = pointer(c1)\n" -">>> p = c1\n" -">>> for i in range(8):\n" -"... print(p.name, end=\" \")\n" -"... p = p.next[0]\n" -"...\n" -"foo bar foo bar foo bar foo bar\n" -">>>" - -#: ../../library/ctypes.rst:1060 -msgid "Callback functions" -msgstr "回呼函式" - -#: ../../library/ctypes.rst:1062 -msgid "" -":mod:`ctypes` allows creating C callable function pointers from Python " -"callables. These are sometimes called *callback functions*." -msgstr "" - -#: ../../library/ctypes.rst:1065 -msgid "" -"First, you must create a class for the callback function. The class knows " -"the calling convention, the return type, and the number and types of " -"arguments this function will receive." -msgstr "" - -#: ../../library/ctypes.rst:1069 -msgid "" -"The :func:`CFUNCTYPE` factory function creates types for callback functions " -"using the ``cdecl`` calling convention. On Windows, the :func:`WINFUNCTYPE` " -"factory function creates types for callback functions using the ``stdcall`` " -"calling convention." -msgstr "" - -#: ../../library/ctypes.rst:1074 -msgid "" -"Both of these factory functions are called with the result type as first " -"argument, and the callback functions expected argument types as the " -"remaining arguments." -msgstr "" - -#: ../../library/ctypes.rst:1078 -msgid "" -"I will present an example here which uses the standard C library's :c:func:`!" -"qsort` function, that is used to sort items with the help of a callback " -"function. :c:func:`!qsort` will be used to sort an array of integers::" -msgstr "" - -#: ../../library/ctypes.rst:1082 -msgid "" -">>> IntArray5 = c_int * 5\n" -">>> ia = IntArray5(5, 1, 7, 33, 99)\n" -">>> qsort = libc.qsort\n" -">>> qsort.restype = None\n" -">>>" -msgstr "" -">>> IntArray5 = c_int * 5\n" -">>> ia = IntArray5(5, 1, 7, 33, 99)\n" -">>> qsort = libc.qsort\n" -">>> qsort.restype = None\n" -">>>" - -#: ../../library/ctypes.rst:1088 -msgid "" -":func:`!qsort` must be called with a pointer to the data to sort, the number " -"of items in the data array, the size of one item, and a pointer to the " -"comparison function, the callback. The callback will then be called with two " -"pointers to items, and it must return a negative integer if the first item " -"is smaller than the second, a zero if they are equal, and a positive integer " -"otherwise." -msgstr "" - -#: ../../library/ctypes.rst:1094 -msgid "" -"So our callback function receives pointers to integers, and must return an " -"integer. First we create the ``type`` for the callback function::" -msgstr "" - -#: ../../library/ctypes.rst:1097 -msgid "" -">>> CMPFUNC = CFUNCTYPE(c_int, POINTER(c_int), POINTER(c_int))\n" -">>>" -msgstr "" -">>> CMPFUNC = CFUNCTYPE(c_int, POINTER(c_int), POINTER(c_int))\n" -">>>" - -#: ../../library/ctypes.rst:1100 -msgid "" -"To get started, here is a simple callback that shows the values it gets " -"passed::" -msgstr "" - -#: ../../library/ctypes.rst:1103 -msgid "" -">>> def py_cmp_func(a, b):\n" -"... print(\"py_cmp_func\", a[0], b[0])\n" -"... return 0\n" -"...\n" -">>> cmp_func = CMPFUNC(py_cmp_func)\n" -">>>" -msgstr "" -">>> def py_cmp_func(a, b):\n" -"... print(\"py_cmp_func\", a[0], b[0])\n" -"... return 0\n" -"...\n" -">>> cmp_func = CMPFUNC(py_cmp_func)\n" -">>>" - -#: ../../library/ctypes.rst:1110 -msgid "The result::" -msgstr "結果為： ::" - -#: ../../library/ctypes.rst:1112 -msgid "" -">>> qsort(ia, len(ia), sizeof(c_int), cmp_func)\n" -"py_cmp_func 5 1\n" -"py_cmp_func 33 99\n" -"py_cmp_func 7 33\n" -"py_cmp_func 5 7\n" -"py_cmp_func 1 7\n" -">>>" -msgstr "" -">>> qsort(ia, len(ia), sizeof(c_int), cmp_func)\n" -"py_cmp_func 5 1\n" -"py_cmp_func 33 99\n" -"py_cmp_func 7 33\n" -"py_cmp_func 5 7\n" -"py_cmp_func 1 7\n" -">>>" - -#: ../../library/ctypes.rst:1120 -msgid "Now we can actually compare the two items and return a useful result::" -msgstr "" - -#: ../../library/ctypes.rst:1122 -msgid "" -">>> def py_cmp_func(a, b):\n" -"... print(\"py_cmp_func\", a[0], b[0])\n" -"... return a[0] - b[0]\n" -"...\n" -">>>\n" -">>> qsort(ia, len(ia), sizeof(c_int), CMPFUNC(py_cmp_func))\n" -"py_cmp_func 5 1\n" -"py_cmp_func 33 99\n" -"py_cmp_func 7 33\n" -"py_cmp_func 1 7\n" -"py_cmp_func 5 7\n" -">>>" -msgstr "" -">>> def py_cmp_func(a, b):\n" -"... print(\"py_cmp_func\", a[0], b[0])\n" -"... return a[0] - b[0]\n" -"...\n" -">>>\n" -">>> qsort(ia, len(ia), sizeof(c_int), CMPFUNC(py_cmp_func))\n" -"py_cmp_func 5 1\n" -"py_cmp_func 33 99\n" -"py_cmp_func 7 33\n" -"py_cmp_func 1 7\n" -"py_cmp_func 5 7\n" -">>>" - -#: ../../library/ctypes.rst:1135 -msgid "As we can easily check, our array is sorted now::" -msgstr "" - -#: ../../library/ctypes.rst:1137 -msgid "" -">>> for i in ia: print(i, end=\" \")\n" -"...\n" -"1 5 7 33 99\n" -">>>" -msgstr "" -">>> for i in ia: print(i, end=\" \")\n" -"...\n" -"1 5 7 33 99\n" -">>>" - -#: ../../library/ctypes.rst:1142 -msgid "" -"The function factories can be used as decorator factories, so we may as well " -"write::" -msgstr "" - -#: ../../library/ctypes.rst:1145 -msgid "" -">>> @CFUNCTYPE(c_int, POINTER(c_int), POINTER(c_int))\n" -"... def py_cmp_func(a, b):\n" -"... print(\"py_cmp_func\", a[0], b[0])\n" -"... return a[0] - b[0]\n" -"...\n" -">>> qsort(ia, len(ia), sizeof(c_int), py_cmp_func)\n" -"py_cmp_func 5 1\n" -"py_cmp_func 33 99\n" -"py_cmp_func 7 33\n" -"py_cmp_func 1 7\n" -"py_cmp_func 5 7\n" -">>>" -msgstr "" -">>> @CFUNCTYPE(c_int, POINTER(c_int), POINTER(c_int))\n" -"... def py_cmp_func(a, b):\n" -"... print(\"py_cmp_func\", a[0], b[0])\n" -"... return a[0] - b[0]\n" -"...\n" -">>> qsort(ia, len(ia), sizeof(c_int), py_cmp_func)\n" -"py_cmp_func 5 1\n" -"py_cmp_func 33 99\n" -"py_cmp_func 7 33\n" -"py_cmp_func 1 7\n" -"py_cmp_func 5 7\n" -">>>" - -#: ../../library/ctypes.rst:1160 -msgid "" -"Make sure you keep references to :func:`CFUNCTYPE` objects as long as they " -"are used from C code. :mod:`ctypes` doesn't, and if you don't, they may be " -"garbage collected, crashing your program when a callback is made." -msgstr "" - -#: ../../library/ctypes.rst:1164 -msgid "" -"Also, note that if the callback function is called in a thread created " -"outside of Python's control (e.g. by the foreign code that calls the " -"callback), ctypes creates a new dummy Python thread on every invocation. " -"This behavior is correct for most purposes, but it means that values stored " -"with :class:`threading.local` will *not* survive across different callbacks, " -"even when those calls are made from the same C thread." -msgstr "" - -#: ../../library/ctypes.rst:1174 -msgid "Accessing values exported from dlls" -msgstr "" - -#: ../../library/ctypes.rst:1176 -msgid "" -"Some shared libraries not only export functions, they also export variables. " -"An example in the Python library itself is the :c:data:`Py_Version`, Python " -"runtime version number encoded in a single constant integer." -msgstr "" - -#: ../../library/ctypes.rst:1180 -msgid "" -":mod:`ctypes` can access values like this with the :meth:`~_CData.in_dll` " -"class methods of the type. *pythonapi* is a predefined symbol giving access " -"to the Python C api::" -msgstr "" - -#: ../../library/ctypes.rst:1184 -msgid "" -">>> version = ctypes.c_int.in_dll(ctypes.pythonapi, \"Py_Version\")\n" -">>> print(hex(version.value))\n" -"0x30c00a0" -msgstr "" -">>> version = ctypes.c_int.in_dll(ctypes.pythonapi, \"Py_Version\")\n" -">>> print(hex(version.value))\n" -"0x30c00a0" - -#: ../../library/ctypes.rst:1188 -msgid "" -"An extended example which also demonstrates the use of pointers accesses " -"the :c:data:`PyImport_FrozenModules` pointer exported by Python." -msgstr "" - -#: ../../library/ctypes.rst:1191 -msgid "Quoting the docs for that value:" -msgstr "" - -#: ../../library/ctypes.rst:1193 -msgid "" -"This pointer is initialized to point to an array of :c:struct:`_frozen` " -"records, terminated by one whose members are all ``NULL`` or zero. When a " -"frozen module is imported, it is searched in this table. Third-party code " -"could play tricks with this to provide a dynamically created collection of " -"frozen modules." -msgstr "" - -#: ../../library/ctypes.rst:1198 -msgid "" -"So manipulating this pointer could even prove useful. To restrict the " -"example size, we show only how this table can be read with :mod:`ctypes`::" -msgstr "" - -#: ../../library/ctypes.rst:1201 -msgid "" -">>> from ctypes import *\n" -">>>\n" -">>> class struct_frozen(Structure):\n" -"... _fields_ = [(\"name\", c_char_p),\n" -"... (\"code\", POINTER(c_ubyte)),\n" -"... (\"size\", c_int),\n" -"... (\"get_code\", POINTER(c_ubyte)), # Function pointer\n" -"... ]\n" -"...\n" -">>>" -msgstr "" -">>> from ctypes import *\n" -">>>\n" -">>> class struct_frozen(Structure):\n" -"... _fields_ = [(\"name\", c_char_p),\n" -"... (\"code\", POINTER(c_ubyte)),\n" -"... (\"size\", c_int),\n" -"... (\"get_code\", POINTER(c_ubyte)), # 函式指標\n" -"... ]\n" -"...\n" -">>>" - -#: ../../library/ctypes.rst:1212 -msgid "" -"We have defined the :c:struct:`_frozen` data type, so we can get the pointer " -"to the table::" -msgstr "" - -#: ../../library/ctypes.rst:1215 -msgid "" -">>> FrozenTable = POINTER(struct_frozen)\n" -">>> table = FrozenTable.in_dll(pythonapi, \"_PyImport_FrozenBootstrap\")\n" -">>>" -msgstr "" -">>> FrozenTable = POINTER(struct_frozen)\n" -">>> table = FrozenTable.in_dll(pythonapi, \"_PyImport_FrozenBootstrap\")\n" -">>>" - -#: ../../library/ctypes.rst:1219 -msgid "" -"Since ``table`` is a ``pointer`` to the array of ``struct_frozen`` records, " -"we can iterate over it, but we just have to make sure that our loop " -"terminates, because pointers have no size. Sooner or later it would probably " -"crash with an access violation or whatever, so it's better to break out of " -"the loop when we hit the ``NULL`` entry::" -msgstr "" - -#: ../../library/ctypes.rst:1225 -msgid "" -">>> for item in table:\n" -"... if item.name is None:\n" -"... break\n" -"... print(item.name.decode(\"ascii\"), item.size)\n" -"...\n" -"_frozen_importlib 31764\n" -"_frozen_importlib_external 41499\n" -"zipimport 12345\n" -">>>" -msgstr "" -">>> for item in table:\n" -"... if item.name is None:\n" -"... break\n" -"... print(item.name.decode(\"ascii\"), item.size)\n" -"...\n" -"_frozen_importlib 31764\n" -"_frozen_importlib_external 41499\n" -"zipimport 12345\n" -">>>" - -#: ../../library/ctypes.rst:1235 -msgid "" -"The fact that standard Python has a frozen module and a frozen package " -"(indicated by the negative ``size`` member) is not well known, it is only " -"used for testing. Try it out with ``import __hello__`` for example." -msgstr "" - -#: ../../library/ctypes.rst:1243 -msgid "Surprises" -msgstr "" - -#: ../../library/ctypes.rst:1245 -msgid "" -"There are some edges in :mod:`ctypes` where you might expect something other " -"than what actually happens." -msgstr "" - -#: ../../library/ctypes.rst:1248 -msgid "Consider the following example::" -msgstr "" - -#: ../../library/ctypes.rst:1250 -msgid "" -">>> from ctypes import *\n" -">>> class POINT(Structure):\n" -"... _fields_ = (\"x\", c_int), (\"y\", c_int)\n" -"...\n" -">>> class RECT(Structure):\n" -"... _fields_ = (\"a\", POINT), (\"b\", POINT)\n" -"...\n" -">>> p1 = POINT(1, 2)\n" -">>> p2 = POINT(3, 4)\n" -">>> rc = RECT(p1, p2)\n" -">>> print(rc.a.x, rc.a.y, rc.b.x, rc.b.y)\n" -"1 2 3 4\n" -">>> # now swap the two points\n" -">>> rc.a, rc.b = rc.b, rc.a\n" -">>> print(rc.a.x, rc.a.y, rc.b.x, rc.b.y)\n" -"3 4 3 4\n" -">>>" -msgstr "" -">>> from ctypes import *\n" -">>> class POINT(Structure):\n" -"... _fields_ = (\"x\", c_int), (\"y\", c_int)\n" -"...\n" -">>> class RECT(Structure):\n" -"... _fields_ = (\"a\", POINT), (\"b\", POINT)\n" -"...\n" -">>> p1 = POINT(1, 2)\n" -">>> p2 = POINT(3, 4)\n" -">>> rc = RECT(p1, p2)\n" -">>> print(rc.a.x, rc.a.y, rc.b.x, rc.b.y)\n" -"1 2 3 4\n" -">>> # now swap the two points\n" -">>> rc.a, rc.b = rc.b, rc.a\n" -">>> print(rc.a.x, rc.a.y, rc.b.x, rc.b.y)\n" -"3 4 3 4\n" -">>>" - -#: ../../library/ctypes.rst:1268 -msgid "" -"Hm. We certainly expected the last statement to print ``3 4 1 2``. What " -"happened? Here are the steps of the ``rc.a, rc.b = rc.b, rc.a`` line above::" -msgstr "" - -#: ../../library/ctypes.rst:1271 -msgid "" -">>> temp0, temp1 = rc.b, rc.a\n" -">>> rc.a = temp0\n" -">>> rc.b = temp1\n" -">>>" -msgstr "" -">>> temp0, temp1 = rc.b, rc.a\n" -">>> rc.a = temp0\n" -">>> rc.b = temp1\n" -">>>" - -#: ../../library/ctypes.rst:1276 -msgid "" -"Note that ``temp0`` and ``temp1`` are objects still using the internal " -"buffer of the ``rc`` object above. So executing ``rc.a = temp0`` copies the " -"buffer contents of ``temp0`` into ``rc`` 's buffer. This, in turn, changes " -"the contents of ``temp1``. So, the last assignment ``rc.b = temp1``, doesn't " -"have the expected effect." -msgstr "" - -#: ../../library/ctypes.rst:1282 -msgid "" -"Keep in mind that retrieving sub-objects from Structure, Unions, and Arrays " -"doesn't *copy* the sub-object, instead it retrieves a wrapper object " -"accessing the root-object's underlying buffer." -msgstr "" - -#: ../../library/ctypes.rst:1286 -msgid "" -"Another example that may behave differently from what one would expect is " -"this::" -msgstr "" - -#: ../../library/ctypes.rst:1288 -msgid "" -">>> s = c_char_p()\n" -">>> s.value = b\"abc def ghi\"\n" -">>> s.value\n" -"b'abc def ghi'\n" -">>> s.value is s.value\n" -"False\n" -">>>" -msgstr "" -">>> s = c_char_p()\n" -">>> s.value = b\"abc def ghi\"\n" -">>> s.value\n" -"b'abc def ghi'\n" -">>> s.value is s.value\n" -"False\n" -">>>" - -#: ../../library/ctypes.rst:1298 -msgid "" -"Objects instantiated from :class:`c_char_p` can only have their value set to " -"bytes or integers." -msgstr "" - -#: ../../library/ctypes.rst:1301 -msgid "" -"Why is it printing ``False``? ctypes instances are objects containing a " -"memory block plus some :term:`descriptor`\\s accessing the contents of the " -"memory. Storing a Python object in the memory block does not store the " -"object itself, instead the ``contents`` of the object is stored. Accessing " -"the contents again constructs a new Python object each time!" -msgstr "" - -#: ../../library/ctypes.rst:1311 -msgid "Variable-sized data types" -msgstr "" - -#: ../../library/ctypes.rst:1313 -msgid "" -":mod:`ctypes` provides some support for variable-sized arrays and structures." -msgstr "" - -#: ../../library/ctypes.rst:1315 -msgid "" -"The :func:`resize` function can be used to resize the memory buffer of an " -"existing ctypes object. The function takes the object as first argument, " -"and the requested size in bytes as the second argument. The memory block " -"cannot be made smaller than the natural memory block specified by the " -"objects type, a :exc:`ValueError` is raised if this is tried::" -msgstr "" - -#: ../../library/ctypes.rst:1321 -msgid "" -">>> short_array = (c_short * 4)()\n" -">>> print(sizeof(short_array))\n" -"8\n" -">>> resize(short_array, 4)\n" -"Traceback (most recent call last):\n" -" ...\n" -"ValueError: minimum size is 8\n" -">>> resize(short_array, 32)\n" -">>> sizeof(short_array)\n" -"32\n" -">>> sizeof(type(short_array))\n" -"8\n" -">>>" -msgstr "" -">>> short_array = (c_short * 4)()\n" -">>> print(sizeof(short_array))\n" -"8\n" -">>> resize(short_array, 4)\n" -"Traceback (most recent call last):\n" -" ...\n" -"ValueError: minimum size is 8\n" -">>> resize(short_array, 32)\n" -">>> sizeof(short_array)\n" -"32\n" -">>> sizeof(type(short_array))\n" -"8\n" -">>>" - -#: ../../library/ctypes.rst:1335 -msgid "" -"This is nice and fine, but how would one access the additional elements " -"contained in this array? Since the type still only knows about 4 elements, " -"we get errors accessing other elements::" -msgstr "" - -#: ../../library/ctypes.rst:1339 -msgid "" -">>> short_array[:]\n" -"[0, 0, 0, 0]\n" -">>> short_array[7]\n" -"Traceback (most recent call last):\n" -" ...\n" -"IndexError: invalid index\n" -">>>" -msgstr "" -">>> short_array[:]\n" -"[0, 0, 0, 0]\n" -">>> short_array[7]\n" -"Traceback (most recent call last):\n" -" ...\n" -"IndexError: invalid index\n" -">>>" - -#: ../../library/ctypes.rst:1347 -msgid "" -"Another way to use variable-sized data types with :mod:`ctypes` is to use " -"the dynamic nature of Python, and (re-)define the data type after the " -"required size is already known, on a case by case basis." -msgstr "" - -#: ../../library/ctypes.rst:1355 -msgid "ctypes reference" -msgstr "" - -#: ../../library/ctypes.rst:1361 -msgid "Finding shared libraries" -msgstr "" - -#: ../../library/ctypes.rst:1363 -msgid "" -"When programming in a compiled language, shared libraries are accessed when " -"compiling/linking a program, and when the program is run." -msgstr "" - -#: ../../library/ctypes.rst:1366 -msgid "" -"The purpose of the :func:`~ctypes.util.find_library` function is to locate a " -"library in a way similar to what the compiler or runtime loader does (on " -"platforms with several versions of a shared library the most recent should " -"be loaded), while the ctypes library loaders act like when a program is run, " -"and call the runtime loader directly." -msgstr "" - -#: ../../library/ctypes.rst:1372 -msgid "" -"The :mod:`!ctypes.util` module provides a function which can help to " -"determine the library to load." -msgstr "" - -#: ../../library/ctypes.rst:1380 -msgid "" -"Try to find a library and return a pathname. *name* is the library name " -"without any prefix like *lib*, suffix like ``.so``, ``.dylib`` or version " -"number (this is the form used for the posix linker option :option:`!-l`). " -"If no library can be found, returns ``None``." -msgstr "" - -#: ../../library/ctypes.rst:1385 ../../library/ctypes.rst:2136 -msgid "The exact functionality is system dependent." -msgstr "" - -#: ../../library/ctypes.rst:1387 -msgid "" -"On Linux, :func:`~ctypes.util.find_library` tries to run external programs " -"(``/sbin/ldconfig``, ``gcc``, ``objdump`` and ``ld``) to find the library " -"file. It returns the filename of the library file." -msgstr "" - -#: ../../library/ctypes.rst:1391 -msgid "" -"Note that if the output of these programs does not correspond to the dynamic " -"linker used by Python, the result of this function may be misleading." -msgstr "" - -#: ../../library/ctypes.rst:1394 -msgid "" -"On Linux, the value of the environment variable ``LD_LIBRARY_PATH`` is used " -"when searching for libraries, if a library cannot be found by any other " -"means." -msgstr "" - -#: ../../library/ctypes.rst:1398 -msgid "Here are some examples::" -msgstr "以下是一些範例： ::" - -#: ../../library/ctypes.rst:1400 -msgid "" -">>> from ctypes.util import find_library\n" -">>> find_library(\"m\")\n" -"'libm.so.6'\n" -">>> find_library(\"c\")\n" -"'libc.so.6'\n" -">>> find_library(\"bz2\")\n" -"'libbz2.so.1.0'\n" -">>>" -msgstr "" -">>> from ctypes.util import find_library\n" -">>> find_library(\"m\")\n" -"'libm.so.6'\n" -">>> find_library(\"c\")\n" -"'libc.so.6'\n" -">>> find_library(\"bz2\")\n" -"'libbz2.so.1.0'\n" -">>>" - -#: ../../library/ctypes.rst:1409 -msgid "" -"On macOS and Android, :func:`~ctypes.util.find_library` uses the system's " -"standard naming schemes and paths to locate the library, and returns a full " -"pathname if successful::" -msgstr "" - -#: ../../library/ctypes.rst:1413 -msgid "" -">>> from ctypes.util import find_library\n" -">>> find_library(\"c\")\n" -"'/usr/lib/libc.dylib'\n" -">>> find_library(\"m\")\n" -"'/usr/lib/libm.dylib'\n" -">>> find_library(\"bz2\")\n" -"'/usr/lib/libbz2.dylib'\n" -">>> find_library(\"AGL\")\n" -"'/System/Library/Frameworks/AGL.framework/AGL'\n" -">>>" -msgstr "" -">>> from ctypes.util import find_library\n" -">>> find_library(\"c\")\n" -"'/usr/lib/libc.dylib'\n" -">>> find_library(\"m\")\n" -"'/usr/lib/libm.dylib'\n" -">>> find_library(\"bz2\")\n" -"'/usr/lib/libbz2.dylib'\n" -">>> find_library(\"AGL\")\n" -"'/System/Library/Frameworks/AGL.framework/AGL'\n" -">>>" - -#: ../../library/ctypes.rst:1424 -msgid "" -"On Windows, :func:`~ctypes.util.find_library` searches along the system " -"search path, and returns the full pathname, but since there is no predefined " -"naming scheme a call like ``find_library(\"c\")`` will fail and return " -"``None``." -msgstr "" - -#: ../../library/ctypes.rst:1428 -msgid "" -"If wrapping a shared library with :mod:`ctypes`, it *may* be better to " -"determine the shared library name at development time, and hardcode that " -"into the wrapper module instead of using :func:`~ctypes.util.find_library` " -"to locate the library at runtime." -msgstr "" - -#: ../../library/ctypes.rst:1436 -msgid "Listing loaded shared libraries" -msgstr "" - -#: ../../library/ctypes.rst:1438 -msgid "" -"When writing code that relies on code loaded from shared libraries, it can " -"be useful to know which shared libraries have already been loaded into the " -"current process." -msgstr "" - -#: ../../library/ctypes.rst:1442 -msgid "" -"The :mod:`!ctypes.util` module provides the :func:`~ctypes.util.dllist` " -"function, which calls the different APIs provided by the various platforms " -"to help determine which shared libraries have already been loaded into the " -"current process." -msgstr "" - -#: ../../library/ctypes.rst:1446 -msgid "" -"The exact output of this function will be system dependent. On most " -"platforms, the first entry of this list represents the current process " -"itself, which may be an empty string. For example, on glibc-based Linux, the " -"return may look like::" -msgstr "" - -#: ../../library/ctypes.rst:1451 -msgid "" -">>> from ctypes.util import dllist\n" -">>> dllist()\n" -"['', 'linux-vdso.so.1', '/lib/x86_64-linux-gnu/libm.so.6', '/lib/x86_64-" -"linux-gnu/libc.so.6', ... ]" -msgstr "" -">>> from ctypes.util import dllist\n" -">>> dllist()\n" -"['', 'linux-vdso.so.1', '/lib/x86_64-linux-gnu/libm.so.6', '/lib/x86_64-" -"linux-gnu/libc.so.6', ... ]" - -#: ../../library/ctypes.rst:1458 -msgid "Loading shared libraries" -msgstr "" - -#: ../../library/ctypes.rst:1460 -msgid "" -"There are several ways to load shared libraries into the Python process. " -"One way is to instantiate one of the following classes:" -msgstr "" - -#: ../../library/ctypes.rst:1466 -msgid "" -"Instances of this class represent loaded shared libraries. Functions in " -"these libraries use the standard C calling convention, and are assumed to " -"return :c:expr:`int`." -msgstr "" - -#: ../../library/ctypes.rst:1470 -msgid "" -"On Windows creating a :class:`CDLL` instance may fail even if the DLL name " -"exists. When a dependent DLL of the loaded DLL is not found, a :exc:" -"`OSError` error is raised with the message *\"[WinError 126] The specified " -"module could not be found\".* This error message does not contain the name " -"of the missing DLL because the Windows API does not return this information " -"making this error hard to diagnose. To resolve this error and determine " -"which DLL is not found, you need to find the list of dependent DLLs and " -"determine which one is not found using Windows debugging and tracing tools." -msgstr "" - -#: ../../library/ctypes.rst:1482 ../../library/ctypes.rst:1507 -#: ../../library/ctypes.rst:1520 ../../library/ctypes.rst:1538 -msgid "The *name* parameter can now be a :term:`path-like object`." -msgstr "" - -#: ../../library/ctypes.rst:1486 -msgid "" -"`Microsoft DUMPBIN tool `_ -- A tool to find DLL dependents." -msgstr "" - -#: ../../library/ctypes.rst:1492 -msgid "" -"Instances of this class represent loaded shared libraries, functions in " -"these libraries use the ``stdcall`` calling convention, and are assumed to " -"return the windows specific :class:`HRESULT` code. :class:`HRESULT` values " -"contain information specifying whether the function call failed or " -"succeeded, together with additional error code. If the return value signals " -"a failure, an :class:`OSError` is automatically raised." -msgstr "" - -#: ../../library/ctypes.rst:1499 ../../library/ctypes.rst:1516 -#: ../../library/ctypes.rst:1660 ../../library/ctypes.rst:1668 -#: ../../library/ctypes.rst:1840 ../../library/ctypes.rst:1892 -#: ../../library/ctypes.rst:2044 ../../library/ctypes.rst:2116 -#: ../../library/ctypes.rst:2125 ../../library/ctypes.rst:2152 -#: ../../library/ctypes.rst:2166 ../../library/ctypes.rst:2175 -#: ../../library/ctypes.rst:2184 ../../library/ctypes.rst:2199 -#: ../../library/ctypes.rst:2266 ../../library/ctypes.rst:2293 -#: ../../library/ctypes.rst:2693 ../../library/ctypes.rst:3111 -msgid "Availability" -msgstr "可用性" - -#: ../../library/ctypes.rst:1501 -msgid "" -":exc:`WindowsError` used to be raised, which is now an alias of :exc:" -"`OSError`." -msgstr "" - -#: ../../library/ctypes.rst:1512 -msgid "" -"Instances of this class represent loaded shared libraries, functions in " -"these libraries use the ``stdcall`` calling convention, and are assumed to " -"return :c:expr:`int` by default." -msgstr "" - -#: ../../library/ctypes.rst:1523 -msgid "" -"The Python :term:`global interpreter lock` is released before calling any " -"function exported by these libraries, and reacquired afterwards." -msgstr "" - -#: ../../library/ctypes.rst:1529 -msgid "" -"Instances of this class behave like :class:`CDLL` instances, except that the " -"Python GIL is *not* released during the function call, and after the " -"function execution the Python error flag is checked. If the error flag is " -"set, a Python exception is raised." -msgstr "" - -#: ../../library/ctypes.rst:1534 -msgid "Thus, this is only useful to call Python C api functions directly." -msgstr "" - -#: ../../library/ctypes.rst:1540 -msgid "" -"All these classes can be instantiated by calling them with at least one " -"argument, the pathname of the shared library. If you have an existing " -"handle to an already loaded shared library, it can be passed as the " -"``handle`` named parameter, otherwise the underlying platform's :c:func:`!" -"dlopen` or :c:func:`!LoadLibrary` function is used to load the library into " -"the process, and to get a handle to it." -msgstr "" - -#: ../../library/ctypes.rst:1547 -msgid "" -"The *mode* parameter can be used to specify how the library is loaded. For " -"details, consult the :manpage:`dlopen(3)` manpage. On Windows, *mode* is " -"ignored. On posix systems, RTLD_NOW is always added, and is not " -"configurable." -msgstr "" - -#: ../../library/ctypes.rst:1552 -msgid "" -"The *use_errno* parameter, when set to true, enables a ctypes mechanism that " -"allows accessing the system :data:`errno` error number in a safe way. :mod:" -"`ctypes` maintains a thread-local copy of the system's :data:`errno` " -"variable; if you call foreign functions created with ``use_errno=True`` then " -"the :data:`errno` value before the function call is swapped with the ctypes " -"private copy, the same happens immediately after the function call." -msgstr "" - -#: ../../library/ctypes.rst:1559 -msgid "" -"The function :func:`ctypes.get_errno` returns the value of the ctypes " -"private copy, and the function :func:`ctypes.set_errno` changes the ctypes " -"private copy to a new value and returns the former value." -msgstr "" - -#: ../../library/ctypes.rst:1563 -msgid "" -"The *use_last_error* parameter, when set to true, enables the same mechanism " -"for the Windows error code which is managed by the :func:`GetLastError` and :" -"func:`!SetLastError` Windows API functions; :func:`ctypes.get_last_error` " -"and :func:`ctypes.set_last_error` are used to request and change the ctypes " -"private copy of the windows error code." -msgstr "" - -#: ../../library/ctypes.rst:1569 -msgid "" -"The *winmode* parameter is used on Windows to specify how the library is " -"loaded (since *mode* is ignored). It takes any value that is valid for the " -"Win32 API ``LoadLibraryEx`` flags parameter. When omitted, the default is to " -"use the flags that result in the most secure DLL load, which avoids issues " -"such as DLL hijacking. Passing the full path to the DLL is the safest way to " -"ensure the correct library and dependencies are loaded." -msgstr "" - -#: ../../library/ctypes.rst:1576 -msgid "Added *winmode* parameter." -msgstr "新增 *winmode* 參數。" - -#: ../../library/ctypes.rst:1583 -msgid "" -"Flag to use as *mode* parameter. On platforms where this flag is not " -"available, it is defined as the integer zero." -msgstr "" - -#: ../../library/ctypes.rst:1590 -msgid "" -"Flag to use as *mode* parameter. On platforms where this is not available, " -"it is the same as *RTLD_GLOBAL*." -msgstr "" - -#: ../../library/ctypes.rst:1597 -msgid "" -"The default mode which is used to load shared libraries. On OSX 10.3, this " -"is *RTLD_GLOBAL*, otherwise it is the same as *RTLD_LOCAL*." -msgstr "" - -#: ../../library/ctypes.rst:1600 -msgid "" -"Instances of these classes have no public methods. Functions exported by " -"the shared library can be accessed as attributes or by index. Please note " -"that accessing the function through an attribute caches the result and " -"therefore accessing it repeatedly returns the same object each time. On the " -"other hand, accessing it through an index returns a new object each time::" -msgstr "" - -#: ../../library/ctypes.rst:1606 -msgid "" -">>> from ctypes import CDLL\n" -">>> libc = CDLL(\"libc.so.6\") # On Linux\n" -">>> libc.time == libc.time\n" -"True\n" -">>> libc['time'] == libc['time']\n" -"False" -msgstr "" -">>> from ctypes import CDLL\n" -">>> libc = CDLL(\"libc.so.6\") # 於 Linux\n" -">>> libc.time == libc.time\n" -"True\n" -">>> libc['time'] == libc['time']\n" -"False" - -#: ../../library/ctypes.rst:1613 -msgid "" -"The following public attributes are available, their name starts with an " -"underscore to not clash with exported function names:" -msgstr "" - -#: ../../library/ctypes.rst:1619 -msgid "The system handle used to access the library." -msgstr "" - -#: ../../library/ctypes.rst:1624 -msgid "The name of the library passed in the constructor." -msgstr "" - -#: ../../library/ctypes.rst:1626 -msgid "" -"Shared libraries can also be loaded by using one of the prefabricated " -"objects, which are instances of the :class:`LibraryLoader` class, either by " -"calling the :meth:`~LibraryLoader.LoadLibrary` method, or by retrieving the " -"library as attribute of the loader instance." -msgstr "" - -#: ../../library/ctypes.rst:1634 -msgid "" -"Class which loads shared libraries. *dlltype* should be one of the :class:" -"`CDLL`, :class:`PyDLL`, :class:`WinDLL`, or :class:`OleDLL` types." -msgstr "" - -#: ../../library/ctypes.rst:1637 -msgid "" -":meth:`!__getattr__` has special behavior: It allows loading a shared " -"library by accessing it as attribute of a library loader instance. The " -"result is cached, so repeated attribute accesses return the same library " -"each time." -msgstr "" - -#: ../../library/ctypes.rst:1643 -msgid "" -"Load a shared library into the process and return it. This method always " -"returns a new instance of the library." -msgstr "" - -#: ../../library/ctypes.rst:1647 -msgid "These prefabricated library loaders are available:" -msgstr "" - -#: ../../library/ctypes.rst:1652 -msgid "Creates :class:`CDLL` instances." -msgstr "" - -#: ../../library/ctypes.rst:1658 -msgid "Creates :class:`WinDLL` instances." -msgstr "" - -#: ../../library/ctypes.rst:1666 -msgid "Creates :class:`OleDLL` instances." -msgstr "" - -#: ../../library/ctypes.rst:1674 -msgid "Creates :class:`PyDLL` instances." -msgstr "" - -#: ../../library/ctypes.rst:1677 -msgid "" -"For accessing the C Python api directly, a ready-to-use Python shared " -"library object is available:" -msgstr "" - -#: ../../library/ctypes.rst:1683 -msgid "" -"An instance of :class:`PyDLL` that exposes Python C API functions as " -"attributes. Note that all these functions are assumed to return C :c:expr:" -"`int`, which is of course not always the truth, so you have to assign the " -"correct :attr:`!restype` attribute to use these functions." -msgstr "" - -#: ../../library/ctypes.rst:1688 ../../library/ctypes.rst:1690 -msgid "" -"Loading a library through any of these objects raises an :ref:`auditing " -"event ` ``ctypes.dlopen`` with string argument ``name``, the name " -"used to load the library." -msgstr "" - -#: ../../library/ctypes.rst:1694 ../../library/ctypes.rst:1696 -msgid "" -"Accessing a function on a loaded library raises an auditing event ``ctypes." -"dlsym`` with arguments ``library`` (the library object) and ``name`` (the " -"symbol's name as a string or integer)." -msgstr "" - -#: ../../library/ctypes.rst:1700 ../../library/ctypes.rst:1702 -msgid "" -"In cases when only the library handle is available rather than the object, " -"accessing a function raises an auditing event ``ctypes.dlsym/handle`` with " -"arguments ``handle`` (the raw library handle) and ``name``." -msgstr "" - -#: ../../library/ctypes.rst:1709 -msgid "Foreign functions" -msgstr "" - -#: ../../library/ctypes.rst:1711 -msgid "" -"As explained in the previous section, foreign functions can be accessed as " -"attributes of loaded shared libraries. The function objects created in this " -"way by default accept any number of arguments, accept any ctypes data " -"instances as arguments, and return the default result type specified by the " -"library loader." -msgstr "" - -#: ../../library/ctypes.rst:1716 -msgid "" -"They are instances of a private local class :class:`!_FuncPtr` (not exposed " -"in :mod:`!ctypes`) which inherits from the private :class:`_CFuncPtr` class:" -msgstr "" - -#: ../../library/ctypes.rst:1719 -msgid "" -">>> import ctypes\n" -">>> lib = ctypes.CDLL(None)\n" -">>> issubclass(lib._FuncPtr, ctypes._CFuncPtr)\n" -"True\n" -">>> lib._FuncPtr is ctypes._CFuncPtr\n" -"False" -msgstr "" -">>> import ctypes\n" -">>> lib = ctypes.CDLL(None)\n" -">>> issubclass(lib._FuncPtr, ctypes._CFuncPtr)\n" -"True\n" -">>> lib._FuncPtr is ctypes._CFuncPtr\n" -"False" - -#: ../../library/ctypes.rst:1730 -msgid "Base class for C callable foreign functions." -msgstr "" - -#: ../../library/ctypes.rst:1732 -msgid "" -"Instances of foreign functions are also C compatible data types; they " -"represent C function pointers." -msgstr "" - -#: ../../library/ctypes.rst:1735 -msgid "" -"This behavior can be customized by assigning to special attributes of the " -"foreign function object." -msgstr "" - -#: ../../library/ctypes.rst:1740 -msgid "" -"Assign a ctypes type to specify the result type of the foreign function. Use " -"``None`` for :c:expr:`void`, a function not returning anything." -msgstr "" - -#: ../../library/ctypes.rst:1743 -msgid "" -"It is possible to assign a callable Python object that is not a ctypes type, " -"in this case the function is assumed to return a C :c:expr:`int`, and the " -"callable will be called with this integer, allowing further processing or " -"error checking. Using this is deprecated, for more flexible post processing " -"or error checking use a ctypes data type as :attr:`!restype` and assign a " -"callable to the :attr:`errcheck` attribute." -msgstr "" - -#: ../../library/ctypes.rst:1752 -msgid "" -"Assign a tuple of ctypes types to specify the argument types that the " -"function accepts. Functions using the ``stdcall`` calling convention can " -"only be called with the same number of arguments as the length of this " -"tuple; functions using the C calling convention accept additional, " -"unspecified arguments as well." -msgstr "" - -#: ../../library/ctypes.rst:1758 -msgid "" -"When a foreign function is called, each actual argument is passed to the :" -"meth:`~_CData.from_param` class method of the items in the :attr:`argtypes` " -"tuple, this method allows adapting the actual argument to an object that the " -"foreign function accepts. For example, a :class:`c_char_p` item in the :" -"attr:`argtypes` tuple will convert a string passed as argument into a bytes " -"object using ctypes conversion rules." -msgstr "" - -#: ../../library/ctypes.rst:1765 -msgid "" -"New: It is now possible to put items in argtypes which are not ctypes types, " -"but each item must have a :meth:`~_CData.from_param` method which returns a " -"value usable as argument (integer, string, ctypes instance). This allows " -"defining adapters that can adapt custom objects as function parameters." -msgstr "" - -#: ../../library/ctypes.rst:1772 -msgid "" -"Assign a Python function or another callable to this attribute. The callable " -"will be called with three or more arguments:" -msgstr "" - -#: ../../library/ctypes.rst:1779 -msgid "" -"*result* is what the foreign function returns, as specified by the :attr:`!" -"restype` attribute." -msgstr "" - -#: ../../library/ctypes.rst:1782 -msgid "" -"*func* is the foreign function object itself, this allows reusing the same " -"callable object to check or post process the results of several functions." -msgstr "" - -#: ../../library/ctypes.rst:1786 -msgid "" -"*arguments* is a tuple containing the parameters originally passed to the " -"function call, this allows specializing the behavior on the arguments used." -msgstr "" - -#: ../../library/ctypes.rst:1790 -msgid "" -"The object that this function returns will be returned from the foreign " -"function call, but it can also check the result value and raise an exception " -"if the foreign function call failed." -msgstr "" - -#: ../../library/ctypes.rst:1795 ../../library/ctypes.rst:1797 -msgid "" -"On Windows, when a foreign function call raises a system exception (for " -"example, due to an access violation), it will be captured and replaced with " -"a suitable Python exception. Further, an auditing event ``ctypes." -"set_exception`` with argument ``code`` will be raised, allowing an audit " -"hook to replace the exception with its own." -msgstr "" - -#: ../../library/ctypes.rst:1803 ../../library/ctypes.rst:1805 -msgid "" -"Some ways to invoke foreign function calls as well as some of the functions " -"in this module may raise an auditing event ``ctypes.call_function`` with " -"arguments ``function pointer`` and ``arguments``." -msgstr "" - -#: ../../library/ctypes.rst:1812 -msgid "Function prototypes" -msgstr "" - -#: ../../library/ctypes.rst:1814 -msgid "" -"Foreign functions can also be created by instantiating function prototypes. " -"Function prototypes are similar to function prototypes in C; they describe a " -"function (return type, argument types, calling convention) without defining " -"an implementation. The factory functions must be called with the desired " -"result type and the argument types of the function, and can be used as " -"decorator factories, and as such, be applied to functions through the " -"``@wrapper`` syntax. See :ref:`ctypes-callback-functions` for examples." -msgstr "" - -#: ../../library/ctypes.rst:1825 -msgid "" -"The returned function prototype creates functions that use the standard C " -"calling convention. The function will release the GIL during the call. If " -"*use_errno* is set to true, the ctypes private copy of the system :data:" -"`errno` variable is exchanged with the real :data:`errno` value before and " -"after the call; *use_last_error* does the same for the Windows error code." -msgstr "" - -#: ../../library/ctypes.rst:1835 -msgid "" -"The returned function prototype creates functions that use the ``stdcall`` " -"calling convention. The function will release the GIL during the call. " -"*use_errno* and *use_last_error* have the same meaning as above." -msgstr "" - -#: ../../library/ctypes.rst:1845 -msgid "" -"The returned function prototype creates functions that use the Python " -"calling convention. The function will *not* release the GIL during the call." -msgstr "" - -#: ../../library/ctypes.rst:1848 -msgid "" -"Function prototypes created by these factory functions can be instantiated " -"in different ways, depending on the type and number of the parameters in the " -"call:" -msgstr "" - -#: ../../library/ctypes.rst:1855 -msgid "" -"Returns a foreign function at the specified address which must be an integer." -msgstr "" - -#: ../../library/ctypes.rst:1862 -msgid "" -"Create a C callable function (a callback function) from a Python *callable*." -msgstr "" - -#: ../../library/ctypes.rst:1869 -msgid "" -"Returns a foreign function exported by a shared library. *func_spec* must be " -"a 2-tuple ``(name_or_ordinal, library)``. The first item is the name of the " -"exported function as string, or the ordinal of the exported function as " -"small integer. The second item is the shared library instance." -msgstr "" - -#: ../../library/ctypes.rst:1879 -msgid "" -"Returns a foreign function that will call a COM method. *vtbl_index* is the " -"index into the virtual function table, a small non-negative integer. *name* " -"is name of the COM method. *iid* is an optional pointer to the interface " -"identifier which is used in extended error reporting." -msgstr "" - -#: ../../library/ctypes.rst:1884 -msgid "" -"If *iid* is not specified, an :exc:`OSError` is raised if the COM method " -"call fails. If *iid* is specified, a :exc:`~ctypes.COMError` is raised " -"instead." -msgstr "" - -#: ../../library/ctypes.rst:1888 -msgid "" -"COM methods use a special calling convention: They require a pointer to the " -"COM interface as first argument, in addition to those parameters that are " -"specified in the :attr:`!argtypes` tuple." -msgstr "" - -#: ../../library/ctypes.rst:1895 -msgid "" -"The optional *paramflags* parameter creates foreign function wrappers with " -"much more functionality than the features described above." -msgstr "" - -#: ../../library/ctypes.rst:1898 -msgid "" -"*paramflags* must be a tuple of the same length as :attr:`~_CFuncPtr." -"argtypes`." -msgstr "" - -#: ../../library/ctypes.rst:1900 -msgid "" -"Each item in this tuple contains further information about a parameter, it " -"must be a tuple containing one, two, or three items." -msgstr "" - -#: ../../library/ctypes.rst:1903 -msgid "" -"The first item is an integer containing a combination of direction flags for " -"the parameter:" -msgstr "" - -#: ../../library/ctypes.rst:1906 -msgid "1" -msgstr "1" - -#: ../../library/ctypes.rst:1907 -msgid "Specifies an input parameter to the function." -msgstr "" - -#: ../../library/ctypes.rst:1909 -msgid "2" -msgstr "2" - -#: ../../library/ctypes.rst:1910 -msgid "Output parameter. The foreign function fills in a value." -msgstr "" - -#: ../../library/ctypes.rst:1912 -msgid "4" -msgstr "4" - -#: ../../library/ctypes.rst:1913 -msgid "Input parameter which defaults to the integer zero." -msgstr "" - -#: ../../library/ctypes.rst:1915 -msgid "" -"The optional second item is the parameter name as string. If this is " -"specified, the foreign function can be called with named parameters." -msgstr "" - -#: ../../library/ctypes.rst:1918 -msgid "The optional third item is the default value for this parameter." -msgstr "" - -#: ../../library/ctypes.rst:1921 -msgid "" -"The following example demonstrates how to wrap the Windows ``MessageBoxW`` " -"function so that it supports default parameters and named arguments. The C " -"declaration from the windows header file is this::" -msgstr "" - -#: ../../library/ctypes.rst:1925 -msgid "" -"WINUSERAPI int WINAPI\n" -"MessageBoxW(\n" -" HWND hWnd,\n" -" LPCWSTR lpText,\n" -" LPCWSTR lpCaption,\n" -" UINT uType);" -msgstr "" -"WINUSERAPI int WINAPI\n" -"MessageBoxW(\n" -" HWND hWnd,\n" -" LPCWSTR lpText,\n" -" LPCWSTR lpCaption,\n" -" UINT uType);" - -#: ../../library/ctypes.rst:1932 ../../library/ctypes.rst:1955 -msgid "Here is the wrapping with :mod:`ctypes`::" -msgstr "" - -#: ../../library/ctypes.rst:1934 -msgid "" -">>> from ctypes import c_int, WINFUNCTYPE, windll\n" -">>> from ctypes.wintypes import HWND, LPCWSTR, UINT\n" -">>> prototype = WINFUNCTYPE(c_int, HWND, LPCWSTR, LPCWSTR, UINT)\n" -">>> paramflags = (1, \"hwnd\", 0), (1, \"text\", \"Hi\"), (1, \"caption\", " -"\"Hello from ctypes\"), (1, \"flags\", 0)\n" -">>> MessageBox = prototype((\"MessageBoxW\", windll.user32), paramflags)" -msgstr "" -">>> from ctypes import c_int, WINFUNCTYPE, windll\n" -">>> from ctypes.wintypes import HWND, LPCWSTR, UINT\n" -">>> prototype = WINFUNCTYPE(c_int, HWND, LPCWSTR, LPCWSTR, UINT)\n" -">>> paramflags = (1, \"hwnd\", 0), (1, \"text\", \"Hi\"), (1, \"caption\", " -"\"Hello from ctypes\"), (1, \"flags\", 0)\n" -">>> MessageBox = prototype((\"MessageBoxW\", windll.user32), paramflags)" - -#: ../../library/ctypes.rst:1940 -msgid "The ``MessageBox`` foreign function can now be called in these ways::" -msgstr "" - -#: ../../library/ctypes.rst:1942 -msgid "" -">>> MessageBox()\n" -">>> MessageBox(text=\"Spam, spam, spam\")\n" -">>> MessageBox(flags=2, text=\"foo bar\")" -msgstr "" -">>> MessageBox()\n" -">>> MessageBox(text=\"Spam, spam, spam\")\n" -">>> MessageBox(flags=2, text=\"foo bar\")" - -#: ../../library/ctypes.rst:1946 -msgid "" -"A second example demonstrates output parameters. The win32 " -"``GetWindowRect`` function retrieves the dimensions of a specified window by " -"copying them into ``RECT`` structure that the caller has to supply. Here is " -"the C declaration::" -msgstr "" - -#: ../../library/ctypes.rst:1950 -msgid "" -"WINUSERAPI BOOL WINAPI\n" -"GetWindowRect(\n" -" HWND hWnd,\n" -" LPRECT lpRect);" -msgstr "" -"WINUSERAPI BOOL WINAPI\n" -"GetWindowRect(\n" -" HWND hWnd,\n" -" LPRECT lpRect);" - -#: ../../library/ctypes.rst:1957 -msgid "" -">>> from ctypes import POINTER, WINFUNCTYPE, windll, WinError\n" -">>> from ctypes.wintypes import BOOL, HWND, RECT\n" -">>> prototype = WINFUNCTYPE(BOOL, HWND, POINTER(RECT))\n" -">>> paramflags = (1, \"hwnd\"), (2, \"lprect\")\n" -">>> GetWindowRect = prototype((\"GetWindowRect\", windll.user32), " -"paramflags)\n" -">>>" -msgstr "" -">>> from ctypes import POINTER, WINFUNCTYPE, windll, WinError\n" -">>> from ctypes.wintypes import BOOL, HWND, RECT\n" -">>> prototype = WINFUNCTYPE(BOOL, HWND, POINTER(RECT))\n" -">>> paramflags = (1, \"hwnd\"), (2, \"lprect\")\n" -">>> GetWindowRect = prototype((\"GetWindowRect\", windll.user32), " -"paramflags)\n" -">>>" - -#: ../../library/ctypes.rst:1964 -msgid "" -"Functions with output parameters will automatically return the output " -"parameter value if there is a single one, or a tuple containing the output " -"parameter values when there are more than one, so the GetWindowRect function " -"now returns a RECT instance, when called." -msgstr "" - -#: ../../library/ctypes.rst:1969 -msgid "" -"Output parameters can be combined with the :attr:`~_CFuncPtr.errcheck` " -"protocol to do further output processing and error checking. The win32 " -"``GetWindowRect`` api function returns a ``BOOL`` to signal success or " -"failure, so this function could do the error checking, and raises an " -"exception when the api call failed::" -msgstr "" - -#: ../../library/ctypes.rst:1974 -msgid "" -">>> def errcheck(result, func, args):\n" -"... if not result:\n" -"... raise WinError()\n" -"... return args\n" -"...\n" -">>> GetWindowRect.errcheck = errcheck\n" -">>>" -msgstr "" -">>> def errcheck(result, func, args):\n" -"... if not result:\n" -"... raise WinError()\n" -"... return args\n" -"...\n" -">>> GetWindowRect.errcheck = errcheck\n" -">>>" - -#: ../../library/ctypes.rst:1982 -msgid "" -"If the :attr:`~_CFuncPtr.errcheck` function returns the argument tuple it " -"receives unchanged, :mod:`ctypes` continues the normal processing it does on " -"the output parameters. If you want to return a tuple of window coordinates " -"instead of a ``RECT`` instance, you can retrieve the fields in the function " -"and return them instead, the normal processing will no longer take place::" -msgstr "" - -#: ../../library/ctypes.rst:1988 -msgid "" -">>> def errcheck(result, func, args):\n" -"... if not result:\n" -"... raise WinError()\n" -"... rc = args[1]\n" -"... return rc.left, rc.top, rc.bottom, rc.right\n" -"...\n" -">>> GetWindowRect.errcheck = errcheck\n" -">>>" -msgstr "" -">>> def errcheck(result, func, args):\n" -"... if not result:\n" -"... raise WinError()\n" -"... rc = args[1]\n" -"... return rc.left, rc.top, rc.bottom, rc.right\n" -"...\n" -">>> GetWindowRect.errcheck = errcheck\n" -">>>" - -#: ../../library/ctypes.rst:2001 -msgid "Utility functions" -msgstr "" - -#: ../../library/ctypes.rst:2005 -msgid "" -"Returns the address of the memory buffer as integer. *obj* must be an " -"instance of a ctypes type." -msgstr "" - -#: ../../library/ctypes.rst:2008 -msgid "" -"Raises an :ref:`auditing event ` ``ctypes.addressof`` with " -"argument ``obj``." -msgstr "" -"引發一個附帶引數 ``obj`` 的\\ :ref:`稽核事件 ` ``ctypes." -"addressof``。" - -#: ../../library/ctypes.rst:2013 -msgid "" -"Returns the alignment requirements of a ctypes type. *obj_or_type* must be a " -"ctypes type or instance." -msgstr "" - -#: ../../library/ctypes.rst:2019 -msgid "" -"Returns a light-weight pointer to *obj*, which must be an instance of a " -"ctypes type. *offset* defaults to zero, and must be an integer that will be " -"added to the internal pointer value." -msgstr "" - -#: ../../library/ctypes.rst:2023 -msgid "``byref(obj, offset)`` corresponds to this C code::" -msgstr "" - -#: ../../library/ctypes.rst:2025 -msgid "(((char *)&obj) + offset)" -msgstr "(((char *)&obj) + offset)" - -#: ../../library/ctypes.rst:2027 -msgid "" -"The returned object can only be used as a foreign function call parameter. " -"It behaves similar to ``pointer(obj)``, but the construction is a lot faster." -msgstr "" - -#: ../../library/ctypes.rst:2033 -msgid "" -"Copies a COM pointer from *src* to *dst* and returns the Windows specific :c:" -"type:`!HRESULT` value." -msgstr "" - -#: ../../library/ctypes.rst:2036 -msgid "" -"If *src* is not ``NULL``, its ``AddRef`` method is called, incrementing the " -"reference count." -msgstr "" - -#: ../../library/ctypes.rst:2039 -msgid "" -"In contrast, the reference count of *dst* will not be decremented before " -"assigning the new value. Unless *dst* is ``NULL``, the caller is responsible " -"for decrementing the reference count by calling its ``Release`` method when " -"necessary." -msgstr "" - -#: ../../library/ctypes.rst:2051 -msgid "" -"This function is similar to the cast operator in C. It returns a new " -"instance of *type* which points to the same memory block as *obj*. *type* " -"must be a pointer type, and *obj* must be an object that can be interpreted " -"as a pointer." -msgstr "" - -#: ../../library/ctypes.rst:2060 -msgid "" -"This function creates a mutable character buffer. The returned object is a " -"ctypes array of :class:`c_char`." -msgstr "" - -#: ../../library/ctypes.rst:2063 -msgid "" -"If *size* is given (and not ``None``), it must be an :class:`int`. It " -"specifies the size of the returned array." -msgstr "" - -#: ../../library/ctypes.rst:2066 -msgid "" -"If the *init* argument is given, it must be :class:`bytes`. It is used to " -"initialize the array items. Bytes not initialized this way are set to zero " -"(NUL)." -msgstr "" - -#: ../../library/ctypes.rst:2070 -msgid "" -"If *size* is not given (or if it is ``None``), the buffer is made one " -"element larger than *init*, effectively adding a NUL terminator." -msgstr "" - -#: ../../library/ctypes.rst:2073 -msgid "" -"If both arguments are given, *size* must not be less than ``len(init)``." -msgstr "如果兩個引數皆有提供，*size* 不得小於 ``len(init)``。" - -#: ../../library/ctypes.rst:2077 -msgid "" -"If *size* is equal to ``len(init)``, a NUL terminator is not added. Do not " -"treat such a buffer as a C string." -msgstr "" - -#: ../../library/ctypes.rst:2080 -msgid "For example::" -msgstr "舉例來說： ::" - -#: ../../library/ctypes.rst:2082 -msgid "" -">>> bytes(create_string_buffer(2))\n" -"b'\\x00\\x00'\n" -">>> bytes(create_string_buffer(b'ab'))\n" -"b'ab\\x00'\n" -">>> bytes(create_string_buffer(b'ab', 2))\n" -"b'ab'\n" -">>> bytes(create_string_buffer(b'ab', 4))\n" -"b'ab\\x00\\x00'\n" -">>> bytes(create_string_buffer(b'abcdef', 2))\n" -"Traceback (most recent call last):\n" -" ...\n" -"ValueError: byte string too long" -msgstr "" -">>> bytes(create_string_buffer(2))\n" -"b'\\x00\\x00'\n" -">>> bytes(create_string_buffer(b'ab'))\n" -"b'ab\\x00'\n" -">>> bytes(create_string_buffer(b'ab', 2))\n" -"b'ab'\n" -">>> bytes(create_string_buffer(b'ab', 4))\n" -"b'ab\\x00\\x00'\n" -">>> bytes(create_string_buffer(b'abcdef', 2))\n" -"Traceback (most recent call last):\n" -" ...\n" -"ValueError: byte string too long" - -#: ../../library/ctypes.rst:2095 -msgid "" -"Raises an :ref:`auditing event ` ``ctypes.create_string_buffer`` " -"with arguments ``init``, ``size``." -msgstr "" -"引發一個附帶引數 ``init`` 與 ``size`` 的\\ :ref:`稽核事件 ` " -"``ctypes.create_string_buffer``。" - -#: ../../library/ctypes.rst:2101 -msgid "" -"This function creates a mutable unicode character buffer. The returned " -"object is a ctypes array of :class:`c_wchar`." -msgstr "" - -#: ../../library/ctypes.rst:2104 -msgid "" -"The function takes the same arguments as :func:`~create_string_buffer` " -"except *init* must be a string and *size* counts :class:`c_wchar`." -msgstr "" - -#: ../../library/ctypes.rst:2107 -msgid "" -"Raises an :ref:`auditing event ` ``ctypes.create_unicode_buffer`` " -"with arguments ``init``, ``size``." -msgstr "" -"引發一個附帶引數 ``init`` 與 ``size`` 的\\ :ref:`稽核事件 ` " -"``ctypes.create_unicode_buffer``。" - -#: ../../library/ctypes.rst:2112 -msgid "" -"This function is a hook which allows implementing in-process COM servers " -"with ctypes. It is called from the DllCanUnloadNow function that the " -"_ctypes extension dll exports." -msgstr "" - -#: ../../library/ctypes.rst:2121 -msgid "" -"This function is a hook which allows implementing in-process COM servers " -"with ctypes. It is called from the DllGetClassObject function that the " -"``_ctypes`` extension dll exports." -msgstr "" - -#: ../../library/ctypes.rst:2131 -msgid "" -"Try to find a library and return a pathname. *name* is the library name " -"without any prefix like ``lib``, suffix like ``.so``, ``.dylib`` or version " -"number (this is the form used for the posix linker option :option:`!-l`). " -"If no library can be found, returns ``None``." -msgstr "" - -#: ../../library/ctypes.rst:2138 -msgid "See :ref:`ctypes-finding-shared-libraries` for complete documentation." -msgstr "" - -#: ../../library/ctypes.rst:2144 -msgid "" -"Returns the filename of the VC runtime library used by Python, and by the " -"extension modules. If the name of the library cannot be determined, " -"``None`` is returned." -msgstr "" - -#: ../../library/ctypes.rst:2148 -msgid "" -"If you need to free memory, for example, allocated by an extension module " -"with a call to the ``free(void *)``, it is important that you use the " -"function in the same library that allocated the memory." -msgstr "" - -#: ../../library/ctypes.rst:2158 -msgid "" -"Try to provide a list of paths of the shared libraries loaded into the " -"current process. These paths are not normalized or processed in any way. " -"The function can raise :exc:`OSError` if the underlying platform APIs fail. " -"The exact functionality is system dependent." -msgstr "" - -#: ../../library/ctypes.rst:2163 -msgid "" -"On most platforms, the first element of the list represents the current " -"executable file. It may be an empty string." -msgstr "" - -#: ../../library/ctypes.rst:2171 -msgid "" -"Returns a textual description of the error code *code*. If no error code is " -"specified, the last error code is used by calling the Windows API function :" -"func:`GetLastError`." -msgstr "" - -#: ../../library/ctypes.rst:2180 -msgid "" -"Returns the last error code set by Windows in the calling thread. This " -"function calls the Windows ``GetLastError()`` function directly, it does not " -"return the ctypes-private copy of the error code." -msgstr "" - -#: ../../library/ctypes.rst:2189 -msgid "" -"Returns the current value of the ctypes-private copy of the system :data:" -"`errno` variable in the calling thread." -msgstr "" - -#: ../../library/ctypes.rst:2192 -msgid "" -"Raises an :ref:`auditing event ` ``ctypes.get_errno`` with no " -"arguments." -msgstr "" -"引發一個不附帶引數的\\ :ref:`稽核事件 ` ``ctypes.get_errno``。" - -#: ../../library/ctypes.rst:2196 -msgid "" -"Returns the current value of the ctypes-private copy of the system :data:`!" -"LastError` variable in the calling thread." -msgstr "" - -#: ../../library/ctypes.rst:2201 -msgid "" -"Raises an :ref:`auditing event ` ``ctypes.get_last_error`` with no " -"arguments." -msgstr "" -"引發一個不附帶引數的\\ :ref:`稽核事件 ` ``ctypes.get_last_error``。" - -#: ../../library/ctypes.rst:2206 -msgid "" -"Same as the standard C memmove library function: copies *count* bytes from " -"*src* to *dst*. *dst* and *src* must be integers or ctypes instances that " -"can be converted to pointers." -msgstr "" - -#: ../../library/ctypes.rst:2213 -msgid "" -"Same as the standard C memset library function: fills the memory block at " -"address *dst* with *count* bytes of value *c*. *dst* must be an integer " -"specifying an address, or a ctypes instance." -msgstr "" - -#: ../../library/ctypes.rst:2220 -msgid "" -"Create or return a ctypes pointer type. Pointer types are cached and reused " -"internally, so calling this function repeatedly is cheap. *type* must be a " -"ctypes type." -msgstr "" - -#: ../../library/ctypes.rst:2226 -msgid "" -"The resulting pointer type is cached in the ``__pointer_type__`` attribute " -"of *type*. It is possible to set this attribute before the first call to " -"``POINTER`` in order to set a custom pointer type. However, doing this is " -"discouraged: manually creating a suitable pointer type is difficult without " -"relying on implementation details that may change in future Python versions." -msgstr "" - -#: ../../library/ctypes.rst:2237 -msgid "" -"Create a new pointer instance, pointing to *obj*. The returned object is of " -"the type ``POINTER(type(obj))``." -msgstr "" - -#: ../../library/ctypes.rst:2240 -msgid "" -"Note: If you just want to pass a pointer to an object to a foreign function " -"call, you should use ``byref(obj)`` which is much faster." -msgstr "" - -#: ../../library/ctypes.rst:2246 -msgid "" -"This function resizes the internal memory buffer of *obj*, which must be an " -"instance of a ctypes type. It is not possible to make the buffer smaller " -"than the native size of the objects type, as given by ``sizeof(type(obj))``, " -"but it is possible to enlarge the buffer." -msgstr "" - -#: ../../library/ctypes.rst:2254 -msgid "" -"Set the current value of the ctypes-private copy of the system :data:`errno` " -"variable in the calling thread to *value* and return the previous value." -msgstr "" - -#: ../../library/ctypes.rst:2257 -msgid "" -"Raises an :ref:`auditing event ` ``ctypes.set_errno`` with " -"argument ``errno``." -msgstr "" -"引發一個附帶引數 ``errno`` 的\\ :ref:`稽核事件 ` ``ctypes." -"set_errno``。" - -#: ../../library/ctypes.rst:2262 -msgid "" -"Sets the current value of the ctypes-private copy of the system :data:`!" -"LastError` variable in the calling thread to *value* and return the previous " -"value." -msgstr "" - -#: ../../library/ctypes.rst:2268 -msgid "" -"Raises an :ref:`auditing event ` ``ctypes.set_last_error`` with " -"argument ``error``." -msgstr "" -"引發一個附帶引數 ``error`` 的\\ :ref:`稽核事件 ` ``ctypes." -"set_last_error``。" - -#: ../../library/ctypes.rst:2273 -msgid "" -"Returns the size in bytes of a ctypes type or instance memory buffer. Does " -"the same as the C ``sizeof`` operator." -msgstr "" - -#: ../../library/ctypes.rst:2279 -msgid "" -"Return the byte string at *void \\*ptr*. If *size* is specified, it is used " -"as size, otherwise the string is assumed to be zero-terminated." -msgstr "" - -#: ../../library/ctypes.rst:2283 -msgid "" -"Raises an :ref:`auditing event ` ``ctypes.string_at`` with " -"arguments ``ptr``, ``size``." -msgstr "" -"引發一個附帶引數 ``ptr``、``size`` 的\\ :ref:`稽核事件 ` ``ctypes." -"string_at``。" - -#: ../../library/ctypes.rst:2288 -msgid "" -"Creates an instance of :exc:`OSError`. If *code* is not specified, :func:" -"`GetLastError` is called to determine the error code. If *descr* is not " -"specified, :func:`FormatError` is called to get a textual description of the " -"error." -msgstr "" - -#: ../../library/ctypes.rst:2295 -msgid "" -"An instance of :exc:`WindowsError` used to be created, which is now an alias " -"of :exc:`OSError`." -msgstr "" - -#: ../../library/ctypes.rst:2302 -msgid "" -"Return the wide-character string at *void \\*ptr*. If *size* is specified, " -"it is used as the number of characters of the string, otherwise the string " -"is assumed to be zero-terminated." -msgstr "" - -#: ../../library/ctypes.rst:2307 -msgid "" -"Raises an :ref:`auditing event ` ``ctypes.wstring_at`` with " -"arguments ``ptr``, ``size``." -msgstr "" -"引發一個附帶引數 ``ptr``、``size`` 的\\ :ref:`稽核事件 ` ``ctypes." -"wstring_at``。" - -#: ../../library/ctypes.rst:2312 -msgid "" -"Return a :class:`memoryview` object of length *size* that references memory " -"starting at *void \\*ptr*." -msgstr "" - -#: ../../library/ctypes.rst:2315 -msgid "" -"If *readonly* is true, the returned :class:`!memoryview` object can not be " -"used to modify the underlying memory. (Changes made by other means will " -"still be reflected in the returned object.)" -msgstr "" - -#: ../../library/ctypes.rst:2320 -msgid "" -"This function is similar to :func:`string_at` with the key difference of not " -"making a copy of the specified memory. It is a semantically equivalent (but " -"more efficient) alternative to ``memoryview((c_byte * size)." -"from_address(ptr))``. (While :meth:`~_CData.from_address` only takes " -"integers, *ptr* can also be given as a :class:`ctypes.POINTER` or a :func:" -"`~ctypes.byref` object.)" -msgstr "" - -#: ../../library/ctypes.rst:2327 -msgid "" -"Raises an :ref:`auditing event ` ``ctypes.memoryview_at`` with " -"arguments ``address``, ``size``, ``readonly``." -msgstr "" -"引發一個附帶引數 ``address``、``size`` 與 ``readonly`` 的\\ :ref:`稽核事件 " -"` ``ctypes.memoryview_at``。" - -#: ../../library/ctypes.rst:2335 -msgid "Data types" -msgstr "" - -#: ../../library/ctypes.rst:2340 -msgid "" -"This non-public class is the common base class of all ctypes data types. " -"Among other things, all ctypes type instances contain a memory block that " -"hold C compatible data; the address of the memory block is returned by the :" -"func:`addressof` helper function. Another instance variable is exposed as :" -"attr:`_objects`; this contains other Python objects that need to be kept " -"alive in case the memory block contains pointers." -msgstr "" - -#: ../../library/ctypes.rst:2347 -msgid "" -"Common methods of ctypes data types, these are all class methods (to be " -"exact, they are methods of the :term:`metaclass`):" -msgstr "" - -#: ../../library/ctypes.rst:2352 -msgid "" -"This method returns a ctypes instance that shares the buffer of the *source* " -"object. The *source* object must support the writeable buffer interface. " -"The optional *offset* parameter specifies an offset into the source buffer " -"in bytes; the default is zero. If the source buffer is not large enough a :" -"exc:`ValueError` is raised." -msgstr "" - -#: ../../library/ctypes.rst:2358 ../../library/ctypes.rst:2368 -msgid "" -"Raises an :ref:`auditing event ` ``ctypes.cdata/buffer`` with " -"arguments ``pointer``, ``size``, ``offset``." -msgstr "" -"引發一個附帶引數 ``pointer``、``size``、``offset`` 的\\ :ref:`稽核事件 " -"` ``ctypes.cdata/buffer``。" - -#: ../../library/ctypes.rst:2362 -msgid "" -"This method creates a ctypes instance, copying the buffer from the *source* " -"object buffer which must be readable. The optional *offset* parameter " -"specifies an offset into the source buffer in bytes; the default is zero. " -"If the source buffer is not large enough a :exc:`ValueError` is raised." -msgstr "" - -#: ../../library/ctypes.rst:2372 -msgid "" -"This method returns a ctypes type instance using the memory specified by " -"*address* which must be an integer." -msgstr "" - -#: ../../library/ctypes.rst:2375 ../../library/ctypes.rst:2377 -msgid "" -"This method, and others that indirectly call this method, raises an :ref:" -"`auditing event ` ``ctypes.cdata`` with argument ``address``." -msgstr "" - -#: ../../library/ctypes.rst:2383 -msgid "" -"This method adapts *obj* to a ctypes type. It is called with the actual " -"object used in a foreign function call when the type is present in the " -"foreign function's :attr:`~_CFuncPtr.argtypes` tuple; it must return an " -"object that can be used as a function call parameter." -msgstr "" - -#: ../../library/ctypes.rst:2388 -msgid "" -"All ctypes data types have a default implementation of this classmethod that " -"normally returns *obj* if that is an instance of the type. Some types " -"accept other objects as well." -msgstr "" - -#: ../../library/ctypes.rst:2394 -msgid "" -"This method returns a ctypes type instance exported by a shared library. " -"*name* is the name of the symbol that exports the data, *library* is the " -"loaded shared library." -msgstr "" - -#: ../../library/ctypes.rst:2398 -msgid "Common class variables of ctypes data types:" -msgstr "" - -#: ../../library/ctypes.rst:2402 -msgid "" -"The pointer type that was created by calling :func:`POINTER` for " -"corresponding ctypes data type. If a pointer type was not yet created, the " -"attribute is missing." -msgstr "" - -#: ../../library/ctypes.rst:2408 -msgid "Common instance variables of ctypes data types:" -msgstr "" - -#: ../../library/ctypes.rst:2412 -msgid "" -"Sometimes ctypes data instances do not own the memory block they contain, " -"instead they share part of the memory block of a base object. The :attr:" -"`_b_base_` read-only member is the root ctypes object that owns the memory " -"block." -msgstr "" - -#: ../../library/ctypes.rst:2419 -msgid "" -"This read-only variable is true when the ctypes data instance has allocated " -"the memory block itself, false otherwise." -msgstr "" - -#: ../../library/ctypes.rst:2424 -msgid "" -"This member is either ``None`` or a dictionary containing Python objects " -"that need to be kept alive so that the memory block contents is kept valid. " -"This object is only exposed for debugging; never modify the contents of this " -"dictionary." -msgstr "" - -#: ../../library/ctypes.rst:2437 -msgid "" -"This non-public class is the base class of all fundamental ctypes data " -"types. It is mentioned here because it contains the common attributes of the " -"fundamental ctypes data types. :class:`_SimpleCData` is a subclass of :" -"class:`_CData`, so it inherits their methods and attributes. ctypes data " -"types that are not and do not contain pointers can now be pickled." -msgstr "" - -#: ../../library/ctypes.rst:2443 -msgid "Instances have a single attribute:" -msgstr "" - -#: ../../library/ctypes.rst:2447 -msgid "" -"This attribute contains the actual value of the instance. For integer and " -"pointer types, it is an integer, for character types, it is a single " -"character bytes object or string, for character pointer types it is a Python " -"bytes object or string." -msgstr "" - -#: ../../library/ctypes.rst:2452 -msgid "" -"When the ``value`` attribute is retrieved from a ctypes instance, usually a " -"new object is returned each time. :mod:`ctypes` does *not* implement " -"original object return, always a new object is constructed. The same is " -"true for all other ctypes object instances." -msgstr "" - -#: ../../library/ctypes.rst:2458 -msgid "" -"Fundamental data types, when returned as foreign function call results, or, " -"for example, by retrieving structure field members or array items, are " -"transparently converted to native Python types. In other words, if a " -"foreign function has a :attr:`~_CFuncPtr.restype` of :class:`c_char_p`, you " -"will always receive a Python bytes object, *not* a :class:`c_char_p` " -"instance." -msgstr "" - -#: ../../library/ctypes.rst:2466 -msgid "" -"Subclasses of fundamental data types do *not* inherit this behavior. So, if " -"a foreign functions :attr:`!restype` is a subclass of :class:`c_void_p`, you " -"will receive an instance of this subclass from the function call. Of course, " -"you can get the value of the pointer by accessing the ``value`` attribute." -msgstr "" - -#: ../../library/ctypes.rst:2471 -msgid "These are the fundamental ctypes data types:" -msgstr "" - -#: ../../library/ctypes.rst:2475 -msgid "" -"Represents the C :c:expr:`signed char` datatype, and interprets the value as " -"small integer. The constructor accepts an optional integer initializer; no " -"overflow checking is done." -msgstr "" - -#: ../../library/ctypes.rst:2482 -msgid "" -"Represents the C :c:expr:`char` datatype, and interprets the value as a " -"single character. The constructor accepts an optional string initializer, " -"the length of the string must be exactly one character." -msgstr "" - -#: ../../library/ctypes.rst:2489 -msgid "" -"Represents the C :c:expr:`char *` datatype when it points to a zero-" -"terminated string. For a general character pointer that may also point to " -"binary data, ``POINTER(c_char)`` must be used. The constructor accepts an " -"integer address, or a bytes object." -msgstr "" - -#: ../../library/ctypes.rst:2497 -msgid "" -"Represents the C :c:expr:`double` datatype. The constructor accepts an " -"optional float initializer." -msgstr "" - -#: ../../library/ctypes.rst:2503 -msgid "" -"Represents the C :c:expr:`long double` datatype. The constructor accepts an " -"optional float initializer. On platforms where ``sizeof(long double) == " -"sizeof(double)`` it is an alias to :class:`c_double`." -msgstr "" - -#: ../../library/ctypes.rst:2509 -msgid "" -"Represents the C :c:expr:`float` datatype. The constructor accepts an " -"optional float initializer." -msgstr "" - -#: ../../library/ctypes.rst:2515 -msgid "" -"Represents the C :c:expr:`double complex` datatype, if available. The " -"constructor accepts an optional :class:`complex` initializer." -msgstr "" - -#: ../../library/ctypes.rst:2523 -msgid "" -"Represents the C :c:expr:`float complex` datatype, if available. The " -"constructor accepts an optional :class:`complex` initializer." -msgstr "" - -#: ../../library/ctypes.rst:2531 -msgid "" -"Represents the C :c:expr:`long double complex` datatype, if available. The " -"constructor accepts an optional :class:`complex` initializer." -msgstr "" - -#: ../../library/ctypes.rst:2539 -msgid "" -"Represents the C :c:expr:`signed int` datatype. The constructor accepts an " -"optional integer initializer; no overflow checking is done. On platforms " -"where ``sizeof(int) == sizeof(long)`` it is an alias to :class:`c_long`." -msgstr "" - -#: ../../library/ctypes.rst:2546 -msgid "" -"Represents the C 8-bit :c:expr:`signed int` datatype. It is an alias for :" -"class:`c_byte`." -msgstr "" - -#: ../../library/ctypes.rst:2552 -msgid "" -"Represents the C 16-bit :c:expr:`signed int` datatype. Usually an alias " -"for :class:`c_short`." -msgstr "" - -#: ../../library/ctypes.rst:2558 -msgid "" -"Represents the C 32-bit :c:expr:`signed int` datatype. Usually an alias " -"for :class:`c_int`." -msgstr "" - -#: ../../library/ctypes.rst:2564 -msgid "" -"Represents the C 64-bit :c:expr:`signed int` datatype. Usually an alias " -"for :class:`c_longlong`." -msgstr "" - -#: ../../library/ctypes.rst:2570 -msgid "" -"Represents the C :c:expr:`signed long` datatype. The constructor accepts an " -"optional integer initializer; no overflow checking is done." -msgstr "" - -#: ../../library/ctypes.rst:2576 -msgid "" -"Represents the C :c:expr:`signed long long` datatype. The constructor " -"accepts an optional integer initializer; no overflow checking is done." -msgstr "" - -#: ../../library/ctypes.rst:2582 -msgid "" -"Represents the C :c:expr:`signed short` datatype. The constructor accepts " -"an optional integer initializer; no overflow checking is done." -msgstr "" - -#: ../../library/ctypes.rst:2588 -msgid "Represents the C :c:type:`size_t` datatype." -msgstr "" - -#: ../../library/ctypes.rst:2593 -msgid "Represents the C :c:type:`ssize_t` datatype." -msgstr "" - -#: ../../library/ctypes.rst:2600 -msgid "Represents the C :c:type:`time_t` datatype." -msgstr "" - -#: ../../library/ctypes.rst:2607 -msgid "" -"Represents the C :c:expr:`unsigned char` datatype, it interprets the value " -"as small integer. The constructor accepts an optional integer initializer; " -"no overflow checking is done." -msgstr "" - -#: ../../library/ctypes.rst:2614 -msgid "" -"Represents the C :c:expr:`unsigned int` datatype. The constructor accepts " -"an optional integer initializer; no overflow checking is done. On platforms " -"where ``sizeof(int) == sizeof(long)`` it is an alias for :class:`c_ulong`." -msgstr "" - -#: ../../library/ctypes.rst:2621 -msgid "" -"Represents the C 8-bit :c:expr:`unsigned int` datatype. It is an alias for :" -"class:`c_ubyte`." -msgstr "" - -#: ../../library/ctypes.rst:2627 -msgid "" -"Represents the C 16-bit :c:expr:`unsigned int` datatype. Usually an alias " -"for :class:`c_ushort`." -msgstr "" - -#: ../../library/ctypes.rst:2633 -msgid "" -"Represents the C 32-bit :c:expr:`unsigned int` datatype. Usually an alias " -"for :class:`c_uint`." -msgstr "" - -#: ../../library/ctypes.rst:2639 -msgid "" -"Represents the C 64-bit :c:expr:`unsigned int` datatype. Usually an alias " -"for :class:`c_ulonglong`." -msgstr "" - -#: ../../library/ctypes.rst:2645 -msgid "" -"Represents the C :c:expr:`unsigned long` datatype. The constructor accepts " -"an optional integer initializer; no overflow checking is done." -msgstr "" - -#: ../../library/ctypes.rst:2651 -msgid "" -"Represents the C :c:expr:`unsigned long long` datatype. The constructor " -"accepts an optional integer initializer; no overflow checking is done." -msgstr "" - -#: ../../library/ctypes.rst:2657 -msgid "" -"Represents the C :c:expr:`unsigned short` datatype. The constructor accepts " -"an optional integer initializer; no overflow checking is done." -msgstr "" - -#: ../../library/ctypes.rst:2663 -msgid "" -"Represents the C :c:expr:`void *` type. The value is represented as " -"integer. The constructor accepts an optional integer initializer." -msgstr "" - -#: ../../library/ctypes.rst:2669 -msgid "" -"Represents the C :c:type:`wchar_t` datatype, and interprets the value as a " -"single character unicode string. The constructor accepts an optional string " -"initializer, the length of the string must be exactly one character." -msgstr "" - -#: ../../library/ctypes.rst:2676 -msgid "" -"Represents the C :c:expr:`wchar_t *` datatype, which must be a pointer to a " -"zero-terminated wide character string. The constructor accepts an integer " -"address, or a string." -msgstr "" - -#: ../../library/ctypes.rst:2683 -msgid "" -"Represent the C :c:expr:`bool` datatype (more accurately, :c:expr:`_Bool` " -"from C99). Its value can be ``True`` or ``False``, and the constructor " -"accepts any object that has a truth value." -msgstr "" - -#: ../../library/ctypes.rst:2690 -msgid "" -"Represents a :c:type:`!HRESULT` value, which contains success or error " -"information for a function or method call." -msgstr "" - -#: ../../library/ctypes.rst:2698 -msgid "" -"Represents the C :c:expr:`PyObject *` datatype. Calling this without an " -"argument creates a ``NULL`` :c:expr:`PyObject *` pointer." -msgstr "" - -#: ../../library/ctypes.rst:2701 -msgid ":class:`!py_object` is now a :term:`generic type`." -msgstr "" - -#: ../../library/ctypes.rst:2704 -msgid "" -"The :mod:`!ctypes.wintypes` module provides quite some other Windows " -"specific data types, for example :c:type:`!HWND`, :c:type:`!WPARAM`, or :c:" -"type:`!DWORD`. Some useful structures like :c:type:`!MSG` or :c:type:`!RECT` " -"are also defined." -msgstr "" - -#: ../../library/ctypes.rst:2712 -msgid "Structured data types" -msgstr "" - -#: ../../library/ctypes.rst:2717 -msgid "Abstract base class for unions in native byte order." -msgstr "" - -#: ../../library/ctypes.rst:2719 -msgid "" -"Unions share common attributes and behavior with structures; see :class:" -"`Structure` documentation for details." -msgstr "" - -#: ../../library/ctypes.rst:2724 -msgid "Abstract base class for unions in *big endian* byte order." -msgstr "" - -#: ../../library/ctypes.rst:2730 -msgid "Abstract base class for unions in *little endian* byte order." -msgstr "" - -#: ../../library/ctypes.rst:2736 -msgid "Abstract base class for structures in *big endian* byte order." -msgstr "" - -#: ../../library/ctypes.rst:2741 -msgid "Abstract base class for structures in *little endian* byte order." -msgstr "" - -#: ../../library/ctypes.rst:2743 -msgid "" -"Structures and unions with non-native byte order cannot contain pointer type " -"fields, or any other data types containing pointer type fields." -msgstr "" - -#: ../../library/ctypes.rst:2749 -msgid "Abstract base class for structures in *native* byte order." -msgstr "" - -#: ../../library/ctypes.rst:2751 -msgid "" -"Concrete structure and union types must be created by subclassing one of " -"these types, and at least define a :attr:`_fields_` class variable. :mod:" -"`ctypes` will create :term:`descriptor`\\s which allow reading and writing " -"the fields by direct attribute accesses. These are the" -msgstr "" - -#: ../../library/ctypes.rst:2759 -msgid "" -"A sequence defining the structure fields. The items must be 2-tuples or 3-" -"tuples. The first item is the name of the field, the second item specifies " -"the type of the field; it can be any ctypes data type." -msgstr "" - -#: ../../library/ctypes.rst:2763 -msgid "" -"For integer type fields like :class:`c_int`, a third optional item can be " -"given. It must be a small positive integer defining the bit width of the " -"field." -msgstr "" - -#: ../../library/ctypes.rst:2767 -msgid "" -"Field names must be unique within one structure or union. This is not " -"checked, only one field can be accessed when names are repeated." -msgstr "" - -#: ../../library/ctypes.rst:2770 -msgid "" -"It is possible to define the :attr:`_fields_` class variable *after* the " -"class statement that defines the Structure subclass, this allows creating " -"data types that directly or indirectly reference themselves::" -msgstr "" - -#: ../../library/ctypes.rst:2774 -msgid "" -"class List(Structure):\n" -" pass\n" -"List._fields_ = [(\"pnext\", POINTER(List)),\n" -" ...\n" -" ]" -msgstr "" -"class List(Structure):\n" -" pass\n" -"List._fields_ = [(\"pnext\", POINTER(List)),\n" -" ...\n" -" ]" - -#: ../../library/ctypes.rst:2780 -msgid "" -"The :attr:`!_fields_` class variable can only be set once. Later assignments " -"will raise an :exc:`AttributeError`." -msgstr "" - -#: ../../library/ctypes.rst:2783 -msgid "" -"Additionally, the :attr:`!_fields_` class variable must be defined before " -"the structure or union type is first used: an instance or subclass is " -"created, :func:`sizeof` is called on it, and so on. Later assignments to :" -"attr:`!_fields_` will raise an :exc:`AttributeError`. If :attr:`!_fields_` " -"has not been set before such use, the structure or union will have no own " -"fields, as if :attr:`!_fields_` was empty." -msgstr "" - -#: ../../library/ctypes.rst:2791 -msgid "" -"Sub-subclasses of structure types inherit the fields of the base class plus " -"the :attr:`_fields_` defined in the sub-subclass, if any." -msgstr "" - -#: ../../library/ctypes.rst:2797 -msgid "" -"An optional small integer that allows overriding the alignment of structure " -"fields in the instance." -msgstr "" - -#: ../../library/ctypes.rst:2800 -msgid "" -"This is only implemented for the MSVC-compatible memory layout (see :attr:" -"`_layout_`)." -msgstr "" - -#: ../../library/ctypes.rst:2803 -msgid "" -"Setting :attr:`!_pack_` to 0 is the same as not setting it at all. " -"Otherwise, the value must be a positive power of two. The effect is " -"equivalent to ``#pragma pack(N)`` in C, except :mod:`ctypes` may allow " -"larger *n* than what the compiler accepts." -msgstr "" - -#: ../../library/ctypes.rst:2808 -msgid "" -":attr:`!_pack_` must already be defined when :attr:`_fields_` is assigned, " -"otherwise it will have no effect." -msgstr "" - -#: ../../library/ctypes.rst:2813 -msgid "" -"For historical reasons, if :attr:`!_pack_` is non-zero, the MSVC-compatible " -"layout will be used by default. On non-Windows platforms, this default is " -"deprecated and is slated to become an error in Python 3.19. If it is " -"intended, set :attr:`~Structure._layout_` to ``'ms'`` explicitly." -msgstr "" - -#: ../../library/ctypes.rst:2822 -msgid "" -"An optional small integer that allows increasing the alignment of the " -"structure when being packed or unpacked to/from memory." -msgstr "" - -#: ../../library/ctypes.rst:2825 -msgid "" -"The value must not be negative. The effect is equivalent to " -"``__attribute__((aligned(N)))`` on GCC or ``#pragma align(N)`` on MSVC, " -"except :mod:`ctypes` may allow values that the compiler would reject." -msgstr "" - -#: ../../library/ctypes.rst:2830 -msgid "" -":attr:`!_align_` can only *increase* a structure's alignment requirements. " -"Setting it to 0 or 1 has no effect." -msgstr "" - -#: ../../library/ctypes.rst:2833 -msgid "" -"Using values that are not powers of two is discouraged and may lead to " -"surprising behavior." -msgstr "" - -#: ../../library/ctypes.rst:2836 -msgid "" -":attr:`!_align_` must already be defined when :attr:`_fields_` is assigned, " -"otherwise it will have no effect." -msgstr "" - -#: ../../library/ctypes.rst:2843 -msgid "" -"An optional string naming the struct/union layout. It can currently be set " -"to:" -msgstr "" - -#: ../../library/ctypes.rst:2846 -msgid "" -"``\"ms\"``: the layout used by the Microsoft compiler (MSVC). On GCC and " -"Clang, this layout can be selected with ``__attribute__((ms_struct))``." -msgstr "" - -#: ../../library/ctypes.rst:2849 -msgid "" -"``\"gcc-sysv\"``: the layout used by GCC with the System V or “SysV-like” " -"data model, as used on Linux and macOS. With this layout, :attr:`~Structure." -"_pack_` must be unset or zero." -msgstr "" - -#: ../../library/ctypes.rst:2853 -msgid "" -"If not set explicitly, ``ctypes`` will use a default that matches the " -"platform conventions. This default may change in future Python releases (for " -"example, when a new platform gains official support, or when a difference " -"between similar platforms is found). Currently the default will be:" -msgstr "" - -#: ../../library/ctypes.rst:2859 -msgid "On Windows: ``\"ms\"``" -msgstr "" - -#: ../../library/ctypes.rst:2860 -msgid "" -"When :attr:`~Structure._pack_` is specified: ``\"ms\"``. (This is " -"deprecated; see :attr:`~Structure._pack_` documentation.)" -msgstr "" - -#: ../../library/ctypes.rst:2862 -msgid "Otherwise: ``\"gcc-sysv\"``" -msgstr "" - -#: ../../library/ctypes.rst:2864 -msgid "" -":attr:`!_layout_` must already be defined when :attr:`~Structure._fields_` " -"is assigned, otherwise it will have no effect." -msgstr "" - -#: ../../library/ctypes.rst:2871 -msgid "" -"An optional sequence that lists the names of unnamed (anonymous) fields. :" -"attr:`_anonymous_` must be already defined when :attr:`_fields_` is " -"assigned, otherwise it will have no effect." -msgstr "" - -#: ../../library/ctypes.rst:2875 -msgid "" -"The fields listed in this variable must be structure or union type fields. :" -"mod:`ctypes` will create descriptors in the structure type that allows " -"accessing the nested fields directly, without the need to create the " -"structure or union field." -msgstr "" - -#: ../../library/ctypes.rst:2880 -msgid "Here is an example type (Windows)::" -msgstr "" - -#: ../../library/ctypes.rst:2882 -msgid "" -"class _U(Union):\n" -" _fields_ = [(\"lptdesc\", POINTER(TYPEDESC)),\n" -" (\"lpadesc\", POINTER(ARRAYDESC)),\n" -" (\"hreftype\", HREFTYPE)]\n" -"\n" -"class TYPEDESC(Structure):\n" -" _anonymous_ = (\"u\",)\n" -" _fields_ = [(\"u\", _U),\n" -" (\"vt\", VARTYPE)]" -msgstr "" -"class _U(Union):\n" -" _fields_ = [(\"lptdesc\", POINTER(TYPEDESC)),\n" -" (\"lpadesc\", POINTER(ARRAYDESC)),\n" -" (\"hreftype\", HREFTYPE)]\n" -"\n" -"class TYPEDESC(Structure):\n" -" _anonymous_ = (\"u\",)\n" -" _fields_ = [(\"u\", _U),\n" -" (\"vt\", VARTYPE)]" - -#: ../../library/ctypes.rst:2893 -msgid "" -"The ``TYPEDESC`` structure describes a COM data type, the ``vt`` field " -"specifies which one of the union fields is valid. Since the ``u`` field is " -"defined as anonymous field, it is now possible to access the members " -"directly off the TYPEDESC instance. ``td.lptdesc`` and ``td.u.lptdesc`` are " -"equivalent, but the former is faster since it does not need to create a " -"temporary union instance::" -msgstr "" - -#: ../../library/ctypes.rst:2900 -msgid "" -"td = TYPEDESC()\n" -"td.vt = VT_PTR\n" -"td.lptdesc = POINTER(some_type)\n" -"td.u.lptdesc = POINTER(some_type)" -msgstr "" -"td = TYPEDESC()\n" -"td.vt = VT_PTR\n" -"td.lptdesc = POINTER(some_type)\n" -"td.u.lptdesc = POINTER(some_type)" - -#: ../../library/ctypes.rst:2905 -msgid "" -"It is possible to define sub-subclasses of structures, they inherit the " -"fields of the base class. If the subclass definition has a separate :attr:" -"`_fields_` variable, the fields specified in this are appended to the fields " -"of the base class." -msgstr "" - -#: ../../library/ctypes.rst:2910 -msgid "" -"Structure and union constructors accept both positional and keyword " -"arguments. Positional arguments are used to initialize member fields in the " -"same order as they are appear in :attr:`_fields_`. Keyword arguments in the " -"constructor are interpreted as attribute assignments, so they will " -"initialize :attr:`_fields_` with the same name, or create new attributes for " -"names not present in :attr:`_fields_`." -msgstr "" - -#: ../../library/ctypes.rst:2920 -msgid "" -"Descriptor for fields of a :class:`Structure` and :class:`Union`. For " -"example::" -msgstr "" - -#: ../../library/ctypes.rst:2923 -msgid "" -">>> class Color(Structure):\n" -"... _fields_ = (\n" -"... ('red', c_uint8),\n" -"... ('green', c_uint8),\n" -"... ('blue', c_uint8),\n" -"... ('intense', c_bool, 1),\n" -"... ('blinking', c_bool, 1),\n" -"... )\n" -"...\n" -">>> Color.red\n" -"\n" -">>> Color.green.type\n" -"\n" -">>> Color.blue.byte_offset\n" -"2\n" -">>> Color.intense\n" -"\n" -">>> Color.blinking.bit_offset\n" -"1" -msgstr "" -">>> class Color(Structure):\n" -"... _fields_ = (\n" -"... ('red', c_uint8),\n" -"... ('green', c_uint8),\n" -"... ('blue', c_uint8),\n" -"... ('intense', c_bool, 1),\n" -"... ('blinking', c_bool, 1),\n" -"... )\n" -"...\n" -">>> Color.red\n" -"\n" -">>> Color.green.type\n" -"\n" -">>> Color.blue.byte_offset\n" -"2\n" -">>> Color.intense\n" -"\n" -">>> Color.blinking.bit_offset\n" -"1" - -#: ../../library/ctypes.rst:2943 -msgid "All attributes are read-only." -msgstr "" - -#: ../../library/ctypes.rst:2945 -msgid "" -":class:`!CField` objects are created via :attr:`~Structure._fields_`; do not " -"instantiate the class directly." -msgstr "" - -#: ../../library/ctypes.rst:2950 -msgid "" -"Previously, descriptors only had ``offset`` and ``size`` attributes and a " -"readable string representation; the :class:`!CField` class was not available " -"directly." -msgstr "" - -#: ../../library/ctypes.rst:2956 -msgid "Name of the field, as a string." -msgstr "" - -#: ../../library/ctypes.rst:2960 -msgid "Type of the field, as a :ref:`ctypes class `." -msgstr "" - -#: ../../library/ctypes.rst:2965 -msgid "Offset of the field, in bytes." -msgstr "" - -#: ../../library/ctypes.rst:2967 -msgid "" -"For bitfields, this is the offset of the underlying byte-aligned *storage " -"unit*; see :attr:`~CField.bit_offset`." -msgstr "" - -#: ../../library/ctypes.rst:2972 -msgid "Size of the field, in bytes." -msgstr "" - -#: ../../library/ctypes.rst:2974 -msgid "" -"For bitfields, this is the size of the underlying *storage unit*. Typically, " -"it has the same size as the bitfield's type." -msgstr "" - -#: ../../library/ctypes.rst:2979 -msgid "For non-bitfields, equivalent to :attr:`~CField.byte_size`." -msgstr "" - -#: ../../library/ctypes.rst:2981 -msgid "" -"For bitfields, this contains a backwards-compatible bit-packed value that " -"combines :attr:`~CField.bit_size` and :attr:`~CField.bit_offset`. Prefer " -"using the explicit attributes instead." -msgstr "" - -#: ../../library/ctypes.rst:2988 -msgid "True if this is a bitfield." -msgstr "" - -#: ../../library/ctypes.rst:2993 -msgid "" -"The location of a bitfield within its *storage unit*, that is, within :attr:" -"`~CField.byte_size` bytes of memory starting at :attr:`~CField.byte_offset`." -msgstr "" - -#: ../../library/ctypes.rst:2997 -msgid "" -"To get the field's value, read the storage unit as an integer, :ref:`shift " -"left ` by :attr:`!bit_offset` and take the :attr:`!bit_size` least " -"significant bits." -msgstr "" - -#: ../../library/ctypes.rst:3001 -msgid "" -"For non-bitfields, :attr:`!bit_offset` is zero and :attr:`!bit_size` is " -"equal to ``byte_size * 8``." -msgstr "" - -#: ../../library/ctypes.rst:3006 -msgid "" -"True if this field is anonymous, that is, it contains nested sub-fields that " -"should be merged into a containing structure or union." -msgstr "" - -#: ../../library/ctypes.rst:3013 -msgid "Arrays and pointers" -msgstr "" - -#: ../../library/ctypes.rst:3017 -msgid "Abstract base class for arrays." -msgstr "" - -#: ../../library/ctypes.rst:3019 -msgid "" -"The recommended way to create concrete array types is by multiplying any :" -"mod:`ctypes` data type with a non-negative integer. Alternatively, you can " -"subclass this type and define :attr:`_length_` and :attr:`_type_` class " -"variables. Array elements can be read and written using standard subscript " -"and slice accesses; for slice reads, the resulting object is *not* itself " -"an :class:`Array`." -msgstr "" - -#: ../../library/ctypes.rst:3029 -msgid "" -"A positive integer specifying the number of elements in the array. Out-of-" -"range subscripts result in an :exc:`IndexError`. Will be returned by :func:" -"`len`." -msgstr "" - -#: ../../library/ctypes.rst:3036 -msgid "Specifies the type of each element in the array." -msgstr "" - -#: ../../library/ctypes.rst:3039 -msgid "" -"Array subclass constructors accept positional arguments, used to initialize " -"the elements in order." -msgstr "" - -#: ../../library/ctypes.rst:3044 -msgid "" -"Create an array. Equivalent to ``type * length``, where *type* is a :mod:" -"`ctypes` data type and *length* an integer." -msgstr "" - -#: ../../library/ctypes.rst:3048 -msgid "" -"This function is :term:`soft deprecated` in favor of multiplication. There " -"are no plans to remove it." -msgstr "" - -#: ../../library/ctypes.rst:3054 -msgid "Private, abstract base class for pointers." -msgstr "" - -#: ../../library/ctypes.rst:3056 -msgid "" -"Concrete pointer types are created by calling :func:`POINTER` with the type " -"that will be pointed to; this is done automatically by :func:`pointer`." -msgstr "" - -#: ../../library/ctypes.rst:3060 -msgid "" -"If a pointer points to an array, its elements can be read and written using " -"standard subscript and slice accesses. Pointer objects have no size, so :" -"func:`len` will raise :exc:`TypeError`. Negative subscripts will read from " -"the memory *before* the pointer (as in C), and out-of-range subscripts will " -"probably crash with an access violation (if you're lucky)." -msgstr "" - -#: ../../library/ctypes.rst:3070 -msgid "Specifies the type pointed to." -msgstr "" - -#: ../../library/ctypes.rst:3074 -msgid "" -"Returns the object to which to pointer points. Assigning to this attribute " -"changes the pointer to point to the assigned object." -msgstr "" - -#: ../../library/ctypes.rst:3081 -msgid "Exceptions" -msgstr "" - -#: ../../library/ctypes.rst:3085 -msgid "" -"This exception is raised when a foreign function call cannot convert one of " -"the passed arguments." -msgstr "" - -#: ../../library/ctypes.rst:3091 -msgid "This exception is raised when a COM method call failed." -msgstr "" - -#: ../../library/ctypes.rst:3095 -msgid "The integer value representing the error code." -msgstr "" - -#: ../../library/ctypes.rst:3099 -msgid "The error message." -msgstr "" - -#: ../../library/ctypes.rst:3103 -msgid "The 5-tuple ``(descr, source, helpfile, helpcontext, progid)``." -msgstr "" - -#: ../../library/ctypes.rst:3105 -msgid "" -"*descr* is the textual description. *source* is the language-dependent " -"``ProgID`` for the class or application that raised the error. *helpfile* " -"is the path of the help file. *helpcontext* is the help context " -"identifier. *progid* is the ``ProgID`` of the interface that defined the " -"error." -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-12-17 00:14+0000\n" +"PO-Revision-Date: 2023-04-26 02:59+0800\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" +"X-Generator: Poedit 3.2.2\n" + +#: ../../library/ctypes.rst:2 +msgid ":mod:`!ctypes` --- A foreign function library for Python" +msgstr ":mod:`!ctypes` --- 用於 Python 的外部函式庫" + +#: ../../library/ctypes.rst:9 +msgid "**Source code:** :source:`Lib/ctypes`" +msgstr "**原始碼：**\\ :source:`Lib/ctypes`" + +#: ../../library/ctypes.rst:13 +msgid "" +":mod:`ctypes` is a foreign function library for Python. It provides C " +"compatible data types, and allows calling functions in DLLs or shared " +"libraries. It can be used to wrap these libraries in pure Python." +msgstr "" + +#: ../../includes/optional-module.rst:1 +msgid "" +"This is an :term:`optional module`. If it is missing from your copy of " +"CPython, look for documentation from your distributor (that is, whoever " +"provided Python to you). If you are the distributor, see :ref:`optional-" +"module-requirements`." +msgstr "" + +#: ../../library/ctypes.rst:23 +msgid "ctypes tutorial" +msgstr "ctypes 教學" + +#: ../../library/ctypes.rst:25 +msgid "" +"Note: The code samples in this tutorial use :mod:`doctest` to make sure that " +"they actually work. Since some code samples behave differently under Linux, " +"Windows, or macOS, they contain doctest directives in comments." +msgstr "" + +#: ../../library/ctypes.rst:29 +msgid "" +"Note: Some code samples reference the ctypes :class:`c_int` type. On " +"platforms where ``sizeof(long) == sizeof(int)`` it is an alias to :class:" +"`c_long`. So, you should not be confused if :class:`c_long` is printed if " +"you would expect :class:`c_int` --- they are actually the same type." +msgstr "" + +#: ../../library/ctypes.rst:37 +msgid "Loading dynamic link libraries" +msgstr "" + +#: ../../library/ctypes.rst:39 +msgid "" +":mod:`ctypes` exports the *cdll*, and on Windows *windll* and *oledll* " +"objects, for loading dynamic link libraries." +msgstr "" + +#: ../../library/ctypes.rst:42 +msgid "" +"You load libraries by accessing them as attributes of these objects. *cdll* " +"loads libraries which export functions using the standard ``cdecl`` calling " +"convention, while *windll* libraries call functions using the ``stdcall`` " +"calling convention. *oledll* also uses the ``stdcall`` calling convention, " +"and assumes the functions return a Windows :c:type:`!HRESULT` error code. " +"The error code is used to automatically raise an :class:`OSError` exception " +"when the function call fails." +msgstr "" + +#: ../../library/ctypes.rst:50 +msgid "" +"Windows errors used to raise :exc:`WindowsError`, which is now an alias of :" +"exc:`OSError`." +msgstr "" + +#: ../../library/ctypes.rst:55 +msgid "" +"Here are some examples for Windows. Note that ``msvcrt`` is the MS standard " +"C library containing most standard C functions, and uses the ``cdecl`` " +"calling convention::" +msgstr "" + +#: ../../library/ctypes.rst:59 +msgid "" +">>> from ctypes import *\n" +">>> print(windll.kernel32)\n" +"\n" +">>> print(cdll.msvcrt)\n" +"\n" +">>> libc = cdll.msvcrt\n" +">>>" +msgstr "" +">>> from ctypes import *\n" +">>> print(windll.kernel32)\n" +"\n" +">>> print(cdll.msvcrt)\n" +"\n" +">>> libc = cdll.msvcrt\n" +">>>" + +#: ../../library/ctypes.rst:67 +msgid "Windows appends the usual ``.dll`` file suffix automatically." +msgstr "" + +#: ../../library/ctypes.rst:70 +msgid "" +"Accessing the standard C library through ``cdll.msvcrt`` will use an " +"outdated version of the library that may be incompatible with the one being " +"used by Python. Where possible, use native Python functionality, or else " +"import and use the ``msvcrt`` module." +msgstr "" + +#: ../../library/ctypes.rst:75 +msgid "" +"On Linux, it is required to specify the filename *including* the extension " +"to load a library, so attribute access can not be used to load libraries. " +"Either the :meth:`~LibraryLoader.LoadLibrary` method of the dll loaders " +"should be used, or you should load the library by creating an instance of " +"CDLL by calling the constructor::" +msgstr "" + +#: ../../library/ctypes.rst:81 +msgid "" +">>> cdll.LoadLibrary(\"libc.so.6\")\n" +"\n" +">>> libc = CDLL(\"libc.so.6\")\n" +">>> libc\n" +"\n" +">>>" +msgstr "" +">>> cdll.LoadLibrary(\"libc.so.6\")\n" +"\n" +">>> libc = CDLL(\"libc.so.6\")\n" +">>> libc\n" +"\n" +">>>" + +#: ../../library/ctypes.rst:94 +msgid "Accessing functions from loaded dlls" +msgstr "" + +#: ../../library/ctypes.rst:96 +msgid "Functions are accessed as attributes of dll objects::" +msgstr "" + +#: ../../library/ctypes.rst:98 +msgid "" +">>> libc.printf\n" +"<_FuncPtr object at 0x...>\n" +">>> print(windll.kernel32.GetModuleHandleA)\n" +"<_FuncPtr object at 0x...>\n" +">>> print(windll.kernel32.MyOwnFunction)\n" +"Traceback (most recent call last):\n" +" File \"\", line 1, in \n" +" File \"ctypes.py\", line 239, in __getattr__\n" +" func = _StdcallFuncPtr(name, self)\n" +"AttributeError: function 'MyOwnFunction' not found\n" +">>>" +msgstr "" +">>> libc.printf\n" +"<_FuncPtr object at 0x...>\n" +">>> print(windll.kernel32.GetModuleHandleA)\n" +"<_FuncPtr object at 0x...>\n" +">>> print(windll.kernel32.MyOwnFunction)\n" +"Traceback (most recent call last):\n" +" File \"\", line 1, in \n" +" File \"ctypes.py\", line 239, in __getattr__\n" +" func = _StdcallFuncPtr(name, self)\n" +"AttributeError: function 'MyOwnFunction' not found\n" +">>>" + +#: ../../library/ctypes.rst:110 +msgid "" +"Note that win32 system dlls like ``kernel32`` and ``user32`` often export " +"ANSI as well as UNICODE versions of a function. The UNICODE version is " +"exported with a ``W`` appended to the name, while the ANSI version is " +"exported with an ``A`` appended to the name. The win32 ``GetModuleHandle`` " +"function, which returns a *module handle* for a given module name, has the " +"following C prototype, and a macro is used to expose one of them as " +"``GetModuleHandle`` depending on whether UNICODE is defined or not::" +msgstr "" + +#: ../../library/ctypes.rst:118 +msgid "" +"/* ANSI version */\n" +"HMODULE GetModuleHandleA(LPCSTR lpModuleName);\n" +"/* UNICODE version */\n" +"HMODULE GetModuleHandleW(LPCWSTR lpModuleName);" +msgstr "" +"/* ANSI 版本 */\n" +"HMODULE GetModuleHandleA(LPCSTR lpModuleName);\n" +"/* UNICODE 版本 */\n" +"HMODULE GetModuleHandleW(LPCWSTR lpModuleName);" + +#: ../../library/ctypes.rst:123 +msgid "" +"*windll* does not try to select one of them by magic, you must access the " +"version you need by specifying ``GetModuleHandleA`` or ``GetModuleHandleW`` " +"explicitly, and then call it with bytes or string objects respectively." +msgstr "" + +#: ../../library/ctypes.rst:127 +msgid "" +"Sometimes, dlls export functions with names which aren't valid Python " +"identifiers, like ``\"??2@YAPAXI@Z\"``. In this case you have to use :func:" +"`getattr` to retrieve the function::" +msgstr "" + +#: ../../library/ctypes.rst:131 +msgid "" +">>> getattr(cdll.msvcrt, \"??2@YAPAXI@Z\")\n" +"<_FuncPtr object at 0x...>\n" +">>>" +msgstr "" +">>> getattr(cdll.msvcrt, \"??2@YAPAXI@Z\")\n" +"<_FuncPtr object at 0x...>\n" +">>>" + +#: ../../library/ctypes.rst:135 +msgid "" +"On Windows, some dlls export functions not by name but by ordinal. These " +"functions can be accessed by indexing the dll object with the ordinal " +"number::" +msgstr "" + +#: ../../library/ctypes.rst:138 +msgid "" +">>> cdll.kernel32[1]\n" +"<_FuncPtr object at 0x...>\n" +">>> cdll.kernel32[0]\n" +"Traceback (most recent call last):\n" +" File \"\", line 1, in \n" +" File \"ctypes.py\", line 310, in __getitem__\n" +" func = _StdcallFuncPtr(name, self)\n" +"AttributeError: function ordinal 0 not found\n" +">>>" +msgstr "" +">>> cdll.kernel32[1]\n" +"<_FuncPtr object at 0x...>\n" +">>> cdll.kernel32[0]\n" +"Traceback (most recent call last):\n" +" File \"\", line 1, in \n" +" File \"ctypes.py\", line 310, in __getitem__\n" +" func = _StdcallFuncPtr(name, self)\n" +"AttributeError: function ordinal 0 not found\n" +">>>" + +#: ../../library/ctypes.rst:152 +msgid "Calling functions" +msgstr "呼叫函式" + +#: ../../library/ctypes.rst:154 +msgid "" +"You can call these functions like any other Python callable. This example " +"uses the ``rand()`` function, which takes no arguments and returns a pseudo-" +"random integer::" +msgstr "" + +#: ../../library/ctypes.rst:157 +msgid "" +">>> print(libc.rand())\n" +"1804289383" +msgstr "" +">>> print(libc.rand())\n" +"1804289383" + +#: ../../library/ctypes.rst:160 +msgid "" +"On Windows, you can call the ``GetModuleHandleA()`` function, which returns " +"a win32 module handle (passing ``None`` as single argument to call it with a " +"``NULL`` pointer)::" +msgstr "" + +#: ../../library/ctypes.rst:163 +msgid "" +">>> print(hex(windll.kernel32.GetModuleHandleA(None)))\n" +"0x1d000000\n" +">>>" +msgstr "" +">>> print(hex(windll.kernel32.GetModuleHandleA(None)))\n" +"0x1d000000\n" +">>>" + +#: ../../library/ctypes.rst:167 +msgid "" +":exc:`ValueError` is raised when you call an ``stdcall`` function with the " +"``cdecl`` calling convention, or vice versa::" +msgstr "" + +#: ../../library/ctypes.rst:170 +msgid "" +">>> cdll.kernel32.GetModuleHandleA(None)\n" +"Traceback (most recent call last):\n" +" File \"\", line 1, in \n" +"ValueError: Procedure probably called with not enough arguments (4 bytes " +"missing)\n" +">>>\n" +"\n" +">>> windll.msvcrt.printf(b\"spam\")\n" +"Traceback (most recent call last):\n" +" File \"\", line 1, in \n" +"ValueError: Procedure probably called with too many arguments (4 bytes in " +"excess)\n" +">>>" +msgstr "" +">>> cdll.kernel32.GetModuleHandleA(None)\n" +"Traceback (most recent call last):\n" +" File \"\", line 1, in \n" +"ValueError: Procedure probably called with not enough arguments (4 bytes " +"missing)\n" +">>>\n" +"\n" +">>> windll.msvcrt.printf(b\"spam\")\n" +"Traceback (most recent call last):\n" +" File \"\", line 1, in \n" +"ValueError: Procedure probably called with too many arguments (4 bytes in " +"excess)\n" +">>>" + +#: ../../library/ctypes.rst:182 +msgid "" +"To find out the correct calling convention you have to look into the C " +"header file or the documentation for the function you want to call." +msgstr "" + +#: ../../library/ctypes.rst:185 +msgid "" +"On Windows, :mod:`ctypes` uses win32 structured exception handling to " +"prevent crashes from general protection faults when functions are called " +"with invalid argument values::" +msgstr "" + +#: ../../library/ctypes.rst:189 +msgid "" +">>> windll.kernel32.GetModuleHandleA(32)\n" +"Traceback (most recent call last):\n" +" File \"\", line 1, in \n" +"OSError: exception: access violation reading 0x00000020\n" +">>>" +msgstr "" +">>> windll.kernel32.GetModuleHandleA(32)\n" +"Traceback (most recent call last):\n" +" File \"\", line 1, in \n" +"OSError: exception: access violation reading 0x00000020\n" +">>>" + +#: ../../library/ctypes.rst:195 +msgid "" +"There are, however, enough ways to crash Python with :mod:`ctypes`, so you " +"should be careful anyway. The :mod:`faulthandler` module can be helpful in " +"debugging crashes (e.g. from segmentation faults produced by erroneous C " +"library calls)." +msgstr "" + +#: ../../library/ctypes.rst:200 +msgid "" +"``None``, integers, bytes objects and (unicode) strings are the only native " +"Python objects that can directly be used as parameters in these function " +"calls. ``None`` is passed as a C ``NULL`` pointer, bytes objects and strings " +"are passed as pointer to the memory block that contains their data (:c:expr:" +"`char *` or :c:expr:`wchar_t *`). Python integers are passed as the " +"platform's default C :c:expr:`int` type, their value is masked to fit into " +"the C type." +msgstr "" + +#: ../../library/ctypes.rst:207 +msgid "" +"Before we move on calling functions with other parameter types, we have to " +"learn more about :mod:`ctypes` data types." +msgstr "" + +#: ../../library/ctypes.rst:214 ../../library/ctypes.rst:2433 +msgid "Fundamental data types" +msgstr "" + +#: ../../library/ctypes.rst:216 +msgid ":mod:`ctypes` defines a number of primitive C compatible data types:" +msgstr "" + +#: ../../library/ctypes.rst:219 ../../library/ctypes.rst:291 +msgid "ctypes type" +msgstr "ctypes 型別" + +#: ../../library/ctypes.rst:219 ../../library/ctypes.rst:291 +msgid "C type" +msgstr "C 型別" + +#: ../../library/ctypes.rst:219 ../../library/ctypes.rst:291 +msgid "Python type" +msgstr "Python 型別" + +#: ../../library/ctypes.rst:221 +msgid ":class:`c_bool`" +msgstr ":class:`c_bool`" + +#: ../../library/ctypes.rst:221 +msgid ":c:expr:`_Bool`" +msgstr ":c:expr:`_Bool`" + +#: ../../library/ctypes.rst:221 +msgid "bool (1)" +msgstr "bool (1)" + +#: ../../library/ctypes.rst:223 +msgid ":class:`c_char`" +msgstr ":class:`c_char`" + +#: ../../library/ctypes.rst:223 ../../library/ctypes.rst:227 +msgid ":c:expr:`char`" +msgstr ":c:expr:`char`" + +#: ../../library/ctypes.rst:223 +msgid "1-character bytes object" +msgstr "" + +#: ../../library/ctypes.rst:225 +msgid ":class:`c_wchar`" +msgstr ":class:`c_wchar`" + +#: ../../library/ctypes.rst:225 +msgid ":c:type:`wchar_t`" +msgstr ":c:type:`wchar_t`" + +#: ../../library/ctypes.rst:225 +msgid "1-character string" +msgstr "" + +#: ../../library/ctypes.rst:227 +msgid ":class:`c_byte`" +msgstr ":class:`c_byte`" + +#: ../../library/ctypes.rst:227 ../../library/ctypes.rst:229 +#: ../../library/ctypes.rst:231 ../../library/ctypes.rst:233 +#: ../../library/ctypes.rst:235 ../../library/ctypes.rst:237 +#: ../../library/ctypes.rst:239 ../../library/ctypes.rst:241 +#: ../../library/ctypes.rst:243 ../../library/ctypes.rst:245 +#: ../../library/ctypes.rst:247 ../../library/ctypes.rst:249 +#: ../../library/ctypes.rst:251 ../../library/ctypes.rst:253 +#: ../../library/ctypes.rst:255 ../../library/ctypes.rst:257 +#: ../../library/ctypes.rst:259 ../../library/ctypes.rst:261 +#: ../../library/ctypes.rst:264 ../../library/ctypes.rst:266 +#: ../../library/ctypes.rst:269 +msgid "int" +msgstr "int" + +#: ../../library/ctypes.rst:229 +msgid ":class:`c_ubyte`" +msgstr ":class:`c_ubyte`" + +#: ../../library/ctypes.rst:229 +msgid ":c:expr:`unsigned char`" +msgstr ":c:expr:`unsigned char`" + +#: ../../library/ctypes.rst:231 +msgid ":class:`c_short`" +msgstr ":class:`c_short`" + +#: ../../library/ctypes.rst:231 +msgid ":c:expr:`short`" +msgstr ":c:expr:`short`" + +#: ../../library/ctypes.rst:233 +msgid ":class:`c_ushort`" +msgstr ":class:`c_ushort`" + +#: ../../library/ctypes.rst:233 +msgid ":c:expr:`unsigned short`" +msgstr ":c:expr:`unsigned short`" + +#: ../../library/ctypes.rst:235 +msgid ":class:`c_int`" +msgstr ":class:`c_int`" + +#: ../../library/ctypes.rst:235 +msgid ":c:expr:`int`" +msgstr ":c:expr:`int`" + +#: ../../library/ctypes.rst:237 +msgid ":class:`c_int8`" +msgstr ":class:`c_int8`" + +#: ../../library/ctypes.rst:237 +msgid ":c:type:`int8_t`" +msgstr ":c:type:`int8_t`" + +#: ../../library/ctypes.rst:239 +msgid ":class:`c_int16`" +msgstr ":class:`c_int16`" + +#: ../../library/ctypes.rst:239 +msgid ":c:type:`int16_t`" +msgstr ":c:type:`int16_t`" + +#: ../../library/ctypes.rst:241 +msgid ":class:`c_int32`" +msgstr ":class:`c_int32`" + +#: ../../library/ctypes.rst:241 +msgid ":c:type:`int32_t`" +msgstr ":c:type:`int32_t`" + +#: ../../library/ctypes.rst:243 +msgid ":class:`c_int64`" +msgstr ":class:`c_int64`" + +#: ../../library/ctypes.rst:243 +msgid ":c:type:`int64_t`" +msgstr ":c:type:`int64_t`" + +#: ../../library/ctypes.rst:245 +msgid ":class:`c_uint`" +msgstr ":class:`c_uint`" + +#: ../../library/ctypes.rst:245 +msgid ":c:expr:`unsigned int`" +msgstr ":c:expr:`unsigned int`" + +#: ../../library/ctypes.rst:247 +msgid ":class:`c_uint8`" +msgstr ":class:`c_uint8`" + +#: ../../library/ctypes.rst:247 +msgid ":c:type:`uint8_t`" +msgstr ":c:type:`uint8_t`" + +#: ../../library/ctypes.rst:249 +msgid ":class:`c_uint16`" +msgstr ":class:`c_uint16`" + +#: ../../library/ctypes.rst:249 +msgid ":c:type:`uint16_t`" +msgstr ":c:type:`uint16_t`" + +#: ../../library/ctypes.rst:251 +msgid ":class:`c_uint32`" +msgstr ":class:`c_uint32`" + +#: ../../library/ctypes.rst:251 +msgid ":c:type:`uint32_t`" +msgstr ":c:type:`uint32_t`" + +#: ../../library/ctypes.rst:253 +msgid ":class:`c_uint64`" +msgstr ":class:`c_uint64`" + +#: ../../library/ctypes.rst:253 +msgid ":c:type:`uint64_t`" +msgstr ":c:type:`uint64_t`" + +#: ../../library/ctypes.rst:255 +msgid ":class:`c_long`" +msgstr ":class:`c_long`" + +#: ../../library/ctypes.rst:255 +msgid ":c:expr:`long`" +msgstr ":c:expr:`long`" + +#: ../../library/ctypes.rst:257 +msgid ":class:`c_ulong`" +msgstr ":class:`c_ulong`" + +#: ../../library/ctypes.rst:257 +msgid ":c:expr:`unsigned long`" +msgstr ":c:expr:`unsigned long`" + +#: ../../library/ctypes.rst:259 +msgid ":class:`c_longlong`" +msgstr ":class:`c_longlong`" + +#: ../../library/ctypes.rst:259 +msgid ":c:expr:`__int64` or :c:expr:`long long`" +msgstr ":c:expr:`__int64` 或 :c:expr:`long long`" + +#: ../../library/ctypes.rst:261 +msgid ":class:`c_ulonglong`" +msgstr ":class:`c_ulonglong`" + +#: ../../library/ctypes.rst:261 +msgid ":c:expr:`unsigned __int64` or :c:expr:`unsigned long long`" +msgstr ":c:expr:`unsigned __int64` 或 :c:expr:`unsigned long long`" + +#: ../../library/ctypes.rst:264 +msgid ":class:`c_size_t`" +msgstr ":class:`c_size_t`" + +#: ../../library/ctypes.rst:264 +msgid ":c:type:`size_t`" +msgstr ":c:type:`size_t`" + +#: ../../library/ctypes.rst:266 +msgid ":class:`c_ssize_t`" +msgstr ":class:`c_ssize_t`" + +#: ../../library/ctypes.rst:266 +msgid ":c:type:`ssize_t` or :c:expr:`Py_ssize_t`" +msgstr ":c:type:`ssize_t` 或 :c:expr:`Py_ssize_t`" + +#: ../../library/ctypes.rst:269 +msgid ":class:`c_time_t`" +msgstr ":class:`c_time_t`" + +#: ../../library/ctypes.rst:269 +msgid ":c:type:`time_t`" +msgstr ":c:type:`time_t`" + +#: ../../library/ctypes.rst:271 +msgid ":class:`c_float`" +msgstr ":class:`c_float`" + +#: ../../library/ctypes.rst:271 +msgid ":c:expr:`float`" +msgstr ":c:expr:`float`" + +#: ../../library/ctypes.rst:271 ../../library/ctypes.rst:273 +#: ../../library/ctypes.rst:275 +msgid "float" +msgstr "float" + +#: ../../library/ctypes.rst:273 +msgid ":class:`c_double`" +msgstr ":class:`c_double`" + +#: ../../library/ctypes.rst:273 +msgid ":c:expr:`double`" +msgstr ":c:expr:`double`" + +#: ../../library/ctypes.rst:275 +msgid ":class:`c_longdouble`" +msgstr ":class:`c_longdouble`" + +#: ../../library/ctypes.rst:275 +msgid ":c:expr:`long double`" +msgstr ":c:expr:`long double`" + +#: ../../library/ctypes.rst:277 +msgid ":class:`c_char_p`" +msgstr ":class:`c_char_p`" + +#: ../../library/ctypes.rst:277 +msgid ":c:expr:`char *` (NUL terminated)" +msgstr "" + +#: ../../library/ctypes.rst:277 +msgid "bytes object or ``None``" +msgstr "位元組物件或 ``None``" + +#: ../../library/ctypes.rst:279 +msgid ":class:`c_wchar_p`" +msgstr ":class:`c_wchar_p`" + +#: ../../library/ctypes.rst:279 +msgid ":c:expr:`wchar_t *` (NUL terminated)" +msgstr "" + +#: ../../library/ctypes.rst:279 +msgid "string or ``None``" +msgstr "字串或 ``None``" + +#: ../../library/ctypes.rst:281 +msgid ":class:`c_void_p`" +msgstr ":class:`c_void_p`" + +#: ../../library/ctypes.rst:281 +msgid ":c:expr:`void *`" +msgstr ":c:expr:`void *`" + +#: ../../library/ctypes.rst:281 +msgid "int or ``None``" +msgstr "" + +#: ../../library/ctypes.rst:285 +msgid "The constructor accepts any object with a truth value." +msgstr "" + +#: ../../library/ctypes.rst:287 +msgid "" +"Additionally, if IEC 60559 compatible complex arithmetic (Annex G) is " +"supported in both C and ``libffi``, the following complex types are " +"available:" +msgstr "" + +#: ../../library/ctypes.rst:293 +msgid ":class:`c_float_complex`" +msgstr ":class:`c_float_complex`" + +#: ../../library/ctypes.rst:293 +msgid ":c:expr:`float complex`" +msgstr ":c:expr:`float complex`" + +#: ../../library/ctypes.rst:293 ../../library/ctypes.rst:295 +#: ../../library/ctypes.rst:297 +msgid "complex" +msgstr "" + +#: ../../library/ctypes.rst:295 +msgid ":class:`c_double_complex`" +msgstr ":class:`c_double_complex`" + +#: ../../library/ctypes.rst:295 +msgid ":c:expr:`double complex`" +msgstr ":c:expr:`double complex`" + +#: ../../library/ctypes.rst:297 +msgid ":class:`c_longdouble_complex`" +msgstr ":class:`c_longdouble_complex`" + +#: ../../library/ctypes.rst:297 +msgid ":c:expr:`long double complex`" +msgstr ":c:expr:`long double complex`" + +#: ../../library/ctypes.rst:301 +msgid "" +"All these types can be created by calling them with an optional initializer " +"of the correct type and value::" +msgstr "" + +#: ../../library/ctypes.rst:304 +msgid "" +">>> c_int()\n" +"c_long(0)\n" +">>> c_wchar_p(\"Hello, World\")\n" +"c_wchar_p(140018365411392)\n" +">>> c_ushort(-3)\n" +"c_ushort(65533)\n" +">>>" +msgstr "" +">>> c_int()\n" +"c_long(0)\n" +">>> c_wchar_p(\"Hello, World\")\n" +"c_wchar_p(140018365411392)\n" +">>> c_ushort(-3)\n" +"c_ushort(65533)\n" +">>>" + +#: ../../library/ctypes.rst:312 +msgid "" +"Since these types are mutable, their value can also be changed afterwards::" +msgstr "" + +#: ../../library/ctypes.rst:314 +msgid "" +">>> i = c_int(42)\n" +">>> print(i)\n" +"c_long(42)\n" +">>> print(i.value)\n" +"42\n" +">>> i.value = -99\n" +">>> print(i.value)\n" +"-99\n" +">>>" +msgstr "" +">>> i = c_int(42)\n" +">>> print(i)\n" +"c_long(42)\n" +">>> print(i.value)\n" +"42\n" +">>> i.value = -99\n" +">>> print(i.value)\n" +"-99\n" +">>>" + +#: ../../library/ctypes.rst:324 +msgid "" +"Assigning a new value to instances of the pointer types :class:`c_char_p`, :" +"class:`c_wchar_p`, and :class:`c_void_p` changes the *memory location* they " +"point to, *not the contents* of the memory block (of course not, because " +"Python string objects are immutable)::" +msgstr "" + +#: ../../library/ctypes.rst:329 +msgid "" +">>> s = \"Hello, World\"\n" +">>> c_s = c_wchar_p(s)\n" +">>> print(c_s)\n" +"c_wchar_p(139966785747344)\n" +">>> print(c_s.value)\n" +"Hello World\n" +">>> c_s.value = \"Hi, there\"\n" +">>> print(c_s) # the memory location has changed\n" +"c_wchar_p(139966783348904)\n" +">>> print(c_s.value)\n" +"Hi, there\n" +">>> print(s) # first object is unchanged\n" +"Hello, World\n" +">>>" +msgstr "" +">>> s = \"Hello, World\"\n" +">>> c_s = c_wchar_p(s)\n" +">>> print(c_s)\n" +"c_wchar_p(139966785747344)\n" +">>> print(c_s.value)\n" +"Hello World\n" +">>> c_s.value = \"Hi, there\"\n" +">>> print(c_s) # 記憶體位置已改變\n" +"c_wchar_p(139966783348904)\n" +">>> print(c_s.value)\n" +"Hi, there\n" +">>> print(s) # 第一個物件未改變\n" +"Hello, World\n" +">>>" + +#: ../../library/ctypes.rst:344 +msgid "" +"You should be careful, however, not to pass them to functions expecting " +"pointers to mutable memory. If you need mutable memory blocks, ctypes has a :" +"func:`create_string_buffer` function which creates these in various ways. " +"The current memory block contents can be accessed (or changed) with the " +"``raw`` property; if you want to access it as NUL terminated string, use the " +"``value`` property::" +msgstr "" + +#: ../../library/ctypes.rst:351 +msgid "" +">>> from ctypes import *\n" +">>> p = create_string_buffer(3) # create a 3 byte buffer, " +"initialized to NUL bytes\n" +">>> print(sizeof(p), repr(p.raw))\n" +"3 b'\\x00\\x00\\x00'\n" +">>> p = create_string_buffer(b\"Hello\") # create a buffer containing a " +"NUL terminated string\n" +">>> print(sizeof(p), repr(p.raw))\n" +"6 b'Hello\\x00'\n" +">>> print(repr(p.value))\n" +"b'Hello'\n" +">>> p = create_string_buffer(b\"Hello\", 10) # create a 10 byte buffer\n" +">>> print(sizeof(p), repr(p.raw))\n" +"10 b'Hello\\x00\\x00\\x00\\x00\\x00'\n" +">>> p.value = b\"Hi\"\n" +">>> print(sizeof(p), repr(p.raw))\n" +"10 b'Hi\\x00lo\\x00\\x00\\x00\\x00\\x00'\n" +">>>" +msgstr "" + +#: ../../library/ctypes.rst:368 +msgid "" +"The :func:`create_string_buffer` function replaces the old :func:`!c_buffer` " +"function (which is still available as an alias). To create a mutable memory " +"block containing unicode characters of the C type :c:type:`wchar_t`, use " +"the :func:`create_unicode_buffer` function." +msgstr "" + +#: ../../library/ctypes.rst:377 +msgid "Calling functions, continued" +msgstr "" + +#: ../../library/ctypes.rst:379 +msgid "" +"Note that printf prints to the real standard output channel, *not* to :data:" +"`sys.stdout`, so these examples will only work at the console prompt, not " +"from within *IDLE* or *PythonWin*::" +msgstr "" + +#: ../../library/ctypes.rst:383 +msgid "" +">>> printf = libc.printf\n" +">>> printf(b\"Hello, %s\\n\", b\"World!\")\n" +"Hello, World!\n" +"14\n" +">>> printf(b\"Hello, %S\\n\", \"World!\")\n" +"Hello, World!\n" +"14\n" +">>> printf(b\"%d bottles of beer\\n\", 42)\n" +"42 bottles of beer\n" +"19\n" +">>> printf(b\"%f bottles of beer\\n\", 42.5)\n" +"Traceback (most recent call last):\n" +" File \"\", line 1, in \n" +"ctypes.ArgumentError: argument 2: TypeError: Don't know how to convert " +"parameter 2\n" +">>>" +msgstr "" +">>> printf = libc.printf\n" +">>> printf(b\"Hello, %s\\n\", b\"World!\")\n" +"Hello, World!\n" +"14\n" +">>> printf(b\"Hello, %S\\n\", \"World!\")\n" +"Hello, World!\n" +"14\n" +">>> printf(b\"%d bottles of beer\\n\", 42)\n" +"42 bottles of beer\n" +"19\n" +">>> printf(b\"%f bottles of beer\\n\", 42.5)\n" +"Traceback (most recent call last):\n" +" File \"\", line 1, in \n" +"ctypes.ArgumentError: argument 2: TypeError: Don't know how to convert " +"parameter 2\n" +">>>" + +#: ../../library/ctypes.rst:399 +msgid "" +"As has been mentioned before, all Python types except integers, strings, and " +"bytes objects have to be wrapped in their corresponding :mod:`ctypes` type, " +"so that they can be converted to the required C data type::" +msgstr "" + +#: ../../library/ctypes.rst:403 +msgid "" +">>> printf(b\"An int %d, a double %f\\n\", 1234, c_double(3.14))\n" +"An int 1234, a double 3.140000\n" +"31\n" +">>>" +msgstr "" +">>> printf(b\"An int %d, a double %f\\n\", 1234, c_double(3.14))\n" +"An int 1234, a double 3.140000\n" +"31\n" +">>>" + +#: ../../library/ctypes.rst:411 +msgid "Calling variadic functions" +msgstr "" + +#: ../../library/ctypes.rst:413 +msgid "" +"On a lot of platforms calling variadic functions through ctypes is exactly " +"the same as calling functions with a fixed number of parameters. On some " +"platforms, and in particular ARM64 for Apple Platforms, the calling " +"convention for variadic functions is different than that for regular " +"functions." +msgstr "" + +#: ../../library/ctypes.rst:418 +msgid "" +"On those platforms it is required to specify the :attr:`~_CFuncPtr.argtypes` " +"attribute for the regular, non-variadic, function arguments:" +msgstr "" + +#: ../../library/ctypes.rst:421 +msgid "libc.printf.argtypes = [ctypes.c_char_p]" +msgstr "libc.printf.argtypes = [ctypes.c_char_p]" + +#: ../../library/ctypes.rst:425 +msgid "" +"Because specifying the attribute does not inhibit portability it is advised " +"to always specify :attr:`~_CFuncPtr.argtypes` for all variadic functions." +msgstr "" + +#: ../../library/ctypes.rst:432 +msgid "Calling functions with your own custom data types" +msgstr "" + +#: ../../library/ctypes.rst:434 +msgid "" +"You can also customize :mod:`ctypes` argument conversion to allow instances " +"of your own classes be used as function arguments. :mod:`ctypes` looks for " +"an :attr:`!_as_parameter_` attribute and uses this as the function argument. " +"The attribute must be an integer, string, bytes, a :mod:`ctypes` instance, " +"or an object with an :attr:`!_as_parameter_` attribute::" +msgstr "" + +#: ../../library/ctypes.rst:440 +msgid "" +">>> class Bottles:\n" +"... def __init__(self, number):\n" +"... self._as_parameter_ = number\n" +"...\n" +">>> bottles = Bottles(42)\n" +">>> printf(b\"%d bottles of beer\\n\", bottles)\n" +"42 bottles of beer\n" +"19\n" +">>>" +msgstr "" +">>> class Bottles:\n" +"... def __init__(self, number):\n" +"... self._as_parameter_ = number\n" +"...\n" +">>> bottles = Bottles(42)\n" +">>> printf(b\"%d bottles of beer\\n\", bottles)\n" +"42 bottles of beer\n" +"19\n" +">>>" + +#: ../../library/ctypes.rst:450 +msgid "" +"If you don't want to store the instance's data in the :attr:`!" +"_as_parameter_` instance variable, you could define a :class:`property` " +"which makes the attribute available on request." +msgstr "" + +#: ../../library/ctypes.rst:458 +msgid "Specifying the required argument types (function prototypes)" +msgstr "" + +#: ../../library/ctypes.rst:460 +msgid "" +"It is possible to specify the required argument types of functions exported " +"from DLLs by setting the :attr:`~_CFuncPtr.argtypes` attribute." +msgstr "" + +#: ../../library/ctypes.rst:463 +msgid "" +":attr:`~_CFuncPtr.argtypes` must be a sequence of C data types (the :func:`!" +"printf` function is probably not a good example here, because it takes a " +"variable number and different types of parameters depending on the format " +"string, on the other hand this is quite handy to experiment with this " +"feature)::" +msgstr "" + +#: ../../library/ctypes.rst:468 +msgid "" +">>> printf.argtypes = [c_char_p, c_char_p, c_int, c_double]\n" +">>> printf(b\"String '%s', Int %d, Double %f\\n\", b\"Hi\", 10, 2.2)\n" +"String 'Hi', Int 10, Double 2.200000\n" +"37\n" +">>>" +msgstr "" +">>> printf.argtypes = [c_char_p, c_char_p, c_int, c_double]\n" +">>> printf(b\"String '%s', Int %d, Double %f\\n\", b\"Hi\", 10, 2.2)\n" +"String 'Hi', Int 10, Double 2.200000\n" +"37\n" +">>>" + +#: ../../library/ctypes.rst:474 +msgid "" +"Specifying a format protects against incompatible argument types (just as a " +"prototype for a C function), and tries to convert the arguments to valid " +"types::" +msgstr "" + +#: ../../library/ctypes.rst:477 +msgid "" +">>> printf(b\"%d %d %d\", 1, 2, 3)\n" +"Traceback (most recent call last):\n" +" File \"\", line 1, in \n" +"ctypes.ArgumentError: argument 2: TypeError: 'int' object cannot be " +"interpreted as ctypes.c_char_p\n" +">>> printf(b\"%s %d %f\\n\", b\"X\", 2, 3)\n" +"X 2 3.000000\n" +"13\n" +">>>" +msgstr "" +">>> printf(b\"%d %d %d\", 1, 2, 3)\n" +"Traceback (most recent call last):\n" +" File \"\", line 1, in \n" +"ctypes.ArgumentError: argument 2: TypeError: 'int' object cannot be " +"interpreted as ctypes.c_char_p\n" +">>> printf(b\"%s %d %f\\n\", b\"X\", 2, 3)\n" +"X 2 3.000000\n" +"13\n" +">>>" + +#: ../../library/ctypes.rst:486 +msgid "" +"If you have defined your own classes which you pass to function calls, you " +"have to implement a :meth:`~_CData.from_param` class method for them to be " +"able to use them in the :attr:`~_CFuncPtr.argtypes` sequence. The :meth:" +"`~_CData.from_param` class method receives the Python object passed to the " +"function call, it should do a typecheck or whatever is needed to make sure " +"this object is acceptable, and then return the object itself, its :attr:`!" +"_as_parameter_` attribute, or whatever you want to pass as the C function " +"argument in this case. Again, the result should be an integer, string, " +"bytes, a :mod:`ctypes` instance, or an object with an :attr:`!" +"_as_parameter_` attribute." +msgstr "" + +#: ../../library/ctypes.rst:500 +msgid "Return types" +msgstr "" + +#: ../../library/ctypes.rst:510 +msgid "" +"By default functions are assumed to return the C :c:expr:`int` type. Other " +"return types can be specified by setting the :attr:`~_CFuncPtr.restype` " +"attribute of the function object." +msgstr "" + +#: ../../library/ctypes.rst:514 +msgid "" +"The C prototype of :c:func:`time` is ``time_t time(time_t *)``. Because :c:" +"type:`time_t` might be of a different type than the default return type :c:" +"expr:`int`, you should specify the :attr:`!restype` attribute::" +msgstr "" + +#: ../../library/ctypes.rst:518 +msgid ">>> libc.time.restype = c_time_t" +msgstr ">>> libc.time.restype = c_time_t" + +#: ../../library/ctypes.rst:520 +msgid "The argument types can be specified using :attr:`~_CFuncPtr.argtypes`::" +msgstr "" + +#: ../../library/ctypes.rst:522 +msgid ">>> libc.time.argtypes = (POINTER(c_time_t),)" +msgstr ">>> libc.time.argtypes = (POINTER(c_time_t),)" + +#: ../../library/ctypes.rst:524 +msgid "" +"To call the function with a ``NULL`` pointer as first argument, use " +"``None``::" +msgstr "" + +#: ../../library/ctypes.rst:526 +msgid "" +">>> print(libc.time(None))\n" +"1150640792" +msgstr "" +">>> print(libc.time(None))\n" +"1150640792" + +#: ../../library/ctypes.rst:529 +msgid "" +"Here is a more advanced example, it uses the :func:`!strchr` function, which " +"expects a string pointer and a char, and returns a pointer to a string::" +msgstr "" + +#: ../../library/ctypes.rst:532 +msgid "" +">>> strchr = libc.strchr\n" +">>> strchr(b\"abcdef\", ord(\"d\"))\n" +"8059983\n" +">>> strchr.restype = c_char_p # c_char_p is a pointer to a string\n" +">>> strchr(b\"abcdef\", ord(\"d\"))\n" +"b'def'\n" +">>> print(strchr(b\"abcdef\", ord(\"x\")))\n" +"None\n" +">>>" +msgstr "" +">>> strchr = libc.strchr\n" +">>> strchr(b\"abcdef\", ord(\"d\"))\n" +"8059983\n" +">>> strchr.restype = c_char_p # c_char_p 一個字串的指標\n" +">>> strchr(b\"abcdef\", ord(\"d\"))\n" +"b'def'\n" +">>> print(strchr(b\"abcdef\", ord(\"x\")))\n" +"None\n" +">>>" + +#: ../../library/ctypes.rst:542 +msgid "" +"If you want to avoid the :func:`ord(\"x\") ` calls above, you can set " +"the :attr:`~_CFuncPtr.argtypes` attribute, and the second argument will be " +"converted from a single character Python bytes object into a C char:" +msgstr "" + +#: ../../library/ctypes.rst:546 +msgid "" +">>> strchr.restype = c_char_p\n" +">>> strchr.argtypes = [c_char_p, c_char]\n" +">>> strchr(b\"abcdef\", b\"d\")\n" +"b'def'\n" +">>> strchr(b\"abcdef\", b\"def\")\n" +"Traceback (most recent call last):\n" +"ctypes.ArgumentError: argument 2: TypeError: one character bytes, bytearray " +"or integer expected\n" +">>> print(strchr(b\"abcdef\", b\"x\"))\n" +"None\n" +">>> strchr(b\"abcdef\", b\"d\")\n" +"b'def'\n" +">>>" +msgstr "" +">>> strchr.restype = c_char_p\n" +">>> strchr.argtypes = [c_char_p, c_char]\n" +">>> strchr(b\"abcdef\", b\"d\")\n" +"b'def'\n" +">>> strchr(b\"abcdef\", b\"def\")\n" +"Traceback (most recent call last):\n" +"ctypes.ArgumentError: argument 2: TypeError: one character bytes, bytearray " +"or integer expected\n" +">>> print(strchr(b\"abcdef\", b\"x\"))\n" +"None\n" +">>> strchr(b\"abcdef\", b\"d\")\n" +"b'def'\n" +">>>" + +#: ../../library/ctypes.rst:561 +msgid "" +"You can also use a callable Python object (a function or a class for " +"example) as the :attr:`~_CFuncPtr.restype` attribute, if the foreign " +"function returns an integer. The callable will be called with the *integer* " +"the C function returns, and the result of this call will be used as the " +"result of your function call. This is useful to check for error return " +"values and automatically raise an exception::" +msgstr "" + +#: ../../library/ctypes.rst:567 +msgid "" +">>> GetModuleHandle = windll.kernel32.GetModuleHandleA\n" +">>> def ValidHandle(value):\n" +"... if value == 0:\n" +"... raise WinError()\n" +"... return value\n" +"...\n" +">>>\n" +">>> GetModuleHandle.restype = ValidHandle\n" +">>> GetModuleHandle(None)\n" +"486539264\n" +">>> GetModuleHandle(\"something silly\")\n" +"Traceback (most recent call last):\n" +" File \"\", line 1, in \n" +" File \"\", line 3, in ValidHandle\n" +"OSError: [Errno 126] The specified module could not be found.\n" +">>>" +msgstr "" +">>> GetModuleHandle = windll.kernel32.GetModuleHandleA\n" +">>> def ValidHandle(value):\n" +"... if value == 0:\n" +"... raise WinError()\n" +"... return value\n" +"...\n" +">>>\n" +">>> GetModuleHandle.restype = ValidHandle\n" +">>> GetModuleHandle(None)\n" +"486539264\n" +">>> GetModuleHandle(\"something silly\")\n" +"Traceback (most recent call last):\n" +" File \"\", line 1, in \n" +" File \"\", line 3, in ValidHandle\n" +"OSError: [Errno 126] The specified module could not be found.\n" +">>>" + +#: ../../library/ctypes.rst:584 +msgid "" +"``WinError`` is a function which will call Windows ``FormatMessage()`` api " +"to get the string representation of an error code, and *returns* an " +"exception. ``WinError`` takes an optional error code parameter, if no one is " +"used, it calls :func:`GetLastError` to retrieve it." +msgstr "" + +#: ../../library/ctypes.rst:589 +msgid "" +"Please note that a much more powerful error checking mechanism is available " +"through the :attr:`~_CFuncPtr.errcheck` attribute; see the reference manual " +"for details." +msgstr "" + +#: ../../library/ctypes.rst:597 +msgid "Passing pointers (or: passing parameters by reference)" +msgstr "" + +#: ../../library/ctypes.rst:599 +msgid "" +"Sometimes a C api function expects a *pointer* to a data type as parameter, " +"probably to write into the corresponding location, or if the data is too " +"large to be passed by value. This is also known as *passing parameters by " +"reference*." +msgstr "" + +#: ../../library/ctypes.rst:603 +msgid "" +":mod:`ctypes` exports the :func:`byref` function which is used to pass " +"parameters by reference. The same effect can be achieved with the :func:" +"`pointer` function, although :func:`pointer` does a lot more work since it " +"constructs a real pointer object, so it is faster to use :func:`byref` if " +"you don't need the pointer object in Python itself::" +msgstr "" + +#: ../../library/ctypes.rst:609 +msgid "" +">>> i = c_int()\n" +">>> f = c_float()\n" +">>> s = create_string_buffer(b'\\000' * 32)\n" +">>> print(i.value, f.value, repr(s.value))\n" +"0 0.0 b''\n" +">>> libc.sscanf(b\"1 3.14 Hello\", b\"%d %f %s\",\n" +"... byref(i), byref(f), s)\n" +"3\n" +">>> print(i.value, f.value, repr(s.value))\n" +"1 3.1400001049 b'Hello'\n" +">>>" +msgstr "" +">>> i = c_int()\n" +">>> f = c_float()\n" +">>> s = create_string_buffer(b'\\000' * 32)\n" +">>> print(i.value, f.value, repr(s.value))\n" +"0 0.0 b''\n" +">>> libc.sscanf(b\"1 3.14 Hello\", b\"%d %f %s\",\n" +"... byref(i), byref(f), s)\n" +"3\n" +">>> print(i.value, f.value, repr(s.value))\n" +"1 3.1400001049 b'Hello'\n" +">>>" + +#: ../../library/ctypes.rst:625 +msgid "Structures and unions" +msgstr "" + +#: ../../library/ctypes.rst:627 +msgid "" +"Structures and unions must derive from the :class:`Structure` and :class:" +"`Union` base classes which are defined in the :mod:`ctypes` module. Each " +"subclass must define a :attr:`~Structure._fields_` attribute. :attr:`!" +"_fields_` must be a list of *2-tuples*, containing a *field name* and a " +"*field type*." +msgstr "" + +#: ../../library/ctypes.rst:632 +msgid "" +"The field type must be a :mod:`ctypes` type like :class:`c_int`, or any " +"other derived :mod:`ctypes` type: structure, union, array, pointer." +msgstr "" + +#: ../../library/ctypes.rst:635 +msgid "" +"Here is a simple example of a POINT structure, which contains two integers " +"named *x* and *y*, and also shows how to initialize a structure in the " +"constructor::" +msgstr "" + +#: ../../library/ctypes.rst:638 +msgid "" +">>> from ctypes import *\n" +">>> class POINT(Structure):\n" +"... _fields_ = [(\"x\", c_int),\n" +"... (\"y\", c_int)]\n" +"...\n" +">>> point = POINT(10, 20)\n" +">>> print(point.x, point.y)\n" +"10 20\n" +">>> point = POINT(y=5)\n" +">>> print(point.x, point.y)\n" +"0 5\n" +">>> POINT(1, 2, 3)\n" +"Traceback (most recent call last):\n" +" File \"\", line 1, in \n" +"TypeError: too many initializers\n" +">>>" +msgstr "" +">>> from ctypes import *\n" +">>> class POINT(Structure):\n" +"... _fields_ = [(\"x\", c_int),\n" +"... (\"y\", c_int)]\n" +"...\n" +">>> point = POINT(10, 20)\n" +">>> print(point.x, point.y)\n" +"10 20\n" +">>> point = POINT(y=5)\n" +">>> print(point.x, point.y)\n" +"0 5\n" +">>> POINT(1, 2, 3)\n" +"Traceback (most recent call last):\n" +" File \"\", line 1, in \n" +"TypeError: too many initializers\n" +">>>" + +#: ../../library/ctypes.rst:655 +msgid "" +"You can, however, build much more complicated structures. A structure can " +"itself contain other structures by using a structure as a field type." +msgstr "" + +#: ../../library/ctypes.rst:658 +msgid "" +"Here is a RECT structure which contains two POINTs named *upperleft* and " +"*lowerright*::" +msgstr "" + +#: ../../library/ctypes.rst:661 +msgid "" +">>> class RECT(Structure):\n" +"... _fields_ = [(\"upperleft\", POINT),\n" +"... (\"lowerright\", POINT)]\n" +"...\n" +">>> rc = RECT(point)\n" +">>> print(rc.upperleft.x, rc.upperleft.y)\n" +"0 5\n" +">>> print(rc.lowerright.x, rc.lowerright.y)\n" +"0 0\n" +">>>" +msgstr "" +">>> class RECT(Structure):\n" +"... _fields_ = [(\"upperleft\", POINT),\n" +"... (\"lowerright\", POINT)]\n" +"...\n" +">>> rc = RECT(point)\n" +">>> print(rc.upperleft.x, rc.upperleft.y)\n" +"0 5\n" +">>> print(rc.lowerright.x, rc.lowerright.y)\n" +"0 0\n" +">>>" + +#: ../../library/ctypes.rst:672 +msgid "" +"Nested structures can also be initialized in the constructor in several " +"ways::" +msgstr "" + +#: ../../library/ctypes.rst:674 +msgid "" +">>> r = RECT(POINT(1, 2), POINT(3, 4))\n" +">>> r = RECT((1, 2), (3, 4))" +msgstr "" +">>> r = RECT(POINT(1, 2), POINT(3, 4))\n" +">>> r = RECT((1, 2), (3, 4))" + +#: ../../library/ctypes.rst:677 +msgid "" +"Field :term:`descriptor`\\s can be retrieved from the *class*, they are " +"useful for debugging because they can provide useful information. See :class:" +"`CField`::" +msgstr "" + +#: ../../library/ctypes.rst:681 +msgid "" +">>> POINT.x\n" +"\n" +">>> POINT.y\n" +"\n" +">>>" +msgstr "" +">>> POINT.x\n" +"\n" +">>> POINT.y\n" +"\n" +">>>" + +#: ../../library/ctypes.rst:692 +msgid "" +":mod:`ctypes` does not support passing unions or structures with bit-fields " +"to functions by value. While this may work on 32-bit x86, it's not " +"guaranteed by the library to work in the general case. Unions and " +"structures with bit-fields should always be passed to functions by pointer." +msgstr "" + +#: ../../library/ctypes.rst:698 +msgid "Structure/union layout, alignment and byte order" +msgstr "" + +#: ../../library/ctypes.rst:700 +msgid "" +"By default, Structure and Union fields are laid out in the same way the C " +"compiler does it. It is possible to override this behavior entirely by " +"specifying a :attr:`~Structure._layout_` class attribute in the subclass " +"definition; see the attribute documentation for details." +msgstr "" + +#: ../../library/ctypes.rst:705 +msgid "" +"It is possible to specify the maximum alignment for the fields and/or for " +"the structure itself by setting the class attributes :attr:`~Structure." +"_pack_` and/or :attr:`~Structure._align_`, respectively. See the attribute " +"documentation for details." +msgstr "" + +#: ../../library/ctypes.rst:710 +msgid "" +":mod:`ctypes` uses the native byte order for Structures and Unions. To " +"build structures with non-native byte order, you can use one of the :class:" +"`BigEndianStructure`, :class:`LittleEndianStructure`, :class:" +"`BigEndianUnion`, and :class:`LittleEndianUnion` base classes. These " +"classes cannot contain pointer fields." +msgstr "" + +#: ../../library/ctypes.rst:720 +msgid "Bit fields in structures and unions" +msgstr "" + +#: ../../library/ctypes.rst:722 +msgid "" +"It is possible to create structures and unions containing bit fields. Bit " +"fields are only possible for integer fields, the bit width is specified as " +"the third item in the :attr:`~Structure._fields_` tuples::" +msgstr "" + +#: ../../library/ctypes.rst:726 +msgid "" +">>> class Int(Structure):\n" +"... _fields_ = [(\"first_16\", c_int, 16),\n" +"... (\"second_16\", c_int, 16)]\n" +"...\n" +">>> print(Int.first_16)\n" +"\n" +">>> print(Int.second_16)\n" +"" +msgstr "" +">>> class Int(Structure):\n" +"... _fields_ = [(\"first_16\", c_int, 16),\n" +"... (\"second_16\", c_int, 16)]\n" +"...\n" +">>> print(Int.first_16)\n" +"\n" +">>> print(Int.second_16)\n" +"" + +#: ../../library/ctypes.rst:735 +msgid "" +"It is important to note that bit field allocation and layout in memory are " +"not defined as a C standard; their implementation is compiler-specific. By " +"default, Python will attempt to match the behavior of a \"native\" compiler " +"for the current platform. See the :attr:`~Structure._layout_` attribute for " +"details on the default behavior and how to change it." +msgstr "" + +#: ../../library/ctypes.rst:746 +msgid "Arrays" +msgstr "" + +#: ../../library/ctypes.rst:748 +msgid "" +"Arrays are sequences, containing a fixed number of instances of the same " +"type." +msgstr "" + +#: ../../library/ctypes.rst:750 +msgid "" +"The recommended way to create array types is by multiplying a data type with " +"a positive integer::" +msgstr "" + +#: ../../library/ctypes.rst:753 +msgid "TenPointsArrayType = POINT * 10" +msgstr "" + +#: ../../library/ctypes.rst:755 +msgid "" +"Here is an example of a somewhat artificial data type, a structure " +"containing 4 POINTs among other stuff::" +msgstr "" + +#: ../../library/ctypes.rst:758 +msgid "" +">>> from ctypes import *\n" +">>> class POINT(Structure):\n" +"... _fields_ = (\"x\", c_int), (\"y\", c_int)\n" +"...\n" +">>> class MyStruct(Structure):\n" +"... _fields_ = [(\"a\", c_int),\n" +"... (\"b\", c_float),\n" +"... (\"point_array\", POINT * 4)]\n" +">>>\n" +">>> print(len(MyStruct().point_array))\n" +"4\n" +">>>" +msgstr "" +">>> from ctypes import *\n" +">>> class POINT(Structure):\n" +"... _fields_ = (\"x\", c_int), (\"y\", c_int)\n" +"...\n" +">>> class MyStruct(Structure):\n" +"... _fields_ = [(\"a\", c_int),\n" +"... (\"b\", c_float),\n" +"... (\"point_array\", POINT * 4)]\n" +">>>\n" +">>> print(len(MyStruct().point_array))\n" +"4\n" +">>>" + +#: ../../library/ctypes.rst:771 +msgid "Instances are created in the usual way, by calling the class::" +msgstr "" + +#: ../../library/ctypes.rst:773 +msgid "" +"arr = TenPointsArrayType()\n" +"for pt in arr:\n" +" print(pt.x, pt.y)" +msgstr "" +"arr = TenPointsArrayType()\n" +"for pt in arr:\n" +" print(pt.x, pt.y)" + +#: ../../library/ctypes.rst:777 +msgid "" +"The above code print a series of ``0 0`` lines, because the array contents " +"is initialized to zeros." +msgstr "" + +#: ../../library/ctypes.rst:780 +msgid "Initializers of the correct type can also be specified::" +msgstr "" + +#: ../../library/ctypes.rst:782 +msgid "" +">>> from ctypes import *\n" +">>> TenIntegers = c_int * 10\n" +">>> ii = TenIntegers(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)\n" +">>> print(ii)\n" +"\n" +">>> for i in ii: print(i, end=\" \")\n" +"...\n" +"1 2 3 4 5 6 7 8 9 10\n" +">>>" +msgstr "" +">>> from ctypes import *\n" +">>> TenIntegers = c_int * 10\n" +">>> ii = TenIntegers(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)\n" +">>> print(ii)\n" +"\n" +">>> for i in ii: print(i, end=\" \")\n" +"...\n" +"1 2 3 4 5 6 7 8 9 10\n" +">>>" + +#: ../../library/ctypes.rst:796 +msgid "Pointers" +msgstr "指標" + +#: ../../library/ctypes.rst:798 +msgid "" +"Pointer instances are created by calling the :func:`pointer` function on a :" +"mod:`ctypes` type::" +msgstr "" + +#: ../../library/ctypes.rst:801 +msgid "" +">>> from ctypes import *\n" +">>> i = c_int(42)\n" +">>> pi = pointer(i)\n" +">>>" +msgstr "" +">>> from ctypes import *\n" +">>> i = c_int(42)\n" +">>> pi = pointer(i)\n" +">>>" + +#: ../../library/ctypes.rst:806 +msgid "" +"Pointer instances have a :attr:`~_Pointer.contents` attribute which returns " +"the object to which the pointer points, the ``i`` object above::" +msgstr "" + +#: ../../library/ctypes.rst:809 +msgid "" +">>> pi.contents\n" +"c_long(42)\n" +">>>" +msgstr "" +">>> pi.contents\n" +"c_long(42)\n" +">>>" + +#: ../../library/ctypes.rst:813 +msgid "" +"Note that :mod:`ctypes` does not have OOR (original object return), it " +"constructs a new, equivalent object each time you retrieve an attribute::" +msgstr "" + +#: ../../library/ctypes.rst:816 +msgid "" +">>> pi.contents is i\n" +"False\n" +">>> pi.contents is pi.contents\n" +"False\n" +">>>" +msgstr "" +">>> pi.contents is i\n" +"False\n" +">>> pi.contents is pi.contents\n" +"False\n" +">>>" + +#: ../../library/ctypes.rst:822 +msgid "" +"Assigning another :class:`c_int` instance to the pointer's contents " +"attribute would cause the pointer to point to the memory location where this " +"is stored::" +msgstr "" + +#: ../../library/ctypes.rst:825 +msgid "" +">>> i = c_int(99)\n" +">>> pi.contents = i\n" +">>> pi.contents\n" +"c_long(99)\n" +">>>" +msgstr "" +">>> i = c_int(99)\n" +">>> pi.contents = i\n" +">>> pi.contents\n" +"c_long(99)\n" +">>>" + +#: ../../library/ctypes.rst:834 +msgid "Pointer instances can also be indexed with integers::" +msgstr "" + +#: ../../library/ctypes.rst:836 +msgid "" +">>> pi[0]\n" +"99\n" +">>>" +msgstr "" +">>> pi[0]\n" +"99\n" +">>>" + +#: ../../library/ctypes.rst:840 +msgid "Assigning to an integer index changes the pointed to value::" +msgstr "" + +#: ../../library/ctypes.rst:842 +msgid "" +">>> print(i)\n" +"c_long(99)\n" +">>> pi[0] = 22\n" +">>> print(i)\n" +"c_long(22)\n" +">>>" +msgstr "" +">>> print(i)\n" +"c_long(99)\n" +">>> pi[0] = 22\n" +">>> print(i)\n" +"c_long(22)\n" +">>>" + +#: ../../library/ctypes.rst:849 +msgid "" +"It is also possible to use indexes different from 0, but you must know what " +"you're doing, just as in C: You can access or change arbitrary memory " +"locations. Generally you only use this feature if you receive a pointer from " +"a C function, and you *know* that the pointer actually points to an array " +"instead of a single item." +msgstr "" + +#: ../../library/ctypes.rst:855 +msgid "" +"Behind the scenes, the :func:`pointer` function does more than simply create " +"pointer instances, it has to create pointer *types* first. This is done with " +"the :func:`POINTER` function, which accepts any :mod:`ctypes` type, and " +"returns a new type::" +msgstr "" + +#: ../../library/ctypes.rst:860 +msgid "" +">>> PI = POINTER(c_int)\n" +">>> PI\n" +"\n" +">>> PI(42)\n" +"Traceback (most recent call last):\n" +" File \"\", line 1, in \n" +"TypeError: expected c_long instead of int\n" +">>> PI(c_int(42))\n" +"\n" +">>>" +msgstr "" +">>> PI = POINTER(c_int)\n" +">>> PI\n" +"\n" +">>> PI(42)\n" +"Traceback (most recent call last):\n" +" File \"\", line 1, in \n" +"TypeError: expected c_long instead of int\n" +">>> PI(c_int(42))\n" +"\n" +">>>" + +#: ../../library/ctypes.rst:871 +msgid "" +"Calling the pointer type without an argument creates a ``NULL`` pointer. " +"``NULL`` pointers have a ``False`` boolean value::" +msgstr "" + +#: ../../library/ctypes.rst:874 +msgid "" +">>> null_ptr = POINTER(c_int)()\n" +">>> print(bool(null_ptr))\n" +"False\n" +">>>" +msgstr "" +">>> null_ptr = POINTER(c_int)()\n" +">>> print(bool(null_ptr))\n" +"False\n" +">>>" + +#: ../../library/ctypes.rst:879 +msgid "" +":mod:`ctypes` checks for ``NULL`` when dereferencing pointers (but " +"dereferencing invalid non-\\ ``NULL`` pointers would crash Python)::" +msgstr "" + +#: ../../library/ctypes.rst:882 +msgid "" +">>> null_ptr[0]\n" +"Traceback (most recent call last):\n" +" ....\n" +"ValueError: NULL pointer access\n" +">>>\n" +"\n" +">>> null_ptr[0] = 1234\n" +"Traceback (most recent call last):\n" +" ....\n" +"ValueError: NULL pointer access\n" +">>>" +msgstr "" +">>> null_ptr[0]\n" +"Traceback (most recent call last):\n" +" ....\n" +"ValueError: NULL pointer access\n" +">>>\n" +"\n" +">>> null_ptr[0] = 1234\n" +"Traceback (most recent call last):\n" +" ....\n" +"ValueError: NULL pointer access\n" +">>>" + +#: ../../library/ctypes.rst:897 +msgid "Thread safety without the GIL" +msgstr "" + +#: ../../library/ctypes.rst:899 +msgid "" +"From Python 3.13 onward, the :term:`GIL` can be disabled on :term:`free " +"threaded ` builds. In ctypes, reads and writes to a single " +"object concurrently is safe, but not across multiple objects:" +msgstr "" + +#: ../../library/ctypes.rst:902 +msgid "" +">>> number = c_int(42)\n" +">>> pointer_a = pointer(number)\n" +">>> pointer_b = pointer(number)" +msgstr "" +">>> number = c_int(42)\n" +">>> pointer_a = pointer(number)\n" +">>> pointer_b = pointer(number)" + +#: ../../library/ctypes.rst:908 +msgid "" +"In the above, it's only safe for one object to read and write to the address " +"at once if the GIL is disabled. So, ``pointer_a`` can be shared and written " +"to across multiple threads, but only if ``pointer_b`` is not also attempting " +"to do the same. If this is an issue, consider using a :class:`threading." +"Lock` to synchronize access to memory:" +msgstr "" + +#: ../../library/ctypes.rst:913 +msgid "" +">>> import threading\n" +">>> lock = threading.Lock()\n" +">>> # Thread 1\n" +">>> with lock:\n" +"... pointer_a.contents = 24\n" +">>> # Thread 2\n" +">>> with lock:\n" +"... pointer_b.contents = 42" +msgstr "" +">>> import threading\n" +">>> lock = threading.Lock()\n" +">>> # 執行緒 1\n" +">>> with lock:\n" +"... pointer_a.contents = 24\n" +">>> # 執行緒 2\n" +">>> with lock:\n" +"... pointer_b.contents = 42" + +#: ../../library/ctypes.rst:928 +msgid "Type conversions" +msgstr "" + +#: ../../library/ctypes.rst:930 +msgid "" +"Usually, ctypes does strict type checking. This means, if you have " +"``POINTER(c_int)`` in the :attr:`~_CFuncPtr.argtypes` list of a function or " +"as the type of a member field in a structure definition, only instances of " +"exactly the same type are accepted. There are some exceptions to this rule, " +"where ctypes accepts other objects. For example, you can pass compatible " +"array instances instead of pointer types. So, for ``POINTER(c_int)``, " +"ctypes accepts an array of c_int::" +msgstr "" + +#: ../../library/ctypes.rst:937 +msgid "" +">>> class Bar(Structure):\n" +"... _fields_ = [(\"count\", c_int), (\"values\", POINTER(c_int))]\n" +"...\n" +">>> bar = Bar()\n" +">>> bar.values = (c_int * 3)(1, 2, 3)\n" +">>> bar.count = 3\n" +">>> for i in range(bar.count):\n" +"... print(bar.values[i])\n" +"...\n" +"1\n" +"2\n" +"3\n" +">>>" +msgstr "" +">>> class Bar(Structure):\n" +"... _fields_ = [(\"count\", c_int), (\"values\", POINTER(c_int))]\n" +"...\n" +">>> bar = Bar()\n" +">>> bar.values = (c_int * 3)(1, 2, 3)\n" +">>> bar.count = 3\n" +">>> for i in range(bar.count):\n" +"... print(bar.values[i])\n" +"...\n" +"1\n" +"2\n" +"3\n" +">>>" + +#: ../../library/ctypes.rst:951 +msgid "" +"In addition, if a function argument is explicitly declared to be a pointer " +"type (such as ``POINTER(c_int)``) in :attr:`~_CFuncPtr.argtypes`, an object " +"of the pointed type (``c_int`` in this case) can be passed to the function. " +"ctypes will apply the required :func:`byref` conversion in this case " +"automatically." +msgstr "" + +#: ../../library/ctypes.rst:956 +msgid "To set a POINTER type field to ``NULL``, you can assign ``None``::" +msgstr "" + +#: ../../library/ctypes.rst:958 +msgid "" +">>> bar.values = None\n" +">>>" +msgstr "" +">>> bar.values = None\n" +">>>" + +#: ../../library/ctypes.rst:963 +msgid "" +"Sometimes you have instances of incompatible types. In C, you can cast one " +"type into another type. :mod:`ctypes` provides a :func:`cast` function " +"which can be used in the same way. The ``Bar`` structure defined above " +"accepts ``POINTER(c_int)`` pointers or :class:`c_int` arrays for its " +"``values`` field, but not instances of other types::" +msgstr "" + +#: ../../library/ctypes.rst:969 +msgid "" +">>> bar.values = (c_byte * 4)()\n" +"Traceback (most recent call last):\n" +" File \"\", line 1, in \n" +"TypeError: incompatible types, c_byte_Array_4 instance instead of LP_c_long " +"instance\n" +">>>" +msgstr "" +">>> bar.values = (c_byte * 4)()\n" +"Traceback (most recent call last):\n" +" File \"\", line 1, in \n" +"TypeError: incompatible types, c_byte_Array_4 instance instead of LP_c_long " +"instance\n" +">>>" + +#: ../../library/ctypes.rst:975 +msgid "For these cases, the :func:`cast` function is handy." +msgstr "" + +#: ../../library/ctypes.rst:977 +msgid "" +"The :func:`cast` function can be used to cast a ctypes instance into a " +"pointer to a different ctypes data type. :func:`cast` takes two parameters, " +"a ctypes object that is or can be converted to a pointer of some kind, and a " +"ctypes pointer type. It returns an instance of the second argument, which " +"references the same memory block as the first argument::" +msgstr "" + +#: ../../library/ctypes.rst:983 +msgid "" +">>> a = (c_byte * 4)()\n" +">>> cast(a, POINTER(c_int))\n" +"\n" +">>>" +msgstr "" +">>> a = (c_byte * 4)()\n" +">>> cast(a, POINTER(c_int))\n" +"\n" +">>>" + +#: ../../library/ctypes.rst:988 +msgid "" +"So, :func:`cast` can be used to assign to the ``values`` field of ``Bar`` " +"the structure::" +msgstr "" + +#: ../../library/ctypes.rst:991 +msgid "" +">>> bar = Bar()\n" +">>> bar.values = cast((c_byte * 4)(), POINTER(c_int))\n" +">>> print(bar.values[0])\n" +"0\n" +">>>" +msgstr "" +">>> bar = Bar()\n" +">>> bar.values = cast((c_byte * 4)(), POINTER(c_int))\n" +">>> print(bar.values[0])\n" +"0\n" +">>>" + +#: ../../library/ctypes.rst:1001 +msgid "Incomplete Types" +msgstr "" + +#: ../../library/ctypes.rst:1003 +msgid "" +"*Incomplete Types* are structures, unions or arrays whose members are not " +"yet specified. In C, they are specified by forward declarations, which are " +"defined later::" +msgstr "" + +#: ../../library/ctypes.rst:1007 +msgid "" +"struct cell; /* forward declaration */\n" +"\n" +"struct cell {\n" +" char *name;\n" +" struct cell *next;\n" +"};" +msgstr "" + +#: ../../library/ctypes.rst:1014 +msgid "" +"The straightforward translation into ctypes code would be this, but it does " +"not work::" +msgstr "" + +#: ../../library/ctypes.rst:1017 +msgid "" +">>> class cell(Structure):\n" +"... _fields_ = [(\"name\", c_char_p),\n" +"... (\"next\", POINTER(cell))]\n" +"...\n" +"Traceback (most recent call last):\n" +" File \"\", line 1, in \n" +" File \"\", line 2, in cell\n" +"NameError: name 'cell' is not defined\n" +">>>" +msgstr "" +">>> class cell(Structure):\n" +"... _fields_ = [(\"name\", c_char_p),\n" +"... (\"next\", POINTER(cell))]\n" +"...\n" +"Traceback (most recent call last):\n" +" File \"\", line 1, in \n" +" File \"\", line 2, in cell\n" +"NameError: name 'cell' is not defined\n" +">>>" + +#: ../../library/ctypes.rst:1027 +msgid "" +"because the new ``class cell`` is not available in the class statement " +"itself. In :mod:`ctypes`, we can define the ``cell`` class and set the :attr:" +"`~Structure._fields_` attribute later, after the class statement::" +msgstr "" + +#: ../../library/ctypes.rst:1031 +msgid "" +">>> from ctypes import *\n" +">>> class cell(Structure):\n" +"... pass\n" +"...\n" +">>> cell._fields_ = [(\"name\", c_char_p),\n" +"... (\"next\", POINTER(cell))]\n" +">>>" +msgstr "" +">>> from ctypes import *\n" +">>> class cell(Structure):\n" +"... pass\n" +"...\n" +">>> cell._fields_ = [(\"name\", c_char_p),\n" +"... (\"next\", POINTER(cell))]\n" +">>>" + +#: ../../library/ctypes.rst:1039 +msgid "" +"Let's try it. We create two instances of ``cell``, and let them point to " +"each other, and finally follow the pointer chain a few times::" +msgstr "" + +#: ../../library/ctypes.rst:1042 +msgid "" +">>> c1 = cell()\n" +">>> c1.name = b\"foo\"\n" +">>> c2 = cell()\n" +">>> c2.name = b\"bar\"\n" +">>> c1.next = pointer(c2)\n" +">>> c2.next = pointer(c1)\n" +">>> p = c1\n" +">>> for i in range(8):\n" +"... print(p.name, end=\" \")\n" +"... p = p.next[0]\n" +"...\n" +"foo bar foo bar foo bar foo bar\n" +">>>" +msgstr "" +">>> c1 = cell()\n" +">>> c1.name = b\"foo\"\n" +">>> c2 = cell()\n" +">>> c2.name = b\"bar\"\n" +">>> c1.next = pointer(c2)\n" +">>> c2.next = pointer(c1)\n" +">>> p = c1\n" +">>> for i in range(8):\n" +"... print(p.name, end=\" \")\n" +"... p = p.next[0]\n" +"...\n" +"foo bar foo bar foo bar foo bar\n" +">>>" + +#: ../../library/ctypes.rst:1060 +msgid "Callback functions" +msgstr "回呼函式" + +#: ../../library/ctypes.rst:1062 +msgid "" +":mod:`ctypes` allows creating C callable function pointers from Python " +"callables. These are sometimes called *callback functions*." +msgstr "" + +#: ../../library/ctypes.rst:1065 +msgid "" +"First, you must create a class for the callback function. The class knows " +"the calling convention, the return type, and the number and types of " +"arguments this function will receive." +msgstr "" + +#: ../../library/ctypes.rst:1069 +msgid "" +"The :func:`CFUNCTYPE` factory function creates types for callback functions " +"using the ``cdecl`` calling convention. On Windows, the :func:`WINFUNCTYPE` " +"factory function creates types for callback functions using the ``stdcall`` " +"calling convention." +msgstr "" + +#: ../../library/ctypes.rst:1074 +msgid "" +"Both of these factory functions are called with the result type as first " +"argument, and the callback functions expected argument types as the " +"remaining arguments." +msgstr "" + +#: ../../library/ctypes.rst:1078 +msgid "" +"I will present an example here which uses the standard C library's :c:func:`!" +"qsort` function, that is used to sort items with the help of a callback " +"function. :c:func:`!qsort` will be used to sort an array of integers::" +msgstr "" + +#: ../../library/ctypes.rst:1082 +msgid "" +">>> IntArray5 = c_int * 5\n" +">>> ia = IntArray5(5, 1, 7, 33, 99)\n" +">>> qsort = libc.qsort\n" +">>> qsort.restype = None\n" +">>>" +msgstr "" +">>> IntArray5 = c_int * 5\n" +">>> ia = IntArray5(5, 1, 7, 33, 99)\n" +">>> qsort = libc.qsort\n" +">>> qsort.restype = None\n" +">>>" + +#: ../../library/ctypes.rst:1088 +msgid "" +":func:`!qsort` must be called with a pointer to the data to sort, the number " +"of items in the data array, the size of one item, and a pointer to the " +"comparison function, the callback. The callback will then be called with two " +"pointers to items, and it must return a negative integer if the first item " +"is smaller than the second, a zero if they are equal, and a positive integer " +"otherwise." +msgstr "" + +#: ../../library/ctypes.rst:1094 +msgid "" +"So our callback function receives pointers to integers, and must return an " +"integer. First we create the ``type`` for the callback function::" +msgstr "" + +#: ../../library/ctypes.rst:1097 +msgid "" +">>> CMPFUNC = CFUNCTYPE(c_int, POINTER(c_int), POINTER(c_int))\n" +">>>" +msgstr "" +">>> CMPFUNC = CFUNCTYPE(c_int, POINTER(c_int), POINTER(c_int))\n" +">>>" + +#: ../../library/ctypes.rst:1100 +msgid "" +"To get started, here is a simple callback that shows the values it gets " +"passed::" +msgstr "" + +#: ../../library/ctypes.rst:1103 +msgid "" +">>> def py_cmp_func(a, b):\n" +"... print(\"py_cmp_func\", a[0], b[0])\n" +"... return 0\n" +"...\n" +">>> cmp_func = CMPFUNC(py_cmp_func)\n" +">>>" +msgstr "" +">>> def py_cmp_func(a, b):\n" +"... print(\"py_cmp_func\", a[0], b[0])\n" +"... return 0\n" +"...\n" +">>> cmp_func = CMPFUNC(py_cmp_func)\n" +">>>" + +#: ../../library/ctypes.rst:1110 +msgid "The result::" +msgstr "結果為： ::" + +#: ../../library/ctypes.rst:1112 +msgid "" +">>> qsort(ia, len(ia), sizeof(c_int), cmp_func)\n" +"py_cmp_func 5 1\n" +"py_cmp_func 33 99\n" +"py_cmp_func 7 33\n" +"py_cmp_func 5 7\n" +"py_cmp_func 1 7\n" +">>>" +msgstr "" +">>> qsort(ia, len(ia), sizeof(c_int), cmp_func)\n" +"py_cmp_func 5 1\n" +"py_cmp_func 33 99\n" +"py_cmp_func 7 33\n" +"py_cmp_func 5 7\n" +"py_cmp_func 1 7\n" +">>>" + +#: ../../library/ctypes.rst:1120 +msgid "Now we can actually compare the two items and return a useful result::" +msgstr "" + +#: ../../library/ctypes.rst:1122 +msgid "" +">>> def py_cmp_func(a, b):\n" +"... print(\"py_cmp_func\", a[0], b[0])\n" +"... return a[0] - b[0]\n" +"...\n" +">>>\n" +">>> qsort(ia, len(ia), sizeof(c_int), CMPFUNC(py_cmp_func))\n" +"py_cmp_func 5 1\n" +"py_cmp_func 33 99\n" +"py_cmp_func 7 33\n" +"py_cmp_func 1 7\n" +"py_cmp_func 5 7\n" +">>>" +msgstr "" +">>> def py_cmp_func(a, b):\n" +"... print(\"py_cmp_func\", a[0], b[0])\n" +"... return a[0] - b[0]\n" +"...\n" +">>>\n" +">>> qsort(ia, len(ia), sizeof(c_int), CMPFUNC(py_cmp_func))\n" +"py_cmp_func 5 1\n" +"py_cmp_func 33 99\n" +"py_cmp_func 7 33\n" +"py_cmp_func 1 7\n" +"py_cmp_func 5 7\n" +">>>" + +#: ../../library/ctypes.rst:1135 +msgid "As we can easily check, our array is sorted now::" +msgstr "" + +#: ../../library/ctypes.rst:1137 +msgid "" +">>> for i in ia: print(i, end=\" \")\n" +"...\n" +"1 5 7 33 99\n" +">>>" +msgstr "" +">>> for i in ia: print(i, end=\" \")\n" +"...\n" +"1 5 7 33 99\n" +">>>" + +#: ../../library/ctypes.rst:1142 +msgid "" +"The function factories can be used as decorator factories, so we may as well " +"write::" +msgstr "" + +#: ../../library/ctypes.rst:1145 +msgid "" +">>> @CFUNCTYPE(c_int, POINTER(c_int), POINTER(c_int))\n" +"... def py_cmp_func(a, b):\n" +"... print(\"py_cmp_func\", a[0], b[0])\n" +"... return a[0] - b[0]\n" +"...\n" +">>> qsort(ia, len(ia), sizeof(c_int), py_cmp_func)\n" +"py_cmp_func 5 1\n" +"py_cmp_func 33 99\n" +"py_cmp_func 7 33\n" +"py_cmp_func 1 7\n" +"py_cmp_func 5 7\n" +">>>" +msgstr "" +">>> @CFUNCTYPE(c_int, POINTER(c_int), POINTER(c_int))\n" +"... def py_cmp_func(a, b):\n" +"... print(\"py_cmp_func\", a[0], b[0])\n" +"... return a[0] - b[0]\n" +"...\n" +">>> qsort(ia, len(ia), sizeof(c_int), py_cmp_func)\n" +"py_cmp_func 5 1\n" +"py_cmp_func 33 99\n" +"py_cmp_func 7 33\n" +"py_cmp_func 1 7\n" +"py_cmp_func 5 7\n" +">>>" + +#: ../../library/ctypes.rst:1160 +msgid "" +"Make sure you keep references to :func:`CFUNCTYPE` objects as long as they " +"are used from C code. :mod:`ctypes` doesn't, and if you don't, they may be " +"garbage collected, crashing your program when a callback is made." +msgstr "" + +#: ../../library/ctypes.rst:1164 +msgid "" +"Also, note that if the callback function is called in a thread created " +"outside of Python's control (e.g. by the foreign code that calls the " +"callback), ctypes creates a new dummy Python thread on every invocation. " +"This behavior is correct for most purposes, but it means that values stored " +"with :class:`threading.local` will *not* survive across different callbacks, " +"even when those calls are made from the same C thread." +msgstr "" + +#: ../../library/ctypes.rst:1174 +msgid "Accessing values exported from dlls" +msgstr "" + +#: ../../library/ctypes.rst:1176 +msgid "" +"Some shared libraries not only export functions, they also export variables. " +"An example in the Python library itself is the :c:data:`Py_Version`, Python " +"runtime version number encoded in a single constant integer." +msgstr "" + +#: ../../library/ctypes.rst:1180 +msgid "" +":mod:`ctypes` can access values like this with the :meth:`~_CData.in_dll` " +"class methods of the type. *pythonapi* is a predefined symbol giving access " +"to the Python C api::" +msgstr "" + +#: ../../library/ctypes.rst:1184 +msgid "" +">>> version = ctypes.c_int.in_dll(ctypes.pythonapi, \"Py_Version\")\n" +">>> print(hex(version.value))\n" +"0x30c00a0" +msgstr "" +">>> version = ctypes.c_int.in_dll(ctypes.pythonapi, \"Py_Version\")\n" +">>> print(hex(version.value))\n" +"0x30c00a0" + +#: ../../library/ctypes.rst:1188 +msgid "" +"An extended example which also demonstrates the use of pointers accesses " +"the :c:data:`PyImport_FrozenModules` pointer exported by Python." +msgstr "" + +#: ../../library/ctypes.rst:1191 +msgid "Quoting the docs for that value:" +msgstr "" + +#: ../../library/ctypes.rst:1193 +msgid "" +"This pointer is initialized to point to an array of :c:struct:`_frozen` " +"records, terminated by one whose members are all ``NULL`` or zero. When a " +"frozen module is imported, it is searched in this table. Third-party code " +"could play tricks with this to provide a dynamically created collection of " +"frozen modules." +msgstr "" + +#: ../../library/ctypes.rst:1198 +msgid "" +"So manipulating this pointer could even prove useful. To restrict the " +"example size, we show only how this table can be read with :mod:`ctypes`::" +msgstr "" + +#: ../../library/ctypes.rst:1201 +msgid "" +">>> from ctypes import *\n" +">>>\n" +">>> class struct_frozen(Structure):\n" +"... _fields_ = [(\"name\", c_char_p),\n" +"... (\"code\", POINTER(c_ubyte)),\n" +"... (\"size\", c_int),\n" +"... (\"get_code\", POINTER(c_ubyte)), # Function pointer\n" +"... ]\n" +"...\n" +">>>" +msgstr "" +">>> from ctypes import *\n" +">>>\n" +">>> class struct_frozen(Structure):\n" +"... _fields_ = [(\"name\", c_char_p),\n" +"... (\"code\", POINTER(c_ubyte)),\n" +"... (\"size\", c_int),\n" +"... (\"get_code\", POINTER(c_ubyte)), # 函式指標\n" +"... ]\n" +"...\n" +">>>" + +#: ../../library/ctypes.rst:1212 +msgid "" +"We have defined the :c:struct:`_frozen` data type, so we can get the pointer " +"to the table::" +msgstr "" + +#: ../../library/ctypes.rst:1215 +msgid "" +">>> FrozenTable = POINTER(struct_frozen)\n" +">>> table = FrozenTable.in_dll(pythonapi, \"_PyImport_FrozenBootstrap\")\n" +">>>" +msgstr "" +">>> FrozenTable = POINTER(struct_frozen)\n" +">>> table = FrozenTable.in_dll(pythonapi, \"_PyImport_FrozenBootstrap\")\n" +">>>" + +#: ../../library/ctypes.rst:1219 +msgid "" +"Since ``table`` is a ``pointer`` to the array of ``struct_frozen`` records, " +"we can iterate over it, but we just have to make sure that our loop " +"terminates, because pointers have no size. Sooner or later it would probably " +"crash with an access violation or whatever, so it's better to break out of " +"the loop when we hit the ``NULL`` entry::" +msgstr "" + +#: ../../library/ctypes.rst:1225 +msgid "" +">>> for item in table:\n" +"... if item.name is None:\n" +"... break\n" +"... print(item.name.decode(\"ascii\"), item.size)\n" +"...\n" +"_frozen_importlib 31764\n" +"_frozen_importlib_external 41499\n" +"zipimport 12345\n" +">>>" +msgstr "" +">>> for item in table:\n" +"... if item.name is None:\n" +"... break\n" +"... print(item.name.decode(\"ascii\"), item.size)\n" +"...\n" +"_frozen_importlib 31764\n" +"_frozen_importlib_external 41499\n" +"zipimport 12345\n" +">>>" + +#: ../../library/ctypes.rst:1235 +msgid "" +"The fact that standard Python has a frozen module and a frozen package " +"(indicated by the negative ``size`` member) is not well known, it is only " +"used for testing. Try it out with ``import __hello__`` for example." +msgstr "" + +#: ../../library/ctypes.rst:1243 +msgid "Surprises" +msgstr "" + +#: ../../library/ctypes.rst:1245 +msgid "" +"There are some edges in :mod:`ctypes` where you might expect something other " +"than what actually happens." +msgstr "" + +#: ../../library/ctypes.rst:1248 +msgid "Consider the following example::" +msgstr "" + +#: ../../library/ctypes.rst:1250 +msgid "" +">>> from ctypes import *\n" +">>> class POINT(Structure):\n" +"... _fields_ = (\"x\", c_int), (\"y\", c_int)\n" +"...\n" +">>> class RECT(Structure):\n" +"... _fields_ = (\"a\", POINT), (\"b\", POINT)\n" +"...\n" +">>> p1 = POINT(1, 2)\n" +">>> p2 = POINT(3, 4)\n" +">>> rc = RECT(p1, p2)\n" +">>> print(rc.a.x, rc.a.y, rc.b.x, rc.b.y)\n" +"1 2 3 4\n" +">>> # now swap the two points\n" +">>> rc.a, rc.b = rc.b, rc.a\n" +">>> print(rc.a.x, rc.a.y, rc.b.x, rc.b.y)\n" +"3 4 3 4\n" +">>>" +msgstr "" +">>> from ctypes import *\n" +">>> class POINT(Structure):\n" +"... _fields_ = (\"x\", c_int), (\"y\", c_int)\n" +"...\n" +">>> class RECT(Structure):\n" +"... _fields_ = (\"a\", POINT), (\"b\", POINT)\n" +"...\n" +">>> p1 = POINT(1, 2)\n" +">>> p2 = POINT(3, 4)\n" +">>> rc = RECT(p1, p2)\n" +">>> print(rc.a.x, rc.a.y, rc.b.x, rc.b.y)\n" +"1 2 3 4\n" +">>> # now swap the two points\n" +">>> rc.a, rc.b = rc.b, rc.a\n" +">>> print(rc.a.x, rc.a.y, rc.b.x, rc.b.y)\n" +"3 4 3 4\n" +">>>" + +#: ../../library/ctypes.rst:1268 +msgid "" +"Hm. We certainly expected the last statement to print ``3 4 1 2``. What " +"happened? Here are the steps of the ``rc.a, rc.b = rc.b, rc.a`` line above::" +msgstr "" + +#: ../../library/ctypes.rst:1271 +msgid "" +">>> temp0, temp1 = rc.b, rc.a\n" +">>> rc.a = temp0\n" +">>> rc.b = temp1\n" +">>>" +msgstr "" +">>> temp0, temp1 = rc.b, rc.a\n" +">>> rc.a = temp0\n" +">>> rc.b = temp1\n" +">>>" + +#: ../../library/ctypes.rst:1276 +msgid "" +"Note that ``temp0`` and ``temp1`` are objects still using the internal " +"buffer of the ``rc`` object above. So executing ``rc.a = temp0`` copies the " +"buffer contents of ``temp0`` into ``rc`` 's buffer. This, in turn, changes " +"the contents of ``temp1``. So, the last assignment ``rc.b = temp1``, doesn't " +"have the expected effect." +msgstr "" + +#: ../../library/ctypes.rst:1282 +msgid "" +"Keep in mind that retrieving sub-objects from Structure, Unions, and Arrays " +"doesn't *copy* the sub-object, instead it retrieves a wrapper object " +"accessing the root-object's underlying buffer." +msgstr "" + +#: ../../library/ctypes.rst:1286 +msgid "" +"Another example that may behave differently from what one would expect is " +"this::" +msgstr "" + +#: ../../library/ctypes.rst:1288 +msgid "" +">>> s = c_char_p()\n" +">>> s.value = b\"abc def ghi\"\n" +">>> s.value\n" +"b'abc def ghi'\n" +">>> s.value is s.value\n" +"False\n" +">>>" +msgstr "" +">>> s = c_char_p()\n" +">>> s.value = b\"abc def ghi\"\n" +">>> s.value\n" +"b'abc def ghi'\n" +">>> s.value is s.value\n" +"False\n" +">>>" + +#: ../../library/ctypes.rst:1298 +msgid "" +"Objects instantiated from :class:`c_char_p` can only have their value set to " +"bytes or integers." +msgstr "" + +#: ../../library/ctypes.rst:1301 +msgid "" +"Why is it printing ``False``? ctypes instances are objects containing a " +"memory block plus some :term:`descriptor`\\s accessing the contents of the " +"memory. Storing a Python object in the memory block does not store the " +"object itself, instead the ``contents`` of the object is stored. Accessing " +"the contents again constructs a new Python object each time!" +msgstr "" + +#: ../../library/ctypes.rst:1311 +msgid "Variable-sized data types" +msgstr "" + +#: ../../library/ctypes.rst:1313 +msgid "" +":mod:`ctypes` provides some support for variable-sized arrays and structures." +msgstr "" + +#: ../../library/ctypes.rst:1315 +msgid "" +"The :func:`resize` function can be used to resize the memory buffer of an " +"existing ctypes object. The function takes the object as first argument, " +"and the requested size in bytes as the second argument. The memory block " +"cannot be made smaller than the natural memory block specified by the " +"objects type, a :exc:`ValueError` is raised if this is tried::" +msgstr "" + +#: ../../library/ctypes.rst:1321 +msgid "" +">>> short_array = (c_short * 4)()\n" +">>> print(sizeof(short_array))\n" +"8\n" +">>> resize(short_array, 4)\n" +"Traceback (most recent call last):\n" +" ...\n" +"ValueError: minimum size is 8\n" +">>> resize(short_array, 32)\n" +">>> sizeof(short_array)\n" +"32\n" +">>> sizeof(type(short_array))\n" +"8\n" +">>>" +msgstr "" +">>> short_array = (c_short * 4)()\n" +">>> print(sizeof(short_array))\n" +"8\n" +">>> resize(short_array, 4)\n" +"Traceback (most recent call last):\n" +" ...\n" +"ValueError: minimum size is 8\n" +">>> resize(short_array, 32)\n" +">>> sizeof(short_array)\n" +"32\n" +">>> sizeof(type(short_array))\n" +"8\n" +">>>" + +#: ../../library/ctypes.rst:1335 +msgid "" +"This is nice and fine, but how would one access the additional elements " +"contained in this array? Since the type still only knows about 4 elements, " +"we get errors accessing other elements::" +msgstr "" + +#: ../../library/ctypes.rst:1339 +msgid "" +">>> short_array[:]\n" +"[0, 0, 0, 0]\n" +">>> short_array[7]\n" +"Traceback (most recent call last):\n" +" ...\n" +"IndexError: invalid index\n" +">>>" +msgstr "" +">>> short_array[:]\n" +"[0, 0, 0, 0]\n" +">>> short_array[7]\n" +"Traceback (most recent call last):\n" +" ...\n" +"IndexError: invalid index\n" +">>>" + +#: ../../library/ctypes.rst:1347 +msgid "" +"Another way to use variable-sized data types with :mod:`ctypes` is to use " +"the dynamic nature of Python, and (re-)define the data type after the " +"required size is already known, on a case by case basis." +msgstr "" + +#: ../../library/ctypes.rst:1355 +msgid "ctypes reference" +msgstr "" + +#: ../../library/ctypes.rst:1361 +msgid "Finding shared libraries" +msgstr "" + +#: ../../library/ctypes.rst:1363 +msgid "" +"When programming in a compiled language, shared libraries are accessed when " +"compiling/linking a program, and when the program is run." +msgstr "" + +#: ../../library/ctypes.rst:1366 +msgid "" +"The purpose of the :func:`~ctypes.util.find_library` function is to locate a " +"library in a way similar to what the compiler or runtime loader does (on " +"platforms with several versions of a shared library the most recent should " +"be loaded), while the ctypes library loaders act like when a program is run, " +"and call the runtime loader directly." +msgstr "" + +#: ../../library/ctypes.rst:1372 +msgid "" +"The :mod:`!ctypes.util` module provides a function which can help to " +"determine the library to load." +msgstr "" + +#: ../../library/ctypes.rst:1380 +msgid "" +"Try to find a library and return a pathname. *name* is the library name " +"without any prefix like *lib*, suffix like ``.so``, ``.dylib`` or version " +"number (this is the form used for the posix linker option :option:`!-l`). " +"If no library can be found, returns ``None``." +msgstr "" + +#: ../../library/ctypes.rst:1385 ../../library/ctypes.rst:2136 +msgid "The exact functionality is system dependent." +msgstr "" + +#: ../../library/ctypes.rst:1387 +msgid "" +"On Linux, :func:`~ctypes.util.find_library` tries to run external programs " +"(``/sbin/ldconfig``, ``gcc``, ``objdump`` and ``ld``) to find the library " +"file. It returns the filename of the library file." +msgstr "" + +#: ../../library/ctypes.rst:1391 +msgid "" +"Note that if the output of these programs does not correspond to the dynamic " +"linker used by Python, the result of this function may be misleading." +msgstr "" + +#: ../../library/ctypes.rst:1394 +msgid "" +"On Linux, the value of the environment variable ``LD_LIBRARY_PATH`` is used " +"when searching for libraries, if a library cannot be found by any other " +"means." +msgstr "" + +#: ../../library/ctypes.rst:1398 +msgid "Here are some examples::" +msgstr "以下是一些範例： ::" + +#: ../../library/ctypes.rst:1400 +msgid "" +">>> from ctypes.util import find_library\n" +">>> find_library(\"m\")\n" +"'libm.so.6'\n" +">>> find_library(\"c\")\n" +"'libc.so.6'\n" +">>> find_library(\"bz2\")\n" +"'libbz2.so.1.0'\n" +">>>" +msgstr "" +">>> from ctypes.util import find_library\n" +">>> find_library(\"m\")\n" +"'libm.so.6'\n" +">>> find_library(\"c\")\n" +"'libc.so.6'\n" +">>> find_library(\"bz2\")\n" +"'libbz2.so.1.0'\n" +">>>" + +#: ../../library/ctypes.rst:1409 +msgid "" +"On macOS and Android, :func:`~ctypes.util.find_library` uses the system's " +"standard naming schemes and paths to locate the library, and returns a full " +"pathname if successful::" +msgstr "" + +#: ../../library/ctypes.rst:1413 +msgid "" +">>> from ctypes.util import find_library\n" +">>> find_library(\"c\")\n" +"'/usr/lib/libc.dylib'\n" +">>> find_library(\"m\")\n" +"'/usr/lib/libm.dylib'\n" +">>> find_library(\"bz2\")\n" +"'/usr/lib/libbz2.dylib'\n" +">>> find_library(\"AGL\")\n" +"'/System/Library/Frameworks/AGL.framework/AGL'\n" +">>>" +msgstr "" +">>> from ctypes.util import find_library\n" +">>> find_library(\"c\")\n" +"'/usr/lib/libc.dylib'\n" +">>> find_library(\"m\")\n" +"'/usr/lib/libm.dylib'\n" +">>> find_library(\"bz2\")\n" +"'/usr/lib/libbz2.dylib'\n" +">>> find_library(\"AGL\")\n" +"'/System/Library/Frameworks/AGL.framework/AGL'\n" +">>>" + +#: ../../library/ctypes.rst:1424 +msgid "" +"On Windows, :func:`~ctypes.util.find_library` searches along the system " +"search path, and returns the full pathname, but since there is no predefined " +"naming scheme a call like ``find_library(\"c\")`` will fail and return " +"``None``." +msgstr "" + +#: ../../library/ctypes.rst:1428 +msgid "" +"If wrapping a shared library with :mod:`ctypes`, it *may* be better to " +"determine the shared library name at development time, and hardcode that " +"into the wrapper module instead of using :func:`~ctypes.util.find_library` " +"to locate the library at runtime." +msgstr "" + +#: ../../library/ctypes.rst:1436 +msgid "Listing loaded shared libraries" +msgstr "" + +#: ../../library/ctypes.rst:1438 +msgid "" +"When writing code that relies on code loaded from shared libraries, it can " +"be useful to know which shared libraries have already been loaded into the " +"current process." +msgstr "" + +#: ../../library/ctypes.rst:1442 +msgid "" +"The :mod:`!ctypes.util` module provides the :func:`~ctypes.util.dllist` " +"function, which calls the different APIs provided by the various platforms " +"to help determine which shared libraries have already been loaded into the " +"current process." +msgstr "" + +#: ../../library/ctypes.rst:1446 +msgid "" +"The exact output of this function will be system dependent. On most " +"platforms, the first entry of this list represents the current process " +"itself, which may be an empty string. For example, on glibc-based Linux, the " +"return may look like::" +msgstr "" + +#: ../../library/ctypes.rst:1451 +msgid "" +">>> from ctypes.util import dllist\n" +">>> dllist()\n" +"['', 'linux-vdso.so.1', '/lib/x86_64-linux-gnu/libm.so.6', '/lib/x86_64-" +"linux-gnu/libc.so.6', ... ]" +msgstr "" +">>> from ctypes.util import dllist\n" +">>> dllist()\n" +"['', 'linux-vdso.so.1', '/lib/x86_64-linux-gnu/libm.so.6', '/lib/x86_64-" +"linux-gnu/libc.so.6', ... ]" + +#: ../../library/ctypes.rst:1458 +msgid "Loading shared libraries" +msgstr "" + +#: ../../library/ctypes.rst:1460 +msgid "" +"There are several ways to load shared libraries into the Python process. " +"One way is to instantiate one of the following classes:" +msgstr "" + +#: ../../library/ctypes.rst:1466 +msgid "" +"Instances of this class represent loaded shared libraries. Functions in " +"these libraries use the standard C calling convention, and are assumed to " +"return :c:expr:`int`." +msgstr "" + +#: ../../library/ctypes.rst:1470 +msgid "" +"On Windows creating a :class:`CDLL` instance may fail even if the DLL name " +"exists. When a dependent DLL of the loaded DLL is not found, a :exc:" +"`OSError` error is raised with the message *\"[WinError 126] The specified " +"module could not be found\".* This error message does not contain the name " +"of the missing DLL because the Windows API does not return this information " +"making this error hard to diagnose. To resolve this error and determine " +"which DLL is not found, you need to find the list of dependent DLLs and " +"determine which one is not found using Windows debugging and tracing tools." +msgstr "" + +#: ../../library/ctypes.rst:1482 ../../library/ctypes.rst:1507 +#: ../../library/ctypes.rst:1520 ../../library/ctypes.rst:1538 +msgid "The *name* parameter can now be a :term:`path-like object`." +msgstr "" + +#: ../../library/ctypes.rst:1486 +msgid "" +"`Microsoft DUMPBIN tool `_ -- A tool to find DLL dependents." +msgstr "" + +#: ../../library/ctypes.rst:1492 +msgid "" +"Instances of this class represent loaded shared libraries, functions in " +"these libraries use the ``stdcall`` calling convention, and are assumed to " +"return the windows specific :class:`HRESULT` code. :class:`HRESULT` values " +"contain information specifying whether the function call failed or " +"succeeded, together with additional error code. If the return value signals " +"a failure, an :class:`OSError` is automatically raised." +msgstr "" + +#: ../../library/ctypes.rst:1499 ../../library/ctypes.rst:1516 +#: ../../library/ctypes.rst:1660 ../../library/ctypes.rst:1668 +#: ../../library/ctypes.rst:1840 ../../library/ctypes.rst:1892 +#: ../../library/ctypes.rst:2044 ../../library/ctypes.rst:2116 +#: ../../library/ctypes.rst:2125 ../../library/ctypes.rst:2152 +#: ../../library/ctypes.rst:2166 ../../library/ctypes.rst:2175 +#: ../../library/ctypes.rst:2184 ../../library/ctypes.rst:2199 +#: ../../library/ctypes.rst:2266 ../../library/ctypes.rst:2293 +#: ../../library/ctypes.rst:2693 ../../library/ctypes.rst:3111 +msgid "Availability" +msgstr "可用性" + +#: ../../library/ctypes.rst:1501 +msgid "" +":exc:`WindowsError` used to be raised, which is now an alias of :exc:" +"`OSError`." +msgstr "" + +#: ../../library/ctypes.rst:1512 +msgid "" +"Instances of this class represent loaded shared libraries, functions in " +"these libraries use the ``stdcall`` calling convention, and are assumed to " +"return :c:expr:`int` by default." +msgstr "" + +#: ../../library/ctypes.rst:1523 +msgid "" +"The Python :term:`global interpreter lock` is released before calling any " +"function exported by these libraries, and reacquired afterwards." +msgstr "" + +#: ../../library/ctypes.rst:1529 +msgid "" +"Instances of this class behave like :class:`CDLL` instances, except that the " +"Python GIL is *not* released during the function call, and after the " +"function execution the Python error flag is checked. If the error flag is " +"set, a Python exception is raised." +msgstr "" + +#: ../../library/ctypes.rst:1534 +msgid "Thus, this is only useful to call Python C api functions directly." +msgstr "" + +#: ../../library/ctypes.rst:1540 +msgid "" +"All these classes can be instantiated by calling them with at least one " +"argument, the pathname of the shared library. If you have an existing " +"handle to an already loaded shared library, it can be passed as the " +"``handle`` named parameter, otherwise the underlying platform's :c:func:`!" +"dlopen` or :c:func:`!LoadLibrary` function is used to load the library into " +"the process, and to get a handle to it." +msgstr "" + +#: ../../library/ctypes.rst:1547 +msgid "" +"The *mode* parameter can be used to specify how the library is loaded. For " +"details, consult the :manpage:`dlopen(3)` manpage. On Windows, *mode* is " +"ignored. On posix systems, RTLD_NOW is always added, and is not " +"configurable." +msgstr "" + +#: ../../library/ctypes.rst:1552 +msgid "" +"The *use_errno* parameter, when set to true, enables a ctypes mechanism that " +"allows accessing the system :data:`errno` error number in a safe way. :mod:" +"`ctypes` maintains a thread-local copy of the system's :data:`errno` " +"variable; if you call foreign functions created with ``use_errno=True`` then " +"the :data:`errno` value before the function call is swapped with the ctypes " +"private copy, the same happens immediately after the function call." +msgstr "" + +#: ../../library/ctypes.rst:1559 +msgid "" +"The function :func:`ctypes.get_errno` returns the value of the ctypes " +"private copy, and the function :func:`ctypes.set_errno` changes the ctypes " +"private copy to a new value and returns the former value." +msgstr "" + +#: ../../library/ctypes.rst:1563 +msgid "" +"The *use_last_error* parameter, when set to true, enables the same mechanism " +"for the Windows error code which is managed by the :func:`GetLastError` and :" +"func:`!SetLastError` Windows API functions; :func:`ctypes.get_last_error` " +"and :func:`ctypes.set_last_error` are used to request and change the ctypes " +"private copy of the windows error code." +msgstr "" + +#: ../../library/ctypes.rst:1569 +msgid "" +"The *winmode* parameter is used on Windows to specify how the library is " +"loaded (since *mode* is ignored). It takes any value that is valid for the " +"Win32 API ``LoadLibraryEx`` flags parameter. When omitted, the default is to " +"use the flags that result in the most secure DLL load, which avoids issues " +"such as DLL hijacking. Passing the full path to the DLL is the safest way to " +"ensure the correct library and dependencies are loaded." +msgstr "" + +#: ../../library/ctypes.rst:1576 +msgid "Added *winmode* parameter." +msgstr "新增 *winmode* 參數。" + +#: ../../library/ctypes.rst:1583 +msgid "" +"Flag to use as *mode* parameter. On platforms where this flag is not " +"available, it is defined as the integer zero." +msgstr "" + +#: ../../library/ctypes.rst:1590 +msgid "" +"Flag to use as *mode* parameter. On platforms where this is not available, " +"it is the same as *RTLD_GLOBAL*." +msgstr "" + +#: ../../library/ctypes.rst:1597 +msgid "" +"The default mode which is used to load shared libraries. On OSX 10.3, this " +"is *RTLD_GLOBAL*, otherwise it is the same as *RTLD_LOCAL*." +msgstr "" + +#: ../../library/ctypes.rst:1600 +msgid "" +"Instances of these classes have no public methods. Functions exported by " +"the shared library can be accessed as attributes or by index. Please note " +"that accessing the function through an attribute caches the result and " +"therefore accessing it repeatedly returns the same object each time. On the " +"other hand, accessing it through an index returns a new object each time::" +msgstr "" + +#: ../../library/ctypes.rst:1606 +msgid "" +">>> from ctypes import CDLL\n" +">>> libc = CDLL(\"libc.so.6\") # On Linux\n" +">>> libc.time == libc.time\n" +"True\n" +">>> libc['time'] == libc['time']\n" +"False" +msgstr "" +">>> from ctypes import CDLL\n" +">>> libc = CDLL(\"libc.so.6\") # 於 Linux\n" +">>> libc.time == libc.time\n" +"True\n" +">>> libc['time'] == libc['time']\n" +"False" + +#: ../../library/ctypes.rst:1613 +msgid "" +"The following public attributes are available, their name starts with an " +"underscore to not clash with exported function names:" +msgstr "" + +#: ../../library/ctypes.rst:1619 +msgid "The system handle used to access the library." +msgstr "" + +#: ../../library/ctypes.rst:1624 +msgid "The name of the library passed in the constructor." +msgstr "" + +#: ../../library/ctypes.rst:1626 +msgid "" +"Shared libraries can also be loaded by using one of the prefabricated " +"objects, which are instances of the :class:`LibraryLoader` class, either by " +"calling the :meth:`~LibraryLoader.LoadLibrary` method, or by retrieving the " +"library as attribute of the loader instance." +msgstr "" + +#: ../../library/ctypes.rst:1634 +msgid "" +"Class which loads shared libraries. *dlltype* should be one of the :class:" +"`CDLL`, :class:`PyDLL`, :class:`WinDLL`, or :class:`OleDLL` types." +msgstr "" + +#: ../../library/ctypes.rst:1637 +msgid "" +":meth:`!__getattr__` has special behavior: It allows loading a shared " +"library by accessing it as attribute of a library loader instance. The " +"result is cached, so repeated attribute accesses return the same library " +"each time." +msgstr "" + +#: ../../library/ctypes.rst:1643 +msgid "" +"Load a shared library into the process and return it. This method always " +"returns a new instance of the library." +msgstr "" + +#: ../../library/ctypes.rst:1647 +msgid "These prefabricated library loaders are available:" +msgstr "" + +#: ../../library/ctypes.rst:1652 +msgid "Creates :class:`CDLL` instances." +msgstr "" + +#: ../../library/ctypes.rst:1658 +msgid "Creates :class:`WinDLL` instances." +msgstr "" + +#: ../../library/ctypes.rst:1666 +msgid "Creates :class:`OleDLL` instances." +msgstr "" + +#: ../../library/ctypes.rst:1674 +msgid "Creates :class:`PyDLL` instances." +msgstr "" + +#: ../../library/ctypes.rst:1677 +msgid "" +"For accessing the C Python api directly, a ready-to-use Python shared " +"library object is available:" +msgstr "" + +#: ../../library/ctypes.rst:1683 +msgid "" +"An instance of :class:`PyDLL` that exposes Python C API functions as " +"attributes. Note that all these functions are assumed to return C :c:expr:" +"`int`, which is of course not always the truth, so you have to assign the " +"correct :attr:`!restype` attribute to use these functions." +msgstr "" + +#: ../../library/ctypes.rst:1688 ../../library/ctypes.rst:1690 +msgid "" +"Loading a library through any of these objects raises an :ref:`auditing " +"event ` ``ctypes.dlopen`` with string argument ``name``, the name " +"used to load the library." +msgstr "" + +#: ../../library/ctypes.rst:1694 ../../library/ctypes.rst:1696 +msgid "" +"Accessing a function on a loaded library raises an auditing event ``ctypes." +"dlsym`` with arguments ``library`` (the library object) and ``name`` (the " +"symbol's name as a string or integer)." +msgstr "" + +#: ../../library/ctypes.rst:1700 ../../library/ctypes.rst:1702 +msgid "" +"In cases when only the library handle is available rather than the object, " +"accessing a function raises an auditing event ``ctypes.dlsym/handle`` with " +"arguments ``handle`` (the raw library handle) and ``name``." +msgstr "" + +#: ../../library/ctypes.rst:1709 +msgid "Foreign functions" +msgstr "" + +#: ../../library/ctypes.rst:1711 +msgid "" +"As explained in the previous section, foreign functions can be accessed as " +"attributes of loaded shared libraries. The function objects created in this " +"way by default accept any number of arguments, accept any ctypes data " +"instances as arguments, and return the default result type specified by the " +"library loader." +msgstr "" + +#: ../../library/ctypes.rst:1716 +msgid "" +"They are instances of a private local class :class:`!_FuncPtr` (not exposed " +"in :mod:`!ctypes`) which inherits from the private :class:`_CFuncPtr` class:" +msgstr "" + +#: ../../library/ctypes.rst:1719 +msgid "" +">>> import ctypes\n" +">>> lib = ctypes.CDLL(None)\n" +">>> issubclass(lib._FuncPtr, ctypes._CFuncPtr)\n" +"True\n" +">>> lib._FuncPtr is ctypes._CFuncPtr\n" +"False" +msgstr "" +">>> import ctypes\n" +">>> lib = ctypes.CDLL(None)\n" +">>> issubclass(lib._FuncPtr, ctypes._CFuncPtr)\n" +"True\n" +">>> lib._FuncPtr is ctypes._CFuncPtr\n" +"False" + +#: ../../library/ctypes.rst:1730 +msgid "Base class for C callable foreign functions." +msgstr "" + +#: ../../library/ctypes.rst:1732 +msgid "" +"Instances of foreign functions are also C compatible data types; they " +"represent C function pointers." +msgstr "" + +#: ../../library/ctypes.rst:1735 +msgid "" +"This behavior can be customized by assigning to special attributes of the " +"foreign function object." +msgstr "" + +#: ../../library/ctypes.rst:1740 +msgid "" +"Assign a ctypes type to specify the result type of the foreign function. Use " +"``None`` for :c:expr:`void`, a function not returning anything." +msgstr "" + +#: ../../library/ctypes.rst:1743 +msgid "" +"It is possible to assign a callable Python object that is not a ctypes type, " +"in this case the function is assumed to return a C :c:expr:`int`, and the " +"callable will be called with this integer, allowing further processing or " +"error checking. Using this is deprecated, for more flexible post processing " +"or error checking use a ctypes data type as :attr:`!restype` and assign a " +"callable to the :attr:`errcheck` attribute." +msgstr "" + +#: ../../library/ctypes.rst:1752 +msgid "" +"Assign a tuple of ctypes types to specify the argument types that the " +"function accepts. Functions using the ``stdcall`` calling convention can " +"only be called with the same number of arguments as the length of this " +"tuple; functions using the C calling convention accept additional, " +"unspecified arguments as well." +msgstr "" + +#: ../../library/ctypes.rst:1758 +msgid "" +"When a foreign function is called, each actual argument is passed to the :" +"meth:`~_CData.from_param` class method of the items in the :attr:`argtypes` " +"tuple, this method allows adapting the actual argument to an object that the " +"foreign function accepts. For example, a :class:`c_char_p` item in the :" +"attr:`argtypes` tuple will convert a string passed as argument into a bytes " +"object using ctypes conversion rules." +msgstr "" + +#: ../../library/ctypes.rst:1765 +msgid "" +"New: It is now possible to put items in argtypes which are not ctypes types, " +"but each item must have a :meth:`~_CData.from_param` method which returns a " +"value usable as argument (integer, string, ctypes instance). This allows " +"defining adapters that can adapt custom objects as function parameters." +msgstr "" + +#: ../../library/ctypes.rst:1772 +msgid "" +"Assign a Python function or another callable to this attribute. The callable " +"will be called with three or more arguments:" +msgstr "" + +#: ../../library/ctypes.rst:1779 +msgid "" +"*result* is what the foreign function returns, as specified by the :attr:`!" +"restype` attribute." +msgstr "" + +#: ../../library/ctypes.rst:1782 +msgid "" +"*func* is the foreign function object itself, this allows reusing the same " +"callable object to check or post process the results of several functions." +msgstr "" + +#: ../../library/ctypes.rst:1786 +msgid "" +"*arguments* is a tuple containing the parameters originally passed to the " +"function call, this allows specializing the behavior on the arguments used." +msgstr "" + +#: ../../library/ctypes.rst:1790 +msgid "" +"The object that this function returns will be returned from the foreign " +"function call, but it can also check the result value and raise an exception " +"if the foreign function call failed." +msgstr "" + +#: ../../library/ctypes.rst:1795 ../../library/ctypes.rst:1797 +msgid "" +"On Windows, when a foreign function call raises a system exception (for " +"example, due to an access violation), it will be captured and replaced with " +"a suitable Python exception. Further, an auditing event ``ctypes." +"set_exception`` with argument ``code`` will be raised, allowing an audit " +"hook to replace the exception with its own." +msgstr "" + +#: ../../library/ctypes.rst:1803 ../../library/ctypes.rst:1805 +msgid "" +"Some ways to invoke foreign function calls as well as some of the functions " +"in this module may raise an auditing event ``ctypes.call_function`` with " +"arguments ``function pointer`` and ``arguments``." +msgstr "" + +#: ../../library/ctypes.rst:1812 +msgid "Function prototypes" +msgstr "" + +#: ../../library/ctypes.rst:1814 +msgid "" +"Foreign functions can also be created by instantiating function prototypes. " +"Function prototypes are similar to function prototypes in C; they describe a " +"function (return type, argument types, calling convention) without defining " +"an implementation. The factory functions must be called with the desired " +"result type and the argument types of the function, and can be used as " +"decorator factories, and as such, be applied to functions through the " +"``@wrapper`` syntax. See :ref:`ctypes-callback-functions` for examples." +msgstr "" + +#: ../../library/ctypes.rst:1825 +msgid "" +"The returned function prototype creates functions that use the standard C " +"calling convention. The function will release the GIL during the call. If " +"*use_errno* is set to true, the ctypes private copy of the system :data:" +"`errno` variable is exchanged with the real :data:`errno` value before and " +"after the call; *use_last_error* does the same for the Windows error code." +msgstr "" + +#: ../../library/ctypes.rst:1835 +msgid "" +"The returned function prototype creates functions that use the ``stdcall`` " +"calling convention. The function will release the GIL during the call. " +"*use_errno* and *use_last_error* have the same meaning as above." +msgstr "" + +#: ../../library/ctypes.rst:1845 +msgid "" +"The returned function prototype creates functions that use the Python " +"calling convention. The function will *not* release the GIL during the call." +msgstr "" + +#: ../../library/ctypes.rst:1848 +msgid "" +"Function prototypes created by these factory functions can be instantiated " +"in different ways, depending on the type and number of the parameters in the " +"call:" +msgstr "" + +#: ../../library/ctypes.rst:1855 +msgid "" +"Returns a foreign function at the specified address which must be an integer." +msgstr "" + +#: ../../library/ctypes.rst:1862 +msgid "" +"Create a C callable function (a callback function) from a Python *callable*." +msgstr "" + +#: ../../library/ctypes.rst:1869 +msgid "" +"Returns a foreign function exported by a shared library. *func_spec* must be " +"a 2-tuple ``(name_or_ordinal, library)``. The first item is the name of the " +"exported function as string, or the ordinal of the exported function as " +"small integer. The second item is the shared library instance." +msgstr "" + +#: ../../library/ctypes.rst:1879 +msgid "" +"Returns a foreign function that will call a COM method. *vtbl_index* is the " +"index into the virtual function table, a small non-negative integer. *name* " +"is name of the COM method. *iid* is an optional pointer to the interface " +"identifier which is used in extended error reporting." +msgstr "" + +#: ../../library/ctypes.rst:1884 +msgid "" +"If *iid* is not specified, an :exc:`OSError` is raised if the COM method " +"call fails. If *iid* is specified, a :exc:`~ctypes.COMError` is raised " +"instead." +msgstr "" + +#: ../../library/ctypes.rst:1888 +msgid "" +"COM methods use a special calling convention: They require a pointer to the " +"COM interface as first argument, in addition to those parameters that are " +"specified in the :attr:`!argtypes` tuple." +msgstr "" + +#: ../../library/ctypes.rst:1895 +msgid "" +"The optional *paramflags* parameter creates foreign function wrappers with " +"much more functionality than the features described above." +msgstr "" + +#: ../../library/ctypes.rst:1898 +msgid "" +"*paramflags* must be a tuple of the same length as :attr:`~_CFuncPtr." +"argtypes`." +msgstr "" + +#: ../../library/ctypes.rst:1900 +msgid "" +"Each item in this tuple contains further information about a parameter, it " +"must be a tuple containing one, two, or three items." +msgstr "" + +#: ../../library/ctypes.rst:1903 +msgid "" +"The first item is an integer containing a combination of direction flags for " +"the parameter:" +msgstr "" + +#: ../../library/ctypes.rst:1906 +msgid "1" +msgstr "1" + +#: ../../library/ctypes.rst:1907 +msgid "Specifies an input parameter to the function." +msgstr "" + +#: ../../library/ctypes.rst:1909 +msgid "2" +msgstr "2" + +#: ../../library/ctypes.rst:1910 +msgid "Output parameter. The foreign function fills in a value." +msgstr "" + +#: ../../library/ctypes.rst:1912 +msgid "4" +msgstr "4" + +#: ../../library/ctypes.rst:1913 +msgid "Input parameter which defaults to the integer zero." +msgstr "" + +#: ../../library/ctypes.rst:1915 +msgid "" +"The optional second item is the parameter name as string. If this is " +"specified, the foreign function can be called with named parameters." +msgstr "" + +#: ../../library/ctypes.rst:1918 +msgid "The optional third item is the default value for this parameter." +msgstr "" + +#: ../../library/ctypes.rst:1921 +msgid "" +"The following example demonstrates how to wrap the Windows ``MessageBoxW`` " +"function so that it supports default parameters and named arguments. The C " +"declaration from the windows header file is this::" +msgstr "" + +#: ../../library/ctypes.rst:1925 +msgid "" +"WINUSERAPI int WINAPI\n" +"MessageBoxW(\n" +" HWND hWnd,\n" +" LPCWSTR lpText,\n" +" LPCWSTR lpCaption,\n" +" UINT uType);" +msgstr "" +"WINUSERAPI int WINAPI\n" +"MessageBoxW(\n" +" HWND hWnd,\n" +" LPCWSTR lpText,\n" +" LPCWSTR lpCaption,\n" +" UINT uType);" + +#: ../../library/ctypes.rst:1932 ../../library/ctypes.rst:1955 +msgid "Here is the wrapping with :mod:`ctypes`::" +msgstr "" + +#: ../../library/ctypes.rst:1934 +msgid "" +">>> from ctypes import c_int, WINFUNCTYPE, windll\n" +">>> from ctypes.wintypes import HWND, LPCWSTR, UINT\n" +">>> prototype = WINFUNCTYPE(c_int, HWND, LPCWSTR, LPCWSTR, UINT)\n" +">>> paramflags = (1, \"hwnd\", 0), (1, \"text\", \"Hi\"), (1, \"caption\", " +"\"Hello from ctypes\"), (1, \"flags\", 0)\n" +">>> MessageBox = prototype((\"MessageBoxW\", windll.user32), paramflags)" +msgstr "" +">>> from ctypes import c_int, WINFUNCTYPE, windll\n" +">>> from ctypes.wintypes import HWND, LPCWSTR, UINT\n" +">>> prototype = WINFUNCTYPE(c_int, HWND, LPCWSTR, LPCWSTR, UINT)\n" +">>> paramflags = (1, \"hwnd\", 0), (1, \"text\", \"Hi\"), (1, \"caption\", " +"\"Hello from ctypes\"), (1, \"flags\", 0)\n" +">>> MessageBox = prototype((\"MessageBoxW\", windll.user32), paramflags)" + +#: ../../library/ctypes.rst:1940 +msgid "The ``MessageBox`` foreign function can now be called in these ways::" +msgstr "" + +#: ../../library/ctypes.rst:1942 +msgid "" +">>> MessageBox()\n" +">>> MessageBox(text=\"Spam, spam, spam\")\n" +">>> MessageBox(flags=2, text=\"foo bar\")" +msgstr "" +">>> MessageBox()\n" +">>> MessageBox(text=\"Spam, spam, spam\")\n" +">>> MessageBox(flags=2, text=\"foo bar\")" + +#: ../../library/ctypes.rst:1946 +msgid "" +"A second example demonstrates output parameters. The win32 " +"``GetWindowRect`` function retrieves the dimensions of a specified window by " +"copying them into ``RECT`` structure that the caller has to supply. Here is " +"the C declaration::" +msgstr "" + +#: ../../library/ctypes.rst:1950 +msgid "" +"WINUSERAPI BOOL WINAPI\n" +"GetWindowRect(\n" +" HWND hWnd,\n" +" LPRECT lpRect);" +msgstr "" +"WINUSERAPI BOOL WINAPI\n" +"GetWindowRect(\n" +" HWND hWnd,\n" +" LPRECT lpRect);" + +#: ../../library/ctypes.rst:1957 +msgid "" +">>> from ctypes import POINTER, WINFUNCTYPE, windll, WinError\n" +">>> from ctypes.wintypes import BOOL, HWND, RECT\n" +">>> prototype = WINFUNCTYPE(BOOL, HWND, POINTER(RECT))\n" +">>> paramflags = (1, \"hwnd\"), (2, \"lprect\")\n" +">>> GetWindowRect = prototype((\"GetWindowRect\", windll.user32), " +"paramflags)\n" +">>>" +msgstr "" +">>> from ctypes import POINTER, WINFUNCTYPE, windll, WinError\n" +">>> from ctypes.wintypes import BOOL, HWND, RECT\n" +">>> prototype = WINFUNCTYPE(BOOL, HWND, POINTER(RECT))\n" +">>> paramflags = (1, \"hwnd\"), (2, \"lprect\")\n" +">>> GetWindowRect = prototype((\"GetWindowRect\", windll.user32), " +"paramflags)\n" +">>>" + +#: ../../library/ctypes.rst:1964 +msgid "" +"Functions with output parameters will automatically return the output " +"parameter value if there is a single one, or a tuple containing the output " +"parameter values when there are more than one, so the GetWindowRect function " +"now returns a RECT instance, when called." +msgstr "" + +#: ../../library/ctypes.rst:1969 +msgid "" +"Output parameters can be combined with the :attr:`~_CFuncPtr.errcheck` " +"protocol to do further output processing and error checking. The win32 " +"``GetWindowRect`` api function returns a ``BOOL`` to signal success or " +"failure, so this function could do the error checking, and raises an " +"exception when the api call failed::" +msgstr "" + +#: ../../library/ctypes.rst:1974 +msgid "" +">>> def errcheck(result, func, args):\n" +"... if not result:\n" +"... raise WinError()\n" +"... return args\n" +"...\n" +">>> GetWindowRect.errcheck = errcheck\n" +">>>" +msgstr "" +">>> def errcheck(result, func, args):\n" +"... if not result:\n" +"... raise WinError()\n" +"... return args\n" +"...\n" +">>> GetWindowRect.errcheck = errcheck\n" +">>>" + +#: ../../library/ctypes.rst:1982 +msgid "" +"If the :attr:`~_CFuncPtr.errcheck` function returns the argument tuple it " +"receives unchanged, :mod:`ctypes` continues the normal processing it does on " +"the output parameters. If you want to return a tuple of window coordinates " +"instead of a ``RECT`` instance, you can retrieve the fields in the function " +"and return them instead, the normal processing will no longer take place::" +msgstr "" + +#: ../../library/ctypes.rst:1988 +msgid "" +">>> def errcheck(result, func, args):\n" +"... if not result:\n" +"... raise WinError()\n" +"... rc = args[1]\n" +"... return rc.left, rc.top, rc.bottom, rc.right\n" +"...\n" +">>> GetWindowRect.errcheck = errcheck\n" +">>>" +msgstr "" +">>> def errcheck(result, func, args):\n" +"... if not result:\n" +"... raise WinError()\n" +"... rc = args[1]\n" +"... return rc.left, rc.top, rc.bottom, rc.right\n" +"...\n" +">>> GetWindowRect.errcheck = errcheck\n" +">>>" + +#: ../../library/ctypes.rst:2001 +msgid "Utility functions" +msgstr "" + +#: ../../library/ctypes.rst:2005 +msgid "" +"Returns the address of the memory buffer as integer. *obj* must be an " +"instance of a ctypes type." +msgstr "" + +#: ../../library/ctypes.rst:2008 +msgid "" +"Raises an :ref:`auditing event ` ``ctypes.addressof`` with " +"argument ``obj``." +msgstr "" +"引發一個附帶引數 ``obj`` 的\\ :ref:`稽核事件 ` ``ctypes." +"addressof``。" + +#: ../../library/ctypes.rst:2013 +msgid "" +"Returns the alignment requirements of a ctypes type. *obj_or_type* must be a " +"ctypes type or instance." +msgstr "" + +#: ../../library/ctypes.rst:2019 +msgid "" +"Returns a light-weight pointer to *obj*, which must be an instance of a " +"ctypes type. *offset* defaults to zero, and must be an integer that will be " +"added to the internal pointer value." +msgstr "" + +#: ../../library/ctypes.rst:2023 +msgid "``byref(obj, offset)`` corresponds to this C code::" +msgstr "" + +#: ../../library/ctypes.rst:2025 +msgid "(((char *)&obj) + offset)" +msgstr "(((char *)&obj) + offset)" + +#: ../../library/ctypes.rst:2027 +msgid "" +"The returned object can only be used as a foreign function call parameter. " +"It behaves similar to ``pointer(obj)``, but the construction is a lot faster." +msgstr "" + +#: ../../library/ctypes.rst:2033 +msgid "" +"Copies a COM pointer from *src* to *dst* and returns the Windows specific :c:" +"type:`!HRESULT` value." +msgstr "" + +#: ../../library/ctypes.rst:2036 +msgid "" +"If *src* is not ``NULL``, its ``AddRef`` method is called, incrementing the " +"reference count." +msgstr "" + +#: ../../library/ctypes.rst:2039 +msgid "" +"In contrast, the reference count of *dst* will not be decremented before " +"assigning the new value. Unless *dst* is ``NULL``, the caller is responsible " +"for decrementing the reference count by calling its ``Release`` method when " +"necessary." +msgstr "" + +#: ../../library/ctypes.rst:2051 +msgid "" +"This function is similar to the cast operator in C. It returns a new " +"instance of *type* which points to the same memory block as *obj*. *type* " +"must be a pointer type, and *obj* must be an object that can be interpreted " +"as a pointer." +msgstr "" + +#: ../../library/ctypes.rst:2060 +msgid "" +"This function creates a mutable character buffer. The returned object is a " +"ctypes array of :class:`c_char`." +msgstr "" + +#: ../../library/ctypes.rst:2063 +msgid "" +"If *size* is given (and not ``None``), it must be an :class:`int`. It " +"specifies the size of the returned array." +msgstr "" + +#: ../../library/ctypes.rst:2066 +msgid "" +"If the *init* argument is given, it must be :class:`bytes`. It is used to " +"initialize the array items. Bytes not initialized this way are set to zero " +"(NUL)." +msgstr "" + +#: ../../library/ctypes.rst:2070 +msgid "" +"If *size* is not given (or if it is ``None``), the buffer is made one " +"element larger than *init*, effectively adding a NUL terminator." +msgstr "" + +#: ../../library/ctypes.rst:2073 +msgid "" +"If both arguments are given, *size* must not be less than ``len(init)``." +msgstr "如果兩個引數皆有提供，*size* 不得小於 ``len(init)``。" + +#: ../../library/ctypes.rst:2077 +msgid "" +"If *size* is equal to ``len(init)``, a NUL terminator is not added. Do not " +"treat such a buffer as a C string." +msgstr "" + +#: ../../library/ctypes.rst:2080 +msgid "For example::" +msgstr "舉例來說： ::" + +#: ../../library/ctypes.rst:2082 +msgid "" +">>> bytes(create_string_buffer(2))\n" +"b'\\x00\\x00'\n" +">>> bytes(create_string_buffer(b'ab'))\n" +"b'ab\\x00'\n" +">>> bytes(create_string_buffer(b'ab', 2))\n" +"b'ab'\n" +">>> bytes(create_string_buffer(b'ab', 4))\n" +"b'ab\\x00\\x00'\n" +">>> bytes(create_string_buffer(b'abcdef', 2))\n" +"Traceback (most recent call last):\n" +" ...\n" +"ValueError: byte string too long" +msgstr "" +">>> bytes(create_string_buffer(2))\n" +"b'\\x00\\x00'\n" +">>> bytes(create_string_buffer(b'ab'))\n" +"b'ab\\x00'\n" +">>> bytes(create_string_buffer(b'ab', 2))\n" +"b'ab'\n" +">>> bytes(create_string_buffer(b'ab', 4))\n" +"b'ab\\x00\\x00'\n" +">>> bytes(create_string_buffer(b'abcdef', 2))\n" +"Traceback (most recent call last):\n" +" ...\n" +"ValueError: byte string too long" + +#: ../../library/ctypes.rst:2095 +msgid "" +"Raises an :ref:`auditing event ` ``ctypes.create_string_buffer`` " +"with arguments ``init``, ``size``." +msgstr "" +"引發一個附帶引數 ``init`` 與 ``size`` 的\\ :ref:`稽核事件 ` " +"``ctypes.create_string_buffer``。" + +#: ../../library/ctypes.rst:2101 +msgid "" +"This function creates a mutable unicode character buffer. The returned " +"object is a ctypes array of :class:`c_wchar`." +msgstr "" + +#: ../../library/ctypes.rst:2104 +msgid "" +"The function takes the same arguments as :func:`~create_string_buffer` " +"except *init* must be a string and *size* counts :class:`c_wchar`." +msgstr "" + +#: ../../library/ctypes.rst:2107 +msgid "" +"Raises an :ref:`auditing event ` ``ctypes.create_unicode_buffer`` " +"with arguments ``init``, ``size``." +msgstr "" +"引發一個附帶引數 ``init`` 與 ``size`` 的\\ :ref:`稽核事件 ` " +"``ctypes.create_unicode_buffer``。" + +#: ../../library/ctypes.rst:2112 +msgid "" +"This function is a hook which allows implementing in-process COM servers " +"with ctypes. It is called from the DllCanUnloadNow function that the " +"_ctypes extension dll exports." +msgstr "" + +#: ../../library/ctypes.rst:2121 +msgid "" +"This function is a hook which allows implementing in-process COM servers " +"with ctypes. It is called from the DllGetClassObject function that the " +"``_ctypes`` extension dll exports." +msgstr "" + +#: ../../library/ctypes.rst:2131 +msgid "" +"Try to find a library and return a pathname. *name* is the library name " +"without any prefix like ``lib``, suffix like ``.so``, ``.dylib`` or version " +"number (this is the form used for the posix linker option :option:`!-l`). " +"If no library can be found, returns ``None``." +msgstr "" + +#: ../../library/ctypes.rst:2138 +msgid "See :ref:`ctypes-finding-shared-libraries` for complete documentation." +msgstr "" + +#: ../../library/ctypes.rst:2144 +msgid "" +"Returns the filename of the VC runtime library used by Python, and by the " +"extension modules. If the name of the library cannot be determined, " +"``None`` is returned." +msgstr "" + +#: ../../library/ctypes.rst:2148 +msgid "" +"If you need to free memory, for example, allocated by an extension module " +"with a call to the ``free(void *)``, it is important that you use the " +"function in the same library that allocated the memory." +msgstr "" + +#: ../../library/ctypes.rst:2158 +msgid "" +"Try to provide a list of paths of the shared libraries loaded into the " +"current process. These paths are not normalized or processed in any way. " +"The function can raise :exc:`OSError` if the underlying platform APIs fail. " +"The exact functionality is system dependent." +msgstr "" + +#: ../../library/ctypes.rst:2163 +msgid "" +"On most platforms, the first element of the list represents the current " +"executable file. It may be an empty string." +msgstr "" + +#: ../../library/ctypes.rst:2171 +msgid "" +"Returns a textual description of the error code *code*. If no error code is " +"specified, the last error code is used by calling the Windows API function :" +"func:`GetLastError`." +msgstr "" + +#: ../../library/ctypes.rst:2180 +msgid "" +"Returns the last error code set by Windows in the calling thread. This " +"function calls the Windows ``GetLastError()`` function directly, it does not " +"return the ctypes-private copy of the error code." +msgstr "" + +#: ../../library/ctypes.rst:2189 +msgid "" +"Returns the current value of the ctypes-private copy of the system :data:" +"`errno` variable in the calling thread." +msgstr "" + +#: ../../library/ctypes.rst:2192 +msgid "" +"Raises an :ref:`auditing event ` ``ctypes.get_errno`` with no " +"arguments." +msgstr "" +"引發一個不附帶引數的\\ :ref:`稽核事件 ` ``ctypes.get_errno``。" + +#: ../../library/ctypes.rst:2196 +msgid "" +"Returns the current value of the ctypes-private copy of the system :data:`!" +"LastError` variable in the calling thread." +msgstr "" + +#: ../../library/ctypes.rst:2201 +msgid "" +"Raises an :ref:`auditing event ` ``ctypes.get_last_error`` with no " +"arguments." +msgstr "" +"引發一個不附帶引數的\\ :ref:`稽核事件 ` ``ctypes.get_last_error``。" + +#: ../../library/ctypes.rst:2206 +msgid "" +"Same as the standard C memmove library function: copies *count* bytes from " +"*src* to *dst*. *dst* and *src* must be integers or ctypes instances that " +"can be converted to pointers." +msgstr "" + +#: ../../library/ctypes.rst:2213 +msgid "" +"Same as the standard C memset library function: fills the memory block at " +"address *dst* with *count* bytes of value *c*. *dst* must be an integer " +"specifying an address, or a ctypes instance." +msgstr "" + +#: ../../library/ctypes.rst:2220 +msgid "" +"Create or return a ctypes pointer type. Pointer types are cached and reused " +"internally, so calling this function repeatedly is cheap. *type* must be a " +"ctypes type." +msgstr "" + +#: ../../library/ctypes.rst:2226 +msgid "" +"The resulting pointer type is cached in the ``__pointer_type__`` attribute " +"of *type*. It is possible to set this attribute before the first call to " +"``POINTER`` in order to set a custom pointer type. However, doing this is " +"discouraged: manually creating a suitable pointer type is difficult without " +"relying on implementation details that may change in future Python versions." +msgstr "" + +#: ../../library/ctypes.rst:2237 +msgid "" +"Create a new pointer instance, pointing to *obj*. The returned object is of " +"the type ``POINTER(type(obj))``." +msgstr "" + +#: ../../library/ctypes.rst:2240 +msgid "" +"Note: If you just want to pass a pointer to an object to a foreign function " +"call, you should use ``byref(obj)`` which is much faster." +msgstr "" + +#: ../../library/ctypes.rst:2246 +msgid "" +"This function resizes the internal memory buffer of *obj*, which must be an " +"instance of a ctypes type. It is not possible to make the buffer smaller " +"than the native size of the objects type, as given by ``sizeof(type(obj))``, " +"but it is possible to enlarge the buffer." +msgstr "" + +#: ../../library/ctypes.rst:2254 +msgid "" +"Set the current value of the ctypes-private copy of the system :data:`errno` " +"variable in the calling thread to *value* and return the previous value." +msgstr "" + +#: ../../library/ctypes.rst:2257 +msgid "" +"Raises an :ref:`auditing event ` ``ctypes.set_errno`` with " +"argument ``errno``." +msgstr "" +"引發一個附帶引數 ``errno`` 的\\ :ref:`稽核事件 ` ``ctypes." +"set_errno``。" + +#: ../../library/ctypes.rst:2262 +msgid "" +"Sets the current value of the ctypes-private copy of the system :data:`!" +"LastError` variable in the calling thread to *value* and return the previous " +"value." +msgstr "" + +#: ../../library/ctypes.rst:2268 +msgid "" +"Raises an :ref:`auditing event ` ``ctypes.set_last_error`` with " +"argument ``error``." +msgstr "" +"引發一個附帶引數 ``error`` 的\\ :ref:`稽核事件 ` ``ctypes." +"set_last_error``。" + +#: ../../library/ctypes.rst:2273 +msgid "" +"Returns the size in bytes of a ctypes type or instance memory buffer. Does " +"the same as the C ``sizeof`` operator." +msgstr "" + +#: ../../library/ctypes.rst:2279 +msgid "" +"Return the byte string at *void \\*ptr*. If *size* is specified, it is used " +"as size, otherwise the string is assumed to be zero-terminated." +msgstr "" + +#: ../../library/ctypes.rst:2283 +msgid "" +"Raises an :ref:`auditing event ` ``ctypes.string_at`` with " +"arguments ``ptr``, ``size``." +msgstr "" +"引發一個附帶引數 ``ptr``、``size`` 的\\ :ref:`稽核事件 ` ``ctypes." +"string_at``。" + +#: ../../library/ctypes.rst:2288 +msgid "" +"Creates an instance of :exc:`OSError`. If *code* is not specified, :func:" +"`GetLastError` is called to determine the error code. If *descr* is not " +"specified, :func:`FormatError` is called to get a textual description of the " +"error." +msgstr "" + +#: ../../library/ctypes.rst:2295 +msgid "" +"An instance of :exc:`WindowsError` used to be created, which is now an alias " +"of :exc:`OSError`." +msgstr "" + +#: ../../library/ctypes.rst:2302 +msgid "" +"Return the wide-character string at *void \\*ptr*. If *size* is specified, " +"it is used as the number of characters of the string, otherwise the string " +"is assumed to be zero-terminated." +msgstr "" + +#: ../../library/ctypes.rst:2307 +msgid "" +"Raises an :ref:`auditing event ` ``ctypes.wstring_at`` with " +"arguments ``ptr``, ``size``." +msgstr "" +"引發一個附帶引數 ``ptr``、``size`` 的\\ :ref:`稽核事件 ` ``ctypes." +"wstring_at``。" + +#: ../../library/ctypes.rst:2312 +msgid "" +"Return a :class:`memoryview` object of length *size* that references memory " +"starting at *void \\*ptr*." +msgstr "" + +#: ../../library/ctypes.rst:2315 +msgid "" +"If *readonly* is true, the returned :class:`!memoryview` object can not be " +"used to modify the underlying memory. (Changes made by other means will " +"still be reflected in the returned object.)" +msgstr "" + +#: ../../library/ctypes.rst:2320 +msgid "" +"This function is similar to :func:`string_at` with the key difference of not " +"making a copy of the specified memory. It is a semantically equivalent (but " +"more efficient) alternative to ``memoryview((c_byte * size)." +"from_address(ptr))``. (While :meth:`~_CData.from_address` only takes " +"integers, *ptr* can also be given as a :class:`ctypes.POINTER` or a :func:" +"`~ctypes.byref` object.)" +msgstr "" + +#: ../../library/ctypes.rst:2327 +msgid "" +"Raises an :ref:`auditing event ` ``ctypes.memoryview_at`` with " +"arguments ``address``, ``size``, ``readonly``." +msgstr "" +"引發一個附帶引數 ``address``、``size`` 與 ``readonly`` 的\\ :ref:`稽核事件 " +"` ``ctypes.memoryview_at``。" + +#: ../../library/ctypes.rst:2335 +msgid "Data types" +msgstr "" + +#: ../../library/ctypes.rst:2340 +msgid "" +"This non-public class is the common base class of all ctypes data types. " +"Among other things, all ctypes type instances contain a memory block that " +"hold C compatible data; the address of the memory block is returned by the :" +"func:`addressof` helper function. Another instance variable is exposed as :" +"attr:`_objects`; this contains other Python objects that need to be kept " +"alive in case the memory block contains pointers." +msgstr "" + +#: ../../library/ctypes.rst:2347 +msgid "" +"Common methods of ctypes data types, these are all class methods (to be " +"exact, they are methods of the :term:`metaclass`):" +msgstr "" + +#: ../../library/ctypes.rst:2352 +msgid "" +"This method returns a ctypes instance that shares the buffer of the *source* " +"object. The *source* object must support the writeable buffer interface. " +"The optional *offset* parameter specifies an offset into the source buffer " +"in bytes; the default is zero. If the source buffer is not large enough a :" +"exc:`ValueError` is raised." +msgstr "" + +#: ../../library/ctypes.rst:2358 ../../library/ctypes.rst:2368 +msgid "" +"Raises an :ref:`auditing event ` ``ctypes.cdata/buffer`` with " +"arguments ``pointer``, ``size``, ``offset``." +msgstr "" +"引發一個附帶引數 ``pointer``、``size``、``offset`` 的\\ :ref:`稽核事件 " +"` ``ctypes.cdata/buffer``。" + +#: ../../library/ctypes.rst:2362 +msgid "" +"This method creates a ctypes instance, copying the buffer from the *source* " +"object buffer which must be readable. The optional *offset* parameter " +"specifies an offset into the source buffer in bytes; the default is zero. " +"If the source buffer is not large enough a :exc:`ValueError` is raised." +msgstr "" + +#: ../../library/ctypes.rst:2372 +msgid "" +"This method returns a ctypes type instance using the memory specified by " +"*address* which must be an integer." +msgstr "" + +#: ../../library/ctypes.rst:2375 ../../library/ctypes.rst:2377 +msgid "" +"This method, and others that indirectly call this method, raises an :ref:" +"`auditing event ` ``ctypes.cdata`` with argument ``address``." +msgstr "" + +#: ../../library/ctypes.rst:2383 +msgid "" +"This method adapts *obj* to a ctypes type. It is called with the actual " +"object used in a foreign function call when the type is present in the " +"foreign function's :attr:`~_CFuncPtr.argtypes` tuple; it must return an " +"object that can be used as a function call parameter." +msgstr "" + +#: ../../library/ctypes.rst:2388 +msgid "" +"All ctypes data types have a default implementation of this classmethod that " +"normally returns *obj* if that is an instance of the type. Some types " +"accept other objects as well." +msgstr "" + +#: ../../library/ctypes.rst:2394 +msgid "" +"This method returns a ctypes type instance exported by a shared library. " +"*name* is the name of the symbol that exports the data, *library* is the " +"loaded shared library." +msgstr "" + +#: ../../library/ctypes.rst:2398 +msgid "Common class variables of ctypes data types:" +msgstr "" + +#: ../../library/ctypes.rst:2402 +msgid "" +"The pointer type that was created by calling :func:`POINTER` for " +"corresponding ctypes data type. If a pointer type was not yet created, the " +"attribute is missing." +msgstr "" + +#: ../../library/ctypes.rst:2408 +msgid "Common instance variables of ctypes data types:" +msgstr "" + +#: ../../library/ctypes.rst:2412 +msgid "" +"Sometimes ctypes data instances do not own the memory block they contain, " +"instead they share part of the memory block of a base object. The :attr:" +"`_b_base_` read-only member is the root ctypes object that owns the memory " +"block." +msgstr "" + +#: ../../library/ctypes.rst:2419 +msgid "" +"This read-only variable is true when the ctypes data instance has allocated " +"the memory block itself, false otherwise." +msgstr "" + +#: ../../library/ctypes.rst:2424 +msgid "" +"This member is either ``None`` or a dictionary containing Python objects " +"that need to be kept alive so that the memory block contents is kept valid. " +"This object is only exposed for debugging; never modify the contents of this " +"dictionary." +msgstr "" + +#: ../../library/ctypes.rst:2437 +msgid "" +"This non-public class is the base class of all fundamental ctypes data " +"types. It is mentioned here because it contains the common attributes of the " +"fundamental ctypes data types. :class:`_SimpleCData` is a subclass of :" +"class:`_CData`, so it inherits their methods and attributes. ctypes data " +"types that are not and do not contain pointers can now be pickled." +msgstr "" + +#: ../../library/ctypes.rst:2443 +msgid "Instances have a single attribute:" +msgstr "" + +#: ../../library/ctypes.rst:2447 +msgid "" +"This attribute contains the actual value of the instance. For integer and " +"pointer types, it is an integer, for character types, it is a single " +"character bytes object or string, for character pointer types it is a Python " +"bytes object or string." +msgstr "" + +#: ../../library/ctypes.rst:2452 +msgid "" +"When the ``value`` attribute is retrieved from a ctypes instance, usually a " +"new object is returned each time. :mod:`ctypes` does *not* implement " +"original object return, always a new object is constructed. The same is " +"true for all other ctypes object instances." +msgstr "" + +#: ../../library/ctypes.rst:2458 +msgid "" +"Fundamental data types, when returned as foreign function call results, or, " +"for example, by retrieving structure field members or array items, are " +"transparently converted to native Python types. In other words, if a " +"foreign function has a :attr:`~_CFuncPtr.restype` of :class:`c_char_p`, you " +"will always receive a Python bytes object, *not* a :class:`c_char_p` " +"instance." +msgstr "" + +#: ../../library/ctypes.rst:2466 +msgid "" +"Subclasses of fundamental data types do *not* inherit this behavior. So, if " +"a foreign functions :attr:`!restype` is a subclass of :class:`c_void_p`, you " +"will receive an instance of this subclass from the function call. Of course, " +"you can get the value of the pointer by accessing the ``value`` attribute." +msgstr "" + +#: ../../library/ctypes.rst:2471 +msgid "These are the fundamental ctypes data types:" +msgstr "" + +#: ../../library/ctypes.rst:2475 +msgid "" +"Represents the C :c:expr:`signed char` datatype, and interprets the value as " +"small integer. The constructor accepts an optional integer initializer; no " +"overflow checking is done." +msgstr "" + +#: ../../library/ctypes.rst:2482 +msgid "" +"Represents the C :c:expr:`char` datatype, and interprets the value as a " +"single character. The constructor accepts an optional string initializer, " +"the length of the string must be exactly one character." +msgstr "" + +#: ../../library/ctypes.rst:2489 +msgid "" +"Represents the C :c:expr:`char *` datatype when it points to a zero-" +"terminated string. For a general character pointer that may also point to " +"binary data, ``POINTER(c_char)`` must be used. The constructor accepts an " +"integer address, or a bytes object." +msgstr "" + +#: ../../library/ctypes.rst:2497 +msgid "" +"Represents the C :c:expr:`double` datatype. The constructor accepts an " +"optional float initializer." +msgstr "" + +#: ../../library/ctypes.rst:2503 +msgid "" +"Represents the C :c:expr:`long double` datatype. The constructor accepts an " +"optional float initializer. On platforms where ``sizeof(long double) == " +"sizeof(double)`` it is an alias to :class:`c_double`." +msgstr "" + +#: ../../library/ctypes.rst:2509 +msgid "" +"Represents the C :c:expr:`float` datatype. The constructor accepts an " +"optional float initializer." +msgstr "" + +#: ../../library/ctypes.rst:2515 +msgid "" +"Represents the C :c:expr:`double complex` datatype, if available. The " +"constructor accepts an optional :class:`complex` initializer." +msgstr "" + +#: ../../library/ctypes.rst:2523 +msgid "" +"Represents the C :c:expr:`float complex` datatype, if available. The " +"constructor accepts an optional :class:`complex` initializer." +msgstr "" + +#: ../../library/ctypes.rst:2531 +msgid "" +"Represents the C :c:expr:`long double complex` datatype, if available. The " +"constructor accepts an optional :class:`complex` initializer." +msgstr "" + +#: ../../library/ctypes.rst:2539 +msgid "" +"Represents the C :c:expr:`signed int` datatype. The constructor accepts an " +"optional integer initializer; no overflow checking is done. On platforms " +"where ``sizeof(int) == sizeof(long)`` it is an alias to :class:`c_long`." +msgstr "" + +#: ../../library/ctypes.rst:2546 +msgid "" +"Represents the C 8-bit :c:expr:`signed int` datatype. It is an alias for :" +"class:`c_byte`." +msgstr "" + +#: ../../library/ctypes.rst:2552 +msgid "" +"Represents the C 16-bit :c:expr:`signed int` datatype. Usually an alias " +"for :class:`c_short`." +msgstr "" + +#: ../../library/ctypes.rst:2558 +msgid "" +"Represents the C 32-bit :c:expr:`signed int` datatype. Usually an alias " +"for :class:`c_int`." +msgstr "" + +#: ../../library/ctypes.rst:2564 +msgid "" +"Represents the C 64-bit :c:expr:`signed int` datatype. Usually an alias " +"for :class:`c_longlong`." +msgstr "" + +#: ../../library/ctypes.rst:2570 +msgid "" +"Represents the C :c:expr:`signed long` datatype. The constructor accepts an " +"optional integer initializer; no overflow checking is done." +msgstr "" + +#: ../../library/ctypes.rst:2576 +msgid "" +"Represents the C :c:expr:`signed long long` datatype. The constructor " +"accepts an optional integer initializer; no overflow checking is done." +msgstr "" + +#: ../../library/ctypes.rst:2582 +msgid "" +"Represents the C :c:expr:`signed short` datatype. The constructor accepts " +"an optional integer initializer; no overflow checking is done." +msgstr "" + +#: ../../library/ctypes.rst:2588 +msgid "Represents the C :c:type:`size_t` datatype." +msgstr "" + +#: ../../library/ctypes.rst:2593 +msgid "Represents the C :c:type:`ssize_t` datatype." +msgstr "" + +#: ../../library/ctypes.rst:2600 +msgid "Represents the C :c:type:`time_t` datatype." +msgstr "" + +#: ../../library/ctypes.rst:2607 +msgid "" +"Represents the C :c:expr:`unsigned char` datatype, it interprets the value " +"as small integer. The constructor accepts an optional integer initializer; " +"no overflow checking is done." +msgstr "" + +#: ../../library/ctypes.rst:2614 +msgid "" +"Represents the C :c:expr:`unsigned int` datatype. The constructor accepts " +"an optional integer initializer; no overflow checking is done. On platforms " +"where ``sizeof(int) == sizeof(long)`` it is an alias for :class:`c_ulong`." +msgstr "" + +#: ../../library/ctypes.rst:2621 +msgid "" +"Represents the C 8-bit :c:expr:`unsigned int` datatype. It is an alias for :" +"class:`c_ubyte`." +msgstr "" + +#: ../../library/ctypes.rst:2627 +msgid "" +"Represents the C 16-bit :c:expr:`unsigned int` datatype. Usually an alias " +"for :class:`c_ushort`." +msgstr "" + +#: ../../library/ctypes.rst:2633 +msgid "" +"Represents the C 32-bit :c:expr:`unsigned int` datatype. Usually an alias " +"for :class:`c_uint`." +msgstr "" + +#: ../../library/ctypes.rst:2639 +msgid "" +"Represents the C 64-bit :c:expr:`unsigned int` datatype. Usually an alias " +"for :class:`c_ulonglong`." +msgstr "" + +#: ../../library/ctypes.rst:2645 +msgid "" +"Represents the C :c:expr:`unsigned long` datatype. The constructor accepts " +"an optional integer initializer; no overflow checking is done." +msgstr "" + +#: ../../library/ctypes.rst:2651 +msgid "" +"Represents the C :c:expr:`unsigned long long` datatype. The constructor " +"accepts an optional integer initializer; no overflow checking is done." +msgstr "" + +#: ../../library/ctypes.rst:2657 +msgid "" +"Represents the C :c:expr:`unsigned short` datatype. The constructor accepts " +"an optional integer initializer; no overflow checking is done." +msgstr "" + +#: ../../library/ctypes.rst:2663 +msgid "" +"Represents the C :c:expr:`void *` type. The value is represented as " +"integer. The constructor accepts an optional integer initializer." +msgstr "" + +#: ../../library/ctypes.rst:2669 +msgid "" +"Represents the C :c:type:`wchar_t` datatype, and interprets the value as a " +"single character unicode string. The constructor accepts an optional string " +"initializer, the length of the string must be exactly one character." +msgstr "" + +#: ../../library/ctypes.rst:2676 +msgid "" +"Represents the C :c:expr:`wchar_t *` datatype, which must be a pointer to a " +"zero-terminated wide character string. The constructor accepts an integer " +"address, or a string." +msgstr "" + +#: ../../library/ctypes.rst:2683 +msgid "" +"Represent the C :c:expr:`bool` datatype (more accurately, :c:expr:`_Bool` " +"from C99). Its value can be ``True`` or ``False``, and the constructor " +"accepts any object that has a truth value." +msgstr "" + +#: ../../library/ctypes.rst:2690 +msgid "" +"Represents a :c:type:`!HRESULT` value, which contains success or error " +"information for a function or method call." +msgstr "" + +#: ../../library/ctypes.rst:2698 +msgid "" +"Represents the C :c:expr:`PyObject *` datatype. Calling this without an " +"argument creates a ``NULL`` :c:expr:`PyObject *` pointer." +msgstr "" + +#: ../../library/ctypes.rst:2701 +msgid ":class:`!py_object` is now a :term:`generic type`." +msgstr "" + +#: ../../library/ctypes.rst:2704 +msgid "" +"The :mod:`!ctypes.wintypes` module provides quite some other Windows " +"specific data types, for example :c:type:`!HWND`, :c:type:`!WPARAM`, or :c:" +"type:`!DWORD`. Some useful structures like :c:type:`!MSG` or :c:type:`!RECT` " +"are also defined." +msgstr "" + +#: ../../library/ctypes.rst:2712 +msgid "Structured data types" +msgstr "" + +#: ../../library/ctypes.rst:2717 +msgid "Abstract base class for unions in native byte order." +msgstr "" + +#: ../../library/ctypes.rst:2719 +msgid "" +"Unions share common attributes and behavior with structures; see :class:" +"`Structure` documentation for details." +msgstr "" + +#: ../../library/ctypes.rst:2724 +msgid "Abstract base class for unions in *big endian* byte order." +msgstr "" + +#: ../../library/ctypes.rst:2730 +msgid "Abstract base class for unions in *little endian* byte order." +msgstr "" + +#: ../../library/ctypes.rst:2736 +msgid "Abstract base class for structures in *big endian* byte order." +msgstr "" + +#: ../../library/ctypes.rst:2741 +msgid "Abstract base class for structures in *little endian* byte order." +msgstr "" + +#: ../../library/ctypes.rst:2743 +msgid "" +"Structures and unions with non-native byte order cannot contain pointer type " +"fields, or any other data types containing pointer type fields." +msgstr "" + +#: ../../library/ctypes.rst:2749 +msgid "Abstract base class for structures in *native* byte order." +msgstr "" + +#: ../../library/ctypes.rst:2751 +msgid "" +"Concrete structure and union types must be created by subclassing one of " +"these types, and at least define a :attr:`_fields_` class variable. :mod:" +"`ctypes` will create :term:`descriptor`\\s which allow reading and writing " +"the fields by direct attribute accesses. These are the" +msgstr "" + +#: ../../library/ctypes.rst:2759 +msgid "" +"A sequence defining the structure fields. The items must be 2-tuples or 3-" +"tuples. The first item is the name of the field, the second item specifies " +"the type of the field; it can be any ctypes data type." +msgstr "" + +#: ../../library/ctypes.rst:2763 +msgid "" +"For integer type fields like :class:`c_int`, a third optional item can be " +"given. It must be a small positive integer defining the bit width of the " +"field." +msgstr "" + +#: ../../library/ctypes.rst:2767 +msgid "" +"Field names must be unique within one structure or union. This is not " +"checked, only one field can be accessed when names are repeated." +msgstr "" + +#: ../../library/ctypes.rst:2770 +msgid "" +"It is possible to define the :attr:`_fields_` class variable *after* the " +"class statement that defines the Structure subclass, this allows creating " +"data types that directly or indirectly reference themselves::" +msgstr "" + +#: ../../library/ctypes.rst:2774 +msgid "" +"class List(Structure):\n" +" pass\n" +"List._fields_ = [(\"pnext\", POINTER(List)),\n" +" ...\n" +" ]" +msgstr "" +"class List(Structure):\n" +" pass\n" +"List._fields_ = [(\"pnext\", POINTER(List)),\n" +" ...\n" +" ]" + +#: ../../library/ctypes.rst:2780 +msgid "" +"The :attr:`!_fields_` class variable can only be set once. Later assignments " +"will raise an :exc:`AttributeError`." +msgstr "" + +#: ../../library/ctypes.rst:2783 +msgid "" +"Additionally, the :attr:`!_fields_` class variable must be defined before " +"the structure or union type is first used: an instance or subclass is " +"created, :func:`sizeof` is called on it, and so on. Later assignments to :" +"attr:`!_fields_` will raise an :exc:`AttributeError`. If :attr:`!_fields_` " +"has not been set before such use, the structure or union will have no own " +"fields, as if :attr:`!_fields_` was empty." +msgstr "" + +#: ../../library/ctypes.rst:2791 +msgid "" +"Sub-subclasses of structure types inherit the fields of the base class plus " +"the :attr:`_fields_` defined in the sub-subclass, if any." +msgstr "" + +#: ../../library/ctypes.rst:2797 +msgid "" +"An optional small integer that allows overriding the alignment of structure " +"fields in the instance." +msgstr "" + +#: ../../library/ctypes.rst:2800 +msgid "" +"This is only implemented for the MSVC-compatible memory layout (see :attr:" +"`_layout_`)." +msgstr "" + +#: ../../library/ctypes.rst:2803 +msgid "" +"Setting :attr:`!_pack_` to 0 is the same as not setting it at all. " +"Otherwise, the value must be a positive power of two. The effect is " +"equivalent to ``#pragma pack(N)`` in C, except :mod:`ctypes` may allow " +"larger *n* than what the compiler accepts." +msgstr "" + +#: ../../library/ctypes.rst:2808 +msgid "" +":attr:`!_pack_` must already be defined when :attr:`_fields_` is assigned, " +"otherwise it will have no effect." +msgstr "" + +#: ../../library/ctypes.rst:2813 +msgid "" +"For historical reasons, if :attr:`!_pack_` is non-zero, the MSVC-compatible " +"layout will be used by default. On non-Windows platforms, this default is " +"deprecated and is slated to become an error in Python 3.19. If it is " +"intended, set :attr:`~Structure._layout_` to ``'ms'`` explicitly." +msgstr "" + +#: ../../library/ctypes.rst:2822 +msgid "" +"An optional small integer that allows increasing the alignment of the " +"structure when being packed or unpacked to/from memory." +msgstr "" + +#: ../../library/ctypes.rst:2825 +msgid "" +"The value must not be negative. The effect is equivalent to " +"``__attribute__((aligned(N)))`` on GCC or ``#pragma align(N)`` on MSVC, " +"except :mod:`ctypes` may allow values that the compiler would reject." +msgstr "" + +#: ../../library/ctypes.rst:2830 +msgid "" +":attr:`!_align_` can only *increase* a structure's alignment requirements. " +"Setting it to 0 or 1 has no effect." +msgstr "" + +#: ../../library/ctypes.rst:2833 +msgid "" +"Using values that are not powers of two is discouraged and may lead to " +"surprising behavior." +msgstr "" + +#: ../../library/ctypes.rst:2836 +msgid "" +":attr:`!_align_` must already be defined when :attr:`_fields_` is assigned, " +"otherwise it will have no effect." +msgstr "" + +#: ../../library/ctypes.rst:2843 +msgid "" +"An optional string naming the struct/union layout. It can currently be set " +"to:" +msgstr "" + +#: ../../library/ctypes.rst:2846 +msgid "" +"``\"ms\"``: the layout used by the Microsoft compiler (MSVC). On GCC and " +"Clang, this layout can be selected with ``__attribute__((ms_struct))``." +msgstr "" + +#: ../../library/ctypes.rst:2849 +msgid "" +"``\"gcc-sysv\"``: the layout used by GCC with the System V or “SysV-like” " +"data model, as used on Linux and macOS. With this layout, :attr:`~Structure." +"_pack_` must be unset or zero." +msgstr "" + +#: ../../library/ctypes.rst:2853 +msgid "" +"If not set explicitly, ``ctypes`` will use a default that matches the " +"platform conventions. This default may change in future Python releases (for " +"example, when a new platform gains official support, or when a difference " +"between similar platforms is found). Currently the default will be:" +msgstr "" + +#: ../../library/ctypes.rst:2859 +msgid "On Windows: ``\"ms\"``" +msgstr "" + +#: ../../library/ctypes.rst:2860 +msgid "" +"When :attr:`~Structure._pack_` is specified: ``\"ms\"``. (This is " +"deprecated; see :attr:`~Structure._pack_` documentation.)" +msgstr "" + +#: ../../library/ctypes.rst:2862 +msgid "Otherwise: ``\"gcc-sysv\"``" +msgstr "" + +#: ../../library/ctypes.rst:2864 +msgid "" +":attr:`!_layout_` must already be defined when :attr:`~Structure._fields_` " +"is assigned, otherwise it will have no effect." +msgstr "" + +#: ../../library/ctypes.rst:2871 +msgid "" +"An optional sequence that lists the names of unnamed (anonymous) fields. :" +"attr:`_anonymous_` must be already defined when :attr:`_fields_` is " +"assigned, otherwise it will have no effect." +msgstr "" + +#: ../../library/ctypes.rst:2875 +msgid "" +"The fields listed in this variable must be structure or union type fields. :" +"mod:`ctypes` will create descriptors in the structure type that allows " +"accessing the nested fields directly, without the need to create the " +"structure or union field." +msgstr "" + +#: ../../library/ctypes.rst:2880 +msgid "Here is an example type (Windows)::" +msgstr "" + +#: ../../library/ctypes.rst:2882 +msgid "" +"class _U(Union):\n" +" _fields_ = [(\"lptdesc\", POINTER(TYPEDESC)),\n" +" (\"lpadesc\", POINTER(ARRAYDESC)),\n" +" (\"hreftype\", HREFTYPE)]\n" +"\n" +"class TYPEDESC(Structure):\n" +" _anonymous_ = (\"u\",)\n" +" _fields_ = [(\"u\", _U),\n" +" (\"vt\", VARTYPE)]" +msgstr "" +"class _U(Union):\n" +" _fields_ = [(\"lptdesc\", POINTER(TYPEDESC)),\n" +" (\"lpadesc\", POINTER(ARRAYDESC)),\n" +" (\"hreftype\", HREFTYPE)]\n" +"\n" +"class TYPEDESC(Structure):\n" +" _anonymous_ = (\"u\",)\n" +" _fields_ = [(\"u\", _U),\n" +" (\"vt\", VARTYPE)]" + +#: ../../library/ctypes.rst:2893 +msgid "" +"The ``TYPEDESC`` structure describes a COM data type, the ``vt`` field " +"specifies which one of the union fields is valid. Since the ``u`` field is " +"defined as anonymous field, it is now possible to access the members " +"directly off the TYPEDESC instance. ``td.lptdesc`` and ``td.u.lptdesc`` are " +"equivalent, but the former is faster since it does not need to create a " +"temporary union instance::" +msgstr "" + +#: ../../library/ctypes.rst:2900 +msgid "" +"td = TYPEDESC()\n" +"td.vt = VT_PTR\n" +"td.lptdesc = POINTER(some_type)\n" +"td.u.lptdesc = POINTER(some_type)" +msgstr "" +"td = TYPEDESC()\n" +"td.vt = VT_PTR\n" +"td.lptdesc = POINTER(some_type)\n" +"td.u.lptdesc = POINTER(some_type)" + +#: ../../library/ctypes.rst:2905 +msgid "" +"It is possible to define sub-subclasses of structures, they inherit the " +"fields of the base class. If the subclass definition has a separate :attr:" +"`_fields_` variable, the fields specified in this are appended to the fields " +"of the base class." +msgstr "" + +#: ../../library/ctypes.rst:2910 +msgid "" +"Structure and union constructors accept both positional and keyword " +"arguments. Positional arguments are used to initialize member fields in the " +"same order as they are appear in :attr:`_fields_`. Keyword arguments in the " +"constructor are interpreted as attribute assignments, so they will " +"initialize :attr:`_fields_` with the same name, or create new attributes for " +"names not present in :attr:`_fields_`." +msgstr "" + +#: ../../library/ctypes.rst:2920 +msgid "" +"Descriptor for fields of a :class:`Structure` and :class:`Union`. For " +"example::" +msgstr "" + +#: ../../library/ctypes.rst:2923 +msgid "" +">>> class Color(Structure):\n" +"... _fields_ = (\n" +"... ('red', c_uint8),\n" +"... ('green', c_uint8),\n" +"... ('blue', c_uint8),\n" +"... ('intense', c_bool, 1),\n" +"... ('blinking', c_bool, 1),\n" +"... )\n" +"...\n" +">>> Color.red\n" +"\n" +">>> Color.green.type\n" +"\n" +">>> Color.blue.byte_offset\n" +"2\n" +">>> Color.intense\n" +"\n" +">>> Color.blinking.bit_offset\n" +"1" +msgstr "" +">>> class Color(Structure):\n" +"... _fields_ = (\n" +"... ('red', c_uint8),\n" +"... ('green', c_uint8),\n" +"... ('blue', c_uint8),\n" +"... ('intense', c_bool, 1),\n" +"... ('blinking', c_bool, 1),\n" +"... )\n" +"...\n" +">>> Color.red\n" +"\n" +">>> Color.green.type\n" +"\n" +">>> Color.blue.byte_offset\n" +"2\n" +">>> Color.intense\n" +"\n" +">>> Color.blinking.bit_offset\n" +"1" + +#: ../../library/ctypes.rst:2943 +msgid "All attributes are read-only." +msgstr "" + +#: ../../library/ctypes.rst:2945 +msgid "" +":class:`!CField` objects are created via :attr:`~Structure._fields_`; do not " +"instantiate the class directly." +msgstr "" + +#: ../../library/ctypes.rst:2950 +msgid "" +"Previously, descriptors only had ``offset`` and ``size`` attributes and a " +"readable string representation; the :class:`!CField` class was not available " +"directly." +msgstr "" + +#: ../../library/ctypes.rst:2956 +msgid "Name of the field, as a string." +msgstr "" + +#: ../../library/ctypes.rst:2960 +msgid "Type of the field, as a :ref:`ctypes class `." +msgstr "" + +#: ../../library/ctypes.rst:2965 +msgid "Offset of the field, in bytes." +msgstr "" + +#: ../../library/ctypes.rst:2967 +msgid "" +"For bitfields, this is the offset of the underlying byte-aligned *storage " +"unit*; see :attr:`~CField.bit_offset`." +msgstr "" + +#: ../../library/ctypes.rst:2972 +msgid "Size of the field, in bytes." +msgstr "" + +#: ../../library/ctypes.rst:2974 +msgid "" +"For bitfields, this is the size of the underlying *storage unit*. Typically, " +"it has the same size as the bitfield's type." +msgstr "" + +#: ../../library/ctypes.rst:2979 +msgid "For non-bitfields, equivalent to :attr:`~CField.byte_size`." +msgstr "" + +#: ../../library/ctypes.rst:2981 +msgid "" +"For bitfields, this contains a backwards-compatible bit-packed value that " +"combines :attr:`~CField.bit_size` and :attr:`~CField.bit_offset`. Prefer " +"using the explicit attributes instead." +msgstr "" + +#: ../../library/ctypes.rst:2988 +msgid "True if this is a bitfield." +msgstr "" + +#: ../../library/ctypes.rst:2993 +msgid "" +"The location of a bitfield within its *storage unit*, that is, within :attr:" +"`~CField.byte_size` bytes of memory starting at :attr:`~CField.byte_offset`." +msgstr "" + +#: ../../library/ctypes.rst:2997 +msgid "" +"To get the field's value, read the storage unit as an integer, :ref:`shift " +"left ` by :attr:`!bit_offset` and take the :attr:`!bit_size` least " +"significant bits." +msgstr "" + +#: ../../library/ctypes.rst:3001 +msgid "" +"For non-bitfields, :attr:`!bit_offset` is zero and :attr:`!bit_size` is " +"equal to ``byte_size * 8``." +msgstr "" + +#: ../../library/ctypes.rst:3006 +msgid "" +"True if this field is anonymous, that is, it contains nested sub-fields that " +"should be merged into a containing structure or union." +msgstr "" + +#: ../../library/ctypes.rst:3013 +msgid "Arrays and pointers" +msgstr "" + +#: ../../library/ctypes.rst:3017 +msgid "Abstract base class for arrays." +msgstr "" + +#: ../../library/ctypes.rst:3019 +msgid "" +"The recommended way to create concrete array types is by multiplying any :" +"mod:`ctypes` data type with a non-negative integer. Alternatively, you can " +"subclass this type and define :attr:`_length_` and :attr:`_type_` class " +"variables. Array elements can be read and written using standard subscript " +"and slice accesses; for slice reads, the resulting object is *not* itself " +"an :class:`Array`." +msgstr "" + +#: ../../library/ctypes.rst:3029 +msgid "" +"A positive integer specifying the number of elements in the array. Out-of-" +"range subscripts result in an :exc:`IndexError`. Will be returned by :func:" +"`len`." +msgstr "" + +#: ../../library/ctypes.rst:3036 +msgid "Specifies the type of each element in the array." +msgstr "" + +#: ../../library/ctypes.rst:3039 +msgid "" +"Array subclass constructors accept positional arguments, used to initialize " +"the elements in order." +msgstr "" + +#: ../../library/ctypes.rst:3044 +msgid "" +"Create an array. Equivalent to ``type * length``, where *type* is a :mod:" +"`ctypes` data type and *length* an integer." +msgstr "" + +#: ../../library/ctypes.rst:3048 +msgid "" +"This function is :term:`soft deprecated` in favor of multiplication. There " +"are no plans to remove it." +msgstr "" + +#: ../../library/ctypes.rst:3054 +msgid "Private, abstract base class for pointers." +msgstr "" + +#: ../../library/ctypes.rst:3056 +msgid "" +"Concrete pointer types are created by calling :func:`POINTER` with the type " +"that will be pointed to; this is done automatically by :func:`pointer`." +msgstr "" + +#: ../../library/ctypes.rst:3060 +msgid "" +"If a pointer points to an array, its elements can be read and written using " +"standard subscript and slice accesses. Pointer objects have no size, so :" +"func:`len` will raise :exc:`TypeError`. Negative subscripts will read from " +"the memory *before* the pointer (as in C), and out-of-range subscripts will " +"probably crash with an access violation (if you're lucky)." +msgstr "" + +#: ../../library/ctypes.rst:3070 +msgid "Specifies the type pointed to." +msgstr "" + +#: ../../library/ctypes.rst:3074 +msgid "" +"Returns the object to which to pointer points. Assigning to this attribute " +"changes the pointer to point to the assigned object." +msgstr "" + +#: ../../library/ctypes.rst:3081 +msgid "Exceptions" +msgstr "" + +#: ../../library/ctypes.rst:3085 +msgid "" +"This exception is raised when a foreign function call cannot convert one of " +"the passed arguments." +msgstr "" + +#: ../../library/ctypes.rst:3091 +msgid "This exception is raised when a COM method call failed." +msgstr "" + +#: ../../library/ctypes.rst:3095 +msgid "The integer value representing the error code." +msgstr "" + +#: ../../library/ctypes.rst:3099 +msgid "The error message." +msgstr "" + +#: ../../library/ctypes.rst:3103 +msgid "The 5-tuple ``(descr, source, helpfile, helpcontext, progid)``." +msgstr "" + +#: ../../library/ctypes.rst:3105 +msgid "" +"*descr* is the textual description. *source* is the language-dependent " +"``ProgID`` for the class or application that raised the error. *helpfile* " +"is the path of the help file. *helpcontext* is the help context " +"identifier. *progid* is the ``ProgID`` of the interface that defined the " +"error." +msgstr "" diff --git a/library/curses.ascii.po b/library/curses.ascii.po index bc02ebebee..4f5c6d7db7 100644 --- a/library/curses.ascii.po +++ b/library/curses.ascii.po @@ -1,339 +1,339 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-05-09 00:03+0000\n" -"PO-Revision-Date: 2018-05-23 14:42+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/curses.ascii.rst:2 -msgid ":mod:`!curses.ascii` --- Utilities for ASCII characters" -msgstr ":mod:`!curses.ascii` --- ASCII 字元的工具程式" - -#: ../../library/curses.ascii.rst:10 -msgid "**Source code:** :source:`Lib/curses/ascii.py`" -msgstr "**原始碼：**\\ :source:`Lib/curses/ascii.py`" - -#: ../../library/curses.ascii.rst:14 -msgid "" -"The :mod:`curses.ascii` module supplies name constants for ASCII characters " -"and functions to test membership in various ASCII character classes. The " -"constants supplied are names for control characters as follows:" -msgstr "" - -#: ../../library/curses.ascii.rst:19 -msgid "Name" -msgstr "名稱" - -#: ../../library/curses.ascii.rst:19 -msgid "Meaning" -msgstr "含義" - -#: ../../library/curses.ascii.rst:23 -msgid "Start of heading, console interrupt" -msgstr "" - -#: ../../library/curses.ascii.rst:25 -msgid "Start of text" -msgstr "" - -#: ../../library/curses.ascii.rst:27 -msgid "End of text" -msgstr "" - -#: ../../library/curses.ascii.rst:29 -msgid "End of transmission" -msgstr "" - -#: ../../library/curses.ascii.rst:31 -msgid "Enquiry, goes with :const:`ACK` flow control" -msgstr "" - -#: ../../library/curses.ascii.rst:33 -msgid "Acknowledgement" -msgstr "" - -#: ../../library/curses.ascii.rst:35 -msgid "Bell" -msgstr "" - -#: ../../library/curses.ascii.rst:37 -msgid "Backspace" -msgstr "" - -#: ../../library/curses.ascii.rst:39 -msgid "Tab" -msgstr "" - -#: ../../library/curses.ascii.rst:41 -msgid "Alias for :const:`TAB`: \"Horizontal tab\"" -msgstr "" - -#: ../../library/curses.ascii.rst:43 -msgid "Line feed" -msgstr "" - -#: ../../library/curses.ascii.rst:45 -msgid "Alias for :const:`LF`: \"New line\"" -msgstr "" - -#: ../../library/curses.ascii.rst:47 -msgid "Vertical tab" -msgstr "" - -#: ../../library/curses.ascii.rst:49 -msgid "Form feed" -msgstr "" - -#: ../../library/curses.ascii.rst:51 -msgid "Carriage return" -msgstr "" - -#: ../../library/curses.ascii.rst:53 -msgid "Shift-out, begin alternate character set" -msgstr "" - -#: ../../library/curses.ascii.rst:55 -msgid "Shift-in, resume default character set" -msgstr "" - -#: ../../library/curses.ascii.rst:57 -msgid "Data-link escape" -msgstr "" - -#: ../../library/curses.ascii.rst:59 -msgid "XON, for flow control" -msgstr "" - -#: ../../library/curses.ascii.rst:61 -msgid "Device control 2, block-mode flow control" -msgstr "" - -#: ../../library/curses.ascii.rst:63 -msgid "XOFF, for flow control" -msgstr "" - -#: ../../library/curses.ascii.rst:65 -msgid "Device control 4" -msgstr "" - -#: ../../library/curses.ascii.rst:67 -msgid "Negative acknowledgement" -msgstr "" - -#: ../../library/curses.ascii.rst:69 -msgid "Synchronous idle" -msgstr "" - -#: ../../library/curses.ascii.rst:71 -msgid "End transmission block" -msgstr "" - -#: ../../library/curses.ascii.rst:73 -msgid "Cancel" -msgstr "" - -#: ../../library/curses.ascii.rst:75 -msgid "End of medium" -msgstr "" - -#: ../../library/curses.ascii.rst:77 -msgid "Substitute" -msgstr "" - -#: ../../library/curses.ascii.rst:79 -msgid "Escape" -msgstr "" - -#: ../../library/curses.ascii.rst:81 -msgid "File separator" -msgstr "" - -#: ../../library/curses.ascii.rst:83 -msgid "Group separator" -msgstr "" - -#: ../../library/curses.ascii.rst:85 -msgid "Record separator, block-mode terminator" -msgstr "" - -#: ../../library/curses.ascii.rst:87 -msgid "Unit separator" -msgstr "" - -#: ../../library/curses.ascii.rst:89 -msgid "Space" -msgstr "" - -#: ../../library/curses.ascii.rst:91 -msgid "Delete" -msgstr "" - -#: ../../library/curses.ascii.rst:94 -msgid "" -"Note that many of these have little practical significance in modern usage. " -"The mnemonics derive from teleprinter conventions that predate digital " -"computers." -msgstr "" - -#: ../../library/curses.ascii.rst:97 -msgid "" -"The module supplies the following functions, patterned on those in the " -"standard C library:" -msgstr "" - -#: ../../library/curses.ascii.rst:103 -msgid "" -"Checks for an ASCII alphanumeric character; it is equivalent to ``isalpha(c) " -"or isdigit(c)``." -msgstr "" - -#: ../../library/curses.ascii.rst:109 -msgid "" -"Checks for an ASCII alphabetic character; it is equivalent to ``isupper(c) " -"or islower(c)``." -msgstr "" - -#: ../../library/curses.ascii.rst:115 -msgid "Checks for a character value that fits in the 7-bit ASCII set." -msgstr "" - -#: ../../library/curses.ascii.rst:120 -msgid "Checks for an ASCII whitespace character; space or horizontal tab." -msgstr "" - -#: ../../library/curses.ascii.rst:125 -msgid "" -"Checks for an ASCII control character (in the range 0x00 to 0x1f or 0x7f)." -msgstr "" - -#: ../../library/curses.ascii.rst:130 -msgid "" -"Checks for an ASCII decimal digit, ``'0'`` through ``'9'``. This is " -"equivalent to ``c in string.digits``." -msgstr "" - -#: ../../library/curses.ascii.rst:136 -msgid "Checks for ASCII any printable character except space." -msgstr "" - -#: ../../library/curses.ascii.rst:141 -msgid "Checks for an ASCII lower-case character." -msgstr "" - -#: ../../library/curses.ascii.rst:146 -msgid "Checks for any ASCII printable character including space." -msgstr "" - -#: ../../library/curses.ascii.rst:151 -msgid "" -"Checks for any printable ASCII character which is not a space or an " -"alphanumeric character." -msgstr "" - -#: ../../library/curses.ascii.rst:157 -msgid "" -"Checks for ASCII white-space characters; space, line feed, carriage return, " -"form feed, horizontal tab, vertical tab." -msgstr "" - -#: ../../library/curses.ascii.rst:163 -msgid "Checks for an ASCII uppercase letter." -msgstr "" - -#: ../../library/curses.ascii.rst:168 -msgid "" -"Checks for an ASCII hexadecimal digit. This is equivalent to ``c in string." -"hexdigits``." -msgstr "" - -#: ../../library/curses.ascii.rst:174 -msgid "Checks for an ASCII control character (ordinal values 0 to 31)." -msgstr "" - -#: ../../library/curses.ascii.rst:179 -msgid "Checks for a non-ASCII character (ordinal values 0x80 and above)." -msgstr "" - -#: ../../library/curses.ascii.rst:181 -msgid "" -"These functions accept either integers or single-character strings; when the " -"argument is a string, it is first converted using the built-in function :" -"func:`ord`." -msgstr "" - -#: ../../library/curses.ascii.rst:184 -msgid "" -"Note that all these functions check ordinal bit values derived from the " -"character of the string you pass in; they do not actually know anything " -"about the host machine's character encoding." -msgstr "" - -#: ../../library/curses.ascii.rst:188 -msgid "" -"The following two functions take either a single-character string or integer " -"byte value; they return a value of the same type." -msgstr "" - -#: ../../library/curses.ascii.rst:194 -msgid "Return the ASCII value corresponding to the low 7 bits of *c*." -msgstr "" - -#: ../../library/curses.ascii.rst:199 -msgid "" -"Return the control character corresponding to the given character (the " -"character bit value is bitwise-anded with 0x1f)." -msgstr "" - -#: ../../library/curses.ascii.rst:205 -msgid "" -"Return the 8-bit character corresponding to the given ASCII character (the " -"character bit value is bitwise-ored with 0x80)." -msgstr "" - -#: ../../library/curses.ascii.rst:208 -msgid "" -"The following function takes either a single-character string or integer " -"value; it returns a string." -msgstr "" - -#: ../../library/curses.ascii.rst:218 -msgid "" -"Return a string representation of the ASCII character *c*. If *c* is " -"printable, this string is the character itself. If the character is a " -"control character (0x00--0x1f) the string consists of a caret (``'^'``) " -"followed by the corresponding uppercase letter. If the character is an ASCII " -"delete (0x7f) the string is ``'^?'``. If the character has its meta bit " -"(0x80) set, the meta bit is stripped, the preceding rules applied, and " -"``'!'`` prepended to the result." -msgstr "" - -#: ../../library/curses.ascii.rst:228 -msgid "" -"A 33-element string array that contains the ASCII mnemonics for the thirty-" -"two ASCII control characters from 0 (NUL) to 0x1f (US), in order, plus the " -"mnemonic ``SP`` for the space character." -msgstr "" - -#: ../../library/curses.ascii.rst:212 -msgid "^ (caret)" -msgstr "^ （插入符號）" - -#: ../../library/curses.ascii.rst:212 -msgid "in curses module" -msgstr "於 curses 模組中" - -#: ../../library/curses.ascii.rst:212 -msgid "! (exclamation)" -msgstr "! （驚嘆號）" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-05-09 00:03+0000\n" +"PO-Revision-Date: 2018-05-23 14:42+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/curses.ascii.rst:2 +msgid ":mod:`!curses.ascii` --- Utilities for ASCII characters" +msgstr ":mod:`!curses.ascii` --- ASCII 字元的工具程式" + +#: ../../library/curses.ascii.rst:10 +msgid "**Source code:** :source:`Lib/curses/ascii.py`" +msgstr "**原始碼：**\\ :source:`Lib/curses/ascii.py`" + +#: ../../library/curses.ascii.rst:14 +msgid "" +"The :mod:`curses.ascii` module supplies name constants for ASCII characters " +"and functions to test membership in various ASCII character classes. The " +"constants supplied are names for control characters as follows:" +msgstr "" + +#: ../../library/curses.ascii.rst:19 +msgid "Name" +msgstr "名稱" + +#: ../../library/curses.ascii.rst:19 +msgid "Meaning" +msgstr "含義" + +#: ../../library/curses.ascii.rst:23 +msgid "Start of heading, console interrupt" +msgstr "" + +#: ../../library/curses.ascii.rst:25 +msgid "Start of text" +msgstr "" + +#: ../../library/curses.ascii.rst:27 +msgid "End of text" +msgstr "" + +#: ../../library/curses.ascii.rst:29 +msgid "End of transmission" +msgstr "" + +#: ../../library/curses.ascii.rst:31 +msgid "Enquiry, goes with :const:`ACK` flow control" +msgstr "" + +#: ../../library/curses.ascii.rst:33 +msgid "Acknowledgement" +msgstr "" + +#: ../../library/curses.ascii.rst:35 +msgid "Bell" +msgstr "" + +#: ../../library/curses.ascii.rst:37 +msgid "Backspace" +msgstr "" + +#: ../../library/curses.ascii.rst:39 +msgid "Tab" +msgstr "" + +#: ../../library/curses.ascii.rst:41 +msgid "Alias for :const:`TAB`: \"Horizontal tab\"" +msgstr "" + +#: ../../library/curses.ascii.rst:43 +msgid "Line feed" +msgstr "" + +#: ../../library/curses.ascii.rst:45 +msgid "Alias for :const:`LF`: \"New line\"" +msgstr "" + +#: ../../library/curses.ascii.rst:47 +msgid "Vertical tab" +msgstr "" + +#: ../../library/curses.ascii.rst:49 +msgid "Form feed" +msgstr "" + +#: ../../library/curses.ascii.rst:51 +msgid "Carriage return" +msgstr "" + +#: ../../library/curses.ascii.rst:53 +msgid "Shift-out, begin alternate character set" +msgstr "" + +#: ../../library/curses.ascii.rst:55 +msgid "Shift-in, resume default character set" +msgstr "" + +#: ../../library/curses.ascii.rst:57 +msgid "Data-link escape" +msgstr "" + +#: ../../library/curses.ascii.rst:59 +msgid "XON, for flow control" +msgstr "" + +#: ../../library/curses.ascii.rst:61 +msgid "Device control 2, block-mode flow control" +msgstr "" + +#: ../../library/curses.ascii.rst:63 +msgid "XOFF, for flow control" +msgstr "" + +#: ../../library/curses.ascii.rst:65 +msgid "Device control 4" +msgstr "" + +#: ../../library/curses.ascii.rst:67 +msgid "Negative acknowledgement" +msgstr "" + +#: ../../library/curses.ascii.rst:69 +msgid "Synchronous idle" +msgstr "" + +#: ../../library/curses.ascii.rst:71 +msgid "End transmission block" +msgstr "" + +#: ../../library/curses.ascii.rst:73 +msgid "Cancel" +msgstr "" + +#: ../../library/curses.ascii.rst:75 +msgid "End of medium" +msgstr "" + +#: ../../library/curses.ascii.rst:77 +msgid "Substitute" +msgstr "" + +#: ../../library/curses.ascii.rst:79 +msgid "Escape" +msgstr "" + +#: ../../library/curses.ascii.rst:81 +msgid "File separator" +msgstr "" + +#: ../../library/curses.ascii.rst:83 +msgid "Group separator" +msgstr "" + +#: ../../library/curses.ascii.rst:85 +msgid "Record separator, block-mode terminator" +msgstr "" + +#: ../../library/curses.ascii.rst:87 +msgid "Unit separator" +msgstr "" + +#: ../../library/curses.ascii.rst:89 +msgid "Space" +msgstr "" + +#: ../../library/curses.ascii.rst:91 +msgid "Delete" +msgstr "" + +#: ../../library/curses.ascii.rst:94 +msgid "" +"Note that many of these have little practical significance in modern usage. " +"The mnemonics derive from teleprinter conventions that predate digital " +"computers." +msgstr "" + +#: ../../library/curses.ascii.rst:97 +msgid "" +"The module supplies the following functions, patterned on those in the " +"standard C library:" +msgstr "" + +#: ../../library/curses.ascii.rst:103 +msgid "" +"Checks for an ASCII alphanumeric character; it is equivalent to ``isalpha(c) " +"or isdigit(c)``." +msgstr "" + +#: ../../library/curses.ascii.rst:109 +msgid "" +"Checks for an ASCII alphabetic character; it is equivalent to ``isupper(c) " +"or islower(c)``." +msgstr "" + +#: ../../library/curses.ascii.rst:115 +msgid "Checks for a character value that fits in the 7-bit ASCII set." +msgstr "" + +#: ../../library/curses.ascii.rst:120 +msgid "Checks for an ASCII whitespace character; space or horizontal tab." +msgstr "" + +#: ../../library/curses.ascii.rst:125 +msgid "" +"Checks for an ASCII control character (in the range 0x00 to 0x1f or 0x7f)." +msgstr "" + +#: ../../library/curses.ascii.rst:130 +msgid "" +"Checks for an ASCII decimal digit, ``'0'`` through ``'9'``. This is " +"equivalent to ``c in string.digits``." +msgstr "" + +#: ../../library/curses.ascii.rst:136 +msgid "Checks for ASCII any printable character except space." +msgstr "" + +#: ../../library/curses.ascii.rst:141 +msgid "Checks for an ASCII lower-case character." +msgstr "" + +#: ../../library/curses.ascii.rst:146 +msgid "Checks for any ASCII printable character including space." +msgstr "" + +#: ../../library/curses.ascii.rst:151 +msgid "" +"Checks for any printable ASCII character which is not a space or an " +"alphanumeric character." +msgstr "" + +#: ../../library/curses.ascii.rst:157 +msgid "" +"Checks for ASCII white-space characters; space, line feed, carriage return, " +"form feed, horizontal tab, vertical tab." +msgstr "" + +#: ../../library/curses.ascii.rst:163 +msgid "Checks for an ASCII uppercase letter." +msgstr "" + +#: ../../library/curses.ascii.rst:168 +msgid "" +"Checks for an ASCII hexadecimal digit. This is equivalent to ``c in string." +"hexdigits``." +msgstr "" + +#: ../../library/curses.ascii.rst:174 +msgid "Checks for an ASCII control character (ordinal values 0 to 31)." +msgstr "" + +#: ../../library/curses.ascii.rst:179 +msgid "Checks for a non-ASCII character (ordinal values 0x80 and above)." +msgstr "" + +#: ../../library/curses.ascii.rst:181 +msgid "" +"These functions accept either integers or single-character strings; when the " +"argument is a string, it is first converted using the built-in function :" +"func:`ord`." +msgstr "" + +#: ../../library/curses.ascii.rst:184 +msgid "" +"Note that all these functions check ordinal bit values derived from the " +"character of the string you pass in; they do not actually know anything " +"about the host machine's character encoding." +msgstr "" + +#: ../../library/curses.ascii.rst:188 +msgid "" +"The following two functions take either a single-character string or integer " +"byte value; they return a value of the same type." +msgstr "" + +#: ../../library/curses.ascii.rst:194 +msgid "Return the ASCII value corresponding to the low 7 bits of *c*." +msgstr "" + +#: ../../library/curses.ascii.rst:199 +msgid "" +"Return the control character corresponding to the given character (the " +"character bit value is bitwise-anded with 0x1f)." +msgstr "" + +#: ../../library/curses.ascii.rst:205 +msgid "" +"Return the 8-bit character corresponding to the given ASCII character (the " +"character bit value is bitwise-ored with 0x80)." +msgstr "" + +#: ../../library/curses.ascii.rst:208 +msgid "" +"The following function takes either a single-character string or integer " +"value; it returns a string." +msgstr "" + +#: ../../library/curses.ascii.rst:218 +msgid "" +"Return a string representation of the ASCII character *c*. If *c* is " +"printable, this string is the character itself. If the character is a " +"control character (0x00--0x1f) the string consists of a caret (``'^'``) " +"followed by the corresponding uppercase letter. If the character is an ASCII " +"delete (0x7f) the string is ``'^?'``. If the character has its meta bit " +"(0x80) set, the meta bit is stripped, the preceding rules applied, and " +"``'!'`` prepended to the result." +msgstr "" + +#: ../../library/curses.ascii.rst:228 +msgid "" +"A 33-element string array that contains the ASCII mnemonics for the thirty-" +"two ASCII control characters from 0 (NUL) to 0x1f (US), in order, plus the " +"mnemonic ``SP`` for the space character." +msgstr "" + +#: ../../library/curses.ascii.rst:212 +msgid "^ (caret)" +msgstr "^ （插入符號）" + +#: ../../library/curses.ascii.rst:212 +msgid "in curses module" +msgstr "於 curses 模組中" + +#: ../../library/curses.ascii.rst:212 +msgid "! (exclamation)" +msgstr "! （驚嘆號）" diff --git a/library/curses.panel.po b/library/curses.panel.po index 6be0d1be8a..02f210e83b 100644 --- a/library/curses.panel.po +++ b/library/curses.panel.po @@ -1,129 +1,129 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-05-09 00:03+0000\n" -"PO-Revision-Date: 2018-05-23 14:42+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/curses.panel.rst:2 -msgid ":mod:`!curses.panel` --- A panel stack extension for curses" -msgstr ":mod:`!curses.panel` --- curses 的面板堆疊擴充" - -#: ../../library/curses.panel.rst:11 -msgid "" -"Panels are windows with the added feature of depth, so they can be stacked " -"on top of each other, and only the visible portions of each window will be " -"displayed. Panels can be added, moved up or down in the stack, and removed." -msgstr "" - -#: ../../library/curses.panel.rst:19 -msgid "Functions" -msgstr "函式" - -#: ../../library/curses.panel.rst:21 -msgid "The module :mod:`curses.panel` defines the following functions:" -msgstr ":mod:`curses.panel` 模組定義了以下函式：" - -#: ../../library/curses.panel.rst:26 -msgid "Returns the bottom panel in the panel stack." -msgstr "" - -#: ../../library/curses.panel.rst:31 -msgid "" -"Returns a panel object, associating it with the given window *win*. Be aware " -"that you need to keep the returned panel object referenced explicitly. If " -"you don't, the panel object is garbage collected and removed from the panel " -"stack." -msgstr "" - -#: ../../library/curses.panel.rst:38 -msgid "Returns the top panel in the panel stack." -msgstr "" - -#: ../../library/curses.panel.rst:43 -msgid "" -"Updates the virtual screen after changes in the panel stack. This does not " -"call :func:`curses.doupdate`, so you'll have to do this yourself." -msgstr "" - -#: ../../library/curses.panel.rst:50 -msgid "Panel Objects" -msgstr "" - -#: ../../library/curses.panel.rst:52 -msgid "" -"Panel objects, as returned by :func:`new_panel` above, are windows with a " -"stacking order. There's always a window associated with a panel which " -"determines the content, while the panel methods are responsible for the " -"window's depth in the panel stack." -msgstr "" - -#: ../../library/curses.panel.rst:57 -msgid "Panel objects have the following methods:" -msgstr "" - -#: ../../library/curses.panel.rst:62 -msgid "Returns the panel above the current panel." -msgstr "" - -#: ../../library/curses.panel.rst:67 -msgid "Returns the panel below the current panel." -msgstr "" - -#: ../../library/curses.panel.rst:72 -msgid "Push the panel to the bottom of the stack." -msgstr "" - -#: ../../library/curses.panel.rst:77 -msgid "" -"Returns ``True`` if the panel is hidden (not visible), ``False`` otherwise." -msgstr "" - -#: ../../library/curses.panel.rst:82 -msgid "" -"Hide the panel. This does not delete the object, it just makes the window on " -"screen invisible." -msgstr "" - -#: ../../library/curses.panel.rst:88 -msgid "Move the panel to the screen coordinates ``(y, x)``." -msgstr "" - -#: ../../library/curses.panel.rst:93 -msgid "Change the window associated with the panel to the window *win*." -msgstr "" - -#: ../../library/curses.panel.rst:98 -msgid "" -"Set the panel's user pointer to *obj*. This is used to associate an " -"arbitrary piece of data with the panel, and can be any Python object." -msgstr "" - -#: ../../library/curses.panel.rst:104 -msgid "Display the panel (which might have been hidden)." -msgstr "" - -#: ../../library/curses.panel.rst:109 -msgid "Push panel to the top of the stack." -msgstr "" - -#: ../../library/curses.panel.rst:114 -msgid "" -"Returns the user pointer for the panel. This might be any Python object." -msgstr "" - -#: ../../library/curses.panel.rst:119 -msgid "Returns the window object associated with the panel." -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-05-09 00:03+0000\n" +"PO-Revision-Date: 2018-05-23 14:42+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/curses.panel.rst:2 +msgid ":mod:`!curses.panel` --- A panel stack extension for curses" +msgstr ":mod:`!curses.panel` --- curses 的面板堆疊擴充" + +#: ../../library/curses.panel.rst:11 +msgid "" +"Panels are windows with the added feature of depth, so they can be stacked " +"on top of each other, and only the visible portions of each window will be " +"displayed. Panels can be added, moved up or down in the stack, and removed." +msgstr "" + +#: ../../library/curses.panel.rst:19 +msgid "Functions" +msgstr "函式" + +#: ../../library/curses.panel.rst:21 +msgid "The module :mod:`curses.panel` defines the following functions:" +msgstr ":mod:`curses.panel` 模組定義了以下函式：" + +#: ../../library/curses.panel.rst:26 +msgid "Returns the bottom panel in the panel stack." +msgstr "" + +#: ../../library/curses.panel.rst:31 +msgid "" +"Returns a panel object, associating it with the given window *win*. Be aware " +"that you need to keep the returned panel object referenced explicitly. If " +"you don't, the panel object is garbage collected and removed from the panel " +"stack." +msgstr "" + +#: ../../library/curses.panel.rst:38 +msgid "Returns the top panel in the panel stack." +msgstr "" + +#: ../../library/curses.panel.rst:43 +msgid "" +"Updates the virtual screen after changes in the panel stack. This does not " +"call :func:`curses.doupdate`, so you'll have to do this yourself." +msgstr "" + +#: ../../library/curses.panel.rst:50 +msgid "Panel Objects" +msgstr "" + +#: ../../library/curses.panel.rst:52 +msgid "" +"Panel objects, as returned by :func:`new_panel` above, are windows with a " +"stacking order. There's always a window associated with a panel which " +"determines the content, while the panel methods are responsible for the " +"window's depth in the panel stack." +msgstr "" + +#: ../../library/curses.panel.rst:57 +msgid "Panel objects have the following methods:" +msgstr "" + +#: ../../library/curses.panel.rst:62 +msgid "Returns the panel above the current panel." +msgstr "" + +#: ../../library/curses.panel.rst:67 +msgid "Returns the panel below the current panel." +msgstr "" + +#: ../../library/curses.panel.rst:72 +msgid "Push the panel to the bottom of the stack." +msgstr "" + +#: ../../library/curses.panel.rst:77 +msgid "" +"Returns ``True`` if the panel is hidden (not visible), ``False`` otherwise." +msgstr "" + +#: ../../library/curses.panel.rst:82 +msgid "" +"Hide the panel. This does not delete the object, it just makes the window on " +"screen invisible." +msgstr "" + +#: ../../library/curses.panel.rst:88 +msgid "Move the panel to the screen coordinates ``(y, x)``." +msgstr "" + +#: ../../library/curses.panel.rst:93 +msgid "Change the window associated with the panel to the window *win*." +msgstr "" + +#: ../../library/curses.panel.rst:98 +msgid "" +"Set the panel's user pointer to *obj*. This is used to associate an " +"arbitrary piece of data with the panel, and can be any Python object." +msgstr "" + +#: ../../library/curses.panel.rst:104 +msgid "Display the panel (which might have been hidden)." +msgstr "" + +#: ../../library/curses.panel.rst:109 +msgid "Push panel to the top of the stack." +msgstr "" + +#: ../../library/curses.panel.rst:114 +msgid "" +"Returns the user pointer for the panel. This might be any Python object." +msgstr "" + +#: ../../library/curses.panel.rst:119 +msgid "Returns the window object associated with the panel." +msgstr "" diff --git a/library/curses.po b/library/curses.po index 5cf6e031f0..901f59a193 100644 --- a/library/curses.po +++ b/library/curses.po @@ -1,2616 +1,2616 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-10 16:45+0000\n" -"PO-Revision-Date: 2018-05-23 14:42+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/curses.rst:2 -msgid ":mod:`!curses` --- Terminal handling for character-cell displays" -msgstr ":mod:`!curses` --- 字元儲存格顯示的終端處理" - -#: ../../library/curses.rst:12 -msgid "**Source code:** :source:`Lib/curses`" -msgstr "**原始碼：**\\ :source:`Lib/curses`" - -#: ../../library/curses.rst:16 -msgid "" -"The :mod:`curses` module provides an interface to the curses library, the de-" -"facto standard for portable advanced terminal handling." -msgstr "" - -#: ../../library/curses.rst:19 -msgid "" -"While curses is most widely used in the Unix environment, versions are " -"available for Windows, DOS, and possibly other systems as well. This " -"extension module is designed to match the API of ncurses, an open-source " -"curses library hosted on Linux and the BSD variants of Unix." -msgstr "" - -#: ../../includes/wasm-mobile-notavail.rst:3 -msgid "Availability" -msgstr "可用性" - -#: ../../includes/wasm-mobile-notavail.rst:5 -msgid "" -"This module is not supported on :ref:`mobile platforms ` or :ref:`WebAssembly platforms `." -msgstr "" -"此模組在\\ :ref:`行動平台 `\\ 或 :ref:`WebAssembly 平" -"台 `\\ 上不支援。" - -#: ../../includes/optional-module.rst:1 -msgid "" -"This is an :term:`optional module`. If it is missing from your copy of " -"CPython, look for documentation from your distributor (that is, whoever " -"provided Python to you). If you are the distributor, see :ref:`optional-" -"module-requirements`." -msgstr "" - -#: ../../library/curses.rst:30 -msgid "" -"Whenever the documentation mentions a *character* it can be specified as an " -"integer, a one-character Unicode string or a one-byte byte string." -msgstr "" - -#: ../../library/curses.rst:33 -msgid "" -"Whenever the documentation mentions a *character string* it can be specified " -"as a Unicode string or a byte string." -msgstr "" - -#: ../../library/curses.rst:38 -msgid "Module :mod:`curses.ascii`" -msgstr ":mod:`curses.ascii` 模組" - -#: ../../library/curses.rst:39 -msgid "" -"Utilities for working with ASCII characters, regardless of your locale " -"settings." -msgstr "" - -#: ../../library/curses.rst:41 -msgid "Module :mod:`curses.panel`" -msgstr ":mod:`curses.panel` 模組" - -#: ../../library/curses.rst:42 -msgid "A panel stack extension that adds depth to curses windows." -msgstr "" - -#: ../../library/curses.rst:44 -msgid "Module :mod:`curses.textpad`" -msgstr ":mod:`curses.textpad` 模組" - -#: ../../library/curses.rst:45 -msgid "" -"Editable text widget for curses supporting :program:`Emacs`\\ -like " -"bindings." -msgstr "" - -#: ../../library/curses.rst:47 -msgid ":ref:`curses-howto`" -msgstr ":ref:`curses-howto`" - -#: ../../library/curses.rst:48 -msgid "" -"Tutorial material on using curses with Python, by Andrew Kuchling and Eric " -"Raymond." -msgstr "" - -#: ../../library/curses.rst:55 -msgid "Functions" -msgstr "函式" - -#: ../../library/curses.rst:57 -msgid "The module :mod:`curses` defines the following exception:" -msgstr ":mod:`curses` 模組定義了以下例外：" - -#: ../../library/curses.rst:62 -msgid "Exception raised when a curses library function returns an error." -msgstr "" - -#: ../../library/curses.rst:66 -msgid "" -"Whenever *x* or *y* arguments to a function or a method are optional, they " -"default to the current cursor location. Whenever *attr* is optional, it " -"defaults to :const:`A_NORMAL`." -msgstr "" - -#: ../../library/curses.rst:70 -msgid "The module :mod:`curses` defines the following functions:" -msgstr ":mod:`curses` 模組定義了以下函式：" - -#: ../../library/curses.rst:75 -msgid "" -"Allow use of default values for colors on terminals supporting this feature. " -"Use this to support transparency in your application." -msgstr "" - -#: ../../library/curses.rst:78 -msgid "" -"Assign terminal default foreground/background colors to color number ``-1``. " -"So ``init_pair(x, COLOR_RED, -1)`` will initialize pair *x* as red on " -"default background and ``init_pair(x, -1, COLOR_BLUE)`` will initialize pair " -"*x* as default foreground on blue." -msgstr "" - -#: ../../library/curses.rst:83 -msgid "Change the definition of the color-pair ``0`` to ``(fg, bg)``." -msgstr "" - -#: ../../library/curses.rst:90 -msgid "" -"Return the output speed of the terminal in bits per second. On software " -"terminal emulators it will have a fixed high value. Included for historical " -"reasons; in former times, it was used to write output loops for time delays " -"and occasionally to change interfaces depending on the line speed." -msgstr "" - -#: ../../library/curses.rst:98 -msgid "Emit a short attention sound." -msgstr "" - -#: ../../library/curses.rst:103 -msgid "" -"Return ``True`` or ``False``, depending on whether the programmer can change " -"the colors displayed by the terminal." -msgstr "" - -#: ../../library/curses.rst:109 -msgid "" -"Enter cbreak mode. In cbreak mode (sometimes called \"rare\" mode) normal " -"tty line buffering is turned off and characters are available to be read one " -"by one. However, unlike raw mode, special characters (interrupt, quit, " -"suspend, and flow control) retain their effects on the tty driver and " -"calling program. Calling first :func:`raw` then :func:`cbreak` leaves the " -"terminal in cbreak mode." -msgstr "" - -#: ../../library/curses.rst:118 -msgid "" -"Return the intensity of the red, green, and blue (RGB) components in the " -"color *color_number*, which must be between ``0`` and ``COLORS - 1``. " -"Return a 3-tuple, containing the R,G,B values for the given color, which " -"will be between ``0`` (no component) and ``1000`` (maximum amount of " -"component)." -msgstr "" - -#: ../../library/curses.rst:126 -msgid "" -"Return the attribute value for displaying text in the specified color pair. " -"Only the first 256 color pairs are supported. This attribute value can be " -"combined with :const:`A_STANDOUT`, :const:`A_REVERSE`, and the other :const:" -"`!A_\\*` attributes. :func:`pair_number` is the counterpart to this " -"function." -msgstr "" - -#: ../../library/curses.rst:135 -msgid "" -"Set the cursor state. *visibility* can be set to ``0``, ``1``, or ``2``, " -"for invisible, normal, or very visible. If the terminal supports the " -"visibility requested, return the previous cursor state; otherwise raise an " -"exception. On many terminals, the \"visible\" mode is an underline cursor " -"and the \"very visible\" mode is a block cursor." -msgstr "" - -#: ../../library/curses.rst:144 -msgid "" -"Save the current terminal mode as the \"program\" mode, the mode when the " -"running program is using curses. (Its counterpart is the \"shell\" mode, " -"for when the program is not in curses.) Subsequent calls to :func:" -"`reset_prog_mode` will restore this mode." -msgstr "" - -#: ../../library/curses.rst:152 -msgid "" -"Save the current terminal mode as the \"shell\" mode, the mode when the " -"running program is not using curses. (Its counterpart is the \"program\" " -"mode, when the program is using curses capabilities.) Subsequent calls to :" -"func:`reset_shell_mode` will restore this mode." -msgstr "" - -#: ../../library/curses.rst:160 -msgid "Insert an *ms* millisecond pause in output." -msgstr "" - -#: ../../library/curses.rst:165 -msgid "" -"Update the physical screen. The curses library keeps two data structures, " -"one representing the current physical screen contents and a virtual screen " -"representing the desired next state. The :func:`doupdate` ground updates " -"the physical screen to match the virtual screen." -msgstr "" - -#: ../../library/curses.rst:170 -msgid "" -"The virtual screen may be updated by a :meth:`~window.noutrefresh` call " -"after write operations such as :meth:`~window.addstr` have been performed on " -"a window. The normal :meth:`~window.refresh` call is simply :meth:`!" -"noutrefresh` followed by :func:`!doupdate`; if you have to update multiple " -"windows, you can speed performance and perhaps reduce screen flicker by " -"issuing :meth:`!noutrefresh` calls on all windows, followed by a single :" -"func:`!doupdate`." -msgstr "" - -#: ../../library/curses.rst:180 -msgid "" -"Enter echo mode. In echo mode, each character input is echoed to the screen " -"as it is entered." -msgstr "" - -#: ../../library/curses.rst:186 -msgid "De-initialize the library, and return terminal to normal status." -msgstr "" - -#: ../../library/curses.rst:191 -msgid "" -"Return the user's current erase character as a one-byte bytes object. Under " -"Unix operating systems this is a property of the controlling tty of the " -"curses program, and is not set by the curses library itself." -msgstr "" - -#: ../../library/curses.rst:198 -msgid "" -"The :func:`.filter` routine, if used, must be called before :func:`initscr` " -"is called. The effect is that, during those calls, :envvar:`LINES` is set " -"to ``1``; the capabilities ``clear``, ``cup``, ``cud``, ``cud1``, ``cuu1``, " -"``cuu``, ``vpa`` are disabled; and the ``home`` string is set to the value " -"of ``cr``. The effect is that the cursor is confined to the current line, " -"and so are screen updates. This may be used for enabling character-at-a-" -"time line editing without touching the rest of the screen." -msgstr "" - -#: ../../library/curses.rst:208 -msgid "" -"Flash the screen. That is, change it to reverse-video and then change it " -"back in a short interval. Some people prefer such as 'visible bell' to the " -"audible attention signal produced by :func:`beep`." -msgstr "" - -#: ../../library/curses.rst:215 -msgid "" -"Flush all input buffers. This throws away any typeahead that has been " -"typed by the user and has not yet been processed by the program." -msgstr "" - -#: ../../library/curses.rst:221 -msgid "" -"After :meth:`~window.getch` returns :const:`KEY_MOUSE` to signal a mouse " -"event, this method should be called to retrieve the queued mouse event, " -"represented as a 5-tuple ``(id, x, y, z, bstate)``. *id* is an ID value used " -"to distinguish multiple devices, and *x*, *y*, *z* are the event's " -"coordinates. (*z* is currently unused.) *bstate* is an integer value whose " -"bits will be set to indicate the type of event, and will be the bitwise OR " -"of one or more of the following constants, where *n* is the button number " -"from 1 to 5: :const:`BUTTONn_PRESSED`, :const:`BUTTONn_RELEASED`, :const:" -"`BUTTONn_CLICKED`, :const:`BUTTONn_DOUBLE_CLICKED`, :const:" -"`BUTTONn_TRIPLE_CLICKED`, :const:`BUTTON_SHIFT`, :const:`BUTTON_CTRL`, :" -"const:`BUTTON_ALT`." -msgstr "" - -#: ../../library/curses.rst:232 ../../library/curses.rst:1800 -msgid "" -"The ``BUTTON5_*`` constants are now exposed if they are provided by the " -"underlying curses library." -msgstr "" - -#: ../../library/curses.rst:239 -msgid "" -"Return the current coordinates of the virtual screen cursor as a tuple ``(y, " -"x)``. If :meth:`leaveok ` is currently ``True``, then " -"return ``(-1, -1)``." -msgstr "" - -#: ../../library/curses.rst:245 -msgid "" -"Read window related data stored in the file by an earlier :func:`window." -"putwin` call. The routine then creates and initializes a new window using " -"that data, returning the new window object." -msgstr "" - -#: ../../library/curses.rst:252 -msgid "" -"Return ``True`` if the terminal can display colors; otherwise, return " -"``False``." -msgstr "" - -#: ../../library/curses.rst:256 -msgid "" -"Return ``True`` if the module supports extended colors; otherwise, return " -"``False``. Extended color support allows more than 256 color pairs for " -"terminals that support more than 16 colors (e.g. xterm-256color)." -msgstr "" - -#: ../../library/curses.rst:260 -msgid "Extended color support requires ncurses version 6.1 or later." -msgstr "" - -#: ../../library/curses.rst:266 -msgid "" -"Return ``True`` if the terminal has insert- and delete-character " -"capabilities. This function is included for historical reasons only, as all " -"modern software terminal emulators have such capabilities." -msgstr "" - -#: ../../library/curses.rst:273 -msgid "" -"Return ``True`` if the terminal has insert- and delete-line capabilities, or " -"can simulate them using scrolling regions. This function is included for " -"historical reasons only, as all modern software terminal emulators have such " -"capabilities." -msgstr "" - -#: ../../library/curses.rst:281 -msgid "" -"Take a key value *ch*, and return ``True`` if the current terminal type " -"recognizes a key with that value." -msgstr "" - -#: ../../library/curses.rst:287 -msgid "" -"Used for half-delay mode, which is similar to cbreak mode in that characters " -"typed by the user are immediately available to the program. However, after " -"blocking for *tenths* tenths of seconds, raise an exception if nothing has " -"been typed. The value of *tenths* must be a number between ``1`` and " -"``255``. Use :func:`nocbreak` to leave half-delay mode." -msgstr "" - -#: ../../library/curses.rst:296 -msgid "" -"Change the definition of a color, taking the number of the color to be " -"changed followed by three RGB values (for the amounts of red, green, and " -"blue components). The value of *color_number* must be between ``0`` and " -"``COLORS - 1``. Each of *r*, *g*, *b*, must be a value between ``0`` and " -"``1000``. When :func:`init_color` is used, all occurrences of that color on " -"the screen immediately change to the new definition. This function is a no-" -"op on most terminals; it is active only if :func:`can_change_color` returns " -"``True``." -msgstr "" - -#: ../../library/curses.rst:307 -msgid "" -"Change the definition of a color-pair. It takes three arguments: the number " -"of the color-pair to be changed, the foreground color number, and the " -"background color number. The value of *pair_number* must be between ``1`` " -"and ``COLOR_PAIRS - 1`` (the ``0`` color pair can only be changed by :func:" -"`use_default_colors` and :func:`assume_default_colors`). The value of *fg* " -"and *bg* arguments must be between ``0`` and ``COLORS - 1``, or, after " -"calling :func:`!use_default_colors` or :func:`!assume_default_colors`, " -"``-1``. If the color-pair was previously initialized, the screen is " -"refreshed and all occurrences of that color-pair are changed to the new " -"definition." -msgstr "" - -#: ../../library/curses.rst:322 -msgid "" -"Initialize the library. Return a :ref:`window ` " -"object which represents the whole screen." -msgstr "" - -#: ../../library/curses.rst:327 -msgid "" -"If there is an error opening the terminal, the underlying curses library may " -"cause the interpreter to exit." -msgstr "" - -#: ../../library/curses.rst:333 -msgid "" -"Return ``True`` if :func:`resize_term` would modify the window structure, " -"``False`` otherwise." -msgstr "" - -#: ../../library/curses.rst:339 -msgid "" -"Return ``True`` if :func:`endwin` has been called (that is, the curses " -"library has been deinitialized)." -msgstr "" - -#: ../../library/curses.rst:345 -msgid "" -"Return the name of the key numbered *k* as a bytes object. The name of a " -"key generating printable ASCII character is the key's character. The name " -"of a control-key combination is a two-byte bytes object consisting of a " -"caret (``b'^'``) followed by the corresponding printable ASCII character. " -"The name of an alt-key combination (128--255) is a bytes object consisting " -"of the prefix ``b'M-'`` followed by the name of the corresponding ASCII " -"character." -msgstr "" - -#: ../../library/curses.rst:355 -msgid "" -"Return the user's current line kill character as a one-byte bytes object. " -"Under Unix operating systems this is a property of the controlling tty of " -"the curses program, and is not set by the curses library itself." -msgstr "" - -#: ../../library/curses.rst:362 -msgid "" -"Return a bytes object containing the terminfo long name field describing the " -"current terminal. The maximum length of a verbose description is 128 " -"characters. It is defined only after the call to :func:`initscr`." -msgstr "" - -#: ../../library/curses.rst:369 -msgid "" -"If *flag* is ``True``, allow 8-bit characters to be input. If *flag* is " -"``False``, allow only 7-bit chars." -msgstr "" - -#: ../../library/curses.rst:375 -msgid "" -"Set the maximum time in milliseconds that can elapse between press and " -"release events in order for them to be recognized as a click, and return the " -"previous interval value. The default value is 200 milliseconds, or one " -"fifth of a second." -msgstr "" - -#: ../../library/curses.rst:382 -msgid "" -"Set the mouse events to be reported, and return a tuple ``(availmask, " -"oldmask)``. *availmask* indicates which of the specified mouse events can " -"be reported; on complete failure it returns ``0``. *oldmask* is the " -"previous value of the given window's mouse event mask. If this function is " -"never called, no mouse events are ever reported." -msgstr "" - -#: ../../library/curses.rst:391 -msgid "Sleep for *ms* milliseconds." -msgstr "" - -#: ../../library/curses.rst:396 -msgid "" -"Create and return a pointer to a new pad data structure with the given " -"number of lines and columns. Return a pad as a window object." -msgstr "" - -#: ../../library/curses.rst:399 -msgid "" -"A pad is like a window, except that it is not restricted by the screen size, " -"and is not necessarily associated with a particular part of the screen. " -"Pads can be used when a large window is needed, and only a part of the " -"window will be on the screen at one time. Automatic refreshes of pads (such " -"as from scrolling or echoing of input) do not occur. The :meth:`~window." -"refresh` and :meth:`~window.noutrefresh` methods of a pad require 6 " -"arguments to specify the part of the pad to be displayed and the location on " -"the screen to be used for the display. The arguments are *pminrow*, " -"*pmincol*, *sminrow*, *smincol*, *smaxrow*, *smaxcol*; the *p* arguments " -"refer to the upper left corner of the pad region to be displayed and the *s* " -"arguments define a clipping box on the screen within which the pad region is " -"to be displayed." -msgstr "" - -#: ../../library/curses.rst:415 -msgid "" -"Return a new :ref:`window `, whose left-upper corner " -"is at ``(begin_y, begin_x)``, and whose height/width is *nlines*/*ncols*." -msgstr "" - -#: ../../library/curses.rst:418 -msgid "" -"By default, the window will extend from the specified position to the lower " -"right corner of the screen." -msgstr "" - -#: ../../library/curses.rst:424 -msgid "" -"Enter newline mode. This mode translates the return key into newline on " -"input, and translates newline into return and line-feed on output. Newline " -"mode is initially on." -msgstr "" - -#: ../../library/curses.rst:431 -msgid "" -"Leave cbreak mode. Return to normal \"cooked\" mode with line buffering." -msgstr "" - -#: ../../library/curses.rst:436 -msgid "Leave echo mode. Echoing of input characters is turned off." -msgstr "" - -#: ../../library/curses.rst:441 -msgid "" -"Leave newline mode. Disable translation of return into newline on input, " -"and disable low-level translation of newline into newline/return on output " -"(but this does not change the behavior of ``addch('\\n')``, which always " -"does the equivalent of return and line feed on the virtual screen). With " -"translation off, curses can sometimes speed up vertical motion a little; " -"also, it will be able to detect the return key on input." -msgstr "" - -#: ../../library/curses.rst:451 -msgid "" -"When the :func:`!noqiflush` routine is used, normal flush of input and " -"output queues associated with the ``INTR``, ``QUIT`` and ``SUSP`` characters " -"will not be done. You may want to call :func:`!noqiflush` in a signal " -"handler if you want output to continue as though the interrupt had not " -"occurred, after the handler exits." -msgstr "" - -#: ../../library/curses.rst:459 -msgid "Leave raw mode. Return to normal \"cooked\" mode with line buffering." -msgstr "" - -#: ../../library/curses.rst:464 -msgid "" -"Return a tuple ``(fg, bg)`` containing the colors for the requested color " -"pair. The value of *pair_number* must be between ``0`` and ``COLOR_PAIRS - " -"1``." -msgstr "" - -#: ../../library/curses.rst:470 -msgid "" -"Return the number of the color-pair set by the attribute value *attr*. :func:" -"`color_pair` is the counterpart to this function." -msgstr "" - -#: ../../library/curses.rst:476 -msgid "" -"Equivalent to ``tputs(str, 1, putchar)``; emit the value of a specified " -"terminfo capability for the current terminal. Note that the output of :func:" -"`putp` always goes to standard output." -msgstr "" - -#: ../../library/curses.rst:483 -msgid "" -"If *flag* is ``False``, the effect is the same as calling :func:`noqiflush`. " -"If *flag* is ``True``, or no argument is provided, the queues will be " -"flushed when these control characters are read." -msgstr "" - -#: ../../library/curses.rst:490 -msgid "" -"Enter raw mode. In raw mode, normal line buffering and processing of " -"interrupt, quit, suspend, and flow control keys are turned off; characters " -"are presented to curses input functions one by one." -msgstr "" - -#: ../../library/curses.rst:497 -msgid "" -"Restore the terminal to \"program\" mode, as previously saved by :func:" -"`def_prog_mode`." -msgstr "" - -#: ../../library/curses.rst:503 -msgid "" -"Restore the terminal to \"shell\" mode, as previously saved by :func:" -"`def_shell_mode`." -msgstr "" - -#: ../../library/curses.rst:509 -msgid "" -"Restore the state of the terminal modes to what it was at the last call to :" -"func:`savetty`." -msgstr "" - -#: ../../library/curses.rst:515 -msgid "" -"Backend function used by :func:`resizeterm`, performing most of the work; " -"when resizing the windows, :func:`resize_term` blank-fills the areas that " -"are extended. The calling application should fill in these areas with " -"appropriate data. The :func:`!resize_term` function attempts to resize all " -"windows. However, due to the calling convention of pads, it is not possible " -"to resize these without additional interaction with the application." -msgstr "" - -#: ../../library/curses.rst:525 -msgid "" -"Resize the standard and current windows to the specified dimensions, and " -"adjusts other bookkeeping data used by the curses library that record the " -"window dimensions (in particular the SIGWINCH handler)." -msgstr "" - -#: ../../library/curses.rst:532 -msgid "" -"Save the current state of the terminal modes in a buffer, usable by :func:" -"`resetty`." -msgstr "" - -#: ../../library/curses.rst:537 -msgid "Retrieves the value set by :func:`set_escdelay`." -msgstr "" - -#: ../../library/curses.rst:543 -msgid "" -"Sets the number of milliseconds to wait after reading an escape character, " -"to distinguish between an individual escape character entered on the " -"keyboard from escape sequences sent by cursor and function keys." -msgstr "" - -#: ../../library/curses.rst:551 -msgid "Retrieves the value set by :func:`set_tabsize`." -msgstr "" - -#: ../../library/curses.rst:557 -msgid "" -"Sets the number of columns used by the curses library when converting a tab " -"character to spaces as it adds the tab to a window." -msgstr "" - -#: ../../library/curses.rst:564 -msgid "" -"Set the virtual screen cursor to *y*, *x*. If *y* and *x* are both ``-1``, " -"then :meth:`leaveok ` is set ``True``." -msgstr "" - -#: ../../library/curses.rst:570 -msgid "" -"Initialize the terminal. *term* is a string giving the terminal name, or " -"``None``; if omitted or ``None``, the value of the :envvar:`TERM` " -"environment variable will be used. *fd* is the file descriptor to which any " -"initialization sequences will be sent; if not supplied or ``-1``, the file " -"descriptor for ``sys.stdout`` will be used." -msgstr "" - -#: ../../library/curses.rst:579 -msgid "" -"Must be called if the programmer wants to use colors, and before any other " -"color manipulation routine is called. It is good practice to call this " -"routine right after :func:`initscr`." -msgstr "" - -#: ../../library/curses.rst:583 -msgid "" -":func:`start_color` initializes eight basic colors (black, red, green, " -"yellow, blue, magenta, cyan, and white), and two global variables in the :" -"mod:`curses` module, :const:`COLORS` and :const:`COLOR_PAIRS`, containing " -"the maximum number of colors and color-pairs the terminal can support. It " -"also restores the colors on the terminal to the values they had when the " -"terminal was just turned on." -msgstr "" - -#: ../../library/curses.rst:592 -msgid "" -"Return a logical OR of all video attributes supported by the terminal. This " -"information is useful when a curses program needs complete control over the " -"appearance of the screen." -msgstr "" - -#: ../../library/curses.rst:599 -msgid "" -"Return the value of the environment variable :envvar:`TERM`, as a bytes " -"object, truncated to 14 characters." -msgstr "" - -#: ../../library/curses.rst:605 -msgid "" -"Return the value of the Boolean capability corresponding to the terminfo " -"capability name *capname* as an integer. Return the value ``-1`` if " -"*capname* is not a Boolean capability, or ``0`` if it is canceled or absent " -"from the terminal description." -msgstr "" - -#: ../../library/curses.rst:613 -msgid "" -"Return the value of the numeric capability corresponding to the terminfo " -"capability name *capname* as an integer. Return the value ``-2`` if " -"*capname* is not a numeric capability, or ``-1`` if it is canceled or absent " -"from the terminal description." -msgstr "" - -#: ../../library/curses.rst:621 -msgid "" -"Return the value of the string capability corresponding to the terminfo " -"capability name *capname* as a bytes object. Return ``None`` if *capname* " -"is not a terminfo \"string capability\", or is canceled or absent from the " -"terminal description." -msgstr "" - -#: ../../library/curses.rst:629 -msgid "" -"Instantiate the bytes object *str* with the supplied parameters, where *str* " -"should be a parameterized string obtained from the terminfo database. E.g. " -"``tparm(tigetstr(\"cup\"), 5, 3)`` could result in ``b'\\033[6;4H'``, the " -"exact result depending on terminal type." -msgstr "" - -#: ../../library/curses.rst:637 -msgid "" -"Specify that the file descriptor *fd* be used for typeahead checking. If " -"*fd* is ``-1``, then no typeahead checking is done." -msgstr "" - -#: ../../library/curses.rst:640 -msgid "" -"The curses library does \"line-breakout optimization\" by looking for " -"typeahead periodically while updating the screen. If input is found, and it " -"is coming from a tty, the current update is postponed until refresh or " -"doupdate is called again, allowing faster response to commands typed in " -"advance. This function allows specifying a different file descriptor for " -"typeahead checking." -msgstr "" - -#: ../../library/curses.rst:649 -msgid "" -"Return a bytes object which is a printable representation of the character " -"*ch*. Control characters are represented as a caret followed by the " -"character, for example as ``b'^C'``. Printing characters are left as they " -"are." -msgstr "" - -#: ../../library/curses.rst:656 -msgid "Push *ch* so the next :meth:`~window.getch` will return it." -msgstr "" - -#: ../../library/curses.rst:660 -msgid "Only one *ch* can be pushed before :meth:`!getch` is called." -msgstr "" - -#: ../../library/curses.rst:665 -msgid "" -"Update the :const:`LINES` and :const:`COLS` module variables. Useful for " -"detecting manual screen resize." -msgstr "" - -#: ../../library/curses.rst:673 -msgid "Push *ch* so the next :meth:`~window.get_wch` will return it." -msgstr "" - -#: ../../library/curses.rst:677 -msgid "Only one *ch* can be pushed before :meth:`!get_wch` is called." -msgstr "" - -#: ../../library/curses.rst:684 -msgid "" -"Push a :const:`KEY_MOUSE` event onto the input queue, associating the given " -"state data with it." -msgstr "" - -#: ../../library/curses.rst:690 -msgid "" -"If used, this function should be called before :func:`initscr` or newterm " -"are called. When *flag* is ``False``, the values of lines and columns " -"specified in the terminfo database will be used, even if environment " -"variables :envvar:`LINES` and :envvar:`COLUMNS` (used by default) are set, " -"or if curses is running in a window (in which case default behavior would be " -"to use the window size if :envvar:`LINES` and :envvar:`COLUMNS` are not set)." -msgstr "" - -#: ../../library/curses.rst:700 -msgid "Equivalent to ``assume_default_colors(-1, -1)``." -msgstr "" - -#: ../../library/curses.rst:705 -msgid "" -"Initialize curses and call another callable object, *func*, which should be " -"the rest of your curses-using application. If the application raises an " -"exception, this function will restore the terminal to a sane state before re-" -"raising the exception and generating a traceback. The callable object " -"*func* is then passed the main window 'stdscr' as its first argument, " -"followed by any other arguments passed to :func:`!wrapper`. Before calling " -"*func*, :func:`!wrapper` turns on cbreak mode, turns off echo, enables the " -"terminal keypad, and initializes colors if the terminal has color support. " -"On exit (whether normally or by exception) it restores cooked mode, turns on " -"echo, and disables the terminal keypad." -msgstr "" - -#: ../../library/curses.rst:719 -msgid "Window Objects" -msgstr "" - -#: ../../library/curses.rst:723 -msgid "" -"Window objects, as returned by :func:`initscr` and :func:`newwin` above, " -"have the following methods and attributes:" -msgstr "" - -#: ../../library/curses.rst:730 -msgid "" -"Paint character *ch* at ``(y, x)`` with attributes *attr*, overwriting any " -"character previously painted at that location. By default, the character " -"position and attributes are the current settings for the window object." -msgstr "" - -#: ../../library/curses.rst:736 -msgid "" -"Writing outside the window, subwindow, or pad raises a :exc:`curses.error`. " -"Attempting to write to the lower right corner of a window, subwindow, or pad " -"will cause an exception to be raised after the character is printed." -msgstr "" - -#: ../../library/curses.rst:744 -msgid "" -"Paint at most *n* characters of the character string *str* at ``(y, x)`` " -"with attributes *attr*, overwriting anything previously on the display." -msgstr "" - -#: ../../library/curses.rst:752 -msgid "" -"Paint the character string *str* at ``(y, x)`` with attributes *attr*, " -"overwriting anything previously on the display." -msgstr "" - -#: ../../library/curses.rst:757 -msgid "" -"Writing outside the window, subwindow, or pad raises :exc:`curses.error`. " -"Attempting to write to the lower right corner of a window, subwindow, or pad " -"will cause an exception to be raised after the string is printed." -msgstr "" - -#: ../../library/curses.rst:761 -msgid "" -"A `bug in ncurses `_, the backend for " -"this Python module, can cause SegFaults when resizing windows. This is fixed " -"in ncurses-6.1-20190511. If you are stuck with an earlier ncurses, you can " -"avoid triggering this if you do not call :func:`addstr` with a *str* that " -"has embedded newlines. Instead, call :func:`addstr` separately for each " -"line." -msgstr "" - -#: ../../library/curses.rst:771 -msgid "" -"Remove attribute *attr* from the \"background\" set applied to all writes to " -"the current window." -msgstr "" - -#: ../../library/curses.rst:777 -msgid "" -"Add attribute *attr* to the \"background\" set applied to all writes to the " -"current window." -msgstr "" - -#: ../../library/curses.rst:783 -msgid "" -"Set the \"background\" set of attributes to *attr*. This set is initially " -"``0`` (no attributes)." -msgstr "" - -#: ../../library/curses.rst:789 -msgid "" -"Set the background property of the window to the character *ch*, with " -"attributes *attr*. The change is then applied to every character position " -"in that window:" -msgstr "" - -#: ../../library/curses.rst:793 -msgid "" -"The attribute of every character in the window is changed to the new " -"background attribute." -msgstr "" - -#: ../../library/curses.rst:796 -msgid "" -"Wherever the former background character appears, it is changed to the new " -"background character." -msgstr "" - -#: ../../library/curses.rst:802 -msgid "" -"Set the window's background. A window's background consists of a character " -"and any combination of attributes. The attribute part of the background is " -"combined (OR'ed) with all non-blank characters that are written into the " -"window. Both the character and attribute parts of the background are " -"combined with the blank characters. The background becomes a property of " -"the character and moves with the character through any scrolling and insert/" -"delete line/character operations." -msgstr "" - -#: ../../library/curses.rst:812 -msgid "" -"Draw a border around the edges of the window. Each parameter specifies the " -"character to use for a specific part of the border; see the table below for " -"more details." -msgstr "" - -#: ../../library/curses.rst:818 -msgid "" -"A ``0`` value for any parameter will cause the default character to be used " -"for that parameter. Keyword parameters can *not* be used. The defaults are " -"listed in this table:" -msgstr "" - -#: ../../library/curses.rst:823 -msgid "Parameter" -msgstr "參數" - -#: ../../library/curses.rst:823 -msgid "Description" -msgstr "描述" - -#: ../../library/curses.rst:823 -msgid "Default value" -msgstr "預設值" - -#: ../../library/curses.rst:825 -msgid "*ls*" -msgstr "*ls*" - -#: ../../library/curses.rst:825 -msgid "Left side" -msgstr "" - -#: ../../library/curses.rst:825 ../../library/curses.rst:827 -msgid ":const:`ACS_VLINE`" -msgstr ":const:`ACS_VLINE`" - -#: ../../library/curses.rst:827 -msgid "*rs*" -msgstr "*rs*" - -#: ../../library/curses.rst:827 -msgid "Right side" -msgstr "" - -#: ../../library/curses.rst:829 -msgid "*ts*" -msgstr "*ts*" - -#: ../../library/curses.rst:829 -msgid "Top" -msgstr "" - -#: ../../library/curses.rst:829 ../../library/curses.rst:831 -msgid ":const:`ACS_HLINE`" -msgstr ":const:`ACS_HLINE`" - -#: ../../library/curses.rst:831 -msgid "*bs*" -msgstr "*bs*" - -#: ../../library/curses.rst:831 -msgid "Bottom" -msgstr "" - -#: ../../library/curses.rst:833 -msgid "*tl*" -msgstr "*tl*" - -#: ../../library/curses.rst:833 -msgid "Upper-left corner" -msgstr "" - -#: ../../library/curses.rst:833 -msgid ":const:`ACS_ULCORNER`" -msgstr ":const:`ACS_ULCORNER`" - -#: ../../library/curses.rst:835 -msgid "*tr*" -msgstr "*tr*" - -#: ../../library/curses.rst:835 -msgid "Upper-right corner" -msgstr "" - -#: ../../library/curses.rst:835 -msgid ":const:`ACS_URCORNER`" -msgstr ":const:`ACS_URCORNER`" - -#: ../../library/curses.rst:837 -msgid "*bl*" -msgstr "*bl*" - -#: ../../library/curses.rst:837 -msgid "Bottom-left corner" -msgstr "" - -#: ../../library/curses.rst:837 -msgid ":const:`ACS_LLCORNER`" -msgstr ":const:`ACS_LLCORNER`" - -#: ../../library/curses.rst:839 -msgid "*br*" -msgstr "*br*" - -#: ../../library/curses.rst:839 -msgid "Bottom-right corner" -msgstr "" - -#: ../../library/curses.rst:839 -msgid ":const:`ACS_LRCORNER`" -msgstr ":const:`ACS_LRCORNER`" - -#: ../../library/curses.rst:845 -msgid "" -"Similar to :meth:`border`, but both *ls* and *rs* are *vertch* and both *ts* " -"and *bs* are *horch*. The default corner characters are always used by this " -"function." -msgstr "" - -#: ../../library/curses.rst:854 -msgid "" -"Set the attributes of *num* characters at the current cursor position, or at " -"position ``(y, x)`` if supplied. If *num* is not given or is ``-1``, the " -"attribute will be set on all the characters to the end of the line. This " -"function moves cursor to position ``(y, x)`` if supplied. The changed line " -"will be touched using the :meth:`touchline` method so that the contents will " -"be redisplayed by the next window refresh." -msgstr "" - -#: ../../library/curses.rst:864 -msgid "" -"Like :meth:`erase`, but also cause the whole window to be repainted upon " -"next call to :meth:`refresh`." -msgstr "" - -#: ../../library/curses.rst:870 -msgid "" -"If *flag* is ``True``, the next call to :meth:`refresh` will clear the " -"window completely." -msgstr "" - -#: ../../library/curses.rst:876 -msgid "" -"Erase from cursor to the end of the window: all lines below the cursor are " -"deleted, and then the equivalent of :meth:`clrtoeol` is performed." -msgstr "" - -#: ../../library/curses.rst:882 -msgid "Erase from cursor to the end of the line." -msgstr "" - -#: ../../library/curses.rst:887 -msgid "" -"Update the current cursor position of all the ancestors of the window to " -"reflect the current cursor position of the window." -msgstr "" - -#: ../../library/curses.rst:893 -msgid "Delete any character at ``(y, x)``." -msgstr "" - -#: ../../library/curses.rst:898 -msgid "" -"Delete the line under the cursor. All following lines are moved up by one " -"line." -msgstr "" - -#: ../../library/curses.rst:904 -msgid "" -"An abbreviation for \"derive window\", :meth:`derwin` is the same as " -"calling :meth:`subwin`, except that *begin_y* and *begin_x* are relative to " -"the origin of the window, rather than relative to the entire screen. Return " -"a window object for the derived window." -msgstr "" - -#: ../../library/curses.rst:912 -msgid "" -"Add character *ch* with attribute *attr*, and immediately call :meth:" -"`refresh` on the window." -msgstr "" - -#: ../../library/curses.rst:918 -msgid "" -"Test whether the given pair of screen-relative character-cell coordinates " -"are enclosed by the given window, returning ``True`` or ``False``. It is " -"useful for determining what subset of the screen windows enclose the " -"location of a mouse event." -msgstr "" - -#: ../../library/curses.rst:923 -msgid "Previously it returned ``1`` or ``0`` instead of ``True`` or ``False``." -msgstr "" - -#: ../../library/curses.rst:929 -msgid "" -"Encoding used to encode method arguments (Unicode strings and characters). " -"The encoding attribute is inherited from the parent window when a subwindow " -"is created, for example with :meth:`window.subwin`. By default, current " -"locale encoding is used (see :func:`locale.getencoding`)." -msgstr "" - -#: ../../library/curses.rst:939 -msgid "Clear the window." -msgstr "清除視窗。" - -#: ../../library/curses.rst:944 -msgid "Return a tuple ``(y, x)`` of coordinates of upper-left corner." -msgstr "回傳左上角的座標 ``(y, x)``。" - -#: ../../library/curses.rst:949 -msgid "Return the given window's current background character/attribute pair." -msgstr "回傳給定視窗目前的背景字元/屬性對。" - -#: ../../library/curses.rst:954 -msgid "" -"Get a character. Note that the integer returned does *not* have to be in " -"ASCII range: function keys, keypad keys and so on are represented by numbers " -"higher than 255. In no-delay mode, return ``-1`` if there is no input, " -"otherwise wait until a key is pressed." -msgstr "" - -#: ../../library/curses.rst:962 -msgid "" -"Get a wide character. Return a character for most keys, or an integer for " -"function keys, keypad keys, and other special keys. In no-delay mode, raise " -"an exception if there is no input." -msgstr "" - -#: ../../library/curses.rst:971 -msgid "" -"Get a character, returning a string instead of an integer, as :meth:`getch` " -"does. Function keys, keypad keys and other special keys return a multibyte " -"string containing the key name. In no-delay mode, raise an exception if " -"there is no input." -msgstr "" - -#: ../../library/curses.rst:979 -msgid "Return a tuple ``(y, x)`` of the height and width of the window." -msgstr "回傳視窗的高度和寬度的元組 ``(y, x)``。" - -#: ../../library/curses.rst:984 -msgid "" -"Return the beginning coordinates of this window relative to its parent " -"window as a tuple ``(y, x)``. Return ``(-1, -1)`` if this window has no " -"parent." -msgstr "" - -#: ../../library/curses.rst:994 -msgid "" -"Read a bytes object from the user, with primitive line editing capacity. The " -"maximum value for *n* is 2047." -msgstr "" - -#: ../../library/curses.rst:997 ../../library/curses.rst:1092 -msgid "The maximum value for *n* was increased from 1023 to 2047." -msgstr "" - -#: ../../library/curses.rst:1003 -msgid "" -"Return a tuple ``(y, x)`` of current cursor position relative to the " -"window's upper-left corner." -msgstr "" - -#: ../../library/curses.rst:1010 -msgid "" -"Display a horizontal line starting at ``(y, x)`` with length *n* consisting " -"of the character *ch*." -msgstr "" - -#: ../../library/curses.rst:1016 -msgid "" -"If *flag* is ``False``, curses no longer considers using the hardware insert/" -"delete character feature of the terminal; if *flag* is ``True``, use of " -"character insertion and deletion is enabled. When curses is first " -"initialized, use of character insert/delete is enabled by default." -msgstr "" - -#: ../../library/curses.rst:1024 -msgid "" -"If *flag* is ``True``, :mod:`curses` will try and use hardware line editing " -"facilities. Otherwise, line insertion/deletion are disabled." -msgstr "" - -#: ../../library/curses.rst:1030 -msgid "" -"If *flag* is ``True``, any change in the window image automatically causes " -"the window to be refreshed; you no longer have to call :meth:`refresh` " -"yourself. However, it may degrade performance considerably, due to repeated " -"calls to wrefresh. This option is disabled by default." -msgstr "" - -#: ../../library/curses.rst:1038 -msgid "" -"Return the character at the given position in the window. The bottom 8 bits " -"are the character proper, and upper bits are the attributes." -msgstr "" - -#: ../../library/curses.rst:1045 -msgid "" -"Paint character *ch* at ``(y, x)`` with attributes *attr*, moving the line " -"from position *x* right by one character." -msgstr "" - -#: ../../library/curses.rst:1051 -msgid "" -"Insert *nlines* lines into the specified window above the current line. The " -"*nlines* bottom lines are lost. For negative *nlines*, delete *nlines* " -"lines starting with the one under the cursor, and move the remaining lines " -"up. The bottom *nlines* lines are cleared. The current cursor position " -"remains the same." -msgstr "" - -#: ../../library/curses.rst:1060 -msgid "" -"Insert a blank line under the cursor. All following lines are moved down by " -"one line." -msgstr "" - -#: ../../library/curses.rst:1067 -msgid "" -"Insert a character string (as many characters as will fit on the line) " -"before the character under the cursor, up to *n* characters. If *n* is " -"zero or negative, the entire string is inserted. All characters to the right " -"of the cursor are shifted right, with the rightmost characters on the line " -"being lost. The cursor position does not change (after moving to *y*, *x*, " -"if specified)." -msgstr "" - -#: ../../library/curses.rst:1077 -msgid "" -"Insert a character string (as many characters as will fit on the line) " -"before the character under the cursor. All characters to the right of the " -"cursor are shifted right, with the rightmost characters on the line being " -"lost. The cursor position does not change (after moving to *y*, *x*, if " -"specified)." -msgstr "" - -#: ../../library/curses.rst:1086 -msgid "" -"Return a bytes object of characters, extracted from the window starting at " -"the current cursor position, or at *y*, *x* if specified. Attributes are " -"stripped from the characters. If *n* is specified, :meth:`instr` returns a " -"string at most *n* characters long (exclusive of the trailing NUL). The " -"maximum value for *n* is 2047." -msgstr "" - -#: ../../library/curses.rst:1098 -msgid "" -"Return ``True`` if the specified line was modified since the last call to :" -"meth:`refresh`; otherwise return ``False``. Raise a :exc:`curses.error` " -"exception if *line* is not valid for the given window." -msgstr "" - -#: ../../library/curses.rst:1105 -msgid "" -"Return ``True`` if the specified window was modified since the last call to :" -"meth:`refresh`; otherwise return ``False``." -msgstr "" - -#: ../../library/curses.rst:1111 -msgid "" -"If *flag* is ``True``, escape sequences generated by some keys (keypad, " -"function keys) will be interpreted by :mod:`curses`. If *flag* is ``False``, " -"escape sequences will be left as is in the input stream." -msgstr "" - -#: ../../library/curses.rst:1118 -msgid "" -"If *flag* is ``True``, cursor is left where it is on update, instead of " -"being at \"cursor position.\" This reduces cursor movement where possible. " -"If possible the cursor will be made invisible." -msgstr "" - -#: ../../library/curses.rst:1122 -msgid "" -"If *flag* is ``False``, cursor will always be at \"cursor position\" after " -"an update." -msgstr "" - -#: ../../library/curses.rst:1127 -msgid "Move cursor to ``(new_y, new_x)``." -msgstr "移動游標到 ``(new_y, new_x)``。" - -#: ../../library/curses.rst:1132 -msgid "" -"Move the window inside its parent window. The screen-relative parameters of " -"the window are not changed. This routine is used to display different parts " -"of the parent window at the same physical position on the screen." -msgstr "" - -#: ../../library/curses.rst:1139 -msgid "Move the window so its upper-left corner is at ``(new_y, new_x)``." -msgstr "" - -#: ../../library/curses.rst:1144 -msgid "If *flag* is ``True``, :meth:`getch` will be non-blocking." -msgstr "如果 *flag* 為 ``True``，則 :meth:`getch` 將為非阻塞的。" - -#: ../../library/curses.rst:1149 -msgid "If *flag* is ``True``, escape sequences will not be timed out." -msgstr "" - -#: ../../library/curses.rst:1151 -msgid "" -"If *flag* is ``False``, after a few milliseconds, an escape sequence will " -"not be interpreted, and will be left in the input stream as is." -msgstr "" - -#: ../../library/curses.rst:1157 -msgid "" -"Mark for refresh but wait. This function updates the data structure " -"representing the desired state of the window, but does not force an update " -"of the physical screen. To accomplish that, call :func:`doupdate`." -msgstr "" - -#: ../../library/curses.rst:1164 -msgid "" -"Overlay the window on top of *destwin*. The windows need not be the same " -"size, only the overlapping region is copied. This copy is non-destructive, " -"which means that the current background character does not overwrite the old " -"contents of *destwin*." -msgstr "" - -#: ../../library/curses.rst:1169 -msgid "" -"To get fine-grained control over the copied region, the second form of :meth:" -"`overlay` can be used. *sminrow* and *smincol* are the upper-left " -"coordinates of the source window, and the other variables mark a rectangle " -"in the destination window." -msgstr "" - -#: ../../library/curses.rst:1177 -msgid "" -"Overwrite the window on top of *destwin*. The windows need not be the same " -"size, in which case only the overlapping region is copied. This copy is " -"destructive, which means that the current background character overwrites " -"the old contents of *destwin*." -msgstr "" - -#: ../../library/curses.rst:1182 -msgid "" -"To get fine-grained control over the copied region, the second form of :meth:" -"`overwrite` can be used. *sminrow* and *smincol* are the upper-left " -"coordinates of the source window, the other variables mark a rectangle in " -"the destination window." -msgstr "" - -#: ../../library/curses.rst:1190 -msgid "" -"Write all data associated with the window into the provided file object. " -"This information can be later retrieved using the :func:`getwin` function." -msgstr "" - -#: ../../library/curses.rst:1196 -msgid "" -"Indicate that the *num* screen lines, starting at line *beg*, are corrupted " -"and should be completely redrawn on the next :meth:`refresh` call." -msgstr "" - -#: ../../library/curses.rst:1202 -msgid "" -"Touch the entire window, causing it to be completely redrawn on the next :" -"meth:`refresh` call." -msgstr "" - -#: ../../library/curses.rst:1208 -msgid "" -"Update the display immediately (sync actual screen with previous drawing/" -"deleting methods)." -msgstr "" - -#: ../../library/curses.rst:1211 -msgid "" -"The 6 optional arguments can only be specified when the window is a pad " -"created with :func:`newpad`. The additional parameters are needed to " -"indicate what part of the pad and screen are involved. *pminrow* and " -"*pmincol* specify the upper left-hand corner of the rectangle to be " -"displayed in the pad. *sminrow*, *smincol*, *smaxrow*, and *smaxcol* " -"specify the edges of the rectangle to be displayed on the screen. The lower " -"right-hand corner of the rectangle to be displayed in the pad is calculated " -"from the screen coordinates, since the rectangles must be the same size. " -"Both rectangles must be entirely contained within their respective " -"structures. Negative values of *pminrow*, *pmincol*, *sminrow*, or " -"*smincol* are treated as if they were zero." -msgstr "" - -#: ../../library/curses.rst:1225 -msgid "" -"Reallocate storage for a curses window to adjust its dimensions to the " -"specified values. If either dimension is larger than the current values, " -"the window's data is filled with blanks that have the current background " -"rendition (as set by :meth:`bkgdset`) merged into them." -msgstr "" - -#: ../../library/curses.rst:1233 -msgid "Scroll the screen or scrolling region upward by *lines* lines." -msgstr "" - -#: ../../library/curses.rst:1238 -msgid "" -"Control what happens when the cursor of a window is moved off the edge of " -"the window or scrolling region, either as a result of a newline action on " -"the bottom line, or typing the last character of the last line. If *flag* " -"is ``False``, the cursor is left on the bottom line. If *flag* is ``True``, " -"the window is scrolled up one line. Note that in order to get the physical " -"scrolling effect on the terminal, it is also necessary to call :meth:`idlok`." -msgstr "" - -#: ../../library/curses.rst:1248 -msgid "" -"Set the scrolling region from line *top* to line *bottom*. All scrolling " -"actions will take place in this region." -msgstr "" - -#: ../../library/curses.rst:1254 -msgid "" -"Turn off the standout attribute. On some terminals this has the side effect " -"of turning off all attributes." -msgstr "" - -#: ../../library/curses.rst:1260 -msgid "Turn on attribute *A_STANDOUT*." -msgstr "" - -#: ../../library/curses.rst:1266 ../../library/curses.rst:1273 -msgid "" -"Return a sub-window, whose upper-left corner is at ``(begin_y, begin_x)``, " -"and whose width/height is *ncols*/*nlines*." -msgstr "" - -#: ../../library/curses.rst:1276 -msgid "" -"By default, the sub-window will extend from the specified position to the " -"lower right corner of the window." -msgstr "" - -#: ../../library/curses.rst:1282 -msgid "" -"Touch each location in the window that has been touched in any of its " -"ancestor windows. This routine is called by :meth:`refresh`, so it should " -"almost never be necessary to call it manually." -msgstr "" - -#: ../../library/curses.rst:1289 -msgid "" -"If *flag* is ``True``, then :meth:`syncup` is called automatically whenever " -"there is a change in the window." -msgstr "" - -#: ../../library/curses.rst:1295 -msgid "" -"Touch all locations in ancestors of the window that have been changed in " -"the window." -msgstr "" - -#: ../../library/curses.rst:1301 -msgid "" -"Set blocking or non-blocking read behavior for the window. If *delay* is " -"negative, blocking read is used (which will wait indefinitely for input). " -"If *delay* is zero, then non-blocking read is used, and :meth:`getch` will " -"return ``-1`` if no input is waiting. If *delay* is positive, then :meth:" -"`getch` will block for *delay* milliseconds, and return ``-1`` if there is " -"still no input at the end of that time." -msgstr "" - -#: ../../library/curses.rst:1311 -msgid "" -"Pretend *count* lines have been changed, starting with line *start*. If " -"*changed* is supplied, it specifies whether the affected lines are marked as " -"having been changed (*changed*\\ ``=True``) or unchanged (*changed*\\ " -"``=False``)." -msgstr "" - -#: ../../library/curses.rst:1318 -msgid "" -"Pretend the whole window has been changed, for purposes of drawing " -"optimizations." -msgstr "" - -#: ../../library/curses.rst:1324 -msgid "" -"Mark all lines in the window as unchanged since the last call to :meth:" -"`refresh`." -msgstr "" - -#: ../../library/curses.rst:1331 -msgid "" -"Display a vertical line starting at ``(y, x)`` with length *n* consisting of " -"the character *ch* with attributes *attr*." -msgstr "" - -#: ../../library/curses.rst:1336 -msgid "Constants" -msgstr "" - -#: ../../library/curses.rst:1338 -msgid "The :mod:`curses` module defines the following data members:" -msgstr ":mod:`curses` 模組定義了以下資料成員：" - -#: ../../library/curses.rst:1343 -msgid "" -"Some curses routines that return an integer, such as :meth:`~window." -"getch`, return :const:`ERR` upon failure." -msgstr "" - -#: ../../library/curses.rst:1349 -msgid "" -"Some curses routines that return an integer, such as :func:`napms`, " -"return :const:`OK` upon success." -msgstr "" - -#: ../../library/curses.rst:1355 -msgid "A bytes object representing the current version of the module." -msgstr "" - -#: ../../library/curses.rst:1360 -msgid "" -"A named tuple containing the three components of the ncurses library " -"version: *major*, *minor*, and *patch*. All values are integers. The " -"components can also be accessed by name, so ``curses.ncurses_version[0]`` " -"is equivalent to ``curses.ncurses_version.major`` and so on." -msgstr "" - -#: ../../library/curses.rst:1365 -msgid "Availability: if the ncurses library is used." -msgstr "" - -#: ../../library/curses.rst:1371 -msgid "" -"The maximum number of colors the terminal can support. It is defined only " -"after the call to :func:`start_color`." -msgstr "" - -#: ../../library/curses.rst:1376 -msgid "" -"The maximum number of color pairs the terminal can support. It is defined " -"only after the call to :func:`start_color`." -msgstr "" - -#: ../../library/curses.rst:1381 -msgid "" -"The width of the screen, i.e., the number of columns. It is defined only " -"after the call to :func:`initscr`. Updated by :func:`update_lines_cols`, :" -"func:`resizeterm` and :func:`resize_term`." -msgstr "" - -#: ../../library/curses.rst:1388 -msgid "" -"The height of the screen, i.e., the number of lines. It is defined only " -"after the call to :func:`initscr`. Updated by :func:`update_lines_cols`, :" -"func:`resizeterm` and :func:`resize_term`." -msgstr "" - -#: ../../library/curses.rst:1394 -msgid "" -"Some constants are available to specify character cell attributes. The exact " -"constants available are system dependent." -msgstr "" - -#: ../../library/curses.rst:1398 -msgid "Attribute" -msgstr "" - -#: ../../library/curses.rst:1398 ../../library/curses.rst:1443 -#: ../../library/curses.rst:1689 ../../library/curses.rst:1781 -msgid "Meaning" -msgstr "含義" - -#: ../../library/curses.rst:1400 -msgid "Alternate character set mode" -msgstr "" - -#: ../../library/curses.rst:1402 -msgid "Blink mode" -msgstr "" - -#: ../../library/curses.rst:1404 -msgid "Bold mode" -msgstr "" - -#: ../../library/curses.rst:1406 -msgid "Dim mode" -msgstr "" - -#: ../../library/curses.rst:1408 -msgid "Invisible or blank mode" -msgstr "" - -#: ../../library/curses.rst:1410 -msgid "Italic mode" -msgstr "" - -#: ../../library/curses.rst:1412 -msgid "Normal attribute" -msgstr "" - -#: ../../library/curses.rst:1414 -msgid "Protected mode" -msgstr "" - -#: ../../library/curses.rst:1416 -msgid "Reverse background and foreground colors" -msgstr "" - -#: ../../library/curses.rst:1419 -msgid "Standout mode" -msgstr "" - -#: ../../library/curses.rst:1421 -msgid "Underline mode" -msgstr "" - -#: ../../library/curses.rst:1423 -msgid "Horizontal highlight" -msgstr "" - -#: ../../library/curses.rst:1425 -msgid "Left highlight" -msgstr "" - -#: ../../library/curses.rst:1427 -msgid "Low highlight" -msgstr "" - -#: ../../library/curses.rst:1429 -msgid "Right highlight" -msgstr "" - -#: ../../library/curses.rst:1431 -msgid "Top highlight" -msgstr "" - -#: ../../library/curses.rst:1433 -msgid "Vertical highlight" -msgstr "" - -#: ../../library/curses.rst:1436 -msgid "``A_ITALIC`` was added." -msgstr "新增 ``A_ITALIC``。" - -#: ../../library/curses.rst:1439 -msgid "" -"Several constants are available to extract corresponding attributes returned " -"by some methods." -msgstr "" - -#: ../../library/curses.rst:1443 -msgid "Bit-mask" -msgstr "" - -#: ../../library/curses.rst:1445 -msgid "Bit-mask to extract attributes" -msgstr "" - -#: ../../library/curses.rst:1448 -msgid "Bit-mask to extract a character" -msgstr "" - -#: ../../library/curses.rst:1451 -msgid "Bit-mask to extract color-pair field information" -msgstr "" - -#: ../../library/curses.rst:1455 -msgid "" -"Keys are referred to by integer constants with names starting with " -"``KEY_``. The exact keycaps available are system dependent." -msgstr "" - -#: ../../library/curses.rst:1461 -msgid "Key constant" -msgstr "" - -#: ../../library/curses.rst:1461 -msgid "Key" -msgstr "" - -#: ../../library/curses.rst:1463 -msgid "Minimum key value" -msgstr "" - -#: ../../library/curses.rst:1465 -msgid "Break key (unreliable)" -msgstr "" - -#: ../../library/curses.rst:1467 -msgid "Down-arrow" -msgstr "" - -#: ../../library/curses.rst:1469 -msgid "Up-arrow" -msgstr "" - -#: ../../library/curses.rst:1471 -msgid "Left-arrow" -msgstr "" - -#: ../../library/curses.rst:1473 -msgid "Right-arrow" -msgstr "" - -#: ../../library/curses.rst:1475 -msgid "Home key (upward+left arrow)" -msgstr "" - -#: ../../library/curses.rst:1477 -msgid "Backspace (unreliable)" -msgstr "" - -#: ../../library/curses.rst:1479 -msgid "Function keys. Up to 64 function keys are supported." -msgstr "" - -#: ../../library/curses.rst:1482 -msgid "Value of function key *n*" -msgstr "" - -#: ../../library/curses.rst:1484 -msgid "Delete line" -msgstr "" - -#: ../../library/curses.rst:1486 -msgid "Insert line" -msgstr "" - -#: ../../library/curses.rst:1488 -msgid "Delete character" -msgstr "" - -#: ../../library/curses.rst:1490 -msgid "Insert char or enter insert mode" -msgstr "" - -#: ../../library/curses.rst:1492 -msgid "Exit insert char mode" -msgstr "" - -#: ../../library/curses.rst:1494 -msgid "Clear screen" -msgstr "" - -#: ../../library/curses.rst:1496 -msgid "Clear to end of screen" -msgstr "" - -#: ../../library/curses.rst:1498 -msgid "Clear to end of line" -msgstr "" - -#: ../../library/curses.rst:1500 -msgid "Scroll 1 line forward" -msgstr "" - -#: ../../library/curses.rst:1502 -msgid "Scroll 1 line backward (reverse)" -msgstr "" - -#: ../../library/curses.rst:1504 -msgid "Next page" -msgstr "" - -#: ../../library/curses.rst:1506 -msgid "Previous page" -msgstr "" - -#: ../../library/curses.rst:1508 -msgid "Set tab" -msgstr "" - -#: ../../library/curses.rst:1510 -msgid "Clear tab" -msgstr "" - -#: ../../library/curses.rst:1512 -msgid "Clear all tabs" -msgstr "" - -#: ../../library/curses.rst:1514 -msgid "Enter or send (unreliable)" -msgstr "" - -#: ../../library/curses.rst:1516 -msgid "Soft (partial) reset (unreliable)" -msgstr "" - -#: ../../library/curses.rst:1518 -msgid "Reset or hard reset (unreliable)" -msgstr "" - -#: ../../library/curses.rst:1520 -msgid "Print" -msgstr "" - -#: ../../library/curses.rst:1522 -msgid "Home down or bottom (lower left)" -msgstr "" - -#: ../../library/curses.rst:1524 -msgid "Upper left of keypad" -msgstr "" - -#: ../../library/curses.rst:1526 -msgid "Upper right of keypad" -msgstr "" - -#: ../../library/curses.rst:1528 -msgid "Center of keypad" -msgstr "" - -#: ../../library/curses.rst:1530 -msgid "Lower left of keypad" -msgstr "" - -#: ../../library/curses.rst:1532 -msgid "Lower right of keypad" -msgstr "" - -#: ../../library/curses.rst:1534 -msgid "Back tab" -msgstr "" - -#: ../../library/curses.rst:1536 -msgid "Beg (beginning)" -msgstr "" - -#: ../../library/curses.rst:1538 -msgid "Cancel" -msgstr "" - -#: ../../library/curses.rst:1540 -msgid "Close" -msgstr "" - -#: ../../library/curses.rst:1542 -msgid "Cmd (command)" -msgstr "" - -#: ../../library/curses.rst:1544 -msgid "Copy" -msgstr "" - -#: ../../library/curses.rst:1546 -msgid "Create" -msgstr "" - -#: ../../library/curses.rst:1548 -msgid "End" -msgstr "" - -#: ../../library/curses.rst:1550 -msgid "Exit" -msgstr "" - -#: ../../library/curses.rst:1552 -msgid "Find" -msgstr "" - -#: ../../library/curses.rst:1554 -msgid "Help" -msgstr "" - -#: ../../library/curses.rst:1556 -msgid "Mark" -msgstr "" - -#: ../../library/curses.rst:1558 -msgid "Message" -msgstr "" - -#: ../../library/curses.rst:1560 -msgid "Move" -msgstr "" - -#: ../../library/curses.rst:1562 -msgid "Next" -msgstr "" - -#: ../../library/curses.rst:1564 -msgid "Open" -msgstr "" - -#: ../../library/curses.rst:1566 -msgid "Options" -msgstr "" - -#: ../../library/curses.rst:1568 -msgid "Prev (previous)" -msgstr "" - -#: ../../library/curses.rst:1570 -msgid "Redo" -msgstr "" - -#: ../../library/curses.rst:1572 -msgid "Ref (reference)" -msgstr "" - -#: ../../library/curses.rst:1574 -msgid "Refresh" -msgstr "" - -#: ../../library/curses.rst:1576 -msgid "Replace" -msgstr "" - -#: ../../library/curses.rst:1578 -msgid "Restart" -msgstr "" - -#: ../../library/curses.rst:1580 -msgid "Resume" -msgstr "" - -#: ../../library/curses.rst:1582 -msgid "Save" -msgstr "" - -#: ../../library/curses.rst:1584 -msgid "Shifted Beg (beginning)" -msgstr "" - -#: ../../library/curses.rst:1586 -msgid "Shifted Cancel" -msgstr "" - -#: ../../library/curses.rst:1588 -msgid "Shifted Command" -msgstr "" - -#: ../../library/curses.rst:1590 -msgid "Shifted Copy" -msgstr "" - -#: ../../library/curses.rst:1592 -msgid "Shifted Create" -msgstr "" - -#: ../../library/curses.rst:1594 -msgid "Shifted Delete char" -msgstr "" - -#: ../../library/curses.rst:1596 -msgid "Shifted Delete line" -msgstr "" - -#: ../../library/curses.rst:1598 -msgid "Select" -msgstr "" - -#: ../../library/curses.rst:1600 -msgid "Shifted End" -msgstr "" - -#: ../../library/curses.rst:1602 -msgid "Shifted Clear line" -msgstr "" - -#: ../../library/curses.rst:1604 -msgid "Shifted Exit" -msgstr "" - -#: ../../library/curses.rst:1606 -msgid "Shifted Find" -msgstr "" - -#: ../../library/curses.rst:1608 -msgid "Shifted Help" -msgstr "" - -#: ../../library/curses.rst:1610 -msgid "Shifted Home" -msgstr "" - -#: ../../library/curses.rst:1612 -msgid "Shifted Input" -msgstr "" - -#: ../../library/curses.rst:1614 -msgid "Shifted Left arrow" -msgstr "" - -#: ../../library/curses.rst:1616 -msgid "Shifted Message" -msgstr "" - -#: ../../library/curses.rst:1618 -msgid "Shifted Move" -msgstr "" - -#: ../../library/curses.rst:1620 -msgid "Shifted Next" -msgstr "" - -#: ../../library/curses.rst:1622 -msgid "Shifted Options" -msgstr "" - -#: ../../library/curses.rst:1624 -msgid "Shifted Prev" -msgstr "" - -#: ../../library/curses.rst:1626 -msgid "Shifted Print" -msgstr "" - -#: ../../library/curses.rst:1628 -msgid "Shifted Redo" -msgstr "" - -#: ../../library/curses.rst:1630 -msgid "Shifted Replace" -msgstr "" - -#: ../../library/curses.rst:1632 -msgid "Shifted Right arrow" -msgstr "" - -#: ../../library/curses.rst:1634 -msgid "Shifted Resume" -msgstr "" - -#: ../../library/curses.rst:1636 -msgid "Shifted Save" -msgstr "" - -#: ../../library/curses.rst:1638 -msgid "Shifted Suspend" -msgstr "" - -#: ../../library/curses.rst:1640 -msgid "Shifted Undo" -msgstr "" - -#: ../../library/curses.rst:1642 -msgid "Suspend" -msgstr "" - -#: ../../library/curses.rst:1644 -msgid "Undo" -msgstr "" - -#: ../../library/curses.rst:1646 -msgid "Mouse event has occurred" -msgstr "" - -#: ../../library/curses.rst:1648 -msgid "Terminal resize event" -msgstr "" - -#: ../../library/curses.rst:1650 -msgid "Maximum key value" -msgstr "" - -#: ../../library/curses.rst:1653 -msgid "" -"On VT100s and their software emulations, such as X terminal emulators, there " -"are normally at least four function keys (:const:`KEY_F1 `, :const:" -"`KEY_F2 `, :const:`KEY_F3 `, :const:`KEY_F4 `) " -"available, and the arrow keys mapped to :const:`KEY_UP`, :const:`KEY_DOWN`, :" -"const:`KEY_LEFT` and :const:`KEY_RIGHT` in the obvious way. If your machine " -"has a PC keyboard, it is safe to expect arrow keys and twelve function keys " -"(older PC keyboards may have only ten function keys); also, the following " -"keypad mappings are standard:" -msgstr "" - -#: ../../library/curses.rst:1662 -msgid "Keycap" -msgstr "" - -#: ../../library/curses.rst:1662 ../../library/curses.rst:1807 -#: ../../library/curses.rst:1931 -msgid "Constant" -msgstr "" - -#: ../../library/curses.rst:1664 -msgid ":kbd:`Insert`" -msgstr ":kbd:`Insert`" - -#: ../../library/curses.rst:1664 -msgid "KEY_IC" -msgstr "KEY_IC" - -#: ../../library/curses.rst:1666 -msgid ":kbd:`Delete`" -msgstr ":kbd:`Delete`" - -#: ../../library/curses.rst:1666 -msgid "KEY_DC" -msgstr "KEY_DC" - -#: ../../library/curses.rst:1668 -msgid ":kbd:`Home`" -msgstr ":kbd:`Home`" - -#: ../../library/curses.rst:1668 -msgid "KEY_HOME" -msgstr "KEY_HOME" - -#: ../../library/curses.rst:1670 -msgid ":kbd:`End`" -msgstr ":kbd:`End`" - -#: ../../library/curses.rst:1670 -msgid "KEY_END" -msgstr "KEY_END" - -#: ../../library/curses.rst:1672 -msgid ":kbd:`Page Up`" -msgstr ":kbd:`Page Up`" - -#: ../../library/curses.rst:1672 -msgid "KEY_PPAGE" -msgstr "KEY_PPAGE" - -#: ../../library/curses.rst:1674 -msgid ":kbd:`Page Down`" -msgstr ":kbd:`Page Down`" - -#: ../../library/curses.rst:1674 -msgid "KEY_NPAGE" -msgstr "KEY_NPAGE" - -#: ../../library/curses.rst:1679 -msgid "" -"The following table lists characters from the alternate character set. These " -"are inherited from the VT100 terminal, and will generally be available on " -"software emulations such as X terminals. When there is no graphic " -"available, curses falls back on a crude printable ASCII approximation." -msgstr "" - -#: ../../library/curses.rst:1686 -msgid "These are available only after :func:`initscr` has been called." -msgstr "" - -#: ../../library/curses.rst:1689 -msgid "ACS code" -msgstr "" - -#: ../../library/curses.rst:1691 -msgid "alternate name for upper right corner" -msgstr "" - -#: ../../library/curses.rst:1693 -msgid "solid square block" -msgstr "" - -#: ../../library/curses.rst:1695 -msgid "board of squares" -msgstr "" - -#: ../../library/curses.rst:1697 -msgid "alternate name for horizontal line" -msgstr "" - -#: ../../library/curses.rst:1699 -msgid "alternate name for upper left corner" -msgstr "" - -#: ../../library/curses.rst:1701 -msgid "alternate name for top tee" -msgstr "" - -#: ../../library/curses.rst:1703 -msgid "bottom tee" -msgstr "" - -#: ../../library/curses.rst:1705 -msgid "bullet" -msgstr "" - -#: ../../library/curses.rst:1707 -msgid "checker board (stipple)" -msgstr "" - -#: ../../library/curses.rst:1709 -msgid "arrow pointing down" -msgstr "" - -#: ../../library/curses.rst:1711 -msgid "degree symbol" -msgstr "" - -#: ../../library/curses.rst:1713 -msgid "diamond" -msgstr "" - -#: ../../library/curses.rst:1715 -msgid "greater-than-or-equal-to" -msgstr "" - -#: ../../library/curses.rst:1717 -msgid "horizontal line" -msgstr "" - -#: ../../library/curses.rst:1719 -msgid "lantern symbol" -msgstr "" - -#: ../../library/curses.rst:1721 -msgid "left arrow" -msgstr "" - -#: ../../library/curses.rst:1723 -msgid "less-than-or-equal-to" -msgstr "" - -#: ../../library/curses.rst:1725 -msgid "lower left-hand corner" -msgstr "" - -#: ../../library/curses.rst:1727 -msgid "lower right-hand corner" -msgstr "" - -#: ../../library/curses.rst:1729 -msgid "left tee" -msgstr "" - -#: ../../library/curses.rst:1731 -msgid "not-equal sign" -msgstr "" - -#: ../../library/curses.rst:1733 -msgid "letter pi" -msgstr "" - -#: ../../library/curses.rst:1735 -msgid "plus-or-minus sign" -msgstr "" - -#: ../../library/curses.rst:1737 -msgid "big plus sign" -msgstr "" - -#: ../../library/curses.rst:1739 -msgid "right arrow" -msgstr "" - -#: ../../library/curses.rst:1741 -msgid "right tee" -msgstr "" - -#: ../../library/curses.rst:1743 -msgid "scan line 1" -msgstr "" - -#: ../../library/curses.rst:1745 -msgid "scan line 3" -msgstr "" - -#: ../../library/curses.rst:1747 -msgid "scan line 7" -msgstr "" - -#: ../../library/curses.rst:1749 -msgid "scan line 9" -msgstr "" - -#: ../../library/curses.rst:1751 -msgid "alternate name for lower right corner" -msgstr "" - -#: ../../library/curses.rst:1753 -msgid "alternate name for vertical line" -msgstr "" - -#: ../../library/curses.rst:1755 -msgid "alternate name for right tee" -msgstr "" - -#: ../../library/curses.rst:1757 -msgid "alternate name for lower left corner" -msgstr "" - -#: ../../library/curses.rst:1759 -msgid "alternate name for bottom tee" -msgstr "" - -#: ../../library/curses.rst:1761 -msgid "alternate name for left tee" -msgstr "" - -#: ../../library/curses.rst:1763 -msgid "alternate name for crossover or big plus" -msgstr "" - -#: ../../library/curses.rst:1765 -msgid "pound sterling" -msgstr "" - -#: ../../library/curses.rst:1767 -msgid "top tee" -msgstr "" - -#: ../../library/curses.rst:1769 -msgid "up arrow" -msgstr "" - -#: ../../library/curses.rst:1771 -msgid "upper left corner" -msgstr "" - -#: ../../library/curses.rst:1773 -msgid "upper right corner" -msgstr "" - -#: ../../library/curses.rst:1775 -msgid "vertical line" -msgstr "" - -#: ../../library/curses.rst:1778 -msgid "" -"The following table lists mouse button constants used by :meth:`getmouse`:" -msgstr "" - -#: ../../library/curses.rst:1781 -msgid "Mouse button constant" -msgstr "" - -#: ../../library/curses.rst:1783 -msgid "Mouse button *n* pressed" -msgstr "" - -#: ../../library/curses.rst:1785 -msgid "Mouse button *n* released" -msgstr "" - -#: ../../library/curses.rst:1787 -msgid "Mouse button *n* clicked" -msgstr "" - -#: ../../library/curses.rst:1789 -msgid "Mouse button *n* double clicked" -msgstr "" - -#: ../../library/curses.rst:1791 -msgid "Mouse button *n* triple clicked" -msgstr "" - -#: ../../library/curses.rst:1793 -msgid "Shift was down during button state change" -msgstr "" - -#: ../../library/curses.rst:1795 ../../library/curses.rst:1797 -msgid "Control was down during button state change" -msgstr "" - -#: ../../library/curses.rst:1804 -msgid "The following table lists the predefined colors:" -msgstr "" - -#: ../../library/curses.rst:1807 -msgid "Color" -msgstr "顏色" - -#: ../../library/curses.rst:1809 -msgid "Black" -msgstr "黑" - -#: ../../library/curses.rst:1811 -msgid "Blue" -msgstr "藍" - -#: ../../library/curses.rst:1813 -msgid "Cyan (light greenish blue)" -msgstr "" - -#: ../../library/curses.rst:1815 -msgid "Green" -msgstr "綠" - -#: ../../library/curses.rst:1817 -msgid "Magenta (purplish red)" -msgstr "" - -#: ../../library/curses.rst:1819 -msgid "Red" -msgstr "紅" - -#: ../../library/curses.rst:1821 -msgid "White" -msgstr "白" - -#: ../../library/curses.rst:1823 -msgid "Yellow" -msgstr "" - -#: ../../library/curses.rst:1828 -msgid ":mod:`curses.textpad` --- Text input widget for curses programs" -msgstr "" - -#: ../../library/curses.rst:1836 -msgid "" -"The :mod:`curses.textpad` module provides a :class:`Textbox` class that " -"handles elementary text editing in a curses window, supporting a set of " -"keybindings resembling those of Emacs (thus, also of Netscape Navigator, " -"BBedit 6.x, FrameMaker, and many other programs). The module also provides " -"a rectangle-drawing function useful for framing text boxes or for other " -"purposes." -msgstr "" - -#: ../../library/curses.rst:1842 -msgid "The module :mod:`curses.textpad` defines the following function:" -msgstr ":mod:`curses.textpad` 模組定義了以下函式：" - -#: ../../library/curses.rst:1847 -msgid "" -"Draw a rectangle. The first argument must be a window object; the remaining " -"arguments are coordinates relative to that window. The second and third " -"arguments are the y and x coordinates of the upper left hand corner of the " -"rectangle to be drawn; the fourth and fifth arguments are the y and x " -"coordinates of the lower right hand corner. The rectangle will be drawn " -"using VT100/IBM PC forms characters on terminals that make this possible " -"(including xterm and most other software terminal emulators). Otherwise it " -"will be drawn with ASCII dashes, vertical bars, and plus signs." -msgstr "" - -#: ../../library/curses.rst:1860 -msgid "Textbox objects" -msgstr "" - -#: ../../library/curses.rst:1862 -msgid "You can instantiate a :class:`Textbox` object as follows:" -msgstr "" - -#: ../../library/curses.rst:1867 -msgid "" -"Return a textbox widget object. The *win* argument should be a curses :ref:" -"`window ` object in which the textbox is to be " -"contained. The edit cursor of the textbox is initially located at the upper " -"left hand corner of the containing window, with coordinates ``(0, 0)``. The " -"instance's :attr:`stripspaces` flag is initially on." -msgstr "" - -#: ../../library/curses.rst:1873 -msgid ":class:`Textbox` objects have the following methods:" -msgstr "" - -#: ../../library/curses.rst:1878 -msgid "" -"This is the entry point you will normally use. It accepts editing " -"keystrokes until one of the termination keystrokes is entered. If " -"*validator* is supplied, it must be a function. It will be called for each " -"keystroke entered with the keystroke as a parameter; command dispatch is " -"done on the result. This method returns the window contents as a string; " -"whether blanks in the window are included is affected by the :attr:" -"`stripspaces` attribute." -msgstr "" - -#: ../../library/curses.rst:1889 -msgid "" -"Process a single command keystroke. Here are the supported special " -"keystrokes:" -msgstr "" - -#: ../../library/curses.rst:1893 ../../library/curses.rst:1931 -msgid "Keystroke" -msgstr "" - -#: ../../library/curses.rst:1893 -msgid "Action" -msgstr "" - -#: ../../library/curses.rst:1895 -msgid ":kbd:`Control-A`" -msgstr ":kbd:`Control-A`" - -#: ../../library/curses.rst:1895 -msgid "Go to left edge of window." -msgstr "" - -#: ../../library/curses.rst:1897 ../../library/curses.rst:1933 -msgid ":kbd:`Control-B`" -msgstr ":kbd:`Control-B`" - -#: ../../library/curses.rst:1897 -msgid "Cursor left, wrapping to previous line if appropriate." -msgstr "" - -#: ../../library/curses.rst:1900 -msgid ":kbd:`Control-D`" -msgstr ":kbd:`Control-D`" - -#: ../../library/curses.rst:1900 -msgid "Delete character under cursor." -msgstr "" - -#: ../../library/curses.rst:1902 -msgid ":kbd:`Control-E`" -msgstr ":kbd:`Control-E`" - -#: ../../library/curses.rst:1902 -msgid "Go to right edge (stripspaces off) or end of line (stripspaces on)." -msgstr "" - -#: ../../library/curses.rst:1905 ../../library/curses.rst:1935 -msgid ":kbd:`Control-F`" -msgstr ":kbd:`Control-F`" - -#: ../../library/curses.rst:1905 -msgid "Cursor right, wrapping to next line when appropriate." -msgstr "" - -#: ../../library/curses.rst:1908 -msgid ":kbd:`Control-G`" -msgstr ":kbd:`Control-G`" - -#: ../../library/curses.rst:1908 -msgid "Terminate, returning the window contents." -msgstr "" - -#: ../../library/curses.rst:1910 -msgid ":kbd:`Control-H`" -msgstr ":kbd:`Control-H`" - -#: ../../library/curses.rst:1910 -msgid "Delete character backward." -msgstr "" - -#: ../../library/curses.rst:1912 -msgid ":kbd:`Control-J`" -msgstr ":kbd:`Control-J`" - -#: ../../library/curses.rst:1912 -msgid "Terminate if the window is 1 line, otherwise insert newline." -msgstr "" - -#: ../../library/curses.rst:1915 -msgid ":kbd:`Control-K`" -msgstr ":kbd:`Control-K`" - -#: ../../library/curses.rst:1915 -msgid "If line is blank, delete it, otherwise clear to end of line." -msgstr "" - -#: ../../library/curses.rst:1918 -msgid ":kbd:`Control-L`" -msgstr ":kbd:`Control-L`" - -#: ../../library/curses.rst:1918 -msgid "Refresh screen." -msgstr "" - -#: ../../library/curses.rst:1920 ../../library/curses.rst:1939 -msgid ":kbd:`Control-N`" -msgstr ":kbd:`Control-N`" - -#: ../../library/curses.rst:1920 -msgid "Cursor down; move down one line." -msgstr "" - -#: ../../library/curses.rst:1922 -msgid ":kbd:`Control-O`" -msgstr ":kbd:`Control-O`" - -#: ../../library/curses.rst:1922 -msgid "Insert a blank line at cursor location." -msgstr "" - -#: ../../library/curses.rst:1924 ../../library/curses.rst:1937 -msgid ":kbd:`Control-P`" -msgstr ":kbd:`Control-P`" - -#: ../../library/curses.rst:1924 -msgid "Cursor up; move up one line." -msgstr "" - -#: ../../library/curses.rst:1927 -msgid "" -"Move operations do nothing if the cursor is at an edge where the movement is " -"not possible. The following synonyms are supported where possible:" -msgstr "" - -#: ../../library/curses.rst:1933 -msgid ":const:`~curses.KEY_LEFT`" -msgstr ":const:`~curses.KEY_LEFT`" - -#: ../../library/curses.rst:1935 -msgid ":const:`~curses.KEY_RIGHT`" -msgstr ":const:`~curses.KEY_RIGHT`" - -#: ../../library/curses.rst:1937 -msgid ":const:`~curses.KEY_UP`" -msgstr ":const:`~curses.KEY_UP`" - -#: ../../library/curses.rst:1939 -msgid ":const:`~curses.KEY_DOWN`" -msgstr ":const:`~curses.KEY_DOWN`" - -#: ../../library/curses.rst:1941 -msgid ":const:`~curses.KEY_BACKSPACE`" -msgstr ":const:`~curses.KEY_BACKSPACE`" - -#: ../../library/curses.rst:1941 -msgid ":kbd:`Control-h`" -msgstr ":kbd:`Control-h`" - -#: ../../library/curses.rst:1944 -msgid "" -"All other keystrokes are treated as a command to insert the given character " -"and move right (with line wrapping)." -msgstr "" - -#: ../../library/curses.rst:1950 -msgid "" -"Return the window contents as a string; whether blanks in the window are " -"included is affected by the :attr:`stripspaces` member." -msgstr "" - -#: ../../library/curses.rst:1956 -msgid "" -"This attribute is a flag which controls the interpretation of blanks in the " -"window. When it is on, trailing blanks on each line are ignored; any cursor " -"motion that would land the cursor on a trailing blank goes to the end of " -"that line instead, and trailing blanks are stripped when the window contents " -"are gathered." -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-10 16:45+0000\n" +"PO-Revision-Date: 2018-05-23 14:42+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/curses.rst:2 +msgid ":mod:`!curses` --- Terminal handling for character-cell displays" +msgstr ":mod:`!curses` --- 字元儲存格顯示的終端處理" + +#: ../../library/curses.rst:12 +msgid "**Source code:** :source:`Lib/curses`" +msgstr "**原始碼：**\\ :source:`Lib/curses`" + +#: ../../library/curses.rst:16 +msgid "" +"The :mod:`curses` module provides an interface to the curses library, the de-" +"facto standard for portable advanced terminal handling." +msgstr "" + +#: ../../library/curses.rst:19 +msgid "" +"While curses is most widely used in the Unix environment, versions are " +"available for Windows, DOS, and possibly other systems as well. This " +"extension module is designed to match the API of ncurses, an open-source " +"curses library hosted on Linux and the BSD variants of Unix." +msgstr "" + +#: ../../includes/wasm-mobile-notavail.rst:3 +msgid "Availability" +msgstr "可用性" + +#: ../../includes/wasm-mobile-notavail.rst:5 +msgid "" +"This module is not supported on :ref:`mobile platforms ` or :ref:`WebAssembly platforms `." +msgstr "" +"此模組在\\ :ref:`行動平台 `\\ 或 :ref:`WebAssembly 平" +"台 `\\ 上不支援。" + +#: ../../includes/optional-module.rst:1 +msgid "" +"This is an :term:`optional module`. If it is missing from your copy of " +"CPython, look for documentation from your distributor (that is, whoever " +"provided Python to you). If you are the distributor, see :ref:`optional-" +"module-requirements`." +msgstr "" + +#: ../../library/curses.rst:30 +msgid "" +"Whenever the documentation mentions a *character* it can be specified as an " +"integer, a one-character Unicode string or a one-byte byte string." +msgstr "" + +#: ../../library/curses.rst:33 +msgid "" +"Whenever the documentation mentions a *character string* it can be specified " +"as a Unicode string or a byte string." +msgstr "" + +#: ../../library/curses.rst:38 +msgid "Module :mod:`curses.ascii`" +msgstr ":mod:`curses.ascii` 模組" + +#: ../../library/curses.rst:39 +msgid "" +"Utilities for working with ASCII characters, regardless of your locale " +"settings." +msgstr "" + +#: ../../library/curses.rst:41 +msgid "Module :mod:`curses.panel`" +msgstr ":mod:`curses.panel` 模組" + +#: ../../library/curses.rst:42 +msgid "A panel stack extension that adds depth to curses windows." +msgstr "" + +#: ../../library/curses.rst:44 +msgid "Module :mod:`curses.textpad`" +msgstr ":mod:`curses.textpad` 模組" + +#: ../../library/curses.rst:45 +msgid "" +"Editable text widget for curses supporting :program:`Emacs`\\ -like " +"bindings." +msgstr "" + +#: ../../library/curses.rst:47 +msgid ":ref:`curses-howto`" +msgstr ":ref:`curses-howto`" + +#: ../../library/curses.rst:48 +msgid "" +"Tutorial material on using curses with Python, by Andrew Kuchling and Eric " +"Raymond." +msgstr "" + +#: ../../library/curses.rst:55 +msgid "Functions" +msgstr "函式" + +#: ../../library/curses.rst:57 +msgid "The module :mod:`curses` defines the following exception:" +msgstr ":mod:`curses` 模組定義了以下例外：" + +#: ../../library/curses.rst:62 +msgid "Exception raised when a curses library function returns an error." +msgstr "" + +#: ../../library/curses.rst:66 +msgid "" +"Whenever *x* or *y* arguments to a function or a method are optional, they " +"default to the current cursor location. Whenever *attr* is optional, it " +"defaults to :const:`A_NORMAL`." +msgstr "" + +#: ../../library/curses.rst:70 +msgid "The module :mod:`curses` defines the following functions:" +msgstr ":mod:`curses` 模組定義了以下函式：" + +#: ../../library/curses.rst:75 +msgid "" +"Allow use of default values for colors on terminals supporting this feature. " +"Use this to support transparency in your application." +msgstr "" + +#: ../../library/curses.rst:78 +msgid "" +"Assign terminal default foreground/background colors to color number ``-1``. " +"So ``init_pair(x, COLOR_RED, -1)`` will initialize pair *x* as red on " +"default background and ``init_pair(x, -1, COLOR_BLUE)`` will initialize pair " +"*x* as default foreground on blue." +msgstr "" + +#: ../../library/curses.rst:83 +msgid "Change the definition of the color-pair ``0`` to ``(fg, bg)``." +msgstr "" + +#: ../../library/curses.rst:90 +msgid "" +"Return the output speed of the terminal in bits per second. On software " +"terminal emulators it will have a fixed high value. Included for historical " +"reasons; in former times, it was used to write output loops for time delays " +"and occasionally to change interfaces depending on the line speed." +msgstr "" + +#: ../../library/curses.rst:98 +msgid "Emit a short attention sound." +msgstr "" + +#: ../../library/curses.rst:103 +msgid "" +"Return ``True`` or ``False``, depending on whether the programmer can change " +"the colors displayed by the terminal." +msgstr "" + +#: ../../library/curses.rst:109 +msgid "" +"Enter cbreak mode. In cbreak mode (sometimes called \"rare\" mode) normal " +"tty line buffering is turned off and characters are available to be read one " +"by one. However, unlike raw mode, special characters (interrupt, quit, " +"suspend, and flow control) retain their effects on the tty driver and " +"calling program. Calling first :func:`raw` then :func:`cbreak` leaves the " +"terminal in cbreak mode." +msgstr "" + +#: ../../library/curses.rst:118 +msgid "" +"Return the intensity of the red, green, and blue (RGB) components in the " +"color *color_number*, which must be between ``0`` and ``COLORS - 1``. " +"Return a 3-tuple, containing the R,G,B values for the given color, which " +"will be between ``0`` (no component) and ``1000`` (maximum amount of " +"component)." +msgstr "" + +#: ../../library/curses.rst:126 +msgid "" +"Return the attribute value for displaying text in the specified color pair. " +"Only the first 256 color pairs are supported. This attribute value can be " +"combined with :const:`A_STANDOUT`, :const:`A_REVERSE`, and the other :const:" +"`!A_\\*` attributes. :func:`pair_number` is the counterpart to this " +"function." +msgstr "" + +#: ../../library/curses.rst:135 +msgid "" +"Set the cursor state. *visibility* can be set to ``0``, ``1``, or ``2``, " +"for invisible, normal, or very visible. If the terminal supports the " +"visibility requested, return the previous cursor state; otherwise raise an " +"exception. On many terminals, the \"visible\" mode is an underline cursor " +"and the \"very visible\" mode is a block cursor." +msgstr "" + +#: ../../library/curses.rst:144 +msgid "" +"Save the current terminal mode as the \"program\" mode, the mode when the " +"running program is using curses. (Its counterpart is the \"shell\" mode, " +"for when the program is not in curses.) Subsequent calls to :func:" +"`reset_prog_mode` will restore this mode." +msgstr "" + +#: ../../library/curses.rst:152 +msgid "" +"Save the current terminal mode as the \"shell\" mode, the mode when the " +"running program is not using curses. (Its counterpart is the \"program\" " +"mode, when the program is using curses capabilities.) Subsequent calls to :" +"func:`reset_shell_mode` will restore this mode." +msgstr "" + +#: ../../library/curses.rst:160 +msgid "Insert an *ms* millisecond pause in output." +msgstr "" + +#: ../../library/curses.rst:165 +msgid "" +"Update the physical screen. The curses library keeps two data structures, " +"one representing the current physical screen contents and a virtual screen " +"representing the desired next state. The :func:`doupdate` ground updates " +"the physical screen to match the virtual screen." +msgstr "" + +#: ../../library/curses.rst:170 +msgid "" +"The virtual screen may be updated by a :meth:`~window.noutrefresh` call " +"after write operations such as :meth:`~window.addstr` have been performed on " +"a window. The normal :meth:`~window.refresh` call is simply :meth:`!" +"noutrefresh` followed by :func:`!doupdate`; if you have to update multiple " +"windows, you can speed performance and perhaps reduce screen flicker by " +"issuing :meth:`!noutrefresh` calls on all windows, followed by a single :" +"func:`!doupdate`." +msgstr "" + +#: ../../library/curses.rst:180 +msgid "" +"Enter echo mode. In echo mode, each character input is echoed to the screen " +"as it is entered." +msgstr "" + +#: ../../library/curses.rst:186 +msgid "De-initialize the library, and return terminal to normal status." +msgstr "" + +#: ../../library/curses.rst:191 +msgid "" +"Return the user's current erase character as a one-byte bytes object. Under " +"Unix operating systems this is a property of the controlling tty of the " +"curses program, and is not set by the curses library itself." +msgstr "" + +#: ../../library/curses.rst:198 +msgid "" +"The :func:`.filter` routine, if used, must be called before :func:`initscr` " +"is called. The effect is that, during those calls, :envvar:`LINES` is set " +"to ``1``; the capabilities ``clear``, ``cup``, ``cud``, ``cud1``, ``cuu1``, " +"``cuu``, ``vpa`` are disabled; and the ``home`` string is set to the value " +"of ``cr``. The effect is that the cursor is confined to the current line, " +"and so are screen updates. This may be used for enabling character-at-a-" +"time line editing without touching the rest of the screen." +msgstr "" + +#: ../../library/curses.rst:208 +msgid "" +"Flash the screen. That is, change it to reverse-video and then change it " +"back in a short interval. Some people prefer such as 'visible bell' to the " +"audible attention signal produced by :func:`beep`." +msgstr "" + +#: ../../library/curses.rst:215 +msgid "" +"Flush all input buffers. This throws away any typeahead that has been " +"typed by the user and has not yet been processed by the program." +msgstr "" + +#: ../../library/curses.rst:221 +msgid "" +"After :meth:`~window.getch` returns :const:`KEY_MOUSE` to signal a mouse " +"event, this method should be called to retrieve the queued mouse event, " +"represented as a 5-tuple ``(id, x, y, z, bstate)``. *id* is an ID value used " +"to distinguish multiple devices, and *x*, *y*, *z* are the event's " +"coordinates. (*z* is currently unused.) *bstate* is an integer value whose " +"bits will be set to indicate the type of event, and will be the bitwise OR " +"of one or more of the following constants, where *n* is the button number " +"from 1 to 5: :const:`BUTTONn_PRESSED`, :const:`BUTTONn_RELEASED`, :const:" +"`BUTTONn_CLICKED`, :const:`BUTTONn_DOUBLE_CLICKED`, :const:" +"`BUTTONn_TRIPLE_CLICKED`, :const:`BUTTON_SHIFT`, :const:`BUTTON_CTRL`, :" +"const:`BUTTON_ALT`." +msgstr "" + +#: ../../library/curses.rst:232 ../../library/curses.rst:1800 +msgid "" +"The ``BUTTON5_*`` constants are now exposed if they are provided by the " +"underlying curses library." +msgstr "" + +#: ../../library/curses.rst:239 +msgid "" +"Return the current coordinates of the virtual screen cursor as a tuple ``(y, " +"x)``. If :meth:`leaveok ` is currently ``True``, then " +"return ``(-1, -1)``." +msgstr "" + +#: ../../library/curses.rst:245 +msgid "" +"Read window related data stored in the file by an earlier :func:`window." +"putwin` call. The routine then creates and initializes a new window using " +"that data, returning the new window object." +msgstr "" + +#: ../../library/curses.rst:252 +msgid "" +"Return ``True`` if the terminal can display colors; otherwise, return " +"``False``." +msgstr "" + +#: ../../library/curses.rst:256 +msgid "" +"Return ``True`` if the module supports extended colors; otherwise, return " +"``False``. Extended color support allows more than 256 color pairs for " +"terminals that support more than 16 colors (e.g. xterm-256color)." +msgstr "" + +#: ../../library/curses.rst:260 +msgid "Extended color support requires ncurses version 6.1 or later." +msgstr "" + +#: ../../library/curses.rst:266 +msgid "" +"Return ``True`` if the terminal has insert- and delete-character " +"capabilities. This function is included for historical reasons only, as all " +"modern software terminal emulators have such capabilities." +msgstr "" + +#: ../../library/curses.rst:273 +msgid "" +"Return ``True`` if the terminal has insert- and delete-line capabilities, or " +"can simulate them using scrolling regions. This function is included for " +"historical reasons only, as all modern software terminal emulators have such " +"capabilities." +msgstr "" + +#: ../../library/curses.rst:281 +msgid "" +"Take a key value *ch*, and return ``True`` if the current terminal type " +"recognizes a key with that value." +msgstr "" + +#: ../../library/curses.rst:287 +msgid "" +"Used for half-delay mode, which is similar to cbreak mode in that characters " +"typed by the user are immediately available to the program. However, after " +"blocking for *tenths* tenths of seconds, raise an exception if nothing has " +"been typed. The value of *tenths* must be a number between ``1`` and " +"``255``. Use :func:`nocbreak` to leave half-delay mode." +msgstr "" + +#: ../../library/curses.rst:296 +msgid "" +"Change the definition of a color, taking the number of the color to be " +"changed followed by three RGB values (for the amounts of red, green, and " +"blue components). The value of *color_number* must be between ``0`` and " +"``COLORS - 1``. Each of *r*, *g*, *b*, must be a value between ``0`` and " +"``1000``. When :func:`init_color` is used, all occurrences of that color on " +"the screen immediately change to the new definition. This function is a no-" +"op on most terminals; it is active only if :func:`can_change_color` returns " +"``True``." +msgstr "" + +#: ../../library/curses.rst:307 +msgid "" +"Change the definition of a color-pair. It takes three arguments: the number " +"of the color-pair to be changed, the foreground color number, and the " +"background color number. The value of *pair_number* must be between ``1`` " +"and ``COLOR_PAIRS - 1`` (the ``0`` color pair can only be changed by :func:" +"`use_default_colors` and :func:`assume_default_colors`). The value of *fg* " +"and *bg* arguments must be between ``0`` and ``COLORS - 1``, or, after " +"calling :func:`!use_default_colors` or :func:`!assume_default_colors`, " +"``-1``. If the color-pair was previously initialized, the screen is " +"refreshed and all occurrences of that color-pair are changed to the new " +"definition." +msgstr "" + +#: ../../library/curses.rst:322 +msgid "" +"Initialize the library. Return a :ref:`window ` " +"object which represents the whole screen." +msgstr "" + +#: ../../library/curses.rst:327 +msgid "" +"If there is an error opening the terminal, the underlying curses library may " +"cause the interpreter to exit." +msgstr "" + +#: ../../library/curses.rst:333 +msgid "" +"Return ``True`` if :func:`resize_term` would modify the window structure, " +"``False`` otherwise." +msgstr "" + +#: ../../library/curses.rst:339 +msgid "" +"Return ``True`` if :func:`endwin` has been called (that is, the curses " +"library has been deinitialized)." +msgstr "" + +#: ../../library/curses.rst:345 +msgid "" +"Return the name of the key numbered *k* as a bytes object. The name of a " +"key generating printable ASCII character is the key's character. The name " +"of a control-key combination is a two-byte bytes object consisting of a " +"caret (``b'^'``) followed by the corresponding printable ASCII character. " +"The name of an alt-key combination (128--255) is a bytes object consisting " +"of the prefix ``b'M-'`` followed by the name of the corresponding ASCII " +"character." +msgstr "" + +#: ../../library/curses.rst:355 +msgid "" +"Return the user's current line kill character as a one-byte bytes object. " +"Under Unix operating systems this is a property of the controlling tty of " +"the curses program, and is not set by the curses library itself." +msgstr "" + +#: ../../library/curses.rst:362 +msgid "" +"Return a bytes object containing the terminfo long name field describing the " +"current terminal. The maximum length of a verbose description is 128 " +"characters. It is defined only after the call to :func:`initscr`." +msgstr "" + +#: ../../library/curses.rst:369 +msgid "" +"If *flag* is ``True``, allow 8-bit characters to be input. If *flag* is " +"``False``, allow only 7-bit chars." +msgstr "" + +#: ../../library/curses.rst:375 +msgid "" +"Set the maximum time in milliseconds that can elapse between press and " +"release events in order for them to be recognized as a click, and return the " +"previous interval value. The default value is 200 milliseconds, or one " +"fifth of a second." +msgstr "" + +#: ../../library/curses.rst:382 +msgid "" +"Set the mouse events to be reported, and return a tuple ``(availmask, " +"oldmask)``. *availmask* indicates which of the specified mouse events can " +"be reported; on complete failure it returns ``0``. *oldmask* is the " +"previous value of the given window's mouse event mask. If this function is " +"never called, no mouse events are ever reported." +msgstr "" + +#: ../../library/curses.rst:391 +msgid "Sleep for *ms* milliseconds." +msgstr "" + +#: ../../library/curses.rst:396 +msgid "" +"Create and return a pointer to a new pad data structure with the given " +"number of lines and columns. Return a pad as a window object." +msgstr "" + +#: ../../library/curses.rst:399 +msgid "" +"A pad is like a window, except that it is not restricted by the screen size, " +"and is not necessarily associated with a particular part of the screen. " +"Pads can be used when a large window is needed, and only a part of the " +"window will be on the screen at one time. Automatic refreshes of pads (such " +"as from scrolling or echoing of input) do not occur. The :meth:`~window." +"refresh` and :meth:`~window.noutrefresh` methods of a pad require 6 " +"arguments to specify the part of the pad to be displayed and the location on " +"the screen to be used for the display. The arguments are *pminrow*, " +"*pmincol*, *sminrow*, *smincol*, *smaxrow*, *smaxcol*; the *p* arguments " +"refer to the upper left corner of the pad region to be displayed and the *s* " +"arguments define a clipping box on the screen within which the pad region is " +"to be displayed." +msgstr "" + +#: ../../library/curses.rst:415 +msgid "" +"Return a new :ref:`window `, whose left-upper corner " +"is at ``(begin_y, begin_x)``, and whose height/width is *nlines*/*ncols*." +msgstr "" + +#: ../../library/curses.rst:418 +msgid "" +"By default, the window will extend from the specified position to the lower " +"right corner of the screen." +msgstr "" + +#: ../../library/curses.rst:424 +msgid "" +"Enter newline mode. This mode translates the return key into newline on " +"input, and translates newline into return and line-feed on output. Newline " +"mode is initially on." +msgstr "" + +#: ../../library/curses.rst:431 +msgid "" +"Leave cbreak mode. Return to normal \"cooked\" mode with line buffering." +msgstr "" + +#: ../../library/curses.rst:436 +msgid "Leave echo mode. Echoing of input characters is turned off." +msgstr "" + +#: ../../library/curses.rst:441 +msgid "" +"Leave newline mode. Disable translation of return into newline on input, " +"and disable low-level translation of newline into newline/return on output " +"(but this does not change the behavior of ``addch('\\n')``, which always " +"does the equivalent of return and line feed on the virtual screen). With " +"translation off, curses can sometimes speed up vertical motion a little; " +"also, it will be able to detect the return key on input." +msgstr "" + +#: ../../library/curses.rst:451 +msgid "" +"When the :func:`!noqiflush` routine is used, normal flush of input and " +"output queues associated with the ``INTR``, ``QUIT`` and ``SUSP`` characters " +"will not be done. You may want to call :func:`!noqiflush` in a signal " +"handler if you want output to continue as though the interrupt had not " +"occurred, after the handler exits." +msgstr "" + +#: ../../library/curses.rst:459 +msgid "Leave raw mode. Return to normal \"cooked\" mode with line buffering." +msgstr "" + +#: ../../library/curses.rst:464 +msgid "" +"Return a tuple ``(fg, bg)`` containing the colors for the requested color " +"pair. The value of *pair_number* must be between ``0`` and ``COLOR_PAIRS - " +"1``." +msgstr "" + +#: ../../library/curses.rst:470 +msgid "" +"Return the number of the color-pair set by the attribute value *attr*. :func:" +"`color_pair` is the counterpart to this function." +msgstr "" + +#: ../../library/curses.rst:476 +msgid "" +"Equivalent to ``tputs(str, 1, putchar)``; emit the value of a specified " +"terminfo capability for the current terminal. Note that the output of :func:" +"`putp` always goes to standard output." +msgstr "" + +#: ../../library/curses.rst:483 +msgid "" +"If *flag* is ``False``, the effect is the same as calling :func:`noqiflush`. " +"If *flag* is ``True``, or no argument is provided, the queues will be " +"flushed when these control characters are read." +msgstr "" + +#: ../../library/curses.rst:490 +msgid "" +"Enter raw mode. In raw mode, normal line buffering and processing of " +"interrupt, quit, suspend, and flow control keys are turned off; characters " +"are presented to curses input functions one by one." +msgstr "" + +#: ../../library/curses.rst:497 +msgid "" +"Restore the terminal to \"program\" mode, as previously saved by :func:" +"`def_prog_mode`." +msgstr "" + +#: ../../library/curses.rst:503 +msgid "" +"Restore the terminal to \"shell\" mode, as previously saved by :func:" +"`def_shell_mode`." +msgstr "" + +#: ../../library/curses.rst:509 +msgid "" +"Restore the state of the terminal modes to what it was at the last call to :" +"func:`savetty`." +msgstr "" + +#: ../../library/curses.rst:515 +msgid "" +"Backend function used by :func:`resizeterm`, performing most of the work; " +"when resizing the windows, :func:`resize_term` blank-fills the areas that " +"are extended. The calling application should fill in these areas with " +"appropriate data. The :func:`!resize_term` function attempts to resize all " +"windows. However, due to the calling convention of pads, it is not possible " +"to resize these without additional interaction with the application." +msgstr "" + +#: ../../library/curses.rst:525 +msgid "" +"Resize the standard and current windows to the specified dimensions, and " +"adjusts other bookkeeping data used by the curses library that record the " +"window dimensions (in particular the SIGWINCH handler)." +msgstr "" + +#: ../../library/curses.rst:532 +msgid "" +"Save the current state of the terminal modes in a buffer, usable by :func:" +"`resetty`." +msgstr "" + +#: ../../library/curses.rst:537 +msgid "Retrieves the value set by :func:`set_escdelay`." +msgstr "" + +#: ../../library/curses.rst:543 +msgid "" +"Sets the number of milliseconds to wait after reading an escape character, " +"to distinguish between an individual escape character entered on the " +"keyboard from escape sequences sent by cursor and function keys." +msgstr "" + +#: ../../library/curses.rst:551 +msgid "Retrieves the value set by :func:`set_tabsize`." +msgstr "" + +#: ../../library/curses.rst:557 +msgid "" +"Sets the number of columns used by the curses library when converting a tab " +"character to spaces as it adds the tab to a window." +msgstr "" + +#: ../../library/curses.rst:564 +msgid "" +"Set the virtual screen cursor to *y*, *x*. If *y* and *x* are both ``-1``, " +"then :meth:`leaveok ` is set ``True``." +msgstr "" + +#: ../../library/curses.rst:570 +msgid "" +"Initialize the terminal. *term* is a string giving the terminal name, or " +"``None``; if omitted or ``None``, the value of the :envvar:`TERM` " +"environment variable will be used. *fd* is the file descriptor to which any " +"initialization sequences will be sent; if not supplied or ``-1``, the file " +"descriptor for ``sys.stdout`` will be used." +msgstr "" + +#: ../../library/curses.rst:579 +msgid "" +"Must be called if the programmer wants to use colors, and before any other " +"color manipulation routine is called. It is good practice to call this " +"routine right after :func:`initscr`." +msgstr "" + +#: ../../library/curses.rst:583 +msgid "" +":func:`start_color` initializes eight basic colors (black, red, green, " +"yellow, blue, magenta, cyan, and white), and two global variables in the :" +"mod:`curses` module, :const:`COLORS` and :const:`COLOR_PAIRS`, containing " +"the maximum number of colors and color-pairs the terminal can support. It " +"also restores the colors on the terminal to the values they had when the " +"terminal was just turned on." +msgstr "" + +#: ../../library/curses.rst:592 +msgid "" +"Return a logical OR of all video attributes supported by the terminal. This " +"information is useful when a curses program needs complete control over the " +"appearance of the screen." +msgstr "" + +#: ../../library/curses.rst:599 +msgid "" +"Return the value of the environment variable :envvar:`TERM`, as a bytes " +"object, truncated to 14 characters." +msgstr "" + +#: ../../library/curses.rst:605 +msgid "" +"Return the value of the Boolean capability corresponding to the terminfo " +"capability name *capname* as an integer. Return the value ``-1`` if " +"*capname* is not a Boolean capability, or ``0`` if it is canceled or absent " +"from the terminal description." +msgstr "" + +#: ../../library/curses.rst:613 +msgid "" +"Return the value of the numeric capability corresponding to the terminfo " +"capability name *capname* as an integer. Return the value ``-2`` if " +"*capname* is not a numeric capability, or ``-1`` if it is canceled or absent " +"from the terminal description." +msgstr "" + +#: ../../library/curses.rst:621 +msgid "" +"Return the value of the string capability corresponding to the terminfo " +"capability name *capname* as a bytes object. Return ``None`` if *capname* " +"is not a terminfo \"string capability\", or is canceled or absent from the " +"terminal description." +msgstr "" + +#: ../../library/curses.rst:629 +msgid "" +"Instantiate the bytes object *str* with the supplied parameters, where *str* " +"should be a parameterized string obtained from the terminfo database. E.g. " +"``tparm(tigetstr(\"cup\"), 5, 3)`` could result in ``b'\\033[6;4H'``, the " +"exact result depending on terminal type." +msgstr "" + +#: ../../library/curses.rst:637 +msgid "" +"Specify that the file descriptor *fd* be used for typeahead checking. If " +"*fd* is ``-1``, then no typeahead checking is done." +msgstr "" + +#: ../../library/curses.rst:640 +msgid "" +"The curses library does \"line-breakout optimization\" by looking for " +"typeahead periodically while updating the screen. If input is found, and it " +"is coming from a tty, the current update is postponed until refresh or " +"doupdate is called again, allowing faster response to commands typed in " +"advance. This function allows specifying a different file descriptor for " +"typeahead checking." +msgstr "" + +#: ../../library/curses.rst:649 +msgid "" +"Return a bytes object which is a printable representation of the character " +"*ch*. Control characters are represented as a caret followed by the " +"character, for example as ``b'^C'``. Printing characters are left as they " +"are." +msgstr "" + +#: ../../library/curses.rst:656 +msgid "Push *ch* so the next :meth:`~window.getch` will return it." +msgstr "" + +#: ../../library/curses.rst:660 +msgid "Only one *ch* can be pushed before :meth:`!getch` is called." +msgstr "" + +#: ../../library/curses.rst:665 +msgid "" +"Update the :const:`LINES` and :const:`COLS` module variables. Useful for " +"detecting manual screen resize." +msgstr "" + +#: ../../library/curses.rst:673 +msgid "Push *ch* so the next :meth:`~window.get_wch` will return it." +msgstr "" + +#: ../../library/curses.rst:677 +msgid "Only one *ch* can be pushed before :meth:`!get_wch` is called." +msgstr "" + +#: ../../library/curses.rst:684 +msgid "" +"Push a :const:`KEY_MOUSE` event onto the input queue, associating the given " +"state data with it." +msgstr "" + +#: ../../library/curses.rst:690 +msgid "" +"If used, this function should be called before :func:`initscr` or newterm " +"are called. When *flag* is ``False``, the values of lines and columns " +"specified in the terminfo database will be used, even if environment " +"variables :envvar:`LINES` and :envvar:`COLUMNS` (used by default) are set, " +"or if curses is running in a window (in which case default behavior would be " +"to use the window size if :envvar:`LINES` and :envvar:`COLUMNS` are not set)." +msgstr "" + +#: ../../library/curses.rst:700 +msgid "Equivalent to ``assume_default_colors(-1, -1)``." +msgstr "" + +#: ../../library/curses.rst:705 +msgid "" +"Initialize curses and call another callable object, *func*, which should be " +"the rest of your curses-using application. If the application raises an " +"exception, this function will restore the terminal to a sane state before re-" +"raising the exception and generating a traceback. The callable object " +"*func* is then passed the main window 'stdscr' as its first argument, " +"followed by any other arguments passed to :func:`!wrapper`. Before calling " +"*func*, :func:`!wrapper` turns on cbreak mode, turns off echo, enables the " +"terminal keypad, and initializes colors if the terminal has color support. " +"On exit (whether normally or by exception) it restores cooked mode, turns on " +"echo, and disables the terminal keypad." +msgstr "" + +#: ../../library/curses.rst:719 +msgid "Window Objects" +msgstr "" + +#: ../../library/curses.rst:723 +msgid "" +"Window objects, as returned by :func:`initscr` and :func:`newwin` above, " +"have the following methods and attributes:" +msgstr "" + +#: ../../library/curses.rst:730 +msgid "" +"Paint character *ch* at ``(y, x)`` with attributes *attr*, overwriting any " +"character previously painted at that location. By default, the character " +"position and attributes are the current settings for the window object." +msgstr "" + +#: ../../library/curses.rst:736 +msgid "" +"Writing outside the window, subwindow, or pad raises a :exc:`curses.error`. " +"Attempting to write to the lower right corner of a window, subwindow, or pad " +"will cause an exception to be raised after the character is printed." +msgstr "" + +#: ../../library/curses.rst:744 +msgid "" +"Paint at most *n* characters of the character string *str* at ``(y, x)`` " +"with attributes *attr*, overwriting anything previously on the display." +msgstr "" + +#: ../../library/curses.rst:752 +msgid "" +"Paint the character string *str* at ``(y, x)`` with attributes *attr*, " +"overwriting anything previously on the display." +msgstr "" + +#: ../../library/curses.rst:757 +msgid "" +"Writing outside the window, subwindow, or pad raises :exc:`curses.error`. " +"Attempting to write to the lower right corner of a window, subwindow, or pad " +"will cause an exception to be raised after the string is printed." +msgstr "" + +#: ../../library/curses.rst:761 +msgid "" +"A `bug in ncurses `_, the backend for " +"this Python module, can cause SegFaults when resizing windows. This is fixed " +"in ncurses-6.1-20190511. If you are stuck with an earlier ncurses, you can " +"avoid triggering this if you do not call :func:`addstr` with a *str* that " +"has embedded newlines. Instead, call :func:`addstr` separately for each " +"line." +msgstr "" + +#: ../../library/curses.rst:771 +msgid "" +"Remove attribute *attr* from the \"background\" set applied to all writes to " +"the current window." +msgstr "" + +#: ../../library/curses.rst:777 +msgid "" +"Add attribute *attr* to the \"background\" set applied to all writes to the " +"current window." +msgstr "" + +#: ../../library/curses.rst:783 +msgid "" +"Set the \"background\" set of attributes to *attr*. This set is initially " +"``0`` (no attributes)." +msgstr "" + +#: ../../library/curses.rst:789 +msgid "" +"Set the background property of the window to the character *ch*, with " +"attributes *attr*. The change is then applied to every character position " +"in that window:" +msgstr "" + +#: ../../library/curses.rst:793 +msgid "" +"The attribute of every character in the window is changed to the new " +"background attribute." +msgstr "" + +#: ../../library/curses.rst:796 +msgid "" +"Wherever the former background character appears, it is changed to the new " +"background character." +msgstr "" + +#: ../../library/curses.rst:802 +msgid "" +"Set the window's background. A window's background consists of a character " +"and any combination of attributes. The attribute part of the background is " +"combined (OR'ed) with all non-blank characters that are written into the " +"window. Both the character and attribute parts of the background are " +"combined with the blank characters. The background becomes a property of " +"the character and moves with the character through any scrolling and insert/" +"delete line/character operations." +msgstr "" + +#: ../../library/curses.rst:812 +msgid "" +"Draw a border around the edges of the window. Each parameter specifies the " +"character to use for a specific part of the border; see the table below for " +"more details." +msgstr "" + +#: ../../library/curses.rst:818 +msgid "" +"A ``0`` value for any parameter will cause the default character to be used " +"for that parameter. Keyword parameters can *not* be used. The defaults are " +"listed in this table:" +msgstr "" + +#: ../../library/curses.rst:823 +msgid "Parameter" +msgstr "參數" + +#: ../../library/curses.rst:823 +msgid "Description" +msgstr "描述" + +#: ../../library/curses.rst:823 +msgid "Default value" +msgstr "預設值" + +#: ../../library/curses.rst:825 +msgid "*ls*" +msgstr "*ls*" + +#: ../../library/curses.rst:825 +msgid "Left side" +msgstr "" + +#: ../../library/curses.rst:825 ../../library/curses.rst:827 +msgid ":const:`ACS_VLINE`" +msgstr ":const:`ACS_VLINE`" + +#: ../../library/curses.rst:827 +msgid "*rs*" +msgstr "*rs*" + +#: ../../library/curses.rst:827 +msgid "Right side" +msgstr "" + +#: ../../library/curses.rst:829 +msgid "*ts*" +msgstr "*ts*" + +#: ../../library/curses.rst:829 +msgid "Top" +msgstr "" + +#: ../../library/curses.rst:829 ../../library/curses.rst:831 +msgid ":const:`ACS_HLINE`" +msgstr ":const:`ACS_HLINE`" + +#: ../../library/curses.rst:831 +msgid "*bs*" +msgstr "*bs*" + +#: ../../library/curses.rst:831 +msgid "Bottom" +msgstr "" + +#: ../../library/curses.rst:833 +msgid "*tl*" +msgstr "*tl*" + +#: ../../library/curses.rst:833 +msgid "Upper-left corner" +msgstr "" + +#: ../../library/curses.rst:833 +msgid ":const:`ACS_ULCORNER`" +msgstr ":const:`ACS_ULCORNER`" + +#: ../../library/curses.rst:835 +msgid "*tr*" +msgstr "*tr*" + +#: ../../library/curses.rst:835 +msgid "Upper-right corner" +msgstr "" + +#: ../../library/curses.rst:835 +msgid ":const:`ACS_URCORNER`" +msgstr ":const:`ACS_URCORNER`" + +#: ../../library/curses.rst:837 +msgid "*bl*" +msgstr "*bl*" + +#: ../../library/curses.rst:837 +msgid "Bottom-left corner" +msgstr "" + +#: ../../library/curses.rst:837 +msgid ":const:`ACS_LLCORNER`" +msgstr ":const:`ACS_LLCORNER`" + +#: ../../library/curses.rst:839 +msgid "*br*" +msgstr "*br*" + +#: ../../library/curses.rst:839 +msgid "Bottom-right corner" +msgstr "" + +#: ../../library/curses.rst:839 +msgid ":const:`ACS_LRCORNER`" +msgstr ":const:`ACS_LRCORNER`" + +#: ../../library/curses.rst:845 +msgid "" +"Similar to :meth:`border`, but both *ls* and *rs* are *vertch* and both *ts* " +"and *bs* are *horch*. The default corner characters are always used by this " +"function." +msgstr "" + +#: ../../library/curses.rst:854 +msgid "" +"Set the attributes of *num* characters at the current cursor position, or at " +"position ``(y, x)`` if supplied. If *num* is not given or is ``-1``, the " +"attribute will be set on all the characters to the end of the line. This " +"function moves cursor to position ``(y, x)`` if supplied. The changed line " +"will be touched using the :meth:`touchline` method so that the contents will " +"be redisplayed by the next window refresh." +msgstr "" + +#: ../../library/curses.rst:864 +msgid "" +"Like :meth:`erase`, but also cause the whole window to be repainted upon " +"next call to :meth:`refresh`." +msgstr "" + +#: ../../library/curses.rst:870 +msgid "" +"If *flag* is ``True``, the next call to :meth:`refresh` will clear the " +"window completely." +msgstr "" + +#: ../../library/curses.rst:876 +msgid "" +"Erase from cursor to the end of the window: all lines below the cursor are " +"deleted, and then the equivalent of :meth:`clrtoeol` is performed." +msgstr "" + +#: ../../library/curses.rst:882 +msgid "Erase from cursor to the end of the line." +msgstr "" + +#: ../../library/curses.rst:887 +msgid "" +"Update the current cursor position of all the ancestors of the window to " +"reflect the current cursor position of the window." +msgstr "" + +#: ../../library/curses.rst:893 +msgid "Delete any character at ``(y, x)``." +msgstr "" + +#: ../../library/curses.rst:898 +msgid "" +"Delete the line under the cursor. All following lines are moved up by one " +"line." +msgstr "" + +#: ../../library/curses.rst:904 +msgid "" +"An abbreviation for \"derive window\", :meth:`derwin` is the same as " +"calling :meth:`subwin`, except that *begin_y* and *begin_x* are relative to " +"the origin of the window, rather than relative to the entire screen. Return " +"a window object for the derived window." +msgstr "" + +#: ../../library/curses.rst:912 +msgid "" +"Add character *ch* with attribute *attr*, and immediately call :meth:" +"`refresh` on the window." +msgstr "" + +#: ../../library/curses.rst:918 +msgid "" +"Test whether the given pair of screen-relative character-cell coordinates " +"are enclosed by the given window, returning ``True`` or ``False``. It is " +"useful for determining what subset of the screen windows enclose the " +"location of a mouse event." +msgstr "" + +#: ../../library/curses.rst:923 +msgid "Previously it returned ``1`` or ``0`` instead of ``True`` or ``False``." +msgstr "" + +#: ../../library/curses.rst:929 +msgid "" +"Encoding used to encode method arguments (Unicode strings and characters). " +"The encoding attribute is inherited from the parent window when a subwindow " +"is created, for example with :meth:`window.subwin`. By default, current " +"locale encoding is used (see :func:`locale.getencoding`)." +msgstr "" + +#: ../../library/curses.rst:939 +msgid "Clear the window." +msgstr "清除視窗。" + +#: ../../library/curses.rst:944 +msgid "Return a tuple ``(y, x)`` of coordinates of upper-left corner." +msgstr "回傳左上角的座標 ``(y, x)``。" + +#: ../../library/curses.rst:949 +msgid "Return the given window's current background character/attribute pair." +msgstr "回傳給定視窗目前的背景字元/屬性對。" + +#: ../../library/curses.rst:954 +msgid "" +"Get a character. Note that the integer returned does *not* have to be in " +"ASCII range: function keys, keypad keys and so on are represented by numbers " +"higher than 255. In no-delay mode, return ``-1`` if there is no input, " +"otherwise wait until a key is pressed." +msgstr "" + +#: ../../library/curses.rst:962 +msgid "" +"Get a wide character. Return a character for most keys, or an integer for " +"function keys, keypad keys, and other special keys. In no-delay mode, raise " +"an exception if there is no input." +msgstr "" + +#: ../../library/curses.rst:971 +msgid "" +"Get a character, returning a string instead of an integer, as :meth:`getch` " +"does. Function keys, keypad keys and other special keys return a multibyte " +"string containing the key name. In no-delay mode, raise an exception if " +"there is no input." +msgstr "" + +#: ../../library/curses.rst:979 +msgid "Return a tuple ``(y, x)`` of the height and width of the window." +msgstr "回傳視窗的高度和寬度的元組 ``(y, x)``。" + +#: ../../library/curses.rst:984 +msgid "" +"Return the beginning coordinates of this window relative to its parent " +"window as a tuple ``(y, x)``. Return ``(-1, -1)`` if this window has no " +"parent." +msgstr "" + +#: ../../library/curses.rst:994 +msgid "" +"Read a bytes object from the user, with primitive line editing capacity. The " +"maximum value for *n* is 2047." +msgstr "" + +#: ../../library/curses.rst:997 ../../library/curses.rst:1092 +msgid "The maximum value for *n* was increased from 1023 to 2047." +msgstr "" + +#: ../../library/curses.rst:1003 +msgid "" +"Return a tuple ``(y, x)`` of current cursor position relative to the " +"window's upper-left corner." +msgstr "" + +#: ../../library/curses.rst:1010 +msgid "" +"Display a horizontal line starting at ``(y, x)`` with length *n* consisting " +"of the character *ch*." +msgstr "" + +#: ../../library/curses.rst:1016 +msgid "" +"If *flag* is ``False``, curses no longer considers using the hardware insert/" +"delete character feature of the terminal; if *flag* is ``True``, use of " +"character insertion and deletion is enabled. When curses is first " +"initialized, use of character insert/delete is enabled by default." +msgstr "" + +#: ../../library/curses.rst:1024 +msgid "" +"If *flag* is ``True``, :mod:`curses` will try and use hardware line editing " +"facilities. Otherwise, line insertion/deletion are disabled." +msgstr "" + +#: ../../library/curses.rst:1030 +msgid "" +"If *flag* is ``True``, any change in the window image automatically causes " +"the window to be refreshed; you no longer have to call :meth:`refresh` " +"yourself. However, it may degrade performance considerably, due to repeated " +"calls to wrefresh. This option is disabled by default." +msgstr "" + +#: ../../library/curses.rst:1038 +msgid "" +"Return the character at the given position in the window. The bottom 8 bits " +"are the character proper, and upper bits are the attributes." +msgstr "" + +#: ../../library/curses.rst:1045 +msgid "" +"Paint character *ch* at ``(y, x)`` with attributes *attr*, moving the line " +"from position *x* right by one character." +msgstr "" + +#: ../../library/curses.rst:1051 +msgid "" +"Insert *nlines* lines into the specified window above the current line. The " +"*nlines* bottom lines are lost. For negative *nlines*, delete *nlines* " +"lines starting with the one under the cursor, and move the remaining lines " +"up. The bottom *nlines* lines are cleared. The current cursor position " +"remains the same." +msgstr "" + +#: ../../library/curses.rst:1060 +msgid "" +"Insert a blank line under the cursor. All following lines are moved down by " +"one line." +msgstr "" + +#: ../../library/curses.rst:1067 +msgid "" +"Insert a character string (as many characters as will fit on the line) " +"before the character under the cursor, up to *n* characters. If *n* is " +"zero or negative, the entire string is inserted. All characters to the right " +"of the cursor are shifted right, with the rightmost characters on the line " +"being lost. The cursor position does not change (after moving to *y*, *x*, " +"if specified)." +msgstr "" + +#: ../../library/curses.rst:1077 +msgid "" +"Insert a character string (as many characters as will fit on the line) " +"before the character under the cursor. All characters to the right of the " +"cursor are shifted right, with the rightmost characters on the line being " +"lost. The cursor position does not change (after moving to *y*, *x*, if " +"specified)." +msgstr "" + +#: ../../library/curses.rst:1086 +msgid "" +"Return a bytes object of characters, extracted from the window starting at " +"the current cursor position, or at *y*, *x* if specified. Attributes are " +"stripped from the characters. If *n* is specified, :meth:`instr` returns a " +"string at most *n* characters long (exclusive of the trailing NUL). The " +"maximum value for *n* is 2047." +msgstr "" + +#: ../../library/curses.rst:1098 +msgid "" +"Return ``True`` if the specified line was modified since the last call to :" +"meth:`refresh`; otherwise return ``False``. Raise a :exc:`curses.error` " +"exception if *line* is not valid for the given window." +msgstr "" + +#: ../../library/curses.rst:1105 +msgid "" +"Return ``True`` if the specified window was modified since the last call to :" +"meth:`refresh`; otherwise return ``False``." +msgstr "" + +#: ../../library/curses.rst:1111 +msgid "" +"If *flag* is ``True``, escape sequences generated by some keys (keypad, " +"function keys) will be interpreted by :mod:`curses`. If *flag* is ``False``, " +"escape sequences will be left as is in the input stream." +msgstr "" + +#: ../../library/curses.rst:1118 +msgid "" +"If *flag* is ``True``, cursor is left where it is on update, instead of " +"being at \"cursor position.\" This reduces cursor movement where possible. " +"If possible the cursor will be made invisible." +msgstr "" + +#: ../../library/curses.rst:1122 +msgid "" +"If *flag* is ``False``, cursor will always be at \"cursor position\" after " +"an update." +msgstr "" + +#: ../../library/curses.rst:1127 +msgid "Move cursor to ``(new_y, new_x)``." +msgstr "移動游標到 ``(new_y, new_x)``。" + +#: ../../library/curses.rst:1132 +msgid "" +"Move the window inside its parent window. The screen-relative parameters of " +"the window are not changed. This routine is used to display different parts " +"of the parent window at the same physical position on the screen." +msgstr "" + +#: ../../library/curses.rst:1139 +msgid "Move the window so its upper-left corner is at ``(new_y, new_x)``." +msgstr "" + +#: ../../library/curses.rst:1144 +msgid "If *flag* is ``True``, :meth:`getch` will be non-blocking." +msgstr "如果 *flag* 為 ``True``，則 :meth:`getch` 將為非阻塞的。" + +#: ../../library/curses.rst:1149 +msgid "If *flag* is ``True``, escape sequences will not be timed out." +msgstr "" + +#: ../../library/curses.rst:1151 +msgid "" +"If *flag* is ``False``, after a few milliseconds, an escape sequence will " +"not be interpreted, and will be left in the input stream as is." +msgstr "" + +#: ../../library/curses.rst:1157 +msgid "" +"Mark for refresh but wait. This function updates the data structure " +"representing the desired state of the window, but does not force an update " +"of the physical screen. To accomplish that, call :func:`doupdate`." +msgstr "" + +#: ../../library/curses.rst:1164 +msgid "" +"Overlay the window on top of *destwin*. The windows need not be the same " +"size, only the overlapping region is copied. This copy is non-destructive, " +"which means that the current background character does not overwrite the old " +"contents of *destwin*." +msgstr "" + +#: ../../library/curses.rst:1169 +msgid "" +"To get fine-grained control over the copied region, the second form of :meth:" +"`overlay` can be used. *sminrow* and *smincol* are the upper-left " +"coordinates of the source window, and the other variables mark a rectangle " +"in the destination window." +msgstr "" + +#: ../../library/curses.rst:1177 +msgid "" +"Overwrite the window on top of *destwin*. The windows need not be the same " +"size, in which case only the overlapping region is copied. This copy is " +"destructive, which means that the current background character overwrites " +"the old contents of *destwin*." +msgstr "" + +#: ../../library/curses.rst:1182 +msgid "" +"To get fine-grained control over the copied region, the second form of :meth:" +"`overwrite` can be used. *sminrow* and *smincol* are the upper-left " +"coordinates of the source window, the other variables mark a rectangle in " +"the destination window." +msgstr "" + +#: ../../library/curses.rst:1190 +msgid "" +"Write all data associated with the window into the provided file object. " +"This information can be later retrieved using the :func:`getwin` function." +msgstr "" + +#: ../../library/curses.rst:1196 +msgid "" +"Indicate that the *num* screen lines, starting at line *beg*, are corrupted " +"and should be completely redrawn on the next :meth:`refresh` call." +msgstr "" + +#: ../../library/curses.rst:1202 +msgid "" +"Touch the entire window, causing it to be completely redrawn on the next :" +"meth:`refresh` call." +msgstr "" + +#: ../../library/curses.rst:1208 +msgid "" +"Update the display immediately (sync actual screen with previous drawing/" +"deleting methods)." +msgstr "" + +#: ../../library/curses.rst:1211 +msgid "" +"The 6 optional arguments can only be specified when the window is a pad " +"created with :func:`newpad`. The additional parameters are needed to " +"indicate what part of the pad and screen are involved. *pminrow* and " +"*pmincol* specify the upper left-hand corner of the rectangle to be " +"displayed in the pad. *sminrow*, *smincol*, *smaxrow*, and *smaxcol* " +"specify the edges of the rectangle to be displayed on the screen. The lower " +"right-hand corner of the rectangle to be displayed in the pad is calculated " +"from the screen coordinates, since the rectangles must be the same size. " +"Both rectangles must be entirely contained within their respective " +"structures. Negative values of *pminrow*, *pmincol*, *sminrow*, or " +"*smincol* are treated as if they were zero." +msgstr "" + +#: ../../library/curses.rst:1225 +msgid "" +"Reallocate storage for a curses window to adjust its dimensions to the " +"specified values. If either dimension is larger than the current values, " +"the window's data is filled with blanks that have the current background " +"rendition (as set by :meth:`bkgdset`) merged into them." +msgstr "" + +#: ../../library/curses.rst:1233 +msgid "Scroll the screen or scrolling region upward by *lines* lines." +msgstr "" + +#: ../../library/curses.rst:1238 +msgid "" +"Control what happens when the cursor of a window is moved off the edge of " +"the window or scrolling region, either as a result of a newline action on " +"the bottom line, or typing the last character of the last line. If *flag* " +"is ``False``, the cursor is left on the bottom line. If *flag* is ``True``, " +"the window is scrolled up one line. Note that in order to get the physical " +"scrolling effect on the terminal, it is also necessary to call :meth:`idlok`." +msgstr "" + +#: ../../library/curses.rst:1248 +msgid "" +"Set the scrolling region from line *top* to line *bottom*. All scrolling " +"actions will take place in this region." +msgstr "" + +#: ../../library/curses.rst:1254 +msgid "" +"Turn off the standout attribute. On some terminals this has the side effect " +"of turning off all attributes." +msgstr "" + +#: ../../library/curses.rst:1260 +msgid "Turn on attribute *A_STANDOUT*." +msgstr "" + +#: ../../library/curses.rst:1266 ../../library/curses.rst:1273 +msgid "" +"Return a sub-window, whose upper-left corner is at ``(begin_y, begin_x)``, " +"and whose width/height is *ncols*/*nlines*." +msgstr "" + +#: ../../library/curses.rst:1276 +msgid "" +"By default, the sub-window will extend from the specified position to the " +"lower right corner of the window." +msgstr "" + +#: ../../library/curses.rst:1282 +msgid "" +"Touch each location in the window that has been touched in any of its " +"ancestor windows. This routine is called by :meth:`refresh`, so it should " +"almost never be necessary to call it manually." +msgstr "" + +#: ../../library/curses.rst:1289 +msgid "" +"If *flag* is ``True``, then :meth:`syncup` is called automatically whenever " +"there is a change in the window." +msgstr "" + +#: ../../library/curses.rst:1295 +msgid "" +"Touch all locations in ancestors of the window that have been changed in " +"the window." +msgstr "" + +#: ../../library/curses.rst:1301 +msgid "" +"Set blocking or non-blocking read behavior for the window. If *delay* is " +"negative, blocking read is used (which will wait indefinitely for input). " +"If *delay* is zero, then non-blocking read is used, and :meth:`getch` will " +"return ``-1`` if no input is waiting. If *delay* is positive, then :meth:" +"`getch` will block for *delay* milliseconds, and return ``-1`` if there is " +"still no input at the end of that time." +msgstr "" + +#: ../../library/curses.rst:1311 +msgid "" +"Pretend *count* lines have been changed, starting with line *start*. If " +"*changed* is supplied, it specifies whether the affected lines are marked as " +"having been changed (*changed*\\ ``=True``) or unchanged (*changed*\\ " +"``=False``)." +msgstr "" + +#: ../../library/curses.rst:1318 +msgid "" +"Pretend the whole window has been changed, for purposes of drawing " +"optimizations." +msgstr "" + +#: ../../library/curses.rst:1324 +msgid "" +"Mark all lines in the window as unchanged since the last call to :meth:" +"`refresh`." +msgstr "" + +#: ../../library/curses.rst:1331 +msgid "" +"Display a vertical line starting at ``(y, x)`` with length *n* consisting of " +"the character *ch* with attributes *attr*." +msgstr "" + +#: ../../library/curses.rst:1336 +msgid "Constants" +msgstr "" + +#: ../../library/curses.rst:1338 +msgid "The :mod:`curses` module defines the following data members:" +msgstr ":mod:`curses` 模組定義了以下資料成員：" + +#: ../../library/curses.rst:1343 +msgid "" +"Some curses routines that return an integer, such as :meth:`~window." +"getch`, return :const:`ERR` upon failure." +msgstr "" + +#: ../../library/curses.rst:1349 +msgid "" +"Some curses routines that return an integer, such as :func:`napms`, " +"return :const:`OK` upon success." +msgstr "" + +#: ../../library/curses.rst:1355 +msgid "A bytes object representing the current version of the module." +msgstr "" + +#: ../../library/curses.rst:1360 +msgid "" +"A named tuple containing the three components of the ncurses library " +"version: *major*, *minor*, and *patch*. All values are integers. The " +"components can also be accessed by name, so ``curses.ncurses_version[0]`` " +"is equivalent to ``curses.ncurses_version.major`` and so on." +msgstr "" + +#: ../../library/curses.rst:1365 +msgid "Availability: if the ncurses library is used." +msgstr "" + +#: ../../library/curses.rst:1371 +msgid "" +"The maximum number of colors the terminal can support. It is defined only " +"after the call to :func:`start_color`." +msgstr "" + +#: ../../library/curses.rst:1376 +msgid "" +"The maximum number of color pairs the terminal can support. It is defined " +"only after the call to :func:`start_color`." +msgstr "" + +#: ../../library/curses.rst:1381 +msgid "" +"The width of the screen, i.e., the number of columns. It is defined only " +"after the call to :func:`initscr`. Updated by :func:`update_lines_cols`, :" +"func:`resizeterm` and :func:`resize_term`." +msgstr "" + +#: ../../library/curses.rst:1388 +msgid "" +"The height of the screen, i.e., the number of lines. It is defined only " +"after the call to :func:`initscr`. Updated by :func:`update_lines_cols`, :" +"func:`resizeterm` and :func:`resize_term`." +msgstr "" + +#: ../../library/curses.rst:1394 +msgid "" +"Some constants are available to specify character cell attributes. The exact " +"constants available are system dependent." +msgstr "" + +#: ../../library/curses.rst:1398 +msgid "Attribute" +msgstr "" + +#: ../../library/curses.rst:1398 ../../library/curses.rst:1443 +#: ../../library/curses.rst:1689 ../../library/curses.rst:1781 +msgid "Meaning" +msgstr "含義" + +#: ../../library/curses.rst:1400 +msgid "Alternate character set mode" +msgstr "" + +#: ../../library/curses.rst:1402 +msgid "Blink mode" +msgstr "" + +#: ../../library/curses.rst:1404 +msgid "Bold mode" +msgstr "" + +#: ../../library/curses.rst:1406 +msgid "Dim mode" +msgstr "" + +#: ../../library/curses.rst:1408 +msgid "Invisible or blank mode" +msgstr "" + +#: ../../library/curses.rst:1410 +msgid "Italic mode" +msgstr "" + +#: ../../library/curses.rst:1412 +msgid "Normal attribute" +msgstr "" + +#: ../../library/curses.rst:1414 +msgid "Protected mode" +msgstr "" + +#: ../../library/curses.rst:1416 +msgid "Reverse background and foreground colors" +msgstr "" + +#: ../../library/curses.rst:1419 +msgid "Standout mode" +msgstr "" + +#: ../../library/curses.rst:1421 +msgid "Underline mode" +msgstr "" + +#: ../../library/curses.rst:1423 +msgid "Horizontal highlight" +msgstr "" + +#: ../../library/curses.rst:1425 +msgid "Left highlight" +msgstr "" + +#: ../../library/curses.rst:1427 +msgid "Low highlight" +msgstr "" + +#: ../../library/curses.rst:1429 +msgid "Right highlight" +msgstr "" + +#: ../../library/curses.rst:1431 +msgid "Top highlight" +msgstr "" + +#: ../../library/curses.rst:1433 +msgid "Vertical highlight" +msgstr "" + +#: ../../library/curses.rst:1436 +msgid "``A_ITALIC`` was added." +msgstr "新增 ``A_ITALIC``。" + +#: ../../library/curses.rst:1439 +msgid "" +"Several constants are available to extract corresponding attributes returned " +"by some methods." +msgstr "" + +#: ../../library/curses.rst:1443 +msgid "Bit-mask" +msgstr "" + +#: ../../library/curses.rst:1445 +msgid "Bit-mask to extract attributes" +msgstr "" + +#: ../../library/curses.rst:1448 +msgid "Bit-mask to extract a character" +msgstr "" + +#: ../../library/curses.rst:1451 +msgid "Bit-mask to extract color-pair field information" +msgstr "" + +#: ../../library/curses.rst:1455 +msgid "" +"Keys are referred to by integer constants with names starting with " +"``KEY_``. The exact keycaps available are system dependent." +msgstr "" + +#: ../../library/curses.rst:1461 +msgid "Key constant" +msgstr "" + +#: ../../library/curses.rst:1461 +msgid "Key" +msgstr "" + +#: ../../library/curses.rst:1463 +msgid "Minimum key value" +msgstr "" + +#: ../../library/curses.rst:1465 +msgid "Break key (unreliable)" +msgstr "" + +#: ../../library/curses.rst:1467 +msgid "Down-arrow" +msgstr "" + +#: ../../library/curses.rst:1469 +msgid "Up-arrow" +msgstr "" + +#: ../../library/curses.rst:1471 +msgid "Left-arrow" +msgstr "" + +#: ../../library/curses.rst:1473 +msgid "Right-arrow" +msgstr "" + +#: ../../library/curses.rst:1475 +msgid "Home key (upward+left arrow)" +msgstr "" + +#: ../../library/curses.rst:1477 +msgid "Backspace (unreliable)" +msgstr "" + +#: ../../library/curses.rst:1479 +msgid "Function keys. Up to 64 function keys are supported." +msgstr "" + +#: ../../library/curses.rst:1482 +msgid "Value of function key *n*" +msgstr "" + +#: ../../library/curses.rst:1484 +msgid "Delete line" +msgstr "" + +#: ../../library/curses.rst:1486 +msgid "Insert line" +msgstr "" + +#: ../../library/curses.rst:1488 +msgid "Delete character" +msgstr "" + +#: ../../library/curses.rst:1490 +msgid "Insert char or enter insert mode" +msgstr "" + +#: ../../library/curses.rst:1492 +msgid "Exit insert char mode" +msgstr "" + +#: ../../library/curses.rst:1494 +msgid "Clear screen" +msgstr "" + +#: ../../library/curses.rst:1496 +msgid "Clear to end of screen" +msgstr "" + +#: ../../library/curses.rst:1498 +msgid "Clear to end of line" +msgstr "" + +#: ../../library/curses.rst:1500 +msgid "Scroll 1 line forward" +msgstr "" + +#: ../../library/curses.rst:1502 +msgid "Scroll 1 line backward (reverse)" +msgstr "" + +#: ../../library/curses.rst:1504 +msgid "Next page" +msgstr "" + +#: ../../library/curses.rst:1506 +msgid "Previous page" +msgstr "" + +#: ../../library/curses.rst:1508 +msgid "Set tab" +msgstr "" + +#: ../../library/curses.rst:1510 +msgid "Clear tab" +msgstr "" + +#: ../../library/curses.rst:1512 +msgid "Clear all tabs" +msgstr "" + +#: ../../library/curses.rst:1514 +msgid "Enter or send (unreliable)" +msgstr "" + +#: ../../library/curses.rst:1516 +msgid "Soft (partial) reset (unreliable)" +msgstr "" + +#: ../../library/curses.rst:1518 +msgid "Reset or hard reset (unreliable)" +msgstr "" + +#: ../../library/curses.rst:1520 +msgid "Print" +msgstr "" + +#: ../../library/curses.rst:1522 +msgid "Home down or bottom (lower left)" +msgstr "" + +#: ../../library/curses.rst:1524 +msgid "Upper left of keypad" +msgstr "" + +#: ../../library/curses.rst:1526 +msgid "Upper right of keypad" +msgstr "" + +#: ../../library/curses.rst:1528 +msgid "Center of keypad" +msgstr "" + +#: ../../library/curses.rst:1530 +msgid "Lower left of keypad" +msgstr "" + +#: ../../library/curses.rst:1532 +msgid "Lower right of keypad" +msgstr "" + +#: ../../library/curses.rst:1534 +msgid "Back tab" +msgstr "" + +#: ../../library/curses.rst:1536 +msgid "Beg (beginning)" +msgstr "" + +#: ../../library/curses.rst:1538 +msgid "Cancel" +msgstr "" + +#: ../../library/curses.rst:1540 +msgid "Close" +msgstr "" + +#: ../../library/curses.rst:1542 +msgid "Cmd (command)" +msgstr "" + +#: ../../library/curses.rst:1544 +msgid "Copy" +msgstr "" + +#: ../../library/curses.rst:1546 +msgid "Create" +msgstr "" + +#: ../../library/curses.rst:1548 +msgid "End" +msgstr "" + +#: ../../library/curses.rst:1550 +msgid "Exit" +msgstr "" + +#: ../../library/curses.rst:1552 +msgid "Find" +msgstr "" + +#: ../../library/curses.rst:1554 +msgid "Help" +msgstr "" + +#: ../../library/curses.rst:1556 +msgid "Mark" +msgstr "" + +#: ../../library/curses.rst:1558 +msgid "Message" +msgstr "" + +#: ../../library/curses.rst:1560 +msgid "Move" +msgstr "" + +#: ../../library/curses.rst:1562 +msgid "Next" +msgstr "" + +#: ../../library/curses.rst:1564 +msgid "Open" +msgstr "" + +#: ../../library/curses.rst:1566 +msgid "Options" +msgstr "" + +#: ../../library/curses.rst:1568 +msgid "Prev (previous)" +msgstr "" + +#: ../../library/curses.rst:1570 +msgid "Redo" +msgstr "" + +#: ../../library/curses.rst:1572 +msgid "Ref (reference)" +msgstr "" + +#: ../../library/curses.rst:1574 +msgid "Refresh" +msgstr "" + +#: ../../library/curses.rst:1576 +msgid "Replace" +msgstr "" + +#: ../../library/curses.rst:1578 +msgid "Restart" +msgstr "" + +#: ../../library/curses.rst:1580 +msgid "Resume" +msgstr "" + +#: ../../library/curses.rst:1582 +msgid "Save" +msgstr "" + +#: ../../library/curses.rst:1584 +msgid "Shifted Beg (beginning)" +msgstr "" + +#: ../../library/curses.rst:1586 +msgid "Shifted Cancel" +msgstr "" + +#: ../../library/curses.rst:1588 +msgid "Shifted Command" +msgstr "" + +#: ../../library/curses.rst:1590 +msgid "Shifted Copy" +msgstr "" + +#: ../../library/curses.rst:1592 +msgid "Shifted Create" +msgstr "" + +#: ../../library/curses.rst:1594 +msgid "Shifted Delete char" +msgstr "" + +#: ../../library/curses.rst:1596 +msgid "Shifted Delete line" +msgstr "" + +#: ../../library/curses.rst:1598 +msgid "Select" +msgstr "" + +#: ../../library/curses.rst:1600 +msgid "Shifted End" +msgstr "" + +#: ../../library/curses.rst:1602 +msgid "Shifted Clear line" +msgstr "" + +#: ../../library/curses.rst:1604 +msgid "Shifted Exit" +msgstr "" + +#: ../../library/curses.rst:1606 +msgid "Shifted Find" +msgstr "" + +#: ../../library/curses.rst:1608 +msgid "Shifted Help" +msgstr "" + +#: ../../library/curses.rst:1610 +msgid "Shifted Home" +msgstr "" + +#: ../../library/curses.rst:1612 +msgid "Shifted Input" +msgstr "" + +#: ../../library/curses.rst:1614 +msgid "Shifted Left arrow" +msgstr "" + +#: ../../library/curses.rst:1616 +msgid "Shifted Message" +msgstr "" + +#: ../../library/curses.rst:1618 +msgid "Shifted Move" +msgstr "" + +#: ../../library/curses.rst:1620 +msgid "Shifted Next" +msgstr "" + +#: ../../library/curses.rst:1622 +msgid "Shifted Options" +msgstr "" + +#: ../../library/curses.rst:1624 +msgid "Shifted Prev" +msgstr "" + +#: ../../library/curses.rst:1626 +msgid "Shifted Print" +msgstr "" + +#: ../../library/curses.rst:1628 +msgid "Shifted Redo" +msgstr "" + +#: ../../library/curses.rst:1630 +msgid "Shifted Replace" +msgstr "" + +#: ../../library/curses.rst:1632 +msgid "Shifted Right arrow" +msgstr "" + +#: ../../library/curses.rst:1634 +msgid "Shifted Resume" +msgstr "" + +#: ../../library/curses.rst:1636 +msgid "Shifted Save" +msgstr "" + +#: ../../library/curses.rst:1638 +msgid "Shifted Suspend" +msgstr "" + +#: ../../library/curses.rst:1640 +msgid "Shifted Undo" +msgstr "" + +#: ../../library/curses.rst:1642 +msgid "Suspend" +msgstr "" + +#: ../../library/curses.rst:1644 +msgid "Undo" +msgstr "" + +#: ../../library/curses.rst:1646 +msgid "Mouse event has occurred" +msgstr "" + +#: ../../library/curses.rst:1648 +msgid "Terminal resize event" +msgstr "" + +#: ../../library/curses.rst:1650 +msgid "Maximum key value" +msgstr "" + +#: ../../library/curses.rst:1653 +msgid "" +"On VT100s and their software emulations, such as X terminal emulators, there " +"are normally at least four function keys (:const:`KEY_F1 `, :const:" +"`KEY_F2 `, :const:`KEY_F3 `, :const:`KEY_F4 `) " +"available, and the arrow keys mapped to :const:`KEY_UP`, :const:`KEY_DOWN`, :" +"const:`KEY_LEFT` and :const:`KEY_RIGHT` in the obvious way. If your machine " +"has a PC keyboard, it is safe to expect arrow keys and twelve function keys " +"(older PC keyboards may have only ten function keys); also, the following " +"keypad mappings are standard:" +msgstr "" + +#: ../../library/curses.rst:1662 +msgid "Keycap" +msgstr "" + +#: ../../library/curses.rst:1662 ../../library/curses.rst:1807 +#: ../../library/curses.rst:1931 +msgid "Constant" +msgstr "" + +#: ../../library/curses.rst:1664 +msgid ":kbd:`Insert`" +msgstr ":kbd:`Insert`" + +#: ../../library/curses.rst:1664 +msgid "KEY_IC" +msgstr "KEY_IC" + +#: ../../library/curses.rst:1666 +msgid ":kbd:`Delete`" +msgstr ":kbd:`Delete`" + +#: ../../library/curses.rst:1666 +msgid "KEY_DC" +msgstr "KEY_DC" + +#: ../../library/curses.rst:1668 +msgid ":kbd:`Home`" +msgstr ":kbd:`Home`" + +#: ../../library/curses.rst:1668 +msgid "KEY_HOME" +msgstr "KEY_HOME" + +#: ../../library/curses.rst:1670 +msgid ":kbd:`End`" +msgstr ":kbd:`End`" + +#: ../../library/curses.rst:1670 +msgid "KEY_END" +msgstr "KEY_END" + +#: ../../library/curses.rst:1672 +msgid ":kbd:`Page Up`" +msgstr ":kbd:`Page Up`" + +#: ../../library/curses.rst:1672 +msgid "KEY_PPAGE" +msgstr "KEY_PPAGE" + +#: ../../library/curses.rst:1674 +msgid ":kbd:`Page Down`" +msgstr ":kbd:`Page Down`" + +#: ../../library/curses.rst:1674 +msgid "KEY_NPAGE" +msgstr "KEY_NPAGE" + +#: ../../library/curses.rst:1679 +msgid "" +"The following table lists characters from the alternate character set. These " +"are inherited from the VT100 terminal, and will generally be available on " +"software emulations such as X terminals. When there is no graphic " +"available, curses falls back on a crude printable ASCII approximation." +msgstr "" + +#: ../../library/curses.rst:1686 +msgid "These are available only after :func:`initscr` has been called." +msgstr "" + +#: ../../library/curses.rst:1689 +msgid "ACS code" +msgstr "" + +#: ../../library/curses.rst:1691 +msgid "alternate name for upper right corner" +msgstr "" + +#: ../../library/curses.rst:1693 +msgid "solid square block" +msgstr "" + +#: ../../library/curses.rst:1695 +msgid "board of squares" +msgstr "" + +#: ../../library/curses.rst:1697 +msgid "alternate name for horizontal line" +msgstr "" + +#: ../../library/curses.rst:1699 +msgid "alternate name for upper left corner" +msgstr "" + +#: ../../library/curses.rst:1701 +msgid "alternate name for top tee" +msgstr "" + +#: ../../library/curses.rst:1703 +msgid "bottom tee" +msgstr "" + +#: ../../library/curses.rst:1705 +msgid "bullet" +msgstr "" + +#: ../../library/curses.rst:1707 +msgid "checker board (stipple)" +msgstr "" + +#: ../../library/curses.rst:1709 +msgid "arrow pointing down" +msgstr "" + +#: ../../library/curses.rst:1711 +msgid "degree symbol" +msgstr "" + +#: ../../library/curses.rst:1713 +msgid "diamond" +msgstr "" + +#: ../../library/curses.rst:1715 +msgid "greater-than-or-equal-to" +msgstr "" + +#: ../../library/curses.rst:1717 +msgid "horizontal line" +msgstr "" + +#: ../../library/curses.rst:1719 +msgid "lantern symbol" +msgstr "" + +#: ../../library/curses.rst:1721 +msgid "left arrow" +msgstr "" + +#: ../../library/curses.rst:1723 +msgid "less-than-or-equal-to" +msgstr "" + +#: ../../library/curses.rst:1725 +msgid "lower left-hand corner" +msgstr "" + +#: ../../library/curses.rst:1727 +msgid "lower right-hand corner" +msgstr "" + +#: ../../library/curses.rst:1729 +msgid "left tee" +msgstr "" + +#: ../../library/curses.rst:1731 +msgid "not-equal sign" +msgstr "" + +#: ../../library/curses.rst:1733 +msgid "letter pi" +msgstr "" + +#: ../../library/curses.rst:1735 +msgid "plus-or-minus sign" +msgstr "" + +#: ../../library/curses.rst:1737 +msgid "big plus sign" +msgstr "" + +#: ../../library/curses.rst:1739 +msgid "right arrow" +msgstr "" + +#: ../../library/curses.rst:1741 +msgid "right tee" +msgstr "" + +#: ../../library/curses.rst:1743 +msgid "scan line 1" +msgstr "" + +#: ../../library/curses.rst:1745 +msgid "scan line 3" +msgstr "" + +#: ../../library/curses.rst:1747 +msgid "scan line 7" +msgstr "" + +#: ../../library/curses.rst:1749 +msgid "scan line 9" +msgstr "" + +#: ../../library/curses.rst:1751 +msgid "alternate name for lower right corner" +msgstr "" + +#: ../../library/curses.rst:1753 +msgid "alternate name for vertical line" +msgstr "" + +#: ../../library/curses.rst:1755 +msgid "alternate name for right tee" +msgstr "" + +#: ../../library/curses.rst:1757 +msgid "alternate name for lower left corner" +msgstr "" + +#: ../../library/curses.rst:1759 +msgid "alternate name for bottom tee" +msgstr "" + +#: ../../library/curses.rst:1761 +msgid "alternate name for left tee" +msgstr "" + +#: ../../library/curses.rst:1763 +msgid "alternate name for crossover or big plus" +msgstr "" + +#: ../../library/curses.rst:1765 +msgid "pound sterling" +msgstr "" + +#: ../../library/curses.rst:1767 +msgid "top tee" +msgstr "" + +#: ../../library/curses.rst:1769 +msgid "up arrow" +msgstr "" + +#: ../../library/curses.rst:1771 +msgid "upper left corner" +msgstr "" + +#: ../../library/curses.rst:1773 +msgid "upper right corner" +msgstr "" + +#: ../../library/curses.rst:1775 +msgid "vertical line" +msgstr "" + +#: ../../library/curses.rst:1778 +msgid "" +"The following table lists mouse button constants used by :meth:`getmouse`:" +msgstr "" + +#: ../../library/curses.rst:1781 +msgid "Mouse button constant" +msgstr "" + +#: ../../library/curses.rst:1783 +msgid "Mouse button *n* pressed" +msgstr "" + +#: ../../library/curses.rst:1785 +msgid "Mouse button *n* released" +msgstr "" + +#: ../../library/curses.rst:1787 +msgid "Mouse button *n* clicked" +msgstr "" + +#: ../../library/curses.rst:1789 +msgid "Mouse button *n* double clicked" +msgstr "" + +#: ../../library/curses.rst:1791 +msgid "Mouse button *n* triple clicked" +msgstr "" + +#: ../../library/curses.rst:1793 +msgid "Shift was down during button state change" +msgstr "" + +#: ../../library/curses.rst:1795 ../../library/curses.rst:1797 +msgid "Control was down during button state change" +msgstr "" + +#: ../../library/curses.rst:1804 +msgid "The following table lists the predefined colors:" +msgstr "" + +#: ../../library/curses.rst:1807 +msgid "Color" +msgstr "顏色" + +#: ../../library/curses.rst:1809 +msgid "Black" +msgstr "黑" + +#: ../../library/curses.rst:1811 +msgid "Blue" +msgstr "藍" + +#: ../../library/curses.rst:1813 +msgid "Cyan (light greenish blue)" +msgstr "" + +#: ../../library/curses.rst:1815 +msgid "Green" +msgstr "綠" + +#: ../../library/curses.rst:1817 +msgid "Magenta (purplish red)" +msgstr "" + +#: ../../library/curses.rst:1819 +msgid "Red" +msgstr "紅" + +#: ../../library/curses.rst:1821 +msgid "White" +msgstr "白" + +#: ../../library/curses.rst:1823 +msgid "Yellow" +msgstr "" + +#: ../../library/curses.rst:1828 +msgid ":mod:`curses.textpad` --- Text input widget for curses programs" +msgstr "" + +#: ../../library/curses.rst:1836 +msgid "" +"The :mod:`curses.textpad` module provides a :class:`Textbox` class that " +"handles elementary text editing in a curses window, supporting a set of " +"keybindings resembling those of Emacs (thus, also of Netscape Navigator, " +"BBedit 6.x, FrameMaker, and many other programs). The module also provides " +"a rectangle-drawing function useful for framing text boxes or for other " +"purposes." +msgstr "" + +#: ../../library/curses.rst:1842 +msgid "The module :mod:`curses.textpad` defines the following function:" +msgstr ":mod:`curses.textpad` 模組定義了以下函式：" + +#: ../../library/curses.rst:1847 +msgid "" +"Draw a rectangle. The first argument must be a window object; the remaining " +"arguments are coordinates relative to that window. The second and third " +"arguments are the y and x coordinates of the upper left hand corner of the " +"rectangle to be drawn; the fourth and fifth arguments are the y and x " +"coordinates of the lower right hand corner. The rectangle will be drawn " +"using VT100/IBM PC forms characters on terminals that make this possible " +"(including xterm and most other software terminal emulators). Otherwise it " +"will be drawn with ASCII dashes, vertical bars, and plus signs." +msgstr "" + +#: ../../library/curses.rst:1860 +msgid "Textbox objects" +msgstr "" + +#: ../../library/curses.rst:1862 +msgid "You can instantiate a :class:`Textbox` object as follows:" +msgstr "" + +#: ../../library/curses.rst:1867 +msgid "" +"Return a textbox widget object. The *win* argument should be a curses :ref:" +"`window ` object in which the textbox is to be " +"contained. The edit cursor of the textbox is initially located at the upper " +"left hand corner of the containing window, with coordinates ``(0, 0)``. The " +"instance's :attr:`stripspaces` flag is initially on." +msgstr "" + +#: ../../library/curses.rst:1873 +msgid ":class:`Textbox` objects have the following methods:" +msgstr "" + +#: ../../library/curses.rst:1878 +msgid "" +"This is the entry point you will normally use. It accepts editing " +"keystrokes until one of the termination keystrokes is entered. If " +"*validator* is supplied, it must be a function. It will be called for each " +"keystroke entered with the keystroke as a parameter; command dispatch is " +"done on the result. This method returns the window contents as a string; " +"whether blanks in the window are included is affected by the :attr:" +"`stripspaces` attribute." +msgstr "" + +#: ../../library/curses.rst:1889 +msgid "" +"Process a single command keystroke. Here are the supported special " +"keystrokes:" +msgstr "" + +#: ../../library/curses.rst:1893 ../../library/curses.rst:1931 +msgid "Keystroke" +msgstr "" + +#: ../../library/curses.rst:1893 +msgid "Action" +msgstr "" + +#: ../../library/curses.rst:1895 +msgid ":kbd:`Control-A`" +msgstr ":kbd:`Control-A`" + +#: ../../library/curses.rst:1895 +msgid "Go to left edge of window." +msgstr "" + +#: ../../library/curses.rst:1897 ../../library/curses.rst:1933 +msgid ":kbd:`Control-B`" +msgstr ":kbd:`Control-B`" + +#: ../../library/curses.rst:1897 +msgid "Cursor left, wrapping to previous line if appropriate." +msgstr "" + +#: ../../library/curses.rst:1900 +msgid ":kbd:`Control-D`" +msgstr ":kbd:`Control-D`" + +#: ../../library/curses.rst:1900 +msgid "Delete character under cursor." +msgstr "" + +#: ../../library/curses.rst:1902 +msgid ":kbd:`Control-E`" +msgstr ":kbd:`Control-E`" + +#: ../../library/curses.rst:1902 +msgid "Go to right edge (stripspaces off) or end of line (stripspaces on)." +msgstr "" + +#: ../../library/curses.rst:1905 ../../library/curses.rst:1935 +msgid ":kbd:`Control-F`" +msgstr ":kbd:`Control-F`" + +#: ../../library/curses.rst:1905 +msgid "Cursor right, wrapping to next line when appropriate." +msgstr "" + +#: ../../library/curses.rst:1908 +msgid ":kbd:`Control-G`" +msgstr ":kbd:`Control-G`" + +#: ../../library/curses.rst:1908 +msgid "Terminate, returning the window contents." +msgstr "" + +#: ../../library/curses.rst:1910 +msgid ":kbd:`Control-H`" +msgstr ":kbd:`Control-H`" + +#: ../../library/curses.rst:1910 +msgid "Delete character backward." +msgstr "" + +#: ../../library/curses.rst:1912 +msgid ":kbd:`Control-J`" +msgstr ":kbd:`Control-J`" + +#: ../../library/curses.rst:1912 +msgid "Terminate if the window is 1 line, otherwise insert newline." +msgstr "" + +#: ../../library/curses.rst:1915 +msgid ":kbd:`Control-K`" +msgstr ":kbd:`Control-K`" + +#: ../../library/curses.rst:1915 +msgid "If line is blank, delete it, otherwise clear to end of line." +msgstr "" + +#: ../../library/curses.rst:1918 +msgid ":kbd:`Control-L`" +msgstr ":kbd:`Control-L`" + +#: ../../library/curses.rst:1918 +msgid "Refresh screen." +msgstr "" + +#: ../../library/curses.rst:1920 ../../library/curses.rst:1939 +msgid ":kbd:`Control-N`" +msgstr ":kbd:`Control-N`" + +#: ../../library/curses.rst:1920 +msgid "Cursor down; move down one line." +msgstr "" + +#: ../../library/curses.rst:1922 +msgid ":kbd:`Control-O`" +msgstr ":kbd:`Control-O`" + +#: ../../library/curses.rst:1922 +msgid "Insert a blank line at cursor location." +msgstr "" + +#: ../../library/curses.rst:1924 ../../library/curses.rst:1937 +msgid ":kbd:`Control-P`" +msgstr ":kbd:`Control-P`" + +#: ../../library/curses.rst:1924 +msgid "Cursor up; move up one line." +msgstr "" + +#: ../../library/curses.rst:1927 +msgid "" +"Move operations do nothing if the cursor is at an edge where the movement is " +"not possible. The following synonyms are supported where possible:" +msgstr "" + +#: ../../library/curses.rst:1933 +msgid ":const:`~curses.KEY_LEFT`" +msgstr ":const:`~curses.KEY_LEFT`" + +#: ../../library/curses.rst:1935 +msgid ":const:`~curses.KEY_RIGHT`" +msgstr ":const:`~curses.KEY_RIGHT`" + +#: ../../library/curses.rst:1937 +msgid ":const:`~curses.KEY_UP`" +msgstr ":const:`~curses.KEY_UP`" + +#: ../../library/curses.rst:1939 +msgid ":const:`~curses.KEY_DOWN`" +msgstr ":const:`~curses.KEY_DOWN`" + +#: ../../library/curses.rst:1941 +msgid ":const:`~curses.KEY_BACKSPACE`" +msgstr ":const:`~curses.KEY_BACKSPACE`" + +#: ../../library/curses.rst:1941 +msgid ":kbd:`Control-h`" +msgstr ":kbd:`Control-h`" + +#: ../../library/curses.rst:1944 +msgid "" +"All other keystrokes are treated as a command to insert the given character " +"and move right (with line wrapping)." +msgstr "" + +#: ../../library/curses.rst:1950 +msgid "" +"Return the window contents as a string; whether blanks in the window are " +"included is affected by the :attr:`stripspaces` member." +msgstr "" + +#: ../../library/curses.rst:1956 +msgid "" +"This attribute is a flag which controls the interpretation of blanks in the " +"window. When it is on, trailing blanks on each line are ignored; any cursor " +"motion that would land the cursor on a trailing blank goes to the end of " +"that line instead, and trailing blanks are stripped when the window contents " +"are gathered." +msgstr "" diff --git a/library/custominterp.po b/library/custominterp.po index 1f661fe658..d2a47255a7 100644 --- a/library/custominterp.po +++ b/library/custominterp.po @@ -1,39 +1,39 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Weilin Du, 2025 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2022-07-06 00:17+0000\n" -"PO-Revision-Date: 2025-06-28 10:57+0800\n" -"Last-Translator: Liang-Bo Wang \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/custominterp.rst:5 -msgid "Custom Python Interpreters" -msgstr "自訂 Python 直譯器" - -#: ../../library/custominterp.rst:7 -msgid "" -"The modules described in this chapter allow writing interfaces similar to " -"Python's interactive interpreter. If you want a Python interpreter that " -"supports some special feature in addition to the Python language, you should " -"look at the :mod:`code` module. (The :mod:`codeop` module is lower-level, " -"used to support compiling a possibly incomplete chunk of Python code.)" -msgstr "" -"本章介紹的模組可用於編寫類似於 Python 交互式直譯器的介面。如果你需要一個在 " -"Python 語言基礎上支援某些特殊功能的直譯器，可以參考 :mod:`code` 模組。（" -" :mod:`codeop` 模組屬於底層工具，用於支援編譯可能不完整的 Python 程式碼。）" - -#: ../../library/custominterp.rst:13 -msgid "The full list of modules described in this chapter is:" -msgstr "本章節所描述的模組清單為：" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Weilin Du, 2025 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2022-07-06 00:17+0000\n" +"PO-Revision-Date: 2025-06-28 10:57+0800\n" +"Last-Translator: Liang-Bo Wang \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/custominterp.rst:5 +msgid "Custom Python Interpreters" +msgstr "自訂 Python 直譯器" + +#: ../../library/custominterp.rst:7 +msgid "" +"The modules described in this chapter allow writing interfaces similar to " +"Python's interactive interpreter. If you want a Python interpreter that " +"supports some special feature in addition to the Python language, you should " +"look at the :mod:`code` module. (The :mod:`codeop` module is lower-level, " +"used to support compiling a possibly incomplete chunk of Python code.)" +msgstr "" +"本章介紹的模組可用於編寫類似於 Python 交互式直譯器的介面。如果你需要一個在 " +"Python 語言基礎上支援某些特殊功能的直譯器，可以參考 :mod:`code` 模組。（" +" :mod:`codeop` 模組屬於底層工具，用於支援編譯可能不完整的 Python 程式碼。）" + +#: ../../library/custominterp.rst:13 +msgid "The full list of modules described in this chapter is:" +msgstr "本章節所描述的模組清單為：" diff --git a/library/dataclasses.po b/library/dataclasses.po index cc1422bc34..4584b20814 100644 --- a/library/dataclasses.po +++ b/library/dataclasses.po @@ -1,1713 +1,1713 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-10-08 00:15+0000\n" -"PO-Revision-Date: 2023-02-11 15:02+0800\n" -"Last-Translator: \n" -"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" -"tw)\n" -"Language: zh_TW\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=UTF-8\n" -"Content-Transfer-Encoding: 8bit\n" -"X-Generator: Poedit 3.2.2\n" - -#: ../../library/dataclasses.rst:2 -msgid ":mod:`!dataclasses` --- Data Classes" -msgstr ":mod:`!dataclasses` --- Data Classes" - -#: ../../library/dataclasses.rst:10 -msgid "**Source code:** :source:`Lib/dataclasses.py`" -msgstr "**原始碼：**\\ :source:`Lib/dataclasses.py`" - -#: ../../library/dataclasses.rst:14 -#, fuzzy -msgid "" -"This module provides a decorator and functions for automatically adding " -"generated :term:`special methods ` such as :meth:`~object." -"__init__` and :meth:`~object.__repr__` to user-defined classes. It was " -"originally described in :pep:`557`." -msgstr "" -"該模組提供了一個裝飾器和函式，用於自動新增生成的\\ :term:`特殊方法 `，例如 :meth:`~object.__init__` 和 :meth:`~object.__repr__` 到使用者" -"定義的類別。它最初在 :pep:`557` 中描述。" - -#: ../../library/dataclasses.rst:19 -#, fuzzy -msgid "" -"The member variables to use in these generated methods are defined using :" -"pep:`526` type annotations. For example, this code::" -msgstr "" -"在這些生成的方法中使用的成員變數是使用 :pep:`526` 型別註釋定義的。例如，這段" -"程式碼： ::" - -#: ../../library/dataclasses.rst:22 -msgid "" -"from dataclasses import dataclass\n" -"\n" -"@dataclass\n" -"class InventoryItem:\n" -" \"\"\"Class for keeping track of an item in inventory.\"\"\"\n" -" name: str\n" -" unit_price: float\n" -" quantity_on_hand: int = 0\n" -"\n" -" def total_cost(self) -> float:\n" -" return self.unit_price * self.quantity_on_hand" -msgstr "" - -#: ../../library/dataclasses.rst:34 -#, fuzzy -msgid "will add, among other things, a :meth:`!__init__` that looks like::" -msgstr "將新增，除其他事項外，一個 :meth:`!__init__` 看起來像： ::" - -#: ../../library/dataclasses.rst:36 -msgid "" -"def __init__(self, name: str, unit_price: float, quantity_on_hand: int = " -"0):\n" -" self.name = name\n" -" self.unit_price = unit_price\n" -" self.quantity_on_hand = quantity_on_hand" -msgstr "" -"def __init__(self, name: str, unit_price: float, quantity_on_hand: int = " -"0):\n" -" self.name = name\n" -" self.unit_price = unit_price\n" -" self.quantity_on_hand = quantity_on_hand" - -#: ../../library/dataclasses.rst:41 -#, fuzzy -msgid "" -"Note that this method is automatically added to the class: it is not " -"directly specified in the :class:`!InventoryItem` definition shown above." -msgstr "" -"請注意，此方法會自動新增到類別中：它不會在上面顯示的 :class:`!InventoryItem` " -"定義中直接指定。" - -#: ../../library/dataclasses.rst:47 -msgid "Module contents" -msgstr "模組內容" - -#: ../../library/dataclasses.rst:51 -#, fuzzy -msgid "" -"This function is a :term:`decorator` that is used to add generated :term:" -"`special methods ` to classes, as described below." -msgstr "" -"此函式是一個 :term:`decorator`，用於將生成的\\ :term:`特殊方法 `\\新增到類別中，如下所述。" - -#: ../../library/dataclasses.rst:54 -#, fuzzy -msgid "" -"The ``@dataclass`` decorator examines the class to find ``field``\\s. A " -"``field`` is defined as a class variable that has a :term:`type annotation " -"`. With two exceptions described below, nothing in " -"``@dataclass`` examines the type specified in the variable annotation." -msgstr "" -"``@dataclass`` 裝飾器檢查類別以找到 ``field``\\s。 ``field`` 被定義為具有 :" -"term:`type annotation ` 的類別變數。除了下面描述的兩個例" -"外，``@dataclass`` 中沒有任何內容檢查變數註釋中指定的型別。" - -#: ../../library/dataclasses.rst:60 -#, fuzzy -msgid "" -"The order of the fields in all of the generated methods is the order in " -"which they appear in the class definition." -msgstr "所有生成的方法中欄位的順序是它們在類別定義中出現的順序。" - -#: ../../library/dataclasses.rst:63 -msgid "" -"The ``@dataclass`` decorator will add various \"dunder\" methods to the " -"class, described below. If any of the added methods already exist in the " -"class, the behavior depends on the parameter, as documented below. The " -"decorator returns the same class that it is called on; no new class is " -"created." -msgstr "" -"如下所述，``@dataclass`` 裝飾器會向類別新增各種 \"dunder\" 方法。如果類別中已" -"存在任何新增的方法，則行為會取決於參數，如下方文件所述。裝飾器會回傳呼叫它的" -"同一個類別；不會建立新類別。" - -#: ../../library/dataclasses.rst:69 -#, fuzzy -msgid "" -"If ``@dataclass`` is used just as a simple decorator with no parameters, it " -"acts as if it has the default values documented in this signature. That is, " -"these three uses of ``@dataclass`` are equivalent::" -msgstr "" -"如果 ``@dataclass`` 僅用作不帶參數的簡單裝飾器，它的行為就好像它具有此簽名中" -"記錄的預設值一樣。也就是說，``@dataclass`` 的這三種用法是等價的： ::" - -#: ../../library/dataclasses.rst:74 -msgid "" -"@dataclass\n" -"class C:\n" -" ...\n" -"\n" -"@dataclass()\n" -"class C:\n" -" ...\n" -"\n" -"@dataclass(init=True, repr=True, eq=True, order=False, unsafe_hash=False, " -"frozen=False,\n" -" match_args=True, kw_only=False, slots=False, weakref_slot=False)\n" -"class C:\n" -" ..." -msgstr "" -"@dataclass\n" -"class C:\n" -" ...\n" -"\n" -"@dataclass()\n" -"class C:\n" -" ...\n" -"\n" -"@dataclass(init=True, repr=True, eq=True, order=False, unsafe_hash=False, " -"frozen=False,\n" -" match_args=True, kw_only=False, slots=False, weakref_slot=False)\n" -"class C:\n" -" ..." - -#: ../../library/dataclasses.rst:87 -msgid "The parameters to ``@dataclass`` are:" -msgstr "``@dataclass`` 的參數是：" - -#: ../../library/dataclasses.rst:89 -msgid "" -"*init*: If true (the default), a :meth:`~object.__init__` method will be " -"generated." -msgstr "*init*：如果為真（預設值），將生成一個 :meth:`~object.__init__` 方法。" - -#: ../../library/dataclasses.rst:92 -msgid "" -"If the class already defines :meth:`!__init__`, this parameter is ignored." -msgstr "如果該類別已經定義了 :meth:`!__init__`，則此參數會被忽略。" - -#: ../../library/dataclasses.rst:95 -#, fuzzy -msgid "" -"*repr*: If true (the default), a :meth:`~object.__repr__` method will be " -"generated. The generated repr string will have the class name and the name " -"and repr of each field, in the order they are defined in the class. Fields " -"that are marked as being excluded from the repr are not included. For " -"example: ``InventoryItem(name='widget', unit_price=3.0, " -"quantity_on_hand=10)``." -msgstr "" -"*repr*：如果為真（預設值），將生成一個 :meth:`__repr__` 方法。生成的 repr 字" -"串將包含類別名稱以及每個欄位的名稱和 repr，按照它們在類別中定義的順序排列。不" -"包括標記為從 repr 中排除的欄位。例如：``InventoryItem(name='widget', " -"unit_price=3.0, quantity_on_hand=10)``。" - -#: ../../library/dataclasses.rst:102 -msgid "" -"If the class already defines :meth:`!__repr__`, this parameter is ignored." -msgstr "如果該類別已經定義了 :meth:`!__repr__`，則此參數會被忽略。" - -#: ../../library/dataclasses.rst:105 -#, fuzzy -msgid "" -"*eq*: If true (the default), an :meth:`~object.__eq__` method will be " -"generated. This method compares the class as if it were a tuple of its " -"fields, in order. Both instances in the comparison must be of the identical " -"type." -msgstr "" -"*eq*：如果為真（預設值），將生成一個 :meth:`~object.__eq__` 方法。此方法按順" -"序比較類別，就好像它是其欄位的元組一樣。比較中的兩個實例必須屬於同一型別。" - -#: ../../library/dataclasses.rst:110 -msgid "" -"If the class already defines :meth:`!__eq__`, this parameter is ignored." -msgstr "如果該類別已經定義了 :meth:`!__eq__`，則此參數會被忽略。" - -#: ../../library/dataclasses.rst:113 -#, fuzzy -msgid "" -"*order*: If true (the default is ``False``), :meth:`~object.__lt__`, :meth:" -"`~object.__le__`, :meth:`~object.__gt__`, and :meth:`~object.__ge__` methods " -"will be generated. These compare the class as if it were a tuple of its " -"fields, in order. Both instances in the comparison must be of the identical " -"type. If *order* is true and *eq* is false, a :exc:`ValueError` is raised." -msgstr "" -"*order*：如果為真（預設為 ``False``），:meth:`~object.__lt__`、:meth:" -"`~object.__le__`、:meth:`~object.__gt__` 和 :meth:`~object.__ge__` 方法將是產" -"生。它們按順序比較類別，就好像它是其欄位的元組一樣。比較中的兩個實例必須屬於" -"同一型別。如果 *order* 為真且 *eq* 為假，則會引發 :exc:`ValueError`。" - -#: ../../library/dataclasses.rst:120 -msgid "" -"If the class already defines any of :meth:`!__lt__`, :meth:`!__le__`, :meth:" -"`!__gt__`, or :meth:`!__ge__`, then :exc:`TypeError` is raised." -msgstr "" -"如果該類別已經定義了 :meth:`!__lt__`、:meth:`!__le__`、:meth:`!__gt__` 或 :" -"meth:`!__ge__` 中的任何一個，則引發 :exc:`TypeError`。" - -#: ../../library/dataclasses.rst:124 -#, fuzzy -msgid "" -"*unsafe_hash*: If true, force ``dataclasses`` to create a :meth:`~object." -"__hash__` method, even though it may not be safe to do so. Otherwise, " -"generate a :meth:`~object.__hash__` method according to how *eq* and " -"*frozen* are set. The default value is ``False``." -msgstr "" -"*unsafe_hash*：如果 ``False``\\ （預設值），將根據 *eq* 和 *frozen* 的設定生成一" -"個 :meth:`~object.__hash__` 方法。" - -#: ../../library/dataclasses.rst:130 -#, fuzzy -msgid "" -":meth:`!__hash__` is used by built-in :meth:`hash`, and when objects are " -"added to hashed collections such as dictionaries and sets. Having a :meth:`!" -"__hash__` implies that instances of the class are immutable. Mutability is a " -"complicated property that depends on the programmer's intent, the existence " -"and behavior of :meth:`!__eq__`, and the values of the *eq* and *frozen* " -"flags in the ``@dataclass`` decorator." -msgstr "" -":meth:`!__hash__` 由內建的 :meth:`hash` 使用，當物件被新增到雜湊集合（如字典" -"和集合）時。擁有 :meth:`!__hash__` 意味著該類別的實例是不可變的。可變性是一個" -"複雜的屬性，它取決於程序設計師的意圖 :meth:`!__eq__` 的存在和行為，以及 " -"dataclass 裝飾器中的 *eq* 和 *frozen* 旗標的值." - -#: ../../library/dataclasses.rst:137 -#, fuzzy -msgid "" -"By default, ``@dataclass`` will not implicitly add a :meth:`~object." -"__hash__` method unless it is safe to do so. Neither will it add or change " -"an existing explicitly defined :meth:`!__hash__` method. Setting the class " -"attribute ``__hash__ = None`` has a specific meaning to Python, as described " -"in the :meth:`!__hash__` documentation." -msgstr "" -"預設情況下，``@dataclass`` 不會隱式新增 :meth:`~object.__hash__` 方法，除非這" -"樣做是安全的。它也不會新增或更改現有的明確定義的 :meth:`!__hash__` 方法。設定" -"類別屬性 ``__hash__ = None`` 對 Python 具有特定含義，如 :meth:`!__hash__` 文" -"件中所述。" - -#: ../../library/dataclasses.rst:143 -#, fuzzy -msgid "" -"If :meth:`!__hash__` is not explicitly defined, or if it is set to ``None``, " -"then ``@dataclass`` *may* add an implicit :meth:`!__hash__` method. Although " -"not recommended, you can force ``@dataclass`` to create a :meth:`!__hash__` " -"method with ``unsafe_hash=True``. This might be the case if your class is " -"logically immutable but can still be mutated. This is a specialized use case " -"and should be considered carefully." -msgstr "" -"如果 :meth:`!__hash__` 沒有明確定義，或者如果它被設定為 ``None``，那麼 " -"``@dataclass`` *可能* 新增一個隱式的 :meth:`!__hash__` 方法。雖然不推薦，但你" -"可以強制 ``@dataclass`` 使用 ``unsafe_hash=True`` 建立一個 :meth:`!__hash__` " -"方法。如果你的類別在邏輯上是不可變的但仍然可以改變，則可能是這種情況。這是一" -"個特殊的用例，應該仔細考慮。" - -#: ../../library/dataclasses.rst:150 -#, fuzzy -msgid "" -"Here are the rules governing implicit creation of a :meth:`!__hash__` " -"method. Note that you cannot both have an explicit :meth:`!__hash__` method " -"in your dataclass and set ``unsafe_hash=True``; this will result in a :exc:" -"`TypeError`." -msgstr "" -"以下是管理隱式建立 :meth:`!__hash__` 方法的規則。請注意，你不能在資料類別中既" -"有顯式的 :meth:`!__hash__` 方法又設定 ``unsafe_hash=True``；這將導致 :exc:" -"`TypeError`。" - -#: ../../library/dataclasses.rst:155 -msgid "" -"If *eq* and *frozen* are both true, by default ``@dataclass`` will generate " -"a :meth:`!__hash__` method for you. If *eq* is true and *frozen* is false, :" -"meth:`!__hash__` will be set to ``None``, marking it unhashable (which it " -"is, since it is mutable). If *eq* is false, :meth:`!__hash__` will be left " -"untouched meaning the :meth:`!__hash__` method of the superclass will be " -"used (if the superclass is :class:`object`, this means it will fall back to " -"id-based hashing)." -msgstr "" -"如果 *eq* 和 *frozen* 都為真，預設情況下 ``@dataclass`` 會為你生成一個 :meth:" -"`!__hash__` 方法。如果 *eq* 為真且 *frozen* 為假，:meth:`!__hash__` 將被設定" -"為 ``None``，並將其標記為不可雜湊（因為它是可變的）。如果 *eq* 為假，:meth:`!" -"__hash__` 將保持不變，這意味著將使用超類別的 :meth:`!__hash__` 方法（如果超類" -"別是 :class:`object`，這意味著它將回退到基於 id 的雜湊）。" - -#: ../../library/dataclasses.rst:163 -#, fuzzy -msgid "" -"*frozen*: If true (the default is ``False``), assigning to fields will " -"generate an exception. This emulates read-only frozen instances. See the :" -"ref:`discussion ` below." -msgstr "" -"*frozen*：如果為真（預設為 ``False``），分配給欄位將產生例外。這模擬了只讀的" -"凍結實例。如果 :meth:`~object.__setattr__` 或 :meth:`~object.__delattr__` 在" -"類別中定義，則 :exc:`TypeError` 被引發。請參閱下面的討論。" - -#: ../../library/dataclasses.rst:167 -msgid "" -"If :meth:`~object.__setattr__` or :meth:`~object.__delattr__` is defined in " -"the class and *frozen* is true, then :exc:`TypeError` is raised." -msgstr "" -"如果類別中定義了 :meth:`~object.__setattr__` 或 :meth:`~object.__delattr__` " -"且 *frozen* 為真，則會引發 :exc:`TypeError`。" - -#: ../../library/dataclasses.rst:170 -#, fuzzy -msgid "" -"*match_args*: If true (the default is ``True``), the :attr:`~object." -"__match_args__` tuple will be created from the list of non keyword-only " -"parameters to the generated :meth:`~object.__init__` method (even if :meth:`!" -"__init__` is not generated, see above). If false, or if :attr:`!" -"__match_args__` is already defined in the class, then :attr:`!" -"__match_args__` will not be generated." -msgstr "" -"*match_args*：如果為真（預設為 ``True``），``__match_args__`` 元組將從參數列" -"表建立到生成的 :meth:`~object.__init__` 方法（即使 :meth: `!__init__` 未生" -"成，見上文）。如果為 false，或者類別中已經定義了 :attr:`!__match_args__`，則" -"不會生成 :attr:`!__match_args__`。" - -#: ../../library/dataclasses.rst:179 -#, fuzzy -msgid "" -"*kw_only*: If true (the default value is ``False``), then all fields will be " -"marked as keyword-only. If a field is marked as keyword-only, then the only " -"effect is that the :meth:`~object.__init__` parameter generated from a " -"keyword-only field must be specified with a keyword when :meth:`!__init__` " -"is called. See the :term:`parameter` glossary entry for details. Also see " -"the :const:`KW_ONLY` section." -msgstr "" -"``kw_only``：如果為 true（預設值為 ``False``），則所有欄位將被標記為僅限關鍵" -"字。如果一個欄位被標記為僅限關鍵字，那麼唯一的影響是從僅限關鍵字欄位生成的 :" -"meth:`~object.__init__` 參數必須在呼叫 :meth:`!__init__` 時指定關鍵字。對資料" -"類別的任何其他方面都沒有影響。有關詳細資訊，請參閱 :term:`parameter` 詞彙表條" -"目。另請參閱 :const:`KW_ONLY` 部分。" - -#: ../../library/dataclasses.rst:187 -msgid "Keyword-only fields are not included in :attr:`!__match_args__`." -msgstr "" - -#: ../../library/dataclasses.rst:191 -#, fuzzy -msgid "" -"*slots*: If true (the default is ``False``), :attr:`~object.__slots__` " -"attribute will be generated and new class will be returned instead of the " -"original one. If :attr:`!__slots__` is already defined in the class, then :" -"exc:`TypeError` is raised." -msgstr "" -"``slots``：如果為 true（預設為 ``False``），將生成 :attr:`~object.__slots__` " -"屬性並回傳新類別而不是原始類別。如果 :attr:`!__slots__` 已經在類別中定義，" -"則 :exc:`TypeError` 被引發。" - -#: ../../library/dataclasses.rst:197 -msgid "" -"Passing parameters to a base class :meth:`~object.__init_subclass__` when " -"using ``slots=True`` will result in a :exc:`TypeError`. Either use " -"``__init_subclass__`` with no parameters or use default values as a " -"workaround. See :gh:`91126` for full details." -msgstr "" - -#: ../../library/dataclasses.rst:205 -#, fuzzy -msgid "" -"If a field name is already included in the :attr:`!__slots__` of a base " -"class, it will not be included in the generated :attr:`!__slots__` to " -"prevent :ref:`overriding them `. Therefore, do not " -"use :attr:`!__slots__` to retrieve the field names of a dataclass. Use :func:" -"`fields` instead. To be able to determine inherited slots, base class :attr:" -"`!__slots__` may be any iterable, but *not* an iterator." -msgstr "" -"如果欄位名稱已經包含在基底類別的 :attr:`!__slots__` 中，它將不會包含在生成" -"的 :attr:`!__slots__` 中以防止 :ref:`覆蓋它們 `。因此，" -"不要使用 __slots__ 來檢索資料類別的欄位名稱。使用 :func:`fields` 代替。為了能" -"夠確定繼承的插槽，基底類別 :attr:`!__slots__` 可以是任何可疊代的，但*不是*疊" -"代器。" - -#: ../../library/dataclasses.rst:215 -#, fuzzy -msgid "" -"*weakref_slot*: If true (the default is ``False``), add a slot named " -"\"__weakref__\", which is required to make an instance :func:`weakref-able " -"`. It is an error to specify ``weakref_slot=True`` without also " -"specifying ``slots=True``." -msgstr "" -"*weakref_slot*：如果為真（預設為 ``False``），新增一個名為 \"__weakref__\" 的" -"插槽，這是使實例可弱引用所必需的。在沒有指定 ``slots=True`` 的情況下指定 " -"``weakref_slot=True`` 是錯誤的。" - -#: ../../library/dataclasses.rst:223 -#, fuzzy -msgid "" -"``field``\\s may optionally specify a default value, using normal Python " -"syntax::" -msgstr "``field``\\s 可以選擇指定一個預設值，使用普通的 Python 語法： ::" - -#: ../../library/dataclasses.rst:226 -msgid "" -"@dataclass\n" -"class C:\n" -" a: int # 'a' has no default value\n" -" b: int = 0 # assign a default value for 'b'" -msgstr "" - -#: ../../library/dataclasses.rst:231 -#, fuzzy -msgid "" -"In this example, both :attr:`!a` and :attr:`!b` will be included in the " -"added :meth:`~object.__init__` method, which will be defined as::" -msgstr "" -"在此示例中，:attr:`!a` 和 :attr:`!b` 都將包含在新增的 :meth:`~object." -"__init__` 方法中，該方法將定義為： ::" - -#: ../../library/dataclasses.rst:234 -msgid "def __init__(self, a: int, b: int = 0):" -msgstr "def __init__(self, a: int, b: int = 0):" - -#: ../../library/dataclasses.rst:236 -#, fuzzy -msgid "" -":exc:`TypeError` will be raised if a field without a default value follows a " -"field with a default value. This is true whether this occurs in a single " -"class, or as a result of class inheritance." -msgstr "" -":exc:`TypeError` 如果沒有預設值的欄位跟在具有預設值的欄位之後，將引發。無論這" -"發生在單個類別中還是作為類別繼承的結果，都是如此。" - -#: ../../library/dataclasses.rst:242 -#, fuzzy -msgid "" -"For common and simple use cases, no other functionality is required. There " -"are, however, some dataclass features that require additional per-field " -"information. To satisfy this need for additional information, you can " -"replace the default field value with a call to the provided :func:`!field` " -"function. For example::" -msgstr "" -"對於常見和簡單的用例，不需要其他功能。但是，有些資料類別功能需要額外的每個欄" -"位資訊。為了滿足這種對附加資訊的需求，你可以透過呼叫提供的 :func:`!field` 函" -"式來替換預設欄位值。例如： ::" - -#: ../../library/dataclasses.rst:248 -msgid "" -"@dataclass\n" -"class C:\n" -" mylist: list[int] = field(default_factory=list)\n" -"\n" -"c = C()\n" -"c.mylist += [1, 2, 3]" -msgstr "" -"@dataclass\n" -"class C:\n" -" mylist: list[int] = field(default_factory=list)\n" -"\n" -"c = C()\n" -"c.mylist += [1, 2, 3]" - -#: ../../library/dataclasses.rst:255 -#, fuzzy -msgid "" -"As shown above, the :const:`MISSING` value is a sentinel object used to " -"detect if some parameters are provided by the user. This sentinel is used " -"because ``None`` is a valid value for some parameters with a distinct " -"meaning. No code should directly use the :const:`MISSING` value." -msgstr "" -"如上所示，:const:`MISSING` 值是一個哨兵物件，用於檢測某些參數是否由使用者提" -"供。使用此標記是因為 ``None`` 對於某些具有不同含義的參數是有效值。任何程式碼" -"都不應直接使用 :const:`MISSING` 值。" - -#: ../../library/dataclasses.rst:260 -msgid "The parameters to :func:`!field` are:" -msgstr ":func:`!field` 的參數是：" - -#: ../../library/dataclasses.rst:262 -msgid "" -"*default*: If provided, this will be the default value for this field. This " -"is needed because the :func:`!field` call itself replaces the normal " -"position of the default value." -msgstr "" -"*default*：如果有提供，這將是該欄位的預設值。這是必需的，因為 :meth:`!field` " -"呼叫本身會替換預設值的正常位置。" - -#: ../../library/dataclasses.rst:266 -#, fuzzy -msgid "" -"*default_factory*: If provided, it must be a zero-argument callable that " -"will be called when a default value is needed for this field. Among other " -"purposes, this can be used to specify fields with mutable default values, as " -"discussed below. It is an error to specify both *default* and " -"*default_factory*." -msgstr "" -"*default_factory*：如果提供，它必須是一個零引數可呼叫函式，當此欄位需要預設值" -"時將被呼叫。除其他用途外，這可用於指定具有可變預設值的欄位，如下所述。同時指" -"定 *default* 和 *default_factory* 是錯誤的。" - -#: ../../library/dataclasses.rst:272 -#, fuzzy -msgid "" -"*init*: If true (the default), this field is included as a parameter to the " -"generated :meth:`~object.__init__` method." -msgstr "" -"*init*：如果為 true（預設值），則此欄位將作為生成的 :meth:`~object.__init__` " -"方法的參數包含在內。" - -#: ../../library/dataclasses.rst:275 -#, fuzzy -msgid "" -"*repr*: If true (the default), this field is included in the string returned " -"by the generated :meth:`~object.__repr__` method." -msgstr "" -"*repr*：如果為真（預設值），則此欄位包含在生成的 :meth:`~object.__repr__` 方" -"法回傳的字串中。" - -#: ../../library/dataclasses.rst:278 -#, fuzzy -msgid "" -"*hash*: This can be a bool or ``None``. If true, this field is included in " -"the generated :meth:`~object.__hash__` method. If false, this field is " -"excluded from the generated :meth:`~object.__hash__`. If ``None`` (the " -"default), use the value of *compare*: this would normally be the expected " -"behavior, since a field should be included in the hash if it's used for " -"comparisons. Setting this value to anything other than ``None`` is " -"discouraged." -msgstr "" -"*hash*：這可以是 bool 或 ``None``。如果為真，則此欄位包含在生成的 :meth:" -"`__hash__` 方法中。如果 ``None``\\ （預設值），則使用\\ *比較*\\ 的值：這通常" -"是預期的行為。如果一個欄位用於比較，則應在雜湊中考慮該欄位。不鼓勵將此值設定" -"為 ``None`` 以外的任何值。" - -#: ../../library/dataclasses.rst:286 -#, fuzzy -msgid "" -"One possible reason to set ``hash=False`` but ``compare=True`` would be if a " -"field is expensive to compute a hash value for, that field is needed for " -"equality testing, and there are other fields that contribute to the type's " -"hash value. Even if a field is excluded from the hash, it will still be " -"used for comparisons." -msgstr "" -"設定 ``hash=False`` 但 ``compare=True`` 的一個可能原因是，如果一個欄位計算雜" -"湊值的成本很高，則需要該欄位進行相等性測試，並且還有其他欄位有助於型別的雜湊" -"值。即使一個欄位被排除在雜湊之外，它仍然會被用於比較。" - -#: ../../library/dataclasses.rst:292 -#, fuzzy -msgid "" -"*compare*: If true (the default), this field is included in the generated " -"equality and comparison methods (:meth:`~object.__eq__`, :meth:`~object." -"__gt__`, et al.)." -msgstr "" -"*compare*：如果為真（預設值），則此欄位包含在生成的相等和比較方法中（:meth:" -"`~object.__eq__`、:meth:`~object.__gt__` 等）。" - -#: ../../library/dataclasses.rst:296 -#, fuzzy -msgid "" -"*metadata*: This can be a mapping or ``None``. ``None`` is treated as an " -"empty dict. This value is wrapped in :func:`~types.MappingProxyType` to " -"make it read-only, and exposed on the :class:`Field` object. It is not used " -"at all by Data Classes, and is provided as a third-party extension " -"mechanism. Multiple third-parties can each have their own key, to use as a " -"namespace in the metadata." -msgstr "" -"*metadata*：這可以是對映或無。 None 被視為空字典。此值包含在 :func:`~types." -"MappingProxyType` 中以使其成為只讀的，並暴露在 :class:`Field` 物件上。它根本" -"不被資料類別使用，而是作為第三方擴充機制提供的。多個第三方可以各自擁有自己的" -"密鑰，用作元資料中的命名空間。" - -#: ../../library/dataclasses.rst:304 -#, fuzzy -msgid "" -"*kw_only*: If true, this field will be marked as keyword-only. This is used " -"when the generated :meth:`~object.__init__` method's parameters are computed." -msgstr "" -"*kw_only*：如果為真，該欄位將被標記為僅限關鍵字。這在計算生成的 :meth:" -"`~object.__init__` 方法的參數時使用。" - -#: ../../library/dataclasses.rst:308 -msgid "Keyword-only fields are also not included in :attr:`!__match_args__`." -msgstr "" - -#: ../../library/dataclasses.rst:312 -msgid "*doc*: optional docstring for this field." -msgstr "" - -#: ../../library/dataclasses.rst:316 -#, fuzzy -msgid "" -"If the default value of a field is specified by a call to :func:`!field`, " -"then the class attribute for this field will be replaced by the specified " -"*default* value. If *default* is not provided, then the class attribute " -"will be deleted. The intent is that after the :deco:`dataclass` decorator " -"runs, the class attributes will all contain the default values for the " -"fields, just as if the default value itself were specified. For example, " -"after::" -msgstr "" -"如果欄位的預設值是透過呼叫 :func:`!field` 指定的，那麼該欄位的類別屬性將被指" -"定的 *default* 值替換。如果沒有提供 *default*，那麼類別屬性將被刪除。目的是" -"在 :func:`@dataclass ` 裝飾器運行後，類別屬性將全部包含欄位的預設" -"值，就像預設值本身已指定一樣。例如，在： ::" - -#: ../../library/dataclasses.rst:325 -msgid "" -"@dataclass\n" -"class C:\n" -" x: int\n" -" y: int = field(repr=False)\n" -" z: int = field(repr=False, default=10)\n" -" t: int = 20" -msgstr "" -"@dataclass\n" -"class C:\n" -" x: int\n" -" y: int = field(repr=False)\n" -" z: int = field(repr=False, default=10)\n" -" t: int = 20" - -#: ../../library/dataclasses.rst:332 -#, fuzzy -msgid "" -"The class attribute :attr:`!C.z` will be ``10``, the class attribute :attr:`!" -"C.t` will be ``20``, and the class attributes :attr:`!C.x` and :attr:`!C.y` " -"will not be set." -msgstr "" -"類別屬性 :attr:`!C.z` 將為 ``10``，類別屬性 :attr:`!C.t` 將為 ``20``，類別屬" -"性 :attr:`!C.x` 和 :attr:`!C.y` 將不會放。" - -#: ../../library/dataclasses.rst:338 -#, fuzzy -msgid "" -":class:`!Field` objects describe each defined field. These objects are " -"created internally, and are returned by the :func:`fields` module-level " -"method (see below). Users should never instantiate a :class:`!Field` object " -"directly. Its documented attributes are:" -msgstr "" -":class:`!Field` 物件描述每個定義的欄位。這些物件在內部建立，並由 :func:" -"`fields` 模組級方法回傳（見下文）。使用者不應該直接實例化 :class:`!Field` 物" -"件。它記錄的屬性是：" - -#: ../../library/dataclasses.rst:343 -msgid ":attr:`!name`: The name of the field." -msgstr ":attr:`!name`：欄位的名稱。" - -#: ../../library/dataclasses.rst:344 -msgid ":attr:`!type`: The type of the field." -msgstr ":attr:`!type`：欄位的型別。" - -#: ../../library/dataclasses.rst:345 -#, fuzzy -msgid "" -":attr:`!default`, :attr:`!default_factory`, :attr:`!init`, :attr:`!repr`, :" -"attr:`!hash`, :attr:`!compare`, :attr:`!metadata`, and :attr:`!kw_only` have " -"the identical meaning and values as they do in the :func:`field` function." -msgstr "" -":attr:`!default`、:attr:`!default_factory`、:attr:`!init`、:attr:`!repr`、:" -"attr:`!hash`、:attr:`!compare`, :attr:`!metadata` 和 :attr:`!kw_only` 有與它" -"們在 :func:`field` 函式中的含義和值相同。" - -#: ../../library/dataclasses.rst:349 -#, fuzzy -msgid "" -"Other attributes may exist, but they are private and must not be inspected " -"or relied on." -msgstr "可能存在其他屬性，但它們是私有的，不得檢查或依賴。" - -#: ../../library/dataclasses.rst:354 -msgid "" -"``InitVar[T]`` type annotations describe variables that are :ref:`init-only " -"`. Fields annotated with :class:`!InitVar` " -"are considered pseudo-fields, and thus are neither returned by the :func:" -"`fields` function nor used in any way except adding them as parameters to :" -"meth:`~object.__init__` and an optional :meth:`__post_init__`." -msgstr "" - -#: ../../library/dataclasses.rst:363 -#, fuzzy -msgid "" -"Returns a tuple of :class:`Field` objects that define the fields for this " -"dataclass. Accepts either a dataclass, or an instance of a dataclass. " -"Raises :exc:`TypeError` if not passed a dataclass or instance of one. Does " -"not return pseudo-fields which are ``ClassVar`` or ``InitVar``." -msgstr "" -"回傳定義此資料類別欄位的 :class:`Field` 物件的元組。接受資料類別或資料類別的" -"實例。如果未傳遞資料類別或其中一個實例，則引發 :exc:`TypeError`。不回傳 " -"``ClassVar`` 或 ``InitVar`` 的偽欄位。" - -#: ../../library/dataclasses.rst:370 -#, fuzzy -msgid "" -"Converts the dataclass *obj* to a dict (by using the factory function " -"*dict_factory*). Each dataclass is converted to a dict of its fields, as " -"``name: value`` pairs. dataclasses, dicts, lists, and tuples are recursed " -"into. Other objects are copied with :func:`copy.deepcopy`." -msgstr "" -"將資料類別 *obj* 轉換為字典（透過使用工廠函式 *dict_factory*）。每個資料類別" -"都被轉換為其欄位的字典，作為 ``name: value`` 對。資料類別、字典、列表和元組被" -"遞迴到。其他物件使用 :func:`copy.deepcopy` 複製。" - -#: ../../library/dataclasses.rst:376 -#, fuzzy -msgid "Example of using :func:`!asdict` on nested dataclasses::" -msgstr "在嵌套資料類別上使用 :func:`!asdict` 的範例： ::" - -#: ../../library/dataclasses.rst:378 -msgid "" -"@dataclass\n" -"class Point:\n" -" x: int\n" -" y: int\n" -"\n" -"@dataclass\n" -"class C:\n" -" mylist: list[Point]\n" -"\n" -"p = Point(10, 20)\n" -"assert asdict(p) == {'x': 10, 'y': 20}\n" -"\n" -"c = C([Point(0, 0), Point(10, 4)])\n" -"assert asdict(c) == {'mylist': [{'x': 0, 'y': 0}, {'x': 10, 'y': 4}]}" -msgstr "" -"@dataclass\n" -"class Point:\n" -" x: int\n" -" y: int\n" -"\n" -"@dataclass\n" -"class C:\n" -" mylist: list[Point]\n" -"\n" -"p = Point(10, 20)\n" -"assert asdict(p) == {'x': 10, 'y': 20}\n" -"\n" -"c = C([Point(0, 0), Point(10, 4)])\n" -"assert asdict(c) == {'mylist': [{'x': 0, 'y': 0}, {'x': 10, 'y': 4}]}" - -#: ../../library/dataclasses.rst:393 ../../library/dataclasses.rst:413 -#, fuzzy -msgid "To create a shallow copy, the following workaround may be used::" -msgstr "要建立淺複製，可以使用以下解決方法：" - -#: ../../library/dataclasses.rst:395 -msgid "{field.name: getattr(obj, field.name) for field in fields(obj)}" -msgstr "{field.name: getattr(obj, field.name) for field in fields(obj)}" - -#: ../../library/dataclasses.rst:397 -#, fuzzy -msgid "" -":func:`!asdict` raises :exc:`TypeError` if *obj* is not a dataclass instance." -msgstr ":func:`!asdict` 如果 *obj* 不是資料類別實例，則引發 :exc:`TypeError`。" - -#: ../../library/dataclasses.rst:402 -#, fuzzy -msgid "" -"Converts the dataclass *obj* to a tuple (by using the factory function " -"*tuple_factory*). Each dataclass is converted to a tuple of its field " -"values. dataclasses, dicts, lists, and tuples are recursed into. Other " -"objects are copied with :func:`copy.deepcopy`." -msgstr "" -"將資料類別 *obj* 轉換為元組（透過使用工廠函式 *tuple_factory*）。每個資料類別" -"都被轉換為其欄位值的元組。資料類別、字典、列表和元組被遞迴到。其他物件使用 :" -"func:`copy.deepcopy` 複製。" - -#: ../../library/dataclasses.rst:408 -msgid "Continuing from the previous example::" -msgstr "從前面的例子繼續： ::" - -#: ../../library/dataclasses.rst:410 -msgid "" -"assert astuple(p) == (10, 20)\n" -"assert astuple(c) == ([(0, 0), (10, 4)],)" -msgstr "" -"assert astuple(p) == (10, 20)\n" -"assert astuple(c) == ([(0, 0), (10, 4)],)" - -#: ../../library/dataclasses.rst:415 -msgid "tuple(getattr(obj, field.name) for field in dataclasses.fields(obj))" -msgstr "tuple(getattr(obj, field.name) for field in dataclasses.fields(obj))" - -#: ../../library/dataclasses.rst:417 -#, fuzzy -msgid "" -":func:`!astuple` raises :exc:`TypeError` if *obj* is not a dataclass " -"instance." -msgstr "" -":func:`!astuple` 如果 *obj* 不是資料類別實例，則引發 :exc:`TypeError`。" - -#: ../../library/dataclasses.rst:422 -#, fuzzy -msgid "" -"Creates a new dataclass with name *cls_name*, fields as defined in *fields*, " -"base classes as given in *bases*, and initialized with a namespace as given " -"in *namespace*. *fields* is an iterable whose elements are each either " -"``name``, ``(name, type)``, or ``(name, type, Field)``. If just ``name`` is " -"supplied, :data:`typing.Any` is used for ``type``. The values of *init*, " -"*repr*, *eq*, *order*, *unsafe_hash*, *frozen*, *match_args*, *kw_only*, " -"*slots*, and *weakref_slot* have the same meaning as they do in :deco:" -"`dataclass`." -msgstr "" -"建立一個名為 *cls_name* 的新資料類別，欄位在 *fields* 中定義，基底類別在 " -"*bases* 中給出，並使用 *namespace* 中給出的命名空間進行初始化。 ``fields`` 是" -"一個疊代器，其元素分別是 ``name``、``(name, type)`` 或 ``(name, type, " -"Field)``。如果只提供 ``name``，則 ``typing.Any`` 用於 ``type``。 ``init``、" -"``repr``、``eq``、``order``、``unsafe_hash``、``frozen``、``match_args``、" -"``kw_only`` 的值, ``slots`` 和 ``weakref_slot`` 與它們在 :func:`dataclass` 中" -"的含義相同。" - -#: ../../library/dataclasses.rst:432 -msgid "" -"If *module* is defined, the :attr:`!__module__` attribute of the dataclass " -"is set to that value. By default, it is set to the module name of the caller." -msgstr "" - -#: ../../library/dataclasses.rst:436 -msgid "" -"The *decorator* parameter is a callable that will be used to create the " -"dataclass. It should take the class object as a first argument and the same " -"keyword arguments as :deco:`dataclass`. By default, the :deco:`dataclass` " -"function is used." -msgstr "" - -#: ../../library/dataclasses.rst:441 -#, fuzzy -msgid "" -"This function is not strictly required, because any Python mechanism for " -"creating a new class with :attr:`~object.__annotations__` can then apply " -"the :deco:`dataclass` function to convert that class to a dataclass. This " -"function is provided as a convenience. For example::" -msgstr "" -"這個函式不是嚴格要求的，因為任何使用 :attr:`~object.__annotations__` 建立新類" -"別的 Python 機制都可以應用 :func:`dataclass` 函式將該類別轉換為資料類別。提供" -"此功能是為了方便。例如： ::" - -#: ../../library/dataclasses.rst:447 -msgid "" -"C = make_dataclass('C',\n" -" [('x', int),\n" -" 'y',\n" -" ('z', int, field(default=5))],\n" -" namespace={'add_one': lambda self: self.x + 1})" -msgstr "" -"C = make_dataclass('C',\n" -" [('x', int),\n" -" 'y',\n" -" ('z', int, field(default=5))],\n" -" namespace={'add_one': lambda self: self.x + 1})" - -#: ../../library/dataclasses.rst:453 -msgid "Is equivalent to::" -msgstr "相當於： ::" - -#: ../../library/dataclasses.rst:455 -msgid "" -"@dataclass\n" -"class C:\n" -" x: int\n" -" y: 'typing.Any'\n" -" z: int = 5\n" -"\n" -" def add_one(self):\n" -" return self.x + 1" -msgstr "" - -#: ../../library/dataclasses.rst:464 -msgid "Added the *decorator* parameter." -msgstr "" - -#: ../../library/dataclasses.rst:469 -#, fuzzy -msgid "" -"Creates a new object of the same type as *obj*, replacing fields with values " -"from *changes*. If *obj* is not a Data Class, raises :exc:`TypeError`. If " -"keys in *changes* are not field names of the given dataclass, raises :exc:" -"`TypeError`." -msgstr "" -"建立一個與 ``obj`` 型別相同的新物件，用 ``changes`` 中的值替換欄位。如果 " -"``obj`` 不是資料類別，則引發 :exc:`TypeError`。如果 ``changes`` 中的值未指定" -"欄位，則引發 :exc:`TypeError`。" - -#: ../../library/dataclasses.rst:474 -#, fuzzy -msgid "" -"The newly returned object is created by calling the :meth:`~object.__init__` " -"method of the dataclass. This ensures that :meth:`__post_init__`, if " -"present, is also called." -msgstr "" -"新回傳的物件是透過呼叫資料類別的 :meth:`~object.__init__` 方法建立的。這確" -"保 :meth:`__post_init__`\\ （如果存在）也被呼叫。" - -#: ../../library/dataclasses.rst:478 -#, fuzzy -msgid "" -"Init-only variables without default values, if any exist, must be specified " -"on the call to :func:`!replace` so that they can be passed to :meth:`!" -"__init__` and :meth:`__post_init__`." -msgstr "" -"沒有預設值的僅初始化變數（如果存在）必須在呼叫 :func:`replace` 時指定，以便它" -"們可以傳遞給 :meth:`__init__` 和 :meth:`__post_init__`。" - -#: ../../library/dataclasses.rst:482 -#, fuzzy -msgid "" -"It is an error for *changes* to contain any fields that are defined as " -"having ``init=False``. A :exc:`ValueError` will be raised in this case." -msgstr "" -"*changes* 包含任何定義為具有 ``init=False`` 的欄位是錯誤的。在這種情況下將引" -"發 :exc:`ValueError`。" - -#: ../../library/dataclasses.rst:486 -#, fuzzy -msgid "" -"Be forewarned about how ``init=False`` fields work during a call to :func:`!" -"replace`. They are not copied from the source object, but rather are " -"initialized in :meth:`__post_init__`, if they're initialized at all. It is " -"expected that ``init=False`` fields will be rarely and judiciously used. If " -"they are used, it might be wise to have alternate class constructors, or " -"perhaps a custom :func:`!replace` (or similarly named) method which handles " -"instance copying." -msgstr "" -"預先警告 ``init=False`` 欄位在呼叫 :func:`!replace` 期間是如何工作的。它們不" -"是從源物件複製的，而是在 :meth:`__post_init__` 中初始化的，如果它們被初始化的" -"話。預計 ``init=False`` 欄位將很少被明智地使用。如果使用它們，使用替代的類別" -"建構函式可能是明智的，或者可能是處理實例複製的自訂 :func:`!replace` （或類似" -"命名的）方法。" - -#: ../../library/dataclasses.rst:495 -msgid "" -"Dataclass instances are also supported by generic function :func:`copy." -"replace`." -msgstr "" - -#: ../../library/dataclasses.rst:499 -msgid "" -"Return ``True`` if its parameter is a dataclass (including subclasses of a " -"dataclass) or an instance of one, otherwise return ``False``." -msgstr "" -"如果它的參數是一個資料類別（包含一個資料類別的子類別）或一個實例則回傳 ``True``，否則回傳 ``False``。" - -#: ../../library/dataclasses.rst:502 -#, fuzzy -msgid "" -"If you need to know if a class is an instance of a dataclass (and not a " -"dataclass itself), then add a further check for ``not isinstance(obj, " -"type)``::" -msgstr "" -"如果你需要知道一個類別是否是資料類別的實例（而不是資料類別本身），那麼新增一" -"個進一步的檢查 ``not isinstance(obj, type)``： ::" - -#: ../../library/dataclasses.rst:506 -msgid "" -"def is_dataclass_instance(obj):\n" -" return is_dataclass(obj) and not isinstance(obj, type)" -msgstr "" -"def is_dataclass_instance(obj):\n" -" return is_dataclass(obj) and not isinstance(obj, type)" - -#: ../../library/dataclasses.rst:511 -#, fuzzy -msgid "A sentinel value signifying a missing default or default_factory." -msgstr "表示缺少 default 或 default_factory 的標記值。" - -#: ../../library/dataclasses.rst:515 -#, fuzzy -msgid "" -"A sentinel value used as a type annotation. Any fields after a pseudo-field " -"with the type of :const:`!KW_ONLY` are marked as keyword-only fields. Note " -"that a pseudo-field of type :const:`!KW_ONLY` is otherwise completely " -"ignored. This includes the name of such a field. By convention, a name of " -"``_`` is used for a :const:`!KW_ONLY` field. Keyword-only fields signify :" -"meth:`~object.__init__` parameters that must be specified as keywords when " -"the class is instantiated." -msgstr "" -"用作型別註釋的標記值。型別為 :const:`!KW_ONLY` 的偽欄位之後的任何欄位都被標記" -"為僅關鍵字欄位。請注意，:const:`!KW_ONLY` 型別的偽欄位將被完全忽略。這包括此" -"類欄位的名稱。按照慣例，名稱 ``_`` 用於 :const:`!KW_ONLY` 欄位。僅關鍵字欄位" -"表示 :meth:`~object.__init__` 參數，在實例化類別時必須將其指定為關鍵字。" - -#: ../../library/dataclasses.rst:524 -#, fuzzy -msgid "" -"In this example, the fields ``y`` and ``z`` will be marked as keyword-only " -"fields::" -msgstr "在此示例中，欄位 ``y`` 和 ``z`` 將被標記為僅關鍵字欄位： ::" - -#: ../../library/dataclasses.rst:526 -msgid "" -"@dataclass\n" -"class Point:\n" -" x: float\n" -" _: KW_ONLY\n" -" y: float\n" -" z: float\n" -"\n" -"p = Point(0, y=1.5, z=2.0)" -msgstr "" -"@dataclass\n" -"class Point:\n" -" x: float\n" -" _: KW_ONLY\n" -" y: float\n" -" z: float\n" -"\n" -"p = Point(0, y=1.5, z=2.0)" - -#: ../../library/dataclasses.rst:535 -#, fuzzy -msgid "" -"In a single dataclass, it is an error to specify more than one field whose " -"type is :const:`!KW_ONLY`." -msgstr "在單個資料類別中，指定多個型別為 :const:`!KW_ONLY` 的欄位是錯誤的。" - -#: ../../library/dataclasses.rst:542 -#, fuzzy -msgid "" -"Raised when an implicitly defined :meth:`~object.__setattr__` or :meth:" -"`~object.__delattr__` is called on a dataclass which was defined with " -"``frozen=True``. It is a subclass of :exc:`AttributeError`." -msgstr "" -"當在使用 frozen=True 定義的資料類別上呼叫隱式定義的 :meth:`__setattr__` 或 :" -"meth:`__delattr__` 時引發。它是 :exc:`AttributeError` 的子類別。" - -#: ../../library/dataclasses.rst:549 -#, fuzzy -msgid "Post-init processing" -msgstr "後初始化處理" - -#: ../../library/dataclasses.rst:553 -#, fuzzy -msgid "" -"When defined on the class, it will be called by the generated :meth:`~object." -"__init__`, normally as :meth:`!self.__post_init__`. However, if any " -"``InitVar`` fields are defined, they will also be passed to :meth:`!" -"__post_init__` in the order they were defined in the class. If no :meth:`!" -"__init__` method is generated, then :meth:`!__post_init__` will not " -"automatically be called." -msgstr "" -"生成的 :meth:`~object.__init__` 程式碼將呼叫一個名為 :meth:`!self." -"__post_init__` 的方法，如果 :meth:`!__post_init__` 是在類別上定義的。它通常被" -"稱為 ``self.!__post_init__()``。但是，如果定義了任何 ``InitVar`` 欄位，它們也" -"將按照它們在類別中定義的順序傳遞給 :meth:`!__post_init__` 。如果沒有生成 :" -"meth:`!__init__` 方法，那麼 :meth:`!__post_init__` 將不會被自動呼叫。" - -#: ../../library/dataclasses.rst:560 -#, fuzzy -msgid "" -"Among other uses, this allows for initializing field values that depend on " -"one or more other fields. For example::" -msgstr "在其他用途中，這允許初始化依賴於一個或多個其他欄位的欄位值。例如： ::" - -#: ../../library/dataclasses.rst:563 -msgid "" -"@dataclass\n" -"class C:\n" -" a: float\n" -" b: float\n" -" c: float = field(init=False)\n" -"\n" -" def __post_init__(self):\n" -" self.c = self.a + self.b" -msgstr "" -"@dataclass\n" -"class C:\n" -" a: float\n" -" b: float\n" -" c: float = field(init=False)\n" -"\n" -" def __post_init__(self):\n" -" self.c = self.a + self.b" - -#: ../../library/dataclasses.rst:572 -#, fuzzy -msgid "" -"The :meth:`~object.__init__` method generated by :deco:`dataclass` does not " -"call base class :meth:`!__init__` methods. If the base class has an :meth:`!" -"__init__` method that has to be called, it is common to call this method in " -"a :meth:`__post_init__` method::" -msgstr "" -":func:`@dataclass ` 生成的 :meth:`~object.__init__` 方法不呼叫基底" -"類別 :meth:`!__init__` 方法。如果基底類別有一個必須呼叫的 :meth:`!__init__` " -"方法，通常在 :meth:`__post_init__` 方法中呼叫此方法： ::" - -#: ../../library/dataclasses.rst:577 -msgid "" -"class Rectangle:\n" -" def __init__(self, height, width):\n" -" self.height = height\n" -" self.width = width\n" -"\n" -"@dataclass\n" -"class Square(Rectangle):\n" -" side: float\n" -"\n" -" def __post_init__(self):\n" -" super().__init__(self.side, self.side)" -msgstr "" -"class Rectangle:\n" -" def __init__(self, height, width):\n" -" self.height = height\n" -" self.width = width\n" -"\n" -"@dataclass\n" -"class Square(Rectangle):\n" -" side: float\n" -"\n" -" def __post_init__(self):\n" -" super().__init__(self.side, self.side)" - -#: ../../library/dataclasses.rst:589 -#, fuzzy -msgid "" -"Note, however, that in general the dataclass-generated :meth:`!__init__` " -"methods don't need to be called, since the derived dataclass will take care " -"of initializing all fields of any base class that is a dataclass itself." -msgstr "" -"但是請注意，通常不需要呼叫資料類別生成的 :meth:`!__init__` 方法，因為衍生資料" -"類別將負責初始化作為資料類別本身的任何基底類別的所有欄位。" - -#: ../../library/dataclasses.rst:593 -#, fuzzy -msgid "" -"See the section below on init-only variables for ways to pass parameters to :" -"meth:`!__post_init__`. Also see the warning about how :func:`replace` " -"handles ``init=False`` fields." -msgstr "" -"請參閱下面有關僅初始化變數的部分，了解將參數傳遞給 :meth:`!__post_init__` 的" -"方法。另請參閱有關 :func:`replace` 如何處理 ``init=False`` 欄位的警告。" - -#: ../../library/dataclasses.rst:600 -msgid "Class variables" -msgstr "類別變數" - -#: ../../library/dataclasses.rst:602 -#, fuzzy -msgid "" -"One of the few places where :deco:`dataclass` actually inspects the type of " -"a field is to determine if a field is a class variable as defined in :pep:" -"`526`. It does this by checking if the type of the field is :data:`typing." -"ClassVar`. If a field is a ``ClassVar``, it is excluded from consideration " -"as a field and is ignored by the dataclass mechanisms. Such ``ClassVar`` " -"pseudo-fields are not returned by the module-level :func:`fields` function." -msgstr "" -":func:`@dataclass ` 實際檢查欄位型別的少數地方之一是確定欄位是否" -"是 :pep:`526` 中定義的類別變數。它透過檢查欄位的型別是否為 :data:`typing." -"ClassVar` 來做到這一點。如果一個欄位是一個 ``ClassVar``，它就被排除在考慮之" -"外，並被資料類別機制忽略。模組級 :func:`fields` 函式不會回傳此類別 " -"``ClassVar`` 偽欄位。" - -#: ../../library/dataclasses.rst:613 -#, fuzzy -msgid "Init-only variables" -msgstr "僅初始化變數" - -#: ../../library/dataclasses.rst:615 -#, fuzzy -msgid "" -"Another place where :deco:`dataclass` inspects a type annotation is to " -"determine if a field is an init-only variable. It does this by seeing if " -"the type of a field is of type :class:`InitVar`. If a field is an :class:" -"`InitVar`, it is considered a pseudo-field called an init-only field. As it " -"is not a true field, it is not returned by the module-level :func:`fields` " -"function. Init-only fields are added as parameters to the generated :meth:" -"`~object.__init__` method, and are passed to the optional :meth:" -"`__post_init__` method. They are not otherwise used by dataclasses." -msgstr "" -":func:`dataclass` 檢查型別註解的另一個地方是確定欄位是否是僅初始化變數。它通" -"過查看欄位的型別是否為 ``dataclasses.InitVar`` 型別來執行此操作。如果一個欄位" -"是一個 ``InitVar``，它被認為是一個偽欄位，稱為 init-only 欄位。由於它不是真正" -"的欄位，因此它不會由模組級 fields 函式回傳。 Init-only 欄位作為參數新增到生成" -"的 :meth:`~object.__init__` 方法，並傳遞給可選的 :meth:`__post_init__` 方法。" -"它們不被資料類別使用。" - -#: ../../library/dataclasses.rst:625 -#, fuzzy -msgid "" -"For example, suppose a field will be initialized from a database, if a value " -"is not provided when creating the class::" -msgstr "例如，假設一個欄位將從資料庫中初始化，如果在建立類別時沒有提供值： ::" - -#: ../../library/dataclasses.rst:628 -msgid "" -"@dataclass\n" -"class C:\n" -" i: int\n" -" j: int | None = None\n" -" database: InitVar[DatabaseType | None] = None\n" -"\n" -" def __post_init__(self, database):\n" -" if self.j is None and database is not None:\n" -" self.j = database.lookup('j')\n" -"\n" -"c = C(10, database=my_database)" -msgstr "" -"@dataclass\n" -"class C:\n" -" i: int\n" -" j: int | None = None\n" -" database: InitVar[DatabaseType | None] = None\n" -"\n" -" def __post_init__(self, database):\n" -" if self.j is None and database is not None:\n" -" self.j = database.lookup('j')\n" -"\n" -"c = C(10, database=my_database)" - -#: ../../library/dataclasses.rst:640 -#, fuzzy -msgid "" -"In this case, :func:`fields` will return :class:`Field` objects for :attr:`!" -"i` and :attr:`!j`, but not for :attr:`!database`." -msgstr "" -"在這種情況下，:func:`fields` 將為 :attr:`!i` 和 :attr:`!j` 回傳 :class:" -"`Field` 物件，但不會為 :attr:`!database` 回傳。" - -#: ../../library/dataclasses.rst:646 -msgid "Frozen instances" -msgstr "凍結實例" - -#: ../../library/dataclasses.rst:648 -#, fuzzy -msgid "" -"It is not possible to create truly immutable Python objects. However, by " -"passing ``frozen=True`` to the :deco:`dataclass` decorator you can emulate " -"immutability. In that case, dataclasses will add :meth:`~object." -"__setattr__` and :meth:`~object.__delattr__` methods to the class. These " -"methods will raise a :exc:`FrozenInstanceError` when invoked." -msgstr "" -"不可能建立真正不可變的 Python 物件。但是，透過將 ``frozen=True`` 傳遞給 :" -"func:`@dataclass ` 裝飾器，你可以模擬不變性。在這種情況下，資料類" -"別將向類別新增 :meth:`~object.__setattr__` 和 :meth:`~object.__delattr__` 方" -"法。這些方法在叫用時會引發 :exc:`FrozenInstanceError`。" - -#: ../../library/dataclasses.rst:654 -#, fuzzy -msgid "" -"There is a tiny performance penalty when using ``frozen=True``: :meth:" -"`~object.__init__` cannot use simple assignment to initialize fields, and " -"must use :meth:`!object.__setattr__`." -msgstr "" -"使用 ``frozen=True`` 時有一個微小的性能損失：:meth:`~object.__init__` 不能使" -"用簡單賦值來初始化欄位，必須使用 :meth:`!object.__setattr__`。" - -#: ../../library/dataclasses.rst:663 -msgid "Inheritance" -msgstr "繼承" - -#: ../../library/dataclasses.rst:665 -#, fuzzy -msgid "" -"When the dataclass is being created by the :deco:`dataclass` decorator, it " -"looks through all of the class's base classes in reverse MRO (that is, " -"starting at :class:`object`) and, for each dataclass that it finds, adds the " -"fields from that base class to an ordered mapping of fields. After all of " -"the base class fields are added, it adds its own fields to the ordered " -"mapping. All of the generated methods will use this combined, calculated " -"ordered mapping of fields. Because the fields are in insertion order, " -"derived classes override base classes. An example::" -msgstr "" -"當 :func:`@dataclass ` 裝飾器建立資料類別時，它會以反向 MRO（即" -"從 :class:`object` 開始）查看該類別的所有基底類別，並且對於它找到的每個資料類" -"別，將該基底類別中的欄位新增到欄位的有序對映中。新增所有基底類別欄位後，它會" -"將自己的欄位新增到有序對映中。所有生成的方法都將使用這種組合的、計算的有序欄" -"位對映。因為欄位是按插入順序排列的，所以衍生類別會覆蓋基底類別。一個例子： ::" - -#: ../../library/dataclasses.rst:675 -msgid "" -"@dataclass\n" -"class Base:\n" -" x: Any = 15.0\n" -" y: int = 0\n" -"\n" -"@dataclass\n" -"class C(Base):\n" -" z: int = 10\n" -" x: int = 15" -msgstr "" -"@dataclass\n" -"class Base:\n" -" x: Any = 15.0\n" -" y: int = 0\n" -"\n" -"@dataclass\n" -"class C(Base):\n" -" z: int = 10\n" -" x: int = 15" - -#: ../../library/dataclasses.rst:685 -#, fuzzy -msgid "" -"The final list of fields is, in order, :attr:`!x`, :attr:`!y`, :attr:`!z`. " -"The final type of :attr:`!x` is :class:`int`, as specified in class :class:`!" -"C`." -msgstr "" -"最終的欄位列表按順序為 :attr:`!x`、:attr:`!y`、:attr:`!z`。:attr:`!x` 的最終" -"型別是 :class:`int`，如類別 :class:`!C` 中指定的那樣。" - -#: ../../library/dataclasses.rst:688 -#, fuzzy -msgid "" -"The generated :meth:`~object.__init__` method for :class:`!C` will look " -"like::" -msgstr "為 :class:`!C` 生成的 :meth:`~object.__init__` 方法將如下所示： ::" - -#: ../../library/dataclasses.rst:690 -msgid "def __init__(self, x: int = 15, y: int = 0, z: int = 10):" -msgstr "def __init__(self, x: int = 15, y: int = 0, z: int = 10):" - -#: ../../library/dataclasses.rst:693 -#, fuzzy -msgid "Re-ordering of keyword-only parameters in :meth:`!__init__`" -msgstr ":meth:`!__init__` 中僅關鍵字參數的重新排序" - -#: ../../library/dataclasses.rst:695 -#, fuzzy -msgid "" -"After the parameters needed for :meth:`~object.__init__` are computed, any " -"keyword-only parameters are moved to come after all regular (non-keyword-" -"only) parameters. This is a requirement of how keyword-only parameters are " -"implemented in Python: they must come after non-keyword-only parameters." -msgstr "" -"在計算 :meth:`__init__` 所需的參數後，任何僅關鍵字參數都將移動到所有常規（非" -"僅關鍵字）參數之後。這是如何在 Python 中實作僅關鍵字參數的要求：它們必須位於" -"非僅關鍵字參數之後。" - -#: ../../library/dataclasses.rst:701 -#, fuzzy -msgid "" -"In this example, :attr:`!Base.y`, :attr:`!Base.w`, and :attr:`!D.t` are " -"keyword-only fields, and :attr:`!Base.x` and :attr:`!D.z` are regular " -"fields::" -msgstr "" -"在此示例中，:attr:`!Base.y`、:attr:`!Base.w` 和 :attr:`!D.t` 是僅限關鍵字的欄" -"位，:attr:`!Base.x` 和 :attr:`!D.z` 是常規欄位： ::" - -#: ../../library/dataclasses.rst:704 -msgid "" -"@dataclass\n" -"class Base:\n" -" x: Any = 15.0\n" -" _: KW_ONLY\n" -" y: int = 0\n" -" w: int = 1\n" -"\n" -"@dataclass\n" -"class D(Base):\n" -" z: int = 10\n" -" t: int = field(kw_only=True, default=0)" -msgstr "" -"@dataclass\n" -"class Base:\n" -" x: Any = 15.0\n" -" _: KW_ONLY\n" -" y: int = 0\n" -" w: int = 1\n" -"\n" -"@dataclass\n" -"class D(Base):\n" -" z: int = 10\n" -" t: int = field(kw_only=True, default=0)" - -#: ../../library/dataclasses.rst:716 -#, fuzzy -msgid "The generated :meth:`!__init__` method for :class:`!D` will look like::" -msgstr "為 :class:`!D` 生成的 :meth:`!__init__` 方法將如下所示： ::" - -#: ../../library/dataclasses.rst:718 -msgid "" -"def __init__(self, x: Any = 15.0, z: int = 10, *, y: int = 0, w: int = 1, t: " -"int = 0):" -msgstr "" -"def __init__(self, x: Any = 15.0, z: int = 10, *, y: int = 0, w: int = 1, t: " -"int = 0):" - -#: ../../library/dataclasses.rst:720 -#, fuzzy -msgid "" -"Note that the parameters have been re-ordered from how they appear in the " -"list of fields: parameters derived from regular fields are followed by " -"parameters derived from keyword-only fields." -msgstr "" -"請注意，參數已根據它們在欄位列表中的顯示方式重新排序：從常規欄位衍生的參數後" -"跟從僅關鍵字欄位衍生的參數。" - -#: ../../library/dataclasses.rst:724 -#, fuzzy -msgid "" -"The relative ordering of keyword-only parameters is maintained in the re-" -"ordered :meth:`!__init__` parameter list." -msgstr "僅關鍵字參數的相對順序在重新排序的 :meth:`!__init__` 參數列表中維護。" - -#: ../../library/dataclasses.rst:729 -msgid "Default factory functions" -msgstr "預設工廠函式" - -#: ../../library/dataclasses.rst:731 -#, fuzzy -msgid "" -"If a :func:`field` specifies a *default_factory*, it is called with zero " -"arguments when a default value for the field is needed. For example, to " -"create a new instance of a list, use::" -msgstr "" -"如果 :func:`field` 指定了 *default_factory*，當需要該欄位的預設值時，它會以零" -"引數呼叫。例如，要建立列表的新實例，請使用： ::" - -#: ../../library/dataclasses.rst:735 -msgid "mylist: list = field(default_factory=list)" -msgstr "mylist: list = field(default_factory=list)" - -#: ../../library/dataclasses.rst:737 -#, fuzzy -msgid "" -"If a field is excluded from :meth:`~object.__init__` (using ``init=False``) " -"and the field also specifies *default_factory*, then the default factory " -"function will always be called from the generated :meth:`!__init__` " -"function. This happens because there is no other way to give the field an " -"initial value." -msgstr "" -"如果一個欄位從 :meth:`~object.__init__` 中排除（使用 ``init=False``）並且該欄" -"位還指定了 ``default_factory``，那麼預設工廠函式將始終從生成的 :meth:" -"`__init__ 中呼叫`功能。發生這種情況是因為沒有其他方法可以為該欄位賦予初始值。" - -#: ../../library/dataclasses.rst:744 -msgid "Mutable default values" -msgstr "可變預設值" - -#: ../../library/dataclasses.rst:746 -#, fuzzy -msgid "" -"Python stores default member variable values in class attributes. Consider " -"this example, not using dataclasses::" -msgstr "" -"Python 將預設成員變數值儲存在類別屬性中。考慮這個例子，不使用資料類別： ::" - -#: ../../library/dataclasses.rst:749 -msgid "" -"class C:\n" -" x = []\n" -" def add(self, element):\n" -" self.x.append(element)\n" -"\n" -"o1 = C()\n" -"o2 = C()\n" -"o1.add(1)\n" -"o2.add(2)\n" -"assert o1.x == [1, 2]\n" -"assert o1.x is o2.x" -msgstr "" -"class C:\n" -" x = []\n" -" def add(self, element):\n" -" self.x.append(element)\n" -"\n" -"o1 = C()\n" -"o2 = C()\n" -"o1.add(1)\n" -"o2.add(2)\n" -"assert o1.x == [1, 2]\n" -"assert o1.x is o2.x" - -#: ../../library/dataclasses.rst:761 -#, fuzzy -msgid "" -"Note that the two instances of class :class:`!C` share the same class " -"variable :attr:`!x`, as expected." -msgstr "" -"請注意，類別 :class:`!C` 的兩個實例共享同一個類別變數 :attr:`!x`，正如預期的" -"那樣。" - -#: ../../library/dataclasses.rst:764 -#, fuzzy -msgid "Using dataclasses, *if* this code was valid::" -msgstr "使用資料類別，*如果*\\ 此程式碼有效： ::" - -#: ../../library/dataclasses.rst:766 -msgid "" -"@dataclass\n" -"class D:\n" -" x: list = [] # This code raises ValueError\n" -" def add(self, element):\n" -" self.x.append(element)" -msgstr "" -"@dataclass\n" -"class D:\n" -" x: list = [] # 這段程式碼會引發 ValueError\n" -" def add(self, element):\n" -" self.x.append(element)" - -#: ../../library/dataclasses.rst:772 -msgid "it would generate code similar to::" -msgstr "它會生成類似的程式碼： ::" - -#: ../../library/dataclasses.rst:774 -msgid "" -"class D:\n" -" x = []\n" -" def __init__(self, x=x):\n" -" self.x = x\n" -" def add(self, element):\n" -" self.x.append(element)\n" -"\n" -"assert D().x is D().x" -msgstr "" -"class D:\n" -" x = []\n" -" def __init__(self, x=x):\n" -" self.x = x\n" -" def add(self, element):\n" -" self.x.append(element)\n" -"\n" -"assert D().x is D().x" - -#: ../../library/dataclasses.rst:783 -#, fuzzy -msgid "" -"This has the same issue as the original example using class :class:`!C`. " -"That is, two instances of class :class:`!D` that do not specify a value for :" -"attr:`!x` when creating a class instance will share the same copy of :attr:`!" -"x`. Because dataclasses just use normal Python class creation they also " -"share this behavior. There is no general way for Data Classes to detect " -"this condition. Instead, the :deco:`dataclass` decorator will raise a :exc:" -"`ValueError` if it detects an unhashable default parameter. The assumption " -"is that if a value is unhashable, it is mutable. This is a partial " -"solution, but it does protect against many common errors." -msgstr "" -"這與使用類別 :class:`!C` 的原始示例存在相同的問題。也就是說，類別 :class:`!" -"D` 的兩個實例在建立類別實例時沒有為 :attr:`!x` 指定值，它們將共享 :attr:`!x` " -"的同一個副本。因為資料類別只是使用普通的 Python 類別建立，所以它們也有這種行" -"為。資料類別沒有通用的方法來檢測這種情況。相反，如果 :func:`dataclass` 裝飾器" -"檢測到不可雜湊的預設參數，它將引發 :exc:`TypeError`。假設是如果一個值是不可散" -"列的，那麼它就是可變的。這是一個部分解決方案，但它確實可以防止許多常見錯誤。" - -#: ../../library/dataclasses.rst:794 -#, fuzzy -msgid "" -"Using default factory functions is a way to create new instances of mutable " -"types as default values for fields::" -msgstr "使用預設工廠函式是一種建立可變型別的新實例作為欄位預設值的方法： ::" - -#: ../../library/dataclasses.rst:797 -msgid "" -"@dataclass\n" -"class D:\n" -" x: list = field(default_factory=list)\n" -"\n" -"assert D().x is not D().x" -msgstr "" -"@dataclass\n" -"class D:\n" -" x: list = field(default_factory=list)\n" -"\n" -"assert D().x is not D().x" - -#: ../../library/dataclasses.rst:803 -#, fuzzy -msgid "" -"Instead of looking for and disallowing objects of type :class:`list`, :class:" -"`dict`, or :class:`set`, unhashable objects are now not allowed as default " -"values. Unhashability is used to approximate mutability." -msgstr "" -"不再查找和禁止型別為 :class:`list`、:class:`dict` 或 :class:`set` 的物件，現" -"在不允許使用不可雜湊的物件作為預設值。不可雜湊性用於近似可變性。" - -#: ../../library/dataclasses.rst:810 -#, fuzzy -msgid "Descriptor-typed fields" -msgstr "描述器型別的欄位" - -#: ../../library/dataclasses.rst:812 -#, fuzzy -msgid "" -"Fields that are assigned :ref:`descriptor objects ` as their " -"default value have the following special behaviors:" -msgstr "" -"指定為\\ :ref:`描述器物件 `\\ 作為預設值的欄位具有以下特殊行為：" - -#: ../../library/dataclasses.rst:815 -#, fuzzy -msgid "" -"The value for the field passed to the dataclass's :meth:`~object.__init__` " -"method is passed to the descriptor's :meth:`~object.__set__` method rather " -"than overwriting the descriptor object." -msgstr "" -"傳遞給資料類別的 :meth:`~object.__init__` 方法的欄位值被傳遞給描述器的 :meth:" -"`~object.__set__` 方法，而不是覆蓋描述器物件。" - -#: ../../library/dataclasses.rst:819 -#, fuzzy -msgid "" -"Similarly, when getting or setting the field, the descriptor's :meth:" -"`~object.__get__` or :meth:`!__set__` method is called rather than returning " -"or overwriting the descriptor object." -msgstr "" -"同樣，在取得或設定欄位時，將呼叫描述器的 :meth:`~object.__get__` 或 :meth:`!" -"__set__` 方法，而不是回傳或覆蓋描述器物件。" - -#: ../../library/dataclasses.rst:823 -#, fuzzy -msgid "" -"To determine whether a field contains a default value, :deco:`dataclass` " -"will call the descriptor's :meth:`!__get__` method using its class access " -"form: ``descriptor.__get__(obj=None, type=cls)``. If the descriptor returns " -"a value in this case, it will be used as the field's default. On the other " -"hand, if the descriptor raises :exc:`AttributeError` in this situation, no " -"default value will be provided for the field." -msgstr "" -"為了確定一個欄位是否包含預設值，:func:`@dataclass ` 將使用其類別存" -"取形式呼叫描述器的 :meth:`!__get__` 方法（即 ``descriptor.__get__(obj=None, " -"type=cls)``。如果在這種情況下，描述器回傳一個值，它將用作欄位的預設值。另一方" -"面，如果描述器在這種情況下引發 :exc:`AttributeError`，則不會為該欄位提供預設" -"值。" - -#: ../../library/dataclasses.rst:833 -msgid "" -"class IntConversionDescriptor:\n" -" def __init__(self, *, default):\n" -" self._default = default\n" -"\n" -" def __set_name__(self, owner, name):\n" -" self._name = \"_\" + name\n" -"\n" -" def __get__(self, obj, type):\n" -" if obj is None:\n" -" return self._default\n" -"\n" -" return getattr(obj, self._name, self._default)\n" -"\n" -" def __set__(self, obj, value):\n" -" setattr(obj, self._name, int(value))\n" -"\n" -"@dataclass\n" -"class InventoryItem:\n" -" quantity_on_hand: IntConversionDescriptor = " -"IntConversionDescriptor(default=100)\n" -"\n" -"i = InventoryItem()\n" -"print(i.quantity_on_hand) # 100\n" -"i.quantity_on_hand = 2.5 # calls __set__ with 2.5\n" -"print(i.quantity_on_hand) # 2" -msgstr "" -"class IntConversionDescriptor:\n" -" def __init__(self, *, default):\n" -" self._default = default\n" -"\n" -" def __set_name__(self, owner, name):\n" -" self._name = \"_\" + name\n" -"\n" -" def __get__(self, obj, type):\n" -" if obj is None:\n" -" return self._default\n" -"\n" -" return getattr(obj, self._name, self._default)\n" -"\n" -" def __set__(self, obj, value):\n" -" setattr(obj, self._name, int(value))\n" -"\n" -"@dataclass\n" -"class InventoryItem:\n" -" quantity_on_hand: IntConversionDescriptor = " -"IntConversionDescriptor(default=100)\n" -"\n" -"i = InventoryItem()\n" -"print(i.quantity_on_hand) # 100\n" -"i.quantity_on_hand = 2.5 # 以 2.5 呼叫 __set__\n" -"print(i.quantity_on_hand) # 2" - -#: ../../library/dataclasses.rst:858 -#, fuzzy -msgid "" -"Note that if a field is annotated with a descriptor type, but is not " -"assigned a descriptor object as its default value, the field will act like a " -"normal field." -msgstr "" -"請注意，如果一個欄位用描述器型別註釋，但未分配描述器物件作為其預設值，則該欄" -"位將像普通欄位一樣工作。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-10-08 00:15+0000\n" +"PO-Revision-Date: 2023-02-11 15:02+0800\n" +"Last-Translator: \n" +"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" +"tw)\n" +"Language: zh_TW\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"X-Generator: Poedit 3.2.2\n" + +#: ../../library/dataclasses.rst:2 +msgid ":mod:`!dataclasses` --- Data Classes" +msgstr ":mod:`!dataclasses` --- Data Classes" + +#: ../../library/dataclasses.rst:10 +msgid "**Source code:** :source:`Lib/dataclasses.py`" +msgstr "**原始碼：**\\ :source:`Lib/dataclasses.py`" + +#: ../../library/dataclasses.rst:14 +#, fuzzy +msgid "" +"This module provides a decorator and functions for automatically adding " +"generated :term:`special methods ` such as :meth:`~object." +"__init__` and :meth:`~object.__repr__` to user-defined classes. It was " +"originally described in :pep:`557`." +msgstr "" +"該模組提供了一個裝飾器和函式，用於自動新增生成的\\ :term:`特殊方法 `，例如 :meth:`~object.__init__` 和 :meth:`~object.__repr__` 到使用者" +"定義的類別。它最初在 :pep:`557` 中描述。" + +#: ../../library/dataclasses.rst:19 +#, fuzzy +msgid "" +"The member variables to use in these generated methods are defined using :" +"pep:`526` type annotations. For example, this code::" +msgstr "" +"在這些生成的方法中使用的成員變數是使用 :pep:`526` 型別註釋定義的。例如，這段" +"程式碼： ::" + +#: ../../library/dataclasses.rst:22 +msgid "" +"from dataclasses import dataclass\n" +"\n" +"@dataclass\n" +"class InventoryItem:\n" +" \"\"\"Class for keeping track of an item in inventory.\"\"\"\n" +" name: str\n" +" unit_price: float\n" +" quantity_on_hand: int = 0\n" +"\n" +" def total_cost(self) -> float:\n" +" return self.unit_price * self.quantity_on_hand" +msgstr "" + +#: ../../library/dataclasses.rst:34 +#, fuzzy +msgid "will add, among other things, a :meth:`!__init__` that looks like::" +msgstr "將新增，除其他事項外，一個 :meth:`!__init__` 看起來像： ::" + +#: ../../library/dataclasses.rst:36 +msgid "" +"def __init__(self, name: str, unit_price: float, quantity_on_hand: int = " +"0):\n" +" self.name = name\n" +" self.unit_price = unit_price\n" +" self.quantity_on_hand = quantity_on_hand" +msgstr "" +"def __init__(self, name: str, unit_price: float, quantity_on_hand: int = " +"0):\n" +" self.name = name\n" +" self.unit_price = unit_price\n" +" self.quantity_on_hand = quantity_on_hand" + +#: ../../library/dataclasses.rst:41 +#, fuzzy +msgid "" +"Note that this method is automatically added to the class: it is not " +"directly specified in the :class:`!InventoryItem` definition shown above." +msgstr "" +"請注意，此方法會自動新增到類別中：它不會在上面顯示的 :class:`!InventoryItem` " +"定義中直接指定。" + +#: ../../library/dataclasses.rst:47 +msgid "Module contents" +msgstr "模組內容" + +#: ../../library/dataclasses.rst:51 +#, fuzzy +msgid "" +"This function is a :term:`decorator` that is used to add generated :term:" +"`special methods ` to classes, as described below." +msgstr "" +"此函式是一個 :term:`decorator`，用於將生成的\\ :term:`特殊方法 `\\新增到類別中，如下所述。" + +#: ../../library/dataclasses.rst:54 +#, fuzzy +msgid "" +"The ``@dataclass`` decorator examines the class to find ``field``\\s. A " +"``field`` is defined as a class variable that has a :term:`type annotation " +"`. With two exceptions described below, nothing in " +"``@dataclass`` examines the type specified in the variable annotation." +msgstr "" +"``@dataclass`` 裝飾器檢查類別以找到 ``field``\\s。 ``field`` 被定義為具有 :" +"term:`type annotation ` 的類別變數。除了下面描述的兩個例" +"外，``@dataclass`` 中沒有任何內容檢查變數註釋中指定的型別。" + +#: ../../library/dataclasses.rst:60 +#, fuzzy +msgid "" +"The order of the fields in all of the generated methods is the order in " +"which they appear in the class definition." +msgstr "所有生成的方法中欄位的順序是它們在類別定義中出現的順序。" + +#: ../../library/dataclasses.rst:63 +msgid "" +"The ``@dataclass`` decorator will add various \"dunder\" methods to the " +"class, described below. If any of the added methods already exist in the " +"class, the behavior depends on the parameter, as documented below. The " +"decorator returns the same class that it is called on; no new class is " +"created." +msgstr "" +"如下所述，``@dataclass`` 裝飾器會向類別新增各種 \"dunder\" 方法。如果類別中已" +"存在任何新增的方法，則行為會取決於參數，如下方文件所述。裝飾器會回傳呼叫它的" +"同一個類別；不會建立新類別。" + +#: ../../library/dataclasses.rst:69 +#, fuzzy +msgid "" +"If ``@dataclass`` is used just as a simple decorator with no parameters, it " +"acts as if it has the default values documented in this signature. That is, " +"these three uses of ``@dataclass`` are equivalent::" +msgstr "" +"如果 ``@dataclass`` 僅用作不帶參數的簡單裝飾器，它的行為就好像它具有此簽名中" +"記錄的預設值一樣。也就是說，``@dataclass`` 的這三種用法是等價的： ::" + +#: ../../library/dataclasses.rst:74 +msgid "" +"@dataclass\n" +"class C:\n" +" ...\n" +"\n" +"@dataclass()\n" +"class C:\n" +" ...\n" +"\n" +"@dataclass(init=True, repr=True, eq=True, order=False, unsafe_hash=False, " +"frozen=False,\n" +" match_args=True, kw_only=False, slots=False, weakref_slot=False)\n" +"class C:\n" +" ..." +msgstr "" +"@dataclass\n" +"class C:\n" +" ...\n" +"\n" +"@dataclass()\n" +"class C:\n" +" ...\n" +"\n" +"@dataclass(init=True, repr=True, eq=True, order=False, unsafe_hash=False, " +"frozen=False,\n" +" match_args=True, kw_only=False, slots=False, weakref_slot=False)\n" +"class C:\n" +" ..." + +#: ../../library/dataclasses.rst:87 +msgid "The parameters to ``@dataclass`` are:" +msgstr "``@dataclass`` 的參數是：" + +#: ../../library/dataclasses.rst:89 +msgid "" +"*init*: If true (the default), a :meth:`~object.__init__` method will be " +"generated." +msgstr "*init*：如果為真（預設值），將生成一個 :meth:`~object.__init__` 方法。" + +#: ../../library/dataclasses.rst:92 +msgid "" +"If the class already defines :meth:`!__init__`, this parameter is ignored." +msgstr "如果該類別已經定義了 :meth:`!__init__`，則此參數會被忽略。" + +#: ../../library/dataclasses.rst:95 +#, fuzzy +msgid "" +"*repr*: If true (the default), a :meth:`~object.__repr__` method will be " +"generated. The generated repr string will have the class name and the name " +"and repr of each field, in the order they are defined in the class. Fields " +"that are marked as being excluded from the repr are not included. For " +"example: ``InventoryItem(name='widget', unit_price=3.0, " +"quantity_on_hand=10)``." +msgstr "" +"*repr*：如果為真（預設值），將生成一個 :meth:`__repr__` 方法。生成的 repr 字" +"串將包含類別名稱以及每個欄位的名稱和 repr，按照它們在類別中定義的順序排列。不" +"包括標記為從 repr 中排除的欄位。例如：``InventoryItem(name='widget', " +"unit_price=3.0, quantity_on_hand=10)``。" + +#: ../../library/dataclasses.rst:102 +msgid "" +"If the class already defines :meth:`!__repr__`, this parameter is ignored." +msgstr "如果該類別已經定義了 :meth:`!__repr__`，則此參數會被忽略。" + +#: ../../library/dataclasses.rst:105 +#, fuzzy +msgid "" +"*eq*: If true (the default), an :meth:`~object.__eq__` method will be " +"generated. This method compares the class as if it were a tuple of its " +"fields, in order. Both instances in the comparison must be of the identical " +"type." +msgstr "" +"*eq*：如果為真（預設值），將生成一個 :meth:`~object.__eq__` 方法。此方法按順" +"序比較類別，就好像它是其欄位的元組一樣。比較中的兩個實例必須屬於同一型別。" + +#: ../../library/dataclasses.rst:110 +msgid "" +"If the class already defines :meth:`!__eq__`, this parameter is ignored." +msgstr "如果該類別已經定義了 :meth:`!__eq__`，則此參數會被忽略。" + +#: ../../library/dataclasses.rst:113 +#, fuzzy +msgid "" +"*order*: If true (the default is ``False``), :meth:`~object.__lt__`, :meth:" +"`~object.__le__`, :meth:`~object.__gt__`, and :meth:`~object.__ge__` methods " +"will be generated. These compare the class as if it were a tuple of its " +"fields, in order. Both instances in the comparison must be of the identical " +"type. If *order* is true and *eq* is false, a :exc:`ValueError` is raised." +msgstr "" +"*order*：如果為真（預設為 ``False``），:meth:`~object.__lt__`、:meth:" +"`~object.__le__`、:meth:`~object.__gt__` 和 :meth:`~object.__ge__` 方法將是產" +"生。它們按順序比較類別，就好像它是其欄位的元組一樣。比較中的兩個實例必須屬於" +"同一型別。如果 *order* 為真且 *eq* 為假，則會引發 :exc:`ValueError`。" + +#: ../../library/dataclasses.rst:120 +msgid "" +"If the class already defines any of :meth:`!__lt__`, :meth:`!__le__`, :meth:" +"`!__gt__`, or :meth:`!__ge__`, then :exc:`TypeError` is raised." +msgstr "" +"如果該類別已經定義了 :meth:`!__lt__`、:meth:`!__le__`、:meth:`!__gt__` 或 :" +"meth:`!__ge__` 中的任何一個，則引發 :exc:`TypeError`。" + +#: ../../library/dataclasses.rst:124 +#, fuzzy +msgid "" +"*unsafe_hash*: If true, force ``dataclasses`` to create a :meth:`~object." +"__hash__` method, even though it may not be safe to do so. Otherwise, " +"generate a :meth:`~object.__hash__` method according to how *eq* and " +"*frozen* are set. The default value is ``False``." +msgstr "" +"*unsafe_hash*：如果 ``False``\\ （預設值），將根據 *eq* 和 *frozen* 的設定生成一" +"個 :meth:`~object.__hash__` 方法。" + +#: ../../library/dataclasses.rst:130 +#, fuzzy +msgid "" +":meth:`!__hash__` is used by built-in :meth:`hash`, and when objects are " +"added to hashed collections such as dictionaries and sets. Having a :meth:`!" +"__hash__` implies that instances of the class are immutable. Mutability is a " +"complicated property that depends on the programmer's intent, the existence " +"and behavior of :meth:`!__eq__`, and the values of the *eq* and *frozen* " +"flags in the ``@dataclass`` decorator." +msgstr "" +":meth:`!__hash__` 由內建的 :meth:`hash` 使用，當物件被新增到雜湊集合（如字典" +"和集合）時。擁有 :meth:`!__hash__` 意味著該類別的實例是不可變的。可變性是一個" +"複雜的屬性，它取決於程序設計師的意圖 :meth:`!__eq__` 的存在和行為，以及 " +"dataclass 裝飾器中的 *eq* 和 *frozen* 旗標的值." + +#: ../../library/dataclasses.rst:137 +#, fuzzy +msgid "" +"By default, ``@dataclass`` will not implicitly add a :meth:`~object." +"__hash__` method unless it is safe to do so. Neither will it add or change " +"an existing explicitly defined :meth:`!__hash__` method. Setting the class " +"attribute ``__hash__ = None`` has a specific meaning to Python, as described " +"in the :meth:`!__hash__` documentation." +msgstr "" +"預設情況下，``@dataclass`` 不會隱式新增 :meth:`~object.__hash__` 方法，除非這" +"樣做是安全的。它也不會新增或更改現有的明確定義的 :meth:`!__hash__` 方法。設定" +"類別屬性 ``__hash__ = None`` 對 Python 具有特定含義，如 :meth:`!__hash__` 文" +"件中所述。" + +#: ../../library/dataclasses.rst:143 +#, fuzzy +msgid "" +"If :meth:`!__hash__` is not explicitly defined, or if it is set to ``None``, " +"then ``@dataclass`` *may* add an implicit :meth:`!__hash__` method. Although " +"not recommended, you can force ``@dataclass`` to create a :meth:`!__hash__` " +"method with ``unsafe_hash=True``. This might be the case if your class is " +"logically immutable but can still be mutated. This is a specialized use case " +"and should be considered carefully." +msgstr "" +"如果 :meth:`!__hash__` 沒有明確定義，或者如果它被設定為 ``None``，那麼 " +"``@dataclass`` *可能* 新增一個隱式的 :meth:`!__hash__` 方法。雖然不推薦，但你" +"可以強制 ``@dataclass`` 使用 ``unsafe_hash=True`` 建立一個 :meth:`!__hash__` " +"方法。如果你的類別在邏輯上是不可變的但仍然可以改變，則可能是這種情況。這是一" +"個特殊的用例，應該仔細考慮。" + +#: ../../library/dataclasses.rst:150 +#, fuzzy +msgid "" +"Here are the rules governing implicit creation of a :meth:`!__hash__` " +"method. Note that you cannot both have an explicit :meth:`!__hash__` method " +"in your dataclass and set ``unsafe_hash=True``; this will result in a :exc:" +"`TypeError`." +msgstr "" +"以下是管理隱式建立 :meth:`!__hash__` 方法的規則。請注意，你不能在資料類別中既" +"有顯式的 :meth:`!__hash__` 方法又設定 ``unsafe_hash=True``；這將導致 :exc:" +"`TypeError`。" + +#: ../../library/dataclasses.rst:155 +msgid "" +"If *eq* and *frozen* are both true, by default ``@dataclass`` will generate " +"a :meth:`!__hash__` method for you. If *eq* is true and *frozen* is false, :" +"meth:`!__hash__` will be set to ``None``, marking it unhashable (which it " +"is, since it is mutable). If *eq* is false, :meth:`!__hash__` will be left " +"untouched meaning the :meth:`!__hash__` method of the superclass will be " +"used (if the superclass is :class:`object`, this means it will fall back to " +"id-based hashing)." +msgstr "" +"如果 *eq* 和 *frozen* 都為真，預設情況下 ``@dataclass`` 會為你生成一個 :meth:" +"`!__hash__` 方法。如果 *eq* 為真且 *frozen* 為假，:meth:`!__hash__` 將被設定" +"為 ``None``，並將其標記為不可雜湊（因為它是可變的）。如果 *eq* 為假，:meth:`!" +"__hash__` 將保持不變，這意味著將使用超類別的 :meth:`!__hash__` 方法（如果超類" +"別是 :class:`object`，這意味著它將回退到基於 id 的雜湊）。" + +#: ../../library/dataclasses.rst:163 +#, fuzzy +msgid "" +"*frozen*: If true (the default is ``False``), assigning to fields will " +"generate an exception. This emulates read-only frozen instances. See the :" +"ref:`discussion ` below." +msgstr "" +"*frozen*：如果為真（預設為 ``False``），分配給欄位將產生例外。這模擬了只讀的" +"凍結實例。如果 :meth:`~object.__setattr__` 或 :meth:`~object.__delattr__` 在" +"類別中定義，則 :exc:`TypeError` 被引發。請參閱下面的討論。" + +#: ../../library/dataclasses.rst:167 +msgid "" +"If :meth:`~object.__setattr__` or :meth:`~object.__delattr__` is defined in " +"the class and *frozen* is true, then :exc:`TypeError` is raised." +msgstr "" +"如果類別中定義了 :meth:`~object.__setattr__` 或 :meth:`~object.__delattr__` " +"且 *frozen* 為真，則會引發 :exc:`TypeError`。" + +#: ../../library/dataclasses.rst:170 +#, fuzzy +msgid "" +"*match_args*: If true (the default is ``True``), the :attr:`~object." +"__match_args__` tuple will be created from the list of non keyword-only " +"parameters to the generated :meth:`~object.__init__` method (even if :meth:`!" +"__init__` is not generated, see above). If false, or if :attr:`!" +"__match_args__` is already defined in the class, then :attr:`!" +"__match_args__` will not be generated." +msgstr "" +"*match_args*：如果為真（預設為 ``True``），``__match_args__`` 元組將從參數列" +"表建立到生成的 :meth:`~object.__init__` 方法（即使 :meth: `!__init__` 未生" +"成，見上文）。如果為 false，或者類別中已經定義了 :attr:`!__match_args__`，則" +"不會生成 :attr:`!__match_args__`。" + +#: ../../library/dataclasses.rst:179 +#, fuzzy +msgid "" +"*kw_only*: If true (the default value is ``False``), then all fields will be " +"marked as keyword-only. If a field is marked as keyword-only, then the only " +"effect is that the :meth:`~object.__init__` parameter generated from a " +"keyword-only field must be specified with a keyword when :meth:`!__init__` " +"is called. See the :term:`parameter` glossary entry for details. Also see " +"the :const:`KW_ONLY` section." +msgstr "" +"``kw_only``：如果為 true（預設值為 ``False``），則所有欄位將被標記為僅限關鍵" +"字。如果一個欄位被標記為僅限關鍵字，那麼唯一的影響是從僅限關鍵字欄位生成的 :" +"meth:`~object.__init__` 參數必須在呼叫 :meth:`!__init__` 時指定關鍵字。對資料" +"類別的任何其他方面都沒有影響。有關詳細資訊，請參閱 :term:`parameter` 詞彙表條" +"目。另請參閱 :const:`KW_ONLY` 部分。" + +#: ../../library/dataclasses.rst:187 +msgid "Keyword-only fields are not included in :attr:`!__match_args__`." +msgstr "" + +#: ../../library/dataclasses.rst:191 +#, fuzzy +msgid "" +"*slots*: If true (the default is ``False``), :attr:`~object.__slots__` " +"attribute will be generated and new class will be returned instead of the " +"original one. If :attr:`!__slots__` is already defined in the class, then :" +"exc:`TypeError` is raised." +msgstr "" +"``slots``：如果為 true（預設為 ``False``），將生成 :attr:`~object.__slots__` " +"屬性並回傳新類別而不是原始類別。如果 :attr:`!__slots__` 已經在類別中定義，" +"則 :exc:`TypeError` 被引發。" + +#: ../../library/dataclasses.rst:197 +msgid "" +"Passing parameters to a base class :meth:`~object.__init_subclass__` when " +"using ``slots=True`` will result in a :exc:`TypeError`. Either use " +"``__init_subclass__`` with no parameters or use default values as a " +"workaround. See :gh:`91126` for full details." +msgstr "" + +#: ../../library/dataclasses.rst:205 +#, fuzzy +msgid "" +"If a field name is already included in the :attr:`!__slots__` of a base " +"class, it will not be included in the generated :attr:`!__slots__` to " +"prevent :ref:`overriding them `. Therefore, do not " +"use :attr:`!__slots__` to retrieve the field names of a dataclass. Use :func:" +"`fields` instead. To be able to determine inherited slots, base class :attr:" +"`!__slots__` may be any iterable, but *not* an iterator." +msgstr "" +"如果欄位名稱已經包含在基底類別的 :attr:`!__slots__` 中，它將不會包含在生成" +"的 :attr:`!__slots__` 中以防止 :ref:`覆蓋它們 `。因此，" +"不要使用 __slots__ 來檢索資料類別的欄位名稱。使用 :func:`fields` 代替。為了能" +"夠確定繼承的插槽，基底類別 :attr:`!__slots__` 可以是任何可疊代的，但*不是*疊" +"代器。" + +#: ../../library/dataclasses.rst:215 +#, fuzzy +msgid "" +"*weakref_slot*: If true (the default is ``False``), add a slot named " +"\"__weakref__\", which is required to make an instance :func:`weakref-able " +"`. It is an error to specify ``weakref_slot=True`` without also " +"specifying ``slots=True``." +msgstr "" +"*weakref_slot*：如果為真（預設為 ``False``），新增一個名為 \"__weakref__\" 的" +"插槽，這是使實例可弱引用所必需的。在沒有指定 ``slots=True`` 的情況下指定 " +"``weakref_slot=True`` 是錯誤的。" + +#: ../../library/dataclasses.rst:223 +#, fuzzy +msgid "" +"``field``\\s may optionally specify a default value, using normal Python " +"syntax::" +msgstr "``field``\\s 可以選擇指定一個預設值，使用普通的 Python 語法： ::" + +#: ../../library/dataclasses.rst:226 +msgid "" +"@dataclass\n" +"class C:\n" +" a: int # 'a' has no default value\n" +" b: int = 0 # assign a default value for 'b'" +msgstr "" + +#: ../../library/dataclasses.rst:231 +#, fuzzy +msgid "" +"In this example, both :attr:`!a` and :attr:`!b` will be included in the " +"added :meth:`~object.__init__` method, which will be defined as::" +msgstr "" +"在此示例中，:attr:`!a` 和 :attr:`!b` 都將包含在新增的 :meth:`~object." +"__init__` 方法中，該方法將定義為： ::" + +#: ../../library/dataclasses.rst:234 +msgid "def __init__(self, a: int, b: int = 0):" +msgstr "def __init__(self, a: int, b: int = 0):" + +#: ../../library/dataclasses.rst:236 +#, fuzzy +msgid "" +":exc:`TypeError` will be raised if a field without a default value follows a " +"field with a default value. This is true whether this occurs in a single " +"class, or as a result of class inheritance." +msgstr "" +":exc:`TypeError` 如果沒有預設值的欄位跟在具有預設值的欄位之後，將引發。無論這" +"發生在單個類別中還是作為類別繼承的結果，都是如此。" + +#: ../../library/dataclasses.rst:242 +#, fuzzy +msgid "" +"For common and simple use cases, no other functionality is required. There " +"are, however, some dataclass features that require additional per-field " +"information. To satisfy this need for additional information, you can " +"replace the default field value with a call to the provided :func:`!field` " +"function. For example::" +msgstr "" +"對於常見和簡單的用例，不需要其他功能。但是，有些資料類別功能需要額外的每個欄" +"位資訊。為了滿足這種對附加資訊的需求，你可以透過呼叫提供的 :func:`!field` 函" +"式來替換預設欄位值。例如： ::" + +#: ../../library/dataclasses.rst:248 +msgid "" +"@dataclass\n" +"class C:\n" +" mylist: list[int] = field(default_factory=list)\n" +"\n" +"c = C()\n" +"c.mylist += [1, 2, 3]" +msgstr "" +"@dataclass\n" +"class C:\n" +" mylist: list[int] = field(default_factory=list)\n" +"\n" +"c = C()\n" +"c.mylist += [1, 2, 3]" + +#: ../../library/dataclasses.rst:255 +#, fuzzy +msgid "" +"As shown above, the :const:`MISSING` value is a sentinel object used to " +"detect if some parameters are provided by the user. This sentinel is used " +"because ``None`` is a valid value for some parameters with a distinct " +"meaning. No code should directly use the :const:`MISSING` value." +msgstr "" +"如上所示，:const:`MISSING` 值是一個哨兵物件，用於檢測某些參數是否由使用者提" +"供。使用此標記是因為 ``None`` 對於某些具有不同含義的參數是有效值。任何程式碼" +"都不應直接使用 :const:`MISSING` 值。" + +#: ../../library/dataclasses.rst:260 +msgid "The parameters to :func:`!field` are:" +msgstr ":func:`!field` 的參數是：" + +#: ../../library/dataclasses.rst:262 +msgid "" +"*default*: If provided, this will be the default value for this field. This " +"is needed because the :func:`!field` call itself replaces the normal " +"position of the default value." +msgstr "" +"*default*：如果有提供，這將是該欄位的預設值。這是必需的，因為 :meth:`!field` " +"呼叫本身會替換預設值的正常位置。" + +#: ../../library/dataclasses.rst:266 +#, fuzzy +msgid "" +"*default_factory*: If provided, it must be a zero-argument callable that " +"will be called when a default value is needed for this field. Among other " +"purposes, this can be used to specify fields with mutable default values, as " +"discussed below. It is an error to specify both *default* and " +"*default_factory*." +msgstr "" +"*default_factory*：如果提供，它必須是一個零引數可呼叫函式，當此欄位需要預設值" +"時將被呼叫。除其他用途外，這可用於指定具有可變預設值的欄位，如下所述。同時指" +"定 *default* 和 *default_factory* 是錯誤的。" + +#: ../../library/dataclasses.rst:272 +#, fuzzy +msgid "" +"*init*: If true (the default), this field is included as a parameter to the " +"generated :meth:`~object.__init__` method." +msgstr "" +"*init*：如果為 true（預設值），則此欄位將作為生成的 :meth:`~object.__init__` " +"方法的參數包含在內。" + +#: ../../library/dataclasses.rst:275 +#, fuzzy +msgid "" +"*repr*: If true (the default), this field is included in the string returned " +"by the generated :meth:`~object.__repr__` method." +msgstr "" +"*repr*：如果為真（預設值），則此欄位包含在生成的 :meth:`~object.__repr__` 方" +"法回傳的字串中。" + +#: ../../library/dataclasses.rst:278 +#, fuzzy +msgid "" +"*hash*: This can be a bool or ``None``. If true, this field is included in " +"the generated :meth:`~object.__hash__` method. If false, this field is " +"excluded from the generated :meth:`~object.__hash__`. If ``None`` (the " +"default), use the value of *compare*: this would normally be the expected " +"behavior, since a field should be included in the hash if it's used for " +"comparisons. Setting this value to anything other than ``None`` is " +"discouraged." +msgstr "" +"*hash*：這可以是 bool 或 ``None``。如果為真，則此欄位包含在生成的 :meth:" +"`__hash__` 方法中。如果 ``None``\\ （預設值），則使用\\ *比較*\\ 的值：這通常" +"是預期的行為。如果一個欄位用於比較，則應在雜湊中考慮該欄位。不鼓勵將此值設定" +"為 ``None`` 以外的任何值。" + +#: ../../library/dataclasses.rst:286 +#, fuzzy +msgid "" +"One possible reason to set ``hash=False`` but ``compare=True`` would be if a " +"field is expensive to compute a hash value for, that field is needed for " +"equality testing, and there are other fields that contribute to the type's " +"hash value. Even if a field is excluded from the hash, it will still be " +"used for comparisons." +msgstr "" +"設定 ``hash=False`` 但 ``compare=True`` 的一個可能原因是，如果一個欄位計算雜" +"湊值的成本很高，則需要該欄位進行相等性測試，並且還有其他欄位有助於型別的雜湊" +"值。即使一個欄位被排除在雜湊之外，它仍然會被用於比較。" + +#: ../../library/dataclasses.rst:292 +#, fuzzy +msgid "" +"*compare*: If true (the default), this field is included in the generated " +"equality and comparison methods (:meth:`~object.__eq__`, :meth:`~object." +"__gt__`, et al.)." +msgstr "" +"*compare*：如果為真（預設值），則此欄位包含在生成的相等和比較方法中（:meth:" +"`~object.__eq__`、:meth:`~object.__gt__` 等）。" + +#: ../../library/dataclasses.rst:296 +#, fuzzy +msgid "" +"*metadata*: This can be a mapping or ``None``. ``None`` is treated as an " +"empty dict. This value is wrapped in :func:`~types.MappingProxyType` to " +"make it read-only, and exposed on the :class:`Field` object. It is not used " +"at all by Data Classes, and is provided as a third-party extension " +"mechanism. Multiple third-parties can each have their own key, to use as a " +"namespace in the metadata." +msgstr "" +"*metadata*：這可以是對映或無。 None 被視為空字典。此值包含在 :func:`~types." +"MappingProxyType` 中以使其成為只讀的，並暴露在 :class:`Field` 物件上。它根本" +"不被資料類別使用，而是作為第三方擴充機制提供的。多個第三方可以各自擁有自己的" +"密鑰，用作元資料中的命名空間。" + +#: ../../library/dataclasses.rst:304 +#, fuzzy +msgid "" +"*kw_only*: If true, this field will be marked as keyword-only. This is used " +"when the generated :meth:`~object.__init__` method's parameters are computed." +msgstr "" +"*kw_only*：如果為真，該欄位將被標記為僅限關鍵字。這在計算生成的 :meth:" +"`~object.__init__` 方法的參數時使用。" + +#: ../../library/dataclasses.rst:308 +msgid "Keyword-only fields are also not included in :attr:`!__match_args__`." +msgstr "" + +#: ../../library/dataclasses.rst:312 +msgid "*doc*: optional docstring for this field." +msgstr "" + +#: ../../library/dataclasses.rst:316 +#, fuzzy +msgid "" +"If the default value of a field is specified by a call to :func:`!field`, " +"then the class attribute for this field will be replaced by the specified " +"*default* value. If *default* is not provided, then the class attribute " +"will be deleted. The intent is that after the :deco:`dataclass` decorator " +"runs, the class attributes will all contain the default values for the " +"fields, just as if the default value itself were specified. For example, " +"after::" +msgstr "" +"如果欄位的預設值是透過呼叫 :func:`!field` 指定的，那麼該欄位的類別屬性將被指" +"定的 *default* 值替換。如果沒有提供 *default*，那麼類別屬性將被刪除。目的是" +"在 :func:`@dataclass ` 裝飾器運行後，類別屬性將全部包含欄位的預設" +"值，就像預設值本身已指定一樣。例如，在： ::" + +#: ../../library/dataclasses.rst:325 +msgid "" +"@dataclass\n" +"class C:\n" +" x: int\n" +" y: int = field(repr=False)\n" +" z: int = field(repr=False, default=10)\n" +" t: int = 20" +msgstr "" +"@dataclass\n" +"class C:\n" +" x: int\n" +" y: int = field(repr=False)\n" +" z: int = field(repr=False, default=10)\n" +" t: int = 20" + +#: ../../library/dataclasses.rst:332 +#, fuzzy +msgid "" +"The class attribute :attr:`!C.z` will be ``10``, the class attribute :attr:`!" +"C.t` will be ``20``, and the class attributes :attr:`!C.x` and :attr:`!C.y` " +"will not be set." +msgstr "" +"類別屬性 :attr:`!C.z` 將為 ``10``，類別屬性 :attr:`!C.t` 將為 ``20``，類別屬" +"性 :attr:`!C.x` 和 :attr:`!C.y` 將不會放。" + +#: ../../library/dataclasses.rst:338 +#, fuzzy +msgid "" +":class:`!Field` objects describe each defined field. These objects are " +"created internally, and are returned by the :func:`fields` module-level " +"method (see below). Users should never instantiate a :class:`!Field` object " +"directly. Its documented attributes are:" +msgstr "" +":class:`!Field` 物件描述每個定義的欄位。這些物件在內部建立，並由 :func:" +"`fields` 模組級方法回傳（見下文）。使用者不應該直接實例化 :class:`!Field` 物" +"件。它記錄的屬性是：" + +#: ../../library/dataclasses.rst:343 +msgid ":attr:`!name`: The name of the field." +msgstr ":attr:`!name`：欄位的名稱。" + +#: ../../library/dataclasses.rst:344 +msgid ":attr:`!type`: The type of the field." +msgstr ":attr:`!type`：欄位的型別。" + +#: ../../library/dataclasses.rst:345 +#, fuzzy +msgid "" +":attr:`!default`, :attr:`!default_factory`, :attr:`!init`, :attr:`!repr`, :" +"attr:`!hash`, :attr:`!compare`, :attr:`!metadata`, and :attr:`!kw_only` have " +"the identical meaning and values as they do in the :func:`field` function." +msgstr "" +":attr:`!default`、:attr:`!default_factory`、:attr:`!init`、:attr:`!repr`、:" +"attr:`!hash`、:attr:`!compare`, :attr:`!metadata` 和 :attr:`!kw_only` 有與它" +"們在 :func:`field` 函式中的含義和值相同。" + +#: ../../library/dataclasses.rst:349 +#, fuzzy +msgid "" +"Other attributes may exist, but they are private and must not be inspected " +"or relied on." +msgstr "可能存在其他屬性，但它們是私有的，不得檢查或依賴。" + +#: ../../library/dataclasses.rst:354 +msgid "" +"``InitVar[T]`` type annotations describe variables that are :ref:`init-only " +"`. Fields annotated with :class:`!InitVar` " +"are considered pseudo-fields, and thus are neither returned by the :func:" +"`fields` function nor used in any way except adding them as parameters to :" +"meth:`~object.__init__` and an optional :meth:`__post_init__`." +msgstr "" + +#: ../../library/dataclasses.rst:363 +#, fuzzy +msgid "" +"Returns a tuple of :class:`Field` objects that define the fields for this " +"dataclass. Accepts either a dataclass, or an instance of a dataclass. " +"Raises :exc:`TypeError` if not passed a dataclass or instance of one. Does " +"not return pseudo-fields which are ``ClassVar`` or ``InitVar``." +msgstr "" +"回傳定義此資料類別欄位的 :class:`Field` 物件的元組。接受資料類別或資料類別的" +"實例。如果未傳遞資料類別或其中一個實例，則引發 :exc:`TypeError`。不回傳 " +"``ClassVar`` 或 ``InitVar`` 的偽欄位。" + +#: ../../library/dataclasses.rst:370 +#, fuzzy +msgid "" +"Converts the dataclass *obj* to a dict (by using the factory function " +"*dict_factory*). Each dataclass is converted to a dict of its fields, as " +"``name: value`` pairs. dataclasses, dicts, lists, and tuples are recursed " +"into. Other objects are copied with :func:`copy.deepcopy`." +msgstr "" +"將資料類別 *obj* 轉換為字典（透過使用工廠函式 *dict_factory*）。每個資料類別" +"都被轉換為其欄位的字典，作為 ``name: value`` 對。資料類別、字典、列表和元組被" +"遞迴到。其他物件使用 :func:`copy.deepcopy` 複製。" + +#: ../../library/dataclasses.rst:376 +#, fuzzy +msgid "Example of using :func:`!asdict` on nested dataclasses::" +msgstr "在嵌套資料類別上使用 :func:`!asdict` 的範例： ::" + +#: ../../library/dataclasses.rst:378 +msgid "" +"@dataclass\n" +"class Point:\n" +" x: int\n" +" y: int\n" +"\n" +"@dataclass\n" +"class C:\n" +" mylist: list[Point]\n" +"\n" +"p = Point(10, 20)\n" +"assert asdict(p) == {'x': 10, 'y': 20}\n" +"\n" +"c = C([Point(0, 0), Point(10, 4)])\n" +"assert asdict(c) == {'mylist': [{'x': 0, 'y': 0}, {'x': 10, 'y': 4}]}" +msgstr "" +"@dataclass\n" +"class Point:\n" +" x: int\n" +" y: int\n" +"\n" +"@dataclass\n" +"class C:\n" +" mylist: list[Point]\n" +"\n" +"p = Point(10, 20)\n" +"assert asdict(p) == {'x': 10, 'y': 20}\n" +"\n" +"c = C([Point(0, 0), Point(10, 4)])\n" +"assert asdict(c) == {'mylist': [{'x': 0, 'y': 0}, {'x': 10, 'y': 4}]}" + +#: ../../library/dataclasses.rst:393 ../../library/dataclasses.rst:413 +#, fuzzy +msgid "To create a shallow copy, the following workaround may be used::" +msgstr "要建立淺複製，可以使用以下解決方法：" + +#: ../../library/dataclasses.rst:395 +msgid "{field.name: getattr(obj, field.name) for field in fields(obj)}" +msgstr "{field.name: getattr(obj, field.name) for field in fields(obj)}" + +#: ../../library/dataclasses.rst:397 +#, fuzzy +msgid "" +":func:`!asdict` raises :exc:`TypeError` if *obj* is not a dataclass instance." +msgstr ":func:`!asdict` 如果 *obj* 不是資料類別實例，則引發 :exc:`TypeError`。" + +#: ../../library/dataclasses.rst:402 +#, fuzzy +msgid "" +"Converts the dataclass *obj* to a tuple (by using the factory function " +"*tuple_factory*). Each dataclass is converted to a tuple of its field " +"values. dataclasses, dicts, lists, and tuples are recursed into. Other " +"objects are copied with :func:`copy.deepcopy`." +msgstr "" +"將資料類別 *obj* 轉換為元組（透過使用工廠函式 *tuple_factory*）。每個資料類別" +"都被轉換為其欄位值的元組。資料類別、字典、列表和元組被遞迴到。其他物件使用 :" +"func:`copy.deepcopy` 複製。" + +#: ../../library/dataclasses.rst:408 +msgid "Continuing from the previous example::" +msgstr "從前面的例子繼續： ::" + +#: ../../library/dataclasses.rst:410 +msgid "" +"assert astuple(p) == (10, 20)\n" +"assert astuple(c) == ([(0, 0), (10, 4)],)" +msgstr "" +"assert astuple(p) == (10, 20)\n" +"assert astuple(c) == ([(0, 0), (10, 4)],)" + +#: ../../library/dataclasses.rst:415 +msgid "tuple(getattr(obj, field.name) for field in dataclasses.fields(obj))" +msgstr "tuple(getattr(obj, field.name) for field in dataclasses.fields(obj))" + +#: ../../library/dataclasses.rst:417 +#, fuzzy +msgid "" +":func:`!astuple` raises :exc:`TypeError` if *obj* is not a dataclass " +"instance." +msgstr "" +":func:`!astuple` 如果 *obj* 不是資料類別實例，則引發 :exc:`TypeError`。" + +#: ../../library/dataclasses.rst:422 +#, fuzzy +msgid "" +"Creates a new dataclass with name *cls_name*, fields as defined in *fields*, " +"base classes as given in *bases*, and initialized with a namespace as given " +"in *namespace*. *fields* is an iterable whose elements are each either " +"``name``, ``(name, type)``, or ``(name, type, Field)``. If just ``name`` is " +"supplied, :data:`typing.Any` is used for ``type``. The values of *init*, " +"*repr*, *eq*, *order*, *unsafe_hash*, *frozen*, *match_args*, *kw_only*, " +"*slots*, and *weakref_slot* have the same meaning as they do in :deco:" +"`dataclass`." +msgstr "" +"建立一個名為 *cls_name* 的新資料類別，欄位在 *fields* 中定義，基底類別在 " +"*bases* 中給出，並使用 *namespace* 中給出的命名空間進行初始化。 ``fields`` 是" +"一個疊代器，其元素分別是 ``name``、``(name, type)`` 或 ``(name, type, " +"Field)``。如果只提供 ``name``，則 ``typing.Any`` 用於 ``type``。 ``init``、" +"``repr``、``eq``、``order``、``unsafe_hash``、``frozen``、``match_args``、" +"``kw_only`` 的值, ``slots`` 和 ``weakref_slot`` 與它們在 :func:`dataclass` 中" +"的含義相同。" + +#: ../../library/dataclasses.rst:432 +msgid "" +"If *module* is defined, the :attr:`!__module__` attribute of the dataclass " +"is set to that value. By default, it is set to the module name of the caller." +msgstr "" + +#: ../../library/dataclasses.rst:436 +msgid "" +"The *decorator* parameter is a callable that will be used to create the " +"dataclass. It should take the class object as a first argument and the same " +"keyword arguments as :deco:`dataclass`. By default, the :deco:`dataclass` " +"function is used." +msgstr "" + +#: ../../library/dataclasses.rst:441 +#, fuzzy +msgid "" +"This function is not strictly required, because any Python mechanism for " +"creating a new class with :attr:`~object.__annotations__` can then apply " +"the :deco:`dataclass` function to convert that class to a dataclass. This " +"function is provided as a convenience. For example::" +msgstr "" +"這個函式不是嚴格要求的，因為任何使用 :attr:`~object.__annotations__` 建立新類" +"別的 Python 機制都可以應用 :func:`dataclass` 函式將該類別轉換為資料類別。提供" +"此功能是為了方便。例如： ::" + +#: ../../library/dataclasses.rst:447 +msgid "" +"C = make_dataclass('C',\n" +" [('x', int),\n" +" 'y',\n" +" ('z', int, field(default=5))],\n" +" namespace={'add_one': lambda self: self.x + 1})" +msgstr "" +"C = make_dataclass('C',\n" +" [('x', int),\n" +" 'y',\n" +" ('z', int, field(default=5))],\n" +" namespace={'add_one': lambda self: self.x + 1})" + +#: ../../library/dataclasses.rst:453 +msgid "Is equivalent to::" +msgstr "相當於： ::" + +#: ../../library/dataclasses.rst:455 +msgid "" +"@dataclass\n" +"class C:\n" +" x: int\n" +" y: 'typing.Any'\n" +" z: int = 5\n" +"\n" +" def add_one(self):\n" +" return self.x + 1" +msgstr "" + +#: ../../library/dataclasses.rst:464 +msgid "Added the *decorator* parameter." +msgstr "" + +#: ../../library/dataclasses.rst:469 +#, fuzzy +msgid "" +"Creates a new object of the same type as *obj*, replacing fields with values " +"from *changes*. If *obj* is not a Data Class, raises :exc:`TypeError`. If " +"keys in *changes* are not field names of the given dataclass, raises :exc:" +"`TypeError`." +msgstr "" +"建立一個與 ``obj`` 型別相同的新物件，用 ``changes`` 中的值替換欄位。如果 " +"``obj`` 不是資料類別，則引發 :exc:`TypeError`。如果 ``changes`` 中的值未指定" +"欄位，則引發 :exc:`TypeError`。" + +#: ../../library/dataclasses.rst:474 +#, fuzzy +msgid "" +"The newly returned object is created by calling the :meth:`~object.__init__` " +"method of the dataclass. This ensures that :meth:`__post_init__`, if " +"present, is also called." +msgstr "" +"新回傳的物件是透過呼叫資料類別的 :meth:`~object.__init__` 方法建立的。這確" +"保 :meth:`__post_init__`\\ （如果存在）也被呼叫。" + +#: ../../library/dataclasses.rst:478 +#, fuzzy +msgid "" +"Init-only variables without default values, if any exist, must be specified " +"on the call to :func:`!replace` so that they can be passed to :meth:`!" +"__init__` and :meth:`__post_init__`." +msgstr "" +"沒有預設值的僅初始化變數（如果存在）必須在呼叫 :func:`replace` 時指定，以便它" +"們可以傳遞給 :meth:`__init__` 和 :meth:`__post_init__`。" + +#: ../../library/dataclasses.rst:482 +#, fuzzy +msgid "" +"It is an error for *changes* to contain any fields that are defined as " +"having ``init=False``. A :exc:`ValueError` will be raised in this case." +msgstr "" +"*changes* 包含任何定義為具有 ``init=False`` 的欄位是錯誤的。在這種情況下將引" +"發 :exc:`ValueError`。" + +#: ../../library/dataclasses.rst:486 +#, fuzzy +msgid "" +"Be forewarned about how ``init=False`` fields work during a call to :func:`!" +"replace`. They are not copied from the source object, but rather are " +"initialized in :meth:`__post_init__`, if they're initialized at all. It is " +"expected that ``init=False`` fields will be rarely and judiciously used. If " +"they are used, it might be wise to have alternate class constructors, or " +"perhaps a custom :func:`!replace` (or similarly named) method which handles " +"instance copying." +msgstr "" +"預先警告 ``init=False`` 欄位在呼叫 :func:`!replace` 期間是如何工作的。它們不" +"是從源物件複製的，而是在 :meth:`__post_init__` 中初始化的，如果它們被初始化的" +"話。預計 ``init=False`` 欄位將很少被明智地使用。如果使用它們，使用替代的類別" +"建構函式可能是明智的，或者可能是處理實例複製的自訂 :func:`!replace` （或類似" +"命名的）方法。" + +#: ../../library/dataclasses.rst:495 +msgid "" +"Dataclass instances are also supported by generic function :func:`copy." +"replace`." +msgstr "" + +#: ../../library/dataclasses.rst:499 +msgid "" +"Return ``True`` if its parameter is a dataclass (including subclasses of a " +"dataclass) or an instance of one, otherwise return ``False``." +msgstr "" +"如果它的參數是一個資料類別（包含一個資料類別的子類別）或一個實例則回傳 ``True``，否則回傳 ``False``。" + +#: ../../library/dataclasses.rst:502 +#, fuzzy +msgid "" +"If you need to know if a class is an instance of a dataclass (and not a " +"dataclass itself), then add a further check for ``not isinstance(obj, " +"type)``::" +msgstr "" +"如果你需要知道一個類別是否是資料類別的實例（而不是資料類別本身），那麼新增一" +"個進一步的檢查 ``not isinstance(obj, type)``： ::" + +#: ../../library/dataclasses.rst:506 +msgid "" +"def is_dataclass_instance(obj):\n" +" return is_dataclass(obj) and not isinstance(obj, type)" +msgstr "" +"def is_dataclass_instance(obj):\n" +" return is_dataclass(obj) and not isinstance(obj, type)" + +#: ../../library/dataclasses.rst:511 +#, fuzzy +msgid "A sentinel value signifying a missing default or default_factory." +msgstr "表示缺少 default 或 default_factory 的標記值。" + +#: ../../library/dataclasses.rst:515 +#, fuzzy +msgid "" +"A sentinel value used as a type annotation. Any fields after a pseudo-field " +"with the type of :const:`!KW_ONLY` are marked as keyword-only fields. Note " +"that a pseudo-field of type :const:`!KW_ONLY` is otherwise completely " +"ignored. This includes the name of such a field. By convention, a name of " +"``_`` is used for a :const:`!KW_ONLY` field. Keyword-only fields signify :" +"meth:`~object.__init__` parameters that must be specified as keywords when " +"the class is instantiated." +msgstr "" +"用作型別註釋的標記值。型別為 :const:`!KW_ONLY` 的偽欄位之後的任何欄位都被標記" +"為僅關鍵字欄位。請注意，:const:`!KW_ONLY` 型別的偽欄位將被完全忽略。這包括此" +"類欄位的名稱。按照慣例，名稱 ``_`` 用於 :const:`!KW_ONLY` 欄位。僅關鍵字欄位" +"表示 :meth:`~object.__init__` 參數，在實例化類別時必須將其指定為關鍵字。" + +#: ../../library/dataclasses.rst:524 +#, fuzzy +msgid "" +"In this example, the fields ``y`` and ``z`` will be marked as keyword-only " +"fields::" +msgstr "在此示例中，欄位 ``y`` 和 ``z`` 將被標記為僅關鍵字欄位： ::" + +#: ../../library/dataclasses.rst:526 +msgid "" +"@dataclass\n" +"class Point:\n" +" x: float\n" +" _: KW_ONLY\n" +" y: float\n" +" z: float\n" +"\n" +"p = Point(0, y=1.5, z=2.0)" +msgstr "" +"@dataclass\n" +"class Point:\n" +" x: float\n" +" _: KW_ONLY\n" +" y: float\n" +" z: float\n" +"\n" +"p = Point(0, y=1.5, z=2.0)" + +#: ../../library/dataclasses.rst:535 +#, fuzzy +msgid "" +"In a single dataclass, it is an error to specify more than one field whose " +"type is :const:`!KW_ONLY`." +msgstr "在單個資料類別中，指定多個型別為 :const:`!KW_ONLY` 的欄位是錯誤的。" + +#: ../../library/dataclasses.rst:542 +#, fuzzy +msgid "" +"Raised when an implicitly defined :meth:`~object.__setattr__` or :meth:" +"`~object.__delattr__` is called on a dataclass which was defined with " +"``frozen=True``. It is a subclass of :exc:`AttributeError`." +msgstr "" +"當在使用 frozen=True 定義的資料類別上呼叫隱式定義的 :meth:`__setattr__` 或 :" +"meth:`__delattr__` 時引發。它是 :exc:`AttributeError` 的子類別。" + +#: ../../library/dataclasses.rst:549 +#, fuzzy +msgid "Post-init processing" +msgstr "後初始化處理" + +#: ../../library/dataclasses.rst:553 +#, fuzzy +msgid "" +"When defined on the class, it will be called by the generated :meth:`~object." +"__init__`, normally as :meth:`!self.__post_init__`. However, if any " +"``InitVar`` fields are defined, they will also be passed to :meth:`!" +"__post_init__` in the order they were defined in the class. If no :meth:`!" +"__init__` method is generated, then :meth:`!__post_init__` will not " +"automatically be called." +msgstr "" +"生成的 :meth:`~object.__init__` 程式碼將呼叫一個名為 :meth:`!self." +"__post_init__` 的方法，如果 :meth:`!__post_init__` 是在類別上定義的。它通常被" +"稱為 ``self.!__post_init__()``。但是，如果定義了任何 ``InitVar`` 欄位，它們也" +"將按照它們在類別中定義的順序傳遞給 :meth:`!__post_init__` 。如果沒有生成 :" +"meth:`!__init__` 方法，那麼 :meth:`!__post_init__` 將不會被自動呼叫。" + +#: ../../library/dataclasses.rst:560 +#, fuzzy +msgid "" +"Among other uses, this allows for initializing field values that depend on " +"one or more other fields. For example::" +msgstr "在其他用途中，這允許初始化依賴於一個或多個其他欄位的欄位值。例如： ::" + +#: ../../library/dataclasses.rst:563 +msgid "" +"@dataclass\n" +"class C:\n" +" a: float\n" +" b: float\n" +" c: float = field(init=False)\n" +"\n" +" def __post_init__(self):\n" +" self.c = self.a + self.b" +msgstr "" +"@dataclass\n" +"class C:\n" +" a: float\n" +" b: float\n" +" c: float = field(init=False)\n" +"\n" +" def __post_init__(self):\n" +" self.c = self.a + self.b" + +#: ../../library/dataclasses.rst:572 +#, fuzzy +msgid "" +"The :meth:`~object.__init__` method generated by :deco:`dataclass` does not " +"call base class :meth:`!__init__` methods. If the base class has an :meth:`!" +"__init__` method that has to be called, it is common to call this method in " +"a :meth:`__post_init__` method::" +msgstr "" +":func:`@dataclass ` 生成的 :meth:`~object.__init__` 方法不呼叫基底" +"類別 :meth:`!__init__` 方法。如果基底類別有一個必須呼叫的 :meth:`!__init__` " +"方法，通常在 :meth:`__post_init__` 方法中呼叫此方法： ::" + +#: ../../library/dataclasses.rst:577 +msgid "" +"class Rectangle:\n" +" def __init__(self, height, width):\n" +" self.height = height\n" +" self.width = width\n" +"\n" +"@dataclass\n" +"class Square(Rectangle):\n" +" side: float\n" +"\n" +" def __post_init__(self):\n" +" super().__init__(self.side, self.side)" +msgstr "" +"class Rectangle:\n" +" def __init__(self, height, width):\n" +" self.height = height\n" +" self.width = width\n" +"\n" +"@dataclass\n" +"class Square(Rectangle):\n" +" side: float\n" +"\n" +" def __post_init__(self):\n" +" super().__init__(self.side, self.side)" + +#: ../../library/dataclasses.rst:589 +#, fuzzy +msgid "" +"Note, however, that in general the dataclass-generated :meth:`!__init__` " +"methods don't need to be called, since the derived dataclass will take care " +"of initializing all fields of any base class that is a dataclass itself." +msgstr "" +"但是請注意，通常不需要呼叫資料類別生成的 :meth:`!__init__` 方法，因為衍生資料" +"類別將負責初始化作為資料類別本身的任何基底類別的所有欄位。" + +#: ../../library/dataclasses.rst:593 +#, fuzzy +msgid "" +"See the section below on init-only variables for ways to pass parameters to :" +"meth:`!__post_init__`. Also see the warning about how :func:`replace` " +"handles ``init=False`` fields." +msgstr "" +"請參閱下面有關僅初始化變數的部分，了解將參數傳遞給 :meth:`!__post_init__` 的" +"方法。另請參閱有關 :func:`replace` 如何處理 ``init=False`` 欄位的警告。" + +#: ../../library/dataclasses.rst:600 +msgid "Class variables" +msgstr "類別變數" + +#: ../../library/dataclasses.rst:602 +#, fuzzy +msgid "" +"One of the few places where :deco:`dataclass` actually inspects the type of " +"a field is to determine if a field is a class variable as defined in :pep:" +"`526`. It does this by checking if the type of the field is :data:`typing." +"ClassVar`. If a field is a ``ClassVar``, it is excluded from consideration " +"as a field and is ignored by the dataclass mechanisms. Such ``ClassVar`` " +"pseudo-fields are not returned by the module-level :func:`fields` function." +msgstr "" +":func:`@dataclass ` 實際檢查欄位型別的少數地方之一是確定欄位是否" +"是 :pep:`526` 中定義的類別變數。它透過檢查欄位的型別是否為 :data:`typing." +"ClassVar` 來做到這一點。如果一個欄位是一個 ``ClassVar``，它就被排除在考慮之" +"外，並被資料類別機制忽略。模組級 :func:`fields` 函式不會回傳此類別 " +"``ClassVar`` 偽欄位。" + +#: ../../library/dataclasses.rst:613 +#, fuzzy +msgid "Init-only variables" +msgstr "僅初始化變數" + +#: ../../library/dataclasses.rst:615 +#, fuzzy +msgid "" +"Another place where :deco:`dataclass` inspects a type annotation is to " +"determine if a field is an init-only variable. It does this by seeing if " +"the type of a field is of type :class:`InitVar`. If a field is an :class:" +"`InitVar`, it is considered a pseudo-field called an init-only field. As it " +"is not a true field, it is not returned by the module-level :func:`fields` " +"function. Init-only fields are added as parameters to the generated :meth:" +"`~object.__init__` method, and are passed to the optional :meth:" +"`__post_init__` method. They are not otherwise used by dataclasses." +msgstr "" +":func:`dataclass` 檢查型別註解的另一個地方是確定欄位是否是僅初始化變數。它通" +"過查看欄位的型別是否為 ``dataclasses.InitVar`` 型別來執行此操作。如果一個欄位" +"是一個 ``InitVar``，它被認為是一個偽欄位，稱為 init-only 欄位。由於它不是真正" +"的欄位，因此它不會由模組級 fields 函式回傳。 Init-only 欄位作為參數新增到生成" +"的 :meth:`~object.__init__` 方法，並傳遞給可選的 :meth:`__post_init__` 方法。" +"它們不被資料類別使用。" + +#: ../../library/dataclasses.rst:625 +#, fuzzy +msgid "" +"For example, suppose a field will be initialized from a database, if a value " +"is not provided when creating the class::" +msgstr "例如，假設一個欄位將從資料庫中初始化，如果在建立類別時沒有提供值： ::" + +#: ../../library/dataclasses.rst:628 +msgid "" +"@dataclass\n" +"class C:\n" +" i: int\n" +" j: int | None = None\n" +" database: InitVar[DatabaseType | None] = None\n" +"\n" +" def __post_init__(self, database):\n" +" if self.j is None and database is not None:\n" +" self.j = database.lookup('j')\n" +"\n" +"c = C(10, database=my_database)" +msgstr "" +"@dataclass\n" +"class C:\n" +" i: int\n" +" j: int | None = None\n" +" database: InitVar[DatabaseType | None] = None\n" +"\n" +" def __post_init__(self, database):\n" +" if self.j is None and database is not None:\n" +" self.j = database.lookup('j')\n" +"\n" +"c = C(10, database=my_database)" + +#: ../../library/dataclasses.rst:640 +#, fuzzy +msgid "" +"In this case, :func:`fields` will return :class:`Field` objects for :attr:`!" +"i` and :attr:`!j`, but not for :attr:`!database`." +msgstr "" +"在這種情況下，:func:`fields` 將為 :attr:`!i` 和 :attr:`!j` 回傳 :class:" +"`Field` 物件，但不會為 :attr:`!database` 回傳。" + +#: ../../library/dataclasses.rst:646 +msgid "Frozen instances" +msgstr "凍結實例" + +#: ../../library/dataclasses.rst:648 +#, fuzzy +msgid "" +"It is not possible to create truly immutable Python objects. However, by " +"passing ``frozen=True`` to the :deco:`dataclass` decorator you can emulate " +"immutability. In that case, dataclasses will add :meth:`~object." +"__setattr__` and :meth:`~object.__delattr__` methods to the class. These " +"methods will raise a :exc:`FrozenInstanceError` when invoked." +msgstr "" +"不可能建立真正不可變的 Python 物件。但是，透過將 ``frozen=True`` 傳遞給 :" +"func:`@dataclass ` 裝飾器，你可以模擬不變性。在這種情況下，資料類" +"別將向類別新增 :meth:`~object.__setattr__` 和 :meth:`~object.__delattr__` 方" +"法。這些方法在叫用時會引發 :exc:`FrozenInstanceError`。" + +#: ../../library/dataclasses.rst:654 +#, fuzzy +msgid "" +"There is a tiny performance penalty when using ``frozen=True``: :meth:" +"`~object.__init__` cannot use simple assignment to initialize fields, and " +"must use :meth:`!object.__setattr__`." +msgstr "" +"使用 ``frozen=True`` 時有一個微小的性能損失：:meth:`~object.__init__` 不能使" +"用簡單賦值來初始化欄位，必須使用 :meth:`!object.__setattr__`。" + +#: ../../library/dataclasses.rst:663 +msgid "Inheritance" +msgstr "繼承" + +#: ../../library/dataclasses.rst:665 +#, fuzzy +msgid "" +"When the dataclass is being created by the :deco:`dataclass` decorator, it " +"looks through all of the class's base classes in reverse MRO (that is, " +"starting at :class:`object`) and, for each dataclass that it finds, adds the " +"fields from that base class to an ordered mapping of fields. After all of " +"the base class fields are added, it adds its own fields to the ordered " +"mapping. All of the generated methods will use this combined, calculated " +"ordered mapping of fields. Because the fields are in insertion order, " +"derived classes override base classes. An example::" +msgstr "" +"當 :func:`@dataclass ` 裝飾器建立資料類別時，它會以反向 MRO（即" +"從 :class:`object` 開始）查看該類別的所有基底類別，並且對於它找到的每個資料類" +"別，將該基底類別中的欄位新增到欄位的有序對映中。新增所有基底類別欄位後，它會" +"將自己的欄位新增到有序對映中。所有生成的方法都將使用這種組合的、計算的有序欄" +"位對映。因為欄位是按插入順序排列的，所以衍生類別會覆蓋基底類別。一個例子： ::" + +#: ../../library/dataclasses.rst:675 +msgid "" +"@dataclass\n" +"class Base:\n" +" x: Any = 15.0\n" +" y: int = 0\n" +"\n" +"@dataclass\n" +"class C(Base):\n" +" z: int = 10\n" +" x: int = 15" +msgstr "" +"@dataclass\n" +"class Base:\n" +" x: Any = 15.0\n" +" y: int = 0\n" +"\n" +"@dataclass\n" +"class C(Base):\n" +" z: int = 10\n" +" x: int = 15" + +#: ../../library/dataclasses.rst:685 +#, fuzzy +msgid "" +"The final list of fields is, in order, :attr:`!x`, :attr:`!y`, :attr:`!z`. " +"The final type of :attr:`!x` is :class:`int`, as specified in class :class:`!" +"C`." +msgstr "" +"最終的欄位列表按順序為 :attr:`!x`、:attr:`!y`、:attr:`!z`。:attr:`!x` 的最終" +"型別是 :class:`int`，如類別 :class:`!C` 中指定的那樣。" + +#: ../../library/dataclasses.rst:688 +#, fuzzy +msgid "" +"The generated :meth:`~object.__init__` method for :class:`!C` will look " +"like::" +msgstr "為 :class:`!C` 生成的 :meth:`~object.__init__` 方法將如下所示： ::" + +#: ../../library/dataclasses.rst:690 +msgid "def __init__(self, x: int = 15, y: int = 0, z: int = 10):" +msgstr "def __init__(self, x: int = 15, y: int = 0, z: int = 10):" + +#: ../../library/dataclasses.rst:693 +#, fuzzy +msgid "Re-ordering of keyword-only parameters in :meth:`!__init__`" +msgstr ":meth:`!__init__` 中僅關鍵字參數的重新排序" + +#: ../../library/dataclasses.rst:695 +#, fuzzy +msgid "" +"After the parameters needed for :meth:`~object.__init__` are computed, any " +"keyword-only parameters are moved to come after all regular (non-keyword-" +"only) parameters. This is a requirement of how keyword-only parameters are " +"implemented in Python: they must come after non-keyword-only parameters." +msgstr "" +"在計算 :meth:`__init__` 所需的參數後，任何僅關鍵字參數都將移動到所有常規（非" +"僅關鍵字）參數之後。這是如何在 Python 中實作僅關鍵字參數的要求：它們必須位於" +"非僅關鍵字參數之後。" + +#: ../../library/dataclasses.rst:701 +#, fuzzy +msgid "" +"In this example, :attr:`!Base.y`, :attr:`!Base.w`, and :attr:`!D.t` are " +"keyword-only fields, and :attr:`!Base.x` and :attr:`!D.z` are regular " +"fields::" +msgstr "" +"在此示例中，:attr:`!Base.y`、:attr:`!Base.w` 和 :attr:`!D.t` 是僅限關鍵字的欄" +"位，:attr:`!Base.x` 和 :attr:`!D.z` 是常規欄位： ::" + +#: ../../library/dataclasses.rst:704 +msgid "" +"@dataclass\n" +"class Base:\n" +" x: Any = 15.0\n" +" _: KW_ONLY\n" +" y: int = 0\n" +" w: int = 1\n" +"\n" +"@dataclass\n" +"class D(Base):\n" +" z: int = 10\n" +" t: int = field(kw_only=True, default=0)" +msgstr "" +"@dataclass\n" +"class Base:\n" +" x: Any = 15.0\n" +" _: KW_ONLY\n" +" y: int = 0\n" +" w: int = 1\n" +"\n" +"@dataclass\n" +"class D(Base):\n" +" z: int = 10\n" +" t: int = field(kw_only=True, default=0)" + +#: ../../library/dataclasses.rst:716 +#, fuzzy +msgid "The generated :meth:`!__init__` method for :class:`!D` will look like::" +msgstr "為 :class:`!D` 生成的 :meth:`!__init__` 方法將如下所示： ::" + +#: ../../library/dataclasses.rst:718 +msgid "" +"def __init__(self, x: Any = 15.0, z: int = 10, *, y: int = 0, w: int = 1, t: " +"int = 0):" +msgstr "" +"def __init__(self, x: Any = 15.0, z: int = 10, *, y: int = 0, w: int = 1, t: " +"int = 0):" + +#: ../../library/dataclasses.rst:720 +#, fuzzy +msgid "" +"Note that the parameters have been re-ordered from how they appear in the " +"list of fields: parameters derived from regular fields are followed by " +"parameters derived from keyword-only fields." +msgstr "" +"請注意，參數已根據它們在欄位列表中的顯示方式重新排序：從常規欄位衍生的參數後" +"跟從僅關鍵字欄位衍生的參數。" + +#: ../../library/dataclasses.rst:724 +#, fuzzy +msgid "" +"The relative ordering of keyword-only parameters is maintained in the re-" +"ordered :meth:`!__init__` parameter list." +msgstr "僅關鍵字參數的相對順序在重新排序的 :meth:`!__init__` 參數列表中維護。" + +#: ../../library/dataclasses.rst:729 +msgid "Default factory functions" +msgstr "預設工廠函式" + +#: ../../library/dataclasses.rst:731 +#, fuzzy +msgid "" +"If a :func:`field` specifies a *default_factory*, it is called with zero " +"arguments when a default value for the field is needed. For example, to " +"create a new instance of a list, use::" +msgstr "" +"如果 :func:`field` 指定了 *default_factory*，當需要該欄位的預設值時，它會以零" +"引數呼叫。例如，要建立列表的新實例，請使用： ::" + +#: ../../library/dataclasses.rst:735 +msgid "mylist: list = field(default_factory=list)" +msgstr "mylist: list = field(default_factory=list)" + +#: ../../library/dataclasses.rst:737 +#, fuzzy +msgid "" +"If a field is excluded from :meth:`~object.__init__` (using ``init=False``) " +"and the field also specifies *default_factory*, then the default factory " +"function will always be called from the generated :meth:`!__init__` " +"function. This happens because there is no other way to give the field an " +"initial value." +msgstr "" +"如果一個欄位從 :meth:`~object.__init__` 中排除（使用 ``init=False``）並且該欄" +"位還指定了 ``default_factory``，那麼預設工廠函式將始終從生成的 :meth:" +"`__init__ 中呼叫`功能。發生這種情況是因為沒有其他方法可以為該欄位賦予初始值。" + +#: ../../library/dataclasses.rst:744 +msgid "Mutable default values" +msgstr "可變預設值" + +#: ../../library/dataclasses.rst:746 +#, fuzzy +msgid "" +"Python stores default member variable values in class attributes. Consider " +"this example, not using dataclasses::" +msgstr "" +"Python 將預設成員變數值儲存在類別屬性中。考慮這個例子，不使用資料類別： ::" + +#: ../../library/dataclasses.rst:749 +msgid "" +"class C:\n" +" x = []\n" +" def add(self, element):\n" +" self.x.append(element)\n" +"\n" +"o1 = C()\n" +"o2 = C()\n" +"o1.add(1)\n" +"o2.add(2)\n" +"assert o1.x == [1, 2]\n" +"assert o1.x is o2.x" +msgstr "" +"class C:\n" +" x = []\n" +" def add(self, element):\n" +" self.x.append(element)\n" +"\n" +"o1 = C()\n" +"o2 = C()\n" +"o1.add(1)\n" +"o2.add(2)\n" +"assert o1.x == [1, 2]\n" +"assert o1.x is o2.x" + +#: ../../library/dataclasses.rst:761 +#, fuzzy +msgid "" +"Note that the two instances of class :class:`!C` share the same class " +"variable :attr:`!x`, as expected." +msgstr "" +"請注意，類別 :class:`!C` 的兩個實例共享同一個類別變數 :attr:`!x`，正如預期的" +"那樣。" + +#: ../../library/dataclasses.rst:764 +#, fuzzy +msgid "Using dataclasses, *if* this code was valid::" +msgstr "使用資料類別，*如果*\\ 此程式碼有效： ::" + +#: ../../library/dataclasses.rst:766 +msgid "" +"@dataclass\n" +"class D:\n" +" x: list = [] # This code raises ValueError\n" +" def add(self, element):\n" +" self.x.append(element)" +msgstr "" +"@dataclass\n" +"class D:\n" +" x: list = [] # 這段程式碼會引發 ValueError\n" +" def add(self, element):\n" +" self.x.append(element)" + +#: ../../library/dataclasses.rst:772 +msgid "it would generate code similar to::" +msgstr "它會生成類似的程式碼： ::" + +#: ../../library/dataclasses.rst:774 +msgid "" +"class D:\n" +" x = []\n" +" def __init__(self, x=x):\n" +" self.x = x\n" +" def add(self, element):\n" +" self.x.append(element)\n" +"\n" +"assert D().x is D().x" +msgstr "" +"class D:\n" +" x = []\n" +" def __init__(self, x=x):\n" +" self.x = x\n" +" def add(self, element):\n" +" self.x.append(element)\n" +"\n" +"assert D().x is D().x" + +#: ../../library/dataclasses.rst:783 +#, fuzzy +msgid "" +"This has the same issue as the original example using class :class:`!C`. " +"That is, two instances of class :class:`!D` that do not specify a value for :" +"attr:`!x` when creating a class instance will share the same copy of :attr:`!" +"x`. Because dataclasses just use normal Python class creation they also " +"share this behavior. There is no general way for Data Classes to detect " +"this condition. Instead, the :deco:`dataclass` decorator will raise a :exc:" +"`ValueError` if it detects an unhashable default parameter. The assumption " +"is that if a value is unhashable, it is mutable. This is a partial " +"solution, but it does protect against many common errors." +msgstr "" +"這與使用類別 :class:`!C` 的原始示例存在相同的問題。也就是說，類別 :class:`!" +"D` 的兩個實例在建立類別實例時沒有為 :attr:`!x` 指定值，它們將共享 :attr:`!x` " +"的同一個副本。因為資料類別只是使用普通的 Python 類別建立，所以它們也有這種行" +"為。資料類別沒有通用的方法來檢測這種情況。相反，如果 :func:`dataclass` 裝飾器" +"檢測到不可雜湊的預設參數，它將引發 :exc:`TypeError`。假設是如果一個值是不可散" +"列的，那麼它就是可變的。這是一個部分解決方案，但它確實可以防止許多常見錯誤。" + +#: ../../library/dataclasses.rst:794 +#, fuzzy +msgid "" +"Using default factory functions is a way to create new instances of mutable " +"types as default values for fields::" +msgstr "使用預設工廠函式是一種建立可變型別的新實例作為欄位預設值的方法： ::" + +#: ../../library/dataclasses.rst:797 +msgid "" +"@dataclass\n" +"class D:\n" +" x: list = field(default_factory=list)\n" +"\n" +"assert D().x is not D().x" +msgstr "" +"@dataclass\n" +"class D:\n" +" x: list = field(default_factory=list)\n" +"\n" +"assert D().x is not D().x" + +#: ../../library/dataclasses.rst:803 +#, fuzzy +msgid "" +"Instead of looking for and disallowing objects of type :class:`list`, :class:" +"`dict`, or :class:`set`, unhashable objects are now not allowed as default " +"values. Unhashability is used to approximate mutability." +msgstr "" +"不再查找和禁止型別為 :class:`list`、:class:`dict` 或 :class:`set` 的物件，現" +"在不允許使用不可雜湊的物件作為預設值。不可雜湊性用於近似可變性。" + +#: ../../library/dataclasses.rst:810 +#, fuzzy +msgid "Descriptor-typed fields" +msgstr "描述器型別的欄位" + +#: ../../library/dataclasses.rst:812 +#, fuzzy +msgid "" +"Fields that are assigned :ref:`descriptor objects ` as their " +"default value have the following special behaviors:" +msgstr "" +"指定為\\ :ref:`描述器物件 `\\ 作為預設值的欄位具有以下特殊行為：" + +#: ../../library/dataclasses.rst:815 +#, fuzzy +msgid "" +"The value for the field passed to the dataclass's :meth:`~object.__init__` " +"method is passed to the descriptor's :meth:`~object.__set__` method rather " +"than overwriting the descriptor object." +msgstr "" +"傳遞給資料類別的 :meth:`~object.__init__` 方法的欄位值被傳遞給描述器的 :meth:" +"`~object.__set__` 方法，而不是覆蓋描述器物件。" + +#: ../../library/dataclasses.rst:819 +#, fuzzy +msgid "" +"Similarly, when getting or setting the field, the descriptor's :meth:" +"`~object.__get__` or :meth:`!__set__` method is called rather than returning " +"or overwriting the descriptor object." +msgstr "" +"同樣，在取得或設定欄位時，將呼叫描述器的 :meth:`~object.__get__` 或 :meth:`!" +"__set__` 方法，而不是回傳或覆蓋描述器物件。" + +#: ../../library/dataclasses.rst:823 +#, fuzzy +msgid "" +"To determine whether a field contains a default value, :deco:`dataclass` " +"will call the descriptor's :meth:`!__get__` method using its class access " +"form: ``descriptor.__get__(obj=None, type=cls)``. If the descriptor returns " +"a value in this case, it will be used as the field's default. On the other " +"hand, if the descriptor raises :exc:`AttributeError` in this situation, no " +"default value will be provided for the field." +msgstr "" +"為了確定一個欄位是否包含預設值，:func:`@dataclass ` 將使用其類別存" +"取形式呼叫描述器的 :meth:`!__get__` 方法（即 ``descriptor.__get__(obj=None, " +"type=cls)``。如果在這種情況下，描述器回傳一個值，它將用作欄位的預設值。另一方" +"面，如果描述器在這種情況下引發 :exc:`AttributeError`，則不會為該欄位提供預設" +"值。" + +#: ../../library/dataclasses.rst:833 +msgid "" +"class IntConversionDescriptor:\n" +" def __init__(self, *, default):\n" +" self._default = default\n" +"\n" +" def __set_name__(self, owner, name):\n" +" self._name = \"_\" + name\n" +"\n" +" def __get__(self, obj, type):\n" +" if obj is None:\n" +" return self._default\n" +"\n" +" return getattr(obj, self._name, self._default)\n" +"\n" +" def __set__(self, obj, value):\n" +" setattr(obj, self._name, int(value))\n" +"\n" +"@dataclass\n" +"class InventoryItem:\n" +" quantity_on_hand: IntConversionDescriptor = " +"IntConversionDescriptor(default=100)\n" +"\n" +"i = InventoryItem()\n" +"print(i.quantity_on_hand) # 100\n" +"i.quantity_on_hand = 2.5 # calls __set__ with 2.5\n" +"print(i.quantity_on_hand) # 2" +msgstr "" +"class IntConversionDescriptor:\n" +" def __init__(self, *, default):\n" +" self._default = default\n" +"\n" +" def __set_name__(self, owner, name):\n" +" self._name = \"_\" + name\n" +"\n" +" def __get__(self, obj, type):\n" +" if obj is None:\n" +" return self._default\n" +"\n" +" return getattr(obj, self._name, self._default)\n" +"\n" +" def __set__(self, obj, value):\n" +" setattr(obj, self._name, int(value))\n" +"\n" +"@dataclass\n" +"class InventoryItem:\n" +" quantity_on_hand: IntConversionDescriptor = " +"IntConversionDescriptor(default=100)\n" +"\n" +"i = InventoryItem()\n" +"print(i.quantity_on_hand) # 100\n" +"i.quantity_on_hand = 2.5 # 以 2.5 呼叫 __set__\n" +"print(i.quantity_on_hand) # 2" + +#: ../../library/dataclasses.rst:858 +#, fuzzy +msgid "" +"Note that if a field is annotated with a descriptor type, but is not " +"assigned a descriptor object as its default value, the field will act like a " +"normal field." +msgstr "" +"請注意，如果一個欄位用描述器型別註釋，但未分配描述器物件作為其預設值，則該欄" +"位將像普通欄位一樣工作。" diff --git a/library/datatypes.po b/library/datatypes.po index c6980edfad..c4592dfd79 100644 --- a/library/datatypes.po +++ b/library/datatypes.po @@ -1,49 +1,49 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2020-06-20 18:08+0800\n" -"PO-Revision-Date: 2022-02-11 12:12+0800\n" -"Last-Translator: Liang-Bo Wang \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" -"X-Generator: Poedit 3.0.1\n" - -#: ../../library/datatypes.rst:5 -msgid "Data Types" -msgstr "資料型別" - -#: ../../library/datatypes.rst:7 -msgid "" -"The modules described in this chapter provide a variety of specialized data " -"types such as dates and times, fixed-type arrays, heap queues, double-ended " -"queues, and enumerations." -msgstr "" -"本章節所描述的模組 (module) 提供了多樣的專門資料型別，例如日期與時間、固定型" -"別陣列 (fixed-type arrays)、堆積佇列 (heap queues)、雙端佇列 (double-ended " -"queues) 與列舉 (enumerations)。" - -#: ../../library/datatypes.rst:11 -msgid "" -"Python also provides some built-in data types, in particular, :class:" -"`dict`, :class:`list`, :class:`set` and :class:`frozenset`, and :class:" -"`tuple`. The :class:`str` class is used to hold Unicode strings, and the :" -"class:`bytes` and :class:`bytearray` classes are used to hold binary data." -msgstr "" -"Python 也有提供一些內建資料型別，特別是 :class:`dict`、:class:`list`、:class:" -"`set` 與 :class:`frozenset` 和 :class:`tuple`。:class:`str` 類別是用來儲存 " -"Unicode 字串，:class:`bytes` 與 :class:`bytearray` 類別則是用來儲存二進位制資" -"料。" - -#: ../../library/datatypes.rst:17 -msgid "The following modules are documented in this chapter:" -msgstr "本章節包含下列模組的文件：" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2020-06-20 18:08+0800\n" +"PO-Revision-Date: 2022-02-11 12:12+0800\n" +"Last-Translator: Liang-Bo Wang \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" +"X-Generator: Poedit 3.0.1\n" + +#: ../../library/datatypes.rst:5 +msgid "Data Types" +msgstr "資料型別" + +#: ../../library/datatypes.rst:7 +msgid "" +"The modules described in this chapter provide a variety of specialized data " +"types such as dates and times, fixed-type arrays, heap queues, double-ended " +"queues, and enumerations." +msgstr "" +"本章節所描述的模組 (module) 提供了多樣的專門資料型別，例如日期與時間、固定型" +"別陣列 (fixed-type arrays)、堆積佇列 (heap queues)、雙端佇列 (double-ended " +"queues) 與列舉 (enumerations)。" + +#: ../../library/datatypes.rst:11 +msgid "" +"Python also provides some built-in data types, in particular, :class:" +"`dict`, :class:`list`, :class:`set` and :class:`frozenset`, and :class:" +"`tuple`. The :class:`str` class is used to hold Unicode strings, and the :" +"class:`bytes` and :class:`bytearray` classes are used to hold binary data." +msgstr "" +"Python 也有提供一些內建資料型別，特別是 :class:`dict`、:class:`list`、:class:" +"`set` 與 :class:`frozenset` 和 :class:`tuple`。:class:`str` 類別是用來儲存 " +"Unicode 字串，:class:`bytes` 與 :class:`bytearray` 類別則是用來儲存二進位制資" +"料。" + +#: ../../library/datatypes.rst:17 +msgid "The following modules are documented in this chapter:" +msgstr "本章節包含下列模組的文件：" diff --git a/library/datetime.po b/library/datetime.po index ae1b1b16c3..b686928072 100644 --- a/library/datetime.po +++ b/library/datetime.po @@ -1,4462 +1,4462 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-12-22 00:16+0000\n" -"PO-Revision-Date: 2023-08-07 10:20+0800\n" -"Last-Translator: Griiid \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" -"X-Generator: Poedit 3.3.2\n" - -#: ../../library/datetime.rst:2 -msgid ":mod:`!datetime` --- Basic date and time types" -msgstr ":mod:`!datetime` --- 日期與時間的基本型別" - -#: ../../library/datetime.rst:11 -msgid "**Source code:** :source:`Lib/datetime.py`" -msgstr "**原始碼：**\\ :source:`Lib/datetime.py`" - -#: ../../library/datetime.rst:17 -msgid "" -"The :mod:`!datetime` module supplies classes for manipulating dates and " -"times." -msgstr ":mod:`!datetime` 模組提供操作日期與時間的類別。" - -#: ../../library/datetime.rst:19 -msgid "" -"While date and time arithmetic is supported, the focus of the implementation " -"is on efficient attribute extraction for output formatting and manipulation." -msgstr "" - -#: ../../library/datetime.rst:24 -msgid "Skip to :ref:`the format codes `." -msgstr "跳轉至\\ :ref:`格式碼 (format codes) `。" - -#: ../../library/datetime.rst:28 -msgid "Module :mod:`calendar`" -msgstr ":mod:`calendar` 模組" - -#: ../../library/datetime.rst:29 -msgid "General calendar related functions." -msgstr "與日曆相關的一般函式。" - -#: ../../library/datetime.rst:31 -msgid "Module :mod:`time`" -msgstr ":mod:`time` 模組" - -#: ../../library/datetime.rst:32 -msgid "Time access and conversions." -msgstr "" - -#: ../../library/datetime.rst:34 -msgid "Module :mod:`zoneinfo`" -msgstr ":mod:`zoneinfo` 模組" - -#: ../../library/datetime.rst:35 -msgid "Concrete time zones representing the IANA time zone database." -msgstr "" - -#: ../../library/datetime.rst:37 -msgid "Package `dateutil `_" -msgstr "`dateutil `_ 套件" - -#: ../../library/datetime.rst:38 -msgid "Third-party library with expanded time zone and parsing support." -msgstr "帶有時區與剖析擴充支援的第三方函式庫。" - -#: ../../library/datetime.rst:40 -msgid "Package :pypi:`DateType`" -msgstr ":pypi:`DateType` 套件" - -#: ../../library/datetime.rst:41 -msgid "" -"Third-party library that introduces distinct static types to e.g. allow :" -"term:`static type checkers ` to differentiate between " -"naive and aware datetimes." -msgstr "" - -#: ../../library/datetime.rst:48 -msgid "Aware and Naive Objects" -msgstr "" - -#: ../../library/datetime.rst:50 -msgid "" -"Date and time objects may be categorized as \"aware\" or \"naive\" depending " -"on whether or not they include time zone information." -msgstr "" - -#: ../../library/datetime.rst:53 -msgid "" -"With sufficient knowledge of applicable algorithmic and political time " -"adjustments, such as time zone and daylight saving time information, an " -"**aware** object can locate itself relative to other aware objects. An aware " -"object represents a specific moment in time that is not open to " -"interpretation. [#]_" -msgstr "" - -#: ../../library/datetime.rst:59 -msgid "" -"A **naive** object does not contain enough information to unambiguously " -"locate itself relative to other date/time objects. Whether a naive object " -"represents Coordinated Universal Time (UTC), local time, or time in some " -"other time zone is purely up to the program, just like it is up to the " -"program whether a particular number represents metres, miles, or mass. Naive " -"objects are easy to understand and to work with, at the cost of ignoring " -"some aspects of reality." -msgstr "" - -#: ../../library/datetime.rst:66 -msgid "" -"For applications requiring aware objects, :class:`.datetime` and :class:`." -"time` objects have an optional time zone information attribute, :attr:`!" -"tzinfo`, that can be set to an instance of a subclass of the abstract :class:" -"`tzinfo` class. These :class:`tzinfo` objects capture information about the " -"offset from UTC time, the time zone name, and whether daylight saving time " -"is in effect." -msgstr "" - -#: ../../library/datetime.rst:72 -msgid "" -"Only one concrete :class:`tzinfo` class, the :class:`timezone` class, is " -"supplied by the :mod:`!datetime` module. The :class:`!timezone` class can " -"represent simple time zones with fixed offsets from UTC, such as UTC itself " -"or North American EST and EDT time zones. Supporting time zones at deeper " -"levels of detail is up to the application. The rules for time adjustment " -"across the world are more political than rational, change frequently, and " -"there is no standard suitable for every application aside from UTC." -msgstr "" - -#: ../../library/datetime.rst:81 -msgid "Constants" -msgstr "常數" - -#: ../../library/datetime.rst:83 -msgid "The :mod:`!datetime` module exports the following constants:" -msgstr ":mod:`!datetime` 模組匯出以下常數：" - -#: ../../library/datetime.rst:87 -msgid "" -"The smallest year number allowed in a :class:`date` or :class:`.datetime` " -"object. :const:`MINYEAR` is 1." -msgstr "" - -#: ../../library/datetime.rst:93 -msgid "" -"The largest year number allowed in a :class:`date` or :class:`.datetime` " -"object. :const:`MAXYEAR` is 9999." -msgstr "" - -#: ../../library/datetime.rst:98 -msgid "Alias for the UTC time zone singleton :attr:`datetime.timezone.utc`." -msgstr "" - -#: ../../library/datetime.rst:103 -msgid "Available Types" -msgstr "" - -#: ../../library/datetime.rst:108 -msgid "" -"An idealized naive date, assuming the current Gregorian calendar always was, " -"and always will be, in effect. Attributes: :attr:`year`, :attr:`month`, and :" -"attr:`day`." -msgstr "" - -#: ../../library/datetime.rst:116 -msgid "" -"An idealized time, independent of any particular day, assuming that every " -"day has exactly 24\\*60\\*60 seconds. (There is no notion of \"leap " -"seconds\" here.) Attributes: :attr:`hour`, :attr:`minute`, :attr:`second`, :" -"attr:`microsecond`, and :attr:`.tzinfo`." -msgstr "" - -#: ../../library/datetime.rst:125 -msgid "" -"A combination of a date and a time. Attributes: :attr:`year`, :attr:" -"`month`, :attr:`day`, :attr:`hour`, :attr:`minute`, :attr:`second`, :attr:" -"`microsecond`, and :attr:`.tzinfo`." -msgstr "" - -#: ../../library/datetime.rst:133 -msgid "" -"A duration expressing the difference between two :class:`.datetime` or :" -"class:`date` instances to microsecond resolution." -msgstr "" -"表示兩個 :class:`.datetime` 或 :class:`date` 實例之間時間的差異，以微秒為解析" -"度。" - -#: ../../library/datetime.rst:140 -msgid "" -"An abstract base class for time zone information objects. These are used by " -"the :class:`.datetime` and :class:`.time` classes to provide a customizable " -"notion of time adjustment (for example, to account for time zone and/or " -"daylight saving time)." -msgstr "" - -#: ../../library/datetime.rst:148 -msgid "" -"A class that implements the :class:`tzinfo` abstract base class as a fixed " -"offset from the UTC." -msgstr "" - -#: ../../library/datetime.rst:153 ../../library/datetime.rst:171 -msgid "Objects of these types are immutable." -msgstr "" - -#: ../../library/datetime.rst:155 -msgid "Subclass relationships::" -msgstr "" - -#: ../../library/datetime.rst:157 -msgid "" -"object\n" -" timedelta\n" -" tzinfo\n" -" timezone\n" -" time\n" -" date\n" -" datetime" -msgstr "" -"object\n" -" timedelta\n" -" tzinfo\n" -" timezone\n" -" time\n" -" date\n" -" datetime" - -#: ../../library/datetime.rst:166 -msgid "Common Properties" -msgstr "常見屬性" - -#: ../../library/datetime.rst:168 -msgid "" -"The :class:`date`, :class:`.datetime`, :class:`.time`, and :class:`timezone` " -"types share these common features:" -msgstr "" - -#: ../../library/datetime.rst:172 -msgid "" -"Objects of these types are :term:`hashable`, meaning that they can be used " -"as dictionary keys." -msgstr "" - -#: ../../library/datetime.rst:174 -msgid "" -"Objects of these types support efficient pickling via the :mod:`pickle` " -"module." -msgstr "" - -#: ../../library/datetime.rst:177 -msgid "Determining if an Object is Aware or Naive" -msgstr "" - -#: ../../library/datetime.rst:179 -msgid "Objects of the :class:`date` type are always naive." -msgstr "" - -#: ../../library/datetime.rst:181 -msgid "" -"An object of type :class:`.time` or :class:`.datetime` may be aware or naive." -msgstr "" - -#: ../../library/datetime.rst:183 -msgid "" -"A :class:`.datetime` object ``d`` is aware if both of the following hold:" -msgstr "" - -#: ../../library/datetime.rst:185 -msgid "``d.tzinfo`` is not ``None``" -msgstr "``d.tzinfo`` 不是 ``None``" - -#: ../../library/datetime.rst:186 -msgid "``d.tzinfo.utcoffset(d)`` does not return ``None``" -msgstr "``d.tzinfo.utcoffset(d)`` 不會回傳 ``None``" - -#: ../../library/datetime.rst:188 -msgid "Otherwise, ``d`` is naive." -msgstr "否則 ``d`` 會是 naive 的。" - -#: ../../library/datetime.rst:190 -msgid "A :class:`.time` object ``t`` is aware if both of the following hold:" -msgstr "" - -#: ../../library/datetime.rst:192 -msgid "``t.tzinfo`` is not ``None``" -msgstr "``t.tzinfo`` 不是 ``None``" - -#: ../../library/datetime.rst:193 -msgid "``t.tzinfo.utcoffset(None)`` does not return ``None``." -msgstr "``t.tzinfo.utcoffset(None)`` 沒有回傳 ``None``。" - -#: ../../library/datetime.rst:195 -msgid "Otherwise, ``t`` is naive." -msgstr "否則 ``t`` 會是 naive 的。" - -#: ../../library/datetime.rst:197 -msgid "" -"The distinction between aware and naive doesn't apply to :class:`timedelta` " -"objects." -msgstr "" - -#: ../../library/datetime.rst:203 -msgid ":class:`timedelta` Objects" -msgstr ":class:`timedelta` 物件" - -#: ../../library/datetime.rst:205 -msgid "" -"A :class:`timedelta` object represents a duration, the difference between " -"two :class:`.datetime` or :class:`date` instances." -msgstr "" -"一個 :class:`timedelta` 物件代表著一段持續時間，即兩個 :class:`.datetime` " -"或 :class:`date` 之間的差異。" - -#: ../../library/datetime.rst:210 -msgid "" -"All arguments are optional and default to 0. Arguments may be integers or " -"floats, and may be positive or negative." -msgstr "" - -#: ../../library/datetime.rst:213 -msgid "" -"Only *days*, *seconds* and *microseconds* are stored internally. Arguments " -"are converted to those units:" -msgstr "" - -#: ../../library/datetime.rst:216 -msgid "A millisecond is converted to 1000 microseconds." -msgstr "一毫秒會被轉換為 1000 微秒。" - -#: ../../library/datetime.rst:217 -msgid "A minute is converted to 60 seconds." -msgstr "一分鐘會被轉換為 60 秒。" - -#: ../../library/datetime.rst:218 -msgid "An hour is converted to 3600 seconds." -msgstr "一小時會被轉換為 3600 秒。" - -#: ../../library/datetime.rst:219 -msgid "A week is converted to 7 days." -msgstr "一週會被轉換為 7 天。" - -#: ../../library/datetime.rst:221 -msgid "" -"and days, seconds and microseconds are then normalized so that the " -"representation is unique, with" -msgstr "" - -#: ../../library/datetime.rst:224 -msgid "``0 <= microseconds < 1000000``" -msgstr "``0 <= microseconds < 1000000``" - -#: ../../library/datetime.rst:225 -msgid "``0 <= seconds < 3600*24`` (the number of seconds in one day)" -msgstr "" - -#: ../../library/datetime.rst:226 -msgid "``-999999999 <= days <= 999999999``" -msgstr "``-999999999 <= days <= 999999999``" - -#: ../../library/datetime.rst:228 -msgid "" -"The following example illustrates how any arguments besides *days*, " -"*seconds* and *microseconds* are \"merged\" and normalized into those three " -"resulting attributes::" -msgstr "" - -#: ../../library/datetime.rst:232 -msgid "" -">>> from datetime import timedelta\n" -">>> delta = timedelta(\n" -"... days=50,\n" -"... seconds=27,\n" -"... microseconds=10,\n" -"... milliseconds=29000,\n" -"... minutes=5,\n" -"... hours=8,\n" -"... weeks=2\n" -"... )\n" -">>> # Only days, seconds, and microseconds remain\n" -">>> delta\n" -"datetime.timedelta(days=64, seconds=29156, microseconds=10)" -msgstr "" - -#: ../../library/datetime.rst:246 -msgid "" -"If any argument is a float and there are fractional microseconds, the " -"fractional microseconds left over from all arguments are combined and their " -"sum is rounded to the nearest microsecond using round-half-to-even " -"tiebreaker. If no argument is a float, the conversion and normalization " -"processes are exact (no information is lost)." -msgstr "" - -#: ../../library/datetime.rst:253 -msgid "" -"If the normalized value of days lies outside the indicated range, :exc:" -"`OverflowError` is raised." -msgstr "" - -#: ../../library/datetime.rst:256 -msgid "" -"Note that normalization of negative values may be surprising at first. For " -"example::" -msgstr "" - -#: ../../library/datetime.rst:259 -msgid "" -">>> from datetime import timedelta\n" -">>> d = timedelta(microseconds=-1)\n" -">>> (d.days, d.seconds, d.microseconds)\n" -"(-1, 86399, 999999)" -msgstr "" -">>> from datetime import timedelta\n" -">>> d = timedelta(microseconds=-1)\n" -">>> (d.days, d.seconds, d.microseconds)\n" -"(-1, 86399, 999999)" - -#: ../../library/datetime.rst:264 -msgid "" -"Since the string representation of :class:`!timedelta` objects can be " -"confusing, use the following recipe to produce a more readable format:" -msgstr "" - -#: ../../library/datetime.rst:267 -msgid "" -">>> def pretty_timedelta(td):\n" -"... if td.days >= 0:\n" -"... return str(td)\n" -"... return f'-({-td!s})'\n" -"...\n" -">>> d = timedelta(hours=-1)\n" -">>> str(d) # not human-friendly\n" -"'-1 day, 23:00:00'\n" -">>> pretty_timedelta(d)\n" -"'-(1:00:00)'" -msgstr "" -">>> def pretty_timedelta(td):\n" -"... if td.days >= 0:\n" -"... return str(td)\n" -"... return f'-({-td!s})'\n" -"...\n" -">>> d = timedelta(hours=-1)\n" -">>> str(d) # not human-friendly\n" -"'-1 day, 23:00:00'\n" -">>> pretty_timedelta(d)\n" -"'-(1:00:00)'" - -#: ../../library/datetime.rst:281 ../../library/datetime.rst:615 -#: ../../library/datetime.rst:1175 ../../library/datetime.rst:1813 -#: ../../library/datetime.rst:2434 -msgid "Class attributes:" -msgstr "類別屬性：" - -#: ../../library/datetime.rst:285 -msgid "The most negative :class:`timedelta` object, ``timedelta(-999999999)``." -msgstr "" - -#: ../../library/datetime.rst:290 -msgid "" -"The most positive :class:`timedelta` object, ``timedelta(days=999999999, " -"hours=23, minutes=59, seconds=59, microseconds=999999)``." -msgstr "" - -#: ../../library/datetime.rst:296 -msgid "" -"The smallest possible difference between non-equal :class:`timedelta` " -"objects, ``timedelta(microseconds=1)``." -msgstr "" - -#: ../../library/datetime.rst:299 -msgid "" -"Note that, because of normalization, ``timedelta.max`` is greater than ``-" -"timedelta.min``. ``-timedelta.max`` is not representable as a :class:" -"`timedelta` object." -msgstr "" - -#: ../../library/datetime.rst:303 ../../library/datetime.rst:633 -#: ../../library/datetime.rst:1195 ../../library/datetime.rst:1833 -msgid "Instance attributes (read-only):" -msgstr "" - -#: ../../library/datetime.rst:307 -msgid "Between -999,999,999 and 999,999,999 inclusive." -msgstr "在 -999,999,999 到 999,999,999 （含）之間" - -#: ../../library/datetime.rst:312 -msgid "Between 0 and 86,399 inclusive." -msgstr "在 0 到 86,399 （含）之間" - -#: ../../library/datetime.rst:316 -msgid "" -"It is a somewhat common bug for code to unintentionally use this attribute " -"when it is actually intended to get a :meth:`~timedelta.total_seconds` value " -"instead:" -msgstr "" - -#: ../../library/datetime.rst:320 -msgid "" -">>> from datetime import timedelta\n" -">>> duration = timedelta(seconds=11235813)\n" -">>> duration.days, duration.seconds\n" -"(130, 3813)\n" -">>> duration.total_seconds()\n" -"11235813.0" -msgstr "" -">>> from datetime import timedelta\n" -">>> duration = timedelta(seconds=11235813)\n" -">>> duration.days, duration.seconds\n" -"(130, 3813)\n" -">>> duration.total_seconds()\n" -"11235813.0" - -#: ../../library/datetime.rst:331 -msgid "Between 0 and 999,999 inclusive." -msgstr "在 0 到 999,999 （含）之間" - -#: ../../library/datetime.rst:334 ../../library/datetime.rst:650 -#: ../../library/datetime.rst:1248 -msgid "Supported operations:" -msgstr "" - -#: ../../library/datetime.rst:339 ../../library/datetime.rst:653 -#: ../../library/datetime.rst:1251 -msgid "Operation" -msgstr "" - -#: ../../library/datetime.rst:339 ../../library/datetime.rst:653 -#: ../../library/datetime.rst:1251 -msgid "Result" -msgstr "" - -#: ../../library/datetime.rst:341 -msgid "``t1 = t2 + t3``" -msgstr "``t1 = t2 + t3``" - -#: ../../library/datetime.rst:341 -msgid "" -"Sum of ``t2`` and ``t3``. Afterwards ``t1 - t2 == t3`` and ``t1 - t3 == t2`` " -"are true. (1)" -msgstr "" - -#: ../../library/datetime.rst:345 -msgid "``t1 = t2 - t3``" -msgstr "``t1 = t2 - t3``" - -#: ../../library/datetime.rst:345 -msgid "" -"Difference of ``t2`` and ``t3``. Afterwards ``t1 == t2 - t3`` and ``t2 == " -"t1 + t3`` are true. (1)(6)" -msgstr "" - -#: ../../library/datetime.rst:349 -msgid "``t1 = t2 * i or t1 = i * t2``" -msgstr "``t1 = t2 * i or t1 = i * t2``" - -#: ../../library/datetime.rst:349 -msgid "" -"Delta multiplied by an integer. Afterwards ``t1 // i == t2`` is true, " -"provided ``i != 0``." -msgstr "" - -#: ../../library/datetime.rst:353 -msgid "In general, ``t1 * i == t1 * (i-1) + t1`` is true. (1)" -msgstr "" - -#: ../../library/datetime.rst:356 -msgid "``t1 = t2 * f or t1 = f * t2``" -msgstr "``t1 = t2 * f or t1 = f * t2``" - -#: ../../library/datetime.rst:356 -msgid "" -"Delta multiplied by a float. The result is rounded to the nearest multiple " -"of timedelta.resolution using round-half-to-even." -msgstr "" - -#: ../../library/datetime.rst:360 -msgid "``f = t2 / t3``" -msgstr "``f = t2 / t3``" - -#: ../../library/datetime.rst:360 -msgid "" -"Division (3) of overall duration ``t2`` by interval unit ``t3``. Returns a :" -"class:`float` object." -msgstr "" - -#: ../../library/datetime.rst:364 -msgid "``t1 = t2 / f or t1 = t2 / i``" -msgstr "``t1 = t2 / f or t1 = t2 / i``" - -#: ../../library/datetime.rst:364 -msgid "" -"Delta divided by a float or an int. The result is rounded to the nearest " -"multiple of timedelta.resolution using round-half-to-even." -msgstr "" - -#: ../../library/datetime.rst:368 -msgid "``t1 = t2 // i`` or ``t1 = t2 // t3``" -msgstr "``t1 = t2 // i`` or ``t1 = t2 // t3``" - -#: ../../library/datetime.rst:368 -msgid "" -"The floor is computed and the remainder (if any) is thrown away. In the " -"second case, an integer is returned. (3)" -msgstr "" - -#: ../../library/datetime.rst:372 -msgid "``t1 = t2 % t3``" -msgstr "``t1 = t2 % t3``" - -#: ../../library/datetime.rst:372 -msgid "The remainder is computed as a :class:`timedelta` object. (3)" -msgstr "" - -#: ../../library/datetime.rst:375 -msgid "``q, r = divmod(t1, t2)``" -msgstr "``q, r = divmod(t1, t2)``" - -#: ../../library/datetime.rst:375 -msgid "" -"Computes the quotient and the remainder: ``q = t1 // t2`` (3) and ``r = t1 % " -"t2``. ``q`` is an integer and ``r`` is a :class:`timedelta` object." -msgstr "" - -#: ../../library/datetime.rst:380 -msgid "``+t1``" -msgstr "``+t1``" - -#: ../../library/datetime.rst:380 -msgid "Returns a :class:`timedelta` object with the same value. (2)" -msgstr "" - -#: ../../library/datetime.rst:383 -msgid "``-t1``" -msgstr "``-t1``" - -#: ../../library/datetime.rst:383 -msgid "" -"Equivalent to ``timedelta(-t1.days, -t1.seconds, -t1.microseconds)``, and to " -"``t1 * -1``. (1)(4)" -msgstr "" -"等價於 ``timedelta(-t1.days, -t1.seconds, -t1.microseconds)``，也等價於 ``t1 " -"* -1``。 (1)(4)" - -#: ../../library/datetime.rst:387 -msgid "``abs(t)``" -msgstr "``abs(t)``" - -#: ../../library/datetime.rst:387 -msgid "" -"Equivalent to ``+t`` when ``t.days >= 0``, and to ``-t`` when ``t.days < " -"0``. (2)" -msgstr "" - -#: ../../library/datetime.rst:390 -msgid "``str(t)``" -msgstr "``str(t)``" - -#: ../../library/datetime.rst:390 -msgid "" -"Returns a string in the form ``[D day[s], ][H]H:MM:SS[.UUUUUU]``, where D is " -"negative for negative ``t``. (5)" -msgstr "" - -#: ../../library/datetime.rst:394 -msgid "``repr(t)``" -msgstr "``repr(t)``" - -#: ../../library/datetime.rst:394 -msgid "" -"Returns a string representation of the :class:`timedelta` object as a " -"constructor call with canonical attribute values." -msgstr "" - -#: ../../library/datetime.rst:400 ../../library/datetime.rst:672 -#: ../../library/datetime.rst:2696 -msgid "Notes:" -msgstr "註解：" - -#: ../../library/datetime.rst:403 -msgid "This is exact but may overflow." -msgstr "這是精確的，但可能會溢位。" - -#: ../../library/datetime.rst:406 -msgid "This is exact and cannot overflow." -msgstr "這是精確的，且不會溢位。" - -#: ../../library/datetime.rst:409 -msgid "Division by zero raises :exc:`ZeroDivisionError`." -msgstr "" - -#: ../../library/datetime.rst:412 -msgid "``-timedelta.max`` is not representable as a :class:`timedelta` object." -msgstr "" - -#: ../../library/datetime.rst:415 -msgid "" -"String representations of :class:`timedelta` objects are normalized " -"similarly to their internal representation. This leads to somewhat unusual " -"results for negative timedeltas. For example::" -msgstr "" - -#: ../../library/datetime.rst:419 -msgid "" -">>> timedelta(hours=-5)\n" -"datetime.timedelta(days=-1, seconds=68400)\n" -">>> print(_)\n" -"-1 day, 19:00:00" -msgstr "" -">>> timedelta(hours=-5)\n" -"datetime.timedelta(days=-1, seconds=68400)\n" -">>> print(_)\n" -"-1 day, 19:00:00" - -#: ../../library/datetime.rst:425 -msgid "" -"The expression ``t2 - t3`` will always be equal to the expression ``t2 + (-" -"t3)`` except when t3 is equal to ``timedelta.max``; in that case the former " -"will produce a result while the latter will overflow." -msgstr "" - -#: ../../library/datetime.rst:429 -msgid "" -"In addition to the operations listed above, :class:`timedelta` objects " -"support certain additions and subtractions with :class:`date` and :class:`." -"datetime` objects (see below)." -msgstr "" - -#: ../../library/datetime.rst:433 -msgid "" -"Floor division and true division of a :class:`timedelta` object by another :" -"class:`timedelta` object are now supported, as are remainder operations and " -"the :func:`divmod` function. True division and multiplication of a :class:" -"`timedelta` object by a :class:`float` object are now supported." -msgstr "" - -#: ../../library/datetime.rst:439 -msgid ":class:`timedelta` objects support equality and order comparisons." -msgstr "" - -#: ../../library/datetime.rst:441 -msgid "" -"In Boolean contexts, a :class:`timedelta` object is considered to be true if " -"and only if it isn't equal to ``timedelta(0)``." -msgstr "" - -#: ../../library/datetime.rst:444 ../../library/datetime.rst:714 -#: ../../library/datetime.rst:1338 ../../library/datetime.rst:1956 -msgid "Instance methods:" -msgstr "實例方法：" - -#: ../../library/datetime.rst:448 -msgid "" -"Return the total number of seconds contained in the duration. Equivalent to " -"``td / timedelta(seconds=1)``. For interval units other than seconds, use " -"the division form directly (e.g. ``td / timedelta(microseconds=1)``)." -msgstr "" - -#: ../../library/datetime.rst:452 -msgid "" -"Note that for very large time intervals (greater than 270 years on most " -"platforms) this method will lose microsecond accuracy." -msgstr "" - -#: ../../library/datetime.rst:458 -msgid "Examples of usage: :class:`timedelta`" -msgstr "用法範例：:class:`timedelta`" - -#: ../../library/datetime.rst:460 -msgid "An additional example of normalization::" -msgstr "" - -#: ../../library/datetime.rst:462 -msgid "" -">>> # Components of another_year add up to exactly 365 days\n" -">>> from datetime import timedelta\n" -">>> year = timedelta(days=365)\n" -">>> another_year = timedelta(weeks=40, days=84, hours=23,\n" -"... minutes=50, seconds=600)\n" -">>> year == another_year\n" -"True\n" -">>> year.total_seconds()\n" -"31536000.0" -msgstr "" - -#: ../../library/datetime.rst:472 -msgid "Examples of :class:`timedelta` arithmetic::" -msgstr "" - -#: ../../library/datetime.rst:474 -msgid "" -">>> from datetime import timedelta\n" -">>> year = timedelta(days=365)\n" -">>> ten_years = 10 * year\n" -">>> ten_years\n" -"datetime.timedelta(days=3650)\n" -">>> ten_years.days // 365\n" -"10\n" -">>> nine_years = ten_years - year\n" -">>> nine_years\n" -"datetime.timedelta(days=3285)\n" -">>> three_years = nine_years // 3\n" -">>> three_years, three_years.days // 365\n" -"(datetime.timedelta(days=1095), 3)" -msgstr "" -">>> from datetime import timedelta\n" -">>> year = timedelta(days=365)\n" -">>> ten_years = 10 * year\n" -">>> ten_years\n" -"datetime.timedelta(days=3650)\n" -">>> ten_years.days // 365\n" -"10\n" -">>> nine_years = ten_years - year\n" -">>> nine_years\n" -"datetime.timedelta(days=3285)\n" -">>> three_years = nine_years // 3\n" -">>> three_years, three_years.days // 365\n" -"(datetime.timedelta(days=1095), 3)" - -#: ../../library/datetime.rst:491 -msgid ":class:`date` Objects" -msgstr ":class:`date` 物件" - -#: ../../library/datetime.rst:493 -msgid "" -"A :class:`date` object represents a date (year, month and day) in an " -"idealized calendar, the current Gregorian calendar indefinitely extended in " -"both directions." -msgstr "" - -#: ../../library/datetime.rst:497 -msgid "" -"January 1 of year 1 is called day number 1, January 2 of year 1 is called " -"day number 2, and so on. [#]_" -msgstr "" - -#: ../../library/datetime.rst:502 -msgid "" -"All arguments are required. Arguments must be integers, in the following " -"ranges:" -msgstr "" - -#: ../../library/datetime.rst:505 -msgid "``MINYEAR <= year <= MAXYEAR``" -msgstr "``MINYEAR <= year <= MAXYEAR``" - -#: ../../library/datetime.rst:506 -msgid "``1 <= month <= 12``" -msgstr "``1 <= month <= 12``" - -#: ../../library/datetime.rst:507 -msgid "``1 <= day <= number of days in the given month and year``" -msgstr "``1 <= day <= 該年該月的天數``" - -#: ../../library/datetime.rst:509 ../../library/datetime.rst:932 -msgid "" -"If an argument outside those ranges is given, :exc:`ValueError` is raised." -msgstr "" - -#: ../../library/datetime.rst:512 ../../library/datetime.rst:937 -msgid "Other constructors, all class methods:" -msgstr "" - -#: ../../library/datetime.rst:516 -msgid "Return the current local date." -msgstr "回傳目前的本地日期。" - -#: ../../library/datetime.rst:518 -msgid "This is equivalent to ``date.fromtimestamp(time.time())``." -msgstr "這等同於 ``date.fromtimestamp(time.time())``。" - -#: ../../library/datetime.rst:522 -msgid "" -"Return the local date corresponding to the POSIX timestamp, such as is " -"returned by :func:`time.time`." -msgstr "" - -#: ../../library/datetime.rst:525 -msgid "" -"This may raise :exc:`OverflowError`, if the timestamp is out of the range of " -"values supported by the platform C :c:func:`localtime` function, and :exc:" -"`OSError` on :c:func:`localtime` failure. It's common for this to be " -"restricted to years from 1970 through 2038. Note that on non-POSIX systems " -"that include leap seconds in their notion of a timestamp, leap seconds are " -"ignored by :meth:`fromtimestamp`." -msgstr "" - -#: ../../library/datetime.rst:532 -msgid "" -"Raise :exc:`OverflowError` instead of :exc:`ValueError` if the timestamp is " -"out of the range of values supported by the platform C :c:func:`localtime` " -"function. Raise :exc:`OSError` instead of :exc:`ValueError` on :c:func:" -"`localtime` failure." -msgstr "" - -#: ../../library/datetime.rst:541 -msgid "" -"Return the date corresponding to the proleptic Gregorian ordinal, where " -"January 1 of year 1 has ordinal 1." -msgstr "" - -#: ../../library/datetime.rst:544 -msgid "" -":exc:`ValueError` is raised unless ``1 <= ordinal <= date.max.toordinal()``. " -"For any date ``d``, ``date.fromordinal(d.toordinal()) == d``." -msgstr "" - -#: ../../library/datetime.rst:551 -msgid "" -"Return a :class:`date` corresponding to a *date_string* given in any valid " -"ISO 8601 format, with the following exceptions:" -msgstr "" - -#: ../../library/datetime.rst:554 ../../library/datetime.rst:1097 -msgid "" -"Reduced precision dates are not currently supported (``YYYY-MM``, ``YYYY``)." -msgstr "" - -#: ../../library/datetime.rst:556 ../../library/datetime.rst:1099 -msgid "" -"Extended date representations are not currently supported (``±YYYYYY-MM-" -"DD``)." -msgstr "" - -#: ../../library/datetime.rst:558 ../../library/datetime.rst:1101 -msgid "Ordinal dates are not currently supported (``YYYY-OOO``)." -msgstr "" - -#: ../../library/datetime.rst:560 ../../library/datetime.rst:1103 -#: ../../library/datetime.rst:1569 -msgid "Examples::" -msgstr "範例： ::" - -#: ../../library/datetime.rst:562 -msgid "" -">>> from datetime import date\n" -">>> date.fromisoformat('2019-12-04')\n" -"datetime.date(2019, 12, 4)\n" -">>> date.fromisoformat('20191204')\n" -"datetime.date(2019, 12, 4)\n" -">>> date.fromisoformat('2021-W01-1')\n" -"datetime.date(2021, 1, 4)" -msgstr "" -">>> from datetime import date\n" -">>> date.fromisoformat('2019-12-04')\n" -"datetime.date(2019, 12, 4)\n" -">>> date.fromisoformat('20191204')\n" -"datetime.date(2019, 12, 4)\n" -">>> date.fromisoformat('2021-W01-1')\n" -"datetime.date(2021, 1, 4)" - -#: ../../library/datetime.rst:571 -msgid "Previously, this method only supported the format ``YYYY-MM-DD``." -msgstr "" - -#: ../../library/datetime.rst:576 -msgid "" -"Return a :class:`date` corresponding to the ISO calendar date specified by " -"year, week and day. This is the inverse of the function :meth:`date." -"isocalendar`." -msgstr "" - -#: ../../library/datetime.rst:583 -msgid "" -"Return a :class:`.date` corresponding to *date_string*, parsed according to " -"*format*. This is equivalent to::" -msgstr "" - -#: ../../library/datetime.rst:586 -msgid "date(*(time.strptime(date_string, format)[0:3]))" -msgstr "date(*(time.strptime(date_string, format)[0:3]))" - -#: ../../library/datetime.rst:588 -msgid "" -":exc:`ValueError` is raised if the date_string and format can't be parsed " -"by :func:`time.strptime` or if it returns a value which isn't a time tuple. " -"See also :ref:`strftime-strptime-behavior` and :meth:`date.fromisoformat`." -msgstr "" - -#: ../../library/datetime.rst:595 -msgid "" -"If *format* specifies a day of month without a year a :exc:" -"`DeprecationWarning` is emitted. This is to avoid a quadrennial leap year " -"bug in code seeking to parse only a month and day as the default year used " -"in absence of one in the format is not a leap year. Such *format* values may " -"raise an error as of Python 3.15. The workaround is to always include a " -"year in your *format*. If parsing *date_string* values that do not have a " -"year, explicitly add a year that is a leap year before parsing:" -msgstr "" - -#: ../../library/datetime.rst:604 -msgid "" -">>> from datetime import date\n" -">>> date_string = \"02/29\"\n" -">>> when = date.strptime(f\"{date_string};1984\", \"%m/%d;%Y\") # Avoids " -"leap year bug.\n" -">>> when.strftime(\"%B %d\")\n" -"'February 29'" -msgstr "" -">>> from datetime import date\n" -">>> date_string = \"02/29\"\n" -">>> when = date.strptime(f\"{date_string};1984\", \"%m/%d;%Y\") # 避免閏年錯" -"誤。\n" -">>> when.strftime(\"%B %d\")\n" -"'February 29'" - -#: ../../library/datetime.rst:619 -msgid "The earliest representable date, ``date(MINYEAR, 1, 1)``." -msgstr "" - -#: ../../library/datetime.rst:624 -msgid "The latest representable date, ``date(MAXYEAR, 12, 31)``." -msgstr "" - -#: ../../library/datetime.rst:629 -msgid "" -"The smallest possible difference between non-equal date objects, " -"``timedelta(days=1)``." -msgstr "" - -#: ../../library/datetime.rst:637 ../../library/datetime.rst:1199 -msgid "Between :const:`MINYEAR` and :const:`MAXYEAR` inclusive." -msgstr "" - -#: ../../library/datetime.rst:642 ../../library/datetime.rst:1204 -msgid "Between 1 and 12 inclusive." -msgstr "在 1 到 12 （含）之間。" - -#: ../../library/datetime.rst:647 ../../library/datetime.rst:1209 -msgid "Between 1 and the number of days in the given month of the given year." -msgstr "" - -#: ../../library/datetime.rst:655 -msgid "``date2 = date1 + timedelta``" -msgstr "``date2 = date1 + timedelta``" - -#: ../../library/datetime.rst:655 -msgid "``date2`` will be ``timedelta.days`` days after ``date1``. (1)" -msgstr "" - -#: ../../library/datetime.rst:658 -msgid "``date2 = date1 - timedelta``" -msgstr "``date2 = date1 - timedelta``" - -#: ../../library/datetime.rst:658 -msgid "Computes ``date2`` such that ``date2 + timedelta == date1``. (2)" -msgstr "" - -#: ../../library/datetime.rst:661 -msgid "``timedelta = date1 - date2``" -msgstr "``timedelta = date1 - date2``" - -#: ../../library/datetime.rst:661 ../../library/datetime.rst:1257 -msgid "\\(3)" -msgstr "\\(3)" - -#: ../../library/datetime.rst:663 -msgid "``date1 == date2``" -msgstr "``date1 == date2``" - -#: ../../library/datetime.rst:664 -msgid "``date1 != date2``" -msgstr "``date1 != date2``" - -#: ../../library/datetime.rst:663 ../../library/datetime.rst:1259 -msgid "Equality comparison. (4)" -msgstr "" - -#: ../../library/datetime.rst:666 -msgid "``date1 < date2``" -msgstr "``date1 < date2``" - -#: ../../library/datetime.rst:667 -msgid "``date1 > date2``" -msgstr "``date1 > date2``" - -#: ../../library/datetime.rst:668 -msgid "``date1 <= date2``" -msgstr "``date1 <= date2``" - -#: ../../library/datetime.rst:669 -msgid "``date1 >= date2``" -msgstr "``date1 >= date2``" - -#: ../../library/datetime.rst:666 ../../library/datetime.rst:1262 -msgid "Order comparison. (5)" -msgstr "" - -#: ../../library/datetime.rst:675 -msgid "" -"*date2* is moved forward in time if ``timedelta.days > 0``, or backward if " -"``timedelta.days < 0``. Afterward ``date2 - date1 == timedelta.days``. " -"``timedelta.seconds`` and ``timedelta.microseconds`` are ignored. :exc:" -"`OverflowError` is raised if ``date2.year`` would be smaller than :const:" -"`MINYEAR` or larger than :const:`MAXYEAR`." -msgstr "" - -#: ../../library/datetime.rst:682 -msgid "``timedelta.seconds`` and ``timedelta.microseconds`` are ignored." -msgstr "``timedelta.seconds`` 和 ``timedelta.microseconds`` 被忽略。" - -#: ../../library/datetime.rst:685 -msgid "" -"This is exact, and cannot overflow. ``timedelta.seconds`` and ``timedelta." -"microseconds`` are 0, and ``date2 + timedelta == date1`` after." -msgstr "" - -#: ../../library/datetime.rst:689 -msgid ":class:`date` objects are equal if they represent the same date." -msgstr "" - -#: ../../library/datetime.rst:691 -msgid "" -":class:`!date` objects that are not also :class:`.datetime` instances are " -"never equal to :class:`!datetime` objects, even if they represent the same " -"date." -msgstr "" - -#: ../../library/datetime.rst:696 -msgid "" -"*date1* is considered less than *date2* when *date1* precedes *date2* in " -"time. In other words, ``date1 < date2`` if and only if ``date1.toordinal() < " -"date2.toordinal()``." -msgstr "" - -#: ../../library/datetime.rst:700 -msgid "" -"Order comparison between a :class:`!date` object that is not also a :class:`." -"datetime` instance and a :class:`!datetime` object raises :exc:`TypeError`." -msgstr "" - -#: ../../library/datetime.rst:704 ../../library/datetime.rst:1330 -msgid "" -"Comparison between :class:`.datetime` object and an instance of the :class:" -"`date` subclass that is not a :class:`!datetime` subclass no longer converts " -"the latter to :class:`!date`, ignoring the time part and the time zone. The " -"default behavior can be changed by overriding the special comparison methods " -"in subclasses." -msgstr "" - -#: ../../library/datetime.rst:712 -msgid "" -"In Boolean contexts, all :class:`date` objects are considered to be true." -msgstr "" - -#: ../../library/datetime.rst:718 -msgid "" -"Return a new :class:`date` object with the same values, but with specified " -"parameters updated." -msgstr "" - -#: ../../library/datetime.rst:721 ../../library/datetime.rst:2002 -msgid "Example::" -msgstr "範例： ::" - -#: ../../library/datetime.rst:723 -msgid "" -">>> from datetime import date\n" -">>> d = date(2002, 12, 31)\n" -">>> d.replace(day=26)\n" -"datetime.date(2002, 12, 26)" -msgstr "" -">>> from datetime import date\n" -">>> d = date(2002, 12, 31)\n" -">>> d.replace(day=26)\n" -"datetime.date(2002, 12, 26)" - -#: ../../library/datetime.rst:728 -msgid "" -"The generic function :func:`copy.replace` also supports :class:`date` " -"objects." -msgstr "" - -#: ../../library/datetime.rst:734 ../../library/datetime.rst:1454 -msgid "" -"Return a :class:`time.struct_time` such as returned by :func:`time." -"localtime`." -msgstr "" -"回傳一個 :class:`time.struct_time`，如同 :func:`time.localtime` 所回傳。" - -#: ../../library/datetime.rst:736 -msgid "The hours, minutes and seconds are 0, and the DST flag is -1." -msgstr "" - -#: ../../library/datetime.rst:738 ../../library/datetime.rst:1456 -msgid "``d.timetuple()`` is equivalent to::" -msgstr "``d.timetuple()`` 等價於： ::" - -#: ../../library/datetime.rst:740 -msgid "" -"time.struct_time((d.year, d.month, d.day, 0, 0, 0, d.weekday(), yday, -1))" -msgstr "" -"time.struct_time((d.year, d.month, d.day, 0, 0, 0, d.weekday(), yday, -1))" - -#: ../../library/datetime.rst:742 -msgid "" -"where ``yday = d.toordinal() - date(d.year, 1, 1).toordinal() + 1`` is the " -"day number within the current year starting with 1 for January 1st." -msgstr "" - -#: ../../library/datetime.rst:748 -msgid "" -"Return the proleptic Gregorian ordinal of the date, where January 1 of year " -"1 has ordinal 1. For any :class:`date` object ``d``, ``date.fromordinal(d." -"toordinal()) == d``." -msgstr "" - -#: ../../library/datetime.rst:755 -msgid "" -"Return the day of the week as an integer, where Monday is 0 and Sunday is 6. " -"For example, ``date(2002, 12, 4).weekday() == 2``, a Wednesday. See also :" -"meth:`isoweekday`." -msgstr "" -"回傳一個代表星期幾的整數，星期一為 0、星期日為 6。例如 ``date(2002, 12, 4)." -"weekday() == 2`` 為星期三。也請參考 :meth:`isoweekday`。" - -#: ../../library/datetime.rst:762 -msgid "" -"Return the day of the week as an integer, where Monday is 1 and Sunday is 7. " -"For example, ``date(2002, 12, 4).isoweekday() == 3``, a Wednesday. See also :" -"meth:`weekday`, :meth:`isocalendar`." -msgstr "" - -#: ../../library/datetime.rst:769 -msgid "" -"Return a :term:`named tuple` object with three components: ``year``, " -"``week`` and ``weekday``." -msgstr "" - -#: ../../library/datetime.rst:772 -msgid "" -"The ISO calendar is a widely used variant of the Gregorian calendar. [#]_" -msgstr "" - -#: ../../library/datetime.rst:774 -msgid "" -"The ISO year consists of 52 or 53 full weeks, and where a week starts on a " -"Monday and ends on a Sunday. The first week of an ISO year is the first " -"(Gregorian) calendar week of a year containing a Thursday. This is called " -"week number 1, and the ISO year of that Thursday is the same as its " -"Gregorian year." -msgstr "" - -#: ../../library/datetime.rst:779 -msgid "" -"For example, 2004 begins on a Thursday, so the first week of ISO year 2004 " -"begins on Monday, 29 Dec 2003 and ends on Sunday, 4 Jan 2004::" -msgstr "" - -#: ../../library/datetime.rst:782 -msgid "" -">>> from datetime import date\n" -">>> date(2003, 12, 29).isocalendar()\n" -"datetime.IsoCalendarDate(year=2004, week=1, weekday=1)\n" -">>> date(2004, 1, 4).isocalendar()\n" -"datetime.IsoCalendarDate(year=2004, week=1, weekday=7)" -msgstr "" -">>> from datetime import date\n" -">>> date(2003, 12, 29).isocalendar()\n" -"datetime.IsoCalendarDate(year=2004, week=1, weekday=1)\n" -">>> date(2004, 1, 4).isocalendar()\n" -"datetime.IsoCalendarDate(year=2004, week=1, weekday=7)" - -#: ../../library/datetime.rst:788 -msgid "Result changed from a tuple to a :term:`named tuple`." -msgstr "" - -#: ../../library/datetime.rst:793 -msgid "" -"Return a string representing the date in ISO 8601 format, ``YYYY-MM-DD``::" -msgstr "回傳一以 ISO 8601 格式 ``YYYY-MM-DD`` 表示的日期字串： ::" - -#: ../../library/datetime.rst:795 -msgid "" -">>> from datetime import date\n" -">>> date(2002, 12, 4).isoformat()\n" -"'2002-12-04'" -msgstr "" -">>> from datetime import date\n" -">>> date(2002, 12, 4).isoformat()\n" -"'2002-12-04'" - -#: ../../library/datetime.rst:801 -msgid "For a date ``d``, ``str(d)`` is equivalent to ``d.isoformat()``." -msgstr "" - -#: ../../library/datetime.rst:806 -msgid "Return a string representing the date::" -msgstr "" - -#: ../../library/datetime.rst:808 -msgid "" -">>> from datetime import date\n" -">>> date(2002, 12, 4).ctime()\n" -"'Wed Dec 4 00:00:00 2002'" -msgstr "" -">>> from datetime import date\n" -">>> date(2002, 12, 4).ctime()\n" -"'Wed Dec 4 00:00:00 2002'" - -#: ../../library/datetime.rst:812 ../../library/datetime.rst:1640 -msgid "``d.ctime()`` is equivalent to::" -msgstr "``d.ctime()`` 等價於： ::" - -#: ../../library/datetime.rst:814 ../../library/datetime.rst:1642 -msgid "time.ctime(time.mktime(d.timetuple()))" -msgstr "time.ctime(time.mktime(d.timetuple()))" - -#: ../../library/datetime.rst:816 -msgid "" -"on platforms where the native C :c:func:`ctime` function (which :func:`time." -"ctime` invokes, but which :meth:`date.ctime` does not invoke) conforms to " -"the C standard." -msgstr "" - -#: ../../library/datetime.rst:823 -msgid "" -"Return a string representing the date, controlled by an explicit format " -"string. Format codes referring to hours, minutes or seconds will see 0 " -"values. See also :ref:`strftime-strptime-behavior` and :meth:`date." -"isoformat`." -msgstr "" - -#: ../../library/datetime.rst:830 -msgid "" -"Same as :meth:`.date.strftime`. This makes it possible to specify a format " -"string for a :class:`.date` object in :ref:`formatted string literals ` and when using :meth:`str.format`. See also :ref:`strftime-" -"strptime-behavior` and :meth:`date.isoformat`." -msgstr "" - -#: ../../library/datetime.rst:836 -msgid "Examples of Usage: :class:`date`" -msgstr "用法範例：:class:`date`" - -#: ../../library/datetime.rst:838 -msgid "Example of counting days to an event::" -msgstr "計算一個事件的天數的範例： ::" - -#: ../../library/datetime.rst:840 -msgid "" -">>> import time\n" -">>> from datetime import date\n" -">>> today = date.today()\n" -">>> today\n" -"datetime.date(2007, 12, 5)\n" -">>> today == date.fromtimestamp(time.time())\n" -"True\n" -">>> my_birthday = date(today.year, 6, 24)\n" -">>> if my_birthday < today:\n" -"... my_birthday = my_birthday.replace(year=today.year + 1)\n" -"...\n" -">>> my_birthday\n" -"datetime.date(2008, 6, 24)\n" -">>> time_to_birthday = abs(my_birthday - today)\n" -">>> time_to_birthday.days\n" -"202" -msgstr "" -">>> import time\n" -">>> from datetime import date\n" -">>> today = date.today()\n" -">>> today\n" -"datetime.date(2007, 12, 5)\n" -">>> today == date.fromtimestamp(time.time())\n" -"True\n" -">>> my_birthday = date(today.year, 6, 24)\n" -">>> if my_birthday < today:\n" -"... my_birthday = my_birthday.replace(year=today.year + 1)\n" -"...\n" -">>> my_birthday\n" -"datetime.date(2008, 6, 24)\n" -">>> time_to_birthday = abs(my_birthday - today)\n" -">>> time_to_birthday.days\n" -"202" - -#: ../../library/datetime.rst:857 -msgid "More examples of working with :class:`date`:" -msgstr "更多 :class:`date` 的用法範例：" - -#: ../../library/datetime.rst:859 -msgid "" -">>> from datetime import date\n" -">>> d = date.fromordinal(730920) # 730920th day after 1. 1. 0001\n" -">>> d\n" -"datetime.date(2002, 3, 11)\n" -"\n" -">>> # Methods related to formatting string output\n" -">>> d.isoformat()\n" -"'2002-03-11'\n" -">>> d.strftime(\"%d/%m/%y\")\n" -"'11/03/02'\n" -">>> d.strftime(\"%A %d. %B %Y\")\n" -"'Monday 11. March 2002'\n" -">>> d.ctime()\n" -"'Mon Mar 11 00:00:00 2002'\n" -">>> 'The {1} is {0:%d}, the {2} is {0:%B}.'.format(d, \"day\", \"month\")\n" -"'The day is 11, the month is March.'\n" -"\n" -">>> # Methods for to extracting 'components' under different calendars\n" -">>> t = d.timetuple()\n" -">>> for i in t:\n" -"... print(i)\n" -"2002 # year\n" -"3 # month\n" -"11 # day\n" -"0\n" -"0\n" -"0\n" -"0 # weekday (0 = Monday)\n" -"70 # 70th day in the year\n" -"-1\n" -">>> ic = d.isocalendar()\n" -">>> for i in ic:\n" -"... print(i)\n" -"2002 # ISO year\n" -"11 # ISO week number\n" -"1 # ISO day number ( 1 = Monday )\n" -"\n" -">>> # A date object is immutable; all operations produce a new object\n" -">>> d.replace(year=2005)\n" -"datetime.date(2005, 3, 11)" -msgstr "" - -#: ../../library/datetime.rst:906 -msgid ":class:`.datetime` Objects" -msgstr ":class:`.datetime` 物件" - -#: ../../library/datetime.rst:908 -msgid "" -"A :class:`.datetime` object is a single object containing all the " -"information from a :class:`date` object and a :class:`.time` object." -msgstr "" - -#: ../../library/datetime.rst:911 -msgid "" -"Like a :class:`date` object, :class:`.datetime` assumes the current " -"Gregorian calendar extended in both directions; like a :class:`.time` " -"object, :class:`.datetime` assumes there are exactly 3600\\*24 seconds in " -"every day." -msgstr "" - -#: ../../library/datetime.rst:915 -msgid "Constructor:" -msgstr "建構函式：" - -#: ../../library/datetime.rst:919 -msgid "" -"The *year*, *month* and *day* arguments are required. *tzinfo* may be " -"``None``, or an instance of a :class:`tzinfo` subclass. The remaining " -"arguments must be integers in the following ranges:" -msgstr "" - -#: ../../library/datetime.rst:923 -msgid "``MINYEAR <= year <= MAXYEAR``," -msgstr "``MINYEAR <= year <= MAXYEAR``," - -#: ../../library/datetime.rst:924 -msgid "``1 <= month <= 12``," -msgstr "``1 <= month <= 12``," - -#: ../../library/datetime.rst:925 -msgid "``1 <= day <= number of days in the given month and year``," -msgstr "" - -#: ../../library/datetime.rst:926 ../../library/datetime.rst:1804 -msgid "``0 <= hour < 24``," -msgstr "``0 <= hour < 24``," - -#: ../../library/datetime.rst:927 ../../library/datetime.rst:1805 -msgid "``0 <= minute < 60``," -msgstr "``0 <= minute < 60``," - -#: ../../library/datetime.rst:928 ../../library/datetime.rst:1806 -msgid "``0 <= second < 60``," -msgstr "``0 <= second < 60``," - -#: ../../library/datetime.rst:929 ../../library/datetime.rst:1807 -msgid "``0 <= microsecond < 1000000``," -msgstr "``0 <= microsecond < 1000000``," - -#: ../../library/datetime.rst:930 ../../library/datetime.rst:1808 -msgid "``fold in [0, 1]``." -msgstr "``fold in [0, 1]``。" - -#: ../../library/datetime.rst:934 ../../library/datetime.rst:1375 -#: ../../library/datetime.rst:1969 -msgid "Added the *fold* parameter." -msgstr "新增 *fold* 參數。" - -#: ../../library/datetime.rst:941 -msgid "Return the current local date and time, with :attr:`.tzinfo` ``None``." -msgstr "回傳目前的本地日期與時間，且 :attr:`.tzinfo` 為 ``None``。" - -#: ../../library/datetime.rst:943 -msgid "Equivalent to::" -msgstr "等價於： ::" - -#: ../../library/datetime.rst:945 -msgid "datetime.fromtimestamp(time.time())" -msgstr "datetime.fromtimestamp(time.time())" - -#: ../../library/datetime.rst:947 -msgid "See also :meth:`now`, :meth:`fromtimestamp`." -msgstr "也請見 :meth:`now`、:meth:`fromtimestamp`。" - -#: ../../library/datetime.rst:949 -msgid "" -"This method is functionally equivalent to :meth:`now`, but without a ``tz`` " -"parameter." -msgstr "" - -#: ../../library/datetime.rst:954 -msgid "Return the current local date and time." -msgstr "" - -#: ../../library/datetime.rst:956 -msgid "" -"If optional argument *tz* is ``None`` or not specified, this is like :meth:" -"`today`, but, if possible, supplies more precision than can be gotten from " -"going through a :func:`time.time` timestamp (for example, this may be " -"possible on platforms supplying the C :c:func:`gettimeofday` function)." -msgstr "" -"如果選用的引數 *tz* 為 ``None`` 或未指定，則會像是 :meth:`today`，但盡可能提" -"供比透過 :func:`time.time` 取得的時間戳記更多位數的資訊（例如，這在有提供 C :" -"c:func:`gettimeofday` 函式的平台上可能可行）。" - -#: ../../library/datetime.rst:962 -msgid "" -"If *tz* is not ``None``, it must be an instance of a :class:`tzinfo` " -"subclass, and the current date and time are converted to *tz*’s time zone." -msgstr "" - -#: ../../library/datetime.rst:965 -msgid "This function is preferred over :meth:`today` and :meth:`utcnow`." -msgstr "" - -#: ../../library/datetime.rst:969 -msgid "" -"Subsequent calls to :meth:`!datetime.now` may return the same instant " -"depending on the precision of the underlying clock." -msgstr "" - -#: ../../library/datetime.rst:974 -msgid "Return the current UTC date and time, with :attr:`.tzinfo` ``None``." -msgstr "" - -#: ../../library/datetime.rst:976 -msgid "" -"This is like :meth:`now`, but returns the current UTC date and time, as a " -"naive :class:`.datetime` object. An aware current UTC datetime can be " -"obtained by calling ``datetime.now(timezone.utc)``. See also :meth:`now`." -msgstr "" - -#: ../../library/datetime.rst:982 -msgid "" -"Because naive ``datetime`` objects are treated by many ``datetime`` methods " -"as local times, it is preferred to use aware datetimes to represent times in " -"UTC. As such, the recommended way to create an object representing the " -"current time in UTC is by calling ``datetime.now(timezone.utc)``." -msgstr "" - -#: ../../library/datetime.rst:989 -msgid "Use :meth:`datetime.now` with :const:`UTC` instead." -msgstr "" - -#: ../../library/datetime.rst:994 -msgid "" -"Return the local date and time corresponding to the POSIX timestamp, such as " -"is returned by :func:`time.time`. If optional argument *tz* is ``None`` or " -"not specified, the timestamp is converted to the platform's local date and " -"time, and the returned :class:`.datetime` object is naive." -msgstr "" - -#: ../../library/datetime.rst:999 -msgid "" -"If *tz* is not ``None``, it must be an instance of a :class:`tzinfo` " -"subclass, and the timestamp is converted to *tz*’s time zone." -msgstr "" - -#: ../../library/datetime.rst:1002 -msgid "" -":meth:`fromtimestamp` may raise :exc:`OverflowError`, if the timestamp is " -"out of the range of values supported by the platform C :c:func:`localtime` " -"or :c:func:`gmtime` functions, and :exc:`OSError` on :c:func:`localtime` or :" -"c:func:`gmtime` failure. It's common for this to be restricted to years in " -"1970 through 2038. Note that on non-POSIX systems that include leap seconds " -"in their notion of a timestamp, leap seconds are ignored by :meth:" -"`fromtimestamp`, and then it's possible to have two timestamps differing by " -"a second that yield identical :class:`.datetime` objects. This method is " -"preferred over :meth:`utcfromtimestamp`." -msgstr "" - -#: ../../library/datetime.rst:1013 -msgid "" -"Raise :exc:`OverflowError` instead of :exc:`ValueError` if the timestamp is " -"out of the range of values supported by the platform C :c:func:`localtime` " -"or :c:func:`gmtime` functions. Raise :exc:`OSError` instead of :exc:" -"`ValueError` on :c:func:`localtime` or :c:func:`gmtime` failure." -msgstr "" - -#: ../../library/datetime.rst:1020 -msgid ":meth:`fromtimestamp` may return instances with :attr:`.fold` set to 1." -msgstr "" - -#: ../../library/datetime.rst:1025 -msgid "" -"Return the UTC :class:`.datetime` corresponding to the POSIX timestamp, " -"with :attr:`.tzinfo` ``None``. (The resulting object is naive.)" -msgstr "" - -#: ../../library/datetime.rst:1028 -msgid "" -"This may raise :exc:`OverflowError`, if the timestamp is out of the range of " -"values supported by the platform C :c:func:`gmtime` function, and :exc:" -"`OSError` on :c:func:`gmtime` failure. It's common for this to be restricted " -"to years in 1970 through 2038." -msgstr "" - -#: ../../library/datetime.rst:1033 -msgid "To get an aware :class:`.datetime` object, call :meth:`fromtimestamp`::" -msgstr "" - -#: ../../library/datetime.rst:1035 -msgid "datetime.fromtimestamp(timestamp, timezone.utc)" -msgstr "datetime.fromtimestamp(timestamp, timezone.utc)" - -#: ../../library/datetime.rst:1037 -msgid "" -"On the POSIX compliant platforms, it is equivalent to the following " -"expression::" -msgstr "" - -#: ../../library/datetime.rst:1040 -msgid "" -"datetime(1970, 1, 1, tzinfo=timezone.utc) + timedelta(seconds=timestamp)" -msgstr "" -"datetime(1970, 1, 1, tzinfo=timezone.utc) + timedelta(seconds=timestamp)" - -#: ../../library/datetime.rst:1042 -msgid "" -"except the latter formula always supports the full years range: between :" -"const:`MINYEAR` and :const:`MAXYEAR` inclusive." -msgstr "" - -#: ../../library/datetime.rst:1047 -msgid "" -"Because naive ``datetime`` objects are treated by many ``datetime`` methods " -"as local times, it is preferred to use aware datetimes to represent times in " -"UTC. As such, the recommended way to create an object representing a " -"specific timestamp in UTC is by calling ``datetime.fromtimestamp(timestamp, " -"tz=timezone.utc)``." -msgstr "" - -#: ../../library/datetime.rst:1053 -msgid "" -"Raise :exc:`OverflowError` instead of :exc:`ValueError` if the timestamp is " -"out of the range of values supported by the platform C :c:func:`gmtime` " -"function. Raise :exc:`OSError` instead of :exc:`ValueError` on :c:func:" -"`gmtime` failure." -msgstr "" - -#: ../../library/datetime.rst:1061 -msgid "Use :meth:`datetime.fromtimestamp` with :const:`UTC` instead." -msgstr "" - -#: ../../library/datetime.rst:1066 -msgid "" -"Return the :class:`.datetime` corresponding to the proleptic Gregorian " -"ordinal, where January 1 of year 1 has ordinal 1. :exc:`ValueError` is " -"raised unless ``1 <= ordinal <= datetime.max.toordinal()``. The hour, " -"minute, second and microsecond of the result are all 0, and :attr:`.tzinfo` " -"is ``None``." -msgstr "" - -#: ../../library/datetime.rst:1074 -msgid "" -"Return a new :class:`.datetime` object whose date components are equal to " -"the given :class:`date` object's, and whose time components are equal to the " -"given :class:`.time` object's. If the *tzinfo* argument is provided, its " -"value is used to set the :attr:`.tzinfo` attribute of the result, otherwise " -"the :attr:`~.time.tzinfo` attribute of the *time* argument is used. If the " -"*date* argument is a :class:`.datetime` object, its time components and :" -"attr:`.tzinfo` attributes are ignored." -msgstr "" - -#: ../../library/datetime.rst:1082 -msgid "" -"For any :class:`.datetime` object ``d``, ``d == datetime.combine(d.date(), d." -"time(), d.tzinfo)``." -msgstr "" - -#: ../../library/datetime.rst:1085 -msgid "Added the *tzinfo* argument." -msgstr "新增 *tzinfo* 引數。" - -#: ../../library/datetime.rst:1091 -msgid "" -"Return a :class:`.datetime` corresponding to a *date_string* in any valid " -"ISO 8601 format, with the following exceptions:" -msgstr "" - -#: ../../library/datetime.rst:1094 ../../library/datetime.rst:1904 -msgid "Time zone offsets may have fractional seconds." -msgstr "" - -#: ../../library/datetime.rst:1095 -msgid "The ``T`` separator may be replaced by any single unicode character." -msgstr "" - -#: ../../library/datetime.rst:1096 ../../library/datetime.rst:1909 -msgid "Fractional hours and minutes are not supported." -msgstr "" - -#: ../../library/datetime.rst:1105 -msgid "" -">>> from datetime import datetime\n" -">>> datetime.fromisoformat('2011-11-04')\n" -"datetime.datetime(2011, 11, 4, 0, 0)\n" -">>> datetime.fromisoformat('20111104')\n" -"datetime.datetime(2011, 11, 4, 0, 0)\n" -">>> datetime.fromisoformat('2011-11-04T00:05:23')\n" -"datetime.datetime(2011, 11, 4, 0, 5, 23)\n" -">>> datetime.fromisoformat('2011-11-04T00:05:23Z')\n" -"datetime.datetime(2011, 11, 4, 0, 5, 23, tzinfo=datetime.timezone.utc)\n" -">>> datetime.fromisoformat('20111104T000523')\n" -"datetime.datetime(2011, 11, 4, 0, 5, 23)\n" -">>> datetime.fromisoformat('2011-W01-2T00:05:23.283')\n" -"datetime.datetime(2011, 1, 4, 0, 5, 23, 283000)\n" -">>> datetime.fromisoformat('2011-11-04 00:05:23.283')\n" -"datetime.datetime(2011, 11, 4, 0, 5, 23, 283000)\n" -">>> datetime.fromisoformat('2011-11-04 00:05:23.283+00:00')\n" -"datetime.datetime(2011, 11, 4, 0, 5, 23, 283000, tzinfo=datetime.timezone." -"utc)\n" -">>> datetime.fromisoformat('2011-11-04T00:05:23+04:00')\n" -"datetime.datetime(2011, 11, 4, 0, 5, 23,\n" -" tzinfo=datetime.timezone(datetime.timedelta(seconds=14400)))" -msgstr "" -">>> from datetime import datetime\n" -">>> datetime.fromisoformat('2011-11-04')\n" -"datetime.datetime(2011, 11, 4, 0, 0)\n" -">>> datetime.fromisoformat('20111104')\n" -"datetime.datetime(2011, 11, 4, 0, 0)\n" -">>> datetime.fromisoformat('2011-11-04T00:05:23')\n" -"datetime.datetime(2011, 11, 4, 0, 5, 23)\n" -">>> datetime.fromisoformat('2011-11-04T00:05:23Z')\n" -"datetime.datetime(2011, 11, 4, 0, 5, 23, tzinfo=datetime.timezone.utc)\n" -">>> datetime.fromisoformat('20111104T000523')\n" -"datetime.datetime(2011, 11, 4, 0, 5, 23)\n" -">>> datetime.fromisoformat('2011-W01-2T00:05:23.283')\n" -"datetime.datetime(2011, 1, 4, 0, 5, 23, 283000)\n" -">>> datetime.fromisoformat('2011-11-04 00:05:23.283')\n" -"datetime.datetime(2011, 11, 4, 0, 5, 23, 283000)\n" -">>> datetime.fromisoformat('2011-11-04 00:05:23.283+00:00')\n" -"datetime.datetime(2011, 11, 4, 0, 5, 23, 283000, tzinfo=datetime.timezone." -"utc)\n" -">>> datetime.fromisoformat('2011-11-04T00:05:23+04:00')\n" -"datetime.datetime(2011, 11, 4, 0, 5, 23,\n" -" tzinfo=datetime.timezone(datetime.timedelta(seconds=14400)))" - -#: ../../library/datetime.rst:1127 -msgid "" -"Previously, this method only supported formats that could be emitted by :" -"meth:`date.isoformat` or :meth:`datetime.isoformat`." -msgstr "" - -#: ../../library/datetime.rst:1134 -msgid "" -"Return a :class:`.datetime` corresponding to the ISO calendar date specified " -"by year, week and day. The non-date components of the datetime are populated " -"with their normal default values. This is the inverse of the function :meth:" -"`datetime.isocalendar`." -msgstr "" - -#: ../../library/datetime.rst:1143 -msgid "" -"Return a :class:`.datetime` corresponding to *date_string*, parsed according " -"to *format*." -msgstr "" - -#: ../../library/datetime.rst:1146 -msgid "" -"If *format* does not contain microseconds or time zone information, this is " -"equivalent to::" -msgstr "" - -#: ../../library/datetime.rst:1148 ../../library/datetime.rst:2676 -msgid "datetime(*(time.strptime(date_string, format)[0:6]))" -msgstr "datetime(*(time.strptime(date_string, format)[0:6]))" - -#: ../../library/datetime.rst:1150 -msgid "" -":exc:`ValueError` is raised if the date_string and format can't be parsed " -"by :func:`time.strptime` or if it returns a value which isn't a time tuple. " -"See also :ref:`strftime-strptime-behavior` and :meth:`datetime." -"fromisoformat`." -msgstr "" - -#: ../../library/datetime.rst:1157 -msgid "" -"If *format* specifies a day of month without a year a :exc:" -"`DeprecationWarning` is now emitted. This is to avoid a quadrennial leap " -"year bug in code seeking to parse only a month and day as the default year " -"used in absence of one in the format is not a leap year. Such *format* " -"values may raise an error as of Python 3.15. The workaround is to always " -"include a year in your *format*. If parsing *date_string* values that do " -"not have a year, explicitly add a year that is a leap year before parsing:" -msgstr "" - -#: ../../library/datetime.rst:1166 -msgid "" -">>> from datetime import datetime\n" -">>> date_string = \"02/29\"\n" -">>> when = datetime.strptime(f\"{date_string};1984\", \"%m/%d;%Y\") # " -"Avoids leap year bug.\n" -">>> when.strftime(\"%B %d\")\n" -"'February 29'" -msgstr "" -">>> from datetime import datetime\n" -">>> date_string = \"02/29\"\n" -">>> when = datetime.strptime(f\"{date_string};1984\", \"%m/%d;%Y\") # 避免閏" -"年錯誤。\n" -">>> when.strftime(\"%B %d\")\n" -"'February 29'" - -#: ../../library/datetime.rst:1179 -msgid "" -"The earliest representable :class:`.datetime`, ``datetime(MINYEAR, 1, 1, " -"tzinfo=None)``." -msgstr "" - -#: ../../library/datetime.rst:1185 -msgid "" -"The latest representable :class:`.datetime`, ``datetime(MAXYEAR, 12, 31, 23, " -"59, 59, 999999, tzinfo=None)``." -msgstr "" - -#: ../../library/datetime.rst:1191 -msgid "" -"The smallest possible difference between non-equal :class:`.datetime` " -"objects, ``timedelta(microseconds=1)``." -msgstr "" - -#: ../../library/datetime.rst:1214 ../../library/datetime.rst:1837 -msgid "In ``range(24)``." -msgstr "" - -#: ../../library/datetime.rst:1219 ../../library/datetime.rst:1224 -#: ../../library/datetime.rst:1842 ../../library/datetime.rst:1847 -msgid "In ``range(60)``." -msgstr "" - -#: ../../library/datetime.rst:1229 ../../library/datetime.rst:1852 -msgid "In ``range(1000000)``." -msgstr "" - -#: ../../library/datetime.rst:1234 -msgid "" -"The object passed as the *tzinfo* argument to the :class:`.datetime` " -"constructor, or ``None`` if none was passed." -msgstr "" - -#: ../../library/datetime.rst:1240 ../../library/datetime.rst:1863 -msgid "" -"In ``[0, 1]``. Used to disambiguate wall times during a repeated interval. " -"(A repeated interval occurs when clocks are rolled back at the end of " -"daylight saving time or when the UTC offset for the current zone is " -"decreased for political reasons.) The values 0 and 1 represent, " -"respectively, the earlier and later of the two moments with the same wall " -"time representation." -msgstr "" - -#: ../../library/datetime.rst:1253 -msgid "``datetime2 = datetime1 + timedelta``" -msgstr "``datetime2 = datetime1 + timedelta``" - -#: ../../library/datetime.rst:1253 ../../library/datetime.rst:2490 -#: ../../library/datetime.rst:2495 ../../library/datetime.rst:2507 -#: ../../library/datetime.rst:2512 ../../library/datetime.rst:2572 -#: ../../library/datetime.rst:2577 ../../library/datetime.rst:2581 -msgid "\\(1)" -msgstr "\\(1)" - -#: ../../library/datetime.rst:1255 -msgid "``datetime2 = datetime1 - timedelta``" -msgstr "``datetime2 = datetime1 - timedelta``" - -#: ../../library/datetime.rst:1255 ../../library/datetime.rst:2523 -msgid "\\(2)" -msgstr "\\(2)" - -#: ../../library/datetime.rst:1257 -msgid "``timedelta = datetime1 - datetime2``" -msgstr "``timedelta = datetime1 - datetime2``" - -#: ../../library/datetime.rst:1259 -msgid "``datetime1 == datetime2``" -msgstr "``datetime1 == datetime2``" - -#: ../../library/datetime.rst:1260 -msgid "``datetime1 != datetime2``" -msgstr "``datetime1 != datetime2``" - -#: ../../library/datetime.rst:1262 -msgid "``datetime1 < datetime2``" -msgstr "``datetime1 < datetime2``" - -#: ../../library/datetime.rst:1263 -msgid "``datetime1 > datetime2``" -msgstr "``datetime1 > datetime2``" - -#: ../../library/datetime.rst:1264 -msgid "``datetime1 <= datetime2``" -msgstr "``datetime1 <= datetime2``" - -#: ../../library/datetime.rst:1265 -msgid "``datetime1 >= datetime2``" -msgstr "``datetime1 >= datetime2``" - -#: ../../library/datetime.rst:1269 -msgid "" -"``datetime2`` is a duration of ``timedelta`` removed from ``datetime1``, " -"moving forward in time if ``timedelta.days > 0``, or backward if ``timedelta." -"days < 0``. The result has the same :attr:`~.datetime.tzinfo` attribute as " -"the input datetime, and ``datetime2 - datetime1 == timedelta`` after. :exc:" -"`OverflowError` is raised if ``datetime2.year`` would be smaller than :const:" -"`MINYEAR` or larger than :const:`MAXYEAR`. Note that no time zone " -"adjustments are done even if the input is an aware object." -msgstr "" - -#: ../../library/datetime.rst:1278 -msgid "" -"Computes the ``datetime2`` such that ``datetime2 + timedelta == datetime1``. " -"As for addition, the result has the same :attr:`~.datetime.tzinfo` attribute " -"as the input datetime, and no time zone adjustments are done even if the " -"input is aware." -msgstr "" - -#: ../../library/datetime.rst:1283 -msgid "" -"Subtraction of a :class:`.datetime` from a :class:`.datetime` is defined " -"only if both operands are naive, or if both are aware. If one is aware and " -"the other is naive, :exc:`TypeError` is raised." -msgstr "" - -#: ../../library/datetime.rst:1287 -msgid "" -"If both are naive, or both are aware and have the same :attr:`~.datetime." -"tzinfo` attribute, the :attr:`~.datetime.tzinfo` attributes are ignored, and " -"the result is a :class:`timedelta` object ``t`` such that ``datetime2 + t == " -"datetime1``. No time zone adjustments are done in this case." -msgstr "" - -#: ../../library/datetime.rst:1292 -msgid "" -"If both are aware and have different :attr:`~.datetime.tzinfo` attributes, " -"``a-b`` acts as if ``a`` and ``b`` were first converted to naive UTC " -"datetimes. The result is ``(a.replace(tzinfo=None) - a.utcoffset()) - (b." -"replace(tzinfo=None) - b.utcoffset())`` except that the implementation never " -"overflows." -msgstr "" - -#: ../../library/datetime.rst:1298 -msgid "" -":class:`.datetime` objects are equal if they represent the same date and " -"time, taking into account the time zone." -msgstr "" - -#: ../../library/datetime.rst:1301 -msgid "Naive and aware :class:`!datetime` objects are never equal." -msgstr "" - -#: ../../library/datetime.rst:1303 -msgid "" -"If both comparands are aware, and have the same :attr:`!tzinfo` attribute, " -"the :attr:`!tzinfo` and :attr:`~.datetime.fold` attributes are ignored and " -"the base datetimes are compared. If both comparands are aware and have " -"different :attr:`~.datetime.tzinfo` attributes, the comparison acts as " -"comparands were first converted to UTC datetimes except that the " -"implementation never overflows. :class:`!datetime` instances in a repeated " -"interval are never equal to :class:`!datetime` instances in other time zone." -msgstr "" - -#: ../../library/datetime.rst:1313 -msgid "" -"*datetime1* is considered less than *datetime2* when *datetime1* precedes " -"*datetime2* in time, taking into account the time zone." -msgstr "" - -#: ../../library/datetime.rst:1316 -msgid "" -"Order comparison between naive and aware :class:`.datetime` objects raises :" -"exc:`TypeError`." -msgstr "" - -#: ../../library/datetime.rst:1319 -msgid "" -"If both comparands are aware, and have the same :attr:`!tzinfo` attribute, " -"the :attr:`!tzinfo` and :attr:`~.datetime.fold` attributes are ignored and " -"the base datetimes are compared. If both comparands are aware and have " -"different :attr:`~.datetime.tzinfo` attributes, the comparison acts as " -"comparands were first converted to UTC datetimes except that the " -"implementation never overflows." -msgstr "" - -#: ../../library/datetime.rst:1326 -msgid "" -"Equality comparisons between aware and naive :class:`.datetime` instances " -"don't raise :exc:`TypeError`." -msgstr "" - -#: ../../library/datetime.rst:1342 -msgid "Return :class:`date` object with same year, month and day." -msgstr "" - -#: ../../library/datetime.rst:1347 -msgid "" -"Return :class:`.time` object with same hour, minute, second, microsecond and " -"fold. :attr:`.tzinfo` is ``None``. See also method :meth:`timetz`." -msgstr "" - -#: ../../library/datetime.rst:1350 ../../library/datetime.rst:1359 -msgid "The fold value is copied to the returned :class:`.time` object." -msgstr "" - -#: ../../library/datetime.rst:1356 -msgid "" -"Return :class:`.time` object with same hour, minute, second, microsecond, " -"fold, and tzinfo attributes. See also method :meth:`time`." -msgstr "" - -#: ../../library/datetime.rst:1367 -msgid "" -"Return a new :class:`datetime` object with the same attributes, but with " -"specified parameters updated. Note that ``tzinfo=None`` can be specified to " -"create a naive datetime from an aware datetime with no conversion of date " -"and time data." -msgstr "" - -#: ../../library/datetime.rst:1372 -msgid "" -":class:`.datetime` objects are also supported by generic function :func:" -"`copy.replace`." -msgstr "" - -#: ../../library/datetime.rst:1381 -msgid "" -"Return a :class:`.datetime` object with new :attr:`.tzinfo` attribute *tz*, " -"adjusting the date and time data so the result is the same UTC time as " -"*self*, but in *tz*'s local time." -msgstr "" - -#: ../../library/datetime.rst:1385 -msgid "" -"If provided, *tz* must be an instance of a :class:`tzinfo` subclass, and " -"its :meth:`utcoffset` and :meth:`dst` methods must not return ``None``. If " -"*self* is naive, it is presumed to represent time in the system time zone." -msgstr "" - -#: ../../library/datetime.rst:1389 -msgid "" -"If called without arguments (or with ``tz=None``) the system local time zone " -"is assumed for the target time zone. The ``.tzinfo`` attribute of the " -"converted datetime instance will be set to an instance of :class:`timezone` " -"with the zone name and offset obtained from the OS." -msgstr "" - -#: ../../library/datetime.rst:1394 -msgid "" -"If ``self.tzinfo`` is *tz*, ``self.astimezone(tz)`` is equal to *self*: no " -"adjustment of date or time data is performed. Else the result is local time " -"in the time zone *tz*, representing the same UTC time as *self*: after " -"``astz = dt.astimezone(tz)``, ``astz - astz.utcoffset()`` will have the same " -"date and time data as ``dt - dt.utcoffset()``." -msgstr "" - -#: ../../library/datetime.rst:1400 -msgid "" -"If you merely want to attach a :class:`timezone` object *tz* to a datetime " -"*dt* without adjustment of date and time data, use ``dt." -"replace(tzinfo=tz)``. If you merely want to remove the :class:`!timezone` " -"object from an aware datetime *dt* without conversion of date and time data, " -"use ``dt.replace(tzinfo=None)``." -msgstr "" - -#: ../../library/datetime.rst:1405 -msgid "" -"Note that the default :meth:`tzinfo.fromutc` method can be overridden in a :" -"class:`tzinfo` subclass to affect the result returned by :meth:`astimezone`. " -"Ignoring error cases, :meth:`astimezone` acts like::" -msgstr "" - -#: ../../library/datetime.rst:1409 -msgid "" -"def astimezone(self, tz):\n" -" if self.tzinfo is tz:\n" -" return self\n" -" # Convert self to UTC, and attach the new timezone object.\n" -" utc = (self - self.utcoffset()).replace(tzinfo=tz)\n" -" # Convert from UTC to tz's local time.\n" -" return tz.fromutc(utc)" -msgstr "" - -#: ../../library/datetime.rst:1417 -msgid "*tz* now can be omitted." -msgstr "" - -#: ../../library/datetime.rst:1420 -msgid "" -"The :meth:`astimezone` method can now be called on naive instances that are " -"presumed to represent system local time." -msgstr "" - -#: ../../library/datetime.rst:1427 -msgid "" -"If :attr:`.tzinfo` is ``None``, returns ``None``, else returns ``self.tzinfo." -"utcoffset(self)``, and raises an exception if the latter doesn't return " -"``None`` or a :class:`timedelta` object with magnitude less than one day." -msgstr "" - -#: ../../library/datetime.rst:1431 ../../library/datetime.rst:2042 -#: ../../library/datetime.rst:2149 ../../library/datetime.rst:2394 -#: ../../library/datetime.rst:2406 ../../library/datetime.rst:2749 -msgid "The UTC offset is not restricted to a whole number of minutes." -msgstr "" - -#: ../../library/datetime.rst:1437 -msgid "" -"If :attr:`.tzinfo` is ``None``, returns ``None``, else returns ``self.tzinfo." -"dst(self)``, and raises an exception if the latter doesn't return ``None`` " -"or a :class:`timedelta` object with magnitude less than one day." -msgstr "" - -#: ../../library/datetime.rst:1441 ../../library/datetime.rst:2052 -#: ../../library/datetime.rst:2203 -msgid "The DST offset is not restricted to a whole number of minutes." -msgstr "" - -#: ../../library/datetime.rst:1447 -msgid "" -"If :attr:`.tzinfo` is ``None``, returns ``None``, else returns ``self.tzinfo." -"tzname(self)``, raises an exception if the latter doesn't return ``None`` or " -"a string object," -msgstr "" - -#: ../../library/datetime.rst:1458 -msgid "" -"time.struct_time((d.year, d.month, d.day,\n" -" d.hour, d.minute, d.second,\n" -" d.weekday(), yday, dst))" -msgstr "" -"time.struct_time((d.year, d.month, d.day,\n" -" d.hour, d.minute, d.second,\n" -" d.weekday(), yday, dst))" - -#: ../../library/datetime.rst:1462 -msgid "" -"where ``yday = d.toordinal() - date(d.year, 1, 1).toordinal() + 1`` is the " -"day number within the current year starting with 1 for January 1st. The :" -"attr:`~time.struct_time.tm_isdst` flag of the result is set according to " -"the :meth:`dst` method: :attr:`.tzinfo` is ``None`` or :meth:`dst` returns " -"``None``, :attr:`!tm_isdst` is set to ``-1``; else if :meth:`dst` returns a " -"non-zero value, :attr:`!tm_isdst` is set to 1; else :attr:`!tm_isdst` is set " -"to 0." -msgstr "" - -#: ../../library/datetime.rst:1473 -msgid "" -"If :class:`.datetime` instance ``d`` is naive, this is the same as ``d." -"timetuple()`` except that :attr:`~.time.struct_time.tm_isdst` is forced to 0 " -"regardless of what ``d.dst()`` returns. DST is never in effect for a UTC " -"time." -msgstr "" - -#: ../../library/datetime.rst:1477 -msgid "" -"If ``d`` is aware, ``d`` is normalized to UTC time, by subtracting ``d." -"utcoffset()``, and a :class:`time.struct_time` for the normalized time is " -"returned. :attr:`!tm_isdst` is forced to 0. Note that an :exc:" -"`OverflowError` may be raised if ``d.year`` was ``MINYEAR`` or ``MAXYEAR`` " -"and UTC adjustment spills over a year boundary." -msgstr "" - -#: ../../library/datetime.rst:1486 -msgid "" -"Because naive ``datetime`` objects are treated by many ``datetime`` methods " -"as local times, it is preferred to use aware datetimes to represent times in " -"UTC; as a result, using :meth:`datetime.utctimetuple` may give misleading " -"results. If you have a naive ``datetime`` representing UTC, use ``datetime." -"replace(tzinfo=timezone.utc)`` to make it aware, at which point you can use :" -"meth:`.datetime.timetuple`." -msgstr "" - -#: ../../library/datetime.rst:1495 -msgid "" -"Return the proleptic Gregorian ordinal of the date. The same as ``self." -"date().toordinal()``." -msgstr "" - -#: ../../library/datetime.rst:1500 -msgid "" -"Return POSIX timestamp corresponding to the :class:`.datetime` instance. The " -"return value is a :class:`float` similar to that returned by :func:`time." -"time`." -msgstr "" - -#: ../../library/datetime.rst:1504 -msgid "" -"Naive :class:`.datetime` instances are assumed to represent local time and " -"this method relies on the platform C :c:func:`mktime` function to perform " -"the conversion. Since :class:`.datetime` supports wider range of values " -"than :c:func:`mktime` on many platforms, this method may raise :exc:" -"`OverflowError` or :exc:`OSError` for times far in the past or far in the " -"future." -msgstr "" - -#: ../../library/datetime.rst:1511 -msgid "" -"For aware :class:`.datetime` instances, the return value is computed as::" -msgstr "" - -#: ../../library/datetime.rst:1514 -msgid "(dt - datetime(1970, 1, 1, tzinfo=timezone.utc)).total_seconds()" -msgstr "(dt - datetime(1970, 1, 1, tzinfo=timezone.utc)).total_seconds()" - -#: ../../library/datetime.rst:1518 -msgid "" -"The :meth:`timestamp` method uses the :attr:`.fold` attribute to " -"disambiguate the times during a repeated interval." -msgstr "" - -#: ../../library/datetime.rst:1524 -msgid "" -"There is no method to obtain the POSIX timestamp directly from a naive :" -"class:`.datetime` instance representing UTC time. If your application uses " -"this convention and your system time zone is not set to UTC, you can obtain " -"the POSIX timestamp by supplying ``tzinfo=timezone.utc``::" -msgstr "" - -#: ../../library/datetime.rst:1530 -msgid "timestamp = dt.replace(tzinfo=timezone.utc).timestamp()" -msgstr "timestamp = dt.replace(tzinfo=timezone.utc).timestamp()" - -#: ../../library/datetime.rst:1532 -msgid "or by calculating the timestamp directly::" -msgstr "" - -#: ../../library/datetime.rst:1534 -msgid "timestamp = (dt - datetime(1970, 1, 1)) / timedelta(seconds=1)" -msgstr "timestamp = (dt - datetime(1970, 1, 1)) / timedelta(seconds=1)" - -#: ../../library/datetime.rst:1538 -msgid "" -"Return the day of the week as an integer, where Monday is 0 and Sunday is 6. " -"The same as ``self.date().weekday()``. See also :meth:`isoweekday`." -msgstr "" - -#: ../../library/datetime.rst:1544 -msgid "" -"Return the day of the week as an integer, where Monday is 1 and Sunday is 7. " -"The same as ``self.date().isoweekday()``. See also :meth:`weekday`, :meth:" -"`isocalendar`." -msgstr "" - -#: ../../library/datetime.rst:1551 -msgid "" -"Return a :term:`named tuple` with three components: ``year``, ``week`` and " -"``weekday``. The same as ``self.date().isocalendar()``." -msgstr "" - -#: ../../library/datetime.rst:1557 -msgid "Return a string representing the date and time in ISO 8601 format:" -msgstr "" - -#: ../../library/datetime.rst:1559 -msgid "``YYYY-MM-DDTHH:MM:SS.ffffff``, if :attr:`microsecond` is not 0" -msgstr "``YYYY-MM-DDTHH:MM:SS.ffffff``，如果 :attr:`microsecond` 不是 0" - -#: ../../library/datetime.rst:1560 -msgid "``YYYY-MM-DDTHH:MM:SS``, if :attr:`microsecond` is 0" -msgstr "``YYYY-MM-DDTHH:MM:SS``，如果 :attr:`microsecond` 是 0" - -#: ../../library/datetime.rst:1562 -msgid "" -"If :meth:`utcoffset` does not return ``None``, a string is appended, giving " -"the UTC offset:" -msgstr "" -"如果 :meth:`utcoffset` 没有回傳 ``None``，則會附加一个字串，給出 UTC 偏移：" - -#: ../../library/datetime.rst:1565 -msgid "" -"``YYYY-MM-DDTHH:MM:SS.ffffff+HH:MM[:SS[.ffffff]]``, if :attr:`microsecond` " -"is not 0" -msgstr "" -"``YYYY-MM-DDTHH:MM:SS.ffffff+HH:MM[:SS[.ffffff]]``，如果 :attr:`microsecond` " -"不是 0" - -#: ../../library/datetime.rst:1567 -msgid "" -"``YYYY-MM-DDTHH:MM:SS+HH:MM[:SS[.ffffff]]``, if :attr:`microsecond` is 0" -msgstr "" -"``YYYY-MM-DDTHH:MM:SS+HH:MM[:SS[.ffffff]]``，如果 :attr:`microsecond` 是 0" - -#: ../../library/datetime.rst:1571 -msgid "" -">>> from datetime import datetime, timezone\n" -">>> datetime(2019, 5, 18, 15, 17, 8, 132263).isoformat()\n" -"'2019-05-18T15:17:08.132263'\n" -">>> datetime(2019, 5, 18, 15, 17, tzinfo=timezone.utc).isoformat()\n" -"'2019-05-18T15:17:00+00:00'" -msgstr "" -">>> from datetime import datetime, timezone\n" -">>> datetime(2019, 5, 18, 15, 17, 8, 132263).isoformat()\n" -"'2019-05-18T15:17:08.132263'\n" -">>> datetime(2019, 5, 18, 15, 17, tzinfo=timezone.utc).isoformat()\n" -"'2019-05-18T15:17:00+00:00'" - -#: ../../library/datetime.rst:1577 -msgid "" -"The optional argument *sep* (default ``'T'``) is a one-character separator, " -"placed between the date and time portions of the result. For example::" -msgstr "" - -#: ../../library/datetime.rst:1580 -msgid "" -">>> from datetime import tzinfo, timedelta, datetime\n" -">>> class TZ(tzinfo):\n" -"... \"\"\"A time zone with an arbitrary, constant -06:39 offset.\"\"\"\n" -"... def utcoffset(self, dt):\n" -"... return timedelta(hours=-6, minutes=-39)\n" -"...\n" -">>> datetime(2002, 12, 25, tzinfo=TZ()).isoformat(' ')\n" -"'2002-12-25 00:00:00-06:39'\n" -">>> datetime(2009, 11, 27, microsecond=100, tzinfo=TZ()).isoformat()\n" -"'2009-11-27T00:00:00.000100-06:39'" -msgstr "" -">>> from datetime import tzinfo, timedelta, datetime\n" -">>> class TZ(tzinfo):\n" -"... \"\"\"A time zone with an arbitrary, constant -06:39 offset.\"\"\"\n" -"... def utcoffset(self, dt):\n" -"... return timedelta(hours=-6, minutes=-39)\n" -"...\n" -">>> datetime(2002, 12, 25, tzinfo=TZ()).isoformat(' ')\n" -"'2002-12-25 00:00:00-06:39'\n" -">>> datetime(2009, 11, 27, microsecond=100, tzinfo=TZ()).isoformat()\n" -"'2009-11-27T00:00:00.000100-06:39'" - -#: ../../library/datetime.rst:1591 ../../library/datetime.rst:1982 -msgid "" -"The optional argument *timespec* specifies the number of additional " -"components of the time to include (the default is ``'auto'``). It can be one " -"of the following:" -msgstr "" - -#: ../../library/datetime.rst:1595 ../../library/datetime.rst:1986 -msgid "" -"``'auto'``: Same as ``'seconds'`` if :attr:`microsecond` is 0, same as " -"``'microseconds'`` otherwise." -msgstr "" - -#: ../../library/datetime.rst:1597 ../../library/datetime.rst:1988 -msgid "``'hours'``: Include the :attr:`hour` in the two-digit ``HH`` format." -msgstr "" - -#: ../../library/datetime.rst:1598 ../../library/datetime.rst:1989 -msgid "" -"``'minutes'``: Include :attr:`hour` and :attr:`minute` in ``HH:MM`` format." -msgstr "" - -#: ../../library/datetime.rst:1599 ../../library/datetime.rst:1990 -msgid "" -"``'seconds'``: Include :attr:`hour`, :attr:`minute`, and :attr:`second` in " -"``HH:MM:SS`` format." -msgstr "" - -#: ../../library/datetime.rst:1601 ../../library/datetime.rst:1992 -msgid "" -"``'milliseconds'``: Include full time, but truncate fractional second part " -"to milliseconds. ``HH:MM:SS.sss`` format." -msgstr "" - -#: ../../library/datetime.rst:1603 ../../library/datetime.rst:1994 -msgid "``'microseconds'``: Include full time in ``HH:MM:SS.ffffff`` format." -msgstr "" - -#: ../../library/datetime.rst:1607 ../../library/datetime.rst:1998 -msgid "Excluded time components are truncated, not rounded." -msgstr "" - -#: ../../library/datetime.rst:1609 -msgid ":exc:`ValueError` will be raised on an invalid *timespec* argument::" -msgstr "" - -#: ../../library/datetime.rst:1612 -msgid "" -">>> from datetime import datetime\n" -">>> datetime.now().isoformat(timespec='minutes')\n" -"'2002-12-25T00:00'\n" -">>> dt = datetime(2015, 1, 1, 12, 30, 59, 0)\n" -">>> dt.isoformat(timespec='microseconds')\n" -"'2015-01-01T12:30:59.000000'" -msgstr "" -">>> from datetime import datetime\n" -">>> datetime.now().isoformat(timespec='minutes')\n" -"'2002-12-25T00:00'\n" -">>> dt = datetime(2015, 1, 1, 12, 30, 59, 0)\n" -">>> dt.isoformat(timespec='microseconds')\n" -"'2015-01-01T12:30:59.000000'" - -#: ../../library/datetime.rst:1619 ../../library/datetime.rst:2013 -msgid "Added the *timespec* parameter." -msgstr "新增 *timespec* 參數。" - -#: ../../library/datetime.rst:1625 -msgid "" -"For a :class:`.datetime` instance ``d``, ``str(d)`` is equivalent to ``d." -"isoformat(' ')``." -msgstr "" - -#: ../../library/datetime.rst:1631 -msgid "Return a string representing the date and time::" -msgstr "" - -#: ../../library/datetime.rst:1633 -msgid "" -">>> from datetime import datetime\n" -">>> datetime(2002, 12, 4, 20, 30, 40).ctime()\n" -"'Wed Dec 4 20:30:40 2002'" -msgstr "" -">>> from datetime import datetime\n" -">>> datetime(2002, 12, 4, 20, 30, 40).ctime()\n" -"'Wed Dec 4 20:30:40 2002'" - -#: ../../library/datetime.rst:1637 -msgid "" -"The output string will *not* include time zone information, regardless of " -"whether the input is aware or naive." -msgstr "" - -#: ../../library/datetime.rst:1644 -msgid "" -"on platforms where the native C :c:func:`ctime` function (which :func:`time." -"ctime` invokes, but which :meth:`datetime.ctime` does not invoke) conforms " -"to the C standard." -msgstr "" - -#: ../../library/datetime.rst:1651 -msgid "" -"Return a string representing the date and time, controlled by an explicit " -"format string. See also :ref:`strftime-strptime-behavior` and :meth:" -"`datetime.isoformat`." -msgstr "" - -#: ../../library/datetime.rst:1658 -msgid "" -"Same as :meth:`.datetime.strftime`. This makes it possible to specify a " -"format string for a :class:`.datetime` object in :ref:`formatted string " -"literals ` and when using :meth:`str.format`. See also :ref:" -"`strftime-strptime-behavior` and :meth:`datetime.isoformat`." -msgstr "" - -#: ../../library/datetime.rst:1665 -msgid "Examples of Usage: :class:`.datetime`" -msgstr "用法範例：:class:`.datetime`" - -#: ../../library/datetime.rst:1667 -msgid "Examples of working with :class:`.datetime` objects:" -msgstr "更多 :class:`.datetime` 的用法範例：" - -#: ../../library/datetime.rst:1669 -msgid "" -">>> from datetime import datetime, date, time, timezone\n" -"\n" -">>> # Using datetime.combine()\n" -">>> d = date(2005, 7, 14)\n" -">>> t = time(12, 30)\n" -">>> datetime.combine(d, t)\n" -"datetime.datetime(2005, 7, 14, 12, 30)\n" -"\n" -">>> # Using datetime.now()\n" -">>> datetime.now()\n" -"datetime.datetime(2007, 12, 6, 16, 29, 43, 79043) # GMT +1\n" -">>> datetime.now(timezone.utc)\n" -"datetime.datetime(2007, 12, 6, 15, 29, 43, 79060, tzinfo=datetime.timezone." -"utc)\n" -"\n" -">>> # Using datetime.strptime()\n" -">>> dt = datetime.strptime(\"21/11/06 16:30\", \"%d/%m/%y %H:%M\")\n" -">>> dt\n" -"datetime.datetime(2006, 11, 21, 16, 30)\n" -"\n" -">>> # Using datetime.timetuple() to get tuple of all attributes\n" -">>> tt = dt.timetuple()\n" -">>> for it in tt:\n" -"... print(it)\n" -"...\n" -"2006 # year\n" -"11 # month\n" -"21 # day\n" -"16 # hour\n" -"30 # minute\n" -"0 # second\n" -"1 # weekday (0 = Monday)\n" -"325 # number of days since 1st January\n" -"-1 # dst - method tzinfo.dst() returned None\n" -"\n" -">>> # Date in ISO format\n" -">>> ic = dt.isocalendar()\n" -">>> for it in ic:\n" -"... print(it)\n" -"...\n" -"2006 # ISO year\n" -"47 # ISO week\n" -"2 # ISO weekday\n" -"\n" -">>> # Formatting a datetime\n" -">>> dt.strftime(\"%A, %d. %B %Y %I:%M%p\")\n" -"'Tuesday, 21. November 2006 04:30PM'\n" -">>> 'The {1} is {0:%d}, the {2} is {0:%B}, the {3} is {0:%I:%M%p}.'." -"format(dt, \"day\", \"month\", \"time\")\n" -"'The day is 21, the month is November, the time is 04:30PM.'" -msgstr "" - -#: ../../library/datetime.rst:1720 -msgid "" -"The example below defines a :class:`tzinfo` subclass capturing time zone " -"information for Kabul, Afghanistan, which used +4 UTC until 1945 and then " -"+4:30 UTC thereafter::" -msgstr "" - -#: ../../library/datetime.rst:1724 -msgid "" -"from datetime import timedelta, datetime, tzinfo, timezone\n" -"\n" -"class KabulTz(tzinfo):\n" -" # Kabul used +4 until 1945, when they moved to +4:30\n" -" UTC_MOVE_DATE = datetime(1944, 12, 31, 20, tzinfo=timezone.utc)\n" -"\n" -" def utcoffset(self, dt):\n" -" if dt.year < 1945:\n" -" return timedelta(hours=4)\n" -" elif (1945, 1, 1, 0, 0) <= dt.timetuple()[:5] < (1945, 1, 1, 0, " -"30):\n" -" # An ambiguous (\"imaginary\") half-hour range representing\n" -" # a 'fold' in time due to the shift from +4 to +4:30.\n" -" # If dt falls in the imaginary range, use fold to decide how\n" -" # to resolve. See PEP495.\n" -" return timedelta(hours=4, minutes=(30 if dt.fold else 0))\n" -" else:\n" -" return timedelta(hours=4, minutes=30)\n" -"\n" -" def fromutc(self, dt):\n" -" # Follow same validations as in datetime.tzinfo\n" -" if not isinstance(dt, datetime):\n" -" raise TypeError(\"fromutc() requires a datetime argument\")\n" -" if dt.tzinfo is not self:\n" -" raise ValueError(\"dt.tzinfo is not self\")\n" -"\n" -" # A custom implementation is required for fromutc as\n" -" # the input to this function is a datetime with utc values\n" -" # but with a tzinfo set to self.\n" -" # See datetime.astimezone or fromtimestamp.\n" -" if dt.replace(tzinfo=timezone.utc) >= self.UTC_MOVE_DATE:\n" -" return dt + timedelta(hours=4, minutes=30)\n" -" else:\n" -" return dt + timedelta(hours=4)\n" -"\n" -" def dst(self, dt):\n" -" # Kabul does not observe daylight saving time.\n" -" return timedelta(0)\n" -"\n" -" def tzname(self, dt):\n" -" if dt >= self.UTC_MOVE_DATE:\n" -" return \"+04:30\"\n" -" return \"+04\"" -msgstr "" - -#: ../../library/datetime.rst:1767 -msgid "Usage of ``KabulTz`` from above::" -msgstr "" - -#: ../../library/datetime.rst:1769 -msgid "" -">>> tz1 = KabulTz()\n" -"\n" -">>> # Datetime before the change\n" -">>> dt1 = datetime(1900, 11, 21, 16, 30, tzinfo=tz1)\n" -">>> print(dt1.utcoffset())\n" -"4:00:00\n" -"\n" -">>> # Datetime after the change\n" -">>> dt2 = datetime(2006, 6, 14, 13, 0, tzinfo=tz1)\n" -">>> print(dt2.utcoffset())\n" -"4:30:00\n" -"\n" -">>> # Convert datetime to another time zone\n" -">>> dt3 = dt2.astimezone(timezone.utc)\n" -">>> dt3\n" -"datetime.datetime(2006, 6, 14, 8, 30, tzinfo=datetime.timezone.utc)\n" -">>> dt2\n" -"datetime.datetime(2006, 6, 14, 13, 0, tzinfo=KabulTz())\n" -">>> dt2 == dt3\n" -"True" -msgstr "" - -#: ../../library/datetime.rst:1793 -msgid ":class:`.time` Objects" -msgstr ":class:`.time` 物件" - -#: ../../library/datetime.rst:1795 -msgid "" -"A :class:`.time` object represents a (local) time of day, independent of any " -"particular day, and subject to adjustment via a :class:`tzinfo` object." -msgstr "" - -#: ../../library/datetime.rst:1800 -msgid "" -"All arguments are optional. *tzinfo* may be ``None``, or an instance of a :" -"class:`tzinfo` subclass. The remaining arguments must be integers in the " -"following ranges:" -msgstr "" - -#: ../../library/datetime.rst:1810 -msgid "" -"If an argument outside those ranges is given, :exc:`ValueError` is raised. " -"All default to 0 except *tzinfo*, which defaults to ``None``." -msgstr "" - -#: ../../library/datetime.rst:1818 -msgid "The earliest representable :class:`.time`, ``time(0, 0, 0, 0)``." -msgstr "" - -#: ../../library/datetime.rst:1823 -msgid "The latest representable :class:`.time`, ``time(23, 59, 59, 999999)``." -msgstr "" - -#: ../../library/datetime.rst:1828 -msgid "" -"The smallest possible difference between non-equal :class:`.time` objects, " -"``timedelta(microseconds=1)``, although note that arithmetic on :class:`." -"time` objects is not supported." -msgstr "" - -#: ../../library/datetime.rst:1857 -msgid "" -"The object passed as the tzinfo argument to the :class:`.time` constructor, " -"or ``None`` if none was passed." -msgstr "" - -#: ../../library/datetime.rst:1871 -msgid "" -":class:`.time` objects support equality and order comparisons, where ``a`` " -"is considered less than ``b`` when ``a`` precedes ``b`` in time." -msgstr "" - -#: ../../library/datetime.rst:1874 -msgid "" -"Naive and aware :class:`!time` objects are never equal. Order comparison " -"between naive and aware :class:`!time` objects raises :exc:`TypeError`." -msgstr "" - -#: ../../library/datetime.rst:1878 -msgid "" -"If both comparands are aware, and have the same :attr:`~.time.tzinfo` " -"attribute, the :attr:`!tzinfo` and :attr:`!fold` attributes are ignored and " -"the base times are compared. If both comparands are aware and have " -"different :attr:`!tzinfo` attributes, the comparands are first adjusted by " -"subtracting their UTC offsets (obtained from ``self.utcoffset()``)." -msgstr "" - -#: ../../library/datetime.rst:1884 -msgid "" -"Equality comparisons between aware and naive :class:`.time` instances don't " -"raise :exc:`TypeError`." -msgstr "" - -#: ../../library/datetime.rst:1888 -msgid "" -"In Boolean contexts, a :class:`.time` object is always considered to be true." -msgstr "" - -#: ../../library/datetime.rst:1890 -msgid "" -"Before Python 3.5, a :class:`.time` object was considered to be false if it " -"represented midnight in UTC. This behavior was considered obscure and error-" -"prone and has been removed in Python 3.5. See :issue:`13936` for full " -"details." -msgstr "" - -#: ../../library/datetime.rst:1897 -msgid "Other constructors:" -msgstr "其他建構函式：" - -#: ../../library/datetime.rst:1901 -msgid "" -"Return a :class:`.time` corresponding to a *time_string* in any valid ISO " -"8601 format, with the following exceptions:" -msgstr "" - -#: ../../library/datetime.rst:1905 -msgid "" -"The leading ``T``, normally required in cases where there may be ambiguity " -"between a date and a time, is not required." -msgstr "" - -#: ../../library/datetime.rst:1907 -msgid "" -"Fractional seconds may have any number of digits (anything beyond 6 will be " -"truncated)." -msgstr "" - -#: ../../library/datetime.rst:1911 -msgid "Examples:" -msgstr "範例： ::" - -#: ../../library/datetime.rst:1913 -msgid "" -">>> from datetime import time\n" -">>> time.fromisoformat('04:23:01')\n" -"datetime.time(4, 23, 1)\n" -">>> time.fromisoformat('T04:23:01')\n" -"datetime.time(4, 23, 1)\n" -">>> time.fromisoformat('T042301')\n" -"datetime.time(4, 23, 1)\n" -">>> time.fromisoformat('04:23:01.000384')\n" -"datetime.time(4, 23, 1, 384)\n" -">>> time.fromisoformat('04:23:01,000384')\n" -"datetime.time(4, 23, 1, 384)\n" -">>> time.fromisoformat('04:23:01+04:00')\n" -"datetime.time(4, 23, 1, tzinfo=datetime.timezone(datetime." -"timedelta(seconds=14400)))\n" -">>> time.fromisoformat('04:23:01Z')\n" -"datetime.time(4, 23, 1, tzinfo=datetime.timezone.utc)\n" -">>> time.fromisoformat('04:23:01+00:00')\n" -"datetime.time(4, 23, 1, tzinfo=datetime.timezone.utc)" -msgstr "" -">>> from datetime import time\n" -">>> time.fromisoformat('04:23:01')\n" -"datetime.time(4, 23, 1)\n" -">>> time.fromisoformat('T04:23:01')\n" -"datetime.time(4, 23, 1)\n" -">>> time.fromisoformat('T042301')\n" -"datetime.time(4, 23, 1)\n" -">>> time.fromisoformat('04:23:01.000384')\n" -"datetime.time(4, 23, 1, 384)\n" -">>> time.fromisoformat('04:23:01,000384')\n" -"datetime.time(4, 23, 1, 384)\n" -">>> time.fromisoformat('04:23:01+04:00')\n" -"datetime.time(4, 23, 1, tzinfo=datetime.timezone(datetime." -"timedelta(seconds=14400)))\n" -">>> time.fromisoformat('04:23:01Z')\n" -"datetime.time(4, 23, 1, tzinfo=datetime.timezone.utc)\n" -">>> time.fromisoformat('04:23:01+00:00')\n" -"datetime.time(4, 23, 1, tzinfo=datetime.timezone.utc)" - -#: ../../library/datetime.rst:1935 -msgid "" -"Previously, this method only supported formats that could be emitted by :" -"meth:`time.isoformat`." -msgstr "" - -#: ../../library/datetime.rst:1941 -msgid "" -"Return a :class:`.time` corresponding to *date_string*, parsed according to " -"*format*." -msgstr "" - -#: ../../library/datetime.rst:1944 -msgid "" -"If *format* does not contain microseconds or timezone information, this is " -"equivalent to::" -msgstr "" - -#: ../../library/datetime.rst:1946 -msgid "time(*(time.strptime(date_string, format)[3:6]))" -msgstr "time(*(time.strptime(date_string, format)[3:6]))" - -#: ../../library/datetime.rst:1948 -msgid "" -":exc:`ValueError` is raised if the *date_string* and *format* cannot be " -"parsed by :func:`time.strptime` or if it returns a value which is not a time " -"tuple. See also :ref:`strftime-strptime-behavior` and :meth:`time." -"fromisoformat`." -msgstr "" - -#: ../../library/datetime.rst:1961 -msgid "" -"Return a new :class:`.time` with the same values, but with specified " -"parameters updated. Note that ``tzinfo=None`` can be specified to create a " -"naive :class:`.time` from an aware :class:`.time`, without conversion of the " -"time data." -msgstr "" - -#: ../../library/datetime.rst:1966 -msgid "" -":class:`.time` objects are also supported by generic function :func:`copy." -"replace`." -msgstr "" - -#: ../../library/datetime.rst:1975 -msgid "Return a string representing the time in ISO 8601 format, one of:" -msgstr "" - -#: ../../library/datetime.rst:1977 -msgid "``HH:MM:SS.ffffff``, if :attr:`microsecond` is not 0" -msgstr "" - -#: ../../library/datetime.rst:1978 -msgid "``HH:MM:SS``, if :attr:`microsecond` is 0" -msgstr "" - -#: ../../library/datetime.rst:1979 -msgid "" -"``HH:MM:SS.ffffff+HH:MM[:SS[.ffffff]]``, if :meth:`utcoffset` does not " -"return ``None``" -msgstr "" - -#: ../../library/datetime.rst:1980 -msgid "" -"``HH:MM:SS+HH:MM[:SS[.ffffff]]``, if :attr:`microsecond` is 0 and :meth:" -"`utcoffset` does not return ``None``" -msgstr "" - -#: ../../library/datetime.rst:2000 -msgid ":exc:`ValueError` will be raised on an invalid *timespec* argument." -msgstr "" - -#: ../../library/datetime.rst:2004 -msgid "" -">>> from datetime import time\n" -">>> time(hour=12, minute=34, second=56, microsecond=123456)." -"isoformat(timespec='minutes')\n" -"'12:34'\n" -">>> dt = time(hour=12, minute=34, second=56, microsecond=0)\n" -">>> dt.isoformat(timespec='microseconds')\n" -"'12:34:56.000000'\n" -">>> dt.isoformat(timespec='auto')\n" -"'12:34:56'" -msgstr "" -">>> from datetime import time\n" -">>> time(hour=12, minute=34, second=56, microsecond=123456)." -"isoformat(timespec='minutes')\n" -"'12:34'\n" -">>> dt = time(hour=12, minute=34, second=56, microsecond=0)\n" -">>> dt.isoformat(timespec='microseconds')\n" -"'12:34:56.000000'\n" -">>> dt.isoformat(timespec='auto')\n" -"'12:34:56'" - -#: ../../library/datetime.rst:2019 -msgid "For a time ``t``, ``str(t)`` is equivalent to ``t.isoformat()``." -msgstr "" - -#: ../../library/datetime.rst:2024 -msgid "" -"Return a string representing the time, controlled by an explicit format " -"string. See also :ref:`strftime-strptime-behavior` and :meth:`time." -"isoformat`." -msgstr "" - -#: ../../library/datetime.rst:2030 -msgid "" -"Same as :meth:`.time.strftime`. This makes it possible to specify a format " -"string for a :class:`.time` object in :ref:`formatted string literals ` and when using :meth:`str.format`. See also :ref:`strftime-" -"strptime-behavior` and :meth:`time.isoformat`." -msgstr "" - -#: ../../library/datetime.rst:2038 -msgid "" -"If :attr:`.tzinfo` is ``None``, returns ``None``, else returns ``self.tzinfo." -"utcoffset(None)``, and raises an exception if the latter doesn't return " -"``None`` or a :class:`timedelta` object with magnitude less than one day." -msgstr "" - -#: ../../library/datetime.rst:2048 -msgid "" -"If :attr:`.tzinfo` is ``None``, returns ``None``, else returns ``self.tzinfo." -"dst(None)``, and raises an exception if the latter doesn't return ``None``, " -"or a :class:`timedelta` object with magnitude less than one day." -msgstr "" - -#: ../../library/datetime.rst:2057 -msgid "" -"If :attr:`.tzinfo` is ``None``, returns ``None``, else returns ``self.tzinfo." -"tzname(None)``, or raises an exception if the latter doesn't return ``None`` " -"or a string object." -msgstr "" - -#: ../../library/datetime.rst:2062 -msgid "Examples of Usage: :class:`.time`" -msgstr "用法範例：:class:`.time`" - -#: ../../library/datetime.rst:2064 -msgid "Examples of working with a :class:`.time` object::" -msgstr "" - -#: ../../library/datetime.rst:2066 -msgid "" -">>> from datetime import time, tzinfo, timedelta\n" -">>> class TZ1(tzinfo):\n" -"... def utcoffset(self, dt):\n" -"... return timedelta(hours=1)\n" -"... def dst(self, dt):\n" -"... return timedelta(0)\n" -"... def tzname(self,dt):\n" -"... return \"+01:00\"\n" -"... def __repr__(self):\n" -"... return f\"{self.__class__.__name__}()\"\n" -"...\n" -">>> t = time(12, 10, 30, tzinfo=TZ1())\n" -">>> t\n" -"datetime.time(12, 10, 30, tzinfo=TZ1())\n" -">>> t.isoformat()\n" -"'12:10:30+01:00'\n" -">>> t.dst()\n" -"datetime.timedelta(0)\n" -">>> t.tzname()\n" -"'+01:00'\n" -">>> t.strftime(\"%H:%M:%S %Z\")\n" -"'12:10:30 +01:00'\n" -">>> 'The {} is {:%H:%M}.'.format(\"time\", t)\n" -"'The time is 12:10.'" -msgstr "" -">>> from datetime import time, tzinfo, timedelta\n" -">>> class TZ1(tzinfo):\n" -"... def utcoffset(self, dt):\n" -"... return timedelta(hours=1)\n" -"... def dst(self, dt):\n" -"... return timedelta(0)\n" -"... def tzname(self,dt):\n" -"... return \"+01:00\"\n" -"... def __repr__(self):\n" -"... return f\"{self.__class__.__name__}()\"\n" -"...\n" -">>> t = time(12, 10, 30, tzinfo=TZ1())\n" -">>> t\n" -"datetime.time(12, 10, 30, tzinfo=TZ1())\n" -">>> t.isoformat()\n" -"'12:10:30+01:00'\n" -">>> t.dst()\n" -"datetime.timedelta(0)\n" -">>> t.tzname()\n" -"'+01:00'\n" -">>> t.strftime(\"%H:%M:%S %Z\")\n" -"'12:10:30 +01:00'\n" -">>> 'The {} is {:%H:%M}.'.format(\"time\", t)\n" -"'The time is 12:10.'" - -#: ../../library/datetime.rst:2095 -msgid ":class:`tzinfo` Objects" -msgstr ":class:`tzinfo` 物件" - -#: ../../library/datetime.rst:2099 -msgid "" -"This is an abstract base class, meaning that this class should not be " -"instantiated directly. Define a subclass of :class:`tzinfo` to capture " -"information about a particular time zone." -msgstr "" - -#: ../../library/datetime.rst:2103 -msgid "" -"An instance of (a concrete subclass of) :class:`tzinfo` can be passed to the " -"constructors for :class:`.datetime` and :class:`.time` objects. The latter " -"objects view their attributes as being in local time, and the :class:" -"`tzinfo` object supports methods revealing offset of local time from UTC, " -"the name of the time zone, and DST offset, all relative to a date or time " -"object passed to them." -msgstr "" - -#: ../../library/datetime.rst:2109 -msgid "" -"You need to derive a concrete subclass, and (at least) supply " -"implementations of the standard :class:`tzinfo` methods needed by the :class:" -"`.datetime` methods you use. The :mod:`!datetime` module provides :class:" -"`timezone`, a simple concrete subclass of :class:`tzinfo` which can " -"represent time zones with fixed offset from UTC such as UTC itself or North " -"American EST and EDT." -msgstr "" - -#: ../../library/datetime.rst:2116 -msgid "" -"Special requirement for pickling: A :class:`tzinfo` subclass must have an :" -"meth:`~object.__init__` method that can be called with no arguments, " -"otherwise it can be pickled but possibly not unpickled again. This is a " -"technical requirement that may be relaxed in the future." -msgstr "" - -#: ../../library/datetime.rst:2122 -msgid "" -"A concrete subclass of :class:`tzinfo` may need to implement the following " -"methods. Exactly which methods are needed depends on the uses made of aware :" -"mod:`!datetime` objects. If in doubt, simply implement all of them." -msgstr "" - -#: ../../library/datetime.rst:2129 -msgid "" -"Return offset of local time from UTC, as a :class:`timedelta` object that is " -"positive east of UTC. If local time is west of UTC, this should be negative." -msgstr "" - -#: ../../library/datetime.rst:2132 -msgid "" -"This represents the *total* offset from UTC; for example, if a :class:" -"`tzinfo` object represents both time zone and DST adjustments, :meth:" -"`utcoffset` should return their sum. If the UTC offset isn't known, return " -"``None``. Else the value returned must be a :class:`timedelta` object " -"strictly between ``-timedelta(hours=24)`` and ``timedelta(hours=24)`` (the " -"magnitude of the offset must be less than one day). Most implementations of :" -"meth:`utcoffset` will probably look like one of these two::" -msgstr "" - -#: ../../library/datetime.rst:2140 -msgid "" -"return CONSTANT # fixed-offset class\n" -"return CONSTANT + self.dst(dt) # daylight-aware class" -msgstr "" - -#: ../../library/datetime.rst:2143 -msgid "" -"If :meth:`utcoffset` does not return ``None``, :meth:`dst` should not return " -"``None`` either." -msgstr "" - -#: ../../library/datetime.rst:2146 -msgid "" -"The default implementation of :meth:`utcoffset` raises :exc:" -"`NotImplementedError`." -msgstr "" - -#: ../../library/datetime.rst:2155 -msgid "" -"Return the daylight saving time (DST) adjustment, as a :class:`timedelta` " -"object or ``None`` if DST information isn't known." -msgstr "" - -#: ../../library/datetime.rst:2159 -msgid "" -"Return ``timedelta(0)`` if DST is not in effect. If DST is in effect, return " -"the offset as a :class:`timedelta` object (see :meth:`utcoffset` for " -"details). Note that DST offset, if applicable, has already been added to the " -"UTC offset returned by :meth:`utcoffset`, so there's no need to consult :" -"meth:`dst` unless you're interested in obtaining DST info separately. For " -"example, :meth:`datetime.timetuple` calls its :attr:`~.datetime.tzinfo` " -"attribute's :meth:`dst` method to determine how the :attr:`~time.struct_time." -"tm_isdst` flag should be set, and :meth:`tzinfo.fromutc` calls :meth:`dst` " -"to account for DST changes when crossing time zones." -msgstr "" - -#: ../../library/datetime.rst:2169 -msgid "" -"An instance *tz* of a :class:`tzinfo` subclass that models both standard and " -"daylight times must be consistent in this sense:" -msgstr "" - -#: ../../library/datetime.rst:2172 -msgid "``tz.utcoffset(dt) - tz.dst(dt)``" -msgstr "``tz.utcoffset(dt) - tz.dst(dt)``" - -#: ../../library/datetime.rst:2174 -msgid "" -"must return the same result for every :class:`.datetime` *dt* with ``dt." -"tzinfo == tz``. For sane :class:`tzinfo` subclasses, this expression yields " -"the time zone's \"standard offset\", which should not depend on the date or " -"the time, but only on geographic location. The implementation of :meth:" -"`datetime.astimezone` relies on this, but cannot detect violations; it's the " -"programmer's responsibility to ensure it. If a :class:`tzinfo` subclass " -"cannot guarantee this, it may be able to override the default implementation " -"of :meth:`tzinfo.fromutc` to work correctly with :meth:`~.datetime." -"astimezone` regardless." -msgstr "" - -#: ../../library/datetime.rst:2183 -msgid "" -"Most implementations of :meth:`dst` will probably look like one of these " -"two::" -msgstr "" - -#: ../../library/datetime.rst:2185 -msgid "" -"def dst(self, dt):\n" -" # a fixed-offset class: doesn't account for DST\n" -" return timedelta(0)" -msgstr "" - -#: ../../library/datetime.rst:2189 -msgid "or::" -msgstr "或是： ::" - -#: ../../library/datetime.rst:2191 -msgid "" -"def dst(self, dt):\n" -" # Code to set dston and dstoff to the time zone's DST\n" -" # transition times based on the input dt.year, and expressed\n" -" # in standard local time.\n" -"\n" -" if dston <= dt.replace(tzinfo=None) < dstoff:\n" -" return timedelta(hours=1)\n" -" else:\n" -" return timedelta(0)" -msgstr "" - -#: ../../library/datetime.rst:2201 -msgid "" -"The default implementation of :meth:`dst` raises :exc:`NotImplementedError`." -msgstr "" - -#: ../../library/datetime.rst:2209 -msgid "" -"Return the time zone name corresponding to the :class:`.datetime` object " -"*dt*, as a string. Nothing about string names is defined by the :mod:`!" -"datetime` module, and there's no requirement that it mean anything in " -"particular. For example, ``\"GMT\"``, ``\"UTC\"``, ``\"-500\"``, " -"``\"-5:00\"``, ``\"EDT\"``, ``\"US/Eastern\"``, ``\"America/New York\"`` are " -"all valid replies. Return ``None`` if a string name isn't known. Note that " -"this is a method rather than a fixed string primarily because some :class:" -"`tzinfo` subclasses will wish to return different names depending on the " -"specific value of *dt* passed, especially if the :class:`tzinfo` class is " -"accounting for daylight time." -msgstr "" - -#: ../../library/datetime.rst:2219 -msgid "" -"The default implementation of :meth:`tzname` raises :exc:" -"`NotImplementedError`." -msgstr "" - -#: ../../library/datetime.rst:2222 -msgid "" -"These methods are called by a :class:`.datetime` or :class:`.time` object, " -"in response to their methods of the same names. A :class:`.datetime` object " -"passes itself as the argument, and a :class:`.time` object passes ``None`` " -"as the argument. A :class:`tzinfo` subclass's methods should therefore be " -"prepared to accept a *dt* argument of ``None``, or of class :class:`." -"datetime`." -msgstr "" - -#: ../../library/datetime.rst:2228 -msgid "" -"When ``None`` is passed, it's up to the class designer to decide the best " -"response. For example, returning ``None`` is appropriate if the class wishes " -"to say that time objects don't participate in the :class:`tzinfo` protocols. " -"It may be more useful for ``utcoffset(None)`` to return the standard UTC " -"offset, as there is no other convention for discovering the standard offset." -msgstr "" - -#: ../../library/datetime.rst:2234 -msgid "" -"When a :class:`.datetime` object is passed in response to a :class:`." -"datetime` method, ``dt.tzinfo`` is the same object as *self*. :class:" -"`tzinfo` methods can rely on this, unless user code calls :class:`tzinfo` " -"methods directly. The intent is that the :class:`tzinfo` methods interpret " -"*dt* as being in local time, and not need worry about objects in other time " -"zones." -msgstr "" - -#: ../../library/datetime.rst:2240 -msgid "" -"There is one more :class:`tzinfo` method that a subclass may wish to " -"override:" -msgstr "" - -#: ../../library/datetime.rst:2245 -msgid "" -"This is called from the default :meth:`datetime.astimezone` implementation. " -"When called from that, ``dt.tzinfo`` is *self*, and *dt*'s date and time " -"data are to be viewed as expressing a UTC time. The purpose of :meth:" -"`fromutc` is to adjust the date and time data, returning an equivalent " -"datetime in *self*'s local time." -msgstr "" - -#: ../../library/datetime.rst:2251 -msgid "" -"Most :class:`tzinfo` subclasses should be able to inherit the default :meth:" -"`fromutc` implementation without problems. It's strong enough to handle " -"fixed-offset time zones, and time zones accounting for both standard and " -"daylight time, and the latter even if the DST transition times differ in " -"different years. An example of a time zone the default :meth:`fromutc` " -"implementation may not handle correctly in all cases is one where the " -"standard offset (from UTC) depends on the specific date and time passed, " -"which can happen for political reasons. The default implementations of :meth:" -"`~.datetime.astimezone` and :meth:`fromutc` may not produce the result you " -"want if the result is one of the hours straddling the moment the standard " -"offset changes." -msgstr "" - -#: ../../library/datetime.rst:2262 -msgid "" -"Skipping code for error cases, the default :meth:`fromutc` implementation " -"acts like::" -msgstr "" - -#: ../../library/datetime.rst:2265 -msgid "" -"def fromutc(self, dt):\n" -" # raise ValueError error if dt.tzinfo is not self\n" -" dtoff = dt.utcoffset()\n" -" dtdst = dt.dst()\n" -" # raise ValueError if dtoff is None or dtdst is None\n" -" delta = dtoff - dtdst # this is self's standard offset\n" -" if delta:\n" -" dt += delta # convert to standard local time\n" -" dtdst = dt.dst()\n" -" # raise ValueError if dtdst is None\n" -" if dtdst:\n" -" return dt + dtdst\n" -" else:\n" -" return dt" -msgstr "" - -#: ../../library/datetime.rst:2280 -msgid "" -"In the following :download:`tzinfo_examples.py <../includes/tzinfo_examples." -"py>` file there are some examples of :class:`tzinfo` classes:" -msgstr "" - -#: ../../library/datetime.rst:2284 -msgid "" -"from datetime import tzinfo, timedelta, datetime\n" -"\n" -"ZERO = timedelta(0)\n" -"HOUR = timedelta(hours=1)\n" -"SECOND = timedelta(seconds=1)\n" -"\n" -"# A class capturing the platform's idea of local time.\n" -"# (May result in wrong values on historical times in\n" -"# timezones where UTC offset and/or the DST rules had\n" -"# changed in the past.)\n" -"import time as _time\n" -"\n" -"STDOFFSET = timedelta(seconds = -_time.timezone)\n" -"if _time.daylight:\n" -" DSTOFFSET = timedelta(seconds = -_time.altzone)\n" -"else:\n" -" DSTOFFSET = STDOFFSET\n" -"\n" -"DSTDIFF = DSTOFFSET - STDOFFSET\n" -"\n" -"class LocalTimezone(tzinfo):\n" -"\n" -" def fromutc(self, dt):\n" -" assert dt.tzinfo is self\n" -" stamp = (dt - datetime(1970, 1, 1, tzinfo=self)) // SECOND\n" -" args = _time.localtime(stamp)[:6]\n" -" dst_diff = DSTDIFF // SECOND\n" -" # Detect fold\n" -" fold = (args == _time.localtime(stamp - dst_diff))\n" -" return datetime(*args, microsecond=dt.microsecond,\n" -" tzinfo=self, fold=fold)\n" -"\n" -" def utcoffset(self, dt):\n" -" if self._isdst(dt):\n" -" return DSTOFFSET\n" -" else:\n" -" return STDOFFSET\n" -"\n" -" def dst(self, dt):\n" -" if self._isdst(dt):\n" -" return DSTDIFF\n" -" else:\n" -" return ZERO\n" -"\n" -" def tzname(self, dt):\n" -" return _time.tzname[self._isdst(dt)]\n" -"\n" -" def _isdst(self, dt):\n" -" tt = (dt.year, dt.month, dt.day,\n" -" dt.hour, dt.minute, dt.second,\n" -" dt.weekday(), 0, 0)\n" -" stamp = _time.mktime(tt)\n" -" tt = _time.localtime(stamp)\n" -" return tt.tm_isdst > 0\n" -"\n" -"Local = LocalTimezone()\n" -"\n" -"\n" -"# A complete implementation of current DST rules for major US time zones.\n" -"\n" -"def first_sunday_on_or_after(dt):\n" -" days_to_go = 6 - dt.weekday()\n" -" if days_to_go:\n" -" dt += timedelta(days_to_go)\n" -" return dt\n" -"\n" -"\n" -"# US DST Rules\n" -"#\n" -"# This is a simplified (i.e., wrong for a few cases) set of rules for US\n" -"# DST start and end times. For a complete and up-to-date set of DST rules\n" -"# and timezone definitions, visit the Olson Database (or try pytz):\n" -"# http://www.twinsun.com/tz/tz-link.htm\n" -"# https://sourceforge.net/projects/pytz/ (might not be up-to-date)\n" -"#\n" -"# In the US, since 2007, DST starts at 2am (standard time) on the second\n" -"# Sunday in March, which is the first Sunday on or after Mar 8.\n" -"DSTSTART_2007 = datetime(1, 3, 8, 2)\n" -"# and ends at 2am (DST time) on the first Sunday of Nov.\n" -"DSTEND_2007 = datetime(1, 11, 1, 2)\n" -"# From 1987 to 2006, DST used to start at 2am (standard time) on the first\n" -"# Sunday in April and to end at 2am (DST time) on the last\n" -"# Sunday of October, which is the first Sunday on or after Oct 25.\n" -"DSTSTART_1987_2006 = datetime(1, 4, 1, 2)\n" -"DSTEND_1987_2006 = datetime(1, 10, 25, 2)\n" -"# From 1967 to 1986, DST used to start at 2am (standard time) on the last\n" -"# Sunday in April (the one on or after April 24) and to end at 2am (DST " -"time)\n" -"# on the last Sunday of October, which is the first Sunday\n" -"# on or after Oct 25.\n" -"DSTSTART_1967_1986 = datetime(1, 4, 24, 2)\n" -"DSTEND_1967_1986 = DSTEND_1987_2006\n" -"\n" -"def us_dst_range(year):\n" -" # Find start and end times for US DST. For years before 1967, return\n" -" # start = end for no DST.\n" -" if 2006 < year:\n" -" dststart, dstend = DSTSTART_2007, DSTEND_2007\n" -" elif 1986 < year < 2007:\n" -" dststart, dstend = DSTSTART_1987_2006, DSTEND_1987_2006\n" -" elif 1966 < year < 1987:\n" -" dststart, dstend = DSTSTART_1967_1986, DSTEND_1967_1986\n" -" else:\n" -" return (datetime(year, 1, 1), ) * 2\n" -"\n" -" start = first_sunday_on_or_after(dststart.replace(year=year))\n" -" end = first_sunday_on_or_after(dstend.replace(year=year))\n" -" return start, end\n" -"\n" -"\n" -"class USTimeZone(tzinfo):\n" -"\n" -" def __init__(self, hours, reprname, stdname, dstname):\n" -" self.stdoffset = timedelta(hours=hours)\n" -" self.reprname = reprname\n" -" self.stdname = stdname\n" -" self.dstname = dstname\n" -"\n" -" def __repr__(self):\n" -" return self.reprname\n" -"\n" -" def tzname(self, dt):\n" -" if self.dst(dt):\n" -" return self.dstname\n" -" else:\n" -" return self.stdname\n" -"\n" -" def utcoffset(self, dt):\n" -" return self.stdoffset + self.dst(dt)\n" -"\n" -" def dst(self, dt):\n" -" if dt is None or dt.tzinfo is None:\n" -" # An exception may be sensible here, in one or both cases.\n" -" # It depends on how you want to treat them. The default\n" -" # fromutc() implementation (called by the default astimezone()\n" -" # implementation) passes a datetime with dt.tzinfo is self.\n" -" return ZERO\n" -" assert dt.tzinfo is self\n" -" start, end = us_dst_range(dt.year)\n" -" # Can't compare naive to aware objects, so strip the timezone from\n" -" # dt first.\n" -" dt = dt.replace(tzinfo=None)\n" -" if start + HOUR <= dt < end - HOUR:\n" -" # DST is in effect.\n" -" return HOUR\n" -" if end - HOUR <= dt < end:\n" -" # Fold (an ambiguous hour): use dt.fold to disambiguate.\n" -" return ZERO if dt.fold else HOUR\n" -" if start <= dt < start + HOUR:\n" -" # Gap (a non-existent hour): reverse the fold rule.\n" -" return HOUR if dt.fold else ZERO\n" -" # DST is off.\n" -" return ZERO\n" -"\n" -" def fromutc(self, dt):\n" -" assert dt.tzinfo is self\n" -" start, end = us_dst_range(dt.year)\n" -" start = start.replace(tzinfo=self)\n" -" end = end.replace(tzinfo=self)\n" -" std_time = dt + self.stdoffset\n" -" dst_time = std_time + HOUR\n" -" if end <= dst_time < end + HOUR:\n" -" # Repeated hour\n" -" return std_time.replace(fold=1)\n" -" if std_time < start or dst_time >= end:\n" -" # Standard time\n" -" return std_time\n" -" if start <= std_time < end - HOUR:\n" -" # Daylight saving time\n" -" return dst_time\n" -"\n" -"\n" -"Eastern = USTimeZone(-5, \"Eastern\", \"EST\", \"EDT\")\n" -"Central = USTimeZone(-6, \"Central\", \"CST\", \"CDT\")\n" -"Mountain = USTimeZone(-7, \"Mountain\", \"MST\", \"MDT\")\n" -"Pacific = USTimeZone(-8, \"Pacific\", \"PST\", \"PDT\")\n" -msgstr "" - -#: ../../library/datetime.rst:2286 -msgid "" -"Note that there are unavoidable subtleties twice per year in a :class:" -"`tzinfo` subclass accounting for both standard and daylight time, at the DST " -"transition points. For concreteness, consider US Eastern (UTC -0500), where " -"EDT begins the minute after 1:59 (EST) on the second Sunday in March, and " -"ends the minute after 1:59 (EDT) on the first Sunday in November::" -msgstr "" - -#: ../../library/datetime.rst:2292 -msgid "" -" UTC 3:MM 4:MM 5:MM 6:MM 7:MM 8:MM\n" -" EST 22:MM 23:MM 0:MM 1:MM 2:MM 3:MM\n" -" EDT 23:MM 0:MM 1:MM 2:MM 3:MM 4:MM\n" -"\n" -"start 22:MM 23:MM 0:MM 1:MM 3:MM 4:MM\n" -"\n" -" end 23:MM 0:MM 1:MM 1:MM 2:MM 3:MM" -msgstr "" -" UTC 3:MM 4:MM 5:MM 6:MM 7:MM 8:MM\n" -" EST 22:MM 23:MM 0:MM 1:MM 2:MM 3:MM\n" -" EDT 23:MM 0:MM 1:MM 2:MM 3:MM 4:MM\n" -"\n" -"start 22:MM 23:MM 0:MM 1:MM 3:MM 4:MM\n" -"\n" -" end 23:MM 0:MM 1:MM 1:MM 2:MM 3:MM" - -#: ../../library/datetime.rst:2300 -msgid "" -"When DST starts (the \"start\" line), the local wall clock leaps from 1:59 " -"to 3:00. A wall time of the form 2:MM doesn't really make sense on that day, " -"so ``astimezone(Eastern)`` won't deliver a result with ``hour == 2`` on the " -"day DST begins. For example, at the Spring forward transition of 2016, we " -"get::" -msgstr "" - -#: ../../library/datetime.rst:2305 -msgid "" -">>> from datetime import datetime, timezone\n" -">>> from tzinfo_examples import HOUR, Eastern\n" -">>> u0 = datetime(2016, 3, 13, 5, tzinfo=timezone.utc)\n" -">>> for i in range(4):\n" -"... u = u0 + i*HOUR\n" -"... t = u.astimezone(Eastern)\n" -"... print(u.time(), 'UTC =', t.time(), t.tzname())\n" -"...\n" -"05:00:00 UTC = 00:00:00 EST\n" -"06:00:00 UTC = 01:00:00 EST\n" -"07:00:00 UTC = 03:00:00 EDT\n" -"08:00:00 UTC = 04:00:00 EDT" -msgstr "" -">>> from datetime import datetime, timezone\n" -">>> from tzinfo_examples import HOUR, Eastern\n" -">>> u0 = datetime(2016, 3, 13, 5, tzinfo=timezone.utc)\n" -">>> for i in range(4):\n" -"... u = u0 + i*HOUR\n" -"... t = u.astimezone(Eastern)\n" -"... print(u.time(), 'UTC =', t.time(), t.tzname())\n" -"...\n" -"05:00:00 UTC = 00:00:00 EST\n" -"06:00:00 UTC = 01:00:00 EST\n" -"07:00:00 UTC = 03:00:00 EDT\n" -"08:00:00 UTC = 04:00:00 EDT" - -#: ../../library/datetime.rst:2319 -msgid "" -"When DST ends (the \"end\" line), there's a potentially worse problem: " -"there's an hour that can't be spelled unambiguously in local wall time: the " -"last hour of daylight time. In Eastern, that's times of the form 5:MM UTC on " -"the day daylight time ends. The local wall clock leaps from 1:59 (daylight " -"time) back to 1:00 (standard time) again. Local times of the form 1:MM are " -"ambiguous. :meth:`~.datetime.astimezone` mimics the local clock's behavior " -"by mapping two adjacent UTC hours into the same local hour then. In the " -"Eastern example, UTC times of the form 5:MM and 6:MM both map to 1:MM when " -"converted to Eastern, but earlier times have the :attr:`~.datetime.fold` " -"attribute set to 0 and the later times have it set to 1. For example, at the " -"Fall back transition of 2016, we get::" -msgstr "" - -#: ../../library/datetime.rst:2330 -msgid "" -">>> u0 = datetime(2016, 11, 6, 4, tzinfo=timezone.utc)\n" -">>> for i in range(4):\n" -"... u = u0 + i*HOUR\n" -"... t = u.astimezone(Eastern)\n" -"... print(u.time(), 'UTC =', t.time(), t.tzname(), t.fold)\n" -"...\n" -"04:00:00 UTC = 00:00:00 EDT 0\n" -"05:00:00 UTC = 01:00:00 EDT 0\n" -"06:00:00 UTC = 01:00:00 EST 1\n" -"07:00:00 UTC = 02:00:00 EST 0" -msgstr "" -">>> u0 = datetime(2016, 11, 6, 4, tzinfo=timezone.utc)\n" -">>> for i in range(4):\n" -"... u = u0 + i*HOUR\n" -"... t = u.astimezone(Eastern)\n" -"... print(u.time(), 'UTC =', t.time(), t.tzname(), t.fold)\n" -"...\n" -"04:00:00 UTC = 00:00:00 EDT 0\n" -"05:00:00 UTC = 01:00:00 EDT 0\n" -"06:00:00 UTC = 01:00:00 EST 1\n" -"07:00:00 UTC = 02:00:00 EST 0" - -#: ../../library/datetime.rst:2341 -msgid "" -"Note that the :class:`.datetime` instances that differ only by the value of " -"the :attr:`~.datetime.fold` attribute are considered equal in comparisons." -msgstr "" - -#: ../../library/datetime.rst:2344 -msgid "" -"Applications that can't bear wall-time ambiguities should explicitly check " -"the value of the :attr:`~.datetime.fold` attribute or avoid using hybrid :" -"class:`tzinfo` subclasses; there are no ambiguities when using :class:" -"`timezone`, or any other fixed-offset :class:`tzinfo` subclass (such as a " -"class representing only EST (fixed offset -5 hours), or only EDT (fixed " -"offset -4 hours))." -msgstr "" - -#: ../../library/datetime.rst:2352 -msgid ":mod:`zoneinfo`" -msgstr ":mod:`zoneinfo`" - -#: ../../library/datetime.rst:2353 -msgid "" -"The :mod:`!datetime` module has a basic :class:`timezone` class (for " -"handling arbitrary fixed offsets from UTC) and its :attr:`timezone.utc` " -"attribute (a UTC :class:`!timezone` instance)." -msgstr "" - -#: ../../library/datetime.rst:2357 -msgid "" -"``zoneinfo`` brings the *IANA time zone database* (also known as the Olson " -"database) to Python, and its usage is recommended." -msgstr "" - -#: ../../library/datetime.rst:2360 -msgid "`IANA time zone database `_" -msgstr "`IANA 時區資料庫 `_" - -#: ../../library/datetime.rst:2361 -msgid "" -"The Time Zone Database (often called tz, tzdata or zoneinfo) contains code " -"and data that represent the history of local time for many representative " -"locations around the globe. It is updated periodically to reflect changes " -"made by political bodies to time zone boundaries, UTC offsets, and daylight-" -"saving rules." -msgstr "" - -#: ../../library/datetime.rst:2371 -msgid ":class:`timezone` Objects" -msgstr ":class:`timezone` 物件" - -#: ../../library/datetime.rst:2373 -msgid "" -"The :class:`timezone` class is a subclass of :class:`tzinfo`, each instance " -"of which represents a time zone defined by a fixed offset from UTC." -msgstr "" - -#: ../../library/datetime.rst:2377 -msgid "" -"Objects of this class cannot be used to represent time zone information in " -"the locations where different offsets are used in different days of the year " -"or where historical changes have been made to civil time." -msgstr "" - -#: ../../library/datetime.rst:2384 -msgid "" -"The *offset* argument must be specified as a :class:`timedelta` object " -"representing the difference between the local time and UTC. It must be " -"strictly between ``-timedelta(hours=24)`` and ``timedelta(hours=24)``, " -"otherwise :exc:`ValueError` is raised." -msgstr "" - -#: ../../library/datetime.rst:2389 -msgid "" -"The *name* argument is optional. If specified it must be a string that will " -"be used as the value returned by the :meth:`datetime.tzname` method." -msgstr "" - -#: ../../library/datetime.rst:2400 ../../library/datetime.rst:2411 -msgid "" -"Return the fixed value specified when the :class:`timezone` instance is " -"constructed." -msgstr "" - -#: ../../library/datetime.rst:2403 -msgid "" -"The *dt* argument is ignored. The return value is a :class:`timedelta` " -"instance equal to the difference between the local time and UTC." -msgstr "" - -#: ../../library/datetime.rst:2414 -msgid "" -"If *name* is not provided in the constructor, the name returned by " -"``tzname(dt)`` is generated from the value of the ``offset`` as follows. If " -"*offset* is ``timedelta(0)``, the name is \"UTC\", otherwise it is a string " -"in the format ``UTC±HH:MM``, where ± is the sign of ``offset``, HH and MM " -"are two digits of ``offset.hours`` and ``offset.minutes`` respectively." -msgstr "" - -#: ../../library/datetime.rst:2420 -msgid "" -"Name generated from ``offset=timedelta(0)`` is now plain ``'UTC'``, not " -"``'UTC+00:00'``." -msgstr "" - -#: ../../library/datetime.rst:2427 -msgid "Always returns ``None``." -msgstr "總是回傳 ``None``。" - -#: ../../library/datetime.rst:2431 -msgid "" -"Return ``dt + offset``. The *dt* argument must be an aware :class:`." -"datetime` instance, with ``tzinfo`` set to ``self``." -msgstr "" - -#: ../../library/datetime.rst:2438 -msgid "The UTC time zone, ``timezone(timedelta(0))``." -msgstr "UTC 時區，``timezone(timedelta(0))``。" - -#: ../../library/datetime.rst:2447 -msgid ":meth:`~.datetime.strftime` and :meth:`~.datetime.strptime` Behavior" -msgstr ":meth:`~.datetime.strftime` 與 :meth:`~.datetime.strptime` 的行為" - -#: ../../library/datetime.rst:2449 -msgid "" -":class:`date`, :class:`.datetime`, and :class:`.time` objects all support a " -"``strftime(format)`` method, to create a string representing the time under " -"the control of an explicit format string." -msgstr "" - -#: ../../library/datetime.rst:2453 -msgid "" -"Conversely, the :meth:`date.strptime`, :meth:`datetime.strptime` and :meth:" -"`time.strptime` class methods create an object from a string representing " -"the time and a corresponding format string." -msgstr "" - -#: ../../library/datetime.rst:2457 -msgid "" -"The table below provides a high-level comparison of :meth:`~.datetime." -"strftime` versus :meth:`~.datetime.strptime`:" -msgstr "" - -#: ../../library/datetime.rst:2461 -msgid "``strftime``" -msgstr "``strftime``" - -#: ../../library/datetime.rst:2461 -msgid "``strptime``" -msgstr "``strptime``" - -#: ../../library/datetime.rst:2463 -msgid "Usage" -msgstr "用法" - -#: ../../library/datetime.rst:2463 -msgid "Convert object to a string according to a given format" -msgstr "" - -#: ../../library/datetime.rst:2463 -msgid "Parse a string into an object given a corresponding format" -msgstr "" - -#: ../../library/datetime.rst:2465 -msgid "Type of method" -msgstr "" - -#: ../../library/datetime.rst:2465 -msgid "Instance method" -msgstr "實例方法" - -#: ../../library/datetime.rst:2465 -msgid "Class method" -msgstr "類別方法" - -#: ../../library/datetime.rst:2467 -msgid "Signature" -msgstr "" - -#: ../../library/datetime.rst:2467 -msgid "``strftime(format)``" -msgstr "``strftime(format)``" - -#: ../../library/datetime.rst:2467 -msgid "``strptime(date_string, format)``" -msgstr "``strptime(date_string, format)``" - -#: ../../library/datetime.rst:2474 -msgid "" -":meth:`~.datetime.strftime` and :meth:`~.datetime.strptime` Format Codes" -msgstr ":meth:`~.datetime.strftime` 與 :meth:`~.datetime.strptime` 格式碼" - -#: ../../library/datetime.rst:2476 -msgid "" -"These methods accept format codes that can be used to parse and format " -"dates::" -msgstr "" - -#: ../../library/datetime.rst:2478 -msgid "" -">>> datetime.strptime('31/01/22 23:59:59.999999',\n" -"... '%d/%m/%y %H:%M:%S.%f')\n" -"datetime.datetime(2022, 1, 31, 23, 59, 59, 999999)\n" -">>> _.strftime('%a %d %b %Y, %I:%M%p')\n" -"'Mon 31 Jan 2022, 11:59PM'" -msgstr "" -">>> datetime.strptime('31/01/22 23:59:59.999999',\n" -"... '%d/%m/%y %H:%M:%S.%f')\n" -"datetime.datetime(2022, 1, 31, 23, 59, 59, 999999)\n" -">>> _.strftime('%a %d %b %Y, %I:%M%p')\n" -"'Mon 31 Jan 2022, 11:59PM'" - -#: ../../library/datetime.rst:2484 -msgid "" -"The following is a list of all the format codes that the 1989 C standard " -"requires, and these work on all platforms with a standard C implementation." -msgstr "" - -#: ../../library/datetime.rst:2488 ../../library/datetime.rst:2591 -msgid "Directive" -msgstr "" - -#: ../../library/datetime.rst:2488 ../../library/datetime.rst:2591 -msgid "Meaning" -msgstr "含義" - -#: ../../library/datetime.rst:2488 ../../library/datetime.rst:2591 -msgid "Example" -msgstr "範例" - -#: ../../library/datetime.rst:2488 ../../library/datetime.rst:2591 -msgid "Notes" -msgstr "註解" - -#: ../../library/datetime.rst:2490 -msgid "``%a``" -msgstr "``%a``" - -#: ../../library/datetime.rst:2490 -msgid "Weekday as locale's abbreviated name." -msgstr "" - -#: ../../library/datetime.rst:2490 -msgid "Sun, Mon, ..., Sat (en_US);" -msgstr "" - -#: ../../library/datetime.rst:2492 -msgid "So, Mo, ..., Sa (de_DE)" -msgstr "" - -#: ../../library/datetime.rst:2495 -msgid "``%A``" -msgstr "``%A``" - -#: ../../library/datetime.rst:2495 -msgid "Weekday as locale's full name." -msgstr "" - -#: ../../library/datetime.rst:2495 -msgid "Sunday, Monday, ..., Saturday (en_US);" -msgstr "" - -#: ../../library/datetime.rst:2497 -msgid "Sonntag, Montag, ..., Samstag (de_DE)" -msgstr "" - -#: ../../library/datetime.rst:2500 -msgid "``%w``" -msgstr "``%w``" - -#: ../../library/datetime.rst:2500 -msgid "Weekday as a decimal number, where 0 is Sunday and 6 is Saturday." -msgstr "" - -#: ../../library/datetime.rst:2500 -msgid "0, 1, ..., 6" -msgstr "0, 1, ..., 6" - -#: ../../library/datetime.rst:2504 -msgid "``%d``" -msgstr "``%d``" - -#: ../../library/datetime.rst:2504 -msgid "Day of the month as a zero-padded decimal number." -msgstr "" - -#: ../../library/datetime.rst:2504 -msgid "01, 02, ..., 31" -msgstr "01, 02, ..., 31" - -#: ../../library/datetime.rst:2504 ../../library/datetime.rst:2517 -#: ../../library/datetime.rst:2520 ../../library/datetime.rst:2526 -#: ../../library/datetime.rst:2529 ../../library/datetime.rst:2535 -#: ../../library/datetime.rst:2553 -msgid "\\(9)" -msgstr "\\(9)" - -#: ../../library/datetime.rst:2507 -msgid "``%b``" -msgstr "``%b``" - -#: ../../library/datetime.rst:2507 -msgid "Month as locale's abbreviated name." -msgstr "" - -#: ../../library/datetime.rst:2507 -msgid "Jan, Feb, ..., Dec (en_US);" -msgstr "" - -#: ../../library/datetime.rst:2509 -msgid "Jan, Feb, ..., Dez (de_DE)" -msgstr "" - -#: ../../library/datetime.rst:2512 -msgid "``%B``" -msgstr "``%B``" - -#: ../../library/datetime.rst:2512 -msgid "Month as locale's full name." -msgstr "" - -#: ../../library/datetime.rst:2512 -msgid "January, February, ..., December (en_US);" -msgstr "" - -#: ../../library/datetime.rst:2514 -msgid "Januar, Februar, ..., Dezember (de_DE)" -msgstr "" - -#: ../../library/datetime.rst:2517 -msgid "``%m``" -msgstr "``%m``" - -#: ../../library/datetime.rst:2517 -msgid "Month as a zero-padded decimal number." -msgstr "以零填充的並以十進位數字表示的月份。" - -#: ../../library/datetime.rst:2517 ../../library/datetime.rst:2529 -msgid "01, 02, ..., 12" -msgstr "01, 02, ..., 12" - -#: ../../library/datetime.rst:2520 -msgid "``%y``" -msgstr "``%y``" - -#: ../../library/datetime.rst:2520 -msgid "Year without century as a zero-padded decimal number." -msgstr "" - -#: ../../library/datetime.rst:2520 -msgid "00, 01, ..., 99" -msgstr "00, 01, ..., 99" - -#: ../../library/datetime.rst:2523 -msgid "``%Y``" -msgstr "``%Y``" - -#: ../../library/datetime.rst:2523 -msgid "Year with century as a decimal number." -msgstr "" - -#: ../../library/datetime.rst:2523 ../../library/datetime.rst:2593 -msgid "0001, 0002, ..., 2013, 2014, ..., 9998, 9999" -msgstr "0001, 0002, ..., 2013, 2014, ..., 9998, 9999" - -#: ../../library/datetime.rst:2526 -msgid "``%H``" -msgstr "``%H``" - -#: ../../library/datetime.rst:2526 -msgid "Hour (24-hour clock) as a zero-padded decimal number." -msgstr "" - -#: ../../library/datetime.rst:2526 -msgid "00, 01, ..., 23" -msgstr "00, 01, ..., 23" - -#: ../../library/datetime.rst:2529 -msgid "``%I``" -msgstr "``%I``" - -#: ../../library/datetime.rst:2529 -msgid "Hour (12-hour clock) as a zero-padded decimal number." -msgstr "" - -#: ../../library/datetime.rst:2532 -msgid "``%p``" -msgstr "``%p``" - -#: ../../library/datetime.rst:2532 -msgid "Locale's equivalent of either AM or PM." -msgstr "" - -#: ../../library/datetime.rst:2532 -msgid "AM, PM (en_US);" -msgstr "AM, PM (en_US);" - -#: ../../library/datetime.rst:2533 -msgid "am, pm (de_DE)" -msgstr "am, pm (de_DE)" - -#: ../../library/datetime.rst:2532 -msgid "\\(1), \\(3)" -msgstr "\\(1), \\(3)" - -#: ../../library/datetime.rst:2535 -msgid "``%M``" -msgstr "``%M``" - -#: ../../library/datetime.rst:2535 -msgid "Minute as a zero-padded decimal number." -msgstr "" - -#: ../../library/datetime.rst:2535 ../../library/datetime.rst:2538 -msgid "00, 01, ..., 59" -msgstr "00, 01, ..., 59" - -#: ../../library/datetime.rst:2538 -msgid "``%S``" -msgstr "``%S``" - -#: ../../library/datetime.rst:2538 -msgid "Second as a zero-padded decimal number." -msgstr "" - -#: ../../library/datetime.rst:2538 -msgid "\\(4), \\(9)" -msgstr "\\(4), \\(9)" - -#: ../../library/datetime.rst:2541 -msgid "``%f``" -msgstr "``%f``" - -#: ../../library/datetime.rst:2541 -msgid "Microsecond as a decimal number, zero-padded to 6 digits." -msgstr "" - -#: ../../library/datetime.rst:2541 -msgid "000000, 000001, ..., 999999" -msgstr "000000, 000001, ..., 999999" - -#: ../../library/datetime.rst:2541 -msgid "\\(5)" -msgstr "\\(5)" - -#: ../../library/datetime.rst:2545 ../../library/datetime.rst:2737 -msgid "``%z``" -msgstr "``%z``" - -#: ../../library/datetime.rst:2545 -msgid "" -"UTC offset in the form ``±HHMM[SS[.ffffff]]`` (empty string if the object is " -"naive)." -msgstr "" - -#: ../../library/datetime.rst:2545 -msgid "(empty), +0000, -0400, +1030, +063415, -030712.345216" -msgstr "" - -#: ../../library/datetime.rst:2545 ../../library/datetime.rst:2550 -#: ../../library/datetime.rst:2607 -msgid "\\(6)" -msgstr "\\(6)" - -#: ../../library/datetime.rst:2550 ../../library/datetime.rst:2763 -msgid "``%Z``" -msgstr "``%Z``" - -#: ../../library/datetime.rst:2550 -msgid "Time zone name (empty string if the object is naive)." -msgstr "" - -#: ../../library/datetime.rst:2550 -msgid "(empty), UTC, GMT" -msgstr "" - -#: ../../library/datetime.rst:2553 -msgid "``%j``" -msgstr "``%j``" - -#: ../../library/datetime.rst:2553 -msgid "Day of the year as a zero-padded decimal number." -msgstr "" - -#: ../../library/datetime.rst:2553 -msgid "001, 002, ..., 366" -msgstr "001, 002, ..., 366" - -#: ../../library/datetime.rst:2556 -msgid "``%U``" -msgstr "``%U``" - -#: ../../library/datetime.rst:2556 -msgid "" -"Week number of the year (Sunday as the first day of the week) as a zero-" -"padded decimal number. All days in a new year preceding the first Sunday are " -"considered to be in week 0." -msgstr "" - -#: ../../library/datetime.rst:2556 ../../library/datetime.rst:2564 -msgid "00, 01, ..., 53" -msgstr "00, 01, ..., 53" - -#: ../../library/datetime.rst:2556 ../../library/datetime.rst:2564 -msgid "\\(7), \\(9)" -msgstr "\\(7), \\(9)" - -#: ../../library/datetime.rst:2564 -msgid "``%W``" -msgstr "``%W``" - -#: ../../library/datetime.rst:2564 -msgid "" -"Week number of the year (Monday as the first day of the week) as a zero-" -"padded decimal number. All days in a new year preceding the first Monday are " -"considered to be in week 0." -msgstr "" - -#: ../../library/datetime.rst:2572 -msgid "``%c``" -msgstr "``%c``" - -#: ../../library/datetime.rst:2572 -msgid "Locale's appropriate date and time representation." -msgstr "" - -#: ../../library/datetime.rst:2572 -msgid "Tue Aug 16 21:30:00 1988 (en_US);" -msgstr "" - -#: ../../library/datetime.rst:2574 -msgid "Di 16 Aug 21:30:00 1988 (de_DE)" -msgstr "" - -#: ../../library/datetime.rst:2577 -msgid "``%x``" -msgstr "``%x``" - -#: ../../library/datetime.rst:2577 -msgid "Locale's appropriate date representation." -msgstr "" - -#: ../../library/datetime.rst:2577 -msgid "08/16/88 (None);" -msgstr "" - -#: ../../library/datetime.rst:2578 -msgid "08/16/1988 (en_US);" -msgstr "" - -#: ../../library/datetime.rst:2579 -msgid "16.08.1988 (de_DE)" -msgstr "" - -#: ../../library/datetime.rst:2581 -msgid "``%X``" -msgstr "``%X``" - -#: ../../library/datetime.rst:2581 -msgid "Locale's appropriate time representation." -msgstr "" - -#: ../../library/datetime.rst:2581 -msgid "21:30:00 (en_US);" -msgstr "" - -#: ../../library/datetime.rst:2582 -msgid "21:30:00 (de_DE)" -msgstr "" - -#: ../../library/datetime.rst:2584 -msgid "``%%``" -msgstr "``%%``" - -#: ../../library/datetime.rst:2584 -msgid "A literal ``'%'`` character." -msgstr "" - -#: ../../library/datetime.rst:2584 -msgid "%" -msgstr "%" - -#: ../../library/datetime.rst:2587 -msgid "" -"Several additional directives not required by the C89 standard are included " -"for convenience. These parameters all correspond to ISO 8601 date values." -msgstr "" - -#: ../../library/datetime.rst:2593 -msgid "``%G``" -msgstr "``%G``" - -#: ../../library/datetime.rst:2593 -msgid "" -"ISO 8601 year with century representing the year that contains the greater " -"part of the ISO week (``%V``)." -msgstr "" - -#: ../../library/datetime.rst:2593 -msgid "\\(8)" -msgstr "\\(8)" - -#: ../../library/datetime.rst:2598 -msgid "``%u``" -msgstr "``%u``" - -#: ../../library/datetime.rst:2598 -msgid "ISO 8601 weekday as a decimal number where 1 is Monday." -msgstr "" - -#: ../../library/datetime.rst:2598 -msgid "1, 2, ..., 7" -msgstr "1, 2, ..., 7" - -#: ../../library/datetime.rst:2601 -msgid "``%V``" -msgstr "``%V``" - -#: ../../library/datetime.rst:2601 -msgid "" -"ISO 8601 week as a decimal number with Monday as the first day of the week. " -"Week 01 is the week containing Jan 4." -msgstr "" - -#: ../../library/datetime.rst:2601 -msgid "01, 02, ..., 53" -msgstr "01, 02, ..., 53" - -#: ../../library/datetime.rst:2601 -msgid "\\(8), \\(9)" -msgstr "\\(8), \\(9)" - -#: ../../library/datetime.rst:2607 ../../library/datetime.rst:2759 -msgid "``%:z``" -msgstr "``%:z``" - -#: ../../library/datetime.rst:2607 -msgid "" -"UTC offset in the form ``±HH:MM[:SS[.ffffff]]`` (empty string if the object " -"is naive)." -msgstr "" - -#: ../../library/datetime.rst:2607 -msgid "(empty), +00:00, -04:00, +10:30, +06:34:15, -03:07:12.345216" -msgstr "" - -#: ../../library/datetime.rst:2613 -msgid "" -"These may not be available on all platforms when used with the :meth:`~." -"datetime.strftime` method. The ISO 8601 year and ISO 8601 week directives " -"are not interchangeable with the year and week number directives above. " -"Calling :meth:`~.datetime.strptime` with incomplete or ambiguous ISO 8601 " -"directives will raise a :exc:`ValueError`." -msgstr "" - -#: ../../library/datetime.rst:2618 -msgid "" -"The full set of format codes supported varies across platforms, because " -"Python calls the platform C library's :c:func:`strftime` function, and " -"platform variations are common. To see the full set of format codes " -"supported on your platform, consult the :manpage:`strftime(3)` " -"documentation. There are also differences between platforms in handling of " -"unsupported format specifiers." -msgstr "" - -#: ../../library/datetime.rst:2624 -msgid "``%G``, ``%u`` and ``%V`` were added." -msgstr "新增 ``%G``、``%u`` 與 ``%V``。" - -#: ../../library/datetime.rst:2627 -msgid "``%:z`` was added." -msgstr "新增 ``%:z``。" - -#: ../../library/datetime.rst:2631 -msgid "Technical Detail" -msgstr "技術細節" - -#: ../../library/datetime.rst:2633 -msgid "" -"Broadly speaking, ``d.strftime(fmt)`` acts like the :mod:`time` module's " -"``time.strftime(fmt, d.timetuple())`` although not all objects support a :" -"meth:`~date.timetuple` method." -msgstr "" - -#: ../../library/datetime.rst:2637 -msgid "" -"For the :meth:`.datetime.strptime` and :meth:`.date.strptime` class methods, " -"the default value is ``1900-01-01T00:00:00.000``: any components not " -"specified in the format string will be pulled from the default value." -msgstr "" - -#: ../../library/datetime.rst:2642 -msgid "" -"When used to parse partial dates lacking a year, :meth:`.datetime.strptime` " -"and :meth:`.date.strptime` will raise when encountering February 29 because " -"the default year of 1900 is *not* a leap year. Always add a default leap " -"year to partial date strings before parsing." -msgstr "" - -#: ../../library/datetime.rst:2663 -msgid "" -">>> from datetime import datetime\n" -">>> value = \"2/29\"\n" -">>> datetime.strptime(value, \"%m/%d\")\n" -"Traceback (most recent call last):\n" -"...\n" -"ValueError: day 29 must be in range 1..28 for month 2 in year 1900\n" -">>> datetime.strptime(f\"1904 {value}\", \"%Y %m/%d\")\n" -"datetime.datetime(1904, 2, 29, 0, 0)" -msgstr "" - -#: ../../library/datetime.rst:2674 -msgid "Using ``datetime.strptime(date_string, format)`` is equivalent to::" -msgstr "" - -#: ../../library/datetime.rst:2678 -msgid "" -"except when the format includes sub-second components or time zone offset " -"information, which are supported in ``datetime.strptime`` but are discarded " -"by ``time.strptime``." -msgstr "" - -#: ../../library/datetime.rst:2682 -msgid "" -"For :class:`.time` objects, the format codes for year, month, and day should " -"not be used, as :class:`!time` objects have no such values. If they're used " -"anyway, 1900 is substituted for the year, and 1 for the month and day." -msgstr "" -"對 :class:`.time` 物件來說，不應該使用年、月、日的格式碼，因為 :class:`!" -"time` 物件並沒有這些值。如果使用這些格式碼，年份會以 1900 代替、月及日會以 1 " -"代替。" - -#: ../../library/datetime.rst:2686 -msgid "" -"For :class:`date` objects, the format codes for hours, minutes, seconds, and " -"microseconds should not be used, as :class:`date` objects have no such " -"values. If they're used anyway, 0 is substituted for them." -msgstr "" -"對 :class:`.date` 物件來說，不應該使用時、分、秒、微秒的格式碼，因為 :class:" -"`date` 物件並沒有這些值。如果使用這些格式碼，這些值都會以 0 代替。" - -#: ../../library/datetime.rst:2690 -msgid "" -"For the same reason, handling of format strings containing Unicode code " -"points that can't be represented in the charset of the current locale is " -"also platform-dependent. On some platforms such code points are preserved " -"intact in the output, while on others ``strftime`` may raise :exc:" -"`UnicodeError` or return an empty string instead." -msgstr "" - -#: ../../library/datetime.rst:2699 -msgid "" -"Because the format depends on the current locale, care should be taken when " -"making assumptions about the output value. Field orderings will vary (for " -"example, \"month/day/year\" versus \"day/month/year\"), and the output may " -"contain non-ASCII characters." -msgstr "" - -#: ../../library/datetime.rst:2705 -msgid "" -"The :meth:`~.datetime.strptime` method can parse years in the full [1, 9999] " -"range, but years < 1000 must be zero-filled to 4-digit width." -msgstr "" - -#: ../../library/datetime.rst:2708 -msgid "" -"In previous versions, :meth:`~.datetime.strftime` method was restricted to " -"years >= 1900." -msgstr "" - -#: ../../library/datetime.rst:2712 -msgid "" -"In version 3.2, :meth:`~.datetime.strftime` method was restricted to years " -">= 1000." -msgstr "" - -#: ../../library/datetime.rst:2717 -msgid "" -"When used with the :meth:`~.datetime.strptime` method, the ``%p`` directive " -"only affects the output hour field if the ``%I`` directive is used to parse " -"the hour." -msgstr "" - -#: ../../library/datetime.rst:2721 -msgid "" -"Unlike the :mod:`time` module, the :mod:`!datetime` module does not support " -"leap seconds." -msgstr "" - -#: ../../library/datetime.rst:2725 -msgid "" -"When used with the :meth:`~.datetime.strptime` method, the ``%f`` directive " -"accepts from one to six digits and zero pads on the right. ``%f`` is an " -"extension to the set of format characters in the C standard (but implemented " -"separately in datetime objects, and therefore always available)." -msgstr "" - -#: ../../library/datetime.rst:2732 -msgid "" -"For a naive object, the ``%z``, ``%:z`` and ``%Z`` format codes are replaced " -"by empty strings." -msgstr "" - -#: ../../library/datetime.rst:2735 -msgid "For an aware object:" -msgstr "" - -#: ../../library/datetime.rst:2738 -msgid "" -":meth:`~.datetime.utcoffset` is transformed into a string of the form " -"``±HHMM[SS[.ffffff]]``, where ``HH`` is a 2-digit string giving the number " -"of UTC offset hours, ``MM`` is a 2-digit string giving the number of UTC " -"offset minutes, ``SS`` is a 2-digit string giving the number of UTC offset " -"seconds and ``ffffff`` is a 6-digit string giving the number of UTC offset " -"microseconds. The ``ffffff`` part is omitted when the offset is a whole " -"number of seconds and both the ``ffffff`` and the ``SS`` part is omitted " -"when the offset is a whole number of minutes. For example, if :meth:`~." -"datetime.utcoffset` returns ``timedelta(hours=-3, minutes=-30)``, ``%z`` is " -"replaced with the string ``'-0330'``." -msgstr "" - -#: ../../library/datetime.rst:2752 -msgid "" -"When the ``%z`` directive is provided to the :meth:`~.datetime.strptime` " -"method, the UTC offsets can have a colon as a separator between hours, " -"minutes and seconds. For example, ``'+01:00:00'`` will be parsed as an " -"offset of one hour. In addition, providing ``'Z'`` is identical to " -"``'+00:00'``." -msgstr "" - -#: ../../library/datetime.rst:2760 -msgid "" -"Behaves exactly as ``%z``, but has a colon separator added between hours, " -"minutes and seconds." -msgstr "" - -#: ../../library/datetime.rst:2764 -msgid "" -"In :meth:`~.datetime.strftime`, ``%Z`` is replaced by an empty string if :" -"meth:`~.datetime.tzname` returns ``None``; otherwise ``%Z`` is replaced by " -"the returned value, which must be a string." -msgstr "" - -#: ../../library/datetime.rst:2768 -msgid ":meth:`~.datetime.strptime` only accepts certain values for ``%Z``:" -msgstr "" - -#: ../../library/datetime.rst:2770 -msgid "any value in ``time.tzname`` for your machine's locale" -msgstr "" - -#: ../../library/datetime.rst:2771 -msgid "the hard-coded values ``UTC`` and ``GMT``" -msgstr "" - -#: ../../library/datetime.rst:2773 -msgid "" -"So someone living in Japan may have ``JST``, ``UTC``, and ``GMT`` as valid " -"values, but probably not ``EST``. It will raise ``ValueError`` for invalid " -"values." -msgstr "" - -#: ../../library/datetime.rst:2777 -msgid "" -"When the ``%z`` directive is provided to the :meth:`~.datetime.strptime` " -"method, an aware :class:`.datetime` object will be produced. The ``tzinfo`` " -"of the result will be set to a :class:`timezone` instance." -msgstr "" - -#: ../../library/datetime.rst:2783 -msgid "" -"When used with the :meth:`~.datetime.strptime` method, ``%U`` and ``%W`` are " -"only used in calculations when the day of the week and the calendar year " -"(``%Y``) are specified." -msgstr "" - -#: ../../library/datetime.rst:2788 -msgid "" -"Similar to ``%U`` and ``%W``, ``%V`` is only used in calculations when the " -"day of the week and the ISO year (``%G``) are specified in a :meth:`~." -"datetime.strptime` format string. Also note that ``%G`` and ``%Y`` are not " -"interchangeable." -msgstr "" - -#: ../../library/datetime.rst:2794 -msgid "" -"When used with the :meth:`~.datetime.strptime` method, the leading zero is " -"optional for formats ``%d``, ``%m``, ``%H``, ``%I``, ``%M``, ``%S``, " -"``%j``, ``%U``, ``%W``, and ``%V``. Format ``%y`` does require a leading " -"zero." -msgstr "" - -#: ../../library/datetime.rst:2799 -msgid "" -"When parsing a month and day using :meth:`~.datetime.strptime`, always " -"include a year in the format. If the value you need to parse lacks a year, " -"append an explicit dummy leap year. Otherwise your code will raise an " -"exception when it encounters leap day because the default year used by the " -"parser (1900) is not a leap year. Users run into that bug every leap year." -msgstr "" - -#: ../../library/datetime.rst:2805 -msgid "" -">>> month_day = \"02/29\"\n" -">>> datetime.strptime(f\"{month_day};1984\", \"%m/%d;%Y\") # No leap year " -"bug.\n" -"datetime.datetime(1984, 2, 29, 0, 0)" -msgstr "" -">>> month_day = \"02/29\"\n" -">>> datetime.strptime(f\"{month_day};1984\", \"%m/%d;%Y\") # 沒有閏年問" -"題。\n" -"datetime.datetime(1984, 2, 29, 0, 0)" - -#: ../../library/datetime.rst:2811 -msgid "" -":meth:`~.datetime.strptime` calls using a format string containing a day of " -"month without a year now emit a :exc:`DeprecationWarning`. In 3.15 or later " -"we may change this into an error or change the default year to a leap year. " -"See :gh:`70647`." -msgstr "" - -#: ../../library/datetime.rst:2818 -msgid "Footnotes" -msgstr "註解" - -#: ../../library/datetime.rst:2819 -msgid "If, that is, we ignore the effects of Relativity" -msgstr "也就是說，我們會忽略相對論的效應" - -#: ../../library/datetime.rst:2821 -msgid "" -"This matches the definition of the \"proleptic Gregorian\" calendar in " -"Dershowitz and Reingold's book *Calendrical Calculations*, where it's the " -"base calendar for all computations. See the book for algorithms for " -"converting between proleptic Gregorian ordinals and many other calendar " -"systems." -msgstr "" - -#: ../../library/datetime.rst:2827 -msgid "" -"See R. H. van Gent's `guide to the mathematics of the ISO 8601 calendar " -"`_ for a good explanation." -msgstr "" - -#: ../../library/datetime.rst:2441 -msgid "% (percent)" -msgstr "% （百分號）" - -#: ../../library/datetime.rst:2441 -msgid "datetime format" -msgstr "datetime format（日期時間格式）" - -#~ msgid ":class:`date`; :class:`.datetime`; :class:`.time`" -#~ msgstr ":class:`date`; :class:`.datetime`; :class:`.time`" - -#~ msgid ":class:`.datetime`" -#~ msgstr ":class:`.datetime`" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-12-22 00:16+0000\n" +"PO-Revision-Date: 2023-08-07 10:20+0800\n" +"Last-Translator: Griiid \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" +"X-Generator: Poedit 3.3.2\n" + +#: ../../library/datetime.rst:2 +msgid ":mod:`!datetime` --- Basic date and time types" +msgstr ":mod:`!datetime` --- 日期與時間的基本型別" + +#: ../../library/datetime.rst:11 +msgid "**Source code:** :source:`Lib/datetime.py`" +msgstr "**原始碼：**\\ :source:`Lib/datetime.py`" + +#: ../../library/datetime.rst:17 +msgid "" +"The :mod:`!datetime` module supplies classes for manipulating dates and " +"times." +msgstr ":mod:`!datetime` 模組提供操作日期與時間的類別。" + +#: ../../library/datetime.rst:19 +msgid "" +"While date and time arithmetic is supported, the focus of the implementation " +"is on efficient attribute extraction for output formatting and manipulation." +msgstr "" + +#: ../../library/datetime.rst:24 +msgid "Skip to :ref:`the format codes `." +msgstr "跳轉至\\ :ref:`格式碼 (format codes) `。" + +#: ../../library/datetime.rst:28 +msgid "Module :mod:`calendar`" +msgstr ":mod:`calendar` 模組" + +#: ../../library/datetime.rst:29 +msgid "General calendar related functions." +msgstr "與日曆相關的一般函式。" + +#: ../../library/datetime.rst:31 +msgid "Module :mod:`time`" +msgstr ":mod:`time` 模組" + +#: ../../library/datetime.rst:32 +msgid "Time access and conversions." +msgstr "" + +#: ../../library/datetime.rst:34 +msgid "Module :mod:`zoneinfo`" +msgstr ":mod:`zoneinfo` 模組" + +#: ../../library/datetime.rst:35 +msgid "Concrete time zones representing the IANA time zone database." +msgstr "" + +#: ../../library/datetime.rst:37 +msgid "Package `dateutil `_" +msgstr "`dateutil `_ 套件" + +#: ../../library/datetime.rst:38 +msgid "Third-party library with expanded time zone and parsing support." +msgstr "帶有時區與剖析擴充支援的第三方函式庫。" + +#: ../../library/datetime.rst:40 +msgid "Package :pypi:`DateType`" +msgstr ":pypi:`DateType` 套件" + +#: ../../library/datetime.rst:41 +msgid "" +"Third-party library that introduces distinct static types to e.g. allow :" +"term:`static type checkers ` to differentiate between " +"naive and aware datetimes." +msgstr "" + +#: ../../library/datetime.rst:48 +msgid "Aware and Naive Objects" +msgstr "" + +#: ../../library/datetime.rst:50 +msgid "" +"Date and time objects may be categorized as \"aware\" or \"naive\" depending " +"on whether or not they include time zone information." +msgstr "" + +#: ../../library/datetime.rst:53 +msgid "" +"With sufficient knowledge of applicable algorithmic and political time " +"adjustments, such as time zone and daylight saving time information, an " +"**aware** object can locate itself relative to other aware objects. An aware " +"object represents a specific moment in time that is not open to " +"interpretation. [#]_" +msgstr "" + +#: ../../library/datetime.rst:59 +msgid "" +"A **naive** object does not contain enough information to unambiguously " +"locate itself relative to other date/time objects. Whether a naive object " +"represents Coordinated Universal Time (UTC), local time, or time in some " +"other time zone is purely up to the program, just like it is up to the " +"program whether a particular number represents metres, miles, or mass. Naive " +"objects are easy to understand and to work with, at the cost of ignoring " +"some aspects of reality." +msgstr "" + +#: ../../library/datetime.rst:66 +msgid "" +"For applications requiring aware objects, :class:`.datetime` and :class:`." +"time` objects have an optional time zone information attribute, :attr:`!" +"tzinfo`, that can be set to an instance of a subclass of the abstract :class:" +"`tzinfo` class. These :class:`tzinfo` objects capture information about the " +"offset from UTC time, the time zone name, and whether daylight saving time " +"is in effect." +msgstr "" + +#: ../../library/datetime.rst:72 +msgid "" +"Only one concrete :class:`tzinfo` class, the :class:`timezone` class, is " +"supplied by the :mod:`!datetime` module. The :class:`!timezone` class can " +"represent simple time zones with fixed offsets from UTC, such as UTC itself " +"or North American EST and EDT time zones. Supporting time zones at deeper " +"levels of detail is up to the application. The rules for time adjustment " +"across the world are more political than rational, change frequently, and " +"there is no standard suitable for every application aside from UTC." +msgstr "" + +#: ../../library/datetime.rst:81 +msgid "Constants" +msgstr "常數" + +#: ../../library/datetime.rst:83 +msgid "The :mod:`!datetime` module exports the following constants:" +msgstr ":mod:`!datetime` 模組匯出以下常數：" + +#: ../../library/datetime.rst:87 +msgid "" +"The smallest year number allowed in a :class:`date` or :class:`.datetime` " +"object. :const:`MINYEAR` is 1." +msgstr "" + +#: ../../library/datetime.rst:93 +msgid "" +"The largest year number allowed in a :class:`date` or :class:`.datetime` " +"object. :const:`MAXYEAR` is 9999." +msgstr "" + +#: ../../library/datetime.rst:98 +msgid "Alias for the UTC time zone singleton :attr:`datetime.timezone.utc`." +msgstr "" + +#: ../../library/datetime.rst:103 +msgid "Available Types" +msgstr "" + +#: ../../library/datetime.rst:108 +msgid "" +"An idealized naive date, assuming the current Gregorian calendar always was, " +"and always will be, in effect. Attributes: :attr:`year`, :attr:`month`, and :" +"attr:`day`." +msgstr "" + +#: ../../library/datetime.rst:116 +msgid "" +"An idealized time, independent of any particular day, assuming that every " +"day has exactly 24\\*60\\*60 seconds. (There is no notion of \"leap " +"seconds\" here.) Attributes: :attr:`hour`, :attr:`minute`, :attr:`second`, :" +"attr:`microsecond`, and :attr:`.tzinfo`." +msgstr "" + +#: ../../library/datetime.rst:125 +msgid "" +"A combination of a date and a time. Attributes: :attr:`year`, :attr:" +"`month`, :attr:`day`, :attr:`hour`, :attr:`minute`, :attr:`second`, :attr:" +"`microsecond`, and :attr:`.tzinfo`." +msgstr "" + +#: ../../library/datetime.rst:133 +msgid "" +"A duration expressing the difference between two :class:`.datetime` or :" +"class:`date` instances to microsecond resolution." +msgstr "" +"表示兩個 :class:`.datetime` 或 :class:`date` 實例之間時間的差異，以微秒為解析" +"度。" + +#: ../../library/datetime.rst:140 +msgid "" +"An abstract base class for time zone information objects. These are used by " +"the :class:`.datetime` and :class:`.time` classes to provide a customizable " +"notion of time adjustment (for example, to account for time zone and/or " +"daylight saving time)." +msgstr "" + +#: ../../library/datetime.rst:148 +msgid "" +"A class that implements the :class:`tzinfo` abstract base class as a fixed " +"offset from the UTC." +msgstr "" + +#: ../../library/datetime.rst:153 ../../library/datetime.rst:171 +msgid "Objects of these types are immutable." +msgstr "" + +#: ../../library/datetime.rst:155 +msgid "Subclass relationships::" +msgstr "" + +#: ../../library/datetime.rst:157 +msgid "" +"object\n" +" timedelta\n" +" tzinfo\n" +" timezone\n" +" time\n" +" date\n" +" datetime" +msgstr "" +"object\n" +" timedelta\n" +" tzinfo\n" +" timezone\n" +" time\n" +" date\n" +" datetime" + +#: ../../library/datetime.rst:166 +msgid "Common Properties" +msgstr "常見屬性" + +#: ../../library/datetime.rst:168 +msgid "" +"The :class:`date`, :class:`.datetime`, :class:`.time`, and :class:`timezone` " +"types share these common features:" +msgstr "" + +#: ../../library/datetime.rst:172 +msgid "" +"Objects of these types are :term:`hashable`, meaning that they can be used " +"as dictionary keys." +msgstr "" + +#: ../../library/datetime.rst:174 +msgid "" +"Objects of these types support efficient pickling via the :mod:`pickle` " +"module." +msgstr "" + +#: ../../library/datetime.rst:177 +msgid "Determining if an Object is Aware or Naive" +msgstr "" + +#: ../../library/datetime.rst:179 +msgid "Objects of the :class:`date` type are always naive." +msgstr "" + +#: ../../library/datetime.rst:181 +msgid "" +"An object of type :class:`.time` or :class:`.datetime` may be aware or naive." +msgstr "" + +#: ../../library/datetime.rst:183 +msgid "" +"A :class:`.datetime` object ``d`` is aware if both of the following hold:" +msgstr "" + +#: ../../library/datetime.rst:185 +msgid "``d.tzinfo`` is not ``None``" +msgstr "``d.tzinfo`` 不是 ``None``" + +#: ../../library/datetime.rst:186 +msgid "``d.tzinfo.utcoffset(d)`` does not return ``None``" +msgstr "``d.tzinfo.utcoffset(d)`` 不會回傳 ``None``" + +#: ../../library/datetime.rst:188 +msgid "Otherwise, ``d`` is naive." +msgstr "否則 ``d`` 會是 naive 的。" + +#: ../../library/datetime.rst:190 +msgid "A :class:`.time` object ``t`` is aware if both of the following hold:" +msgstr "" + +#: ../../library/datetime.rst:192 +msgid "``t.tzinfo`` is not ``None``" +msgstr "``t.tzinfo`` 不是 ``None``" + +#: ../../library/datetime.rst:193 +msgid "``t.tzinfo.utcoffset(None)`` does not return ``None``." +msgstr "``t.tzinfo.utcoffset(None)`` 沒有回傳 ``None``。" + +#: ../../library/datetime.rst:195 +msgid "Otherwise, ``t`` is naive." +msgstr "否則 ``t`` 會是 naive 的。" + +#: ../../library/datetime.rst:197 +msgid "" +"The distinction between aware and naive doesn't apply to :class:`timedelta` " +"objects." +msgstr "" + +#: ../../library/datetime.rst:203 +msgid ":class:`timedelta` Objects" +msgstr ":class:`timedelta` 物件" + +#: ../../library/datetime.rst:205 +msgid "" +"A :class:`timedelta` object represents a duration, the difference between " +"two :class:`.datetime` or :class:`date` instances." +msgstr "" +"一個 :class:`timedelta` 物件代表著一段持續時間，即兩個 :class:`.datetime` " +"或 :class:`date` 之間的差異。" + +#: ../../library/datetime.rst:210 +msgid "" +"All arguments are optional and default to 0. Arguments may be integers or " +"floats, and may be positive or negative." +msgstr "" + +#: ../../library/datetime.rst:213 +msgid "" +"Only *days*, *seconds* and *microseconds* are stored internally. Arguments " +"are converted to those units:" +msgstr "" + +#: ../../library/datetime.rst:216 +msgid "A millisecond is converted to 1000 microseconds." +msgstr "一毫秒會被轉換為 1000 微秒。" + +#: ../../library/datetime.rst:217 +msgid "A minute is converted to 60 seconds." +msgstr "一分鐘會被轉換為 60 秒。" + +#: ../../library/datetime.rst:218 +msgid "An hour is converted to 3600 seconds." +msgstr "一小時會被轉換為 3600 秒。" + +#: ../../library/datetime.rst:219 +msgid "A week is converted to 7 days." +msgstr "一週會被轉換為 7 天。" + +#: ../../library/datetime.rst:221 +msgid "" +"and days, seconds and microseconds are then normalized so that the " +"representation is unique, with" +msgstr "" + +#: ../../library/datetime.rst:224 +msgid "``0 <= microseconds < 1000000``" +msgstr "``0 <= microseconds < 1000000``" + +#: ../../library/datetime.rst:225 +msgid "``0 <= seconds < 3600*24`` (the number of seconds in one day)" +msgstr "" + +#: ../../library/datetime.rst:226 +msgid "``-999999999 <= days <= 999999999``" +msgstr "``-999999999 <= days <= 999999999``" + +#: ../../library/datetime.rst:228 +msgid "" +"The following example illustrates how any arguments besides *days*, " +"*seconds* and *microseconds* are \"merged\" and normalized into those three " +"resulting attributes::" +msgstr "" + +#: ../../library/datetime.rst:232 +msgid "" +">>> from datetime import timedelta\n" +">>> delta = timedelta(\n" +"... days=50,\n" +"... seconds=27,\n" +"... microseconds=10,\n" +"... milliseconds=29000,\n" +"... minutes=5,\n" +"... hours=8,\n" +"... weeks=2\n" +"... )\n" +">>> # Only days, seconds, and microseconds remain\n" +">>> delta\n" +"datetime.timedelta(days=64, seconds=29156, microseconds=10)" +msgstr "" + +#: ../../library/datetime.rst:246 +msgid "" +"If any argument is a float and there are fractional microseconds, the " +"fractional microseconds left over from all arguments are combined and their " +"sum is rounded to the nearest microsecond using round-half-to-even " +"tiebreaker. If no argument is a float, the conversion and normalization " +"processes are exact (no information is lost)." +msgstr "" + +#: ../../library/datetime.rst:253 +msgid "" +"If the normalized value of days lies outside the indicated range, :exc:" +"`OverflowError` is raised." +msgstr "" + +#: ../../library/datetime.rst:256 +msgid "" +"Note that normalization of negative values may be surprising at first. For " +"example::" +msgstr "" + +#: ../../library/datetime.rst:259 +msgid "" +">>> from datetime import timedelta\n" +">>> d = timedelta(microseconds=-1)\n" +">>> (d.days, d.seconds, d.microseconds)\n" +"(-1, 86399, 999999)" +msgstr "" +">>> from datetime import timedelta\n" +">>> d = timedelta(microseconds=-1)\n" +">>> (d.days, d.seconds, d.microseconds)\n" +"(-1, 86399, 999999)" + +#: ../../library/datetime.rst:264 +msgid "" +"Since the string representation of :class:`!timedelta` objects can be " +"confusing, use the following recipe to produce a more readable format:" +msgstr "" + +#: ../../library/datetime.rst:267 +msgid "" +">>> def pretty_timedelta(td):\n" +"... if td.days >= 0:\n" +"... return str(td)\n" +"... return f'-({-td!s})'\n" +"...\n" +">>> d = timedelta(hours=-1)\n" +">>> str(d) # not human-friendly\n" +"'-1 day, 23:00:00'\n" +">>> pretty_timedelta(d)\n" +"'-(1:00:00)'" +msgstr "" +">>> def pretty_timedelta(td):\n" +"... if td.days >= 0:\n" +"... return str(td)\n" +"... return f'-({-td!s})'\n" +"...\n" +">>> d = timedelta(hours=-1)\n" +">>> str(d) # not human-friendly\n" +"'-1 day, 23:00:00'\n" +">>> pretty_timedelta(d)\n" +"'-(1:00:00)'" + +#: ../../library/datetime.rst:281 ../../library/datetime.rst:615 +#: ../../library/datetime.rst:1175 ../../library/datetime.rst:1813 +#: ../../library/datetime.rst:2434 +msgid "Class attributes:" +msgstr "類別屬性：" + +#: ../../library/datetime.rst:285 +msgid "The most negative :class:`timedelta` object, ``timedelta(-999999999)``." +msgstr "" + +#: ../../library/datetime.rst:290 +msgid "" +"The most positive :class:`timedelta` object, ``timedelta(days=999999999, " +"hours=23, minutes=59, seconds=59, microseconds=999999)``." +msgstr "" + +#: ../../library/datetime.rst:296 +msgid "" +"The smallest possible difference between non-equal :class:`timedelta` " +"objects, ``timedelta(microseconds=1)``." +msgstr "" + +#: ../../library/datetime.rst:299 +msgid "" +"Note that, because of normalization, ``timedelta.max`` is greater than ``-" +"timedelta.min``. ``-timedelta.max`` is not representable as a :class:" +"`timedelta` object." +msgstr "" + +#: ../../library/datetime.rst:303 ../../library/datetime.rst:633 +#: ../../library/datetime.rst:1195 ../../library/datetime.rst:1833 +msgid "Instance attributes (read-only):" +msgstr "" + +#: ../../library/datetime.rst:307 +msgid "Between -999,999,999 and 999,999,999 inclusive." +msgstr "在 -999,999,999 到 999,999,999 （含）之間" + +#: ../../library/datetime.rst:312 +msgid "Between 0 and 86,399 inclusive." +msgstr "在 0 到 86,399 （含）之間" + +#: ../../library/datetime.rst:316 +msgid "" +"It is a somewhat common bug for code to unintentionally use this attribute " +"when it is actually intended to get a :meth:`~timedelta.total_seconds` value " +"instead:" +msgstr "" + +#: ../../library/datetime.rst:320 +msgid "" +">>> from datetime import timedelta\n" +">>> duration = timedelta(seconds=11235813)\n" +">>> duration.days, duration.seconds\n" +"(130, 3813)\n" +">>> duration.total_seconds()\n" +"11235813.0" +msgstr "" +">>> from datetime import timedelta\n" +">>> duration = timedelta(seconds=11235813)\n" +">>> duration.days, duration.seconds\n" +"(130, 3813)\n" +">>> duration.total_seconds()\n" +"11235813.0" + +#: ../../library/datetime.rst:331 +msgid "Between 0 and 999,999 inclusive." +msgstr "在 0 到 999,999 （含）之間" + +#: ../../library/datetime.rst:334 ../../library/datetime.rst:650 +#: ../../library/datetime.rst:1248 +msgid "Supported operations:" +msgstr "" + +#: ../../library/datetime.rst:339 ../../library/datetime.rst:653 +#: ../../library/datetime.rst:1251 +msgid "Operation" +msgstr "" + +#: ../../library/datetime.rst:339 ../../library/datetime.rst:653 +#: ../../library/datetime.rst:1251 +msgid "Result" +msgstr "" + +#: ../../library/datetime.rst:341 +msgid "``t1 = t2 + t3``" +msgstr "``t1 = t2 + t3``" + +#: ../../library/datetime.rst:341 +msgid "" +"Sum of ``t2`` and ``t3``. Afterwards ``t1 - t2 == t3`` and ``t1 - t3 == t2`` " +"are true. (1)" +msgstr "" + +#: ../../library/datetime.rst:345 +msgid "``t1 = t2 - t3``" +msgstr "``t1 = t2 - t3``" + +#: ../../library/datetime.rst:345 +msgid "" +"Difference of ``t2`` and ``t3``. Afterwards ``t1 == t2 - t3`` and ``t2 == " +"t1 + t3`` are true. (1)(6)" +msgstr "" + +#: ../../library/datetime.rst:349 +msgid "``t1 = t2 * i or t1 = i * t2``" +msgstr "``t1 = t2 * i or t1 = i * t2``" + +#: ../../library/datetime.rst:349 +msgid "" +"Delta multiplied by an integer. Afterwards ``t1 // i == t2`` is true, " +"provided ``i != 0``." +msgstr "" + +#: ../../library/datetime.rst:353 +msgid "In general, ``t1 * i == t1 * (i-1) + t1`` is true. (1)" +msgstr "" + +#: ../../library/datetime.rst:356 +msgid "``t1 = t2 * f or t1 = f * t2``" +msgstr "``t1 = t2 * f or t1 = f * t2``" + +#: ../../library/datetime.rst:356 +msgid "" +"Delta multiplied by a float. The result is rounded to the nearest multiple " +"of timedelta.resolution using round-half-to-even." +msgstr "" + +#: ../../library/datetime.rst:360 +msgid "``f = t2 / t3``" +msgstr "``f = t2 / t3``" + +#: ../../library/datetime.rst:360 +msgid "" +"Division (3) of overall duration ``t2`` by interval unit ``t3``. Returns a :" +"class:`float` object." +msgstr "" + +#: ../../library/datetime.rst:364 +msgid "``t1 = t2 / f or t1 = t2 / i``" +msgstr "``t1 = t2 / f or t1 = t2 / i``" + +#: ../../library/datetime.rst:364 +msgid "" +"Delta divided by a float or an int. The result is rounded to the nearest " +"multiple of timedelta.resolution using round-half-to-even." +msgstr "" + +#: ../../library/datetime.rst:368 +msgid "``t1 = t2 // i`` or ``t1 = t2 // t3``" +msgstr "``t1 = t2 // i`` or ``t1 = t2 // t3``" + +#: ../../library/datetime.rst:368 +msgid "" +"The floor is computed and the remainder (if any) is thrown away. In the " +"second case, an integer is returned. (3)" +msgstr "" + +#: ../../library/datetime.rst:372 +msgid "``t1 = t2 % t3``" +msgstr "``t1 = t2 % t3``" + +#: ../../library/datetime.rst:372 +msgid "The remainder is computed as a :class:`timedelta` object. (3)" +msgstr "" + +#: ../../library/datetime.rst:375 +msgid "``q, r = divmod(t1, t2)``" +msgstr "``q, r = divmod(t1, t2)``" + +#: ../../library/datetime.rst:375 +msgid "" +"Computes the quotient and the remainder: ``q = t1 // t2`` (3) and ``r = t1 % " +"t2``. ``q`` is an integer and ``r`` is a :class:`timedelta` object." +msgstr "" + +#: ../../library/datetime.rst:380 +msgid "``+t1``" +msgstr "``+t1``" + +#: ../../library/datetime.rst:380 +msgid "Returns a :class:`timedelta` object with the same value. (2)" +msgstr "" + +#: ../../library/datetime.rst:383 +msgid "``-t1``" +msgstr "``-t1``" + +#: ../../library/datetime.rst:383 +msgid "" +"Equivalent to ``timedelta(-t1.days, -t1.seconds, -t1.microseconds)``, and to " +"``t1 * -1``. (1)(4)" +msgstr "" +"等價於 ``timedelta(-t1.days, -t1.seconds, -t1.microseconds)``，也等價於 ``t1 " +"* -1``。 (1)(4)" + +#: ../../library/datetime.rst:387 +msgid "``abs(t)``" +msgstr "``abs(t)``" + +#: ../../library/datetime.rst:387 +msgid "" +"Equivalent to ``+t`` when ``t.days >= 0``, and to ``-t`` when ``t.days < " +"0``. (2)" +msgstr "" + +#: ../../library/datetime.rst:390 +msgid "``str(t)``" +msgstr "``str(t)``" + +#: ../../library/datetime.rst:390 +msgid "" +"Returns a string in the form ``[D day[s], ][H]H:MM:SS[.UUUUUU]``, where D is " +"negative for negative ``t``. (5)" +msgstr "" + +#: ../../library/datetime.rst:394 +msgid "``repr(t)``" +msgstr "``repr(t)``" + +#: ../../library/datetime.rst:394 +msgid "" +"Returns a string representation of the :class:`timedelta` object as a " +"constructor call with canonical attribute values." +msgstr "" + +#: ../../library/datetime.rst:400 ../../library/datetime.rst:672 +#: ../../library/datetime.rst:2696 +msgid "Notes:" +msgstr "註解：" + +#: ../../library/datetime.rst:403 +msgid "This is exact but may overflow." +msgstr "這是精確的，但可能會溢位。" + +#: ../../library/datetime.rst:406 +msgid "This is exact and cannot overflow." +msgstr "這是精確的，且不會溢位。" + +#: ../../library/datetime.rst:409 +msgid "Division by zero raises :exc:`ZeroDivisionError`." +msgstr "" + +#: ../../library/datetime.rst:412 +msgid "``-timedelta.max`` is not representable as a :class:`timedelta` object." +msgstr "" + +#: ../../library/datetime.rst:415 +msgid "" +"String representations of :class:`timedelta` objects are normalized " +"similarly to their internal representation. This leads to somewhat unusual " +"results for negative timedeltas. For example::" +msgstr "" + +#: ../../library/datetime.rst:419 +msgid "" +">>> timedelta(hours=-5)\n" +"datetime.timedelta(days=-1, seconds=68400)\n" +">>> print(_)\n" +"-1 day, 19:00:00" +msgstr "" +">>> timedelta(hours=-5)\n" +"datetime.timedelta(days=-1, seconds=68400)\n" +">>> print(_)\n" +"-1 day, 19:00:00" + +#: ../../library/datetime.rst:425 +msgid "" +"The expression ``t2 - t3`` will always be equal to the expression ``t2 + (-" +"t3)`` except when t3 is equal to ``timedelta.max``; in that case the former " +"will produce a result while the latter will overflow." +msgstr "" + +#: ../../library/datetime.rst:429 +msgid "" +"In addition to the operations listed above, :class:`timedelta` objects " +"support certain additions and subtractions with :class:`date` and :class:`." +"datetime` objects (see below)." +msgstr "" + +#: ../../library/datetime.rst:433 +msgid "" +"Floor division and true division of a :class:`timedelta` object by another :" +"class:`timedelta` object are now supported, as are remainder operations and " +"the :func:`divmod` function. True division and multiplication of a :class:" +"`timedelta` object by a :class:`float` object are now supported." +msgstr "" + +#: ../../library/datetime.rst:439 +msgid ":class:`timedelta` objects support equality and order comparisons." +msgstr "" + +#: ../../library/datetime.rst:441 +msgid "" +"In Boolean contexts, a :class:`timedelta` object is considered to be true if " +"and only if it isn't equal to ``timedelta(0)``." +msgstr "" + +#: ../../library/datetime.rst:444 ../../library/datetime.rst:714 +#: ../../library/datetime.rst:1338 ../../library/datetime.rst:1956 +msgid "Instance methods:" +msgstr "實例方法：" + +#: ../../library/datetime.rst:448 +msgid "" +"Return the total number of seconds contained in the duration. Equivalent to " +"``td / timedelta(seconds=1)``. For interval units other than seconds, use " +"the division form directly (e.g. ``td / timedelta(microseconds=1)``)." +msgstr "" + +#: ../../library/datetime.rst:452 +msgid "" +"Note that for very large time intervals (greater than 270 years on most " +"platforms) this method will lose microsecond accuracy." +msgstr "" + +#: ../../library/datetime.rst:458 +msgid "Examples of usage: :class:`timedelta`" +msgstr "用法範例：:class:`timedelta`" + +#: ../../library/datetime.rst:460 +msgid "An additional example of normalization::" +msgstr "" + +#: ../../library/datetime.rst:462 +msgid "" +">>> # Components of another_year add up to exactly 365 days\n" +">>> from datetime import timedelta\n" +">>> year = timedelta(days=365)\n" +">>> another_year = timedelta(weeks=40, days=84, hours=23,\n" +"... minutes=50, seconds=600)\n" +">>> year == another_year\n" +"True\n" +">>> year.total_seconds()\n" +"31536000.0" +msgstr "" + +#: ../../library/datetime.rst:472 +msgid "Examples of :class:`timedelta` arithmetic::" +msgstr "" + +#: ../../library/datetime.rst:474 +msgid "" +">>> from datetime import timedelta\n" +">>> year = timedelta(days=365)\n" +">>> ten_years = 10 * year\n" +">>> ten_years\n" +"datetime.timedelta(days=3650)\n" +">>> ten_years.days // 365\n" +"10\n" +">>> nine_years = ten_years - year\n" +">>> nine_years\n" +"datetime.timedelta(days=3285)\n" +">>> three_years = nine_years // 3\n" +">>> three_years, three_years.days // 365\n" +"(datetime.timedelta(days=1095), 3)" +msgstr "" +">>> from datetime import timedelta\n" +">>> year = timedelta(days=365)\n" +">>> ten_years = 10 * year\n" +">>> ten_years\n" +"datetime.timedelta(days=3650)\n" +">>> ten_years.days // 365\n" +"10\n" +">>> nine_years = ten_years - year\n" +">>> nine_years\n" +"datetime.timedelta(days=3285)\n" +">>> three_years = nine_years // 3\n" +">>> three_years, three_years.days // 365\n" +"(datetime.timedelta(days=1095), 3)" + +#: ../../library/datetime.rst:491 +msgid ":class:`date` Objects" +msgstr ":class:`date` 物件" + +#: ../../library/datetime.rst:493 +msgid "" +"A :class:`date` object represents a date (year, month and day) in an " +"idealized calendar, the current Gregorian calendar indefinitely extended in " +"both directions." +msgstr "" + +#: ../../library/datetime.rst:497 +msgid "" +"January 1 of year 1 is called day number 1, January 2 of year 1 is called " +"day number 2, and so on. [#]_" +msgstr "" + +#: ../../library/datetime.rst:502 +msgid "" +"All arguments are required. Arguments must be integers, in the following " +"ranges:" +msgstr "" + +#: ../../library/datetime.rst:505 +msgid "``MINYEAR <= year <= MAXYEAR``" +msgstr "``MINYEAR <= year <= MAXYEAR``" + +#: ../../library/datetime.rst:506 +msgid "``1 <= month <= 12``" +msgstr "``1 <= month <= 12``" + +#: ../../library/datetime.rst:507 +msgid "``1 <= day <= number of days in the given month and year``" +msgstr "``1 <= day <= 該年該月的天數``" + +#: ../../library/datetime.rst:509 ../../library/datetime.rst:932 +msgid "" +"If an argument outside those ranges is given, :exc:`ValueError` is raised." +msgstr "" + +#: ../../library/datetime.rst:512 ../../library/datetime.rst:937 +msgid "Other constructors, all class methods:" +msgstr "" + +#: ../../library/datetime.rst:516 +msgid "Return the current local date." +msgstr "回傳目前的本地日期。" + +#: ../../library/datetime.rst:518 +msgid "This is equivalent to ``date.fromtimestamp(time.time())``." +msgstr "這等同於 ``date.fromtimestamp(time.time())``。" + +#: ../../library/datetime.rst:522 +msgid "" +"Return the local date corresponding to the POSIX timestamp, such as is " +"returned by :func:`time.time`." +msgstr "" + +#: ../../library/datetime.rst:525 +msgid "" +"This may raise :exc:`OverflowError`, if the timestamp is out of the range of " +"values supported by the platform C :c:func:`localtime` function, and :exc:" +"`OSError` on :c:func:`localtime` failure. It's common for this to be " +"restricted to years from 1970 through 2038. Note that on non-POSIX systems " +"that include leap seconds in their notion of a timestamp, leap seconds are " +"ignored by :meth:`fromtimestamp`." +msgstr "" + +#: ../../library/datetime.rst:532 +msgid "" +"Raise :exc:`OverflowError` instead of :exc:`ValueError` if the timestamp is " +"out of the range of values supported by the platform C :c:func:`localtime` " +"function. Raise :exc:`OSError` instead of :exc:`ValueError` on :c:func:" +"`localtime` failure." +msgstr "" + +#: ../../library/datetime.rst:541 +msgid "" +"Return the date corresponding to the proleptic Gregorian ordinal, where " +"January 1 of year 1 has ordinal 1." +msgstr "" + +#: ../../library/datetime.rst:544 +msgid "" +":exc:`ValueError` is raised unless ``1 <= ordinal <= date.max.toordinal()``. " +"For any date ``d``, ``date.fromordinal(d.toordinal()) == d``." +msgstr "" + +#: ../../library/datetime.rst:551 +msgid "" +"Return a :class:`date` corresponding to a *date_string* given in any valid " +"ISO 8601 format, with the following exceptions:" +msgstr "" + +#: ../../library/datetime.rst:554 ../../library/datetime.rst:1097 +msgid "" +"Reduced precision dates are not currently supported (``YYYY-MM``, ``YYYY``)." +msgstr "" + +#: ../../library/datetime.rst:556 ../../library/datetime.rst:1099 +msgid "" +"Extended date representations are not currently supported (``±YYYYYY-MM-" +"DD``)." +msgstr "" + +#: ../../library/datetime.rst:558 ../../library/datetime.rst:1101 +msgid "Ordinal dates are not currently supported (``YYYY-OOO``)." +msgstr "" + +#: ../../library/datetime.rst:560 ../../library/datetime.rst:1103 +#: ../../library/datetime.rst:1569 +msgid "Examples::" +msgstr "範例： ::" + +#: ../../library/datetime.rst:562 +msgid "" +">>> from datetime import date\n" +">>> date.fromisoformat('2019-12-04')\n" +"datetime.date(2019, 12, 4)\n" +">>> date.fromisoformat('20191204')\n" +"datetime.date(2019, 12, 4)\n" +">>> date.fromisoformat('2021-W01-1')\n" +"datetime.date(2021, 1, 4)" +msgstr "" +">>> from datetime import date\n" +">>> date.fromisoformat('2019-12-04')\n" +"datetime.date(2019, 12, 4)\n" +">>> date.fromisoformat('20191204')\n" +"datetime.date(2019, 12, 4)\n" +">>> date.fromisoformat('2021-W01-1')\n" +"datetime.date(2021, 1, 4)" + +#: ../../library/datetime.rst:571 +msgid "Previously, this method only supported the format ``YYYY-MM-DD``." +msgstr "" + +#: ../../library/datetime.rst:576 +msgid "" +"Return a :class:`date` corresponding to the ISO calendar date specified by " +"year, week and day. This is the inverse of the function :meth:`date." +"isocalendar`." +msgstr "" + +#: ../../library/datetime.rst:583 +msgid "" +"Return a :class:`.date` corresponding to *date_string*, parsed according to " +"*format*. This is equivalent to::" +msgstr "" + +#: ../../library/datetime.rst:586 +msgid "date(*(time.strptime(date_string, format)[0:3]))" +msgstr "date(*(time.strptime(date_string, format)[0:3]))" + +#: ../../library/datetime.rst:588 +msgid "" +":exc:`ValueError` is raised if the date_string and format can't be parsed " +"by :func:`time.strptime` or if it returns a value which isn't a time tuple. " +"See also :ref:`strftime-strptime-behavior` and :meth:`date.fromisoformat`." +msgstr "" + +#: ../../library/datetime.rst:595 +msgid "" +"If *format* specifies a day of month without a year a :exc:" +"`DeprecationWarning` is emitted. This is to avoid a quadrennial leap year " +"bug in code seeking to parse only a month and day as the default year used " +"in absence of one in the format is not a leap year. Such *format* values may " +"raise an error as of Python 3.15. The workaround is to always include a " +"year in your *format*. If parsing *date_string* values that do not have a " +"year, explicitly add a year that is a leap year before parsing:" +msgstr "" + +#: ../../library/datetime.rst:604 +msgid "" +">>> from datetime import date\n" +">>> date_string = \"02/29\"\n" +">>> when = date.strptime(f\"{date_string};1984\", \"%m/%d;%Y\") # Avoids " +"leap year bug.\n" +">>> when.strftime(\"%B %d\")\n" +"'February 29'" +msgstr "" +">>> from datetime import date\n" +">>> date_string = \"02/29\"\n" +">>> when = date.strptime(f\"{date_string};1984\", \"%m/%d;%Y\") # 避免閏年錯" +"誤。\n" +">>> when.strftime(\"%B %d\")\n" +"'February 29'" + +#: ../../library/datetime.rst:619 +msgid "The earliest representable date, ``date(MINYEAR, 1, 1)``." +msgstr "" + +#: ../../library/datetime.rst:624 +msgid "The latest representable date, ``date(MAXYEAR, 12, 31)``." +msgstr "" + +#: ../../library/datetime.rst:629 +msgid "" +"The smallest possible difference between non-equal date objects, " +"``timedelta(days=1)``." +msgstr "" + +#: ../../library/datetime.rst:637 ../../library/datetime.rst:1199 +msgid "Between :const:`MINYEAR` and :const:`MAXYEAR` inclusive." +msgstr "" + +#: ../../library/datetime.rst:642 ../../library/datetime.rst:1204 +msgid "Between 1 and 12 inclusive." +msgstr "在 1 到 12 （含）之間。" + +#: ../../library/datetime.rst:647 ../../library/datetime.rst:1209 +msgid "Between 1 and the number of days in the given month of the given year." +msgstr "" + +#: ../../library/datetime.rst:655 +msgid "``date2 = date1 + timedelta``" +msgstr "``date2 = date1 + timedelta``" + +#: ../../library/datetime.rst:655 +msgid "``date2`` will be ``timedelta.days`` days after ``date1``. (1)" +msgstr "" + +#: ../../library/datetime.rst:658 +msgid "``date2 = date1 - timedelta``" +msgstr "``date2 = date1 - timedelta``" + +#: ../../library/datetime.rst:658 +msgid "Computes ``date2`` such that ``date2 + timedelta == date1``. (2)" +msgstr "" + +#: ../../library/datetime.rst:661 +msgid "``timedelta = date1 - date2``" +msgstr "``timedelta = date1 - date2``" + +#: ../../library/datetime.rst:661 ../../library/datetime.rst:1257 +msgid "\\(3)" +msgstr "\\(3)" + +#: ../../library/datetime.rst:663 +msgid "``date1 == date2``" +msgstr "``date1 == date2``" + +#: ../../library/datetime.rst:664 +msgid "``date1 != date2``" +msgstr "``date1 != date2``" + +#: ../../library/datetime.rst:663 ../../library/datetime.rst:1259 +msgid "Equality comparison. (4)" +msgstr "" + +#: ../../library/datetime.rst:666 +msgid "``date1 < date2``" +msgstr "``date1 < date2``" + +#: ../../library/datetime.rst:667 +msgid "``date1 > date2``" +msgstr "``date1 > date2``" + +#: ../../library/datetime.rst:668 +msgid "``date1 <= date2``" +msgstr "``date1 <= date2``" + +#: ../../library/datetime.rst:669 +msgid "``date1 >= date2``" +msgstr "``date1 >= date2``" + +#: ../../library/datetime.rst:666 ../../library/datetime.rst:1262 +msgid "Order comparison. (5)" +msgstr "" + +#: ../../library/datetime.rst:675 +msgid "" +"*date2* is moved forward in time if ``timedelta.days > 0``, or backward if " +"``timedelta.days < 0``. Afterward ``date2 - date1 == timedelta.days``. " +"``timedelta.seconds`` and ``timedelta.microseconds`` are ignored. :exc:" +"`OverflowError` is raised if ``date2.year`` would be smaller than :const:" +"`MINYEAR` or larger than :const:`MAXYEAR`." +msgstr "" + +#: ../../library/datetime.rst:682 +msgid "``timedelta.seconds`` and ``timedelta.microseconds`` are ignored." +msgstr "``timedelta.seconds`` 和 ``timedelta.microseconds`` 被忽略。" + +#: ../../library/datetime.rst:685 +msgid "" +"This is exact, and cannot overflow. ``timedelta.seconds`` and ``timedelta." +"microseconds`` are 0, and ``date2 + timedelta == date1`` after." +msgstr "" + +#: ../../library/datetime.rst:689 +msgid ":class:`date` objects are equal if they represent the same date." +msgstr "" + +#: ../../library/datetime.rst:691 +msgid "" +":class:`!date` objects that are not also :class:`.datetime` instances are " +"never equal to :class:`!datetime` objects, even if they represent the same " +"date." +msgstr "" + +#: ../../library/datetime.rst:696 +msgid "" +"*date1* is considered less than *date2* when *date1* precedes *date2* in " +"time. In other words, ``date1 < date2`` if and only if ``date1.toordinal() < " +"date2.toordinal()``." +msgstr "" + +#: ../../library/datetime.rst:700 +msgid "" +"Order comparison between a :class:`!date` object that is not also a :class:`." +"datetime` instance and a :class:`!datetime` object raises :exc:`TypeError`." +msgstr "" + +#: ../../library/datetime.rst:704 ../../library/datetime.rst:1330 +msgid "" +"Comparison between :class:`.datetime` object and an instance of the :class:" +"`date` subclass that is not a :class:`!datetime` subclass no longer converts " +"the latter to :class:`!date`, ignoring the time part and the time zone. The " +"default behavior can be changed by overriding the special comparison methods " +"in subclasses." +msgstr "" + +#: ../../library/datetime.rst:712 +msgid "" +"In Boolean contexts, all :class:`date` objects are considered to be true." +msgstr "" + +#: ../../library/datetime.rst:718 +msgid "" +"Return a new :class:`date` object with the same values, but with specified " +"parameters updated." +msgstr "" + +#: ../../library/datetime.rst:721 ../../library/datetime.rst:2002 +msgid "Example::" +msgstr "範例： ::" + +#: ../../library/datetime.rst:723 +msgid "" +">>> from datetime import date\n" +">>> d = date(2002, 12, 31)\n" +">>> d.replace(day=26)\n" +"datetime.date(2002, 12, 26)" +msgstr "" +">>> from datetime import date\n" +">>> d = date(2002, 12, 31)\n" +">>> d.replace(day=26)\n" +"datetime.date(2002, 12, 26)" + +#: ../../library/datetime.rst:728 +msgid "" +"The generic function :func:`copy.replace` also supports :class:`date` " +"objects." +msgstr "" + +#: ../../library/datetime.rst:734 ../../library/datetime.rst:1454 +msgid "" +"Return a :class:`time.struct_time` such as returned by :func:`time." +"localtime`." +msgstr "" +"回傳一個 :class:`time.struct_time`，如同 :func:`time.localtime` 所回傳。" + +#: ../../library/datetime.rst:736 +msgid "The hours, minutes and seconds are 0, and the DST flag is -1." +msgstr "" + +#: ../../library/datetime.rst:738 ../../library/datetime.rst:1456 +msgid "``d.timetuple()`` is equivalent to::" +msgstr "``d.timetuple()`` 等價於： ::" + +#: ../../library/datetime.rst:740 +msgid "" +"time.struct_time((d.year, d.month, d.day, 0, 0, 0, d.weekday(), yday, -1))" +msgstr "" +"time.struct_time((d.year, d.month, d.day, 0, 0, 0, d.weekday(), yday, -1))" + +#: ../../library/datetime.rst:742 +msgid "" +"where ``yday = d.toordinal() - date(d.year, 1, 1).toordinal() + 1`` is the " +"day number within the current year starting with 1 for January 1st." +msgstr "" + +#: ../../library/datetime.rst:748 +msgid "" +"Return the proleptic Gregorian ordinal of the date, where January 1 of year " +"1 has ordinal 1. For any :class:`date` object ``d``, ``date.fromordinal(d." +"toordinal()) == d``." +msgstr "" + +#: ../../library/datetime.rst:755 +msgid "" +"Return the day of the week as an integer, where Monday is 0 and Sunday is 6. " +"For example, ``date(2002, 12, 4).weekday() == 2``, a Wednesday. See also :" +"meth:`isoweekday`." +msgstr "" +"回傳一個代表星期幾的整數，星期一為 0、星期日為 6。例如 ``date(2002, 12, 4)." +"weekday() == 2`` 為星期三。也請參考 :meth:`isoweekday`。" + +#: ../../library/datetime.rst:762 +msgid "" +"Return the day of the week as an integer, where Monday is 1 and Sunday is 7. " +"For example, ``date(2002, 12, 4).isoweekday() == 3``, a Wednesday. See also :" +"meth:`weekday`, :meth:`isocalendar`." +msgstr "" + +#: ../../library/datetime.rst:769 +msgid "" +"Return a :term:`named tuple` object with three components: ``year``, " +"``week`` and ``weekday``." +msgstr "" + +#: ../../library/datetime.rst:772 +msgid "" +"The ISO calendar is a widely used variant of the Gregorian calendar. [#]_" +msgstr "" + +#: ../../library/datetime.rst:774 +msgid "" +"The ISO year consists of 52 or 53 full weeks, and where a week starts on a " +"Monday and ends on a Sunday. The first week of an ISO year is the first " +"(Gregorian) calendar week of a year containing a Thursday. This is called " +"week number 1, and the ISO year of that Thursday is the same as its " +"Gregorian year." +msgstr "" + +#: ../../library/datetime.rst:779 +msgid "" +"For example, 2004 begins on a Thursday, so the first week of ISO year 2004 " +"begins on Monday, 29 Dec 2003 and ends on Sunday, 4 Jan 2004::" +msgstr "" + +#: ../../library/datetime.rst:782 +msgid "" +">>> from datetime import date\n" +">>> date(2003, 12, 29).isocalendar()\n" +"datetime.IsoCalendarDate(year=2004, week=1, weekday=1)\n" +">>> date(2004, 1, 4).isocalendar()\n" +"datetime.IsoCalendarDate(year=2004, week=1, weekday=7)" +msgstr "" +">>> from datetime import date\n" +">>> date(2003, 12, 29).isocalendar()\n" +"datetime.IsoCalendarDate(year=2004, week=1, weekday=1)\n" +">>> date(2004, 1, 4).isocalendar()\n" +"datetime.IsoCalendarDate(year=2004, week=1, weekday=7)" + +#: ../../library/datetime.rst:788 +msgid "Result changed from a tuple to a :term:`named tuple`." +msgstr "" + +#: ../../library/datetime.rst:793 +msgid "" +"Return a string representing the date in ISO 8601 format, ``YYYY-MM-DD``::" +msgstr "回傳一以 ISO 8601 格式 ``YYYY-MM-DD`` 表示的日期字串： ::" + +#: ../../library/datetime.rst:795 +msgid "" +">>> from datetime import date\n" +">>> date(2002, 12, 4).isoformat()\n" +"'2002-12-04'" +msgstr "" +">>> from datetime import date\n" +">>> date(2002, 12, 4).isoformat()\n" +"'2002-12-04'" + +#: ../../library/datetime.rst:801 +msgid "For a date ``d``, ``str(d)`` is equivalent to ``d.isoformat()``." +msgstr "" + +#: ../../library/datetime.rst:806 +msgid "Return a string representing the date::" +msgstr "" + +#: ../../library/datetime.rst:808 +msgid "" +">>> from datetime import date\n" +">>> date(2002, 12, 4).ctime()\n" +"'Wed Dec 4 00:00:00 2002'" +msgstr "" +">>> from datetime import date\n" +">>> date(2002, 12, 4).ctime()\n" +"'Wed Dec 4 00:00:00 2002'" + +#: ../../library/datetime.rst:812 ../../library/datetime.rst:1640 +msgid "``d.ctime()`` is equivalent to::" +msgstr "``d.ctime()`` 等價於： ::" + +#: ../../library/datetime.rst:814 ../../library/datetime.rst:1642 +msgid "time.ctime(time.mktime(d.timetuple()))" +msgstr "time.ctime(time.mktime(d.timetuple()))" + +#: ../../library/datetime.rst:816 +msgid "" +"on platforms where the native C :c:func:`ctime` function (which :func:`time." +"ctime` invokes, but which :meth:`date.ctime` does not invoke) conforms to " +"the C standard." +msgstr "" + +#: ../../library/datetime.rst:823 +msgid "" +"Return a string representing the date, controlled by an explicit format " +"string. Format codes referring to hours, minutes or seconds will see 0 " +"values. See also :ref:`strftime-strptime-behavior` and :meth:`date." +"isoformat`." +msgstr "" + +#: ../../library/datetime.rst:830 +msgid "" +"Same as :meth:`.date.strftime`. This makes it possible to specify a format " +"string for a :class:`.date` object in :ref:`formatted string literals ` and when using :meth:`str.format`. See also :ref:`strftime-" +"strptime-behavior` and :meth:`date.isoformat`." +msgstr "" + +#: ../../library/datetime.rst:836 +msgid "Examples of Usage: :class:`date`" +msgstr "用法範例：:class:`date`" + +#: ../../library/datetime.rst:838 +msgid "Example of counting days to an event::" +msgstr "計算一個事件的天數的範例： ::" + +#: ../../library/datetime.rst:840 +msgid "" +">>> import time\n" +">>> from datetime import date\n" +">>> today = date.today()\n" +">>> today\n" +"datetime.date(2007, 12, 5)\n" +">>> today == date.fromtimestamp(time.time())\n" +"True\n" +">>> my_birthday = date(today.year, 6, 24)\n" +">>> if my_birthday < today:\n" +"... my_birthday = my_birthday.replace(year=today.year + 1)\n" +"...\n" +">>> my_birthday\n" +"datetime.date(2008, 6, 24)\n" +">>> time_to_birthday = abs(my_birthday - today)\n" +">>> time_to_birthday.days\n" +"202" +msgstr "" +">>> import time\n" +">>> from datetime import date\n" +">>> today = date.today()\n" +">>> today\n" +"datetime.date(2007, 12, 5)\n" +">>> today == date.fromtimestamp(time.time())\n" +"True\n" +">>> my_birthday = date(today.year, 6, 24)\n" +">>> if my_birthday < today:\n" +"... my_birthday = my_birthday.replace(year=today.year + 1)\n" +"...\n" +">>> my_birthday\n" +"datetime.date(2008, 6, 24)\n" +">>> time_to_birthday = abs(my_birthday - today)\n" +">>> time_to_birthday.days\n" +"202" + +#: ../../library/datetime.rst:857 +msgid "More examples of working with :class:`date`:" +msgstr "更多 :class:`date` 的用法範例：" + +#: ../../library/datetime.rst:859 +msgid "" +">>> from datetime import date\n" +">>> d = date.fromordinal(730920) # 730920th day after 1. 1. 0001\n" +">>> d\n" +"datetime.date(2002, 3, 11)\n" +"\n" +">>> # Methods related to formatting string output\n" +">>> d.isoformat()\n" +"'2002-03-11'\n" +">>> d.strftime(\"%d/%m/%y\")\n" +"'11/03/02'\n" +">>> d.strftime(\"%A %d. %B %Y\")\n" +"'Monday 11. March 2002'\n" +">>> d.ctime()\n" +"'Mon Mar 11 00:00:00 2002'\n" +">>> 'The {1} is {0:%d}, the {2} is {0:%B}.'.format(d, \"day\", \"month\")\n" +"'The day is 11, the month is March.'\n" +"\n" +">>> # Methods for to extracting 'components' under different calendars\n" +">>> t = d.timetuple()\n" +">>> for i in t:\n" +"... print(i)\n" +"2002 # year\n" +"3 # month\n" +"11 # day\n" +"0\n" +"0\n" +"0\n" +"0 # weekday (0 = Monday)\n" +"70 # 70th day in the year\n" +"-1\n" +">>> ic = d.isocalendar()\n" +">>> for i in ic:\n" +"... print(i)\n" +"2002 # ISO year\n" +"11 # ISO week number\n" +"1 # ISO day number ( 1 = Monday )\n" +"\n" +">>> # A date object is immutable; all operations produce a new object\n" +">>> d.replace(year=2005)\n" +"datetime.date(2005, 3, 11)" +msgstr "" + +#: ../../library/datetime.rst:906 +msgid ":class:`.datetime` Objects" +msgstr ":class:`.datetime` 物件" + +#: ../../library/datetime.rst:908 +msgid "" +"A :class:`.datetime` object is a single object containing all the " +"information from a :class:`date` object and a :class:`.time` object." +msgstr "" + +#: ../../library/datetime.rst:911 +msgid "" +"Like a :class:`date` object, :class:`.datetime` assumes the current " +"Gregorian calendar extended in both directions; like a :class:`.time` " +"object, :class:`.datetime` assumes there are exactly 3600\\*24 seconds in " +"every day." +msgstr "" + +#: ../../library/datetime.rst:915 +msgid "Constructor:" +msgstr "建構函式：" + +#: ../../library/datetime.rst:919 +msgid "" +"The *year*, *month* and *day* arguments are required. *tzinfo* may be " +"``None``, or an instance of a :class:`tzinfo` subclass. The remaining " +"arguments must be integers in the following ranges:" +msgstr "" + +#: ../../library/datetime.rst:923 +msgid "``MINYEAR <= year <= MAXYEAR``," +msgstr "``MINYEAR <= year <= MAXYEAR``," + +#: ../../library/datetime.rst:924 +msgid "``1 <= month <= 12``," +msgstr "``1 <= month <= 12``," + +#: ../../library/datetime.rst:925 +msgid "``1 <= day <= number of days in the given month and year``," +msgstr "" + +#: ../../library/datetime.rst:926 ../../library/datetime.rst:1804 +msgid "``0 <= hour < 24``," +msgstr "``0 <= hour < 24``," + +#: ../../library/datetime.rst:927 ../../library/datetime.rst:1805 +msgid "``0 <= minute < 60``," +msgstr "``0 <= minute < 60``," + +#: ../../library/datetime.rst:928 ../../library/datetime.rst:1806 +msgid "``0 <= second < 60``," +msgstr "``0 <= second < 60``," + +#: ../../library/datetime.rst:929 ../../library/datetime.rst:1807 +msgid "``0 <= microsecond < 1000000``," +msgstr "``0 <= microsecond < 1000000``," + +#: ../../library/datetime.rst:930 ../../library/datetime.rst:1808 +msgid "``fold in [0, 1]``." +msgstr "``fold in [0, 1]``。" + +#: ../../library/datetime.rst:934 ../../library/datetime.rst:1375 +#: ../../library/datetime.rst:1969 +msgid "Added the *fold* parameter." +msgstr "新增 *fold* 參數。" + +#: ../../library/datetime.rst:941 +msgid "Return the current local date and time, with :attr:`.tzinfo` ``None``." +msgstr "回傳目前的本地日期與時間，且 :attr:`.tzinfo` 為 ``None``。" + +#: ../../library/datetime.rst:943 +msgid "Equivalent to::" +msgstr "等價於： ::" + +#: ../../library/datetime.rst:945 +msgid "datetime.fromtimestamp(time.time())" +msgstr "datetime.fromtimestamp(time.time())" + +#: ../../library/datetime.rst:947 +msgid "See also :meth:`now`, :meth:`fromtimestamp`." +msgstr "也請見 :meth:`now`、:meth:`fromtimestamp`。" + +#: ../../library/datetime.rst:949 +msgid "" +"This method is functionally equivalent to :meth:`now`, but without a ``tz`` " +"parameter." +msgstr "" + +#: ../../library/datetime.rst:954 +msgid "Return the current local date and time." +msgstr "" + +#: ../../library/datetime.rst:956 +msgid "" +"If optional argument *tz* is ``None`` or not specified, this is like :meth:" +"`today`, but, if possible, supplies more precision than can be gotten from " +"going through a :func:`time.time` timestamp (for example, this may be " +"possible on platforms supplying the C :c:func:`gettimeofday` function)." +msgstr "" +"如果選用的引數 *tz* 為 ``None`` 或未指定，則會像是 :meth:`today`，但盡可能提" +"供比透過 :func:`time.time` 取得的時間戳記更多位數的資訊（例如，這在有提供 C :" +"c:func:`gettimeofday` 函式的平台上可能可行）。" + +#: ../../library/datetime.rst:962 +msgid "" +"If *tz* is not ``None``, it must be an instance of a :class:`tzinfo` " +"subclass, and the current date and time are converted to *tz*’s time zone." +msgstr "" + +#: ../../library/datetime.rst:965 +msgid "This function is preferred over :meth:`today` and :meth:`utcnow`." +msgstr "" + +#: ../../library/datetime.rst:969 +msgid "" +"Subsequent calls to :meth:`!datetime.now` may return the same instant " +"depending on the precision of the underlying clock." +msgstr "" + +#: ../../library/datetime.rst:974 +msgid "Return the current UTC date and time, with :attr:`.tzinfo` ``None``." +msgstr "" + +#: ../../library/datetime.rst:976 +msgid "" +"This is like :meth:`now`, but returns the current UTC date and time, as a " +"naive :class:`.datetime` object. An aware current UTC datetime can be " +"obtained by calling ``datetime.now(timezone.utc)``. See also :meth:`now`." +msgstr "" + +#: ../../library/datetime.rst:982 +msgid "" +"Because naive ``datetime`` objects are treated by many ``datetime`` methods " +"as local times, it is preferred to use aware datetimes to represent times in " +"UTC. As such, the recommended way to create an object representing the " +"current time in UTC is by calling ``datetime.now(timezone.utc)``." +msgstr "" + +#: ../../library/datetime.rst:989 +msgid "Use :meth:`datetime.now` with :const:`UTC` instead." +msgstr "" + +#: ../../library/datetime.rst:994 +msgid "" +"Return the local date and time corresponding to the POSIX timestamp, such as " +"is returned by :func:`time.time`. If optional argument *tz* is ``None`` or " +"not specified, the timestamp is converted to the platform's local date and " +"time, and the returned :class:`.datetime` object is naive." +msgstr "" + +#: ../../library/datetime.rst:999 +msgid "" +"If *tz* is not ``None``, it must be an instance of a :class:`tzinfo` " +"subclass, and the timestamp is converted to *tz*’s time zone." +msgstr "" + +#: ../../library/datetime.rst:1002 +msgid "" +":meth:`fromtimestamp` may raise :exc:`OverflowError`, if the timestamp is " +"out of the range of values supported by the platform C :c:func:`localtime` " +"or :c:func:`gmtime` functions, and :exc:`OSError` on :c:func:`localtime` or :" +"c:func:`gmtime` failure. It's common for this to be restricted to years in " +"1970 through 2038. Note that on non-POSIX systems that include leap seconds " +"in their notion of a timestamp, leap seconds are ignored by :meth:" +"`fromtimestamp`, and then it's possible to have two timestamps differing by " +"a second that yield identical :class:`.datetime` objects. This method is " +"preferred over :meth:`utcfromtimestamp`." +msgstr "" + +#: ../../library/datetime.rst:1013 +msgid "" +"Raise :exc:`OverflowError` instead of :exc:`ValueError` if the timestamp is " +"out of the range of values supported by the platform C :c:func:`localtime` " +"or :c:func:`gmtime` functions. Raise :exc:`OSError` instead of :exc:" +"`ValueError` on :c:func:`localtime` or :c:func:`gmtime` failure." +msgstr "" + +#: ../../library/datetime.rst:1020 +msgid ":meth:`fromtimestamp` may return instances with :attr:`.fold` set to 1." +msgstr "" + +#: ../../library/datetime.rst:1025 +msgid "" +"Return the UTC :class:`.datetime` corresponding to the POSIX timestamp, " +"with :attr:`.tzinfo` ``None``. (The resulting object is naive.)" +msgstr "" + +#: ../../library/datetime.rst:1028 +msgid "" +"This may raise :exc:`OverflowError`, if the timestamp is out of the range of " +"values supported by the platform C :c:func:`gmtime` function, and :exc:" +"`OSError` on :c:func:`gmtime` failure. It's common for this to be restricted " +"to years in 1970 through 2038." +msgstr "" + +#: ../../library/datetime.rst:1033 +msgid "To get an aware :class:`.datetime` object, call :meth:`fromtimestamp`::" +msgstr "" + +#: ../../library/datetime.rst:1035 +msgid "datetime.fromtimestamp(timestamp, timezone.utc)" +msgstr "datetime.fromtimestamp(timestamp, timezone.utc)" + +#: ../../library/datetime.rst:1037 +msgid "" +"On the POSIX compliant platforms, it is equivalent to the following " +"expression::" +msgstr "" + +#: ../../library/datetime.rst:1040 +msgid "" +"datetime(1970, 1, 1, tzinfo=timezone.utc) + timedelta(seconds=timestamp)" +msgstr "" +"datetime(1970, 1, 1, tzinfo=timezone.utc) + timedelta(seconds=timestamp)" + +#: ../../library/datetime.rst:1042 +msgid "" +"except the latter formula always supports the full years range: between :" +"const:`MINYEAR` and :const:`MAXYEAR` inclusive." +msgstr "" + +#: ../../library/datetime.rst:1047 +msgid "" +"Because naive ``datetime`` objects are treated by many ``datetime`` methods " +"as local times, it is preferred to use aware datetimes to represent times in " +"UTC. As such, the recommended way to create an object representing a " +"specific timestamp in UTC is by calling ``datetime.fromtimestamp(timestamp, " +"tz=timezone.utc)``." +msgstr "" + +#: ../../library/datetime.rst:1053 +msgid "" +"Raise :exc:`OverflowError` instead of :exc:`ValueError` if the timestamp is " +"out of the range of values supported by the platform C :c:func:`gmtime` " +"function. Raise :exc:`OSError` instead of :exc:`ValueError` on :c:func:" +"`gmtime` failure." +msgstr "" + +#: ../../library/datetime.rst:1061 +msgid "Use :meth:`datetime.fromtimestamp` with :const:`UTC` instead." +msgstr "" + +#: ../../library/datetime.rst:1066 +msgid "" +"Return the :class:`.datetime` corresponding to the proleptic Gregorian " +"ordinal, where January 1 of year 1 has ordinal 1. :exc:`ValueError` is " +"raised unless ``1 <= ordinal <= datetime.max.toordinal()``. The hour, " +"minute, second and microsecond of the result are all 0, and :attr:`.tzinfo` " +"is ``None``." +msgstr "" + +#: ../../library/datetime.rst:1074 +msgid "" +"Return a new :class:`.datetime` object whose date components are equal to " +"the given :class:`date` object's, and whose time components are equal to the " +"given :class:`.time` object's. If the *tzinfo* argument is provided, its " +"value is used to set the :attr:`.tzinfo` attribute of the result, otherwise " +"the :attr:`~.time.tzinfo` attribute of the *time* argument is used. If the " +"*date* argument is a :class:`.datetime` object, its time components and :" +"attr:`.tzinfo` attributes are ignored." +msgstr "" + +#: ../../library/datetime.rst:1082 +msgid "" +"For any :class:`.datetime` object ``d``, ``d == datetime.combine(d.date(), d." +"time(), d.tzinfo)``." +msgstr "" + +#: ../../library/datetime.rst:1085 +msgid "Added the *tzinfo* argument." +msgstr "新增 *tzinfo* 引數。" + +#: ../../library/datetime.rst:1091 +msgid "" +"Return a :class:`.datetime` corresponding to a *date_string* in any valid " +"ISO 8601 format, with the following exceptions:" +msgstr "" + +#: ../../library/datetime.rst:1094 ../../library/datetime.rst:1904 +msgid "Time zone offsets may have fractional seconds." +msgstr "" + +#: ../../library/datetime.rst:1095 +msgid "The ``T`` separator may be replaced by any single unicode character." +msgstr "" + +#: ../../library/datetime.rst:1096 ../../library/datetime.rst:1909 +msgid "Fractional hours and minutes are not supported." +msgstr "" + +#: ../../library/datetime.rst:1105 +msgid "" +">>> from datetime import datetime\n" +">>> datetime.fromisoformat('2011-11-04')\n" +"datetime.datetime(2011, 11, 4, 0, 0)\n" +">>> datetime.fromisoformat('20111104')\n" +"datetime.datetime(2011, 11, 4, 0, 0)\n" +">>> datetime.fromisoformat('2011-11-04T00:05:23')\n" +"datetime.datetime(2011, 11, 4, 0, 5, 23)\n" +">>> datetime.fromisoformat('2011-11-04T00:05:23Z')\n" +"datetime.datetime(2011, 11, 4, 0, 5, 23, tzinfo=datetime.timezone.utc)\n" +">>> datetime.fromisoformat('20111104T000523')\n" +"datetime.datetime(2011, 11, 4, 0, 5, 23)\n" +">>> datetime.fromisoformat('2011-W01-2T00:05:23.283')\n" +"datetime.datetime(2011, 1, 4, 0, 5, 23, 283000)\n" +">>> datetime.fromisoformat('2011-11-04 00:05:23.283')\n" +"datetime.datetime(2011, 11, 4, 0, 5, 23, 283000)\n" +">>> datetime.fromisoformat('2011-11-04 00:05:23.283+00:00')\n" +"datetime.datetime(2011, 11, 4, 0, 5, 23, 283000, tzinfo=datetime.timezone." +"utc)\n" +">>> datetime.fromisoformat('2011-11-04T00:05:23+04:00')\n" +"datetime.datetime(2011, 11, 4, 0, 5, 23,\n" +" tzinfo=datetime.timezone(datetime.timedelta(seconds=14400)))" +msgstr "" +">>> from datetime import datetime\n" +">>> datetime.fromisoformat('2011-11-04')\n" +"datetime.datetime(2011, 11, 4, 0, 0)\n" +">>> datetime.fromisoformat('20111104')\n" +"datetime.datetime(2011, 11, 4, 0, 0)\n" +">>> datetime.fromisoformat('2011-11-04T00:05:23')\n" +"datetime.datetime(2011, 11, 4, 0, 5, 23)\n" +">>> datetime.fromisoformat('2011-11-04T00:05:23Z')\n" +"datetime.datetime(2011, 11, 4, 0, 5, 23, tzinfo=datetime.timezone.utc)\n" +">>> datetime.fromisoformat('20111104T000523')\n" +"datetime.datetime(2011, 11, 4, 0, 5, 23)\n" +">>> datetime.fromisoformat('2011-W01-2T00:05:23.283')\n" +"datetime.datetime(2011, 1, 4, 0, 5, 23, 283000)\n" +">>> datetime.fromisoformat('2011-11-04 00:05:23.283')\n" +"datetime.datetime(2011, 11, 4, 0, 5, 23, 283000)\n" +">>> datetime.fromisoformat('2011-11-04 00:05:23.283+00:00')\n" +"datetime.datetime(2011, 11, 4, 0, 5, 23, 283000, tzinfo=datetime.timezone." +"utc)\n" +">>> datetime.fromisoformat('2011-11-04T00:05:23+04:00')\n" +"datetime.datetime(2011, 11, 4, 0, 5, 23,\n" +" tzinfo=datetime.timezone(datetime.timedelta(seconds=14400)))" + +#: ../../library/datetime.rst:1127 +msgid "" +"Previously, this method only supported formats that could be emitted by :" +"meth:`date.isoformat` or :meth:`datetime.isoformat`." +msgstr "" + +#: ../../library/datetime.rst:1134 +msgid "" +"Return a :class:`.datetime` corresponding to the ISO calendar date specified " +"by year, week and day. The non-date components of the datetime are populated " +"with their normal default values. This is the inverse of the function :meth:" +"`datetime.isocalendar`." +msgstr "" + +#: ../../library/datetime.rst:1143 +msgid "" +"Return a :class:`.datetime` corresponding to *date_string*, parsed according " +"to *format*." +msgstr "" + +#: ../../library/datetime.rst:1146 +msgid "" +"If *format* does not contain microseconds or time zone information, this is " +"equivalent to::" +msgstr "" + +#: ../../library/datetime.rst:1148 ../../library/datetime.rst:2676 +msgid "datetime(*(time.strptime(date_string, format)[0:6]))" +msgstr "datetime(*(time.strptime(date_string, format)[0:6]))" + +#: ../../library/datetime.rst:1150 +msgid "" +":exc:`ValueError` is raised if the date_string and format can't be parsed " +"by :func:`time.strptime` or if it returns a value which isn't a time tuple. " +"See also :ref:`strftime-strptime-behavior` and :meth:`datetime." +"fromisoformat`." +msgstr "" + +#: ../../library/datetime.rst:1157 +msgid "" +"If *format* specifies a day of month without a year a :exc:" +"`DeprecationWarning` is now emitted. This is to avoid a quadrennial leap " +"year bug in code seeking to parse only a month and day as the default year " +"used in absence of one in the format is not a leap year. Such *format* " +"values may raise an error as of Python 3.15. The workaround is to always " +"include a year in your *format*. If parsing *date_string* values that do " +"not have a year, explicitly add a year that is a leap year before parsing:" +msgstr "" + +#: ../../library/datetime.rst:1166 +msgid "" +">>> from datetime import datetime\n" +">>> date_string = \"02/29\"\n" +">>> when = datetime.strptime(f\"{date_string};1984\", \"%m/%d;%Y\") # " +"Avoids leap year bug.\n" +">>> when.strftime(\"%B %d\")\n" +"'February 29'" +msgstr "" +">>> from datetime import datetime\n" +">>> date_string = \"02/29\"\n" +">>> when = datetime.strptime(f\"{date_string};1984\", \"%m/%d;%Y\") # 避免閏" +"年錯誤。\n" +">>> when.strftime(\"%B %d\")\n" +"'February 29'" + +#: ../../library/datetime.rst:1179 +msgid "" +"The earliest representable :class:`.datetime`, ``datetime(MINYEAR, 1, 1, " +"tzinfo=None)``." +msgstr "" + +#: ../../library/datetime.rst:1185 +msgid "" +"The latest representable :class:`.datetime`, ``datetime(MAXYEAR, 12, 31, 23, " +"59, 59, 999999, tzinfo=None)``." +msgstr "" + +#: ../../library/datetime.rst:1191 +msgid "" +"The smallest possible difference between non-equal :class:`.datetime` " +"objects, ``timedelta(microseconds=1)``." +msgstr "" + +#: ../../library/datetime.rst:1214 ../../library/datetime.rst:1837 +msgid "In ``range(24)``." +msgstr "" + +#: ../../library/datetime.rst:1219 ../../library/datetime.rst:1224 +#: ../../library/datetime.rst:1842 ../../library/datetime.rst:1847 +msgid "In ``range(60)``." +msgstr "" + +#: ../../library/datetime.rst:1229 ../../library/datetime.rst:1852 +msgid "In ``range(1000000)``." +msgstr "" + +#: ../../library/datetime.rst:1234 +msgid "" +"The object passed as the *tzinfo* argument to the :class:`.datetime` " +"constructor, or ``None`` if none was passed." +msgstr "" + +#: ../../library/datetime.rst:1240 ../../library/datetime.rst:1863 +msgid "" +"In ``[0, 1]``. Used to disambiguate wall times during a repeated interval. " +"(A repeated interval occurs when clocks are rolled back at the end of " +"daylight saving time or when the UTC offset for the current zone is " +"decreased for political reasons.) The values 0 and 1 represent, " +"respectively, the earlier and later of the two moments with the same wall " +"time representation." +msgstr "" + +#: ../../library/datetime.rst:1253 +msgid "``datetime2 = datetime1 + timedelta``" +msgstr "``datetime2 = datetime1 + timedelta``" + +#: ../../library/datetime.rst:1253 ../../library/datetime.rst:2490 +#: ../../library/datetime.rst:2495 ../../library/datetime.rst:2507 +#: ../../library/datetime.rst:2512 ../../library/datetime.rst:2572 +#: ../../library/datetime.rst:2577 ../../library/datetime.rst:2581 +msgid "\\(1)" +msgstr "\\(1)" + +#: ../../library/datetime.rst:1255 +msgid "``datetime2 = datetime1 - timedelta``" +msgstr "``datetime2 = datetime1 - timedelta``" + +#: ../../library/datetime.rst:1255 ../../library/datetime.rst:2523 +msgid "\\(2)" +msgstr "\\(2)" + +#: ../../library/datetime.rst:1257 +msgid "``timedelta = datetime1 - datetime2``" +msgstr "``timedelta = datetime1 - datetime2``" + +#: ../../library/datetime.rst:1259 +msgid "``datetime1 == datetime2``" +msgstr "``datetime1 == datetime2``" + +#: ../../library/datetime.rst:1260 +msgid "``datetime1 != datetime2``" +msgstr "``datetime1 != datetime2``" + +#: ../../library/datetime.rst:1262 +msgid "``datetime1 < datetime2``" +msgstr "``datetime1 < datetime2``" + +#: ../../library/datetime.rst:1263 +msgid "``datetime1 > datetime2``" +msgstr "``datetime1 > datetime2``" + +#: ../../library/datetime.rst:1264 +msgid "``datetime1 <= datetime2``" +msgstr "``datetime1 <= datetime2``" + +#: ../../library/datetime.rst:1265 +msgid "``datetime1 >= datetime2``" +msgstr "``datetime1 >= datetime2``" + +#: ../../library/datetime.rst:1269 +msgid "" +"``datetime2`` is a duration of ``timedelta`` removed from ``datetime1``, " +"moving forward in time if ``timedelta.days > 0``, or backward if ``timedelta." +"days < 0``. The result has the same :attr:`~.datetime.tzinfo` attribute as " +"the input datetime, and ``datetime2 - datetime1 == timedelta`` after. :exc:" +"`OverflowError` is raised if ``datetime2.year`` would be smaller than :const:" +"`MINYEAR` or larger than :const:`MAXYEAR`. Note that no time zone " +"adjustments are done even if the input is an aware object." +msgstr "" + +#: ../../library/datetime.rst:1278 +msgid "" +"Computes the ``datetime2`` such that ``datetime2 + timedelta == datetime1``. " +"As for addition, the result has the same :attr:`~.datetime.tzinfo` attribute " +"as the input datetime, and no time zone adjustments are done even if the " +"input is aware." +msgstr "" + +#: ../../library/datetime.rst:1283 +msgid "" +"Subtraction of a :class:`.datetime` from a :class:`.datetime` is defined " +"only if both operands are naive, or if both are aware. If one is aware and " +"the other is naive, :exc:`TypeError` is raised." +msgstr "" + +#: ../../library/datetime.rst:1287 +msgid "" +"If both are naive, or both are aware and have the same :attr:`~.datetime." +"tzinfo` attribute, the :attr:`~.datetime.tzinfo` attributes are ignored, and " +"the result is a :class:`timedelta` object ``t`` such that ``datetime2 + t == " +"datetime1``. No time zone adjustments are done in this case." +msgstr "" + +#: ../../library/datetime.rst:1292 +msgid "" +"If both are aware and have different :attr:`~.datetime.tzinfo` attributes, " +"``a-b`` acts as if ``a`` and ``b`` were first converted to naive UTC " +"datetimes. The result is ``(a.replace(tzinfo=None) - a.utcoffset()) - (b." +"replace(tzinfo=None) - b.utcoffset())`` except that the implementation never " +"overflows." +msgstr "" + +#: ../../library/datetime.rst:1298 +msgid "" +":class:`.datetime` objects are equal if they represent the same date and " +"time, taking into account the time zone." +msgstr "" + +#: ../../library/datetime.rst:1301 +msgid "Naive and aware :class:`!datetime` objects are never equal." +msgstr "" + +#: ../../library/datetime.rst:1303 +msgid "" +"If both comparands are aware, and have the same :attr:`!tzinfo` attribute, " +"the :attr:`!tzinfo` and :attr:`~.datetime.fold` attributes are ignored and " +"the base datetimes are compared. If both comparands are aware and have " +"different :attr:`~.datetime.tzinfo` attributes, the comparison acts as " +"comparands were first converted to UTC datetimes except that the " +"implementation never overflows. :class:`!datetime` instances in a repeated " +"interval are never equal to :class:`!datetime` instances in other time zone." +msgstr "" + +#: ../../library/datetime.rst:1313 +msgid "" +"*datetime1* is considered less than *datetime2* when *datetime1* precedes " +"*datetime2* in time, taking into account the time zone." +msgstr "" + +#: ../../library/datetime.rst:1316 +msgid "" +"Order comparison between naive and aware :class:`.datetime` objects raises :" +"exc:`TypeError`." +msgstr "" + +#: ../../library/datetime.rst:1319 +msgid "" +"If both comparands are aware, and have the same :attr:`!tzinfo` attribute, " +"the :attr:`!tzinfo` and :attr:`~.datetime.fold` attributes are ignored and " +"the base datetimes are compared. If both comparands are aware and have " +"different :attr:`~.datetime.tzinfo` attributes, the comparison acts as " +"comparands were first converted to UTC datetimes except that the " +"implementation never overflows." +msgstr "" + +#: ../../library/datetime.rst:1326 +msgid "" +"Equality comparisons between aware and naive :class:`.datetime` instances " +"don't raise :exc:`TypeError`." +msgstr "" + +#: ../../library/datetime.rst:1342 +msgid "Return :class:`date` object with same year, month and day." +msgstr "" + +#: ../../library/datetime.rst:1347 +msgid "" +"Return :class:`.time` object with same hour, minute, second, microsecond and " +"fold. :attr:`.tzinfo` is ``None``. See also method :meth:`timetz`." +msgstr "" + +#: ../../library/datetime.rst:1350 ../../library/datetime.rst:1359 +msgid "The fold value is copied to the returned :class:`.time` object." +msgstr "" + +#: ../../library/datetime.rst:1356 +msgid "" +"Return :class:`.time` object with same hour, minute, second, microsecond, " +"fold, and tzinfo attributes. See also method :meth:`time`." +msgstr "" + +#: ../../library/datetime.rst:1367 +msgid "" +"Return a new :class:`datetime` object with the same attributes, but with " +"specified parameters updated. Note that ``tzinfo=None`` can be specified to " +"create a naive datetime from an aware datetime with no conversion of date " +"and time data." +msgstr "" + +#: ../../library/datetime.rst:1372 +msgid "" +":class:`.datetime` objects are also supported by generic function :func:" +"`copy.replace`." +msgstr "" + +#: ../../library/datetime.rst:1381 +msgid "" +"Return a :class:`.datetime` object with new :attr:`.tzinfo` attribute *tz*, " +"adjusting the date and time data so the result is the same UTC time as " +"*self*, but in *tz*'s local time." +msgstr "" + +#: ../../library/datetime.rst:1385 +msgid "" +"If provided, *tz* must be an instance of a :class:`tzinfo` subclass, and " +"its :meth:`utcoffset` and :meth:`dst` methods must not return ``None``. If " +"*self* is naive, it is presumed to represent time in the system time zone." +msgstr "" + +#: ../../library/datetime.rst:1389 +msgid "" +"If called without arguments (or with ``tz=None``) the system local time zone " +"is assumed for the target time zone. The ``.tzinfo`` attribute of the " +"converted datetime instance will be set to an instance of :class:`timezone` " +"with the zone name and offset obtained from the OS." +msgstr "" + +#: ../../library/datetime.rst:1394 +msgid "" +"If ``self.tzinfo`` is *tz*, ``self.astimezone(tz)`` is equal to *self*: no " +"adjustment of date or time data is performed. Else the result is local time " +"in the time zone *tz*, representing the same UTC time as *self*: after " +"``astz = dt.astimezone(tz)``, ``astz - astz.utcoffset()`` will have the same " +"date and time data as ``dt - dt.utcoffset()``." +msgstr "" + +#: ../../library/datetime.rst:1400 +msgid "" +"If you merely want to attach a :class:`timezone` object *tz* to a datetime " +"*dt* without adjustment of date and time data, use ``dt." +"replace(tzinfo=tz)``. If you merely want to remove the :class:`!timezone` " +"object from an aware datetime *dt* without conversion of date and time data, " +"use ``dt.replace(tzinfo=None)``." +msgstr "" + +#: ../../library/datetime.rst:1405 +msgid "" +"Note that the default :meth:`tzinfo.fromutc` method can be overridden in a :" +"class:`tzinfo` subclass to affect the result returned by :meth:`astimezone`. " +"Ignoring error cases, :meth:`astimezone` acts like::" +msgstr "" + +#: ../../library/datetime.rst:1409 +msgid "" +"def astimezone(self, tz):\n" +" if self.tzinfo is tz:\n" +" return self\n" +" # Convert self to UTC, and attach the new timezone object.\n" +" utc = (self - self.utcoffset()).replace(tzinfo=tz)\n" +" # Convert from UTC to tz's local time.\n" +" return tz.fromutc(utc)" +msgstr "" + +#: ../../library/datetime.rst:1417 +msgid "*tz* now can be omitted." +msgstr "" + +#: ../../library/datetime.rst:1420 +msgid "" +"The :meth:`astimezone` method can now be called on naive instances that are " +"presumed to represent system local time." +msgstr "" + +#: ../../library/datetime.rst:1427 +msgid "" +"If :attr:`.tzinfo` is ``None``, returns ``None``, else returns ``self.tzinfo." +"utcoffset(self)``, and raises an exception if the latter doesn't return " +"``None`` or a :class:`timedelta` object with magnitude less than one day." +msgstr "" + +#: ../../library/datetime.rst:1431 ../../library/datetime.rst:2042 +#: ../../library/datetime.rst:2149 ../../library/datetime.rst:2394 +#: ../../library/datetime.rst:2406 ../../library/datetime.rst:2749 +msgid "The UTC offset is not restricted to a whole number of minutes." +msgstr "" + +#: ../../library/datetime.rst:1437 +msgid "" +"If :attr:`.tzinfo` is ``None``, returns ``None``, else returns ``self.tzinfo." +"dst(self)``, and raises an exception if the latter doesn't return ``None`` " +"or a :class:`timedelta` object with magnitude less than one day." +msgstr "" + +#: ../../library/datetime.rst:1441 ../../library/datetime.rst:2052 +#: ../../library/datetime.rst:2203 +msgid "The DST offset is not restricted to a whole number of minutes." +msgstr "" + +#: ../../library/datetime.rst:1447 +msgid "" +"If :attr:`.tzinfo` is ``None``, returns ``None``, else returns ``self.tzinfo." +"tzname(self)``, raises an exception if the latter doesn't return ``None`` or " +"a string object," +msgstr "" + +#: ../../library/datetime.rst:1458 +msgid "" +"time.struct_time((d.year, d.month, d.day,\n" +" d.hour, d.minute, d.second,\n" +" d.weekday(), yday, dst))" +msgstr "" +"time.struct_time((d.year, d.month, d.day,\n" +" d.hour, d.minute, d.second,\n" +" d.weekday(), yday, dst))" + +#: ../../library/datetime.rst:1462 +msgid "" +"where ``yday = d.toordinal() - date(d.year, 1, 1).toordinal() + 1`` is the " +"day number within the current year starting with 1 for January 1st. The :" +"attr:`~time.struct_time.tm_isdst` flag of the result is set according to " +"the :meth:`dst` method: :attr:`.tzinfo` is ``None`` or :meth:`dst` returns " +"``None``, :attr:`!tm_isdst` is set to ``-1``; else if :meth:`dst` returns a " +"non-zero value, :attr:`!tm_isdst` is set to 1; else :attr:`!tm_isdst` is set " +"to 0." +msgstr "" + +#: ../../library/datetime.rst:1473 +msgid "" +"If :class:`.datetime` instance ``d`` is naive, this is the same as ``d." +"timetuple()`` except that :attr:`~.time.struct_time.tm_isdst` is forced to 0 " +"regardless of what ``d.dst()`` returns. DST is never in effect for a UTC " +"time." +msgstr "" + +#: ../../library/datetime.rst:1477 +msgid "" +"If ``d`` is aware, ``d`` is normalized to UTC time, by subtracting ``d." +"utcoffset()``, and a :class:`time.struct_time` for the normalized time is " +"returned. :attr:`!tm_isdst` is forced to 0. Note that an :exc:" +"`OverflowError` may be raised if ``d.year`` was ``MINYEAR`` or ``MAXYEAR`` " +"and UTC adjustment spills over a year boundary." +msgstr "" + +#: ../../library/datetime.rst:1486 +msgid "" +"Because naive ``datetime`` objects are treated by many ``datetime`` methods " +"as local times, it is preferred to use aware datetimes to represent times in " +"UTC; as a result, using :meth:`datetime.utctimetuple` may give misleading " +"results. If you have a naive ``datetime`` representing UTC, use ``datetime." +"replace(tzinfo=timezone.utc)`` to make it aware, at which point you can use :" +"meth:`.datetime.timetuple`." +msgstr "" + +#: ../../library/datetime.rst:1495 +msgid "" +"Return the proleptic Gregorian ordinal of the date. The same as ``self." +"date().toordinal()``." +msgstr "" + +#: ../../library/datetime.rst:1500 +msgid "" +"Return POSIX timestamp corresponding to the :class:`.datetime` instance. The " +"return value is a :class:`float` similar to that returned by :func:`time." +"time`." +msgstr "" + +#: ../../library/datetime.rst:1504 +msgid "" +"Naive :class:`.datetime` instances are assumed to represent local time and " +"this method relies on the platform C :c:func:`mktime` function to perform " +"the conversion. Since :class:`.datetime` supports wider range of values " +"than :c:func:`mktime` on many platforms, this method may raise :exc:" +"`OverflowError` or :exc:`OSError` for times far in the past or far in the " +"future." +msgstr "" + +#: ../../library/datetime.rst:1511 +msgid "" +"For aware :class:`.datetime` instances, the return value is computed as::" +msgstr "" + +#: ../../library/datetime.rst:1514 +msgid "(dt - datetime(1970, 1, 1, tzinfo=timezone.utc)).total_seconds()" +msgstr "(dt - datetime(1970, 1, 1, tzinfo=timezone.utc)).total_seconds()" + +#: ../../library/datetime.rst:1518 +msgid "" +"The :meth:`timestamp` method uses the :attr:`.fold` attribute to " +"disambiguate the times during a repeated interval." +msgstr "" + +#: ../../library/datetime.rst:1524 +msgid "" +"There is no method to obtain the POSIX timestamp directly from a naive :" +"class:`.datetime` instance representing UTC time. If your application uses " +"this convention and your system time zone is not set to UTC, you can obtain " +"the POSIX timestamp by supplying ``tzinfo=timezone.utc``::" +msgstr "" + +#: ../../library/datetime.rst:1530 +msgid "timestamp = dt.replace(tzinfo=timezone.utc).timestamp()" +msgstr "timestamp = dt.replace(tzinfo=timezone.utc).timestamp()" + +#: ../../library/datetime.rst:1532 +msgid "or by calculating the timestamp directly::" +msgstr "" + +#: ../../library/datetime.rst:1534 +msgid "timestamp = (dt - datetime(1970, 1, 1)) / timedelta(seconds=1)" +msgstr "timestamp = (dt - datetime(1970, 1, 1)) / timedelta(seconds=1)" + +#: ../../library/datetime.rst:1538 +msgid "" +"Return the day of the week as an integer, where Monday is 0 and Sunday is 6. " +"The same as ``self.date().weekday()``. See also :meth:`isoweekday`." +msgstr "" + +#: ../../library/datetime.rst:1544 +msgid "" +"Return the day of the week as an integer, where Monday is 1 and Sunday is 7. " +"The same as ``self.date().isoweekday()``. See also :meth:`weekday`, :meth:" +"`isocalendar`." +msgstr "" + +#: ../../library/datetime.rst:1551 +msgid "" +"Return a :term:`named tuple` with three components: ``year``, ``week`` and " +"``weekday``. The same as ``self.date().isocalendar()``." +msgstr "" + +#: ../../library/datetime.rst:1557 +msgid "Return a string representing the date and time in ISO 8601 format:" +msgstr "" + +#: ../../library/datetime.rst:1559 +msgid "``YYYY-MM-DDTHH:MM:SS.ffffff``, if :attr:`microsecond` is not 0" +msgstr "``YYYY-MM-DDTHH:MM:SS.ffffff``，如果 :attr:`microsecond` 不是 0" + +#: ../../library/datetime.rst:1560 +msgid "``YYYY-MM-DDTHH:MM:SS``, if :attr:`microsecond` is 0" +msgstr "``YYYY-MM-DDTHH:MM:SS``，如果 :attr:`microsecond` 是 0" + +#: ../../library/datetime.rst:1562 +msgid "" +"If :meth:`utcoffset` does not return ``None``, a string is appended, giving " +"the UTC offset:" +msgstr "" +"如果 :meth:`utcoffset` 没有回傳 ``None``，則會附加一个字串，給出 UTC 偏移：" + +#: ../../library/datetime.rst:1565 +msgid "" +"``YYYY-MM-DDTHH:MM:SS.ffffff+HH:MM[:SS[.ffffff]]``, if :attr:`microsecond` " +"is not 0" +msgstr "" +"``YYYY-MM-DDTHH:MM:SS.ffffff+HH:MM[:SS[.ffffff]]``，如果 :attr:`microsecond` " +"不是 0" + +#: ../../library/datetime.rst:1567 +msgid "" +"``YYYY-MM-DDTHH:MM:SS+HH:MM[:SS[.ffffff]]``, if :attr:`microsecond` is 0" +msgstr "" +"``YYYY-MM-DDTHH:MM:SS+HH:MM[:SS[.ffffff]]``，如果 :attr:`microsecond` 是 0" + +#: ../../library/datetime.rst:1571 +msgid "" +">>> from datetime import datetime, timezone\n" +">>> datetime(2019, 5, 18, 15, 17, 8, 132263).isoformat()\n" +"'2019-05-18T15:17:08.132263'\n" +">>> datetime(2019, 5, 18, 15, 17, tzinfo=timezone.utc).isoformat()\n" +"'2019-05-18T15:17:00+00:00'" +msgstr "" +">>> from datetime import datetime, timezone\n" +">>> datetime(2019, 5, 18, 15, 17, 8, 132263).isoformat()\n" +"'2019-05-18T15:17:08.132263'\n" +">>> datetime(2019, 5, 18, 15, 17, tzinfo=timezone.utc).isoformat()\n" +"'2019-05-18T15:17:00+00:00'" + +#: ../../library/datetime.rst:1577 +msgid "" +"The optional argument *sep* (default ``'T'``) is a one-character separator, " +"placed between the date and time portions of the result. For example::" +msgstr "" + +#: ../../library/datetime.rst:1580 +msgid "" +">>> from datetime import tzinfo, timedelta, datetime\n" +">>> class TZ(tzinfo):\n" +"... \"\"\"A time zone with an arbitrary, constant -06:39 offset.\"\"\"\n" +"... def utcoffset(self, dt):\n" +"... return timedelta(hours=-6, minutes=-39)\n" +"...\n" +">>> datetime(2002, 12, 25, tzinfo=TZ()).isoformat(' ')\n" +"'2002-12-25 00:00:00-06:39'\n" +">>> datetime(2009, 11, 27, microsecond=100, tzinfo=TZ()).isoformat()\n" +"'2009-11-27T00:00:00.000100-06:39'" +msgstr "" +">>> from datetime import tzinfo, timedelta, datetime\n" +">>> class TZ(tzinfo):\n" +"... \"\"\"A time zone with an arbitrary, constant -06:39 offset.\"\"\"\n" +"... def utcoffset(self, dt):\n" +"... return timedelta(hours=-6, minutes=-39)\n" +"...\n" +">>> datetime(2002, 12, 25, tzinfo=TZ()).isoformat(' ')\n" +"'2002-12-25 00:00:00-06:39'\n" +">>> datetime(2009, 11, 27, microsecond=100, tzinfo=TZ()).isoformat()\n" +"'2009-11-27T00:00:00.000100-06:39'" + +#: ../../library/datetime.rst:1591 ../../library/datetime.rst:1982 +msgid "" +"The optional argument *timespec* specifies the number of additional " +"components of the time to include (the default is ``'auto'``). It can be one " +"of the following:" +msgstr "" + +#: ../../library/datetime.rst:1595 ../../library/datetime.rst:1986 +msgid "" +"``'auto'``: Same as ``'seconds'`` if :attr:`microsecond` is 0, same as " +"``'microseconds'`` otherwise." +msgstr "" + +#: ../../library/datetime.rst:1597 ../../library/datetime.rst:1988 +msgid "``'hours'``: Include the :attr:`hour` in the two-digit ``HH`` format." +msgstr "" + +#: ../../library/datetime.rst:1598 ../../library/datetime.rst:1989 +msgid "" +"``'minutes'``: Include :attr:`hour` and :attr:`minute` in ``HH:MM`` format." +msgstr "" + +#: ../../library/datetime.rst:1599 ../../library/datetime.rst:1990 +msgid "" +"``'seconds'``: Include :attr:`hour`, :attr:`minute`, and :attr:`second` in " +"``HH:MM:SS`` format." +msgstr "" + +#: ../../library/datetime.rst:1601 ../../library/datetime.rst:1992 +msgid "" +"``'milliseconds'``: Include full time, but truncate fractional second part " +"to milliseconds. ``HH:MM:SS.sss`` format." +msgstr "" + +#: ../../library/datetime.rst:1603 ../../library/datetime.rst:1994 +msgid "``'microseconds'``: Include full time in ``HH:MM:SS.ffffff`` format." +msgstr "" + +#: ../../library/datetime.rst:1607 ../../library/datetime.rst:1998 +msgid "Excluded time components are truncated, not rounded." +msgstr "" + +#: ../../library/datetime.rst:1609 +msgid ":exc:`ValueError` will be raised on an invalid *timespec* argument::" +msgstr "" + +#: ../../library/datetime.rst:1612 +msgid "" +">>> from datetime import datetime\n" +">>> datetime.now().isoformat(timespec='minutes')\n" +"'2002-12-25T00:00'\n" +">>> dt = datetime(2015, 1, 1, 12, 30, 59, 0)\n" +">>> dt.isoformat(timespec='microseconds')\n" +"'2015-01-01T12:30:59.000000'" +msgstr "" +">>> from datetime import datetime\n" +">>> datetime.now().isoformat(timespec='minutes')\n" +"'2002-12-25T00:00'\n" +">>> dt = datetime(2015, 1, 1, 12, 30, 59, 0)\n" +">>> dt.isoformat(timespec='microseconds')\n" +"'2015-01-01T12:30:59.000000'" + +#: ../../library/datetime.rst:1619 ../../library/datetime.rst:2013 +msgid "Added the *timespec* parameter." +msgstr "新增 *timespec* 參數。" + +#: ../../library/datetime.rst:1625 +msgid "" +"For a :class:`.datetime` instance ``d``, ``str(d)`` is equivalent to ``d." +"isoformat(' ')``." +msgstr "" + +#: ../../library/datetime.rst:1631 +msgid "Return a string representing the date and time::" +msgstr "" + +#: ../../library/datetime.rst:1633 +msgid "" +">>> from datetime import datetime\n" +">>> datetime(2002, 12, 4, 20, 30, 40).ctime()\n" +"'Wed Dec 4 20:30:40 2002'" +msgstr "" +">>> from datetime import datetime\n" +">>> datetime(2002, 12, 4, 20, 30, 40).ctime()\n" +"'Wed Dec 4 20:30:40 2002'" + +#: ../../library/datetime.rst:1637 +msgid "" +"The output string will *not* include time zone information, regardless of " +"whether the input is aware or naive." +msgstr "" + +#: ../../library/datetime.rst:1644 +msgid "" +"on platforms where the native C :c:func:`ctime` function (which :func:`time." +"ctime` invokes, but which :meth:`datetime.ctime` does not invoke) conforms " +"to the C standard." +msgstr "" + +#: ../../library/datetime.rst:1651 +msgid "" +"Return a string representing the date and time, controlled by an explicit " +"format string. See also :ref:`strftime-strptime-behavior` and :meth:" +"`datetime.isoformat`." +msgstr "" + +#: ../../library/datetime.rst:1658 +msgid "" +"Same as :meth:`.datetime.strftime`. This makes it possible to specify a " +"format string for a :class:`.datetime` object in :ref:`formatted string " +"literals ` and when using :meth:`str.format`. See also :ref:" +"`strftime-strptime-behavior` and :meth:`datetime.isoformat`." +msgstr "" + +#: ../../library/datetime.rst:1665 +msgid "Examples of Usage: :class:`.datetime`" +msgstr "用法範例：:class:`.datetime`" + +#: ../../library/datetime.rst:1667 +msgid "Examples of working with :class:`.datetime` objects:" +msgstr "更多 :class:`.datetime` 的用法範例：" + +#: ../../library/datetime.rst:1669 +msgid "" +">>> from datetime import datetime, date, time, timezone\n" +"\n" +">>> # Using datetime.combine()\n" +">>> d = date(2005, 7, 14)\n" +">>> t = time(12, 30)\n" +">>> datetime.combine(d, t)\n" +"datetime.datetime(2005, 7, 14, 12, 30)\n" +"\n" +">>> # Using datetime.now()\n" +">>> datetime.now()\n" +"datetime.datetime(2007, 12, 6, 16, 29, 43, 79043) # GMT +1\n" +">>> datetime.now(timezone.utc)\n" +"datetime.datetime(2007, 12, 6, 15, 29, 43, 79060, tzinfo=datetime.timezone." +"utc)\n" +"\n" +">>> # Using datetime.strptime()\n" +">>> dt = datetime.strptime(\"21/11/06 16:30\", \"%d/%m/%y %H:%M\")\n" +">>> dt\n" +"datetime.datetime(2006, 11, 21, 16, 30)\n" +"\n" +">>> # Using datetime.timetuple() to get tuple of all attributes\n" +">>> tt = dt.timetuple()\n" +">>> for it in tt:\n" +"... print(it)\n" +"...\n" +"2006 # year\n" +"11 # month\n" +"21 # day\n" +"16 # hour\n" +"30 # minute\n" +"0 # second\n" +"1 # weekday (0 = Monday)\n" +"325 # number of days since 1st January\n" +"-1 # dst - method tzinfo.dst() returned None\n" +"\n" +">>> # Date in ISO format\n" +">>> ic = dt.isocalendar()\n" +">>> for it in ic:\n" +"... print(it)\n" +"...\n" +"2006 # ISO year\n" +"47 # ISO week\n" +"2 # ISO weekday\n" +"\n" +">>> # Formatting a datetime\n" +">>> dt.strftime(\"%A, %d. %B %Y %I:%M%p\")\n" +"'Tuesday, 21. November 2006 04:30PM'\n" +">>> 'The {1} is {0:%d}, the {2} is {0:%B}, the {3} is {0:%I:%M%p}.'." +"format(dt, \"day\", \"month\", \"time\")\n" +"'The day is 21, the month is November, the time is 04:30PM.'" +msgstr "" + +#: ../../library/datetime.rst:1720 +msgid "" +"The example below defines a :class:`tzinfo` subclass capturing time zone " +"information for Kabul, Afghanistan, which used +4 UTC until 1945 and then " +"+4:30 UTC thereafter::" +msgstr "" + +#: ../../library/datetime.rst:1724 +msgid "" +"from datetime import timedelta, datetime, tzinfo, timezone\n" +"\n" +"class KabulTz(tzinfo):\n" +" # Kabul used +4 until 1945, when they moved to +4:30\n" +" UTC_MOVE_DATE = datetime(1944, 12, 31, 20, tzinfo=timezone.utc)\n" +"\n" +" def utcoffset(self, dt):\n" +" if dt.year < 1945:\n" +" return timedelta(hours=4)\n" +" elif (1945, 1, 1, 0, 0) <= dt.timetuple()[:5] < (1945, 1, 1, 0, " +"30):\n" +" # An ambiguous (\"imaginary\") half-hour range representing\n" +" # a 'fold' in time due to the shift from +4 to +4:30.\n" +" # If dt falls in the imaginary range, use fold to decide how\n" +" # to resolve. See PEP495.\n" +" return timedelta(hours=4, minutes=(30 if dt.fold else 0))\n" +" else:\n" +" return timedelta(hours=4, minutes=30)\n" +"\n" +" def fromutc(self, dt):\n" +" # Follow same validations as in datetime.tzinfo\n" +" if not isinstance(dt, datetime):\n" +" raise TypeError(\"fromutc() requires a datetime argument\")\n" +" if dt.tzinfo is not self:\n" +" raise ValueError(\"dt.tzinfo is not self\")\n" +"\n" +" # A custom implementation is required for fromutc as\n" +" # the input to this function is a datetime with utc values\n" +" # but with a tzinfo set to self.\n" +" # See datetime.astimezone or fromtimestamp.\n" +" if dt.replace(tzinfo=timezone.utc) >= self.UTC_MOVE_DATE:\n" +" return dt + timedelta(hours=4, minutes=30)\n" +" else:\n" +" return dt + timedelta(hours=4)\n" +"\n" +" def dst(self, dt):\n" +" # Kabul does not observe daylight saving time.\n" +" return timedelta(0)\n" +"\n" +" def tzname(self, dt):\n" +" if dt >= self.UTC_MOVE_DATE:\n" +" return \"+04:30\"\n" +" return \"+04\"" +msgstr "" + +#: ../../library/datetime.rst:1767 +msgid "Usage of ``KabulTz`` from above::" +msgstr "" + +#: ../../library/datetime.rst:1769 +msgid "" +">>> tz1 = KabulTz()\n" +"\n" +">>> # Datetime before the change\n" +">>> dt1 = datetime(1900, 11, 21, 16, 30, tzinfo=tz1)\n" +">>> print(dt1.utcoffset())\n" +"4:00:00\n" +"\n" +">>> # Datetime after the change\n" +">>> dt2 = datetime(2006, 6, 14, 13, 0, tzinfo=tz1)\n" +">>> print(dt2.utcoffset())\n" +"4:30:00\n" +"\n" +">>> # Convert datetime to another time zone\n" +">>> dt3 = dt2.astimezone(timezone.utc)\n" +">>> dt3\n" +"datetime.datetime(2006, 6, 14, 8, 30, tzinfo=datetime.timezone.utc)\n" +">>> dt2\n" +"datetime.datetime(2006, 6, 14, 13, 0, tzinfo=KabulTz())\n" +">>> dt2 == dt3\n" +"True" +msgstr "" + +#: ../../library/datetime.rst:1793 +msgid ":class:`.time` Objects" +msgstr ":class:`.time` 物件" + +#: ../../library/datetime.rst:1795 +msgid "" +"A :class:`.time` object represents a (local) time of day, independent of any " +"particular day, and subject to adjustment via a :class:`tzinfo` object." +msgstr "" + +#: ../../library/datetime.rst:1800 +msgid "" +"All arguments are optional. *tzinfo* may be ``None``, or an instance of a :" +"class:`tzinfo` subclass. The remaining arguments must be integers in the " +"following ranges:" +msgstr "" + +#: ../../library/datetime.rst:1810 +msgid "" +"If an argument outside those ranges is given, :exc:`ValueError` is raised. " +"All default to 0 except *tzinfo*, which defaults to ``None``." +msgstr "" + +#: ../../library/datetime.rst:1818 +msgid "The earliest representable :class:`.time`, ``time(0, 0, 0, 0)``." +msgstr "" + +#: ../../library/datetime.rst:1823 +msgid "The latest representable :class:`.time`, ``time(23, 59, 59, 999999)``." +msgstr "" + +#: ../../library/datetime.rst:1828 +msgid "" +"The smallest possible difference between non-equal :class:`.time` objects, " +"``timedelta(microseconds=1)``, although note that arithmetic on :class:`." +"time` objects is not supported." +msgstr "" + +#: ../../library/datetime.rst:1857 +msgid "" +"The object passed as the tzinfo argument to the :class:`.time` constructor, " +"or ``None`` if none was passed." +msgstr "" + +#: ../../library/datetime.rst:1871 +msgid "" +":class:`.time` objects support equality and order comparisons, where ``a`` " +"is considered less than ``b`` when ``a`` precedes ``b`` in time." +msgstr "" + +#: ../../library/datetime.rst:1874 +msgid "" +"Naive and aware :class:`!time` objects are never equal. Order comparison " +"between naive and aware :class:`!time` objects raises :exc:`TypeError`." +msgstr "" + +#: ../../library/datetime.rst:1878 +msgid "" +"If both comparands are aware, and have the same :attr:`~.time.tzinfo` " +"attribute, the :attr:`!tzinfo` and :attr:`!fold` attributes are ignored and " +"the base times are compared. If both comparands are aware and have " +"different :attr:`!tzinfo` attributes, the comparands are first adjusted by " +"subtracting their UTC offsets (obtained from ``self.utcoffset()``)." +msgstr "" + +#: ../../library/datetime.rst:1884 +msgid "" +"Equality comparisons between aware and naive :class:`.time` instances don't " +"raise :exc:`TypeError`." +msgstr "" + +#: ../../library/datetime.rst:1888 +msgid "" +"In Boolean contexts, a :class:`.time` object is always considered to be true." +msgstr "" + +#: ../../library/datetime.rst:1890 +msgid "" +"Before Python 3.5, a :class:`.time` object was considered to be false if it " +"represented midnight in UTC. This behavior was considered obscure and error-" +"prone and has been removed in Python 3.5. See :issue:`13936` for full " +"details." +msgstr "" + +#: ../../library/datetime.rst:1897 +msgid "Other constructors:" +msgstr "其他建構函式：" + +#: ../../library/datetime.rst:1901 +msgid "" +"Return a :class:`.time` corresponding to a *time_string* in any valid ISO " +"8601 format, with the following exceptions:" +msgstr "" + +#: ../../library/datetime.rst:1905 +msgid "" +"The leading ``T``, normally required in cases where there may be ambiguity " +"between a date and a time, is not required." +msgstr "" + +#: ../../library/datetime.rst:1907 +msgid "" +"Fractional seconds may have any number of digits (anything beyond 6 will be " +"truncated)." +msgstr "" + +#: ../../library/datetime.rst:1911 +msgid "Examples:" +msgstr "範例： ::" + +#: ../../library/datetime.rst:1913 +msgid "" +">>> from datetime import time\n" +">>> time.fromisoformat('04:23:01')\n" +"datetime.time(4, 23, 1)\n" +">>> time.fromisoformat('T04:23:01')\n" +"datetime.time(4, 23, 1)\n" +">>> time.fromisoformat('T042301')\n" +"datetime.time(4, 23, 1)\n" +">>> time.fromisoformat('04:23:01.000384')\n" +"datetime.time(4, 23, 1, 384)\n" +">>> time.fromisoformat('04:23:01,000384')\n" +"datetime.time(4, 23, 1, 384)\n" +">>> time.fromisoformat('04:23:01+04:00')\n" +"datetime.time(4, 23, 1, tzinfo=datetime.timezone(datetime." +"timedelta(seconds=14400)))\n" +">>> time.fromisoformat('04:23:01Z')\n" +"datetime.time(4, 23, 1, tzinfo=datetime.timezone.utc)\n" +">>> time.fromisoformat('04:23:01+00:00')\n" +"datetime.time(4, 23, 1, tzinfo=datetime.timezone.utc)" +msgstr "" +">>> from datetime import time\n" +">>> time.fromisoformat('04:23:01')\n" +"datetime.time(4, 23, 1)\n" +">>> time.fromisoformat('T04:23:01')\n" +"datetime.time(4, 23, 1)\n" +">>> time.fromisoformat('T042301')\n" +"datetime.time(4, 23, 1)\n" +">>> time.fromisoformat('04:23:01.000384')\n" +"datetime.time(4, 23, 1, 384)\n" +">>> time.fromisoformat('04:23:01,000384')\n" +"datetime.time(4, 23, 1, 384)\n" +">>> time.fromisoformat('04:23:01+04:00')\n" +"datetime.time(4, 23, 1, tzinfo=datetime.timezone(datetime." +"timedelta(seconds=14400)))\n" +">>> time.fromisoformat('04:23:01Z')\n" +"datetime.time(4, 23, 1, tzinfo=datetime.timezone.utc)\n" +">>> time.fromisoformat('04:23:01+00:00')\n" +"datetime.time(4, 23, 1, tzinfo=datetime.timezone.utc)" + +#: ../../library/datetime.rst:1935 +msgid "" +"Previously, this method only supported formats that could be emitted by :" +"meth:`time.isoformat`." +msgstr "" + +#: ../../library/datetime.rst:1941 +msgid "" +"Return a :class:`.time` corresponding to *date_string*, parsed according to " +"*format*." +msgstr "" + +#: ../../library/datetime.rst:1944 +msgid "" +"If *format* does not contain microseconds or timezone information, this is " +"equivalent to::" +msgstr "" + +#: ../../library/datetime.rst:1946 +msgid "time(*(time.strptime(date_string, format)[3:6]))" +msgstr "time(*(time.strptime(date_string, format)[3:6]))" + +#: ../../library/datetime.rst:1948 +msgid "" +":exc:`ValueError` is raised if the *date_string* and *format* cannot be " +"parsed by :func:`time.strptime` or if it returns a value which is not a time " +"tuple. See also :ref:`strftime-strptime-behavior` and :meth:`time." +"fromisoformat`." +msgstr "" + +#: ../../library/datetime.rst:1961 +msgid "" +"Return a new :class:`.time` with the same values, but with specified " +"parameters updated. Note that ``tzinfo=None`` can be specified to create a " +"naive :class:`.time` from an aware :class:`.time`, without conversion of the " +"time data." +msgstr "" + +#: ../../library/datetime.rst:1966 +msgid "" +":class:`.time` objects are also supported by generic function :func:`copy." +"replace`." +msgstr "" + +#: ../../library/datetime.rst:1975 +msgid "Return a string representing the time in ISO 8601 format, one of:" +msgstr "" + +#: ../../library/datetime.rst:1977 +msgid "``HH:MM:SS.ffffff``, if :attr:`microsecond` is not 0" +msgstr "" + +#: ../../library/datetime.rst:1978 +msgid "``HH:MM:SS``, if :attr:`microsecond` is 0" +msgstr "" + +#: ../../library/datetime.rst:1979 +msgid "" +"``HH:MM:SS.ffffff+HH:MM[:SS[.ffffff]]``, if :meth:`utcoffset` does not " +"return ``None``" +msgstr "" + +#: ../../library/datetime.rst:1980 +msgid "" +"``HH:MM:SS+HH:MM[:SS[.ffffff]]``, if :attr:`microsecond` is 0 and :meth:" +"`utcoffset` does not return ``None``" +msgstr "" + +#: ../../library/datetime.rst:2000 +msgid ":exc:`ValueError` will be raised on an invalid *timespec* argument." +msgstr "" + +#: ../../library/datetime.rst:2004 +msgid "" +">>> from datetime import time\n" +">>> time(hour=12, minute=34, second=56, microsecond=123456)." +"isoformat(timespec='minutes')\n" +"'12:34'\n" +">>> dt = time(hour=12, minute=34, second=56, microsecond=0)\n" +">>> dt.isoformat(timespec='microseconds')\n" +"'12:34:56.000000'\n" +">>> dt.isoformat(timespec='auto')\n" +"'12:34:56'" +msgstr "" +">>> from datetime import time\n" +">>> time(hour=12, minute=34, second=56, microsecond=123456)." +"isoformat(timespec='minutes')\n" +"'12:34'\n" +">>> dt = time(hour=12, minute=34, second=56, microsecond=0)\n" +">>> dt.isoformat(timespec='microseconds')\n" +"'12:34:56.000000'\n" +">>> dt.isoformat(timespec='auto')\n" +"'12:34:56'" + +#: ../../library/datetime.rst:2019 +msgid "For a time ``t``, ``str(t)`` is equivalent to ``t.isoformat()``." +msgstr "" + +#: ../../library/datetime.rst:2024 +msgid "" +"Return a string representing the time, controlled by an explicit format " +"string. See also :ref:`strftime-strptime-behavior` and :meth:`time." +"isoformat`." +msgstr "" + +#: ../../library/datetime.rst:2030 +msgid "" +"Same as :meth:`.time.strftime`. This makes it possible to specify a format " +"string for a :class:`.time` object in :ref:`formatted string literals ` and when using :meth:`str.format`. See also :ref:`strftime-" +"strptime-behavior` and :meth:`time.isoformat`." +msgstr "" + +#: ../../library/datetime.rst:2038 +msgid "" +"If :attr:`.tzinfo` is ``None``, returns ``None``, else returns ``self.tzinfo." +"utcoffset(None)``, and raises an exception if the latter doesn't return " +"``None`` or a :class:`timedelta` object with magnitude less than one day." +msgstr "" + +#: ../../library/datetime.rst:2048 +msgid "" +"If :attr:`.tzinfo` is ``None``, returns ``None``, else returns ``self.tzinfo." +"dst(None)``, and raises an exception if the latter doesn't return ``None``, " +"or a :class:`timedelta` object with magnitude less than one day." +msgstr "" + +#: ../../library/datetime.rst:2057 +msgid "" +"If :attr:`.tzinfo` is ``None``, returns ``None``, else returns ``self.tzinfo." +"tzname(None)``, or raises an exception if the latter doesn't return ``None`` " +"or a string object." +msgstr "" + +#: ../../library/datetime.rst:2062 +msgid "Examples of Usage: :class:`.time`" +msgstr "用法範例：:class:`.time`" + +#: ../../library/datetime.rst:2064 +msgid "Examples of working with a :class:`.time` object::" +msgstr "" + +#: ../../library/datetime.rst:2066 +msgid "" +">>> from datetime import time, tzinfo, timedelta\n" +">>> class TZ1(tzinfo):\n" +"... def utcoffset(self, dt):\n" +"... return timedelta(hours=1)\n" +"... def dst(self, dt):\n" +"... return timedelta(0)\n" +"... def tzname(self,dt):\n" +"... return \"+01:00\"\n" +"... def __repr__(self):\n" +"... return f\"{self.__class__.__name__}()\"\n" +"...\n" +">>> t = time(12, 10, 30, tzinfo=TZ1())\n" +">>> t\n" +"datetime.time(12, 10, 30, tzinfo=TZ1())\n" +">>> t.isoformat()\n" +"'12:10:30+01:00'\n" +">>> t.dst()\n" +"datetime.timedelta(0)\n" +">>> t.tzname()\n" +"'+01:00'\n" +">>> t.strftime(\"%H:%M:%S %Z\")\n" +"'12:10:30 +01:00'\n" +">>> 'The {} is {:%H:%M}.'.format(\"time\", t)\n" +"'The time is 12:10.'" +msgstr "" +">>> from datetime import time, tzinfo, timedelta\n" +">>> class TZ1(tzinfo):\n" +"... def utcoffset(self, dt):\n" +"... return timedelta(hours=1)\n" +"... def dst(self, dt):\n" +"... return timedelta(0)\n" +"... def tzname(self,dt):\n" +"... return \"+01:00\"\n" +"... def __repr__(self):\n" +"... return f\"{self.__class__.__name__}()\"\n" +"...\n" +">>> t = time(12, 10, 30, tzinfo=TZ1())\n" +">>> t\n" +"datetime.time(12, 10, 30, tzinfo=TZ1())\n" +">>> t.isoformat()\n" +"'12:10:30+01:00'\n" +">>> t.dst()\n" +"datetime.timedelta(0)\n" +">>> t.tzname()\n" +"'+01:00'\n" +">>> t.strftime(\"%H:%M:%S %Z\")\n" +"'12:10:30 +01:00'\n" +">>> 'The {} is {:%H:%M}.'.format(\"time\", t)\n" +"'The time is 12:10.'" + +#: ../../library/datetime.rst:2095 +msgid ":class:`tzinfo` Objects" +msgstr ":class:`tzinfo` 物件" + +#: ../../library/datetime.rst:2099 +msgid "" +"This is an abstract base class, meaning that this class should not be " +"instantiated directly. Define a subclass of :class:`tzinfo` to capture " +"information about a particular time zone." +msgstr "" + +#: ../../library/datetime.rst:2103 +msgid "" +"An instance of (a concrete subclass of) :class:`tzinfo` can be passed to the " +"constructors for :class:`.datetime` and :class:`.time` objects. The latter " +"objects view their attributes as being in local time, and the :class:" +"`tzinfo` object supports methods revealing offset of local time from UTC, " +"the name of the time zone, and DST offset, all relative to a date or time " +"object passed to them." +msgstr "" + +#: ../../library/datetime.rst:2109 +msgid "" +"You need to derive a concrete subclass, and (at least) supply " +"implementations of the standard :class:`tzinfo` methods needed by the :class:" +"`.datetime` methods you use. The :mod:`!datetime` module provides :class:" +"`timezone`, a simple concrete subclass of :class:`tzinfo` which can " +"represent time zones with fixed offset from UTC such as UTC itself or North " +"American EST and EDT." +msgstr "" + +#: ../../library/datetime.rst:2116 +msgid "" +"Special requirement for pickling: A :class:`tzinfo` subclass must have an :" +"meth:`~object.__init__` method that can be called with no arguments, " +"otherwise it can be pickled but possibly not unpickled again. This is a " +"technical requirement that may be relaxed in the future." +msgstr "" + +#: ../../library/datetime.rst:2122 +msgid "" +"A concrete subclass of :class:`tzinfo` may need to implement the following " +"methods. Exactly which methods are needed depends on the uses made of aware :" +"mod:`!datetime` objects. If in doubt, simply implement all of them." +msgstr "" + +#: ../../library/datetime.rst:2129 +msgid "" +"Return offset of local time from UTC, as a :class:`timedelta` object that is " +"positive east of UTC. If local time is west of UTC, this should be negative." +msgstr "" + +#: ../../library/datetime.rst:2132 +msgid "" +"This represents the *total* offset from UTC; for example, if a :class:" +"`tzinfo` object represents both time zone and DST adjustments, :meth:" +"`utcoffset` should return their sum. If the UTC offset isn't known, return " +"``None``. Else the value returned must be a :class:`timedelta` object " +"strictly between ``-timedelta(hours=24)`` and ``timedelta(hours=24)`` (the " +"magnitude of the offset must be less than one day). Most implementations of :" +"meth:`utcoffset` will probably look like one of these two::" +msgstr "" + +#: ../../library/datetime.rst:2140 +msgid "" +"return CONSTANT # fixed-offset class\n" +"return CONSTANT + self.dst(dt) # daylight-aware class" +msgstr "" + +#: ../../library/datetime.rst:2143 +msgid "" +"If :meth:`utcoffset` does not return ``None``, :meth:`dst` should not return " +"``None`` either." +msgstr "" + +#: ../../library/datetime.rst:2146 +msgid "" +"The default implementation of :meth:`utcoffset` raises :exc:" +"`NotImplementedError`." +msgstr "" + +#: ../../library/datetime.rst:2155 +msgid "" +"Return the daylight saving time (DST) adjustment, as a :class:`timedelta` " +"object or ``None`` if DST information isn't known." +msgstr "" + +#: ../../library/datetime.rst:2159 +msgid "" +"Return ``timedelta(0)`` if DST is not in effect. If DST is in effect, return " +"the offset as a :class:`timedelta` object (see :meth:`utcoffset` for " +"details). Note that DST offset, if applicable, has already been added to the " +"UTC offset returned by :meth:`utcoffset`, so there's no need to consult :" +"meth:`dst` unless you're interested in obtaining DST info separately. For " +"example, :meth:`datetime.timetuple` calls its :attr:`~.datetime.tzinfo` " +"attribute's :meth:`dst` method to determine how the :attr:`~time.struct_time." +"tm_isdst` flag should be set, and :meth:`tzinfo.fromutc` calls :meth:`dst` " +"to account for DST changes when crossing time zones." +msgstr "" + +#: ../../library/datetime.rst:2169 +msgid "" +"An instance *tz* of a :class:`tzinfo` subclass that models both standard and " +"daylight times must be consistent in this sense:" +msgstr "" + +#: ../../library/datetime.rst:2172 +msgid "``tz.utcoffset(dt) - tz.dst(dt)``" +msgstr "``tz.utcoffset(dt) - tz.dst(dt)``" + +#: ../../library/datetime.rst:2174 +msgid "" +"must return the same result for every :class:`.datetime` *dt* with ``dt." +"tzinfo == tz``. For sane :class:`tzinfo` subclasses, this expression yields " +"the time zone's \"standard offset\", which should not depend on the date or " +"the time, but only on geographic location. The implementation of :meth:" +"`datetime.astimezone` relies on this, but cannot detect violations; it's the " +"programmer's responsibility to ensure it. If a :class:`tzinfo` subclass " +"cannot guarantee this, it may be able to override the default implementation " +"of :meth:`tzinfo.fromutc` to work correctly with :meth:`~.datetime." +"astimezone` regardless." +msgstr "" + +#: ../../library/datetime.rst:2183 +msgid "" +"Most implementations of :meth:`dst` will probably look like one of these " +"two::" +msgstr "" + +#: ../../library/datetime.rst:2185 +msgid "" +"def dst(self, dt):\n" +" # a fixed-offset class: doesn't account for DST\n" +" return timedelta(0)" +msgstr "" + +#: ../../library/datetime.rst:2189 +msgid "or::" +msgstr "或是： ::" + +#: ../../library/datetime.rst:2191 +msgid "" +"def dst(self, dt):\n" +" # Code to set dston and dstoff to the time zone's DST\n" +" # transition times based on the input dt.year, and expressed\n" +" # in standard local time.\n" +"\n" +" if dston <= dt.replace(tzinfo=None) < dstoff:\n" +" return timedelta(hours=1)\n" +" else:\n" +" return timedelta(0)" +msgstr "" + +#: ../../library/datetime.rst:2201 +msgid "" +"The default implementation of :meth:`dst` raises :exc:`NotImplementedError`." +msgstr "" + +#: ../../library/datetime.rst:2209 +msgid "" +"Return the time zone name corresponding to the :class:`.datetime` object " +"*dt*, as a string. Nothing about string names is defined by the :mod:`!" +"datetime` module, and there's no requirement that it mean anything in " +"particular. For example, ``\"GMT\"``, ``\"UTC\"``, ``\"-500\"``, " +"``\"-5:00\"``, ``\"EDT\"``, ``\"US/Eastern\"``, ``\"America/New York\"`` are " +"all valid replies. Return ``None`` if a string name isn't known. Note that " +"this is a method rather than a fixed string primarily because some :class:" +"`tzinfo` subclasses will wish to return different names depending on the " +"specific value of *dt* passed, especially if the :class:`tzinfo` class is " +"accounting for daylight time." +msgstr "" + +#: ../../library/datetime.rst:2219 +msgid "" +"The default implementation of :meth:`tzname` raises :exc:" +"`NotImplementedError`." +msgstr "" + +#: ../../library/datetime.rst:2222 +msgid "" +"These methods are called by a :class:`.datetime` or :class:`.time` object, " +"in response to their methods of the same names. A :class:`.datetime` object " +"passes itself as the argument, and a :class:`.time` object passes ``None`` " +"as the argument. A :class:`tzinfo` subclass's methods should therefore be " +"prepared to accept a *dt* argument of ``None``, or of class :class:`." +"datetime`." +msgstr "" + +#: ../../library/datetime.rst:2228 +msgid "" +"When ``None`` is passed, it's up to the class designer to decide the best " +"response. For example, returning ``None`` is appropriate if the class wishes " +"to say that time objects don't participate in the :class:`tzinfo` protocols. " +"It may be more useful for ``utcoffset(None)`` to return the standard UTC " +"offset, as there is no other convention for discovering the standard offset." +msgstr "" + +#: ../../library/datetime.rst:2234 +msgid "" +"When a :class:`.datetime` object is passed in response to a :class:`." +"datetime` method, ``dt.tzinfo`` is the same object as *self*. :class:" +"`tzinfo` methods can rely on this, unless user code calls :class:`tzinfo` " +"methods directly. The intent is that the :class:`tzinfo` methods interpret " +"*dt* as being in local time, and not need worry about objects in other time " +"zones." +msgstr "" + +#: ../../library/datetime.rst:2240 +msgid "" +"There is one more :class:`tzinfo` method that a subclass may wish to " +"override:" +msgstr "" + +#: ../../library/datetime.rst:2245 +msgid "" +"This is called from the default :meth:`datetime.astimezone` implementation. " +"When called from that, ``dt.tzinfo`` is *self*, and *dt*'s date and time " +"data are to be viewed as expressing a UTC time. The purpose of :meth:" +"`fromutc` is to adjust the date and time data, returning an equivalent " +"datetime in *self*'s local time." +msgstr "" + +#: ../../library/datetime.rst:2251 +msgid "" +"Most :class:`tzinfo` subclasses should be able to inherit the default :meth:" +"`fromutc` implementation without problems. It's strong enough to handle " +"fixed-offset time zones, and time zones accounting for both standard and " +"daylight time, and the latter even if the DST transition times differ in " +"different years. An example of a time zone the default :meth:`fromutc` " +"implementation may not handle correctly in all cases is one where the " +"standard offset (from UTC) depends on the specific date and time passed, " +"which can happen for political reasons. The default implementations of :meth:" +"`~.datetime.astimezone` and :meth:`fromutc` may not produce the result you " +"want if the result is one of the hours straddling the moment the standard " +"offset changes." +msgstr "" + +#: ../../library/datetime.rst:2262 +msgid "" +"Skipping code for error cases, the default :meth:`fromutc` implementation " +"acts like::" +msgstr "" + +#: ../../library/datetime.rst:2265 +msgid "" +"def fromutc(self, dt):\n" +" # raise ValueError error if dt.tzinfo is not self\n" +" dtoff = dt.utcoffset()\n" +" dtdst = dt.dst()\n" +" # raise ValueError if dtoff is None or dtdst is None\n" +" delta = dtoff - dtdst # this is self's standard offset\n" +" if delta:\n" +" dt += delta # convert to standard local time\n" +" dtdst = dt.dst()\n" +" # raise ValueError if dtdst is None\n" +" if dtdst:\n" +" return dt + dtdst\n" +" else:\n" +" return dt" +msgstr "" + +#: ../../library/datetime.rst:2280 +msgid "" +"In the following :download:`tzinfo_examples.py <../includes/tzinfo_examples." +"py>` file there are some examples of :class:`tzinfo` classes:" +msgstr "" + +#: ../../library/datetime.rst:2284 +msgid "" +"from datetime import tzinfo, timedelta, datetime\n" +"\n" +"ZERO = timedelta(0)\n" +"HOUR = timedelta(hours=1)\n" +"SECOND = timedelta(seconds=1)\n" +"\n" +"# A class capturing the platform's idea of local time.\n" +"# (May result in wrong values on historical times in\n" +"# timezones where UTC offset and/or the DST rules had\n" +"# changed in the past.)\n" +"import time as _time\n" +"\n" +"STDOFFSET = timedelta(seconds = -_time.timezone)\n" +"if _time.daylight:\n" +" DSTOFFSET = timedelta(seconds = -_time.altzone)\n" +"else:\n" +" DSTOFFSET = STDOFFSET\n" +"\n" +"DSTDIFF = DSTOFFSET - STDOFFSET\n" +"\n" +"class LocalTimezone(tzinfo):\n" +"\n" +" def fromutc(self, dt):\n" +" assert dt.tzinfo is self\n" +" stamp = (dt - datetime(1970, 1, 1, tzinfo=self)) // SECOND\n" +" args = _time.localtime(stamp)[:6]\n" +" dst_diff = DSTDIFF // SECOND\n" +" # Detect fold\n" +" fold = (args == _time.localtime(stamp - dst_diff))\n" +" return datetime(*args, microsecond=dt.microsecond,\n" +" tzinfo=self, fold=fold)\n" +"\n" +" def utcoffset(self, dt):\n" +" if self._isdst(dt):\n" +" return DSTOFFSET\n" +" else:\n" +" return STDOFFSET\n" +"\n" +" def dst(self, dt):\n" +" if self._isdst(dt):\n" +" return DSTDIFF\n" +" else:\n" +" return ZERO\n" +"\n" +" def tzname(self, dt):\n" +" return _time.tzname[self._isdst(dt)]\n" +"\n" +" def _isdst(self, dt):\n" +" tt = (dt.year, dt.month, dt.day,\n" +" dt.hour, dt.minute, dt.second,\n" +" dt.weekday(), 0, 0)\n" +" stamp = _time.mktime(tt)\n" +" tt = _time.localtime(stamp)\n" +" return tt.tm_isdst > 0\n" +"\n" +"Local = LocalTimezone()\n" +"\n" +"\n" +"# A complete implementation of current DST rules for major US time zones.\n" +"\n" +"def first_sunday_on_or_after(dt):\n" +" days_to_go = 6 - dt.weekday()\n" +" if days_to_go:\n" +" dt += timedelta(days_to_go)\n" +" return dt\n" +"\n" +"\n" +"# US DST Rules\n" +"#\n" +"# This is a simplified (i.e., wrong for a few cases) set of rules for US\n" +"# DST start and end times. For a complete and up-to-date set of DST rules\n" +"# and timezone definitions, visit the Olson Database (or try pytz):\n" +"# http://www.twinsun.com/tz/tz-link.htm\n" +"# https://sourceforge.net/projects/pytz/ (might not be up-to-date)\n" +"#\n" +"# In the US, since 2007, DST starts at 2am (standard time) on the second\n" +"# Sunday in March, which is the first Sunday on or after Mar 8.\n" +"DSTSTART_2007 = datetime(1, 3, 8, 2)\n" +"# and ends at 2am (DST time) on the first Sunday of Nov.\n" +"DSTEND_2007 = datetime(1, 11, 1, 2)\n" +"# From 1987 to 2006, DST used to start at 2am (standard time) on the first\n" +"# Sunday in April and to end at 2am (DST time) on the last\n" +"# Sunday of October, which is the first Sunday on or after Oct 25.\n" +"DSTSTART_1987_2006 = datetime(1, 4, 1, 2)\n" +"DSTEND_1987_2006 = datetime(1, 10, 25, 2)\n" +"# From 1967 to 1986, DST used to start at 2am (standard time) on the last\n" +"# Sunday in April (the one on or after April 24) and to end at 2am (DST " +"time)\n" +"# on the last Sunday of October, which is the first Sunday\n" +"# on or after Oct 25.\n" +"DSTSTART_1967_1986 = datetime(1, 4, 24, 2)\n" +"DSTEND_1967_1986 = DSTEND_1987_2006\n" +"\n" +"def us_dst_range(year):\n" +" # Find start and end times for US DST. For years before 1967, return\n" +" # start = end for no DST.\n" +" if 2006 < year:\n" +" dststart, dstend = DSTSTART_2007, DSTEND_2007\n" +" elif 1986 < year < 2007:\n" +" dststart, dstend = DSTSTART_1987_2006, DSTEND_1987_2006\n" +" elif 1966 < year < 1987:\n" +" dststart, dstend = DSTSTART_1967_1986, DSTEND_1967_1986\n" +" else:\n" +" return (datetime(year, 1, 1), ) * 2\n" +"\n" +" start = first_sunday_on_or_after(dststart.replace(year=year))\n" +" end = first_sunday_on_or_after(dstend.replace(year=year))\n" +" return start, end\n" +"\n" +"\n" +"class USTimeZone(tzinfo):\n" +"\n" +" def __init__(self, hours, reprname, stdname, dstname):\n" +" self.stdoffset = timedelta(hours=hours)\n" +" self.reprname = reprname\n" +" self.stdname = stdname\n" +" self.dstname = dstname\n" +"\n" +" def __repr__(self):\n" +" return self.reprname\n" +"\n" +" def tzname(self, dt):\n" +" if self.dst(dt):\n" +" return self.dstname\n" +" else:\n" +" return self.stdname\n" +"\n" +" def utcoffset(self, dt):\n" +" return self.stdoffset + self.dst(dt)\n" +"\n" +" def dst(self, dt):\n" +" if dt is None or dt.tzinfo is None:\n" +" # An exception may be sensible here, in one or both cases.\n" +" # It depends on how you want to treat them. The default\n" +" # fromutc() implementation (called by the default astimezone()\n" +" # implementation) passes a datetime with dt.tzinfo is self.\n" +" return ZERO\n" +" assert dt.tzinfo is self\n" +" start, end = us_dst_range(dt.year)\n" +" # Can't compare naive to aware objects, so strip the timezone from\n" +" # dt first.\n" +" dt = dt.replace(tzinfo=None)\n" +" if start + HOUR <= dt < end - HOUR:\n" +" # DST is in effect.\n" +" return HOUR\n" +" if end - HOUR <= dt < end:\n" +" # Fold (an ambiguous hour): use dt.fold to disambiguate.\n" +" return ZERO if dt.fold else HOUR\n" +" if start <= dt < start + HOUR:\n" +" # Gap (a non-existent hour): reverse the fold rule.\n" +" return HOUR if dt.fold else ZERO\n" +" # DST is off.\n" +" return ZERO\n" +"\n" +" def fromutc(self, dt):\n" +" assert dt.tzinfo is self\n" +" start, end = us_dst_range(dt.year)\n" +" start = start.replace(tzinfo=self)\n" +" end = end.replace(tzinfo=self)\n" +" std_time = dt + self.stdoffset\n" +" dst_time = std_time + HOUR\n" +" if end <= dst_time < end + HOUR:\n" +" # Repeated hour\n" +" return std_time.replace(fold=1)\n" +" if std_time < start or dst_time >= end:\n" +" # Standard time\n" +" return std_time\n" +" if start <= std_time < end - HOUR:\n" +" # Daylight saving time\n" +" return dst_time\n" +"\n" +"\n" +"Eastern = USTimeZone(-5, \"Eastern\", \"EST\", \"EDT\")\n" +"Central = USTimeZone(-6, \"Central\", \"CST\", \"CDT\")\n" +"Mountain = USTimeZone(-7, \"Mountain\", \"MST\", \"MDT\")\n" +"Pacific = USTimeZone(-8, \"Pacific\", \"PST\", \"PDT\")\n" +msgstr "" + +#: ../../library/datetime.rst:2286 +msgid "" +"Note that there are unavoidable subtleties twice per year in a :class:" +"`tzinfo` subclass accounting for both standard and daylight time, at the DST " +"transition points. For concreteness, consider US Eastern (UTC -0500), where " +"EDT begins the minute after 1:59 (EST) on the second Sunday in March, and " +"ends the minute after 1:59 (EDT) on the first Sunday in November::" +msgstr "" + +#: ../../library/datetime.rst:2292 +msgid "" +" UTC 3:MM 4:MM 5:MM 6:MM 7:MM 8:MM\n" +" EST 22:MM 23:MM 0:MM 1:MM 2:MM 3:MM\n" +" EDT 23:MM 0:MM 1:MM 2:MM 3:MM 4:MM\n" +"\n" +"start 22:MM 23:MM 0:MM 1:MM 3:MM 4:MM\n" +"\n" +" end 23:MM 0:MM 1:MM 1:MM 2:MM 3:MM" +msgstr "" +" UTC 3:MM 4:MM 5:MM 6:MM 7:MM 8:MM\n" +" EST 22:MM 23:MM 0:MM 1:MM 2:MM 3:MM\n" +" EDT 23:MM 0:MM 1:MM 2:MM 3:MM 4:MM\n" +"\n" +"start 22:MM 23:MM 0:MM 1:MM 3:MM 4:MM\n" +"\n" +" end 23:MM 0:MM 1:MM 1:MM 2:MM 3:MM" + +#: ../../library/datetime.rst:2300 +msgid "" +"When DST starts (the \"start\" line), the local wall clock leaps from 1:59 " +"to 3:00. A wall time of the form 2:MM doesn't really make sense on that day, " +"so ``astimezone(Eastern)`` won't deliver a result with ``hour == 2`` on the " +"day DST begins. For example, at the Spring forward transition of 2016, we " +"get::" +msgstr "" + +#: ../../library/datetime.rst:2305 +msgid "" +">>> from datetime import datetime, timezone\n" +">>> from tzinfo_examples import HOUR, Eastern\n" +">>> u0 = datetime(2016, 3, 13, 5, tzinfo=timezone.utc)\n" +">>> for i in range(4):\n" +"... u = u0 + i*HOUR\n" +"... t = u.astimezone(Eastern)\n" +"... print(u.time(), 'UTC =', t.time(), t.tzname())\n" +"...\n" +"05:00:00 UTC = 00:00:00 EST\n" +"06:00:00 UTC = 01:00:00 EST\n" +"07:00:00 UTC = 03:00:00 EDT\n" +"08:00:00 UTC = 04:00:00 EDT" +msgstr "" +">>> from datetime import datetime, timezone\n" +">>> from tzinfo_examples import HOUR, Eastern\n" +">>> u0 = datetime(2016, 3, 13, 5, tzinfo=timezone.utc)\n" +">>> for i in range(4):\n" +"... u = u0 + i*HOUR\n" +"... t = u.astimezone(Eastern)\n" +"... print(u.time(), 'UTC =', t.time(), t.tzname())\n" +"...\n" +"05:00:00 UTC = 00:00:00 EST\n" +"06:00:00 UTC = 01:00:00 EST\n" +"07:00:00 UTC = 03:00:00 EDT\n" +"08:00:00 UTC = 04:00:00 EDT" + +#: ../../library/datetime.rst:2319 +msgid "" +"When DST ends (the \"end\" line), there's a potentially worse problem: " +"there's an hour that can't be spelled unambiguously in local wall time: the " +"last hour of daylight time. In Eastern, that's times of the form 5:MM UTC on " +"the day daylight time ends. The local wall clock leaps from 1:59 (daylight " +"time) back to 1:00 (standard time) again. Local times of the form 1:MM are " +"ambiguous. :meth:`~.datetime.astimezone` mimics the local clock's behavior " +"by mapping two adjacent UTC hours into the same local hour then. In the " +"Eastern example, UTC times of the form 5:MM and 6:MM both map to 1:MM when " +"converted to Eastern, but earlier times have the :attr:`~.datetime.fold` " +"attribute set to 0 and the later times have it set to 1. For example, at the " +"Fall back transition of 2016, we get::" +msgstr "" + +#: ../../library/datetime.rst:2330 +msgid "" +">>> u0 = datetime(2016, 11, 6, 4, tzinfo=timezone.utc)\n" +">>> for i in range(4):\n" +"... u = u0 + i*HOUR\n" +"... t = u.astimezone(Eastern)\n" +"... print(u.time(), 'UTC =', t.time(), t.tzname(), t.fold)\n" +"...\n" +"04:00:00 UTC = 00:00:00 EDT 0\n" +"05:00:00 UTC = 01:00:00 EDT 0\n" +"06:00:00 UTC = 01:00:00 EST 1\n" +"07:00:00 UTC = 02:00:00 EST 0" +msgstr "" +">>> u0 = datetime(2016, 11, 6, 4, tzinfo=timezone.utc)\n" +">>> for i in range(4):\n" +"... u = u0 + i*HOUR\n" +"... t = u.astimezone(Eastern)\n" +"... print(u.time(), 'UTC =', t.time(), t.tzname(), t.fold)\n" +"...\n" +"04:00:00 UTC = 00:00:00 EDT 0\n" +"05:00:00 UTC = 01:00:00 EDT 0\n" +"06:00:00 UTC = 01:00:00 EST 1\n" +"07:00:00 UTC = 02:00:00 EST 0" + +#: ../../library/datetime.rst:2341 +msgid "" +"Note that the :class:`.datetime` instances that differ only by the value of " +"the :attr:`~.datetime.fold` attribute are considered equal in comparisons." +msgstr "" + +#: ../../library/datetime.rst:2344 +msgid "" +"Applications that can't bear wall-time ambiguities should explicitly check " +"the value of the :attr:`~.datetime.fold` attribute or avoid using hybrid :" +"class:`tzinfo` subclasses; there are no ambiguities when using :class:" +"`timezone`, or any other fixed-offset :class:`tzinfo` subclass (such as a " +"class representing only EST (fixed offset -5 hours), or only EDT (fixed " +"offset -4 hours))." +msgstr "" + +#: ../../library/datetime.rst:2352 +msgid ":mod:`zoneinfo`" +msgstr ":mod:`zoneinfo`" + +#: ../../library/datetime.rst:2353 +msgid "" +"The :mod:`!datetime` module has a basic :class:`timezone` class (for " +"handling arbitrary fixed offsets from UTC) and its :attr:`timezone.utc` " +"attribute (a UTC :class:`!timezone` instance)." +msgstr "" + +#: ../../library/datetime.rst:2357 +msgid "" +"``zoneinfo`` brings the *IANA time zone database* (also known as the Olson " +"database) to Python, and its usage is recommended." +msgstr "" + +#: ../../library/datetime.rst:2360 +msgid "`IANA time zone database `_" +msgstr "`IANA 時區資料庫 `_" + +#: ../../library/datetime.rst:2361 +msgid "" +"The Time Zone Database (often called tz, tzdata or zoneinfo) contains code " +"and data that represent the history of local time for many representative " +"locations around the globe. It is updated periodically to reflect changes " +"made by political bodies to time zone boundaries, UTC offsets, and daylight-" +"saving rules." +msgstr "" + +#: ../../library/datetime.rst:2371 +msgid ":class:`timezone` Objects" +msgstr ":class:`timezone` 物件" + +#: ../../library/datetime.rst:2373 +msgid "" +"The :class:`timezone` class is a subclass of :class:`tzinfo`, each instance " +"of which represents a time zone defined by a fixed offset from UTC." +msgstr "" + +#: ../../library/datetime.rst:2377 +msgid "" +"Objects of this class cannot be used to represent time zone information in " +"the locations where different offsets are used in different days of the year " +"or where historical changes have been made to civil time." +msgstr "" + +#: ../../library/datetime.rst:2384 +msgid "" +"The *offset* argument must be specified as a :class:`timedelta` object " +"representing the difference between the local time and UTC. It must be " +"strictly between ``-timedelta(hours=24)`` and ``timedelta(hours=24)``, " +"otherwise :exc:`ValueError` is raised." +msgstr "" + +#: ../../library/datetime.rst:2389 +msgid "" +"The *name* argument is optional. If specified it must be a string that will " +"be used as the value returned by the :meth:`datetime.tzname` method." +msgstr "" + +#: ../../library/datetime.rst:2400 ../../library/datetime.rst:2411 +msgid "" +"Return the fixed value specified when the :class:`timezone` instance is " +"constructed." +msgstr "" + +#: ../../library/datetime.rst:2403 +msgid "" +"The *dt* argument is ignored. The return value is a :class:`timedelta` " +"instance equal to the difference between the local time and UTC." +msgstr "" + +#: ../../library/datetime.rst:2414 +msgid "" +"If *name* is not provided in the constructor, the name returned by " +"``tzname(dt)`` is generated from the value of the ``offset`` as follows. If " +"*offset* is ``timedelta(0)``, the name is \"UTC\", otherwise it is a string " +"in the format ``UTC±HH:MM``, where ± is the sign of ``offset``, HH and MM " +"are two digits of ``offset.hours`` and ``offset.minutes`` respectively." +msgstr "" + +#: ../../library/datetime.rst:2420 +msgid "" +"Name generated from ``offset=timedelta(0)`` is now plain ``'UTC'``, not " +"``'UTC+00:00'``." +msgstr "" + +#: ../../library/datetime.rst:2427 +msgid "Always returns ``None``." +msgstr "總是回傳 ``None``。" + +#: ../../library/datetime.rst:2431 +msgid "" +"Return ``dt + offset``. The *dt* argument must be an aware :class:`." +"datetime` instance, with ``tzinfo`` set to ``self``." +msgstr "" + +#: ../../library/datetime.rst:2438 +msgid "The UTC time zone, ``timezone(timedelta(0))``." +msgstr "UTC 時區，``timezone(timedelta(0))``。" + +#: ../../library/datetime.rst:2447 +msgid ":meth:`~.datetime.strftime` and :meth:`~.datetime.strptime` Behavior" +msgstr ":meth:`~.datetime.strftime` 與 :meth:`~.datetime.strptime` 的行為" + +#: ../../library/datetime.rst:2449 +msgid "" +":class:`date`, :class:`.datetime`, and :class:`.time` objects all support a " +"``strftime(format)`` method, to create a string representing the time under " +"the control of an explicit format string." +msgstr "" + +#: ../../library/datetime.rst:2453 +msgid "" +"Conversely, the :meth:`date.strptime`, :meth:`datetime.strptime` and :meth:" +"`time.strptime` class methods create an object from a string representing " +"the time and a corresponding format string." +msgstr "" + +#: ../../library/datetime.rst:2457 +msgid "" +"The table below provides a high-level comparison of :meth:`~.datetime." +"strftime` versus :meth:`~.datetime.strptime`:" +msgstr "" + +#: ../../library/datetime.rst:2461 +msgid "``strftime``" +msgstr "``strftime``" + +#: ../../library/datetime.rst:2461 +msgid "``strptime``" +msgstr "``strptime``" + +#: ../../library/datetime.rst:2463 +msgid "Usage" +msgstr "用法" + +#: ../../library/datetime.rst:2463 +msgid "Convert object to a string according to a given format" +msgstr "" + +#: ../../library/datetime.rst:2463 +msgid "Parse a string into an object given a corresponding format" +msgstr "" + +#: ../../library/datetime.rst:2465 +msgid "Type of method" +msgstr "" + +#: ../../library/datetime.rst:2465 +msgid "Instance method" +msgstr "實例方法" + +#: ../../library/datetime.rst:2465 +msgid "Class method" +msgstr "類別方法" + +#: ../../library/datetime.rst:2467 +msgid "Signature" +msgstr "" + +#: ../../library/datetime.rst:2467 +msgid "``strftime(format)``" +msgstr "``strftime(format)``" + +#: ../../library/datetime.rst:2467 +msgid "``strptime(date_string, format)``" +msgstr "``strptime(date_string, format)``" + +#: ../../library/datetime.rst:2474 +msgid "" +":meth:`~.datetime.strftime` and :meth:`~.datetime.strptime` Format Codes" +msgstr ":meth:`~.datetime.strftime` 與 :meth:`~.datetime.strptime` 格式碼" + +#: ../../library/datetime.rst:2476 +msgid "" +"These methods accept format codes that can be used to parse and format " +"dates::" +msgstr "" + +#: ../../library/datetime.rst:2478 +msgid "" +">>> datetime.strptime('31/01/22 23:59:59.999999',\n" +"... '%d/%m/%y %H:%M:%S.%f')\n" +"datetime.datetime(2022, 1, 31, 23, 59, 59, 999999)\n" +">>> _.strftime('%a %d %b %Y, %I:%M%p')\n" +"'Mon 31 Jan 2022, 11:59PM'" +msgstr "" +">>> datetime.strptime('31/01/22 23:59:59.999999',\n" +"... '%d/%m/%y %H:%M:%S.%f')\n" +"datetime.datetime(2022, 1, 31, 23, 59, 59, 999999)\n" +">>> _.strftime('%a %d %b %Y, %I:%M%p')\n" +"'Mon 31 Jan 2022, 11:59PM'" + +#: ../../library/datetime.rst:2484 +msgid "" +"The following is a list of all the format codes that the 1989 C standard " +"requires, and these work on all platforms with a standard C implementation." +msgstr "" + +#: ../../library/datetime.rst:2488 ../../library/datetime.rst:2591 +msgid "Directive" +msgstr "" + +#: ../../library/datetime.rst:2488 ../../library/datetime.rst:2591 +msgid "Meaning" +msgstr "含義" + +#: ../../library/datetime.rst:2488 ../../library/datetime.rst:2591 +msgid "Example" +msgstr "範例" + +#: ../../library/datetime.rst:2488 ../../library/datetime.rst:2591 +msgid "Notes" +msgstr "註解" + +#: ../../library/datetime.rst:2490 +msgid "``%a``" +msgstr "``%a``" + +#: ../../library/datetime.rst:2490 +msgid "Weekday as locale's abbreviated name." +msgstr "" + +#: ../../library/datetime.rst:2490 +msgid "Sun, Mon, ..., Sat (en_US);" +msgstr "" + +#: ../../library/datetime.rst:2492 +msgid "So, Mo, ..., Sa (de_DE)" +msgstr "" + +#: ../../library/datetime.rst:2495 +msgid "``%A``" +msgstr "``%A``" + +#: ../../library/datetime.rst:2495 +msgid "Weekday as locale's full name." +msgstr "" + +#: ../../library/datetime.rst:2495 +msgid "Sunday, Monday, ..., Saturday (en_US);" +msgstr "" + +#: ../../library/datetime.rst:2497 +msgid "Sonntag, Montag, ..., Samstag (de_DE)" +msgstr "" + +#: ../../library/datetime.rst:2500 +msgid "``%w``" +msgstr "``%w``" + +#: ../../library/datetime.rst:2500 +msgid "Weekday as a decimal number, where 0 is Sunday and 6 is Saturday." +msgstr "" + +#: ../../library/datetime.rst:2500 +msgid "0, 1, ..., 6" +msgstr "0, 1, ..., 6" + +#: ../../library/datetime.rst:2504 +msgid "``%d``" +msgstr "``%d``" + +#: ../../library/datetime.rst:2504 +msgid "Day of the month as a zero-padded decimal number." +msgstr "" + +#: ../../library/datetime.rst:2504 +msgid "01, 02, ..., 31" +msgstr "01, 02, ..., 31" + +#: ../../library/datetime.rst:2504 ../../library/datetime.rst:2517 +#: ../../library/datetime.rst:2520 ../../library/datetime.rst:2526 +#: ../../library/datetime.rst:2529 ../../library/datetime.rst:2535 +#: ../../library/datetime.rst:2553 +msgid "\\(9)" +msgstr "\\(9)" + +#: ../../library/datetime.rst:2507 +msgid "``%b``" +msgstr "``%b``" + +#: ../../library/datetime.rst:2507 +msgid "Month as locale's abbreviated name." +msgstr "" + +#: ../../library/datetime.rst:2507 +msgid "Jan, Feb, ..., Dec (en_US);" +msgstr "" + +#: ../../library/datetime.rst:2509 +msgid "Jan, Feb, ..., Dez (de_DE)" +msgstr "" + +#: ../../library/datetime.rst:2512 +msgid "``%B``" +msgstr "``%B``" + +#: ../../library/datetime.rst:2512 +msgid "Month as locale's full name." +msgstr "" + +#: ../../library/datetime.rst:2512 +msgid "January, February, ..., December (en_US);" +msgstr "" + +#: ../../library/datetime.rst:2514 +msgid "Januar, Februar, ..., Dezember (de_DE)" +msgstr "" + +#: ../../library/datetime.rst:2517 +msgid "``%m``" +msgstr "``%m``" + +#: ../../library/datetime.rst:2517 +msgid "Month as a zero-padded decimal number." +msgstr "以零填充的並以十進位數字表示的月份。" + +#: ../../library/datetime.rst:2517 ../../library/datetime.rst:2529 +msgid "01, 02, ..., 12" +msgstr "01, 02, ..., 12" + +#: ../../library/datetime.rst:2520 +msgid "``%y``" +msgstr "``%y``" + +#: ../../library/datetime.rst:2520 +msgid "Year without century as a zero-padded decimal number." +msgstr "" + +#: ../../library/datetime.rst:2520 +msgid "00, 01, ..., 99" +msgstr "00, 01, ..., 99" + +#: ../../library/datetime.rst:2523 +msgid "``%Y``" +msgstr "``%Y``" + +#: ../../library/datetime.rst:2523 +msgid "Year with century as a decimal number." +msgstr "" + +#: ../../library/datetime.rst:2523 ../../library/datetime.rst:2593 +msgid "0001, 0002, ..., 2013, 2014, ..., 9998, 9999" +msgstr "0001, 0002, ..., 2013, 2014, ..., 9998, 9999" + +#: ../../library/datetime.rst:2526 +msgid "``%H``" +msgstr "``%H``" + +#: ../../library/datetime.rst:2526 +msgid "Hour (24-hour clock) as a zero-padded decimal number." +msgstr "" + +#: ../../library/datetime.rst:2526 +msgid "00, 01, ..., 23" +msgstr "00, 01, ..., 23" + +#: ../../library/datetime.rst:2529 +msgid "``%I``" +msgstr "``%I``" + +#: ../../library/datetime.rst:2529 +msgid "Hour (12-hour clock) as a zero-padded decimal number." +msgstr "" + +#: ../../library/datetime.rst:2532 +msgid "``%p``" +msgstr "``%p``" + +#: ../../library/datetime.rst:2532 +msgid "Locale's equivalent of either AM or PM." +msgstr "" + +#: ../../library/datetime.rst:2532 +msgid "AM, PM (en_US);" +msgstr "AM, PM (en_US);" + +#: ../../library/datetime.rst:2533 +msgid "am, pm (de_DE)" +msgstr "am, pm (de_DE)" + +#: ../../library/datetime.rst:2532 +msgid "\\(1), \\(3)" +msgstr "\\(1), \\(3)" + +#: ../../library/datetime.rst:2535 +msgid "``%M``" +msgstr "``%M``" + +#: ../../library/datetime.rst:2535 +msgid "Minute as a zero-padded decimal number." +msgstr "" + +#: ../../library/datetime.rst:2535 ../../library/datetime.rst:2538 +msgid "00, 01, ..., 59" +msgstr "00, 01, ..., 59" + +#: ../../library/datetime.rst:2538 +msgid "``%S``" +msgstr "``%S``" + +#: ../../library/datetime.rst:2538 +msgid "Second as a zero-padded decimal number." +msgstr "" + +#: ../../library/datetime.rst:2538 +msgid "\\(4), \\(9)" +msgstr "\\(4), \\(9)" + +#: ../../library/datetime.rst:2541 +msgid "``%f``" +msgstr "``%f``" + +#: ../../library/datetime.rst:2541 +msgid "Microsecond as a decimal number, zero-padded to 6 digits." +msgstr "" + +#: ../../library/datetime.rst:2541 +msgid "000000, 000001, ..., 999999" +msgstr "000000, 000001, ..., 999999" + +#: ../../library/datetime.rst:2541 +msgid "\\(5)" +msgstr "\\(5)" + +#: ../../library/datetime.rst:2545 ../../library/datetime.rst:2737 +msgid "``%z``" +msgstr "``%z``" + +#: ../../library/datetime.rst:2545 +msgid "" +"UTC offset in the form ``±HHMM[SS[.ffffff]]`` (empty string if the object is " +"naive)." +msgstr "" + +#: ../../library/datetime.rst:2545 +msgid "(empty), +0000, -0400, +1030, +063415, -030712.345216" +msgstr "" + +#: ../../library/datetime.rst:2545 ../../library/datetime.rst:2550 +#: ../../library/datetime.rst:2607 +msgid "\\(6)" +msgstr "\\(6)" + +#: ../../library/datetime.rst:2550 ../../library/datetime.rst:2763 +msgid "``%Z``" +msgstr "``%Z``" + +#: ../../library/datetime.rst:2550 +msgid "Time zone name (empty string if the object is naive)." +msgstr "" + +#: ../../library/datetime.rst:2550 +msgid "(empty), UTC, GMT" +msgstr "" + +#: ../../library/datetime.rst:2553 +msgid "``%j``" +msgstr "``%j``" + +#: ../../library/datetime.rst:2553 +msgid "Day of the year as a zero-padded decimal number." +msgstr "" + +#: ../../library/datetime.rst:2553 +msgid "001, 002, ..., 366" +msgstr "001, 002, ..., 366" + +#: ../../library/datetime.rst:2556 +msgid "``%U``" +msgstr "``%U``" + +#: ../../library/datetime.rst:2556 +msgid "" +"Week number of the year (Sunday as the first day of the week) as a zero-" +"padded decimal number. All days in a new year preceding the first Sunday are " +"considered to be in week 0." +msgstr "" + +#: ../../library/datetime.rst:2556 ../../library/datetime.rst:2564 +msgid "00, 01, ..., 53" +msgstr "00, 01, ..., 53" + +#: ../../library/datetime.rst:2556 ../../library/datetime.rst:2564 +msgid "\\(7), \\(9)" +msgstr "\\(7), \\(9)" + +#: ../../library/datetime.rst:2564 +msgid "``%W``" +msgstr "``%W``" + +#: ../../library/datetime.rst:2564 +msgid "" +"Week number of the year (Monday as the first day of the week) as a zero-" +"padded decimal number. All days in a new year preceding the first Monday are " +"considered to be in week 0." +msgstr "" + +#: ../../library/datetime.rst:2572 +msgid "``%c``" +msgstr "``%c``" + +#: ../../library/datetime.rst:2572 +msgid "Locale's appropriate date and time representation." +msgstr "" + +#: ../../library/datetime.rst:2572 +msgid "Tue Aug 16 21:30:00 1988 (en_US);" +msgstr "" + +#: ../../library/datetime.rst:2574 +msgid "Di 16 Aug 21:30:00 1988 (de_DE)" +msgstr "" + +#: ../../library/datetime.rst:2577 +msgid "``%x``" +msgstr "``%x``" + +#: ../../library/datetime.rst:2577 +msgid "Locale's appropriate date representation." +msgstr "" + +#: ../../library/datetime.rst:2577 +msgid "08/16/88 (None);" +msgstr "" + +#: ../../library/datetime.rst:2578 +msgid "08/16/1988 (en_US);" +msgstr "" + +#: ../../library/datetime.rst:2579 +msgid "16.08.1988 (de_DE)" +msgstr "" + +#: ../../library/datetime.rst:2581 +msgid "``%X``" +msgstr "``%X``" + +#: ../../library/datetime.rst:2581 +msgid "Locale's appropriate time representation." +msgstr "" + +#: ../../library/datetime.rst:2581 +msgid "21:30:00 (en_US);" +msgstr "" + +#: ../../library/datetime.rst:2582 +msgid "21:30:00 (de_DE)" +msgstr "" + +#: ../../library/datetime.rst:2584 +msgid "``%%``" +msgstr "``%%``" + +#: ../../library/datetime.rst:2584 +msgid "A literal ``'%'`` character." +msgstr "" + +#: ../../library/datetime.rst:2584 +msgid "%" +msgstr "%" + +#: ../../library/datetime.rst:2587 +msgid "" +"Several additional directives not required by the C89 standard are included " +"for convenience. These parameters all correspond to ISO 8601 date values." +msgstr "" + +#: ../../library/datetime.rst:2593 +msgid "``%G``" +msgstr "``%G``" + +#: ../../library/datetime.rst:2593 +msgid "" +"ISO 8601 year with century representing the year that contains the greater " +"part of the ISO week (``%V``)." +msgstr "" + +#: ../../library/datetime.rst:2593 +msgid "\\(8)" +msgstr "\\(8)" + +#: ../../library/datetime.rst:2598 +msgid "``%u``" +msgstr "``%u``" + +#: ../../library/datetime.rst:2598 +msgid "ISO 8601 weekday as a decimal number where 1 is Monday." +msgstr "" + +#: ../../library/datetime.rst:2598 +msgid "1, 2, ..., 7" +msgstr "1, 2, ..., 7" + +#: ../../library/datetime.rst:2601 +msgid "``%V``" +msgstr "``%V``" + +#: ../../library/datetime.rst:2601 +msgid "" +"ISO 8601 week as a decimal number with Monday as the first day of the week. " +"Week 01 is the week containing Jan 4." +msgstr "" + +#: ../../library/datetime.rst:2601 +msgid "01, 02, ..., 53" +msgstr "01, 02, ..., 53" + +#: ../../library/datetime.rst:2601 +msgid "\\(8), \\(9)" +msgstr "\\(8), \\(9)" + +#: ../../library/datetime.rst:2607 ../../library/datetime.rst:2759 +msgid "``%:z``" +msgstr "``%:z``" + +#: ../../library/datetime.rst:2607 +msgid "" +"UTC offset in the form ``±HH:MM[:SS[.ffffff]]`` (empty string if the object " +"is naive)." +msgstr "" + +#: ../../library/datetime.rst:2607 +msgid "(empty), +00:00, -04:00, +10:30, +06:34:15, -03:07:12.345216" +msgstr "" + +#: ../../library/datetime.rst:2613 +msgid "" +"These may not be available on all platforms when used with the :meth:`~." +"datetime.strftime` method. The ISO 8601 year and ISO 8601 week directives " +"are not interchangeable with the year and week number directives above. " +"Calling :meth:`~.datetime.strptime` with incomplete or ambiguous ISO 8601 " +"directives will raise a :exc:`ValueError`." +msgstr "" + +#: ../../library/datetime.rst:2618 +msgid "" +"The full set of format codes supported varies across platforms, because " +"Python calls the platform C library's :c:func:`strftime` function, and " +"platform variations are common. To see the full set of format codes " +"supported on your platform, consult the :manpage:`strftime(3)` " +"documentation. There are also differences between platforms in handling of " +"unsupported format specifiers." +msgstr "" + +#: ../../library/datetime.rst:2624 +msgid "``%G``, ``%u`` and ``%V`` were added." +msgstr "新增 ``%G``、``%u`` 與 ``%V``。" + +#: ../../library/datetime.rst:2627 +msgid "``%:z`` was added." +msgstr "新增 ``%:z``。" + +#: ../../library/datetime.rst:2631 +msgid "Technical Detail" +msgstr "技術細節" + +#: ../../library/datetime.rst:2633 +msgid "" +"Broadly speaking, ``d.strftime(fmt)`` acts like the :mod:`time` module's " +"``time.strftime(fmt, d.timetuple())`` although not all objects support a :" +"meth:`~date.timetuple` method." +msgstr "" + +#: ../../library/datetime.rst:2637 +msgid "" +"For the :meth:`.datetime.strptime` and :meth:`.date.strptime` class methods, " +"the default value is ``1900-01-01T00:00:00.000``: any components not " +"specified in the format string will be pulled from the default value." +msgstr "" + +#: ../../library/datetime.rst:2642 +msgid "" +"When used to parse partial dates lacking a year, :meth:`.datetime.strptime` " +"and :meth:`.date.strptime` will raise when encountering February 29 because " +"the default year of 1900 is *not* a leap year. Always add a default leap " +"year to partial date strings before parsing." +msgstr "" + +#: ../../library/datetime.rst:2663 +msgid "" +">>> from datetime import datetime\n" +">>> value = \"2/29\"\n" +">>> datetime.strptime(value, \"%m/%d\")\n" +"Traceback (most recent call last):\n" +"...\n" +"ValueError: day 29 must be in range 1..28 for month 2 in year 1900\n" +">>> datetime.strptime(f\"1904 {value}\", \"%Y %m/%d\")\n" +"datetime.datetime(1904, 2, 29, 0, 0)" +msgstr "" + +#: ../../library/datetime.rst:2674 +msgid "Using ``datetime.strptime(date_string, format)`` is equivalent to::" +msgstr "" + +#: ../../library/datetime.rst:2678 +msgid "" +"except when the format includes sub-second components or time zone offset " +"information, which are supported in ``datetime.strptime`` but are discarded " +"by ``time.strptime``." +msgstr "" + +#: ../../library/datetime.rst:2682 +msgid "" +"For :class:`.time` objects, the format codes for year, month, and day should " +"not be used, as :class:`!time` objects have no such values. If they're used " +"anyway, 1900 is substituted for the year, and 1 for the month and day." +msgstr "" +"對 :class:`.time` 物件來說，不應該使用年、月、日的格式碼，因為 :class:`!" +"time` 物件並沒有這些值。如果使用這些格式碼，年份會以 1900 代替、月及日會以 1 " +"代替。" + +#: ../../library/datetime.rst:2686 +msgid "" +"For :class:`date` objects, the format codes for hours, minutes, seconds, and " +"microseconds should not be used, as :class:`date` objects have no such " +"values. If they're used anyway, 0 is substituted for them." +msgstr "" +"對 :class:`.date` 物件來說，不應該使用時、分、秒、微秒的格式碼，因為 :class:" +"`date` 物件並沒有這些值。如果使用這些格式碼，這些值都會以 0 代替。" + +#: ../../library/datetime.rst:2690 +msgid "" +"For the same reason, handling of format strings containing Unicode code " +"points that can't be represented in the charset of the current locale is " +"also platform-dependent. On some platforms such code points are preserved " +"intact in the output, while on others ``strftime`` may raise :exc:" +"`UnicodeError` or return an empty string instead." +msgstr "" + +#: ../../library/datetime.rst:2699 +msgid "" +"Because the format depends on the current locale, care should be taken when " +"making assumptions about the output value. Field orderings will vary (for " +"example, \"month/day/year\" versus \"day/month/year\"), and the output may " +"contain non-ASCII characters." +msgstr "" + +#: ../../library/datetime.rst:2705 +msgid "" +"The :meth:`~.datetime.strptime` method can parse years in the full [1, 9999] " +"range, but years < 1000 must be zero-filled to 4-digit width." +msgstr "" + +#: ../../library/datetime.rst:2708 +msgid "" +"In previous versions, :meth:`~.datetime.strftime` method was restricted to " +"years >= 1900." +msgstr "" + +#: ../../library/datetime.rst:2712 +msgid "" +"In version 3.2, :meth:`~.datetime.strftime` method was restricted to years " +">= 1000." +msgstr "" + +#: ../../library/datetime.rst:2717 +msgid "" +"When used with the :meth:`~.datetime.strptime` method, the ``%p`` directive " +"only affects the output hour field if the ``%I`` directive is used to parse " +"the hour." +msgstr "" + +#: ../../library/datetime.rst:2721 +msgid "" +"Unlike the :mod:`time` module, the :mod:`!datetime` module does not support " +"leap seconds." +msgstr "" + +#: ../../library/datetime.rst:2725 +msgid "" +"When used with the :meth:`~.datetime.strptime` method, the ``%f`` directive " +"accepts from one to six digits and zero pads on the right. ``%f`` is an " +"extension to the set of format characters in the C standard (but implemented " +"separately in datetime objects, and therefore always available)." +msgstr "" + +#: ../../library/datetime.rst:2732 +msgid "" +"For a naive object, the ``%z``, ``%:z`` and ``%Z`` format codes are replaced " +"by empty strings." +msgstr "" + +#: ../../library/datetime.rst:2735 +msgid "For an aware object:" +msgstr "" + +#: ../../library/datetime.rst:2738 +msgid "" +":meth:`~.datetime.utcoffset` is transformed into a string of the form " +"``±HHMM[SS[.ffffff]]``, where ``HH`` is a 2-digit string giving the number " +"of UTC offset hours, ``MM`` is a 2-digit string giving the number of UTC " +"offset minutes, ``SS`` is a 2-digit string giving the number of UTC offset " +"seconds and ``ffffff`` is a 6-digit string giving the number of UTC offset " +"microseconds. The ``ffffff`` part is omitted when the offset is a whole " +"number of seconds and both the ``ffffff`` and the ``SS`` part is omitted " +"when the offset is a whole number of minutes. For example, if :meth:`~." +"datetime.utcoffset` returns ``timedelta(hours=-3, minutes=-30)``, ``%z`` is " +"replaced with the string ``'-0330'``." +msgstr "" + +#: ../../library/datetime.rst:2752 +msgid "" +"When the ``%z`` directive is provided to the :meth:`~.datetime.strptime` " +"method, the UTC offsets can have a colon as a separator between hours, " +"minutes and seconds. For example, ``'+01:00:00'`` will be parsed as an " +"offset of one hour. In addition, providing ``'Z'`` is identical to " +"``'+00:00'``." +msgstr "" + +#: ../../library/datetime.rst:2760 +msgid "" +"Behaves exactly as ``%z``, but has a colon separator added between hours, " +"minutes and seconds." +msgstr "" + +#: ../../library/datetime.rst:2764 +msgid "" +"In :meth:`~.datetime.strftime`, ``%Z`` is replaced by an empty string if :" +"meth:`~.datetime.tzname` returns ``None``; otherwise ``%Z`` is replaced by " +"the returned value, which must be a string." +msgstr "" + +#: ../../library/datetime.rst:2768 +msgid ":meth:`~.datetime.strptime` only accepts certain values for ``%Z``:" +msgstr "" + +#: ../../library/datetime.rst:2770 +msgid "any value in ``time.tzname`` for your machine's locale" +msgstr "" + +#: ../../library/datetime.rst:2771 +msgid "the hard-coded values ``UTC`` and ``GMT``" +msgstr "" + +#: ../../library/datetime.rst:2773 +msgid "" +"So someone living in Japan may have ``JST``, ``UTC``, and ``GMT`` as valid " +"values, but probably not ``EST``. It will raise ``ValueError`` for invalid " +"values." +msgstr "" + +#: ../../library/datetime.rst:2777 +msgid "" +"When the ``%z`` directive is provided to the :meth:`~.datetime.strptime` " +"method, an aware :class:`.datetime` object will be produced. The ``tzinfo`` " +"of the result will be set to a :class:`timezone` instance." +msgstr "" + +#: ../../library/datetime.rst:2783 +msgid "" +"When used with the :meth:`~.datetime.strptime` method, ``%U`` and ``%W`` are " +"only used in calculations when the day of the week and the calendar year " +"(``%Y``) are specified." +msgstr "" + +#: ../../library/datetime.rst:2788 +msgid "" +"Similar to ``%U`` and ``%W``, ``%V`` is only used in calculations when the " +"day of the week and the ISO year (``%G``) are specified in a :meth:`~." +"datetime.strptime` format string. Also note that ``%G`` and ``%Y`` are not " +"interchangeable." +msgstr "" + +#: ../../library/datetime.rst:2794 +msgid "" +"When used with the :meth:`~.datetime.strptime` method, the leading zero is " +"optional for formats ``%d``, ``%m``, ``%H``, ``%I``, ``%M``, ``%S``, " +"``%j``, ``%U``, ``%W``, and ``%V``. Format ``%y`` does require a leading " +"zero." +msgstr "" + +#: ../../library/datetime.rst:2799 +msgid "" +"When parsing a month and day using :meth:`~.datetime.strptime`, always " +"include a year in the format. If the value you need to parse lacks a year, " +"append an explicit dummy leap year. Otherwise your code will raise an " +"exception when it encounters leap day because the default year used by the " +"parser (1900) is not a leap year. Users run into that bug every leap year." +msgstr "" + +#: ../../library/datetime.rst:2805 +msgid "" +">>> month_day = \"02/29\"\n" +">>> datetime.strptime(f\"{month_day};1984\", \"%m/%d;%Y\") # No leap year " +"bug.\n" +"datetime.datetime(1984, 2, 29, 0, 0)" +msgstr "" +">>> month_day = \"02/29\"\n" +">>> datetime.strptime(f\"{month_day};1984\", \"%m/%d;%Y\") # 沒有閏年問" +"題。\n" +"datetime.datetime(1984, 2, 29, 0, 0)" + +#: ../../library/datetime.rst:2811 +msgid "" +":meth:`~.datetime.strptime` calls using a format string containing a day of " +"month without a year now emit a :exc:`DeprecationWarning`. In 3.15 or later " +"we may change this into an error or change the default year to a leap year. " +"See :gh:`70647`." +msgstr "" + +#: ../../library/datetime.rst:2818 +msgid "Footnotes" +msgstr "註解" + +#: ../../library/datetime.rst:2819 +msgid "If, that is, we ignore the effects of Relativity" +msgstr "也就是說，我們會忽略相對論的效應" + +#: ../../library/datetime.rst:2821 +msgid "" +"This matches the definition of the \"proleptic Gregorian\" calendar in " +"Dershowitz and Reingold's book *Calendrical Calculations*, where it's the " +"base calendar for all computations. See the book for algorithms for " +"converting between proleptic Gregorian ordinals and many other calendar " +"systems." +msgstr "" + +#: ../../library/datetime.rst:2827 +msgid "" +"See R. H. van Gent's `guide to the mathematics of the ISO 8601 calendar " +"`_ for a good explanation." +msgstr "" + +#: ../../library/datetime.rst:2441 +msgid "% (percent)" +msgstr "% （百分號）" + +#: ../../library/datetime.rst:2441 +msgid "datetime format" +msgstr "datetime format（日期時間格式）" + +#~ msgid ":class:`date`; :class:`.datetime`; :class:`.time`" +#~ msgstr ":class:`date`; :class:`.datetime`; :class:`.time`" + +#~ msgid ":class:`.datetime`" +#~ msgstr ":class:`.datetime`" diff --git a/library/dbm.po b/library/dbm.po index 1e095eea0b..4005531d24 100644 --- a/library/dbm.po +++ b/library/dbm.po @@ -1,636 +1,636 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# jerrychen , 2016 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-10-08 00:15+0000\n" -"PO-Revision-Date: 2018-05-23 14:42+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/dbm.rst:2 -msgid ":mod:`!dbm` --- Interfaces to Unix \"databases\"" -msgstr ":mod:`!dbm` --- Unix \"databases\" 的介面" - -#: ../../library/dbm.rst:7 -msgid "**Source code:** :source:`Lib/dbm/__init__.py`" -msgstr "**原始碼：**\\ :source:`Lib/dbm/__init__.py`" - -#: ../../library/dbm.rst:11 -msgid ":mod:`dbm` is a generic interface to variants of the DBM database:" -msgstr "" - -#: ../../library/dbm.rst:13 -msgid ":mod:`dbm.sqlite3`" -msgstr ":mod:`dbm.sqlite3`" - -#: ../../library/dbm.rst:14 -msgid ":mod:`dbm.gnu`" -msgstr ":mod:`dbm.gnu`" - -#: ../../library/dbm.rst:15 -msgid ":mod:`dbm.ndbm`" -msgstr ":mod:`dbm.ndbm`" - -#: ../../library/dbm.rst:17 -msgid "" -"If none of these modules are installed, the slow-but-simple implementation " -"in module :mod:`dbm.dumb` will be used. There is a `third party interface " -"`_ to the Oracle Berkeley DB." -msgstr "" - -#: ../../library/dbm.rst:24 -msgid "" -"A tuple containing the exceptions that can be raised by each of the " -"supported modules, with a unique exception also named :exc:`dbm.error` as " -"the first item --- the latter is used when :exc:`dbm.error` is raised." -msgstr "" - -#: ../../library/dbm.rst:31 -msgid "" -"This function attempts to guess which of the several simple database modules " -"available --- :mod:`dbm.sqlite3`, :mod:`dbm.gnu`, :mod:`dbm.ndbm`, or :mod:" -"`dbm.dumb` --- should be used to open a given file." -msgstr "" - -#: ../../library/dbm.rst:35 -msgid "Return one of the following values:" -msgstr "回傳以下其中一個值：" - -#: ../../library/dbm.rst:37 -msgid "" -"``None`` if the file can't be opened because it's unreadable or doesn't exist" -msgstr "" - -#: ../../library/dbm.rst:38 -msgid "the empty string (``''``) if the file's format can't be guessed" -msgstr "" - -#: ../../library/dbm.rst:39 -msgid "" -"a string containing the required module name, such as ``'dbm.ndbm'`` or " -"``'dbm.gnu'``" -msgstr "" - -#: ../../library/dbm.rst:41 ../../library/dbm.rst:270 ../../library/dbm.rst:471 -msgid "*filename* accepts a :term:`path-like object`." -msgstr "" - -#: ../../library/dbm.rst:65 -msgid "Open a database and return the corresponding database object." -msgstr "" - -#: ../../library/dbm.rst:0 -msgid "Parameters" -msgstr "參數" - -#: ../../library/dbm.rst:67 -msgid "" -"The database file to open. If the database file already exists, the :func:" -"`whichdb` function is used to determine its type and the appropriate module " -"is used; if it does not exist, the first submodule listed above that can be " -"imported is used." -msgstr "" - -#: ../../library/dbm.rst:68 ../../library/dbm.rst:242 -msgid "The database file to open." -msgstr "要打開的資料庫檔案" - -#: ../../library/dbm.rst:70 -msgid "" -"If the database file already exists, the :func:`whichdb` function is used to " -"determine its type and the appropriate module is used; if it does not exist, " -"the first submodule listed above that can be imported is used." -msgstr "" - -#: ../../library/dbm.rst:75 ../../library/dbm.rst:182 ../../library/dbm.rst:374 -msgid "" -"* ``'r'`` (default): |flag_r| * ``'w'``: |flag_w| * ``'c'``: |flag_c| * " -"``'n'``: |flag_n|" -msgstr "" -"* ``'r'`` (default): |flag_r| * ``'w'``: |flag_w| * ``'c'``: |flag_c| * " -"``'n'``: |flag_n|" - -#: ../../library/dbm.rst:76 ../../library/dbm.rst:184 ../../library/dbm.rst:247 -#: ../../library/dbm.rst:375 -msgid "``'r'`` (default): |flag_r|" -msgstr "``'r'`` (default): |flag_r|" - -#: ../../library/dbm.rst:77 ../../library/dbm.rst:185 ../../library/dbm.rst:248 -#: ../../library/dbm.rst:376 ../../library/dbm.rst:452 -msgid "``'w'``: |flag_w|" -msgstr "``'w'``: |flag_w|" - -#: ../../library/dbm.rst:78 ../../library/dbm.rst:186 ../../library/dbm.rst:249 -#: ../../library/dbm.rst:377 -msgid "``'c'``: |flag_c|" -msgstr "``'c'``: |flag_c|" - -#: ../../library/dbm.rst:79 ../../library/dbm.rst:187 ../../library/dbm.rst:250 -#: ../../library/dbm.rst:378 ../../library/dbm.rst:454 -msgid "``'n'``: |flag_n|" -msgstr "``'n'``: |flag_n|" - -#: ../../library/dbm.rst:81 ../../library/dbm.rst:264 ../../library/dbm.rst:380 -#: ../../library/dbm.rst:456 -msgid "|mode_param_doc|" -msgstr "|mode_param_doc|" - -#: ../../library/dbm.rst:84 -msgid "*file* accepts a :term:`path-like object`." -msgstr "*file* 接受一個\\ :term:`類路徑物件 `。" - -#: ../../library/dbm.rst:87 -msgid "" -"The object returned by :func:`~dbm.open` supports the basic functionality of " -"mutable :term:`mappings `; keys and their corresponding values can " -"be stored, retrieved, and deleted, and iteration, the :keyword:`in` operator " -"and methods :meth:`!keys`, :meth:`!get`, :meth:`!setdefault` and :meth:`!" -"clear` are available. The :meth:`!keys` method returns a list instead of a " -"view object. The :meth:`!setdefault` method requires two arguments." -msgstr "" - -#: ../../library/dbm.rst:95 -msgid "" -"Key and values are always stored as :class:`bytes`. This means that when " -"strings are used they are implicitly converted to the default encoding " -"before being stored." -msgstr "" - -#: ../../library/dbm.rst:99 -msgid "" -"These objects also support being used in a :keyword:`with` statement, which " -"will automatically close them when done." -msgstr "" - -#: ../../library/dbm.rst:102 -msgid "" -":meth:`!get` and :meth:`!setdefault` methods are now available for all :mod:" -"`dbm` backends." -msgstr "" - -#: ../../library/dbm.rst:106 -msgid "" -"Added native support for the context management protocol to the objects " -"returned by :func:`~dbm.open`." -msgstr "" - -#: ../../library/dbm.rst:110 -msgid "" -"Deleting a key from a read-only database raises a database module specific " -"exception instead of :exc:`KeyError`." -msgstr "" - -#: ../../library/dbm.rst:114 -msgid ":meth:`!clear` methods are now available for all :mod:`dbm` backends." -msgstr ":meth:`!clear` 方法現在可用於所有 :mod:`dbm` 後端。" - -#: ../../library/dbm.rst:118 -msgid "" -"The following example records some hostnames and a corresponding title, and " -"then prints out the contents of the database::" -msgstr "" - -#: ../../library/dbm.rst:121 -msgid "" -"import dbm\n" -"\n" -"# Open database, creating it if necessary.\n" -"with dbm.open('cache', 'c') as db:\n" -"\n" -" # Record some values\n" -" db[b'hello'] = b'there'\n" -" db['www.python.org'] = 'Python Website'\n" -" db['www.cnn.com'] = 'Cable News Network'\n" -"\n" -" # Note that the keys are considered bytes now.\n" -" assert db[b'www.python.org'] == b'Python Website'\n" -" # Notice how the value is now in bytes.\n" -" assert db['www.cnn.com'] == b'Cable News Network'\n" -"\n" -" # Often-used methods of the dict interface work too.\n" -" print(db.get('python.org', b'not present'))\n" -"\n" -" # Storing a non-string key or value will raise an exception (most\n" -" # likely a TypeError).\n" -" db['www.yahoo.com'] = 4\n" -"\n" -"# db is automatically closed when leaving the with statement." -msgstr "" - -#: ../../library/dbm.rst:148 -msgid "Module :mod:`shelve`" -msgstr ":mod:`shelve` 模組" - -#: ../../library/dbm.rst:149 -msgid "Persistence module which stores non-string data." -msgstr "" - -#: ../../library/dbm.rst:152 -msgid "The individual submodules are described in the following sections." -msgstr "" - -#: ../../library/dbm.rst:155 -msgid ":mod:`dbm.sqlite3` --- SQLite backend for dbm" -msgstr ":mod:`dbm.sqlite3` --- dbm 的 SQLite 後端" - -#: ../../library/dbm.rst:163 -msgid "**Source code:** :source:`Lib/dbm/sqlite3.py`" -msgstr "**原始碼：**\\ :source:`Lib/dbm/sqlite3.py`" - -#: ../../library/dbm.rst:167 -msgid "" -"This module uses the standard library :mod:`sqlite3` module to provide an " -"SQLite backend for the :mod:`dbm` module. The files created by :mod:`dbm." -"sqlite3` can thus be opened by :mod:`sqlite3`, or any other SQLite browser, " -"including the SQLite CLI." -msgstr "" - -#: ../../includes/wasm-mobile-notavail.rst:3 ../../includes/wasm-notavail.rst:3 -msgid "Availability" -msgstr "可用性" - -#: ../../includes/wasm-notavail.rst:5 -msgid "" -"This module does not work or is not available on WebAssembly. See :ref:`wasm-" -"availability` for more information." -msgstr "" -"此模組在 WebAssembly 平台上不起作用或無法使用。更多資訊請參閱 :ref:`wasm-" -"availability`。" - -#: ../../library/dbm.rst:176 -msgid "Open an SQLite database." -msgstr "打開一個 SQLite 資料庫。" - -#: ../../library/dbm.rst:178 -msgid "The path to the database to be opened." -msgstr "要打開的資料庫路徑" - -#: ../../library/dbm.rst:189 -msgid "" -"The Unix file access mode of the file (default: octal ``0o666``), used only " -"when the database has to be created." -msgstr "" - -#: ../../library/dbm.rst:193 -msgid "" -"The returned database object behaves similar to a mutable :term:`mapping`, " -"but the :meth:`!keys` method returns a list, and the :meth:`!setdefault` " -"method requires two arguments. It also supports a \"closing\" context " -"manager via the :keyword:`with` keyword." -msgstr "" - -#: ../../library/dbm.rst:198 ../../library/dbm.rst:399 -msgid "The following method is also provided:" -msgstr "也提供了以下方法：" - -#: ../../library/dbm.rst:202 -msgid "Close the SQLite database." -msgstr "關閉 SQLite 資料庫。" - -#: ../../library/dbm.rst:206 -msgid ":mod:`dbm.gnu` --- GNU database manager" -msgstr ":mod:`dbm.gnu` --- GNU 資料庫管理器" - -#: ../../library/dbm.rst:212 -msgid "**Source code:** :source:`Lib/dbm/gnu.py`" -msgstr "**原始碼：**\\ :source:`Lib/dbm/gnu.py`" - -#: ../../library/dbm.rst:216 -msgid "" -"The :mod:`dbm.gnu` module provides an interface to the :abbr:`GDBM (GNU " -"dbm)` library, similar to the :mod:`dbm.ndbm` module, but with additional " -"functionality like crash tolerance." -msgstr "" - -#: ../../library/dbm.rst:222 ../../library/dbm.rst:342 -msgid "" -"The file formats created by :mod:`dbm.gnu` and :mod:`dbm.ndbm` are " -"incompatible and can not be used interchangeably." -msgstr "" - -#: ../../includes/wasm-mobile-notavail.rst:5 -msgid "" -"This module is not supported on :ref:`mobile platforms ` or :ref:`WebAssembly platforms `." -msgstr "" -"此模組在\\ :ref:`行動平台 `\\ 或 :ref:`WebAssembly 平" -"台 `\\ 上不支援。" - -#: ../../library/dbm.rst:229 -msgid "" -"Raised on :mod:`dbm.gnu`-specific errors, such as I/O errors. :exc:" -"`KeyError` is raised for general mapping errors like specifying an incorrect " -"key." -msgstr "" - -#: ../../library/dbm.rst:235 -msgid "" -"A string of characters the *flag* parameter of :meth:`~dbm.gnu.open` " -"supports." -msgstr "" - -#: ../../library/dbm.rst:240 -msgid "Open a GDBM database and return a :class:`!gdbm` object." -msgstr "打開一個 GDBM 資料庫，並回傳一個 :class:`!gdbm` 物件。" - -#: ../../library/dbm.rst:246 -msgid "" -"* ``'r'`` (default): |flag_r| * ``'w'``: |flag_w| * ``'c'``: |flag_c| * " -"``'n'``: |flag_n| The following additional characters may be appended to " -"control how the database is opened: * ``'f'``: Open the database in fast " -"mode. Writes to the database will not be synchronized. * ``'s'``: " -"Synchronized mode. Changes to the database will be written immediately to " -"the file. * ``'u'``: Do not lock database. Not all flags are valid for all " -"versions of GDBM. See the :data:`open_flags` member for a list of supported " -"flag characters." -msgstr "" - -#: ../../library/dbm.rst:252 -msgid "" -"The following additional characters may be appended to control how the " -"database is opened:" -msgstr "" - -#: ../../library/dbm.rst:255 -msgid "" -"``'f'``: Open the database in fast mode. Writes to the database will not be " -"synchronized." -msgstr "" - -#: ../../library/dbm.rst:257 -msgid "" -"``'s'``: Synchronized mode. Changes to the database will be written " -"immediately to the file." -msgstr "" - -#: ../../library/dbm.rst:259 -msgid "``'u'``: Do not lock database." -msgstr "``'u'``: 不要鎖住資料庫。" - -#: ../../library/dbm.rst:261 -msgid "" -"Not all flags are valid for all versions of GDBM. See the :data:`open_flags` " -"member for a list of supported flag characters." -msgstr "" - -#: ../../library/dbm.rst:0 -msgid "Raises" -msgstr "引發" - -#: ../../library/dbm.rst:267 -msgid "If an invalid *flag* argument is passed." -msgstr "如果一個無效的 *flag* 引數被傳入。" - -#: ../../library/dbm.rst:273 -msgid "" -":class:`!gdbm` objects behave similar to mutable :term:`mappings `, " -"but methods :meth:`!items`, :meth:`!values`, :meth:`!pop`, :meth:`!popitem`, " -"and :meth:`!update` are not supported, the :meth:`!keys` method returns a " -"list, and the :meth:`!setdefault` method requires two arguments. It also " -"supports a \"closing\" context manager via the :keyword:`with` keyword." -msgstr "" - -#: ../../library/dbm.rst:280 ../../library/dbm.rst:393 -msgid "Added the :meth:`!get` and :meth:`!setdefault` methods." -msgstr "新增了 :meth:`!get` 和 :meth:`!setdefault` 方法。" - -#: ../../library/dbm.rst:283 ../../library/dbm.rst:396 -msgid "Added the :meth:`!clear` method." -msgstr "新增了 :meth:`!clear` 方法。" - -#: ../../library/dbm.rst:286 ../../library/dbm.rst:479 -msgid "The following methods are also provided:" -msgstr "也提供了以下方法：" - -#: ../../library/dbm.rst:290 -msgid "Close the GDBM database." -msgstr "關閉 GDBM 資料庫。" - -#: ../../library/dbm.rst:294 -msgid "" -"It's possible to loop over every key in the database using this method and " -"the :meth:`nextkey` method. The traversal is ordered by GDBM's internal " -"hash values, and won't be sorted by the key values. This method returns the " -"starting key." -msgstr "" - -#: ../../library/dbm.rst:301 -msgid "" -"Returns the key that follows *key* in the traversal. The following code " -"prints every key in the database ``db``, without having to create a list in " -"memory that contains them all::" -msgstr "" - -#: ../../library/dbm.rst:305 -msgid "" -"k = db.firstkey()\n" -"while k is not None:\n" -" print(k)\n" -" k = db.nextkey(k)" -msgstr "" -"k = db.firstkey()\n" -"while k is not None:\n" -" print(k)\n" -" k = db.nextkey(k)" - -#: ../../library/dbm.rst:312 -msgid "" -"If you have carried out a lot of deletions and would like to shrink the " -"space used by the GDBM file, this routine will reorganize the database. :" -"class:`!gdbm` objects will not shorten the length of a database file except " -"by using this reorganization; otherwise, deleted file space will be kept and " -"reused as new (key, value) pairs are added." -msgstr "" - -#: ../../library/dbm.rst:320 -msgid "" -"When the database has been opened in fast mode, this method forces any " -"unwritten data to be written to the disk." -msgstr "" - -#: ../../library/dbm.rst:325 -msgid ":mod:`dbm.ndbm` --- New Database Manager" -msgstr ":mod:`dbm.ndbm` --- 新資料庫管理器" - -#: ../../library/dbm.rst:331 -msgid "**Source code:** :source:`Lib/dbm/ndbm.py`" -msgstr "**原始碼：**\\ :source:`Lib/dbm/ndbm.py`" - -#: ../../library/dbm.rst:335 -msgid "" -"The :mod:`dbm.ndbm` module provides an interface to the :abbr:`NDBM (New " -"Database Manager)` library. This module can be used with the \"classic\" " -"NDBM interface or the :abbr:`GDBM (GNU dbm)` compatibility interface." -msgstr "" - -#: ../../library/dbm.rst:347 -msgid "" -"The NDBM library shipped as part of macOS has an undocumented limitation on " -"the size of values, which can result in corrupted database files when " -"storing values larger than this limit. Reading such corrupted files can " -"result in a hard crash (segmentation fault)." -msgstr "" - -#: ../../library/dbm.rst:356 -msgid "" -"Raised on :mod:`dbm.ndbm`-specific errors, such as I/O errors. :exc:" -"`KeyError` is raised for general mapping errors like specifying an incorrect " -"key." -msgstr "" - -#: ../../library/dbm.rst:362 -msgid "Name of the NDBM implementation library used." -msgstr "" - -#: ../../library/dbm.rst:367 -msgid "Open an NDBM database and return an :class:`!ndbm` object." -msgstr "" - -#: ../../library/dbm.rst:369 -msgid "" -"The basename of the database file (without the :file:`.dir` or :file:`.pag` " -"extensions)." -msgstr "" - -#: ../../library/dbm.rst:383 -msgid "Accepts :term:`path-like object` for filename." -msgstr "" - -#: ../../library/dbm.rst:386 -msgid "" -":class:`!ndbm` objects behave similar to mutable :term:`mappings `, " -"but methods :meth:`!items`, :meth:`!values`, :meth:`!pop`, :meth:`!popitem`, " -"and :meth:`!update` are not supported, the :meth:`!keys` method returns a " -"list, and the :meth:`!setdefault` method requires two arguments. It also " -"supports a \"closing\" context manager via the :keyword:`with` keyword." -msgstr "" - -#: ../../library/dbm.rst:403 -msgid "Close the NDBM database." -msgstr "關閉 NDBM 資料庫。" - -#: ../../library/dbm.rst:407 -msgid ":mod:`dbm.dumb` --- Portable DBM implementation" -msgstr ":mod:`dbm.dumb` --- 可攜式 DBM 實作" - -#: ../../library/dbm.rst:412 -msgid "**Source code:** :source:`Lib/dbm/dumb.py`" -msgstr "**原始碼：**\\ :source:`Lib/dbm/dumb.py`" - -#: ../../library/dbm.rst:418 -msgid "" -"The :mod:`dbm.dumb` module is intended as a last resort fallback for the :" -"mod:`dbm` module when a more robust module is not available. The :mod:`dbm." -"dumb` module is not written for speed and is not nearly as heavily used as " -"the other database modules." -msgstr "" - -#: ../../library/dbm.rst:425 -msgid "" -"The :mod:`dbm.dumb` module provides a persistent :class:`dict`-like " -"interface which is written entirely in Python. Unlike other :mod:`dbm` " -"backends, such as :mod:`dbm.gnu`, no external library is required." -msgstr "" - -#: ../../library/dbm.rst:430 -msgid "The :mod:`!dbm.dumb` module defines the following:" -msgstr ":mod:`!dbm.dumb` 模組定義了以下項目：" - -#: ../../library/dbm.rst:434 -msgid "" -"Raised on :mod:`dbm.dumb`-specific errors, such as I/O errors. :exc:" -"`KeyError` is raised for general mapping errors like specifying an incorrect " -"key." -msgstr "" - -#: ../../library/dbm.rst:440 -msgid "Open a :mod:`!dbm.dumb` database." -msgstr "開啟一個 :mod:`!dbm.dumb` 資料庫。" - -#: ../../library/dbm.rst:442 -msgid "" -"The basename of the database file (without extensions). A new database " -"creates the following files: - :file:`{filename}.dat` - :file:`{filename}." -"dir`" -msgstr "" - -#: ../../library/dbm.rst:443 -msgid "" -"The basename of the database file (without extensions). A new database " -"creates the following files:" -msgstr "" - -#: ../../library/dbm.rst:446 -msgid ":file:`{filename}.dat`" -msgstr ":file:`{filename}.dat`" - -#: ../../library/dbm.rst:447 -msgid ":file:`{filename}.dir`" -msgstr ":file:`{filename}.dir`" - -#: ../../library/dbm.rst:450 -msgid "" -"* ``'r'``: |flag_r| * ``'w'``: |flag_w| * ``'c'`` (default): |flag_c| * " -"``'n'``: |flag_n|" -msgstr "" -"* ``'r'``: |flag_r| * ``'w'``: |flag_w| * ``'c'`` (default): |flag_c| * " -"``'n'``: |flag_n|" - -#: ../../library/dbm.rst:451 -msgid "``'r'``: |flag_r|" -msgstr "``'r'``: |flag_r|" - -#: ../../library/dbm.rst:453 -msgid "``'c'`` (default): |flag_c|" -msgstr "``'c'`` (default): |flag_c|" - -#: ../../library/dbm.rst:460 -msgid "" -"It is possible to crash the Python interpreter when loading a database with " -"a sufficiently large/complex entry due to stack depth limitations in " -"Python's AST compiler." -msgstr "" - -#: ../../library/dbm.rst:464 -msgid "" -":func:`~dbm.dumb.open` always creates a new database when *flag* is ``'n'``." -msgstr "" - -#: ../../library/dbm.rst:467 -msgid "" -"A database opened read-only if *flag* is ``'r'``. A database is not created " -"if it does not exist if *flag* is ``'r'`` or ``'w'``." -msgstr "" - -#: ../../library/dbm.rst:474 -msgid "" -"The returned database object behaves similar to a mutable :term:`mapping`, " -"but the :meth:`!keys` and :meth:`!items` methods return lists, and the :meth:" -"`!setdefault` method requires two arguments. It also supports a \"closing\" " -"context manager via the :keyword:`with` keyword." -msgstr "" - -#: ../../library/dbm.rst:483 -msgid "Close the database." -msgstr "關閉資料庫。" - -#: ../../library/dbm.rst:487 -msgid "" -"Synchronize the on-disk directory and data files. This method is called by " -"the :meth:`shelve.Shelf.sync` method." -msgstr "" - -#: ../../library/dbm.rst:414 -msgid "databases" -msgstr "databases（資料庫）" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# jerrychen , 2016 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-10-08 00:15+0000\n" +"PO-Revision-Date: 2018-05-23 14:42+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/dbm.rst:2 +msgid ":mod:`!dbm` --- Interfaces to Unix \"databases\"" +msgstr ":mod:`!dbm` --- Unix \"databases\" 的介面" + +#: ../../library/dbm.rst:7 +msgid "**Source code:** :source:`Lib/dbm/__init__.py`" +msgstr "**原始碼：**\\ :source:`Lib/dbm/__init__.py`" + +#: ../../library/dbm.rst:11 +msgid ":mod:`dbm` is a generic interface to variants of the DBM database:" +msgstr "" + +#: ../../library/dbm.rst:13 +msgid ":mod:`dbm.sqlite3`" +msgstr ":mod:`dbm.sqlite3`" + +#: ../../library/dbm.rst:14 +msgid ":mod:`dbm.gnu`" +msgstr ":mod:`dbm.gnu`" + +#: ../../library/dbm.rst:15 +msgid ":mod:`dbm.ndbm`" +msgstr ":mod:`dbm.ndbm`" + +#: ../../library/dbm.rst:17 +msgid "" +"If none of these modules are installed, the slow-but-simple implementation " +"in module :mod:`dbm.dumb` will be used. There is a `third party interface " +"`_ to the Oracle Berkeley DB." +msgstr "" + +#: ../../library/dbm.rst:24 +msgid "" +"A tuple containing the exceptions that can be raised by each of the " +"supported modules, with a unique exception also named :exc:`dbm.error` as " +"the first item --- the latter is used when :exc:`dbm.error` is raised." +msgstr "" + +#: ../../library/dbm.rst:31 +msgid "" +"This function attempts to guess which of the several simple database modules " +"available --- :mod:`dbm.sqlite3`, :mod:`dbm.gnu`, :mod:`dbm.ndbm`, or :mod:" +"`dbm.dumb` --- should be used to open a given file." +msgstr "" + +#: ../../library/dbm.rst:35 +msgid "Return one of the following values:" +msgstr "回傳以下其中一個值：" + +#: ../../library/dbm.rst:37 +msgid "" +"``None`` if the file can't be opened because it's unreadable or doesn't exist" +msgstr "" + +#: ../../library/dbm.rst:38 +msgid "the empty string (``''``) if the file's format can't be guessed" +msgstr "" + +#: ../../library/dbm.rst:39 +msgid "" +"a string containing the required module name, such as ``'dbm.ndbm'`` or " +"``'dbm.gnu'``" +msgstr "" + +#: ../../library/dbm.rst:41 ../../library/dbm.rst:270 ../../library/dbm.rst:471 +msgid "*filename* accepts a :term:`path-like object`." +msgstr "" + +#: ../../library/dbm.rst:65 +msgid "Open a database and return the corresponding database object." +msgstr "" + +#: ../../library/dbm.rst:0 +msgid "Parameters" +msgstr "參數" + +#: ../../library/dbm.rst:67 +msgid "" +"The database file to open. If the database file already exists, the :func:" +"`whichdb` function is used to determine its type and the appropriate module " +"is used; if it does not exist, the first submodule listed above that can be " +"imported is used." +msgstr "" + +#: ../../library/dbm.rst:68 ../../library/dbm.rst:242 +msgid "The database file to open." +msgstr "要打開的資料庫檔案" + +#: ../../library/dbm.rst:70 +msgid "" +"If the database file already exists, the :func:`whichdb` function is used to " +"determine its type and the appropriate module is used; if it does not exist, " +"the first submodule listed above that can be imported is used." +msgstr "" + +#: ../../library/dbm.rst:75 ../../library/dbm.rst:182 ../../library/dbm.rst:374 +msgid "" +"* ``'r'`` (default): |flag_r| * ``'w'``: |flag_w| * ``'c'``: |flag_c| * " +"``'n'``: |flag_n|" +msgstr "" +"* ``'r'`` (default): |flag_r| * ``'w'``: |flag_w| * ``'c'``: |flag_c| * " +"``'n'``: |flag_n|" + +#: ../../library/dbm.rst:76 ../../library/dbm.rst:184 ../../library/dbm.rst:247 +#: ../../library/dbm.rst:375 +msgid "``'r'`` (default): |flag_r|" +msgstr "``'r'`` (default): |flag_r|" + +#: ../../library/dbm.rst:77 ../../library/dbm.rst:185 ../../library/dbm.rst:248 +#: ../../library/dbm.rst:376 ../../library/dbm.rst:452 +msgid "``'w'``: |flag_w|" +msgstr "``'w'``: |flag_w|" + +#: ../../library/dbm.rst:78 ../../library/dbm.rst:186 ../../library/dbm.rst:249 +#: ../../library/dbm.rst:377 +msgid "``'c'``: |flag_c|" +msgstr "``'c'``: |flag_c|" + +#: ../../library/dbm.rst:79 ../../library/dbm.rst:187 ../../library/dbm.rst:250 +#: ../../library/dbm.rst:378 ../../library/dbm.rst:454 +msgid "``'n'``: |flag_n|" +msgstr "``'n'``: |flag_n|" + +#: ../../library/dbm.rst:81 ../../library/dbm.rst:264 ../../library/dbm.rst:380 +#: ../../library/dbm.rst:456 +msgid "|mode_param_doc|" +msgstr "|mode_param_doc|" + +#: ../../library/dbm.rst:84 +msgid "*file* accepts a :term:`path-like object`." +msgstr "*file* 接受一個\\ :term:`類路徑物件 `。" + +#: ../../library/dbm.rst:87 +msgid "" +"The object returned by :func:`~dbm.open` supports the basic functionality of " +"mutable :term:`mappings `; keys and their corresponding values can " +"be stored, retrieved, and deleted, and iteration, the :keyword:`in` operator " +"and methods :meth:`!keys`, :meth:`!get`, :meth:`!setdefault` and :meth:`!" +"clear` are available. The :meth:`!keys` method returns a list instead of a " +"view object. The :meth:`!setdefault` method requires two arguments." +msgstr "" + +#: ../../library/dbm.rst:95 +msgid "" +"Key and values are always stored as :class:`bytes`. This means that when " +"strings are used they are implicitly converted to the default encoding " +"before being stored." +msgstr "" + +#: ../../library/dbm.rst:99 +msgid "" +"These objects also support being used in a :keyword:`with` statement, which " +"will automatically close them when done." +msgstr "" + +#: ../../library/dbm.rst:102 +msgid "" +":meth:`!get` and :meth:`!setdefault` methods are now available for all :mod:" +"`dbm` backends." +msgstr "" + +#: ../../library/dbm.rst:106 +msgid "" +"Added native support for the context management protocol to the objects " +"returned by :func:`~dbm.open`." +msgstr "" + +#: ../../library/dbm.rst:110 +msgid "" +"Deleting a key from a read-only database raises a database module specific " +"exception instead of :exc:`KeyError`." +msgstr "" + +#: ../../library/dbm.rst:114 +msgid ":meth:`!clear` methods are now available for all :mod:`dbm` backends." +msgstr ":meth:`!clear` 方法現在可用於所有 :mod:`dbm` 後端。" + +#: ../../library/dbm.rst:118 +msgid "" +"The following example records some hostnames and a corresponding title, and " +"then prints out the contents of the database::" +msgstr "" + +#: ../../library/dbm.rst:121 +msgid "" +"import dbm\n" +"\n" +"# Open database, creating it if necessary.\n" +"with dbm.open('cache', 'c') as db:\n" +"\n" +" # Record some values\n" +" db[b'hello'] = b'there'\n" +" db['www.python.org'] = 'Python Website'\n" +" db['www.cnn.com'] = 'Cable News Network'\n" +"\n" +" # Note that the keys are considered bytes now.\n" +" assert db[b'www.python.org'] == b'Python Website'\n" +" # Notice how the value is now in bytes.\n" +" assert db['www.cnn.com'] == b'Cable News Network'\n" +"\n" +" # Often-used methods of the dict interface work too.\n" +" print(db.get('python.org', b'not present'))\n" +"\n" +" # Storing a non-string key or value will raise an exception (most\n" +" # likely a TypeError).\n" +" db['www.yahoo.com'] = 4\n" +"\n" +"# db is automatically closed when leaving the with statement." +msgstr "" + +#: ../../library/dbm.rst:148 +msgid "Module :mod:`shelve`" +msgstr ":mod:`shelve` 模組" + +#: ../../library/dbm.rst:149 +msgid "Persistence module which stores non-string data." +msgstr "" + +#: ../../library/dbm.rst:152 +msgid "The individual submodules are described in the following sections." +msgstr "" + +#: ../../library/dbm.rst:155 +msgid ":mod:`dbm.sqlite3` --- SQLite backend for dbm" +msgstr ":mod:`dbm.sqlite3` --- dbm 的 SQLite 後端" + +#: ../../library/dbm.rst:163 +msgid "**Source code:** :source:`Lib/dbm/sqlite3.py`" +msgstr "**原始碼：**\\ :source:`Lib/dbm/sqlite3.py`" + +#: ../../library/dbm.rst:167 +msgid "" +"This module uses the standard library :mod:`sqlite3` module to provide an " +"SQLite backend for the :mod:`dbm` module. The files created by :mod:`dbm." +"sqlite3` can thus be opened by :mod:`sqlite3`, or any other SQLite browser, " +"including the SQLite CLI." +msgstr "" + +#: ../../includes/wasm-mobile-notavail.rst:3 ../../includes/wasm-notavail.rst:3 +msgid "Availability" +msgstr "可用性" + +#: ../../includes/wasm-notavail.rst:5 +msgid "" +"This module does not work or is not available on WebAssembly. See :ref:`wasm-" +"availability` for more information." +msgstr "" +"此模組在 WebAssembly 平台上不起作用或無法使用。更多資訊請參閱 :ref:`wasm-" +"availability`。" + +#: ../../library/dbm.rst:176 +msgid "Open an SQLite database." +msgstr "打開一個 SQLite 資料庫。" + +#: ../../library/dbm.rst:178 +msgid "The path to the database to be opened." +msgstr "要打開的資料庫路徑" + +#: ../../library/dbm.rst:189 +msgid "" +"The Unix file access mode of the file (default: octal ``0o666``), used only " +"when the database has to be created." +msgstr "" + +#: ../../library/dbm.rst:193 +msgid "" +"The returned database object behaves similar to a mutable :term:`mapping`, " +"but the :meth:`!keys` method returns a list, and the :meth:`!setdefault` " +"method requires two arguments. It also supports a \"closing\" context " +"manager via the :keyword:`with` keyword." +msgstr "" + +#: ../../library/dbm.rst:198 ../../library/dbm.rst:399 +msgid "The following method is also provided:" +msgstr "也提供了以下方法：" + +#: ../../library/dbm.rst:202 +msgid "Close the SQLite database." +msgstr "關閉 SQLite 資料庫。" + +#: ../../library/dbm.rst:206 +msgid ":mod:`dbm.gnu` --- GNU database manager" +msgstr ":mod:`dbm.gnu` --- GNU 資料庫管理器" + +#: ../../library/dbm.rst:212 +msgid "**Source code:** :source:`Lib/dbm/gnu.py`" +msgstr "**原始碼：**\\ :source:`Lib/dbm/gnu.py`" + +#: ../../library/dbm.rst:216 +msgid "" +"The :mod:`dbm.gnu` module provides an interface to the :abbr:`GDBM (GNU " +"dbm)` library, similar to the :mod:`dbm.ndbm` module, but with additional " +"functionality like crash tolerance." +msgstr "" + +#: ../../library/dbm.rst:222 ../../library/dbm.rst:342 +msgid "" +"The file formats created by :mod:`dbm.gnu` and :mod:`dbm.ndbm` are " +"incompatible and can not be used interchangeably." +msgstr "" + +#: ../../includes/wasm-mobile-notavail.rst:5 +msgid "" +"This module is not supported on :ref:`mobile platforms ` or :ref:`WebAssembly platforms `." +msgstr "" +"此模組在\\ :ref:`行動平台 `\\ 或 :ref:`WebAssembly 平" +"台 `\\ 上不支援。" + +#: ../../library/dbm.rst:229 +msgid "" +"Raised on :mod:`dbm.gnu`-specific errors, such as I/O errors. :exc:" +"`KeyError` is raised for general mapping errors like specifying an incorrect " +"key." +msgstr "" + +#: ../../library/dbm.rst:235 +msgid "" +"A string of characters the *flag* parameter of :meth:`~dbm.gnu.open` " +"supports." +msgstr "" + +#: ../../library/dbm.rst:240 +msgid "Open a GDBM database and return a :class:`!gdbm` object." +msgstr "打開一個 GDBM 資料庫，並回傳一個 :class:`!gdbm` 物件。" + +#: ../../library/dbm.rst:246 +msgid "" +"* ``'r'`` (default): |flag_r| * ``'w'``: |flag_w| * ``'c'``: |flag_c| * " +"``'n'``: |flag_n| The following additional characters may be appended to " +"control how the database is opened: * ``'f'``: Open the database in fast " +"mode. Writes to the database will not be synchronized. * ``'s'``: " +"Synchronized mode. Changes to the database will be written immediately to " +"the file. * ``'u'``: Do not lock database. Not all flags are valid for all " +"versions of GDBM. See the :data:`open_flags` member for a list of supported " +"flag characters." +msgstr "" + +#: ../../library/dbm.rst:252 +msgid "" +"The following additional characters may be appended to control how the " +"database is opened:" +msgstr "" + +#: ../../library/dbm.rst:255 +msgid "" +"``'f'``: Open the database in fast mode. Writes to the database will not be " +"synchronized." +msgstr "" + +#: ../../library/dbm.rst:257 +msgid "" +"``'s'``: Synchronized mode. Changes to the database will be written " +"immediately to the file." +msgstr "" + +#: ../../library/dbm.rst:259 +msgid "``'u'``: Do not lock database." +msgstr "``'u'``: 不要鎖住資料庫。" + +#: ../../library/dbm.rst:261 +msgid "" +"Not all flags are valid for all versions of GDBM. See the :data:`open_flags` " +"member for a list of supported flag characters." +msgstr "" + +#: ../../library/dbm.rst:0 +msgid "Raises" +msgstr "引發" + +#: ../../library/dbm.rst:267 +msgid "If an invalid *flag* argument is passed." +msgstr "如果一個無效的 *flag* 引數被傳入。" + +#: ../../library/dbm.rst:273 +msgid "" +":class:`!gdbm` objects behave similar to mutable :term:`mappings `, " +"but methods :meth:`!items`, :meth:`!values`, :meth:`!pop`, :meth:`!popitem`, " +"and :meth:`!update` are not supported, the :meth:`!keys` method returns a " +"list, and the :meth:`!setdefault` method requires two arguments. It also " +"supports a \"closing\" context manager via the :keyword:`with` keyword." +msgstr "" + +#: ../../library/dbm.rst:280 ../../library/dbm.rst:393 +msgid "Added the :meth:`!get` and :meth:`!setdefault` methods." +msgstr "新增了 :meth:`!get` 和 :meth:`!setdefault` 方法。" + +#: ../../library/dbm.rst:283 ../../library/dbm.rst:396 +msgid "Added the :meth:`!clear` method." +msgstr "新增了 :meth:`!clear` 方法。" + +#: ../../library/dbm.rst:286 ../../library/dbm.rst:479 +msgid "The following methods are also provided:" +msgstr "也提供了以下方法：" + +#: ../../library/dbm.rst:290 +msgid "Close the GDBM database." +msgstr "關閉 GDBM 資料庫。" + +#: ../../library/dbm.rst:294 +msgid "" +"It's possible to loop over every key in the database using this method and " +"the :meth:`nextkey` method. The traversal is ordered by GDBM's internal " +"hash values, and won't be sorted by the key values. This method returns the " +"starting key." +msgstr "" + +#: ../../library/dbm.rst:301 +msgid "" +"Returns the key that follows *key* in the traversal. The following code " +"prints every key in the database ``db``, without having to create a list in " +"memory that contains them all::" +msgstr "" + +#: ../../library/dbm.rst:305 +msgid "" +"k = db.firstkey()\n" +"while k is not None:\n" +" print(k)\n" +" k = db.nextkey(k)" +msgstr "" +"k = db.firstkey()\n" +"while k is not None:\n" +" print(k)\n" +" k = db.nextkey(k)" + +#: ../../library/dbm.rst:312 +msgid "" +"If you have carried out a lot of deletions and would like to shrink the " +"space used by the GDBM file, this routine will reorganize the database. :" +"class:`!gdbm` objects will not shorten the length of a database file except " +"by using this reorganization; otherwise, deleted file space will be kept and " +"reused as new (key, value) pairs are added." +msgstr "" + +#: ../../library/dbm.rst:320 +msgid "" +"When the database has been opened in fast mode, this method forces any " +"unwritten data to be written to the disk." +msgstr "" + +#: ../../library/dbm.rst:325 +msgid ":mod:`dbm.ndbm` --- New Database Manager" +msgstr ":mod:`dbm.ndbm` --- 新資料庫管理器" + +#: ../../library/dbm.rst:331 +msgid "**Source code:** :source:`Lib/dbm/ndbm.py`" +msgstr "**原始碼：**\\ :source:`Lib/dbm/ndbm.py`" + +#: ../../library/dbm.rst:335 +msgid "" +"The :mod:`dbm.ndbm` module provides an interface to the :abbr:`NDBM (New " +"Database Manager)` library. This module can be used with the \"classic\" " +"NDBM interface or the :abbr:`GDBM (GNU dbm)` compatibility interface." +msgstr "" + +#: ../../library/dbm.rst:347 +msgid "" +"The NDBM library shipped as part of macOS has an undocumented limitation on " +"the size of values, which can result in corrupted database files when " +"storing values larger than this limit. Reading such corrupted files can " +"result in a hard crash (segmentation fault)." +msgstr "" + +#: ../../library/dbm.rst:356 +msgid "" +"Raised on :mod:`dbm.ndbm`-specific errors, such as I/O errors. :exc:" +"`KeyError` is raised for general mapping errors like specifying an incorrect " +"key." +msgstr "" + +#: ../../library/dbm.rst:362 +msgid "Name of the NDBM implementation library used." +msgstr "" + +#: ../../library/dbm.rst:367 +msgid "Open an NDBM database and return an :class:`!ndbm` object." +msgstr "" + +#: ../../library/dbm.rst:369 +msgid "" +"The basename of the database file (without the :file:`.dir` or :file:`.pag` " +"extensions)." +msgstr "" + +#: ../../library/dbm.rst:383 +msgid "Accepts :term:`path-like object` for filename." +msgstr "" + +#: ../../library/dbm.rst:386 +msgid "" +":class:`!ndbm` objects behave similar to mutable :term:`mappings `, " +"but methods :meth:`!items`, :meth:`!values`, :meth:`!pop`, :meth:`!popitem`, " +"and :meth:`!update` are not supported, the :meth:`!keys` method returns a " +"list, and the :meth:`!setdefault` method requires two arguments. It also " +"supports a \"closing\" context manager via the :keyword:`with` keyword." +msgstr "" + +#: ../../library/dbm.rst:403 +msgid "Close the NDBM database." +msgstr "關閉 NDBM 資料庫。" + +#: ../../library/dbm.rst:407 +msgid ":mod:`dbm.dumb` --- Portable DBM implementation" +msgstr ":mod:`dbm.dumb` --- 可攜式 DBM 實作" + +#: ../../library/dbm.rst:412 +msgid "**Source code:** :source:`Lib/dbm/dumb.py`" +msgstr "**原始碼：**\\ :source:`Lib/dbm/dumb.py`" + +#: ../../library/dbm.rst:418 +msgid "" +"The :mod:`dbm.dumb` module is intended as a last resort fallback for the :" +"mod:`dbm` module when a more robust module is not available. The :mod:`dbm." +"dumb` module is not written for speed and is not nearly as heavily used as " +"the other database modules." +msgstr "" + +#: ../../library/dbm.rst:425 +msgid "" +"The :mod:`dbm.dumb` module provides a persistent :class:`dict`-like " +"interface which is written entirely in Python. Unlike other :mod:`dbm` " +"backends, such as :mod:`dbm.gnu`, no external library is required." +msgstr "" + +#: ../../library/dbm.rst:430 +msgid "The :mod:`!dbm.dumb` module defines the following:" +msgstr ":mod:`!dbm.dumb` 模組定義了以下項目：" + +#: ../../library/dbm.rst:434 +msgid "" +"Raised on :mod:`dbm.dumb`-specific errors, such as I/O errors. :exc:" +"`KeyError` is raised for general mapping errors like specifying an incorrect " +"key." +msgstr "" + +#: ../../library/dbm.rst:440 +msgid "Open a :mod:`!dbm.dumb` database." +msgstr "開啟一個 :mod:`!dbm.dumb` 資料庫。" + +#: ../../library/dbm.rst:442 +msgid "" +"The basename of the database file (without extensions). A new database " +"creates the following files: - :file:`{filename}.dat` - :file:`{filename}." +"dir`" +msgstr "" + +#: ../../library/dbm.rst:443 +msgid "" +"The basename of the database file (without extensions). A new database " +"creates the following files:" +msgstr "" + +#: ../../library/dbm.rst:446 +msgid ":file:`{filename}.dat`" +msgstr ":file:`{filename}.dat`" + +#: ../../library/dbm.rst:447 +msgid ":file:`{filename}.dir`" +msgstr ":file:`{filename}.dir`" + +#: ../../library/dbm.rst:450 +msgid "" +"* ``'r'``: |flag_r| * ``'w'``: |flag_w| * ``'c'`` (default): |flag_c| * " +"``'n'``: |flag_n|" +msgstr "" +"* ``'r'``: |flag_r| * ``'w'``: |flag_w| * ``'c'`` (default): |flag_c| * " +"``'n'``: |flag_n|" + +#: ../../library/dbm.rst:451 +msgid "``'r'``: |flag_r|" +msgstr "``'r'``: |flag_r|" + +#: ../../library/dbm.rst:453 +msgid "``'c'`` (default): |flag_c|" +msgstr "``'c'`` (default): |flag_c|" + +#: ../../library/dbm.rst:460 +msgid "" +"It is possible to crash the Python interpreter when loading a database with " +"a sufficiently large/complex entry due to stack depth limitations in " +"Python's AST compiler." +msgstr "" + +#: ../../library/dbm.rst:464 +msgid "" +":func:`~dbm.dumb.open` always creates a new database when *flag* is ``'n'``." +msgstr "" + +#: ../../library/dbm.rst:467 +msgid "" +"A database opened read-only if *flag* is ``'r'``. A database is not created " +"if it does not exist if *flag* is ``'r'`` or ``'w'``." +msgstr "" + +#: ../../library/dbm.rst:474 +msgid "" +"The returned database object behaves similar to a mutable :term:`mapping`, " +"but the :meth:`!keys` and :meth:`!items` methods return lists, and the :meth:" +"`!setdefault` method requires two arguments. It also supports a \"closing\" " +"context manager via the :keyword:`with` keyword." +msgstr "" + +#: ../../library/dbm.rst:483 +msgid "Close the database." +msgstr "關閉資料庫。" + +#: ../../library/dbm.rst:487 +msgid "" +"Synchronize the on-disk directory and data files. This method is called by " +"the :meth:`shelve.Shelf.sync` method." +msgstr "" + +#: ../../library/dbm.rst:414 +msgid "databases" +msgstr "databases（資料庫）" diff --git a/library/debug.po b/library/debug.po index 17ff8f43ed..dfdf76d67e 100644 --- a/library/debug.po +++ b/library/debug.po @@ -1,39 +1,39 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Liang-Bo Wang , 2015 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2020-06-20 18:08+0800\n" -"PO-Revision-Date: 2021-12-08 00:47+0800\n" -"Last-Translator: Jordan Su \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" -"X-Generator: Poedit 3.0\n" - -#: ../../library/debug.rst:3 -msgid "Debugging and Profiling" -msgstr "除錯與效能分析" - -#: ../../library/debug.rst:5 -msgid "" -"These libraries help you with Python development: the debugger enables you " -"to step through code, analyze stack frames and set breakpoints etc., and the " -"profilers run code and give you a detailed breakdown of execution times, " -"allowing you to identify bottlenecks in your programs. Auditing events " -"provide visibility into runtime behaviors that would otherwise require " -"intrusive debugging or patching." -msgstr "" -"這些函式庫幫助你進行 Python 程式開發：除錯器允許你在程式碼中單步 (step) 執" -"行、分析堆疊框 (stack frames) 以及設置中斷點 (breakpoints) 等，效能分析工具執" -"行程式碼並提供關於執行時間的詳細分析，讓你找到程式中的瓶頸 (bottlenecks)。事" -"件稽核 (auditing events) 提供執行時期行為的可見性，否則的話可能需要更侵入性的" -"除錯或修補。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Liang-Bo Wang , 2015 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2020-06-20 18:08+0800\n" +"PO-Revision-Date: 2021-12-08 00:47+0800\n" +"Last-Translator: Jordan Su \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" +"X-Generator: Poedit 3.0\n" + +#: ../../library/debug.rst:3 +msgid "Debugging and Profiling" +msgstr "除錯與效能分析" + +#: ../../library/debug.rst:5 +msgid "" +"These libraries help you with Python development: the debugger enables you " +"to step through code, analyze stack frames and set breakpoints etc., and the " +"profilers run code and give you a detailed breakdown of execution times, " +"allowing you to identify bottlenecks in your programs. Auditing events " +"provide visibility into runtime behaviors that would otherwise require " +"intrusive debugging or patching." +msgstr "" +"這些函式庫幫助你進行 Python 程式開發：除錯器允許你在程式碼中單步 (step) 執" +"行、分析堆疊框 (stack frames) 以及設置中斷點 (breakpoints) 等，效能分析工具執" +"行程式碼並提供關於執行時間的詳細分析，讓你找到程式中的瓶頸 (bottlenecks)。事" +"件稽核 (auditing events) 提供執行時期行為的可見性，否則的話可能需要更侵入性的" +"除錯或修補。" diff --git a/library/decimal.po b/library/decimal.po index 919d7811ca..763610d9b0 100644 --- a/library/decimal.po +++ b/library/decimal.po @@ -1,2955 +1,2955 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-12-17 17:02+0000\n" -"PO-Revision-Date: 2018-05-23 14:43+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/decimal.rst:2 -msgid ":mod:`!decimal` --- Decimal fixed-point and floating-point arithmetic" -msgstr ":mod:`!decimal` --- 十進位固定點和浮點運算" - -#: ../../library/decimal.rst:15 -msgid "**Source code:** :source:`Lib/decimal.py`" -msgstr "**原始碼：**\\ :source:`Lib/decimal.py`" - -#: ../../library/decimal.rst:33 -msgid "" -"The :mod:`decimal` module provides support for fast correctly rounded " -"decimal floating-point arithmetic. It offers several advantages over the :" -"class:`float` datatype:" -msgstr "" - -#: ../../library/decimal.rst:37 -msgid "" -"Decimal \"is based on a `floating-point model `__ which was designed with people in mind, " -"and necessarily has a paramount guiding principle -- computers must provide " -"an arithmetic that works in the same way as the arithmetic that people learn " -"at school.\" -- excerpt from the decimal arithmetic specification." -msgstr "" - -#: ../../library/decimal.rst:44 -msgid "" -"Decimal numbers can be represented exactly. In contrast, numbers like " -"``1.1`` and ``2.2`` do not have exact representations in binary floating " -"point. End users typically would not expect ``1.1 + 2.2`` to display as " -"``3.3000000000000003`` as it does with binary floating point." -msgstr "" - -#: ../../library/decimal.rst:49 -msgid "" -"The exactness carries over into arithmetic. In decimal floating point, " -"``0.1 + 0.1 + 0.1 - 0.3`` is exactly equal to zero. In binary floating " -"point, the result is ``5.5511151231257827e-017``. While near to zero, the " -"differences prevent reliable equality testing and differences can " -"accumulate. For this reason, decimal is preferred in accounting applications " -"which have strict equality invariants." -msgstr "" - -#: ../../library/decimal.rst:56 -msgid "" -"The decimal module incorporates a notion of significant places so that " -"``1.30 + 1.20`` is ``2.50``. The trailing zero is kept to indicate " -"significance. This is the customary presentation for monetary applications. " -"For multiplication, the \"schoolbook\" approach uses all the figures in the " -"multiplicands. For instance, ``1.3 * 1.2`` gives ``1.56`` while ``1.30 * " -"1.20`` gives ``1.5600``." -msgstr "" - -#: ../../library/decimal.rst:63 -msgid "" -"Unlike hardware based binary floating point, the decimal module has a user " -"alterable precision (defaulting to 28 places) which can be as large as " -"needed for a given problem:" -msgstr "" - -#: ../../library/decimal.rst:75 -msgid "" -"Both binary and decimal floating point are implemented in terms of published " -"standards. While the built-in float type exposes only a modest portion of " -"its capabilities, the decimal module exposes all required parts of the " -"standard. When needed, the programmer has full control over rounding and " -"signal handling. This includes an option to enforce exact arithmetic by " -"using exceptions to block any inexact operations." -msgstr "" - -#: ../../library/decimal.rst:82 -msgid "" -"The decimal module was designed to support \"without prejudice, both exact " -"unrounded decimal arithmetic (sometimes called fixed-point arithmetic) and " -"rounded floating-point arithmetic.\" -- excerpt from the decimal arithmetic " -"specification." -msgstr "" - -#: ../../library/decimal.rst:87 -msgid "" -"The module design is centered around three concepts: the decimal number, " -"the context for arithmetic, and signals." -msgstr "" - -#: ../../library/decimal.rst:90 -msgid "" -"A decimal number is immutable. It has a sign, coefficient digits, and an " -"exponent. To preserve significance, the coefficient digits do not truncate " -"trailing zeros. Decimals also include special values such as ``Infinity``, " -"``-Infinity``, and ``NaN``. The standard also differentiates ``-0`` from " -"``+0``." -msgstr "" - -#: ../../library/decimal.rst:96 -msgid "" -"The context for arithmetic is an environment specifying precision, rounding " -"rules, limits on exponents, flags indicating the results of operations, and " -"trap enablers which determine whether signals are treated as exceptions. " -"Rounding options include :const:`ROUND_CEILING`, :const:`ROUND_DOWN`, :const:" -"`ROUND_FLOOR`, :const:`ROUND_HALF_DOWN`, :const:`ROUND_HALF_EVEN`, :const:" -"`ROUND_HALF_UP`, :const:`ROUND_UP`, and :const:`ROUND_05UP`." -msgstr "" - -#: ../../library/decimal.rst:103 -msgid "" -"Signals are groups of exceptional conditions arising during the course of " -"computation. Depending on the needs of the application, signals may be " -"ignored, considered as informational, or treated as exceptions. The signals " -"in the decimal module are: :const:`Clamped`, :const:`InvalidOperation`, :" -"const:`DivisionByZero`, :const:`Inexact`, :const:`Rounded`, :const:" -"`Subnormal`, :const:`Overflow`, :const:`Underflow` and :const:" -"`FloatOperation`." -msgstr "" - -#: ../../library/decimal.rst:110 -msgid "" -"For each signal there is a flag and a trap enabler. When a signal is " -"encountered, its flag is set to one, then, if the trap enabler is set to " -"one, an exception is raised. Flags are sticky, so the user needs to reset " -"them before monitoring a calculation." -msgstr "" - -#: ../../library/decimal.rst:118 -msgid "" -"IBM's General Decimal Arithmetic Specification, `The General Decimal " -"Arithmetic Specification `_." -msgstr "" - -#: ../../library/decimal.rst:127 -msgid "Quick-start tutorial" -msgstr "" - -#: ../../library/decimal.rst:129 -msgid "" -"The usual start to using decimals is importing the module, viewing the " -"current context with :func:`getcontext` and, if necessary, setting new " -"values for precision, rounding, or enabled traps::" -msgstr "" - -#: ../../library/decimal.rst:133 -msgid "" -">>> from decimal import *\n" -">>> getcontext()\n" -"Context(prec=28, rounding=ROUND_HALF_EVEN, Emin=-999999, Emax=999999,\n" -" capitals=1, clamp=0, flags=[], traps=[Overflow, DivisionByZero,\n" -" InvalidOperation])\n" -"\n" -">>> getcontext().prec = 7 # Set a new precision" -msgstr "" - -#: ../../library/decimal.rst:141 -msgid "" -"Decimal instances can be constructed from integers, strings, floats, or " -"tuples. Construction from an integer or a float performs an exact conversion " -"of the value of that integer or float. Decimal numbers include special " -"values such as ``NaN`` which stands for \"Not a number\", positive and " -"negative ``Infinity``, and ``-0``::" -msgstr "" - -#: ../../library/decimal.rst:147 -msgid "" -">>> getcontext().prec = 28\n" -">>> Decimal(10)\n" -"Decimal('10')\n" -">>> Decimal('3.14')\n" -"Decimal('3.14')\n" -">>> Decimal(3.14)\n" -"Decimal('3.140000000000000124344978758017532527446746826171875')\n" -">>> Decimal((0, (3, 1, 4), -2))\n" -"Decimal('3.14')\n" -">>> Decimal(str(2.0 ** 0.5))\n" -"Decimal('1.4142135623730951')\n" -">>> Decimal(2) ** Decimal('0.5')\n" -"Decimal('1.414213562373095048801688724')\n" -">>> Decimal('NaN')\n" -"Decimal('NaN')\n" -">>> Decimal('-Infinity')\n" -"Decimal('-Infinity')" -msgstr "" -">>> getcontext().prec = 28\n" -">>> Decimal(10)\n" -"Decimal('10')\n" -">>> Decimal('3.14')\n" -"Decimal('3.14')\n" -">>> Decimal(3.14)\n" -"Decimal('3.140000000000000124344978758017532527446746826171875')\n" -">>> Decimal((0, (3, 1, 4), -2))\n" -"Decimal('3.14')\n" -">>> Decimal(str(2.0 ** 0.5))\n" -"Decimal('1.4142135623730951')\n" -">>> Decimal(2) ** Decimal('0.5')\n" -"Decimal('1.414213562373095048801688724')\n" -">>> Decimal('NaN')\n" -"Decimal('NaN')\n" -">>> Decimal('-Infinity')\n" -"Decimal('-Infinity')" - -#: ../../library/decimal.rst:165 -msgid "" -"If the :exc:`FloatOperation` signal is trapped, accidental mixing of " -"decimals and floats in constructors or ordering comparisons raises an " -"exception::" -msgstr "" - -#: ../../library/decimal.rst:169 -msgid "" -">>> c = getcontext()\n" -">>> c.traps[FloatOperation] = True\n" -">>> Decimal(3.14)\n" -"Traceback (most recent call last):\n" -" File \"\", line 1, in \n" -"decimal.FloatOperation: []\n" -">>> Decimal('3.5') < 3.7\n" -"Traceback (most recent call last):\n" -" File \"\", line 1, in \n" -"decimal.FloatOperation: []\n" -">>> Decimal('3.5') == 3.5\n" -"True" -msgstr "" -">>> c = getcontext()\n" -">>> c.traps[FloatOperation] = True\n" -">>> Decimal(3.14)\n" -"Traceback (most recent call last):\n" -" File \"\", line 1, in \n" -"decimal.FloatOperation: []\n" -">>> Decimal('3.5') < 3.7\n" -"Traceback (most recent call last):\n" -" File \"\", line 1, in \n" -"decimal.FloatOperation: []\n" -">>> Decimal('3.5') == 3.5\n" -"True" - -#: ../../library/decimal.rst:184 -msgid "" -"The significance of a new Decimal is determined solely by the number of " -"digits input. Context precision and rounding only come into play during " -"arithmetic operations." -msgstr "" - -#: ../../library/decimal.rst:188 -msgid "" -">>> getcontext().prec = 6\n" -">>> Decimal('3.0')\n" -"Decimal('3.0')\n" -">>> Decimal('3.1415926535')\n" -"Decimal('3.1415926535')\n" -">>> Decimal('3.1415926535') + Decimal('2.7182818285')\n" -"Decimal('5.85987')\n" -">>> getcontext().rounding = ROUND_UP\n" -">>> Decimal('3.1415926535') + Decimal('2.7182818285')\n" -"Decimal('5.85988')" -msgstr "" -">>> getcontext().prec = 6\n" -">>> Decimal('3.0')\n" -"Decimal('3.0')\n" -">>> Decimal('3.1415926535')\n" -"Decimal('3.1415926535')\n" -">>> Decimal('3.1415926535') + Decimal('2.7182818285')\n" -"Decimal('5.85987')\n" -">>> getcontext().rounding = ROUND_UP\n" -">>> Decimal('3.1415926535') + Decimal('2.7182818285')\n" -"Decimal('5.85988')" - -#: ../../library/decimal.rst:201 -msgid "" -"If the internal limits of the C version are exceeded, constructing a decimal " -"raises :class:`InvalidOperation`::" -msgstr "" - -#: ../../library/decimal.rst:204 -msgid "" -">>> Decimal(\"1e9999999999999999999\")\n" -"Traceback (most recent call last):\n" -" File \"\", line 1, in \n" -"decimal.InvalidOperation: []" -msgstr "" -">>> Decimal(\"1e9999999999999999999\")\n" -"Traceback (most recent call last):\n" -" File \"\", line 1, in \n" -"decimal.InvalidOperation: []" - -#: ../../library/decimal.rst:211 -msgid "" -"Decimals interact well with much of the rest of Python. Here is a small " -"decimal floating-point flying circus:" -msgstr "" - -#: ../../library/decimal.rst:214 -msgid "" -">>> data = list(map(Decimal, '1.34 1.87 3.45 2.35 1.00 0.03 9.25'.split()))\n" -">>> max(data)\n" -"Decimal('9.25')\n" -">>> min(data)\n" -"Decimal('0.03')\n" -">>> sorted(data)\n" -"[Decimal('0.03'), Decimal('1.00'), Decimal('1.34'), Decimal('1.87'),\n" -" Decimal('2.35'), Decimal('3.45'), Decimal('9.25')]\n" -">>> sum(data)\n" -"Decimal('19.29')\n" -">>> a,b,c = data[:3]\n" -">>> str(a)\n" -"'1.34'\n" -">>> float(a)\n" -"1.34\n" -">>> round(a, 1)\n" -"Decimal('1.3')\n" -">>> int(a)\n" -"1\n" -">>> a * 5\n" -"Decimal('6.70')\n" -">>> a * b\n" -"Decimal('2.5058')\n" -">>> c % a\n" -"Decimal('0.77')" -msgstr "" -">>> data = list(map(Decimal, '1.34 1.87 3.45 2.35 1.00 0.03 9.25'.split()))\n" -">>> max(data)\n" -"Decimal('9.25')\n" -">>> min(data)\n" -"Decimal('0.03')\n" -">>> sorted(data)\n" -"[Decimal('0.03'), Decimal('1.00'), Decimal('1.34'), Decimal('1.87'),\n" -" Decimal('2.35'), Decimal('3.45'), Decimal('9.25')]\n" -">>> sum(data)\n" -"Decimal('19.29')\n" -">>> a,b,c = data[:3]\n" -">>> str(a)\n" -"'1.34'\n" -">>> float(a)\n" -"1.34\n" -">>> round(a, 1)\n" -"Decimal('1.3')\n" -">>> int(a)\n" -"1\n" -">>> a * 5\n" -"Decimal('6.70')\n" -">>> a * b\n" -"Decimal('2.5058')\n" -">>> c % a\n" -"Decimal('0.77')" - -#: ../../library/decimal.rst:243 -msgid "" -"Decimals can be formatted (with :func:`format` built-in or :ref:`f-strings`) " -"in fixed-point or scientific notation, using the same formatting syntax " -"(see :ref:`formatspec`) as builtin :class:`float` type:" -msgstr "" - -#: ../../library/decimal.rst:247 -msgid "" -">>> format(Decimal('2.675'), \"f\")\n" -"'2.675'\n" -">>> format(Decimal('2.675'), \".2f\")\n" -"'2.68'\n" -">>> f\"{Decimal('2.675'):.2f}\"\n" -"'2.68'\n" -">>> format(Decimal('2.675'), \".2e\")\n" -"'2.68e+0'\n" -">>> with localcontext() as ctx:\n" -"... ctx.rounding = ROUND_DOWN\n" -"... print(format(Decimal('2.675'), \".2f\"))\n" -"...\n" -"2.67" -msgstr "" - -#: ../../library/decimal.rst:263 -msgid "And some mathematical functions are also available to Decimal:" -msgstr "" - -#: ../../library/decimal.rst:275 -msgid "" -"The :meth:`~Decimal.quantize` method rounds a number to a fixed exponent. " -"This method is useful for monetary applications that often round results to " -"a fixed number of places:" -msgstr "" - -#: ../../library/decimal.rst:284 -msgid "" -"As shown above, the :func:`getcontext` function accesses the current context " -"and allows the settings to be changed. This approach meets the needs of " -"most applications." -msgstr "" - -#: ../../library/decimal.rst:288 -msgid "" -"For more advanced work, it may be useful to create alternate contexts using " -"the :meth:`Context` constructor. To make an alternate active, use the :func:" -"`setcontext` function." -msgstr "" - -#: ../../library/decimal.rst:292 -msgid "" -"In accordance with the standard, the :mod:`decimal` module provides two " -"ready to use standard contexts, :const:`BasicContext` and :const:" -"`ExtendedContext`. The former is especially useful for debugging because " -"many of the traps are enabled:" -msgstr "" - -#: ../../library/decimal.rst:297 -msgid "" -">>> myothercontext = Context(prec=60, rounding=ROUND_HALF_DOWN)\n" -">>> setcontext(myothercontext)\n" -">>> Decimal(1) / Decimal(7)\n" -"Decimal('0.142857142857142857142857142857142857142857142857142857142857')\n" -"\n" -">>> ExtendedContext\n" -"Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999, Emax=999999,\n" -" capitals=1, clamp=0, flags=[], traps=[])\n" -">>> setcontext(ExtendedContext)\n" -">>> Decimal(1) / Decimal(7)\n" -"Decimal('0.142857143')\n" -">>> Decimal(42) / Decimal(0)\n" -"Decimal('Infinity')\n" -"\n" -">>> setcontext(BasicContext)\n" -">>> Decimal(42) / Decimal(0)\n" -"Traceback (most recent call last):\n" -" File \"\", line 1, in -toplevel-\n" -" Decimal(42) / Decimal(0)\n" -"DivisionByZero: x / 0" -msgstr "" -">>> myothercontext = Context(prec=60, rounding=ROUND_HALF_DOWN)\n" -">>> setcontext(myothercontext)\n" -">>> Decimal(1) / Decimal(7)\n" -"Decimal('0.142857142857142857142857142857142857142857142857142857142857')\n" -"\n" -">>> ExtendedContext\n" -"Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999, Emax=999999,\n" -" capitals=1, clamp=0, flags=[], traps=[])\n" -">>> setcontext(ExtendedContext)\n" -">>> Decimal(1) / Decimal(7)\n" -"Decimal('0.142857143')\n" -">>> Decimal(42) / Decimal(0)\n" -"Decimal('Infinity')\n" -"\n" -">>> setcontext(BasicContext)\n" -">>> Decimal(42) / Decimal(0)\n" -"Traceback (most recent call last):\n" -" File \"\", line 1, in -toplevel-\n" -" Decimal(42) / Decimal(0)\n" -"DivisionByZero: x / 0" - -#: ../../library/decimal.rst:321 -msgid "" -"Contexts also have signal flags for monitoring exceptional conditions " -"encountered during computations. The flags remain set until explicitly " -"cleared, so it is best to clear the flags before each set of monitored " -"computations by using the :meth:`~Context.clear_flags` method. ::" -msgstr "" - -#: ../../library/decimal.rst:326 -msgid "" -">>> setcontext(ExtendedContext)\n" -">>> getcontext().clear_flags()\n" -">>> Decimal(355) / Decimal(113)\n" -"Decimal('3.14159292')\n" -">>> getcontext()\n" -"Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999, Emax=999999,\n" -" capitals=1, clamp=0, flags=[Inexact, Rounded], traps=[])" -msgstr "" -">>> setcontext(ExtendedContext)\n" -">>> getcontext().clear_flags()\n" -">>> Decimal(355) / Decimal(113)\n" -"Decimal('3.14159292')\n" -">>> getcontext()\n" -"Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999, Emax=999999,\n" -" capitals=1, clamp=0, flags=[Inexact, Rounded], traps=[])" - -#: ../../library/decimal.rst:334 -msgid "" -"The *flags* entry shows that the rational approximation to pi was rounded " -"(digits beyond the context precision were thrown away) and that the result " -"is inexact (some of the discarded digits were non-zero)." -msgstr "" - -#: ../../library/decimal.rst:338 -msgid "" -"Individual traps are set using the dictionary in the :attr:`~Context.traps` " -"attribute of a context:" -msgstr "" - -#: ../../library/decimal.rst:341 -msgid "" -">>> setcontext(ExtendedContext)\n" -">>> Decimal(1) / Decimal(0)\n" -"Decimal('Infinity')\n" -">>> getcontext().traps[DivisionByZero] = 1\n" -">>> Decimal(1) / Decimal(0)\n" -"Traceback (most recent call last):\n" -" File \"\", line 1, in -toplevel-\n" -" Decimal(1) / Decimal(0)\n" -"DivisionByZero: x / 0" -msgstr "" -">>> setcontext(ExtendedContext)\n" -">>> Decimal(1) / Decimal(0)\n" -"Decimal('Infinity')\n" -">>> getcontext().traps[DivisionByZero] = 1\n" -">>> Decimal(1) / Decimal(0)\n" -"Traceback (most recent call last):\n" -" File \"\", line 1, in -toplevel-\n" -" Decimal(1) / Decimal(0)\n" -"DivisionByZero: x / 0" - -#: ../../library/decimal.rst:353 -msgid "" -"Most programs adjust the current context only once, at the beginning of the " -"program. And, in many applications, data is converted to :class:`Decimal` " -"with a single cast inside a loop. With context set and decimals created, " -"the bulk of the program manipulates the data no differently than with other " -"Python numeric types." -msgstr "" - -#: ../../library/decimal.rst:365 -msgid "Decimal objects" -msgstr "" - -#: ../../library/decimal.rst:370 -msgid "Construct a new :class:`Decimal` object based from *value*." -msgstr "" - -#: ../../library/decimal.rst:372 -msgid "" -"*value* can be an integer, string, tuple, :class:`float`, or another :class:" -"`Decimal` object. If no *value* is given, returns ``Decimal('0')``. If " -"*value* is a string, it should conform to the decimal numeric string syntax " -"after leading and trailing whitespace characters, as well as underscores " -"throughout, are removed::" -msgstr "" - -#: ../../library/decimal.rst:377 -msgid "" -"sign ::= '+' | '-'\n" -"digit ::= '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | " -"'9'\n" -"indicator ::= 'e' | 'E'\n" -"digits ::= digit [digit]...\n" -"decimal-part ::= digits '.' [digits] | ['.'] digits\n" -"exponent-part ::= indicator [sign] digits\n" -"infinity ::= 'Infinity' | 'Inf'\n" -"nan ::= 'NaN' [digits] | 'sNaN' [digits]\n" -"numeric-value ::= decimal-part [exponent-part] | infinity\n" -"numeric-string ::= [sign] numeric-value | [sign] nan" -msgstr "" - -#: ../../library/decimal.rst:388 -msgid "" -"Other Unicode decimal digits are also permitted where ``digit`` appears " -"above. These include decimal digits from various other alphabets (for " -"example, Arabic-Indic and Devanāgarī digits) along with the fullwidth digits " -"``'\\uff10'`` through ``'\\uff19'``. Case is not significant, so, for " -"example, ``inf``, ``Inf``, ``INFINITY``, and ``iNfINity`` are all acceptable " -"spellings for positive infinity." -msgstr "" - -#: ../../library/decimal.rst:395 -msgid "" -"If *value* is a :class:`tuple`, it should have three components, a sign " -"(``0`` for positive or ``1`` for negative), a :class:`tuple` of digits, and " -"an integer exponent. For example, ``Decimal((0, (1, 4, 1, 4), -3))`` returns " -"``Decimal('1.414')``." -msgstr "" - -#: ../../library/decimal.rst:400 -msgid "" -"If *value* is a :class:`float`, the binary floating-point value is " -"losslessly converted to its exact decimal equivalent. This conversion can " -"often require 53 or more digits of precision. For example, " -"``Decimal(float('1.1'))`` converts to " -"``Decimal('1.100000000000000088817841970012523233890533447265625')``." -msgstr "" - -#: ../../library/decimal.rst:406 -msgid "" -"The *context* precision does not affect how many digits are stored. That is " -"determined exclusively by the number of digits in *value*. For example, " -"``Decimal('3.00000')`` records all five zeros even if the context precision " -"is only three." -msgstr "" - -#: ../../library/decimal.rst:411 -msgid "" -"The purpose of the *context* argument is determining what to do if *value* " -"is a malformed string. If the context traps :const:`InvalidOperation`, an " -"exception is raised; otherwise, the constructor returns a new Decimal with " -"the value of ``NaN``." -msgstr "" - -#: ../../library/decimal.rst:416 -msgid "Once constructed, :class:`Decimal` objects are immutable." -msgstr "" - -#: ../../library/decimal.rst:418 -msgid "" -"The argument to the constructor is now permitted to be a :class:`float` " -"instance." -msgstr "" - -#: ../../library/decimal.rst:422 -msgid "" -":class:`float` arguments raise an exception if the :exc:`FloatOperation` " -"trap is set. By default the trap is off." -msgstr "" - -#: ../../library/decimal.rst:426 -msgid "" -"Underscores are allowed for grouping, as with integral and floating-point " -"literals in code." -msgstr "" - -#: ../../library/decimal.rst:430 -msgid "" -"Decimal floating-point objects share many properties with the other built-in " -"numeric types such as :class:`float` and :class:`int`. All of the usual " -"math operations and special methods apply. Likewise, decimal objects can be " -"copied, pickled, printed, used as dictionary keys, used as set elements, " -"compared, sorted, and coerced to another type (such as :class:`float` or :" -"class:`int`)." -msgstr "" - -#: ../../library/decimal.rst:437 -msgid "" -"There are some small differences between arithmetic on Decimal objects and " -"arithmetic on integers and floats. When the remainder operator ``%`` is " -"applied to Decimal objects, the sign of the result is the sign of the " -"*dividend* rather than the sign of the divisor::" -msgstr "" - -#: ../../library/decimal.rst:442 -msgid "" -">>> (-7) % 4\n" -"1\n" -">>> Decimal(-7) % Decimal(4)\n" -"Decimal('-3')" -msgstr "" -">>> (-7) % 4\n" -"1\n" -">>> Decimal(-7) % Decimal(4)\n" -"Decimal('-3')" - -#: ../../library/decimal.rst:447 -msgid "" -"The integer division operator ``//`` behaves analogously, returning the " -"integer part of the true quotient (truncating towards zero) rather than its " -"floor, so as to preserve the usual identity ``x == (x // y) * y + x % y``::" -msgstr "" - -#: ../../library/decimal.rst:451 -msgid "" -">>> -7 // 4\n" -"-2\n" -">>> Decimal(-7) // Decimal(4)\n" -"Decimal('-1')" -msgstr "" -">>> -7 // 4\n" -"-2\n" -">>> Decimal(-7) // Decimal(4)\n" -"Decimal('-1')" - -#: ../../library/decimal.rst:456 -msgid "" -"The ``%`` and ``//`` operators implement the ``remainder`` and ``divide-" -"integer`` operations (respectively) as described in the specification." -msgstr "" - -#: ../../library/decimal.rst:460 -msgid "" -"Decimal objects cannot generally be combined with floats or instances of :" -"class:`fractions.Fraction` in arithmetic operations: an attempt to add a :" -"class:`Decimal` to a :class:`float`, for example, will raise a :exc:" -"`TypeError`. However, it is possible to use Python's comparison operators " -"to compare a :class:`Decimal` instance ``x`` with another number ``y``. " -"This avoids confusing results when doing equality comparisons between " -"numbers of different types." -msgstr "" - -#: ../../library/decimal.rst:468 -msgid "" -"Mixed-type comparisons between :class:`Decimal` instances and other numeric " -"types are now fully supported." -msgstr "" - -#: ../../library/decimal.rst:472 -msgid "" -"In addition to the standard numeric properties, decimal floating-point " -"objects also have a number of specialized methods:" -msgstr "" - -#: ../../library/decimal.rst:478 -msgid "" -"Return the adjusted exponent after shifting out the coefficient's rightmost " -"digits until only the lead digit remains: ``Decimal('321e+5').adjusted()`` " -"returns seven. Used for determining the position of the most significant " -"digit with respect to the decimal point." -msgstr "" - -#: ../../library/decimal.rst:485 -msgid "" -"Return a pair ``(n, d)`` of integers that represent the given :class:" -"`Decimal` instance as a fraction, in lowest terms and with a positive " -"denominator::" -msgstr "" - -#: ../../library/decimal.rst:489 -msgid "" -">>> Decimal('-3.14').as_integer_ratio()\n" -"(-157, 50)" -msgstr "" -">>> Decimal('-3.14').as_integer_ratio()\n" -"(-157, 50)" - -#: ../../library/decimal.rst:492 -msgid "" -"The conversion is exact. Raise OverflowError on infinities and ValueError " -"on NaNs." -msgstr "" - -#: ../../library/decimal.rst:499 -msgid "" -"Return a :term:`named tuple` representation of the number: " -"``DecimalTuple(sign, digits, exponent)``." -msgstr "" - -#: ../../library/decimal.rst:505 -msgid "" -"Return the canonical encoding of the argument. Currently, the encoding of " -"a :class:`Decimal` instance is always canonical, so this operation returns " -"its argument unchanged." -msgstr "" - -#: ../../library/decimal.rst:511 -msgid "" -"Compare the values of two Decimal instances. :meth:`compare` returns a " -"Decimal instance, and if either operand is a NaN then the result is a NaN::" -msgstr "" - -#: ../../library/decimal.rst:515 -msgid "" -"a or b is a NaN ==> Decimal('NaN')\n" -"a < b ==> Decimal('-1')\n" -"a == b ==> Decimal('0')\n" -"a > b ==> Decimal('1')" -msgstr "" -"a or b is a NaN ==> Decimal('NaN')\n" -"a < b ==> Decimal('-1')\n" -"a == b ==> Decimal('0')\n" -"a > b ==> Decimal('1')" - -#: ../../library/decimal.rst:522 -msgid "" -"This operation is identical to the :meth:`compare` method, except that all " -"NaNs signal. That is, if neither operand is a signaling NaN then any quiet " -"NaN operand is treated as though it were a signaling NaN." -msgstr "" - -#: ../../library/decimal.rst:528 -msgid "" -"Compare two operands using their abstract representation rather than their " -"numerical value. Similar to the :meth:`compare` method, but the result " -"gives a total ordering on :class:`Decimal` instances. Two :class:`Decimal` " -"instances with the same numeric value but different representations compare " -"unequal in this ordering:" -msgstr "" - -#: ../../library/decimal.rst:537 -msgid "" -"Quiet and signaling NaNs are also included in the total ordering. The " -"result of this function is ``Decimal('0')`` if both operands have the same " -"representation, ``Decimal('-1')`` if the first operand is lower in the total " -"order than the second, and ``Decimal('1')`` if the first operand is higher " -"in the total order than the second operand. See the specification for " -"details of the total order." -msgstr "" - -#: ../../library/decimal.rst:544 ../../library/decimal.rst:555 -#: ../../library/decimal.rst:583 ../../library/decimal.rst:887 -msgid "" -"This operation is unaffected by context and is quiet: no flags are changed " -"and no rounding is performed. As an exception, the C version may raise " -"InvalidOperation if the second operand cannot be converted exactly." -msgstr "" - -#: ../../library/decimal.rst:550 -msgid "" -"Compare two operands using their abstract representation rather than their " -"value as in :meth:`compare_total`, but ignoring the sign of each operand. " -"``x.compare_total_mag(y)`` is equivalent to ``x.copy_abs().compare_total(y." -"copy_abs())``." -msgstr "" - -#: ../../library/decimal.rst:561 -msgid "" -"Just returns self, this method is only to comply with the Decimal " -"Specification." -msgstr "" - -#: ../../library/decimal.rst:566 -msgid "" -"Return the absolute value of the argument. This operation is unaffected by " -"the context and is quiet: no flags are changed and no rounding is performed." -msgstr "" - -#: ../../library/decimal.rst:572 -msgid "" -"Return the negation of the argument. This operation is unaffected by the " -"context and is quiet: no flags are changed and no rounding is performed." -msgstr "" - -#: ../../library/decimal.rst:577 -msgid "" -"Return a copy of the first operand with the sign set to be the same as the " -"sign of the second operand. For example:" -msgstr "" - -#: ../../library/decimal.rst:589 -msgid "" -"Return the value of the (natural) exponential function ``e**x`` at the given " -"number. The result is correctly rounded using the :const:`ROUND_HALF_EVEN` " -"rounding mode." -msgstr "" - -#: ../../library/decimal.rst:600 -msgid "" -"Alternative constructor that only accepts instances of :class:`float` or :" -"class:`int`." -msgstr "" - -#: ../../library/decimal.rst:603 -msgid "" -"Note ``Decimal.from_float(0.1)`` is not the same as ``Decimal('0.1')``. " -"Since 0.1 is not exactly representable in binary floating point, the value " -"is stored as the nearest representable value which is " -"``0x1.999999999999ap-4``. That equivalent value in decimal is " -"``0.1000000000000000055511151231257827021181583404541015625``." -msgstr "" - -#: ../../library/decimal.rst:609 -msgid "" -"From Python 3.2 onwards, a :class:`Decimal` instance can also be constructed " -"directly from a :class:`float`." -msgstr "" - -#: ../../library/decimal.rst:612 -msgid "" -">>> Decimal.from_float(0.1)\n" -"Decimal('0.1000000000000000055511151231257827021181583404541015625')\n" -">>> Decimal.from_float(float('nan'))\n" -"Decimal('NaN')\n" -">>> Decimal.from_float(float('inf'))\n" -"Decimal('Infinity')\n" -">>> Decimal.from_float(float('-inf'))\n" -"Decimal('-Infinity')" -msgstr "" -">>> Decimal.from_float(0.1)\n" -"Decimal('0.1000000000000000055511151231257827021181583404541015625')\n" -">>> Decimal.from_float(float('nan'))\n" -"Decimal('NaN')\n" -">>> Decimal.from_float(float('inf'))\n" -"Decimal('Infinity')\n" -">>> Decimal.from_float(float('-inf'))\n" -"Decimal('-Infinity')" - -#: ../../library/decimal.rst:627 -msgid "" -"Alternative constructor that only accepts instances of :class:`float`, :" -"class:`int` or :class:`Decimal`, but not strings or tuples." -msgstr "" - -#: ../../library/decimal.rst:631 -msgid "" -">>> Decimal.from_number(314)\n" -"Decimal('314')\n" -">>> Decimal.from_number(0.1)\n" -"Decimal('0.1000000000000000055511151231257827021181583404541015625')\n" -">>> Decimal.from_number(Decimal('3.14'))\n" -"Decimal('3.14')" -msgstr "" -">>> Decimal.from_number(314)\n" -"Decimal('314')\n" -">>> Decimal.from_number(0.1)\n" -"Decimal('0.1000000000000000055511151231257827021181583404541015625')\n" -">>> Decimal.from_number(Decimal('3.14'))\n" -"Decimal('3.14')" - -#: ../../library/decimal.rst:644 -msgid "" -"Fused multiply-add. Return self*other+third with no rounding of the " -"intermediate product self*other." -msgstr "" - -#: ../../library/decimal.rst:652 -msgid "" -"Return :const:`True` if the argument is canonical and :const:`False` " -"otherwise. Currently, a :class:`Decimal` instance is always canonical, so " -"this operation always returns :const:`True`." -msgstr "" - -#: ../../library/decimal.rst:658 -msgid "" -"Return :const:`True` if the argument is a finite number, and :const:`False` " -"if the argument is an infinity or a NaN." -msgstr "" - -#: ../../library/decimal.rst:663 -msgid "" -"Return :const:`True` if the argument is either positive or negative infinity " -"and :const:`False` otherwise." -msgstr "" - -#: ../../library/decimal.rst:668 -msgid "" -"Return :const:`True` if the argument is a (quiet or signaling) NaN and :" -"const:`False` otherwise." -msgstr "" - -#: ../../library/decimal.rst:673 -msgid "" -"Return :const:`True` if the argument is a *normal* finite number. Return :" -"const:`False` if the argument is zero, subnormal, infinite or a NaN." -msgstr "" - -#: ../../library/decimal.rst:678 -msgid "" -"Return :const:`True` if the argument is a quiet NaN, and :const:`False` " -"otherwise." -msgstr "" - -#: ../../library/decimal.rst:683 -msgid "" -"Return :const:`True` if the argument has a negative sign and :const:`False` " -"otherwise. Note that zeros and NaNs can both carry signs." -msgstr "" - -#: ../../library/decimal.rst:688 -msgid "" -"Return :const:`True` if the argument is a signaling NaN and :const:`False` " -"otherwise." -msgstr "" - -#: ../../library/decimal.rst:693 -msgid "" -"Return :const:`True` if the argument is subnormal, and :const:`False` " -"otherwise." -msgstr "" - -#: ../../library/decimal.rst:698 -msgid "" -"Return :const:`True` if the argument is a (positive or negative) zero and :" -"const:`False` otherwise." -msgstr "" - -#: ../../library/decimal.rst:703 -msgid "" -"Return the natural (base e) logarithm of the operand. The result is " -"correctly rounded using the :const:`ROUND_HALF_EVEN` rounding mode." -msgstr "" - -#: ../../library/decimal.rst:708 -msgid "" -"Return the base ten logarithm of the operand. The result is correctly " -"rounded using the :const:`ROUND_HALF_EVEN` rounding mode." -msgstr "" - -#: ../../library/decimal.rst:713 -msgid "" -"For a nonzero number, return the adjusted exponent of its operand as a :" -"class:`Decimal` instance. If the operand is a zero then ``Decimal('-" -"Infinity')`` is returned and the :const:`DivisionByZero` flag is raised. If " -"the operand is an infinity then ``Decimal('Infinity')`` is returned." -msgstr "" - -#: ../../library/decimal.rst:721 -msgid "" -":meth:`logical_and` is a logical operation which takes two *logical " -"operands* (see :ref:`logical_operands_label`). The result is the digit-wise " -"``and`` of the two operands." -msgstr "" - -#: ../../library/decimal.rst:727 -msgid "" -":meth:`logical_invert` is a logical operation. The result is the digit-wise " -"inversion of the operand." -msgstr "" - -#: ../../library/decimal.rst:732 -msgid "" -":meth:`logical_or` is a logical operation which takes two *logical operands* " -"(see :ref:`logical_operands_label`). The result is the digit-wise ``or`` of " -"the two operands." -msgstr "" - -#: ../../library/decimal.rst:738 -msgid "" -":meth:`logical_xor` is a logical operation which takes two *logical " -"operands* (see :ref:`logical_operands_label`). The result is the digit-wise " -"exclusive or of the two operands." -msgstr "" - -#: ../../library/decimal.rst:744 -msgid "" -"Like ``max(self, other)`` except that the context rounding rule is applied " -"before returning and that ``NaN`` values are either signaled or ignored " -"(depending on the context and whether they are signaling or quiet)." -msgstr "" - -#: ../../library/decimal.rst:751 -msgid "" -"Similar to the :meth:`.max` method, but the comparison is done using the " -"absolute values of the operands." -msgstr "" - -#: ../../library/decimal.rst:756 -msgid "" -"Like ``min(self, other)`` except that the context rounding rule is applied " -"before returning and that ``NaN`` values are either signaled or ignored " -"(depending on the context and whether they are signaling or quiet)." -msgstr "" - -#: ../../library/decimal.rst:763 -msgid "" -"Similar to the :meth:`.min` method, but the comparison is done using the " -"absolute values of the operands." -msgstr "" - -#: ../../library/decimal.rst:768 -msgid "" -"Return the largest number representable in the given context (or in the " -"current thread's context if no context is given) that is smaller than the " -"given operand." -msgstr "" - -#: ../../library/decimal.rst:774 -msgid "" -"Return the smallest number representable in the given context (or in the " -"current thread's context if no context is given) that is larger than the " -"given operand." -msgstr "" - -#: ../../library/decimal.rst:780 -msgid "" -"If the two operands are unequal, return the number closest to the first " -"operand in the direction of the second operand. If both operands are " -"numerically equal, return a copy of the first operand with the sign set to " -"be the same as the sign of the second operand." -msgstr "" - -#: ../../library/decimal.rst:787 -msgid "" -"Used for producing canonical values of an equivalence class within either " -"the current context or the specified context." -msgstr "" - -#: ../../library/decimal.rst:790 -msgid "" -"This has the same semantics as the unary plus operation, except that if the " -"final result is finite it is reduced to its simplest form, with all trailing " -"zeros removed and its sign preserved. That is, while the coefficient is non-" -"zero and a multiple of ten the coefficient is divided by ten and the " -"exponent is incremented by 1. Otherwise (the coefficient is zero) the " -"exponent is set to 0. In all cases the sign is unchanged." -msgstr "" - -#: ../../library/decimal.rst:797 -msgid "" -"For example, ``Decimal('32.100')`` and ``Decimal('0.321000e+2')`` both " -"normalize to the equivalent value ``Decimal('32.1')``." -msgstr "" - -#: ../../library/decimal.rst:800 -msgid "Note that rounding is applied *before* reducing to simplest form." -msgstr "" - -#: ../../library/decimal.rst:802 -msgid "" -"In the latest versions of the specification, this operation is also known as " -"``reduce``." -msgstr "" - -#: ../../library/decimal.rst:807 -msgid "" -"Return a string describing the *class* of the operand. The returned value " -"is one of the following ten strings." -msgstr "" - -#: ../../library/decimal.rst:810 -msgid "``\"-Infinity\"``, indicating that the operand is negative infinity." -msgstr "" - -#: ../../library/decimal.rst:811 -msgid "" -"``\"-Normal\"``, indicating that the operand is a negative normal number." -msgstr "" - -#: ../../library/decimal.rst:812 -msgid "" -"``\"-Subnormal\"``, indicating that the operand is negative and subnormal." -msgstr "" - -#: ../../library/decimal.rst:813 -msgid "``\"-Zero\"``, indicating that the operand is a negative zero." -msgstr "" - -#: ../../library/decimal.rst:814 -msgid "``\"+Zero\"``, indicating that the operand is a positive zero." -msgstr "" - -#: ../../library/decimal.rst:815 -msgid "" -"``\"+Subnormal\"``, indicating that the operand is positive and subnormal." -msgstr "" - -#: ../../library/decimal.rst:816 -msgid "" -"``\"+Normal\"``, indicating that the operand is a positive normal number." -msgstr "" - -#: ../../library/decimal.rst:817 -msgid "``\"+Infinity\"``, indicating that the operand is positive infinity." -msgstr "" - -#: ../../library/decimal.rst:818 -msgid "``\"NaN\"``, indicating that the operand is a quiet NaN (Not a Number)." -msgstr "" - -#: ../../library/decimal.rst:819 -msgid "``\"sNaN\"``, indicating that the operand is a signaling NaN." -msgstr "" - -#: ../../library/decimal.rst:823 -msgid "" -"Return a value equal to the first operand after rounding and having the " -"exponent of the second operand." -msgstr "" - -#: ../../library/decimal.rst:829 -msgid "" -"Unlike other operations, if the length of the coefficient after the quantize " -"operation would be greater than precision, then an :const:`InvalidOperation` " -"is signaled. This guarantees that, unless there is an error condition, the " -"quantized exponent is always equal to that of the right-hand operand." -msgstr "" - -#: ../../library/decimal.rst:835 -msgid "" -"Also unlike other operations, quantize never signals Underflow, even if the " -"result is subnormal and inexact." -msgstr "" - -#: ../../library/decimal.rst:838 -msgid "" -"If the exponent of the second operand is larger than that of the first then " -"rounding may be necessary. In this case, the rounding mode is determined by " -"the ``rounding`` argument if given, else by the given ``context`` argument; " -"if neither argument is given the rounding mode of the current thread's " -"context is used." -msgstr "" - -#: ../../library/decimal.rst:844 -msgid "" -"An error is returned whenever the resulting exponent is greater than :attr:" -"`~Context.Emax` or less than :meth:`~Context.Etiny`." -msgstr "" - -#: ../../library/decimal.rst:849 -msgid "" -"Return ``Decimal(10)``, the radix (base) in which the :class:`Decimal` class " -"does all its arithmetic. Included for compatibility with the specification." -msgstr "" - -#: ../../library/decimal.rst:855 -msgid "" -"Return the remainder from dividing *self* by *other*. This differs from " -"``self % other`` in that the sign of the remainder is chosen so as to " -"minimize its absolute value. More precisely, the return value is ``self - n " -"* other`` where ``n`` is the integer nearest to the exact value of ``self / " -"other``, and if two integers are equally near then the even one is chosen." -msgstr "" - -#: ../../library/decimal.rst:862 -msgid "If the result is zero then its sign will be the sign of *self*." -msgstr "" - -#: ../../library/decimal.rst:873 -msgid "" -"Return the result of rotating the digits of the first operand by an amount " -"specified by the second operand. The second operand must be an integer in " -"the range -precision through precision. The absolute value of the second " -"operand gives the number of places to rotate. If the second operand is " -"positive then rotation is to the left; otherwise rotation is to the right. " -"The coefficient of the first operand is padded on the left with zeros to " -"length precision if necessary. The sign and exponent of the first operand " -"are unchanged." -msgstr "" - -#: ../../library/decimal.rst:884 -msgid "" -"Test whether self and other have the same exponent or whether both are " -"``NaN``." -msgstr "" - -#: ../../library/decimal.rst:893 -msgid "" -"Return the first operand with exponent adjusted by the second. Equivalently, " -"return the first operand multiplied by ``10**other``. The second operand " -"must be an integer." -msgstr "" - -#: ../../library/decimal.rst:899 -msgid "" -"Return the result of shifting the digits of the first operand by an amount " -"specified by the second operand. The second operand must be an integer in " -"the range -precision through precision. The absolute value of the second " -"operand gives the number of places to shift. If the second operand is " -"positive then the shift is to the left; otherwise the shift is to the " -"right. Digits shifted into the coefficient are zeros. The sign and " -"exponent of the first operand are unchanged." -msgstr "" - -#: ../../library/decimal.rst:909 -msgid "Return the square root of the argument to full precision." -msgstr "" - -#: ../../library/decimal.rst:914 ../../library/decimal.rst:1571 -msgid "" -"Convert to a string, using engineering notation if an exponent is needed." -msgstr "" - -#: ../../library/decimal.rst:916 ../../library/decimal.rst:1573 -msgid "" -"Engineering notation has an exponent which is a multiple of 3. This can " -"leave up to 3 digits to the left of the decimal place and may require the " -"addition of either one or two trailing zeros." -msgstr "" - -#: ../../library/decimal.rst:920 -msgid "" -"For example, this converts ``Decimal('123E+1')`` to ``Decimal('1.23E+3')``." -msgstr "" - -#: ../../library/decimal.rst:924 -msgid "" -"Identical to the :meth:`to_integral_value` method. The ``to_integral`` name " -"has been kept for compatibility with older versions." -msgstr "" - -#: ../../library/decimal.rst:929 -msgid "" -"Round to the nearest integer, signaling :const:`Inexact` or :const:`Rounded` " -"as appropriate if rounding occurs. The rounding mode is determined by the " -"``rounding`` parameter if given, else by the given ``context``. If neither " -"parameter is given then the rounding mode of the current context is used." -msgstr "" - -#: ../../library/decimal.rst:937 -msgid "" -"Round to the nearest integer without signaling :const:`Inexact` or :const:" -"`Rounded`. If given, applies *rounding*; otherwise, uses the rounding " -"method in either the supplied *context* or the current context." -msgstr "" - -#: ../../library/decimal.rst:941 -msgid "Decimal numbers can be rounded using the :func:`.round` function:" -msgstr "" - -#: ../../library/decimal.rst:946 -msgid "" -"If *ndigits* is not given or ``None``, returns the nearest :class:`int` to " -"*number*, rounding ties to even, and ignoring the rounding mode of the :" -"class:`Decimal` context. Raises :exc:`OverflowError` if *number* is an " -"infinity or :exc:`ValueError` if it is a (quiet or signaling) NaN." -msgstr "" - -#: ../../library/decimal.rst:952 -msgid "" -"If *ndigits* is an :class:`int`, the context's rounding mode is respected " -"and a :class:`Decimal` representing *number* rounded to the nearest multiple " -"of ``Decimal('1E-ndigits')`` is returned; in this case, ``round(number, " -"ndigits)`` is equivalent to ``self.quantize(Decimal('1E-ndigits'))``. " -"Returns ``Decimal('NaN')`` if *number* is a quiet NaN. Raises :class:" -"`InvalidOperation` if *number* is an infinity, a signaling NaN, or if the " -"length of the coefficient after the quantize operation would be greater than " -"the current context's precision. In other words, for the non-corner cases:" -msgstr "" - -#: ../../library/decimal.rst:962 -msgid "" -"if *ndigits* is positive, return *number* rounded to *ndigits* decimal " -"places;" -msgstr "" - -#: ../../library/decimal.rst:964 -msgid "if *ndigits* is zero, return *number* rounded to the nearest integer;" -msgstr "" - -#: ../../library/decimal.rst:965 -msgid "" -"if *ndigits* is negative, return *number* rounded to the nearest multiple of " -"``10**abs(ndigits)``." -msgstr "" - -#: ../../library/decimal.rst:968 -msgid "For example::" -msgstr "舉例來說： ::" - -#: ../../library/decimal.rst:970 -msgid "" -">>> from decimal import Decimal, getcontext, ROUND_DOWN\n" -">>> getcontext().rounding = ROUND_DOWN\n" -">>> round(Decimal('3.75')) # context rounding ignored\n" -"4\n" -">>> round(Decimal('3.5')) # round-ties-to-even\n" -"4\n" -">>> round(Decimal('3.75'), 0) # uses the context rounding\n" -"Decimal('3')\n" -">>> round(Decimal('3.75'), 1)\n" -"Decimal('3.7')\n" -">>> round(Decimal('3.75'), -1)\n" -"Decimal('0E+1')" -msgstr "" - -#: ../../library/decimal.rst:987 -msgid "Logical operands" -msgstr "" - -#: ../../library/decimal.rst:989 -msgid "" -"The :meth:`~Decimal.logical_and`, :meth:`~Decimal.logical_invert`, :meth:" -"`~Decimal.logical_or`, and :meth:`~Decimal.logical_xor` methods expect their " -"arguments to be *logical operands*. A *logical operand* is a :class:" -"`Decimal` instance whose exponent and sign are both zero, and whose digits " -"are all either ``0`` or ``1``." -msgstr "" - -#: ../../library/decimal.rst:1001 -msgid "Context objects" -msgstr "" - -#: ../../library/decimal.rst:1003 -msgid "" -"Contexts are environments for arithmetic operations. They govern precision, " -"set rules for rounding, determine which signals are treated as exceptions, " -"and limit the range for exponents." -msgstr "" - -#: ../../library/decimal.rst:1007 -msgid "" -"Each thread has its own current context which is accessed or changed using " -"the :func:`getcontext` and :func:`setcontext` functions:" -msgstr "" - -#: ../../library/decimal.rst:1013 -msgid "Return the current context for the active thread." -msgstr "" - -#: ../../library/decimal.rst:1018 -msgid "Set the current context for the active thread to *c*." -msgstr "" - -#: ../../library/decimal.rst:1020 -msgid "" -"You can also use the :keyword:`with` statement and the :func:`localcontext` " -"function to temporarily change the active context." -msgstr "" - -#: ../../library/decimal.rst:1025 -msgid "" -"Return a context manager that will set the current context for the active " -"thread to a copy of *ctx* on entry to the with-statement and restore the " -"previous context when exiting the with-statement. If no context is " -"specified, a copy of the current context is used. The *kwargs* argument is " -"used to set the attributes of the new context." -msgstr "" - -#: ../../library/decimal.rst:1031 -msgid "" -"For example, the following code sets the current decimal precision to 42 " -"places, performs a calculation, and then automatically restores the previous " -"context::" -msgstr "" - -#: ../../library/decimal.rst:1034 -msgid "" -"from decimal import localcontext\n" -"\n" -"with localcontext() as ctx:\n" -" ctx.prec = 42 # Perform a high precision calculation\n" -" s = calculate_something()\n" -"s = +s # Round the final result back to the default precision" -msgstr "" - -#: ../../library/decimal.rst:1041 -msgid "Using keyword arguments, the code would be the following::" -msgstr "" - -#: ../../library/decimal.rst:1043 -msgid "" -"from decimal import localcontext\n" -"\n" -"with localcontext(prec=42) as ctx:\n" -" s = calculate_something()\n" -"s = +s" -msgstr "" -"from decimal import localcontext\n" -"\n" -"with localcontext(prec=42) as ctx:\n" -" s = calculate_something()\n" -"s = +s" - -#: ../../library/decimal.rst:1049 -msgid "" -"Raises :exc:`TypeError` if *kwargs* supplies an attribute that :class:" -"`Context` doesn't support. Raises either :exc:`TypeError` or :exc:" -"`ValueError` if *kwargs* supplies an invalid value for an attribute." -msgstr "" - -#: ../../library/decimal.rst:1053 -msgid "" -":meth:`localcontext` now supports setting context attributes through the use " -"of keyword arguments." -msgstr "" - -#: ../../library/decimal.rst:1058 -msgid "" -"Return a context object initialized to the proper values for one of the IEEE " -"interchange formats. The argument must be a multiple of 32 and less than :" -"const:`IEEE_CONTEXT_MAX_BITS`." -msgstr "" - -#: ../../library/decimal.rst:1064 -msgid "" -"New contexts can also be created using the :class:`Context` constructor " -"described below. In addition, the module provides three pre-made contexts:" -msgstr "" - -#: ../../library/decimal.rst:1070 -msgid "" -"This is a standard context defined by the General Decimal Arithmetic " -"Specification. Precision is set to nine. Rounding is set to :const:" -"`ROUND_HALF_UP`. All flags are cleared. All traps are enabled (treated as " -"exceptions) except :const:`Inexact`, :const:`Rounded`, and :const:" -"`Subnormal`." -msgstr "" - -#: ../../library/decimal.rst:1076 -msgid "" -"Because many of the traps are enabled, this context is useful for debugging." -msgstr "" - -#: ../../library/decimal.rst:1081 -msgid "" -"This is a standard context defined by the General Decimal Arithmetic " -"Specification. Precision is set to nine. Rounding is set to :const:" -"`ROUND_HALF_EVEN`. All flags are cleared. No traps are enabled (so that " -"exceptions are not raised during computations)." -msgstr "" - -#: ../../library/decimal.rst:1086 -msgid "" -"Because the traps are disabled, this context is useful for applications that " -"prefer to have result value of ``NaN`` or ``Infinity`` instead of raising " -"exceptions. This allows an application to complete a run in the presence of " -"conditions that would otherwise halt the program." -msgstr "" - -#: ../../library/decimal.rst:1094 -msgid "" -"This context is used by the :class:`Context` constructor as a prototype for " -"new contexts. Changing a field (such a precision) has the effect of " -"changing the default for new contexts created by the :class:`Context` " -"constructor." -msgstr "" - -#: ../../library/decimal.rst:1098 -msgid "" -"This context is most useful in multi-threaded environments. Changing one of " -"the fields before threads are started has the effect of setting system-wide " -"defaults. Changing the fields after threads have started is not recommended " -"as it would require thread synchronization to prevent race conditions." -msgstr "" - -#: ../../library/decimal.rst:1103 -msgid "" -"In single threaded environments, it is preferable to not use this context at " -"all. Instead, simply create contexts explicitly as described below." -msgstr "" - -#: ../../library/decimal.rst:1106 -msgid "" -"The default values are :attr:`Context.prec`\\ =\\ ``28``, :attr:`Context." -"rounding`\\ =\\ :const:`ROUND_HALF_EVEN`, and enabled traps for :class:" -"`Overflow`, :class:`InvalidOperation`, and :class:`DivisionByZero`." -msgstr "" - -#: ../../library/decimal.rst:1111 -msgid "" -"In addition to the three supplied contexts, new contexts can be created with " -"the :class:`Context` constructor." -msgstr "" - -#: ../../library/decimal.rst:1117 -msgid "" -"Creates a new context. If a field is not specified or is :const:`None`, the " -"default values are copied from the :const:`DefaultContext`. If the *flags* " -"field is not specified or is :const:`None`, all flags are cleared." -msgstr "" - -#: ../../library/decimal.rst:1123 -msgid "" -"An integer in the range [``1``, :const:`MAX_PREC`] that sets the precision " -"for arithmetic operations in the context." -msgstr "" - -#: ../../library/decimal.rst:1128 -msgid "One of the constants listed in the section `Rounding Modes`_." -msgstr "" - -#: ../../library/decimal.rst:1133 -msgid "" -"Lists of any signals to be set. Generally, new contexts should only set " -"traps and leave the flags clear." -msgstr "" - -#: ../../library/decimal.rst:1139 -msgid "" -"Integers specifying the outer limits allowable for exponents. *Emin* must be " -"in the range [:const:`MIN_EMIN`, ``0``], *Emax* in the range [``0``, :const:" -"`MAX_EMAX`]." -msgstr "" - -#: ../../library/decimal.rst:1145 -msgid "" -"Either ``0`` or ``1`` (the default). If set to ``1``, exponents are printed " -"with a capital ``E``; otherwise, a lowercase ``e`` is used: " -"``Decimal('6.02e+23')``." -msgstr "" - -#: ../../library/decimal.rst:1151 -msgid "" -"Either ``0`` (the default) or ``1``. If set to ``1``, the exponent ``e`` of " -"a :class:`Decimal` instance representable in this context is strictly " -"limited to the range ``Emin - prec + 1 <= e <= Emax - prec + 1``. If *clamp* " -"is ``0`` then a weaker condition holds: the adjusted exponent of the :class:" -"`Decimal` instance is at most :attr:`~Context.Emax`. When *clamp* is ``1``, " -"a large normal number will, where possible, have its exponent reduced and a " -"corresponding number of zeros added to its coefficient, in order to fit the " -"exponent constraints; this preserves the value of the number but loses " -"information about significant trailing zeros. For example::" -msgstr "" - -#: ../../library/decimal.rst:1162 -msgid "" -">>> Context(prec=6, Emax=999, clamp=1).create_decimal('1.23e999')\n" -"Decimal('1.23000E+999')" -msgstr "" -">>> Context(prec=6, Emax=999, clamp=1).create_decimal('1.23e999')\n" -"Decimal('1.23000E+999')" - -#: ../../library/decimal.rst:1165 -msgid "" -"A *clamp* value of ``1`` allows compatibility with the fixed-width decimal " -"interchange formats specified in IEEE 754." -msgstr "" - -#: ../../library/decimal.rst:1168 -msgid "" -"The :class:`Context` class defines several general purpose methods as well " -"as a large number of methods for doing arithmetic directly in a given " -"context. In addition, for each of the :class:`Decimal` methods described " -"above (with the exception of the :meth:`~Decimal.adjusted` and :meth:" -"`~Decimal.as_tuple` methods) there is a corresponding :class:`Context` " -"method. For example, for a :class:`Context` instance ``C`` and :class:" -"`Decimal` instance ``x``, ``C.exp(x)`` is equivalent to ``x." -"exp(context=C)``. Each :class:`Context` method accepts a Python integer (an " -"instance of :class:`int`) anywhere that a Decimal instance is accepted." -msgstr "" - -#: ../../library/decimal.rst:1181 -msgid "Resets all of the flags to ``0``." -msgstr "" - -#: ../../library/decimal.rst:1185 -msgid "Resets all of the traps to ``0``." -msgstr "" - -#: ../../library/decimal.rst:1191 -msgid "Return a duplicate of the context." -msgstr "" - -#: ../../library/decimal.rst:1195 -msgid "Return a copy of the Decimal instance num." -msgstr "" - -#: ../../library/decimal.rst:1199 -msgid "" -"Creates a new Decimal instance from *num* but using *self* as context. " -"Unlike the :class:`Decimal` constructor, the context precision, rounding " -"method, flags, and traps are applied to the conversion." -msgstr "" - -#: ../../library/decimal.rst:1203 -msgid "" -"This is useful because constants are often given to a greater precision than " -"is needed by the application. Another benefit is that rounding immediately " -"eliminates unintended effects from digits beyond the current precision. In " -"the following example, using unrounded inputs means that adding zero to a " -"sum can change the result:" -msgstr "" - -#: ../../library/decimal.rst:1209 -msgid "" -">>> getcontext().prec = 3\n" -">>> Decimal('3.4445') + Decimal('1.0023')\n" -"Decimal('4.45')\n" -">>> Decimal('3.4445') + Decimal(0) + Decimal('1.0023')\n" -"Decimal('4.44')" -msgstr "" -">>> getcontext().prec = 3\n" -">>> Decimal('3.4445') + Decimal('1.0023')\n" -"Decimal('4.45')\n" -">>> Decimal('3.4445') + Decimal(0) + Decimal('1.0023')\n" -"Decimal('4.44')" - -#: ../../library/decimal.rst:1217 -msgid "" -"This method implements the to-number operation of the IBM specification. If " -"the argument is a string, no leading or trailing whitespace or underscores " -"are permitted." -msgstr "" - -#: ../../library/decimal.rst:1223 -msgid "" -"Creates a new Decimal instance from a float *f* but rounding using *self* as " -"the context. Unlike the :meth:`Decimal.from_float` class method, the " -"context precision, rounding method, flags, and traps are applied to the " -"conversion." -msgstr "" - -#: ../../library/decimal.rst:1228 -msgid "" -">>> context = Context(prec=5, rounding=ROUND_DOWN)\n" -">>> context.create_decimal_from_float(math.pi)\n" -"Decimal('3.1415')\n" -">>> context = Context(prec=5, traps=[Inexact])\n" -">>> context.create_decimal_from_float(math.pi)\n" -"Traceback (most recent call last):\n" -" ...\n" -"decimal.Inexact: None" -msgstr "" -">>> context = Context(prec=5, rounding=ROUND_DOWN)\n" -">>> context.create_decimal_from_float(math.pi)\n" -"Decimal('3.1415')\n" -">>> context = Context(prec=5, traps=[Inexact])\n" -">>> context.create_decimal_from_float(math.pi)\n" -"Traceback (most recent call last):\n" -" ...\n" -"decimal.Inexact: None" - -#: ../../library/decimal.rst:1243 -msgid "" -"Returns a value equal to ``Emin - prec + 1`` which is the minimum exponent " -"value for subnormal results. When underflow occurs, the exponent is set to :" -"const:`Etiny`." -msgstr "" - -#: ../../library/decimal.rst:1249 -msgid "Returns a value equal to ``Emax - prec + 1``." -msgstr "回傳一個等於 ``Emax - prec + 1`` 的值。" - -#: ../../library/decimal.rst:1251 -msgid "" -"The usual approach to working with decimals is to create :class:`Decimal` " -"instances and then apply arithmetic operations which take place within the " -"current context for the active thread. An alternative approach is to use " -"context methods for calculating within a specific context. The methods are " -"similar to those for the :class:`Decimal` class and are only briefly " -"recounted here." -msgstr "" - -#: ../../library/decimal.rst:1261 -msgid "Returns the absolute value of *x*." -msgstr "回傳 *x* 的絕對值。" - -#: ../../library/decimal.rst:1266 -msgid "Return the sum of *x* and *y*." -msgstr "回傳 *x* 與 *y* 的和。" - -#: ../../library/decimal.rst:1271 -msgid "Returns the same Decimal object *x*." -msgstr "回傳相同的 Decimal 物件 *x*。" - -#: ../../library/decimal.rst:1276 -msgid "Compares *x* and *y* numerically." -msgstr "" - -#: ../../library/decimal.rst:1281 -msgid "Compares the values of the two operands numerically." -msgstr "" - -#: ../../library/decimal.rst:1286 -msgid "Compares two operands using their abstract representation." -msgstr "" - -#: ../../library/decimal.rst:1291 -msgid "" -"Compares two operands using their abstract representation, ignoring sign." -msgstr "" - -#: ../../library/decimal.rst:1296 -msgid "Returns a copy of *x* with the sign set to 0." -msgstr "" - -#: ../../library/decimal.rst:1301 -msgid "Returns a copy of *x* with the sign inverted." -msgstr "" - -#: ../../library/decimal.rst:1306 -msgid "Copies the sign from *y* to *x*." -msgstr "將 *y* 的正負號複製到 *x*。" - -#: ../../library/decimal.rst:1311 -msgid "Return *x* divided by *y*." -msgstr "回傳 *x* 除以 *y*。" - -#: ../../library/decimal.rst:1316 -msgid "Return *x* divided by *y*, truncated to an integer." -msgstr "" - -#: ../../library/decimal.rst:1321 -msgid "Divides two numbers and returns the integer part of the result." -msgstr "" - -#: ../../library/decimal.rst:1326 -msgid "Returns ``e ** x``." -msgstr "回傳 ``e ** x``。" - -#: ../../library/decimal.rst:1331 -msgid "Returns *x* multiplied by *y*, plus *z*." -msgstr "回傳 *x* 乘以 *y*，再加上 *z*。" - -#: ../../library/decimal.rst:1336 -msgid "Returns ``True`` if *x* is canonical; otherwise returns ``False``." -msgstr "" - -#: ../../library/decimal.rst:1341 -msgid "Returns ``True`` if *x* is finite; otherwise returns ``False``." -msgstr "如果 *x* 是有限的則回傳 ``True``；否則回傳 ``False``。" - -#: ../../library/decimal.rst:1346 -msgid "Returns ``True`` if *x* is infinite; otherwise returns ``False``." -msgstr "如果 *x* 是無限大則回傳 ``True``；否則回傳 ``False``。" - -#: ../../library/decimal.rst:1351 -msgid "Returns ``True`` if *x* is a qNaN or sNaN; otherwise returns ``False``." -msgstr "如果 *x* 是 qNaN 或 sNaN 則回傳 ``True``；否則回傳 ``False``。" - -#: ../../library/decimal.rst:1356 -msgid "" -"Returns ``True`` if *x* is a normal number; otherwise returns ``False``." -msgstr "" -"如果 *x* 是正規數 (normal number) 則回傳 ``True``；否則回傳 ``False``。" - -#: ../../library/decimal.rst:1361 -msgid "Returns ``True`` if *x* is a quiet NaN; otherwise returns ``False``." -msgstr "" -"如果 *x* 是安靜型 NaN (quiet NaN) 則回傳 ``True``；否則回傳 ``False``。" - -#: ../../library/decimal.rst:1366 -msgid "Returns ``True`` if *x* is negative; otherwise returns ``False``." -msgstr "如果 *x* 是負數則回傳 ``True``；否則回傳 ``False``。" - -#: ../../library/decimal.rst:1371 -msgid "" -"Returns ``True`` if *x* is a signaling NaN; otherwise returns ``False``." -msgstr "" -"如果 *x* 是訊號型 NaN (signaling NaN) 則回傳 ``True``；否則回傳 ``False``。" - -#: ../../library/decimal.rst:1376 -msgid "Returns ``True`` if *x* is subnormal; otherwise returns ``False``." -msgstr "如果 *x* 是次正規數 (subnormal) 則回傳 ``True``；否則回傳 ``False``。" - -#: ../../library/decimal.rst:1381 -msgid "Returns ``True`` if *x* is a zero; otherwise returns ``False``." -msgstr "如果 *x* 是零則回傳 ``True``；否則回傳 ``False``。" - -#: ../../library/decimal.rst:1386 -msgid "Returns the natural (base e) logarithm of *x*." -msgstr "回傳 *x* 的自然對數（以 e 為底）。" - -#: ../../library/decimal.rst:1391 -msgid "Returns the base 10 logarithm of *x*." -msgstr "回傳 *x* 的以 10 為底的對數。" - -#: ../../library/decimal.rst:1396 -msgid "Returns the exponent of the magnitude of the operand's MSD." -msgstr "回傳運算元最高有效位數（MSD）數值的指數。" - -#: ../../library/decimal.rst:1401 -msgid "Applies the logical operation *and* between each operand's digits." -msgstr "將每個運算元的位數套用邏輯運算 *and*。" - -#: ../../library/decimal.rst:1406 -msgid "Invert all the digits in *x*." -msgstr "" - -#: ../../library/decimal.rst:1411 -msgid "Applies the logical operation *or* between each operand's digits." -msgstr "" - -#: ../../library/decimal.rst:1416 -msgid "Applies the logical operation *xor* between each operand's digits." -msgstr "" - -#: ../../library/decimal.rst:1421 -msgid "Compares two values numerically and returns the maximum." -msgstr "" - -#: ../../library/decimal.rst:1426 ../../library/decimal.rst:1436 -msgid "Compares the values numerically with their sign ignored." -msgstr "" - -#: ../../library/decimal.rst:1431 -msgid "Compares two values numerically and returns the minimum." -msgstr "" - -#: ../../library/decimal.rst:1441 -msgid "Minus corresponds to the unary prefix minus operator in Python." -msgstr "" - -#: ../../library/decimal.rst:1446 -msgid "Return the product of *x* and *y*." -msgstr "" - -#: ../../library/decimal.rst:1451 -msgid "Returns the largest representable number smaller than *x*." -msgstr "" - -#: ../../library/decimal.rst:1456 -msgid "Returns the smallest representable number larger than *x*." -msgstr "" - -#: ../../library/decimal.rst:1461 -msgid "Returns the number closest to *x*, in direction towards *y*." -msgstr "" - -#: ../../library/decimal.rst:1466 -msgid "Reduces *x* to its simplest form." -msgstr "" - -#: ../../library/decimal.rst:1471 -msgid "Returns an indication of the class of *x*." -msgstr "" - -#: ../../library/decimal.rst:1476 -msgid "" -"Plus corresponds to the unary prefix plus operator in Python. This " -"operation applies the context precision and rounding, so it is *not* an " -"identity operation." -msgstr "" - -#: ../../library/decimal.rst:1483 -msgid "Return ``x`` to the power of ``y``, reduced modulo ``modulo`` if given." -msgstr "" - -#: ../../library/decimal.rst:1485 -msgid "" -"With two arguments, compute ``x**y``. If ``x`` is negative then ``y`` must " -"be integral. The result will be inexact unless ``y`` is integral and the " -"result is finite and can be expressed exactly in 'precision' digits. The " -"rounding mode of the context is used. Results are always correctly rounded " -"in the Python version." -msgstr "" - -#: ../../library/decimal.rst:1491 -msgid "" -"``Decimal(0) ** Decimal(0)`` results in ``InvalidOperation``, and if " -"``InvalidOperation`` is not trapped, then results in ``Decimal('NaN')``." -msgstr "" - -#: ../../library/decimal.rst:1494 -msgid "" -"The C module computes :meth:`power` in terms of the correctly rounded :meth:" -"`exp` and :meth:`ln` functions. The result is well-defined but only \"almost " -"always correctly rounded\"." -msgstr "" - -#: ../../library/decimal.rst:1499 -msgid "" -"With three arguments, compute ``(x**y) % modulo``. For the three argument " -"form, the following restrictions on the arguments hold:" -msgstr "" - -#: ../../library/decimal.rst:1502 -msgid "all three arguments must be integral" -msgstr "" - -#: ../../library/decimal.rst:1503 -msgid "``y`` must be nonnegative" -msgstr "" - -#: ../../library/decimal.rst:1504 -msgid "at least one of ``x`` or ``y`` must be nonzero" -msgstr "" - -#: ../../library/decimal.rst:1505 -msgid "``modulo`` must be nonzero and have at most 'precision' digits" -msgstr "" - -#: ../../library/decimal.rst:1507 -msgid "" -"The value resulting from ``Context.power(x, y, modulo)`` is equal to the " -"value that would be obtained by computing ``(x**y) % modulo`` with unbounded " -"precision, but is computed more efficiently. The exponent of the result is " -"zero, regardless of the exponents of ``x``, ``y`` and ``modulo``. The " -"result is always exact." -msgstr "" - -#: ../../library/decimal.rst:1517 -msgid "Returns a value equal to *x* (rounded), having the exponent of *y*." -msgstr "" - -#: ../../library/decimal.rst:1522 -msgid "Just returns 10, as this is Decimal, :)" -msgstr "" - -#: ../../library/decimal.rst:1527 -msgid "Returns the remainder from integer division." -msgstr "" - -#: ../../library/decimal.rst:1529 -msgid "" -"The sign of the result, if non-zero, is the same as that of the original " -"dividend." -msgstr "" - -#: ../../library/decimal.rst:1535 -msgid "" -"Returns ``x - y * n``, where *n* is the integer nearest the exact value of " -"``x / y`` (if the result is 0 then its sign will be the sign of *x*)." -msgstr "" - -#: ../../library/decimal.rst:1541 -msgid "Returns a rotated copy of *x*, *y* times." -msgstr "" - -#: ../../library/decimal.rst:1546 -msgid "Returns ``True`` if the two operands have the same exponent." -msgstr "如果兩個運算元有相同的指數則回傳 ``True``。" - -#: ../../library/decimal.rst:1551 -msgid "Returns the first operand after adding the second value its exp." -msgstr "" - -#: ../../library/decimal.rst:1556 -msgid "Returns a shifted copy of *x*, *y* times." -msgstr "" - -#: ../../library/decimal.rst:1561 -msgid "Square root of a non-negative number to context precision." -msgstr "" - -#: ../../library/decimal.rst:1566 -msgid "Return the difference between *x* and *y*." -msgstr "" - -#: ../../library/decimal.rst:1580 -msgid "Rounds to an integer." -msgstr "" - -#: ../../library/decimal.rst:1585 -msgid "Converts a number to a string using scientific notation." -msgstr "" - -#: ../../library/decimal.rst:1592 -msgid "Constants" -msgstr "常數" - -#: ../../library/decimal.rst:1594 -msgid "" -"The constants in this section are only relevant for the C module. They are " -"also included in the pure Python version for compatibility." -msgstr "" - -#: ../../library/decimal.rst:1598 -msgid "32-bit" -msgstr "32 位元" - -#: ../../library/decimal.rst:1598 -msgid "64-bit" -msgstr "64 位元" - -#: ../../library/decimal.rst:1600 ../../library/decimal.rst:1602 -msgid "``425000000``" -msgstr "``425000000``" - -#: ../../library/decimal.rst:1600 ../../library/decimal.rst:1602 -msgid "``999999999999999999``" -msgstr "``999999999999999999``" - -#: ../../library/decimal.rst:1604 -msgid "``-425000000``" -msgstr "``-425000000``" - -#: ../../library/decimal.rst:1604 -msgid "``-999999999999999999``" -msgstr "``-999999999999999999``" - -#: ../../library/decimal.rst:1606 -msgid "``-849999999``" -msgstr "``-849999999``" - -#: ../../library/decimal.rst:1606 -msgid "``-1999999999999999997``" -msgstr "``-1999999999999999997``" - -#: ../../library/decimal.rst:1608 -msgid "``256``" -msgstr "``256``" - -#: ../../library/decimal.rst:1608 -msgid "``512``" -msgstr "``512``" - -#: ../../library/decimal.rst:1613 -msgid "" -"The value is ``True``. Deprecated, because Python now always has threads." -msgstr "" - -#: ../../library/decimal.rst:1619 -msgid "" -"The default value is ``True``. If Python is :option:`configured using the --" -"without-decimal-contextvar option <--without-decimal-contextvar>`, the C " -"version uses a thread-local rather than a coroutine-local context and the " -"value is ``False``. This is slightly faster in some nested context " -"scenarios." -msgstr "" - -#: ../../library/decimal.rst:1628 -msgid "Rounding modes" -msgstr "" - -#: ../../library/decimal.rst:1632 -msgid "Round towards ``Infinity``." -msgstr "" - -#: ../../library/decimal.rst:1636 -msgid "Round towards zero." -msgstr "" - -#: ../../library/decimal.rst:1640 -msgid "Round towards ``-Infinity``." -msgstr "" - -#: ../../library/decimal.rst:1644 -msgid "Round to nearest with ties going towards zero." -msgstr "" - -#: ../../library/decimal.rst:1648 -msgid "Round to nearest with ties going to nearest even integer." -msgstr "" - -#: ../../library/decimal.rst:1652 -msgid "Round to nearest with ties going away from zero." -msgstr "" - -#: ../../library/decimal.rst:1656 -msgid "Round away from zero." -msgstr "" - -#: ../../library/decimal.rst:1660 -msgid "" -"Round away from zero if last digit after rounding towards zero would have " -"been 0 or 5; otherwise round towards zero." -msgstr "" - -#: ../../library/decimal.rst:1667 -msgid "Signals" -msgstr "" - -#: ../../library/decimal.rst:1669 -msgid "" -"Signals represent conditions that arise during computation. Each corresponds " -"to one context flag and one context trap enabler." -msgstr "" - -#: ../../library/decimal.rst:1672 -msgid "" -"The context flag is set whenever the condition is encountered. After the " -"computation, flags may be checked for informational purposes (for instance, " -"to determine whether a computation was exact). After checking the flags, be " -"sure to clear all flags before starting the next computation." -msgstr "" - -#: ../../library/decimal.rst:1677 -msgid "" -"If the context's trap enabler is set for the signal, then the condition " -"causes a Python exception to be raised. For example, if the :class:" -"`DivisionByZero` trap is set, then a :exc:`DivisionByZero` exception is " -"raised upon encountering the condition." -msgstr "" - -#: ../../library/decimal.rst:1685 -msgid "Altered an exponent to fit representation constraints." -msgstr "" - -#: ../../library/decimal.rst:1687 -msgid "" -"Typically, clamping occurs when an exponent falls outside the context's :" -"attr:`~Context.Emin` and :attr:`~Context.Emax` limits. If possible, the " -"exponent is reduced to fit by adding zeros to the coefficient." -msgstr "" - -#: ../../library/decimal.rst:1694 -msgid "Base class for other signals and a subclass of :exc:`ArithmeticError`." -msgstr "" - -#: ../../library/decimal.rst:1699 -msgid "Signals the division of a non-infinite number by zero." -msgstr "" - -#: ../../library/decimal.rst:1701 -msgid "" -"Can occur with division, modulo division, or when raising a number to a " -"negative power. If this signal is not trapped, returns ``Infinity`` or ``-" -"Infinity`` with the sign determined by the inputs to the calculation." -msgstr "" - -#: ../../library/decimal.rst:1708 -msgid "Indicates that rounding occurred and the result is not exact." -msgstr "" - -#: ../../library/decimal.rst:1710 -msgid "" -"Signals when non-zero digits were discarded during rounding. The rounded " -"result is returned. The signal flag or trap is used to detect when results " -"are inexact." -msgstr "" - -#: ../../library/decimal.rst:1717 -msgid "An invalid operation was performed." -msgstr "" - -#: ../../library/decimal.rst:1719 -msgid "" -"Indicates that an operation was requested that does not make sense. If not " -"trapped, returns ``NaN``. Possible causes include::" -msgstr "" - -#: ../../library/decimal.rst:1722 -msgid "" -"Infinity - Infinity\n" -"0 * Infinity\n" -"Infinity / Infinity\n" -"x % 0\n" -"Infinity % x\n" -"sqrt(-x) and x > 0\n" -"0 ** 0\n" -"x ** (non-integer)\n" -"x ** Infinity" -msgstr "" -"Infinity - Infinity\n" -"0 * Infinity\n" -"Infinity / Infinity\n" -"x % 0\n" -"Infinity % x\n" -"sqrt(-x) and x > 0\n" -"0 ** 0\n" -"x ** (non-integer)\n" -"x ** Infinity" - -#: ../../library/decimal.rst:1735 -msgid "Numerical overflow." -msgstr "" - -#: ../../library/decimal.rst:1737 -msgid "" -"Indicates the exponent is larger than :attr:`Context.Emax` after rounding " -"has occurred. If not trapped, the result depends on the rounding mode, " -"either pulling inward to the largest representable finite number or rounding " -"outward to ``Infinity``. In either case, :class:`Inexact` and :class:" -"`Rounded` are also signaled." -msgstr "" - -#: ../../library/decimal.rst:1746 -msgid "Rounding occurred though possibly no information was lost." -msgstr "" - -#: ../../library/decimal.rst:1748 -msgid "" -"Signaled whenever rounding discards digits; even if those digits are zero " -"(such as rounding ``5.00`` to ``5.0``). If not trapped, returns the result " -"unchanged. This signal is used to detect loss of significant digits." -msgstr "" - -#: ../../library/decimal.rst:1756 -msgid "Exponent was lower than :attr:`~Context.Emin` prior to rounding." -msgstr "" - -#: ../../library/decimal.rst:1758 -msgid "" -"Occurs when an operation result is subnormal (the exponent is too small). If " -"not trapped, returns the result unchanged." -msgstr "" - -#: ../../library/decimal.rst:1764 -msgid "Numerical underflow with result rounded to zero." -msgstr "" - -#: ../../library/decimal.rst:1766 -msgid "" -"Occurs when a subnormal result is pushed to zero by rounding. :class:" -"`Inexact` and :class:`Subnormal` are also signaled." -msgstr "" - -#: ../../library/decimal.rst:1772 -msgid "Enable stricter semantics for mixing floats and Decimals." -msgstr "" - -#: ../../library/decimal.rst:1774 -msgid "" -"If the signal is not trapped (default), mixing floats and Decimals is " -"permitted in the :class:`~decimal.Decimal` constructor, :meth:`~decimal." -"Context.create_decimal` and all comparison operators. Both conversion and " -"comparisons are exact. Any occurrence of a mixed operation is silently " -"recorded by setting :exc:`FloatOperation` in the context flags. Explicit " -"conversions with :meth:`~decimal.Decimal.from_float` or :meth:`~decimal." -"Context.create_decimal_from_float` do not set the flag." -msgstr "" - -#: ../../library/decimal.rst:1782 -msgid "" -"Otherwise (the signal is trapped), only equality comparisons and explicit " -"conversions are silent. All other mixed operations raise :exc:" -"`FloatOperation`." -msgstr "" - -#: ../../library/decimal.rst:1786 -msgid "The following table summarizes the hierarchy of signals::" -msgstr "" - -#: ../../library/decimal.rst:1788 -msgid "" -"exceptions.ArithmeticError(exceptions.Exception)\n" -" DecimalException\n" -" Clamped\n" -" DivisionByZero(DecimalException, exceptions.ZeroDivisionError)\n" -" Inexact\n" -" Overflow(Inexact, Rounded)\n" -" Underflow(Inexact, Rounded, Subnormal)\n" -" InvalidOperation\n" -" Rounded\n" -" Subnormal\n" -" FloatOperation(DecimalException, exceptions.TypeError)" -msgstr "" -"exceptions.ArithmeticError(exceptions.Exception)\n" -" DecimalException\n" -" Clamped\n" -" DivisionByZero(DecimalException, exceptions.ZeroDivisionError)\n" -" Inexact\n" -" Overflow(Inexact, Rounded)\n" -" Underflow(Inexact, Rounded, Subnormal)\n" -" InvalidOperation\n" -" Rounded\n" -" Subnormal\n" -" FloatOperation(DecimalException, exceptions.TypeError)" - -#: ../../library/decimal.rst:1807 -msgid "Floating-point notes" -msgstr "" - -#: ../../library/decimal.rst:1811 -msgid "Mitigating round-off error with increased precision" -msgstr "" - -#: ../../library/decimal.rst:1813 -msgid "" -"The use of decimal floating point eliminates decimal representation error " -"(making it possible to represent ``0.1`` exactly); however, some operations " -"can still incur round-off error when non-zero digits exceed the fixed " -"precision." -msgstr "" - -#: ../../library/decimal.rst:1817 -msgid "" -"The effects of round-off error can be amplified by the addition or " -"subtraction of nearly offsetting quantities resulting in loss of " -"significance. Knuth provides two instructive examples where rounded " -"floating-point arithmetic with insufficient precision causes the breakdown " -"of the associative and distributive properties of addition:" -msgstr "" - -#: ../../library/decimal.rst:1823 -msgid "" -"# Examples from Seminumerical Algorithms, Section 4.2.2.\n" -">>> from decimal import Decimal, getcontext\n" -">>> getcontext().prec = 8\n" -"\n" -">>> u, v, w = Decimal(11111113), Decimal(-11111111), Decimal('7.51111111')\n" -">>> (u + v) + w\n" -"Decimal('9.5111111')\n" -">>> u + (v + w)\n" -"Decimal('10')\n" -"\n" -">>> u, v, w = Decimal(20000), Decimal(-6), Decimal('6.0000003')\n" -">>> (u*v) + (u*w)\n" -"Decimal('0.01')\n" -">>> u * (v+w)\n" -"Decimal('0.0060000')" -msgstr "" - -#: ../../library/decimal.rst:1841 -msgid "" -"The :mod:`decimal` module makes it possible to restore the identities by " -"expanding the precision sufficiently to avoid loss of significance:" -msgstr "" - -#: ../../library/decimal.rst:1844 -msgid "" -">>> getcontext().prec = 20\n" -">>> u, v, w = Decimal(11111113), Decimal(-11111111), Decimal('7.51111111')\n" -">>> (u + v) + w\n" -"Decimal('9.51111111')\n" -">>> u + (v + w)\n" -"Decimal('9.51111111')\n" -">>>\n" -">>> u, v, w = Decimal(20000), Decimal(-6), Decimal('6.0000003')\n" -">>> (u*v) + (u*w)\n" -"Decimal('0.0060000')\n" -">>> u * (v+w)\n" -"Decimal('0.0060000')" -msgstr "" -">>> getcontext().prec = 20\n" -">>> u, v, w = Decimal(11111113), Decimal(-11111111), Decimal('7.51111111')\n" -">>> (u + v) + w\n" -"Decimal('9.51111111')\n" -">>> u + (v + w)\n" -"Decimal('9.51111111')\n" -">>>\n" -">>> u, v, w = Decimal(20000), Decimal(-6), Decimal('6.0000003')\n" -">>> (u*v) + (u*w)\n" -"Decimal('0.0060000')\n" -">>> u * (v+w)\n" -"Decimal('0.0060000')" - -#: ../../library/decimal.rst:1861 -msgid "Special values" -msgstr "特殊值" - -#: ../../library/decimal.rst:1863 -msgid "" -"The number system for the :mod:`decimal` module provides special values " -"including ``NaN``, ``sNaN``, ``-Infinity``, ``Infinity``, and two zeros, " -"``+0`` and ``-0``." -msgstr "" - -#: ../../library/decimal.rst:1867 -msgid "" -"Infinities can be constructed directly with: ``Decimal('Infinity')``. Also, " -"they can arise from dividing by zero when the :exc:`DivisionByZero` signal " -"is not trapped. Likewise, when the :exc:`Overflow` signal is not trapped, " -"infinity can result from rounding beyond the limits of the largest " -"representable number." -msgstr "" - -#: ../../library/decimal.rst:1872 -msgid "" -"The infinities are signed (affine) and can be used in arithmetic operations " -"where they get treated as very large, indeterminate numbers. For instance, " -"adding a constant to infinity gives another infinite result." -msgstr "" - -#: ../../library/decimal.rst:1876 -msgid "" -"Some operations are indeterminate and return ``NaN``, or if the :exc:" -"`InvalidOperation` signal is trapped, raise an exception. For example, " -"``0/0`` returns ``NaN`` which means \"not a number\". This variety of " -"``NaN`` is quiet and, once created, will flow through other computations " -"always resulting in another ``NaN``. This behavior can be useful for a " -"series of computations that occasionally have missing inputs --- it allows " -"the calculation to proceed while flagging specific results as invalid." -msgstr "" - -#: ../../library/decimal.rst:1884 -msgid "" -"A variant is ``sNaN`` which signals rather than remaining quiet after every " -"operation. This is a useful return value when an invalid result needs to " -"interrupt a calculation for special handling." -msgstr "" - -#: ../../library/decimal.rst:1888 -msgid "" -"The behavior of Python's comparison operators can be a little surprising " -"where a ``NaN`` is involved. A test for equality where one of the operands " -"is a quiet or signaling ``NaN`` always returns :const:`False` (even when " -"doing ``Decimal('NaN')==Decimal('NaN')``), while a test for inequality " -"always returns :const:`True`. An attempt to compare two Decimals using any " -"of the ``<``, ``<=``, ``>`` or ``>=`` operators will raise the :exc:" -"`InvalidOperation` signal if either operand is a ``NaN``, and return :const:" -"`False` if this signal is not trapped. Note that the General Decimal " -"Arithmetic specification does not specify the behavior of direct " -"comparisons; these rules for comparisons involving a ``NaN`` were taken from " -"the IEEE 854 standard (see Table 3 in section 5.7). To ensure strict " -"standards-compliance, use the :meth:`~Decimal.compare` and :meth:`~Decimal." -"compare_signal` methods instead." -msgstr "" - -#: ../../library/decimal.rst:1901 -msgid "" -"The signed zeros can result from calculations that underflow. They keep the " -"sign that would have resulted if the calculation had been carried out to " -"greater precision. Since their magnitude is zero, both positive and " -"negative zeros are treated as equal and their sign is informational." -msgstr "" - -#: ../../library/decimal.rst:1906 -msgid "" -"In addition to the two signed zeros which are distinct yet equal, there are " -"various representations of zero with differing precisions yet equivalent in " -"value. This takes a bit of getting used to. For an eye accustomed to " -"normalized floating-point representations, it is not immediately obvious " -"that the following calculation returns a value equal to zero:" -msgstr "" - -#: ../../library/decimal.rst:1921 -msgid "Working with threads" -msgstr "" - -#: ../../library/decimal.rst:1923 -msgid "" -"The :func:`getcontext` function accesses a different :class:`Context` object " -"for each thread. Having separate thread contexts means that threads may " -"make changes (such as ``getcontext().prec=10``) without interfering with " -"other threads." -msgstr "" - -#: ../../library/decimal.rst:1927 -msgid "" -"Likewise, the :func:`setcontext` function automatically assigns its target " -"to the current thread." -msgstr "" - -#: ../../library/decimal.rst:1930 -msgid "" -"If :func:`setcontext` has not been called before :func:`getcontext`, then :" -"func:`getcontext` will automatically create a new context for use in the " -"current thread. New context objects have default values set from the :data:" -"`decimal.DefaultContext` object." -msgstr "" - -#: ../../library/decimal.rst:1935 -msgid "" -"The :data:`sys.flags.thread_inherit_context` flag affects the context for " -"new threads. If the flag is false, new threads will start with an empty " -"context. In this case, :func:`getcontext` will create a new context object " -"when called and use the default values from *DefaultContext*. If the flag " -"is true, new threads will start with a copy of context from the caller of :" -"meth:`threading.Thread.start`." -msgstr "" - -#: ../../library/decimal.rst:1942 -msgid "" -"To control the defaults so that each thread will use the same values " -"throughout the application, directly modify the *DefaultContext* object. " -"This should be done *before* any threads are started so that there won't be " -"a race condition between threads calling :func:`getcontext`. For example::" -msgstr "" - -#: ../../library/decimal.rst:1947 -msgid "" -"# Set applicationwide defaults for all threads about to be launched\n" -"DefaultContext.prec = 12\n" -"DefaultContext.rounding = ROUND_DOWN\n" -"DefaultContext.traps = ExtendedContext.traps.copy()\n" -"DefaultContext.traps[InvalidOperation] = 1\n" -"setcontext(DefaultContext)\n" -"\n" -"# Afterwards, the threads can be started\n" -"t1.start()\n" -"t2.start()\n" -"t3.start()\n" -" . . ." -msgstr "" - -#: ../../library/decimal.rst:1966 -msgid "Recipes" -msgstr "" - -#: ../../library/decimal.rst:1968 -msgid "" -"Here are a few recipes that serve as utility functions and that demonstrate " -"ways to work with the :class:`Decimal` class::" -msgstr "" - -#: ../../library/decimal.rst:1971 -msgid "" -"def moneyfmt(value, places=2, curr='', sep=',', dp='.',\n" -" pos='', neg='-', trailneg=''):\n" -" \"\"\"Convert Decimal to a money formatted string.\n" -"\n" -" places: required number of places after the decimal point\n" -" curr: optional currency symbol before the sign (may be blank)\n" -" sep: optional grouping separator (comma, period, space, or blank)\n" -" dp: decimal point indicator (comma or period)\n" -" only specify as blank when places is zero\n" -" pos: optional sign for positive numbers: '+', space or blank\n" -" neg: optional sign for negative numbers: '-', '(', space or blank\n" -" trailneg:optional trailing minus indicator: '-', ')', space or blank\n" -"\n" -" >>> d = Decimal('-1234567.8901')\n" -" >>> moneyfmt(d, curr='$')\n" -" '-$1,234,567.89'\n" -" >>> moneyfmt(d, places=0, sep='.', dp='', neg='', trailneg='-')\n" -" '1.234.568-'\n" -" >>> moneyfmt(d, curr='$', neg='(', trailneg=')')\n" -" '($1,234,567.89)'\n" -" >>> moneyfmt(Decimal(123456789), sep=' ')\n" -" '123 456 789.00'\n" -" >>> moneyfmt(Decimal('-0.02'), neg='<', trailneg='>')\n" -" '<0.02>'\n" -"\n" -" \"\"\"\n" -" q = Decimal(10) ** -places # 2 places --> '0.01'\n" -" sign, digits, exp = value.quantize(q).as_tuple()\n" -" result = []\n" -" digits = list(map(str, digits))\n" -" build, next = result.append, digits.pop\n" -" if sign:\n" -" build(trailneg)\n" -" for i in range(places):\n" -" build(next() if digits else '0')\n" -" if places:\n" -" build(dp)\n" -" if not digits:\n" -" build('0')\n" -" i = 0\n" -" while digits:\n" -" build(next())\n" -" i += 1\n" -" if i == 3 and digits:\n" -" i = 0\n" -" build(sep)\n" -" build(curr)\n" -" build(neg if sign else pos)\n" -" return ''.join(reversed(result))\n" -"\n" -"def pi():\n" -" \"\"\"Compute Pi to the current precision.\n" -"\n" -" >>> print(pi())\n" -" 3.141592653589793238462643383\n" -"\n" -" \"\"\"\n" -" getcontext().prec += 2 # extra digits for intermediate steps\n" -" three = Decimal(3) # substitute \"three=3.0\" for regular floats\n" -" lasts, t, s, n, na, d, da = 0, three, 3, 1, 0, 0, 24\n" -" while s != lasts:\n" -" lasts = s\n" -" n, na = n+na, na+8\n" -" d, da = d+da, da+32\n" -" t = (t * n) / d\n" -" s += t\n" -" getcontext().prec -= 2\n" -" return +s # unary plus applies the new precision\n" -"\n" -"def exp(x):\n" -" \"\"\"Return e raised to the power of x. Result type matches input " -"type.\n" -"\n" -" >>> print(exp(Decimal(1)))\n" -" 2.718281828459045235360287471\n" -" >>> print(exp(Decimal(2)))\n" -" 7.389056098930650227230427461\n" -" >>> print(exp(2.0))\n" -" 7.38905609893\n" -" >>> print(exp(2+0j))\n" -" (7.38905609893+0j)\n" -"\n" -" \"\"\"\n" -" getcontext().prec += 2\n" -" i, lasts, s, fact, num = 0, 0, 1, 1, 1\n" -" while s != lasts:\n" -" lasts = s\n" -" i += 1\n" -" fact *= i\n" -" num *= x\n" -" s += num / fact\n" -" getcontext().prec -= 2\n" -" return +s\n" -"\n" -"def cos(x):\n" -" \"\"\"Return the cosine of x as measured in radians.\n" -"\n" -" The Taylor series approximation works best for a small value of x.\n" -" For larger values, first compute x = x % (2 * pi).\n" -"\n" -" >>> print(cos(Decimal('0.5')))\n" -" 0.8775825618903727161162815826\n" -" >>> print(cos(0.5))\n" -" 0.87758256189\n" -" >>> print(cos(0.5+0j))\n" -" (0.87758256189+0j)\n" -"\n" -" \"\"\"\n" -" getcontext().prec += 2\n" -" i, lasts, s, fact, num, sign = 0, 0, 1, 1, 1, 1\n" -" while s != lasts:\n" -" lasts = s\n" -" i += 2\n" -" fact *= i * (i-1)\n" -" num *= x * x\n" -" sign *= -1\n" -" s += num / fact * sign\n" -" getcontext().prec -= 2\n" -" return +s\n" -"\n" -"def sin(x):\n" -" \"\"\"Return the sine of x as measured in radians.\n" -"\n" -" The Taylor series approximation works best for a small value of x.\n" -" For larger values, first compute x = x % (2 * pi).\n" -"\n" -" >>> print(sin(Decimal('0.5')))\n" -" 0.4794255386042030002732879352\n" -" >>> print(sin(0.5))\n" -" 0.479425538604\n" -" >>> print(sin(0.5+0j))\n" -" (0.479425538604+0j)\n" -"\n" -" \"\"\"\n" -" getcontext().prec += 2\n" -" i, lasts, s, fact, num, sign = 1, 0, x, 1, x, 1\n" -" while s != lasts:\n" -" lasts = s\n" -" i += 2\n" -" fact *= i * (i-1)\n" -" num *= x * x\n" -" sign *= -1\n" -" s += num / fact * sign\n" -" getcontext().prec -= 2\n" -" return +s" -msgstr "" - -#: ../../library/decimal.rst:2123 -msgid "Decimal FAQ" -msgstr "" - -#: ../../library/decimal.rst:2125 -msgid "" -"Q: It is cumbersome to type ``decimal.Decimal('1234.5')``. Is there a way " -"to minimize typing when using the interactive interpreter?" -msgstr "" - -#: ../../library/decimal.rst:2128 -msgid "A: Some users abbreviate the constructor to just a single letter:" -msgstr "" - -#: ../../library/decimal.rst:2134 -msgid "" -"Q: In a fixed-point application with two decimal places, some inputs have " -"many places and need to be rounded. Others are not supposed to have excess " -"digits and need to be validated. What methods should be used?" -msgstr "" - -#: ../../library/decimal.rst:2138 -msgid "" -"A: The :meth:`~Decimal.quantize` method rounds to a fixed number of decimal " -"places. If the :const:`Inexact` trap is set, it is also useful for " -"validation:" -msgstr "" - -#: ../../library/decimal.rst:2156 -msgid "" -"Q: Once I have valid two place inputs, how do I maintain that invariant " -"throughout an application?" -msgstr "" - -#: ../../library/decimal.rst:2159 -msgid "" -"A: Some operations like addition, subtraction, and multiplication by an " -"integer will automatically preserve fixed point. Others operations, like " -"division and non-integer multiplication, will change the number of decimal " -"places and need to be followed-up with a :meth:`~Decimal.quantize` step:" -msgstr "" - -#: ../../library/decimal.rst:2177 -msgid "" -"In developing fixed-point applications, it is convenient to define functions " -"to handle the :meth:`~Decimal.quantize` step:" -msgstr "" - -#: ../../library/decimal.rst:2191 -msgid "" -"Q: There are many ways to express the same value. The numbers ``200``, " -"``200.000``, ``2E2``, and ``.02E+4`` all have the same value at various " -"precisions. Is there a way to transform them to a single recognizable " -"canonical value?" -msgstr "" - -#: ../../library/decimal.rst:2196 -msgid "" -"A: The :meth:`~Decimal.normalize` method maps all equivalent values to a " -"single representative:" -msgstr "" - -#: ../../library/decimal.rst:2203 -msgid "Q: When does rounding occur in a computation?" -msgstr "" - -#: ../../library/decimal.rst:2205 -msgid "" -"A: It occurs *after* the computation. The philosophy of the decimal " -"specification is that numbers are considered exact and are created " -"independent of the current context. They can even have greater precision " -"than current context. Computations process with those exact inputs and then " -"rounding (or other context operations) is applied to the *result* of the " -"computation::" -msgstr "" - -#: ../../library/decimal.rst:2212 -msgid "" -">>> getcontext().prec = 5\n" -">>> pi = Decimal('3.1415926535') # More than 5 digits\n" -">>> pi # All digits are retained\n" -"Decimal('3.1415926535')\n" -">>> pi + 0 # Rounded after an addition\n" -"Decimal('3.1416')\n" -">>> pi - Decimal('0.00005') # Subtract unrounded numbers, then round\n" -"Decimal('3.1415')\n" -">>> pi + 0 - Decimal('0.00005'). # Intermediate values are rounded\n" -"Decimal('3.1416')" -msgstr "" - -#: ../../library/decimal.rst:2223 -msgid "" -"Q: Some decimal values always print with exponential notation. Is there a " -"way to get a non-exponential representation?" -msgstr "" - -#: ../../library/decimal.rst:2226 -msgid "" -"A: For some values, exponential notation is the only way to express the " -"number of significant places in the coefficient. For example, expressing " -"``5.0E+3`` as ``5000`` keeps the value constant but cannot show the " -"original's two-place significance." -msgstr "" - -#: ../../library/decimal.rst:2231 -msgid "" -"If an application does not care about tracking significance, it is easy to " -"remove the exponent and trailing zeroes, losing significance, but keeping " -"the value unchanged:" -msgstr "" - -#: ../../library/decimal.rst:2241 -msgid "Q: Is there a way to convert a regular float to a :class:`Decimal`?" -msgstr "" - -#: ../../library/decimal.rst:2243 -msgid "" -"A: Yes, any binary floating-point number can be exactly expressed as a " -"Decimal though an exact conversion may take more precision than intuition " -"would suggest:" -msgstr "" - -#: ../../library/decimal.rst:2247 -msgid "" -">>> Decimal(math.pi)\n" -"Decimal('3.141592653589793115997963468544185161590576171875')" -msgstr "" -">>> Decimal(math.pi)\n" -"Decimal('3.141592653589793115997963468544185161590576171875')" - -#: ../../library/decimal.rst:2252 -msgid "" -"Q: Within a complex calculation, how can I make sure that I haven't gotten a " -"spurious result because of insufficient precision or rounding anomalies." -msgstr "" - -#: ../../library/decimal.rst:2255 -msgid "" -"A: The decimal module makes it easy to test results. A best practice is to " -"re-run calculations using greater precision and with various rounding modes. " -"Widely differing results indicate insufficient precision, rounding mode " -"issues, ill-conditioned inputs, or a numerically unstable algorithm." -msgstr "" - -#: ../../library/decimal.rst:2260 -msgid "" -"Q: I noticed that context precision is applied to the results of operations " -"but not to the inputs. Is there anything to watch out for when mixing " -"values of different precisions?" -msgstr "" - -#: ../../library/decimal.rst:2264 -msgid "" -"A: Yes. The principle is that all values are considered to be exact and so " -"is the arithmetic on those values. Only the results are rounded. The " -"advantage for inputs is that \"what you type is what you get\". A " -"disadvantage is that the results can look odd if you forget that the inputs " -"haven't been rounded:" -msgstr "" - -#: ../../library/decimal.rst:2269 -msgid "" -">>> getcontext().prec = 3\n" -">>> Decimal('3.104') + Decimal('2.104')\n" -"Decimal('5.21')\n" -">>> Decimal('3.104') + Decimal('0.000') + Decimal('2.104')\n" -"Decimal('5.20')" -msgstr "" -">>> getcontext().prec = 3\n" -">>> Decimal('3.104') + Decimal('2.104')\n" -"Decimal('5.21')\n" -">>> Decimal('3.104') + Decimal('0.000') + Decimal('2.104')\n" -"Decimal('5.20')" - -#: ../../library/decimal.rst:2277 -msgid "" -"The solution is either to increase precision or to force rounding of inputs " -"using the unary plus operation:" -msgstr "" - -#: ../../library/decimal.rst:2280 -msgid "" -">>> getcontext().prec = 3\n" -">>> +Decimal('1.23456789') # unary plus triggers rounding\n" -"Decimal('1.23')" -msgstr "" - -#: ../../library/decimal.rst:2286 -msgid "" -"Alternatively, inputs can be rounded upon creation using the :meth:`Context." -"create_decimal` method:" -msgstr "" - -#: ../../library/decimal.rst:2292 -msgid "Q: Is the CPython implementation fast for large numbers?" -msgstr "" - -#: ../../library/decimal.rst:2294 -msgid "" -"A: Yes. In the CPython and PyPy3 implementations, the C/CFFI versions of " -"the decimal module integrate the high speed `libmpdec `_ library for arbitrary precision " -"correctly rounded decimal floating-point arithmetic [#]_. ``libmpdec`` uses " -"`Karatsuba multiplication `_ for medium-sized numbers and the `Number Theoretic " -"Transform `_ for very " -"large numbers." -msgstr "" - -#: ../../library/decimal.rst:2304 -msgid "" -"The context must be adapted for exact arbitrary precision arithmetic. :attr:" -"`~Context.Emin` and :attr:`~Context.Emax` should always be set to the " -"maximum values, :attr:`~Context.clamp` should always be 0 (the default). " -"Setting :attr:`~Context.prec` requires some care." -msgstr "" - -#: ../../library/decimal.rst:2308 -msgid "" -"The easiest approach for trying out bignum arithmetic is to use the maximum " -"value for :attr:`~Context.prec` as well [#]_::" -msgstr "" - -#: ../../library/decimal.rst:2311 -msgid "" -">>> setcontext(Context(prec=MAX_PREC, Emax=MAX_EMAX, Emin=MIN_EMIN))\n" -">>> x = Decimal(2) ** 256\n" -">>> x / 128\n" -"Decimal('904625697166532776746648320380374280103671755200316906558262375061821325312')" -msgstr "" -">>> setcontext(Context(prec=MAX_PREC, Emax=MAX_EMAX, Emin=MIN_EMIN))\n" -">>> x = Decimal(2) ** 256\n" -">>> x / 128\n" -"Decimal('904625697166532776746648320380374280103671755200316906558262375061821325312')" - -#: ../../library/decimal.rst:2317 -msgid "" -"For inexact results, :const:`MAX_PREC` is far too large on 64-bit platforms " -"and the available memory will be insufficient::" -msgstr "" - -#: ../../library/decimal.rst:2320 -msgid "" -">>> Decimal(1) / 3\n" -"Traceback (most recent call last):\n" -" File \"\", line 1, in \n" -"MemoryError" -msgstr "" -">>> Decimal(1) / 3\n" -"Traceback (most recent call last):\n" -" File \"\", line 1, in \n" -"MemoryError" - -#: ../../library/decimal.rst:2325 -msgid "" -"On systems with overallocation (e.g. Linux), a more sophisticated approach " -"is to adjust :attr:`~Context.prec` to the amount of available RAM. Suppose " -"that you have 8GB of RAM and expect 10 simultaneous operands using a maximum " -"of 500MB each::" -msgstr "" - -#: ../../library/decimal.rst:2329 -msgid "" -">>> import sys\n" -">>>\n" -">>> # Maximum number of digits for a single operand using 500MB in 8-byte " -"words\n" -">>> # with 19 digits per word (4-byte and 9 digits for the 32-bit build):\n" -">>> maxdigits = 19 * ((500 * 1024**2) // 8)\n" -">>>\n" -">>> # Check that this works:\n" -">>> c = Context(prec=maxdigits, Emax=MAX_EMAX, Emin=MIN_EMIN)\n" -">>> c.traps[Inexact] = True\n" -">>> setcontext(c)\n" -">>>\n" -">>> # Fill the available precision with nines:\n" -">>> x = Decimal(0).logical_invert() * 9\n" -">>> sys.getsizeof(x)\n" -"524288112\n" -">>> x + 2\n" -"Traceback (most recent call last):\n" -" File \"\", line 1, in \n" -" decimal.Inexact: []" -msgstr "" - -#: ../../library/decimal.rst:2349 -msgid "" -"In general (and especially on systems without overallocation), it is " -"recommended to estimate even tighter bounds and set the :attr:`Inexact` trap " -"if all calculations are expected to be exact." -msgstr "" - -#: ../../library/decimal.rst:2358 -msgid "" -"This approach now works for all exact results except for non-integer powers." -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-12-17 17:02+0000\n" +"PO-Revision-Date: 2018-05-23 14:43+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/decimal.rst:2 +msgid ":mod:`!decimal` --- Decimal fixed-point and floating-point arithmetic" +msgstr ":mod:`!decimal` --- 十進位固定點和浮點運算" + +#: ../../library/decimal.rst:15 +msgid "**Source code:** :source:`Lib/decimal.py`" +msgstr "**原始碼：**\\ :source:`Lib/decimal.py`" + +#: ../../library/decimal.rst:33 +msgid "" +"The :mod:`decimal` module provides support for fast correctly rounded " +"decimal floating-point arithmetic. It offers several advantages over the :" +"class:`float` datatype:" +msgstr "" + +#: ../../library/decimal.rst:37 +msgid "" +"Decimal \"is based on a `floating-point model `__ which was designed with people in mind, " +"and necessarily has a paramount guiding principle -- computers must provide " +"an arithmetic that works in the same way as the arithmetic that people learn " +"at school.\" -- excerpt from the decimal arithmetic specification." +msgstr "" + +#: ../../library/decimal.rst:44 +msgid "" +"Decimal numbers can be represented exactly. In contrast, numbers like " +"``1.1`` and ``2.2`` do not have exact representations in binary floating " +"point. End users typically would not expect ``1.1 + 2.2`` to display as " +"``3.3000000000000003`` as it does with binary floating point." +msgstr "" + +#: ../../library/decimal.rst:49 +msgid "" +"The exactness carries over into arithmetic. In decimal floating point, " +"``0.1 + 0.1 + 0.1 - 0.3`` is exactly equal to zero. In binary floating " +"point, the result is ``5.5511151231257827e-017``. While near to zero, the " +"differences prevent reliable equality testing and differences can " +"accumulate. For this reason, decimal is preferred in accounting applications " +"which have strict equality invariants." +msgstr "" + +#: ../../library/decimal.rst:56 +msgid "" +"The decimal module incorporates a notion of significant places so that " +"``1.30 + 1.20`` is ``2.50``. The trailing zero is kept to indicate " +"significance. This is the customary presentation for monetary applications. " +"For multiplication, the \"schoolbook\" approach uses all the figures in the " +"multiplicands. For instance, ``1.3 * 1.2`` gives ``1.56`` while ``1.30 * " +"1.20`` gives ``1.5600``." +msgstr "" + +#: ../../library/decimal.rst:63 +msgid "" +"Unlike hardware based binary floating point, the decimal module has a user " +"alterable precision (defaulting to 28 places) which can be as large as " +"needed for a given problem:" +msgstr "" + +#: ../../library/decimal.rst:75 +msgid "" +"Both binary and decimal floating point are implemented in terms of published " +"standards. While the built-in float type exposes only a modest portion of " +"its capabilities, the decimal module exposes all required parts of the " +"standard. When needed, the programmer has full control over rounding and " +"signal handling. This includes an option to enforce exact arithmetic by " +"using exceptions to block any inexact operations." +msgstr "" + +#: ../../library/decimal.rst:82 +msgid "" +"The decimal module was designed to support \"without prejudice, both exact " +"unrounded decimal arithmetic (sometimes called fixed-point arithmetic) and " +"rounded floating-point arithmetic.\" -- excerpt from the decimal arithmetic " +"specification." +msgstr "" + +#: ../../library/decimal.rst:87 +msgid "" +"The module design is centered around three concepts: the decimal number, " +"the context for arithmetic, and signals." +msgstr "" + +#: ../../library/decimal.rst:90 +msgid "" +"A decimal number is immutable. It has a sign, coefficient digits, and an " +"exponent. To preserve significance, the coefficient digits do not truncate " +"trailing zeros. Decimals also include special values such as ``Infinity``, " +"``-Infinity``, and ``NaN``. The standard also differentiates ``-0`` from " +"``+0``." +msgstr "" + +#: ../../library/decimal.rst:96 +msgid "" +"The context for arithmetic is an environment specifying precision, rounding " +"rules, limits on exponents, flags indicating the results of operations, and " +"trap enablers which determine whether signals are treated as exceptions. " +"Rounding options include :const:`ROUND_CEILING`, :const:`ROUND_DOWN`, :const:" +"`ROUND_FLOOR`, :const:`ROUND_HALF_DOWN`, :const:`ROUND_HALF_EVEN`, :const:" +"`ROUND_HALF_UP`, :const:`ROUND_UP`, and :const:`ROUND_05UP`." +msgstr "" + +#: ../../library/decimal.rst:103 +msgid "" +"Signals are groups of exceptional conditions arising during the course of " +"computation. Depending on the needs of the application, signals may be " +"ignored, considered as informational, or treated as exceptions. The signals " +"in the decimal module are: :const:`Clamped`, :const:`InvalidOperation`, :" +"const:`DivisionByZero`, :const:`Inexact`, :const:`Rounded`, :const:" +"`Subnormal`, :const:`Overflow`, :const:`Underflow` and :const:" +"`FloatOperation`." +msgstr "" + +#: ../../library/decimal.rst:110 +msgid "" +"For each signal there is a flag and a trap enabler. When a signal is " +"encountered, its flag is set to one, then, if the trap enabler is set to " +"one, an exception is raised. Flags are sticky, so the user needs to reset " +"them before monitoring a calculation." +msgstr "" + +#: ../../library/decimal.rst:118 +msgid "" +"IBM's General Decimal Arithmetic Specification, `The General Decimal " +"Arithmetic Specification `_." +msgstr "" + +#: ../../library/decimal.rst:127 +msgid "Quick-start tutorial" +msgstr "" + +#: ../../library/decimal.rst:129 +msgid "" +"The usual start to using decimals is importing the module, viewing the " +"current context with :func:`getcontext` and, if necessary, setting new " +"values for precision, rounding, or enabled traps::" +msgstr "" + +#: ../../library/decimal.rst:133 +msgid "" +">>> from decimal import *\n" +">>> getcontext()\n" +"Context(prec=28, rounding=ROUND_HALF_EVEN, Emin=-999999, Emax=999999,\n" +" capitals=1, clamp=0, flags=[], traps=[Overflow, DivisionByZero,\n" +" InvalidOperation])\n" +"\n" +">>> getcontext().prec = 7 # Set a new precision" +msgstr "" + +#: ../../library/decimal.rst:141 +msgid "" +"Decimal instances can be constructed from integers, strings, floats, or " +"tuples. Construction from an integer or a float performs an exact conversion " +"of the value of that integer or float. Decimal numbers include special " +"values such as ``NaN`` which stands for \"Not a number\", positive and " +"negative ``Infinity``, and ``-0``::" +msgstr "" + +#: ../../library/decimal.rst:147 +msgid "" +">>> getcontext().prec = 28\n" +">>> Decimal(10)\n" +"Decimal('10')\n" +">>> Decimal('3.14')\n" +"Decimal('3.14')\n" +">>> Decimal(3.14)\n" +"Decimal('3.140000000000000124344978758017532527446746826171875')\n" +">>> Decimal((0, (3, 1, 4), -2))\n" +"Decimal('3.14')\n" +">>> Decimal(str(2.0 ** 0.5))\n" +"Decimal('1.4142135623730951')\n" +">>> Decimal(2) ** Decimal('0.5')\n" +"Decimal('1.414213562373095048801688724')\n" +">>> Decimal('NaN')\n" +"Decimal('NaN')\n" +">>> Decimal('-Infinity')\n" +"Decimal('-Infinity')" +msgstr "" +">>> getcontext().prec = 28\n" +">>> Decimal(10)\n" +"Decimal('10')\n" +">>> Decimal('3.14')\n" +"Decimal('3.14')\n" +">>> Decimal(3.14)\n" +"Decimal('3.140000000000000124344978758017532527446746826171875')\n" +">>> Decimal((0, (3, 1, 4), -2))\n" +"Decimal('3.14')\n" +">>> Decimal(str(2.0 ** 0.5))\n" +"Decimal('1.4142135623730951')\n" +">>> Decimal(2) ** Decimal('0.5')\n" +"Decimal('1.414213562373095048801688724')\n" +">>> Decimal('NaN')\n" +"Decimal('NaN')\n" +">>> Decimal('-Infinity')\n" +"Decimal('-Infinity')" + +#: ../../library/decimal.rst:165 +msgid "" +"If the :exc:`FloatOperation` signal is trapped, accidental mixing of " +"decimals and floats in constructors or ordering comparisons raises an " +"exception::" +msgstr "" + +#: ../../library/decimal.rst:169 +msgid "" +">>> c = getcontext()\n" +">>> c.traps[FloatOperation] = True\n" +">>> Decimal(3.14)\n" +"Traceback (most recent call last):\n" +" File \"\", line 1, in \n" +"decimal.FloatOperation: []\n" +">>> Decimal('3.5') < 3.7\n" +"Traceback (most recent call last):\n" +" File \"\", line 1, in \n" +"decimal.FloatOperation: []\n" +">>> Decimal('3.5') == 3.5\n" +"True" +msgstr "" +">>> c = getcontext()\n" +">>> c.traps[FloatOperation] = True\n" +">>> Decimal(3.14)\n" +"Traceback (most recent call last):\n" +" File \"\", line 1, in \n" +"decimal.FloatOperation: []\n" +">>> Decimal('3.5') < 3.7\n" +"Traceback (most recent call last):\n" +" File \"\", line 1, in \n" +"decimal.FloatOperation: []\n" +">>> Decimal('3.5') == 3.5\n" +"True" + +#: ../../library/decimal.rst:184 +msgid "" +"The significance of a new Decimal is determined solely by the number of " +"digits input. Context precision and rounding only come into play during " +"arithmetic operations." +msgstr "" + +#: ../../library/decimal.rst:188 +msgid "" +">>> getcontext().prec = 6\n" +">>> Decimal('3.0')\n" +"Decimal('3.0')\n" +">>> Decimal('3.1415926535')\n" +"Decimal('3.1415926535')\n" +">>> Decimal('3.1415926535') + Decimal('2.7182818285')\n" +"Decimal('5.85987')\n" +">>> getcontext().rounding = ROUND_UP\n" +">>> Decimal('3.1415926535') + Decimal('2.7182818285')\n" +"Decimal('5.85988')" +msgstr "" +">>> getcontext().prec = 6\n" +">>> Decimal('3.0')\n" +"Decimal('3.0')\n" +">>> Decimal('3.1415926535')\n" +"Decimal('3.1415926535')\n" +">>> Decimal('3.1415926535') + Decimal('2.7182818285')\n" +"Decimal('5.85987')\n" +">>> getcontext().rounding = ROUND_UP\n" +">>> Decimal('3.1415926535') + Decimal('2.7182818285')\n" +"Decimal('5.85988')" + +#: ../../library/decimal.rst:201 +msgid "" +"If the internal limits of the C version are exceeded, constructing a decimal " +"raises :class:`InvalidOperation`::" +msgstr "" + +#: ../../library/decimal.rst:204 +msgid "" +">>> Decimal(\"1e9999999999999999999\")\n" +"Traceback (most recent call last):\n" +" File \"\", line 1, in \n" +"decimal.InvalidOperation: []" +msgstr "" +">>> Decimal(\"1e9999999999999999999\")\n" +"Traceback (most recent call last):\n" +" File \"\", line 1, in \n" +"decimal.InvalidOperation: []" + +#: ../../library/decimal.rst:211 +msgid "" +"Decimals interact well with much of the rest of Python. Here is a small " +"decimal floating-point flying circus:" +msgstr "" + +#: ../../library/decimal.rst:214 +msgid "" +">>> data = list(map(Decimal, '1.34 1.87 3.45 2.35 1.00 0.03 9.25'.split()))\n" +">>> max(data)\n" +"Decimal('9.25')\n" +">>> min(data)\n" +"Decimal('0.03')\n" +">>> sorted(data)\n" +"[Decimal('0.03'), Decimal('1.00'), Decimal('1.34'), Decimal('1.87'),\n" +" Decimal('2.35'), Decimal('3.45'), Decimal('9.25')]\n" +">>> sum(data)\n" +"Decimal('19.29')\n" +">>> a,b,c = data[:3]\n" +">>> str(a)\n" +"'1.34'\n" +">>> float(a)\n" +"1.34\n" +">>> round(a, 1)\n" +"Decimal('1.3')\n" +">>> int(a)\n" +"1\n" +">>> a * 5\n" +"Decimal('6.70')\n" +">>> a * b\n" +"Decimal('2.5058')\n" +">>> c % a\n" +"Decimal('0.77')" +msgstr "" +">>> data = list(map(Decimal, '1.34 1.87 3.45 2.35 1.00 0.03 9.25'.split()))\n" +">>> max(data)\n" +"Decimal('9.25')\n" +">>> min(data)\n" +"Decimal('0.03')\n" +">>> sorted(data)\n" +"[Decimal('0.03'), Decimal('1.00'), Decimal('1.34'), Decimal('1.87'),\n" +" Decimal('2.35'), Decimal('3.45'), Decimal('9.25')]\n" +">>> sum(data)\n" +"Decimal('19.29')\n" +">>> a,b,c = data[:3]\n" +">>> str(a)\n" +"'1.34'\n" +">>> float(a)\n" +"1.34\n" +">>> round(a, 1)\n" +"Decimal('1.3')\n" +">>> int(a)\n" +"1\n" +">>> a * 5\n" +"Decimal('6.70')\n" +">>> a * b\n" +"Decimal('2.5058')\n" +">>> c % a\n" +"Decimal('0.77')" + +#: ../../library/decimal.rst:243 +msgid "" +"Decimals can be formatted (with :func:`format` built-in or :ref:`f-strings`) " +"in fixed-point or scientific notation, using the same formatting syntax " +"(see :ref:`formatspec`) as builtin :class:`float` type:" +msgstr "" + +#: ../../library/decimal.rst:247 +msgid "" +">>> format(Decimal('2.675'), \"f\")\n" +"'2.675'\n" +">>> format(Decimal('2.675'), \".2f\")\n" +"'2.68'\n" +">>> f\"{Decimal('2.675'):.2f}\"\n" +"'2.68'\n" +">>> format(Decimal('2.675'), \".2e\")\n" +"'2.68e+0'\n" +">>> with localcontext() as ctx:\n" +"... ctx.rounding = ROUND_DOWN\n" +"... print(format(Decimal('2.675'), \".2f\"))\n" +"...\n" +"2.67" +msgstr "" + +#: ../../library/decimal.rst:263 +msgid "And some mathematical functions are also available to Decimal:" +msgstr "" + +#: ../../library/decimal.rst:275 +msgid "" +"The :meth:`~Decimal.quantize` method rounds a number to a fixed exponent. " +"This method is useful for monetary applications that often round results to " +"a fixed number of places:" +msgstr "" + +#: ../../library/decimal.rst:284 +msgid "" +"As shown above, the :func:`getcontext` function accesses the current context " +"and allows the settings to be changed. This approach meets the needs of " +"most applications." +msgstr "" + +#: ../../library/decimal.rst:288 +msgid "" +"For more advanced work, it may be useful to create alternate contexts using " +"the :meth:`Context` constructor. To make an alternate active, use the :func:" +"`setcontext` function." +msgstr "" + +#: ../../library/decimal.rst:292 +msgid "" +"In accordance with the standard, the :mod:`decimal` module provides two " +"ready to use standard contexts, :const:`BasicContext` and :const:" +"`ExtendedContext`. The former is especially useful for debugging because " +"many of the traps are enabled:" +msgstr "" + +#: ../../library/decimal.rst:297 +msgid "" +">>> myothercontext = Context(prec=60, rounding=ROUND_HALF_DOWN)\n" +">>> setcontext(myothercontext)\n" +">>> Decimal(1) / Decimal(7)\n" +"Decimal('0.142857142857142857142857142857142857142857142857142857142857')\n" +"\n" +">>> ExtendedContext\n" +"Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999, Emax=999999,\n" +" capitals=1, clamp=0, flags=[], traps=[])\n" +">>> setcontext(ExtendedContext)\n" +">>> Decimal(1) / Decimal(7)\n" +"Decimal('0.142857143')\n" +">>> Decimal(42) / Decimal(0)\n" +"Decimal('Infinity')\n" +"\n" +">>> setcontext(BasicContext)\n" +">>> Decimal(42) / Decimal(0)\n" +"Traceback (most recent call last):\n" +" File \"\", line 1, in -toplevel-\n" +" Decimal(42) / Decimal(0)\n" +"DivisionByZero: x / 0" +msgstr "" +">>> myothercontext = Context(prec=60, rounding=ROUND_HALF_DOWN)\n" +">>> setcontext(myothercontext)\n" +">>> Decimal(1) / Decimal(7)\n" +"Decimal('0.142857142857142857142857142857142857142857142857142857142857')\n" +"\n" +">>> ExtendedContext\n" +"Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999, Emax=999999,\n" +" capitals=1, clamp=0, flags=[], traps=[])\n" +">>> setcontext(ExtendedContext)\n" +">>> Decimal(1) / Decimal(7)\n" +"Decimal('0.142857143')\n" +">>> Decimal(42) / Decimal(0)\n" +"Decimal('Infinity')\n" +"\n" +">>> setcontext(BasicContext)\n" +">>> Decimal(42) / Decimal(0)\n" +"Traceback (most recent call last):\n" +" File \"\", line 1, in -toplevel-\n" +" Decimal(42) / Decimal(0)\n" +"DivisionByZero: x / 0" + +#: ../../library/decimal.rst:321 +msgid "" +"Contexts also have signal flags for monitoring exceptional conditions " +"encountered during computations. The flags remain set until explicitly " +"cleared, so it is best to clear the flags before each set of monitored " +"computations by using the :meth:`~Context.clear_flags` method. ::" +msgstr "" + +#: ../../library/decimal.rst:326 +msgid "" +">>> setcontext(ExtendedContext)\n" +">>> getcontext().clear_flags()\n" +">>> Decimal(355) / Decimal(113)\n" +"Decimal('3.14159292')\n" +">>> getcontext()\n" +"Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999, Emax=999999,\n" +" capitals=1, clamp=0, flags=[Inexact, Rounded], traps=[])" +msgstr "" +">>> setcontext(ExtendedContext)\n" +">>> getcontext().clear_flags()\n" +">>> Decimal(355) / Decimal(113)\n" +"Decimal('3.14159292')\n" +">>> getcontext()\n" +"Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999, Emax=999999,\n" +" capitals=1, clamp=0, flags=[Inexact, Rounded], traps=[])" + +#: ../../library/decimal.rst:334 +msgid "" +"The *flags* entry shows that the rational approximation to pi was rounded " +"(digits beyond the context precision were thrown away) and that the result " +"is inexact (some of the discarded digits were non-zero)." +msgstr "" + +#: ../../library/decimal.rst:338 +msgid "" +"Individual traps are set using the dictionary in the :attr:`~Context.traps` " +"attribute of a context:" +msgstr "" + +#: ../../library/decimal.rst:341 +msgid "" +">>> setcontext(ExtendedContext)\n" +">>> Decimal(1) / Decimal(0)\n" +"Decimal('Infinity')\n" +">>> getcontext().traps[DivisionByZero] = 1\n" +">>> Decimal(1) / Decimal(0)\n" +"Traceback (most recent call last):\n" +" File \"\", line 1, in -toplevel-\n" +" Decimal(1) / Decimal(0)\n" +"DivisionByZero: x / 0" +msgstr "" +">>> setcontext(ExtendedContext)\n" +">>> Decimal(1) / Decimal(0)\n" +"Decimal('Infinity')\n" +">>> getcontext().traps[DivisionByZero] = 1\n" +">>> Decimal(1) / Decimal(0)\n" +"Traceback (most recent call last):\n" +" File \"\", line 1, in -toplevel-\n" +" Decimal(1) / Decimal(0)\n" +"DivisionByZero: x / 0" + +#: ../../library/decimal.rst:353 +msgid "" +"Most programs adjust the current context only once, at the beginning of the " +"program. And, in many applications, data is converted to :class:`Decimal` " +"with a single cast inside a loop. With context set and decimals created, " +"the bulk of the program manipulates the data no differently than with other " +"Python numeric types." +msgstr "" + +#: ../../library/decimal.rst:365 +msgid "Decimal objects" +msgstr "" + +#: ../../library/decimal.rst:370 +msgid "Construct a new :class:`Decimal` object based from *value*." +msgstr "" + +#: ../../library/decimal.rst:372 +msgid "" +"*value* can be an integer, string, tuple, :class:`float`, or another :class:" +"`Decimal` object. If no *value* is given, returns ``Decimal('0')``. If " +"*value* is a string, it should conform to the decimal numeric string syntax " +"after leading and trailing whitespace characters, as well as underscores " +"throughout, are removed::" +msgstr "" + +#: ../../library/decimal.rst:377 +msgid "" +"sign ::= '+' | '-'\n" +"digit ::= '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | " +"'9'\n" +"indicator ::= 'e' | 'E'\n" +"digits ::= digit [digit]...\n" +"decimal-part ::= digits '.' [digits] | ['.'] digits\n" +"exponent-part ::= indicator [sign] digits\n" +"infinity ::= 'Infinity' | 'Inf'\n" +"nan ::= 'NaN' [digits] | 'sNaN' [digits]\n" +"numeric-value ::= decimal-part [exponent-part] | infinity\n" +"numeric-string ::= [sign] numeric-value | [sign] nan" +msgstr "" + +#: ../../library/decimal.rst:388 +msgid "" +"Other Unicode decimal digits are also permitted where ``digit`` appears " +"above. These include decimal digits from various other alphabets (for " +"example, Arabic-Indic and Devanāgarī digits) along with the fullwidth digits " +"``'\\uff10'`` through ``'\\uff19'``. Case is not significant, so, for " +"example, ``inf``, ``Inf``, ``INFINITY``, and ``iNfINity`` are all acceptable " +"spellings for positive infinity." +msgstr "" + +#: ../../library/decimal.rst:395 +msgid "" +"If *value* is a :class:`tuple`, it should have three components, a sign " +"(``0`` for positive or ``1`` for negative), a :class:`tuple` of digits, and " +"an integer exponent. For example, ``Decimal((0, (1, 4, 1, 4), -3))`` returns " +"``Decimal('1.414')``." +msgstr "" + +#: ../../library/decimal.rst:400 +msgid "" +"If *value* is a :class:`float`, the binary floating-point value is " +"losslessly converted to its exact decimal equivalent. This conversion can " +"often require 53 or more digits of precision. For example, " +"``Decimal(float('1.1'))`` converts to " +"``Decimal('1.100000000000000088817841970012523233890533447265625')``." +msgstr "" + +#: ../../library/decimal.rst:406 +msgid "" +"The *context* precision does not affect how many digits are stored. That is " +"determined exclusively by the number of digits in *value*. For example, " +"``Decimal('3.00000')`` records all five zeros even if the context precision " +"is only three." +msgstr "" + +#: ../../library/decimal.rst:411 +msgid "" +"The purpose of the *context* argument is determining what to do if *value* " +"is a malformed string. If the context traps :const:`InvalidOperation`, an " +"exception is raised; otherwise, the constructor returns a new Decimal with " +"the value of ``NaN``." +msgstr "" + +#: ../../library/decimal.rst:416 +msgid "Once constructed, :class:`Decimal` objects are immutable." +msgstr "" + +#: ../../library/decimal.rst:418 +msgid "" +"The argument to the constructor is now permitted to be a :class:`float` " +"instance." +msgstr "" + +#: ../../library/decimal.rst:422 +msgid "" +":class:`float` arguments raise an exception if the :exc:`FloatOperation` " +"trap is set. By default the trap is off." +msgstr "" + +#: ../../library/decimal.rst:426 +msgid "" +"Underscores are allowed for grouping, as with integral and floating-point " +"literals in code." +msgstr "" + +#: ../../library/decimal.rst:430 +msgid "" +"Decimal floating-point objects share many properties with the other built-in " +"numeric types such as :class:`float` and :class:`int`. All of the usual " +"math operations and special methods apply. Likewise, decimal objects can be " +"copied, pickled, printed, used as dictionary keys, used as set elements, " +"compared, sorted, and coerced to another type (such as :class:`float` or :" +"class:`int`)." +msgstr "" + +#: ../../library/decimal.rst:437 +msgid "" +"There are some small differences between arithmetic on Decimal objects and " +"arithmetic on integers and floats. When the remainder operator ``%`` is " +"applied to Decimal objects, the sign of the result is the sign of the " +"*dividend* rather than the sign of the divisor::" +msgstr "" + +#: ../../library/decimal.rst:442 +msgid "" +">>> (-7) % 4\n" +"1\n" +">>> Decimal(-7) % Decimal(4)\n" +"Decimal('-3')" +msgstr "" +">>> (-7) % 4\n" +"1\n" +">>> Decimal(-7) % Decimal(4)\n" +"Decimal('-3')" + +#: ../../library/decimal.rst:447 +msgid "" +"The integer division operator ``//`` behaves analogously, returning the " +"integer part of the true quotient (truncating towards zero) rather than its " +"floor, so as to preserve the usual identity ``x == (x // y) * y + x % y``::" +msgstr "" + +#: ../../library/decimal.rst:451 +msgid "" +">>> -7 // 4\n" +"-2\n" +">>> Decimal(-7) // Decimal(4)\n" +"Decimal('-1')" +msgstr "" +">>> -7 // 4\n" +"-2\n" +">>> Decimal(-7) // Decimal(4)\n" +"Decimal('-1')" + +#: ../../library/decimal.rst:456 +msgid "" +"The ``%`` and ``//`` operators implement the ``remainder`` and ``divide-" +"integer`` operations (respectively) as described in the specification." +msgstr "" + +#: ../../library/decimal.rst:460 +msgid "" +"Decimal objects cannot generally be combined with floats or instances of :" +"class:`fractions.Fraction` in arithmetic operations: an attempt to add a :" +"class:`Decimal` to a :class:`float`, for example, will raise a :exc:" +"`TypeError`. However, it is possible to use Python's comparison operators " +"to compare a :class:`Decimal` instance ``x`` with another number ``y``. " +"This avoids confusing results when doing equality comparisons between " +"numbers of different types." +msgstr "" + +#: ../../library/decimal.rst:468 +msgid "" +"Mixed-type comparisons between :class:`Decimal` instances and other numeric " +"types are now fully supported." +msgstr "" + +#: ../../library/decimal.rst:472 +msgid "" +"In addition to the standard numeric properties, decimal floating-point " +"objects also have a number of specialized methods:" +msgstr "" + +#: ../../library/decimal.rst:478 +msgid "" +"Return the adjusted exponent after shifting out the coefficient's rightmost " +"digits until only the lead digit remains: ``Decimal('321e+5').adjusted()`` " +"returns seven. Used for determining the position of the most significant " +"digit with respect to the decimal point." +msgstr "" + +#: ../../library/decimal.rst:485 +msgid "" +"Return a pair ``(n, d)`` of integers that represent the given :class:" +"`Decimal` instance as a fraction, in lowest terms and with a positive " +"denominator::" +msgstr "" + +#: ../../library/decimal.rst:489 +msgid "" +">>> Decimal('-3.14').as_integer_ratio()\n" +"(-157, 50)" +msgstr "" +">>> Decimal('-3.14').as_integer_ratio()\n" +"(-157, 50)" + +#: ../../library/decimal.rst:492 +msgid "" +"The conversion is exact. Raise OverflowError on infinities and ValueError " +"on NaNs." +msgstr "" + +#: ../../library/decimal.rst:499 +msgid "" +"Return a :term:`named tuple` representation of the number: " +"``DecimalTuple(sign, digits, exponent)``." +msgstr "" + +#: ../../library/decimal.rst:505 +msgid "" +"Return the canonical encoding of the argument. Currently, the encoding of " +"a :class:`Decimal` instance is always canonical, so this operation returns " +"its argument unchanged." +msgstr "" + +#: ../../library/decimal.rst:511 +msgid "" +"Compare the values of two Decimal instances. :meth:`compare` returns a " +"Decimal instance, and if either operand is a NaN then the result is a NaN::" +msgstr "" + +#: ../../library/decimal.rst:515 +msgid "" +"a or b is a NaN ==> Decimal('NaN')\n" +"a < b ==> Decimal('-1')\n" +"a == b ==> Decimal('0')\n" +"a > b ==> Decimal('1')" +msgstr "" +"a or b is a NaN ==> Decimal('NaN')\n" +"a < b ==> Decimal('-1')\n" +"a == b ==> Decimal('0')\n" +"a > b ==> Decimal('1')" + +#: ../../library/decimal.rst:522 +msgid "" +"This operation is identical to the :meth:`compare` method, except that all " +"NaNs signal. That is, if neither operand is a signaling NaN then any quiet " +"NaN operand is treated as though it were a signaling NaN." +msgstr "" + +#: ../../library/decimal.rst:528 +msgid "" +"Compare two operands using their abstract representation rather than their " +"numerical value. Similar to the :meth:`compare` method, but the result " +"gives a total ordering on :class:`Decimal` instances. Two :class:`Decimal` " +"instances with the same numeric value but different representations compare " +"unequal in this ordering:" +msgstr "" + +#: ../../library/decimal.rst:537 +msgid "" +"Quiet and signaling NaNs are also included in the total ordering. The " +"result of this function is ``Decimal('0')`` if both operands have the same " +"representation, ``Decimal('-1')`` if the first operand is lower in the total " +"order than the second, and ``Decimal('1')`` if the first operand is higher " +"in the total order than the second operand. See the specification for " +"details of the total order." +msgstr "" + +#: ../../library/decimal.rst:544 ../../library/decimal.rst:555 +#: ../../library/decimal.rst:583 ../../library/decimal.rst:887 +msgid "" +"This operation is unaffected by context and is quiet: no flags are changed " +"and no rounding is performed. As an exception, the C version may raise " +"InvalidOperation if the second operand cannot be converted exactly." +msgstr "" + +#: ../../library/decimal.rst:550 +msgid "" +"Compare two operands using their abstract representation rather than their " +"value as in :meth:`compare_total`, but ignoring the sign of each operand. " +"``x.compare_total_mag(y)`` is equivalent to ``x.copy_abs().compare_total(y." +"copy_abs())``." +msgstr "" + +#: ../../library/decimal.rst:561 +msgid "" +"Just returns self, this method is only to comply with the Decimal " +"Specification." +msgstr "" + +#: ../../library/decimal.rst:566 +msgid "" +"Return the absolute value of the argument. This operation is unaffected by " +"the context and is quiet: no flags are changed and no rounding is performed." +msgstr "" + +#: ../../library/decimal.rst:572 +msgid "" +"Return the negation of the argument. This operation is unaffected by the " +"context and is quiet: no flags are changed and no rounding is performed." +msgstr "" + +#: ../../library/decimal.rst:577 +msgid "" +"Return a copy of the first operand with the sign set to be the same as the " +"sign of the second operand. For example:" +msgstr "" + +#: ../../library/decimal.rst:589 +msgid "" +"Return the value of the (natural) exponential function ``e**x`` at the given " +"number. The result is correctly rounded using the :const:`ROUND_HALF_EVEN` " +"rounding mode." +msgstr "" + +#: ../../library/decimal.rst:600 +msgid "" +"Alternative constructor that only accepts instances of :class:`float` or :" +"class:`int`." +msgstr "" + +#: ../../library/decimal.rst:603 +msgid "" +"Note ``Decimal.from_float(0.1)`` is not the same as ``Decimal('0.1')``. " +"Since 0.1 is not exactly representable in binary floating point, the value " +"is stored as the nearest representable value which is " +"``0x1.999999999999ap-4``. That equivalent value in decimal is " +"``0.1000000000000000055511151231257827021181583404541015625``." +msgstr "" + +#: ../../library/decimal.rst:609 +msgid "" +"From Python 3.2 onwards, a :class:`Decimal` instance can also be constructed " +"directly from a :class:`float`." +msgstr "" + +#: ../../library/decimal.rst:612 +msgid "" +">>> Decimal.from_float(0.1)\n" +"Decimal('0.1000000000000000055511151231257827021181583404541015625')\n" +">>> Decimal.from_float(float('nan'))\n" +"Decimal('NaN')\n" +">>> Decimal.from_float(float('inf'))\n" +"Decimal('Infinity')\n" +">>> Decimal.from_float(float('-inf'))\n" +"Decimal('-Infinity')" +msgstr "" +">>> Decimal.from_float(0.1)\n" +"Decimal('0.1000000000000000055511151231257827021181583404541015625')\n" +">>> Decimal.from_float(float('nan'))\n" +"Decimal('NaN')\n" +">>> Decimal.from_float(float('inf'))\n" +"Decimal('Infinity')\n" +">>> Decimal.from_float(float('-inf'))\n" +"Decimal('-Infinity')" + +#: ../../library/decimal.rst:627 +msgid "" +"Alternative constructor that only accepts instances of :class:`float`, :" +"class:`int` or :class:`Decimal`, but not strings or tuples." +msgstr "" + +#: ../../library/decimal.rst:631 +msgid "" +">>> Decimal.from_number(314)\n" +"Decimal('314')\n" +">>> Decimal.from_number(0.1)\n" +"Decimal('0.1000000000000000055511151231257827021181583404541015625')\n" +">>> Decimal.from_number(Decimal('3.14'))\n" +"Decimal('3.14')" +msgstr "" +">>> Decimal.from_number(314)\n" +"Decimal('314')\n" +">>> Decimal.from_number(0.1)\n" +"Decimal('0.1000000000000000055511151231257827021181583404541015625')\n" +">>> Decimal.from_number(Decimal('3.14'))\n" +"Decimal('3.14')" + +#: ../../library/decimal.rst:644 +msgid "" +"Fused multiply-add. Return self*other+third with no rounding of the " +"intermediate product self*other." +msgstr "" + +#: ../../library/decimal.rst:652 +msgid "" +"Return :const:`True` if the argument is canonical and :const:`False` " +"otherwise. Currently, a :class:`Decimal` instance is always canonical, so " +"this operation always returns :const:`True`." +msgstr "" + +#: ../../library/decimal.rst:658 +msgid "" +"Return :const:`True` if the argument is a finite number, and :const:`False` " +"if the argument is an infinity or a NaN." +msgstr "" + +#: ../../library/decimal.rst:663 +msgid "" +"Return :const:`True` if the argument is either positive or negative infinity " +"and :const:`False` otherwise." +msgstr "" + +#: ../../library/decimal.rst:668 +msgid "" +"Return :const:`True` if the argument is a (quiet or signaling) NaN and :" +"const:`False` otherwise." +msgstr "" + +#: ../../library/decimal.rst:673 +msgid "" +"Return :const:`True` if the argument is a *normal* finite number. Return :" +"const:`False` if the argument is zero, subnormal, infinite or a NaN." +msgstr "" + +#: ../../library/decimal.rst:678 +msgid "" +"Return :const:`True` if the argument is a quiet NaN, and :const:`False` " +"otherwise." +msgstr "" + +#: ../../library/decimal.rst:683 +msgid "" +"Return :const:`True` if the argument has a negative sign and :const:`False` " +"otherwise. Note that zeros and NaNs can both carry signs." +msgstr "" + +#: ../../library/decimal.rst:688 +msgid "" +"Return :const:`True` if the argument is a signaling NaN and :const:`False` " +"otherwise." +msgstr "" + +#: ../../library/decimal.rst:693 +msgid "" +"Return :const:`True` if the argument is subnormal, and :const:`False` " +"otherwise." +msgstr "" + +#: ../../library/decimal.rst:698 +msgid "" +"Return :const:`True` if the argument is a (positive or negative) zero and :" +"const:`False` otherwise." +msgstr "" + +#: ../../library/decimal.rst:703 +msgid "" +"Return the natural (base e) logarithm of the operand. The result is " +"correctly rounded using the :const:`ROUND_HALF_EVEN` rounding mode." +msgstr "" + +#: ../../library/decimal.rst:708 +msgid "" +"Return the base ten logarithm of the operand. The result is correctly " +"rounded using the :const:`ROUND_HALF_EVEN` rounding mode." +msgstr "" + +#: ../../library/decimal.rst:713 +msgid "" +"For a nonzero number, return the adjusted exponent of its operand as a :" +"class:`Decimal` instance. If the operand is a zero then ``Decimal('-" +"Infinity')`` is returned and the :const:`DivisionByZero` flag is raised. If " +"the operand is an infinity then ``Decimal('Infinity')`` is returned." +msgstr "" + +#: ../../library/decimal.rst:721 +msgid "" +":meth:`logical_and` is a logical operation which takes two *logical " +"operands* (see :ref:`logical_operands_label`). The result is the digit-wise " +"``and`` of the two operands." +msgstr "" + +#: ../../library/decimal.rst:727 +msgid "" +":meth:`logical_invert` is a logical operation. The result is the digit-wise " +"inversion of the operand." +msgstr "" + +#: ../../library/decimal.rst:732 +msgid "" +":meth:`logical_or` is a logical operation which takes two *logical operands* " +"(see :ref:`logical_operands_label`). The result is the digit-wise ``or`` of " +"the two operands." +msgstr "" + +#: ../../library/decimal.rst:738 +msgid "" +":meth:`logical_xor` is a logical operation which takes two *logical " +"operands* (see :ref:`logical_operands_label`). The result is the digit-wise " +"exclusive or of the two operands." +msgstr "" + +#: ../../library/decimal.rst:744 +msgid "" +"Like ``max(self, other)`` except that the context rounding rule is applied " +"before returning and that ``NaN`` values are either signaled or ignored " +"(depending on the context and whether they are signaling or quiet)." +msgstr "" + +#: ../../library/decimal.rst:751 +msgid "" +"Similar to the :meth:`.max` method, but the comparison is done using the " +"absolute values of the operands." +msgstr "" + +#: ../../library/decimal.rst:756 +msgid "" +"Like ``min(self, other)`` except that the context rounding rule is applied " +"before returning and that ``NaN`` values are either signaled or ignored " +"(depending on the context and whether they are signaling or quiet)." +msgstr "" + +#: ../../library/decimal.rst:763 +msgid "" +"Similar to the :meth:`.min` method, but the comparison is done using the " +"absolute values of the operands." +msgstr "" + +#: ../../library/decimal.rst:768 +msgid "" +"Return the largest number representable in the given context (or in the " +"current thread's context if no context is given) that is smaller than the " +"given operand." +msgstr "" + +#: ../../library/decimal.rst:774 +msgid "" +"Return the smallest number representable in the given context (or in the " +"current thread's context if no context is given) that is larger than the " +"given operand." +msgstr "" + +#: ../../library/decimal.rst:780 +msgid "" +"If the two operands are unequal, return the number closest to the first " +"operand in the direction of the second operand. If both operands are " +"numerically equal, return a copy of the first operand with the sign set to " +"be the same as the sign of the second operand." +msgstr "" + +#: ../../library/decimal.rst:787 +msgid "" +"Used for producing canonical values of an equivalence class within either " +"the current context or the specified context." +msgstr "" + +#: ../../library/decimal.rst:790 +msgid "" +"This has the same semantics as the unary plus operation, except that if the " +"final result is finite it is reduced to its simplest form, with all trailing " +"zeros removed and its sign preserved. That is, while the coefficient is non-" +"zero and a multiple of ten the coefficient is divided by ten and the " +"exponent is incremented by 1. Otherwise (the coefficient is zero) the " +"exponent is set to 0. In all cases the sign is unchanged." +msgstr "" + +#: ../../library/decimal.rst:797 +msgid "" +"For example, ``Decimal('32.100')`` and ``Decimal('0.321000e+2')`` both " +"normalize to the equivalent value ``Decimal('32.1')``." +msgstr "" + +#: ../../library/decimal.rst:800 +msgid "Note that rounding is applied *before* reducing to simplest form." +msgstr "" + +#: ../../library/decimal.rst:802 +msgid "" +"In the latest versions of the specification, this operation is also known as " +"``reduce``." +msgstr "" + +#: ../../library/decimal.rst:807 +msgid "" +"Return a string describing the *class* of the operand. The returned value " +"is one of the following ten strings." +msgstr "" + +#: ../../library/decimal.rst:810 +msgid "``\"-Infinity\"``, indicating that the operand is negative infinity." +msgstr "" + +#: ../../library/decimal.rst:811 +msgid "" +"``\"-Normal\"``, indicating that the operand is a negative normal number." +msgstr "" + +#: ../../library/decimal.rst:812 +msgid "" +"``\"-Subnormal\"``, indicating that the operand is negative and subnormal." +msgstr "" + +#: ../../library/decimal.rst:813 +msgid "``\"-Zero\"``, indicating that the operand is a negative zero." +msgstr "" + +#: ../../library/decimal.rst:814 +msgid "``\"+Zero\"``, indicating that the operand is a positive zero." +msgstr "" + +#: ../../library/decimal.rst:815 +msgid "" +"``\"+Subnormal\"``, indicating that the operand is positive and subnormal." +msgstr "" + +#: ../../library/decimal.rst:816 +msgid "" +"``\"+Normal\"``, indicating that the operand is a positive normal number." +msgstr "" + +#: ../../library/decimal.rst:817 +msgid "``\"+Infinity\"``, indicating that the operand is positive infinity." +msgstr "" + +#: ../../library/decimal.rst:818 +msgid "``\"NaN\"``, indicating that the operand is a quiet NaN (Not a Number)." +msgstr "" + +#: ../../library/decimal.rst:819 +msgid "``\"sNaN\"``, indicating that the operand is a signaling NaN." +msgstr "" + +#: ../../library/decimal.rst:823 +msgid "" +"Return a value equal to the first operand after rounding and having the " +"exponent of the second operand." +msgstr "" + +#: ../../library/decimal.rst:829 +msgid "" +"Unlike other operations, if the length of the coefficient after the quantize " +"operation would be greater than precision, then an :const:`InvalidOperation` " +"is signaled. This guarantees that, unless there is an error condition, the " +"quantized exponent is always equal to that of the right-hand operand." +msgstr "" + +#: ../../library/decimal.rst:835 +msgid "" +"Also unlike other operations, quantize never signals Underflow, even if the " +"result is subnormal and inexact." +msgstr "" + +#: ../../library/decimal.rst:838 +msgid "" +"If the exponent of the second operand is larger than that of the first then " +"rounding may be necessary. In this case, the rounding mode is determined by " +"the ``rounding`` argument if given, else by the given ``context`` argument; " +"if neither argument is given the rounding mode of the current thread's " +"context is used." +msgstr "" + +#: ../../library/decimal.rst:844 +msgid "" +"An error is returned whenever the resulting exponent is greater than :attr:" +"`~Context.Emax` or less than :meth:`~Context.Etiny`." +msgstr "" + +#: ../../library/decimal.rst:849 +msgid "" +"Return ``Decimal(10)``, the radix (base) in which the :class:`Decimal` class " +"does all its arithmetic. Included for compatibility with the specification." +msgstr "" + +#: ../../library/decimal.rst:855 +msgid "" +"Return the remainder from dividing *self* by *other*. This differs from " +"``self % other`` in that the sign of the remainder is chosen so as to " +"minimize its absolute value. More precisely, the return value is ``self - n " +"* other`` where ``n`` is the integer nearest to the exact value of ``self / " +"other``, and if two integers are equally near then the even one is chosen." +msgstr "" + +#: ../../library/decimal.rst:862 +msgid "If the result is zero then its sign will be the sign of *self*." +msgstr "" + +#: ../../library/decimal.rst:873 +msgid "" +"Return the result of rotating the digits of the first operand by an amount " +"specified by the second operand. The second operand must be an integer in " +"the range -precision through precision. The absolute value of the second " +"operand gives the number of places to rotate. If the second operand is " +"positive then rotation is to the left; otherwise rotation is to the right. " +"The coefficient of the first operand is padded on the left with zeros to " +"length precision if necessary. The sign and exponent of the first operand " +"are unchanged." +msgstr "" + +#: ../../library/decimal.rst:884 +msgid "" +"Test whether self and other have the same exponent or whether both are " +"``NaN``." +msgstr "" + +#: ../../library/decimal.rst:893 +msgid "" +"Return the first operand with exponent adjusted by the second. Equivalently, " +"return the first operand multiplied by ``10**other``. The second operand " +"must be an integer." +msgstr "" + +#: ../../library/decimal.rst:899 +msgid "" +"Return the result of shifting the digits of the first operand by an amount " +"specified by the second operand. The second operand must be an integer in " +"the range -precision through precision. The absolute value of the second " +"operand gives the number of places to shift. If the second operand is " +"positive then the shift is to the left; otherwise the shift is to the " +"right. Digits shifted into the coefficient are zeros. The sign and " +"exponent of the first operand are unchanged." +msgstr "" + +#: ../../library/decimal.rst:909 +msgid "Return the square root of the argument to full precision." +msgstr "" + +#: ../../library/decimal.rst:914 ../../library/decimal.rst:1571 +msgid "" +"Convert to a string, using engineering notation if an exponent is needed." +msgstr "" + +#: ../../library/decimal.rst:916 ../../library/decimal.rst:1573 +msgid "" +"Engineering notation has an exponent which is a multiple of 3. This can " +"leave up to 3 digits to the left of the decimal place and may require the " +"addition of either one or two trailing zeros." +msgstr "" + +#: ../../library/decimal.rst:920 +msgid "" +"For example, this converts ``Decimal('123E+1')`` to ``Decimal('1.23E+3')``." +msgstr "" + +#: ../../library/decimal.rst:924 +msgid "" +"Identical to the :meth:`to_integral_value` method. The ``to_integral`` name " +"has been kept for compatibility with older versions." +msgstr "" + +#: ../../library/decimal.rst:929 +msgid "" +"Round to the nearest integer, signaling :const:`Inexact` or :const:`Rounded` " +"as appropriate if rounding occurs. The rounding mode is determined by the " +"``rounding`` parameter if given, else by the given ``context``. If neither " +"parameter is given then the rounding mode of the current context is used." +msgstr "" + +#: ../../library/decimal.rst:937 +msgid "" +"Round to the nearest integer without signaling :const:`Inexact` or :const:" +"`Rounded`. If given, applies *rounding*; otherwise, uses the rounding " +"method in either the supplied *context* or the current context." +msgstr "" + +#: ../../library/decimal.rst:941 +msgid "Decimal numbers can be rounded using the :func:`.round` function:" +msgstr "" + +#: ../../library/decimal.rst:946 +msgid "" +"If *ndigits* is not given or ``None``, returns the nearest :class:`int` to " +"*number*, rounding ties to even, and ignoring the rounding mode of the :" +"class:`Decimal` context. Raises :exc:`OverflowError` if *number* is an " +"infinity or :exc:`ValueError` if it is a (quiet or signaling) NaN." +msgstr "" + +#: ../../library/decimal.rst:952 +msgid "" +"If *ndigits* is an :class:`int`, the context's rounding mode is respected " +"and a :class:`Decimal` representing *number* rounded to the nearest multiple " +"of ``Decimal('1E-ndigits')`` is returned; in this case, ``round(number, " +"ndigits)`` is equivalent to ``self.quantize(Decimal('1E-ndigits'))``. " +"Returns ``Decimal('NaN')`` if *number* is a quiet NaN. Raises :class:" +"`InvalidOperation` if *number* is an infinity, a signaling NaN, or if the " +"length of the coefficient after the quantize operation would be greater than " +"the current context's precision. In other words, for the non-corner cases:" +msgstr "" + +#: ../../library/decimal.rst:962 +msgid "" +"if *ndigits* is positive, return *number* rounded to *ndigits* decimal " +"places;" +msgstr "" + +#: ../../library/decimal.rst:964 +msgid "if *ndigits* is zero, return *number* rounded to the nearest integer;" +msgstr "" + +#: ../../library/decimal.rst:965 +msgid "" +"if *ndigits* is negative, return *number* rounded to the nearest multiple of " +"``10**abs(ndigits)``." +msgstr "" + +#: ../../library/decimal.rst:968 +msgid "For example::" +msgstr "舉例來說： ::" + +#: ../../library/decimal.rst:970 +msgid "" +">>> from decimal import Decimal, getcontext, ROUND_DOWN\n" +">>> getcontext().rounding = ROUND_DOWN\n" +">>> round(Decimal('3.75')) # context rounding ignored\n" +"4\n" +">>> round(Decimal('3.5')) # round-ties-to-even\n" +"4\n" +">>> round(Decimal('3.75'), 0) # uses the context rounding\n" +"Decimal('3')\n" +">>> round(Decimal('3.75'), 1)\n" +"Decimal('3.7')\n" +">>> round(Decimal('3.75'), -1)\n" +"Decimal('0E+1')" +msgstr "" + +#: ../../library/decimal.rst:987 +msgid "Logical operands" +msgstr "" + +#: ../../library/decimal.rst:989 +msgid "" +"The :meth:`~Decimal.logical_and`, :meth:`~Decimal.logical_invert`, :meth:" +"`~Decimal.logical_or`, and :meth:`~Decimal.logical_xor` methods expect their " +"arguments to be *logical operands*. A *logical operand* is a :class:" +"`Decimal` instance whose exponent and sign are both zero, and whose digits " +"are all either ``0`` or ``1``." +msgstr "" + +#: ../../library/decimal.rst:1001 +msgid "Context objects" +msgstr "" + +#: ../../library/decimal.rst:1003 +msgid "" +"Contexts are environments for arithmetic operations. They govern precision, " +"set rules for rounding, determine which signals are treated as exceptions, " +"and limit the range for exponents." +msgstr "" + +#: ../../library/decimal.rst:1007 +msgid "" +"Each thread has its own current context which is accessed or changed using " +"the :func:`getcontext` and :func:`setcontext` functions:" +msgstr "" + +#: ../../library/decimal.rst:1013 +msgid "Return the current context for the active thread." +msgstr "" + +#: ../../library/decimal.rst:1018 +msgid "Set the current context for the active thread to *c*." +msgstr "" + +#: ../../library/decimal.rst:1020 +msgid "" +"You can also use the :keyword:`with` statement and the :func:`localcontext` " +"function to temporarily change the active context." +msgstr "" + +#: ../../library/decimal.rst:1025 +msgid "" +"Return a context manager that will set the current context for the active " +"thread to a copy of *ctx* on entry to the with-statement and restore the " +"previous context when exiting the with-statement. If no context is " +"specified, a copy of the current context is used. The *kwargs* argument is " +"used to set the attributes of the new context." +msgstr "" + +#: ../../library/decimal.rst:1031 +msgid "" +"For example, the following code sets the current decimal precision to 42 " +"places, performs a calculation, and then automatically restores the previous " +"context::" +msgstr "" + +#: ../../library/decimal.rst:1034 +msgid "" +"from decimal import localcontext\n" +"\n" +"with localcontext() as ctx:\n" +" ctx.prec = 42 # Perform a high precision calculation\n" +" s = calculate_something()\n" +"s = +s # Round the final result back to the default precision" +msgstr "" + +#: ../../library/decimal.rst:1041 +msgid "Using keyword arguments, the code would be the following::" +msgstr "" + +#: ../../library/decimal.rst:1043 +msgid "" +"from decimal import localcontext\n" +"\n" +"with localcontext(prec=42) as ctx:\n" +" s = calculate_something()\n" +"s = +s" +msgstr "" +"from decimal import localcontext\n" +"\n" +"with localcontext(prec=42) as ctx:\n" +" s = calculate_something()\n" +"s = +s" + +#: ../../library/decimal.rst:1049 +msgid "" +"Raises :exc:`TypeError` if *kwargs* supplies an attribute that :class:" +"`Context` doesn't support. Raises either :exc:`TypeError` or :exc:" +"`ValueError` if *kwargs* supplies an invalid value for an attribute." +msgstr "" + +#: ../../library/decimal.rst:1053 +msgid "" +":meth:`localcontext` now supports setting context attributes through the use " +"of keyword arguments." +msgstr "" + +#: ../../library/decimal.rst:1058 +msgid "" +"Return a context object initialized to the proper values for one of the IEEE " +"interchange formats. The argument must be a multiple of 32 and less than :" +"const:`IEEE_CONTEXT_MAX_BITS`." +msgstr "" + +#: ../../library/decimal.rst:1064 +msgid "" +"New contexts can also be created using the :class:`Context` constructor " +"described below. In addition, the module provides three pre-made contexts:" +msgstr "" + +#: ../../library/decimal.rst:1070 +msgid "" +"This is a standard context defined by the General Decimal Arithmetic " +"Specification. Precision is set to nine. Rounding is set to :const:" +"`ROUND_HALF_UP`. All flags are cleared. All traps are enabled (treated as " +"exceptions) except :const:`Inexact`, :const:`Rounded`, and :const:" +"`Subnormal`." +msgstr "" + +#: ../../library/decimal.rst:1076 +msgid "" +"Because many of the traps are enabled, this context is useful for debugging." +msgstr "" + +#: ../../library/decimal.rst:1081 +msgid "" +"This is a standard context defined by the General Decimal Arithmetic " +"Specification. Precision is set to nine. Rounding is set to :const:" +"`ROUND_HALF_EVEN`. All flags are cleared. No traps are enabled (so that " +"exceptions are not raised during computations)." +msgstr "" + +#: ../../library/decimal.rst:1086 +msgid "" +"Because the traps are disabled, this context is useful for applications that " +"prefer to have result value of ``NaN`` or ``Infinity`` instead of raising " +"exceptions. This allows an application to complete a run in the presence of " +"conditions that would otherwise halt the program." +msgstr "" + +#: ../../library/decimal.rst:1094 +msgid "" +"This context is used by the :class:`Context` constructor as a prototype for " +"new contexts. Changing a field (such a precision) has the effect of " +"changing the default for new contexts created by the :class:`Context` " +"constructor." +msgstr "" + +#: ../../library/decimal.rst:1098 +msgid "" +"This context is most useful in multi-threaded environments. Changing one of " +"the fields before threads are started has the effect of setting system-wide " +"defaults. Changing the fields after threads have started is not recommended " +"as it would require thread synchronization to prevent race conditions." +msgstr "" + +#: ../../library/decimal.rst:1103 +msgid "" +"In single threaded environments, it is preferable to not use this context at " +"all. Instead, simply create contexts explicitly as described below." +msgstr "" + +#: ../../library/decimal.rst:1106 +msgid "" +"The default values are :attr:`Context.prec`\\ =\\ ``28``, :attr:`Context." +"rounding`\\ =\\ :const:`ROUND_HALF_EVEN`, and enabled traps for :class:" +"`Overflow`, :class:`InvalidOperation`, and :class:`DivisionByZero`." +msgstr "" + +#: ../../library/decimal.rst:1111 +msgid "" +"In addition to the three supplied contexts, new contexts can be created with " +"the :class:`Context` constructor." +msgstr "" + +#: ../../library/decimal.rst:1117 +msgid "" +"Creates a new context. If a field is not specified or is :const:`None`, the " +"default values are copied from the :const:`DefaultContext`. If the *flags* " +"field is not specified or is :const:`None`, all flags are cleared." +msgstr "" + +#: ../../library/decimal.rst:1123 +msgid "" +"An integer in the range [``1``, :const:`MAX_PREC`] that sets the precision " +"for arithmetic operations in the context." +msgstr "" + +#: ../../library/decimal.rst:1128 +msgid "One of the constants listed in the section `Rounding Modes`_." +msgstr "" + +#: ../../library/decimal.rst:1133 +msgid "" +"Lists of any signals to be set. Generally, new contexts should only set " +"traps and leave the flags clear." +msgstr "" + +#: ../../library/decimal.rst:1139 +msgid "" +"Integers specifying the outer limits allowable for exponents. *Emin* must be " +"in the range [:const:`MIN_EMIN`, ``0``], *Emax* in the range [``0``, :const:" +"`MAX_EMAX`]." +msgstr "" + +#: ../../library/decimal.rst:1145 +msgid "" +"Either ``0`` or ``1`` (the default). If set to ``1``, exponents are printed " +"with a capital ``E``; otherwise, a lowercase ``e`` is used: " +"``Decimal('6.02e+23')``." +msgstr "" + +#: ../../library/decimal.rst:1151 +msgid "" +"Either ``0`` (the default) or ``1``. If set to ``1``, the exponent ``e`` of " +"a :class:`Decimal` instance representable in this context is strictly " +"limited to the range ``Emin - prec + 1 <= e <= Emax - prec + 1``. If *clamp* " +"is ``0`` then a weaker condition holds: the adjusted exponent of the :class:" +"`Decimal` instance is at most :attr:`~Context.Emax`. When *clamp* is ``1``, " +"a large normal number will, where possible, have its exponent reduced and a " +"corresponding number of zeros added to its coefficient, in order to fit the " +"exponent constraints; this preserves the value of the number but loses " +"information about significant trailing zeros. For example::" +msgstr "" + +#: ../../library/decimal.rst:1162 +msgid "" +">>> Context(prec=6, Emax=999, clamp=1).create_decimal('1.23e999')\n" +"Decimal('1.23000E+999')" +msgstr "" +">>> Context(prec=6, Emax=999, clamp=1).create_decimal('1.23e999')\n" +"Decimal('1.23000E+999')" + +#: ../../library/decimal.rst:1165 +msgid "" +"A *clamp* value of ``1`` allows compatibility with the fixed-width decimal " +"interchange formats specified in IEEE 754." +msgstr "" + +#: ../../library/decimal.rst:1168 +msgid "" +"The :class:`Context` class defines several general purpose methods as well " +"as a large number of methods for doing arithmetic directly in a given " +"context. In addition, for each of the :class:`Decimal` methods described " +"above (with the exception of the :meth:`~Decimal.adjusted` and :meth:" +"`~Decimal.as_tuple` methods) there is a corresponding :class:`Context` " +"method. For example, for a :class:`Context` instance ``C`` and :class:" +"`Decimal` instance ``x``, ``C.exp(x)`` is equivalent to ``x." +"exp(context=C)``. Each :class:`Context` method accepts a Python integer (an " +"instance of :class:`int`) anywhere that a Decimal instance is accepted." +msgstr "" + +#: ../../library/decimal.rst:1181 +msgid "Resets all of the flags to ``0``." +msgstr "" + +#: ../../library/decimal.rst:1185 +msgid "Resets all of the traps to ``0``." +msgstr "" + +#: ../../library/decimal.rst:1191 +msgid "Return a duplicate of the context." +msgstr "" + +#: ../../library/decimal.rst:1195 +msgid "Return a copy of the Decimal instance num." +msgstr "" + +#: ../../library/decimal.rst:1199 +msgid "" +"Creates a new Decimal instance from *num* but using *self* as context. " +"Unlike the :class:`Decimal` constructor, the context precision, rounding " +"method, flags, and traps are applied to the conversion." +msgstr "" + +#: ../../library/decimal.rst:1203 +msgid "" +"This is useful because constants are often given to a greater precision than " +"is needed by the application. Another benefit is that rounding immediately " +"eliminates unintended effects from digits beyond the current precision. In " +"the following example, using unrounded inputs means that adding zero to a " +"sum can change the result:" +msgstr "" + +#: ../../library/decimal.rst:1209 +msgid "" +">>> getcontext().prec = 3\n" +">>> Decimal('3.4445') + Decimal('1.0023')\n" +"Decimal('4.45')\n" +">>> Decimal('3.4445') + Decimal(0) + Decimal('1.0023')\n" +"Decimal('4.44')" +msgstr "" +">>> getcontext().prec = 3\n" +">>> Decimal('3.4445') + Decimal('1.0023')\n" +"Decimal('4.45')\n" +">>> Decimal('3.4445') + Decimal(0) + Decimal('1.0023')\n" +"Decimal('4.44')" + +#: ../../library/decimal.rst:1217 +msgid "" +"This method implements the to-number operation of the IBM specification. If " +"the argument is a string, no leading or trailing whitespace or underscores " +"are permitted." +msgstr "" + +#: ../../library/decimal.rst:1223 +msgid "" +"Creates a new Decimal instance from a float *f* but rounding using *self* as " +"the context. Unlike the :meth:`Decimal.from_float` class method, the " +"context precision, rounding method, flags, and traps are applied to the " +"conversion." +msgstr "" + +#: ../../library/decimal.rst:1228 +msgid "" +">>> context = Context(prec=5, rounding=ROUND_DOWN)\n" +">>> context.create_decimal_from_float(math.pi)\n" +"Decimal('3.1415')\n" +">>> context = Context(prec=5, traps=[Inexact])\n" +">>> context.create_decimal_from_float(math.pi)\n" +"Traceback (most recent call last):\n" +" ...\n" +"decimal.Inexact: None" +msgstr "" +">>> context = Context(prec=5, rounding=ROUND_DOWN)\n" +">>> context.create_decimal_from_float(math.pi)\n" +"Decimal('3.1415')\n" +">>> context = Context(prec=5, traps=[Inexact])\n" +">>> context.create_decimal_from_float(math.pi)\n" +"Traceback (most recent call last):\n" +" ...\n" +"decimal.Inexact: None" + +#: ../../library/decimal.rst:1243 +msgid "" +"Returns a value equal to ``Emin - prec + 1`` which is the minimum exponent " +"value for subnormal results. When underflow occurs, the exponent is set to :" +"const:`Etiny`." +msgstr "" + +#: ../../library/decimal.rst:1249 +msgid "Returns a value equal to ``Emax - prec + 1``." +msgstr "回傳一個等於 ``Emax - prec + 1`` 的值。" + +#: ../../library/decimal.rst:1251 +msgid "" +"The usual approach to working with decimals is to create :class:`Decimal` " +"instances and then apply arithmetic operations which take place within the " +"current context for the active thread. An alternative approach is to use " +"context methods for calculating within a specific context. The methods are " +"similar to those for the :class:`Decimal` class and are only briefly " +"recounted here." +msgstr "" + +#: ../../library/decimal.rst:1261 +msgid "Returns the absolute value of *x*." +msgstr "回傳 *x* 的絕對值。" + +#: ../../library/decimal.rst:1266 +msgid "Return the sum of *x* and *y*." +msgstr "回傳 *x* 與 *y* 的和。" + +#: ../../library/decimal.rst:1271 +msgid "Returns the same Decimal object *x*." +msgstr "回傳相同的 Decimal 物件 *x*。" + +#: ../../library/decimal.rst:1276 +msgid "Compares *x* and *y* numerically." +msgstr "" + +#: ../../library/decimal.rst:1281 +msgid "Compares the values of the two operands numerically." +msgstr "" + +#: ../../library/decimal.rst:1286 +msgid "Compares two operands using their abstract representation." +msgstr "" + +#: ../../library/decimal.rst:1291 +msgid "" +"Compares two operands using their abstract representation, ignoring sign." +msgstr "" + +#: ../../library/decimal.rst:1296 +msgid "Returns a copy of *x* with the sign set to 0." +msgstr "" + +#: ../../library/decimal.rst:1301 +msgid "Returns a copy of *x* with the sign inverted." +msgstr "" + +#: ../../library/decimal.rst:1306 +msgid "Copies the sign from *y* to *x*." +msgstr "將 *y* 的正負號複製到 *x*。" + +#: ../../library/decimal.rst:1311 +msgid "Return *x* divided by *y*." +msgstr "回傳 *x* 除以 *y*。" + +#: ../../library/decimal.rst:1316 +msgid "Return *x* divided by *y*, truncated to an integer." +msgstr "" + +#: ../../library/decimal.rst:1321 +msgid "Divides two numbers and returns the integer part of the result." +msgstr "" + +#: ../../library/decimal.rst:1326 +msgid "Returns ``e ** x``." +msgstr "回傳 ``e ** x``。" + +#: ../../library/decimal.rst:1331 +msgid "Returns *x* multiplied by *y*, plus *z*." +msgstr "回傳 *x* 乘以 *y*，再加上 *z*。" + +#: ../../library/decimal.rst:1336 +msgid "Returns ``True`` if *x* is canonical; otherwise returns ``False``." +msgstr "" + +#: ../../library/decimal.rst:1341 +msgid "Returns ``True`` if *x* is finite; otherwise returns ``False``." +msgstr "如果 *x* 是有限的則回傳 ``True``；否則回傳 ``False``。" + +#: ../../library/decimal.rst:1346 +msgid "Returns ``True`` if *x* is infinite; otherwise returns ``False``." +msgstr "如果 *x* 是無限大則回傳 ``True``；否則回傳 ``False``。" + +#: ../../library/decimal.rst:1351 +msgid "Returns ``True`` if *x* is a qNaN or sNaN; otherwise returns ``False``." +msgstr "如果 *x* 是 qNaN 或 sNaN 則回傳 ``True``；否則回傳 ``False``。" + +#: ../../library/decimal.rst:1356 +msgid "" +"Returns ``True`` if *x* is a normal number; otherwise returns ``False``." +msgstr "" +"如果 *x* 是正規數 (normal number) 則回傳 ``True``；否則回傳 ``False``。" + +#: ../../library/decimal.rst:1361 +msgid "Returns ``True`` if *x* is a quiet NaN; otherwise returns ``False``." +msgstr "" +"如果 *x* 是安靜型 NaN (quiet NaN) 則回傳 ``True``；否則回傳 ``False``。" + +#: ../../library/decimal.rst:1366 +msgid "Returns ``True`` if *x* is negative; otherwise returns ``False``." +msgstr "如果 *x* 是負數則回傳 ``True``；否則回傳 ``False``。" + +#: ../../library/decimal.rst:1371 +msgid "" +"Returns ``True`` if *x* is a signaling NaN; otherwise returns ``False``." +msgstr "" +"如果 *x* 是訊號型 NaN (signaling NaN) 則回傳 ``True``；否則回傳 ``False``。" + +#: ../../library/decimal.rst:1376 +msgid "Returns ``True`` if *x* is subnormal; otherwise returns ``False``." +msgstr "如果 *x* 是次正規數 (subnormal) 則回傳 ``True``；否則回傳 ``False``。" + +#: ../../library/decimal.rst:1381 +msgid "Returns ``True`` if *x* is a zero; otherwise returns ``False``." +msgstr "如果 *x* 是零則回傳 ``True``；否則回傳 ``False``。" + +#: ../../library/decimal.rst:1386 +msgid "Returns the natural (base e) logarithm of *x*." +msgstr "回傳 *x* 的自然對數（以 e 為底）。" + +#: ../../library/decimal.rst:1391 +msgid "Returns the base 10 logarithm of *x*." +msgstr "回傳 *x* 的以 10 為底的對數。" + +#: ../../library/decimal.rst:1396 +msgid "Returns the exponent of the magnitude of the operand's MSD." +msgstr "回傳運算元最高有效位數（MSD）數值的指數。" + +#: ../../library/decimal.rst:1401 +msgid "Applies the logical operation *and* between each operand's digits." +msgstr "將每個運算元的位數套用邏輯運算 *and*。" + +#: ../../library/decimal.rst:1406 +msgid "Invert all the digits in *x*." +msgstr "" + +#: ../../library/decimal.rst:1411 +msgid "Applies the logical operation *or* between each operand's digits." +msgstr "" + +#: ../../library/decimal.rst:1416 +msgid "Applies the logical operation *xor* between each operand's digits." +msgstr "" + +#: ../../library/decimal.rst:1421 +msgid "Compares two values numerically and returns the maximum." +msgstr "" + +#: ../../library/decimal.rst:1426 ../../library/decimal.rst:1436 +msgid "Compares the values numerically with their sign ignored." +msgstr "" + +#: ../../library/decimal.rst:1431 +msgid "Compares two values numerically and returns the minimum." +msgstr "" + +#: ../../library/decimal.rst:1441 +msgid "Minus corresponds to the unary prefix minus operator in Python." +msgstr "" + +#: ../../library/decimal.rst:1446 +msgid "Return the product of *x* and *y*." +msgstr "" + +#: ../../library/decimal.rst:1451 +msgid "Returns the largest representable number smaller than *x*." +msgstr "" + +#: ../../library/decimal.rst:1456 +msgid "Returns the smallest representable number larger than *x*." +msgstr "" + +#: ../../library/decimal.rst:1461 +msgid "Returns the number closest to *x*, in direction towards *y*." +msgstr "" + +#: ../../library/decimal.rst:1466 +msgid "Reduces *x* to its simplest form." +msgstr "" + +#: ../../library/decimal.rst:1471 +msgid "Returns an indication of the class of *x*." +msgstr "" + +#: ../../library/decimal.rst:1476 +msgid "" +"Plus corresponds to the unary prefix plus operator in Python. This " +"operation applies the context precision and rounding, so it is *not* an " +"identity operation." +msgstr "" + +#: ../../library/decimal.rst:1483 +msgid "Return ``x`` to the power of ``y``, reduced modulo ``modulo`` if given." +msgstr "" + +#: ../../library/decimal.rst:1485 +msgid "" +"With two arguments, compute ``x**y``. If ``x`` is negative then ``y`` must " +"be integral. The result will be inexact unless ``y`` is integral and the " +"result is finite and can be expressed exactly in 'precision' digits. The " +"rounding mode of the context is used. Results are always correctly rounded " +"in the Python version." +msgstr "" + +#: ../../library/decimal.rst:1491 +msgid "" +"``Decimal(0) ** Decimal(0)`` results in ``InvalidOperation``, and if " +"``InvalidOperation`` is not trapped, then results in ``Decimal('NaN')``." +msgstr "" + +#: ../../library/decimal.rst:1494 +msgid "" +"The C module computes :meth:`power` in terms of the correctly rounded :meth:" +"`exp` and :meth:`ln` functions. The result is well-defined but only \"almost " +"always correctly rounded\"." +msgstr "" + +#: ../../library/decimal.rst:1499 +msgid "" +"With three arguments, compute ``(x**y) % modulo``. For the three argument " +"form, the following restrictions on the arguments hold:" +msgstr "" + +#: ../../library/decimal.rst:1502 +msgid "all three arguments must be integral" +msgstr "" + +#: ../../library/decimal.rst:1503 +msgid "``y`` must be nonnegative" +msgstr "" + +#: ../../library/decimal.rst:1504 +msgid "at least one of ``x`` or ``y`` must be nonzero" +msgstr "" + +#: ../../library/decimal.rst:1505 +msgid "``modulo`` must be nonzero and have at most 'precision' digits" +msgstr "" + +#: ../../library/decimal.rst:1507 +msgid "" +"The value resulting from ``Context.power(x, y, modulo)`` is equal to the " +"value that would be obtained by computing ``(x**y) % modulo`` with unbounded " +"precision, but is computed more efficiently. The exponent of the result is " +"zero, regardless of the exponents of ``x``, ``y`` and ``modulo``. The " +"result is always exact." +msgstr "" + +#: ../../library/decimal.rst:1517 +msgid "Returns a value equal to *x* (rounded), having the exponent of *y*." +msgstr "" + +#: ../../library/decimal.rst:1522 +msgid "Just returns 10, as this is Decimal, :)" +msgstr "" + +#: ../../library/decimal.rst:1527 +msgid "Returns the remainder from integer division." +msgstr "" + +#: ../../library/decimal.rst:1529 +msgid "" +"The sign of the result, if non-zero, is the same as that of the original " +"dividend." +msgstr "" + +#: ../../library/decimal.rst:1535 +msgid "" +"Returns ``x - y * n``, where *n* is the integer nearest the exact value of " +"``x / y`` (if the result is 0 then its sign will be the sign of *x*)." +msgstr "" + +#: ../../library/decimal.rst:1541 +msgid "Returns a rotated copy of *x*, *y* times." +msgstr "" + +#: ../../library/decimal.rst:1546 +msgid "Returns ``True`` if the two operands have the same exponent." +msgstr "如果兩個運算元有相同的指數則回傳 ``True``。" + +#: ../../library/decimal.rst:1551 +msgid "Returns the first operand after adding the second value its exp." +msgstr "" + +#: ../../library/decimal.rst:1556 +msgid "Returns a shifted copy of *x*, *y* times." +msgstr "" + +#: ../../library/decimal.rst:1561 +msgid "Square root of a non-negative number to context precision." +msgstr "" + +#: ../../library/decimal.rst:1566 +msgid "Return the difference between *x* and *y*." +msgstr "" + +#: ../../library/decimal.rst:1580 +msgid "Rounds to an integer." +msgstr "" + +#: ../../library/decimal.rst:1585 +msgid "Converts a number to a string using scientific notation." +msgstr "" + +#: ../../library/decimal.rst:1592 +msgid "Constants" +msgstr "常數" + +#: ../../library/decimal.rst:1594 +msgid "" +"The constants in this section are only relevant for the C module. They are " +"also included in the pure Python version for compatibility." +msgstr "" + +#: ../../library/decimal.rst:1598 +msgid "32-bit" +msgstr "32 位元" + +#: ../../library/decimal.rst:1598 +msgid "64-bit" +msgstr "64 位元" + +#: ../../library/decimal.rst:1600 ../../library/decimal.rst:1602 +msgid "``425000000``" +msgstr "``425000000``" + +#: ../../library/decimal.rst:1600 ../../library/decimal.rst:1602 +msgid "``999999999999999999``" +msgstr "``999999999999999999``" + +#: ../../library/decimal.rst:1604 +msgid "``-425000000``" +msgstr "``-425000000``" + +#: ../../library/decimal.rst:1604 +msgid "``-999999999999999999``" +msgstr "``-999999999999999999``" + +#: ../../library/decimal.rst:1606 +msgid "``-849999999``" +msgstr "``-849999999``" + +#: ../../library/decimal.rst:1606 +msgid "``-1999999999999999997``" +msgstr "``-1999999999999999997``" + +#: ../../library/decimal.rst:1608 +msgid "``256``" +msgstr "``256``" + +#: ../../library/decimal.rst:1608 +msgid "``512``" +msgstr "``512``" + +#: ../../library/decimal.rst:1613 +msgid "" +"The value is ``True``. Deprecated, because Python now always has threads." +msgstr "" + +#: ../../library/decimal.rst:1619 +msgid "" +"The default value is ``True``. If Python is :option:`configured using the --" +"without-decimal-contextvar option <--without-decimal-contextvar>`, the C " +"version uses a thread-local rather than a coroutine-local context and the " +"value is ``False``. This is slightly faster in some nested context " +"scenarios." +msgstr "" + +#: ../../library/decimal.rst:1628 +msgid "Rounding modes" +msgstr "" + +#: ../../library/decimal.rst:1632 +msgid "Round towards ``Infinity``." +msgstr "" + +#: ../../library/decimal.rst:1636 +msgid "Round towards zero." +msgstr "" + +#: ../../library/decimal.rst:1640 +msgid "Round towards ``-Infinity``." +msgstr "" + +#: ../../library/decimal.rst:1644 +msgid "Round to nearest with ties going towards zero." +msgstr "" + +#: ../../library/decimal.rst:1648 +msgid "Round to nearest with ties going to nearest even integer." +msgstr "" + +#: ../../library/decimal.rst:1652 +msgid "Round to nearest with ties going away from zero." +msgstr "" + +#: ../../library/decimal.rst:1656 +msgid "Round away from zero." +msgstr "" + +#: ../../library/decimal.rst:1660 +msgid "" +"Round away from zero if last digit after rounding towards zero would have " +"been 0 or 5; otherwise round towards zero." +msgstr "" + +#: ../../library/decimal.rst:1667 +msgid "Signals" +msgstr "" + +#: ../../library/decimal.rst:1669 +msgid "" +"Signals represent conditions that arise during computation. Each corresponds " +"to one context flag and one context trap enabler." +msgstr "" + +#: ../../library/decimal.rst:1672 +msgid "" +"The context flag is set whenever the condition is encountered. After the " +"computation, flags may be checked for informational purposes (for instance, " +"to determine whether a computation was exact). After checking the flags, be " +"sure to clear all flags before starting the next computation." +msgstr "" + +#: ../../library/decimal.rst:1677 +msgid "" +"If the context's trap enabler is set for the signal, then the condition " +"causes a Python exception to be raised. For example, if the :class:" +"`DivisionByZero` trap is set, then a :exc:`DivisionByZero` exception is " +"raised upon encountering the condition." +msgstr "" + +#: ../../library/decimal.rst:1685 +msgid "Altered an exponent to fit representation constraints." +msgstr "" + +#: ../../library/decimal.rst:1687 +msgid "" +"Typically, clamping occurs when an exponent falls outside the context's :" +"attr:`~Context.Emin` and :attr:`~Context.Emax` limits. If possible, the " +"exponent is reduced to fit by adding zeros to the coefficient." +msgstr "" + +#: ../../library/decimal.rst:1694 +msgid "Base class for other signals and a subclass of :exc:`ArithmeticError`." +msgstr "" + +#: ../../library/decimal.rst:1699 +msgid "Signals the division of a non-infinite number by zero." +msgstr "" + +#: ../../library/decimal.rst:1701 +msgid "" +"Can occur with division, modulo division, or when raising a number to a " +"negative power. If this signal is not trapped, returns ``Infinity`` or ``-" +"Infinity`` with the sign determined by the inputs to the calculation." +msgstr "" + +#: ../../library/decimal.rst:1708 +msgid "Indicates that rounding occurred and the result is not exact." +msgstr "" + +#: ../../library/decimal.rst:1710 +msgid "" +"Signals when non-zero digits were discarded during rounding. The rounded " +"result is returned. The signal flag or trap is used to detect when results " +"are inexact." +msgstr "" + +#: ../../library/decimal.rst:1717 +msgid "An invalid operation was performed." +msgstr "" + +#: ../../library/decimal.rst:1719 +msgid "" +"Indicates that an operation was requested that does not make sense. If not " +"trapped, returns ``NaN``. Possible causes include::" +msgstr "" + +#: ../../library/decimal.rst:1722 +msgid "" +"Infinity - Infinity\n" +"0 * Infinity\n" +"Infinity / Infinity\n" +"x % 0\n" +"Infinity % x\n" +"sqrt(-x) and x > 0\n" +"0 ** 0\n" +"x ** (non-integer)\n" +"x ** Infinity" +msgstr "" +"Infinity - Infinity\n" +"0 * Infinity\n" +"Infinity / Infinity\n" +"x % 0\n" +"Infinity % x\n" +"sqrt(-x) and x > 0\n" +"0 ** 0\n" +"x ** (non-integer)\n" +"x ** Infinity" + +#: ../../library/decimal.rst:1735 +msgid "Numerical overflow." +msgstr "" + +#: ../../library/decimal.rst:1737 +msgid "" +"Indicates the exponent is larger than :attr:`Context.Emax` after rounding " +"has occurred. If not trapped, the result depends on the rounding mode, " +"either pulling inward to the largest representable finite number or rounding " +"outward to ``Infinity``. In either case, :class:`Inexact` and :class:" +"`Rounded` are also signaled." +msgstr "" + +#: ../../library/decimal.rst:1746 +msgid "Rounding occurred though possibly no information was lost." +msgstr "" + +#: ../../library/decimal.rst:1748 +msgid "" +"Signaled whenever rounding discards digits; even if those digits are zero " +"(such as rounding ``5.00`` to ``5.0``). If not trapped, returns the result " +"unchanged. This signal is used to detect loss of significant digits." +msgstr "" + +#: ../../library/decimal.rst:1756 +msgid "Exponent was lower than :attr:`~Context.Emin` prior to rounding." +msgstr "" + +#: ../../library/decimal.rst:1758 +msgid "" +"Occurs when an operation result is subnormal (the exponent is too small). If " +"not trapped, returns the result unchanged." +msgstr "" + +#: ../../library/decimal.rst:1764 +msgid "Numerical underflow with result rounded to zero." +msgstr "" + +#: ../../library/decimal.rst:1766 +msgid "" +"Occurs when a subnormal result is pushed to zero by rounding. :class:" +"`Inexact` and :class:`Subnormal` are also signaled." +msgstr "" + +#: ../../library/decimal.rst:1772 +msgid "Enable stricter semantics for mixing floats and Decimals." +msgstr "" + +#: ../../library/decimal.rst:1774 +msgid "" +"If the signal is not trapped (default), mixing floats and Decimals is " +"permitted in the :class:`~decimal.Decimal` constructor, :meth:`~decimal." +"Context.create_decimal` and all comparison operators. Both conversion and " +"comparisons are exact. Any occurrence of a mixed operation is silently " +"recorded by setting :exc:`FloatOperation` in the context flags. Explicit " +"conversions with :meth:`~decimal.Decimal.from_float` or :meth:`~decimal." +"Context.create_decimal_from_float` do not set the flag." +msgstr "" + +#: ../../library/decimal.rst:1782 +msgid "" +"Otherwise (the signal is trapped), only equality comparisons and explicit " +"conversions are silent. All other mixed operations raise :exc:" +"`FloatOperation`." +msgstr "" + +#: ../../library/decimal.rst:1786 +msgid "The following table summarizes the hierarchy of signals::" +msgstr "" + +#: ../../library/decimal.rst:1788 +msgid "" +"exceptions.ArithmeticError(exceptions.Exception)\n" +" DecimalException\n" +" Clamped\n" +" DivisionByZero(DecimalException, exceptions.ZeroDivisionError)\n" +" Inexact\n" +" Overflow(Inexact, Rounded)\n" +" Underflow(Inexact, Rounded, Subnormal)\n" +" InvalidOperation\n" +" Rounded\n" +" Subnormal\n" +" FloatOperation(DecimalException, exceptions.TypeError)" +msgstr "" +"exceptions.ArithmeticError(exceptions.Exception)\n" +" DecimalException\n" +" Clamped\n" +" DivisionByZero(DecimalException, exceptions.ZeroDivisionError)\n" +" Inexact\n" +" Overflow(Inexact, Rounded)\n" +" Underflow(Inexact, Rounded, Subnormal)\n" +" InvalidOperation\n" +" Rounded\n" +" Subnormal\n" +" FloatOperation(DecimalException, exceptions.TypeError)" + +#: ../../library/decimal.rst:1807 +msgid "Floating-point notes" +msgstr "" + +#: ../../library/decimal.rst:1811 +msgid "Mitigating round-off error with increased precision" +msgstr "" + +#: ../../library/decimal.rst:1813 +msgid "" +"The use of decimal floating point eliminates decimal representation error " +"(making it possible to represent ``0.1`` exactly); however, some operations " +"can still incur round-off error when non-zero digits exceed the fixed " +"precision." +msgstr "" + +#: ../../library/decimal.rst:1817 +msgid "" +"The effects of round-off error can be amplified by the addition or " +"subtraction of nearly offsetting quantities resulting in loss of " +"significance. Knuth provides two instructive examples where rounded " +"floating-point arithmetic with insufficient precision causes the breakdown " +"of the associative and distributive properties of addition:" +msgstr "" + +#: ../../library/decimal.rst:1823 +msgid "" +"# Examples from Seminumerical Algorithms, Section 4.2.2.\n" +">>> from decimal import Decimal, getcontext\n" +">>> getcontext().prec = 8\n" +"\n" +">>> u, v, w = Decimal(11111113), Decimal(-11111111), Decimal('7.51111111')\n" +">>> (u + v) + w\n" +"Decimal('9.5111111')\n" +">>> u + (v + w)\n" +"Decimal('10')\n" +"\n" +">>> u, v, w = Decimal(20000), Decimal(-6), Decimal('6.0000003')\n" +">>> (u*v) + (u*w)\n" +"Decimal('0.01')\n" +">>> u * (v+w)\n" +"Decimal('0.0060000')" +msgstr "" + +#: ../../library/decimal.rst:1841 +msgid "" +"The :mod:`decimal` module makes it possible to restore the identities by " +"expanding the precision sufficiently to avoid loss of significance:" +msgstr "" + +#: ../../library/decimal.rst:1844 +msgid "" +">>> getcontext().prec = 20\n" +">>> u, v, w = Decimal(11111113), Decimal(-11111111), Decimal('7.51111111')\n" +">>> (u + v) + w\n" +"Decimal('9.51111111')\n" +">>> u + (v + w)\n" +"Decimal('9.51111111')\n" +">>>\n" +">>> u, v, w = Decimal(20000), Decimal(-6), Decimal('6.0000003')\n" +">>> (u*v) + (u*w)\n" +"Decimal('0.0060000')\n" +">>> u * (v+w)\n" +"Decimal('0.0060000')" +msgstr "" +">>> getcontext().prec = 20\n" +">>> u, v, w = Decimal(11111113), Decimal(-11111111), Decimal('7.51111111')\n" +">>> (u + v) + w\n" +"Decimal('9.51111111')\n" +">>> u + (v + w)\n" +"Decimal('9.51111111')\n" +">>>\n" +">>> u, v, w = Decimal(20000), Decimal(-6), Decimal('6.0000003')\n" +">>> (u*v) + (u*w)\n" +"Decimal('0.0060000')\n" +">>> u * (v+w)\n" +"Decimal('0.0060000')" + +#: ../../library/decimal.rst:1861 +msgid "Special values" +msgstr "特殊值" + +#: ../../library/decimal.rst:1863 +msgid "" +"The number system for the :mod:`decimal` module provides special values " +"including ``NaN``, ``sNaN``, ``-Infinity``, ``Infinity``, and two zeros, " +"``+0`` and ``-0``." +msgstr "" + +#: ../../library/decimal.rst:1867 +msgid "" +"Infinities can be constructed directly with: ``Decimal('Infinity')``. Also, " +"they can arise from dividing by zero when the :exc:`DivisionByZero` signal " +"is not trapped. Likewise, when the :exc:`Overflow` signal is not trapped, " +"infinity can result from rounding beyond the limits of the largest " +"representable number." +msgstr "" + +#: ../../library/decimal.rst:1872 +msgid "" +"The infinities are signed (affine) and can be used in arithmetic operations " +"where they get treated as very large, indeterminate numbers. For instance, " +"adding a constant to infinity gives another infinite result." +msgstr "" + +#: ../../library/decimal.rst:1876 +msgid "" +"Some operations are indeterminate and return ``NaN``, or if the :exc:" +"`InvalidOperation` signal is trapped, raise an exception. For example, " +"``0/0`` returns ``NaN`` which means \"not a number\". This variety of " +"``NaN`` is quiet and, once created, will flow through other computations " +"always resulting in another ``NaN``. This behavior can be useful for a " +"series of computations that occasionally have missing inputs --- it allows " +"the calculation to proceed while flagging specific results as invalid." +msgstr "" + +#: ../../library/decimal.rst:1884 +msgid "" +"A variant is ``sNaN`` which signals rather than remaining quiet after every " +"operation. This is a useful return value when an invalid result needs to " +"interrupt a calculation for special handling." +msgstr "" + +#: ../../library/decimal.rst:1888 +msgid "" +"The behavior of Python's comparison operators can be a little surprising " +"where a ``NaN`` is involved. A test for equality where one of the operands " +"is a quiet or signaling ``NaN`` always returns :const:`False` (even when " +"doing ``Decimal('NaN')==Decimal('NaN')``), while a test for inequality " +"always returns :const:`True`. An attempt to compare two Decimals using any " +"of the ``<``, ``<=``, ``>`` or ``>=`` operators will raise the :exc:" +"`InvalidOperation` signal if either operand is a ``NaN``, and return :const:" +"`False` if this signal is not trapped. Note that the General Decimal " +"Arithmetic specification does not specify the behavior of direct " +"comparisons; these rules for comparisons involving a ``NaN`` were taken from " +"the IEEE 854 standard (see Table 3 in section 5.7). To ensure strict " +"standards-compliance, use the :meth:`~Decimal.compare` and :meth:`~Decimal." +"compare_signal` methods instead." +msgstr "" + +#: ../../library/decimal.rst:1901 +msgid "" +"The signed zeros can result from calculations that underflow. They keep the " +"sign that would have resulted if the calculation had been carried out to " +"greater precision. Since their magnitude is zero, both positive and " +"negative zeros are treated as equal and their sign is informational." +msgstr "" + +#: ../../library/decimal.rst:1906 +msgid "" +"In addition to the two signed zeros which are distinct yet equal, there are " +"various representations of zero with differing precisions yet equivalent in " +"value. This takes a bit of getting used to. For an eye accustomed to " +"normalized floating-point representations, it is not immediately obvious " +"that the following calculation returns a value equal to zero:" +msgstr "" + +#: ../../library/decimal.rst:1921 +msgid "Working with threads" +msgstr "" + +#: ../../library/decimal.rst:1923 +msgid "" +"The :func:`getcontext` function accesses a different :class:`Context` object " +"for each thread. Having separate thread contexts means that threads may " +"make changes (such as ``getcontext().prec=10``) without interfering with " +"other threads." +msgstr "" + +#: ../../library/decimal.rst:1927 +msgid "" +"Likewise, the :func:`setcontext` function automatically assigns its target " +"to the current thread." +msgstr "" + +#: ../../library/decimal.rst:1930 +msgid "" +"If :func:`setcontext` has not been called before :func:`getcontext`, then :" +"func:`getcontext` will automatically create a new context for use in the " +"current thread. New context objects have default values set from the :data:" +"`decimal.DefaultContext` object." +msgstr "" + +#: ../../library/decimal.rst:1935 +msgid "" +"The :data:`sys.flags.thread_inherit_context` flag affects the context for " +"new threads. If the flag is false, new threads will start with an empty " +"context. In this case, :func:`getcontext` will create a new context object " +"when called and use the default values from *DefaultContext*. If the flag " +"is true, new threads will start with a copy of context from the caller of :" +"meth:`threading.Thread.start`." +msgstr "" + +#: ../../library/decimal.rst:1942 +msgid "" +"To control the defaults so that each thread will use the same values " +"throughout the application, directly modify the *DefaultContext* object. " +"This should be done *before* any threads are started so that there won't be " +"a race condition between threads calling :func:`getcontext`. For example::" +msgstr "" + +#: ../../library/decimal.rst:1947 +msgid "" +"# Set applicationwide defaults for all threads about to be launched\n" +"DefaultContext.prec = 12\n" +"DefaultContext.rounding = ROUND_DOWN\n" +"DefaultContext.traps = ExtendedContext.traps.copy()\n" +"DefaultContext.traps[InvalidOperation] = 1\n" +"setcontext(DefaultContext)\n" +"\n" +"# Afterwards, the threads can be started\n" +"t1.start()\n" +"t2.start()\n" +"t3.start()\n" +" . . ." +msgstr "" + +#: ../../library/decimal.rst:1966 +msgid "Recipes" +msgstr "" + +#: ../../library/decimal.rst:1968 +msgid "" +"Here are a few recipes that serve as utility functions and that demonstrate " +"ways to work with the :class:`Decimal` class::" +msgstr "" + +#: ../../library/decimal.rst:1971 +msgid "" +"def moneyfmt(value, places=2, curr='', sep=',', dp='.',\n" +" pos='', neg='-', trailneg=''):\n" +" \"\"\"Convert Decimal to a money formatted string.\n" +"\n" +" places: required number of places after the decimal point\n" +" curr: optional currency symbol before the sign (may be blank)\n" +" sep: optional grouping separator (comma, period, space, or blank)\n" +" dp: decimal point indicator (comma or period)\n" +" only specify as blank when places is zero\n" +" pos: optional sign for positive numbers: '+', space or blank\n" +" neg: optional sign for negative numbers: '-', '(', space or blank\n" +" trailneg:optional trailing minus indicator: '-', ')', space or blank\n" +"\n" +" >>> d = Decimal('-1234567.8901')\n" +" >>> moneyfmt(d, curr='$')\n" +" '-$1,234,567.89'\n" +" >>> moneyfmt(d, places=0, sep='.', dp='', neg='', trailneg='-')\n" +" '1.234.568-'\n" +" >>> moneyfmt(d, curr='$', neg='(', trailneg=')')\n" +" '($1,234,567.89)'\n" +" >>> moneyfmt(Decimal(123456789), sep=' ')\n" +" '123 456 789.00'\n" +" >>> moneyfmt(Decimal('-0.02'), neg='<', trailneg='>')\n" +" '<0.02>'\n" +"\n" +" \"\"\"\n" +" q = Decimal(10) ** -places # 2 places --> '0.01'\n" +" sign, digits, exp = value.quantize(q).as_tuple()\n" +" result = []\n" +" digits = list(map(str, digits))\n" +" build, next = result.append, digits.pop\n" +" if sign:\n" +" build(trailneg)\n" +" for i in range(places):\n" +" build(next() if digits else '0')\n" +" if places:\n" +" build(dp)\n" +" if not digits:\n" +" build('0')\n" +" i = 0\n" +" while digits:\n" +" build(next())\n" +" i += 1\n" +" if i == 3 and digits:\n" +" i = 0\n" +" build(sep)\n" +" build(curr)\n" +" build(neg if sign else pos)\n" +" return ''.join(reversed(result))\n" +"\n" +"def pi():\n" +" \"\"\"Compute Pi to the current precision.\n" +"\n" +" >>> print(pi())\n" +" 3.141592653589793238462643383\n" +"\n" +" \"\"\"\n" +" getcontext().prec += 2 # extra digits for intermediate steps\n" +" three = Decimal(3) # substitute \"three=3.0\" for regular floats\n" +" lasts, t, s, n, na, d, da = 0, three, 3, 1, 0, 0, 24\n" +" while s != lasts:\n" +" lasts = s\n" +" n, na = n+na, na+8\n" +" d, da = d+da, da+32\n" +" t = (t * n) / d\n" +" s += t\n" +" getcontext().prec -= 2\n" +" return +s # unary plus applies the new precision\n" +"\n" +"def exp(x):\n" +" \"\"\"Return e raised to the power of x. Result type matches input " +"type.\n" +"\n" +" >>> print(exp(Decimal(1)))\n" +" 2.718281828459045235360287471\n" +" >>> print(exp(Decimal(2)))\n" +" 7.389056098930650227230427461\n" +" >>> print(exp(2.0))\n" +" 7.38905609893\n" +" >>> print(exp(2+0j))\n" +" (7.38905609893+0j)\n" +"\n" +" \"\"\"\n" +" getcontext().prec += 2\n" +" i, lasts, s, fact, num = 0, 0, 1, 1, 1\n" +" while s != lasts:\n" +" lasts = s\n" +" i += 1\n" +" fact *= i\n" +" num *= x\n" +" s += num / fact\n" +" getcontext().prec -= 2\n" +" return +s\n" +"\n" +"def cos(x):\n" +" \"\"\"Return the cosine of x as measured in radians.\n" +"\n" +" The Taylor series approximation works best for a small value of x.\n" +" For larger values, first compute x = x % (2 * pi).\n" +"\n" +" >>> print(cos(Decimal('0.5')))\n" +" 0.8775825618903727161162815826\n" +" >>> print(cos(0.5))\n" +" 0.87758256189\n" +" >>> print(cos(0.5+0j))\n" +" (0.87758256189+0j)\n" +"\n" +" \"\"\"\n" +" getcontext().prec += 2\n" +" i, lasts, s, fact, num, sign = 0, 0, 1, 1, 1, 1\n" +" while s != lasts:\n" +" lasts = s\n" +" i += 2\n" +" fact *= i * (i-1)\n" +" num *= x * x\n" +" sign *= -1\n" +" s += num / fact * sign\n" +" getcontext().prec -= 2\n" +" return +s\n" +"\n" +"def sin(x):\n" +" \"\"\"Return the sine of x as measured in radians.\n" +"\n" +" The Taylor series approximation works best for a small value of x.\n" +" For larger values, first compute x = x % (2 * pi).\n" +"\n" +" >>> print(sin(Decimal('0.5')))\n" +" 0.4794255386042030002732879352\n" +" >>> print(sin(0.5))\n" +" 0.479425538604\n" +" >>> print(sin(0.5+0j))\n" +" (0.479425538604+0j)\n" +"\n" +" \"\"\"\n" +" getcontext().prec += 2\n" +" i, lasts, s, fact, num, sign = 1, 0, x, 1, x, 1\n" +" while s != lasts:\n" +" lasts = s\n" +" i += 2\n" +" fact *= i * (i-1)\n" +" num *= x * x\n" +" sign *= -1\n" +" s += num / fact * sign\n" +" getcontext().prec -= 2\n" +" return +s" +msgstr "" + +#: ../../library/decimal.rst:2123 +msgid "Decimal FAQ" +msgstr "" + +#: ../../library/decimal.rst:2125 +msgid "" +"Q: It is cumbersome to type ``decimal.Decimal('1234.5')``. Is there a way " +"to minimize typing when using the interactive interpreter?" +msgstr "" + +#: ../../library/decimal.rst:2128 +msgid "A: Some users abbreviate the constructor to just a single letter:" +msgstr "" + +#: ../../library/decimal.rst:2134 +msgid "" +"Q: In a fixed-point application with two decimal places, some inputs have " +"many places and need to be rounded. Others are not supposed to have excess " +"digits and need to be validated. What methods should be used?" +msgstr "" + +#: ../../library/decimal.rst:2138 +msgid "" +"A: The :meth:`~Decimal.quantize` method rounds to a fixed number of decimal " +"places. If the :const:`Inexact` trap is set, it is also useful for " +"validation:" +msgstr "" + +#: ../../library/decimal.rst:2156 +msgid "" +"Q: Once I have valid two place inputs, how do I maintain that invariant " +"throughout an application?" +msgstr "" + +#: ../../library/decimal.rst:2159 +msgid "" +"A: Some operations like addition, subtraction, and multiplication by an " +"integer will automatically preserve fixed point. Others operations, like " +"division and non-integer multiplication, will change the number of decimal " +"places and need to be followed-up with a :meth:`~Decimal.quantize` step:" +msgstr "" + +#: ../../library/decimal.rst:2177 +msgid "" +"In developing fixed-point applications, it is convenient to define functions " +"to handle the :meth:`~Decimal.quantize` step:" +msgstr "" + +#: ../../library/decimal.rst:2191 +msgid "" +"Q: There are many ways to express the same value. The numbers ``200``, " +"``200.000``, ``2E2``, and ``.02E+4`` all have the same value at various " +"precisions. Is there a way to transform them to a single recognizable " +"canonical value?" +msgstr "" + +#: ../../library/decimal.rst:2196 +msgid "" +"A: The :meth:`~Decimal.normalize` method maps all equivalent values to a " +"single representative:" +msgstr "" + +#: ../../library/decimal.rst:2203 +msgid "Q: When does rounding occur in a computation?" +msgstr "" + +#: ../../library/decimal.rst:2205 +msgid "" +"A: It occurs *after* the computation. The philosophy of the decimal " +"specification is that numbers are considered exact and are created " +"independent of the current context. They can even have greater precision " +"than current context. Computations process with those exact inputs and then " +"rounding (or other context operations) is applied to the *result* of the " +"computation::" +msgstr "" + +#: ../../library/decimal.rst:2212 +msgid "" +">>> getcontext().prec = 5\n" +">>> pi = Decimal('3.1415926535') # More than 5 digits\n" +">>> pi # All digits are retained\n" +"Decimal('3.1415926535')\n" +">>> pi + 0 # Rounded after an addition\n" +"Decimal('3.1416')\n" +">>> pi - Decimal('0.00005') # Subtract unrounded numbers, then round\n" +"Decimal('3.1415')\n" +">>> pi + 0 - Decimal('0.00005'). # Intermediate values are rounded\n" +"Decimal('3.1416')" +msgstr "" + +#: ../../library/decimal.rst:2223 +msgid "" +"Q: Some decimal values always print with exponential notation. Is there a " +"way to get a non-exponential representation?" +msgstr "" + +#: ../../library/decimal.rst:2226 +msgid "" +"A: For some values, exponential notation is the only way to express the " +"number of significant places in the coefficient. For example, expressing " +"``5.0E+3`` as ``5000`` keeps the value constant but cannot show the " +"original's two-place significance." +msgstr "" + +#: ../../library/decimal.rst:2231 +msgid "" +"If an application does not care about tracking significance, it is easy to " +"remove the exponent and trailing zeroes, losing significance, but keeping " +"the value unchanged:" +msgstr "" + +#: ../../library/decimal.rst:2241 +msgid "Q: Is there a way to convert a regular float to a :class:`Decimal`?" +msgstr "" + +#: ../../library/decimal.rst:2243 +msgid "" +"A: Yes, any binary floating-point number can be exactly expressed as a " +"Decimal though an exact conversion may take more precision than intuition " +"would suggest:" +msgstr "" + +#: ../../library/decimal.rst:2247 +msgid "" +">>> Decimal(math.pi)\n" +"Decimal('3.141592653589793115997963468544185161590576171875')" +msgstr "" +">>> Decimal(math.pi)\n" +"Decimal('3.141592653589793115997963468544185161590576171875')" + +#: ../../library/decimal.rst:2252 +msgid "" +"Q: Within a complex calculation, how can I make sure that I haven't gotten a " +"spurious result because of insufficient precision or rounding anomalies." +msgstr "" + +#: ../../library/decimal.rst:2255 +msgid "" +"A: The decimal module makes it easy to test results. A best practice is to " +"re-run calculations using greater precision and with various rounding modes. " +"Widely differing results indicate insufficient precision, rounding mode " +"issues, ill-conditioned inputs, or a numerically unstable algorithm." +msgstr "" + +#: ../../library/decimal.rst:2260 +msgid "" +"Q: I noticed that context precision is applied to the results of operations " +"but not to the inputs. Is there anything to watch out for when mixing " +"values of different precisions?" +msgstr "" + +#: ../../library/decimal.rst:2264 +msgid "" +"A: Yes. The principle is that all values are considered to be exact and so " +"is the arithmetic on those values. Only the results are rounded. The " +"advantage for inputs is that \"what you type is what you get\". A " +"disadvantage is that the results can look odd if you forget that the inputs " +"haven't been rounded:" +msgstr "" + +#: ../../library/decimal.rst:2269 +msgid "" +">>> getcontext().prec = 3\n" +">>> Decimal('3.104') + Decimal('2.104')\n" +"Decimal('5.21')\n" +">>> Decimal('3.104') + Decimal('0.000') + Decimal('2.104')\n" +"Decimal('5.20')" +msgstr "" +">>> getcontext().prec = 3\n" +">>> Decimal('3.104') + Decimal('2.104')\n" +"Decimal('5.21')\n" +">>> Decimal('3.104') + Decimal('0.000') + Decimal('2.104')\n" +"Decimal('5.20')" + +#: ../../library/decimal.rst:2277 +msgid "" +"The solution is either to increase precision or to force rounding of inputs " +"using the unary plus operation:" +msgstr "" + +#: ../../library/decimal.rst:2280 +msgid "" +">>> getcontext().prec = 3\n" +">>> +Decimal('1.23456789') # unary plus triggers rounding\n" +"Decimal('1.23')" +msgstr "" + +#: ../../library/decimal.rst:2286 +msgid "" +"Alternatively, inputs can be rounded upon creation using the :meth:`Context." +"create_decimal` method:" +msgstr "" + +#: ../../library/decimal.rst:2292 +msgid "Q: Is the CPython implementation fast for large numbers?" +msgstr "" + +#: ../../library/decimal.rst:2294 +msgid "" +"A: Yes. In the CPython and PyPy3 implementations, the C/CFFI versions of " +"the decimal module integrate the high speed `libmpdec `_ library for arbitrary precision " +"correctly rounded decimal floating-point arithmetic [#]_. ``libmpdec`` uses " +"`Karatsuba multiplication `_ for medium-sized numbers and the `Number Theoretic " +"Transform `_ for very " +"large numbers." +msgstr "" + +#: ../../library/decimal.rst:2304 +msgid "" +"The context must be adapted for exact arbitrary precision arithmetic. :attr:" +"`~Context.Emin` and :attr:`~Context.Emax` should always be set to the " +"maximum values, :attr:`~Context.clamp` should always be 0 (the default). " +"Setting :attr:`~Context.prec` requires some care." +msgstr "" + +#: ../../library/decimal.rst:2308 +msgid "" +"The easiest approach for trying out bignum arithmetic is to use the maximum " +"value for :attr:`~Context.prec` as well [#]_::" +msgstr "" + +#: ../../library/decimal.rst:2311 +msgid "" +">>> setcontext(Context(prec=MAX_PREC, Emax=MAX_EMAX, Emin=MIN_EMIN))\n" +">>> x = Decimal(2) ** 256\n" +">>> x / 128\n" +"Decimal('904625697166532776746648320380374280103671755200316906558262375061821325312')" +msgstr "" +">>> setcontext(Context(prec=MAX_PREC, Emax=MAX_EMAX, Emin=MIN_EMIN))\n" +">>> x = Decimal(2) ** 256\n" +">>> x / 128\n" +"Decimal('904625697166532776746648320380374280103671755200316906558262375061821325312')" + +#: ../../library/decimal.rst:2317 +msgid "" +"For inexact results, :const:`MAX_PREC` is far too large on 64-bit platforms " +"and the available memory will be insufficient::" +msgstr "" + +#: ../../library/decimal.rst:2320 +msgid "" +">>> Decimal(1) / 3\n" +"Traceback (most recent call last):\n" +" File \"\", line 1, in \n" +"MemoryError" +msgstr "" +">>> Decimal(1) / 3\n" +"Traceback (most recent call last):\n" +" File \"\", line 1, in \n" +"MemoryError" + +#: ../../library/decimal.rst:2325 +msgid "" +"On systems with overallocation (e.g. Linux), a more sophisticated approach " +"is to adjust :attr:`~Context.prec` to the amount of available RAM. Suppose " +"that you have 8GB of RAM and expect 10 simultaneous operands using a maximum " +"of 500MB each::" +msgstr "" + +#: ../../library/decimal.rst:2329 +msgid "" +">>> import sys\n" +">>>\n" +">>> # Maximum number of digits for a single operand using 500MB in 8-byte " +"words\n" +">>> # with 19 digits per word (4-byte and 9 digits for the 32-bit build):\n" +">>> maxdigits = 19 * ((500 * 1024**2) // 8)\n" +">>>\n" +">>> # Check that this works:\n" +">>> c = Context(prec=maxdigits, Emax=MAX_EMAX, Emin=MIN_EMIN)\n" +">>> c.traps[Inexact] = True\n" +">>> setcontext(c)\n" +">>>\n" +">>> # Fill the available precision with nines:\n" +">>> x = Decimal(0).logical_invert() * 9\n" +">>> sys.getsizeof(x)\n" +"524288112\n" +">>> x + 2\n" +"Traceback (most recent call last):\n" +" File \"\", line 1, in \n" +" decimal.Inexact: []" +msgstr "" + +#: ../../library/decimal.rst:2349 +msgid "" +"In general (and especially on systems without overallocation), it is " +"recommended to estimate even tighter bounds and set the :attr:`Inexact` trap " +"if all calculations are expected to be exact." +msgstr "" + +#: ../../library/decimal.rst:2358 +msgid "" +"This approach now works for all exact results except for non-integer powers." +msgstr "" diff --git a/library/development.po b/library/development.po index 9e47eced75..c1c4b7764d 100644 --- a/library/development.po +++ b/library/development.po @@ -1,39 +1,39 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Leon H., 2017 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-09-23 07:52+0800\n" -"PO-Revision-Date: 2017-09-22 18:26+0000\n" -"Last-Translator: Leon H.\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/development.rst:5 -msgid "Development Tools" -msgstr "開發工具" - -#: ../../library/development.rst:7 -msgid "" -"The modules described in this chapter help you write software. For example, " -"the :mod:`pydoc` module takes a module and generates documentation based on " -"the module's contents. The :mod:`doctest` and :mod:`unittest` modules " -"contains frameworks for writing unit tests that automatically exercise code " -"and verify that the expected output is produced." -msgstr "" -"本章所描述的模組可以幫助你編寫軟體。例如 :mod:`pydoc` 模組可以根據模組的內容" -"生成文件；:mod:`doctest` 和 :mod:`unittest` 模組則包含編寫單元測試的框架，這" -"些測試程式碼會自動執行並驗證輸出結果是否正確。" - -#: ../../library/development.rst:13 -msgid "The list of modules described in this chapter is:" -msgstr "本章節所描述的模組列表為：" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Leon H., 2017 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-09-23 07:52+0800\n" +"PO-Revision-Date: 2017-09-22 18:26+0000\n" +"Last-Translator: Leon H.\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/development.rst:5 +msgid "Development Tools" +msgstr "開發工具" + +#: ../../library/development.rst:7 +msgid "" +"The modules described in this chapter help you write software. For example, " +"the :mod:`pydoc` module takes a module and generates documentation based on " +"the module's contents. The :mod:`doctest` and :mod:`unittest` modules " +"contains frameworks for writing unit tests that automatically exercise code " +"and verify that the expected output is produced." +msgstr "" +"本章所描述的模組可以幫助你編寫軟體。例如 :mod:`pydoc` 模組可以根據模組的內容" +"生成文件；:mod:`doctest` 和 :mod:`unittest` 模組則包含編寫單元測試的框架，這" +"些測試程式碼會自動執行並驗證輸出結果是否正確。" + +#: ../../library/development.rst:13 +msgid "The list of modules described in this chapter is:" +msgstr "本章節所描述的模組列表為：" diff --git a/library/devmode.po b/library/devmode.po index 3d05d82aac..f16f6bd382 100644 --- a/library/devmode.po +++ b/library/devmode.po @@ -1,490 +1,490 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Matt Wang , 2024 -#, fuzzy -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-09-01 22:24+0800\n" -"PO-Revision-Date: 2024-05-03 02:14+0800\n" -"Last-Translator: Matt Wang \n" -"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" -"tw)\n" -"Language: zh_TW\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=UTF-8\n" -"Content-Transfer-Encoding: 8bit\n" - -#: ../../library/devmode.rst:4 -msgid "Python Development Mode" -msgstr "Python 開發模式" - -#: ../../library/devmode.rst:8 -msgid "" -"The Python Development Mode introduces additional runtime checks that are " -"too expensive to be enabled by default. It should not be more verbose than " -"the default if the code is correct; new warnings are only emitted when an " -"issue is detected." -msgstr "" -"Python 開發模式引入了額外的 runtime 檢查，預設啟用這些檢查的成本太高。如果程" -"式碼正確，它不應比預設值更詳細；僅當偵測到問題時才會發出新警告。" - -#: ../../library/devmode.rst:13 -msgid "" -"It can be enabled using the :option:`-X dev <-X>` command line option or by " -"setting the :envvar:`PYTHONDEVMODE` environment variable to ``1``." -msgstr "" -"可以使用 :option:`-X dev <-X>` 命令列選項或將 :envvar:`PYTHONDEVMODE` 環境變" -"數設為 1 來啟用它。" - -#: ../../library/devmode.rst:16 -msgid "See also :ref:`Python debug build `." -msgstr "另請參閱 :ref:`Python 除錯建置 `。" - -#: ../../library/devmode.rst:19 -msgid "Effects of the Python Development Mode" -msgstr "Python 開發模式的影響" - -#: ../../library/devmode.rst:21 -msgid "" -"Enabling the Python Development Mode is similar to the following command, " -"but with additional effects described below::" -msgstr "啟用 Python 開發模式類似以下指令，但具有如下所述的附加效果：" - -#: ../../library/devmode.rst:24 -msgid "" -"PYTHONMALLOC=debug PYTHONASYNCIODEBUG=1 python -W default -X faulthandler" -msgstr "" -"PYTHONMALLOC=debug PYTHONASYNCIODEBUG=1 python -W default -X faulthandler" - -#: ../../library/devmode.rst:26 -msgid "Effects of the Python Development Mode:" -msgstr "Python 開發模式的效果：" - -#: ../../library/devmode.rst:28 -msgid "" -"Add ``default`` :ref:`warning filter `. The " -"following warnings are shown:" -msgstr "" -"新增 ``default`` :ref:`警告過濾器 `。以下警告會被" -"顯示：" - -#: ../../library/devmode.rst:31 -msgid ":exc:`DeprecationWarning`" -msgstr ":exc:`DeprecationWarning`" - -#: ../../library/devmode.rst:32 -msgid ":exc:`ImportWarning`" -msgstr ":exc:`ImportWarning`" - -#: ../../library/devmode.rst:33 -msgid ":exc:`PendingDeprecationWarning`" -msgstr ":exc:`PendingDeprecationWarning`" - -#: ../../library/devmode.rst:34 -msgid ":exc:`ResourceWarning`" -msgstr ":exc:`ResourceWarning`" - -#: ../../library/devmode.rst:36 -msgid "" -"Normally, the above warnings are filtered by the default :ref:`warning " -"filters `." -msgstr "" -"一般來說，上述警告會被預設的\\ :ref:`警告過濾器 `\\ 給過濾掉。" - -#: ../../library/devmode.rst:39 -msgid "" -"It behaves as if the :option:`-W default <-W>` command line option is used." -msgstr "它的行為就像使用 :option:`-W default <-W>` 命令列選項一樣。" - -#: ../../library/devmode.rst:41 -msgid "" -"Use the :option:`-W error <-W>` command line option or set the :envvar:" -"`PYTHONWARNINGS` environment variable to ``error`` to treat warnings as " -"errors." -msgstr "" -"使用 :option:`-W error <-W>` 命令列選項或將 :envvar:`PYTHONWARNINGS` 環境變數" -"設為 ``error`` 會將警告視為錯誤。" - -#: ../../library/devmode.rst:45 -msgid "Install debug hooks on memory allocators to check for:" -msgstr "在記憶體分配器上安裝除錯 hook（掛鉤）以檢查：" - -#: ../../library/devmode.rst:47 -msgid "Buffer underflow" -msgstr "緩衝區下溢 (underflow)" - -#: ../../library/devmode.rst:48 -msgid "Buffer overflow" -msgstr "緩衝區溢位 (overflow)" - -#: ../../library/devmode.rst:49 -msgid "Memory allocator API violation" -msgstr "記憶體分配器 API 違規" - -#: ../../library/devmode.rst:50 -msgid "Unsafe usage of the GIL" -msgstr "GIL 的不安全使用" - -#: ../../library/devmode.rst:52 -msgid "See the :c:func:`PyMem_SetupDebugHooks` C function." -msgstr "請參閱 :c:func:`PyMem_SetupDebugHooks` C 函式。" - -#: ../../library/devmode.rst:54 -msgid "" -"It behaves as if the :envvar:`PYTHONMALLOC` environment variable is set to " -"``debug``." -msgstr "" -"它的行為就好像是將 :envvar:`PYTHONMALLOC` 環境變數設定為 ``debug`` 一樣。" - -#: ../../library/devmode.rst:57 -msgid "" -"To enable the Python Development Mode without installing debug hooks on " -"memory allocators, set the :envvar:`PYTHONMALLOC` environment variable to " -"``default``." -msgstr "" -"若要啟用 Python 開發模式而不在記憶體分配器上安裝偵錯 hook，請將 :envvar:" -"`PYTHONMALLOC` 環境變數設為 ``default``。" - -#: ../../library/devmode.rst:61 -msgid "" -"Call :func:`faulthandler.enable` at Python startup to install handlers for " -"the :const:`~signal.SIGSEGV`, :const:`~signal.SIGFPE`, :const:`~signal." -"SIGABRT`, :const:`~signal.SIGBUS` and :const:`~signal.SIGILL` signals to " -"dump the Python traceback on a crash." -msgstr "" -"在 Python 啟動時呼叫 :func:`faulthandler.enable` 來為 :const:`~signal." -"SIGSEGV`、:const:`~signal.SIGFPE`、:const:`~signal.SIGABRT`、:const:`~signal." -"SIGBUS` 和 :const:`~signal.SIGILL` 訊號安裝處理函式以在當機時傾印 (dump) " -"Python 回溯 (traceback)。" - -#: ../../library/devmode.rst:66 -msgid "" -"It behaves as if the :option:`-X faulthandler <-X>` command line option is " -"used or if the :envvar:`PYTHONFAULTHANDLER` environment variable is set to " -"``1``." -msgstr "" -"它的行為就像使用 :option:`-X faulthandler <-X>` 命令列選項或將 :envvar:" -"`PYTHONFAULTHANDLER` 環境變數設定為 ``1``。" - -#: ../../library/devmode.rst:70 -msgid "" -"Enable :ref:`asyncio debug mode `. For example, :mod:" -"`asyncio` checks for coroutines that were not awaited and logs them." -msgstr "" -"啟用 :ref:`asyncio 除錯模式 `。例如 :mod:`asyncio` 會檢查" -"未被等待的 (not awaited) 協程並記錄 (log) 它們。" - -#: ../../library/devmode.rst:73 -msgid "" -"It behaves as if the :envvar:`PYTHONASYNCIODEBUG` environment variable is " -"set to ``1``." -msgstr "它的行為就像將 :envvar:`PYTHONASYNCIODEBUG` 環境變數設定為 1 一樣。" - -#: ../../library/devmode.rst:76 -msgid "" -"Check the *encoding* and *errors* arguments for string encoding and decoding " -"operations. Examples: :func:`open`, :meth:`str.encode` and :meth:`bytes." -"decode`." -msgstr "" -"檢查字串編碼和解碼操作的 *encoding* 和 *errors* 引數。例如：:func:`open`、:" -"meth:`str.encode` 和 :meth:`bytes.decode`。" - -#: ../../library/devmode.rst:80 -msgid "" -"By default, for best performance, the *errors* argument is only checked at " -"the first encoding/decoding error and the *encoding* argument is sometimes " -"ignored for empty strings." -msgstr "" -"預設情況下，為了獲得最佳效能，僅在第一個編碼/解碼錯誤時檢查 *errors* 引數，並" -"且有時會因為是空字串而忽略 *encoding* 引數。" - -#: ../../library/devmode.rst:84 -msgid "The :class:`io.IOBase` destructor logs ``close()`` exceptions." -msgstr ":class:`io.IOBase` 解構函式會記錄 ``close()`` 例外。" - -#: ../../library/devmode.rst:85 -msgid "" -"Set the :attr:`~sys.flags.dev_mode` attribute of :data:`sys.flags` to " -"``True``." -msgstr "" -"將 :data:`sys.flags` 的 :attr:`~sys.flags.dev_mode` 屬性設為 ``True``。" - -#: ../../library/devmode.rst:88 -msgid "" -"The Python Development Mode does not enable the :mod:`tracemalloc` module by " -"default, because the overhead cost (to performance and memory) would be too " -"large. Enabling the :mod:`tracemalloc` module provides additional " -"information on the origin of some errors. For example, :exc:" -"`ResourceWarning` logs the traceback where the resource was allocated, and a " -"buffer overflow error logs the traceback where the memory block was " -"allocated." -msgstr "" -"Python 開發模式預設不會啟用 :mod:`tracemalloc` 模組，因為（效能和記憶體的）開" -"銷太大。啟用 :mod:`tracemalloc` 模組可提供有關某些錯誤來源的附加資訊。例如 :" -"exc:`ResourceWarning` 記錄了分配資源之處的回溯、緩衝區溢位錯誤記錄了分配記憶" -"體區塊的回溯。" - -#: ../../library/devmode.rst:95 -msgid "" -"The Python Development Mode does not prevent the :option:`-O` command line " -"option from removing :keyword:`assert` statements nor from setting :const:" -"`__debug__` to ``False``." -msgstr "" -"Python 開發模式不會防止 :option:`-O` 命令列選項刪除 :keyword:`assert` 陳述" -"式，也不會防止將 :const:`__debug__` 設定為 ``False``。" - -#: ../../library/devmode.rst:99 -msgid "" -"The Python Development Mode can only be enabled at the Python startup. Its " -"value can be read from :data:`sys.flags.dev_mode `." -msgstr "" -"Python 開發模式只能在 Python 啟動時啟用。它的值可以從 :data:`sys.flags." -"dev_mode ` 讀取。" - -#: ../../library/devmode.rst:102 -msgid "The :class:`io.IOBase` destructor now logs ``close()`` exceptions." -msgstr ":class:`io.IOBase` 解構函式現在會記錄 ``close()`` 例外。" - -#: ../../library/devmode.rst:105 -msgid "" -"The *encoding* and *errors* arguments are now checked for string encoding " -"and decoding operations." -msgstr "現在會為字串編碼和解碼操作檢查 *encoding* 和 *errors* 引數。" - -#: ../../library/devmode.rst:111 -msgid "ResourceWarning Example" -msgstr "ResourceWarning 範例" - -#: ../../library/devmode.rst:113 -msgid "" -"Example of a script counting the number of lines of the text file specified " -"in the command line::" -msgstr "計算命令列中指定的文字檔案列數的腳本範例： ::" - -#: ../../library/devmode.rst:116 -msgid "" -"import sys\n" -"\n" -"def main():\n" -" fp = open(sys.argv[1])\n" -" nlines = len(fp.readlines())\n" -" print(nlines)\n" -" # The file is closed implicitly\n" -"\n" -"if __name__ == \"__main__\":\n" -" main()" -msgstr "" -"import sys\n" -"\n" -"def main():\n" -" fp = open(sys.argv[1])\n" -" nlines = len(fp.readlines())\n" -" print(nlines)\n" -" # The file is closed implicitly\n" -"\n" -"if __name__ == \"__main__\":\n" -" main()" - -#: ../../library/devmode.rst:127 -msgid "" -"The script does not close the file explicitly. By default, Python does not " -"emit any warning. Example using README.txt, which has 269 lines:" -msgstr "" -"該腳本不會明確關閉檔案。預設情況下，Python 不會發出任何警告。使用 README.txt " -"的範例，該檔案有 269 列：" - -#: ../../library/devmode.rst:130 -msgid "" -"$ python script.py README.txt\n" -"269" -msgstr "" -"$ python script.py README.txt\n" -"269" - -#: ../../library/devmode.rst:135 -msgid "" -"Enabling the Python Development Mode displays a :exc:`ResourceWarning` " -"warning:" -msgstr "啟用 Python 開發模式會顯示 :exc:`ResourceWarning` 警告：" - -#: ../../library/devmode.rst:137 -msgid "" -"$ python -X dev script.py README.txt\n" -"269\n" -"script.py:10: ResourceWarning: unclosed file <_io.TextIOWrapper name='README." -"rst' mode='r' encoding='UTF-8'>\n" -" main()\n" -"ResourceWarning: Enable tracemalloc to get the object allocation traceback" -msgstr "" -"$ python -X dev script.py README.txt\n" -"269\n" -"script.py:10: ResourceWarning: unclosed file <_io.TextIOWrapper name='README." -"rst' mode='r' encoding='UTF-8'>\n" -" main()\n" -"ResourceWarning: Enable tracemalloc to get the object allocation traceback" - -#: ../../library/devmode.rst:145 -msgid "" -"In addition, enabling :mod:`tracemalloc` shows the line where the file was " -"opened:" -msgstr "此外，啟用 :mod:`tracemalloc` 會顯示檔案被開啟的那一列：" - -#: ../../library/devmode.rst:148 -msgid "" -"$ python -X dev -X tracemalloc=5 script.py README.rst\n" -"269\n" -"script.py:10: ResourceWarning: unclosed file <_io.TextIOWrapper name='README." -"rst' mode='r' encoding='UTF-8'>\n" -" main()\n" -"Object allocated at (most recent call last):\n" -" File \"script.py\", lineno 10\n" -" main()\n" -" File \"script.py\", lineno 4\n" -" fp = open(sys.argv[1])" -msgstr "" -"$ python -X dev -X tracemalloc=5 script.py README.rst\n" -"269\n" -"script.py:10: ResourceWarning: unclosed file <_io.TextIOWrapper name='README." -"rst' mode='r' encoding='UTF-8'>\n" -" main()\n" -"Object allocated at (most recent call last):\n" -" File \"script.py\", lineno 10\n" -" main()\n" -" File \"script.py\", lineno 4\n" -" fp = open(sys.argv[1])" - -#: ../../library/devmode.rst:160 -msgid "" -"The fix is to close explicitly the file. Example using a context manager::" -msgstr "修復方法是明確關閉該檔案。以下是使用情境管理器的範例： ::" - -#: ../../library/devmode.rst:162 -msgid "" -"def main():\n" -" # Close the file explicitly when exiting the with block\n" -" with open(sys.argv[1]) as fp:\n" -" nlines = len(fp.readlines())\n" -" print(nlines)" -msgstr "" -"def main():\n" -" # 在退出 with 區塊時明確關閉檔案\n" -" with open(sys.argv[1]) as fp:\n" -" nlines = len(fp.readlines())\n" -" print(nlines)" - -#: ../../library/devmode.rst:168 -msgid "" -"Not closing a resource explicitly can leave a resource open for way longer " -"than expected; it can cause severe issues upon exiting Python. It is bad in " -"CPython, but it is even worse in PyPy. Closing resources explicitly makes an " -"application more deterministic and more reliable." -msgstr "" -"不明確關閉資源可能會使資源開啟的時間比預期的長得多；它可能會在退出 Python 時" -"導致嚴重問題。在 CPython 中很糟糕，但在 PyPy 中更糟。明確關閉資源使應用程式更" -"具確定性和可靠性。" - -#: ../../library/devmode.rst:175 -msgid "Bad file descriptor error example" -msgstr "檔案描述器的錯誤範例" - -#: ../../library/devmode.rst:177 -msgid "Script displaying the first line of itself::" -msgstr "顯示自身第一列的腳本： ::" - -#: ../../library/devmode.rst:179 -msgid "" -"import os\n" -"\n" -"def main():\n" -" fp = open(__file__)\n" -" firstline = fp.readline()\n" -" print(firstline.rstrip())\n" -" os.close(fp.fileno())\n" -" # The file is closed implicitly\n" -"\n" -"main()" -msgstr "" -"import os\n" -"\n" -"def main():\n" -" fp = open(__file__)\n" -" firstline = fp.readline()\n" -" print(firstline.rstrip())\n" -" os.close(fp.fileno())\n" -" # 檔案是隱式關閉的\n" -"\n" -"main()" - -#: ../../library/devmode.rst:190 -msgid "By default, Python does not emit any warning:" -msgstr "預設情況下，Python 不會發出任何警告：" - -#: ../../library/devmode.rst:192 -msgid "" -"$ python script.py\n" -"import os" -msgstr "" -"$ python script.py\n" -"import os" - -#: ../../library/devmode.rst:197 -msgid "" -"The Python Development Mode shows a :exc:`ResourceWarning` and logs a \"Bad " -"file descriptor\" error when finalizing the file object:" -msgstr "" -"Python 開發模式在最終化 (finalize) 檔案物件時顯示 :exc:`ResourceWarning` 並記" -"錄 \"Bad file descriptor\" 錯誤：" - -#: ../../library/devmode.rst:200 -msgid "" -"$ python -X dev script.py\n" -"import os\n" -"script.py:10: ResourceWarning: unclosed file <_io.TextIOWrapper name='script." -"py' mode='r' encoding='UTF-8'>\n" -" main()\n" -"ResourceWarning: Enable tracemalloc to get the object allocation traceback\n" -"Exception ignored in: <_io.TextIOWrapper name='script.py' mode='r' " -"encoding='UTF-8'>\n" -"Traceback (most recent call last):\n" -" File \"script.py\", line 10, in \n" -" main()\n" -"OSError: [Errno 9] Bad file descriptor" -msgstr "" -"$ python -X dev script.py\n" -"import os\n" -"script.py:10: ResourceWarning: unclosed file <_io.TextIOWrapper name='script." -"py' mode='r' encoding='UTF-8'>\n" -" main()\n" -"ResourceWarning: Enable tracemalloc to get the object allocation traceback\n" -"Exception ignored in: <_io.TextIOWrapper name='script.py' mode='r' " -"encoding='UTF-8'>\n" -"Traceback (most recent call last):\n" -" File \"script.py\", line 10, in \n" -" main()\n" -"OSError: [Errno 9] Bad file descriptor" - -#: ../../library/devmode.rst:213 -msgid "" -"``os.close(fp.fileno())`` closes the file descriptor. When the file object " -"finalizer tries to close the file descriptor again, it fails with the ``Bad " -"file descriptor`` error. A file descriptor must be closed only once. In the " -"worst case scenario, closing it twice can lead to a crash (see :issue:" -"`18748` for an example)." -msgstr "" -"``os.close(fp.fileno())`` 會關閉檔案描述器。當檔案物件最終化函式 (finalizer) " -"嘗試再次關閉檔案描述器時，它會失敗並出現 ``Bad file descriptor`` 錯誤。檔案描" -"述器只能關閉一次。在最壞的情況下，將它關閉兩次可能會導致崩潰 (crash)（相關範" -"例請參閱 :issue:`18748`）。" - -#: ../../library/devmode.rst:219 -msgid "" -"The fix is to remove the ``os.close(fp.fileno())`` line, or open the file " -"with ``closefd=False``." -msgstr "" -"修復方法是刪除 ``os.close(fp.fileno())`` 那列，或使用 ``closefd=False`` 開啟" -"檔案。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Matt Wang , 2024 +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-09-01 22:24+0800\n" +"PO-Revision-Date: 2024-05-03 02:14+0800\n" +"Last-Translator: Matt Wang \n" +"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" +"tw)\n" +"Language: zh_TW\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../library/devmode.rst:4 +msgid "Python Development Mode" +msgstr "Python 開發模式" + +#: ../../library/devmode.rst:8 +msgid "" +"The Python Development Mode introduces additional runtime checks that are " +"too expensive to be enabled by default. It should not be more verbose than " +"the default if the code is correct; new warnings are only emitted when an " +"issue is detected." +msgstr "" +"Python 開發模式引入了額外的 runtime 檢查，預設啟用這些檢查的成本太高。如果程" +"式碼正確，它不應比預設值更詳細；僅當偵測到問題時才會發出新警告。" + +#: ../../library/devmode.rst:13 +msgid "" +"It can be enabled using the :option:`-X dev <-X>` command line option or by " +"setting the :envvar:`PYTHONDEVMODE` environment variable to ``1``." +msgstr "" +"可以使用 :option:`-X dev <-X>` 命令列選項或將 :envvar:`PYTHONDEVMODE` 環境變" +"數設為 1 來啟用它。" + +#: ../../library/devmode.rst:16 +msgid "See also :ref:`Python debug build `." +msgstr "另請參閱 :ref:`Python 除錯建置 `。" + +#: ../../library/devmode.rst:19 +msgid "Effects of the Python Development Mode" +msgstr "Python 開發模式的影響" + +#: ../../library/devmode.rst:21 +msgid "" +"Enabling the Python Development Mode is similar to the following command, " +"but with additional effects described below::" +msgstr "啟用 Python 開發模式類似以下指令，但具有如下所述的附加效果：" + +#: ../../library/devmode.rst:24 +msgid "" +"PYTHONMALLOC=debug PYTHONASYNCIODEBUG=1 python -W default -X faulthandler" +msgstr "" +"PYTHONMALLOC=debug PYTHONASYNCIODEBUG=1 python -W default -X faulthandler" + +#: ../../library/devmode.rst:26 +msgid "Effects of the Python Development Mode:" +msgstr "Python 開發模式的效果：" + +#: ../../library/devmode.rst:28 +msgid "" +"Add ``default`` :ref:`warning filter `. The " +"following warnings are shown:" +msgstr "" +"新增 ``default`` :ref:`警告過濾器 `。以下警告會被" +"顯示：" + +#: ../../library/devmode.rst:31 +msgid ":exc:`DeprecationWarning`" +msgstr ":exc:`DeprecationWarning`" + +#: ../../library/devmode.rst:32 +msgid ":exc:`ImportWarning`" +msgstr ":exc:`ImportWarning`" + +#: ../../library/devmode.rst:33 +msgid ":exc:`PendingDeprecationWarning`" +msgstr ":exc:`PendingDeprecationWarning`" + +#: ../../library/devmode.rst:34 +msgid ":exc:`ResourceWarning`" +msgstr ":exc:`ResourceWarning`" + +#: ../../library/devmode.rst:36 +msgid "" +"Normally, the above warnings are filtered by the default :ref:`warning " +"filters `." +msgstr "" +"一般來說，上述警告會被預設的\\ :ref:`警告過濾器 `\\ 給過濾掉。" + +#: ../../library/devmode.rst:39 +msgid "" +"It behaves as if the :option:`-W default <-W>` command line option is used." +msgstr "它的行為就像使用 :option:`-W default <-W>` 命令列選項一樣。" + +#: ../../library/devmode.rst:41 +msgid "" +"Use the :option:`-W error <-W>` command line option or set the :envvar:" +"`PYTHONWARNINGS` environment variable to ``error`` to treat warnings as " +"errors." +msgstr "" +"使用 :option:`-W error <-W>` 命令列選項或將 :envvar:`PYTHONWARNINGS` 環境變數" +"設為 ``error`` 會將警告視為錯誤。" + +#: ../../library/devmode.rst:45 +msgid "Install debug hooks on memory allocators to check for:" +msgstr "在記憶體分配器上安裝除錯 hook（掛鉤）以檢查：" + +#: ../../library/devmode.rst:47 +msgid "Buffer underflow" +msgstr "緩衝區下溢 (underflow)" + +#: ../../library/devmode.rst:48 +msgid "Buffer overflow" +msgstr "緩衝區溢位 (overflow)" + +#: ../../library/devmode.rst:49 +msgid "Memory allocator API violation" +msgstr "記憶體分配器 API 違規" + +#: ../../library/devmode.rst:50 +msgid "Unsafe usage of the GIL" +msgstr "GIL 的不安全使用" + +#: ../../library/devmode.rst:52 +msgid "See the :c:func:`PyMem_SetupDebugHooks` C function." +msgstr "請參閱 :c:func:`PyMem_SetupDebugHooks` C 函式。" + +#: ../../library/devmode.rst:54 +msgid "" +"It behaves as if the :envvar:`PYTHONMALLOC` environment variable is set to " +"``debug``." +msgstr "" +"它的行為就好像是將 :envvar:`PYTHONMALLOC` 環境變數設定為 ``debug`` 一樣。" + +#: ../../library/devmode.rst:57 +msgid "" +"To enable the Python Development Mode without installing debug hooks on " +"memory allocators, set the :envvar:`PYTHONMALLOC` environment variable to " +"``default``." +msgstr "" +"若要啟用 Python 開發模式而不在記憶體分配器上安裝偵錯 hook，請將 :envvar:" +"`PYTHONMALLOC` 環境變數設為 ``default``。" + +#: ../../library/devmode.rst:61 +msgid "" +"Call :func:`faulthandler.enable` at Python startup to install handlers for " +"the :const:`~signal.SIGSEGV`, :const:`~signal.SIGFPE`, :const:`~signal." +"SIGABRT`, :const:`~signal.SIGBUS` and :const:`~signal.SIGILL` signals to " +"dump the Python traceback on a crash." +msgstr "" +"在 Python 啟動時呼叫 :func:`faulthandler.enable` 來為 :const:`~signal." +"SIGSEGV`、:const:`~signal.SIGFPE`、:const:`~signal.SIGABRT`、:const:`~signal." +"SIGBUS` 和 :const:`~signal.SIGILL` 訊號安裝處理函式以在當機時傾印 (dump) " +"Python 回溯 (traceback)。" + +#: ../../library/devmode.rst:66 +msgid "" +"It behaves as if the :option:`-X faulthandler <-X>` command line option is " +"used or if the :envvar:`PYTHONFAULTHANDLER` environment variable is set to " +"``1``." +msgstr "" +"它的行為就像使用 :option:`-X faulthandler <-X>` 命令列選項或將 :envvar:" +"`PYTHONFAULTHANDLER` 環境變數設定為 ``1``。" + +#: ../../library/devmode.rst:70 +msgid "" +"Enable :ref:`asyncio debug mode `. For example, :mod:" +"`asyncio` checks for coroutines that were not awaited and logs them." +msgstr "" +"啟用 :ref:`asyncio 除錯模式 `。例如 :mod:`asyncio` 會檢查" +"未被等待的 (not awaited) 協程並記錄 (log) 它們。" + +#: ../../library/devmode.rst:73 +msgid "" +"It behaves as if the :envvar:`PYTHONASYNCIODEBUG` environment variable is " +"set to ``1``." +msgstr "它的行為就像將 :envvar:`PYTHONASYNCIODEBUG` 環境變數設定為 1 一樣。" + +#: ../../library/devmode.rst:76 +msgid "" +"Check the *encoding* and *errors* arguments for string encoding and decoding " +"operations. Examples: :func:`open`, :meth:`str.encode` and :meth:`bytes." +"decode`." +msgstr "" +"檢查字串編碼和解碼操作的 *encoding* 和 *errors* 引數。例如：:func:`open`、:" +"meth:`str.encode` 和 :meth:`bytes.decode`。" + +#: ../../library/devmode.rst:80 +msgid "" +"By default, for best performance, the *errors* argument is only checked at " +"the first encoding/decoding error and the *encoding* argument is sometimes " +"ignored for empty strings." +msgstr "" +"預設情況下，為了獲得最佳效能，僅在第一個編碼/解碼錯誤時檢查 *errors* 引數，並" +"且有時會因為是空字串而忽略 *encoding* 引數。" + +#: ../../library/devmode.rst:84 +msgid "The :class:`io.IOBase` destructor logs ``close()`` exceptions." +msgstr ":class:`io.IOBase` 解構函式會記錄 ``close()`` 例外。" + +#: ../../library/devmode.rst:85 +msgid "" +"Set the :attr:`~sys.flags.dev_mode` attribute of :data:`sys.flags` to " +"``True``." +msgstr "" +"將 :data:`sys.flags` 的 :attr:`~sys.flags.dev_mode` 屬性設為 ``True``。" + +#: ../../library/devmode.rst:88 +msgid "" +"The Python Development Mode does not enable the :mod:`tracemalloc` module by " +"default, because the overhead cost (to performance and memory) would be too " +"large. Enabling the :mod:`tracemalloc` module provides additional " +"information on the origin of some errors. For example, :exc:" +"`ResourceWarning` logs the traceback where the resource was allocated, and a " +"buffer overflow error logs the traceback where the memory block was " +"allocated." +msgstr "" +"Python 開發模式預設不會啟用 :mod:`tracemalloc` 模組，因為（效能和記憶體的）開" +"銷太大。啟用 :mod:`tracemalloc` 模組可提供有關某些錯誤來源的附加資訊。例如 :" +"exc:`ResourceWarning` 記錄了分配資源之處的回溯、緩衝區溢位錯誤記錄了分配記憶" +"體區塊的回溯。" + +#: ../../library/devmode.rst:95 +msgid "" +"The Python Development Mode does not prevent the :option:`-O` command line " +"option from removing :keyword:`assert` statements nor from setting :const:" +"`__debug__` to ``False``." +msgstr "" +"Python 開發模式不會防止 :option:`-O` 命令列選項刪除 :keyword:`assert` 陳述" +"式，也不會防止將 :const:`__debug__` 設定為 ``False``。" + +#: ../../library/devmode.rst:99 +msgid "" +"The Python Development Mode can only be enabled at the Python startup. Its " +"value can be read from :data:`sys.flags.dev_mode `." +msgstr "" +"Python 開發模式只能在 Python 啟動時啟用。它的值可以從 :data:`sys.flags." +"dev_mode ` 讀取。" + +#: ../../library/devmode.rst:102 +msgid "The :class:`io.IOBase` destructor now logs ``close()`` exceptions." +msgstr ":class:`io.IOBase` 解構函式現在會記錄 ``close()`` 例外。" + +#: ../../library/devmode.rst:105 +msgid "" +"The *encoding* and *errors* arguments are now checked for string encoding " +"and decoding operations." +msgstr "現在會為字串編碼和解碼操作檢查 *encoding* 和 *errors* 引數。" + +#: ../../library/devmode.rst:111 +msgid "ResourceWarning Example" +msgstr "ResourceWarning 範例" + +#: ../../library/devmode.rst:113 +msgid "" +"Example of a script counting the number of lines of the text file specified " +"in the command line::" +msgstr "計算命令列中指定的文字檔案列數的腳本範例： ::" + +#: ../../library/devmode.rst:116 +msgid "" +"import sys\n" +"\n" +"def main():\n" +" fp = open(sys.argv[1])\n" +" nlines = len(fp.readlines())\n" +" print(nlines)\n" +" # The file is closed implicitly\n" +"\n" +"if __name__ == \"__main__\":\n" +" main()" +msgstr "" +"import sys\n" +"\n" +"def main():\n" +" fp = open(sys.argv[1])\n" +" nlines = len(fp.readlines())\n" +" print(nlines)\n" +" # The file is closed implicitly\n" +"\n" +"if __name__ == \"__main__\":\n" +" main()" + +#: ../../library/devmode.rst:127 +msgid "" +"The script does not close the file explicitly. By default, Python does not " +"emit any warning. Example using README.txt, which has 269 lines:" +msgstr "" +"該腳本不會明確關閉檔案。預設情況下，Python 不會發出任何警告。使用 README.txt " +"的範例，該檔案有 269 列：" + +#: ../../library/devmode.rst:130 +msgid "" +"$ python script.py README.txt\n" +"269" +msgstr "" +"$ python script.py README.txt\n" +"269" + +#: ../../library/devmode.rst:135 +msgid "" +"Enabling the Python Development Mode displays a :exc:`ResourceWarning` " +"warning:" +msgstr "啟用 Python 開發模式會顯示 :exc:`ResourceWarning` 警告：" + +#: ../../library/devmode.rst:137 +msgid "" +"$ python -X dev script.py README.txt\n" +"269\n" +"script.py:10: ResourceWarning: unclosed file <_io.TextIOWrapper name='README." +"rst' mode='r' encoding='UTF-8'>\n" +" main()\n" +"ResourceWarning: Enable tracemalloc to get the object allocation traceback" +msgstr "" +"$ python -X dev script.py README.txt\n" +"269\n" +"script.py:10: ResourceWarning: unclosed file <_io.TextIOWrapper name='README." +"rst' mode='r' encoding='UTF-8'>\n" +" main()\n" +"ResourceWarning: Enable tracemalloc to get the object allocation traceback" + +#: ../../library/devmode.rst:145 +msgid "" +"In addition, enabling :mod:`tracemalloc` shows the line where the file was " +"opened:" +msgstr "此外，啟用 :mod:`tracemalloc` 會顯示檔案被開啟的那一列：" + +#: ../../library/devmode.rst:148 +msgid "" +"$ python -X dev -X tracemalloc=5 script.py README.rst\n" +"269\n" +"script.py:10: ResourceWarning: unclosed file <_io.TextIOWrapper name='README." +"rst' mode='r' encoding='UTF-8'>\n" +" main()\n" +"Object allocated at (most recent call last):\n" +" File \"script.py\", lineno 10\n" +" main()\n" +" File \"script.py\", lineno 4\n" +" fp = open(sys.argv[1])" +msgstr "" +"$ python -X dev -X tracemalloc=5 script.py README.rst\n" +"269\n" +"script.py:10: ResourceWarning: unclosed file <_io.TextIOWrapper name='README." +"rst' mode='r' encoding='UTF-8'>\n" +" main()\n" +"Object allocated at (most recent call last):\n" +" File \"script.py\", lineno 10\n" +" main()\n" +" File \"script.py\", lineno 4\n" +" fp = open(sys.argv[1])" + +#: ../../library/devmode.rst:160 +msgid "" +"The fix is to close explicitly the file. Example using a context manager::" +msgstr "修復方法是明確關閉該檔案。以下是使用情境管理器的範例： ::" + +#: ../../library/devmode.rst:162 +msgid "" +"def main():\n" +" # Close the file explicitly when exiting the with block\n" +" with open(sys.argv[1]) as fp:\n" +" nlines = len(fp.readlines())\n" +" print(nlines)" +msgstr "" +"def main():\n" +" # 在退出 with 區塊時明確關閉檔案\n" +" with open(sys.argv[1]) as fp:\n" +" nlines = len(fp.readlines())\n" +" print(nlines)" + +#: ../../library/devmode.rst:168 +msgid "" +"Not closing a resource explicitly can leave a resource open for way longer " +"than expected; it can cause severe issues upon exiting Python. It is bad in " +"CPython, but it is even worse in PyPy. Closing resources explicitly makes an " +"application more deterministic and more reliable." +msgstr "" +"不明確關閉資源可能會使資源開啟的時間比預期的長得多；它可能會在退出 Python 時" +"導致嚴重問題。在 CPython 中很糟糕，但在 PyPy 中更糟。明確關閉資源使應用程式更" +"具確定性和可靠性。" + +#: ../../library/devmode.rst:175 +msgid "Bad file descriptor error example" +msgstr "檔案描述器的錯誤範例" + +#: ../../library/devmode.rst:177 +msgid "Script displaying the first line of itself::" +msgstr "顯示自身第一列的腳本： ::" + +#: ../../library/devmode.rst:179 +msgid "" +"import os\n" +"\n" +"def main():\n" +" fp = open(__file__)\n" +" firstline = fp.readline()\n" +" print(firstline.rstrip())\n" +" os.close(fp.fileno())\n" +" # The file is closed implicitly\n" +"\n" +"main()" +msgstr "" +"import os\n" +"\n" +"def main():\n" +" fp = open(__file__)\n" +" firstline = fp.readline()\n" +" print(firstline.rstrip())\n" +" os.close(fp.fileno())\n" +" # 檔案是隱式關閉的\n" +"\n" +"main()" + +#: ../../library/devmode.rst:190 +msgid "By default, Python does not emit any warning:" +msgstr "預設情況下，Python 不會發出任何警告：" + +#: ../../library/devmode.rst:192 +msgid "" +"$ python script.py\n" +"import os" +msgstr "" +"$ python script.py\n" +"import os" + +#: ../../library/devmode.rst:197 +msgid "" +"The Python Development Mode shows a :exc:`ResourceWarning` and logs a \"Bad " +"file descriptor\" error when finalizing the file object:" +msgstr "" +"Python 開發模式在最終化 (finalize) 檔案物件時顯示 :exc:`ResourceWarning` 並記" +"錄 \"Bad file descriptor\" 錯誤：" + +#: ../../library/devmode.rst:200 +msgid "" +"$ python -X dev script.py\n" +"import os\n" +"script.py:10: ResourceWarning: unclosed file <_io.TextIOWrapper name='script." +"py' mode='r' encoding='UTF-8'>\n" +" main()\n" +"ResourceWarning: Enable tracemalloc to get the object allocation traceback\n" +"Exception ignored in: <_io.TextIOWrapper name='script.py' mode='r' " +"encoding='UTF-8'>\n" +"Traceback (most recent call last):\n" +" File \"script.py\", line 10, in \n" +" main()\n" +"OSError: [Errno 9] Bad file descriptor" +msgstr "" +"$ python -X dev script.py\n" +"import os\n" +"script.py:10: ResourceWarning: unclosed file <_io.TextIOWrapper name='script." +"py' mode='r' encoding='UTF-8'>\n" +" main()\n" +"ResourceWarning: Enable tracemalloc to get the object allocation traceback\n" +"Exception ignored in: <_io.TextIOWrapper name='script.py' mode='r' " +"encoding='UTF-8'>\n" +"Traceback (most recent call last):\n" +" File \"script.py\", line 10, in \n" +" main()\n" +"OSError: [Errno 9] Bad file descriptor" + +#: ../../library/devmode.rst:213 +msgid "" +"``os.close(fp.fileno())`` closes the file descriptor. When the file object " +"finalizer tries to close the file descriptor again, it fails with the ``Bad " +"file descriptor`` error. A file descriptor must be closed only once. In the " +"worst case scenario, closing it twice can lead to a crash (see :issue:" +"`18748` for an example)." +msgstr "" +"``os.close(fp.fileno())`` 會關閉檔案描述器。當檔案物件最終化函式 (finalizer) " +"嘗試再次關閉檔案描述器時，它會失敗並出現 ``Bad file descriptor`` 錯誤。檔案描" +"述器只能關閉一次。在最壞的情況下，將它關閉兩次可能會導致崩潰 (crash)（相關範" +"例請參閱 :issue:`18748`）。" + +#: ../../library/devmode.rst:219 +msgid "" +"The fix is to remove the ``os.close(fp.fileno())`` line, or open the file " +"with ``closefd=False``." +msgstr "" +"修復方法是刪除 ``os.close(fp.fileno())`` 那列，或使用 ``closefd=False`` 開啟" +"檔案。" diff --git a/library/dialog.po b/library/dialog.po index 7bc9c50cda..9394557dfa 100644 --- a/library/dialog.po +++ b/library/dialog.po @@ -1,286 +1,286 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# FIRST AUTHOR , YEAR. -# -#, fuzzy -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-12-01 00:17+0000\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" -"tw)\n" -"Language: zh_TW\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=UTF-8\n" -"Content-Transfer-Encoding: 8bit\n" - -#: ../../library/dialog.rst:2 -msgid "Tkinter Dialogs" -msgstr "Tkinter 對話框" - -#: ../../library/dialog.rst:5 -msgid ":mod:`tkinter.simpledialog` --- Standard Tkinter input dialogs" -msgstr ":mod:`tkinter.simpledialog` --- 標準 Tkinter 輸入對話框" - -#: ../../library/dialog.rst:11 -msgid "**Source code:** :source:`Lib/tkinter/simpledialog.py`" -msgstr "**原始碼：**\\ :source:`Lib/tkinter/simpledialog.py`" - -#: ../../library/dialog.rst:15 -msgid "" -"The :mod:`tkinter.simpledialog` module contains convenience classes and " -"functions for creating simple modal dialogs to get a value from the user." -msgstr "" - -#: ../../library/dialog.rst:23 -msgid "" -"The above three functions provide dialogs that prompt the user to enter a " -"value of the desired type." -msgstr "" - -#: ../../library/dialog.rst:28 -msgid "The base class for custom dialogs." -msgstr "" - -#: ../../library/dialog.rst:32 -msgid "" -"Override to construct the dialog's interface and return the widget that " -"should have initial focus." -msgstr "" - -#: ../../library/dialog.rst:37 -msgid "" -"Default behaviour adds OK and Cancel buttons. Override for custom button " -"layouts." -msgstr "" - -#: ../../library/dialog.rst:43 -msgid ":mod:`tkinter.filedialog` --- File selection dialogs" -msgstr ":mod:`tkinter.filedialog` --- 檔案選擇對話框" - -#: ../../library/dialog.rst:49 -msgid "**Source code:** :source:`Lib/tkinter/filedialog.py`" -msgstr "**原始碼：**\\ :source:`Lib/tkinter/filedialog.py`" - -#: ../../library/dialog.rst:53 -msgid "" -"The :mod:`tkinter.filedialog` module provides classes and factory functions " -"for creating file/directory selection windows." -msgstr "" - -#: ../../library/dialog.rst:57 -msgid "Native Load/Save Dialogs" -msgstr "" - -#: ../../library/dialog.rst:59 -msgid "" -"The following classes and functions provide file dialog windows that combine " -"a native look-and-feel with configuration options to customize behaviour. " -"The following keyword arguments are applicable to the classes and functions " -"listed below:" -msgstr "" - -#: ../../library/dialog.rst:64 -msgid "*parent* - the window to place the dialog on top of" -msgstr "" - -#: ../../library/dialog.rst:66 -msgid "*title* - the title of the window" -msgstr "" - -#: ../../library/dialog.rst:68 -msgid "*initialdir* - the directory that the dialog starts in" -msgstr "" - -#: ../../library/dialog.rst:70 -msgid "*initialfile* - the file selected upon opening of the dialog" -msgstr "" - -#: ../../library/dialog.rst:72 -msgid "" -"*filetypes* - a sequence of (label, pattern) tuples, '*' wildcard is allowed" -msgstr "" - -#: ../../library/dialog.rst:74 -msgid "*defaultextension* - default extension to append to file (save dialogs)" -msgstr "" - -#: ../../library/dialog.rst:76 -msgid "*multiple* - when true, selection of multiple items is allowed" -msgstr "" - -#: ../../library/dialog.rst:79 -msgid "**Static factory functions**" -msgstr "" - -#: ../../library/dialog.rst:81 -msgid "" -"The below functions when called create a modal, native look-and-feel dialog, " -"wait for the user's selection, then return the selected value(s) or ``None`` " -"to the caller." -msgstr "" - -#: ../../library/dialog.rst:88 -msgid "" -"The above two functions create an :class:`Open` dialog and return the opened " -"file object(s) in read-only mode." -msgstr "" - -#: ../../library/dialog.rst:93 -msgid "" -"Create a :class:`SaveAs` dialog and return a file object opened in write-" -"only mode." -msgstr "" - -#: ../../library/dialog.rst:98 -msgid "" -"The above two functions create an :class:`Open` dialog and return the " -"selected filename(s) that correspond to existing file(s)." -msgstr "" - -#: ../../library/dialog.rst:103 -msgid "Create a :class:`SaveAs` dialog and return the selected filename." -msgstr "" - -#: ../../library/dialog.rst:107 -msgid "Prompt user to select a directory." -msgstr "" - -#: ../../library/dialog.rst:108 -msgid "Additional keyword option:" -msgstr "" - -#: ../../library/dialog.rst:109 -msgid "*mustexist* - determines if selection must be an existing directory." -msgstr "" - -#: ../../library/dialog.rst:114 -msgid "" -"The above two classes provide native dialog windows for saving and loading " -"files." -msgstr "" - -#: ../../library/dialog.rst:117 -msgid "**Convenience classes**" -msgstr "" - -#: ../../library/dialog.rst:119 -msgid "" -"The below classes are used for creating file/directory windows from scratch. " -"These do not emulate the native look-and-feel of the platform." -msgstr "" - -#: ../../library/dialog.rst:124 -msgid "Create a dialog prompting the user to select a directory." -msgstr "" - -#: ../../library/dialog.rst:126 -msgid "" -"The *FileDialog* class should be subclassed for custom event handling and " -"behaviour." -msgstr "" - -#: ../../library/dialog.rst:131 -msgid "Create a basic file selection dialog." -msgstr "" - -#: ../../library/dialog.rst:135 -msgid "Trigger the termination of the dialog window." -msgstr "" - -#: ../../library/dialog.rst:139 -msgid "Event handler for double-click event on directory." -msgstr "" - -#: ../../library/dialog.rst:143 -msgid "Event handler for click event on directory." -msgstr "" - -#: ../../library/dialog.rst:147 -msgid "Event handler for double-click event on file." -msgstr "" - -#: ../../library/dialog.rst:151 -msgid "Event handler for single-click event on file." -msgstr "" - -#: ../../library/dialog.rst:155 -msgid "Filter the files by directory." -msgstr "" - -#: ../../library/dialog.rst:159 -msgid "Retrieve the file filter currently in use." -msgstr "" - -#: ../../library/dialog.rst:163 -msgid "Retrieve the currently selected item." -msgstr "" - -#: ../../library/dialog.rst:167 -msgid "Render dialog and start event loop." -msgstr "" - -#: ../../library/dialog.rst:171 -msgid "Exit dialog returning current selection." -msgstr "" - -#: ../../library/dialog.rst:175 -msgid "Exit dialog returning filename, if any." -msgstr "" - -#: ../../library/dialog.rst:179 -msgid "Set the file filter." -msgstr "" - -#: ../../library/dialog.rst:183 -msgid "Update the current file selection to *file*." -msgstr "" - -#: ../../library/dialog.rst:188 -msgid "" -"A subclass of FileDialog that creates a dialog window for selecting an " -"existing file." -msgstr "" - -#: ../../library/dialog.rst:193 -msgid "" -"Test that a file is provided and that the selection indicates an already " -"existing file." -msgstr "" - -#: ../../library/dialog.rst:198 -msgid "" -"A subclass of FileDialog that creates a dialog window for selecting a " -"destination file." -msgstr "" - -#: ../../library/dialog.rst:203 -msgid "" -"Test whether or not the selection points to a valid file that is not a " -"directory. Confirmation is required if an already existing file is selected." -msgstr "" - -#: ../../library/dialog.rst:208 -msgid ":mod:`tkinter.commondialog` --- Dialog window templates" -msgstr "" - -#: ../../library/dialog.rst:214 -msgid "**Source code:** :source:`Lib/tkinter/commondialog.py`" -msgstr "**原始碼：**\\ :source:`Lib/tkinter/commondialog.py`" - -#: ../../library/dialog.rst:218 -msgid "" -"The :mod:`tkinter.commondialog` module provides the :class:`Dialog` class " -"that is the base class for dialogs defined in other supporting modules." -msgstr "" - -#: ../../library/dialog.rst:225 -msgid "Render the Dialog window." -msgstr "" - -#: ../../library/dialog.rst:230 -msgid "Modules :mod:`tkinter.messagebox`, :ref:`tut-files`" -msgstr ":mod:`tkinter.messagebox` 模組、:ref:`tut-files`" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-12-01 00:17+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" +"tw)\n" +"Language: zh_TW\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../library/dialog.rst:2 +msgid "Tkinter Dialogs" +msgstr "Tkinter 對話框" + +#: ../../library/dialog.rst:5 +msgid ":mod:`tkinter.simpledialog` --- Standard Tkinter input dialogs" +msgstr ":mod:`tkinter.simpledialog` --- 標準 Tkinter 輸入對話框" + +#: ../../library/dialog.rst:11 +msgid "**Source code:** :source:`Lib/tkinter/simpledialog.py`" +msgstr "**原始碼：**\\ :source:`Lib/tkinter/simpledialog.py`" + +#: ../../library/dialog.rst:15 +msgid "" +"The :mod:`tkinter.simpledialog` module contains convenience classes and " +"functions for creating simple modal dialogs to get a value from the user." +msgstr "" + +#: ../../library/dialog.rst:23 +msgid "" +"The above three functions provide dialogs that prompt the user to enter a " +"value of the desired type." +msgstr "" + +#: ../../library/dialog.rst:28 +msgid "The base class for custom dialogs." +msgstr "" + +#: ../../library/dialog.rst:32 +msgid "" +"Override to construct the dialog's interface and return the widget that " +"should have initial focus." +msgstr "" + +#: ../../library/dialog.rst:37 +msgid "" +"Default behaviour adds OK and Cancel buttons. Override for custom button " +"layouts." +msgstr "" + +#: ../../library/dialog.rst:43 +msgid ":mod:`tkinter.filedialog` --- File selection dialogs" +msgstr ":mod:`tkinter.filedialog` --- 檔案選擇對話框" + +#: ../../library/dialog.rst:49 +msgid "**Source code:** :source:`Lib/tkinter/filedialog.py`" +msgstr "**原始碼：**\\ :source:`Lib/tkinter/filedialog.py`" + +#: ../../library/dialog.rst:53 +msgid "" +"The :mod:`tkinter.filedialog` module provides classes and factory functions " +"for creating file/directory selection windows." +msgstr "" + +#: ../../library/dialog.rst:57 +msgid "Native Load/Save Dialogs" +msgstr "" + +#: ../../library/dialog.rst:59 +msgid "" +"The following classes and functions provide file dialog windows that combine " +"a native look-and-feel with configuration options to customize behaviour. " +"The following keyword arguments are applicable to the classes and functions " +"listed below:" +msgstr "" + +#: ../../library/dialog.rst:64 +msgid "*parent* - the window to place the dialog on top of" +msgstr "" + +#: ../../library/dialog.rst:66 +msgid "*title* - the title of the window" +msgstr "" + +#: ../../library/dialog.rst:68 +msgid "*initialdir* - the directory that the dialog starts in" +msgstr "" + +#: ../../library/dialog.rst:70 +msgid "*initialfile* - the file selected upon opening of the dialog" +msgstr "" + +#: ../../library/dialog.rst:72 +msgid "" +"*filetypes* - a sequence of (label, pattern) tuples, '*' wildcard is allowed" +msgstr "" + +#: ../../library/dialog.rst:74 +msgid "*defaultextension* - default extension to append to file (save dialogs)" +msgstr "" + +#: ../../library/dialog.rst:76 +msgid "*multiple* - when true, selection of multiple items is allowed" +msgstr "" + +#: ../../library/dialog.rst:79 +msgid "**Static factory functions**" +msgstr "" + +#: ../../library/dialog.rst:81 +msgid "" +"The below functions when called create a modal, native look-and-feel dialog, " +"wait for the user's selection, then return the selected value(s) or ``None`` " +"to the caller." +msgstr "" + +#: ../../library/dialog.rst:88 +msgid "" +"The above two functions create an :class:`Open` dialog and return the opened " +"file object(s) in read-only mode." +msgstr "" + +#: ../../library/dialog.rst:93 +msgid "" +"Create a :class:`SaveAs` dialog and return a file object opened in write-" +"only mode." +msgstr "" + +#: ../../library/dialog.rst:98 +msgid "" +"The above two functions create an :class:`Open` dialog and return the " +"selected filename(s) that correspond to existing file(s)." +msgstr "" + +#: ../../library/dialog.rst:103 +msgid "Create a :class:`SaveAs` dialog and return the selected filename." +msgstr "" + +#: ../../library/dialog.rst:107 +msgid "Prompt user to select a directory." +msgstr "" + +#: ../../library/dialog.rst:108 +msgid "Additional keyword option:" +msgstr "" + +#: ../../library/dialog.rst:109 +msgid "*mustexist* - determines if selection must be an existing directory." +msgstr "" + +#: ../../library/dialog.rst:114 +msgid "" +"The above two classes provide native dialog windows for saving and loading " +"files." +msgstr "" + +#: ../../library/dialog.rst:117 +msgid "**Convenience classes**" +msgstr "" + +#: ../../library/dialog.rst:119 +msgid "" +"The below classes are used for creating file/directory windows from scratch. " +"These do not emulate the native look-and-feel of the platform." +msgstr "" + +#: ../../library/dialog.rst:124 +msgid "Create a dialog prompting the user to select a directory." +msgstr "" + +#: ../../library/dialog.rst:126 +msgid "" +"The *FileDialog* class should be subclassed for custom event handling and " +"behaviour." +msgstr "" + +#: ../../library/dialog.rst:131 +msgid "Create a basic file selection dialog." +msgstr "" + +#: ../../library/dialog.rst:135 +msgid "Trigger the termination of the dialog window." +msgstr "" + +#: ../../library/dialog.rst:139 +msgid "Event handler for double-click event on directory." +msgstr "" + +#: ../../library/dialog.rst:143 +msgid "Event handler for click event on directory." +msgstr "" + +#: ../../library/dialog.rst:147 +msgid "Event handler for double-click event on file." +msgstr "" + +#: ../../library/dialog.rst:151 +msgid "Event handler for single-click event on file." +msgstr "" + +#: ../../library/dialog.rst:155 +msgid "Filter the files by directory." +msgstr "" + +#: ../../library/dialog.rst:159 +msgid "Retrieve the file filter currently in use." +msgstr "" + +#: ../../library/dialog.rst:163 +msgid "Retrieve the currently selected item." +msgstr "" + +#: ../../library/dialog.rst:167 +msgid "Render dialog and start event loop." +msgstr "" + +#: ../../library/dialog.rst:171 +msgid "Exit dialog returning current selection." +msgstr "" + +#: ../../library/dialog.rst:175 +msgid "Exit dialog returning filename, if any." +msgstr "" + +#: ../../library/dialog.rst:179 +msgid "Set the file filter." +msgstr "" + +#: ../../library/dialog.rst:183 +msgid "Update the current file selection to *file*." +msgstr "" + +#: ../../library/dialog.rst:188 +msgid "" +"A subclass of FileDialog that creates a dialog window for selecting an " +"existing file." +msgstr "" + +#: ../../library/dialog.rst:193 +msgid "" +"Test that a file is provided and that the selection indicates an already " +"existing file." +msgstr "" + +#: ../../library/dialog.rst:198 +msgid "" +"A subclass of FileDialog that creates a dialog window for selecting a " +"destination file." +msgstr "" + +#: ../../library/dialog.rst:203 +msgid "" +"Test whether or not the selection points to a valid file that is not a " +"directory. Confirmation is required if an already existing file is selected." +msgstr "" + +#: ../../library/dialog.rst:208 +msgid ":mod:`tkinter.commondialog` --- Dialog window templates" +msgstr "" + +#: ../../library/dialog.rst:214 +msgid "**Source code:** :source:`Lib/tkinter/commondialog.py`" +msgstr "**原始碼：**\\ :source:`Lib/tkinter/commondialog.py`" + +#: ../../library/dialog.rst:218 +msgid "" +"The :mod:`tkinter.commondialog` module provides the :class:`Dialog` class " +"that is the base class for dialogs defined in other supporting modules." +msgstr "" + +#: ../../library/dialog.rst:225 +msgid "Render the Dialog window." +msgstr "" + +#: ../../library/dialog.rst:230 +msgid "Modules :mod:`tkinter.messagebox`, :ref:`tut-files`" +msgstr ":mod:`tkinter.messagebox` 模組、:ref:`tut-files`" diff --git a/library/difflib.po b/library/difflib.po index 8db7c3d59a..fb8f63b398 100644 --- a/library/difflib.po +++ b/library/difflib.po @@ -1,1129 +1,1129 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-10-08 00:15+0000\n" -"PO-Revision-Date: 2016-11-19 00:29+0000\n" -"Last-Translator: Liang-Bo Wang \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/difflib.rst:2 -msgid ":mod:`!difflib` --- Helpers for computing deltas" -msgstr ":mod:`!difflib` --- 計算差異的輔助工具" - -#: ../../library/difflib.rst:11 -msgid "**Source code:** :source:`Lib/difflib.py`" -msgstr "**原始碼：**\\ :source:`Lib/difflib.py`" - -#: ../../library/difflib.rst:20 -msgid "" -"This module provides classes and functions for comparing sequences. It can " -"be used for example, for comparing files, and can produce information about " -"file differences in various formats, including HTML and context and unified " -"diffs. For comparing directories and files, see also, the :mod:`filecmp` " -"module." -msgstr "" - -#: ../../library/difflib.rst:29 -msgid "" -"This is a flexible class for comparing pairs of sequences of any type, so " -"long as the sequence elements are :term:`hashable`. The basic algorithm " -"predates, and is a little fancier than, an algorithm published in the late " -"1980's by Ratcliff and Obershelp under the hyperbolic name \"gestalt pattern " -"matching.\" The idea is to find the longest contiguous matching subsequence " -"that contains no \"junk\" elements; these \"junk\" elements are ones that " -"are uninteresting in some sense, such as blank lines or whitespace. " -"(Handling junk is an extension to the Ratcliff and Obershelp algorithm.) The " -"same idea is then applied recursively to the pieces of the sequences to the " -"left and to the right of the matching subsequence. This does not yield " -"minimal edit sequences, but does tend to yield matches that \"look right\" " -"to people." -msgstr "" - -#: ../../library/difflib.rst:41 -msgid "" -"**Timing:** The basic Ratcliff-Obershelp algorithm is cubic time in the " -"worst case and quadratic time in the expected case. :class:`SequenceMatcher` " -"is quadratic time for the worst case and has expected-case behavior " -"dependent in a complicated way on how many elements the sequences have in " -"common; best case time is linear." -msgstr "" - -#: ../../library/difflib.rst:47 -msgid "" -"**Automatic junk heuristic:** :class:`SequenceMatcher` supports a heuristic " -"that automatically treats certain sequence items as junk. The heuristic " -"counts how many times each individual item appears in the sequence. If an " -"item's duplicates (after the first one) account for more than 1% of the " -"sequence and the sequence is at least 200 items long, this item is marked as " -"\"popular\" and is treated as junk for the purpose of sequence matching. " -"This heuristic can be turned off by setting the ``autojunk`` argument to " -"``False`` when creating the :class:`SequenceMatcher`." -msgstr "" - -#: ../../library/difflib.rst:55 ../../library/difflib.rst:386 -msgid "Added the *autojunk* parameter." -msgstr "新增 *autojunk* 參數。" - -#: ../../library/difflib.rst:61 -msgid "" -"This is a class for comparing sequences of lines of text, and producing " -"human-readable differences or deltas. Differ uses :class:`SequenceMatcher` " -"both to compare sequences of lines, and to compare sequences of characters " -"within similar (near-matching) lines." -msgstr "" - -#: ../../library/difflib.rst:66 -msgid "Each line of a :class:`Differ` delta begins with a two-letter code:" -msgstr "" - -#: ../../library/difflib.rst:69 -msgid "Code" -msgstr "程式碼" - -#: ../../library/difflib.rst:69 ../../library/difflib.rst:496 -msgid "Meaning" -msgstr "含義" - -#: ../../library/difflib.rst:71 -msgid "``'- '``" -msgstr "``'- '``" - -#: ../../library/difflib.rst:71 -msgid "line unique to sequence 1" -msgstr "" - -#: ../../library/difflib.rst:73 -msgid "``'+ '``" -msgstr "``'+ '``" - -#: ../../library/difflib.rst:73 -msgid "line unique to sequence 2" -msgstr "" - -#: ../../library/difflib.rst:75 -msgid "``' '``" -msgstr "``' '``" - -#: ../../library/difflib.rst:75 -msgid "line common to both sequences" -msgstr "" - -#: ../../library/difflib.rst:77 -msgid "``'? '``" -msgstr "``'? '``" - -#: ../../library/difflib.rst:77 -msgid "line not present in either input sequence" -msgstr "" - -#: ../../library/difflib.rst:80 -msgid "" -"Lines beginning with '``?``' attempt to guide the eye to intraline " -"differences, and were not present in either input sequence. These lines can " -"be confusing if the sequences contain whitespace characters, such as spaces, " -"tabs or line breaks." -msgstr "" - -#: ../../library/difflib.rst:87 -msgid "" -"This class can be used to create an HTML table (or a complete HTML file " -"containing the table) showing a side by side, line by line comparison of " -"text with inter-line and intra-line change highlights. The table can be " -"generated in either full or contextual difference mode." -msgstr "" - -#: ../../library/difflib.rst:92 -msgid "The constructor for this class is:" -msgstr "" - -#: ../../library/difflib.rst:97 -msgid "Initializes instance of :class:`HtmlDiff`." -msgstr "" - -#: ../../library/difflib.rst:99 -msgid "" -"*tabsize* is an optional keyword argument to specify tab stop spacing and " -"defaults to ``8``." -msgstr "" - -#: ../../library/difflib.rst:102 -msgid "" -"*wrapcolumn* is an optional keyword to specify column number where lines are " -"broken and wrapped, defaults to ``None`` where lines are not wrapped." -msgstr "" - -#: ../../library/difflib.rst:105 -msgid "" -"*linejunk* and *charjunk* are optional keyword arguments passed into :func:" -"`ndiff` (used by :class:`HtmlDiff` to generate the side by side HTML " -"differences). See :func:`ndiff` documentation for argument default values " -"and descriptions." -msgstr "" - -#: ../../library/difflib.rst:109 -msgid "The following methods are public:" -msgstr "" - -#: ../../library/difflib.rst:114 -msgid "" -"Compares *fromlines* and *tolines* (lists of strings) and returns a string " -"which is a complete HTML file containing a table showing line by line " -"differences with inter-line and intra-line changes highlighted." -msgstr "" - -#: ../../library/difflib.rst:118 -msgid "" -"*fromdesc* and *todesc* are optional keyword arguments to specify from/to " -"file column header strings (both default to an empty string)." -msgstr "" - -#: ../../library/difflib.rst:121 -msgid "" -"*context* and *numlines* are both optional keyword arguments. Set *context* " -"to ``True`` when contextual differences are to be shown, else the default is " -"``False`` to show the full files. *numlines* defaults to ``5``. When " -"*context* is ``True`` *numlines* controls the number of context lines which " -"surround the difference highlights. When *context* is ``False`` *numlines* " -"controls the number of lines which are shown before a difference highlight " -"when using the \"next\" hyperlinks (setting to zero would cause the \"next\" " -"hyperlinks to place the next difference highlight at the top of the browser " -"without any leading context)." -msgstr "" - -#: ../../library/difflib.rst:132 -msgid "" -"*fromdesc* and *todesc* are interpreted as unescaped HTML and should be " -"properly escaped while receiving input from untrusted sources." -msgstr "" - -#: ../../library/difflib.rst:135 -msgid "" -"*charset* keyword-only argument was added. The default charset of HTML " -"document changed from ``'ISO-8859-1'`` to ``'utf-8'``." -msgstr "" - -#: ../../library/difflib.rst:141 -msgid "" -"Compares *fromlines* and *tolines* (lists of strings) and returns a string " -"which is a complete HTML table showing line by line differences with inter-" -"line and intra-line changes highlighted." -msgstr "" - -#: ../../library/difflib.rst:145 -msgid "" -"The arguments for this method are the same as those for the :meth:" -"`make_file` method." -msgstr "" - -#: ../../library/difflib.rst:152 -msgid "" -"Compare *a* and *b* (lists of strings); return a delta (a :term:`generator` " -"generating the delta lines) in context diff format." -msgstr "" - -#: ../../library/difflib.rst:155 -msgid "" -"Context diffs are a compact way of showing just the lines that have changed " -"plus a few lines of context. The changes are shown in a before/after " -"style. The number of context lines is set by *n* which defaults to three." -msgstr "" - -#: ../../library/difflib.rst:159 -msgid "" -"By default, the diff control lines (those with ``***`` or ``---``) are " -"created with a trailing newline. This is helpful so that inputs created " -"from :func:`io.IOBase.readlines` result in diffs that are suitable for use " -"with :func:`io.IOBase.writelines` since both the inputs and outputs have " -"trailing newlines." -msgstr "" - -#: ../../library/difflib.rst:165 ../../library/difflib.rst:297 -msgid "" -"For inputs that do not have trailing newlines, set the *lineterm* argument " -"to ``\"\"`` so that the output will be uniformly newline free." -msgstr "" - -#: ../../library/difflib.rst:168 -msgid "" -"The context diff format normally has a header for filenames and modification " -"times. Any or all of these may be specified using strings for *fromfile*, " -"*tofile*, *fromfiledate*, and *tofiledate*. The modification times are " -"normally expressed in the ISO 8601 format. If not specified, the strings " -"default to blanks." -msgstr "" - -#: ../../library/difflib.rst:194 ../../library/difflib.rst:320 -msgid "See :ref:`difflib-interface` for a more detailed example." -msgstr "一個更詳盡的範例請見 :ref:`difflib-interface`。" - -#: ../../library/difflib.rst:199 -msgid "" -"Return a list of the best \"good enough\" matches. *word* is a sequence for " -"which close matches are desired (typically a string), and *possibilities* is " -"a list of sequences against which to match *word* (typically a list of " -"strings)." -msgstr "" - -#: ../../library/difflib.rst:203 -msgid "" -"Optional argument *n* (default ``3``) is the maximum number of close matches " -"to return; *n* must be greater than ``0``." -msgstr "" - -#: ../../library/difflib.rst:206 -msgid "" -"Optional argument *cutoff* (default ``0.6``) is a float in the range [0, 1]. " -"Possibilities that don't score at least that similar to *word* are ignored." -msgstr "" - -#: ../../library/difflib.rst:209 -msgid "" -"The best (no more than *n*) matches among the possibilities are returned in " -"a list, sorted by similarity score, most similar first." -msgstr "" - -#: ../../library/difflib.rst:225 -msgid "" -"Compare *a* and *b* (lists of strings); return a :class:`Differ`\\ -style " -"delta (a :term:`generator` generating the delta lines)." -msgstr "" - -#: ../../library/difflib.rst:228 -msgid "" -"Optional keyword parameters *linejunk* and *charjunk* are filtering " -"functions (or ``None``):" -msgstr "" - -#: ../../library/difflib.rst:231 -msgid "" -"*linejunk*: A function that accepts a single string argument, and returns " -"true if the string is junk, or false if not. The default is ``None``. There " -"is also a module-level function :func:`IS_LINE_JUNK`, which filters out " -"lines without visible characters, except for at most one hash character " -"(``'#'``) -- however the underlying :class:`SequenceMatcher` class does a " -"dynamic analysis of which lines are so frequent as to constitute noise, and " -"this usually works better than using this function." -msgstr "" - -#: ../../library/difflib.rst:239 -msgid "" -"*charjunk*: A function that accepts a character (a string of length 1), and " -"returns if the character is junk, or false if not. The default is module-" -"level function :func:`IS_CHARACTER_JUNK`, which filters out whitespace " -"characters (a blank or tab; it's a bad idea to include newline in this!)." -msgstr "" - -#: ../../library/difflib.rst:260 -msgid "Return one of the two sequences that generated a delta." -msgstr "" - -#: ../../library/difflib.rst:262 -msgid "" -"Given a *sequence* produced by :meth:`Differ.compare` or :func:`ndiff`, " -"extract lines originating from file 1 or 2 (parameter *which*), stripping " -"off line prefixes." -msgstr "" - -#: ../../library/difflib.rst:266 -msgid "Example:" -msgstr "範例：" - -#: ../../library/difflib.rst:283 -msgid "" -"Compare *a* and *b* (lists of strings); return a delta (a :term:`generator` " -"generating the delta lines) in unified diff format." -msgstr "" - -#: ../../library/difflib.rst:286 -msgid "" -"Unified diffs are a compact way of showing just the lines that have changed " -"plus a few lines of context. The changes are shown in an inline style " -"(instead of separate before/after blocks). The number of context lines is " -"set by *n* which defaults to three." -msgstr "" - -#: ../../library/difflib.rst:291 -msgid "" -"By default, the diff control lines (those with ``---``, ``+++``, or ``@@``) " -"are created with a trailing newline. This is helpful so that inputs created " -"from :func:`io.IOBase.readlines` result in diffs that are suitable for use " -"with :func:`io.IOBase.writelines` since both the inputs and outputs have " -"trailing newlines." -msgstr "" - -#: ../../library/difflib.rst:300 -msgid "" -"The unified diff format normally has a header for filenames and modification " -"times. Any or all of these may be specified using strings for *fromfile*, " -"*tofile*, *fromfiledate*, and *tofiledate*. The modification times are " -"normally expressed in the ISO 8601 format. If not specified, the strings " -"default to blanks." -msgstr "" - -#: ../../library/difflib.rst:324 -msgid "" -"Compare *a* and *b* (lists of bytes objects) using *dfunc*; yield a sequence " -"of delta lines (also bytes) in the format returned by *dfunc*. *dfunc* must " -"be a callable, typically either :func:`unified_diff` or :func:`context_diff`." -msgstr "" - -#: ../../library/difflib.rst:329 -msgid "" -"Allows you to compare data with unknown or inconsistent encoding. All inputs " -"except *n* must be bytes objects, not str. Works by losslessly converting " -"all inputs (except *n*) to str, and calling ``dfunc(a, b, fromfile, tofile, " -"fromfiledate, tofiledate, n, lineterm)``. The output of *dfunc* is then " -"converted back to bytes, so the delta lines that you receive have the same " -"unknown/inconsistent encodings as *a* and *b*." -msgstr "" - -#: ../../library/difflib.rst:340 -msgid "" -"Return ``True`` for ignorable lines. The line *line* is ignorable if *line* " -"is blank or contains a single ``'#'``, otherwise it is not ignorable. Used " -"as a default for parameter *linejunk* in :func:`ndiff` in older versions." -msgstr "" - -#: ../../library/difflib.rst:347 -msgid "" -"Return ``True`` for ignorable characters. The character *ch* is ignorable " -"if *ch* is a space or tab, otherwise it is not ignorable. Used as a default " -"for parameter *charjunk* in :func:`ndiff`." -msgstr "" - -#: ../../library/difflib.rst:354 -msgid "" -"`Pattern Matching: The Gestalt Approach `_" -msgstr "" - -#: ../../library/difflib.rst:355 -msgid "" -"Discussion of a similar algorithm by John W. Ratcliff and D. E. Metzener. " -"This was published in Dr. Dobb's Journal in July, 1988." -msgstr "" - -#: ../../library/difflib.rst:362 -msgid "SequenceMatcher Objects" -msgstr "SequenceMatcher 物件" - -#: ../../library/difflib.rst:364 -msgid "The :class:`SequenceMatcher` class has this constructor:" -msgstr "" - -#: ../../library/difflib.rst:369 -msgid "" -"Optional argument *isjunk* must be ``None`` (the default) or a one-argument " -"function that takes a sequence element and returns true if and only if the " -"element is \"junk\" and should be ignored. Passing ``None`` for *isjunk* is " -"equivalent to passing ``lambda x: False``; in other words, no elements are " -"ignored. For example, pass::" -msgstr "" - -#: ../../library/difflib.rst:375 -msgid "lambda x: x in \" \\t\"" -msgstr "lambda x: x in \" \\t\"" - -#: ../../library/difflib.rst:377 -msgid "" -"if you're comparing lines as sequences of characters, and don't want to " -"synch up on blanks or hard tabs." -msgstr "" - -#: ../../library/difflib.rst:380 -msgid "" -"The optional arguments *a* and *b* are sequences to be compared; both " -"default to empty strings. The elements of both sequences must be :term:" -"`hashable`." -msgstr "" - -#: ../../library/difflib.rst:383 -msgid "" -"The optional argument *autojunk* can be used to disable the automatic junk " -"heuristic." -msgstr "" - -#: ../../library/difflib.rst:389 -msgid "" -"SequenceMatcher objects get three data attributes: *bjunk* is the set of " -"elements of *b* for which *isjunk* is ``True``; *bpopular* is the set of non-" -"junk elements considered popular by the heuristic (if it is not disabled); " -"*b2j* is a dict mapping the remaining elements of *b* to a list of positions " -"where they occur. All three are reset whenever *b* is reset with :meth:" -"`set_seqs` or :meth:`set_seq2`." -msgstr "" - -#: ../../library/difflib.rst:396 -msgid "The *bjunk* and *bpopular* attributes." -msgstr "" - -#: ../../library/difflib.rst:399 -msgid ":class:`SequenceMatcher` objects have the following methods:" -msgstr ":class:`SequenceMatcher` 物件有以下方法：" - -#: ../../library/difflib.rst:403 -msgid "Set the two sequences to be compared." -msgstr "" - -#: ../../library/difflib.rst:405 -msgid "" -":class:`SequenceMatcher` computes and caches detailed information about the " -"second sequence, so if you want to compare one sequence against many " -"sequences, use :meth:`set_seq2` to set the commonly used sequence once and " -"call :meth:`set_seq1` repeatedly, once for each of the other sequences." -msgstr "" - -#: ../../library/difflib.rst:413 -msgid "" -"Set the first sequence to be compared. The second sequence to be compared " -"is not changed." -msgstr "" - -#: ../../library/difflib.rst:419 -msgid "" -"Set the second sequence to be compared. The first sequence to be compared " -"is not changed." -msgstr "" - -#: ../../library/difflib.rst:425 -msgid "Find longest matching block in ``a[alo:ahi]`` and ``b[blo:bhi]``." -msgstr "" - -#: ../../library/difflib.rst:427 -msgid "" -"If *isjunk* was omitted or ``None``, :meth:`find_longest_match` returns " -"``(i, j, k)`` such that ``a[i:i+k]`` is equal to ``b[j:j+k]``, where ``alo " -"<= i <= i+k <= ahi`` and ``blo <= j <= j+k <= bhi``. For all ``(i', j', " -"k')`` meeting those conditions, the additional conditions ``k >= k'``, ``i " -"<= i'``, and if ``i == i'``, ``j <= j'`` are also met. In other words, of " -"all maximal matching blocks, return one that starts earliest in *a*, and of " -"all those maximal matching blocks that start earliest in *a*, return the one " -"that starts earliest in *b*." -msgstr "" - -#: ../../library/difflib.rst:440 -msgid "" -"If *isjunk* was provided, first the longest matching block is determined as " -"above, but with the additional restriction that no junk element appears in " -"the block. Then that block is extended as far as possible by matching " -"(only) junk elements on both sides. So the resulting block never matches on " -"junk except as identical junk happens to be adjacent to an interesting match." -msgstr "" - -#: ../../library/difflib.rst:447 -msgid "" -"Here's the same example as before, but considering blanks to be junk. That " -"prevents ``' abcd'`` from matching the ``' abcd'`` at the tail end of the " -"second sequence directly. Instead only the ``'abcd'`` can match, and " -"matches the leftmost ``'abcd'`` in the second sequence:" -msgstr "" - -#: ../../library/difflib.rst:456 -msgid "If no blocks match, this returns ``(alo, blo, 0)``." -msgstr "" - -#: ../../library/difflib.rst:458 -msgid "This method returns a :term:`named tuple` ``Match(a, b, size)``." -msgstr "" - -#: ../../library/difflib.rst:460 -msgid "Added default arguments." -msgstr "新增預設引數。" - -#: ../../library/difflib.rst:466 -msgid "" -"Return list of triples describing non-overlapping matching subsequences. " -"Each triple is of the form ``(i, j, n)``, and means that ``a[i:i+n] == b[j:" -"j+n]``. The triples are monotonically increasing in *i* and *j*." -msgstr "" - -#: ../../library/difflib.rst:471 -msgid "" -"The last triple is a dummy, and has the value ``(len(a), len(b), 0)``. It " -"is the only triple with ``n == 0``. If ``(i, j, n)`` and ``(i', j', n')`` " -"are adjacent triples in the list, and the second is not the last triple in " -"the list, then ``i+n < i'`` or ``j+n < j'``; in other words, adjacent " -"triples always describe non-adjacent equal blocks." -msgstr "" - -#: ../../library/difflib.rst:479 -msgid "" -">>> s = SequenceMatcher(None, \"abxcd\", \"abcd\")\n" -">>> s.get_matching_blocks()\n" -"[Match(a=0, b=0, size=2), Match(a=3, b=2, size=2), Match(a=5, b=4, size=0)]" -msgstr "" -">>> s = SequenceMatcher(None, \"abxcd\", \"abcd\")\n" -">>> s.get_matching_blocks()\n" -"[Match(a=0, b=0, size=2), Match(a=3, b=2, size=2), Match(a=5, b=4, size=0)]" - -#: ../../library/difflib.rst:488 -msgid "" -"Return list of 5-tuples describing how to turn *a* into *b*. Each tuple is " -"of the form ``(tag, i1, i2, j1, j2)``. The first tuple has ``i1 == j1 == " -"0``, and remaining tuples have *i1* equal to the *i2* from the preceding " -"tuple, and, likewise, *j1* equal to the previous *j2*." -msgstr "" - -#: ../../library/difflib.rst:493 -msgid "The *tag* values are strings, with these meanings:" -msgstr "" - -#: ../../library/difflib.rst:496 -msgid "Value" -msgstr "" - -#: ../../library/difflib.rst:498 -msgid "``'replace'``" -msgstr "``'replace'``" - -#: ../../library/difflib.rst:498 -msgid "``a[i1:i2]`` should be replaced by ``b[j1:j2]``." -msgstr "``a[i1:i2]`` 應該被替換為 ``b[j1:j2]``。" - -#: ../../library/difflib.rst:501 -msgid "``'delete'``" -msgstr "``'delete'``" - -#: ../../library/difflib.rst:501 -msgid "``a[i1:i2]`` should be deleted. Note that ``j1 == j2`` in this case." -msgstr "``a[i1:i2]`` 應該被刪除。請注意，在這種情況下 ``j1 == j2``。" - -#: ../../library/difflib.rst:504 -msgid "``'insert'``" -msgstr "``'insert'``" - -#: ../../library/difflib.rst:504 -msgid "" -"``b[j1:j2]`` should be inserted at ``a[i1:i1]``. Note that ``i1 == i2`` in " -"this case." -msgstr "" - -#: ../../library/difflib.rst:508 -msgid "``'equal'``" -msgstr "``'equal'``" - -#: ../../library/difflib.rst:508 -msgid "``a[i1:i2] == b[j1:j2]`` (the sub-sequences are equal)." -msgstr "" - -#: ../../library/difflib.rst:512 -msgid "For example::" -msgstr "舉例來說： ::" - -#: ../../library/difflib.rst:514 -msgid "" -">>> a = \"qabxcd\"\n" -">>> b = \"abycdf\"\n" -">>> s = SequenceMatcher(None, a, b)\n" -">>> for tag, i1, i2, j1, j2 in s.get_opcodes():\n" -"... print('{:7} a[{}:{}] --> b[{}:{}] {!r:>8} --> {!r}'.format(\n" -"... tag, i1, i2, j1, j2, a[i1:i2], b[j1:j2]))\n" -"delete a[0:1] --> b[0:0] 'q' --> ''\n" -"equal a[1:3] --> b[0:2] 'ab' --> 'ab'\n" -"replace a[3:4] --> b[2:3] 'x' --> 'y'\n" -"equal a[4:6] --> b[3:5] 'cd' --> 'cd'\n" -"insert a[6:6] --> b[5:6] '' --> 'f'" -msgstr "" -">>> a = \"qabxcd\"\n" -">>> b = \"abycdf\"\n" -">>> s = SequenceMatcher(None, a, b)\n" -">>> for tag, i1, i2, j1, j2 in s.get_opcodes():\n" -"... print('{:7} a[{}:{}] --> b[{}:{}] {!r:>8} --> {!r}'.format(\n" -"... tag, i1, i2, j1, j2, a[i1:i2], b[j1:j2]))\n" -"delete a[0:1] --> b[0:0] 'q' --> ''\n" -"equal a[1:3] --> b[0:2] 'ab' --> 'ab'\n" -"replace a[3:4] --> b[2:3] 'x' --> 'y'\n" -"equal a[4:6] --> b[3:5] 'cd' --> 'cd'\n" -"insert a[6:6] --> b[5:6] '' --> 'f'" - -#: ../../library/difflib.rst:529 -msgid "Return a :term:`generator` of groups with up to *n* lines of context." -msgstr "" - -#: ../../library/difflib.rst:531 -msgid "" -"Starting with the groups returned by :meth:`get_opcodes`, this method splits " -"out smaller change clusters and eliminates intervening ranges which have no " -"changes." -msgstr "" - -#: ../../library/difflib.rst:535 -msgid "The groups are returned in the same format as :meth:`get_opcodes`." -msgstr "" - -#: ../../library/difflib.rst:540 -msgid "" -"Return a measure of the sequences' similarity as a float in the range [0, 1]." -msgstr "" - -#: ../../library/difflib.rst:543 -msgid "" -"Where T is the total number of elements in both sequences, and M is the " -"number of matches, this is 2.0\\*M / T. Note that this is ``1.0`` if the " -"sequences are identical, and ``0.0`` if they have nothing in common." -msgstr "" - -#: ../../library/difflib.rst:547 -msgid "" -"This is expensive to compute if :meth:`get_matching_blocks` or :meth:" -"`get_opcodes` hasn't already been called, in which case you may want to try :" -"meth:`quick_ratio` or :meth:`real_quick_ratio` first to get an upper bound." -msgstr "" - -#: ../../library/difflib.rst:554 -msgid "" -"Caution: The result of a :meth:`ratio` call may depend on the order of the " -"arguments. For instance::" -msgstr "" - -#: ../../library/difflib.rst:557 -msgid "" -">>> SequenceMatcher(None, 'tide', 'diet').ratio()\n" -"0.25\n" -">>> SequenceMatcher(None, 'diet', 'tide').ratio()\n" -"0.5" -msgstr "" -">>> SequenceMatcher(None, 'tide', 'diet').ratio()\n" -"0.25\n" -">>> SequenceMatcher(None, 'diet', 'tide').ratio()\n" -"0.5" - -#: ../../library/difflib.rst:565 -msgid "Return an upper bound on :meth:`ratio` relatively quickly." -msgstr "" - -#: ../../library/difflib.rst:570 -msgid "Return an upper bound on :meth:`ratio` very quickly." -msgstr "" - -#: ../../library/difflib.rst:573 -msgid "" -"The three methods that return the ratio of matching to total characters can " -"give different results due to differing levels of approximation, although :" -"meth:`~SequenceMatcher.quick_ratio` and :meth:`~SequenceMatcher." -"real_quick_ratio` are always at least as large as :meth:`~SequenceMatcher." -"ratio`:" -msgstr "" - -#: ../../library/difflib.rst:590 -msgid "SequenceMatcher Examples" -msgstr "SequenceMatcher 範例" - -#: ../../library/difflib.rst:592 -msgid "This example compares two strings, considering blanks to be \"junk\":" -msgstr "" - -#: ../../library/difflib.rst:598 -msgid "" -":meth:`~SequenceMatcher.ratio` returns a float in [0, 1], measuring the " -"similarity of the sequences. As a rule of thumb, a :meth:`~SequenceMatcher." -"ratio` value over 0.6 means the sequences are close matches:" -msgstr "" - -#: ../../library/difflib.rst:605 -msgid "" -"If you're only interested in where the sequences match, :meth:" -"`~SequenceMatcher.get_matching_blocks` is handy:" -msgstr "" - -#: ../../library/difflib.rst:614 -msgid "" -"Note that the last tuple returned by :meth:`~SequenceMatcher." -"get_matching_blocks` is always a dummy, ``(len(a), len(b), 0)``, and this is " -"the only case in which the last tuple element (number of elements matched) " -"is ``0``." -msgstr "" - -#: ../../library/difflib.rst:618 -msgid "" -"If you want to know how to change the first sequence into the second, use :" -"meth:`~SequenceMatcher.get_opcodes`:" -msgstr "" - -#: ../../library/difflib.rst:629 -msgid "" -"The :func:`get_close_matches` function in this module which shows how simple " -"code building on :class:`SequenceMatcher` can be used to do useful work." -msgstr "" - -#: ../../library/difflib.rst:633 -msgid "" -"`Simple version control recipe `_ for a small application built with :class:" -"`SequenceMatcher`." -msgstr "" - -#: ../../library/difflib.rst:641 -msgid "Differ Objects" -msgstr "" - -#: ../../library/difflib.rst:643 -msgid "" -"Note that :class:`Differ`\\ -generated deltas make no claim to be " -"**minimal** diffs. To the contrary, minimal diffs are often counter-" -"intuitive, because they synch up anywhere possible, sometimes accidental " -"matches 100 pages apart. Restricting synch points to contiguous matches " -"preserves some notion of locality, at the occasional cost of producing a " -"longer diff." -msgstr "" - -#: ../../library/difflib.rst:649 -msgid "The :class:`Differ` class has this constructor:" -msgstr ":class:`Differ` 類別有這個建構函式：" - -#: ../../library/difflib.rst:655 -msgid "" -"Optional keyword parameters *linejunk* and *charjunk* are for filter " -"functions (or ``None``):" -msgstr "" - -#: ../../library/difflib.rst:658 -msgid "" -"*linejunk*: A function that accepts a single string argument, and returns " -"true if the string is junk. The default is ``None``, meaning that no line " -"is considered junk." -msgstr "" - -#: ../../library/difflib.rst:662 -msgid "" -"*charjunk*: A function that accepts a single character argument (a string of " -"length 1), and returns true if the character is junk. The default is " -"``None``, meaning that no character is considered junk." -msgstr "" - -#: ../../library/difflib.rst:666 -msgid "" -"These junk-filtering functions speed up matching to find differences and do " -"not cause any differing lines or characters to be ignored. Read the " -"description of the :meth:`~SequenceMatcher.find_longest_match` method's " -"*isjunk* parameter for an explanation." -msgstr "" - -#: ../../library/difflib.rst:672 -msgid "" -":class:`Differ` objects are used (deltas generated) via a single method:" -msgstr "" - -#: ../../library/difflib.rst:677 -msgid "" -"Compare two sequences of lines, and generate the delta (a sequence of lines)." -msgstr "" - -#: ../../library/difflib.rst:679 -msgid "" -"Each sequence must contain individual single-line strings ending with " -"newlines. Such sequences can be obtained from the :meth:`~io.IOBase." -"readlines` method of file-like objects. The delta generated also consists " -"of newline-terminated strings, ready to be printed as-is via the :meth:`~io." -"IOBase.writelines` method of a file-like object." -msgstr "" - -#: ../../library/difflib.rst:690 -msgid "Differ Example" -msgstr "" - -#: ../../library/difflib.rst:692 -msgid "" -"This example compares two texts. First we set up the texts, sequences of " -"individual single-line strings ending with newlines (such sequences can also " -"be obtained from the :meth:`~io.IOBase.readlines` method of file-like " -"objects):" -msgstr "" - -#: ../../library/difflib.rst:711 -msgid "Next we instantiate a Differ object:" -msgstr "" - -#: ../../library/difflib.rst:715 -msgid "" -"Note that when instantiating a :class:`Differ` object we may pass functions " -"to filter out line and character \"junk.\" See the :meth:`Differ` " -"constructor for details." -msgstr "" - -#: ../../library/difflib.rst:719 -msgid "Finally, we compare the two:" -msgstr "" - -#: ../../library/difflib.rst:723 -msgid "``result`` is a list of strings, so let's pretty-print it:" -msgstr "" - -#: ../../library/difflib.rst:738 -msgid "As a single multi-line string it looks like this:" -msgstr "" - -#: ../../library/difflib.rst:757 -msgid "A command-line interface to difflib" -msgstr "difflib 的命令列介面" - -#: ../../library/difflib.rst:759 -msgid "" -"This example shows how to use difflib to create a ``diff``-like utility." -msgstr "" - -#: ../../library/difflib.rst:761 -msgid "" -"\"\"\" Command line interface to difflib.py providing diffs in four " -"formats:\n" -"\n" -"* ndiff: lists every line and highlights interline changes.\n" -"* context: highlights clusters of changes in a before/after format.\n" -"* unified: highlights clusters of changes in an inline format.\n" -"* html: generates side by side comparison with change highlights.\n" -"\n" -"\"\"\"\n" -"\n" -"import sys, os, difflib, argparse\n" -"from datetime import datetime, timezone\n" -"\n" -"def file_mtime(path):\n" -" t = datetime.fromtimestamp(os.stat(path).st_mtime,\n" -" timezone.utc)\n" -" return t.astimezone().isoformat()\n" -"\n" -"def main():\n" -"\n" -" parser = argparse.ArgumentParser()\n" -" parser.add_argument('-c', action='store_true', default=False,\n" -" help='Produce a context format diff (default)')\n" -" parser.add_argument('-u', action='store_true', default=False,\n" -" help='Produce a unified format diff')\n" -" parser.add_argument('-m', action='store_true', default=False,\n" -" help='Produce HTML side by side diff '\n" -" '(can use -c and -l in conjunction)')\n" -" parser.add_argument('-n', action='store_true', default=False,\n" -" help='Produce a ndiff format diff')\n" -" parser.add_argument('-l', '--lines', type=int, default=3,\n" -" help='Set number of context lines (default 3)')\n" -" parser.add_argument('fromfile')\n" -" parser.add_argument('tofile')\n" -" options = parser.parse_args()\n" -"\n" -" n = options.lines\n" -" fromfile = options.fromfile\n" -" tofile = options.tofile\n" -"\n" -" fromdate = file_mtime(fromfile)\n" -" todate = file_mtime(tofile)\n" -" with open(fromfile) as ff:\n" -" fromlines = ff.readlines()\n" -" with open(tofile) as tf:\n" -" tolines = tf.readlines()\n" -"\n" -" if options.u:\n" -" diff = difflib.unified_diff(fromlines, tolines, fromfile, tofile, " -"fromdate, todate, n=n)\n" -" elif options.n:\n" -" diff = difflib.ndiff(fromlines, tolines)\n" -" elif options.m:\n" -" diff = difflib.HtmlDiff().make_file(fromlines,tolines,fromfile," -"tofile,context=options.c,numlines=n)\n" -" else:\n" -" diff = difflib.context_diff(fromlines, tolines, fromfile, tofile, " -"fromdate, todate, n=n)\n" -"\n" -" sys.stdout.writelines(diff)\n" -"\n" -"if __name__ == '__main__':\n" -" main()\n" -msgstr "" -"\"\"\" Command line interface to difflib.py providing diffs in four " -"formats:\n" -"\n" -"* ndiff: lists every line and highlights interline changes.\n" -"* context: highlights clusters of changes in a before/after format.\n" -"* unified: highlights clusters of changes in an inline format.\n" -"* html: generates side by side comparison with change highlights.\n" -"\n" -"\"\"\"\n" -"\n" -"import sys, os, difflib, argparse\n" -"from datetime import datetime, timezone\n" -"\n" -"def file_mtime(path):\n" -" t = datetime.fromtimestamp(os.stat(path).st_mtime,\n" -" timezone.utc)\n" -" return t.astimezone().isoformat()\n" -"\n" -"def main():\n" -"\n" -" parser = argparse.ArgumentParser()\n" -" parser.add_argument('-c', action='store_true', default=False,\n" -" help='Produce a context format diff (default)')\n" -" parser.add_argument('-u', action='store_true', default=False,\n" -" help='Produce a unified format diff')\n" -" parser.add_argument('-m', action='store_true', default=False,\n" -" help='Produce HTML side by side diff '\n" -" '(can use -c and -l in conjunction)')\n" -" parser.add_argument('-n', action='store_true', default=False,\n" -" help='Produce a ndiff format diff')\n" -" parser.add_argument('-l', '--lines', type=int, default=3,\n" -" help='Set number of context lines (default 3)')\n" -" parser.add_argument('fromfile')\n" -" parser.add_argument('tofile')\n" -" options = parser.parse_args()\n" -"\n" -" n = options.lines\n" -" fromfile = options.fromfile\n" -" tofile = options.tofile\n" -"\n" -" fromdate = file_mtime(fromfile)\n" -" todate = file_mtime(tofile)\n" -" with open(fromfile) as ff:\n" -" fromlines = ff.readlines()\n" -" with open(tofile) as tf:\n" -" tolines = tf.readlines()\n" -"\n" -" if options.u:\n" -" diff = difflib.unified_diff(fromlines, tolines, fromfile, tofile, " -"fromdate, todate, n=n)\n" -" elif options.n:\n" -" diff = difflib.ndiff(fromlines, tolines)\n" -" elif options.m:\n" -" diff = difflib.HtmlDiff().make_file(fromlines,tolines,fromfile," -"tofile,context=options.c,numlines=n)\n" -" else:\n" -" diff = difflib.context_diff(fromlines, tolines, fromfile, tofile, " -"fromdate, todate, n=n)\n" -"\n" -" sys.stdout.writelines(diff)\n" -"\n" -"if __name__ == '__main__':\n" -" main()\n" - -#: ../../library/difflib.rst:764 -msgid "ndiff example" -msgstr "ndiff 範例： ::" - -#: ../../library/difflib.rst:766 -msgid "This example shows how to use :func:`difflib.ndiff`." -msgstr "" - -#: ../../library/difflib.rst:768 -msgid "" -"\"\"\"ndiff [-q] file1 file2\n" -" or\n" -"ndiff (-r1 | -r2) < ndiff_output > file1_or_file2\n" -"\n" -"Print a human-friendly file difference report to stdout. Both inter-\n" -"and intra-line differences are noted. In the second form, recreate file1\n" -"(-r1) or file2 (-r2) on stdout, from an ndiff report on stdin.\n" -"\n" -"In the first form, if -q (\"quiet\") is not specified, the first two lines\n" -"of output are\n" -"\n" -"-: file1\n" -"+: file2\n" -"\n" -"Each remaining line begins with a two-letter code:\n" -"\n" -" \"- \" line unique to file1\n" -" \"+ \" line unique to file2\n" -" \" \" line common to both files\n" -" \"? \" line not present in either input file\n" -"\n" -"Lines beginning with \"? \" attempt to guide the eye to intraline\n" -"differences, and were not present in either input file. These lines can be\n" -"confusing if the source files contain tab characters.\n" -"\n" -"The first file can be recovered by retaining only lines that begin with\n" -"\" \" or \"- \", and deleting those 2-character prefixes; use ndiff with -" -"r1.\n" -"\n" -"The second file can be recovered similarly, but by retaining only \" \" " -"and\n" -"\"+ \" lines; use ndiff with -r2; or, on Unix, the second file can be\n" -"recovered by piping the output through\n" -"\n" -" sed -n '/^[+ ] /s/^..//p'\n" -"\"\"\"\n" -"\n" -"__version__ = 1, 7, 0\n" -"\n" -"import difflib, sys\n" -"\n" -"def fail(msg):\n" -" out = sys.stderr.write\n" -" out(msg + \"\\n\\n\")\n" -" out(__doc__)\n" -" return 0\n" -"\n" -"# open a file & return the file object; gripe and return 0 if it\n" -"# couldn't be opened\n" -"def fopen(fname):\n" -" try:\n" -" return open(fname)\n" -" except IOError as detail:\n" -" return fail(\"couldn't open \" + fname + \": \" + str(detail))\n" -"\n" -"# open two files & spray the diff to stdout; return false iff a problem\n" -"def fcompare(f1name, f2name):\n" -" f1 = fopen(f1name)\n" -" f2 = fopen(f2name)\n" -" if not f1 or not f2:\n" -" return 0\n" -"\n" -" a = f1.readlines(); f1.close()\n" -" b = f2.readlines(); f2.close()\n" -" for line in difflib.ndiff(a, b):\n" -" print(line, end=' ')\n" -"\n" -" return 1\n" -"\n" -"# crack args (sys.argv[1:] is normal) & compare;\n" -"# return false iff a problem\n" -"\n" -"def main(args):\n" -" import getopt\n" -" try:\n" -" opts, args = getopt.getopt(args, \"qr:\")\n" -" except getopt.error as detail:\n" -" return fail(str(detail))\n" -" noisy = 1\n" -" qseen = rseen = 0\n" -" for opt, val in opts:\n" -" if opt == \"-q\":\n" -" qseen = 1\n" -" noisy = 0\n" -" elif opt == \"-r\":\n" -" rseen = 1\n" -" whichfile = val\n" -" if qseen and rseen:\n" -" return fail(\"can't specify both -q and -r\")\n" -" if rseen:\n" -" if args:\n" -" return fail(\"no args allowed with -r option\")\n" -" if whichfile in (\"1\", \"2\"):\n" -" restore(whichfile)\n" -" return 1\n" -" return fail(\"-r value must be 1 or 2\")\n" -" if len(args) != 2:\n" -" return fail(\"need 2 filename args\")\n" -" f1name, f2name = args\n" -" if noisy:\n" -" print('-:', f1name)\n" -" print('+:', f2name)\n" -" return fcompare(f1name, f2name)\n" -"\n" -"# read ndiff output from stdin, and print file1 (which=='1') or\n" -"# file2 (which=='2') to stdout\n" -"\n" -"def restore(which):\n" -" restored = difflib.restore(sys.stdin.readlines(), which)\n" -" sys.stdout.writelines(restored)\n" -"\n" -"if __name__ == '__main__':\n" -" main(sys.argv[1:])\n" -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-10-08 00:15+0000\n" +"PO-Revision-Date: 2016-11-19 00:29+0000\n" +"Last-Translator: Liang-Bo Wang \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/difflib.rst:2 +msgid ":mod:`!difflib` --- Helpers for computing deltas" +msgstr ":mod:`!difflib` --- 計算差異的輔助工具" + +#: ../../library/difflib.rst:11 +msgid "**Source code:** :source:`Lib/difflib.py`" +msgstr "**原始碼：**\\ :source:`Lib/difflib.py`" + +#: ../../library/difflib.rst:20 +msgid "" +"This module provides classes and functions for comparing sequences. It can " +"be used for example, for comparing files, and can produce information about " +"file differences in various formats, including HTML and context and unified " +"diffs. For comparing directories and files, see also, the :mod:`filecmp` " +"module." +msgstr "" + +#: ../../library/difflib.rst:29 +msgid "" +"This is a flexible class for comparing pairs of sequences of any type, so " +"long as the sequence elements are :term:`hashable`. The basic algorithm " +"predates, and is a little fancier than, an algorithm published in the late " +"1980's by Ratcliff and Obershelp under the hyperbolic name \"gestalt pattern " +"matching.\" The idea is to find the longest contiguous matching subsequence " +"that contains no \"junk\" elements; these \"junk\" elements are ones that " +"are uninteresting in some sense, such as blank lines or whitespace. " +"(Handling junk is an extension to the Ratcliff and Obershelp algorithm.) The " +"same idea is then applied recursively to the pieces of the sequences to the " +"left and to the right of the matching subsequence. This does not yield " +"minimal edit sequences, but does tend to yield matches that \"look right\" " +"to people." +msgstr "" + +#: ../../library/difflib.rst:41 +msgid "" +"**Timing:** The basic Ratcliff-Obershelp algorithm is cubic time in the " +"worst case and quadratic time in the expected case. :class:`SequenceMatcher` " +"is quadratic time for the worst case and has expected-case behavior " +"dependent in a complicated way on how many elements the sequences have in " +"common; best case time is linear." +msgstr "" + +#: ../../library/difflib.rst:47 +msgid "" +"**Automatic junk heuristic:** :class:`SequenceMatcher` supports a heuristic " +"that automatically treats certain sequence items as junk. The heuristic " +"counts how many times each individual item appears in the sequence. If an " +"item's duplicates (after the first one) account for more than 1% of the " +"sequence and the sequence is at least 200 items long, this item is marked as " +"\"popular\" and is treated as junk for the purpose of sequence matching. " +"This heuristic can be turned off by setting the ``autojunk`` argument to " +"``False`` when creating the :class:`SequenceMatcher`." +msgstr "" + +#: ../../library/difflib.rst:55 ../../library/difflib.rst:386 +msgid "Added the *autojunk* parameter." +msgstr "新增 *autojunk* 參數。" + +#: ../../library/difflib.rst:61 +msgid "" +"This is a class for comparing sequences of lines of text, and producing " +"human-readable differences or deltas. Differ uses :class:`SequenceMatcher` " +"both to compare sequences of lines, and to compare sequences of characters " +"within similar (near-matching) lines." +msgstr "" + +#: ../../library/difflib.rst:66 +msgid "Each line of a :class:`Differ` delta begins with a two-letter code:" +msgstr "" + +#: ../../library/difflib.rst:69 +msgid "Code" +msgstr "程式碼" + +#: ../../library/difflib.rst:69 ../../library/difflib.rst:496 +msgid "Meaning" +msgstr "含義" + +#: ../../library/difflib.rst:71 +msgid "``'- '``" +msgstr "``'- '``" + +#: ../../library/difflib.rst:71 +msgid "line unique to sequence 1" +msgstr "" + +#: ../../library/difflib.rst:73 +msgid "``'+ '``" +msgstr "``'+ '``" + +#: ../../library/difflib.rst:73 +msgid "line unique to sequence 2" +msgstr "" + +#: ../../library/difflib.rst:75 +msgid "``' '``" +msgstr "``' '``" + +#: ../../library/difflib.rst:75 +msgid "line common to both sequences" +msgstr "" + +#: ../../library/difflib.rst:77 +msgid "``'? '``" +msgstr "``'? '``" + +#: ../../library/difflib.rst:77 +msgid "line not present in either input sequence" +msgstr "" + +#: ../../library/difflib.rst:80 +msgid "" +"Lines beginning with '``?``' attempt to guide the eye to intraline " +"differences, and were not present in either input sequence. These lines can " +"be confusing if the sequences contain whitespace characters, such as spaces, " +"tabs or line breaks." +msgstr "" + +#: ../../library/difflib.rst:87 +msgid "" +"This class can be used to create an HTML table (or a complete HTML file " +"containing the table) showing a side by side, line by line comparison of " +"text with inter-line and intra-line change highlights. The table can be " +"generated in either full or contextual difference mode." +msgstr "" + +#: ../../library/difflib.rst:92 +msgid "The constructor for this class is:" +msgstr "" + +#: ../../library/difflib.rst:97 +msgid "Initializes instance of :class:`HtmlDiff`." +msgstr "" + +#: ../../library/difflib.rst:99 +msgid "" +"*tabsize* is an optional keyword argument to specify tab stop spacing and " +"defaults to ``8``." +msgstr "" + +#: ../../library/difflib.rst:102 +msgid "" +"*wrapcolumn* is an optional keyword to specify column number where lines are " +"broken and wrapped, defaults to ``None`` where lines are not wrapped." +msgstr "" + +#: ../../library/difflib.rst:105 +msgid "" +"*linejunk* and *charjunk* are optional keyword arguments passed into :func:" +"`ndiff` (used by :class:`HtmlDiff` to generate the side by side HTML " +"differences). See :func:`ndiff` documentation for argument default values " +"and descriptions." +msgstr "" + +#: ../../library/difflib.rst:109 +msgid "The following methods are public:" +msgstr "" + +#: ../../library/difflib.rst:114 +msgid "" +"Compares *fromlines* and *tolines* (lists of strings) and returns a string " +"which is a complete HTML file containing a table showing line by line " +"differences with inter-line and intra-line changes highlighted." +msgstr "" + +#: ../../library/difflib.rst:118 +msgid "" +"*fromdesc* and *todesc* are optional keyword arguments to specify from/to " +"file column header strings (both default to an empty string)." +msgstr "" + +#: ../../library/difflib.rst:121 +msgid "" +"*context* and *numlines* are both optional keyword arguments. Set *context* " +"to ``True`` when contextual differences are to be shown, else the default is " +"``False`` to show the full files. *numlines* defaults to ``5``. When " +"*context* is ``True`` *numlines* controls the number of context lines which " +"surround the difference highlights. When *context* is ``False`` *numlines* " +"controls the number of lines which are shown before a difference highlight " +"when using the \"next\" hyperlinks (setting to zero would cause the \"next\" " +"hyperlinks to place the next difference highlight at the top of the browser " +"without any leading context)." +msgstr "" + +#: ../../library/difflib.rst:132 +msgid "" +"*fromdesc* and *todesc* are interpreted as unescaped HTML and should be " +"properly escaped while receiving input from untrusted sources." +msgstr "" + +#: ../../library/difflib.rst:135 +msgid "" +"*charset* keyword-only argument was added. The default charset of HTML " +"document changed from ``'ISO-8859-1'`` to ``'utf-8'``." +msgstr "" + +#: ../../library/difflib.rst:141 +msgid "" +"Compares *fromlines* and *tolines* (lists of strings) and returns a string " +"which is a complete HTML table showing line by line differences with inter-" +"line and intra-line changes highlighted." +msgstr "" + +#: ../../library/difflib.rst:145 +msgid "" +"The arguments for this method are the same as those for the :meth:" +"`make_file` method." +msgstr "" + +#: ../../library/difflib.rst:152 +msgid "" +"Compare *a* and *b* (lists of strings); return a delta (a :term:`generator` " +"generating the delta lines) in context diff format." +msgstr "" + +#: ../../library/difflib.rst:155 +msgid "" +"Context diffs are a compact way of showing just the lines that have changed " +"plus a few lines of context. The changes are shown in a before/after " +"style. The number of context lines is set by *n* which defaults to three." +msgstr "" + +#: ../../library/difflib.rst:159 +msgid "" +"By default, the diff control lines (those with ``***`` or ``---``) are " +"created with a trailing newline. This is helpful so that inputs created " +"from :func:`io.IOBase.readlines` result in diffs that are suitable for use " +"with :func:`io.IOBase.writelines` since both the inputs and outputs have " +"trailing newlines." +msgstr "" + +#: ../../library/difflib.rst:165 ../../library/difflib.rst:297 +msgid "" +"For inputs that do not have trailing newlines, set the *lineterm* argument " +"to ``\"\"`` so that the output will be uniformly newline free." +msgstr "" + +#: ../../library/difflib.rst:168 +msgid "" +"The context diff format normally has a header for filenames and modification " +"times. Any or all of these may be specified using strings for *fromfile*, " +"*tofile*, *fromfiledate*, and *tofiledate*. The modification times are " +"normally expressed in the ISO 8601 format. If not specified, the strings " +"default to blanks." +msgstr "" + +#: ../../library/difflib.rst:194 ../../library/difflib.rst:320 +msgid "See :ref:`difflib-interface` for a more detailed example." +msgstr "一個更詳盡的範例請見 :ref:`difflib-interface`。" + +#: ../../library/difflib.rst:199 +msgid "" +"Return a list of the best \"good enough\" matches. *word* is a sequence for " +"which close matches are desired (typically a string), and *possibilities* is " +"a list of sequences against which to match *word* (typically a list of " +"strings)." +msgstr "" + +#: ../../library/difflib.rst:203 +msgid "" +"Optional argument *n* (default ``3``) is the maximum number of close matches " +"to return; *n* must be greater than ``0``." +msgstr "" + +#: ../../library/difflib.rst:206 +msgid "" +"Optional argument *cutoff* (default ``0.6``) is a float in the range [0, 1]. " +"Possibilities that don't score at least that similar to *word* are ignored." +msgstr "" + +#: ../../library/difflib.rst:209 +msgid "" +"The best (no more than *n*) matches among the possibilities are returned in " +"a list, sorted by similarity score, most similar first." +msgstr "" + +#: ../../library/difflib.rst:225 +msgid "" +"Compare *a* and *b* (lists of strings); return a :class:`Differ`\\ -style " +"delta (a :term:`generator` generating the delta lines)." +msgstr "" + +#: ../../library/difflib.rst:228 +msgid "" +"Optional keyword parameters *linejunk* and *charjunk* are filtering " +"functions (or ``None``):" +msgstr "" + +#: ../../library/difflib.rst:231 +msgid "" +"*linejunk*: A function that accepts a single string argument, and returns " +"true if the string is junk, or false if not. The default is ``None``. There " +"is also a module-level function :func:`IS_LINE_JUNK`, which filters out " +"lines without visible characters, except for at most one hash character " +"(``'#'``) -- however the underlying :class:`SequenceMatcher` class does a " +"dynamic analysis of which lines are so frequent as to constitute noise, and " +"this usually works better than using this function." +msgstr "" + +#: ../../library/difflib.rst:239 +msgid "" +"*charjunk*: A function that accepts a character (a string of length 1), and " +"returns if the character is junk, or false if not. The default is module-" +"level function :func:`IS_CHARACTER_JUNK`, which filters out whitespace " +"characters (a blank or tab; it's a bad idea to include newline in this!)." +msgstr "" + +#: ../../library/difflib.rst:260 +msgid "Return one of the two sequences that generated a delta." +msgstr "" + +#: ../../library/difflib.rst:262 +msgid "" +"Given a *sequence* produced by :meth:`Differ.compare` or :func:`ndiff`, " +"extract lines originating from file 1 or 2 (parameter *which*), stripping " +"off line prefixes." +msgstr "" + +#: ../../library/difflib.rst:266 +msgid "Example:" +msgstr "範例：" + +#: ../../library/difflib.rst:283 +msgid "" +"Compare *a* and *b* (lists of strings); return a delta (a :term:`generator` " +"generating the delta lines) in unified diff format." +msgstr "" + +#: ../../library/difflib.rst:286 +msgid "" +"Unified diffs are a compact way of showing just the lines that have changed " +"plus a few lines of context. The changes are shown in an inline style " +"(instead of separate before/after blocks). The number of context lines is " +"set by *n* which defaults to three." +msgstr "" + +#: ../../library/difflib.rst:291 +msgid "" +"By default, the diff control lines (those with ``---``, ``+++``, or ``@@``) " +"are created with a trailing newline. This is helpful so that inputs created " +"from :func:`io.IOBase.readlines` result in diffs that are suitable for use " +"with :func:`io.IOBase.writelines` since both the inputs and outputs have " +"trailing newlines." +msgstr "" + +#: ../../library/difflib.rst:300 +msgid "" +"The unified diff format normally has a header for filenames and modification " +"times. Any or all of these may be specified using strings for *fromfile*, " +"*tofile*, *fromfiledate*, and *tofiledate*. The modification times are " +"normally expressed in the ISO 8601 format. If not specified, the strings " +"default to blanks." +msgstr "" + +#: ../../library/difflib.rst:324 +msgid "" +"Compare *a* and *b* (lists of bytes objects) using *dfunc*; yield a sequence " +"of delta lines (also bytes) in the format returned by *dfunc*. *dfunc* must " +"be a callable, typically either :func:`unified_diff` or :func:`context_diff`." +msgstr "" + +#: ../../library/difflib.rst:329 +msgid "" +"Allows you to compare data with unknown or inconsistent encoding. All inputs " +"except *n* must be bytes objects, not str. Works by losslessly converting " +"all inputs (except *n*) to str, and calling ``dfunc(a, b, fromfile, tofile, " +"fromfiledate, tofiledate, n, lineterm)``. The output of *dfunc* is then " +"converted back to bytes, so the delta lines that you receive have the same " +"unknown/inconsistent encodings as *a* and *b*." +msgstr "" + +#: ../../library/difflib.rst:340 +msgid "" +"Return ``True`` for ignorable lines. The line *line* is ignorable if *line* " +"is blank or contains a single ``'#'``, otherwise it is not ignorable. Used " +"as a default for parameter *linejunk* in :func:`ndiff` in older versions." +msgstr "" + +#: ../../library/difflib.rst:347 +msgid "" +"Return ``True`` for ignorable characters. The character *ch* is ignorable " +"if *ch* is a space or tab, otherwise it is not ignorable. Used as a default " +"for parameter *charjunk* in :func:`ndiff`." +msgstr "" + +#: ../../library/difflib.rst:354 +msgid "" +"`Pattern Matching: The Gestalt Approach `_" +msgstr "" + +#: ../../library/difflib.rst:355 +msgid "" +"Discussion of a similar algorithm by John W. Ratcliff and D. E. Metzener. " +"This was published in Dr. Dobb's Journal in July, 1988." +msgstr "" + +#: ../../library/difflib.rst:362 +msgid "SequenceMatcher Objects" +msgstr "SequenceMatcher 物件" + +#: ../../library/difflib.rst:364 +msgid "The :class:`SequenceMatcher` class has this constructor:" +msgstr "" + +#: ../../library/difflib.rst:369 +msgid "" +"Optional argument *isjunk* must be ``None`` (the default) or a one-argument " +"function that takes a sequence element and returns true if and only if the " +"element is \"junk\" and should be ignored. Passing ``None`` for *isjunk* is " +"equivalent to passing ``lambda x: False``; in other words, no elements are " +"ignored. For example, pass::" +msgstr "" + +#: ../../library/difflib.rst:375 +msgid "lambda x: x in \" \\t\"" +msgstr "lambda x: x in \" \\t\"" + +#: ../../library/difflib.rst:377 +msgid "" +"if you're comparing lines as sequences of characters, and don't want to " +"synch up on blanks or hard tabs." +msgstr "" + +#: ../../library/difflib.rst:380 +msgid "" +"The optional arguments *a* and *b* are sequences to be compared; both " +"default to empty strings. The elements of both sequences must be :term:" +"`hashable`." +msgstr "" + +#: ../../library/difflib.rst:383 +msgid "" +"The optional argument *autojunk* can be used to disable the automatic junk " +"heuristic." +msgstr "" + +#: ../../library/difflib.rst:389 +msgid "" +"SequenceMatcher objects get three data attributes: *bjunk* is the set of " +"elements of *b* for which *isjunk* is ``True``; *bpopular* is the set of non-" +"junk elements considered popular by the heuristic (if it is not disabled); " +"*b2j* is a dict mapping the remaining elements of *b* to a list of positions " +"where they occur. All three are reset whenever *b* is reset with :meth:" +"`set_seqs` or :meth:`set_seq2`." +msgstr "" + +#: ../../library/difflib.rst:396 +msgid "The *bjunk* and *bpopular* attributes." +msgstr "" + +#: ../../library/difflib.rst:399 +msgid ":class:`SequenceMatcher` objects have the following methods:" +msgstr ":class:`SequenceMatcher` 物件有以下方法：" + +#: ../../library/difflib.rst:403 +msgid "Set the two sequences to be compared." +msgstr "" + +#: ../../library/difflib.rst:405 +msgid "" +":class:`SequenceMatcher` computes and caches detailed information about the " +"second sequence, so if you want to compare one sequence against many " +"sequences, use :meth:`set_seq2` to set the commonly used sequence once and " +"call :meth:`set_seq1` repeatedly, once for each of the other sequences." +msgstr "" + +#: ../../library/difflib.rst:413 +msgid "" +"Set the first sequence to be compared. The second sequence to be compared " +"is not changed." +msgstr "" + +#: ../../library/difflib.rst:419 +msgid "" +"Set the second sequence to be compared. The first sequence to be compared " +"is not changed." +msgstr "" + +#: ../../library/difflib.rst:425 +msgid "Find longest matching block in ``a[alo:ahi]`` and ``b[blo:bhi]``." +msgstr "" + +#: ../../library/difflib.rst:427 +msgid "" +"If *isjunk* was omitted or ``None``, :meth:`find_longest_match` returns " +"``(i, j, k)`` such that ``a[i:i+k]`` is equal to ``b[j:j+k]``, where ``alo " +"<= i <= i+k <= ahi`` and ``blo <= j <= j+k <= bhi``. For all ``(i', j', " +"k')`` meeting those conditions, the additional conditions ``k >= k'``, ``i " +"<= i'``, and if ``i == i'``, ``j <= j'`` are also met. In other words, of " +"all maximal matching blocks, return one that starts earliest in *a*, and of " +"all those maximal matching blocks that start earliest in *a*, return the one " +"that starts earliest in *b*." +msgstr "" + +#: ../../library/difflib.rst:440 +msgid "" +"If *isjunk* was provided, first the longest matching block is determined as " +"above, but with the additional restriction that no junk element appears in " +"the block. Then that block is extended as far as possible by matching " +"(only) junk elements on both sides. So the resulting block never matches on " +"junk except as identical junk happens to be adjacent to an interesting match." +msgstr "" + +#: ../../library/difflib.rst:447 +msgid "" +"Here's the same example as before, but considering blanks to be junk. That " +"prevents ``' abcd'`` from matching the ``' abcd'`` at the tail end of the " +"second sequence directly. Instead only the ``'abcd'`` can match, and " +"matches the leftmost ``'abcd'`` in the second sequence:" +msgstr "" + +#: ../../library/difflib.rst:456 +msgid "If no blocks match, this returns ``(alo, blo, 0)``." +msgstr "" + +#: ../../library/difflib.rst:458 +msgid "This method returns a :term:`named tuple` ``Match(a, b, size)``." +msgstr "" + +#: ../../library/difflib.rst:460 +msgid "Added default arguments." +msgstr "新增預設引數。" + +#: ../../library/difflib.rst:466 +msgid "" +"Return list of triples describing non-overlapping matching subsequences. " +"Each triple is of the form ``(i, j, n)``, and means that ``a[i:i+n] == b[j:" +"j+n]``. The triples are monotonically increasing in *i* and *j*." +msgstr "" + +#: ../../library/difflib.rst:471 +msgid "" +"The last triple is a dummy, and has the value ``(len(a), len(b), 0)``. It " +"is the only triple with ``n == 0``. If ``(i, j, n)`` and ``(i', j', n')`` " +"are adjacent triples in the list, and the second is not the last triple in " +"the list, then ``i+n < i'`` or ``j+n < j'``; in other words, adjacent " +"triples always describe non-adjacent equal blocks." +msgstr "" + +#: ../../library/difflib.rst:479 +msgid "" +">>> s = SequenceMatcher(None, \"abxcd\", \"abcd\")\n" +">>> s.get_matching_blocks()\n" +"[Match(a=0, b=0, size=2), Match(a=3, b=2, size=2), Match(a=5, b=4, size=0)]" +msgstr "" +">>> s = SequenceMatcher(None, \"abxcd\", \"abcd\")\n" +">>> s.get_matching_blocks()\n" +"[Match(a=0, b=0, size=2), Match(a=3, b=2, size=2), Match(a=5, b=4, size=0)]" + +#: ../../library/difflib.rst:488 +msgid "" +"Return list of 5-tuples describing how to turn *a* into *b*. Each tuple is " +"of the form ``(tag, i1, i2, j1, j2)``. The first tuple has ``i1 == j1 == " +"0``, and remaining tuples have *i1* equal to the *i2* from the preceding " +"tuple, and, likewise, *j1* equal to the previous *j2*." +msgstr "" + +#: ../../library/difflib.rst:493 +msgid "The *tag* values are strings, with these meanings:" +msgstr "" + +#: ../../library/difflib.rst:496 +msgid "Value" +msgstr "" + +#: ../../library/difflib.rst:498 +msgid "``'replace'``" +msgstr "``'replace'``" + +#: ../../library/difflib.rst:498 +msgid "``a[i1:i2]`` should be replaced by ``b[j1:j2]``." +msgstr "``a[i1:i2]`` 應該被替換為 ``b[j1:j2]``。" + +#: ../../library/difflib.rst:501 +msgid "``'delete'``" +msgstr "``'delete'``" + +#: ../../library/difflib.rst:501 +msgid "``a[i1:i2]`` should be deleted. Note that ``j1 == j2`` in this case." +msgstr "``a[i1:i2]`` 應該被刪除。請注意，在這種情況下 ``j1 == j2``。" + +#: ../../library/difflib.rst:504 +msgid "``'insert'``" +msgstr "``'insert'``" + +#: ../../library/difflib.rst:504 +msgid "" +"``b[j1:j2]`` should be inserted at ``a[i1:i1]``. Note that ``i1 == i2`` in " +"this case." +msgstr "" + +#: ../../library/difflib.rst:508 +msgid "``'equal'``" +msgstr "``'equal'``" + +#: ../../library/difflib.rst:508 +msgid "``a[i1:i2] == b[j1:j2]`` (the sub-sequences are equal)." +msgstr "" + +#: ../../library/difflib.rst:512 +msgid "For example::" +msgstr "舉例來說： ::" + +#: ../../library/difflib.rst:514 +msgid "" +">>> a = \"qabxcd\"\n" +">>> b = \"abycdf\"\n" +">>> s = SequenceMatcher(None, a, b)\n" +">>> for tag, i1, i2, j1, j2 in s.get_opcodes():\n" +"... print('{:7} a[{}:{}] --> b[{}:{}] {!r:>8} --> {!r}'.format(\n" +"... tag, i1, i2, j1, j2, a[i1:i2], b[j1:j2]))\n" +"delete a[0:1] --> b[0:0] 'q' --> ''\n" +"equal a[1:3] --> b[0:2] 'ab' --> 'ab'\n" +"replace a[3:4] --> b[2:3] 'x' --> 'y'\n" +"equal a[4:6] --> b[3:5] 'cd' --> 'cd'\n" +"insert a[6:6] --> b[5:6] '' --> 'f'" +msgstr "" +">>> a = \"qabxcd\"\n" +">>> b = \"abycdf\"\n" +">>> s = SequenceMatcher(None, a, b)\n" +">>> for tag, i1, i2, j1, j2 in s.get_opcodes():\n" +"... print('{:7} a[{}:{}] --> b[{}:{}] {!r:>8} --> {!r}'.format(\n" +"... tag, i1, i2, j1, j2, a[i1:i2], b[j1:j2]))\n" +"delete a[0:1] --> b[0:0] 'q' --> ''\n" +"equal a[1:3] --> b[0:2] 'ab' --> 'ab'\n" +"replace a[3:4] --> b[2:3] 'x' --> 'y'\n" +"equal a[4:6] --> b[3:5] 'cd' --> 'cd'\n" +"insert a[6:6] --> b[5:6] '' --> 'f'" + +#: ../../library/difflib.rst:529 +msgid "Return a :term:`generator` of groups with up to *n* lines of context." +msgstr "" + +#: ../../library/difflib.rst:531 +msgid "" +"Starting with the groups returned by :meth:`get_opcodes`, this method splits " +"out smaller change clusters and eliminates intervening ranges which have no " +"changes." +msgstr "" + +#: ../../library/difflib.rst:535 +msgid "The groups are returned in the same format as :meth:`get_opcodes`." +msgstr "" + +#: ../../library/difflib.rst:540 +msgid "" +"Return a measure of the sequences' similarity as a float in the range [0, 1]." +msgstr "" + +#: ../../library/difflib.rst:543 +msgid "" +"Where T is the total number of elements in both sequences, and M is the " +"number of matches, this is 2.0\\*M / T. Note that this is ``1.0`` if the " +"sequences are identical, and ``0.0`` if they have nothing in common." +msgstr "" + +#: ../../library/difflib.rst:547 +msgid "" +"This is expensive to compute if :meth:`get_matching_blocks` or :meth:" +"`get_opcodes` hasn't already been called, in which case you may want to try :" +"meth:`quick_ratio` or :meth:`real_quick_ratio` first to get an upper bound." +msgstr "" + +#: ../../library/difflib.rst:554 +msgid "" +"Caution: The result of a :meth:`ratio` call may depend on the order of the " +"arguments. For instance::" +msgstr "" + +#: ../../library/difflib.rst:557 +msgid "" +">>> SequenceMatcher(None, 'tide', 'diet').ratio()\n" +"0.25\n" +">>> SequenceMatcher(None, 'diet', 'tide').ratio()\n" +"0.5" +msgstr "" +">>> SequenceMatcher(None, 'tide', 'diet').ratio()\n" +"0.25\n" +">>> SequenceMatcher(None, 'diet', 'tide').ratio()\n" +"0.5" + +#: ../../library/difflib.rst:565 +msgid "Return an upper bound on :meth:`ratio` relatively quickly." +msgstr "" + +#: ../../library/difflib.rst:570 +msgid "Return an upper bound on :meth:`ratio` very quickly." +msgstr "" + +#: ../../library/difflib.rst:573 +msgid "" +"The three methods that return the ratio of matching to total characters can " +"give different results due to differing levels of approximation, although :" +"meth:`~SequenceMatcher.quick_ratio` and :meth:`~SequenceMatcher." +"real_quick_ratio` are always at least as large as :meth:`~SequenceMatcher." +"ratio`:" +msgstr "" + +#: ../../library/difflib.rst:590 +msgid "SequenceMatcher Examples" +msgstr "SequenceMatcher 範例" + +#: ../../library/difflib.rst:592 +msgid "This example compares two strings, considering blanks to be \"junk\":" +msgstr "" + +#: ../../library/difflib.rst:598 +msgid "" +":meth:`~SequenceMatcher.ratio` returns a float in [0, 1], measuring the " +"similarity of the sequences. As a rule of thumb, a :meth:`~SequenceMatcher." +"ratio` value over 0.6 means the sequences are close matches:" +msgstr "" + +#: ../../library/difflib.rst:605 +msgid "" +"If you're only interested in where the sequences match, :meth:" +"`~SequenceMatcher.get_matching_blocks` is handy:" +msgstr "" + +#: ../../library/difflib.rst:614 +msgid "" +"Note that the last tuple returned by :meth:`~SequenceMatcher." +"get_matching_blocks` is always a dummy, ``(len(a), len(b), 0)``, and this is " +"the only case in which the last tuple element (number of elements matched) " +"is ``0``." +msgstr "" + +#: ../../library/difflib.rst:618 +msgid "" +"If you want to know how to change the first sequence into the second, use :" +"meth:`~SequenceMatcher.get_opcodes`:" +msgstr "" + +#: ../../library/difflib.rst:629 +msgid "" +"The :func:`get_close_matches` function in this module which shows how simple " +"code building on :class:`SequenceMatcher` can be used to do useful work." +msgstr "" + +#: ../../library/difflib.rst:633 +msgid "" +"`Simple version control recipe `_ for a small application built with :class:" +"`SequenceMatcher`." +msgstr "" + +#: ../../library/difflib.rst:641 +msgid "Differ Objects" +msgstr "" + +#: ../../library/difflib.rst:643 +msgid "" +"Note that :class:`Differ`\\ -generated deltas make no claim to be " +"**minimal** diffs. To the contrary, minimal diffs are often counter-" +"intuitive, because they synch up anywhere possible, sometimes accidental " +"matches 100 pages apart. Restricting synch points to contiguous matches " +"preserves some notion of locality, at the occasional cost of producing a " +"longer diff." +msgstr "" + +#: ../../library/difflib.rst:649 +msgid "The :class:`Differ` class has this constructor:" +msgstr ":class:`Differ` 類別有這個建構函式：" + +#: ../../library/difflib.rst:655 +msgid "" +"Optional keyword parameters *linejunk* and *charjunk* are for filter " +"functions (or ``None``):" +msgstr "" + +#: ../../library/difflib.rst:658 +msgid "" +"*linejunk*: A function that accepts a single string argument, and returns " +"true if the string is junk. The default is ``None``, meaning that no line " +"is considered junk." +msgstr "" + +#: ../../library/difflib.rst:662 +msgid "" +"*charjunk*: A function that accepts a single character argument (a string of " +"length 1), and returns true if the character is junk. The default is " +"``None``, meaning that no character is considered junk." +msgstr "" + +#: ../../library/difflib.rst:666 +msgid "" +"These junk-filtering functions speed up matching to find differences and do " +"not cause any differing lines or characters to be ignored. Read the " +"description of the :meth:`~SequenceMatcher.find_longest_match` method's " +"*isjunk* parameter for an explanation." +msgstr "" + +#: ../../library/difflib.rst:672 +msgid "" +":class:`Differ` objects are used (deltas generated) via a single method:" +msgstr "" + +#: ../../library/difflib.rst:677 +msgid "" +"Compare two sequences of lines, and generate the delta (a sequence of lines)." +msgstr "" + +#: ../../library/difflib.rst:679 +msgid "" +"Each sequence must contain individual single-line strings ending with " +"newlines. Such sequences can be obtained from the :meth:`~io.IOBase." +"readlines` method of file-like objects. The delta generated also consists " +"of newline-terminated strings, ready to be printed as-is via the :meth:`~io." +"IOBase.writelines` method of a file-like object." +msgstr "" + +#: ../../library/difflib.rst:690 +msgid "Differ Example" +msgstr "" + +#: ../../library/difflib.rst:692 +msgid "" +"This example compares two texts. First we set up the texts, sequences of " +"individual single-line strings ending with newlines (such sequences can also " +"be obtained from the :meth:`~io.IOBase.readlines` method of file-like " +"objects):" +msgstr "" + +#: ../../library/difflib.rst:711 +msgid "Next we instantiate a Differ object:" +msgstr "" + +#: ../../library/difflib.rst:715 +msgid "" +"Note that when instantiating a :class:`Differ` object we may pass functions " +"to filter out line and character \"junk.\" See the :meth:`Differ` " +"constructor for details." +msgstr "" + +#: ../../library/difflib.rst:719 +msgid "Finally, we compare the two:" +msgstr "" + +#: ../../library/difflib.rst:723 +msgid "``result`` is a list of strings, so let's pretty-print it:" +msgstr "" + +#: ../../library/difflib.rst:738 +msgid "As a single multi-line string it looks like this:" +msgstr "" + +#: ../../library/difflib.rst:757 +msgid "A command-line interface to difflib" +msgstr "difflib 的命令列介面" + +#: ../../library/difflib.rst:759 +msgid "" +"This example shows how to use difflib to create a ``diff``-like utility." +msgstr "" + +#: ../../library/difflib.rst:761 +msgid "" +"\"\"\" Command line interface to difflib.py providing diffs in four " +"formats:\n" +"\n" +"* ndiff: lists every line and highlights interline changes.\n" +"* context: highlights clusters of changes in a before/after format.\n" +"* unified: highlights clusters of changes in an inline format.\n" +"* html: generates side by side comparison with change highlights.\n" +"\n" +"\"\"\"\n" +"\n" +"import sys, os, difflib, argparse\n" +"from datetime import datetime, timezone\n" +"\n" +"def file_mtime(path):\n" +" t = datetime.fromtimestamp(os.stat(path).st_mtime,\n" +" timezone.utc)\n" +" return t.astimezone().isoformat()\n" +"\n" +"def main():\n" +"\n" +" parser = argparse.ArgumentParser()\n" +" parser.add_argument('-c', action='store_true', default=False,\n" +" help='Produce a context format diff (default)')\n" +" parser.add_argument('-u', action='store_true', default=False,\n" +" help='Produce a unified format diff')\n" +" parser.add_argument('-m', action='store_true', default=False,\n" +" help='Produce HTML side by side diff '\n" +" '(can use -c and -l in conjunction)')\n" +" parser.add_argument('-n', action='store_true', default=False,\n" +" help='Produce a ndiff format diff')\n" +" parser.add_argument('-l', '--lines', type=int, default=3,\n" +" help='Set number of context lines (default 3)')\n" +" parser.add_argument('fromfile')\n" +" parser.add_argument('tofile')\n" +" options = parser.parse_args()\n" +"\n" +" n = options.lines\n" +" fromfile = options.fromfile\n" +" tofile = options.tofile\n" +"\n" +" fromdate = file_mtime(fromfile)\n" +" todate = file_mtime(tofile)\n" +" with open(fromfile) as ff:\n" +" fromlines = ff.readlines()\n" +" with open(tofile) as tf:\n" +" tolines = tf.readlines()\n" +"\n" +" if options.u:\n" +" diff = difflib.unified_diff(fromlines, tolines, fromfile, tofile, " +"fromdate, todate, n=n)\n" +" elif options.n:\n" +" diff = difflib.ndiff(fromlines, tolines)\n" +" elif options.m:\n" +" diff = difflib.HtmlDiff().make_file(fromlines,tolines,fromfile," +"tofile,context=options.c,numlines=n)\n" +" else:\n" +" diff = difflib.context_diff(fromlines, tolines, fromfile, tofile, " +"fromdate, todate, n=n)\n" +"\n" +" sys.stdout.writelines(diff)\n" +"\n" +"if __name__ == '__main__':\n" +" main()\n" +msgstr "" +"\"\"\" Command line interface to difflib.py providing diffs in four " +"formats:\n" +"\n" +"* ndiff: lists every line and highlights interline changes.\n" +"* context: highlights clusters of changes in a before/after format.\n" +"* unified: highlights clusters of changes in an inline format.\n" +"* html: generates side by side comparison with change highlights.\n" +"\n" +"\"\"\"\n" +"\n" +"import sys, os, difflib, argparse\n" +"from datetime import datetime, timezone\n" +"\n" +"def file_mtime(path):\n" +" t = datetime.fromtimestamp(os.stat(path).st_mtime,\n" +" timezone.utc)\n" +" return t.astimezone().isoformat()\n" +"\n" +"def main():\n" +"\n" +" parser = argparse.ArgumentParser()\n" +" parser.add_argument('-c', action='store_true', default=False,\n" +" help='Produce a context format diff (default)')\n" +" parser.add_argument('-u', action='store_true', default=False,\n" +" help='Produce a unified format diff')\n" +" parser.add_argument('-m', action='store_true', default=False,\n" +" help='Produce HTML side by side diff '\n" +" '(can use -c and -l in conjunction)')\n" +" parser.add_argument('-n', action='store_true', default=False,\n" +" help='Produce a ndiff format diff')\n" +" parser.add_argument('-l', '--lines', type=int, default=3,\n" +" help='Set number of context lines (default 3)')\n" +" parser.add_argument('fromfile')\n" +" parser.add_argument('tofile')\n" +" options = parser.parse_args()\n" +"\n" +" n = options.lines\n" +" fromfile = options.fromfile\n" +" tofile = options.tofile\n" +"\n" +" fromdate = file_mtime(fromfile)\n" +" todate = file_mtime(tofile)\n" +" with open(fromfile) as ff:\n" +" fromlines = ff.readlines()\n" +" with open(tofile) as tf:\n" +" tolines = tf.readlines()\n" +"\n" +" if options.u:\n" +" diff = difflib.unified_diff(fromlines, tolines, fromfile, tofile, " +"fromdate, todate, n=n)\n" +" elif options.n:\n" +" diff = difflib.ndiff(fromlines, tolines)\n" +" elif options.m:\n" +" diff = difflib.HtmlDiff().make_file(fromlines,tolines,fromfile," +"tofile,context=options.c,numlines=n)\n" +" else:\n" +" diff = difflib.context_diff(fromlines, tolines, fromfile, tofile, " +"fromdate, todate, n=n)\n" +"\n" +" sys.stdout.writelines(diff)\n" +"\n" +"if __name__ == '__main__':\n" +" main()\n" + +#: ../../library/difflib.rst:764 +msgid "ndiff example" +msgstr "ndiff 範例： ::" + +#: ../../library/difflib.rst:766 +msgid "This example shows how to use :func:`difflib.ndiff`." +msgstr "" + +#: ../../library/difflib.rst:768 +msgid "" +"\"\"\"ndiff [-q] file1 file2\n" +" or\n" +"ndiff (-r1 | -r2) < ndiff_output > file1_or_file2\n" +"\n" +"Print a human-friendly file difference report to stdout. Both inter-\n" +"and intra-line differences are noted. In the second form, recreate file1\n" +"(-r1) or file2 (-r2) on stdout, from an ndiff report on stdin.\n" +"\n" +"In the first form, if -q (\"quiet\") is not specified, the first two lines\n" +"of output are\n" +"\n" +"-: file1\n" +"+: file2\n" +"\n" +"Each remaining line begins with a two-letter code:\n" +"\n" +" \"- \" line unique to file1\n" +" \"+ \" line unique to file2\n" +" \" \" line common to both files\n" +" \"? \" line not present in either input file\n" +"\n" +"Lines beginning with \"? \" attempt to guide the eye to intraline\n" +"differences, and were not present in either input file. These lines can be\n" +"confusing if the source files contain tab characters.\n" +"\n" +"The first file can be recovered by retaining only lines that begin with\n" +"\" \" or \"- \", and deleting those 2-character prefixes; use ndiff with -" +"r1.\n" +"\n" +"The second file can be recovered similarly, but by retaining only \" \" " +"and\n" +"\"+ \" lines; use ndiff with -r2; or, on Unix, the second file can be\n" +"recovered by piping the output through\n" +"\n" +" sed -n '/^[+ ] /s/^..//p'\n" +"\"\"\"\n" +"\n" +"__version__ = 1, 7, 0\n" +"\n" +"import difflib, sys\n" +"\n" +"def fail(msg):\n" +" out = sys.stderr.write\n" +" out(msg + \"\\n\\n\")\n" +" out(__doc__)\n" +" return 0\n" +"\n" +"# open a file & return the file object; gripe and return 0 if it\n" +"# couldn't be opened\n" +"def fopen(fname):\n" +" try:\n" +" return open(fname)\n" +" except IOError as detail:\n" +" return fail(\"couldn't open \" + fname + \": \" + str(detail))\n" +"\n" +"# open two files & spray the diff to stdout; return false iff a problem\n" +"def fcompare(f1name, f2name):\n" +" f1 = fopen(f1name)\n" +" f2 = fopen(f2name)\n" +" if not f1 or not f2:\n" +" return 0\n" +"\n" +" a = f1.readlines(); f1.close()\n" +" b = f2.readlines(); f2.close()\n" +" for line in difflib.ndiff(a, b):\n" +" print(line, end=' ')\n" +"\n" +" return 1\n" +"\n" +"# crack args (sys.argv[1:] is normal) & compare;\n" +"# return false iff a problem\n" +"\n" +"def main(args):\n" +" import getopt\n" +" try:\n" +" opts, args = getopt.getopt(args, \"qr:\")\n" +" except getopt.error as detail:\n" +" return fail(str(detail))\n" +" noisy = 1\n" +" qseen = rseen = 0\n" +" for opt, val in opts:\n" +" if opt == \"-q\":\n" +" qseen = 1\n" +" noisy = 0\n" +" elif opt == \"-r\":\n" +" rseen = 1\n" +" whichfile = val\n" +" if qseen and rseen:\n" +" return fail(\"can't specify both -q and -r\")\n" +" if rseen:\n" +" if args:\n" +" return fail(\"no args allowed with -r option\")\n" +" if whichfile in (\"1\", \"2\"):\n" +" restore(whichfile)\n" +" return 1\n" +" return fail(\"-r value must be 1 or 2\")\n" +" if len(args) != 2:\n" +" return fail(\"need 2 filename args\")\n" +" f1name, f2name = args\n" +" if noisy:\n" +" print('-:', f1name)\n" +" print('+:', f2name)\n" +" return fcompare(f1name, f2name)\n" +"\n" +"# read ndiff output from stdin, and print file1 (which=='1') or\n" +"# file2 (which=='2') to stdout\n" +"\n" +"def restore(which):\n" +" restored = difflib.restore(sys.stdin.readlines(), which)\n" +" sys.stdout.writelines(restored)\n" +"\n" +"if __name__ == '__main__':\n" +" main(sys.argv[1:])\n" +msgstr "" diff --git a/library/dis.po b/library/dis.po index 86f01b1f75..1e2e99ae96 100644 --- a/library/dis.po +++ b/library/dis.po @@ -1,2432 +1,2432 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# splasky Chang , 2017 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2026-01-08 00:16+0000\n" -"PO-Revision-Date: 2018-07-27 16:55+0800\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" -"X-Generator: Poedit 2.1.1\n" - -#: ../../library/dis.rst:2 -msgid ":mod:`!dis` --- Disassembler for Python bytecode" -msgstr ":mod:`!dis` --- Python bytecode 的反組譯器" - -#: ../../library/dis.rst:7 -msgid "**Source code:** :source:`Lib/dis.py`" -msgstr "**原始碼：**\\ :source:`Lib/dis.py`" - -#: ../../library/dis.rst:17 -msgid "" -"The :mod:`dis` module supports the analysis of CPython :term:`bytecode` by " -"disassembling it. The CPython bytecode which this module takes as an input " -"is defined in the file :file:`Include/opcode.h` and used by the compiler and " -"the interpreter." -msgstr "" -":mod:`dis` 模組支援反組譯分析 CPython :term:`bytecode`。CPython bytecode 作為" -"輸入的模組被定義於 :file:`Include/opcode.h` 並且被編譯器和直譯器所使用。" - -#: ../../library/dis.rst:24 -msgid "" -"Bytecode is an implementation detail of the CPython interpreter. No " -"guarantees are made that bytecode will not be added, removed, or changed " -"between versions of Python. Use of this module should not be considered to " -"work across Python VMs or Python releases." -msgstr "" - -#: ../../library/dis.rst:29 -msgid "" -"Use 2 bytes for each instruction. Previously the number of bytes varied by " -"instruction." -msgstr "" - -#: ../../library/dis.rst:33 -msgid "" -"The argument of jump, exception handling and loop instructions is now the " -"instruction offset rather than the byte offset." -msgstr "" - -#: ../../library/dis.rst:37 -msgid "" -"Some instructions are accompanied by one or more inline cache entries, which " -"take the form of :opcode:`CACHE` instructions. These instructions are hidden " -"by default, but can be shown by passing ``show_caches=True`` to any :mod:" -"`dis` utility. Furthermore, the interpreter now adapts the bytecode to " -"specialize it for different runtime conditions. The adaptive bytecode can be " -"shown by passing ``adaptive=True``." -msgstr "" - -#: ../../library/dis.rst:45 -msgid "" -"The argument of a jump is the offset of the target instruction relative to " -"the instruction that appears immediately after the jump instruction's :" -"opcode:`CACHE` entries." -msgstr "" - -#: ../../library/dis.rst:50 -msgid "" -"As a consequence, the presence of the :opcode:`CACHE` instructions is " -"transparent for forward jumps but needs to be taken into account when " -"reasoning about backward jumps." -msgstr "" - -#: ../../library/dis.rst:54 -msgid "" -"The output shows logical labels rather than instruction offsets for jump " -"targets and exception handlers. The ``-O`` command line option and the " -"``show_offsets`` argument were added." -msgstr "" - -#: ../../library/dis.rst:59 -msgid "" -"The :option:`-P ` command-line option and the " -"``show_positions`` argument were added." -msgstr "" - -#: ../../library/dis.rst:63 -msgid "The :option:`-S ` command-line option is added." -msgstr "" - -#: ../../library/dis.rst:65 -msgid "Example: Given the function :func:`!myfunc`::" -msgstr "" - -#: ../../library/dis.rst:67 -msgid "" -"def myfunc(alist):\n" -" return len(alist)" -msgstr "" -"def myfunc(alist):\n" -" return len(alist)" - -#: ../../library/dis.rst:70 -msgid "" -"the following command can be used to display the disassembly of :func:`!" -"myfunc`:" -msgstr "可以使用以下指令來顯示 :func:`!myfunc` 的反組譯：" - -#: ../../library/dis.rst:73 -msgid "" -">>> dis.dis(myfunc)\n" -" 2 RESUME 0\n" -"\n" -" 3 LOAD_GLOBAL 1 (len + NULL)\n" -" LOAD_FAST_BORROW 0 (alist)\n" -" CALL 1\n" -" RETURN_VALUE" -msgstr "" -">>> dis.dis(myfunc)\n" -" 2 RESUME 0\n" -"\n" -" 3 LOAD_GLOBAL 1 (len + NULL)\n" -" LOAD_FAST_BORROW 0 (alist)\n" -" CALL 1\n" -" RETURN_VALUE" - -#: ../../library/dis.rst:83 -msgid "(The \"2\" is a line number)." -msgstr "" - -#: ../../library/dis.rst:88 -msgid "Command-line interface" -msgstr "命令列介面" - -#: ../../library/dis.rst:90 -msgid "The :mod:`dis` module can be invoked as a script from the command line:" -msgstr "" - -#: ../../library/dis.rst:92 -msgid "python -m dis [-h] [-C] [-O] [-P] [-S] [infile]" -msgstr "python -m dis [-h] [-C] [-O] [-P] [-S] [infile]" - -#: ../../library/dis.rst:96 -msgid "The following options are accepted:" -msgstr "可接受以下選項：" - -#: ../../library/dis.rst:102 -msgid "Display usage and exit." -msgstr "" - -#: ../../library/dis.rst:106 -msgid "Show inline caches." -msgstr "" - -#: ../../library/dis.rst:112 -msgid "Show offsets of instructions." -msgstr "" - -#: ../../library/dis.rst:118 -msgid "Show positions of instructions in the source code." -msgstr "" - -#: ../../library/dis.rst:124 -msgid "Show specialized bytecode." -msgstr "" - -#: ../../library/dis.rst:128 -msgid "" -"If :file:`infile` is specified, its disassembled code will be written to " -"stdout. Otherwise, disassembly is performed on compiled source code received " -"from stdin." -msgstr "" - -#: ../../library/dis.rst:132 -msgid "Bytecode analysis" -msgstr "" - -#: ../../library/dis.rst:136 -msgid "" -"The bytecode analysis API allows pieces of Python code to be wrapped in a :" -"class:`Bytecode` object that provides easy access to details of the compiled " -"code." -msgstr "" - -#: ../../library/dis.rst:144 -msgid "" -"Analyse the bytecode corresponding to a function, generator, asynchronous " -"generator, coroutine, method, string of source code, or a code object (as " -"returned by :func:`compile`)." -msgstr "" - -#: ../../library/dis.rst:148 -msgid "" -"This is a convenience wrapper around many of the functions listed below, " -"most notably :func:`get_instructions`, as iterating over a :class:`Bytecode` " -"instance yields the bytecode operations as :class:`Instruction` instances." -msgstr "" - -#: ../../library/dis.rst:152 ../../library/dis.rst:373 -msgid "" -"If *first_line* is not ``None``, it indicates the line number that should be " -"reported for the first source line in the disassembled code. Otherwise, the " -"source line information (if any) is taken directly from the disassembled " -"code object." -msgstr "" - -#: ../../library/dis.rst:157 -msgid "" -"If *current_offset* is not ``None``, it refers to an instruction offset in " -"the disassembled code. Setting this means :meth:`.dis` will display a " -"\"current instruction\" marker against the specified opcode." -msgstr "" - -#: ../../library/dis.rst:161 -msgid "" -"If *show_caches* is ``True``, :meth:`.dis` will display inline cache entries " -"used by the interpreter to specialize the bytecode." -msgstr "" - -#: ../../library/dis.rst:164 -msgid "" -"If *adaptive* is ``True``, :meth:`.dis` will display specialized bytecode " -"that may be different from the original bytecode." -msgstr "" - -#: ../../library/dis.rst:167 -msgid "" -"If *show_offsets* is ``True``, :meth:`.dis` will include instruction offsets " -"in the output." -msgstr "" - -#: ../../library/dis.rst:170 -msgid "" -"If *show_positions* is ``True``, :meth:`.dis` will include instruction " -"source code positions in the output." -msgstr "" - -#: ../../library/dis.rst:175 -msgid "" -"Construct a :class:`Bytecode` instance from the given traceback, setting " -"*current_offset* to the instruction responsible for the exception." -msgstr "" - -#: ../../library/dis.rst:180 -msgid "The compiled code object." -msgstr "" - -#: ../../library/dis.rst:184 -msgid "The first source line of the code object (if available)" -msgstr "" - -#: ../../library/dis.rst:188 -msgid "" -"Return a formatted view of the bytecode operations (the same as printed by :" -"func:`dis.dis`, but returned as a multi-line string)." -msgstr "" - -#: ../../library/dis.rst:193 -msgid "" -"Return a formatted multi-line string with detailed information about the " -"code object, like :func:`code_info`." -msgstr "" - -#: ../../library/dis.rst:196 ../../library/dis.rst:242 -#: ../../library/dis.rst:295 -msgid "This can now handle coroutine and asynchronous generator objects." -msgstr "" - -#: ../../library/dis.rst:199 ../../library/dis.rst:298 -#: ../../library/dis.rst:320 ../../library/dis.rst:356 -#: ../../library/dis.rst:382 -msgid "Added the *show_caches* and *adaptive* parameters." -msgstr "新增 *show_caches* 與 *adaptive* 參數。" - -#: ../../library/dis.rst:202 -msgid "Added the *show_offsets* parameter" -msgstr "新增 *show_offsets* 參數。" - -#: ../../library/dis.rst:205 ../../library/dis.rst:304 -#: ../../library/dis.rst:326 ../../library/dis.rst:362 -msgid "Added the *show_positions* parameter." -msgstr "新增 *show_positions* 參數。" - -#: ../../library/dis.rst:208 -msgid "Example:" -msgstr "範例：" - -#: ../../library/dis.rst:210 -msgid "" -">>> bytecode = dis.Bytecode(myfunc)\n" -">>> for instr in bytecode:\n" -"... print(instr.opname)\n" -"...\n" -"RESUME\n" -"LOAD_GLOBAL\n" -"LOAD_FAST_BORROW\n" -"CALL\n" -"RETURN_VALUE" -msgstr "" -">>> bytecode = dis.Bytecode(myfunc)\n" -">>> for instr in bytecode:\n" -"... print(instr.opname)\n" -"...\n" -"RESUME\n" -"LOAD_GLOBAL\n" -"LOAD_FAST_BORROW\n" -"CALL\n" -"RETURN_VALUE" - -#: ../../library/dis.rst:224 -msgid "Analysis functions" -msgstr "分析函式" - -#: ../../library/dis.rst:226 -msgid "" -"The :mod:`dis` module also defines the following analysis functions that " -"convert the input directly to the desired output. They can be useful if only " -"a single operation is being performed, so the intermediate analysis object " -"isn't useful:" -msgstr "" - -#: ../../library/dis.rst:232 -msgid "" -"Return a formatted multi-line string with detailed code object information " -"for the supplied function, generator, asynchronous generator, coroutine, " -"method, source code string or code object." -msgstr "" - -#: ../../library/dis.rst:236 -msgid "" -"Note that the exact contents of code info strings are highly implementation " -"dependent and they may change arbitrarily across Python VMs or Python " -"releases." -msgstr "" - -#: ../../library/dis.rst:248 -msgid "" -"Print detailed code object information for the supplied function, method, " -"source code string or code object to *file* (or ``sys.stdout`` if *file* is " -"not specified)." -msgstr "" - -#: ../../library/dis.rst:252 -msgid "" -"This is a convenient shorthand for ``print(code_info(x), file=file)``, " -"intended for interactive exploration at the interpreter prompt." -msgstr "" - -#: ../../library/dis.rst:257 ../../library/dis.rst:289 -#: ../../library/dis.rst:317 ../../library/dis.rst:353 -msgid "Added *file* parameter." -msgstr "新增 *file* 參數。" - -#: ../../library/dis.rst:264 -msgid "" -"Disassemble the *x* object. *x* can denote either a module, a class, a " -"method, a function, a generator, an asynchronous generator, a coroutine, a " -"code object, a string of source code or a byte sequence of raw bytecode. For " -"a module, it disassembles all functions. For a class, it disassembles all " -"methods (including class and static methods). For a code object or sequence " -"of raw bytecode, it prints one line per bytecode instruction. It also " -"recursively disassembles nested code objects. These can include generator " -"expressions, nested functions, the bodies of nested classes, and the code " -"objects used for :ref:`annotation scopes `. Strings are " -"first compiled to code objects with the :func:`compile` built-in function " -"before being disassembled. If no object is provided, this function " -"disassembles the last traceback." -msgstr "" - -#: ../../library/dis.rst:277 ../../library/dis.rst:314 -#: ../../library/dis.rst:350 -msgid "" -"The disassembly is written as text to the supplied *file* argument if " -"provided and to ``sys.stdout`` otherwise." -msgstr "" - -#: ../../library/dis.rst:280 -msgid "" -"The maximal depth of recursion is limited by *depth* unless it is ``None``. " -"``depth=0`` means no recursion." -msgstr "" - -#: ../../library/dis.rst:283 -msgid "" -"If *show_caches* is ``True``, this function will display inline cache " -"entries used by the interpreter to specialize the bytecode." -msgstr "" - -#: ../../library/dis.rst:286 -msgid "" -"If *adaptive* is ``True``, this function will display specialized bytecode " -"that may be different from the original bytecode." -msgstr "" - -#: ../../library/dis.rst:292 -msgid "Implemented recursive disassembling and added *depth* parameter." -msgstr "" - -#: ../../library/dis.rst:301 ../../library/dis.rst:323 -#: ../../library/dis.rst:359 -msgid "Added the *show_offsets* parameter." -msgstr "新增 *show_offsets* 參數。" - -#: ../../library/dis.rst:310 -msgid "" -"Disassemble the top-of-stack function of a traceback, using the last " -"traceback if none was passed. The instruction causing the exception is " -"indicated." -msgstr "" - -#: ../../library/dis.rst:334 -msgid "" -"Disassemble a code object, indicating the last instruction if *lasti* was " -"provided. The output is divided in the following columns:" -msgstr "" - -#: ../../library/dis.rst:337 -msgid "" -"the source code location of the instruction. Complete location information " -"is shown if *show_positions* is true. Otherwise (the default) only the line " -"number is displayed." -msgstr "" - -#: ../../library/dis.rst:340 -msgid "the current instruction, indicated as ``-->``," -msgstr "" - -#: ../../library/dis.rst:341 -msgid "a labelled instruction, indicated with ``>>``," -msgstr "" - -#: ../../library/dis.rst:342 -msgid "the address of the instruction," -msgstr "" - -#: ../../library/dis.rst:343 -msgid "the operation code name," -msgstr "" - -#: ../../library/dis.rst:344 -msgid "operation parameters, and" -msgstr "" - -#: ../../library/dis.rst:345 -msgid "interpretation of the parameters in parentheses." -msgstr "" - -#: ../../library/dis.rst:347 -msgid "" -"The parameter interpretation recognizes local and global variable names, " -"constant values, branch targets, and compare operators." -msgstr "" - -#: ../../library/dis.rst:367 -msgid "" -"Return an iterator over the instructions in the supplied function, method, " -"source code string or code object." -msgstr "" - -#: ../../library/dis.rst:370 -msgid "" -"The iterator generates a series of :class:`Instruction` named tuples giving " -"the details of each operation in the supplied code." -msgstr "" - -#: ../../library/dis.rst:378 -msgid "The *adaptive* parameter works as it does in :func:`dis`." -msgstr "" - -#: ../../library/dis.rst:385 -msgid "" -"The *show_caches* parameter is deprecated and has no effect. The iterator " -"generates the :class:`Instruction` instances with the *cache_info* field " -"populated (regardless of the value of *show_caches*) and it no longer " -"generates separate items for the cache entries." -msgstr "" - -#: ../../library/dis.rst:393 -msgid "" -"This generator function uses the :meth:`~codeobject.co_lines` method of the :" -"ref:`code object ` *code* to find the offsets which are starts " -"of lines in the source code. They are generated as ``(offset, lineno)`` " -"pairs." -msgstr "" - -#: ../../library/dis.rst:398 -msgid "Line numbers can be decreasing. Before, they were always increasing." -msgstr "" - -#: ../../library/dis.rst:401 -msgid "" -"The :pep:`626` :meth:`~codeobject.co_lines` method is used instead of the :" -"attr:`~codeobject.co_firstlineno` and :attr:`~codeobject.co_lnotab` " -"attributes of the :ref:`code object `." -msgstr "" - -#: ../../library/dis.rst:406 -msgid "" -"Line numbers can be ``None`` for bytecode that does not map to source lines." -msgstr "" - -#: ../../library/dis.rst:412 -msgid "" -"Detect all offsets in the raw compiled bytecode string *code* which are jump " -"targets, and return a list of these offsets." -msgstr "" - -#: ../../library/dis.rst:418 -msgid "Compute the stack effect of *opcode* with argument *oparg*." -msgstr "" - -#: ../../library/dis.rst:420 -msgid "" -"If the code has a jump target and *jump* is ``True``, :func:`~stack_effect` " -"will return the stack effect of jumping. If *jump* is ``False``, it will " -"return the stack effect of not jumping. And if *jump* is ``None`` (default), " -"it will return the maximal stack effect of both cases." -msgstr "" - -#: ../../library/dis.rst:427 -msgid "Added *jump* parameter." -msgstr "新增 *jump* 參數。" - -#: ../../library/dis.rst:430 -msgid "" -"If ``oparg`` is omitted (or ``None``), the stack effect is now returned for " -"``oparg=0``. Previously this was an error for opcodes that use their arg. It " -"is also no longer an error to pass an integer ``oparg`` when the ``opcode`` " -"does not use it; the ``oparg`` in this case is ignored." -msgstr "" - -#: ../../library/dis.rst:440 -msgid "Python Bytecode Instructions" -msgstr "Python 位元組碼指令" - -#: ../../library/dis.rst:442 -msgid "" -"The :func:`get_instructions` function and :class:`Bytecode` class provide " -"details of bytecode instructions as :class:`Instruction` instances:" -msgstr "" - -#: ../../library/dis.rst:447 -msgid "Details for a bytecode operation" -msgstr "位元組碼操作的詳細資訊" - -#: ../../library/dis.rst:451 -msgid "" -"numeric code for operation, corresponding to the opcode values listed below " -"and the bytecode values in the :ref:`opcode_collections`." -msgstr "" - -#: ../../library/dis.rst:457 -msgid "human readable name for operation" -msgstr "操作的可讀名稱" - -#: ../../library/dis.rst:462 -msgid "" -"numeric code for the base operation if operation is specialized; otherwise " -"equal to :data:`opcode`" -msgstr "" - -#: ../../library/dis.rst:468 -msgid "" -"human readable name for the base operation if operation is specialized; " -"otherwise equal to :data:`opname`" -msgstr "" - -#: ../../library/dis.rst:474 -msgid "numeric argument to operation (if any), otherwise ``None``" -msgstr "" - -#: ../../library/dis.rst:478 -msgid "alias for :data:`arg`" -msgstr ":data:`arg` 的別名。" - -#: ../../library/dis.rst:482 -msgid "resolved arg value (if any), otherwise ``None``" -msgstr "" - -#: ../../library/dis.rst:487 -msgid "" -"human readable description of operation argument (if any), otherwise an " -"empty string." -msgstr "" - -#: ../../library/dis.rst:493 -msgid "start index of operation within bytecode sequence" -msgstr "" - -#: ../../library/dis.rst:498 -msgid "" -"start index of operation within bytecode sequence, including prefixed " -"``EXTENDED_ARG`` operations if present; otherwise equal to :data:`offset`" -msgstr "" - -#: ../../library/dis.rst:504 -msgid "start index of the cache entries following the operation" -msgstr "" - -#: ../../library/dis.rst:509 -msgid "end index of the cache entries following the operation" -msgstr "" - -#: ../../library/dis.rst:514 -msgid "``True`` if this opcode starts a source line, otherwise ``False``" -msgstr "" - -#: ../../library/dis.rst:519 -msgid "" -"source line number associated with this opcode (if any), otherwise ``None``" -msgstr "" - -#: ../../library/dis.rst:524 -msgid "``True`` if other code jumps to here, otherwise ``False``" -msgstr "" - -#: ../../library/dis.rst:529 -msgid "" -"bytecode index of the jump target if this is a jump operation, otherwise " -"``None``" -msgstr "" - -#: ../../library/dis.rst:535 -msgid "" -":class:`dis.Positions` object holding the start and end locations that are " -"covered by this instruction." -msgstr "" - -#: ../../library/dis.rst:540 -msgid "" -"Information about the cache entries of this instruction, as triplets of the " -"form ``(name, size, data)``, where the ``name`` and ``size`` describe the " -"cache format and data is the contents of the cache. ``cache_info`` is " -"``None`` if the instruction does not have caches." -msgstr "" - -#: ../../library/dis.rst:550 -msgid "Field ``positions`` is added." -msgstr "" - -#: ../../library/dis.rst:554 -msgid "Changed field ``starts_line``." -msgstr "" - -#: ../../library/dis.rst:556 -msgid "" -"Added fields ``start_offset``, ``cache_offset``, ``end_offset``, " -"``baseopname``, ``baseopcode``, ``jump_target``, ``oparg``, ``line_number`` " -"and ``cache_info``." -msgstr "" - -#: ../../library/dis.rst:563 -msgid "" -"In case the information is not available, some fields might be ``None``." -msgstr "" - -#: ../../library/dis.rst:573 -msgid "" -"The Python compiler currently generates the following bytecode instructions." -msgstr "" - -#: ../../library/dis.rst:576 -msgid "**General instructions**" -msgstr "**一般指令**" - -#: ../../library/dis.rst:578 -msgid "" -"In the following, We will refer to the interpreter stack as ``STACK`` and " -"describe operations on it as if it was a Python list. The top of the stack " -"corresponds to ``STACK[-1]`` in this language." -msgstr "" - -#: ../../library/dis.rst:584 -msgid "" -"Do nothing code. Used as a placeholder by the bytecode optimizer, and to " -"generate line tracing events." -msgstr "" - -#: ../../library/dis.rst:590 -msgid "" -"Do nothing code. Used by the interpreter to record :monitoring-event:" -"`BRANCH_LEFT` and :monitoring-event:`BRANCH_RIGHT` events for :mod:`sys." -"monitoring`." -msgstr "" - -#: ../../library/dis.rst:599 -msgid "Removes the iterator from the top of the stack." -msgstr "" - -#: ../../library/dis.rst:606 -msgid "Removes the top-of-stack item::" -msgstr "" - -#: ../../library/dis.rst:608 -msgid "STACK.pop()" -msgstr "STACK.pop()" - -#: ../../library/dis.rst:613 -msgid "" -"Removes the top-of-stack item. Equivalent to ``POP_TOP``. Used to clean up " -"at the end of loops, hence the name." -msgstr "" - -#: ../../library/dis.rst:622 -msgid "Implements ``del STACK[-2]``. Used to clean up when a generator exits." -msgstr "" - -#: ../../library/dis.rst:630 -msgid "" -"Push the i-th item to the top of the stack without removing it from its " -"original location::" -msgstr "" - -#: ../../library/dis.rst:633 -msgid "" -"assert i > 0\n" -"STACK.append(STACK[-i])" -msgstr "" -"assert i > 0\n" -"STACK.append(STACK[-i])" - -#: ../../library/dis.rst:641 -msgid "Swap the top of the stack with the i-th element::" -msgstr "" - -#: ../../library/dis.rst:643 -msgid "STACK[-i], STACK[-1] = STACK[-1], STACK[-i]" -msgstr "STACK[-i], STACK[-1] = STACK[-1], STACK[-i]" - -#: ../../library/dis.rst:650 -msgid "" -"Rather than being an actual instruction, this opcode is used to mark extra " -"space for the interpreter to cache useful data directly in the bytecode " -"itself. It is automatically hidden by all ``dis`` utilities, but can be " -"viewed with ``show_caches=True``." -msgstr "" - -#: ../../library/dis.rst:655 -msgid "" -"Logically, this space is part of the preceding instruction. Many opcodes " -"expect to be followed by an exact number of caches, and will instruct the " -"interpreter to skip over them at runtime." -msgstr "" - -#: ../../library/dis.rst:659 -msgid "" -"Populated caches can look like arbitrary instructions, so great care should " -"be taken when reading or modifying raw, adaptive bytecode containing " -"quickened data." -msgstr "" - -#: ../../library/dis.rst:666 -msgid "**Unary operations**" -msgstr "" - -#: ../../library/dis.rst:668 -msgid "" -"Unary operations take the top of the stack, apply the operation, and push " -"the result back on the stack." -msgstr "" - -#: ../../library/dis.rst:674 -msgid "Implements ``STACK[-1] = -STACK[-1]``." -msgstr "實作 ``STACK[-1] = -STACK[-1]``。" - -#: ../../library/dis.rst:679 -msgid "Implements ``STACK[-1] = not STACK[-1]``." -msgstr "實作 ``STACK[-1] = not STACK[-1]``。" - -#: ../../library/dis.rst:681 ../../library/dis.rst:1383 -#: ../../library/dis.rst:1399 -msgid "This instruction now requires an exact :class:`bool` operand." -msgstr "" - -#: ../../library/dis.rst:687 -msgid "Implements ``STACK[-1] = ~STACK[-1]``." -msgstr "實作 ``STACK[-1] = ~STACK[-1]``。" - -#: ../../library/dis.rst:692 -msgid "Implements ``STACK[-1] = iter(STACK[-1])``." -msgstr "實作 ``STACK[-1] = iter(STACK[-1])``。" - -#: ../../library/dis.rst:697 -msgid "" -"If ``STACK[-1]`` is a :term:`generator iterator` or :term:`coroutine` object " -"it is left as is. Otherwise, implements ``STACK[-1] = iter(STACK[-1])``." -msgstr "" - -#: ../../library/dis.rst:705 -msgid "Implements ``STACK[-1] = bool(STACK[-1])``." -msgstr "" - -#: ../../library/dis.rst:710 -msgid "**Binary and in-place operations**" -msgstr "" - -#: ../../library/dis.rst:712 -msgid "" -"Binary operations remove the top two items from the stack (``STACK[-1]`` and " -"``STACK[-2]``). They perform the operation, then put the result back on the " -"stack." -msgstr "" - -#: ../../library/dis.rst:715 -msgid "" -"In-place operations are like binary operations, but the operation is done in-" -"place when ``STACK[-2]`` supports it, and the resulting ``STACK[-1]`` may be " -"(but does not have to be) the original ``STACK[-2]``." -msgstr "" - -#: ../../library/dis.rst:722 -msgid "" -"Implements the binary and in-place operators (depending on the value of " -"*op*)::" -msgstr "" - -#: ../../library/dis.rst:725 -msgid "" -"rhs = STACK.pop()\n" -"lhs = STACK.pop()\n" -"STACK.append(lhs op rhs)" -msgstr "" -"rhs = STACK.pop()\n" -"lhs = STACK.pop()\n" -"STACK.append(lhs op rhs)" - -#: ../../library/dis.rst:730 -msgid "" -"With oparg :``NB_SUBSCR``, implements binary subscript (replaces opcode " -"``BINARY_SUBSCR``)" -msgstr "" - -#: ../../library/dis.rst:736 ../../library/dis.rst:746 -#: ../../library/dis.rst:754 ../../library/dis.rst:766 -#: ../../library/dis.rst:844 ../../library/dis.rst:854 -#: ../../library/dis.rst:864 ../../library/dis.rst:1070 -#: ../../library/dis.rst:1081 ../../library/dis.rst:1226 -#: ../../library/dis.rst:1238 ../../library/dis.rst:1250 -msgid "Implements::" -msgstr "實作了： ::" - -#: ../../library/dis.rst:738 -msgid "" -"key = STACK.pop()\n" -"container = STACK.pop()\n" -"value = STACK.pop()\n" -"container[key] = value" -msgstr "" -"key = STACK.pop()\n" -"container = STACK.pop()\n" -"value = STACK.pop()\n" -"container[key] = value" - -#: ../../library/dis.rst:748 -msgid "" -"key = STACK.pop()\n" -"container = STACK.pop()\n" -"del container[key]" -msgstr "" -"key = STACK.pop()\n" -"container = STACK.pop()\n" -"del container[key]" - -#: ../../library/dis.rst:756 -msgid "" -"end = STACK.pop()\n" -"start = STACK.pop()\n" -"container = STACK.pop()\n" -"STACK.append(container[start:end])" -msgstr "" -"end = STACK.pop()\n" -"start = STACK.pop()\n" -"container = STACK.pop()\n" -"STACK.append(container[start:end])" - -#: ../../library/dis.rst:768 -msgid "" -"end = STACK.pop()\n" -"start = STACK.pop()\n" -"container = STACK.pop()\n" -"value = STACK.pop()\n" -"container[start:end] = value" -msgstr "" -"end = STACK.pop()\n" -"start = STACK.pop()\n" -"container = STACK.pop()\n" -"value = STACK.pop()\n" -"container[start:end] = value" - -#: ../../library/dis.rst:777 -msgid "**Coroutine opcodes**" -msgstr "" - -#: ../../library/dis.rst:781 -msgid "" -"Implements ``STACK[-1] = get_awaitable(STACK[-1])``, where " -"``get_awaitable(o)`` returns ``o`` if ``o`` is a coroutine object or a " -"generator object with the :data:`~inspect.CO_ITERABLE_COROUTINE` flag, or " -"resolves ``o.__await__``." -msgstr "" - -#: ../../library/dis.rst:786 -msgid "" -"If the ``where`` operand is nonzero, it indicates where the instruction " -"occurs:" -msgstr "" - -#: ../../library/dis.rst:789 -msgid "``1``: After a call to ``__aenter__``" -msgstr "" - -#: ../../library/dis.rst:790 -msgid "``2``: After a call to ``__aexit__``" -msgstr "" - -#: ../../library/dis.rst:794 -msgid "Previously, this instruction did not have an oparg." -msgstr "先前此指令沒有 oparg。" - -#: ../../library/dis.rst:800 -msgid "Implements ``STACK[-1] = STACK[-1].__aiter__()``." -msgstr "" - -#: ../../library/dis.rst:803 -msgid "Returning awaitable objects from ``__aiter__`` is no longer supported." -msgstr "" - -#: ../../library/dis.rst:810 -msgid "" -"Implement ``STACK.append(get_awaitable(STACK[-1].__anext__()))`` to the " -"stack. See ``GET_AWAITABLE`` for details about ``get_awaitable``." -msgstr "" - -#: ../../library/dis.rst:818 -msgid "" -"Terminates an :keyword:`async for` loop. Handles an exception raised when " -"awaiting a next item. The stack contains the async iterable in ``STACK[-2]`` " -"and the raised exception in ``STACK[-1]``. Both are popped. If the exception " -"is not :exc:`StopAsyncIteration`, it is re-raised." -msgstr "" - -#: ../../library/dis.rst:825 ../../library/dis.rst:916 -#: ../../library/dis.rst:927 -msgid "" -"Exception representation on the stack now consist of one, not three, items." -msgstr "" - -#: ../../library/dis.rst:831 -msgid "" -"Handles an exception raised during a :meth:`~generator.throw` or :meth:" -"`~generator.close` call through the current frame. If ``STACK[-1]`` is an " -"instance of :exc:`StopIteration`, pop three values from the stack and push " -"its ``value`` member. Otherwise, re-raise ``STACK[-1]``." -msgstr "" - -#: ../../library/dis.rst:840 -msgid "**Miscellaneous opcodes**" -msgstr "" - -#: ../../library/dis.rst:846 -msgid "" -"item = STACK.pop()\n" -"set.add(STACK[-i], item)" -msgstr "" -"item = STACK.pop()\n" -"set.add(STACK[-i], item)" - -#: ../../library/dis.rst:849 -msgid "Used to implement set comprehensions." -msgstr "" - -#: ../../library/dis.rst:856 -msgid "" -"item = STACK.pop()\n" -"list.append(STACK[-i], item)" -msgstr "" -"item = STACK.pop()\n" -"list.append(STACK[-i], item)" - -#: ../../library/dis.rst:859 -msgid "Used to implement list comprehensions." -msgstr "" - -#: ../../library/dis.rst:866 -msgid "" -"value = STACK.pop()\n" -"key = STACK.pop()\n" -"dict.__setitem__(STACK[-i], key, value)" -msgstr "" -"value = STACK.pop()\n" -"key = STACK.pop()\n" -"dict.__setitem__(STACK[-i], key, value)" - -#: ../../library/dis.rst:870 -msgid "Used to implement dict comprehensions." -msgstr "" - -#: ../../library/dis.rst:873 -msgid "" -"Map value is ``STACK[-1]`` and map key is ``STACK[-2]``. Before, those were " -"reversed." -msgstr "" - -#: ../../library/dis.rst:877 -msgid "" -"For all of the :opcode:`SET_ADD`, :opcode:`LIST_APPEND` and :opcode:" -"`MAP_ADD` instructions, while the added value or key/value pair is popped " -"off, the container object remains on the stack so that it is available for " -"further iterations of the loop." -msgstr "" - -#: ../../library/dis.rst:885 -msgid "Returns with ``STACK[-1]`` to the caller of the function." -msgstr "" - -#: ../../library/dis.rst:890 -msgid "Yields ``STACK.pop()`` from a :term:`generator`." -msgstr "" - -#: ../../library/dis.rst:892 -msgid "oparg set to be the stack depth." -msgstr "" - -#: ../../library/dis.rst:895 -msgid "" -"oparg set to be the exception block depth, for efficient closing of " -"generators." -msgstr "" - -#: ../../library/dis.rst:898 -msgid "" -"oparg is ``1`` if this instruction is part of a yield-from or await, and " -"``0`` otherwise." -msgstr "" - -#: ../../library/dis.rst:904 -msgid "" -"Checks whether ``__annotations__`` is defined in ``locals()``, if not it is " -"set up to an empty ``dict``. This opcode is only emitted if a class or " -"module body contains :term:`variable annotations ` " -"statically." -msgstr "" - -#: ../../library/dis.rst:914 -msgid "" -"Pops a value from the stack, which is used to restore the exception state." -msgstr "" - -#: ../../library/dis.rst:921 -msgid "" -"Re-raises the exception currently on top of the stack. If oparg is non-zero, " -"pops an additional value from the stack which is used to set :attr:`~frame." -"f_lasti` of the current frame." -msgstr "" - -#: ../../library/dis.rst:932 -msgid "" -"Pops a value from the stack. Pushes the current exception to the top of the " -"stack. Pushes the value originally popped back to the stack. Used in " -"exception handlers." -msgstr "" - -#: ../../library/dis.rst:940 -msgid "" -"Performs exception matching for ``except``. Tests whether the ``STACK[-2]`` " -"is an exception matching ``STACK[-1]``. Pops ``STACK[-1]`` and pushes the " -"boolean result of the test." -msgstr "" - -#: ../../library/dis.rst:948 -msgid "" -"Performs exception matching for ``except*``. Applies ``split(STACK[-1])`` on " -"the exception group representing ``STACK[-2]``." -msgstr "" - -#: ../../library/dis.rst:951 -msgid "" -"In case of a match, pops two items from the stack and pushes the non-" -"matching subgroup (``None`` in case of full match) followed by the matching " -"subgroup. When there is no match, pops one item (the match type) and pushes " -"``None``." -msgstr "" - -#: ../../library/dis.rst:960 -msgid "" -"Calls the function in position 4 on the stack with arguments (type, val, tb) " -"representing the exception at the top of the stack. Used to implement the " -"call ``context_manager.__exit__(*exc_info())`` when an exception has " -"occurred in a :keyword:`with` statement." -msgstr "" - -#: ../../library/dis.rst:967 -msgid "" -"The ``__exit__`` function is in position 4 of the stack rather than 7. " -"Exception representation on the stack now consist of one, not three, items." -msgstr "" - -#: ../../library/dis.rst:974 -msgid "" -"Pushes a common constant onto the stack. The interpreter contains a " -"hardcoded list of constants supported by this instruction. Used by the :" -"keyword:`assert` statement to load :exc:`AssertionError`." -msgstr "" - -#: ../../library/dis.rst:983 -msgid "" -"Pushes :func:`!builtins.__build_class__` onto the stack. It is later called " -"to construct a class." -msgstr "" - -#: ../../library/dis.rst:988 -msgid "" -"Perform ``STACK.append(len(STACK[-1]))``. Used in :keyword:`match` " -"statements where comparison with structure of pattern is needed." -msgstr "" - -#: ../../library/dis.rst:996 -msgid "" -"If ``STACK[-1]`` is an instance of :class:`collections.abc.Mapping` (or, " -"more technically: if it has the :c:macro:`Py_TPFLAGS_MAPPING` flag set in " -"its :c:member:`~PyTypeObject.tp_flags`), push ``True`` onto the stack. " -"Otherwise, push ``False``." -msgstr "" - -#: ../../library/dis.rst:1006 -msgid "" -"If ``STACK[-1]`` is an instance of :class:`collections.abc.Sequence` and is " -"*not* an instance of :class:`str`/:class:`bytes`/:class:`bytearray` (or, " -"more technically: if it has the :c:macro:`Py_TPFLAGS_SEQUENCE` flag set in " -"its :c:member:`~PyTypeObject.tp_flags`), push ``True`` onto the stack. " -"Otherwise, push ``False``." -msgstr "" - -#: ../../library/dis.rst:1016 -msgid "" -"``STACK[-1]`` is a tuple of mapping keys, and ``STACK[-2]`` is the match " -"subject. If ``STACK[-2]`` contains all of the keys in ``STACK[-1]``, push a :" -"class:`tuple` containing the corresponding values. Otherwise, push ``None``." -msgstr "" - -#: ../../library/dis.rst:1022 ../../library/dis.rst:1768 -msgid "" -"Previously, this instruction also pushed a boolean value indicating success " -"(``True``) or failure (``False``)." -msgstr "" - -#: ../../library/dis.rst:1029 -msgid "" -"Implements ``name = STACK.pop()``. *namei* is the index of *name* in the " -"attribute :attr:`~codeobject.co_names` of the :ref:`code object `. The compiler tries to use :opcode:`STORE_FAST` or :opcode:" -"`STORE_GLOBAL` if possible." -msgstr "" - -#: ../../library/dis.rst:1036 -msgid "" -"Implements ``del name``, where *namei* is the index into :attr:`~codeobject." -"co_names` attribute of the :ref:`code object `." -msgstr "" - -#: ../../library/dis.rst:1042 -msgid "" -"Unpacks ``STACK[-1]`` into *count* individual values, which are put onto the " -"stack right-to-left. Require there to be exactly *count* values.::" -msgstr "" - -#: ../../library/dis.rst:1045 -msgid "" -"assert(len(STACK[-1]) == count)\n" -"STACK.extend(STACK.pop()[:-count-1:-1])" -msgstr "" -"assert(len(STACK[-1]) == count)\n" -"STACK.extend(STACK.pop()[:-count-1:-1])" - -#: ../../library/dis.rst:1051 -msgid "" -"Implements assignment with a starred target: Unpacks an iterable in " -"``STACK[-1]`` into individual values, where the total number of values can " -"be smaller than the number of items in the iterable: one of the new values " -"will be a list of all leftover items." -msgstr "" - -#: ../../library/dis.rst:1056 -msgid "The number of values before and after the list value is limited to 255." -msgstr "" - -#: ../../library/dis.rst:1058 -msgid "" -"The number of values before the list value is encoded in the argument of the " -"opcode. The number of values after the list if any is encoded using an " -"``EXTENDED_ARG``. As a consequence, the argument can be seen as a two bytes " -"values where the low byte of *counts* is the number of values before the " -"list value, the high byte of *counts* the number of values after it." -msgstr "" - -#: ../../library/dis.rst:1064 -msgid "" -"The extracted values are put onto the stack right-to-left, i.e. ``a, *b, c = " -"d`` will be stored after execution as ``STACK.extend((a, b, c))``." -msgstr "" - -#: ../../library/dis.rst:1072 -msgid "" -"obj = STACK.pop()\n" -"value = STACK.pop()\n" -"obj.name = value" -msgstr "" -"obj = STACK.pop()\n" -"value = STACK.pop()\n" -"obj.name = value" - -#: ../../library/dis.rst:1076 -msgid "" -"where *namei* is the index of name in :attr:`~codeobject.co_names` of the :" -"ref:`code object `." -msgstr "" - -#: ../../library/dis.rst:1083 -msgid "" -"obj = STACK.pop()\n" -"del obj.name" -msgstr "" -"obj = STACK.pop()\n" -"del obj.name" - -#: ../../library/dis.rst:1086 -msgid "" -"where *namei* is the index of name into :attr:`~codeobject.co_names` of the :" -"ref:`code object `." -msgstr "" - -#: ../../library/dis.rst:1092 -msgid "Works as :opcode:`STORE_NAME`, but stores the name as a global." -msgstr "" - -#: ../../library/dis.rst:1097 -msgid "Works as :opcode:`DELETE_NAME`, but deletes a global name." -msgstr "" - -#: ../../library/dis.rst:1102 -msgid "Pushes ``co_consts[consti]`` onto the stack." -msgstr "" - -#: ../../library/dis.rst:1107 -msgid "" -"Pushes the integer ``i`` onto the stack. ``i`` must be in ``range(256)``" -msgstr "" - -#: ../../library/dis.rst:1115 -msgid "" -"Pushes the value associated with ``co_names[namei]`` onto the stack. The " -"name is looked up within the locals, then the globals, then the builtins." -msgstr "" - -#: ../../library/dis.rst:1121 -msgid "" -"Pushes a reference to the locals dictionary onto the stack. This is used to " -"prepare namespace dictionaries for :opcode:`LOAD_FROM_DICT_OR_DEREF` and :" -"opcode:`LOAD_FROM_DICT_OR_GLOBALS`." -msgstr "" - -#: ../../library/dis.rst:1130 -msgid "" -"Pops a mapping off the stack and looks up the value for ``co_names[namei]``. " -"If the name is not found there, looks it up in the globals and then the " -"builtins, similar to :opcode:`LOAD_GLOBAL`. This is used for loading global " -"variables in :ref:`annotation scopes ` within class " -"bodies." -msgstr "" - -#: ../../library/dis.rst:1141 -msgid "" -"Constructs a new :class:`~string.templatelib.Template` instance from a tuple " -"of strings and a tuple of interpolations and pushes the resulting object " -"onto the stack::" -msgstr "" - -#: ../../library/dis.rst:1145 -msgid "" -"interpolations = STACK.pop()\n" -"strings = STACK.pop()\n" -"STACK.append(_build_template(strings, interpolations))" -msgstr "" -"interpolations = STACK.pop()\n" -"strings = STACK.pop()\n" -"STACK.append(_build_template(strings, interpolations))" - -#: ../../library/dis.rst:1154 -msgid "" -"Constructs a new :class:`~string.templatelib.Interpolation` instance from a " -"value and its source expression and pushes the resulting object onto the " -"stack." -msgstr "" - -#: ../../library/dis.rst:1158 -msgid "" -"If no conversion or format specification is present, ``format`` is set to " -"``2``." -msgstr "" - -#: ../../library/dis.rst:1161 -msgid "" -"If the low bit of ``format`` is set, it indicates that the interpolation " -"contains a format specification." -msgstr "" - -#: ../../library/dis.rst:1164 -msgid "" -"If ``format >> 2`` is non-zero, it indicates that the interpolation contains " -"a conversion. The value of ``format >> 2`` is the conversion type (``0`` for " -"no conversion, ``1`` for ``!s``, ``2`` for ``!r``, and ``3`` for ``!a``)::" -msgstr "" - -#: ../../library/dis.rst:1169 -msgid "" -"conversion = format >> 2\n" -"if format & 1:\n" -" format_spec = STACK.pop()\n" -"else:\n" -" format_spec = None\n" -"expression = STACK.pop()\n" -"value = STACK.pop()\n" -"STACK.append(_build_interpolation(value, expression, conversion, " -"format_spec))" -msgstr "" -"conversion = format >> 2\n" -"if format & 1:\n" -" format_spec = STACK.pop()\n" -"else:\n" -" format_spec = None\n" -"expression = STACK.pop()\n" -"value = STACK.pop()\n" -"STACK.append(_build_interpolation(value, expression, conversion, " -"format_spec))" - -#: ../../library/dis.rst:1183 -msgid "" -"Creates a tuple consuming *count* items from the stack, and pushes the " -"resulting tuple onto the stack::" -msgstr "" - -#: ../../library/dis.rst:1186 -msgid "" -"if count == 0:\n" -" value = ()\n" -"else:\n" -" value = tuple(STACK[-count:])\n" -" STACK = STACK[:-count]\n" -"\n" -"STACK.append(value)" -msgstr "" -"if count == 0:\n" -" value = ()\n" -"else:\n" -" value = tuple(STACK[-count:])\n" -" STACK = STACK[:-count]\n" -"\n" -"STACK.append(value)" - -#: ../../library/dis.rst:1197 -msgid "Works as :opcode:`BUILD_TUPLE`, but creates a list." -msgstr "" - -#: ../../library/dis.rst:1202 -msgid "Works as :opcode:`BUILD_TUPLE`, but creates a set." -msgstr "" - -#: ../../library/dis.rst:1207 -msgid "" -"Pushes a new dictionary object onto the stack. Pops ``2 * count`` items so " -"that the dictionary holds *count* entries: ``{..., STACK[-4]: STACK[-3], " -"STACK[-2]: STACK[-1]}``." -msgstr "" - -#: ../../library/dis.rst:1211 -msgid "" -"The dictionary is created from stack items instead of creating an empty " -"dictionary pre-sized to hold *count* items." -msgstr "" - -#: ../../library/dis.rst:1218 -msgid "" -"Concatenates *count* strings from the stack and pushes the resulting string " -"onto the stack." -msgstr "" - -#: ../../library/dis.rst:1228 -msgid "" -"seq = STACK.pop()\n" -"list.extend(STACK[-i], seq)" -msgstr "" -"seq = STACK.pop()\n" -"list.extend(STACK[-i], seq)" - -#: ../../library/dis.rst:1231 -msgid "Used to build lists." -msgstr "" - -#: ../../library/dis.rst:1240 -msgid "" -"seq = STACK.pop()\n" -"set.update(STACK[-i], seq)" -msgstr "" -"seq = STACK.pop()\n" -"set.update(STACK[-i], seq)" - -#: ../../library/dis.rst:1243 -msgid "Used to build sets." -msgstr "" - -#: ../../library/dis.rst:1252 -msgid "" -"map = STACK.pop()\n" -"dict.update(STACK[-i], map)" -msgstr "" -"map = STACK.pop()\n" -"dict.update(STACK[-i], map)" - -#: ../../library/dis.rst:1255 -msgid "Used to build dicts." -msgstr "" - -#: ../../library/dis.rst:1262 -msgid "Like :opcode:`DICT_UPDATE` but raises an exception for duplicate keys." -msgstr "" - -#: ../../library/dis.rst:1269 -msgid "" -"If the low bit of ``namei`` is not set, this replaces ``STACK[-1]`` with " -"``getattr(STACK[-1], co_names[namei>>1])``." -msgstr "" - -#: ../../library/dis.rst:1272 -msgid "" -"If the low bit of ``namei`` is set, this will attempt to load a method named " -"``co_names[namei>>1]`` from the ``STACK[-1]`` object. ``STACK[-1]`` is " -"popped. This bytecode distinguishes two cases: if ``STACK[-1]`` has a method " -"with the correct name, the bytecode pushes the unbound method and " -"``STACK[-1]``. ``STACK[-1]`` will be used as the first argument (``self``) " -"by :opcode:`CALL` or :opcode:`CALL_KW` when calling the unbound method. " -"Otherwise, ``NULL`` and the object returned by the attribute lookup are " -"pushed." -msgstr "" - -#: ../../library/dis.rst:1281 -msgid "" -"If the low bit of ``namei`` is set, then a ``NULL`` or ``self`` is pushed to " -"the stack before the attribute or unbound method respectively." -msgstr "" - -#: ../../library/dis.rst:1288 -msgid "" -"This opcode implements :func:`super`, both in its zero-argument and two-" -"argument forms (e.g. ``super().method()``, ``super().attr`` and ``super(cls, " -"self).method()``, ``super(cls, self).attr``)." -msgstr "" - -#: ../../library/dis.rst:1292 -msgid "It pops three values from the stack (from top of stack down):" -msgstr "" - -#: ../../library/dis.rst:1294 -msgid "``self``: the first argument to the current method" -msgstr "" - -#: ../../library/dis.rst:1295 -msgid "``cls``: the class within which the current method was defined" -msgstr "" - -#: ../../library/dis.rst:1296 -msgid "the global ``super``" -msgstr "" - -#: ../../library/dis.rst:1298 -msgid "" -"With respect to its argument, it works similarly to :opcode:`LOAD_ATTR`, " -"except that ``namei`` is shifted left by 2 bits instead of 1." -msgstr "" - -#: ../../library/dis.rst:1301 -msgid "" -"The low bit of ``namei`` signals to attempt a method load, as with :opcode:" -"`LOAD_ATTR`, which results in pushing ``NULL`` and the loaded method. When " -"it is unset a single value is pushed to the stack." -msgstr "" - -#: ../../library/dis.rst:1305 -msgid "" -"The second-low bit of ``namei``, if set, means that this was a two-argument " -"call to :func:`super` (unset means zero-argument)." -msgstr "" - -#: ../../library/dis.rst:1313 -msgid "" -"Performs a Boolean operation. The operation name can be found in " -"``cmp_op[opname >> 5]``. If the fifth-lowest bit of ``opname`` is set " -"(``opname & 16``), the result should be coerced to ``bool``." -msgstr "" - -#: ../../library/dis.rst:1317 -msgid "" -"The fifth-lowest bit of the oparg now indicates a forced conversion to :" -"class:`bool`." -msgstr "" - -#: ../../library/dis.rst:1324 -msgid "Performs ``is`` comparison, or ``is not`` if ``invert`` is 1." -msgstr "" - -#: ../../library/dis.rst:1331 -msgid "Performs ``in`` comparison, or ``not in`` if ``invert`` is 1." -msgstr "" - -#: ../../library/dis.rst:1338 -msgid "" -"Imports the module ``co_names[namei]``. ``STACK[-1]`` and ``STACK[-2]`` are " -"popped and provide the *fromlist* and *level* arguments of :func:" -"`__import__`. The module object is pushed onto the stack. The current " -"namespace is not affected: for a proper import statement, a subsequent :" -"opcode:`STORE_FAST` instruction modifies the namespace." -msgstr "" - -#: ../../library/dis.rst:1346 -msgid "" -"Loads the attribute ``co_names[namei]`` from the module found in " -"``STACK[-1]``. The resulting object is pushed onto the stack, to be " -"subsequently stored by a :opcode:`STORE_FAST` instruction." -msgstr "" - -#: ../../library/dis.rst:1353 -msgid "Increments bytecode counter by *delta*." -msgstr "" - -#: ../../library/dis.rst:1358 -msgid "Decrements bytecode counter by *delta*. Checks for interrupts." -msgstr "" - -#: ../../library/dis.rst:1365 -msgid "Decrements bytecode counter by *delta*. Does not check for interrupts." -msgstr "" - -#: ../../library/dis.rst:1372 -msgid "" -"If ``STACK[-1]`` is true, increments the bytecode counter by *delta*. " -"``STACK[-1]`` is popped." -msgstr "" - -#: ../../library/dis.rst:1375 ../../library/dis.rst:1391 -msgid "" -"The oparg is now a relative delta rather than an absolute target. This " -"opcode is a pseudo-instruction, replaced in final bytecode by the directed " -"versions (forward/backward)." -msgstr "" - -#: ../../library/dis.rst:1380 ../../library/dis.rst:1396 -#: ../../library/dis.rst:1409 ../../library/dis.rst:1420 -msgid "This is no longer a pseudo-instruction." -msgstr "" - -#: ../../library/dis.rst:1388 -msgid "" -"If ``STACK[-1]`` is false, increments the bytecode counter by *delta*. " -"``STACK[-1]`` is popped." -msgstr "" - -#: ../../library/dis.rst:1404 -msgid "" -"If ``STACK[-1]`` is not ``None``, increments the bytecode counter by " -"*delta*. ``STACK[-1]`` is popped." -msgstr "" - -#: ../../library/dis.rst:1415 -msgid "" -"If ``STACK[-1]`` is ``None``, increments the bytecode counter by *delta*. " -"``STACK[-1]`` is popped." -msgstr "" - -#: ../../library/dis.rst:1425 -msgid "" -"``STACK[-1]`` is an :term:`iterator`. Call its :meth:`~iterator.__next__` " -"method. If this yields a new value, push it on the stack (leaving the " -"iterator below it). If the iterator indicates it is exhausted then the byte " -"code counter is incremented by *delta*." -msgstr "" - -#: ../../library/dis.rst:1430 -msgid "Up until 3.11 the iterator was popped when it was exhausted." -msgstr "" - -#: ../../library/dis.rst:1435 -msgid "Loads the global named ``co_names[namei>>1]`` onto the stack." -msgstr "" - -#: ../../library/dis.rst:1437 -msgid "" -"If the low bit of ``namei`` is set, then a ``NULL`` is pushed to the stack " -"before the global variable." -msgstr "" - -#: ../../library/dis.rst:1443 -msgid "" -"Pushes a reference to the local ``co_varnames[var_num]`` onto the stack." -msgstr "" - -#: ../../library/dis.rst:1445 -msgid "" -"This opcode is now only used in situations where the local variable is " -"guaranteed to be initialized. It cannot raise :exc:`UnboundLocalError`." -msgstr "" - -#: ../../library/dis.rst:1451 -msgid "" -"Pushes a borrowed reference to the local ``co_varnames[var_num]`` onto the " -"stack." -msgstr "" - -#: ../../library/dis.rst:1458 -msgid "" -"Pushes references to ``co_varnames[var_nums >> 4]`` and " -"``co_varnames[var_nums & 15]`` onto the stack." -msgstr "" - -#: ../../library/dis.rst:1466 -msgid "" -"Pushes borrowed references to ``co_varnames[var_nums >> 4]`` and " -"``co_varnames[var_nums & 15]`` onto the stack." -msgstr "" - -#: ../../library/dis.rst:1473 -msgid "" -"Pushes a reference to the local ``co_varnames[var_num]`` onto the stack, " -"raising an :exc:`UnboundLocalError` if the local variable has not been " -"initialized." -msgstr "" - -#: ../../library/dis.rst:1481 -msgid "" -"Pushes a reference to the local ``co_varnames[var_num]`` onto the stack (or " -"pushes ``NULL`` onto the stack if the local variable has not been " -"initialized) and sets ``co_varnames[var_num]`` to ``NULL``." -msgstr "" - -#: ../../library/dis.rst:1489 -msgid "Stores ``STACK.pop()`` into the local ``co_varnames[var_num]``." -msgstr "" - -#: ../../library/dis.rst:1493 -msgid "" -"Stores ``STACK[-1]`` into ``co_varnames[var_nums >> 4]`` and ``STACK[-2]`` " -"into ``co_varnames[var_nums & 15]``." -msgstr "" - -#: ../../library/dis.rst:1500 -msgid "" -"Stores ``STACK.pop()`` into the local ``co_varnames[var_nums >> 4]`` and " -"pushes a reference to the local ``co_varnames[var_nums & 15]`` onto the " -"stack." -msgstr "" - -#: ../../library/dis.rst:1508 -msgid "Deletes local ``co_varnames[var_num]``." -msgstr "" - -#: ../../library/dis.rst:1513 -msgid "" -"Creates a new cell in slot ``i``. If that slot is nonempty then that value " -"is stored into the new cell." -msgstr "" - -#: ../../library/dis.rst:1521 -msgid "" -"Loads the cell contained in slot ``i`` of the \"fast locals\" storage. " -"Pushes a reference to the object the cell contains on the stack." -msgstr "" - -#: ../../library/dis.rst:1524 ../../library/dis.rst:1546 -#: ../../library/dis.rst:1557 -msgid "" -"``i`` is no longer offset by the length of :attr:`~codeobject.co_varnames`." -msgstr "" - -#: ../../library/dis.rst:1530 -msgid "" -"Pops a mapping off the stack and looks up the name associated with slot " -"``i`` of the \"fast locals\" storage in this mapping. If the name is not " -"found there, loads it from the cell contained in slot ``i``, similar to :" -"opcode:`LOAD_DEREF`. This is used for loading :term:`closure variables " -"` in class bodies (which previously used :opcode:`!" -"LOAD_CLASSDEREF`) and in :ref:`annotation scopes ` within " -"class bodies." -msgstr "" - -#: ../../library/dis.rst:1543 -msgid "" -"Stores ``STACK.pop()`` into the cell contained in slot ``i`` of the \"fast " -"locals\" storage." -msgstr "" - -#: ../../library/dis.rst:1552 -msgid "" -"Empties the cell contained in slot ``i`` of the \"fast locals\" storage. " -"Used by the :keyword:`del` statement." -msgstr "" - -#: ../../library/dis.rst:1563 -msgid "" -"Copies the ``n`` :term:`free (closure) variables ` from " -"the closure into the frame. Removes the need for special code on the " -"caller's side when calling closures." -msgstr "" - -#: ../../library/dis.rst:1572 -msgid "" -"Raises an exception using one of the 3 forms of the ``raise`` statement, " -"depending on the value of *argc*:" -msgstr "" - -#: ../../library/dis.rst:1575 -msgid "0: ``raise`` (re-raise previous exception)" -msgstr "" - -#: ../../library/dis.rst:1576 -msgid "" -"1: ``raise STACK[-1]`` (raise exception instance or type at ``STACK[-1]``)" -msgstr "" - -#: ../../library/dis.rst:1577 -msgid "" -"2: ``raise STACK[-2] from STACK[-1]`` (raise exception instance or type at " -"``STACK[-2]`` with ``__cause__`` set to ``STACK[-1]``)" -msgstr "" - -#: ../../library/dis.rst:1583 -msgid "" -"Calls a callable object with the number of arguments specified by ``argc``. " -"On the stack are (in ascending order):" -msgstr "" - -#: ../../library/dis.rst:1586 ../../library/dis.rst:1610 -msgid "The callable" -msgstr "" - -#: ../../library/dis.rst:1587 ../../library/dis.rst:1611 -msgid "``self`` or ``NULL``" -msgstr "``self`` 或 ``NULL``" - -#: ../../library/dis.rst:1588 ../../library/dis.rst:1612 -msgid "The remaining positional arguments" -msgstr "剩餘的位置引數" - -#: ../../library/dis.rst:1590 -msgid "``argc`` is the total of the positional arguments, excluding ``self``." -msgstr "" - -#: ../../library/dis.rst:1592 -msgid "" -"``CALL`` pops all arguments and the callable object off the stack, calls the " -"callable object with those arguments, and pushes the return value returned " -"by the callable object." -msgstr "" - -#: ../../library/dis.rst:1598 -msgid "The callable now always appears at the same position on the stack." -msgstr "" - -#: ../../library/dis.rst:1601 -msgid "Calls with keyword arguments are now handled by :opcode:`CALL_KW`." -msgstr "" - -#: ../../library/dis.rst:1607 -msgid "" -"Calls a callable object with the number of arguments specified by ``argc``, " -"including one or more named arguments. On the stack are (in ascending order):" -msgstr "" - -#: ../../library/dis.rst:1613 -msgid "The named arguments" -msgstr "" - -#: ../../library/dis.rst:1614 -msgid "A :class:`tuple` of keyword argument names" -msgstr "" - -#: ../../library/dis.rst:1616 -msgid "" -"``argc`` is the total of the positional and named arguments, excluding " -"``self``. The length of the tuple of keyword argument names is the number of " -"named arguments." -msgstr "" - -#: ../../library/dis.rst:1619 -msgid "" -"``CALL_KW`` pops all arguments, the keyword names, and the callable object " -"off the stack, calls the callable object with those arguments, and pushes " -"the return value returned by the callable object." -msgstr "" - -#: ../../library/dis.rst:1628 -msgid "" -"Calls a callable object with variable set of positional and keyword " -"arguments. If the lowest bit of *flags* is set, the top of the stack " -"contains a mapping object containing additional keyword arguments. Before " -"the callable is called, the mapping object and iterable object are each " -"\"unpacked\" and their contents passed in as keyword and positional " -"arguments respectively. ``CALL_FUNCTION_EX`` pops all arguments and the " -"callable object off the stack, calls the callable object with those " -"arguments, and pushes the return value returned by the callable object." -msgstr "" - -#: ../../library/dis.rst:1643 -msgid "" -"Pushes a ``NULL`` to the stack. Used in the call sequence to match the " -"``NULL`` pushed by :opcode:`!LOAD_METHOD` for non-method calls." -msgstr "" - -#: ../../library/dis.rst:1652 -msgid "" -"Pushes a new function object on the stack built from the code object at " -"``STACK[-1]``." -msgstr "" - -#: ../../library/dis.rst:1654 -msgid "Flag value ``0x04`` is a tuple of strings instead of dictionary" -msgstr "" - -#: ../../library/dis.rst:1657 -msgid "Qualified name at ``STACK[-1]`` was removed." -msgstr "" - -#: ../../library/dis.rst:1660 -msgid "" -"Extra function attributes on the stack, signaled by oparg flags, were " -"removed. They now use :opcode:`SET_FUNCTION_ATTRIBUTE`." -msgstr "" - -#: ../../library/dis.rst:1667 -msgid "" -"Sets an attribute on a function object. Expects the function at " -"``STACK[-1]`` and the attribute value to set at ``STACK[-2]``; consumes both " -"and leaves the function at ``STACK[-1]``. The flag determines which " -"attribute to set:" -msgstr "" - -#: ../../library/dis.rst:1671 -msgid "" -"``0x01`` a tuple of default values for positional-only and positional-or-" -"keyword parameters in positional order" -msgstr "" - -#: ../../library/dis.rst:1673 -msgid "``0x02`` a dictionary of keyword-only parameters' default values" -msgstr "" - -#: ../../library/dis.rst:1674 -msgid "``0x04`` a tuple of strings containing parameters' annotations" -msgstr "" - -#: ../../library/dis.rst:1675 -msgid "``0x08`` a tuple containing cells for free variables, making a closure" -msgstr "" - -#: ../../library/dis.rst:1676 -msgid "``0x10`` the :term:`annotate function` for the function object" -msgstr "" - -#: ../../library/dis.rst:1680 -msgid "" -"Added ``0x10`` to indicate the annotate function for the function object." -msgstr "" - -#: ../../library/dis.rst:1688 -msgid "" -"Pushes a slice object on the stack. *argc* must be 2 or 3. If it is 2, " -"implements::" -msgstr "" - -#: ../../library/dis.rst:1690 -msgid "" -"end = STACK.pop()\n" -"start = STACK.pop()\n" -"STACK.append(slice(start, end))" -msgstr "" - -#: ../../library/dis.rst:1694 -msgid "if it is 3, implements::" -msgstr "" - -#: ../../library/dis.rst:1696 -msgid "" -"step = STACK.pop()\n" -"end = STACK.pop()\n" -"start = STACK.pop()\n" -"STACK.append(slice(start, end, step))" -msgstr "" -"step = STACK.pop()\n" -"end = STACK.pop()\n" -"start = STACK.pop()\n" -"STACK.append(slice(start, end, step))" - -#: ../../library/dis.rst:1701 -msgid "See the :func:`slice` built-in function for more information." -msgstr "更多資訊請參閱內建函式 :func:`slice`。" - -#: ../../library/dis.rst:1706 -msgid "" -"Prefixes any opcode which has an argument too big to fit into the default " -"one byte. *ext* holds an additional byte which act as higher bits in the " -"argument. For each opcode, at most three prefixal ``EXTENDED_ARG`` are " -"allowed, forming an argument from two-byte to four-byte." -msgstr "" - -#: ../../library/dis.rst:1714 -msgid "Convert value to a string, depending on ``oparg``::" -msgstr "" - -#: ../../library/dis.rst:1716 -msgid "" -"value = STACK.pop()\n" -"result = func(value)\n" -"STACK.append(result)" -msgstr "" -"value = STACK.pop()\n" -"result = func(value)\n" -"STACK.append(result)" - -#: ../../library/dis.rst:1720 -msgid "``oparg == 1``: call :func:`str` on *value*" -msgstr "``oparg == 1``：對 *value* 呼叫 :func:`str`" - -#: ../../library/dis.rst:1721 -msgid "``oparg == 2``: call :func:`repr` on *value*" -msgstr "``oparg == 2``：對 *value* 呼叫 :func:`repr`" -#: ../../library/dis.rst:1722 -msgid "``oparg == 3``: call :func:`ascii` on *value*" -msgstr "``oparg == 3``：對 *value* 呼叫 :func:`ascii`" - -#: ../../library/dis.rst:1724 ../../library/dis.rst:1737 -#: ../../library/dis.rst:1750 -msgid "Used for implementing formatted string literals (f-strings)." -msgstr "" - -#: ../../library/dis.rst:1731 -msgid "Formats the value on top of stack::" -msgstr "" - -#: ../../library/dis.rst:1733 -msgid "" -"value = STACK.pop()\n" -"result = value.__format__(\"\")\n" -"STACK.append(result)" -msgstr "" -"value = STACK.pop()\n" -"result = value.__format__(\"\")\n" -"STACK.append(result)" - -#: ../../library/dis.rst:1743 -msgid "Formats the given value with the given format spec::" -msgstr "" - -#: ../../library/dis.rst:1745 -msgid "" -"spec = STACK.pop()\n" -"value = STACK.pop()\n" -"result = value.__format__(spec)\n" -"STACK.append(result)" -msgstr "" -"spec = STACK.pop()\n" -"value = STACK.pop()\n" -"result = value.__format__(spec)\n" -"STACK.append(result)" - -#: ../../library/dis.rst:1757 -msgid "" -"``STACK[-1]`` is a tuple of keyword attribute names, ``STACK[-2]`` is the " -"class being matched against, and ``STACK[-3]`` is the match subject. " -"*count* is the number of positional sub-patterns." -msgstr "" - -#: ../../library/dis.rst:1761 -msgid "" -"Pop ``STACK[-1]``, ``STACK[-2]``, and ``STACK[-3]``. If ``STACK[-3]`` is an " -"instance of ``STACK[-2]`` and has the positional and keyword attributes " -"required by *count* and ``STACK[-1]``, push a tuple of extracted attributes. " -"Otherwise, push ``None``." -msgstr "" - -#: ../../library/dis.rst:1775 -msgid "A no-op. Performs internal tracing, debugging and optimization checks." -msgstr "" - -#: ../../library/dis.rst:1777 -msgid "" -"The ``context`` operand consists of two parts. The lowest two bits indicate " -"where the ``RESUME`` occurs:" -msgstr "" - -#: ../../library/dis.rst:1780 -msgid "" -"``0`` The start of a function, which is neither a generator, coroutine nor " -"an async generator" -msgstr "" - -#: ../../library/dis.rst:1782 -msgid "``1`` After a ``yield`` expression" -msgstr "" - -#: ../../library/dis.rst:1783 -msgid "``2`` After a ``yield from`` expression" -msgstr "" - -#: ../../library/dis.rst:1784 -msgid "``3`` After an ``await`` expression" -msgstr "" - -#: ../../library/dis.rst:1786 -msgid "" -"The next bit is ``1`` if the RESUME is at except-depth ``1``, and ``0`` " -"otherwise." -msgstr "" - -#: ../../library/dis.rst:1791 -msgid "The oparg value changed to include information about except-depth" -msgstr "" - -#: ../../library/dis.rst:1797 -msgid "" -"Create a generator, coroutine, or async generator from the current frame. " -"Used as first opcode of in code object for the above mentioned callables. " -"Clear the current frame and return the newly created generator." -msgstr "" - -#: ../../library/dis.rst:1806 -msgid "" -"Equivalent to ``STACK[-1] = STACK[-2].send(STACK[-1])``. Used in ``yield " -"from`` and ``await`` statements." -msgstr "" - -#: ../../library/dis.rst:1809 -msgid "" -"If the call raises :exc:`StopIteration`, pop the top value from the stack, " -"push the exception's ``value`` attribute, and increment the bytecode counter " -"by *delta*." -msgstr "" - -#: ../../library/dis.rst:1818 -msgid "" -"This is not really an opcode. It identifies the dividing line between " -"opcodes in the range [0,255] which don't use their argument and those that " -"do (``< HAVE_ARGUMENT`` and ``>= HAVE_ARGUMENT``, respectively)." -msgstr "" - -#: ../../library/dis.rst:1822 -msgid "" -"If your application uses pseudo instructions or specialized instructions, " -"use the :data:`hasarg` collection instead." -msgstr "" - -#: ../../library/dis.rst:1825 -msgid "" -"Now every instruction has an argument, but opcodes ``< HAVE_ARGUMENT`` " -"ignore it. Before, only opcodes ``>= HAVE_ARGUMENT`` had an argument." -msgstr "" - -#: ../../library/dis.rst:1829 -msgid "" -"Pseudo instructions were added to the :mod:`dis` module, and for them it is " -"not true that comparison with ``HAVE_ARGUMENT`` indicates whether they use " -"their arg." -msgstr "" - -#: ../../library/dis.rst:1834 -msgid "Use :data:`hasarg` instead." -msgstr "改用 :data:`hasarg`。" - -#: ../../library/dis.rst:1839 -msgid "" -"Calls an intrinsic function with one argument. Passes ``STACK[-1]`` as the " -"argument and sets ``STACK[-1]`` to the result. Used to implement " -"functionality that is not performance critical." -msgstr "" - -#: ../../library/dis.rst:1843 ../../library/dis.rst:1897 -msgid "The operand determines which intrinsic function is called:" -msgstr "" - -#: ../../library/dis.rst:1846 ../../library/dis.rst:1900 -msgid "Operand" -msgstr "運算元" - -#: ../../library/dis.rst:1846 ../../library/dis.rst:1900 -msgid "Description" -msgstr "描述" - -#: ../../library/dis.rst:1848 -msgid "``INTRINSIC_1_INVALID``" -msgstr "``INTRINSIC_1_INVALID``" - -#: ../../library/dis.rst:1848 ../../library/dis.rst:1902 -msgid "Not valid" -msgstr "" - -#: ../../library/dis.rst:1850 -msgid "``INTRINSIC_PRINT``" -msgstr "``INTRINSIC_PRINT``" - -#: ../../library/dis.rst:1850 -msgid "Prints the argument to standard out. Used in the REPL." -msgstr "" - -#: ../../library/dis.rst:1853 -msgid "``INTRINSIC_IMPORT_STAR``" -msgstr "``INTRINSIC_IMPORT_STAR``" - -#: ../../library/dis.rst:1853 -msgid "Performs ``import *`` for the named module." -msgstr "" - -#: ../../library/dis.rst:1856 -msgid "``INTRINSIC_STOPITERATION_ERROR``" -msgstr "``INTRINSIC_STOPITERATION_ERROR``" - -#: ../../library/dis.rst:1856 -msgid "Extracts the return value from a ``StopIteration`` exception." -msgstr "" - -#: ../../library/dis.rst:1859 -msgid "``INTRINSIC_ASYNC_GEN_WRAP``" -msgstr "``INTRINSIC_ASYNC_GEN_WRAP``" - -#: ../../library/dis.rst:1859 -msgid "Wraps an async generator value" -msgstr "" - -#: ../../library/dis.rst:1861 -msgid "``INTRINSIC_UNARY_POSITIVE``" -msgstr "``INTRINSIC_UNARY_POSITIVE``" - -#: ../../library/dis.rst:1861 -msgid "Performs the unary ``+`` operation" -msgstr "" - -#: ../../library/dis.rst:1864 -msgid "``INTRINSIC_LIST_TO_TUPLE``" -msgstr "``INTRINSIC_LIST_TO_TUPLE``" - -#: ../../library/dis.rst:1864 -msgid "Converts a list to a tuple" -msgstr "" - -#: ../../library/dis.rst:1866 -msgid "``INTRINSIC_TYPEVAR``" -msgstr "``INTRINSIC_TYPEVAR``" - -#: ../../library/dis.rst:1866 -msgid "Creates a :class:`typing.TypeVar`" -msgstr "建立一個 :class:`typing.TypeVar`" - -#: ../../library/dis.rst:1868 -msgid "``INTRINSIC_PARAMSPEC``" -msgstr "``INTRINSIC_PARAMSPEC``" - -#: ../../library/dis.rst:1868 -msgid "Creates a :class:`typing.ParamSpec`" -msgstr "建立一個 :class:`typing.ParamSpec`" - -#: ../../library/dis.rst:1871 -msgid "``INTRINSIC_TYPEVARTUPLE``" -msgstr "``INTRINSIC_TYPEVARTUPLE``" - -#: ../../library/dis.rst:1871 -msgid "Creates a :class:`typing.TypeVarTuple`" -msgstr "建立一個 :class:`typing.TypeVarTuple`" - -#: ../../library/dis.rst:1874 -msgid "``INTRINSIC_SUBSCRIPT_GENERIC``" -msgstr "``INTRINSIC_SUBSCRIPT_GENERIC``" - -#: ../../library/dis.rst:1874 -msgid "Returns :class:`typing.Generic` subscripted with the argument" -msgstr "" - -#: ../../library/dis.rst:1877 -msgid "``INTRINSIC_TYPEALIAS``" -msgstr "``INTRINSIC_TYPEALIAS``" - -#: ../../library/dis.rst:1877 -msgid "" -"Creates a :class:`typing.TypeAliasType`; used in the :keyword:`type` " -"statement. The argument is a tuple of the type alias's name, type " -"parameters, and value." -msgstr "" - -#: ../../library/dis.rst:1889 -msgid "" -"Calls an intrinsic function with two arguments. Used to implement " -"functionality that is not performance critical::" -msgstr "" - -#: ../../library/dis.rst:1892 -msgid "" -"arg2 = STACK.pop()\n" -"arg1 = STACK.pop()\n" -"result = intrinsic2(arg1, arg2)\n" -"STACK.append(result)" -msgstr "" -"arg2 = STACK.pop()\n" -"arg1 = STACK.pop()\n" -"result = intrinsic2(arg1, arg2)\n" -"STACK.append(result)" - -#: ../../library/dis.rst:1902 -msgid "``INTRINSIC_2_INVALID``" -msgstr "``INTRINSIC_2_INVALID``" - -#: ../../library/dis.rst:1904 -msgid "``INTRINSIC_PREP_RERAISE_STAR``" -msgstr "``INTRINSIC_PREP_RERAISE_STAR``" - -#: ../../library/dis.rst:1904 -msgid "Calculates the :exc:`ExceptionGroup` to raise from a ``try-except*``." -msgstr "" - -#: ../../library/dis.rst:1908 -msgid "``INTRINSIC_TYPEVAR_WITH_BOUND``" -msgstr "``INTRINSIC_TYPEVAR_WITH_BOUND``" - -#: ../../library/dis.rst:1908 -msgid "Creates a :class:`typing.TypeVar` with a bound." -msgstr "" - -#: ../../library/dis.rst:1911 -msgid "``INTRINSIC_TYPEVAR_WITH_CONSTRAINTS``" -msgstr "``INTRINSIC_TYPEVAR_WITH_CONSTRAINTS``" - -#: ../../library/dis.rst:1911 -msgid "Creates a :class:`typing.TypeVar` with constraints." -msgstr "" - -#: ../../library/dis.rst:1915 -msgid "``INTRINSIC_SET_FUNCTION_TYPE_PARAMS``" -msgstr "``INTRINSIC_SET_FUNCTION_TYPE_PARAMS``" - -#: ../../library/dis.rst:1915 -msgid "Sets the ``__type_params__`` attribute of a function." -msgstr "設定函式的 ``__type_params__`` 屬性。" - -#: ../../library/dis.rst:1924 -msgid "" -"Performs special method lookup on ``STACK[-1]``. If ``type(STACK[-1])." -"__xxx__`` is a method, leave ``type(STACK[-1]).__xxx__; STACK[-1]`` on the " -"stack. If ``type(STACK[-1]).__xxx__`` is not a method, leave ``STACK[-1]." -"__xxx__; NULL`` on the stack." -msgstr "" - -#: ../../library/dis.rst:1933 -msgid "**Pseudo-instructions**" -msgstr "" - -#: ../../library/dis.rst:1935 -msgid "" -"These opcodes do not appear in Python bytecode. They are used by the " -"compiler but are replaced by real opcodes or removed before bytecode is " -"generated." -msgstr "" - -#: ../../library/dis.rst:1940 -msgid "" -"Set up an exception handler for the following code block. If an exception " -"occurs, the value stack level is restored to its current state and control " -"is transferred to the exception handler at ``target``." -msgstr "" - -#: ../../library/dis.rst:1947 -msgid "" -"Like ``SETUP_FINALLY``, but in case of an exception also pushes the last " -"instruction (``lasti``) to the stack so that ``RERAISE`` can restore it. If " -"an exception occurs, the value stack level and the last instruction on the " -"frame are restored to their current state, and control is transferred to the " -"exception handler at ``target``." -msgstr "" - -#: ../../library/dis.rst:1956 -msgid "" -"Like ``SETUP_CLEANUP``, but in case of an exception one more item is popped " -"from the stack before control is transferred to the exception handler at " -"``target``." -msgstr "" - -#: ../../library/dis.rst:1960 -msgid "" -"This variant is used in :keyword:`with` and :keyword:`async with` " -"constructs, which push the return value of the context manager's :meth:" -"`~object.__enter__` or :meth:`~object.__aenter__` to the stack." -msgstr "" - -#: ../../library/dis.rst:1967 -msgid "" -"Marks the end of the code block associated with the last ``SETUP_FINALLY``, " -"``SETUP_CLEANUP`` or ``SETUP_WITH``." -msgstr "" - -#: ../../library/dis.rst:1973 -msgid "" -"Works as :opcode:`LOAD_CONST`, but is more efficient for immortal objects." -msgstr "" - -#: ../../library/dis.rst:1979 -msgid "" -"Undirected relative jump instructions which are replaced by their directed " -"(forward/backward) counterparts by the assembler." -msgstr "" - -#: ../../library/dis.rst:1985 -msgid "" -"Conditional jumps which do not impact the stack. Replaced by the sequence " -"``COPY 1``, ``TO_BOOL``, ``POP_JUMP_IF_TRUE/FALSE``." -msgstr "" - -#: ../../library/dis.rst:1990 -msgid "" -"Pushes a reference to the cell contained in slot ``i`` of the \"fast " -"locals\" storage." -msgstr "" - -#: ../../library/dis.rst:1993 -msgid "" -"Note that ``LOAD_CLOSURE`` is replaced with ``LOAD_FAST`` in the assembler." -msgstr "" - -#: ../../library/dis.rst:1995 -msgid "This opcode is now a pseudo-instruction." -msgstr "" - -#: ../../library/dis.rst:2002 -msgid "Opcode collections" -msgstr "" - -#: ../../library/dis.rst:2004 -msgid "" -"These collections are provided for automatic introspection of bytecode " -"instructions:" -msgstr "" - -#: ../../library/dis.rst:2007 -msgid "" -"The collections now contain pseudo instructions and instrumented " -"instructions as well. These are opcodes with values ``>= MIN_PSEUDO_OPCODE`` " -"and ``>= MIN_INSTRUMENTED_OPCODE``." -msgstr "" - -#: ../../library/dis.rst:2014 -msgid "Sequence of operation names, indexable using the bytecode." -msgstr "" - -#: ../../library/dis.rst:2019 -msgid "Dictionary mapping operation names to bytecodes." -msgstr "" - -#: ../../library/dis.rst:2024 -msgid "Sequence of all compare operation names." -msgstr "" - -#: ../../library/dis.rst:2029 -msgid "Sequence of bytecodes that use their argument." -msgstr "" - -#: ../../library/dis.rst:2036 -msgid "Sequence of bytecodes that access a constant." -msgstr "" - -#: ../../library/dis.rst:2041 -msgid "" -"Sequence of bytecodes that access a :term:`free (closure) variable `. 'free' in this context refers to names in the current scope that " -"are referenced by inner scopes or names in outer scopes that are referenced " -"from this scope. It does *not* include references to global or builtin " -"scopes." -msgstr "" - -#: ../../library/dis.rst:2049 -msgid "Sequence of bytecodes that access an attribute by name." -msgstr "" - -#: ../../library/dis.rst:2054 -msgid "Sequence of bytecodes that have a jump target. All jumps are relative." -msgstr "" - -#: ../../library/dis.rst:2061 -msgid "Sequence of bytecodes that access a local variable." -msgstr "" - -#: ../../library/dis.rst:2066 -msgid "Sequence of bytecodes of Boolean operations." -msgstr "" - -#: ../../library/dis.rst:2070 -msgid "Sequence of bytecodes that set an exception handler." -msgstr "" - -#: ../../library/dis.rst:2077 -msgid "Sequence of bytecodes that have a relative jump target." -msgstr "" - -#: ../../library/dis.rst:2079 -msgid "All jumps are now relative. Use :data:`hasjump`." -msgstr "" - -#: ../../library/dis.rst:2085 -msgid "Sequence of bytecodes that have an absolute jump target." -msgstr "" - -#: ../../library/dis.rst:2087 -msgid "All jumps are now relative. This list is empty." -msgstr "" - -#: ../../library/dis.rst:1686 -msgid "built-in function" -msgstr "built-in function（內建函式）" - -#: ../../library/dis.rst:1686 -msgid "slice" -msgstr "slice（切片）" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# splasky Chang , 2017 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-01-08 00:16+0000\n" +"PO-Revision-Date: 2018-07-27 16:55+0800\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" +"X-Generator: Poedit 2.1.1\n" + +#: ../../library/dis.rst:2 +msgid ":mod:`!dis` --- Disassembler for Python bytecode" +msgstr ":mod:`!dis` --- Python bytecode 的反組譯器" + +#: ../../library/dis.rst:7 +msgid "**Source code:** :source:`Lib/dis.py`" +msgstr "**原始碼：**\\ :source:`Lib/dis.py`" + +#: ../../library/dis.rst:17 +msgid "" +"The :mod:`dis` module supports the analysis of CPython :term:`bytecode` by " +"disassembling it. The CPython bytecode which this module takes as an input " +"is defined in the file :file:`Include/opcode.h` and used by the compiler and " +"the interpreter." +msgstr "" +":mod:`dis` 模組支援反組譯分析 CPython :term:`bytecode`。CPython bytecode 作為" +"輸入的模組被定義於 :file:`Include/opcode.h` 並且被編譯器和直譯器所使用。" + +#: ../../library/dis.rst:24 +msgid "" +"Bytecode is an implementation detail of the CPython interpreter. No " +"guarantees are made that bytecode will not be added, removed, or changed " +"between versions of Python. Use of this module should not be considered to " +"work across Python VMs or Python releases." +msgstr "" + +#: ../../library/dis.rst:29 +msgid "" +"Use 2 bytes for each instruction. Previously the number of bytes varied by " +"instruction." +msgstr "" + +#: ../../library/dis.rst:33 +msgid "" +"The argument of jump, exception handling and loop instructions is now the " +"instruction offset rather than the byte offset." +msgstr "" + +#: ../../library/dis.rst:37 +msgid "" +"Some instructions are accompanied by one or more inline cache entries, which " +"take the form of :opcode:`CACHE` instructions. These instructions are hidden " +"by default, but can be shown by passing ``show_caches=True`` to any :mod:" +"`dis` utility. Furthermore, the interpreter now adapts the bytecode to " +"specialize it for different runtime conditions. The adaptive bytecode can be " +"shown by passing ``adaptive=True``." +msgstr "" + +#: ../../library/dis.rst:45 +msgid "" +"The argument of a jump is the offset of the target instruction relative to " +"the instruction that appears immediately after the jump instruction's :" +"opcode:`CACHE` entries." +msgstr "" + +#: ../../library/dis.rst:50 +msgid "" +"As a consequence, the presence of the :opcode:`CACHE` instructions is " +"transparent for forward jumps but needs to be taken into account when " +"reasoning about backward jumps." +msgstr "" + +#: ../../library/dis.rst:54 +msgid "" +"The output shows logical labels rather than instruction offsets for jump " +"targets and exception handlers. The ``-O`` command line option and the " +"``show_offsets`` argument were added." +msgstr "" + +#: ../../library/dis.rst:59 +msgid "" +"The :option:`-P ` command-line option and the " +"``show_positions`` argument were added." +msgstr "" + +#: ../../library/dis.rst:63 +msgid "The :option:`-S ` command-line option is added." +msgstr "" + +#: ../../library/dis.rst:65 +msgid "Example: Given the function :func:`!myfunc`::" +msgstr "" + +#: ../../library/dis.rst:67 +msgid "" +"def myfunc(alist):\n" +" return len(alist)" +msgstr "" +"def myfunc(alist):\n" +" return len(alist)" + +#: ../../library/dis.rst:70 +msgid "" +"the following command can be used to display the disassembly of :func:`!" +"myfunc`:" +msgstr "可以使用以下指令來顯示 :func:`!myfunc` 的反組譯：" + +#: ../../library/dis.rst:73 +msgid "" +">>> dis.dis(myfunc)\n" +" 2 RESUME 0\n" +"\n" +" 3 LOAD_GLOBAL 1 (len + NULL)\n" +" LOAD_FAST_BORROW 0 (alist)\n" +" CALL 1\n" +" RETURN_VALUE" +msgstr "" +">>> dis.dis(myfunc)\n" +" 2 RESUME 0\n" +"\n" +" 3 LOAD_GLOBAL 1 (len + NULL)\n" +" LOAD_FAST_BORROW 0 (alist)\n" +" CALL 1\n" +" RETURN_VALUE" + +#: ../../library/dis.rst:83 +msgid "(The \"2\" is a line number)." +msgstr "" + +#: ../../library/dis.rst:88 +msgid "Command-line interface" +msgstr "命令列介面" + +#: ../../library/dis.rst:90 +msgid "The :mod:`dis` module can be invoked as a script from the command line:" +msgstr "" + +#: ../../library/dis.rst:92 +msgid "python -m dis [-h] [-C] [-O] [-P] [-S] [infile]" +msgstr "python -m dis [-h] [-C] [-O] [-P] [-S] [infile]" + +#: ../../library/dis.rst:96 +msgid "The following options are accepted:" +msgstr "可接受以下選項：" + +#: ../../library/dis.rst:102 +msgid "Display usage and exit." +msgstr "" + +#: ../../library/dis.rst:106 +msgid "Show inline caches." +msgstr "" + +#: ../../library/dis.rst:112 +msgid "Show offsets of instructions." +msgstr "" + +#: ../../library/dis.rst:118 +msgid "Show positions of instructions in the source code." +msgstr "" + +#: ../../library/dis.rst:124 +msgid "Show specialized bytecode." +msgstr "" + +#: ../../library/dis.rst:128 +msgid "" +"If :file:`infile` is specified, its disassembled code will be written to " +"stdout. Otherwise, disassembly is performed on compiled source code received " +"from stdin." +msgstr "" + +#: ../../library/dis.rst:132 +msgid "Bytecode analysis" +msgstr "" + +#: ../../library/dis.rst:136 +msgid "" +"The bytecode analysis API allows pieces of Python code to be wrapped in a :" +"class:`Bytecode` object that provides easy access to details of the compiled " +"code." +msgstr "" + +#: ../../library/dis.rst:144 +msgid "" +"Analyse the bytecode corresponding to a function, generator, asynchronous " +"generator, coroutine, method, string of source code, or a code object (as " +"returned by :func:`compile`)." +msgstr "" + +#: ../../library/dis.rst:148 +msgid "" +"This is a convenience wrapper around many of the functions listed below, " +"most notably :func:`get_instructions`, as iterating over a :class:`Bytecode` " +"instance yields the bytecode operations as :class:`Instruction` instances." +msgstr "" + +#: ../../library/dis.rst:152 ../../library/dis.rst:373 +msgid "" +"If *first_line* is not ``None``, it indicates the line number that should be " +"reported for the first source line in the disassembled code. Otherwise, the " +"source line information (if any) is taken directly from the disassembled " +"code object." +msgstr "" + +#: ../../library/dis.rst:157 +msgid "" +"If *current_offset* is not ``None``, it refers to an instruction offset in " +"the disassembled code. Setting this means :meth:`.dis` will display a " +"\"current instruction\" marker against the specified opcode." +msgstr "" + +#: ../../library/dis.rst:161 +msgid "" +"If *show_caches* is ``True``, :meth:`.dis` will display inline cache entries " +"used by the interpreter to specialize the bytecode." +msgstr "" + +#: ../../library/dis.rst:164 +msgid "" +"If *adaptive* is ``True``, :meth:`.dis` will display specialized bytecode " +"that may be different from the original bytecode." +msgstr "" + +#: ../../library/dis.rst:167 +msgid "" +"If *show_offsets* is ``True``, :meth:`.dis` will include instruction offsets " +"in the output." +msgstr "" + +#: ../../library/dis.rst:170 +msgid "" +"If *show_positions* is ``True``, :meth:`.dis` will include instruction " +"source code positions in the output." +msgstr "" + +#: ../../library/dis.rst:175 +msgid "" +"Construct a :class:`Bytecode` instance from the given traceback, setting " +"*current_offset* to the instruction responsible for the exception." +msgstr "" + +#: ../../library/dis.rst:180 +msgid "The compiled code object." +msgstr "" + +#: ../../library/dis.rst:184 +msgid "The first source line of the code object (if available)" +msgstr "" + +#: ../../library/dis.rst:188 +msgid "" +"Return a formatted view of the bytecode operations (the same as printed by :" +"func:`dis.dis`, but returned as a multi-line string)." +msgstr "" + +#: ../../library/dis.rst:193 +msgid "" +"Return a formatted multi-line string with detailed information about the " +"code object, like :func:`code_info`." +msgstr "" + +#: ../../library/dis.rst:196 ../../library/dis.rst:242 +#: ../../library/dis.rst:295 +msgid "This can now handle coroutine and asynchronous generator objects." +msgstr "" + +#: ../../library/dis.rst:199 ../../library/dis.rst:298 +#: ../../library/dis.rst:320 ../../library/dis.rst:356 +#: ../../library/dis.rst:382 +msgid "Added the *show_caches* and *adaptive* parameters." +msgstr "新增 *show_caches* 與 *adaptive* 參數。" + +#: ../../library/dis.rst:202 +msgid "Added the *show_offsets* parameter" +msgstr "新增 *show_offsets* 參數。" + +#: ../../library/dis.rst:205 ../../library/dis.rst:304 +#: ../../library/dis.rst:326 ../../library/dis.rst:362 +msgid "Added the *show_positions* parameter." +msgstr "新增 *show_positions* 參數。" + +#: ../../library/dis.rst:208 +msgid "Example:" +msgstr "範例：" + +#: ../../library/dis.rst:210 +msgid "" +">>> bytecode = dis.Bytecode(myfunc)\n" +">>> for instr in bytecode:\n" +"... print(instr.opname)\n" +"...\n" +"RESUME\n" +"LOAD_GLOBAL\n" +"LOAD_FAST_BORROW\n" +"CALL\n" +"RETURN_VALUE" +msgstr "" +">>> bytecode = dis.Bytecode(myfunc)\n" +">>> for instr in bytecode:\n" +"... print(instr.opname)\n" +"...\n" +"RESUME\n" +"LOAD_GLOBAL\n" +"LOAD_FAST_BORROW\n" +"CALL\n" +"RETURN_VALUE" + +#: ../../library/dis.rst:224 +msgid "Analysis functions" +msgstr "分析函式" + +#: ../../library/dis.rst:226 +msgid "" +"The :mod:`dis` module also defines the following analysis functions that " +"convert the input directly to the desired output. They can be useful if only " +"a single operation is being performed, so the intermediate analysis object " +"isn't useful:" +msgstr "" + +#: ../../library/dis.rst:232 +msgid "" +"Return a formatted multi-line string with detailed code object information " +"for the supplied function, generator, asynchronous generator, coroutine, " +"method, source code string or code object." +msgstr "" + +#: ../../library/dis.rst:236 +msgid "" +"Note that the exact contents of code info strings are highly implementation " +"dependent and they may change arbitrarily across Python VMs or Python " +"releases." +msgstr "" + +#: ../../library/dis.rst:248 +msgid "" +"Print detailed code object information for the supplied function, method, " +"source code string or code object to *file* (or ``sys.stdout`` if *file* is " +"not specified)." +msgstr "" + +#: ../../library/dis.rst:252 +msgid "" +"This is a convenient shorthand for ``print(code_info(x), file=file)``, " +"intended for interactive exploration at the interpreter prompt." +msgstr "" + +#: ../../library/dis.rst:257 ../../library/dis.rst:289 +#: ../../library/dis.rst:317 ../../library/dis.rst:353 +msgid "Added *file* parameter." +msgstr "新增 *file* 參數。" + +#: ../../library/dis.rst:264 +msgid "" +"Disassemble the *x* object. *x* can denote either a module, a class, a " +"method, a function, a generator, an asynchronous generator, a coroutine, a " +"code object, a string of source code or a byte sequence of raw bytecode. For " +"a module, it disassembles all functions. For a class, it disassembles all " +"methods (including class and static methods). For a code object or sequence " +"of raw bytecode, it prints one line per bytecode instruction. It also " +"recursively disassembles nested code objects. These can include generator " +"expressions, nested functions, the bodies of nested classes, and the code " +"objects used for :ref:`annotation scopes `. Strings are " +"first compiled to code objects with the :func:`compile` built-in function " +"before being disassembled. If no object is provided, this function " +"disassembles the last traceback." +msgstr "" + +#: ../../library/dis.rst:277 ../../library/dis.rst:314 +#: ../../library/dis.rst:350 +msgid "" +"The disassembly is written as text to the supplied *file* argument if " +"provided and to ``sys.stdout`` otherwise." +msgstr "" + +#: ../../library/dis.rst:280 +msgid "" +"The maximal depth of recursion is limited by *depth* unless it is ``None``. " +"``depth=0`` means no recursion." +msgstr "" + +#: ../../library/dis.rst:283 +msgid "" +"If *show_caches* is ``True``, this function will display inline cache " +"entries used by the interpreter to specialize the bytecode." +msgstr "" + +#: ../../library/dis.rst:286 +msgid "" +"If *adaptive* is ``True``, this function will display specialized bytecode " +"that may be different from the original bytecode." +msgstr "" + +#: ../../library/dis.rst:292 +msgid "Implemented recursive disassembling and added *depth* parameter." +msgstr "" + +#: ../../library/dis.rst:301 ../../library/dis.rst:323 +#: ../../library/dis.rst:359 +msgid "Added the *show_offsets* parameter." +msgstr "新增 *show_offsets* 參數。" + +#: ../../library/dis.rst:310 +msgid "" +"Disassemble the top-of-stack function of a traceback, using the last " +"traceback if none was passed. The instruction causing the exception is " +"indicated." +msgstr "" + +#: ../../library/dis.rst:334 +msgid "" +"Disassemble a code object, indicating the last instruction if *lasti* was " +"provided. The output is divided in the following columns:" +msgstr "" + +#: ../../library/dis.rst:337 +msgid "" +"the source code location of the instruction. Complete location information " +"is shown if *show_positions* is true. Otherwise (the default) only the line " +"number is displayed." +msgstr "" + +#: ../../library/dis.rst:340 +msgid "the current instruction, indicated as ``-->``," +msgstr "" + +#: ../../library/dis.rst:341 +msgid "a labelled instruction, indicated with ``>>``," +msgstr "" + +#: ../../library/dis.rst:342 +msgid "the address of the instruction," +msgstr "" + +#: ../../library/dis.rst:343 +msgid "the operation code name," +msgstr "" + +#: ../../library/dis.rst:344 +msgid "operation parameters, and" +msgstr "" + +#: ../../library/dis.rst:345 +msgid "interpretation of the parameters in parentheses." +msgstr "" + +#: ../../library/dis.rst:347 +msgid "" +"The parameter interpretation recognizes local and global variable names, " +"constant values, branch targets, and compare operators." +msgstr "" + +#: ../../library/dis.rst:367 +msgid "" +"Return an iterator over the instructions in the supplied function, method, " +"source code string or code object." +msgstr "" + +#: ../../library/dis.rst:370 +msgid "" +"The iterator generates a series of :class:`Instruction` named tuples giving " +"the details of each operation in the supplied code." +msgstr "" + +#: ../../library/dis.rst:378 +msgid "The *adaptive* parameter works as it does in :func:`dis`." +msgstr "" + +#: ../../library/dis.rst:385 +msgid "" +"The *show_caches* parameter is deprecated and has no effect. The iterator " +"generates the :class:`Instruction` instances with the *cache_info* field " +"populated (regardless of the value of *show_caches*) and it no longer " +"generates separate items for the cache entries." +msgstr "" + +#: ../../library/dis.rst:393 +msgid "" +"This generator function uses the :meth:`~codeobject.co_lines` method of the :" +"ref:`code object ` *code* to find the offsets which are starts " +"of lines in the source code. They are generated as ``(offset, lineno)`` " +"pairs." +msgstr "" + +#: ../../library/dis.rst:398 +msgid "Line numbers can be decreasing. Before, they were always increasing." +msgstr "" + +#: ../../library/dis.rst:401 +msgid "" +"The :pep:`626` :meth:`~codeobject.co_lines` method is used instead of the :" +"attr:`~codeobject.co_firstlineno` and :attr:`~codeobject.co_lnotab` " +"attributes of the :ref:`code object `." +msgstr "" + +#: ../../library/dis.rst:406 +msgid "" +"Line numbers can be ``None`` for bytecode that does not map to source lines." +msgstr "" + +#: ../../library/dis.rst:412 +msgid "" +"Detect all offsets in the raw compiled bytecode string *code* which are jump " +"targets, and return a list of these offsets." +msgstr "" + +#: ../../library/dis.rst:418 +msgid "Compute the stack effect of *opcode* with argument *oparg*." +msgstr "" + +#: ../../library/dis.rst:420 +msgid "" +"If the code has a jump target and *jump* is ``True``, :func:`~stack_effect` " +"will return the stack effect of jumping. If *jump* is ``False``, it will " +"return the stack effect of not jumping. And if *jump* is ``None`` (default), " +"it will return the maximal stack effect of both cases." +msgstr "" + +#: ../../library/dis.rst:427 +msgid "Added *jump* parameter." +msgstr "新增 *jump* 參數。" + +#: ../../library/dis.rst:430 +msgid "" +"If ``oparg`` is omitted (or ``None``), the stack effect is now returned for " +"``oparg=0``. Previously this was an error for opcodes that use their arg. It " +"is also no longer an error to pass an integer ``oparg`` when the ``opcode`` " +"does not use it; the ``oparg`` in this case is ignored." +msgstr "" + +#: ../../library/dis.rst:440 +msgid "Python Bytecode Instructions" +msgstr "Python 位元組碼指令" + +#: ../../library/dis.rst:442 +msgid "" +"The :func:`get_instructions` function and :class:`Bytecode` class provide " +"details of bytecode instructions as :class:`Instruction` instances:" +msgstr "" + +#: ../../library/dis.rst:447 +msgid "Details for a bytecode operation" +msgstr "位元組碼操作的詳細資訊" + +#: ../../library/dis.rst:451 +msgid "" +"numeric code for operation, corresponding to the opcode values listed below " +"and the bytecode values in the :ref:`opcode_collections`." +msgstr "" + +#: ../../library/dis.rst:457 +msgid "human readable name for operation" +msgstr "操作的可讀名稱" + +#: ../../library/dis.rst:462 +msgid "" +"numeric code for the base operation if operation is specialized; otherwise " +"equal to :data:`opcode`" +msgstr "" + +#: ../../library/dis.rst:468 +msgid "" +"human readable name for the base operation if operation is specialized; " +"otherwise equal to :data:`opname`" +msgstr "" + +#: ../../library/dis.rst:474 +msgid "numeric argument to operation (if any), otherwise ``None``" +msgstr "" + +#: ../../library/dis.rst:478 +msgid "alias for :data:`arg`" +msgstr ":data:`arg` 的別名。" + +#: ../../library/dis.rst:482 +msgid "resolved arg value (if any), otherwise ``None``" +msgstr "" + +#: ../../library/dis.rst:487 +msgid "" +"human readable description of operation argument (if any), otherwise an " +"empty string." +msgstr "" + +#: ../../library/dis.rst:493 +msgid "start index of operation within bytecode sequence" +msgstr "" + +#: ../../library/dis.rst:498 +msgid "" +"start index of operation within bytecode sequence, including prefixed " +"``EXTENDED_ARG`` operations if present; otherwise equal to :data:`offset`" +msgstr "" + +#: ../../library/dis.rst:504 +msgid "start index of the cache entries following the operation" +msgstr "" + +#: ../../library/dis.rst:509 +msgid "end index of the cache entries following the operation" +msgstr "" + +#: ../../library/dis.rst:514 +msgid "``True`` if this opcode starts a source line, otherwise ``False``" +msgstr "" + +#: ../../library/dis.rst:519 +msgid "" +"source line number associated with this opcode (if any), otherwise ``None``" +msgstr "" + +#: ../../library/dis.rst:524 +msgid "``True`` if other code jumps to here, otherwise ``False``" +msgstr "" + +#: ../../library/dis.rst:529 +msgid "" +"bytecode index of the jump target if this is a jump operation, otherwise " +"``None``" +msgstr "" + +#: ../../library/dis.rst:535 +msgid "" +":class:`dis.Positions` object holding the start and end locations that are " +"covered by this instruction." +msgstr "" + +#: ../../library/dis.rst:540 +msgid "" +"Information about the cache entries of this instruction, as triplets of the " +"form ``(name, size, data)``, where the ``name`` and ``size`` describe the " +"cache format and data is the contents of the cache. ``cache_info`` is " +"``None`` if the instruction does not have caches." +msgstr "" + +#: ../../library/dis.rst:550 +msgid "Field ``positions`` is added." +msgstr "" + +#: ../../library/dis.rst:554 +msgid "Changed field ``starts_line``." +msgstr "" + +#: ../../library/dis.rst:556 +msgid "" +"Added fields ``start_offset``, ``cache_offset``, ``end_offset``, " +"``baseopname``, ``baseopcode``, ``jump_target``, ``oparg``, ``line_number`` " +"and ``cache_info``." +msgstr "" + +#: ../../library/dis.rst:563 +msgid "" +"In case the information is not available, some fields might be ``None``." +msgstr "" + +#: ../../library/dis.rst:573 +msgid "" +"The Python compiler currently generates the following bytecode instructions." +msgstr "" + +#: ../../library/dis.rst:576 +msgid "**General instructions**" +msgstr "**一般指令**" + +#: ../../library/dis.rst:578 +msgid "" +"In the following, We will refer to the interpreter stack as ``STACK`` and " +"describe operations on it as if it was a Python list. The top of the stack " +"corresponds to ``STACK[-1]`` in this language." +msgstr "" + +#: ../../library/dis.rst:584 +msgid "" +"Do nothing code. Used as a placeholder by the bytecode optimizer, and to " +"generate line tracing events." +msgstr "" + +#: ../../library/dis.rst:590 +msgid "" +"Do nothing code. Used by the interpreter to record :monitoring-event:" +"`BRANCH_LEFT` and :monitoring-event:`BRANCH_RIGHT` events for :mod:`sys." +"monitoring`." +msgstr "" + +#: ../../library/dis.rst:599 +msgid "Removes the iterator from the top of the stack." +msgstr "" + +#: ../../library/dis.rst:606 +msgid "Removes the top-of-stack item::" +msgstr "" + +#: ../../library/dis.rst:608 +msgid "STACK.pop()" +msgstr "STACK.pop()" + +#: ../../library/dis.rst:613 +msgid "" +"Removes the top-of-stack item. Equivalent to ``POP_TOP``. Used to clean up " +"at the end of loops, hence the name." +msgstr "" + +#: ../../library/dis.rst:622 +msgid "Implements ``del STACK[-2]``. Used to clean up when a generator exits." +msgstr "" + +#: ../../library/dis.rst:630 +msgid "" +"Push the i-th item to the top of the stack without removing it from its " +"original location::" +msgstr "" + +#: ../../library/dis.rst:633 +msgid "" +"assert i > 0\n" +"STACK.append(STACK[-i])" +msgstr "" +"assert i > 0\n" +"STACK.append(STACK[-i])" + +#: ../../library/dis.rst:641 +msgid "Swap the top of the stack with the i-th element::" +msgstr "" + +#: ../../library/dis.rst:643 +msgid "STACK[-i], STACK[-1] = STACK[-1], STACK[-i]" +msgstr "STACK[-i], STACK[-1] = STACK[-1], STACK[-i]" + +#: ../../library/dis.rst:650 +msgid "" +"Rather than being an actual instruction, this opcode is used to mark extra " +"space for the interpreter to cache useful data directly in the bytecode " +"itself. It is automatically hidden by all ``dis`` utilities, but can be " +"viewed with ``show_caches=True``." +msgstr "" + +#: ../../library/dis.rst:655 +msgid "" +"Logically, this space is part of the preceding instruction. Many opcodes " +"expect to be followed by an exact number of caches, and will instruct the " +"interpreter to skip over them at runtime." +msgstr "" + +#: ../../library/dis.rst:659 +msgid "" +"Populated caches can look like arbitrary instructions, so great care should " +"be taken when reading or modifying raw, adaptive bytecode containing " +"quickened data." +msgstr "" + +#: ../../library/dis.rst:666 +msgid "**Unary operations**" +msgstr "" + +#: ../../library/dis.rst:668 +msgid "" +"Unary operations take the top of the stack, apply the operation, and push " +"the result back on the stack." +msgstr "" + +#: ../../library/dis.rst:674 +msgid "Implements ``STACK[-1] = -STACK[-1]``." +msgstr "實作 ``STACK[-1] = -STACK[-1]``。" + +#: ../../library/dis.rst:679 +msgid "Implements ``STACK[-1] = not STACK[-1]``." +msgstr "實作 ``STACK[-1] = not STACK[-1]``。" + +#: ../../library/dis.rst:681 ../../library/dis.rst:1383 +#: ../../library/dis.rst:1399 +msgid "This instruction now requires an exact :class:`bool` operand." +msgstr "" + +#: ../../library/dis.rst:687 +msgid "Implements ``STACK[-1] = ~STACK[-1]``." +msgstr "實作 ``STACK[-1] = ~STACK[-1]``。" + +#: ../../library/dis.rst:692 +msgid "Implements ``STACK[-1] = iter(STACK[-1])``." +msgstr "實作 ``STACK[-1] = iter(STACK[-1])``。" + +#: ../../library/dis.rst:697 +msgid "" +"If ``STACK[-1]`` is a :term:`generator iterator` or :term:`coroutine` object " +"it is left as is. Otherwise, implements ``STACK[-1] = iter(STACK[-1])``." +msgstr "" + +#: ../../library/dis.rst:705 +msgid "Implements ``STACK[-1] = bool(STACK[-1])``." +msgstr "" + +#: ../../library/dis.rst:710 +msgid "**Binary and in-place operations**" +msgstr "" + +#: ../../library/dis.rst:712 +msgid "" +"Binary operations remove the top two items from the stack (``STACK[-1]`` and " +"``STACK[-2]``). They perform the operation, then put the result back on the " +"stack." +msgstr "" + +#: ../../library/dis.rst:715 +msgid "" +"In-place operations are like binary operations, but the operation is done in-" +"place when ``STACK[-2]`` supports it, and the resulting ``STACK[-1]`` may be " +"(but does not have to be) the original ``STACK[-2]``." +msgstr "" + +#: ../../library/dis.rst:722 +msgid "" +"Implements the binary and in-place operators (depending on the value of " +"*op*)::" +msgstr "" + +#: ../../library/dis.rst:725 +msgid "" +"rhs = STACK.pop()\n" +"lhs = STACK.pop()\n" +"STACK.append(lhs op rhs)" +msgstr "" +"rhs = STACK.pop()\n" +"lhs = STACK.pop()\n" +"STACK.append(lhs op rhs)" + +#: ../../library/dis.rst:730 +msgid "" +"With oparg :``NB_SUBSCR``, implements binary subscript (replaces opcode " +"``BINARY_SUBSCR``)" +msgstr "" + +#: ../../library/dis.rst:736 ../../library/dis.rst:746 +#: ../../library/dis.rst:754 ../../library/dis.rst:766 +#: ../../library/dis.rst:844 ../../library/dis.rst:854 +#: ../../library/dis.rst:864 ../../library/dis.rst:1070 +#: ../../library/dis.rst:1081 ../../library/dis.rst:1226 +#: ../../library/dis.rst:1238 ../../library/dis.rst:1250 +msgid "Implements::" +msgstr "實作了： ::" + +#: ../../library/dis.rst:738 +msgid "" +"key = STACK.pop()\n" +"container = STACK.pop()\n" +"value = STACK.pop()\n" +"container[key] = value" +msgstr "" +"key = STACK.pop()\n" +"container = STACK.pop()\n" +"value = STACK.pop()\n" +"container[key] = value" + +#: ../../library/dis.rst:748 +msgid "" +"key = STACK.pop()\n" +"container = STACK.pop()\n" +"del container[key]" +msgstr "" +"key = STACK.pop()\n" +"container = STACK.pop()\n" +"del container[key]" + +#: ../../library/dis.rst:756 +msgid "" +"end = STACK.pop()\n" +"start = STACK.pop()\n" +"container = STACK.pop()\n" +"STACK.append(container[start:end])" +msgstr "" +"end = STACK.pop()\n" +"start = STACK.pop()\n" +"container = STACK.pop()\n" +"STACK.append(container[start:end])" + +#: ../../library/dis.rst:768 +msgid "" +"end = STACK.pop()\n" +"start = STACK.pop()\n" +"container = STACK.pop()\n" +"value = STACK.pop()\n" +"container[start:end] = value" +msgstr "" +"end = STACK.pop()\n" +"start = STACK.pop()\n" +"container = STACK.pop()\n" +"value = STACK.pop()\n" +"container[start:end] = value" + +#: ../../library/dis.rst:777 +msgid "**Coroutine opcodes**" +msgstr "" + +#: ../../library/dis.rst:781 +msgid "" +"Implements ``STACK[-1] = get_awaitable(STACK[-1])``, where " +"``get_awaitable(o)`` returns ``o`` if ``o`` is a coroutine object or a " +"generator object with the :data:`~inspect.CO_ITERABLE_COROUTINE` flag, or " +"resolves ``o.__await__``." +msgstr "" + +#: ../../library/dis.rst:786 +msgid "" +"If the ``where`` operand is nonzero, it indicates where the instruction " +"occurs:" +msgstr "" + +#: ../../library/dis.rst:789 +msgid "``1``: After a call to ``__aenter__``" +msgstr "" + +#: ../../library/dis.rst:790 +msgid "``2``: After a call to ``__aexit__``" +msgstr "" + +#: ../../library/dis.rst:794 +msgid "Previously, this instruction did not have an oparg." +msgstr "先前此指令沒有 oparg。" + +#: ../../library/dis.rst:800 +msgid "Implements ``STACK[-1] = STACK[-1].__aiter__()``." +msgstr "" + +#: ../../library/dis.rst:803 +msgid "Returning awaitable objects from ``__aiter__`` is no longer supported." +msgstr "" + +#: ../../library/dis.rst:810 +msgid "" +"Implement ``STACK.append(get_awaitable(STACK[-1].__anext__()))`` to the " +"stack. See ``GET_AWAITABLE`` for details about ``get_awaitable``." +msgstr "" + +#: ../../library/dis.rst:818 +msgid "" +"Terminates an :keyword:`async for` loop. Handles an exception raised when " +"awaiting a next item. The stack contains the async iterable in ``STACK[-2]`` " +"and the raised exception in ``STACK[-1]``. Both are popped. If the exception " +"is not :exc:`StopAsyncIteration`, it is re-raised." +msgstr "" + +#: ../../library/dis.rst:825 ../../library/dis.rst:916 +#: ../../library/dis.rst:927 +msgid "" +"Exception representation on the stack now consist of one, not three, items." +msgstr "" + +#: ../../library/dis.rst:831 +msgid "" +"Handles an exception raised during a :meth:`~generator.throw` or :meth:" +"`~generator.close` call through the current frame. If ``STACK[-1]`` is an " +"instance of :exc:`StopIteration`, pop three values from the stack and push " +"its ``value`` member. Otherwise, re-raise ``STACK[-1]``." +msgstr "" + +#: ../../library/dis.rst:840 +msgid "**Miscellaneous opcodes**" +msgstr "" + +#: ../../library/dis.rst:846 +msgid "" +"item = STACK.pop()\n" +"set.add(STACK[-i], item)" +msgstr "" +"item = STACK.pop()\n" +"set.add(STACK[-i], item)" + +#: ../../library/dis.rst:849 +msgid "Used to implement set comprehensions." +msgstr "" + +#: ../../library/dis.rst:856 +msgid "" +"item = STACK.pop()\n" +"list.append(STACK[-i], item)" +msgstr "" +"item = STACK.pop()\n" +"list.append(STACK[-i], item)" + +#: ../../library/dis.rst:859 +msgid "Used to implement list comprehensions." +msgstr "" + +#: ../../library/dis.rst:866 +msgid "" +"value = STACK.pop()\n" +"key = STACK.pop()\n" +"dict.__setitem__(STACK[-i], key, value)" +msgstr "" +"value = STACK.pop()\n" +"key = STACK.pop()\n" +"dict.__setitem__(STACK[-i], key, value)" + +#: ../../library/dis.rst:870 +msgid "Used to implement dict comprehensions." +msgstr "" + +#: ../../library/dis.rst:873 +msgid "" +"Map value is ``STACK[-1]`` and map key is ``STACK[-2]``. Before, those were " +"reversed." +msgstr "" + +#: ../../library/dis.rst:877 +msgid "" +"For all of the :opcode:`SET_ADD`, :opcode:`LIST_APPEND` and :opcode:" +"`MAP_ADD` instructions, while the added value or key/value pair is popped " +"off, the container object remains on the stack so that it is available for " +"further iterations of the loop." +msgstr "" + +#: ../../library/dis.rst:885 +msgid "Returns with ``STACK[-1]`` to the caller of the function." +msgstr "" + +#: ../../library/dis.rst:890 +msgid "Yields ``STACK.pop()`` from a :term:`generator`." +msgstr "" + +#: ../../library/dis.rst:892 +msgid "oparg set to be the stack depth." +msgstr "" + +#: ../../library/dis.rst:895 +msgid "" +"oparg set to be the exception block depth, for efficient closing of " +"generators." +msgstr "" + +#: ../../library/dis.rst:898 +msgid "" +"oparg is ``1`` if this instruction is part of a yield-from or await, and " +"``0`` otherwise." +msgstr "" + +#: ../../library/dis.rst:904 +msgid "" +"Checks whether ``__annotations__`` is defined in ``locals()``, if not it is " +"set up to an empty ``dict``. This opcode is only emitted if a class or " +"module body contains :term:`variable annotations ` " +"statically." +msgstr "" + +#: ../../library/dis.rst:914 +msgid "" +"Pops a value from the stack, which is used to restore the exception state." +msgstr "" + +#: ../../library/dis.rst:921 +msgid "" +"Re-raises the exception currently on top of the stack. If oparg is non-zero, " +"pops an additional value from the stack which is used to set :attr:`~frame." +"f_lasti` of the current frame." +msgstr "" + +#: ../../library/dis.rst:932 +msgid "" +"Pops a value from the stack. Pushes the current exception to the top of the " +"stack. Pushes the value originally popped back to the stack. Used in " +"exception handlers." +msgstr "" + +#: ../../library/dis.rst:940 +msgid "" +"Performs exception matching for ``except``. Tests whether the ``STACK[-2]`` " +"is an exception matching ``STACK[-1]``. Pops ``STACK[-1]`` and pushes the " +"boolean result of the test." +msgstr "" + +#: ../../library/dis.rst:948 +msgid "" +"Performs exception matching for ``except*``. Applies ``split(STACK[-1])`` on " +"the exception group representing ``STACK[-2]``." +msgstr "" + +#: ../../library/dis.rst:951 +msgid "" +"In case of a match, pops two items from the stack and pushes the non-" +"matching subgroup (``None`` in case of full match) followed by the matching " +"subgroup. When there is no match, pops one item (the match type) and pushes " +"``None``." +msgstr "" + +#: ../../library/dis.rst:960 +msgid "" +"Calls the function in position 4 on the stack with arguments (type, val, tb) " +"representing the exception at the top of the stack. Used to implement the " +"call ``context_manager.__exit__(*exc_info())`` when an exception has " +"occurred in a :keyword:`with` statement." +msgstr "" + +#: ../../library/dis.rst:967 +msgid "" +"The ``__exit__`` function is in position 4 of the stack rather than 7. " +"Exception representation on the stack now consist of one, not three, items." +msgstr "" + +#: ../../library/dis.rst:974 +msgid "" +"Pushes a common constant onto the stack. The interpreter contains a " +"hardcoded list of constants supported by this instruction. Used by the :" +"keyword:`assert` statement to load :exc:`AssertionError`." +msgstr "" + +#: ../../library/dis.rst:983 +msgid "" +"Pushes :func:`!builtins.__build_class__` onto the stack. It is later called " +"to construct a class." +msgstr "" + +#: ../../library/dis.rst:988 +msgid "" +"Perform ``STACK.append(len(STACK[-1]))``. Used in :keyword:`match` " +"statements where comparison with structure of pattern is needed." +msgstr "" + +#: ../../library/dis.rst:996 +msgid "" +"If ``STACK[-1]`` is an instance of :class:`collections.abc.Mapping` (or, " +"more technically: if it has the :c:macro:`Py_TPFLAGS_MAPPING` flag set in " +"its :c:member:`~PyTypeObject.tp_flags`), push ``True`` onto the stack. " +"Otherwise, push ``False``." +msgstr "" + +#: ../../library/dis.rst:1006 +msgid "" +"If ``STACK[-1]`` is an instance of :class:`collections.abc.Sequence` and is " +"*not* an instance of :class:`str`/:class:`bytes`/:class:`bytearray` (or, " +"more technically: if it has the :c:macro:`Py_TPFLAGS_SEQUENCE` flag set in " +"its :c:member:`~PyTypeObject.tp_flags`), push ``True`` onto the stack. " +"Otherwise, push ``False``." +msgstr "" + +#: ../../library/dis.rst:1016 +msgid "" +"``STACK[-1]`` is a tuple of mapping keys, and ``STACK[-2]`` is the match " +"subject. If ``STACK[-2]`` contains all of the keys in ``STACK[-1]``, push a :" +"class:`tuple` containing the corresponding values. Otherwise, push ``None``." +msgstr "" + +#: ../../library/dis.rst:1022 ../../library/dis.rst:1768 +msgid "" +"Previously, this instruction also pushed a boolean value indicating success " +"(``True``) or failure (``False``)." +msgstr "" + +#: ../../library/dis.rst:1029 +msgid "" +"Implements ``name = STACK.pop()``. *namei* is the index of *name* in the " +"attribute :attr:`~codeobject.co_names` of the :ref:`code object `. The compiler tries to use :opcode:`STORE_FAST` or :opcode:" +"`STORE_GLOBAL` if possible." +msgstr "" + +#: ../../library/dis.rst:1036 +msgid "" +"Implements ``del name``, where *namei* is the index into :attr:`~codeobject." +"co_names` attribute of the :ref:`code object `." +msgstr "" + +#: ../../library/dis.rst:1042 +msgid "" +"Unpacks ``STACK[-1]`` into *count* individual values, which are put onto the " +"stack right-to-left. Require there to be exactly *count* values.::" +msgstr "" + +#: ../../library/dis.rst:1045 +msgid "" +"assert(len(STACK[-1]) == count)\n" +"STACK.extend(STACK.pop()[:-count-1:-1])" +msgstr "" +"assert(len(STACK[-1]) == count)\n" +"STACK.extend(STACK.pop()[:-count-1:-1])" + +#: ../../library/dis.rst:1051 +msgid "" +"Implements assignment with a starred target: Unpacks an iterable in " +"``STACK[-1]`` into individual values, where the total number of values can " +"be smaller than the number of items in the iterable: one of the new values " +"will be a list of all leftover items." +msgstr "" + +#: ../../library/dis.rst:1056 +msgid "The number of values before and after the list value is limited to 255." +msgstr "" + +#: ../../library/dis.rst:1058 +msgid "" +"The number of values before the list value is encoded in the argument of the " +"opcode. The number of values after the list if any is encoded using an " +"``EXTENDED_ARG``. As a consequence, the argument can be seen as a two bytes " +"values where the low byte of *counts* is the number of values before the " +"list value, the high byte of *counts* the number of values after it." +msgstr "" + +#: ../../library/dis.rst:1064 +msgid "" +"The extracted values are put onto the stack right-to-left, i.e. ``a, *b, c = " +"d`` will be stored after execution as ``STACK.extend((a, b, c))``." +msgstr "" + +#: ../../library/dis.rst:1072 +msgid "" +"obj = STACK.pop()\n" +"value = STACK.pop()\n" +"obj.name = value" +msgstr "" +"obj = STACK.pop()\n" +"value = STACK.pop()\n" +"obj.name = value" + +#: ../../library/dis.rst:1076 +msgid "" +"where *namei* is the index of name in :attr:`~codeobject.co_names` of the :" +"ref:`code object `." +msgstr "" + +#: ../../library/dis.rst:1083 +msgid "" +"obj = STACK.pop()\n" +"del obj.name" +msgstr "" +"obj = STACK.pop()\n" +"del obj.name" + +#: ../../library/dis.rst:1086 +msgid "" +"where *namei* is the index of name into :attr:`~codeobject.co_names` of the :" +"ref:`code object `." +msgstr "" + +#: ../../library/dis.rst:1092 +msgid "Works as :opcode:`STORE_NAME`, but stores the name as a global." +msgstr "" + +#: ../../library/dis.rst:1097 +msgid "Works as :opcode:`DELETE_NAME`, but deletes a global name." +msgstr "" + +#: ../../library/dis.rst:1102 +msgid "Pushes ``co_consts[consti]`` onto the stack." +msgstr "" + +#: ../../library/dis.rst:1107 +msgid "" +"Pushes the integer ``i`` onto the stack. ``i`` must be in ``range(256)``" +msgstr "" + +#: ../../library/dis.rst:1115 +msgid "" +"Pushes the value associated with ``co_names[namei]`` onto the stack. The " +"name is looked up within the locals, then the globals, then the builtins." +msgstr "" + +#: ../../library/dis.rst:1121 +msgid "" +"Pushes a reference to the locals dictionary onto the stack. This is used to " +"prepare namespace dictionaries for :opcode:`LOAD_FROM_DICT_OR_DEREF` and :" +"opcode:`LOAD_FROM_DICT_OR_GLOBALS`." +msgstr "" + +#: ../../library/dis.rst:1130 +msgid "" +"Pops a mapping off the stack and looks up the value for ``co_names[namei]``. " +"If the name is not found there, looks it up in the globals and then the " +"builtins, similar to :opcode:`LOAD_GLOBAL`. This is used for loading global " +"variables in :ref:`annotation scopes ` within class " +"bodies." +msgstr "" + +#: ../../library/dis.rst:1141 +msgid "" +"Constructs a new :class:`~string.templatelib.Template` instance from a tuple " +"of strings and a tuple of interpolations and pushes the resulting object " +"onto the stack::" +msgstr "" + +#: ../../library/dis.rst:1145 +msgid "" +"interpolations = STACK.pop()\n" +"strings = STACK.pop()\n" +"STACK.append(_build_template(strings, interpolations))" +msgstr "" +"interpolations = STACK.pop()\n" +"strings = STACK.pop()\n" +"STACK.append(_build_template(strings, interpolations))" + +#: ../../library/dis.rst:1154 +msgid "" +"Constructs a new :class:`~string.templatelib.Interpolation` instance from a " +"value and its source expression and pushes the resulting object onto the " +"stack." +msgstr "" + +#: ../../library/dis.rst:1158 +msgid "" +"If no conversion or format specification is present, ``format`` is set to " +"``2``." +msgstr "" + +#: ../../library/dis.rst:1161 +msgid "" +"If the low bit of ``format`` is set, it indicates that the interpolation " +"contains a format specification." +msgstr "" + +#: ../../library/dis.rst:1164 +msgid "" +"If ``format >> 2`` is non-zero, it indicates that the interpolation contains " +"a conversion. The value of ``format >> 2`` is the conversion type (``0`` for " +"no conversion, ``1`` for ``!s``, ``2`` for ``!r``, and ``3`` for ``!a``)::" +msgstr "" + +#: ../../library/dis.rst:1169 +msgid "" +"conversion = format >> 2\n" +"if format & 1:\n" +" format_spec = STACK.pop()\n" +"else:\n" +" format_spec = None\n" +"expression = STACK.pop()\n" +"value = STACK.pop()\n" +"STACK.append(_build_interpolation(value, expression, conversion, " +"format_spec))" +msgstr "" +"conversion = format >> 2\n" +"if format & 1:\n" +" format_spec = STACK.pop()\n" +"else:\n" +" format_spec = None\n" +"expression = STACK.pop()\n" +"value = STACK.pop()\n" +"STACK.append(_build_interpolation(value, expression, conversion, " +"format_spec))" + +#: ../../library/dis.rst:1183 +msgid "" +"Creates a tuple consuming *count* items from the stack, and pushes the " +"resulting tuple onto the stack::" +msgstr "" + +#: ../../library/dis.rst:1186 +msgid "" +"if count == 0:\n" +" value = ()\n" +"else:\n" +" value = tuple(STACK[-count:])\n" +" STACK = STACK[:-count]\n" +"\n" +"STACK.append(value)" +msgstr "" +"if count == 0:\n" +" value = ()\n" +"else:\n" +" value = tuple(STACK[-count:])\n" +" STACK = STACK[:-count]\n" +"\n" +"STACK.append(value)" + +#: ../../library/dis.rst:1197 +msgid "Works as :opcode:`BUILD_TUPLE`, but creates a list." +msgstr "" + +#: ../../library/dis.rst:1202 +msgid "Works as :opcode:`BUILD_TUPLE`, but creates a set." +msgstr "" + +#: ../../library/dis.rst:1207 +msgid "" +"Pushes a new dictionary object onto the stack. Pops ``2 * count`` items so " +"that the dictionary holds *count* entries: ``{..., STACK[-4]: STACK[-3], " +"STACK[-2]: STACK[-1]}``." +msgstr "" + +#: ../../library/dis.rst:1211 +msgid "" +"The dictionary is created from stack items instead of creating an empty " +"dictionary pre-sized to hold *count* items." +msgstr "" + +#: ../../library/dis.rst:1218 +msgid "" +"Concatenates *count* strings from the stack and pushes the resulting string " +"onto the stack." +msgstr "" + +#: ../../library/dis.rst:1228 +msgid "" +"seq = STACK.pop()\n" +"list.extend(STACK[-i], seq)" +msgstr "" +"seq = STACK.pop()\n" +"list.extend(STACK[-i], seq)" + +#: ../../library/dis.rst:1231 +msgid "Used to build lists." +msgstr "" + +#: ../../library/dis.rst:1240 +msgid "" +"seq = STACK.pop()\n" +"set.update(STACK[-i], seq)" +msgstr "" +"seq = STACK.pop()\n" +"set.update(STACK[-i], seq)" + +#: ../../library/dis.rst:1243 +msgid "Used to build sets." +msgstr "" + +#: ../../library/dis.rst:1252 +msgid "" +"map = STACK.pop()\n" +"dict.update(STACK[-i], map)" +msgstr "" +"map = STACK.pop()\n" +"dict.update(STACK[-i], map)" + +#: ../../library/dis.rst:1255 +msgid "Used to build dicts." +msgstr "" + +#: ../../library/dis.rst:1262 +msgid "Like :opcode:`DICT_UPDATE` but raises an exception for duplicate keys." +msgstr "" + +#: ../../library/dis.rst:1269 +msgid "" +"If the low bit of ``namei`` is not set, this replaces ``STACK[-1]`` with " +"``getattr(STACK[-1], co_names[namei>>1])``." +msgstr "" + +#: ../../library/dis.rst:1272 +msgid "" +"If the low bit of ``namei`` is set, this will attempt to load a method named " +"``co_names[namei>>1]`` from the ``STACK[-1]`` object. ``STACK[-1]`` is " +"popped. This bytecode distinguishes two cases: if ``STACK[-1]`` has a method " +"with the correct name, the bytecode pushes the unbound method and " +"``STACK[-1]``. ``STACK[-1]`` will be used as the first argument (``self``) " +"by :opcode:`CALL` or :opcode:`CALL_KW` when calling the unbound method. " +"Otherwise, ``NULL`` and the object returned by the attribute lookup are " +"pushed." +msgstr "" + +#: ../../library/dis.rst:1281 +msgid "" +"If the low bit of ``namei`` is set, then a ``NULL`` or ``self`` is pushed to " +"the stack before the attribute or unbound method respectively." +msgstr "" + +#: ../../library/dis.rst:1288 +msgid "" +"This opcode implements :func:`super`, both in its zero-argument and two-" +"argument forms (e.g. ``super().method()``, ``super().attr`` and ``super(cls, " +"self).method()``, ``super(cls, self).attr``)." +msgstr "" + +#: ../../library/dis.rst:1292 +msgid "It pops three values from the stack (from top of stack down):" +msgstr "" + +#: ../../library/dis.rst:1294 +msgid "``self``: the first argument to the current method" +msgstr "" + +#: ../../library/dis.rst:1295 +msgid "``cls``: the class within which the current method was defined" +msgstr "" + +#: ../../library/dis.rst:1296 +msgid "the global ``super``" +msgstr "" + +#: ../../library/dis.rst:1298 +msgid "" +"With respect to its argument, it works similarly to :opcode:`LOAD_ATTR`, " +"except that ``namei`` is shifted left by 2 bits instead of 1." +msgstr "" + +#: ../../library/dis.rst:1301 +msgid "" +"The low bit of ``namei`` signals to attempt a method load, as with :opcode:" +"`LOAD_ATTR`, which results in pushing ``NULL`` and the loaded method. When " +"it is unset a single value is pushed to the stack." +msgstr "" + +#: ../../library/dis.rst:1305 +msgid "" +"The second-low bit of ``namei``, if set, means that this was a two-argument " +"call to :func:`super` (unset means zero-argument)." +msgstr "" + +#: ../../library/dis.rst:1313 +msgid "" +"Performs a Boolean operation. The operation name can be found in " +"``cmp_op[opname >> 5]``. If the fifth-lowest bit of ``opname`` is set " +"(``opname & 16``), the result should be coerced to ``bool``." +msgstr "" + +#: ../../library/dis.rst:1317 +msgid "" +"The fifth-lowest bit of the oparg now indicates a forced conversion to :" +"class:`bool`." +msgstr "" + +#: ../../library/dis.rst:1324 +msgid "Performs ``is`` comparison, or ``is not`` if ``invert`` is 1." +msgstr "" + +#: ../../library/dis.rst:1331 +msgid "Performs ``in`` comparison, or ``not in`` if ``invert`` is 1." +msgstr "" + +#: ../../library/dis.rst:1338 +msgid "" +"Imports the module ``co_names[namei]``. ``STACK[-1]`` and ``STACK[-2]`` are " +"popped and provide the *fromlist* and *level* arguments of :func:" +"`__import__`. The module object is pushed onto the stack. The current " +"namespace is not affected: for a proper import statement, a subsequent :" +"opcode:`STORE_FAST` instruction modifies the namespace." +msgstr "" + +#: ../../library/dis.rst:1346 +msgid "" +"Loads the attribute ``co_names[namei]`` from the module found in " +"``STACK[-1]``. The resulting object is pushed onto the stack, to be " +"subsequently stored by a :opcode:`STORE_FAST` instruction." +msgstr "" + +#: ../../library/dis.rst:1353 +msgid "Increments bytecode counter by *delta*." +msgstr "" + +#: ../../library/dis.rst:1358 +msgid "Decrements bytecode counter by *delta*. Checks for interrupts." +msgstr "" + +#: ../../library/dis.rst:1365 +msgid "Decrements bytecode counter by *delta*. Does not check for interrupts." +msgstr "" + +#: ../../library/dis.rst:1372 +msgid "" +"If ``STACK[-1]`` is true, increments the bytecode counter by *delta*. " +"``STACK[-1]`` is popped." +msgstr "" + +#: ../../library/dis.rst:1375 ../../library/dis.rst:1391 +msgid "" +"The oparg is now a relative delta rather than an absolute target. This " +"opcode is a pseudo-instruction, replaced in final bytecode by the directed " +"versions (forward/backward)." +msgstr "" + +#: ../../library/dis.rst:1380 ../../library/dis.rst:1396 +#: ../../library/dis.rst:1409 ../../library/dis.rst:1420 +msgid "This is no longer a pseudo-instruction." +msgstr "" + +#: ../../library/dis.rst:1388 +msgid "" +"If ``STACK[-1]`` is false, increments the bytecode counter by *delta*. " +"``STACK[-1]`` is popped." +msgstr "" + +#: ../../library/dis.rst:1404 +msgid "" +"If ``STACK[-1]`` is not ``None``, increments the bytecode counter by " +"*delta*. ``STACK[-1]`` is popped." +msgstr "" + +#: ../../library/dis.rst:1415 +msgid "" +"If ``STACK[-1]`` is ``None``, increments the bytecode counter by *delta*. " +"``STACK[-1]`` is popped." +msgstr "" + +#: ../../library/dis.rst:1425 +msgid "" +"``STACK[-1]`` is an :term:`iterator`. Call its :meth:`~iterator.__next__` " +"method. If this yields a new value, push it on the stack (leaving the " +"iterator below it). If the iterator indicates it is exhausted then the byte " +"code counter is incremented by *delta*." +msgstr "" + +#: ../../library/dis.rst:1430 +msgid "Up until 3.11 the iterator was popped when it was exhausted." +msgstr "" + +#: ../../library/dis.rst:1435 +msgid "Loads the global named ``co_names[namei>>1]`` onto the stack." +msgstr "" + +#: ../../library/dis.rst:1437 +msgid "" +"If the low bit of ``namei`` is set, then a ``NULL`` is pushed to the stack " +"before the global variable." +msgstr "" + +#: ../../library/dis.rst:1443 +msgid "" +"Pushes a reference to the local ``co_varnames[var_num]`` onto the stack." +msgstr "" + +#: ../../library/dis.rst:1445 +msgid "" +"This opcode is now only used in situations where the local variable is " +"guaranteed to be initialized. It cannot raise :exc:`UnboundLocalError`." +msgstr "" + +#: ../../library/dis.rst:1451 +msgid "" +"Pushes a borrowed reference to the local ``co_varnames[var_num]`` onto the " +"stack." +msgstr "" + +#: ../../library/dis.rst:1458 +msgid "" +"Pushes references to ``co_varnames[var_nums >> 4]`` and " +"``co_varnames[var_nums & 15]`` onto the stack." +msgstr "" + +#: ../../library/dis.rst:1466 +msgid "" +"Pushes borrowed references to ``co_varnames[var_nums >> 4]`` and " +"``co_varnames[var_nums & 15]`` onto the stack." +msgstr "" + +#: ../../library/dis.rst:1473 +msgid "" +"Pushes a reference to the local ``co_varnames[var_num]`` onto the stack, " +"raising an :exc:`UnboundLocalError` if the local variable has not been " +"initialized." +msgstr "" + +#: ../../library/dis.rst:1481 +msgid "" +"Pushes a reference to the local ``co_varnames[var_num]`` onto the stack (or " +"pushes ``NULL`` onto the stack if the local variable has not been " +"initialized) and sets ``co_varnames[var_num]`` to ``NULL``." +msgstr "" + +#: ../../library/dis.rst:1489 +msgid "Stores ``STACK.pop()`` into the local ``co_varnames[var_num]``." +msgstr "" + +#: ../../library/dis.rst:1493 +msgid "" +"Stores ``STACK[-1]`` into ``co_varnames[var_nums >> 4]`` and ``STACK[-2]`` " +"into ``co_varnames[var_nums & 15]``." +msgstr "" + +#: ../../library/dis.rst:1500 +msgid "" +"Stores ``STACK.pop()`` into the local ``co_varnames[var_nums >> 4]`` and " +"pushes a reference to the local ``co_varnames[var_nums & 15]`` onto the " +"stack." +msgstr "" + +#: ../../library/dis.rst:1508 +msgid "Deletes local ``co_varnames[var_num]``." +msgstr "" + +#: ../../library/dis.rst:1513 +msgid "" +"Creates a new cell in slot ``i``. If that slot is nonempty then that value " +"is stored into the new cell." +msgstr "" + +#: ../../library/dis.rst:1521 +msgid "" +"Loads the cell contained in slot ``i`` of the \"fast locals\" storage. " +"Pushes a reference to the object the cell contains on the stack." +msgstr "" + +#: ../../library/dis.rst:1524 ../../library/dis.rst:1546 +#: ../../library/dis.rst:1557 +msgid "" +"``i`` is no longer offset by the length of :attr:`~codeobject.co_varnames`." +msgstr "" + +#: ../../library/dis.rst:1530 +msgid "" +"Pops a mapping off the stack and looks up the name associated with slot " +"``i`` of the \"fast locals\" storage in this mapping. If the name is not " +"found there, loads it from the cell contained in slot ``i``, similar to :" +"opcode:`LOAD_DEREF`. This is used for loading :term:`closure variables " +"` in class bodies (which previously used :opcode:`!" +"LOAD_CLASSDEREF`) and in :ref:`annotation scopes ` within " +"class bodies." +msgstr "" + +#: ../../library/dis.rst:1543 +msgid "" +"Stores ``STACK.pop()`` into the cell contained in slot ``i`` of the \"fast " +"locals\" storage." +msgstr "" + +#: ../../library/dis.rst:1552 +msgid "" +"Empties the cell contained in slot ``i`` of the \"fast locals\" storage. " +"Used by the :keyword:`del` statement." +msgstr "" + +#: ../../library/dis.rst:1563 +msgid "" +"Copies the ``n`` :term:`free (closure) variables ` from " +"the closure into the frame. Removes the need for special code on the " +"caller's side when calling closures." +msgstr "" + +#: ../../library/dis.rst:1572 +msgid "" +"Raises an exception using one of the 3 forms of the ``raise`` statement, " +"depending on the value of *argc*:" +msgstr "" + +#: ../../library/dis.rst:1575 +msgid "0: ``raise`` (re-raise previous exception)" +msgstr "" + +#: ../../library/dis.rst:1576 +msgid "" +"1: ``raise STACK[-1]`` (raise exception instance or type at ``STACK[-1]``)" +msgstr "" + +#: ../../library/dis.rst:1577 +msgid "" +"2: ``raise STACK[-2] from STACK[-1]`` (raise exception instance or type at " +"``STACK[-2]`` with ``__cause__`` set to ``STACK[-1]``)" +msgstr "" + +#: ../../library/dis.rst:1583 +msgid "" +"Calls a callable object with the number of arguments specified by ``argc``. " +"On the stack are (in ascending order):" +msgstr "" + +#: ../../library/dis.rst:1586 ../../library/dis.rst:1610 +msgid "The callable" +msgstr "" + +#: ../../library/dis.rst:1587 ../../library/dis.rst:1611 +msgid "``self`` or ``NULL``" +msgstr "``self`` 或 ``NULL``" + +#: ../../library/dis.rst:1588 ../../library/dis.rst:1612 +msgid "The remaining positional arguments" +msgstr "剩餘的位置引數" + +#: ../../library/dis.rst:1590 +msgid "``argc`` is the total of the positional arguments, excluding ``self``." +msgstr "" + +#: ../../library/dis.rst:1592 +msgid "" +"``CALL`` pops all arguments and the callable object off the stack, calls the " +"callable object with those arguments, and pushes the return value returned " +"by the callable object." +msgstr "" + +#: ../../library/dis.rst:1598 +msgid "The callable now always appears at the same position on the stack." +msgstr "" + +#: ../../library/dis.rst:1601 +msgid "Calls with keyword arguments are now handled by :opcode:`CALL_KW`." +msgstr "" + +#: ../../library/dis.rst:1607 +msgid "" +"Calls a callable object with the number of arguments specified by ``argc``, " +"including one or more named arguments. On the stack are (in ascending order):" +msgstr "" + +#: ../../library/dis.rst:1613 +msgid "The named arguments" +msgstr "" + +#: ../../library/dis.rst:1614 +msgid "A :class:`tuple` of keyword argument names" +msgstr "" + +#: ../../library/dis.rst:1616 +msgid "" +"``argc`` is the total of the positional and named arguments, excluding " +"``self``. The length of the tuple of keyword argument names is the number of " +"named arguments." +msgstr "" + +#: ../../library/dis.rst:1619 +msgid "" +"``CALL_KW`` pops all arguments, the keyword names, and the callable object " +"off the stack, calls the callable object with those arguments, and pushes " +"the return value returned by the callable object." +msgstr "" + +#: ../../library/dis.rst:1628 +msgid "" +"Calls a callable object with variable set of positional and keyword " +"arguments. If the lowest bit of *flags* is set, the top of the stack " +"contains a mapping object containing additional keyword arguments. Before " +"the callable is called, the mapping object and iterable object are each " +"\"unpacked\" and their contents passed in as keyword and positional " +"arguments respectively. ``CALL_FUNCTION_EX`` pops all arguments and the " +"callable object off the stack, calls the callable object with those " +"arguments, and pushes the return value returned by the callable object." +msgstr "" + +#: ../../library/dis.rst:1643 +msgid "" +"Pushes a ``NULL`` to the stack. Used in the call sequence to match the " +"``NULL`` pushed by :opcode:`!LOAD_METHOD` for non-method calls." +msgstr "" + +#: ../../library/dis.rst:1652 +msgid "" +"Pushes a new function object on the stack built from the code object at " +"``STACK[-1]``." +msgstr "" + +#: ../../library/dis.rst:1654 +msgid "Flag value ``0x04`` is a tuple of strings instead of dictionary" +msgstr "" + +#: ../../library/dis.rst:1657 +msgid "Qualified name at ``STACK[-1]`` was removed." +msgstr "" + +#: ../../library/dis.rst:1660 +msgid "" +"Extra function attributes on the stack, signaled by oparg flags, were " +"removed. They now use :opcode:`SET_FUNCTION_ATTRIBUTE`." +msgstr "" + +#: ../../library/dis.rst:1667 +msgid "" +"Sets an attribute on a function object. Expects the function at " +"``STACK[-1]`` and the attribute value to set at ``STACK[-2]``; consumes both " +"and leaves the function at ``STACK[-1]``. The flag determines which " +"attribute to set:" +msgstr "" + +#: ../../library/dis.rst:1671 +msgid "" +"``0x01`` a tuple of default values for positional-only and positional-or-" +"keyword parameters in positional order" +msgstr "" + +#: ../../library/dis.rst:1673 +msgid "``0x02`` a dictionary of keyword-only parameters' default values" +msgstr "" + +#: ../../library/dis.rst:1674 +msgid "``0x04`` a tuple of strings containing parameters' annotations" +msgstr "" + +#: ../../library/dis.rst:1675 +msgid "``0x08`` a tuple containing cells for free variables, making a closure" +msgstr "" + +#: ../../library/dis.rst:1676 +msgid "``0x10`` the :term:`annotate function` for the function object" +msgstr "" + +#: ../../library/dis.rst:1680 +msgid "" +"Added ``0x10`` to indicate the annotate function for the function object." +msgstr "" + +#: ../../library/dis.rst:1688 +msgid "" +"Pushes a slice object on the stack. *argc* must be 2 or 3. If it is 2, " +"implements::" +msgstr "" + +#: ../../library/dis.rst:1690 +msgid "" +"end = STACK.pop()\n" +"start = STACK.pop()\n" +"STACK.append(slice(start, end))" +msgstr "" + +#: ../../library/dis.rst:1694 +msgid "if it is 3, implements::" +msgstr "" + +#: ../../library/dis.rst:1696 +msgid "" +"step = STACK.pop()\n" +"end = STACK.pop()\n" +"start = STACK.pop()\n" +"STACK.append(slice(start, end, step))" +msgstr "" +"step = STACK.pop()\n" +"end = STACK.pop()\n" +"start = STACK.pop()\n" +"STACK.append(slice(start, end, step))" + +#: ../../library/dis.rst:1701 +msgid "See the :func:`slice` built-in function for more information." +msgstr "更多資訊請參閱內建函式 :func:`slice`。" + +#: ../../library/dis.rst:1706 +msgid "" +"Prefixes any opcode which has an argument too big to fit into the default " +"one byte. *ext* holds an additional byte which act as higher bits in the " +"argument. For each opcode, at most three prefixal ``EXTENDED_ARG`` are " +"allowed, forming an argument from two-byte to four-byte." +msgstr "" + +#: ../../library/dis.rst:1714 +msgid "Convert value to a string, depending on ``oparg``::" +msgstr "" + +#: ../../library/dis.rst:1716 +msgid "" +"value = STACK.pop()\n" +"result = func(value)\n" +"STACK.append(result)" +msgstr "" +"value = STACK.pop()\n" +"result = func(value)\n" +"STACK.append(result)" + +#: ../../library/dis.rst:1720 +msgid "``oparg == 1``: call :func:`str` on *value*" +msgstr "``oparg == 1``：對 *value* 呼叫 :func:`str`" + +#: ../../library/dis.rst:1721 +msgid "``oparg == 2``: call :func:`repr` on *value*" +msgstr "``oparg == 2``：對 *value* 呼叫 :func:`repr`" +#: ../../library/dis.rst:1722 +msgid "``oparg == 3``: call :func:`ascii` on *value*" +msgstr "``oparg == 3``：對 *value* 呼叫 :func:`ascii`" + +#: ../../library/dis.rst:1724 ../../library/dis.rst:1737 +#: ../../library/dis.rst:1750 +msgid "Used for implementing formatted string literals (f-strings)." +msgstr "" + +#: ../../library/dis.rst:1731 +msgid "Formats the value on top of stack::" +msgstr "" + +#: ../../library/dis.rst:1733 +msgid "" +"value = STACK.pop()\n" +"result = value.__format__(\"\")\n" +"STACK.append(result)" +msgstr "" +"value = STACK.pop()\n" +"result = value.__format__(\"\")\n" +"STACK.append(result)" + +#: ../../library/dis.rst:1743 +msgid "Formats the given value with the given format spec::" +msgstr "" + +#: ../../library/dis.rst:1745 +msgid "" +"spec = STACK.pop()\n" +"value = STACK.pop()\n" +"result = value.__format__(spec)\n" +"STACK.append(result)" +msgstr "" +"spec = STACK.pop()\n" +"value = STACK.pop()\n" +"result = value.__format__(spec)\n" +"STACK.append(result)" + +#: ../../library/dis.rst:1757 +msgid "" +"``STACK[-1]`` is a tuple of keyword attribute names, ``STACK[-2]`` is the " +"class being matched against, and ``STACK[-3]`` is the match subject. " +"*count* is the number of positional sub-patterns." +msgstr "" + +#: ../../library/dis.rst:1761 +msgid "" +"Pop ``STACK[-1]``, ``STACK[-2]``, and ``STACK[-3]``. If ``STACK[-3]`` is an " +"instance of ``STACK[-2]`` and has the positional and keyword attributes " +"required by *count* and ``STACK[-1]``, push a tuple of extracted attributes. " +"Otherwise, push ``None``." +msgstr "" + +#: ../../library/dis.rst:1775 +msgid "A no-op. Performs internal tracing, debugging and optimization checks." +msgstr "" + +#: ../../library/dis.rst:1777 +msgid "" +"The ``context`` operand consists of two parts. The lowest two bits indicate " +"where the ``RESUME`` occurs:" +msgstr "" + +#: ../../library/dis.rst:1780 +msgid "" +"``0`` The start of a function, which is neither a generator, coroutine nor " +"an async generator" +msgstr "" + +#: ../../library/dis.rst:1782 +msgid "``1`` After a ``yield`` expression" +msgstr "" + +#: ../../library/dis.rst:1783 +msgid "``2`` After a ``yield from`` expression" +msgstr "" + +#: ../../library/dis.rst:1784 +msgid "``3`` After an ``await`` expression" +msgstr "" + +#: ../../library/dis.rst:1786 +msgid "" +"The next bit is ``1`` if the RESUME is at except-depth ``1``, and ``0`` " +"otherwise." +msgstr "" + +#: ../../library/dis.rst:1791 +msgid "The oparg value changed to include information about except-depth" +msgstr "" + +#: ../../library/dis.rst:1797 +msgid "" +"Create a generator, coroutine, or async generator from the current frame. " +"Used as first opcode of in code object for the above mentioned callables. " +"Clear the current frame and return the newly created generator." +msgstr "" + +#: ../../library/dis.rst:1806 +msgid "" +"Equivalent to ``STACK[-1] = STACK[-2].send(STACK[-1])``. Used in ``yield " +"from`` and ``await`` statements." +msgstr "" + +#: ../../library/dis.rst:1809 +msgid "" +"If the call raises :exc:`StopIteration`, pop the top value from the stack, " +"push the exception's ``value`` attribute, and increment the bytecode counter " +"by *delta*." +msgstr "" + +#: ../../library/dis.rst:1818 +msgid "" +"This is not really an opcode. It identifies the dividing line between " +"opcodes in the range [0,255] which don't use their argument and those that " +"do (``< HAVE_ARGUMENT`` and ``>= HAVE_ARGUMENT``, respectively)." +msgstr "" + +#: ../../library/dis.rst:1822 +msgid "" +"If your application uses pseudo instructions or specialized instructions, " +"use the :data:`hasarg` collection instead." +msgstr "" + +#: ../../library/dis.rst:1825 +msgid "" +"Now every instruction has an argument, but opcodes ``< HAVE_ARGUMENT`` " +"ignore it. Before, only opcodes ``>= HAVE_ARGUMENT`` had an argument." +msgstr "" + +#: ../../library/dis.rst:1829 +msgid "" +"Pseudo instructions were added to the :mod:`dis` module, and for them it is " +"not true that comparison with ``HAVE_ARGUMENT`` indicates whether they use " +"their arg." +msgstr "" + +#: ../../library/dis.rst:1834 +msgid "Use :data:`hasarg` instead." +msgstr "改用 :data:`hasarg`。" + +#: ../../library/dis.rst:1839 +msgid "" +"Calls an intrinsic function with one argument. Passes ``STACK[-1]`` as the " +"argument and sets ``STACK[-1]`` to the result. Used to implement " +"functionality that is not performance critical." +msgstr "" + +#: ../../library/dis.rst:1843 ../../library/dis.rst:1897 +msgid "The operand determines which intrinsic function is called:" +msgstr "" + +#: ../../library/dis.rst:1846 ../../library/dis.rst:1900 +msgid "Operand" +msgstr "運算元" + +#: ../../library/dis.rst:1846 ../../library/dis.rst:1900 +msgid "Description" +msgstr "描述" + +#: ../../library/dis.rst:1848 +msgid "``INTRINSIC_1_INVALID``" +msgstr "``INTRINSIC_1_INVALID``" + +#: ../../library/dis.rst:1848 ../../library/dis.rst:1902 +msgid "Not valid" +msgstr "" + +#: ../../library/dis.rst:1850 +msgid "``INTRINSIC_PRINT``" +msgstr "``INTRINSIC_PRINT``" + +#: ../../library/dis.rst:1850 +msgid "Prints the argument to standard out. Used in the REPL." +msgstr "" + +#: ../../library/dis.rst:1853 +msgid "``INTRINSIC_IMPORT_STAR``" +msgstr "``INTRINSIC_IMPORT_STAR``" + +#: ../../library/dis.rst:1853 +msgid "Performs ``import *`` for the named module." +msgstr "" + +#: ../../library/dis.rst:1856 +msgid "``INTRINSIC_STOPITERATION_ERROR``" +msgstr "``INTRINSIC_STOPITERATION_ERROR``" + +#: ../../library/dis.rst:1856 +msgid "Extracts the return value from a ``StopIteration`` exception." +msgstr "" + +#: ../../library/dis.rst:1859 +msgid "``INTRINSIC_ASYNC_GEN_WRAP``" +msgstr "``INTRINSIC_ASYNC_GEN_WRAP``" + +#: ../../library/dis.rst:1859 +msgid "Wraps an async generator value" +msgstr "" + +#: ../../library/dis.rst:1861 +msgid "``INTRINSIC_UNARY_POSITIVE``" +msgstr "``INTRINSIC_UNARY_POSITIVE``" + +#: ../../library/dis.rst:1861 +msgid "Performs the unary ``+`` operation" +msgstr "" + +#: ../../library/dis.rst:1864 +msgid "``INTRINSIC_LIST_TO_TUPLE``" +msgstr "``INTRINSIC_LIST_TO_TUPLE``" + +#: ../../library/dis.rst:1864 +msgid "Converts a list to a tuple" +msgstr "" + +#: ../../library/dis.rst:1866 +msgid "``INTRINSIC_TYPEVAR``" +msgstr "``INTRINSIC_TYPEVAR``" + +#: ../../library/dis.rst:1866 +msgid "Creates a :class:`typing.TypeVar`" +msgstr "建立一個 :class:`typing.TypeVar`" + +#: ../../library/dis.rst:1868 +msgid "``INTRINSIC_PARAMSPEC``" +msgstr "``INTRINSIC_PARAMSPEC``" + +#: ../../library/dis.rst:1868 +msgid "Creates a :class:`typing.ParamSpec`" +msgstr "建立一個 :class:`typing.ParamSpec`" + +#: ../../library/dis.rst:1871 +msgid "``INTRINSIC_TYPEVARTUPLE``" +msgstr "``INTRINSIC_TYPEVARTUPLE``" + +#: ../../library/dis.rst:1871 +msgid "Creates a :class:`typing.TypeVarTuple`" +msgstr "建立一個 :class:`typing.TypeVarTuple`" + +#: ../../library/dis.rst:1874 +msgid "``INTRINSIC_SUBSCRIPT_GENERIC``" +msgstr "``INTRINSIC_SUBSCRIPT_GENERIC``" + +#: ../../library/dis.rst:1874 +msgid "Returns :class:`typing.Generic` subscripted with the argument" +msgstr "" + +#: ../../library/dis.rst:1877 +msgid "``INTRINSIC_TYPEALIAS``" +msgstr "``INTRINSIC_TYPEALIAS``" + +#: ../../library/dis.rst:1877 +msgid "" +"Creates a :class:`typing.TypeAliasType`; used in the :keyword:`type` " +"statement. The argument is a tuple of the type alias's name, type " +"parameters, and value." +msgstr "" + +#: ../../library/dis.rst:1889 +msgid "" +"Calls an intrinsic function with two arguments. Used to implement " +"functionality that is not performance critical::" +msgstr "" + +#: ../../library/dis.rst:1892 +msgid "" +"arg2 = STACK.pop()\n" +"arg1 = STACK.pop()\n" +"result = intrinsic2(arg1, arg2)\n" +"STACK.append(result)" +msgstr "" +"arg2 = STACK.pop()\n" +"arg1 = STACK.pop()\n" +"result = intrinsic2(arg1, arg2)\n" +"STACK.append(result)" + +#: ../../library/dis.rst:1902 +msgid "``INTRINSIC_2_INVALID``" +msgstr "``INTRINSIC_2_INVALID``" + +#: ../../library/dis.rst:1904 +msgid "``INTRINSIC_PREP_RERAISE_STAR``" +msgstr "``INTRINSIC_PREP_RERAISE_STAR``" + +#: ../../library/dis.rst:1904 +msgid "Calculates the :exc:`ExceptionGroup` to raise from a ``try-except*``." +msgstr "" + +#: ../../library/dis.rst:1908 +msgid "``INTRINSIC_TYPEVAR_WITH_BOUND``" +msgstr "``INTRINSIC_TYPEVAR_WITH_BOUND``" + +#: ../../library/dis.rst:1908 +msgid "Creates a :class:`typing.TypeVar` with a bound." +msgstr "" + +#: ../../library/dis.rst:1911 +msgid "``INTRINSIC_TYPEVAR_WITH_CONSTRAINTS``" +msgstr "``INTRINSIC_TYPEVAR_WITH_CONSTRAINTS``" + +#: ../../library/dis.rst:1911 +msgid "Creates a :class:`typing.TypeVar` with constraints." +msgstr "" + +#: ../../library/dis.rst:1915 +msgid "``INTRINSIC_SET_FUNCTION_TYPE_PARAMS``" +msgstr "``INTRINSIC_SET_FUNCTION_TYPE_PARAMS``" + +#: ../../library/dis.rst:1915 +msgid "Sets the ``__type_params__`` attribute of a function." +msgstr "設定函式的 ``__type_params__`` 屬性。" + +#: ../../library/dis.rst:1924 +msgid "" +"Performs special method lookup on ``STACK[-1]``. If ``type(STACK[-1])." +"__xxx__`` is a method, leave ``type(STACK[-1]).__xxx__; STACK[-1]`` on the " +"stack. If ``type(STACK[-1]).__xxx__`` is not a method, leave ``STACK[-1]." +"__xxx__; NULL`` on the stack." +msgstr "" + +#: ../../library/dis.rst:1933 +msgid "**Pseudo-instructions**" +msgstr "" + +#: ../../library/dis.rst:1935 +msgid "" +"These opcodes do not appear in Python bytecode. They are used by the " +"compiler but are replaced by real opcodes or removed before bytecode is " +"generated." +msgstr "" + +#: ../../library/dis.rst:1940 +msgid "" +"Set up an exception handler for the following code block. If an exception " +"occurs, the value stack level is restored to its current state and control " +"is transferred to the exception handler at ``target``." +msgstr "" + +#: ../../library/dis.rst:1947 +msgid "" +"Like ``SETUP_FINALLY``, but in case of an exception also pushes the last " +"instruction (``lasti``) to the stack so that ``RERAISE`` can restore it. If " +"an exception occurs, the value stack level and the last instruction on the " +"frame are restored to their current state, and control is transferred to the " +"exception handler at ``target``." +msgstr "" + +#: ../../library/dis.rst:1956 +msgid "" +"Like ``SETUP_CLEANUP``, but in case of an exception one more item is popped " +"from the stack before control is transferred to the exception handler at " +"``target``." +msgstr "" + +#: ../../library/dis.rst:1960 +msgid "" +"This variant is used in :keyword:`with` and :keyword:`async with` " +"constructs, which push the return value of the context manager's :meth:" +"`~object.__enter__` or :meth:`~object.__aenter__` to the stack." +msgstr "" + +#: ../../library/dis.rst:1967 +msgid "" +"Marks the end of the code block associated with the last ``SETUP_FINALLY``, " +"``SETUP_CLEANUP`` or ``SETUP_WITH``." +msgstr "" + +#: ../../library/dis.rst:1973 +msgid "" +"Works as :opcode:`LOAD_CONST`, but is more efficient for immortal objects." +msgstr "" + +#: ../../library/dis.rst:1979 +msgid "" +"Undirected relative jump instructions which are replaced by their directed " +"(forward/backward) counterparts by the assembler." +msgstr "" + +#: ../../library/dis.rst:1985 +msgid "" +"Conditional jumps which do not impact the stack. Replaced by the sequence " +"``COPY 1``, ``TO_BOOL``, ``POP_JUMP_IF_TRUE/FALSE``." +msgstr "" + +#: ../../library/dis.rst:1990 +msgid "" +"Pushes a reference to the cell contained in slot ``i`` of the \"fast " +"locals\" storage." +msgstr "" + +#: ../../library/dis.rst:1993 +msgid "" +"Note that ``LOAD_CLOSURE`` is replaced with ``LOAD_FAST`` in the assembler." +msgstr "" + +#: ../../library/dis.rst:1995 +msgid "This opcode is now a pseudo-instruction." +msgstr "" + +#: ../../library/dis.rst:2002 +msgid "Opcode collections" +msgstr "" + +#: ../../library/dis.rst:2004 +msgid "" +"These collections are provided for automatic introspection of bytecode " +"instructions:" +msgstr "" + +#: ../../library/dis.rst:2007 +msgid "" +"The collections now contain pseudo instructions and instrumented " +"instructions as well. These are opcodes with values ``>= MIN_PSEUDO_OPCODE`` " +"and ``>= MIN_INSTRUMENTED_OPCODE``." +msgstr "" + +#: ../../library/dis.rst:2014 +msgid "Sequence of operation names, indexable using the bytecode." +msgstr "" + +#: ../../library/dis.rst:2019 +msgid "Dictionary mapping operation names to bytecodes." +msgstr "" + +#: ../../library/dis.rst:2024 +msgid "Sequence of all compare operation names." +msgstr "" + +#: ../../library/dis.rst:2029 +msgid "Sequence of bytecodes that use their argument." +msgstr "" + +#: ../../library/dis.rst:2036 +msgid "Sequence of bytecodes that access a constant." +msgstr "" + +#: ../../library/dis.rst:2041 +msgid "" +"Sequence of bytecodes that access a :term:`free (closure) variable `. 'free' in this context refers to names in the current scope that " +"are referenced by inner scopes or names in outer scopes that are referenced " +"from this scope. It does *not* include references to global or builtin " +"scopes." +msgstr "" + +#: ../../library/dis.rst:2049 +msgid "Sequence of bytecodes that access an attribute by name." +msgstr "" + +#: ../../library/dis.rst:2054 +msgid "Sequence of bytecodes that have a jump target. All jumps are relative." +msgstr "" + +#: ../../library/dis.rst:2061 +msgid "Sequence of bytecodes that access a local variable." +msgstr "" + +#: ../../library/dis.rst:2066 +msgid "Sequence of bytecodes of Boolean operations." +msgstr "" + +#: ../../library/dis.rst:2070 +msgid "Sequence of bytecodes that set an exception handler." +msgstr "" + +#: ../../library/dis.rst:2077 +msgid "Sequence of bytecodes that have a relative jump target." +msgstr "" + +#: ../../library/dis.rst:2079 +msgid "All jumps are now relative. Use :data:`hasjump`." +msgstr "" + +#: ../../library/dis.rst:2085 +msgid "Sequence of bytecodes that have an absolute jump target." +msgstr "" + +#: ../../library/dis.rst:2087 +msgid "All jumps are now relative. This list is empty." +msgstr "" + +#: ../../library/dis.rst:1686 +msgid "built-in function" +msgstr "built-in function（內建函式）" + +#: ../../library/dis.rst:1686 +msgid "slice" +msgstr "slice（切片）" diff --git a/library/distribution.po b/library/distribution.po index ec4ebd2237..4d0ee1ee3c 100644 --- a/library/distribution.po +++ b/library/distribution.po @@ -1,34 +1,34 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Leon H., 2017 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2018-06-26 18:54+0800\n" -"PO-Revision-Date: 2018-05-23 14:43+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/distribution.rst:3 -msgid "Software Packaging and Distribution" -msgstr "軟體封裝與發布" - -#: ../../library/distribution.rst:5 -msgid "" -"These libraries help you with publishing and installing Python software. " -"While these modules are designed to work in conjunction with the `Python " -"Package Index `__, they can also be used with a local " -"index server, or without any index server at all." -msgstr "" -"這些函式庫可以幫助你發布和安裝 Python 軟體。雖然這些模組設計是為了與 `Python " -"套件索引 (Python Package Index) `__ 結合使用，但它們也可以" -"搭配本地索引伺服器，甚至可以在沒有任何索引伺服器的情況下使用。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Leon H., 2017 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2018-06-26 18:54+0800\n" +"PO-Revision-Date: 2018-05-23 14:43+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/distribution.rst:3 +msgid "Software Packaging and Distribution" +msgstr "軟體封裝與發布" + +#: ../../library/distribution.rst:5 +msgid "" +"These libraries help you with publishing and installing Python software. " +"While these modules are designed to work in conjunction with the `Python " +"Package Index `__, they can also be used with a local " +"index server, or without any index server at all." +msgstr "" +"這些函式庫可以幫助你發布和安裝 Python 軟體。雖然這些模組設計是為了與 `Python " +"套件索引 (Python Package Index) `__ 結合使用，但它們也可以" +"搭配本地索引伺服器，甚至可以在沒有任何索引伺服器的情況下使用。" diff --git a/library/distutils.po b/library/distutils.po index c73c27804e..1d6e3cf650 100644 --- a/library/distutils.po +++ b/library/distutils.po @@ -1,41 +1,41 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -#, fuzzy -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-11-18 00:15+0000\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" -"tw)\n" -"Language: zh_TW\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=UTF-8\n" -"Content-Transfer-Encoding: 8bit\n" - -#: ../../library/distutils.rst:2 -msgid ":mod:`!distutils` --- Building and installing Python modules" -msgstr ":mod:`!distutils` --- 建置與安裝 Python 模組" - -#: ../../library/distutils.rst:10 -msgid "" -"This module is no longer part of the Python standard library. It was :ref:" -"`removed in Python 3.12 ` after being " -"deprecated in Python 3.10. The removal was decided in :pep:`632`, which has " -"`migration advice `_." -msgstr "" -"這個模組已不再是 Python 標準函式庫的一部分。它在 Python 3.10 中被棄用，並\\ :" -"ref:`已在 Python 3.12 中被移除 `。它的移除是" -"在 :pep:`632` 中決定的，該 PEP 附有\\ `遷移建議 `_。" - -#: ../../library/distutils.rst:16 -msgid "" -"The last version of Python that provided the :mod:`!distutils` module was " -"`Python 3.11 `_." -msgstr "" -"最後提供 :mod:`!distutils` 模組的 Python 版本是 `Python 3.11 `_。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-11-18 00:15+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" +"tw)\n" +"Language: zh_TW\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../library/distutils.rst:2 +msgid ":mod:`!distutils` --- Building and installing Python modules" +msgstr ":mod:`!distutils` --- 建置與安裝 Python 模組" + +#: ../../library/distutils.rst:10 +msgid "" +"This module is no longer part of the Python standard library. It was :ref:" +"`removed in Python 3.12 ` after being " +"deprecated in Python 3.10. The removal was decided in :pep:`632`, which has " +"`migration advice `_." +msgstr "" +"這個模組已不再是 Python 標準函式庫的一部分。它在 Python 3.10 中被棄用，並\\ :" +"ref:`已在 Python 3.12 中被移除 `。它的移除是" +"在 :pep:`632` 中決定的，該 PEP 附有\\ `遷移建議 `_。" + +#: ../../library/distutils.rst:16 +msgid "" +"The last version of Python that provided the :mod:`!distutils` module was " +"`Python 3.11 `_." +msgstr "" +"最後提供 :mod:`!distutils` 模組的 Python 版本是 `Python 3.11 `_。" diff --git a/library/doctest.po b/library/doctest.po index 4b4508a442..028d047d32 100644 --- a/library/doctest.po +++ b/library/doctest.po @@ -1,2909 +1,2909 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: 2018-05-23 14:43+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/doctest.rst:2 -msgid ":mod:`!doctest` --- Test interactive Python examples" -msgstr ":mod:`!doctest` --- 測試互動式 Python 範例" - -#: ../../library/doctest.rst:12 -msgid "**Source code:** :source:`Lib/doctest.py`" -msgstr "**原始碼：**\\ :source:`Lib/doctest.py`" - -#: ../../library/doctest.rst:16 -msgid "" -"The :mod:`doctest` module searches for pieces of text that look like " -"interactive Python sessions, and then executes those sessions to verify that " -"they work exactly as shown. There are several common ways to use doctest:" -msgstr "" - -#: ../../library/doctest.rst:20 -msgid "" -"To check that a module's docstrings are up-to-date by verifying that all " -"interactive examples still work as documented." -msgstr "" - -#: ../../library/doctest.rst:23 -msgid "" -"To perform regression testing by verifying that interactive examples from a " -"test file or a test object work as expected." -msgstr "透過驗證測試檔案或測試物件中的互動式範例是否按預期運作來執行迴歸測試。" - -#: ../../library/doctest.rst:26 -msgid "" -"To write tutorial documentation for a package, liberally illustrated with " -"input-output examples. Depending on whether the examples or the expository " -"text are emphasized, this has the flavor of \"literate testing\" or " -"\"executable documentation\"." -msgstr "" - -#: ../../library/doctest.rst:31 -msgid "Here's a complete but small example module::" -msgstr "" - -#: ../../library/doctest.rst:33 -msgid "" -"\"\"\"\n" -"This is the \"example\" module.\n" -"\n" -"The example module supplies one function, factorial(). For example,\n" -"\n" -">>> factorial(5)\n" -"120\n" -"\"\"\"\n" -"\n" -"def factorial(n):\n" -" \"\"\"Return the factorial of n, an exact integer >= 0.\n" -"\n" -" >>> [factorial(n) for n in range(6)]\n" -" [1, 1, 2, 6, 24, 120]\n" -" >>> factorial(30)\n" -" 265252859812191058636308480000000\n" -" >>> factorial(-1)\n" -" Traceback (most recent call last):\n" -" ...\n" -" ValueError: n must be >= 0\n" -"\n" -" Factorials of floats are OK, but the float must be an exact integer:\n" -" >>> factorial(30.1)\n" -" Traceback (most recent call last):\n" -" ...\n" -" ValueError: n must be exact integer\n" -" >>> factorial(30.0)\n" -" 265252859812191058636308480000000\n" -"\n" -" It must also not be ridiculously large:\n" -" >>> factorial(1e100)\n" -" Traceback (most recent call last):\n" -" ...\n" -" OverflowError: n too large\n" -" \"\"\"\n" -"\n" -" import math\n" -" if not n >= 0:\n" -" raise ValueError(\"n must be >= 0\")\n" -" if math.floor(n) != n:\n" -" raise ValueError(\"n must be exact integer\")\n" -" if n+1 == n: # catch a value like 1e300\n" -" raise OverflowError(\"n too large\")\n" -" result = 1\n" -" factor = 2\n" -" while factor <= n:\n" -" result *= factor\n" -" factor += 1\n" -" return result\n" -"\n" -"\n" -"if __name__ == \"__main__\":\n" -" import doctest\n" -" doctest.testmod()" -msgstr "" - -#: ../../library/doctest.rst:88 -msgid "" -"If you run :file:`example.py` directly from the command line, :mod:`doctest` " -"works its magic:" -msgstr "" - -#: ../../library/doctest.rst:91 -msgid "" -"$ python example.py\n" -"$" -msgstr "" -"$ python example.py\n" -"$" - -#: ../../library/doctest.rst:96 -msgid "" -"There's no output! That's normal, and it means all the examples worked. " -"Pass ``-v`` to the script, and :mod:`doctest` prints a detailed log of what " -"it's trying, and prints a summary at the end:" -msgstr "" - -#: ../../library/doctest.rst:100 -msgid "" -"$ python example.py -v\n" -"Trying:\n" -" factorial(5)\n" -"Expecting:\n" -" 120\n" -"ok\n" -"Trying:\n" -" [factorial(n) for n in range(6)]\n" -"Expecting:\n" -" [1, 1, 2, 6, 24, 120]\n" -"ok" -msgstr "" -"$ python example.py -v\n" -"Trying:\n" -" factorial(5)\n" -"Expecting:\n" -" 120\n" -"ok\n" -"Trying:\n" -" [factorial(n) for n in range(6)]\n" -"Expecting:\n" -" [1, 1, 2, 6, 24, 120]\n" -"ok" - -#: ../../library/doctest.rst:114 -msgid "And so on, eventually ending with:" -msgstr "" - -#: ../../library/doctest.rst:116 -msgid "" -"Trying:\n" -" factorial(1e100)\n" -"Expecting:\n" -" Traceback (most recent call last):\n" -" ...\n" -" OverflowError: n too large\n" -"ok\n" -"2 items passed all tests:\n" -" 1 test in __main__\n" -" 6 tests in __main__.factorial\n" -"7 tests in 2 items.\n" -"7 passed.\n" -"Test passed.\n" -"$" -msgstr "" -"Trying:\n" -" factorial(1e100)\n" -"Expecting:\n" -" Traceback (most recent call last):\n" -" ...\n" -" OverflowError: n too large\n" -"ok\n" -"2 items passed all tests:\n" -" 1 test in __main__\n" -" 6 tests in __main__.factorial\n" -"7 tests in 2 items.\n" -"7 passed.\n" -"Test passed.\n" -"$" - -#: ../../library/doctest.rst:133 -msgid "" -"That's all you need to know to start making productive use " -"of :mod:`doctest`! Jump in. The following sections provide full details. " -"Note that there are many examples of doctests in the standard Python test " -"suite and libraries. Especially useful examples can be found in the standard " -"test file :file:`Lib/test/test_doctest/test_doctest.py`." -msgstr "" - -#: ../../library/doctest.rst:139 -msgid "" -"Output is colorized by default and can be :ref:`controlled using environment " -"variables `." -msgstr "" - -#: ../../library/doctest.rst:147 -msgid "Simple Usage: Checking Examples in Docstrings" -msgstr "" - -#: ../../library/doctest.rst:149 -msgid "" -"The simplest way to start using doctest (but not necessarily the way you'll " -"continue to do it) is to end each module :mod:`!M` with::" -msgstr "" - -#: ../../library/doctest.rst:152 -msgid "" -"if __name__ == \"__main__\":\n" -" import doctest\n" -" doctest.testmod()" -msgstr "" -"if __name__ == \"__main__\":\n" -" import doctest\n" -" doctest.testmod()" - -#: ../../library/doctest.rst:156 -msgid ":mod:`!doctest` then examines docstrings in module :mod:`!M`." -msgstr "" - -#: ../../library/doctest.rst:158 -msgid "" -"Running the module as a script causes the examples in the docstrings to get " -"executed and verified::" -msgstr "" - -#: ../../library/doctest.rst:161 -msgid "python M.py" -msgstr "python M.py" - -#: ../../library/doctest.rst:163 -msgid "" -"This won't display anything unless an example fails, in which case the " -"failing example(s) and the cause(s) of the failure(s) are printed to stdout, " -"and the final line of output is ``***Test Failed*** N failures.``, where *N* " -"is the number of examples that failed." -msgstr "" - -#: ../../library/doctest.rst:168 -msgid "Run it with the ``-v`` switch instead::" -msgstr "" - -#: ../../library/doctest.rst:170 -msgid "python M.py -v" -msgstr "python M.py -v" - -#: ../../library/doctest.rst:172 -msgid "" -"and a detailed report of all examples tried is printed to standard output, " -"along with assorted summaries at the end." -msgstr "" - -#: ../../library/doctest.rst:175 -msgid "" -"You can force verbose mode by passing ``verbose=True`` to :func:`testmod`, " -"or prohibit it by passing ``verbose=False``. In either of those " -"cases, :data:`sys.argv` is not examined by :func:`testmod` (so passing ``-" -"v`` or not has no effect)." -msgstr "" - -#: ../../library/doctest.rst:180 -msgid "" -"There is also a command line shortcut for running :func:`testmod`, see " -"section :ref:`doctest-cli`." -msgstr "" - -#: ../../library/doctest.rst:183 -msgid "" -"For more information on :func:`testmod`, see section :ref:`doctest-basic-" -"api`." -msgstr "" - -#: ../../library/doctest.rst:189 -msgid "Simple Usage: Checking Examples in a Text File" -msgstr "" - -#: ../../library/doctest.rst:191 -msgid "" -"Another simple application of doctest is testing interactive examples in a " -"text file. This can be done with the :func:`testfile` function::" -msgstr "" - -#: ../../library/doctest.rst:194 -msgid "" -"import doctest\n" -"doctest.testfile(\"example.txt\")" -msgstr "" -"import doctest\n" -"doctest.testfile(\"example.txt\")" - -#: ../../library/doctest.rst:197 -msgid "" -"That short script executes and verifies any interactive Python examples " -"contained in the file :file:`example.txt`. The file content is treated as " -"if it were a single giant docstring; the file doesn't need to contain a " -"Python program! For example, perhaps :file:`example.txt` contains this:" -msgstr "" - -#: ../../library/doctest.rst:202 -msgid "" -"The ``example`` module\n" -"======================\n" -"\n" -"Using ``factorial``\n" -"-------------------\n" -"\n" -"This is an example text file in reStructuredText format. First import\n" -"``factorial`` from the ``example`` module:\n" -"\n" -" >>> from example import factorial\n" -"\n" -"Now use it:\n" -"\n" -" >>> factorial(6)\n" -" 120" -msgstr "" -"The ``example`` module\n" -"======================\n" -"\n" -"Using ``factorial``\n" -"-------------------\n" -"\n" -"This is an example text file in reStructuredText format. First import\n" -"``factorial`` from the ``example`` module:\n" -"\n" -" >>> from example import factorial\n" -"\n" -"Now use it:\n" -"\n" -" >>> factorial(6)\n" -" 120" - -#: ../../library/doctest.rst:220 -msgid "" -"Running ``doctest.testfile(\"example.txt\")`` then finds the error in this " -"documentation::" -msgstr "" - -#: ../../library/doctest.rst:223 -msgid "" -"File \"./example.txt\", line 14, in example.txt\n" -"Failed example:\n" -" factorial(6)\n" -"Expected:\n" -" 120\n" -"Got:\n" -" 720" -msgstr "" -"File \"./example.txt\", line 14, in example.txt\n" -"Failed example:\n" -" factorial(6)\n" -"Expected:\n" -" 120\n" -"Got:\n" -" 720" - -#: ../../library/doctest.rst:231 -msgid "" -"As with :func:`testmod`, :func:`testfile` won't display anything unless an " -"example fails. If an example does fail, then the failing example(s) and the " -"cause(s) of the failure(s) are printed to stdout, using the same format " -"as :func:`!testmod`." -msgstr "" - -#: ../../library/doctest.rst:236 -msgid "" -"By default, :func:`testfile` looks for files in the calling module's " -"directory. See section :ref:`doctest-basic-api` for a description of the " -"optional arguments that can be used to tell it to look for files in other " -"locations." -msgstr "" - -#: ../../library/doctest.rst:240 -msgid "" -"Like :func:`testmod`, :func:`testfile`'s verbosity can be set with the ``-" -"v`` command-line switch or with the optional keyword argument *verbose*." -msgstr "" - -#: ../../library/doctest.rst:244 -msgid "" -"There is also a command line shortcut for running :func:`testfile`, see " -"section :ref:`doctest-cli`." -msgstr "" - -#: ../../library/doctest.rst:247 -msgid "" -"For more information on :func:`testfile`, see section :ref:`doctest-basic-" -"api`." -msgstr "" - -#: ../../library/doctest.rst:253 -msgid "Command-line Usage" -msgstr "命令列用法" - -#: ../../library/doctest.rst:255 -msgid "" -"The :mod:`doctest` module can be invoked as a script from the command line:" -msgstr "可以從命令列以腳本方式叫用 :mod:`doctest` 模組：" - -#: ../../library/doctest.rst:257 -msgid "python -m doctest [-v] [-o OPTION] [-f] file [file ...]" -msgstr "python -m doctest [-v] [-o OPTION] [-f] file [file ...]" - -#: ../../library/doctest.rst:265 -msgid "" -"Detailed report of all examples tried is printed to standard output, along " -"with assorted summaries at the end::" -msgstr "" - -#: ../../library/doctest.rst:268 -msgid "python -m doctest -v example.py" -msgstr "python -m doctest -v example.py" - -#: ../../library/doctest.rst:270 -msgid "" -"This will import :file:`example.py` as a standalone module and " -"run :func:`testmod` on it. Note that this may not work correctly if the file " -"is part of a package and imports other submodules from that package." -msgstr "" - -#: ../../library/doctest.rst:274 -msgid "" -"If the file name does not end with :file:`.py`, :mod:`!doctest` infers that " -"it must be run with :func:`testfile` instead::" -msgstr "" - -#: ../../library/doctest.rst:277 -msgid "python -m doctest -v example.txt" -msgstr "python -m doctest -v example.txt" - -#: ../../library/doctest.rst:281 -msgid "" -"Option flags control various aspects of doctest's behavior, see " -"section :ref:`doctest-options`." -msgstr "" - -#: ../../library/doctest.rst:288 -msgid "This is shorthand for ``-o FAIL_FAST``." -msgstr "" - -#: ../../library/doctest.rst:296 -msgid "How It Works" -msgstr "運作方式" - -#: ../../library/doctest.rst:298 -msgid "" -"This section examines in detail how doctest works: which docstrings it looks " -"at, how it finds interactive examples, what execution context it uses, how " -"it handles exceptions, and how option flags can be used to control its " -"behavior. This is the information that you need to know to write doctest " -"examples; for information about actually running doctest on these examples, " -"see the following sections." -msgstr "" - -#: ../../library/doctest.rst:309 -msgid "Which Docstrings Are Examined?" -msgstr "" - -#: ../../library/doctest.rst:311 -msgid "" -"The module docstring, and all function, class and method docstrings are " -"searched. Objects imported into the module are not searched." -msgstr "" - -#: ../../library/doctest.rst:321 -msgid "" -"In addition, there are cases when you want tests to be part of a module but " -"not part of the help text, which requires that the tests not be included in " -"the docstring. Doctest looks for a module-level variable called ``__test__`` " -"and uses it to locate other tests. If ``M.__test__`` exists, it must be a " -"dict, and each entry maps a (string) name to a function object, class " -"object, or string. Function and class object docstrings found from " -"``M.__test__`` are searched, and strings are treated as if they were " -"docstrings. In output, a key ``K`` in ``M.__test__`` appears with name " -"``M.__test__.K``." -msgstr "" - -#: ../../library/doctest.rst:330 -msgid "For example, place this block of code at the top of :file:`example.py`:" -msgstr "" - -#: ../../library/doctest.rst:332 -msgid "" -"__test__ = {\n" -" 'numbers': \"\"\"\n" -">>> factorial(6)\n" -"720\n" -"\n" -">>> [factorial(n) for n in range(6)]\n" -"[1, 1, 2, 6, 24, 120]\n" -"\"\"\"\n" -"}" -msgstr "" -"__test__ = {\n" -" 'numbers': \"\"\"\n" -">>> factorial(6)\n" -"720\n" -"\n" -">>> [factorial(n) for n in range(6)]\n" -"[1, 1, 2, 6, 24, 120]\n" -"\"\"\"\n" -"}" - -#: ../../library/doctest.rst:344 -msgid "" -"The value of ``example.__test__[\"numbers\"]`` will be treated as a " -"docstring and all the tests inside it will be run. It is important to note " -"that the value can be mapped to a function, class object, or module; if " -"so, :mod:`!doctest` searches them recursively for docstrings, which are then " -"scanned for tests." -msgstr "" - -#: ../../library/doctest.rst:350 -msgid "" -"Any classes found are recursively searched similarly, to test docstrings in " -"their contained methods and nested classes." -msgstr "" - -#: ../../library/doctest.rst:355 -msgid "" -"``doctest`` can only automatically discover classes and functions that are " -"defined at the module level or inside other classes." -msgstr "" - -#: ../../library/doctest.rst:358 -msgid "" -"Since nested classes and functions only exist when an outer function is " -"called, they cannot be discovered. Define them outside to make them visible." -msgstr "" - -#: ../../library/doctest.rst:364 -msgid "How are Docstring Examples Recognized?" -msgstr "" - -#: ../../library/doctest.rst:366 -msgid "" -"In most cases a copy-and-paste of an interactive console session works fine, " -"but doctest isn't trying to do an exact emulation of any specific Python " -"shell." -msgstr "" - -#: ../../library/doctest.rst:371 -msgid "" -">>> # comments are ignored\n" -">>> x = 12\n" -">>> x\n" -"12\n" -">>> if x == 13:\n" -"... print(\"yes\")\n" -"... else:\n" -"... print(\"no\")\n" -"... print(\"NO\")\n" -"... print(\"NO!!!\")\n" -"...\n" -"no\n" -"NO\n" -"NO!!!\n" -">>>" -msgstr "" -">>> # 註解會被忽略\n" -">>> x = 12\n" -">>> x\n" -"12\n" -">>> if x == 13:\n" -"... print(\"yes\")\n" -"... else:\n" -"... print(\"no\")\n" -"... print(\"NO\")\n" -"... print(\"NO!!!\")\n" -"...\n" -"no\n" -"NO\n" -"NO!!!\n" -">>>" - -#: ../../library/doctest.rst:391 -msgid "" -"Any expected output must immediately follow the final ``'>>> '`` or ``'... " -"'`` line containing the code, and the expected output (if any) extends to " -"the next ``'>>> '`` or all-whitespace line." -msgstr "" - -#: ../../library/doctest.rst:395 -msgid "The fine print:" -msgstr "" - -#: ../../library/doctest.rst:397 -msgid "" -"Expected output cannot contain an all-whitespace line, since such a line is " -"taken to signal the end of expected output. If expected output does contain " -"a blank line, put ```` in your doctest example each place a blank " -"line is expected." -msgstr "" - -#: ../../library/doctest.rst:402 -msgid "" -"All hard tab characters are expanded to spaces, using 8-column tab stops. " -"Tabs in output generated by the tested code are not modified. Because any " -"hard tabs in the sample output *are* expanded, this means that if the code " -"output includes hard tabs, the only way the doctest can pass is if " -"the :const:`NORMALIZE_WHITESPACE` option or :ref:`directive ` is in effect. Alternatively, the test can be rewritten to " -"capture the output and compare it to an expected value as part of the test. " -"This handling of tabs in the source was arrived at through trial and error, " -"and has proven to be the least error prone way of handling them. It is " -"possible to use a different algorithm for handling tabs by writing a " -"custom :class:`DocTestParser` class." -msgstr "" - -#: ../../library/doctest.rst:414 -msgid "" -"Output to stdout is captured, but not output to stderr (exception tracebacks " -"are captured via a different means)." -msgstr "" - -#: ../../library/doctest.rst:417 -msgid "" -"If you continue a line via backslashing in an interactive session, or for " -"any other reason use a backslash, you should use a raw docstring, which will " -"preserve your backslashes exactly as you type them::" -msgstr "" - -#: ../../library/doctest.rst:421 -msgid "" -">>> def f(x):\n" -"... r'''Backslashes in a raw docstring: m\\n'''\n" -"...\n" -">>> print(f.__doc__)\n" -"Backslashes in a raw docstring: m\\n" -msgstr "" - -#: ../../library/doctest.rst:427 -msgid "" -"Otherwise, the backslash will be interpreted as part of the string. For " -"example, the ``\\n`` above would be interpreted as a newline character. " -"Alternatively, you can double each backslash in the doctest version (and not " -"use a raw string)::" -msgstr "" - -#: ../../library/doctest.rst:431 -msgid "" -">>> def f(x):\n" -"... '''Backslashes in a raw docstring: m\\\\n'''\n" -"...\n" -">>> print(f.__doc__)\n" -"Backslashes in a raw docstring: m\\n" -msgstr "" - -#: ../../library/doctest.rst:437 -msgid "The starting column doesn't matter::" -msgstr "" - -#: ../../library/doctest.rst:439 -msgid "" -">>> assert \"Easy!\"\n" -" >>> import math\n" -" >>> math.floor(1.9)\n" -" 1" -msgstr "" -">>> assert \"Easy!\"\n" -" >>> import math\n" -" >>> math.floor(1.9)\n" -" 1" - -#: ../../library/doctest.rst:444 -msgid "" -"and as many leading whitespace characters are stripped from the expected " -"output as appeared in the initial ``'>>> '`` line that started the example." -msgstr "" - -#: ../../library/doctest.rst:451 -msgid "What's the Execution Context?" -msgstr "" - -#: ../../library/doctest.rst:453 -msgid "" -"By default, each time :mod:`doctest` finds a docstring to test, it uses a " -"*shallow copy* of :mod:`!M`'s globals, so that running tests doesn't change " -"the module's real globals, and so that one test in :mod:`!M` can't leave " -"behind crumbs that accidentally allow another test to work. This means " -"examples can freely use any names defined at top-level in :mod:`!M`, and " -"names defined earlier in the docstring being run. Examples cannot see names " -"defined in other docstrings." -msgstr "" - -#: ../../library/doctest.rst:461 -msgid "" -"You can force use of your own dict as the execution context by passing " -"``globs=your_dict`` to :func:`testmod` or :func:`testfile` instead." -msgstr "" - -#: ../../library/doctest.rst:468 -msgid "What About Exceptions?" -msgstr "" - -#: ../../library/doctest.rst:470 -msgid "" -"No problem, provided that the traceback is the only output produced by the " -"example: just paste in the traceback. [#]_ Since tracebacks contain details " -"that are likely to change rapidly (for example, exact file paths and line " -"numbers), this is one case where doctest works hard to be flexible in what " -"it accepts." -msgstr "" - -#: ../../library/doctest.rst:476 -msgid "Simple example::" -msgstr "簡單範例： ::" - -#: ../../library/doctest.rst:478 -msgid "" -">>> [1, 2, 3].remove(42)\n" -"Traceback (most recent call last):\n" -" File \"\", line 1, in \n" -"ValueError: list.remove(x): x not in list" -msgstr "" -">>> [1, 2, 3].remove(42)\n" -"Traceback (most recent call last):\n" -" File \"\", line 1, in \n" -"ValueError: list.remove(x): x not in list" - -#: ../../library/doctest.rst:483 -msgid "" -"That doctest succeeds if :exc:`ValueError` is raised, with the " -"``list.remove(x): x not in list`` detail as shown." -msgstr "" - -#: ../../library/doctest.rst:486 -msgid "" -"The expected output for an exception must start with a traceback header, " -"which may be either of the following two lines, indented the same as the " -"first line of the example::" -msgstr "" - -#: ../../library/doctest.rst:490 -msgid "" -"Traceback (most recent call last):\n" -"Traceback (innermost last):" -msgstr "" -"Traceback (most recent call last):\n" -"Traceback (innermost last):" - -#: ../../library/doctest.rst:493 -msgid "" -"The traceback header is followed by an optional traceback stack, whose " -"contents are ignored by doctest. The traceback stack is typically omitted, " -"or copied verbatim from an interactive session." -msgstr "" - -#: ../../library/doctest.rst:497 -msgid "" -"The traceback stack is followed by the most interesting part: the line(s) " -"containing the exception type and detail. This is usually the last line of " -"a traceback, but can extend across multiple lines if the exception has a " -"multi-line detail::" -msgstr "" - -#: ../../library/doctest.rst:502 -msgid "" -">>> raise ValueError('multi\\n line\\ndetail')\n" -"Traceback (most recent call last):\n" -" File \"\", line 1, in \n" -"ValueError: multi\n" -" line\n" -"detail" -msgstr "" -">>> raise ValueError('multi\\n line\\ndetail')\n" -"Traceback (most recent call last):\n" -" File \"\", line 1, in \n" -"ValueError: multi\n" -" line\n" -"detail" - -#: ../../library/doctest.rst:509 -msgid "" -"The last three lines (starting with :exc:`ValueError`) are compared against " -"the exception's type and detail, and the rest are ignored." -msgstr "" - -#: ../../library/doctest.rst:512 -msgid "" -"Best practice is to omit the traceback stack, unless it adds significant " -"documentation value to the example. So the last example is probably better " -"as::" -msgstr "" - -#: ../../library/doctest.rst:515 -msgid "" -">>> raise ValueError('multi\\n line\\ndetail')\n" -"Traceback (most recent call last):\n" -" ...\n" -"ValueError: multi\n" -" line\n" -"detail" -msgstr "" -">>> raise ValueError('multi\\n line\\ndetail')\n" -"Traceback (most recent call last):\n" -" ...\n" -"ValueError: multi\n" -" line\n" -"detail" - -#: ../../library/doctest.rst:522 -msgid "" -"Note that tracebacks are treated very specially. In particular, in the " -"rewritten example, the use of ``...`` is independent of " -"doctest's :const:`ELLIPSIS` option. The ellipsis in that example could be " -"left out, or could just as well be three (or three hundred) commas or " -"digits, or an indented transcript of a Monty Python skit." -msgstr "" - -#: ../../library/doctest.rst:528 -msgid "Some details you should read once, but won't need to remember:" -msgstr "" - -#: ../../library/doctest.rst:530 -msgid "" -"Doctest can't guess whether your expected output came from an exception " -"traceback or from ordinary printing. So, e.g., an example that expects " -"``ValueError: 42 is prime`` will pass whether :exc:`ValueError` is actually " -"raised or if the example merely prints that traceback text. In practice, " -"ordinary output rarely begins with a traceback header line, so this doesn't " -"create real problems." -msgstr "" - -#: ../../library/doctest.rst:537 -msgid "" -"Each line of the traceback stack (if present) must be indented further than " -"the first line of the example, *or* start with a non-alphanumeric character. " -"The first line following the traceback header indented the same and starting " -"with an alphanumeric is taken to be the start of the exception detail. Of " -"course this does the right thing for genuine tracebacks." -msgstr "" - -#: ../../library/doctest.rst:543 -msgid "" -"When the :const:`IGNORE_EXCEPTION_DETAIL` doctest option is specified, " -"everything following the leftmost colon and any module information in the " -"exception name is ignored." -msgstr "" - -#: ../../library/doctest.rst:547 -msgid "" -"The interactive shell omits the traceback header line for " -"some :exc:`SyntaxError`\\ s. But doctest uses the traceback header line to " -"distinguish exceptions from non-exceptions. So in the rare case where you " -"need to test a :exc:`!SyntaxError` that omits the traceback header, you will " -"need to manually add the traceback header line to your test example." -msgstr "" - -#: ../../library/doctest.rst:555 -msgid "" -"For some exceptions, Python displays the position of the error using ``^`` " -"markers and tildes::" -msgstr "" - -#: ../../library/doctest.rst:558 -msgid "" -">>> 1 + None\n" -" File \"\", line 1\n" -" 1 + None\n" -" ~~^~~~~~\n" -"TypeError: unsupported operand type(s) for +: 'int' and 'NoneType'" -msgstr "" -">>> 1 + None\n" -" File \"\", line 1\n" -" 1 + None\n" -" ~~^~~~~~\n" -"TypeError: unsupported operand type(s) for +: 'int' and 'NoneType'" - -#: ../../library/doctest.rst:564 -msgid "" -"Since the lines showing the position of the error come before the exception " -"type and detail, they are not checked by doctest. For example, the " -"following test would pass, even though it puts the ``^`` marker in the wrong " -"location::" -msgstr "" - -#: ../../library/doctest.rst:568 -msgid "" -">>> 1 + None\n" -" File \"\", line 1\n" -" 1 + None\n" -" ^~~~~~~~\n" -"TypeError: unsupported operand type(s) for +: 'int' and 'NoneType'" -msgstr "" -">>> 1 + None\n" -" File \"\", line 1\n" -" 1 + None\n" -" ^~~~~~~~\n" -"TypeError: unsupported operand type(s) for +: 'int' and 'NoneType'" - -#: ../../library/doctest.rst:579 -msgid "Option Flags" -msgstr "可選旗標" - -#: ../../library/doctest.rst:581 -msgid "" -"A number of option flags control various aspects of doctest's behavior. " -"Symbolic names for the flags are supplied as module constants, which can " -"be :ref:`bitwise ORed ` together and passed to various functions. " -"The names can also be used in :ref:`doctest directives `, and may be passed to the doctest command line interface via " -"the ``-o`` option." -msgstr "" - -#: ../../library/doctest.rst:587 -msgid "" -"The first group of options define test semantics, controlling aspects of how " -"doctest decides whether actual output matches an example's expected output:" -msgstr "" - -#: ../../library/doctest.rst:593 -msgid "" -"By default, if an expected output block contains just ``1``, an actual " -"output block containing just ``1`` or just ``True`` is considered to be a " -"match, and similarly for ``0`` versus ``False``. " -"When :const:`DONT_ACCEPT_TRUE_FOR_1` is specified, neither substitution is " -"allowed. The default behavior caters to that Python changed the return type " -"of many functions from integer to boolean; doctests expecting \"little " -"integer\" output still work in these cases. This option will probably go " -"away, but not for several years." -msgstr "" - -#: ../../library/doctest.rst:605 -msgid "" -"By default, if an expected output block contains a line containing only the " -"string ````, then that line will match a blank line in the actual " -"output. Because a genuinely blank line delimits the expected output, this " -"is the only way to communicate that a blank line is expected. " -"When :const:`DONT_ACCEPT_BLANKLINE` is specified, this substitution is not " -"allowed." -msgstr "" - -#: ../../library/doctest.rst:614 -msgid "" -"When specified, all sequences of whitespace (blanks and newlines) are " -"treated as equal. Any sequence of whitespace within the expected output " -"will match any sequence of whitespace within the actual output. By default, " -"whitespace must match exactly. :const:`NORMALIZE_WHITESPACE` is especially " -"useful when a line of expected output is very long, and you want to wrap it " -"across multiple lines in your source." -msgstr "" - -#: ../../library/doctest.rst:625 -msgid "" -"When specified, an ellipsis marker (``...``) in the expected output can " -"match any substring in the actual output. This includes substrings that " -"span line boundaries, and empty substrings, so it's best to keep usage of " -"this simple. Complicated uses can lead to the same kinds of \"oops, it " -"matched too much!\" surprises that ``.*`` is prone to in regular expressions." -msgstr "" - -#: ../../library/doctest.rst:634 -msgid "" -"When specified, doctests expecting exceptions pass so long as an exception " -"of the expected type is raised, even if the details (message and fully " -"qualified exception name) don't match." -msgstr "" - -#: ../../library/doctest.rst:638 -msgid "" -"For example, an example expecting ``ValueError: 42`` will pass if the actual " -"exception raised is ``ValueError: 3*14``, but will fail if, say, " -"a :exc:`TypeError` is raised instead. It will also ignore any fully " -"qualified name included before the exception class, which can vary between " -"implementations and versions of Python and the code/libraries in use. Hence, " -"all three of these variations will work with the flag specified:" -msgstr "" - -#: ../../library/doctest.rst:646 -msgid "" -">>> raise Exception('message')\n" -"Traceback (most recent call last):\n" -"Exception: message\n" -"\n" -">>> raise Exception('message')\n" -"Traceback (most recent call last):\n" -"builtins.Exception: message\n" -"\n" -">>> raise Exception('message')\n" -"Traceback (most recent call last):\n" -"__main__.Exception: message" -msgstr "" -">>> raise Exception('message')\n" -"Traceback (most recent call last):\n" -"Exception: message\n" -"\n" -">>> raise Exception('message')\n" -"Traceback (most recent call last):\n" -"builtins.Exception: message\n" -"\n" -">>> raise Exception('message')\n" -"Traceback (most recent call last):\n" -"__main__.Exception: message" - -#: ../../library/doctest.rst:660 -msgid "" -"Note that :const:`ELLIPSIS` can also be used to ignore the details of the " -"exception message, but such a test may still fail based on whether the " -"module name is present or matches exactly." -msgstr "" - -#: ../../library/doctest.rst:664 -msgid "" -":const:`IGNORE_EXCEPTION_DETAIL` now also ignores any information relating " -"to the module containing the exception under test." -msgstr "" - -#: ../../library/doctest.rst:671 -msgid "" -"When specified, do not run the example at all. This can be useful in " -"contexts where doctest examples serve as both documentation and test cases, " -"and an example should be included for documentation purposes, but should not " -"be checked. E.g., the example's output might be random; or the example " -"might depend on resources which would be unavailable to the test driver." -msgstr "" - -#: ../../library/doctest.rst:677 -msgid "" -"The SKIP flag can also be used for temporarily \"commenting out\" examples." -msgstr "" - -#: ../../library/doctest.rst:682 -msgid "A bitmask or'ing together all the comparison flags above." -msgstr "" - -#: ../../library/doctest.rst:684 -msgid "The second group of options controls how test failures are reported:" -msgstr "" - -#: ../../library/doctest.rst:689 -msgid "" -"When specified, failures that involve multi-line expected and actual outputs " -"are displayed using a unified diff." -msgstr "" - -#: ../../library/doctest.rst:695 -msgid "" -"When specified, failures that involve multi-line expected and actual outputs " -"will be displayed using a context diff." -msgstr "" - -#: ../../library/doctest.rst:701 -msgid "" -"When specified, differences are computed by ``difflib.Differ``, using the " -"same algorithm as the popular :file:`ndiff.py` utility. This is the only " -"method that marks differences within lines as well as across lines. For " -"example, if a line of expected output contains digit ``1`` where actual " -"output contains letter ``l``, a line is inserted with a caret marking the " -"mismatching column positions." -msgstr "" - -#: ../../library/doctest.rst:710 -msgid "" -"When specified, display the first failing example in each doctest, but " -"suppress output for all remaining examples. This will prevent doctest from " -"reporting correct examples that break because of earlier failures; but it " -"might also hide incorrect examples that fail independently of the first " -"failure. When :const:`REPORT_ONLY_FIRST_FAILURE` is specified, the " -"remaining examples are still run, and still count towards the total number " -"of failures reported; only the output is suppressed." -msgstr "" - -#: ../../library/doctest.rst:721 -msgid "" -"When specified, exit after the first failing example and don't attempt to " -"run the remaining examples. Thus, the number of failures reported will be at " -"most 1. This flag may be useful during debugging, since examples after the " -"first failure won't even produce debugging output." -msgstr "" - -#: ../../library/doctest.rst:729 -msgid "A bitmask or'ing together all the reporting flags above." -msgstr "" - -#: ../../library/doctest.rst:732 -msgid "" -"There is also a way to register new option flag names, though this isn't " -"useful unless you intend to extend :mod:`doctest` internals via subclassing:" -msgstr "" - -#: ../../library/doctest.rst:738 -msgid "" -"Create a new option flag with a given name, and return the new flag's " -"integer value. :func:`register_optionflag` can be used when " -"subclassing :class:`OutputChecker` or :class:`DocTestRunner` to create new " -"options that are supported by your subclasses. :func:`register_optionflag` " -"should always be called using the following idiom::" -msgstr "" - -#: ../../library/doctest.rst:744 -msgid "MY_FLAG = register_optionflag('MY_FLAG')" -msgstr "MY_FLAG = register_optionflag('MY_FLAG')" - -#: ../../library/doctest.rst:754 -msgid "Directives" -msgstr "" - -#: ../../library/doctest.rst:756 -msgid "" -"Doctest directives may be used to modify the :ref:`option flags ` for an individual example. Doctest directives are special Python " -"comments following an example's source code:" -msgstr "" - -#: ../../library/doctest.rst:767 -msgid "" -"Whitespace is not allowed between the ``+`` or ``-`` and the directive " -"option name. The directive option name can be any of the option flag names " -"explained above." -msgstr "" - -#: ../../library/doctest.rst:771 -msgid "" -"An example's doctest directives modify doctest's behavior for that single " -"example. Use ``+`` to enable the named behavior, or ``-`` to disable it." -msgstr "" - -#: ../../library/doctest.rst:774 -msgid "For example, this test passes:" -msgstr "舉例來說，這個測試會通過：" - -#: ../../library/doctest.rst:776 -msgid "" -">>> print(list(range(20))) # doctest: +NORMALIZE_WHITESPACE\n" -"[0, 1, 2, 3, 4, 5, 6, 7, 8, 9,\n" -"10, 11, 12, 13, 14, 15, 16, 17, 18, 19]" -msgstr "" -">>> print(list(range(20))) # doctest: +NORMALIZE_WHITESPACE\n" -"[0, 1, 2, 3, 4, 5, 6, 7, 8, 9,\n" -"10, 11, 12, 13, 14, 15, 16, 17, 18, 19]" - -#: ../../library/doctest.rst:783 -msgid "" -"Without the directive it would fail, both because the actual output doesn't " -"have two blanks before the single-digit list elements, and because the " -"actual output is on a single line. This test also passes, and also requires " -"a directive to do so:" -msgstr "" - -#: ../../library/doctest.rst:788 -msgid "" -">>> print(list(range(20))) # doctest: +ELLIPSIS\n" -"[0, 1, ..., 18, 19]" -msgstr "" -">>> print(list(range(20))) # doctest: +ELLIPSIS\n" -"[0, 1, ..., 18, 19]" - -#: ../../library/doctest.rst:794 -msgid "" -"Multiple directives can be used on a single physical line, separated by " -"commas:" -msgstr "" - -#: ../../library/doctest.rst:797 -msgid "" -">>> print(list(range(20))) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE\n" -"[0, 1, ..., 18, 19]" -msgstr "" -">>> print(list(range(20))) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE\n" -"[0, 1, ..., 18, 19]" - -#: ../../library/doctest.rst:803 -msgid "" -"If multiple directive comments are used for a single example, then they are " -"combined:" -msgstr "" - -#: ../../library/doctest.rst:806 -msgid "" -">>> print(list(range(20))) # doctest: +ELLIPSIS\n" -"... # doctest: +NORMALIZE_WHITESPACE\n" -"[0, 1, ..., 18, 19]" -msgstr "" -">>> print(list(range(20))) # doctest: +ELLIPSIS\n" -"... # doctest: +NORMALIZE_WHITESPACE\n" -"[0, 1, ..., 18, 19]" - -#: ../../library/doctest.rst:813 -msgid "" -"As the previous example shows, you can add ``...`` lines to your example " -"containing only directives. This can be useful when an example is too long " -"for a directive to comfortably fit on the same line:" -msgstr "" - -#: ../../library/doctest.rst:817 -msgid "" -">>> print(list(range(5)) + list(range(10, 20)) + list(range(30, 40)))\n" -"... # doctest: +ELLIPSIS\n" -"[0, ..., 4, 10, ..., 19, 30, ..., 39]" -msgstr "" -">>> print(list(range(5)) + list(range(10, 20)) + list(range(30, 40)))\n" -"... # doctest: +ELLIPSIS\n" -"[0, ..., 4, 10, ..., 19, 30, ..., 39]" - -#: ../../library/doctest.rst:824 -msgid "" -"Note that since all options are disabled by default, and directives apply " -"only to the example they appear in, enabling options (via ``+`` in a " -"directive) is usually the only meaningful choice. However, option flags can " -"also be passed to functions that run doctests, establishing different " -"defaults. In such cases, disabling an option via ``-`` in a directive can " -"be useful." -msgstr "" - -#: ../../library/doctest.rst:834 -msgid "Warnings" -msgstr "警告" - -#: ../../library/doctest.rst:836 -msgid "" -":mod:`doctest` is serious about requiring exact matches in expected output. " -"If even a single character doesn't match, the test fails. This will " -"probably surprise you a few times, as you learn exactly what Python does and " -"doesn't guarantee about output. For example, when printing a set, Python " -"doesn't guarantee that the element is printed in any particular order, so a " -"test like ::" -msgstr "" - -#: ../../library/doctest.rst:842 -msgid "" -">>> foo()\n" -"{\"spam\", \"eggs\"}" -msgstr "" -">>> foo()\n" -"{\"spam\", \"eggs\"}" - -#: ../../library/doctest.rst:845 -msgid "is vulnerable! One workaround is to do ::" -msgstr "" - -#: ../../library/doctest.rst:847 -msgid "" -">>> foo() == {\"spam\", \"eggs\"}\n" -"True" -msgstr "" -">>> foo() == {\"spam\", \"eggs\"}\n" -"True" - -#: ../../library/doctest.rst:850 -msgid "instead. Another is to do ::" -msgstr "" - -#: ../../library/doctest.rst:852 -msgid "" -">>> d = sorted(foo())\n" -">>> d\n" -"['eggs', 'spam']" -msgstr "" -">>> d = sorted(foo())\n" -">>> d\n" -"['eggs', 'spam']" - -#: ../../library/doctest.rst:856 -msgid "There are others, but you get the idea." -msgstr "" - -#: ../../library/doctest.rst:858 -msgid "Another bad idea is to print things that embed an object address, like" -msgstr "" - -#: ../../library/doctest.rst:860 -msgid "" -">>> id(1.0) # certain to fail some of the time\n" -"7948648\n" -">>> class C: pass\n" -">>> C() # the default repr() for instances embeds an address\n" -"" -msgstr "" - -#: ../../library/doctest.rst:868 -msgid "" -"The :const:`ELLIPSIS` directive gives a nice approach for the last example:" -msgstr "" - -#: ../../library/doctest.rst:870 -msgid "" -">>> C() # doctest: +ELLIPSIS\n" -"" -msgstr "" -">>> C() # doctest: +ELLIPSIS\n" -"" - -#: ../../library/doctest.rst:876 -msgid "" -"Floating-point numbers are also subject to small output variations across " -"platforms, because Python defers to the platform C library for some floating-" -"point calculations, and C libraries vary widely in quality here. ::" -msgstr "" - -#: ../../library/doctest.rst:880 -msgid "" -">>> 1000**0.1 # risky\n" -"1.9952623149688797\n" -">>> round(1000**0.1, 9) # safer\n" -"1.995262315\n" -">>> print(f'{1000**0.1:.4f}') # much safer\n" -"1.9953" -msgstr "" -">>> 1000**0.1 # 有風險\n" -"1.9952623149688797\n" -">>> round(1000**0.1, 9) # 更安全\n" -"1.995262315\n" -">>> print(f'{1000**0.1:.4f}') # 更加安全\n" -"1.9953" - -#: ../../library/doctest.rst:887 -msgid "" -"Numbers of the form ``I/2.**J`` are safe across all platforms, and I often " -"contrive doctest examples to produce numbers of that form::" -msgstr "" - -#: ../../library/doctest.rst:890 -msgid "" -">>> 3./4 # utterly safe\n" -"0.75" -msgstr "" -">>> 3./4 # utterly safe\n" -"0.75" - -#: ../../library/doctest.rst:893 -msgid "" -"Simple fractions are also easier for people to understand, and that makes " -"for better documentation." -msgstr "" - -#: ../../library/doctest.rst:900 -msgid "Basic API" -msgstr "基礎 API" - -#: ../../library/doctest.rst:902 -msgid "" -"The functions :func:`testmod` and :func:`testfile` provide a simple " -"interface to doctest that should be sufficient for most basic uses. For a " -"less formal introduction to these two functions, see sections :ref:`doctest-" -"simple-testmod` and :ref:`doctest-simple-testfile`." -msgstr "" - -#: ../../library/doctest.rst:910 -msgid "" -"All arguments except *filename* are optional, and should be specified in " -"keyword form." -msgstr "" - -#: ../../library/doctest.rst:913 -msgid "" -"Test examples in the file named *filename*. Return ``(failure_count, " -"test_count)``." -msgstr "" - -#: ../../library/doctest.rst:916 -msgid "" -"Optional argument *module_relative* specifies how the filename should be " -"interpreted:" -msgstr "" - -#: ../../library/doctest.rst:919 -msgid "" -"If *module_relative* is ``True`` (the default), then *filename* specifies an " -"OS-independent module-relative path. By default, this path is relative to " -"the calling module's directory; but if the *package* argument is specified, " -"then it is relative to that package. To ensure OS-independence, *filename* " -"should use ``/`` characters to separate path segments, and may not be an " -"absolute path (i.e., it may not begin with ``/``)." -msgstr "" - -#: ../../library/doctest.rst:926 -msgid "" -"If *module_relative* is ``False``, then *filename* specifies an OS-specific " -"path. The path may be absolute or relative; relative paths are resolved " -"with respect to the current working directory." -msgstr "" - -#: ../../library/doctest.rst:930 -msgid "" -"Optional argument *name* gives the name of the test; by default, or if " -"``None``, ``os.path.basename(filename)`` is used." -msgstr "" - -#: ../../library/doctest.rst:933 -msgid "" -"Optional argument *package* is a Python package or the name of a Python " -"package whose directory should be used as the base directory for a module-" -"relative filename. If no package is specified, then the calling module's " -"directory is used as the base directory for module-relative filenames. It " -"is an error to specify *package* if *module_relative* is ``False``." -msgstr "" - -#: ../../library/doctest.rst:939 -msgid "" -"Optional argument *globs* gives a dict to be used as the globals when " -"executing examples. A new shallow copy of this dict is created for the " -"doctest, so its examples start with a clean slate. By default, or if " -"``None``, a new empty dict is used." -msgstr "" - -#: ../../library/doctest.rst:944 -msgid "" -"Optional argument *extraglobs* gives a dict merged into the globals used to " -"execute examples. This works like :meth:`dict.update`: if *globs* and " -"*extraglobs* have a common key, the associated value in *extraglobs* appears " -"in the combined dict. By default, or if ``None``, no extra globals are " -"used. This is an advanced feature that allows parameterization of " -"doctests. For example, a doctest can be written for a base class, using a " -"generic name for the class, then reused to test any number of subclasses by " -"passing an *extraglobs* dict mapping the generic name to the subclass to be " -"tested." -msgstr "" - -#: ../../library/doctest.rst:953 -msgid "" -"Optional argument *verbose* prints lots of stuff if true, and prints only " -"failures if false; by default, or if ``None``, it's true if and only if ``'-" -"v'`` is in :data:`sys.argv`." -msgstr "" - -#: ../../library/doctest.rst:957 -msgid "" -"Optional argument *report* prints a summary at the end when true, else " -"prints nothing at the end. In verbose mode, the summary is detailed, else " -"the summary is very brief (in fact, empty if all tests passed)." -msgstr "" - -#: ../../library/doctest.rst:961 -msgid "" -"Optional argument *optionflags* (default value ``0``) takes " -"the :ref:`bitwise OR ` of option flags. See section :ref:`doctest-" -"options`." -msgstr "" - -#: ../../library/doctest.rst:965 -msgid "" -"Optional argument *raise_on_error* defaults to false. If true, an exception " -"is raised upon the first failure or unexpected exception in an example. " -"This allows failures to be post-mortem debugged. Default behavior is to " -"continue running examples." -msgstr "" - -#: ../../library/doctest.rst:970 ../../library/doctest.rst:1113 -msgid "" -"Optional argument *parser* specifies a :class:`DocTestParser` (or subclass) " -"that should be used to extract tests from the files. It defaults to a " -"normal parser (i.e., ``DocTestParser()``)." -msgstr "" - -#: ../../library/doctest.rst:974 ../../library/doctest.rst:1117 -msgid "" -"Optional argument *encoding* specifies an encoding that should be used to " -"convert the file to unicode." -msgstr "" - -#: ../../library/doctest.rst:980 -msgid "" -"All arguments are optional, and all except for *m* should be specified in " -"keyword form." -msgstr "" - -#: ../../library/doctest.rst:983 -msgid "" -"Test examples in docstrings in functions and classes reachable from module " -"*m* (or module :mod:`__main__` if *m* is not supplied or is ``None``), " -"starting with ``m.__doc__``." -msgstr "" - -#: ../../library/doctest.rst:987 -msgid "" -"Also test examples reachable from dict ``m.__test__``, if it exists. " -"``m.__test__`` maps names (strings) to functions, classes and strings; " -"function and class docstrings are searched for examples; strings are " -"searched directly, as if they were docstrings." -msgstr "" - -#: ../../library/doctest.rst:992 -msgid "" -"Only docstrings attached to objects belonging to module *m* are searched." -msgstr "" - -#: ../../library/doctest.rst:994 -msgid "Return ``(failure_count, test_count)``." -msgstr "回傳 ``(failure_count, test_count)``。" - -#: ../../library/doctest.rst:996 -msgid "" -"Optional argument *name* gives the name of the module; by default, or if " -"``None``, ``m.__name__`` is used." -msgstr "" - -#: ../../library/doctest.rst:999 -msgid "" -"Optional argument *exclude_empty* defaults to false. If true, objects for " -"which no doctests are found are excluded from consideration. The default is " -"a backward compatibility hack, so that code still " -"using :meth:`doctest.master.summarize ` in " -"conjunction with :func:`testmod` continues to get output for objects with no " -"tests. The *exclude_empty* argument to the newer :class:`DocTestFinder` " -"constructor defaults to true." -msgstr "" - -#: ../../library/doctest.rst:1007 -msgid "" -"Optional arguments *extraglobs*, *verbose*, *report*, *optionflags*, " -"*raise_on_error*, and *globs* are the same as for function :func:`testfile` " -"above, except that *globs* defaults to ``m.__dict__``." -msgstr "" - -#: ../../library/doctest.rst:1014 -msgid "" -"Test examples associated with object *f*; for example, *f* may be a string, " -"a module, a function, or a class object." -msgstr "" - -#: ../../library/doctest.rst:1017 -msgid "" -"A shallow copy of dictionary argument *globs* is used for the execution " -"context." -msgstr "" - -#: ../../library/doctest.rst:1019 -msgid "" -"Optional argument *name* is used in failure messages, and defaults to " -"``\"NoName\"``." -msgstr "" - -#: ../../library/doctest.rst:1022 -msgid "" -"If optional argument *verbose* is true, output is generated even if there " -"are no failures. By default, output is generated only in case of an example " -"failure." -msgstr "" - -#: ../../library/doctest.rst:1025 -msgid "" -"Optional argument *compileflags* gives the set of flags that should be used " -"by the Python compiler when running the examples. By default, or if " -"``None``, flags are deduced corresponding to the set of future features " -"found in *globs*." -msgstr "" - -#: ../../library/doctest.rst:1029 -msgid "" -"Optional argument *optionflags* works as for function :func:`testfile` above." -msgstr "" - -#: ../../library/doctest.rst:1035 -msgid "Unittest API" -msgstr "Unittest API" - -#: ../../library/doctest.rst:1037 -msgid "" -"As your collection of doctest'ed modules grows, you'll want a way to run all " -"their doctests systematically. :mod:`doctest` provides two functions that " -"can be used to create :mod:`unittest` test suites from modules and text " -"files containing doctests. To integrate with :mod:`unittest` test " -"discovery, include a :ref:`load_tests ` function in " -"your test module::" -msgstr "" - -#: ../../library/doctest.rst:1043 -msgid "" -"import unittest\n" -"import doctest\n" -"import my_module_with_doctests\n" -"\n" -"def load_tests(loader, tests, ignore):\n" -" tests.addTests(doctest.DocTestSuite(my_module_with_doctests))\n" -" return tests" -msgstr "" -"import unittest\n" -"import doctest\n" -"import my_module_with_doctests\n" -"\n" -"def load_tests(loader, tests, ignore):\n" -" tests.addTests(doctest.DocTestSuite(my_module_with_doctests))\n" -" return tests" - -#: ../../library/doctest.rst:1051 -msgid "" -"There are two main functions for creating :class:`unittest.TestSuite` " -"instances from text files and modules with doctests:" -msgstr "" - -#: ../../library/doctest.rst:1057 -msgid "" -"Convert doctest tests from one or more text files to " -"a :class:`unittest.TestSuite`." -msgstr "" - -#: ../../library/doctest.rst:1060 -msgid "" -"The returned :class:`unittest.TestSuite` is to be run by the unittest " -"framework and runs the interactive examples in each file. If an example in " -"any file fails, then the synthesized unit test fails, and " -"a :exc:`~unittest.TestCase.failureException` exception is raised showing the " -"name of the file containing the test and a (sometimes approximate) line " -"number. If all the examples in a file are skipped, then the synthesized " -"unit test is also marked as skipped." -msgstr "" - -#: ../../library/doctest.rst:1067 -msgid "Pass one or more paths (as strings) to text files to be examined." -msgstr "" - -#: ../../library/doctest.rst:1069 -msgid "Options may be provided as keyword arguments:" -msgstr "" - -#: ../../library/doctest.rst:1071 -msgid "" -"Optional argument *module_relative* specifies how the filenames in *paths* " -"should be interpreted:" -msgstr "" - -#: ../../library/doctest.rst:1074 -msgid "" -"If *module_relative* is ``True`` (the default), then each filename in " -"*paths* specifies an OS-independent module-relative path. By default, this " -"path is relative to the calling module's directory; but if the *package* " -"argument is specified, then it is relative to that package. To ensure OS-" -"independence, each filename should use ``/`` characters to separate path " -"segments, and may not be an absolute path (i.e., it may not begin with ``/" -"``)." -msgstr "" - -#: ../../library/doctest.rst:1082 -msgid "" -"If *module_relative* is ``False``, then each filename in *paths* specifies " -"an OS-specific path. The path may be absolute or relative; relative paths " -"are resolved with respect to the current working directory." -msgstr "" - -#: ../../library/doctest.rst:1086 -msgid "" -"Optional argument *package* is a Python package or the name of a Python " -"package whose directory should be used as the base directory for module-" -"relative filenames in *paths*. If no package is specified, then the calling " -"module's directory is used as the base directory for module-relative " -"filenames. It is an error to specify *package* if *module_relative* is " -"``False``." -msgstr "" - -#: ../../library/doctest.rst:1093 -msgid "" -"Optional argument *setUp* specifies a set-up function for the test suite. " -"This is called before running the tests in each file. The *setUp* function " -"will be passed a :class:`DocTest` object. The *setUp* function can access " -"the test globals as the :attr:`~DocTest.globs` attribute of the test passed." -msgstr "" - -#: ../../library/doctest.rst:1098 -msgid "" -"Optional argument *tearDown* specifies a tear-down function for the test " -"suite. This is called after running the tests in each file. The *tearDown* " -"function will be passed a :class:`DocTest` object. The *tearDown* function " -"can access the test globals as the :attr:`~DocTest.globs` attribute of the " -"test passed." -msgstr "" - -#: ../../library/doctest.rst:1104 -msgid "" -"Optional argument *globs* is a dictionary containing the initial global " -"variables for the tests. A new copy of this dictionary is created for each " -"test. By default, *globs* is a new empty dictionary." -msgstr "" - -#: ../../library/doctest.rst:1108 -msgid "" -"Optional argument *optionflags* specifies the default doctest options for " -"the tests, created by or-ing together individual option flags. See " -"section :ref:`doctest-options`. See " -"function :func:`set_unittest_reportflags` below for a better way to set " -"reporting options." -msgstr "" - -#: ../../library/doctest.rst:1120 -msgid "" -"The global ``__file__`` is added to the globals provided to doctests loaded " -"from a text file using :func:`DocFileSuite`." -msgstr "" - -#: ../../library/doctest.rst:1126 -msgid "Convert doctest tests for a module to a :class:`unittest.TestSuite`." -msgstr "" - -#: ../../library/doctest.rst:1128 -msgid "" -"The returned :class:`unittest.TestSuite` is to be run by the unittest " -"framework and runs each doctest in the module. Each docstring is run as a " -"separate unit test. If any of the doctests fail, then the synthesized unit " -"test fails, and a :exc:`unittest.TestCase.failureException` exception is " -"raised showing the name of the file containing the test and a (sometimes " -"approximate) line number. If all the examples in a docstring are skipped, " -"then the" -msgstr "" - -#: ../../library/doctest.rst:1136 -msgid "" -"Optional argument *module* provides the module to be tested. It can be a " -"module object or a (possibly dotted) module name. If not specified, the " -"module calling this function is used." -msgstr "" - -#: ../../library/doctest.rst:1140 -msgid "" -"Optional argument *globs* is a dictionary containing the initial global " -"variables for the tests. A new copy of this dictionary is created for each " -"test. By default, *globs* is the module's :attr:`~module.__dict__`." -msgstr "" - -#: ../../library/doctest.rst:1144 -msgid "" -"Optional argument *extraglobs* specifies an extra set of global variables, " -"which is merged into *globs*. By default, no extra globals are used." -msgstr "" - -#: ../../library/doctest.rst:1147 -msgid "" -"Optional argument *test_finder* is the :class:`DocTestFinder` object (or a " -"drop-in replacement) that is used to extract doctests from the module." -msgstr "" - -#: ../../library/doctest.rst:1150 -msgid "" -"Optional arguments *setUp*, *tearDown*, and *optionflags* are the same as " -"for function :func:`DocFileSuite` above, but they are called for each " -"docstring." -msgstr "" - -#: ../../library/doctest.rst:1153 -msgid "This function uses the same search technique as :func:`testmod`." -msgstr "" - -#: ../../library/doctest.rst:1155 -msgid "" -":func:`DocTestSuite` returns an empty :class:`unittest.TestSuite` if " -"*module* contains no docstrings instead of raising :exc:`ValueError`." -msgstr "" - -#: ../../library/doctest.rst:1159 -msgid "" -"Under the covers, :func:`DocTestSuite` creates a :class:`unittest.TestSuite` " -"out of :class:`!doctest.DocTestCase` instances, and :class:`!DocTestCase` is " -"a subclass of :class:`unittest.TestCase`. :class:`!DocTestCase` isn't " -"documented here (it's an internal detail), but studying its code can answer " -"questions about the exact details of :mod:`unittest` integration." -msgstr "" - -#: ../../library/doctest.rst:1165 -msgid "" -"Similarly, :func:`DocFileSuite` creates a :class:`unittest.TestSuite` out " -"of :class:`!doctest.DocFileCase` instances, and :class:`!DocFileCase` is a " -"subclass of :class:`!DocTestCase`." -msgstr "" - -#: ../../library/doctest.rst:1169 -msgid "" -"So both ways of creating a :class:`unittest.TestSuite` run instances " -"of :class:`!DocTestCase`. This is important for a subtle reason: when you " -"run :mod:`doctest` functions yourself, you can control the :mod:`!doctest` " -"options in use directly, by passing option flags to :mod:`!doctest` " -"functions. However, if you're writing a :mod:`unittest` framework, :mod:`!" -"unittest` ultimately controls when and how tests get run. The framework " -"author typically wants to control :mod:`!doctest` reporting options " -"(perhaps, e.g., specified by command line options), but there's no way to " -"pass options through :mod:`!unittest` to :mod:`!doctest` test runners." -msgstr "" - -#: ../../library/doctest.rst:1179 -msgid "" -"For this reason, :mod:`doctest` also supports a notion of :mod:`!doctest` " -"reporting flags specific to :mod:`unittest` support, via this function:" -msgstr "" - -#: ../../library/doctest.rst:1185 -msgid "Set the :mod:`doctest` reporting flags to use." -msgstr "" - -#: ../../library/doctest.rst:1187 -msgid "" -"Argument *flags* takes the :ref:`bitwise OR ` of option flags. See " -"section :ref:`doctest-options`. Only \"reporting flags\" can be used." -msgstr "" - -#: ../../library/doctest.rst:1190 -msgid "" -"This is a module-global setting, and affects all future doctests run by " -"module :mod:`unittest`: the :meth:`!runTest` method of :class:`!" -"DocTestCase` looks at the option flags specified for the test case when " -"the :class:`!DocTestCase` instance was constructed. If no reporting flags " -"were specified (which is the typical and expected case), :mod:`!" -"doctest`'s :mod:`!unittest` reporting flags are :ref:`bitwise ORed " -"` into the option flags, and the option flags so augmented are " -"passed to the :class:`DocTestRunner` instance created to run the doctest. " -"If any reporting flags were specified when the :class:`!DocTestCase` " -"instance was constructed, :mod:`!doctest`'s :mod:`!unittest` reporting flags " -"are ignored." -msgstr "" - -#: ../../library/doctest.rst:1201 -msgid "" -"The value of the :mod:`unittest` reporting flags in effect before the " -"function was called is returned by the function." -msgstr "" - -#: ../../library/doctest.rst:1208 -msgid "Advanced API" -msgstr "" - -#: ../../library/doctest.rst:1210 -msgid "" -"The basic API is a simple wrapper that's intended to make doctest easy to " -"use. It is fairly flexible, and should meet most users' needs; however, if " -"you require more fine-grained control over testing, or wish to extend " -"doctest's capabilities, then you should use the advanced API." -msgstr "" - -#: ../../library/doctest.rst:1215 -msgid "" -"The advanced API revolves around two container classes, which are used to " -"store the interactive examples extracted from doctest cases:" -msgstr "" - -#: ../../library/doctest.rst:1218 -msgid "" -":class:`Example`: A single Python :term:`statement`, paired with its " -"expected output." -msgstr "" - -#: ../../library/doctest.rst:1221 -msgid "" -":class:`DocTest`: A collection of :class:`Example`\\ s, typically extracted " -"from a single docstring or text file." -msgstr "" - -#: ../../library/doctest.rst:1224 -msgid "" -"Additional processing classes are defined to find, parse, and run, and check " -"doctest examples:" -msgstr "" - -#: ../../library/doctest.rst:1227 -msgid "" -":class:`DocTestFinder`: Finds all docstrings in a given module, and uses " -"a :class:`DocTestParser` to create a :class:`DocTest` from every docstring " -"that contains interactive examples." -msgstr "" - -#: ../../library/doctest.rst:1231 -msgid "" -":class:`DocTestParser`: Creates a :class:`DocTest` object from a string " -"(such as an object's docstring)." -msgstr "" - -#: ../../library/doctest.rst:1234 -msgid "" -":class:`DocTestRunner`: Executes the examples in a :class:`DocTest`, and " -"uses an :class:`OutputChecker` to verify their output." -msgstr "" - -#: ../../library/doctest.rst:1237 -msgid "" -":class:`OutputChecker`: Compares the actual output from a doctest example " -"with the expected output, and decides whether they match." -msgstr "" - -#: ../../library/doctest.rst:1240 -msgid "" -"The relationships among these processing classes are summarized in the " -"following diagram::" -msgstr "" - -#: ../../library/doctest.rst:1243 -msgid "" -" list of:\n" -"+------+ +---------+\n" -"|module| --DocTestFinder-> | DocTest | --DocTestRunner-> results\n" -"+------+ | ^ +---------+ | ^ (printed)\n" -" | | | Example | | |\n" -" v | | ... | v |\n" -" DocTestParser | Example | OutputChecker\n" -" +---------+" -msgstr "" -" list of:\n" -"+------+ +---------+\n" -"|module| --DocTestFinder-> | DocTest | --DocTestRunner-> results\n" -"+------+ | ^ +---------+ | ^ (printed)\n" -" | | | Example | | |\n" -" v | | ... | v |\n" -" DocTestParser | Example | OutputChecker\n" -" +---------+" - -#: ../../library/doctest.rst:1256 -msgid "DocTest Objects" -msgstr "DocTest 物件" - -#: ../../library/doctest.rst:1261 -msgid "" -"A collection of doctest examples that should be run in a single namespace. " -"The constructor arguments are used to initialize the attributes of the same " -"names." -msgstr "" - -#: ../../library/doctest.rst:1265 -msgid "" -":class:`DocTest` defines the following attributes. They are initialized by " -"the constructor, and should not be modified directly." -msgstr "" - -#: ../../library/doctest.rst:1271 -msgid "" -"A list of :class:`Example` objects encoding the individual interactive " -"Python examples that should be run by this test." -msgstr "" - -#: ../../library/doctest.rst:1277 -msgid "" -"The namespace (aka globals) that the examples should be run in. This is a " -"dictionary mapping names to values. Any changes to the namespace made by " -"the examples (such as binding new variables) will be reflected " -"in :attr:`globs` after the test is run." -msgstr "" - -#: ../../library/doctest.rst:1285 -msgid "" -"A string name identifying the :class:`DocTest`. Typically, this is the name " -"of the object or file that the test was extracted from." -msgstr "" - -#: ../../library/doctest.rst:1291 -msgid "" -"The name of the file that this :class:`DocTest` was extracted from; or " -"``None`` if the filename is unknown, or if the :class:`!DocTest` was not " -"extracted from a file." -msgstr "" - -#: ../../library/doctest.rst:1298 -msgid "" -"The line number within :attr:`filename` where this :class:`DocTest` begins, " -"or ``None`` if the line number is unavailable. This line number is zero-" -"based with respect to the beginning of the file." -msgstr "" - -#: ../../library/doctest.rst:1305 -msgid "" -"The string that the test was extracted from, or ``None`` if the string is " -"unavailable, or if the test was not extracted from a string." -msgstr "" - -#: ../../library/doctest.rst:1312 -msgid "Example Objects" -msgstr "Example 物件" - -#: ../../library/doctest.rst:1317 -msgid "" -"A single interactive example, consisting of a Python statement and its " -"expected output. The constructor arguments are used to initialize the " -"attributes of the same names." -msgstr "" - -#: ../../library/doctest.rst:1322 -msgid "" -":class:`Example` defines the following attributes. They are initialized by " -"the constructor, and should not be modified directly." -msgstr "" - -#: ../../library/doctest.rst:1328 -msgid "" -"A string containing the example's source code. This source code consists of " -"a single Python statement, and always ends with a newline; the constructor " -"adds a newline when necessary." -msgstr "" - -#: ../../library/doctest.rst:1335 -msgid "" -"The expected output from running the example's source code (either from " -"stdout, or a traceback in case of exception). :attr:`want` ends with a " -"newline unless no output is expected, in which case it's an empty string. " -"The constructor adds a newline when necessary." -msgstr "" - -#: ../../library/doctest.rst:1343 -msgid "" -"The exception message generated by the example, if the example is expected " -"to generate an exception; or ``None`` if it is not expected to generate an " -"exception. This exception message is compared against the return value " -"of :func:`traceback.format_exception_only`. :attr:`exc_msg` ends with a " -"newline unless it's ``None``. The constructor adds a newline if needed." -msgstr "" - -#: ../../library/doctest.rst:1352 -msgid "" -"The line number within the string containing this example where the example " -"begins. This line number is zero-based with respect to the beginning of the " -"containing string." -msgstr "" - -#: ../../library/doctest.rst:1359 -msgid "" -"The example's indentation in the containing string, i.e., the number of " -"space characters that precede the example's first prompt." -msgstr "" - -#: ../../library/doctest.rst:1365 -msgid "" -"A dictionary mapping from option flags to ``True`` or ``False``, which is " -"used to override default options for this example. Any option flags not " -"contained in this dictionary are left at their default value (as specified " -"by the :class:`DocTestRunner`'s :ref:`optionflags `). By " -"default, no options are set." -msgstr "" - -#: ../../library/doctest.rst:1375 -msgid "DocTestFinder objects" -msgstr "DocTestFinder 物件" - -#: ../../library/doctest.rst:1380 -msgid "" -"A processing class used to extract the :class:`DocTest`\\ s that are " -"relevant to a given object, from its docstring and the docstrings of its " -"contained objects. :class:`DocTest`\\ s can be extracted from modules, " -"classes, functions, methods, staticmethods, classmethods, and properties." -msgstr "" - -#: ../../library/doctest.rst:1385 -msgid "" -"The optional argument *verbose* can be used to display the objects searched " -"by the finder. It defaults to ``False`` (no output)." -msgstr "" - -#: ../../library/doctest.rst:1388 -msgid "" -"The optional argument *parser* specifies the :class:`DocTestParser` object " -"(or a drop-in replacement) that is used to extract doctests from docstrings." -msgstr "" - -#: ../../library/doctest.rst:1391 -msgid "" -"If the optional argument *recurse* is false, then :meth:`DocTestFinder.find` " -"will only examine the given object, and not any contained objects." -msgstr "" - -#: ../../library/doctest.rst:1394 -msgid "" -"If the optional argument *exclude_empty* is false, " -"then :meth:`DocTestFinder.find` will include tests for objects with empty " -"docstrings." -msgstr "" - -#: ../../library/doctest.rst:1398 -msgid ":class:`DocTestFinder` defines the following method:" -msgstr ":class:`DocTestFinder` 定義了以下方法：" - -#: ../../library/doctest.rst:1403 -msgid "" -"Return a list of the :class:`DocTest`\\ s that are defined by *obj*'s " -"docstring, or by any of its contained objects' docstrings." -msgstr "" - -#: ../../library/doctest.rst:1406 -msgid "" -"The optional argument *name* specifies the object's name; this name will be " -"used to construct names for the returned :class:`DocTest`\\ s. If *name* is " -"not specified, then ``obj.__name__`` is used." -msgstr "" - -#: ../../library/doctest.rst:1410 -msgid "" -"The optional parameter *module* is the module that contains the given " -"object. If the module is not specified or is ``None``, then the test finder " -"will attempt to automatically determine the correct module. The object's " -"module is used:" -msgstr "" - -#: ../../library/doctest.rst:1414 -msgid "As a default namespace, if *globs* is not specified." -msgstr "" - -#: ../../library/doctest.rst:1416 -msgid "" -"To prevent the DocTestFinder from extracting DocTests from objects that are " -"imported from other modules. (Contained objects with modules other than " -"*module* are ignored.)" -msgstr "" - -#: ../../library/doctest.rst:1420 -msgid "To find the name of the file containing the object." -msgstr "" - -#: ../../library/doctest.rst:1422 -msgid "To help find the line number of the object within its file." -msgstr "" - -#: ../../library/doctest.rst:1424 -msgid "" -"If *module* is ``False``, no attempt to find the module will be made. This " -"is obscure, of use mostly in testing doctest itself: if *module* is " -"``False``, or is ``None`` but cannot be found automatically, then all " -"objects are considered to belong to the (non-existent) module, so all " -"contained objects will (recursively) be searched for doctests." -msgstr "" - -#: ../../library/doctest.rst:1430 -msgid "" -"The globals for each :class:`DocTest` is formed by combining *globs* and " -"*extraglobs* (bindings in *extraglobs* override bindings in *globs*). A new " -"shallow copy of the globals dictionary is created for each :class:`!" -"DocTest`. If *globs* is not specified, then it defaults to the " -"module's :attr:`~module.__dict__`, if specified, or ``{}`` otherwise. If " -"*extraglobs* is not specified, then it defaults to ``{}``." -msgstr "" - -#: ../../library/doctest.rst:1441 -msgid "DocTestParser objects" -msgstr "DocTestParser 物件" - -#: ../../library/doctest.rst:1446 -msgid "" -"A processing class used to extract interactive examples from a string, and " -"use them to create a :class:`DocTest` object." -msgstr "" - -#: ../../library/doctest.rst:1450 -msgid ":class:`DocTestParser` defines the following methods:" -msgstr ":class:`DocTestParser` 定義了以下方法：" - -#: ../../library/doctest.rst:1455 -msgid "" -"Extract all doctest examples from the given string, and collect them into " -"a :class:`DocTest` object." -msgstr "" - -#: ../../library/doctest.rst:1458 -msgid "" -"*globs*, *name*, *filename*, and *lineno* are attributes for the " -"new :class:`!DocTest` object. See the documentation for :class:`DocTest` " -"for more information." -msgstr "" - -#: ../../library/doctest.rst:1465 -msgid "" -"Extract all doctest examples from the given string, and return them as a " -"list of :class:`Example` objects. Line numbers are 0-based. The optional " -"argument *name* is a name identifying this string, and is only used for " -"error messages." -msgstr "" - -#: ../../library/doctest.rst:1472 -msgid "" -"Divide the given string into examples and intervening text, and return them " -"as a list of alternating :class:`Example`\\ s and strings. Line numbers for " -"the :class:`!Example`\\ s are 0-based. The optional argument *name* is a " -"name identifying this string, and is only used for error messages." -msgstr "" - -#: ../../library/doctest.rst:1479 -msgid "TestResults objects" -msgstr "TestResults 物件" - -#: ../../library/doctest.rst:1486 -msgid "Number of failed tests." -msgstr "失敗的測試數量。" - -#: ../../library/doctest.rst:1490 -msgid "Number of attempted tests." -msgstr "嘗試的測試數量。" - -#: ../../library/doctest.rst:1494 -msgid "Number of skipped tests." -msgstr "跳過的測試數量。" - -#: ../../library/doctest.rst:1502 -msgid "DocTestRunner objects" -msgstr "DocTestRunner 物件" - -#: ../../library/doctest.rst:1507 -msgid "" -"A processing class used to execute and verify the interactive examples in " -"a :class:`DocTest`." -msgstr "" - -#: ../../library/doctest.rst:1510 -msgid "" -"The comparison between expected outputs and actual outputs is done by " -"an :class:`OutputChecker`. This comparison may be customized with a number " -"of option flags; see section :ref:`doctest-options` for more information. " -"If the option flags are insufficient, then the comparison may also be " -"customized by passing a subclass of :class:`!OutputChecker` to the " -"constructor." -msgstr "" - -#: ../../library/doctest.rst:1516 -msgid "" -"The test runner's display output can be controlled in two ways. First, an " -"output function can be passed to :meth:`run`; this function will be called " -"with strings that should be displayed. It defaults to " -"``sys.stdout.write``. If capturing the output is not sufficient, then the " -"display output can be also customized by subclassing DocTestRunner, and " -"overriding the " -"methods :meth:`report_start`, :meth:`report_success`, :meth:`report_unexpected_exception`, " -"and :meth:`report_failure`." -msgstr "" - -#: ../../library/doctest.rst:1524 -msgid "" -"The optional keyword argument *checker* specifies the :class:`OutputChecker` " -"object (or drop-in replacement) that should be used to compare the expected " -"outputs to the actual outputs of doctest examples." -msgstr "" - -#: ../../library/doctest.rst:1528 -msgid "" -"The optional keyword argument *verbose* controls " -"the :class:`DocTestRunner`'s verbosity. If *verbose* is ``True``, then " -"information is printed about each example, as it is run. If *verbose* is " -"``False``, then only failures are printed. If *verbose* is unspecified, or " -"``None``, then verbose output is used iff the command-line switch ``-v`` is " -"used." -msgstr "" - -#: ../../library/doctest.rst:1534 -msgid "" -"The optional keyword argument *optionflags* can be used to control how the " -"test runner compares expected output to actual output, and how it displays " -"failures. For more information, see section :ref:`doctest-options`." -msgstr "" - -#: ../../library/doctest.rst:1538 -msgid "" -"The test runner accumulates statistics. The aggregated number of attempted, " -"failed and skipped examples is also available via " -"the :attr:`tries`, :attr:`failures` and :attr:`skips` attributes. " -"The :meth:`run` and :meth:`summarize` methods return a :class:`TestResults` " -"instance." -msgstr "" - -#: ../../library/doctest.rst:1543 -msgid ":class:`DocTestRunner` defines the following methods:" -msgstr ":class:`DocTestRunner` 定義了以下方法：" - -#: ../../library/doctest.rst:1548 -msgid "" -"Report that the test runner is about to process the given example. This " -"method is provided to allow subclasses of :class:`DocTestRunner` to " -"customize their output; it should not be called directly." -msgstr "" - -#: ../../library/doctest.rst:1552 -msgid "" -"*example* is the example about to be processed. *test* is the test " -"containing *example*. *out* is the output function that was passed " -"to :meth:`DocTestRunner.run`." -msgstr "" - -#: ../../library/doctest.rst:1559 -msgid "" -"Report that the given example ran successfully. This method is provided to " -"allow subclasses of :class:`DocTestRunner` to customize their output; it " -"should not be called directly." -msgstr "" - -#: ../../library/doctest.rst:1563 ../../library/doctest.rst:1574 -msgid "" -"*example* is the example about to be processed. *got* is the actual output " -"from the example. *test* is the test containing *example*. *out* is the " -"output function that was passed to :meth:`DocTestRunner.run`." -msgstr "" - -#: ../../library/doctest.rst:1570 -msgid "" -"Report that the given example failed. This method is provided to allow " -"subclasses of :class:`DocTestRunner` to customize their output; it should " -"not be called directly." -msgstr "" - -#: ../../library/doctest.rst:1581 -msgid "" -"Report that the given example raised an unexpected exception. This method is " -"provided to allow subclasses of :class:`DocTestRunner` to customize their " -"output; it should not be called directly." -msgstr "" - -#: ../../library/doctest.rst:1585 -msgid "" -"*example* is the example about to be processed. *exc_info* is a tuple " -"containing information about the unexpected exception (as returned " -"by :func:`sys.exc_info`). *test* is the test containing *example*. *out* is " -"the output function that was passed to :meth:`DocTestRunner.run`." -msgstr "" - -#: ../../library/doctest.rst:1593 -msgid "" -"Run the examples in *test* (a :class:`DocTest` object), and display the " -"results using the writer function *out*. Return a :class:`TestResults` " -"instance." -msgstr "" - -#: ../../library/doctest.rst:1597 -msgid "" -"The examples are run in the namespace ``test.globs``. If *clear_globs* is " -"true (the default), then this namespace will be cleared after the test runs, " -"to help with garbage collection. If you would like to examine the namespace " -"after the test completes, then use *clear_globs=False*." -msgstr "" - -#: ../../library/doctest.rst:1602 -msgid "" -"*compileflags* gives the set of flags that should be used by the Python " -"compiler when running the examples. If not specified, then it will default " -"to the set of future-import flags that apply to *globs*." -msgstr "" - -#: ../../library/doctest.rst:1606 -msgid "" -"The output of each example is checked using the :class:`DocTestRunner`'s " -"output checker, and the results are formatted by the :meth:`!" -"DocTestRunner.report_\\*` methods." -msgstr "" - -#: ../../library/doctest.rst:1613 -msgid "" -"Print a summary of all the test cases that have been run by this " -"DocTestRunner, and return a :class:`TestResults` instance." -msgstr "" - -#: ../../library/doctest.rst:1616 -msgid "" -"The optional *verbose* argument controls how detailed the summary is. If " -"the verbosity is not specified, then the :class:`DocTestRunner`'s verbosity " -"is used." -msgstr "" - -#: ../../library/doctest.rst:1620 -msgid ":class:`DocTestParser` has the following attributes:" -msgstr ":class:`DocTestParser` 有以下屬性：" - -#: ../../library/doctest.rst:1624 -msgid "Number of attempted examples." -msgstr "嘗試的範例數量。" - -#: ../../library/doctest.rst:1628 -msgid "Number of failed examples." -msgstr "失敗的範例數量。" - -#: ../../library/doctest.rst:1632 -msgid "Number of skipped examples." -msgstr "跳過的範例數量。" - -#: ../../library/doctest.rst:1640 -msgid "OutputChecker objects" -msgstr "OutputChecker 物件" - -#: ../../library/doctest.rst:1645 -msgid "" -"A class used to check the whether the actual output from a doctest example " -"matches the expected output. :class:`OutputChecker` defines two " -"methods: :meth:`check_output`, which compares a given pair of outputs, and " -"returns ``True`` if they match; and :meth:`output_difference`, which returns " -"a string describing the differences between two outputs." -msgstr "" - -#: ../../library/doctest.rst:1652 -msgid ":class:`OutputChecker` defines the following methods:" -msgstr ":class:`OutputChecker` 定義了以下方法：" - -#: ../../library/doctest.rst:1656 -msgid "" -"Return ``True`` iff the actual output from an example (*got*) matches the " -"expected output (*want*). These strings are always considered to match if " -"they are identical; but depending on what option flags the test runner is " -"using, several non-exact match types are also possible. See " -"section :ref:`doctest-options` for more information about option flags." -msgstr "" - -#: ../../library/doctest.rst:1665 -msgid "" -"Return a string describing the differences between the expected output for a " -"given example (*example*) and the actual output (*got*). *optionflags* is " -"the set of option flags used to compare *want* and *got*." -msgstr "" - -#: ../../library/doctest.rst:1673 -msgid "Debugging" -msgstr "偵錯" - -#: ../../library/doctest.rst:1675 -msgid "Doctest provides several mechanisms for debugging doctest examples:" -msgstr "Doctest 提供了幾種偵錯 doctest 範例的機制：" - -#: ../../library/doctest.rst:1677 -msgid "" -"Several functions convert doctests to executable Python programs, which can " -"be run under the Python debugger, :mod:`pdb`." -msgstr "" - -#: ../../library/doctest.rst:1680 -msgid "" -"The :class:`DebugRunner` class is a subclass of :class:`DocTestRunner` that " -"raises an exception for the first failing example, containing information " -"about that example. This information can be used to perform post-mortem " -"debugging on the example." -msgstr "" - -#: ../../library/doctest.rst:1685 -msgid "" -"The :mod:`unittest` cases generated by :func:`DocTestSuite` support " -"the :meth:`debug` method defined by :class:`unittest.TestCase`." -msgstr "" - -#: ../../library/doctest.rst:1688 -msgid "" -"You can add a call to :func:`pdb.set_trace` in a doctest example, and you'll " -"drop into the Python debugger when that line is executed. Then you can " -"inspect current values of variables, and so on. For example, " -"suppose :file:`a.py` contains just this module docstring::" -msgstr "" - -#: ../../library/doctest.rst:1693 -msgid "" -"\"\"\"\n" -">>> def f(x):\n" -"... g(x*2)\n" -">>> def g(x):\n" -"... print(x+3)\n" -"... import pdb; pdb.set_trace()\n" -">>> f(3)\n" -"9\n" -"\"\"\"" -msgstr "" -"\"\"\"\n" -">>> def f(x):\n" -"... g(x*2)\n" -">>> def g(x):\n" -"... print(x+3)\n" -"... import pdb; pdb.set_trace()\n" -">>> f(3)\n" -"9\n" -"\"\"\"" - -#: ../../library/doctest.rst:1703 -msgid "Then an interactive Python session may look like this::" -msgstr "" - -#: ../../library/doctest.rst:1705 -msgid "" -">>> import a, doctest\n" -">>> doctest.testmod(a)\n" -"--Return--\n" -"> (3)g()->None\n" -"-> import pdb; pdb.set_trace()\n" -"(Pdb) list\n" -" 1 def g(x):\n" -" 2 print(x+3)\n" -" 3 -> import pdb; pdb.set_trace()\n" -"[EOF]\n" -"(Pdb) p x\n" -"6\n" -"(Pdb) step\n" -"--Return--\n" -"> (2)f()->None\n" -"-> g(x*2)\n" -"(Pdb) list\n" -" 1 def f(x):\n" -" 2 -> g(x*2)\n" -"[EOF]\n" -"(Pdb) p x\n" -"3\n" -"(Pdb) step\n" -"--Return--\n" -"> (1)?()->None\n" -"-> f(3)\n" -"(Pdb) cont\n" -"(0, 3)\n" -">>>" -msgstr "" -">>> import a, doctest\n" -">>> doctest.testmod(a)\n" -"--Return--\n" -"> (3)g()->None\n" -"-> import pdb; pdb.set_trace()\n" -"(Pdb) list\n" -" 1 def g(x):\n" -" 2 print(x+3)\n" -" 3 -> import pdb; pdb.set_trace()\n" -"[EOF]\n" -"(Pdb) p x\n" -"6\n" -"(Pdb) step\n" -"--Return--\n" -"> (2)f()->None\n" -"-> g(x*2)\n" -"(Pdb) list\n" -" 1 def f(x):\n" -" 2 -> g(x*2)\n" -"[EOF]\n" -"(Pdb) p x\n" -"3\n" -"(Pdb) step\n" -"--Return--\n" -"> (1)?()->None\n" -"-> f(3)\n" -"(Pdb) cont\n" -"(0, 3)\n" -">>>" - -#: ../../library/doctest.rst:1736 -msgid "" -"Functions that convert doctests to Python code, and possibly run the " -"synthesized code under the debugger:" -msgstr "" - -#: ../../library/doctest.rst:1742 -msgid "Convert text with examples to a script." -msgstr "" - -#: ../../library/doctest.rst:1744 -msgid "" -"Argument *s* is a string containing doctest examples. The string is " -"converted to a Python script, where doctest examples in *s* are converted to " -"regular code, and everything else is converted to Python comments. The " -"generated script is returned as a string. For example, ::" -msgstr "" - -#: ../../library/doctest.rst:1749 -msgid "" -"import doctest\n" -"print(doctest.script_from_examples(r\"\"\"\n" -" Set x and y to 1 and 2.\n" -" >>> x, y = 1, 2\n" -"\n" -" Print their sum:\n" -" >>> print(x+y)\n" -" 3\n" -"\"\"\"))" -msgstr "" - -#: ../../library/doctest.rst:1759 -msgid "displays::" -msgstr "" - -#: ../../library/doctest.rst:1761 -msgid "" -"# Set x and y to 1 and 2.\n" -"x, y = 1, 2\n" -"#\n" -"# Print their sum:\n" -"print(x+y)\n" -"# Expected:\n" -"## 3" -msgstr "" - -#: ../../library/doctest.rst:1769 -msgid "" -"This function is used internally by other functions (see below), but can " -"also be useful when you want to transform an interactive Python session into " -"a Python script." -msgstr "" - -#: ../../library/doctest.rst:1776 -msgid "Convert the doctest for an object to a script." -msgstr "" - -#: ../../library/doctest.rst:1778 -msgid "" -"Argument *module* is a module object, or dotted name of a module, containing " -"the object whose doctests are of interest. Argument *name* is the name " -"(within the module) of the object with the doctests of interest. The result " -"is a string, containing the object's docstring converted to a Python script, " -"as described for :func:`script_from_examples` above. For example, if " -"module :file:`a.py` contains a top-level function :func:`!f`, then ::" -msgstr "" - -#: ../../library/doctest.rst:1785 -msgid "" -"import a, doctest\n" -"print(doctest.testsource(a, \"a.f\"))" -msgstr "" -"import a, doctest\n" -"print(doctest.testsource(a, \"a.f\"))" - -#: ../../library/doctest.rst:1788 -msgid "" -"prints a script version of function :func:`!f`'s docstring, with doctests " -"converted to code, and the rest placed in comments." -msgstr "" - -#: ../../library/doctest.rst:1794 -msgid "Debug the doctests for an object." -msgstr "" - -#: ../../library/doctest.rst:1796 -msgid "" -"The *module* and *name* arguments are the same as for " -"function :func:`testsource` above. The synthesized Python script for the " -"named object's docstring is written to a temporary file, and then that file " -"is run under the control of the Python debugger, :mod:`pdb`." -msgstr "" - -#: ../../library/doctest.rst:1801 -msgid "" -"A shallow copy of ``module.__dict__`` is used for both local and global " -"execution context." -msgstr "" - -#: ../../library/doctest.rst:1804 -msgid "" -"Optional argument *pm* controls whether post-mortem debugging is used. If " -"*pm* has a true value, the script file is run directly, and the debugger " -"gets involved only if the script terminates via raising an unhandled " -"exception. If it does, then post-mortem debugging is invoked, " -"via :func:`pdb.post_mortem`, passing the traceback object from the unhandled " -"exception. If *pm* is not specified, or is false, the script is run under " -"the debugger from the start, via passing an appropriate :func:`exec` call " -"to :func:`pdb.run`." -msgstr "" - -#: ../../library/doctest.rst:1815 -msgid "Debug the doctests in a string." -msgstr "" - -#: ../../library/doctest.rst:1817 -msgid "" -"This is like function :func:`debug` above, except that a string containing " -"doctest examples is specified directly, via the *src* argument." -msgstr "" - -#: ../../library/doctest.rst:1820 -msgid "" -"Optional argument *pm* has the same meaning as in function :func:`debug` " -"above." -msgstr "" - -#: ../../library/doctest.rst:1822 -msgid "" -"Optional argument *globs* gives a dictionary to use as both local and global " -"execution context. If not specified, or ``None``, an empty dictionary is " -"used. If specified, a shallow copy of the dictionary is used." -msgstr "" - -#: ../../library/doctest.rst:1827 -msgid "" -"The :class:`DebugRunner` class, and the special exceptions it may raise, are " -"of most interest to testing framework authors, and will only be sketched " -"here. See the source code, and especially :class:`DebugRunner`'s docstring " -"(which is a doctest!) for more details:" -msgstr "" - -#: ../../library/doctest.rst:1835 -msgid "" -"A subclass of :class:`DocTestRunner` that raises an exception as soon as a " -"failure is encountered. If an unexpected exception occurs, " -"an :exc:`UnexpectedException` exception is raised, containing the test, the " -"example, and the original exception. If the output doesn't match, then " -"a :exc:`DocTestFailure` exception is raised, containing the test, the " -"example, and the actual output." -msgstr "" - -#: ../../library/doctest.rst:1842 -msgid "" -"For information about the constructor parameters and methods, see the " -"documentation for :class:`DocTestRunner` in section :ref:`doctest-advanced-" -"api`." -msgstr "" - -#: ../../library/doctest.rst:1845 -msgid "" -"There are two exceptions that may be raised by :class:`DebugRunner` " -"instances:" -msgstr "" - -#: ../../library/doctest.rst:1850 -msgid "" -"An exception raised by :class:`DocTestRunner` to signal that a doctest " -"example's actual output did not match its expected output. The constructor " -"arguments are used to initialize the attributes of the same names." -msgstr "" - -#: ../../library/doctest.rst:1854 -msgid ":exc:`DocTestFailure` defines the following attributes:" -msgstr ":exc:`DocTestFailure` 定義了以下屬性：" - -#: ../../library/doctest.rst:1859 ../../library/doctest.rst:1883 -msgid "The :class:`DocTest` object that was being run when the example failed." -msgstr "" - -#: ../../library/doctest.rst:1864 ../../library/doctest.rst:1888 -msgid "The :class:`Example` that failed." -msgstr "" - -#: ../../library/doctest.rst:1869 -msgid "The example's actual output." -msgstr "" - -#: ../../library/doctest.rst:1874 -msgid "" -"An exception raised by :class:`DocTestRunner` to signal that a doctest " -"example raised an unexpected exception. The constructor arguments are used " -"to initialize the attributes of the same names." -msgstr "" - -#: ../../library/doctest.rst:1878 -msgid ":exc:`UnexpectedException` defines the following attributes:" -msgstr ":exc:`UnexpectedException` 定義了以下屬性：" - -#: ../../library/doctest.rst:1893 -msgid "" -"A tuple containing information about the unexpected exception, as returned " -"by :func:`sys.exc_info`." -msgstr "" - -#: ../../library/doctest.rst:1900 -msgid "Soapbox" -msgstr "" - -#: ../../library/doctest.rst:1902 -msgid "" -"As mentioned in the introduction, :mod:`doctest` has grown to have three " -"primary uses:" -msgstr "" - -#: ../../library/doctest.rst:1905 -msgid "Checking examples in docstrings." -msgstr "" - -#: ../../library/doctest.rst:1907 -msgid "Regression testing." -msgstr "回歸測試。" - -#: ../../library/doctest.rst:1909 -msgid "Executable documentation / literate testing." -msgstr "" - -#: ../../library/doctest.rst:1911 -msgid "" -"These uses have different requirements, and it is important to distinguish " -"them. In particular, filling your docstrings with obscure test cases makes " -"for bad documentation." -msgstr "" - -#: ../../library/doctest.rst:1915 -msgid "" -"When writing a docstring, choose docstring examples with care. There's an " -"art to this that needs to be learned---it may not be natural at first. " -"Examples should add genuine value to the documentation. A good example can " -"often be worth many words. If done with care, the examples will be " -"invaluable for your users, and will pay back the time it takes to collect " -"them many times over as the years go by and things change. I'm still amazed " -"at how often one of my :mod:`doctest` examples stops working after a " -"\"harmless\" change." -msgstr "" - -#: ../../library/doctest.rst:1923 -msgid "" -"Doctest also makes an excellent tool for regression testing, especially if " -"you don't skimp on explanatory text. By interleaving prose and examples, it " -"becomes much easier to keep track of what's actually being tested, and why. " -"When a test fails, good prose can make it much easier to figure out what the " -"problem is, and how it should be fixed. It's true that you could write " -"extensive comments in code-based testing, but few programmers do. Many have " -"found that using doctest approaches instead leads to much clearer tests. " -"Perhaps this is simply because doctest makes writing prose a little easier " -"than writing code, while writing comments in code is a little harder. I " -"think it goes deeper than just that: the natural attitude when writing a " -"doctest-based test is that you want to explain the fine points of your " -"software, and illustrate them with examples. This in turn naturally leads to " -"test files that start with the simplest features, and logically progress to " -"complications and edge cases. A coherent narrative is the result, instead " -"of a collection of isolated functions that test isolated bits of " -"functionality seemingly at random. It's a different attitude, and produces " -"different results, blurring the distinction between testing and explaining." -msgstr "" - -#: ../../library/doctest.rst:1941 -msgid "" -"Regression testing is best confined to dedicated objects or files. There " -"are several options for organizing tests:" -msgstr "" - -#: ../../library/doctest.rst:1944 -msgid "" -"Write text files containing test cases as interactive examples, and test the " -"files using :func:`testfile` or :func:`DocFileSuite`. This is recommended, " -"although is easiest to do for new projects, designed from the start to use " -"doctest." -msgstr "" - -#: ../../library/doctest.rst:1949 -msgid "" -"Define functions named ``_regrtest_topic`` that consist of single " -"docstrings, containing test cases for the named topics. These functions can " -"be included in the same file as the module, or separated out into a separate " -"test file." -msgstr "" - -#: ../../library/doctest.rst:1953 -msgid "" -"Define a :attr:`~module.__test__` dictionary mapping from regression test " -"topics to docstrings containing test cases." -msgstr "" - -#: ../../library/doctest.rst:1956 -msgid "" -"When you have placed your tests in a module, the module can itself be the " -"test runner. When a test fails, you can arrange for your test runner to re-" -"run only the failing doctest while you debug the problem. Here is a minimal " -"example of such a test runner::" -msgstr "" - -#: ../../library/doctest.rst:1961 -msgid "" -"if __name__ == '__main__':\n" -" import doctest\n" -" flags = doctest.REPORT_NDIFF|doctest.FAIL_FAST\n" -" if len(sys.argv) > 1:\n" -" name = sys.argv[1]\n" -" if name in globals():\n" -" obj = globals()[name]\n" -" else:\n" -" obj = __test__[name]\n" -" doctest.run_docstring_examples(obj, globals(), name=name,\n" -" optionflags=flags)\n" -" else:\n" -" fail, total = doctest.testmod(optionflags=flags)\n" -" print(f\"{fail} failures out of {total} tests\")" -msgstr "" -"if __name__ == '__main__':\n" -" import doctest\n" -" flags = doctest.REPORT_NDIFF|doctest.FAIL_FAST\n" -" if len(sys.argv) > 1:\n" -" name = sys.argv[1]\n" -" if name in globals():\n" -" obj = globals()[name]\n" -" else:\n" -" obj = __test__[name]\n" -" doctest.run_docstring_examples(obj, globals(), name=name,\n" -" optionflags=flags)\n" -" else:\n" -" fail, total = doctest.testmod(optionflags=flags)\n" -" print(f\"{fail} failures out of {total} tests\")" - -#: ../../library/doctest.rst:1978 -msgid "Footnotes" -msgstr "註腳" - -#: ../../library/doctest.rst:1979 -msgid "" -"Examples containing both expected output and an exception are not supported. " -"Trying to guess where one ends and the other begins is too error-prone, and " -"that also makes for a confusing test." -msgstr "" - -#: ../../library/doctest.rst:387 -msgid ">>>" -msgstr ">>>" - -#: ../../library/doctest.rst:387 -msgid "interpreter prompt" -msgstr "interpreter prompt（直譯器提示）" - -#: ../../library/doctest.rst:387 ../../library/doctest.rst:622 -msgid "..." -msgstr "..." - -#: ../../library/doctest.rst:553 -msgid "^ (caret)" -msgstr "^ （插入符號）" - -#: ../../library/doctest.rst:553 -msgid "marker" -msgstr "marker（標記）" - -#: ../../library/doctest.rst:602 -msgid "" -msgstr "" - -#: ../../library/doctest.rst:622 ../../library/doctest.rst:747 -msgid "in doctests" -msgstr "於 doctests 中" - -#: ../../library/doctest.rst:747 -msgid "# (hash)" -msgstr "# （井字號）" - -#: ../../library/doctest.rst:747 -msgid "+ (plus)" -msgstr "+ （加號）" - -#: ../../library/doctest.rst:747 -msgid "- (minus)" -msgstr "- （減號）" - -#~ msgid "The ``-o`` command line option." -#~ msgstr " ``-o`` 命令列選項。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: 2018-05-23 14:43+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/doctest.rst:2 +msgid ":mod:`!doctest` --- Test interactive Python examples" +msgstr ":mod:`!doctest` --- 測試互動式 Python 範例" + +#: ../../library/doctest.rst:12 +msgid "**Source code:** :source:`Lib/doctest.py`" +msgstr "**原始碼：**\\ :source:`Lib/doctest.py`" + +#: ../../library/doctest.rst:16 +msgid "" +"The :mod:`doctest` module searches for pieces of text that look like " +"interactive Python sessions, and then executes those sessions to verify that " +"they work exactly as shown. There are several common ways to use doctest:" +msgstr "" + +#: ../../library/doctest.rst:20 +msgid "" +"To check that a module's docstrings are up-to-date by verifying that all " +"interactive examples still work as documented." +msgstr "" + +#: ../../library/doctest.rst:23 +msgid "" +"To perform regression testing by verifying that interactive examples from a " +"test file or a test object work as expected." +msgstr "透過驗證測試檔案或測試物件中的互動式範例是否按預期運作來執行迴歸測試。" + +#: ../../library/doctest.rst:26 +msgid "" +"To write tutorial documentation for a package, liberally illustrated with " +"input-output examples. Depending on whether the examples or the expository " +"text are emphasized, this has the flavor of \"literate testing\" or " +"\"executable documentation\"." +msgstr "" + +#: ../../library/doctest.rst:31 +msgid "Here's a complete but small example module::" +msgstr "" + +#: ../../library/doctest.rst:33 +msgid "" +"\"\"\"\n" +"This is the \"example\" module.\n" +"\n" +"The example module supplies one function, factorial(). For example,\n" +"\n" +">>> factorial(5)\n" +"120\n" +"\"\"\"\n" +"\n" +"def factorial(n):\n" +" \"\"\"Return the factorial of n, an exact integer >= 0.\n" +"\n" +" >>> [factorial(n) for n in range(6)]\n" +" [1, 1, 2, 6, 24, 120]\n" +" >>> factorial(30)\n" +" 265252859812191058636308480000000\n" +" >>> factorial(-1)\n" +" Traceback (most recent call last):\n" +" ...\n" +" ValueError: n must be >= 0\n" +"\n" +" Factorials of floats are OK, but the float must be an exact integer:\n" +" >>> factorial(30.1)\n" +" Traceback (most recent call last):\n" +" ...\n" +" ValueError: n must be exact integer\n" +" >>> factorial(30.0)\n" +" 265252859812191058636308480000000\n" +"\n" +" It must also not be ridiculously large:\n" +" >>> factorial(1e100)\n" +" Traceback (most recent call last):\n" +" ...\n" +" OverflowError: n too large\n" +" \"\"\"\n" +"\n" +" import math\n" +" if not n >= 0:\n" +" raise ValueError(\"n must be >= 0\")\n" +" if math.floor(n) != n:\n" +" raise ValueError(\"n must be exact integer\")\n" +" if n+1 == n: # catch a value like 1e300\n" +" raise OverflowError(\"n too large\")\n" +" result = 1\n" +" factor = 2\n" +" while factor <= n:\n" +" result *= factor\n" +" factor += 1\n" +" return result\n" +"\n" +"\n" +"if __name__ == \"__main__\":\n" +" import doctest\n" +" doctest.testmod()" +msgstr "" + +#: ../../library/doctest.rst:88 +msgid "" +"If you run :file:`example.py` directly from the command line, :mod:`doctest` " +"works its magic:" +msgstr "" + +#: ../../library/doctest.rst:91 +msgid "" +"$ python example.py\n" +"$" +msgstr "" +"$ python example.py\n" +"$" + +#: ../../library/doctest.rst:96 +msgid "" +"There's no output! That's normal, and it means all the examples worked. " +"Pass ``-v`` to the script, and :mod:`doctest` prints a detailed log of what " +"it's trying, and prints a summary at the end:" +msgstr "" + +#: ../../library/doctest.rst:100 +msgid "" +"$ python example.py -v\n" +"Trying:\n" +" factorial(5)\n" +"Expecting:\n" +" 120\n" +"ok\n" +"Trying:\n" +" [factorial(n) for n in range(6)]\n" +"Expecting:\n" +" [1, 1, 2, 6, 24, 120]\n" +"ok" +msgstr "" +"$ python example.py -v\n" +"Trying:\n" +" factorial(5)\n" +"Expecting:\n" +" 120\n" +"ok\n" +"Trying:\n" +" [factorial(n) for n in range(6)]\n" +"Expecting:\n" +" [1, 1, 2, 6, 24, 120]\n" +"ok" + +#: ../../library/doctest.rst:114 +msgid "And so on, eventually ending with:" +msgstr "" + +#: ../../library/doctest.rst:116 +msgid "" +"Trying:\n" +" factorial(1e100)\n" +"Expecting:\n" +" Traceback (most recent call last):\n" +" ...\n" +" OverflowError: n too large\n" +"ok\n" +"2 items passed all tests:\n" +" 1 test in __main__\n" +" 6 tests in __main__.factorial\n" +"7 tests in 2 items.\n" +"7 passed.\n" +"Test passed.\n" +"$" +msgstr "" +"Trying:\n" +" factorial(1e100)\n" +"Expecting:\n" +" Traceback (most recent call last):\n" +" ...\n" +" OverflowError: n too large\n" +"ok\n" +"2 items passed all tests:\n" +" 1 test in __main__\n" +" 6 tests in __main__.factorial\n" +"7 tests in 2 items.\n" +"7 passed.\n" +"Test passed.\n" +"$" + +#: ../../library/doctest.rst:133 +msgid "" +"That's all you need to know to start making productive use " +"of :mod:`doctest`! Jump in. The following sections provide full details. " +"Note that there are many examples of doctests in the standard Python test " +"suite and libraries. Especially useful examples can be found in the standard " +"test file :file:`Lib/test/test_doctest/test_doctest.py`." +msgstr "" + +#: ../../library/doctest.rst:139 +msgid "" +"Output is colorized by default and can be :ref:`controlled using environment " +"variables `." +msgstr "" + +#: ../../library/doctest.rst:147 +msgid "Simple Usage: Checking Examples in Docstrings" +msgstr "" + +#: ../../library/doctest.rst:149 +msgid "" +"The simplest way to start using doctest (but not necessarily the way you'll " +"continue to do it) is to end each module :mod:`!M` with::" +msgstr "" + +#: ../../library/doctest.rst:152 +msgid "" +"if __name__ == \"__main__\":\n" +" import doctest\n" +" doctest.testmod()" +msgstr "" +"if __name__ == \"__main__\":\n" +" import doctest\n" +" doctest.testmod()" + +#: ../../library/doctest.rst:156 +msgid ":mod:`!doctest` then examines docstrings in module :mod:`!M`." +msgstr "" + +#: ../../library/doctest.rst:158 +msgid "" +"Running the module as a script causes the examples in the docstrings to get " +"executed and verified::" +msgstr "" + +#: ../../library/doctest.rst:161 +msgid "python M.py" +msgstr "python M.py" + +#: ../../library/doctest.rst:163 +msgid "" +"This won't display anything unless an example fails, in which case the " +"failing example(s) and the cause(s) of the failure(s) are printed to stdout, " +"and the final line of output is ``***Test Failed*** N failures.``, where *N* " +"is the number of examples that failed." +msgstr "" + +#: ../../library/doctest.rst:168 +msgid "Run it with the ``-v`` switch instead::" +msgstr "" + +#: ../../library/doctest.rst:170 +msgid "python M.py -v" +msgstr "python M.py -v" + +#: ../../library/doctest.rst:172 +msgid "" +"and a detailed report of all examples tried is printed to standard output, " +"along with assorted summaries at the end." +msgstr "" + +#: ../../library/doctest.rst:175 +msgid "" +"You can force verbose mode by passing ``verbose=True`` to :func:`testmod`, " +"or prohibit it by passing ``verbose=False``. In either of those " +"cases, :data:`sys.argv` is not examined by :func:`testmod` (so passing ``-" +"v`` or not has no effect)." +msgstr "" + +#: ../../library/doctest.rst:180 +msgid "" +"There is also a command line shortcut for running :func:`testmod`, see " +"section :ref:`doctest-cli`." +msgstr "" + +#: ../../library/doctest.rst:183 +msgid "" +"For more information on :func:`testmod`, see section :ref:`doctest-basic-" +"api`." +msgstr "" + +#: ../../library/doctest.rst:189 +msgid "Simple Usage: Checking Examples in a Text File" +msgstr "" + +#: ../../library/doctest.rst:191 +msgid "" +"Another simple application of doctest is testing interactive examples in a " +"text file. This can be done with the :func:`testfile` function::" +msgstr "" + +#: ../../library/doctest.rst:194 +msgid "" +"import doctest\n" +"doctest.testfile(\"example.txt\")" +msgstr "" +"import doctest\n" +"doctest.testfile(\"example.txt\")" + +#: ../../library/doctest.rst:197 +msgid "" +"That short script executes and verifies any interactive Python examples " +"contained in the file :file:`example.txt`. The file content is treated as " +"if it were a single giant docstring; the file doesn't need to contain a " +"Python program! For example, perhaps :file:`example.txt` contains this:" +msgstr "" + +#: ../../library/doctest.rst:202 +msgid "" +"The ``example`` module\n" +"======================\n" +"\n" +"Using ``factorial``\n" +"-------------------\n" +"\n" +"This is an example text file in reStructuredText format. First import\n" +"``factorial`` from the ``example`` module:\n" +"\n" +" >>> from example import factorial\n" +"\n" +"Now use it:\n" +"\n" +" >>> factorial(6)\n" +" 120" +msgstr "" +"The ``example`` module\n" +"======================\n" +"\n" +"Using ``factorial``\n" +"-------------------\n" +"\n" +"This is an example text file in reStructuredText format. First import\n" +"``factorial`` from the ``example`` module:\n" +"\n" +" >>> from example import factorial\n" +"\n" +"Now use it:\n" +"\n" +" >>> factorial(6)\n" +" 120" + +#: ../../library/doctest.rst:220 +msgid "" +"Running ``doctest.testfile(\"example.txt\")`` then finds the error in this " +"documentation::" +msgstr "" + +#: ../../library/doctest.rst:223 +msgid "" +"File \"./example.txt\", line 14, in example.txt\n" +"Failed example:\n" +" factorial(6)\n" +"Expected:\n" +" 120\n" +"Got:\n" +" 720" +msgstr "" +"File \"./example.txt\", line 14, in example.txt\n" +"Failed example:\n" +" factorial(6)\n" +"Expected:\n" +" 120\n" +"Got:\n" +" 720" + +#: ../../library/doctest.rst:231 +msgid "" +"As with :func:`testmod`, :func:`testfile` won't display anything unless an " +"example fails. If an example does fail, then the failing example(s) and the " +"cause(s) of the failure(s) are printed to stdout, using the same format " +"as :func:`!testmod`." +msgstr "" + +#: ../../library/doctest.rst:236 +msgid "" +"By default, :func:`testfile` looks for files in the calling module's " +"directory. See section :ref:`doctest-basic-api` for a description of the " +"optional arguments that can be used to tell it to look for files in other " +"locations." +msgstr "" + +#: ../../library/doctest.rst:240 +msgid "" +"Like :func:`testmod`, :func:`testfile`'s verbosity can be set with the ``-" +"v`` command-line switch or with the optional keyword argument *verbose*." +msgstr "" + +#: ../../library/doctest.rst:244 +msgid "" +"There is also a command line shortcut for running :func:`testfile`, see " +"section :ref:`doctest-cli`." +msgstr "" + +#: ../../library/doctest.rst:247 +msgid "" +"For more information on :func:`testfile`, see section :ref:`doctest-basic-" +"api`." +msgstr "" + +#: ../../library/doctest.rst:253 +msgid "Command-line Usage" +msgstr "命令列用法" + +#: ../../library/doctest.rst:255 +msgid "" +"The :mod:`doctest` module can be invoked as a script from the command line:" +msgstr "可以從命令列以腳本方式叫用 :mod:`doctest` 模組：" + +#: ../../library/doctest.rst:257 +msgid "python -m doctest [-v] [-o OPTION] [-f] file [file ...]" +msgstr "python -m doctest [-v] [-o OPTION] [-f] file [file ...]" + +#: ../../library/doctest.rst:265 +msgid "" +"Detailed report of all examples tried is printed to standard output, along " +"with assorted summaries at the end::" +msgstr "" + +#: ../../library/doctest.rst:268 +msgid "python -m doctest -v example.py" +msgstr "python -m doctest -v example.py" + +#: ../../library/doctest.rst:270 +msgid "" +"This will import :file:`example.py` as a standalone module and " +"run :func:`testmod` on it. Note that this may not work correctly if the file " +"is part of a package and imports other submodules from that package." +msgstr "" + +#: ../../library/doctest.rst:274 +msgid "" +"If the file name does not end with :file:`.py`, :mod:`!doctest` infers that " +"it must be run with :func:`testfile` instead::" +msgstr "" + +#: ../../library/doctest.rst:277 +msgid "python -m doctest -v example.txt" +msgstr "python -m doctest -v example.txt" + +#: ../../library/doctest.rst:281 +msgid "" +"Option flags control various aspects of doctest's behavior, see " +"section :ref:`doctest-options`." +msgstr "" + +#: ../../library/doctest.rst:288 +msgid "This is shorthand for ``-o FAIL_FAST``." +msgstr "" + +#: ../../library/doctest.rst:296 +msgid "How It Works" +msgstr "運作方式" + +#: ../../library/doctest.rst:298 +msgid "" +"This section examines in detail how doctest works: which docstrings it looks " +"at, how it finds interactive examples, what execution context it uses, how " +"it handles exceptions, and how option flags can be used to control its " +"behavior. This is the information that you need to know to write doctest " +"examples; for information about actually running doctest on these examples, " +"see the following sections." +msgstr "" + +#: ../../library/doctest.rst:309 +msgid "Which Docstrings Are Examined?" +msgstr "" + +#: ../../library/doctest.rst:311 +msgid "" +"The module docstring, and all function, class and method docstrings are " +"searched. Objects imported into the module are not searched." +msgstr "" + +#: ../../library/doctest.rst:321 +msgid "" +"In addition, there are cases when you want tests to be part of a module but " +"not part of the help text, which requires that the tests not be included in " +"the docstring. Doctest looks for a module-level variable called ``__test__`` " +"and uses it to locate other tests. If ``M.__test__`` exists, it must be a " +"dict, and each entry maps a (string) name to a function object, class " +"object, or string. Function and class object docstrings found from " +"``M.__test__`` are searched, and strings are treated as if they were " +"docstrings. In output, a key ``K`` in ``M.__test__`` appears with name " +"``M.__test__.K``." +msgstr "" + +#: ../../library/doctest.rst:330 +msgid "For example, place this block of code at the top of :file:`example.py`:" +msgstr "" + +#: ../../library/doctest.rst:332 +msgid "" +"__test__ = {\n" +" 'numbers': \"\"\"\n" +">>> factorial(6)\n" +"720\n" +"\n" +">>> [factorial(n) for n in range(6)]\n" +"[1, 1, 2, 6, 24, 120]\n" +"\"\"\"\n" +"}" +msgstr "" +"__test__ = {\n" +" 'numbers': \"\"\"\n" +">>> factorial(6)\n" +"720\n" +"\n" +">>> [factorial(n) for n in range(6)]\n" +"[1, 1, 2, 6, 24, 120]\n" +"\"\"\"\n" +"}" + +#: ../../library/doctest.rst:344 +msgid "" +"The value of ``example.__test__[\"numbers\"]`` will be treated as a " +"docstring and all the tests inside it will be run. It is important to note " +"that the value can be mapped to a function, class object, or module; if " +"so, :mod:`!doctest` searches them recursively for docstrings, which are then " +"scanned for tests." +msgstr "" + +#: ../../library/doctest.rst:350 +msgid "" +"Any classes found are recursively searched similarly, to test docstrings in " +"their contained methods and nested classes." +msgstr "" + +#: ../../library/doctest.rst:355 +msgid "" +"``doctest`` can only automatically discover classes and functions that are " +"defined at the module level or inside other classes." +msgstr "" + +#: ../../library/doctest.rst:358 +msgid "" +"Since nested classes and functions only exist when an outer function is " +"called, they cannot be discovered. Define them outside to make them visible." +msgstr "" + +#: ../../library/doctest.rst:364 +msgid "How are Docstring Examples Recognized?" +msgstr "" + +#: ../../library/doctest.rst:366 +msgid "" +"In most cases a copy-and-paste of an interactive console session works fine, " +"but doctest isn't trying to do an exact emulation of any specific Python " +"shell." +msgstr "" + +#: ../../library/doctest.rst:371 +msgid "" +">>> # comments are ignored\n" +">>> x = 12\n" +">>> x\n" +"12\n" +">>> if x == 13:\n" +"... print(\"yes\")\n" +"... else:\n" +"... print(\"no\")\n" +"... print(\"NO\")\n" +"... print(\"NO!!!\")\n" +"...\n" +"no\n" +"NO\n" +"NO!!!\n" +">>>" +msgstr "" +">>> # 註解會被忽略\n" +">>> x = 12\n" +">>> x\n" +"12\n" +">>> if x == 13:\n" +"... print(\"yes\")\n" +"... else:\n" +"... print(\"no\")\n" +"... print(\"NO\")\n" +"... print(\"NO!!!\")\n" +"...\n" +"no\n" +"NO\n" +"NO!!!\n" +">>>" + +#: ../../library/doctest.rst:391 +msgid "" +"Any expected output must immediately follow the final ``'>>> '`` or ``'... " +"'`` line containing the code, and the expected output (if any) extends to " +"the next ``'>>> '`` or all-whitespace line." +msgstr "" + +#: ../../library/doctest.rst:395 +msgid "The fine print:" +msgstr "" + +#: ../../library/doctest.rst:397 +msgid "" +"Expected output cannot contain an all-whitespace line, since such a line is " +"taken to signal the end of expected output. If expected output does contain " +"a blank line, put ```` in your doctest example each place a blank " +"line is expected." +msgstr "" + +#: ../../library/doctest.rst:402 +msgid "" +"All hard tab characters are expanded to spaces, using 8-column tab stops. " +"Tabs in output generated by the tested code are not modified. Because any " +"hard tabs in the sample output *are* expanded, this means that if the code " +"output includes hard tabs, the only way the doctest can pass is if " +"the :const:`NORMALIZE_WHITESPACE` option or :ref:`directive ` is in effect. Alternatively, the test can be rewritten to " +"capture the output and compare it to an expected value as part of the test. " +"This handling of tabs in the source was arrived at through trial and error, " +"and has proven to be the least error prone way of handling them. It is " +"possible to use a different algorithm for handling tabs by writing a " +"custom :class:`DocTestParser` class." +msgstr "" + +#: ../../library/doctest.rst:414 +msgid "" +"Output to stdout is captured, but not output to stderr (exception tracebacks " +"are captured via a different means)." +msgstr "" + +#: ../../library/doctest.rst:417 +msgid "" +"If you continue a line via backslashing in an interactive session, or for " +"any other reason use a backslash, you should use a raw docstring, which will " +"preserve your backslashes exactly as you type them::" +msgstr "" + +#: ../../library/doctest.rst:421 +msgid "" +">>> def f(x):\n" +"... r'''Backslashes in a raw docstring: m\\n'''\n" +"...\n" +">>> print(f.__doc__)\n" +"Backslashes in a raw docstring: m\\n" +msgstr "" + +#: ../../library/doctest.rst:427 +msgid "" +"Otherwise, the backslash will be interpreted as part of the string. For " +"example, the ``\\n`` above would be interpreted as a newline character. " +"Alternatively, you can double each backslash in the doctest version (and not " +"use a raw string)::" +msgstr "" + +#: ../../library/doctest.rst:431 +msgid "" +">>> def f(x):\n" +"... '''Backslashes in a raw docstring: m\\\\n'''\n" +"...\n" +">>> print(f.__doc__)\n" +"Backslashes in a raw docstring: m\\n" +msgstr "" + +#: ../../library/doctest.rst:437 +msgid "The starting column doesn't matter::" +msgstr "" + +#: ../../library/doctest.rst:439 +msgid "" +">>> assert \"Easy!\"\n" +" >>> import math\n" +" >>> math.floor(1.9)\n" +" 1" +msgstr "" +">>> assert \"Easy!\"\n" +" >>> import math\n" +" >>> math.floor(1.9)\n" +" 1" + +#: ../../library/doctest.rst:444 +msgid "" +"and as many leading whitespace characters are stripped from the expected " +"output as appeared in the initial ``'>>> '`` line that started the example." +msgstr "" + +#: ../../library/doctest.rst:451 +msgid "What's the Execution Context?" +msgstr "" + +#: ../../library/doctest.rst:453 +msgid "" +"By default, each time :mod:`doctest` finds a docstring to test, it uses a " +"*shallow copy* of :mod:`!M`'s globals, so that running tests doesn't change " +"the module's real globals, and so that one test in :mod:`!M` can't leave " +"behind crumbs that accidentally allow another test to work. This means " +"examples can freely use any names defined at top-level in :mod:`!M`, and " +"names defined earlier in the docstring being run. Examples cannot see names " +"defined in other docstrings." +msgstr "" + +#: ../../library/doctest.rst:461 +msgid "" +"You can force use of your own dict as the execution context by passing " +"``globs=your_dict`` to :func:`testmod` or :func:`testfile` instead." +msgstr "" + +#: ../../library/doctest.rst:468 +msgid "What About Exceptions?" +msgstr "" + +#: ../../library/doctest.rst:470 +msgid "" +"No problem, provided that the traceback is the only output produced by the " +"example: just paste in the traceback. [#]_ Since tracebacks contain details " +"that are likely to change rapidly (for example, exact file paths and line " +"numbers), this is one case where doctest works hard to be flexible in what " +"it accepts." +msgstr "" + +#: ../../library/doctest.rst:476 +msgid "Simple example::" +msgstr "簡單範例： ::" + +#: ../../library/doctest.rst:478 +msgid "" +">>> [1, 2, 3].remove(42)\n" +"Traceback (most recent call last):\n" +" File \"\", line 1, in \n" +"ValueError: list.remove(x): x not in list" +msgstr "" +">>> [1, 2, 3].remove(42)\n" +"Traceback (most recent call last):\n" +" File \"\", line 1, in \n" +"ValueError: list.remove(x): x not in list" + +#: ../../library/doctest.rst:483 +msgid "" +"That doctest succeeds if :exc:`ValueError` is raised, with the " +"``list.remove(x): x not in list`` detail as shown." +msgstr "" + +#: ../../library/doctest.rst:486 +msgid "" +"The expected output for an exception must start with a traceback header, " +"which may be either of the following two lines, indented the same as the " +"first line of the example::" +msgstr "" + +#: ../../library/doctest.rst:490 +msgid "" +"Traceback (most recent call last):\n" +"Traceback (innermost last):" +msgstr "" +"Traceback (most recent call last):\n" +"Traceback (innermost last):" + +#: ../../library/doctest.rst:493 +msgid "" +"The traceback header is followed by an optional traceback stack, whose " +"contents are ignored by doctest. The traceback stack is typically omitted, " +"or copied verbatim from an interactive session." +msgstr "" + +#: ../../library/doctest.rst:497 +msgid "" +"The traceback stack is followed by the most interesting part: the line(s) " +"containing the exception type and detail. This is usually the last line of " +"a traceback, but can extend across multiple lines if the exception has a " +"multi-line detail::" +msgstr "" + +#: ../../library/doctest.rst:502 +msgid "" +">>> raise ValueError('multi\\n line\\ndetail')\n" +"Traceback (most recent call last):\n" +" File \"\", line 1, in \n" +"ValueError: multi\n" +" line\n" +"detail" +msgstr "" +">>> raise ValueError('multi\\n line\\ndetail')\n" +"Traceback (most recent call last):\n" +" File \"\", line 1, in \n" +"ValueError: multi\n" +" line\n" +"detail" + +#: ../../library/doctest.rst:509 +msgid "" +"The last three lines (starting with :exc:`ValueError`) are compared against " +"the exception's type and detail, and the rest are ignored." +msgstr "" + +#: ../../library/doctest.rst:512 +msgid "" +"Best practice is to omit the traceback stack, unless it adds significant " +"documentation value to the example. So the last example is probably better " +"as::" +msgstr "" + +#: ../../library/doctest.rst:515 +msgid "" +">>> raise ValueError('multi\\n line\\ndetail')\n" +"Traceback (most recent call last):\n" +" ...\n" +"ValueError: multi\n" +" line\n" +"detail" +msgstr "" +">>> raise ValueError('multi\\n line\\ndetail')\n" +"Traceback (most recent call last):\n" +" ...\n" +"ValueError: multi\n" +" line\n" +"detail" + +#: ../../library/doctest.rst:522 +msgid "" +"Note that tracebacks are treated very specially. In particular, in the " +"rewritten example, the use of ``...`` is independent of " +"doctest's :const:`ELLIPSIS` option. The ellipsis in that example could be " +"left out, or could just as well be three (or three hundred) commas or " +"digits, or an indented transcript of a Monty Python skit." +msgstr "" + +#: ../../library/doctest.rst:528 +msgid "Some details you should read once, but won't need to remember:" +msgstr "" + +#: ../../library/doctest.rst:530 +msgid "" +"Doctest can't guess whether your expected output came from an exception " +"traceback or from ordinary printing. So, e.g., an example that expects " +"``ValueError: 42 is prime`` will pass whether :exc:`ValueError` is actually " +"raised or if the example merely prints that traceback text. In practice, " +"ordinary output rarely begins with a traceback header line, so this doesn't " +"create real problems." +msgstr "" + +#: ../../library/doctest.rst:537 +msgid "" +"Each line of the traceback stack (if present) must be indented further than " +"the first line of the example, *or* start with a non-alphanumeric character. " +"The first line following the traceback header indented the same and starting " +"with an alphanumeric is taken to be the start of the exception detail. Of " +"course this does the right thing for genuine tracebacks." +msgstr "" + +#: ../../library/doctest.rst:543 +msgid "" +"When the :const:`IGNORE_EXCEPTION_DETAIL` doctest option is specified, " +"everything following the leftmost colon and any module information in the " +"exception name is ignored." +msgstr "" + +#: ../../library/doctest.rst:547 +msgid "" +"The interactive shell omits the traceback header line for " +"some :exc:`SyntaxError`\\ s. But doctest uses the traceback header line to " +"distinguish exceptions from non-exceptions. So in the rare case where you " +"need to test a :exc:`!SyntaxError` that omits the traceback header, you will " +"need to manually add the traceback header line to your test example." +msgstr "" + +#: ../../library/doctest.rst:555 +msgid "" +"For some exceptions, Python displays the position of the error using ``^`` " +"markers and tildes::" +msgstr "" + +#: ../../library/doctest.rst:558 +msgid "" +">>> 1 + None\n" +" File \"\", line 1\n" +" 1 + None\n" +" ~~^~~~~~\n" +"TypeError: unsupported operand type(s) for +: 'int' and 'NoneType'" +msgstr "" +">>> 1 + None\n" +" File \"\", line 1\n" +" 1 + None\n" +" ~~^~~~~~\n" +"TypeError: unsupported operand type(s) for +: 'int' and 'NoneType'" + +#: ../../library/doctest.rst:564 +msgid "" +"Since the lines showing the position of the error come before the exception " +"type and detail, they are not checked by doctest. For example, the " +"following test would pass, even though it puts the ``^`` marker in the wrong " +"location::" +msgstr "" + +#: ../../library/doctest.rst:568 +msgid "" +">>> 1 + None\n" +" File \"\", line 1\n" +" 1 + None\n" +" ^~~~~~~~\n" +"TypeError: unsupported operand type(s) for +: 'int' and 'NoneType'" +msgstr "" +">>> 1 + None\n" +" File \"\", line 1\n" +" 1 + None\n" +" ^~~~~~~~\n" +"TypeError: unsupported operand type(s) for +: 'int' and 'NoneType'" + +#: ../../library/doctest.rst:579 +msgid "Option Flags" +msgstr "可選旗標" + +#: ../../library/doctest.rst:581 +msgid "" +"A number of option flags control various aspects of doctest's behavior. " +"Symbolic names for the flags are supplied as module constants, which can " +"be :ref:`bitwise ORed ` together and passed to various functions. " +"The names can also be used in :ref:`doctest directives `, and may be passed to the doctest command line interface via " +"the ``-o`` option." +msgstr "" + +#: ../../library/doctest.rst:587 +msgid "" +"The first group of options define test semantics, controlling aspects of how " +"doctest decides whether actual output matches an example's expected output:" +msgstr "" + +#: ../../library/doctest.rst:593 +msgid "" +"By default, if an expected output block contains just ``1``, an actual " +"output block containing just ``1`` or just ``True`` is considered to be a " +"match, and similarly for ``0`` versus ``False``. " +"When :const:`DONT_ACCEPT_TRUE_FOR_1` is specified, neither substitution is " +"allowed. The default behavior caters to that Python changed the return type " +"of many functions from integer to boolean; doctests expecting \"little " +"integer\" output still work in these cases. This option will probably go " +"away, but not for several years." +msgstr "" + +#: ../../library/doctest.rst:605 +msgid "" +"By default, if an expected output block contains a line containing only the " +"string ````, then that line will match a blank line in the actual " +"output. Because a genuinely blank line delimits the expected output, this " +"is the only way to communicate that a blank line is expected. " +"When :const:`DONT_ACCEPT_BLANKLINE` is specified, this substitution is not " +"allowed." +msgstr "" + +#: ../../library/doctest.rst:614 +msgid "" +"When specified, all sequences of whitespace (blanks and newlines) are " +"treated as equal. Any sequence of whitespace within the expected output " +"will match any sequence of whitespace within the actual output. By default, " +"whitespace must match exactly. :const:`NORMALIZE_WHITESPACE` is especially " +"useful when a line of expected output is very long, and you want to wrap it " +"across multiple lines in your source." +msgstr "" + +#: ../../library/doctest.rst:625 +msgid "" +"When specified, an ellipsis marker (``...``) in the expected output can " +"match any substring in the actual output. This includes substrings that " +"span line boundaries, and empty substrings, so it's best to keep usage of " +"this simple. Complicated uses can lead to the same kinds of \"oops, it " +"matched too much!\" surprises that ``.*`` is prone to in regular expressions." +msgstr "" + +#: ../../library/doctest.rst:634 +msgid "" +"When specified, doctests expecting exceptions pass so long as an exception " +"of the expected type is raised, even if the details (message and fully " +"qualified exception name) don't match." +msgstr "" + +#: ../../library/doctest.rst:638 +msgid "" +"For example, an example expecting ``ValueError: 42`` will pass if the actual " +"exception raised is ``ValueError: 3*14``, but will fail if, say, " +"a :exc:`TypeError` is raised instead. It will also ignore any fully " +"qualified name included before the exception class, which can vary between " +"implementations and versions of Python and the code/libraries in use. Hence, " +"all three of these variations will work with the flag specified:" +msgstr "" + +#: ../../library/doctest.rst:646 +msgid "" +">>> raise Exception('message')\n" +"Traceback (most recent call last):\n" +"Exception: message\n" +"\n" +">>> raise Exception('message')\n" +"Traceback (most recent call last):\n" +"builtins.Exception: message\n" +"\n" +">>> raise Exception('message')\n" +"Traceback (most recent call last):\n" +"__main__.Exception: message" +msgstr "" +">>> raise Exception('message')\n" +"Traceback (most recent call last):\n" +"Exception: message\n" +"\n" +">>> raise Exception('message')\n" +"Traceback (most recent call last):\n" +"builtins.Exception: message\n" +"\n" +">>> raise Exception('message')\n" +"Traceback (most recent call last):\n" +"__main__.Exception: message" + +#: ../../library/doctest.rst:660 +msgid "" +"Note that :const:`ELLIPSIS` can also be used to ignore the details of the " +"exception message, but such a test may still fail based on whether the " +"module name is present or matches exactly." +msgstr "" + +#: ../../library/doctest.rst:664 +msgid "" +":const:`IGNORE_EXCEPTION_DETAIL` now also ignores any information relating " +"to the module containing the exception under test." +msgstr "" + +#: ../../library/doctest.rst:671 +msgid "" +"When specified, do not run the example at all. This can be useful in " +"contexts where doctest examples serve as both documentation and test cases, " +"and an example should be included for documentation purposes, but should not " +"be checked. E.g., the example's output might be random; or the example " +"might depend on resources which would be unavailable to the test driver." +msgstr "" + +#: ../../library/doctest.rst:677 +msgid "" +"The SKIP flag can also be used for temporarily \"commenting out\" examples." +msgstr "" + +#: ../../library/doctest.rst:682 +msgid "A bitmask or'ing together all the comparison flags above." +msgstr "" + +#: ../../library/doctest.rst:684 +msgid "The second group of options controls how test failures are reported:" +msgstr "" + +#: ../../library/doctest.rst:689 +msgid "" +"When specified, failures that involve multi-line expected and actual outputs " +"are displayed using a unified diff." +msgstr "" + +#: ../../library/doctest.rst:695 +msgid "" +"When specified, failures that involve multi-line expected and actual outputs " +"will be displayed using a context diff." +msgstr "" + +#: ../../library/doctest.rst:701 +msgid "" +"When specified, differences are computed by ``difflib.Differ``, using the " +"same algorithm as the popular :file:`ndiff.py` utility. This is the only " +"method that marks differences within lines as well as across lines. For " +"example, if a line of expected output contains digit ``1`` where actual " +"output contains letter ``l``, a line is inserted with a caret marking the " +"mismatching column positions." +msgstr "" + +#: ../../library/doctest.rst:710 +msgid "" +"When specified, display the first failing example in each doctest, but " +"suppress output for all remaining examples. This will prevent doctest from " +"reporting correct examples that break because of earlier failures; but it " +"might also hide incorrect examples that fail independently of the first " +"failure. When :const:`REPORT_ONLY_FIRST_FAILURE` is specified, the " +"remaining examples are still run, and still count towards the total number " +"of failures reported; only the output is suppressed." +msgstr "" + +#: ../../library/doctest.rst:721 +msgid "" +"When specified, exit after the first failing example and don't attempt to " +"run the remaining examples. Thus, the number of failures reported will be at " +"most 1. This flag may be useful during debugging, since examples after the " +"first failure won't even produce debugging output." +msgstr "" + +#: ../../library/doctest.rst:729 +msgid "A bitmask or'ing together all the reporting flags above." +msgstr "" + +#: ../../library/doctest.rst:732 +msgid "" +"There is also a way to register new option flag names, though this isn't " +"useful unless you intend to extend :mod:`doctest` internals via subclassing:" +msgstr "" + +#: ../../library/doctest.rst:738 +msgid "" +"Create a new option flag with a given name, and return the new flag's " +"integer value. :func:`register_optionflag` can be used when " +"subclassing :class:`OutputChecker` or :class:`DocTestRunner` to create new " +"options that are supported by your subclasses. :func:`register_optionflag` " +"should always be called using the following idiom::" +msgstr "" + +#: ../../library/doctest.rst:744 +msgid "MY_FLAG = register_optionflag('MY_FLAG')" +msgstr "MY_FLAG = register_optionflag('MY_FLAG')" + +#: ../../library/doctest.rst:754 +msgid "Directives" +msgstr "" + +#: ../../library/doctest.rst:756 +msgid "" +"Doctest directives may be used to modify the :ref:`option flags ` for an individual example. Doctest directives are special Python " +"comments following an example's source code:" +msgstr "" + +#: ../../library/doctest.rst:767 +msgid "" +"Whitespace is not allowed between the ``+`` or ``-`` and the directive " +"option name. The directive option name can be any of the option flag names " +"explained above." +msgstr "" + +#: ../../library/doctest.rst:771 +msgid "" +"An example's doctest directives modify doctest's behavior for that single " +"example. Use ``+`` to enable the named behavior, or ``-`` to disable it." +msgstr "" + +#: ../../library/doctest.rst:774 +msgid "For example, this test passes:" +msgstr "舉例來說，這個測試會通過：" + +#: ../../library/doctest.rst:776 +msgid "" +">>> print(list(range(20))) # doctest: +NORMALIZE_WHITESPACE\n" +"[0, 1, 2, 3, 4, 5, 6, 7, 8, 9,\n" +"10, 11, 12, 13, 14, 15, 16, 17, 18, 19]" +msgstr "" +">>> print(list(range(20))) # doctest: +NORMALIZE_WHITESPACE\n" +"[0, 1, 2, 3, 4, 5, 6, 7, 8, 9,\n" +"10, 11, 12, 13, 14, 15, 16, 17, 18, 19]" + +#: ../../library/doctest.rst:783 +msgid "" +"Without the directive it would fail, both because the actual output doesn't " +"have two blanks before the single-digit list elements, and because the " +"actual output is on a single line. This test also passes, and also requires " +"a directive to do so:" +msgstr "" + +#: ../../library/doctest.rst:788 +msgid "" +">>> print(list(range(20))) # doctest: +ELLIPSIS\n" +"[0, 1, ..., 18, 19]" +msgstr "" +">>> print(list(range(20))) # doctest: +ELLIPSIS\n" +"[0, 1, ..., 18, 19]" + +#: ../../library/doctest.rst:794 +msgid "" +"Multiple directives can be used on a single physical line, separated by " +"commas:" +msgstr "" + +#: ../../library/doctest.rst:797 +msgid "" +">>> print(list(range(20))) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE\n" +"[0, 1, ..., 18, 19]" +msgstr "" +">>> print(list(range(20))) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE\n" +"[0, 1, ..., 18, 19]" + +#: ../../library/doctest.rst:803 +msgid "" +"If multiple directive comments are used for a single example, then they are " +"combined:" +msgstr "" + +#: ../../library/doctest.rst:806 +msgid "" +">>> print(list(range(20))) # doctest: +ELLIPSIS\n" +"... # doctest: +NORMALIZE_WHITESPACE\n" +"[0, 1, ..., 18, 19]" +msgstr "" +">>> print(list(range(20))) # doctest: +ELLIPSIS\n" +"... # doctest: +NORMALIZE_WHITESPACE\n" +"[0, 1, ..., 18, 19]" + +#: ../../library/doctest.rst:813 +msgid "" +"As the previous example shows, you can add ``...`` lines to your example " +"containing only directives. This can be useful when an example is too long " +"for a directive to comfortably fit on the same line:" +msgstr "" + +#: ../../library/doctest.rst:817 +msgid "" +">>> print(list(range(5)) + list(range(10, 20)) + list(range(30, 40)))\n" +"... # doctest: +ELLIPSIS\n" +"[0, ..., 4, 10, ..., 19, 30, ..., 39]" +msgstr "" +">>> print(list(range(5)) + list(range(10, 20)) + list(range(30, 40)))\n" +"... # doctest: +ELLIPSIS\n" +"[0, ..., 4, 10, ..., 19, 30, ..., 39]" + +#: ../../library/doctest.rst:824 +msgid "" +"Note that since all options are disabled by default, and directives apply " +"only to the example they appear in, enabling options (via ``+`` in a " +"directive) is usually the only meaningful choice. However, option flags can " +"also be passed to functions that run doctests, establishing different " +"defaults. In such cases, disabling an option via ``-`` in a directive can " +"be useful." +msgstr "" + +#: ../../library/doctest.rst:834 +msgid "Warnings" +msgstr "警告" + +#: ../../library/doctest.rst:836 +msgid "" +":mod:`doctest` is serious about requiring exact matches in expected output. " +"If even a single character doesn't match, the test fails. This will " +"probably surprise you a few times, as you learn exactly what Python does and " +"doesn't guarantee about output. For example, when printing a set, Python " +"doesn't guarantee that the element is printed in any particular order, so a " +"test like ::" +msgstr "" + +#: ../../library/doctest.rst:842 +msgid "" +">>> foo()\n" +"{\"spam\", \"eggs\"}" +msgstr "" +">>> foo()\n" +"{\"spam\", \"eggs\"}" + +#: ../../library/doctest.rst:845 +msgid "is vulnerable! One workaround is to do ::" +msgstr "" + +#: ../../library/doctest.rst:847 +msgid "" +">>> foo() == {\"spam\", \"eggs\"}\n" +"True" +msgstr "" +">>> foo() == {\"spam\", \"eggs\"}\n" +"True" + +#: ../../library/doctest.rst:850 +msgid "instead. Another is to do ::" +msgstr "" + +#: ../../library/doctest.rst:852 +msgid "" +">>> d = sorted(foo())\n" +">>> d\n" +"['eggs', 'spam']" +msgstr "" +">>> d = sorted(foo())\n" +">>> d\n" +"['eggs', 'spam']" + +#: ../../library/doctest.rst:856 +msgid "There are others, but you get the idea." +msgstr "" + +#: ../../library/doctest.rst:858 +msgid "Another bad idea is to print things that embed an object address, like" +msgstr "" + +#: ../../library/doctest.rst:860 +msgid "" +">>> id(1.0) # certain to fail some of the time\n" +"7948648\n" +">>> class C: pass\n" +">>> C() # the default repr() for instances embeds an address\n" +"" +msgstr "" + +#: ../../library/doctest.rst:868 +msgid "" +"The :const:`ELLIPSIS` directive gives a nice approach for the last example:" +msgstr "" + +#: ../../library/doctest.rst:870 +msgid "" +">>> C() # doctest: +ELLIPSIS\n" +"" +msgstr "" +">>> C() # doctest: +ELLIPSIS\n" +"" + +#: ../../library/doctest.rst:876 +msgid "" +"Floating-point numbers are also subject to small output variations across " +"platforms, because Python defers to the platform C library for some floating-" +"point calculations, and C libraries vary widely in quality here. ::" +msgstr "" + +#: ../../library/doctest.rst:880 +msgid "" +">>> 1000**0.1 # risky\n" +"1.9952623149688797\n" +">>> round(1000**0.1, 9) # safer\n" +"1.995262315\n" +">>> print(f'{1000**0.1:.4f}') # much safer\n" +"1.9953" +msgstr "" +">>> 1000**0.1 # 有風險\n" +"1.9952623149688797\n" +">>> round(1000**0.1, 9) # 更安全\n" +"1.995262315\n" +">>> print(f'{1000**0.1:.4f}') # 更加安全\n" +"1.9953" + +#: ../../library/doctest.rst:887 +msgid "" +"Numbers of the form ``I/2.**J`` are safe across all platforms, and I often " +"contrive doctest examples to produce numbers of that form::" +msgstr "" + +#: ../../library/doctest.rst:890 +msgid "" +">>> 3./4 # utterly safe\n" +"0.75" +msgstr "" +">>> 3./4 # utterly safe\n" +"0.75" + +#: ../../library/doctest.rst:893 +msgid "" +"Simple fractions are also easier for people to understand, and that makes " +"for better documentation." +msgstr "" + +#: ../../library/doctest.rst:900 +msgid "Basic API" +msgstr "基礎 API" + +#: ../../library/doctest.rst:902 +msgid "" +"The functions :func:`testmod` and :func:`testfile` provide a simple " +"interface to doctest that should be sufficient for most basic uses. For a " +"less formal introduction to these two functions, see sections :ref:`doctest-" +"simple-testmod` and :ref:`doctest-simple-testfile`." +msgstr "" + +#: ../../library/doctest.rst:910 +msgid "" +"All arguments except *filename* are optional, and should be specified in " +"keyword form." +msgstr "" + +#: ../../library/doctest.rst:913 +msgid "" +"Test examples in the file named *filename*. Return ``(failure_count, " +"test_count)``." +msgstr "" + +#: ../../library/doctest.rst:916 +msgid "" +"Optional argument *module_relative* specifies how the filename should be " +"interpreted:" +msgstr "" + +#: ../../library/doctest.rst:919 +msgid "" +"If *module_relative* is ``True`` (the default), then *filename* specifies an " +"OS-independent module-relative path. By default, this path is relative to " +"the calling module's directory; but if the *package* argument is specified, " +"then it is relative to that package. To ensure OS-independence, *filename* " +"should use ``/`` characters to separate path segments, and may not be an " +"absolute path (i.e., it may not begin with ``/``)." +msgstr "" + +#: ../../library/doctest.rst:926 +msgid "" +"If *module_relative* is ``False``, then *filename* specifies an OS-specific " +"path. The path may be absolute or relative; relative paths are resolved " +"with respect to the current working directory." +msgstr "" + +#: ../../library/doctest.rst:930 +msgid "" +"Optional argument *name* gives the name of the test; by default, or if " +"``None``, ``os.path.basename(filename)`` is used." +msgstr "" + +#: ../../library/doctest.rst:933 +msgid "" +"Optional argument *package* is a Python package or the name of a Python " +"package whose directory should be used as the base directory for a module-" +"relative filename. If no package is specified, then the calling module's " +"directory is used as the base directory for module-relative filenames. It " +"is an error to specify *package* if *module_relative* is ``False``." +msgstr "" + +#: ../../library/doctest.rst:939 +msgid "" +"Optional argument *globs* gives a dict to be used as the globals when " +"executing examples. A new shallow copy of this dict is created for the " +"doctest, so its examples start with a clean slate. By default, or if " +"``None``, a new empty dict is used." +msgstr "" + +#: ../../library/doctest.rst:944 +msgid "" +"Optional argument *extraglobs* gives a dict merged into the globals used to " +"execute examples. This works like :meth:`dict.update`: if *globs* and " +"*extraglobs* have a common key, the associated value in *extraglobs* appears " +"in the combined dict. By default, or if ``None``, no extra globals are " +"used. This is an advanced feature that allows parameterization of " +"doctests. For example, a doctest can be written for a base class, using a " +"generic name for the class, then reused to test any number of subclasses by " +"passing an *extraglobs* dict mapping the generic name to the subclass to be " +"tested." +msgstr "" + +#: ../../library/doctest.rst:953 +msgid "" +"Optional argument *verbose* prints lots of stuff if true, and prints only " +"failures if false; by default, or if ``None``, it's true if and only if ``'-" +"v'`` is in :data:`sys.argv`." +msgstr "" + +#: ../../library/doctest.rst:957 +msgid "" +"Optional argument *report* prints a summary at the end when true, else " +"prints nothing at the end. In verbose mode, the summary is detailed, else " +"the summary is very brief (in fact, empty if all tests passed)." +msgstr "" + +#: ../../library/doctest.rst:961 +msgid "" +"Optional argument *optionflags* (default value ``0``) takes " +"the :ref:`bitwise OR ` of option flags. See section :ref:`doctest-" +"options`." +msgstr "" + +#: ../../library/doctest.rst:965 +msgid "" +"Optional argument *raise_on_error* defaults to false. If true, an exception " +"is raised upon the first failure or unexpected exception in an example. " +"This allows failures to be post-mortem debugged. Default behavior is to " +"continue running examples." +msgstr "" + +#: ../../library/doctest.rst:970 ../../library/doctest.rst:1113 +msgid "" +"Optional argument *parser* specifies a :class:`DocTestParser` (or subclass) " +"that should be used to extract tests from the files. It defaults to a " +"normal parser (i.e., ``DocTestParser()``)." +msgstr "" + +#: ../../library/doctest.rst:974 ../../library/doctest.rst:1117 +msgid "" +"Optional argument *encoding* specifies an encoding that should be used to " +"convert the file to unicode." +msgstr "" + +#: ../../library/doctest.rst:980 +msgid "" +"All arguments are optional, and all except for *m* should be specified in " +"keyword form." +msgstr "" + +#: ../../library/doctest.rst:983 +msgid "" +"Test examples in docstrings in functions and classes reachable from module " +"*m* (or module :mod:`__main__` if *m* is not supplied or is ``None``), " +"starting with ``m.__doc__``." +msgstr "" + +#: ../../library/doctest.rst:987 +msgid "" +"Also test examples reachable from dict ``m.__test__``, if it exists. " +"``m.__test__`` maps names (strings) to functions, classes and strings; " +"function and class docstrings are searched for examples; strings are " +"searched directly, as if they were docstrings." +msgstr "" + +#: ../../library/doctest.rst:992 +msgid "" +"Only docstrings attached to objects belonging to module *m* are searched." +msgstr "" + +#: ../../library/doctest.rst:994 +msgid "Return ``(failure_count, test_count)``." +msgstr "回傳 ``(failure_count, test_count)``。" + +#: ../../library/doctest.rst:996 +msgid "" +"Optional argument *name* gives the name of the module; by default, or if " +"``None``, ``m.__name__`` is used." +msgstr "" + +#: ../../library/doctest.rst:999 +msgid "" +"Optional argument *exclude_empty* defaults to false. If true, objects for " +"which no doctests are found are excluded from consideration. The default is " +"a backward compatibility hack, so that code still " +"using :meth:`doctest.master.summarize ` in " +"conjunction with :func:`testmod` continues to get output for objects with no " +"tests. The *exclude_empty* argument to the newer :class:`DocTestFinder` " +"constructor defaults to true." +msgstr "" + +#: ../../library/doctest.rst:1007 +msgid "" +"Optional arguments *extraglobs*, *verbose*, *report*, *optionflags*, " +"*raise_on_error*, and *globs* are the same as for function :func:`testfile` " +"above, except that *globs* defaults to ``m.__dict__``." +msgstr "" + +#: ../../library/doctest.rst:1014 +msgid "" +"Test examples associated with object *f*; for example, *f* may be a string, " +"a module, a function, or a class object." +msgstr "" + +#: ../../library/doctest.rst:1017 +msgid "" +"A shallow copy of dictionary argument *globs* is used for the execution " +"context." +msgstr "" + +#: ../../library/doctest.rst:1019 +msgid "" +"Optional argument *name* is used in failure messages, and defaults to " +"``\"NoName\"``." +msgstr "" + +#: ../../library/doctest.rst:1022 +msgid "" +"If optional argument *verbose* is true, output is generated even if there " +"are no failures. By default, output is generated only in case of an example " +"failure." +msgstr "" + +#: ../../library/doctest.rst:1025 +msgid "" +"Optional argument *compileflags* gives the set of flags that should be used " +"by the Python compiler when running the examples. By default, or if " +"``None``, flags are deduced corresponding to the set of future features " +"found in *globs*." +msgstr "" + +#: ../../library/doctest.rst:1029 +msgid "" +"Optional argument *optionflags* works as for function :func:`testfile` above." +msgstr "" + +#: ../../library/doctest.rst:1035 +msgid "Unittest API" +msgstr "Unittest API" + +#: ../../library/doctest.rst:1037 +msgid "" +"As your collection of doctest'ed modules grows, you'll want a way to run all " +"their doctests systematically. :mod:`doctest` provides two functions that " +"can be used to create :mod:`unittest` test suites from modules and text " +"files containing doctests. To integrate with :mod:`unittest` test " +"discovery, include a :ref:`load_tests ` function in " +"your test module::" +msgstr "" + +#: ../../library/doctest.rst:1043 +msgid "" +"import unittest\n" +"import doctest\n" +"import my_module_with_doctests\n" +"\n" +"def load_tests(loader, tests, ignore):\n" +" tests.addTests(doctest.DocTestSuite(my_module_with_doctests))\n" +" return tests" +msgstr "" +"import unittest\n" +"import doctest\n" +"import my_module_with_doctests\n" +"\n" +"def load_tests(loader, tests, ignore):\n" +" tests.addTests(doctest.DocTestSuite(my_module_with_doctests))\n" +" return tests" + +#: ../../library/doctest.rst:1051 +msgid "" +"There are two main functions for creating :class:`unittest.TestSuite` " +"instances from text files and modules with doctests:" +msgstr "" + +#: ../../library/doctest.rst:1057 +msgid "" +"Convert doctest tests from one or more text files to " +"a :class:`unittest.TestSuite`." +msgstr "" + +#: ../../library/doctest.rst:1060 +msgid "" +"The returned :class:`unittest.TestSuite` is to be run by the unittest " +"framework and runs the interactive examples in each file. If an example in " +"any file fails, then the synthesized unit test fails, and " +"a :exc:`~unittest.TestCase.failureException` exception is raised showing the " +"name of the file containing the test and a (sometimes approximate) line " +"number. If all the examples in a file are skipped, then the synthesized " +"unit test is also marked as skipped." +msgstr "" + +#: ../../library/doctest.rst:1067 +msgid "Pass one or more paths (as strings) to text files to be examined." +msgstr "" + +#: ../../library/doctest.rst:1069 +msgid "Options may be provided as keyword arguments:" +msgstr "" + +#: ../../library/doctest.rst:1071 +msgid "" +"Optional argument *module_relative* specifies how the filenames in *paths* " +"should be interpreted:" +msgstr "" + +#: ../../library/doctest.rst:1074 +msgid "" +"If *module_relative* is ``True`` (the default), then each filename in " +"*paths* specifies an OS-independent module-relative path. By default, this " +"path is relative to the calling module's directory; but if the *package* " +"argument is specified, then it is relative to that package. To ensure OS-" +"independence, each filename should use ``/`` characters to separate path " +"segments, and may not be an absolute path (i.e., it may not begin with ``/" +"``)." +msgstr "" + +#: ../../library/doctest.rst:1082 +msgid "" +"If *module_relative* is ``False``, then each filename in *paths* specifies " +"an OS-specific path. The path may be absolute or relative; relative paths " +"are resolved with respect to the current working directory." +msgstr "" + +#: ../../library/doctest.rst:1086 +msgid "" +"Optional argument *package* is a Python package or the name of a Python " +"package whose directory should be used as the base directory for module-" +"relative filenames in *paths*. If no package is specified, then the calling " +"module's directory is used as the base directory for module-relative " +"filenames. It is an error to specify *package* if *module_relative* is " +"``False``." +msgstr "" + +#: ../../library/doctest.rst:1093 +msgid "" +"Optional argument *setUp* specifies a set-up function for the test suite. " +"This is called before running the tests in each file. The *setUp* function " +"will be passed a :class:`DocTest` object. The *setUp* function can access " +"the test globals as the :attr:`~DocTest.globs` attribute of the test passed." +msgstr "" + +#: ../../library/doctest.rst:1098 +msgid "" +"Optional argument *tearDown* specifies a tear-down function for the test " +"suite. This is called after running the tests in each file. The *tearDown* " +"function will be passed a :class:`DocTest` object. The *tearDown* function " +"can access the test globals as the :attr:`~DocTest.globs` attribute of the " +"test passed." +msgstr "" + +#: ../../library/doctest.rst:1104 +msgid "" +"Optional argument *globs* is a dictionary containing the initial global " +"variables for the tests. A new copy of this dictionary is created for each " +"test. By default, *globs* is a new empty dictionary." +msgstr "" + +#: ../../library/doctest.rst:1108 +msgid "" +"Optional argument *optionflags* specifies the default doctest options for " +"the tests, created by or-ing together individual option flags. See " +"section :ref:`doctest-options`. See " +"function :func:`set_unittest_reportflags` below for a better way to set " +"reporting options." +msgstr "" + +#: ../../library/doctest.rst:1120 +msgid "" +"The global ``__file__`` is added to the globals provided to doctests loaded " +"from a text file using :func:`DocFileSuite`." +msgstr "" + +#: ../../library/doctest.rst:1126 +msgid "Convert doctest tests for a module to a :class:`unittest.TestSuite`." +msgstr "" + +#: ../../library/doctest.rst:1128 +msgid "" +"The returned :class:`unittest.TestSuite` is to be run by the unittest " +"framework and runs each doctest in the module. Each docstring is run as a " +"separate unit test. If any of the doctests fail, then the synthesized unit " +"test fails, and a :exc:`unittest.TestCase.failureException` exception is " +"raised showing the name of the file containing the test and a (sometimes " +"approximate) line number. If all the examples in a docstring are skipped, " +"then the" +msgstr "" + +#: ../../library/doctest.rst:1136 +msgid "" +"Optional argument *module* provides the module to be tested. It can be a " +"module object or a (possibly dotted) module name. If not specified, the " +"module calling this function is used." +msgstr "" + +#: ../../library/doctest.rst:1140 +msgid "" +"Optional argument *globs* is a dictionary containing the initial global " +"variables for the tests. A new copy of this dictionary is created for each " +"test. By default, *globs* is the module's :attr:`~module.__dict__`." +msgstr "" + +#: ../../library/doctest.rst:1144 +msgid "" +"Optional argument *extraglobs* specifies an extra set of global variables, " +"which is merged into *globs*. By default, no extra globals are used." +msgstr "" + +#: ../../library/doctest.rst:1147 +msgid "" +"Optional argument *test_finder* is the :class:`DocTestFinder` object (or a " +"drop-in replacement) that is used to extract doctests from the module." +msgstr "" + +#: ../../library/doctest.rst:1150 +msgid "" +"Optional arguments *setUp*, *tearDown*, and *optionflags* are the same as " +"for function :func:`DocFileSuite` above, but they are called for each " +"docstring." +msgstr "" + +#: ../../library/doctest.rst:1153 +msgid "This function uses the same search technique as :func:`testmod`." +msgstr "" + +#: ../../library/doctest.rst:1155 +msgid "" +":func:`DocTestSuite` returns an empty :class:`unittest.TestSuite` if " +"*module* contains no docstrings instead of raising :exc:`ValueError`." +msgstr "" + +#: ../../library/doctest.rst:1159 +msgid "" +"Under the covers, :func:`DocTestSuite` creates a :class:`unittest.TestSuite` " +"out of :class:`!doctest.DocTestCase` instances, and :class:`!DocTestCase` is " +"a subclass of :class:`unittest.TestCase`. :class:`!DocTestCase` isn't " +"documented here (it's an internal detail), but studying its code can answer " +"questions about the exact details of :mod:`unittest` integration." +msgstr "" + +#: ../../library/doctest.rst:1165 +msgid "" +"Similarly, :func:`DocFileSuite` creates a :class:`unittest.TestSuite` out " +"of :class:`!doctest.DocFileCase` instances, and :class:`!DocFileCase` is a " +"subclass of :class:`!DocTestCase`." +msgstr "" + +#: ../../library/doctest.rst:1169 +msgid "" +"So both ways of creating a :class:`unittest.TestSuite` run instances " +"of :class:`!DocTestCase`. This is important for a subtle reason: when you " +"run :mod:`doctest` functions yourself, you can control the :mod:`!doctest` " +"options in use directly, by passing option flags to :mod:`!doctest` " +"functions. However, if you're writing a :mod:`unittest` framework, :mod:`!" +"unittest` ultimately controls when and how tests get run. The framework " +"author typically wants to control :mod:`!doctest` reporting options " +"(perhaps, e.g., specified by command line options), but there's no way to " +"pass options through :mod:`!unittest` to :mod:`!doctest` test runners." +msgstr "" + +#: ../../library/doctest.rst:1179 +msgid "" +"For this reason, :mod:`doctest` also supports a notion of :mod:`!doctest` " +"reporting flags specific to :mod:`unittest` support, via this function:" +msgstr "" + +#: ../../library/doctest.rst:1185 +msgid "Set the :mod:`doctest` reporting flags to use." +msgstr "" + +#: ../../library/doctest.rst:1187 +msgid "" +"Argument *flags* takes the :ref:`bitwise OR ` of option flags. See " +"section :ref:`doctest-options`. Only \"reporting flags\" can be used." +msgstr "" + +#: ../../library/doctest.rst:1190 +msgid "" +"This is a module-global setting, and affects all future doctests run by " +"module :mod:`unittest`: the :meth:`!runTest` method of :class:`!" +"DocTestCase` looks at the option flags specified for the test case when " +"the :class:`!DocTestCase` instance was constructed. If no reporting flags " +"were specified (which is the typical and expected case), :mod:`!" +"doctest`'s :mod:`!unittest` reporting flags are :ref:`bitwise ORed " +"` into the option flags, and the option flags so augmented are " +"passed to the :class:`DocTestRunner` instance created to run the doctest. " +"If any reporting flags were specified when the :class:`!DocTestCase` " +"instance was constructed, :mod:`!doctest`'s :mod:`!unittest` reporting flags " +"are ignored." +msgstr "" + +#: ../../library/doctest.rst:1201 +msgid "" +"The value of the :mod:`unittest` reporting flags in effect before the " +"function was called is returned by the function." +msgstr "" + +#: ../../library/doctest.rst:1208 +msgid "Advanced API" +msgstr "" + +#: ../../library/doctest.rst:1210 +msgid "" +"The basic API is a simple wrapper that's intended to make doctest easy to " +"use. It is fairly flexible, and should meet most users' needs; however, if " +"you require more fine-grained control over testing, or wish to extend " +"doctest's capabilities, then you should use the advanced API." +msgstr "" + +#: ../../library/doctest.rst:1215 +msgid "" +"The advanced API revolves around two container classes, which are used to " +"store the interactive examples extracted from doctest cases:" +msgstr "" + +#: ../../library/doctest.rst:1218 +msgid "" +":class:`Example`: A single Python :term:`statement`, paired with its " +"expected output." +msgstr "" + +#: ../../library/doctest.rst:1221 +msgid "" +":class:`DocTest`: A collection of :class:`Example`\\ s, typically extracted " +"from a single docstring or text file." +msgstr "" + +#: ../../library/doctest.rst:1224 +msgid "" +"Additional processing classes are defined to find, parse, and run, and check " +"doctest examples:" +msgstr "" + +#: ../../library/doctest.rst:1227 +msgid "" +":class:`DocTestFinder`: Finds all docstrings in a given module, and uses " +"a :class:`DocTestParser` to create a :class:`DocTest` from every docstring " +"that contains interactive examples." +msgstr "" + +#: ../../library/doctest.rst:1231 +msgid "" +":class:`DocTestParser`: Creates a :class:`DocTest` object from a string " +"(such as an object's docstring)." +msgstr "" + +#: ../../library/doctest.rst:1234 +msgid "" +":class:`DocTestRunner`: Executes the examples in a :class:`DocTest`, and " +"uses an :class:`OutputChecker` to verify their output." +msgstr "" + +#: ../../library/doctest.rst:1237 +msgid "" +":class:`OutputChecker`: Compares the actual output from a doctest example " +"with the expected output, and decides whether they match." +msgstr "" + +#: ../../library/doctest.rst:1240 +msgid "" +"The relationships among these processing classes are summarized in the " +"following diagram::" +msgstr "" + +#: ../../library/doctest.rst:1243 +msgid "" +" list of:\n" +"+------+ +---------+\n" +"|module| --DocTestFinder-> | DocTest | --DocTestRunner-> results\n" +"+------+ | ^ +---------+ | ^ (printed)\n" +" | | | Example | | |\n" +" v | | ... | v |\n" +" DocTestParser | Example | OutputChecker\n" +" +---------+" +msgstr "" +" list of:\n" +"+------+ +---------+\n" +"|module| --DocTestFinder-> | DocTest | --DocTestRunner-> results\n" +"+------+ | ^ +---------+ | ^ (printed)\n" +" | | | Example | | |\n" +" v | | ... | v |\n" +" DocTestParser | Example | OutputChecker\n" +" +---------+" + +#: ../../library/doctest.rst:1256 +msgid "DocTest Objects" +msgstr "DocTest 物件" + +#: ../../library/doctest.rst:1261 +msgid "" +"A collection of doctest examples that should be run in a single namespace. " +"The constructor arguments are used to initialize the attributes of the same " +"names." +msgstr "" + +#: ../../library/doctest.rst:1265 +msgid "" +":class:`DocTest` defines the following attributes. They are initialized by " +"the constructor, and should not be modified directly." +msgstr "" + +#: ../../library/doctest.rst:1271 +msgid "" +"A list of :class:`Example` objects encoding the individual interactive " +"Python examples that should be run by this test." +msgstr "" + +#: ../../library/doctest.rst:1277 +msgid "" +"The namespace (aka globals) that the examples should be run in. This is a " +"dictionary mapping names to values. Any changes to the namespace made by " +"the examples (such as binding new variables) will be reflected " +"in :attr:`globs` after the test is run." +msgstr "" + +#: ../../library/doctest.rst:1285 +msgid "" +"A string name identifying the :class:`DocTest`. Typically, this is the name " +"of the object or file that the test was extracted from." +msgstr "" + +#: ../../library/doctest.rst:1291 +msgid "" +"The name of the file that this :class:`DocTest` was extracted from; or " +"``None`` if the filename is unknown, or if the :class:`!DocTest` was not " +"extracted from a file." +msgstr "" + +#: ../../library/doctest.rst:1298 +msgid "" +"The line number within :attr:`filename` where this :class:`DocTest` begins, " +"or ``None`` if the line number is unavailable. This line number is zero-" +"based with respect to the beginning of the file." +msgstr "" + +#: ../../library/doctest.rst:1305 +msgid "" +"The string that the test was extracted from, or ``None`` if the string is " +"unavailable, or if the test was not extracted from a string." +msgstr "" + +#: ../../library/doctest.rst:1312 +msgid "Example Objects" +msgstr "Example 物件" + +#: ../../library/doctest.rst:1317 +msgid "" +"A single interactive example, consisting of a Python statement and its " +"expected output. The constructor arguments are used to initialize the " +"attributes of the same names." +msgstr "" + +#: ../../library/doctest.rst:1322 +msgid "" +":class:`Example` defines the following attributes. They are initialized by " +"the constructor, and should not be modified directly." +msgstr "" + +#: ../../library/doctest.rst:1328 +msgid "" +"A string containing the example's source code. This source code consists of " +"a single Python statement, and always ends with a newline; the constructor " +"adds a newline when necessary." +msgstr "" + +#: ../../library/doctest.rst:1335 +msgid "" +"The expected output from running the example's source code (either from " +"stdout, or a traceback in case of exception). :attr:`want` ends with a " +"newline unless no output is expected, in which case it's an empty string. " +"The constructor adds a newline when necessary." +msgstr "" + +#: ../../library/doctest.rst:1343 +msgid "" +"The exception message generated by the example, if the example is expected " +"to generate an exception; or ``None`` if it is not expected to generate an " +"exception. This exception message is compared against the return value " +"of :func:`traceback.format_exception_only`. :attr:`exc_msg` ends with a " +"newline unless it's ``None``. The constructor adds a newline if needed." +msgstr "" + +#: ../../library/doctest.rst:1352 +msgid "" +"The line number within the string containing this example where the example " +"begins. This line number is zero-based with respect to the beginning of the " +"containing string." +msgstr "" + +#: ../../library/doctest.rst:1359 +msgid "" +"The example's indentation in the containing string, i.e., the number of " +"space characters that precede the example's first prompt." +msgstr "" + +#: ../../library/doctest.rst:1365 +msgid "" +"A dictionary mapping from option flags to ``True`` or ``False``, which is " +"used to override default options for this example. Any option flags not " +"contained in this dictionary are left at their default value (as specified " +"by the :class:`DocTestRunner`'s :ref:`optionflags `). By " +"default, no options are set." +msgstr "" + +#: ../../library/doctest.rst:1375 +msgid "DocTestFinder objects" +msgstr "DocTestFinder 物件" + +#: ../../library/doctest.rst:1380 +msgid "" +"A processing class used to extract the :class:`DocTest`\\ s that are " +"relevant to a given object, from its docstring and the docstrings of its " +"contained objects. :class:`DocTest`\\ s can be extracted from modules, " +"classes, functions, methods, staticmethods, classmethods, and properties." +msgstr "" + +#: ../../library/doctest.rst:1385 +msgid "" +"The optional argument *verbose* can be used to display the objects searched " +"by the finder. It defaults to ``False`` (no output)." +msgstr "" + +#: ../../library/doctest.rst:1388 +msgid "" +"The optional argument *parser* specifies the :class:`DocTestParser` object " +"(or a drop-in replacement) that is used to extract doctests from docstrings." +msgstr "" + +#: ../../library/doctest.rst:1391 +msgid "" +"If the optional argument *recurse* is false, then :meth:`DocTestFinder.find` " +"will only examine the given object, and not any contained objects." +msgstr "" + +#: ../../library/doctest.rst:1394 +msgid "" +"If the optional argument *exclude_empty* is false, " +"then :meth:`DocTestFinder.find` will include tests for objects with empty " +"docstrings." +msgstr "" + +#: ../../library/doctest.rst:1398 +msgid ":class:`DocTestFinder` defines the following method:" +msgstr ":class:`DocTestFinder` 定義了以下方法：" + +#: ../../library/doctest.rst:1403 +msgid "" +"Return a list of the :class:`DocTest`\\ s that are defined by *obj*'s " +"docstring, or by any of its contained objects' docstrings." +msgstr "" + +#: ../../library/doctest.rst:1406 +msgid "" +"The optional argument *name* specifies the object's name; this name will be " +"used to construct names for the returned :class:`DocTest`\\ s. If *name* is " +"not specified, then ``obj.__name__`` is used." +msgstr "" + +#: ../../library/doctest.rst:1410 +msgid "" +"The optional parameter *module* is the module that contains the given " +"object. If the module is not specified or is ``None``, then the test finder " +"will attempt to automatically determine the correct module. The object's " +"module is used:" +msgstr "" + +#: ../../library/doctest.rst:1414 +msgid "As a default namespace, if *globs* is not specified." +msgstr "" + +#: ../../library/doctest.rst:1416 +msgid "" +"To prevent the DocTestFinder from extracting DocTests from objects that are " +"imported from other modules. (Contained objects with modules other than " +"*module* are ignored.)" +msgstr "" + +#: ../../library/doctest.rst:1420 +msgid "To find the name of the file containing the object." +msgstr "" + +#: ../../library/doctest.rst:1422 +msgid "To help find the line number of the object within its file." +msgstr "" + +#: ../../library/doctest.rst:1424 +msgid "" +"If *module* is ``False``, no attempt to find the module will be made. This " +"is obscure, of use mostly in testing doctest itself: if *module* is " +"``False``, or is ``None`` but cannot be found automatically, then all " +"objects are considered to belong to the (non-existent) module, so all " +"contained objects will (recursively) be searched for doctests." +msgstr "" + +#: ../../library/doctest.rst:1430 +msgid "" +"The globals for each :class:`DocTest` is formed by combining *globs* and " +"*extraglobs* (bindings in *extraglobs* override bindings in *globs*). A new " +"shallow copy of the globals dictionary is created for each :class:`!" +"DocTest`. If *globs* is not specified, then it defaults to the " +"module's :attr:`~module.__dict__`, if specified, or ``{}`` otherwise. If " +"*extraglobs* is not specified, then it defaults to ``{}``." +msgstr "" + +#: ../../library/doctest.rst:1441 +msgid "DocTestParser objects" +msgstr "DocTestParser 物件" + +#: ../../library/doctest.rst:1446 +msgid "" +"A processing class used to extract interactive examples from a string, and " +"use them to create a :class:`DocTest` object." +msgstr "" + +#: ../../library/doctest.rst:1450 +msgid ":class:`DocTestParser` defines the following methods:" +msgstr ":class:`DocTestParser` 定義了以下方法：" + +#: ../../library/doctest.rst:1455 +msgid "" +"Extract all doctest examples from the given string, and collect them into " +"a :class:`DocTest` object." +msgstr "" + +#: ../../library/doctest.rst:1458 +msgid "" +"*globs*, *name*, *filename*, and *lineno* are attributes for the " +"new :class:`!DocTest` object. See the documentation for :class:`DocTest` " +"for more information." +msgstr "" + +#: ../../library/doctest.rst:1465 +msgid "" +"Extract all doctest examples from the given string, and return them as a " +"list of :class:`Example` objects. Line numbers are 0-based. The optional " +"argument *name* is a name identifying this string, and is only used for " +"error messages." +msgstr "" + +#: ../../library/doctest.rst:1472 +msgid "" +"Divide the given string into examples and intervening text, and return them " +"as a list of alternating :class:`Example`\\ s and strings. Line numbers for " +"the :class:`!Example`\\ s are 0-based. The optional argument *name* is a " +"name identifying this string, and is only used for error messages." +msgstr "" + +#: ../../library/doctest.rst:1479 +msgid "TestResults objects" +msgstr "TestResults 物件" + +#: ../../library/doctest.rst:1486 +msgid "Number of failed tests." +msgstr "失敗的測試數量。" + +#: ../../library/doctest.rst:1490 +msgid "Number of attempted tests." +msgstr "嘗試的測試數量。" + +#: ../../library/doctest.rst:1494 +msgid "Number of skipped tests." +msgstr "跳過的測試數量。" + +#: ../../library/doctest.rst:1502 +msgid "DocTestRunner objects" +msgstr "DocTestRunner 物件" + +#: ../../library/doctest.rst:1507 +msgid "" +"A processing class used to execute and verify the interactive examples in " +"a :class:`DocTest`." +msgstr "" + +#: ../../library/doctest.rst:1510 +msgid "" +"The comparison between expected outputs and actual outputs is done by " +"an :class:`OutputChecker`. This comparison may be customized with a number " +"of option flags; see section :ref:`doctest-options` for more information. " +"If the option flags are insufficient, then the comparison may also be " +"customized by passing a subclass of :class:`!OutputChecker` to the " +"constructor." +msgstr "" + +#: ../../library/doctest.rst:1516 +msgid "" +"The test runner's display output can be controlled in two ways. First, an " +"output function can be passed to :meth:`run`; this function will be called " +"with strings that should be displayed. It defaults to " +"``sys.stdout.write``. If capturing the output is not sufficient, then the " +"display output can be also customized by subclassing DocTestRunner, and " +"overriding the " +"methods :meth:`report_start`, :meth:`report_success`, :meth:`report_unexpected_exception`, " +"and :meth:`report_failure`." +msgstr "" + +#: ../../library/doctest.rst:1524 +msgid "" +"The optional keyword argument *checker* specifies the :class:`OutputChecker` " +"object (or drop-in replacement) that should be used to compare the expected " +"outputs to the actual outputs of doctest examples." +msgstr "" + +#: ../../library/doctest.rst:1528 +msgid "" +"The optional keyword argument *verbose* controls " +"the :class:`DocTestRunner`'s verbosity. If *verbose* is ``True``, then " +"information is printed about each example, as it is run. If *verbose* is " +"``False``, then only failures are printed. If *verbose* is unspecified, or " +"``None``, then verbose output is used iff the command-line switch ``-v`` is " +"used." +msgstr "" + +#: ../../library/doctest.rst:1534 +msgid "" +"The optional keyword argument *optionflags* can be used to control how the " +"test runner compares expected output to actual output, and how it displays " +"failures. For more information, see section :ref:`doctest-options`." +msgstr "" + +#: ../../library/doctest.rst:1538 +msgid "" +"The test runner accumulates statistics. The aggregated number of attempted, " +"failed and skipped examples is also available via " +"the :attr:`tries`, :attr:`failures` and :attr:`skips` attributes. " +"The :meth:`run` and :meth:`summarize` methods return a :class:`TestResults` " +"instance." +msgstr "" + +#: ../../library/doctest.rst:1543 +msgid ":class:`DocTestRunner` defines the following methods:" +msgstr ":class:`DocTestRunner` 定義了以下方法：" + +#: ../../library/doctest.rst:1548 +msgid "" +"Report that the test runner is about to process the given example. This " +"method is provided to allow subclasses of :class:`DocTestRunner` to " +"customize their output; it should not be called directly." +msgstr "" + +#: ../../library/doctest.rst:1552 +msgid "" +"*example* is the example about to be processed. *test* is the test " +"containing *example*. *out* is the output function that was passed " +"to :meth:`DocTestRunner.run`." +msgstr "" + +#: ../../library/doctest.rst:1559 +msgid "" +"Report that the given example ran successfully. This method is provided to " +"allow subclasses of :class:`DocTestRunner` to customize their output; it " +"should not be called directly." +msgstr "" + +#: ../../library/doctest.rst:1563 ../../library/doctest.rst:1574 +msgid "" +"*example* is the example about to be processed. *got* is the actual output " +"from the example. *test* is the test containing *example*. *out* is the " +"output function that was passed to :meth:`DocTestRunner.run`." +msgstr "" + +#: ../../library/doctest.rst:1570 +msgid "" +"Report that the given example failed. This method is provided to allow " +"subclasses of :class:`DocTestRunner` to customize their output; it should " +"not be called directly." +msgstr "" + +#: ../../library/doctest.rst:1581 +msgid "" +"Report that the given example raised an unexpected exception. This method is " +"provided to allow subclasses of :class:`DocTestRunner` to customize their " +"output; it should not be called directly." +msgstr "" + +#: ../../library/doctest.rst:1585 +msgid "" +"*example* is the example about to be processed. *exc_info* is a tuple " +"containing information about the unexpected exception (as returned " +"by :func:`sys.exc_info`). *test* is the test containing *example*. *out* is " +"the output function that was passed to :meth:`DocTestRunner.run`." +msgstr "" + +#: ../../library/doctest.rst:1593 +msgid "" +"Run the examples in *test* (a :class:`DocTest` object), and display the " +"results using the writer function *out*. Return a :class:`TestResults` " +"instance." +msgstr "" + +#: ../../library/doctest.rst:1597 +msgid "" +"The examples are run in the namespace ``test.globs``. If *clear_globs* is " +"true (the default), then this namespace will be cleared after the test runs, " +"to help with garbage collection. If you would like to examine the namespace " +"after the test completes, then use *clear_globs=False*." +msgstr "" + +#: ../../library/doctest.rst:1602 +msgid "" +"*compileflags* gives the set of flags that should be used by the Python " +"compiler when running the examples. If not specified, then it will default " +"to the set of future-import flags that apply to *globs*." +msgstr "" + +#: ../../library/doctest.rst:1606 +msgid "" +"The output of each example is checked using the :class:`DocTestRunner`'s " +"output checker, and the results are formatted by the :meth:`!" +"DocTestRunner.report_\\*` methods." +msgstr "" + +#: ../../library/doctest.rst:1613 +msgid "" +"Print a summary of all the test cases that have been run by this " +"DocTestRunner, and return a :class:`TestResults` instance." +msgstr "" + +#: ../../library/doctest.rst:1616 +msgid "" +"The optional *verbose* argument controls how detailed the summary is. If " +"the verbosity is not specified, then the :class:`DocTestRunner`'s verbosity " +"is used." +msgstr "" + +#: ../../library/doctest.rst:1620 +msgid ":class:`DocTestParser` has the following attributes:" +msgstr ":class:`DocTestParser` 有以下屬性：" + +#: ../../library/doctest.rst:1624 +msgid "Number of attempted examples." +msgstr "嘗試的範例數量。" + +#: ../../library/doctest.rst:1628 +msgid "Number of failed examples." +msgstr "失敗的範例數量。" + +#: ../../library/doctest.rst:1632 +msgid "Number of skipped examples." +msgstr "跳過的範例數量。" + +#: ../../library/doctest.rst:1640 +msgid "OutputChecker objects" +msgstr "OutputChecker 物件" + +#: ../../library/doctest.rst:1645 +msgid "" +"A class used to check the whether the actual output from a doctest example " +"matches the expected output. :class:`OutputChecker` defines two " +"methods: :meth:`check_output`, which compares a given pair of outputs, and " +"returns ``True`` if they match; and :meth:`output_difference`, which returns " +"a string describing the differences between two outputs." +msgstr "" + +#: ../../library/doctest.rst:1652 +msgid ":class:`OutputChecker` defines the following methods:" +msgstr ":class:`OutputChecker` 定義了以下方法：" + +#: ../../library/doctest.rst:1656 +msgid "" +"Return ``True`` iff the actual output from an example (*got*) matches the " +"expected output (*want*). These strings are always considered to match if " +"they are identical; but depending on what option flags the test runner is " +"using, several non-exact match types are also possible. See " +"section :ref:`doctest-options` for more information about option flags." +msgstr "" + +#: ../../library/doctest.rst:1665 +msgid "" +"Return a string describing the differences between the expected output for a " +"given example (*example*) and the actual output (*got*). *optionflags* is " +"the set of option flags used to compare *want* and *got*." +msgstr "" + +#: ../../library/doctest.rst:1673 +msgid "Debugging" +msgstr "偵錯" + +#: ../../library/doctest.rst:1675 +msgid "Doctest provides several mechanisms for debugging doctest examples:" +msgstr "Doctest 提供了幾種偵錯 doctest 範例的機制：" + +#: ../../library/doctest.rst:1677 +msgid "" +"Several functions convert doctests to executable Python programs, which can " +"be run under the Python debugger, :mod:`pdb`." +msgstr "" + +#: ../../library/doctest.rst:1680 +msgid "" +"The :class:`DebugRunner` class is a subclass of :class:`DocTestRunner` that " +"raises an exception for the first failing example, containing information " +"about that example. This information can be used to perform post-mortem " +"debugging on the example." +msgstr "" + +#: ../../library/doctest.rst:1685 +msgid "" +"The :mod:`unittest` cases generated by :func:`DocTestSuite` support " +"the :meth:`debug` method defined by :class:`unittest.TestCase`." +msgstr "" + +#: ../../library/doctest.rst:1688 +msgid "" +"You can add a call to :func:`pdb.set_trace` in a doctest example, and you'll " +"drop into the Python debugger when that line is executed. Then you can " +"inspect current values of variables, and so on. For example, " +"suppose :file:`a.py` contains just this module docstring::" +msgstr "" + +#: ../../library/doctest.rst:1693 +msgid "" +"\"\"\"\n" +">>> def f(x):\n" +"... g(x*2)\n" +">>> def g(x):\n" +"... print(x+3)\n" +"... import pdb; pdb.set_trace()\n" +">>> f(3)\n" +"9\n" +"\"\"\"" +msgstr "" +"\"\"\"\n" +">>> def f(x):\n" +"... g(x*2)\n" +">>> def g(x):\n" +"... print(x+3)\n" +"... import pdb; pdb.set_trace()\n" +">>> f(3)\n" +"9\n" +"\"\"\"" + +#: ../../library/doctest.rst:1703 +msgid "Then an interactive Python session may look like this::" +msgstr "" + +#: ../../library/doctest.rst:1705 +msgid "" +">>> import a, doctest\n" +">>> doctest.testmod(a)\n" +"--Return--\n" +"> (3)g()->None\n" +"-> import pdb; pdb.set_trace()\n" +"(Pdb) list\n" +" 1 def g(x):\n" +" 2 print(x+3)\n" +" 3 -> import pdb; pdb.set_trace()\n" +"[EOF]\n" +"(Pdb) p x\n" +"6\n" +"(Pdb) step\n" +"--Return--\n" +"> (2)f()->None\n" +"-> g(x*2)\n" +"(Pdb) list\n" +" 1 def f(x):\n" +" 2 -> g(x*2)\n" +"[EOF]\n" +"(Pdb) p x\n" +"3\n" +"(Pdb) step\n" +"--Return--\n" +"> (1)?()->None\n" +"-> f(3)\n" +"(Pdb) cont\n" +"(0, 3)\n" +">>>" +msgstr "" +">>> import a, doctest\n" +">>> doctest.testmod(a)\n" +"--Return--\n" +"> (3)g()->None\n" +"-> import pdb; pdb.set_trace()\n" +"(Pdb) list\n" +" 1 def g(x):\n" +" 2 print(x+3)\n" +" 3 -> import pdb; pdb.set_trace()\n" +"[EOF]\n" +"(Pdb) p x\n" +"6\n" +"(Pdb) step\n" +"--Return--\n" +"> (2)f()->None\n" +"-> g(x*2)\n" +"(Pdb) list\n" +" 1 def f(x):\n" +" 2 -> g(x*2)\n" +"[EOF]\n" +"(Pdb) p x\n" +"3\n" +"(Pdb) step\n" +"--Return--\n" +"> (1)?()->None\n" +"-> f(3)\n" +"(Pdb) cont\n" +"(0, 3)\n" +">>>" + +#: ../../library/doctest.rst:1736 +msgid "" +"Functions that convert doctests to Python code, and possibly run the " +"synthesized code under the debugger:" +msgstr "" + +#: ../../library/doctest.rst:1742 +msgid "Convert text with examples to a script." +msgstr "" + +#: ../../library/doctest.rst:1744 +msgid "" +"Argument *s* is a string containing doctest examples. The string is " +"converted to a Python script, where doctest examples in *s* are converted to " +"regular code, and everything else is converted to Python comments. The " +"generated script is returned as a string. For example, ::" +msgstr "" + +#: ../../library/doctest.rst:1749 +msgid "" +"import doctest\n" +"print(doctest.script_from_examples(r\"\"\"\n" +" Set x and y to 1 and 2.\n" +" >>> x, y = 1, 2\n" +"\n" +" Print their sum:\n" +" >>> print(x+y)\n" +" 3\n" +"\"\"\"))" +msgstr "" + +#: ../../library/doctest.rst:1759 +msgid "displays::" +msgstr "" + +#: ../../library/doctest.rst:1761 +msgid "" +"# Set x and y to 1 and 2.\n" +"x, y = 1, 2\n" +"#\n" +"# Print their sum:\n" +"print(x+y)\n" +"# Expected:\n" +"## 3" +msgstr "" + +#: ../../library/doctest.rst:1769 +msgid "" +"This function is used internally by other functions (see below), but can " +"also be useful when you want to transform an interactive Python session into " +"a Python script." +msgstr "" + +#: ../../library/doctest.rst:1776 +msgid "Convert the doctest for an object to a script." +msgstr "" + +#: ../../library/doctest.rst:1778 +msgid "" +"Argument *module* is a module object, or dotted name of a module, containing " +"the object whose doctests are of interest. Argument *name* is the name " +"(within the module) of the object with the doctests of interest. The result " +"is a string, containing the object's docstring converted to a Python script, " +"as described for :func:`script_from_examples` above. For example, if " +"module :file:`a.py` contains a top-level function :func:`!f`, then ::" +msgstr "" + +#: ../../library/doctest.rst:1785 +msgid "" +"import a, doctest\n" +"print(doctest.testsource(a, \"a.f\"))" +msgstr "" +"import a, doctest\n" +"print(doctest.testsource(a, \"a.f\"))" + +#: ../../library/doctest.rst:1788 +msgid "" +"prints a script version of function :func:`!f`'s docstring, with doctests " +"converted to code, and the rest placed in comments." +msgstr "" + +#: ../../library/doctest.rst:1794 +msgid "Debug the doctests for an object." +msgstr "" + +#: ../../library/doctest.rst:1796 +msgid "" +"The *module* and *name* arguments are the same as for " +"function :func:`testsource` above. The synthesized Python script for the " +"named object's docstring is written to a temporary file, and then that file " +"is run under the control of the Python debugger, :mod:`pdb`." +msgstr "" + +#: ../../library/doctest.rst:1801 +msgid "" +"A shallow copy of ``module.__dict__`` is used for both local and global " +"execution context." +msgstr "" + +#: ../../library/doctest.rst:1804 +msgid "" +"Optional argument *pm* controls whether post-mortem debugging is used. If " +"*pm* has a true value, the script file is run directly, and the debugger " +"gets involved only if the script terminates via raising an unhandled " +"exception. If it does, then post-mortem debugging is invoked, " +"via :func:`pdb.post_mortem`, passing the traceback object from the unhandled " +"exception. If *pm* is not specified, or is false, the script is run under " +"the debugger from the start, via passing an appropriate :func:`exec` call " +"to :func:`pdb.run`." +msgstr "" + +#: ../../library/doctest.rst:1815 +msgid "Debug the doctests in a string." +msgstr "" + +#: ../../library/doctest.rst:1817 +msgid "" +"This is like function :func:`debug` above, except that a string containing " +"doctest examples is specified directly, via the *src* argument." +msgstr "" + +#: ../../library/doctest.rst:1820 +msgid "" +"Optional argument *pm* has the same meaning as in function :func:`debug` " +"above." +msgstr "" + +#: ../../library/doctest.rst:1822 +msgid "" +"Optional argument *globs* gives a dictionary to use as both local and global " +"execution context. If not specified, or ``None``, an empty dictionary is " +"used. If specified, a shallow copy of the dictionary is used." +msgstr "" + +#: ../../library/doctest.rst:1827 +msgid "" +"The :class:`DebugRunner` class, and the special exceptions it may raise, are " +"of most interest to testing framework authors, and will only be sketched " +"here. See the source code, and especially :class:`DebugRunner`'s docstring " +"(which is a doctest!) for more details:" +msgstr "" + +#: ../../library/doctest.rst:1835 +msgid "" +"A subclass of :class:`DocTestRunner` that raises an exception as soon as a " +"failure is encountered. If an unexpected exception occurs, " +"an :exc:`UnexpectedException` exception is raised, containing the test, the " +"example, and the original exception. If the output doesn't match, then " +"a :exc:`DocTestFailure` exception is raised, containing the test, the " +"example, and the actual output." +msgstr "" + +#: ../../library/doctest.rst:1842 +msgid "" +"For information about the constructor parameters and methods, see the " +"documentation for :class:`DocTestRunner` in section :ref:`doctest-advanced-" +"api`." +msgstr "" + +#: ../../library/doctest.rst:1845 +msgid "" +"There are two exceptions that may be raised by :class:`DebugRunner` " +"instances:" +msgstr "" + +#: ../../library/doctest.rst:1850 +msgid "" +"An exception raised by :class:`DocTestRunner` to signal that a doctest " +"example's actual output did not match its expected output. The constructor " +"arguments are used to initialize the attributes of the same names." +msgstr "" + +#: ../../library/doctest.rst:1854 +msgid ":exc:`DocTestFailure` defines the following attributes:" +msgstr ":exc:`DocTestFailure` 定義了以下屬性：" + +#: ../../library/doctest.rst:1859 ../../library/doctest.rst:1883 +msgid "The :class:`DocTest` object that was being run when the example failed." +msgstr "" + +#: ../../library/doctest.rst:1864 ../../library/doctest.rst:1888 +msgid "The :class:`Example` that failed." +msgstr "" + +#: ../../library/doctest.rst:1869 +msgid "The example's actual output." +msgstr "" + +#: ../../library/doctest.rst:1874 +msgid "" +"An exception raised by :class:`DocTestRunner` to signal that a doctest " +"example raised an unexpected exception. The constructor arguments are used " +"to initialize the attributes of the same names." +msgstr "" + +#: ../../library/doctest.rst:1878 +msgid ":exc:`UnexpectedException` defines the following attributes:" +msgstr ":exc:`UnexpectedException` 定義了以下屬性：" + +#: ../../library/doctest.rst:1893 +msgid "" +"A tuple containing information about the unexpected exception, as returned " +"by :func:`sys.exc_info`." +msgstr "" + +#: ../../library/doctest.rst:1900 +msgid "Soapbox" +msgstr "" + +#: ../../library/doctest.rst:1902 +msgid "" +"As mentioned in the introduction, :mod:`doctest` has grown to have three " +"primary uses:" +msgstr "" + +#: ../../library/doctest.rst:1905 +msgid "Checking examples in docstrings." +msgstr "" + +#: ../../library/doctest.rst:1907 +msgid "Regression testing." +msgstr "回歸測試。" + +#: ../../library/doctest.rst:1909 +msgid "Executable documentation / literate testing." +msgstr "" + +#: ../../library/doctest.rst:1911 +msgid "" +"These uses have different requirements, and it is important to distinguish " +"them. In particular, filling your docstrings with obscure test cases makes " +"for bad documentation." +msgstr "" + +#: ../../library/doctest.rst:1915 +msgid "" +"When writing a docstring, choose docstring examples with care. There's an " +"art to this that needs to be learned---it may not be natural at first. " +"Examples should add genuine value to the documentation. A good example can " +"often be worth many words. If done with care, the examples will be " +"invaluable for your users, and will pay back the time it takes to collect " +"them many times over as the years go by and things change. I'm still amazed " +"at how often one of my :mod:`doctest` examples stops working after a " +"\"harmless\" change." +msgstr "" + +#: ../../library/doctest.rst:1923 +msgid "" +"Doctest also makes an excellent tool for regression testing, especially if " +"you don't skimp on explanatory text. By interleaving prose and examples, it " +"becomes much easier to keep track of what's actually being tested, and why. " +"When a test fails, good prose can make it much easier to figure out what the " +"problem is, and how it should be fixed. It's true that you could write " +"extensive comments in code-based testing, but few programmers do. Many have " +"found that using doctest approaches instead leads to much clearer tests. " +"Perhaps this is simply because doctest makes writing prose a little easier " +"than writing code, while writing comments in code is a little harder. I " +"think it goes deeper than just that: the natural attitude when writing a " +"doctest-based test is that you want to explain the fine points of your " +"software, and illustrate them with examples. This in turn naturally leads to " +"test files that start with the simplest features, and logically progress to " +"complications and edge cases. A coherent narrative is the result, instead " +"of a collection of isolated functions that test isolated bits of " +"functionality seemingly at random. It's a different attitude, and produces " +"different results, blurring the distinction between testing and explaining." +msgstr "" + +#: ../../library/doctest.rst:1941 +msgid "" +"Regression testing is best confined to dedicated objects or files. There " +"are several options for organizing tests:" +msgstr "" + +#: ../../library/doctest.rst:1944 +msgid "" +"Write text files containing test cases as interactive examples, and test the " +"files using :func:`testfile` or :func:`DocFileSuite`. This is recommended, " +"although is easiest to do for new projects, designed from the start to use " +"doctest." +msgstr "" + +#: ../../library/doctest.rst:1949 +msgid "" +"Define functions named ``_regrtest_topic`` that consist of single " +"docstrings, containing test cases for the named topics. These functions can " +"be included in the same file as the module, or separated out into a separate " +"test file." +msgstr "" + +#: ../../library/doctest.rst:1953 +msgid "" +"Define a :attr:`~module.__test__` dictionary mapping from regression test " +"topics to docstrings containing test cases." +msgstr "" + +#: ../../library/doctest.rst:1956 +msgid "" +"When you have placed your tests in a module, the module can itself be the " +"test runner. When a test fails, you can arrange for your test runner to re-" +"run only the failing doctest while you debug the problem. Here is a minimal " +"example of such a test runner::" +msgstr "" + +#: ../../library/doctest.rst:1961 +msgid "" +"if __name__ == '__main__':\n" +" import doctest\n" +" flags = doctest.REPORT_NDIFF|doctest.FAIL_FAST\n" +" if len(sys.argv) > 1:\n" +" name = sys.argv[1]\n" +" if name in globals():\n" +" obj = globals()[name]\n" +" else:\n" +" obj = __test__[name]\n" +" doctest.run_docstring_examples(obj, globals(), name=name,\n" +" optionflags=flags)\n" +" else:\n" +" fail, total = doctest.testmod(optionflags=flags)\n" +" print(f\"{fail} failures out of {total} tests\")" +msgstr "" +"if __name__ == '__main__':\n" +" import doctest\n" +" flags = doctest.REPORT_NDIFF|doctest.FAIL_FAST\n" +" if len(sys.argv) > 1:\n" +" name = sys.argv[1]\n" +" if name in globals():\n" +" obj = globals()[name]\n" +" else:\n" +" obj = __test__[name]\n" +" doctest.run_docstring_examples(obj, globals(), name=name,\n" +" optionflags=flags)\n" +" else:\n" +" fail, total = doctest.testmod(optionflags=flags)\n" +" print(f\"{fail} failures out of {total} tests\")" + +#: ../../library/doctest.rst:1978 +msgid "Footnotes" +msgstr "註腳" + +#: ../../library/doctest.rst:1979 +msgid "" +"Examples containing both expected output and an exception are not supported. " +"Trying to guess where one ends and the other begins is too error-prone, and " +"that also makes for a confusing test." +msgstr "" + +#: ../../library/doctest.rst:387 +msgid ">>>" +msgstr ">>>" + +#: ../../library/doctest.rst:387 +msgid "interpreter prompt" +msgstr "interpreter prompt（直譯器提示）" + +#: ../../library/doctest.rst:387 ../../library/doctest.rst:622 +msgid "..." +msgstr "..." + +#: ../../library/doctest.rst:553 +msgid "^ (caret)" +msgstr "^ （插入符號）" + +#: ../../library/doctest.rst:553 +msgid "marker" +msgstr "marker（標記）" + +#: ../../library/doctest.rst:602 +msgid "" +msgstr "" + +#: ../../library/doctest.rst:622 ../../library/doctest.rst:747 +msgid "in doctests" +msgstr "於 doctests 中" + +#: ../../library/doctest.rst:747 +msgid "# (hash)" +msgstr "# （井字號）" + +#: ../../library/doctest.rst:747 +msgid "+ (plus)" +msgstr "+ （加號）" + +#: ../../library/doctest.rst:747 +msgid "- (minus)" +msgstr "- （減號）" + +#~ msgid "The ``-o`` command line option." +#~ msgstr " ``-o`` 命令列選項。" diff --git a/library/email.charset.po b/library/email.charset.po index d5fa76c922..ddb91aba4a 100644 --- a/library/email.charset.po +++ b/library/email.charset.po @@ -1,358 +1,358 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-05-09 00:03+0000\n" -"PO-Revision-Date: 2018-05-23 14:43+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/email.charset.rst:2 -msgid ":mod:`!email.charset`: Representing character sets" -msgstr ":mod:`!email.charset`：字元集合的表示" - -#: ../../library/email.charset.rst:7 -msgid "**Source code:** :source:`Lib/email/charset.py`" -msgstr "**原始碼：**\\ :source:`Lib/email/charset.py`" - -#: ../../library/email.charset.rst:11 -msgid "" -"This module is part of the legacy (``Compat32``) email API. In the new API " -"only the aliases table is used." -msgstr "" -"此模組是舊版 (``Compat32``) email API的其中一部份，在新版的 API 只有使用別名" -"表。" - -#: ../../library/email.charset.rst:14 -msgid "" -"The remaining text in this section is the original documentation of the " -"module." -msgstr "此章節的其餘內容是模組的原始說明文件" - -#: ../../library/email.charset.rst:16 -msgid "" -"This module provides a class :class:`Charset` for representing character " -"sets and character set conversions in email messages, as well as a character " -"set registry and several convenience methods for manipulating this registry. " -"Instances of :class:`Charset` are used in several other modules within the :" -"mod:`email` package." -msgstr "" -"此模組提供一個類別 :class:`Charset` 來表示電子郵件訊息中的字元集合和字元集合轉" -"換，也包含字元集合登錄檔 (registry) 和其他許多運用此登錄檔的便捷方法。:class:" -"`Charset` 的實例被 :mod:`email` 套件中其他數個模組所使用。" - -#: ../../library/email.charset.rst:22 -msgid "Import this class from the :mod:`email.charset` module." -msgstr "從 :mod:`email.charset` 模組中引入此類別" - -#: ../../library/email.charset.rst:27 -msgid "Map character sets to their email properties." -msgstr "將字元集合對映到其電子郵件特性 (properties)。" - -#: ../../library/email.charset.rst:29 -msgid "" -"This class provides information about the requirements imposed on email for " -"a specific character set. It also provides convenience routines for " -"converting between character sets, given the availability of the applicable " -"codecs. Given a character set, it will do its best to provide information " -"on how to use that character set in an email message in an RFC-compliant way." -msgstr "" -"此類別提供有關於電子郵件對特定字元集合的規範資訊。考慮到適用之編解碼器 " -"(codec) 的可用性，它還提供了在字元集合之間進行轉換的便利例行操作 (routine)。" -"給定一個字元集合，它將盡量提供有關如何以符合 RFC (RFC-compliant) 的方式在電子" -"郵件訊息中使用該字元集合的資訊。" - -#: ../../library/email.charset.rst:35 -msgid "" -"Certain character sets must be encoded with quoted-printable or base64 when " -"used in email headers or bodies. Certain character sets must be converted " -"outright, and are not allowed in email." -msgstr "" -"在電子郵件標頭 (header) 或內文 (body) 用特定字元集合時必須使用可列印字元編碼 " -"(quoted-printable) 或 base64 來編碼。特定字元集合不允許出現在電子郵件中、必須" -"被徹底轉換。" - -#: ../../library/email.charset.rst:39 -msgid "" -"Optional *input_charset* is as described below; it is always coerced to " -"lower case. After being alias normalized it is also used as a lookup into " -"the registry of character sets to find out the header encoding, body " -"encoding, and output conversion codec to be used for the character set. For " -"example, if *input_charset* is ``iso-8859-1``, then headers and bodies will " -"be encoded using quoted-printable and no output conversion codec is " -"necessary. If *input_charset* is ``euc-jp``, then headers will be encoded " -"with base64, bodies will not be encoded, but output text will be converted " -"from the ``euc-jp`` character set to the ``iso-2022-jp`` character set." -msgstr "" -"可選的 *input_charset* 描述如下；*input_charset* 會被強制轉換 (coerced) 為小寫。經過" -"別名標準化 (alias normalize) 後，會進到字元集合登錄檔 (registry) 去查詢此字元" -"集合使用的標頭編碼、內文編碼以及輸出轉換編解碼器。舉例來說，如果 " -"*input_charset* 是 ``iso-8859-1``，標頭跟內文會以可列印字元編碼並且不需要輸出" -"轉換編解碼器。如果 *input_charset* 是 ``euc-jp``，標頭則會被編碼成 base64、內" -"文不會被編碼，但輸出文字則會從 ``euc-jp`` 字元集合被轉換成 ``iso-2022-jp`` 字" -"元集合。" - -#: ../../library/email.charset.rst:49 -msgid ":class:`Charset` instances have the following data attributes:" -msgstr ":class:`Charset` 實例有以下資料屬性：" - -#: ../../library/email.charset.rst:53 -msgid "" -"The initial character set specified. Common aliases are converted to their " -"*official* email names (e.g. ``latin_1`` is converted to ``iso-8859-1``). " -"Defaults to 7-bit ``us-ascii``." -msgstr "" -"指定的初始字元集合。通用別名會被轉換成它們的\\ *官方*\\ 電子郵件名稱（例如：" -"``latin_1`` 會被轉換成 ``iso-8859-1``）。預設為 7 位元 ``us-ascii``。" - -#: ../../library/email.charset.rst:60 -msgid "" -"If the character set must be encoded before it can be used in an email " -"header, this attribute will be set to ``charset.QP`` (for quoted-printable), " -"``charset.BASE64`` (for base64 encoding), or ``charset.SHORTEST`` for the " -"shortest of QP or BASE64 encoding. Otherwise, it will be ``None``." -msgstr "" -"如果字元集合在被用於電子郵件標頭前必須被編碼的話，這個屬性會被設為 ``charset." -"QP``\\ （表示可列印字元編碼）、``charset.BASE64``\\ （表示 base64 編碼格式）或" -"是 ``charset.SHORTEST`` 表示最短的 QP 或是 base64 編碼格式。不然這個屬性會是 " -"``None``。" - -#: ../../library/email.charset.rst:69 -msgid "" -"Same as *header_encoding*, but describes the encoding for the mail message's " -"body, which indeed may be different than the header encoding. ``charset." -"SHORTEST`` is not allowed for *body_encoding*." -msgstr "" -"與 *header_encoding* 相同，但表示郵件訊息內文的編碼，與上述的標頭編碼有可能不" -"同。``charset.SHORTEST`` 是不允許於 *body_encoding* 使用的。" - -#: ../../library/email.charset.rst:76 -msgid "" -"Some character sets must be converted before they can be used in email " -"headers or bodies. If the *input_charset* is one of them, this attribute " -"will contain the name of the character set output will be converted to. " -"Otherwise, it will be ``None``." -msgstr "" -"部分的字元集合在用於電子郵件的標頭或內文前必須先被轉換。如果 *input_charset* " -"是這些字元集合的其中之一，這個屬性將會包含輸出時轉換成的字元集合名稱。不然這" -"個屬性則為 ``None``。" - -#: ../../library/email.charset.rst:84 -msgid "" -"The name of the Python codec used to convert the *input_charset* to " -"Unicode. If no conversion codec is necessary, this attribute will be " -"``None``." -msgstr "" -"用於將 *input_charset* 轉換成 Unicode 的 Python 編解碼器的名稱。如果不需要轉" -"換編解碼器，這個屬性為 ``None``。" - -#: ../../library/email.charset.rst:91 -msgid "" -"The name of the Python codec used to convert Unicode to the " -"*output_charset*. If no conversion codec is necessary, this attribute will " -"have the same value as the *input_codec*." -msgstr "" -"用於將 Unicode 轉換成 *output_charset* 的 Python 編解碼器名稱。如果不需要轉換" -"編解碼器，這個屬性將會與 *input_codec* 有相同的值。" - -#: ../../library/email.charset.rst:96 -msgid ":class:`Charset` instances also have the following methods:" -msgstr ":class:`Charset` 實例還有以下方法：" - -#: ../../library/email.charset.rst:100 -msgid "Return the content transfer encoding used for body encoding." -msgstr "回傳用於內文編碼的內容傳輸編碼 (content transfer encoding)。" - -#: ../../library/email.charset.rst:102 -msgid "" -"This is either the string ``quoted-printable`` or ``base64`` depending on " -"the encoding used, or it is a function, in which case you should call the " -"function with a single argument, the Message object being encoded. The " -"function should then set the :mailheader:`Content-Transfer-Encoding` header " -"itself to whatever is appropriate." -msgstr "" -"這可以是字串 ``quoted-printable`` 或 ``base64``，具體取決於所使用的編碼，或者" -"它也可以是一個函式，在這種情況下，你應該使用單個引數呼叫該函式，即正被編碼的 " -"Message 物件。然後函式應將 :mailheader:`Content-Transfer-Encoding` 標頭本身設" -"定為任何適當的值。" - -#: ../../library/email.charset.rst:108 -msgid "" -"Returns the string ``quoted-printable`` if *body_encoding* is ``QP``, " -"returns the string ``base64`` if *body_encoding* is ``BASE64``, and returns " -"the string ``7bit`` otherwise." -msgstr "" -"如果 *body_encoding* 為 ``QP`` 則回傳字串 ``quoted-printable``，如果 " -"*body_encoding* 為 ``BASE64`` 則回傳字串 ``base64``，否則回傳字串 ``7bit`` 。" - -#: ../../library/email.charset.rst:115 -msgid "Return the output character set." -msgstr "回傳輸出字元集合。" - -#: ../../library/email.charset.rst:117 -msgid "" -"This is the *output_charset* attribute if that is not ``None``, otherwise it " -"is *input_charset*." -msgstr "" -"如果不為 ``None`` 則這會是 *output_charset* 屬性，否則它是 *input_charset*。" - -#: ../../library/email.charset.rst:123 -msgid "Header-encode the string *string*." -msgstr "對字串 *string* 進行標頭編碼 (header-encode)。" - -#: ../../library/email.charset.rst:125 -msgid "" -"The type of encoding (base64 or quoted-printable) will be based on the " -"*header_encoding* attribute." -msgstr "編碼類型（base64 或可列印字元編碼）將基於 *header_encoding* 屬性。" - -#: ../../library/email.charset.rst:131 -msgid "Header-encode a *string* by converting it first to bytes." -msgstr "透過先將 *string* 轉換為位元組來對它進行標頭編碼。" - -#: ../../library/email.charset.rst:133 -msgid "" -"This is similar to :meth:`header_encode` except that the string is fit into " -"maximum line lengths as given by the argument *maxlengths*, which must be an " -"iterator: each element returned from this iterator will provide the next " -"maximum line length." -msgstr "" -"這與 :meth:`header_encode` 類似，只不過字串不會超過由引數 *maxlengths* 給定的" -"最大列長度 (maximum line length)，該引數必須是個疊代器：從此疊代器回傳的每個" -"元素將提供下一個最大列長度。" - -#: ../../library/email.charset.rst:141 -msgid "Body-encode the string *string*." -msgstr "對字串 *string* 進行內文編碼 (body-encode)。" - -#: ../../library/email.charset.rst:143 -msgid "" -"The type of encoding (base64 or quoted-printable) will be based on the " -"*body_encoding* attribute." -msgstr "編碼類型（base64 或可列印字元編碼）將基於 *body_encoding* 屬性。" - -#: ../../library/email.charset.rst:146 -msgid "" -"The :class:`Charset` class also provides a number of methods to support " -"standard operations and built-in functions." -msgstr ":class:`Charset` 類別也提供了許多支援標準操作和內建函式的方法。" - -#: ../../library/email.charset.rst:152 -msgid "" -"Returns *input_charset* as a string coerced to lower case. :meth:`!__repr__` " -"is an alias for :meth:`!__str__`." -msgstr "" -"回傳強制轉換 *input_charset* 為小寫後的字串。:meth:`!__repr__` 是 :meth:`!" -"__str__` 的別名。" - -#: ../../library/email.charset.rst:158 -msgid "" -"This method allows you to compare two :class:`Charset` instances for " -"equality." -msgstr "此方法讓你比較兩個 :class:`Charset` 實例的相等性。" - -#: ../../library/email.charset.rst:164 -msgid "" -"This method allows you to compare two :class:`Charset` instances for " -"inequality." -msgstr "此方法讓你比較兩個 :class:`Charset` 實例的不相等性。" - -#: ../../library/email.charset.rst:167 -msgid "" -"The :mod:`email.charset` module also provides the following functions for " -"adding new entries to the global character set, alias, and codec registries:" -msgstr "" -":mod:`email.charset` 模組還提供以下函式，用於將項目新增至全域字元集合、別名和" -"編解碼器登錄檔中：" - -#: ../../library/email.charset.rst:173 -msgid "Add character properties to the global registry." -msgstr "將字元特性 (properties) 新增至全域登錄檔。" - -#: ../../library/email.charset.rst:175 -msgid "" -"*charset* is the input character set, and must be the canonical name of a " -"character set." -msgstr "" -"*charset* 是輸入的字元集合，且必須是字元集合的規範名稱 (canonical name)。" - -#: ../../library/email.charset.rst:178 -msgid "" -"Optional *header_enc* and *body_enc* is either ``charset.QP`` for quoted-" -"printable, ``charset.BASE64`` for base64 encoding, ``charset.SHORTEST`` for " -"the shortest of quoted-printable or base64 encoding, or ``None`` for no " -"encoding. ``SHORTEST`` is only valid for *header_enc*. The default is " -"``None`` for no encoding." -msgstr "" -"可選的 *header_enc* 和 *body_enc* 為 ``charset.QP``\\ （表示可列印字元編" -"碼）、``charset.BASE64``\\ （表示 base64 編碼）、``charset.SHORTEST``\\ （表" -"示最短的 base64 或可列印字元編碼）或 ``None``\\ （表示無編碼）。``SHORTEST`` " -"僅在用於 *header_enc* 時有效。預設為 ``None``，表示無編碼。" - -#: ../../library/email.charset.rst:184 -msgid "" -"Optional *output_charset* is the character set that the output should be in. " -"Conversions will proceed from input charset, to Unicode, to the output " -"charset when the method :meth:`Charset.convert` is called. The default is " -"to output in the same character set as the input." -msgstr "" -"可選的 *output_charset* 是輸出應採用的字元集合。當呼叫 :meth:`Charset." -"convert` 方法時，將從輸入字元集合轉換為 Unicode，再轉換為輸出字元集合。預設是" -"以與輸入相同的字元集合輸出。" - -#: ../../library/email.charset.rst:189 -msgid "" -"Both *input_charset* and *output_charset* must have Unicode codec entries in " -"the module's character set-to-codec mapping; use :func:`add_codec` to add " -"codecs the module does not know about. See the :mod:`codecs` module's " -"documentation for more information." -msgstr "" -"*input_charset* 和 *output_charset* 都必須在模組的字元集合到編解碼器對映 " -"(character set-to-codec mapping) 中具有 Unicode 編解碼器項目；使用 :func:" -"`add_codec` 來新增模組未知的編解碼器。有關更多資訊請參閱 :mod:`codecs` 模組的" -"文件。" - -#: ../../library/email.charset.rst:194 -msgid "" -"The global character set registry is kept in the module global dictionary " -"``CHARSETS``." -msgstr "全域字元集合登錄檔保存在模組全域字典 ``CHARSETS`` 中。" - -#: ../../library/email.charset.rst:200 -msgid "" -"Add a character set alias. *alias* is the alias name, e.g. ``latin-1``. " -"*canonical* is the character set's canonical name, e.g. ``iso-8859-1``." -msgstr "" -"新增字元集合別名。*alias* 是別名，例如 ``latin-1``。*canonical* 是字元集合的" -"規範名稱，例如 ``iso-8859-1``。" - -#: ../../library/email.charset.rst:203 -msgid "" -"The global charset alias registry is kept in the module global dictionary " -"``ALIASES``." -msgstr "全域字元集合別名登錄檔保存在模組全域字典 ``ALIASES`` 中。" - -#: ../../library/email.charset.rst:209 -msgid "" -"Add a codec that map characters in the given character set to and from " -"Unicode." -msgstr "新增一個編解碼器，將給定字元集合中的字元與 Unicode 進行對映。" - -#: ../../library/email.charset.rst:211 -msgid "" -"*charset* is the canonical name of a character set. *codecname* is the name " -"of a Python codec, as appropriate for the second argument to the :class:" -"`str`'s :meth:`~str.encode` method." -msgstr "" -"*charset* 是字元集合的規範名稱。*codecname* 是 Python 編解碼器的名稱，適用" -"於 :class:`str` 的 :meth:`~str.encode` 方法的第二個引數。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-05-09 00:03+0000\n" +"PO-Revision-Date: 2018-05-23 14:43+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/email.charset.rst:2 +msgid ":mod:`!email.charset`: Representing character sets" +msgstr ":mod:`!email.charset`：字元集合的表示" + +#: ../../library/email.charset.rst:7 +msgid "**Source code:** :source:`Lib/email/charset.py`" +msgstr "**原始碼：**\\ :source:`Lib/email/charset.py`" + +#: ../../library/email.charset.rst:11 +msgid "" +"This module is part of the legacy (``Compat32``) email API. In the new API " +"only the aliases table is used." +msgstr "" +"此模組是舊版 (``Compat32``) email API的其中一部份，在新版的 API 只有使用別名" +"表。" + +#: ../../library/email.charset.rst:14 +msgid "" +"The remaining text in this section is the original documentation of the " +"module." +msgstr "此章節的其餘內容是模組的原始說明文件" + +#: ../../library/email.charset.rst:16 +msgid "" +"This module provides a class :class:`Charset` for representing character " +"sets and character set conversions in email messages, as well as a character " +"set registry and several convenience methods for manipulating this registry. " +"Instances of :class:`Charset` are used in several other modules within the :" +"mod:`email` package." +msgstr "" +"此模組提供一個類別 :class:`Charset` 來表示電子郵件訊息中的字元集合和字元集合轉" +"換，也包含字元集合登錄檔 (registry) 和其他許多運用此登錄檔的便捷方法。:class:" +"`Charset` 的實例被 :mod:`email` 套件中其他數個模組所使用。" + +#: ../../library/email.charset.rst:22 +msgid "Import this class from the :mod:`email.charset` module." +msgstr "從 :mod:`email.charset` 模組中引入此類別" + +#: ../../library/email.charset.rst:27 +msgid "Map character sets to their email properties." +msgstr "將字元集合對映到其電子郵件特性 (properties)。" + +#: ../../library/email.charset.rst:29 +msgid "" +"This class provides information about the requirements imposed on email for " +"a specific character set. It also provides convenience routines for " +"converting between character sets, given the availability of the applicable " +"codecs. Given a character set, it will do its best to provide information " +"on how to use that character set in an email message in an RFC-compliant way." +msgstr "" +"此類別提供有關於電子郵件對特定字元集合的規範資訊。考慮到適用之編解碼器 " +"(codec) 的可用性，它還提供了在字元集合之間進行轉換的便利例行操作 (routine)。" +"給定一個字元集合，它將盡量提供有關如何以符合 RFC (RFC-compliant) 的方式在電子" +"郵件訊息中使用該字元集合的資訊。" + +#: ../../library/email.charset.rst:35 +msgid "" +"Certain character sets must be encoded with quoted-printable or base64 when " +"used in email headers or bodies. Certain character sets must be converted " +"outright, and are not allowed in email." +msgstr "" +"在電子郵件標頭 (header) 或內文 (body) 用特定字元集合時必須使用可列印字元編碼 " +"(quoted-printable) 或 base64 來編碼。特定字元集合不允許出現在電子郵件中、必須" +"被徹底轉換。" + +#: ../../library/email.charset.rst:39 +msgid "" +"Optional *input_charset* is as described below; it is always coerced to " +"lower case. After being alias normalized it is also used as a lookup into " +"the registry of character sets to find out the header encoding, body " +"encoding, and output conversion codec to be used for the character set. For " +"example, if *input_charset* is ``iso-8859-1``, then headers and bodies will " +"be encoded using quoted-printable and no output conversion codec is " +"necessary. If *input_charset* is ``euc-jp``, then headers will be encoded " +"with base64, bodies will not be encoded, but output text will be converted " +"from the ``euc-jp`` character set to the ``iso-2022-jp`` character set." +msgstr "" +"可選的 *input_charset* 描述如下；*input_charset* 會被強制轉換 (coerced) 為小寫。經過" +"別名標準化 (alias normalize) 後，會進到字元集合登錄檔 (registry) 去查詢此字元" +"集合使用的標頭編碼、內文編碼以及輸出轉換編解碼器。舉例來說，如果 " +"*input_charset* 是 ``iso-8859-1``，標頭跟內文會以可列印字元編碼並且不需要輸出" +"轉換編解碼器。如果 *input_charset* 是 ``euc-jp``，標頭則會被編碼成 base64、內" +"文不會被編碼，但輸出文字則會從 ``euc-jp`` 字元集合被轉換成 ``iso-2022-jp`` 字" +"元集合。" + +#: ../../library/email.charset.rst:49 +msgid ":class:`Charset` instances have the following data attributes:" +msgstr ":class:`Charset` 實例有以下資料屬性：" + +#: ../../library/email.charset.rst:53 +msgid "" +"The initial character set specified. Common aliases are converted to their " +"*official* email names (e.g. ``latin_1`` is converted to ``iso-8859-1``). " +"Defaults to 7-bit ``us-ascii``." +msgstr "" +"指定的初始字元集合。通用別名會被轉換成它們的\\ *官方*\\ 電子郵件名稱（例如：" +"``latin_1`` 會被轉換成 ``iso-8859-1``）。預設為 7 位元 ``us-ascii``。" + +#: ../../library/email.charset.rst:60 +msgid "" +"If the character set must be encoded before it can be used in an email " +"header, this attribute will be set to ``charset.QP`` (for quoted-printable), " +"``charset.BASE64`` (for base64 encoding), or ``charset.SHORTEST`` for the " +"shortest of QP or BASE64 encoding. Otherwise, it will be ``None``." +msgstr "" +"如果字元集合在被用於電子郵件標頭前必須被編碼的話，這個屬性會被設為 ``charset." +"QP``\\ （表示可列印字元編碼）、``charset.BASE64``\\ （表示 base64 編碼格式）或" +"是 ``charset.SHORTEST`` 表示最短的 QP 或是 base64 編碼格式。不然這個屬性會是 " +"``None``。" + +#: ../../library/email.charset.rst:69 +msgid "" +"Same as *header_encoding*, but describes the encoding for the mail message's " +"body, which indeed may be different than the header encoding. ``charset." +"SHORTEST`` is not allowed for *body_encoding*." +msgstr "" +"與 *header_encoding* 相同，但表示郵件訊息內文的編碼，與上述的標頭編碼有可能不" +"同。``charset.SHORTEST`` 是不允許於 *body_encoding* 使用的。" + +#: ../../library/email.charset.rst:76 +msgid "" +"Some character sets must be converted before they can be used in email " +"headers or bodies. If the *input_charset* is one of them, this attribute " +"will contain the name of the character set output will be converted to. " +"Otherwise, it will be ``None``." +msgstr "" +"部分的字元集合在用於電子郵件的標頭或內文前必須先被轉換。如果 *input_charset* " +"是這些字元集合的其中之一，這個屬性將會包含輸出時轉換成的字元集合名稱。不然這" +"個屬性則為 ``None``。" + +#: ../../library/email.charset.rst:84 +msgid "" +"The name of the Python codec used to convert the *input_charset* to " +"Unicode. If no conversion codec is necessary, this attribute will be " +"``None``." +msgstr "" +"用於將 *input_charset* 轉換成 Unicode 的 Python 編解碼器的名稱。如果不需要轉" +"換編解碼器，這個屬性為 ``None``。" + +#: ../../library/email.charset.rst:91 +msgid "" +"The name of the Python codec used to convert Unicode to the " +"*output_charset*. If no conversion codec is necessary, this attribute will " +"have the same value as the *input_codec*." +msgstr "" +"用於將 Unicode 轉換成 *output_charset* 的 Python 編解碼器名稱。如果不需要轉換" +"編解碼器，這個屬性將會與 *input_codec* 有相同的值。" + +#: ../../library/email.charset.rst:96 +msgid ":class:`Charset` instances also have the following methods:" +msgstr ":class:`Charset` 實例還有以下方法：" + +#: ../../library/email.charset.rst:100 +msgid "Return the content transfer encoding used for body encoding." +msgstr "回傳用於內文編碼的內容傳輸編碼 (content transfer encoding)。" + +#: ../../library/email.charset.rst:102 +msgid "" +"This is either the string ``quoted-printable`` or ``base64`` depending on " +"the encoding used, or it is a function, in which case you should call the " +"function with a single argument, the Message object being encoded. The " +"function should then set the :mailheader:`Content-Transfer-Encoding` header " +"itself to whatever is appropriate." +msgstr "" +"這可以是字串 ``quoted-printable`` 或 ``base64``，具體取決於所使用的編碼，或者" +"它也可以是一個函式，在這種情況下，你應該使用單個引數呼叫該函式，即正被編碼的 " +"Message 物件。然後函式應將 :mailheader:`Content-Transfer-Encoding` 標頭本身設" +"定為任何適當的值。" + +#: ../../library/email.charset.rst:108 +msgid "" +"Returns the string ``quoted-printable`` if *body_encoding* is ``QP``, " +"returns the string ``base64`` if *body_encoding* is ``BASE64``, and returns " +"the string ``7bit`` otherwise." +msgstr "" +"如果 *body_encoding* 為 ``QP`` 則回傳字串 ``quoted-printable``，如果 " +"*body_encoding* 為 ``BASE64`` 則回傳字串 ``base64``，否則回傳字串 ``7bit`` 。" + +#: ../../library/email.charset.rst:115 +msgid "Return the output character set." +msgstr "回傳輸出字元集合。" + +#: ../../library/email.charset.rst:117 +msgid "" +"This is the *output_charset* attribute if that is not ``None``, otherwise it " +"is *input_charset*." +msgstr "" +"如果不為 ``None`` 則這會是 *output_charset* 屬性，否則它是 *input_charset*。" + +#: ../../library/email.charset.rst:123 +msgid "Header-encode the string *string*." +msgstr "對字串 *string* 進行標頭編碼 (header-encode)。" + +#: ../../library/email.charset.rst:125 +msgid "" +"The type of encoding (base64 or quoted-printable) will be based on the " +"*header_encoding* attribute." +msgstr "編碼類型（base64 或可列印字元編碼）將基於 *header_encoding* 屬性。" + +#: ../../library/email.charset.rst:131 +msgid "Header-encode a *string* by converting it first to bytes." +msgstr "透過先將 *string* 轉換為位元組來對它進行標頭編碼。" + +#: ../../library/email.charset.rst:133 +msgid "" +"This is similar to :meth:`header_encode` except that the string is fit into " +"maximum line lengths as given by the argument *maxlengths*, which must be an " +"iterator: each element returned from this iterator will provide the next " +"maximum line length." +msgstr "" +"這與 :meth:`header_encode` 類似，只不過字串不會超過由引數 *maxlengths* 給定的" +"最大列長度 (maximum line length)，該引數必須是個疊代器：從此疊代器回傳的每個" +"元素將提供下一個最大列長度。" + +#: ../../library/email.charset.rst:141 +msgid "Body-encode the string *string*." +msgstr "對字串 *string* 進行內文編碼 (body-encode)。" + +#: ../../library/email.charset.rst:143 +msgid "" +"The type of encoding (base64 or quoted-printable) will be based on the " +"*body_encoding* attribute." +msgstr "編碼類型（base64 或可列印字元編碼）將基於 *body_encoding* 屬性。" + +#: ../../library/email.charset.rst:146 +msgid "" +"The :class:`Charset` class also provides a number of methods to support " +"standard operations and built-in functions." +msgstr ":class:`Charset` 類別也提供了許多支援標準操作和內建函式的方法。" + +#: ../../library/email.charset.rst:152 +msgid "" +"Returns *input_charset* as a string coerced to lower case. :meth:`!__repr__` " +"is an alias for :meth:`!__str__`." +msgstr "" +"回傳強制轉換 *input_charset* 為小寫後的字串。:meth:`!__repr__` 是 :meth:`!" +"__str__` 的別名。" + +#: ../../library/email.charset.rst:158 +msgid "" +"This method allows you to compare two :class:`Charset` instances for " +"equality." +msgstr "此方法讓你比較兩個 :class:`Charset` 實例的相等性。" + +#: ../../library/email.charset.rst:164 +msgid "" +"This method allows you to compare two :class:`Charset` instances for " +"inequality." +msgstr "此方法讓你比較兩個 :class:`Charset` 實例的不相等性。" + +#: ../../library/email.charset.rst:167 +msgid "" +"The :mod:`email.charset` module also provides the following functions for " +"adding new entries to the global character set, alias, and codec registries:" +msgstr "" +":mod:`email.charset` 模組還提供以下函式，用於將項目新增至全域字元集合、別名和" +"編解碼器登錄檔中：" + +#: ../../library/email.charset.rst:173 +msgid "Add character properties to the global registry." +msgstr "將字元特性 (properties) 新增至全域登錄檔。" + +#: ../../library/email.charset.rst:175 +msgid "" +"*charset* is the input character set, and must be the canonical name of a " +"character set." +msgstr "" +"*charset* 是輸入的字元集合，且必須是字元集合的規範名稱 (canonical name)。" + +#: ../../library/email.charset.rst:178 +msgid "" +"Optional *header_enc* and *body_enc* is either ``charset.QP`` for quoted-" +"printable, ``charset.BASE64`` for base64 encoding, ``charset.SHORTEST`` for " +"the shortest of quoted-printable or base64 encoding, or ``None`` for no " +"encoding. ``SHORTEST`` is only valid for *header_enc*. The default is " +"``None`` for no encoding." +msgstr "" +"可選的 *header_enc* 和 *body_enc* 為 ``charset.QP``\\ （表示可列印字元編" +"碼）、``charset.BASE64``\\ （表示 base64 編碼）、``charset.SHORTEST``\\ （表" +"示最短的 base64 或可列印字元編碼）或 ``None``\\ （表示無編碼）。``SHORTEST`` " +"僅在用於 *header_enc* 時有效。預設為 ``None``，表示無編碼。" + +#: ../../library/email.charset.rst:184 +msgid "" +"Optional *output_charset* is the character set that the output should be in. " +"Conversions will proceed from input charset, to Unicode, to the output " +"charset when the method :meth:`Charset.convert` is called. The default is " +"to output in the same character set as the input." +msgstr "" +"可選的 *output_charset* 是輸出應採用的字元集合。當呼叫 :meth:`Charset." +"convert` 方法時，將從輸入字元集合轉換為 Unicode，再轉換為輸出字元集合。預設是" +"以與輸入相同的字元集合輸出。" + +#: ../../library/email.charset.rst:189 +msgid "" +"Both *input_charset* and *output_charset* must have Unicode codec entries in " +"the module's character set-to-codec mapping; use :func:`add_codec` to add " +"codecs the module does not know about. See the :mod:`codecs` module's " +"documentation for more information." +msgstr "" +"*input_charset* 和 *output_charset* 都必須在模組的字元集合到編解碼器對映 " +"(character set-to-codec mapping) 中具有 Unicode 編解碼器項目；使用 :func:" +"`add_codec` 來新增模組未知的編解碼器。有關更多資訊請參閱 :mod:`codecs` 模組的" +"文件。" + +#: ../../library/email.charset.rst:194 +msgid "" +"The global character set registry is kept in the module global dictionary " +"``CHARSETS``." +msgstr "全域字元集合登錄檔保存在模組全域字典 ``CHARSETS`` 中。" + +#: ../../library/email.charset.rst:200 +msgid "" +"Add a character set alias. *alias* is the alias name, e.g. ``latin-1``. " +"*canonical* is the character set's canonical name, e.g. ``iso-8859-1``." +msgstr "" +"新增字元集合別名。*alias* 是別名，例如 ``latin-1``。*canonical* 是字元集合的" +"規範名稱，例如 ``iso-8859-1``。" + +#: ../../library/email.charset.rst:203 +msgid "" +"The global charset alias registry is kept in the module global dictionary " +"``ALIASES``." +msgstr "全域字元集合別名登錄檔保存在模組全域字典 ``ALIASES`` 中。" + +#: ../../library/email.charset.rst:209 +msgid "" +"Add a codec that map characters in the given character set to and from " +"Unicode." +msgstr "新增一個編解碼器，將給定字元集合中的字元與 Unicode 進行對映。" + +#: ../../library/email.charset.rst:211 +msgid "" +"*charset* is the canonical name of a character set. *codecname* is the name " +"of a Python codec, as appropriate for the second argument to the :class:" +"`str`'s :meth:`~str.encode` method." +msgstr "" +"*charset* 是字元集合的規範名稱。*codecname* 是 Python 編解碼器的名稱，適用" +"於 :class:`str` 的 :meth:`~str.encode` 方法的第二個引數。" diff --git a/library/email.compat32-message.po b/library/email.compat32-message.po index 98b599220d..00536456c4 100644 --- a/library/email.compat32-message.po +++ b/library/email.compat32-message.po @@ -1,964 +1,964 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-07-07 17:47+0000\n" -"PO-Revision-Date: 2018-07-15 18:56+0800\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/email.compat32-message.rst:4 -msgid "" -":mod:`email.message.Message`: Representing an email message using the :data:" -"`~email.policy.compat32` API" -msgstr "" - -#: ../../library/email.compat32-message.rst:13 -msgid "" -"The :class:`Message` class is very similar to the :class:`~email.message." -"EmailMessage` class, without the methods added by that class, and with the " -"default behavior of certain other methods being slightly different. We also " -"document here some methods that, while supported by the :class:`~email." -"message.EmailMessage` class, are not recommended unless you are dealing with " -"legacy code." -msgstr "" - -#: ../../library/email.compat32-message.rst:20 -msgid "The philosophy and structure of the two classes is otherwise the same." -msgstr "" - -#: ../../library/email.compat32-message.rst:22 -msgid "" -"This document describes the behavior under the default (for :class:" -"`Message`) policy :attr:`~email.policy.Compat32`. If you are going to use " -"another policy, you should be using the :class:`~email.message.EmailMessage` " -"class instead." -msgstr "" - -#: ../../library/email.compat32-message.rst:26 -msgid "" -"An email message consists of *headers* and a *payload*. Headers must be :" -"rfc:`5322` style names and values, where the field name and value are " -"separated by a colon. The colon is not part of either the field name or the " -"field value. The payload may be a simple text message, or a binary object, " -"or a structured sequence of sub-messages each with their own set of headers " -"and their own payload. The latter type of payload is indicated by the " -"message having a MIME type such as :mimetype:`multipart/\\*` or :mimetype:" -"`message/rfc822`." -msgstr "" - -#: ../../library/email.compat32-message.rst:35 -msgid "" -"The conceptual model provided by a :class:`Message` object is that of an " -"ordered dictionary of headers with additional methods for accessing both " -"specialized information from the headers, for accessing the payload, for " -"generating a serialized version of the message, and for recursively walking " -"over the object tree. Note that duplicate headers are supported but special " -"methods must be used to access them." -msgstr "" - -#: ../../library/email.compat32-message.rst:42 -msgid "" -"The :class:`Message` pseudo-dictionary is indexed by the header names, which " -"must be ASCII values. The values of the dictionary are strings that are " -"supposed to contain only ASCII characters; there is some special handling " -"for non-ASCII input, but it doesn't always produce the correct results. " -"Headers are stored and returned in case-preserving form, but field names are " -"matched case-insensitively. There may also be a single envelope header, " -"also known as the *Unix-From* header or the ``From_`` header. The *payload* " -"is either a string or bytes, in the case of simple message objects, or a " -"list of :class:`Message` objects, for MIME container documents (e.g. :" -"mimetype:`multipart/\\*` and :mimetype:`message/rfc822`)." -msgstr "" - -#: ../../library/email.compat32-message.rst:53 -msgid "Here are the methods of the :class:`Message` class:" -msgstr "" - -#: ../../library/email.compat32-message.rst:58 -msgid "" -"If *policy* is specified (it must be an instance of a :mod:`~email.policy` " -"class) use the rules it specifies to update and serialize the representation " -"of the message. If *policy* is not set, use the :class:`compat32 ` policy, which maintains backward compatibility with the " -"Python 3.2 version of the email package. For more information see the :mod:" -"`~email.policy` documentation." -msgstr "" - -#: ../../library/email.compat32-message.rst:65 -msgid "The *policy* keyword argument was added." -msgstr "新增 *policy* 關鍵字引數。" - -#: ../../library/email.compat32-message.rst:70 -msgid "" -"Return the entire message flattened as a string. When optional *unixfrom* " -"is true, the envelope header is included in the returned string. *unixfrom* " -"defaults to ``False``. For backward compatibility reasons, *maxheaderlen* " -"defaults to ``0``, so if you want a different value you must override it " -"explicitly (the value specified for *max_line_length* in the policy will be " -"ignored by this method). The *policy* argument may be used to override the " -"default policy obtained from the message instance. This can be used to " -"control some of the formatting produced by the method, since the specified " -"*policy* will be passed to the ``Generator``." -msgstr "" - -#: ../../library/email.compat32-message.rst:80 -#: ../../library/email.compat32-message.rst:122 -msgid "" -"Flattening the message may trigger changes to the :class:`Message` if " -"defaults need to be filled in to complete the transformation to a string " -"(for example, MIME boundaries may be generated or modified)." -msgstr "" - -#: ../../library/email.compat32-message.rst:84 -msgid "" -"Note that this method is provided as a convenience and may not always format " -"the message the way you want. For example, by default it does not do the " -"mangling of lines that begin with ``From`` that is required by the Unix mbox " -"format. For more flexibility, instantiate a :class:`~email.generator." -"Generator` instance and use its :meth:`~email.generator.Generator.flatten` " -"method directly. For example::" -msgstr "" - -#: ../../library/email.compat32-message.rst:91 -msgid "" -"from io import StringIO\n" -"from email.generator import Generator\n" -"fp = StringIO()\n" -"g = Generator(fp, mangle_from_=True, maxheaderlen=60)\n" -"g.flatten(msg)\n" -"text = fp.getvalue()" -msgstr "" -"from io import StringIO\n" -"from email.generator import Generator\n" -"fp = StringIO()\n" -"g = Generator(fp, mangle_from_=True, maxheaderlen=60)\n" -"g.flatten(msg)\n" -"text = fp.getvalue()" - -#: ../../library/email.compat32-message.rst:98 -msgid "" -"If the message object contains binary data that is not encoded according to " -"RFC standards, the non-compliant data will be replaced by unicode \"unknown " -"character\" code points. (See also :meth:`.as_bytes` and :class:`~email." -"generator.BytesGenerator`.)" -msgstr "" - -#: ../../library/email.compat32-message.rst:103 -msgid "the *policy* keyword argument was added." -msgstr "新增 *policy* 關鍵字引數。" - -#: ../../library/email.compat32-message.rst:108 -msgid "" -"Equivalent to :meth:`.as_string`. Allows ``str(msg)`` to produce a string " -"containing the formatted message." -msgstr "" - -#: ../../library/email.compat32-message.rst:114 -msgid "" -"Return the entire message flattened as a bytes object. When optional " -"*unixfrom* is true, the envelope header is included in the returned string. " -"*unixfrom* defaults to ``False``. The *policy* argument may be used to " -"override the default policy obtained from the message instance. This can be " -"used to control some of the formatting produced by the method, since the " -"specified *policy* will be passed to the ``BytesGenerator``." -msgstr "" - -#: ../../library/email.compat32-message.rst:126 -msgid "" -"Note that this method is provided as a convenience and may not always format " -"the message the way you want. For example, by default it does not do the " -"mangling of lines that begin with ``From`` that is required by the Unix mbox " -"format. For more flexibility, instantiate a :class:`~email.generator." -"BytesGenerator` instance and use its :meth:`~email.generator.BytesGenerator." -"flatten` method directly. For example::" -msgstr "" - -#: ../../library/email.compat32-message.rst:134 -msgid "" -"from io import BytesIO\n" -"from email.generator import BytesGenerator\n" -"fp = BytesIO()\n" -"g = BytesGenerator(fp, mangle_from_=True, maxheaderlen=60)\n" -"g.flatten(msg)\n" -"text = fp.getvalue()" -msgstr "" -"from io import BytesIO\n" -"from email.generator import BytesGenerator\n" -"fp = BytesIO()\n" -"g = BytesGenerator(fp, mangle_from_=True, maxheaderlen=60)\n" -"g.flatten(msg)\n" -"text = fp.getvalue()" - -#: ../../library/email.compat32-message.rst:146 -msgid "" -"Equivalent to :meth:`.as_bytes`. Allows ``bytes(msg)`` to produce a bytes " -"object containing the formatted message." -msgstr "" - -#: ../../library/email.compat32-message.rst:154 -msgid "" -"Return ``True`` if the message's payload is a list of sub-\\ :class:" -"`Message` objects, otherwise return ``False``. When :meth:`is_multipart` " -"returns ``False``, the payload should be a string object (which might be a " -"CTE encoded binary payload). (Note that :meth:`is_multipart` returning " -"``True`` does not necessarily mean that \"msg.get_content_maintype() == " -"'multipart'\" will return the ``True``. For example, ``is_multipart`` will " -"return ``True`` when the :class:`Message` is of type ``message/rfc822``.)" -msgstr "" - -#: ../../library/email.compat32-message.rst:166 -msgid "" -"Set the message's envelope header to *unixfrom*, which should be a string." -msgstr "" - -#: ../../library/email.compat32-message.rst:171 -msgid "" -"Return the message's envelope header. Defaults to ``None`` if the envelope " -"header was never set." -msgstr "" - -#: ../../library/email.compat32-message.rst:177 -msgid "" -"Add the given *payload* to the current payload, which must be ``None`` or a " -"list of :class:`Message` objects before the call. After the call, the " -"payload will always be a list of :class:`Message` objects. If you want to " -"set the payload to a scalar object (e.g. a string), use :meth:`set_payload` " -"instead." -msgstr "" - -#: ../../library/email.compat32-message.rst:183 -msgid "" -"This is a legacy method. On the :class:`~email.message.EmailMessage` class " -"its functionality is replaced by :meth:`~email.message.EmailMessage." -"set_content` and the related ``make`` and ``add`` methods." -msgstr "" - -#: ../../library/email.compat32-message.rst:191 -msgid "" -"Return the current payload, which will be a list of :class:`Message` objects " -"when :meth:`is_multipart` is ``True``, or a string when :meth:`is_multipart` " -"is ``False``. If the payload is a list and you mutate the list object, you " -"modify the message's payload in place." -msgstr "" - -#: ../../library/email.compat32-message.rst:196 -msgid "" -"With optional argument *i*, :meth:`get_payload` will return the *i*-th " -"element of the payload, counting from zero, if :meth:`is_multipart` is " -"``True``. An :exc:`IndexError` will be raised if *i* is less than 0 or " -"greater than or equal to the number of items in the payload. If the payload " -"is a string (i.e. :meth:`is_multipart` is ``False``) and *i* is given, a :" -"exc:`TypeError` is raised." -msgstr "" - -#: ../../library/email.compat32-message.rst:203 -msgid "" -"Optional *decode* is a flag indicating whether the payload should be decoded " -"or not, according to the :mailheader:`Content-Transfer-Encoding` header. " -"When ``True`` and the message is not a multipart, the payload will be " -"decoded if this header's value is ``quoted-printable`` or ``base64``. If " -"some other encoding is used, or :mailheader:`Content-Transfer-Encoding` " -"header is missing, the payload is returned as-is (undecoded). In all cases " -"the returned value is binary data. If the message is a multipart and the " -"*decode* flag is ``True``, then ``None`` is returned. If the payload is " -"base64 and it was not perfectly formed (missing padding, characters outside " -"the base64 alphabet), then an appropriate defect will be added to the " -"message's defect property (:class:`~email.errors.InvalidBase64PaddingDefect` " -"or :class:`~email.errors.InvalidBase64CharactersDefect`, respectively)." -msgstr "" - -#: ../../library/email.compat32-message.rst:217 -msgid "" -"When *decode* is ``False`` (the default) the body is returned as a string " -"without decoding the :mailheader:`Content-Transfer-Encoding`. However, for " -"a :mailheader:`Content-Transfer-Encoding` of 8bit, an attempt is made to " -"decode the original bytes using the ``charset`` specified by the :mailheader:" -"`Content-Type` header, using the ``replace`` error handler. If no " -"``charset`` is specified, or if the ``charset`` given is not recognized by " -"the email package, the body is decoded using the default ASCII charset." -msgstr "" - -#: ../../library/email.compat32-message.rst:226 -msgid "" -"This is a legacy method. On the :class:`~email.message.EmailMessage` class " -"its functionality is replaced by :meth:`~email.message.EmailMessage." -"get_content` and :meth:`~email.message.EmailMessage.iter_parts`." -msgstr "" - -#: ../../library/email.compat32-message.rst:234 -msgid "" -"Set the entire message object's payload to *payload*. It is the client's " -"responsibility to ensure the payload invariants. Optional *charset* sets " -"the message's default character set; see :meth:`set_charset` for details." -msgstr "" - -#: ../../library/email.compat32-message.rst:238 -msgid "" -"This is a legacy method. On the :class:`~email.message.EmailMessage` class " -"its functionality is replaced by :meth:`~email.message.EmailMessage." -"set_content`." -msgstr "" - -#: ../../library/email.compat32-message.rst:245 -msgid "" -"Set the character set of the payload to *charset*, which can either be a :" -"class:`~email.charset.Charset` instance (see :mod:`email.charset`), a string " -"naming a character set, or ``None``. If it is a string, it will be " -"converted to a :class:`~email.charset.Charset` instance. If *charset* is " -"``None``, the ``charset`` parameter will be removed from the :mailheader:" -"`Content-Type` header (the message will not be otherwise modified). " -"Anything else will generate a :exc:`TypeError`." -msgstr "" - -#: ../../library/email.compat32-message.rst:253 -msgid "" -"If there is no existing :mailheader:`MIME-Version` header one will be " -"added. If there is no existing :mailheader:`Content-Type` header, one will " -"be added with a value of :mimetype:`text/plain`. Whether the :mailheader:" -"`Content-Type` header already exists or not, its ``charset`` parameter will " -"be set to *charset.output_charset*. If *charset.input_charset* and " -"*charset.output_charset* differ, the payload will be re-encoded to the " -"*output_charset*. If there is no existing :mailheader:`Content-Transfer-" -"Encoding` header, then the payload will be transfer-encoded, if needed, " -"using the specified :class:`~email.charset.Charset`, and a header with the " -"appropriate value will be added. If a :mailheader:`Content-Transfer-" -"Encoding` header already exists, the payload is assumed to already be " -"correctly encoded using that :mailheader:`Content-Transfer-Encoding` and is " -"not modified." -msgstr "" - -#: ../../library/email.compat32-message.rst:267 -msgid "" -"This is a legacy method. On the :class:`~email.message.EmailMessage` class " -"its functionality is replaced by the *charset* parameter of the :meth:`email." -"message.EmailMessage.set_content` method." -msgstr "" - -#: ../../library/email.compat32-message.rst:275 -msgid "" -"Return the :class:`~email.charset.Charset` instance associated with the " -"message's payload." -msgstr "" - -#: ../../library/email.compat32-message.rst:278 -msgid "" -"This is a legacy method. On the :class:`~email.message.EmailMessage` class " -"it always returns ``None``." -msgstr "" - -#: ../../library/email.compat32-message.rst:283 -msgid "" -"The following methods implement a mapping-like interface for accessing the " -"message's :rfc:`2822` headers. Note that there are some semantic " -"differences between these methods and a normal mapping (i.e. dictionary) " -"interface. For example, in a dictionary there are no duplicate keys, but " -"here there may be duplicate message headers. Also, in dictionaries there is " -"no guaranteed order to the keys returned by :meth:`keys`, but in a :class:" -"`Message` object, headers are always returned in the order they appeared in " -"the original message, or were added to the message later. Any header " -"deleted and then re-added are always appended to the end of the header list." -msgstr "" - -#: ../../library/email.compat32-message.rst:293 -msgid "" -"These semantic differences are intentional and are biased toward maximal " -"convenience." -msgstr "" - -#: ../../library/email.compat32-message.rst:296 -msgid "" -"Note that in all cases, any envelope header present in the message is not " -"included in the mapping interface." -msgstr "" - -#: ../../library/email.compat32-message.rst:299 -msgid "" -"In a model generated from bytes, any header values that (in contravention of " -"the RFCs) contain non-ASCII bytes will, when retrieved through this " -"interface, be represented as :class:`~email.header.Header` objects with a " -"charset of ``unknown-8bit``." -msgstr "" - -#: ../../library/email.compat32-message.rst:307 -msgid "Return the total number of headers, including duplicates." -msgstr "" - -#: ../../library/email.compat32-message.rst:312 -msgid "" -"Return ``True`` if the message object has a field named *name*. Matching is " -"done case-insensitively and *name* should not include the trailing colon. " -"Used for the ``in`` operator, e.g.::" -msgstr "" - -#: ../../library/email.compat32-message.rst:316 -msgid "" -"if 'message-id' in myMessage:\n" -" print('Message-ID:', myMessage['message-id'])" -msgstr "" -"if 'message-id' in myMessage:\n" -" print('Message-ID:', myMessage['message-id'])" - -#: ../../library/email.compat32-message.rst:322 -msgid "" -"Return the value of the named header field. *name* should not include the " -"colon field separator. If the header is missing, ``None`` is returned; a :" -"exc:`KeyError` is never raised." -msgstr "" - -#: ../../library/email.compat32-message.rst:326 -msgid "" -"Note that if the named field appears more than once in the message's " -"headers, exactly which of those field values will be returned is undefined. " -"Use the :meth:`get_all` method to get the values of all the extant named " -"headers." -msgstr "" - -#: ../../library/email.compat32-message.rst:334 -msgid "" -"Add a header to the message with field name *name* and value *val*. The " -"field is appended to the end of the message's existing fields." -msgstr "" - -#: ../../library/email.compat32-message.rst:337 -msgid "" -"Note that this does *not* overwrite or delete any existing header with the " -"same name. If you want to ensure that the new header is the only one " -"present in the message with field name *name*, delete the field first, e.g.::" -msgstr "" - -#: ../../library/email.compat32-message.rst:341 -msgid "" -"del msg['subject']\n" -"msg['subject'] = 'Python roolz!'" -msgstr "" -"del msg['subject']\n" -"msg['subject'] = 'Python roolz!'" - -#: ../../library/email.compat32-message.rst:347 -msgid "" -"Delete all occurrences of the field with name *name* from the message's " -"headers. No exception is raised if the named field isn't present in the " -"headers." -msgstr "" - -#: ../../library/email.compat32-message.rst:354 -msgid "Return a list of all the message's header field names." -msgstr "" - -#: ../../library/email.compat32-message.rst:359 -msgid "Return a list of all the message's field values." -msgstr "" - -#: ../../library/email.compat32-message.rst:364 -msgid "" -"Return a list of 2-tuples containing all the message's field headers and " -"values." -msgstr "" - -#: ../../library/email.compat32-message.rst:370 -msgid "" -"Return the value of the named header field. This is identical to :meth:" -"`~object.__getitem__` except that optional *failobj* is returned if the " -"named header is missing (defaults to ``None``)." -msgstr "" - -#: ../../library/email.compat32-message.rst:374 -msgid "Here are some additional useful methods:" -msgstr "" - -#: ../../library/email.compat32-message.rst:379 -msgid "" -"Return a list of all the values for the field named *name*. If there are no " -"such named headers in the message, *failobj* is returned (defaults to " -"``None``)." -msgstr "" - -#: ../../library/email.compat32-message.rst:386 -msgid "" -"Extended header setting. This method is similar to :meth:`__setitem__` " -"except that additional header parameters can be provided as keyword " -"arguments. *_name* is the header field to add and *_value* is the *primary* " -"value for the header." -msgstr "" - -#: ../../library/email.compat32-message.rst:391 -msgid "" -"For each item in the keyword argument dictionary *_params*, the key is taken " -"as the parameter name, with underscores converted to dashes (since dashes " -"are illegal in Python identifiers). Normally, the parameter will be added " -"as ``key=\"value\"`` unless the value is ``None``, in which case only the " -"key will be added. If the value contains non-ASCII characters, it can be " -"specified as a three tuple in the format ``(CHARSET, LANGUAGE, VALUE)``, " -"where ``CHARSET`` is a string naming the charset to be used to encode the " -"value, ``LANGUAGE`` can usually be set to ``None`` or the empty string (see :" -"rfc:`2231` for other possibilities), and ``VALUE`` is the string value " -"containing non-ASCII code points. If a three tuple is not passed and the " -"value contains non-ASCII characters, it is automatically encoded in :rfc:" -"`2231` format using a ``CHARSET`` of ``utf-8`` and a ``LANGUAGE`` of " -"``None``." -msgstr "" - -#: ../../library/email.compat32-message.rst:405 -msgid "Here's an example::" -msgstr "以下是個範例： ::" - -#: ../../library/email.compat32-message.rst:407 -msgid "msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')" -msgstr "" -"msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')" - -#: ../../library/email.compat32-message.rst:409 -msgid "This will add a header that looks like ::" -msgstr "" - -#: ../../library/email.compat32-message.rst:411 -msgid "Content-Disposition: attachment; filename=\"bud.gif\"" -msgstr "Content-Disposition: attachment; filename=\"bud.gif\"" - -#: ../../library/email.compat32-message.rst:413 -msgid "An example with non-ASCII characters::" -msgstr "" - -#: ../../library/email.compat32-message.rst:415 -msgid "" -"msg.add_header('Content-Disposition', 'attachment',\n" -" filename=('iso-8859-1', '', 'Fußballer.ppt'))" -msgstr "" -"msg.add_header('Content-Disposition', 'attachment',\n" -" filename=('iso-8859-1', '', 'Fußballer.ppt'))" - -#: ../../library/email.compat32-message.rst:418 -msgid "Which produces ::" -msgstr "" - -#: ../../library/email.compat32-message.rst:420 -msgid "" -"Content-Disposition: attachment; filename*=\"iso-8859-1''Fu%DFballer.ppt\"" -msgstr "" -"Content-Disposition: attachment; filename*=\"iso-8859-1''Fu%DFballer.ppt\"" - -#: ../../library/email.compat32-message.rst:425 -msgid "" -"Replace a header. Replace the first header found in the message that " -"matches *_name*, retaining header order and field name case. If no matching " -"header was found, a :exc:`KeyError` is raised." -msgstr "" - -#: ../../library/email.compat32-message.rst:432 -msgid "" -"Return the message's content type. The returned string is coerced to lower " -"case of the form :mimetype:`maintype/subtype`. If there was no :mailheader:" -"`Content-Type` header in the message the default type as given by :meth:" -"`get_default_type` will be returned. Since according to :rfc:`2045`, " -"messages always have a default type, :meth:`get_content_type` will always " -"return a value." -msgstr "" - -#: ../../library/email.compat32-message.rst:439 -msgid "" -":rfc:`2045` defines a message's default type to be :mimetype:`text/plain` " -"unless it appears inside a :mimetype:`multipart/digest` container, in which " -"case it would be :mimetype:`message/rfc822`. If the :mailheader:`Content-" -"Type` header has an invalid type specification, :rfc:`2045` mandates that " -"the default type be :mimetype:`text/plain`." -msgstr "" - -#: ../../library/email.compat32-message.rst:448 -msgid "" -"Return the message's main content type. This is the :mimetype:`maintype` " -"part of the string returned by :meth:`get_content_type`." -msgstr "" - -#: ../../library/email.compat32-message.rst:454 -msgid "" -"Return the message's sub-content type. This is the :mimetype:`subtype` part " -"of the string returned by :meth:`get_content_type`." -msgstr "" - -#: ../../library/email.compat32-message.rst:460 -msgid "" -"Return the default content type. Most messages have a default content type " -"of :mimetype:`text/plain`, except for messages that are subparts of :" -"mimetype:`multipart/digest` containers. Such subparts have a default " -"content type of :mimetype:`message/rfc822`." -msgstr "" - -#: ../../library/email.compat32-message.rst:468 -msgid "" -"Set the default content type. *ctype* should either be :mimetype:`text/" -"plain` or :mimetype:`message/rfc822`, although this is not enforced. The " -"default content type is not stored in the :mailheader:`Content-Type` header." -msgstr "" - -#: ../../library/email.compat32-message.rst:476 -msgid "" -"Return the message's :mailheader:`Content-Type` parameters, as a list. The " -"elements of the returned list are 2-tuples of key/value pairs, as split on " -"the ``'='`` sign. The left hand side of the ``'='`` is the key, while the " -"right hand side is the value. If there is no ``'='`` sign in the parameter " -"the value is the empty string, otherwise the value is as described in :meth:" -"`get_param` and is unquoted if optional *unquote* is ``True`` (the default)." -msgstr "" - -#: ../../library/email.compat32-message.rst:484 -msgid "" -"Optional *failobj* is the object to return if there is no :mailheader:" -"`Content-Type` header. Optional *header* is the header to search instead " -"of :mailheader:`Content-Type`." -msgstr "" - -#: ../../library/email.compat32-message.rst:488 -#: ../../library/email.compat32-message.rst:526 -msgid "" -"This is a legacy method. On the :class:`~email.message.EmailMessage` class " -"its functionality is replaced by the *params* property of the individual " -"header objects returned by the header access methods." -msgstr "" - -#: ../../library/email.compat32-message.rst:496 -msgid "" -"Return the value of the :mailheader:`Content-Type` header's parameter " -"*param* as a string. If the message has no :mailheader:`Content-Type` " -"header or if there is no such parameter, then *failobj* is returned " -"(defaults to ``None``)." -msgstr "" - -#: ../../library/email.compat32-message.rst:501 -msgid "" -"Optional *header* if given, specifies the message header to use instead of :" -"mailheader:`Content-Type`." -msgstr "" - -#: ../../library/email.compat32-message.rst:504 -msgid "" -"Parameter keys are always compared case insensitively. The return value can " -"either be a string, or a 3-tuple if the parameter was :rfc:`2231` encoded. " -"When it's a 3-tuple, the elements of the value are of the form ``(CHARSET, " -"LANGUAGE, VALUE)``. Note that both ``CHARSET`` and ``LANGUAGE`` can be " -"``None``, in which case you should consider ``VALUE`` to be encoded in the " -"``us-ascii`` charset. You can usually ignore ``LANGUAGE``." -msgstr "" - -#: ../../library/email.compat32-message.rst:512 -msgid "" -"If your application doesn't care whether the parameter was encoded as in :" -"rfc:`2231`, you can collapse the parameter value by calling :func:`email." -"utils.collapse_rfc2231_value`, passing in the return value from :meth:" -"`get_param`. This will return a suitably decoded Unicode string when the " -"value is a tuple, or the original string unquoted if it isn't. For example::" -msgstr "" - -#: ../../library/email.compat32-message.rst:519 -msgid "" -"rawparam = msg.get_param('foo')\n" -"param = email.utils.collapse_rfc2231_value(rawparam)" -msgstr "" -"rawparam = msg.get_param('foo')\n" -"param = email.utils.collapse_rfc2231_value(rawparam)" - -#: ../../library/email.compat32-message.rst:522 -msgid "" -"In any case, the parameter value (either the returned string, or the " -"``VALUE`` item in the 3-tuple) is always unquoted, unless *unquote* is set " -"to ``False``." -msgstr "" - -#: ../../library/email.compat32-message.rst:535 -msgid "" -"Set a parameter in the :mailheader:`Content-Type` header. If the parameter " -"already exists in the header, its value will be replaced with *value*. If " -"the :mailheader:`Content-Type` header as not yet been defined for this " -"message, it will be set to :mimetype:`text/plain` and the new parameter " -"value will be appended as per :rfc:`2045`." -msgstr "" - -#: ../../library/email.compat32-message.rst:541 -msgid "" -"Optional *header* specifies an alternative header to :mailheader:`Content-" -"Type`, and all parameters will be quoted as necessary unless optional " -"*requote* is ``False`` (the default is ``True``)." -msgstr "" - -#: ../../library/email.compat32-message.rst:545 -msgid "" -"If optional *charset* is specified, the parameter will be encoded according " -"to :rfc:`2231`. Optional *language* specifies the RFC 2231 language, " -"defaulting to the empty string. Both *charset* and *language* should be " -"strings." -msgstr "" - -#: ../../library/email.compat32-message.rst:550 -msgid "" -"If *replace* is ``False`` (the default) the header is moved to the end of " -"the list of headers. If *replace* is ``True``, the header will be updated " -"in place." -msgstr "" - -#: ../../library/email.compat32-message.rst:554 -msgid "``replace`` keyword was added." -msgstr "新增 ``replace`` 關鍵字。" - -#: ../../library/email.compat32-message.rst:559 -msgid "" -"Remove the given parameter completely from the :mailheader:`Content-Type` " -"header. The header will be re-written in place without the parameter or its " -"value. All values will be quoted as necessary unless *requote* is ``False`` " -"(the default is ``True``). Optional *header* specifies an alternative to :" -"mailheader:`Content-Type`." -msgstr "" - -#: ../../library/email.compat32-message.rst:568 -msgid "" -"Set the main type and subtype for the :mailheader:`Content-Type` header. " -"*type* must be a string in the form :mimetype:`maintype/subtype`, otherwise " -"a :exc:`ValueError` is raised." -msgstr "" - -#: ../../library/email.compat32-message.rst:572 -msgid "" -"This method replaces the :mailheader:`Content-Type` header, keeping all the " -"parameters in place. If *requote* is ``False``, this leaves the existing " -"header's quoting as is, otherwise the parameters will be quoted (the " -"default)." -msgstr "" - -#: ../../library/email.compat32-message.rst:577 -msgid "" -"An alternative header can be specified in the *header* argument. When the :" -"mailheader:`Content-Type` header is set a :mailheader:`MIME-Version` header " -"is also added." -msgstr "" - -#: ../../library/email.compat32-message.rst:581 -msgid "" -"This is a legacy method. On the :class:`~email.message.EmailMessage` class " -"its functionality is replaced by the ``make_`` and ``add_`` methods." -msgstr "" - -#: ../../library/email.compat32-message.rst:588 -msgid "" -"Return the value of the ``filename`` parameter of the :mailheader:`Content-" -"Disposition` header of the message. If the header does not have a " -"``filename`` parameter, this method falls back to looking for the ``name`` " -"parameter on the :mailheader:`Content-Type` header. If neither is found, or " -"the header is missing, then *failobj* is returned. The returned string will " -"always be unquoted as per :func:`email.utils.unquote`." -msgstr "" - -#: ../../library/email.compat32-message.rst:599 -msgid "" -"Return the value of the ``boundary`` parameter of the :mailheader:`Content-" -"Type` header of the message, or *failobj* if either the header is missing, " -"or has no ``boundary`` parameter. The returned string will always be " -"unquoted as per :func:`email.utils.unquote`." -msgstr "" - -#: ../../library/email.compat32-message.rst:607 -msgid "" -"Set the ``boundary`` parameter of the :mailheader:`Content-Type` header to " -"*boundary*. :meth:`set_boundary` will always quote *boundary* if " -"necessary. A :exc:`~email.errors.HeaderParseError` is raised if the message " -"object has no :mailheader:`Content-Type` header." -msgstr "" - -#: ../../library/email.compat32-message.rst:612 -msgid "" -"Note that using this method is subtly different than deleting the old :" -"mailheader:`Content-Type` header and adding a new one with the new boundary " -"via :meth:`add_header`, because :meth:`set_boundary` preserves the order of " -"the :mailheader:`Content-Type` header in the list of headers. However, it " -"does *not* preserve any continuation lines which may have been present in " -"the original :mailheader:`Content-Type` header." -msgstr "" - -#: ../../library/email.compat32-message.rst:622 -msgid "" -"Return the ``charset`` parameter of the :mailheader:`Content-Type` header, " -"coerced to lower case. If there is no :mailheader:`Content-Type` header, or " -"if that header has no ``charset`` parameter, *failobj* is returned." -msgstr "" - -#: ../../library/email.compat32-message.rst:626 -msgid "" -"Note that this method differs from :meth:`get_charset` which returns the :" -"class:`~email.charset.Charset` instance for the default encoding of the " -"message body." -msgstr "" - -#: ../../library/email.compat32-message.rst:632 -msgid "" -"Return a list containing the character set names in the message. If the " -"message is a :mimetype:`multipart`, then the list will contain one element " -"for each subpart in the payload, otherwise, it will be a list of length 1." -msgstr "" - -#: ../../library/email.compat32-message.rst:636 -msgid "" -"Each item in the list will be a string which is the value of the ``charset`` " -"parameter in the :mailheader:`Content-Type` header for the represented " -"subpart. However, if the subpart has no :mailheader:`Content-Type` header, " -"no ``charset`` parameter, or is not of the :mimetype:`text` main MIME type, " -"then that item in the returned list will be *failobj*." -msgstr "" - -#: ../../library/email.compat32-message.rst:646 -msgid "" -"Return the lowercased value (without parameters) of the message's :" -"mailheader:`Content-Disposition` header if it has one, or ``None``. The " -"possible values for this method are *inline*, *attachment* or ``None`` if " -"the message follows :rfc:`2183`." -msgstr "" - -#: ../../library/email.compat32-message.rst:655 -msgid "" -"The :meth:`walk` method is an all-purpose generator which can be used to " -"iterate over all the parts and subparts of a message object tree, in depth-" -"first traversal order. You will typically use :meth:`walk` as the iterator " -"in a ``for`` loop; each iteration returns the next subpart." -msgstr "" - -#: ../../library/email.compat32-message.rst:660 -msgid "" -"Here's an example that prints the MIME type of every part of a multipart " -"message structure:" -msgstr "" - -#: ../../library/email.compat32-message.rst:674 -msgid "" -">>> for part in msg.walk():\n" -"... print(part.get_content_type())\n" -"multipart/report\n" -"text/plain\n" -"message/delivery-status\n" -"text/plain\n" -"text/plain\n" -"message/rfc822\n" -"text/plain" -msgstr "" -">>> for part in msg.walk():\n" -"... print(part.get_content_type())\n" -"multipart/report\n" -"text/plain\n" -"message/delivery-status\n" -"text/plain\n" -"text/plain\n" -"message/rfc822\n" -"text/plain" - -#: ../../library/email.compat32-message.rst:686 -msgid "" -"``walk`` iterates over the subparts of any part where :meth:`is_multipart` " -"returns ``True``, even though ``msg.get_content_maintype() == 'multipart'`` " -"may return ``False``. We can see this in our example by making use of the " -"``_structure`` debug helper function:" -msgstr "" - -#: ../../library/email.compat32-message.rst:692 -msgid "" -">>> for part in msg.walk():\n" -"... print(part.get_content_maintype() == 'multipart',\n" -"... part.is_multipart())\n" -"True True\n" -"False False\n" -"False True\n" -"False False\n" -"False False\n" -"False True\n" -"False False\n" -">>> _structure(msg)\n" -"multipart/report\n" -" text/plain\n" -" message/delivery-status\n" -" text/plain\n" -" text/plain\n" -" message/rfc822\n" -" text/plain" -msgstr "" -">>> for part in msg.walk():\n" -"... print(part.get_content_maintype() == 'multipart',\n" -"... part.is_multipart())\n" -"True True\n" -"False False\n" -"False True\n" -"False False\n" -"False False\n" -"False True\n" -"False False\n" -">>> _structure(msg)\n" -"multipart/report\n" -" text/plain\n" -" message/delivery-status\n" -" text/plain\n" -" text/plain\n" -" message/rfc822\n" -" text/plain" - -#: ../../library/email.compat32-message.rst:713 -msgid "" -"Here the ``message`` parts are not ``multiparts``, but they do contain " -"subparts. ``is_multipart()`` returns ``True`` and ``walk`` descends into the " -"subparts." -msgstr "" - -#: ../../library/email.compat32-message.rst:718 -msgid "" -":class:`Message` objects can also optionally contain two instance " -"attributes, which can be used when generating the plain text of a MIME " -"message." -msgstr "" - -#: ../../library/email.compat32-message.rst:724 -msgid "" -"The format of a MIME document allows for some text between the blank line " -"following the headers, and the first multipart boundary string. Normally, " -"this text is never visible in a MIME-aware mail reader because it falls " -"outside the standard MIME armor. However, when viewing the raw text of the " -"message, or when viewing the message in a non-MIME aware reader, this text " -"can become visible." -msgstr "" - -#: ../../library/email.compat32-message.rst:731 -msgid "" -"The *preamble* attribute contains this leading extra-armor text for MIME " -"documents. When the :class:`~email.parser.Parser` discovers some text after " -"the headers but before the first boundary string, it assigns this text to " -"the message's *preamble* attribute. When the :class:`~email.generator." -"Generator` is writing out the plain text representation of a MIME message, " -"and it finds the message has a *preamble* attribute, it will write this text " -"in the area between the headers and the first boundary. See :mod:`email." -"parser` and :mod:`email.generator` for details." -msgstr "" - -#: ../../library/email.compat32-message.rst:741 -msgid "" -"Note that if the message object has no preamble, the *preamble* attribute " -"will be ``None``." -msgstr "" - -#: ../../library/email.compat32-message.rst:747 -msgid "" -"The *epilogue* attribute acts the same way as the *preamble* attribute, " -"except that it contains text that appears between the last boundary and the " -"end of the message." -msgstr "" - -#: ../../library/email.compat32-message.rst:751 -msgid "" -"You do not need to set the epilogue to the empty string in order for the :" -"class:`~email.generator.Generator` to print a newline at the end of the file." -msgstr "" - -#: ../../library/email.compat32-message.rst:758 -msgid "" -"The *defects* attribute contains a list of all the problems found when " -"parsing this message. See :mod:`email.errors` for a detailed description of " -"the possible parsing defects." -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-07-07 17:47+0000\n" +"PO-Revision-Date: 2018-07-15 18:56+0800\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/email.compat32-message.rst:4 +msgid "" +":mod:`email.message.Message`: Representing an email message using the :data:" +"`~email.policy.compat32` API" +msgstr "" + +#: ../../library/email.compat32-message.rst:13 +msgid "" +"The :class:`Message` class is very similar to the :class:`~email.message." +"EmailMessage` class, without the methods added by that class, and with the " +"default behavior of certain other methods being slightly different. We also " +"document here some methods that, while supported by the :class:`~email." +"message.EmailMessage` class, are not recommended unless you are dealing with " +"legacy code." +msgstr "" + +#: ../../library/email.compat32-message.rst:20 +msgid "The philosophy and structure of the two classes is otherwise the same." +msgstr "" + +#: ../../library/email.compat32-message.rst:22 +msgid "" +"This document describes the behavior under the default (for :class:" +"`Message`) policy :attr:`~email.policy.Compat32`. If you are going to use " +"another policy, you should be using the :class:`~email.message.EmailMessage` " +"class instead." +msgstr "" + +#: ../../library/email.compat32-message.rst:26 +msgid "" +"An email message consists of *headers* and a *payload*. Headers must be :" +"rfc:`5322` style names and values, where the field name and value are " +"separated by a colon. The colon is not part of either the field name or the " +"field value. The payload may be a simple text message, or a binary object, " +"or a structured sequence of sub-messages each with their own set of headers " +"and their own payload. The latter type of payload is indicated by the " +"message having a MIME type such as :mimetype:`multipart/\\*` or :mimetype:" +"`message/rfc822`." +msgstr "" + +#: ../../library/email.compat32-message.rst:35 +msgid "" +"The conceptual model provided by a :class:`Message` object is that of an " +"ordered dictionary of headers with additional methods for accessing both " +"specialized information from the headers, for accessing the payload, for " +"generating a serialized version of the message, and for recursively walking " +"over the object tree. Note that duplicate headers are supported but special " +"methods must be used to access them." +msgstr "" + +#: ../../library/email.compat32-message.rst:42 +msgid "" +"The :class:`Message` pseudo-dictionary is indexed by the header names, which " +"must be ASCII values. The values of the dictionary are strings that are " +"supposed to contain only ASCII characters; there is some special handling " +"for non-ASCII input, but it doesn't always produce the correct results. " +"Headers are stored and returned in case-preserving form, but field names are " +"matched case-insensitively. There may also be a single envelope header, " +"also known as the *Unix-From* header or the ``From_`` header. The *payload* " +"is either a string or bytes, in the case of simple message objects, or a " +"list of :class:`Message` objects, for MIME container documents (e.g. :" +"mimetype:`multipart/\\*` and :mimetype:`message/rfc822`)." +msgstr "" + +#: ../../library/email.compat32-message.rst:53 +msgid "Here are the methods of the :class:`Message` class:" +msgstr "" + +#: ../../library/email.compat32-message.rst:58 +msgid "" +"If *policy* is specified (it must be an instance of a :mod:`~email.policy` " +"class) use the rules it specifies to update and serialize the representation " +"of the message. If *policy* is not set, use the :class:`compat32 ` policy, which maintains backward compatibility with the " +"Python 3.2 version of the email package. For more information see the :mod:" +"`~email.policy` documentation." +msgstr "" + +#: ../../library/email.compat32-message.rst:65 +msgid "The *policy* keyword argument was added." +msgstr "新增 *policy* 關鍵字引數。" + +#: ../../library/email.compat32-message.rst:70 +msgid "" +"Return the entire message flattened as a string. When optional *unixfrom* " +"is true, the envelope header is included in the returned string. *unixfrom* " +"defaults to ``False``. For backward compatibility reasons, *maxheaderlen* " +"defaults to ``0``, so if you want a different value you must override it " +"explicitly (the value specified for *max_line_length* in the policy will be " +"ignored by this method). The *policy* argument may be used to override the " +"default policy obtained from the message instance. This can be used to " +"control some of the formatting produced by the method, since the specified " +"*policy* will be passed to the ``Generator``." +msgstr "" + +#: ../../library/email.compat32-message.rst:80 +#: ../../library/email.compat32-message.rst:122 +msgid "" +"Flattening the message may trigger changes to the :class:`Message` if " +"defaults need to be filled in to complete the transformation to a string " +"(for example, MIME boundaries may be generated or modified)." +msgstr "" + +#: ../../library/email.compat32-message.rst:84 +msgid "" +"Note that this method is provided as a convenience and may not always format " +"the message the way you want. For example, by default it does not do the " +"mangling of lines that begin with ``From`` that is required by the Unix mbox " +"format. For more flexibility, instantiate a :class:`~email.generator." +"Generator` instance and use its :meth:`~email.generator.Generator.flatten` " +"method directly. For example::" +msgstr "" + +#: ../../library/email.compat32-message.rst:91 +msgid "" +"from io import StringIO\n" +"from email.generator import Generator\n" +"fp = StringIO()\n" +"g = Generator(fp, mangle_from_=True, maxheaderlen=60)\n" +"g.flatten(msg)\n" +"text = fp.getvalue()" +msgstr "" +"from io import StringIO\n" +"from email.generator import Generator\n" +"fp = StringIO()\n" +"g = Generator(fp, mangle_from_=True, maxheaderlen=60)\n" +"g.flatten(msg)\n" +"text = fp.getvalue()" + +#: ../../library/email.compat32-message.rst:98 +msgid "" +"If the message object contains binary data that is not encoded according to " +"RFC standards, the non-compliant data will be replaced by unicode \"unknown " +"character\" code points. (See also :meth:`.as_bytes` and :class:`~email." +"generator.BytesGenerator`.)" +msgstr "" + +#: ../../library/email.compat32-message.rst:103 +msgid "the *policy* keyword argument was added." +msgstr "新增 *policy* 關鍵字引數。" + +#: ../../library/email.compat32-message.rst:108 +msgid "" +"Equivalent to :meth:`.as_string`. Allows ``str(msg)`` to produce a string " +"containing the formatted message." +msgstr "" + +#: ../../library/email.compat32-message.rst:114 +msgid "" +"Return the entire message flattened as a bytes object. When optional " +"*unixfrom* is true, the envelope header is included in the returned string. " +"*unixfrom* defaults to ``False``. The *policy* argument may be used to " +"override the default policy obtained from the message instance. This can be " +"used to control some of the formatting produced by the method, since the " +"specified *policy* will be passed to the ``BytesGenerator``." +msgstr "" + +#: ../../library/email.compat32-message.rst:126 +msgid "" +"Note that this method is provided as a convenience and may not always format " +"the message the way you want. For example, by default it does not do the " +"mangling of lines that begin with ``From`` that is required by the Unix mbox " +"format. For more flexibility, instantiate a :class:`~email.generator." +"BytesGenerator` instance and use its :meth:`~email.generator.BytesGenerator." +"flatten` method directly. For example::" +msgstr "" + +#: ../../library/email.compat32-message.rst:134 +msgid "" +"from io import BytesIO\n" +"from email.generator import BytesGenerator\n" +"fp = BytesIO()\n" +"g = BytesGenerator(fp, mangle_from_=True, maxheaderlen=60)\n" +"g.flatten(msg)\n" +"text = fp.getvalue()" +msgstr "" +"from io import BytesIO\n" +"from email.generator import BytesGenerator\n" +"fp = BytesIO()\n" +"g = BytesGenerator(fp, mangle_from_=True, maxheaderlen=60)\n" +"g.flatten(msg)\n" +"text = fp.getvalue()" + +#: ../../library/email.compat32-message.rst:146 +msgid "" +"Equivalent to :meth:`.as_bytes`. Allows ``bytes(msg)`` to produce a bytes " +"object containing the formatted message." +msgstr "" + +#: ../../library/email.compat32-message.rst:154 +msgid "" +"Return ``True`` if the message's payload is a list of sub-\\ :class:" +"`Message` objects, otherwise return ``False``. When :meth:`is_multipart` " +"returns ``False``, the payload should be a string object (which might be a " +"CTE encoded binary payload). (Note that :meth:`is_multipart` returning " +"``True`` does not necessarily mean that \"msg.get_content_maintype() == " +"'multipart'\" will return the ``True``. For example, ``is_multipart`` will " +"return ``True`` when the :class:`Message` is of type ``message/rfc822``.)" +msgstr "" + +#: ../../library/email.compat32-message.rst:166 +msgid "" +"Set the message's envelope header to *unixfrom*, which should be a string." +msgstr "" + +#: ../../library/email.compat32-message.rst:171 +msgid "" +"Return the message's envelope header. Defaults to ``None`` if the envelope " +"header was never set." +msgstr "" + +#: ../../library/email.compat32-message.rst:177 +msgid "" +"Add the given *payload* to the current payload, which must be ``None`` or a " +"list of :class:`Message` objects before the call. After the call, the " +"payload will always be a list of :class:`Message` objects. If you want to " +"set the payload to a scalar object (e.g. a string), use :meth:`set_payload` " +"instead." +msgstr "" + +#: ../../library/email.compat32-message.rst:183 +msgid "" +"This is a legacy method. On the :class:`~email.message.EmailMessage` class " +"its functionality is replaced by :meth:`~email.message.EmailMessage." +"set_content` and the related ``make`` and ``add`` methods." +msgstr "" + +#: ../../library/email.compat32-message.rst:191 +msgid "" +"Return the current payload, which will be a list of :class:`Message` objects " +"when :meth:`is_multipart` is ``True``, or a string when :meth:`is_multipart` " +"is ``False``. If the payload is a list and you mutate the list object, you " +"modify the message's payload in place." +msgstr "" + +#: ../../library/email.compat32-message.rst:196 +msgid "" +"With optional argument *i*, :meth:`get_payload` will return the *i*-th " +"element of the payload, counting from zero, if :meth:`is_multipart` is " +"``True``. An :exc:`IndexError` will be raised if *i* is less than 0 or " +"greater than or equal to the number of items in the payload. If the payload " +"is a string (i.e. :meth:`is_multipart` is ``False``) and *i* is given, a :" +"exc:`TypeError` is raised." +msgstr "" + +#: ../../library/email.compat32-message.rst:203 +msgid "" +"Optional *decode* is a flag indicating whether the payload should be decoded " +"or not, according to the :mailheader:`Content-Transfer-Encoding` header. " +"When ``True`` and the message is not a multipart, the payload will be " +"decoded if this header's value is ``quoted-printable`` or ``base64``. If " +"some other encoding is used, or :mailheader:`Content-Transfer-Encoding` " +"header is missing, the payload is returned as-is (undecoded). In all cases " +"the returned value is binary data. If the message is a multipart and the " +"*decode* flag is ``True``, then ``None`` is returned. If the payload is " +"base64 and it was not perfectly formed (missing padding, characters outside " +"the base64 alphabet), then an appropriate defect will be added to the " +"message's defect property (:class:`~email.errors.InvalidBase64PaddingDefect` " +"or :class:`~email.errors.InvalidBase64CharactersDefect`, respectively)." +msgstr "" + +#: ../../library/email.compat32-message.rst:217 +msgid "" +"When *decode* is ``False`` (the default) the body is returned as a string " +"without decoding the :mailheader:`Content-Transfer-Encoding`. However, for " +"a :mailheader:`Content-Transfer-Encoding` of 8bit, an attempt is made to " +"decode the original bytes using the ``charset`` specified by the :mailheader:" +"`Content-Type` header, using the ``replace`` error handler. If no " +"``charset`` is specified, or if the ``charset`` given is not recognized by " +"the email package, the body is decoded using the default ASCII charset." +msgstr "" + +#: ../../library/email.compat32-message.rst:226 +msgid "" +"This is a legacy method. On the :class:`~email.message.EmailMessage` class " +"its functionality is replaced by :meth:`~email.message.EmailMessage." +"get_content` and :meth:`~email.message.EmailMessage.iter_parts`." +msgstr "" + +#: ../../library/email.compat32-message.rst:234 +msgid "" +"Set the entire message object's payload to *payload*. It is the client's " +"responsibility to ensure the payload invariants. Optional *charset* sets " +"the message's default character set; see :meth:`set_charset` for details." +msgstr "" + +#: ../../library/email.compat32-message.rst:238 +msgid "" +"This is a legacy method. On the :class:`~email.message.EmailMessage` class " +"its functionality is replaced by :meth:`~email.message.EmailMessage." +"set_content`." +msgstr "" + +#: ../../library/email.compat32-message.rst:245 +msgid "" +"Set the character set of the payload to *charset*, which can either be a :" +"class:`~email.charset.Charset` instance (see :mod:`email.charset`), a string " +"naming a character set, or ``None``. If it is a string, it will be " +"converted to a :class:`~email.charset.Charset` instance. If *charset* is " +"``None``, the ``charset`` parameter will be removed from the :mailheader:" +"`Content-Type` header (the message will not be otherwise modified). " +"Anything else will generate a :exc:`TypeError`." +msgstr "" + +#: ../../library/email.compat32-message.rst:253 +msgid "" +"If there is no existing :mailheader:`MIME-Version` header one will be " +"added. If there is no existing :mailheader:`Content-Type` header, one will " +"be added with a value of :mimetype:`text/plain`. Whether the :mailheader:" +"`Content-Type` header already exists or not, its ``charset`` parameter will " +"be set to *charset.output_charset*. If *charset.input_charset* and " +"*charset.output_charset* differ, the payload will be re-encoded to the " +"*output_charset*. If there is no existing :mailheader:`Content-Transfer-" +"Encoding` header, then the payload will be transfer-encoded, if needed, " +"using the specified :class:`~email.charset.Charset`, and a header with the " +"appropriate value will be added. If a :mailheader:`Content-Transfer-" +"Encoding` header already exists, the payload is assumed to already be " +"correctly encoded using that :mailheader:`Content-Transfer-Encoding` and is " +"not modified." +msgstr "" + +#: ../../library/email.compat32-message.rst:267 +msgid "" +"This is a legacy method. On the :class:`~email.message.EmailMessage` class " +"its functionality is replaced by the *charset* parameter of the :meth:`email." +"message.EmailMessage.set_content` method." +msgstr "" + +#: ../../library/email.compat32-message.rst:275 +msgid "" +"Return the :class:`~email.charset.Charset` instance associated with the " +"message's payload." +msgstr "" + +#: ../../library/email.compat32-message.rst:278 +msgid "" +"This is a legacy method. On the :class:`~email.message.EmailMessage` class " +"it always returns ``None``." +msgstr "" + +#: ../../library/email.compat32-message.rst:283 +msgid "" +"The following methods implement a mapping-like interface for accessing the " +"message's :rfc:`2822` headers. Note that there are some semantic " +"differences between these methods and a normal mapping (i.e. dictionary) " +"interface. For example, in a dictionary there are no duplicate keys, but " +"here there may be duplicate message headers. Also, in dictionaries there is " +"no guaranteed order to the keys returned by :meth:`keys`, but in a :class:" +"`Message` object, headers are always returned in the order they appeared in " +"the original message, or were added to the message later. Any header " +"deleted and then re-added are always appended to the end of the header list." +msgstr "" + +#: ../../library/email.compat32-message.rst:293 +msgid "" +"These semantic differences are intentional and are biased toward maximal " +"convenience." +msgstr "" + +#: ../../library/email.compat32-message.rst:296 +msgid "" +"Note that in all cases, any envelope header present in the message is not " +"included in the mapping interface." +msgstr "" + +#: ../../library/email.compat32-message.rst:299 +msgid "" +"In a model generated from bytes, any header values that (in contravention of " +"the RFCs) contain non-ASCII bytes will, when retrieved through this " +"interface, be represented as :class:`~email.header.Header` objects with a " +"charset of ``unknown-8bit``." +msgstr "" + +#: ../../library/email.compat32-message.rst:307 +msgid "Return the total number of headers, including duplicates." +msgstr "" + +#: ../../library/email.compat32-message.rst:312 +msgid "" +"Return ``True`` if the message object has a field named *name*. Matching is " +"done case-insensitively and *name* should not include the trailing colon. " +"Used for the ``in`` operator, e.g.::" +msgstr "" + +#: ../../library/email.compat32-message.rst:316 +msgid "" +"if 'message-id' in myMessage:\n" +" print('Message-ID:', myMessage['message-id'])" +msgstr "" +"if 'message-id' in myMessage:\n" +" print('Message-ID:', myMessage['message-id'])" + +#: ../../library/email.compat32-message.rst:322 +msgid "" +"Return the value of the named header field. *name* should not include the " +"colon field separator. If the header is missing, ``None`` is returned; a :" +"exc:`KeyError` is never raised." +msgstr "" + +#: ../../library/email.compat32-message.rst:326 +msgid "" +"Note that if the named field appears more than once in the message's " +"headers, exactly which of those field values will be returned is undefined. " +"Use the :meth:`get_all` method to get the values of all the extant named " +"headers." +msgstr "" + +#: ../../library/email.compat32-message.rst:334 +msgid "" +"Add a header to the message with field name *name* and value *val*. The " +"field is appended to the end of the message's existing fields." +msgstr "" + +#: ../../library/email.compat32-message.rst:337 +msgid "" +"Note that this does *not* overwrite or delete any existing header with the " +"same name. If you want to ensure that the new header is the only one " +"present in the message with field name *name*, delete the field first, e.g.::" +msgstr "" + +#: ../../library/email.compat32-message.rst:341 +msgid "" +"del msg['subject']\n" +"msg['subject'] = 'Python roolz!'" +msgstr "" +"del msg['subject']\n" +"msg['subject'] = 'Python roolz!'" + +#: ../../library/email.compat32-message.rst:347 +msgid "" +"Delete all occurrences of the field with name *name* from the message's " +"headers. No exception is raised if the named field isn't present in the " +"headers." +msgstr "" + +#: ../../library/email.compat32-message.rst:354 +msgid "Return a list of all the message's header field names." +msgstr "" + +#: ../../library/email.compat32-message.rst:359 +msgid "Return a list of all the message's field values." +msgstr "" + +#: ../../library/email.compat32-message.rst:364 +msgid "" +"Return a list of 2-tuples containing all the message's field headers and " +"values." +msgstr "" + +#: ../../library/email.compat32-message.rst:370 +msgid "" +"Return the value of the named header field. This is identical to :meth:" +"`~object.__getitem__` except that optional *failobj* is returned if the " +"named header is missing (defaults to ``None``)." +msgstr "" + +#: ../../library/email.compat32-message.rst:374 +msgid "Here are some additional useful methods:" +msgstr "" + +#: ../../library/email.compat32-message.rst:379 +msgid "" +"Return a list of all the values for the field named *name*. If there are no " +"such named headers in the message, *failobj* is returned (defaults to " +"``None``)." +msgstr "" + +#: ../../library/email.compat32-message.rst:386 +msgid "" +"Extended header setting. This method is similar to :meth:`__setitem__` " +"except that additional header parameters can be provided as keyword " +"arguments. *_name* is the header field to add and *_value* is the *primary* " +"value for the header." +msgstr "" + +#: ../../library/email.compat32-message.rst:391 +msgid "" +"For each item in the keyword argument dictionary *_params*, the key is taken " +"as the parameter name, with underscores converted to dashes (since dashes " +"are illegal in Python identifiers). Normally, the parameter will be added " +"as ``key=\"value\"`` unless the value is ``None``, in which case only the " +"key will be added. If the value contains non-ASCII characters, it can be " +"specified as a three tuple in the format ``(CHARSET, LANGUAGE, VALUE)``, " +"where ``CHARSET`` is a string naming the charset to be used to encode the " +"value, ``LANGUAGE`` can usually be set to ``None`` or the empty string (see :" +"rfc:`2231` for other possibilities), and ``VALUE`` is the string value " +"containing non-ASCII code points. If a three tuple is not passed and the " +"value contains non-ASCII characters, it is automatically encoded in :rfc:" +"`2231` format using a ``CHARSET`` of ``utf-8`` and a ``LANGUAGE`` of " +"``None``." +msgstr "" + +#: ../../library/email.compat32-message.rst:405 +msgid "Here's an example::" +msgstr "以下是個範例： ::" + +#: ../../library/email.compat32-message.rst:407 +msgid "msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')" +msgstr "" +"msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')" + +#: ../../library/email.compat32-message.rst:409 +msgid "This will add a header that looks like ::" +msgstr "" + +#: ../../library/email.compat32-message.rst:411 +msgid "Content-Disposition: attachment; filename=\"bud.gif\"" +msgstr "Content-Disposition: attachment; filename=\"bud.gif\"" + +#: ../../library/email.compat32-message.rst:413 +msgid "An example with non-ASCII characters::" +msgstr "" + +#: ../../library/email.compat32-message.rst:415 +msgid "" +"msg.add_header('Content-Disposition', 'attachment',\n" +" filename=('iso-8859-1', '', 'Fußballer.ppt'))" +msgstr "" +"msg.add_header('Content-Disposition', 'attachment',\n" +" filename=('iso-8859-1', '', 'Fußballer.ppt'))" + +#: ../../library/email.compat32-message.rst:418 +msgid "Which produces ::" +msgstr "" + +#: ../../library/email.compat32-message.rst:420 +msgid "" +"Content-Disposition: attachment; filename*=\"iso-8859-1''Fu%DFballer.ppt\"" +msgstr "" +"Content-Disposition: attachment; filename*=\"iso-8859-1''Fu%DFballer.ppt\"" + +#: ../../library/email.compat32-message.rst:425 +msgid "" +"Replace a header. Replace the first header found in the message that " +"matches *_name*, retaining header order and field name case. If no matching " +"header was found, a :exc:`KeyError` is raised." +msgstr "" + +#: ../../library/email.compat32-message.rst:432 +msgid "" +"Return the message's content type. The returned string is coerced to lower " +"case of the form :mimetype:`maintype/subtype`. If there was no :mailheader:" +"`Content-Type` header in the message the default type as given by :meth:" +"`get_default_type` will be returned. Since according to :rfc:`2045`, " +"messages always have a default type, :meth:`get_content_type` will always " +"return a value." +msgstr "" + +#: ../../library/email.compat32-message.rst:439 +msgid "" +":rfc:`2045` defines a message's default type to be :mimetype:`text/plain` " +"unless it appears inside a :mimetype:`multipart/digest` container, in which " +"case it would be :mimetype:`message/rfc822`. If the :mailheader:`Content-" +"Type` header has an invalid type specification, :rfc:`2045` mandates that " +"the default type be :mimetype:`text/plain`." +msgstr "" + +#: ../../library/email.compat32-message.rst:448 +msgid "" +"Return the message's main content type. This is the :mimetype:`maintype` " +"part of the string returned by :meth:`get_content_type`." +msgstr "" + +#: ../../library/email.compat32-message.rst:454 +msgid "" +"Return the message's sub-content type. This is the :mimetype:`subtype` part " +"of the string returned by :meth:`get_content_type`." +msgstr "" + +#: ../../library/email.compat32-message.rst:460 +msgid "" +"Return the default content type. Most messages have a default content type " +"of :mimetype:`text/plain`, except for messages that are subparts of :" +"mimetype:`multipart/digest` containers. Such subparts have a default " +"content type of :mimetype:`message/rfc822`." +msgstr "" + +#: ../../library/email.compat32-message.rst:468 +msgid "" +"Set the default content type. *ctype* should either be :mimetype:`text/" +"plain` or :mimetype:`message/rfc822`, although this is not enforced. The " +"default content type is not stored in the :mailheader:`Content-Type` header." +msgstr "" + +#: ../../library/email.compat32-message.rst:476 +msgid "" +"Return the message's :mailheader:`Content-Type` parameters, as a list. The " +"elements of the returned list are 2-tuples of key/value pairs, as split on " +"the ``'='`` sign. The left hand side of the ``'='`` is the key, while the " +"right hand side is the value. If there is no ``'='`` sign in the parameter " +"the value is the empty string, otherwise the value is as described in :meth:" +"`get_param` and is unquoted if optional *unquote* is ``True`` (the default)." +msgstr "" + +#: ../../library/email.compat32-message.rst:484 +msgid "" +"Optional *failobj* is the object to return if there is no :mailheader:" +"`Content-Type` header. Optional *header* is the header to search instead " +"of :mailheader:`Content-Type`." +msgstr "" + +#: ../../library/email.compat32-message.rst:488 +#: ../../library/email.compat32-message.rst:526 +msgid "" +"This is a legacy method. On the :class:`~email.message.EmailMessage` class " +"its functionality is replaced by the *params* property of the individual " +"header objects returned by the header access methods." +msgstr "" + +#: ../../library/email.compat32-message.rst:496 +msgid "" +"Return the value of the :mailheader:`Content-Type` header's parameter " +"*param* as a string. If the message has no :mailheader:`Content-Type` " +"header or if there is no such parameter, then *failobj* is returned " +"(defaults to ``None``)." +msgstr "" + +#: ../../library/email.compat32-message.rst:501 +msgid "" +"Optional *header* if given, specifies the message header to use instead of :" +"mailheader:`Content-Type`." +msgstr "" + +#: ../../library/email.compat32-message.rst:504 +msgid "" +"Parameter keys are always compared case insensitively. The return value can " +"either be a string, or a 3-tuple if the parameter was :rfc:`2231` encoded. " +"When it's a 3-tuple, the elements of the value are of the form ``(CHARSET, " +"LANGUAGE, VALUE)``. Note that both ``CHARSET`` and ``LANGUAGE`` can be " +"``None``, in which case you should consider ``VALUE`` to be encoded in the " +"``us-ascii`` charset. You can usually ignore ``LANGUAGE``." +msgstr "" + +#: ../../library/email.compat32-message.rst:512 +msgid "" +"If your application doesn't care whether the parameter was encoded as in :" +"rfc:`2231`, you can collapse the parameter value by calling :func:`email." +"utils.collapse_rfc2231_value`, passing in the return value from :meth:" +"`get_param`. This will return a suitably decoded Unicode string when the " +"value is a tuple, or the original string unquoted if it isn't. For example::" +msgstr "" + +#: ../../library/email.compat32-message.rst:519 +msgid "" +"rawparam = msg.get_param('foo')\n" +"param = email.utils.collapse_rfc2231_value(rawparam)" +msgstr "" +"rawparam = msg.get_param('foo')\n" +"param = email.utils.collapse_rfc2231_value(rawparam)" + +#: ../../library/email.compat32-message.rst:522 +msgid "" +"In any case, the parameter value (either the returned string, or the " +"``VALUE`` item in the 3-tuple) is always unquoted, unless *unquote* is set " +"to ``False``." +msgstr "" + +#: ../../library/email.compat32-message.rst:535 +msgid "" +"Set a parameter in the :mailheader:`Content-Type` header. If the parameter " +"already exists in the header, its value will be replaced with *value*. If " +"the :mailheader:`Content-Type` header as not yet been defined for this " +"message, it will be set to :mimetype:`text/plain` and the new parameter " +"value will be appended as per :rfc:`2045`." +msgstr "" + +#: ../../library/email.compat32-message.rst:541 +msgid "" +"Optional *header* specifies an alternative header to :mailheader:`Content-" +"Type`, and all parameters will be quoted as necessary unless optional " +"*requote* is ``False`` (the default is ``True``)." +msgstr "" + +#: ../../library/email.compat32-message.rst:545 +msgid "" +"If optional *charset* is specified, the parameter will be encoded according " +"to :rfc:`2231`. Optional *language* specifies the RFC 2231 language, " +"defaulting to the empty string. Both *charset* and *language* should be " +"strings." +msgstr "" + +#: ../../library/email.compat32-message.rst:550 +msgid "" +"If *replace* is ``False`` (the default) the header is moved to the end of " +"the list of headers. If *replace* is ``True``, the header will be updated " +"in place." +msgstr "" + +#: ../../library/email.compat32-message.rst:554 +msgid "``replace`` keyword was added." +msgstr "新增 ``replace`` 關鍵字。" + +#: ../../library/email.compat32-message.rst:559 +msgid "" +"Remove the given parameter completely from the :mailheader:`Content-Type` " +"header. The header will be re-written in place without the parameter or its " +"value. All values will be quoted as necessary unless *requote* is ``False`` " +"(the default is ``True``). Optional *header* specifies an alternative to :" +"mailheader:`Content-Type`." +msgstr "" + +#: ../../library/email.compat32-message.rst:568 +msgid "" +"Set the main type and subtype for the :mailheader:`Content-Type` header. " +"*type* must be a string in the form :mimetype:`maintype/subtype`, otherwise " +"a :exc:`ValueError` is raised." +msgstr "" + +#: ../../library/email.compat32-message.rst:572 +msgid "" +"This method replaces the :mailheader:`Content-Type` header, keeping all the " +"parameters in place. If *requote* is ``False``, this leaves the existing " +"header's quoting as is, otherwise the parameters will be quoted (the " +"default)." +msgstr "" + +#: ../../library/email.compat32-message.rst:577 +msgid "" +"An alternative header can be specified in the *header* argument. When the :" +"mailheader:`Content-Type` header is set a :mailheader:`MIME-Version` header " +"is also added." +msgstr "" + +#: ../../library/email.compat32-message.rst:581 +msgid "" +"This is a legacy method. On the :class:`~email.message.EmailMessage` class " +"its functionality is replaced by the ``make_`` and ``add_`` methods." +msgstr "" + +#: ../../library/email.compat32-message.rst:588 +msgid "" +"Return the value of the ``filename`` parameter of the :mailheader:`Content-" +"Disposition` header of the message. If the header does not have a " +"``filename`` parameter, this method falls back to looking for the ``name`` " +"parameter on the :mailheader:`Content-Type` header. If neither is found, or " +"the header is missing, then *failobj* is returned. The returned string will " +"always be unquoted as per :func:`email.utils.unquote`." +msgstr "" + +#: ../../library/email.compat32-message.rst:599 +msgid "" +"Return the value of the ``boundary`` parameter of the :mailheader:`Content-" +"Type` header of the message, or *failobj* if either the header is missing, " +"or has no ``boundary`` parameter. The returned string will always be " +"unquoted as per :func:`email.utils.unquote`." +msgstr "" + +#: ../../library/email.compat32-message.rst:607 +msgid "" +"Set the ``boundary`` parameter of the :mailheader:`Content-Type` header to " +"*boundary*. :meth:`set_boundary` will always quote *boundary* if " +"necessary. A :exc:`~email.errors.HeaderParseError` is raised if the message " +"object has no :mailheader:`Content-Type` header." +msgstr "" + +#: ../../library/email.compat32-message.rst:612 +msgid "" +"Note that using this method is subtly different than deleting the old :" +"mailheader:`Content-Type` header and adding a new one with the new boundary " +"via :meth:`add_header`, because :meth:`set_boundary` preserves the order of " +"the :mailheader:`Content-Type` header in the list of headers. However, it " +"does *not* preserve any continuation lines which may have been present in " +"the original :mailheader:`Content-Type` header." +msgstr "" + +#: ../../library/email.compat32-message.rst:622 +msgid "" +"Return the ``charset`` parameter of the :mailheader:`Content-Type` header, " +"coerced to lower case. If there is no :mailheader:`Content-Type` header, or " +"if that header has no ``charset`` parameter, *failobj* is returned." +msgstr "" + +#: ../../library/email.compat32-message.rst:626 +msgid "" +"Note that this method differs from :meth:`get_charset` which returns the :" +"class:`~email.charset.Charset` instance for the default encoding of the " +"message body." +msgstr "" + +#: ../../library/email.compat32-message.rst:632 +msgid "" +"Return a list containing the character set names in the message. If the " +"message is a :mimetype:`multipart`, then the list will contain one element " +"for each subpart in the payload, otherwise, it will be a list of length 1." +msgstr "" + +#: ../../library/email.compat32-message.rst:636 +msgid "" +"Each item in the list will be a string which is the value of the ``charset`` " +"parameter in the :mailheader:`Content-Type` header for the represented " +"subpart. However, if the subpart has no :mailheader:`Content-Type` header, " +"no ``charset`` parameter, or is not of the :mimetype:`text` main MIME type, " +"then that item in the returned list will be *failobj*." +msgstr "" + +#: ../../library/email.compat32-message.rst:646 +msgid "" +"Return the lowercased value (without parameters) of the message's :" +"mailheader:`Content-Disposition` header if it has one, or ``None``. The " +"possible values for this method are *inline*, *attachment* or ``None`` if " +"the message follows :rfc:`2183`." +msgstr "" + +#: ../../library/email.compat32-message.rst:655 +msgid "" +"The :meth:`walk` method is an all-purpose generator which can be used to " +"iterate over all the parts and subparts of a message object tree, in depth-" +"first traversal order. You will typically use :meth:`walk` as the iterator " +"in a ``for`` loop; each iteration returns the next subpart." +msgstr "" + +#: ../../library/email.compat32-message.rst:660 +msgid "" +"Here's an example that prints the MIME type of every part of a multipart " +"message structure:" +msgstr "" + +#: ../../library/email.compat32-message.rst:674 +msgid "" +">>> for part in msg.walk():\n" +"... print(part.get_content_type())\n" +"multipart/report\n" +"text/plain\n" +"message/delivery-status\n" +"text/plain\n" +"text/plain\n" +"message/rfc822\n" +"text/plain" +msgstr "" +">>> for part in msg.walk():\n" +"... print(part.get_content_type())\n" +"multipart/report\n" +"text/plain\n" +"message/delivery-status\n" +"text/plain\n" +"text/plain\n" +"message/rfc822\n" +"text/plain" + +#: ../../library/email.compat32-message.rst:686 +msgid "" +"``walk`` iterates over the subparts of any part where :meth:`is_multipart` " +"returns ``True``, even though ``msg.get_content_maintype() == 'multipart'`` " +"may return ``False``. We can see this in our example by making use of the " +"``_structure`` debug helper function:" +msgstr "" + +#: ../../library/email.compat32-message.rst:692 +msgid "" +">>> for part in msg.walk():\n" +"... print(part.get_content_maintype() == 'multipart',\n" +"... part.is_multipart())\n" +"True True\n" +"False False\n" +"False True\n" +"False False\n" +"False False\n" +"False True\n" +"False False\n" +">>> _structure(msg)\n" +"multipart/report\n" +" text/plain\n" +" message/delivery-status\n" +" text/plain\n" +" text/plain\n" +" message/rfc822\n" +" text/plain" +msgstr "" +">>> for part in msg.walk():\n" +"... print(part.get_content_maintype() == 'multipart',\n" +"... part.is_multipart())\n" +"True True\n" +"False False\n" +"False True\n" +"False False\n" +"False False\n" +"False True\n" +"False False\n" +">>> _structure(msg)\n" +"multipart/report\n" +" text/plain\n" +" message/delivery-status\n" +" text/plain\n" +" text/plain\n" +" message/rfc822\n" +" text/plain" + +#: ../../library/email.compat32-message.rst:713 +msgid "" +"Here the ``message`` parts are not ``multiparts``, but they do contain " +"subparts. ``is_multipart()`` returns ``True`` and ``walk`` descends into the " +"subparts." +msgstr "" + +#: ../../library/email.compat32-message.rst:718 +msgid "" +":class:`Message` objects can also optionally contain two instance " +"attributes, which can be used when generating the plain text of a MIME " +"message." +msgstr "" + +#: ../../library/email.compat32-message.rst:724 +msgid "" +"The format of a MIME document allows for some text between the blank line " +"following the headers, and the first multipart boundary string. Normally, " +"this text is never visible in a MIME-aware mail reader because it falls " +"outside the standard MIME armor. However, when viewing the raw text of the " +"message, or when viewing the message in a non-MIME aware reader, this text " +"can become visible." +msgstr "" + +#: ../../library/email.compat32-message.rst:731 +msgid "" +"The *preamble* attribute contains this leading extra-armor text for MIME " +"documents. When the :class:`~email.parser.Parser` discovers some text after " +"the headers but before the first boundary string, it assigns this text to " +"the message's *preamble* attribute. When the :class:`~email.generator." +"Generator` is writing out the plain text representation of a MIME message, " +"and it finds the message has a *preamble* attribute, it will write this text " +"in the area between the headers and the first boundary. See :mod:`email." +"parser` and :mod:`email.generator` for details." +msgstr "" + +#: ../../library/email.compat32-message.rst:741 +msgid "" +"Note that if the message object has no preamble, the *preamble* attribute " +"will be ``None``." +msgstr "" + +#: ../../library/email.compat32-message.rst:747 +msgid "" +"The *epilogue* attribute acts the same way as the *preamble* attribute, " +"except that it contains text that appears between the last boundary and the " +"end of the message." +msgstr "" + +#: ../../library/email.compat32-message.rst:751 +msgid "" +"You do not need to set the epilogue to the empty string in order for the :" +"class:`~email.generator.Generator` to print a newline at the end of the file." +msgstr "" + +#: ../../library/email.compat32-message.rst:758 +msgid "" +"The *defects* attribute contains a list of all the problems found when " +"parsing this message. See :mod:`email.errors` for a detailed description of " +"the possible parsing defects." +msgstr "" diff --git a/library/email.contentmanager.po b/library/email.contentmanager.po index 694d14c518..17a48326b2 100644 --- a/library/email.contentmanager.po +++ b/library/email.contentmanager.po @@ -1,290 +1,290 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-01-19 00:15+0000\n" -"PO-Revision-Date: 2018-05-23 14:43+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/email.contentmanager.rst:2 -msgid ":mod:`!email.contentmanager`: Managing MIME Content" -msgstr ":mod:`!email.contentmanager`：管理 MIME 內容" - -#: ../../library/email.contentmanager.rst:10 -msgid "**Source code:** :source:`Lib/email/contentmanager.py`" -msgstr "**原始碼：**\\ :source:`Lib/email/contentmanager.py`" - -#: ../../library/email.contentmanager.rst:14 -msgid "[1]_" -msgstr "[1]_" - -#: ../../library/email.contentmanager.rst:19 -msgid "" -"Base class for content managers. Provides the standard registry mechanisms " -"to register converters between MIME content and other representations, as " -"well as the ``get_content`` and ``set_content`` dispatch methods." -msgstr "" - -#: ../../library/email.contentmanager.rst:26 -msgid "" -"Look up a handler function based on the ``mimetype`` of *msg* (see next " -"paragraph), call it, passing through all arguments, and return the result of " -"the call. The expectation is that the handler will extract the payload from " -"*msg* and return an object that encodes information about the extracted data." -msgstr "" - -#: ../../library/email.contentmanager.rst:32 -msgid "" -"To find the handler, look for the following keys in the registry, stopping " -"with the first one found:" -msgstr "" - -#: ../../library/email.contentmanager.rst:35 -msgid "the string representing the full MIME type (``maintype/subtype``)" -msgstr "" - -#: ../../library/email.contentmanager.rst:36 -msgid "the string representing the ``maintype``" -msgstr "" - -#: ../../library/email.contentmanager.rst:37 -msgid "the empty string" -msgstr "" - -#: ../../library/email.contentmanager.rst:39 -msgid "" -"If none of these keys produce a handler, raise a :exc:`KeyError` for the " -"full MIME type." -msgstr "" - -#: ../../library/email.contentmanager.rst:45 -msgid "" -"If the ``maintype`` is ``multipart``, raise a :exc:`TypeError`; otherwise " -"look up a handler function based on the type of *obj* (see next paragraph), " -"call :meth:`~email.message.EmailMessage.clear_content` on the *msg*, and " -"call the handler function, passing through all arguments. The expectation " -"is that the handler will transform and store *obj* into *msg*, possibly " -"making other changes to *msg* as well, such as adding various MIME headers " -"to encode information needed to interpret the stored data." -msgstr "" - -#: ../../library/email.contentmanager.rst:54 -msgid "" -"To find the handler, obtain the type of *obj* (``typ = type(obj)``), and " -"look for the following keys in the registry, stopping with the first one " -"found:" -msgstr "" - -#: ../../library/email.contentmanager.rst:58 -msgid "the type itself (``typ``)" -msgstr "" - -#: ../../library/email.contentmanager.rst:59 -msgid "" -"the type's fully qualified name (``typ.__module__ + '.' + typ." -"__qualname__``)." -msgstr "" - -#: ../../library/email.contentmanager.rst:61 -msgid "the type's :attr:`qualname ` (``typ.__qualname__``)" -msgstr "" - -#: ../../library/email.contentmanager.rst:62 -msgid "the type's :attr:`name ` (``typ.__name__``)." -msgstr "" - -#: ../../library/email.contentmanager.rst:64 -msgid "" -"If none of the above match, repeat all of the checks above for each of the " -"types in the :term:`MRO` (:attr:`typ.__mro__ `). Finally, if " -"no other key yields a handler, check for a handler for the key ``None``. If " -"there is no handler for ``None``, raise a :exc:`KeyError` for the fully " -"qualified name of the type." -msgstr "" - -#: ../../library/email.contentmanager.rst:71 -msgid "" -"Also add a :mailheader:`MIME-Version` header if one is not present (see " -"also :class:`.MIMEPart`)." -msgstr "" - -#: ../../library/email.contentmanager.rst:77 -msgid "" -"Record the function *handler* as the handler for *key*. For the possible " -"values of *key*, see :meth:`get_content`." -msgstr "" - -#: ../../library/email.contentmanager.rst:83 -msgid "" -"Record *handler* as the function to call when an object of a type matching " -"*typekey* is passed to :meth:`set_content`. For the possible values of " -"*typekey*, see :meth:`set_content`." -msgstr "" - -#: ../../library/email.contentmanager.rst:89 -msgid "Content Manager Instances" -msgstr "" - -#: ../../library/email.contentmanager.rst:91 -msgid "" -"Currently the email package provides only one concrete content manager, :" -"data:`raw_data_manager`, although more may be added in the future. :data:" -"`raw_data_manager` is the :attr:`~email.policy.EmailPolicy.content_manager` " -"provided by :attr:`~email.policy.EmailPolicy` and its derivatives." -msgstr "" - -#: ../../library/email.contentmanager.rst:100 -msgid "" -"This content manager provides only a minimum interface beyond that provided " -"by :class:`~email.message.Message` itself: it deals only with text, raw " -"byte strings, and :class:`~email.message.Message` objects. Nevertheless, it " -"provides significant advantages compared to the base API: ``get_content`` on " -"a text part will return a unicode string without the application needing to " -"manually decode it, ``set_content`` provides a rich set of options for " -"controlling the headers added to a part and controlling the content transfer " -"encoding, and it enables the use of the various ``add_`` methods, thereby " -"simplifying the creation of multipart messages." -msgstr "" - -#: ../../library/email.contentmanager.rst:112 -msgid "" -"Return the payload of the part as either a string (for ``text`` parts), an :" -"class:`~email.message.EmailMessage` object (for ``message/rfc822`` parts), " -"or a ``bytes`` object (for all other non-multipart types). Raise a :exc:" -"`KeyError` if called on a ``multipart``. If the part is a ``text`` part and " -"*errors* is specified, use it as the error handler when decoding the payload " -"to unicode. The default error handler is ``replace``." -msgstr "" - -#: ../../library/email.contentmanager.rst:131 -msgid "Add headers and payload to *msg*:" -msgstr "" - -#: ../../library/email.contentmanager.rst:133 -msgid "" -"Add a :mailheader:`Content-Type` header with a ``maintype/subtype`` value." -msgstr "" - -#: ../../library/email.contentmanager.rst:136 -msgid "" -"For ``str``, set the MIME ``maintype`` to ``text``, and set the subtype to " -"*subtype* if it is specified, or ``plain`` if it is not." -msgstr "" - -#: ../../library/email.contentmanager.rst:138 -msgid "" -"For ``bytes``, use the specified *maintype* and *subtype*, or raise a :exc:" -"`TypeError` if they are not specified." -msgstr "" - -#: ../../library/email.contentmanager.rst:140 -msgid "" -"For :class:`~email.message.EmailMessage` objects, set the maintype to " -"``message``, and set the subtype to *subtype* if it is specified or " -"``rfc822`` if it is not. If *subtype* is ``partial``, raise an error " -"(``bytes`` objects must be used to construct ``message/partial`` parts)." -msgstr "" - -#: ../../library/email.contentmanager.rst:146 -msgid "" -"If *charset* is provided (which is valid only for ``str``), encode the " -"string to bytes using the specified character set. The default is " -"``utf-8``. If the specified *charset* is a known alias for a standard MIME " -"charset name, use the standard charset instead." -msgstr "" - -#: ../../library/email.contentmanager.rst:151 -msgid "" -"If *cte* is set, encode the payload using the specified content transfer " -"encoding, and set the :mailheader:`Content-Transfer-Encoding` header to that " -"value. Possible values for *cte* are ``quoted-printable``, ``base64``, " -"``7bit``, ``8bit``, and ``binary``. If the input cannot be encoded in the " -"specified encoding (for example, specifying a *cte* of ``7bit`` for an input " -"that contains non-ASCII values), raise a :exc:`ValueError`." -msgstr "" - -#: ../../library/email.contentmanager.rst:159 -msgid "" -"For ``str`` objects, if *cte* is not set use heuristics to determine the " -"most compact encoding. Prior to encoding, :meth:`str.splitlines` is used to " -"normalize all line boundaries, ensuring that each line of the payload is " -"terminated by the current policy's :data:`~email.policy.Policy.linesep` " -"property (even if the original string did not end with one)." -msgstr "" - -#: ../../library/email.contentmanager.rst:165 -msgid "" -"For ``bytes`` objects, *cte* is taken to be base64 if not set, and the " -"aforementioned newline translation is not performed." -msgstr "" - -#: ../../library/email.contentmanager.rst:167 -msgid "" -"For :class:`~email.message.EmailMessage`, per :rfc:`2046`, raise an error if " -"a *cte* of ``quoted-printable`` or ``base64`` is requested for *subtype* " -"``rfc822``, and for any *cte* other than ``7bit`` for *subtype* ``external-" -"body``. For ``message/rfc822``, use ``8bit`` if *cte* is not specified. " -"For all other values of *subtype*, use ``7bit``." -msgstr "" - -#: ../../library/email.contentmanager.rst:174 -msgid "" -"A *cte* of ``binary`` does not actually work correctly yet. The " -"``EmailMessage`` object as modified by ``set_content`` is correct, but :" -"class:`~email.generator.BytesGenerator` does not serialize it correctly." -msgstr "" - -#: ../../library/email.contentmanager.rst:179 -msgid "" -"If *disposition* is set, use it as the value of the :mailheader:`Content-" -"Disposition` header. If not specified, and *filename* is specified, add the " -"header with the value ``attachment``. If *disposition* is not specified and " -"*filename* is also not specified, do not add the header. The only valid " -"values for *disposition* are ``attachment`` and ``inline``." -msgstr "" - -#: ../../library/email.contentmanager.rst:186 -msgid "" -"If *filename* is specified, use it as the value of the ``filename`` " -"parameter of the :mailheader:`Content-Disposition` header." -msgstr "" - -#: ../../library/email.contentmanager.rst:189 -msgid "" -"If *cid* is specified, add a :mailheader:`Content-ID` header with *cid* as " -"its value." -msgstr "" - -#: ../../library/email.contentmanager.rst:192 -msgid "" -"If *params* is specified, iterate its ``items`` method and use the resulting " -"``(key, value)`` pairs to set additional parameters on the :mailheader:" -"`Content-Type` header." -msgstr "" - -#: ../../library/email.contentmanager.rst:196 -msgid "" -"If *headers* is specified and is a list of strings of the form ``headername: " -"headervalue`` or a list of ``header`` objects (distinguished from strings by " -"having a ``name`` attribute), add the headers to *msg*." -msgstr "" - -#: ../../library/email.contentmanager.rst:203 -msgid "Footnotes" -msgstr "註解" - -#: ../../library/email.contentmanager.rst:204 -msgid "" -"Originally added in 3.4 as a :term:`provisional module `" -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-01-19 00:15+0000\n" +"PO-Revision-Date: 2018-05-23 14:43+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/email.contentmanager.rst:2 +msgid ":mod:`!email.contentmanager`: Managing MIME Content" +msgstr ":mod:`!email.contentmanager`：管理 MIME 內容" + +#: ../../library/email.contentmanager.rst:10 +msgid "**Source code:** :source:`Lib/email/contentmanager.py`" +msgstr "**原始碼：**\\ :source:`Lib/email/contentmanager.py`" + +#: ../../library/email.contentmanager.rst:14 +msgid "[1]_" +msgstr "[1]_" + +#: ../../library/email.contentmanager.rst:19 +msgid "" +"Base class for content managers. Provides the standard registry mechanisms " +"to register converters between MIME content and other representations, as " +"well as the ``get_content`` and ``set_content`` dispatch methods." +msgstr "" + +#: ../../library/email.contentmanager.rst:26 +msgid "" +"Look up a handler function based on the ``mimetype`` of *msg* (see next " +"paragraph), call it, passing through all arguments, and return the result of " +"the call. The expectation is that the handler will extract the payload from " +"*msg* and return an object that encodes information about the extracted data." +msgstr "" + +#: ../../library/email.contentmanager.rst:32 +msgid "" +"To find the handler, look for the following keys in the registry, stopping " +"with the first one found:" +msgstr "" + +#: ../../library/email.contentmanager.rst:35 +msgid "the string representing the full MIME type (``maintype/subtype``)" +msgstr "" + +#: ../../library/email.contentmanager.rst:36 +msgid "the string representing the ``maintype``" +msgstr "" + +#: ../../library/email.contentmanager.rst:37 +msgid "the empty string" +msgstr "" + +#: ../../library/email.contentmanager.rst:39 +msgid "" +"If none of these keys produce a handler, raise a :exc:`KeyError` for the " +"full MIME type." +msgstr "" + +#: ../../library/email.contentmanager.rst:45 +msgid "" +"If the ``maintype`` is ``multipart``, raise a :exc:`TypeError`; otherwise " +"look up a handler function based on the type of *obj* (see next paragraph), " +"call :meth:`~email.message.EmailMessage.clear_content` on the *msg*, and " +"call the handler function, passing through all arguments. The expectation " +"is that the handler will transform and store *obj* into *msg*, possibly " +"making other changes to *msg* as well, such as adding various MIME headers " +"to encode information needed to interpret the stored data." +msgstr "" + +#: ../../library/email.contentmanager.rst:54 +msgid "" +"To find the handler, obtain the type of *obj* (``typ = type(obj)``), and " +"look for the following keys in the registry, stopping with the first one " +"found:" +msgstr "" + +#: ../../library/email.contentmanager.rst:58 +msgid "the type itself (``typ``)" +msgstr "" + +#: ../../library/email.contentmanager.rst:59 +msgid "" +"the type's fully qualified name (``typ.__module__ + '.' + typ." +"__qualname__``)." +msgstr "" + +#: ../../library/email.contentmanager.rst:61 +msgid "the type's :attr:`qualname ` (``typ.__qualname__``)" +msgstr "" + +#: ../../library/email.contentmanager.rst:62 +msgid "the type's :attr:`name ` (``typ.__name__``)." +msgstr "" + +#: ../../library/email.contentmanager.rst:64 +msgid "" +"If none of the above match, repeat all of the checks above for each of the " +"types in the :term:`MRO` (:attr:`typ.__mro__ `). Finally, if " +"no other key yields a handler, check for a handler for the key ``None``. If " +"there is no handler for ``None``, raise a :exc:`KeyError` for the fully " +"qualified name of the type." +msgstr "" + +#: ../../library/email.contentmanager.rst:71 +msgid "" +"Also add a :mailheader:`MIME-Version` header if one is not present (see " +"also :class:`.MIMEPart`)." +msgstr "" + +#: ../../library/email.contentmanager.rst:77 +msgid "" +"Record the function *handler* as the handler for *key*. For the possible " +"values of *key*, see :meth:`get_content`." +msgstr "" + +#: ../../library/email.contentmanager.rst:83 +msgid "" +"Record *handler* as the function to call when an object of a type matching " +"*typekey* is passed to :meth:`set_content`. For the possible values of " +"*typekey*, see :meth:`set_content`." +msgstr "" + +#: ../../library/email.contentmanager.rst:89 +msgid "Content Manager Instances" +msgstr "" + +#: ../../library/email.contentmanager.rst:91 +msgid "" +"Currently the email package provides only one concrete content manager, :" +"data:`raw_data_manager`, although more may be added in the future. :data:" +"`raw_data_manager` is the :attr:`~email.policy.EmailPolicy.content_manager` " +"provided by :attr:`~email.policy.EmailPolicy` and its derivatives." +msgstr "" + +#: ../../library/email.contentmanager.rst:100 +msgid "" +"This content manager provides only a minimum interface beyond that provided " +"by :class:`~email.message.Message` itself: it deals only with text, raw " +"byte strings, and :class:`~email.message.Message` objects. Nevertheless, it " +"provides significant advantages compared to the base API: ``get_content`` on " +"a text part will return a unicode string without the application needing to " +"manually decode it, ``set_content`` provides a rich set of options for " +"controlling the headers added to a part and controlling the content transfer " +"encoding, and it enables the use of the various ``add_`` methods, thereby " +"simplifying the creation of multipart messages." +msgstr "" + +#: ../../library/email.contentmanager.rst:112 +msgid "" +"Return the payload of the part as either a string (for ``text`` parts), an :" +"class:`~email.message.EmailMessage` object (for ``message/rfc822`` parts), " +"or a ``bytes`` object (for all other non-multipart types). Raise a :exc:" +"`KeyError` if called on a ``multipart``. If the part is a ``text`` part and " +"*errors* is specified, use it as the error handler when decoding the payload " +"to unicode. The default error handler is ``replace``." +msgstr "" + +#: ../../library/email.contentmanager.rst:131 +msgid "Add headers and payload to *msg*:" +msgstr "" + +#: ../../library/email.contentmanager.rst:133 +msgid "" +"Add a :mailheader:`Content-Type` header with a ``maintype/subtype`` value." +msgstr "" + +#: ../../library/email.contentmanager.rst:136 +msgid "" +"For ``str``, set the MIME ``maintype`` to ``text``, and set the subtype to " +"*subtype* if it is specified, or ``plain`` if it is not." +msgstr "" + +#: ../../library/email.contentmanager.rst:138 +msgid "" +"For ``bytes``, use the specified *maintype* and *subtype*, or raise a :exc:" +"`TypeError` if they are not specified." +msgstr "" + +#: ../../library/email.contentmanager.rst:140 +msgid "" +"For :class:`~email.message.EmailMessage` objects, set the maintype to " +"``message``, and set the subtype to *subtype* if it is specified or " +"``rfc822`` if it is not. If *subtype* is ``partial``, raise an error " +"(``bytes`` objects must be used to construct ``message/partial`` parts)." +msgstr "" + +#: ../../library/email.contentmanager.rst:146 +msgid "" +"If *charset* is provided (which is valid only for ``str``), encode the " +"string to bytes using the specified character set. The default is " +"``utf-8``. If the specified *charset* is a known alias for a standard MIME " +"charset name, use the standard charset instead." +msgstr "" + +#: ../../library/email.contentmanager.rst:151 +msgid "" +"If *cte* is set, encode the payload using the specified content transfer " +"encoding, and set the :mailheader:`Content-Transfer-Encoding` header to that " +"value. Possible values for *cte* are ``quoted-printable``, ``base64``, " +"``7bit``, ``8bit``, and ``binary``. If the input cannot be encoded in the " +"specified encoding (for example, specifying a *cte* of ``7bit`` for an input " +"that contains non-ASCII values), raise a :exc:`ValueError`." +msgstr "" + +#: ../../library/email.contentmanager.rst:159 +msgid "" +"For ``str`` objects, if *cte* is not set use heuristics to determine the " +"most compact encoding. Prior to encoding, :meth:`str.splitlines` is used to " +"normalize all line boundaries, ensuring that each line of the payload is " +"terminated by the current policy's :data:`~email.policy.Policy.linesep` " +"property (even if the original string did not end with one)." +msgstr "" + +#: ../../library/email.contentmanager.rst:165 +msgid "" +"For ``bytes`` objects, *cte* is taken to be base64 if not set, and the " +"aforementioned newline translation is not performed." +msgstr "" + +#: ../../library/email.contentmanager.rst:167 +msgid "" +"For :class:`~email.message.EmailMessage`, per :rfc:`2046`, raise an error if " +"a *cte* of ``quoted-printable`` or ``base64`` is requested for *subtype* " +"``rfc822``, and for any *cte* other than ``7bit`` for *subtype* ``external-" +"body``. For ``message/rfc822``, use ``8bit`` if *cte* is not specified. " +"For all other values of *subtype*, use ``7bit``." +msgstr "" + +#: ../../library/email.contentmanager.rst:174 +msgid "" +"A *cte* of ``binary`` does not actually work correctly yet. The " +"``EmailMessage`` object as modified by ``set_content`` is correct, but :" +"class:`~email.generator.BytesGenerator` does not serialize it correctly." +msgstr "" + +#: ../../library/email.contentmanager.rst:179 +msgid "" +"If *disposition* is set, use it as the value of the :mailheader:`Content-" +"Disposition` header. If not specified, and *filename* is specified, add the " +"header with the value ``attachment``. If *disposition* is not specified and " +"*filename* is also not specified, do not add the header. The only valid " +"values for *disposition* are ``attachment`` and ``inline``." +msgstr "" + +#: ../../library/email.contentmanager.rst:186 +msgid "" +"If *filename* is specified, use it as the value of the ``filename`` " +"parameter of the :mailheader:`Content-Disposition` header." +msgstr "" + +#: ../../library/email.contentmanager.rst:189 +msgid "" +"If *cid* is specified, add a :mailheader:`Content-ID` header with *cid* as " +"its value." +msgstr "" + +#: ../../library/email.contentmanager.rst:192 +msgid "" +"If *params* is specified, iterate its ``items`` method and use the resulting " +"``(key, value)`` pairs to set additional parameters on the :mailheader:" +"`Content-Type` header." +msgstr "" + +#: ../../library/email.contentmanager.rst:196 +msgid "" +"If *headers* is specified and is a list of strings of the form ``headername: " +"headervalue`` or a list of ``header`` objects (distinguished from strings by " +"having a ``name`` attribute), add the headers to *msg*." +msgstr "" + +#: ../../library/email.contentmanager.rst:203 +msgid "Footnotes" +msgstr "註解" + +#: ../../library/email.contentmanager.rst:204 +msgid "" +"Originally added in 3.4 as a :term:`provisional module `" +msgstr "" diff --git a/library/email.encoders.po b/library/email.encoders.po index 6aa55e0710..20902ea0eb 100644 --- a/library/email.encoders.po +++ b/library/email.encoders.po @@ -1,146 +1,146 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Matt Wang , 2024 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2023-07-29 10:36+0000\n" -"PO-Revision-Date: 2024-05-03 03:44+0000\n" -"Last-Translator: Matt Wang \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/email.encoders.rst:2 -msgid ":mod:`!email.encoders`: Encoders" -msgstr ":mod:`!email.encoders`：編碼器" - -#: ../../library/email.encoders.rst:7 -msgid "**Source code:** :source:`Lib/email/encoders.py`" -msgstr "**原始碼：**\\ :source:`Lib/email/encoders.py`" - -#: ../../library/email.encoders.rst:11 -msgid "" -"This module is part of the legacy (``Compat32``) email API. In the new API " -"the functionality is provided by the *cte* parameter of the :meth:`~email." -"message.EmailMessage.set_content` method." -msgstr "" -"此模組是舊版 (``Compat32``) 電子郵件 API 的一部分。在新 API 中，此功能由 :" -"meth:`~email.message.EmailMessage.set_content` 方法的 *cte* 參數提供。" - -#: ../../library/email.encoders.rst:15 -msgid "" -"This module is deprecated in Python 3. The functions provided here should " -"not be called explicitly since the :class:`~email.mime.text.MIMEText` class " -"sets the content type and CTE header using the *_subtype* and *_charset* " -"values passed during the instantiation of that class." -msgstr "" -"此模組在 Python 3 中已棄用。不應明確呼叫此處提供的函式，因為 :class:`~email." -"mime.text.MIMEText` 類別使用在該類別的實例化過程中傳遞的 *_subtype* 和 " -"*_charset* 值來設定內容類型 (content type) 和 CTE 標頭。" - -#: ../../library/email.encoders.rst:20 -msgid "" -"The remaining text in this section is the original documentation of the " -"module." -msgstr "本節中的其餘文字是該模組的原始文件。" - -#: ../../library/email.encoders.rst:22 -msgid "" -"When creating :class:`~email.message.Message` objects from scratch, you " -"often need to encode the payloads for transport through compliant mail " -"servers. This is especially true for :mimetype:`image/\\*` and :mimetype:" -"`text/\\*` type messages containing binary data." -msgstr "" -"從零開始建立 :class:`~email.message.Message` 物件時，你通常需要對負載 " -"(payload) 進行編碼，以便透過相容的郵件伺服器進行傳輸。對於包含二進位資料的 :" -"mimetype:`image/\\*` 和 :mimetype:`text/\\*` 類型的訊息尤其如此。" - -#: ../../library/email.encoders.rst:27 -msgid "" -"The :mod:`email` package provides some convenient encoders in its :mod:" -"`~email.encoders` module. These encoders are actually used by the :class:" -"`~email.mime.audio.MIMEAudio` and :class:`~email.mime.image.MIMEImage` class " -"constructors to provide default encodings. All encoder functions take " -"exactly one argument, the message object to encode. They usually extract " -"the payload, encode it, and reset the payload to this newly encoded value. " -"They should also set the :mailheader:`Content-Transfer-Encoding` header as " -"appropriate." -msgstr "" -":mod:`email` 套件在其 :mod:`~email.encoders` 模組中提供了一些方便的編碼器。這" -"些編碼器實際上由 :class:`~email.mime.audio.MIMEAudio` 和 :class:`~email.mime." -"image.MIMEImage` 類別建構函式使用來提供預設編碼。所有編碼器函式都只接受一個引" -"數，也就是要編碼的訊息物件。他們通常會提取負載、對其進行編碼，然後將負載重設" -"為新編碼的值。他們也應適當地設定 :mailheader:`Content-Transfer-Encoding` 標" -"頭。" - -#: ../../library/email.encoders.rst:35 -msgid "" -"Note that these functions are not meaningful for a multipart message. They " -"must be applied to individual subparts instead, and will raise a :exc:" -"`TypeError` if passed a message whose type is multipart." -msgstr "" -"請注意，這些函式對於多部分訊息 (multipart message) 沒有意義。它們必須應用於各" -"個子部分，如果傳遞類型為多部分訊息，則會引發 :exc:`TypeError`。" - -#: ../../library/email.encoders.rst:39 -msgid "Here are the encoding functions provided:" -msgstr "以下是提供的編碼函式：" - -#: ../../library/email.encoders.rst:44 -msgid "" -"Encodes the payload into quoted-printable form and sets the :mailheader:" -"`Content-Transfer-Encoding` header to ``quoted-printable`` [#]_. This is a " -"good encoding to use when most of your payload is normal printable data, but " -"contains a few unprintable characters." -msgstr "" -"將負載編碼為可列印字元 (quoted-printable) 形式，並將 :mailheader:`Content-" -"Transfer-Encoding` 標頭設定為 ``quoted-printable`` [#]_。當大部分負載是正常的" -"可列印資料，但包含一些不可列印的字元時，這是一種很好的編碼。" - -#: ../../library/email.encoders.rst:52 -msgid "" -"Encodes the payload into base64 form and sets the :mailheader:`Content-" -"Transfer-Encoding` header to ``base64``. This is a good encoding to use " -"when most of your payload is unprintable data since it is a more compact " -"form than quoted-printable. The drawback of base64 encoding is that it " -"renders the text non-human readable." -msgstr "" -"將負載編碼為 base64 形式，並將 :mailheader:`Content-Transfer-Encoding` 標頭設" -"定為 ``base64``。當大部分負載是不可列印資料時，這是一種很好的編碼，因為它是比" -"可列印字元更緊湊的形式。Base64 編碼的缺點是它使文字無法讓人類可讀。" - -#: ../../library/email.encoders.rst:61 -msgid "" -"This doesn't actually modify the message's payload, but it does set the :" -"mailheader:`Content-Transfer-Encoding` header to either ``7bit`` or ``8bit`` " -"as appropriate, based on the payload data." -msgstr "" -"這實際上並沒有修改訊息的負載，但它確實根據負載資料將 :mailheader:`Content-" -"Transfer-Encoding` 標頭設定為適當的 ``7bit`` 或 ``8bit``。" - -#: ../../library/email.encoders.rst:68 -msgid "" -"This does nothing; it doesn't even set the :mailheader:`Content-Transfer-" -"Encoding` header." -msgstr "" -"這沒有任何作用；它甚至沒有設定 :mailheader:`Content-Transfer-Encoding` 標頭。" - -#: ../../library/email.encoders.rst:72 -msgid "Footnotes" -msgstr "註腳" - -#: ../../library/email.encoders.rst:73 -msgid "" -"Note that encoding with :meth:`encode_quopri` also encodes all tabs and " -"space characters in the data." -msgstr "" -"請注意，使用 :meth:`encode_quopri` 進行編碼也會對資料中的所有定位字元 (tab) " -"和空格字元進行編碼。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Matt Wang , 2024 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-07-29 10:36+0000\n" +"PO-Revision-Date: 2024-05-03 03:44+0000\n" +"Last-Translator: Matt Wang \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/email.encoders.rst:2 +msgid ":mod:`!email.encoders`: Encoders" +msgstr ":mod:`!email.encoders`：編碼器" + +#: ../../library/email.encoders.rst:7 +msgid "**Source code:** :source:`Lib/email/encoders.py`" +msgstr "**原始碼：**\\ :source:`Lib/email/encoders.py`" + +#: ../../library/email.encoders.rst:11 +msgid "" +"This module is part of the legacy (``Compat32``) email API. In the new API " +"the functionality is provided by the *cte* parameter of the :meth:`~email." +"message.EmailMessage.set_content` method." +msgstr "" +"此模組是舊版 (``Compat32``) 電子郵件 API 的一部分。在新 API 中，此功能由 :" +"meth:`~email.message.EmailMessage.set_content` 方法的 *cte* 參數提供。" + +#: ../../library/email.encoders.rst:15 +msgid "" +"This module is deprecated in Python 3. The functions provided here should " +"not be called explicitly since the :class:`~email.mime.text.MIMEText` class " +"sets the content type and CTE header using the *_subtype* and *_charset* " +"values passed during the instantiation of that class." +msgstr "" +"此模組在 Python 3 中已棄用。不應明確呼叫此處提供的函式，因為 :class:`~email." +"mime.text.MIMEText` 類別使用在該類別的實例化過程中傳遞的 *_subtype* 和 " +"*_charset* 值來設定內容類型 (content type) 和 CTE 標頭。" + +#: ../../library/email.encoders.rst:20 +msgid "" +"The remaining text in this section is the original documentation of the " +"module." +msgstr "本節中的其餘文字是該模組的原始文件。" + +#: ../../library/email.encoders.rst:22 +msgid "" +"When creating :class:`~email.message.Message` objects from scratch, you " +"often need to encode the payloads for transport through compliant mail " +"servers. This is especially true for :mimetype:`image/\\*` and :mimetype:" +"`text/\\*` type messages containing binary data." +msgstr "" +"從零開始建立 :class:`~email.message.Message` 物件時，你通常需要對負載 " +"(payload) 進行編碼，以便透過相容的郵件伺服器進行傳輸。對於包含二進位資料的 :" +"mimetype:`image/\\*` 和 :mimetype:`text/\\*` 類型的訊息尤其如此。" + +#: ../../library/email.encoders.rst:27 +msgid "" +"The :mod:`email` package provides some convenient encoders in its :mod:" +"`~email.encoders` module. These encoders are actually used by the :class:" +"`~email.mime.audio.MIMEAudio` and :class:`~email.mime.image.MIMEImage` class " +"constructors to provide default encodings. All encoder functions take " +"exactly one argument, the message object to encode. They usually extract " +"the payload, encode it, and reset the payload to this newly encoded value. " +"They should also set the :mailheader:`Content-Transfer-Encoding` header as " +"appropriate." +msgstr "" +":mod:`email` 套件在其 :mod:`~email.encoders` 模組中提供了一些方便的編碼器。這" +"些編碼器實際上由 :class:`~email.mime.audio.MIMEAudio` 和 :class:`~email.mime." +"image.MIMEImage` 類別建構函式使用來提供預設編碼。所有編碼器函式都只接受一個引" +"數，也就是要編碼的訊息物件。他們通常會提取負載、對其進行編碼，然後將負載重設" +"為新編碼的值。他們也應適當地設定 :mailheader:`Content-Transfer-Encoding` 標" +"頭。" + +#: ../../library/email.encoders.rst:35 +msgid "" +"Note that these functions are not meaningful for a multipart message. They " +"must be applied to individual subparts instead, and will raise a :exc:" +"`TypeError` if passed a message whose type is multipart." +msgstr "" +"請注意，這些函式對於多部分訊息 (multipart message) 沒有意義。它們必須應用於各" +"個子部分，如果傳遞類型為多部分訊息，則會引發 :exc:`TypeError`。" + +#: ../../library/email.encoders.rst:39 +msgid "Here are the encoding functions provided:" +msgstr "以下是提供的編碼函式：" + +#: ../../library/email.encoders.rst:44 +msgid "" +"Encodes the payload into quoted-printable form and sets the :mailheader:" +"`Content-Transfer-Encoding` header to ``quoted-printable`` [#]_. This is a " +"good encoding to use when most of your payload is normal printable data, but " +"contains a few unprintable characters." +msgstr "" +"將負載編碼為可列印字元 (quoted-printable) 形式，並將 :mailheader:`Content-" +"Transfer-Encoding` 標頭設定為 ``quoted-printable`` [#]_。當大部分負載是正常的" +"可列印資料，但包含一些不可列印的字元時，這是一種很好的編碼。" + +#: ../../library/email.encoders.rst:52 +msgid "" +"Encodes the payload into base64 form and sets the :mailheader:`Content-" +"Transfer-Encoding` header to ``base64``. This is a good encoding to use " +"when most of your payload is unprintable data since it is a more compact " +"form than quoted-printable. The drawback of base64 encoding is that it " +"renders the text non-human readable." +msgstr "" +"將負載編碼為 base64 形式，並將 :mailheader:`Content-Transfer-Encoding` 標頭設" +"定為 ``base64``。當大部分負載是不可列印資料時，這是一種很好的編碼，因為它是比" +"可列印字元更緊湊的形式。Base64 編碼的缺點是它使文字無法讓人類可讀。" + +#: ../../library/email.encoders.rst:61 +msgid "" +"This doesn't actually modify the message's payload, but it does set the :" +"mailheader:`Content-Transfer-Encoding` header to either ``7bit`` or ``8bit`` " +"as appropriate, based on the payload data." +msgstr "" +"這實際上並沒有修改訊息的負載，但它確實根據負載資料將 :mailheader:`Content-" +"Transfer-Encoding` 標頭設定為適當的 ``7bit`` 或 ``8bit``。" + +#: ../../library/email.encoders.rst:68 +msgid "" +"This does nothing; it doesn't even set the :mailheader:`Content-Transfer-" +"Encoding` header." +msgstr "" +"這沒有任何作用；它甚至沒有設定 :mailheader:`Content-Transfer-Encoding` 標頭。" + +#: ../../library/email.encoders.rst:72 +msgid "Footnotes" +msgstr "註腳" + +#: ../../library/email.encoders.rst:73 +msgid "" +"Note that encoding with :meth:`encode_quopri` also encodes all tabs and " +"space characters in the data." +msgstr "" +"請注意，使用 :meth:`encode_quopri` 進行編碼也會對資料中的所有定位字元 (tab) " +"和空格字元進行編碼。" diff --git a/library/email.errors.po b/library/email.errors.po index 8ff458b07f..536392d093 100644 --- a/library/email.errors.po +++ b/library/email.errors.po @@ -1,180 +1,180 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-03-04 00:14+0000\n" -"PO-Revision-Date: 2018-05-23 14:44+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/email.errors.rst:2 -msgid ":mod:`!email.errors`: Exception and Defect classes" -msgstr ":mod:`!email.errors`：例外和缺陷類別" - -#: ../../library/email.errors.rst:7 -msgid "**Source code:** :source:`Lib/email/errors.py`" -msgstr "**原始碼：**\\ :source:`Lib/email/errors.py`" - -#: ../../library/email.errors.rst:11 -msgid "" -"The following exception classes are defined in the :mod:`email.errors` " -"module:" -msgstr "" - -#: ../../library/email.errors.rst:16 -msgid "" -"This is the base class for all exceptions that the :mod:`email` package can " -"raise. It is derived from the standard :exc:`Exception` class and defines " -"no additional methods." -msgstr "" - -#: ../../library/email.errors.rst:23 -msgid "" -"This is the base class for exceptions raised by the :class:`~email.parser." -"Parser` class. It is derived from :exc:`MessageError`. This class is also " -"used internally by the parser used by :mod:`~email.headerregistry`." -msgstr "" - -#: ../../library/email.errors.rst:31 -msgid "" -"Raised under some error conditions when parsing the :rfc:`5322` headers of a " -"message, this class is derived from :exc:`MessageParseError`. The :meth:" -"`~email.message.EmailMessage.set_boundary` method will raise this error if " -"the content type is unknown when the method is called. :class:`~email.header." -"Header` may raise this error for certain base64 decoding errors, and when an " -"attempt is made to create a header that appears to contain an embedded " -"header (that is, there is what is supposed to be a continuation line that " -"has no leading whitespace and looks like a header)." -msgstr "" - -#: ../../library/email.errors.rst:43 -msgid "Deprecated and no longer used." -msgstr "" - -#: ../../library/email.errors.rst:48 -msgid "" -"Raised if the :meth:`~email.message.Message.attach` method is called on an " -"instance of a class derived from :class:`~email.mime.nonmultipart." -"MIMENonMultipart` (e.g. :class:`~email.mime.image.MIMEImage`). :exc:" -"`MultipartConversionError` multiply inherits from :exc:`MessageError` and " -"the built-in :exc:`TypeError`." -msgstr "" - -#: ../../library/email.errors.rst:58 -msgid "" -"Raised when an error occurs when the :mod:`~email.generator` outputs headers." -msgstr "" - -#: ../../library/email.errors.rst:64 -msgid "" -"This is the base class for all defects found when parsing email messages. It " -"is derived from :exc:`ValueError`." -msgstr "" - -#: ../../library/email.errors.rst:69 -msgid "" -"This is the base class for all defects found when parsing email headers. It " -"is derived from :exc:`MessageDefect`." -msgstr "" - -#: ../../library/email.errors.rst:72 -msgid "" -"Here is the list of the defects that the :class:`~email.parser.FeedParser` " -"can find while parsing messages. Note that the defects are added to the " -"message where the problem was found, so for example, if a message nested " -"inside a :mimetype:`multipart/alternative` had a malformed header, that " -"nested message object would have a defect, but the containing messages would " -"not." -msgstr "" - -#: ../../library/email.errors.rst:78 -msgid "" -"All defect classes are subclassed from :class:`email.errors.MessageDefect`." -msgstr "" - -#: ../../library/email.errors.rst:82 -msgid "" -"A message claimed to be a multipart, but had no :mimetype:`boundary` " -"parameter." -msgstr "" - -#: ../../library/email.errors.rst:87 -msgid "" -"The start boundary claimed in the :mailheader:`Content-Type` header was " -"never found." -msgstr "" - -#: ../../library/email.errors.rst:92 -msgid "" -"A start boundary was found, but no corresponding close boundary was ever " -"found." -msgstr "" - -#: ../../library/email.errors.rst:99 -msgid "The message had a continuation line as its first header line." -msgstr "" - -#: ../../library/email.errors.rst:103 -msgid "A \"Unix From\" header was found in the middle of a header block." -msgstr "" - -#: ../../library/email.errors.rst:107 -msgid "" -"A line was found while parsing headers that had no leading white space but " -"contained no ':'. Parsing continues assuming that the line represents the " -"first line of the body." -msgstr "" - -#: ../../library/email.errors.rst:115 -msgid "" -"A header was found that was missing a colon, or was otherwise malformed." -msgstr "" - -#: ../../library/email.errors.rst:117 -msgid "This defect has not been used for several Python versions." -msgstr "" - -#: ../../library/email.errors.rst:122 -msgid "" -"A message claimed to be a :mimetype:`multipart`, but no subparts were found. " -"Note that when a message has this defect, its :meth:`~email.message.Message." -"is_multipart` method may return ``False`` even though its content type " -"claims to be :mimetype:`multipart`." -msgstr "" - -#: ../../library/email.errors.rst:129 -msgid "" -"When decoding a block of base64 encoded bytes, the padding was not correct. " -"Enough padding is added to perform the decode, but the resulting decoded " -"bytes may be invalid." -msgstr "" - -#: ../../library/email.errors.rst:135 -msgid "" -"When decoding a block of base64 encoded bytes, characters outside the base64 " -"alphabet were encountered. The characters are ignored, but the resulting " -"decoded bytes may be invalid." -msgstr "" - -#: ../../library/email.errors.rst:141 -msgid "" -"When decoding a block of base64 encoded bytes, the number of non-padding " -"base64 characters was invalid (1 more than a multiple of 4). The encoded " -"block was kept as-is." -msgstr "" - -#: ../../library/email.errors.rst:147 -msgid "" -"When decoding an invalid or unparsable date field. The original value is " -"kept as-is." -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-03-04 00:14+0000\n" +"PO-Revision-Date: 2018-05-23 14:44+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/email.errors.rst:2 +msgid ":mod:`!email.errors`: Exception and Defect classes" +msgstr ":mod:`!email.errors`：例外和缺陷類別" + +#: ../../library/email.errors.rst:7 +msgid "**Source code:** :source:`Lib/email/errors.py`" +msgstr "**原始碼：**\\ :source:`Lib/email/errors.py`" + +#: ../../library/email.errors.rst:11 +msgid "" +"The following exception classes are defined in the :mod:`email.errors` " +"module:" +msgstr "" + +#: ../../library/email.errors.rst:16 +msgid "" +"This is the base class for all exceptions that the :mod:`email` package can " +"raise. It is derived from the standard :exc:`Exception` class and defines " +"no additional methods." +msgstr "" + +#: ../../library/email.errors.rst:23 +msgid "" +"This is the base class for exceptions raised by the :class:`~email.parser." +"Parser` class. It is derived from :exc:`MessageError`. This class is also " +"used internally by the parser used by :mod:`~email.headerregistry`." +msgstr "" + +#: ../../library/email.errors.rst:31 +msgid "" +"Raised under some error conditions when parsing the :rfc:`5322` headers of a " +"message, this class is derived from :exc:`MessageParseError`. The :meth:" +"`~email.message.EmailMessage.set_boundary` method will raise this error if " +"the content type is unknown when the method is called. :class:`~email.header." +"Header` may raise this error for certain base64 decoding errors, and when an " +"attempt is made to create a header that appears to contain an embedded " +"header (that is, there is what is supposed to be a continuation line that " +"has no leading whitespace and looks like a header)." +msgstr "" + +#: ../../library/email.errors.rst:43 +msgid "Deprecated and no longer used." +msgstr "" + +#: ../../library/email.errors.rst:48 +msgid "" +"Raised if the :meth:`~email.message.Message.attach` method is called on an " +"instance of a class derived from :class:`~email.mime.nonmultipart." +"MIMENonMultipart` (e.g. :class:`~email.mime.image.MIMEImage`). :exc:" +"`MultipartConversionError` multiply inherits from :exc:`MessageError` and " +"the built-in :exc:`TypeError`." +msgstr "" + +#: ../../library/email.errors.rst:58 +msgid "" +"Raised when an error occurs when the :mod:`~email.generator` outputs headers." +msgstr "" + +#: ../../library/email.errors.rst:64 +msgid "" +"This is the base class for all defects found when parsing email messages. It " +"is derived from :exc:`ValueError`." +msgstr "" + +#: ../../library/email.errors.rst:69 +msgid "" +"This is the base class for all defects found when parsing email headers. It " +"is derived from :exc:`MessageDefect`." +msgstr "" + +#: ../../library/email.errors.rst:72 +msgid "" +"Here is the list of the defects that the :class:`~email.parser.FeedParser` " +"can find while parsing messages. Note that the defects are added to the " +"message where the problem was found, so for example, if a message nested " +"inside a :mimetype:`multipart/alternative` had a malformed header, that " +"nested message object would have a defect, but the containing messages would " +"not." +msgstr "" + +#: ../../library/email.errors.rst:78 +msgid "" +"All defect classes are subclassed from :class:`email.errors.MessageDefect`." +msgstr "" + +#: ../../library/email.errors.rst:82 +msgid "" +"A message claimed to be a multipart, but had no :mimetype:`boundary` " +"parameter." +msgstr "" + +#: ../../library/email.errors.rst:87 +msgid "" +"The start boundary claimed in the :mailheader:`Content-Type` header was " +"never found." +msgstr "" + +#: ../../library/email.errors.rst:92 +msgid "" +"A start boundary was found, but no corresponding close boundary was ever " +"found." +msgstr "" + +#: ../../library/email.errors.rst:99 +msgid "The message had a continuation line as its first header line." +msgstr "" + +#: ../../library/email.errors.rst:103 +msgid "A \"Unix From\" header was found in the middle of a header block." +msgstr "" + +#: ../../library/email.errors.rst:107 +msgid "" +"A line was found while parsing headers that had no leading white space but " +"contained no ':'. Parsing continues assuming that the line represents the " +"first line of the body." +msgstr "" + +#: ../../library/email.errors.rst:115 +msgid "" +"A header was found that was missing a colon, or was otherwise malformed." +msgstr "" + +#: ../../library/email.errors.rst:117 +msgid "This defect has not been used for several Python versions." +msgstr "" + +#: ../../library/email.errors.rst:122 +msgid "" +"A message claimed to be a :mimetype:`multipart`, but no subparts were found. " +"Note that when a message has this defect, its :meth:`~email.message.Message." +"is_multipart` method may return ``False`` even though its content type " +"claims to be :mimetype:`multipart`." +msgstr "" + +#: ../../library/email.errors.rst:129 +msgid "" +"When decoding a block of base64 encoded bytes, the padding was not correct. " +"Enough padding is added to perform the decode, but the resulting decoded " +"bytes may be invalid." +msgstr "" + +#: ../../library/email.errors.rst:135 +msgid "" +"When decoding a block of base64 encoded bytes, characters outside the base64 " +"alphabet were encountered. The characters are ignored, but the resulting " +"decoded bytes may be invalid." +msgstr "" + +#: ../../library/email.errors.rst:141 +msgid "" +"When decoding a block of base64 encoded bytes, the number of non-padding " +"base64 characters was invalid (1 more than a multiple of 4). The encoded " +"block was kept as-is." +msgstr "" + +#: ../../library/email.errors.rst:147 +msgid "" +"When decoding an invalid or unparsable date field. The original value is " +"kept as-is." +msgstr "" diff --git a/library/email.examples.po b/library/email.examples.po index a6699ca390..9618995800 100644 --- a/library/email.examples.po +++ b/library/email.examples.po @@ -1,479 +1,479 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-04-08 00:14+0000\n" -"PO-Revision-Date: 2018-07-15 18:56+0800\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/email.examples.rst:4 -msgid ":mod:`email`: Examples" -msgstr ":mod:`email`：範例" - -#: ../../library/email.examples.rst:6 -msgid "" -"Here are a few examples of how to use the :mod:`email` package to read, " -"write, and send simple email messages, as well as more complex MIME messages." -msgstr "" - -#: ../../library/email.examples.rst:9 -msgid "" -"First, let's see how to create and send a simple text message (both the text " -"content and the addresses may contain unicode characters):" -msgstr "" - -#: ../../library/email.examples.rst:12 -msgid "" -"# Import smtplib for the actual sending function\n" -"import smtplib\n" -"\n" -"# Import the email modules we'll need\n" -"from email.message import EmailMessage\n" -"\n" -"# Open the plain text file whose name is in textfile for reading.\n" -"with open(textfile) as fp:\n" -" # Create a text/plain message\n" -" msg = EmailMessage()\n" -" msg.set_content(fp.read())\n" -"\n" -"# me == the sender's email address\n" -"# you == the recipient's email address\n" -"msg['Subject'] = f'The contents of {textfile}'\n" -"msg['From'] = me\n" -"msg['To'] = you\n" -"\n" -"# Send the message via our own SMTP server.\n" -"s = smtplib.SMTP('localhost')\n" -"s.send_message(msg)\n" -"s.quit()\n" -msgstr "" - -#: ../../library/email.examples.rst:15 -msgid "" -"Parsing :rfc:`822` headers can easily be done by the using the classes from " -"the :mod:`~email.parser` module:" -msgstr "" - -#: ../../library/email.examples.rst:18 -msgid "" -"# Import the email modules we'll need\n" -"#from email.parser import BytesParser\n" -"from email.parser import Parser\n" -"from email.policy import default\n" -"\n" -"# If the e-mail headers are in a file, uncomment these two lines:\n" -"# with open(messagefile, 'rb') as fp:\n" -"# headers = BytesParser(policy=default).parse(fp)\n" -"\n" -"# Or for parsing headers in a string (this is an uncommon operation), use:\n" -"headers = Parser(policy=default).parsestr(\n" -" 'From: Foo Bar \\n'\n" -" 'To: \\n'\n" -" 'Subject: Test message\\n'\n" -" '\\n'\n" -" 'Body would go here\\n')\n" -"\n" -"# Now the header items can be accessed as a dictionary:\n" -"print('To: {}'.format(headers['to']))\n" -"print('From: {}'.format(headers['from']))\n" -"print('Subject: {}'.format(headers['subject']))\n" -"\n" -"# You can also access the parts of the addresses:\n" -"print('Recipient username: {}'.format(headers['to'].addresses[0].username))\n" -"print('Sender name: {}'.format(headers['from'].addresses[0].display_name))\n" -msgstr "" - -#: ../../library/email.examples.rst:21 -msgid "" -"Here's an example of how to send a MIME message containing a bunch of family " -"pictures that may be residing in a directory:" -msgstr "" - -#: ../../library/email.examples.rst:24 -msgid "" -"# Import smtplib for the actual sending function.\n" -"import smtplib\n" -"\n" -"# Here are the email package modules we'll need.\n" -"from email.message import EmailMessage\n" -"\n" -"# Create the container email message.\n" -"msg = EmailMessage()\n" -"msg['Subject'] = 'Our family reunion'\n" -"# me == the sender's email address\n" -"# family = the list of all recipients' email addresses\n" -"msg['From'] = me\n" -"msg['To'] = ', '.join(family)\n" -"msg.preamble = 'You will not see this in a MIME-aware mail reader.\\n'\n" -"\n" -"# Open the files in binary mode. You can also omit the subtype\n" -"# if you want MIMEImage to guess it.\n" -"for file in pngfiles:\n" -" with open(file, 'rb') as fp:\n" -" img_data = fp.read()\n" -" msg.add_attachment(img_data, maintype='image',\n" -" subtype='png')\n" -"\n" -"# Send the email via our own SMTP server.\n" -"with smtplib.SMTP('localhost') as s:\n" -" s.send_message(msg)\n" -msgstr "" - -#: ../../library/email.examples.rst:27 -msgid "" -"Here's an example of how to send the entire contents of a directory as an " -"email message: [1]_" -msgstr "" - -#: ../../library/email.examples.rst:30 -msgid "" -"#!/usr/bin/env python3\n" -"\n" -"\"\"\"Send the contents of a directory as a MIME message.\"\"\"\n" -"\n" -"import os\n" -"import smtplib\n" -"# For guessing MIME type based on file name extension\n" -"import mimetypes\n" -"\n" -"from argparse import ArgumentParser\n" -"\n" -"from email.message import EmailMessage\n" -"from email.policy import SMTP\n" -"\n" -"\n" -"def main():\n" -" parser = ArgumentParser(description=\"\"\"\\\n" -"Send the contents of a directory as a MIME message.\n" -"Unless the -o option is given, the email is sent by forwarding to your " -"local\n" -"SMTP server, which then does the normal delivery process. Your local " -"machine\n" -"must be running an SMTP server.\n" -"\"\"\")\n" -" parser.add_argument('-d', '--directory',\n" -" help=\"\"\"Mail the contents of the specified " -"directory,\n" -" otherwise use the current directory. Only the " -"regular\n" -" files in the directory are sent, and we don't " -"recurse to\n" -" subdirectories.\"\"\")\n" -" parser.add_argument('-o', '--output',\n" -" metavar='FILE',\n" -" help=\"\"\"Print the composed message to FILE " -"instead of\n" -" sending the message to the SMTP server.\"\"\")\n" -" parser.add_argument('-s', '--sender', required=True,\n" -" help='The value of the From: header (required)')\n" -" parser.add_argument('-r', '--recipient', required=True,\n" -" action='append', metavar='RECIPIENT',\n" -" default=[], dest='recipients',\n" -" help='A To: header value (at least one required)')\n" -" args = parser.parse_args()\n" -" directory = args.directory\n" -" if not directory:\n" -" directory = '.'\n" -" # Create the message\n" -" msg = EmailMessage()\n" -" msg['Subject'] = f'Contents of directory {os.path.abspath(directory)}'\n" -" msg['To'] = ', '.join(args.recipients)\n" -" msg['From'] = args.sender\n" -" msg.preamble = 'You will not see this in a MIME-aware mail reader.\\n'\n" -"\n" -" for filename in os.listdir(directory):\n" -" path = os.path.join(directory, filename)\n" -" if not os.path.isfile(path):\n" -" continue\n" -" # Guess the content type based on the file's extension. Encoding\n" -" # will be ignored, although we should check for simple things like\n" -" # gzip'd or compressed files.\n" -" ctype, encoding = mimetypes.guess_file_type(path)\n" -" if ctype is None or encoding is not None:\n" -" # No guess could be made, or the file is encoded (compressed), " -"so\n" -" # use a generic bag-of-bits type.\n" -" ctype = 'application/octet-stream'\n" -" maintype, subtype = ctype.split('/', 1)\n" -" with open(path, 'rb') as fp:\n" -" msg.add_attachment(fp.read(),\n" -" maintype=maintype,\n" -" subtype=subtype,\n" -" filename=filename)\n" -" # Now send or store the message\n" -" if args.output:\n" -" with open(args.output, 'wb') as fp:\n" -" fp.write(msg.as_bytes(policy=SMTP))\n" -" else:\n" -" with smtplib.SMTP('localhost') as s:\n" -" s.send_message(msg)\n" -"\n" -"\n" -"if __name__ == '__main__':\n" -" main()\n" -msgstr "" - -#: ../../library/email.examples.rst:33 -msgid "" -"Here's an example of how to unpack a MIME message like the one above, into a " -"directory of files:" -msgstr "" - -#: ../../library/email.examples.rst:36 -msgid "" -"#!/usr/bin/env python3\n" -"\n" -"\"\"\"Unpack a MIME message into a directory of files.\"\"\"\n" -"\n" -"import os\n" -"import email\n" -"import mimetypes\n" -"\n" -"from email.policy import default\n" -"\n" -"from argparse import ArgumentParser\n" -"\n" -"\n" -"def main():\n" -" parser = ArgumentParser(description=\"\"\"\\\n" -"Unpack a MIME message into a directory of files.\n" -"\"\"\")\n" -" parser.add_argument('-d', '--directory', required=True,\n" -" help=\"\"\"Unpack the MIME message into the named\n" -" directory, which will be created if it doesn't " -"already\n" -" exist.\"\"\")\n" -" parser.add_argument('msgfile')\n" -" args = parser.parse_args()\n" -"\n" -" with open(args.msgfile, 'rb') as fp:\n" -" msg = email.message_from_binary_file(fp, policy=default)\n" -"\n" -" try:\n" -" os.mkdir(args.directory)\n" -" except FileExistsError:\n" -" pass\n" -"\n" -" counter = 1\n" -" for part in msg.walk():\n" -" # multipart/* are just containers\n" -" if part.get_content_maintype() == 'multipart':\n" -" continue\n" -" # Applications should really sanitize the given filename so that an\n" -" # email message can't be used to overwrite important files\n" -" filename = part.get_filename()\n" -" if not filename:\n" -" ext = mimetypes.guess_extension(part.get_content_type())\n" -" if not ext:\n" -" # Use a generic bag-of-bits extension\n" -" ext = '.bin'\n" -" filename = f'part-{counter:03d}{ext}'\n" -" counter += 1\n" -" with open(os.path.join(args.directory, filename), 'wb') as fp:\n" -" fp.write(part.get_payload(decode=True))\n" -"\n" -"\n" -"if __name__ == '__main__':\n" -" main()\n" -msgstr "" - -#: ../../library/email.examples.rst:39 -msgid "" -"Here's an example of how to create an HTML message with an alternative plain " -"text version. To make things a bit more interesting, we include a related " -"image in the html part, and we save a copy of what we are going to send to " -"disk, as well as sending it." -msgstr "" - -#: ../../library/email.examples.rst:44 -msgid "" -"#!/usr/bin/env python3\n" -"\n" -"import smtplib\n" -"\n" -"from email.message import EmailMessage\n" -"from email.headerregistry import Address\n" -"from email.utils import make_msgid\n" -"\n" -"# Create the base text message.\n" -"msg = EmailMessage()\n" -"msg['Subject'] = \"Pourquoi pas des asperges pour ce midi ?\"\n" -"msg['From'] = Address(\"Pepé Le Pew\", \"pepe\", \"example.com\")\n" -"msg['To'] = (Address(\"Penelope Pussycat\", \"penelope\", \"example.com\"),\n" -" Address(\"Fabrette Pussycat\", \"fabrette\", \"example.com\"))\n" -"msg.set_content(\"\"\"\\\n" -"Salut!\n" -"\n" -"Cette recette [1] sera sûrement un très bon repas.\n" -"\n" -"[1] http://www.yummly.com/recipe/Roasted-Asparagus-Epicurious-203718\n" -"\n" -"--Pepé\n" -"\"\"\")\n" -"\n" -"# Add the html version. This converts the message into a multipart/" -"alternative\n" -"# container, with the original text message as the first part and the new " -"html\n" -"# message as the second part.\n" -"asparagus_cid = make_msgid()\n" -"msg.add_alternative(\"\"\"\\\n" -"\n" -" \n" -" \n" -"

Salut!

\n" -"

Cette\n" -" \n" -" recette\n" -" sera sûrement un très bon repas.\n" -"

\n" -" \n" -" \n" -"\n" -"\"\"\".format(asparagus_cid=asparagus_cid[1:-1]), subtype='html')\n" -"# note that we needed to peel the <> off the msgid for use in the html.\n" -"\n" -"# Now add the related image to the html part.\n" -"with open(\"roasted-asparagus.jpg\", 'rb') as img:\n" -" msg.get_payload()[1].add_related(img.read(), 'image', 'jpeg',\n" -" cid=asparagus_cid)\n" -"\n" -"# Make a local copy of what we are going to send.\n" -"with open('outgoing.msg', 'wb') as f:\n" -" f.write(bytes(msg))\n" -"\n" -"# Send the message via local SMTP server.\n" -"with smtplib.SMTP('localhost') as s:\n" -" s.send_message(msg)\n" -msgstr "" - -#: ../../library/email.examples.rst:47 -msgid "" -"If we were sent the message from the last example, here is one way we could " -"process it:" -msgstr "" - -#: ../../library/email.examples.rst:50 -msgid "" -"import os\n" -"import sys\n" -"import tempfile\n" -"import mimetypes\n" -"import webbrowser\n" -"\n" -"# Import the email modules we'll need\n" -"from email import policy\n" -"from email.parser import BytesParser\n" -"\n" -"\n" -"def magic_html_parser(html_text, partfiles):\n" -" \"\"\"Return safety-sanitized html linked to partfiles.\n" -"\n" -" Rewrite the href=\"cid:....\" attributes to point to the filenames in " -"partfiles.\n" -" Though not trivial, this should be possible using html.parser.\n" -" \"\"\"\n" -" raise NotImplementedError(\"Add the magic needed\")\n" -"\n" -"\n" -"# In a real program you'd get the filename from the arguments.\n" -"with open('outgoing.msg', 'rb') as fp:\n" -" msg = BytesParser(policy=policy.default).parse(fp)\n" -"\n" -"# Now the header items can be accessed as a dictionary, and any non-ASCII " -"will\n" -"# be converted to unicode:\n" -"print('To:', msg['to'])\n" -"print('From:', msg['from'])\n" -"print('Subject:', msg['subject'])\n" -"\n" -"# If we want to print a preview of the message content, we can extract " -"whatever\n" -"# the least formatted payload is and print the first three lines. Of " -"course,\n" -"# if the message has no plain text part printing the first three lines of " -"html\n" -"# is probably useless, but this is just a conceptual example.\n" -"simplest = msg.get_body(preferencelist=('plain', 'html'))\n" -"print()\n" -"print(''.join(simplest.get_content().splitlines(keepends=True)[:3]))\n" -"\n" -"ans = input(\"View full message?\")\n" -"if ans.lower()[0] == 'n':\n" -" sys.exit()\n" -"\n" -"# We can extract the richest alternative in order to display it:\n" -"richest = msg.get_body()\n" -"partfiles = {}\n" -"if richest['content-type'].maintype == 'text':\n" -" if richest['content-type'].subtype == 'plain':\n" -" for line in richest.get_content().splitlines():\n" -" print(line)\n" -" sys.exit()\n" -" elif richest['content-type'].subtype == 'html':\n" -" body = richest\n" -" else:\n" -" print(\"Don't know how to display {}\".format(richest." -"get_content_type()))\n" -" sys.exit()\n" -"elif richest['content-type'].content_type == 'multipart/related':\n" -" body = richest.get_body(preferencelist=('html'))\n" -" for part in richest.iter_attachments():\n" -" fn = part.get_filename()\n" -" if fn:\n" -" extension = os.path.splitext(part.get_filename())[1]\n" -" else:\n" -" extension = mimetypes.guess_extension(part.get_content_type())\n" -" with tempfile.NamedTemporaryFile(suffix=extension, delete=False) as " -"f:\n" -" f.write(part.get_content())\n" -" # again strip the <> to go from email form of cid to html form.\n" -" partfiles[part['content-id'][1:-1]] = f.name\n" -"else:\n" -" print(\"Don't know how to display {}\".format(richest." -"get_content_type()))\n" -" sys.exit()\n" -"with tempfile.NamedTemporaryFile(mode='w', delete=False) as f:\n" -" f.write(magic_html_parser(body.get_content(), partfiles))\n" -"webbrowser.open(f.name)\n" -"os.remove(f.name)\n" -"for fn in partfiles.values():\n" -" os.remove(fn)\n" -"\n" -"# Of course, there are lots of email messages that could break this simple\n" -"# minded program, but it will handle the most common ones.\n" -msgstr "" - -#: ../../library/email.examples.rst:52 -msgid "Up to the prompt, the output from the above is:" -msgstr "" - -#: ../../library/email.examples.rst:54 -msgid "" -"To: Penelope Pussycat , Fabrette Pussycat " -"\n" -"From: Pepé Le Pew \n" -"Subject: Pourquoi pas des asperges pour ce midi ?\n" -"\n" -"Salut!\n" -"\n" -"Cette recette [1] sera sûrement un très bon repas." -msgstr "" - -#: ../../library/email.examples.rst:66 -msgid "Footnotes" -msgstr "註解" - -#: ../../library/email.examples.rst:67 -msgid "" -"Thanks to Matthew Dixon Cowles for the original inspiration and examples." -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-04-08 00:14+0000\n" +"PO-Revision-Date: 2018-07-15 18:56+0800\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/email.examples.rst:4 +msgid ":mod:`email`: Examples" +msgstr ":mod:`email`：範例" + +#: ../../library/email.examples.rst:6 +msgid "" +"Here are a few examples of how to use the :mod:`email` package to read, " +"write, and send simple email messages, as well as more complex MIME messages." +msgstr "" + +#: ../../library/email.examples.rst:9 +msgid "" +"First, let's see how to create and send a simple text message (both the text " +"content and the addresses may contain unicode characters):" +msgstr "" + +#: ../../library/email.examples.rst:12 +msgid "" +"# Import smtplib for the actual sending function\n" +"import smtplib\n" +"\n" +"# Import the email modules we'll need\n" +"from email.message import EmailMessage\n" +"\n" +"# Open the plain text file whose name is in textfile for reading.\n" +"with open(textfile) as fp:\n" +" # Create a text/plain message\n" +" msg = EmailMessage()\n" +" msg.set_content(fp.read())\n" +"\n" +"# me == the sender's email address\n" +"# you == the recipient's email address\n" +"msg['Subject'] = f'The contents of {textfile}'\n" +"msg['From'] = me\n" +"msg['To'] = you\n" +"\n" +"# Send the message via our own SMTP server.\n" +"s = smtplib.SMTP('localhost')\n" +"s.send_message(msg)\n" +"s.quit()\n" +msgstr "" + +#: ../../library/email.examples.rst:15 +msgid "" +"Parsing :rfc:`822` headers can easily be done by the using the classes from " +"the :mod:`~email.parser` module:" +msgstr "" + +#: ../../library/email.examples.rst:18 +msgid "" +"# Import the email modules we'll need\n" +"#from email.parser import BytesParser\n" +"from email.parser import Parser\n" +"from email.policy import default\n" +"\n" +"# If the e-mail headers are in a file, uncomment these two lines:\n" +"# with open(messagefile, 'rb') as fp:\n" +"# headers = BytesParser(policy=default).parse(fp)\n" +"\n" +"# Or for parsing headers in a string (this is an uncommon operation), use:\n" +"headers = Parser(policy=default).parsestr(\n" +" 'From: Foo Bar \\n'\n" +" 'To: \\n'\n" +" 'Subject: Test message\\n'\n" +" '\\n'\n" +" 'Body would go here\\n')\n" +"\n" +"# Now the header items can be accessed as a dictionary:\n" +"print('To: {}'.format(headers['to']))\n" +"print('From: {}'.format(headers['from']))\n" +"print('Subject: {}'.format(headers['subject']))\n" +"\n" +"# You can also access the parts of the addresses:\n" +"print('Recipient username: {}'.format(headers['to'].addresses[0].username))\n" +"print('Sender name: {}'.format(headers['from'].addresses[0].display_name))\n" +msgstr "" + +#: ../../library/email.examples.rst:21 +msgid "" +"Here's an example of how to send a MIME message containing a bunch of family " +"pictures that may be residing in a directory:" +msgstr "" + +#: ../../library/email.examples.rst:24 +msgid "" +"# Import smtplib for the actual sending function.\n" +"import smtplib\n" +"\n" +"# Here are the email package modules we'll need.\n" +"from email.message import EmailMessage\n" +"\n" +"# Create the container email message.\n" +"msg = EmailMessage()\n" +"msg['Subject'] = 'Our family reunion'\n" +"# me == the sender's email address\n" +"# family = the list of all recipients' email addresses\n" +"msg['From'] = me\n" +"msg['To'] = ', '.join(family)\n" +"msg.preamble = 'You will not see this in a MIME-aware mail reader.\\n'\n" +"\n" +"# Open the files in binary mode. You can also omit the subtype\n" +"# if you want MIMEImage to guess it.\n" +"for file in pngfiles:\n" +" with open(file, 'rb') as fp:\n" +" img_data = fp.read()\n" +" msg.add_attachment(img_data, maintype='image',\n" +" subtype='png')\n" +"\n" +"# Send the email via our own SMTP server.\n" +"with smtplib.SMTP('localhost') as s:\n" +" s.send_message(msg)\n" +msgstr "" + +#: ../../library/email.examples.rst:27 +msgid "" +"Here's an example of how to send the entire contents of a directory as an " +"email message: [1]_" +msgstr "" + +#: ../../library/email.examples.rst:30 +msgid "" +"#!/usr/bin/env python3\n" +"\n" +"\"\"\"Send the contents of a directory as a MIME message.\"\"\"\n" +"\n" +"import os\n" +"import smtplib\n" +"# For guessing MIME type based on file name extension\n" +"import mimetypes\n" +"\n" +"from argparse import ArgumentParser\n" +"\n" +"from email.message import EmailMessage\n" +"from email.policy import SMTP\n" +"\n" +"\n" +"def main():\n" +" parser = ArgumentParser(description=\"\"\"\\\n" +"Send the contents of a directory as a MIME message.\n" +"Unless the -o option is given, the email is sent by forwarding to your " +"local\n" +"SMTP server, which then does the normal delivery process. Your local " +"machine\n" +"must be running an SMTP server.\n" +"\"\"\")\n" +" parser.add_argument('-d', '--directory',\n" +" help=\"\"\"Mail the contents of the specified " +"directory,\n" +" otherwise use the current directory. Only the " +"regular\n" +" files in the directory are sent, and we don't " +"recurse to\n" +" subdirectories.\"\"\")\n" +" parser.add_argument('-o', '--output',\n" +" metavar='FILE',\n" +" help=\"\"\"Print the composed message to FILE " +"instead of\n" +" sending the message to the SMTP server.\"\"\")\n" +" parser.add_argument('-s', '--sender', required=True,\n" +" help='The value of the From: header (required)')\n" +" parser.add_argument('-r', '--recipient', required=True,\n" +" action='append', metavar='RECIPIENT',\n" +" default=[], dest='recipients',\n" +" help='A To: header value (at least one required)')\n" +" args = parser.parse_args()\n" +" directory = args.directory\n" +" if not directory:\n" +" directory = '.'\n" +" # Create the message\n" +" msg = EmailMessage()\n" +" msg['Subject'] = f'Contents of directory {os.path.abspath(directory)}'\n" +" msg['To'] = ', '.join(args.recipients)\n" +" msg['From'] = args.sender\n" +" msg.preamble = 'You will not see this in a MIME-aware mail reader.\\n'\n" +"\n" +" for filename in os.listdir(directory):\n" +" path = os.path.join(directory, filename)\n" +" if not os.path.isfile(path):\n" +" continue\n" +" # Guess the content type based on the file's extension. Encoding\n" +" # will be ignored, although we should check for simple things like\n" +" # gzip'd or compressed files.\n" +" ctype, encoding = mimetypes.guess_file_type(path)\n" +" if ctype is None or encoding is not None:\n" +" # No guess could be made, or the file is encoded (compressed), " +"so\n" +" # use a generic bag-of-bits type.\n" +" ctype = 'application/octet-stream'\n" +" maintype, subtype = ctype.split('/', 1)\n" +" with open(path, 'rb') as fp:\n" +" msg.add_attachment(fp.read(),\n" +" maintype=maintype,\n" +" subtype=subtype,\n" +" filename=filename)\n" +" # Now send or store the message\n" +" if args.output:\n" +" with open(args.output, 'wb') as fp:\n" +" fp.write(msg.as_bytes(policy=SMTP))\n" +" else:\n" +" with smtplib.SMTP('localhost') as s:\n" +" s.send_message(msg)\n" +"\n" +"\n" +"if __name__ == '__main__':\n" +" main()\n" +msgstr "" + +#: ../../library/email.examples.rst:33 +msgid "" +"Here's an example of how to unpack a MIME message like the one above, into a " +"directory of files:" +msgstr "" + +#: ../../library/email.examples.rst:36 +msgid "" +"#!/usr/bin/env python3\n" +"\n" +"\"\"\"Unpack a MIME message into a directory of files.\"\"\"\n" +"\n" +"import os\n" +"import email\n" +"import mimetypes\n" +"\n" +"from email.policy import default\n" +"\n" +"from argparse import ArgumentParser\n" +"\n" +"\n" +"def main():\n" +" parser = ArgumentParser(description=\"\"\"\\\n" +"Unpack a MIME message into a directory of files.\n" +"\"\"\")\n" +" parser.add_argument('-d', '--directory', required=True,\n" +" help=\"\"\"Unpack the MIME message into the named\n" +" directory, which will be created if it doesn't " +"already\n" +" exist.\"\"\")\n" +" parser.add_argument('msgfile')\n" +" args = parser.parse_args()\n" +"\n" +" with open(args.msgfile, 'rb') as fp:\n" +" msg = email.message_from_binary_file(fp, policy=default)\n" +"\n" +" try:\n" +" os.mkdir(args.directory)\n" +" except FileExistsError:\n" +" pass\n" +"\n" +" counter = 1\n" +" for part in msg.walk():\n" +" # multipart/* are just containers\n" +" if part.get_content_maintype() == 'multipart':\n" +" continue\n" +" # Applications should really sanitize the given filename so that an\n" +" # email message can't be used to overwrite important files\n" +" filename = part.get_filename()\n" +" if not filename:\n" +" ext = mimetypes.guess_extension(part.get_content_type())\n" +" if not ext:\n" +" # Use a generic bag-of-bits extension\n" +" ext = '.bin'\n" +" filename = f'part-{counter:03d}{ext}'\n" +" counter += 1\n" +" with open(os.path.join(args.directory, filename), 'wb') as fp:\n" +" fp.write(part.get_payload(decode=True))\n" +"\n" +"\n" +"if __name__ == '__main__':\n" +" main()\n" +msgstr "" + +#: ../../library/email.examples.rst:39 +msgid "" +"Here's an example of how to create an HTML message with an alternative plain " +"text version. To make things a bit more interesting, we include a related " +"image in the html part, and we save a copy of what we are going to send to " +"disk, as well as sending it." +msgstr "" + +#: ../../library/email.examples.rst:44 +msgid "" +"#!/usr/bin/env python3\n" +"\n" +"import smtplib\n" +"\n" +"from email.message import EmailMessage\n" +"from email.headerregistry import Address\n" +"from email.utils import make_msgid\n" +"\n" +"# Create the base text message.\n" +"msg = EmailMessage()\n" +"msg['Subject'] = \"Pourquoi pas des asperges pour ce midi ?\"\n" +"msg['From'] = Address(\"Pepé Le Pew\", \"pepe\", \"example.com\")\n" +"msg['To'] = (Address(\"Penelope Pussycat\", \"penelope\", \"example.com\"),\n" +" Address(\"Fabrette Pussycat\", \"fabrette\", \"example.com\"))\n" +"msg.set_content(\"\"\"\\\n" +"Salut!\n" +"\n" +"Cette recette [1] sera sûrement un très bon repas.\n" +"\n" +"[1] http://www.yummly.com/recipe/Roasted-Asparagus-Epicurious-203718\n" +"\n" +"--Pepé\n" +"\"\"\")\n" +"\n" +"# Add the html version. This converts the message into a multipart/" +"alternative\n" +"# container, with the original text message as the first part and the new " +"html\n" +"# message as the second part.\n" +"asparagus_cid = make_msgid()\n" +"msg.add_alternative(\"\"\"\\\n" +"\n" +" \n" +" \n" +"

Salut!

\n" +"

Cette\n" +" \n" +" recette\n" +" sera sûrement un très bon repas.\n" +"

\n" +" \n" +" \n" +"\n" +"\"\"\".format(asparagus_cid=asparagus_cid[1:-1]), subtype='html')\n" +"# note that we needed to peel the <> off the msgid for use in the html.\n" +"\n" +"# Now add the related image to the html part.\n" +"with open(\"roasted-asparagus.jpg\", 'rb') as img:\n" +" msg.get_payload()[1].add_related(img.read(), 'image', 'jpeg',\n" +" cid=asparagus_cid)\n" +"\n" +"# Make a local copy of what we are going to send.\n" +"with open('outgoing.msg', 'wb') as f:\n" +" f.write(bytes(msg))\n" +"\n" +"# Send the message via local SMTP server.\n" +"with smtplib.SMTP('localhost') as s:\n" +" s.send_message(msg)\n" +msgstr "" + +#: ../../library/email.examples.rst:47 +msgid "" +"If we were sent the message from the last example, here is one way we could " +"process it:" +msgstr "" + +#: ../../library/email.examples.rst:50 +msgid "" +"import os\n" +"import sys\n" +"import tempfile\n" +"import mimetypes\n" +"import webbrowser\n" +"\n" +"# Import the email modules we'll need\n" +"from email import policy\n" +"from email.parser import BytesParser\n" +"\n" +"\n" +"def magic_html_parser(html_text, partfiles):\n" +" \"\"\"Return safety-sanitized html linked to partfiles.\n" +"\n" +" Rewrite the href=\"cid:....\" attributes to point to the filenames in " +"partfiles.\n" +" Though not trivial, this should be possible using html.parser.\n" +" \"\"\"\n" +" raise NotImplementedError(\"Add the magic needed\")\n" +"\n" +"\n" +"# In a real program you'd get the filename from the arguments.\n" +"with open('outgoing.msg', 'rb') as fp:\n" +" msg = BytesParser(policy=policy.default).parse(fp)\n" +"\n" +"# Now the header items can be accessed as a dictionary, and any non-ASCII " +"will\n" +"# be converted to unicode:\n" +"print('To:', msg['to'])\n" +"print('From:', msg['from'])\n" +"print('Subject:', msg['subject'])\n" +"\n" +"# If we want to print a preview of the message content, we can extract " +"whatever\n" +"# the least formatted payload is and print the first three lines. Of " +"course,\n" +"# if the message has no plain text part printing the first three lines of " +"html\n" +"# is probably useless, but this is just a conceptual example.\n" +"simplest = msg.get_body(preferencelist=('plain', 'html'))\n" +"print()\n" +"print(''.join(simplest.get_content().splitlines(keepends=True)[:3]))\n" +"\n" +"ans = input(\"View full message?\")\n" +"if ans.lower()[0] == 'n':\n" +" sys.exit()\n" +"\n" +"# We can extract the richest alternative in order to display it:\n" +"richest = msg.get_body()\n" +"partfiles = {}\n" +"if richest['content-type'].maintype == 'text':\n" +" if richest['content-type'].subtype == 'plain':\n" +" for line in richest.get_content().splitlines():\n" +" print(line)\n" +" sys.exit()\n" +" elif richest['content-type'].subtype == 'html':\n" +" body = richest\n" +" else:\n" +" print(\"Don't know how to display {}\".format(richest." +"get_content_type()))\n" +" sys.exit()\n" +"elif richest['content-type'].content_type == 'multipart/related':\n" +" body = richest.get_body(preferencelist=('html'))\n" +" for part in richest.iter_attachments():\n" +" fn = part.get_filename()\n" +" if fn:\n" +" extension = os.path.splitext(part.get_filename())[1]\n" +" else:\n" +" extension = mimetypes.guess_extension(part.get_content_type())\n" +" with tempfile.NamedTemporaryFile(suffix=extension, delete=False) as " +"f:\n" +" f.write(part.get_content())\n" +" # again strip the <> to go from email form of cid to html form.\n" +" partfiles[part['content-id'][1:-1]] = f.name\n" +"else:\n" +" print(\"Don't know how to display {}\".format(richest." +"get_content_type()))\n" +" sys.exit()\n" +"with tempfile.NamedTemporaryFile(mode='w', delete=False) as f:\n" +" f.write(magic_html_parser(body.get_content(), partfiles))\n" +"webbrowser.open(f.name)\n" +"os.remove(f.name)\n" +"for fn in partfiles.values():\n" +" os.remove(fn)\n" +"\n" +"# Of course, there are lots of email messages that could break this simple\n" +"# minded program, but it will handle the most common ones.\n" +msgstr "" + +#: ../../library/email.examples.rst:52 +msgid "Up to the prompt, the output from the above is:" +msgstr "" + +#: ../../library/email.examples.rst:54 +msgid "" +"To: Penelope Pussycat , Fabrette Pussycat " +"\n" +"From: Pepé Le Pew \n" +"Subject: Pourquoi pas des asperges pour ce midi ?\n" +"\n" +"Salut!\n" +"\n" +"Cette recette [1] sera sûrement un très bon repas." +msgstr "" + +#: ../../library/email.examples.rst:66 +msgid "Footnotes" +msgstr "註解" + +#: ../../library/email.examples.rst:67 +msgid "" +"Thanks to Matthew Dixon Cowles for the original inspiration and examples." +msgstr "" diff --git a/library/email.generator.po b/library/email.generator.po index 3ab3635a49..ca1928dec0 100644 --- a/library/email.generator.po +++ b/library/email.generator.po @@ -1,329 +1,329 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-09-23 07:52+0800\n" -"PO-Revision-Date: 2018-05-23 14:44+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/email.generator.rst:2 -msgid ":mod:`!email.generator`: Generating MIME documents" -msgstr ":mod:`!email.generator`：產生 MIME 文件" - -#: ../../library/email.generator.rst:7 -msgid "**Source code:** :source:`Lib/email/generator.py`" -msgstr "**原始碼：**\\ :source:`Lib/email/generator.py`" - -#: ../../library/email.generator.rst:11 -msgid "" -"One of the most common tasks is to generate the flat (serialized) version of " -"the email message represented by a message object structure. You will need " -"to do this if you want to send your message via :meth:`smtplib.SMTP." -"sendmail`, or print the message on the console. Taking a message object " -"structure and producing a serialized representation is the job of the " -"generator classes." -msgstr "" - -#: ../../library/email.generator.rst:18 -msgid "" -"As with the :mod:`email.parser` module, you aren't limited to the " -"functionality of the bundled generator; you could write one from scratch " -"yourself. However the bundled generator knows how to generate most email in " -"a standards-compliant way, should handle MIME and non-MIME email messages " -"just fine, and is designed so that the bytes-oriented parsing and generation " -"operations are inverses, assuming the same non-transforming :mod:`~email." -"policy` is used for both. That is, parsing the serialized byte stream via " -"the :class:`~email.parser.BytesParser` class and then regenerating the " -"serialized byte stream using :class:`BytesGenerator` should produce output " -"identical to the input [#]_. (On the other hand, using the generator on an :" -"class:`~email.message.EmailMessage` constructed by program may result in " -"changes to the :class:`~email.message.EmailMessage` object as defaults are " -"filled in.)" -msgstr "" - -#: ../../library/email.generator.rst:32 -msgid "" -"The :class:`Generator` class can be used to flatten a message into a text " -"(as opposed to binary) serialized representation, but since Unicode cannot " -"represent binary data directly, the message is of necessity transformed into " -"something that contains only ASCII characters, using the standard email RFC " -"Content Transfer Encoding techniques for encoding email messages for " -"transport over channels that are not \"8 bit clean\"." -msgstr "" - -#: ../../library/email.generator.rst:39 -msgid "" -"To accommodate reproducible processing of SMIME-signed messages :class:" -"`Generator` disables header folding for message parts of type ``multipart/" -"signed`` and all subparts." -msgstr "" - -#: ../../library/email.generator.rst:47 -msgid "" -"Return a :class:`BytesGenerator` object that will write any message provided " -"to the :meth:`flatten` method, or any surrogateescape encoded text provided " -"to the :meth:`write` method, to the :term:`file-like object` *outfp*. " -"*outfp* must support a ``write`` method that accepts binary data." -msgstr "" - -#: ../../library/email.generator.rst:52 ../../library/email.generator.rst:153 -msgid "" -"If optional *mangle_from_* is ``True``, put a ``>`` character in front of " -"any line in the body that starts with the exact string ``\"From \"``, that " -"is ``From`` followed by a space at the beginning of a line. *mangle_from_* " -"defaults to the value of the :attr:`~email.policy.Policy.mangle_from_` " -"setting of the *policy* (which is ``True`` for the :data:`~email.policy." -"compat32` policy and ``False`` for all others). *mangle_from_* is intended " -"for use when messages are stored in Unix mbox format (see :mod:`mailbox` and " -"`WHY THE CONTENT-LENGTH FORMAT IS BAD `_)." -msgstr "" - -#: ../../library/email.generator.rst:62 ../../library/email.generator.rst:163 -msgid "" -"If *maxheaderlen* is not ``None``, refold any header lines that are longer " -"than *maxheaderlen*, or if ``0``, do not rewrap any headers. If " -"*manheaderlen* is ``None`` (the default), wrap headers and other message " -"lines according to the *policy* settings." -msgstr "" - -#: ../../library/email.generator.rst:67 ../../library/email.generator.rst:168 -msgid "" -"If *policy* is specified, use that policy to control message generation. If " -"*policy* is ``None`` (the default), use the policy associated with the :" -"class:`~email.message.Message` or :class:`~email.message.EmailMessage` " -"object passed to ``flatten`` to control the message generation. See :mod:" -"`email.policy` for details on what *policy* controls." -msgstr "" - -#: ../../library/email.generator.rst:75 ../../library/email.generator.rst:174 -msgid "Added the *policy* keyword." -msgstr "新增關鍵字 *policy*。" - -#: ../../library/email.generator.rst:77 ../../library/email.generator.rst:176 -msgid "" -"The default behavior of the *mangle_from_* and *maxheaderlen* parameters is " -"to follow the policy." -msgstr "" - -#: ../../library/email.generator.rst:83 -msgid "" -"Print the textual representation of the message object structure rooted at " -"*msg* to the output file specified when the :class:`BytesGenerator` instance " -"was created." -msgstr "" - -#: ../../library/email.generator.rst:87 -msgid "" -"If the :mod:`~email.policy` option :attr:`~email.policy.Policy.cte_type` is " -"``8bit`` (the default), copy any headers in the original parsed message that " -"have not been modified to the output with any bytes with the high bit set " -"reproduced as in the original, and preserve the non-ASCII :mailheader:" -"`Content-Transfer-Encoding` of any body parts that have them. If " -"``cte_type`` is ``7bit``, convert the bytes with the high bit set as needed " -"using an ASCII-compatible :mailheader:`Content-Transfer-Encoding`. That is, " -"transform parts with non-ASCII :mailheader:`Content-Transfer-Encoding` (:" -"mailheader:`Content-Transfer-Encoding: 8bit`) to an ASCII compatible :" -"mailheader:`Content-Transfer-Encoding`, and encode RFC-invalid non-ASCII " -"bytes in headers using the MIME ``unknown-8bit`` character set, thus " -"rendering them RFC-compliant." -msgstr "" - -#: ../../library/email.generator.rst:104 ../../library/email.generator.rst:197 -msgid "" -"If *unixfrom* is ``True``, print the envelope header delimiter used by the " -"Unix mailbox format (see :mod:`mailbox`) before the first of the :rfc:`5322` " -"headers of the root message object. If the root object has no envelope " -"header, craft a standard one. The default is ``False``. Note that for " -"subparts, no envelope header is ever printed." -msgstr "" - -#: ../../library/email.generator.rst:110 ../../library/email.generator.rst:203 -msgid "" -"If *linesep* is not ``None``, use it as the separator character between all " -"the lines of the flattened message. If *linesep* is ``None`` (the default), " -"use the value specified in the *policy*." -msgstr "" - -#: ../../library/email.generator.rst:119 -msgid "" -"Return an independent clone of this :class:`BytesGenerator` instance with " -"the exact same option settings, and *fp* as the new *outfp*." -msgstr "" - -#: ../../library/email.generator.rst:125 -msgid "" -"Encode *s* using the ``ASCII`` codec and the ``surrogateescape`` error " -"handler, and pass it to the *write* method of the *outfp* passed to the :" -"class:`BytesGenerator`'s constructor." -msgstr "" - -#: ../../library/email.generator.rst:130 -msgid "" -"As a convenience, :class:`~email.message.EmailMessage` provides the methods :" -"meth:`~email.message.EmailMessage.as_bytes` and ``bytes(aMessage)`` (a.k.a. :" -"meth:`~email.message.EmailMessage.__bytes__`), which simplify the generation " -"of a serialized binary representation of a message object. For more detail, " -"see :mod:`email.message`." -msgstr "" - -#: ../../library/email.generator.rst:137 -msgid "" -"Because strings cannot represent binary data, the :class:`Generator` class " -"must convert any binary data in any message it flattens to an ASCII " -"compatible format, by converting them to an ASCII compatible :mailheader:" -"`Content-Transfer_Encoding`. Using the terminology of the email RFCs, you " -"can think of this as :class:`Generator` serializing to an I/O stream that is " -"not \"8 bit clean\". In other words, most applications will want to be " -"using :class:`BytesGenerator`, and not :class:`Generator`." -msgstr "" - -#: ../../library/email.generator.rst:148 -msgid "" -"Return a :class:`Generator` object that will write any message provided to " -"the :meth:`flatten` method, or any text provided to the :meth:`write` " -"method, to the :term:`file-like object` *outfp*. *outfp* must support a " -"``write`` method that accepts string data." -msgstr "" - -#: ../../library/email.generator.rst:182 -msgid "" -"Print the textual representation of the message object structure rooted at " -"*msg* to the output file specified when the :class:`Generator` instance was " -"created." -msgstr "" - -#: ../../library/email.generator.rst:186 -msgid "" -"If the :mod:`~email.policy` option :attr:`~email.policy.Policy.cte_type` is " -"``8bit``, generate the message as if the option were set to ``7bit``. (This " -"is required because strings cannot represent non-ASCII bytes.) Convert any " -"bytes with the high bit set as needed using an ASCII-compatible :mailheader:" -"`Content-Transfer-Encoding`. That is, transform parts with non-ASCII :" -"mailheader:`Content-Transfer-Encoding` (:mailheader:`Content-Transfer-" -"Encoding: 8bit`) to an ASCII compatible :mailheader:`Content-Transfer-" -"Encoding`, and encode RFC-invalid non-ASCII bytes in headers using the MIME " -"``unknown-8bit`` character set, thus rendering them RFC-compliant." -msgstr "" - -#: ../../library/email.generator.rst:209 -msgid "" -"Added support for re-encoding ``8bit`` message bodies, and the *linesep* " -"argument." -msgstr "" - -#: ../../library/email.generator.rst:216 -msgid "" -"Return an independent clone of this :class:`Generator` instance with the " -"exact same options, and *fp* as the new *outfp*." -msgstr "" - -#: ../../library/email.generator.rst:222 -msgid "" -"Write *s* to the *write* method of the *outfp* passed to the :class:" -"`Generator`'s constructor. This provides just enough file-like API for :" -"class:`Generator` instances to be used in the :func:`print` function." -msgstr "" - -#: ../../library/email.generator.rst:228 -msgid "" -"As a convenience, :class:`~email.message.EmailMessage` provides the methods :" -"meth:`~email.message.EmailMessage.as_string` and ``str(aMessage)`` (a.k.a. :" -"meth:`~email.message.EmailMessage.__str__`), which simplify the generation " -"of a formatted string representation of a message object. For more detail, " -"see :mod:`email.message`." -msgstr "" - -#: ../../library/email.generator.rst:235 -msgid "" -"The :mod:`email.generator` module also provides a derived class, :class:" -"`DecodedGenerator`, which is like the :class:`Generator` base class, except " -"that non-\\ :mimetype:`text` parts are not serialized, but are instead " -"represented in the output stream by a string derived from a template filled " -"in with information about the part." -msgstr "" - -#: ../../library/email.generator.rst:244 -msgid "" -"Act like :class:`Generator`, except that for any subpart of the message " -"passed to :meth:`Generator.flatten`, if the subpart is of main type :" -"mimetype:`text`, print the decoded payload of the subpart, and if the main " -"type is not :mimetype:`text`, instead of printing it fill in the string " -"*fmt* using information from the part and print the resulting filled-in " -"string." -msgstr "" - -#: ../../library/email.generator.rst:251 -msgid "" -"To fill in *fmt*, execute ``fmt % part_info``, where ``part_info`` is a " -"dictionary composed of the following keys and values:" -msgstr "" - -#: ../../library/email.generator.rst:254 -msgid "``type`` -- Full MIME type of the non-\\ :mimetype:`text` part" -msgstr "" - -#: ../../library/email.generator.rst:256 -msgid "``maintype`` -- Main MIME type of the non-\\ :mimetype:`text` part" -msgstr "" - -#: ../../library/email.generator.rst:258 -msgid "``subtype`` -- Sub-MIME type of the non-\\ :mimetype:`text` part" -msgstr "" - -#: ../../library/email.generator.rst:260 -msgid "``filename`` -- Filename of the non-\\ :mimetype:`text` part" -msgstr "" - -#: ../../library/email.generator.rst:262 -msgid "" -"``description`` -- Description associated with the non-\\ :mimetype:`text` " -"part" -msgstr "" - -#: ../../library/email.generator.rst:264 -msgid "" -"``encoding`` -- Content transfer encoding of the non-\\ :mimetype:`text` part" -msgstr "" - -#: ../../library/email.generator.rst:266 -msgid "If *fmt* is ``None``, use the following default *fmt*:" -msgstr "" - -#: ../../library/email.generator.rst:268 -msgid "" -"\"[Non-text (%(type)s) part of message omitted, filename %(filename)s]\"" -msgstr "" - -#: ../../library/email.generator.rst:270 -msgid "" -"Optional *_mangle_from_* and *maxheaderlen* are as with the :class:" -"`Generator` base class." -msgstr "" - -#: ../../library/email.generator.rst:275 -msgid "Footnotes" -msgstr "註解" - -#: ../../library/email.generator.rst:276 -msgid "" -"This statement assumes that you use the appropriate setting for " -"``unixfrom``, and that there are no :mod:`email.policy` settings calling for " -"automatic adjustments (for example, :attr:`~email.policy.EmailPolicy." -"refold_source` must be ``none``, which is *not* the default). It is also " -"not 100% true, since if the message does not conform to the RFC standards " -"occasionally information about the exact original text is lost during " -"parsing error recovery. It is a goal to fix these latter edge cases when " -"possible." -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-09-23 07:52+0800\n" +"PO-Revision-Date: 2018-05-23 14:44+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/email.generator.rst:2 +msgid ":mod:`!email.generator`: Generating MIME documents" +msgstr ":mod:`!email.generator`：產生 MIME 文件" + +#: ../../library/email.generator.rst:7 +msgid "**Source code:** :source:`Lib/email/generator.py`" +msgstr "**原始碼：**\\ :source:`Lib/email/generator.py`" + +#: ../../library/email.generator.rst:11 +msgid "" +"One of the most common tasks is to generate the flat (serialized) version of " +"the email message represented by a message object structure. You will need " +"to do this if you want to send your message via :meth:`smtplib.SMTP." +"sendmail`, or print the message on the console. Taking a message object " +"structure and producing a serialized representation is the job of the " +"generator classes." +msgstr "" + +#: ../../library/email.generator.rst:18 +msgid "" +"As with the :mod:`email.parser` module, you aren't limited to the " +"functionality of the bundled generator; you could write one from scratch " +"yourself. However the bundled generator knows how to generate most email in " +"a standards-compliant way, should handle MIME and non-MIME email messages " +"just fine, and is designed so that the bytes-oriented parsing and generation " +"operations are inverses, assuming the same non-transforming :mod:`~email." +"policy` is used for both. That is, parsing the serialized byte stream via " +"the :class:`~email.parser.BytesParser` class and then regenerating the " +"serialized byte stream using :class:`BytesGenerator` should produce output " +"identical to the input [#]_. (On the other hand, using the generator on an :" +"class:`~email.message.EmailMessage` constructed by program may result in " +"changes to the :class:`~email.message.EmailMessage` object as defaults are " +"filled in.)" +msgstr "" + +#: ../../library/email.generator.rst:32 +msgid "" +"The :class:`Generator` class can be used to flatten a message into a text " +"(as opposed to binary) serialized representation, but since Unicode cannot " +"represent binary data directly, the message is of necessity transformed into " +"something that contains only ASCII characters, using the standard email RFC " +"Content Transfer Encoding techniques for encoding email messages for " +"transport over channels that are not \"8 bit clean\"." +msgstr "" + +#: ../../library/email.generator.rst:39 +msgid "" +"To accommodate reproducible processing of SMIME-signed messages :class:" +"`Generator` disables header folding for message parts of type ``multipart/" +"signed`` and all subparts." +msgstr "" + +#: ../../library/email.generator.rst:47 +msgid "" +"Return a :class:`BytesGenerator` object that will write any message provided " +"to the :meth:`flatten` method, or any surrogateescape encoded text provided " +"to the :meth:`write` method, to the :term:`file-like object` *outfp*. " +"*outfp* must support a ``write`` method that accepts binary data." +msgstr "" + +#: ../../library/email.generator.rst:52 ../../library/email.generator.rst:153 +msgid "" +"If optional *mangle_from_* is ``True``, put a ``>`` character in front of " +"any line in the body that starts with the exact string ``\"From \"``, that " +"is ``From`` followed by a space at the beginning of a line. *mangle_from_* " +"defaults to the value of the :attr:`~email.policy.Policy.mangle_from_` " +"setting of the *policy* (which is ``True`` for the :data:`~email.policy." +"compat32` policy and ``False`` for all others). *mangle_from_* is intended " +"for use when messages are stored in Unix mbox format (see :mod:`mailbox` and " +"`WHY THE CONTENT-LENGTH FORMAT IS BAD `_)." +msgstr "" + +#: ../../library/email.generator.rst:62 ../../library/email.generator.rst:163 +msgid "" +"If *maxheaderlen* is not ``None``, refold any header lines that are longer " +"than *maxheaderlen*, or if ``0``, do not rewrap any headers. If " +"*manheaderlen* is ``None`` (the default), wrap headers and other message " +"lines according to the *policy* settings." +msgstr "" + +#: ../../library/email.generator.rst:67 ../../library/email.generator.rst:168 +msgid "" +"If *policy* is specified, use that policy to control message generation. If " +"*policy* is ``None`` (the default), use the policy associated with the :" +"class:`~email.message.Message` or :class:`~email.message.EmailMessage` " +"object passed to ``flatten`` to control the message generation. See :mod:" +"`email.policy` for details on what *policy* controls." +msgstr "" + +#: ../../library/email.generator.rst:75 ../../library/email.generator.rst:174 +msgid "Added the *policy* keyword." +msgstr "新增關鍵字 *policy*。" + +#: ../../library/email.generator.rst:77 ../../library/email.generator.rst:176 +msgid "" +"The default behavior of the *mangle_from_* and *maxheaderlen* parameters is " +"to follow the policy." +msgstr "" + +#: ../../library/email.generator.rst:83 +msgid "" +"Print the textual representation of the message object structure rooted at " +"*msg* to the output file specified when the :class:`BytesGenerator` instance " +"was created." +msgstr "" + +#: ../../library/email.generator.rst:87 +msgid "" +"If the :mod:`~email.policy` option :attr:`~email.policy.Policy.cte_type` is " +"``8bit`` (the default), copy any headers in the original parsed message that " +"have not been modified to the output with any bytes with the high bit set " +"reproduced as in the original, and preserve the non-ASCII :mailheader:" +"`Content-Transfer-Encoding` of any body parts that have them. If " +"``cte_type`` is ``7bit``, convert the bytes with the high bit set as needed " +"using an ASCII-compatible :mailheader:`Content-Transfer-Encoding`. That is, " +"transform parts with non-ASCII :mailheader:`Content-Transfer-Encoding` (:" +"mailheader:`Content-Transfer-Encoding: 8bit`) to an ASCII compatible :" +"mailheader:`Content-Transfer-Encoding`, and encode RFC-invalid non-ASCII " +"bytes in headers using the MIME ``unknown-8bit`` character set, thus " +"rendering them RFC-compliant." +msgstr "" + +#: ../../library/email.generator.rst:104 ../../library/email.generator.rst:197 +msgid "" +"If *unixfrom* is ``True``, print the envelope header delimiter used by the " +"Unix mailbox format (see :mod:`mailbox`) before the first of the :rfc:`5322` " +"headers of the root message object. If the root object has no envelope " +"header, craft a standard one. The default is ``False``. Note that for " +"subparts, no envelope header is ever printed." +msgstr "" + +#: ../../library/email.generator.rst:110 ../../library/email.generator.rst:203 +msgid "" +"If *linesep* is not ``None``, use it as the separator character between all " +"the lines of the flattened message. If *linesep* is ``None`` (the default), " +"use the value specified in the *policy*." +msgstr "" + +#: ../../library/email.generator.rst:119 +msgid "" +"Return an independent clone of this :class:`BytesGenerator` instance with " +"the exact same option settings, and *fp* as the new *outfp*." +msgstr "" + +#: ../../library/email.generator.rst:125 +msgid "" +"Encode *s* using the ``ASCII`` codec and the ``surrogateescape`` error " +"handler, and pass it to the *write* method of the *outfp* passed to the :" +"class:`BytesGenerator`'s constructor." +msgstr "" + +#: ../../library/email.generator.rst:130 +msgid "" +"As a convenience, :class:`~email.message.EmailMessage` provides the methods :" +"meth:`~email.message.EmailMessage.as_bytes` and ``bytes(aMessage)`` (a.k.a. :" +"meth:`~email.message.EmailMessage.__bytes__`), which simplify the generation " +"of a serialized binary representation of a message object. For more detail, " +"see :mod:`email.message`." +msgstr "" + +#: ../../library/email.generator.rst:137 +msgid "" +"Because strings cannot represent binary data, the :class:`Generator` class " +"must convert any binary data in any message it flattens to an ASCII " +"compatible format, by converting them to an ASCII compatible :mailheader:" +"`Content-Transfer_Encoding`. Using the terminology of the email RFCs, you " +"can think of this as :class:`Generator` serializing to an I/O stream that is " +"not \"8 bit clean\". In other words, most applications will want to be " +"using :class:`BytesGenerator`, and not :class:`Generator`." +msgstr "" + +#: ../../library/email.generator.rst:148 +msgid "" +"Return a :class:`Generator` object that will write any message provided to " +"the :meth:`flatten` method, or any text provided to the :meth:`write` " +"method, to the :term:`file-like object` *outfp*. *outfp* must support a " +"``write`` method that accepts string data." +msgstr "" + +#: ../../library/email.generator.rst:182 +msgid "" +"Print the textual representation of the message object structure rooted at " +"*msg* to the output file specified when the :class:`Generator` instance was " +"created." +msgstr "" + +#: ../../library/email.generator.rst:186 +msgid "" +"If the :mod:`~email.policy` option :attr:`~email.policy.Policy.cte_type` is " +"``8bit``, generate the message as if the option were set to ``7bit``. (This " +"is required because strings cannot represent non-ASCII bytes.) Convert any " +"bytes with the high bit set as needed using an ASCII-compatible :mailheader:" +"`Content-Transfer-Encoding`. That is, transform parts with non-ASCII :" +"mailheader:`Content-Transfer-Encoding` (:mailheader:`Content-Transfer-" +"Encoding: 8bit`) to an ASCII compatible :mailheader:`Content-Transfer-" +"Encoding`, and encode RFC-invalid non-ASCII bytes in headers using the MIME " +"``unknown-8bit`` character set, thus rendering them RFC-compliant." +msgstr "" + +#: ../../library/email.generator.rst:209 +msgid "" +"Added support for re-encoding ``8bit`` message bodies, and the *linesep* " +"argument." +msgstr "" + +#: ../../library/email.generator.rst:216 +msgid "" +"Return an independent clone of this :class:`Generator` instance with the " +"exact same options, and *fp* as the new *outfp*." +msgstr "" + +#: ../../library/email.generator.rst:222 +msgid "" +"Write *s* to the *write* method of the *outfp* passed to the :class:" +"`Generator`'s constructor. This provides just enough file-like API for :" +"class:`Generator` instances to be used in the :func:`print` function." +msgstr "" + +#: ../../library/email.generator.rst:228 +msgid "" +"As a convenience, :class:`~email.message.EmailMessage` provides the methods :" +"meth:`~email.message.EmailMessage.as_string` and ``str(aMessage)`` (a.k.a. :" +"meth:`~email.message.EmailMessage.__str__`), which simplify the generation " +"of a formatted string representation of a message object. For more detail, " +"see :mod:`email.message`." +msgstr "" + +#: ../../library/email.generator.rst:235 +msgid "" +"The :mod:`email.generator` module also provides a derived class, :class:" +"`DecodedGenerator`, which is like the :class:`Generator` base class, except " +"that non-\\ :mimetype:`text` parts are not serialized, but are instead " +"represented in the output stream by a string derived from a template filled " +"in with information about the part." +msgstr "" + +#: ../../library/email.generator.rst:244 +msgid "" +"Act like :class:`Generator`, except that for any subpart of the message " +"passed to :meth:`Generator.flatten`, if the subpart is of main type :" +"mimetype:`text`, print the decoded payload of the subpart, and if the main " +"type is not :mimetype:`text`, instead of printing it fill in the string " +"*fmt* using information from the part and print the resulting filled-in " +"string." +msgstr "" + +#: ../../library/email.generator.rst:251 +msgid "" +"To fill in *fmt*, execute ``fmt % part_info``, where ``part_info`` is a " +"dictionary composed of the following keys and values:" +msgstr "" + +#: ../../library/email.generator.rst:254 +msgid "``type`` -- Full MIME type of the non-\\ :mimetype:`text` part" +msgstr "" + +#: ../../library/email.generator.rst:256 +msgid "``maintype`` -- Main MIME type of the non-\\ :mimetype:`text` part" +msgstr "" + +#: ../../library/email.generator.rst:258 +msgid "``subtype`` -- Sub-MIME type of the non-\\ :mimetype:`text` part" +msgstr "" + +#: ../../library/email.generator.rst:260 +msgid "``filename`` -- Filename of the non-\\ :mimetype:`text` part" +msgstr "" + +#: ../../library/email.generator.rst:262 +msgid "" +"``description`` -- Description associated with the non-\\ :mimetype:`text` " +"part" +msgstr "" + +#: ../../library/email.generator.rst:264 +msgid "" +"``encoding`` -- Content transfer encoding of the non-\\ :mimetype:`text` part" +msgstr "" + +#: ../../library/email.generator.rst:266 +msgid "If *fmt* is ``None``, use the following default *fmt*:" +msgstr "" + +#: ../../library/email.generator.rst:268 +msgid "" +"\"[Non-text (%(type)s) part of message omitted, filename %(filename)s]\"" +msgstr "" + +#: ../../library/email.generator.rst:270 +msgid "" +"Optional *_mangle_from_* and *maxheaderlen* are as with the :class:" +"`Generator` base class." +msgstr "" + +#: ../../library/email.generator.rst:275 +msgid "Footnotes" +msgstr "註解" + +#: ../../library/email.generator.rst:276 +msgid "" +"This statement assumes that you use the appropriate setting for " +"``unixfrom``, and that there are no :mod:`email.policy` settings calling for " +"automatic adjustments (for example, :attr:`~email.policy.EmailPolicy." +"refold_source` must be ``none``, which is *not* the default). It is also " +"not 100% true, since if the message does not conform to the RFC standards " +"occasionally information about the exact original text is lost during " +"parsing error recovery. It is a goal to fix these latter edge cases when " +"possible." +msgstr "" diff --git a/library/email.header.po b/library/email.header.po index 6cf77fc3c8..daa98a8537 100644 --- a/library/email.header.po +++ b/library/email.header.po @@ -1,349 +1,349 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-06-27 07:36+0000\n" -"PO-Revision-Date: 2018-05-23 14:44+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/email.header.rst:2 -msgid ":mod:`!email.header`: Internationalized headers" -msgstr ":mod:`!email.header`：國際化標頭" - -#: ../../library/email.header.rst:7 -msgid "**Source code:** :source:`Lib/email/header.py`" -msgstr "**原始碼：**\\ :source:`Lib/email/header.py`" - -#: ../../library/email.header.rst:11 -msgid "" -"This module is part of the legacy (``Compat32``) email API. In the current " -"API encoding and decoding of headers is handled transparently by the " -"dictionary-like API of the :class:`~email.message.EmailMessage` class. In " -"addition to uses in legacy code, this module can be useful in applications " -"that need to completely control the character sets used when encoding " -"headers." -msgstr "" - -#: ../../library/email.header.rst:17 -msgid "" -"The remaining text in this section is the original documentation of the " -"module." -msgstr "" - -#: ../../library/email.header.rst:19 -msgid "" -":rfc:`2822` is the base standard that describes the format of email " -"messages. It derives from the older :rfc:`822` standard which came into " -"widespread use at a time when most email was composed of ASCII characters " -"only. :rfc:`2822` is a specification written assuming email contains only 7-" -"bit ASCII characters." -msgstr "" - -#: ../../library/email.header.rst:24 -msgid "" -"Of course, as email has been deployed worldwide, it has become " -"internationalized, such that language specific character sets can now be " -"used in email messages. The base standard still requires email messages to " -"be transferred using only 7-bit ASCII characters, so a slew of RFCs have " -"been written describing how to encode email containing non-ASCII characters " -"into :rfc:`2822`\\ -compliant format. These RFCs include :rfc:`2045`, :rfc:" -"`2046`, :rfc:`2047`, and :rfc:`2231`. The :mod:`email` package supports " -"these standards in its :mod:`email.header` and :mod:`email.charset` modules." -msgstr "" - -#: ../../library/email.header.rst:33 -msgid "" -"If you want to include non-ASCII characters in your email headers, say in " -"the :mailheader:`Subject` or :mailheader:`To` fields, you should use the :" -"class:`Header` class and assign the field in the :class:`~email.message." -"Message` object to an instance of :class:`Header` instead of using a string " -"for the header value. Import the :class:`Header` class from the :mod:`email." -"header` module. For example::" -msgstr "" - -#: ../../library/email.header.rst:40 -msgid "" -">>> from email.message import Message\n" -">>> from email.header import Header\n" -">>> msg = Message()\n" -">>> h = Header('p\\xf6stal', 'iso-8859-1')\n" -">>> msg['Subject'] = h\n" -">>> msg.as_string()\n" -"'Subject: =?iso-8859-1?q?p=F6stal?=\\n\\n'" -msgstr "" -">>> from email.message import Message\n" -">>> from email.header import Header\n" -">>> msg = Message()\n" -">>> h = Header('p\\xf6stal', 'iso-8859-1')\n" -">>> msg['Subject'] = h\n" -">>> msg.as_string()\n" -"'Subject: =?iso-8859-1?q?p=F6stal?=\\n\\n'" - -#: ../../library/email.header.rst:50 -msgid "" -"Notice here how we wanted the :mailheader:`Subject` field to contain a non-" -"ASCII character? We did this by creating a :class:`Header` instance and " -"passing in the character set that the byte string was encoded in. When the " -"subsequent :class:`~email.message.Message` instance was flattened, the :" -"mailheader:`Subject` field was properly :rfc:`2047` encoded. MIME-aware " -"mail readers would show this header using the embedded ISO-8859-1 character." -msgstr "" - -#: ../../library/email.header.rst:57 -msgid "Here is the :class:`Header` class description:" -msgstr "" - -#: ../../library/email.header.rst:62 -msgid "" -"Create a MIME-compliant header that can contain strings in different " -"character sets." -msgstr "" - -#: ../../library/email.header.rst:65 -msgid "" -"Optional *s* is the initial header value. If ``None`` (the default), the " -"initial header value is not set. You can later append to the header with :" -"meth:`append` method calls. *s* may be an instance of :class:`bytes` or :" -"class:`str`, but see the :meth:`append` documentation for semantics." -msgstr "" - -#: ../../library/email.header.rst:70 -msgid "" -"Optional *charset* serves two purposes: it has the same meaning as the " -"*charset* argument to the :meth:`append` method. It also sets the default " -"character set for all subsequent :meth:`append` calls that omit the " -"*charset* argument. If *charset* is not provided in the constructor (the " -"default), the ``us-ascii`` character set is used both as *s*'s initial " -"charset and as the default for subsequent :meth:`append` calls." -msgstr "" - -#: ../../library/email.header.rst:77 -msgid "" -"The maximum line length can be specified explicitly via *maxlinelen*. For " -"splitting the first line to a shorter value (to account for the field header " -"which isn't included in *s*, e.g. :mailheader:`Subject`) pass in the name of " -"the field in *header_name*. The default *maxlinelen* is 78, and the default " -"value for *header_name* is ``None``, meaning it is not taken into account " -"for the first line of a long, split header." -msgstr "" - -#: ../../library/email.header.rst:84 -msgid "" -"Optional *continuation_ws* must be :rfc:`2822`\\ -compliant folding " -"whitespace, and is usually either a space or a hard tab character. This " -"character will be prepended to continuation lines. *continuation_ws* " -"defaults to a single space character." -msgstr "" - -#: ../../library/email.header.rst:89 -msgid "" -"Optional *errors* is passed straight through to the :meth:`append` method." -msgstr "" - -#: ../../library/email.header.rst:94 -msgid "Append the string *s* to the MIME header." -msgstr "" - -#: ../../library/email.header.rst:96 -msgid "" -"Optional *charset*, if given, should be a :class:`~email.charset.Charset` " -"instance (see :mod:`email.charset`) or the name of a character set, which " -"will be converted to a :class:`~email.charset.Charset` instance. A value of " -"``None`` (the default) means that the *charset* given in the constructor is " -"used." -msgstr "" - -#: ../../library/email.header.rst:102 -msgid "" -"*s* may be an instance of :class:`bytes` or :class:`str`. If it is an " -"instance of :class:`bytes`, then *charset* is the encoding of that byte " -"string, and a :exc:`UnicodeError` will be raised if the string cannot be " -"decoded with that character set." -msgstr "" - -#: ../../library/email.header.rst:107 -msgid "" -"If *s* is an instance of :class:`str`, then *charset* is a hint specifying " -"the character set of the characters in the string." -msgstr "" - -#: ../../library/email.header.rst:110 -msgid "" -"In either case, when producing an :rfc:`2822`\\ -compliant header using :rfc:" -"`2047` rules, the string will be encoded using the output codec of the " -"charset. If the string cannot be encoded using the output codec, a " -"UnicodeError will be raised." -msgstr "" - -#: ../../library/email.header.rst:115 -msgid "" -"Optional *errors* is passed as the errors argument to the decode call if *s* " -"is a byte string." -msgstr "" - -#: ../../library/email.header.rst:121 -msgid "" -"Encode a message header into an RFC-compliant format, possibly wrapping long " -"lines and encapsulating non-ASCII parts in base64 or quoted-printable " -"encodings." -msgstr "" - -#: ../../library/email.header.rst:125 -msgid "" -"Optional *splitchars* is a string containing characters which should be " -"given extra weight by the splitting algorithm during normal header " -"wrapping. This is in very rough support of :RFC:`2822`\\'s 'higher level " -"syntactic breaks': split points preceded by a splitchar are preferred " -"during line splitting, with the characters preferred in the order in which " -"they appear in the string. Space and tab may be included in the string to " -"indicate whether preference should be given to one over the other as a split " -"point when other split chars do not appear in the line being split. " -"Splitchars does not affect :RFC:`2047` encoded lines." -msgstr "" - -#: ../../library/email.header.rst:135 -msgid "" -"*maxlinelen*, if given, overrides the instance's value for the maximum line " -"length." -msgstr "" - -#: ../../library/email.header.rst:138 -msgid "" -"*linesep* specifies the characters used to separate the lines of the folded " -"header. It defaults to the most useful value for Python application code " -"(``\\n``), but ``\\r\\n`` can be specified in order to produce headers with " -"RFC-compliant line separators." -msgstr "" - -#: ../../library/email.header.rst:143 -msgid "Added the *linesep* argument." -msgstr "新增引數 *linesep*。" - -#: ../../library/email.header.rst:147 -msgid "" -"The :class:`Header` class also provides a number of methods to support " -"standard operators and built-in functions." -msgstr "" - -#: ../../library/email.header.rst:152 -msgid "" -"Returns an approximation of the :class:`Header` as a string, using an " -"unlimited line length. All pieces are converted to unicode using the " -"specified encoding and joined together appropriately. Any pieces with a " -"charset of ``'unknown-8bit'`` are decoded as ASCII using the ``'replace'`` " -"error handler." -msgstr "" - -#: ../../library/email.header.rst:158 -msgid "Added handling for the ``'unknown-8bit'`` charset." -msgstr "" - -#: ../../library/email.header.rst:164 -msgid "" -"This method allows you to compare two :class:`Header` instances for equality." -msgstr "" - -#: ../../library/email.header.rst:170 -msgid "" -"This method allows you to compare two :class:`Header` instances for " -"inequality." -msgstr "" - -#: ../../library/email.header.rst:173 -msgid "" -"The :mod:`email.header` module also provides the following convenient " -"functions." -msgstr "" - -#: ../../library/email.header.rst:178 -msgid "" -"Decode a message header value without converting the character set. The " -"header value is in *header*." -msgstr "" - -#: ../../library/email.header.rst:181 -msgid "For historical reasons, this function may return either:" -msgstr "" - -#: ../../library/email.header.rst:183 -msgid "" -"A list of pairs containing each of the decoded parts of the header, " -"``(decoded_bytes, charset)``, where *decoded_bytes* is always an instance " -"of :class:`bytes`, and *charset* is either:" -msgstr "" - -#: ../../library/email.header.rst:187 -msgid "A lower case string containing the name of the character set specified." -msgstr "" - -#: ../../library/email.header.rst:189 -msgid "``None`` for non-encoded parts of the header." -msgstr "" - -#: ../../library/email.header.rst:191 -msgid "" -"A list of length 1 containing a pair ``(string, None)``, where *string* is " -"always an instance of :class:`str`." -msgstr "" - -#: ../../library/email.header.rst:194 -msgid "" -"An :exc:`email.errors.HeaderParseError` may be raised when certain decoding " -"errors occur (e.g. a base64 decoding exception)." -msgstr "" - -#: ../../library/email.header.rst:197 -msgid "Here are examples:" -msgstr "以下為範例： ::" - -#: ../../library/email.header.rst:209 -msgid "" -"This function exists for backwards compatibility only. For new code, we " -"recommend using :class:`email.headerregistry.HeaderRegistry`." -msgstr "" - -#: ../../library/email.header.rst:215 -msgid "" -"Create a :class:`Header` instance from a sequence of pairs as returned by :" -"func:`decode_header`." -msgstr "" - -#: ../../library/email.header.rst:218 -msgid "" -":func:`decode_header` takes a header value string and returns a sequence of " -"pairs of the format ``(decoded_string, charset)`` where *charset* is the " -"name of the character set." -msgstr "" - -#: ../../library/email.header.rst:222 -msgid "" -"This function takes one of those sequence of pairs and returns a :class:" -"`Header` instance. Optional *maxlinelen*, *header_name*, and " -"*continuation_ws* are as in the :class:`Header` constructor." -msgstr "" - -#: ../../library/email.header.rst:228 -msgid "" -"This function exists for backwards compatibility only, and is not " -"recommended for use in new code." -msgstr "" - -#~ msgid "" -#~ ">>> from email.header import decode_header\n" -#~ ">>> decode_header('=?iso-8859-1?q?p=F6stal?=')\n" -#~ "[(b'p\\xf6stal', 'iso-8859-1')]" -#~ msgstr "" -#~ ">>> from email.header import decode_header\n" -#~ ">>> decode_header('=?iso-8859-1?q?p=F6stal?=')\n" -#~ "[(b'p\\xf6stal', 'iso-8859-1')]" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-06-27 07:36+0000\n" +"PO-Revision-Date: 2018-05-23 14:44+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/email.header.rst:2 +msgid ":mod:`!email.header`: Internationalized headers" +msgstr ":mod:`!email.header`：國際化標頭" + +#: ../../library/email.header.rst:7 +msgid "**Source code:** :source:`Lib/email/header.py`" +msgstr "**原始碼：**\\ :source:`Lib/email/header.py`" + +#: ../../library/email.header.rst:11 +msgid "" +"This module is part of the legacy (``Compat32``) email API. In the current " +"API encoding and decoding of headers is handled transparently by the " +"dictionary-like API of the :class:`~email.message.EmailMessage` class. In " +"addition to uses in legacy code, this module can be useful in applications " +"that need to completely control the character sets used when encoding " +"headers." +msgstr "" + +#: ../../library/email.header.rst:17 +msgid "" +"The remaining text in this section is the original documentation of the " +"module." +msgstr "" + +#: ../../library/email.header.rst:19 +msgid "" +":rfc:`2822` is the base standard that describes the format of email " +"messages. It derives from the older :rfc:`822` standard which came into " +"widespread use at a time when most email was composed of ASCII characters " +"only. :rfc:`2822` is a specification written assuming email contains only 7-" +"bit ASCII characters." +msgstr "" + +#: ../../library/email.header.rst:24 +msgid "" +"Of course, as email has been deployed worldwide, it has become " +"internationalized, such that language specific character sets can now be " +"used in email messages. The base standard still requires email messages to " +"be transferred using only 7-bit ASCII characters, so a slew of RFCs have " +"been written describing how to encode email containing non-ASCII characters " +"into :rfc:`2822`\\ -compliant format. These RFCs include :rfc:`2045`, :rfc:" +"`2046`, :rfc:`2047`, and :rfc:`2231`. The :mod:`email` package supports " +"these standards in its :mod:`email.header` and :mod:`email.charset` modules." +msgstr "" + +#: ../../library/email.header.rst:33 +msgid "" +"If you want to include non-ASCII characters in your email headers, say in " +"the :mailheader:`Subject` or :mailheader:`To` fields, you should use the :" +"class:`Header` class and assign the field in the :class:`~email.message." +"Message` object to an instance of :class:`Header` instead of using a string " +"for the header value. Import the :class:`Header` class from the :mod:`email." +"header` module. For example::" +msgstr "" + +#: ../../library/email.header.rst:40 +msgid "" +">>> from email.message import Message\n" +">>> from email.header import Header\n" +">>> msg = Message()\n" +">>> h = Header('p\\xf6stal', 'iso-8859-1')\n" +">>> msg['Subject'] = h\n" +">>> msg.as_string()\n" +"'Subject: =?iso-8859-1?q?p=F6stal?=\\n\\n'" +msgstr "" +">>> from email.message import Message\n" +">>> from email.header import Header\n" +">>> msg = Message()\n" +">>> h = Header('p\\xf6stal', 'iso-8859-1')\n" +">>> msg['Subject'] = h\n" +">>> msg.as_string()\n" +"'Subject: =?iso-8859-1?q?p=F6stal?=\\n\\n'" + +#: ../../library/email.header.rst:50 +msgid "" +"Notice here how we wanted the :mailheader:`Subject` field to contain a non-" +"ASCII character? We did this by creating a :class:`Header` instance and " +"passing in the character set that the byte string was encoded in. When the " +"subsequent :class:`~email.message.Message` instance was flattened, the :" +"mailheader:`Subject` field was properly :rfc:`2047` encoded. MIME-aware " +"mail readers would show this header using the embedded ISO-8859-1 character." +msgstr "" + +#: ../../library/email.header.rst:57 +msgid "Here is the :class:`Header` class description:" +msgstr "" + +#: ../../library/email.header.rst:62 +msgid "" +"Create a MIME-compliant header that can contain strings in different " +"character sets." +msgstr "" + +#: ../../library/email.header.rst:65 +msgid "" +"Optional *s* is the initial header value. If ``None`` (the default), the " +"initial header value is not set. You can later append to the header with :" +"meth:`append` method calls. *s* may be an instance of :class:`bytes` or :" +"class:`str`, but see the :meth:`append` documentation for semantics." +msgstr "" + +#: ../../library/email.header.rst:70 +msgid "" +"Optional *charset* serves two purposes: it has the same meaning as the " +"*charset* argument to the :meth:`append` method. It also sets the default " +"character set for all subsequent :meth:`append` calls that omit the " +"*charset* argument. If *charset* is not provided in the constructor (the " +"default), the ``us-ascii`` character set is used both as *s*'s initial " +"charset and as the default for subsequent :meth:`append` calls." +msgstr "" + +#: ../../library/email.header.rst:77 +msgid "" +"The maximum line length can be specified explicitly via *maxlinelen*. For " +"splitting the first line to a shorter value (to account for the field header " +"which isn't included in *s*, e.g. :mailheader:`Subject`) pass in the name of " +"the field in *header_name*. The default *maxlinelen* is 78, and the default " +"value for *header_name* is ``None``, meaning it is not taken into account " +"for the first line of a long, split header." +msgstr "" + +#: ../../library/email.header.rst:84 +msgid "" +"Optional *continuation_ws* must be :rfc:`2822`\\ -compliant folding " +"whitespace, and is usually either a space or a hard tab character. This " +"character will be prepended to continuation lines. *continuation_ws* " +"defaults to a single space character." +msgstr "" + +#: ../../library/email.header.rst:89 +msgid "" +"Optional *errors* is passed straight through to the :meth:`append` method." +msgstr "" + +#: ../../library/email.header.rst:94 +msgid "Append the string *s* to the MIME header." +msgstr "" + +#: ../../library/email.header.rst:96 +msgid "" +"Optional *charset*, if given, should be a :class:`~email.charset.Charset` " +"instance (see :mod:`email.charset`) or the name of a character set, which " +"will be converted to a :class:`~email.charset.Charset` instance. A value of " +"``None`` (the default) means that the *charset* given in the constructor is " +"used." +msgstr "" + +#: ../../library/email.header.rst:102 +msgid "" +"*s* may be an instance of :class:`bytes` or :class:`str`. If it is an " +"instance of :class:`bytes`, then *charset* is the encoding of that byte " +"string, and a :exc:`UnicodeError` will be raised if the string cannot be " +"decoded with that character set." +msgstr "" + +#: ../../library/email.header.rst:107 +msgid "" +"If *s* is an instance of :class:`str`, then *charset* is a hint specifying " +"the character set of the characters in the string." +msgstr "" + +#: ../../library/email.header.rst:110 +msgid "" +"In either case, when producing an :rfc:`2822`\\ -compliant header using :rfc:" +"`2047` rules, the string will be encoded using the output codec of the " +"charset. If the string cannot be encoded using the output codec, a " +"UnicodeError will be raised." +msgstr "" + +#: ../../library/email.header.rst:115 +msgid "" +"Optional *errors* is passed as the errors argument to the decode call if *s* " +"is a byte string." +msgstr "" + +#: ../../library/email.header.rst:121 +msgid "" +"Encode a message header into an RFC-compliant format, possibly wrapping long " +"lines and encapsulating non-ASCII parts in base64 or quoted-printable " +"encodings." +msgstr "" + +#: ../../library/email.header.rst:125 +msgid "" +"Optional *splitchars* is a string containing characters which should be " +"given extra weight by the splitting algorithm during normal header " +"wrapping. This is in very rough support of :RFC:`2822`\\'s 'higher level " +"syntactic breaks': split points preceded by a splitchar are preferred " +"during line splitting, with the characters preferred in the order in which " +"they appear in the string. Space and tab may be included in the string to " +"indicate whether preference should be given to one over the other as a split " +"point when other split chars do not appear in the line being split. " +"Splitchars does not affect :RFC:`2047` encoded lines." +msgstr "" + +#: ../../library/email.header.rst:135 +msgid "" +"*maxlinelen*, if given, overrides the instance's value for the maximum line " +"length." +msgstr "" + +#: ../../library/email.header.rst:138 +msgid "" +"*linesep* specifies the characters used to separate the lines of the folded " +"header. It defaults to the most useful value for Python application code " +"(``\\n``), but ``\\r\\n`` can be specified in order to produce headers with " +"RFC-compliant line separators." +msgstr "" + +#: ../../library/email.header.rst:143 +msgid "Added the *linesep* argument." +msgstr "新增引數 *linesep*。" + +#: ../../library/email.header.rst:147 +msgid "" +"The :class:`Header` class also provides a number of methods to support " +"standard operators and built-in functions." +msgstr "" + +#: ../../library/email.header.rst:152 +msgid "" +"Returns an approximation of the :class:`Header` as a string, using an " +"unlimited line length. All pieces are converted to unicode using the " +"specified encoding and joined together appropriately. Any pieces with a " +"charset of ``'unknown-8bit'`` are decoded as ASCII using the ``'replace'`` " +"error handler." +msgstr "" + +#: ../../library/email.header.rst:158 +msgid "Added handling for the ``'unknown-8bit'`` charset." +msgstr "" + +#: ../../library/email.header.rst:164 +msgid "" +"This method allows you to compare two :class:`Header` instances for equality." +msgstr "" + +#: ../../library/email.header.rst:170 +msgid "" +"This method allows you to compare two :class:`Header` instances for " +"inequality." +msgstr "" + +#: ../../library/email.header.rst:173 +msgid "" +"The :mod:`email.header` module also provides the following convenient " +"functions." +msgstr "" + +#: ../../library/email.header.rst:178 +msgid "" +"Decode a message header value without converting the character set. The " +"header value is in *header*." +msgstr "" + +#: ../../library/email.header.rst:181 +msgid "For historical reasons, this function may return either:" +msgstr "" + +#: ../../library/email.header.rst:183 +msgid "" +"A list of pairs containing each of the decoded parts of the header, " +"``(decoded_bytes, charset)``, where *decoded_bytes* is always an instance " +"of :class:`bytes`, and *charset* is either:" +msgstr "" + +#: ../../library/email.header.rst:187 +msgid "A lower case string containing the name of the character set specified." +msgstr "" + +#: ../../library/email.header.rst:189 +msgid "``None`` for non-encoded parts of the header." +msgstr "" + +#: ../../library/email.header.rst:191 +msgid "" +"A list of length 1 containing a pair ``(string, None)``, where *string* is " +"always an instance of :class:`str`." +msgstr "" + +#: ../../library/email.header.rst:194 +msgid "" +"An :exc:`email.errors.HeaderParseError` may be raised when certain decoding " +"errors occur (e.g. a base64 decoding exception)." +msgstr "" + +#: ../../library/email.header.rst:197 +msgid "Here are examples:" +msgstr "以下為範例： ::" + +#: ../../library/email.header.rst:209 +msgid "" +"This function exists for backwards compatibility only. For new code, we " +"recommend using :class:`email.headerregistry.HeaderRegistry`." +msgstr "" + +#: ../../library/email.header.rst:215 +msgid "" +"Create a :class:`Header` instance from a sequence of pairs as returned by :" +"func:`decode_header`." +msgstr "" + +#: ../../library/email.header.rst:218 +msgid "" +":func:`decode_header` takes a header value string and returns a sequence of " +"pairs of the format ``(decoded_string, charset)`` where *charset* is the " +"name of the character set." +msgstr "" + +#: ../../library/email.header.rst:222 +msgid "" +"This function takes one of those sequence of pairs and returns a :class:" +"`Header` instance. Optional *maxlinelen*, *header_name*, and " +"*continuation_ws* are as in the :class:`Header` constructor." +msgstr "" + +#: ../../library/email.header.rst:228 +msgid "" +"This function exists for backwards compatibility only, and is not " +"recommended for use in new code." +msgstr "" + +#~ msgid "" +#~ ">>> from email.header import decode_header\n" +#~ ">>> decode_header('=?iso-8859-1?q?p=F6stal?=')\n" +#~ "[(b'p\\xf6stal', 'iso-8859-1')]" +#~ msgstr "" +#~ ">>> from email.header import decode_header\n" +#~ ">>> decode_header('=?iso-8859-1?q?p=F6stal?=')\n" +#~ "[(b'p\\xf6stal', 'iso-8859-1')]" diff --git a/library/email.headerregistry.po b/library/email.headerregistry.po index 450f84fe06..2619fe8204 100644 --- a/library/email.headerregistry.po +++ b/library/email.headerregistry.po @@ -1,683 +1,683 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-09-27 00:14+0000\n" -"PO-Revision-Date: 2018-05-23 14:44+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/email.headerregistry.rst:2 -msgid ":mod:`!email.headerregistry`: Custom Header Objects" -msgstr ":mod:`!email.headerregistry`：自訂標頭物件" - -#: ../../library/email.headerregistry.rst:10 -msgid "**Source code:** :source:`Lib/email/headerregistry.py`" -msgstr "**原始碼：**\\ :source:`Lib/email/headerregistry.py`" - -#: ../../library/email.headerregistry.rst:14 -msgid "[1]_" -msgstr "[1]_" - -#: ../../library/email.headerregistry.rst:16 -msgid "" -"Headers are represented by customized subclasses of :class:`str`. The " -"particular class used to represent a given header is determined by the :attr:" -"`~email.policy.EmailPolicy.header_factory` of the :mod:`~email.policy` in " -"effect when the headers are created. This section documents the particular " -"``header_factory`` implemented by the email package for handling :RFC:`5322` " -"compliant email messages, which not only provides customized header objects " -"for various header types, but also provides an extension mechanism for " -"applications to add their own custom header types." -msgstr "" - -#: ../../library/email.headerregistry.rst:25 -msgid "" -"When using any of the policy objects derived from :data:`~email.policy." -"EmailPolicy`, all headers are produced by :class:`.HeaderRegistry` and have :" -"class:`.BaseHeader` as their last base class. Each header class has an " -"additional base class that is determined by the type of the header. For " -"example, many headers have the class :class:`.UnstructuredHeader` as their " -"other base class. The specialized second class for a header is determined " -"by the name of the header, using a lookup table stored in the :class:`." -"HeaderRegistry`. All of this is managed transparently for the typical " -"application program, but interfaces are provided for modifying the default " -"behavior for use by more complex applications." -msgstr "" - -#: ../../library/email.headerregistry.rst:36 -msgid "" -"The sections below first document the header base classes and their " -"attributes, followed by the API for modifying the behavior of :class:`." -"HeaderRegistry`, and finally the support classes used to represent the data " -"parsed from structured headers." -msgstr "" - -#: ../../library/email.headerregistry.rst:44 -msgid "" -"*name* and *value* are passed to ``BaseHeader`` from the :attr:`~email." -"policy.EmailPolicy.header_factory` call. The string value of any header " -"object is the *value* fully decoded to unicode." -msgstr "" - -#: ../../library/email.headerregistry.rst:48 -msgid "This base class defines the following read-only properties:" -msgstr "這個基底類別定義了以下唯讀屬性：" - -#: ../../library/email.headerregistry.rst:53 -msgid "" -"The name of the header (the portion of the field before the ':'). This is " -"exactly the value passed in the :attr:`~email.policy.EmailPolicy." -"header_factory` call for *name*; that is, case is preserved." -msgstr "" - -#: ../../library/email.headerregistry.rst:61 -msgid "" -"A tuple of :exc:`~email.errors.HeaderDefect` instances reporting any RFC " -"compliance problems found during parsing. The email package tries to be " -"complete about detecting compliance issues. See the :mod:`~email.errors` " -"module for a discussion of the types of defects that may be reported." -msgstr "" - -#: ../../library/email.headerregistry.rst:69 -msgid "" -"The maximum number of headers of this type that can have the same ``name``. " -"A value of ``None`` means unlimited. The ``BaseHeader`` value for this " -"attribute is ``None``; it is expected that specialized header classes will " -"override this value as needed." -msgstr "" - -#: ../../library/email.headerregistry.rst:74 -msgid "" -"``BaseHeader`` also provides the following method, which is called by the " -"email library code and should not in general be called by application " -"programs:" -msgstr "" - -#: ../../library/email.headerregistry.rst:80 -msgid "" -"Return a string containing :attr:`~email.policy.Policy.linesep` characters " -"as required to correctly fold the header according to *policy*. A :attr:" -"`~email.policy.Policy.cte_type` of ``8bit`` will be treated as if it were " -"``7bit``, since headers may not contain arbitrary binary data. If :attr:" -"`~email.policy.EmailPolicy.utf8` is ``False``, non-ASCII data will be :rfc:" -"`2047` encoded." -msgstr "" - -#: ../../library/email.headerregistry.rst:88 -msgid "" -"``BaseHeader`` by itself cannot be used to create a header object. It " -"defines a protocol that each specialized header cooperates with in order to " -"produce the header object. Specifically, ``BaseHeader`` requires that the " -"specialized class provide a :func:`classmethod` named ``parse``. This " -"method is called as follows::" -msgstr "" - -#: ../../library/email.headerregistry.rst:94 -msgid "parse(string, kwds)" -msgstr "parse(string, kwds)" - -#: ../../library/email.headerregistry.rst:96 -msgid "" -"``kwds`` is a dictionary containing one pre-initialized key, ``defects``. " -"``defects`` is an empty list. The parse method should append any detected " -"defects to this list. On return, the ``kwds`` dictionary *must* contain " -"values for at least the keys ``decoded`` and ``defects``. ``decoded`` " -"should be the string value for the header (that is, the header value fully " -"decoded to unicode). The parse method should assume that *string* may " -"contain content-transfer-encoded parts, but should correctly handle all " -"valid unicode characters as well so that it can parse un-encoded header " -"values." -msgstr "" - -#: ../../library/email.headerregistry.rst:105 -msgid "" -"``BaseHeader``'s ``__new__`` then creates the header instance, and calls its " -"``init`` method. The specialized class only needs to provide an ``init`` " -"method if it wishes to set additional attributes beyond those provided by " -"``BaseHeader`` itself. Such an ``init`` method should look like this::" -msgstr "" - -#: ../../library/email.headerregistry.rst:110 -msgid "" -"def init(self, /, *args, **kw):\n" -" self._myattr = kw.pop('myattr')\n" -" super().init(*args, **kw)" -msgstr "" -"def init(self, /, *args, **kw):\n" -" self._myattr = kw.pop('myattr')\n" -" super().init(*args, **kw)" - -#: ../../library/email.headerregistry.rst:114 -msgid "" -"That is, anything extra that the specialized class puts in to the ``kwds`` " -"dictionary should be removed and handled, and the remaining contents of " -"``kw`` (and ``args``) passed to the ``BaseHeader`` ``init`` method." -msgstr "" - -#: ../../library/email.headerregistry.rst:121 -msgid "" -"An \"unstructured\" header is the default type of header in :rfc:`5322`. Any " -"header that does not have a specified syntax is treated as unstructured. " -"The classic example of an unstructured header is the :mailheader:`Subject` " -"header." -msgstr "" - -#: ../../library/email.headerregistry.rst:126 -msgid "" -"In :rfc:`5322`, an unstructured header is a run of arbitrary text in the " -"ASCII character set. :rfc:`2047`, however, has an :rfc:`5322` compatible " -"mechanism for encoding non-ASCII text as ASCII characters within a header " -"value. When a *value* containing encoded words is passed to the " -"constructor, the ``UnstructuredHeader`` parser converts such encoded words " -"into unicode, following the :rfc:`2047` rules for unstructured text. The " -"parser uses heuristics to attempt to decode certain non-compliant encoded " -"words. Defects are registered in such cases, as well as defects for issues " -"such as invalid characters within the encoded words or the non-encoded text." -msgstr "" - -#: ../../library/email.headerregistry.rst:136 -msgid "This header type provides no additional attributes." -msgstr "" - -#: ../../library/email.headerregistry.rst:141 -msgid "" -":rfc:`5322` specifies a very specific format for dates within email headers. " -"The ``DateHeader`` parser recognizes that date format, as well as " -"recognizing a number of variant forms that are sometimes found \"in the " -"wild\"." -msgstr "" - -#: ../../library/email.headerregistry.rst:146 -#: ../../library/email.headerregistry.rst:188 -msgid "This header type provides the following additional attributes:" -msgstr "" - -#: ../../library/email.headerregistry.rst:150 -msgid "" -"If the header value can be recognized as a valid date of one form or " -"another, this attribute will contain a :class:`~datetime.datetime` instance " -"representing that date. If the timezone of the input date is specified as " -"``-0000`` (indicating it is in UTC but contains no information about the " -"source timezone), then :attr:`.datetime` will be a naive :class:`~datetime." -"datetime`. If a specific timezone offset is found (including ``+0000``), " -"then :attr:`.datetime` will contain an aware ``datetime`` that uses :class:" -"`datetime.timezone` to record the timezone offset." -msgstr "" - -#: ../../library/email.headerregistry.rst:160 -msgid "" -"The ``decoded`` value of the header is determined by formatting the " -"``datetime`` according to the :rfc:`5322` rules; that is, it is set to::" -msgstr "" - -#: ../../library/email.headerregistry.rst:163 -msgid "email.utils.format_datetime(self.datetime)" -msgstr "" - -#: ../../library/email.headerregistry.rst:165 -msgid "" -"When creating a ``DateHeader``, *value* may be :class:`~datetime.datetime` " -"instance. This means, for example, that the following code is valid and " -"does what one would expect::" -msgstr "" - -#: ../../library/email.headerregistry.rst:169 -msgid "msg['Date'] = datetime(2011, 7, 15, 21)" -msgstr "msg['Date'] = datetime(2011, 7, 15, 21)" - -#: ../../library/email.headerregistry.rst:171 -msgid "" -"Because this is a naive ``datetime`` it will be interpreted as a UTC " -"timestamp, and the resulting value will have a timezone of ``-0000``. Much " -"more useful is to use the :func:`~email.utils.localtime` function from the :" -"mod:`~email.utils` module::" -msgstr "" - -#: ../../library/email.headerregistry.rst:176 -msgid "msg['Date'] = utils.localtime()" -msgstr "msg['Date'] = utils.localtime()" - -#: ../../library/email.headerregistry.rst:178 -msgid "" -"This example sets the date header to the current time and date using the " -"current timezone offset." -msgstr "" - -#: ../../library/email.headerregistry.rst:184 -msgid "" -"Address headers are one of the most complex structured header types. The " -"``AddressHeader`` class provides a generic interface to any address header." -msgstr "" - -#: ../../library/email.headerregistry.rst:193 -msgid "" -"A tuple of :class:`.Group` objects encoding the addresses and groups found " -"in the header value. Addresses that are not part of a group are represented " -"in this list as single-address ``Groups`` whose :attr:`~.Group.display_name` " -"is ``None``." -msgstr "" - -#: ../../library/email.headerregistry.rst:201 -msgid "" -"A tuple of :class:`.Address` objects encoding all of the individual " -"addresses from the header value. If the header value contains any groups, " -"the individual addresses from the group are included in the list at the " -"point where the group occurs in the value (that is, the list of addresses is " -"\"flattened\" into a one dimensional list)." -msgstr "" - -#: ../../library/email.headerregistry.rst:207 -msgid "" -"The ``decoded`` value of the header will have all encoded words decoded to " -"unicode. :class:`~encodings.idna` encoded domain names are also decoded to " -"unicode. The ``decoded`` value is set by :ref:`joining ` " -"the :class:`str` value of the elements of the ``groups`` attribute with ``', " -"'``." -msgstr "" - -#: ../../library/email.headerregistry.rst:213 -msgid "" -"A list of :class:`.Address` and :class:`.Group` objects in any combination " -"may be used to set the value of an address header. ``Group`` objects whose " -"``display_name`` is ``None`` will be interpreted as single addresses, which " -"allows an address list to be copied with groups intact by using the list " -"obtained from the ``groups`` attribute of the source header." -msgstr "" - -#: ../../library/email.headerregistry.rst:222 -msgid "" -"A subclass of :class:`.AddressHeader` that adds one additional attribute:" -msgstr "" - -#: ../../library/email.headerregistry.rst:228 -msgid "" -"The single address encoded by the header value. If the header value " -"actually contains more than one address (which would be a violation of the " -"RFC under the default :mod:`~email.policy`), accessing this attribute will " -"result in a :exc:`ValueError`." -msgstr "" - -#: ../../library/email.headerregistry.rst:234 -msgid "" -"Many of the above classes also have a ``Unique`` variant (for example, " -"``UniqueUnstructuredHeader``). The only difference is that in the " -"``Unique`` variant, :attr:`~.BaseHeader.max_count` is set to 1." -msgstr "" - -#: ../../library/email.headerregistry.rst:241 -msgid "" -"There is really only one valid value for the :mailheader:`MIME-Version` " -"header, and that is ``1.0``. For future proofing, this header class " -"supports other valid version numbers. If a version number has a valid value " -"per :rfc:`2045`, then the header object will have non-``None`` values for " -"the following attributes:" -msgstr "" - -#: ../../library/email.headerregistry.rst:249 -msgid "" -"The version number as a string, with any whitespace and/or comments removed." -msgstr "" - -#: ../../library/email.headerregistry.rst:254 -msgid "The major version number as an integer" -msgstr "" - -#: ../../library/email.headerregistry.rst:258 -msgid "The minor version number as an integer" -msgstr "" - -#: ../../library/email.headerregistry.rst:263 -msgid "" -"MIME headers all start with the prefix 'Content-'. Each specific header has " -"a certain value, described under the class for that header. Some can also " -"take a list of supplemental parameters, which have a common format. This " -"class serves as a base for all the MIME headers that take parameters." -msgstr "" - -#: ../../library/email.headerregistry.rst:270 -msgid "A dictionary mapping parameter names to parameter values." -msgstr "" - -#: ../../library/email.headerregistry.rst:275 -msgid "" -"A :class:`ParameterizedMIMEHeader` class that handles the :mailheader:" -"`Content-Type` header." -msgstr "" - -#: ../../library/email.headerregistry.rst:280 -msgid "The content type string, in the form ``maintype/subtype``." -msgstr "" - -#: ../../library/email.headerregistry.rst:289 -msgid "" -"A :class:`ParameterizedMIMEHeader` class that handles the :mailheader:" -"`Content-Disposition` header." -msgstr "" - -#: ../../library/email.headerregistry.rst:294 -msgid "``inline`` and ``attachment`` are the only valid values in common use." -msgstr "" - -#: ../../library/email.headerregistry.rst:299 -msgid "Handles the :mailheader:`Content-Transfer-Encoding` header." -msgstr "" - -#: ../../library/email.headerregistry.rst:303 -msgid "" -"Valid values are ``7bit``, ``8bit``, ``base64``, and ``quoted-printable``. " -"See :rfc:`2045` for more information." -msgstr "" - -#: ../../library/email.headerregistry.rst:312 -msgid "" -"This is the factory used by :class:`~email.policy.EmailPolicy` by default. " -"``HeaderRegistry`` builds the class used to create a header instance " -"dynamically, using *base_class* and a specialized class retrieved from a " -"registry that it holds. When a given header name does not appear in the " -"registry, the class specified by *default_class* is used as the specialized " -"class. When *use_default_map* is ``True`` (the default), the standard " -"mapping of header names to classes is copied in to the registry during " -"initialization. *base_class* is always the last class in the generated " -"class's :class:`~type.__bases__` list." -msgstr "" - -#: ../../library/email.headerregistry.rst:322 -msgid "The default mappings are:" -msgstr "" - -#: ../../library/email.headerregistry.rst:0 -msgid "subject" -msgstr "subject" - -#: ../../library/email.headerregistry.rst:324 -msgid "UniqueUnstructuredHeader" -msgstr "UniqueUnstructuredHeader" - -#: ../../library/email.headerregistry.rst:0 -msgid "date" -msgstr "date" - -#: ../../library/email.headerregistry.rst:325 -#: ../../library/email.headerregistry.rst:327 -msgid "UniqueDateHeader" -msgstr "UniqueDateHeader" - -#: ../../library/email.headerregistry.rst:0 -msgid "resent-date" -msgstr "resent-date" - -#: ../../library/email.headerregistry.rst:326 -msgid "DateHeader" -msgstr "DateHeader" - -#: ../../library/email.headerregistry.rst:0 -msgid "orig-date" -msgstr "orig-date" - -#: ../../library/email.headerregistry.rst:0 -msgid "sender" -msgstr "sender" - -#: ../../library/email.headerregistry.rst:328 -msgid "UniqueSingleAddressHeader" -msgstr "UniqueSingleAddressHeader" - -#: ../../library/email.headerregistry.rst:0 -msgid "resent-sender" -msgstr "resent-sender" - -#: ../../library/email.headerregistry.rst:329 -msgid "SingleAddressHeader" -msgstr "SingleAddressHeader" - -#: ../../library/email.headerregistry.rst:0 -msgid "to" -msgstr "to" - -#: ../../library/email.headerregistry.rst:330 -#: ../../library/email.headerregistry.rst:332 -#: ../../library/email.headerregistry.rst:334 -#: ../../library/email.headerregistry.rst:336 -#: ../../library/email.headerregistry.rst:338 -msgid "UniqueAddressHeader" -msgstr "UniqueAddressHeader" - -#: ../../library/email.headerregistry.rst:0 -msgid "resent-to" -msgstr "resent-to" - -#: ../../library/email.headerregistry.rst:331 -#: ../../library/email.headerregistry.rst:333 -#: ../../library/email.headerregistry.rst:335 -#: ../../library/email.headerregistry.rst:337 -msgid "AddressHeader" -msgstr "AddressHeader" - -#: ../../library/email.headerregistry.rst:0 -msgid "cc" -msgstr "cc" - -#: ../../library/email.headerregistry.rst:0 -msgid "resent-cc" -msgstr "resent-cc" - -#: ../../library/email.headerregistry.rst:0 -msgid "bcc" -msgstr "bcc" - -#: ../../library/email.headerregistry.rst:0 -msgid "resent-bcc" -msgstr "resent-bcc" - -#: ../../library/email.headerregistry.rst:0 -msgid "from" -msgstr "from" - -#: ../../library/email.headerregistry.rst:0 -msgid "resent-from" -msgstr "resent-from" - -#: ../../library/email.headerregistry.rst:0 -msgid "reply-to" -msgstr "reply-to" - -#: ../../library/email.headerregistry.rst:0 -msgid "mime-version" -msgstr "mime-version" - -#: ../../library/email.headerregistry.rst:339 -msgid "MIMEVersionHeader" -msgstr "MIMEVersionHeader" - -#: ../../library/email.headerregistry.rst:0 -msgid "content-type" -msgstr "content-type" - -#: ../../library/email.headerregistry.rst:340 -msgid "ContentTypeHeader" -msgstr "ContentTypeHeader" - -#: ../../library/email.headerregistry.rst:0 -msgid "content-disposition" -msgstr "content-disposition" - -#: ../../library/email.headerregistry.rst:341 -msgid "ContentDispositionHeader" -msgstr "ContentDispositionHeader" - -#: ../../library/email.headerregistry.rst:0 -msgid "content-transfer-encoding" -msgstr "content-transfer-encoding" - -#: ../../library/email.headerregistry.rst:342 -msgid "ContentTransferEncodingHeader" -msgstr "ContentTransferEncodingHeader" - -#: ../../library/email.headerregistry.rst:0 -msgid "message-id" -msgstr "message-id" - -#: ../../library/email.headerregistry.rst:343 -msgid "MessageIDHeader" -msgstr "MessageIDHeader" - -#: ../../library/email.headerregistry.rst:345 -msgid "``HeaderRegistry`` has the following methods:" -msgstr "``HeaderRegistry`` 有以下方法：" - -#: ../../library/email.headerregistry.rst:350 -msgid "" -"*name* is the name of the header to be mapped. It will be converted to " -"lower case in the registry. *cls* is the specialized class to be used, " -"along with *base_class*, to create the class used to instantiate headers " -"that match *name*." -msgstr "" - -#: ../../library/email.headerregistry.rst:358 -msgid "Construct and return a class to handle creating a *name* header." -msgstr "" - -#: ../../library/email.headerregistry.rst:363 -msgid "" -"Retrieves the specialized header associated with *name* from the registry " -"(using *default_class* if *name* does not appear in the registry) and " -"composes it with *base_class* to produce a class, calls the constructed " -"class's constructor, passing it the same argument list, and finally returns " -"the class instance created thereby." -msgstr "" - -#: ../../library/email.headerregistry.rst:370 -msgid "" -"The following classes are the classes used to represent data parsed from " -"structured headers and can, in general, be used by an application program to " -"construct structured values to assign to specific headers." -msgstr "" - -#: ../../library/email.headerregistry.rst:377 -msgid "" -"The class used to represent an email address. The general form of an " -"address is::" -msgstr "" - -#: ../../library/email.headerregistry.rst:380 -msgid "[display_name] " -msgstr "[display_name] " - -#: ../../library/email.headerregistry.rst:382 -msgid "or::" -msgstr "或是： ::" - -#: ../../library/email.headerregistry.rst:384 -msgid "username@domain" -msgstr "username@domain" - -#: ../../library/email.headerregistry.rst:386 -msgid "" -"where each part must conform to specific syntax rules spelled out in :rfc:" -"`5322`." -msgstr "" - -#: ../../library/email.headerregistry.rst:389 -msgid "" -"As a convenience *addr_spec* can be specified instead of *username* and " -"*domain*, in which case *username* and *domain* will be parsed from the " -"*addr_spec*. An *addr_spec* must be a properly RFC quoted string; if it is " -"not ``Address`` will raise an error. Unicode characters are allowed and " -"will be property encoded when serialized. However, per the RFCs, unicode is " -"*not* allowed in the username portion of the address." -msgstr "" - -#: ../../library/email.headerregistry.rst:398 -msgid "" -"The display name portion of the address, if any, with all quoting removed. " -"If the address does not have a display name, this attribute will be an empty " -"string." -msgstr "" - -#: ../../library/email.headerregistry.rst:404 -msgid "The ``username`` portion of the address, with all quoting removed." -msgstr "" - -#: ../../library/email.headerregistry.rst:408 -msgid "The ``domain`` portion of the address." -msgstr "" - -#: ../../library/email.headerregistry.rst:412 -msgid "" -"The ``username@domain`` portion of the address, correctly quoted for use as " -"a bare address (the second form shown above). This attribute is not mutable." -msgstr "" - -#: ../../library/email.headerregistry.rst:418 -msgid "" -"The ``str`` value of the object is the address quoted according to :rfc:" -"`5322` rules, but with no Content Transfer Encoding of any non-ASCII " -"characters." -msgstr "" - -#: ../../library/email.headerregistry.rst:422 -msgid "" -"To support SMTP (:rfc:`5321`), ``Address`` handles one special case: if " -"``username`` and ``domain`` are both the empty string (or ``None``), then " -"the string value of the ``Address`` is ``<>``." -msgstr "" - -#: ../../library/email.headerregistry.rst:429 -msgid "" -"The class used to represent an address group. The general form of an " -"address group is::" -msgstr "" - -#: ../../library/email.headerregistry.rst:432 -msgid "display_name: [address-list];" -msgstr "display_name: [address-list];" - -#: ../../library/email.headerregistry.rst:434 -msgid "" -"As a convenience for processing lists of addresses that consist of a mixture " -"of groups and single addresses, a ``Group`` may also be used to represent " -"single addresses that are not part of a group by setting *display_name* to " -"``None`` and providing a list of the single address as *addresses*." -msgstr "" - -#: ../../library/email.headerregistry.rst:441 -msgid "" -"The ``display_name`` of the group. If it is ``None`` and there is exactly " -"one ``Address`` in ``addresses``, then the ``Group`` represents a single " -"address that is not in a group." -msgstr "" - -#: ../../library/email.headerregistry.rst:447 -msgid "" -"A possibly empty tuple of :class:`.Address` objects representing the " -"addresses in the group." -msgstr "" - -#: ../../library/email.headerregistry.rst:452 -msgid "" -"The ``str`` value of a ``Group`` is formatted according to :rfc:`5322`, but " -"with no Content Transfer Encoding of any non-ASCII characters. If " -"``display_name`` is none and there is a single ``Address`` in the " -"``addresses`` list, the ``str`` value will be the same as the ``str`` of " -"that single ``Address``." -msgstr "" - -#: ../../library/email.headerregistry.rst:460 -msgid "Footnotes" -msgstr "註解" - -#: ../../library/email.headerregistry.rst:461 -msgid "" -"Originally added in 3.3 as a :term:`provisional module `" -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-09-27 00:14+0000\n" +"PO-Revision-Date: 2018-05-23 14:44+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/email.headerregistry.rst:2 +msgid ":mod:`!email.headerregistry`: Custom Header Objects" +msgstr ":mod:`!email.headerregistry`：自訂標頭物件" + +#: ../../library/email.headerregistry.rst:10 +msgid "**Source code:** :source:`Lib/email/headerregistry.py`" +msgstr "**原始碼：**\\ :source:`Lib/email/headerregistry.py`" + +#: ../../library/email.headerregistry.rst:14 +msgid "[1]_" +msgstr "[1]_" + +#: ../../library/email.headerregistry.rst:16 +msgid "" +"Headers are represented by customized subclasses of :class:`str`. The " +"particular class used to represent a given header is determined by the :attr:" +"`~email.policy.EmailPolicy.header_factory` of the :mod:`~email.policy` in " +"effect when the headers are created. This section documents the particular " +"``header_factory`` implemented by the email package for handling :RFC:`5322` " +"compliant email messages, which not only provides customized header objects " +"for various header types, but also provides an extension mechanism for " +"applications to add their own custom header types." +msgstr "" + +#: ../../library/email.headerregistry.rst:25 +msgid "" +"When using any of the policy objects derived from :data:`~email.policy." +"EmailPolicy`, all headers are produced by :class:`.HeaderRegistry` and have :" +"class:`.BaseHeader` as their last base class. Each header class has an " +"additional base class that is determined by the type of the header. For " +"example, many headers have the class :class:`.UnstructuredHeader` as their " +"other base class. The specialized second class for a header is determined " +"by the name of the header, using a lookup table stored in the :class:`." +"HeaderRegistry`. All of this is managed transparently for the typical " +"application program, but interfaces are provided for modifying the default " +"behavior for use by more complex applications." +msgstr "" + +#: ../../library/email.headerregistry.rst:36 +msgid "" +"The sections below first document the header base classes and their " +"attributes, followed by the API for modifying the behavior of :class:`." +"HeaderRegistry`, and finally the support classes used to represent the data " +"parsed from structured headers." +msgstr "" + +#: ../../library/email.headerregistry.rst:44 +msgid "" +"*name* and *value* are passed to ``BaseHeader`` from the :attr:`~email." +"policy.EmailPolicy.header_factory` call. The string value of any header " +"object is the *value* fully decoded to unicode." +msgstr "" + +#: ../../library/email.headerregistry.rst:48 +msgid "This base class defines the following read-only properties:" +msgstr "這個基底類別定義了以下唯讀屬性：" + +#: ../../library/email.headerregistry.rst:53 +msgid "" +"The name of the header (the portion of the field before the ':'). This is " +"exactly the value passed in the :attr:`~email.policy.EmailPolicy." +"header_factory` call for *name*; that is, case is preserved." +msgstr "" + +#: ../../library/email.headerregistry.rst:61 +msgid "" +"A tuple of :exc:`~email.errors.HeaderDefect` instances reporting any RFC " +"compliance problems found during parsing. The email package tries to be " +"complete about detecting compliance issues. See the :mod:`~email.errors` " +"module for a discussion of the types of defects that may be reported." +msgstr "" + +#: ../../library/email.headerregistry.rst:69 +msgid "" +"The maximum number of headers of this type that can have the same ``name``. " +"A value of ``None`` means unlimited. The ``BaseHeader`` value for this " +"attribute is ``None``; it is expected that specialized header classes will " +"override this value as needed." +msgstr "" + +#: ../../library/email.headerregistry.rst:74 +msgid "" +"``BaseHeader`` also provides the following method, which is called by the " +"email library code and should not in general be called by application " +"programs:" +msgstr "" + +#: ../../library/email.headerregistry.rst:80 +msgid "" +"Return a string containing :attr:`~email.policy.Policy.linesep` characters " +"as required to correctly fold the header according to *policy*. A :attr:" +"`~email.policy.Policy.cte_type` of ``8bit`` will be treated as if it were " +"``7bit``, since headers may not contain arbitrary binary data. If :attr:" +"`~email.policy.EmailPolicy.utf8` is ``False``, non-ASCII data will be :rfc:" +"`2047` encoded." +msgstr "" + +#: ../../library/email.headerregistry.rst:88 +msgid "" +"``BaseHeader`` by itself cannot be used to create a header object. It " +"defines a protocol that each specialized header cooperates with in order to " +"produce the header object. Specifically, ``BaseHeader`` requires that the " +"specialized class provide a :func:`classmethod` named ``parse``. This " +"method is called as follows::" +msgstr "" + +#: ../../library/email.headerregistry.rst:94 +msgid "parse(string, kwds)" +msgstr "parse(string, kwds)" + +#: ../../library/email.headerregistry.rst:96 +msgid "" +"``kwds`` is a dictionary containing one pre-initialized key, ``defects``. " +"``defects`` is an empty list. The parse method should append any detected " +"defects to this list. On return, the ``kwds`` dictionary *must* contain " +"values for at least the keys ``decoded`` and ``defects``. ``decoded`` " +"should be the string value for the header (that is, the header value fully " +"decoded to unicode). The parse method should assume that *string* may " +"contain content-transfer-encoded parts, but should correctly handle all " +"valid unicode characters as well so that it can parse un-encoded header " +"values." +msgstr "" + +#: ../../library/email.headerregistry.rst:105 +msgid "" +"``BaseHeader``'s ``__new__`` then creates the header instance, and calls its " +"``init`` method. The specialized class only needs to provide an ``init`` " +"method if it wishes to set additional attributes beyond those provided by " +"``BaseHeader`` itself. Such an ``init`` method should look like this::" +msgstr "" + +#: ../../library/email.headerregistry.rst:110 +msgid "" +"def init(self, /, *args, **kw):\n" +" self._myattr = kw.pop('myattr')\n" +" super().init(*args, **kw)" +msgstr "" +"def init(self, /, *args, **kw):\n" +" self._myattr = kw.pop('myattr')\n" +" super().init(*args, **kw)" + +#: ../../library/email.headerregistry.rst:114 +msgid "" +"That is, anything extra that the specialized class puts in to the ``kwds`` " +"dictionary should be removed and handled, and the remaining contents of " +"``kw`` (and ``args``) passed to the ``BaseHeader`` ``init`` method." +msgstr "" + +#: ../../library/email.headerregistry.rst:121 +msgid "" +"An \"unstructured\" header is the default type of header in :rfc:`5322`. Any " +"header that does not have a specified syntax is treated as unstructured. " +"The classic example of an unstructured header is the :mailheader:`Subject` " +"header." +msgstr "" + +#: ../../library/email.headerregistry.rst:126 +msgid "" +"In :rfc:`5322`, an unstructured header is a run of arbitrary text in the " +"ASCII character set. :rfc:`2047`, however, has an :rfc:`5322` compatible " +"mechanism for encoding non-ASCII text as ASCII characters within a header " +"value. When a *value* containing encoded words is passed to the " +"constructor, the ``UnstructuredHeader`` parser converts such encoded words " +"into unicode, following the :rfc:`2047` rules for unstructured text. The " +"parser uses heuristics to attempt to decode certain non-compliant encoded " +"words. Defects are registered in such cases, as well as defects for issues " +"such as invalid characters within the encoded words or the non-encoded text." +msgstr "" + +#: ../../library/email.headerregistry.rst:136 +msgid "This header type provides no additional attributes." +msgstr "" + +#: ../../library/email.headerregistry.rst:141 +msgid "" +":rfc:`5322` specifies a very specific format for dates within email headers. " +"The ``DateHeader`` parser recognizes that date format, as well as " +"recognizing a number of variant forms that are sometimes found \"in the " +"wild\"." +msgstr "" + +#: ../../library/email.headerregistry.rst:146 +#: ../../library/email.headerregistry.rst:188 +msgid "This header type provides the following additional attributes:" +msgstr "" + +#: ../../library/email.headerregistry.rst:150 +msgid "" +"If the header value can be recognized as a valid date of one form or " +"another, this attribute will contain a :class:`~datetime.datetime` instance " +"representing that date. If the timezone of the input date is specified as " +"``-0000`` (indicating it is in UTC but contains no information about the " +"source timezone), then :attr:`.datetime` will be a naive :class:`~datetime." +"datetime`. If a specific timezone offset is found (including ``+0000``), " +"then :attr:`.datetime` will contain an aware ``datetime`` that uses :class:" +"`datetime.timezone` to record the timezone offset." +msgstr "" + +#: ../../library/email.headerregistry.rst:160 +msgid "" +"The ``decoded`` value of the header is determined by formatting the " +"``datetime`` according to the :rfc:`5322` rules; that is, it is set to::" +msgstr "" + +#: ../../library/email.headerregistry.rst:163 +msgid "email.utils.format_datetime(self.datetime)" +msgstr "" + +#: ../../library/email.headerregistry.rst:165 +msgid "" +"When creating a ``DateHeader``, *value* may be :class:`~datetime.datetime` " +"instance. This means, for example, that the following code is valid and " +"does what one would expect::" +msgstr "" + +#: ../../library/email.headerregistry.rst:169 +msgid "msg['Date'] = datetime(2011, 7, 15, 21)" +msgstr "msg['Date'] = datetime(2011, 7, 15, 21)" + +#: ../../library/email.headerregistry.rst:171 +msgid "" +"Because this is a naive ``datetime`` it will be interpreted as a UTC " +"timestamp, and the resulting value will have a timezone of ``-0000``. Much " +"more useful is to use the :func:`~email.utils.localtime` function from the :" +"mod:`~email.utils` module::" +msgstr "" + +#: ../../library/email.headerregistry.rst:176 +msgid "msg['Date'] = utils.localtime()" +msgstr "msg['Date'] = utils.localtime()" + +#: ../../library/email.headerregistry.rst:178 +msgid "" +"This example sets the date header to the current time and date using the " +"current timezone offset." +msgstr "" + +#: ../../library/email.headerregistry.rst:184 +msgid "" +"Address headers are one of the most complex structured header types. The " +"``AddressHeader`` class provides a generic interface to any address header." +msgstr "" + +#: ../../library/email.headerregistry.rst:193 +msgid "" +"A tuple of :class:`.Group` objects encoding the addresses and groups found " +"in the header value. Addresses that are not part of a group are represented " +"in this list as single-address ``Groups`` whose :attr:`~.Group.display_name` " +"is ``None``." +msgstr "" + +#: ../../library/email.headerregistry.rst:201 +msgid "" +"A tuple of :class:`.Address` objects encoding all of the individual " +"addresses from the header value. If the header value contains any groups, " +"the individual addresses from the group are included in the list at the " +"point where the group occurs in the value (that is, the list of addresses is " +"\"flattened\" into a one dimensional list)." +msgstr "" + +#: ../../library/email.headerregistry.rst:207 +msgid "" +"The ``decoded`` value of the header will have all encoded words decoded to " +"unicode. :class:`~encodings.idna` encoded domain names are also decoded to " +"unicode. The ``decoded`` value is set by :ref:`joining ` " +"the :class:`str` value of the elements of the ``groups`` attribute with ``', " +"'``." +msgstr "" + +#: ../../library/email.headerregistry.rst:213 +msgid "" +"A list of :class:`.Address` and :class:`.Group` objects in any combination " +"may be used to set the value of an address header. ``Group`` objects whose " +"``display_name`` is ``None`` will be interpreted as single addresses, which " +"allows an address list to be copied with groups intact by using the list " +"obtained from the ``groups`` attribute of the source header." +msgstr "" + +#: ../../library/email.headerregistry.rst:222 +msgid "" +"A subclass of :class:`.AddressHeader` that adds one additional attribute:" +msgstr "" + +#: ../../library/email.headerregistry.rst:228 +msgid "" +"The single address encoded by the header value. If the header value " +"actually contains more than one address (which would be a violation of the " +"RFC under the default :mod:`~email.policy`), accessing this attribute will " +"result in a :exc:`ValueError`." +msgstr "" + +#: ../../library/email.headerregistry.rst:234 +msgid "" +"Many of the above classes also have a ``Unique`` variant (for example, " +"``UniqueUnstructuredHeader``). The only difference is that in the " +"``Unique`` variant, :attr:`~.BaseHeader.max_count` is set to 1." +msgstr "" + +#: ../../library/email.headerregistry.rst:241 +msgid "" +"There is really only one valid value for the :mailheader:`MIME-Version` " +"header, and that is ``1.0``. For future proofing, this header class " +"supports other valid version numbers. If a version number has a valid value " +"per :rfc:`2045`, then the header object will have non-``None`` values for " +"the following attributes:" +msgstr "" + +#: ../../library/email.headerregistry.rst:249 +msgid "" +"The version number as a string, with any whitespace and/or comments removed." +msgstr "" + +#: ../../library/email.headerregistry.rst:254 +msgid "The major version number as an integer" +msgstr "" + +#: ../../library/email.headerregistry.rst:258 +msgid "The minor version number as an integer" +msgstr "" + +#: ../../library/email.headerregistry.rst:263 +msgid "" +"MIME headers all start with the prefix 'Content-'. Each specific header has " +"a certain value, described under the class for that header. Some can also " +"take a list of supplemental parameters, which have a common format. This " +"class serves as a base for all the MIME headers that take parameters." +msgstr "" + +#: ../../library/email.headerregistry.rst:270 +msgid "A dictionary mapping parameter names to parameter values." +msgstr "" + +#: ../../library/email.headerregistry.rst:275 +msgid "" +"A :class:`ParameterizedMIMEHeader` class that handles the :mailheader:" +"`Content-Type` header." +msgstr "" + +#: ../../library/email.headerregistry.rst:280 +msgid "The content type string, in the form ``maintype/subtype``." +msgstr "" + +#: ../../library/email.headerregistry.rst:289 +msgid "" +"A :class:`ParameterizedMIMEHeader` class that handles the :mailheader:" +"`Content-Disposition` header." +msgstr "" + +#: ../../library/email.headerregistry.rst:294 +msgid "``inline`` and ``attachment`` are the only valid values in common use." +msgstr "" + +#: ../../library/email.headerregistry.rst:299 +msgid "Handles the :mailheader:`Content-Transfer-Encoding` header." +msgstr "" + +#: ../../library/email.headerregistry.rst:303 +msgid "" +"Valid values are ``7bit``, ``8bit``, ``base64``, and ``quoted-printable``. " +"See :rfc:`2045` for more information." +msgstr "" + +#: ../../library/email.headerregistry.rst:312 +msgid "" +"This is the factory used by :class:`~email.policy.EmailPolicy` by default. " +"``HeaderRegistry`` builds the class used to create a header instance " +"dynamically, using *base_class* and a specialized class retrieved from a " +"registry that it holds. When a given header name does not appear in the " +"registry, the class specified by *default_class* is used as the specialized " +"class. When *use_default_map* is ``True`` (the default), the standard " +"mapping of header names to classes is copied in to the registry during " +"initialization. *base_class* is always the last class in the generated " +"class's :class:`~type.__bases__` list." +msgstr "" + +#: ../../library/email.headerregistry.rst:322 +msgid "The default mappings are:" +msgstr "" + +#: ../../library/email.headerregistry.rst:0 +msgid "subject" +msgstr "subject" + +#: ../../library/email.headerregistry.rst:324 +msgid "UniqueUnstructuredHeader" +msgstr "UniqueUnstructuredHeader" + +#: ../../library/email.headerregistry.rst:0 +msgid "date" +msgstr "date" + +#: ../../library/email.headerregistry.rst:325 +#: ../../library/email.headerregistry.rst:327 +msgid "UniqueDateHeader" +msgstr "UniqueDateHeader" + +#: ../../library/email.headerregistry.rst:0 +msgid "resent-date" +msgstr "resent-date" + +#: ../../library/email.headerregistry.rst:326 +msgid "DateHeader" +msgstr "DateHeader" + +#: ../../library/email.headerregistry.rst:0 +msgid "orig-date" +msgstr "orig-date" + +#: ../../library/email.headerregistry.rst:0 +msgid "sender" +msgstr "sender" + +#: ../../library/email.headerregistry.rst:328 +msgid "UniqueSingleAddressHeader" +msgstr "UniqueSingleAddressHeader" + +#: ../../library/email.headerregistry.rst:0 +msgid "resent-sender" +msgstr "resent-sender" + +#: ../../library/email.headerregistry.rst:329 +msgid "SingleAddressHeader" +msgstr "SingleAddressHeader" + +#: ../../library/email.headerregistry.rst:0 +msgid "to" +msgstr "to" + +#: ../../library/email.headerregistry.rst:330 +#: ../../library/email.headerregistry.rst:332 +#: ../../library/email.headerregistry.rst:334 +#: ../../library/email.headerregistry.rst:336 +#: ../../library/email.headerregistry.rst:338 +msgid "UniqueAddressHeader" +msgstr "UniqueAddressHeader" + +#: ../../library/email.headerregistry.rst:0 +msgid "resent-to" +msgstr "resent-to" + +#: ../../library/email.headerregistry.rst:331 +#: ../../library/email.headerregistry.rst:333 +#: ../../library/email.headerregistry.rst:335 +#: ../../library/email.headerregistry.rst:337 +msgid "AddressHeader" +msgstr "AddressHeader" + +#: ../../library/email.headerregistry.rst:0 +msgid "cc" +msgstr "cc" + +#: ../../library/email.headerregistry.rst:0 +msgid "resent-cc" +msgstr "resent-cc" + +#: ../../library/email.headerregistry.rst:0 +msgid "bcc" +msgstr "bcc" + +#: ../../library/email.headerregistry.rst:0 +msgid "resent-bcc" +msgstr "resent-bcc" + +#: ../../library/email.headerregistry.rst:0 +msgid "from" +msgstr "from" + +#: ../../library/email.headerregistry.rst:0 +msgid "resent-from" +msgstr "resent-from" + +#: ../../library/email.headerregistry.rst:0 +msgid "reply-to" +msgstr "reply-to" + +#: ../../library/email.headerregistry.rst:0 +msgid "mime-version" +msgstr "mime-version" + +#: ../../library/email.headerregistry.rst:339 +msgid "MIMEVersionHeader" +msgstr "MIMEVersionHeader" + +#: ../../library/email.headerregistry.rst:0 +msgid "content-type" +msgstr "content-type" + +#: ../../library/email.headerregistry.rst:340 +msgid "ContentTypeHeader" +msgstr "ContentTypeHeader" + +#: ../../library/email.headerregistry.rst:0 +msgid "content-disposition" +msgstr "content-disposition" + +#: ../../library/email.headerregistry.rst:341 +msgid "ContentDispositionHeader" +msgstr "ContentDispositionHeader" + +#: ../../library/email.headerregistry.rst:0 +msgid "content-transfer-encoding" +msgstr "content-transfer-encoding" + +#: ../../library/email.headerregistry.rst:342 +msgid "ContentTransferEncodingHeader" +msgstr "ContentTransferEncodingHeader" + +#: ../../library/email.headerregistry.rst:0 +msgid "message-id" +msgstr "message-id" + +#: ../../library/email.headerregistry.rst:343 +msgid "MessageIDHeader" +msgstr "MessageIDHeader" + +#: ../../library/email.headerregistry.rst:345 +msgid "``HeaderRegistry`` has the following methods:" +msgstr "``HeaderRegistry`` 有以下方法：" + +#: ../../library/email.headerregistry.rst:350 +msgid "" +"*name* is the name of the header to be mapped. It will be converted to " +"lower case in the registry. *cls* is the specialized class to be used, " +"along with *base_class*, to create the class used to instantiate headers " +"that match *name*." +msgstr "" + +#: ../../library/email.headerregistry.rst:358 +msgid "Construct and return a class to handle creating a *name* header." +msgstr "" + +#: ../../library/email.headerregistry.rst:363 +msgid "" +"Retrieves the specialized header associated with *name* from the registry " +"(using *default_class* if *name* does not appear in the registry) and " +"composes it with *base_class* to produce a class, calls the constructed " +"class's constructor, passing it the same argument list, and finally returns " +"the class instance created thereby." +msgstr "" + +#: ../../library/email.headerregistry.rst:370 +msgid "" +"The following classes are the classes used to represent data parsed from " +"structured headers and can, in general, be used by an application program to " +"construct structured values to assign to specific headers." +msgstr "" + +#: ../../library/email.headerregistry.rst:377 +msgid "" +"The class used to represent an email address. The general form of an " +"address is::" +msgstr "" + +#: ../../library/email.headerregistry.rst:380 +msgid "[display_name] " +msgstr "[display_name] " + +#: ../../library/email.headerregistry.rst:382 +msgid "or::" +msgstr "或是： ::" + +#: ../../library/email.headerregistry.rst:384 +msgid "username@domain" +msgstr "username@domain" + +#: ../../library/email.headerregistry.rst:386 +msgid "" +"where each part must conform to specific syntax rules spelled out in :rfc:" +"`5322`." +msgstr "" + +#: ../../library/email.headerregistry.rst:389 +msgid "" +"As a convenience *addr_spec* can be specified instead of *username* and " +"*domain*, in which case *username* and *domain* will be parsed from the " +"*addr_spec*. An *addr_spec* must be a properly RFC quoted string; if it is " +"not ``Address`` will raise an error. Unicode characters are allowed and " +"will be property encoded when serialized. However, per the RFCs, unicode is " +"*not* allowed in the username portion of the address." +msgstr "" + +#: ../../library/email.headerregistry.rst:398 +msgid "" +"The display name portion of the address, if any, with all quoting removed. " +"If the address does not have a display name, this attribute will be an empty " +"string." +msgstr "" + +#: ../../library/email.headerregistry.rst:404 +msgid "The ``username`` portion of the address, with all quoting removed." +msgstr "" + +#: ../../library/email.headerregistry.rst:408 +msgid "The ``domain`` portion of the address." +msgstr "" + +#: ../../library/email.headerregistry.rst:412 +msgid "" +"The ``username@domain`` portion of the address, correctly quoted for use as " +"a bare address (the second form shown above). This attribute is not mutable." +msgstr "" + +#: ../../library/email.headerregistry.rst:418 +msgid "" +"The ``str`` value of the object is the address quoted according to :rfc:" +"`5322` rules, but with no Content Transfer Encoding of any non-ASCII " +"characters." +msgstr "" + +#: ../../library/email.headerregistry.rst:422 +msgid "" +"To support SMTP (:rfc:`5321`), ``Address`` handles one special case: if " +"``username`` and ``domain`` are both the empty string (or ``None``), then " +"the string value of the ``Address`` is ``<>``." +msgstr "" + +#: ../../library/email.headerregistry.rst:429 +msgid "" +"The class used to represent an address group. The general form of an " +"address group is::" +msgstr "" + +#: ../../library/email.headerregistry.rst:432 +msgid "display_name: [address-list];" +msgstr "display_name: [address-list];" + +#: ../../library/email.headerregistry.rst:434 +msgid "" +"As a convenience for processing lists of addresses that consist of a mixture " +"of groups and single addresses, a ``Group`` may also be used to represent " +"single addresses that are not part of a group by setting *display_name* to " +"``None`` and providing a list of the single address as *addresses*." +msgstr "" + +#: ../../library/email.headerregistry.rst:441 +msgid "" +"The ``display_name`` of the group. If it is ``None`` and there is exactly " +"one ``Address`` in ``addresses``, then the ``Group`` represents a single " +"address that is not in a group." +msgstr "" + +#: ../../library/email.headerregistry.rst:447 +msgid "" +"A possibly empty tuple of :class:`.Address` objects representing the " +"addresses in the group." +msgstr "" + +#: ../../library/email.headerregistry.rst:452 +msgid "" +"The ``str`` value of a ``Group`` is formatted according to :rfc:`5322`, but " +"with no Content Transfer Encoding of any non-ASCII characters. If " +"``display_name`` is none and there is a single ``Address`` in the " +"``addresses`` list, the ``str`` value will be the same as the ``str`` of " +"that single ``Address``." +msgstr "" + +#: ../../library/email.headerregistry.rst:460 +msgid "Footnotes" +msgstr "註解" + +#: ../../library/email.headerregistry.rst:461 +msgid "" +"Originally added in 3.3 as a :term:`provisional module `" +msgstr "" diff --git a/library/email.iterators.po b/library/email.iterators.po index 5a0856c018..c3592137e7 100644 --- a/library/email.iterators.po +++ b/library/email.iterators.po @@ -1,126 +1,126 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-09-03 11:11+0800\n" -"PO-Revision-Date: 2016-11-19 00:30+0000\n" -"Last-Translator: Liang-Bo Wang \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/email.iterators.rst:2 -msgid ":mod:`!email.iterators`: Iterators" -msgstr ":mod:`!email.iterators`：疊代器" - -#: ../../library/email.iterators.rst:7 -msgid "**Source code:** :source:`Lib/email/iterators.py`" -msgstr "**原始碼：**\\ :source:`Lib/email/iterators.py`" - -#: ../../library/email.iterators.rst:11 -msgid "" -"Iterating over a message object tree is fairly easy with the :meth:`Message." -"walk ` method. The :mod:`email.iterators` " -"module provides some useful higher level iterations over message object " -"trees." -msgstr "" - -#: ../../library/email.iterators.rst:19 -msgid "" -"This iterates over all the payloads in all the subparts of *msg*, returning " -"the string payloads line-by-line. It skips over all the subpart headers, " -"and it skips over any subpart with a payload that isn't a Python string. " -"This is somewhat equivalent to reading the flat text representation of the " -"message from a file using :meth:`~io.TextIOBase.readline`, skipping over all " -"the intervening headers." -msgstr "" - -#: ../../library/email.iterators.rst:26 -msgid "" -"Optional *decode* is passed through to :meth:`Message.get_payload `." -msgstr "" - -#: ../../library/email.iterators.rst:32 -msgid "" -"This iterates over all the subparts of *msg*, returning only those subparts " -"that match the MIME type specified by *maintype* and *subtype*." -msgstr "" - -#: ../../library/email.iterators.rst:35 -msgid "" -"Note that *subtype* is optional; if omitted, then subpart MIME type matching " -"is done only with the main type. *maintype* is optional too; it defaults " -"to :mimetype:`text`." -msgstr "" - -#: ../../library/email.iterators.rst:39 -msgid "" -"Thus, by default :func:`typed_subpart_iterator` returns each subpart that " -"has a MIME type of :mimetype:`text/\\*`." -msgstr "" - -#: ../../library/email.iterators.rst:43 -msgid "" -"The following function has been added as a useful debugging tool. It should " -"*not* be considered part of the supported public interface for the package." -msgstr "" - -#: ../../library/email.iterators.rst:48 -msgid "" -"Prints an indented representation of the content types of the message object " -"structure. For example:" -msgstr "" - -#: ../../library/email.iterators.rst:57 -msgid "" -">>> msg = email.message_from_file(somefile)\n" -">>> _structure(msg)\n" -"multipart/mixed\n" -" text/plain\n" -" text/plain\n" -" multipart/digest\n" -" message/rfc822\n" -" text/plain\n" -" message/rfc822\n" -" text/plain\n" -" message/rfc822\n" -" text/plain\n" -" message/rfc822\n" -" text/plain\n" -" message/rfc822\n" -" text/plain\n" -" text/plain" -msgstr "" -">>> msg = email.message_from_file(somefile)\n" -">>> _structure(msg)\n" -"multipart/mixed\n" -" text/plain\n" -" text/plain\n" -" multipart/digest\n" -" message/rfc822\n" -" text/plain\n" -" message/rfc822\n" -" text/plain\n" -" message/rfc822\n" -" text/plain\n" -" message/rfc822\n" -" text/plain\n" -" message/rfc822\n" -" text/plain\n" -" text/plain" - -#: ../../library/email.iterators.rst:81 -msgid "" -"Optional *fp* is a file-like object to print the output to. It must be " -"suitable for Python's :func:`print` function. *level* is used internally. " -"*include_default*, if true, prints the default type as well." -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-09-03 11:11+0800\n" +"PO-Revision-Date: 2016-11-19 00:30+0000\n" +"Last-Translator: Liang-Bo Wang \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/email.iterators.rst:2 +msgid ":mod:`!email.iterators`: Iterators" +msgstr ":mod:`!email.iterators`：疊代器" + +#: ../../library/email.iterators.rst:7 +msgid "**Source code:** :source:`Lib/email/iterators.py`" +msgstr "**原始碼：**\\ :source:`Lib/email/iterators.py`" + +#: ../../library/email.iterators.rst:11 +msgid "" +"Iterating over a message object tree is fairly easy with the :meth:`Message." +"walk ` method. The :mod:`email.iterators` " +"module provides some useful higher level iterations over message object " +"trees." +msgstr "" + +#: ../../library/email.iterators.rst:19 +msgid "" +"This iterates over all the payloads in all the subparts of *msg*, returning " +"the string payloads line-by-line. It skips over all the subpart headers, " +"and it skips over any subpart with a payload that isn't a Python string. " +"This is somewhat equivalent to reading the flat text representation of the " +"message from a file using :meth:`~io.TextIOBase.readline`, skipping over all " +"the intervening headers." +msgstr "" + +#: ../../library/email.iterators.rst:26 +msgid "" +"Optional *decode* is passed through to :meth:`Message.get_payload `." +msgstr "" + +#: ../../library/email.iterators.rst:32 +msgid "" +"This iterates over all the subparts of *msg*, returning only those subparts " +"that match the MIME type specified by *maintype* and *subtype*." +msgstr "" + +#: ../../library/email.iterators.rst:35 +msgid "" +"Note that *subtype* is optional; if omitted, then subpart MIME type matching " +"is done only with the main type. *maintype* is optional too; it defaults " +"to :mimetype:`text`." +msgstr "" + +#: ../../library/email.iterators.rst:39 +msgid "" +"Thus, by default :func:`typed_subpart_iterator` returns each subpart that " +"has a MIME type of :mimetype:`text/\\*`." +msgstr "" + +#: ../../library/email.iterators.rst:43 +msgid "" +"The following function has been added as a useful debugging tool. It should " +"*not* be considered part of the supported public interface for the package." +msgstr "" + +#: ../../library/email.iterators.rst:48 +msgid "" +"Prints an indented representation of the content types of the message object " +"structure. For example:" +msgstr "" + +#: ../../library/email.iterators.rst:57 +msgid "" +">>> msg = email.message_from_file(somefile)\n" +">>> _structure(msg)\n" +"multipart/mixed\n" +" text/plain\n" +" text/plain\n" +" multipart/digest\n" +" message/rfc822\n" +" text/plain\n" +" message/rfc822\n" +" text/plain\n" +" message/rfc822\n" +" text/plain\n" +" message/rfc822\n" +" text/plain\n" +" message/rfc822\n" +" text/plain\n" +" text/plain" +msgstr "" +">>> msg = email.message_from_file(somefile)\n" +">>> _structure(msg)\n" +"multipart/mixed\n" +" text/plain\n" +" text/plain\n" +" multipart/digest\n" +" message/rfc822\n" +" text/plain\n" +" message/rfc822\n" +" text/plain\n" +" message/rfc822\n" +" text/plain\n" +" message/rfc822\n" +" text/plain\n" +" message/rfc822\n" +" text/plain\n" +" text/plain" + +#: ../../library/email.iterators.rst:81 +msgid "" +"Optional *fp* is a file-like object to print the output to. It must be " +"suitable for Python's :func:`print` function. *level* is used internally. " +"*include_default*, if true, prints the default type as well." +msgstr "" diff --git a/library/email.message.po b/library/email.message.po index 7e1526c920..bb1d90e010 100644 --- a/library/email.message.po +++ b/library/email.message.po @@ -1,922 +1,922 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2026-01-07 00:14+0000\n" -"PO-Revision-Date: 2018-05-23 14:44+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/email.message.rst:2 -msgid ":mod:`!email.message`: Representing an email message" -msgstr ":mod:`!email.message`：表示電子郵件訊息" - -#: ../../library/email.message.rst:10 -msgid "**Source code:** :source:`Lib/email/message.py`" -msgstr "**原始碼：**\\ :source:`Lib/email/message.py`" - -#: ../../library/email.message.rst:14 -msgid "[1]_" -msgstr "[1]_" - -#: ../../library/email.message.rst:16 -msgid "" -"The central class in the :mod:`email` package is the :class:`EmailMessage` " -"class, imported from the :mod:`email.message` module. It is the base class " -"for the :mod:`email` object model. :class:`EmailMessage` provides the core " -"functionality for setting and querying header fields, for accessing message " -"bodies, and for creating or modifying structured messages." -msgstr "" - -#: ../../library/email.message.rst:22 -msgid "" -"An email message consists of *headers* and a *payload* (which is also " -"referred to as the *content*). Headers are :rfc:`5322` or :rfc:`6532` style " -"field names and values, where the field name and value are separated by a " -"colon. The colon is not part of either the field name or the field value. " -"The payload may be a simple text message, or a binary object, or a " -"structured sequence of sub-messages each with their own set of headers and " -"their own payload. The latter type of payload is indicated by the message " -"having a MIME type such as :mimetype:`multipart/\\*` or :mimetype:`message/" -"rfc822`." -msgstr "" - -#: ../../library/email.message.rst:31 -msgid "" -"The conceptual model provided by an :class:`EmailMessage` object is that of " -"an ordered dictionary of headers coupled with a *payload* that represents " -"the :rfc:`5322` body of the message, which might be a list of sub-" -"``EmailMessage`` objects. In addition to the normal dictionary methods for " -"accessing the header names and values, there are methods for accessing " -"specialized information from the headers (for example the MIME content " -"type), for operating on the payload, for generating a serialized version of " -"the message, and for recursively walking over the object tree." -msgstr "" - -#: ../../library/email.message.rst:40 -msgid "" -"The :class:`EmailMessage` dictionary-like interface is indexed by the header " -"names, which must be ASCII values. The values of the dictionary are strings " -"with some extra methods. Headers are stored and returned in case-preserving " -"form, but field names are matched case-insensitively. The keys are ordered, " -"but unlike a real dict, there can be duplicates. Additional methods are " -"provided for working with headers that have duplicate keys." -msgstr "" - -#: ../../library/email.message.rst:47 -msgid "" -"The *payload* is either a string or bytes object, in the case of simple " -"message objects, or a list of :class:`EmailMessage` objects, for MIME " -"container documents such as :mimetype:`multipart/\\*` and :mimetype:`message/" -"rfc822` message objects." -msgstr "" - -#: ../../library/email.message.rst:55 -msgid "" -"If *policy* is specified use the rules it specifies to update and serialize " -"the representation of the message. If *policy* is not set, use the :class:" -"`~email.policy.default` policy, which follows the rules of the email RFCs " -"except for line endings (instead of the RFC mandated ``\\r\\n``, it uses the " -"Python standard ``\\n`` line endings). For more information see the :mod:" -"`~email.policy` documentation. [2]_" -msgstr "" - -#: ../../library/email.message.rst:64 -msgid "" -"Return the entire message flattened as a string. When optional *unixfrom* " -"is true, the envelope header is included in the returned string. *unixfrom* " -"defaults to ``False``. For backward compatibility with the base :class:" -"`~email.message.Message` class *maxheaderlen* is accepted, but defaults to " -"``None``, which means that by default the line length is controlled by the :" -"attr:`~email.policy.Policy.max_line_length` of the policy. The *policy* " -"argument may be used to override the default policy obtained from the " -"message instance. This can be used to control some of the formatting " -"produced by the method, since the specified *policy* will be passed to the :" -"class:`~email.generator.Generator`." -msgstr "" - -#: ../../library/email.message.rst:76 ../../library/email.message.rst:114 -msgid "" -"Flattening the message may trigger changes to the :class:`EmailMessage` if " -"defaults need to be filled in to complete the transformation to a string " -"(for example, MIME boundaries may be generated or modified)." -msgstr "" - -#: ../../library/email.message.rst:80 -msgid "" -"Note that this method is provided as a convenience and may not be the most " -"useful way to serialize messages in your application, especially if you are " -"dealing with multiple messages. See :class:`email.generator.Generator` for " -"a more flexible API for serializing messages. Note also that this method is " -"restricted to producing messages serialized as \"7 bit clean\" when :attr:" -"`~email.policy.EmailPolicy.utf8` is ``False``, which is the default." -msgstr "" - -#: ../../library/email.message.rst:88 -msgid "" -"the default behavior when *maxheaderlen* is not specified was changed from " -"defaulting to 0 to defaulting to the value of *max_line_length* from the " -"policy." -msgstr "" - -#: ../../library/email.message.rst:95 -msgid "" -"Equivalent to ``as_string(policy=self.policy.clone(utf8=True))``. Allows " -"``str(msg)`` to produce a string containing the serialized message in a " -"readable format." -msgstr "" - -#: ../../library/email.message.rst:99 -msgid "" -"the method was changed to use ``utf8=True``, thus producing an :rfc:`6531`-" -"like message representation, instead of being a direct alias for :meth:" -"`as_string`." -msgstr "" - -#: ../../library/email.message.rst:106 -msgid "" -"Return the entire message flattened as a bytes object. When optional " -"*unixfrom* is true, the envelope header is included in the returned string. " -"*unixfrom* defaults to ``False``. The *policy* argument may be used to " -"override the default policy obtained from the message instance. This can be " -"used to control some of the formatting produced by the method, since the " -"specified *policy* will be passed to the :class:`~email.generator." -"BytesGenerator`." -msgstr "" - -#: ../../library/email.message.rst:118 -msgid "" -"Note that this method is provided as a convenience and may not be the most " -"useful way to serialize messages in your application, especially if you are " -"dealing with multiple messages. See :class:`email.generator.BytesGenerator` " -"for a more flexible API for serializing messages." -msgstr "" - -#: ../../library/email.message.rst:127 -msgid "" -"Equivalent to :meth:`.as_bytes`. Allows ``bytes(msg)`` to produce a bytes " -"object containing the serialized message." -msgstr "" - -#: ../../library/email.message.rst:133 -msgid "" -"Return ``True`` if the message's payload is a list of sub-\\ :class:" -"`EmailMessage` objects, otherwise return ``False``. When :meth:" -"`is_multipart` returns ``False``, the payload should be a string object " -"(which might be a CTE encoded binary payload). Note that :meth:" -"`is_multipart` returning ``True`` does not necessarily mean that \"msg." -"get_content_maintype() == 'multipart'\" will return the ``True``. For " -"example, ``is_multipart`` will return ``True`` when the :class:" -"`EmailMessage` is of type ``message/rfc822``." -msgstr "" - -#: ../../library/email.message.rst:145 -msgid "" -"Set the message's envelope header to *unixfrom*, which should be a string. " -"(See :class:`~mailbox.mboxMessage` for a brief description of this header.)" -msgstr "" - -#: ../../library/email.message.rst:152 -msgid "" -"Return the message's envelope header. Defaults to ``None`` if the envelope " -"header was never set." -msgstr "" - -#: ../../library/email.message.rst:156 -msgid "" -"The following methods implement the mapping-like interface for accessing the " -"message's headers. Note that there are some semantic differences between " -"these methods and a normal mapping (i.e. dictionary) interface. For " -"example, in a dictionary there are no duplicate keys, but here there may be " -"duplicate message headers. Also, in dictionaries there is no guaranteed " -"order to the keys returned by :meth:`keys`, but in an :class:`EmailMessage` " -"object, headers are always returned in the order they appeared in the " -"original message, or in which they were added to the message later. Any " -"header deleted and then re-added is always appended to the end of the header " -"list." -msgstr "" - -#: ../../library/email.message.rst:167 -msgid "" -"These semantic differences are intentional and are biased toward convenience " -"in the most common use cases." -msgstr "" - -#: ../../library/email.message.rst:170 -msgid "" -"Note that in all cases, any envelope header present in the message is not " -"included in the mapping interface." -msgstr "" - -#: ../../library/email.message.rst:176 -msgid "Return the total number of headers, including duplicates." -msgstr "" - -#: ../../library/email.message.rst:181 -msgid "" -"Return ``True`` if the message object has a field named *name*. Matching is " -"done without regard to case and *name* does not include the trailing colon. " -"Used for the ``in`` operator. For example::" -msgstr "" - -#: ../../library/email.message.rst:185 -msgid "" -"if 'message-id' in myMessage:\n" -" print('Message-ID:', myMessage['message-id'])" -msgstr "" -"if 'message-id' in myMessage:\n" -" print('Message-ID:', myMessage['message-id'])" - -#: ../../library/email.message.rst:191 -msgid "" -"Return the value of the named header field. *name* does not include the " -"colon field separator. If the header is missing, ``None`` is returned; a :" -"exc:`KeyError` is never raised." -msgstr "" - -#: ../../library/email.message.rst:195 -msgid "" -"Note that if the named field appears more than once in the message's " -"headers, exactly which of those field values will be returned is undefined. " -"Use the :meth:`get_all` method to get the values of all the extant headers " -"named *name*." -msgstr "" - -#: ../../library/email.message.rst:200 -msgid "" -"Using the standard (non-``compat32``) policies, the returned value is an " -"instance of a subclass of :class:`email.headerregistry.BaseHeader`." -msgstr "" - -#: ../../library/email.message.rst:206 -msgid "" -"Add a header to the message with field name *name* and value *val*. The " -"field is appended to the end of the message's existing headers." -msgstr "" - -#: ../../library/email.message.rst:209 -msgid "" -"Note that this does *not* overwrite or delete any existing header with the " -"same name. If you want to ensure that the new header is the only one " -"present in the message with field name *name*, delete the field first, e.g.::" -msgstr "" - -#: ../../library/email.message.rst:213 -msgid "" -"del msg['subject']\n" -"msg['subject'] = 'Python roolz!'" -msgstr "" -"del msg['subject']\n" -"msg['subject'] = 'Python roolz!'" - -#: ../../library/email.message.rst:216 -msgid "" -"If the :mod:`policy ` defines certain headers to be unique (as " -"the standard policies do), this method may raise a :exc:`ValueError` when an " -"attempt is made to assign a value to such a header when one already exists. " -"This behavior is intentional for consistency's sake, but do not depend on it " -"as we may choose to make such assignments do an automatic deletion of the " -"existing header in the future." -msgstr "" - -#: ../../library/email.message.rst:226 -msgid "" -"Delete all occurrences of the field with name *name* from the message's " -"headers. No exception is raised if the named field isn't present in the " -"headers." -msgstr "" - -#: ../../library/email.message.rst:233 -msgid "Return a list of all the message's header field names." -msgstr "" - -#: ../../library/email.message.rst:238 -msgid "Return a list of all the message's field values." -msgstr "" - -#: ../../library/email.message.rst:243 -msgid "" -"Return a list of 2-tuples containing all the message's field headers and " -"values." -msgstr "" - -#: ../../library/email.message.rst:249 -msgid "" -"Return the value of the named header field. This is identical to :meth:" -"`~object.__getitem__` except that optional *failobj* is returned if the " -"named header is missing (*failobj* defaults to ``None``)." -msgstr "" - -#: ../../library/email.message.rst:254 -msgid "Here are some additional useful header related methods:" -msgstr "" - -#: ../../library/email.message.rst:259 -msgid "" -"Return a list of all the values for the field named *name*. If there are no " -"such named headers in the message, *failobj* is returned (defaults to " -"``None``)." -msgstr "" - -#: ../../library/email.message.rst:266 -msgid "" -"Extended header setting. This method is similar to :meth:`__setitem__` " -"except that additional header parameters can be provided as keyword " -"arguments. *_name* is the header field to add and *_value* is the *primary* " -"value for the header." -msgstr "" - -#: ../../library/email.message.rst:271 -msgid "" -"For each item in the keyword argument dictionary *_params*, the key is taken " -"as the parameter name, with underscores converted to dashes (since dashes " -"are illegal in Python identifiers). Normally, the parameter will be added " -"as ``key=\"value\"`` unless the value is ``None``, in which case only the " -"key will be added." -msgstr "" - -#: ../../library/email.message.rst:277 -msgid "" -"If the value contains non-ASCII characters, the charset and language may be " -"explicitly controlled by specifying the value as a three tuple in the format " -"``(CHARSET, LANGUAGE, VALUE)``, where ``CHARSET`` is a string naming the " -"charset to be used to encode the value, ``LANGUAGE`` can usually be set to " -"``None`` or the empty string (see :rfc:`2231` for other possibilities), and " -"``VALUE`` is the string value containing non-ASCII code points. If a three " -"tuple is not passed and the value contains non-ASCII characters, it is " -"automatically encoded in :rfc:`2231` format using a ``CHARSET`` of ``utf-8`` " -"and a ``LANGUAGE`` of ``None``." -msgstr "" - -#: ../../library/email.message.rst:287 -msgid "Here is an example::" -msgstr "以下是個範例： ::" - -#: ../../library/email.message.rst:289 -msgid "msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')" -msgstr "" -"msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')" - -#: ../../library/email.message.rst:291 -msgid "This will add a header that looks like ::" -msgstr "" - -#: ../../library/email.message.rst:293 -msgid "Content-Disposition: attachment; filename=\"bud.gif\"" -msgstr "Content-Disposition: attachment; filename=\"bud.gif\"" - -#: ../../library/email.message.rst:295 -msgid "An example of the extended interface with non-ASCII characters::" -msgstr "" - -#: ../../library/email.message.rst:297 -msgid "" -"msg.add_header('Content-Disposition', 'attachment',\n" -" filename=('iso-8859-1', '', 'Fußballer.ppt'))" -msgstr "" - -#: ../../library/email.message.rst:303 -msgid "" -"Replace a header. Replace the first header found in the message that " -"matches *_name*, retaining header order and field name case of the original " -"header. If no matching header is found, raise a :exc:`KeyError`." -msgstr "" - -#: ../../library/email.message.rst:311 -msgid "" -"Return the message's content type, coerced to lower case of the form :" -"mimetype:`maintype/subtype`. If there is no :mailheader:`Content-Type` " -"header in the message return the value returned by :meth:" -"`get_default_type`. If the :mailheader:`Content-Type` header is invalid, " -"return ``text/plain``." -msgstr "" - -#: ../../library/email.message.rst:317 -msgid "" -"(According to :rfc:`2045`, messages always have a default type, :meth:" -"`get_content_type` will always return a value. :rfc:`2045` defines a " -"message's default type to be :mimetype:`text/plain` unless it appears inside " -"a :mimetype:`multipart/digest` container, in which case it would be :" -"mimetype:`message/rfc822`. If the :mailheader:`Content-Type` header has an " -"invalid type specification, :rfc:`2045` mandates that the default type be :" -"mimetype:`text/plain`.)" -msgstr "" - -#: ../../library/email.message.rst:328 -msgid "" -"Return the message's main content type. This is the :mimetype:`maintype` " -"part of the string returned by :meth:`get_content_type`." -msgstr "" - -#: ../../library/email.message.rst:334 -msgid "" -"Return the message's sub-content type. This is the :mimetype:`subtype` part " -"of the string returned by :meth:`get_content_type`." -msgstr "" - -#: ../../library/email.message.rst:340 -msgid "" -"Return the default content type. Most messages have a default content type " -"of :mimetype:`text/plain`, except for messages that are subparts of :" -"mimetype:`multipart/digest` containers. Such subparts have a default " -"content type of :mimetype:`message/rfc822`." -msgstr "" - -#: ../../library/email.message.rst:348 -msgid "" -"Set the default content type. *ctype* should either be :mimetype:`text/" -"plain` or :mimetype:`message/rfc822`, although this is not enforced. The " -"default content type is not stored in the :mailheader:`Content-Type` header, " -"so it only affects the return value of the ``get_content_type`` methods when " -"no :mailheader:`Content-Type` header is present in the message." -msgstr "" - -#: ../../library/email.message.rst:359 -msgid "" -"Set a parameter in the :mailheader:`Content-Type` header. If the parameter " -"already exists in the header, replace its value with *value*. When *header* " -"is ``Content-Type`` (the default) and the header does not yet exist in the " -"message, add it, set its value to :mimetype:`text/plain`, and append the new " -"parameter value. Optional *header* specifies an alternative header to :" -"mailheader:`Content-Type`." -msgstr "" - -#: ../../library/email.message.rst:366 -msgid "" -"If the value contains non-ASCII characters, the charset and language may be " -"explicitly specified using the optional *charset* and *language* " -"parameters. Optional *language* specifies the :rfc:`2231` language, " -"defaulting to the empty string. Both *charset* and *language* should be " -"strings. The default is to use the ``utf8`` *charset* and ``None`` for the " -"*language*." -msgstr "" - -#: ../../library/email.message.rst:373 -msgid "" -"If *replace* is ``False`` (the default) the header is moved to the end of " -"the list of headers. If *replace* is ``True``, the header will be updated " -"in place." -msgstr "" - -#: ../../library/email.message.rst:377 ../../library/email.message.rst:394 -msgid "" -"Use of the *requote* parameter with :class:`EmailMessage` objects is " -"deprecated." -msgstr "" - -#: ../../library/email.message.rst:380 -msgid "" -"Note that existing parameter values of headers may be accessed through the :" -"attr:`~email.headerregistry.ParameterizedMIMEHeader.params` attribute of the " -"header value (for example, ``msg['Content-Type'].params['charset']``)." -msgstr "" - -#: ../../library/email.message.rst:384 -msgid "``replace`` keyword was added." -msgstr "新增 ``replace`` 關鍵字。" - -#: ../../library/email.message.rst:389 -msgid "" -"Remove the given parameter completely from the :mailheader:`Content-Type` " -"header. The header will be re-written in place without the parameter or its " -"value. Optional *header* specifies an alternative to :mailheader:`Content-" -"Type`." -msgstr "" - -#: ../../library/email.message.rst:400 -msgid "" -"Return the value of the ``filename`` parameter of the :mailheader:`Content-" -"Disposition` header of the message. If the header does not have a " -"``filename`` parameter, this method falls back to looking for the ``name`` " -"parameter on the :mailheader:`Content-Type` header. If neither is found, or " -"the header is missing, then *failobj* is returned. The returned string will " -"always be unquoted as per :func:`email.utils.unquote`." -msgstr "" - -#: ../../library/email.message.rst:411 -msgid "" -"Return the value of the ``boundary`` parameter of the :mailheader:`Content-" -"Type` header of the message, or *failobj* if either the header is missing, " -"or has no ``boundary`` parameter. The returned string will always be " -"unquoted as per :func:`email.utils.unquote`." -msgstr "" - -#: ../../library/email.message.rst:419 -msgid "" -"Set the ``boundary`` parameter of the :mailheader:`Content-Type` header to " -"*boundary*. :meth:`set_boundary` will always quote *boundary* if " -"necessary. A :exc:`~email.errors.HeaderParseError` is raised if the message " -"object has no :mailheader:`Content-Type` header." -msgstr "" - -#: ../../library/email.message.rst:424 -msgid "" -"Note that using this method is subtly different from deleting the old :" -"mailheader:`Content-Type` header and adding a new one with the new boundary " -"via :meth:`add_header`, because :meth:`set_boundary` preserves the order of " -"the :mailheader:`Content-Type` header in the list of headers." -msgstr "" - -#: ../../library/email.message.rst:433 -msgid "" -"Return the ``charset`` parameter of the :mailheader:`Content-Type` header, " -"coerced to lower case. If there is no :mailheader:`Content-Type` header, or " -"if that header has no ``charset`` parameter, *failobj* is returned." -msgstr "" - -#: ../../library/email.message.rst:440 -msgid "" -"Return a list containing the character set names in the message. If the " -"message is a :mimetype:`multipart`, then the list will contain one element " -"for each subpart in the payload, otherwise, it will be a list of length 1." -msgstr "" - -#: ../../library/email.message.rst:444 -msgid "" -"Each item in the list will be a string which is the value of the ``charset`` " -"parameter in the :mailheader:`Content-Type` header for the represented " -"subpart. If the subpart has no :mailheader:`Content-Type` header, no " -"``charset`` parameter, or is not of the :mimetype:`text` main MIME type, " -"then that item in the returned list will be *failobj*." -msgstr "" - -#: ../../library/email.message.rst:453 -msgid "" -"Return ``True`` if there is a :mailheader:`Content-Disposition` header and " -"its (case insensitive) value is ``attachment``, ``False`` otherwise." -msgstr "" - -#: ../../library/email.message.rst:456 -msgid "" -"is_attachment is now a method instead of a property, for consistency with :" -"meth:`~email.message.Message.is_multipart`." -msgstr "" - -#: ../../library/email.message.rst:463 -msgid "" -"Return the lowercased value (without parameters) of the message's :" -"mailheader:`Content-Disposition` header if it has one, or ``None``. The " -"possible values for this method are *inline*, *attachment* or ``None`` if " -"the message follows :rfc:`2183`." -msgstr "" - -#: ../../library/email.message.rst:471 -msgid "" -"The following methods relate to interrogating and manipulating the content " -"(payload) of the message." -msgstr "" - -#: ../../library/email.message.rst:477 -msgid "" -"The :meth:`walk` method is an all-purpose generator which can be used to " -"iterate over all the parts and subparts of a message object tree, in depth-" -"first traversal order. You will typically use :meth:`walk` as the iterator " -"in a ``for`` loop; each iteration returns the next subpart." -msgstr "" - -#: ../../library/email.message.rst:482 -msgid "" -"Here's an example that prints the MIME type of every part of a multipart " -"message structure:" -msgstr "" - -#: ../../library/email.message.rst:491 -msgid "" -">>> for part in msg.walk():\n" -"... print(part.get_content_type())\n" -"multipart/report\n" -"text/plain\n" -"message/delivery-status\n" -"text/plain\n" -"text/plain\n" -"message/rfc822\n" -"text/plain" -msgstr "" -">>> for part in msg.walk():\n" -"... print(part.get_content_type())\n" -"multipart/report\n" -"text/plain\n" -"message/delivery-status\n" -"text/plain\n" -"text/plain\n" -"message/rfc822\n" -"text/plain" - -#: ../../library/email.message.rst:503 -msgid "" -"``walk`` iterates over the subparts of any part where :meth:`is_multipart` " -"returns ``True``, even though ``msg.get_content_maintype() == 'multipart'`` " -"may return ``False``. We can see this in our example by making use of the " -"``_structure`` debug helper function:" -msgstr "" - -#: ../../library/email.message.rst:509 -msgid "" -">>> from email.iterators import _structure\n" -">>> for part in msg.walk():\n" -"... print(part.get_content_maintype() == 'multipart',\n" -"... part.is_multipart())\n" -"True True\n" -"False False\n" -"False True\n" -"False False\n" -"False False\n" -"False True\n" -"False False\n" -">>> _structure(msg)\n" -"multipart/report\n" -" text/plain\n" -" message/delivery-status\n" -" text/plain\n" -" text/plain\n" -" message/rfc822\n" -" text/plain" -msgstr "" -">>> from email.iterators import _structure\n" -">>> for part in msg.walk():\n" -"... print(part.get_content_maintype() == 'multipart',\n" -"... part.is_multipart())\n" -"True True\n" -"False False\n" -"False True\n" -"False False\n" -"False False\n" -"False True\n" -"False False\n" -">>> _structure(msg)\n" -"multipart/report\n" -" text/plain\n" -" message/delivery-status\n" -" text/plain\n" -" text/plain\n" -" message/rfc822\n" -" text/plain" - -#: ../../library/email.message.rst:531 -msgid "" -"Here the ``message`` parts are not ``multiparts``, but they do contain " -"subparts. ``is_multipart()`` returns ``True`` and ``walk`` descends into the " -"subparts." -msgstr "" - -#: ../../library/email.message.rst:538 -msgid "" -"Return the MIME part that is the best candidate to be the \"body\" of the " -"message." -msgstr "" - -#: ../../library/email.message.rst:541 -msgid "" -"*preferencelist* must be a sequence of strings from the set ``related``, " -"``html``, and ``plain``, and indicates the order of preference for the " -"content type of the part returned." -msgstr "" - -#: ../../library/email.message.rst:545 -msgid "" -"Start looking for candidate matches with the object on which the " -"``get_body`` method is called." -msgstr "" - -#: ../../library/email.message.rst:548 -msgid "" -"If ``related`` is not included in *preferencelist*, consider the root part " -"(or subpart of the root part) of any related encountered as a candidate if " -"the (sub-)part matches a preference." -msgstr "" - -#: ../../library/email.message.rst:552 -msgid "" -"When encountering a ``multipart/related``, check the ``start`` parameter and " -"if a part with a matching :mailheader:`Content-ID` is found, consider only " -"it when looking for candidate matches. Otherwise consider only the first " -"(default root) part of the ``multipart/related``." -msgstr "" - -#: ../../library/email.message.rst:557 -msgid "" -"If a part has a :mailheader:`Content-Disposition` header, only consider the " -"part a candidate match if the value of the header is ``inline``." -msgstr "" - -#: ../../library/email.message.rst:560 -msgid "" -"If none of the candidates matches any of the preferences in " -"*preferencelist*, return ``None``." -msgstr "" - -#: ../../library/email.message.rst:563 -msgid "" -"Notes: (1) For most applications the only *preferencelist* combinations that " -"really make sense are ``('plain',)``, ``('html', 'plain')``, and the default " -"``('related', 'html', 'plain')``. (2) Because matching starts with the " -"object on which ``get_body`` is called, calling ``get_body`` on a " -"``multipart/related`` will return the object itself unless *preferencelist* " -"has a non-default value. (3) Messages (or message parts) that do not specify " -"a :mailheader:`Content-Type` or whose :mailheader:`Content-Type` header is " -"invalid will be treated as if they are of type ``text/plain``, which may " -"occasionally cause ``get_body`` to return unexpected results." -msgstr "" - -#: ../../library/email.message.rst:577 -msgid "" -"Return an iterator over all of the immediate sub-parts of the message that " -"are not candidate \"body\" parts. That is, skip the first occurrence of " -"each of ``text/plain``, ``text/html``, ``multipart/related``, or ``multipart/" -"alternative`` (unless they are explicitly marked as attachments via :" -"mailheader:`Content-Disposition: attachment`), and return all remaining " -"parts. When applied directly to a ``multipart/related``, return an iterator " -"over the all the related parts except the root part (ie: the part pointed to " -"by the ``start`` parameter, or the first part if there is no ``start`` " -"parameter or the ``start`` parameter doesn't match the :mailheader:`Content-" -"ID` of any of the parts). When applied directly to a ``multipart/" -"alternative`` or a non-``multipart``, return an empty iterator." -msgstr "" - -#: ../../library/email.message.rst:593 -msgid "" -"Return an iterator over all of the immediate sub-parts of the message, which " -"will be empty for a non-``multipart``. (See also :meth:`~email.message." -"EmailMessage.walk`.)" -msgstr "" - -#: ../../library/email.message.rst:600 -msgid "" -"Call the :meth:`~email.contentmanager.ContentManager.get_content` method of " -"the *content_manager*, passing self as the message object, and passing along " -"any other arguments or keywords as additional arguments. If " -"*content_manager* is not specified, use the ``content_manager`` specified by " -"the current :mod:`~email.policy`." -msgstr "" - -#: ../../library/email.message.rst:609 -msgid "" -"Call the :meth:`~email.contentmanager.ContentManager.set_content` method of " -"the *content_manager*, passing self as the message object, and passing along " -"any other arguments or keywords as additional arguments. If " -"*content_manager* is not specified, use the ``content_manager`` specified by " -"the current :mod:`~email.policy`." -msgstr "" - -#: ../../library/email.message.rst:618 -msgid "" -"Convert a non-``multipart`` message into a ``multipart/related`` message, " -"moving any existing :mailheader:`Content-` headers and payload into a (new) " -"first part of the ``multipart``. If *boundary* is specified, use it as the " -"boundary string in the multipart, otherwise leave the boundary to be " -"automatically created when it is needed (for example, when the message is " -"serialized)." -msgstr "" - -#: ../../library/email.message.rst:628 -msgid "" -"Convert a non-``multipart`` or a ``multipart/related`` into a ``multipart/" -"alternative``, moving any existing :mailheader:`Content-` headers and " -"payload into a (new) first part of the ``multipart``. If *boundary* is " -"specified, use it as the boundary string in the multipart, otherwise leave " -"the boundary to be automatically created when it is needed (for example, " -"when the message is serialized)." -msgstr "" - -#: ../../library/email.message.rst:638 -msgid "" -"Convert a non-``multipart``, a ``multipart/related``, or a ``multipart-" -"alternative`` into a ``multipart/mixed``, moving any existing :mailheader:" -"`Content-` headers and payload into a (new) first part of the " -"``multipart``. If *boundary* is specified, use it as the boundary string in " -"the multipart, otherwise leave the boundary to be automatically created when " -"it is needed (for example, when the message is serialized)." -msgstr "" - -#: ../../library/email.message.rst:648 -msgid "" -"If the message is a ``multipart/related``, create a new message object, pass " -"all of the arguments to its :meth:`set_content` method, and :meth:`~email." -"message.Message.attach` it to the ``multipart``. If the message is a non-" -"``multipart``, call :meth:`make_related` and then proceed as above. If the " -"message is any other type of ``multipart``, raise a :exc:`TypeError`. If " -"*content_manager* is not specified, use the ``content_manager`` specified by " -"the current :mod:`~email.policy`. If the added part has no :mailheader:" -"`Content-Disposition` header, add one with the value ``inline``." -msgstr "" - -#: ../../library/email.message.rst:661 -msgid "" -"If the message is a ``multipart/alternative``, create a new message object, " -"pass all of the arguments to its :meth:`set_content` method, and :meth:" -"`~email.message.Message.attach` it to the ``multipart``. If the message is " -"a non-``multipart`` or ``multipart/related``, call :meth:`make_alternative` " -"and then proceed as above. If the message is any other type of " -"``multipart``, raise a :exc:`TypeError`. If *content_manager* is not " -"specified, use the ``content_manager`` specified by the current :mod:`~email." -"policy`." -msgstr "" - -#: ../../library/email.message.rst:673 -msgid "" -"If the message is a ``multipart/mixed``, create a new message object, pass " -"all of the arguments to its :meth:`set_content` method, and :meth:`~email." -"message.Message.attach` it to the ``multipart``. If the message is a non-" -"``multipart``, ``multipart/related``, or ``multipart/alternative``, call :" -"meth:`make_mixed` and then proceed as above. If *content_manager* is not " -"specified, use the ``content_manager`` specified by the current :mod:`~email." -"policy`. If the added part has no :mailheader:`Content-Disposition` header, " -"add one with the value ``attachment``. This method can be used both for " -"explicit attachments (:mailheader:`Content-Disposition: attachment`) and " -"``inline`` attachments (:mailheader:`Content-Disposition: inline`), by " -"passing appropriate options to the ``content_manager``." -msgstr "" - -#: ../../library/email.message.rst:689 -msgid "Remove the payload and all of the headers." -msgstr "" - -#: ../../library/email.message.rst:694 -msgid "" -"Remove the payload and all of the :mailheader:`!Content-` headers, leaving " -"all other headers intact and in their original order." -msgstr "" - -#: ../../library/email.message.rst:698 -msgid ":class:`EmailMessage` objects have the following instance attributes:" -msgstr "" - -#: ../../library/email.message.rst:703 -msgid "" -"The format of a MIME document allows for some text between the blank line " -"following the headers, and the first multipart boundary string. Normally, " -"this text is never visible in a MIME-aware mail reader because it falls " -"outside the standard MIME armor. However, when viewing the raw text of the " -"message, or when viewing the message in a non-MIME aware reader, this text " -"can become visible." -msgstr "" - -#: ../../library/email.message.rst:710 -msgid "" -"The *preamble* attribute contains this leading extra-armor text for MIME " -"documents. When the :class:`~email.parser.Parser` discovers some text after " -"the headers but before the first boundary string, it assigns this text to " -"the message's *preamble* attribute. When the :class:`~email.generator." -"Generator` is writing out the plain text representation of a MIME message, " -"and it finds the message has a *preamble* attribute, it will write this text " -"in the area between the headers and the first boundary. See :mod:`email." -"parser` and :mod:`email.generator` for details." -msgstr "" - -#: ../../library/email.message.rst:720 -msgid "" -"Note that if the message object has no preamble, the *preamble* attribute " -"will be ``None``." -msgstr "" - -#: ../../library/email.message.rst:726 -msgid "" -"The *epilogue* attribute acts the same way as the *preamble* attribute, " -"except that it contains text that appears between the last boundary and the " -"end of the message. As with the :attr:`~EmailMessage.preamble`, if there is " -"no epilog text this attribute will be ``None``." -msgstr "" - -#: ../../library/email.message.rst:734 -msgid "" -"The *defects* attribute contains a list of all the problems found when " -"parsing this message. See :mod:`email.errors` for a detailed description of " -"the possible parsing defects." -msgstr "" - -#: ../../library/email.message.rst:741 -msgid "" -"This class represents a subpart of a MIME message. It is identical to :" -"class:`EmailMessage`, except that no :mailheader:`MIME-Version` headers are " -"added when :meth:`~EmailMessage.set_content` is called, since sub-parts do " -"not need their own :mailheader:`MIME-Version` headers." -msgstr "" - -#: ../../library/email.message.rst:748 -msgid "Footnotes" -msgstr "註解" - -#: ../../library/email.message.rst:749 -msgid "" -"Originally added in 3.4 as a :term:`provisional module `. Docs for legacy message class moved to :ref:`compat32_message`." -msgstr "" - -#: ../../library/email.message.rst:753 -msgid "" -"The :class:`EmailMessage` class requires a policy that provides a " -"``content_manager`` attribute for content management methods like " -"``set_content()`` and ``get_content()`` to work. The legacy :const:`~email." -"policy.compat32` policy does not support these methods and should not be " -"used with :class:`EmailMessage`." -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-01-07 00:14+0000\n" +"PO-Revision-Date: 2018-05-23 14:44+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/email.message.rst:2 +msgid ":mod:`!email.message`: Representing an email message" +msgstr ":mod:`!email.message`：表示電子郵件訊息" + +#: ../../library/email.message.rst:10 +msgid "**Source code:** :source:`Lib/email/message.py`" +msgstr "**原始碼：**\\ :source:`Lib/email/message.py`" + +#: ../../library/email.message.rst:14 +msgid "[1]_" +msgstr "[1]_" + +#: ../../library/email.message.rst:16 +msgid "" +"The central class in the :mod:`email` package is the :class:`EmailMessage` " +"class, imported from the :mod:`email.message` module. It is the base class " +"for the :mod:`email` object model. :class:`EmailMessage` provides the core " +"functionality for setting and querying header fields, for accessing message " +"bodies, and for creating or modifying structured messages." +msgstr "" + +#: ../../library/email.message.rst:22 +msgid "" +"An email message consists of *headers* and a *payload* (which is also " +"referred to as the *content*). Headers are :rfc:`5322` or :rfc:`6532` style " +"field names and values, where the field name and value are separated by a " +"colon. The colon is not part of either the field name or the field value. " +"The payload may be a simple text message, or a binary object, or a " +"structured sequence of sub-messages each with their own set of headers and " +"their own payload. The latter type of payload is indicated by the message " +"having a MIME type such as :mimetype:`multipart/\\*` or :mimetype:`message/" +"rfc822`." +msgstr "" + +#: ../../library/email.message.rst:31 +msgid "" +"The conceptual model provided by an :class:`EmailMessage` object is that of " +"an ordered dictionary of headers coupled with a *payload* that represents " +"the :rfc:`5322` body of the message, which might be a list of sub-" +"``EmailMessage`` objects. In addition to the normal dictionary methods for " +"accessing the header names and values, there are methods for accessing " +"specialized information from the headers (for example the MIME content " +"type), for operating on the payload, for generating a serialized version of " +"the message, and for recursively walking over the object tree." +msgstr "" + +#: ../../library/email.message.rst:40 +msgid "" +"The :class:`EmailMessage` dictionary-like interface is indexed by the header " +"names, which must be ASCII values. The values of the dictionary are strings " +"with some extra methods. Headers are stored and returned in case-preserving " +"form, but field names are matched case-insensitively. The keys are ordered, " +"but unlike a real dict, there can be duplicates. Additional methods are " +"provided for working with headers that have duplicate keys." +msgstr "" + +#: ../../library/email.message.rst:47 +msgid "" +"The *payload* is either a string or bytes object, in the case of simple " +"message objects, or a list of :class:`EmailMessage` objects, for MIME " +"container documents such as :mimetype:`multipart/\\*` and :mimetype:`message/" +"rfc822` message objects." +msgstr "" + +#: ../../library/email.message.rst:55 +msgid "" +"If *policy* is specified use the rules it specifies to update and serialize " +"the representation of the message. If *policy* is not set, use the :class:" +"`~email.policy.default` policy, which follows the rules of the email RFCs " +"except for line endings (instead of the RFC mandated ``\\r\\n``, it uses the " +"Python standard ``\\n`` line endings). For more information see the :mod:" +"`~email.policy` documentation. [2]_" +msgstr "" + +#: ../../library/email.message.rst:64 +msgid "" +"Return the entire message flattened as a string. When optional *unixfrom* " +"is true, the envelope header is included in the returned string. *unixfrom* " +"defaults to ``False``. For backward compatibility with the base :class:" +"`~email.message.Message` class *maxheaderlen* is accepted, but defaults to " +"``None``, which means that by default the line length is controlled by the :" +"attr:`~email.policy.Policy.max_line_length` of the policy. The *policy* " +"argument may be used to override the default policy obtained from the " +"message instance. This can be used to control some of the formatting " +"produced by the method, since the specified *policy* will be passed to the :" +"class:`~email.generator.Generator`." +msgstr "" + +#: ../../library/email.message.rst:76 ../../library/email.message.rst:114 +msgid "" +"Flattening the message may trigger changes to the :class:`EmailMessage` if " +"defaults need to be filled in to complete the transformation to a string " +"(for example, MIME boundaries may be generated or modified)." +msgstr "" + +#: ../../library/email.message.rst:80 +msgid "" +"Note that this method is provided as a convenience and may not be the most " +"useful way to serialize messages in your application, especially if you are " +"dealing with multiple messages. See :class:`email.generator.Generator` for " +"a more flexible API for serializing messages. Note also that this method is " +"restricted to producing messages serialized as \"7 bit clean\" when :attr:" +"`~email.policy.EmailPolicy.utf8` is ``False``, which is the default." +msgstr "" + +#: ../../library/email.message.rst:88 +msgid "" +"the default behavior when *maxheaderlen* is not specified was changed from " +"defaulting to 0 to defaulting to the value of *max_line_length* from the " +"policy." +msgstr "" + +#: ../../library/email.message.rst:95 +msgid "" +"Equivalent to ``as_string(policy=self.policy.clone(utf8=True))``. Allows " +"``str(msg)`` to produce a string containing the serialized message in a " +"readable format." +msgstr "" + +#: ../../library/email.message.rst:99 +msgid "" +"the method was changed to use ``utf8=True``, thus producing an :rfc:`6531`-" +"like message representation, instead of being a direct alias for :meth:" +"`as_string`." +msgstr "" + +#: ../../library/email.message.rst:106 +msgid "" +"Return the entire message flattened as a bytes object. When optional " +"*unixfrom* is true, the envelope header is included in the returned string. " +"*unixfrom* defaults to ``False``. The *policy* argument may be used to " +"override the default policy obtained from the message instance. This can be " +"used to control some of the formatting produced by the method, since the " +"specified *policy* will be passed to the :class:`~email.generator." +"BytesGenerator`." +msgstr "" + +#: ../../library/email.message.rst:118 +msgid "" +"Note that this method is provided as a convenience and may not be the most " +"useful way to serialize messages in your application, especially if you are " +"dealing with multiple messages. See :class:`email.generator.BytesGenerator` " +"for a more flexible API for serializing messages." +msgstr "" + +#: ../../library/email.message.rst:127 +msgid "" +"Equivalent to :meth:`.as_bytes`. Allows ``bytes(msg)`` to produce a bytes " +"object containing the serialized message." +msgstr "" + +#: ../../library/email.message.rst:133 +msgid "" +"Return ``True`` if the message's payload is a list of sub-\\ :class:" +"`EmailMessage` objects, otherwise return ``False``. When :meth:" +"`is_multipart` returns ``False``, the payload should be a string object " +"(which might be a CTE encoded binary payload). Note that :meth:" +"`is_multipart` returning ``True`` does not necessarily mean that \"msg." +"get_content_maintype() == 'multipart'\" will return the ``True``. For " +"example, ``is_multipart`` will return ``True`` when the :class:" +"`EmailMessage` is of type ``message/rfc822``." +msgstr "" + +#: ../../library/email.message.rst:145 +msgid "" +"Set the message's envelope header to *unixfrom*, which should be a string. " +"(See :class:`~mailbox.mboxMessage` for a brief description of this header.)" +msgstr "" + +#: ../../library/email.message.rst:152 +msgid "" +"Return the message's envelope header. Defaults to ``None`` if the envelope " +"header was never set." +msgstr "" + +#: ../../library/email.message.rst:156 +msgid "" +"The following methods implement the mapping-like interface for accessing the " +"message's headers. Note that there are some semantic differences between " +"these methods and a normal mapping (i.e. dictionary) interface. For " +"example, in a dictionary there are no duplicate keys, but here there may be " +"duplicate message headers. Also, in dictionaries there is no guaranteed " +"order to the keys returned by :meth:`keys`, but in an :class:`EmailMessage` " +"object, headers are always returned in the order they appeared in the " +"original message, or in which they were added to the message later. Any " +"header deleted and then re-added is always appended to the end of the header " +"list." +msgstr "" + +#: ../../library/email.message.rst:167 +msgid "" +"These semantic differences are intentional and are biased toward convenience " +"in the most common use cases." +msgstr "" + +#: ../../library/email.message.rst:170 +msgid "" +"Note that in all cases, any envelope header present in the message is not " +"included in the mapping interface." +msgstr "" + +#: ../../library/email.message.rst:176 +msgid "Return the total number of headers, including duplicates." +msgstr "" + +#: ../../library/email.message.rst:181 +msgid "" +"Return ``True`` if the message object has a field named *name*. Matching is " +"done without regard to case and *name* does not include the trailing colon. " +"Used for the ``in`` operator. For example::" +msgstr "" + +#: ../../library/email.message.rst:185 +msgid "" +"if 'message-id' in myMessage:\n" +" print('Message-ID:', myMessage['message-id'])" +msgstr "" +"if 'message-id' in myMessage:\n" +" print('Message-ID:', myMessage['message-id'])" + +#: ../../library/email.message.rst:191 +msgid "" +"Return the value of the named header field. *name* does not include the " +"colon field separator. If the header is missing, ``None`` is returned; a :" +"exc:`KeyError` is never raised." +msgstr "" + +#: ../../library/email.message.rst:195 +msgid "" +"Note that if the named field appears more than once in the message's " +"headers, exactly which of those field values will be returned is undefined. " +"Use the :meth:`get_all` method to get the values of all the extant headers " +"named *name*." +msgstr "" + +#: ../../library/email.message.rst:200 +msgid "" +"Using the standard (non-``compat32``) policies, the returned value is an " +"instance of a subclass of :class:`email.headerregistry.BaseHeader`." +msgstr "" + +#: ../../library/email.message.rst:206 +msgid "" +"Add a header to the message with field name *name* and value *val*. The " +"field is appended to the end of the message's existing headers." +msgstr "" + +#: ../../library/email.message.rst:209 +msgid "" +"Note that this does *not* overwrite or delete any existing header with the " +"same name. If you want to ensure that the new header is the only one " +"present in the message with field name *name*, delete the field first, e.g.::" +msgstr "" + +#: ../../library/email.message.rst:213 +msgid "" +"del msg['subject']\n" +"msg['subject'] = 'Python roolz!'" +msgstr "" +"del msg['subject']\n" +"msg['subject'] = 'Python roolz!'" + +#: ../../library/email.message.rst:216 +msgid "" +"If the :mod:`policy ` defines certain headers to be unique (as " +"the standard policies do), this method may raise a :exc:`ValueError` when an " +"attempt is made to assign a value to such a header when one already exists. " +"This behavior is intentional for consistency's sake, but do not depend on it " +"as we may choose to make such assignments do an automatic deletion of the " +"existing header in the future." +msgstr "" + +#: ../../library/email.message.rst:226 +msgid "" +"Delete all occurrences of the field with name *name* from the message's " +"headers. No exception is raised if the named field isn't present in the " +"headers." +msgstr "" + +#: ../../library/email.message.rst:233 +msgid "Return a list of all the message's header field names." +msgstr "" + +#: ../../library/email.message.rst:238 +msgid "Return a list of all the message's field values." +msgstr "" + +#: ../../library/email.message.rst:243 +msgid "" +"Return a list of 2-tuples containing all the message's field headers and " +"values." +msgstr "" + +#: ../../library/email.message.rst:249 +msgid "" +"Return the value of the named header field. This is identical to :meth:" +"`~object.__getitem__` except that optional *failobj* is returned if the " +"named header is missing (*failobj* defaults to ``None``)." +msgstr "" + +#: ../../library/email.message.rst:254 +msgid "Here are some additional useful header related methods:" +msgstr "" + +#: ../../library/email.message.rst:259 +msgid "" +"Return a list of all the values for the field named *name*. If there are no " +"such named headers in the message, *failobj* is returned (defaults to " +"``None``)." +msgstr "" + +#: ../../library/email.message.rst:266 +msgid "" +"Extended header setting. This method is similar to :meth:`__setitem__` " +"except that additional header parameters can be provided as keyword " +"arguments. *_name* is the header field to add and *_value* is the *primary* " +"value for the header." +msgstr "" + +#: ../../library/email.message.rst:271 +msgid "" +"For each item in the keyword argument dictionary *_params*, the key is taken " +"as the parameter name, with underscores converted to dashes (since dashes " +"are illegal in Python identifiers). Normally, the parameter will be added " +"as ``key=\"value\"`` unless the value is ``None``, in which case only the " +"key will be added." +msgstr "" + +#: ../../library/email.message.rst:277 +msgid "" +"If the value contains non-ASCII characters, the charset and language may be " +"explicitly controlled by specifying the value as a three tuple in the format " +"``(CHARSET, LANGUAGE, VALUE)``, where ``CHARSET`` is a string naming the " +"charset to be used to encode the value, ``LANGUAGE`` can usually be set to " +"``None`` or the empty string (see :rfc:`2231` for other possibilities), and " +"``VALUE`` is the string value containing non-ASCII code points. If a three " +"tuple is not passed and the value contains non-ASCII characters, it is " +"automatically encoded in :rfc:`2231` format using a ``CHARSET`` of ``utf-8`` " +"and a ``LANGUAGE`` of ``None``." +msgstr "" + +#: ../../library/email.message.rst:287 +msgid "Here is an example::" +msgstr "以下是個範例： ::" + +#: ../../library/email.message.rst:289 +msgid "msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')" +msgstr "" +"msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')" + +#: ../../library/email.message.rst:291 +msgid "This will add a header that looks like ::" +msgstr "" + +#: ../../library/email.message.rst:293 +msgid "Content-Disposition: attachment; filename=\"bud.gif\"" +msgstr "Content-Disposition: attachment; filename=\"bud.gif\"" + +#: ../../library/email.message.rst:295 +msgid "An example of the extended interface with non-ASCII characters::" +msgstr "" + +#: ../../library/email.message.rst:297 +msgid "" +"msg.add_header('Content-Disposition', 'attachment',\n" +" filename=('iso-8859-1', '', 'Fußballer.ppt'))" +msgstr "" + +#: ../../library/email.message.rst:303 +msgid "" +"Replace a header. Replace the first header found in the message that " +"matches *_name*, retaining header order and field name case of the original " +"header. If no matching header is found, raise a :exc:`KeyError`." +msgstr "" + +#: ../../library/email.message.rst:311 +msgid "" +"Return the message's content type, coerced to lower case of the form :" +"mimetype:`maintype/subtype`. If there is no :mailheader:`Content-Type` " +"header in the message return the value returned by :meth:" +"`get_default_type`. If the :mailheader:`Content-Type` header is invalid, " +"return ``text/plain``." +msgstr "" + +#: ../../library/email.message.rst:317 +msgid "" +"(According to :rfc:`2045`, messages always have a default type, :meth:" +"`get_content_type` will always return a value. :rfc:`2045` defines a " +"message's default type to be :mimetype:`text/plain` unless it appears inside " +"a :mimetype:`multipart/digest` container, in which case it would be :" +"mimetype:`message/rfc822`. If the :mailheader:`Content-Type` header has an " +"invalid type specification, :rfc:`2045` mandates that the default type be :" +"mimetype:`text/plain`.)" +msgstr "" + +#: ../../library/email.message.rst:328 +msgid "" +"Return the message's main content type. This is the :mimetype:`maintype` " +"part of the string returned by :meth:`get_content_type`." +msgstr "" + +#: ../../library/email.message.rst:334 +msgid "" +"Return the message's sub-content type. This is the :mimetype:`subtype` part " +"of the string returned by :meth:`get_content_type`." +msgstr "" + +#: ../../library/email.message.rst:340 +msgid "" +"Return the default content type. Most messages have a default content type " +"of :mimetype:`text/plain`, except for messages that are subparts of :" +"mimetype:`multipart/digest` containers. Such subparts have a default " +"content type of :mimetype:`message/rfc822`." +msgstr "" + +#: ../../library/email.message.rst:348 +msgid "" +"Set the default content type. *ctype* should either be :mimetype:`text/" +"plain` or :mimetype:`message/rfc822`, although this is not enforced. The " +"default content type is not stored in the :mailheader:`Content-Type` header, " +"so it only affects the return value of the ``get_content_type`` methods when " +"no :mailheader:`Content-Type` header is present in the message." +msgstr "" + +#: ../../library/email.message.rst:359 +msgid "" +"Set a parameter in the :mailheader:`Content-Type` header. If the parameter " +"already exists in the header, replace its value with *value*. When *header* " +"is ``Content-Type`` (the default) and the header does not yet exist in the " +"message, add it, set its value to :mimetype:`text/plain`, and append the new " +"parameter value. Optional *header* specifies an alternative header to :" +"mailheader:`Content-Type`." +msgstr "" + +#: ../../library/email.message.rst:366 +msgid "" +"If the value contains non-ASCII characters, the charset and language may be " +"explicitly specified using the optional *charset* and *language* " +"parameters. Optional *language* specifies the :rfc:`2231` language, " +"defaulting to the empty string. Both *charset* and *language* should be " +"strings. The default is to use the ``utf8`` *charset* and ``None`` for the " +"*language*." +msgstr "" + +#: ../../library/email.message.rst:373 +msgid "" +"If *replace* is ``False`` (the default) the header is moved to the end of " +"the list of headers. If *replace* is ``True``, the header will be updated " +"in place." +msgstr "" + +#: ../../library/email.message.rst:377 ../../library/email.message.rst:394 +msgid "" +"Use of the *requote* parameter with :class:`EmailMessage` objects is " +"deprecated." +msgstr "" + +#: ../../library/email.message.rst:380 +msgid "" +"Note that existing parameter values of headers may be accessed through the :" +"attr:`~email.headerregistry.ParameterizedMIMEHeader.params` attribute of the " +"header value (for example, ``msg['Content-Type'].params['charset']``)." +msgstr "" + +#: ../../library/email.message.rst:384 +msgid "``replace`` keyword was added." +msgstr "新增 ``replace`` 關鍵字。" + +#: ../../library/email.message.rst:389 +msgid "" +"Remove the given parameter completely from the :mailheader:`Content-Type` " +"header. The header will be re-written in place without the parameter or its " +"value. Optional *header* specifies an alternative to :mailheader:`Content-" +"Type`." +msgstr "" + +#: ../../library/email.message.rst:400 +msgid "" +"Return the value of the ``filename`` parameter of the :mailheader:`Content-" +"Disposition` header of the message. If the header does not have a " +"``filename`` parameter, this method falls back to looking for the ``name`` " +"parameter on the :mailheader:`Content-Type` header. If neither is found, or " +"the header is missing, then *failobj* is returned. The returned string will " +"always be unquoted as per :func:`email.utils.unquote`." +msgstr "" + +#: ../../library/email.message.rst:411 +msgid "" +"Return the value of the ``boundary`` parameter of the :mailheader:`Content-" +"Type` header of the message, or *failobj* if either the header is missing, " +"or has no ``boundary`` parameter. The returned string will always be " +"unquoted as per :func:`email.utils.unquote`." +msgstr "" + +#: ../../library/email.message.rst:419 +msgid "" +"Set the ``boundary`` parameter of the :mailheader:`Content-Type` header to " +"*boundary*. :meth:`set_boundary` will always quote *boundary* if " +"necessary. A :exc:`~email.errors.HeaderParseError` is raised if the message " +"object has no :mailheader:`Content-Type` header." +msgstr "" + +#: ../../library/email.message.rst:424 +msgid "" +"Note that using this method is subtly different from deleting the old :" +"mailheader:`Content-Type` header and adding a new one with the new boundary " +"via :meth:`add_header`, because :meth:`set_boundary` preserves the order of " +"the :mailheader:`Content-Type` header in the list of headers." +msgstr "" + +#: ../../library/email.message.rst:433 +msgid "" +"Return the ``charset`` parameter of the :mailheader:`Content-Type` header, " +"coerced to lower case. If there is no :mailheader:`Content-Type` header, or " +"if that header has no ``charset`` parameter, *failobj* is returned." +msgstr "" + +#: ../../library/email.message.rst:440 +msgid "" +"Return a list containing the character set names in the message. If the " +"message is a :mimetype:`multipart`, then the list will contain one element " +"for each subpart in the payload, otherwise, it will be a list of length 1." +msgstr "" + +#: ../../library/email.message.rst:444 +msgid "" +"Each item in the list will be a string which is the value of the ``charset`` " +"parameter in the :mailheader:`Content-Type` header for the represented " +"subpart. If the subpart has no :mailheader:`Content-Type` header, no " +"``charset`` parameter, or is not of the :mimetype:`text` main MIME type, " +"then that item in the returned list will be *failobj*." +msgstr "" + +#: ../../library/email.message.rst:453 +msgid "" +"Return ``True`` if there is a :mailheader:`Content-Disposition` header and " +"its (case insensitive) value is ``attachment``, ``False`` otherwise." +msgstr "" + +#: ../../library/email.message.rst:456 +msgid "" +"is_attachment is now a method instead of a property, for consistency with :" +"meth:`~email.message.Message.is_multipart`." +msgstr "" + +#: ../../library/email.message.rst:463 +msgid "" +"Return the lowercased value (without parameters) of the message's :" +"mailheader:`Content-Disposition` header if it has one, or ``None``. The " +"possible values for this method are *inline*, *attachment* or ``None`` if " +"the message follows :rfc:`2183`." +msgstr "" + +#: ../../library/email.message.rst:471 +msgid "" +"The following methods relate to interrogating and manipulating the content " +"(payload) of the message." +msgstr "" + +#: ../../library/email.message.rst:477 +msgid "" +"The :meth:`walk` method is an all-purpose generator which can be used to " +"iterate over all the parts and subparts of a message object tree, in depth-" +"first traversal order. You will typically use :meth:`walk` as the iterator " +"in a ``for`` loop; each iteration returns the next subpart." +msgstr "" + +#: ../../library/email.message.rst:482 +msgid "" +"Here's an example that prints the MIME type of every part of a multipart " +"message structure:" +msgstr "" + +#: ../../library/email.message.rst:491 +msgid "" +">>> for part in msg.walk():\n" +"... print(part.get_content_type())\n" +"multipart/report\n" +"text/plain\n" +"message/delivery-status\n" +"text/plain\n" +"text/plain\n" +"message/rfc822\n" +"text/plain" +msgstr "" +">>> for part in msg.walk():\n" +"... print(part.get_content_type())\n" +"multipart/report\n" +"text/plain\n" +"message/delivery-status\n" +"text/plain\n" +"text/plain\n" +"message/rfc822\n" +"text/plain" + +#: ../../library/email.message.rst:503 +msgid "" +"``walk`` iterates over the subparts of any part where :meth:`is_multipart` " +"returns ``True``, even though ``msg.get_content_maintype() == 'multipart'`` " +"may return ``False``. We can see this in our example by making use of the " +"``_structure`` debug helper function:" +msgstr "" + +#: ../../library/email.message.rst:509 +msgid "" +">>> from email.iterators import _structure\n" +">>> for part in msg.walk():\n" +"... print(part.get_content_maintype() == 'multipart',\n" +"... part.is_multipart())\n" +"True True\n" +"False False\n" +"False True\n" +"False False\n" +"False False\n" +"False True\n" +"False False\n" +">>> _structure(msg)\n" +"multipart/report\n" +" text/plain\n" +" message/delivery-status\n" +" text/plain\n" +" text/plain\n" +" message/rfc822\n" +" text/plain" +msgstr "" +">>> from email.iterators import _structure\n" +">>> for part in msg.walk():\n" +"... print(part.get_content_maintype() == 'multipart',\n" +"... part.is_multipart())\n" +"True True\n" +"False False\n" +"False True\n" +"False False\n" +"False False\n" +"False True\n" +"False False\n" +">>> _structure(msg)\n" +"multipart/report\n" +" text/plain\n" +" message/delivery-status\n" +" text/plain\n" +" text/plain\n" +" message/rfc822\n" +" text/plain" + +#: ../../library/email.message.rst:531 +msgid "" +"Here the ``message`` parts are not ``multiparts``, but they do contain " +"subparts. ``is_multipart()`` returns ``True`` and ``walk`` descends into the " +"subparts." +msgstr "" + +#: ../../library/email.message.rst:538 +msgid "" +"Return the MIME part that is the best candidate to be the \"body\" of the " +"message." +msgstr "" + +#: ../../library/email.message.rst:541 +msgid "" +"*preferencelist* must be a sequence of strings from the set ``related``, " +"``html``, and ``plain``, and indicates the order of preference for the " +"content type of the part returned." +msgstr "" + +#: ../../library/email.message.rst:545 +msgid "" +"Start looking for candidate matches with the object on which the " +"``get_body`` method is called." +msgstr "" + +#: ../../library/email.message.rst:548 +msgid "" +"If ``related`` is not included in *preferencelist*, consider the root part " +"(or subpart of the root part) of any related encountered as a candidate if " +"the (sub-)part matches a preference." +msgstr "" + +#: ../../library/email.message.rst:552 +msgid "" +"When encountering a ``multipart/related``, check the ``start`` parameter and " +"if a part with a matching :mailheader:`Content-ID` is found, consider only " +"it when looking for candidate matches. Otherwise consider only the first " +"(default root) part of the ``multipart/related``." +msgstr "" + +#: ../../library/email.message.rst:557 +msgid "" +"If a part has a :mailheader:`Content-Disposition` header, only consider the " +"part a candidate match if the value of the header is ``inline``." +msgstr "" + +#: ../../library/email.message.rst:560 +msgid "" +"If none of the candidates matches any of the preferences in " +"*preferencelist*, return ``None``." +msgstr "" + +#: ../../library/email.message.rst:563 +msgid "" +"Notes: (1) For most applications the only *preferencelist* combinations that " +"really make sense are ``('plain',)``, ``('html', 'plain')``, and the default " +"``('related', 'html', 'plain')``. (2) Because matching starts with the " +"object on which ``get_body`` is called, calling ``get_body`` on a " +"``multipart/related`` will return the object itself unless *preferencelist* " +"has a non-default value. (3) Messages (or message parts) that do not specify " +"a :mailheader:`Content-Type` or whose :mailheader:`Content-Type` header is " +"invalid will be treated as if they are of type ``text/plain``, which may " +"occasionally cause ``get_body`` to return unexpected results." +msgstr "" + +#: ../../library/email.message.rst:577 +msgid "" +"Return an iterator over all of the immediate sub-parts of the message that " +"are not candidate \"body\" parts. That is, skip the first occurrence of " +"each of ``text/plain``, ``text/html``, ``multipart/related``, or ``multipart/" +"alternative`` (unless they are explicitly marked as attachments via :" +"mailheader:`Content-Disposition: attachment`), and return all remaining " +"parts. When applied directly to a ``multipart/related``, return an iterator " +"over the all the related parts except the root part (ie: the part pointed to " +"by the ``start`` parameter, or the first part if there is no ``start`` " +"parameter or the ``start`` parameter doesn't match the :mailheader:`Content-" +"ID` of any of the parts). When applied directly to a ``multipart/" +"alternative`` or a non-``multipart``, return an empty iterator." +msgstr "" + +#: ../../library/email.message.rst:593 +msgid "" +"Return an iterator over all of the immediate sub-parts of the message, which " +"will be empty for a non-``multipart``. (See also :meth:`~email.message." +"EmailMessage.walk`.)" +msgstr "" + +#: ../../library/email.message.rst:600 +msgid "" +"Call the :meth:`~email.contentmanager.ContentManager.get_content` method of " +"the *content_manager*, passing self as the message object, and passing along " +"any other arguments or keywords as additional arguments. If " +"*content_manager* is not specified, use the ``content_manager`` specified by " +"the current :mod:`~email.policy`." +msgstr "" + +#: ../../library/email.message.rst:609 +msgid "" +"Call the :meth:`~email.contentmanager.ContentManager.set_content` method of " +"the *content_manager*, passing self as the message object, and passing along " +"any other arguments or keywords as additional arguments. If " +"*content_manager* is not specified, use the ``content_manager`` specified by " +"the current :mod:`~email.policy`." +msgstr "" + +#: ../../library/email.message.rst:618 +msgid "" +"Convert a non-``multipart`` message into a ``multipart/related`` message, " +"moving any existing :mailheader:`Content-` headers and payload into a (new) " +"first part of the ``multipart``. If *boundary* is specified, use it as the " +"boundary string in the multipart, otherwise leave the boundary to be " +"automatically created when it is needed (for example, when the message is " +"serialized)." +msgstr "" + +#: ../../library/email.message.rst:628 +msgid "" +"Convert a non-``multipart`` or a ``multipart/related`` into a ``multipart/" +"alternative``, moving any existing :mailheader:`Content-` headers and " +"payload into a (new) first part of the ``multipart``. If *boundary* is " +"specified, use it as the boundary string in the multipart, otherwise leave " +"the boundary to be automatically created when it is needed (for example, " +"when the message is serialized)." +msgstr "" + +#: ../../library/email.message.rst:638 +msgid "" +"Convert a non-``multipart``, a ``multipart/related``, or a ``multipart-" +"alternative`` into a ``multipart/mixed``, moving any existing :mailheader:" +"`Content-` headers and payload into a (new) first part of the " +"``multipart``. If *boundary* is specified, use it as the boundary string in " +"the multipart, otherwise leave the boundary to be automatically created when " +"it is needed (for example, when the message is serialized)." +msgstr "" + +#: ../../library/email.message.rst:648 +msgid "" +"If the message is a ``multipart/related``, create a new message object, pass " +"all of the arguments to its :meth:`set_content` method, and :meth:`~email." +"message.Message.attach` it to the ``multipart``. If the message is a non-" +"``multipart``, call :meth:`make_related` and then proceed as above. If the " +"message is any other type of ``multipart``, raise a :exc:`TypeError`. If " +"*content_manager* is not specified, use the ``content_manager`` specified by " +"the current :mod:`~email.policy`. If the added part has no :mailheader:" +"`Content-Disposition` header, add one with the value ``inline``." +msgstr "" + +#: ../../library/email.message.rst:661 +msgid "" +"If the message is a ``multipart/alternative``, create a new message object, " +"pass all of the arguments to its :meth:`set_content` method, and :meth:" +"`~email.message.Message.attach` it to the ``multipart``. If the message is " +"a non-``multipart`` or ``multipart/related``, call :meth:`make_alternative` " +"and then proceed as above. If the message is any other type of " +"``multipart``, raise a :exc:`TypeError`. If *content_manager* is not " +"specified, use the ``content_manager`` specified by the current :mod:`~email." +"policy`." +msgstr "" + +#: ../../library/email.message.rst:673 +msgid "" +"If the message is a ``multipart/mixed``, create a new message object, pass " +"all of the arguments to its :meth:`set_content` method, and :meth:`~email." +"message.Message.attach` it to the ``multipart``. If the message is a non-" +"``multipart``, ``multipart/related``, or ``multipart/alternative``, call :" +"meth:`make_mixed` and then proceed as above. If *content_manager* is not " +"specified, use the ``content_manager`` specified by the current :mod:`~email." +"policy`. If the added part has no :mailheader:`Content-Disposition` header, " +"add one with the value ``attachment``. This method can be used both for " +"explicit attachments (:mailheader:`Content-Disposition: attachment`) and " +"``inline`` attachments (:mailheader:`Content-Disposition: inline`), by " +"passing appropriate options to the ``content_manager``." +msgstr "" + +#: ../../library/email.message.rst:689 +msgid "Remove the payload and all of the headers." +msgstr "" + +#: ../../library/email.message.rst:694 +msgid "" +"Remove the payload and all of the :mailheader:`!Content-` headers, leaving " +"all other headers intact and in their original order." +msgstr "" + +#: ../../library/email.message.rst:698 +msgid ":class:`EmailMessage` objects have the following instance attributes:" +msgstr "" + +#: ../../library/email.message.rst:703 +msgid "" +"The format of a MIME document allows for some text between the blank line " +"following the headers, and the first multipart boundary string. Normally, " +"this text is never visible in a MIME-aware mail reader because it falls " +"outside the standard MIME armor. However, when viewing the raw text of the " +"message, or when viewing the message in a non-MIME aware reader, this text " +"can become visible." +msgstr "" + +#: ../../library/email.message.rst:710 +msgid "" +"The *preamble* attribute contains this leading extra-armor text for MIME " +"documents. When the :class:`~email.parser.Parser` discovers some text after " +"the headers but before the first boundary string, it assigns this text to " +"the message's *preamble* attribute. When the :class:`~email.generator." +"Generator` is writing out the plain text representation of a MIME message, " +"and it finds the message has a *preamble* attribute, it will write this text " +"in the area between the headers and the first boundary. See :mod:`email." +"parser` and :mod:`email.generator` for details." +msgstr "" + +#: ../../library/email.message.rst:720 +msgid "" +"Note that if the message object has no preamble, the *preamble* attribute " +"will be ``None``." +msgstr "" + +#: ../../library/email.message.rst:726 +msgid "" +"The *epilogue* attribute acts the same way as the *preamble* attribute, " +"except that it contains text that appears between the last boundary and the " +"end of the message. As with the :attr:`~EmailMessage.preamble`, if there is " +"no epilog text this attribute will be ``None``." +msgstr "" + +#: ../../library/email.message.rst:734 +msgid "" +"The *defects* attribute contains a list of all the problems found when " +"parsing this message. See :mod:`email.errors` for a detailed description of " +"the possible parsing defects." +msgstr "" + +#: ../../library/email.message.rst:741 +msgid "" +"This class represents a subpart of a MIME message. It is identical to :" +"class:`EmailMessage`, except that no :mailheader:`MIME-Version` headers are " +"added when :meth:`~EmailMessage.set_content` is called, since sub-parts do " +"not need their own :mailheader:`MIME-Version` headers." +msgstr "" + +#: ../../library/email.message.rst:748 +msgid "Footnotes" +msgstr "註解" + +#: ../../library/email.message.rst:749 +msgid "" +"Originally added in 3.4 as a :term:`provisional module `. Docs for legacy message class moved to :ref:`compat32_message`." +msgstr "" + +#: ../../library/email.message.rst:753 +msgid "" +"The :class:`EmailMessage` class requires a policy that provides a " +"``content_manager`` attribute for content management methods like " +"``set_content()`` and ``get_content()`` to work. The legacy :const:`~email." +"policy.compat32` policy does not support these methods and should not be " +"used with :class:`EmailMessage`." +msgstr "" diff --git a/library/email.mime.po b/library/email.mime.po index e51a1ffd94..3a9f50d55c 100644 --- a/library/email.mime.po +++ b/library/email.mime.po @@ -1,302 +1,302 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-05-09 00:03+0000\n" -"PO-Revision-Date: 2018-05-23 16:00+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/email.mime.rst:2 -msgid ":mod:`!email.mime`: Creating email and MIME objects from scratch" -msgstr ":mod:`!email.mime`：從頭開始建立電子郵件和 MIME 物件" - -#: ../../library/email.mime.rst:7 -msgid "**Source code:** :source:`Lib/email/mime/`" -msgstr "**原始碼：**\\ :source:`Lib/email/mime/`" - -#: ../../library/email.mime.rst:11 -msgid "" -"This module is part of the legacy (``Compat32``) email API. Its " -"functionality is partially replaced by the :mod:`~email.contentmanager` in " -"the new API, but in certain applications these classes may still be useful, " -"even in non-legacy code." -msgstr "" - -#: ../../library/email.mime.rst:16 -msgid "" -"Ordinarily, you get a message object structure by passing a file or some " -"text to a parser, which parses the text and returns the root message " -"object. However you can also build a complete message structure from " -"scratch, or even individual :class:`~email.message.Message` objects by " -"hand. In fact, you can also take an existing structure and add new :class:" -"`~email.message.Message` objects, move them around, etc. This makes a very " -"convenient interface for slicing-and-dicing MIME messages." -msgstr "" - -#: ../../library/email.mime.rst:24 -msgid "" -"You can create a new object structure by creating :class:`~email.message." -"Message` instances, adding attachments and all the appropriate headers " -"manually. For MIME messages though, the :mod:`email` package provides some " -"convenient subclasses to make things easier." -msgstr "" - -#: ../../library/email.mime.rst:29 -msgid "Here are the classes:" -msgstr "" - -#: ../../library/email.mime.rst:35 -msgid "Module: :mod:`email.mime.base`" -msgstr "模組：:mod:`email.mime.base`" - -#: ../../library/email.mime.rst:37 -msgid "" -"This is the base class for all the MIME-specific subclasses of :class:" -"`~email.message.Message`. Ordinarily you won't create instances " -"specifically of :class:`MIMEBase`, although you could. :class:`MIMEBase` is " -"provided primarily as a convenient base class for more specific MIME-aware " -"subclasses." -msgstr "" - -#: ../../library/email.mime.rst:43 -msgid "" -"*_maintype* is the :mailheader:`Content-Type` major type (e.g. :mimetype:" -"`text` or :mimetype:`image`), and *_subtype* is the :mailheader:`Content-" -"Type` minor type (e.g. :mimetype:`plain` or :mimetype:`gif`). *_params* is " -"a parameter key/value dictionary and is passed directly to :meth:`Message." -"add_header `." -msgstr "" - -#: ../../library/email.mime.rst:49 -msgid "" -"If *policy* is specified, (defaults to the :class:`compat32 ` policy) it will be passed to :class:`~email.message.Message`." -msgstr "" - -#: ../../library/email.mime.rst:53 -msgid "" -"The :class:`MIMEBase` class always adds a :mailheader:`Content-Type` header " -"(based on *_maintype*, *_subtype*, and *_params*), and a :mailheader:`MIME-" -"Version` header (always set to ``1.0``)." -msgstr "" - -#: ../../library/email.mime.rst:57 ../../library/email.mime.rst:104 -#: ../../library/email.mime.rst:135 ../../library/email.mime.rst:169 -#: ../../library/email.mime.rst:205 ../../library/email.mime.rst:225 -#: ../../library/email.mime.rst:259 -msgid "Added *policy* keyword-only parameter." -msgstr "新增僅限關鍵字參數 *policy*。" - -#: ../../library/email.mime.rst:65 -msgid "Module: :mod:`email.mime.nonmultipart`" -msgstr "模組：:mod:`email.mime.nonmultipart`" - -#: ../../library/email.mime.rst:67 -msgid "" -"A subclass of :class:`~email.mime.base.MIMEBase`, this is an intermediate " -"base class for MIME messages that are not :mimetype:`multipart`. The " -"primary purpose of this class is to prevent the use of the :meth:`~email." -"message.Message.attach` method, which only makes sense for :mimetype:" -"`multipart` messages. If :meth:`~email.message.Message.attach` is called, " -"a :exc:`~email.errors.MultipartConversionError` exception is raised." -msgstr "" - -#: ../../library/email.mime.rst:80 -msgid "Module: :mod:`email.mime.multipart`" -msgstr "模組：:mod:`email.mime.multipart`" - -#: ../../library/email.mime.rst:82 -msgid "" -"A subclass of :class:`~email.mime.base.MIMEBase`, this is an intermediate " -"base class for MIME messages that are :mimetype:`multipart`. Optional " -"*_subtype* defaults to :mimetype:`mixed`, but can be used to specify the " -"subtype of the message. A :mailheader:`Content-Type` header of :mimetype:" -"`multipart/_subtype` will be added to the message object. A :mailheader:" -"`MIME-Version` header will also be added." -msgstr "" - -#: ../../library/email.mime.rst:89 -msgid "" -"Optional *boundary* is the multipart boundary string. When ``None`` (the " -"default), the boundary is calculated when needed (for example, when the " -"message is serialized)." -msgstr "" - -#: ../../library/email.mime.rst:93 -msgid "" -"*_subparts* is a sequence of initial subparts for the payload. It must be " -"possible to convert this sequence to a list. You can always attach new " -"subparts to the message by using the :meth:`Message.attach ` method." -msgstr "" - -#: ../../library/email.mime.rst:98 ../../library/email.mime.rst:131 -#: ../../library/email.mime.rst:165 ../../library/email.mime.rst:200 -#: ../../library/email.mime.rst:223 ../../library/email.mime.rst:254 -msgid "" -"Optional *policy* argument defaults to :class:`compat32 `." -msgstr "" - -#: ../../library/email.mime.rst:100 -msgid "" -"Additional parameters for the :mailheader:`Content-Type` header are taken " -"from the keyword arguments, or passed into the *_params* argument, which is " -"a keyword dictionary." -msgstr "" - -#: ../../library/email.mime.rst:113 -msgid "Module: :mod:`email.mime.application`" -msgstr "模組：:mod:`email.mime.application`" - -#: ../../library/email.mime.rst:115 -msgid "" -"A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the :class:" -"`MIMEApplication` class is used to represent MIME message objects of major " -"type :mimetype:`application`. *_data* contains the bytes for the raw " -"application data. Optional *_subtype* specifies the MIME subtype and " -"defaults to :mimetype:`octet-stream`." -msgstr "" - -#: ../../library/email.mime.rst:121 -msgid "" -"Optional *_encoder* is a callable (i.e. function) which will perform the " -"actual encoding of the data for transport. This callable takes one " -"argument, which is the :class:`MIMEApplication` instance. It should use :" -"meth:`~email.message.Message.get_payload` and :meth:`~email.message.Message." -"set_payload` to change the payload to encoded form. It should also add any :" -"mailheader:`Content-Transfer-Encoding` or other headers to the message " -"object as necessary. The default encoding is base64. See the :mod:`email." -"encoders` module for a list of the built-in encoders." -msgstr "" - -#: ../../library/email.mime.rst:133 ../../library/email.mime.rst:167 -msgid "*_params* are passed straight through to the base class constructor." -msgstr "" - -#: ../../library/email.mime.rst:144 -msgid "Module: :mod:`email.mime.audio`" -msgstr "模組：:mod:`email.mime.audio`" - -#: ../../library/email.mime.rst:146 -msgid "" -"A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the :class:" -"`MIMEAudio` class is used to create MIME message objects of major type :" -"mimetype:`audio`. *_audiodata* contains the bytes for the raw audio data. " -"If this data can be decoded as au, wav, aiff, or aifc, then the subtype will " -"be automatically included in the :mailheader:`Content-Type` header. " -"Otherwise you can explicitly specify the audio subtype via the *_subtype* " -"argument. If the minor type could not be guessed and *_subtype* was not " -"given, then :exc:`TypeError` is raised." -msgstr "" - -#: ../../library/email.mime.rst:155 -msgid "" -"Optional *_encoder* is a callable (i.e. function) which will perform the " -"actual encoding of the audio data for transport. This callable takes one " -"argument, which is the :class:`MIMEAudio` instance. It should use :meth:" -"`~email.message.Message.get_payload` and :meth:`~email.message.Message." -"set_payload` to change the payload to encoded form. It should also add any :" -"mailheader:`Content-Transfer-Encoding` or other headers to the message " -"object as necessary. The default encoding is base64. See the :mod:`email." -"encoders` module for a list of the built-in encoders." -msgstr "" - -#: ../../library/email.mime.rst:178 -msgid "Module: :mod:`email.mime.image`" -msgstr "模組：:mod:`email.mime.image`" - -#: ../../library/email.mime.rst:180 -msgid "" -"A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the :class:" -"`MIMEImage` class is used to create MIME message objects of major type :" -"mimetype:`image`. *_imagedata* contains the bytes for the raw image data. " -"If this data type can be detected (jpeg, png, gif, tiff, rgb, pbm, pgm, ppm, " -"rast, xbm, bmp, webp, and exr attempted), then the subtype will be " -"automatically included in the :mailheader:`Content-Type` header. Otherwise " -"you can explicitly specify the image subtype via the *_subtype* argument. If " -"the minor type could not be guessed and *_subtype* was not given, then :exc:" -"`TypeError` is raised." -msgstr "" - -#: ../../library/email.mime.rst:190 -msgid "" -"Optional *_encoder* is a callable (i.e. function) which will perform the " -"actual encoding of the image data for transport. This callable takes one " -"argument, which is the :class:`MIMEImage` instance. It should use :meth:" -"`~email.message.Message.get_payload` and :meth:`~email.message.Message." -"set_payload` to change the payload to encoded form. It should also add any :" -"mailheader:`Content-Transfer-Encoding` or other headers to the message " -"object as necessary. The default encoding is base64. See the :mod:`email." -"encoders` module for a list of the built-in encoders." -msgstr "" - -#: ../../library/email.mime.rst:202 -msgid "" -"*_params* are passed straight through to the :class:`~email.mime.base." -"MIMEBase` constructor." -msgstr "" - -#: ../../library/email.mime.rst:212 -msgid "Module: :mod:`email.mime.message`" -msgstr "模組：:mod:`email.mime.message`" - -#: ../../library/email.mime.rst:214 -msgid "" -"A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the :class:" -"`MIMEMessage` class is used to create MIME objects of main type :mimetype:" -"`message`. *_msg* is used as the payload, and must be an instance of class :" -"class:`~email.message.Message` (or a subclass thereof), otherwise a :exc:" -"`TypeError` is raised." -msgstr "" - -#: ../../library/email.mime.rst:220 -msgid "" -"Optional *_subtype* sets the subtype of the message; it defaults to :" -"mimetype:`rfc822`." -msgstr "" - -#: ../../library/email.mime.rst:232 -msgid "Module: :mod:`email.mime.text`" -msgstr "模組：:mod:`email.mime.text`" - -#: ../../library/email.mime.rst:234 -msgid "" -"A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the :class:" -"`MIMEText` class is used to create MIME objects of major type :mimetype:" -"`text`. *_text* is the string for the payload. *_subtype* is the minor type " -"and defaults to :mimetype:`plain`. *_charset* is the character set of the " -"text and is passed as an argument to the :class:`~email.mime.nonmultipart." -"MIMENonMultipart` constructor; it defaults to ``us-ascii`` if the string " -"contains only ``ascii`` code points, and ``utf-8`` otherwise. The " -"*_charset* parameter accepts either a string or a :class:`~email.charset." -"Charset` instance." -msgstr "" - -#: ../../library/email.mime.rst:244 -msgid "" -"Unless the *_charset* argument is explicitly set to ``None``, the MIMEText " -"object created will have both a :mailheader:`Content-Type` header with a " -"``charset`` parameter, and a :mailheader:`Content-Transfer-Encoding` " -"header. This means that a subsequent ``set_payload`` call will not result " -"in an encoded payload, even if a charset is passed in the ``set_payload`` " -"command. You can \"reset\" this behavior by deleting the ``Content-Transfer-" -"Encoding`` header, after which a ``set_payload`` call will automatically " -"encode the new payload (and add a new :mailheader:`Content-Transfer-" -"Encoding` header)." -msgstr "" - -#: ../../library/email.mime.rst:256 -msgid "*_charset* also accepts :class:`~email.charset.Charset` instances." -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-05-09 00:03+0000\n" +"PO-Revision-Date: 2018-05-23 16:00+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/email.mime.rst:2 +msgid ":mod:`!email.mime`: Creating email and MIME objects from scratch" +msgstr ":mod:`!email.mime`：從頭開始建立電子郵件和 MIME 物件" + +#: ../../library/email.mime.rst:7 +msgid "**Source code:** :source:`Lib/email/mime/`" +msgstr "**原始碼：**\\ :source:`Lib/email/mime/`" + +#: ../../library/email.mime.rst:11 +msgid "" +"This module is part of the legacy (``Compat32``) email API. Its " +"functionality is partially replaced by the :mod:`~email.contentmanager` in " +"the new API, but in certain applications these classes may still be useful, " +"even in non-legacy code." +msgstr "" + +#: ../../library/email.mime.rst:16 +msgid "" +"Ordinarily, you get a message object structure by passing a file or some " +"text to a parser, which parses the text and returns the root message " +"object. However you can also build a complete message structure from " +"scratch, or even individual :class:`~email.message.Message` objects by " +"hand. In fact, you can also take an existing structure and add new :class:" +"`~email.message.Message` objects, move them around, etc. This makes a very " +"convenient interface for slicing-and-dicing MIME messages." +msgstr "" + +#: ../../library/email.mime.rst:24 +msgid "" +"You can create a new object structure by creating :class:`~email.message." +"Message` instances, adding attachments and all the appropriate headers " +"manually. For MIME messages though, the :mod:`email` package provides some " +"convenient subclasses to make things easier." +msgstr "" + +#: ../../library/email.mime.rst:29 +msgid "Here are the classes:" +msgstr "" + +#: ../../library/email.mime.rst:35 +msgid "Module: :mod:`email.mime.base`" +msgstr "模組：:mod:`email.mime.base`" + +#: ../../library/email.mime.rst:37 +msgid "" +"This is the base class for all the MIME-specific subclasses of :class:" +"`~email.message.Message`. Ordinarily you won't create instances " +"specifically of :class:`MIMEBase`, although you could. :class:`MIMEBase` is " +"provided primarily as a convenient base class for more specific MIME-aware " +"subclasses." +msgstr "" + +#: ../../library/email.mime.rst:43 +msgid "" +"*_maintype* is the :mailheader:`Content-Type` major type (e.g. :mimetype:" +"`text` or :mimetype:`image`), and *_subtype* is the :mailheader:`Content-" +"Type` minor type (e.g. :mimetype:`plain` or :mimetype:`gif`). *_params* is " +"a parameter key/value dictionary and is passed directly to :meth:`Message." +"add_header `." +msgstr "" + +#: ../../library/email.mime.rst:49 +msgid "" +"If *policy* is specified, (defaults to the :class:`compat32 ` policy) it will be passed to :class:`~email.message.Message`." +msgstr "" + +#: ../../library/email.mime.rst:53 +msgid "" +"The :class:`MIMEBase` class always adds a :mailheader:`Content-Type` header " +"(based on *_maintype*, *_subtype*, and *_params*), and a :mailheader:`MIME-" +"Version` header (always set to ``1.0``)." +msgstr "" + +#: ../../library/email.mime.rst:57 ../../library/email.mime.rst:104 +#: ../../library/email.mime.rst:135 ../../library/email.mime.rst:169 +#: ../../library/email.mime.rst:205 ../../library/email.mime.rst:225 +#: ../../library/email.mime.rst:259 +msgid "Added *policy* keyword-only parameter." +msgstr "新增僅限關鍵字參數 *policy*。" + +#: ../../library/email.mime.rst:65 +msgid "Module: :mod:`email.mime.nonmultipart`" +msgstr "模組：:mod:`email.mime.nonmultipart`" + +#: ../../library/email.mime.rst:67 +msgid "" +"A subclass of :class:`~email.mime.base.MIMEBase`, this is an intermediate " +"base class for MIME messages that are not :mimetype:`multipart`. The " +"primary purpose of this class is to prevent the use of the :meth:`~email." +"message.Message.attach` method, which only makes sense for :mimetype:" +"`multipart` messages. If :meth:`~email.message.Message.attach` is called, " +"a :exc:`~email.errors.MultipartConversionError` exception is raised." +msgstr "" + +#: ../../library/email.mime.rst:80 +msgid "Module: :mod:`email.mime.multipart`" +msgstr "模組：:mod:`email.mime.multipart`" + +#: ../../library/email.mime.rst:82 +msgid "" +"A subclass of :class:`~email.mime.base.MIMEBase`, this is an intermediate " +"base class for MIME messages that are :mimetype:`multipart`. Optional " +"*_subtype* defaults to :mimetype:`mixed`, but can be used to specify the " +"subtype of the message. A :mailheader:`Content-Type` header of :mimetype:" +"`multipart/_subtype` will be added to the message object. A :mailheader:" +"`MIME-Version` header will also be added." +msgstr "" + +#: ../../library/email.mime.rst:89 +msgid "" +"Optional *boundary* is the multipart boundary string. When ``None`` (the " +"default), the boundary is calculated when needed (for example, when the " +"message is serialized)." +msgstr "" + +#: ../../library/email.mime.rst:93 +msgid "" +"*_subparts* is a sequence of initial subparts for the payload. It must be " +"possible to convert this sequence to a list. You can always attach new " +"subparts to the message by using the :meth:`Message.attach ` method." +msgstr "" + +#: ../../library/email.mime.rst:98 ../../library/email.mime.rst:131 +#: ../../library/email.mime.rst:165 ../../library/email.mime.rst:200 +#: ../../library/email.mime.rst:223 ../../library/email.mime.rst:254 +msgid "" +"Optional *policy* argument defaults to :class:`compat32 `." +msgstr "" + +#: ../../library/email.mime.rst:100 +msgid "" +"Additional parameters for the :mailheader:`Content-Type` header are taken " +"from the keyword arguments, or passed into the *_params* argument, which is " +"a keyword dictionary." +msgstr "" + +#: ../../library/email.mime.rst:113 +msgid "Module: :mod:`email.mime.application`" +msgstr "模組：:mod:`email.mime.application`" + +#: ../../library/email.mime.rst:115 +msgid "" +"A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the :class:" +"`MIMEApplication` class is used to represent MIME message objects of major " +"type :mimetype:`application`. *_data* contains the bytes for the raw " +"application data. Optional *_subtype* specifies the MIME subtype and " +"defaults to :mimetype:`octet-stream`." +msgstr "" + +#: ../../library/email.mime.rst:121 +msgid "" +"Optional *_encoder* is a callable (i.e. function) which will perform the " +"actual encoding of the data for transport. This callable takes one " +"argument, which is the :class:`MIMEApplication` instance. It should use :" +"meth:`~email.message.Message.get_payload` and :meth:`~email.message.Message." +"set_payload` to change the payload to encoded form. It should also add any :" +"mailheader:`Content-Transfer-Encoding` or other headers to the message " +"object as necessary. The default encoding is base64. See the :mod:`email." +"encoders` module for a list of the built-in encoders." +msgstr "" + +#: ../../library/email.mime.rst:133 ../../library/email.mime.rst:167 +msgid "*_params* are passed straight through to the base class constructor." +msgstr "" + +#: ../../library/email.mime.rst:144 +msgid "Module: :mod:`email.mime.audio`" +msgstr "模組：:mod:`email.mime.audio`" + +#: ../../library/email.mime.rst:146 +msgid "" +"A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the :class:" +"`MIMEAudio` class is used to create MIME message objects of major type :" +"mimetype:`audio`. *_audiodata* contains the bytes for the raw audio data. " +"If this data can be decoded as au, wav, aiff, or aifc, then the subtype will " +"be automatically included in the :mailheader:`Content-Type` header. " +"Otherwise you can explicitly specify the audio subtype via the *_subtype* " +"argument. If the minor type could not be guessed and *_subtype* was not " +"given, then :exc:`TypeError` is raised." +msgstr "" + +#: ../../library/email.mime.rst:155 +msgid "" +"Optional *_encoder* is a callable (i.e. function) which will perform the " +"actual encoding of the audio data for transport. This callable takes one " +"argument, which is the :class:`MIMEAudio` instance. It should use :meth:" +"`~email.message.Message.get_payload` and :meth:`~email.message.Message." +"set_payload` to change the payload to encoded form. It should also add any :" +"mailheader:`Content-Transfer-Encoding` or other headers to the message " +"object as necessary. The default encoding is base64. See the :mod:`email." +"encoders` module for a list of the built-in encoders." +msgstr "" + +#: ../../library/email.mime.rst:178 +msgid "Module: :mod:`email.mime.image`" +msgstr "模組：:mod:`email.mime.image`" + +#: ../../library/email.mime.rst:180 +msgid "" +"A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the :class:" +"`MIMEImage` class is used to create MIME message objects of major type :" +"mimetype:`image`. *_imagedata* contains the bytes for the raw image data. " +"If this data type can be detected (jpeg, png, gif, tiff, rgb, pbm, pgm, ppm, " +"rast, xbm, bmp, webp, and exr attempted), then the subtype will be " +"automatically included in the :mailheader:`Content-Type` header. Otherwise " +"you can explicitly specify the image subtype via the *_subtype* argument. If " +"the minor type could not be guessed and *_subtype* was not given, then :exc:" +"`TypeError` is raised." +msgstr "" + +#: ../../library/email.mime.rst:190 +msgid "" +"Optional *_encoder* is a callable (i.e. function) which will perform the " +"actual encoding of the image data for transport. This callable takes one " +"argument, which is the :class:`MIMEImage` instance. It should use :meth:" +"`~email.message.Message.get_payload` and :meth:`~email.message.Message." +"set_payload` to change the payload to encoded form. It should also add any :" +"mailheader:`Content-Transfer-Encoding` or other headers to the message " +"object as necessary. The default encoding is base64. See the :mod:`email." +"encoders` module for a list of the built-in encoders." +msgstr "" + +#: ../../library/email.mime.rst:202 +msgid "" +"*_params* are passed straight through to the :class:`~email.mime.base." +"MIMEBase` constructor." +msgstr "" + +#: ../../library/email.mime.rst:212 +msgid "Module: :mod:`email.mime.message`" +msgstr "模組：:mod:`email.mime.message`" + +#: ../../library/email.mime.rst:214 +msgid "" +"A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the :class:" +"`MIMEMessage` class is used to create MIME objects of main type :mimetype:" +"`message`. *_msg* is used as the payload, and must be an instance of class :" +"class:`~email.message.Message` (or a subclass thereof), otherwise a :exc:" +"`TypeError` is raised." +msgstr "" + +#: ../../library/email.mime.rst:220 +msgid "" +"Optional *_subtype* sets the subtype of the message; it defaults to :" +"mimetype:`rfc822`." +msgstr "" + +#: ../../library/email.mime.rst:232 +msgid "Module: :mod:`email.mime.text`" +msgstr "模組：:mod:`email.mime.text`" + +#: ../../library/email.mime.rst:234 +msgid "" +"A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the :class:" +"`MIMEText` class is used to create MIME objects of major type :mimetype:" +"`text`. *_text* is the string for the payload. *_subtype* is the minor type " +"and defaults to :mimetype:`plain`. *_charset* is the character set of the " +"text and is passed as an argument to the :class:`~email.mime.nonmultipart." +"MIMENonMultipart` constructor; it defaults to ``us-ascii`` if the string " +"contains only ``ascii`` code points, and ``utf-8`` otherwise. The " +"*_charset* parameter accepts either a string or a :class:`~email.charset." +"Charset` instance." +msgstr "" + +#: ../../library/email.mime.rst:244 +msgid "" +"Unless the *_charset* argument is explicitly set to ``None``, the MIMEText " +"object created will have both a :mailheader:`Content-Type` header with a " +"``charset`` parameter, and a :mailheader:`Content-Transfer-Encoding` " +"header. This means that a subsequent ``set_payload`` call will not result " +"in an encoded payload, even if a charset is passed in the ``set_payload`` " +"command. You can \"reset\" this behavior by deleting the ``Content-Transfer-" +"Encoding`` header, after which a ``set_payload`` call will automatically " +"encode the new payload (and add a new :mailheader:`Content-Transfer-" +"Encoding` header)." +msgstr "" + +#: ../../library/email.mime.rst:256 +msgid "*_charset* also accepts :class:`~email.charset.Charset` instances." +msgstr "" diff --git a/library/email.parser.po b/library/email.parser.po index 6decb9220c..fde8825316 100644 --- a/library/email.parser.po +++ b/library/email.parser.po @@ -1,382 +1,382 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-07-14 11:31+0000\n" -"PO-Revision-Date: 2018-05-23 16:01+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/email.parser.rst:2 -msgid ":mod:`!email.parser`: Parsing email messages" -msgstr ":mod:`!email.parser`：剖析電子郵件訊息" - -#: ../../library/email.parser.rst:7 -msgid "**Source code:** :source:`Lib/email/parser.py`" -msgstr "**原始碼：**\\ :source:`Lib/email/parser.py`" - -#: ../../library/email.parser.rst:11 -msgid "" -"Message object structures can be created in one of two ways: they can be " -"created from whole cloth by creating an :class:`~email.message.EmailMessage` " -"object, adding headers using the dictionary interface, and adding payload(s) " -"using :meth:`~email.message.EmailMessage.set_content` and related methods, " -"or they can be created by parsing a serialized representation of the email " -"message." -msgstr "" - -#: ../../library/email.parser.rst:18 -msgid "" -"The :mod:`email` package provides a standard parser that understands most " -"email document structures, including MIME documents. You can pass the " -"parser a bytes, string or file object, and the parser will return to you the " -"root :class:`~email.message.EmailMessage` instance of the object structure. " -"For simple, non-MIME messages the payload of this root object will likely be " -"a string containing the text of the message. For MIME messages, the root " -"object will return ``True`` from its :meth:`~email.message.EmailMessage." -"is_multipart` method, and the subparts can be accessed via the payload " -"manipulation methods, such as :meth:`~email.message.EmailMessage.get_body`, :" -"meth:`~email.message.EmailMessage.iter_parts`, and :meth:`~email.message." -"EmailMessage.walk`." -msgstr "" - -#: ../../library/email.parser.rst:30 -msgid "" -"There are actually two parser interfaces available for use, the :class:" -"`Parser` API and the incremental :class:`FeedParser` API. The :class:" -"`Parser` API is most useful if you have the entire text of the message in " -"memory, or if the entire message lives in a file on the file system. :class:" -"`FeedParser` is more appropriate when you are reading the message from a " -"stream which might block waiting for more input (such as reading an email " -"message from a socket). The :class:`FeedParser` can consume and parse the " -"message incrementally, and only returns the root object when you close the " -"parser." -msgstr "" - -#: ../../library/email.parser.rst:39 -msgid "" -"Note that the parser can be extended in limited ways, and of course you can " -"implement your own parser completely from scratch. All of the logic that " -"connects the :mod:`email` package's bundled parser and the :class:`~email." -"message.EmailMessage` class is embodied in the :class:`~email.policy.Policy` " -"class, so a custom parser can create message object trees any way it finds " -"necessary by implementing custom versions of the appropriate :class:`!" -"Policy` methods." -msgstr "" - -#: ../../library/email.parser.rst:49 -msgid "FeedParser API" -msgstr "" - -#: ../../library/email.parser.rst:51 -msgid "" -"The :class:`BytesFeedParser`, imported from the :mod:`email.feedparser` " -"module, provides an API that is conducive to incremental parsing of email " -"messages, such as would be necessary when reading the text of an email " -"message from a source that can block (such as a socket). The :class:" -"`BytesFeedParser` can of course be used to parse an email message fully " -"contained in a :term:`bytes-like object`, string, or file, but the :class:" -"`BytesParser` API may be more convenient for such use cases. The semantics " -"and results of the two parser APIs are identical." -msgstr "" - -#: ../../library/email.parser.rst:60 -msgid "" -"The :class:`BytesFeedParser`'s API is simple; you create an instance, feed " -"it a bunch of bytes until there's no more to feed it, then close the parser " -"to retrieve the root message object. The :class:`BytesFeedParser` is " -"extremely accurate when parsing standards-compliant messages, and it does a " -"very good job of parsing non-compliant messages, providing information about " -"how a message was deemed broken. It will populate a message object's :attr:" -"`~email.message.EmailMessage.defects` attribute with a list of any problems " -"it found in a message. See the :mod:`email.errors` module for the list of " -"defects that it can find." -msgstr "" - -#: ../../library/email.parser.rst:70 -msgid "Here is the API for the :class:`BytesFeedParser`:" -msgstr "" - -#: ../../library/email.parser.rst:75 -msgid "" -"Create a :class:`BytesFeedParser` instance. Optional *_factory* is a no-" -"argument callable; if not specified use the :attr:`~email.policy.Policy." -"message_factory` from the *policy*. Call *_factory* whenever a new message " -"object is needed." -msgstr "" - -#: ../../library/email.parser.rst:80 -msgid "" -"If *policy* is specified use the rules it specifies to update the " -"representation of the message. If *policy* is not set, use the :class:" -"`compat32 ` policy, which maintains backward " -"compatibility with the Python 3.2 version of the email package and provides :" -"class:`~email.message.Message` as the default factory. All other policies " -"provide :class:`~email.message.EmailMessage` as the default *_factory*. For " -"more information on what else *policy* controls, see the :mod:`~email." -"policy` documentation." -msgstr "" - -#: ../../library/email.parser.rst:89 ../../library/email.parser.rst:145 -msgid "" -"Note: **The policy keyword should always be specified**; The default will " -"change to :data:`email.policy.default` in a future version of Python." -msgstr "" - -#: ../../library/email.parser.rst:94 ../../library/email.parser.rst:122 -msgid "Added the *policy* keyword." -msgstr "新增 *policy* 關鍵字。" - -#: ../../library/email.parser.rst:95 -msgid "*_factory* defaults to the policy ``message_factory``." -msgstr "" - -#: ../../library/email.parser.rst:100 -msgid "" -"Feed the parser some more data. *data* should be a :term:`bytes-like " -"object` containing one or more lines. The lines can be partial and the " -"parser will stitch such partial lines together properly. The lines can have " -"any of the three common line endings: carriage return, newline, or carriage " -"return and newline (they can even be mixed)." -msgstr "" - -#: ../../library/email.parser.rst:109 -msgid "" -"Complete the parsing of all previously fed data and return the root message " -"object. It is undefined what happens if :meth:`~feed` is called after this " -"method has been called." -msgstr "" - -#: ../../library/email.parser.rst:116 -msgid "" -"Works like :class:`BytesFeedParser` except that the input to the :meth:" -"`~BytesFeedParser.feed` method must be a string. This is of limited " -"utility, since the only way for such a message to be valid is for it to " -"contain only ASCII text or, if :attr:`~email.policy.EmailPolicy.utf8` is " -"``True``, no binary attachments." -msgstr "" - -#: ../../library/email.parser.rst:126 -msgid "Parser API" -msgstr "" - -#: ../../library/email.parser.rst:128 -msgid "" -"The :class:`BytesParser` class, imported from the :mod:`email.parser` " -"module, provides an API that can be used to parse a message when the " -"complete contents of the message are available in a :term:`bytes-like " -"object` or file. The :mod:`email.parser` module also provides :class:" -"`Parser` for parsing strings, and header-only parsers, :class:" -"`BytesHeaderParser` and :class:`HeaderParser`, which can be used if you're " -"only interested in the headers of the message. :class:`BytesHeaderParser` " -"and :class:`HeaderParser` can be much faster in these situations, since they " -"do not attempt to parse the message body, instead setting the payload to the " -"raw body." -msgstr "" - -#: ../../library/email.parser.rst:141 -msgid "" -"Create a :class:`BytesParser` instance. The *_class* and *policy* arguments " -"have the same meaning and semantics as the *_factory* and *policy* arguments " -"of :class:`BytesFeedParser`." -msgstr "" - -#: ../../library/email.parser.rst:148 -msgid "" -"Removed the *strict* argument that was deprecated in 2.4. Added the " -"*policy* keyword." -msgstr "" - -#: ../../library/email.parser.rst:151 ../../library/email.parser.rst:200 -#: ../../library/email.parser.rst:280 -msgid "*_class* defaults to the policy ``message_factory``." -msgstr "" - -#: ../../library/email.parser.rst:156 -msgid "" -"Read all the data from the binary file-like object *fp*, parse the resulting " -"bytes, and return the message object. *fp* must support both the :meth:`~io." -"IOBase.readline` and the :meth:`~io.IOBase.read` methods." -msgstr "" - -#: ../../library/email.parser.rst:161 -msgid "" -"The bytes contained in *fp* must be formatted as a block of :rfc:`5322` (or, " -"if :attr:`~email.policy.EmailPolicy.utf8` is ``True``, :rfc:`6532`) style " -"headers and header continuation lines, optionally preceded by an envelope " -"header. The header block is terminated either by the end of the data or by " -"a blank line. Following the header block is the body of the message (which " -"may contain MIME-encoded subparts, including subparts with a :mailheader:" -"`Content-Transfer-Encoding` of ``8bit``)." -msgstr "" - -#: ../../library/email.parser.rst:169 -msgid "" -"Optional *headersonly* is a flag specifying whether to stop parsing after " -"reading the headers or not. The default is ``False``, meaning it parses the " -"entire contents of the file." -msgstr "" - -#: ../../library/email.parser.rst:176 -msgid "" -"Similar to the :meth:`parse` method, except it takes a :term:`bytes-like " -"object` instead of a file-like object. Calling this method on a :term:" -"`bytes-like object` is equivalent to wrapping *bytes* in a :class:`~io." -"BytesIO` instance first and calling :meth:`parse`." -msgstr "" - -#: ../../library/email.parser.rst:181 ../../library/email.parser.rst:221 -msgid "Optional *headersonly* is as with the :meth:`parse` method." -msgstr "" - -#: ../../library/email.parser.rst:188 -msgid "" -"Exactly like :class:`BytesParser`, except that *headersonly* defaults to " -"``True``." -msgstr "" - -#: ../../library/email.parser.rst:196 -msgid "" -"This class is parallel to :class:`BytesParser`, but handles string input." -msgstr "" - -#: ../../library/email.parser.rst:198 ../../library/email.parser.rst:245 -#: ../../library/email.parser.rst:258 ../../library/email.parser.rst:268 -#: ../../library/email.parser.rst:278 -msgid "Removed the *strict* argument. Added the *policy* keyword." -msgstr "" - -#: ../../library/email.parser.rst:205 -msgid "" -"Read all the data from the text-mode file-like object *fp*, parse the " -"resulting text, and return the root message object. *fp* must support both " -"the :meth:`~io.TextIOBase.readline` and the :meth:`~io.TextIOBase.read` " -"methods on file-like objects." -msgstr "" - -#: ../../library/email.parser.rst:210 -msgid "" -"Other than the text mode requirement, this method operates like :meth:" -"`BytesParser.parse`." -msgstr "" - -#: ../../library/email.parser.rst:216 -msgid "" -"Similar to the :meth:`parse` method, except it takes a string object instead " -"of a file-like object. Calling this method on a string is equivalent to " -"wrapping *text* in a :class:`~io.StringIO` instance first and calling :meth:" -"`parse`." -msgstr "" - -#: ../../library/email.parser.rst:226 -msgid "" -"Exactly like :class:`Parser`, except that *headersonly* defaults to ``True``." -msgstr "" - -#: ../../library/email.parser.rst:230 -msgid "" -"Since creating a message object structure from a string or a file object is " -"such a common task, four functions are provided as a convenience. They are " -"available in the top-level :mod:`email` package namespace." -msgstr "" - -#: ../../library/email.parser.rst:239 -msgid "" -"Return a message object structure from a :term:`bytes-like object`. This is " -"equivalent to ``BytesParser().parsebytes(s)``. Optional *_class* and " -"*policy* are interpreted as with the :class:`~email.parser.BytesParser` " -"class constructor." -msgstr "" - -#: ../../library/email.parser.rst:252 -msgid "" -"Return a message object structure tree from an open binary :term:`file " -"object`. This is equivalent to ``BytesParser().parse(fp)``. *_class* and " -"*policy* are interpreted as with the :class:`~email.parser.BytesParser` " -"class constructor." -msgstr "" - -#: ../../library/email.parser.rst:264 -msgid "" -"Return a message object structure from a string. This is equivalent to " -"``Parser().parsestr(s)``. *_class* and *policy* are interpreted as with " -"the :class:`~email.parser.Parser` class constructor." -msgstr "" - -#: ../../library/email.parser.rst:274 -msgid "" -"Return a message object structure tree from an open :term:`file object`. " -"This is equivalent to ``Parser().parse(fp)``. *_class* and *policy* are " -"interpreted as with the :class:`~email.parser.Parser` class constructor." -msgstr "" - -#: ../../library/email.parser.rst:283 -msgid "" -"Here's an example of how you might use :func:`message_from_bytes` at an " -"interactive Python prompt::" -msgstr "" - -#: ../../library/email.parser.rst:286 -msgid "" -">>> import email\n" -">>> msg = email.message_from_bytes(myBytes)" -msgstr "" -">>> import email\n" -">>> msg = email.message_from_bytes(myBytes)" - -#: ../../library/email.parser.rst:291 -msgid "Additional notes" -msgstr "" - -#: ../../library/email.parser.rst:293 -msgid "Here are some notes on the parsing semantics:" -msgstr "" - -#: ../../library/email.parser.rst:295 -msgid "" -"Most non-\\ :mimetype:`multipart` type messages are parsed as a single " -"message object with a string payload. These objects will return ``False`` " -"for :meth:`~email.message.EmailMessage.is_multipart`, and :meth:`~email." -"message.EmailMessage.iter_parts` will yield an empty list." -msgstr "" - -#: ../../library/email.parser.rst:300 -msgid "" -"All :mimetype:`multipart` type messages will be parsed as a container " -"message object with a list of sub-message objects for their payload. The " -"outer container message will return ``True`` for :meth:`~email.message." -"EmailMessage.is_multipart`, and :meth:`~email.message.EmailMessage." -"iter_parts` will yield a list of subparts." -msgstr "" - -#: ../../library/email.parser.rst:306 -msgid "" -"Most messages with a content type of :mimetype:`message/\\*` (such as :" -"mimetype:`message/delivery-status` and :mimetype:`message/rfc822`) will also " -"be parsed as container object containing a list payload of length 1. Their :" -"meth:`~email.message.EmailMessage.is_multipart` method will return ``True``. " -"The single element yielded by :meth:`~email.message.EmailMessage.iter_parts` " -"will be a sub-message object." -msgstr "" - -#: ../../library/email.parser.rst:313 -msgid "" -"Some non-standards-compliant messages may not be internally consistent about " -"their :mimetype:`multipart`\\ -edness. Such messages may have a :mailheader:" -"`Content-Type` header of type :mimetype:`multipart`, but their :meth:`~email." -"message.EmailMessage.is_multipart` method may return ``False``. If such " -"messages were parsed with the :class:`~email.parser.FeedParser`, they will " -"have an instance of the :class:`~email.errors." -"MultipartInvariantViolationDefect` class in their *defects* attribute list. " -"See :mod:`email.errors` for details." -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-07-14 11:31+0000\n" +"PO-Revision-Date: 2018-05-23 16:01+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/email.parser.rst:2 +msgid ":mod:`!email.parser`: Parsing email messages" +msgstr ":mod:`!email.parser`：剖析電子郵件訊息" + +#: ../../library/email.parser.rst:7 +msgid "**Source code:** :source:`Lib/email/parser.py`" +msgstr "**原始碼：**\\ :source:`Lib/email/parser.py`" + +#: ../../library/email.parser.rst:11 +msgid "" +"Message object structures can be created in one of two ways: they can be " +"created from whole cloth by creating an :class:`~email.message.EmailMessage` " +"object, adding headers using the dictionary interface, and adding payload(s) " +"using :meth:`~email.message.EmailMessage.set_content` and related methods, " +"or they can be created by parsing a serialized representation of the email " +"message." +msgstr "" + +#: ../../library/email.parser.rst:18 +msgid "" +"The :mod:`email` package provides a standard parser that understands most " +"email document structures, including MIME documents. You can pass the " +"parser a bytes, string or file object, and the parser will return to you the " +"root :class:`~email.message.EmailMessage` instance of the object structure. " +"For simple, non-MIME messages the payload of this root object will likely be " +"a string containing the text of the message. For MIME messages, the root " +"object will return ``True`` from its :meth:`~email.message.EmailMessage." +"is_multipart` method, and the subparts can be accessed via the payload " +"manipulation methods, such as :meth:`~email.message.EmailMessage.get_body`, :" +"meth:`~email.message.EmailMessage.iter_parts`, and :meth:`~email.message." +"EmailMessage.walk`." +msgstr "" + +#: ../../library/email.parser.rst:30 +msgid "" +"There are actually two parser interfaces available for use, the :class:" +"`Parser` API and the incremental :class:`FeedParser` API. The :class:" +"`Parser` API is most useful if you have the entire text of the message in " +"memory, or if the entire message lives in a file on the file system. :class:" +"`FeedParser` is more appropriate when you are reading the message from a " +"stream which might block waiting for more input (such as reading an email " +"message from a socket). The :class:`FeedParser` can consume and parse the " +"message incrementally, and only returns the root object when you close the " +"parser." +msgstr "" + +#: ../../library/email.parser.rst:39 +msgid "" +"Note that the parser can be extended in limited ways, and of course you can " +"implement your own parser completely from scratch. All of the logic that " +"connects the :mod:`email` package's bundled parser and the :class:`~email." +"message.EmailMessage` class is embodied in the :class:`~email.policy.Policy` " +"class, so a custom parser can create message object trees any way it finds " +"necessary by implementing custom versions of the appropriate :class:`!" +"Policy` methods." +msgstr "" + +#: ../../library/email.parser.rst:49 +msgid "FeedParser API" +msgstr "" + +#: ../../library/email.parser.rst:51 +msgid "" +"The :class:`BytesFeedParser`, imported from the :mod:`email.feedparser` " +"module, provides an API that is conducive to incremental parsing of email " +"messages, such as would be necessary when reading the text of an email " +"message from a source that can block (such as a socket). The :class:" +"`BytesFeedParser` can of course be used to parse an email message fully " +"contained in a :term:`bytes-like object`, string, or file, but the :class:" +"`BytesParser` API may be more convenient for such use cases. The semantics " +"and results of the two parser APIs are identical." +msgstr "" + +#: ../../library/email.parser.rst:60 +msgid "" +"The :class:`BytesFeedParser`'s API is simple; you create an instance, feed " +"it a bunch of bytes until there's no more to feed it, then close the parser " +"to retrieve the root message object. The :class:`BytesFeedParser` is " +"extremely accurate when parsing standards-compliant messages, and it does a " +"very good job of parsing non-compliant messages, providing information about " +"how a message was deemed broken. It will populate a message object's :attr:" +"`~email.message.EmailMessage.defects` attribute with a list of any problems " +"it found in a message. See the :mod:`email.errors` module for the list of " +"defects that it can find." +msgstr "" + +#: ../../library/email.parser.rst:70 +msgid "Here is the API for the :class:`BytesFeedParser`:" +msgstr "" + +#: ../../library/email.parser.rst:75 +msgid "" +"Create a :class:`BytesFeedParser` instance. Optional *_factory* is a no-" +"argument callable; if not specified use the :attr:`~email.policy.Policy." +"message_factory` from the *policy*. Call *_factory* whenever a new message " +"object is needed." +msgstr "" + +#: ../../library/email.parser.rst:80 +msgid "" +"If *policy* is specified use the rules it specifies to update the " +"representation of the message. If *policy* is not set, use the :class:" +"`compat32 ` policy, which maintains backward " +"compatibility with the Python 3.2 version of the email package and provides :" +"class:`~email.message.Message` as the default factory. All other policies " +"provide :class:`~email.message.EmailMessage` as the default *_factory*. For " +"more information on what else *policy* controls, see the :mod:`~email." +"policy` documentation." +msgstr "" + +#: ../../library/email.parser.rst:89 ../../library/email.parser.rst:145 +msgid "" +"Note: **The policy keyword should always be specified**; The default will " +"change to :data:`email.policy.default` in a future version of Python." +msgstr "" + +#: ../../library/email.parser.rst:94 ../../library/email.parser.rst:122 +msgid "Added the *policy* keyword." +msgstr "新增 *policy* 關鍵字。" + +#: ../../library/email.parser.rst:95 +msgid "*_factory* defaults to the policy ``message_factory``." +msgstr "" + +#: ../../library/email.parser.rst:100 +msgid "" +"Feed the parser some more data. *data* should be a :term:`bytes-like " +"object` containing one or more lines. The lines can be partial and the " +"parser will stitch such partial lines together properly. The lines can have " +"any of the three common line endings: carriage return, newline, or carriage " +"return and newline (they can even be mixed)." +msgstr "" + +#: ../../library/email.parser.rst:109 +msgid "" +"Complete the parsing of all previously fed data and return the root message " +"object. It is undefined what happens if :meth:`~feed` is called after this " +"method has been called." +msgstr "" + +#: ../../library/email.parser.rst:116 +msgid "" +"Works like :class:`BytesFeedParser` except that the input to the :meth:" +"`~BytesFeedParser.feed` method must be a string. This is of limited " +"utility, since the only way for such a message to be valid is for it to " +"contain only ASCII text or, if :attr:`~email.policy.EmailPolicy.utf8` is " +"``True``, no binary attachments." +msgstr "" + +#: ../../library/email.parser.rst:126 +msgid "Parser API" +msgstr "" + +#: ../../library/email.parser.rst:128 +msgid "" +"The :class:`BytesParser` class, imported from the :mod:`email.parser` " +"module, provides an API that can be used to parse a message when the " +"complete contents of the message are available in a :term:`bytes-like " +"object` or file. The :mod:`email.parser` module also provides :class:" +"`Parser` for parsing strings, and header-only parsers, :class:" +"`BytesHeaderParser` and :class:`HeaderParser`, which can be used if you're " +"only interested in the headers of the message. :class:`BytesHeaderParser` " +"and :class:`HeaderParser` can be much faster in these situations, since they " +"do not attempt to parse the message body, instead setting the payload to the " +"raw body." +msgstr "" + +#: ../../library/email.parser.rst:141 +msgid "" +"Create a :class:`BytesParser` instance. The *_class* and *policy* arguments " +"have the same meaning and semantics as the *_factory* and *policy* arguments " +"of :class:`BytesFeedParser`." +msgstr "" + +#: ../../library/email.parser.rst:148 +msgid "" +"Removed the *strict* argument that was deprecated in 2.4. Added the " +"*policy* keyword." +msgstr "" + +#: ../../library/email.parser.rst:151 ../../library/email.parser.rst:200 +#: ../../library/email.parser.rst:280 +msgid "*_class* defaults to the policy ``message_factory``." +msgstr "" + +#: ../../library/email.parser.rst:156 +msgid "" +"Read all the data from the binary file-like object *fp*, parse the resulting " +"bytes, and return the message object. *fp* must support both the :meth:`~io." +"IOBase.readline` and the :meth:`~io.IOBase.read` methods." +msgstr "" + +#: ../../library/email.parser.rst:161 +msgid "" +"The bytes contained in *fp* must be formatted as a block of :rfc:`5322` (or, " +"if :attr:`~email.policy.EmailPolicy.utf8` is ``True``, :rfc:`6532`) style " +"headers and header continuation lines, optionally preceded by an envelope " +"header. The header block is terminated either by the end of the data or by " +"a blank line. Following the header block is the body of the message (which " +"may contain MIME-encoded subparts, including subparts with a :mailheader:" +"`Content-Transfer-Encoding` of ``8bit``)." +msgstr "" + +#: ../../library/email.parser.rst:169 +msgid "" +"Optional *headersonly* is a flag specifying whether to stop parsing after " +"reading the headers or not. The default is ``False``, meaning it parses the " +"entire contents of the file." +msgstr "" + +#: ../../library/email.parser.rst:176 +msgid "" +"Similar to the :meth:`parse` method, except it takes a :term:`bytes-like " +"object` instead of a file-like object. Calling this method on a :term:" +"`bytes-like object` is equivalent to wrapping *bytes* in a :class:`~io." +"BytesIO` instance first and calling :meth:`parse`." +msgstr "" + +#: ../../library/email.parser.rst:181 ../../library/email.parser.rst:221 +msgid "Optional *headersonly* is as with the :meth:`parse` method." +msgstr "" + +#: ../../library/email.parser.rst:188 +msgid "" +"Exactly like :class:`BytesParser`, except that *headersonly* defaults to " +"``True``." +msgstr "" + +#: ../../library/email.parser.rst:196 +msgid "" +"This class is parallel to :class:`BytesParser`, but handles string input." +msgstr "" + +#: ../../library/email.parser.rst:198 ../../library/email.parser.rst:245 +#: ../../library/email.parser.rst:258 ../../library/email.parser.rst:268 +#: ../../library/email.parser.rst:278 +msgid "Removed the *strict* argument. Added the *policy* keyword." +msgstr "" + +#: ../../library/email.parser.rst:205 +msgid "" +"Read all the data from the text-mode file-like object *fp*, parse the " +"resulting text, and return the root message object. *fp* must support both " +"the :meth:`~io.TextIOBase.readline` and the :meth:`~io.TextIOBase.read` " +"methods on file-like objects." +msgstr "" + +#: ../../library/email.parser.rst:210 +msgid "" +"Other than the text mode requirement, this method operates like :meth:" +"`BytesParser.parse`." +msgstr "" + +#: ../../library/email.parser.rst:216 +msgid "" +"Similar to the :meth:`parse` method, except it takes a string object instead " +"of a file-like object. Calling this method on a string is equivalent to " +"wrapping *text* in a :class:`~io.StringIO` instance first and calling :meth:" +"`parse`." +msgstr "" + +#: ../../library/email.parser.rst:226 +msgid "" +"Exactly like :class:`Parser`, except that *headersonly* defaults to ``True``." +msgstr "" + +#: ../../library/email.parser.rst:230 +msgid "" +"Since creating a message object structure from a string or a file object is " +"such a common task, four functions are provided as a convenience. They are " +"available in the top-level :mod:`email` package namespace." +msgstr "" + +#: ../../library/email.parser.rst:239 +msgid "" +"Return a message object structure from a :term:`bytes-like object`. This is " +"equivalent to ``BytesParser().parsebytes(s)``. Optional *_class* and " +"*policy* are interpreted as with the :class:`~email.parser.BytesParser` " +"class constructor." +msgstr "" + +#: ../../library/email.parser.rst:252 +msgid "" +"Return a message object structure tree from an open binary :term:`file " +"object`. This is equivalent to ``BytesParser().parse(fp)``. *_class* and " +"*policy* are interpreted as with the :class:`~email.parser.BytesParser` " +"class constructor." +msgstr "" + +#: ../../library/email.parser.rst:264 +msgid "" +"Return a message object structure from a string. This is equivalent to " +"``Parser().parsestr(s)``. *_class* and *policy* are interpreted as with " +"the :class:`~email.parser.Parser` class constructor." +msgstr "" + +#: ../../library/email.parser.rst:274 +msgid "" +"Return a message object structure tree from an open :term:`file object`. " +"This is equivalent to ``Parser().parse(fp)``. *_class* and *policy* are " +"interpreted as with the :class:`~email.parser.Parser` class constructor." +msgstr "" + +#: ../../library/email.parser.rst:283 +msgid "" +"Here's an example of how you might use :func:`message_from_bytes` at an " +"interactive Python prompt::" +msgstr "" + +#: ../../library/email.parser.rst:286 +msgid "" +">>> import email\n" +">>> msg = email.message_from_bytes(myBytes)" +msgstr "" +">>> import email\n" +">>> msg = email.message_from_bytes(myBytes)" + +#: ../../library/email.parser.rst:291 +msgid "Additional notes" +msgstr "" + +#: ../../library/email.parser.rst:293 +msgid "Here are some notes on the parsing semantics:" +msgstr "" + +#: ../../library/email.parser.rst:295 +msgid "" +"Most non-\\ :mimetype:`multipart` type messages are parsed as a single " +"message object with a string payload. These objects will return ``False`` " +"for :meth:`~email.message.EmailMessage.is_multipart`, and :meth:`~email." +"message.EmailMessage.iter_parts` will yield an empty list." +msgstr "" + +#: ../../library/email.parser.rst:300 +msgid "" +"All :mimetype:`multipart` type messages will be parsed as a container " +"message object with a list of sub-message objects for their payload. The " +"outer container message will return ``True`` for :meth:`~email.message." +"EmailMessage.is_multipart`, and :meth:`~email.message.EmailMessage." +"iter_parts` will yield a list of subparts." +msgstr "" + +#: ../../library/email.parser.rst:306 +msgid "" +"Most messages with a content type of :mimetype:`message/\\*` (such as :" +"mimetype:`message/delivery-status` and :mimetype:`message/rfc822`) will also " +"be parsed as container object containing a list payload of length 1. Their :" +"meth:`~email.message.EmailMessage.is_multipart` method will return ``True``. " +"The single element yielded by :meth:`~email.message.EmailMessage.iter_parts` " +"will be a sub-message object." +msgstr "" + +#: ../../library/email.parser.rst:313 +msgid "" +"Some non-standards-compliant messages may not be internally consistent about " +"their :mimetype:`multipart`\\ -edness. Such messages may have a :mailheader:" +"`Content-Type` header of type :mimetype:`multipart`, but their :meth:`~email." +"message.EmailMessage.is_multipart` method may return ``False``. If such " +"messages were parsed with the :class:`~email.parser.FeedParser`, they will " +"have an instance of the :class:`~email.errors." +"MultipartInvariantViolationDefect` class in their *defects* attribute list. " +"See :mod:`email.errors` for details." +msgstr "" diff --git a/library/email.po b/library/email.po index f0bad9cfcb..24e41b03e6 100644 --- a/library/email.po +++ b/library/email.po @@ -1,196 +1,196 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-09-23 07:52+0800\n" -"PO-Revision-Date: 2018-05-23 16:01+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/email.rst:2 -msgid ":mod:`!email` --- An email and MIME handling package" -msgstr ":mod:`!email` --- 郵件和 MIME 處理套件" - -#: ../../library/email.rst:11 -msgid "**Source code:** :source:`Lib/email/__init__.py`" -msgstr "**原始碼：**\\ :source:`Lib/email/__init__.py`" - -#: ../../library/email.rst:15 -msgid "" -"The :mod:`email` package is a library for managing email messages. It is " -"specifically *not* designed to do any sending of email messages to SMTP (:" -"rfc:`2821`), NNTP, or other servers; those are functions of modules such as :" -"mod:`smtplib`. The :mod:`email` package attempts to be as RFC-compliant as " -"possible, supporting :rfc:`5322` and :rfc:`6532`, as well as such MIME-" -"related RFCs as :rfc:`2045`, :rfc:`2046`, :rfc:`2047`, :rfc:`2183`, and :rfc:" -"`2231`." -msgstr "" - -#: ../../library/email.rst:23 -msgid "" -"The overall structure of the email package can be divided into three major " -"components, plus a fourth component that controls the behavior of the other " -"components." -msgstr "" - -#: ../../library/email.rst:27 -msgid "" -"The central component of the package is an \"object model\" that represents " -"email messages. An application interacts with the package primarily through " -"the object model interface defined in the :mod:`~email.message` sub-module. " -"The application can use this API to ask questions about an existing email, " -"to construct a new email, or to add or remove email subcomponents that " -"themselves use the same object model interface. That is, following the " -"nature of email messages and their MIME subcomponents, the email object " -"model is a tree structure of objects that all provide the :class:`~email." -"message.EmailMessage` API." -msgstr "" - -#: ../../library/email.rst:37 -msgid "" -"The other two major components of the package are the :mod:`~email.parser` " -"and the :mod:`~email.generator`. The parser takes the serialized version of " -"an email message (a stream of bytes) and converts it into a tree of :class:" -"`~email.message.EmailMessage` objects. The generator takes an :class:" -"`~email.message.EmailMessage` and turns it back into a serialized byte " -"stream. (The parser and generator also handle streams of text characters, " -"but this usage is discouraged as it is too easy to end up with messages that " -"are not valid in one way or another.)" -msgstr "" - -#: ../../library/email.rst:46 -msgid "" -"The control component is the :mod:`~email.policy` module. Every :class:" -"`~email.message.EmailMessage`, every :mod:`~email.generator`, and every :mod:" -"`~email.parser` has an associated :mod:`~email.policy` object that controls " -"its behavior. Usually an application only needs to specify the policy when " -"an :class:`~email.message.EmailMessage` is created, either by directly " -"instantiating an :class:`~email.message.EmailMessage` to create a new " -"email, or by parsing an input stream using a :mod:`~email.parser`. But the " -"policy can be changed when the message is serialized using a :mod:`~email." -"generator`. This allows, for example, a generic email message to be parsed " -"from disk, but to serialize it using standard SMTP settings when sending it " -"to an email server." -msgstr "" - -#: ../../library/email.rst:58 -msgid "" -"The email package does its best to hide the details of the various governing " -"RFCs from the application. Conceptually the application should be able to " -"treat the email message as a structured tree of unicode text and binary " -"attachments, without having to worry about how these are represented when " -"serialized. In practice, however, it is often necessary to be aware of at " -"least some of the rules governing MIME messages and their structure, " -"specifically the names and nature of the MIME \"content types\" and how they " -"identify multipart documents. For the most part this knowledge should only " -"be required for more complex applications, and even then it should only be " -"the high level structure in question, and not the details of how those " -"structures are represented. Since MIME content types are used widely in " -"modern internet software (not just email), this will be a familiar concept " -"to many programmers." -msgstr "" - -#: ../../library/email.rst:71 -msgid "" -"The following sections describe the functionality of the :mod:`email` " -"package. We start with the :mod:`~email.message` object model, which is the " -"primary interface an application will use, and follow that with the :mod:" -"`~email.parser` and :mod:`~email.generator` components. Then we cover the :" -"mod:`~email.policy` controls, which completes the treatment of the main " -"components of the library." -msgstr "" - -#: ../../library/email.rst:78 -msgid "" -"The next three sections cover the exceptions the package may raise and the " -"defects (non-compliance with the RFCs) that the :mod:`~email.parser` may " -"detect. Then we cover the :mod:`~email.headerregistry` and the :mod:`~email." -"contentmanager` sub-components, which provide tools for doing more detailed " -"manipulation of headers and payloads, respectively. Both of these " -"components contain features relevant to consuming and producing non-trivial " -"messages, but also document their extensibility APIs, which will be of " -"interest to advanced applications." -msgstr "" - -#: ../../library/email.rst:87 -msgid "" -"Following those is a set of examples of using the fundamental parts of the " -"APIs covered in the preceding sections." -msgstr "" - -#: ../../library/email.rst:90 -msgid "" -"The foregoing represent the modern (unicode friendly) API of the email " -"package. The remaining sections, starting with the :class:`~email.message." -"Message` class, cover the legacy :data:`~email.policy.compat32` API that " -"deals much more directly with the details of how email messages are " -"represented. The :data:`~email.policy.compat32` API does *not* hide the " -"details of the RFCs from the application, but for applications that need to " -"operate at that level, they can be useful tools. This documentation is also " -"relevant for applications that are still using the :mod:`~email.policy." -"compat32` API for backward compatibility reasons." -msgstr "" - -#: ../../library/email.rst:100 -msgid "" -"Docs reorganized and rewritten to promote the new :class:`~email.message." -"EmailMessage`/:class:`~email.policy.EmailPolicy` API." -msgstr "" - -#: ../../library/email.rst:105 -msgid "Contents of the :mod:`email` package documentation:" -msgstr "" - -#: ../../library/email.rst:120 -msgid "Legacy API:" -msgstr "" - -#: ../../library/email.rst:135 -msgid "Module :mod:`smtplib`" -msgstr ":mod:`smtplib` 模組" - -#: ../../library/email.rst:136 -msgid "SMTP (Simple Mail Transport Protocol) client" -msgstr "" - -#: ../../library/email.rst:138 -msgid "Module :mod:`poplib`" -msgstr ":mod:`poplib` 模組" - -#: ../../library/email.rst:139 -msgid "POP (Post Office Protocol) client" -msgstr "" - -#: ../../library/email.rst:141 -msgid "Module :mod:`imaplib`" -msgstr ":mod:`imaplib` 模組" - -#: ../../library/email.rst:142 -msgid "IMAP (Internet Message Access Protocol) client" -msgstr "" - -#: ../../library/email.rst:144 -msgid "Module :mod:`mailbox`" -msgstr ":mod:`mailbox` 模組" - -#: ../../library/email.rst:145 -msgid "" -"Tools for creating, reading, and managing collections of messages on disk " -"using a variety standard formats." -msgstr "" - -#~ msgid "Module :mod:`nntplib`" -#~ msgstr ":mod:`nntplib` 模組" - -#~ msgid "Module :mod:`smtpd`" -#~ msgstr ":mod:`smtpd` 模組" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-09-23 07:52+0800\n" +"PO-Revision-Date: 2018-05-23 16:01+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/email.rst:2 +msgid ":mod:`!email` --- An email and MIME handling package" +msgstr ":mod:`!email` --- 郵件和 MIME 處理套件" + +#: ../../library/email.rst:11 +msgid "**Source code:** :source:`Lib/email/__init__.py`" +msgstr "**原始碼：**\\ :source:`Lib/email/__init__.py`" + +#: ../../library/email.rst:15 +msgid "" +"The :mod:`email` package is a library for managing email messages. It is " +"specifically *not* designed to do any sending of email messages to SMTP (:" +"rfc:`2821`), NNTP, or other servers; those are functions of modules such as :" +"mod:`smtplib`. The :mod:`email` package attempts to be as RFC-compliant as " +"possible, supporting :rfc:`5322` and :rfc:`6532`, as well as such MIME-" +"related RFCs as :rfc:`2045`, :rfc:`2046`, :rfc:`2047`, :rfc:`2183`, and :rfc:" +"`2231`." +msgstr "" + +#: ../../library/email.rst:23 +msgid "" +"The overall structure of the email package can be divided into three major " +"components, plus a fourth component that controls the behavior of the other " +"components." +msgstr "" + +#: ../../library/email.rst:27 +msgid "" +"The central component of the package is an \"object model\" that represents " +"email messages. An application interacts with the package primarily through " +"the object model interface defined in the :mod:`~email.message` sub-module. " +"The application can use this API to ask questions about an existing email, " +"to construct a new email, or to add or remove email subcomponents that " +"themselves use the same object model interface. That is, following the " +"nature of email messages and their MIME subcomponents, the email object " +"model is a tree structure of objects that all provide the :class:`~email." +"message.EmailMessage` API." +msgstr "" + +#: ../../library/email.rst:37 +msgid "" +"The other two major components of the package are the :mod:`~email.parser` " +"and the :mod:`~email.generator`. The parser takes the serialized version of " +"an email message (a stream of bytes) and converts it into a tree of :class:" +"`~email.message.EmailMessage` objects. The generator takes an :class:" +"`~email.message.EmailMessage` and turns it back into a serialized byte " +"stream. (The parser and generator also handle streams of text characters, " +"but this usage is discouraged as it is too easy to end up with messages that " +"are not valid in one way or another.)" +msgstr "" + +#: ../../library/email.rst:46 +msgid "" +"The control component is the :mod:`~email.policy` module. Every :class:" +"`~email.message.EmailMessage`, every :mod:`~email.generator`, and every :mod:" +"`~email.parser` has an associated :mod:`~email.policy` object that controls " +"its behavior. Usually an application only needs to specify the policy when " +"an :class:`~email.message.EmailMessage` is created, either by directly " +"instantiating an :class:`~email.message.EmailMessage` to create a new " +"email, or by parsing an input stream using a :mod:`~email.parser`. But the " +"policy can be changed when the message is serialized using a :mod:`~email." +"generator`. This allows, for example, a generic email message to be parsed " +"from disk, but to serialize it using standard SMTP settings when sending it " +"to an email server." +msgstr "" + +#: ../../library/email.rst:58 +msgid "" +"The email package does its best to hide the details of the various governing " +"RFCs from the application. Conceptually the application should be able to " +"treat the email message as a structured tree of unicode text and binary " +"attachments, without having to worry about how these are represented when " +"serialized. In practice, however, it is often necessary to be aware of at " +"least some of the rules governing MIME messages and their structure, " +"specifically the names and nature of the MIME \"content types\" and how they " +"identify multipart documents. For the most part this knowledge should only " +"be required for more complex applications, and even then it should only be " +"the high level structure in question, and not the details of how those " +"structures are represented. Since MIME content types are used widely in " +"modern internet software (not just email), this will be a familiar concept " +"to many programmers." +msgstr "" + +#: ../../library/email.rst:71 +msgid "" +"The following sections describe the functionality of the :mod:`email` " +"package. We start with the :mod:`~email.message` object model, which is the " +"primary interface an application will use, and follow that with the :mod:" +"`~email.parser` and :mod:`~email.generator` components. Then we cover the :" +"mod:`~email.policy` controls, which completes the treatment of the main " +"components of the library." +msgstr "" + +#: ../../library/email.rst:78 +msgid "" +"The next three sections cover the exceptions the package may raise and the " +"defects (non-compliance with the RFCs) that the :mod:`~email.parser` may " +"detect. Then we cover the :mod:`~email.headerregistry` and the :mod:`~email." +"contentmanager` sub-components, which provide tools for doing more detailed " +"manipulation of headers and payloads, respectively. Both of these " +"components contain features relevant to consuming and producing non-trivial " +"messages, but also document their extensibility APIs, which will be of " +"interest to advanced applications." +msgstr "" + +#: ../../library/email.rst:87 +msgid "" +"Following those is a set of examples of using the fundamental parts of the " +"APIs covered in the preceding sections." +msgstr "" + +#: ../../library/email.rst:90 +msgid "" +"The foregoing represent the modern (unicode friendly) API of the email " +"package. The remaining sections, starting with the :class:`~email.message." +"Message` class, cover the legacy :data:`~email.policy.compat32` API that " +"deals much more directly with the details of how email messages are " +"represented. The :data:`~email.policy.compat32` API does *not* hide the " +"details of the RFCs from the application, but for applications that need to " +"operate at that level, they can be useful tools. This documentation is also " +"relevant for applications that are still using the :mod:`~email.policy." +"compat32` API for backward compatibility reasons." +msgstr "" + +#: ../../library/email.rst:100 +msgid "" +"Docs reorganized and rewritten to promote the new :class:`~email.message." +"EmailMessage`/:class:`~email.policy.EmailPolicy` API." +msgstr "" + +#: ../../library/email.rst:105 +msgid "Contents of the :mod:`email` package documentation:" +msgstr "" + +#: ../../library/email.rst:120 +msgid "Legacy API:" +msgstr "" + +#: ../../library/email.rst:135 +msgid "Module :mod:`smtplib`" +msgstr ":mod:`smtplib` 模組" + +#: ../../library/email.rst:136 +msgid "SMTP (Simple Mail Transport Protocol) client" +msgstr "" + +#: ../../library/email.rst:138 +msgid "Module :mod:`poplib`" +msgstr ":mod:`poplib` 模組" + +#: ../../library/email.rst:139 +msgid "POP (Post Office Protocol) client" +msgstr "" + +#: ../../library/email.rst:141 +msgid "Module :mod:`imaplib`" +msgstr ":mod:`imaplib` 模組" + +#: ../../library/email.rst:142 +msgid "IMAP (Internet Message Access Protocol) client" +msgstr "" + +#: ../../library/email.rst:144 +msgid "Module :mod:`mailbox`" +msgstr ":mod:`mailbox` 模組" + +#: ../../library/email.rst:145 +msgid "" +"Tools for creating, reading, and managing collections of messages on disk " +"using a variety standard formats." +msgstr "" + +#~ msgid "Module :mod:`nntplib`" +#~ msgstr ":mod:`nntplib` 模組" + +#~ msgid "Module :mod:`smtpd`" +#~ msgstr ":mod:`smtpd` 模組" diff --git a/library/email.policy.po b/library/email.policy.po index c3ef102d76..1e6f5f5ac4 100644 --- a/library/email.policy.po +++ b/library/email.policy.po @@ -1,834 +1,834 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2026-01-07 00:14+0000\n" -"PO-Revision-Date: 2018-05-23 16:01+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/email.policy.rst:2 -msgid ":mod:`!email.policy`: Policy Objects" -msgstr "" - -#: ../../library/email.policy.rst:12 -msgid "**Source code:** :source:`Lib/email/policy.py`" -msgstr "**原始碼：**\\ :source:`Lib/email/policy.py`" - -#: ../../library/email.policy.rst:16 -msgid "" -"The :mod:`email` package's prime focus is the handling of email messages as " -"described by the various email and MIME RFCs. However, the general format " -"of email messages (a block of header fields each consisting of a name " -"followed by a colon followed by a value, the whole block followed by a blank " -"line and an arbitrary 'body'), is a format that has found utility outside of " -"the realm of email. Some of these uses conform fairly closely to the main " -"email RFCs, some do not. Even when working with email, there are times when " -"it is desirable to break strict compliance with the RFCs, such as generating " -"emails that interoperate with email servers that do not themselves follow " -"the standards, or that implement extensions you want to use in ways that " -"violate the standards." -msgstr "" - -#: ../../library/email.policy.rst:28 -msgid "" -"Policy objects give the email package the flexibility to handle all these " -"disparate use cases." -msgstr "" - -#: ../../library/email.policy.rst:31 -msgid "" -"A :class:`Policy` object encapsulates a set of attributes and methods that " -"control the behavior of various components of the email package during use. :" -"class:`Policy` instances can be passed to various classes and methods in the " -"email package to alter the default behavior. The settable values and their " -"defaults are described below." -msgstr "" - -#: ../../library/email.policy.rst:37 -msgid "" -"There is a default policy used by all classes in the email package. For all " -"of the :mod:`~email.parser` classes and the related convenience functions, " -"and for the :class:`~email.message.Message` class, this is the :class:" -"`Compat32` policy, via its corresponding pre-defined instance :const:" -"`compat32`. This policy provides for complete backward compatibility (in " -"some cases, including bug compatibility) with the pre-Python3.3 version of " -"the email package." -msgstr "" - -#: ../../library/email.policy.rst:44 -msgid "" -"This default value for the *policy* keyword to :class:`~email.message." -"EmailMessage` is the :class:`EmailPolicy` policy, via its pre-defined " -"instance :data:`~default`." -msgstr "" - -#: ../../library/email.policy.rst:48 -msgid "" -"When a :class:`~email.message.Message` or :class:`~email.message." -"EmailMessage` object is created, it acquires a policy. If the message is " -"created by a :mod:`~email.parser`, a policy passed to the parser will be the " -"policy used by the message it creates. If the message is created by the " -"program, then the policy can be specified when it is created. When a " -"message is passed to a :mod:`~email.generator`, the generator uses the " -"policy from the message by default, but you can also pass a specific policy " -"to the generator that will override the one stored on the message object." -msgstr "" - -#: ../../library/email.policy.rst:57 -msgid "" -"The default value for the *policy* keyword for the :mod:`email.parser` " -"classes and the parser convenience functions **will be changing** in a " -"future version of Python. Therefore you should **always specify explicitly " -"which policy you want to use** when calling any of the classes and functions " -"described in the :mod:`~email.parser` module." -msgstr "" - -#: ../../library/email.policy.rst:63 -msgid "" -"The first part of this documentation covers the features of :class:`Policy`, " -"an :term:`abstract base class` that defines the features that are common to " -"all policy objects, including :const:`compat32`. This includes certain hook " -"methods that are called internally by the email package, which a custom " -"policy could override to obtain different behavior. The second part " -"describes the concrete classes :class:`EmailPolicy` and :class:`Compat32`, " -"which implement the hooks that provide the standard behavior and the " -"backward compatible behavior and features, respectively." -msgstr "" - -#: ../../library/email.policy.rst:72 -msgid "" -":class:`Policy` instances are immutable, but they can be cloned, accepting " -"the same keyword arguments as the class constructor and returning a new :" -"class:`Policy` instance that is a copy of the original but with the " -"specified attributes values changed." -msgstr "" - -#: ../../library/email.policy.rst:77 -msgid "" -"As an example, the following code could be used to read an email message " -"from a file on disk and pass it to the system ``sendmail`` program on a Unix " -"system:" -msgstr "" - -#: ../../library/email.policy.rst:92 -msgid "" -">>> from email import message_from_binary_file\n" -">>> from email.generator import BytesGenerator\n" -">>> from email import policy\n" -">>> from subprocess import Popen, PIPE\n" -">>> with open('mymsg.txt', 'rb') as f:\n" -"... msg = message_from_binary_file(f, policy=policy.default)\n" -"...\n" -">>> p = Popen(['sendmail', msg['To'].addresses[0]], stdin=PIPE)\n" -">>> g = BytesGenerator(p.stdin, policy=msg.policy.clone(linesep='\\r\\n'))\n" -">>> g.flatten(msg)\n" -">>> p.stdin.close()\n" -">>> rc = p.wait()" -msgstr "" -">>> from email import message_from_binary_file\n" -">>> from email.generator import BytesGenerator\n" -">>> from email import policy\n" -">>> from subprocess import Popen, PIPE\n" -">>> with open('mymsg.txt', 'rb') as f:\n" -"... msg = message_from_binary_file(f, policy=policy.default)\n" -"...\n" -">>> p = Popen(['sendmail', msg['To'].addresses[0]], stdin=PIPE)\n" -">>> g = BytesGenerator(p.stdin, policy=msg.policy.clone(linesep='\\r\\n'))\n" -">>> g.flatten(msg)\n" -">>> p.stdin.close()\n" -">>> rc = p.wait()" - -#: ../../library/email.policy.rst:114 -msgid "" -"Here we are telling :class:`~email.generator.BytesGenerator` to use the RFC " -"correct line separator characters when creating the binary string to feed " -"into ``sendmail's`` ``stdin``, where the default policy would use ``\\n`` " -"line separators." -msgstr "" - -#: ../../library/email.policy.rst:119 -msgid "" -"Some email package methods accept a *policy* keyword argument, allowing the " -"policy to be overridden for that method. For example, the following code " -"uses the :meth:`~email.message.Message.as_bytes` method of the *msg* object " -"from the previous example and writes the message to a file using the native " -"line separators for the platform on which it is running::" -msgstr "" - -#: ../../library/email.policy.rst:125 -msgid "" -">>> import os\n" -">>> with open('converted.txt', 'wb') as f:\n" -"... f.write(msg.as_bytes(policy=msg.policy.clone(linesep=os.linesep)))\n" -"17" -msgstr "" -">>> import os\n" -">>> with open('converted.txt', 'wb') as f:\n" -"... f.write(msg.as_bytes(policy=msg.policy.clone(linesep=os.linesep)))\n" -"17" - -#: ../../library/email.policy.rst:130 -msgid "" -"Policy objects can also be combined using the addition operator, producing a " -"policy object whose settings are a combination of the non-default values of " -"the summed objects::" -msgstr "" - -#: ../../library/email.policy.rst:134 -msgid "" -">>> compat_SMTP = policy.compat32.clone(linesep='\\r\\n')\n" -">>> compat_strict = policy.compat32.clone(raise_on_defect=True)\n" -">>> compat_strict_SMTP = compat_SMTP + compat_strict" -msgstr "" -">>> compat_SMTP = policy.compat32.clone(linesep='\\r\\n')\n" -">>> compat_strict = policy.compat32.clone(raise_on_defect=True)\n" -">>> compat_strict_SMTP = compat_SMTP + compat_strict" - -#: ../../library/email.policy.rst:138 -msgid "" -"This operation is not commutative; that is, the order in which the objects " -"are added matters. To illustrate::" -msgstr "" - -#: ../../library/email.policy.rst:141 -msgid "" -">>> policy100 = policy.compat32.clone(max_line_length=100)\n" -">>> policy80 = policy.compat32.clone(max_line_length=80)\n" -">>> apolicy = policy100 + policy80\n" -">>> apolicy.max_line_length\n" -"80\n" -">>> apolicy = policy80 + policy100\n" -">>> apolicy.max_line_length\n" -"100" -msgstr "" -">>> policy100 = policy.compat32.clone(max_line_length=100)\n" -">>> policy80 = policy.compat32.clone(max_line_length=80)\n" -">>> apolicy = policy100 + policy80\n" -">>> apolicy.max_line_length\n" -"80\n" -">>> apolicy = policy80 + policy100\n" -">>> apolicy.max_line_length\n" -"100" - -#: ../../library/email.policy.rst:153 -msgid "" -"This is the :term:`abstract base class` for all policy classes. It provides " -"default implementations for a couple of trivial methods, as well as the " -"implementation of the immutability property, the :meth:`clone` method, and " -"the constructor semantics." -msgstr "" - -#: ../../library/email.policy.rst:158 -msgid "" -"The constructor of a policy class can be passed various keyword arguments. " -"The arguments that may be specified are any non-method properties on this " -"class, plus any additional non-method properties on the concrete class. A " -"value specified in the constructor will override the default value for the " -"corresponding attribute." -msgstr "" - -#: ../../library/email.policy.rst:164 -msgid "" -"This class defines the following properties, and thus values for the " -"following may be passed in the constructor of any policy class:" -msgstr "" - -#: ../../library/email.policy.rst:170 -msgid "" -"The maximum length of any line in the serialized output, not counting the " -"end of line character(s). Default is 78, per :rfc:`5322`. A value of ``0`` " -"or :const:`None` indicates that no line wrapping should be done at all." -msgstr "" - -#: ../../library/email.policy.rst:178 -msgid "" -"The string to be used to terminate lines in serialized output. The default " -"is ``\\n`` because that's the internal end-of-line discipline used by " -"Python, though ``\\r\\n`` is required by the RFCs." -msgstr "" - -#: ../../library/email.policy.rst:185 -msgid "" -"Controls the type of Content Transfer Encodings that may be or are required " -"to be used. The possible values are:" -msgstr "" - -#: ../../library/email.policy.rst:191 -msgid "``7bit``" -msgstr "``7bit``" - -#: ../../library/email.policy.rst:191 -msgid "" -"all data must be \"7 bit clean\" (ASCII-only). This means that where " -"necessary data will be encoded using either quoted-printable or base64 " -"encoding." -msgstr "" - -#: ../../library/email.policy.rst:195 -msgid "``8bit``" -msgstr "``8bit``" - -#: ../../library/email.policy.rst:195 -msgid "" -"data is not constrained to be 7 bit clean. Data in headers is still " -"required to be ASCII-only and so will be encoded (see :meth:`fold_binary` " -"and :attr:`~EmailPolicy.utf8` below for exceptions), but body parts may use " -"the ``8bit`` CTE." -msgstr "" - -#: ../../library/email.policy.rst:201 -msgid "" -"A ``cte_type`` value of ``8bit`` only works with ``BytesGenerator``, not " -"``Generator``, because strings cannot contain binary data. If a " -"``Generator`` is operating under a policy that specifies ``cte_type=8bit``, " -"it will act as if ``cte_type`` is ``7bit``." -msgstr "" - -#: ../../library/email.policy.rst:209 -msgid "" -"If :const:`True`, any defects encountered will be raised as errors. If :" -"const:`False` (the default), defects will be passed to the :meth:" -"`register_defect` method." -msgstr "" - -#: ../../library/email.policy.rst:216 -msgid "" -"If :const:`True`, lines starting with *\"From \"* in the body are escaped by " -"putting a ``>`` in front of them. This parameter is used when the message is " -"being serialized by a generator. Default: :const:`False`." -msgstr "" - -#: ../../library/email.policy.rst:226 -msgid "" -"A factory function for constructing a new empty message object. Used by the " -"parser when building messages. Defaults to ``None``, in which case :class:" -"`~email.message.Message` is used." -msgstr "" - -#: ../../library/email.policy.rst:235 -msgid "" -"If ``True`` (the default), the generator will raise :exc:`~email.errors." -"HeaderWriteError` instead of writing a header that is improperly folded or " -"delimited, such that it would be parsed as multiple headers or joined with " -"adjacent data. Such headers can be generated by custom header classes or " -"bugs in the ``email`` module." -msgstr "" - -#: ../../library/email.policy.rst:242 -msgid "" -"As it's a security feature, this defaults to ``True`` even in the :class:" -"`~email.policy.Compat32` policy. For backwards compatible, but unsafe, " -"behavior, it must be set to ``False`` explicitly." -msgstr "" - -#: ../../library/email.policy.rst:250 -msgid "" -"The following :class:`Policy` method is intended to be called by code using " -"the email library to create policy instances with custom settings:" -msgstr "" - -#: ../../library/email.policy.rst:256 -msgid "" -"Return a new :class:`Policy` instance whose attributes have the same values " -"as the current instance, except where those attributes are given new values " -"by the keyword arguments." -msgstr "" - -#: ../../library/email.policy.rst:261 -msgid "" -"The remaining :class:`Policy` methods are called by the email package code, " -"and are not intended to be called by an application using the email package. " -"A custom policy must implement all of these methods." -msgstr "" - -#: ../../library/email.policy.rst:268 -msgid "" -"Handle a *defect* found on *obj*. When the email package calls this method, " -"*defect* will always be a subclass of :class:`~email.errors.MessageDefect`." -msgstr "" - -#: ../../library/email.policy.rst:272 -msgid "" -"The default implementation checks the :attr:`raise_on_defect` flag. If it " -"is ``True``, *defect* is raised as an exception. If it is ``False`` (the " -"default), *obj* and *defect* are passed to :meth:`register_defect`." -msgstr "" - -#: ../../library/email.policy.rst:279 -msgid "" -"Register a *defect* on *obj*. In the email package, *defect* will always be " -"a subclass of :class:`~email.errors.MessageDefect`." -msgstr "" - -#: ../../library/email.policy.rst:282 -msgid "" -"The default implementation calls the ``append`` method of the ``defects`` " -"attribute of *obj*. When the email package calls :attr:`handle_defect`, " -"*obj* will normally have a ``defects`` attribute that has an ``append`` " -"method. Custom object types used with the email package (for example, " -"custom ``Message`` objects) should also provide such an attribute, otherwise " -"defects in parsed messages will raise unexpected errors." -msgstr "" - -#: ../../library/email.policy.rst:292 -msgid "Return the maximum allowed number of headers named *name*." -msgstr "" - -#: ../../library/email.policy.rst:294 -msgid "" -"Called when a header is added to an :class:`~email.message.EmailMessage` or :" -"class:`~email.message.Message` object. If the returned value is not ``0`` " -"or ``None``, and there are already a number of headers with the name *name* " -"greater than or equal to the value returned, a :exc:`ValueError` is raised." -msgstr "" - -#: ../../library/email.policy.rst:300 -msgid "" -"Because the default behavior of ``Message.__setitem__`` is to append the " -"value to the list of headers, it is easy to create duplicate headers without " -"realizing it. This method allows certain headers to be limited in the " -"number of instances of that header that may be added to a ``Message`` " -"programmatically. (The limit is not observed by the parser, which will " -"faithfully produce as many headers as exist in the message being parsed.)" -msgstr "" - -#: ../../library/email.policy.rst:308 -msgid "The default implementation returns ``None`` for all header names." -msgstr "" - -#: ../../library/email.policy.rst:313 -msgid "" -"The email package calls this method with a list of strings, each string " -"ending with the line separation characters found in the source being " -"parsed. The first line includes the field header name and separator. All " -"whitespace in the source is preserved. The method should return the " -"``(name, value)`` tuple that is to be stored in the ``Message`` to represent " -"the parsed header." -msgstr "" - -#: ../../library/email.policy.rst:320 -msgid "" -"If an implementation wishes to retain compatibility with the existing email " -"package policies, *name* should be the case preserved name (all characters " -"up to the '``:``' separator), while *value* should be the unfolded value " -"(all line separator characters removed, but whitespace kept intact), " -"stripped of leading whitespace." -msgstr "" - -#: ../../library/email.policy.rst:326 -msgid "*sourcelines* may contain surrogateescaped binary data." -msgstr "" - -#: ../../library/email.policy.rst:328 ../../library/email.policy.rst:344 -#: ../../library/email.policy.rst:360 -msgid "There is no default implementation" -msgstr "" - -#: ../../library/email.policy.rst:333 -msgid "" -"The email package calls this method with the name and value provided by the " -"application program when the application program is modifying a ``Message`` " -"programmatically (as opposed to a ``Message`` created by a parser). The " -"method should return the ``(name, value)`` tuple that is to be stored in the " -"``Message`` to represent the header." -msgstr "" - -#: ../../library/email.policy.rst:339 -msgid "" -"If an implementation wishes to retain compatibility with the existing email " -"package policies, the *name* and *value* should be strings or string " -"subclasses that do not change the content of the passed in arguments." -msgstr "" - -#: ../../library/email.policy.rst:349 -msgid "" -"The email package calls this method with the *name* and *value* currently " -"stored in the ``Message`` when that header is requested by the application " -"program, and whatever the method returns is what is passed back to the " -"application as the value of the header being retrieved. Note that there may " -"be more than one header with the same name stored in the ``Message``; the " -"method is passed the specific name and value of the header destined to be " -"returned to the application." -msgstr "" - -#: ../../library/email.policy.rst:357 -msgid "" -"*value* may contain surrogateescaped binary data. There should be no " -"surrogateescaped binary data in the value returned by the method." -msgstr "" - -#: ../../library/email.policy.rst:365 -msgid "" -"The email package calls this method with the *name* and *value* currently " -"stored in the ``Message`` for a given header. The method should return a " -"string that represents that header \"folded\" correctly (according to the " -"policy settings) by composing the *name* with the *value* and inserting :" -"attr:`linesep` characters at the appropriate places. See :rfc:`5322` for a " -"discussion of the rules for folding email headers." -msgstr "" - -#: ../../library/email.policy.rst:372 -msgid "" -"*value* may contain surrogateescaped binary data. There should be no " -"surrogateescaped binary data in the string returned by the method." -msgstr "" - -#: ../../library/email.policy.rst:378 -msgid "" -"The same as :meth:`fold`, except that the returned value should be a bytes " -"object rather than a string." -msgstr "" - -#: ../../library/email.policy.rst:381 -msgid "" -"*value* may contain surrogateescaped binary data. These could be converted " -"back into binary data in the returned bytes object." -msgstr "" - -#: ../../library/email.policy.rst:388 -msgid "" -"This concrete :class:`Policy` provides behavior that is intended to be fully " -"compliant with the current email RFCs. These include (but are not limited " -"to) :rfc:`5322`, :rfc:`2047`, and the current MIME RFCs." -msgstr "" - -#: ../../library/email.policy.rst:392 -msgid "" -"This policy adds new header parsing and folding algorithms. Instead of " -"simple strings, headers are ``str`` subclasses with attributes that depend " -"on the type of the field. The parsing and folding algorithm fully " -"implement :rfc:`2047` and :rfc:`5322`." -msgstr "" - -#: ../../library/email.policy.rst:397 -msgid "" -"The default value for the :attr:`~email.policy.Policy.message_factory` " -"attribute is :class:`~email.message.EmailMessage`." -msgstr "" - -#: ../../library/email.policy.rst:400 -msgid "" -"In addition to the settable attributes listed above that apply to all " -"policies, this policy adds the following additional attributes:" -msgstr "" - -#: ../../library/email.policy.rst:403 -msgid "[1]_" -msgstr "[1]_" - -#: ../../library/email.policy.rst:408 -msgid "" -"If ``False``, follow :rfc:`5322`, supporting non-ASCII characters in headers " -"by encoding them as \"encoded words\". If ``True``, follow :rfc:`6532` and " -"use ``utf-8`` encoding for headers. Messages formatted in this way may be " -"passed to SMTP servers that support the ``SMTPUTF8`` extension (:rfc:`6531`)." -msgstr "" - -#: ../../library/email.policy.rst:417 -msgid "" -"If the value for a header in the ``Message`` object originated from a :mod:" -"`~email.parser` (as opposed to being set by a program), this attribute " -"indicates whether or not a generator should refold that value when " -"transforming the message back into serialized form. The possible values are:" -msgstr "" - -#: ../../library/email.policy.rst:424 -msgid "``none``" -msgstr "``none``" - -#: ../../library/email.policy.rst:424 -msgid "all source values use original folding" -msgstr "" - -#: ../../library/email.policy.rst:426 -msgid "``long``" -msgstr "``long``" - -#: ../../library/email.policy.rst:426 -msgid "" -"source values that have any line that is longer than ``max_line_length`` " -"will be refolded" -msgstr "" - -#: ../../library/email.policy.rst:429 -msgid "``all``" -msgstr "``all``" - -#: ../../library/email.policy.rst:429 -msgid "all values are refolded." -msgstr "" - -#: ../../library/email.policy.rst:432 -msgid "The default is ``long``." -msgstr "預設為 ``long``。" - -#: ../../library/email.policy.rst:437 -msgid "" -"A callable that takes two arguments, ``name`` and ``value``, where ``name`` " -"is a header field name and ``value`` is an unfolded header field value, and " -"returns a string subclass that represents that header. A default " -"``header_factory`` (see :mod:`~email.headerregistry`) is provided that " -"supports custom parsing for the various address and date :RFC:`5322` header " -"field types, and the major MIME header field stypes. Support for additional " -"custom parsing will be added in the future." -msgstr "" - -#: ../../library/email.policy.rst:448 -msgid "" -"An object with at least two methods: get_content and set_content. When the :" -"meth:`~email.message.EmailMessage.get_content` or :meth:`~email.message." -"EmailMessage.set_content` method of an :class:`~email.message.EmailMessage` " -"object is called, it calls the corresponding method of this object, passing " -"it the message object as its first argument, and any arguments or keywords " -"that were passed to it as additional arguments. By default " -"``content_manager`` is set to :data:`~email.contentmanager.raw_data_manager`." -msgstr "" - -#: ../../library/email.policy.rst:460 ../../library/email.policy.rst:618 -msgid "" -"The class provides the following concrete implementations of the abstract " -"methods of :class:`Policy`:" -msgstr "" - -#: ../../library/email.policy.rst:466 -msgid "" -"Returns the value of the :attr:`~email.headerregistry.BaseHeader.max_count` " -"attribute of the specialized class used to represent the header with the " -"given name." -msgstr "" - -#: ../../library/email.policy.rst:474 ../../library/email.policy.rst:624 -msgid "" -"The name is parsed as everything up to the '``:``' and returned unmodified. " -"The value is determined by stripping leading whitespace off the remainder of " -"the first line, joining all subsequent lines together, and stripping any " -"trailing carriage return or linefeed characters." -msgstr "" - -#: ../../library/email.policy.rst:482 -msgid "" -"The name is returned unchanged. If the input value has a ``name`` attribute " -"and it matches *name* ignoring case, the value is returned unchanged. " -"Otherwise the *name* and *value* are passed to ``header_factory``, and the " -"resulting header object is returned as the value. In this case a " -"``ValueError`` is raised if the input value contains CR or LF characters." -msgstr "" - -#: ../../library/email.policy.rst:492 -msgid "" -"If the value has a ``name`` attribute, it is returned to unmodified. " -"Otherwise the *name*, and the *value* with any CR or LF characters removed, " -"are passed to the ``header_factory``, and the resulting header object is " -"returned. Any surrogateescaped bytes get turned into the unicode unknown-" -"character glyph." -msgstr "" - -#: ../../library/email.policy.rst:501 -msgid "" -"Header folding is controlled by the :attr:`refold_source` policy setting. A " -"value is considered to be a 'source value' if and only if it does not have a " -"``name`` attribute (having a ``name`` attribute means it is a header object " -"of some sort). If a source value needs to be refolded according to the " -"policy, it is converted into a header object by passing the *name* and the " -"*value* with any CR and LF characters removed to the ``header_factory``. " -"Folding of a header object is done by calling its ``fold`` method with the " -"current policy." -msgstr "" - -#: ../../library/email.policy.rst:510 -msgid "" -"Source values are split into lines using :meth:`~str.splitlines`. If the " -"value is not to be refolded, the lines are rejoined using the ``linesep`` " -"from the policy and returned. The exception is lines containing non-ascii " -"binary data. In that case the value is refolded regardless of the " -"``refold_source`` setting, which causes the binary data to be CTE encoded " -"using the ``unknown-8bit`` charset." -msgstr "" - -#: ../../library/email.policy.rst:520 -msgid "" -"The same as :meth:`fold` if :attr:`~Policy.cte_type` is ``7bit``, except " -"that the returned value is bytes." -msgstr "" - -#: ../../library/email.policy.rst:523 -msgid "" -"If :attr:`~Policy.cte_type` is ``8bit``, non-ASCII binary data is converted " -"back into bytes. Headers with binary data are not refolded, regardless of " -"the ``refold_header`` setting, since there is no way to know whether the " -"binary data consists of single byte characters or multibyte characters." -msgstr "" - -#: ../../library/email.policy.rst:530 -msgid "" -"The following instances of :class:`EmailPolicy` provide defaults suitable " -"for specific application domains. Note that in the future the behavior of " -"these instances (in particular the ``HTTP`` instance) may be adjusted to " -"conform even more closely to the RFCs relevant to their domains." -msgstr "" - -#: ../../library/email.policy.rst:538 -msgid "" -"An instance of ``EmailPolicy`` with all defaults unchanged. This policy " -"uses the standard Python ``\\n`` line endings rather than the RFC-correct " -"``\\r\\n``." -msgstr "" - -#: ../../library/email.policy.rst:545 -msgid "" -"Suitable for serializing messages in conformance with the email RFCs. Like " -"``default``, but with ``linesep`` set to ``\\r\\n``, which is RFC compliant." -msgstr "" - -#: ../../library/email.policy.rst:552 -msgid "" -"The same as ``SMTP`` except that :attr:`~EmailPolicy.utf8` is ``True``. " -"Useful for serializing messages to a message store without using encoded " -"words in the headers. Should only be used for SMTP transmission if the " -"sender or recipient addresses have non-ASCII characters (the :meth:`smtplib." -"SMTP.send_message` method handles this automatically)." -msgstr "" - -#: ../../library/email.policy.rst:561 -msgid "" -"Suitable for serializing headers with for use in HTTP traffic. Like " -"``SMTP`` except that ``max_line_length`` is set to ``None`` (unlimited)." -msgstr "" - -#: ../../library/email.policy.rst:567 -msgid "" -"Convenience instance. The same as ``default`` except that " -"``raise_on_defect`` is set to ``True``. This allows any policy to be made " -"strict by writing::" -msgstr "" - -#: ../../library/email.policy.rst:571 -msgid "somepolicy + policy.strict" -msgstr "somepolicy + policy.strict" - -#: ../../library/email.policy.rst:574 -msgid "" -"With all of these :class:`EmailPolicies <.EmailPolicy>`, the effective API " -"of the email package is changed from the Python 3.2 API in the following " -"ways:" -msgstr "" - -#: ../../library/email.policy.rst:577 -msgid "" -"Setting a header on a :class:`~email.message.Message` results in that header " -"being parsed and a header object created." -msgstr "" - -#: ../../library/email.policy.rst:580 -msgid "" -"Fetching a header value from a :class:`~email.message.Message` results in " -"that header being parsed and a header object created and returned." -msgstr "" - -#: ../../library/email.policy.rst:584 -msgid "" -"Any header object, or any header that is refolded due to the policy " -"settings, is folded using an algorithm that fully implements the RFC folding " -"algorithms, including knowing where encoded words are required and allowed." -msgstr "" - -#: ../../library/email.policy.rst:589 -msgid "" -"From the application view, this means that any header obtained through the :" -"class:`~email.message.EmailMessage` is a header object with extra " -"attributes, whose string value is the fully decoded unicode value of the " -"header. Likewise, a header may be assigned a new value, or a new header " -"created, using a unicode string, and the policy will take care of converting " -"the unicode string into the correct RFC encoded form." -msgstr "" - -#: ../../library/email.policy.rst:596 -msgid "" -"The header objects and their attributes are described in :mod:`~email." -"headerregistry`." -msgstr "" - -#: ../../library/email.policy.rst:603 -msgid "" -"This concrete :class:`Policy` is the backward compatibility policy. It " -"replicates the behavior of the email package in Python 3.2. The :mod:" -"`~email.policy` module also defines an instance of this class, :const:" -"`compat32`, that is used as the default policy. Thus the default behavior " -"of the email package is to maintain compatibility with Python 3.2." -msgstr "" - -#: ../../library/email.policy.rst:609 -msgid "" -"The following attributes have values that are different from the :class:" -"`Policy` default:" -msgstr "" - -#: ../../library/email.policy.rst:615 -msgid "The default is ``True``." -msgstr "預設值為 ``True``。" - -#: ../../library/email.policy.rst:632 -msgid "The name and value are returned unmodified." -msgstr "名稱和值會原封不動地回傳。" - -#: ../../library/email.policy.rst:637 -msgid "" -"If the value contains binary data, it is converted into a :class:`~email." -"header.Header` object using the ``unknown-8bit`` charset. Otherwise it is " -"returned unmodified." -msgstr "" - -#: ../../library/email.policy.rst:644 -msgid "" -"Headers are folded using the :class:`~email.header.Header` folding " -"algorithm, which preserves existing line breaks in the value, and wraps each " -"resulting line to the ``max_line_length``. Non-ASCII binary data are CTE " -"encoded using the ``unknown-8bit`` charset." -msgstr "" - -#: ../../library/email.policy.rst:652 -msgid "" -"Headers are folded using the :class:`~email.header.Header` folding " -"algorithm, which preserves existing line breaks in the value, and wraps each " -"resulting line to the ``max_line_length``. If ``cte_type`` is ``7bit``, non-" -"ascii binary data is CTE encoded using the ``unknown-8bit`` charset. " -"Otherwise the original source header is used, with its existing line breaks " -"and any (RFC invalid) binary data it may contain." -msgstr "" - -#: ../../library/email.policy.rst:662 -msgid "" -"An instance of :class:`Compat32`, providing backward compatibility with the " -"behavior of the email package in Python 3.2." -msgstr "" - -#: ../../library/email.policy.rst:667 -msgid "" -"The :const:`compat32` policy should not be used as a policy for :class:" -"`~email.message.EmailMessage` objects, and should only be used to serialize " -"messages that were created using the :const:`compat32` policy." -msgstr "" - -#: ../../library/email.policy.rst:674 -msgid "Footnotes" -msgstr "註解" - -#: ../../library/email.policy.rst:675 -msgid "" -"Originally added in 3.3 as a :term:`provisional feature `." -msgstr "" - -#~ msgid "The *mangle_from_* parameter." -#~ msgstr "*mangle_from_* 參數。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-01-07 00:14+0000\n" +"PO-Revision-Date: 2018-05-23 16:01+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/email.policy.rst:2 +msgid ":mod:`!email.policy`: Policy Objects" +msgstr "" + +#: ../../library/email.policy.rst:12 +msgid "**Source code:** :source:`Lib/email/policy.py`" +msgstr "**原始碼：**\\ :source:`Lib/email/policy.py`" + +#: ../../library/email.policy.rst:16 +msgid "" +"The :mod:`email` package's prime focus is the handling of email messages as " +"described by the various email and MIME RFCs. However, the general format " +"of email messages (a block of header fields each consisting of a name " +"followed by a colon followed by a value, the whole block followed by a blank " +"line and an arbitrary 'body'), is a format that has found utility outside of " +"the realm of email. Some of these uses conform fairly closely to the main " +"email RFCs, some do not. Even when working with email, there are times when " +"it is desirable to break strict compliance with the RFCs, such as generating " +"emails that interoperate with email servers that do not themselves follow " +"the standards, or that implement extensions you want to use in ways that " +"violate the standards." +msgstr "" + +#: ../../library/email.policy.rst:28 +msgid "" +"Policy objects give the email package the flexibility to handle all these " +"disparate use cases." +msgstr "" + +#: ../../library/email.policy.rst:31 +msgid "" +"A :class:`Policy` object encapsulates a set of attributes and methods that " +"control the behavior of various components of the email package during use. :" +"class:`Policy` instances can be passed to various classes and methods in the " +"email package to alter the default behavior. The settable values and their " +"defaults are described below." +msgstr "" + +#: ../../library/email.policy.rst:37 +msgid "" +"There is a default policy used by all classes in the email package. For all " +"of the :mod:`~email.parser` classes and the related convenience functions, " +"and for the :class:`~email.message.Message` class, this is the :class:" +"`Compat32` policy, via its corresponding pre-defined instance :const:" +"`compat32`. This policy provides for complete backward compatibility (in " +"some cases, including bug compatibility) with the pre-Python3.3 version of " +"the email package." +msgstr "" + +#: ../../library/email.policy.rst:44 +msgid "" +"This default value for the *policy* keyword to :class:`~email.message." +"EmailMessage` is the :class:`EmailPolicy` policy, via its pre-defined " +"instance :data:`~default`." +msgstr "" + +#: ../../library/email.policy.rst:48 +msgid "" +"When a :class:`~email.message.Message` or :class:`~email.message." +"EmailMessage` object is created, it acquires a policy. If the message is " +"created by a :mod:`~email.parser`, a policy passed to the parser will be the " +"policy used by the message it creates. If the message is created by the " +"program, then the policy can be specified when it is created. When a " +"message is passed to a :mod:`~email.generator`, the generator uses the " +"policy from the message by default, but you can also pass a specific policy " +"to the generator that will override the one stored on the message object." +msgstr "" + +#: ../../library/email.policy.rst:57 +msgid "" +"The default value for the *policy* keyword for the :mod:`email.parser` " +"classes and the parser convenience functions **will be changing** in a " +"future version of Python. Therefore you should **always specify explicitly " +"which policy you want to use** when calling any of the classes and functions " +"described in the :mod:`~email.parser` module." +msgstr "" + +#: ../../library/email.policy.rst:63 +msgid "" +"The first part of this documentation covers the features of :class:`Policy`, " +"an :term:`abstract base class` that defines the features that are common to " +"all policy objects, including :const:`compat32`. This includes certain hook " +"methods that are called internally by the email package, which a custom " +"policy could override to obtain different behavior. The second part " +"describes the concrete classes :class:`EmailPolicy` and :class:`Compat32`, " +"which implement the hooks that provide the standard behavior and the " +"backward compatible behavior and features, respectively." +msgstr "" + +#: ../../library/email.policy.rst:72 +msgid "" +":class:`Policy` instances are immutable, but they can be cloned, accepting " +"the same keyword arguments as the class constructor and returning a new :" +"class:`Policy` instance that is a copy of the original but with the " +"specified attributes values changed." +msgstr "" + +#: ../../library/email.policy.rst:77 +msgid "" +"As an example, the following code could be used to read an email message " +"from a file on disk and pass it to the system ``sendmail`` program on a Unix " +"system:" +msgstr "" + +#: ../../library/email.policy.rst:92 +msgid "" +">>> from email import message_from_binary_file\n" +">>> from email.generator import BytesGenerator\n" +">>> from email import policy\n" +">>> from subprocess import Popen, PIPE\n" +">>> with open('mymsg.txt', 'rb') as f:\n" +"... msg = message_from_binary_file(f, policy=policy.default)\n" +"...\n" +">>> p = Popen(['sendmail', msg['To'].addresses[0]], stdin=PIPE)\n" +">>> g = BytesGenerator(p.stdin, policy=msg.policy.clone(linesep='\\r\\n'))\n" +">>> g.flatten(msg)\n" +">>> p.stdin.close()\n" +">>> rc = p.wait()" +msgstr "" +">>> from email import message_from_binary_file\n" +">>> from email.generator import BytesGenerator\n" +">>> from email import policy\n" +">>> from subprocess import Popen, PIPE\n" +">>> with open('mymsg.txt', 'rb') as f:\n" +"... msg = message_from_binary_file(f, policy=policy.default)\n" +"...\n" +">>> p = Popen(['sendmail', msg['To'].addresses[0]], stdin=PIPE)\n" +">>> g = BytesGenerator(p.stdin, policy=msg.policy.clone(linesep='\\r\\n'))\n" +">>> g.flatten(msg)\n" +">>> p.stdin.close()\n" +">>> rc = p.wait()" + +#: ../../library/email.policy.rst:114 +msgid "" +"Here we are telling :class:`~email.generator.BytesGenerator` to use the RFC " +"correct line separator characters when creating the binary string to feed " +"into ``sendmail's`` ``stdin``, where the default policy would use ``\\n`` " +"line separators." +msgstr "" + +#: ../../library/email.policy.rst:119 +msgid "" +"Some email package methods accept a *policy* keyword argument, allowing the " +"policy to be overridden for that method. For example, the following code " +"uses the :meth:`~email.message.Message.as_bytes` method of the *msg* object " +"from the previous example and writes the message to a file using the native " +"line separators for the platform on which it is running::" +msgstr "" + +#: ../../library/email.policy.rst:125 +msgid "" +">>> import os\n" +">>> with open('converted.txt', 'wb') as f:\n" +"... f.write(msg.as_bytes(policy=msg.policy.clone(linesep=os.linesep)))\n" +"17" +msgstr "" +">>> import os\n" +">>> with open('converted.txt', 'wb') as f:\n" +"... f.write(msg.as_bytes(policy=msg.policy.clone(linesep=os.linesep)))\n" +"17" + +#: ../../library/email.policy.rst:130 +msgid "" +"Policy objects can also be combined using the addition operator, producing a " +"policy object whose settings are a combination of the non-default values of " +"the summed objects::" +msgstr "" + +#: ../../library/email.policy.rst:134 +msgid "" +">>> compat_SMTP = policy.compat32.clone(linesep='\\r\\n')\n" +">>> compat_strict = policy.compat32.clone(raise_on_defect=True)\n" +">>> compat_strict_SMTP = compat_SMTP + compat_strict" +msgstr "" +">>> compat_SMTP = policy.compat32.clone(linesep='\\r\\n')\n" +">>> compat_strict = policy.compat32.clone(raise_on_defect=True)\n" +">>> compat_strict_SMTP = compat_SMTP + compat_strict" + +#: ../../library/email.policy.rst:138 +msgid "" +"This operation is not commutative; that is, the order in which the objects " +"are added matters. To illustrate::" +msgstr "" + +#: ../../library/email.policy.rst:141 +msgid "" +">>> policy100 = policy.compat32.clone(max_line_length=100)\n" +">>> policy80 = policy.compat32.clone(max_line_length=80)\n" +">>> apolicy = policy100 + policy80\n" +">>> apolicy.max_line_length\n" +"80\n" +">>> apolicy = policy80 + policy100\n" +">>> apolicy.max_line_length\n" +"100" +msgstr "" +">>> policy100 = policy.compat32.clone(max_line_length=100)\n" +">>> policy80 = policy.compat32.clone(max_line_length=80)\n" +">>> apolicy = policy100 + policy80\n" +">>> apolicy.max_line_length\n" +"80\n" +">>> apolicy = policy80 + policy100\n" +">>> apolicy.max_line_length\n" +"100" + +#: ../../library/email.policy.rst:153 +msgid "" +"This is the :term:`abstract base class` for all policy classes. It provides " +"default implementations for a couple of trivial methods, as well as the " +"implementation of the immutability property, the :meth:`clone` method, and " +"the constructor semantics." +msgstr "" + +#: ../../library/email.policy.rst:158 +msgid "" +"The constructor of a policy class can be passed various keyword arguments. " +"The arguments that may be specified are any non-method properties on this " +"class, plus any additional non-method properties on the concrete class. A " +"value specified in the constructor will override the default value for the " +"corresponding attribute." +msgstr "" + +#: ../../library/email.policy.rst:164 +msgid "" +"This class defines the following properties, and thus values for the " +"following may be passed in the constructor of any policy class:" +msgstr "" + +#: ../../library/email.policy.rst:170 +msgid "" +"The maximum length of any line in the serialized output, not counting the " +"end of line character(s). Default is 78, per :rfc:`5322`. A value of ``0`` " +"or :const:`None` indicates that no line wrapping should be done at all." +msgstr "" + +#: ../../library/email.policy.rst:178 +msgid "" +"The string to be used to terminate lines in serialized output. The default " +"is ``\\n`` because that's the internal end-of-line discipline used by " +"Python, though ``\\r\\n`` is required by the RFCs." +msgstr "" + +#: ../../library/email.policy.rst:185 +msgid "" +"Controls the type of Content Transfer Encodings that may be or are required " +"to be used. The possible values are:" +msgstr "" + +#: ../../library/email.policy.rst:191 +msgid "``7bit``" +msgstr "``7bit``" + +#: ../../library/email.policy.rst:191 +msgid "" +"all data must be \"7 bit clean\" (ASCII-only). This means that where " +"necessary data will be encoded using either quoted-printable or base64 " +"encoding." +msgstr "" + +#: ../../library/email.policy.rst:195 +msgid "``8bit``" +msgstr "``8bit``" + +#: ../../library/email.policy.rst:195 +msgid "" +"data is not constrained to be 7 bit clean. Data in headers is still " +"required to be ASCII-only and so will be encoded (see :meth:`fold_binary` " +"and :attr:`~EmailPolicy.utf8` below for exceptions), but body parts may use " +"the ``8bit`` CTE." +msgstr "" + +#: ../../library/email.policy.rst:201 +msgid "" +"A ``cte_type`` value of ``8bit`` only works with ``BytesGenerator``, not " +"``Generator``, because strings cannot contain binary data. If a " +"``Generator`` is operating under a policy that specifies ``cte_type=8bit``, " +"it will act as if ``cte_type`` is ``7bit``." +msgstr "" + +#: ../../library/email.policy.rst:209 +msgid "" +"If :const:`True`, any defects encountered will be raised as errors. If :" +"const:`False` (the default), defects will be passed to the :meth:" +"`register_defect` method." +msgstr "" + +#: ../../library/email.policy.rst:216 +msgid "" +"If :const:`True`, lines starting with *\"From \"* in the body are escaped by " +"putting a ``>`` in front of them. This parameter is used when the message is " +"being serialized by a generator. Default: :const:`False`." +msgstr "" + +#: ../../library/email.policy.rst:226 +msgid "" +"A factory function for constructing a new empty message object. Used by the " +"parser when building messages. Defaults to ``None``, in which case :class:" +"`~email.message.Message` is used." +msgstr "" + +#: ../../library/email.policy.rst:235 +msgid "" +"If ``True`` (the default), the generator will raise :exc:`~email.errors." +"HeaderWriteError` instead of writing a header that is improperly folded or " +"delimited, such that it would be parsed as multiple headers or joined with " +"adjacent data. Such headers can be generated by custom header classes or " +"bugs in the ``email`` module." +msgstr "" + +#: ../../library/email.policy.rst:242 +msgid "" +"As it's a security feature, this defaults to ``True`` even in the :class:" +"`~email.policy.Compat32` policy. For backwards compatible, but unsafe, " +"behavior, it must be set to ``False`` explicitly." +msgstr "" + +#: ../../library/email.policy.rst:250 +msgid "" +"The following :class:`Policy` method is intended to be called by code using " +"the email library to create policy instances with custom settings:" +msgstr "" + +#: ../../library/email.policy.rst:256 +msgid "" +"Return a new :class:`Policy` instance whose attributes have the same values " +"as the current instance, except where those attributes are given new values " +"by the keyword arguments." +msgstr "" + +#: ../../library/email.policy.rst:261 +msgid "" +"The remaining :class:`Policy` methods are called by the email package code, " +"and are not intended to be called by an application using the email package. " +"A custom policy must implement all of these methods." +msgstr "" + +#: ../../library/email.policy.rst:268 +msgid "" +"Handle a *defect* found on *obj*. When the email package calls this method, " +"*defect* will always be a subclass of :class:`~email.errors.MessageDefect`." +msgstr "" + +#: ../../library/email.policy.rst:272 +msgid "" +"The default implementation checks the :attr:`raise_on_defect` flag. If it " +"is ``True``, *defect* is raised as an exception. If it is ``False`` (the " +"default), *obj* and *defect* are passed to :meth:`register_defect`." +msgstr "" + +#: ../../library/email.policy.rst:279 +msgid "" +"Register a *defect* on *obj*. In the email package, *defect* will always be " +"a subclass of :class:`~email.errors.MessageDefect`." +msgstr "" + +#: ../../library/email.policy.rst:282 +msgid "" +"The default implementation calls the ``append`` method of the ``defects`` " +"attribute of *obj*. When the email package calls :attr:`handle_defect`, " +"*obj* will normally have a ``defects`` attribute that has an ``append`` " +"method. Custom object types used with the email package (for example, " +"custom ``Message`` objects) should also provide such an attribute, otherwise " +"defects in parsed messages will raise unexpected errors." +msgstr "" + +#: ../../library/email.policy.rst:292 +msgid "Return the maximum allowed number of headers named *name*." +msgstr "" + +#: ../../library/email.policy.rst:294 +msgid "" +"Called when a header is added to an :class:`~email.message.EmailMessage` or :" +"class:`~email.message.Message` object. If the returned value is not ``0`` " +"or ``None``, and there are already a number of headers with the name *name* " +"greater than or equal to the value returned, a :exc:`ValueError` is raised." +msgstr "" + +#: ../../library/email.policy.rst:300 +msgid "" +"Because the default behavior of ``Message.__setitem__`` is to append the " +"value to the list of headers, it is easy to create duplicate headers without " +"realizing it. This method allows certain headers to be limited in the " +"number of instances of that header that may be added to a ``Message`` " +"programmatically. (The limit is not observed by the parser, which will " +"faithfully produce as many headers as exist in the message being parsed.)" +msgstr "" + +#: ../../library/email.policy.rst:308 +msgid "The default implementation returns ``None`` for all header names." +msgstr "" + +#: ../../library/email.policy.rst:313 +msgid "" +"The email package calls this method with a list of strings, each string " +"ending with the line separation characters found in the source being " +"parsed. The first line includes the field header name and separator. All " +"whitespace in the source is preserved. The method should return the " +"``(name, value)`` tuple that is to be stored in the ``Message`` to represent " +"the parsed header." +msgstr "" + +#: ../../library/email.policy.rst:320 +msgid "" +"If an implementation wishes to retain compatibility with the existing email " +"package policies, *name* should be the case preserved name (all characters " +"up to the '``:``' separator), while *value* should be the unfolded value " +"(all line separator characters removed, but whitespace kept intact), " +"stripped of leading whitespace." +msgstr "" + +#: ../../library/email.policy.rst:326 +msgid "*sourcelines* may contain surrogateescaped binary data." +msgstr "" + +#: ../../library/email.policy.rst:328 ../../library/email.policy.rst:344 +#: ../../library/email.policy.rst:360 +msgid "There is no default implementation" +msgstr "" + +#: ../../library/email.policy.rst:333 +msgid "" +"The email package calls this method with the name and value provided by the " +"application program when the application program is modifying a ``Message`` " +"programmatically (as opposed to a ``Message`` created by a parser). The " +"method should return the ``(name, value)`` tuple that is to be stored in the " +"``Message`` to represent the header." +msgstr "" + +#: ../../library/email.policy.rst:339 +msgid "" +"If an implementation wishes to retain compatibility with the existing email " +"package policies, the *name* and *value* should be strings or string " +"subclasses that do not change the content of the passed in arguments." +msgstr "" + +#: ../../library/email.policy.rst:349 +msgid "" +"The email package calls this method with the *name* and *value* currently " +"stored in the ``Message`` when that header is requested by the application " +"program, and whatever the method returns is what is passed back to the " +"application as the value of the header being retrieved. Note that there may " +"be more than one header with the same name stored in the ``Message``; the " +"method is passed the specific name and value of the header destined to be " +"returned to the application." +msgstr "" + +#: ../../library/email.policy.rst:357 +msgid "" +"*value* may contain surrogateescaped binary data. There should be no " +"surrogateescaped binary data in the value returned by the method." +msgstr "" + +#: ../../library/email.policy.rst:365 +msgid "" +"The email package calls this method with the *name* and *value* currently " +"stored in the ``Message`` for a given header. The method should return a " +"string that represents that header \"folded\" correctly (according to the " +"policy settings) by composing the *name* with the *value* and inserting :" +"attr:`linesep` characters at the appropriate places. See :rfc:`5322` for a " +"discussion of the rules for folding email headers." +msgstr "" + +#: ../../library/email.policy.rst:372 +msgid "" +"*value* may contain surrogateescaped binary data. There should be no " +"surrogateescaped binary data in the string returned by the method." +msgstr "" + +#: ../../library/email.policy.rst:378 +msgid "" +"The same as :meth:`fold`, except that the returned value should be a bytes " +"object rather than a string." +msgstr "" + +#: ../../library/email.policy.rst:381 +msgid "" +"*value* may contain surrogateescaped binary data. These could be converted " +"back into binary data in the returned bytes object." +msgstr "" + +#: ../../library/email.policy.rst:388 +msgid "" +"This concrete :class:`Policy` provides behavior that is intended to be fully " +"compliant with the current email RFCs. These include (but are not limited " +"to) :rfc:`5322`, :rfc:`2047`, and the current MIME RFCs." +msgstr "" + +#: ../../library/email.policy.rst:392 +msgid "" +"This policy adds new header parsing and folding algorithms. Instead of " +"simple strings, headers are ``str`` subclasses with attributes that depend " +"on the type of the field. The parsing and folding algorithm fully " +"implement :rfc:`2047` and :rfc:`5322`." +msgstr "" + +#: ../../library/email.policy.rst:397 +msgid "" +"The default value for the :attr:`~email.policy.Policy.message_factory` " +"attribute is :class:`~email.message.EmailMessage`." +msgstr "" + +#: ../../library/email.policy.rst:400 +msgid "" +"In addition to the settable attributes listed above that apply to all " +"policies, this policy adds the following additional attributes:" +msgstr "" + +#: ../../library/email.policy.rst:403 +msgid "[1]_" +msgstr "[1]_" + +#: ../../library/email.policy.rst:408 +msgid "" +"If ``False``, follow :rfc:`5322`, supporting non-ASCII characters in headers " +"by encoding them as \"encoded words\". If ``True``, follow :rfc:`6532` and " +"use ``utf-8`` encoding for headers. Messages formatted in this way may be " +"passed to SMTP servers that support the ``SMTPUTF8`` extension (:rfc:`6531`)." +msgstr "" + +#: ../../library/email.policy.rst:417 +msgid "" +"If the value for a header in the ``Message`` object originated from a :mod:" +"`~email.parser` (as opposed to being set by a program), this attribute " +"indicates whether or not a generator should refold that value when " +"transforming the message back into serialized form. The possible values are:" +msgstr "" + +#: ../../library/email.policy.rst:424 +msgid "``none``" +msgstr "``none``" + +#: ../../library/email.policy.rst:424 +msgid "all source values use original folding" +msgstr "" + +#: ../../library/email.policy.rst:426 +msgid "``long``" +msgstr "``long``" + +#: ../../library/email.policy.rst:426 +msgid "" +"source values that have any line that is longer than ``max_line_length`` " +"will be refolded" +msgstr "" + +#: ../../library/email.policy.rst:429 +msgid "``all``" +msgstr "``all``" + +#: ../../library/email.policy.rst:429 +msgid "all values are refolded." +msgstr "" + +#: ../../library/email.policy.rst:432 +msgid "The default is ``long``." +msgstr "預設為 ``long``。" + +#: ../../library/email.policy.rst:437 +msgid "" +"A callable that takes two arguments, ``name`` and ``value``, where ``name`` " +"is a header field name and ``value`` is an unfolded header field value, and " +"returns a string subclass that represents that header. A default " +"``header_factory`` (see :mod:`~email.headerregistry`) is provided that " +"supports custom parsing for the various address and date :RFC:`5322` header " +"field types, and the major MIME header field stypes. Support for additional " +"custom parsing will be added in the future." +msgstr "" + +#: ../../library/email.policy.rst:448 +msgid "" +"An object with at least two methods: get_content and set_content. When the :" +"meth:`~email.message.EmailMessage.get_content` or :meth:`~email.message." +"EmailMessage.set_content` method of an :class:`~email.message.EmailMessage` " +"object is called, it calls the corresponding method of this object, passing " +"it the message object as its first argument, and any arguments or keywords " +"that were passed to it as additional arguments. By default " +"``content_manager`` is set to :data:`~email.contentmanager.raw_data_manager`." +msgstr "" + +#: ../../library/email.policy.rst:460 ../../library/email.policy.rst:618 +msgid "" +"The class provides the following concrete implementations of the abstract " +"methods of :class:`Policy`:" +msgstr "" + +#: ../../library/email.policy.rst:466 +msgid "" +"Returns the value of the :attr:`~email.headerregistry.BaseHeader.max_count` " +"attribute of the specialized class used to represent the header with the " +"given name." +msgstr "" + +#: ../../library/email.policy.rst:474 ../../library/email.policy.rst:624 +msgid "" +"The name is parsed as everything up to the '``:``' and returned unmodified. " +"The value is determined by stripping leading whitespace off the remainder of " +"the first line, joining all subsequent lines together, and stripping any " +"trailing carriage return or linefeed characters." +msgstr "" + +#: ../../library/email.policy.rst:482 +msgid "" +"The name is returned unchanged. If the input value has a ``name`` attribute " +"and it matches *name* ignoring case, the value is returned unchanged. " +"Otherwise the *name* and *value* are passed to ``header_factory``, and the " +"resulting header object is returned as the value. In this case a " +"``ValueError`` is raised if the input value contains CR or LF characters." +msgstr "" + +#: ../../library/email.policy.rst:492 +msgid "" +"If the value has a ``name`` attribute, it is returned to unmodified. " +"Otherwise the *name*, and the *value* with any CR or LF characters removed, " +"are passed to the ``header_factory``, and the resulting header object is " +"returned. Any surrogateescaped bytes get turned into the unicode unknown-" +"character glyph." +msgstr "" + +#: ../../library/email.policy.rst:501 +msgid "" +"Header folding is controlled by the :attr:`refold_source` policy setting. A " +"value is considered to be a 'source value' if and only if it does not have a " +"``name`` attribute (having a ``name`` attribute means it is a header object " +"of some sort). If a source value needs to be refolded according to the " +"policy, it is converted into a header object by passing the *name* and the " +"*value* with any CR and LF characters removed to the ``header_factory``. " +"Folding of a header object is done by calling its ``fold`` method with the " +"current policy." +msgstr "" + +#: ../../library/email.policy.rst:510 +msgid "" +"Source values are split into lines using :meth:`~str.splitlines`. If the " +"value is not to be refolded, the lines are rejoined using the ``linesep`` " +"from the policy and returned. The exception is lines containing non-ascii " +"binary data. In that case the value is refolded regardless of the " +"``refold_source`` setting, which causes the binary data to be CTE encoded " +"using the ``unknown-8bit`` charset." +msgstr "" + +#: ../../library/email.policy.rst:520 +msgid "" +"The same as :meth:`fold` if :attr:`~Policy.cte_type` is ``7bit``, except " +"that the returned value is bytes." +msgstr "" + +#: ../../library/email.policy.rst:523 +msgid "" +"If :attr:`~Policy.cte_type` is ``8bit``, non-ASCII binary data is converted " +"back into bytes. Headers with binary data are not refolded, regardless of " +"the ``refold_header`` setting, since there is no way to know whether the " +"binary data consists of single byte characters or multibyte characters." +msgstr "" + +#: ../../library/email.policy.rst:530 +msgid "" +"The following instances of :class:`EmailPolicy` provide defaults suitable " +"for specific application domains. Note that in the future the behavior of " +"these instances (in particular the ``HTTP`` instance) may be adjusted to " +"conform even more closely to the RFCs relevant to their domains." +msgstr "" + +#: ../../library/email.policy.rst:538 +msgid "" +"An instance of ``EmailPolicy`` with all defaults unchanged. This policy " +"uses the standard Python ``\\n`` line endings rather than the RFC-correct " +"``\\r\\n``." +msgstr "" + +#: ../../library/email.policy.rst:545 +msgid "" +"Suitable for serializing messages in conformance with the email RFCs. Like " +"``default``, but with ``linesep`` set to ``\\r\\n``, which is RFC compliant." +msgstr "" + +#: ../../library/email.policy.rst:552 +msgid "" +"The same as ``SMTP`` except that :attr:`~EmailPolicy.utf8` is ``True``. " +"Useful for serializing messages to a message store without using encoded " +"words in the headers. Should only be used for SMTP transmission if the " +"sender or recipient addresses have non-ASCII characters (the :meth:`smtplib." +"SMTP.send_message` method handles this automatically)." +msgstr "" + +#: ../../library/email.policy.rst:561 +msgid "" +"Suitable for serializing headers with for use in HTTP traffic. Like " +"``SMTP`` except that ``max_line_length`` is set to ``None`` (unlimited)." +msgstr "" + +#: ../../library/email.policy.rst:567 +msgid "" +"Convenience instance. The same as ``default`` except that " +"``raise_on_defect`` is set to ``True``. This allows any policy to be made " +"strict by writing::" +msgstr "" + +#: ../../library/email.policy.rst:571 +msgid "somepolicy + policy.strict" +msgstr "somepolicy + policy.strict" + +#: ../../library/email.policy.rst:574 +msgid "" +"With all of these :class:`EmailPolicies <.EmailPolicy>`, the effective API " +"of the email package is changed from the Python 3.2 API in the following " +"ways:" +msgstr "" + +#: ../../library/email.policy.rst:577 +msgid "" +"Setting a header on a :class:`~email.message.Message` results in that header " +"being parsed and a header object created." +msgstr "" + +#: ../../library/email.policy.rst:580 +msgid "" +"Fetching a header value from a :class:`~email.message.Message` results in " +"that header being parsed and a header object created and returned." +msgstr "" + +#: ../../library/email.policy.rst:584 +msgid "" +"Any header object, or any header that is refolded due to the policy " +"settings, is folded using an algorithm that fully implements the RFC folding " +"algorithms, including knowing where encoded words are required and allowed." +msgstr "" + +#: ../../library/email.policy.rst:589 +msgid "" +"From the application view, this means that any header obtained through the :" +"class:`~email.message.EmailMessage` is a header object with extra " +"attributes, whose string value is the fully decoded unicode value of the " +"header. Likewise, a header may be assigned a new value, or a new header " +"created, using a unicode string, and the policy will take care of converting " +"the unicode string into the correct RFC encoded form." +msgstr "" + +#: ../../library/email.policy.rst:596 +msgid "" +"The header objects and their attributes are described in :mod:`~email." +"headerregistry`." +msgstr "" + +#: ../../library/email.policy.rst:603 +msgid "" +"This concrete :class:`Policy` is the backward compatibility policy. It " +"replicates the behavior of the email package in Python 3.2. The :mod:" +"`~email.policy` module also defines an instance of this class, :const:" +"`compat32`, that is used as the default policy. Thus the default behavior " +"of the email package is to maintain compatibility with Python 3.2." +msgstr "" + +#: ../../library/email.policy.rst:609 +msgid "" +"The following attributes have values that are different from the :class:" +"`Policy` default:" +msgstr "" + +#: ../../library/email.policy.rst:615 +msgid "The default is ``True``." +msgstr "預設值為 ``True``。" + +#: ../../library/email.policy.rst:632 +msgid "The name and value are returned unmodified." +msgstr "名稱和值會原封不動地回傳。" + +#: ../../library/email.policy.rst:637 +msgid "" +"If the value contains binary data, it is converted into a :class:`~email." +"header.Header` object using the ``unknown-8bit`` charset. Otherwise it is " +"returned unmodified." +msgstr "" + +#: ../../library/email.policy.rst:644 +msgid "" +"Headers are folded using the :class:`~email.header.Header` folding " +"algorithm, which preserves existing line breaks in the value, and wraps each " +"resulting line to the ``max_line_length``. Non-ASCII binary data are CTE " +"encoded using the ``unknown-8bit`` charset." +msgstr "" + +#: ../../library/email.policy.rst:652 +msgid "" +"Headers are folded using the :class:`~email.header.Header` folding " +"algorithm, which preserves existing line breaks in the value, and wraps each " +"resulting line to the ``max_line_length``. If ``cte_type`` is ``7bit``, non-" +"ascii binary data is CTE encoded using the ``unknown-8bit`` charset. " +"Otherwise the original source header is used, with its existing line breaks " +"and any (RFC invalid) binary data it may contain." +msgstr "" + +#: ../../library/email.policy.rst:662 +msgid "" +"An instance of :class:`Compat32`, providing backward compatibility with the " +"behavior of the email package in Python 3.2." +msgstr "" + +#: ../../library/email.policy.rst:667 +msgid "" +"The :const:`compat32` policy should not be used as a policy for :class:" +"`~email.message.EmailMessage` objects, and should only be used to serialize " +"messages that were created using the :const:`compat32` policy." +msgstr "" + +#: ../../library/email.policy.rst:674 +msgid "Footnotes" +msgstr "註解" + +#: ../../library/email.policy.rst:675 +msgid "" +"Originally added in 3.3 as a :term:`provisional feature `." +msgstr "" + +#~ msgid "The *mangle_from_* parameter." +#~ msgstr "*mangle_from_* 參數。" diff --git a/library/email.utils.po b/library/email.utils.po index 37cc9eb500..26c212a3b4 100644 --- a/library/email.utils.po +++ b/library/email.utils.po @@ -1,281 +1,281 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# FIRST AUTHOR , YEAR. -# -#, fuzzy -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" -"tw)\n" -"Language: zh_TW\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=UTF-8\n" -"Content-Transfer-Encoding: 8bit\n" - -#: ../../library/email.utils.rst:2 -msgid ":mod:`!email.utils`: Miscellaneous utilities" -msgstr ":mod:`!email.utils`：雜項工具" - -#: ../../library/email.utils.rst:7 -msgid "**Source code:** :source:`Lib/email/utils.py`" -msgstr "**原始碼：**\\ :source:`Lib/email/utils.py`" - -#: ../../library/email.utils.rst:11 -msgid "" -"There are a couple of useful utilities provided in the :mod:`email.utils` " -"module:" -msgstr "" - -#: ../../library/email.utils.rst:16 -msgid "" -"Return local time as an aware datetime object. If called without arguments, " -"return current time. Otherwise *dt* argument should be " -"a :class:`~datetime.datetime` instance, and it is converted to the local " -"time zone according to the system time zone database. If *dt* is naive " -"(that is, ``dt.tzinfo`` is ``None``), it is assumed to be in local time." -msgstr "" - -#: ../../library/email.utils.rst:24 -msgid "The *isdst* parameter." -msgstr "" - -#: ../../library/email.utils.rst:29 -msgid "" -"Returns a string suitable for an :rfc:`2822`\\ " -"-compliant :mailheader:`Message-ID` header. Optional *idstring* if given, " -"is a string used to strengthen the uniqueness of the message id. Optional " -"*domain* if given provides the portion of the msgid after the '@'. The " -"default is the local hostname. It is not normally necessary to override " -"this default, but may be useful certain cases, such as a constructing " -"distributed system that uses a consistent domain name across multiple hosts." -msgstr "" - -#: ../../library/email.utils.rst:37 -msgid "Added the *domain* keyword." -msgstr "新增 *domain* 關鍵字。" - -#: ../../library/email.utils.rst:41 -msgid "" -"The remaining functions are part of the legacy (``Compat32``) email API. " -"There is no need to directly use these with the new API, since the parsing " -"and formatting they provide is done automatically by the header parsing " -"machinery of the new API." -msgstr "" - -#: ../../library/email.utils.rst:49 -msgid "" -"Return a new string with backslashes in *str* replaced by two backslashes, " -"and double quotes replaced by backslash-double quote." -msgstr "" - -#: ../../library/email.utils.rst:55 -msgid "" -"Return a new string which is an *unquoted* version of *str*. If *str* ends " -"and begins with double quotes, they are stripped off. Likewise if *str* " -"ends and begins with angle brackets, they are stripped off." -msgstr "" - -#: ../../library/email.utils.rst:62 -msgid "" -"Parse address -- which should be the value of some address-containing field " -"such as :mailheader:`To` or :mailheader:`Cc` -- into its constituent " -"*realname* and *email address* parts. Returns a tuple of that information, " -"unless the parse fails, in which case a 2-tuple of ``('', '')`` is returned." -msgstr "" - -#: ../../library/email.utils.rst:67 ../../library/email.utils.rst:95 -msgid "" -"If *strict* is true, use a strict parser which rejects malformed inputs." -msgstr "" - -#: ../../library/email.utils.rst:69 ../../library/email.utils.rst:107 -msgid "Add *strict* optional parameter and reject malformed inputs by default." -msgstr "" - -#: ../../library/email.utils.rst:75 -msgid "" -"The inverse of :meth:`parseaddr`, this takes a 2-tuple of the form " -"``(realname, email_address)`` and returns the string value suitable for " -"a :mailheader:`To` or :mailheader:`Cc` header. If the first element of " -"*pair* is false, then the second element is returned unmodified." -msgstr "" - -#: ../../library/email.utils.rst:80 -msgid "" -"Optional *charset* is the character set that will be used in the :rfc:`2047` " -"encoding of the ``realname`` if the ``realname`` contains non-ASCII " -"characters. Can be an instance of :class:`str` or " -"a :class:`~email.charset.Charset`. Defaults to ``utf-8``." -msgstr "" - -#: ../../library/email.utils.rst:85 -msgid "Added the *charset* option." -msgstr "新增 *charset* 選項。" - -#: ../../library/email.utils.rst:91 -msgid "" -"This method returns a list of 2-tuples of the form returned by " -"``parseaddr()``. *fieldvalues* is a sequence of header field values as might " -"be returned by :meth:`Message.get_all `." -msgstr "" - -#: ../../library/email.utils.rst:97 -msgid "Here's a simple example that gets all the recipients of a message::" -msgstr "" - -#: ../../library/email.utils.rst:99 -msgid "" -"from email.utils import getaddresses\n" -"\n" -"tos = msg.get_all('to', [])\n" -"ccs = msg.get_all('cc', [])\n" -"resent_tos = msg.get_all('resent-to', [])\n" -"resent_ccs = msg.get_all('resent-cc', [])\n" -"all_recipients = getaddresses(tos + ccs + resent_tos + resent_ccs)" -msgstr "" -"from email.utils import getaddresses\n" -"\n" -"tos = msg.get_all('to', [])\n" -"ccs = msg.get_all('cc', [])\n" -"resent_tos = msg.get_all('resent-to', [])\n" -"resent_ccs = msg.get_all('resent-cc', [])\n" -"all_recipients = getaddresses(tos + ccs + resent_tos + resent_ccs)" - -#: ../../library/email.utils.rst:113 -msgid "" -"Attempts to parse a date according to the rules in :rfc:`2822`. however, " -"some mailers don't follow that format as specified, so :func:`parsedate` " -"tries to guess correctly in such cases. *date* is a string containing " -"an :rfc:`2822` date, such as ``\"Mon, 20 Nov 1995 19:12:08 -0500\"``. If " -"it succeeds in parsing the date, :func:`parsedate` returns a 9-tuple that " -"can be passed directly to :func:`time.mktime`; otherwise ``None`` will be " -"returned. Note that indexes 6, 7, and 8 of the result tuple are not usable." -msgstr "" - -#: ../../library/email.utils.rst:124 -msgid "" -"Performs the same function as :func:`parsedate`, but returns either ``None`` " -"or a 10-tuple; the first 9 elements make up a tuple that can be passed " -"directly to :func:`time.mktime`, and the tenth is the offset of the date's " -"timezone from UTC (which is the official term for Greenwich Mean Time) " -"[#]_. If the input string has no timezone, the last element of the tuple " -"returned is ``0``, which represents UTC. Note that indexes 6, 7, and 8 of " -"the result tuple are not usable." -msgstr "" - -#: ../../library/email.utils.rst:134 -msgid "" -"The inverse of :func:`format_datetime`. Performs the same function " -"as :func:`parsedate`, but on success returns a :mod:`~datetime.datetime`; " -"otherwise ``ValueError`` is raised if *date* contains an invalid value such " -"as an hour greater than 23 or a timezone offset not between -24 and 24 " -"hours. If the input date has a timezone of ``-0000``, the ``datetime`` will " -"be a naive ``datetime``, and if the date is conforming to the RFCs it will " -"represent a time in UTC but with no indication of the actual source timezone " -"of the message the date comes from. If the input date has any other valid " -"timezone offset, the ``datetime`` will be an aware ``datetime`` with the " -"corresponding a :class:`~datetime.timezone` :class:`~datetime.tzinfo`." -msgstr "" - -#: ../../library/email.utils.rst:150 -msgid "" -"Turn a 10-tuple as returned by :func:`parsedate_tz` into a UTC timestamp " -"(seconds since the Epoch). If the timezone item in the tuple is ``None``, " -"assume local time." -msgstr "" - -#: ../../library/email.utils.rst:157 -msgid "Returns a date string as per :rfc:`2822`, e.g.::" -msgstr "" - -#: ../../library/email.utils.rst:159 -msgid "Fri, 09 Nov 2001 01:08:47 -0000" -msgstr "Fri, 09 Nov 2001 01:08:47 -0000" - -#: ../../library/email.utils.rst:161 -msgid "" -"Optional *timeval* if given is a floating-point time value as accepted " -"by :func:`time.gmtime` and :func:`time.localtime`, otherwise the current " -"time is used." -msgstr "" - -#: ../../library/email.utils.rst:165 -msgid "" -"Optional *localtime* is a flag that when ``True``, interprets *timeval*, and " -"returns a date relative to the local timezone instead of UTC, properly " -"taking daylight savings time into account. The default is ``False`` meaning " -"UTC is used." -msgstr "" - -#: ../../library/email.utils.rst:170 -msgid "" -"Optional *usegmt* is a flag that when ``True``, outputs a date string with " -"the timezone as an ascii string ``GMT``, rather than a numeric ``-0000``. " -"This is needed for some protocols (such as HTTP). This only applies when " -"*localtime* is ``False``. The default is ``False``." -msgstr "" - -#: ../../library/email.utils.rst:178 -msgid "" -"Like ``formatdate``, but the input is a :mod:`datetime` instance. If it is " -"a naive datetime, it is assumed to be \"UTC with no information about the " -"source timezone\", and the conventional ``-0000`` is used for the timezone. " -"If it is an aware ``datetime``, then the numeric timezone offset is used. If " -"it is an aware timezone with offset zero, then *usegmt* may be set to " -"``True``, in which case the string ``GMT`` is used instead of the numeric " -"timezone offset. This provides a way to generate standards conformant HTTP " -"date headers." -msgstr "" - -#: ../../library/email.utils.rst:192 -msgid "Decode the string *s* according to :rfc:`2231`." -msgstr "" - -#: ../../library/email.utils.rst:197 -msgid "" -"Encode the string *s* according to :rfc:`2231`. Optional *charset* and " -"*language*, if given is the character set name and language name to use. If " -"neither is given, *s* is returned as-is. If *charset* is given but " -"*language* is not, the string is encoded using the empty string for " -"*language*." -msgstr "" - -#: ../../library/email.utils.rst:205 -msgid "" -"When a header parameter is encoded in :rfc:`2231` " -"format, :meth:`Message.get_param ` may " -"return a 3-tuple containing the character set, language, and " -"value. :func:`collapse_rfc2231_value` turns this into a unicode string. " -"Optional *errors* is passed to the *errors* argument " -"of :class:`str`'s :func:`~str.encode` method; it defaults to ``'replace'``. " -"Optional *fallback_charset* specifies the character set to use if the one in " -"the :rfc:`2231` header is not known by Python; it defaults to ``'us-ascii'``." -msgstr "" - -#: ../../library/email.utils.rst:214 -msgid "" -"For convenience, if the *value* passed to :func:`collapse_rfc2231_value` is " -"not a tuple, it should be a string and it is returned unquoted." -msgstr "" - -#: ../../library/email.utils.rst:220 -msgid "" -"Decode parameters list according to :rfc:`2231`. *params* is a sequence of " -"2-tuples containing elements of the form ``(content-type, string-value)``." -msgstr "" - -#: ../../library/email.utils.rst:225 -msgid "Footnotes" -msgstr "註解" - -#: ../../library/email.utils.rst:226 -msgid "" -"Note that the sign of the timezone offset is the opposite of the sign of the " -"``time.timezone`` variable for the same timezone; the latter variable " -"follows the POSIX standard while this module follows :rfc:`2822`." -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" +"tw)\n" +"Language: zh_TW\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../library/email.utils.rst:2 +msgid ":mod:`!email.utils`: Miscellaneous utilities" +msgstr ":mod:`!email.utils`：雜項工具" + +#: ../../library/email.utils.rst:7 +msgid "**Source code:** :source:`Lib/email/utils.py`" +msgstr "**原始碼：**\\ :source:`Lib/email/utils.py`" + +#: ../../library/email.utils.rst:11 +msgid "" +"There are a couple of useful utilities provided in the :mod:`email.utils` " +"module:" +msgstr "" + +#: ../../library/email.utils.rst:16 +msgid "" +"Return local time as an aware datetime object. If called without arguments, " +"return current time. Otherwise *dt* argument should be " +"a :class:`~datetime.datetime` instance, and it is converted to the local " +"time zone according to the system time zone database. If *dt* is naive " +"(that is, ``dt.tzinfo`` is ``None``), it is assumed to be in local time." +msgstr "" + +#: ../../library/email.utils.rst:24 +msgid "The *isdst* parameter." +msgstr "" + +#: ../../library/email.utils.rst:29 +msgid "" +"Returns a string suitable for an :rfc:`2822`\\ " +"-compliant :mailheader:`Message-ID` header. Optional *idstring* if given, " +"is a string used to strengthen the uniqueness of the message id. Optional " +"*domain* if given provides the portion of the msgid after the '@'. The " +"default is the local hostname. It is not normally necessary to override " +"this default, but may be useful certain cases, such as a constructing " +"distributed system that uses a consistent domain name across multiple hosts." +msgstr "" + +#: ../../library/email.utils.rst:37 +msgid "Added the *domain* keyword." +msgstr "新增 *domain* 關鍵字。" + +#: ../../library/email.utils.rst:41 +msgid "" +"The remaining functions are part of the legacy (``Compat32``) email API. " +"There is no need to directly use these with the new API, since the parsing " +"and formatting they provide is done automatically by the header parsing " +"machinery of the new API." +msgstr "" + +#: ../../library/email.utils.rst:49 +msgid "" +"Return a new string with backslashes in *str* replaced by two backslashes, " +"and double quotes replaced by backslash-double quote." +msgstr "" + +#: ../../library/email.utils.rst:55 +msgid "" +"Return a new string which is an *unquoted* version of *str*. If *str* ends " +"and begins with double quotes, they are stripped off. Likewise if *str* " +"ends and begins with angle brackets, they are stripped off." +msgstr "" + +#: ../../library/email.utils.rst:62 +msgid "" +"Parse address -- which should be the value of some address-containing field " +"such as :mailheader:`To` or :mailheader:`Cc` -- into its constituent " +"*realname* and *email address* parts. Returns a tuple of that information, " +"unless the parse fails, in which case a 2-tuple of ``('', '')`` is returned." +msgstr "" + +#: ../../library/email.utils.rst:67 ../../library/email.utils.rst:95 +msgid "" +"If *strict* is true, use a strict parser which rejects malformed inputs." +msgstr "" + +#: ../../library/email.utils.rst:69 ../../library/email.utils.rst:107 +msgid "Add *strict* optional parameter and reject malformed inputs by default." +msgstr "" + +#: ../../library/email.utils.rst:75 +msgid "" +"The inverse of :meth:`parseaddr`, this takes a 2-tuple of the form " +"``(realname, email_address)`` and returns the string value suitable for " +"a :mailheader:`To` or :mailheader:`Cc` header. If the first element of " +"*pair* is false, then the second element is returned unmodified." +msgstr "" + +#: ../../library/email.utils.rst:80 +msgid "" +"Optional *charset* is the character set that will be used in the :rfc:`2047` " +"encoding of the ``realname`` if the ``realname`` contains non-ASCII " +"characters. Can be an instance of :class:`str` or " +"a :class:`~email.charset.Charset`. Defaults to ``utf-8``." +msgstr "" + +#: ../../library/email.utils.rst:85 +msgid "Added the *charset* option." +msgstr "新增 *charset* 選項。" + +#: ../../library/email.utils.rst:91 +msgid "" +"This method returns a list of 2-tuples of the form returned by " +"``parseaddr()``. *fieldvalues* is a sequence of header field values as might " +"be returned by :meth:`Message.get_all `." +msgstr "" + +#: ../../library/email.utils.rst:97 +msgid "Here's a simple example that gets all the recipients of a message::" +msgstr "" + +#: ../../library/email.utils.rst:99 +msgid "" +"from email.utils import getaddresses\n" +"\n" +"tos = msg.get_all('to', [])\n" +"ccs = msg.get_all('cc', [])\n" +"resent_tos = msg.get_all('resent-to', [])\n" +"resent_ccs = msg.get_all('resent-cc', [])\n" +"all_recipients = getaddresses(tos + ccs + resent_tos + resent_ccs)" +msgstr "" +"from email.utils import getaddresses\n" +"\n" +"tos = msg.get_all('to', [])\n" +"ccs = msg.get_all('cc', [])\n" +"resent_tos = msg.get_all('resent-to', [])\n" +"resent_ccs = msg.get_all('resent-cc', [])\n" +"all_recipients = getaddresses(tos + ccs + resent_tos + resent_ccs)" + +#: ../../library/email.utils.rst:113 +msgid "" +"Attempts to parse a date according to the rules in :rfc:`2822`. however, " +"some mailers don't follow that format as specified, so :func:`parsedate` " +"tries to guess correctly in such cases. *date* is a string containing " +"an :rfc:`2822` date, such as ``\"Mon, 20 Nov 1995 19:12:08 -0500\"``. If " +"it succeeds in parsing the date, :func:`parsedate` returns a 9-tuple that " +"can be passed directly to :func:`time.mktime`; otherwise ``None`` will be " +"returned. Note that indexes 6, 7, and 8 of the result tuple are not usable." +msgstr "" + +#: ../../library/email.utils.rst:124 +msgid "" +"Performs the same function as :func:`parsedate`, but returns either ``None`` " +"or a 10-tuple; the first 9 elements make up a tuple that can be passed " +"directly to :func:`time.mktime`, and the tenth is the offset of the date's " +"timezone from UTC (which is the official term for Greenwich Mean Time) " +"[#]_. If the input string has no timezone, the last element of the tuple " +"returned is ``0``, which represents UTC. Note that indexes 6, 7, and 8 of " +"the result tuple are not usable." +msgstr "" + +#: ../../library/email.utils.rst:134 +msgid "" +"The inverse of :func:`format_datetime`. Performs the same function " +"as :func:`parsedate`, but on success returns a :mod:`~datetime.datetime`; " +"otherwise ``ValueError`` is raised if *date* contains an invalid value such " +"as an hour greater than 23 or a timezone offset not between -24 and 24 " +"hours. If the input date has a timezone of ``-0000``, the ``datetime`` will " +"be a naive ``datetime``, and if the date is conforming to the RFCs it will " +"represent a time in UTC but with no indication of the actual source timezone " +"of the message the date comes from. If the input date has any other valid " +"timezone offset, the ``datetime`` will be an aware ``datetime`` with the " +"corresponding a :class:`~datetime.timezone` :class:`~datetime.tzinfo`." +msgstr "" + +#: ../../library/email.utils.rst:150 +msgid "" +"Turn a 10-tuple as returned by :func:`parsedate_tz` into a UTC timestamp " +"(seconds since the Epoch). If the timezone item in the tuple is ``None``, " +"assume local time." +msgstr "" + +#: ../../library/email.utils.rst:157 +msgid "Returns a date string as per :rfc:`2822`, e.g.::" +msgstr "" + +#: ../../library/email.utils.rst:159 +msgid "Fri, 09 Nov 2001 01:08:47 -0000" +msgstr "Fri, 09 Nov 2001 01:08:47 -0000" + +#: ../../library/email.utils.rst:161 +msgid "" +"Optional *timeval* if given is a floating-point time value as accepted " +"by :func:`time.gmtime` and :func:`time.localtime`, otherwise the current " +"time is used." +msgstr "" + +#: ../../library/email.utils.rst:165 +msgid "" +"Optional *localtime* is a flag that when ``True``, interprets *timeval*, and " +"returns a date relative to the local timezone instead of UTC, properly " +"taking daylight savings time into account. The default is ``False`` meaning " +"UTC is used." +msgstr "" + +#: ../../library/email.utils.rst:170 +msgid "" +"Optional *usegmt* is a flag that when ``True``, outputs a date string with " +"the timezone as an ascii string ``GMT``, rather than a numeric ``-0000``. " +"This is needed for some protocols (such as HTTP). This only applies when " +"*localtime* is ``False``. The default is ``False``." +msgstr "" + +#: ../../library/email.utils.rst:178 +msgid "" +"Like ``formatdate``, but the input is a :mod:`datetime` instance. If it is " +"a naive datetime, it is assumed to be \"UTC with no information about the " +"source timezone\", and the conventional ``-0000`` is used for the timezone. " +"If it is an aware ``datetime``, then the numeric timezone offset is used. If " +"it is an aware timezone with offset zero, then *usegmt* may be set to " +"``True``, in which case the string ``GMT`` is used instead of the numeric " +"timezone offset. This provides a way to generate standards conformant HTTP " +"date headers." +msgstr "" + +#: ../../library/email.utils.rst:192 +msgid "Decode the string *s* according to :rfc:`2231`." +msgstr "" + +#: ../../library/email.utils.rst:197 +msgid "" +"Encode the string *s* according to :rfc:`2231`. Optional *charset* and " +"*language*, if given is the character set name and language name to use. If " +"neither is given, *s* is returned as-is. If *charset* is given but " +"*language* is not, the string is encoded using the empty string for " +"*language*." +msgstr "" + +#: ../../library/email.utils.rst:205 +msgid "" +"When a header parameter is encoded in :rfc:`2231` " +"format, :meth:`Message.get_param ` may " +"return a 3-tuple containing the character set, language, and " +"value. :func:`collapse_rfc2231_value` turns this into a unicode string. " +"Optional *errors* is passed to the *errors* argument " +"of :class:`str`'s :func:`~str.encode` method; it defaults to ``'replace'``. " +"Optional *fallback_charset* specifies the character set to use if the one in " +"the :rfc:`2231` header is not known by Python; it defaults to ``'us-ascii'``." +msgstr "" + +#: ../../library/email.utils.rst:214 +msgid "" +"For convenience, if the *value* passed to :func:`collapse_rfc2231_value` is " +"not a tuple, it should be a string and it is returned unquoted." +msgstr "" + +#: ../../library/email.utils.rst:220 +msgid "" +"Decode parameters list according to :rfc:`2231`. *params* is a sequence of " +"2-tuples containing elements of the form ``(content-type, string-value)``." +msgstr "" + +#: ../../library/email.utils.rst:225 +msgid "Footnotes" +msgstr "註解" + +#: ../../library/email.utils.rst:226 +msgid "" +"Note that the sign of the timezone offset is the opposite of the sign of the " +"``time.timezone`` variable for the same timezone; the latter variable " +"follows the POSIX standard while this module follows :rfc:`2822`." +msgstr "" diff --git a/library/ensurepip.po b/library/ensurepip.po index a1d344920b..ded2a1a80a 100644 --- a/library/ensurepip.po +++ b/library/ensurepip.po @@ -1,276 +1,276 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-18 00:15+0000\n" -"PO-Revision-Date: 2018-05-23 16:01+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/ensurepip.rst:2 -msgid ":mod:`!ensurepip` --- Bootstrapping the ``pip`` installer" -msgstr ":mod:`!ensurepip` --- ``pip`` 安裝器的初始建置 (bootstrapping)" - -#: ../../library/ensurepip.rst:10 -msgid "**Source code:** :source:`Lib/ensurepip`" -msgstr "**原始碼：**\\ :source:`Lib/ensurepip`" - -#: ../../library/ensurepip.rst:14 -msgid "" -"The :mod:`ensurepip` package provides support for bootstrapping the ``pip`` " -"installer into an existing Python installation or virtual environment. This " -"bootstrapping approach reflects the fact that ``pip`` is an independent " -"project with its own release cycle, and the latest available stable version " -"is bundled with maintenance and feature releases of the CPython reference " -"interpreter." -msgstr "" -":mod:`ensurepip` 套件 (package) 為既有的 Python 安裝或虛擬環境提供 ``pip`` 安" -"裝器初始建置 (bootstrapping) 的支援。這個初始建置的方式應證了事實 —— ``pip`` " -"是有其獨立發布週期的專案，且其最新可用穩定的版本，會與 CPython 直譯器 " -"(interpreter) 之維護和功能發布綁定。" - -#: ../../library/ensurepip.rst:21 -msgid "" -"In most cases, end users of Python shouldn't need to invoke this module " -"directly (as ``pip`` should be bootstrapped by default), but it may be " -"needed if installing ``pip`` was skipped when installing Python (or when " -"creating a virtual environment) or after explicitly uninstalling ``pip``." -msgstr "" -"大多數情況下，Python 的終端使用者不需要直接叫用此模組（因為 ``pip`` 預設應為" -"初始建置），但若安裝 Python 時 ``pip`` 被省略（或建立一虛擬環境時），又或是 " -"``pip`` 被明確解除安裝時，則此模組的初始建置仍有可能用上。" - -#: ../../library/ensurepip.rst:29 -msgid "" -"This module *does not* access the internet. All of the components needed to " -"bootstrap ``pip`` are included as internal parts of the package." -msgstr "" -"此模組\\ *不會*\\ 存取網路。所有需要用來初始建置 ``pip`` 的元件都已包含在" -"套件之內。" - -#: ../../includes/optional-module.rst:1 -msgid "" -"This is an :term:`optional module`. If it is missing from your copy of " -"CPython, look for documentation from your distributor (that is, whoever " -"provided Python to you). If you are the distributor, see :ref:`optional-" -"module-requirements`." -msgstr "" - -#: ../../library/ensurepip.rst:37 -msgid ":ref:`installing-index`" -msgstr ":ref:`installing-index`" - -#: ../../library/ensurepip.rst:38 -msgid "The end user guide for installing Python packages" -msgstr "對於終端使用者安裝 Python 套件的指引" - -#: ../../library/ensurepip.rst:40 -msgid ":pep:`453`: Explicit bootstrapping of pip in Python installations" -msgstr ":pep:`453`: 在 Python 安裝中的 pip 明確初始建置" - -#: ../../library/ensurepip.rst:41 -msgid "The original rationale and specification for this module." -msgstr "此模組的最初設計理念與規範。" - -#: ../../includes/wasm-mobile-notavail.rst:3 -msgid "Availability" -msgstr "可用性" - -#: ../../includes/wasm-mobile-notavail.rst:5 -msgid "" -"This module is not supported on :ref:`mobile platforms ` or :ref:`WebAssembly platforms `." -msgstr "" -"此模組在\\ :ref:`行動平台 `\\ 或 :ref:`WebAssembly 平" -"台 `\\ 上不支援。" - -#: ../../library/ensurepip.rst:48 -msgid "Command-line interface" -msgstr "命令列介面" - -#: ../../library/ensurepip.rst:52 -msgid "" -"The command line interface is invoked using the interpreter's ``-m`` switch." -msgstr "使用直譯器 (interpreter) 的 ``-m`` 來叫用命令列介面" - -#: ../../library/ensurepip.rst:54 -msgid "The simplest possible invocation is::" -msgstr "最簡單可行的呼叫： ::" - -#: ../../library/ensurepip.rst:56 -msgid "python -m ensurepip" -msgstr "python -m ensurepip" - -#: ../../library/ensurepip.rst:58 -msgid "" -"This invocation will install ``pip`` if it is not already installed, but " -"otherwise does nothing. To ensure the installed version of ``pip`` is at " -"least as recent as the one available in ``ensurepip``, pass the ``--" -"upgrade`` option::" -msgstr "" -"若 ``pip`` 未安裝，此呼叫會將其安裝；否則甚麼也不做。可透過傳入 ``--" -"upgrade`` 參數來確保 ``pip`` 的安裝版本至少為目前 ``ensurepip`` 中最新可用的" -"版本： ::" - -#: ../../library/ensurepip.rst:63 -msgid "python -m ensurepip --upgrade" -msgstr "python -m ensurepip --upgrade" - -#: ../../library/ensurepip.rst:65 -msgid "" -"By default, ``pip`` is installed into the current virtual environment (if " -"one is active) or into the system site packages (if there is no active " -"virtual environment). The installation location can be controlled through " -"two additional command line options:" -msgstr "" -"預設上，``pip`` 會被安裝至目前虛擬環境（若已啟動虛擬環境）或系統端的套件（若" -"沒有啟動的虛擬環境）。安裝位置可透過兩個額外的命令列選項來控制：" - -#: ../../library/ensurepip.rst:72 -msgid "" -"Installs ``pip`` relative to the given root directory rather than the root " -"of the currently active virtual environment (if any) or the default root for " -"the current Python installation." -msgstr "" -"安裝 ``pip`` 到給定的根目錄 (root directory) 的相對路徑，而不是目前虛擬環境" -"（若存在）的根目錄，或目前 Python 安裝版所預設的根目錄。" - -#: ../../library/ensurepip.rst:78 -msgid "" -"Installs ``pip`` into the user site packages directory rather than globally " -"for the current Python installation (this option is not permitted inside an " -"active virtual environment)." -msgstr "" -"安裝 ``pip`` 到使用者端的套件目錄，而不是全域安裝到目前的 Python 安裝版（此選" -"項不允許在一啟動的虛擬環境中使用）。" - -#: ../../library/ensurepip.rst:82 -msgid "" -"By default, the scripts ``pipX`` and ``pipX.Y`` will be installed (where X.Y " -"stands for the version of Python used to invoke ``ensurepip``). The scripts " -"installed can be controlled through two additional command line options:" -msgstr "" -"預設會安裝 ``pipX`` 和 ``pipX.Y`` 腳本（X.Y 代表用來叫用 ``ensurepip`` 的 " -"Python 之版本）。安裝的腳本可透過兩個額外的命令列選項來控制：" - -#: ../../library/ensurepip.rst:89 -msgid "" -"If an alternate installation is requested, the ``pipX`` script will *not* be " -"installed." -msgstr "若要求一個替代安裝版，則\\ *不會*\\ 安裝 ``pipX`` 腳本。" - -#: ../../library/ensurepip.rst:94 -msgid "" -"If a \"default pip\" installation is requested, the ``pip`` script will be " -"installed in addition to the two regular scripts." -msgstr "若要求安裝「預設 pip」，則會安裝 ``pip`` 腳本，及 2 個常規腳本。" - -#: ../../library/ensurepip.rst:97 -msgid "" -"Providing both of the script selection options will trigger an exception." -msgstr "提供兩種指令選項將會導致例外 (exception) 。" - -#: ../../library/ensurepip.rst:100 -msgid "Module API" -msgstr "模組 API" - -#: ../../library/ensurepip.rst:102 -msgid ":mod:`ensurepip` exposes two functions for programmatic use:" -msgstr ":mod:`ensurepip` 開放了兩個用於編寫程式的函式：" - -#: ../../library/ensurepip.rst:106 -msgid "" -"Returns a string specifying the available version of pip that will be " -"installed when bootstrapping an environment." -msgstr "回傳一個字串，用以標明初始建置時，安裝的 pip 的可行版本號。" - -#: ../../library/ensurepip.rst:113 -msgid "Bootstraps ``pip`` into the current or designated environment." -msgstr "在目前或指定的環境之中建立 ``pip``。" - -#: ../../library/ensurepip.rst:115 -msgid "" -"*root* specifies an alternative root directory to install relative to. If " -"*root* is ``None``, then installation uses the default install location for " -"the current environment." -msgstr "" -"*root* 指定一個替代的根目錄，作為安裝的相對路徑。若 *root* 為 ``None``，則安" -"裝使用目前環境的預設安裝位置。" - -#: ../../library/ensurepip.rst:119 -msgid "" -"*upgrade* indicates whether or not to upgrade an existing installation of an " -"earlier version of ``pip`` to the available version." -msgstr "*upgrade* 指出是否要將一個既有的較早版本的 ``pip`` 升級至可用的新版。" - -#: ../../library/ensurepip.rst:122 -msgid "" -"*user* indicates whether to use the user scheme rather than installing " -"globally." -msgstr "*user* 指出是否要使用使用者的安裝方案而不是全域安裝。" - -#: ../../library/ensurepip.rst:125 -msgid "" -"By default, the scripts ``pipX`` and ``pipX.Y`` will be installed (where X.Y " -"stands for the current version of Python)." -msgstr "預設會安裝 ``pipX`` 和 ``pipX.Y`` 腳本（X.Y 代表 Python 的目前版本）。" - -#: ../../library/ensurepip.rst:128 -msgid "If *altinstall* is set, then ``pipX`` will *not* be installed." -msgstr "如果啟用了 *altinstall*，則不會安裝 ``pipX``。" - -#: ../../library/ensurepip.rst:130 -msgid "" -"If *default_pip* is set, then ``pip`` will be installed in addition to the " -"two regular scripts." -msgstr "如果啟用了 *default_pip*，則會安裝 ``pip``，以及 2 個常規腳本。" - -#: ../../library/ensurepip.rst:133 -msgid "" -"Setting both *altinstall* and *default_pip* will trigger :exc:`ValueError`." -msgstr "同時啟用 *altinstall* 跟 *default_pip*，將會觸發 :exc:`ValueError`。" - -#: ../../library/ensurepip.rst:136 -msgid "" -"*verbosity* controls the level of output to :data:`sys.stdout` from the " -"bootstrapping operation." -msgstr "" -"*verbosity* 用來控制初始建置操作內，對於 :data:`sys.stdout` 的輸出等級。" - -#: ../../library/ensurepip.rst:139 -msgid "" -"Raises an :ref:`auditing event ` ``ensurepip.bootstrap`` with " -"argument ``root``." -msgstr "" -"引發一個附帶引數 ``root`` 的\\ :ref:`稽核事件 ` ``ensurepip." -"bootstrap``。" - -#: ../../library/ensurepip.rst:143 -msgid "" -"The bootstrapping process has side effects on both ``sys.path`` and ``os." -"environ``. Invoking the command line interface in a subprocess instead " -"allows these side effects to be avoided." -msgstr "" -"初始建置的過程對於 ``sys.path`` 及 ``os.environ`` 均有副作用。改為在一子行程 " -"(subprocess) 呼叫命令列介面可避免這些副作用。" - -#: ../../library/ensurepip.rst:149 -msgid "" -"The bootstrapping process may install additional modules required by " -"``pip``, but other software should not assume those dependencies will always " -"be present by default (as the dependencies may be removed in a future " -"version of ``pip``)." -msgstr "" -"初始建置的過程也許會安裝 ``pip`` 所需要的額外的模組，但其他軟體不應該假設這些" -"相依 (dependency) 總是預設存在（因為這些相依很可能會在未來版本的 ``pip`` 中被" -"移除）。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-18 00:15+0000\n" +"PO-Revision-Date: 2018-05-23 16:01+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/ensurepip.rst:2 +msgid ":mod:`!ensurepip` --- Bootstrapping the ``pip`` installer" +msgstr ":mod:`!ensurepip` --- ``pip`` 安裝器的初始建置 (bootstrapping)" + +#: ../../library/ensurepip.rst:10 +msgid "**Source code:** :source:`Lib/ensurepip`" +msgstr "**原始碼：**\\ :source:`Lib/ensurepip`" + +#: ../../library/ensurepip.rst:14 +msgid "" +"The :mod:`ensurepip` package provides support for bootstrapping the ``pip`` " +"installer into an existing Python installation or virtual environment. This " +"bootstrapping approach reflects the fact that ``pip`` is an independent " +"project with its own release cycle, and the latest available stable version " +"is bundled with maintenance and feature releases of the CPython reference " +"interpreter." +msgstr "" +":mod:`ensurepip` 套件 (package) 為既有的 Python 安裝或虛擬環境提供 ``pip`` 安" +"裝器初始建置 (bootstrapping) 的支援。這個初始建置的方式應證了事實 —— ``pip`` " +"是有其獨立發布週期的專案，且其最新可用穩定的版本，會與 CPython 直譯器 " +"(interpreter) 之維護和功能發布綁定。" + +#: ../../library/ensurepip.rst:21 +msgid "" +"In most cases, end users of Python shouldn't need to invoke this module " +"directly (as ``pip`` should be bootstrapped by default), but it may be " +"needed if installing ``pip`` was skipped when installing Python (or when " +"creating a virtual environment) or after explicitly uninstalling ``pip``." +msgstr "" +"大多數情況下，Python 的終端使用者不需要直接叫用此模組（因為 ``pip`` 預設應為" +"初始建置），但若安裝 Python 時 ``pip`` 被省略（或建立一虛擬環境時），又或是 " +"``pip`` 被明確解除安裝時，則此模組的初始建置仍有可能用上。" + +#: ../../library/ensurepip.rst:29 +msgid "" +"This module *does not* access the internet. All of the components needed to " +"bootstrap ``pip`` are included as internal parts of the package." +msgstr "" +"此模組\\ *不會*\\ 存取網路。所有需要用來初始建置 ``pip`` 的元件都已包含在" +"套件之內。" + +#: ../../includes/optional-module.rst:1 +msgid "" +"This is an :term:`optional module`. If it is missing from your copy of " +"CPython, look for documentation from your distributor (that is, whoever " +"provided Python to you). If you are the distributor, see :ref:`optional-" +"module-requirements`." +msgstr "" + +#: ../../library/ensurepip.rst:37 +msgid ":ref:`installing-index`" +msgstr ":ref:`installing-index`" + +#: ../../library/ensurepip.rst:38 +msgid "The end user guide for installing Python packages" +msgstr "對於終端使用者安裝 Python 套件的指引" + +#: ../../library/ensurepip.rst:40 +msgid ":pep:`453`: Explicit bootstrapping of pip in Python installations" +msgstr ":pep:`453`: 在 Python 安裝中的 pip 明確初始建置" + +#: ../../library/ensurepip.rst:41 +msgid "The original rationale and specification for this module." +msgstr "此模組的最初設計理念與規範。" + +#: ../../includes/wasm-mobile-notavail.rst:3 +msgid "Availability" +msgstr "可用性" + +#: ../../includes/wasm-mobile-notavail.rst:5 +msgid "" +"This module is not supported on :ref:`mobile platforms ` or :ref:`WebAssembly platforms `." +msgstr "" +"此模組在\\ :ref:`行動平台 `\\ 或 :ref:`WebAssembly 平" +"台 `\\ 上不支援。" + +#: ../../library/ensurepip.rst:48 +msgid "Command-line interface" +msgstr "命令列介面" + +#: ../../library/ensurepip.rst:52 +msgid "" +"The command line interface is invoked using the interpreter's ``-m`` switch." +msgstr "使用直譯器 (interpreter) 的 ``-m`` 來叫用命令列介面" + +#: ../../library/ensurepip.rst:54 +msgid "The simplest possible invocation is::" +msgstr "最簡單可行的呼叫： ::" + +#: ../../library/ensurepip.rst:56 +msgid "python -m ensurepip" +msgstr "python -m ensurepip" + +#: ../../library/ensurepip.rst:58 +msgid "" +"This invocation will install ``pip`` if it is not already installed, but " +"otherwise does nothing. To ensure the installed version of ``pip`` is at " +"least as recent as the one available in ``ensurepip``, pass the ``--" +"upgrade`` option::" +msgstr "" +"若 ``pip`` 未安裝，此呼叫會將其安裝；否則甚麼也不做。可透過傳入 ``--" +"upgrade`` 參數來確保 ``pip`` 的安裝版本至少為目前 ``ensurepip`` 中最新可用的" +"版本： ::" + +#: ../../library/ensurepip.rst:63 +msgid "python -m ensurepip --upgrade" +msgstr "python -m ensurepip --upgrade" + +#: ../../library/ensurepip.rst:65 +msgid "" +"By default, ``pip`` is installed into the current virtual environment (if " +"one is active) or into the system site packages (if there is no active " +"virtual environment). The installation location can be controlled through " +"two additional command line options:" +msgstr "" +"預設上，``pip`` 會被安裝至目前虛擬環境（若已啟動虛擬環境）或系統端的套件（若" +"沒有啟動的虛擬環境）。安裝位置可透過兩個額外的命令列選項來控制：" + +#: ../../library/ensurepip.rst:72 +msgid "" +"Installs ``pip`` relative to the given root directory rather than the root " +"of the currently active virtual environment (if any) or the default root for " +"the current Python installation." +msgstr "" +"安裝 ``pip`` 到給定的根目錄 (root directory) 的相對路徑，而不是目前虛擬環境" +"（若存在）的根目錄，或目前 Python 安裝版所預設的根目錄。" + +#: ../../library/ensurepip.rst:78 +msgid "" +"Installs ``pip`` into the user site packages directory rather than globally " +"for the current Python installation (this option is not permitted inside an " +"active virtual environment)." +msgstr "" +"安裝 ``pip`` 到使用者端的套件目錄，而不是全域安裝到目前的 Python 安裝版（此選" +"項不允許在一啟動的虛擬環境中使用）。" + +#: ../../library/ensurepip.rst:82 +msgid "" +"By default, the scripts ``pipX`` and ``pipX.Y`` will be installed (where X.Y " +"stands for the version of Python used to invoke ``ensurepip``). The scripts " +"installed can be controlled through two additional command line options:" +msgstr "" +"預設會安裝 ``pipX`` 和 ``pipX.Y`` 腳本（X.Y 代表用來叫用 ``ensurepip`` 的 " +"Python 之版本）。安裝的腳本可透過兩個額外的命令列選項來控制：" + +#: ../../library/ensurepip.rst:89 +msgid "" +"If an alternate installation is requested, the ``pipX`` script will *not* be " +"installed." +msgstr "若要求一個替代安裝版，則\\ *不會*\\ 安裝 ``pipX`` 腳本。" + +#: ../../library/ensurepip.rst:94 +msgid "" +"If a \"default pip\" installation is requested, the ``pip`` script will be " +"installed in addition to the two regular scripts." +msgstr "若要求安裝「預設 pip」，則會安裝 ``pip`` 腳本，及 2 個常規腳本。" + +#: ../../library/ensurepip.rst:97 +msgid "" +"Providing both of the script selection options will trigger an exception." +msgstr "提供兩種指令選項將會導致例外 (exception) 。" + +#: ../../library/ensurepip.rst:100 +msgid "Module API" +msgstr "模組 API" + +#: ../../library/ensurepip.rst:102 +msgid ":mod:`ensurepip` exposes two functions for programmatic use:" +msgstr ":mod:`ensurepip` 開放了兩個用於編寫程式的函式：" + +#: ../../library/ensurepip.rst:106 +msgid "" +"Returns a string specifying the available version of pip that will be " +"installed when bootstrapping an environment." +msgstr "回傳一個字串，用以標明初始建置時，安裝的 pip 的可行版本號。" + +#: ../../library/ensurepip.rst:113 +msgid "Bootstraps ``pip`` into the current or designated environment." +msgstr "在目前或指定的環境之中建立 ``pip``。" + +#: ../../library/ensurepip.rst:115 +msgid "" +"*root* specifies an alternative root directory to install relative to. If " +"*root* is ``None``, then installation uses the default install location for " +"the current environment." +msgstr "" +"*root* 指定一個替代的根目錄，作為安裝的相對路徑。若 *root* 為 ``None``，則安" +"裝使用目前環境的預設安裝位置。" + +#: ../../library/ensurepip.rst:119 +msgid "" +"*upgrade* indicates whether or not to upgrade an existing installation of an " +"earlier version of ``pip`` to the available version." +msgstr "*upgrade* 指出是否要將一個既有的較早版本的 ``pip`` 升級至可用的新版。" + +#: ../../library/ensurepip.rst:122 +msgid "" +"*user* indicates whether to use the user scheme rather than installing " +"globally." +msgstr "*user* 指出是否要使用使用者的安裝方案而不是全域安裝。" + +#: ../../library/ensurepip.rst:125 +msgid "" +"By default, the scripts ``pipX`` and ``pipX.Y`` will be installed (where X.Y " +"stands for the current version of Python)." +msgstr "預設會安裝 ``pipX`` 和 ``pipX.Y`` 腳本（X.Y 代表 Python 的目前版本）。" + +#: ../../library/ensurepip.rst:128 +msgid "If *altinstall* is set, then ``pipX`` will *not* be installed." +msgstr "如果啟用了 *altinstall*，則不會安裝 ``pipX``。" + +#: ../../library/ensurepip.rst:130 +msgid "" +"If *default_pip* is set, then ``pip`` will be installed in addition to the " +"two regular scripts." +msgstr "如果啟用了 *default_pip*，則會安裝 ``pip``，以及 2 個常規腳本。" + +#: ../../library/ensurepip.rst:133 +msgid "" +"Setting both *altinstall* and *default_pip* will trigger :exc:`ValueError`." +msgstr "同時啟用 *altinstall* 跟 *default_pip*，將會觸發 :exc:`ValueError`。" + +#: ../../library/ensurepip.rst:136 +msgid "" +"*verbosity* controls the level of output to :data:`sys.stdout` from the " +"bootstrapping operation." +msgstr "" +"*verbosity* 用來控制初始建置操作內，對於 :data:`sys.stdout` 的輸出等級。" + +#: ../../library/ensurepip.rst:139 +msgid "" +"Raises an :ref:`auditing event ` ``ensurepip.bootstrap`` with " +"argument ``root``." +msgstr "" +"引發一個附帶引數 ``root`` 的\\ :ref:`稽核事件 ` ``ensurepip." +"bootstrap``。" + +#: ../../library/ensurepip.rst:143 +msgid "" +"The bootstrapping process has side effects on both ``sys.path`` and ``os." +"environ``. Invoking the command line interface in a subprocess instead " +"allows these side effects to be avoided." +msgstr "" +"初始建置的過程對於 ``sys.path`` 及 ``os.environ`` 均有副作用。改為在一子行程 " +"(subprocess) 呼叫命令列介面可避免這些副作用。" + +#: ../../library/ensurepip.rst:149 +msgid "" +"The bootstrapping process may install additional modules required by " +"``pip``, but other software should not assume those dependencies will always " +"be present by default (as the dependencies may be removed in a future " +"version of ``pip``)." +msgstr "" +"初始建置的過程也許會安裝 ``pip`` 所需要的額外的模組，但其他軟體不應該假設這些" +"相依 (dependency) 總是預設存在（因為這些相依很可能會在未來版本的 ``pip`` 中被" +"移除）。" diff --git a/library/enum.po b/library/enum.po index 7445c2760e..4214da220b 100644 --- a/library/enum.po +++ b/library/enum.po @@ -1,1898 +1,1898 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-12-19 00:15+0000\n" -"PO-Revision-Date: 2024-12-21 13:50+0800\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/enum.rst:2 -msgid ":mod:`!enum` --- Support for enumerations" -msgstr ":mod:`!enum` --- 對列舉的支援" - -#: ../../library/enum.rst:14 -msgid "**Source code:** :source:`Lib/enum.py`" -msgstr "**原始碼：**\\ :source:`Lib/enum.py`" - -#: ../../library/enum.rst:16 -msgid "Important" -msgstr "重點資訊" - -#: ../../library/enum.rst:18 -msgid "" -"This page contains the API reference information. For tutorial information " -"and discussion of more advanced topics, see" -msgstr "本頁包含 API 的參考資訊。關於教學資訊及更多進階主題的討論請參考" - -#: ../../library/enum.rst:21 -msgid ":ref:`Basic Tutorial `" -msgstr ":ref:`基本教學 `" - -#: ../../library/enum.rst:22 -msgid ":ref:`Advanced Tutorial `" -msgstr ":ref:`進階教學 `" - -#: ../../library/enum.rst:23 -msgid ":ref:`Enum Cookbook `" -msgstr ":ref:`列舉指南 `" - -#: ../../library/enum.rst:27 -msgid "An enumeration:" -msgstr "列舉：" - -#: ../../library/enum.rst:29 -msgid "is a set of symbolic names (members) bound to unique values" -msgstr "是一組綁定唯一值的代表名稱（成員）" - -#: ../../library/enum.rst:30 -msgid "" -"can be iterated over to return its canonical (i.e. non-alias) members in " -"definition order" -msgstr "可以用疊代的方式以定義的順序回傳其正式 (canonical)（即非別名）成員" - -#: ../../library/enum.rst:32 -msgid "uses *call* syntax to return members by value" -msgstr "使用 *call* 語法來透過值回傳成員" - -#: ../../library/enum.rst:33 -msgid "uses *index* syntax to return members by name" -msgstr "使用 *index* 語法來透過名稱回傳成員" - -#: ../../library/enum.rst:35 -msgid "" -"Enumerations are created either by using :keyword:`class` syntax, or by " -"using function-call syntax::" -msgstr "列舉透過 :keyword:`class` 語法或函式呼叫的語法來建立： ::" - -#: ../../library/enum.rst:38 -msgid "" -">>> from enum import Enum\n" -"\n" -">>> # class syntax\n" -">>> class Color(Enum):\n" -"... RED = 1\n" -"... GREEN = 2\n" -"... BLUE = 3\n" -"\n" -">>> # functional syntax\n" -">>> Color = Enum('Color', [('RED', 1), ('GREEN', 2), ('BLUE', 3)])" -msgstr "" -">>> from enum import Enum\n" -"\n" -">>> # class 語法\n" -">>> class Color(Enum):\n" -"... RED = 1\n" -"... GREEN = 2\n" -"... BLUE = 3\n" -"\n" -">>> # 函式語法\n" -">>> Color = Enum('Color', [('RED', 1), ('GREEN', 2), ('BLUE', 3)])" - -#: ../../library/enum.rst:49 -msgid "" -"Even though we can use :keyword:`class` syntax to create Enums, Enums are " -"not normal Python classes. See :ref:`How are Enums different? ` for more details." -msgstr "" -"雖然我們可以用 :keyword:`class` 語法來建立列舉，列舉並不是標準的 Python 類" -"別。參考\\ :ref:`列舉有何差異 `\\ 以取得更多細節。" - -#: ../../library/enum.rst:53 -msgid "Nomenclature" -msgstr "命名方式" - -#: ../../library/enum.rst:55 -msgid "The class :class:`!Color` is an *enumeration* (or *enum*)" -msgstr ":class:`!Color` 類別是一個\\ *列舉*\\ （或 *enum*）" - -#: ../../library/enum.rst:56 -msgid "" -"The attributes :attr:`!Color.RED`, :attr:`!Color.GREEN`, etc., are " -"*enumeration members* (or *members*) and are functionally constants." -msgstr "" -":attr:`!Color.RED`、:attr:`!Color.GREEN` 等屬性是\\ *列舉成員*\\ （或\\ *成員" -"*），並且使用上可以看作常數。" - -#: ../../library/enum.rst:58 -msgid "" -"The enum members have *names* and *values* (the name of :attr:`!Color.RED` " -"is ``RED``, the value of :attr:`!Color.BLUE` is ``3``, etc.)" -msgstr "" -"列舉成員有\\ *名稱*\\ 和\\ *值*\\ （:attr:`!Color.RED` 的名稱是 ``RED``，:" -"attr:`!Color.BLUE` 的值是 ``3`` 諸如此類）" - -#: ../../library/enum.rst:65 -msgid "Module Contents" -msgstr "模組內容" - -#: ../../library/enum.rst:67 -msgid ":class:`EnumType`" -msgstr ":class:`EnumType`" - -#: ../../library/enum.rst:69 -msgid "The ``type`` for Enum and its subclasses." -msgstr "Enum 及其子類別的 ``type``。" - -#: ../../library/enum.rst:71 -msgid ":class:`Enum`" -msgstr ":class:`Enum`" - -#: ../../library/enum.rst:73 -msgid "Base class for creating enumerated constants." -msgstr "用來建立列舉常數的基礎類別。" - -#: ../../library/enum.rst:75 -msgid ":class:`IntEnum`" -msgstr ":class:`IntEnum`" - -#: ../../library/enum.rst:77 -msgid "" -"Base class for creating enumerated constants that are also subclasses of :" -"class:`int`. (`Notes`_)" -msgstr "" -"用來建立列舉常數的基礎類別，同時也是 :class:`int` 的子類別。（`備註 " -"`_）" - -#: ../../library/enum.rst:80 -msgid ":class:`StrEnum`" -msgstr ":class:`StrEnum`" - -#: ../../library/enum.rst:82 -msgid "" -"Base class for creating enumerated constants that are also subclasses of :" -"class:`str`. (`Notes`_)" -msgstr "" -"用來建立列舉常數的基礎類別，同時也是 :class:`str` 的子類別。（`備註 " -"`_）" - -#: ../../library/enum.rst:85 -msgid ":class:`Flag`" -msgstr ":class:`Flag`" - -#: ../../library/enum.rst:87 -msgid "" -"Base class for creating enumerated constants that can be combined using the " -"bitwise operations without losing their :class:`Flag` membership." -msgstr "" -"用來建立列舉常數的基礎類別，可以使用位元操作來結合成員且其結果不失去 :class:" -"`Flag` 的成員資格。" - -#: ../../library/enum.rst:90 -msgid ":class:`IntFlag`" -msgstr ":class:`IntFlag`" - -#: ../../library/enum.rst:92 -msgid "" -"Base class for creating enumerated constants that can be combined using the " -"bitwise operators without losing their :class:`IntFlag` membership. :class:" -"`IntFlag` members are also subclasses of :class:`int`. (`Notes`_)" -msgstr "" -"用來建立列舉常數的基礎類別，可以使用位元操作來結合成員且其結果不失去 :class:" -"`IntFlag` 的成員資格。:class:`IntFlag` 的成員也是 :class:`int` 的子類別。（`" -"備註 `_）" - -#: ../../library/enum.rst:96 -msgid ":class:`ReprEnum`" -msgstr ":class:`ReprEnum`" - -#: ../../library/enum.rst:98 -msgid "" -"Used by :class:`IntEnum`, :class:`StrEnum`, and :class:`IntFlag` to keep " -"the :class:`str() ` of the mixed-in type." -msgstr "" -"由 :class:`IntEnum`、:class:`StrEnum` 及 :class:`IntFlag` 所使用來保留這些混" -"合型別的 :class:`str() `。" - -#: ../../library/enum.rst:101 -msgid ":class:`EnumCheck`" -msgstr ":class:`EnumCheck`" - -#: ../../library/enum.rst:103 -msgid "" -"An enumeration with the values ``CONTINUOUS``, ``NAMED_FLAGS``, and " -"``UNIQUE``, for use with :func:`verify` to ensure various constraints are " -"met by a given enumeration." -msgstr "" -"一個有 ``CONTINUOUS``、``NAMED_FLAGS`` 及 ``UNIQUE`` 這些值的列舉，和 :func:" -"`verify` 一起使用來確保給定的列舉符合多種限制。" - -#: ../../library/enum.rst:107 -msgid ":class:`FlagBoundary`" -msgstr ":class:`FlagBoundary`" - -#: ../../library/enum.rst:109 -msgid "" -"An enumeration with the values ``STRICT``, ``CONFORM``, ``EJECT``, and " -"``KEEP`` which allows for more fine-grained control over how invalid values " -"are dealt with in an enumeration." -msgstr "" -"一個有 ``STRICT``、``CONFORM``、``EJECT`` 及 ``KEEP`` 這些值的列舉，允許列舉" -"對如何處理非法值做更細微的控制。" - -#: ../../library/enum.rst:113 -msgid ":class:`EnumDict`" -msgstr ":class:`EnumDict`" - -#: ../../library/enum.rst:115 -msgid "A subclass of :class:`dict` for use when subclassing :class:`EnumType`." -msgstr ":class:`dict` 的子類別，用於當作 :class:`EnumType` 的子類別時使用。" - -#: ../../library/enum.rst:117 -msgid ":class:`auto`" -msgstr ":class:`auto`" - -#: ../../library/enum.rst:119 -msgid "" -"Instances are replaced with an appropriate value for Enum members. :class:" -"`StrEnum` defaults to the lower-cased version of the member name, while " -"other Enums default to 1 and increase from there." -msgstr "" -"列舉成員的實例會被取代成合適的值。:class:`StrEnum` 預設是小寫版本的成員名稱，" -"其它列舉則預設是 1 且往後遞增。" - -#: ../../library/enum.rst:123 -msgid ":func:`~enum.property`" -msgstr ":func:`~enum.property`" - -#: ../../library/enum.rst:125 -msgid "" -"Allows :class:`Enum` members to have attributes without conflicting with " -"member names. The ``value`` and ``name`` attributes are implemented this " -"way." -msgstr "" -"允許 :class:`Enum` 成員擁有屬性且不會與成員名稱有衝突。``value`` 及 ``name`` " -"屬性是用這個方式來實作。" - -#: ../../library/enum.rst:129 -msgid ":func:`unique`" -msgstr ":func:`unique`" - -#: ../../library/enum.rst:131 -msgid "" -"Enum class decorator that ensures only one name is bound to any one value." -msgstr "Enum 類別的裝飾器，用來確保任何值只有綁定到一個名稱上。" - -#: ../../library/enum.rst:133 -msgid ":func:`verify`" -msgstr ":func:`verify`" - -#: ../../library/enum.rst:135 -msgid "" -"Enum class decorator that checks user-selectable constraints on an " -"enumeration." -msgstr "Enum 類別的裝飾器，用來檢查列舉上使用者所選的限制。" - -#: ../../library/enum.rst:138 -msgid ":func:`member`" -msgstr ":func:`member`" - -#: ../../library/enum.rst:140 -msgid "Make ``obj`` a member. Can be used as a decorator." -msgstr "讓 ``obj`` 變成成員。可以當作裝飾器使用。" - -#: ../../library/enum.rst:142 -msgid ":func:`nonmember`" -msgstr ":func:`nonmember`" - -#: ../../library/enum.rst:144 -msgid "Do not make ``obj`` a member. Can be used as a decorator." -msgstr "不讓 ``obj`` 變成成員。可以當作裝飾器使用。" - -#: ../../library/enum.rst:146 -msgid ":func:`global_enum`" -msgstr ":func:`global_enum`" - -#: ../../library/enum.rst:148 -msgid "" -"Modify the :class:`str() ` and :func:`repr` of an enum to show its " -"members as belonging to the module instead of its class, and export the enum " -"members to the global namespace." -msgstr "" -"修改列舉上的 :class:`str() ` 及 :func:`repr` ，讓成員顯示為屬於模組而不" -"是類別，並將該列舉成員匯出到全域命名空間。" - -#: ../../library/enum.rst:152 -msgid ":func:`show_flag_values`" -msgstr ":func:`show_flag_values`" - -#: ../../library/enum.rst:154 -msgid "Return a list of all power-of-two integers contained in a flag." -msgstr "回傳旗標 (flag) 裡包含的所有 2 的次方的整數串列。" - -#: ../../library/enum.rst:157 -msgid "``Flag``, ``IntFlag``, ``auto``" -msgstr "``Flag``, ``IntFlag``, ``auto``" - -#: ../../library/enum.rst:158 -msgid "" -"``StrEnum``, ``EnumCheck``, ``ReprEnum``, ``FlagBoundary``, ``property``, " -"``member``, ``nonmember``, ``global_enum``, ``show_flag_values``" -msgstr "" -"``StrEnum``, ``EnumCheck``, ``ReprEnum``, ``FlagBoundary``, ``property``, " -"``member``, ``nonmember``, ``global_enum``, ``show_flag_values``" - -#: ../../library/enum.rst:159 -msgid "``EnumDict``" -msgstr "``EnumDict``" - -#: ../../library/enum.rst:164 -msgid "Data Types" -msgstr "資料型別" - -#: ../../library/enum.rst:169 -msgid "" -"*EnumType* is the :term:`metaclass` for *enum* enumerations. It is possible " -"to subclass *EnumType* -- see :ref:`Subclassing EnumType ` for details." -msgstr "" -"*EnumType* 是 *enum* 列舉的 :term:`metaclass`。*EnumType* 可以有子類別 -- 細" -"節請參考 :ref:`建立 EnumType 的子類別 `。" - -#: ../../library/enum.rst:173 -msgid "" -"``EnumType`` is responsible for setting the correct :meth:`!__repr__`, :meth:" -"`!__str__`, :meth:`!__format__`, and :meth:`!__reduce__` methods on the " -"final *enum*, as well as creating the enum members, properly handling " -"duplicates, providing iteration over the enum class, etc." -msgstr "" -"``EnumType`` 負責在最後的\\ *列舉*\\ 上面設定正確的 :meth:`!__repr__`、:meth:" -"`!__str__`、:meth:`!__format__` 及 :meth:`!__reduce__` 方法，以及建立列舉成" -"員、正確處理重複、提供列舉類別的疊代等等。" - -#: ../../library/enum.rst:180 -msgid "" -"Before 3.11 ``EnumType`` was called ``EnumMeta``, which is still available " -"as an alias." -msgstr "在 3.11 之前，``EnumType`` 稱作 ``EnumMeta``，其目前仍可作為別名使用。" - -#: ../../library/enum.rst:184 -msgid "This method is called in two different ways:" -msgstr "這個方法可以用兩種不同的方式呼叫：" - -#: ../../library/enum.rst:186 -msgid "to look up an existing member:" -msgstr "查詢已存在的成員：" - -#: ../../library/enum.rst:0 -msgid "cls" -msgstr "cls" - -#: ../../library/enum.rst:188 ../../library/enum.rst:194 -msgid "The enum class being called." -msgstr "所呼叫的列舉類別。" - -#: ../../library/enum.rst:0 -msgid "value" -msgstr "value" - -#: ../../library/enum.rst:189 -msgid "The value to lookup." -msgstr "要查詢的值。" - -#: ../../library/enum.rst:191 -msgid "" -"to use the ``cls`` enum to create a new enum (only if the existing enum does " -"not have any members):" -msgstr "使用 ``cls`` 列舉來建立新列舉（只有在現有列舉沒有任何成員時）" - -#: ../../library/enum.rst:195 -msgid "The name of the new Enum to create." -msgstr "要建立的新列舉的名稱。" - -#: ../../library/enum.rst:0 -msgid "names" -msgstr "names" - -#: ../../library/enum.rst:196 -msgid "The names/values of the members for the new Enum." -msgstr "新列舉的成員的名稱/值。" - -#: ../../library/enum.rst:0 -msgid "module" -msgstr "module" - -#: ../../library/enum.rst:197 -msgid "The name of the module the new Enum is created in." -msgstr "新列舉要建立在哪個模組名稱下。" - -#: ../../library/enum.rst:0 -msgid "qualname" -msgstr "qualname" - -#: ../../library/enum.rst:198 -msgid "The actual location in the module where this Enum can be found." -msgstr "這個列舉在模組裡實際上的位置。" - -#: ../../library/enum.rst:0 -msgid "type" -msgstr "type" - -#: ../../library/enum.rst:199 -msgid "A mix-in type for the new Enum." -msgstr "新列舉的混合型別。" - -#: ../../library/enum.rst:0 -msgid "start" -msgstr "start" - -#: ../../library/enum.rst:200 -msgid "The first integer value for the Enum (used by :class:`auto`)." -msgstr "列舉的第一個整數值（由 :class:`auto` 所使用）" - -#: ../../library/enum.rst:0 -msgid "boundary" -msgstr "boundary" - -#: ../../library/enum.rst:201 -msgid "" -"How to handle out-of-range values from bit operations (:class:`Flag` only)." -msgstr "在位元操作時怎麼處理範圍外的值（只有 :class:`Flag` 會用到）" - -#: ../../library/enum.rst:205 -msgid "Returns ``True`` if member belongs to the ``cls``::" -msgstr "如果 member 屬於 ``cls`` 則回傳 ``True``： ::" - -#: ../../library/enum.rst:207 -msgid "" -">>> some_var = Color.RED\n" -">>> some_var in Color\n" -"True\n" -">>> Color.RED.value in Color\n" -"True" -msgstr "" -">>> some_var = Color.RED\n" -">>> some_var in Color\n" -"True\n" -">>> Color.RED.value in Color\n" -"True" - -#: ../../library/enum.rst:215 -msgid "" -"Before Python 3.12, a ``TypeError`` is raised if a non-Enum-member is used " -"in a containment check." -msgstr "" -"在 Python 3.12 之前，如果用非列舉成員做屬於檢查 (containment check) 會引發 " -"``TypeError``。" - -#: ../../library/enum.rst:220 -msgid "" -"Returns ``['__class__', '__doc__', '__members__', '__module__']`` and the " -"names of the members in *cls*::" -msgstr "" -"回傳 ``['__class__', '__doc__', '__members__', '__module__']`` 及 *cls* 的成" -"員名稱： ::" - -#: ../../library/enum.rst:223 -msgid "" -">>> dir(Color)\n" -"['BLUE', 'GREEN', 'RED', '__class__', '__contains__', '__doc__', " -"'__getitem__', '__init_subclass__', '__iter__', '__len__', '__members__', " -"'__module__', '__name__', '__qualname__']" -msgstr "" -">>> dir(Color)\n" -"['BLUE', 'GREEN', 'RED', '__class__', '__contains__', '__doc__', " -"'__getitem__', '__init_subclass__', '__iter__', '__len__', '__members__', " -"'__module__', '__name__', '__qualname__']" - -#: ../../library/enum.rst:228 -msgid "" -"Returns the Enum member in *cls* matching *name*, or raises a :exc:" -"`KeyError`::" -msgstr "回傳 *cls* 中符合 *name* 的列舉成員，或引發 :exc:`KeyError`： ::" - -#: ../../library/enum.rst:230 -msgid "" -">>> Color['BLUE']\n" -"" -msgstr "" -">>> Color['BLUE']\n" -"" - -#: ../../library/enum.rst:235 -msgid "Returns each member in *cls* in definition order::" -msgstr "以定義的順序回傳在 *cls* 中的每個成員： ::" - -#: ../../library/enum.rst:237 -msgid "" -">>> list(Color)\n" -"[, , ]" -msgstr "" -">>> list(Color)\n" -"[, , ]" - -#: ../../library/enum.rst:242 -msgid "Returns the number of member in *cls*::" -msgstr "回傳 *cls* 的成員數量： ::" - -#: ../../library/enum.rst:244 -msgid "" -">>> len(Color)\n" -"3" -msgstr "" -">>> len(Color)\n" -"3" - -#: ../../library/enum.rst:249 -msgid "Returns a mapping of every enum name to its member, including aliases" -msgstr "回傳每個列舉名稱到其成員的對映，包括別名" - -#: ../../library/enum.rst:253 -msgid "Returns each member in *cls* in reverse definition order::" -msgstr "以跟定義相反的順序回傳 *cls* 的每個成員： ::" - -#: ../../library/enum.rst:255 -msgid "" -">>> list(reversed(Color))\n" -"[, , ]" -msgstr "" -">>> list(reversed(Color))\n" -"[, , ]" - -#: ../../library/enum.rst:261 -msgid "*Enum* is the base class for all *enum* enumerations." -msgstr "*Enum* 是所有 *enum* 列舉的基礎類別。" - -#: ../../library/enum.rst:265 -msgid "The name used to define the ``Enum`` member::" -msgstr "用來定義 ``Enum`` 成員的名稱： ::" - -#: ../../library/enum.rst:267 -msgid "" -">>> Color.BLUE.name\n" -"'BLUE'" -msgstr "" -">>> Color.BLUE.name\n" -"'BLUE'" - -#: ../../library/enum.rst:272 -msgid "The value given to the ``Enum`` member::" -msgstr "``Enum`` 成員給定的值： ::" - -#: ../../library/enum.rst:274 -msgid "" -">>> Color.RED.value\n" -"1" -msgstr "" -">>> Color.RED.value\n" -"1" - -#: ../../library/enum.rst:277 ../../library/enum.rst:297 -msgid "Value of the member, can be set in :meth:`~Enum.__new__`." -msgstr "成員的值，可以在 :meth:`~Enum.__new__` 設定。" - -#: ../../library/enum.rst:279 -msgid "Enum member values" -msgstr "列舉成員的值" - -#: ../../library/enum.rst:281 -msgid "" -"Member values can be anything: :class:`int`, :class:`str`, etc. If the " -"exact value is unimportant you may use :class:`auto` instances and an " -"appropriate value will be chosen for you. See :class:`auto` for the details." -msgstr "" -"成員的值可以是任何值：:class:`int`、:class:`str` 等等。如果實際使用什麼值並不" -"重要，你可以使用 :class:`auto` 實例，它會為你選擇合適的值。更多細節請參考 :" -"class:`auto`。" - -#: ../../library/enum.rst:286 -msgid "" -"While mutable/unhashable values, such as :class:`dict`, :class:`list` or a " -"mutable :class:`~dataclasses.dataclass`, can be used, they will have a " -"quadratic performance impact during creation relative to the total number of " -"mutable/unhashable values in the enum." -msgstr "" -"雖然可以使用可變的 (mutable) / 不可雜湊的 (unhashable) 值，例如 :class:" -"`dict`、:class:`list` 或可變的 :class:`~dataclasses.dataclass`，它們在建立期" -"間會對效能產生相對於列舉中可變的 / 不可雜湊的值總數量的二次方影響。" - -#: ../../library/enum.rst:293 -msgid "Name of the member." -msgstr "成員名稱。" - -#: ../../library/enum.rst:301 -msgid "" -"No longer used, kept for backward compatibility. (class attribute, removed " -"during class creation)." -msgstr "已不再使用，只為了向後相容而保留（類別屬性，在類別建立時移除）" - -#: ../../library/enum.rst:306 -msgid "" -"``_ignore_`` is only used during creation and is removed from the " -"enumeration once creation is complete." -msgstr "``_ignore_`` 只有在建立的時候用到，在列舉建立完成後會被移除。" - -#: ../../library/enum.rst:309 -msgid "" -"``_ignore_`` is a list of names that will not become members, and whose " -"names will also be removed from the completed enumeration. See :ref:" -"`TimePeriod ` for an example." -msgstr "" -"``_ignore_`` 是一個不會變成成員的名稱串列，在列舉建立完成後其名稱會被移除。範" -"例請參考 :ref:`TimePeriod `。" - -#: ../../library/enum.rst:315 -msgid "" -"Returns ``['__class__', '__doc__', '__module__', 'name', 'value']`` and any " -"public methods defined on *self.__class__*::" -msgstr "" -"回傳 ``['__class__', '__doc__', '__module__', 'name', 'value']`` 及任何 " -"*self.__class__* 上定義的公開方法： ::" - -#: ../../library/enum.rst:318 -msgid "" -">>> from enum import Enum\n" -">>> from datetime import date\n" -">>> class Weekday(Enum):\n" -"... MONDAY = 1\n" -"... TUESDAY = 2\n" -"... WEDNESDAY = 3\n" -"... THURSDAY = 4\n" -"... FRIDAY = 5\n" -"... SATURDAY = 6\n" -"... SUNDAY = 7\n" -"... @classmethod\n" -"... def today(cls):\n" -"... print('today is %s' % cls(date.today().isoweekday()).name)\n" -"...\n" -">>> dir(Weekday.SATURDAY)\n" -"['__class__', '__doc__', '__eq__', '__hash__', '__module__', 'name', " -"'today', 'value']" -msgstr "" -">>> from enum import Enum\n" -">>> from datetime import date\n" -">>> class Weekday(Enum):\n" -"... MONDAY = 1\n" -"... TUESDAY = 2\n" -"... WEDNESDAY = 3\n" -"... THURSDAY = 4\n" -"... FRIDAY = 5\n" -"... SATURDAY = 6\n" -"... SUNDAY = 7\n" -"... @classmethod\n" -"... def today(cls):\n" -"... print('today is %s' % cls(date.today().isoweekday()).name)\n" -"...\n" -">>> dir(Weekday.SATURDAY)\n" -"['__class__', '__doc__', '__eq__', '__hash__', '__module__', 'name', " -"'today', 'value']" - -#: ../../library/enum.rst:0 -msgid "name" -msgstr "name" - -#: ../../library/enum.rst:337 -msgid "The name of the member being defined (e.g. 'RED')." -msgstr "定義的成員名稱（例如 'RED'）。" - -#: ../../library/enum.rst:338 -msgid "The start value for the Enum; the default is 1." -msgstr "列舉的開始值，預設為 1。" - -#: ../../library/enum.rst:0 -msgid "count" -msgstr "count" - -#: ../../library/enum.rst:339 -msgid "The number of members currently defined, not including this one." -msgstr "已定義的成員數量，不包含目前這一個。" - -#: ../../library/enum.rst:0 -msgid "last_values" -msgstr "last_values" - -#: ../../library/enum.rst:340 -msgid "A list of the previous values." -msgstr "一個之前值的串列。" - -#: ../../library/enum.rst:342 -msgid "" -"A *staticmethod* that is used to determine the next value returned by :class:" -"`auto`::" -msgstr "一個 *staticmethod*，用來決定 :class:`auto` 下一個要回傳的值的： ::" - -#: ../../library/enum.rst:345 -msgid "" -">>> from enum import auto, Enum\n" -">>> class PowersOfThree(Enum):\n" -"... @staticmethod\n" -"... def _generate_next_value_(name, start, count, last_values):\n" -"... return 3 ** (count + 1)\n" -"... FIRST = auto()\n" -"... SECOND = auto()\n" -"...\n" -">>> PowersOfThree.SECOND.value\n" -"9" -msgstr "" -">>> from enum import auto, Enum\n" -">>> class PowersOfThree(Enum):\n" -"... @staticmethod\n" -"... def _generate_next_value_(name, start, count, last_values):\n" -"... return 3 ** (count + 1)\n" -"... FIRST = auto()\n" -"... SECOND = auto()\n" -"...\n" -">>> PowersOfThree.SECOND.value\n" -"9" - -#: ../../library/enum.rst:358 -msgid "" -"By default, does nothing. If multiple values are given in the member " -"assignment, those values become separate arguments to ``__init__``; e.g." -msgstr "" -"預設情況下，不執行任何操作。如果在成員賦值中給出多個值，這些值將成為與 " -"``__init__`` 分別的引數；例如" - -#: ../../library/enum.rst:365 -msgid "" -"``Weekday.__init__()`` would be called as ``Weekday.__init__(self, 1, " -"'Mon')``" -msgstr "``Weekday.__init__()`` 將被稱為 ``Weekday.__init__(self, 1, 'Mon')``" - -#: ../../library/enum.rst:369 -msgid "" -"A *classmethod* that is used to further configure subsequent subclasses. By " -"default, does nothing." -msgstr "一個 *classmethod*，用來進一步設定後續的子類別，預設不做任何事。" - -#: ../../library/enum.rst:374 -msgid "" -"A *classmethod* for looking up values not found in *cls*. By default it " -"does nothing, but can be overridden to implement custom search behavior::" -msgstr "" -"一個 *classmethod*，用來查詢在 *cls* 裡找不到的值。預設不做任何事，但可以被覆" -"寫以實作客製化的搜尋行為： ::" - -#: ../../library/enum.rst:377 -msgid "" -">>> from enum import auto, StrEnum\n" -">>> class Build(StrEnum):\n" -"... DEBUG = auto()\n" -"... OPTIMIZED = auto()\n" -"... @classmethod\n" -"... def _missing_(cls, value):\n" -"... value = value.lower()\n" -"... for member in cls:\n" -"... if member.value == value:\n" -"... return member\n" -"... return None\n" -"...\n" -">>> Build.DEBUG.value\n" -"'debug'\n" -">>> Build('deBUG')\n" -"" -msgstr "" -">>> from enum import auto, StrEnum\n" -">>> class Build(StrEnum):\n" -"... DEBUG = auto()\n" -"... OPTIMIZED = auto()\n" -"... @classmethod\n" -"... def _missing_(cls, value):\n" -"... value = value.lower()\n" -"... for member in cls:\n" -"... if member.value == value:\n" -"... return member\n" -"... return None\n" -"...\n" -">>> Build.DEBUG.value\n" -"'debug'\n" -">>> Build('deBUG')\n" -"" - -#: ../../library/enum.rst:396 -msgid "" -"By default, doesn't exist. If specified, either in the enum class " -"definition or in a mixin class (such as ``int``), all values given in the " -"member assignment will be passed; e.g." -msgstr "" -"預設情況下不存在。如果有指定，無論是在列舉類別定義中還是在 mixin 類別中（例" -"如 ``int``\\ ），都將傳遞成員賦值中給出的所有值；例如" - -#: ../../library/enum.rst:404 -msgid "" -"results in the call ``int('1a', 16)`` and a value of ``26`` for the member." -msgstr "會產生呼叫 ``int('1a', 16)`` 而該成員的值為 ``26``。" - -#: ../../library/enum.rst:408 -msgid "" -"When writing a custom ``__new__``, do not use ``super().__new__`` -- call " -"the appropriate ``__new__`` instead." -msgstr "" -"當寫自訂的 ``__new__`` 時，不要使用 ``super().__new__``，而是要呼叫適當的 " -"``__new__``。" - -#: ../../library/enum.rst:413 -msgid "" -"Returns the string used for *repr()* calls. By default, returns the *Enum* " -"name, member name, and value, but can be overridden::" -msgstr "" -"回傳呼叫 *repr()* 時使用的字串。預設回傳 *Enum* 名稱、成員名稱及值，但可以被" -"覆寫： ::" - -#: ../../library/enum.rst:416 -msgid "" -">>> from enum import auto, Enum\n" -">>> class OtherStyle(Enum):\n" -"... ALTERNATE = auto()\n" -"... OTHER = auto()\n" -"... SOMETHING_ELSE = auto()\n" -"... def __repr__(self):\n" -"... cls_name = self.__class__.__name__\n" -"... return f'{cls_name}.{self.name}'\n" -"...\n" -">>> OtherStyle.ALTERNATE, str(OtherStyle.ALTERNATE), f\"{OtherStyle." -"ALTERNATE}\"\n" -"(OtherStyle.ALTERNATE, 'OtherStyle.ALTERNATE', 'OtherStyle.ALTERNATE')" -msgstr "" -">>> from enum import auto, Enum\n" -">>> class OtherStyle(Enum):\n" -"... ALTERNATE = auto()\n" -"... OTHER = auto()\n" -"... SOMETHING_ELSE = auto()\n" -"... def __repr__(self):\n" -"... cls_name = self.__class__.__name__\n" -"... return f'{cls_name}.{self.name}'\n" -"...\n" -">>> OtherStyle.ALTERNATE, str(OtherStyle.ALTERNATE), f\"{OtherStyle." -"ALTERNATE}\"\n" -"(OtherStyle.ALTERNATE, 'OtherStyle.ALTERNATE', 'OtherStyle.ALTERNATE')" - -#: ../../library/enum.rst:430 -msgid "" -"Returns the string used for *str()* calls. By default, returns the *Enum* " -"name and member name, but can be overridden::" -msgstr "" -"回傳呼叫 *str()* 時使用的字串。預設回傳 *Enum* 名稱及成員名稱，但可以被覆" -"寫： ::" - -#: ../../library/enum.rst:433 -msgid "" -">>> from enum import auto, Enum\n" -">>> class OtherStyle(Enum):\n" -"... ALTERNATE = auto()\n" -"... OTHER = auto()\n" -"... SOMETHING_ELSE = auto()\n" -"... def __str__(self):\n" -"... return f'{self.name}'\n" -"...\n" -">>> OtherStyle.ALTERNATE, str(OtherStyle.ALTERNATE), f\"{OtherStyle." -"ALTERNATE}\"\n" -"(, 'ALTERNATE', 'ALTERNATE')" -msgstr "" -">>> from enum import auto, Enum\n" -">>> class OtherStyle(Enum):\n" -"... ALTERNATE = auto()\n" -"... OTHER = auto()\n" -"... SOMETHING_ELSE = auto()\n" -"... def __str__(self):\n" -"... return f'{self.name}'\n" -"...\n" -">>> OtherStyle.ALTERNATE, str(OtherStyle.ALTERNATE), f\"{OtherStyle." -"ALTERNATE}\"\n" -"(, 'ALTERNATE', 'ALTERNATE')" - -#: ../../library/enum.rst:446 -msgid "" -"Returns the string used for *format()* and *f-string* calls. By default, " -"returns :meth:`__str__` return value, but can be overridden::" -msgstr "" -"回傳呼叫 *format()* 及 *f-string* 時使用的字串。預設回傳 :meth:`__str__` 的回" -"傳值，但可以被覆寫： ::" - -#: ../../library/enum.rst:449 -msgid "" -">>> from enum import auto, Enum\n" -">>> class OtherStyle(Enum):\n" -"... ALTERNATE = auto()\n" -"... OTHER = auto()\n" -"... SOMETHING_ELSE = auto()\n" -"... def __format__(self, spec):\n" -"... return f'{self.name}'\n" -"...\n" -">>> OtherStyle.ALTERNATE, str(OtherStyle.ALTERNATE), f\"{OtherStyle." -"ALTERNATE}\"\n" -"(, 'OtherStyle.ALTERNATE', 'ALTERNATE')" -msgstr "" -">>> from enum import auto, Enum\n" -">>> class OtherStyle(Enum):\n" -"... ALTERNATE = auto()\n" -"... OTHER = auto()\n" -"... SOMETHING_ELSE = auto()\n" -"... def __format__(self, spec):\n" -"... return f'{self.name}'\n" -"...\n" -">>> OtherStyle.ALTERNATE, str(OtherStyle.ALTERNATE), f\"{OtherStyle." -"ALTERNATE}\"\n" -"(, 'OtherStyle.ALTERNATE', 'ALTERNATE')" - -#: ../../library/enum.rst:462 -msgid "" -"Using :class:`auto` with :class:`Enum` results in integers of increasing " -"value, starting with ``1``." -msgstr ":class:`Enum` 使用 :class:`auto` 會產生從 ``1`` 開始遞增的整數。" - -#: ../../library/enum.rst:465 -msgid "Added :ref:`enum-dataclass-support`" -msgstr "新增 :ref:`enum-dataclass-support`" - -#: ../../library/enum.rst:469 -msgid "Adds a new name as an alias to an existing member::" -msgstr "新增一個名稱作為現有成員的別名： ::" - -#: ../../library/enum.rst:471 -msgid "" -">>> Color.RED._add_alias_(\"ERROR\")\n" -">>> Color.ERROR\n" -"" -msgstr "" -">>> Color.RED._add_alias_(\"ERROR\")\n" -">>> Color.ERROR\n" -"" - -#: ../../library/enum.rst:475 -msgid "" -"Raises a :exc:`NameError` if the name is already assigned to a different " -"member." -msgstr "如果該名稱已經被指派給不同的成員，則會引發 :exc:`NameError`。" - -#: ../../library/enum.rst:481 -msgid "Adds a new value as an alias to an existing member::" -msgstr "新增一個值作為現有成員的別名： ::" - -#: ../../library/enum.rst:483 -msgid "" -">>> Color.RED._add_value_alias_(42)\n" -">>> Color(42)\n" -"" -msgstr "" -">>> Color.RED._add_value_alias_(42)\n" -">>> Color(42)\n" -"" - -#: ../../library/enum.rst:487 -msgid "" -"Raises a :exc:`ValueError` if the value is already linked with a different " -"member." -msgstr "如果該值已經被連結到不同的成員，則會引發 :exc:`ValueError`。" - -#: ../../library/enum.rst:494 -msgid "" -"*IntEnum* is the same as :class:`Enum`, but its members are also integers " -"and can be used anywhere that an integer can be used. If any integer " -"operation is performed with an *IntEnum* member, the resulting value loses " -"its enumeration status." -msgstr "" -"*IntEnum* 和 :class:`Enum` 一樣，但其成員同時也是整數而可以被用在任何使用整數" -"的地方。如果 *IntEnum* 成員經過任何整數運算，結果值會失去其列舉狀態。" - -#: ../../library/enum.rst:515 -msgid "" -"Using :class:`auto` with :class:`IntEnum` results in integers of increasing " -"value, starting with ``1``." -msgstr ":class:`IntEnum` 使用 :class:`auto` 會產生從 ``1`` 開始遞增的整數。" - -#: ../../library/enum.rst:518 -msgid "" -":meth:`~object.__str__` is now :meth:`!int.__str__` to better support the " -"*replacement of existing constants* use-case. :meth:`~object.__format__` was " -"already :meth:`!int.__format__` for that same reason." -msgstr "" -"為了更好地支援\\ *現存常數取代 (replacement of existing constants)* 的使用情" -"境，:meth:`~object.__str__` 現在會是 :meth:`!int.__str__`。為了同樣的理由，:" -"meth:`~object.__format__` 已經是 :meth:`!int.__format__`。" - -#: ../../library/enum.rst:525 -msgid "" -"*StrEnum* is the same as :class:`Enum`, but its members are also strings and " -"can be used in most of the same places that a string can be used. The result " -"of any string operation performed on or with a *StrEnum* member is not part " -"of the enumeration." -msgstr "" -"*StrEnum* 和 :class:`Enum` 一樣，但其成員同時也是字串而可以被用在幾乎所有使用" -"字串的地方。*StrEnum* 成員經過任何字串操作的結果會不再是列舉的一部份。" - -#: ../../library/enum.rst:546 -msgid "" -"There are places in the stdlib that check for an exact :class:`str` instead " -"of a :class:`str` subclass (i.e. ``type(unknown) == str`` instead of " -"``isinstance(unknown, str)``), and in those locations you will need to use " -"``str(MyStrEnum.MY_MEMBER)``." -msgstr "" -"stdlib 裡有些地方會檢查只能是 :class:`str` 而不是 :class:`str` 的子類別（也就" -"是 ``type(unknown) == str`` 而不是 ``isinstance(unknown, str)``），在這些地方" -"你需要使用 ``str(MyStrEnum.MY_MEMBER)``。" - -#: ../../library/enum.rst:553 -msgid "" -"Using :class:`auto` with :class:`StrEnum` results in the lower-cased member " -"name as the value." -msgstr ":class:`StrEnum` 使用 :class:`auto` 會產生小寫的成員名稱當作值。" - -#: ../../library/enum.rst:558 -msgid "" -":meth:`~object.__str__` is :meth:`!str.__str__` to better support the " -"*replacement of existing constants* use-case. :meth:`~object.__format__` is " -"likewise :meth:`!str.__format__` for that same reason." -msgstr "" -"為了更好地支援\\ *現存常數取代 (replacement of existing constants)* 的使用情" -"境，:meth:`~object.__str__` 現在會是 :meth:`!str.__str__`。為了同樣的理由，:" -"meth:`~object.__format__` 也會是 :meth:`!str.__format__`。" - -#: ../../library/enum.rst:566 -msgid "" -"``Flag`` is the same as :class:`Enum`, but its members support the bitwise " -"operators ``&`` (*AND*), ``|`` (*OR*), ``^`` (*XOR*), and ``~`` (*INVERT*); " -"the results of those operations are (aliases of) members of the enumeration." -msgstr "" -"``Flag`` 與 :class:`Enum` 相同，但其成員支援位元運算子 ``&`` (*AND*)、``|`` " -"(*OR*)、``^`` (*XOR*) 和 ``~`` (*INVERT*)；這些操作的結果是列舉的成員（的別" -"名）。" - -#: ../../library/enum.rst:572 -msgid "Returns *True* if value is in self::" -msgstr "如果 value 在 self 裡則回傳 *True*： ::" - -#: ../../library/enum.rst:574 -msgid "" -">>> from enum import Flag, auto\n" -">>> class Color(Flag):\n" -"... RED = auto()\n" -"... GREEN = auto()\n" -"... BLUE = auto()\n" -"...\n" -">>> purple = Color.RED | Color.BLUE\n" -">>> white = Color.RED | Color.GREEN | Color.BLUE\n" -">>> Color.GREEN in purple\n" -"False\n" -">>> Color.GREEN in white\n" -"True\n" -">>> purple in white\n" -"True\n" -">>> white in purple\n" -"False" -msgstr "" -">>> from enum import Flag, auto\n" -">>> class Color(Flag):\n" -"... RED = auto()\n" -"... GREEN = auto()\n" -"... BLUE = auto()\n" -"...\n" -">>> purple = Color.RED | Color.BLUE\n" -">>> white = Color.RED | Color.GREEN | Color.BLUE\n" -">>> Color.GREEN in purple\n" -"False\n" -">>> Color.GREEN in white\n" -"True\n" -">>> purple in white\n" -"True\n" -">>> white in purple\n" -"False" - -#: ../../library/enum.rst:593 -msgid "Returns all contained non-alias members::" -msgstr "回傳所有包含的非別名成員： ::" - -#: ../../library/enum.rst:595 -msgid "" -">>> list(Color.RED)\n" -"[]\n" -">>> list(purple)\n" -"[, ]" -msgstr "" -">>> list(Color.RED)\n" -"[]\n" -">>> list(purple)\n" -"[, ]" - -#: ../../library/enum.rst:604 -msgid "Returns number of members in flag::" -msgstr "回傳旗標裡的成員數量： ::" - -#: ../../library/enum.rst:606 -msgid "" -">>> len(Color.GREEN)\n" -"1\n" -">>> len(white)\n" -"3" -msgstr "" -">>> len(Color.GREEN)\n" -"1\n" -">>> len(white)\n" -"3" - -#: ../../library/enum.rst:615 -msgid "Returns *True* if any members in flag, *False* otherwise::" -msgstr "如果成員在旗標裡則回傳 *True*，否則回傳 *False*： ::" - -#: ../../library/enum.rst:617 -msgid "" -">>> bool(Color.GREEN)\n" -"True\n" -">>> bool(white)\n" -"True\n" -">>> black = Color(0)\n" -">>> bool(black)\n" -"False" -msgstr "" -">>> bool(Color.GREEN)\n" -"True\n" -">>> bool(white)\n" -"True\n" -">>> black = Color(0)\n" -">>> bool(black)\n" -"False" - -#: ../../library/enum.rst:627 -msgid "Returns current flag binary or'ed with other::" -msgstr "回傳和 other 做 OR 過後的二進位旗標： ::" - -#: ../../library/enum.rst:629 -msgid "" -">>> Color.RED | Color.GREEN\n" -"" -msgstr "" -">>> Color.RED | Color.GREEN\n" -"" - -#: ../../library/enum.rst:634 -msgid "Returns current flag binary and'ed with other::" -msgstr "回傳和 other 做 AND 過後的二進位旗標： ::" - -#: ../../library/enum.rst:636 -msgid "" -">>> purple & white\n" -"\n" -">>> purple & Color.GREEN\n" -"" -msgstr "" -">>> purple & white\n" -"\n" -">>> purple & Color.GREEN\n" -"" - -#: ../../library/enum.rst:643 -msgid "Returns current flag binary xor'ed with other::" -msgstr "回傳和 other 做 XOR 過後的二進位旗標： ::" - -#: ../../library/enum.rst:645 -msgid "" -">>> purple ^ white\n" -"\n" -">>> purple ^ Color.GREEN\n" -"" -msgstr "" -">>> purple ^ white\n" -"\n" -">>> purple ^ Color.GREEN\n" -"" - -#: ../../library/enum.rst:652 -msgid "Returns all the flags in *type(self)* that are not in *self*::" -msgstr "回傳所有在 *type(self)* 但不在 *self* 裡的旗標： ::" - -#: ../../library/enum.rst:654 -msgid "" -">>> ~white\n" -"\n" -">>> ~purple\n" -"\n" -">>> ~Color.RED\n" -"" -msgstr "" -">>> ~white\n" -"\n" -">>> ~purple\n" -"\n" -">>> ~Color.RED\n" -"" - -#: ../../library/enum.rst:663 -msgid "" -"Function used to format any remaining unnamed numeric values. Default is " -"the value's repr; common choices are :func:`hex` and :func:`oct`." -msgstr "" -"用來格式化任何剩下未命名數值的函式。預設是值的 repr，常見選擇是 :func:`hex` " -"和 :func:`oct`。" - -#: ../../library/enum.rst:668 -msgid "" -"Using :class:`auto` with :class:`Flag` results in integers that are powers " -"of two, starting with ``1``." -msgstr ":class:`Flag` 使用 :class:`auto` 會產生從 ``1`` 開始 2 的次方的整數。" - -#: ../../library/enum.rst:671 -msgid "The *repr()* of zero-valued flags has changed. It is now:" -msgstr "值為 0 的旗標的 *repr()* 已改變。現在是：" - -#: ../../library/enum.rst:679 -msgid "" -"``IntFlag`` is the same as :class:`Flag`, but its members are also integers " -"and can be used anywhere that an integer can be used." -msgstr "" -"``IntFlag`` 和 :class:`Flag` 一樣，但其成員同時也是整數而可以被用在任何使用整" -"數的地方。" - -#: ../../library/enum.rst:693 -msgid "" -"If any integer operation is performed with an *IntFlag* member, the result " -"is not an *IntFlag*::" -msgstr "如果 *IntFlag* 成員經過任何整數運算，其結果不是 *IntFlag*： ::" - -#: ../../library/enum.rst:696 -msgid "" -">>> Color.RED + 2\n" -"3" -msgstr "" -">>> Color.RED + 2\n" -"3" - -#: ../../library/enum.rst:699 -msgid "If a :class:`Flag` operation is performed with an *IntFlag* member and:" -msgstr "如果 *IntFlag* 成員經過 :class:`Flag` 操作且：" - -#: ../../library/enum.rst:701 -msgid "the result is a valid *IntFlag*: an *IntFlag* is returned" -msgstr "結果是合法的 *IntFlag*：回傳 *IntFlag*" - -#: ../../library/enum.rst:702 -msgid "" -"the result is not a valid *IntFlag*: the result depends on the :class:" -"`FlagBoundary` setting" -msgstr "結果不是合法的 *IntFlag*：結果會根據 :class:`FlagBoundary` 的設定" - -#: ../../library/enum.rst:704 -msgid "The :func:`repr` of unnamed zero-valued flags has changed. It is now::" -msgstr "未命名且值為 0 的旗標的 :func:`repr` 已改變。現在是： ::" - -#: ../../library/enum.rst:706 -msgid "" -">>> Color(0)\n" -"" -msgstr "" -">>> Color(0)\n" -"" - -#: ../../library/enum.rst:711 -msgid "" -"Using :class:`auto` with :class:`IntFlag` results in integers that are " -"powers of two, starting with ``1``." -msgstr "" -":class:`IntFlag` 使用 :class:`auto` 會產生從 ``1`` 開始 2 的次方的整數。" - -#: ../../library/enum.rst:716 -msgid "" -":meth:`~object.__str__` is now :meth:`!int.__str__` to better support the " -"*replacement of existing constants* use-case. :meth:`~object.__format__` " -"was already :meth:`!int.__format__` for that same reason." -msgstr "" -"為了更好地支援\\ *現存常數取代 (replacement of existing constants)* 的使用情" -"境，:meth:`~object.__str__` 現在會是 :meth:`!int.__str__`。為了同樣的理由，:" -"meth:`~object.__format__` 已經是 :meth:`!int.__format__`。" - -#: ../../library/enum.rst:720 -msgid "" -"Inversion of an :class:`!IntFlag` now returns a positive value that is the " -"union of all flags not in the given flag, rather than a negative value. This " -"matches the existing :class:`Flag` behavior." -msgstr "" -":class:`!IntFlag` 的反轉 (inversion) 現在會回傳正值，該值是不在給定旗標的所有" -"旗標聯集，而不是一個負值。這符合現有 :class:`Flag` 的行為。" - -#: ../../library/enum.rst:726 -msgid "" -":class:`!ReprEnum` uses the :meth:`repr() ` of :class:`Enum`, " -"but the :class:`str() ` of the mixed-in data type:" -msgstr "" -":class:`!ReprEnum` 使用 :class:`Enum` 的 :meth:`repr() `，但使" -"用混合資料型別的 :class:`str() `：" - -#: ../../library/enum.rst:729 -msgid ":meth:`!int.__str__` for :class:`IntEnum` and :class:`IntFlag`" -msgstr "對 :class:`IntEnum` 和 :class:`IntFlag` 是 :meth:`!int.__str__`" - -#: ../../library/enum.rst:730 -msgid ":meth:`!str.__str__` for :class:`StrEnum`" -msgstr "對 :class:`StrEnum` 是 :meth:`!str.__str__`" - -#: ../../library/enum.rst:732 -msgid "" -"Inherit from :class:`!ReprEnum` to keep the :class:`str() ` / :func:" -"`format` of the mixed-in data type instead of using the :class:`Enum`-" -"default :meth:`str() `." -msgstr "" -"繼承 :class:`!ReprEnum` 來保留混合資料型別的 :class:`str() ` / :func:" -"`format`，而不是使用 :class:`Enum` 預設的 :meth:`str() `。" - -#: ../../library/enum.rst:741 -msgid "" -"*EnumCheck* contains the options used by the :func:`verify` decorator to " -"ensure various constraints; failed constraints result in a :exc:`ValueError`." -msgstr "" -"*EnumCheck* 包含 :func:`verify` 裝飾器使用的選項，以確保多樣的限制，不符合限" -"制會產生 :exc:`ValueError`。" - -#: ../../library/enum.rst:746 -msgid "Ensure that each value has only one name::" -msgstr "確保每個值只有一個名稱： ::" - -#: ../../library/enum.rst:748 -msgid "" -">>> from enum import Enum, verify, UNIQUE\n" -">>> @verify(UNIQUE)\n" -"... class Color(Enum):\n" -"... RED = 1\n" -"... GREEN = 2\n" -"... BLUE = 3\n" -"... CRIMSON = 1\n" -"Traceback (most recent call last):\n" -"...\n" -"ValueError: aliases found in : CRIMSON -> RED" -msgstr "" -">>> from enum import Enum, verify, UNIQUE\n" -">>> @verify(UNIQUE)\n" -"... class Color(Enum):\n" -"... RED = 1\n" -"... GREEN = 2\n" -"... BLUE = 3\n" -"... CRIMSON = 1\n" -"Traceback (most recent call last):\n" -"...\n" -"ValueError: aliases found in : CRIMSON -> RED" - -#: ../../library/enum.rst:762 -msgid "" -"Ensure that there are no missing values between the lowest-valued member and " -"the highest-valued member::" -msgstr "確保在最小值成員跟最大值成員間沒有缺少值： ::" - -#: ../../library/enum.rst:765 -msgid "" -">>> from enum import Enum, verify, CONTINUOUS\n" -">>> @verify(CONTINUOUS)\n" -"... class Color(Enum):\n" -"... RED = 1\n" -"... GREEN = 2\n" -"... BLUE = 5\n" -"Traceback (most recent call last):\n" -"...\n" -"ValueError: invalid enum 'Color': missing values 3, 4" -msgstr "" -">>> from enum import Enum, verify, CONTINUOUS\n" -">>> @verify(CONTINUOUS)\n" -"... class Color(Enum):\n" -"... RED = 1\n" -"... GREEN = 2\n" -"... BLUE = 5\n" -"Traceback (most recent call last):\n" -"...\n" -"ValueError: invalid enum 'Color': missing values 3, 4" - -#: ../../library/enum.rst:777 -msgid "" -"Ensure that any flag groups/masks contain only named flags -- useful when " -"values are specified instead of being generated by :func:`auto`::" -msgstr "" -"確保任何旗標群組 / 遮罩只包含命名旗標 -- 當值是用指定而不是透過 :func:`auto` " -"產生時是很實用的： ::" - -#: ../../library/enum.rst:780 -msgid "" -">>> from enum import Flag, verify, NAMED_FLAGS\n" -">>> @verify(NAMED_FLAGS)\n" -"... class Color(Flag):\n" -"... RED = 1\n" -"... GREEN = 2\n" -"... BLUE = 4\n" -"... WHITE = 15\n" -"... NEON = 31\n" -"Traceback (most recent call last):\n" -"...\n" -"ValueError: invalid Flag 'Color': aliases WHITE and NEON are missing " -"combined values of 0x18 [use enum.show_flag_values(value) for details]" -msgstr "" -">>> from enum import Flag, verify, NAMED_FLAGS\n" -">>> @verify(NAMED_FLAGS)\n" -"... class Color(Flag):\n" -"... RED = 1\n" -"... GREEN = 2\n" -"... BLUE = 4\n" -"... WHITE = 15\n" -"... NEON = 31\n" -"Traceback (most recent call last):\n" -"...\n" -"ValueError: invalid Flag 'Color': aliases WHITE and NEON are missing " -"combined values of 0x18 [use enum.show_flag_values(value) for details]" - -#: ../../library/enum.rst:794 -msgid "" -"CONTINUOUS and NAMED_FLAGS are designed to work with integer-valued members." -msgstr "CONTINUOUS 和 NAMED_FLAGS 是設計用來運作在整數值的成員上。" - -#: ../../library/enum.rst:800 -msgid "" -"``FlagBoundary`` controls how out-of-range values are handled in :class:" -"`Flag` and its subclasses." -msgstr "``FlagBoundary`` 控制在 :class:`Flag` 及其子類別中如何處理範圍外的值。" - -#: ../../library/enum.rst:805 -msgid "" -"Out-of-range values cause a :exc:`ValueError` to be raised. This is the " -"default for :class:`Flag`::" -msgstr "範圍外的值會引發 :exc:`ValueError`。這是 :class:`Flag` 的預設行為： ::" - -#: ../../library/enum.rst:808 -msgid "" -">>> from enum import Flag, STRICT, auto\n" -">>> class StrictFlag(Flag, boundary=STRICT):\n" -"... RED = auto()\n" -"... GREEN = auto()\n" -"... BLUE = auto()\n" -"...\n" -">>> StrictFlag(2**2 + 2**4)\n" -"Traceback (most recent call last):\n" -"...\n" -"ValueError: invalid value 20\n" -" given 0b0 10100\n" -" allowed 0b0 00111" -msgstr "" -">>> from enum import Flag, STRICT, auto\n" -">>> class StrictFlag(Flag, boundary=STRICT):\n" -"... RED = auto()\n" -"... GREEN = auto()\n" -"... BLUE = auto()\n" -"...\n" -">>> StrictFlag(2**2 + 2**4)\n" -"Traceback (most recent call last):\n" -"...\n" -"ValueError: invalid value 20\n" -" given 0b0 10100\n" -" allowed 0b0 00111" - -#: ../../library/enum.rst:823 -msgid "" -"Out-of-range values have invalid values removed, leaving a valid :class:" -"`Flag` value::" -msgstr "會移除範圍外的值中的非法值，留下合法的 :class:`Flag` 值： ::" - -#: ../../library/enum.rst:826 -msgid "" -">>> from enum import Flag, CONFORM, auto\n" -">>> class ConformFlag(Flag, boundary=CONFORM):\n" -"... RED = auto()\n" -"... GREEN = auto()\n" -"... BLUE = auto()\n" -"...\n" -">>> ConformFlag(2**2 + 2**4)\n" -"" -msgstr "" -">>> from enum import Flag, CONFORM, auto\n" -">>> class ConformFlag(Flag, boundary=CONFORM):\n" -"... RED = auto()\n" -"... GREEN = auto()\n" -"... BLUE = auto()\n" -"...\n" -">>> ConformFlag(2**2 + 2**4)\n" -"" - -#: ../../library/enum.rst:837 -msgid "" -"Out-of-range values lose their :class:`Flag` membership and revert to :class:" -"`int`." -msgstr "範圍外的值會失去它們的 :class:`Flag` 成員資格且恢復成 :class:`int`。" - -#: ../../library/enum.rst:850 -msgid "" -"Out-of-range values are kept, and the :class:`Flag` membership is kept. This " -"is the default for :class:`IntFlag`::" -msgstr "" -"範圍外的值會被保留，:class:`Flag` 成員資格也會被保留。這是 :class:`IntFlag` " -"的預設行為： ::" - -#: ../../library/enum.rst:853 -msgid "" -">>> from enum import Flag, KEEP, auto\n" -">>> class KeepFlag(Flag, boundary=KEEP):\n" -"... RED = auto()\n" -"... GREEN = auto()\n" -"... BLUE = auto()\n" -"...\n" -">>> KeepFlag(2**2 + 2**4)\n" -"" -msgstr "" -">>> from enum import Flag, KEEP, auto\n" -">>> class KeepFlag(Flag, boundary=KEEP):\n" -"... RED = auto()\n" -"... GREEN = auto()\n" -"... BLUE = auto()\n" -"...\n" -">>> KeepFlag(2**2 + 2**4)\n" -"" - -#: ../../library/enum.rst:866 -msgid "" -"*EnumDict* is a subclass of :class:`dict` that is used as the namespace for " -"defining enum classes (see :ref:`prepare`). It is exposed to allow " -"subclasses of :class:`EnumType` with advanced behavior like having multiple " -"values per member. It should be called with the name of the enum class being " -"created, otherwise private names and internal classes will not be handled " -"correctly." -msgstr "" -"*EnumDict* 是 :class:`dict` 的子類別，用來作為定義列舉類別的命名空間（參見 :" -"ref:`prepare`）。它被公開來使得 :class:`EnumType` 的子類別能具有進階行為，例" -"如讓每個成員有多個值。它應該在被呼叫時帶上正在建立的列舉類別名稱，否則私有名" -"稱和內部類別將無法被正確處理。" - -#: ../../library/enum.rst:873 -msgid "" -"Note that only the :class:`~collections.abc.MutableMapping` interface (:meth:" -"`~object.__setitem__` and :meth:`~dict.update`) is overridden. It may be " -"possible to bypass the checks using other :class:`!dict` operations like :" -"meth:`|= `." -msgstr "" -"注意只有 :class:`~collections.abc.MutableMapping` 介面（:meth:`~object." -"__setitem__` 和 :meth:`~dict.update`）被覆寫。可能可以使用其他 :class:`!" -"dict` 操作來繞過檢查，例如 :meth:`|= `。" - -#: ../../library/enum.rst:880 -msgid "A list of member names." -msgstr "一個成員名稱的串列。" - -#: ../../library/enum.rst:887 -msgid "Supported ``__dunder__`` names" -msgstr "支援的 ``__dunder__`` 名稱" - -#: ../../library/enum.rst:889 -msgid "" -":attr:`~EnumType.__members__` is a read-only ordered mapping of " -"``member_name``:``member`` items. It is only available on the class." -msgstr "" -":attr:`~EnumType.__members__` 是一個唯讀有序的\\ ``成員名稱``：``成員``\\ 項" -"目的對映。只有在類別上可用。" - -#: ../../library/enum.rst:892 -msgid "" -":meth:`~Enum.__new__`, if specified, must create and return the enum " -"members; it is also a very good idea to set the member's :attr:`!_value_` " -"appropriately. Once all the members are created it is no longer used." -msgstr "" -":meth:`~Enum.__new__`，如果有指定，它必須建立並回傳列舉成員；適當地設定成員" -"的 :attr:`!_value_` 也是一個很好的主意。一旦所有成員都建立之後就不會再被用" -"到。" - -#: ../../library/enum.rst:898 -msgid "Supported ``_sunder_`` names" -msgstr "支援的 ``_sunder_`` 名稱" - -#: ../../library/enum.rst:900 -msgid ":attr:`~Enum._name_` -- name of the member" -msgstr ":attr:`~Enum._name_` -- 成員名稱" - -#: ../../library/enum.rst:901 -msgid ":attr:`~Enum._value_` -- value of the member; can be set in ``__new__``" -msgstr ":attr:`~Enum._value_` -- 成員的值；可以在 ``__new__`` 設定" - -#: ../../library/enum.rst:902 -msgid "" -":meth:`~Enum._missing_` -- a lookup function used when a value is not found; " -"may be overridden" -msgstr "" -":meth:`~Enum._missing_` -- 當值沒有被找到時會使用的查詢函式；可以被覆寫" - -#: ../../library/enum.rst:904 -msgid "" -":attr:`~Enum._ignore_` -- a list of names, either as a :class:`list` or a :" -"class:`str`, that will not be transformed into members, and will be removed " -"from the final class" -msgstr "" -":attr:`~Enum._ignore_` -- 一個名稱的串列，可以是 :class:`list` 或 :class:" -"`str`，它不會被轉換成成員，且在最後的類別上會被移除" - -#: ../../library/enum.rst:907 -msgid "" -":attr:`~Enum._order_` -- no longer used, kept for backward compatibility " -"(class attribute, removed during class creation)" -msgstr "" -":attr:`~Enum._order_` -- 不再被使用，僅為了向後相容而保留（類別屬性，在類別建" -"立時移除）" - -#: ../../library/enum.rst:909 -msgid "" -":meth:`~Enum._generate_next_value_` -- used to get an appropriate value for " -"an enum member; may be overridden" -msgstr "" -":meth:`~Enum._generate_next_value_` -- 用來為列舉成員取得合適的值；可以被覆寫" - -#: ../../library/enum.rst:914 -msgid "" -"For standard :class:`Enum` classes the next value chosen is the highest " -"value seen incremented by one." -msgstr "" -"對標準的 :class:`Enum` 類別來說，下一個被選擇的值是所看過的最大值加一。" - -#: ../../library/enum.rst:917 -msgid "" -"For :class:`Flag` classes the next value chosen will be the next highest " -"power-of-two." -msgstr "" -"對 :class:`Flag` 類別來說，下一個被選擇的值是下一個最大的 2 的次方的數字。" - -#: ../../library/enum.rst:920 -msgid "" -":meth:`~Enum._add_alias_` -- adds a new name as an alias to an existing " -"member." -msgstr ":meth:`~Enum._add_alias_` -- 新增一個名稱作為現有成員的別名。" - -#: ../../library/enum.rst:922 -msgid "" -":meth:`~Enum._add_value_alias_` -- adds a new value as an alias to an " -"existing member." -msgstr ":meth:`~Enum._add_value_alias_` -- 新增一個值作為現有成員的別名。" - -#: ../../library/enum.rst:925 -msgid "" -"While ``_sunder_`` names are generally reserved for the further development " -"of the :class:`Enum` class and can not be used, some are explicitly allowed:" -msgstr "" -"雖然 ``_sunder_`` 名稱通常保留用於 :class:`Enum` 類別的進一步開發而不能被使" -"用，但有些是明確允許的：" - -#: ../../library/enum.rst:928 -msgid "" -"``_repr_*`` (e.g. ``_repr_html_``), as used in `IPython's rich display`_" -msgstr "" -"``_repr_*``\\ （例如 ``_repr_html_``），例如用於 `IPython 的豐富顯示 " -"`_" - -#: ../../library/enum.rst:930 -msgid "``_missing_``, ``_order_``, ``_generate_next_value_``" -msgstr "``_missing_``、``_order_``、``_generate_next_value_``" - -#: ../../library/enum.rst:931 -msgid "``_ignore_``" -msgstr "``_ignore_``" - -#: ../../library/enum.rst:932 -msgid "``_add_alias_``, ``_add_value_alias_``, ``_repr_*``" -msgstr "``_add_alias_``、``_add_value_alias_``、``_repr_*``" - -#: ../../library/enum.rst:938 -msgid "Utilities and Decorators" -msgstr "通用項目與裝飾器" - -#: ../../library/enum.rst:942 -msgid "" -"*auto* can be used in place of a value. If used, the *Enum* machinery will " -"call an :class:`Enum`'s :meth:`~Enum._generate_next_value_` to get an " -"appropriate value. For :class:`Enum` and :class:`IntEnum` that appropriate " -"value will be the last value plus one; for :class:`Flag` and :class:" -"`IntFlag` it will be the first power-of-two greater than the highest value; " -"for :class:`StrEnum` it will be the lower-cased version of the member's " -"name. Care must be taken if mixing *auto()* with manually specified values." -msgstr "" -"*auto* 可以用來取代給值。如果使用的話，*Enum* 系統會呼叫 :class:`Enum` 的 :" -"meth:`~Enum._generate_next_value_` 來取得合適的值。對 :class:`Enum` 和 :" -"class:`IntEnum` 來說，合適的值是最後一個值加一；對 :class:`Flag` 和 :class:" -"`IntFlag` 來說，是第一個比最大值還大的 2 的次方的數字；對 :class:`StrEnum` 來" -"說，是成員名稱的小寫版本。如果混用 *auto()* 和手動指定值的話要特別注意。" - -#: ../../library/enum.rst:950 -msgid "" -"*auto* instances are only resolved when at the top level of an assignment, " -"either by itself or as part of a tuple:" -msgstr "*auto* 實例只有在最上層的賦值時才會被解析，不論是獨自一個或作為元組的一部分：" - -#: ../../library/enum.rst:953 -msgid "``FIRST = auto()`` will work (auto() is replaced with ``1``);" -msgstr "``FIRST = auto()`` 可以運作（auto() 會被取代成 ``1``）" - -#: ../../library/enum.rst:954 -msgid "" -"``SECOND = auto(), -2`` will work (auto is replaced with ``2``, so ``2, -2`` " -"is used to create the ``SECOND`` enum member;" -msgstr "" -"``SECOND = auto(), -2`` 可以運作（auto 會被取代成 ``2``, 因此 ``2, -2`` 會被" -"用來建立列舉成員 ``SECOND``；" - -#: ../../library/enum.rst:956 -msgid "" -"``THREE = [auto(), -3]`` will *not* work (``[, -3]`` is used " -"to create the ``THREE`` enum member)" -msgstr "" -"``THREE = [auto(), -3]`` *無法*\\ 運作（``[, -3]`` 會被用來建立列" -"舉成員 ``THREE``）" - -#: ../../library/enum.rst:961 -msgid "" -"In prior versions, ``auto()`` had to be the only thing on the assignment " -"line to work properly." -msgstr "在之前的版本中，``auto()`` 必須是賦值行裡的唯一內容才能運作正確。" - -#: ../../library/enum.rst:964 -msgid "" -"``_generate_next_value_`` can be overridden to customize the values used by " -"*auto*." -msgstr "可以覆寫 ``_generate_next_value_`` 來客製 *auto* 使用的值。" - -#: ../../library/enum.rst:967 -msgid "" -"in 3.13 the default ``_generate_next_value_`` will always return the highest " -"member value incremented by 1, and will fail if any member is an " -"incompatible type." -msgstr "" -"在 3.13 預設 ``_generate_next_value_`` 總是回傳最大的成員值加一，如果任何成員" -"是不相容的型別就會失敗。" - -#: ../../library/enum.rst:973 -msgid "" -"A decorator similar to the built-in *property*, but specifically for " -"enumerations. It allows member attributes to have the same names as members " -"themselves." -msgstr "" -"和內建的 *property* 相似的裝飾器，但只專門針對列舉。它允許成員屬性和成員本身" -"有相同名稱。" - -#: ../../library/enum.rst:977 -msgid "" -"the *property* and the member must be defined in separate classes; for " -"example, the *value* and *name* attributes are defined in the *Enum* class, " -"and *Enum* subclasses can define members with the names ``value`` and " -"``name``." -msgstr "" -"*屬性*\\ 和成員必須定義在分開的類別裡；例如 *value* 和 *name* 屬性定義在 " -"*Enum* 類別而 *Enum* 子類別可以定義成員名稱為 ``value`` 和 ``name``。" - -#: ../../library/enum.rst:986 -msgid "" -"A :keyword:`class` decorator specifically for enumerations. It searches an " -"enumeration's :attr:`~EnumType.__members__`, gathering any aliases it finds; " -"if any are found :exc:`ValueError` is raised with the details::" -msgstr "" -"專門針對列舉的 :keyword:`class` 裝飾器。它搜尋列舉的 :attr:`~EnumType." -"__members__`，蒐集任何它找到的別名；如果有找到任何別名則引發 :exc:" -"`ValueError` 並附上細節： ::" - -#: ../../library/enum.rst:990 -msgid "" -">>> from enum import Enum, unique\n" -">>> @unique\n" -"... class Mistake(Enum):\n" -"... ONE = 1\n" -"... TWO = 2\n" -"... THREE = 3\n" -"... FOUR = 3\n" -"...\n" -"Traceback (most recent call last):\n" -"...\n" -"ValueError: duplicate values found in : FOUR -> THREE" -msgstr "" -">>> from enum import Enum, unique\n" -">>> @unique\n" -"... class Mistake(Enum):\n" -"... ONE = 1\n" -"... TWO = 2\n" -"... THREE = 3\n" -"... FOUR = 3\n" -"...\n" -"Traceback (most recent call last):\n" -"...\n" -"ValueError: duplicate values found in : FOUR -> THREE" - -#: ../../library/enum.rst:1004 -msgid "" -"A :keyword:`class` decorator specifically for enumerations. Members from :" -"class:`EnumCheck` are used to specify which constraints should be checked on " -"the decorated enumeration." -msgstr "" -"專門針對列舉的 :keyword:`class` 裝飾器。使用 :class:`EnumCheck` 裡的成員來指" -"定在裝飾的列舉上應該檢查什麼限制。" - -#: ../../library/enum.rst:1012 -msgid "A decorator for use in enums: its target will become a member." -msgstr "列舉所使用的裝飾器：其目標會變成成員。" - -#: ../../library/enum.rst:1018 -msgid "A decorator for use in enums: its target will not become a member." -msgstr "列舉所使用的裝飾器：其目標不會變成成員。" - -#: ../../library/enum.rst:1024 -msgid "" -"A decorator to change the :class:`str() ` and :func:`repr` of an enum " -"to show its members as belonging to the module instead of its class. Should " -"only be used when the enum members are exported to the module global " -"namespace (see :class:`re.RegexFlag` for an example)." -msgstr "" -"修改列舉的 :class:`str() ` 及 :func:`repr` 的裝飾器，讓成員顯示為屬於模" -"組而不是其類別。應該只有當列舉成員被匯出到模組的全域命名空間才使用（範例請參" -"考 :class:`re.RegexFlag`）。" - -#: ../../library/enum.rst:1034 -msgid "Return a list of all power-of-two integers contained in a flag *value*." -msgstr "回傳在旗標\\ *值*\\ 中包含的所有 2 的次方的整數串列。" - -#: ../../library/enum.rst:1041 -msgid "Notes" -msgstr "備註" - -#: ../../library/enum.rst:1043 -msgid ":class:`IntEnum`, :class:`StrEnum`, and :class:`IntFlag`" -msgstr ":class:`IntEnum`、:class:`StrEnum` 及 :class:`IntFlag`" - -#: ../../library/enum.rst:1045 -msgid "" -"These three enum types are designed to be drop-in replacements for existing " -"integer- and string-based values; as such, they have extra limitations:" -msgstr "" -"這三種列舉型別是設計來直接取代現有以整數及字串為基底的值；因此它們有額外的限" -"制：" - -#: ../../library/enum.rst:1048 -msgid "``__str__`` uses the value and not the name of the enum member" -msgstr "``__str__`` 使用值而不是列舉成員的名稱" - -#: ../../library/enum.rst:1050 -msgid "" -"``__format__``, because it uses ``__str__``, will also use the value of the " -"enum member instead of its name" -msgstr "``__format__`` 因為使用 ``__str__``，也會使用值而不是列舉成員的名稱" - -#: ../../library/enum.rst:1053 -msgid "" -"If you do not need/want those limitations, you can either create your own " -"base class by mixing in the ``int`` or ``str`` type yourself::" -msgstr "" -"如果你不需要或不想要這些限制，你可以透過混合 ``int`` 或 ``str`` 型別來建立自" -"己的基礎類別： ::" - -#: ../../library/enum.rst:1056 -msgid "" -">>> from enum import Enum\n" -">>> class MyIntEnum(int, Enum):\n" -"... pass" -msgstr "" -">>> from enum import Enum\n" -">>> class MyIntEnum(int, Enum):\n" -"... pass" - -#: ../../library/enum.rst:1060 -msgid "or you can reassign the appropriate :meth:`str`, etc., in your enum::" -msgstr "或者你也可以在你的列舉重新給定合適的 :meth:`str`： ::" - -#: ../../library/enum.rst:1062 -msgid "" -">>> from enum import Enum, IntEnum\n" -">>> class MyIntEnum(IntEnum):\n" -"... __str__ = Enum.__str__" -msgstr "" -">>> from enum import Enum, IntEnum\n" -">>> class MyIntEnum(IntEnum):\n" -"... __str__ = Enum.__str__" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-12-19 00:15+0000\n" +"PO-Revision-Date: 2024-12-21 13:50+0800\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/enum.rst:2 +msgid ":mod:`!enum` --- Support for enumerations" +msgstr ":mod:`!enum` --- 對列舉的支援" + +#: ../../library/enum.rst:14 +msgid "**Source code:** :source:`Lib/enum.py`" +msgstr "**原始碼：**\\ :source:`Lib/enum.py`" + +#: ../../library/enum.rst:16 +msgid "Important" +msgstr "重點資訊" + +#: ../../library/enum.rst:18 +msgid "" +"This page contains the API reference information. For tutorial information " +"and discussion of more advanced topics, see" +msgstr "本頁包含 API 的參考資訊。關於教學資訊及更多進階主題的討論請參考" + +#: ../../library/enum.rst:21 +msgid ":ref:`Basic Tutorial `" +msgstr ":ref:`基本教學 `" + +#: ../../library/enum.rst:22 +msgid ":ref:`Advanced Tutorial `" +msgstr ":ref:`進階教學 `" + +#: ../../library/enum.rst:23 +msgid ":ref:`Enum Cookbook `" +msgstr ":ref:`列舉指南 `" + +#: ../../library/enum.rst:27 +msgid "An enumeration:" +msgstr "列舉：" + +#: ../../library/enum.rst:29 +msgid "is a set of symbolic names (members) bound to unique values" +msgstr "是一組綁定唯一值的代表名稱（成員）" + +#: ../../library/enum.rst:30 +msgid "" +"can be iterated over to return its canonical (i.e. non-alias) members in " +"definition order" +msgstr "可以用疊代的方式以定義的順序回傳其正式 (canonical)（即非別名）成員" + +#: ../../library/enum.rst:32 +msgid "uses *call* syntax to return members by value" +msgstr "使用 *call* 語法來透過值回傳成員" + +#: ../../library/enum.rst:33 +msgid "uses *index* syntax to return members by name" +msgstr "使用 *index* 語法來透過名稱回傳成員" + +#: ../../library/enum.rst:35 +msgid "" +"Enumerations are created either by using :keyword:`class` syntax, or by " +"using function-call syntax::" +msgstr "列舉透過 :keyword:`class` 語法或函式呼叫的語法來建立： ::" + +#: ../../library/enum.rst:38 +msgid "" +">>> from enum import Enum\n" +"\n" +">>> # class syntax\n" +">>> class Color(Enum):\n" +"... RED = 1\n" +"... GREEN = 2\n" +"... BLUE = 3\n" +"\n" +">>> # functional syntax\n" +">>> Color = Enum('Color', [('RED', 1), ('GREEN', 2), ('BLUE', 3)])" +msgstr "" +">>> from enum import Enum\n" +"\n" +">>> # class 語法\n" +">>> class Color(Enum):\n" +"... RED = 1\n" +"... GREEN = 2\n" +"... BLUE = 3\n" +"\n" +">>> # 函式語法\n" +">>> Color = Enum('Color', [('RED', 1), ('GREEN', 2), ('BLUE', 3)])" + +#: ../../library/enum.rst:49 +msgid "" +"Even though we can use :keyword:`class` syntax to create Enums, Enums are " +"not normal Python classes. See :ref:`How are Enums different? ` for more details." +msgstr "" +"雖然我們可以用 :keyword:`class` 語法來建立列舉，列舉並不是標準的 Python 類" +"別。參考\\ :ref:`列舉有何差異 `\\ 以取得更多細節。" + +#: ../../library/enum.rst:53 +msgid "Nomenclature" +msgstr "命名方式" + +#: ../../library/enum.rst:55 +msgid "The class :class:`!Color` is an *enumeration* (or *enum*)" +msgstr ":class:`!Color` 類別是一個\\ *列舉*\\ （或 *enum*）" + +#: ../../library/enum.rst:56 +msgid "" +"The attributes :attr:`!Color.RED`, :attr:`!Color.GREEN`, etc., are " +"*enumeration members* (or *members*) and are functionally constants." +msgstr "" +":attr:`!Color.RED`、:attr:`!Color.GREEN` 等屬性是\\ *列舉成員*\\ （或\\ *成員" +"*），並且使用上可以看作常數。" + +#: ../../library/enum.rst:58 +msgid "" +"The enum members have *names* and *values* (the name of :attr:`!Color.RED` " +"is ``RED``, the value of :attr:`!Color.BLUE` is ``3``, etc.)" +msgstr "" +"列舉成員有\\ *名稱*\\ 和\\ *值*\\ （:attr:`!Color.RED` 的名稱是 ``RED``，:" +"attr:`!Color.BLUE` 的值是 ``3`` 諸如此類）" + +#: ../../library/enum.rst:65 +msgid "Module Contents" +msgstr "模組內容" + +#: ../../library/enum.rst:67 +msgid ":class:`EnumType`" +msgstr ":class:`EnumType`" + +#: ../../library/enum.rst:69 +msgid "The ``type`` for Enum and its subclasses." +msgstr "Enum 及其子類別的 ``type``。" + +#: ../../library/enum.rst:71 +msgid ":class:`Enum`" +msgstr ":class:`Enum`" + +#: ../../library/enum.rst:73 +msgid "Base class for creating enumerated constants." +msgstr "用來建立列舉常數的基礎類別。" + +#: ../../library/enum.rst:75 +msgid ":class:`IntEnum`" +msgstr ":class:`IntEnum`" + +#: ../../library/enum.rst:77 +msgid "" +"Base class for creating enumerated constants that are also subclasses of :" +"class:`int`. (`Notes`_)" +msgstr "" +"用來建立列舉常數的基礎類別，同時也是 :class:`int` 的子類別。（`備註 " +"`_）" + +#: ../../library/enum.rst:80 +msgid ":class:`StrEnum`" +msgstr ":class:`StrEnum`" + +#: ../../library/enum.rst:82 +msgid "" +"Base class for creating enumerated constants that are also subclasses of :" +"class:`str`. (`Notes`_)" +msgstr "" +"用來建立列舉常數的基礎類別，同時也是 :class:`str` 的子類別。（`備註 " +"`_）" + +#: ../../library/enum.rst:85 +msgid ":class:`Flag`" +msgstr ":class:`Flag`" + +#: ../../library/enum.rst:87 +msgid "" +"Base class for creating enumerated constants that can be combined using the " +"bitwise operations without losing their :class:`Flag` membership." +msgstr "" +"用來建立列舉常數的基礎類別，可以使用位元操作來結合成員且其結果不失去 :class:" +"`Flag` 的成員資格。" + +#: ../../library/enum.rst:90 +msgid ":class:`IntFlag`" +msgstr ":class:`IntFlag`" + +#: ../../library/enum.rst:92 +msgid "" +"Base class for creating enumerated constants that can be combined using the " +"bitwise operators without losing their :class:`IntFlag` membership. :class:" +"`IntFlag` members are also subclasses of :class:`int`. (`Notes`_)" +msgstr "" +"用來建立列舉常數的基礎類別，可以使用位元操作來結合成員且其結果不失去 :class:" +"`IntFlag` 的成員資格。:class:`IntFlag` 的成員也是 :class:`int` 的子類別。（`" +"備註 `_）" + +#: ../../library/enum.rst:96 +msgid ":class:`ReprEnum`" +msgstr ":class:`ReprEnum`" + +#: ../../library/enum.rst:98 +msgid "" +"Used by :class:`IntEnum`, :class:`StrEnum`, and :class:`IntFlag` to keep " +"the :class:`str() ` of the mixed-in type." +msgstr "" +"由 :class:`IntEnum`、:class:`StrEnum` 及 :class:`IntFlag` 所使用來保留這些混" +"合型別的 :class:`str() `。" + +#: ../../library/enum.rst:101 +msgid ":class:`EnumCheck`" +msgstr ":class:`EnumCheck`" + +#: ../../library/enum.rst:103 +msgid "" +"An enumeration with the values ``CONTINUOUS``, ``NAMED_FLAGS``, and " +"``UNIQUE``, for use with :func:`verify` to ensure various constraints are " +"met by a given enumeration." +msgstr "" +"一個有 ``CONTINUOUS``、``NAMED_FLAGS`` 及 ``UNIQUE`` 這些值的列舉，和 :func:" +"`verify` 一起使用來確保給定的列舉符合多種限制。" + +#: ../../library/enum.rst:107 +msgid ":class:`FlagBoundary`" +msgstr ":class:`FlagBoundary`" + +#: ../../library/enum.rst:109 +msgid "" +"An enumeration with the values ``STRICT``, ``CONFORM``, ``EJECT``, and " +"``KEEP`` which allows for more fine-grained control over how invalid values " +"are dealt with in an enumeration." +msgstr "" +"一個有 ``STRICT``、``CONFORM``、``EJECT`` 及 ``KEEP`` 這些值的列舉，允許列舉" +"對如何處理非法值做更細微的控制。" + +#: ../../library/enum.rst:113 +msgid ":class:`EnumDict`" +msgstr ":class:`EnumDict`" + +#: ../../library/enum.rst:115 +msgid "A subclass of :class:`dict` for use when subclassing :class:`EnumType`." +msgstr ":class:`dict` 的子類別，用於當作 :class:`EnumType` 的子類別時使用。" + +#: ../../library/enum.rst:117 +msgid ":class:`auto`" +msgstr ":class:`auto`" + +#: ../../library/enum.rst:119 +msgid "" +"Instances are replaced with an appropriate value for Enum members. :class:" +"`StrEnum` defaults to the lower-cased version of the member name, while " +"other Enums default to 1 and increase from there." +msgstr "" +"列舉成員的實例會被取代成合適的值。:class:`StrEnum` 預設是小寫版本的成員名稱，" +"其它列舉則預設是 1 且往後遞增。" + +#: ../../library/enum.rst:123 +msgid ":func:`~enum.property`" +msgstr ":func:`~enum.property`" + +#: ../../library/enum.rst:125 +msgid "" +"Allows :class:`Enum` members to have attributes without conflicting with " +"member names. The ``value`` and ``name`` attributes are implemented this " +"way." +msgstr "" +"允許 :class:`Enum` 成員擁有屬性且不會與成員名稱有衝突。``value`` 及 ``name`` " +"屬性是用這個方式來實作。" + +#: ../../library/enum.rst:129 +msgid ":func:`unique`" +msgstr ":func:`unique`" + +#: ../../library/enum.rst:131 +msgid "" +"Enum class decorator that ensures only one name is bound to any one value." +msgstr "Enum 類別的裝飾器，用來確保任何值只有綁定到一個名稱上。" + +#: ../../library/enum.rst:133 +msgid ":func:`verify`" +msgstr ":func:`verify`" + +#: ../../library/enum.rst:135 +msgid "" +"Enum class decorator that checks user-selectable constraints on an " +"enumeration." +msgstr "Enum 類別的裝飾器，用來檢查列舉上使用者所選的限制。" + +#: ../../library/enum.rst:138 +msgid ":func:`member`" +msgstr ":func:`member`" + +#: ../../library/enum.rst:140 +msgid "Make ``obj`` a member. Can be used as a decorator." +msgstr "讓 ``obj`` 變成成員。可以當作裝飾器使用。" + +#: ../../library/enum.rst:142 +msgid ":func:`nonmember`" +msgstr ":func:`nonmember`" + +#: ../../library/enum.rst:144 +msgid "Do not make ``obj`` a member. Can be used as a decorator." +msgstr "不讓 ``obj`` 變成成員。可以當作裝飾器使用。" + +#: ../../library/enum.rst:146 +msgid ":func:`global_enum`" +msgstr ":func:`global_enum`" + +#: ../../library/enum.rst:148 +msgid "" +"Modify the :class:`str() ` and :func:`repr` of an enum to show its " +"members as belonging to the module instead of its class, and export the enum " +"members to the global namespace." +msgstr "" +"修改列舉上的 :class:`str() ` 及 :func:`repr` ，讓成員顯示為屬於模組而不" +"是類別，並將該列舉成員匯出到全域命名空間。" + +#: ../../library/enum.rst:152 +msgid ":func:`show_flag_values`" +msgstr ":func:`show_flag_values`" + +#: ../../library/enum.rst:154 +msgid "Return a list of all power-of-two integers contained in a flag." +msgstr "回傳旗標 (flag) 裡包含的所有 2 的次方的整數串列。" + +#: ../../library/enum.rst:157 +msgid "``Flag``, ``IntFlag``, ``auto``" +msgstr "``Flag``, ``IntFlag``, ``auto``" + +#: ../../library/enum.rst:158 +msgid "" +"``StrEnum``, ``EnumCheck``, ``ReprEnum``, ``FlagBoundary``, ``property``, " +"``member``, ``nonmember``, ``global_enum``, ``show_flag_values``" +msgstr "" +"``StrEnum``, ``EnumCheck``, ``ReprEnum``, ``FlagBoundary``, ``property``, " +"``member``, ``nonmember``, ``global_enum``, ``show_flag_values``" + +#: ../../library/enum.rst:159 +msgid "``EnumDict``" +msgstr "``EnumDict``" + +#: ../../library/enum.rst:164 +msgid "Data Types" +msgstr "資料型別" + +#: ../../library/enum.rst:169 +msgid "" +"*EnumType* is the :term:`metaclass` for *enum* enumerations. It is possible " +"to subclass *EnumType* -- see :ref:`Subclassing EnumType ` for details." +msgstr "" +"*EnumType* 是 *enum* 列舉的 :term:`metaclass`。*EnumType* 可以有子類別 -- 細" +"節請參考 :ref:`建立 EnumType 的子類別 `。" + +#: ../../library/enum.rst:173 +msgid "" +"``EnumType`` is responsible for setting the correct :meth:`!__repr__`, :meth:" +"`!__str__`, :meth:`!__format__`, and :meth:`!__reduce__` methods on the " +"final *enum*, as well as creating the enum members, properly handling " +"duplicates, providing iteration over the enum class, etc." +msgstr "" +"``EnumType`` 負責在最後的\\ *列舉*\\ 上面設定正確的 :meth:`!__repr__`、:meth:" +"`!__str__`、:meth:`!__format__` 及 :meth:`!__reduce__` 方法，以及建立列舉成" +"員、正確處理重複、提供列舉類別的疊代等等。" + +#: ../../library/enum.rst:180 +msgid "" +"Before 3.11 ``EnumType`` was called ``EnumMeta``, which is still available " +"as an alias." +msgstr "在 3.11 之前，``EnumType`` 稱作 ``EnumMeta``，其目前仍可作為別名使用。" + +#: ../../library/enum.rst:184 +msgid "This method is called in two different ways:" +msgstr "這個方法可以用兩種不同的方式呼叫：" + +#: ../../library/enum.rst:186 +msgid "to look up an existing member:" +msgstr "查詢已存在的成員：" + +#: ../../library/enum.rst:0 +msgid "cls" +msgstr "cls" + +#: ../../library/enum.rst:188 ../../library/enum.rst:194 +msgid "The enum class being called." +msgstr "所呼叫的列舉類別。" + +#: ../../library/enum.rst:0 +msgid "value" +msgstr "value" + +#: ../../library/enum.rst:189 +msgid "The value to lookup." +msgstr "要查詢的值。" + +#: ../../library/enum.rst:191 +msgid "" +"to use the ``cls`` enum to create a new enum (only if the existing enum does " +"not have any members):" +msgstr "使用 ``cls`` 列舉來建立新列舉（只有在現有列舉沒有任何成員時）" + +#: ../../library/enum.rst:195 +msgid "The name of the new Enum to create." +msgstr "要建立的新列舉的名稱。" + +#: ../../library/enum.rst:0 +msgid "names" +msgstr "names" + +#: ../../library/enum.rst:196 +msgid "The names/values of the members for the new Enum." +msgstr "新列舉的成員的名稱/值。" + +#: ../../library/enum.rst:0 +msgid "module" +msgstr "module" + +#: ../../library/enum.rst:197 +msgid "The name of the module the new Enum is created in." +msgstr "新列舉要建立在哪個模組名稱下。" + +#: ../../library/enum.rst:0 +msgid "qualname" +msgstr "qualname" + +#: ../../library/enum.rst:198 +msgid "The actual location in the module where this Enum can be found." +msgstr "這個列舉在模組裡實際上的位置。" + +#: ../../library/enum.rst:0 +msgid "type" +msgstr "type" + +#: ../../library/enum.rst:199 +msgid "A mix-in type for the new Enum." +msgstr "新列舉的混合型別。" + +#: ../../library/enum.rst:0 +msgid "start" +msgstr "start" + +#: ../../library/enum.rst:200 +msgid "The first integer value for the Enum (used by :class:`auto`)." +msgstr "列舉的第一個整數值（由 :class:`auto` 所使用）" + +#: ../../library/enum.rst:0 +msgid "boundary" +msgstr "boundary" + +#: ../../library/enum.rst:201 +msgid "" +"How to handle out-of-range values from bit operations (:class:`Flag` only)." +msgstr "在位元操作時怎麼處理範圍外的值（只有 :class:`Flag` 會用到）" + +#: ../../library/enum.rst:205 +msgid "Returns ``True`` if member belongs to the ``cls``::" +msgstr "如果 member 屬於 ``cls`` 則回傳 ``True``： ::" + +#: ../../library/enum.rst:207 +msgid "" +">>> some_var = Color.RED\n" +">>> some_var in Color\n" +"True\n" +">>> Color.RED.value in Color\n" +"True" +msgstr "" +">>> some_var = Color.RED\n" +">>> some_var in Color\n" +"True\n" +">>> Color.RED.value in Color\n" +"True" + +#: ../../library/enum.rst:215 +msgid "" +"Before Python 3.12, a ``TypeError`` is raised if a non-Enum-member is used " +"in a containment check." +msgstr "" +"在 Python 3.12 之前，如果用非列舉成員做屬於檢查 (containment check) 會引發 " +"``TypeError``。" + +#: ../../library/enum.rst:220 +msgid "" +"Returns ``['__class__', '__doc__', '__members__', '__module__']`` and the " +"names of the members in *cls*::" +msgstr "" +"回傳 ``['__class__', '__doc__', '__members__', '__module__']`` 及 *cls* 的成" +"員名稱： ::" + +#: ../../library/enum.rst:223 +msgid "" +">>> dir(Color)\n" +"['BLUE', 'GREEN', 'RED', '__class__', '__contains__', '__doc__', " +"'__getitem__', '__init_subclass__', '__iter__', '__len__', '__members__', " +"'__module__', '__name__', '__qualname__']" +msgstr "" +">>> dir(Color)\n" +"['BLUE', 'GREEN', 'RED', '__class__', '__contains__', '__doc__', " +"'__getitem__', '__init_subclass__', '__iter__', '__len__', '__members__', " +"'__module__', '__name__', '__qualname__']" + +#: ../../library/enum.rst:228 +msgid "" +"Returns the Enum member in *cls* matching *name*, or raises a :exc:" +"`KeyError`::" +msgstr "回傳 *cls* 中符合 *name* 的列舉成員，或引發 :exc:`KeyError`： ::" + +#: ../../library/enum.rst:230 +msgid "" +">>> Color['BLUE']\n" +"" +msgstr "" +">>> Color['BLUE']\n" +"" + +#: ../../library/enum.rst:235 +msgid "Returns each member in *cls* in definition order::" +msgstr "以定義的順序回傳在 *cls* 中的每個成員： ::" + +#: ../../library/enum.rst:237 +msgid "" +">>> list(Color)\n" +"[, , ]" +msgstr "" +">>> list(Color)\n" +"[, , ]" + +#: ../../library/enum.rst:242 +msgid "Returns the number of member in *cls*::" +msgstr "回傳 *cls* 的成員數量： ::" + +#: ../../library/enum.rst:244 +msgid "" +">>> len(Color)\n" +"3" +msgstr "" +">>> len(Color)\n" +"3" + +#: ../../library/enum.rst:249 +msgid "Returns a mapping of every enum name to its member, including aliases" +msgstr "回傳每個列舉名稱到其成員的對映，包括別名" + +#: ../../library/enum.rst:253 +msgid "Returns each member in *cls* in reverse definition order::" +msgstr "以跟定義相反的順序回傳 *cls* 的每個成員： ::" + +#: ../../library/enum.rst:255 +msgid "" +">>> list(reversed(Color))\n" +"[, , ]" +msgstr "" +">>> list(reversed(Color))\n" +"[, , ]" + +#: ../../library/enum.rst:261 +msgid "*Enum* is the base class for all *enum* enumerations." +msgstr "*Enum* 是所有 *enum* 列舉的基礎類別。" + +#: ../../library/enum.rst:265 +msgid "The name used to define the ``Enum`` member::" +msgstr "用來定義 ``Enum`` 成員的名稱： ::" + +#: ../../library/enum.rst:267 +msgid "" +">>> Color.BLUE.name\n" +"'BLUE'" +msgstr "" +">>> Color.BLUE.name\n" +"'BLUE'" + +#: ../../library/enum.rst:272 +msgid "The value given to the ``Enum`` member::" +msgstr "``Enum`` 成員給定的值： ::" + +#: ../../library/enum.rst:274 +msgid "" +">>> Color.RED.value\n" +"1" +msgstr "" +">>> Color.RED.value\n" +"1" + +#: ../../library/enum.rst:277 ../../library/enum.rst:297 +msgid "Value of the member, can be set in :meth:`~Enum.__new__`." +msgstr "成員的值，可以在 :meth:`~Enum.__new__` 設定。" + +#: ../../library/enum.rst:279 +msgid "Enum member values" +msgstr "列舉成員的值" + +#: ../../library/enum.rst:281 +msgid "" +"Member values can be anything: :class:`int`, :class:`str`, etc. If the " +"exact value is unimportant you may use :class:`auto` instances and an " +"appropriate value will be chosen for you. See :class:`auto` for the details." +msgstr "" +"成員的值可以是任何值：:class:`int`、:class:`str` 等等。如果實際使用什麼值並不" +"重要，你可以使用 :class:`auto` 實例，它會為你選擇合適的值。更多細節請參考 :" +"class:`auto`。" + +#: ../../library/enum.rst:286 +msgid "" +"While mutable/unhashable values, such as :class:`dict`, :class:`list` or a " +"mutable :class:`~dataclasses.dataclass`, can be used, they will have a " +"quadratic performance impact during creation relative to the total number of " +"mutable/unhashable values in the enum." +msgstr "" +"雖然可以使用可變的 (mutable) / 不可雜湊的 (unhashable) 值，例如 :class:" +"`dict`、:class:`list` 或可變的 :class:`~dataclasses.dataclass`，它們在建立期" +"間會對效能產生相對於列舉中可變的 / 不可雜湊的值總數量的二次方影響。" + +#: ../../library/enum.rst:293 +msgid "Name of the member." +msgstr "成員名稱。" + +#: ../../library/enum.rst:301 +msgid "" +"No longer used, kept for backward compatibility. (class attribute, removed " +"during class creation)." +msgstr "已不再使用，只為了向後相容而保留（類別屬性，在類別建立時移除）" + +#: ../../library/enum.rst:306 +msgid "" +"``_ignore_`` is only used during creation and is removed from the " +"enumeration once creation is complete." +msgstr "``_ignore_`` 只有在建立的時候用到，在列舉建立完成後會被移除。" + +#: ../../library/enum.rst:309 +msgid "" +"``_ignore_`` is a list of names that will not become members, and whose " +"names will also be removed from the completed enumeration. See :ref:" +"`TimePeriod ` for an example." +msgstr "" +"``_ignore_`` 是一個不會變成成員的名稱串列，在列舉建立完成後其名稱會被移除。範" +"例請參考 :ref:`TimePeriod `。" + +#: ../../library/enum.rst:315 +msgid "" +"Returns ``['__class__', '__doc__', '__module__', 'name', 'value']`` and any " +"public methods defined on *self.__class__*::" +msgstr "" +"回傳 ``['__class__', '__doc__', '__module__', 'name', 'value']`` 及任何 " +"*self.__class__* 上定義的公開方法： ::" + +#: ../../library/enum.rst:318 +msgid "" +">>> from enum import Enum\n" +">>> from datetime import date\n" +">>> class Weekday(Enum):\n" +"... MONDAY = 1\n" +"... TUESDAY = 2\n" +"... WEDNESDAY = 3\n" +"... THURSDAY = 4\n" +"... FRIDAY = 5\n" +"... SATURDAY = 6\n" +"... SUNDAY = 7\n" +"... @classmethod\n" +"... def today(cls):\n" +"... print('today is %s' % cls(date.today().isoweekday()).name)\n" +"...\n" +">>> dir(Weekday.SATURDAY)\n" +"['__class__', '__doc__', '__eq__', '__hash__', '__module__', 'name', " +"'today', 'value']" +msgstr "" +">>> from enum import Enum\n" +">>> from datetime import date\n" +">>> class Weekday(Enum):\n" +"... MONDAY = 1\n" +"... TUESDAY = 2\n" +"... WEDNESDAY = 3\n" +"... THURSDAY = 4\n" +"... FRIDAY = 5\n" +"... SATURDAY = 6\n" +"... SUNDAY = 7\n" +"... @classmethod\n" +"... def today(cls):\n" +"... print('today is %s' % cls(date.today().isoweekday()).name)\n" +"...\n" +">>> dir(Weekday.SATURDAY)\n" +"['__class__', '__doc__', '__eq__', '__hash__', '__module__', 'name', " +"'today', 'value']" + +#: ../../library/enum.rst:0 +msgid "name" +msgstr "name" + +#: ../../library/enum.rst:337 +msgid "The name of the member being defined (e.g. 'RED')." +msgstr "定義的成員名稱（例如 'RED'）。" + +#: ../../library/enum.rst:338 +msgid "The start value for the Enum; the default is 1." +msgstr "列舉的開始值，預設為 1。" + +#: ../../library/enum.rst:0 +msgid "count" +msgstr "count" + +#: ../../library/enum.rst:339 +msgid "The number of members currently defined, not including this one." +msgstr "已定義的成員數量，不包含目前這一個。" + +#: ../../library/enum.rst:0 +msgid "last_values" +msgstr "last_values" + +#: ../../library/enum.rst:340 +msgid "A list of the previous values." +msgstr "一個之前值的串列。" + +#: ../../library/enum.rst:342 +msgid "" +"A *staticmethod* that is used to determine the next value returned by :class:" +"`auto`::" +msgstr "一個 *staticmethod*，用來決定 :class:`auto` 下一個要回傳的值的： ::" + +#: ../../library/enum.rst:345 +msgid "" +">>> from enum import auto, Enum\n" +">>> class PowersOfThree(Enum):\n" +"... @staticmethod\n" +"... def _generate_next_value_(name, start, count, last_values):\n" +"... return 3 ** (count + 1)\n" +"... FIRST = auto()\n" +"... SECOND = auto()\n" +"...\n" +">>> PowersOfThree.SECOND.value\n" +"9" +msgstr "" +">>> from enum import auto, Enum\n" +">>> class PowersOfThree(Enum):\n" +"... @staticmethod\n" +"... def _generate_next_value_(name, start, count, last_values):\n" +"... return 3 ** (count + 1)\n" +"... FIRST = auto()\n" +"... SECOND = auto()\n" +"...\n" +">>> PowersOfThree.SECOND.value\n" +"9" + +#: ../../library/enum.rst:358 +msgid "" +"By default, does nothing. If multiple values are given in the member " +"assignment, those values become separate arguments to ``__init__``; e.g." +msgstr "" +"預設情況下，不執行任何操作。如果在成員賦值中給出多個值，這些值將成為與 " +"``__init__`` 分別的引數；例如" + +#: ../../library/enum.rst:365 +msgid "" +"``Weekday.__init__()`` would be called as ``Weekday.__init__(self, 1, " +"'Mon')``" +msgstr "``Weekday.__init__()`` 將被稱為 ``Weekday.__init__(self, 1, 'Mon')``" + +#: ../../library/enum.rst:369 +msgid "" +"A *classmethod* that is used to further configure subsequent subclasses. By " +"default, does nothing." +msgstr "一個 *classmethod*，用來進一步設定後續的子類別，預設不做任何事。" + +#: ../../library/enum.rst:374 +msgid "" +"A *classmethod* for looking up values not found in *cls*. By default it " +"does nothing, but can be overridden to implement custom search behavior::" +msgstr "" +"一個 *classmethod*，用來查詢在 *cls* 裡找不到的值。預設不做任何事，但可以被覆" +"寫以實作客製化的搜尋行為： ::" + +#: ../../library/enum.rst:377 +msgid "" +">>> from enum import auto, StrEnum\n" +">>> class Build(StrEnum):\n" +"... DEBUG = auto()\n" +"... OPTIMIZED = auto()\n" +"... @classmethod\n" +"... def _missing_(cls, value):\n" +"... value = value.lower()\n" +"... for member in cls:\n" +"... if member.value == value:\n" +"... return member\n" +"... return None\n" +"...\n" +">>> Build.DEBUG.value\n" +"'debug'\n" +">>> Build('deBUG')\n" +"" +msgstr "" +">>> from enum import auto, StrEnum\n" +">>> class Build(StrEnum):\n" +"... DEBUG = auto()\n" +"... OPTIMIZED = auto()\n" +"... @classmethod\n" +"... def _missing_(cls, value):\n" +"... value = value.lower()\n" +"... for member in cls:\n" +"... if member.value == value:\n" +"... return member\n" +"... return None\n" +"...\n" +">>> Build.DEBUG.value\n" +"'debug'\n" +">>> Build('deBUG')\n" +"" + +#: ../../library/enum.rst:396 +msgid "" +"By default, doesn't exist. If specified, either in the enum class " +"definition or in a mixin class (such as ``int``), all values given in the " +"member assignment will be passed; e.g." +msgstr "" +"預設情況下不存在。如果有指定，無論是在列舉類別定義中還是在 mixin 類別中（例" +"如 ``int``\\ ），都將傳遞成員賦值中給出的所有值；例如" + +#: ../../library/enum.rst:404 +msgid "" +"results in the call ``int('1a', 16)`` and a value of ``26`` for the member." +msgstr "會產生呼叫 ``int('1a', 16)`` 而該成員的值為 ``26``。" + +#: ../../library/enum.rst:408 +msgid "" +"When writing a custom ``__new__``, do not use ``super().__new__`` -- call " +"the appropriate ``__new__`` instead." +msgstr "" +"當寫自訂的 ``__new__`` 時，不要使用 ``super().__new__``，而是要呼叫適當的 " +"``__new__``。" + +#: ../../library/enum.rst:413 +msgid "" +"Returns the string used for *repr()* calls. By default, returns the *Enum* " +"name, member name, and value, but can be overridden::" +msgstr "" +"回傳呼叫 *repr()* 時使用的字串。預設回傳 *Enum* 名稱、成員名稱及值，但可以被" +"覆寫： ::" + +#: ../../library/enum.rst:416 +msgid "" +">>> from enum import auto, Enum\n" +">>> class OtherStyle(Enum):\n" +"... ALTERNATE = auto()\n" +"... OTHER = auto()\n" +"... SOMETHING_ELSE = auto()\n" +"... def __repr__(self):\n" +"... cls_name = self.__class__.__name__\n" +"... return f'{cls_name}.{self.name}'\n" +"...\n" +">>> OtherStyle.ALTERNATE, str(OtherStyle.ALTERNATE), f\"{OtherStyle." +"ALTERNATE}\"\n" +"(OtherStyle.ALTERNATE, 'OtherStyle.ALTERNATE', 'OtherStyle.ALTERNATE')" +msgstr "" +">>> from enum import auto, Enum\n" +">>> class OtherStyle(Enum):\n" +"... ALTERNATE = auto()\n" +"... OTHER = auto()\n" +"... SOMETHING_ELSE = auto()\n" +"... def __repr__(self):\n" +"... cls_name = self.__class__.__name__\n" +"... return f'{cls_name}.{self.name}'\n" +"...\n" +">>> OtherStyle.ALTERNATE, str(OtherStyle.ALTERNATE), f\"{OtherStyle." +"ALTERNATE}\"\n" +"(OtherStyle.ALTERNATE, 'OtherStyle.ALTERNATE', 'OtherStyle.ALTERNATE')" + +#: ../../library/enum.rst:430 +msgid "" +"Returns the string used for *str()* calls. By default, returns the *Enum* " +"name and member name, but can be overridden::" +msgstr "" +"回傳呼叫 *str()* 時使用的字串。預設回傳 *Enum* 名稱及成員名稱，但可以被覆" +"寫： ::" + +#: ../../library/enum.rst:433 +msgid "" +">>> from enum import auto, Enum\n" +">>> class OtherStyle(Enum):\n" +"... ALTERNATE = auto()\n" +"... OTHER = auto()\n" +"... SOMETHING_ELSE = auto()\n" +"... def __str__(self):\n" +"... return f'{self.name}'\n" +"...\n" +">>> OtherStyle.ALTERNATE, str(OtherStyle.ALTERNATE), f\"{OtherStyle." +"ALTERNATE}\"\n" +"(, 'ALTERNATE', 'ALTERNATE')" +msgstr "" +">>> from enum import auto, Enum\n" +">>> class OtherStyle(Enum):\n" +"... ALTERNATE = auto()\n" +"... OTHER = auto()\n" +"... SOMETHING_ELSE = auto()\n" +"... def __str__(self):\n" +"... return f'{self.name}'\n" +"...\n" +">>> OtherStyle.ALTERNATE, str(OtherStyle.ALTERNATE), f\"{OtherStyle." +"ALTERNATE}\"\n" +"(, 'ALTERNATE', 'ALTERNATE')" + +#: ../../library/enum.rst:446 +msgid "" +"Returns the string used for *format()* and *f-string* calls. By default, " +"returns :meth:`__str__` return value, but can be overridden::" +msgstr "" +"回傳呼叫 *format()* 及 *f-string* 時使用的字串。預設回傳 :meth:`__str__` 的回" +"傳值，但可以被覆寫： ::" + +#: ../../library/enum.rst:449 +msgid "" +">>> from enum import auto, Enum\n" +">>> class OtherStyle(Enum):\n" +"... ALTERNATE = auto()\n" +"... OTHER = auto()\n" +"... SOMETHING_ELSE = auto()\n" +"... def __format__(self, spec):\n" +"... return f'{self.name}'\n" +"...\n" +">>> OtherStyle.ALTERNATE, str(OtherStyle.ALTERNATE), f\"{OtherStyle." +"ALTERNATE}\"\n" +"(, 'OtherStyle.ALTERNATE', 'ALTERNATE')" +msgstr "" +">>> from enum import auto, Enum\n" +">>> class OtherStyle(Enum):\n" +"... ALTERNATE = auto()\n" +"... OTHER = auto()\n" +"... SOMETHING_ELSE = auto()\n" +"... def __format__(self, spec):\n" +"... return f'{self.name}'\n" +"...\n" +">>> OtherStyle.ALTERNATE, str(OtherStyle.ALTERNATE), f\"{OtherStyle." +"ALTERNATE}\"\n" +"(, 'OtherStyle.ALTERNATE', 'ALTERNATE')" + +#: ../../library/enum.rst:462 +msgid "" +"Using :class:`auto` with :class:`Enum` results in integers of increasing " +"value, starting with ``1``." +msgstr ":class:`Enum` 使用 :class:`auto` 會產生從 ``1`` 開始遞增的整數。" + +#: ../../library/enum.rst:465 +msgid "Added :ref:`enum-dataclass-support`" +msgstr "新增 :ref:`enum-dataclass-support`" + +#: ../../library/enum.rst:469 +msgid "Adds a new name as an alias to an existing member::" +msgstr "新增一個名稱作為現有成員的別名： ::" + +#: ../../library/enum.rst:471 +msgid "" +">>> Color.RED._add_alias_(\"ERROR\")\n" +">>> Color.ERROR\n" +"" +msgstr "" +">>> Color.RED._add_alias_(\"ERROR\")\n" +">>> Color.ERROR\n" +"" + +#: ../../library/enum.rst:475 +msgid "" +"Raises a :exc:`NameError` if the name is already assigned to a different " +"member." +msgstr "如果該名稱已經被指派給不同的成員，則會引發 :exc:`NameError`。" + +#: ../../library/enum.rst:481 +msgid "Adds a new value as an alias to an existing member::" +msgstr "新增一個值作為現有成員的別名： ::" + +#: ../../library/enum.rst:483 +msgid "" +">>> Color.RED._add_value_alias_(42)\n" +">>> Color(42)\n" +"" +msgstr "" +">>> Color.RED._add_value_alias_(42)\n" +">>> Color(42)\n" +"" + +#: ../../library/enum.rst:487 +msgid "" +"Raises a :exc:`ValueError` if the value is already linked with a different " +"member." +msgstr "如果該值已經被連結到不同的成員，則會引發 :exc:`ValueError`。" + +#: ../../library/enum.rst:494 +msgid "" +"*IntEnum* is the same as :class:`Enum`, but its members are also integers " +"and can be used anywhere that an integer can be used. If any integer " +"operation is performed with an *IntEnum* member, the resulting value loses " +"its enumeration status." +msgstr "" +"*IntEnum* 和 :class:`Enum` 一樣，但其成員同時也是整數而可以被用在任何使用整數" +"的地方。如果 *IntEnum* 成員經過任何整數運算，結果值會失去其列舉狀態。" + +#: ../../library/enum.rst:515 +msgid "" +"Using :class:`auto` with :class:`IntEnum` results in integers of increasing " +"value, starting with ``1``." +msgstr ":class:`IntEnum` 使用 :class:`auto` 會產生從 ``1`` 開始遞增的整數。" + +#: ../../library/enum.rst:518 +msgid "" +":meth:`~object.__str__` is now :meth:`!int.__str__` to better support the " +"*replacement of existing constants* use-case. :meth:`~object.__format__` was " +"already :meth:`!int.__format__` for that same reason." +msgstr "" +"為了更好地支援\\ *現存常數取代 (replacement of existing constants)* 的使用情" +"境，:meth:`~object.__str__` 現在會是 :meth:`!int.__str__`。為了同樣的理由，:" +"meth:`~object.__format__` 已經是 :meth:`!int.__format__`。" + +#: ../../library/enum.rst:525 +msgid "" +"*StrEnum* is the same as :class:`Enum`, but its members are also strings and " +"can be used in most of the same places that a string can be used. The result " +"of any string operation performed on or with a *StrEnum* member is not part " +"of the enumeration." +msgstr "" +"*StrEnum* 和 :class:`Enum` 一樣，但其成員同時也是字串而可以被用在幾乎所有使用" +"字串的地方。*StrEnum* 成員經過任何字串操作的結果會不再是列舉的一部份。" + +#: ../../library/enum.rst:546 +msgid "" +"There are places in the stdlib that check for an exact :class:`str` instead " +"of a :class:`str` subclass (i.e. ``type(unknown) == str`` instead of " +"``isinstance(unknown, str)``), and in those locations you will need to use " +"``str(MyStrEnum.MY_MEMBER)``." +msgstr "" +"stdlib 裡有些地方會檢查只能是 :class:`str` 而不是 :class:`str` 的子類別（也就" +"是 ``type(unknown) == str`` 而不是 ``isinstance(unknown, str)``），在這些地方" +"你需要使用 ``str(MyStrEnum.MY_MEMBER)``。" + +#: ../../library/enum.rst:553 +msgid "" +"Using :class:`auto` with :class:`StrEnum` results in the lower-cased member " +"name as the value." +msgstr ":class:`StrEnum` 使用 :class:`auto` 會產生小寫的成員名稱當作值。" + +#: ../../library/enum.rst:558 +msgid "" +":meth:`~object.__str__` is :meth:`!str.__str__` to better support the " +"*replacement of existing constants* use-case. :meth:`~object.__format__` is " +"likewise :meth:`!str.__format__` for that same reason." +msgstr "" +"為了更好地支援\\ *現存常數取代 (replacement of existing constants)* 的使用情" +"境，:meth:`~object.__str__` 現在會是 :meth:`!str.__str__`。為了同樣的理由，:" +"meth:`~object.__format__` 也會是 :meth:`!str.__format__`。" + +#: ../../library/enum.rst:566 +msgid "" +"``Flag`` is the same as :class:`Enum`, but its members support the bitwise " +"operators ``&`` (*AND*), ``|`` (*OR*), ``^`` (*XOR*), and ``~`` (*INVERT*); " +"the results of those operations are (aliases of) members of the enumeration." +msgstr "" +"``Flag`` 與 :class:`Enum` 相同，但其成員支援位元運算子 ``&`` (*AND*)、``|`` " +"(*OR*)、``^`` (*XOR*) 和 ``~`` (*INVERT*)；這些操作的結果是列舉的成員（的別" +"名）。" + +#: ../../library/enum.rst:572 +msgid "Returns *True* if value is in self::" +msgstr "如果 value 在 self 裡則回傳 *True*： ::" + +#: ../../library/enum.rst:574 +msgid "" +">>> from enum import Flag, auto\n" +">>> class Color(Flag):\n" +"... RED = auto()\n" +"... GREEN = auto()\n" +"... BLUE = auto()\n" +"...\n" +">>> purple = Color.RED | Color.BLUE\n" +">>> white = Color.RED | Color.GREEN | Color.BLUE\n" +">>> Color.GREEN in purple\n" +"False\n" +">>> Color.GREEN in white\n" +"True\n" +">>> purple in white\n" +"True\n" +">>> white in purple\n" +"False" +msgstr "" +">>> from enum import Flag, auto\n" +">>> class Color(Flag):\n" +"... RED = auto()\n" +"... GREEN = auto()\n" +"... BLUE = auto()\n" +"...\n" +">>> purple = Color.RED | Color.BLUE\n" +">>> white = Color.RED | Color.GREEN | Color.BLUE\n" +">>> Color.GREEN in purple\n" +"False\n" +">>> Color.GREEN in white\n" +"True\n" +">>> purple in white\n" +"True\n" +">>> white in purple\n" +"False" + +#: ../../library/enum.rst:593 +msgid "Returns all contained non-alias members::" +msgstr "回傳所有包含的非別名成員： ::" + +#: ../../library/enum.rst:595 +msgid "" +">>> list(Color.RED)\n" +"[]\n" +">>> list(purple)\n" +"[, ]" +msgstr "" +">>> list(Color.RED)\n" +"[]\n" +">>> list(purple)\n" +"[, ]" + +#: ../../library/enum.rst:604 +msgid "Returns number of members in flag::" +msgstr "回傳旗標裡的成員數量： ::" + +#: ../../library/enum.rst:606 +msgid "" +">>> len(Color.GREEN)\n" +"1\n" +">>> len(white)\n" +"3" +msgstr "" +">>> len(Color.GREEN)\n" +"1\n" +">>> len(white)\n" +"3" + +#: ../../library/enum.rst:615 +msgid "Returns *True* if any members in flag, *False* otherwise::" +msgstr "如果成員在旗標裡則回傳 *True*，否則回傳 *False*： ::" + +#: ../../library/enum.rst:617 +msgid "" +">>> bool(Color.GREEN)\n" +"True\n" +">>> bool(white)\n" +"True\n" +">>> black = Color(0)\n" +">>> bool(black)\n" +"False" +msgstr "" +">>> bool(Color.GREEN)\n" +"True\n" +">>> bool(white)\n" +"True\n" +">>> black = Color(0)\n" +">>> bool(black)\n" +"False" + +#: ../../library/enum.rst:627 +msgid "Returns current flag binary or'ed with other::" +msgstr "回傳和 other 做 OR 過後的二進位旗標： ::" + +#: ../../library/enum.rst:629 +msgid "" +">>> Color.RED | Color.GREEN\n" +"" +msgstr "" +">>> Color.RED | Color.GREEN\n" +"" + +#: ../../library/enum.rst:634 +msgid "Returns current flag binary and'ed with other::" +msgstr "回傳和 other 做 AND 過後的二進位旗標： ::" + +#: ../../library/enum.rst:636 +msgid "" +">>> purple & white\n" +"\n" +">>> purple & Color.GREEN\n" +"" +msgstr "" +">>> purple & white\n" +"\n" +">>> purple & Color.GREEN\n" +"" + +#: ../../library/enum.rst:643 +msgid "Returns current flag binary xor'ed with other::" +msgstr "回傳和 other 做 XOR 過後的二進位旗標： ::" + +#: ../../library/enum.rst:645 +msgid "" +">>> purple ^ white\n" +"\n" +">>> purple ^ Color.GREEN\n" +"" +msgstr "" +">>> purple ^ white\n" +"\n" +">>> purple ^ Color.GREEN\n" +"" + +#: ../../library/enum.rst:652 +msgid "Returns all the flags in *type(self)* that are not in *self*::" +msgstr "回傳所有在 *type(self)* 但不在 *self* 裡的旗標： ::" + +#: ../../library/enum.rst:654 +msgid "" +">>> ~white\n" +"\n" +">>> ~purple\n" +"\n" +">>> ~Color.RED\n" +"" +msgstr "" +">>> ~white\n" +"\n" +">>> ~purple\n" +"\n" +">>> ~Color.RED\n" +"" + +#: ../../library/enum.rst:663 +msgid "" +"Function used to format any remaining unnamed numeric values. Default is " +"the value's repr; common choices are :func:`hex` and :func:`oct`." +msgstr "" +"用來格式化任何剩下未命名數值的函式。預設是值的 repr，常見選擇是 :func:`hex` " +"和 :func:`oct`。" + +#: ../../library/enum.rst:668 +msgid "" +"Using :class:`auto` with :class:`Flag` results in integers that are powers " +"of two, starting with ``1``." +msgstr ":class:`Flag` 使用 :class:`auto` 會產生從 ``1`` 開始 2 的次方的整數。" + +#: ../../library/enum.rst:671 +msgid "The *repr()* of zero-valued flags has changed. It is now:" +msgstr "值為 0 的旗標的 *repr()* 已改變。現在是：" + +#: ../../library/enum.rst:679 +msgid "" +"``IntFlag`` is the same as :class:`Flag`, but its members are also integers " +"and can be used anywhere that an integer can be used." +msgstr "" +"``IntFlag`` 和 :class:`Flag` 一樣，但其成員同時也是整數而可以被用在任何使用整" +"數的地方。" + +#: ../../library/enum.rst:693 +msgid "" +"If any integer operation is performed with an *IntFlag* member, the result " +"is not an *IntFlag*::" +msgstr "如果 *IntFlag* 成員經過任何整數運算，其結果不是 *IntFlag*： ::" + +#: ../../library/enum.rst:696 +msgid "" +">>> Color.RED + 2\n" +"3" +msgstr "" +">>> Color.RED + 2\n" +"3" + +#: ../../library/enum.rst:699 +msgid "If a :class:`Flag` operation is performed with an *IntFlag* member and:" +msgstr "如果 *IntFlag* 成員經過 :class:`Flag` 操作且：" + +#: ../../library/enum.rst:701 +msgid "the result is a valid *IntFlag*: an *IntFlag* is returned" +msgstr "結果是合法的 *IntFlag*：回傳 *IntFlag*" + +#: ../../library/enum.rst:702 +msgid "" +"the result is not a valid *IntFlag*: the result depends on the :class:" +"`FlagBoundary` setting" +msgstr "結果不是合法的 *IntFlag*：結果會根據 :class:`FlagBoundary` 的設定" + +#: ../../library/enum.rst:704 +msgid "The :func:`repr` of unnamed zero-valued flags has changed. It is now::" +msgstr "未命名且值為 0 的旗標的 :func:`repr` 已改變。現在是： ::" + +#: ../../library/enum.rst:706 +msgid "" +">>> Color(0)\n" +"" +msgstr "" +">>> Color(0)\n" +"" + +#: ../../library/enum.rst:711 +msgid "" +"Using :class:`auto` with :class:`IntFlag` results in integers that are " +"powers of two, starting with ``1``." +msgstr "" +":class:`IntFlag` 使用 :class:`auto` 會產生從 ``1`` 開始 2 的次方的整數。" + +#: ../../library/enum.rst:716 +msgid "" +":meth:`~object.__str__` is now :meth:`!int.__str__` to better support the " +"*replacement of existing constants* use-case. :meth:`~object.__format__` " +"was already :meth:`!int.__format__` for that same reason." +msgstr "" +"為了更好地支援\\ *現存常數取代 (replacement of existing constants)* 的使用情" +"境，:meth:`~object.__str__` 現在會是 :meth:`!int.__str__`。為了同樣的理由，:" +"meth:`~object.__format__` 已經是 :meth:`!int.__format__`。" + +#: ../../library/enum.rst:720 +msgid "" +"Inversion of an :class:`!IntFlag` now returns a positive value that is the " +"union of all flags not in the given flag, rather than a negative value. This " +"matches the existing :class:`Flag` behavior." +msgstr "" +":class:`!IntFlag` 的反轉 (inversion) 現在會回傳正值，該值是不在給定旗標的所有" +"旗標聯集，而不是一個負值。這符合現有 :class:`Flag` 的行為。" + +#: ../../library/enum.rst:726 +msgid "" +":class:`!ReprEnum` uses the :meth:`repr() ` of :class:`Enum`, " +"but the :class:`str() ` of the mixed-in data type:" +msgstr "" +":class:`!ReprEnum` 使用 :class:`Enum` 的 :meth:`repr() `，但使" +"用混合資料型別的 :class:`str() `：" + +#: ../../library/enum.rst:729 +msgid ":meth:`!int.__str__` for :class:`IntEnum` and :class:`IntFlag`" +msgstr "對 :class:`IntEnum` 和 :class:`IntFlag` 是 :meth:`!int.__str__`" + +#: ../../library/enum.rst:730 +msgid ":meth:`!str.__str__` for :class:`StrEnum`" +msgstr "對 :class:`StrEnum` 是 :meth:`!str.__str__`" + +#: ../../library/enum.rst:732 +msgid "" +"Inherit from :class:`!ReprEnum` to keep the :class:`str() ` / :func:" +"`format` of the mixed-in data type instead of using the :class:`Enum`-" +"default :meth:`str() `." +msgstr "" +"繼承 :class:`!ReprEnum` 來保留混合資料型別的 :class:`str() ` / :func:" +"`format`，而不是使用 :class:`Enum` 預設的 :meth:`str() `。" + +#: ../../library/enum.rst:741 +msgid "" +"*EnumCheck* contains the options used by the :func:`verify` decorator to " +"ensure various constraints; failed constraints result in a :exc:`ValueError`." +msgstr "" +"*EnumCheck* 包含 :func:`verify` 裝飾器使用的選項，以確保多樣的限制，不符合限" +"制會產生 :exc:`ValueError`。" + +#: ../../library/enum.rst:746 +msgid "Ensure that each value has only one name::" +msgstr "確保每個值只有一個名稱： ::" + +#: ../../library/enum.rst:748 +msgid "" +">>> from enum import Enum, verify, UNIQUE\n" +">>> @verify(UNIQUE)\n" +"... class Color(Enum):\n" +"... RED = 1\n" +"... GREEN = 2\n" +"... BLUE = 3\n" +"... CRIMSON = 1\n" +"Traceback (most recent call last):\n" +"...\n" +"ValueError: aliases found in : CRIMSON -> RED" +msgstr "" +">>> from enum import Enum, verify, UNIQUE\n" +">>> @verify(UNIQUE)\n" +"... class Color(Enum):\n" +"... RED = 1\n" +"... GREEN = 2\n" +"... BLUE = 3\n" +"... CRIMSON = 1\n" +"Traceback (most recent call last):\n" +"...\n" +"ValueError: aliases found in : CRIMSON -> RED" + +#: ../../library/enum.rst:762 +msgid "" +"Ensure that there are no missing values between the lowest-valued member and " +"the highest-valued member::" +msgstr "確保在最小值成員跟最大值成員間沒有缺少值： ::" + +#: ../../library/enum.rst:765 +msgid "" +">>> from enum import Enum, verify, CONTINUOUS\n" +">>> @verify(CONTINUOUS)\n" +"... class Color(Enum):\n" +"... RED = 1\n" +"... GREEN = 2\n" +"... BLUE = 5\n" +"Traceback (most recent call last):\n" +"...\n" +"ValueError: invalid enum 'Color': missing values 3, 4" +msgstr "" +">>> from enum import Enum, verify, CONTINUOUS\n" +">>> @verify(CONTINUOUS)\n" +"... class Color(Enum):\n" +"... RED = 1\n" +"... GREEN = 2\n" +"... BLUE = 5\n" +"Traceback (most recent call last):\n" +"...\n" +"ValueError: invalid enum 'Color': missing values 3, 4" + +#: ../../library/enum.rst:777 +msgid "" +"Ensure that any flag groups/masks contain only named flags -- useful when " +"values are specified instead of being generated by :func:`auto`::" +msgstr "" +"確保任何旗標群組 / 遮罩只包含命名旗標 -- 當值是用指定而不是透過 :func:`auto` " +"產生時是很實用的： ::" + +#: ../../library/enum.rst:780 +msgid "" +">>> from enum import Flag, verify, NAMED_FLAGS\n" +">>> @verify(NAMED_FLAGS)\n" +"... class Color(Flag):\n" +"... RED = 1\n" +"... GREEN = 2\n" +"... BLUE = 4\n" +"... WHITE = 15\n" +"... NEON = 31\n" +"Traceback (most recent call last):\n" +"...\n" +"ValueError: invalid Flag 'Color': aliases WHITE and NEON are missing " +"combined values of 0x18 [use enum.show_flag_values(value) for details]" +msgstr "" +">>> from enum import Flag, verify, NAMED_FLAGS\n" +">>> @verify(NAMED_FLAGS)\n" +"... class Color(Flag):\n" +"... RED = 1\n" +"... GREEN = 2\n" +"... BLUE = 4\n" +"... WHITE = 15\n" +"... NEON = 31\n" +"Traceback (most recent call last):\n" +"...\n" +"ValueError: invalid Flag 'Color': aliases WHITE and NEON are missing " +"combined values of 0x18 [use enum.show_flag_values(value) for details]" + +#: ../../library/enum.rst:794 +msgid "" +"CONTINUOUS and NAMED_FLAGS are designed to work with integer-valued members." +msgstr "CONTINUOUS 和 NAMED_FLAGS 是設計用來運作在整數值的成員上。" + +#: ../../library/enum.rst:800 +msgid "" +"``FlagBoundary`` controls how out-of-range values are handled in :class:" +"`Flag` and its subclasses." +msgstr "``FlagBoundary`` 控制在 :class:`Flag` 及其子類別中如何處理範圍外的值。" + +#: ../../library/enum.rst:805 +msgid "" +"Out-of-range values cause a :exc:`ValueError` to be raised. This is the " +"default for :class:`Flag`::" +msgstr "範圍外的值會引發 :exc:`ValueError`。這是 :class:`Flag` 的預設行為： ::" + +#: ../../library/enum.rst:808 +msgid "" +">>> from enum import Flag, STRICT, auto\n" +">>> class StrictFlag(Flag, boundary=STRICT):\n" +"... RED = auto()\n" +"... GREEN = auto()\n" +"... BLUE = auto()\n" +"...\n" +">>> StrictFlag(2**2 + 2**4)\n" +"Traceback (most recent call last):\n" +"...\n" +"ValueError: invalid value 20\n" +" given 0b0 10100\n" +" allowed 0b0 00111" +msgstr "" +">>> from enum import Flag, STRICT, auto\n" +">>> class StrictFlag(Flag, boundary=STRICT):\n" +"... RED = auto()\n" +"... GREEN = auto()\n" +"... BLUE = auto()\n" +"...\n" +">>> StrictFlag(2**2 + 2**4)\n" +"Traceback (most recent call last):\n" +"...\n" +"ValueError: invalid value 20\n" +" given 0b0 10100\n" +" allowed 0b0 00111" + +#: ../../library/enum.rst:823 +msgid "" +"Out-of-range values have invalid values removed, leaving a valid :class:" +"`Flag` value::" +msgstr "會移除範圍外的值中的非法值，留下合法的 :class:`Flag` 值： ::" + +#: ../../library/enum.rst:826 +msgid "" +">>> from enum import Flag, CONFORM, auto\n" +">>> class ConformFlag(Flag, boundary=CONFORM):\n" +"... RED = auto()\n" +"... GREEN = auto()\n" +"... BLUE = auto()\n" +"...\n" +">>> ConformFlag(2**2 + 2**4)\n" +"" +msgstr "" +">>> from enum import Flag, CONFORM, auto\n" +">>> class ConformFlag(Flag, boundary=CONFORM):\n" +"... RED = auto()\n" +"... GREEN = auto()\n" +"... BLUE = auto()\n" +"...\n" +">>> ConformFlag(2**2 + 2**4)\n" +"" + +#: ../../library/enum.rst:837 +msgid "" +"Out-of-range values lose their :class:`Flag` membership and revert to :class:" +"`int`." +msgstr "範圍外的值會失去它們的 :class:`Flag` 成員資格且恢復成 :class:`int`。" + +#: ../../library/enum.rst:850 +msgid "" +"Out-of-range values are kept, and the :class:`Flag` membership is kept. This " +"is the default for :class:`IntFlag`::" +msgstr "" +"範圍外的值會被保留，:class:`Flag` 成員資格也會被保留。這是 :class:`IntFlag` " +"的預設行為： ::" + +#: ../../library/enum.rst:853 +msgid "" +">>> from enum import Flag, KEEP, auto\n" +">>> class KeepFlag(Flag, boundary=KEEP):\n" +"... RED = auto()\n" +"... GREEN = auto()\n" +"... BLUE = auto()\n" +"...\n" +">>> KeepFlag(2**2 + 2**4)\n" +"" +msgstr "" +">>> from enum import Flag, KEEP, auto\n" +">>> class KeepFlag(Flag, boundary=KEEP):\n" +"... RED = auto()\n" +"... GREEN = auto()\n" +"... BLUE = auto()\n" +"...\n" +">>> KeepFlag(2**2 + 2**4)\n" +"" + +#: ../../library/enum.rst:866 +msgid "" +"*EnumDict* is a subclass of :class:`dict` that is used as the namespace for " +"defining enum classes (see :ref:`prepare`). It is exposed to allow " +"subclasses of :class:`EnumType` with advanced behavior like having multiple " +"values per member. It should be called with the name of the enum class being " +"created, otherwise private names and internal classes will not be handled " +"correctly." +msgstr "" +"*EnumDict* 是 :class:`dict` 的子類別，用來作為定義列舉類別的命名空間（參見 :" +"ref:`prepare`）。它被公開來使得 :class:`EnumType` 的子類別能具有進階行為，例" +"如讓每個成員有多個值。它應該在被呼叫時帶上正在建立的列舉類別名稱，否則私有名" +"稱和內部類別將無法被正確處理。" + +#: ../../library/enum.rst:873 +msgid "" +"Note that only the :class:`~collections.abc.MutableMapping` interface (:meth:" +"`~object.__setitem__` and :meth:`~dict.update`) is overridden. It may be " +"possible to bypass the checks using other :class:`!dict` operations like :" +"meth:`|= `." +msgstr "" +"注意只有 :class:`~collections.abc.MutableMapping` 介面（:meth:`~object." +"__setitem__` 和 :meth:`~dict.update`）被覆寫。可能可以使用其他 :class:`!" +"dict` 操作來繞過檢查，例如 :meth:`|= `。" + +#: ../../library/enum.rst:880 +msgid "A list of member names." +msgstr "一個成員名稱的串列。" + +#: ../../library/enum.rst:887 +msgid "Supported ``__dunder__`` names" +msgstr "支援的 ``__dunder__`` 名稱" + +#: ../../library/enum.rst:889 +msgid "" +":attr:`~EnumType.__members__` is a read-only ordered mapping of " +"``member_name``:``member`` items. It is only available on the class." +msgstr "" +":attr:`~EnumType.__members__` 是一個唯讀有序的\\ ``成員名稱``：``成員``\\ 項" +"目的對映。只有在類別上可用。" + +#: ../../library/enum.rst:892 +msgid "" +":meth:`~Enum.__new__`, if specified, must create and return the enum " +"members; it is also a very good idea to set the member's :attr:`!_value_` " +"appropriately. Once all the members are created it is no longer used." +msgstr "" +":meth:`~Enum.__new__`，如果有指定，它必須建立並回傳列舉成員；適當地設定成員" +"的 :attr:`!_value_` 也是一個很好的主意。一旦所有成員都建立之後就不會再被用" +"到。" + +#: ../../library/enum.rst:898 +msgid "Supported ``_sunder_`` names" +msgstr "支援的 ``_sunder_`` 名稱" + +#: ../../library/enum.rst:900 +msgid ":attr:`~Enum._name_` -- name of the member" +msgstr ":attr:`~Enum._name_` -- 成員名稱" + +#: ../../library/enum.rst:901 +msgid ":attr:`~Enum._value_` -- value of the member; can be set in ``__new__``" +msgstr ":attr:`~Enum._value_` -- 成員的值；可以在 ``__new__`` 設定" + +#: ../../library/enum.rst:902 +msgid "" +":meth:`~Enum._missing_` -- a lookup function used when a value is not found; " +"may be overridden" +msgstr "" +":meth:`~Enum._missing_` -- 當值沒有被找到時會使用的查詢函式；可以被覆寫" + +#: ../../library/enum.rst:904 +msgid "" +":attr:`~Enum._ignore_` -- a list of names, either as a :class:`list` or a :" +"class:`str`, that will not be transformed into members, and will be removed " +"from the final class" +msgstr "" +":attr:`~Enum._ignore_` -- 一個名稱的串列，可以是 :class:`list` 或 :class:" +"`str`，它不會被轉換成成員，且在最後的類別上會被移除" + +#: ../../library/enum.rst:907 +msgid "" +":attr:`~Enum._order_` -- no longer used, kept for backward compatibility " +"(class attribute, removed during class creation)" +msgstr "" +":attr:`~Enum._order_` -- 不再被使用，僅為了向後相容而保留（類別屬性，在類別建" +"立時移除）" + +#: ../../library/enum.rst:909 +msgid "" +":meth:`~Enum._generate_next_value_` -- used to get an appropriate value for " +"an enum member; may be overridden" +msgstr "" +":meth:`~Enum._generate_next_value_` -- 用來為列舉成員取得合適的值；可以被覆寫" + +#: ../../library/enum.rst:914 +msgid "" +"For standard :class:`Enum` classes the next value chosen is the highest " +"value seen incremented by one." +msgstr "" +"對標準的 :class:`Enum` 類別來說，下一個被選擇的值是所看過的最大值加一。" + +#: ../../library/enum.rst:917 +msgid "" +"For :class:`Flag` classes the next value chosen will be the next highest " +"power-of-two." +msgstr "" +"對 :class:`Flag` 類別來說，下一個被選擇的值是下一個最大的 2 的次方的數字。" + +#: ../../library/enum.rst:920 +msgid "" +":meth:`~Enum._add_alias_` -- adds a new name as an alias to an existing " +"member." +msgstr ":meth:`~Enum._add_alias_` -- 新增一個名稱作為現有成員的別名。" + +#: ../../library/enum.rst:922 +msgid "" +":meth:`~Enum._add_value_alias_` -- adds a new value as an alias to an " +"existing member." +msgstr ":meth:`~Enum._add_value_alias_` -- 新增一個值作為現有成員的別名。" + +#: ../../library/enum.rst:925 +msgid "" +"While ``_sunder_`` names are generally reserved for the further development " +"of the :class:`Enum` class and can not be used, some are explicitly allowed:" +msgstr "" +"雖然 ``_sunder_`` 名稱通常保留用於 :class:`Enum` 類別的進一步開發而不能被使" +"用，但有些是明確允許的：" + +#: ../../library/enum.rst:928 +msgid "" +"``_repr_*`` (e.g. ``_repr_html_``), as used in `IPython's rich display`_" +msgstr "" +"``_repr_*``\\ （例如 ``_repr_html_``），例如用於 `IPython 的豐富顯示 " +"`_" + +#: ../../library/enum.rst:930 +msgid "``_missing_``, ``_order_``, ``_generate_next_value_``" +msgstr "``_missing_``、``_order_``、``_generate_next_value_``" + +#: ../../library/enum.rst:931 +msgid "``_ignore_``" +msgstr "``_ignore_``" + +#: ../../library/enum.rst:932 +msgid "``_add_alias_``, ``_add_value_alias_``, ``_repr_*``" +msgstr "``_add_alias_``、``_add_value_alias_``、``_repr_*``" + +#: ../../library/enum.rst:938 +msgid "Utilities and Decorators" +msgstr "通用項目與裝飾器" + +#: ../../library/enum.rst:942 +msgid "" +"*auto* can be used in place of a value. If used, the *Enum* machinery will " +"call an :class:`Enum`'s :meth:`~Enum._generate_next_value_` to get an " +"appropriate value. For :class:`Enum` and :class:`IntEnum` that appropriate " +"value will be the last value plus one; for :class:`Flag` and :class:" +"`IntFlag` it will be the first power-of-two greater than the highest value; " +"for :class:`StrEnum` it will be the lower-cased version of the member's " +"name. Care must be taken if mixing *auto()* with manually specified values." +msgstr "" +"*auto* 可以用來取代給值。如果使用的話，*Enum* 系統會呼叫 :class:`Enum` 的 :" +"meth:`~Enum._generate_next_value_` 來取得合適的值。對 :class:`Enum` 和 :" +"class:`IntEnum` 來說，合適的值是最後一個值加一；對 :class:`Flag` 和 :class:" +"`IntFlag` 來說，是第一個比最大值還大的 2 的次方的數字；對 :class:`StrEnum` 來" +"說，是成員名稱的小寫版本。如果混用 *auto()* 和手動指定值的話要特別注意。" + +#: ../../library/enum.rst:950 +msgid "" +"*auto* instances are only resolved when at the top level of an assignment, " +"either by itself or as part of a tuple:" +msgstr "*auto* 實例只有在最上層的賦值時才會被解析，不論是獨自一個或作為元組的一部分：" + +#: ../../library/enum.rst:953 +msgid "``FIRST = auto()`` will work (auto() is replaced with ``1``);" +msgstr "``FIRST = auto()`` 可以運作（auto() 會被取代成 ``1``）" + +#: ../../library/enum.rst:954 +msgid "" +"``SECOND = auto(), -2`` will work (auto is replaced with ``2``, so ``2, -2`` " +"is used to create the ``SECOND`` enum member;" +msgstr "" +"``SECOND = auto(), -2`` 可以運作（auto 會被取代成 ``2``, 因此 ``2, -2`` 會被" +"用來建立列舉成員 ``SECOND``；" + +#: ../../library/enum.rst:956 +msgid "" +"``THREE = [auto(), -3]`` will *not* work (``[, -3]`` is used " +"to create the ``THREE`` enum member)" +msgstr "" +"``THREE = [auto(), -3]`` *無法*\\ 運作（``[, -3]`` 會被用來建立列" +"舉成員 ``THREE``）" + +#: ../../library/enum.rst:961 +msgid "" +"In prior versions, ``auto()`` had to be the only thing on the assignment " +"line to work properly." +msgstr "在之前的版本中，``auto()`` 必須是賦值行裡的唯一內容才能運作正確。" + +#: ../../library/enum.rst:964 +msgid "" +"``_generate_next_value_`` can be overridden to customize the values used by " +"*auto*." +msgstr "可以覆寫 ``_generate_next_value_`` 來客製 *auto* 使用的值。" + +#: ../../library/enum.rst:967 +msgid "" +"in 3.13 the default ``_generate_next_value_`` will always return the highest " +"member value incremented by 1, and will fail if any member is an " +"incompatible type." +msgstr "" +"在 3.13 預設 ``_generate_next_value_`` 總是回傳最大的成員值加一，如果任何成員" +"是不相容的型別就會失敗。" + +#: ../../library/enum.rst:973 +msgid "" +"A decorator similar to the built-in *property*, but specifically for " +"enumerations. It allows member attributes to have the same names as members " +"themselves." +msgstr "" +"和內建的 *property* 相似的裝飾器，但只專門針對列舉。它允許成員屬性和成員本身" +"有相同名稱。" + +#: ../../library/enum.rst:977 +msgid "" +"the *property* and the member must be defined in separate classes; for " +"example, the *value* and *name* attributes are defined in the *Enum* class, " +"and *Enum* subclasses can define members with the names ``value`` and " +"``name``." +msgstr "" +"*屬性*\\ 和成員必須定義在分開的類別裡；例如 *value* 和 *name* 屬性定義在 " +"*Enum* 類別而 *Enum* 子類別可以定義成員名稱為 ``value`` 和 ``name``。" + +#: ../../library/enum.rst:986 +msgid "" +"A :keyword:`class` decorator specifically for enumerations. It searches an " +"enumeration's :attr:`~EnumType.__members__`, gathering any aliases it finds; " +"if any are found :exc:`ValueError` is raised with the details::" +msgstr "" +"專門針對列舉的 :keyword:`class` 裝飾器。它搜尋列舉的 :attr:`~EnumType." +"__members__`，蒐集任何它找到的別名；如果有找到任何別名則引發 :exc:" +"`ValueError` 並附上細節： ::" + +#: ../../library/enum.rst:990 +msgid "" +">>> from enum import Enum, unique\n" +">>> @unique\n" +"... class Mistake(Enum):\n" +"... ONE = 1\n" +"... TWO = 2\n" +"... THREE = 3\n" +"... FOUR = 3\n" +"...\n" +"Traceback (most recent call last):\n" +"...\n" +"ValueError: duplicate values found in : FOUR -> THREE" +msgstr "" +">>> from enum import Enum, unique\n" +">>> @unique\n" +"... class Mistake(Enum):\n" +"... ONE = 1\n" +"... TWO = 2\n" +"... THREE = 3\n" +"... FOUR = 3\n" +"...\n" +"Traceback (most recent call last):\n" +"...\n" +"ValueError: duplicate values found in : FOUR -> THREE" + +#: ../../library/enum.rst:1004 +msgid "" +"A :keyword:`class` decorator specifically for enumerations. Members from :" +"class:`EnumCheck` are used to specify which constraints should be checked on " +"the decorated enumeration." +msgstr "" +"專門針對列舉的 :keyword:`class` 裝飾器。使用 :class:`EnumCheck` 裡的成員來指" +"定在裝飾的列舉上應該檢查什麼限制。" + +#: ../../library/enum.rst:1012 +msgid "A decorator for use in enums: its target will become a member." +msgstr "列舉所使用的裝飾器：其目標會變成成員。" + +#: ../../library/enum.rst:1018 +msgid "A decorator for use in enums: its target will not become a member." +msgstr "列舉所使用的裝飾器：其目標不會變成成員。" + +#: ../../library/enum.rst:1024 +msgid "" +"A decorator to change the :class:`str() ` and :func:`repr` of an enum " +"to show its members as belonging to the module instead of its class. Should " +"only be used when the enum members are exported to the module global " +"namespace (see :class:`re.RegexFlag` for an example)." +msgstr "" +"修改列舉的 :class:`str() ` 及 :func:`repr` 的裝飾器，讓成員顯示為屬於模" +"組而不是其類別。應該只有當列舉成員被匯出到模組的全域命名空間才使用（範例請參" +"考 :class:`re.RegexFlag`）。" + +#: ../../library/enum.rst:1034 +msgid "Return a list of all power-of-two integers contained in a flag *value*." +msgstr "回傳在旗標\\ *值*\\ 中包含的所有 2 的次方的整數串列。" + +#: ../../library/enum.rst:1041 +msgid "Notes" +msgstr "備註" + +#: ../../library/enum.rst:1043 +msgid ":class:`IntEnum`, :class:`StrEnum`, and :class:`IntFlag`" +msgstr ":class:`IntEnum`、:class:`StrEnum` 及 :class:`IntFlag`" + +#: ../../library/enum.rst:1045 +msgid "" +"These three enum types are designed to be drop-in replacements for existing " +"integer- and string-based values; as such, they have extra limitations:" +msgstr "" +"這三種列舉型別是設計來直接取代現有以整數及字串為基底的值；因此它們有額外的限" +"制：" + +#: ../../library/enum.rst:1048 +msgid "``__str__`` uses the value and not the name of the enum member" +msgstr "``__str__`` 使用值而不是列舉成員的名稱" + +#: ../../library/enum.rst:1050 +msgid "" +"``__format__``, because it uses ``__str__``, will also use the value of the " +"enum member instead of its name" +msgstr "``__format__`` 因為使用 ``__str__``，也會使用值而不是列舉成員的名稱" + +#: ../../library/enum.rst:1053 +msgid "" +"If you do not need/want those limitations, you can either create your own " +"base class by mixing in the ``int`` or ``str`` type yourself::" +msgstr "" +"如果你不需要或不想要這些限制，你可以透過混合 ``int`` 或 ``str`` 型別來建立自" +"己的基礎類別： ::" + +#: ../../library/enum.rst:1056 +msgid "" +">>> from enum import Enum\n" +">>> class MyIntEnum(int, Enum):\n" +"... pass" +msgstr "" +">>> from enum import Enum\n" +">>> class MyIntEnum(int, Enum):\n" +"... pass" + +#: ../../library/enum.rst:1060 +msgid "or you can reassign the appropriate :meth:`str`, etc., in your enum::" +msgstr "或者你也可以在你的列舉重新給定合適的 :meth:`str`： ::" + +#: ../../library/enum.rst:1062 +msgid "" +">>> from enum import Enum, IntEnum\n" +">>> class MyIntEnum(IntEnum):\n" +"... __str__ = Enum.__str__" +msgstr "" +">>> from enum import Enum, IntEnum\n" +">>> class MyIntEnum(IntEnum):\n" +"... __str__ = Enum.__str__" diff --git a/library/errno.po b/library/errno.po index 822df7939f..b57d230f7a 100644 --- a/library/errno.po +++ b/library/errno.po @@ -1,711 +1,711 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: 2015-12-09 17:51+0000\n" -"Last-Translator: Liang-Bo Wang \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/errno.rst:2 -msgid ":mod:`!errno` --- Standard errno system symbols" -msgstr ":mod:`!errno` --- 標準 errno 系統符號" - -#: ../../library/errno.rst:9 -msgid "" -"This module makes available standard ``errno`` system symbols. The value of " -"each symbol is the corresponding integer value. The names and descriptions " -"are borrowed from :file:`linux/include/errno.h`, which should be all-" -"inclusive." -msgstr "" - -#: ../../library/errno.rst:17 -msgid "" -"Dictionary providing a mapping from the errno value to the string name in " -"the underlying system. For instance, ``errno.errorcode[errno.EPERM]`` maps " -"to ``'EPERM'``." -msgstr "" - -#: ../../library/errno.rst:21 -msgid "" -"To translate a numeric error code to an error message, " -"use :func:`os.strerror`." -msgstr "" - -#: ../../library/errno.rst:23 -msgid "" -"Of the following list, symbols that are not used on the current platform are " -"not defined by the module. The specific list of defined symbols is " -"available as ``errno.errorcode.keys()``. Symbols available can include:" -msgstr "" - -#: ../../library/errno.rst:30 -msgid "" -"Operation not permitted. This error is mapped to the " -"exception :exc:`PermissionError`." -msgstr "" - -#: ../../library/errno.rst:36 -msgid "" -"No such file or directory. This error is mapped to the " -"exception :exc:`FileNotFoundError`." -msgstr "" - -#: ../../library/errno.rst:42 -msgid "" -"No such process. This error is mapped to the " -"exception :exc:`ProcessLookupError`." -msgstr "" - -#: ../../library/errno.rst:48 -msgid "" -"Interrupted system call. This error is mapped to the " -"exception :exc:`InterruptedError`." -msgstr "" - -#: ../../library/errno.rst:54 -msgid "I/O error" -msgstr "" - -#: ../../library/errno.rst:59 -msgid "No such device or address" -msgstr "" - -#: ../../library/errno.rst:64 -msgid "Arg list too long" -msgstr "" - -#: ../../library/errno.rst:69 -msgid "Exec format error" -msgstr "" - -#: ../../library/errno.rst:74 -msgid "Bad file number" -msgstr "" - -#: ../../library/errno.rst:79 -msgid "" -"No child processes. This error is mapped to the " -"exception :exc:`ChildProcessError`." -msgstr "" - -#: ../../library/errno.rst:85 -msgid "" -"Try again. This error is mapped to the exception :exc:`BlockingIOError`." -msgstr "" - -#: ../../library/errno.rst:90 -msgid "Out of memory" -msgstr "" - -#: ../../library/errno.rst:95 -msgid "" -"Permission denied. This error is mapped to the " -"exception :exc:`PermissionError`." -msgstr "" - -#: ../../library/errno.rst:101 -msgid "Bad address" -msgstr "" - -#: ../../library/errno.rst:106 -msgid "Block device required" -msgstr "" - -#: ../../library/errno.rst:111 -msgid "Device or resource busy" -msgstr "" - -#: ../../library/errno.rst:116 -msgid "" -"File exists. This error is mapped to the exception :exc:`FileExistsError`." -msgstr "" - -#: ../../library/errno.rst:122 -msgid "Cross-device link" -msgstr "" - -#: ../../library/errno.rst:127 -msgid "No such device" -msgstr "" - -#: ../../library/errno.rst:132 -msgid "" -"Not a directory. This error is mapped to the " -"exception :exc:`NotADirectoryError`." -msgstr "" - -#: ../../library/errno.rst:138 -msgid "" -"Is a directory. This error is mapped to the " -"exception :exc:`IsADirectoryError`." -msgstr "" - -#: ../../library/errno.rst:144 -msgid "Invalid argument" -msgstr "" - -#: ../../library/errno.rst:149 -msgid "File table overflow" -msgstr "" - -#: ../../library/errno.rst:154 -msgid "Too many open files" -msgstr "" - -#: ../../library/errno.rst:159 -msgid "Not a typewriter" -msgstr "" - -#: ../../library/errno.rst:164 -msgid "Text file busy" -msgstr "" - -#: ../../library/errno.rst:169 -msgid "File too large" -msgstr "" - -#: ../../library/errno.rst:174 -msgid "No space left on device" -msgstr "" - -#: ../../library/errno.rst:179 -msgid "Illegal seek" -msgstr "" - -#: ../../library/errno.rst:184 -msgid "Read-only file system" -msgstr "" - -#: ../../library/errno.rst:189 -msgid "Too many links" -msgstr "" - -#: ../../library/errno.rst:194 -msgid "" -"Broken pipe. This error is mapped to the exception :exc:`BrokenPipeError`." -msgstr "" - -#: ../../library/errno.rst:200 -msgid "Math argument out of domain of func" -msgstr "" - -#: ../../library/errno.rst:205 -msgid "Math result not representable" -msgstr "" - -#: ../../library/errno.rst:210 -msgid "Resource deadlock would occur" -msgstr "" - -#: ../../library/errno.rst:215 -msgid "File name too long" -msgstr "" - -#: ../../library/errno.rst:220 -msgid "No record locks available" -msgstr "" - -#: ../../library/errno.rst:225 -msgid "Function not implemented" -msgstr "" - -#: ../../library/errno.rst:230 -msgid "Directory not empty" -msgstr "" - -#: ../../library/errno.rst:235 -msgid "Too many symbolic links encountered" -msgstr "" - -#: ../../library/errno.rst:240 -msgid "" -"Operation would block. This error is mapped to the " -"exception :exc:`BlockingIOError`." -msgstr "" - -#: ../../library/errno.rst:246 -msgid "No message of desired type" -msgstr "" - -#: ../../library/errno.rst:251 -msgid "Identifier removed" -msgstr "" - -#: ../../library/errno.rst:256 -msgid "Channel number out of range" -msgstr "" - -#: ../../library/errno.rst:261 -msgid "Level 2 not synchronized" -msgstr "" - -#: ../../library/errno.rst:266 -msgid "Level 3 halted" -msgstr "" - -#: ../../library/errno.rst:271 -msgid "Level 3 reset" -msgstr "" - -#: ../../library/errno.rst:276 -msgid "Link number out of range" -msgstr "" - -#: ../../library/errno.rst:281 -msgid "Protocol driver not attached" -msgstr "" - -#: ../../library/errno.rst:286 -msgid "No CSI structure available" -msgstr "" - -#: ../../library/errno.rst:291 -msgid "Level 2 halted" -msgstr "" - -#: ../../library/errno.rst:296 -msgid "Invalid exchange" -msgstr "" - -#: ../../library/errno.rst:301 -msgid "Invalid request descriptor" -msgstr "" - -#: ../../library/errno.rst:306 -msgid "Exchange full" -msgstr "" - -#: ../../library/errno.rst:311 -msgid "No anode" -msgstr "" - -#: ../../library/errno.rst:316 -msgid "Invalid request code" -msgstr "" - -#: ../../library/errno.rst:321 -msgid "Invalid slot" -msgstr "" - -#: ../../library/errno.rst:326 -msgid "File locking deadlock error" -msgstr "" - -#: ../../library/errno.rst:331 -msgid "Bad font file format" -msgstr "" - -#: ../../library/errno.rst:336 -msgid "Device not a stream" -msgstr "" - -#: ../../library/errno.rst:341 -msgid "No data available" -msgstr "" - -#: ../../library/errno.rst:346 -msgid "Timer expired" -msgstr "" - -#: ../../library/errno.rst:351 -msgid "Out of streams resources" -msgstr "" - -#: ../../library/errno.rst:356 -msgid "Machine is not on the network" -msgstr "" - -#: ../../library/errno.rst:361 -msgid "Package not installed" -msgstr "" - -#: ../../library/errno.rst:366 -msgid "Object is remote" -msgstr "" - -#: ../../library/errno.rst:371 -msgid "Link has been severed" -msgstr "" - -#: ../../library/errno.rst:376 -msgid "Advertise error" -msgstr "" - -#: ../../library/errno.rst:381 -msgid "Srmount error" -msgstr "" - -#: ../../library/errno.rst:386 -msgid "Communication error on send" -msgstr "" - -#: ../../library/errno.rst:391 -msgid "Protocol error" -msgstr "" - -#: ../../library/errno.rst:396 -msgid "Multihop attempted" -msgstr "" - -#: ../../library/errno.rst:401 -msgid "RFS specific error" -msgstr "" - -#: ../../library/errno.rst:406 -msgid "Not a data message" -msgstr "" - -#: ../../library/errno.rst:411 -msgid "Value too large for defined data type" -msgstr "" - -#: ../../library/errno.rst:416 -msgid "Name not unique on network" -msgstr "" - -#: ../../library/errno.rst:421 -msgid "File descriptor in bad state" -msgstr "" - -#: ../../library/errno.rst:426 -msgid "Remote address changed" -msgstr "" - -#: ../../library/errno.rst:431 -msgid "Can not access a needed shared library" -msgstr "" - -#: ../../library/errno.rst:436 -msgid "Accessing a corrupted shared library" -msgstr "" - -#: ../../library/errno.rst:441 -msgid ".lib section in a.out corrupted" -msgstr "" - -#: ../../library/errno.rst:446 -msgid "Attempting to link in too many shared libraries" -msgstr "" - -#: ../../library/errno.rst:451 -msgid "Cannot exec a shared library directly" -msgstr "" - -#: ../../library/errno.rst:456 -msgid "Illegal byte sequence" -msgstr "" - -#: ../../library/errno.rst:461 -msgid "Interrupted system call should be restarted" -msgstr "" - -#: ../../library/errno.rst:466 -msgid "Streams pipe error" -msgstr "" - -#: ../../library/errno.rst:471 -msgid "Too many users" -msgstr "使用者數量過多" - -#: ../../library/errno.rst:476 -msgid "Socket operation on non-socket" -msgstr "" - -#: ../../library/errno.rst:481 -msgid "Destination address required" -msgstr "" - -#: ../../library/errno.rst:486 -msgid "Message too long" -msgstr "" - -#: ../../library/errno.rst:491 -msgid "Protocol wrong type for socket" -msgstr "" - -#: ../../library/errno.rst:496 -msgid "Protocol not available" -msgstr "" - -#: ../../library/errno.rst:501 -msgid "Protocol not supported" -msgstr "" - -#: ../../library/errno.rst:506 -msgid "Socket type not supported" -msgstr "" - -#: ../../library/errno.rst:511 -msgid "Operation not supported on transport endpoint" -msgstr "" - -#: ../../library/errno.rst:516 -msgid "Operation not supported" -msgstr "" - -#: ../../library/errno.rst:523 -msgid "Protocol family not supported" -msgstr "" - -#: ../../library/errno.rst:528 -msgid "Address family not supported by protocol" -msgstr "" - -#: ../../library/errno.rst:533 -msgid "Address already in use" -msgstr "" - -#: ../../library/errno.rst:538 -msgid "Cannot assign requested address" -msgstr "" - -#: ../../library/errno.rst:543 -msgid "Network is down" -msgstr "" - -#: ../../library/errno.rst:548 -msgid "Network is unreachable" -msgstr "" - -#: ../../library/errno.rst:553 -msgid "Network dropped connection because of reset" -msgstr "" - -#: ../../library/errno.rst:558 -msgid "" -"Software caused connection abort. This error is mapped to the " -"exception :exc:`ConnectionAbortedError`." -msgstr "" - -#: ../../library/errno.rst:564 -msgid "" -"Connection reset by peer. This error is mapped to the " -"exception :exc:`ConnectionResetError`." -msgstr "" - -#: ../../library/errno.rst:570 -msgid "No buffer space available" -msgstr "" - -#: ../../library/errno.rst:575 -msgid "Transport endpoint is already connected" -msgstr "" - -#: ../../library/errno.rst:580 -msgid "Transport endpoint is not connected" -msgstr "" - -#: ../../library/errno.rst:585 -msgid "" -"Cannot send after transport endpoint shutdown. This error is mapped to the " -"exception :exc:`BrokenPipeError`." -msgstr "" - -#: ../../library/errno.rst:591 -msgid "Too many references: cannot splice" -msgstr "" - -#: ../../library/errno.rst:596 -msgid "" -"Connection timed out. This error is mapped to the " -"exception :exc:`TimeoutError`." -msgstr "" - -#: ../../library/errno.rst:602 -msgid "" -"Connection refused. This error is mapped to the " -"exception :exc:`ConnectionRefusedError`." -msgstr "" - -#: ../../library/errno.rst:608 -msgid "Host is down" -msgstr "" - -#: ../../library/errno.rst:613 -msgid "No route to host" -msgstr "" - -#: ../../library/errno.rst:618 -msgid "Memory page has hardware error." -msgstr "" - -#: ../../library/errno.rst:625 -msgid "" -"Operation already in progress. This error is mapped to the " -"exception :exc:`BlockingIOError`." -msgstr "" - -#: ../../library/errno.rst:631 -msgid "" -"Operation now in progress. This error is mapped to the " -"exception :exc:`BlockingIOError`." -msgstr "" - -#: ../../library/errno.rst:637 -msgid "Stale NFS file handle" -msgstr "" - -#: ../../library/errno.rst:642 -msgid "Structure needs cleaning" -msgstr "" - -#: ../../library/errno.rst:647 -msgid "Not a XENIX named type file" -msgstr "" - -#: ../../library/errno.rst:652 -msgid "No XENIX semaphores available" -msgstr "" - -#: ../../library/errno.rst:657 -msgid "Is a named type file" -msgstr "" - -#: ../../library/errno.rst:662 -msgid "Remote I/O error" -msgstr "" - -#: ../../library/errno.rst:667 -msgid "Quota exceeded" -msgstr "" - -#: ../../library/errno.rst:671 -msgid "Interface output queue is full" -msgstr "" - -#: ../../library/errno.rst:678 -msgid "No medium found" -msgstr "" - -#: ../../library/errno.rst:683 -msgid "Wrong medium type" -msgstr "" - -#: ../../library/errno.rst:688 -msgid "Required key not available" -msgstr "" - -#: ../../library/errno.rst:693 -msgid "Key has expired" -msgstr "" - -#: ../../library/errno.rst:698 -msgid "Key has been revoked" -msgstr "" - -#: ../../library/errno.rst:703 -msgid "Key was rejected by service" -msgstr "" - -#: ../../library/errno.rst:708 -msgid "Operation not possible due to RF-kill" -msgstr "" - -#: ../../library/errno.rst:713 -msgid "Locked lock was unmapped" -msgstr "" - -#: ../../library/errno.rst:718 -msgid "Facility is not active" -msgstr "" - -#: ../../library/errno.rst:723 -msgid "Authentication error" -msgstr "" - -#: ../../library/errno.rst:730 -msgid "Bad CPU type in executable" -msgstr "" - -#: ../../library/errno.rst:737 -msgid "Bad executable (or shared library)" -msgstr "" - -#: ../../library/errno.rst:744 -msgid "Malformed Mach-o file" -msgstr "" - -#: ../../library/errno.rst:751 -msgid "Device error" -msgstr "裝置錯誤" - -#: ../../library/errno.rst:758 -msgid "Inappropriate file type or format" -msgstr "不適當的檔案類型或格式" - -#: ../../library/errno.rst:765 -msgid "Need authenticator" -msgstr "需要驗證器" - -#: ../../library/errno.rst:772 -msgid "Attribute not found" -msgstr "找不到屬性" - -#: ../../library/errno.rst:779 -msgid "Policy not found" -msgstr "" - -#: ../../library/errno.rst:786 -msgid "Too many processes" -msgstr "行程數量過多" - -#: ../../library/errno.rst:793 -msgid "Bad procedure for program" -msgstr "" - -#: ../../library/errno.rst:800 -msgid "Program version wrong" -msgstr "" - -#: ../../library/errno.rst:807 -msgid "RPC prog. not avail" -msgstr "" - -#: ../../library/errno.rst:814 -msgid "Device power is off" -msgstr "裝置電源關閉" - -#: ../../library/errno.rst:821 -msgid "RPC struct is bad" -msgstr "RPC 結構不正確" - -#: ../../library/errno.rst:828 -msgid "RPC version wrong" -msgstr "RPC 版本錯誤" - -#: ../../library/errno.rst:835 -msgid "Shared library version mismatch" -msgstr "共享函式庫版本不匹配" - -#: ../../library/errno.rst:842 -msgid "" -"Capabilities insufficient. This error is mapped to the " -"exception :exc:`PermissionError`." -msgstr "" - -#: ../../library/errno.rst:845 -msgid "Availability" -msgstr "可用性" - -#: ../../library/errno.rst:852 -msgid "Operation canceled" -msgstr "操作已取消" - -#: ../../library/errno.rst:859 -msgid "Owner died" -msgstr "擁有者過世" - -#: ../../library/errno.rst:866 -msgid "State not recoverable" -msgstr "狀態無法恢復" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: 2015-12-09 17:51+0000\n" +"Last-Translator: Liang-Bo Wang \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/errno.rst:2 +msgid ":mod:`!errno` --- Standard errno system symbols" +msgstr ":mod:`!errno` --- 標準 errno 系統符號" + +#: ../../library/errno.rst:9 +msgid "" +"This module makes available standard ``errno`` system symbols. The value of " +"each symbol is the corresponding integer value. The names and descriptions " +"are borrowed from :file:`linux/include/errno.h`, which should be all-" +"inclusive." +msgstr "" + +#: ../../library/errno.rst:17 +msgid "" +"Dictionary providing a mapping from the errno value to the string name in " +"the underlying system. For instance, ``errno.errorcode[errno.EPERM]`` maps " +"to ``'EPERM'``." +msgstr "" + +#: ../../library/errno.rst:21 +msgid "" +"To translate a numeric error code to an error message, " +"use :func:`os.strerror`." +msgstr "" + +#: ../../library/errno.rst:23 +msgid "" +"Of the following list, symbols that are not used on the current platform are " +"not defined by the module. The specific list of defined symbols is " +"available as ``errno.errorcode.keys()``. Symbols available can include:" +msgstr "" + +#: ../../library/errno.rst:30 +msgid "" +"Operation not permitted. This error is mapped to the " +"exception :exc:`PermissionError`." +msgstr "" + +#: ../../library/errno.rst:36 +msgid "" +"No such file or directory. This error is mapped to the " +"exception :exc:`FileNotFoundError`." +msgstr "" + +#: ../../library/errno.rst:42 +msgid "" +"No such process. This error is mapped to the " +"exception :exc:`ProcessLookupError`." +msgstr "" + +#: ../../library/errno.rst:48 +msgid "" +"Interrupted system call. This error is mapped to the " +"exception :exc:`InterruptedError`." +msgstr "" + +#: ../../library/errno.rst:54 +msgid "I/O error" +msgstr "" + +#: ../../library/errno.rst:59 +msgid "No such device or address" +msgstr "" + +#: ../../library/errno.rst:64 +msgid "Arg list too long" +msgstr "" + +#: ../../library/errno.rst:69 +msgid "Exec format error" +msgstr "" + +#: ../../library/errno.rst:74 +msgid "Bad file number" +msgstr "" + +#: ../../library/errno.rst:79 +msgid "" +"No child processes. This error is mapped to the " +"exception :exc:`ChildProcessError`." +msgstr "" + +#: ../../library/errno.rst:85 +msgid "" +"Try again. This error is mapped to the exception :exc:`BlockingIOError`." +msgstr "" + +#: ../../library/errno.rst:90 +msgid "Out of memory" +msgstr "" + +#: ../../library/errno.rst:95 +msgid "" +"Permission denied. This error is mapped to the " +"exception :exc:`PermissionError`." +msgstr "" + +#: ../../library/errno.rst:101 +msgid "Bad address" +msgstr "" + +#: ../../library/errno.rst:106 +msgid "Block device required" +msgstr "" + +#: ../../library/errno.rst:111 +msgid "Device or resource busy" +msgstr "" + +#: ../../library/errno.rst:116 +msgid "" +"File exists. This error is mapped to the exception :exc:`FileExistsError`." +msgstr "" + +#: ../../library/errno.rst:122 +msgid "Cross-device link" +msgstr "" + +#: ../../library/errno.rst:127 +msgid "No such device" +msgstr "" + +#: ../../library/errno.rst:132 +msgid "" +"Not a directory. This error is mapped to the " +"exception :exc:`NotADirectoryError`." +msgstr "" + +#: ../../library/errno.rst:138 +msgid "" +"Is a directory. This error is mapped to the " +"exception :exc:`IsADirectoryError`." +msgstr "" + +#: ../../library/errno.rst:144 +msgid "Invalid argument" +msgstr "" + +#: ../../library/errno.rst:149 +msgid "File table overflow" +msgstr "" + +#: ../../library/errno.rst:154 +msgid "Too many open files" +msgstr "" + +#: ../../library/errno.rst:159 +msgid "Not a typewriter" +msgstr "" + +#: ../../library/errno.rst:164 +msgid "Text file busy" +msgstr "" + +#: ../../library/errno.rst:169 +msgid "File too large" +msgstr "" + +#: ../../library/errno.rst:174 +msgid "No space left on device" +msgstr "" + +#: ../../library/errno.rst:179 +msgid "Illegal seek" +msgstr "" + +#: ../../library/errno.rst:184 +msgid "Read-only file system" +msgstr "" + +#: ../../library/errno.rst:189 +msgid "Too many links" +msgstr "" + +#: ../../library/errno.rst:194 +msgid "" +"Broken pipe. This error is mapped to the exception :exc:`BrokenPipeError`." +msgstr "" + +#: ../../library/errno.rst:200 +msgid "Math argument out of domain of func" +msgstr "" + +#: ../../library/errno.rst:205 +msgid "Math result not representable" +msgstr "" + +#: ../../library/errno.rst:210 +msgid "Resource deadlock would occur" +msgstr "" + +#: ../../library/errno.rst:215 +msgid "File name too long" +msgstr "" + +#: ../../library/errno.rst:220 +msgid "No record locks available" +msgstr "" + +#: ../../library/errno.rst:225 +msgid "Function not implemented" +msgstr "" + +#: ../../library/errno.rst:230 +msgid "Directory not empty" +msgstr "" + +#: ../../library/errno.rst:235 +msgid "Too many symbolic links encountered" +msgstr "" + +#: ../../library/errno.rst:240 +msgid "" +"Operation would block. This error is mapped to the " +"exception :exc:`BlockingIOError`." +msgstr "" + +#: ../../library/errno.rst:246 +msgid "No message of desired type" +msgstr "" + +#: ../../library/errno.rst:251 +msgid "Identifier removed" +msgstr "" + +#: ../../library/errno.rst:256 +msgid "Channel number out of range" +msgstr "" + +#: ../../library/errno.rst:261 +msgid "Level 2 not synchronized" +msgstr "" + +#: ../../library/errno.rst:266 +msgid "Level 3 halted" +msgstr "" + +#: ../../library/errno.rst:271 +msgid "Level 3 reset" +msgstr "" + +#: ../../library/errno.rst:276 +msgid "Link number out of range" +msgstr "" + +#: ../../library/errno.rst:281 +msgid "Protocol driver not attached" +msgstr "" + +#: ../../library/errno.rst:286 +msgid "No CSI structure available" +msgstr "" + +#: ../../library/errno.rst:291 +msgid "Level 2 halted" +msgstr "" + +#: ../../library/errno.rst:296 +msgid "Invalid exchange" +msgstr "" + +#: ../../library/errno.rst:301 +msgid "Invalid request descriptor" +msgstr "" + +#: ../../library/errno.rst:306 +msgid "Exchange full" +msgstr "" + +#: ../../library/errno.rst:311 +msgid "No anode" +msgstr "" + +#: ../../library/errno.rst:316 +msgid "Invalid request code" +msgstr "" + +#: ../../library/errno.rst:321 +msgid "Invalid slot" +msgstr "" + +#: ../../library/errno.rst:326 +msgid "File locking deadlock error" +msgstr "" + +#: ../../library/errno.rst:331 +msgid "Bad font file format" +msgstr "" + +#: ../../library/errno.rst:336 +msgid "Device not a stream" +msgstr "" + +#: ../../library/errno.rst:341 +msgid "No data available" +msgstr "" + +#: ../../library/errno.rst:346 +msgid "Timer expired" +msgstr "" + +#: ../../library/errno.rst:351 +msgid "Out of streams resources" +msgstr "" + +#: ../../library/errno.rst:356 +msgid "Machine is not on the network" +msgstr "" + +#: ../../library/errno.rst:361 +msgid "Package not installed" +msgstr "" + +#: ../../library/errno.rst:366 +msgid "Object is remote" +msgstr "" + +#: ../../library/errno.rst:371 +msgid "Link has been severed" +msgstr "" + +#: ../../library/errno.rst:376 +msgid "Advertise error" +msgstr "" + +#: ../../library/errno.rst:381 +msgid "Srmount error" +msgstr "" + +#: ../../library/errno.rst:386 +msgid "Communication error on send" +msgstr "" + +#: ../../library/errno.rst:391 +msgid "Protocol error" +msgstr "" + +#: ../../library/errno.rst:396 +msgid "Multihop attempted" +msgstr "" + +#: ../../library/errno.rst:401 +msgid "RFS specific error" +msgstr "" + +#: ../../library/errno.rst:406 +msgid "Not a data message" +msgstr "" + +#: ../../library/errno.rst:411 +msgid "Value too large for defined data type" +msgstr "" + +#: ../../library/errno.rst:416 +msgid "Name not unique on network" +msgstr "" + +#: ../../library/errno.rst:421 +msgid "File descriptor in bad state" +msgstr "" + +#: ../../library/errno.rst:426 +msgid "Remote address changed" +msgstr "" + +#: ../../library/errno.rst:431 +msgid "Can not access a needed shared library" +msgstr "" + +#: ../../library/errno.rst:436 +msgid "Accessing a corrupted shared library" +msgstr "" + +#: ../../library/errno.rst:441 +msgid ".lib section in a.out corrupted" +msgstr "" + +#: ../../library/errno.rst:446 +msgid "Attempting to link in too many shared libraries" +msgstr "" + +#: ../../library/errno.rst:451 +msgid "Cannot exec a shared library directly" +msgstr "" + +#: ../../library/errno.rst:456 +msgid "Illegal byte sequence" +msgstr "" + +#: ../../library/errno.rst:461 +msgid "Interrupted system call should be restarted" +msgstr "" + +#: ../../library/errno.rst:466 +msgid "Streams pipe error" +msgstr "" + +#: ../../library/errno.rst:471 +msgid "Too many users" +msgstr "使用者數量過多" + +#: ../../library/errno.rst:476 +msgid "Socket operation on non-socket" +msgstr "" + +#: ../../library/errno.rst:481 +msgid "Destination address required" +msgstr "" + +#: ../../library/errno.rst:486 +msgid "Message too long" +msgstr "" + +#: ../../library/errno.rst:491 +msgid "Protocol wrong type for socket" +msgstr "" + +#: ../../library/errno.rst:496 +msgid "Protocol not available" +msgstr "" + +#: ../../library/errno.rst:501 +msgid "Protocol not supported" +msgstr "" + +#: ../../library/errno.rst:506 +msgid "Socket type not supported" +msgstr "" + +#: ../../library/errno.rst:511 +msgid "Operation not supported on transport endpoint" +msgstr "" + +#: ../../library/errno.rst:516 +msgid "Operation not supported" +msgstr "" + +#: ../../library/errno.rst:523 +msgid "Protocol family not supported" +msgstr "" + +#: ../../library/errno.rst:528 +msgid "Address family not supported by protocol" +msgstr "" + +#: ../../library/errno.rst:533 +msgid "Address already in use" +msgstr "" + +#: ../../library/errno.rst:538 +msgid "Cannot assign requested address" +msgstr "" + +#: ../../library/errno.rst:543 +msgid "Network is down" +msgstr "" + +#: ../../library/errno.rst:548 +msgid "Network is unreachable" +msgstr "" + +#: ../../library/errno.rst:553 +msgid "Network dropped connection because of reset" +msgstr "" + +#: ../../library/errno.rst:558 +msgid "" +"Software caused connection abort. This error is mapped to the " +"exception :exc:`ConnectionAbortedError`." +msgstr "" + +#: ../../library/errno.rst:564 +msgid "" +"Connection reset by peer. This error is mapped to the " +"exception :exc:`ConnectionResetError`." +msgstr "" + +#: ../../library/errno.rst:570 +msgid "No buffer space available" +msgstr "" + +#: ../../library/errno.rst:575 +msgid "Transport endpoint is already connected" +msgstr "" + +#: ../../library/errno.rst:580 +msgid "Transport endpoint is not connected" +msgstr "" + +#: ../../library/errno.rst:585 +msgid "" +"Cannot send after transport endpoint shutdown. This error is mapped to the " +"exception :exc:`BrokenPipeError`." +msgstr "" + +#: ../../library/errno.rst:591 +msgid "Too many references: cannot splice" +msgstr "" + +#: ../../library/errno.rst:596 +msgid "" +"Connection timed out. This error is mapped to the " +"exception :exc:`TimeoutError`." +msgstr "" + +#: ../../library/errno.rst:602 +msgid "" +"Connection refused. This error is mapped to the " +"exception :exc:`ConnectionRefusedError`." +msgstr "" + +#: ../../library/errno.rst:608 +msgid "Host is down" +msgstr "" + +#: ../../library/errno.rst:613 +msgid "No route to host" +msgstr "" + +#: ../../library/errno.rst:618 +msgid "Memory page has hardware error." +msgstr "" + +#: ../../library/errno.rst:625 +msgid "" +"Operation already in progress. This error is mapped to the " +"exception :exc:`BlockingIOError`." +msgstr "" + +#: ../../library/errno.rst:631 +msgid "" +"Operation now in progress. This error is mapped to the " +"exception :exc:`BlockingIOError`." +msgstr "" + +#: ../../library/errno.rst:637 +msgid "Stale NFS file handle" +msgstr "" + +#: ../../library/errno.rst:642 +msgid "Structure needs cleaning" +msgstr "" + +#: ../../library/errno.rst:647 +msgid "Not a XENIX named type file" +msgstr "" + +#: ../../library/errno.rst:652 +msgid "No XENIX semaphores available" +msgstr "" + +#: ../../library/errno.rst:657 +msgid "Is a named type file" +msgstr "" + +#: ../../library/errno.rst:662 +msgid "Remote I/O error" +msgstr "" + +#: ../../library/errno.rst:667 +msgid "Quota exceeded" +msgstr "" + +#: ../../library/errno.rst:671 +msgid "Interface output queue is full" +msgstr "" + +#: ../../library/errno.rst:678 +msgid "No medium found" +msgstr "" + +#: ../../library/errno.rst:683 +msgid "Wrong medium type" +msgstr "" + +#: ../../library/errno.rst:688 +msgid "Required key not available" +msgstr "" + +#: ../../library/errno.rst:693 +msgid "Key has expired" +msgstr "" + +#: ../../library/errno.rst:698 +msgid "Key has been revoked" +msgstr "" + +#: ../../library/errno.rst:703 +msgid "Key was rejected by service" +msgstr "" + +#: ../../library/errno.rst:708 +msgid "Operation not possible due to RF-kill" +msgstr "" + +#: ../../library/errno.rst:713 +msgid "Locked lock was unmapped" +msgstr "" + +#: ../../library/errno.rst:718 +msgid "Facility is not active" +msgstr "" + +#: ../../library/errno.rst:723 +msgid "Authentication error" +msgstr "" + +#: ../../library/errno.rst:730 +msgid "Bad CPU type in executable" +msgstr "" + +#: ../../library/errno.rst:737 +msgid "Bad executable (or shared library)" +msgstr "" + +#: ../../library/errno.rst:744 +msgid "Malformed Mach-o file" +msgstr "" + +#: ../../library/errno.rst:751 +msgid "Device error" +msgstr "裝置錯誤" + +#: ../../library/errno.rst:758 +msgid "Inappropriate file type or format" +msgstr "不適當的檔案類型或格式" + +#: ../../library/errno.rst:765 +msgid "Need authenticator" +msgstr "需要驗證器" + +#: ../../library/errno.rst:772 +msgid "Attribute not found" +msgstr "找不到屬性" + +#: ../../library/errno.rst:779 +msgid "Policy not found" +msgstr "" + +#: ../../library/errno.rst:786 +msgid "Too many processes" +msgstr "行程數量過多" + +#: ../../library/errno.rst:793 +msgid "Bad procedure for program" +msgstr "" + +#: ../../library/errno.rst:800 +msgid "Program version wrong" +msgstr "" + +#: ../../library/errno.rst:807 +msgid "RPC prog. not avail" +msgstr "" + +#: ../../library/errno.rst:814 +msgid "Device power is off" +msgstr "裝置電源關閉" + +#: ../../library/errno.rst:821 +msgid "RPC struct is bad" +msgstr "RPC 結構不正確" + +#: ../../library/errno.rst:828 +msgid "RPC version wrong" +msgstr "RPC 版本錯誤" + +#: ../../library/errno.rst:835 +msgid "Shared library version mismatch" +msgstr "共享函式庫版本不匹配" + +#: ../../library/errno.rst:842 +msgid "" +"Capabilities insufficient. This error is mapped to the " +"exception :exc:`PermissionError`." +msgstr "" + +#: ../../library/errno.rst:845 +msgid "Availability" +msgstr "可用性" + +#: ../../library/errno.rst:852 +msgid "Operation canceled" +msgstr "操作已取消" + +#: ../../library/errno.rst:859 +msgid "Owner died" +msgstr "擁有者過世" + +#: ../../library/errno.rst:866 +msgid "State not recoverable" +msgstr "狀態無法恢復" diff --git a/library/exceptions.po b/library/exceptions.po index ed37e93b45..60e2cc28c0 100644 --- a/library/exceptions.po +++ b/library/exceptions.po @@ -1,1806 +1,1806 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Leon H., 2017 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-12-17 00:14+0000\n" -"PO-Revision-Date: 2024-12-20 16:57+0800\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/exceptions.rst:4 -msgid "Built-in Exceptions" -msgstr "內建的例外" - -#: ../../library/exceptions.rst:10 -msgid "" -"In Python, all exceptions must be instances of a class that derives from :" -"class:`BaseException`. In a :keyword:`try` statement with an :keyword:" -"`except` clause that mentions a particular class, that clause also handles " -"any exception classes derived from that class (but not exception classes " -"from which *it* is derived). Two exception classes that are not related via " -"subclassing are never equivalent, even if they have the same name." -msgstr "" -"在 Python 中，所有例外必須是從 :class:`BaseException` 衍生的類別的實例。在陳" -"述式 :keyword:`try` 搭配 :keyword:`except` 子句裡提到一個特定的類別時，那個子" -"句也會處理任何從該類別衍生的例外類別（但不會處理該類別\\ *衍生自*\\ 的例外類" -"別）。兩個不是由子類別關係關聯起來的例外類別永遠不相等，就算它們有相同的名稱" -"也是如此。" - -#: ../../library/exceptions.rst:19 -msgid "" -"The built-in exceptions listed in this chapter can be generated by the " -"interpreter or built-in functions. Except where mentioned, they have an " -"\"associated value\" indicating the detailed cause of the error. This may " -"be a string or a tuple of several items of information (e.g., an error code " -"and a string explaining the code). The associated value is usually passed " -"as arguments to the exception class's constructor." -msgstr "" -"此章節裡列出的內建例外可以從直譯器或內建函式產生。除了特別提到的地方之外，它" -"們會有一個\\ *關聯值*\\ 表示錯誤發生的詳細原因。這可能是一個字串，或者是一些" -"資訊項目組成的元組（例如一個錯誤代碼及一個解釋該代碼的字串）。這個關聯值通常" -"當作引數傳遞給例外類別的建構函式。" - -#: ../../library/exceptions.rst:26 -msgid "" -"User code can raise built-in exceptions. This can be used to test an " -"exception handler or to report an error condition \"just like\" the " -"situation in which the interpreter raises the same exception; but beware " -"that there is nothing to prevent user code from raising an inappropriate " -"error." -msgstr "" -"使用者的程式碼可以引發內建例外。這可以用來測試例外處理器或者用來回報一個錯誤" -"條件，*就像*\\ 直譯器會引發相同例外的情況；但需要注意的是沒有任何方式可以避免" -"使用者的程式碼引發不適當的錯誤。" - -#: ../../library/exceptions.rst:31 -msgid "" -"The built-in exception classes can be subclassed to define new exceptions; " -"programmers are encouraged to derive new exceptions from the :exc:" -"`Exception` class or one of its subclasses, and not from :exc:" -"`BaseException`. More information on defining exceptions is available in " -"the Python Tutorial under :ref:`tut-userexceptions`." -msgstr "" -"可以從內建的例外類別定義新的例外子類別；程式設計師被鼓勵從 :exc:`Exception` " -"類別或其子類別衍生新的例外，而不是從 :exc:`BaseException` 來衍生。更多關於定" -"義例外的資訊可以在 Python 教學中的\\ :ref:`tut-userexceptions`\\ 裡取得。" - -#: ../../library/exceptions.rst:39 -msgid "Exception context" -msgstr "例外的情境" - -#: ../../library/exceptions.rst:46 -msgid "" -"Three attributes on exception objects provide information about the context " -"in which the exception was raised:" -msgstr "三個例外物件上的屬性提供關於引發此例外的情境的資訊：" - -#: ../../library/exceptions.rst:53 -msgid "" -"When raising a new exception while another exception is already being " -"handled, the new exception's :attr:`!__context__` attribute is automatically " -"set to the handled exception. An exception may be handled when an :keyword:" -"`except` or :keyword:`finally` clause, or a :keyword:`with` statement, is " -"used." -msgstr "" -"當引發一個新的例外而同時有另一個例外已經正在被處理時，這個新例外的 :attr:`!" -"__context__` 屬性會自動被設成那個已處理的例外。當使用 :keyword:`except` 或 :" -"keyword:`finally` 子句或 :keyword:`with` 陳述式的時候例外會被處理。" - -#: ../../library/exceptions.rst:59 -msgid "" -"This implicit exception context can be supplemented with an explicit cause " -"by using :keyword:`!from` with :keyword:`raise`::" -msgstr "" -"這個隱含的例外情境可以透過使用 :keyword:`!from` 搭配 :keyword:`raise` 來補充" -"明確的原因： ::" - -#: ../../library/exceptions.rst:63 -msgid "raise new_exc from original_exc" -msgstr "raise new_exc from original_exc" - -#: ../../library/exceptions.rst:65 -msgid "" -"The expression following :keyword:`from` must be an exception or " -"``None``. It will be set as :attr:`!__cause__` on the raised exception. " -"Setting :attr:`!__cause__` also implicitly sets the :attr:`!" -"__suppress_context__` attribute to ``True``, so that using ``raise new_exc " -"from None`` effectively replaces the old exception with the new one for " -"display purposes (e.g. converting :exc:`KeyError` to :exc:`AttributeError`), " -"while leaving the old exception available in :attr:`!__context__` for " -"introspection when debugging." -msgstr "" -"在 :keyword:`from` 後面的運算式必須是一個例外或 ``None``。它將會被設定" -"成所引發例外的 :attr:`!__cause__`。設定 :attr:`!__cause__` 也隱含地設定 :" -"attr:`!__suppress_context__` 屬性為 ``True``，因此使用 ``raise new_exc from " -"None`` 實際上會以新的例外取代舊的例外以利於顯示（例如轉換 :exc:`KeyError` " -"為 :exc:`AttributeError`），同時保持舊的例外可以透過 :attr:`!__context__` 取" -"得以方便 debug 的時候檢查。" - -#: ../../library/exceptions.rst:74 -msgid "" -"The default traceback display code shows these chained exceptions in " -"addition to the traceback for the exception itself. An explicitly chained " -"exception in :attr:`!__cause__` is always shown when present. An implicitly " -"chained exception in :attr:`!__context__` is shown only if :attr:`!" -"__cause__` is :const:`None` and :attr:`!__suppress_context__` is false." -msgstr "" -"預設的回溯 (traceback) 顯示程式碼會顯示這些連鎖的例外 (chained exception) 加" -"上例外本身的回溯。當存在的時候，在 :attr:`!__cause__` 中明確地連鎖的例外總是" -"會被顯示。而在 :attr:`!__context__` 中隱含地連鎖的例外只有當 :attr:`!" -"__cause__` 是 :const:`None` 且 :attr:`!__suppress_context__` 是 false 時才會" -"顯示。" - -#: ../../library/exceptions.rst:80 -msgid "" -"In either case, the exception itself is always shown after any chained " -"exceptions so that the final line of the traceback always shows the last " -"exception that was raised." -msgstr "" -"在任一種情況下，例外本身總是會顯示在任何連鎖例外的後面，因此回溯的最後一列總" -"是顯示最後一個被引發的例外。" - -#: ../../library/exceptions.rst:86 -msgid "Inheriting from built-in exceptions" -msgstr "繼承自內建的例外" - -#: ../../library/exceptions.rst:88 -msgid "" -"User code can create subclasses that inherit from an exception type. It's " -"recommended to only subclass one exception type at a time to avoid any " -"possible conflicts between how the bases handle the ``args`` attribute, as " -"well as due to possible memory layout incompatibilities." -msgstr "" -"使用者的程式碼可以建立繼承自例外型別的子類別。建議一次只繼承一種例外型別以避" -"免在基底類別之間如何處理 ``args`` 屬性的任何可能衝突，以及可能的記憶體佈局 " -"(memory layout) 不相容。" - -#: ../../library/exceptions.rst:95 -msgid "" -"Most built-in exceptions are implemented in C for efficiency, see: :source:" -"`Objects/exceptions.c`. Some have custom memory layouts which makes it " -"impossible to create a subclass that inherits from multiple exception types. " -"The memory layout of a type is an implementation detail and might change " -"between Python versions, leading to new conflicts in the future. Therefore, " -"it's recommended to avoid subclassing multiple exception types altogether." -msgstr "" -"為了效率，大部分的內建例外使用 C 來實作，參考 :source:`Objects/exceptions." -"c`。一些例外有客製化的記憶體佈局，使其不可能建立一個繼承多種例外型別的子類" -"別。型別的記憶體佈局是實作細節且可能會在不同 Python 版本間改變，造成未來新的" -"衝突。因此，總之建議避免繼承多種例外型別。" - -#: ../../library/exceptions.rst:105 -msgid "Base classes" -msgstr "基底類別 (base classes)" - -#: ../../library/exceptions.rst:107 -msgid "" -"The following exceptions are used mostly as base classes for other " -"exceptions." -msgstr "以下的例外大部分被用在當作其他例外的基底類別。" - -#: ../../library/exceptions.rst:111 -msgid "" -"The base class for all built-in exceptions. It is not meant to be directly " -"inherited by user-defined classes (for that, use :exc:`Exception`). If :" -"func:`str` is called on an instance of this class, the representation of the " -"argument(s) to the instance are returned, or the empty string when there " -"were no arguments." -msgstr "" -"所有內建例外的基底類別。這不是為了讓使用者定義的類別直接繼承（可以使用 :exc:" -"`Exception`）。如果在這個類別的實例上呼叫 :func:`str`，會回傳實例的引數的表" -"示，或者沒有引數的時候會回傳空字串。" - -#: ../../library/exceptions.rst:119 -msgid "" -"The tuple of arguments given to the exception constructor. Some built-in " -"exceptions (like :exc:`OSError`) expect a certain number of arguments and " -"assign a special meaning to the elements of this tuple, while others are " -"usually called only with a single string giving an error message." -msgstr "" -"提供給該例外建構函式的引數元組。一些內建的例外（像是 :exc:`OSError`）預期接受" -"特定數量的引數並賦予該元組的每一個元素一個特別的意義，其他例外則通常用一個提" -"供錯誤訊息的單一字串來呼叫。" - -#: ../../library/exceptions.rst:126 -msgid "" -"This method sets *tb* as the new traceback for the exception and returns the " -"exception object. It was more commonly used before the exception chaining " -"features of :pep:`3134` became available. The following example shows how " -"we can convert an instance of ``SomeException`` into an instance of " -"``OtherException`` while preserving the traceback. Once raised, the current " -"frame is pushed onto the traceback of the ``OtherException``, as would have " -"happened to the traceback of the original ``SomeException`` had we allowed " -"it to propagate to the caller. ::" -msgstr "" -"此方法設定 *tb* 為該例外的新的回溯並回傳該例外物件。在 :pep:`3134` 的例外連鎖" -"功能變得可用之前，此方法曾被更普遍使用。下面的範例顯示我們如何將 " -"``SomeException`` 的實例轉換為 ``OtherException`` 的實例同時保留回溯。一旦被" -"引發，目前的 frame 會被加進 ``OtherException`` 的回溯，就像原來 " -"``SomeException`` 的回溯會發生的一樣，我們允許它被傳遞給呼叫者： ::" - -#: ../../library/exceptions.rst:135 -msgid "" -"try:\n" -" ...\n" -"except SomeException:\n" -" tb = sys.exception().__traceback__\n" -" raise OtherException(...).with_traceback(tb)" -msgstr "" -"try:\n" -" ...\n" -"except SomeException:\n" -" tb = sys.exception().__traceback__\n" -" raise OtherException(...).with_traceback(tb)" - -#: ../../library/exceptions.rst:143 -msgid "" -"A writable field that holds the :ref:`traceback object ` " -"associated with this exception. See also: :ref:`raise`." -msgstr "" -"可寫入的欄位，儲存關聯到該例外的\\ :ref:`回溯物件 `。也可" -"以參考 :ref:`raise`。" - -#: ../../library/exceptions.rst:149 -msgid "" -"Add the string ``note`` to the exception's notes which appear in the " -"standard traceback after the exception string. A :exc:`TypeError` is raised " -"if ``note`` is not a string." -msgstr "" -"新增字串 ``note`` 到例外的備註，在標準的回溯裡，備註出現在例外字串的後面。如" -"果 ``note`` 不是字串則引發 :exc:`TypeError`。" - -#: ../../library/exceptions.rst:157 -msgid "" -"A list of the notes of this exception, which were added with :meth:" -"`add_note`. This attribute is created when :meth:`add_note` is called." -msgstr "" -"該例外的備註串列，使用 :meth:`add_note` 來新增。此屬性在 :meth:`add_note` 被" -"呼叫的時候建立。" - -#: ../../library/exceptions.rst:165 -msgid "" -"All built-in, non-system-exiting exceptions are derived from this class. " -"All user-defined exceptions should also be derived from this class." -msgstr "" -"所有內建、非系統退出 (non-system-exiting) 的例外都衍生自此類別。所有使用者定" -"義的例外應該也要衍生自此類別。" - -#: ../../library/exceptions.rst:171 -msgid "" -"The base class for those built-in exceptions that are raised for various " -"arithmetic errors: :exc:`OverflowError`, :exc:`ZeroDivisionError`, :exc:" -"`FloatingPointError`." -msgstr "" -"各種運算錯誤所引發的那些內建例外：:exc:`OverflowError`、:exc:" -"`ZeroDivisionError`、:exc:`FloatingPointError` 的基底類別。" - -#: ../../library/exceptions.rst:178 -msgid "" -"Raised when a :ref:`buffer ` related operation cannot be " -"performed." -msgstr "" -"當\\ :ref:`緩衝 (buffer) ` 相關的操作無法被執行時會引發此例" -"外。" - -#: ../../library/exceptions.rst:184 -msgid "" -"The base class for the exceptions that are raised when a key or index used " -"on a mapping or sequence is invalid: :exc:`IndexError`, :exc:`KeyError`. " -"This can be raised directly by :func:`codecs.lookup`." -msgstr "" -"當使用在對映或序列上的鍵或索引是無效的時候所引發的例外：:exc:`IndexError`、:" -"exc:`KeyError` 的基底類別。這可以被 :func:`codecs.lookup` 直接引發。" - -#: ../../library/exceptions.rst:190 -msgid "Concrete exceptions" -msgstr "實體例外" - -#: ../../library/exceptions.rst:192 -msgid "The following exceptions are the exceptions that are usually raised." -msgstr "以下的例外是通常會被引發的例外。" - -#: ../../library/exceptions.rst:198 -msgid "Raised when an :keyword:`assert` statement fails." -msgstr "當 :keyword:`assert` 陳述式失敗的時候被引發。" - -#: ../../library/exceptions.rst:203 -msgid "" -"Raised when an attribute reference (see :ref:`attribute-references`) or " -"assignment fails. (When an object does not support attribute references or " -"attribute assignments at all, :exc:`TypeError` is raised.)" -msgstr "" -"當屬性參照（參考 :ref:`attribute-references`）或賦值失敗的時候被引發。（當物" -"件根本不支援屬性參照或屬性賦值的時候，:exc:`TypeError` 會被引發。）" - -#: ../../library/exceptions.rst:207 -msgid "" -"The optional *name* and *obj* keyword-only arguments set the corresponding " -"attributes:" -msgstr "可選的僅限關鍵字引數 *name* 和 *obj* 會設定對應的屬性：" - -#: ../../library/exceptions.rst:212 -msgid "The name of the attribute that was attempted to be accessed." -msgstr "嘗試被存取的屬性名稱。" - -#: ../../library/exceptions.rst:216 -msgid "The object that was accessed for the named attribute." -msgstr "存取指定屬性的物件。" - -#: ../../library/exceptions.rst:218 -msgid "Added the :attr:`name` and :attr:`obj` attributes." -msgstr "新增 :attr:`name` 與 :attr:`obj` 屬性。" - -#: ../../library/exceptions.rst:223 -msgid "" -"Raised when the :func:`input` function hits an end-of-file condition (EOF) " -"without reading any data. (Note: the :meth:`!io.IOBase.read` and :meth:`io." -"IOBase.readline` methods return an empty string when they hit EOF.)" -msgstr "" -"當 :func:`input` 函式在沒有讀到任何資料而到達檔案結尾 (end-of-file, EOF) 條件" -"的時候被引發。（注意：:meth:`!io.IOBase.read` 和 :meth:`io.IOBase.readline` " -"方法當達到 EOF 時會回傳空字串。）" - -#: ../../library/exceptions.rst:230 -msgid "Not currently used." -msgstr "目前沒有被使用。" - -#: ../../library/exceptions.rst:235 -msgid "" -"Raised when a :term:`generator` or :term:`coroutine` is closed; see :meth:" -"`generator.close` and :meth:`coroutine.close`. It directly inherits from :" -"exc:`BaseException` instead of :exc:`Exception` since it is technically not " -"an error." -msgstr "" -"當 :term:`generator` 或 :term:`coroutine` 被關閉的時候被引發；參考 :meth:" -"`generator.close` 和 :meth:`coroutine.close`。此例外直接繼承自 :exc:" -"`BaseException` 而不是 :exc:`Exception`，因為技術上來說這不是一個錯誤。" - -#: ../../library/exceptions.rst:243 -msgid "" -"Raised when the :keyword:`import` statement has troubles trying to load a " -"module. Also raised when the \"from list\" in ``from ... import`` has a " -"name that cannot be found." -msgstr "" -"當 :keyword:`import` 陳述式嘗試載入模組遇到問題的時候會被引發。當 ``from ... " -"import`` 裡的 \"from list\" 包含找不到的名稱時也會被引發。" - -#: ../../library/exceptions.rst:247 -msgid "" -"The optional *name* and *path* keyword-only arguments set the corresponding " -"attributes:" -msgstr "可選的僅限關鍵字引數 *name* 和 *path* 設定對應的屬性：" - -#: ../../library/exceptions.rst:252 -msgid "The name of the module that was attempted to be imported." -msgstr "嘗試引入 (import) 的模組名稱。" - -#: ../../library/exceptions.rst:256 -msgid "The path to any file which triggered the exception." -msgstr "觸發此例外的任何檔案的路徑。" - -#: ../../library/exceptions.rst:258 -msgid "Added the :attr:`name` and :attr:`path` attributes." -msgstr "新增 :attr:`name` 與 :attr:`path` 屬性。" - -#: ../../library/exceptions.rst:263 -msgid "" -"A subclass of :exc:`ImportError` which is raised by :keyword:`import` when a " -"module could not be located. It is also raised when ``None`` is found in :" -"data:`sys.modules`." -msgstr "" -":exc:`ImportError` 的子類別，當模組不能被定位的時候會被 :keyword:`import` 所" -"引發。當在 :data:`sys.modules` 裡找到 ``None`` 時也會被引發。" - -#: ../../library/exceptions.rst:272 -msgid "" -"Raised when a sequence subscript is out of range. (Slice indices are " -"silently truncated to fall in the allowed range; if an index is not an " -"integer, :exc:`TypeError` is raised.)" -msgstr "" -"當序列的索引超出範圍的時候會被引發。（切片索引 (slice indices) 會默默地被截短" -"使其能落在允許的範圍內；如果索引不是整數，:exc:`TypeError` 會被引發。）" - -#: ../../library/exceptions.rst:281 -msgid "" -"Raised when a mapping (dictionary) key is not found in the set of existing " -"keys." -msgstr "當對映（字典）的鍵無法在已存在的鍵的集合中被找到時會被引發。" - -#: ../../library/exceptions.rst:288 -msgid "" -"Raised when the user hits the interrupt key (normally :kbd:`Control-C` or :" -"kbd:`Delete`). During execution, a check for interrupts is made regularly. " -"The exception inherits from :exc:`BaseException` so as to not be " -"accidentally caught by code that catches :exc:`Exception` and thus prevent " -"the interpreter from exiting." -msgstr "" -"當使用者輸入中斷鍵 (interrupt key)（一般來說是 :kbd:`Control-C` 或 :kbd:" -"`Delete`）時會被引發。在執行過程中，會定期檢查是否產生中斷。此例外繼承自 :" -"exc:`BaseException` 以防止意外地被捕捉 :exc:`Exception` 的程式碼所捕捉，而因" -"此讓直譯器無法結束。" - -#: ../../library/exceptions.rst:296 -msgid "" -"Catching a :exc:`KeyboardInterrupt` requires special consideration. Because " -"it can be raised at unpredictable points, it may, in some circumstances, " -"leave the running program in an inconsistent state. It is generally best to " -"allow :exc:`KeyboardInterrupt` to end the program as quickly as possible or " -"avoid raising it entirely. (See :ref:`handlers-and-exceptions`.)" -msgstr "" -"捕捉 :exc:`KeyboardInterrupt` 需要特殊的考量。因為它可以在無法預期的時間點被" -"引發，可能在某些情況下讓正在跑的程式處在一個不一致的狀態。一般來說最好讓 :" -"exc:`KeyboardInterrupt` 越快結束程式越好，或者完全避免引發它。（參考 :ref:" -"`handlers-and-exceptions`。）" - -#: ../../library/exceptions.rst:306 -msgid "" -"Raised when an operation runs out of memory but the situation may still be " -"rescued (by deleting some objects). The associated value is a string " -"indicating what kind of (internal) operation ran out of memory. Note that " -"because of the underlying memory management architecture (C's :c:func:" -"`malloc` function), the interpreter may not always be able to completely " -"recover from this situation; it nevertheless raises an exception so that a " -"stack traceback can be printed, in case a run-away program was the cause." -msgstr "" -"當一個操作用光了記憶體但情況還可能被修復 (rescued)（透過刪除一些物件）的時候" -"被引發。關聯值是一個字串，表示什麼類型的（內部）操作用光了記憶體。需注意的是" -"因為底層的記憶體管理架構（C 的 :c:func:`malloc` 函式），直譯器可能無法總是完" -"整地從該情況中修復；僅管如此，它還是引發例外以讓堆疊回溯可以被印出，以防原因" -"出在失控的程式。" - -#: ../../library/exceptions.rst:317 -msgid "" -"Raised when a local or global name is not found. This applies only to " -"unqualified names. The associated value is an error message that includes " -"the name that could not be found." -msgstr "" -"當找不到本地或全域的名稱時會被引發。這只應用在不合格的名稱 (unqualified " -"name) 上。關聯值是一個錯誤訊息，包含那個無法被找到的名稱。" - -#: ../../library/exceptions.rst:321 -msgid "The optional *name* keyword-only argument sets the attribute:" -msgstr "可選的僅限關鍵字引數 *name* 設定對應的屬性：" - -#: ../../library/exceptions.rst:325 -msgid "The name of the variable that was attempted to be accessed." -msgstr "嘗試被存取的變數名稱。" - -#: ../../library/exceptions.rst:327 -msgid "Added the :attr:`name` attribute." -msgstr "新增 :attr:`name` 屬性。" - -#: ../../library/exceptions.rst:333 -msgid "" -"This exception is derived from :exc:`RuntimeError`. In user defined base " -"classes, abstract methods should raise this exception when they require " -"derived classes to override the method, or while the class is being " -"developed to indicate that the real implementation still needs to be added." -msgstr "" -"此例外衍生自 :exc:`RuntimeError`。在使用者定義的基礎類別裡，當抽象方法要求衍" -"生類別覆寫該方法時應該要引發此例外，或者當類別正在開發中，可用此例外表示還需" -"要加入真正的實作。" - -#: ../../library/exceptions.rst:340 -msgid "" -"It should not be used to indicate that an operator or method is not meant to " -"be supported at all -- in that case either leave the operator / method " -"undefined or, if a subclass, set it to :data:`None`." -msgstr "" -"此例外不應該用來表示根本沒有要支援的運算子或方法 ── 在這個情況下可以讓該運算" -"子或方法保持未定義，或者如果是子類別的話將其設成 :data:`None`。" - -#: ../../library/exceptions.rst:346 -msgid "" -":exc:`!NotImplementedError` and :data:`!NotImplemented` are not " -"interchangeable. This exception should only be used as described above; see :" -"data:`NotImplemented` for details on correct usage of the built-in constant." -msgstr "" -":exc:`!NotImplementedError` 和 :data:`!NotImplemented` 並不是可互換的。這個例" -"外只能用在上面描述的情況；參考 :data:`NotImplemented` 裡關於內建常數正確使用" -"方法的細節。" - -#: ../../library/exceptions.rst:357 -msgid "" -"This exception is raised when a system function returns a system-related " -"error, including I/O failures such as \"file not found\" or \"disk " -"full\" (not for illegal argument types or other incidental errors)." -msgstr "" -"當系統函式回傳系統相關錯誤，包含像\"找不到檔案\"或\"硬碟已滿\"的 I/O 失敗會引" -"發此例外（而非不合法的引數或其他次要的錯誤）。" - -#: ../../library/exceptions.rst:361 -msgid "" -"The second form of the constructor sets the corresponding attributes, " -"described below. The attributes default to :const:`None` if not specified. " -"For backwards compatibility, if three arguments are passed, the :attr:" -"`~BaseException.args` attribute contains only a 2-tuple of the first two " -"constructor arguments." -msgstr "" -"建構函式的第二種形式會設定以下描述的相對應屬性。如果沒有給定則屬性預設為 :" -"const:`None`。為了向後相容，如果傳入三個引數，:attr:`~BaseException.args` 屬" -"性只會是包含建構函式前兩個引數的雙元素元組。" - -#: ../../library/exceptions.rst:367 -msgid "" -"The constructor often actually returns a subclass of :exc:`OSError`, as " -"described in `OS exceptions`_ below. The particular subclass depends on the " -"final :attr:`.errno` value. This behaviour only occurs when constructing :" -"exc:`OSError` directly or via an alias, and is not inherited when " -"subclassing." -msgstr "" -"如同下面的\\ `作業系統例外 `_\\ 所描述，實際上建構函式通常回" -"傳 :exc:`OSError` 的子類別。會依據最後 :attr:`.errno` 的值決定特定子類別。這" -"個行為只發生在直接建構 :exc:`OSError` 或透過別名，且產生子類別的時候不會被繼" -"承。" - -#: ../../library/exceptions.rst:375 -msgid "A numeric error code from the C variable :c:data:`errno`." -msgstr "從 C 變數 :c:data:`errno` 而來的數值錯誤代碼。" - -#: ../../library/exceptions.rst:379 -msgid "" -"Under Windows, this gives you the native Windows error code. The :attr:`." -"errno` attribute is then an approximate translation, in POSIX terms, of that " -"native error code." -msgstr "" -"在 Windows 下，這會提供你原生的 Windows 錯誤代碼。而 :attr:`.errno` 屬性是一" -"個該原生錯誤代碼對於 POSIX 來說的近似翻譯。" - -#: ../../library/exceptions.rst:383 -msgid "" -"Under Windows, if the *winerror* constructor argument is an integer, the :" -"attr:`.errno` attribute is determined from the Windows error code, and the " -"*errno* argument is ignored. On other platforms, the *winerror* argument is " -"ignored, and the :attr:`winerror` attribute does not exist." -msgstr "" -"在 Windows 下，如果建構函式引數 *winerror* 是整數，則 :attr:`.errno` 屬性會根" -"據該 Windows 錯誤代碼來決定，且 *errno* 引數會被忽略。在其他平台上，" -"*winerror* 引數會被忽略，而 :attr:`winerror` 屬性會不存在。" - -#: ../../library/exceptions.rst:391 -msgid "" -"The corresponding error message, as provided by the operating system. It is " -"formatted by the C functions :c:func:`!perror` under POSIX, and :c:func:`!" -"FormatMessage` under Windows." -msgstr "" -"作業系統提供的對應錯誤訊息。在 POSIX 下會使用 C 函式 :c:func:`!perror` 做格式" -"化，而在 Windows 下會使用 :c:func:`!FormatMessage`。" - -#: ../../library/exceptions.rst:399 -msgid "" -"For exceptions that involve a file system path (such as :func:`open` or :" -"func:`os.unlink`), :attr:`filename` is the file name passed to the function. " -"For functions that involve two file system paths (such as :func:`os." -"rename`), :attr:`filename2` corresponds to the second file name passed to " -"the function." -msgstr "" -"對於包含檔案系統路徑的例外（像是 :func:`open` 或 :func:`os.unlink`），:attr:" -"`filename` 是傳入函式的檔案名稱。對於包含兩個檔案系統路徑的函式（像是 :func:" -"`os.rename`），:attr:`filename2` 對應到傳入函式的第二個檔案名稱。" - -#: ../../library/exceptions.rst:406 -msgid "" -":exc:`EnvironmentError`, :exc:`IOError`, :exc:`WindowsError`, :exc:`socket." -"error`, :exc:`select.error` and :exc:`!mmap.error` have been merged into :" -"exc:`OSError`, and the constructor may return a subclass." -msgstr "" -":exc:`EnvironmentError`、:exc:`IOError`、:exc:`WindowsError`、:exc:`socket." -"error`、:exc:`select.error` 及 :exc:`!mmap.error` 已合併進 :exc:`OSError`，而" -"建構函式可能會回傳子類別。" - -#: ../../library/exceptions.rst:412 -msgid "" -"The :attr:`filename` attribute is now the original file name passed to the " -"function, instead of the name encoded to or decoded from the :term:" -"`filesystem encoding and error handler`. Also, the *filename2* constructor " -"argument and attribute was added." -msgstr "" -":attr:`filename` 屬性現在是傳入函式的原始檔名，而不是從\\ :term:`檔案系統編碼" -"和錯誤處理函式 `\\ 編碼或解碼過的名" -"稱。並且新增 *filename2* 建構函式引數與屬性。" - -#: ../../library/exceptions.rst:421 -msgid "" -"Raised when the result of an arithmetic operation is too large to be " -"represented. This cannot occur for integers (which would rather raise :exc:" -"`MemoryError` than give up). However, for historical reasons, OverflowError " -"is sometimes raised for integers that are outside a required range. " -"Because of the lack of standardization of floating-point exception handling " -"in C, most floating-point operations are not checked." -msgstr "" -"當運算操作的結果太大而無法表示的時候會引發此例外。這不會發生在整數上（會改成" -"引發 :exc:`MemoryError` 而不是放棄）。然而，因為一些歷史因素，OverflowError " -"有時候會因為整數在要求範圍之外而引發。因為在 C 裡面缺乏浮點數例外處理的標準" -"化，大部分的浮點數運算都沒有被檢查。" - -#: ../../library/exceptions.rst:431 -msgid "" -"This exception is derived from :exc:`RuntimeError`. It is raised when an " -"operation is blocked during interpreter shutdown also known as :term:`Python " -"finalization `." -msgstr "" -"此例外衍生自 :exc:`RuntimeError`。當一個操作在直譯器關閉（也稱作 :term:" -"`Python 最終化 (Python finalization） `）期間被阻塞會引" -"發此例外。" - -#: ../../library/exceptions.rst:435 -msgid "" -"Examples of operations which can be blocked with a :exc:" -"`PythonFinalizationError` during the Python finalization:" -msgstr "" -"在 Python 最終化期間，能夠以 :exc:`PythonFinalizationError` 被阻塞的操作範" -"例：" - -#: ../../library/exceptions.rst:438 -msgid "Creating a new Python thread." -msgstr "建立新的 Python 執行緒。" - -#: ../../library/exceptions.rst:439 -msgid ":meth:`Joining ` a running daemon thread." -msgstr "" - -#: ../../library/exceptions.rst:440 -msgid ":func:`os.fork`." -msgstr ":func:`os.fork`。" - -#: ../../library/exceptions.rst:442 -msgid "See also the :func:`sys.is_finalizing` function." -msgstr "也可以參閱 :func:`sys.is_finalizing` 函式。" - -#: ../../library/exceptions.rst:444 ../../library/exceptions.rst:457 -msgid "Previously, a plain :exc:`RuntimeError` was raised." -msgstr "在之前，會引發一般的 :exc:`RuntimeError`。" - -#: ../../library/exceptions.rst:449 -msgid ":meth:`threading.Thread.join` can now raise this exception." -msgstr "" - -#: ../../library/exceptions.rst:453 -msgid "" -"This exception is derived from :exc:`RuntimeError`. It is raised when the " -"interpreter detects that the maximum recursion depth (see :func:`sys." -"getrecursionlimit`) is exceeded." -msgstr "" -"此例外衍生自 :exc:`RuntimeError`。當直譯器偵測到超過最大的遞迴深度（參考 :" -"func:`sys.getrecursionlimit`）時會引發此例外。" - -#: ../../library/exceptions.rst:463 -msgid "" -"This exception is raised when a weak reference proxy, created by the :func:" -"`weakref.proxy` function, is used to access an attribute of the referent " -"after it has been garbage collected. For more information on weak " -"references, see the :mod:`weakref` module." -msgstr "" -"當一個被 :func:`weakref.proxy` 函式建立的弱參照代理 (weak reference proxy) 被" -"用來存取已經被垃圾回收 (garbage collected) 的參照物屬性時會引發此例外。更多關" -"於弱參照的資訊參考 :mod:`weakref` 模組。" - -#: ../../library/exceptions.rst:471 -msgid "" -"Raised when an error is detected that doesn't fall in any of the other " -"categories. The associated value is a string indicating what precisely went " -"wrong." -msgstr "" -"當偵測到一個不屬於任何其他種類的錯誤時會引發此例外。關聯值是一個表示確切什麼" -"地方出錯的字串。" - -#: ../../library/exceptions.rst:478 -msgid "" -"Raised by built-in function :func:`next` and an :term:`iterator`\\'s :meth:" -"`~iterator.__next__` method to signal that there are no further items " -"produced by the iterator." -msgstr "" -"會被內建函式 :func:`next` 及 :term:`iterator` 的 :meth:`~iterator.__next__` " -"方法引發，用來表示疊代器沒有更多項目可以產生。" - -#: ../../library/exceptions.rst:484 -msgid "" -"The exception object has a single attribute :attr:`!value`, which is given " -"as an argument when constructing the exception, and defaults to :const:" -"`None`." -msgstr "" -"此例外物件有單一屬性 :attr:`!value`，當建構此例外時會以引數給定，預設為 :" -"const:`None`。" - -#: ../../library/exceptions.rst:488 -msgid "" -"When a :term:`generator` or :term:`coroutine` function returns, a new :exc:" -"`StopIteration` instance is raised, and the value returned by the function " -"is used as the :attr:`value` parameter to the constructor of the exception." -msgstr "" -"當 :term:`generator` 或 :term:`coroutine` 函式回傳時，新的 :exc:" -"`StopIteration` 實例會被引發，而該函式的回傳值會被用來當作此例外建構函式的 :" -"attr:`value` 參數。" - -#: ../../library/exceptions.rst:493 -msgid "" -"If a generator code directly or indirectly raises :exc:`StopIteration`, it " -"is converted into a :exc:`RuntimeError` (retaining the :exc:`StopIteration` " -"as the new exception's cause)." -msgstr "" -"如果產生器程式直接或間接引發 :exc:`StopIteration`，則其會被轉換成 :exc:" -"`RuntimeError`\\ （保留 :exc:`StopIteration` 作為新例外的成因）。" - -#: ../../library/exceptions.rst:497 -msgid "" -"Added ``value`` attribute and the ability for generator functions to use it " -"to return a value." -msgstr "新增 ``value`` 屬性且產生器函式可以用它來回傳值。" - -#: ../../library/exceptions.rst:501 -msgid "" -"Introduced the RuntimeError transformation via ``from __future__ import " -"generator_stop``, see :pep:`479`." -msgstr "" -"透過 ``from __future__ import generator_stop`` 引入 RuntimeError 的轉換，參" -"考 :pep:`479`。" - -#: ../../library/exceptions.rst:505 -msgid "" -"Enable :pep:`479` for all code by default: a :exc:`StopIteration` error " -"raised in a generator is transformed into a :exc:`RuntimeError`." -msgstr "" -"預設對所有程式啟用 :pep:`479`：在產生器引發的 :exc:`StopIteration` 錯誤會轉換" -"成 :exc:`RuntimeError`。" - -#: ../../library/exceptions.rst:511 -msgid "" -"Must be raised by :meth:`~object.__anext__` method of an :term:`asynchronous " -"iterator` object to stop the iteration." -msgstr "" -"此例外必須被 :term:`asynchronous iterator` 物件的 :meth:`~object.__anext__` " -"方法引發來停止疊代。" - -#: ../../library/exceptions.rst:518 -msgid "" -"Raised when the parser encounters a syntax error. This may occur in an :" -"keyword:`import` statement, in a call to the built-in functions :func:" -"`compile`, :func:`exec`, or :func:`eval`, or when reading the initial script " -"or standard input (also interactively)." -msgstr "" -"當剖析器遇到語法錯誤時會引發此例外。這可能發生在 :keyword:`import` 陳述式、在" -"呼叫內建函式 :func:`compile`、:func:`exec` 或 :func:`eval` 的時候，或者在讀取" -"初始腳本或標準輸入（也包含互動式）的時候。" - -#: ../../library/exceptions.rst:524 -msgid "" -"The :func:`str` of the exception instance returns only the error message. " -"Details is a tuple whose members are also available as separate attributes." -msgstr "" -"例外實例的 :func:`str` 只回傳錯誤訊息。Details 是個元組，其成員也能夠以分開的" -"屬性取得。" - -#: ../../library/exceptions.rst:529 -msgid "The name of the file the syntax error occurred in." -msgstr "發生語法錯誤所在的檔案名稱。" - -#: ../../library/exceptions.rst:533 -msgid "" -"Which line number in the file the error occurred in. This is 1-indexed: the " -"first line in the file has a ``lineno`` of 1." -msgstr "" -"發生錯誤所在檔案的列號。這是以 1 開始的索引：檔案第一列的 ``lineno`` 是 1。" - -#: ../../library/exceptions.rst:538 -msgid "" -"The column in the line where the error occurred. This is 1-indexed: the " -"first character in the line has an ``offset`` of 1." -msgstr "" -"發生錯誤所在該列的欄號 (column)。這是以 1 開始的索引：該列第一個字元的 " -"``offset`` 是 1。" - -#: ../../library/exceptions.rst:543 -msgid "The source code text involved in the error." -msgstr "涉及該錯誤的原始程式碼文字。" - -#: ../../library/exceptions.rst:547 -msgid "" -"Which line number in the file the error occurred ends in. This is 1-indexed: " -"the first line in the file has a ``lineno`` of 1." -msgstr "" -"發生錯誤所在檔案的結束列號。這是以 1 開始的索引：檔案第一列的 ``lineno`` 是 " -"1。" - -#: ../../library/exceptions.rst:552 -msgid "" -"The column in the end line where the error occurred finishes. This is 1-" -"indexed: the first character in the line has an ``offset`` of 1." -msgstr "" -"發生錯誤所在該結束列的欄號。這是以 1 開始的索引：該列第一個字元的 ``offset`` " -"是 1。" - -#: ../../library/exceptions.rst:555 -msgid "" -"For errors in f-string fields, the message is prefixed by \"f-string: \" and " -"the offsets are offsets in a text constructed from the replacement " -"expression. For example, compiling f'Bad {a b} field' results in this args " -"attribute: ('f-string: ...', ('', 1, 2, '(a b)\\n', 1, 5))." -msgstr "" -"對於發生在 f-string 欄位的錯誤，訊息會以 \"f-string: \" 為前綴，而偏移量 " -"(offset) 是從替代運算式建構的文字的偏移量。例如編譯 f'Bad {a b} field' 會得到" -"這個 args 屬性：('f-string: ...', ('', 1, 2, '(a b)\\n', 1, 5))。" - -#: ../../library/exceptions.rst:560 -msgid "Added the :attr:`end_lineno` and :attr:`end_offset` attributes." -msgstr "新增 :attr:`end_lineno` 與 :attr:`end_offset` 屬性。" - -#: ../../library/exceptions.rst:565 -msgid "" -"Base class for syntax errors related to incorrect indentation. This is a " -"subclass of :exc:`SyntaxError`." -msgstr "" -"與不正確的縮排有關的語法錯誤的基礎類別。這是 :exc:`SyntaxError` 的子類別。" - -#: ../../library/exceptions.rst:571 -msgid "" -"Raised when indentation contains an inconsistent use of tabs and spaces. " -"This is a subclass of :exc:`IndentationError`." -msgstr "" -"當縮排包含製表符號 (tab) 和空白的不一致用法時會引發此例外。這是 :exc:" -"`IndentationError` 的子類別。" - -#: ../../library/exceptions.rst:577 -msgid "" -"Raised when the interpreter finds an internal error, but the situation does " -"not look so serious to cause it to abandon all hope. The associated value is " -"a string indicating what went wrong (in low-level terms). In :term:" -"`CPython`, this could be raised by incorrectly using Python's C API, such as " -"returning a ``NULL`` value without an exception set." -msgstr "" -"當直譯器找到一個內部錯誤，但該情況看起來沒有嚴重到要讓它放棄所有的希望時會引" -"發此例外。關聯值是一個表示什麼地方出錯的字串（以低階的方式表達）。在 :term:" -"`CPython` 中，這可能是因為錯誤地使用 Python 的 C API，例如回傳一個 ``NULL`` " -"值而沒有設定例外。" - -#: ../../library/exceptions.rst:583 -msgid "" -"If you're confident that this exception wasn't your fault, or the fault of a " -"package you're using, you should report this to the author or maintainer of " -"your Python interpreter. Be sure to report the version of the Python " -"interpreter (``sys.version``; it is also printed at the start of an " -"interactive Python session), the exact error message (the exception's " -"associated value) and if possible the source of the program that triggered " -"the error." -msgstr "" -"如果你確定這個例外不是你的或者所用套件的錯，你應該向你的 Python 直譯器作者或" -"維護者回報此錯誤。務必要回報該 Python 直譯器的版本（``sys.version``；這也會在" -"互動式 Python 會話的開頭被印出）、確切的錯誤訊息（該例外的關聯值）及如果可能" -"的話，觸發此錯誤的程式來源。" - -#: ../../library/exceptions.rst:594 -msgid "" -"This exception is raised by the :func:`sys.exit` function. It inherits " -"from :exc:`BaseException` instead of :exc:`Exception` so that it is not " -"accidentally caught by code that catches :exc:`Exception`. This allows the " -"exception to properly propagate up and cause the interpreter to exit. When " -"it is not handled, the Python interpreter exits; no stack traceback is " -"printed. The constructor accepts the same optional argument passed to :func:" -"`sys.exit`. If the value is an integer, it specifies the system exit status " -"(passed to C's :c:func:`!exit` function); if it is ``None``, the exit status " -"is zero; if it has another type (such as a string), the object's value is " -"printed and the exit status is one." -msgstr "" -"此例外會被 :func:`sys.exit` 函式引發。它繼承自 :exc:`BaseException` 而不是 :" -"exc:`Exception` 因此不會被捕捉 :exc:`Exception` 的程式意外地捕捉。這允許例外" -"可以正確地向上傳遞並導致直譯器結束。當它未被處理時，Python 直譯器會結束；不會" -"印出堆疊回溯。建構函式接受跟傳入 :func:`sys.exit` 一樣的可選引數。如果該值是" -"整數，它會指定系統的結束狀態（傳入 C 的 :c:func:`!exit` 函式）；如果它是 " -"``None``，結束狀態會是 0；如果它是其他型別（例如字串），則物件的值會被印出而" -"結束狀態是 1。" - -#: ../../library/exceptions.rst:605 -msgid "" -"A call to :func:`sys.exit` is translated into an exception so that clean-up " -"handlers (:keyword:`finally` clauses of :keyword:`try` statements) can be " -"executed, and so that a debugger can execute a script without running the " -"risk of losing control. The :func:`os._exit` function can be used if it is " -"absolutely positively necessary to exit immediately (for example, in the " -"child process after a call to :func:`os.fork`)." -msgstr "" -"對 :func:`sys.exit` 的呼叫會轉譯成例外讓負責清理的處理函式（:keyword:`try` 陳" -"述式的 :keyword:`finally` 子句）可以被執行，且讓除錯器可以在不冒著失去控制的" -"風險下執行腳本。如果在絕對有必要立即結束的情況（例如在子行程呼叫完 :func:`os." -"fork` 之後 ）可以使用 :func:`os._exit` 函式。" - -#: ../../library/exceptions.rst:614 -msgid "" -"The exit status or error message that is passed to the constructor. " -"(Defaults to ``None``.)" -msgstr "傳入建構函式的結束狀態或錯誤訊息。（預設是 ``None``。 ）" - -#: ../../library/exceptions.rst:620 -msgid "" -"Raised when an operation or function is applied to an object of " -"inappropriate type. The associated value is a string giving details about " -"the type mismatch." -msgstr "" -"當一個操作或函式被用在不適合的型別的物件時會引發此例外。關聯值是一個字串，提" -"供關於不相符型別的細節。" - -#: ../../library/exceptions.rst:623 -msgid "" -"This exception may be raised by user code to indicate that an attempted " -"operation on an object is not supported, and is not meant to be. If an " -"object is meant to support a given operation but has not yet provided an " -"implementation, :exc:`NotImplementedError` is the proper exception to raise." -msgstr "" -"此例外可能被使用者程式碼引發，以表示並不支援物件上所嘗試的操作，且本來就無意" -"這樣做。如果一個物件有意要支援某個給定的操作但尚未提供實作，該引發的正確例外" -"是 :exc:`NotImplementedError`。" - -#: ../../library/exceptions.rst:628 -msgid "" -"Passing arguments of the wrong type (e.g. passing a :class:`list` when an :" -"class:`int` is expected) should result in a :exc:`TypeError`, but passing " -"arguments with the wrong value (e.g. a number outside expected boundaries) " -"should result in a :exc:`ValueError`." -msgstr "" -"傳入錯誤型別的引數（例如當預期傳入 :class:`int` 卻傳入 :class:`list`）應該要" -"導致 :exc:`TypeError`，但傳入帶有錯誤值的引數（例如超出預期範圍的數值）應該要" -"導致 :exc:`ValueError`。" - -#: ../../library/exceptions.rst:635 -msgid "" -"Raised when a reference is made to a local variable in a function or method, " -"but no value has been bound to that variable. This is a subclass of :exc:" -"`NameError`." -msgstr "" -"當在函式或方法裡引用某個區域變數，但該變數尚未被繫結到任何值的時候會引發此例" -"外。這是 :exc:`NameError` 的子類別。" - -#: ../../library/exceptions.rst:642 -msgid "" -"Raised when a Unicode-related encoding or decoding error occurs. It is a " -"subclass of :exc:`ValueError`." -msgstr "" -"當 Unicode 相關的編碼或解碼錯誤發生時會引發此例外。這是 :exc:`ValueError` 的" -"子類別。" - -#: ../../library/exceptions.rst:645 -msgid "" -":exc:`UnicodeError` has attributes that describe the encoding or decoding " -"error. For example, ``err.object[err.start:err.end]`` gives the particular " -"invalid input that the codec failed on." -msgstr "" -":exc:`UnicodeError` 有屬性描述編碼或解碼錯誤。例如 ``err.object[err.start:" -"err.end]`` 會提供讓編解碼器失敗的具體無效輸入。" - -#: ../../library/exceptions.rst:651 -msgid "The name of the encoding that raised the error." -msgstr "引發錯誤的編碼名稱。" - -#: ../../library/exceptions.rst:655 -msgid "A string describing the specific codec error." -msgstr "描述特定編解碼器錯誤的字串。" - -#: ../../library/exceptions.rst:659 -msgid "The object the codec was attempting to encode or decode." -msgstr "編解碼器嘗試編碼或解碼的物件。" - -#: ../../library/exceptions.rst:663 -msgid "The first index of invalid data in :attr:`object`." -msgstr "在 :attr:`object` 中無效資料的開始索引。" - -#: ../../library/exceptions.rst:665 ../../library/exceptions.rst:672 -msgid "" -"This value should not be negative as it is interpreted as an absolute offset " -"but this constraint is not enforced at runtime." -msgstr "" - -#: ../../library/exceptions.rst:670 -msgid "The index after the last invalid data in :attr:`object`." -msgstr "在 :attr:`object` 中最後的無效資料後的索引。" - -#: ../../library/exceptions.rst:678 -msgid "" -"Raised when a Unicode-related error occurs during encoding. It is a " -"subclass of :exc:`UnicodeError`." -msgstr "" -"在編碼當中發生 Unicode 相關錯誤時會引發此例外。這是 :exc:`UnicodeError` 的子" -"類別。" - -#: ../../library/exceptions.rst:684 -msgid "" -"Raised when a Unicode-related error occurs during decoding. It is a " -"subclass of :exc:`UnicodeError`." -msgstr "" -"在解碼當中發生 Unicode 相關錯誤時會引發此例外。這是 :exc:`UnicodeError` 的子" -"類別。" - -#: ../../library/exceptions.rst:690 -msgid "" -"Raised when a Unicode-related error occurs during translating. It is a " -"subclass of :exc:`UnicodeError`." -msgstr "" -"在轉譯當中發生 Unicode 相關錯誤時會引發此例外。這是 :exc:`UnicodeError` 的子" -"類別。" - -#: ../../library/exceptions.rst:696 -msgid "" -"Raised when an operation or function receives an argument that has the right " -"type but an inappropriate value, and the situation is not described by a " -"more precise exception such as :exc:`IndexError`." -msgstr "" -"當一個操作或函式收到引數是正確型別但是不適合的值，且該情況無法被更精確的例外" -"例如 :exc:`IndexError` 所描述時會引發此例外。" - -#: ../../library/exceptions.rst:703 -msgid "" -"Raised when the second argument of a division or modulo operation is zero. " -"The associated value is a string indicating the type of the operands and the " -"operation." -msgstr "" -"當除法或模數運算 (modulo operation) 的第二個引數是 0 的時候會引發此例外。關聯" -"值是一個字串，表示運算元及運算的類型。" - -#: ../../library/exceptions.rst:708 -msgid "" -"The following exceptions are kept for compatibility with previous versions; " -"starting from Python 3.3, they are aliases of :exc:`OSError`." -msgstr "" -"以下例外是為了相容於之前版本而保留；從 Python 3.3 開始，它們是 :exc:" -"`OSError` 的別名。" - -#: ../../library/exceptions.rst:717 -msgid "Only available on Windows." -msgstr "僅限於在 Windows 中使用。" - -#: ../../library/exceptions.rst:721 -msgid "OS exceptions" -msgstr "作業系統例外" - -#: ../../library/exceptions.rst:723 -msgid "" -"The following exceptions are subclasses of :exc:`OSError`, they get raised " -"depending on the system error code." -msgstr "以下的例外是 :exc:`OSError` 的子類別，它們根據系統錯誤代碼來引發。" - -#: ../../library/exceptions.rst:728 -msgid "" -"Raised when an operation would block on an object (e.g. socket) set for non-" -"blocking operation. Corresponds to :c:data:`errno` :py:const:`~errno." -"EAGAIN`, :py:const:`~errno.EALREADY`, :py:const:`~errno.EWOULDBLOCK` and :py:" -"const:`~errno.EINPROGRESS`." -msgstr "" -"當設置為非阻塞操作的物件（例如 socket）上的操作將要阻塞時會引發此例外。對應" -"到 :c:data:`errno` :py:const:`~errno.EAGAIN`、:py:const:`~errno.EALREADY`、:" -"py:const:`~errno.EWOULDBLOCK` 及 :py:const:`~errno.EINPROGRESS`。" - -#: ../../library/exceptions.rst:733 -msgid "" -"In addition to those of :exc:`OSError`, :exc:`BlockingIOError` can have one " -"more attribute:" -msgstr "" -"除了 :exc:`OSError` 的那些屬性之外，:exc:`BlockingIOError` 有多一個屬性：" - -#: ../../library/exceptions.rst:738 -msgid "" -"An integer containing the number of **bytes** written to the stream before " -"it blocked. This attribute is available when using the buffered I/O classes " -"from the :mod:`io` module." -msgstr "" -"一個整數，內容為在其阻塞之前，已寫進串流的\\ **位元組**\\ 數。當使用 :mod:`io` 模組裡的緩" -"衝 I/O 類別時這個屬性是可用的。" - -#: ../../library/exceptions.rst:744 -msgid "" -"Raised when an operation on a child process failed. Corresponds to :c:data:" -"`errno` :py:const:`~errno.ECHILD`." -msgstr "" -"當子行程上的操作失敗時會引發此例外。對應到 :c:data:`errno` :py:const:`~errno." -"ECHILD`。" - -#: ../../library/exceptions.rst:749 -msgid "A base class for connection-related issues." -msgstr "連線相關問題的基礎類別。" - -#: ../../library/exceptions.rst:751 -msgid "" -"Subclasses are :exc:`BrokenPipeError`, :exc:`ConnectionAbortedError`, :exc:" -"`ConnectionRefusedError` and :exc:`ConnectionResetError`." -msgstr "" -"子類別有 :exc:`BrokenPipeError`、:exc:`ConnectionAbortedError`、:exc:" -"`ConnectionRefusedError` 及 :exc:`ConnectionResetError`。" - -#: ../../library/exceptions.rst:756 -msgid "" -"A subclass of :exc:`ConnectionError`, raised when trying to write on a pipe " -"while the other end has been closed, or trying to write on a socket which " -"has been shutdown for writing. Corresponds to :c:data:`errno` :py:const:" -"`~errno.EPIPE` and :py:const:`~errno.ESHUTDOWN`." -msgstr "" -":exc:`ConnectionError` 的子類別，當嘗試寫入管道 (pipe) 同時另一端已經被關閉時" -"會引發此例外，或者當嘗試寫入已關閉寫入的 socket 時也會引發。對應到 :c:data:" -"`errno` :py:const:`~errno.EPIPE` 及 :py:const:`~errno.ESHUTDOWN`。" - -#: ../../library/exceptions.rst:763 -msgid "" -"A subclass of :exc:`ConnectionError`, raised when a connection attempt is " -"aborted by the peer. Corresponds to :c:data:`errno` :py:const:`~errno." -"ECONNABORTED`." -msgstr "" -":exc:`ConnectionError` 的子類別。當一個連線的嘗試被對等端點 (peer) 中斷時會引" -"發此例外。對應到 :c:data:`errno` :py:const:`~errno.ECONNABORTED`。" - -#: ../../library/exceptions.rst:769 -msgid "" -"A subclass of :exc:`ConnectionError`, raised when a connection attempt is " -"refused by the peer. Corresponds to :c:data:`errno` :py:const:`~errno." -"ECONNREFUSED`." -msgstr "" -":exc:`ConnectionError` 的子類別。當一個連線的嘗試被對等端點拒絕時會引發此例" -"外。對應到 :c:data:`errno` :py:const:`~errno.ECONNREFUSED`。" - -#: ../../library/exceptions.rst:775 -msgid "" -"A subclass of :exc:`ConnectionError`, raised when a connection is reset by " -"the peer. Corresponds to :c:data:`errno` :py:const:`~errno.ECONNRESET`." -msgstr "" -":exc:`ConnectionError` 的子類別。當一個連線被對等端點重置時會引發此例外。對應" -"到 :c:data:`errno` :py:const:`~errno.ECONNRESET`。" - -#: ../../library/exceptions.rst:781 -msgid "" -"Raised when trying to create a file or directory which already exists. " -"Corresponds to :c:data:`errno` :py:const:`~errno.EEXIST`." -msgstr "" -"當嘗試建立已存在的檔案或目錄時會引發此例外。對應到 :c:data:`errno` :py:const:" -"`~errno.EEXIST`。" - -#: ../../library/exceptions.rst:786 -msgid "" -"Raised when a file or directory is requested but doesn't exist. Corresponds " -"to :c:data:`errno` :py:const:`~errno.ENOENT`." -msgstr "" -"當請求不存在的檔案或目錄時會引發此例外。對應到 :c:data:`errno` :py:const:" -"`~errno.ENOENT`。" - -#: ../../library/exceptions.rst:791 -msgid "" -"Raised when a system call is interrupted by an incoming signal. Corresponds " -"to :c:data:`errno` :py:const:`~errno.EINTR`." -msgstr "" -"當系統呼叫被傳入的信號中斷時會引發此例外。對應到 :c:data:`errno` :py:const:" -"`~errno.EINTR`。" - -#: ../../library/exceptions.rst:794 -msgid "" -"Python now retries system calls when a syscall is interrupted by a signal, " -"except if the signal handler raises an exception (see :pep:`475` for the " -"rationale), instead of raising :exc:`InterruptedError`." -msgstr "" -"現在當 syscall 被信號中斷時 Python 會重試系統呼叫而不會引發 :exc:" -"`InterruptedError`，除非信號處理器引發例外（理由可參考 :pep:`475`）。" - -#: ../../library/exceptions.rst:801 -msgid "" -"Raised when a file operation (such as :func:`os.remove`) is requested on a " -"directory. Corresponds to :c:data:`errno` :py:const:`~errno.EISDIR`." -msgstr "" -"當在目錄上請求檔案操作（例如 :func:`os.remove`）時會引發此例外。對應到 :c:" -"data:`errno` :py:const:`~errno.EISDIR`。" - -#: ../../library/exceptions.rst:807 -msgid "" -"Raised when a directory operation (such as :func:`os.listdir`) is requested " -"on something which is not a directory. On most POSIX platforms, it may also " -"be raised if an operation attempts to open or traverse a non-directory file " -"as if it were a directory. Corresponds to :c:data:`errno` :py:const:`~errno." -"ENOTDIR`." -msgstr "" -"當在某個不是目錄的東西上請求目錄操作（例如 :func:`os.listdir`）時會引發此例" -"外。在大多數的 POSIX 平台上，如果嘗試操作開啟或遍歷一個當作目錄的非目錄檔案也" -"會引發此例外。對應到 :c:data:`errno` :py:const:`~errno.ENOTDIR`。" - -#: ../../library/exceptions.rst:815 -msgid "" -"Raised when trying to run an operation without the adequate access rights - " -"for example filesystem permissions. Corresponds to :c:data:`errno` :py:const:" -"`~errno.EACCES`, :py:const:`~errno.EPERM`, and :py:const:`~errno." -"ENOTCAPABLE`." -msgstr "" -"當嘗試執行一個沒有合乎存取權限的操作時會引發此例外 — 例如檔案系統權限。對應" -"到 :c:data:`errno` :py:const:`~errno.EACCES`、:py:const:`~errno.EPERM` 及 :" -"py:const:`~errno.ENOTCAPABLE`。" - -#: ../../library/exceptions.rst:820 -msgid "" -"WASI's :py:const:`~errno.ENOTCAPABLE` is now mapped to :exc:" -"`PermissionError`." -msgstr "" -"WASI 的 :py:const:`~errno.ENOTCAPABLE` 現在對應到 :exc:`PermissionError`。" - -#: ../../library/exceptions.rst:826 -msgid "" -"Raised when a given process doesn't exist. Corresponds to :c:data:`errno` :" -"py:const:`~errno.ESRCH`." -msgstr "" -"當給定的行程不存在時會引發此例外。對應到 :c:data:`errno` :py:const:`~errno." -"ESRCH`。" - -#: ../../library/exceptions.rst:831 -msgid "" -"Raised when a system function timed out at the system level. Corresponds to :" -"c:data:`errno` :py:const:`~errno.ETIMEDOUT`." -msgstr "" -"當系統函式在系統層級超時會引發此例外。對應到 :c:data:`errno` :py:const:" -"`~errno.ETIMEDOUT`。" - -#: ../../library/exceptions.rst:834 -msgid "All the above :exc:`OSError` subclasses were added." -msgstr "加入以上所有的 :exc:`OSError` 子類別。" - -#: ../../library/exceptions.rst:840 -msgid ":pep:`3151` - Reworking the OS and IO exception hierarchy" -msgstr ":pep:`3151` — 改寫作業系統與 IO 例外階層" - -#: ../../library/exceptions.rst:846 -msgid "Warnings" -msgstr "警告" - -#: ../../library/exceptions.rst:848 -msgid "" -"The following exceptions are used as warning categories; see the :ref:" -"`warning-categories` documentation for more details." -msgstr "" -"以下的例外是當作警告的種類使用；更多細節參考 :ref:`warning-categories` 文件。" - -#: ../../library/exceptions.rst:853 -msgid "Base class for warning categories." -msgstr "警告種類的基礎類別。" - -#: ../../library/exceptions.rst:858 -msgid "Base class for warnings generated by user code." -msgstr "使用者程式碼產生的警告的基礎類別。" - -#: ../../library/exceptions.rst:863 -msgid "" -"Base class for warnings about deprecated features when those warnings are " -"intended for other Python developers." -msgstr "關於已棄用功能的警告的基礎類別，且當那些警告是針對其他 Python 開發者。" - -#: ../../library/exceptions.rst:866 -msgid "" -"Ignored by the default warning filters, except in the ``__main__`` module (:" -"pep:`565`). Enabling the :ref:`Python Development Mode ` shows this " -"warning." -msgstr "" -"會被預設的警告過濾器忽略，在 ``__main__`` 模組裡除外 (:pep:`565`)。啟用 :ref:" -"`Python 開發模式 `\\ 會顯示此警告。" - -#: ../../library/exceptions.rst:870 ../../library/exceptions.rst:886 -msgid "The deprecation policy is described in :pep:`387`." -msgstr "棄用原則描述在 :pep:`387` 裡。" - -#: ../../library/exceptions.rst:875 -msgid "" -"Base class for warnings about features which are obsolete and expected to be " -"deprecated in the future, but are not deprecated at the moment." -msgstr "關於過時且預期未來要被棄用，但目前尚未被棄用的功能的警告的基礎類別。" - -#: ../../library/exceptions.rst:879 -msgid "" -"This class is rarely used as emitting a warning about a possible upcoming " -"deprecation is unusual, and :exc:`DeprecationWarning` is preferred for " -"already active deprecations." -msgstr "" -"因為發出關於可能即將被棄用的警告是不尋常的，此類別很少被使用，而對已經被棄用" -"的情況會優先使用 :exc:`DeprecationWarning`。" - -#: ../../library/exceptions.rst:883 ../../library/exceptions.rst:912 -#: ../../library/exceptions.rst:939 -msgid "" -"Ignored by the default warning filters. Enabling the :ref:`Python " -"Development Mode ` shows this warning." -msgstr "" -"會被預設的警告過濾器忽略。啟用 :ref:`Python 開發模式 `\\ 會顯示此警" -"告。" - -#: ../../library/exceptions.rst:891 -msgid "Base class for warnings about dubious syntax." -msgstr "關於可疑語法的警告的基礎類別。" - -#: ../../library/exceptions.rst:893 -msgid "" -"This warning is typically emitted when compiling Python source code, and " -"usually won't be reported when running already compiled code." -msgstr "" - -#: ../../library/exceptions.rst:899 -msgid "Base class for warnings about dubious runtime behavior." -msgstr "關於可疑執行環境行為的警告的基礎類別。" - -#: ../../library/exceptions.rst:904 -msgid "" -"Base class for warnings about deprecated features when those warnings are " -"intended for end users of applications that are written in Python." -msgstr "" -"關於已棄用功能的警告的基礎類別，且當那些警告是針對以 Python 寫的應用程式的終" -"端使用者。" - -#: ../../library/exceptions.rst:910 -msgid "Base class for warnings about probable mistakes in module imports." -msgstr "關於在模組引入的可能錯誤的警告的基礎類別。" - -#: ../../library/exceptions.rst:918 -msgid "Base class for warnings related to Unicode." -msgstr "Unicode 相關警告的基礎類別。" - -#: ../../library/exceptions.rst:923 -msgid "Base class for warnings related to encodings." -msgstr "編碼相關警告的基礎類別。" - -#: ../../library/exceptions.rst:925 -msgid "See :ref:`io-encoding-warning` for details." -msgstr "細節參考\\ :ref:`io-encoding-warning`。" - -#: ../../library/exceptions.rst:932 -msgid "" -"Base class for warnings related to :class:`bytes` and :class:`bytearray`." -msgstr ":class:`bytes` 及 :class:`bytearray` 相關警告的基礎類別。" - -#: ../../library/exceptions.rst:937 -msgid "Base class for warnings related to resource usage." -msgstr "資源用法相關警告的基礎類別。" - -#: ../../library/exceptions.rst:948 -msgid "Exception groups" -msgstr "例外群組" - -#: ../../library/exceptions.rst:950 -msgid "" -"The following are used when it is necessary to raise multiple unrelated " -"exceptions. They are part of the exception hierarchy so they can be handled " -"with :keyword:`except` like all other exceptions. In addition, they are " -"recognised by :keyword:`except*`, which matches their subgroups " -"based on the types of the contained exceptions." -msgstr "" -"當需要引發多個不相關例外時會使用下列的類別。它們是例外階層的一部分所以可以像" -"所有其他例外一樣使用 :keyword:`except` 來處理。此外，它們會以包含的例外型別為" -"基礎來比對其子群組而被 :keyword:`except*` 辨認出來。" - -#: ../../library/exceptions.rst:959 -msgid "" -"Both of these exception types wrap the exceptions in the sequence ``excs``. " -"The ``msg`` parameter must be a string. The difference between the two " -"classes is that :exc:`BaseExceptionGroup` extends :exc:`BaseException` and " -"it can wrap any exception, while :exc:`ExceptionGroup` extends :exc:" -"`Exception` and it can only wrap subclasses of :exc:`Exception`. This design " -"is so that ``except Exception`` catches an :exc:`ExceptionGroup` but not :" -"exc:`BaseExceptionGroup`." -msgstr "" -"這兩個例外型別都將例外包裝在序列 ``excs`` 中。``msg`` 參數必須是字串。這兩個" -"類別的差異是 :exc:`BaseExceptionGroup` 擴充了 :exc:`BaseException` 且可以包裝" -"任何例外，而 :exc:`ExceptionGroup` 擴充了 :exc:`Exception` 且只能包裝 :exc:" -"`Exception` 的子類別。這個設計使得 ``except Exception`` 可以捕捉 :exc:" -"`ExceptionGroup` 但不能捕捉 :exc:`BaseExceptionGroup`。" - -#: ../../library/exceptions.rst:967 -msgid "" -"The :exc:`BaseExceptionGroup` constructor returns an :exc:`ExceptionGroup` " -"rather than a :exc:`BaseExceptionGroup` if all contained exceptions are :exc:" -"`Exception` instances, so it can be used to make the selection automatic. " -"The :exc:`ExceptionGroup` constructor, on the other hand, raises a :exc:" -"`TypeError` if any contained exception is not an :exc:`Exception` subclass." -msgstr "" -"如果所有包含的例外都是 :exc:`Exception` 實例，:exc:`BaseExceptionGroup` 建構" -"函式會回傳 :exc:`ExceptionGroup` 而不是 :exc:`BaseExceptionGroup`，因此可以被" -"使用來讓這樣的選擇自動化。另一方面來說，如果任何包含的例外不是 :exc:" -"`Exception` 的子類別，:exc:`ExceptionGroup` 建構函式會引發 :exc:`TypeError`。" - -#: ../../library/exceptions.rst:976 -msgid "The ``msg`` argument to the constructor. This is a read-only attribute." -msgstr "建構函式的 ``msg`` 引數。這是一個唯讀的屬性。" - -#: ../../library/exceptions.rst:980 -msgid "" -"A tuple of the exceptions in the ``excs`` sequence given to the constructor. " -"This is a read-only attribute." -msgstr "指定給建構函式 ``excs`` 序列中的例外組成的元組。這是一個唯讀的屬性。" - -#: ../../library/exceptions.rst:985 -msgid "" -"Returns an exception group that contains only the exceptions from the " -"current group that match *condition*, or ``None`` if the result is empty." -msgstr "" -"回傳只包含從現有群組比對到 *condition* 的例外的例外群組，或者當結果為空時回" -"傳 ``None``。" - -#: ../../library/exceptions.rst:988 -msgid "" -"The condition can be an exception type or tuple of exception types, in which " -"case each exception is checked for a match using the same check that is used " -"in an ``except`` clause. The condition can also be a callable (other than a " -"type object) that accepts an exception as its single argument and returns " -"true for the exceptions that should be in the subgroup." -msgstr "" -"條件式可以是一個例外型別或是例外型別的元組，在此情況下，每個例外都會使用與 " -"``except`` 子句中使用的相同檢查方法來檢查是否有匹配。條件式也可以是一個可呼叫" -"物件（除了型別物件之外），其接受一個例外作為單一引數，而如果該例外應該在子群" -"組中就回傳 true。" - -#: ../../library/exceptions.rst:994 -msgid "" -"The nesting structure of the current exception is preserved in the result, " -"as are the values of its :attr:`message`, :attr:`~BaseException." -"__traceback__`, :attr:`~BaseException.__cause__`, :attr:`~BaseException." -"__context__` and :attr:`~BaseException.__notes__` fields. Empty nested " -"groups are omitted from the result." -msgstr "" -"現有例外的巢狀結構會保留在結果裡，其 :attr:`message`、:attr:`~BaseException." -"__traceback__`、:attr:`~BaseException.__cause__`、:attr:`~BaseException." -"__context__` 及 :attr:`~BaseException.__notes__` 欄位的值也一樣。空的巢狀群組" -"會從結果裡排除。" - -#: ../../library/exceptions.rst:1001 -msgid "" -"The condition is checked for all exceptions in the nested exception group, " -"including the top-level and any nested exception groups. If the condition is " -"true for such an exception group, it is included in the result in full." -msgstr "" -"條件會對巢狀例外群組裡的所有例外做檢查，包括頂層及任何巢狀的例外群組。如果條" -"件對這樣的例外群組為 true，它會被完整包含在結果裡。" - -#: ../../library/exceptions.rst:1005 -msgid "``condition`` can be any callable which is not a type object." -msgstr "``condition`` 可以是任何不是型別物件的可呼叫物件。" - -#: ../../library/exceptions.rst:1010 -msgid "" -"Like :meth:`subgroup`, but returns the pair ``(match, rest)`` where " -"``match`` is ``subgroup(condition)`` and ``rest`` is the remaining non-" -"matching part." -msgstr "" -"像 :meth:`subgroup` 一樣，但回傳一對 ``(match, rest)``，其中 ``match`` 是 " -"``subgroup(condition)`` 而 ``rest`` 是剩下沒有比對到的部分。" - -#: ../../library/exceptions.rst:1016 -msgid "" -"Returns an exception group with the same :attr:`message`, but which wraps " -"the exceptions in ``excs``." -msgstr "回傳有相同 :attr:`message` 但將例外包裝在 ``excs`` 的例外群組。" - -#: ../../library/exceptions.rst:1019 -msgid "" -"This method is used by :meth:`subgroup` and :meth:`split`, which are used in " -"various contexts to break up an exception group. A subclass needs to " -"override it in order to make :meth:`subgroup` and :meth:`split` return " -"instances of the subclass rather than :exc:`ExceptionGroup`." -msgstr "" -"此方法被 :meth:`subgroup` 及 :meth:`split` 使用，被用來在各種情境下拆分例外群" -"組。子類別需要覆寫它來讓 :meth:`subgroup` 及 :meth:`split` 回傳子類別而不是 :" -"exc:`ExceptionGroup` 的實例。" - -#: ../../library/exceptions.rst:1025 -msgid "" -":meth:`subgroup` and :meth:`split` copy the :attr:`~BaseException." -"__traceback__`, :attr:`~BaseException.__cause__`, :attr:`~BaseException." -"__context__` and :attr:`~BaseException.__notes__` fields from the original " -"exception group to the one returned by :meth:`derive`, so these fields do " -"not need to be updated by :meth:`derive`." -msgstr "" -":meth:`subgroup` 及 :meth:`split` 會從原始的例外群組複製 :attr:" -"`~BaseException.__traceback__`、:attr:`~BaseException.__cause__`、:attr:" -"`~BaseException.__context__` 和 :attr:`~BaseException.__notes__` 欄位到 :" -"meth:`derive` 所回傳的例外群組上，因此這些欄位不需要被 :meth:`derive` 更新。" - -#: ../../library/exceptions.rst:1032 -msgid "" -">>> class MyGroup(ExceptionGroup):\n" -"... def derive(self, excs):\n" -"... return MyGroup(self.message, excs)\n" -"...\n" -">>> e = MyGroup(\"eg\", [ValueError(1), TypeError(2)])\n" -">>> e.add_note(\"a note\")\n" -">>> e.__context__ = Exception(\"context\")\n" -">>> e.__cause__ = Exception(\"cause\")\n" -">>> try:\n" -"... raise e\n" -"... except Exception as e:\n" -"... exc = e\n" -"...\n" -">>> match, rest = exc.split(ValueError)\n" -">>> exc, exc.__context__, exc.__cause__, exc.__notes__\n" -"(MyGroup('eg', [ValueError(1), TypeError(2)]), Exception('context'), " -"Exception('cause'), ['a note'])\n" -">>> match, match.__context__, match.__cause__, match.__notes__\n" -"(MyGroup('eg', [ValueError(1)]), Exception('context'), Exception('cause'), " -"['a note'])\n" -">>> rest, rest.__context__, rest.__cause__, rest.__notes__\n" -"(MyGroup('eg', [TypeError(2)]), Exception('context'), Exception('cause'), " -"['a note'])\n" -">>> exc.__traceback__ is match.__traceback__ is rest.__traceback__\n" -"True" -msgstr "" -">>> class MyGroup(ExceptionGroup):\n" -"... def derive(self, excs):\n" -"... return MyGroup(self.message, excs)\n" -"...\n" -">>> e = MyGroup(\"eg\", [ValueError(1), TypeError(2)])\n" -">>> e.add_note(\"a note\")\n" -">>> e.__context__ = Exception(\"context\")\n" -">>> e.__cause__ = Exception(\"cause\")\n" -">>> try:\n" -"... raise e\n" -"... except Exception as e:\n" -"... exc = e\n" -"...\n" -">>> match, rest = exc.split(ValueError)\n" -">>> exc, exc.__context__, exc.__cause__, exc.__notes__\n" -"(MyGroup('eg', [ValueError(1), TypeError(2)]), Exception('context'), " -"Exception('cause'), ['a note'])\n" -">>> match, match.__context__, match.__cause__, match.__notes__\n" -"(MyGroup('eg', [ValueError(1)]), Exception('context'), Exception('cause'), " -"['a note'])\n" -">>> rest, rest.__context__, rest.__cause__, rest.__notes__\n" -"(MyGroup('eg', [TypeError(2)]), Exception('context'), Exception('cause'), " -"['a note'])\n" -">>> exc.__traceback__ is match.__traceback__ is rest.__traceback__\n" -"True" - -#: ../../library/exceptions.rst:1058 -msgid "" -"Note that :exc:`BaseExceptionGroup` defines :meth:`~object.__new__`, so " -"subclasses that need a different constructor signature need to override that " -"rather than :meth:`~object.__init__`. For example, the following defines an " -"exception group subclass which accepts an exit_code and constructs the " -"group's message from it. ::" -msgstr "" -"需注意 :exc:`BaseExceptionGroup` 定義了 :meth:`~object.__new__`，因此需要不同" -"建構函式簽名的子類別需要覆寫它而不是 :meth:`~object.__init__`。例如下面定義了" -"一個例外群組子類別接受 exit_code 並從中建構群組的訊息。： ::" - -#: ../../library/exceptions.rst:1064 -msgid "" -"class Errors(ExceptionGroup):\n" -" def __new__(cls, errors, exit_code):\n" -" self = super().__new__(Errors, f\"exit code: {exit_code}\", errors)\n" -" self.exit_code = exit_code\n" -" return self\n" -"\n" -" def derive(self, excs):\n" -" return Errors(excs, self.exit_code)" -msgstr "" -"class Errors(ExceptionGroup):\n" -" def __new__(cls, errors, exit_code):\n" -" self = super().__new__(Errors, f\"exit code: {exit_code}\", errors)\n" -" self.exit_code = exit_code\n" -" return self\n" -"\n" -" def derive(self, excs):\n" -" return Errors(excs, self.exit_code)" - -#: ../../library/exceptions.rst:1073 -msgid "" -"Like :exc:`ExceptionGroup`, any subclass of :exc:`BaseExceptionGroup` which " -"is also a subclass of :exc:`Exception` can only wrap instances of :exc:" -"`Exception`." -msgstr "" -"像 :exc:`ExceptionGroup` 一樣，任何 :exc:`BaseExceptionGroup` 的子類別且也" -"是 :exc:`Exception` 的子類別只能包裝 :exc:`Exception` 的實例。" - -#: ../../library/exceptions.rst:1081 -msgid "Exception hierarchy" -msgstr "例外階層" - -#: ../../library/exceptions.rst:1083 -msgid "The class hierarchy for built-in exceptions is:" -msgstr "內建例外的類別階層如下：" - -#: ../../library/exceptions.rst:1085 -msgid "" -"BaseException\n" -" ├── BaseExceptionGroup\n" -" ├── GeneratorExit\n" -" ├── KeyboardInterrupt\n" -" ├── SystemExit\n" -" └── Exception\n" -" ├── ArithmeticError\n" -" │ ├── FloatingPointError\n" -" │ ├── OverflowError\n" -" │ └── ZeroDivisionError\n" -" ├── AssertionError\n" -" ├── AttributeError\n" -" ├── BufferError\n" -" ├── EOFError\n" -" ├── ExceptionGroup [BaseExceptionGroup]\n" -" ├── ImportError\n" -" │ └── ModuleNotFoundError\n" -" ├── LookupError\n" -" │ ├── IndexError\n" -" │ └── KeyError\n" -" ├── MemoryError\n" -" ├── NameError\n" -" │ └── UnboundLocalError\n" -" ├── OSError\n" -" │ ├── BlockingIOError\n" -" │ ├── ChildProcessError\n" -" │ ├── ConnectionError\n" -" │ │ ├── BrokenPipeError\n" -" │ │ ├── ConnectionAbortedError\n" -" │ │ ├── ConnectionRefusedError\n" -" │ │ └── ConnectionResetError\n" -" │ ├── FileExistsError\n" -" │ ├── FileNotFoundError\n" -" │ ├── InterruptedError\n" -" │ ├── IsADirectoryError\n" -" │ ├── NotADirectoryError\n" -" │ ├── PermissionError\n" -" │ ├── ProcessLookupError\n" -" │ └── TimeoutError\n" -" ├── ReferenceError\n" -" ├── RuntimeError\n" -" │ ├── NotImplementedError\n" -" │ ├── PythonFinalizationError\n" -" │ └── RecursionError\n" -" ├── StopAsyncIteration\n" -" ├── StopIteration\n" -" ├── SyntaxError\n" -" │ └── IndentationError\n" -" │ └── TabError\n" -" ├── SystemError\n" -" ├── TypeError\n" -" ├── ValueError\n" -" │ └── UnicodeError\n" -" │ ├── UnicodeDecodeError\n" -" │ ├── UnicodeEncodeError\n" -" │ └── UnicodeTranslateError\n" -" └── Warning\n" -" ├── BytesWarning\n" -" ├── DeprecationWarning\n" -" ├── EncodingWarning\n" -" ├── FutureWarning\n" -" ├── ImportWarning\n" -" ├── PendingDeprecationWarning\n" -" ├── ResourceWarning\n" -" ├── RuntimeWarning\n" -" ├── SyntaxWarning\n" -" ├── UnicodeWarning\n" -" └── UserWarning\n" -msgstr "" -"BaseException\n" -" ├── BaseExceptionGroup\n" -" ├── GeneratorExit\n" -" ├── KeyboardInterrupt\n" -" ├── SystemExit\n" -" └── Exception\n" -" ├── ArithmeticError\n" -" │ ├── FloatingPointError\n" -" │ ├── OverflowError\n" -" │ └── ZeroDivisionError\n" -" ├── AssertionError\n" -" ├── AttributeError\n" -" ├── BufferError\n" -" ├── EOFError\n" -" ├── ExceptionGroup [BaseExceptionGroup]\n" -" ├── ImportError\n" -" │ └── ModuleNotFoundError\n" -" ├── LookupError\n" -" │ ├── IndexError\n" -" │ └── KeyError\n" -" ├── MemoryError\n" -" ├── NameError\n" -" │ └── UnboundLocalError\n" -" ├── OSError\n" -" │ ├── BlockingIOError\n" -" │ ├── ChildProcessError\n" -" │ ├── ConnectionError\n" -" │ │ ├── BrokenPipeError\n" -" │ │ ├── ConnectionAbortedError\n" -" │ │ ├── ConnectionRefusedError\n" -" │ │ └── ConnectionResetError\n" -" │ ├── FileExistsError\n" -" │ ├── FileNotFoundError\n" -" │ ├── InterruptedError\n" -" │ ├── IsADirectoryError\n" -" │ ├── NotADirectoryError\n" -" │ ├── PermissionError\n" -" │ ├── ProcessLookupError\n" -" │ └── TimeoutError\n" -" ├── ReferenceError\n" -" ├── RuntimeError\n" -" │ ├── NotImplementedError\n" -" │ ├── PythonFinalizationError\n" -" │ └── RecursionError\n" -" ├── StopAsyncIteration\n" -" ├── StopIteration\n" -" ├── SyntaxError\n" -" │ └── IndentationError\n" -" │ └── TabError\n" -" ├── SystemError\n" -" ├── TypeError\n" -" ├── ValueError\n" -" │ └── UnicodeError\n" -" │ ├── UnicodeDecodeError\n" -" │ ├── UnicodeEncodeError\n" -" │ └── UnicodeTranslateError\n" -" └── Warning\n" -" ├── BytesWarning\n" -" ├── DeprecationWarning\n" -" ├── EncodingWarning\n" -" ├── FutureWarning\n" -" ├── ImportWarning\n" -" ├── PendingDeprecationWarning\n" -" ├── ResourceWarning\n" -" ├── RuntimeWarning\n" -" ├── SyntaxWarning\n" -" ├── UnicodeWarning\n" -" └── UserWarning\n" - -#: ../../library/exceptions.rst:6 ../../library/exceptions.rst:17 -#: ../../library/exceptions.rst:196 -msgid "statement" -msgstr "statement（陳述式）" - -#: ../../library/exceptions.rst:6 -msgid "try" -msgstr "try" - -#: ../../library/exceptions.rst:6 -msgid "except" -msgstr "except" - -#: ../../library/exceptions.rst:17 -msgid "raise" -msgstr "raise" - -#: ../../library/exceptions.rst:41 -msgid "exception" -msgstr "exception（例外）" - -#: ../../library/exceptions.rst:41 -msgid "chaining" -msgstr "chaining" - -#: ../../library/exceptions.rst:41 -msgid "__cause__ (exception attribute)" -msgstr "__cause__（例外屬性）" - -#: ../../library/exceptions.rst:41 -msgid "__context__ (exception attribute)" -msgstr "__context__（例外屬性）" - -#: ../../library/exceptions.rst:41 -msgid "__suppress_context__ (exception attribute)" -msgstr "__suppress_context__（例外屬性）" - -#: ../../library/exceptions.rst:196 -msgid "assert" -msgstr "assert" - -#: ../../library/exceptions.rst:355 -msgid "module" -msgstr "module（模組）" - -#: ../../library/exceptions.rst:355 -msgid "errno" -msgstr "errno" - -#~ msgid "" -#~ "The :attr:`name` and :attr:`obj` attributes can be set using keyword-only " -#~ "arguments to the constructor. When set they represent the name of the " -#~ "attribute that was attempted to be accessed and the object that was " -#~ "accessed for said attribute, respectively." -#~ msgstr "" -#~ ":attr:`name` 和 :attr:`obj` 屬性可以使用建構函式的僅限關鍵字 (keyword-" -#~ "only) 引數來設定。當被設定的時候，它們分別代表被嘗試存取的屬性名稱以及被以" -#~ "該屬性存取的物件。" - -#~ msgid "" -#~ "The :attr:`name` attribute can be set using a keyword-only argument to " -#~ "the constructor. When set it represent the name of the variable that was " -#~ "attempted to be accessed." -#~ msgstr "" -#~ ":attr:`name` 屬性可以使用僅限關鍵字引數來設定到建構函式。當被設定的時候它" -#~ "代表被嘗試存取的變數名稱。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Leon H., 2017 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-12-17 00:14+0000\n" +"PO-Revision-Date: 2024-12-20 16:57+0800\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/exceptions.rst:4 +msgid "Built-in Exceptions" +msgstr "內建的例外" + +#: ../../library/exceptions.rst:10 +msgid "" +"In Python, all exceptions must be instances of a class that derives from :" +"class:`BaseException`. In a :keyword:`try` statement with an :keyword:" +"`except` clause that mentions a particular class, that clause also handles " +"any exception classes derived from that class (but not exception classes " +"from which *it* is derived). Two exception classes that are not related via " +"subclassing are never equivalent, even if they have the same name." +msgstr "" +"在 Python 中，所有例外必須是從 :class:`BaseException` 衍生的類別的實例。在陳" +"述式 :keyword:`try` 搭配 :keyword:`except` 子句裡提到一個特定的類別時，那個子" +"句也會處理任何從該類別衍生的例外類別（但不會處理該類別\\ *衍生自*\\ 的例外類" +"別）。兩個不是由子類別關係關聯起來的例外類別永遠不相等，就算它們有相同的名稱" +"也是如此。" + +#: ../../library/exceptions.rst:19 +msgid "" +"The built-in exceptions listed in this chapter can be generated by the " +"interpreter or built-in functions. Except where mentioned, they have an " +"\"associated value\" indicating the detailed cause of the error. This may " +"be a string or a tuple of several items of information (e.g., an error code " +"and a string explaining the code). The associated value is usually passed " +"as arguments to the exception class's constructor." +msgstr "" +"此章節裡列出的內建例外可以從直譯器或內建函式產生。除了特別提到的地方之外，它" +"們會有一個\\ *關聯值*\\ 表示錯誤發生的詳細原因。這可能是一個字串，或者是一些" +"資訊項目組成的元組（例如一個錯誤代碼及一個解釋該代碼的字串）。這個關聯值通常" +"當作引數傳遞給例外類別的建構函式。" + +#: ../../library/exceptions.rst:26 +msgid "" +"User code can raise built-in exceptions. This can be used to test an " +"exception handler or to report an error condition \"just like\" the " +"situation in which the interpreter raises the same exception; but beware " +"that there is nothing to prevent user code from raising an inappropriate " +"error." +msgstr "" +"使用者的程式碼可以引發內建例外。這可以用來測試例外處理器或者用來回報一個錯誤" +"條件，*就像*\\ 直譯器會引發相同例外的情況；但需要注意的是沒有任何方式可以避免" +"使用者的程式碼引發不適當的錯誤。" + +#: ../../library/exceptions.rst:31 +msgid "" +"The built-in exception classes can be subclassed to define new exceptions; " +"programmers are encouraged to derive new exceptions from the :exc:" +"`Exception` class or one of its subclasses, and not from :exc:" +"`BaseException`. More information on defining exceptions is available in " +"the Python Tutorial under :ref:`tut-userexceptions`." +msgstr "" +"可以從內建的例外類別定義新的例外子類別；程式設計師被鼓勵從 :exc:`Exception` " +"類別或其子類別衍生新的例外，而不是從 :exc:`BaseException` 來衍生。更多關於定" +"義例外的資訊可以在 Python 教學中的\\ :ref:`tut-userexceptions`\\ 裡取得。" + +#: ../../library/exceptions.rst:39 +msgid "Exception context" +msgstr "例外的情境" + +#: ../../library/exceptions.rst:46 +msgid "" +"Three attributes on exception objects provide information about the context " +"in which the exception was raised:" +msgstr "三個例外物件上的屬性提供關於引發此例外的情境的資訊：" + +#: ../../library/exceptions.rst:53 +msgid "" +"When raising a new exception while another exception is already being " +"handled, the new exception's :attr:`!__context__` attribute is automatically " +"set to the handled exception. An exception may be handled when an :keyword:" +"`except` or :keyword:`finally` clause, or a :keyword:`with` statement, is " +"used." +msgstr "" +"當引發一個新的例外而同時有另一個例外已經正在被處理時，這個新例外的 :attr:`!" +"__context__` 屬性會自動被設成那個已處理的例外。當使用 :keyword:`except` 或 :" +"keyword:`finally` 子句或 :keyword:`with` 陳述式的時候例外會被處理。" + +#: ../../library/exceptions.rst:59 +msgid "" +"This implicit exception context can be supplemented with an explicit cause " +"by using :keyword:`!from` with :keyword:`raise`::" +msgstr "" +"這個隱含的例外情境可以透過使用 :keyword:`!from` 搭配 :keyword:`raise` 來補充" +"明確的原因： ::" + +#: ../../library/exceptions.rst:63 +msgid "raise new_exc from original_exc" +msgstr "raise new_exc from original_exc" + +#: ../../library/exceptions.rst:65 +msgid "" +"The expression following :keyword:`from` must be an exception or " +"``None``. It will be set as :attr:`!__cause__` on the raised exception. " +"Setting :attr:`!__cause__` also implicitly sets the :attr:`!" +"__suppress_context__` attribute to ``True``, so that using ``raise new_exc " +"from None`` effectively replaces the old exception with the new one for " +"display purposes (e.g. converting :exc:`KeyError` to :exc:`AttributeError`), " +"while leaving the old exception available in :attr:`!__context__` for " +"introspection when debugging." +msgstr "" +"在 :keyword:`from` 後面的運算式必須是一個例外或 ``None``。它將會被設定" +"成所引發例外的 :attr:`!__cause__`。設定 :attr:`!__cause__` 也隱含地設定 :" +"attr:`!__suppress_context__` 屬性為 ``True``，因此使用 ``raise new_exc from " +"None`` 實際上會以新的例外取代舊的例外以利於顯示（例如轉換 :exc:`KeyError` " +"為 :exc:`AttributeError`），同時保持舊的例外可以透過 :attr:`!__context__` 取" +"得以方便 debug 的時候檢查。" + +#: ../../library/exceptions.rst:74 +msgid "" +"The default traceback display code shows these chained exceptions in " +"addition to the traceback for the exception itself. An explicitly chained " +"exception in :attr:`!__cause__` is always shown when present. An implicitly " +"chained exception in :attr:`!__context__` is shown only if :attr:`!" +"__cause__` is :const:`None` and :attr:`!__suppress_context__` is false." +msgstr "" +"預設的回溯 (traceback) 顯示程式碼會顯示這些連鎖的例外 (chained exception) 加" +"上例外本身的回溯。當存在的時候，在 :attr:`!__cause__` 中明確地連鎖的例外總是" +"會被顯示。而在 :attr:`!__context__` 中隱含地連鎖的例外只有當 :attr:`!" +"__cause__` 是 :const:`None` 且 :attr:`!__suppress_context__` 是 false 時才會" +"顯示。" + +#: ../../library/exceptions.rst:80 +msgid "" +"In either case, the exception itself is always shown after any chained " +"exceptions so that the final line of the traceback always shows the last " +"exception that was raised." +msgstr "" +"在任一種情況下，例外本身總是會顯示在任何連鎖例外的後面，因此回溯的最後一列總" +"是顯示最後一個被引發的例外。" + +#: ../../library/exceptions.rst:86 +msgid "Inheriting from built-in exceptions" +msgstr "繼承自內建的例外" + +#: ../../library/exceptions.rst:88 +msgid "" +"User code can create subclasses that inherit from an exception type. It's " +"recommended to only subclass one exception type at a time to avoid any " +"possible conflicts between how the bases handle the ``args`` attribute, as " +"well as due to possible memory layout incompatibilities." +msgstr "" +"使用者的程式碼可以建立繼承自例外型別的子類別。建議一次只繼承一種例外型別以避" +"免在基底類別之間如何處理 ``args`` 屬性的任何可能衝突，以及可能的記憶體佈局 " +"(memory layout) 不相容。" + +#: ../../library/exceptions.rst:95 +msgid "" +"Most built-in exceptions are implemented in C for efficiency, see: :source:" +"`Objects/exceptions.c`. Some have custom memory layouts which makes it " +"impossible to create a subclass that inherits from multiple exception types. " +"The memory layout of a type is an implementation detail and might change " +"between Python versions, leading to new conflicts in the future. Therefore, " +"it's recommended to avoid subclassing multiple exception types altogether." +msgstr "" +"為了效率，大部分的內建例外使用 C 來實作，參考 :source:`Objects/exceptions." +"c`。一些例外有客製化的記憶體佈局，使其不可能建立一個繼承多種例外型別的子類" +"別。型別的記憶體佈局是實作細節且可能會在不同 Python 版本間改變，造成未來新的" +"衝突。因此，總之建議避免繼承多種例外型別。" + +#: ../../library/exceptions.rst:105 +msgid "Base classes" +msgstr "基底類別 (base classes)" + +#: ../../library/exceptions.rst:107 +msgid "" +"The following exceptions are used mostly as base classes for other " +"exceptions." +msgstr "以下的例外大部分被用在當作其他例外的基底類別。" + +#: ../../library/exceptions.rst:111 +msgid "" +"The base class for all built-in exceptions. It is not meant to be directly " +"inherited by user-defined classes (for that, use :exc:`Exception`). If :" +"func:`str` is called on an instance of this class, the representation of the " +"argument(s) to the instance are returned, or the empty string when there " +"were no arguments." +msgstr "" +"所有內建例外的基底類別。這不是為了讓使用者定義的類別直接繼承（可以使用 :exc:" +"`Exception`）。如果在這個類別的實例上呼叫 :func:`str`，會回傳實例的引數的表" +"示，或者沒有引數的時候會回傳空字串。" + +#: ../../library/exceptions.rst:119 +msgid "" +"The tuple of arguments given to the exception constructor. Some built-in " +"exceptions (like :exc:`OSError`) expect a certain number of arguments and " +"assign a special meaning to the elements of this tuple, while others are " +"usually called only with a single string giving an error message." +msgstr "" +"提供給該例外建構函式的引數元組。一些內建的例外（像是 :exc:`OSError`）預期接受" +"特定數量的引數並賦予該元組的每一個元素一個特別的意義，其他例外則通常用一個提" +"供錯誤訊息的單一字串來呼叫。" + +#: ../../library/exceptions.rst:126 +msgid "" +"This method sets *tb* as the new traceback for the exception and returns the " +"exception object. It was more commonly used before the exception chaining " +"features of :pep:`3134` became available. The following example shows how " +"we can convert an instance of ``SomeException`` into an instance of " +"``OtherException`` while preserving the traceback. Once raised, the current " +"frame is pushed onto the traceback of the ``OtherException``, as would have " +"happened to the traceback of the original ``SomeException`` had we allowed " +"it to propagate to the caller. ::" +msgstr "" +"此方法設定 *tb* 為該例外的新的回溯並回傳該例外物件。在 :pep:`3134` 的例外連鎖" +"功能變得可用之前，此方法曾被更普遍使用。下面的範例顯示我們如何將 " +"``SomeException`` 的實例轉換為 ``OtherException`` 的實例同時保留回溯。一旦被" +"引發，目前的 frame 會被加進 ``OtherException`` 的回溯，就像原來 " +"``SomeException`` 的回溯會發生的一樣，我們允許它被傳遞給呼叫者： ::" + +#: ../../library/exceptions.rst:135 +msgid "" +"try:\n" +" ...\n" +"except SomeException:\n" +" tb = sys.exception().__traceback__\n" +" raise OtherException(...).with_traceback(tb)" +msgstr "" +"try:\n" +" ...\n" +"except SomeException:\n" +" tb = sys.exception().__traceback__\n" +" raise OtherException(...).with_traceback(tb)" + +#: ../../library/exceptions.rst:143 +msgid "" +"A writable field that holds the :ref:`traceback object ` " +"associated with this exception. See also: :ref:`raise`." +msgstr "" +"可寫入的欄位，儲存關聯到該例外的\\ :ref:`回溯物件 `。也可" +"以參考 :ref:`raise`。" + +#: ../../library/exceptions.rst:149 +msgid "" +"Add the string ``note`` to the exception's notes which appear in the " +"standard traceback after the exception string. A :exc:`TypeError` is raised " +"if ``note`` is not a string." +msgstr "" +"新增字串 ``note`` 到例外的備註，在標準的回溯裡，備註出現在例外字串的後面。如" +"果 ``note`` 不是字串則引發 :exc:`TypeError`。" + +#: ../../library/exceptions.rst:157 +msgid "" +"A list of the notes of this exception, which were added with :meth:" +"`add_note`. This attribute is created when :meth:`add_note` is called." +msgstr "" +"該例外的備註串列，使用 :meth:`add_note` 來新增。此屬性在 :meth:`add_note` 被" +"呼叫的時候建立。" + +#: ../../library/exceptions.rst:165 +msgid "" +"All built-in, non-system-exiting exceptions are derived from this class. " +"All user-defined exceptions should also be derived from this class." +msgstr "" +"所有內建、非系統退出 (non-system-exiting) 的例外都衍生自此類別。所有使用者定" +"義的例外應該也要衍生自此類別。" + +#: ../../library/exceptions.rst:171 +msgid "" +"The base class for those built-in exceptions that are raised for various " +"arithmetic errors: :exc:`OverflowError`, :exc:`ZeroDivisionError`, :exc:" +"`FloatingPointError`." +msgstr "" +"各種運算錯誤所引發的那些內建例外：:exc:`OverflowError`、:exc:" +"`ZeroDivisionError`、:exc:`FloatingPointError` 的基底類別。" + +#: ../../library/exceptions.rst:178 +msgid "" +"Raised when a :ref:`buffer ` related operation cannot be " +"performed." +msgstr "" +"當\\ :ref:`緩衝 (buffer) ` 相關的操作無法被執行時會引發此例" +"外。" + +#: ../../library/exceptions.rst:184 +msgid "" +"The base class for the exceptions that are raised when a key or index used " +"on a mapping or sequence is invalid: :exc:`IndexError`, :exc:`KeyError`. " +"This can be raised directly by :func:`codecs.lookup`." +msgstr "" +"當使用在對映或序列上的鍵或索引是無效的時候所引發的例外：:exc:`IndexError`、:" +"exc:`KeyError` 的基底類別。這可以被 :func:`codecs.lookup` 直接引發。" + +#: ../../library/exceptions.rst:190 +msgid "Concrete exceptions" +msgstr "實體例外" + +#: ../../library/exceptions.rst:192 +msgid "The following exceptions are the exceptions that are usually raised." +msgstr "以下的例外是通常會被引發的例外。" + +#: ../../library/exceptions.rst:198 +msgid "Raised when an :keyword:`assert` statement fails." +msgstr "當 :keyword:`assert` 陳述式失敗的時候被引發。" + +#: ../../library/exceptions.rst:203 +msgid "" +"Raised when an attribute reference (see :ref:`attribute-references`) or " +"assignment fails. (When an object does not support attribute references or " +"attribute assignments at all, :exc:`TypeError` is raised.)" +msgstr "" +"當屬性參照（參考 :ref:`attribute-references`）或賦值失敗的時候被引發。（當物" +"件根本不支援屬性參照或屬性賦值的時候，:exc:`TypeError` 會被引發。）" + +#: ../../library/exceptions.rst:207 +msgid "" +"The optional *name* and *obj* keyword-only arguments set the corresponding " +"attributes:" +msgstr "可選的僅限關鍵字引數 *name* 和 *obj* 會設定對應的屬性：" + +#: ../../library/exceptions.rst:212 +msgid "The name of the attribute that was attempted to be accessed." +msgstr "嘗試被存取的屬性名稱。" + +#: ../../library/exceptions.rst:216 +msgid "The object that was accessed for the named attribute." +msgstr "存取指定屬性的物件。" + +#: ../../library/exceptions.rst:218 +msgid "Added the :attr:`name` and :attr:`obj` attributes." +msgstr "新增 :attr:`name` 與 :attr:`obj` 屬性。" + +#: ../../library/exceptions.rst:223 +msgid "" +"Raised when the :func:`input` function hits an end-of-file condition (EOF) " +"without reading any data. (Note: the :meth:`!io.IOBase.read` and :meth:`io." +"IOBase.readline` methods return an empty string when they hit EOF.)" +msgstr "" +"當 :func:`input` 函式在沒有讀到任何資料而到達檔案結尾 (end-of-file, EOF) 條件" +"的時候被引發。（注意：:meth:`!io.IOBase.read` 和 :meth:`io.IOBase.readline` " +"方法當達到 EOF 時會回傳空字串。）" + +#: ../../library/exceptions.rst:230 +msgid "Not currently used." +msgstr "目前沒有被使用。" + +#: ../../library/exceptions.rst:235 +msgid "" +"Raised when a :term:`generator` or :term:`coroutine` is closed; see :meth:" +"`generator.close` and :meth:`coroutine.close`. It directly inherits from :" +"exc:`BaseException` instead of :exc:`Exception` since it is technically not " +"an error." +msgstr "" +"當 :term:`generator` 或 :term:`coroutine` 被關閉的時候被引發；參考 :meth:" +"`generator.close` 和 :meth:`coroutine.close`。此例外直接繼承自 :exc:" +"`BaseException` 而不是 :exc:`Exception`，因為技術上來說這不是一個錯誤。" + +#: ../../library/exceptions.rst:243 +msgid "" +"Raised when the :keyword:`import` statement has troubles trying to load a " +"module. Also raised when the \"from list\" in ``from ... import`` has a " +"name that cannot be found." +msgstr "" +"當 :keyword:`import` 陳述式嘗試載入模組遇到問題的時候會被引發。當 ``from ... " +"import`` 裡的 \"from list\" 包含找不到的名稱時也會被引發。" + +#: ../../library/exceptions.rst:247 +msgid "" +"The optional *name* and *path* keyword-only arguments set the corresponding " +"attributes:" +msgstr "可選的僅限關鍵字引數 *name* 和 *path* 設定對應的屬性：" + +#: ../../library/exceptions.rst:252 +msgid "The name of the module that was attempted to be imported." +msgstr "嘗試引入 (import) 的模組名稱。" + +#: ../../library/exceptions.rst:256 +msgid "The path to any file which triggered the exception." +msgstr "觸發此例外的任何檔案的路徑。" + +#: ../../library/exceptions.rst:258 +msgid "Added the :attr:`name` and :attr:`path` attributes." +msgstr "新增 :attr:`name` 與 :attr:`path` 屬性。" + +#: ../../library/exceptions.rst:263 +msgid "" +"A subclass of :exc:`ImportError` which is raised by :keyword:`import` when a " +"module could not be located. It is also raised when ``None`` is found in :" +"data:`sys.modules`." +msgstr "" +":exc:`ImportError` 的子類別，當模組不能被定位的時候會被 :keyword:`import` 所" +"引發。當在 :data:`sys.modules` 裡找到 ``None`` 時也會被引發。" + +#: ../../library/exceptions.rst:272 +msgid "" +"Raised when a sequence subscript is out of range. (Slice indices are " +"silently truncated to fall in the allowed range; if an index is not an " +"integer, :exc:`TypeError` is raised.)" +msgstr "" +"當序列的索引超出範圍的時候會被引發。（切片索引 (slice indices) 會默默地被截短" +"使其能落在允許的範圍內；如果索引不是整數，:exc:`TypeError` 會被引發。）" + +#: ../../library/exceptions.rst:281 +msgid "" +"Raised when a mapping (dictionary) key is not found in the set of existing " +"keys." +msgstr "當對映（字典）的鍵無法在已存在的鍵的集合中被找到時會被引發。" + +#: ../../library/exceptions.rst:288 +msgid "" +"Raised when the user hits the interrupt key (normally :kbd:`Control-C` or :" +"kbd:`Delete`). During execution, a check for interrupts is made regularly. " +"The exception inherits from :exc:`BaseException` so as to not be " +"accidentally caught by code that catches :exc:`Exception` and thus prevent " +"the interpreter from exiting." +msgstr "" +"當使用者輸入中斷鍵 (interrupt key)（一般來說是 :kbd:`Control-C` 或 :kbd:" +"`Delete`）時會被引發。在執行過程中，會定期檢查是否產生中斷。此例外繼承自 :" +"exc:`BaseException` 以防止意外地被捕捉 :exc:`Exception` 的程式碼所捕捉，而因" +"此讓直譯器無法結束。" + +#: ../../library/exceptions.rst:296 +msgid "" +"Catching a :exc:`KeyboardInterrupt` requires special consideration. Because " +"it can be raised at unpredictable points, it may, in some circumstances, " +"leave the running program in an inconsistent state. It is generally best to " +"allow :exc:`KeyboardInterrupt` to end the program as quickly as possible or " +"avoid raising it entirely. (See :ref:`handlers-and-exceptions`.)" +msgstr "" +"捕捉 :exc:`KeyboardInterrupt` 需要特殊的考量。因為它可以在無法預期的時間點被" +"引發，可能在某些情況下讓正在跑的程式處在一個不一致的狀態。一般來說最好讓 :" +"exc:`KeyboardInterrupt` 越快結束程式越好，或者完全避免引發它。（參考 :ref:" +"`handlers-and-exceptions`。）" + +#: ../../library/exceptions.rst:306 +msgid "" +"Raised when an operation runs out of memory but the situation may still be " +"rescued (by deleting some objects). The associated value is a string " +"indicating what kind of (internal) operation ran out of memory. Note that " +"because of the underlying memory management architecture (C's :c:func:" +"`malloc` function), the interpreter may not always be able to completely " +"recover from this situation; it nevertheless raises an exception so that a " +"stack traceback can be printed, in case a run-away program was the cause." +msgstr "" +"當一個操作用光了記憶體但情況還可能被修復 (rescued)（透過刪除一些物件）的時候" +"被引發。關聯值是一個字串，表示什麼類型的（內部）操作用光了記憶體。需注意的是" +"因為底層的記憶體管理架構（C 的 :c:func:`malloc` 函式），直譯器可能無法總是完" +"整地從該情況中修復；僅管如此，它還是引發例外以讓堆疊回溯可以被印出，以防原因" +"出在失控的程式。" + +#: ../../library/exceptions.rst:317 +msgid "" +"Raised when a local or global name is not found. This applies only to " +"unqualified names. The associated value is an error message that includes " +"the name that could not be found." +msgstr "" +"當找不到本地或全域的名稱時會被引發。這只應用在不合格的名稱 (unqualified " +"name) 上。關聯值是一個錯誤訊息，包含那個無法被找到的名稱。" + +#: ../../library/exceptions.rst:321 +msgid "The optional *name* keyword-only argument sets the attribute:" +msgstr "可選的僅限關鍵字引數 *name* 設定對應的屬性：" + +#: ../../library/exceptions.rst:325 +msgid "The name of the variable that was attempted to be accessed." +msgstr "嘗試被存取的變數名稱。" + +#: ../../library/exceptions.rst:327 +msgid "Added the :attr:`name` attribute." +msgstr "新增 :attr:`name` 屬性。" + +#: ../../library/exceptions.rst:333 +msgid "" +"This exception is derived from :exc:`RuntimeError`. In user defined base " +"classes, abstract methods should raise this exception when they require " +"derived classes to override the method, or while the class is being " +"developed to indicate that the real implementation still needs to be added." +msgstr "" +"此例外衍生自 :exc:`RuntimeError`。在使用者定義的基礎類別裡，當抽象方法要求衍" +"生類別覆寫該方法時應該要引發此例外，或者當類別正在開發中，可用此例外表示還需" +"要加入真正的實作。" + +#: ../../library/exceptions.rst:340 +msgid "" +"It should not be used to indicate that an operator or method is not meant to " +"be supported at all -- in that case either leave the operator / method " +"undefined or, if a subclass, set it to :data:`None`." +msgstr "" +"此例外不應該用來表示根本沒有要支援的運算子或方法 ── 在這個情況下可以讓該運算" +"子或方法保持未定義，或者如果是子類別的話將其設成 :data:`None`。" + +#: ../../library/exceptions.rst:346 +msgid "" +":exc:`!NotImplementedError` and :data:`!NotImplemented` are not " +"interchangeable. This exception should only be used as described above; see :" +"data:`NotImplemented` for details on correct usage of the built-in constant." +msgstr "" +":exc:`!NotImplementedError` 和 :data:`!NotImplemented` 並不是可互換的。這個例" +"外只能用在上面描述的情況；參考 :data:`NotImplemented` 裡關於內建常數正確使用" +"方法的細節。" + +#: ../../library/exceptions.rst:357 +msgid "" +"This exception is raised when a system function returns a system-related " +"error, including I/O failures such as \"file not found\" or \"disk " +"full\" (not for illegal argument types or other incidental errors)." +msgstr "" +"當系統函式回傳系統相關錯誤，包含像\"找不到檔案\"或\"硬碟已滿\"的 I/O 失敗會引" +"發此例外（而非不合法的引數或其他次要的錯誤）。" + +#: ../../library/exceptions.rst:361 +msgid "" +"The second form of the constructor sets the corresponding attributes, " +"described below. The attributes default to :const:`None` if not specified. " +"For backwards compatibility, if three arguments are passed, the :attr:" +"`~BaseException.args` attribute contains only a 2-tuple of the first two " +"constructor arguments." +msgstr "" +"建構函式的第二種形式會設定以下描述的相對應屬性。如果沒有給定則屬性預設為 :" +"const:`None`。為了向後相容，如果傳入三個引數，:attr:`~BaseException.args` 屬" +"性只會是包含建構函式前兩個引數的雙元素元組。" + +#: ../../library/exceptions.rst:367 +msgid "" +"The constructor often actually returns a subclass of :exc:`OSError`, as " +"described in `OS exceptions`_ below. The particular subclass depends on the " +"final :attr:`.errno` value. This behaviour only occurs when constructing :" +"exc:`OSError` directly or via an alias, and is not inherited when " +"subclassing." +msgstr "" +"如同下面的\\ `作業系統例外 `_\\ 所描述，實際上建構函式通常回" +"傳 :exc:`OSError` 的子類別。會依據最後 :attr:`.errno` 的值決定特定子類別。這" +"個行為只發生在直接建構 :exc:`OSError` 或透過別名，且產生子類別的時候不會被繼" +"承。" + +#: ../../library/exceptions.rst:375 +msgid "A numeric error code from the C variable :c:data:`errno`." +msgstr "從 C 變數 :c:data:`errno` 而來的數值錯誤代碼。" + +#: ../../library/exceptions.rst:379 +msgid "" +"Under Windows, this gives you the native Windows error code. The :attr:`." +"errno` attribute is then an approximate translation, in POSIX terms, of that " +"native error code." +msgstr "" +"在 Windows 下，這會提供你原生的 Windows 錯誤代碼。而 :attr:`.errno` 屬性是一" +"個該原生錯誤代碼對於 POSIX 來說的近似翻譯。" + +#: ../../library/exceptions.rst:383 +msgid "" +"Under Windows, if the *winerror* constructor argument is an integer, the :" +"attr:`.errno` attribute is determined from the Windows error code, and the " +"*errno* argument is ignored. On other platforms, the *winerror* argument is " +"ignored, and the :attr:`winerror` attribute does not exist." +msgstr "" +"在 Windows 下，如果建構函式引數 *winerror* 是整數，則 :attr:`.errno` 屬性會根" +"據該 Windows 錯誤代碼來決定，且 *errno* 引數會被忽略。在其他平台上，" +"*winerror* 引數會被忽略，而 :attr:`winerror` 屬性會不存在。" + +#: ../../library/exceptions.rst:391 +msgid "" +"The corresponding error message, as provided by the operating system. It is " +"formatted by the C functions :c:func:`!perror` under POSIX, and :c:func:`!" +"FormatMessage` under Windows." +msgstr "" +"作業系統提供的對應錯誤訊息。在 POSIX 下會使用 C 函式 :c:func:`!perror` 做格式" +"化，而在 Windows 下會使用 :c:func:`!FormatMessage`。" + +#: ../../library/exceptions.rst:399 +msgid "" +"For exceptions that involve a file system path (such as :func:`open` or :" +"func:`os.unlink`), :attr:`filename` is the file name passed to the function. " +"For functions that involve two file system paths (such as :func:`os." +"rename`), :attr:`filename2` corresponds to the second file name passed to " +"the function." +msgstr "" +"對於包含檔案系統路徑的例外（像是 :func:`open` 或 :func:`os.unlink`），:attr:" +"`filename` 是傳入函式的檔案名稱。對於包含兩個檔案系統路徑的函式（像是 :func:" +"`os.rename`），:attr:`filename2` 對應到傳入函式的第二個檔案名稱。" + +#: ../../library/exceptions.rst:406 +msgid "" +":exc:`EnvironmentError`, :exc:`IOError`, :exc:`WindowsError`, :exc:`socket." +"error`, :exc:`select.error` and :exc:`!mmap.error` have been merged into :" +"exc:`OSError`, and the constructor may return a subclass." +msgstr "" +":exc:`EnvironmentError`、:exc:`IOError`、:exc:`WindowsError`、:exc:`socket." +"error`、:exc:`select.error` 及 :exc:`!mmap.error` 已合併進 :exc:`OSError`，而" +"建構函式可能會回傳子類別。" + +#: ../../library/exceptions.rst:412 +msgid "" +"The :attr:`filename` attribute is now the original file name passed to the " +"function, instead of the name encoded to or decoded from the :term:" +"`filesystem encoding and error handler`. Also, the *filename2* constructor " +"argument and attribute was added." +msgstr "" +":attr:`filename` 屬性現在是傳入函式的原始檔名，而不是從\\ :term:`檔案系統編碼" +"和錯誤處理函式 `\\ 編碼或解碼過的名" +"稱。並且新增 *filename2* 建構函式引數與屬性。" + +#: ../../library/exceptions.rst:421 +msgid "" +"Raised when the result of an arithmetic operation is too large to be " +"represented. This cannot occur for integers (which would rather raise :exc:" +"`MemoryError` than give up). However, for historical reasons, OverflowError " +"is sometimes raised for integers that are outside a required range. " +"Because of the lack of standardization of floating-point exception handling " +"in C, most floating-point operations are not checked." +msgstr "" +"當運算操作的結果太大而無法表示的時候會引發此例外。這不會發生在整數上（會改成" +"引發 :exc:`MemoryError` 而不是放棄）。然而，因為一些歷史因素，OverflowError " +"有時候會因為整數在要求範圍之外而引發。因為在 C 裡面缺乏浮點數例外處理的標準" +"化，大部分的浮點數運算都沒有被檢查。" + +#: ../../library/exceptions.rst:431 +msgid "" +"This exception is derived from :exc:`RuntimeError`. It is raised when an " +"operation is blocked during interpreter shutdown also known as :term:`Python " +"finalization `." +msgstr "" +"此例外衍生自 :exc:`RuntimeError`。當一個操作在直譯器關閉（也稱作 :term:" +"`Python 最終化 (Python finalization） `）期間被阻塞會引" +"發此例外。" + +#: ../../library/exceptions.rst:435 +msgid "" +"Examples of operations which can be blocked with a :exc:" +"`PythonFinalizationError` during the Python finalization:" +msgstr "" +"在 Python 最終化期間，能夠以 :exc:`PythonFinalizationError` 被阻塞的操作範" +"例：" + +#: ../../library/exceptions.rst:438 +msgid "Creating a new Python thread." +msgstr "建立新的 Python 執行緒。" + +#: ../../library/exceptions.rst:439 +msgid ":meth:`Joining ` a running daemon thread." +msgstr "" + +#: ../../library/exceptions.rst:440 +msgid ":func:`os.fork`." +msgstr ":func:`os.fork`。" + +#: ../../library/exceptions.rst:442 +msgid "See also the :func:`sys.is_finalizing` function." +msgstr "也可以參閱 :func:`sys.is_finalizing` 函式。" + +#: ../../library/exceptions.rst:444 ../../library/exceptions.rst:457 +msgid "Previously, a plain :exc:`RuntimeError` was raised." +msgstr "在之前，會引發一般的 :exc:`RuntimeError`。" + +#: ../../library/exceptions.rst:449 +msgid ":meth:`threading.Thread.join` can now raise this exception." +msgstr "" + +#: ../../library/exceptions.rst:453 +msgid "" +"This exception is derived from :exc:`RuntimeError`. It is raised when the " +"interpreter detects that the maximum recursion depth (see :func:`sys." +"getrecursionlimit`) is exceeded." +msgstr "" +"此例外衍生自 :exc:`RuntimeError`。當直譯器偵測到超過最大的遞迴深度（參考 :" +"func:`sys.getrecursionlimit`）時會引發此例外。" + +#: ../../library/exceptions.rst:463 +msgid "" +"This exception is raised when a weak reference proxy, created by the :func:" +"`weakref.proxy` function, is used to access an attribute of the referent " +"after it has been garbage collected. For more information on weak " +"references, see the :mod:`weakref` module." +msgstr "" +"當一個被 :func:`weakref.proxy` 函式建立的弱參照代理 (weak reference proxy) 被" +"用來存取已經被垃圾回收 (garbage collected) 的參照物屬性時會引發此例外。更多關" +"於弱參照的資訊參考 :mod:`weakref` 模組。" + +#: ../../library/exceptions.rst:471 +msgid "" +"Raised when an error is detected that doesn't fall in any of the other " +"categories. The associated value is a string indicating what precisely went " +"wrong." +msgstr "" +"當偵測到一個不屬於任何其他種類的錯誤時會引發此例外。關聯值是一個表示確切什麼" +"地方出錯的字串。" + +#: ../../library/exceptions.rst:478 +msgid "" +"Raised by built-in function :func:`next` and an :term:`iterator`\\'s :meth:" +"`~iterator.__next__` method to signal that there are no further items " +"produced by the iterator." +msgstr "" +"會被內建函式 :func:`next` 及 :term:`iterator` 的 :meth:`~iterator.__next__` " +"方法引發，用來表示疊代器沒有更多項目可以產生。" + +#: ../../library/exceptions.rst:484 +msgid "" +"The exception object has a single attribute :attr:`!value`, which is given " +"as an argument when constructing the exception, and defaults to :const:" +"`None`." +msgstr "" +"此例外物件有單一屬性 :attr:`!value`，當建構此例外時會以引數給定，預設為 :" +"const:`None`。" + +#: ../../library/exceptions.rst:488 +msgid "" +"When a :term:`generator` or :term:`coroutine` function returns, a new :exc:" +"`StopIteration` instance is raised, and the value returned by the function " +"is used as the :attr:`value` parameter to the constructor of the exception." +msgstr "" +"當 :term:`generator` 或 :term:`coroutine` 函式回傳時，新的 :exc:" +"`StopIteration` 實例會被引發，而該函式的回傳值會被用來當作此例外建構函式的 :" +"attr:`value` 參數。" + +#: ../../library/exceptions.rst:493 +msgid "" +"If a generator code directly or indirectly raises :exc:`StopIteration`, it " +"is converted into a :exc:`RuntimeError` (retaining the :exc:`StopIteration` " +"as the new exception's cause)." +msgstr "" +"如果產生器程式直接或間接引發 :exc:`StopIteration`，則其會被轉換成 :exc:" +"`RuntimeError`\\ （保留 :exc:`StopIteration` 作為新例外的成因）。" + +#: ../../library/exceptions.rst:497 +msgid "" +"Added ``value`` attribute and the ability for generator functions to use it " +"to return a value." +msgstr "新增 ``value`` 屬性且產生器函式可以用它來回傳值。" + +#: ../../library/exceptions.rst:501 +msgid "" +"Introduced the RuntimeError transformation via ``from __future__ import " +"generator_stop``, see :pep:`479`." +msgstr "" +"透過 ``from __future__ import generator_stop`` 引入 RuntimeError 的轉換，參" +"考 :pep:`479`。" + +#: ../../library/exceptions.rst:505 +msgid "" +"Enable :pep:`479` for all code by default: a :exc:`StopIteration` error " +"raised in a generator is transformed into a :exc:`RuntimeError`." +msgstr "" +"預設對所有程式啟用 :pep:`479`：在產生器引發的 :exc:`StopIteration` 錯誤會轉換" +"成 :exc:`RuntimeError`。" + +#: ../../library/exceptions.rst:511 +msgid "" +"Must be raised by :meth:`~object.__anext__` method of an :term:`asynchronous " +"iterator` object to stop the iteration." +msgstr "" +"此例外必須被 :term:`asynchronous iterator` 物件的 :meth:`~object.__anext__` " +"方法引發來停止疊代。" + +#: ../../library/exceptions.rst:518 +msgid "" +"Raised when the parser encounters a syntax error. This may occur in an :" +"keyword:`import` statement, in a call to the built-in functions :func:" +"`compile`, :func:`exec`, or :func:`eval`, or when reading the initial script " +"or standard input (also interactively)." +msgstr "" +"當剖析器遇到語法錯誤時會引發此例外。這可能發生在 :keyword:`import` 陳述式、在" +"呼叫內建函式 :func:`compile`、:func:`exec` 或 :func:`eval` 的時候，或者在讀取" +"初始腳本或標準輸入（也包含互動式）的時候。" + +#: ../../library/exceptions.rst:524 +msgid "" +"The :func:`str` of the exception instance returns only the error message. " +"Details is a tuple whose members are also available as separate attributes." +msgstr "" +"例外實例的 :func:`str` 只回傳錯誤訊息。Details 是個元組，其成員也能夠以分開的" +"屬性取得。" + +#: ../../library/exceptions.rst:529 +msgid "The name of the file the syntax error occurred in." +msgstr "發生語法錯誤所在的檔案名稱。" + +#: ../../library/exceptions.rst:533 +msgid "" +"Which line number in the file the error occurred in. This is 1-indexed: the " +"first line in the file has a ``lineno`` of 1." +msgstr "" +"發生錯誤所在檔案的列號。這是以 1 開始的索引：檔案第一列的 ``lineno`` 是 1。" + +#: ../../library/exceptions.rst:538 +msgid "" +"The column in the line where the error occurred. This is 1-indexed: the " +"first character in the line has an ``offset`` of 1." +msgstr "" +"發生錯誤所在該列的欄號 (column)。這是以 1 開始的索引：該列第一個字元的 " +"``offset`` 是 1。" + +#: ../../library/exceptions.rst:543 +msgid "The source code text involved in the error." +msgstr "涉及該錯誤的原始程式碼文字。" + +#: ../../library/exceptions.rst:547 +msgid "" +"Which line number in the file the error occurred ends in. This is 1-indexed: " +"the first line in the file has a ``lineno`` of 1." +msgstr "" +"發生錯誤所在檔案的結束列號。這是以 1 開始的索引：檔案第一列的 ``lineno`` 是 " +"1。" + +#: ../../library/exceptions.rst:552 +msgid "" +"The column in the end line where the error occurred finishes. This is 1-" +"indexed: the first character in the line has an ``offset`` of 1." +msgstr "" +"發生錯誤所在該結束列的欄號。這是以 1 開始的索引：該列第一個字元的 ``offset`` " +"是 1。" + +#: ../../library/exceptions.rst:555 +msgid "" +"For errors in f-string fields, the message is prefixed by \"f-string: \" and " +"the offsets are offsets in a text constructed from the replacement " +"expression. For example, compiling f'Bad {a b} field' results in this args " +"attribute: ('f-string: ...', ('', 1, 2, '(a b)\\n', 1, 5))." +msgstr "" +"對於發生在 f-string 欄位的錯誤，訊息會以 \"f-string: \" 為前綴，而偏移量 " +"(offset) 是從替代運算式建構的文字的偏移量。例如編譯 f'Bad {a b} field' 會得到" +"這個 args 屬性：('f-string: ...', ('', 1, 2, '(a b)\\n', 1, 5))。" + +#: ../../library/exceptions.rst:560 +msgid "Added the :attr:`end_lineno` and :attr:`end_offset` attributes." +msgstr "新增 :attr:`end_lineno` 與 :attr:`end_offset` 屬性。" + +#: ../../library/exceptions.rst:565 +msgid "" +"Base class for syntax errors related to incorrect indentation. This is a " +"subclass of :exc:`SyntaxError`." +msgstr "" +"與不正確的縮排有關的語法錯誤的基礎類別。這是 :exc:`SyntaxError` 的子類別。" + +#: ../../library/exceptions.rst:571 +msgid "" +"Raised when indentation contains an inconsistent use of tabs and spaces. " +"This is a subclass of :exc:`IndentationError`." +msgstr "" +"當縮排包含製表符號 (tab) 和空白的不一致用法時會引發此例外。這是 :exc:" +"`IndentationError` 的子類別。" + +#: ../../library/exceptions.rst:577 +msgid "" +"Raised when the interpreter finds an internal error, but the situation does " +"not look so serious to cause it to abandon all hope. The associated value is " +"a string indicating what went wrong (in low-level terms). In :term:" +"`CPython`, this could be raised by incorrectly using Python's C API, such as " +"returning a ``NULL`` value without an exception set." +msgstr "" +"當直譯器找到一個內部錯誤，但該情況看起來沒有嚴重到要讓它放棄所有的希望時會引" +"發此例外。關聯值是一個表示什麼地方出錯的字串（以低階的方式表達）。在 :term:" +"`CPython` 中，這可能是因為錯誤地使用 Python 的 C API，例如回傳一個 ``NULL`` " +"值而沒有設定例外。" + +#: ../../library/exceptions.rst:583 +msgid "" +"If you're confident that this exception wasn't your fault, or the fault of a " +"package you're using, you should report this to the author or maintainer of " +"your Python interpreter. Be sure to report the version of the Python " +"interpreter (``sys.version``; it is also printed at the start of an " +"interactive Python session), the exact error message (the exception's " +"associated value) and if possible the source of the program that triggered " +"the error." +msgstr "" +"如果你確定這個例外不是你的或者所用套件的錯，你應該向你的 Python 直譯器作者或" +"維護者回報此錯誤。務必要回報該 Python 直譯器的版本（``sys.version``；這也會在" +"互動式 Python 會話的開頭被印出）、確切的錯誤訊息（該例外的關聯值）及如果可能" +"的話，觸發此錯誤的程式來源。" + +#: ../../library/exceptions.rst:594 +msgid "" +"This exception is raised by the :func:`sys.exit` function. It inherits " +"from :exc:`BaseException` instead of :exc:`Exception` so that it is not " +"accidentally caught by code that catches :exc:`Exception`. This allows the " +"exception to properly propagate up and cause the interpreter to exit. When " +"it is not handled, the Python interpreter exits; no stack traceback is " +"printed. The constructor accepts the same optional argument passed to :func:" +"`sys.exit`. If the value is an integer, it specifies the system exit status " +"(passed to C's :c:func:`!exit` function); if it is ``None``, the exit status " +"is zero; if it has another type (such as a string), the object's value is " +"printed and the exit status is one." +msgstr "" +"此例外會被 :func:`sys.exit` 函式引發。它繼承自 :exc:`BaseException` 而不是 :" +"exc:`Exception` 因此不會被捕捉 :exc:`Exception` 的程式意外地捕捉。這允許例外" +"可以正確地向上傳遞並導致直譯器結束。當它未被處理時，Python 直譯器會結束；不會" +"印出堆疊回溯。建構函式接受跟傳入 :func:`sys.exit` 一樣的可選引數。如果該值是" +"整數，它會指定系統的結束狀態（傳入 C 的 :c:func:`!exit` 函式）；如果它是 " +"``None``，結束狀態會是 0；如果它是其他型別（例如字串），則物件的值會被印出而" +"結束狀態是 1。" + +#: ../../library/exceptions.rst:605 +msgid "" +"A call to :func:`sys.exit` is translated into an exception so that clean-up " +"handlers (:keyword:`finally` clauses of :keyword:`try` statements) can be " +"executed, and so that a debugger can execute a script without running the " +"risk of losing control. The :func:`os._exit` function can be used if it is " +"absolutely positively necessary to exit immediately (for example, in the " +"child process after a call to :func:`os.fork`)." +msgstr "" +"對 :func:`sys.exit` 的呼叫會轉譯成例外讓負責清理的處理函式（:keyword:`try` 陳" +"述式的 :keyword:`finally` 子句）可以被執行，且讓除錯器可以在不冒著失去控制的" +"風險下執行腳本。如果在絕對有必要立即結束的情況（例如在子行程呼叫完 :func:`os." +"fork` 之後 ）可以使用 :func:`os._exit` 函式。" + +#: ../../library/exceptions.rst:614 +msgid "" +"The exit status or error message that is passed to the constructor. " +"(Defaults to ``None``.)" +msgstr "傳入建構函式的結束狀態或錯誤訊息。（預設是 ``None``。 ）" + +#: ../../library/exceptions.rst:620 +msgid "" +"Raised when an operation or function is applied to an object of " +"inappropriate type. The associated value is a string giving details about " +"the type mismatch." +msgstr "" +"當一個操作或函式被用在不適合的型別的物件時會引發此例外。關聯值是一個字串，提" +"供關於不相符型別的細節。" + +#: ../../library/exceptions.rst:623 +msgid "" +"This exception may be raised by user code to indicate that an attempted " +"operation on an object is not supported, and is not meant to be. If an " +"object is meant to support a given operation but has not yet provided an " +"implementation, :exc:`NotImplementedError` is the proper exception to raise." +msgstr "" +"此例外可能被使用者程式碼引發，以表示並不支援物件上所嘗試的操作，且本來就無意" +"這樣做。如果一個物件有意要支援某個給定的操作但尚未提供實作，該引發的正確例外" +"是 :exc:`NotImplementedError`。" + +#: ../../library/exceptions.rst:628 +msgid "" +"Passing arguments of the wrong type (e.g. passing a :class:`list` when an :" +"class:`int` is expected) should result in a :exc:`TypeError`, but passing " +"arguments with the wrong value (e.g. a number outside expected boundaries) " +"should result in a :exc:`ValueError`." +msgstr "" +"傳入錯誤型別的引數（例如當預期傳入 :class:`int` 卻傳入 :class:`list`）應該要" +"導致 :exc:`TypeError`，但傳入帶有錯誤值的引數（例如超出預期範圍的數值）應該要" +"導致 :exc:`ValueError`。" + +#: ../../library/exceptions.rst:635 +msgid "" +"Raised when a reference is made to a local variable in a function or method, " +"but no value has been bound to that variable. This is a subclass of :exc:" +"`NameError`." +msgstr "" +"當在函式或方法裡引用某個區域變數，但該變數尚未被繫結到任何值的時候會引發此例" +"外。這是 :exc:`NameError` 的子類別。" + +#: ../../library/exceptions.rst:642 +msgid "" +"Raised when a Unicode-related encoding or decoding error occurs. It is a " +"subclass of :exc:`ValueError`." +msgstr "" +"當 Unicode 相關的編碼或解碼錯誤發生時會引發此例外。這是 :exc:`ValueError` 的" +"子類別。" + +#: ../../library/exceptions.rst:645 +msgid "" +":exc:`UnicodeError` has attributes that describe the encoding or decoding " +"error. For example, ``err.object[err.start:err.end]`` gives the particular " +"invalid input that the codec failed on." +msgstr "" +":exc:`UnicodeError` 有屬性描述編碼或解碼錯誤。例如 ``err.object[err.start:" +"err.end]`` 會提供讓編解碼器失敗的具體無效輸入。" + +#: ../../library/exceptions.rst:651 +msgid "The name of the encoding that raised the error." +msgstr "引發錯誤的編碼名稱。" + +#: ../../library/exceptions.rst:655 +msgid "A string describing the specific codec error." +msgstr "描述特定編解碼器錯誤的字串。" + +#: ../../library/exceptions.rst:659 +msgid "The object the codec was attempting to encode or decode." +msgstr "編解碼器嘗試編碼或解碼的物件。" + +#: ../../library/exceptions.rst:663 +msgid "The first index of invalid data in :attr:`object`." +msgstr "在 :attr:`object` 中無效資料的開始索引。" + +#: ../../library/exceptions.rst:665 ../../library/exceptions.rst:672 +msgid "" +"This value should not be negative as it is interpreted as an absolute offset " +"but this constraint is not enforced at runtime." +msgstr "" + +#: ../../library/exceptions.rst:670 +msgid "The index after the last invalid data in :attr:`object`." +msgstr "在 :attr:`object` 中最後的無效資料後的索引。" + +#: ../../library/exceptions.rst:678 +msgid "" +"Raised when a Unicode-related error occurs during encoding. It is a " +"subclass of :exc:`UnicodeError`." +msgstr "" +"在編碼當中發生 Unicode 相關錯誤時會引發此例外。這是 :exc:`UnicodeError` 的子" +"類別。" + +#: ../../library/exceptions.rst:684 +msgid "" +"Raised when a Unicode-related error occurs during decoding. It is a " +"subclass of :exc:`UnicodeError`." +msgstr "" +"在解碼當中發生 Unicode 相關錯誤時會引發此例外。這是 :exc:`UnicodeError` 的子" +"類別。" + +#: ../../library/exceptions.rst:690 +msgid "" +"Raised when a Unicode-related error occurs during translating. It is a " +"subclass of :exc:`UnicodeError`." +msgstr "" +"在轉譯當中發生 Unicode 相關錯誤時會引發此例外。這是 :exc:`UnicodeError` 的子" +"類別。" + +#: ../../library/exceptions.rst:696 +msgid "" +"Raised when an operation or function receives an argument that has the right " +"type but an inappropriate value, and the situation is not described by a " +"more precise exception such as :exc:`IndexError`." +msgstr "" +"當一個操作或函式收到引數是正確型別但是不適合的值，且該情況無法被更精確的例外" +"例如 :exc:`IndexError` 所描述時會引發此例外。" + +#: ../../library/exceptions.rst:703 +msgid "" +"Raised when the second argument of a division or modulo operation is zero. " +"The associated value is a string indicating the type of the operands and the " +"operation." +msgstr "" +"當除法或模數運算 (modulo operation) 的第二個引數是 0 的時候會引發此例外。關聯" +"值是一個字串，表示運算元及運算的類型。" + +#: ../../library/exceptions.rst:708 +msgid "" +"The following exceptions are kept for compatibility with previous versions; " +"starting from Python 3.3, they are aliases of :exc:`OSError`." +msgstr "" +"以下例外是為了相容於之前版本而保留；從 Python 3.3 開始，它們是 :exc:" +"`OSError` 的別名。" + +#: ../../library/exceptions.rst:717 +msgid "Only available on Windows." +msgstr "僅限於在 Windows 中使用。" + +#: ../../library/exceptions.rst:721 +msgid "OS exceptions" +msgstr "作業系統例外" + +#: ../../library/exceptions.rst:723 +msgid "" +"The following exceptions are subclasses of :exc:`OSError`, they get raised " +"depending on the system error code." +msgstr "以下的例外是 :exc:`OSError` 的子類別，它們根據系統錯誤代碼來引發。" + +#: ../../library/exceptions.rst:728 +msgid "" +"Raised when an operation would block on an object (e.g. socket) set for non-" +"blocking operation. Corresponds to :c:data:`errno` :py:const:`~errno." +"EAGAIN`, :py:const:`~errno.EALREADY`, :py:const:`~errno.EWOULDBLOCK` and :py:" +"const:`~errno.EINPROGRESS`." +msgstr "" +"當設置為非阻塞操作的物件（例如 socket）上的操作將要阻塞時會引發此例外。對應" +"到 :c:data:`errno` :py:const:`~errno.EAGAIN`、:py:const:`~errno.EALREADY`、:" +"py:const:`~errno.EWOULDBLOCK` 及 :py:const:`~errno.EINPROGRESS`。" + +#: ../../library/exceptions.rst:733 +msgid "" +"In addition to those of :exc:`OSError`, :exc:`BlockingIOError` can have one " +"more attribute:" +msgstr "" +"除了 :exc:`OSError` 的那些屬性之外，:exc:`BlockingIOError` 有多一個屬性：" + +#: ../../library/exceptions.rst:738 +msgid "" +"An integer containing the number of **bytes** written to the stream before " +"it blocked. This attribute is available when using the buffered I/O classes " +"from the :mod:`io` module." +msgstr "" +"一個整數，內容為在其阻塞之前，已寫進串流的\\ **位元組**\\ 數。當使用 :mod:`io` 模組裡的緩" +"衝 I/O 類別時這個屬性是可用的。" + +#: ../../library/exceptions.rst:744 +msgid "" +"Raised when an operation on a child process failed. Corresponds to :c:data:" +"`errno` :py:const:`~errno.ECHILD`." +msgstr "" +"當子行程上的操作失敗時會引發此例外。對應到 :c:data:`errno` :py:const:`~errno." +"ECHILD`。" + +#: ../../library/exceptions.rst:749 +msgid "A base class for connection-related issues." +msgstr "連線相關問題的基礎類別。" + +#: ../../library/exceptions.rst:751 +msgid "" +"Subclasses are :exc:`BrokenPipeError`, :exc:`ConnectionAbortedError`, :exc:" +"`ConnectionRefusedError` and :exc:`ConnectionResetError`." +msgstr "" +"子類別有 :exc:`BrokenPipeError`、:exc:`ConnectionAbortedError`、:exc:" +"`ConnectionRefusedError` 及 :exc:`ConnectionResetError`。" + +#: ../../library/exceptions.rst:756 +msgid "" +"A subclass of :exc:`ConnectionError`, raised when trying to write on a pipe " +"while the other end has been closed, or trying to write on a socket which " +"has been shutdown for writing. Corresponds to :c:data:`errno` :py:const:" +"`~errno.EPIPE` and :py:const:`~errno.ESHUTDOWN`." +msgstr "" +":exc:`ConnectionError` 的子類別，當嘗試寫入管道 (pipe) 同時另一端已經被關閉時" +"會引發此例外，或者當嘗試寫入已關閉寫入的 socket 時也會引發。對應到 :c:data:" +"`errno` :py:const:`~errno.EPIPE` 及 :py:const:`~errno.ESHUTDOWN`。" + +#: ../../library/exceptions.rst:763 +msgid "" +"A subclass of :exc:`ConnectionError`, raised when a connection attempt is " +"aborted by the peer. Corresponds to :c:data:`errno` :py:const:`~errno." +"ECONNABORTED`." +msgstr "" +":exc:`ConnectionError` 的子類別。當一個連線的嘗試被對等端點 (peer) 中斷時會引" +"發此例外。對應到 :c:data:`errno` :py:const:`~errno.ECONNABORTED`。" + +#: ../../library/exceptions.rst:769 +msgid "" +"A subclass of :exc:`ConnectionError`, raised when a connection attempt is " +"refused by the peer. Corresponds to :c:data:`errno` :py:const:`~errno." +"ECONNREFUSED`." +msgstr "" +":exc:`ConnectionError` 的子類別。當一個連線的嘗試被對等端點拒絕時會引發此例" +"外。對應到 :c:data:`errno` :py:const:`~errno.ECONNREFUSED`。" + +#: ../../library/exceptions.rst:775 +msgid "" +"A subclass of :exc:`ConnectionError`, raised when a connection is reset by " +"the peer. Corresponds to :c:data:`errno` :py:const:`~errno.ECONNRESET`." +msgstr "" +":exc:`ConnectionError` 的子類別。當一個連線被對等端點重置時會引發此例外。對應" +"到 :c:data:`errno` :py:const:`~errno.ECONNRESET`。" + +#: ../../library/exceptions.rst:781 +msgid "" +"Raised when trying to create a file or directory which already exists. " +"Corresponds to :c:data:`errno` :py:const:`~errno.EEXIST`." +msgstr "" +"當嘗試建立已存在的檔案或目錄時會引發此例外。對應到 :c:data:`errno` :py:const:" +"`~errno.EEXIST`。" + +#: ../../library/exceptions.rst:786 +msgid "" +"Raised when a file or directory is requested but doesn't exist. Corresponds " +"to :c:data:`errno` :py:const:`~errno.ENOENT`." +msgstr "" +"當請求不存在的檔案或目錄時會引發此例外。對應到 :c:data:`errno` :py:const:" +"`~errno.ENOENT`。" + +#: ../../library/exceptions.rst:791 +msgid "" +"Raised when a system call is interrupted by an incoming signal. Corresponds " +"to :c:data:`errno` :py:const:`~errno.EINTR`." +msgstr "" +"當系統呼叫被傳入的信號中斷時會引發此例外。對應到 :c:data:`errno` :py:const:" +"`~errno.EINTR`。" + +#: ../../library/exceptions.rst:794 +msgid "" +"Python now retries system calls when a syscall is interrupted by a signal, " +"except if the signal handler raises an exception (see :pep:`475` for the " +"rationale), instead of raising :exc:`InterruptedError`." +msgstr "" +"現在當 syscall 被信號中斷時 Python 會重試系統呼叫而不會引發 :exc:" +"`InterruptedError`，除非信號處理器引發例外（理由可參考 :pep:`475`）。" + +#: ../../library/exceptions.rst:801 +msgid "" +"Raised when a file operation (such as :func:`os.remove`) is requested on a " +"directory. Corresponds to :c:data:`errno` :py:const:`~errno.EISDIR`." +msgstr "" +"當在目錄上請求檔案操作（例如 :func:`os.remove`）時會引發此例外。對應到 :c:" +"data:`errno` :py:const:`~errno.EISDIR`。" + +#: ../../library/exceptions.rst:807 +msgid "" +"Raised when a directory operation (such as :func:`os.listdir`) is requested " +"on something which is not a directory. On most POSIX platforms, it may also " +"be raised if an operation attempts to open or traverse a non-directory file " +"as if it were a directory. Corresponds to :c:data:`errno` :py:const:`~errno." +"ENOTDIR`." +msgstr "" +"當在某個不是目錄的東西上請求目錄操作（例如 :func:`os.listdir`）時會引發此例" +"外。在大多數的 POSIX 平台上，如果嘗試操作開啟或遍歷一個當作目錄的非目錄檔案也" +"會引發此例外。對應到 :c:data:`errno` :py:const:`~errno.ENOTDIR`。" + +#: ../../library/exceptions.rst:815 +msgid "" +"Raised when trying to run an operation without the adequate access rights - " +"for example filesystem permissions. Corresponds to :c:data:`errno` :py:const:" +"`~errno.EACCES`, :py:const:`~errno.EPERM`, and :py:const:`~errno." +"ENOTCAPABLE`." +msgstr "" +"當嘗試執行一個沒有合乎存取權限的操作時會引發此例外 — 例如檔案系統權限。對應" +"到 :c:data:`errno` :py:const:`~errno.EACCES`、:py:const:`~errno.EPERM` 及 :" +"py:const:`~errno.ENOTCAPABLE`。" + +#: ../../library/exceptions.rst:820 +msgid "" +"WASI's :py:const:`~errno.ENOTCAPABLE` is now mapped to :exc:" +"`PermissionError`." +msgstr "" +"WASI 的 :py:const:`~errno.ENOTCAPABLE` 現在對應到 :exc:`PermissionError`。" + +#: ../../library/exceptions.rst:826 +msgid "" +"Raised when a given process doesn't exist. Corresponds to :c:data:`errno` :" +"py:const:`~errno.ESRCH`." +msgstr "" +"當給定的行程不存在時會引發此例外。對應到 :c:data:`errno` :py:const:`~errno." +"ESRCH`。" + +#: ../../library/exceptions.rst:831 +msgid "" +"Raised when a system function timed out at the system level. Corresponds to :" +"c:data:`errno` :py:const:`~errno.ETIMEDOUT`." +msgstr "" +"當系統函式在系統層級超時會引發此例外。對應到 :c:data:`errno` :py:const:" +"`~errno.ETIMEDOUT`。" + +#: ../../library/exceptions.rst:834 +msgid "All the above :exc:`OSError` subclasses were added." +msgstr "加入以上所有的 :exc:`OSError` 子類別。" + +#: ../../library/exceptions.rst:840 +msgid ":pep:`3151` - Reworking the OS and IO exception hierarchy" +msgstr ":pep:`3151` — 改寫作業系統與 IO 例外階層" + +#: ../../library/exceptions.rst:846 +msgid "Warnings" +msgstr "警告" + +#: ../../library/exceptions.rst:848 +msgid "" +"The following exceptions are used as warning categories; see the :ref:" +"`warning-categories` documentation for more details." +msgstr "" +"以下的例外是當作警告的種類使用；更多細節參考 :ref:`warning-categories` 文件。" + +#: ../../library/exceptions.rst:853 +msgid "Base class for warning categories." +msgstr "警告種類的基礎類別。" + +#: ../../library/exceptions.rst:858 +msgid "Base class for warnings generated by user code." +msgstr "使用者程式碼產生的警告的基礎類別。" + +#: ../../library/exceptions.rst:863 +msgid "" +"Base class for warnings about deprecated features when those warnings are " +"intended for other Python developers." +msgstr "關於已棄用功能的警告的基礎類別，且當那些警告是針對其他 Python 開發者。" + +#: ../../library/exceptions.rst:866 +msgid "" +"Ignored by the default warning filters, except in the ``__main__`` module (:" +"pep:`565`). Enabling the :ref:`Python Development Mode ` shows this " +"warning." +msgstr "" +"會被預設的警告過濾器忽略，在 ``__main__`` 模組裡除外 (:pep:`565`)。啟用 :ref:" +"`Python 開發模式 `\\ 會顯示此警告。" + +#: ../../library/exceptions.rst:870 ../../library/exceptions.rst:886 +msgid "The deprecation policy is described in :pep:`387`." +msgstr "棄用原則描述在 :pep:`387` 裡。" + +#: ../../library/exceptions.rst:875 +msgid "" +"Base class for warnings about features which are obsolete and expected to be " +"deprecated in the future, but are not deprecated at the moment." +msgstr "關於過時且預期未來要被棄用，但目前尚未被棄用的功能的警告的基礎類別。" + +#: ../../library/exceptions.rst:879 +msgid "" +"This class is rarely used as emitting a warning about a possible upcoming " +"deprecation is unusual, and :exc:`DeprecationWarning` is preferred for " +"already active deprecations." +msgstr "" +"因為發出關於可能即將被棄用的警告是不尋常的，此類別很少被使用，而對已經被棄用" +"的情況會優先使用 :exc:`DeprecationWarning`。" + +#: ../../library/exceptions.rst:883 ../../library/exceptions.rst:912 +#: ../../library/exceptions.rst:939 +msgid "" +"Ignored by the default warning filters. Enabling the :ref:`Python " +"Development Mode ` shows this warning." +msgstr "" +"會被預設的警告過濾器忽略。啟用 :ref:`Python 開發模式 `\\ 會顯示此警" +"告。" + +#: ../../library/exceptions.rst:891 +msgid "Base class for warnings about dubious syntax." +msgstr "關於可疑語法的警告的基礎類別。" + +#: ../../library/exceptions.rst:893 +msgid "" +"This warning is typically emitted when compiling Python source code, and " +"usually won't be reported when running already compiled code." +msgstr "" + +#: ../../library/exceptions.rst:899 +msgid "Base class for warnings about dubious runtime behavior." +msgstr "關於可疑執行環境行為的警告的基礎類別。" + +#: ../../library/exceptions.rst:904 +msgid "" +"Base class for warnings about deprecated features when those warnings are " +"intended for end users of applications that are written in Python." +msgstr "" +"關於已棄用功能的警告的基礎類別，且當那些警告是針對以 Python 寫的應用程式的終" +"端使用者。" + +#: ../../library/exceptions.rst:910 +msgid "Base class for warnings about probable mistakes in module imports." +msgstr "關於在模組引入的可能錯誤的警告的基礎類別。" + +#: ../../library/exceptions.rst:918 +msgid "Base class for warnings related to Unicode." +msgstr "Unicode 相關警告的基礎類別。" + +#: ../../library/exceptions.rst:923 +msgid "Base class for warnings related to encodings." +msgstr "編碼相關警告的基礎類別。" + +#: ../../library/exceptions.rst:925 +msgid "See :ref:`io-encoding-warning` for details." +msgstr "細節參考\\ :ref:`io-encoding-warning`。" + +#: ../../library/exceptions.rst:932 +msgid "" +"Base class for warnings related to :class:`bytes` and :class:`bytearray`." +msgstr ":class:`bytes` 及 :class:`bytearray` 相關警告的基礎類別。" + +#: ../../library/exceptions.rst:937 +msgid "Base class for warnings related to resource usage." +msgstr "資源用法相關警告的基礎類別。" + +#: ../../library/exceptions.rst:948 +msgid "Exception groups" +msgstr "例外群組" + +#: ../../library/exceptions.rst:950 +msgid "" +"The following are used when it is necessary to raise multiple unrelated " +"exceptions. They are part of the exception hierarchy so they can be handled " +"with :keyword:`except` like all other exceptions. In addition, they are " +"recognised by :keyword:`except*`, which matches their subgroups " +"based on the types of the contained exceptions." +msgstr "" +"當需要引發多個不相關例外時會使用下列的類別。它們是例外階層的一部分所以可以像" +"所有其他例外一樣使用 :keyword:`except` 來處理。此外，它們會以包含的例外型別為" +"基礎來比對其子群組而被 :keyword:`except*` 辨認出來。" + +#: ../../library/exceptions.rst:959 +msgid "" +"Both of these exception types wrap the exceptions in the sequence ``excs``. " +"The ``msg`` parameter must be a string. The difference between the two " +"classes is that :exc:`BaseExceptionGroup` extends :exc:`BaseException` and " +"it can wrap any exception, while :exc:`ExceptionGroup` extends :exc:" +"`Exception` and it can only wrap subclasses of :exc:`Exception`. This design " +"is so that ``except Exception`` catches an :exc:`ExceptionGroup` but not :" +"exc:`BaseExceptionGroup`." +msgstr "" +"這兩個例外型別都將例外包裝在序列 ``excs`` 中。``msg`` 參數必須是字串。這兩個" +"類別的差異是 :exc:`BaseExceptionGroup` 擴充了 :exc:`BaseException` 且可以包裝" +"任何例外，而 :exc:`ExceptionGroup` 擴充了 :exc:`Exception` 且只能包裝 :exc:" +"`Exception` 的子類別。這個設計使得 ``except Exception`` 可以捕捉 :exc:" +"`ExceptionGroup` 但不能捕捉 :exc:`BaseExceptionGroup`。" + +#: ../../library/exceptions.rst:967 +msgid "" +"The :exc:`BaseExceptionGroup` constructor returns an :exc:`ExceptionGroup` " +"rather than a :exc:`BaseExceptionGroup` if all contained exceptions are :exc:" +"`Exception` instances, so it can be used to make the selection automatic. " +"The :exc:`ExceptionGroup` constructor, on the other hand, raises a :exc:" +"`TypeError` if any contained exception is not an :exc:`Exception` subclass." +msgstr "" +"如果所有包含的例外都是 :exc:`Exception` 實例，:exc:`BaseExceptionGroup` 建構" +"函式會回傳 :exc:`ExceptionGroup` 而不是 :exc:`BaseExceptionGroup`，因此可以被" +"使用來讓這樣的選擇自動化。另一方面來說，如果任何包含的例外不是 :exc:" +"`Exception` 的子類別，:exc:`ExceptionGroup` 建構函式會引發 :exc:`TypeError`。" + +#: ../../library/exceptions.rst:976 +msgid "The ``msg`` argument to the constructor. This is a read-only attribute." +msgstr "建構函式的 ``msg`` 引數。這是一個唯讀的屬性。" + +#: ../../library/exceptions.rst:980 +msgid "" +"A tuple of the exceptions in the ``excs`` sequence given to the constructor. " +"This is a read-only attribute." +msgstr "指定給建構函式 ``excs`` 序列中的例外組成的元組。這是一個唯讀的屬性。" + +#: ../../library/exceptions.rst:985 +msgid "" +"Returns an exception group that contains only the exceptions from the " +"current group that match *condition*, or ``None`` if the result is empty." +msgstr "" +"回傳只包含從現有群組比對到 *condition* 的例外的例外群組，或者當結果為空時回" +"傳 ``None``。" + +#: ../../library/exceptions.rst:988 +msgid "" +"The condition can be an exception type or tuple of exception types, in which " +"case each exception is checked for a match using the same check that is used " +"in an ``except`` clause. The condition can also be a callable (other than a " +"type object) that accepts an exception as its single argument and returns " +"true for the exceptions that should be in the subgroup." +msgstr "" +"條件式可以是一個例外型別或是例外型別的元組，在此情況下，每個例外都會使用與 " +"``except`` 子句中使用的相同檢查方法來檢查是否有匹配。條件式也可以是一個可呼叫" +"物件（除了型別物件之外），其接受一個例外作為單一引數，而如果該例外應該在子群" +"組中就回傳 true。" + +#: ../../library/exceptions.rst:994 +msgid "" +"The nesting structure of the current exception is preserved in the result, " +"as are the values of its :attr:`message`, :attr:`~BaseException." +"__traceback__`, :attr:`~BaseException.__cause__`, :attr:`~BaseException." +"__context__` and :attr:`~BaseException.__notes__` fields. Empty nested " +"groups are omitted from the result." +msgstr "" +"現有例外的巢狀結構會保留在結果裡，其 :attr:`message`、:attr:`~BaseException." +"__traceback__`、:attr:`~BaseException.__cause__`、:attr:`~BaseException." +"__context__` 及 :attr:`~BaseException.__notes__` 欄位的值也一樣。空的巢狀群組" +"會從結果裡排除。" + +#: ../../library/exceptions.rst:1001 +msgid "" +"The condition is checked for all exceptions in the nested exception group, " +"including the top-level and any nested exception groups. If the condition is " +"true for such an exception group, it is included in the result in full." +msgstr "" +"條件會對巢狀例外群組裡的所有例外做檢查，包括頂層及任何巢狀的例外群組。如果條" +"件對這樣的例外群組為 true，它會被完整包含在結果裡。" + +#: ../../library/exceptions.rst:1005 +msgid "``condition`` can be any callable which is not a type object." +msgstr "``condition`` 可以是任何不是型別物件的可呼叫物件。" + +#: ../../library/exceptions.rst:1010 +msgid "" +"Like :meth:`subgroup`, but returns the pair ``(match, rest)`` where " +"``match`` is ``subgroup(condition)`` and ``rest`` is the remaining non-" +"matching part." +msgstr "" +"像 :meth:`subgroup` 一樣，但回傳一對 ``(match, rest)``，其中 ``match`` 是 " +"``subgroup(condition)`` 而 ``rest`` 是剩下沒有比對到的部分。" + +#: ../../library/exceptions.rst:1016 +msgid "" +"Returns an exception group with the same :attr:`message`, but which wraps " +"the exceptions in ``excs``." +msgstr "回傳有相同 :attr:`message` 但將例外包裝在 ``excs`` 的例外群組。" + +#: ../../library/exceptions.rst:1019 +msgid "" +"This method is used by :meth:`subgroup` and :meth:`split`, which are used in " +"various contexts to break up an exception group. A subclass needs to " +"override it in order to make :meth:`subgroup` and :meth:`split` return " +"instances of the subclass rather than :exc:`ExceptionGroup`." +msgstr "" +"此方法被 :meth:`subgroup` 及 :meth:`split` 使用，被用來在各種情境下拆分例外群" +"組。子類別需要覆寫它來讓 :meth:`subgroup` 及 :meth:`split` 回傳子類別而不是 :" +"exc:`ExceptionGroup` 的實例。" + +#: ../../library/exceptions.rst:1025 +msgid "" +":meth:`subgroup` and :meth:`split` copy the :attr:`~BaseException." +"__traceback__`, :attr:`~BaseException.__cause__`, :attr:`~BaseException." +"__context__` and :attr:`~BaseException.__notes__` fields from the original " +"exception group to the one returned by :meth:`derive`, so these fields do " +"not need to be updated by :meth:`derive`." +msgstr "" +":meth:`subgroup` 及 :meth:`split` 會從原始的例外群組複製 :attr:" +"`~BaseException.__traceback__`、:attr:`~BaseException.__cause__`、:attr:" +"`~BaseException.__context__` 和 :attr:`~BaseException.__notes__` 欄位到 :" +"meth:`derive` 所回傳的例外群組上，因此這些欄位不需要被 :meth:`derive` 更新。" + +#: ../../library/exceptions.rst:1032 +msgid "" +">>> class MyGroup(ExceptionGroup):\n" +"... def derive(self, excs):\n" +"... return MyGroup(self.message, excs)\n" +"...\n" +">>> e = MyGroup(\"eg\", [ValueError(1), TypeError(2)])\n" +">>> e.add_note(\"a note\")\n" +">>> e.__context__ = Exception(\"context\")\n" +">>> e.__cause__ = Exception(\"cause\")\n" +">>> try:\n" +"... raise e\n" +"... except Exception as e:\n" +"... exc = e\n" +"...\n" +">>> match, rest = exc.split(ValueError)\n" +">>> exc, exc.__context__, exc.__cause__, exc.__notes__\n" +"(MyGroup('eg', [ValueError(1), TypeError(2)]), Exception('context'), " +"Exception('cause'), ['a note'])\n" +">>> match, match.__context__, match.__cause__, match.__notes__\n" +"(MyGroup('eg', [ValueError(1)]), Exception('context'), Exception('cause'), " +"['a note'])\n" +">>> rest, rest.__context__, rest.__cause__, rest.__notes__\n" +"(MyGroup('eg', [TypeError(2)]), Exception('context'), Exception('cause'), " +"['a note'])\n" +">>> exc.__traceback__ is match.__traceback__ is rest.__traceback__\n" +"True" +msgstr "" +">>> class MyGroup(ExceptionGroup):\n" +"... def derive(self, excs):\n" +"... return MyGroup(self.message, excs)\n" +"...\n" +">>> e = MyGroup(\"eg\", [ValueError(1), TypeError(2)])\n" +">>> e.add_note(\"a note\")\n" +">>> e.__context__ = Exception(\"context\")\n" +">>> e.__cause__ = Exception(\"cause\")\n" +">>> try:\n" +"... raise e\n" +"... except Exception as e:\n" +"... exc = e\n" +"...\n" +">>> match, rest = exc.split(ValueError)\n" +">>> exc, exc.__context__, exc.__cause__, exc.__notes__\n" +"(MyGroup('eg', [ValueError(1), TypeError(2)]), Exception('context'), " +"Exception('cause'), ['a note'])\n" +">>> match, match.__context__, match.__cause__, match.__notes__\n" +"(MyGroup('eg', [ValueError(1)]), Exception('context'), Exception('cause'), " +"['a note'])\n" +">>> rest, rest.__context__, rest.__cause__, rest.__notes__\n" +"(MyGroup('eg', [TypeError(2)]), Exception('context'), Exception('cause'), " +"['a note'])\n" +">>> exc.__traceback__ is match.__traceback__ is rest.__traceback__\n" +"True" + +#: ../../library/exceptions.rst:1058 +msgid "" +"Note that :exc:`BaseExceptionGroup` defines :meth:`~object.__new__`, so " +"subclasses that need a different constructor signature need to override that " +"rather than :meth:`~object.__init__`. For example, the following defines an " +"exception group subclass which accepts an exit_code and constructs the " +"group's message from it. ::" +msgstr "" +"需注意 :exc:`BaseExceptionGroup` 定義了 :meth:`~object.__new__`，因此需要不同" +"建構函式簽名的子類別需要覆寫它而不是 :meth:`~object.__init__`。例如下面定義了" +"一個例外群組子類別接受 exit_code 並從中建構群組的訊息。： ::" + +#: ../../library/exceptions.rst:1064 +msgid "" +"class Errors(ExceptionGroup):\n" +" def __new__(cls, errors, exit_code):\n" +" self = super().__new__(Errors, f\"exit code: {exit_code}\", errors)\n" +" self.exit_code = exit_code\n" +" return self\n" +"\n" +" def derive(self, excs):\n" +" return Errors(excs, self.exit_code)" +msgstr "" +"class Errors(ExceptionGroup):\n" +" def __new__(cls, errors, exit_code):\n" +" self = super().__new__(Errors, f\"exit code: {exit_code}\", errors)\n" +" self.exit_code = exit_code\n" +" return self\n" +"\n" +" def derive(self, excs):\n" +" return Errors(excs, self.exit_code)" + +#: ../../library/exceptions.rst:1073 +msgid "" +"Like :exc:`ExceptionGroup`, any subclass of :exc:`BaseExceptionGroup` which " +"is also a subclass of :exc:`Exception` can only wrap instances of :exc:" +"`Exception`." +msgstr "" +"像 :exc:`ExceptionGroup` 一樣，任何 :exc:`BaseExceptionGroup` 的子類別且也" +"是 :exc:`Exception` 的子類別只能包裝 :exc:`Exception` 的實例。" + +#: ../../library/exceptions.rst:1081 +msgid "Exception hierarchy" +msgstr "例外階層" + +#: ../../library/exceptions.rst:1083 +msgid "The class hierarchy for built-in exceptions is:" +msgstr "內建例外的類別階層如下：" + +#: ../../library/exceptions.rst:1085 +msgid "" +"BaseException\n" +" ├── BaseExceptionGroup\n" +" ├── GeneratorExit\n" +" ├── KeyboardInterrupt\n" +" ├── SystemExit\n" +" └── Exception\n" +" ├── ArithmeticError\n" +" │ ├── FloatingPointError\n" +" │ ├── OverflowError\n" +" │ └── ZeroDivisionError\n" +" ├── AssertionError\n" +" ├── AttributeError\n" +" ├── BufferError\n" +" ├── EOFError\n" +" ├── ExceptionGroup [BaseExceptionGroup]\n" +" ├── ImportError\n" +" │ └── ModuleNotFoundError\n" +" ├── LookupError\n" +" │ ├── IndexError\n" +" │ └── KeyError\n" +" ├── MemoryError\n" +" ├── NameError\n" +" │ └── UnboundLocalError\n" +" ├── OSError\n" +" │ ├── BlockingIOError\n" +" │ ├── ChildProcessError\n" +" │ ├── ConnectionError\n" +" │ │ ├── BrokenPipeError\n" +" │ │ ├── ConnectionAbortedError\n" +" │ │ ├── ConnectionRefusedError\n" +" │ │ └── ConnectionResetError\n" +" │ ├── FileExistsError\n" +" │ ├── FileNotFoundError\n" +" │ ├── InterruptedError\n" +" │ ├── IsADirectoryError\n" +" │ ├── NotADirectoryError\n" +" │ ├── PermissionError\n" +" │ ├── ProcessLookupError\n" +" │ └── TimeoutError\n" +" ├── ReferenceError\n" +" ├── RuntimeError\n" +" │ ├── NotImplementedError\n" +" │ ├── PythonFinalizationError\n" +" │ └── RecursionError\n" +" ├── StopAsyncIteration\n" +" ├── StopIteration\n" +" ├── SyntaxError\n" +" │ └── IndentationError\n" +" │ └── TabError\n" +" ├── SystemError\n" +" ├── TypeError\n" +" ├── ValueError\n" +" │ └── UnicodeError\n" +" │ ├── UnicodeDecodeError\n" +" │ ├── UnicodeEncodeError\n" +" │ └── UnicodeTranslateError\n" +" └── Warning\n" +" ├── BytesWarning\n" +" ├── DeprecationWarning\n" +" ├── EncodingWarning\n" +" ├── FutureWarning\n" +" ├── ImportWarning\n" +" ├── PendingDeprecationWarning\n" +" ├── ResourceWarning\n" +" ├── RuntimeWarning\n" +" ├── SyntaxWarning\n" +" ├── UnicodeWarning\n" +" └── UserWarning\n" +msgstr "" +"BaseException\n" +" ├── BaseExceptionGroup\n" +" ├── GeneratorExit\n" +" ├── KeyboardInterrupt\n" +" ├── SystemExit\n" +" └── Exception\n" +" ├── ArithmeticError\n" +" │ ├── FloatingPointError\n" +" │ ├── OverflowError\n" +" │ └── ZeroDivisionError\n" +" ├── AssertionError\n" +" ├── AttributeError\n" +" ├── BufferError\n" +" ├── EOFError\n" +" ├── ExceptionGroup [BaseExceptionGroup]\n" +" ├── ImportError\n" +" │ └── ModuleNotFoundError\n" +" ├── LookupError\n" +" │ ├── IndexError\n" +" │ └── KeyError\n" +" ├── MemoryError\n" +" ├── NameError\n" +" │ └── UnboundLocalError\n" +" ├── OSError\n" +" │ ├── BlockingIOError\n" +" │ ├── ChildProcessError\n" +" │ ├── ConnectionError\n" +" │ │ ├── BrokenPipeError\n" +" │ │ ├── ConnectionAbortedError\n" +" │ │ ├── ConnectionRefusedError\n" +" │ │ └── ConnectionResetError\n" +" │ ├── FileExistsError\n" +" │ ├── FileNotFoundError\n" +" │ ├── InterruptedError\n" +" │ ├── IsADirectoryError\n" +" │ ├── NotADirectoryError\n" +" │ ├── PermissionError\n" +" │ ├── ProcessLookupError\n" +" │ └── TimeoutError\n" +" ├── ReferenceError\n" +" ├── RuntimeError\n" +" │ ├── NotImplementedError\n" +" │ ├── PythonFinalizationError\n" +" │ └── RecursionError\n" +" ├── StopAsyncIteration\n" +" ├── StopIteration\n" +" ├── SyntaxError\n" +" │ └── IndentationError\n" +" │ └── TabError\n" +" ├── SystemError\n" +" ├── TypeError\n" +" ├── ValueError\n" +" │ └── UnicodeError\n" +" │ ├── UnicodeDecodeError\n" +" │ ├── UnicodeEncodeError\n" +" │ └── UnicodeTranslateError\n" +" └── Warning\n" +" ├── BytesWarning\n" +" ├── DeprecationWarning\n" +" ├── EncodingWarning\n" +" ├── FutureWarning\n" +" ├── ImportWarning\n" +" ├── PendingDeprecationWarning\n" +" ├── ResourceWarning\n" +" ├── RuntimeWarning\n" +" ├── SyntaxWarning\n" +" ├── UnicodeWarning\n" +" └── UserWarning\n" + +#: ../../library/exceptions.rst:6 ../../library/exceptions.rst:17 +#: ../../library/exceptions.rst:196 +msgid "statement" +msgstr "statement（陳述式）" + +#: ../../library/exceptions.rst:6 +msgid "try" +msgstr "try" + +#: ../../library/exceptions.rst:6 +msgid "except" +msgstr "except" + +#: ../../library/exceptions.rst:17 +msgid "raise" +msgstr "raise" + +#: ../../library/exceptions.rst:41 +msgid "exception" +msgstr "exception（例外）" + +#: ../../library/exceptions.rst:41 +msgid "chaining" +msgstr "chaining" + +#: ../../library/exceptions.rst:41 +msgid "__cause__ (exception attribute)" +msgstr "__cause__（例外屬性）" + +#: ../../library/exceptions.rst:41 +msgid "__context__ (exception attribute)" +msgstr "__context__（例外屬性）" + +#: ../../library/exceptions.rst:41 +msgid "__suppress_context__ (exception attribute)" +msgstr "__suppress_context__（例外屬性）" + +#: ../../library/exceptions.rst:196 +msgid "assert" +msgstr "assert" + +#: ../../library/exceptions.rst:355 +msgid "module" +msgstr "module（模組）" + +#: ../../library/exceptions.rst:355 +msgid "errno" +msgstr "errno" + +#~ msgid "" +#~ "The :attr:`name` and :attr:`obj` attributes can be set using keyword-only " +#~ "arguments to the constructor. When set they represent the name of the " +#~ "attribute that was attempted to be accessed and the object that was " +#~ "accessed for said attribute, respectively." +#~ msgstr "" +#~ ":attr:`name` 和 :attr:`obj` 屬性可以使用建構函式的僅限關鍵字 (keyword-" +#~ "only) 引數來設定。當被設定的時候，它們分別代表被嘗試存取的屬性名稱以及被以" +#~ "該屬性存取的物件。" + +#~ msgid "" +#~ "The :attr:`name` attribute can be set using a keyword-only argument to " +#~ "the constructor. When set it represent the name of the variable that was " +#~ "attempted to be accessed." +#~ msgstr "" +#~ ":attr:`name` 屬性可以使用僅限關鍵字引數來設定到建構函式。當被設定的時候它" +#~ "代表被嘗試存取的變數名稱。" diff --git a/library/faulthandler.po b/library/faulthandler.po index 6a951db496..a79026f1f9 100644 --- a/library/faulthandler.po +++ b/library/faulthandler.po @@ -1,403 +1,403 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: 2018-05-23 16:01+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/faulthandler.rst:2 -msgid ":mod:`!faulthandler` --- Dump the Python traceback" -msgstr ":mod:`!faulthandler` --- 傾印 Python 回溯" - -#: ../../library/faulthandler.rst:11 -msgid "" -"This module contains functions to dump Python tracebacks explicitly, on a " -"fault, after a timeout, or on a user signal. " -"Call :func:`faulthandler.enable` to install fault handlers for " -"the :const:`~signal.SIGSEGV`, :const:`~signal.SIGFPE`, :const:`~signal.SIGABRT`, :const:`~signal.SIGBUS`, " -"and :const:`~signal.SIGILL` signals. You can also enable them at startup by " -"setting the :envvar:`PYTHONFAULTHANDLER` environment variable or by using " -"the :option:`-X` ``faulthandler`` command line option." -msgstr "" - -#: ../../library/faulthandler.rst:19 -msgid "" -"The fault handler is compatible with system fault handlers like Apport or " -"the Windows fault handler. The module uses an alternative stack for signal " -"handlers if the :c:func:`!sigaltstack` function is available. This allows it " -"to dump the traceback even on a stack overflow." -msgstr "" - -#: ../../library/faulthandler.rst:24 -msgid "" -"The fault handler is called on catastrophic cases and therefore can only use " -"signal-safe functions (e.g. it cannot allocate memory on the heap). Because " -"of this limitation traceback dumping is minimal compared to normal Python " -"tracebacks:" -msgstr "" - -#: ../../library/faulthandler.rst:29 -msgid "" -"Only ASCII is supported. The ``backslashreplace`` error handler is used on " -"encoding." -msgstr "" - -#: ../../library/faulthandler.rst:31 -msgid "Each string is limited to 500 characters." -msgstr "每個字串限制為 500 個字元。" - -#: ../../library/faulthandler.rst:32 -msgid "" -"Only the filename, the function name and the line number are displayed. (no " -"source code)" -msgstr "" - -#: ../../library/faulthandler.rst:34 -msgid "It is limited to 100 frames and 100 threads." -msgstr "" - -#: ../../library/faulthandler.rst:35 -msgid "The order is reversed: the most recent call is shown first." -msgstr "" - -#: ../../library/faulthandler.rst:37 -msgid "" -"By default, the Python traceback is written to :data:`sys.stderr`. To see " -"tracebacks, applications must be run in the terminal. A log file can " -"alternatively be passed to :func:`faulthandler.enable`." -msgstr "" - -#: ../../library/faulthandler.rst:41 -msgid "" -"The module is implemented in C, so tracebacks can be dumped on a crash or " -"when Python is deadlocked." -msgstr "" - -#: ../../library/faulthandler.rst:44 -msgid "" -"The :ref:`Python Development Mode ` " -"calls :func:`faulthandler.enable` at Python startup." -msgstr "" - -#: ../../library/faulthandler.rst:49 -msgid "Module :mod:`pdb`" -msgstr ":mod:`pdb` 模組" - -#: ../../library/faulthandler.rst:50 -msgid "Interactive source code debugger for Python programs." -msgstr "" - -#: ../../library/faulthandler.rst:52 -msgid "Module :mod:`traceback`" -msgstr ":mod:`traceback` 模組" - -#: ../../library/faulthandler.rst:53 -msgid "" -"Standard interface to extract, format and print stack traces of Python " -"programs." -msgstr "" - -#: ../../library/faulthandler.rst:56 -msgid "Dumping the traceback" -msgstr "" - -#: ../../library/faulthandler.rst:60 -msgid "" -"Dump the tracebacks of all threads into *file*. If *all_threads* is " -"``False``, dump only the current thread." -msgstr "" - -#: ../../library/faulthandler.rst:63 -msgid "" -":func:`traceback.print_tb`, which can be used to print a traceback object." -msgstr "" - -#: ../../library/faulthandler.rst:65 ../../library/faulthandler.rst:119 -#: ../../library/faulthandler.rst:165 ../../library/faulthandler.rst:190 -msgid "Added support for passing file descriptor to this function." -msgstr "新增傳遞檔案描述器給此函式的支援。" - -#: ../../library/faulthandler.rst:70 -msgid "Dumping the C stack" -msgstr "" - -#: ../../library/faulthandler.rst:76 -msgid "Dump the C stack trace of the current thread into *file*." -msgstr "" - -#: ../../library/faulthandler.rst:78 -msgid "" -"If the Python build does not support it or the operating system does not " -"provide a stack trace, then this prints an error in place of a dumped C " -"stack." -msgstr "" - -#: ../../library/faulthandler.rst:85 -msgid "C Stack Compatibility" -msgstr "" - -#: ../../library/faulthandler.rst:87 -msgid "" -"If the system does not support the C-level :manpage:`backtrace(3)` " -"or :manpage:`dladdr1(3)`, then C stack dumps will not work. An error will be " -"printed instead of the stack." -msgstr "" - -#: ../../library/faulthandler.rst:91 -msgid "" -"Additionally, some compilers do not support :term:`CPython's ` " -"implementation of C stack dumps. As a result, a different error may be " -"printed instead of the stack, even if the operating system supports dumping " -"stacks." -msgstr "" - -#: ../../library/faulthandler.rst:97 -msgid "" -"Dumping C stacks can be arbitrarily slow, depending on the DWARF level of " -"the binaries in the call stack." -msgstr "" - -#: ../../library/faulthandler.rst:101 -msgid "Fault handler state" -msgstr "" - -#: ../../library/faulthandler.rst:105 -msgid "" -"Enable the fault handler: install handlers for " -"the :const:`~signal.SIGSEGV`, :const:`~signal.SIGFPE`, :const:`~signal.SIGABRT`, :const:`~signal.SIGBUS` " -"and :const:`~signal.SIGILL` signals to dump the Python traceback. If " -"*all_threads* is ``True``, produce tracebacks for every running thread. " -"Otherwise, dump only the current thread." -msgstr "" - -#: ../../library/faulthandler.rst:112 -msgid "" -"The *file* must be kept open until the fault handler is disabled: " -"see :ref:`issue with file descriptors `." -msgstr "" - -#: ../../library/faulthandler.rst:115 -msgid "" -"If *c_stack* is ``True``, then the C stack trace is printed after the Python " -"traceback, unless the system does not support it. See :func:`dump_c_stack` " -"for more information on compatibility." -msgstr "" - -#: ../../library/faulthandler.rst:122 -msgid "On Windows, a handler for Windows exception is also installed." -msgstr "" - -#: ../../library/faulthandler.rst:125 -msgid "" -"The dump now mentions if a garbage collector collection is running if " -"*all_threads* is true." -msgstr "" - -#: ../../library/faulthandler.rst:129 -msgid "" -"Only the current thread is dumped if the :term:`GIL` is disabled to prevent " -"the risk of data races." -msgstr "" - -#: ../../library/faulthandler.rst:133 -msgid "The dump now displays the C stack trace if *c_stack* is true." -msgstr "" - -#: ../../library/faulthandler.rst:138 -msgid "" -"Disable the fault handler: uninstall the signal handlers installed " -"by :func:`enable`." -msgstr "" - -#: ../../library/faulthandler.rst:143 -msgid "Check if the fault handler is enabled." -msgstr "" - -#: ../../library/faulthandler.rst:147 -msgid "Dumping the tracebacks after a timeout" -msgstr "" - -#: ../../library/faulthandler.rst:151 -msgid "" -"Dump the tracebacks of all threads, after a timeout of *timeout* seconds, or " -"every *timeout* seconds if *repeat* is ``True``. If *exit* is ``True``, " -"call :c:func:`!_exit` with status=1 after dumping the tracebacks. " -"(Note :c:func:`!_exit` exits the process immediately, which means it doesn't " -"do any cleanup like flushing file buffers.) If the function is called twice, " -"the new call replaces previous parameters and resets the timeout. The timer " -"has a sub-second resolution." -msgstr "" - -#: ../../library/faulthandler.rst:159 -msgid "" -"The *file* must be kept open until the traceback is dumped " -"or :func:`cancel_dump_traceback_later` is called: see :ref:`issue with file " -"descriptors `." -msgstr "" - -#: ../../library/faulthandler.rst:163 -msgid "This function is implemented using a watchdog thread." -msgstr "" - -#: ../../library/faulthandler.rst:168 -msgid "This function is now always available." -msgstr "" - -#: ../../library/faulthandler.rst:173 -msgid "Cancel the last call to :func:`dump_traceback_later`." -msgstr "" - -#: ../../library/faulthandler.rst:177 -msgid "Dumping the traceback on a user signal" -msgstr "" - -#: ../../library/faulthandler.rst:181 -msgid "" -"Register a user signal: install a handler for the *signum* signal to dump " -"the traceback of all threads, or of the current thread if *all_threads* is " -"``False``, into *file*. Call the previous handler if chain is ``True``." -msgstr "" - -#: ../../library/faulthandler.rst:185 -msgid "" -"The *file* must be kept open until the signal is unregistered " -"by :func:`unregister`: see :ref:`issue with file descriptors `." -msgstr "" - -#: ../../library/faulthandler.rst:188 ../../library/faulthandler.rst:199 -msgid "Not available on Windows." -msgstr "" - -#: ../../library/faulthandler.rst:195 -msgid "" -"Unregister a user signal: uninstall the handler of the *signum* signal " -"installed by :func:`register`. Return ``True`` if the signal was registered, " -"``False`` otherwise." -msgstr "" - -#: ../../library/faulthandler.rst:205 -msgid "Issue with file descriptors" -msgstr "" - -#: ../../library/faulthandler.rst:207 -msgid "" -":func:`enable`, :func:`dump_traceback_later` and :func:`register` keep the " -"file descriptor of their *file* argument. If the file is closed and its file " -"descriptor is reused by a new file, or if :func:`os.dup2` is used to replace " -"the file descriptor, the traceback will be written into a different file. " -"Call these functions again each time that the file is replaced." -msgstr "" - -#: ../../library/faulthandler.rst:215 -msgid "Example" -msgstr "範例" - -#: ../../library/faulthandler.rst:217 -msgid "" -"Example of a segmentation fault on Linux with and without enabling the fault " -"handler:" -msgstr "" - -#: ../../library/faulthandler.rst:220 -msgid "" -"$ python -c \"import ctypes; ctypes.string_at(0)\"\n" -"Segmentation fault\n" -"\n" -"$ python -q -X faulthandler\n" -">>> import ctypes\n" -">>> ctypes.string_at(0)\n" -"Fatal Python error: Segmentation fault\n" -"\n" -"Current thread 0x00007fb899f39700 (most recent call first):\n" -" File \"/opt/python/Lib/ctypes/__init__.py\", line 486 in string_at\n" -" File \"\", line 1 in \n" -"\n" -"Current thread's C stack trace (most recent call first):\n" -" Binary file \"/opt/python/python\", at _Py_DumpStack+0x42 " -"[0x5b27f7d7147e]\n" -" Binary file \"/opt/python/python\", at +0x32dcbd [0x5b27f7d85cbd]\n" -" Binary file \"/opt/python/python\", at +0x32df8a [0x5b27f7d85f8a]\n" -" Binary file \"/usr/lib/libc.so.6\", at +0x3def0 [0x77b73226bef0]\n" -" Binary file \"/usr/lib/libc.so.6\", at +0x17ef9c [0x77b7323acf9c]\n" -" Binary file \"/opt/python/build/lib.linux-x86_64-3.14/_ctypes.cpython-314d-" -"x86_64-linux-gnu.so\", at +0xcdf6 [0x77b7315dddf6]\n" -" Binary file \"/usr/lib/libffi.so.8\", at +0x7976 [0x77b73158f976]\n" -" Binary file \"/usr/lib/libffi.so.8\", at +0x413c [0x77b73158c13c]\n" -" Binary file \"/usr/lib/libffi.so.8\", at ffi_call+0x12e [0x77b73158ef0e]\n" -" Binary file \"/opt/python/build/lib.linux-x86_64-3.14/_ctypes.cpython-314d-" -"x86_64-linux-gnu.so\", at +0x15a33 [0x77b7315e6a33]\n" -" Binary file \"/opt/python/build/lib.linux-x86_64-3.14/_ctypes.cpython-314d-" -"x86_64-linux-gnu.so\", at +0x164fa [0x77b7315e74fa]\n" -" Binary file \"/opt/python/build/lib.linux-x86_64-3.14/_ctypes.cpython-314d-" -"x86_64-linux-gnu.so\", at +0xc624 [0x77b7315dd624]\n" -" Binary file \"/opt/python/python\", at _PyObject_MakeTpCall+0xce " -"[0x5b27f7b73883]\n" -" Binary file \"/opt/python/python\", at +0x11bab6 [0x5b27f7b73ab6]\n" -" Binary file \"/opt/python/python\", at PyObject_Vectorcall+0x23 " -"[0x5b27f7b73b04]\n" -" Binary file \"/opt/python/python\", at _PyEval_EvalFrameDefault+0x490c " -"[0x5b27f7cbb302]\n" -" Binary file \"/opt/python/python\", at +0x2818e6 [0x5b27f7cd98e6]\n" -" Binary file \"/opt/python/python\", at +0x281aab [0x5b27f7cd9aab]\n" -" Binary file \"/opt/python/python\", at PyEval_EvalCode+0xc5 " -"[0x5b27f7cd9ba3]\n" -" Binary file \"/opt/python/python\", at +0x255957 [0x5b27f7cad957]\n" -" Binary file \"/opt/python/python\", at +0x255ab4 [0x5b27f7cadab4]\n" -" Binary file \"/opt/python/python\", at _PyEval_EvalFrameDefault+0x6c3e " -"[0x5b27f7cbd634]\n" -" Binary file \"/opt/python/python\", at +0x2818e6 [0x5b27f7cd98e6]\n" -" Binary file \"/opt/python/python\", at +0x281aab [0x5b27f7cd9aab]\n" -" Binary file \"/opt/python/python\", at +0x11b6e1 [0x5b27f7b736e1]\n" -" Binary file \"/opt/python/python\", at +0x11d348 [0x5b27f7b75348]\n" -" Binary file \"/opt/python/python\", at +0x11d626 [0x5b27f7b75626]\n" -" Binary file \"/opt/python/python\", at PyObject_Call+0x20 " -"[0x5b27f7b7565e]\n" -" Binary file \"/opt/python/python\", at +0x32a67a [0x5b27f7d8267a]\n" -" Binary file \"/opt/python/python\", at +0x32a7f8 [0x5b27f7d827f8]\n" -" Binary file \"/opt/python/python\", at +0x32ac1b [0x5b27f7d82c1b]\n" -" Binary file \"/opt/python/python\", at Py_RunMain+0x31 [0x5b27f7d82ebe]\n" -" \n" -"Segmentation fault" -msgstr "" - -#~ msgid "" -#~ "$ python -c \"import ctypes; ctypes.string_at(0)\"\n" -#~ "Segmentation fault\n" -#~ "\n" -#~ "$ python -q -X faulthandler\n" -#~ ">>> import ctypes\n" -#~ ">>> ctypes.string_at(0)\n" -#~ "Fatal Python error: Segmentation fault\n" -#~ "\n" -#~ "Current thread 0x00007fb899f39700 (most recent call first):\n" -#~ " File \"/home/python/cpython/Lib/ctypes/__init__.py\", line 486 in " -#~ "string_at\n" -#~ " File \"\", line 1 in \n" -#~ "Segmentation fault" -#~ msgstr "" -#~ "$ python -c \"import ctypes; ctypes.string_at(0)\"\n" -#~ "Segmentation fault\n" -#~ "\n" -#~ "$ python -q -X faulthandler\n" -#~ ">>> import ctypes\n" -#~ ">>> ctypes.string_at(0)\n" -#~ "Fatal Python error: Segmentation fault\n" -#~ "\n" -#~ "Current thread 0x00007fb899f39700 (most recent call first):\n" -#~ " File \"/home/python/cpython/Lib/ctypes/__init__.py\", line 486 in " -#~ "string_at\n" -#~ " File \"\", line 1 in \n" -#~ "Segmentation fault" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: 2018-05-23 16:01+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/faulthandler.rst:2 +msgid ":mod:`!faulthandler` --- Dump the Python traceback" +msgstr ":mod:`!faulthandler` --- 傾印 Python 回溯" + +#: ../../library/faulthandler.rst:11 +msgid "" +"This module contains functions to dump Python tracebacks explicitly, on a " +"fault, after a timeout, or on a user signal. " +"Call :func:`faulthandler.enable` to install fault handlers for " +"the :const:`~signal.SIGSEGV`, :const:`~signal.SIGFPE`, :const:`~signal.SIGABRT`, :const:`~signal.SIGBUS`, " +"and :const:`~signal.SIGILL` signals. You can also enable them at startup by " +"setting the :envvar:`PYTHONFAULTHANDLER` environment variable or by using " +"the :option:`-X` ``faulthandler`` command line option." +msgstr "" + +#: ../../library/faulthandler.rst:19 +msgid "" +"The fault handler is compatible with system fault handlers like Apport or " +"the Windows fault handler. The module uses an alternative stack for signal " +"handlers if the :c:func:`!sigaltstack` function is available. This allows it " +"to dump the traceback even on a stack overflow." +msgstr "" + +#: ../../library/faulthandler.rst:24 +msgid "" +"The fault handler is called on catastrophic cases and therefore can only use " +"signal-safe functions (e.g. it cannot allocate memory on the heap). Because " +"of this limitation traceback dumping is minimal compared to normal Python " +"tracebacks:" +msgstr "" + +#: ../../library/faulthandler.rst:29 +msgid "" +"Only ASCII is supported. The ``backslashreplace`` error handler is used on " +"encoding." +msgstr "" + +#: ../../library/faulthandler.rst:31 +msgid "Each string is limited to 500 characters." +msgstr "每個字串限制為 500 個字元。" + +#: ../../library/faulthandler.rst:32 +msgid "" +"Only the filename, the function name and the line number are displayed. (no " +"source code)" +msgstr "" + +#: ../../library/faulthandler.rst:34 +msgid "It is limited to 100 frames and 100 threads." +msgstr "" + +#: ../../library/faulthandler.rst:35 +msgid "The order is reversed: the most recent call is shown first." +msgstr "" + +#: ../../library/faulthandler.rst:37 +msgid "" +"By default, the Python traceback is written to :data:`sys.stderr`. To see " +"tracebacks, applications must be run in the terminal. A log file can " +"alternatively be passed to :func:`faulthandler.enable`." +msgstr "" + +#: ../../library/faulthandler.rst:41 +msgid "" +"The module is implemented in C, so tracebacks can be dumped on a crash or " +"when Python is deadlocked." +msgstr "" + +#: ../../library/faulthandler.rst:44 +msgid "" +"The :ref:`Python Development Mode ` " +"calls :func:`faulthandler.enable` at Python startup." +msgstr "" + +#: ../../library/faulthandler.rst:49 +msgid "Module :mod:`pdb`" +msgstr ":mod:`pdb` 模組" + +#: ../../library/faulthandler.rst:50 +msgid "Interactive source code debugger for Python programs." +msgstr "" + +#: ../../library/faulthandler.rst:52 +msgid "Module :mod:`traceback`" +msgstr ":mod:`traceback` 模組" + +#: ../../library/faulthandler.rst:53 +msgid "" +"Standard interface to extract, format and print stack traces of Python " +"programs." +msgstr "" + +#: ../../library/faulthandler.rst:56 +msgid "Dumping the traceback" +msgstr "" + +#: ../../library/faulthandler.rst:60 +msgid "" +"Dump the tracebacks of all threads into *file*. If *all_threads* is " +"``False``, dump only the current thread." +msgstr "" + +#: ../../library/faulthandler.rst:63 +msgid "" +":func:`traceback.print_tb`, which can be used to print a traceback object." +msgstr "" + +#: ../../library/faulthandler.rst:65 ../../library/faulthandler.rst:119 +#: ../../library/faulthandler.rst:165 ../../library/faulthandler.rst:190 +msgid "Added support for passing file descriptor to this function." +msgstr "新增傳遞檔案描述器給此函式的支援。" + +#: ../../library/faulthandler.rst:70 +msgid "Dumping the C stack" +msgstr "" + +#: ../../library/faulthandler.rst:76 +msgid "Dump the C stack trace of the current thread into *file*." +msgstr "" + +#: ../../library/faulthandler.rst:78 +msgid "" +"If the Python build does not support it or the operating system does not " +"provide a stack trace, then this prints an error in place of a dumped C " +"stack." +msgstr "" + +#: ../../library/faulthandler.rst:85 +msgid "C Stack Compatibility" +msgstr "" + +#: ../../library/faulthandler.rst:87 +msgid "" +"If the system does not support the C-level :manpage:`backtrace(3)` " +"or :manpage:`dladdr1(3)`, then C stack dumps will not work. An error will be " +"printed instead of the stack." +msgstr "" + +#: ../../library/faulthandler.rst:91 +msgid "" +"Additionally, some compilers do not support :term:`CPython's ` " +"implementation of C stack dumps. As a result, a different error may be " +"printed instead of the stack, even if the operating system supports dumping " +"stacks." +msgstr "" + +#: ../../library/faulthandler.rst:97 +msgid "" +"Dumping C stacks can be arbitrarily slow, depending on the DWARF level of " +"the binaries in the call stack." +msgstr "" + +#: ../../library/faulthandler.rst:101 +msgid "Fault handler state" +msgstr "" + +#: ../../library/faulthandler.rst:105 +msgid "" +"Enable the fault handler: install handlers for " +"the :const:`~signal.SIGSEGV`, :const:`~signal.SIGFPE`, :const:`~signal.SIGABRT`, :const:`~signal.SIGBUS` " +"and :const:`~signal.SIGILL` signals to dump the Python traceback. If " +"*all_threads* is ``True``, produce tracebacks for every running thread. " +"Otherwise, dump only the current thread." +msgstr "" + +#: ../../library/faulthandler.rst:112 +msgid "" +"The *file* must be kept open until the fault handler is disabled: " +"see :ref:`issue with file descriptors `." +msgstr "" + +#: ../../library/faulthandler.rst:115 +msgid "" +"If *c_stack* is ``True``, then the C stack trace is printed after the Python " +"traceback, unless the system does not support it. See :func:`dump_c_stack` " +"for more information on compatibility." +msgstr "" + +#: ../../library/faulthandler.rst:122 +msgid "On Windows, a handler for Windows exception is also installed." +msgstr "" + +#: ../../library/faulthandler.rst:125 +msgid "" +"The dump now mentions if a garbage collector collection is running if " +"*all_threads* is true." +msgstr "" + +#: ../../library/faulthandler.rst:129 +msgid "" +"Only the current thread is dumped if the :term:`GIL` is disabled to prevent " +"the risk of data races." +msgstr "" + +#: ../../library/faulthandler.rst:133 +msgid "The dump now displays the C stack trace if *c_stack* is true." +msgstr "" + +#: ../../library/faulthandler.rst:138 +msgid "" +"Disable the fault handler: uninstall the signal handlers installed " +"by :func:`enable`." +msgstr "" + +#: ../../library/faulthandler.rst:143 +msgid "Check if the fault handler is enabled." +msgstr "" + +#: ../../library/faulthandler.rst:147 +msgid "Dumping the tracebacks after a timeout" +msgstr "" + +#: ../../library/faulthandler.rst:151 +msgid "" +"Dump the tracebacks of all threads, after a timeout of *timeout* seconds, or " +"every *timeout* seconds if *repeat* is ``True``. If *exit* is ``True``, " +"call :c:func:`!_exit` with status=1 after dumping the tracebacks. " +"(Note :c:func:`!_exit` exits the process immediately, which means it doesn't " +"do any cleanup like flushing file buffers.) If the function is called twice, " +"the new call replaces previous parameters and resets the timeout. The timer " +"has a sub-second resolution." +msgstr "" + +#: ../../library/faulthandler.rst:159 +msgid "" +"The *file* must be kept open until the traceback is dumped " +"or :func:`cancel_dump_traceback_later` is called: see :ref:`issue with file " +"descriptors `." +msgstr "" + +#: ../../library/faulthandler.rst:163 +msgid "This function is implemented using a watchdog thread." +msgstr "" + +#: ../../library/faulthandler.rst:168 +msgid "This function is now always available." +msgstr "" + +#: ../../library/faulthandler.rst:173 +msgid "Cancel the last call to :func:`dump_traceback_later`." +msgstr "" + +#: ../../library/faulthandler.rst:177 +msgid "Dumping the traceback on a user signal" +msgstr "" + +#: ../../library/faulthandler.rst:181 +msgid "" +"Register a user signal: install a handler for the *signum* signal to dump " +"the traceback of all threads, or of the current thread if *all_threads* is " +"``False``, into *file*. Call the previous handler if chain is ``True``." +msgstr "" + +#: ../../library/faulthandler.rst:185 +msgid "" +"The *file* must be kept open until the signal is unregistered " +"by :func:`unregister`: see :ref:`issue with file descriptors `." +msgstr "" + +#: ../../library/faulthandler.rst:188 ../../library/faulthandler.rst:199 +msgid "Not available on Windows." +msgstr "" + +#: ../../library/faulthandler.rst:195 +msgid "" +"Unregister a user signal: uninstall the handler of the *signum* signal " +"installed by :func:`register`. Return ``True`` if the signal was registered, " +"``False`` otherwise." +msgstr "" + +#: ../../library/faulthandler.rst:205 +msgid "Issue with file descriptors" +msgstr "" + +#: ../../library/faulthandler.rst:207 +msgid "" +":func:`enable`, :func:`dump_traceback_later` and :func:`register` keep the " +"file descriptor of their *file* argument. If the file is closed and its file " +"descriptor is reused by a new file, or if :func:`os.dup2` is used to replace " +"the file descriptor, the traceback will be written into a different file. " +"Call these functions again each time that the file is replaced." +msgstr "" + +#: ../../library/faulthandler.rst:215 +msgid "Example" +msgstr "範例" + +#: ../../library/faulthandler.rst:217 +msgid "" +"Example of a segmentation fault on Linux with and without enabling the fault " +"handler:" +msgstr "" + +#: ../../library/faulthandler.rst:220 +msgid "" +"$ python -c \"import ctypes; ctypes.string_at(0)\"\n" +"Segmentation fault\n" +"\n" +"$ python -q -X faulthandler\n" +">>> import ctypes\n" +">>> ctypes.string_at(0)\n" +"Fatal Python error: Segmentation fault\n" +"\n" +"Current thread 0x00007fb899f39700 (most recent call first):\n" +" File \"/opt/python/Lib/ctypes/__init__.py\", line 486 in string_at\n" +" File \"\", line 1 in \n" +"\n" +"Current thread's C stack trace (most recent call first):\n" +" Binary file \"/opt/python/python\", at _Py_DumpStack+0x42 " +"[0x5b27f7d7147e]\n" +" Binary file \"/opt/python/python\", at +0x32dcbd [0x5b27f7d85cbd]\n" +" Binary file \"/opt/python/python\", at +0x32df8a [0x5b27f7d85f8a]\n" +" Binary file \"/usr/lib/libc.so.6\", at +0x3def0 [0x77b73226bef0]\n" +" Binary file \"/usr/lib/libc.so.6\", at +0x17ef9c [0x77b7323acf9c]\n" +" Binary file \"/opt/python/build/lib.linux-x86_64-3.14/_ctypes.cpython-314d-" +"x86_64-linux-gnu.so\", at +0xcdf6 [0x77b7315dddf6]\n" +" Binary file \"/usr/lib/libffi.so.8\", at +0x7976 [0x77b73158f976]\n" +" Binary file \"/usr/lib/libffi.so.8\", at +0x413c [0x77b73158c13c]\n" +" Binary file \"/usr/lib/libffi.so.8\", at ffi_call+0x12e [0x77b73158ef0e]\n" +" Binary file \"/opt/python/build/lib.linux-x86_64-3.14/_ctypes.cpython-314d-" +"x86_64-linux-gnu.so\", at +0x15a33 [0x77b7315e6a33]\n" +" Binary file \"/opt/python/build/lib.linux-x86_64-3.14/_ctypes.cpython-314d-" +"x86_64-linux-gnu.so\", at +0x164fa [0x77b7315e74fa]\n" +" Binary file \"/opt/python/build/lib.linux-x86_64-3.14/_ctypes.cpython-314d-" +"x86_64-linux-gnu.so\", at +0xc624 [0x77b7315dd624]\n" +" Binary file \"/opt/python/python\", at _PyObject_MakeTpCall+0xce " +"[0x5b27f7b73883]\n" +" Binary file \"/opt/python/python\", at +0x11bab6 [0x5b27f7b73ab6]\n" +" Binary file \"/opt/python/python\", at PyObject_Vectorcall+0x23 " +"[0x5b27f7b73b04]\n" +" Binary file \"/opt/python/python\", at _PyEval_EvalFrameDefault+0x490c " +"[0x5b27f7cbb302]\n" +" Binary file \"/opt/python/python\", at +0x2818e6 [0x5b27f7cd98e6]\n" +" Binary file \"/opt/python/python\", at +0x281aab [0x5b27f7cd9aab]\n" +" Binary file \"/opt/python/python\", at PyEval_EvalCode+0xc5 " +"[0x5b27f7cd9ba3]\n" +" Binary file \"/opt/python/python\", at +0x255957 [0x5b27f7cad957]\n" +" Binary file \"/opt/python/python\", at +0x255ab4 [0x5b27f7cadab4]\n" +" Binary file \"/opt/python/python\", at _PyEval_EvalFrameDefault+0x6c3e " +"[0x5b27f7cbd634]\n" +" Binary file \"/opt/python/python\", at +0x2818e6 [0x5b27f7cd98e6]\n" +" Binary file \"/opt/python/python\", at +0x281aab [0x5b27f7cd9aab]\n" +" Binary file \"/opt/python/python\", at +0x11b6e1 [0x5b27f7b736e1]\n" +" Binary file \"/opt/python/python\", at +0x11d348 [0x5b27f7b75348]\n" +" Binary file \"/opt/python/python\", at +0x11d626 [0x5b27f7b75626]\n" +" Binary file \"/opt/python/python\", at PyObject_Call+0x20 " +"[0x5b27f7b7565e]\n" +" Binary file \"/opt/python/python\", at +0x32a67a [0x5b27f7d8267a]\n" +" Binary file \"/opt/python/python\", at +0x32a7f8 [0x5b27f7d827f8]\n" +" Binary file \"/opt/python/python\", at +0x32ac1b [0x5b27f7d82c1b]\n" +" Binary file \"/opt/python/python\", at Py_RunMain+0x31 [0x5b27f7d82ebe]\n" +" \n" +"Segmentation fault" +msgstr "" + +#~ msgid "" +#~ "$ python -c \"import ctypes; ctypes.string_at(0)\"\n" +#~ "Segmentation fault\n" +#~ "\n" +#~ "$ python -q -X faulthandler\n" +#~ ">>> import ctypes\n" +#~ ">>> ctypes.string_at(0)\n" +#~ "Fatal Python error: Segmentation fault\n" +#~ "\n" +#~ "Current thread 0x00007fb899f39700 (most recent call first):\n" +#~ " File \"/home/python/cpython/Lib/ctypes/__init__.py\", line 486 in " +#~ "string_at\n" +#~ " File \"\", line 1 in \n" +#~ "Segmentation fault" +#~ msgstr "" +#~ "$ python -c \"import ctypes; ctypes.string_at(0)\"\n" +#~ "Segmentation fault\n" +#~ "\n" +#~ "$ python -q -X faulthandler\n" +#~ ">>> import ctypes\n" +#~ ">>> ctypes.string_at(0)\n" +#~ "Fatal Python error: Segmentation fault\n" +#~ "\n" +#~ "Current thread 0x00007fb899f39700 (most recent call first):\n" +#~ " File \"/home/python/cpython/Lib/ctypes/__init__.py\", line 486 in " +#~ "string_at\n" +#~ " File \"\", line 1 in \n" +#~ "Segmentation fault" diff --git a/library/fcntl.po b/library/fcntl.po index 7f8e4b7a7f..b3bd29ea3a 100644 --- a/library/fcntl.po +++ b/library/fcntl.po @@ -1,414 +1,414 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: 2017-09-22 18:26+0000\n" -"Last-Translator: Liang-Bo Wang \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/fcntl.rst:2 -msgid ":mod:`!fcntl` --- The ``fcntl`` and ``ioctl`` system calls" -msgstr ":mod:`!fcntl` --- ``fcntl`` 和 ``ioctl`` 系統呼叫" - -#: ../../library/fcntl.rst:16 -msgid "" -"This module performs file and I/O control on file descriptors. It is an " -"interface to the :c:func:`fcntl` and :c:func:`ioctl` Unix routines. See " -"the :manpage:`fcntl(2)` and :manpage:`ioctl(2)` Unix manual pages for full " -"details." -msgstr "" - -#: ../../library/fcntl.rst:21 -msgid "Availability" -msgstr "可用性" - -#: ../../library/fcntl.rst:23 -msgid "" -"All functions in this module take a file descriptor *fd* as their first " -"argument. This can be an integer file descriptor, such as returned by " -"``sys.stdin.fileno()``, or an :class:`io.IOBase` object, such as " -"``sys.stdin`` itself, which provides a :meth:`~io.IOBase.fileno` that " -"returns a genuine file descriptor." -msgstr "" - -#: ../../library/fcntl.rst:29 -msgid "" -"Operations in this module used to raise an :exc:`IOError` where they now " -"raise an :exc:`OSError`." -msgstr "" - -#: ../../library/fcntl.rst:33 -msgid "" -"The :mod:`!fcntl` module now contains ``F_ADD_SEALS``, ``F_GET_SEALS``, and " -"``F_SEAL_*`` constants for sealing of :func:`os.memfd_create` file " -"descriptors." -msgstr "" - -#: ../../library/fcntl.rst:38 -msgid "" -"On macOS, the :mod:`!fcntl` module exposes the ``F_GETPATH`` constant, which " -"obtains the path of a file from a file descriptor. On Linux(>=3.15), " -"the :mod:`!fcntl` module exposes the ``F_OFD_GETLK``, ``F_OFD_SETLK`` and " -"``F_OFD_SETLKW`` constants, which are used when working with open file " -"description locks." -msgstr "" - -#: ../../library/fcntl.rst:45 -msgid "" -"On Linux >= 2.6.11, the :mod:`!fcntl` module exposes the ``F_GETPIPE_SZ`` " -"and ``F_SETPIPE_SZ`` constants, which allow to check and modify a pipe's " -"size respectively." -msgstr "" - -#: ../../library/fcntl.rst:50 -msgid "" -"On FreeBSD, the :mod:`!fcntl` module exposes the ``F_DUP2FD`` and " -"``F_DUP2FD_CLOEXEC`` constants, which allow to duplicate a file descriptor, " -"the latter setting ``FD_CLOEXEC`` flag in addition." -msgstr "" - -#: ../../library/fcntl.rst:55 -msgid "" -"On Linux >= 4.5, the :mod:`fcntl` module exposes the ``FICLONE`` and " -"``FICLONERANGE`` constants, which allow to share some data of one file with " -"another file by reflinking on some filesystems (e.g., btrfs, OCFS2, and " -"XFS). This behavior is commonly referred to as \"copy-on-write\"." -msgstr "" - -#: ../../library/fcntl.rst:61 -msgid "" -"On Linux >= 2.6.32, the :mod:`!fcntl` module exposes the ``F_GETOWN_EX``, " -"``F_SETOWN_EX``, ``F_OWNER_TID``, ``F_OWNER_PID``, ``F_OWNER_PGRP`` " -"constants, which allow to direct I/O availability signals to a specific " -"thread, process, or process group. On Linux >= 4.13, the :mod:`!fcntl` " -"module exposes the ``F_GET_RW_HINT``, ``F_SET_RW_HINT``, " -"``F_GET_FILE_RW_HINT``, ``F_SET_FILE_RW_HINT``, and ``RWH_WRITE_LIFE_*`` " -"constants, which allow to inform the kernel about the relative expected " -"lifetime of writes on a given inode or via a particular open file " -"description. On Linux >= 5.1 and NetBSD, the :mod:`!fcntl` module exposes " -"the ``F_SEAL_FUTURE_WRITE`` constant for use with ``F_ADD_SEALS`` and " -"``F_GET_SEALS`` operations. On FreeBSD, the :mod:`!fcntl` module exposes the " -"``F_READAHEAD``, ``F_ISUNIONSTACK``, and ``F_KINFO`` constants. On macOS and " -"FreeBSD, the :mod:`!fcntl` module exposes the ``F_RDAHEAD`` constant. On " -"NetBSD and AIX, the :mod:`!fcntl` module exposes the ``F_CLOSEM`` constant. " -"On NetBSD, the :mod:`!fcntl` module exposes the ``F_MAXFD`` constant. On " -"macOS and NetBSD, the :mod:`!fcntl` module exposes the ``F_GETNOSIGPIPE`` " -"and ``F_SETNOSIGPIPE`` constant." -msgstr "" - -#: ../../library/fcntl.rst:82 -msgid "" -"On Linux >= 6.1, the :mod:`!fcntl` module exposes the ``F_DUPFD_QUERY`` to " -"query a file descriptor pointing to the same file." -msgstr "" - -#: ../../library/fcntl.rst:86 -msgid "The module defines the following functions:" -msgstr "這個模組定義了以下函式：" - -#: ../../library/fcntl.rst:91 -msgid "" -"Perform the operation *cmd* on file descriptor *fd* (file objects providing " -"a :meth:`~io.IOBase.fileno` method are accepted as well). The values used " -"for *cmd* are operating system dependent, and are available as constants in " -"the :mod:`fcntl` module, using the same names as used in the relevant C " -"header files. The argument *arg* can either be an integer value, " -"a :term:`bytes-like object`, or a string. The type and size of *arg* must " -"match the type and size of the argument of the operation as specified in the " -"relevant C documentation." -msgstr "" - -#: ../../library/fcntl.rst:100 -msgid "" -"When *arg* is an integer, the function returns the integer return value of " -"the C :c:func:`fcntl` call." -msgstr "" - -#: ../../library/fcntl.rst:103 -msgid "" -"When the argument is bytes-like object, it represents a binary structure, " -"for example, created by :func:`struct.pack`. A string value is encoded to " -"binary using the UTF-8 encoding. The binary data is copied to a buffer whose " -"address is passed to the C :c:func:`fcntl` call. The return value after a " -"successful call is the contents of the buffer, converted to a :class:`bytes` " -"object. The length of the returned object will be the same as the length of " -"the *arg* argument. This is limited to 1024 bytes." -msgstr "" - -#: ../../library/fcntl.rst:112 -msgid "If the :c:func:`fcntl` call fails, an :exc:`OSError` is raised." -msgstr "" - -#: ../../library/fcntl.rst:115 -msgid "" -"If the type or the size of *arg* does not match the type or size of the " -"argument of the operation (for example, if an integer is passed when a " -"pointer is expected, or the information returned in the buffer by the " -"operating system is larger than 1024 bytes), this is most likely to result " -"in a segmentation violation or a more subtle data corruption." -msgstr "" - -#: ../../library/fcntl.rst:122 -msgid "" -"Raises an :ref:`auditing event ` ``fcntl.fcntl`` with arguments " -"``fd``, ``cmd``, ``arg``." -msgstr "" -"引發一個附帶引數 ``fd``、``cmd``、``arg`` 的\\ :ref:`稽核事件 ` " -"``fcntl.fcntl``。" - -#: ../../library/fcntl.rst:124 -msgid "" -"Add support of arbitrary :term:`bytes-like objects `, not " -"only :class:`bytes`." -msgstr "" - -#: ../../library/fcntl.rst:131 -msgid "" -"This function is identical to the :func:`~fcntl.fcntl` function, except that " -"the argument handling is even more complicated." -msgstr "" - -#: ../../library/fcntl.rst:134 -msgid "" -"The *request* parameter is limited to values that can fit in 32-bits or 64-" -"bits, depending on the platform. Additional constants of interest for use as " -"the *request* argument can be found in the :mod:`termios` module, under the " -"same names as used in the relevant C header files." -msgstr "" - -#: ../../library/fcntl.rst:140 -msgid "" -"The parameter *arg* can be an integer, a :term:`bytes-like object`, or a " -"string. The type and size of *arg* must match the type and size of the " -"argument of the operation as specified in the relevant C documentation." -msgstr "" - -#: ../../library/fcntl.rst:145 -msgid "" -"If *arg* does not support the read-write buffer interface or the " -"*mutate_flag* is false, behavior is as for the :func:`~fcntl.fcntl` function." -msgstr "" - -#: ../../library/fcntl.rst:149 -msgid "" -"If *arg* supports the read-write buffer interface (like :class:`bytearray`) " -"and *mutate_flag* is true (the default), then the buffer is (in effect) " -"passed to the underlying :c:func:`!ioctl` system call, the latter's return " -"code is passed back to the calling Python, and the buffer's new contents " -"reflect the action of the :c:func:`ioctl`. This is a slight simplification, " -"because if the supplied buffer is less than 1024 bytes long it is first " -"copied into a static buffer 1024 bytes long which is then passed " -"to :func:`ioctl` and copied back into the supplied buffer." -msgstr "" - -#: ../../library/fcntl.rst:158 -msgid "" -"If the :c:func:`ioctl` call fails, an :exc:`OSError` exception is raised." -msgstr "" - -#: ../../library/fcntl.rst:161 -msgid "" -"If the type or size of *arg* does not match the type or size of the " -"operation's argument (for example, if an integer is passed when a pointer is " -"expected, or the information returned in the buffer by the operating system " -"is larger than 1024 bytes, or the size of the mutable bytes-like object is " -"too small), this is most likely to result in a segmentation violation or a " -"more subtle data corruption." -msgstr "" - -#: ../../library/fcntl.rst:169 -msgid "An example::" -msgstr "範例： ::" - -#: ../../library/fcntl.rst:171 -msgid "" -">>> import array, fcntl, struct, termios, os\n" -">>> os.getpgrp()\n" -"13341\n" -">>> struct.unpack('h', fcntl.ioctl(0, termios.TIOCGPGRP, \" \"))[0]\n" -"13341\n" -">>> buf = array.array('h', [0])\n" -">>> fcntl.ioctl(0, termios.TIOCGPGRP, buf, 1)\n" -"0\n" -">>> buf\n" -"array('h', [13341])" -msgstr "" -">>> import array, fcntl, struct, termios, os\n" -">>> os.getpgrp()\n" -"13341\n" -">>> struct.unpack('h', fcntl.ioctl(0, termios.TIOCGPGRP, \" \"))[0]\n" -"13341\n" -">>> buf = array.array('h', [0])\n" -">>> fcntl.ioctl(0, termios.TIOCGPGRP, buf, 1)\n" -"0\n" -">>> buf\n" -"array('h', [13341])" - -#: ../../library/fcntl.rst:182 -msgid "" -"Raises an :ref:`auditing event ` ``fcntl.ioctl`` with arguments " -"``fd``, ``request``, ``arg``." -msgstr "" -"引發一個附帶引數 ``fd``、``request``、``arg`` 的\\ :ref:`稽核事件 " -"` ``fcntl.ioctl``。" - -#: ../../library/fcntl.rst:184 -msgid "" -"The GIL is always released during a system call. System calls failing with " -"EINTR are automatically retried." -msgstr "" - -#: ../../library/fcntl.rst:190 -msgid "" -"Perform the lock operation *operation* on file descriptor *fd* (file objects " -"providing a :meth:`~io.IOBase.fileno` method are accepted as well). See the " -"Unix manual :manpage:`flock(2)` for details. (On some systems, this " -"function is emulated using :c:func:`fcntl`.)" -msgstr "" - -#: ../../library/fcntl.rst:195 -msgid "" -"If the :c:func:`flock` call fails, an :exc:`OSError` exception is raised." -msgstr "" - -#: ../../library/fcntl.rst:197 -msgid "" -"Raises an :ref:`auditing event ` ``fcntl.flock`` with arguments " -"``fd``, ``operation``." -msgstr "" -"引發一個附帶引數 ``fd``、``operation`` 的\\ :ref:`稽核事件 ` " -"``fcntl.flock``。" - -#: ../../library/fcntl.rst:202 -msgid "" -"This is essentially a wrapper around the :func:`~fcntl.fcntl` locking calls. " -"*fd* is the file descriptor (file objects providing " -"a :meth:`~io.IOBase.fileno` method are accepted as well) of the file to lock " -"or unlock, and *cmd* is one of the following values:" -msgstr "" - -#: ../../library/fcntl.rst:209 -msgid "Release an existing lock." -msgstr "" - -#: ../../library/fcntl.rst:213 -msgid "Acquire a shared lock." -msgstr "" - -#: ../../library/fcntl.rst:217 -msgid "Acquire an exclusive lock." -msgstr "" - -#: ../../library/fcntl.rst:221 -msgid "" -"Bitwise OR with any of the other three ``LOCK_*`` constants to make the " -"request non-blocking." -msgstr "" - -#: ../../library/fcntl.rst:224 -msgid "" -"If :const:`!LOCK_NB` is used and the lock cannot be acquired, " -"an :exc:`OSError` will be raised and the exception will have an *errno* " -"attribute set to :const:`~errno.EACCES` or :const:`~errno.EAGAIN` (depending " -"on the operating system; for portability, check for both values). On at " -"least some systems, :const:`!LOCK_EX` can only be used if the file " -"descriptor refers to a file opened for writing." -msgstr "" - -#: ../../library/fcntl.rst:231 -msgid "" -"*len* is the number of bytes to lock, *start* is the byte offset at which " -"the lock starts, relative to *whence*, and *whence* is as " -"with :func:`io.IOBase.seek`, specifically:" -msgstr "" - -#: ../../library/fcntl.rst:235 -msgid "``0`` -- relative to the start of the file (:const:`os.SEEK_SET`)" -msgstr "" - -#: ../../library/fcntl.rst:236 -msgid "``1`` -- relative to the current buffer position (:const:`os.SEEK_CUR`)" -msgstr "" - -#: ../../library/fcntl.rst:237 -msgid "``2`` -- relative to the end of the file (:const:`os.SEEK_END`)" -msgstr "" - -#: ../../library/fcntl.rst:239 -msgid "" -"The default for *start* is 0, which means to start at the beginning of the " -"file. The default for *len* is 0 which means to lock to the end of the " -"file. The default for *whence* is also 0." -msgstr "" - -#: ../../library/fcntl.rst:243 -msgid "" -"Raises an :ref:`auditing event ` ``fcntl.lockf`` with arguments " -"``fd``, ``cmd``, ``len``, ``start``, ``whence``." -msgstr "" -"引發一個附帶引數 ``fd``、``cmd``、``len``、``start``、``whence`` 的\\ :ref:`" -"稽核事件 ` ``fcntl.lockf``。" - -#: ../../library/fcntl.rst:245 -msgid "Examples (all on a SVR4 compliant system)::" -msgstr "" - -#: ../../library/fcntl.rst:247 -msgid "" -"import struct, fcntl, os\n" -"\n" -"f = open(...)\n" -"rv = fcntl.fcntl(f, fcntl.F_SETFL, os.O_NDELAY)\n" -"\n" -"lockdata = struct.pack('hhllhh', fcntl.F_WRLCK, 0, 0, 0, 0, 0)\n" -"rv = fcntl.fcntl(f, fcntl.F_SETLKW, lockdata)" -msgstr "" -"import struct, fcntl, os\n" -"\n" -"f = open(...)\n" -"rv = fcntl.fcntl(f, fcntl.F_SETFL, os.O_NDELAY)\n" -"\n" -"lockdata = struct.pack('hhllhh', fcntl.F_WRLCK, 0, 0, 0, 0, 0)\n" -"rv = fcntl.fcntl(f, fcntl.F_SETLKW, lockdata)" - -#: ../../library/fcntl.rst:255 -msgid "" -"Note that in the first example the return value variable *rv* will hold an " -"integer value; in the second example it will hold a :class:`bytes` object. " -"The structure lay-out for the *lockdata* variable is system dependent --- " -"therefore using the :func:`flock` call may be better." -msgstr "" - -#: ../../library/fcntl.rst:263 -msgid "Module :mod:`os`" -msgstr ":mod:`os` 模組" - -#: ../../library/fcntl.rst:264 -msgid "" -"If the locking flags :const:`~os.O_SHLOCK` and :const:`~os.O_EXLOCK` are " -"present in the :mod:`os` module (on BSD only), the :func:`os.open` function " -"provides an alternative to the :func:`lockf` and :func:`flock` functions." -msgstr "" - -#: ../../library/fcntl.rst:10 -msgid "UNIX" -msgstr "UNIX" - -#: ../../library/fcntl.rst:10 -msgid "file control" -msgstr "file control（檔案控制）" - -#: ../../library/fcntl.rst:10 -msgid "I/O control" -msgstr "I/O control（I/O 控制）" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: 2017-09-22 18:26+0000\n" +"Last-Translator: Liang-Bo Wang \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/fcntl.rst:2 +msgid ":mod:`!fcntl` --- The ``fcntl`` and ``ioctl`` system calls" +msgstr ":mod:`!fcntl` --- ``fcntl`` 和 ``ioctl`` 系統呼叫" + +#: ../../library/fcntl.rst:16 +msgid "" +"This module performs file and I/O control on file descriptors. It is an " +"interface to the :c:func:`fcntl` and :c:func:`ioctl` Unix routines. See " +"the :manpage:`fcntl(2)` and :manpage:`ioctl(2)` Unix manual pages for full " +"details." +msgstr "" + +#: ../../library/fcntl.rst:21 +msgid "Availability" +msgstr "可用性" + +#: ../../library/fcntl.rst:23 +msgid "" +"All functions in this module take a file descriptor *fd* as their first " +"argument. This can be an integer file descriptor, such as returned by " +"``sys.stdin.fileno()``, or an :class:`io.IOBase` object, such as " +"``sys.stdin`` itself, which provides a :meth:`~io.IOBase.fileno` that " +"returns a genuine file descriptor." +msgstr "" + +#: ../../library/fcntl.rst:29 +msgid "" +"Operations in this module used to raise an :exc:`IOError` where they now " +"raise an :exc:`OSError`." +msgstr "" + +#: ../../library/fcntl.rst:33 +msgid "" +"The :mod:`!fcntl` module now contains ``F_ADD_SEALS``, ``F_GET_SEALS``, and " +"``F_SEAL_*`` constants for sealing of :func:`os.memfd_create` file " +"descriptors." +msgstr "" + +#: ../../library/fcntl.rst:38 +msgid "" +"On macOS, the :mod:`!fcntl` module exposes the ``F_GETPATH`` constant, which " +"obtains the path of a file from a file descriptor. On Linux(>=3.15), " +"the :mod:`!fcntl` module exposes the ``F_OFD_GETLK``, ``F_OFD_SETLK`` and " +"``F_OFD_SETLKW`` constants, which are used when working with open file " +"description locks." +msgstr "" + +#: ../../library/fcntl.rst:45 +msgid "" +"On Linux >= 2.6.11, the :mod:`!fcntl` module exposes the ``F_GETPIPE_SZ`` " +"and ``F_SETPIPE_SZ`` constants, which allow to check and modify a pipe's " +"size respectively." +msgstr "" + +#: ../../library/fcntl.rst:50 +msgid "" +"On FreeBSD, the :mod:`!fcntl` module exposes the ``F_DUP2FD`` and " +"``F_DUP2FD_CLOEXEC`` constants, which allow to duplicate a file descriptor, " +"the latter setting ``FD_CLOEXEC`` flag in addition." +msgstr "" + +#: ../../library/fcntl.rst:55 +msgid "" +"On Linux >= 4.5, the :mod:`fcntl` module exposes the ``FICLONE`` and " +"``FICLONERANGE`` constants, which allow to share some data of one file with " +"another file by reflinking on some filesystems (e.g., btrfs, OCFS2, and " +"XFS). This behavior is commonly referred to as \"copy-on-write\"." +msgstr "" + +#: ../../library/fcntl.rst:61 +msgid "" +"On Linux >= 2.6.32, the :mod:`!fcntl` module exposes the ``F_GETOWN_EX``, " +"``F_SETOWN_EX``, ``F_OWNER_TID``, ``F_OWNER_PID``, ``F_OWNER_PGRP`` " +"constants, which allow to direct I/O availability signals to a specific " +"thread, process, or process group. On Linux >= 4.13, the :mod:`!fcntl` " +"module exposes the ``F_GET_RW_HINT``, ``F_SET_RW_HINT``, " +"``F_GET_FILE_RW_HINT``, ``F_SET_FILE_RW_HINT``, and ``RWH_WRITE_LIFE_*`` " +"constants, which allow to inform the kernel about the relative expected " +"lifetime of writes on a given inode or via a particular open file " +"description. On Linux >= 5.1 and NetBSD, the :mod:`!fcntl` module exposes " +"the ``F_SEAL_FUTURE_WRITE`` constant for use with ``F_ADD_SEALS`` and " +"``F_GET_SEALS`` operations. On FreeBSD, the :mod:`!fcntl` module exposes the " +"``F_READAHEAD``, ``F_ISUNIONSTACK``, and ``F_KINFO`` constants. On macOS and " +"FreeBSD, the :mod:`!fcntl` module exposes the ``F_RDAHEAD`` constant. On " +"NetBSD and AIX, the :mod:`!fcntl` module exposes the ``F_CLOSEM`` constant. " +"On NetBSD, the :mod:`!fcntl` module exposes the ``F_MAXFD`` constant. On " +"macOS and NetBSD, the :mod:`!fcntl` module exposes the ``F_GETNOSIGPIPE`` " +"and ``F_SETNOSIGPIPE`` constant." +msgstr "" + +#: ../../library/fcntl.rst:82 +msgid "" +"On Linux >= 6.1, the :mod:`!fcntl` module exposes the ``F_DUPFD_QUERY`` to " +"query a file descriptor pointing to the same file." +msgstr "" + +#: ../../library/fcntl.rst:86 +msgid "The module defines the following functions:" +msgstr "這個模組定義了以下函式：" + +#: ../../library/fcntl.rst:91 +msgid "" +"Perform the operation *cmd* on file descriptor *fd* (file objects providing " +"a :meth:`~io.IOBase.fileno` method are accepted as well). The values used " +"for *cmd* are operating system dependent, and are available as constants in " +"the :mod:`fcntl` module, using the same names as used in the relevant C " +"header files. The argument *arg* can either be an integer value, " +"a :term:`bytes-like object`, or a string. The type and size of *arg* must " +"match the type and size of the argument of the operation as specified in the " +"relevant C documentation." +msgstr "" + +#: ../../library/fcntl.rst:100 +msgid "" +"When *arg* is an integer, the function returns the integer return value of " +"the C :c:func:`fcntl` call." +msgstr "" + +#: ../../library/fcntl.rst:103 +msgid "" +"When the argument is bytes-like object, it represents a binary structure, " +"for example, created by :func:`struct.pack`. A string value is encoded to " +"binary using the UTF-8 encoding. The binary data is copied to a buffer whose " +"address is passed to the C :c:func:`fcntl` call. The return value after a " +"successful call is the contents of the buffer, converted to a :class:`bytes` " +"object. The length of the returned object will be the same as the length of " +"the *arg* argument. This is limited to 1024 bytes." +msgstr "" + +#: ../../library/fcntl.rst:112 +msgid "If the :c:func:`fcntl` call fails, an :exc:`OSError` is raised." +msgstr "" + +#: ../../library/fcntl.rst:115 +msgid "" +"If the type or the size of *arg* does not match the type or size of the " +"argument of the operation (for example, if an integer is passed when a " +"pointer is expected, or the information returned in the buffer by the " +"operating system is larger than 1024 bytes), this is most likely to result " +"in a segmentation violation or a more subtle data corruption." +msgstr "" + +#: ../../library/fcntl.rst:122 +msgid "" +"Raises an :ref:`auditing event ` ``fcntl.fcntl`` with arguments " +"``fd``, ``cmd``, ``arg``." +msgstr "" +"引發一個附帶引數 ``fd``、``cmd``、``arg`` 的\\ :ref:`稽核事件 ` " +"``fcntl.fcntl``。" + +#: ../../library/fcntl.rst:124 +msgid "" +"Add support of arbitrary :term:`bytes-like objects `, not " +"only :class:`bytes`." +msgstr "" + +#: ../../library/fcntl.rst:131 +msgid "" +"This function is identical to the :func:`~fcntl.fcntl` function, except that " +"the argument handling is even more complicated." +msgstr "" + +#: ../../library/fcntl.rst:134 +msgid "" +"The *request* parameter is limited to values that can fit in 32-bits or 64-" +"bits, depending on the platform. Additional constants of interest for use as " +"the *request* argument can be found in the :mod:`termios` module, under the " +"same names as used in the relevant C header files." +msgstr "" + +#: ../../library/fcntl.rst:140 +msgid "" +"The parameter *arg* can be an integer, a :term:`bytes-like object`, or a " +"string. The type and size of *arg* must match the type and size of the " +"argument of the operation as specified in the relevant C documentation." +msgstr "" + +#: ../../library/fcntl.rst:145 +msgid "" +"If *arg* does not support the read-write buffer interface or the " +"*mutate_flag* is false, behavior is as for the :func:`~fcntl.fcntl` function." +msgstr "" + +#: ../../library/fcntl.rst:149 +msgid "" +"If *arg* supports the read-write buffer interface (like :class:`bytearray`) " +"and *mutate_flag* is true (the default), then the buffer is (in effect) " +"passed to the underlying :c:func:`!ioctl` system call, the latter's return " +"code is passed back to the calling Python, and the buffer's new contents " +"reflect the action of the :c:func:`ioctl`. This is a slight simplification, " +"because if the supplied buffer is less than 1024 bytes long it is first " +"copied into a static buffer 1024 bytes long which is then passed " +"to :func:`ioctl` and copied back into the supplied buffer." +msgstr "" + +#: ../../library/fcntl.rst:158 +msgid "" +"If the :c:func:`ioctl` call fails, an :exc:`OSError` exception is raised." +msgstr "" + +#: ../../library/fcntl.rst:161 +msgid "" +"If the type or size of *arg* does not match the type or size of the " +"operation's argument (for example, if an integer is passed when a pointer is " +"expected, or the information returned in the buffer by the operating system " +"is larger than 1024 bytes, or the size of the mutable bytes-like object is " +"too small), this is most likely to result in a segmentation violation or a " +"more subtle data corruption." +msgstr "" + +#: ../../library/fcntl.rst:169 +msgid "An example::" +msgstr "範例： ::" + +#: ../../library/fcntl.rst:171 +msgid "" +">>> import array, fcntl, struct, termios, os\n" +">>> os.getpgrp()\n" +"13341\n" +">>> struct.unpack('h', fcntl.ioctl(0, termios.TIOCGPGRP, \" \"))[0]\n" +"13341\n" +">>> buf = array.array('h', [0])\n" +">>> fcntl.ioctl(0, termios.TIOCGPGRP, buf, 1)\n" +"0\n" +">>> buf\n" +"array('h', [13341])" +msgstr "" +">>> import array, fcntl, struct, termios, os\n" +">>> os.getpgrp()\n" +"13341\n" +">>> struct.unpack('h', fcntl.ioctl(0, termios.TIOCGPGRP, \" \"))[0]\n" +"13341\n" +">>> buf = array.array('h', [0])\n" +">>> fcntl.ioctl(0, termios.TIOCGPGRP, buf, 1)\n" +"0\n" +">>> buf\n" +"array('h', [13341])" + +#: ../../library/fcntl.rst:182 +msgid "" +"Raises an :ref:`auditing event ` ``fcntl.ioctl`` with arguments " +"``fd``, ``request``, ``arg``." +msgstr "" +"引發一個附帶引數 ``fd``、``request``、``arg`` 的\\ :ref:`稽核事件 " +"` ``fcntl.ioctl``。" + +#: ../../library/fcntl.rst:184 +msgid "" +"The GIL is always released during a system call. System calls failing with " +"EINTR are automatically retried." +msgstr "" + +#: ../../library/fcntl.rst:190 +msgid "" +"Perform the lock operation *operation* on file descriptor *fd* (file objects " +"providing a :meth:`~io.IOBase.fileno` method are accepted as well). See the " +"Unix manual :manpage:`flock(2)` for details. (On some systems, this " +"function is emulated using :c:func:`fcntl`.)" +msgstr "" + +#: ../../library/fcntl.rst:195 +msgid "" +"If the :c:func:`flock` call fails, an :exc:`OSError` exception is raised." +msgstr "" + +#: ../../library/fcntl.rst:197 +msgid "" +"Raises an :ref:`auditing event ` ``fcntl.flock`` with arguments " +"``fd``, ``operation``." +msgstr "" +"引發一個附帶引數 ``fd``、``operation`` 的\\ :ref:`稽核事件 ` " +"``fcntl.flock``。" + +#: ../../library/fcntl.rst:202 +msgid "" +"This is essentially a wrapper around the :func:`~fcntl.fcntl` locking calls. " +"*fd* is the file descriptor (file objects providing " +"a :meth:`~io.IOBase.fileno` method are accepted as well) of the file to lock " +"or unlock, and *cmd* is one of the following values:" +msgstr "" + +#: ../../library/fcntl.rst:209 +msgid "Release an existing lock." +msgstr "" + +#: ../../library/fcntl.rst:213 +msgid "Acquire a shared lock." +msgstr "" + +#: ../../library/fcntl.rst:217 +msgid "Acquire an exclusive lock." +msgstr "" + +#: ../../library/fcntl.rst:221 +msgid "" +"Bitwise OR with any of the other three ``LOCK_*`` constants to make the " +"request non-blocking." +msgstr "" + +#: ../../library/fcntl.rst:224 +msgid "" +"If :const:`!LOCK_NB` is used and the lock cannot be acquired, " +"an :exc:`OSError` will be raised and the exception will have an *errno* " +"attribute set to :const:`~errno.EACCES` or :const:`~errno.EAGAIN` (depending " +"on the operating system; for portability, check for both values). On at " +"least some systems, :const:`!LOCK_EX` can only be used if the file " +"descriptor refers to a file opened for writing." +msgstr "" + +#: ../../library/fcntl.rst:231 +msgid "" +"*len* is the number of bytes to lock, *start* is the byte offset at which " +"the lock starts, relative to *whence*, and *whence* is as " +"with :func:`io.IOBase.seek`, specifically:" +msgstr "" + +#: ../../library/fcntl.rst:235 +msgid "``0`` -- relative to the start of the file (:const:`os.SEEK_SET`)" +msgstr "" + +#: ../../library/fcntl.rst:236 +msgid "``1`` -- relative to the current buffer position (:const:`os.SEEK_CUR`)" +msgstr "" + +#: ../../library/fcntl.rst:237 +msgid "``2`` -- relative to the end of the file (:const:`os.SEEK_END`)" +msgstr "" + +#: ../../library/fcntl.rst:239 +msgid "" +"The default for *start* is 0, which means to start at the beginning of the " +"file. The default for *len* is 0 which means to lock to the end of the " +"file. The default for *whence* is also 0." +msgstr "" + +#: ../../library/fcntl.rst:243 +msgid "" +"Raises an :ref:`auditing event ` ``fcntl.lockf`` with arguments " +"``fd``, ``cmd``, ``len``, ``start``, ``whence``." +msgstr "" +"引發一個附帶引數 ``fd``、``cmd``、``len``、``start``、``whence`` 的\\ :ref:`" +"稽核事件 ` ``fcntl.lockf``。" + +#: ../../library/fcntl.rst:245 +msgid "Examples (all on a SVR4 compliant system)::" +msgstr "" + +#: ../../library/fcntl.rst:247 +msgid "" +"import struct, fcntl, os\n" +"\n" +"f = open(...)\n" +"rv = fcntl.fcntl(f, fcntl.F_SETFL, os.O_NDELAY)\n" +"\n" +"lockdata = struct.pack('hhllhh', fcntl.F_WRLCK, 0, 0, 0, 0, 0)\n" +"rv = fcntl.fcntl(f, fcntl.F_SETLKW, lockdata)" +msgstr "" +"import struct, fcntl, os\n" +"\n" +"f = open(...)\n" +"rv = fcntl.fcntl(f, fcntl.F_SETFL, os.O_NDELAY)\n" +"\n" +"lockdata = struct.pack('hhllhh', fcntl.F_WRLCK, 0, 0, 0, 0, 0)\n" +"rv = fcntl.fcntl(f, fcntl.F_SETLKW, lockdata)" + +#: ../../library/fcntl.rst:255 +msgid "" +"Note that in the first example the return value variable *rv* will hold an " +"integer value; in the second example it will hold a :class:`bytes` object. " +"The structure lay-out for the *lockdata* variable is system dependent --- " +"therefore using the :func:`flock` call may be better." +msgstr "" + +#: ../../library/fcntl.rst:263 +msgid "Module :mod:`os`" +msgstr ":mod:`os` 模組" + +#: ../../library/fcntl.rst:264 +msgid "" +"If the locking flags :const:`~os.O_SHLOCK` and :const:`~os.O_EXLOCK` are " +"present in the :mod:`os` module (on BSD only), the :func:`os.open` function " +"provides an alternative to the :func:`lockf` and :func:`flock` functions." +msgstr "" + +#: ../../library/fcntl.rst:10 +msgid "UNIX" +msgstr "UNIX" + +#: ../../library/fcntl.rst:10 +msgid "file control" +msgstr "file control（檔案控制）" + +#: ../../library/fcntl.rst:10 +msgid "I/O control" +msgstr "I/O control（I/O 控制）" diff --git a/library/filecmp.po b/library/filecmp.po index 72f95f8282..90f82bdb7f 100644 --- a/library/filecmp.po +++ b/library/filecmp.po @@ -1,265 +1,265 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-02-19 00:13+0000\n" -"PO-Revision-Date: 2015-12-09 17:51+0000\n" -"Last-Translator: Liang-Bo Wang \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/filecmp.rst:2 -msgid ":mod:`!filecmp` --- File and Directory Comparisons" -msgstr ":mod:`!filecmp` --- 檔案與目錄比較" - -#: ../../library/filecmp.rst:9 -msgid "**Source code:** :source:`Lib/filecmp.py`" -msgstr "**原始碼：**\\ :source:`Lib/filecmp.py`" - -#: ../../library/filecmp.rst:13 -msgid "" -"The :mod:`filecmp` module defines functions to compare files and " -"directories, with various optional time/correctness trade-offs. For " -"comparing files, see also the :mod:`difflib` module." -msgstr "" - -#: ../../library/filecmp.rst:17 -msgid "The :mod:`filecmp` module defines the following functions:" -msgstr ":mod:`filecmp` 模組定義了以下函式：" - -#: ../../library/filecmp.rst:22 -msgid "" -"Compare the files named *f1* and *f2*, returning ``True`` if they seem " -"equal, ``False`` otherwise." -msgstr "" - -#: ../../library/filecmp.rst:25 -msgid "" -"If *shallow* is true and the :func:`os.stat` signatures (file type, size, " -"and modification time) of both files are identical, the files are taken to " -"be equal." -msgstr "" - -#: ../../library/filecmp.rst:29 -msgid "" -"Otherwise, the files are treated as different if their sizes or contents " -"differ." -msgstr "" - -#: ../../library/filecmp.rst:31 -msgid "" -"Note that no external programs are called from this function, giving it " -"portability and efficiency." -msgstr "" - -#: ../../library/filecmp.rst:34 -msgid "" -"This function uses a cache for past comparisons and the results, with cache " -"entries invalidated if the :func:`os.stat` information for the file " -"changes. The entire cache may be cleared using :func:`clear_cache`." -msgstr "" - -#: ../../library/filecmp.rst:41 -msgid "" -"Compare the files in the two directories *dir1* and *dir2* whose names are " -"given by *common*." -msgstr "" - -#: ../../library/filecmp.rst:44 -msgid "" -"Returns three lists of file names: *match*, *mismatch*, *errors*. *match* " -"contains the list of files that match, *mismatch* contains the names of " -"those that don't, and *errors* lists the names of files which could not be " -"compared. Files are listed in *errors* if they don't exist in one of the " -"directories, the user lacks permission to read them or if the comparison " -"could not be done for some other reason." -msgstr "" - -#: ../../library/filecmp.rst:51 -msgid "" -"The *shallow* parameter has the same meaning and default value as " -"for :func:`filecmp.cmp`." -msgstr "" - -#: ../../library/filecmp.rst:54 -msgid "" -"For example, ``cmpfiles('a', 'b', ['c', 'd/e'])`` will compare ``a/c`` with " -"``b/c`` and ``a/d/e`` with ``b/d/e``. ``'c'`` and ``'d/e'`` will each be in " -"one of the three returned lists." -msgstr "" - -#: ../../library/filecmp.rst:61 -msgid "" -"Clear the filecmp cache. This may be useful if a file is compared so quickly " -"after it is modified that it is within the mtime resolution of the " -"underlying filesystem." -msgstr "" - -#: ../../library/filecmp.rst:71 -msgid "The :class:`dircmp` class" -msgstr "" - -#: ../../library/filecmp.rst:75 -msgid "" -"Construct a new directory comparison object, to compare the directories *a* " -"and *b*. *ignore* is a list of names to ignore, and defaults " -"to :const:`filecmp.DEFAULT_IGNORES`. *hide* is a list of names to hide, and " -"defaults to ``[os.curdir, os.pardir]``." -msgstr "" - -#: ../../library/filecmp.rst:80 -msgid "" -"The :class:`dircmp` class compares files by doing *shallow* comparisons as " -"described for :func:`filecmp.cmp` by default using the *shallow* parameter." -msgstr "" - -#: ../../library/filecmp.rst:86 -msgid "Added the *shallow* parameter." -msgstr "" - -#: ../../library/filecmp.rst:88 -msgid "The :class:`dircmp` class provides the following methods:" -msgstr "" - -#: ../../library/filecmp.rst:92 -msgid "Print (to :data:`sys.stdout`) a comparison between *a* and *b*." -msgstr "" - -#: ../../library/filecmp.rst:96 -msgid "" -"Print a comparison between *a* and *b* and common immediate subdirectories." -msgstr "" - -#: ../../library/filecmp.rst:101 -msgid "" -"Print a comparison between *a* and *b* and common subdirectories " -"(recursively)." -msgstr "" - -#: ../../library/filecmp.rst:104 -msgid "" -"The :class:`dircmp` class offers a number of interesting attributes that may " -"be used to get various bits of information about the directory trees being " -"compared." -msgstr "" - -#: ../../library/filecmp.rst:108 -msgid "" -"Note that via :meth:`~object.__getattr__` hooks, all attributes are computed " -"lazily, so there is no speed penalty if only those attributes which are " -"lightweight to compute are used." -msgstr "" - -#: ../../library/filecmp.rst:115 -msgid "The directory *a*." -msgstr "" - -#: ../../library/filecmp.rst:120 -msgid "The directory *b*." -msgstr "" - -#: ../../library/filecmp.rst:125 -msgid "Files and subdirectories in *a*, filtered by *hide* and *ignore*." -msgstr "" - -#: ../../library/filecmp.rst:130 -msgid "Files and subdirectories in *b*, filtered by *hide* and *ignore*." -msgstr "" - -#: ../../library/filecmp.rst:135 -msgid "Files and subdirectories in both *a* and *b*." -msgstr "" - -#: ../../library/filecmp.rst:140 -msgid "Files and subdirectories only in *a*." -msgstr "" - -#: ../../library/filecmp.rst:145 -msgid "Files and subdirectories only in *b*." -msgstr "" - -#: ../../library/filecmp.rst:150 -msgid "Subdirectories in both *a* and *b*." -msgstr "" - -#: ../../library/filecmp.rst:155 -msgid "Files in both *a* and *b*." -msgstr "" - -#: ../../library/filecmp.rst:160 -msgid "" -"Names in both *a* and *b*, such that the type differs between the " -"directories, or names for which :func:`os.stat` reports an error." -msgstr "" - -#: ../../library/filecmp.rst:166 -msgid "" -"Files which are identical in both *a* and *b*, using the class's file " -"comparison operator." -msgstr "" - -#: ../../library/filecmp.rst:172 -msgid "" -"Files which are in both *a* and *b*, whose contents differ according to the " -"class's file comparison operator." -msgstr "" - -#: ../../library/filecmp.rst:178 -msgid "Files which are in both *a* and *b*, but could not be compared." -msgstr "" - -#: ../../library/filecmp.rst:183 -msgid "" -"A dictionary mapping names in :attr:`common_dirs` to :class:`dircmp` " -"instances (or MyDirCmp instances if this instance is of type MyDirCmp, a " -"subclass of :class:`dircmp`)." -msgstr "" - -#: ../../library/filecmp.rst:187 -msgid "" -"Previously entries were always :class:`dircmp` instances. Now entries are " -"the same type as *self*, if *self* is a subclass of :class:`dircmp`." -msgstr "" - -#: ../../library/filecmp.rst:196 -msgid "List of directories ignored by :class:`dircmp` by default." -msgstr "" - -#: ../../library/filecmp.rst:199 -msgid "" -"Here is a simplified example of using the ``subdirs`` attribute to search " -"recursively through two directories to show common different files::" -msgstr "" - -#: ../../library/filecmp.rst:202 -msgid "" -">>> from filecmp import dircmp\n" -">>> def print_diff_files(dcmp):\n" -"... for name in dcmp.diff_files:\n" -"... print(\"diff_file %s found in %s and %s\" % (name, dcmp.left,\n" -"... dcmp.right))\n" -"... for sub_dcmp in dcmp.subdirs.values():\n" -"... print_diff_files(sub_dcmp)\n" -"...\n" -">>> dcmp = dircmp('dir1', 'dir2')\n" -">>> print_diff_files(dcmp)" -msgstr "" -">>> from filecmp import dircmp\n" -">>> def print_diff_files(dcmp):\n" -"... for name in dcmp.diff_files:\n" -"... print(\"diff_file %s found in %s and %s\" % (name, dcmp.left,\n" -"... dcmp.right))\n" -"... for sub_dcmp in dcmp.subdirs.values():\n" -"... print_diff_files(sub_dcmp)\n" -"...\n" -">>> dcmp = dircmp('dir1', 'dir2')\n" -">>> print_diff_files(dcmp)" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-02-19 00:13+0000\n" +"PO-Revision-Date: 2015-12-09 17:51+0000\n" +"Last-Translator: Liang-Bo Wang \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/filecmp.rst:2 +msgid ":mod:`!filecmp` --- File and Directory Comparisons" +msgstr ":mod:`!filecmp` --- 檔案與目錄比較" + +#: ../../library/filecmp.rst:9 +msgid "**Source code:** :source:`Lib/filecmp.py`" +msgstr "**原始碼：**\\ :source:`Lib/filecmp.py`" + +#: ../../library/filecmp.rst:13 +msgid "" +"The :mod:`filecmp` module defines functions to compare files and " +"directories, with various optional time/correctness trade-offs. For " +"comparing files, see also the :mod:`difflib` module." +msgstr "" + +#: ../../library/filecmp.rst:17 +msgid "The :mod:`filecmp` module defines the following functions:" +msgstr ":mod:`filecmp` 模組定義了以下函式：" + +#: ../../library/filecmp.rst:22 +msgid "" +"Compare the files named *f1* and *f2*, returning ``True`` if they seem " +"equal, ``False`` otherwise." +msgstr "" + +#: ../../library/filecmp.rst:25 +msgid "" +"If *shallow* is true and the :func:`os.stat` signatures (file type, size, " +"and modification time) of both files are identical, the files are taken to " +"be equal." +msgstr "" + +#: ../../library/filecmp.rst:29 +msgid "" +"Otherwise, the files are treated as different if their sizes or contents " +"differ." +msgstr "" + +#: ../../library/filecmp.rst:31 +msgid "" +"Note that no external programs are called from this function, giving it " +"portability and efficiency." +msgstr "" + +#: ../../library/filecmp.rst:34 +msgid "" +"This function uses a cache for past comparisons and the results, with cache " +"entries invalidated if the :func:`os.stat` information for the file " +"changes. The entire cache may be cleared using :func:`clear_cache`." +msgstr "" + +#: ../../library/filecmp.rst:41 +msgid "" +"Compare the files in the two directories *dir1* and *dir2* whose names are " +"given by *common*." +msgstr "" + +#: ../../library/filecmp.rst:44 +msgid "" +"Returns three lists of file names: *match*, *mismatch*, *errors*. *match* " +"contains the list of files that match, *mismatch* contains the names of " +"those that don't, and *errors* lists the names of files which could not be " +"compared. Files are listed in *errors* if they don't exist in one of the " +"directories, the user lacks permission to read them or if the comparison " +"could not be done for some other reason." +msgstr "" + +#: ../../library/filecmp.rst:51 +msgid "" +"The *shallow* parameter has the same meaning and default value as " +"for :func:`filecmp.cmp`." +msgstr "" + +#: ../../library/filecmp.rst:54 +msgid "" +"For example, ``cmpfiles('a', 'b', ['c', 'd/e'])`` will compare ``a/c`` with " +"``b/c`` and ``a/d/e`` with ``b/d/e``. ``'c'`` and ``'d/e'`` will each be in " +"one of the three returned lists." +msgstr "" + +#: ../../library/filecmp.rst:61 +msgid "" +"Clear the filecmp cache. This may be useful if a file is compared so quickly " +"after it is modified that it is within the mtime resolution of the " +"underlying filesystem." +msgstr "" + +#: ../../library/filecmp.rst:71 +msgid "The :class:`dircmp` class" +msgstr "" + +#: ../../library/filecmp.rst:75 +msgid "" +"Construct a new directory comparison object, to compare the directories *a* " +"and *b*. *ignore* is a list of names to ignore, and defaults " +"to :const:`filecmp.DEFAULT_IGNORES`. *hide* is a list of names to hide, and " +"defaults to ``[os.curdir, os.pardir]``." +msgstr "" + +#: ../../library/filecmp.rst:80 +msgid "" +"The :class:`dircmp` class compares files by doing *shallow* comparisons as " +"described for :func:`filecmp.cmp` by default using the *shallow* parameter." +msgstr "" + +#: ../../library/filecmp.rst:86 +msgid "Added the *shallow* parameter." +msgstr "" + +#: ../../library/filecmp.rst:88 +msgid "The :class:`dircmp` class provides the following methods:" +msgstr "" + +#: ../../library/filecmp.rst:92 +msgid "Print (to :data:`sys.stdout`) a comparison between *a* and *b*." +msgstr "" + +#: ../../library/filecmp.rst:96 +msgid "" +"Print a comparison between *a* and *b* and common immediate subdirectories." +msgstr "" + +#: ../../library/filecmp.rst:101 +msgid "" +"Print a comparison between *a* and *b* and common subdirectories " +"(recursively)." +msgstr "" + +#: ../../library/filecmp.rst:104 +msgid "" +"The :class:`dircmp` class offers a number of interesting attributes that may " +"be used to get various bits of information about the directory trees being " +"compared." +msgstr "" + +#: ../../library/filecmp.rst:108 +msgid "" +"Note that via :meth:`~object.__getattr__` hooks, all attributes are computed " +"lazily, so there is no speed penalty if only those attributes which are " +"lightweight to compute are used." +msgstr "" + +#: ../../library/filecmp.rst:115 +msgid "The directory *a*." +msgstr "" + +#: ../../library/filecmp.rst:120 +msgid "The directory *b*." +msgstr "" + +#: ../../library/filecmp.rst:125 +msgid "Files and subdirectories in *a*, filtered by *hide* and *ignore*." +msgstr "" + +#: ../../library/filecmp.rst:130 +msgid "Files and subdirectories in *b*, filtered by *hide* and *ignore*." +msgstr "" + +#: ../../library/filecmp.rst:135 +msgid "Files and subdirectories in both *a* and *b*." +msgstr "" + +#: ../../library/filecmp.rst:140 +msgid "Files and subdirectories only in *a*." +msgstr "" + +#: ../../library/filecmp.rst:145 +msgid "Files and subdirectories only in *b*." +msgstr "" + +#: ../../library/filecmp.rst:150 +msgid "Subdirectories in both *a* and *b*." +msgstr "" + +#: ../../library/filecmp.rst:155 +msgid "Files in both *a* and *b*." +msgstr "" + +#: ../../library/filecmp.rst:160 +msgid "" +"Names in both *a* and *b*, such that the type differs between the " +"directories, or names for which :func:`os.stat` reports an error." +msgstr "" + +#: ../../library/filecmp.rst:166 +msgid "" +"Files which are identical in both *a* and *b*, using the class's file " +"comparison operator." +msgstr "" + +#: ../../library/filecmp.rst:172 +msgid "" +"Files which are in both *a* and *b*, whose contents differ according to the " +"class's file comparison operator." +msgstr "" + +#: ../../library/filecmp.rst:178 +msgid "Files which are in both *a* and *b*, but could not be compared." +msgstr "" + +#: ../../library/filecmp.rst:183 +msgid "" +"A dictionary mapping names in :attr:`common_dirs` to :class:`dircmp` " +"instances (or MyDirCmp instances if this instance is of type MyDirCmp, a " +"subclass of :class:`dircmp`)." +msgstr "" + +#: ../../library/filecmp.rst:187 +msgid "" +"Previously entries were always :class:`dircmp` instances. Now entries are " +"the same type as *self*, if *self* is a subclass of :class:`dircmp`." +msgstr "" + +#: ../../library/filecmp.rst:196 +msgid "List of directories ignored by :class:`dircmp` by default." +msgstr "" + +#: ../../library/filecmp.rst:199 +msgid "" +"Here is a simplified example of using the ``subdirs`` attribute to search " +"recursively through two directories to show common different files::" +msgstr "" + +#: ../../library/filecmp.rst:202 +msgid "" +">>> from filecmp import dircmp\n" +">>> def print_diff_files(dcmp):\n" +"... for name in dcmp.diff_files:\n" +"... print(\"diff_file %s found in %s and %s\" % (name, dcmp.left,\n" +"... dcmp.right))\n" +"... for sub_dcmp in dcmp.subdirs.values():\n" +"... print_diff_files(sub_dcmp)\n" +"...\n" +">>> dcmp = dircmp('dir1', 'dir2')\n" +">>> print_diff_files(dcmp)" +msgstr "" +">>> from filecmp import dircmp\n" +">>> def print_diff_files(dcmp):\n" +"... for name in dcmp.diff_files:\n" +"... print(\"diff_file %s found in %s and %s\" % (name, dcmp.left,\n" +"... dcmp.right))\n" +"... for sub_dcmp in dcmp.subdirs.values():\n" +"... print_diff_files(sub_dcmp)\n" +"...\n" +">>> dcmp = dircmp('dir1', 'dir2')\n" +">>> print_diff_files(dcmp)" diff --git a/library/fileformats.po b/library/fileformats.po index 03c53fa5e1..759276d229 100644 --- a/library/fileformats.po +++ b/library/fileformats.po @@ -1,31 +1,31 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Leon H., 2017 -# Weilin Du, 2025 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2018-06-26 18:54+0800\n" -"PO-Revision-Date: 2025-06-28 00:51+0800\n" -"Last-Translator: Weilin Du\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/fileformats.rst:5 -msgid "File Formats" -msgstr "檔案格式" - -#: ../../library/fileformats.rst:7 -msgid "" -"The modules described in this chapter parse various miscellaneous file " -"formats that aren't markup languages and are not related to e-mail." -msgstr "" -"本章所描述的模組會剖析各種非標記類型語言且與電子郵件無關的雜項檔案格式。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Leon H., 2017 +# Weilin Du, 2025 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2018-06-26 18:54+0800\n" +"PO-Revision-Date: 2025-06-28 00:51+0800\n" +"Last-Translator: Weilin Du\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/fileformats.rst:5 +msgid "File Formats" +msgstr "檔案格式" + +#: ../../library/fileformats.rst:7 +msgid "" +"The modules described in this chapter parse various miscellaneous file " +"formats that aren't markup languages and are not related to e-mail." +msgstr "" +"本章所描述的模組會剖析各種非標記類型語言且與電子郵件無關的雜項檔案格式。" diff --git a/library/fileinput.po b/library/fileinput.po index 377e861870..d2701ac426 100644 --- a/library/fileinput.po +++ b/library/fileinput.po @@ -1,328 +1,328 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-09-01 22:24+0800\n" -"PO-Revision-Date: 2018-05-23 16:01+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/fileinput.rst:2 -msgid ":mod:`!fileinput` --- Iterate over lines from multiple input streams" -msgstr ":mod:`!fileinput` --- 逐列疊代多個輸入串流" - -#: ../../library/fileinput.rst:10 -msgid "**Source code:** :source:`Lib/fileinput.py`" -msgstr "**原始碼：**\\ :source:`Lib/fileinput.py`" - -#: ../../library/fileinput.rst:14 -msgid "" -"This module implements a helper class and functions to quickly write a loop " -"over standard input or a list of files. If you just want to read or write " -"one file see :func:`open`." -msgstr "" - -#: ../../library/fileinput.rst:18 -msgid "The typical use is::" -msgstr "" - -#: ../../library/fileinput.rst:20 -msgid "" -"import fileinput\n" -"for line in fileinput.input(encoding=\"utf-8\"):\n" -" process(line)" -msgstr "" -"import fileinput\n" -"for line in fileinput.input(encoding=\"utf-8\"):\n" -" process(line)" - -#: ../../library/fileinput.rst:24 -msgid "" -"This iterates over the lines of all files listed in ``sys.argv[1:]``, " -"defaulting to ``sys.stdin`` if the list is empty. If a filename is ``'-'``, " -"it is also replaced by ``sys.stdin`` and the optional arguments *mode* and " -"*openhook* are ignored. To specify an alternative list of filenames, pass " -"it as the first argument to :func:`.input`. A single file name is also " -"allowed." -msgstr "" - -#: ../../library/fileinput.rst:30 -msgid "" -"All files are opened in text mode by default, but you can override this by " -"specifying the *mode* parameter in the call to :func:`.input` or :class:" -"`FileInput`. If an I/O error occurs during opening or reading a file, :exc:" -"`OSError` is raised." -msgstr "" - -#: ../../library/fileinput.rst:35 -msgid ":exc:`IOError` used to be raised; it is now an alias of :exc:`OSError`." -msgstr ":exc:`IOError` 曾經被引發；現在它是一個 :exc:`OSError` 的別名。" - -#: ../../library/fileinput.rst:38 -msgid "" -"If ``sys.stdin`` is used more than once, the second and further use will " -"return no lines, except perhaps for interactive use, or if it has been " -"explicitly reset (e.g. using ``sys.stdin.seek(0)``)." -msgstr "" - -#: ../../library/fileinput.rst:42 -msgid "" -"Empty files are opened and immediately closed; the only time their presence " -"in the list of filenames is noticeable at all is when the last file opened " -"is empty." -msgstr "" - -#: ../../library/fileinput.rst:46 -msgid "" -"Lines are returned with any newlines intact, which means that the last line " -"in a file may not have one." -msgstr "" - -#: ../../library/fileinput.rst:49 -msgid "" -"You can control how files are opened by providing an opening hook via the " -"*openhook* parameter to :func:`fileinput.input` or :func:`FileInput`. The " -"hook must be a function that takes two arguments, *filename* and *mode*, and " -"returns an accordingly opened file-like object. If *encoding* and/or " -"*errors* are specified, they will be passed to the hook as additional " -"keyword arguments. This module provides a :func:`hook_compressed` to support " -"compressed files." -msgstr "" - -#: ../../library/fileinput.rst:56 -msgid "The following function is the primary interface of this module:" -msgstr "" - -#: ../../library/fileinput.rst:61 -msgid "" -"Create an instance of the :class:`FileInput` class. The instance will be " -"used as global state for the functions of this module, and is also returned " -"to use during iteration. The parameters to this function will be passed " -"along to the constructor of the :class:`FileInput` class." -msgstr "" - -#: ../../library/fileinput.rst:66 -msgid "" -"The :class:`FileInput` instance can be used as a context manager in the :" -"keyword:`with` statement. In this example, *input* is closed after the :" -"keyword:`!with` statement is exited, even if an exception occurs::" -msgstr "" - -#: ../../library/fileinput.rst:70 -msgid "" -"with fileinput.input(files=('spam.txt', 'eggs.txt'), encoding=\"utf-8\") as " -"f:\n" -" for line in f:\n" -" process(line)" -msgstr "" -"with fileinput.input(files=('spam.txt', 'eggs.txt'), encoding=\"utf-8\") as " -"f:\n" -" for line in f:\n" -" process(line)" - -#: ../../library/fileinput.rst:74 ../../library/fileinput.rst:170 -msgid "Can be used as a context manager." -msgstr "" - -#: ../../library/fileinput.rst:77 -msgid "The keyword parameters *mode* and *openhook* are now keyword-only." -msgstr "" - -#: ../../library/fileinput.rst:80 ../../library/fileinput.rst:176 -#: ../../library/fileinput.rst:210 -msgid "The keyword-only parameter *encoding* and *errors* are added." -msgstr "" - -#: ../../library/fileinput.rst:84 -msgid "" -"The following functions use the global state created by :func:`fileinput." -"input`; if there is no active state, :exc:`RuntimeError` is raised." -msgstr "" - -#: ../../library/fileinput.rst:90 -msgid "" -"Return the name of the file currently being read. Before the first line has " -"been read, returns ``None``." -msgstr "" - -#: ../../library/fileinput.rst:96 -msgid "" -"Return the integer \"file descriptor\" for the current file. When no file is " -"opened (before the first line and between files), returns ``-1``." -msgstr "" - -#: ../../library/fileinput.rst:102 -msgid "" -"Return the cumulative line number of the line that has just been read. " -"Before the first line has been read, returns ``0``. After the last line of " -"the last file has been read, returns the line number of that line." -msgstr "" - -#: ../../library/fileinput.rst:109 -msgid "" -"Return the line number in the current file. Before the first line has been " -"read, returns ``0``. After the last line of the last file has been read, " -"returns the line number of that line within the file." -msgstr "" - -#: ../../library/fileinput.rst:116 -msgid "" -"Return ``True`` if the line just read is the first line of its file, " -"otherwise return ``False``." -msgstr "" - -#: ../../library/fileinput.rst:122 -msgid "" -"Return ``True`` if the last line was read from ``sys.stdin``, otherwise " -"return ``False``." -msgstr "" - -#: ../../library/fileinput.rst:128 -msgid "" -"Close the current file so that the next iteration will read the first line " -"from the next file (if any); lines not read from the file will not count " -"towards the cumulative line count. The filename is not changed until after " -"the first line of the next file has been read. Before the first line has " -"been read, this function has no effect; it cannot be used to skip the first " -"file. After the last line of the last file has been read, this function has " -"no effect." -msgstr "" - -#: ../../library/fileinput.rst:138 -msgid "Close the sequence." -msgstr "" - -#: ../../library/fileinput.rst:140 -msgid "" -"The class which implements the sequence behavior provided by the module is " -"available for subclassing as well:" -msgstr "" - -#: ../../library/fileinput.rst:146 -msgid "" -"Class :class:`FileInput` is the implementation; its methods :meth:" -"`filename`, :meth:`fileno`, :meth:`lineno`, :meth:`filelineno`, :meth:" -"`isfirstline`, :meth:`isstdin`, :meth:`nextfile` and :meth:`close` " -"correspond to the functions of the same name in the module. In addition it " -"is :term:`iterable` and has a :meth:`~io.TextIOBase.readline` method which " -"returns the next input line. The sequence must be accessed in strictly " -"sequential order; random access and :meth:`~io.TextIOBase.readline` cannot " -"be mixed." -msgstr "" - -#: ../../library/fileinput.rst:154 -msgid "" -"With *mode* you can specify which file mode will be passed to :func:`open`. " -"It must be one of ``'r'`` and ``'rb'``." -msgstr "" - -#: ../../library/fileinput.rst:157 -msgid "" -"The *openhook*, when given, must be a function that takes two arguments, " -"*filename* and *mode*, and returns an accordingly opened file-like object. " -"You cannot use *inplace* and *openhook* together." -msgstr "" - -#: ../../library/fileinput.rst:161 -msgid "" -"You can specify *encoding* and *errors* that is passed to :func:`open` or " -"*openhook*." -msgstr "" - -#: ../../library/fileinput.rst:163 -msgid "" -"A :class:`FileInput` instance can be used as a context manager in the :" -"keyword:`with` statement. In this example, *input* is closed after the :" -"keyword:`!with` statement is exited, even if an exception occurs::" -msgstr "" - -#: ../../library/fileinput.rst:167 -msgid "" -"with FileInput(files=('spam.txt', 'eggs.txt')) as input:\n" -" process(input)" -msgstr "" -"with FileInput(files=('spam.txt', 'eggs.txt')) as input:\n" -" process(input)" - -#: ../../library/fileinput.rst:173 -msgid "The keyword parameter *mode* and *openhook* are now keyword-only." -msgstr "" - -#: ../../library/fileinput.rst:179 -msgid "" -"The ``'rU'`` and ``'U'`` modes and the :meth:`!__getitem__` method have been " -"removed." -msgstr "" - -#: ../../library/fileinput.rst:184 -msgid "" -"**Optional in-place filtering:** if the keyword argument ``inplace=True`` is " -"passed to :func:`fileinput.input` or to the :class:`FileInput` constructor, " -"the file is moved to a backup file and standard output is directed to the " -"input file (if a file of the same name as the backup file already exists, it " -"will be replaced silently). This makes it possible to write a filter that " -"rewrites its input file in place. If the *backup* parameter is given " -"(typically as ``backup='.'``), it specifies the extension " -"for the backup file, and the backup file remains around; by default, the " -"extension is ``'.bak'`` and it is deleted when the output file is closed. " -"In-place filtering is disabled when standard input is read." -msgstr "" - -#: ../../library/fileinput.rst:196 -msgid "The two following opening hooks are provided by this module:" -msgstr "" - -#: ../../library/fileinput.rst:200 -msgid "" -"Transparently opens files compressed with gzip and bzip2 (recognized by the " -"extensions ``'.gz'`` and ``'.bz2'``) using the :mod:`gzip` and :mod:`bz2` " -"modules. If the filename extension is not ``'.gz'`` or ``'.bz2'``, the file " -"is opened normally (ie, using :func:`open` without any decompression)." -msgstr "" - -#: ../../library/fileinput.rst:205 -msgid "" -"The *encoding* and *errors* values are passed to :class:`io.TextIOWrapper` " -"for compressed files and open for normal files." -msgstr "" - -#: ../../library/fileinput.rst:208 -msgid "" -"Usage example: ``fi = fileinput.FileInput(openhook=fileinput." -"hook_compressed, encoding=\"utf-8\")``" -msgstr "" - -#: ../../library/fileinput.rst:216 -msgid "" -"Returns a hook which opens each file with :func:`open`, using the given " -"*encoding* and *errors* to read the file." -msgstr "" - -#: ../../library/fileinput.rst:219 -msgid "" -"Usage example: ``fi = fileinput.FileInput(openhook=fileinput." -"hook_encoded(\"utf-8\", \"surrogateescape\"))``" -msgstr "" - -#: ../../library/fileinput.rst:223 -msgid "Added the optional *errors* parameter." -msgstr "新增可選參數 *errors*。" - -#: ../../library/fileinput.rst:226 -msgid "" -"This function is deprecated since :func:`fileinput.input` and :class:" -"`FileInput` now have *encoding* and *errors* parameters." -msgstr "" - -#~ msgid "The ``'rU'`` and ``'U'`` modes." -#~ msgstr "``'rU'`` 和 ``'U'`` 模式。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-09-01 22:24+0800\n" +"PO-Revision-Date: 2018-05-23 16:01+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/fileinput.rst:2 +msgid ":mod:`!fileinput` --- Iterate over lines from multiple input streams" +msgstr ":mod:`!fileinput` --- 逐列疊代多個輸入串流" + +#: ../../library/fileinput.rst:10 +msgid "**Source code:** :source:`Lib/fileinput.py`" +msgstr "**原始碼：**\\ :source:`Lib/fileinput.py`" + +#: ../../library/fileinput.rst:14 +msgid "" +"This module implements a helper class and functions to quickly write a loop " +"over standard input or a list of files. If you just want to read or write " +"one file see :func:`open`." +msgstr "" + +#: ../../library/fileinput.rst:18 +msgid "The typical use is::" +msgstr "" + +#: ../../library/fileinput.rst:20 +msgid "" +"import fileinput\n" +"for line in fileinput.input(encoding=\"utf-8\"):\n" +" process(line)" +msgstr "" +"import fileinput\n" +"for line in fileinput.input(encoding=\"utf-8\"):\n" +" process(line)" + +#: ../../library/fileinput.rst:24 +msgid "" +"This iterates over the lines of all files listed in ``sys.argv[1:]``, " +"defaulting to ``sys.stdin`` if the list is empty. If a filename is ``'-'``, " +"it is also replaced by ``sys.stdin`` and the optional arguments *mode* and " +"*openhook* are ignored. To specify an alternative list of filenames, pass " +"it as the first argument to :func:`.input`. A single file name is also " +"allowed." +msgstr "" + +#: ../../library/fileinput.rst:30 +msgid "" +"All files are opened in text mode by default, but you can override this by " +"specifying the *mode* parameter in the call to :func:`.input` or :class:" +"`FileInput`. If an I/O error occurs during opening or reading a file, :exc:" +"`OSError` is raised." +msgstr "" + +#: ../../library/fileinput.rst:35 +msgid ":exc:`IOError` used to be raised; it is now an alias of :exc:`OSError`." +msgstr ":exc:`IOError` 曾經被引發；現在它是一個 :exc:`OSError` 的別名。" + +#: ../../library/fileinput.rst:38 +msgid "" +"If ``sys.stdin`` is used more than once, the second and further use will " +"return no lines, except perhaps for interactive use, or if it has been " +"explicitly reset (e.g. using ``sys.stdin.seek(0)``)." +msgstr "" + +#: ../../library/fileinput.rst:42 +msgid "" +"Empty files are opened and immediately closed; the only time their presence " +"in the list of filenames is noticeable at all is when the last file opened " +"is empty." +msgstr "" + +#: ../../library/fileinput.rst:46 +msgid "" +"Lines are returned with any newlines intact, which means that the last line " +"in a file may not have one." +msgstr "" + +#: ../../library/fileinput.rst:49 +msgid "" +"You can control how files are opened by providing an opening hook via the " +"*openhook* parameter to :func:`fileinput.input` or :func:`FileInput`. The " +"hook must be a function that takes two arguments, *filename* and *mode*, and " +"returns an accordingly opened file-like object. If *encoding* and/or " +"*errors* are specified, they will be passed to the hook as additional " +"keyword arguments. This module provides a :func:`hook_compressed` to support " +"compressed files." +msgstr "" + +#: ../../library/fileinput.rst:56 +msgid "The following function is the primary interface of this module:" +msgstr "" + +#: ../../library/fileinput.rst:61 +msgid "" +"Create an instance of the :class:`FileInput` class. The instance will be " +"used as global state for the functions of this module, and is also returned " +"to use during iteration. The parameters to this function will be passed " +"along to the constructor of the :class:`FileInput` class." +msgstr "" + +#: ../../library/fileinput.rst:66 +msgid "" +"The :class:`FileInput` instance can be used as a context manager in the :" +"keyword:`with` statement. In this example, *input* is closed after the :" +"keyword:`!with` statement is exited, even if an exception occurs::" +msgstr "" + +#: ../../library/fileinput.rst:70 +msgid "" +"with fileinput.input(files=('spam.txt', 'eggs.txt'), encoding=\"utf-8\") as " +"f:\n" +" for line in f:\n" +" process(line)" +msgstr "" +"with fileinput.input(files=('spam.txt', 'eggs.txt'), encoding=\"utf-8\") as " +"f:\n" +" for line in f:\n" +" process(line)" + +#: ../../library/fileinput.rst:74 ../../library/fileinput.rst:170 +msgid "Can be used as a context manager." +msgstr "" + +#: ../../library/fileinput.rst:77 +msgid "The keyword parameters *mode* and *openhook* are now keyword-only." +msgstr "" + +#: ../../library/fileinput.rst:80 ../../library/fileinput.rst:176 +#: ../../library/fileinput.rst:210 +msgid "The keyword-only parameter *encoding* and *errors* are added." +msgstr "" + +#: ../../library/fileinput.rst:84 +msgid "" +"The following functions use the global state created by :func:`fileinput." +"input`; if there is no active state, :exc:`RuntimeError` is raised." +msgstr "" + +#: ../../library/fileinput.rst:90 +msgid "" +"Return the name of the file currently being read. Before the first line has " +"been read, returns ``None``." +msgstr "" + +#: ../../library/fileinput.rst:96 +msgid "" +"Return the integer \"file descriptor\" for the current file. When no file is " +"opened (before the first line and between files), returns ``-1``." +msgstr "" + +#: ../../library/fileinput.rst:102 +msgid "" +"Return the cumulative line number of the line that has just been read. " +"Before the first line has been read, returns ``0``. After the last line of " +"the last file has been read, returns the line number of that line." +msgstr "" + +#: ../../library/fileinput.rst:109 +msgid "" +"Return the line number in the current file. Before the first line has been " +"read, returns ``0``. After the last line of the last file has been read, " +"returns the line number of that line within the file." +msgstr "" + +#: ../../library/fileinput.rst:116 +msgid "" +"Return ``True`` if the line just read is the first line of its file, " +"otherwise return ``False``." +msgstr "" + +#: ../../library/fileinput.rst:122 +msgid "" +"Return ``True`` if the last line was read from ``sys.stdin``, otherwise " +"return ``False``." +msgstr "" + +#: ../../library/fileinput.rst:128 +msgid "" +"Close the current file so that the next iteration will read the first line " +"from the next file (if any); lines not read from the file will not count " +"towards the cumulative line count. The filename is not changed until after " +"the first line of the next file has been read. Before the first line has " +"been read, this function has no effect; it cannot be used to skip the first " +"file. After the last line of the last file has been read, this function has " +"no effect." +msgstr "" + +#: ../../library/fileinput.rst:138 +msgid "Close the sequence." +msgstr "" + +#: ../../library/fileinput.rst:140 +msgid "" +"The class which implements the sequence behavior provided by the module is " +"available for subclassing as well:" +msgstr "" + +#: ../../library/fileinput.rst:146 +msgid "" +"Class :class:`FileInput` is the implementation; its methods :meth:" +"`filename`, :meth:`fileno`, :meth:`lineno`, :meth:`filelineno`, :meth:" +"`isfirstline`, :meth:`isstdin`, :meth:`nextfile` and :meth:`close` " +"correspond to the functions of the same name in the module. In addition it " +"is :term:`iterable` and has a :meth:`~io.TextIOBase.readline` method which " +"returns the next input line. The sequence must be accessed in strictly " +"sequential order; random access and :meth:`~io.TextIOBase.readline` cannot " +"be mixed." +msgstr "" + +#: ../../library/fileinput.rst:154 +msgid "" +"With *mode* you can specify which file mode will be passed to :func:`open`. " +"It must be one of ``'r'`` and ``'rb'``." +msgstr "" + +#: ../../library/fileinput.rst:157 +msgid "" +"The *openhook*, when given, must be a function that takes two arguments, " +"*filename* and *mode*, and returns an accordingly opened file-like object. " +"You cannot use *inplace* and *openhook* together." +msgstr "" + +#: ../../library/fileinput.rst:161 +msgid "" +"You can specify *encoding* and *errors* that is passed to :func:`open` or " +"*openhook*." +msgstr "" + +#: ../../library/fileinput.rst:163 +msgid "" +"A :class:`FileInput` instance can be used as a context manager in the :" +"keyword:`with` statement. In this example, *input* is closed after the :" +"keyword:`!with` statement is exited, even if an exception occurs::" +msgstr "" + +#: ../../library/fileinput.rst:167 +msgid "" +"with FileInput(files=('spam.txt', 'eggs.txt')) as input:\n" +" process(input)" +msgstr "" +"with FileInput(files=('spam.txt', 'eggs.txt')) as input:\n" +" process(input)" + +#: ../../library/fileinput.rst:173 +msgid "The keyword parameter *mode* and *openhook* are now keyword-only." +msgstr "" + +#: ../../library/fileinput.rst:179 +msgid "" +"The ``'rU'`` and ``'U'`` modes and the :meth:`!__getitem__` method have been " +"removed." +msgstr "" + +#: ../../library/fileinput.rst:184 +msgid "" +"**Optional in-place filtering:** if the keyword argument ``inplace=True`` is " +"passed to :func:`fileinput.input` or to the :class:`FileInput` constructor, " +"the file is moved to a backup file and standard output is directed to the " +"input file (if a file of the same name as the backup file already exists, it " +"will be replaced silently). This makes it possible to write a filter that " +"rewrites its input file in place. If the *backup* parameter is given " +"(typically as ``backup='.'``), it specifies the extension " +"for the backup file, and the backup file remains around; by default, the " +"extension is ``'.bak'`` and it is deleted when the output file is closed. " +"In-place filtering is disabled when standard input is read." +msgstr "" + +#: ../../library/fileinput.rst:196 +msgid "The two following opening hooks are provided by this module:" +msgstr "" + +#: ../../library/fileinput.rst:200 +msgid "" +"Transparently opens files compressed with gzip and bzip2 (recognized by the " +"extensions ``'.gz'`` and ``'.bz2'``) using the :mod:`gzip` and :mod:`bz2` " +"modules. If the filename extension is not ``'.gz'`` or ``'.bz2'``, the file " +"is opened normally (ie, using :func:`open` without any decompression)." +msgstr "" + +#: ../../library/fileinput.rst:205 +msgid "" +"The *encoding* and *errors* values are passed to :class:`io.TextIOWrapper` " +"for compressed files and open for normal files." +msgstr "" + +#: ../../library/fileinput.rst:208 +msgid "" +"Usage example: ``fi = fileinput.FileInput(openhook=fileinput." +"hook_compressed, encoding=\"utf-8\")``" +msgstr "" + +#: ../../library/fileinput.rst:216 +msgid "" +"Returns a hook which opens each file with :func:`open`, using the given " +"*encoding* and *errors* to read the file." +msgstr "" + +#: ../../library/fileinput.rst:219 +msgid "" +"Usage example: ``fi = fileinput.FileInput(openhook=fileinput." +"hook_encoded(\"utf-8\", \"surrogateescape\"))``" +msgstr "" + +#: ../../library/fileinput.rst:223 +msgid "Added the optional *errors* parameter." +msgstr "新增可選參數 *errors*。" + +#: ../../library/fileinput.rst:226 +msgid "" +"This function is deprecated since :func:`fileinput.input` and :class:" +"`FileInput` now have *encoding* and *errors* parameters." +msgstr "" + +#~ msgid "The ``'rU'`` and ``'U'`` modes." +#~ msgstr "``'rU'`` 和 ``'U'`` 模式。" diff --git a/library/filesys.po b/library/filesys.po index f3eff555d9..f4519eea0c 100644 --- a/library/filesys.po +++ b/library/filesys.po @@ -1,68 +1,68 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Leon H., 2017 -# Allen Wu , 2021 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-12-29 11:18+0000\n" -"PO-Revision-Date: 2021-11-22 20:13+0800\n" -"Last-Translator: Allen Wu \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" -"X-Generator: Poedit 3.0\n" - -#: ../../library/filesys.rst:5 -msgid "File and Directory Access" -msgstr "檔案與目錄存取" - -#: ../../library/filesys.rst:7 -msgid "" -"The modules described in this chapter deal with disk files and directories. " -"For example, there are modules for reading the properties of files, " -"manipulating paths in a portable way, and creating temporary files. The " -"full list of modules in this chapter is:" -msgstr "" -"本章中描述的 module（模組）用於處理硬碟檔案和目錄。例如，有一些 module 用於讀" -"取檔案的屬性、以可攜 (portable) 方式操作路徑以及建立暫存檔。本章中的完整 " -"module 清單是：" - -#: ../../library/filesys.rst:28 -msgid "Module :mod:`os`" -msgstr "Module :mod:`os`" - -#: ../../library/filesys.rst:29 -msgid "" -"Operating system interfaces, including functions to work with files at a " -"lower level than Python :term:`file objects `." -msgstr "" -"作業系統介面，包括處理比 Python :term:`檔案物件 `\\ 更低階檔案的" -"函式。" - -#: ../../library/filesys.rst:32 -msgid "Module :mod:`io`" -msgstr "Module :mod:`io`" - -#: ../../library/filesys.rst:33 -msgid "" -"Python's built-in I/O library, including both abstract classes and some " -"concrete classes such as file I/O." -msgstr "" -"Python 的內建 I/O 函式庫，包含抽象類別和一些具體類別 (concrete class)，如檔" -"案 I/O。" - -#: ../../library/filesys.rst:36 -msgid "Built-in function :func:`open`" -msgstr "內建函式 :func:`open`" - -#: ../../library/filesys.rst:37 -msgid "The standard way to open files for reading and writing with Python." -msgstr "使用 Python 打開檔案以進行讀寫檔案的標準方法。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Leon H., 2017 +# Allen Wu , 2021 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-12-29 11:18+0000\n" +"PO-Revision-Date: 2021-11-22 20:13+0800\n" +"Last-Translator: Allen Wu \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" +"X-Generator: Poedit 3.0\n" + +#: ../../library/filesys.rst:5 +msgid "File and Directory Access" +msgstr "檔案與目錄存取" + +#: ../../library/filesys.rst:7 +msgid "" +"The modules described in this chapter deal with disk files and directories. " +"For example, there are modules for reading the properties of files, " +"manipulating paths in a portable way, and creating temporary files. The " +"full list of modules in this chapter is:" +msgstr "" +"本章中描述的 module（模組）用於處理硬碟檔案和目錄。例如，有一些 module 用於讀" +"取檔案的屬性、以可攜 (portable) 方式操作路徑以及建立暫存檔。本章中的完整 " +"module 清單是：" + +#: ../../library/filesys.rst:28 +msgid "Module :mod:`os`" +msgstr "Module :mod:`os`" + +#: ../../library/filesys.rst:29 +msgid "" +"Operating system interfaces, including functions to work with files at a " +"lower level than Python :term:`file objects `." +msgstr "" +"作業系統介面，包括處理比 Python :term:`檔案物件 `\\ 更低階檔案的" +"函式。" + +#: ../../library/filesys.rst:32 +msgid "Module :mod:`io`" +msgstr "Module :mod:`io`" + +#: ../../library/filesys.rst:33 +msgid "" +"Python's built-in I/O library, including both abstract classes and some " +"concrete classes such as file I/O." +msgstr "" +"Python 的內建 I/O 函式庫，包含抽象類別和一些具體類別 (concrete class)，如檔" +"案 I/O。" + +#: ../../library/filesys.rst:36 +msgid "Built-in function :func:`open`" +msgstr "內建函式 :func:`open`" + +#: ../../library/filesys.rst:37 +msgid "The standard way to open files for reading and writing with Python." +msgstr "使用 Python 打開檔案以進行讀寫檔案的標準方法。" diff --git a/library/fnmatch.po b/library/fnmatch.po index 5c17ff5a54..897ba17634 100644 --- a/library/fnmatch.po +++ b/library/fnmatch.po @@ -1,218 +1,218 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: 2018-05-23 16:02+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/fnmatch.rst:2 -msgid ":mod:`!fnmatch` --- Unix filename pattern matching" -msgstr ":mod:`!fnmatch` --- Unix 檔案名稱模式比對" - -#: ../../library/fnmatch.rst:7 -msgid "**Source code:** :source:`Lib/fnmatch.py`" -msgstr "**原始碼：**\\ :source:`Lib/fnmatch.py`" - -#: ../../library/fnmatch.rst:15 -msgid "" -"This module provides support for Unix shell-style wildcards, which are *not* " -"the same as regular expressions (which are documented in the :mod:`re` " -"module). The special characters used in shell-style wildcards are:" -msgstr "" - -#: ../../library/fnmatch.rst:27 -msgid "Pattern" -msgstr "" - -#: ../../library/fnmatch.rst:27 -msgid "Meaning" -msgstr "含義" - -#: ../../library/fnmatch.rst:29 -msgid "``*``" -msgstr "``*``" - -#: ../../library/fnmatch.rst:29 -msgid "matches everything" -msgstr "" - -#: ../../library/fnmatch.rst:31 -msgid "``?``" -msgstr "``?``" - -#: ../../library/fnmatch.rst:31 -msgid "matches any single character" -msgstr "" - -#: ../../library/fnmatch.rst:33 -msgid "``[seq]``" -msgstr "``[seq]``" - -#: ../../library/fnmatch.rst:33 -msgid "matches any character in *seq*" -msgstr "" - -#: ../../library/fnmatch.rst:35 -msgid "``[!seq]``" -msgstr "``[!seq]``" - -#: ../../library/fnmatch.rst:35 -msgid "matches any character not in *seq*" -msgstr "" - -#: ../../library/fnmatch.rst:38 -msgid "" -"For a literal match, wrap the meta-characters in brackets. For example, " -"``'[?]'`` matches the character ``'?'``." -msgstr "" - -#: ../../library/fnmatch.rst:43 -msgid "" -"Note that the filename separator (``'/'`` on Unix) is *not* special to this " -"module. See module :mod:`glob` for pathname expansion (:mod:`glob` " -"uses :func:`.filter` to match pathname segments). Similarly, filenames " -"starting with a period are not special for this module, and are matched by " -"the ``*`` and ``?`` patterns." -msgstr "" - -#: ../../library/fnmatch.rst:49 -msgid "" -"Unless stated otherwise, \"filename string\" and \"pattern string\" either " -"refer to :class:`str` or ``ISO-8859-1`` encoded :class:`bytes` objects. Note " -"that the functions documented below do not allow to mix a :class:`!bytes` " -"pattern with a :class:`!str` filename, and vice-versa." -msgstr "" - -#: ../../library/fnmatch.rst:54 -msgid "" -"Finally, note that :func:`functools.lru_cache` with a *maxsize* of 32768 is " -"used to cache the (typed) compiled regex patterns in the following " -"functions: :func:`fnmatch`, :func:`fnmatchcase`, :func:`.filter`, :func:`.filterfalse`." -msgstr "" - -#: ../../library/fnmatch.rst:61 -msgid "" -"Test whether the filename string *name* matches the pattern string *pat*, " -"returning ``True`` or ``False``. Both parameters are case-normalized " -"using :func:`os.path.normcase`. :func:`fnmatchcase` can be used to perform a " -"case-sensitive comparison, regardless of whether that's standard for the " -"operating system." -msgstr "" - -#: ../../library/fnmatch.rst:67 -msgid "" -"This example will print all file names in the current directory with the " -"extension ``.txt``::" -msgstr "" - -#: ../../library/fnmatch.rst:70 -msgid "" -"import fnmatch\n" -"import os\n" -"\n" -"for file in os.listdir('.'):\n" -" if fnmatch.fnmatch(file, '*.txt'):\n" -" print(file)" -msgstr "" -"import fnmatch\n" -"import os\n" -"\n" -"for file in os.listdir('.'):\n" -" if fnmatch.fnmatch(file, '*.txt'):\n" -" print(file)" - -#: ../../library/fnmatch.rst:80 -msgid "" -"Test whether the filename string *name* matches the pattern string *pat*, " -"returning ``True`` or ``False``; the comparison is case-sensitive and does " -"not apply :func:`os.path.normcase`." -msgstr "" - -#: ../../library/fnmatch.rst:87 -msgid "" -"Construct a list from those elements of the :term:`iterable` of filename " -"strings *names* that match the pattern string *pat*. It is the same as ``[n " -"for n in names if fnmatch(n, pat)]``, but implemented more efficiently." -msgstr "" - -#: ../../library/fnmatch.rst:95 -msgid "" -"Construct a list from those elements of the :term:`iterable` of filename " -"strings *names* that do not match the pattern string *pat*. It is the same " -"as ``[n for n in names if not fnmatch(n, pat)]``, but implemented more " -"efficiently." -msgstr "" - -#: ../../library/fnmatch.rst:105 -msgid "" -"Return the shell-style pattern *pat* converted to a regular expression for " -"using with :func:`re.match`. The pattern is expected to be a :class:`str`." -msgstr "" - -#: ../../library/fnmatch.rst:108 -msgid "Example:" -msgstr "範例：" - -#: ../../library/fnmatch.rst:122 -msgid "Module :mod:`glob`" -msgstr ":mod:`glob` 模組" - -#: ../../library/fnmatch.rst:123 -msgid "Unix shell-style path expansion." -msgstr "" - -#: ../../library/fnmatch.rst:9 -msgid "filenames" -msgstr "filenames（檔案名稱）" - -#: ../../library/fnmatch.rst:9 -msgid "wildcard expansion" -msgstr "wildcard expansion（萬用字元展開）" - -#: ../../library/fnmatch.rst:11 ../../library/fnmatch.rst:41 -msgid "module" -msgstr "module（模組）" - -#: ../../library/fnmatch.rst:11 -msgid "re" -msgstr "re" - -#: ../../library/fnmatch.rst:19 -msgid "* (asterisk)" -msgstr "* （星號）" - -#: ../../library/fnmatch.rst:19 -msgid "in glob-style wildcards" -msgstr "於 glob 風格的萬用字元中" - -#: ../../library/fnmatch.rst:19 -msgid "? (question mark)" -msgstr "? （問號）" - -#: ../../library/fnmatch.rst:19 -msgid "[] (square brackets)" -msgstr "[] （方括號）" - -#: ../../library/fnmatch.rst:19 -msgid "! (exclamation)" -msgstr "! （驚嘆號）" - -#: ../../library/fnmatch.rst:19 -msgid "- (minus)" -msgstr "- （減號）" - -#: ../../library/fnmatch.rst:41 -msgid "glob" -msgstr "glob" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: 2018-05-23 16:02+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/fnmatch.rst:2 +msgid ":mod:`!fnmatch` --- Unix filename pattern matching" +msgstr ":mod:`!fnmatch` --- Unix 檔案名稱模式比對" + +#: ../../library/fnmatch.rst:7 +msgid "**Source code:** :source:`Lib/fnmatch.py`" +msgstr "**原始碼：**\\ :source:`Lib/fnmatch.py`" + +#: ../../library/fnmatch.rst:15 +msgid "" +"This module provides support for Unix shell-style wildcards, which are *not* " +"the same as regular expressions (which are documented in the :mod:`re` " +"module). The special characters used in shell-style wildcards are:" +msgstr "" + +#: ../../library/fnmatch.rst:27 +msgid "Pattern" +msgstr "" + +#: ../../library/fnmatch.rst:27 +msgid "Meaning" +msgstr "含義" + +#: ../../library/fnmatch.rst:29 +msgid "``*``" +msgstr "``*``" + +#: ../../library/fnmatch.rst:29 +msgid "matches everything" +msgstr "" + +#: ../../library/fnmatch.rst:31 +msgid "``?``" +msgstr "``?``" + +#: ../../library/fnmatch.rst:31 +msgid "matches any single character" +msgstr "" + +#: ../../library/fnmatch.rst:33 +msgid "``[seq]``" +msgstr "``[seq]``" + +#: ../../library/fnmatch.rst:33 +msgid "matches any character in *seq*" +msgstr "" + +#: ../../library/fnmatch.rst:35 +msgid "``[!seq]``" +msgstr "``[!seq]``" + +#: ../../library/fnmatch.rst:35 +msgid "matches any character not in *seq*" +msgstr "" + +#: ../../library/fnmatch.rst:38 +msgid "" +"For a literal match, wrap the meta-characters in brackets. For example, " +"``'[?]'`` matches the character ``'?'``." +msgstr "" + +#: ../../library/fnmatch.rst:43 +msgid "" +"Note that the filename separator (``'/'`` on Unix) is *not* special to this " +"module. See module :mod:`glob` for pathname expansion (:mod:`glob` " +"uses :func:`.filter` to match pathname segments). Similarly, filenames " +"starting with a period are not special for this module, and are matched by " +"the ``*`` and ``?`` patterns." +msgstr "" + +#: ../../library/fnmatch.rst:49 +msgid "" +"Unless stated otherwise, \"filename string\" and \"pattern string\" either " +"refer to :class:`str` or ``ISO-8859-1`` encoded :class:`bytes` objects. Note " +"that the functions documented below do not allow to mix a :class:`!bytes` " +"pattern with a :class:`!str` filename, and vice-versa." +msgstr "" + +#: ../../library/fnmatch.rst:54 +msgid "" +"Finally, note that :func:`functools.lru_cache` with a *maxsize* of 32768 is " +"used to cache the (typed) compiled regex patterns in the following " +"functions: :func:`fnmatch`, :func:`fnmatchcase`, :func:`.filter`, :func:`.filterfalse`." +msgstr "" + +#: ../../library/fnmatch.rst:61 +msgid "" +"Test whether the filename string *name* matches the pattern string *pat*, " +"returning ``True`` or ``False``. Both parameters are case-normalized " +"using :func:`os.path.normcase`. :func:`fnmatchcase` can be used to perform a " +"case-sensitive comparison, regardless of whether that's standard for the " +"operating system." +msgstr "" + +#: ../../library/fnmatch.rst:67 +msgid "" +"This example will print all file names in the current directory with the " +"extension ``.txt``::" +msgstr "" + +#: ../../library/fnmatch.rst:70 +msgid "" +"import fnmatch\n" +"import os\n" +"\n" +"for file in os.listdir('.'):\n" +" if fnmatch.fnmatch(file, '*.txt'):\n" +" print(file)" +msgstr "" +"import fnmatch\n" +"import os\n" +"\n" +"for file in os.listdir('.'):\n" +" if fnmatch.fnmatch(file, '*.txt'):\n" +" print(file)" + +#: ../../library/fnmatch.rst:80 +msgid "" +"Test whether the filename string *name* matches the pattern string *pat*, " +"returning ``True`` or ``False``; the comparison is case-sensitive and does " +"not apply :func:`os.path.normcase`." +msgstr "" + +#: ../../library/fnmatch.rst:87 +msgid "" +"Construct a list from those elements of the :term:`iterable` of filename " +"strings *names* that match the pattern string *pat*. It is the same as ``[n " +"for n in names if fnmatch(n, pat)]``, but implemented more efficiently." +msgstr "" + +#: ../../library/fnmatch.rst:95 +msgid "" +"Construct a list from those elements of the :term:`iterable` of filename " +"strings *names* that do not match the pattern string *pat*. It is the same " +"as ``[n for n in names if not fnmatch(n, pat)]``, but implemented more " +"efficiently." +msgstr "" + +#: ../../library/fnmatch.rst:105 +msgid "" +"Return the shell-style pattern *pat* converted to a regular expression for " +"using with :func:`re.match`. The pattern is expected to be a :class:`str`." +msgstr "" + +#: ../../library/fnmatch.rst:108 +msgid "Example:" +msgstr "範例：" + +#: ../../library/fnmatch.rst:122 +msgid "Module :mod:`glob`" +msgstr ":mod:`glob` 模組" + +#: ../../library/fnmatch.rst:123 +msgid "Unix shell-style path expansion." +msgstr "" + +#: ../../library/fnmatch.rst:9 +msgid "filenames" +msgstr "filenames（檔案名稱）" + +#: ../../library/fnmatch.rst:9 +msgid "wildcard expansion" +msgstr "wildcard expansion（萬用字元展開）" + +#: ../../library/fnmatch.rst:11 ../../library/fnmatch.rst:41 +msgid "module" +msgstr "module（模組）" + +#: ../../library/fnmatch.rst:11 +msgid "re" +msgstr "re" + +#: ../../library/fnmatch.rst:19 +msgid "* (asterisk)" +msgstr "* （星號）" + +#: ../../library/fnmatch.rst:19 +msgid "in glob-style wildcards" +msgstr "於 glob 風格的萬用字元中" + +#: ../../library/fnmatch.rst:19 +msgid "? (question mark)" +msgstr "? （問號）" + +#: ../../library/fnmatch.rst:19 +msgid "[] (square brackets)" +msgstr "[] （方括號）" + +#: ../../library/fnmatch.rst:19 +msgid "! (exclamation)" +msgstr "! （驚嘆號）" + +#: ../../library/fnmatch.rst:19 +msgid "- (minus)" +msgstr "- （減號）" + +#: ../../library/fnmatch.rst:41 +msgid "glob" +msgstr "glob" diff --git a/library/fractions.po b/library/fractions.po index 03799a18f9..33b5ab664a 100644 --- a/library/fractions.po +++ b/library/fractions.po @@ -1,360 +1,360 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-10-08 00:15+0000\n" -"PO-Revision-Date: 2016-01-31 07:18+0000\n" -"Last-Translator: Liang-Bo Wang \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/fractions.rst:2 -msgid ":mod:`!fractions` --- Rational numbers" -msgstr ":mod:`!fractions` --- 有理數" - -#: ../../library/fractions.rst:10 -msgid "**Source code:** :source:`Lib/fractions.py`" -msgstr "**原始碼：**\\ :source:`Lib/fractions.py`" - -#: ../../library/fractions.rst:14 -msgid "" -"The :mod:`fractions` module provides support for rational number arithmetic." -msgstr "" - -#: ../../library/fractions.rst:17 -msgid "" -"A Fraction instance can be constructed from a pair of rational numbers, from " -"a single number, or from a string." -msgstr "" - -#: ../../library/fractions.rst:26 -msgid "" -"The first version requires that *numerator* and *denominator* are instances " -"of :class:`numbers.Rational` and returns a new :class:`Fraction` instance " -"with a value equal to ``numerator/denominator``. If *denominator* is zero, " -"it raises a :exc:`ZeroDivisionError`." -msgstr "" - -#: ../../library/fractions.rst:31 -msgid "" -"The second version requires that *number* is an instance of :class:`numbers." -"Rational` or has the :meth:`!as_integer_ratio` method (this includes :class:" -"`float` and :class:`decimal.Decimal`). It returns a :class:`Fraction` " -"instance with exactly the same value. Assumed, that the :meth:`!" -"as_integer_ratio` method returns a pair of coprime integers and last one is " -"positive. Note that due to the usual issues with binary point (see :ref:`tut-" -"fp-issues`), the argument to ``Fraction(1.1)`` is not exactly equal to " -"11/10, and so ``Fraction(1.1)`` does *not* return ``Fraction(11, 10)`` as " -"one might expect. (But see the documentation for the :meth:" -"`limit_denominator` method below.)" -msgstr "" - -#: ../../library/fractions.rst:43 -msgid "" -"The last version of the constructor expects a string. The usual form for " -"this instance is::" -msgstr "" - -#: ../../library/fractions.rst:46 -msgid "[sign] numerator ['/' denominator]" -msgstr "[sign] numerator ['/' denominator]" - -#: ../../library/fractions.rst:48 -msgid "" -"where the optional ``sign`` may be either '+' or '-' and ``numerator`` and " -"``denominator`` (if present) are strings of decimal digits (underscores may " -"be used to delimit digits as with integral literals in code). In addition, " -"any string that represents a finite value and is accepted by the :class:" -"`float` constructor is also accepted by the :class:`Fraction` constructor. " -"In either form the input string may also have leading and/or trailing " -"whitespace. Here are some examples::" -msgstr "" - -#: ../../library/fractions.rst:57 -msgid "" -">>> from fractions import Fraction\n" -">>> Fraction(16, -10)\n" -"Fraction(-8, 5)\n" -">>> Fraction(123)\n" -"Fraction(123, 1)\n" -">>> Fraction()\n" -"Fraction(0, 1)\n" -">>> Fraction('3/7')\n" -"Fraction(3, 7)\n" -">>> Fraction(' -3/7 ')\n" -"Fraction(-3, 7)\n" -">>> Fraction('1.414213 \\t\\n')\n" -"Fraction(1414213, 1000000)\n" -">>> Fraction('-.125')\n" -"Fraction(-1, 8)\n" -">>> Fraction('7e-6')\n" -"Fraction(7, 1000000)\n" -">>> Fraction(2.25)\n" -"Fraction(9, 4)\n" -">>> Fraction(1.1)\n" -"Fraction(2476979795053773, 2251799813685248)\n" -">>> from decimal import Decimal\n" -">>> Fraction(Decimal('1.1'))\n" -"Fraction(11, 10)" -msgstr "" -">>> from fractions import Fraction\n" -">>> Fraction(16, -10)\n" -"Fraction(-8, 5)\n" -">>> Fraction(123)\n" -"Fraction(123, 1)\n" -">>> Fraction()\n" -"Fraction(0, 1)\n" -">>> Fraction('3/7')\n" -"Fraction(3, 7)\n" -">>> Fraction(' -3/7 ')\n" -"Fraction(-3, 7)\n" -">>> Fraction('1.414213 \\t\\n')\n" -"Fraction(1414213, 1000000)\n" -">>> Fraction('-.125')\n" -"Fraction(-1, 8)\n" -">>> Fraction('7e-6')\n" -"Fraction(7, 1000000)\n" -">>> Fraction(2.25)\n" -"Fraction(9, 4)\n" -">>> Fraction(1.1)\n" -"Fraction(2476979795053773, 2251799813685248)\n" -">>> from decimal import Decimal\n" -">>> Fraction(Decimal('1.1'))\n" -"Fraction(11, 10)" - -#: ../../library/fractions.rst:83 -msgid "" -"The :class:`Fraction` class inherits from the abstract base class :class:" -"`numbers.Rational`, and implements all of the methods and operations from " -"that class. :class:`Fraction` instances are :term:`hashable`, and should be " -"treated as immutable. In addition, :class:`Fraction` has the following " -"properties and methods:" -msgstr "" - -#: ../../library/fractions.rst:89 -msgid "" -"The :class:`Fraction` constructor now accepts :class:`float` and :class:" -"`decimal.Decimal` instances." -msgstr "" -":class:`Fraction` 建構函式現在可接受 :class:`float` 和 :class:`decimal." -"Decimal` 實例。" - -#: ../../library/fractions.rst:93 -msgid "" -"The :func:`math.gcd` function is now used to normalize the *numerator* and " -"*denominator*. :func:`math.gcd` always returns an :class:`int` type. " -"Previously, the GCD type depended on *numerator* and *denominator*." -msgstr "" - -#: ../../library/fractions.rst:98 -msgid "" -"Underscores are now permitted when creating a :class:`Fraction` instance " -"from a string, following :PEP:`515` rules." -msgstr "" - -#: ../../library/fractions.rst:102 -msgid "" -":class:`Fraction` implements ``__int__`` now to satisfy ``typing." -"SupportsInt`` instance checks." -msgstr "" - -#: ../../library/fractions.rst:106 -msgid "" -"Space is allowed around the slash for string inputs: ``Fraction('2 / 3')``." -msgstr "" - -#: ../../library/fractions.rst:109 -msgid "" -":class:`Fraction` instances now support float-style formatting, with " -"presentation types ``\"e\"``, ``\"E\"``, ``\"f\"``, ``\"F\"``, ``\"g\"``, " -"``\"G\"`` and ``\"%\"\"``." -msgstr "" - -#: ../../library/fractions.rst:114 -msgid "" -"Formatting of :class:`Fraction` instances without a presentation type now " -"supports fill, alignment, sign handling, minimum width and grouping." -msgstr "" - -#: ../../library/fractions.rst:118 -msgid "" -"The :class:`Fraction` constructor now accepts any objects with the :meth:`!" -"as_integer_ratio` method." -msgstr "" -":class:`Fraction` 建構函式現在可接受任何具有 :meth:`!as_integer_ratio` 方法的" -"物件。" - -#: ../../library/fractions.rst:124 -msgid "Numerator of the Fraction in lowest term." -msgstr "" - -#: ../../library/fractions.rst:128 -msgid "Denominator of the Fraction in lowest terms. Guaranteed to be positive." -msgstr "" - -#: ../../library/fractions.rst:134 -msgid "" -"Return a tuple of two integers, whose ratio is equal to the original " -"Fraction. The ratio is in lowest terms and has a positive denominator." -msgstr "" - -#: ../../library/fractions.rst:142 -msgid "Return ``True`` if the Fraction is an integer." -msgstr "" - -#: ../../library/fractions.rst:148 -msgid "" -"Alternative constructor which only accepts instances of :class:`float` or :" -"class:`numbers.Integral`. Beware that ``Fraction.from_float(0.3)`` is not " -"the same value as ``Fraction(3, 10)``." -msgstr "" - -#: ../../library/fractions.rst:154 -msgid "" -"From Python 3.2 onwards, you can also construct a :class:`Fraction` instance " -"directly from a :class:`float`." -msgstr "" - -#: ../../library/fractions.rst:160 -msgid "" -"Alternative constructor which only accepts instances of :class:`decimal." -"Decimal` or :class:`numbers.Integral`." -msgstr "" - -#: ../../library/fractions.rst:165 -msgid "" -"From Python 3.2 onwards, you can also construct a :class:`Fraction` instance " -"directly from a :class:`decimal.Decimal` instance." -msgstr "" - -#: ../../library/fractions.rst:172 -msgid "" -"Alternative constructor which only accepts instances of :class:`numbers." -"Integral`, :class:`numbers.Rational`, :class:`float` or :class:`decimal." -"Decimal`, and objects with the :meth:`!as_integer_ratio` method, but not " -"strings." -msgstr "" - -#: ../../library/fractions.rst:182 -msgid "" -"Finds and returns the closest :class:`Fraction` to ``self`` that has " -"denominator at most max_denominator. This method is useful for finding " -"rational approximations to a given floating-point number:" -msgstr "" - -#: ../../library/fractions.rst:190 -msgid "or for recovering a rational number that's represented as a float:" -msgstr "" - -#: ../../library/fractions.rst:203 -msgid "" -"Returns the greatest :class:`int` ``<= self``. This method can also be " -"accessed through the :func:`math.floor` function:" -msgstr "" - -#: ../../library/fractions.rst:213 -msgid "" -"Returns the least :class:`int` ``>= self``. This method can also be " -"accessed through the :func:`math.ceil` function." -msgstr "" - -#: ../../library/fractions.rst:220 -msgid "" -"The first version returns the nearest :class:`int` to ``self``, rounding " -"half to even. The second version rounds ``self`` to the nearest multiple of " -"``Fraction(1, 10**ndigits)`` (logically, if ``ndigits`` is negative), again " -"rounding half toward even. This method can also be accessed through the :" -"func:`round` function." -msgstr "" - -#: ../../library/fractions.rst:228 -msgid "" -"Provides support for formatting of :class:`Fraction` instances via the :meth:" -"`str.format` method, the :func:`format` built-in function, or :ref:" -"`Formatted string literals `." -msgstr "" - -#: ../../library/fractions.rst:232 -msgid "" -"If the ``format_spec`` format specification string does not end with one of " -"the presentation types ``'e'``, ``'E'``, ``'f'``, ``'F'``, ``'g'``, ``'G'`` " -"or ``'%'`` then formatting follows the general rules for fill, alignment, " -"sign handling, minimum width, and grouping as described in the :ref:`format " -"specification mini-language `. The \"alternate form\" flag " -"``'#'`` is supported: if present, it forces the output string to always " -"include an explicit denominator, even when the value being formatted is an " -"exact integer. The zero-fill flag ``'0'`` is not supported." -msgstr "" - -#: ../../library/fractions.rst:242 -msgid "" -"If the ``format_spec`` format specification string ends with one of the " -"presentation types ``'e'``, ``'E'``, ``'f'``, ``'F'``, ``'g'``, ``'G'`` or " -"``'%'`` then formatting follows the rules outlined for the :class:`float` " -"type in the :ref:`formatspec` section." -msgstr "" - -#: ../../library/fractions.rst:247 -msgid "Here are some examples::" -msgstr "" - -#: ../../library/fractions.rst:249 -msgid "" -">>> from fractions import Fraction\n" -">>> format(Fraction(103993, 33102), '_')\n" -"'103_993/33_102'\n" -">>> format(Fraction(1, 7), '.^+10')\n" -"'...+1/7...'\n" -">>> format(Fraction(3, 1), '')\n" -"'3'\n" -">>> format(Fraction(3, 1), '#')\n" -"'3/1'\n" -">>> format(Fraction(1, 7), '.40g')\n" -"'0.1428571428571428571428571428571428571429'\n" -">>> format(Fraction('1234567.855'), '_.2f')\n" -"'1_234_567.86'\n" -">>> f\"{Fraction(355, 113):*>20.6e}\"\n" -"'********3.141593e+00'\n" -">>> old_price, new_price = 499, 672\n" -">>> \"{:.2%} price increase\".format(Fraction(new_price, old_price) - 1)\n" -"'34.67% price increase'" -msgstr "" -">>> from fractions import Fraction\n" -">>> format(Fraction(103993, 33102), '_')\n" -"'103_993/33_102'\n" -">>> format(Fraction(1, 7), '.^+10')\n" -"'...+1/7...'\n" -">>> format(Fraction(3, 1), '')\n" -"'3'\n" -">>> format(Fraction(3, 1), '#')\n" -"'3/1'\n" -">>> format(Fraction(1, 7), '.40g')\n" -"'0.1428571428571428571428571428571428571429'\n" -">>> format(Fraction('1234567.855'), '_.2f')\n" -"'1_234_567.86'\n" -">>> f\"{Fraction(355, 113):*>20.6e}\"\n" -"'********3.141593e+00'\n" -">>> old_price, new_price = 499, 672\n" -">>> \"{:.2%} price increase\".format(Fraction(new_price, old_price) - 1)\n" -"'34.67% price increase'" - -#: ../../library/fractions.rst:271 -msgid "Module :mod:`numbers`" -msgstr ":mod:`numbers` 模組" - -#: ../../library/fractions.rst:272 -msgid "The abstract base classes making up the numeric tower." -msgstr "" - -#: ../../library/fractions.rst:20 -msgid "as_integer_ratio()" -msgstr "as_integer_ratio()" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-10-08 00:15+0000\n" +"PO-Revision-Date: 2016-01-31 07:18+0000\n" +"Last-Translator: Liang-Bo Wang \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/fractions.rst:2 +msgid ":mod:`!fractions` --- Rational numbers" +msgstr ":mod:`!fractions` --- 有理數" + +#: ../../library/fractions.rst:10 +msgid "**Source code:** :source:`Lib/fractions.py`" +msgstr "**原始碼：**\\ :source:`Lib/fractions.py`" + +#: ../../library/fractions.rst:14 +msgid "" +"The :mod:`fractions` module provides support for rational number arithmetic." +msgstr "" + +#: ../../library/fractions.rst:17 +msgid "" +"A Fraction instance can be constructed from a pair of rational numbers, from " +"a single number, or from a string." +msgstr "" + +#: ../../library/fractions.rst:26 +msgid "" +"The first version requires that *numerator* and *denominator* are instances " +"of :class:`numbers.Rational` and returns a new :class:`Fraction` instance " +"with a value equal to ``numerator/denominator``. If *denominator* is zero, " +"it raises a :exc:`ZeroDivisionError`." +msgstr "" + +#: ../../library/fractions.rst:31 +msgid "" +"The second version requires that *number* is an instance of :class:`numbers." +"Rational` or has the :meth:`!as_integer_ratio` method (this includes :class:" +"`float` and :class:`decimal.Decimal`). It returns a :class:`Fraction` " +"instance with exactly the same value. Assumed, that the :meth:`!" +"as_integer_ratio` method returns a pair of coprime integers and last one is " +"positive. Note that due to the usual issues with binary point (see :ref:`tut-" +"fp-issues`), the argument to ``Fraction(1.1)`` is not exactly equal to " +"11/10, and so ``Fraction(1.1)`` does *not* return ``Fraction(11, 10)`` as " +"one might expect. (But see the documentation for the :meth:" +"`limit_denominator` method below.)" +msgstr "" + +#: ../../library/fractions.rst:43 +msgid "" +"The last version of the constructor expects a string. The usual form for " +"this instance is::" +msgstr "" + +#: ../../library/fractions.rst:46 +msgid "[sign] numerator ['/' denominator]" +msgstr "[sign] numerator ['/' denominator]" + +#: ../../library/fractions.rst:48 +msgid "" +"where the optional ``sign`` may be either '+' or '-' and ``numerator`` and " +"``denominator`` (if present) are strings of decimal digits (underscores may " +"be used to delimit digits as with integral literals in code). In addition, " +"any string that represents a finite value and is accepted by the :class:" +"`float` constructor is also accepted by the :class:`Fraction` constructor. " +"In either form the input string may also have leading and/or trailing " +"whitespace. Here are some examples::" +msgstr "" + +#: ../../library/fractions.rst:57 +msgid "" +">>> from fractions import Fraction\n" +">>> Fraction(16, -10)\n" +"Fraction(-8, 5)\n" +">>> Fraction(123)\n" +"Fraction(123, 1)\n" +">>> Fraction()\n" +"Fraction(0, 1)\n" +">>> Fraction('3/7')\n" +"Fraction(3, 7)\n" +">>> Fraction(' -3/7 ')\n" +"Fraction(-3, 7)\n" +">>> Fraction('1.414213 \\t\\n')\n" +"Fraction(1414213, 1000000)\n" +">>> Fraction('-.125')\n" +"Fraction(-1, 8)\n" +">>> Fraction('7e-6')\n" +"Fraction(7, 1000000)\n" +">>> Fraction(2.25)\n" +"Fraction(9, 4)\n" +">>> Fraction(1.1)\n" +"Fraction(2476979795053773, 2251799813685248)\n" +">>> from decimal import Decimal\n" +">>> Fraction(Decimal('1.1'))\n" +"Fraction(11, 10)" +msgstr "" +">>> from fractions import Fraction\n" +">>> Fraction(16, -10)\n" +"Fraction(-8, 5)\n" +">>> Fraction(123)\n" +"Fraction(123, 1)\n" +">>> Fraction()\n" +"Fraction(0, 1)\n" +">>> Fraction('3/7')\n" +"Fraction(3, 7)\n" +">>> Fraction(' -3/7 ')\n" +"Fraction(-3, 7)\n" +">>> Fraction('1.414213 \\t\\n')\n" +"Fraction(1414213, 1000000)\n" +">>> Fraction('-.125')\n" +"Fraction(-1, 8)\n" +">>> Fraction('7e-6')\n" +"Fraction(7, 1000000)\n" +">>> Fraction(2.25)\n" +"Fraction(9, 4)\n" +">>> Fraction(1.1)\n" +"Fraction(2476979795053773, 2251799813685248)\n" +">>> from decimal import Decimal\n" +">>> Fraction(Decimal('1.1'))\n" +"Fraction(11, 10)" + +#: ../../library/fractions.rst:83 +msgid "" +"The :class:`Fraction` class inherits from the abstract base class :class:" +"`numbers.Rational`, and implements all of the methods and operations from " +"that class. :class:`Fraction` instances are :term:`hashable`, and should be " +"treated as immutable. In addition, :class:`Fraction` has the following " +"properties and methods:" +msgstr "" + +#: ../../library/fractions.rst:89 +msgid "" +"The :class:`Fraction` constructor now accepts :class:`float` and :class:" +"`decimal.Decimal` instances." +msgstr "" +":class:`Fraction` 建構函式現在可接受 :class:`float` 和 :class:`decimal." +"Decimal` 實例。" + +#: ../../library/fractions.rst:93 +msgid "" +"The :func:`math.gcd` function is now used to normalize the *numerator* and " +"*denominator*. :func:`math.gcd` always returns an :class:`int` type. " +"Previously, the GCD type depended on *numerator* and *denominator*." +msgstr "" + +#: ../../library/fractions.rst:98 +msgid "" +"Underscores are now permitted when creating a :class:`Fraction` instance " +"from a string, following :PEP:`515` rules." +msgstr "" + +#: ../../library/fractions.rst:102 +msgid "" +":class:`Fraction` implements ``__int__`` now to satisfy ``typing." +"SupportsInt`` instance checks." +msgstr "" + +#: ../../library/fractions.rst:106 +msgid "" +"Space is allowed around the slash for string inputs: ``Fraction('2 / 3')``." +msgstr "" + +#: ../../library/fractions.rst:109 +msgid "" +":class:`Fraction` instances now support float-style formatting, with " +"presentation types ``\"e\"``, ``\"E\"``, ``\"f\"``, ``\"F\"``, ``\"g\"``, " +"``\"G\"`` and ``\"%\"\"``." +msgstr "" + +#: ../../library/fractions.rst:114 +msgid "" +"Formatting of :class:`Fraction` instances without a presentation type now " +"supports fill, alignment, sign handling, minimum width and grouping." +msgstr "" + +#: ../../library/fractions.rst:118 +msgid "" +"The :class:`Fraction` constructor now accepts any objects with the :meth:`!" +"as_integer_ratio` method." +msgstr "" +":class:`Fraction` 建構函式現在可接受任何具有 :meth:`!as_integer_ratio` 方法的" +"物件。" + +#: ../../library/fractions.rst:124 +msgid "Numerator of the Fraction in lowest term." +msgstr "" + +#: ../../library/fractions.rst:128 +msgid "Denominator of the Fraction in lowest terms. Guaranteed to be positive." +msgstr "" + +#: ../../library/fractions.rst:134 +msgid "" +"Return a tuple of two integers, whose ratio is equal to the original " +"Fraction. The ratio is in lowest terms and has a positive denominator." +msgstr "" + +#: ../../library/fractions.rst:142 +msgid "Return ``True`` if the Fraction is an integer." +msgstr "" + +#: ../../library/fractions.rst:148 +msgid "" +"Alternative constructor which only accepts instances of :class:`float` or :" +"class:`numbers.Integral`. Beware that ``Fraction.from_float(0.3)`` is not " +"the same value as ``Fraction(3, 10)``." +msgstr "" + +#: ../../library/fractions.rst:154 +msgid "" +"From Python 3.2 onwards, you can also construct a :class:`Fraction` instance " +"directly from a :class:`float`." +msgstr "" + +#: ../../library/fractions.rst:160 +msgid "" +"Alternative constructor which only accepts instances of :class:`decimal." +"Decimal` or :class:`numbers.Integral`." +msgstr "" + +#: ../../library/fractions.rst:165 +msgid "" +"From Python 3.2 onwards, you can also construct a :class:`Fraction` instance " +"directly from a :class:`decimal.Decimal` instance." +msgstr "" + +#: ../../library/fractions.rst:172 +msgid "" +"Alternative constructor which only accepts instances of :class:`numbers." +"Integral`, :class:`numbers.Rational`, :class:`float` or :class:`decimal." +"Decimal`, and objects with the :meth:`!as_integer_ratio` method, but not " +"strings." +msgstr "" + +#: ../../library/fractions.rst:182 +msgid "" +"Finds and returns the closest :class:`Fraction` to ``self`` that has " +"denominator at most max_denominator. This method is useful for finding " +"rational approximations to a given floating-point number:" +msgstr "" + +#: ../../library/fractions.rst:190 +msgid "or for recovering a rational number that's represented as a float:" +msgstr "" + +#: ../../library/fractions.rst:203 +msgid "" +"Returns the greatest :class:`int` ``<= self``. This method can also be " +"accessed through the :func:`math.floor` function:" +msgstr "" + +#: ../../library/fractions.rst:213 +msgid "" +"Returns the least :class:`int` ``>= self``. This method can also be " +"accessed through the :func:`math.ceil` function." +msgstr "" + +#: ../../library/fractions.rst:220 +msgid "" +"The first version returns the nearest :class:`int` to ``self``, rounding " +"half to even. The second version rounds ``self`` to the nearest multiple of " +"``Fraction(1, 10**ndigits)`` (logically, if ``ndigits`` is negative), again " +"rounding half toward even. This method can also be accessed through the :" +"func:`round` function." +msgstr "" + +#: ../../library/fractions.rst:228 +msgid "" +"Provides support for formatting of :class:`Fraction` instances via the :meth:" +"`str.format` method, the :func:`format` built-in function, or :ref:" +"`Formatted string literals `." +msgstr "" + +#: ../../library/fractions.rst:232 +msgid "" +"If the ``format_spec`` format specification string does not end with one of " +"the presentation types ``'e'``, ``'E'``, ``'f'``, ``'F'``, ``'g'``, ``'G'`` " +"or ``'%'`` then formatting follows the general rules for fill, alignment, " +"sign handling, minimum width, and grouping as described in the :ref:`format " +"specification mini-language `. The \"alternate form\" flag " +"``'#'`` is supported: if present, it forces the output string to always " +"include an explicit denominator, even when the value being formatted is an " +"exact integer. The zero-fill flag ``'0'`` is not supported." +msgstr "" + +#: ../../library/fractions.rst:242 +msgid "" +"If the ``format_spec`` format specification string ends with one of the " +"presentation types ``'e'``, ``'E'``, ``'f'``, ``'F'``, ``'g'``, ``'G'`` or " +"``'%'`` then formatting follows the rules outlined for the :class:`float` " +"type in the :ref:`formatspec` section." +msgstr "" + +#: ../../library/fractions.rst:247 +msgid "Here are some examples::" +msgstr "" + +#: ../../library/fractions.rst:249 +msgid "" +">>> from fractions import Fraction\n" +">>> format(Fraction(103993, 33102), '_')\n" +"'103_993/33_102'\n" +">>> format(Fraction(1, 7), '.^+10')\n" +"'...+1/7...'\n" +">>> format(Fraction(3, 1), '')\n" +"'3'\n" +">>> format(Fraction(3, 1), '#')\n" +"'3/1'\n" +">>> format(Fraction(1, 7), '.40g')\n" +"'0.1428571428571428571428571428571428571429'\n" +">>> format(Fraction('1234567.855'), '_.2f')\n" +"'1_234_567.86'\n" +">>> f\"{Fraction(355, 113):*>20.6e}\"\n" +"'********3.141593e+00'\n" +">>> old_price, new_price = 499, 672\n" +">>> \"{:.2%} price increase\".format(Fraction(new_price, old_price) - 1)\n" +"'34.67% price increase'" +msgstr "" +">>> from fractions import Fraction\n" +">>> format(Fraction(103993, 33102), '_')\n" +"'103_993/33_102'\n" +">>> format(Fraction(1, 7), '.^+10')\n" +"'...+1/7...'\n" +">>> format(Fraction(3, 1), '')\n" +"'3'\n" +">>> format(Fraction(3, 1), '#')\n" +"'3/1'\n" +">>> format(Fraction(1, 7), '.40g')\n" +"'0.1428571428571428571428571428571428571429'\n" +">>> format(Fraction('1234567.855'), '_.2f')\n" +"'1_234_567.86'\n" +">>> f\"{Fraction(355, 113):*>20.6e}\"\n" +"'********3.141593e+00'\n" +">>> old_price, new_price = 499, 672\n" +">>> \"{:.2%} price increase\".format(Fraction(new_price, old_price) - 1)\n" +"'34.67% price increase'" + +#: ../../library/fractions.rst:271 +msgid "Module :mod:`numbers`" +msgstr ":mod:`numbers` 模組" + +#: ../../library/fractions.rst:272 +msgid "The abstract base classes making up the numeric tower." +msgstr "" + +#: ../../library/fractions.rst:20 +msgid "as_integer_ratio()" +msgstr "as_integer_ratio()" diff --git a/library/frameworks.po b/library/frameworks.po index a3767f2497..a68fcb2ecc 100644 --- a/library/frameworks.po +++ b/library/frameworks.po @@ -1,42 +1,42 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Leon H., 2017 -# Weilin Du, 2025 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-08-16 00:16+0000\n" -"PO-Revision-Date: 2025-06-27 13:41+0800\n" -"Last-Translator: Leon H.\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/frameworks.rst:7 -msgid "Program frameworks" -msgstr "程式框架" - -#: ../../library/frameworks.rst:9 -msgid "" -"This chapter is no longer maintained, and the modules it contained have been " -"moved to their respective topical documentation." -msgstr "此章節不再維護，所包含的模組已移至各自的主題文件中。" - -#: ../../library/frameworks.rst:11 -msgid ":mod:`cmd` — :doc:`Command Line Interface Libraries <./cmdlinelibs>`" -msgstr ":mod:`cmd` — :doc:`命令列介面函式庫 <./cmdlinelibs>`" - -#: ../../library/frameworks.rst:12 -msgid ":mod:`shlex` — :doc:`Unix Specific Services <./unix>`" -msgstr ":mod:`shlex` — :doc:`Unix 特定服務 <./unix>`" - -#: ../../library/frameworks.rst:13 -msgid ":mod:`turtle` — :doc:`Graphical User Interfaces with Tk <./tk>`" -msgstr ":mod:`turtle` — :doc:`使用 Tk 的圖形化使用者介面 <./tk>`" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Leon H., 2017 +# Weilin Du, 2025 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-08-16 00:16+0000\n" +"PO-Revision-Date: 2025-06-27 13:41+0800\n" +"Last-Translator: Leon H.\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/frameworks.rst:7 +msgid "Program frameworks" +msgstr "程式框架" + +#: ../../library/frameworks.rst:9 +msgid "" +"This chapter is no longer maintained, and the modules it contained have been " +"moved to their respective topical documentation." +msgstr "此章節不再維護，所包含的模組已移至各自的主題文件中。" + +#: ../../library/frameworks.rst:11 +msgid ":mod:`cmd` — :doc:`Command Line Interface Libraries <./cmdlinelibs>`" +msgstr ":mod:`cmd` — :doc:`命令列介面函式庫 <./cmdlinelibs>`" + +#: ../../library/frameworks.rst:12 +msgid ":mod:`shlex` — :doc:`Unix Specific Services <./unix>`" +msgstr ":mod:`shlex` — :doc:`Unix 特定服務 <./unix>`" + +#: ../../library/frameworks.rst:13 +msgid ":mod:`turtle` — :doc:`Graphical User Interfaces with Tk <./tk>`" +msgstr ":mod:`turtle` — :doc:`使用 Tk 的圖形化使用者介面 <./tk>`" diff --git a/library/ftplib.po b/library/ftplib.po index d453fa16ca..40e5d730b8 100644 --- a/library/ftplib.po +++ b/library/ftplib.po @@ -1,748 +1,748 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Matt Wang , 2023-2024 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-10-11 00:13+0000\n" -"PO-Revision-Date: 2023-04-26 19:44+0800\n" -"Last-Translator: Matt Wang \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" -"X-Generator: Poedit 3.2.2\n" - -#: ../../library/ftplib.rst:2 -msgid ":mod:`!ftplib` --- FTP protocol client" -msgstr ":mod:`!ftplib` --- FTP 協定用戶端" - -#: ../../library/ftplib.rst:7 -msgid "**Source code:** :source:`Lib/ftplib.py`" -msgstr "**原始碼：**\\ :source:`Lib/ftplib.py`" - -#: ../../library/ftplib.rst:15 -msgid "" -"This module defines the class :class:`FTP` and a few related items. The :" -"class:`FTP` class implements the client side of the FTP protocol. You can " -"use this to write Python programs that perform a variety of automated FTP " -"jobs, such as mirroring other FTP servers. It is also used by the module :" -"mod:`urllib.request` to handle URLs that use FTP. For more information on " -"FTP (File Transfer Protocol), see internet :rfc:`959`." -msgstr "" -"這個模組定義了 :class:`FTP` 類別和一些相關的項目。:class:`FTP` 類別實作了 " -"FTP 協定的用戶端。你可以使用它來編寫能夠執行各種 FTP 自動作業的 Python 程式，" -"例如鏡像 (mirror) 其他 FTP 伺服器。:mod:`urllib.request` 模組也使用它來處理使" -"用 FTP 的 URL。有關 FTP（檔案傳輸協定）的更多資訊，請參閱 :rfc:`959`。" - -#: ../../library/ftplib.rst:22 -msgid "The default encoding is UTF-8, following :rfc:`2640`." -msgstr "預設編碼是 UTF-8，遵循 :rfc:`2640`。" - -#: ../../includes/wasm-notavail.rst:3 -msgid "Availability" -msgstr "可用性" - -#: ../../includes/wasm-notavail.rst:5 -msgid "" -"This module does not work or is not available on WebAssembly. See :ref:`wasm-" -"availability` for more information." -msgstr "" -"此模組在 WebAssembly 平台上不起作用或無法使用。更多資訊請參閱 :ref:`wasm-" -"availability`。" - -#: ../../library/ftplib.rst:26 -msgid "Here's a sample session using the :mod:`ftplib` module::" -msgstr "這是一個使用 :mod:`ftplib` 模組的會話範例：" - -#: ../../library/ftplib.rst:28 -msgid "" -">>> from ftplib import FTP\n" -">>> ftp = FTP('ftp.us.debian.org') # connect to host, default port\n" -">>> ftp.login() # user anonymous, passwd anonymous@\n" -"'230 Login successful.'\n" -">>> ftp.cwd('debian') # change into \"debian\" directory\n" -"'250 Directory successfully changed.'\n" -">>> ftp.retrlines('LIST') # list directory contents\n" -"-rw-rw-r-- 1 1176 1176 1063 Jun 15 10:18 README\n" -"...\n" -"drwxr-sr-x 5 1176 1176 4096 Dec 19 2000 pool\n" -"drwxr-sr-x 4 1176 1176 4096 Nov 17 2008 project\n" -"drwxr-xr-x 3 1176 1176 4096 Oct 10 2012 tools\n" -"'226 Directory send OK.'\n" -">>> with open('README', 'wb') as fp:\n" -">>> ftp.retrbinary('RETR README', fp.write)\n" -"'226 Transfer complete.'\n" -">>> ftp.quit()\n" -"'221 Goodbye.'" -msgstr "" - -#: ../../library/ftplib.rst:51 -msgid "Reference" -msgstr "參考" - -#: ../../library/ftplib.rst:56 -msgid "FTP objects" -msgstr "FTP 物件" - -#: ../../library/ftplib.rst:87 -msgid "Return a new instance of the :class:`FTP` class." -msgstr "回傳一個新的 :class:`FTP` 類別實例。" - -#: ../../library/ftplib.rst:0 -msgid "Parameters" -msgstr "參數" - -#: ../../library/ftplib.rst:89 ../../library/ftplib.rst:461 -msgid "" -"The hostname to connect to. If given, :code:`connect(host)` is implicitly " -"called by the constructor." -msgstr "" -"要連接的主機名稱。如果有給定，:code:`connect(host)` 會由建構函式來隱式地呼" -"叫。" - -#: ../../library/ftplib.rst:93 ../../library/ftplib.rst:465 -msgid "" -"|param_doc_user| If given, :code:`login(host, passwd, acct)` is implicitly " -"called by the constructor." -msgstr "" -"|param_doc_user| 如果有給定，:code:`login(host, passwd, acct)` 會由建構函式來" -"隱式地呼叫。" - -#: ../../library/ftplib.rst:98 ../../library/ftplib.rst:212 -#: ../../library/ftplib.rst:470 -msgid "|param_doc_passwd|" -msgstr "|param_doc_passwd|" - -#: ../../library/ftplib.rst:101 ../../library/ftplib.rst:215 -#: ../../library/ftplib.rst:473 -msgid "|param_doc_acct|" -msgstr "|param_doc_acct|" - -#: ../../library/ftplib.rst:104 -msgid "" -"A timeout in seconds for blocking operations like :meth:`connect` (default: " -"the global default timeout setting)." -msgstr "" -"如 :meth:`connect` 的阻塞操作的超時設定，以秒為單位（預設：使用全域預設超時設" -"定）。" - -#: ../../library/ftplib.rst:109 ../../library/ftplib.rst:183 -#: ../../library/ftplib.rst:488 -msgid "|param_doc_source_address|" -msgstr "|param_doc_source_address|" - -#: ../../library/ftplib.rst:113 ../../library/ftplib.rst:492 -msgid "|param_doc_encoding|" -msgstr "|param_doc_encoding|" - -#: ../../library/ftplib.rst:116 -msgid "The :class:`FTP` class supports the :keyword:`with` statement, e.g.:" -msgstr ":class:`FTP` 類別支援 :keyword:`with` 陳述式，例如：" - -#: ../../library/ftplib.rst:130 -msgid "Support for the :keyword:`with` statement was added." -msgstr "新增了對 :keyword:`with` 陳述式的支援。" - -#: ../../library/ftplib.rst:133 ../../library/ftplib.rst:189 -msgid "*source_address* parameter was added." -msgstr "新增 *source_address* 參數。" - -#: ../../library/ftplib.rst:136 ../../library/ftplib.rst:505 -msgid "" -"If the *timeout* parameter is set to be zero, it will raise a :class:" -"`ValueError` to prevent the creation of a non-blocking socket. The " -"*encoding* parameter was added, and the default was changed from Latin-1 to " -"UTF-8 to follow :rfc:`2640`." -msgstr "" -"如果 *timeout* 參數設定為零，它將引發 :class:`ValueError` 以防止建立非阻塞 " -"socket。新增了 *encoding* 參數，預設值從 Latin-1 更改為 UTF-8 以遵循 :rfc:" -"`2640`。" - -#: ../../library/ftplib.rst:142 -msgid "" -"Several :class:`!FTP` methods are available in two flavors: one for handling " -"text files and another for binary files. The methods are named for the " -"command which is used followed by ``lines`` for the text version or " -"``binary`` for the binary version." -msgstr "" -":class:`!FTP` 的多個可用方法大致有分為兩個方向：一種用於處理文本檔案 (text " -"files)，另一種用於二進位檔案 (binary files)。這些以在文本檔案的 ``lines`` 或" -"二進位檔案的 ``binary`` 前使用的命令命名。" - -#: ../../library/ftplib.rst:147 -msgid ":class:`FTP` instances have the following methods:" -msgstr ":class:`FTP` 實例具有以下方法：" - -#: ../../library/ftplib.rst:151 -msgid "" -"Set the instance's debugging level as an :class:`int`. This controls the " -"amount of debugging output printed. The debug levels are:" -msgstr "將實例的偵錯級別設定為一個 :class:`int`，這控制印出的偵錯訊息輸出量。" - -#: ../../library/ftplib.rst:155 -msgid "``0`` (default): No debug output." -msgstr "``0``\\ （預設值）：不產生偵錯輸出。" - -#: ../../library/ftplib.rst:156 -msgid "" -"``1``: Produce a moderate amount of debug output, generally a single line " -"per request." -msgstr "``1``：會產生適量的偵錯輸出，通常是每個請求輸出一行。" - -#: ../../library/ftplib.rst:158 -msgid "" -"``2`` or higher: Produce the maximum amount of debugging output, logging " -"each line sent and received on the control connection." -msgstr "" -"``2`` 或更高的值：會產生最大量的偵錯輸出，以日誌紀錄下控制連線發送和接收的每" -"個步驟。" - -#: ../../library/ftplib.rst:163 -msgid "" -"Connect to the given host and port. This function should be called only once " -"for each instance; it should not be called if a *host* argument was given " -"when the :class:`FTP` instance was created. All other :class:`!FTP` methods " -"can only be called after a connection has successfully been made." -msgstr "" -"連線到給定的主機 (host) 和連接埠 (port)。每個實例只應呼叫此函式一次；如果在建" -"立 :class:`FTP` 實例時有給定 *host* 引數，則不應呼叫它。所有其他的 :class:`!" -"FTP` 方法只能在成功建立連線後使用。" - -#: ../../library/ftplib.rst:170 -msgid "The host to connect to." -msgstr "要連接的主機。" - -#: ../../library/ftplib.rst:173 -msgid "" -"The TCP port to connect to (default: ``21``, as specified by the FTP " -"protocol specification). It is rarely needed to specify a different port " -"number." -msgstr "" -"要連接的 TCP 連接埠（預設值：``21``，由 FTP 協定規範指定）。很少需要指定不同" -"的連接埠號碼。" - -#: ../../library/ftplib.rst:178 -msgid "" -"A timeout in seconds for the connection attempt (default: the global default " -"timeout setting)." -msgstr "連線嘗試的超時設定，以秒為單位（預設：全域預設超時設定）。" - -#: ../../library/ftplib.rst:187 -msgid "" -"Raises an :ref:`auditing event ` ``ftplib.connect`` with arguments " -"``self``, ``host``, ``port``." -msgstr "" -"引發一個附帶引數 ``self``、``host``、``port`` 的\\ :ref:`稽核事件 " -"` ``ftplib.connect``。" - -#: ../../library/ftplib.rst:195 -msgid "" -"Return the welcome message sent by the server in reply to the initial " -"connection. (This message sometimes contains disclaimers or help " -"information that may be relevant to the user.)" -msgstr "" -"回傳伺服器為回應初始連線而發送的歡迎訊息。（此訊息有時會包含與使用者相關的免" -"責聲明或幫助資訊。）" - -#: ../../library/ftplib.rst:202 -msgid "" -"Log on to the connected FTP server. This function should be called only once " -"for each instance, after a connection has been established; it should not be " -"called if the *host* and *user* arguments were given when the :class:`FTP` " -"instance was created. Most FTP commands are only allowed after the client " -"has logged in." -msgstr "" -"在以連線的伺服器上登入。在建立連線後，每個實例只應呼叫此函式一次；如果在建" -"立 :class:`FTP` 實例時有給定 *host* 和 *user* 引數，則不應呼叫它。大多數 FTP " -"命令僅在用戶端登錄後才允許使用" - -#: ../../library/ftplib.rst:209 -msgid "|param_doc_user|" -msgstr "|param_doc_user|" - -#: ../../library/ftplib.rst:221 -msgid "" -"Abort a file transfer that is in progress. Using this does not always work, " -"but it's worth a try." -msgstr "中止正在進行的檔案傳輸。使用它並不是都會成功，但值得一試。" - -#: ../../library/ftplib.rst:227 -msgid "" -"Send a simple command string to the server and return the response string." -msgstr "向伺服器發送一個簡單的命令字串並回傳回應字串。" - -#: ../../library/ftplib.rst:229 ../../library/ftplib.rst:238 -msgid "" -"Raises an :ref:`auditing event ` ``ftplib.sendcmd`` with arguments " -"``self``, ``cmd``." -msgstr "" -"引發一個附帶引數 ``self``、``cmd`` 的\\ :ref:`稽核事件 ` ``ftplib." -"sendcmd``。" - -#: ../../library/ftplib.rst:234 -msgid "" -"Send a simple command string to the server and handle the response. Return " -"the response string if the response code corresponds to success (codes in " -"the range 200--299). Raise :exc:`error_reply` otherwise." -msgstr "" -"向伺服器發送一個簡單的命令字串並處理回應。如果收到代表成功的回應狀態碼（範圍" -"為 200--299 的狀態碼），則回傳回應字串，否則引發 :exc:`error_reply`。" - -#: ../../library/ftplib.rst:243 -msgid "Retrieve a file in binary transfer mode." -msgstr "以二進位傳輸模式 (binary transfer mode) 取得檔案。" - -#: ../../library/ftplib.rst:245 -msgid "An appropriate ``RETR`` command: :samp:`\"RETR {filename}\"`." -msgstr "一個正確的 ``RETR`` 指令：:samp:`\"RETR {filename}\"`。" - -#: ../../library/ftplib.rst:248 -msgid "" -"A single parameter callable that is called for each block of data received, " -"with its single argument being the data as :class:`bytes`." -msgstr "" -"為接收到的每個資料區塊呼叫的單一參數可呼叫物件，其單一引數是以 :class:" -"`bytes` 為形式的資料。" - -#: ../../library/ftplib.rst:254 -msgid "" -"The maximum chunk size to read on the low-level :class:`~socket.socket` " -"object created to do the actual transfer. This also corresponds to the " -"largest size of data that will be passed to *callback*. Defaults to ``8192``." -msgstr "" -"在執行實際傳輸時所建立的低階 :class:`~socket.socket` 物件上讀取的最大分塊 " -"(chunk) 大小。這也對應於將傳遞給 *callback* 的最大資料大小。預設為 ``8192``。" - -#: ../../library/ftplib.rst:261 ../../library/ftplib.rst:308 -msgid "" -"A ``REST`` command to be sent to the server. See the documentation for the " -"*rest* parameter of the :meth:`transfercmd` method." -msgstr "" -"一個要發送到伺服器的 ``REST`` 命令。參見 :meth:`transfercmd` 方法之 *rest* 參" -"數的文件。" - -#: ../../library/ftplib.rst:268 -msgid "" -"Retrieve a file or directory listing in the encoding specified by the " -"*encoding* parameter at initialization. *cmd* should be an appropriate " -"``RETR`` command (see :meth:`retrbinary`) or a command such as ``LIST`` or " -"``NLST`` (usually just the string ``'LIST'``). ``LIST`` retrieves a list of " -"files and information about those files. ``NLST`` retrieves a list of file " -"names. The *callback* function is called for each line with a string " -"argument containing the line with the trailing CRLF stripped. The default " -"*callback* prints the line to :data:`sys.stdout`." -msgstr "" -"在初始化時以 *encoding* 參數指定的編碼來取得檔案或目錄列表。 *cmd* 要是一個正" -"確的 ``RETR`` 命令（見 :meth:`retrbinary`）或者一個像 ``LIST`` 或 ``NLST`` 的" -"命令（通常只是字串 ``'LIST'`` )。 ``LIST`` 會取得檔案列表和這些檔案的相關資" -"訊。 ``NLST`` 取得檔案名稱列表。會為每一行以一個字串引數呼叫 *callback* 函" -"式，其引數包含已經刪除尾隨 CRLF 的一行。預設的 *callback* 會將各行印出到 :" -"data:`sys.stdout`。" - -#: ../../library/ftplib.rst:281 -msgid "" -"Enable \"passive\" mode if *val* is true, otherwise disable passive mode. " -"Passive mode is on by default." -msgstr "" -"如果 *val* 為真，則啟用「被動」模式，否則禁用被動模式。被動模式預設開啟。" - -#: ../../library/ftplib.rst:287 -msgid "Store a file in binary transfer mode." -msgstr "以二進位傳輸模式儲存檔案。" - -#: ../../library/ftplib.rst:289 -msgid "An appropriate ``STOR`` command: :samp:`\"STOR {filename}\"`." -msgstr "一個正確的 ``STOR`` 指令：:samp:`\"STOR {filename}\"`。" - -#: ../../library/ftplib.rst:292 -msgid "" -"A file object (opened in binary mode) which is read until EOF, using its :" -"meth:`~io.RawIOBase.read` method in blocks of size *blocksize* to provide " -"the data to be stored." -msgstr "" -"一個檔案物件（以二進位模式開啟），在大小為 *blocksize* 的區塊中使用其 :meth:" -"`~io.RawIOBase.read` 方法讀取直到 EOF 來提供要儲存的資料。" - -#: ../../library/ftplib.rst:298 -msgid "The read block size. Defaults to ``8192``." -msgstr "讀取區塊大小。預設為 ``8192``。" - -#: ../../library/ftplib.rst:302 -msgid "" -"A single parameter callable that is called for each block of data sent, with " -"its single argument being the data as :class:`bytes`." -msgstr "" -"為發送的每個資料區塊來呼叫的單一參數可呼叫物件，其單一引數是以 :class:" -"`bytes` 為形式的資料。" - -#: ../../library/ftplib.rst:312 -msgid "The *rest* parameter was added." -msgstr "新增 *rest* 參數。" - -#: ../../library/ftplib.rst:318 -msgid "" -"Store a file in line mode. *cmd* should be an appropriate ``STOR`` command " -"(see :meth:`storbinary`). Lines are read until EOF from the :term:`file " -"object` *fp* (opened in binary mode) using its :meth:`~io.IOBase.readline` " -"method to provide the data to be stored. *callback* is an optional single " -"parameter callable that is called on each line after it is sent." -msgstr "" -"以行模式 (line mode) 儲存檔案。 *cmd* 應是一個正確的 ``STOR`` 命令（參見 :" -"meth:`storbinary`）。使用其 :meth:`~io.IOBase.readline` 方法從\\ :term:`檔案" -"物件 ` *fp* （以二進位模式打開）讀取各行、直到 EOF，以提供要儲存" -"的資料。 *callback* 是可選的單參數可呼叫物件，於發送後以各行進行呼叫。" - -#: ../../library/ftplib.rst:327 -msgid "" -"Initiate a transfer over the data connection. If the transfer is active, " -"send an ``EPRT`` or ``PORT`` command and the transfer command specified by " -"*cmd*, and accept the connection. If the server is passive, send an " -"``EPSV`` or ``PASV`` command, connect to it, and start the transfer " -"command. Either way, return the socket for the connection." -msgstr "" -"透過資料連線啟動傳輸。如果傳輸為主動 (active) 模式，則發送 ``EPRT`` 或 " -"``PORT`` 命令和 *cmd* 指定的傳輸命令，並接受連線。如果伺服器是被動 (passive) " -"模式，則發送 ``EPSV`` 或 ``PASV`` 命令、連線、並啟動傳輸命令。無論哪種方式，" -"都是回傳連線的 socket。" - -#: ../../library/ftplib.rst:333 -msgid "" -"If optional *rest* is given, a ``REST`` command is sent to the server, " -"passing *rest* as an argument. *rest* is usually a byte offset into the " -"requested file, telling the server to restart sending the file's bytes at " -"the requested offset, skipping over the initial bytes. Note however that " -"the :meth:`transfercmd` method converts *rest* to a string with the " -"*encoding* parameter specified at initialization, but no check is performed " -"on the string's contents. If the server does not recognize the ``REST`` " -"command, an :exc:`error_reply` exception will be raised. If this happens, " -"simply call :meth:`transfercmd` without a *rest* argument." -msgstr "" -"如果有給定可選的 *rest*，一個 ``REST`` 命令會被發送到伺服器，並以 *rest* 作為" -"引數。*rest* 通常是請求檔案的一個位元組偏移量 (byte offset)，告訴伺服器以請求" -"的偏移量重新開始發送檔案的位元組，並跳過初始位元組。但是請注意，:meth:" -"`transfercmd` 方法將 *rest* 轉換為帶有初始化時指定的 *encoding* 參數的字串，" -"但不會對字串的內容執行檢查。如果伺服器無法識別 ``REST`` 命令，則會引發 :exc:" -"`error_reply` 例外。如果發生這種情況，只需在沒有 *rest* 引數的情況下呼叫 :" -"meth:`transfercmd`。" - -#: ../../library/ftplib.rst:346 -msgid "" -"Like :meth:`transfercmd`, but returns a tuple of the data connection and the " -"expected size of the data. If the expected size could not be computed, " -"``None`` will be returned as the expected size. *cmd* and *rest* means the " -"same thing as in :meth:`transfercmd`." -msgstr "" -"類似於 :meth:`transfercmd`，但回傳一個帶有資料連線和資料預期大小的元組。如果" -"無法計算預期大小，則回傳 ``None``。 *cmd* 和 *rest* 與 :meth:`transfercmd` 中" -"的含義相同。" - -#: ../../library/ftplib.rst:354 -msgid "" -"List a directory in a standardized format by using ``MLSD`` command (:rfc:" -"`3659`). If *path* is omitted the current directory is assumed. *facts* is " -"a list of strings representing the type of information desired (e.g. " -"``[\"type\", \"size\", \"perm\"]``). Return a generator object yielding a " -"tuple of two elements for every file found in path. First element is the " -"file name, the second one is a dictionary containing facts about the file " -"name. Content of this dictionary might be limited by the *facts* argument " -"but server is not guaranteed to return all requested facts." -msgstr "" -"使用 ``MLSD`` 命令 (:rfc:`3659`) 列出標準格式的目錄。如果省略 *path* 則假定為" -"作用於目前目錄。*facts* 是表示所需資訊類型的字串列表（例如 ``[\"type\", " -"\"size\", \"perm\"]`` ）。會回傳一個產生器物件，為每個在路徑中找到的檔案生成" -"一個包含兩個元素的元組，第一個元素是檔案名稱，第二個元素是包含有關檔案名稱 " -"facts的字典。該字典的內容可能受 *facts* 引數限制，但不保證伺服器會回傳所有請" -"求的 facts。" - -#: ../../library/ftplib.rst:368 -msgid "" -"Return a list of file names as returned by the ``NLST`` command. The " -"optional *argument* is a directory to list (default is the current server " -"directory). Multiple arguments can be used to pass non-standard options to " -"the ``NLST`` command." -msgstr "" -"回傳由 ``NLST`` 命令回傳的檔案名稱列表。可選的 *argument* 是要列出的目錄（預" -"設為目前伺服器目錄）。多個引數可用於將非標準選項傳遞給 ``NLST`` 命令。" - -#: ../../library/ftplib.rst:373 ../../library/ftplib.rst:385 -msgid "If your server supports the command, :meth:`mlsd` offers a better API." -msgstr "如果你的伺服器支援該命令，:meth:`mlsd` 會提供更好的 API。" - -#: ../../library/ftplib.rst:378 -msgid "" -"Produce a directory listing as returned by the ``LIST`` command, printing it " -"to standard output. The optional *argument* is a directory to list (default " -"is the current server directory). Multiple arguments can be used to pass " -"non-standard options to the ``LIST`` command. If the last argument is a " -"function, it is used as a *callback* function as for :meth:`retrlines`; the " -"default prints to :data:`sys.stdout`. This method returns ``None``." -msgstr "" -"生成由 ``LIST`` 命令回傳的目錄列表，並將其印出到標準輸出 (standard output)。" -"可選的 *argument* 是要列出的目錄（預設為目前伺服器目錄）。有多個引數可用於將" -"非標準選項傳遞給 ``LIST`` 命令。如果最後一個引數是一個函式，它被用作 :meth:" -"`retrlines` 的 *callback* 函式；預設印出到 :data:`sys.stdout`。此方法回傳 " -"``None``。" - -#: ../../library/ftplib.rst:390 -msgid "Rename file *fromname* on the server to *toname*." -msgstr "將伺服器上的檔案 *fromname* 重新命名為 *toname*。" - -#: ../../library/ftplib.rst:395 -msgid "" -"Remove the file named *filename* from the server. If successful, returns " -"the text of the response, otherwise raises :exc:`error_perm` on permission " -"errors or :exc:`error_reply` on other errors." -msgstr "" -"從伺服器中刪除名為 *filename* 的檔案。如果成功，回傳回應的文字，否則引發 :" -"exc:`error_perm` 權限錯誤或在其他錯誤發生時引發 :exc:`error_reply`。" - -#: ../../library/ftplib.rst:402 -msgid "Set the current directory on the server." -msgstr "設定伺服器上的目前目錄。" - -#: ../../library/ftplib.rst:407 -msgid "Create a new directory on the server." -msgstr "在伺服器上建立一個新目錄。" - -#: ../../library/ftplib.rst:412 -msgid "Return the pathname of the current directory on the server." -msgstr "回傳伺服器上目前目錄的路徑名。" - -#: ../../library/ftplib.rst:417 -msgid "Remove the directory named *dirname* on the server." -msgstr "刪除伺服器上名為 *dirname* 的目錄。" - -#: ../../library/ftplib.rst:422 -msgid "" -"Request the size of the file named *filename* on the server. On success, " -"the size of the file is returned as an integer, otherwise ``None`` is " -"returned. Note that the ``SIZE`` command is not standardized, but is " -"supported by many common server implementations." -msgstr "" -"請求伺服器上名為 *filename* 的檔案的大小。成功時，檔案的大小作為整數回傳，否" -"則回傳 ``None``。請注意，``SIZE`` 命令不是標準化的，但被許多常見的伺服器實作" -"支援。" - -#: ../../library/ftplib.rst:430 -msgid "" -"Send a ``QUIT`` command to the server and close the connection. This is the " -"\"polite\" way to close a connection, but it may raise an exception if the " -"server responds with an error to the ``QUIT`` command. This implies a call " -"to the :meth:`close` method which renders the :class:`FTP` instance useless " -"for subsequent calls (see below)." -msgstr "" -"向伺服器發送 ``QUIT`` 命令並關閉連線。這是關閉連線的「禮貌」方式，但如果伺服" -"器對 ``QUIT`` 命令作出錯誤回應，它可能會引發例外。這意味著呼叫 :meth:`close` " -"方法使 :class:`FTP` 實例無法用於後續呼叫（見下文）。" - -#: ../../library/ftplib.rst:439 -msgid "" -"Close the connection unilaterally. This should not be applied to an already " -"closed connection such as after a successful call to :meth:`~FTP.quit`. " -"After this call the :class:`FTP` instance should not be used any more (after " -"a call to :meth:`close` or :meth:`~FTP.quit` you cannot reopen the " -"connection by issuing another :meth:`login` method)." -msgstr "" -"單方面關閉連線。這不應該使用於已經關閉的連線，例如在成功呼叫 :meth:`~FTP." -"quit` 之後。呼叫後就不應該再次使用 :class:`FTP` 實例（在呼叫 :meth:`close` " -"或 :meth:`~FTP.quit` 後，你不能透過發出另一個 :meth:`login` 方法重新打開連" -"線）。" - -#: ../../library/ftplib.rst:447 -msgid "FTP_TLS objects" -msgstr "FTP_TLS 物件" - -#: ../../library/ftplib.rst:452 -msgid "" -"An :class:`FTP` subclass which adds TLS support to FTP as described in :rfc:" -"`4217`. Connect to port 21 implicitly securing the FTP control connection " -"before authenticating." -msgstr "" - -#: ../../library/ftplib.rst:458 -msgid "" -"The user must explicitly secure the data connection by calling the :meth:" -"`prot_p` method." -msgstr "" - -#: ../../library/ftplib.rst:476 -msgid "" -"An SSL context object which allows bundling SSL configuration options, " -"certificates and private keys into a single, potentially long-lived, " -"structure. Please read :ref:`ssl-security` for best practices." -msgstr "" - -#: ../../library/ftplib.rst:483 -msgid "" -"A timeout in seconds for blocking operations like :meth:`~FTP.connect` " -"(default: the global default timeout setting)." -msgstr "" -"如 :meth:`~FTP.connect` 的阻塞操作的超時設定，以秒為單位（預設：使用全域預設" -"超時設定）。" - -#: ../../library/ftplib.rst:497 -msgid "Added the *source_address* parameter." -msgstr "新增 *source_address* 參數。" - -#: ../../library/ftplib.rst:500 -msgid "" -"The class now supports hostname check with :attr:`ssl.SSLContext." -"check_hostname` and *Server Name Indication* (see :const:`ssl.HAS_SNI`)." -msgstr "" -"該類別現在支援使用 :attr:`ssl.SSLContext.check_hostname` 和 *Server Name " -"Indication* 進行主機名 (hostname) 檢查（參見 :const:`ssl.HAS_SNI`）。" - -#: ../../library/ftplib.rst:511 -msgid "The deprecated *keyfile* and *certfile* parameters have been removed." -msgstr "已棄用的 *keyfile* 和 *certfile* 參數已被移除。" - -#: ../../library/ftplib.rst:514 -msgid "Here's a sample session using the :class:`FTP_TLS` class::" -msgstr "這是一個使用 :class:`FTP_TLS` 類別的範例會話：" - -#: ../../library/ftplib.rst:516 -msgid "" -">>> ftps = FTP_TLS('ftp.pureftpd.org')\n" -">>> ftps.login()\n" -"'230 Anonymous user logged in'\n" -">>> ftps.prot_p()\n" -"'200 Data protection level set to \"private\"'\n" -">>> ftps.nlst()\n" -"['6jack', 'OpenBSD', 'antilink', 'blogbench', 'bsdcam', 'clockspeed', " -"'djbdns-jedi', 'docs', 'eaccelerator-jedi', 'favicon.ico', 'francotone', " -"'fugu', 'ignore', 'libpuzzle', 'metalog', 'minidentd', 'misc', 'mysql-udf-" -"global-user-variables', 'php-jenkins-hash', 'php-skein-hash', 'php-webdav', " -"'phpaudit', 'phpbench', 'pincaster', 'ping', 'posto', 'pub', 'public', " -"'public_keys', 'pure-ftpd', 'qscan', 'qtc', 'sharedance', 'skycache', " -"'sound', 'tmp', 'ucarp']" -msgstr "" -">>> ftps = FTP_TLS('ftp.pureftpd.org')\n" -">>> ftps.login()\n" -"'230 Anonymous user logged in'\n" -">>> ftps.prot_p()\n" -"'200 Data protection level set to \"private\"'\n" -">>> ftps.nlst()\n" -"['6jack', 'OpenBSD', 'antilink', 'blogbench', 'bsdcam', 'clockspeed', " -"'djbdns-jedi', 'docs', 'eaccelerator-jedi', 'favicon.ico', 'francotone', " -"'fugu', 'ignore', 'libpuzzle', 'metalog', 'minidentd', 'misc', 'mysql-udf-" -"global-user-variables', 'php-jenkins-hash', 'php-skein-hash', 'php-webdav', " -"'phpaudit', 'phpbench', 'pincaster', 'ping', 'posto', 'pub', 'public', " -"'public_keys', 'pure-ftpd', 'qscan', 'qtc', 'sharedance', 'skycache', " -"'sound', 'tmp', 'ucarp']" - -#: ../../library/ftplib.rst:524 -msgid "" -":class:`!FTP_TLS` class inherits from :class:`FTP`, defining these " -"additional methods and attributes:" -msgstr "" -":class:`!FTP_TLS` 類別繼承自 :class:`FTP`，並另外定義了這些的方法與屬性：" - -#: ../../library/ftplib.rst:529 -msgid "The SSL version to use (defaults to :data:`ssl.PROTOCOL_SSLv23`)." -msgstr "要使用的 SSL 版本（預設為 :data:`ssl.PROTOCOL_SSLv23`）。" - -#: ../../library/ftplib.rst:533 -msgid "" -"Set up a secure control connection by using TLS or SSL, depending on what is " -"specified in the :attr:`ssl_version` attribute." -msgstr "" -"根據 :attr:`ssl_version` 屬性中指定的內容，使用 TLS 或 SSL 設定安全控制連線。" - -#: ../../library/ftplib.rst:536 -msgid "" -"The method now supports hostname check with :attr:`ssl.SSLContext." -"check_hostname` and *Server Name Indication* (see :const:`ssl.HAS_SNI`)." -msgstr "" -"該方法現在支援使用 :attr:`ssl.SSLContext.check_hostname` 和 *Server Name " -"Indication* 進行主機名檢查（參見 :const:`ssl.HAS_SNI`）。" - -#: ../../library/ftplib.rst:543 -msgid "" -"Revert control channel back to plaintext. This can be useful to take " -"advantage of firewalls that know how to handle NAT with non-secure FTP " -"without opening fixed ports." -msgstr "" -"將控制通道恢復為純文本。這對於利用知道如何在不打開固定連接埠的情況下使用非安" -"全 (non-secure) FTP 以處理 NAT 的防火牆很有用。" - -#: ../../library/ftplib.rst:551 -msgid "Set up secure data connection." -msgstr "設定安全資料連線。" - -#: ../../library/ftplib.rst:555 -msgid "Set up clear text data connection." -msgstr "設定明文資料 (clear text data) 連線。" - -#: ../../library/ftplib.rst:559 -msgid "Module variables" -msgstr "模組變數" - -#: ../../library/ftplib.rst:563 -msgid "Exception raised when an unexpected reply is received from the server." -msgstr "伺服器收到意外回覆時所引發的例外。" - -#: ../../library/ftplib.rst:568 -msgid "" -"Exception raised when an error code signifying a temporary error (response " -"codes in the range 400--499) is received." -msgstr "" -"當收到表示暫時錯誤的錯誤碼（400--499 範圍內的回應狀態碼）時引發的例外。" - -#: ../../library/ftplib.rst:574 -msgid "" -"Exception raised when an error code signifying a permanent error (response " -"codes in the range 500--599) is received." -msgstr "" -"當收到表示永久錯誤的錯誤碼（500--599 範圍內的回應狀態碼）時引發的例外。" - -#: ../../library/ftplib.rst:580 -msgid "" -"Exception raised when a reply is received from the server that does not fit " -"the response specifications of the File Transfer Protocol, i.e. begin with a " -"digit in the range 1--5." -msgstr "" -"當從伺服器收到不符合檔案傳輸協定回應規範的回覆時引發例外，即 1--5 範圍內的數" -"字開頭。" - -#: ../../library/ftplib.rst:587 -msgid "" -"The set of all exceptions (as a tuple) that methods of :class:`FTP` " -"instances may raise as a result of problems with the FTP connection (as " -"opposed to programming errors made by the caller). This set includes the " -"four exceptions listed above as well as :exc:`OSError` and :exc:`EOFError`." -msgstr "" -":class:`FTP` 實例方法由於 FTP 連線問題（相對於呼叫者的程式錯誤）而可能引發的" -"所有例外集合（元組形式）。該集合包括上面列出的四個例外以及 :exc:`OSError` " -"和 :exc:`EOFError`。" - -#: ../../library/ftplib.rst:595 -msgid "Module :mod:`netrc`" -msgstr ":mod:`netrc` 模組" - -#: ../../library/ftplib.rst:596 -msgid "" -"Parser for the :file:`.netrc` file format. The file :file:`.netrc` is " -"typically used by FTP clients to load user authentication information before " -"prompting the user." -msgstr "" -":file:`.netrc` 檔案格式的剖析器。:file:`.netrc` 檔案通常被 FTP 用戶端用來在提" -"示使用者之前載入使用者身份驗證資訊。" - -#: ../../library/ftplib.rst:9 -msgid "FTP" -msgstr "FTP" - -#: ../../library/ftplib.rst:9 -msgid "protocol" -msgstr "protocol（協定）" - -#: ../../library/ftplib.rst:9 -msgid "ftplib (standard module)" -msgstr "ftplib（標準模組）" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Matt Wang , 2023-2024 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-10-11 00:13+0000\n" +"PO-Revision-Date: 2023-04-26 19:44+0800\n" +"Last-Translator: Matt Wang \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" +"X-Generator: Poedit 3.2.2\n" + +#: ../../library/ftplib.rst:2 +msgid ":mod:`!ftplib` --- FTP protocol client" +msgstr ":mod:`!ftplib` --- FTP 協定用戶端" + +#: ../../library/ftplib.rst:7 +msgid "**Source code:** :source:`Lib/ftplib.py`" +msgstr "**原始碼：**\\ :source:`Lib/ftplib.py`" + +#: ../../library/ftplib.rst:15 +msgid "" +"This module defines the class :class:`FTP` and a few related items. The :" +"class:`FTP` class implements the client side of the FTP protocol. You can " +"use this to write Python programs that perform a variety of automated FTP " +"jobs, such as mirroring other FTP servers. It is also used by the module :" +"mod:`urllib.request` to handle URLs that use FTP. For more information on " +"FTP (File Transfer Protocol), see internet :rfc:`959`." +msgstr "" +"這個模組定義了 :class:`FTP` 類別和一些相關的項目。:class:`FTP` 類別實作了 " +"FTP 協定的用戶端。你可以使用它來編寫能夠執行各種 FTP 自動作業的 Python 程式，" +"例如鏡像 (mirror) 其他 FTP 伺服器。:mod:`urllib.request` 模組也使用它來處理使" +"用 FTP 的 URL。有關 FTP（檔案傳輸協定）的更多資訊，請參閱 :rfc:`959`。" + +#: ../../library/ftplib.rst:22 +msgid "The default encoding is UTF-8, following :rfc:`2640`." +msgstr "預設編碼是 UTF-8，遵循 :rfc:`2640`。" + +#: ../../includes/wasm-notavail.rst:3 +msgid "Availability" +msgstr "可用性" + +#: ../../includes/wasm-notavail.rst:5 +msgid "" +"This module does not work or is not available on WebAssembly. See :ref:`wasm-" +"availability` for more information." +msgstr "" +"此模組在 WebAssembly 平台上不起作用或無法使用。更多資訊請參閱 :ref:`wasm-" +"availability`。" + +#: ../../library/ftplib.rst:26 +msgid "Here's a sample session using the :mod:`ftplib` module::" +msgstr "這是一個使用 :mod:`ftplib` 模組的會話範例：" + +#: ../../library/ftplib.rst:28 +msgid "" +">>> from ftplib import FTP\n" +">>> ftp = FTP('ftp.us.debian.org') # connect to host, default port\n" +">>> ftp.login() # user anonymous, passwd anonymous@\n" +"'230 Login successful.'\n" +">>> ftp.cwd('debian') # change into \"debian\" directory\n" +"'250 Directory successfully changed.'\n" +">>> ftp.retrlines('LIST') # list directory contents\n" +"-rw-rw-r-- 1 1176 1176 1063 Jun 15 10:18 README\n" +"...\n" +"drwxr-sr-x 5 1176 1176 4096 Dec 19 2000 pool\n" +"drwxr-sr-x 4 1176 1176 4096 Nov 17 2008 project\n" +"drwxr-xr-x 3 1176 1176 4096 Oct 10 2012 tools\n" +"'226 Directory send OK.'\n" +">>> with open('README', 'wb') as fp:\n" +">>> ftp.retrbinary('RETR README', fp.write)\n" +"'226 Transfer complete.'\n" +">>> ftp.quit()\n" +"'221 Goodbye.'" +msgstr "" + +#: ../../library/ftplib.rst:51 +msgid "Reference" +msgstr "參考" + +#: ../../library/ftplib.rst:56 +msgid "FTP objects" +msgstr "FTP 物件" + +#: ../../library/ftplib.rst:87 +msgid "Return a new instance of the :class:`FTP` class." +msgstr "回傳一個新的 :class:`FTP` 類別實例。" + +#: ../../library/ftplib.rst:0 +msgid "Parameters" +msgstr "參數" + +#: ../../library/ftplib.rst:89 ../../library/ftplib.rst:461 +msgid "" +"The hostname to connect to. If given, :code:`connect(host)` is implicitly " +"called by the constructor." +msgstr "" +"要連接的主機名稱。如果有給定，:code:`connect(host)` 會由建構函式來隱式地呼" +"叫。" + +#: ../../library/ftplib.rst:93 ../../library/ftplib.rst:465 +msgid "" +"|param_doc_user| If given, :code:`login(host, passwd, acct)` is implicitly " +"called by the constructor." +msgstr "" +"|param_doc_user| 如果有給定，:code:`login(host, passwd, acct)` 會由建構函式來" +"隱式地呼叫。" + +#: ../../library/ftplib.rst:98 ../../library/ftplib.rst:212 +#: ../../library/ftplib.rst:470 +msgid "|param_doc_passwd|" +msgstr "|param_doc_passwd|" + +#: ../../library/ftplib.rst:101 ../../library/ftplib.rst:215 +#: ../../library/ftplib.rst:473 +msgid "|param_doc_acct|" +msgstr "|param_doc_acct|" + +#: ../../library/ftplib.rst:104 +msgid "" +"A timeout in seconds for blocking operations like :meth:`connect` (default: " +"the global default timeout setting)." +msgstr "" +"如 :meth:`connect` 的阻塞操作的超時設定，以秒為單位（預設：使用全域預設超時設" +"定）。" + +#: ../../library/ftplib.rst:109 ../../library/ftplib.rst:183 +#: ../../library/ftplib.rst:488 +msgid "|param_doc_source_address|" +msgstr "|param_doc_source_address|" + +#: ../../library/ftplib.rst:113 ../../library/ftplib.rst:492 +msgid "|param_doc_encoding|" +msgstr "|param_doc_encoding|" + +#: ../../library/ftplib.rst:116 +msgid "The :class:`FTP` class supports the :keyword:`with` statement, e.g.:" +msgstr ":class:`FTP` 類別支援 :keyword:`with` 陳述式，例如：" + +#: ../../library/ftplib.rst:130 +msgid "Support for the :keyword:`with` statement was added." +msgstr "新增了對 :keyword:`with` 陳述式的支援。" + +#: ../../library/ftplib.rst:133 ../../library/ftplib.rst:189 +msgid "*source_address* parameter was added." +msgstr "新增 *source_address* 參數。" + +#: ../../library/ftplib.rst:136 ../../library/ftplib.rst:505 +msgid "" +"If the *timeout* parameter is set to be zero, it will raise a :class:" +"`ValueError` to prevent the creation of a non-blocking socket. The " +"*encoding* parameter was added, and the default was changed from Latin-1 to " +"UTF-8 to follow :rfc:`2640`." +msgstr "" +"如果 *timeout* 參數設定為零，它將引發 :class:`ValueError` 以防止建立非阻塞 " +"socket。新增了 *encoding* 參數，預設值從 Latin-1 更改為 UTF-8 以遵循 :rfc:" +"`2640`。" + +#: ../../library/ftplib.rst:142 +msgid "" +"Several :class:`!FTP` methods are available in two flavors: one for handling " +"text files and another for binary files. The methods are named for the " +"command which is used followed by ``lines`` for the text version or " +"``binary`` for the binary version." +msgstr "" +":class:`!FTP` 的多個可用方法大致有分為兩個方向：一種用於處理文本檔案 (text " +"files)，另一種用於二進位檔案 (binary files)。這些以在文本檔案的 ``lines`` 或" +"二進位檔案的 ``binary`` 前使用的命令命名。" + +#: ../../library/ftplib.rst:147 +msgid ":class:`FTP` instances have the following methods:" +msgstr ":class:`FTP` 實例具有以下方法：" + +#: ../../library/ftplib.rst:151 +msgid "" +"Set the instance's debugging level as an :class:`int`. This controls the " +"amount of debugging output printed. The debug levels are:" +msgstr "將實例的偵錯級別設定為一個 :class:`int`，這控制印出的偵錯訊息輸出量。" + +#: ../../library/ftplib.rst:155 +msgid "``0`` (default): No debug output." +msgstr "``0``\\ （預設值）：不產生偵錯輸出。" + +#: ../../library/ftplib.rst:156 +msgid "" +"``1``: Produce a moderate amount of debug output, generally a single line " +"per request." +msgstr "``1``：會產生適量的偵錯輸出，通常是每個請求輸出一行。" + +#: ../../library/ftplib.rst:158 +msgid "" +"``2`` or higher: Produce the maximum amount of debugging output, logging " +"each line sent and received on the control connection." +msgstr "" +"``2`` 或更高的值：會產生最大量的偵錯輸出，以日誌紀錄下控制連線發送和接收的每" +"個步驟。" + +#: ../../library/ftplib.rst:163 +msgid "" +"Connect to the given host and port. This function should be called only once " +"for each instance; it should not be called if a *host* argument was given " +"when the :class:`FTP` instance was created. All other :class:`!FTP` methods " +"can only be called after a connection has successfully been made." +msgstr "" +"連線到給定的主機 (host) 和連接埠 (port)。每個實例只應呼叫此函式一次；如果在建" +"立 :class:`FTP` 實例時有給定 *host* 引數，則不應呼叫它。所有其他的 :class:`!" +"FTP` 方法只能在成功建立連線後使用。" + +#: ../../library/ftplib.rst:170 +msgid "The host to connect to." +msgstr "要連接的主機。" + +#: ../../library/ftplib.rst:173 +msgid "" +"The TCP port to connect to (default: ``21``, as specified by the FTP " +"protocol specification). It is rarely needed to specify a different port " +"number." +msgstr "" +"要連接的 TCP 連接埠（預設值：``21``，由 FTP 協定規範指定）。很少需要指定不同" +"的連接埠號碼。" + +#: ../../library/ftplib.rst:178 +msgid "" +"A timeout in seconds for the connection attempt (default: the global default " +"timeout setting)." +msgstr "連線嘗試的超時設定，以秒為單位（預設：全域預設超時設定）。" + +#: ../../library/ftplib.rst:187 +msgid "" +"Raises an :ref:`auditing event ` ``ftplib.connect`` with arguments " +"``self``, ``host``, ``port``." +msgstr "" +"引發一個附帶引數 ``self``、``host``、``port`` 的\\ :ref:`稽核事件 " +"` ``ftplib.connect``。" + +#: ../../library/ftplib.rst:195 +msgid "" +"Return the welcome message sent by the server in reply to the initial " +"connection. (This message sometimes contains disclaimers or help " +"information that may be relevant to the user.)" +msgstr "" +"回傳伺服器為回應初始連線而發送的歡迎訊息。（此訊息有時會包含與使用者相關的免" +"責聲明或幫助資訊。）" + +#: ../../library/ftplib.rst:202 +msgid "" +"Log on to the connected FTP server. This function should be called only once " +"for each instance, after a connection has been established; it should not be " +"called if the *host* and *user* arguments were given when the :class:`FTP` " +"instance was created. Most FTP commands are only allowed after the client " +"has logged in." +msgstr "" +"在以連線的伺服器上登入。在建立連線後，每個實例只應呼叫此函式一次；如果在建" +"立 :class:`FTP` 實例時有給定 *host* 和 *user* 引數，則不應呼叫它。大多數 FTP " +"命令僅在用戶端登錄後才允許使用" + +#: ../../library/ftplib.rst:209 +msgid "|param_doc_user|" +msgstr "|param_doc_user|" + +#: ../../library/ftplib.rst:221 +msgid "" +"Abort a file transfer that is in progress. Using this does not always work, " +"but it's worth a try." +msgstr "中止正在進行的檔案傳輸。使用它並不是都會成功，但值得一試。" + +#: ../../library/ftplib.rst:227 +msgid "" +"Send a simple command string to the server and return the response string." +msgstr "向伺服器發送一個簡單的命令字串並回傳回應字串。" + +#: ../../library/ftplib.rst:229 ../../library/ftplib.rst:238 +msgid "" +"Raises an :ref:`auditing event ` ``ftplib.sendcmd`` with arguments " +"``self``, ``cmd``." +msgstr "" +"引發一個附帶引數 ``self``、``cmd`` 的\\ :ref:`稽核事件 ` ``ftplib." +"sendcmd``。" + +#: ../../library/ftplib.rst:234 +msgid "" +"Send a simple command string to the server and handle the response. Return " +"the response string if the response code corresponds to success (codes in " +"the range 200--299). Raise :exc:`error_reply` otherwise." +msgstr "" +"向伺服器發送一個簡單的命令字串並處理回應。如果收到代表成功的回應狀態碼（範圍" +"為 200--299 的狀態碼），則回傳回應字串，否則引發 :exc:`error_reply`。" + +#: ../../library/ftplib.rst:243 +msgid "Retrieve a file in binary transfer mode." +msgstr "以二進位傳輸模式 (binary transfer mode) 取得檔案。" + +#: ../../library/ftplib.rst:245 +msgid "An appropriate ``RETR`` command: :samp:`\"RETR {filename}\"`." +msgstr "一個正確的 ``RETR`` 指令：:samp:`\"RETR {filename}\"`。" + +#: ../../library/ftplib.rst:248 +msgid "" +"A single parameter callable that is called for each block of data received, " +"with its single argument being the data as :class:`bytes`." +msgstr "" +"為接收到的每個資料區塊呼叫的單一參數可呼叫物件，其單一引數是以 :class:" +"`bytes` 為形式的資料。" + +#: ../../library/ftplib.rst:254 +msgid "" +"The maximum chunk size to read on the low-level :class:`~socket.socket` " +"object created to do the actual transfer. This also corresponds to the " +"largest size of data that will be passed to *callback*. Defaults to ``8192``." +msgstr "" +"在執行實際傳輸時所建立的低階 :class:`~socket.socket` 物件上讀取的最大分塊 " +"(chunk) 大小。這也對應於將傳遞給 *callback* 的最大資料大小。預設為 ``8192``。" + +#: ../../library/ftplib.rst:261 ../../library/ftplib.rst:308 +msgid "" +"A ``REST`` command to be sent to the server. See the documentation for the " +"*rest* parameter of the :meth:`transfercmd` method." +msgstr "" +"一個要發送到伺服器的 ``REST`` 命令。參見 :meth:`transfercmd` 方法之 *rest* 參" +"數的文件。" + +#: ../../library/ftplib.rst:268 +msgid "" +"Retrieve a file or directory listing in the encoding specified by the " +"*encoding* parameter at initialization. *cmd* should be an appropriate " +"``RETR`` command (see :meth:`retrbinary`) or a command such as ``LIST`` or " +"``NLST`` (usually just the string ``'LIST'``). ``LIST`` retrieves a list of " +"files and information about those files. ``NLST`` retrieves a list of file " +"names. The *callback* function is called for each line with a string " +"argument containing the line with the trailing CRLF stripped. The default " +"*callback* prints the line to :data:`sys.stdout`." +msgstr "" +"在初始化時以 *encoding* 參數指定的編碼來取得檔案或目錄列表。 *cmd* 要是一個正" +"確的 ``RETR`` 命令（見 :meth:`retrbinary`）或者一個像 ``LIST`` 或 ``NLST`` 的" +"命令（通常只是字串 ``'LIST'`` )。 ``LIST`` 會取得檔案列表和這些檔案的相關資" +"訊。 ``NLST`` 取得檔案名稱列表。會為每一行以一個字串引數呼叫 *callback* 函" +"式，其引數包含已經刪除尾隨 CRLF 的一行。預設的 *callback* 會將各行印出到 :" +"data:`sys.stdout`。" + +#: ../../library/ftplib.rst:281 +msgid "" +"Enable \"passive\" mode if *val* is true, otherwise disable passive mode. " +"Passive mode is on by default." +msgstr "" +"如果 *val* 為真，則啟用「被動」模式，否則禁用被動模式。被動模式預設開啟。" + +#: ../../library/ftplib.rst:287 +msgid "Store a file in binary transfer mode." +msgstr "以二進位傳輸模式儲存檔案。" + +#: ../../library/ftplib.rst:289 +msgid "An appropriate ``STOR`` command: :samp:`\"STOR {filename}\"`." +msgstr "一個正確的 ``STOR`` 指令：:samp:`\"STOR {filename}\"`。" + +#: ../../library/ftplib.rst:292 +msgid "" +"A file object (opened in binary mode) which is read until EOF, using its :" +"meth:`~io.RawIOBase.read` method in blocks of size *blocksize* to provide " +"the data to be stored." +msgstr "" +"一個檔案物件（以二進位模式開啟），在大小為 *blocksize* 的區塊中使用其 :meth:" +"`~io.RawIOBase.read` 方法讀取直到 EOF 來提供要儲存的資料。" + +#: ../../library/ftplib.rst:298 +msgid "The read block size. Defaults to ``8192``." +msgstr "讀取區塊大小。預設為 ``8192``。" + +#: ../../library/ftplib.rst:302 +msgid "" +"A single parameter callable that is called for each block of data sent, with " +"its single argument being the data as :class:`bytes`." +msgstr "" +"為發送的每個資料區塊來呼叫的單一參數可呼叫物件，其單一引數是以 :class:" +"`bytes` 為形式的資料。" + +#: ../../library/ftplib.rst:312 +msgid "The *rest* parameter was added." +msgstr "新增 *rest* 參數。" + +#: ../../library/ftplib.rst:318 +msgid "" +"Store a file in line mode. *cmd* should be an appropriate ``STOR`` command " +"(see :meth:`storbinary`). Lines are read until EOF from the :term:`file " +"object` *fp* (opened in binary mode) using its :meth:`~io.IOBase.readline` " +"method to provide the data to be stored. *callback* is an optional single " +"parameter callable that is called on each line after it is sent." +msgstr "" +"以行模式 (line mode) 儲存檔案。 *cmd* 應是一個正確的 ``STOR`` 命令（參見 :" +"meth:`storbinary`）。使用其 :meth:`~io.IOBase.readline` 方法從\\ :term:`檔案" +"物件 ` *fp* （以二進位模式打開）讀取各行、直到 EOF，以提供要儲存" +"的資料。 *callback* 是可選的單參數可呼叫物件，於發送後以各行進行呼叫。" + +#: ../../library/ftplib.rst:327 +msgid "" +"Initiate a transfer over the data connection. If the transfer is active, " +"send an ``EPRT`` or ``PORT`` command and the transfer command specified by " +"*cmd*, and accept the connection. If the server is passive, send an " +"``EPSV`` or ``PASV`` command, connect to it, and start the transfer " +"command. Either way, return the socket for the connection." +msgstr "" +"透過資料連線啟動傳輸。如果傳輸為主動 (active) 模式，則發送 ``EPRT`` 或 " +"``PORT`` 命令和 *cmd* 指定的傳輸命令，並接受連線。如果伺服器是被動 (passive) " +"模式，則發送 ``EPSV`` 或 ``PASV`` 命令、連線、並啟動傳輸命令。無論哪種方式，" +"都是回傳連線的 socket。" + +#: ../../library/ftplib.rst:333 +msgid "" +"If optional *rest* is given, a ``REST`` command is sent to the server, " +"passing *rest* as an argument. *rest* is usually a byte offset into the " +"requested file, telling the server to restart sending the file's bytes at " +"the requested offset, skipping over the initial bytes. Note however that " +"the :meth:`transfercmd` method converts *rest* to a string with the " +"*encoding* parameter specified at initialization, but no check is performed " +"on the string's contents. If the server does not recognize the ``REST`` " +"command, an :exc:`error_reply` exception will be raised. If this happens, " +"simply call :meth:`transfercmd` without a *rest* argument." +msgstr "" +"如果有給定可選的 *rest*，一個 ``REST`` 命令會被發送到伺服器，並以 *rest* 作為" +"引數。*rest* 通常是請求檔案的一個位元組偏移量 (byte offset)，告訴伺服器以請求" +"的偏移量重新開始發送檔案的位元組，並跳過初始位元組。但是請注意，:meth:" +"`transfercmd` 方法將 *rest* 轉換為帶有初始化時指定的 *encoding* 參數的字串，" +"但不會對字串的內容執行檢查。如果伺服器無法識別 ``REST`` 命令，則會引發 :exc:" +"`error_reply` 例外。如果發生這種情況，只需在沒有 *rest* 引數的情況下呼叫 :" +"meth:`transfercmd`。" + +#: ../../library/ftplib.rst:346 +msgid "" +"Like :meth:`transfercmd`, but returns a tuple of the data connection and the " +"expected size of the data. If the expected size could not be computed, " +"``None`` will be returned as the expected size. *cmd* and *rest* means the " +"same thing as in :meth:`transfercmd`." +msgstr "" +"類似於 :meth:`transfercmd`，但回傳一個帶有資料連線和資料預期大小的元組。如果" +"無法計算預期大小，則回傳 ``None``。 *cmd* 和 *rest* 與 :meth:`transfercmd` 中" +"的含義相同。" + +#: ../../library/ftplib.rst:354 +msgid "" +"List a directory in a standardized format by using ``MLSD`` command (:rfc:" +"`3659`). If *path* is omitted the current directory is assumed. *facts* is " +"a list of strings representing the type of information desired (e.g. " +"``[\"type\", \"size\", \"perm\"]``). Return a generator object yielding a " +"tuple of two elements for every file found in path. First element is the " +"file name, the second one is a dictionary containing facts about the file " +"name. Content of this dictionary might be limited by the *facts* argument " +"but server is not guaranteed to return all requested facts." +msgstr "" +"使用 ``MLSD`` 命令 (:rfc:`3659`) 列出標準格式的目錄。如果省略 *path* 則假定為" +"作用於目前目錄。*facts* 是表示所需資訊類型的字串列表（例如 ``[\"type\", " +"\"size\", \"perm\"]`` ）。會回傳一個產生器物件，為每個在路徑中找到的檔案生成" +"一個包含兩個元素的元組，第一個元素是檔案名稱，第二個元素是包含有關檔案名稱 " +"facts的字典。該字典的內容可能受 *facts* 引數限制，但不保證伺服器會回傳所有請" +"求的 facts。" + +#: ../../library/ftplib.rst:368 +msgid "" +"Return a list of file names as returned by the ``NLST`` command. The " +"optional *argument* is a directory to list (default is the current server " +"directory). Multiple arguments can be used to pass non-standard options to " +"the ``NLST`` command." +msgstr "" +"回傳由 ``NLST`` 命令回傳的檔案名稱列表。可選的 *argument* 是要列出的目錄（預" +"設為目前伺服器目錄）。多個引數可用於將非標準選項傳遞給 ``NLST`` 命令。" + +#: ../../library/ftplib.rst:373 ../../library/ftplib.rst:385 +msgid "If your server supports the command, :meth:`mlsd` offers a better API." +msgstr "如果你的伺服器支援該命令，:meth:`mlsd` 會提供更好的 API。" + +#: ../../library/ftplib.rst:378 +msgid "" +"Produce a directory listing as returned by the ``LIST`` command, printing it " +"to standard output. The optional *argument* is a directory to list (default " +"is the current server directory). Multiple arguments can be used to pass " +"non-standard options to the ``LIST`` command. If the last argument is a " +"function, it is used as a *callback* function as for :meth:`retrlines`; the " +"default prints to :data:`sys.stdout`. This method returns ``None``." +msgstr "" +"生成由 ``LIST`` 命令回傳的目錄列表，並將其印出到標準輸出 (standard output)。" +"可選的 *argument* 是要列出的目錄（預設為目前伺服器目錄）。有多個引數可用於將" +"非標準選項傳遞給 ``LIST`` 命令。如果最後一個引數是一個函式，它被用作 :meth:" +"`retrlines` 的 *callback* 函式；預設印出到 :data:`sys.stdout`。此方法回傳 " +"``None``。" + +#: ../../library/ftplib.rst:390 +msgid "Rename file *fromname* on the server to *toname*." +msgstr "將伺服器上的檔案 *fromname* 重新命名為 *toname*。" + +#: ../../library/ftplib.rst:395 +msgid "" +"Remove the file named *filename* from the server. If successful, returns " +"the text of the response, otherwise raises :exc:`error_perm` on permission " +"errors or :exc:`error_reply` on other errors." +msgstr "" +"從伺服器中刪除名為 *filename* 的檔案。如果成功，回傳回應的文字，否則引發 :" +"exc:`error_perm` 權限錯誤或在其他錯誤發生時引發 :exc:`error_reply`。" + +#: ../../library/ftplib.rst:402 +msgid "Set the current directory on the server." +msgstr "設定伺服器上的目前目錄。" + +#: ../../library/ftplib.rst:407 +msgid "Create a new directory on the server." +msgstr "在伺服器上建立一個新目錄。" + +#: ../../library/ftplib.rst:412 +msgid "Return the pathname of the current directory on the server." +msgstr "回傳伺服器上目前目錄的路徑名。" + +#: ../../library/ftplib.rst:417 +msgid "Remove the directory named *dirname* on the server." +msgstr "刪除伺服器上名為 *dirname* 的目錄。" + +#: ../../library/ftplib.rst:422 +msgid "" +"Request the size of the file named *filename* on the server. On success, " +"the size of the file is returned as an integer, otherwise ``None`` is " +"returned. Note that the ``SIZE`` command is not standardized, but is " +"supported by many common server implementations." +msgstr "" +"請求伺服器上名為 *filename* 的檔案的大小。成功時，檔案的大小作為整數回傳，否" +"則回傳 ``None``。請注意，``SIZE`` 命令不是標準化的，但被許多常見的伺服器實作" +"支援。" + +#: ../../library/ftplib.rst:430 +msgid "" +"Send a ``QUIT`` command to the server and close the connection. This is the " +"\"polite\" way to close a connection, but it may raise an exception if the " +"server responds with an error to the ``QUIT`` command. This implies a call " +"to the :meth:`close` method which renders the :class:`FTP` instance useless " +"for subsequent calls (see below)." +msgstr "" +"向伺服器發送 ``QUIT`` 命令並關閉連線。這是關閉連線的「禮貌」方式，但如果伺服" +"器對 ``QUIT`` 命令作出錯誤回應，它可能會引發例外。這意味著呼叫 :meth:`close` " +"方法使 :class:`FTP` 實例無法用於後續呼叫（見下文）。" + +#: ../../library/ftplib.rst:439 +msgid "" +"Close the connection unilaterally. This should not be applied to an already " +"closed connection such as after a successful call to :meth:`~FTP.quit`. " +"After this call the :class:`FTP` instance should not be used any more (after " +"a call to :meth:`close` or :meth:`~FTP.quit` you cannot reopen the " +"connection by issuing another :meth:`login` method)." +msgstr "" +"單方面關閉連線。這不應該使用於已經關閉的連線，例如在成功呼叫 :meth:`~FTP." +"quit` 之後。呼叫後就不應該再次使用 :class:`FTP` 實例（在呼叫 :meth:`close` " +"或 :meth:`~FTP.quit` 後，你不能透過發出另一個 :meth:`login` 方法重新打開連" +"線）。" + +#: ../../library/ftplib.rst:447 +msgid "FTP_TLS objects" +msgstr "FTP_TLS 物件" + +#: ../../library/ftplib.rst:452 +msgid "" +"An :class:`FTP` subclass which adds TLS support to FTP as described in :rfc:" +"`4217`. Connect to port 21 implicitly securing the FTP control connection " +"before authenticating." +msgstr "" + +#: ../../library/ftplib.rst:458 +msgid "" +"The user must explicitly secure the data connection by calling the :meth:" +"`prot_p` method." +msgstr "" + +#: ../../library/ftplib.rst:476 +msgid "" +"An SSL context object which allows bundling SSL configuration options, " +"certificates and private keys into a single, potentially long-lived, " +"structure. Please read :ref:`ssl-security` for best practices." +msgstr "" + +#: ../../library/ftplib.rst:483 +msgid "" +"A timeout in seconds for blocking operations like :meth:`~FTP.connect` " +"(default: the global default timeout setting)." +msgstr "" +"如 :meth:`~FTP.connect` 的阻塞操作的超時設定，以秒為單位（預設：使用全域預設" +"超時設定）。" + +#: ../../library/ftplib.rst:497 +msgid "Added the *source_address* parameter." +msgstr "新增 *source_address* 參數。" + +#: ../../library/ftplib.rst:500 +msgid "" +"The class now supports hostname check with :attr:`ssl.SSLContext." +"check_hostname` and *Server Name Indication* (see :const:`ssl.HAS_SNI`)." +msgstr "" +"該類別現在支援使用 :attr:`ssl.SSLContext.check_hostname` 和 *Server Name " +"Indication* 進行主機名 (hostname) 檢查（參見 :const:`ssl.HAS_SNI`）。" + +#: ../../library/ftplib.rst:511 +msgid "The deprecated *keyfile* and *certfile* parameters have been removed." +msgstr "已棄用的 *keyfile* 和 *certfile* 參數已被移除。" + +#: ../../library/ftplib.rst:514 +msgid "Here's a sample session using the :class:`FTP_TLS` class::" +msgstr "這是一個使用 :class:`FTP_TLS` 類別的範例會話：" + +#: ../../library/ftplib.rst:516 +msgid "" +">>> ftps = FTP_TLS('ftp.pureftpd.org')\n" +">>> ftps.login()\n" +"'230 Anonymous user logged in'\n" +">>> ftps.prot_p()\n" +"'200 Data protection level set to \"private\"'\n" +">>> ftps.nlst()\n" +"['6jack', 'OpenBSD', 'antilink', 'blogbench', 'bsdcam', 'clockspeed', " +"'djbdns-jedi', 'docs', 'eaccelerator-jedi', 'favicon.ico', 'francotone', " +"'fugu', 'ignore', 'libpuzzle', 'metalog', 'minidentd', 'misc', 'mysql-udf-" +"global-user-variables', 'php-jenkins-hash', 'php-skein-hash', 'php-webdav', " +"'phpaudit', 'phpbench', 'pincaster', 'ping', 'posto', 'pub', 'public', " +"'public_keys', 'pure-ftpd', 'qscan', 'qtc', 'sharedance', 'skycache', " +"'sound', 'tmp', 'ucarp']" +msgstr "" +">>> ftps = FTP_TLS('ftp.pureftpd.org')\n" +">>> ftps.login()\n" +"'230 Anonymous user logged in'\n" +">>> ftps.prot_p()\n" +"'200 Data protection level set to \"private\"'\n" +">>> ftps.nlst()\n" +"['6jack', 'OpenBSD', 'antilink', 'blogbench', 'bsdcam', 'clockspeed', " +"'djbdns-jedi', 'docs', 'eaccelerator-jedi', 'favicon.ico', 'francotone', " +"'fugu', 'ignore', 'libpuzzle', 'metalog', 'minidentd', 'misc', 'mysql-udf-" +"global-user-variables', 'php-jenkins-hash', 'php-skein-hash', 'php-webdav', " +"'phpaudit', 'phpbench', 'pincaster', 'ping', 'posto', 'pub', 'public', " +"'public_keys', 'pure-ftpd', 'qscan', 'qtc', 'sharedance', 'skycache', " +"'sound', 'tmp', 'ucarp']" + +#: ../../library/ftplib.rst:524 +msgid "" +":class:`!FTP_TLS` class inherits from :class:`FTP`, defining these " +"additional methods and attributes:" +msgstr "" +":class:`!FTP_TLS` 類別繼承自 :class:`FTP`，並另外定義了這些的方法與屬性：" + +#: ../../library/ftplib.rst:529 +msgid "The SSL version to use (defaults to :data:`ssl.PROTOCOL_SSLv23`)." +msgstr "要使用的 SSL 版本（預設為 :data:`ssl.PROTOCOL_SSLv23`）。" + +#: ../../library/ftplib.rst:533 +msgid "" +"Set up a secure control connection by using TLS or SSL, depending on what is " +"specified in the :attr:`ssl_version` attribute." +msgstr "" +"根據 :attr:`ssl_version` 屬性中指定的內容，使用 TLS 或 SSL 設定安全控制連線。" + +#: ../../library/ftplib.rst:536 +msgid "" +"The method now supports hostname check with :attr:`ssl.SSLContext." +"check_hostname` and *Server Name Indication* (see :const:`ssl.HAS_SNI`)." +msgstr "" +"該方法現在支援使用 :attr:`ssl.SSLContext.check_hostname` 和 *Server Name " +"Indication* 進行主機名檢查（參見 :const:`ssl.HAS_SNI`）。" + +#: ../../library/ftplib.rst:543 +msgid "" +"Revert control channel back to plaintext. This can be useful to take " +"advantage of firewalls that know how to handle NAT with non-secure FTP " +"without opening fixed ports." +msgstr "" +"將控制通道恢復為純文本。這對於利用知道如何在不打開固定連接埠的情況下使用非安" +"全 (non-secure) FTP 以處理 NAT 的防火牆很有用。" + +#: ../../library/ftplib.rst:551 +msgid "Set up secure data connection." +msgstr "設定安全資料連線。" + +#: ../../library/ftplib.rst:555 +msgid "Set up clear text data connection." +msgstr "設定明文資料 (clear text data) 連線。" + +#: ../../library/ftplib.rst:559 +msgid "Module variables" +msgstr "模組變數" + +#: ../../library/ftplib.rst:563 +msgid "Exception raised when an unexpected reply is received from the server." +msgstr "伺服器收到意外回覆時所引發的例外。" + +#: ../../library/ftplib.rst:568 +msgid "" +"Exception raised when an error code signifying a temporary error (response " +"codes in the range 400--499) is received." +msgstr "" +"當收到表示暫時錯誤的錯誤碼（400--499 範圍內的回應狀態碼）時引發的例外。" + +#: ../../library/ftplib.rst:574 +msgid "" +"Exception raised when an error code signifying a permanent error (response " +"codes in the range 500--599) is received." +msgstr "" +"當收到表示永久錯誤的錯誤碼（500--599 範圍內的回應狀態碼）時引發的例外。" + +#: ../../library/ftplib.rst:580 +msgid "" +"Exception raised when a reply is received from the server that does not fit " +"the response specifications of the File Transfer Protocol, i.e. begin with a " +"digit in the range 1--5." +msgstr "" +"當從伺服器收到不符合檔案傳輸協定回應規範的回覆時引發例外，即 1--5 範圍內的數" +"字開頭。" + +#: ../../library/ftplib.rst:587 +msgid "" +"The set of all exceptions (as a tuple) that methods of :class:`FTP` " +"instances may raise as a result of problems with the FTP connection (as " +"opposed to programming errors made by the caller). This set includes the " +"four exceptions listed above as well as :exc:`OSError` and :exc:`EOFError`." +msgstr "" +":class:`FTP` 實例方法由於 FTP 連線問題（相對於呼叫者的程式錯誤）而可能引發的" +"所有例外集合（元組形式）。該集合包括上面列出的四個例外以及 :exc:`OSError` " +"和 :exc:`EOFError`。" + +#: ../../library/ftplib.rst:595 +msgid "Module :mod:`netrc`" +msgstr ":mod:`netrc` 模組" + +#: ../../library/ftplib.rst:596 +msgid "" +"Parser for the :file:`.netrc` file format. The file :file:`.netrc` is " +"typically used by FTP clients to load user authentication information before " +"prompting the user." +msgstr "" +":file:`.netrc` 檔案格式的剖析器。:file:`.netrc` 檔案通常被 FTP 用戶端用來在提" +"示使用者之前載入使用者身份驗證資訊。" + +#: ../../library/ftplib.rst:9 +msgid "FTP" +msgstr "FTP" + +#: ../../library/ftplib.rst:9 +msgid "protocol" +msgstr "protocol（協定）" + +#: ../../library/ftplib.rst:9 +msgid "ftplib (standard module)" +msgstr "ftplib（標準模組）" diff --git a/library/functional.po b/library/functional.po index b5ba495525..d8074d3ef6 100644 --- a/library/functional.po +++ b/library/functional.po @@ -1,35 +1,35 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Leon H., 2017 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2018-06-26 18:54+0800\n" -"PO-Revision-Date: 2017-09-22 18:26+0000\n" -"Last-Translator: Leon H.\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/functional.rst:3 -msgid "Functional Programming Modules" -msgstr "函式程式設計模組" - -#: ../../library/functional.rst:5 -msgid "" -"The modules described in this chapter provide functions and classes that " -"support a functional programming style, and general operations on callables." -msgstr "" -"本章節所描述的模組提供了支援函式程式設計風格的函式和類別，以及對可呼叫物件的" -"一般操作。" - -#: ../../library/functional.rst:8 -msgid "The following modules are documented in this chapter:" -msgstr "本章包含下列的模組：" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Leon H., 2017 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2018-06-26 18:54+0800\n" +"PO-Revision-Date: 2017-09-22 18:26+0000\n" +"Last-Translator: Leon H.\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/functional.rst:3 +msgid "Functional Programming Modules" +msgstr "函式程式設計模組" + +#: ../../library/functional.rst:5 +msgid "" +"The modules described in this chapter provide functions and classes that " +"support a functional programming style, and general operations on callables." +msgstr "" +"本章節所描述的模組提供了支援函式程式設計風格的函式和類別，以及對可呼叫物件的" +"一般操作。" + +#: ../../library/functional.rst:8 +msgid "The following modules are documented in this chapter:" +msgstr "本章包含下列的模組：" diff --git a/library/functions.po b/library/functions.po index d443021cdc..4ff1424ebc 100644 --- a/library/functions.po +++ b/library/functions.po @@ -1,3968 +1,3968 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# Translators: -# Adrian Liaw , 2018 -# nienzu , 2018 -# Matt Wang , 2021 -# Phil Lin , 2022 -# Steven Hsu , 2023 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-12-15 00:16+0000\n" -"PO-Revision-Date: 2024-05-06 17:06+0800\n" -"Last-Translator: KNChiu \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" -"X-Generator: Poedit 3.4.2\n" - -#: ../../library/functions.rst:5 ../../library/functions.rst:11 -msgid "Built-in Functions" -msgstr "內建函式" - -#: ../../library/functions.rst:7 -msgid "" -"The Python interpreter has a number of functions and types built into it " -"that are always available. They are listed here in alphabetical order." -msgstr "" -"Python 直譯器有內建多個可隨時使用的函式和型別。以下按照英文字母排序列出。" - -#: ../../library/functions.rst:13 -msgid "**A**" -msgstr "**A**" - -#: ../../library/functions.rst:14 -msgid ":func:`abs`" -msgstr ":func:`abs`" - -#: ../../library/functions.rst:15 -msgid ":func:`aiter`" -msgstr ":func:`aiter`" - -#: ../../library/functions.rst:16 -msgid ":func:`all`" -msgstr ":func:`all`" - -#: ../../library/functions.rst:17 -msgid ":func:`anext`" -msgstr ":func:`anext`" - -#: ../../library/functions.rst:18 -msgid ":func:`any`" -msgstr ":func:`any`" - -#: ../../library/functions.rst:19 -msgid ":func:`ascii`" -msgstr ":func:`ascii`" - -#: ../../library/functions.rst:21 -msgid "**B**" -msgstr "**B**" - -#: ../../library/functions.rst:22 -msgid ":func:`bin`" -msgstr ":func:`bin`" - -#: ../../library/functions.rst:23 -msgid ":func:`bool`" -msgstr ":func:`bool`" - -#: ../../library/functions.rst:24 -msgid ":func:`breakpoint`" -msgstr ":func:`breakpoint`" - -#: ../../library/functions.rst:25 -msgid "|func-bytearray|_" -msgstr "|func-bytearray|_" - -#: ../../library/functions.rst:26 -msgid "|func-bytes|_" -msgstr "|func-bytes|_" - -#: ../../library/functions.rst:28 -msgid "**C**" -msgstr "**C**" - -#: ../../library/functions.rst:29 -msgid ":func:`callable`" -msgstr ":func:`callable`" - -#: ../../library/functions.rst:30 -msgid ":func:`chr`" -msgstr ":func:`chr`" - -#: ../../library/functions.rst:31 -msgid ":func:`classmethod`" -msgstr ":func:`classmethod`" - -#: ../../library/functions.rst:32 -msgid ":func:`compile`" -msgstr ":func:`compile`" - -#: ../../library/functions.rst:33 -msgid ":func:`complex`" -msgstr ":func:`complex`" - -#: ../../library/functions.rst:35 -msgid "**D**" -msgstr "**D**" - -#: ../../library/functions.rst:36 -msgid ":func:`delattr`" -msgstr ":func:`delattr`" - -#: ../../library/functions.rst:37 -msgid "|func-dict|_" -msgstr "|func-dict|_" - -#: ../../library/functions.rst:38 -msgid ":func:`dir`" -msgstr ":func:`dir`" - -#: ../../library/functions.rst:39 -msgid ":func:`divmod`" -msgstr ":func:`divmod`" - -#: ../../library/functions.rst:13 -msgid "**E**" -msgstr "**E**" - -#: ../../library/functions.rst:14 -msgid ":func:`enumerate`" -msgstr ":func:`enumerate`" - -#: ../../library/functions.rst:15 -msgid ":func:`eval`" -msgstr ":func:`eval`" - -#: ../../library/functions.rst:16 -msgid ":func:`exec`" -msgstr ":func:`exec`" - -#: ../../library/functions.rst:18 -msgid "**F**" -msgstr "**F**" - -#: ../../library/functions.rst:19 -msgid ":func:`filter`" -msgstr ":func:`filter`" - -#: ../../library/functions.rst:20 -msgid ":func:`float`" -msgstr ":func:`float`" - -#: ../../library/functions.rst:21 -msgid ":func:`format`" -msgstr ":func:`format`" - -#: ../../library/functions.rst:22 -msgid "|func-frozenset|_" -msgstr "|func-frozenset|_" - -#: ../../library/functions.rst:24 -msgid "**G**" -msgstr "**G**" - -#: ../../library/functions.rst:25 -msgid ":func:`getattr`" -msgstr ":func:`getattr`" - -#: ../../library/functions.rst:26 -msgid ":func:`globals`" -msgstr ":func:`globals`" - -#: ../../library/functions.rst:28 -msgid "**H**" -msgstr "**H**" - -#: ../../library/functions.rst:29 -msgid ":func:`hasattr`" -msgstr ":func:`hasattr`" - -#: ../../library/functions.rst:30 -msgid ":func:`hash`" -msgstr ":func:`hash`" - -#: ../../library/functions.rst:31 -msgid ":func:`help`" -msgstr ":func:`help`" - -#: ../../library/functions.rst:32 -msgid ":func:`hex`" -msgstr ":func:`hex`" - -#: ../../library/functions.rst:34 -msgid "**I**" -msgstr "**I**" - -#: ../../library/functions.rst:35 -msgid ":func:`id`" -msgstr ":func:`id`" - -#: ../../library/functions.rst:36 -msgid ":func:`input`" -msgstr ":func:`input`" - -#: ../../library/functions.rst:37 -msgid ":func:`int`" -msgstr ":func:`int`" - -#: ../../library/functions.rst:38 -msgid ":func:`isinstance`" -msgstr ":func:`isinstance`" - -#: ../../library/functions.rst:39 -msgid ":func:`issubclass`" -msgstr ":func:`issubclass`" - -#: ../../library/functions.rst:40 -msgid ":func:`iter`" -msgstr ":func:`iter`" - -#: ../../library/functions.rst:13 -msgid "**L**" -msgstr "**L**" - -#: ../../library/functions.rst:14 -msgid ":func:`len`" -msgstr ":func:`len`" - -#: ../../library/functions.rst:15 -msgid "|func-list|_" -msgstr "|func-list|_" - -#: ../../library/functions.rst:16 -msgid ":func:`locals`" -msgstr ":func:`locals`" - -#: ../../library/functions.rst:18 -msgid "**M**" -msgstr "**M**" - -#: ../../library/functions.rst:19 -msgid ":func:`map`" -msgstr ":func:`map`" - -#: ../../library/functions.rst:20 -msgid ":func:`max`" -msgstr ":func:`max`" - -#: ../../library/functions.rst:21 -msgid "|func-memoryview|_" -msgstr "|func-memoryview|_" - -#: ../../library/functions.rst:22 -msgid ":func:`min`" -msgstr ":func:`min`" - -#: ../../library/functions.rst:24 -msgid "**N**" -msgstr "**N**" - -#: ../../library/functions.rst:25 -msgid ":func:`next`" -msgstr ":func:`next`" - -#: ../../library/functions.rst:27 -msgid "**O**" -msgstr "**O**" - -#: ../../library/functions.rst:28 -msgid ":func:`object`" -msgstr ":func:`object`" - -#: ../../library/functions.rst:29 -msgid ":func:`oct`" -msgstr ":func:`oct`" - -#: ../../library/functions.rst:30 -msgid ":func:`open`" -msgstr ":func:`open`" - -#: ../../library/functions.rst:31 -msgid ":func:`ord`" -msgstr ":func:`ord`" - -#: ../../library/functions.rst:33 -msgid "**P**" -msgstr "**P**" - -#: ../../library/functions.rst:34 -msgid ":func:`pow`" -msgstr ":func:`pow`" - -#: ../../library/functions.rst:35 -msgid ":func:`print`" -msgstr ":func:`print`" - -#: ../../library/functions.rst:36 -msgid ":func:`property`" -msgstr ":func:`property`" - -#: ../../library/functions.rst:13 -msgid "**R**" -msgstr "**R**" - -#: ../../library/functions.rst:14 -msgid "|func-range|_" -msgstr "|func-range|_" - -#: ../../library/functions.rst:15 -msgid ":func:`repr`" -msgstr ":func:`repr`" - -#: ../../library/functions.rst:16 -msgid ":func:`reversed`" -msgstr ":func:`reversed`" - -#: ../../library/functions.rst:17 -msgid ":func:`round`" -msgstr ":func:`round`" - -#: ../../library/functions.rst:19 -msgid "**S**" -msgstr "**S**" - -#: ../../library/functions.rst:20 -msgid "|func-set|_" -msgstr "|func-set|_" - -#: ../../library/functions.rst:21 -msgid ":func:`setattr`" -msgstr ":func:`setattr`" - -#: ../../library/functions.rst:22 -msgid ":func:`slice`" -msgstr ":func:`slice`" - -#: ../../library/functions.rst:23 -msgid ":func:`sorted`" -msgstr ":func:`sorted`" - -#: ../../library/functions.rst:24 -msgid ":func:`staticmethod`" -msgstr ":func:`staticmethod`" - -#: ../../library/functions.rst:25 -msgid "|func-str|_" -msgstr "|func-str|_" - -#: ../../library/functions.rst:26 -msgid ":func:`sum`" -msgstr ":func:`sum`" - -#: ../../library/functions.rst:27 -msgid ":func:`super`" -msgstr ":func:`super`" - -#: ../../library/functions.rst:29 -msgid "**T**" -msgstr "**T**" - -#: ../../library/functions.rst:30 -msgid "|func-tuple|_" -msgstr "|func-tuple|_" - -#: ../../library/functions.rst:31 -msgid ":func:`type`" -msgstr ":func:`type`" - -#: ../../library/functions.rst:33 -msgid "**V**" -msgstr "**V**" - -#: ../../library/functions.rst:34 -msgid ":func:`vars`" -msgstr ":func:`vars`" - -#: ../../library/functions.rst:36 -msgid "**Z**" -msgstr "**Z**" - -#: ../../library/functions.rst:37 -msgid ":func:`zip`" -msgstr ":func:`zip`" - -#: ../../library/functions.rst:39 -msgid "**_**" -msgstr "**_**" - -#: ../../library/functions.rst:40 -msgid ":func:`__import__`" -msgstr ":func:`__import__`" - -#: ../../library/functions.rst:59 -msgid "" -"Return the absolute value of a number. The argument may be an integer, a " -"floating-point number, or an object implementing :meth:`~object.__abs__`. If " -"the argument is a complex number, its magnitude is returned." -msgstr "" -"回傳一個數的絕對值，引數可以是整數、浮點數或有實現 :meth:`~object.__abs__` 的" -"物件。如果引數是一個複數，回傳它的純量（大小）。" - -#: ../../library/functions.rst:67 -msgid "" -"Return an :term:`asynchronous iterator` for an :term:`asynchronous " -"iterable`. Equivalent to calling ``x.__aiter__()``." -msgstr "" -"回傳 :term:`非同步疊代器 ` 做為 :term:`非同步可疊代物" -"件 `。相當於呼叫 x.__aiter__()。" - -#: ../../library/functions.rst:70 -msgid "Note: Unlike :func:`iter`, :func:`aiter` has no 2-argument variant." -msgstr "注意：與 :func:`iter` 不同，:func:`aiter` 沒有兩個引數的變體。" - -#: ../../library/functions.rst:76 -msgid "" -"Return ``True`` if all elements of the *iterable* are true (or if the " -"iterable is empty). Equivalent to::" -msgstr "" -"如果 *iterable* 的所有元素皆為真（或 iterable 為空）則回傳 ``True``。等價" -"於： ::" - -#: ../../library/functions.rst:79 -msgid "" -"def all(iterable):\n" -" for element in iterable:\n" -" if not element:\n" -" return False\n" -" return True" -msgstr "" -"def all(iterable):\n" -" for element in iterable:\n" -" if not element:\n" -" return False\n" -" return True" - -#: ../../library/functions.rst:89 -msgid "" -"When awaited, return the next item from the given :term:`asynchronous " -"iterator`, or *default* if given and the iterator is exhausted." -msgstr "" -"當進入 await 時，從給定的 :term:`asynchronous iterator` 中回傳下一個項目" -"（item），疊代完畢則回傳 *default* 。" - -#: ../../library/functions.rst:92 -msgid "" -"This is the async variant of the :func:`next` builtin, and behaves similarly." -msgstr "這是內建函式 :func:`next` 的非同步版本，其行為類似於：" - -#: ../../library/functions.rst:95 -msgid "" -"This calls the :meth:`~object.__anext__` method of *async_iterator*, " -"returning an :term:`awaitable`. Awaiting this returns the next value of the " -"iterator. If *default* is given, it is returned if the iterator is " -"exhausted, otherwise :exc:`StopAsyncIteration` is raised." -msgstr "" -"呼叫 *async_iterator* 的 :meth:`~object.__anext__` 方法，回傳 :term:" -"`awaitable`。等待返回疊代器的下一個值。如果指定 *default*，當疊代器結束時會返" -"回該值，否則會引發 :exc:`StopAsyncIteration` 。" - -#: ../../library/functions.rst:104 -msgid "" -"Return ``True`` if any element of the *iterable* is true. If the iterable " -"is empty, return ``False``. Equivalent to::" -msgstr "" -"如果 *iterable* 的任一元素為真，回傳 ``True``。如果 iterable 是空的，則回傳 " -"``False``。等價於： ::" - -#: ../../library/functions.rst:107 -msgid "" -"def any(iterable):\n" -" for element in iterable:\n" -" if element:\n" -" return True\n" -" return False" -msgstr "" -"def any(iterable):\n" -" for element in iterable:\n" -" if element:\n" -" return True\n" -" return False" - -#: ../../library/functions.rst:116 -msgid "" -"As :func:`repr`, return a string containing a printable representation of an " -"object, but escape the non-ASCII characters in the string returned by :func:" -"`repr` using ``\\x``, ``\\u``, or ``\\U`` escapes. This generates a string " -"similar to that returned by :func:`repr` in Python 2." -msgstr "" -"就像函式 :func:`repr`，回傳一個表示物件的字串，但是 :func:`repr` 回傳的字串中" -"非 ASCII 編碼的字元會被跳脫 (escape)，像是 ``\\x``、``\\u`` 和 ``\\U``。這個" -"函式生成的字串和 Python 2 的 :func:`repr` 回傳的結果相似。" - -#: ../../library/functions.rst:124 -msgid "" -"Convert an integer number to a binary string prefixed with \"0b\". The " -"result is a valid Python expression. If *integer* is not a Python :class:" -"`int` object, it has to define an :meth:`~object.__index__` method that " -"returns an integer. Some examples:" -msgstr "" -"將一個整數轉變為一個前綴為 \"0b\" 的二進位制字串。結果是一個有效的 Python 運" -"算式。如果 *integer* 不是 Python 的 :class:`int` 物件，那它需要定義 :meth:" -"`~object.__index__` method 回傳一個整數。舉例來說：" - -#: ../../library/functions.rst:134 -msgid "" -"If the prefix \"0b\" is desired or not, you can use either of the following " -"ways." -msgstr "如果不一定需要 \"0b\" 前綴，還可以使用如下的方法。" - -#: ../../library/functions.rst:141 ../../library/functions.rst:948 -#: ../../library/functions.rst:1332 -msgid "See also :func:`format` for more information." -msgstr "可參考 :func:`format` 取得更多資訊。" - -#: ../../library/functions.rst:146 -msgid "" -"Return a Boolean value, i.e. one of ``True`` or ``False``. The argument is " -"converted using the standard :ref:`truth testing procedure `. If the " -"argument is false or omitted, this returns ``False``; otherwise, it returns " -"``True``. The :class:`bool` class is a subclass of :class:`int` (see :ref:" -"`typesnumeric`). It cannot be subclassed further. Its only instances are " -"``False`` and ``True`` (see :ref:`typebool`)." -msgstr "" -"回傳一個布林值，即 ``True`` 或者 ``False``。引數會使用標準的\\ :ref:`真值測試" -"程序 `\\ 來轉換。如果引數為假或者被省略，則回傳 ``False``；其他情況回" -"傳 ``True``。:class:`bool` class（類別）是 :class:`int` 的 subclass（子類別）" -"（參見 :ref:`typesnumeric`），其他 class 不能繼承自它。它只有 ``False`` 和 " -"``True`` 兩個實例（參見 :ref:`typebool`）。" - -#: ../../library/functions.rst:156 ../../library/functions.rst:813 -msgid "The parameter is now positional-only." -msgstr "現在為僅限位置參數。" - -#: ../../library/functions.rst:161 -msgid "" -"This function drops you into the debugger at the call site. Specifically, " -"it calls :func:`sys.breakpointhook`, passing ``args`` and ``kws`` straight " -"through. By default, ``sys.breakpointhook()`` calls :func:`pdb.set_trace` " -"expecting no arguments. In this case, it is purely a convenience function " -"so you don't have to explicitly import :mod:`pdb` or type as much code to " -"enter the debugger. However, :func:`sys.breakpointhook` can be set to some " -"other function and :func:`breakpoint` will automatically call that, allowing " -"you to drop into the debugger of choice. If :func:`sys.breakpointhook` is " -"not accessible, this function will raise :exc:`RuntimeError`." -msgstr "" -"這個函式將呼叫 :func:`sys.breakpointhook` 函式，並將 ``args`` 和 ``kws`` 傳遞" -"給它。這將有效地讓你在特定的呼叫點進入除錯器。預設情況下，``sys." -"breakpointhook()`` 呼叫 :func:`pdb.set_trace` 不須帶任何引數。這樣的設計是為" -"了方便使用者，讓他們不需要額外地導入 :mod:`pdb` 模組或輸入太多程式就可以進入" -"除錯器。然而，可以將 :func:`sys.breakpointhook` 設置為其他函式，並且 :func:" -"`breakpoint` 將自動呼叫該函式，讓你進入所選擇的除錯器。如果無法存取 :func:" -"`sys.breakpointhook` 這個函式，則此函式將引發 :exc:`RuntimeError`。" - -#: ../../library/functions.rst:173 -msgid "" -"By default, the behavior of :func:`breakpoint` can be changed with the :" -"envvar:`PYTHONBREAKPOINT` environment variable. See :func:`sys." -"breakpointhook` for usage details." -msgstr "" -"預設情況下，:func:`breakpoint` 的行為可以透過 :envvar:`PYTHONBREAKPOINT` 環境" -"變數來更改。有關使用詳情，請參考 :func:`sys.breakpointhook`。" - -#: ../../library/functions.rst:177 -msgid "" -"Note that this is not guaranteed if :func:`sys.breakpointhook` has been " -"replaced." -msgstr "請注意，如果 :func:`sys.breakpointhook` 被替換了，則無法保證此功能。" - -#: ../../library/functions.rst:180 -msgid "" -"Raises an :ref:`auditing event ` ``builtins.breakpoint`` with " -"argument ``breakpointhook``." -msgstr "" -"引發一個附帶引數 ``breakpointhook`` 的\\ :ref:`稽核事件 ` " -"``builtins.breakpoint``。" - -#: ../../library/functions.rst:189 -msgid "" -"Return a new array of bytes. The :class:`bytearray` class is a mutable " -"sequence of integers in the range 0 <= x < 256. It has most of the usual " -"methods of mutable sequences, described in :ref:`typesseq-mutable`, as well " -"as most methods that the :class:`bytes` type has, see :ref:`bytes-methods`." -msgstr "" -"回傳一個新的 bytes 陣列。:class:`bytearray` class 是一個可變的整數序列，包含" -"範圍為 0 <= x < 256 的整數。它有可變序列大部分常見的 method（如在 :ref:" -"`typesseq-mutable` 中所述），同時也有 :class:`bytes` 型別大部分的 method，參" -"見 :ref:`bytes-methods`。" - -#: ../../library/functions.rst:194 -msgid "" -"The optional *source* parameter can be used to initialize the array in a few " -"different ways:" -msgstr "選擇性參數 *source* 可以被用來以不同的方式初始化陣列：" - -#: ../../library/functions.rst:197 -msgid "" -"If it is a *string*, you must also give the *encoding* (and optionally, " -"*errors*) parameters; :func:`bytearray` then converts the string to bytes " -"using :meth:`str.encode`." -msgstr "" -"如果是一個 *string*，你必須提供 *encoding* 參數（以及選擇性地提供 " -"*errors* ）；:func:`bytearray` 會使用 :meth:`str.encode` method 來將 string " -"轉變成 bytes。" - -#: ../../library/functions.rst:201 -msgid "" -"If it is an *integer*, the array will have that size and will be initialized " -"with null bytes." -msgstr "" -"如果是一個 *integer*，陣列則會有該數值的長度，並以 null bytes 來當作初始值。" - -#: ../../library/functions.rst:204 -msgid "" -"If it is an object conforming to the :ref:`buffer interface " -"`, a read-only buffer of the object will be used to " -"initialize the bytes array." -msgstr "" -"如果是一個符合 :ref:`buffer 介面 `\\ 的物件，該物件的唯讀 " -"buffer 會被用來初始化 bytes 陣列。" - -#: ../../library/functions.rst:207 -msgid "" -"If it is an *iterable*, it must be an iterable of integers in the range ``0 " -"<= x < 256``, which are used as the initial contents of the array." -msgstr "" -"如果是一個 *iterable*，它的元素必須是範圍為 ``0 <= x < 256`` 的整數，並且會被" -"用作陣列的初始值。" - -#: ../../library/functions.rst:210 -msgid "Without an argument, an array of size 0 is created." -msgstr "如果沒有引數，則建立長度為 0 的陣列。" - -#: ../../library/functions.rst:212 -msgid "See also :ref:`binaryseq` and :ref:`typebytearray`." -msgstr "可參考 :ref:`binaryseq` 和 :ref:`typebytearray`。" - -#: ../../library/functions.rst:220 -msgid "" -"Return a new \"bytes\" object which is an immutable sequence of integers in " -"the range ``0 <= x < 256``. :class:`bytes` is an immutable version of :" -"class:`bytearray` -- it has the same non-mutating methods and the same " -"indexing and slicing behavior." -msgstr "" -"回傳一個新的 \"bytes\" 物件，會是一個元素是範圍為 ``0 <= x < 256`` 整數的不可" -"變序列。:class:`bytes` 是 :class:`bytearray` 的不可變版本 — 它的同樣具備不改" -"變物件的 method，也有相同的索引和切片操作。" - -#: ../../library/functions.rst:225 -msgid "" -"Accordingly, constructor arguments are interpreted as for :func:`bytearray`." -msgstr "因此，建構函式的引數和 :func:`bytearray` 相同。" - -#: ../../library/functions.rst:227 -msgid "Bytes objects can also be created with literals, see :ref:`strings`." -msgstr "Bytes 物件還可以用文字建立，參見 :ref:`strings`。" - -#: ../../library/functions.rst:229 -msgid "See also :ref:`binaryseq`, :ref:`typebytes`, and :ref:`bytes-methods`." -msgstr "可參考 :ref:`binaryseq`、:ref:`typebytes` 和 :ref:`bytes-methods`。" - -#: ../../library/functions.rst:234 -msgid "" -"Return :const:`True` if the *object* argument appears callable, :const:" -"`False` if not. If this returns ``True``, it is still possible that a call " -"fails, but if it is ``False``, calling *object* will never succeed. Note " -"that classes are callable (calling a class returns a new instance); " -"instances are callable if their class has a :meth:`~object.__call__` method." -msgstr "" -"如果引數 *object* 是可呼叫的，回傳 :const:`True`，否則回傳 :const:`False`。如" -"果回傳 ``True``，呼叫仍可能會失敗；但如果回傳 ``False``，則呼叫 *object* 肯定" -"會失敗。注意 class 是可呼叫的（呼叫 class 會回傳一個新的實例）；如果實例的 " -"class 有定義 :meth:`~object.__call__` method，則它是可呼叫的。" - -#: ../../library/functions.rst:240 -msgid "" -"This function was first removed in Python 3.0 and then brought back in " -"Python 3.2." -msgstr "這個函式一開始在 Python 3.0 被移除，但在 Python 3.2 又被重新加入。" - -#: ../../library/functions.rst:247 -msgid "" -"Return the string representing a character with the specified Unicode code " -"point. For example, ``chr(97)`` returns the string ``'a'``, while " -"``chr(8364)`` returns the string ``'€'``. This is the inverse of :func:`ord`." -msgstr "" -"回傳代表有特定 Unicode 編碼位置字元的字串。例如，``chr(97)`` 回傳字串 " -"``'a'``，而 ``chr(8364)`` 回傳字串 ``'€'``。這是 :func:`ord` 的逆函式。" - -#: ../../library/functions.rst:251 -msgid "" -"The valid range for the argument is from 0 through 1,114,111 (0x10FFFF in " -"base 16). :exc:`ValueError` will be raised if it is outside that range." -msgstr "" -"引數的有效範圍是 0 到 1,114,111（16 進制表示為 0x10FFFF）。如果它超過這個範" -"圍，會引發 :exc:`ValueError`。" - -#: ../../library/functions.rst:257 -msgid "Transform a method into a class method." -msgstr "把一個 method 封裝成 class method（類別方法）。" - -#: ../../library/functions.rst:259 -msgid "" -"A class method receives the class as an implicit first argument, just like " -"an instance method receives the instance. To declare a class method, use " -"this idiom::" -msgstr "" -"一個 class method 把自己的 class 作為第一個引數，就像一個實例 method 把實例自" -"己作為第一個引數。請用以下慣例來宣告 class method： ::" - -#: ../../library/functions.rst:263 -msgid "" -"class C:\n" -" @classmethod\n" -" def f(cls, arg1, arg2): ..." -msgstr "" -"class C:\n" -" @classmethod\n" -" def f(cls, arg1, arg2): ..." - -#: ../../library/functions.rst:267 -msgid "" -"The ``@classmethod`` form is a function :term:`decorator` -- see :ref:" -"`function` for details." -msgstr "" -"``@classmethod`` 語法是一個函式 :term:`decorator` — 參見 :ref:`function` 中關" -"於函式定義的詳細介紹。" - -#: ../../library/functions.rst:270 -msgid "" -"A class method can be called either on the class (such as ``C.f()``) or on " -"an instance (such as ``C().f()``). The instance is ignored except for its " -"class. If a class method is called for a derived class, the derived class " -"object is passed as the implied first argument." -msgstr "" -"一個 class method 可以在 class（如 ``C.f()``）或實例（如 ``C().f()``）上呼" -"叫。實例除了它的 class 資訊，其他都會被忽略。如果一個 class method 在 " -"subclass 上呼叫，subclass 會作為第一個引數傳入。" - -#: ../../library/functions.rst:275 -msgid "" -"Class methods are different than C++ or Java static methods. If you want " -"those, see :func:`staticmethod` in this section. For more information on " -"class methods, see :ref:`types`." -msgstr "" -"Class method 和 C++ 與 Java 的 static method 是有區別的。如果你想瞭解 static " -"method，請看本節的 :func:`staticmethod`。關於 class method 的更多資訊，請參考" -"\\ :ref:`types`。" - -#: ../../library/functions.rst:279 -msgid "" -"Class methods can now wrap other :term:`descriptors ` such as :" -"func:`property`." -msgstr "" -"Class methods 現在可以包裝其他\\ :term:`描述器 `，例如 :func:" -"`property`" - -#: ../../library/functions.rst:283 -msgid "" -"Class methods now inherit the method attributes (:attr:`~function." -"__module__`, :attr:`~function.__name__`, :attr:`~function.__qualname__`, :" -"attr:`~function.__doc__` and :attr:`~function.__annotations__`) and have a " -"new ``__wrapped__`` attribute." -msgstr "" -"Class method 現在繼承了 method 屬性（:attr:`~function.__module__`、:attr:" -"`~function.__name__`、:attr:`~function.__qualname__`、:attr:`~function." -"__doc__` 和 :attr:`~function.__annotations__`），並擁有一個新的 " -"``__wrapped__`` 屬性。" - -#: ../../library/functions.rst:290 -msgid "" -"Class methods can no longer wrap other :term:`descriptors ` such " -"as :func:`property`." -msgstr "" -"Class methods 不能再包裝其他的\\ :term:`描述器 `，例如 :func:" -"`property`。" - -#: ../../library/functions.rst:297 -msgid "" -"Compile the *source* into a code or AST object. Code objects can be " -"executed by :func:`exec` or :func:`eval`. *source* can either be a normal " -"string, a byte string, or an AST object. Refer to the :mod:`ast` module " -"documentation for information on how to work with AST objects." -msgstr "" -"將 *source* 編譯成程式碼或 AST 物件。程式碼物件可以被 :func:`exec` 或 :func:" -"`eval` 執行。*source* 可以是一般的字串、bytes 字串、或者 AST 物件。參見 :mod:" -"`ast` module（模組）的說明文件瞭解如何使用 AST 物件。" - -#: ../../library/functions.rst:302 -msgid "" -"The *filename* argument should give the file from which the code was read; " -"pass some recognizable value if it wasn't read from a file (``''`` " -"is commonly used)." -msgstr "" -"*filename* 引數必須是程式碼的檔名；如果程式碼不是從檔案中讀取，可以傳入一些可" -"辨識的值（經常會使用 ``''`` 來替代）。" - -#: ../../library/functions.rst:306 -msgid "" -"The *mode* argument specifies what kind of code must be compiled; it can be " -"``'exec'`` if *source* consists of a sequence of statements, ``'eval'`` if " -"it consists of a single expression, or ``'single'`` if it consists of a " -"single interactive statement (in the latter case, expression statements that " -"evaluate to something other than ``None`` will be printed)." -msgstr "" -"*mode* 引數指定了編譯程式碼時必須用的模式。如果 *source* 是一系列的陳述式，可" -"以是 ``'exec'``；如果是單一運算式，可以是 ``'eval'``；如果是單個互動式陳述" -"式，可以是 ``'single'``\\ （在最後一種情況下，如果運算式執行結果不是 " -"``None`` 則會被印出來）。" - -#: ../../library/functions.rst:312 -msgid "" -"The optional arguments *flags* and *dont_inherit* control which :ref:" -"`compiler options ` should be activated and which :ref:" -"`future features ` should be allowed. If neither is present (or both " -"are zero) the code is compiled with the same flags that affect the code that " -"is calling :func:`compile`. If the *flags* argument is given and " -"*dont_inherit* is not (or is zero) then the compiler options and the future " -"statements specified by the *flags* argument are used in addition to those " -"that would be used anyway. If *dont_inherit* is a non-zero integer then the " -"*flags* argument is it -- the flags (future features and compiler options) " -"in the surrounding code are ignored." -msgstr "" -"可選引數 *flags* 和 *dont_inherit* 控制啟用哪個\\ :ref:`編譯器選項 `\\ 以及允許哪個\\ :ref:`未來功能 `。如果兩者都不存在" -"（或兩者都為零），則會呼叫與 :func:`compile` 相同旗標的程式碼來編譯。如果給" -"定 *flags* 引數而未給定 *dont_inherit*\\ （或為零）則無論如何都會使用由 " -"*flags* 引數所指定的編譯器選項和未來陳述式。如果 *dont_inherit* 是一個非零整" -"數，則使用 *flags* 引數 -- 周圍程式碼中的旗標（未來功能和編譯器選項）將被忽" -"略。" - -#: ../../library/functions.rst:323 -msgid "" -"Compiler options and future statements are specified by bits which can be " -"bitwise ORed together to specify multiple options. The bitfield required to " -"specify a given future feature can be found as the :attr:`~__future__." -"_Feature.compiler_flag` attribute on the :class:`~__future__._Feature` " -"instance in the :mod:`__future__` module. :ref:`Compiler flags ` can be found in :mod:`ast` module, with ``PyCF_`` prefix." -msgstr "" -"編譯器選項和 future 陳述式使用 bits 來表示，可以一起被位元操作 OR 來表示複數" -"個選項。需要被具體定義特徵的位元域可以透過 :mod:`__future__` module 中 :" -"class:`~__future__._Feature` 實例中的 :attr:`~__future__._Feature." -"compiler_flag` 屬性來獲得。:ref:`編譯器旗標 `\\ 可以在 :" -"mod:`ast` module 中搜尋有 ``PyCF_`` 前綴的名稱。" - -#: ../../library/functions.rst:331 -msgid "" -"The argument *optimize* specifies the optimization level of the compiler; " -"the default value of ``-1`` selects the optimization level of the " -"interpreter as given by :option:`-O` options. Explicit levels are ``0`` (no " -"optimization; ``__debug__`` is true), ``1`` (asserts are removed, " -"``__debug__`` is false) or ``2`` (docstrings are removed too)." -msgstr "" -"引數 *optimize* 用來指定編譯器的最佳化級別；預設值 ``-1`` 選擇與直譯器的 :" -"option:`-O` 選項相同的最佳化級別。其他級別為 ``0``\\ （沒有最佳化；\\ " -"``__debug__`` 為真值）、``1``\\ （assert 被刪除，``__debug__`` 為假值）或 " -"``2``\\ （說明字串 (docstring) 也被刪除）。" - -#: ../../library/functions.rst:337 -msgid "" -"This function raises :exc:`SyntaxError` or :exc:`ValueError` if the compiled " -"source is invalid." -msgstr "" -"如果編譯的原始碼無效，此函式會引發 :exc:`SyntaxError` 或 :exc:`ValueError`。" - -#: ../../library/functions.rst:340 -msgid "" -"If you want to parse Python code into its AST representation, see :func:`ast." -"parse`." -msgstr "如果你想解析 Python 程式碼為 AST 運算式，請參閱 :func:`ast.parse`。" - -#: ../../library/functions.rst:343 ../../library/functions.rst:345 -msgid "" -"Raises an :ref:`auditing event ` ``compile`` with arguments " -"``source`` and ``filename``. This event may also be raised by implicit " -"compilation." -msgstr "" -"引發一個附帶引數 ``source``、``filename`` 的\\ :ref:`稽核事件 ` " -"``compile``。此事件也可能由隱式編譯 (implicit compilation) 所引發。" - -#: ../../library/functions.rst:351 -msgid "" -"When compiling a string with multi-line code in ``'single'`` or ``'eval'`` " -"mode, input must be terminated by at least one newline character. This is " -"to facilitate detection of incomplete and complete statements in the :mod:" -"`code` module." -msgstr "" -"在 ``'single'`` 或 ``'eval'`` 模式編譯多行程式碼時，輸入必須以至少一個換行符" -"結尾。這使 :mod:`code` module 更容易檢測陳述式的完整性。" - -#: ../../library/functions.rst:358 -msgid "" -"It is possible to crash the Python interpreter with a sufficiently large/" -"complex string when compiling to an AST object due to stack depth " -"limitations in Python's AST compiler." -msgstr "" -"如果編譯足夠大或者足夠複雜的字串成 AST 物件時，Python 直譯器會因為 Python " -"AST 編譯器的 stack 深度限制而崩潰。" - -#: ../../library/functions.rst:362 -msgid "" -"Allowed use of Windows and Mac newlines. Also, input in ``'exec'`` mode " -"does not have to end in a newline anymore. Added the *optimize* parameter." -msgstr "" -"允許使用 Windows 和 Mac 的換行符號。此外，在 ``'exec'`` 模式不需要以換行符號" -"結尾。增加了 *optimize* 參數。" - -#: ../../library/functions.rst:366 -msgid "" -"Previously, :exc:`TypeError` was raised when null bytes were encountered in " -"*source*." -msgstr "在之前的版本，*source* 中包含 null bytes 會引發 :exc:`TypeError`。" - -#: ../../library/functions.rst:370 -msgid "" -"``ast.PyCF_ALLOW_TOP_LEVEL_AWAIT`` can now be passed in flags to enable " -"support for top-level ``await``, ``async for``, and ``async with``." -msgstr "" -"``ast.PyCF_ALLOW_TOP_LEVEL_AWAIT`` 現在可以傳遞旗標以啟用對頂層 ``await``、" -"``async for`` 和 ``async with`` 的支援。" - -#: ../../library/functions.rst:379 -msgid "" -"Convert a single string or number to a complex number, or create a complex " -"number from real and imaginary parts." -msgstr "" - -#: ../../library/functions.rst:382 ../../library/functions.rst:756 -#: ../../library/functions.rst:1004 -msgid "Examples:" -msgstr "例如： ::" - -#: ../../library/functions.rst:384 -msgid "" -">>> complex('+1.23')\n" -"(1.23+0j)\n" -">>> complex('-4.5j')\n" -"-4.5j\n" -">>> complex('-1.23+4.5j')\n" -"(-1.23+4.5j)\n" -">>> complex('\\t( -1.23+4.5J )\\n')\n" -"(-1.23+4.5j)\n" -">>> complex('-Infinity+NaNj')\n" -"(-inf+nanj)\n" -">>> complex(1.23)\n" -"(1.23+0j)\n" -">>> complex(imag=-4.5)\n" -"-4.5j\n" -">>> complex(-1.23, 4.5)\n" -"(-1.23+4.5j)" -msgstr "" -">>> complex('+1.23')\n" -"(1.23+0j)\n" -">>> complex('-4.5j')\n" -"-4.5j\n" -">>> complex('-1.23+4.5j')\n" -"(-1.23+4.5j)\n" -">>> complex('\\t( -1.23+4.5J )\\n')\n" -"(-1.23+4.5j)\n" -">>> complex('-Infinity+NaNj')\n" -"(-inf+nanj)\n" -">>> complex(1.23)\n" -"(1.23+0j)\n" -">>> complex(imag=-4.5)\n" -"-4.5j\n" -">>> complex(-1.23, 4.5)\n" -"(-1.23+4.5j)" - -#: ../../library/functions.rst:403 -msgid "" -"If the argument is a string, it must contain either a real part (in the same " -"format as for :func:`float`) or an imaginary part (in the same format but " -"with a ``'j'`` or ``'J'`` suffix), or both real and imaginary parts (the " -"sign of the imaginary part is mandatory in this case). The string can " -"optionally be surrounded by whitespaces and the round parentheses ``'('`` " -"and ``')'``, which are ignored. The string must not contain whitespace " -"between ``'+'``, ``'-'``, the ``'j'`` or ``'J'`` suffix, and the decimal " -"number. For example, ``complex('1+2j')`` is fine, but ``complex('1 + 2j')`` " -"raises :exc:`ValueError`. More precisely, the input must conform to the :" -"token:`~float:complexvalue` production rule in the following grammar, after " -"parentheses and leading and trailing whitespace characters are removed:" -msgstr "" - -#: ../../library/functions.rst:422 -msgid "" -"If the argument is a number, the constructor serves as a numeric conversion " -"like :class:`int` and :class:`float`. For a general Python object ``x``, " -"``complex(x)`` delegates to ``x.__complex__()``. If :meth:`~object." -"__complex__` is not defined then it falls back to :meth:`~object.__float__`. " -"If :meth:`!__float__` is not defined then it falls back to :meth:`~object." -"__index__`." -msgstr "" -"如果引數是一個數字，則建構函式會像 :class:`int` 和 :class:`float` 一樣進行數" -"值轉換。對於一個普通的 Python 物件 ``x``，``complex(x)`` 會委派給 ``x." -"__complex__()``。如果 :meth:`~object.__complex__` 未定義，則會回退 (fall " -"back) 到 :meth:`~object.__float__`。如果 :meth:`!__float__` 未定義，則會再回" -"退到 :meth:`~object.__index__`。" - -#: ../../library/functions.rst:431 -msgid "" -"If two arguments are provided or keyword arguments are used, each argument " -"may be any numeric type (including complex). If both arguments are real " -"numbers, return a complex number with the real component *real* and the " -"imaginary component *imag*. If both arguments are complex numbers, return a " -"complex number with the real component ``real.real-imag.imag`` and the " -"imaginary component ``real.imag+imag.real``. If one of arguments is a real " -"number, only its real component is used in the above expressions." -msgstr "" - -#: ../../library/functions.rst:441 -msgid "" -"See also :meth:`complex.from_number` which only accepts a single numeric " -"argument." -msgstr "" - -#: ../../library/functions.rst:443 -msgid "If all arguments are omitted, returns ``0j``." -msgstr "" - -#: ../../library/functions.rst:445 -msgid "The complex type is described in :ref:`typesnumeric`." -msgstr "複數型別在 :ref:`typesnumeric` 中有相關描述。" - -#: ../../library/functions.rst:447 ../../library/functions.rst:810 -#: ../../library/functions.rst:1052 -msgid "Grouping digits with underscores as in code literals is allowed." -msgstr "可以使用底線將程式碼文字中的數字進行分組。" - -#: ../../library/functions.rst:450 -msgid "" -"Falls back to :meth:`~object.__index__` if :meth:`~object.__complex__` and :" -"meth:`~object.__float__` are not defined." -msgstr "" -"如果 :meth:`~object.__complex__` 和 :meth:`~object.__float__` 未定義，則會回" -"退到 :meth:`~object.__index__`。" - -#: ../../library/functions.rst:454 -msgid "" -"Passing a complex number as the *real* or *imag* argument is now deprecated; " -"it should only be passed as a single positional argument." -msgstr "" - -#: ../../library/functions.rst:461 -msgid "" -"This is a relative of :func:`setattr`. The arguments are an object and a " -"string. The string must be the name of one of the object's attributes. The " -"function deletes the named attribute, provided the object allows it. For " -"example, ``delattr(x, 'foobar')`` is equivalent to ``del x.foobar``. *name* " -"need not be a Python identifier (see :func:`setattr`)." -msgstr "" -"這是 :func:`setattr` 相關的函式。引數是一個物件和一個字串，該字串必須是物件中" -"某個屬性名稱。如果物件允許，該函式將刪除指定的屬性。例如 ``delattr(x, " -"'foobar')`` 等價於 ``del x.foobar``。*name* 不必是個 Python 識別符 " -"(identifier)（請見 :func:`setattr`）。" - -#: ../../library/functions.rst:474 -msgid "" -"Create a new dictionary. The :class:`dict` object is the dictionary class. " -"See :class:`dict` and :ref:`typesmapping` for documentation about this class." -msgstr "" -"建立一個新的 dictionary（字典）。:class:`dict` 物件是一個 dictionary class。" -"參見 :class:`dict` 和 :ref:`typesmapping` 來瞭解這個 class。" - -#: ../../library/functions.rst:477 -msgid "" -"For other containers see the built-in :class:`list`, :class:`set`, and :" -"class:`tuple` classes, as well as the :mod:`collections` module." -msgstr "" -"其他容器型別，請參見內建的 :class:`list`、:class:`set` 和 :class:`tuple` " -"class，以及 :mod:`collections` module。" - -#: ../../library/functions.rst:484 -msgid "" -"Without arguments, return the list of names in the current local scope. " -"With an argument, attempt to return a list of valid attributes for that " -"object." -msgstr "" -"如果沒有引數，則回傳目前區域作用域 (local scope) 中的名稱列表。如果有引數，它" -"會嘗試回傳該物件的有效屬性列表。" - -#: ../../library/functions.rst:487 -msgid "" -"If the object has a method named :meth:`~object.__dir__`, this method will " -"be called and must return the list of attributes. This allows objects that " -"implement a custom :func:`~object.__getattr__` or :func:`~object." -"__getattribute__` function to customize the way :func:`dir` reports their " -"attributes." -msgstr "" -"如果物件有一個名為 :meth:`~object.__dir__` 的 method，那麼該 method 將被呼" -"叫，並且必須回傳一個屬性列表。這允許實現自訂 :func:`~object.__getattr__` " -"或 :func:`~object.__getattribute__` 函式的物件能夠自訂 :func:`dir` 來報告它" -"們的屬性。" - -#: ../../library/functions.rst:494 -msgid "" -"If the object does not provide :meth:`~object.__dir__`, the function tries " -"its best to gather information from the object's :attr:`~object.__dict__` " -"attribute, if defined, and from its type object. The resulting list is not " -"necessarily complete and may be inaccurate when the object has a custom :" -"func:`~object.__getattr__`." -msgstr "" -"如果物件不提供 :meth:`~object.__dir__`，這個函式會嘗試從物件已定義的 :attr:" -"`~object.__dict__` 屬性和型別物件收集資訊。結果列表並不總是完整的，如果物件有" -"自訂 :func:`~object.__getattr__`，那結果可能不準確。" - -#: ../../library/functions.rst:500 -msgid "" -"The default :func:`dir` mechanism behaves differently with different types " -"of objects, as it attempts to produce the most relevant, rather than " -"complete, information:" -msgstr "" -"預設的 :func:`dir` 機制對不同型別的物件有不同行為，它會試圖回傳最相關而非最完" -"整的資訊：" - -#: ../../library/functions.rst:504 -msgid "" -"If the object is a module object, the list contains the names of the " -"module's attributes." -msgstr "如果物件是 module 物件，則列表包含 module 的屬性名稱。" - -#: ../../library/functions.rst:507 -msgid "" -"If the object is a type or class object, the list contains the names of its " -"attributes, and recursively of the attributes of its bases." -msgstr "" -"如果物件是型別或 class 物件，則列表包含它們的屬性名稱，並且遞迴查詢其基礎的所" -"有屬性。" - -#: ../../library/functions.rst:510 -msgid "" -"Otherwise, the list contains the object's attributes' names, the names of " -"its class's attributes, and recursively of the attributes of its class's " -"base classes." -msgstr "" -"否則，包含物件的屬性名稱列表、它的 class 屬性名稱，並且遞迴查詢它的 class 的" -"所有基礎 class 的屬性。" - -#: ../../library/functions.rst:514 -msgid "The resulting list is sorted alphabetically. For example:" -msgstr "回傳的列表按字母表排序，例如：" - -#: ../../library/functions.rst:534 -msgid "" -"Because :func:`dir` is supplied primarily as a convenience for use at an " -"interactive prompt, it tries to supply an interesting set of names more than " -"it tries to supply a rigorously or consistently defined set of names, and " -"its detailed behavior may change across releases. For example, metaclass " -"attributes are not in the result list when the argument is a class." -msgstr "" -"因為 :func:`dir` 主要是為了便於在互動式提示字元時使用，所以它會試圖回傳人們感" -"興趣的名稱集合，而不是試圖保證結果的嚴格性或一致性，它具體的行為也可能在不同" -"版本之間改變。例如，當引數是一個 class 時，metaclass 的屬性不包含在結果列表" -"中。" - -#: ../../library/functions.rst:544 -msgid "" -"Take two (non-complex) numbers as arguments and return a pair of numbers " -"consisting of their quotient and remainder when using integer division. " -"With mixed operand types, the rules for binary arithmetic operators apply. " -"For integers, the result is the same as ``(a // b, a % b)``. For floating-" -"point numbers the result is ``(q, a % b)``, where *q* is usually ``math." -"floor(a / b)`` but may be 1 less than that. In any case ``q * b + a % b`` " -"is very close to *a*, if ``a % b`` is non-zero it has the same sign as *b*, " -"and ``0 <= abs(a % b) < abs(b)``." -msgstr "" -"它將兩個（非複數）數字作為引數，並在執行整數除法時回傳一對商和餘數。對於混合" -"運算元型別，適用二進位算術運算子的規則。對於整數，運算結果和 ``(a // b, a % " -"b)`` 一致。對於浮點數，運算結果是 ``(q, a % b)``，*q* 通常是 ``math." -"floor(a / b)`` 但可能會比 1 小。在任何情況下，``q * b + a % b`` 和 *a* 基本相" -"等，如果 ``a % b`` 非零，則它的符號和 *b* 一樣，且 ``0 <= abs(a % b) < " -"abs(b)``。" - -#: ../../library/functions.rst:556 -msgid "" -"Return an enumerate object. *iterable* must be a sequence, an :term:" -"`iterator`, or some other object which supports iteration. The :meth:" -"`~iterator.__next__` method of the iterator returned by :func:`enumerate` " -"returns a tuple containing a count (from *start* which defaults to 0) and " -"the values obtained from iterating over *iterable*." -msgstr "" -"回傳一個列舉 (enumerate) 物件。*iterable* 必須是一個序列、:term:`iterator` 或" -"其他支援疊代的物件。:func:`enumerate` 回傳之 iterator 的 :meth:`~iterator." -"__next__` method 回傳一個 tuple（元組），裡面包含一個計數值（從 *start* 開" -"始，預設為 0）和透過疊代 *iterable* 獲得的值。" - -#: ../../library/functions.rst:568 -msgid "Equivalent to::" -msgstr "等價於： ::" - -#: ../../library/functions.rst:570 -msgid "" -"def enumerate(iterable, start=0):\n" -" n = start\n" -" for elem in iterable:\n" -" yield n, elem\n" -" n += 1" -msgstr "" -"def enumerate(iterable, start=0):\n" -" n = start\n" -" for elem in iterable:\n" -" yield n, elem\n" -" n += 1" - -#: ../../library/functions.rst:0 -msgid "Parameters" -msgstr "" - -#: ../../library/functions.rst:580 -msgid "A Python expression." -msgstr "" - -#: ../../library/functions.rst:584 -msgid "The global namespace (default: ``None``)." -msgstr "" - -#: ../../library/functions.rst:588 -msgid "The local namespace (default: ``None``)." -msgstr "" - -#: ../../library/functions.rst:0 -msgid "Returns" -msgstr "" - -#: ../../library/functions.rst:592 -msgid "The result of the evaluated expression." -msgstr "" - -#: ../../library/functions.rst:0 -msgid "raises" -msgstr "引發" - -#: ../../library/functions.rst:593 -msgid "Syntax errors are reported as exceptions." -msgstr "" - -#: ../../library/functions.rst:597 ../../library/functions.rst:658 -msgid "" -"This function executes arbitrary code. Calling it with user-supplied input " -"may lead to security vulnerabilities." -msgstr "" - -#: ../../library/functions.rst:600 -msgid "" -"The *source* argument is parsed and evaluated as a Python expression " -"(technically speaking, a condition list) using the *globals* and *locals* " -"mappings as global and local namespace. If the *globals* dictionary is " -"present and does not contain a value for the key ``__builtins__``, a " -"reference to the dictionary of the built-in module :mod:`builtins` is " -"inserted under that key before *source* is parsed. That way you can control " -"what builtins are available to the executed code by inserting your own " -"``__builtins__`` dictionary into *globals* before passing it to :func:" -"`eval`. If the *locals* mapping is omitted it defaults to the *globals* " -"dictionary. If both mappings are omitted, the source is executed with the " -"*globals* and *locals* in the environment where :func:`eval` is called. " -"Note, *eval()* will only have access to the :term:`nested scopes ` (non-locals) in the enclosing environment if they are already " -"referenced in the scope that is calling :func:`eval` (e.g. via a :keyword:" -"`nonlocal` statement)." -msgstr "" -"*source* 引數會被視為一條 Python 運算式（技術上而言，是條件列表）來剖析及" -"求值，而 *globals* 和 *locals* 對映分別用作全域和區域命名空間。如果 " -"*globals* dictionary 存在但缺少 ``__builtins__`` 的鍵值，那 *source* 被剖" -"析之前，將為該鍵插入對內建 :mod:`builtins` module dictionary 的引用。這麼一" -"來，在將 ``__builtins__`` dictionary 傳入 :func:`eval` 之前，你可以透過將它插" -"入 *globals* 來控制你需要哪些內建函式來執行程式碼。如果 *locals* 對映被省略，" -"那它的預設值是 *globals* dictionary。如果兩個對映都被省略，則以在 :func:" -"`eval` 被呼叫的環境中的 *globals* 和 *locals* 執行原始碼。請注意，*eval()* 在" -"封閉 (enclosing) 環境中無法存取\\ :term:`巢狀作用域 ` (non-" -"locals)，除非呼叫 :func:`eval` 的作用域已經有參照它們（例如透過 :keyword:" -"`nonlocal` 陳述式）。" - -#: ../../library/functions.rst:616 -msgid "Example:" -msgstr "範例：" - -#: ../../library/functions.rst:622 -msgid "" -"This function can also be used to execute arbitrary code objects (such as " -"those created by :func:`compile`). In this case, pass a code object instead " -"of a string. If the code object has been compiled with ``'exec'`` as the " -"*mode* argument, :func:`eval`\\'s return value will be ``None``." -msgstr "" -"這個函式也可以用來執行任意程式碼物件（如被 :func:`compile` 建立的那些）。這種" -"情況下，傳入的引數是程式碼物件而不是字串。如果編譯該物件時的 *mode* 引數是 " -"``'exec'``，那麼 :func:`eval` 回傳值為 ``None``。" - -#: ../../library/functions.rst:627 -msgid "" -"Hints: dynamic execution of statements is supported by the :func:`exec` " -"function. The :func:`globals` and :func:`locals` functions return the " -"current global and local dictionary, respectively, which may be useful to " -"pass around for use by :func:`eval` or :func:`exec`." -msgstr "" -"提示：:func:`exec` 函式支援動態執行陳述式。:func:`globals` 和 :func:`locals` " -"函式分別回傳目前的全域性和局部性 dictionary，它們對於將引數傳遞給 :func:" -"`eval` 或 :func:`exec` 可能會方便許多。" - -#: ../../library/functions.rst:632 -msgid "" -"If the given source is a string, then leading and trailing spaces and tabs " -"are stripped." -msgstr "如果給定來源是一個字串，那麼其前後的空格和定位字元會被移除。" - -#: ../../library/functions.rst:635 -msgid "" -"See :func:`ast.literal_eval` for a function that can safely evaluate strings " -"with expressions containing only literals." -msgstr "" -"另外可以參閱 :func:`ast.literal_eval`，該函式可以安全執行僅包含文字的運算式字" -"串。" - -#: ../../library/functions.rst:638 ../../library/functions.rst:640 -#: ../../library/functions.rst:700 ../../library/functions.rst:702 -msgid "" -"Raises an :ref:`auditing event ` ``exec`` with the code object as " -"the argument. Code compilation events may also be raised." -msgstr "" -"引發一個附帶程式碼物件為引數的\\ :ref:`稽核事件 ` ``exec``。也可能" -"會引發程式碼編譯事件。" - -#: ../../library/functions.rst:645 ../../library/functions.rst:722 -msgid "The *globals* and *locals* arguments can now be passed as keywords." -msgstr "" - -#: ../../library/functions.rst:649 ../../library/functions.rst:726 -msgid "" -"The semantics of the default *locals* namespace have been adjusted as " -"described for the :func:`locals` builtin." -msgstr "" - -#: ../../library/functions.rst:661 -msgid "" -"This function supports dynamic execution of Python code. *source* must be " -"either a string or a code object. If it is a string, the string is parsed " -"as a suite of Python statements which is then executed (unless a syntax " -"error occurs). [#]_ If it is a code object, it is simply executed. In all " -"cases, the code that's executed is expected to be valid as file input (see " -"the section :ref:`file-input` in the Reference Manual). Be aware that the :" -"keyword:`nonlocal`, :keyword:`yield`, and :keyword:`return` statements may " -"not be used outside of function definitions even within the context of code " -"passed to the :func:`exec` function. The return value is ``None``." -msgstr "" -"這個函式支援動態執行 Python 程式碼。*source* 必須是字串或者程式碼物件。如果是" -"字串，那麼該字串將被剖析為一系列 Python 陳述式並執行（除非發生語法錯誤）。" -"[#]_ 如果是程式碼物件，它將被直接執行。無論哪種情況，被執行的程式碼都需要和檔" -"案輸入一樣是有效的（可參閱語言參考手冊中關於\\ :ref:`file-input`\\ 的章節）。" -"請注意，即使在傳遞給 :func:`exec` 函式的程式碼的上下文中，:keyword:" -"`nonlocal`、:keyword:`yield` 和 :keyword:`return` 陳述式也不能在函式之外使" -"用。該函式回傳值是 ``None``。" - -#: ../../library/functions.rst:672 -msgid "" -"In all cases, if the optional parts are omitted, the code is executed in the " -"current scope. If only *globals* is provided, it must be a dictionary (and " -"not a subclass of dictionary), which will be used for both the global and " -"the local variables. If *globals* and *locals* are given, they are used for " -"the global and local variables, respectively. If provided, *locals* can be " -"any mapping object. Remember that at the module level, globals and locals " -"are the same dictionary." -msgstr "" -"無論哪種情況，如果省略了選擇性的部分，程式碼將在目前作用域內執行。如果只提供" -"了 *globals* 引數，就必須是 dictionary 型別（且不能是 dictionary 的子類別），" -"而且會被用作全域和區域變數。如果同時提供了 *globals* 和 *locals*，它們分別被" -"用作全域和區域變數。如果提供了 *locals*，則它可以是任何對映物件。請記住在 " -"module 層級中全域和區域變數是相同的 dictionary。" - -#: ../../library/functions.rst:682 -msgid "" -"When ``exec`` gets two separate objects as *globals* and *locals*, the code " -"will be executed as if it were embedded in a class definition. This means " -"functions and classes defined in the executed code will not be able to " -"access variables assigned at the top level (as the \"top level\" variables " -"are treated as class variables in a class definition)." -msgstr "" - -#: ../../library/functions.rst:688 -msgid "" -"If the *globals* dictionary does not contain a value for the key " -"``__builtins__``, a reference to the dictionary of the built-in module :mod:" -"`builtins` is inserted under that key. That way you can control what " -"builtins are available to the executed code by inserting your own " -"``__builtins__`` dictionary into *globals* before passing it to :func:`exec`." -msgstr "" -"如果 *globals* dictionary 不包含 ``__builtins__`` 鍵值，則將為該鍵插入對內" -"建 :mod:`builtins` module dictionary 的引用。這麼一來，在將 ``__builtins__`` " -"dictionary 傳入 :func:`exec` 之前，你可以透過將它插入 *globals* 來控制你需要" -"哪些內建函式來執行程式碼。" - -#: ../../library/functions.rst:694 -msgid "" -"The *closure* argument specifies a closure--a tuple of cellvars. It's only " -"valid when the *object* is a code object containing :term:`free (closure) " -"variables `. The length of the tuple must exactly match " -"the length of the code object's :attr:`~codeobject.co_freevars` attribute." -msgstr "" -"*closure* 引數會指定一個閉包 (closure) — 它是一個 cellvar（格變數）的 tuple。" -"只有在 *object* 是一個含有\\ :term:`自由（閉包）變數 (free (closure) " -"variables) ` 的程式碼物件時，它才有效。Tuple 的長度必須與程" -"式碼物件的 :attr:`~codeobject.co_freevars` 屬性完全匹配。" - -#: ../../library/functions.rst:707 -msgid "" -"The built-in functions :func:`globals` and :func:`locals` return the current " -"global and local namespace, respectively, which may be useful to pass around " -"for use as the second and third argument to :func:`exec`." -msgstr "" -"內建 :func:`globals` 和 :func:`locals` 函式各自回傳目前的全域和區域命名空間，" -"因此可以將它們傳遞給 :func:`exec` 的第二個和第三個引數以供後續使用。" - -#: ../../library/functions.rst:713 -msgid "" -"The default *locals* act as described for function :func:`locals` below. " -"Pass an explicit *locals* dictionary if you need to see effects of the code " -"on *locals* after function :func:`exec` returns." -msgstr "" -"預設情況下，*locals* 的行為如下面 :func:`locals` 函式描述的一樣。如果你想在 :" -"func:`exec` 函式回傳時知道程式碼對 *locals* 的變動，請明確地傳遞 *locals* " -"dictionary 。" - -#: ../../library/functions.rst:717 -msgid "Added the *closure* parameter." -msgstr "增加了 *closure* 參數。" - -#: ../../library/functions.rst:732 -msgid "" -"Construct an iterator from those elements of *iterable* for which *function* " -"is true. *iterable* may be either a sequence, a container which supports " -"iteration, or an iterator. If *function* is ``None``, the identity function " -"is assumed, that is, all elements of *iterable* that are false are removed." -msgstr "" -"用 *iterable* 中函式 *function* 為 True 的那些元素，構建一個新的 iterator。" -"*iterable* 可以是一個序列、一個支援疊代的容器、或一個 iterator。如果 " -"*function* 是 ``None``，則會假設它是一個識別性函式，即 *iterable* 中所有假值" -"元素會被移除。" - -#: ../../library/functions.rst:738 -msgid "" -"Note that ``filter(function, iterable)`` is equivalent to the generator " -"expression ``(item for item in iterable if function(item))`` if function is " -"not ``None`` and ``(item for item in iterable if item)`` if function is " -"``None``." -msgstr "" -"請注意，``filter(function, iterable)`` 相當於一個生成器運算式，當 function 不" -"是 ``None`` 的時候為 ``(item for item in iterable if function(item))``；" -"function 是 ``None`` 的時候為 ``(item for item in iterable if item)``。" - -#: ../../library/functions.rst:743 -msgid "" -"See :func:`itertools.filterfalse` for the complementary function that " -"returns elements of *iterable* for which *function* is false." -msgstr "" -"請參閱 :func:`itertools.filterfalse`，只有 *function* 為 false 時才選取 " -"*iterable* 中元素的互補函式。" - -#: ../../library/functions.rst:754 -msgid "Return a floating-point number constructed from a number or a string." -msgstr "回傳從數字或字串生成的浮點數。" - -#: ../../library/functions.rst:758 -msgid "" -">>> float('+1.23')\n" -"1.23\n" -">>> float(' -12345\\n')\n" -"-12345.0\n" -">>> float('1e-003')\n" -"0.001\n" -">>> float('+1E6')\n" -"1000000.0\n" -">>> float('-Infinity')\n" -"-inf" -msgstr "" -">>> float('+1.23')\n" -"1.23\n" -">>> float(' -12345\\n')\n" -"-12345.0\n" -">>> float('1e-003')\n" -"0.001\n" -">>> float('+1E6')\n" -"1000000.0\n" -">>> float('-Infinity')\n" -"-inf" - -#: ../../library/functions.rst:771 -msgid "" -"If the argument is a string, it should contain a decimal number, optionally " -"preceded by a sign, and optionally embedded in whitespace. The optional " -"sign may be ``'+'`` or ``'-'``; a ``'+'`` sign has no effect on the value " -"produced. The argument may also be a string representing a NaN (not-a-" -"number), or positive or negative infinity. More precisely, the input must " -"conform to the :token:`~float:floatvalue` production rule in the following " -"grammar, after leading and trailing whitespace characters are removed:" -msgstr "" -"如果引數是字串，則它必須是包含十進位制數字的字串，字串前面可以有符號，之前也" -"可以有空格。選擇性的符號有 ``'+'`` 和 ``'-'``；``'+'`` 對建立的值沒有影響。引" -"數也可以是 NaN（非數字）或正負無窮大的字串。確切地說，除去首尾的空格後，輸入" -"必須遵循以下語法中 :token:`~float:floatvalue` 的生成規則：" - -#: ../../library/functions.rst:792 -msgid "" -"Case is not significant, so, for example, \"inf\", \"Inf\", \"INFINITY\", " -"and \"iNfINity\" are all acceptable spellings for positive infinity." -msgstr "" -"字母大小寫不影響，例如，\"inf\"、\"Inf\"、\"INFINITY\"、\"iNfINity\" 都可以表" -"示正無窮大。" - -#: ../../library/functions.rst:795 -msgid "" -"Otherwise, if the argument is an integer or a floating-point number, a " -"floating-point number with the same value (within Python's floating-point " -"precision) is returned. If the argument is outside the range of a Python " -"float, an :exc:`OverflowError` will be raised." -msgstr "" -"否則，如果引數是整數或浮點數，則回傳具有相同值（在 Python 浮點精度範圍內）的" -"浮點數。如果引數在 Python 浮點精度範圍外，則會引發 :exc:`OverflowError`。" - -#: ../../library/functions.rst:800 -msgid "" -"For a general Python object ``x``, ``float(x)`` delegates to ``x." -"__float__()``. If :meth:`~object.__float__` is not defined then it falls " -"back to :meth:`~object.__index__`." -msgstr "" -"對於一般的 Python 物件 ``x``，``float(x)`` 會委派給 ``x.__float__()``。如果未" -"定義 :meth:`~object.__float__` 則會回退到 :meth:`~object.__index__`。" - -#: ../../library/functions.rst:804 -msgid "" -"See also :meth:`float.from_number` which only accepts a numeric argument." -msgstr "" - -#: ../../library/functions.rst:806 -msgid "If no argument is given, ``0.0`` is returned." -msgstr "如果沒有引數，則回傳 ``0.0``。" - -#: ../../library/functions.rst:808 -msgid "The float type is described in :ref:`typesnumeric`." -msgstr ":ref:`typesnumeric` 描述了浮點數型別。" - -#: ../../library/functions.rst:816 -msgid "" -"Falls back to :meth:`~object.__index__` if :meth:`~object.__float__` is not " -"defined." -msgstr "" -"如果 :meth:`~object.__float__` 未定義，則會回退到 :meth:`~object.__index__`。" - -#: ../../library/functions.rst:826 -msgid "" -"Convert a *value* to a \"formatted\" representation, as controlled by " -"*format_spec*. The interpretation of *format_spec* will depend on the type " -"of the *value* argument; however, there is a standard formatting syntax that " -"is used by most built-in types: :ref:`formatspec`." -msgstr "" -"將 *value* 轉換為 *format_spec* 控制的 \"格式化\" 表示。*format_spec* 的解釋" -"取決於 *value* 引數的型別，但是大多數內建型別使用標準格式化語法：:ref:" -"`formatspec`。" - -#: ../../library/functions.rst:831 -msgid "" -"The default *format_spec* is an empty string which usually gives the same " -"effect as calling :func:`str(value) `." -msgstr "" -"預設的 *format_spec* 是一個空字串，它通常和呼叫 :func:`str(value) ` 的效" -"果相同。" - -#: ../../library/functions.rst:834 -msgid "" -"A call to ``format(value, format_spec)`` is translated to ``type(value)." -"__format__(value, format_spec)`` which bypasses the instance dictionary when " -"searching for the value's :meth:`~object.__format__` method. A :exc:" -"`TypeError` exception is raised if the method search reaches :mod:`object` " -"and the *format_spec* is non-empty, or if either the *format_spec* or the " -"return value are not strings." -msgstr "" -"呼叫 ``format(value, format_spec)`` 會轉換成 ``type(value).__format__(value, " -"format_spec)``，當搜尋 value 的 :meth:`~object.__format__` method 時，會忽略" -"實例中的字典。如果搜尋到 :mod:`object` 這個 method 但 *format_spec* 不為空，" -"或是 *format_spec* 或回傳值不是字串，則會引發 :exc:`TypeError`。" - -#: ../../library/functions.rst:841 -msgid "" -"``object().__format__(format_spec)`` raises :exc:`TypeError` if " -"*format_spec* is not an empty string." -msgstr "" -"當 *format_spec* 不是空字串時，``object().__format__(format_spec)`` 會引發 :" -"exc:`TypeError`。" - -#: ../../library/functions.rst:850 -msgid "" -"Return a new :class:`frozenset` object, optionally with elements taken from " -"*iterable*. ``frozenset`` is a built-in class. See :class:`frozenset` and :" -"ref:`types-set` for documentation about this class." -msgstr "" -"回傳一個新的 :class:`frozenset` 物件，它包含選擇性引數 *iterable* 中的元素。" -"``frozenset`` 是一個內建的 class。有關此 class 的文件，請參閱 :class:" -"`frozenset` 和 :ref:`types-set`。" - -#: ../../library/functions.rst:854 -msgid "" -"For other containers see the built-in :class:`set`, :class:`list`, :class:" -"`tuple`, and :class:`dict` classes, as well as the :mod:`collections` module." -msgstr "" -"請參閱內建的 :class:`set`、:class:`list`、:class:`tuple` 和 :class:`dict` " -"class，以及 :mod:`collections` module 來了解其它的容器。" - -#: ../../library/functions.rst:862 -msgid "" -"Return the value of the named attribute of *object*. *name* must be a " -"string. If the string is the name of one of the object's attributes, the " -"result is the value of that attribute. For example, ``getattr(x, " -"'foobar')`` is equivalent to ``x.foobar``. If the named attribute does not " -"exist, *default* is returned if provided, otherwise :exc:`AttributeError` is " -"raised. *name* need not be a Python identifier (see :func:`setattr`)." -msgstr "" -"回傳 *object* 之具名屬性的值。*name* 必須是字串。如果該字串是物件屬性之一的名" -"稱，則回傳該屬性的值。例如，``getattr(x, 'foobar')`` 等同於 ``x.foobar``。如" -"果指定的屬性不存在，且提供了 *default* 值，則回傳其值，否則引發 :exc:" -"`AttributeError`。*name* 不必是個 Python 識別符 (identifier)（請見 :func:" -"`setattr`）。" - -#: ../../library/functions.rst:871 -msgid "" -"Since :ref:`private name mangling ` happens at " -"compilation time, one must manually mangle a private attribute's (attributes " -"with two leading underscores) name in order to retrieve it with :func:" -"`getattr`." -msgstr "" -"由於\\ :ref:`私有名稱改編 (private name mangling) ` 是" -"發生在編譯期，因此你必須手動改編私有屬性（有兩個前導底線的屬性）的名稱，才能" -"使用 :func:`getattr` 來取得它。" - -#: ../../library/functions.rst:879 -msgid "" -"Return the dictionary implementing the current module namespace. For code " -"within functions, this is set when the function is defined and remains the " -"same regardless of where the function is called." -msgstr "" -"回傳代表目前 module 命名空間的 dictionary。對於在函式中的程式碼來說，這在定義" -"函式時設定且不論該函式是在何處呼叫都會保持相同。" - -#: ../../library/functions.rst:886 -msgid "" -"The arguments are an object and a string. The result is ``True`` if the " -"string is the name of one of the object's attributes, ``False`` if not. " -"(This is implemented by calling ``getattr(object, name)`` and seeing whether " -"it raises an :exc:`AttributeError` or not.)" -msgstr "" -"該引數是一個物件和一個字串。如果字串是物件屬性之一的名稱，則回傳 ``True``，否" -"則回傳 ``False``。（此功能是透過呼叫 ``getattr(object, name)`` 並檢查是否引" -"發 :exc:`AttributeError` 來實作的。）" - -#: ../../library/functions.rst:894 -msgid "" -"Return the hash value of the object (if it has one). Hash values are " -"integers. They are used to quickly compare dictionary keys during a " -"dictionary lookup. Numeric values that compare equal have the same hash " -"value (even if they are of different types, as is the case for 1 and 1.0)." -msgstr "" -"回傳該物件的雜湊值（如果它有的話）。雜湊值是整數。它們在 dictionary 查詢元素" -"時用來快速比較 dictionary 的鍵。相同大小的數字數值有相同的雜湊值（即使它們型" -"別不同，如 1 和 1.0）。" - -#: ../../library/functions.rst:901 -msgid "" -"For objects with custom :meth:`~object.__hash__` methods, note that :func:" -"`hash` truncates the return value based on the bit width of the host machine." -msgstr "" -"請注意，如果物件帶有自訂的 :meth:`~object.__hash__` 方法，:func:`hash` 將根據" -"運行機器的位元長度來截斷回傳值。" - -#: ../../library/functions.rst:908 -msgid "" -"Invoke the built-in help system. (This function is intended for interactive " -"use.) If no argument is given, the interactive help system starts on the " -"interpreter console. If the argument is a string, then the string is looked " -"up as the name of a module, function, class, method, keyword, or " -"documentation topic, and a help page is printed on the console. If the " -"argument is any other kind of object, a help page on the object is generated." -msgstr "" -"啟動內建的幫助系統（此函式主要以互動式使用）。如果沒有引數，直譯器控制台裡會" -"啟動互動式幫助系統。如果引數是一個字串，則會在 module、函式、class、method、" -"關鍵字或說明文件主題中搜尋該字串，並在控制台上列印幫助資訊。如果引數是其他任" -"意物件，則會生成該物件的幫助頁。" - -#: ../../library/functions.rst:915 -msgid "" -"Note that if a slash(/) appears in the parameter list of a function when " -"invoking :func:`help`, it means that the parameters prior to the slash are " -"positional-only. For more info, see :ref:`the FAQ entry on positional-only " -"parameters `." -msgstr "" -"請注意，呼叫 :func:`help` 時，如果斜線 (/) 出現在函式的參數列表中，這表示斜線" -"前面的參數是僅限位置 (positional-only) 參數。有關更多資訊，請參閱\\ :ref:`常" -"見問答集中的僅限位置參數條目 `。" - -#: ../../library/functions.rst:920 -msgid "" -"This function is added to the built-in namespace by the :mod:`site` module." -msgstr "此函式會被 :mod:`site` module 加入到內建命名空間。" - -#: ../../library/functions.rst:922 -msgid "" -"Changes to :mod:`pydoc` and :mod:`inspect` mean that the reported signatures " -"for callables are now more comprehensive and consistent." -msgstr "" -"對於 :mod:`pydoc` 和 :mod:`inspect` 的變更，使得可呼叫物件回報的的簽名 " -"(signature) 更加全面和一致。" - -#: ../../library/functions.rst:929 -msgid "" -"Convert an integer number to a lowercase hexadecimal string prefixed with " -"\"0x\". If *integer* is not a Python :class:`int` object, it has to define " -"an :meth:`~object.__index__` method that returns an integer. Some examples:" -msgstr "" -"將整數轉換為以 \"0x\" 為前綴的小寫十六進位制字串。如果 *integer* 不是 " -"Python :class:`int` 物件，則必須定義一個 :meth:`~object.__index__` method 並" -"且回傳一個整數。舉例來說：" - -#: ../../library/functions.rst:938 -msgid "" -"If you want to convert an integer number to an uppercase or lower " -"hexadecimal string with prefix or not, you can use either of the following " -"ways:" -msgstr "" -"如果要將整數轉換為大寫或小寫的十六進位制字串，並可選擇有無 \"0x\" 前綴，則可" -"以使用如下方法：" - -#: ../../library/functions.rst:950 -msgid "" -"See also :func:`int` for converting a hexadecimal string to an integer using " -"a base of 16." -msgstr "另請參閱 :func:`int` 將十六進位制字串轉換為以 16 為基數的整數。" - -#: ../../library/functions.rst:955 -msgid "" -"To obtain a hexadecimal string representation for a float, use the :meth:" -"`float.hex` method." -msgstr "" -"如果要取得浮點數的十六進位制字串形式，請使用 :meth:`float.hex` method。" - -#: ../../library/functions.rst:961 -msgid "" -"Return the \"identity\" of an object. This is an integer which is " -"guaranteed to be unique and constant for this object during its lifetime. " -"Two objects with non-overlapping lifetimes may have the same :func:`id` " -"value." -msgstr "" -"回傳物件的 \"識別性\" 。該值是一個整數，在此物件的生命週期中保證是唯一且恆定" -"的。兩個生命期不重疊的物件可能具有相同的 :func:`id` 值。" - -#: ../../library/functions.rst:966 -msgid "This is the address of the object in memory." -msgstr "這是該物件在記憶體中的位址。" - -#: ../../library/functions.rst:968 -msgid "" -"Raises an :ref:`auditing event ` ``builtins.id`` with argument " -"``id``." -msgstr "" -"引發一個附帶引數 ``id`` 的\\ :ref:`稽核事件 ` ``builtins.id``。" - -#: ../../library/functions.rst:974 -msgid "" -"If the *prompt* argument is present, it is written to standard output " -"without a trailing newline. The function then reads a line from input, " -"converts it to a string (stripping a trailing newline), and returns that. " -"When EOF is read, :exc:`EOFError` is raised. Example::" -msgstr "" -"如果有提供 *prompt* 引數，則將其寫入標準輸出，末尾不帶換行符。接下來，該函式" -"從輸入中讀取一行，將其轉換為字串（去除末尾的換行符）並回傳。當讀取到 EOF 時，" -"則引發 :exc:`EOFError`。例如： ::" - -#: ../../library/functions.rst:979 -msgid "" -">>> s = input('--> ')\n" -"--> Monty Python's Flying Circus\n" -">>> s\n" -"\"Monty Python's Flying Circus\"" -msgstr "" -">>> s = input('--> ')\n" -"--> Monty Python's Flying Circus\n" -">>> s\n" -"\"Monty Python's Flying Circus\"" - -#: ../../library/functions.rst:984 -msgid "" -"If the :mod:`readline` module was loaded, then :func:`input` will use it to " -"provide elaborate line editing and history features." -msgstr "" -"如果載入了 :mod:`readline` module，:func:`input` 將使用它來提供複雜的行編輯和" -"歷史記錄功能。" - -#: ../../library/functions.rst:987 ../../library/functions.rst:989 -msgid "" -"Raises an :ref:`auditing event ` ``builtins.input`` with argument " -"``prompt`` before reading input" -msgstr "" -"引發一個附帶讀取輸入前的引數 ``prompt`` 的\\ :ref:`稽核事件 ` " -"``builtins.input``。" - -#: ../../library/functions.rst:992 ../../library/functions.rst:994 -msgid "" -"Raises an :ref:`auditing event ` ``builtins.input/result`` with " -"the result after successfully reading input." -msgstr "" -"引發一個附帶成功讀取結果的\\ :ref:`稽核事件 ` ``builtins.input/" -"result``。" - -#: ../../library/functions.rst:1001 -msgid "" -"Return an integer object constructed from a number or a string, or return " -"``0`` if no arguments are given." -msgstr "" - -#: ../../library/functions.rst:1006 -msgid "" -">>> int(123.45)\n" -"123\n" -">>> int('123')\n" -"123\n" -">>> int(' -12_345\\n')\n" -"-12345\n" -">>> int('FACE', 16)\n" -"64206\n" -">>> int('0xface', 0)\n" -"64206\n" -">>> int('01110011', base=2)\n" -"115" -msgstr "" -">>> int(123.45)\n" -"123\n" -">>> int('123')\n" -"123\n" -">>> int(' -12_345\\n')\n" -"-12345\n" -">>> int('FACE', 16)\n" -"64206\n" -">>> int('0xface', 0)\n" -"64206\n" -">>> int('01110011', base=2)\n" -"115" - -#: ../../library/functions.rst:1021 -msgid "" -"If the argument defines :meth:`~object.__int__`, ``int(x)`` returns ``x." -"__int__()``. If the argument defines :meth:`~object.__index__`, it returns " -"``x.__index__()``. For floating-point numbers, this truncates towards zero." -msgstr "" -"如果引數定義了 :meth:`~object.__int__`，則 ``int(x)`` 會回傳 ``x." -"__int__()``。如果引數定義了 :meth:`~object.__index__` 則回傳 ``x." -"__index__()``。對於浮點數，則會向零的方向無條件捨去。" - -#: ../../library/functions.rst:1026 -msgid "" -"If the argument is not a number or if *base* is given, then it must be a " -"string, :class:`bytes`, or :class:`bytearray` instance representing an " -"integer in radix *base*. Optionally, the string can be preceded by ``+`` or " -"``-`` (with no space in between), have leading zeros, be surrounded by " -"whitespace, and have single underscores interspersed between digits." -msgstr "" -"如果引數不是數字或如果有給定 *base*，則它必須是個字串、:class:`bytes` 或 :" -"class:`bytearray` 實例，表示基數 (radix) *base* 中的整數。可選地，字串之前可" -"以有 ``+`` 或 ``-``\\ （中間沒有空格）、可有個前導的零、也可被空格包圍、或在" -"數字間有單一底線。" - -#: ../../library/functions.rst:1032 -msgid "" -"A base-n integer string contains digits, each representing a value from 0 to " -"n-1. The values 0--9 can be represented by any Unicode decimal digit. The " -"values 10--35 can be represented by ``a`` to ``z`` (or ``A`` to ``Z``). The " -"default *base* is 10. The allowed bases are 0 and 2--36. Base-2, -8, and -16 " -"strings can be optionally prefixed with ``0b``/``0B``, ``0o``/``0O``, or " -"``0x``/``0X``, as with integer literals in code. For base 0, the string is " -"interpreted in a similar way to an :ref:`integer literal in code " -"`, in that the actual base is 2, 8, 10, or 16 as determined by the " -"prefix. Base 0 also disallows leading zeros: ``int('010', 0)`` is not legal, " -"while ``int('010')`` and ``int('010', 8)`` are." -msgstr "" -"一個 n 進制的整數字串，包含各個代表 0 到 n-1 的數字，0–9 可以用任何 Unicode " -"十進制數字表示，10–35 可以用 ``a`` 到 ``z``\\ （或 ``A`` 到 ``Z``\\ ）表示。" -"預設的 *base* 是 10。允許的進位制有 0、2–36。2、8、16 進位制的字串可以在程式" -"碼中用 ``0b``/``0B``、``0o``/``0O``、``0x``/``0X`` 前綴來表示，如同程式碼中的" -"整數文字。進位制為 0 的字串將以和\\ :ref:`程式碼整數字面值 (integer literal " -"in code) ` 類似的方式來直譯，最後由前綴決定的結果會是 2、8、10、16 " -"進制中的一個，所以 ``int('010', 0)`` 是非法的，但 ``int('010')`` 和 " -"``int('010', 8)`` 是有效的。" - -#: ../../library/functions.rst:1043 -msgid "The integer type is described in :ref:`typesnumeric`." -msgstr "整數型別定義請參閱\\ :ref:`typesnumeric`。" - -#: ../../library/functions.rst:1045 -msgid "" -"If *base* is not an instance of :class:`int` and the *base* object has a :" -"meth:`base.__index__ ` method, that method is called to " -"obtain an integer for the base. Previous versions used :meth:`base.__int__ " -"` instead of :meth:`base.__index__ `." -msgstr "" -"如果 *base* 不是 :class:`int` 的實例，但 *base* 物件有 :meth:`base.__index__ " -"` method，則會呼叫該 method 來取得此進位制所需的整數。以前" -"的版本使用 :meth:`base.__int__ ` 而不是 :meth:`base." -"__index__ `。" - -#: ../../library/functions.rst:1055 -msgid "The first parameter is now positional-only." -msgstr "第一個參數為僅限位置參數。" - -#: ../../library/functions.rst:1058 -msgid "" -"Falls back to :meth:`~object.__index__` if :meth:`~object.__int__` is not " -"defined." -msgstr "" -"如果未定義 :meth:`~object.__int__` 則會回退到 :meth:`~object.__index__`。" - -#: ../../library/functions.rst:1061 -msgid "" -":class:`int` string inputs and string representations can be limited to help " -"avoid denial of service attacks. A :exc:`ValueError` is raised when the " -"limit is exceeded while converting a string to an :class:`int` or when " -"converting an :class:`int` into a string would exceed the limit. See the :" -"ref:`integer string conversion length limitation ` " -"documentation." -msgstr "" -":class:`int` 的字串輸入和字串表示法可以被限制，以避免阻斷服務攻擊 (denial of " -"service attack)。在字串 *x* 轉換為 :class:`int` 時已超出限制，或是在 :class:" -"`int` 轉換為字串時將會超出限制時，會引發 :exc:`ValueError`。請參閱\\ :ref:`整" -"數字串轉換的長度限制 `\\ 說明文件。" - -#: ../../library/functions.rst:1069 -msgid "" -":func:`int` no longer delegates to the :meth:`~object.__trunc__` method." -msgstr ":func:`int` 不再委派給 :meth:`~object.__trunc__` method。" - -#: ../../library/functions.rst:1074 -msgid "" -"Return ``True`` if the *object* argument is an instance of the *classinfo* " -"argument, or of a (direct, indirect, or :term:`virtual `) subclass thereof. If *object* is not an object of the given type, " -"the function always returns ``False``. If *classinfo* is a tuple of type " -"objects (or recursively, other such tuples) or a :ref:`types-union` of " -"multiple types, return ``True`` if *object* is an instance of any of the " -"types. If *classinfo* is not a type or tuple of types and such tuples, a :" -"exc:`TypeError` exception is raised. :exc:`TypeError` may not be raised for " -"an invalid type if an earlier check succeeds." -msgstr "" -"如果 *object* 引數是 *classinfo* 引數的實例，或者是（直接、間接或 :term:" -"`virtual `）subclass 的實例，則回傳 ``True``。如果 " -"*object* 不是給定型別的物件，函式始終回傳 ``False``。如果 *classinfo* 是包含" -"物件型別的 tuple（或多個遞迴 tuple）或一個包含多種型別的 :ref:`types-union`，" -"若 *object* 是其中的任何一個物件的實例則回傳 ``True``。如果 *classinfo* 既不" -"是型別，也不是型別 tuple 或型別的遞迴 tuple，那麼會引發 :exc:`TypeError` 異" -"常。若是先前檢查已經成功，:exc:`TypeError` 可能不會再因為不合格的型別而被引" -"發。" - -#: ../../library/functions.rst:1085 ../../library/functions.rst:1099 -msgid "*classinfo* can be a :ref:`types-union`." -msgstr "*classinfo* 可以是一個 :ref:`types-union`。" - -#: ../../library/functions.rst:1091 -msgid "" -"Return ``True`` if *class* is a subclass (direct, indirect, or :term:" -"`virtual `) of *classinfo*. A class is considered a " -"subclass of itself. *classinfo* may be a tuple of class objects (or " -"recursively, other such tuples) or a :ref:`types-union`, in which case " -"return ``True`` if *class* is a subclass of any entry in *classinfo*. In " -"any other case, a :exc:`TypeError` exception is raised." -msgstr "" -"如果 *class* 是 *classinfo* 的 subclass（直接、間接或 :term:`virtual " -"`），則回傳 ``True``。*classinfo* 可以是 class 物件的 " -"tuple（或遞迴地其他類似 tuple）或是一個 :ref:`types-union`，此時若 *class* " -"是 *classinfo* 中任一元素的 subclass 時則回傳 ``True``。其他情況，會引發 :" -"exc:`TypeError`。" - -#: ../../library/functions.rst:1106 -msgid "" -"Return an :term:`iterator` object. The first argument is interpreted very " -"differently depending on the presence of the second argument. Without a " -"second argument, the single argument must be a collection object which " -"supports the :term:`iterable` protocol (the :meth:`~object.__iter__` " -"method), or it must support the sequence protocol (the :meth:`~object." -"__getitem__` method with integer arguments starting at ``0``). If it does " -"not support either of those protocols, :exc:`TypeError` is raised. If the " -"second argument, *sentinel*, is given, then the first argument must be a " -"callable object. The iterator created in this case will call *callable* " -"with no arguments for each call to its :meth:`~iterator.__next__` method; if " -"the value returned is equal to *sentinel*, :exc:`StopIteration` will be " -"raised, otherwise the value will be returned." -msgstr "" -"回傳一個 :term:`iterator` 物件。根據是否存在第二個引數，第一個引數的意義是非" -"常不同的。如果沒有第二個引數，該單一引數必須是支援 :term:`iterable` 協定" -"（有 :meth:`~object.__iter__` method）的集合物件，或必須支援序列協定（有 :" -"meth:`~object.__getitem__` 方法，且數字引數從 ``0`` 開始）。如果它不支援這些" -"協定，會引發 :exc:`TypeError`。如果有第二個引數 *sentinel*，那麼第一引數必須" -"是可呼叫的物件，這種情況下生成的 iterator，每次疊代呼叫 :meth:`~iterator." -"__next__` 時會不帶引數地呼叫 *callable*；如果回傳的結果是 *sentinel* 則引發 :" -"exc:`StopIteration`，否則回傳呼叫結果。" - -#: ../../library/functions.rst:1120 -msgid "See also :ref:`typeiter`." -msgstr "另請參閱 :ref:`typeiter`。" - -#: ../../library/functions.rst:1122 -msgid "" -"One useful application of the second form of :func:`iter` is to build a " -"block-reader. For example, reading fixed-width blocks from a binary database " -"file until the end of file is reached::" -msgstr "" -":func:`iter` 的第二種形式有一個好用的應用，是能夠建立一個區塊閱讀器 (block-" -"reader)。例如，從二進位資料庫檔案中讀取固定寬度的區塊，直到檔案的結尾： ::" - -#: ../../library/functions.rst:1126 -msgid "" -"from functools import partial\n" -"with open('mydata.db', 'rb') as f:\n" -" for block in iter(partial(f.read, 64), b''):\n" -" process_block(block)" -msgstr "" -"from functools import partial\n" -"with open('mydata.db', 'rb') as f:\n" -" for block in iter(partial(f.read, 64), b''):\n" -" process_block(block)" - -#: ../../library/functions.rst:1134 -msgid "" -"Return the length (the number of items) of an object. The argument may be a " -"sequence (such as a string, bytes, tuple, list, or range) or a collection " -"(such as a dictionary, set, or frozen set)." -msgstr "" -"回傳物件的長度（元素個數）。引數可以是序列（如 string、bytes、tuple、list 或 " -"range）或集合（如 dictionary、set 或 frozen set）。" - -#: ../../library/functions.rst:1140 -msgid "" -"``len`` raises :exc:`OverflowError` on lengths larger than :data:`sys." -"maxsize`, such as :class:`range(2 ** 100) `." -msgstr "" -"如果物件長度大於 :data:`sys.maxsize`，像是 :class:`range(2 ** 100) `，" -"則 ``len`` 會引發 :exc:`OverflowError`。" - -#: ../../library/functions.rst:1148 -msgid "" -"Rather than being a function, :class:`list` is actually a mutable sequence " -"type, as documented in :ref:`typesseq-list` and :ref:`typesseq`." -msgstr "" -"除了是函式，:class:`list` 也是可變序列型別，詳情請參閱 :ref:`typesseq-list` " -"和 :ref:`typesseq`。" - -#: ../../library/functions.rst:1154 -msgid "" -"Return a mapping object representing the current local symbol table, with " -"variable names as the keys, and their currently bound references as the " -"values." -msgstr "" - -#: ../../library/functions.rst:1158 -msgid "" -"At module scope, as well as when using :func:`exec` or :func:`eval` with a " -"single namespace, this function returns the same namespace as :func:" -"`globals`." -msgstr "" - -#: ../../library/functions.rst:1162 -msgid "" -"At class scope, it returns the namespace that will be passed to the " -"metaclass constructor." -msgstr "" - -#: ../../library/functions.rst:1165 -msgid "" -"When using ``exec()`` or ``eval()`` with separate local and global " -"arguments, it returns the local namespace passed in to the function call." -msgstr "" - -#: ../../library/functions.rst:1168 -msgid "" -"In all of the above cases, each call to ``locals()`` in a given frame of " -"execution will return the *same* mapping object. Changes made through the " -"mapping object returned from ``locals()`` will be visible as assigned, " -"reassigned, or deleted local variables, and assigning, reassigning, or " -"deleting local variables will immediately affect the contents of the " -"returned mapping object." -msgstr "" - -#: ../../library/functions.rst:1175 -msgid "" -"In an :term:`optimized scope` (including functions, generators, and " -"coroutines), each call to ``locals()`` instead returns a fresh dictionary " -"containing the current bindings of the function's local variables and any " -"nonlocal cell references. In this case, name binding changes made via the " -"returned dict are *not* written back to the corresponding local variables or " -"nonlocal cell references, and assigning, reassigning, or deleting local " -"variables and nonlocal cell references does *not* affect the contents of " -"previously returned dictionaries." -msgstr "" - -#: ../../library/functions.rst:1184 -msgid "" -"Calling ``locals()`` as part of a comprehension in a function, generator, or " -"coroutine is equivalent to calling it in the containing scope, except that " -"the comprehension's initialised iteration variables will be included. In " -"other scopes, it behaves as if the comprehension were running as a nested " -"function." -msgstr "" - -#: ../../library/functions.rst:1190 -msgid "" -"Calling ``locals()`` as part of a generator expression is equivalent to " -"calling it in a nested generator function." -msgstr "" - -#: ../../library/functions.rst:1193 -msgid "" -"The behaviour of ``locals()`` in a comprehension has been updated as " -"described in :pep:`709`." -msgstr "" - -#: ../../library/functions.rst:1197 -msgid "" -"As part of :pep:`667`, the semantics of mutating the mapping objects " -"returned from this function are now defined. The behavior in :term:" -"`optimized scopes ` is now as described above. Aside from " -"being defined, the behaviour in other scopes remains unchanged from previous " -"versions." -msgstr "" - -#: ../../library/functions.rst:1207 -msgid "" -"Return an iterator that applies *function* to every item of *iterable*, " -"yielding the results. If additional *iterables* arguments are passed, " -"*function* must take that many arguments and is applied to the items from " -"all iterables in parallel. With multiple iterables, the iterator stops when " -"the shortest iterable is exhausted. If *strict* is ``True`` and one of the " -"iterables is exhausted before the others, a :exc:`ValueError` is raised. For " -"cases where the function inputs are already arranged into argument tuples, " -"see :func:`itertools.starmap`." -msgstr "" -"產生一個將 *function* 應用於 *iterable* 中所有項目並 yield 回傳結果的疊代器。" -"如果傳遞了額外的 *iterables* 引數，則 *function* 必須接受相同個數的引數，且 " -"*function* 會平行地被應用於所有可疊代物件的項目。當有多個可疊代物件時，項目最" -"少的可疊代物件耗盡時疊代器也會結束。如果 *strict* 為 ``True`` 且其中一個可疊" -"代物件在其他可疊代物件之前耗盡，則會拋出 :exc:`ValueError`。如果函式的輸入已" -"經被編排為引數的元組，請參閱 :func:`itertools.starmap`。" - -#: ../../library/functions.rst:1216 -msgid "Added the *strict* parameter." -msgstr "增加了 *strict* 參數。" - -#: ../../library/functions.rst:1224 -msgid "" -"Return the largest item in an iterable or the largest of two or more " -"arguments." -msgstr "回傳 iterable 中最大的元素，或者回傳兩個以上的引數中最大的。" - -#: ../../library/functions.rst:1227 -msgid "" -"If one positional argument is provided, it should be an :term:`iterable`. " -"The largest item in the iterable is returned. If two or more positional " -"arguments are provided, the largest of the positional arguments is returned." -msgstr "" -"如果只提供了一個位置引數，它必須是個 :term:`iterable`，iterable 中最大的元素" -"會被回傳。如果提供了兩個或以上的位置引數，則回傳最大的位置引數。" - -#: ../../library/functions.rst:1232 ../../library/functions.rst:1270 -msgid "" -"There are two optional keyword-only arguments. The *key* argument specifies " -"a one-argument ordering function like that used for :meth:`list.sort`. The " -"*default* argument specifies an object to return if the provided iterable is " -"empty. If the iterable is empty and *default* is not provided, a :exc:" -"`ValueError` is raised." -msgstr "" -"這個函式有兩個選擇性的僅限關鍵字引數。*key* 引數能指定單一引數所使用的排序函" -"式，如同 :meth:`list.sort` 的使用方式。*default* 引數是當 iterable 為空時回傳" -"的物件。如果 iterable 為空，並且沒有提供 *default*，則會引發 :exc:" -"`ValueError`。" - -#: ../../library/functions.rst:1238 -msgid "" -"If multiple items are maximal, the function returns the first one " -"encountered. This is consistent with other sort-stability preserving tools " -"such as ``sorted(iterable, key=keyfunc, reverse=True)[0]`` and ``heapq." -"nlargest(1, iterable, key=keyfunc)``." -msgstr "" -"如果有多個最大元素，則此函式將回傳第一個找到的。這和其他穩定排序工具如 " -"``sorted(iterable, key=keyfunc, reverse=True)[0]`` 和 ``heapq.nlargest(1, " -"iterable, key=keyfunc)`` 一致。" - -#: ../../library/functions.rst:1243 ../../library/functions.rst:1281 -msgid "Added the *default* keyword-only parameter." -msgstr "新增 *default* 僅限關鍵字參數。" - -#: ../../library/functions.rst:1246 ../../library/functions.rst:1284 -msgid "The *key* can be ``None``." -msgstr "*key* 可以為 ``None``。" - -#: ../../library/functions.rst:1254 -msgid "" -"Return a \"memory view\" object created from the given argument. See :ref:" -"`typememoryview` for more information." -msgstr "" -"回傳由給定的引數所建立之「memory view（記憶體檢視）」物件。有關詳細資訊，請參" -"閱\\ :ref:`typememoryview`。" - -#: ../../library/functions.rst:1262 -msgid "" -"Return the smallest item in an iterable or the smallest of two or more " -"arguments." -msgstr "回傳 iterable 中最小的元素，或者回傳兩個以上的引數中最小的。" - -#: ../../library/functions.rst:1265 -msgid "" -"If one positional argument is provided, it should be an :term:`iterable`. " -"The smallest item in the iterable is returned. If two or more positional " -"arguments are provided, the smallest of the positional arguments is returned." -msgstr "" -"如果只提供了一個位置引數，它必須是 :term:`iterable`，iterable 中最小的元素會" -"被回傳。如果提供了兩個以上的位置引數，則回傳最小的位置引數。" - -#: ../../library/functions.rst:1276 -msgid "" -"If multiple items are minimal, the function returns the first one " -"encountered. This is consistent with other sort-stability preserving tools " -"such as ``sorted(iterable, key=keyfunc)[0]`` and ``heapq.nsmallest(1, " -"iterable, key=keyfunc)``." -msgstr "" -"如果有多個最小元素，則此函式將回傳第一個找到的。這和其他穩定排序工具如 " -"``sorted(iterable, key=keyfunc)[0]`` 和 ``heapq.nsmallest(1, iterable, " -"key=keyfunc)`` 一致。" - -#: ../../library/functions.rst:1291 -msgid "" -"Retrieve the next item from the :term:`iterator` by calling its :meth:" -"`~iterator.__next__` method. If *default* is given, it is returned if the " -"iterator is exhausted, otherwise :exc:`StopIteration` is raised." -msgstr "" -"透過呼叫 :term:`iterator` 的 :meth:`~iterator.__next__` method 取得下一個元" -"素。如果 iterator 耗盡，則回傳給定的預設值 *default*，如果沒有預設值則引發 :" -"exc:`StopIteration`。" - -#: ../../library/functions.rst:1298 -msgid "" -"This is the ultimate base class of all other classes. It has methods that " -"are common to all instances of Python classes. When the constructor is " -"called, it returns a new featureless object. The constructor does not accept " -"any arguments." -msgstr "" -"這是所有其他 class 的基礎，它具有所有 Python class 實例的通用 method。當建構" -"函式被呼叫時，它會回傳一個新的沒有特徵 (featureless) 的物件。這個建構函式不接" -"受任何引數。" - -#: ../../library/functions.rst:1305 -msgid "" -":class:`object` instances do *not* have :attr:`~object.__dict__` attributes, " -"so you can't assign arbitrary attributes to an instance of :class:`object`." -msgstr "" -"由於 :class:`object` 實例\\ *沒有* :attr:`~object.__dict__` 屬性，因此無法將" -"任意屬性賦給 :class:`object` 的實例。" - -#: ../../library/functions.rst:1312 -msgid "" -"Convert an integer number to an octal string prefixed with \"0o\". The " -"result is a valid Python expression. If *integer* is not a Python :class:" -"`int` object, it has to define an :meth:`~object.__index__` method that " -"returns an integer. For example:" -msgstr "" -"將一個整數轉變為一個前綴為 \"0o\" 的八進位制字串。回傳結果是一個有效的 " -"Python 運算式。如果 *integer* 不是 Python 的 :class:`int` 物件，那它需要定" -"義 :meth:`~object.__index__` method 回傳一個整數。舉例來說：" - -#: ../../library/functions.rst:1322 -msgid "" -"If you want to convert an integer number to an octal string either with the " -"prefix \"0o\" or not, you can use either of the following ways." -msgstr "" -"如果要將整數轉換為八進位制字串，不論是否具備 \"0o\" 前綴，都可以使用下面的方" -"法。" - -#: ../../library/functions.rst:1339 -msgid "" -"Open *file* and return a corresponding :term:`file object`. If the file " -"cannot be opened, an :exc:`OSError` is raised. See :ref:`tut-files` for more " -"examples of how to use this function." -msgstr "" -"開啟 *file* 並回傳對應的\\ :term:`檔案物件 `。如果該檔案不能開" -"啟，則引發 :exc:`OSError`。關於使用此函式的更多方法，請參閱\\ :ref:`tut-" -"files`。" - -#: ../../library/functions.rst:1343 -msgid "" -"*file* is a :term:`path-like object` giving the pathname (absolute or " -"relative to the current working directory) of the file to be opened or an " -"integer file descriptor of the file to be wrapped. (If a file descriptor is " -"given, it is closed when the returned I/O object is closed unless *closefd* " -"is set to ``False``.)" -msgstr "" -"*file* 是一個\\ :term:`類路徑物件 `，是將被開啟之檔案的路徑" -"（絕對路徑或目前工作目錄的相對路徑），或是要被包裝 (wrap) 檔案的整數檔案描述" -"器 (file descriptor)。（如果有給定檔案描述器，它會隨著回傳的 I/O 物件關閉而關" -"閉，除非 *closefd* 被設為 ``False``。）" - -#: ../../library/functions.rst:1349 -msgid "" -"*mode* is an optional string that specifies the mode in which the file is " -"opened. It defaults to ``'r'`` which means open for reading in text mode. " -"Other common values are ``'w'`` for writing (truncating the file if it " -"already exists), ``'x'`` for exclusive creation, and ``'a'`` for appending " -"(which on *some* Unix systems, means that *all* writes append to the end of " -"the file regardless of the current seek position). In text mode, if " -"*encoding* is not specified the encoding used is platform-dependent: :func:" -"`locale.getencoding` is called to get the current locale encoding. (For " -"reading and writing raw bytes use binary mode and leave *encoding* " -"unspecified.) The available modes are:" -msgstr "" -"*mode* 是一個選擇性字串，用於指定開啟檔案的模式。預設值是 ``'r'``，這意味著它" -"以文字模式開啟並讀取。其他常見模式有：寫入 ``'w'``\\ （會捨去已經存在的檔" -"案）、唯一性建立 ``'x'``、追加寫入 ``'a'``\\ （在\\ *一些* Unix 系統上，無論" -"目前的檔案指標在什麼位置，*所有* 寫入都會追加到檔案末尾）。在文字模式，如果沒" -"有指定 *encoding*，則根據電腦平臺來決定使用的編碼：呼叫 :func:`locale." -"getencoding` 來取得目前的本地編碼。（要讀取和寫入原始 bytes，請使用二進位制模" -"式且不要指定 *encoding*。）可用的模式有：" - -#: ../../library/functions.rst:1366 -msgid "Character" -msgstr "字元" - -#: ../../library/functions.rst:1366 -msgid "Meaning" -msgstr "意義" - -#: ../../library/functions.rst:1368 -msgid "``'r'``" -msgstr "``'r'``" - -#: ../../library/functions.rst:1368 -msgid "open for reading (default)" -msgstr "讀取（預設）" - -#: ../../library/functions.rst:1369 -msgid "``'w'``" -msgstr "``'w'``" - -#: ../../library/functions.rst:1369 -msgid "open for writing, truncating the file first" -msgstr "寫入，會先清除檔案內容" - -#: ../../library/functions.rst:1370 -msgid "``'x'``" -msgstr "``'x'``" - -#: ../../library/functions.rst:1370 -msgid "open for exclusive creation, failing if the file already exists" -msgstr "唯一性建立，如果文件已存在則會失敗" - -#: ../../library/functions.rst:1371 -msgid "``'a'``" -msgstr "``'a'``" - -#: ../../library/functions.rst:1371 -msgid "open for writing, appending to the end of file if it exists" -msgstr "寫入，如果檔案存在則在其末端附加內容" - -#: ../../library/functions.rst:1372 -msgid "``'b'``" -msgstr "``'b'``" - -#: ../../library/functions.rst:1372 ../../library/functions.rst:1516 -msgid "binary mode" -msgstr "二進制模式" - -#: ../../library/functions.rst:1373 -msgid "``'t'``" -msgstr "``'t'``" - -#: ../../library/functions.rst:1373 -msgid "text mode (default)" -msgstr "文字模式（預設）" - -#: ../../library/functions.rst:1374 -msgid "``'+'``" -msgstr "``'+'``" - -#: ../../library/functions.rst:1374 -msgid "open for updating (reading and writing)" -msgstr "更新（讀取並寫入）" - -#: ../../library/functions.rst:1377 -msgid "" -"The default mode is ``'r'`` (open for reading text, a synonym of ``'rt'``). " -"Modes ``'w+'`` and ``'w+b'`` open and truncate the file. Modes ``'r+'`` and " -"``'r+b'`` open the file with no truncation." -msgstr "" -"預設的模式是 ``'r'``\\ （開啟並讀取文字，同 ``'rt'``）。``'w+'`` 和 " -"``'w+b'`` 模式會開啟並清除檔案。``'r+'`` 和 ``'r+b'`` 模式會開啟且保留檔案內" -"容。" - -#: ../../library/functions.rst:1381 -msgid "" -"As mentioned in the :ref:`io-overview`, Python distinguishes between binary " -"and text I/O. Files opened in binary mode (including ``'b'`` in the *mode* " -"argument) return contents as :class:`bytes` objects without any decoding. " -"In text mode (the default, or when ``'t'`` is included in the *mode* " -"argument), the contents of the file are returned as :class:`str`, the bytes " -"having been first decoded using a platform-dependent encoding or using the " -"specified *encoding* if given." -msgstr "" -"如\\ :ref:`io-overview`\\ 中所述，Python 能區分二進制和文字的 I/O。在二進制模" -"式下開啟的檔案（*mode* 引數中含有 ``'b'``）會將其內容以 :class:`bytes` 物件回" -"傳，而不進行任何解碼。在文字模式（預設情況，或當 *mode* 引數中含有 " -"``'t'``），檔案的內容會以 :class:`str` 回傳，其位元組已經先被解碼，使用的是取" -"決於平台的編碼系統或是給定的 *encoding*。" - -#: ../../library/functions.rst:1391 -msgid "" -"Python doesn't depend on the underlying operating system's notion of text " -"files; all the processing is done by Python itself, and is therefore " -"platform-independent." -msgstr "" -"Python 不會使用底層作業系統對於文字檔案的操作概念；所有的處理都是由 Python 獨" -"自完成的，因此能獨立於不同平台。" - -#: ../../library/functions.rst:1395 -msgid "" -"*buffering* is an optional integer used to set the buffering policy. Pass 0 " -"to switch buffering off (only allowed in binary mode), 1 to select line " -"buffering (only usable when writing in text mode), and an integer > 1 to " -"indicate the size in bytes of a fixed-size chunk buffer. Note that " -"specifying a buffer size this way applies for binary buffered I/O, but " -"``TextIOWrapper`` (i.e., files opened with ``mode='r+'``) would have another " -"buffering. To disable buffering in ``TextIOWrapper``, consider using the " -"``write_through`` flag for :func:`io.TextIOWrapper.reconfigure`. When no " -"*buffering* argument is given, the default buffering policy works as follows:" -msgstr "" -"*buffering* 是一個選擇性的整數，用於設定緩衝策略。傳入 0 表示關閉緩衝（僅在二" -"進制模式下被允許），1 表示行緩衝（line buffering，僅在文字模式下可用），而 " -">1 的整數是指示一個大小固定的區塊緩衝區 (chunk buffer)，其位元組的數量。請注" -"意，此類指定緩衝區大小的方式適用於二進制緩衝 I/O，但是 ``TextIOWrapper``\\ " -"（以 ``mode='r+'`` 開啟的檔案）會有另一種緩衝方式。若要在 ``TextIOWrapper`` " -"中停用緩衝，可考慮使用 :func:`io.TextIOWrapper.reconfigure` 的 " -"``write_through`` 旗標。若未給定 *buffering* 引數，則預設的緩衝策略會運作如" -"下：" - -#: ../../library/functions.rst:1405 -msgid "" -"Binary files are buffered in fixed-size chunks; the size of the buffer is " -"``max(min(blocksize, 8 MiB), DEFAULT_BUFFER_SIZE)`` when the device block " -"size is available. On most systems, the buffer will typically be 128 " -"kilobytes long." -msgstr "" -"二進位檔案會以固定大小的區塊進行緩衝；緩衝區的大小為 ``max(min(blocksize, 8 " -"MiB), DEFAULT_BUFFER_SIZE)``，當裝置區塊大小可用時。在大多數系統上，緩衝區的" -"長度通常為 128 KB。" - -#: ../../library/functions.rst:1410 -msgid "" -"\"Interactive\" text files (files for which :meth:`~io.IOBase.isatty` " -"returns ``True``) use line buffering. Other text files use the policy " -"described above for binary files." -msgstr "" -"「互動式」文字檔（:meth:`~io.IOBase.isatty` 回傳 ``True`` 的檔案）會使用列緩" -"衝。其他文字檔則使用上述的二進制檔案緩衝策略。" - -#: ../../library/functions.rst:1414 -msgid "" -"*encoding* is the name of the encoding used to decode or encode the file. " -"This should only be used in text mode. The default encoding is platform " -"dependent (whatever :func:`locale.getencoding` returns), but any :term:`text " -"encoding` supported by Python can be used. See the :mod:`codecs` module for " -"the list of supported encodings." -msgstr "" -"*encoding* 是用於解碼或編碼檔案的編碼系統之名稱。它只應該在文字模式下使用。預" -"設的編碼系統會取決於平台（根據 :func:`locale.getencoding` 回傳的內容），但 " -"Python 支援的任何 :term:`text encoding`\\ （文字編碼）都是可以使用的。關於支" -"援的編碼系統清單，請參閱 :mod:`codecs` module。" - -#: ../../library/functions.rst:1420 -msgid "" -"*errors* is an optional string that specifies how encoding and decoding " -"errors are to be handled—this cannot be used in binary mode. A variety of " -"standard error handlers are available (listed under :ref:`error-handlers`), " -"though any error handling name that has been registered with :func:`codecs." -"register_error` is also valid. The standard names include:" -msgstr "" -"*errors* 是一個選擇性的字串，用於指定要如何處理編碼和解碼的錯誤——它不能在二進" -"制模式下使用。有許多不同的標準錯誤處理程式（error handler，在\\ :ref:`error-" -"handlers`\\ 有列出清單），不過任何已註冊到 :func:`codecs.register_error` 的錯" -"誤處理程式名稱也都是有效的。標準的名稱包括：" - -#: ../../library/functions.rst:1428 -msgid "" -"``'strict'`` to raise a :exc:`ValueError` exception if there is an encoding " -"error. The default value of ``None`` has the same effect." -msgstr "" -"``'strict'`` 如果發生編碼錯誤，則引發 :exc:`ValueError` 例外。預設值 " -"``None`` 也有相同的效果。" - -#: ../../library/functions.rst:1432 -msgid "" -"``'ignore'`` ignores errors. Note that ignoring encoding errors can lead to " -"data loss." -msgstr "``'ignore'`` 忽略錯誤。請注意，忽略編碼錯誤可能導致資料遺失。" - -#: ../../library/functions.rst:1435 -msgid "" -"``'replace'`` causes a replacement marker (such as ``'?'``) to be inserted " -"where there is malformed data." -msgstr "" -"``'replace'`` 會在格式不正確的資料位置插入一個替換標誌（像是 ``'?'``）。" - -#: ../../library/functions.rst:1438 -msgid "" -"``'surrogateescape'`` will represent any incorrect bytes as low surrogate " -"code units ranging from U+DC80 to U+DCFF. These surrogate code units will " -"then be turned back into the same bytes when the ``surrogateescape`` error " -"handler is used when writing data. This is useful for processing files in " -"an unknown encoding." -msgstr "" -"``'surrogateescape'`` 會將任何不正確的位元組表示為低位代理碼元 (low " -"surrogate code unit)，範圍從 U+DC80 到 U+DCFF。在寫入資料時，這些代理碼元將會" -"被還原回 ``surrogateescape`` 錯誤處理程式當時所處理的那些相同位元組。這對於處" -"理未知編碼方式的檔案會很好用。" - -#: ../../library/functions.rst:1445 -msgid "" -"``'xmlcharrefreplace'`` is only supported when writing to a file. Characters " -"not supported by the encoding are replaced with the appropriate XML " -"character reference :samp:`&#{nnn};`." -msgstr "" -"``'xmlcharrefreplace'`` 僅在寫入檔案時可支援。編碼系統不支援的字元會被替換為" -"適當的 XML 字元參考 (character reference) ``&#nnn;``。" - -#: ../../library/functions.rst:1449 -msgid "" -"``'backslashreplace'`` replaces malformed data by Python's backslashed " -"escape sequences." -msgstr "" -"``'backslashreplace'`` 會用 Python 的反斜線跳脫序列 (backslashed escape " -"sequence) 替換格式不正確的資料。" - -#: ../../library/functions.rst:1452 -msgid "" -"``'namereplace'`` (also only supported when writing) replaces unsupported " -"characters with ``\\N{...}`` escape sequences." -msgstr "" -"``'namereplace'``\\ （也僅在寫入時支援）會將不支援的字元替換為 ``\\N{...}`` " -"跳脫序列。" - -#: ../../library/functions.rst:1460 -msgid "" -"*newline* determines how to parse newline characters from the stream. It can " -"be ``None``, ``''``, ``'\\n'``, ``'\\r'``, and ``'\\r\\n'``. It works as " -"follows:" -msgstr "" -"*newline* 會決定如何剖析資料串流 (stream) 中的換行字元。它可以是 ``None``、" -"``''``、``'\\n'``、``'\\r'`` 或 ``'\\r\\n'``。它的運作規則如下：" - -#: ../../library/functions.rst:1464 -msgid "" -"When reading input from the stream, if *newline* is ``None``, universal " -"newlines mode is enabled. Lines in the input can end in ``'\\n'``, " -"``'\\r'``, or ``'\\r\\n'``, and these are translated into ``'\\n'`` before " -"being returned to the caller. If it is ``''``, universal newlines mode is " -"enabled, but line endings are returned to the caller untranslated. If it " -"has any of the other legal values, input lines are only terminated by the " -"given string, and the line ending is returned to the caller untranslated." -msgstr "" -"從資料串流讀取輸入時，如果 *newline* 是 ``None``，則會啟用通用換行模式。輸入" -"資料中的行結尾可以是 ``'\\n'``、``'\\r'`` 或 ``'\\r\\n'``，這些符號會被轉換" -"為 ``'\\n'`` 之後再回傳給呼叫方。如果是 ``''``，也會啟用通用換行模式，但在回" -"傳給呼叫方時，行尾符號不會被轉換。如果它是任何其他有效的值，則輸入資料的行只" -"會由給定的字串做結尾，且在回傳給呼叫方時，行尾符號不會被轉換。" - -#: ../../library/functions.rst:1472 -msgid "" -"When writing output to the stream, if *newline* is ``None``, any ``'\\n'`` " -"characters written are translated to the system default line separator, :" -"data:`os.linesep`. If *newline* is ``''`` or ``'\\n'``, no translation " -"takes place. If *newline* is any of the other legal values, any ``'\\n'`` " -"characters written are translated to the given string." -msgstr "" -"將輸出寫入資料串流時，如果 *newline* 是 ``None``，則被寫入的任何 ``'\\n'`` 字" -"元都會轉換為系統預設的行分隔符號 :data:`os.linesep`。如果 *newline* 是 " -"``''`` 或 ``'\\n'``，則不做任何轉換。如果 *newline* 是任何其他有效的值，則寫" -"入的任何 ``'\\n'`` 字元都將轉換為給定的字串。" - -#: ../../library/functions.rst:1478 -msgid "" -"If *closefd* is ``False`` and a file descriptor rather than a filename was " -"given, the underlying file descriptor will be kept open when the file is " -"closed. If a filename is given *closefd* must be ``True`` (the default); " -"otherwise, an error will be raised." -msgstr "" -"如果 *closefd* 是 ``False``，且給定的 *file* 引數是一個檔案描述器而不是檔名，" -"則當檔案關閉時，底層的檔案描述器會保持開啟狀態。如果有給定一個檔名，則 " -"*closefd* 必須是 ``True``\\ （預設值）；否則將引發錯誤。" - -#: ../../library/functions.rst:1483 -msgid "" -"A custom opener can be used by passing a callable as *opener*. The " -"underlying file descriptor for the file object is then obtained by calling " -"*opener* with (*file*, *flags*). *opener* must return an open file " -"descriptor (passing :mod:`os.open` as *opener* results in functionality " -"similar to passing ``None``)." -msgstr "" -"透過以 *opener* 傳遞一個可呼叫物件，就可以自訂開啟函式。然後透過以引數 " -"(*file*, *flags*) 呼叫 *opener*，就能取得檔案物件的底層檔案描述器。*opener* " -"必須回傳一個開啟的檔案描述器（將 :mod:`os.open` 作為 *opener* 傳入，在功能上" -"的結果會相當於傳入 ``None``）。" - -#: ../../library/functions.rst:1489 -msgid "The newly created file is :ref:`non-inheritable `." -msgstr "新建立的檔案是\\ :ref:`不可繼承的 `。" - -#: ../../library/functions.rst:1491 -msgid "" -"The following example uses the :ref:`dir_fd ` parameter of the :func:" -"`os.open` function to open a file relative to a given directory::" -msgstr "" -"下面的範例使用 :func:`os.open` 函式回傳值當作 :ref:`dir_fd ` 的參數，" -"從給定的目錄中用相對路徑開啟檔案： ::" - -#: ../../library/functions.rst:1494 -msgid "" -">>> import os\n" -">>> dir_fd = os.open('somedir', os.O_RDONLY)\n" -">>> def opener(path, flags):\n" -"... return os.open(path, flags, dir_fd=dir_fd)\n" -"...\n" -">>> with open('spamspam.txt', 'w', opener=opener) as f:\n" -"... print('This will be written to somedir/spamspam.txt', file=f)\n" -"...\n" -">>> os.close(dir_fd) # don't leak a file descriptor" -msgstr "" -">>> import os\n" -">>> dir_fd = os.open('somedir', os.O_RDONLY)\n" -">>> def opener(path, flags):\n" -"... return os.open(path, flags, dir_fd=dir_fd)\n" -"...\n" -">>> with open('spamspam.txt', 'w', opener=opener) as f:\n" -"... print('This will be written to somedir/spamspam.txt', file=f)\n" -"...\n" -">>> os.close(dir_fd) # don't leak a file descriptor" - -#: ../../library/functions.rst:1504 -msgid "" -"The type of :term:`file object` returned by the :func:`open` function " -"depends on the mode. When :func:`open` is used to open a file in a text " -"mode (``'w'``, ``'r'``, ``'wt'``, ``'rt'``, etc.), it returns a subclass of :" -"class:`io.TextIOBase` (specifically :class:`io.TextIOWrapper`). When used " -"to open a file in a binary mode with buffering, the returned class is a " -"subclass of :class:`io.BufferedIOBase`. The exact class varies: in read " -"binary mode, it returns an :class:`io.BufferedReader`; in write binary and " -"append binary modes, it returns an :class:`io.BufferedWriter`, and in read/" -"write mode, it returns an :class:`io.BufferedRandom`. When buffering is " -"disabled, the raw stream, a subclass of :class:`io.RawIOBase`, :class:`io." -"FileIO`, is returned." -msgstr "" -":func:`open` 函式回傳的 :term:`file object` 型別取決於模式。當 :func:`open` " -"是在文字模式中開啟檔案時（``'w'``、``'r'``、``'wt'``、``'rt'`` 等），它會回" -"傳 :class:`io.TextIOBase` 的一個 subclass（具體來說，就是 :class:`io." -"TextIOWrapper`）。使用有緩衝的二進制模式開啟檔案時，回傳的 class 則會是 :" -"class:`io.BufferedIOBase` 的 subclass。確切的 class 各不相同：在讀取的二進制" -"模式，它會回傳 :class:`io.BufferedReader`；在寫入和附加的二進制模式，它會回" -"傳 :class:`io.BufferedWriter`，而在讀／寫模式，它會回傳 :class:`io." -"BufferedRandom`。當緩衝被停用時，會回傳原始資料串流 :class:`io.FileIO`，它" -"是 :class:`io.RawIOBase` 的一個 subclass。" - -#: ../../library/functions.rst:1525 -msgid "" -"See also the file handling modules, such as :mod:`fileinput`, :mod:`io` " -"(where :func:`open` is declared), :mod:`os`, :mod:`os.path`, :mod:" -"`tempfile`, and :mod:`shutil`." -msgstr "" -"另請參閱檔案操作模組，例如 :mod:`fileinput`、:mod:`io`\\ （定義了 :func:" -"`open` 的 module ）、:mod:`os`、:mod:`os.path`、:mod:`tempfile` 以及 :mod:" -"`shutil`。" - -#: ../../library/functions.rst:1529 -msgid "" -"Raises an :ref:`auditing event ` ``open`` with arguments ``path``, " -"``mode``, ``flags``." -msgstr "" -"引發一個附帶引數 ``path``、``mode``、``flags`` 的\\ :ref:`稽核事件 " -"` ``open``。" - -#: ../../library/functions.rst:1531 -msgid "" -"The ``mode`` and ``flags`` arguments may have been modified or inferred from " -"the original call." -msgstr "``mode`` 和 ``flags`` 引數可能會被原始的呼叫所修改或推論 (infer)。" - -#: ../../library/functions.rst:1536 -msgid "The *opener* parameter was added." -msgstr "新增 *opener* 參數。" - -#: ../../library/functions.rst:1537 -msgid "The ``'x'`` mode was added." -msgstr "新增 ``'x'`` 模式。" - -#: ../../library/functions.rst:1538 -msgid ":exc:`IOError` used to be raised, it is now an alias of :exc:`OSError`." -msgstr "過去引發的 :exc:`IOError`，現在是 :exc:`OSError` 的別名。" - -#: ../../library/functions.rst:1539 -msgid "" -":exc:`FileExistsError` is now raised if the file opened in exclusive " -"creation mode (``'x'``) already exists." -msgstr "" -"如果檔案已存在但使用了唯一性建立模式 (``'x'``)，現在會引發 :exc:" -"`FileExistsError`。" - -#: ../../library/functions.rst:1544 -msgid "The file is now non-inheritable." -msgstr "檔案在此版本開始是不可繼承的。" - -#: ../../library/functions.rst:1548 -msgid "" -"If the system call is interrupted and the signal handler does not raise an " -"exception, the function now retries the system call instead of raising an :" -"exc:`InterruptedError` exception (see :pep:`475` for the rationale)." -msgstr "" -"如果系統呼叫被中斷，但訊號處理程式沒有引發例外，此函式現在會重試系統呼叫，而" -"不是引發 :exc:`InterruptedError` 例外（原因詳見 :pep:`475`）。" - -#: ../../library/functions.rst:1551 -msgid "The ``'namereplace'`` error handler was added." -msgstr "增加了 ``'namereplace'`` 錯誤處理程式。" - -#: ../../library/functions.rst:1555 -msgid "Support added to accept objects implementing :class:`os.PathLike`." -msgstr "增加對於實作 :class:`os.PathLike` 物件的支援。" - -#: ../../library/functions.rst:1556 -msgid "" -"On Windows, opening a console buffer may return a subclass of :class:`io." -"RawIOBase` other than :class:`io.FileIO`." -msgstr "" -"在 Windows 上，開啟一個控制臺緩衝區可能會回傳 :class:`io.RawIOBase` 的 " -"subclass，而不是 :class:`io.FileIO`。" - -#: ../../library/functions.rst:1559 -msgid "The ``'U'`` mode has been removed." -msgstr "``'U'`` 模式被移除。" - -#: ../../library/functions.rst:1564 -msgid "Return the ordinal value of a character." -msgstr "" - -#: ../../library/functions.rst:1566 -msgid "" -"If the argument is a one-character string, return the Unicode code point of " -"that character. For example, ``ord('a')`` returns the integer ``97`` and " -"``ord('€')`` (Euro sign) returns ``8364``. This is the inverse of :func:" -"`chr`." -msgstr "" -"如果引數是單字元字串，則回傳該字元的 Unicode 編碼位置。例如 ``ord('a')`` 回傳" -"整數 ``97``、``ord('€')``\\ （歐元符號）回傳 ``8364``。這是 :func:`chr` 的逆" -"函式。" - -#: ../../library/functions.rst:1571 -msgid "" -"If the argument is a :class:`bytes` or :class:`bytearray` object of length " -"1, return its single byte value. For example, ``ord(b'a')`` returns the " -"integer ``97``." -msgstr "" - -#: ../../library/functions.rst:1578 -msgid "" -"Return *base* to the power *exp*; if *mod* is present, return *base* to the " -"power *exp*, modulo *mod* (computed more efficiently than ``pow(base, exp) % " -"mod``). The two-argument form ``pow(base, exp)`` is equivalent to using the " -"power operator: ``base**exp``." -msgstr "" -"回傳 *base* 的 *exp* 次方；如果 *mod* 存在，則回傳 *base* 的 *exp* 次方對 " -"*mod* 取餘數（比直接呼叫 ``pow(base, exp) % mod`` 計算更高效）。兩個引數形式" -"的 ``pow(exp, exp)`` 等價於次方運算子：``base**exp``。" - -#: ../../library/functions.rst:1583 -msgid "" -"When arguments are builtin numeric types with mixed operand types, the " -"coercion rules for binary arithmetic operators apply. For :class:`int` " -"operands, the result has the same type as the operands (after coercion) " -"unless the second argument is negative; in that case, all arguments are " -"converted to float and a float result is delivered. For example, ``pow(10, " -"2)`` returns ``100``, but ``pow(10, -2)`` returns ``0.01``. For a negative " -"base of type :class:`int` or :class:`float` and a non-integral exponent, a " -"complex result is delivered. For example, ``pow(-9, 0.5)`` returns a value " -"close to ``3j``. Whereas, for a negative base of type :class:`int` or :class:" -"`float` with an integral exponent, a float result is delivered. For example, " -"``pow(-9, 2.0)`` returns ``81.0``." -msgstr "" -"當引數為內建數值型別且運算元型別為混合型別時，會套用二元算術運算子的強制轉型 " -"(coercion) 規則。對於 :class:`int` 運算元，運算結果會（在強制轉型後）與運算元" -"的型別相同，除非第二個引數是負數；在這種情況下，所有的引數都會被轉換為浮點數" -"並得到浮點數的結果。例如，``pow(10, 2)`` 會回傳 ``100``，但 ``pow(10, -2)`` " -"會回傳 ``0.01``。如果底數 (base) 是型別為 :class:`int` 或 :class:`float` 的負" -"數且指數 (exponent) 為非整數，則會傳回複數結果。例如 ``pow(-9, 0.5)`` 會回傳" -"一個接近 ``3j`` 的值。然而，如果底數 (base) 是型別為 :class:`int` 或 :class:" -"`float` 的負數且指數為整數，則會傳回浮點數結果。例如 ``pow(-9, 2.0)`` 會回傳 " -"``81.0``。" - -#: ../../library/functions.rst:1595 -msgid "" -"For :class:`int` operands *base* and *exp*, if *mod* is present, *mod* must " -"also be of integer type and *mod* must be nonzero. If *mod* is present and " -"*exp* is negative, *base* must be relatively prime to *mod*. In that case, " -"``pow(inv_base, -exp, mod)`` is returned, where *inv_base* is an inverse to " -"*base* modulo *mod*." -msgstr "" -"對於 :class:`int` 運算元 *base* 和 *exp*，如果有給定 *mod*，則 *mod* 也必須是" -"整數型別，且 *mod* 必須不為零。如果有給定 *mod* 且 *exp* 為負，則 *base* 必須" -"與 *mod* 互質。在這種情況下，會回傳 ``pow(inv_base, -exp, mod)``，其中 " -"*inv_base* 是 *base* 對 *mod* 的模倒數 (inverse modulo)。" - -#: ../../library/functions.rst:1601 -msgid "Here's an example of computing an inverse for ``38`` modulo ``97``::" -msgstr "以下是一個計算 ``38`` 對 ``97`` 取模倒數的範例： ::" - -#: ../../library/functions.rst:1603 -msgid "" -">>> pow(38, -1, mod=97)\n" -"23\n" -">>> 23 * 38 % 97 == 1\n" -"True" -msgstr "" -">>> pow(38, -1, mod=97)\n" -"23\n" -">>> 23 * 38 % 97 == 1\n" -"True" - -#: ../../library/functions.rst:1608 -msgid "" -"For :class:`int` operands, the three-argument form of ``pow`` now allows the " -"second argument to be negative, permitting computation of modular inverses." -msgstr "" -"對於 :class:`int` 運算元，現在 ``pow`` 的三引數形式允許第二個引數為負數，也容" -"許模倒數的計算。" - -#: ../../library/functions.rst:1613 -msgid "" -"Allow keyword arguments. Formerly, only positional arguments were supported." -msgstr "允許關鍵字引數。在此之前只支援位置引數。" - -#: ../../library/functions.rst:1620 -msgid "" -"Print *objects* to the text stream *file*, separated by *sep* and followed " -"by *end*. *sep*, *end*, *file*, and *flush*, if present, must be given as " -"keyword arguments." -msgstr "" -"將 *objects* 列印到文字資料串流 *file*，用 *sep* 分隔並以 *end* 結尾。如果有" -"給定 *sep*、*end*、*file* 和 *flush*，那麼它們必須是關鍵字引數的形式。" - -#: ../../library/functions.rst:1624 -msgid "" -"All non-keyword arguments are converted to strings like :func:`str` does and " -"written to the stream, separated by *sep* and followed by *end*. Both *sep* " -"and *end* must be strings; they can also be ``None``, which means to use the " -"default values. If no *objects* are given, :func:`print` will just write " -"*end*." -msgstr "" -"所有的非關鍵字引數都會像是 :func:`str` 操作一樣地被轉換為字串，並寫入資料串" -"流，彼此以 *sep* 分隔，並以 *end* 結尾。*sep* 和 *end* 都必須是字串；它們也可" -"以是 ``None``，這表示使用預設值。如果沒有給定 *objects*，:func:`print` 就只會" -"寫入 *end*。" - -#: ../../library/functions.rst:1630 -msgid "" -"The *file* argument must be an object with a ``write(string)`` method; if it " -"is not present or ``None``, :data:`sys.stdout` will be used. Since printed " -"arguments are converted to text strings, :func:`print` cannot be used with " -"binary mode file objects. For these, use ``file.write(...)`` instead." -msgstr "" -"*file* 引數必須是一個有 ``write(string)`` method 的物件；如果沒有給定或被設" -"為 ``None``，則將使用 :data:`sys.stdout`。因為要列印的引數會被轉換為文字字" -"串，所以 :func:`print` 不能用於二進位模式的檔案物件。對於此類物件，請改用 " -"``file.write(...)``。" - -#: ../../library/functions.rst:1635 -msgid "" -"Output buffering is usually determined by *file*. However, if *flush* is " -"true, the stream is forcibly flushed." -msgstr "" -"輸出緩衝通常會由 *file* 決定。但是如果 *flush* 為 true，則資料串流會被強制清" -"除。" - -#: ../../library/functions.rst:1639 -msgid "Added the *flush* keyword argument." -msgstr "增加了 *flush* 關鍵字引數。" - -#: ../../library/functions.rst:1645 -msgid "Return a property attribute." -msgstr "回傳 property 屬性。" - -#: ../../library/functions.rst:1647 -msgid "" -"*fget* is a function for getting an attribute value. *fset* is a function " -"for setting an attribute value. *fdel* is a function for deleting an " -"attribute value. And *doc* creates a docstring for the attribute." -msgstr "" -"*fget* 是一個用於取得屬性值的函式，*fset* 是一個用於設定屬性值的函式，*fdel* " -"是一個用於刪除屬性值的函式，而 *doc* 會為該屬性建立一個說明字串。" - -#: ../../library/functions.rst:1651 -msgid "A typical use is to define a managed attribute ``x``::" -msgstr "一個典型的用途是定義一個受管理的屬性 ``x``： ::" - -#: ../../library/functions.rst:1653 -msgid "" -"class C:\n" -" def __init__(self):\n" -" self._x = None\n" -"\n" -" def getx(self):\n" -" return self._x\n" -"\n" -" def setx(self, value):\n" -" self._x = value\n" -"\n" -" def delx(self):\n" -" del self._x\n" -"\n" -" x = property(getx, setx, delx, \"I'm the 'x' property.\")" -msgstr "" -"class C:\n" -" def __init__(self):\n" -" self._x = None\n" -"\n" -" def getx(self):\n" -" return self._x\n" -"\n" -" def setx(self, value):\n" -" self._x = value\n" -"\n" -" def delx(self):\n" -" del self._x\n" -"\n" -" x = property(getx, setx, delx, \"I'm the 'x' property.\")" - -#: ../../library/functions.rst:1668 -msgid "" -"If *c* is an instance of *C*, ``c.x`` will invoke the getter, ``c.x = " -"value`` will invoke the setter, and ``del c.x`` the deleter." -msgstr "" -"如果 *c* 是 *C* 的一個實例，則 ``c.x`` 將會叫用取得器 (getter)，``c.x = " -"value`` 會呼叫設定器 (setter)，而 ``del c.x`` 會叫用刪除器 (deleter)。" - -#: ../../library/functions.rst:1671 -msgid "" -"If given, *doc* will be the docstring of the property attribute. Otherwise, " -"the property will copy *fget*'s docstring (if it exists). This makes it " -"possible to create read-only properties easily using :func:`property` as a :" -"term:`decorator`::" -msgstr "" -"如果有給定 *doc*，它將會是 property 屬性的說明字串。否則，property 會複製 " -"*fget* 的說明字串（如果它存在的話）。這樣一來，就能夠輕鬆地使用 :func:" -"`property` 作為\\ :term:`裝飾器 `\\ 來建立唯讀屬性： ::" - -#: ../../library/functions.rst:1675 -msgid "" -"class Parrot:\n" -" def __init__(self):\n" -" self._voltage = 100000\n" -"\n" -" @property\n" -" def voltage(self):\n" -" \"\"\"Get the current voltage.\"\"\"\n" -" return self._voltage" -msgstr "" - -#: ../../library/functions.rst:1684 -msgid "" -"The ``@property`` decorator turns the :meth:`!voltage` method into a " -"\"getter\" for a read-only attribute with the same name, and it sets the " -"docstring for *voltage* to \"Get the current voltage.\"" -msgstr "" - -#: ../../library/functions.rst:1692 -msgid "" -"A property object has ``getter``, ``setter``, and ``deleter`` methods usable " -"as decorators that create a copy of the property with the corresponding " -"accessor function set to the decorated function. This is best explained " -"with an example:" -msgstr "" - -#: ../../library/functions.rst:1697 -msgid "" -"class C:\n" -" def __init__(self):\n" -" self._x = None\n" -"\n" -" @property\n" -" def x(self):\n" -" \"\"\"I'm the 'x' property.\"\"\"\n" -" return self._x\n" -"\n" -" @x.setter\n" -" def x(self, value):\n" -" self._x = value\n" -"\n" -" @x.deleter\n" -" def x(self):\n" -" del self._x" -msgstr "" -"class C:\n" -" def __init__(self):\n" -" self._x = None\n" -"\n" -" @property\n" -" def x(self):\n" -" \"\"\"I'm the 'x' property.\"\"\"\n" -" return self._x\n" -"\n" -" @x.setter\n" -" def x(self, value):\n" -" self._x = value\n" -"\n" -" @x.deleter\n" -" def x(self):\n" -" del self._x" - -#: ../../library/functions.rst:1716 -msgid "" -"This code is exactly equivalent to the first example. Be sure to give the " -"additional functions the same name as the original property (``x`` in this " -"case.)" -msgstr "" - -#: ../../library/functions.rst:1720 -msgid "" -"The returned property object also has the attributes ``fget``, ``fset``, and " -"``fdel`` corresponding to the constructor arguments." -msgstr "" - -#: ../../library/functions.rst:1723 -msgid "The docstrings of property objects are now writeable." -msgstr "" - -#: ../../library/functions.rst:1728 -msgid "" -"Attribute holding the name of the property. The name of the property can be " -"changed at runtime." -msgstr "" - -#: ../../library/functions.rst:1739 -msgid "" -"Rather than being a function, :class:`range` is actually an immutable " -"sequence type, as documented in :ref:`typesseq-range` and :ref:`typesseq`." -msgstr "" - -#: ../../library/functions.rst:1745 -msgid "" -"Return a string containing a printable representation of an object. For " -"many types, this function makes an attempt to return a string that would " -"yield an object with the same value when passed to :func:`eval`; otherwise, " -"the representation is a string enclosed in angle brackets that contains the " -"name of the type of the object together with additional information often " -"including the name and address of the object. A class can control what this " -"function returns for its instances by defining a :meth:`~object.__repr__` " -"method. If :func:`sys.displayhook` is not accessible, this function will " -"raise :exc:`RuntimeError`." -msgstr "" - -#: ../../library/functions.rst:1756 -msgid "This class has a custom representation that can be evaluated::" -msgstr "" - -#: ../../library/functions.rst:1758 -msgid "" -"class Person:\n" -" def __init__(self, name, age):\n" -" self.name = name\n" -" self.age = age\n" -"\n" -" def __repr__(self):\n" -" return f\"Person('{self.name}', {self.age})\"" -msgstr "" -"class Person:\n" -" def __init__(self, name, age):\n" -" self.name = name\n" -" self.age = age\n" -"\n" -" def __repr__(self):\n" -" return f\"Person('{self.name}', {self.age})\"" - -#: ../../library/functions.rst:1769 -msgid "" -"Return a reverse :term:`iterator`. The argument must be an object which has " -"a :meth:`~object.__reversed__` method or supports the sequence protocol " -"(the :meth:`~object.__len__` method and the :meth:`~object.__getitem__` " -"method with integer arguments starting at ``0``)." -msgstr "" - -#: ../../library/functions.rst:1777 -msgid "" -"Return *number* rounded to *ndigits* precision after the decimal point. If " -"*ndigits* is omitted or is ``None``, it returns the nearest integer to its " -"input." -msgstr "" - -#: ../../library/functions.rst:1781 -msgid "" -"For the built-in types supporting :func:`round`, values are rounded to the " -"closest multiple of 10 to the power minus *ndigits*; if two multiples are " -"equally close, rounding is done toward the even choice (so, for example, " -"both ``round(0.5)`` and ``round(-0.5)`` are ``0``, and ``round(1.5)`` is " -"``2``). Any integer value is valid for *ndigits* (positive, zero, or " -"negative). The return value is an integer if *ndigits* is omitted or " -"``None``. Otherwise, the return value has the same type as *number*." -msgstr "" - -#: ../../library/functions.rst:1790 -msgid "" -"For a general Python object ``number``, ``round`` delegates to ``number." -"__round__``." -msgstr "" - -#: ../../library/functions.rst:1795 -msgid "" -"The behavior of :func:`round` for floats can be surprising: for example, " -"``round(2.675, 2)`` gives ``2.67`` instead of the expected ``2.68``. This is " -"not a bug: it's a result of the fact that most decimal fractions can't be " -"represented exactly as a float. See :ref:`tut-fp-issues` for more " -"information." -msgstr "" - -#: ../../library/functions.rst:1806 -msgid "" -"Return a new :class:`set` object, optionally with elements taken from " -"*iterable*. ``set`` is a built-in class. See :class:`set` and :ref:`types-" -"set` for documentation about this class." -msgstr "" - -#: ../../library/functions.rst:1810 -msgid "" -"For other containers see the built-in :class:`frozenset`, :class:`list`, :" -"class:`tuple`, and :class:`dict` classes, as well as the :mod:`collections` " -"module." -msgstr "" - -#: ../../library/functions.rst:1817 -msgid "" -"This is the counterpart of :func:`getattr`. The arguments are an object, a " -"string, and an arbitrary value. The string may name an existing attribute " -"or a new attribute. The function assigns the value to the attribute, " -"provided the object allows it. For example, ``setattr(x, 'foobar', 123)`` " -"is equivalent to ``x.foobar = 123``." -msgstr "" - -#: ../../library/functions.rst:1823 -msgid "" -"*name* need not be a Python identifier as defined in :ref:`identifiers` " -"unless the object chooses to enforce that, for example in a custom :meth:" -"`~object.__getattribute__` or via :attr:`~object.__slots__`. An attribute " -"whose name is not an identifier will not be accessible using the dot " -"notation, but is accessible through :func:`getattr` etc.." -msgstr "" - -#: ../../library/functions.rst:1831 -msgid "" -"Since :ref:`private name mangling ` happens at " -"compilation time, one must manually mangle a private attribute's (attributes " -"with two leading underscores) name in order to set it with :func:`setattr`." -msgstr "" - -#: ../../library/functions.rst:1840 -msgid "" -"Return a :term:`slice` object representing the set of indices specified by " -"``range(start, stop, step)``. The *start* and *step* arguments default to " -"``None``." -msgstr "" - -#: ../../library/functions.rst:1844 -msgid "" -"Slice objects have read-only data attributes :attr:`!start`, :attr:`!stop`, " -"and :attr:`!step` which merely return the argument values (or their " -"default). They have no other explicit functionality; however, they are used " -"by NumPy and other third-party packages." -msgstr "" - -#: ../../library/functions.rst:1853 -msgid "" -"Slice objects are also generated when extended indexing syntax is used. For " -"example: ``a[start:stop:step]`` or ``a[start:stop, i]``. See :func:" -"`itertools.islice` for an alternate version that returns an :term:`iterator`." -msgstr "" - -#: ../../library/functions.rst:1858 -msgid "" -"Slice objects are now :term:`hashable` (provided :attr:`~slice.start`, :attr:" -"`~slice.stop`, and :attr:`~slice.step` are hashable)." -msgstr "" - -#: ../../library/functions.rst:1864 -msgid "Return a new sorted list from the items in *iterable*." -msgstr "" - -#: ../../library/functions.rst:1866 -msgid "" -"Has two optional arguments which must be specified as keyword arguments." -msgstr "有兩個選擇性引數，只能使用關鍵字引數來指定。" - -#: ../../library/functions.rst:1868 -msgid "" -"*key* specifies a function of one argument that is used to extract a " -"comparison key from each element in *iterable* (for example, ``key=str." -"lower``). The default value is ``None`` (compare the elements directly)." -msgstr "" - -#: ../../library/functions.rst:1872 -msgid "" -"*reverse* is a boolean value. If set to ``True``, then the list elements " -"are sorted as if each comparison were reversed." -msgstr "" - -#: ../../library/functions.rst:1875 -msgid "" -"Use :func:`functools.cmp_to_key` to convert an old-style *cmp* function to a " -"*key* function." -msgstr "" - -#: ../../library/functions.rst:1878 -msgid "" -"The built-in :func:`sorted` function is guaranteed to be stable. A sort is " -"stable if it guarantees not to change the relative order of elements that " -"compare equal --- this is helpful for sorting in multiple passes (for " -"example, sort by department, then by salary grade)." -msgstr "" - -#: ../../library/functions.rst:1883 -msgid "" -"The sort algorithm uses only ``<`` comparisons between items. While " -"defining an :meth:`~object.__lt__` method will suffice for sorting, :PEP:`8` " -"recommends that all six :ref:`rich comparisons ` be " -"implemented. This will help avoid bugs when using the same data with other " -"ordering tools such as :func:`max` that rely on a different underlying " -"method. Implementing all six comparisons also helps avoid confusion for " -"mixed type comparisons which can call the reflected :meth:`~object.__gt__` " -"method." -msgstr "" - -#: ../../library/functions.rst:1892 -msgid "" -"For sorting examples and a brief sorting tutorial, see :ref:`sortinghowto`." -msgstr "" - -#: ../../library/functions.rst:1896 -msgid "Transform a method into a static method." -msgstr "" - -#: ../../library/functions.rst:1898 -msgid "" -"A static method does not receive an implicit first argument. To declare a " -"static method, use this idiom::" -msgstr "" - -#: ../../library/functions.rst:1901 -msgid "" -"class C:\n" -" @staticmethod\n" -" def f(arg1, arg2, argN): ..." -msgstr "" -"class C:\n" -" @staticmethod\n" -" def f(arg1, arg2, argN): ..." - -#: ../../library/functions.rst:1905 -msgid "" -"The ``@staticmethod`` form is a function :term:`decorator` -- see :ref:" -"`function` for details." -msgstr "" -"``@staticmethod`` 語法是一個函式 :term:`decorator` - 參見 :ref:`function` 中" -"的詳細介紹。" - -#: ../../library/functions.rst:1908 -msgid "" -"A static method can be called either on the class (such as ``C.f()``) or on " -"an instance (such as ``C().f()``). Moreover, the static method :term:" -"`descriptor` is also callable, so it can be used in the class definition " -"(such as ``f()``)." -msgstr "" - -#: ../../library/functions.rst:1913 -msgid "" -"Static methods in Python are similar to those found in Java or C++. Also, " -"see :func:`classmethod` for a variant that is useful for creating alternate " -"class constructors." -msgstr "" - -#: ../../library/functions.rst:1917 -msgid "" -"Like all decorators, it is also possible to call ``staticmethod`` as a " -"regular function and do something with its result. This is needed in some " -"cases where you need a reference to a function from a class body and you " -"want to avoid the automatic transformation to instance method. For these " -"cases, use this idiom::" -msgstr "" - -#: ../../library/functions.rst:1923 -msgid "" -"def regular_function():\n" -" ...\n" -"\n" -"class C:\n" -" method = staticmethod(regular_function)" -msgstr "" -"def regular_function():\n" -" ...\n" -"\n" -"class C:\n" -" method = staticmethod(regular_function)" - -#: ../../library/functions.rst:1929 -msgid "For more information on static methods, see :ref:`types`." -msgstr "關於 static method 的更多資訊，請參考 :ref:`types`。" - -#: ../../library/functions.rst:1931 -msgid "" -"Static methods now inherit the method attributes (:attr:`~function." -"__module__`, :attr:`~function.__name__`, :attr:`~function.__qualname__`, :" -"attr:`~function.__doc__` and :attr:`~function.__annotations__`), have a new " -"``__wrapped__`` attribute, and are now callable as regular functions." -msgstr "" -"Static method 現在繼承了 method 屬性（:attr:`~function.__module__`、:attr:" -"`~function.__name__`、:attr:`~function.__qualname__`、:attr:`~function." -"__doc__` 和 :attr:`~function.__annotations__`），並擁有一個新的 " -"``__wrapped__`` 屬性，且為如一般函式的可呼叫物件。" - -#: ../../library/functions.rst:1949 -msgid "" -"Return a :class:`str` version of *object*. See :func:`str` for details." -msgstr "" - -#: ../../library/functions.rst:1951 -msgid "" -"``str`` is the built-in string :term:`class`. For general information about " -"strings, see :ref:`textseq`." -msgstr "" - -#: ../../library/functions.rst:1957 -msgid "" -"Sums *start* and the items of an *iterable* from left to right and returns " -"the total. The *iterable*'s items are normally numbers, and the start value " -"is not allowed to be a string." -msgstr "" - -#: ../../library/functions.rst:1961 -msgid "" -"For some use cases, there are good alternatives to :func:`sum`. The " -"preferred, fast way to concatenate a sequence of strings is by calling ``''." -"join(sequence)``. To add floating-point values with extended precision, " -"see :func:`math.fsum`\\. To concatenate a series of iterables, consider " -"using :func:`itertools.chain`." -msgstr "" - -#: ../../library/functions.rst:1967 -msgid "The *start* parameter can be specified as a keyword argument." -msgstr "*start* 參數可被指定為關鍵字引數。" - -#: ../../library/functions.rst:1970 -msgid "" -"Summation of floats switched to an algorithm that gives higher accuracy and " -"better commutativity on most builds." -msgstr "" - -#: ../../library/functions.rst:1973 -msgid "" -"Added specialization for summation of complexes, using same algorithm as for " -"summation of floats." -msgstr "" - -#: ../../library/functions.rst:1981 -msgid "" -"Return a proxy object that delegates method calls to a parent or sibling " -"class of *type*. This is useful for accessing inherited methods that have " -"been overridden in a class." -msgstr "" - -#: ../../library/functions.rst:1985 -msgid "" -"The *object_or_type* determines the :term:`method resolution order` to be " -"searched. The search starts from the class right after the *type*." -msgstr "" - -#: ../../library/functions.rst:1989 -msgid "" -"For example, if :attr:`~type.__mro__` of *object_or_type* is ``D -> B -> C -" -"> A -> object`` and the value of *type* is ``B``, then :func:`super` " -"searches ``C -> A -> object``." -msgstr "" - -#: ../../library/functions.rst:1993 -msgid "" -"The :attr:`~type.__mro__` attribute of the class corresponding to " -"*object_or_type* lists the method resolution search order used by both :func:" -"`getattr` and :func:`super`. The attribute is dynamic and can change " -"whenever the inheritance hierarchy is updated." -msgstr "" - -#: ../../library/functions.rst:1998 -msgid "" -"If the second argument is omitted, the super object returned is unbound. If " -"the second argument is an object, ``isinstance(obj, type)`` must be true. " -"If the second argument is a type, ``issubclass(type2, type)`` must be true " -"(this is useful for classmethods)." -msgstr "" - -#: ../../library/functions.rst:2003 -msgid "" -"When called directly within an ordinary method of a class, both arguments " -"may be omitted (\"zero-argument :func:`!super`\"). In this case, *type* will " -"be the enclosing class, and *obj* will be the first argument of the " -"immediately enclosing function (typically ``self``). (This means that zero-" -"argument :func:`!super` will not work as expected within nested functions, " -"including generator expressions, which implicitly create nested functions.)" -msgstr "" - -#: ../../library/functions.rst:2010 -msgid "" -"There are two typical use cases for *super*. In a class hierarchy with " -"single inheritance, *super* can be used to refer to parent classes without " -"naming them explicitly, thus making the code more maintainable. This use " -"closely parallels the use of *super* in other programming languages." -msgstr "" - -#: ../../library/functions.rst:2015 -msgid "" -"The second use case is to support cooperative multiple inheritance in a " -"dynamic execution environment. This use case is unique to Python and is not " -"found in statically compiled languages or languages that only support single " -"inheritance. This makes it possible to implement \"diamond diagrams\" where " -"multiple base classes implement the same method. Good design dictates that " -"such implementations have the same calling signature in every case (because " -"the order of calls is determined at runtime, because that order adapts to " -"changes in the class hierarchy, and because that order can include sibling " -"classes that are unknown prior to runtime)." -msgstr "" - -#: ../../library/functions.rst:2025 -msgid "For both use cases, a typical superclass call looks like this::" -msgstr "" - -#: ../../library/functions.rst:2027 -msgid "" -"class C(B):\n" -" def method(self, arg):\n" -" super().method(arg) # This does the same thing as:\n" -" # super(C, self).method(arg)" -msgstr "" - -#: ../../library/functions.rst:2032 -msgid "" -"In addition to method lookups, :func:`super` also works for attribute " -"lookups. One possible use case for this is calling :term:`descriptors " -"` in a parent or sibling class." -msgstr "" - -#: ../../library/functions.rst:2036 -msgid "" -"Note that :func:`super` is implemented as part of the binding process for " -"explicit dotted attribute lookups such as ``super().__getitem__(name)``. It " -"does so by implementing its own :meth:`~object.__getattribute__` method for " -"searching classes in a predictable order that supports cooperative multiple " -"inheritance. Accordingly, :func:`super` is undefined for implicit lookups " -"using statements or operators such as ``super()[name]``." -msgstr "" - -#: ../../library/functions.rst:2044 -msgid "" -"Also note that, aside from the zero argument form, :func:`super` is not " -"limited to use inside methods. The two argument form specifies the " -"arguments exactly and makes the appropriate references. The zero argument " -"form only works inside a class definition, as the compiler fills in the " -"necessary details to correctly retrieve the class being defined, as well as " -"accessing the current instance for ordinary methods." -msgstr "" - -#: ../../library/functions.rst:2051 -msgid "" -"For practical suggestions on how to design cooperative classes using :func:" -"`super`, see `guide to using super() `_." -msgstr "" - -#: ../../library/functions.rst:2055 -msgid "" -":class:`super` objects are now :mod:`pickleable ` and :mod:" -"`copyable `." -msgstr "" - -#: ../../library/functions.rst:2064 -msgid "" -"Rather than being a function, :class:`tuple` is actually an immutable " -"sequence type, as documented in :ref:`typesseq-tuple` and :ref:`typesseq`." -msgstr "" - -#: ../../library/functions.rst:2073 -msgid "" -"With one argument, return the type of an *object*. The return value is a " -"type object and generally the same object as returned by :attr:`object." -"__class__`." -msgstr "" - -#: ../../library/functions.rst:2077 -msgid "" -"The :func:`isinstance` built-in function is recommended for testing the type " -"of an object, because it takes subclasses into account." -msgstr "" - -#: ../../library/functions.rst:2080 -msgid "" -"With three arguments, return a new type object. This is essentially a " -"dynamic form of the :keyword:`class` statement. The *name* string is the " -"class name and becomes the :attr:`~type.__name__` attribute. The *bases* " -"tuple contains the base classes and becomes the :attr:`~type.__bases__` " -"attribute; if empty, :class:`object`, the ultimate base of all classes, is " -"added. The *dict* dictionary contains attribute and method definitions for " -"the class body; it may be copied or wrapped before becoming the :attr:`~type." -"__dict__` attribute. The following two statements create identical :class:`!" -"type` objects:" -msgstr "" - -#: ../../library/functions.rst:2095 -msgid "See also:" -msgstr "另請參閱：" - -#: ../../library/functions.rst:2097 -msgid "" -":ref:`Documentation on attributes and methods on classes `." -msgstr "" - -#: ../../library/functions.rst:2098 -msgid ":ref:`bltin-type-objects`" -msgstr ":ref:`bltin-type-objects`" - -#: ../../library/functions.rst:2100 -msgid "" -"Keyword arguments provided to the three argument form are passed to the " -"appropriate metaclass machinery (usually :meth:`~object.__init_subclass__`) " -"in the same way that keywords in a class definition (besides *metaclass*) " -"would." -msgstr "" - -#: ../../library/functions.rst:2105 -msgid "See also :ref:`class-customization`." -msgstr "另請參閱 :ref:`class-customization`。" - -#: ../../library/functions.rst:2107 -msgid "" -"Subclasses of :class:`!type` which don't override ``type.__new__`` may no " -"longer use the one-argument form to get the type of an object." -msgstr "" - -#: ../../library/functions.rst:2114 -msgid "" -"Return the :attr:`~object.__dict__` attribute for a module, class, instance, " -"or any other object with a :attr:`!__dict__` attribute." -msgstr "" - -#: ../../library/functions.rst:2117 -msgid "" -"Objects such as modules and instances have an updateable :attr:`~object." -"__dict__` attribute; however, other objects may have write restrictions on " -"their :attr:`!__dict__` attributes (for example, classes use a :class:`types." -"MappingProxyType` to prevent direct dictionary updates)." -msgstr "" - -#: ../../library/functions.rst:2122 -msgid "Without an argument, :func:`vars` acts like :func:`locals`." -msgstr "" - -#: ../../library/functions.rst:2124 -msgid "" -"A :exc:`TypeError` exception is raised if an object is specified but it " -"doesn't have a :attr:`~object.__dict__` attribute (for example, if its class " -"defines the :attr:`~object.__slots__` attribute)." -msgstr "" - -#: ../../library/functions.rst:2130 -msgid "" -"The result of calling this function without an argument has been updated as " -"described for the :func:`locals` builtin." -msgstr "" - -#: ../../library/functions.rst:2136 -msgid "" -"Iterate over several iterables in parallel, producing tuples with an item " -"from each one." -msgstr "" - -#: ../../library/functions.rst:2139 -msgid "Example::" -msgstr "例如： ::" - -#: ../../library/functions.rst:2141 -msgid "" -">>> for item in zip([1, 2, 3], ['sugar', 'spice', 'everything nice']):\n" -"... print(item)\n" -"...\n" -"(1, 'sugar')\n" -"(2, 'spice')\n" -"(3, 'everything nice')" -msgstr "" -">>> for item in zip([1, 2, 3], ['sugar', 'spice', 'everything nice']):\n" -"... print(item)\n" -"...\n" -"(1, 'sugar')\n" -"(2, 'spice')\n" -"(3, 'everything nice')" - -#: ../../library/functions.rst:2148 -msgid "" -"More formally: :func:`zip` returns an iterator of tuples, where the *i*-th " -"tuple contains the *i*-th element from each of the argument iterables." -msgstr "" - -#: ../../library/functions.rst:2151 -msgid "" -"Another way to think of :func:`zip` is that it turns rows into columns, and " -"columns into rows. This is similar to `transposing a matrix `_." -msgstr "" - -#: ../../library/functions.rst:2155 -msgid "" -":func:`zip` is lazy: The elements won't be processed until the iterable is " -"iterated on, e.g. by a :keyword:`!for` loop or by wrapping in a :class:" -"`list`." -msgstr "" - -#: ../../library/functions.rst:2159 -msgid "" -"One thing to consider is that the iterables passed to :func:`zip` could have " -"different lengths; sometimes by design, and sometimes because of a bug in " -"the code that prepared these iterables. Python offers three different " -"approaches to dealing with this issue:" -msgstr "" - -#: ../../library/functions.rst:2164 -msgid "" -"By default, :func:`zip` stops when the shortest iterable is exhausted. It " -"will ignore the remaining items in the longer iterables, cutting off the " -"result to the length of the shortest iterable::" -msgstr "" - -#: ../../library/functions.rst:2168 -msgid "" -">>> list(zip(range(3), ['fee', 'fi', 'fo', 'fum']))\n" -"[(0, 'fee'), (1, 'fi'), (2, 'fo')]" -msgstr "" -">>> list(zip(range(3), ['fee', 'fi', 'fo', 'fum']))\n" -"[(0, 'fee'), (1, 'fi'), (2, 'fo')]" - -#: ../../library/functions.rst:2171 -msgid "" -":func:`zip` is often used in cases where the iterables are assumed to be of " -"equal length. In such cases, it's recommended to use the ``strict=True`` " -"option. Its output is the same as regular :func:`zip`::" -msgstr "" - -#: ../../library/functions.rst:2175 -msgid "" -">>> list(zip(('a', 'b', 'c'), (1, 2, 3), strict=True))\n" -"[('a', 1), ('b', 2), ('c', 3)]" -msgstr "" -">>> list(zip(('a', 'b', 'c'), (1, 2, 3), strict=True))\n" -"[('a', 1), ('b', 2), ('c', 3)]" - -#: ../../library/functions.rst:2178 -msgid "" -"Unlike the default behavior, it raises a :exc:`ValueError` if one iterable " -"is exhausted before the others:" -msgstr "" - -#: ../../library/functions.rst:2196 -msgid "" -"Without the ``strict=True`` argument, any bug that results in iterables of " -"different lengths will be silenced, possibly manifesting as a hard-to-find " -"bug in another part of the program." -msgstr "" - -#: ../../library/functions.rst:2200 -msgid "" -"Shorter iterables can be padded with a constant value to make all the " -"iterables have the same length. This is done by :func:`itertools." -"zip_longest`." -msgstr "" - -#: ../../library/functions.rst:2204 -msgid "" -"Edge cases: With a single iterable argument, :func:`zip` returns an iterator " -"of 1-tuples. With no arguments, it returns an empty iterator." -msgstr "" - -#: ../../library/functions.rst:2207 -msgid "Tips and tricks:" -msgstr "" - -#: ../../library/functions.rst:2209 -msgid "" -"The left-to-right evaluation order of the iterables is guaranteed. This " -"makes possible an idiom for clustering a data series into n-length groups " -"using ``zip(*[iter(s)]*n, strict=True)``. This repeats the *same* iterator " -"``n`` times so that each output tuple has the result of ``n`` calls to the " -"iterator. This has the effect of dividing the input into n-length chunks." -msgstr "" - -#: ../../library/functions.rst:2215 -msgid "" -":func:`zip` in conjunction with the ``*`` operator can be used to unzip a " -"list::" -msgstr "" - -#: ../../library/functions.rst:2218 -msgid "" -">>> x = [1, 2, 3]\n" -">>> y = [4, 5, 6]\n" -">>> list(zip(x, y))\n" -"[(1, 4), (2, 5), (3, 6)]\n" -">>> x2, y2 = zip(*zip(x, y))\n" -">>> x == list(x2) and y == list(y2)\n" -"True" -msgstr "" -">>> x = [1, 2, 3]\n" -">>> y = [4, 5, 6]\n" -">>> list(zip(x, y))\n" -"[(1, 4), (2, 5), (3, 6)]\n" -">>> x2, y2 = zip(*zip(x, y))\n" -">>> x == list(x2) and y == list(y2)\n" -"True" - -#: ../../library/functions.rst:2226 -msgid "Added the ``strict`` argument." -msgstr "增加了 ``strict`` 引數。" - -#: ../../library/functions.rst:2238 -msgid "" -"This is an advanced function that is not needed in everyday Python " -"programming, unlike :func:`importlib.import_module`." -msgstr "" - -#: ../../library/functions.rst:2241 -msgid "" -"This function is invoked by the :keyword:`import` statement. It can be " -"replaced (by importing the :mod:`builtins` module and assigning to " -"``builtins.__import__``) in order to change semantics of the :keyword:`!" -"import` statement, but doing so is **strongly** discouraged as it is usually " -"simpler to use import hooks (see :pep:`302`) to attain the same goals and " -"does not cause issues with code which assumes the default import " -"implementation is in use. Direct use of :func:`__import__` is also " -"discouraged in favor of :func:`importlib.import_module`." -msgstr "" - -#: ../../library/functions.rst:2250 -msgid "" -"The function imports the module *name*, potentially using the given " -"*globals* and *locals* to determine how to interpret the name in a package " -"context. The *fromlist* gives the names of objects or submodules that should " -"be imported from the module given by *name*. The standard implementation " -"does not use its *locals* argument at all and uses its *globals* only to " -"determine the package context of the :keyword:`import` statement." -msgstr "" - -#: ../../library/functions.rst:2257 -msgid "" -"*level* specifies whether to use absolute or relative imports. ``0`` (the " -"default) means only perform absolute imports. Positive values for *level* " -"indicate the number of parent directories to search relative to the " -"directory of the module calling :func:`__import__` (see :pep:`328` for the " -"details)." -msgstr "" - -#: ../../library/functions.rst:2263 -msgid "" -"When the *name* variable is of the form ``package.module``, normally, the " -"top-level package (the name up till the first dot) is returned, *not* the " -"module named by *name*. However, when a non-empty *fromlist* argument is " -"given, the module named by *name* is returned." -msgstr "" - -#: ../../library/functions.rst:2268 -msgid "" -"For example, the statement ``import spam`` results in bytecode resembling " -"the following code::" -msgstr "" - -#: ../../library/functions.rst:2271 -msgid "spam = __import__('spam', globals(), locals(), [], 0)" -msgstr "spam = __import__('spam', globals(), locals(), [], 0)" - -#: ../../library/functions.rst:2273 -msgid "The statement ``import spam.ham`` results in this call::" -msgstr "" - -#: ../../library/functions.rst:2275 -msgid "spam = __import__('spam.ham', globals(), locals(), [], 0)" -msgstr "spam = __import__('spam.ham', globals(), locals(), [], 0)" - -#: ../../library/functions.rst:2277 -msgid "" -"Note how :func:`__import__` returns the toplevel module here because this is " -"the object that is bound to a name by the :keyword:`import` statement." -msgstr "" - -#: ../../library/functions.rst:2280 -msgid "" -"On the other hand, the statement ``from spam.ham import eggs, sausage as " -"saus`` results in ::" -msgstr "" - -#: ../../library/functions.rst:2283 -msgid "" -"_temp = __import__('spam.ham', globals(), locals(), ['eggs', 'sausage'], 0)\n" -"eggs = _temp.eggs\n" -"saus = _temp.sausage" -msgstr "" -"_temp = __import__('spam.ham', globals(), locals(), ['eggs', 'sausage'], 0)\n" -"eggs = _temp.eggs\n" -"saus = _temp.sausage" - -#: ../../library/functions.rst:2287 -msgid "" -"Here, the ``spam.ham`` module is returned from :func:`__import__`. From " -"this object, the names to import are retrieved and assigned to their " -"respective names." -msgstr "" - -#: ../../library/functions.rst:2291 -msgid "" -"If you simply want to import a module (potentially within a package) by " -"name, use :func:`importlib.import_module`." -msgstr "" - -#: ../../library/functions.rst:2294 -msgid "" -"Negative values for *level* are no longer supported (which also changes the " -"default value to 0)." -msgstr "" - -#: ../../library/functions.rst:2298 -msgid "" -"When the command line options :option:`-E` or :option:`-I` are being used, " -"the environment variable :envvar:`PYTHONCASEOK` is now ignored." -msgstr "" - -#: ../../library/functions.rst:2303 -msgid "Footnotes" -msgstr "註解" - -#: ../../library/functions.rst:2304 -msgid "" -"Note that the parser only accepts the Unix-style end of line convention. If " -"you are reading the code from a file, make sure to use newline conversion " -"mode to convert Windows or Mac-style newlines." -msgstr "" -"剖析器只接受 Unix 風格的行結束符。如果你從檔案中讀取程式碼，請確保用換行符號" -"轉換模式轉換 Windows 或 Mac 風格的換行符號。" - -#: ../../library/functions.rst:154 -msgid "Boolean" -msgstr "Boolean（布林值）" - -#: ../../library/functions.rst:154 ../../library/functions.rst:2071 -msgid "type" -msgstr "type（型別）" - -#: ../../library/functions.rst:652 -msgid "built-in function" -msgstr "built-in function（內建函式）" - -#: ../../library/functions.rst:652 -msgid "exec" -msgstr "exec" - -#: ../../library/functions.rst:750 -msgid "NaN" -msgstr "NaN" - -#: ../../library/functions.rst:750 -msgid "Infinity" -msgstr "Infinity（無窮）" - -#: ../../library/functions.rst:820 -msgid "__format__" -msgstr "__format__" - -#: ../../library/functions.rst:820 ../../library/functions.rst:1939 -msgid "string" -msgstr "string（字串）" - -#: ../../library/functions.rst:820 -msgid "format() (built-in function)" -msgstr "format()（內建函式）" - -#: ../../library/functions.rst:1334 -msgid "file object" -msgstr "file object（檔案物件）" - -#: ../../library/functions.rst:1334 ../../library/functions.rst:1455 -msgid "open() built-in function" -msgstr "open() 內建函式" - -#: ../../library/functions.rst:1362 -msgid "file" -msgstr "file（檔案）" - -#: ../../library/functions.rst:1362 -msgid "modes" -msgstr "modes（模式）" - -#: ../../library/functions.rst:1455 -msgid "universal newlines" -msgstr "universal newlines" - -#: ../../library/functions.rst:1516 -msgid "line-buffered I/O" -msgstr "line-buffered I/O（行緩衝 I/O）" - -#: ../../library/functions.rst:1516 -msgid "unbuffered I/O" -msgstr "unbuffered I/O（非緩衝 I/O）" - -#: ../../library/functions.rst:1516 -msgid "buffer size, I/O" -msgstr "buffer size, I/O（緩衝區大小、I/O）" - -#: ../../library/functions.rst:1516 -msgid "I/O control" -msgstr "I/O control（I/O 控制）" - -#: ../../library/functions.rst:1516 -msgid "buffering" -msgstr "buffering（緩衝）" - -#: ../../library/functions.rst:1516 -msgid "text mode" -msgstr "text mode（文字模式）" - -#: ../../library/functions.rst:1516 ../../library/functions.rst:2232 -msgid "module" -msgstr "module（模組）" - -#: ../../library/functions.rst:1516 -msgid "sys" -msgstr "sys" - -#: ../../library/functions.rst:1939 -msgid "str() (built-in function)" -msgstr "str() （內建函式）" - -#: ../../library/functions.rst:2071 -msgid "object" -msgstr "object（物件）" - -#: ../../library/functions.rst:2232 -msgid "statement" -msgstr "statement（陳述式）" - -#: ../../library/functions.rst:2232 -msgid "import" -msgstr "import（引入）" - -#: ../../library/functions.rst:2232 -msgid "builtins" -msgstr "builtins（內建）" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# Translators: +# Adrian Liaw , 2018 +# nienzu , 2018 +# Matt Wang , 2021 +# Phil Lin , 2022 +# Steven Hsu , 2023 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-12-15 00:16+0000\n" +"PO-Revision-Date: 2024-05-06 17:06+0800\n" +"Last-Translator: KNChiu \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" +"X-Generator: Poedit 3.4.2\n" + +#: ../../library/functions.rst:5 ../../library/functions.rst:11 +msgid "Built-in Functions" +msgstr "內建函式" + +#: ../../library/functions.rst:7 +msgid "" +"The Python interpreter has a number of functions and types built into it " +"that are always available. They are listed here in alphabetical order." +msgstr "" +"Python 直譯器有內建多個可隨時使用的函式和型別。以下按照英文字母排序列出。" + +#: ../../library/functions.rst:13 +msgid "**A**" +msgstr "**A**" + +#: ../../library/functions.rst:14 +msgid ":func:`abs`" +msgstr ":func:`abs`" + +#: ../../library/functions.rst:15 +msgid ":func:`aiter`" +msgstr ":func:`aiter`" + +#: ../../library/functions.rst:16 +msgid ":func:`all`" +msgstr ":func:`all`" + +#: ../../library/functions.rst:17 +msgid ":func:`anext`" +msgstr ":func:`anext`" + +#: ../../library/functions.rst:18 +msgid ":func:`any`" +msgstr ":func:`any`" + +#: ../../library/functions.rst:19 +msgid ":func:`ascii`" +msgstr ":func:`ascii`" + +#: ../../library/functions.rst:21 +msgid "**B**" +msgstr "**B**" + +#: ../../library/functions.rst:22 +msgid ":func:`bin`" +msgstr ":func:`bin`" + +#: ../../library/functions.rst:23 +msgid ":func:`bool`" +msgstr ":func:`bool`" + +#: ../../library/functions.rst:24 +msgid ":func:`breakpoint`" +msgstr ":func:`breakpoint`" + +#: ../../library/functions.rst:25 +msgid "|func-bytearray|_" +msgstr "|func-bytearray|_" + +#: ../../library/functions.rst:26 +msgid "|func-bytes|_" +msgstr "|func-bytes|_" + +#: ../../library/functions.rst:28 +msgid "**C**" +msgstr "**C**" + +#: ../../library/functions.rst:29 +msgid ":func:`callable`" +msgstr ":func:`callable`" + +#: ../../library/functions.rst:30 +msgid ":func:`chr`" +msgstr ":func:`chr`" + +#: ../../library/functions.rst:31 +msgid ":func:`classmethod`" +msgstr ":func:`classmethod`" + +#: ../../library/functions.rst:32 +msgid ":func:`compile`" +msgstr ":func:`compile`" + +#: ../../library/functions.rst:33 +msgid ":func:`complex`" +msgstr ":func:`complex`" + +#: ../../library/functions.rst:35 +msgid "**D**" +msgstr "**D**" + +#: ../../library/functions.rst:36 +msgid ":func:`delattr`" +msgstr ":func:`delattr`" + +#: ../../library/functions.rst:37 +msgid "|func-dict|_" +msgstr "|func-dict|_" + +#: ../../library/functions.rst:38 +msgid ":func:`dir`" +msgstr ":func:`dir`" + +#: ../../library/functions.rst:39 +msgid ":func:`divmod`" +msgstr ":func:`divmod`" + +#: ../../library/functions.rst:13 +msgid "**E**" +msgstr "**E**" + +#: ../../library/functions.rst:14 +msgid ":func:`enumerate`" +msgstr ":func:`enumerate`" + +#: ../../library/functions.rst:15 +msgid ":func:`eval`" +msgstr ":func:`eval`" + +#: ../../library/functions.rst:16 +msgid ":func:`exec`" +msgstr ":func:`exec`" + +#: ../../library/functions.rst:18 +msgid "**F**" +msgstr "**F**" + +#: ../../library/functions.rst:19 +msgid ":func:`filter`" +msgstr ":func:`filter`" + +#: ../../library/functions.rst:20 +msgid ":func:`float`" +msgstr ":func:`float`" + +#: ../../library/functions.rst:21 +msgid ":func:`format`" +msgstr ":func:`format`" + +#: ../../library/functions.rst:22 +msgid "|func-frozenset|_" +msgstr "|func-frozenset|_" + +#: ../../library/functions.rst:24 +msgid "**G**" +msgstr "**G**" + +#: ../../library/functions.rst:25 +msgid ":func:`getattr`" +msgstr ":func:`getattr`" + +#: ../../library/functions.rst:26 +msgid ":func:`globals`" +msgstr ":func:`globals`" + +#: ../../library/functions.rst:28 +msgid "**H**" +msgstr "**H**" + +#: ../../library/functions.rst:29 +msgid ":func:`hasattr`" +msgstr ":func:`hasattr`" + +#: ../../library/functions.rst:30 +msgid ":func:`hash`" +msgstr ":func:`hash`" + +#: ../../library/functions.rst:31 +msgid ":func:`help`" +msgstr ":func:`help`" + +#: ../../library/functions.rst:32 +msgid ":func:`hex`" +msgstr ":func:`hex`" + +#: ../../library/functions.rst:34 +msgid "**I**" +msgstr "**I**" + +#: ../../library/functions.rst:35 +msgid ":func:`id`" +msgstr ":func:`id`" + +#: ../../library/functions.rst:36 +msgid ":func:`input`" +msgstr ":func:`input`" + +#: ../../library/functions.rst:37 +msgid ":func:`int`" +msgstr ":func:`int`" + +#: ../../library/functions.rst:38 +msgid ":func:`isinstance`" +msgstr ":func:`isinstance`" + +#: ../../library/functions.rst:39 +msgid ":func:`issubclass`" +msgstr ":func:`issubclass`" + +#: ../../library/functions.rst:40 +msgid ":func:`iter`" +msgstr ":func:`iter`" + +#: ../../library/functions.rst:13 +msgid "**L**" +msgstr "**L**" + +#: ../../library/functions.rst:14 +msgid ":func:`len`" +msgstr ":func:`len`" + +#: ../../library/functions.rst:15 +msgid "|func-list|_" +msgstr "|func-list|_" + +#: ../../library/functions.rst:16 +msgid ":func:`locals`" +msgstr ":func:`locals`" + +#: ../../library/functions.rst:18 +msgid "**M**" +msgstr "**M**" + +#: ../../library/functions.rst:19 +msgid ":func:`map`" +msgstr ":func:`map`" + +#: ../../library/functions.rst:20 +msgid ":func:`max`" +msgstr ":func:`max`" + +#: ../../library/functions.rst:21 +msgid "|func-memoryview|_" +msgstr "|func-memoryview|_" + +#: ../../library/functions.rst:22 +msgid ":func:`min`" +msgstr ":func:`min`" + +#: ../../library/functions.rst:24 +msgid "**N**" +msgstr "**N**" + +#: ../../library/functions.rst:25 +msgid ":func:`next`" +msgstr ":func:`next`" + +#: ../../library/functions.rst:27 +msgid "**O**" +msgstr "**O**" + +#: ../../library/functions.rst:28 +msgid ":func:`object`" +msgstr ":func:`object`" + +#: ../../library/functions.rst:29 +msgid ":func:`oct`" +msgstr ":func:`oct`" + +#: ../../library/functions.rst:30 +msgid ":func:`open`" +msgstr ":func:`open`" + +#: ../../library/functions.rst:31 +msgid ":func:`ord`" +msgstr ":func:`ord`" + +#: ../../library/functions.rst:33 +msgid "**P**" +msgstr "**P**" + +#: ../../library/functions.rst:34 +msgid ":func:`pow`" +msgstr ":func:`pow`" + +#: ../../library/functions.rst:35 +msgid ":func:`print`" +msgstr ":func:`print`" + +#: ../../library/functions.rst:36 +msgid ":func:`property`" +msgstr ":func:`property`" + +#: ../../library/functions.rst:13 +msgid "**R**" +msgstr "**R**" + +#: ../../library/functions.rst:14 +msgid "|func-range|_" +msgstr "|func-range|_" + +#: ../../library/functions.rst:15 +msgid ":func:`repr`" +msgstr ":func:`repr`" + +#: ../../library/functions.rst:16 +msgid ":func:`reversed`" +msgstr ":func:`reversed`" + +#: ../../library/functions.rst:17 +msgid ":func:`round`" +msgstr ":func:`round`" + +#: ../../library/functions.rst:19 +msgid "**S**" +msgstr "**S**" + +#: ../../library/functions.rst:20 +msgid "|func-set|_" +msgstr "|func-set|_" + +#: ../../library/functions.rst:21 +msgid ":func:`setattr`" +msgstr ":func:`setattr`" + +#: ../../library/functions.rst:22 +msgid ":func:`slice`" +msgstr ":func:`slice`" + +#: ../../library/functions.rst:23 +msgid ":func:`sorted`" +msgstr ":func:`sorted`" + +#: ../../library/functions.rst:24 +msgid ":func:`staticmethod`" +msgstr ":func:`staticmethod`" + +#: ../../library/functions.rst:25 +msgid "|func-str|_" +msgstr "|func-str|_" + +#: ../../library/functions.rst:26 +msgid ":func:`sum`" +msgstr ":func:`sum`" + +#: ../../library/functions.rst:27 +msgid ":func:`super`" +msgstr ":func:`super`" + +#: ../../library/functions.rst:29 +msgid "**T**" +msgstr "**T**" + +#: ../../library/functions.rst:30 +msgid "|func-tuple|_" +msgstr "|func-tuple|_" + +#: ../../library/functions.rst:31 +msgid ":func:`type`" +msgstr ":func:`type`" + +#: ../../library/functions.rst:33 +msgid "**V**" +msgstr "**V**" + +#: ../../library/functions.rst:34 +msgid ":func:`vars`" +msgstr ":func:`vars`" + +#: ../../library/functions.rst:36 +msgid "**Z**" +msgstr "**Z**" + +#: ../../library/functions.rst:37 +msgid ":func:`zip`" +msgstr ":func:`zip`" + +#: ../../library/functions.rst:39 +msgid "**_**" +msgstr "**_**" + +#: ../../library/functions.rst:40 +msgid ":func:`__import__`" +msgstr ":func:`__import__`" + +#: ../../library/functions.rst:59 +msgid "" +"Return the absolute value of a number. The argument may be an integer, a " +"floating-point number, or an object implementing :meth:`~object.__abs__`. If " +"the argument is a complex number, its magnitude is returned." +msgstr "" +"回傳一個數的絕對值，引數可以是整數、浮點數或有實現 :meth:`~object.__abs__` 的" +"物件。如果引數是一個複數，回傳它的純量（大小）。" + +#: ../../library/functions.rst:67 +msgid "" +"Return an :term:`asynchronous iterator` for an :term:`asynchronous " +"iterable`. Equivalent to calling ``x.__aiter__()``." +msgstr "" +"回傳 :term:`非同步疊代器 ` 做為 :term:`非同步可疊代物" +"件 `。相當於呼叫 x.__aiter__()。" + +#: ../../library/functions.rst:70 +msgid "Note: Unlike :func:`iter`, :func:`aiter` has no 2-argument variant." +msgstr "注意：與 :func:`iter` 不同，:func:`aiter` 沒有兩個引數的變體。" + +#: ../../library/functions.rst:76 +msgid "" +"Return ``True`` if all elements of the *iterable* are true (or if the " +"iterable is empty). Equivalent to::" +msgstr "" +"如果 *iterable* 的所有元素皆為真（或 iterable 為空）則回傳 ``True``。等價" +"於： ::" + +#: ../../library/functions.rst:79 +msgid "" +"def all(iterable):\n" +" for element in iterable:\n" +" if not element:\n" +" return False\n" +" return True" +msgstr "" +"def all(iterable):\n" +" for element in iterable:\n" +" if not element:\n" +" return False\n" +" return True" + +#: ../../library/functions.rst:89 +msgid "" +"When awaited, return the next item from the given :term:`asynchronous " +"iterator`, or *default* if given and the iterator is exhausted." +msgstr "" +"當進入 await 時，從給定的 :term:`asynchronous iterator` 中回傳下一個項目" +"（item），疊代完畢則回傳 *default* 。" + +#: ../../library/functions.rst:92 +msgid "" +"This is the async variant of the :func:`next` builtin, and behaves similarly." +msgstr "這是內建函式 :func:`next` 的非同步版本，其行為類似於：" + +#: ../../library/functions.rst:95 +msgid "" +"This calls the :meth:`~object.__anext__` method of *async_iterator*, " +"returning an :term:`awaitable`. Awaiting this returns the next value of the " +"iterator. If *default* is given, it is returned if the iterator is " +"exhausted, otherwise :exc:`StopAsyncIteration` is raised." +msgstr "" +"呼叫 *async_iterator* 的 :meth:`~object.__anext__` 方法，回傳 :term:" +"`awaitable`。等待返回疊代器的下一個值。如果指定 *default*，當疊代器結束時會返" +"回該值，否則會引發 :exc:`StopAsyncIteration` 。" + +#: ../../library/functions.rst:104 +msgid "" +"Return ``True`` if any element of the *iterable* is true. If the iterable " +"is empty, return ``False``. Equivalent to::" +msgstr "" +"如果 *iterable* 的任一元素為真，回傳 ``True``。如果 iterable 是空的，則回傳 " +"``False``。等價於： ::" + +#: ../../library/functions.rst:107 +msgid "" +"def any(iterable):\n" +" for element in iterable:\n" +" if element:\n" +" return True\n" +" return False" +msgstr "" +"def any(iterable):\n" +" for element in iterable:\n" +" if element:\n" +" return True\n" +" return False" + +#: ../../library/functions.rst:116 +msgid "" +"As :func:`repr`, return a string containing a printable representation of an " +"object, but escape the non-ASCII characters in the string returned by :func:" +"`repr` using ``\\x``, ``\\u``, or ``\\U`` escapes. This generates a string " +"similar to that returned by :func:`repr` in Python 2." +msgstr "" +"就像函式 :func:`repr`，回傳一個表示物件的字串，但是 :func:`repr` 回傳的字串中" +"非 ASCII 編碼的字元會被跳脫 (escape)，像是 ``\\x``、``\\u`` 和 ``\\U``。這個" +"函式生成的字串和 Python 2 的 :func:`repr` 回傳的結果相似。" + +#: ../../library/functions.rst:124 +msgid "" +"Convert an integer number to a binary string prefixed with \"0b\". The " +"result is a valid Python expression. If *integer* is not a Python :class:" +"`int` object, it has to define an :meth:`~object.__index__` method that " +"returns an integer. Some examples:" +msgstr "" +"將一個整數轉變為一個前綴為 \"0b\" 的二進位制字串。結果是一個有效的 Python 運" +"算式。如果 *integer* 不是 Python 的 :class:`int` 物件，那它需要定義 :meth:" +"`~object.__index__` method 回傳一個整數。舉例來說：" + +#: ../../library/functions.rst:134 +msgid "" +"If the prefix \"0b\" is desired or not, you can use either of the following " +"ways." +msgstr "如果不一定需要 \"0b\" 前綴，還可以使用如下的方法。" + +#: ../../library/functions.rst:141 ../../library/functions.rst:948 +#: ../../library/functions.rst:1332 +msgid "See also :func:`format` for more information." +msgstr "可參考 :func:`format` 取得更多資訊。" + +#: ../../library/functions.rst:146 +msgid "" +"Return a Boolean value, i.e. one of ``True`` or ``False``. The argument is " +"converted using the standard :ref:`truth testing procedure `. If the " +"argument is false or omitted, this returns ``False``; otherwise, it returns " +"``True``. The :class:`bool` class is a subclass of :class:`int` (see :ref:" +"`typesnumeric`). It cannot be subclassed further. Its only instances are " +"``False`` and ``True`` (see :ref:`typebool`)." +msgstr "" +"回傳一個布林值，即 ``True`` 或者 ``False``。引數會使用標準的\\ :ref:`真值測試" +"程序 `\\ 來轉換。如果引數為假或者被省略，則回傳 ``False``；其他情況回" +"傳 ``True``。:class:`bool` class（類別）是 :class:`int` 的 subclass（子類別）" +"（參見 :ref:`typesnumeric`），其他 class 不能繼承自它。它只有 ``False`` 和 " +"``True`` 兩個實例（參見 :ref:`typebool`）。" + +#: ../../library/functions.rst:156 ../../library/functions.rst:813 +msgid "The parameter is now positional-only." +msgstr "現在為僅限位置參數。" + +#: ../../library/functions.rst:161 +msgid "" +"This function drops you into the debugger at the call site. Specifically, " +"it calls :func:`sys.breakpointhook`, passing ``args`` and ``kws`` straight " +"through. By default, ``sys.breakpointhook()`` calls :func:`pdb.set_trace` " +"expecting no arguments. In this case, it is purely a convenience function " +"so you don't have to explicitly import :mod:`pdb` or type as much code to " +"enter the debugger. However, :func:`sys.breakpointhook` can be set to some " +"other function and :func:`breakpoint` will automatically call that, allowing " +"you to drop into the debugger of choice. If :func:`sys.breakpointhook` is " +"not accessible, this function will raise :exc:`RuntimeError`." +msgstr "" +"這個函式將呼叫 :func:`sys.breakpointhook` 函式，並將 ``args`` 和 ``kws`` 傳遞" +"給它。這將有效地讓你在特定的呼叫點進入除錯器。預設情況下，``sys." +"breakpointhook()`` 呼叫 :func:`pdb.set_trace` 不須帶任何引數。這樣的設計是為" +"了方便使用者，讓他們不需要額外地導入 :mod:`pdb` 模組或輸入太多程式就可以進入" +"除錯器。然而，可以將 :func:`sys.breakpointhook` 設置為其他函式，並且 :func:" +"`breakpoint` 將自動呼叫該函式，讓你進入所選擇的除錯器。如果無法存取 :func:" +"`sys.breakpointhook` 這個函式，則此函式將引發 :exc:`RuntimeError`。" + +#: ../../library/functions.rst:173 +msgid "" +"By default, the behavior of :func:`breakpoint` can be changed with the :" +"envvar:`PYTHONBREAKPOINT` environment variable. See :func:`sys." +"breakpointhook` for usage details." +msgstr "" +"預設情況下，:func:`breakpoint` 的行為可以透過 :envvar:`PYTHONBREAKPOINT` 環境" +"變數來更改。有關使用詳情，請參考 :func:`sys.breakpointhook`。" + +#: ../../library/functions.rst:177 +msgid "" +"Note that this is not guaranteed if :func:`sys.breakpointhook` has been " +"replaced." +msgstr "請注意，如果 :func:`sys.breakpointhook` 被替換了，則無法保證此功能。" + +#: ../../library/functions.rst:180 +msgid "" +"Raises an :ref:`auditing event ` ``builtins.breakpoint`` with " +"argument ``breakpointhook``." +msgstr "" +"引發一個附帶引數 ``breakpointhook`` 的\\ :ref:`稽核事件 ` " +"``builtins.breakpoint``。" + +#: ../../library/functions.rst:189 +msgid "" +"Return a new array of bytes. The :class:`bytearray` class is a mutable " +"sequence of integers in the range 0 <= x < 256. It has most of the usual " +"methods of mutable sequences, described in :ref:`typesseq-mutable`, as well " +"as most methods that the :class:`bytes` type has, see :ref:`bytes-methods`." +msgstr "" +"回傳一個新的 bytes 陣列。:class:`bytearray` class 是一個可變的整數序列，包含" +"範圍為 0 <= x < 256 的整數。它有可變序列大部分常見的 method（如在 :ref:" +"`typesseq-mutable` 中所述），同時也有 :class:`bytes` 型別大部分的 method，參" +"見 :ref:`bytes-methods`。" + +#: ../../library/functions.rst:194 +msgid "" +"The optional *source* parameter can be used to initialize the array in a few " +"different ways:" +msgstr "選擇性參數 *source* 可以被用來以不同的方式初始化陣列：" + +#: ../../library/functions.rst:197 +msgid "" +"If it is a *string*, you must also give the *encoding* (and optionally, " +"*errors*) parameters; :func:`bytearray` then converts the string to bytes " +"using :meth:`str.encode`." +msgstr "" +"如果是一個 *string*，你必須提供 *encoding* 參數（以及選擇性地提供 " +"*errors* ）；:func:`bytearray` 會使用 :meth:`str.encode` method 來將 string " +"轉變成 bytes。" + +#: ../../library/functions.rst:201 +msgid "" +"If it is an *integer*, the array will have that size and will be initialized " +"with null bytes." +msgstr "" +"如果是一個 *integer*，陣列則會有該數值的長度，並以 null bytes 來當作初始值。" + +#: ../../library/functions.rst:204 +msgid "" +"If it is an object conforming to the :ref:`buffer interface " +"`, a read-only buffer of the object will be used to " +"initialize the bytes array." +msgstr "" +"如果是一個符合 :ref:`buffer 介面 `\\ 的物件，該物件的唯讀 " +"buffer 會被用來初始化 bytes 陣列。" + +#: ../../library/functions.rst:207 +msgid "" +"If it is an *iterable*, it must be an iterable of integers in the range ``0 " +"<= x < 256``, which are used as the initial contents of the array." +msgstr "" +"如果是一個 *iterable*，它的元素必須是範圍為 ``0 <= x < 256`` 的整數，並且會被" +"用作陣列的初始值。" + +#: ../../library/functions.rst:210 +msgid "Without an argument, an array of size 0 is created." +msgstr "如果沒有引數，則建立長度為 0 的陣列。" + +#: ../../library/functions.rst:212 +msgid "See also :ref:`binaryseq` and :ref:`typebytearray`." +msgstr "可參考 :ref:`binaryseq` 和 :ref:`typebytearray`。" + +#: ../../library/functions.rst:220 +msgid "" +"Return a new \"bytes\" object which is an immutable sequence of integers in " +"the range ``0 <= x < 256``. :class:`bytes` is an immutable version of :" +"class:`bytearray` -- it has the same non-mutating methods and the same " +"indexing and slicing behavior." +msgstr "" +"回傳一個新的 \"bytes\" 物件，會是一個元素是範圍為 ``0 <= x < 256`` 整數的不可" +"變序列。:class:`bytes` 是 :class:`bytearray` 的不可變版本 — 它的同樣具備不改" +"變物件的 method，也有相同的索引和切片操作。" + +#: ../../library/functions.rst:225 +msgid "" +"Accordingly, constructor arguments are interpreted as for :func:`bytearray`." +msgstr "因此，建構函式的引數和 :func:`bytearray` 相同。" + +#: ../../library/functions.rst:227 +msgid "Bytes objects can also be created with literals, see :ref:`strings`." +msgstr "Bytes 物件還可以用文字建立，參見 :ref:`strings`。" + +#: ../../library/functions.rst:229 +msgid "See also :ref:`binaryseq`, :ref:`typebytes`, and :ref:`bytes-methods`." +msgstr "可參考 :ref:`binaryseq`、:ref:`typebytes` 和 :ref:`bytes-methods`。" + +#: ../../library/functions.rst:234 +msgid "" +"Return :const:`True` if the *object* argument appears callable, :const:" +"`False` if not. If this returns ``True``, it is still possible that a call " +"fails, but if it is ``False``, calling *object* will never succeed. Note " +"that classes are callable (calling a class returns a new instance); " +"instances are callable if their class has a :meth:`~object.__call__` method." +msgstr "" +"如果引數 *object* 是可呼叫的，回傳 :const:`True`，否則回傳 :const:`False`。如" +"果回傳 ``True``，呼叫仍可能會失敗；但如果回傳 ``False``，則呼叫 *object* 肯定" +"會失敗。注意 class 是可呼叫的（呼叫 class 會回傳一個新的實例）；如果實例的 " +"class 有定義 :meth:`~object.__call__` method，則它是可呼叫的。" + +#: ../../library/functions.rst:240 +msgid "" +"This function was first removed in Python 3.0 and then brought back in " +"Python 3.2." +msgstr "這個函式一開始在 Python 3.0 被移除，但在 Python 3.2 又被重新加入。" + +#: ../../library/functions.rst:247 +msgid "" +"Return the string representing a character with the specified Unicode code " +"point. For example, ``chr(97)`` returns the string ``'a'``, while " +"``chr(8364)`` returns the string ``'€'``. This is the inverse of :func:`ord`." +msgstr "" +"回傳代表有特定 Unicode 編碼位置字元的字串。例如，``chr(97)`` 回傳字串 " +"``'a'``，而 ``chr(8364)`` 回傳字串 ``'€'``。這是 :func:`ord` 的逆函式。" + +#: ../../library/functions.rst:251 +msgid "" +"The valid range for the argument is from 0 through 1,114,111 (0x10FFFF in " +"base 16). :exc:`ValueError` will be raised if it is outside that range." +msgstr "" +"引數的有效範圍是 0 到 1,114,111（16 進制表示為 0x10FFFF）。如果它超過這個範" +"圍，會引發 :exc:`ValueError`。" + +#: ../../library/functions.rst:257 +msgid "Transform a method into a class method." +msgstr "把一個 method 封裝成 class method（類別方法）。" + +#: ../../library/functions.rst:259 +msgid "" +"A class method receives the class as an implicit first argument, just like " +"an instance method receives the instance. To declare a class method, use " +"this idiom::" +msgstr "" +"一個 class method 把自己的 class 作為第一個引數，就像一個實例 method 把實例自" +"己作為第一個引數。請用以下慣例來宣告 class method： ::" + +#: ../../library/functions.rst:263 +msgid "" +"class C:\n" +" @classmethod\n" +" def f(cls, arg1, arg2): ..." +msgstr "" +"class C:\n" +" @classmethod\n" +" def f(cls, arg1, arg2): ..." + +#: ../../library/functions.rst:267 +msgid "" +"The ``@classmethod`` form is a function :term:`decorator` -- see :ref:" +"`function` for details." +msgstr "" +"``@classmethod`` 語法是一個函式 :term:`decorator` — 參見 :ref:`function` 中關" +"於函式定義的詳細介紹。" + +#: ../../library/functions.rst:270 +msgid "" +"A class method can be called either on the class (such as ``C.f()``) or on " +"an instance (such as ``C().f()``). The instance is ignored except for its " +"class. If a class method is called for a derived class, the derived class " +"object is passed as the implied first argument." +msgstr "" +"一個 class method 可以在 class（如 ``C.f()``）或實例（如 ``C().f()``）上呼" +"叫。實例除了它的 class 資訊，其他都會被忽略。如果一個 class method 在 " +"subclass 上呼叫，subclass 會作為第一個引數傳入。" + +#: ../../library/functions.rst:275 +msgid "" +"Class methods are different than C++ or Java static methods. If you want " +"those, see :func:`staticmethod` in this section. For more information on " +"class methods, see :ref:`types`." +msgstr "" +"Class method 和 C++ 與 Java 的 static method 是有區別的。如果你想瞭解 static " +"method，請看本節的 :func:`staticmethod`。關於 class method 的更多資訊，請參考" +"\\ :ref:`types`。" + +#: ../../library/functions.rst:279 +msgid "" +"Class methods can now wrap other :term:`descriptors ` such as :" +"func:`property`." +msgstr "" +"Class methods 現在可以包裝其他\\ :term:`描述器 `，例如 :func:" +"`property`" + +#: ../../library/functions.rst:283 +msgid "" +"Class methods now inherit the method attributes (:attr:`~function." +"__module__`, :attr:`~function.__name__`, :attr:`~function.__qualname__`, :" +"attr:`~function.__doc__` and :attr:`~function.__annotations__`) and have a " +"new ``__wrapped__`` attribute." +msgstr "" +"Class method 現在繼承了 method 屬性（:attr:`~function.__module__`、:attr:" +"`~function.__name__`、:attr:`~function.__qualname__`、:attr:`~function." +"__doc__` 和 :attr:`~function.__annotations__`），並擁有一個新的 " +"``__wrapped__`` 屬性。" + +#: ../../library/functions.rst:290 +msgid "" +"Class methods can no longer wrap other :term:`descriptors ` such " +"as :func:`property`." +msgstr "" +"Class methods 不能再包裝其他的\\ :term:`描述器 `，例如 :func:" +"`property`。" + +#: ../../library/functions.rst:297 +msgid "" +"Compile the *source* into a code or AST object. Code objects can be " +"executed by :func:`exec` or :func:`eval`. *source* can either be a normal " +"string, a byte string, or an AST object. Refer to the :mod:`ast` module " +"documentation for information on how to work with AST objects." +msgstr "" +"將 *source* 編譯成程式碼或 AST 物件。程式碼物件可以被 :func:`exec` 或 :func:" +"`eval` 執行。*source* 可以是一般的字串、bytes 字串、或者 AST 物件。參見 :mod:" +"`ast` module（模組）的說明文件瞭解如何使用 AST 物件。" + +#: ../../library/functions.rst:302 +msgid "" +"The *filename* argument should give the file from which the code was read; " +"pass some recognizable value if it wasn't read from a file (``''`` " +"is commonly used)." +msgstr "" +"*filename* 引數必須是程式碼的檔名；如果程式碼不是從檔案中讀取，可以傳入一些可" +"辨識的值（經常會使用 ``''`` 來替代）。" + +#: ../../library/functions.rst:306 +msgid "" +"The *mode* argument specifies what kind of code must be compiled; it can be " +"``'exec'`` if *source* consists of a sequence of statements, ``'eval'`` if " +"it consists of a single expression, or ``'single'`` if it consists of a " +"single interactive statement (in the latter case, expression statements that " +"evaluate to something other than ``None`` will be printed)." +msgstr "" +"*mode* 引數指定了編譯程式碼時必須用的模式。如果 *source* 是一系列的陳述式，可" +"以是 ``'exec'``；如果是單一運算式，可以是 ``'eval'``；如果是單個互動式陳述" +"式，可以是 ``'single'``\\ （在最後一種情況下，如果運算式執行結果不是 " +"``None`` 則會被印出來）。" + +#: ../../library/functions.rst:312 +msgid "" +"The optional arguments *flags* and *dont_inherit* control which :ref:" +"`compiler options ` should be activated and which :ref:" +"`future features ` should be allowed. If neither is present (or both " +"are zero) the code is compiled with the same flags that affect the code that " +"is calling :func:`compile`. If the *flags* argument is given and " +"*dont_inherit* is not (or is zero) then the compiler options and the future " +"statements specified by the *flags* argument are used in addition to those " +"that would be used anyway. If *dont_inherit* is a non-zero integer then the " +"*flags* argument is it -- the flags (future features and compiler options) " +"in the surrounding code are ignored." +msgstr "" +"可選引數 *flags* 和 *dont_inherit* 控制啟用哪個\\ :ref:`編譯器選項 `\\ 以及允許哪個\\ :ref:`未來功能 `。如果兩者都不存在" +"（或兩者都為零），則會呼叫與 :func:`compile` 相同旗標的程式碼來編譯。如果給" +"定 *flags* 引數而未給定 *dont_inherit*\\ （或為零）則無論如何都會使用由 " +"*flags* 引數所指定的編譯器選項和未來陳述式。如果 *dont_inherit* 是一個非零整" +"數，則使用 *flags* 引數 -- 周圍程式碼中的旗標（未來功能和編譯器選項）將被忽" +"略。" + +#: ../../library/functions.rst:323 +msgid "" +"Compiler options and future statements are specified by bits which can be " +"bitwise ORed together to specify multiple options. The bitfield required to " +"specify a given future feature can be found as the :attr:`~__future__." +"_Feature.compiler_flag` attribute on the :class:`~__future__._Feature` " +"instance in the :mod:`__future__` module. :ref:`Compiler flags ` can be found in :mod:`ast` module, with ``PyCF_`` prefix." +msgstr "" +"編譯器選項和 future 陳述式使用 bits 來表示，可以一起被位元操作 OR 來表示複數" +"個選項。需要被具體定義特徵的位元域可以透過 :mod:`__future__` module 中 :" +"class:`~__future__._Feature` 實例中的 :attr:`~__future__._Feature." +"compiler_flag` 屬性來獲得。:ref:`編譯器旗標 `\\ 可以在 :" +"mod:`ast` module 中搜尋有 ``PyCF_`` 前綴的名稱。" + +#: ../../library/functions.rst:331 +msgid "" +"The argument *optimize* specifies the optimization level of the compiler; " +"the default value of ``-1`` selects the optimization level of the " +"interpreter as given by :option:`-O` options. Explicit levels are ``0`` (no " +"optimization; ``__debug__`` is true), ``1`` (asserts are removed, " +"``__debug__`` is false) or ``2`` (docstrings are removed too)." +msgstr "" +"引數 *optimize* 用來指定編譯器的最佳化級別；預設值 ``-1`` 選擇與直譯器的 :" +"option:`-O` 選項相同的最佳化級別。其他級別為 ``0``\\ （沒有最佳化；\\ " +"``__debug__`` 為真值）、``1``\\ （assert 被刪除，``__debug__`` 為假值）或 " +"``2``\\ （說明字串 (docstring) 也被刪除）。" + +#: ../../library/functions.rst:337 +msgid "" +"This function raises :exc:`SyntaxError` or :exc:`ValueError` if the compiled " +"source is invalid." +msgstr "" +"如果編譯的原始碼無效，此函式會引發 :exc:`SyntaxError` 或 :exc:`ValueError`。" + +#: ../../library/functions.rst:340 +msgid "" +"If you want to parse Python code into its AST representation, see :func:`ast." +"parse`." +msgstr "如果你想解析 Python 程式碼為 AST 運算式，請參閱 :func:`ast.parse`。" + +#: ../../library/functions.rst:343 ../../library/functions.rst:345 +msgid "" +"Raises an :ref:`auditing event ` ``compile`` with arguments " +"``source`` and ``filename``. This event may also be raised by implicit " +"compilation." +msgstr "" +"引發一個附帶引數 ``source``、``filename`` 的\\ :ref:`稽核事件 ` " +"``compile``。此事件也可能由隱式編譯 (implicit compilation) 所引發。" + +#: ../../library/functions.rst:351 +msgid "" +"When compiling a string with multi-line code in ``'single'`` or ``'eval'`` " +"mode, input must be terminated by at least one newline character. This is " +"to facilitate detection of incomplete and complete statements in the :mod:" +"`code` module." +msgstr "" +"在 ``'single'`` 或 ``'eval'`` 模式編譯多行程式碼時，輸入必須以至少一個換行符" +"結尾。這使 :mod:`code` module 更容易檢測陳述式的完整性。" + +#: ../../library/functions.rst:358 +msgid "" +"It is possible to crash the Python interpreter with a sufficiently large/" +"complex string when compiling to an AST object due to stack depth " +"limitations in Python's AST compiler." +msgstr "" +"如果編譯足夠大或者足夠複雜的字串成 AST 物件時，Python 直譯器會因為 Python " +"AST 編譯器的 stack 深度限制而崩潰。" + +#: ../../library/functions.rst:362 +msgid "" +"Allowed use of Windows and Mac newlines. Also, input in ``'exec'`` mode " +"does not have to end in a newline anymore. Added the *optimize* parameter." +msgstr "" +"允許使用 Windows 和 Mac 的換行符號。此外，在 ``'exec'`` 模式不需要以換行符號" +"結尾。增加了 *optimize* 參數。" + +#: ../../library/functions.rst:366 +msgid "" +"Previously, :exc:`TypeError` was raised when null bytes were encountered in " +"*source*." +msgstr "在之前的版本，*source* 中包含 null bytes 會引發 :exc:`TypeError`。" + +#: ../../library/functions.rst:370 +msgid "" +"``ast.PyCF_ALLOW_TOP_LEVEL_AWAIT`` can now be passed in flags to enable " +"support for top-level ``await``, ``async for``, and ``async with``." +msgstr "" +"``ast.PyCF_ALLOW_TOP_LEVEL_AWAIT`` 現在可以傳遞旗標以啟用對頂層 ``await``、" +"``async for`` 和 ``async with`` 的支援。" + +#: ../../library/functions.rst:379 +msgid "" +"Convert a single string or number to a complex number, or create a complex " +"number from real and imaginary parts." +msgstr "" + +#: ../../library/functions.rst:382 ../../library/functions.rst:756 +#: ../../library/functions.rst:1004 +msgid "Examples:" +msgstr "例如： ::" + +#: ../../library/functions.rst:384 +msgid "" +">>> complex('+1.23')\n" +"(1.23+0j)\n" +">>> complex('-4.5j')\n" +"-4.5j\n" +">>> complex('-1.23+4.5j')\n" +"(-1.23+4.5j)\n" +">>> complex('\\t( -1.23+4.5J )\\n')\n" +"(-1.23+4.5j)\n" +">>> complex('-Infinity+NaNj')\n" +"(-inf+nanj)\n" +">>> complex(1.23)\n" +"(1.23+0j)\n" +">>> complex(imag=-4.5)\n" +"-4.5j\n" +">>> complex(-1.23, 4.5)\n" +"(-1.23+4.5j)" +msgstr "" +">>> complex('+1.23')\n" +"(1.23+0j)\n" +">>> complex('-4.5j')\n" +"-4.5j\n" +">>> complex('-1.23+4.5j')\n" +"(-1.23+4.5j)\n" +">>> complex('\\t( -1.23+4.5J )\\n')\n" +"(-1.23+4.5j)\n" +">>> complex('-Infinity+NaNj')\n" +"(-inf+nanj)\n" +">>> complex(1.23)\n" +"(1.23+0j)\n" +">>> complex(imag=-4.5)\n" +"-4.5j\n" +">>> complex(-1.23, 4.5)\n" +"(-1.23+4.5j)" + +#: ../../library/functions.rst:403 +msgid "" +"If the argument is a string, it must contain either a real part (in the same " +"format as for :func:`float`) or an imaginary part (in the same format but " +"with a ``'j'`` or ``'J'`` suffix), or both real and imaginary parts (the " +"sign of the imaginary part is mandatory in this case). The string can " +"optionally be surrounded by whitespaces and the round parentheses ``'('`` " +"and ``')'``, which are ignored. The string must not contain whitespace " +"between ``'+'``, ``'-'``, the ``'j'`` or ``'J'`` suffix, and the decimal " +"number. For example, ``complex('1+2j')`` is fine, but ``complex('1 + 2j')`` " +"raises :exc:`ValueError`. More precisely, the input must conform to the :" +"token:`~float:complexvalue` production rule in the following grammar, after " +"parentheses and leading and trailing whitespace characters are removed:" +msgstr "" + +#: ../../library/functions.rst:422 +msgid "" +"If the argument is a number, the constructor serves as a numeric conversion " +"like :class:`int` and :class:`float`. For a general Python object ``x``, " +"``complex(x)`` delegates to ``x.__complex__()``. If :meth:`~object." +"__complex__` is not defined then it falls back to :meth:`~object.__float__`. " +"If :meth:`!__float__` is not defined then it falls back to :meth:`~object." +"__index__`." +msgstr "" +"如果引數是一個數字，則建構函式會像 :class:`int` 和 :class:`float` 一樣進行數" +"值轉換。對於一個普通的 Python 物件 ``x``，``complex(x)`` 會委派給 ``x." +"__complex__()``。如果 :meth:`~object.__complex__` 未定義，則會回退 (fall " +"back) 到 :meth:`~object.__float__`。如果 :meth:`!__float__` 未定義，則會再回" +"退到 :meth:`~object.__index__`。" + +#: ../../library/functions.rst:431 +msgid "" +"If two arguments are provided or keyword arguments are used, each argument " +"may be any numeric type (including complex). If both arguments are real " +"numbers, return a complex number with the real component *real* and the " +"imaginary component *imag*. If both arguments are complex numbers, return a " +"complex number with the real component ``real.real-imag.imag`` and the " +"imaginary component ``real.imag+imag.real``. If one of arguments is a real " +"number, only its real component is used in the above expressions." +msgstr "" + +#: ../../library/functions.rst:441 +msgid "" +"See also :meth:`complex.from_number` which only accepts a single numeric " +"argument." +msgstr "" + +#: ../../library/functions.rst:443 +msgid "If all arguments are omitted, returns ``0j``." +msgstr "" + +#: ../../library/functions.rst:445 +msgid "The complex type is described in :ref:`typesnumeric`." +msgstr "複數型別在 :ref:`typesnumeric` 中有相關描述。" + +#: ../../library/functions.rst:447 ../../library/functions.rst:810 +#: ../../library/functions.rst:1052 +msgid "Grouping digits with underscores as in code literals is allowed." +msgstr "可以使用底線將程式碼文字中的數字進行分組。" + +#: ../../library/functions.rst:450 +msgid "" +"Falls back to :meth:`~object.__index__` if :meth:`~object.__complex__` and :" +"meth:`~object.__float__` are not defined." +msgstr "" +"如果 :meth:`~object.__complex__` 和 :meth:`~object.__float__` 未定義，則會回" +"退到 :meth:`~object.__index__`。" + +#: ../../library/functions.rst:454 +msgid "" +"Passing a complex number as the *real* or *imag* argument is now deprecated; " +"it should only be passed as a single positional argument." +msgstr "" + +#: ../../library/functions.rst:461 +msgid "" +"This is a relative of :func:`setattr`. The arguments are an object and a " +"string. The string must be the name of one of the object's attributes. The " +"function deletes the named attribute, provided the object allows it. For " +"example, ``delattr(x, 'foobar')`` is equivalent to ``del x.foobar``. *name* " +"need not be a Python identifier (see :func:`setattr`)." +msgstr "" +"這是 :func:`setattr` 相關的函式。引數是一個物件和一個字串，該字串必須是物件中" +"某個屬性名稱。如果物件允許，該函式將刪除指定的屬性。例如 ``delattr(x, " +"'foobar')`` 等價於 ``del x.foobar``。*name* 不必是個 Python 識別符 " +"(identifier)（請見 :func:`setattr`）。" + +#: ../../library/functions.rst:474 +msgid "" +"Create a new dictionary. The :class:`dict` object is the dictionary class. " +"See :class:`dict` and :ref:`typesmapping` for documentation about this class." +msgstr "" +"建立一個新的 dictionary（字典）。:class:`dict` 物件是一個 dictionary class。" +"參見 :class:`dict` 和 :ref:`typesmapping` 來瞭解這個 class。" + +#: ../../library/functions.rst:477 +msgid "" +"For other containers see the built-in :class:`list`, :class:`set`, and :" +"class:`tuple` classes, as well as the :mod:`collections` module." +msgstr "" +"其他容器型別，請參見內建的 :class:`list`、:class:`set` 和 :class:`tuple` " +"class，以及 :mod:`collections` module。" + +#: ../../library/functions.rst:484 +msgid "" +"Without arguments, return the list of names in the current local scope. " +"With an argument, attempt to return a list of valid attributes for that " +"object." +msgstr "" +"如果沒有引數，則回傳目前區域作用域 (local scope) 中的名稱列表。如果有引數，它" +"會嘗試回傳該物件的有效屬性列表。" + +#: ../../library/functions.rst:487 +msgid "" +"If the object has a method named :meth:`~object.__dir__`, this method will " +"be called and must return the list of attributes. This allows objects that " +"implement a custom :func:`~object.__getattr__` or :func:`~object." +"__getattribute__` function to customize the way :func:`dir` reports their " +"attributes." +msgstr "" +"如果物件有一個名為 :meth:`~object.__dir__` 的 method，那麼該 method 將被呼" +"叫，並且必須回傳一個屬性列表。這允許實現自訂 :func:`~object.__getattr__` " +"或 :func:`~object.__getattribute__` 函式的物件能夠自訂 :func:`dir` 來報告它" +"們的屬性。" + +#: ../../library/functions.rst:494 +msgid "" +"If the object does not provide :meth:`~object.__dir__`, the function tries " +"its best to gather information from the object's :attr:`~object.__dict__` " +"attribute, if defined, and from its type object. The resulting list is not " +"necessarily complete and may be inaccurate when the object has a custom :" +"func:`~object.__getattr__`." +msgstr "" +"如果物件不提供 :meth:`~object.__dir__`，這個函式會嘗試從物件已定義的 :attr:" +"`~object.__dict__` 屬性和型別物件收集資訊。結果列表並不總是完整的，如果物件有" +"自訂 :func:`~object.__getattr__`，那結果可能不準確。" + +#: ../../library/functions.rst:500 +msgid "" +"The default :func:`dir` mechanism behaves differently with different types " +"of objects, as it attempts to produce the most relevant, rather than " +"complete, information:" +msgstr "" +"預設的 :func:`dir` 機制對不同型別的物件有不同行為，它會試圖回傳最相關而非最完" +"整的資訊：" + +#: ../../library/functions.rst:504 +msgid "" +"If the object is a module object, the list contains the names of the " +"module's attributes." +msgstr "如果物件是 module 物件，則列表包含 module 的屬性名稱。" + +#: ../../library/functions.rst:507 +msgid "" +"If the object is a type or class object, the list contains the names of its " +"attributes, and recursively of the attributes of its bases." +msgstr "" +"如果物件是型別或 class 物件，則列表包含它們的屬性名稱，並且遞迴查詢其基礎的所" +"有屬性。" + +#: ../../library/functions.rst:510 +msgid "" +"Otherwise, the list contains the object's attributes' names, the names of " +"its class's attributes, and recursively of the attributes of its class's " +"base classes." +msgstr "" +"否則，包含物件的屬性名稱列表、它的 class 屬性名稱，並且遞迴查詢它的 class 的" +"所有基礎 class 的屬性。" + +#: ../../library/functions.rst:514 +msgid "The resulting list is sorted alphabetically. For example:" +msgstr "回傳的列表按字母表排序，例如：" + +#: ../../library/functions.rst:534 +msgid "" +"Because :func:`dir` is supplied primarily as a convenience for use at an " +"interactive prompt, it tries to supply an interesting set of names more than " +"it tries to supply a rigorously or consistently defined set of names, and " +"its detailed behavior may change across releases. For example, metaclass " +"attributes are not in the result list when the argument is a class." +msgstr "" +"因為 :func:`dir` 主要是為了便於在互動式提示字元時使用，所以它會試圖回傳人們感" +"興趣的名稱集合，而不是試圖保證結果的嚴格性或一致性，它具體的行為也可能在不同" +"版本之間改變。例如，當引數是一個 class 時，metaclass 的屬性不包含在結果列表" +"中。" + +#: ../../library/functions.rst:544 +msgid "" +"Take two (non-complex) numbers as arguments and return a pair of numbers " +"consisting of their quotient and remainder when using integer division. " +"With mixed operand types, the rules for binary arithmetic operators apply. " +"For integers, the result is the same as ``(a // b, a % b)``. For floating-" +"point numbers the result is ``(q, a % b)``, where *q* is usually ``math." +"floor(a / b)`` but may be 1 less than that. In any case ``q * b + a % b`` " +"is very close to *a*, if ``a % b`` is non-zero it has the same sign as *b*, " +"and ``0 <= abs(a % b) < abs(b)``." +msgstr "" +"它將兩個（非複數）數字作為引數，並在執行整數除法時回傳一對商和餘數。對於混合" +"運算元型別，適用二進位算術運算子的規則。對於整數，運算結果和 ``(a // b, a % " +"b)`` 一致。對於浮點數，運算結果是 ``(q, a % b)``，*q* 通常是 ``math." +"floor(a / b)`` 但可能會比 1 小。在任何情況下，``q * b + a % b`` 和 *a* 基本相" +"等，如果 ``a % b`` 非零，則它的符號和 *b* 一樣，且 ``0 <= abs(a % b) < " +"abs(b)``。" + +#: ../../library/functions.rst:556 +msgid "" +"Return an enumerate object. *iterable* must be a sequence, an :term:" +"`iterator`, or some other object which supports iteration. The :meth:" +"`~iterator.__next__` method of the iterator returned by :func:`enumerate` " +"returns a tuple containing a count (from *start* which defaults to 0) and " +"the values obtained from iterating over *iterable*." +msgstr "" +"回傳一個列舉 (enumerate) 物件。*iterable* 必須是一個序列、:term:`iterator` 或" +"其他支援疊代的物件。:func:`enumerate` 回傳之 iterator 的 :meth:`~iterator." +"__next__` method 回傳一個 tuple（元組），裡面包含一個計數值（從 *start* 開" +"始，預設為 0）和透過疊代 *iterable* 獲得的值。" + +#: ../../library/functions.rst:568 +msgid "Equivalent to::" +msgstr "等價於： ::" + +#: ../../library/functions.rst:570 +msgid "" +"def enumerate(iterable, start=0):\n" +" n = start\n" +" for elem in iterable:\n" +" yield n, elem\n" +" n += 1" +msgstr "" +"def enumerate(iterable, start=0):\n" +" n = start\n" +" for elem in iterable:\n" +" yield n, elem\n" +" n += 1" + +#: ../../library/functions.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../library/functions.rst:580 +msgid "A Python expression." +msgstr "" + +#: ../../library/functions.rst:584 +msgid "The global namespace (default: ``None``)." +msgstr "" + +#: ../../library/functions.rst:588 +msgid "The local namespace (default: ``None``)." +msgstr "" + +#: ../../library/functions.rst:0 +msgid "Returns" +msgstr "" + +#: ../../library/functions.rst:592 +msgid "The result of the evaluated expression." +msgstr "" + +#: ../../library/functions.rst:0 +msgid "raises" +msgstr "引發" + +#: ../../library/functions.rst:593 +msgid "Syntax errors are reported as exceptions." +msgstr "" + +#: ../../library/functions.rst:597 ../../library/functions.rst:658 +msgid "" +"This function executes arbitrary code. Calling it with user-supplied input " +"may lead to security vulnerabilities." +msgstr "" + +#: ../../library/functions.rst:600 +msgid "" +"The *source* argument is parsed and evaluated as a Python expression " +"(technically speaking, a condition list) using the *globals* and *locals* " +"mappings as global and local namespace. If the *globals* dictionary is " +"present and does not contain a value for the key ``__builtins__``, a " +"reference to the dictionary of the built-in module :mod:`builtins` is " +"inserted under that key before *source* is parsed. That way you can control " +"what builtins are available to the executed code by inserting your own " +"``__builtins__`` dictionary into *globals* before passing it to :func:" +"`eval`. If the *locals* mapping is omitted it defaults to the *globals* " +"dictionary. If both mappings are omitted, the source is executed with the " +"*globals* and *locals* in the environment where :func:`eval` is called. " +"Note, *eval()* will only have access to the :term:`nested scopes ` (non-locals) in the enclosing environment if they are already " +"referenced in the scope that is calling :func:`eval` (e.g. via a :keyword:" +"`nonlocal` statement)." +msgstr "" +"*source* 引數會被視為一條 Python 運算式（技術上而言，是條件列表）來剖析及" +"求值，而 *globals* 和 *locals* 對映分別用作全域和區域命名空間。如果 " +"*globals* dictionary 存在但缺少 ``__builtins__`` 的鍵值，那 *source* 被剖" +"析之前，將為該鍵插入對內建 :mod:`builtins` module dictionary 的引用。這麼一" +"來，在將 ``__builtins__`` dictionary 傳入 :func:`eval` 之前，你可以透過將它插" +"入 *globals* 來控制你需要哪些內建函式來執行程式碼。如果 *locals* 對映被省略，" +"那它的預設值是 *globals* dictionary。如果兩個對映都被省略，則以在 :func:" +"`eval` 被呼叫的環境中的 *globals* 和 *locals* 執行原始碼。請注意，*eval()* 在" +"封閉 (enclosing) 環境中無法存取\\ :term:`巢狀作用域 ` (non-" +"locals)，除非呼叫 :func:`eval` 的作用域已經有參照它們（例如透過 :keyword:" +"`nonlocal` 陳述式）。" + +#: ../../library/functions.rst:616 +msgid "Example:" +msgstr "範例：" + +#: ../../library/functions.rst:622 +msgid "" +"This function can also be used to execute arbitrary code objects (such as " +"those created by :func:`compile`). In this case, pass a code object instead " +"of a string. If the code object has been compiled with ``'exec'`` as the " +"*mode* argument, :func:`eval`\\'s return value will be ``None``." +msgstr "" +"這個函式也可以用來執行任意程式碼物件（如被 :func:`compile` 建立的那些）。這種" +"情況下，傳入的引數是程式碼物件而不是字串。如果編譯該物件時的 *mode* 引數是 " +"``'exec'``，那麼 :func:`eval` 回傳值為 ``None``。" + +#: ../../library/functions.rst:627 +msgid "" +"Hints: dynamic execution of statements is supported by the :func:`exec` " +"function. The :func:`globals` and :func:`locals` functions return the " +"current global and local dictionary, respectively, which may be useful to " +"pass around for use by :func:`eval` or :func:`exec`." +msgstr "" +"提示：:func:`exec` 函式支援動態執行陳述式。:func:`globals` 和 :func:`locals` " +"函式分別回傳目前的全域性和局部性 dictionary，它們對於將引數傳遞給 :func:" +"`eval` 或 :func:`exec` 可能會方便許多。" + +#: ../../library/functions.rst:632 +msgid "" +"If the given source is a string, then leading and trailing spaces and tabs " +"are stripped." +msgstr "如果給定來源是一個字串，那麼其前後的空格和定位字元會被移除。" + +#: ../../library/functions.rst:635 +msgid "" +"See :func:`ast.literal_eval` for a function that can safely evaluate strings " +"with expressions containing only literals." +msgstr "" +"另外可以參閱 :func:`ast.literal_eval`，該函式可以安全執行僅包含文字的運算式字" +"串。" + +#: ../../library/functions.rst:638 ../../library/functions.rst:640 +#: ../../library/functions.rst:700 ../../library/functions.rst:702 +msgid "" +"Raises an :ref:`auditing event ` ``exec`` with the code object as " +"the argument. Code compilation events may also be raised." +msgstr "" +"引發一個附帶程式碼物件為引數的\\ :ref:`稽核事件 ` ``exec``。也可能" +"會引發程式碼編譯事件。" + +#: ../../library/functions.rst:645 ../../library/functions.rst:722 +msgid "The *globals* and *locals* arguments can now be passed as keywords." +msgstr "" + +#: ../../library/functions.rst:649 ../../library/functions.rst:726 +msgid "" +"The semantics of the default *locals* namespace have been adjusted as " +"described for the :func:`locals` builtin." +msgstr "" + +#: ../../library/functions.rst:661 +msgid "" +"This function supports dynamic execution of Python code. *source* must be " +"either a string or a code object. If it is a string, the string is parsed " +"as a suite of Python statements which is then executed (unless a syntax " +"error occurs). [#]_ If it is a code object, it is simply executed. In all " +"cases, the code that's executed is expected to be valid as file input (see " +"the section :ref:`file-input` in the Reference Manual). Be aware that the :" +"keyword:`nonlocal`, :keyword:`yield`, and :keyword:`return` statements may " +"not be used outside of function definitions even within the context of code " +"passed to the :func:`exec` function. The return value is ``None``." +msgstr "" +"這個函式支援動態執行 Python 程式碼。*source* 必須是字串或者程式碼物件。如果是" +"字串，那麼該字串將被剖析為一系列 Python 陳述式並執行（除非發生語法錯誤）。" +"[#]_ 如果是程式碼物件，它將被直接執行。無論哪種情況，被執行的程式碼都需要和檔" +"案輸入一樣是有效的（可參閱語言參考手冊中關於\\ :ref:`file-input`\\ 的章節）。" +"請注意，即使在傳遞給 :func:`exec` 函式的程式碼的上下文中，:keyword:" +"`nonlocal`、:keyword:`yield` 和 :keyword:`return` 陳述式也不能在函式之外使" +"用。該函式回傳值是 ``None``。" + +#: ../../library/functions.rst:672 +msgid "" +"In all cases, if the optional parts are omitted, the code is executed in the " +"current scope. If only *globals* is provided, it must be a dictionary (and " +"not a subclass of dictionary), which will be used for both the global and " +"the local variables. If *globals* and *locals* are given, they are used for " +"the global and local variables, respectively. If provided, *locals* can be " +"any mapping object. Remember that at the module level, globals and locals " +"are the same dictionary." +msgstr "" +"無論哪種情況，如果省略了選擇性的部分，程式碼將在目前作用域內執行。如果只提供" +"了 *globals* 引數，就必須是 dictionary 型別（且不能是 dictionary 的子類別），" +"而且會被用作全域和區域變數。如果同時提供了 *globals* 和 *locals*，它們分別被" +"用作全域和區域變數。如果提供了 *locals*，則它可以是任何對映物件。請記住在 " +"module 層級中全域和區域變數是相同的 dictionary。" + +#: ../../library/functions.rst:682 +msgid "" +"When ``exec`` gets two separate objects as *globals* and *locals*, the code " +"will be executed as if it were embedded in a class definition. This means " +"functions and classes defined in the executed code will not be able to " +"access variables assigned at the top level (as the \"top level\" variables " +"are treated as class variables in a class definition)." +msgstr "" + +#: ../../library/functions.rst:688 +msgid "" +"If the *globals* dictionary does not contain a value for the key " +"``__builtins__``, a reference to the dictionary of the built-in module :mod:" +"`builtins` is inserted under that key. That way you can control what " +"builtins are available to the executed code by inserting your own " +"``__builtins__`` dictionary into *globals* before passing it to :func:`exec`." +msgstr "" +"如果 *globals* dictionary 不包含 ``__builtins__`` 鍵值，則將為該鍵插入對內" +"建 :mod:`builtins` module dictionary 的引用。這麼一來，在將 ``__builtins__`` " +"dictionary 傳入 :func:`exec` 之前，你可以透過將它插入 *globals* 來控制你需要" +"哪些內建函式來執行程式碼。" + +#: ../../library/functions.rst:694 +msgid "" +"The *closure* argument specifies a closure--a tuple of cellvars. It's only " +"valid when the *object* is a code object containing :term:`free (closure) " +"variables `. The length of the tuple must exactly match " +"the length of the code object's :attr:`~codeobject.co_freevars` attribute." +msgstr "" +"*closure* 引數會指定一個閉包 (closure) — 它是一個 cellvar（格變數）的 tuple。" +"只有在 *object* 是一個含有\\ :term:`自由（閉包）變數 (free (closure) " +"variables) ` 的程式碼物件時，它才有效。Tuple 的長度必須與程" +"式碼物件的 :attr:`~codeobject.co_freevars` 屬性完全匹配。" + +#: ../../library/functions.rst:707 +msgid "" +"The built-in functions :func:`globals` and :func:`locals` return the current " +"global and local namespace, respectively, which may be useful to pass around " +"for use as the second and third argument to :func:`exec`." +msgstr "" +"內建 :func:`globals` 和 :func:`locals` 函式各自回傳目前的全域和區域命名空間，" +"因此可以將它們傳遞給 :func:`exec` 的第二個和第三個引數以供後續使用。" + +#: ../../library/functions.rst:713 +msgid "" +"The default *locals* act as described for function :func:`locals` below. " +"Pass an explicit *locals* dictionary if you need to see effects of the code " +"on *locals* after function :func:`exec` returns." +msgstr "" +"預設情況下，*locals* 的行為如下面 :func:`locals` 函式描述的一樣。如果你想在 :" +"func:`exec` 函式回傳時知道程式碼對 *locals* 的變動，請明確地傳遞 *locals* " +"dictionary 。" + +#: ../../library/functions.rst:717 +msgid "Added the *closure* parameter." +msgstr "增加了 *closure* 參數。" + +#: ../../library/functions.rst:732 +msgid "" +"Construct an iterator from those elements of *iterable* for which *function* " +"is true. *iterable* may be either a sequence, a container which supports " +"iteration, or an iterator. If *function* is ``None``, the identity function " +"is assumed, that is, all elements of *iterable* that are false are removed." +msgstr "" +"用 *iterable* 中函式 *function* 為 True 的那些元素，構建一個新的 iterator。" +"*iterable* 可以是一個序列、一個支援疊代的容器、或一個 iterator。如果 " +"*function* 是 ``None``，則會假設它是一個識別性函式，即 *iterable* 中所有假值" +"元素會被移除。" + +#: ../../library/functions.rst:738 +msgid "" +"Note that ``filter(function, iterable)`` is equivalent to the generator " +"expression ``(item for item in iterable if function(item))`` if function is " +"not ``None`` and ``(item for item in iterable if item)`` if function is " +"``None``." +msgstr "" +"請注意，``filter(function, iterable)`` 相當於一個生成器運算式，當 function 不" +"是 ``None`` 的時候為 ``(item for item in iterable if function(item))``；" +"function 是 ``None`` 的時候為 ``(item for item in iterable if item)``。" + +#: ../../library/functions.rst:743 +msgid "" +"See :func:`itertools.filterfalse` for the complementary function that " +"returns elements of *iterable* for which *function* is false." +msgstr "" +"請參閱 :func:`itertools.filterfalse`，只有 *function* 為 false 時才選取 " +"*iterable* 中元素的互補函式。" + +#: ../../library/functions.rst:754 +msgid "Return a floating-point number constructed from a number or a string." +msgstr "回傳從數字或字串生成的浮點數。" + +#: ../../library/functions.rst:758 +msgid "" +">>> float('+1.23')\n" +"1.23\n" +">>> float(' -12345\\n')\n" +"-12345.0\n" +">>> float('1e-003')\n" +"0.001\n" +">>> float('+1E6')\n" +"1000000.0\n" +">>> float('-Infinity')\n" +"-inf" +msgstr "" +">>> float('+1.23')\n" +"1.23\n" +">>> float(' -12345\\n')\n" +"-12345.0\n" +">>> float('1e-003')\n" +"0.001\n" +">>> float('+1E6')\n" +"1000000.0\n" +">>> float('-Infinity')\n" +"-inf" + +#: ../../library/functions.rst:771 +msgid "" +"If the argument is a string, it should contain a decimal number, optionally " +"preceded by a sign, and optionally embedded in whitespace. The optional " +"sign may be ``'+'`` or ``'-'``; a ``'+'`` sign has no effect on the value " +"produced. The argument may also be a string representing a NaN (not-a-" +"number), or positive or negative infinity. More precisely, the input must " +"conform to the :token:`~float:floatvalue` production rule in the following " +"grammar, after leading and trailing whitespace characters are removed:" +msgstr "" +"如果引數是字串，則它必須是包含十進位制數字的字串，字串前面可以有符號，之前也" +"可以有空格。選擇性的符號有 ``'+'`` 和 ``'-'``；``'+'`` 對建立的值沒有影響。引" +"數也可以是 NaN（非數字）或正負無窮大的字串。確切地說，除去首尾的空格後，輸入" +"必須遵循以下語法中 :token:`~float:floatvalue` 的生成規則：" + +#: ../../library/functions.rst:792 +msgid "" +"Case is not significant, so, for example, \"inf\", \"Inf\", \"INFINITY\", " +"and \"iNfINity\" are all acceptable spellings for positive infinity." +msgstr "" +"字母大小寫不影響，例如，\"inf\"、\"Inf\"、\"INFINITY\"、\"iNfINity\" 都可以表" +"示正無窮大。" + +#: ../../library/functions.rst:795 +msgid "" +"Otherwise, if the argument is an integer or a floating-point number, a " +"floating-point number with the same value (within Python's floating-point " +"precision) is returned. If the argument is outside the range of a Python " +"float, an :exc:`OverflowError` will be raised." +msgstr "" +"否則，如果引數是整數或浮點數，則回傳具有相同值（在 Python 浮點精度範圍內）的" +"浮點數。如果引數在 Python 浮點精度範圍外，則會引發 :exc:`OverflowError`。" + +#: ../../library/functions.rst:800 +msgid "" +"For a general Python object ``x``, ``float(x)`` delegates to ``x." +"__float__()``. If :meth:`~object.__float__` is not defined then it falls " +"back to :meth:`~object.__index__`." +msgstr "" +"對於一般的 Python 物件 ``x``，``float(x)`` 會委派給 ``x.__float__()``。如果未" +"定義 :meth:`~object.__float__` 則會回退到 :meth:`~object.__index__`。" + +#: ../../library/functions.rst:804 +msgid "" +"See also :meth:`float.from_number` which only accepts a numeric argument." +msgstr "" + +#: ../../library/functions.rst:806 +msgid "If no argument is given, ``0.0`` is returned." +msgstr "如果沒有引數，則回傳 ``0.0``。" + +#: ../../library/functions.rst:808 +msgid "The float type is described in :ref:`typesnumeric`." +msgstr ":ref:`typesnumeric` 描述了浮點數型別。" + +#: ../../library/functions.rst:816 +msgid "" +"Falls back to :meth:`~object.__index__` if :meth:`~object.__float__` is not " +"defined." +msgstr "" +"如果 :meth:`~object.__float__` 未定義，則會回退到 :meth:`~object.__index__`。" + +#: ../../library/functions.rst:826 +msgid "" +"Convert a *value* to a \"formatted\" representation, as controlled by " +"*format_spec*. The interpretation of *format_spec* will depend on the type " +"of the *value* argument; however, there is a standard formatting syntax that " +"is used by most built-in types: :ref:`formatspec`." +msgstr "" +"將 *value* 轉換為 *format_spec* 控制的 \"格式化\" 表示。*format_spec* 的解釋" +"取決於 *value* 引數的型別，但是大多數內建型別使用標準格式化語法：:ref:" +"`formatspec`。" + +#: ../../library/functions.rst:831 +msgid "" +"The default *format_spec* is an empty string which usually gives the same " +"effect as calling :func:`str(value) `." +msgstr "" +"預設的 *format_spec* 是一個空字串，它通常和呼叫 :func:`str(value) ` 的效" +"果相同。" + +#: ../../library/functions.rst:834 +msgid "" +"A call to ``format(value, format_spec)`` is translated to ``type(value)." +"__format__(value, format_spec)`` which bypasses the instance dictionary when " +"searching for the value's :meth:`~object.__format__` method. A :exc:" +"`TypeError` exception is raised if the method search reaches :mod:`object` " +"and the *format_spec* is non-empty, or if either the *format_spec* or the " +"return value are not strings." +msgstr "" +"呼叫 ``format(value, format_spec)`` 會轉換成 ``type(value).__format__(value, " +"format_spec)``，當搜尋 value 的 :meth:`~object.__format__` method 時，會忽略" +"實例中的字典。如果搜尋到 :mod:`object` 這個 method 但 *format_spec* 不為空，" +"或是 *format_spec* 或回傳值不是字串，則會引發 :exc:`TypeError`。" + +#: ../../library/functions.rst:841 +msgid "" +"``object().__format__(format_spec)`` raises :exc:`TypeError` if " +"*format_spec* is not an empty string." +msgstr "" +"當 *format_spec* 不是空字串時，``object().__format__(format_spec)`` 會引發 :" +"exc:`TypeError`。" + +#: ../../library/functions.rst:850 +msgid "" +"Return a new :class:`frozenset` object, optionally with elements taken from " +"*iterable*. ``frozenset`` is a built-in class. See :class:`frozenset` and :" +"ref:`types-set` for documentation about this class." +msgstr "" +"回傳一個新的 :class:`frozenset` 物件，它包含選擇性引數 *iterable* 中的元素。" +"``frozenset`` 是一個內建的 class。有關此 class 的文件，請參閱 :class:" +"`frozenset` 和 :ref:`types-set`。" + +#: ../../library/functions.rst:854 +msgid "" +"For other containers see the built-in :class:`set`, :class:`list`, :class:" +"`tuple`, and :class:`dict` classes, as well as the :mod:`collections` module." +msgstr "" +"請參閱內建的 :class:`set`、:class:`list`、:class:`tuple` 和 :class:`dict` " +"class，以及 :mod:`collections` module 來了解其它的容器。" + +#: ../../library/functions.rst:862 +msgid "" +"Return the value of the named attribute of *object*. *name* must be a " +"string. If the string is the name of one of the object's attributes, the " +"result is the value of that attribute. For example, ``getattr(x, " +"'foobar')`` is equivalent to ``x.foobar``. If the named attribute does not " +"exist, *default* is returned if provided, otherwise :exc:`AttributeError` is " +"raised. *name* need not be a Python identifier (see :func:`setattr`)." +msgstr "" +"回傳 *object* 之具名屬性的值。*name* 必須是字串。如果該字串是物件屬性之一的名" +"稱，則回傳該屬性的值。例如，``getattr(x, 'foobar')`` 等同於 ``x.foobar``。如" +"果指定的屬性不存在，且提供了 *default* 值，則回傳其值，否則引發 :exc:" +"`AttributeError`。*name* 不必是個 Python 識別符 (identifier)（請見 :func:" +"`setattr`）。" + +#: ../../library/functions.rst:871 +msgid "" +"Since :ref:`private name mangling ` happens at " +"compilation time, one must manually mangle a private attribute's (attributes " +"with two leading underscores) name in order to retrieve it with :func:" +"`getattr`." +msgstr "" +"由於\\ :ref:`私有名稱改編 (private name mangling) ` 是" +"發生在編譯期，因此你必須手動改編私有屬性（有兩個前導底線的屬性）的名稱，才能" +"使用 :func:`getattr` 來取得它。" + +#: ../../library/functions.rst:879 +msgid "" +"Return the dictionary implementing the current module namespace. For code " +"within functions, this is set when the function is defined and remains the " +"same regardless of where the function is called." +msgstr "" +"回傳代表目前 module 命名空間的 dictionary。對於在函式中的程式碼來說，這在定義" +"函式時設定且不論該函式是在何處呼叫都會保持相同。" + +#: ../../library/functions.rst:886 +msgid "" +"The arguments are an object and a string. The result is ``True`` if the " +"string is the name of one of the object's attributes, ``False`` if not. " +"(This is implemented by calling ``getattr(object, name)`` and seeing whether " +"it raises an :exc:`AttributeError` or not.)" +msgstr "" +"該引數是一個物件和一個字串。如果字串是物件屬性之一的名稱，則回傳 ``True``，否" +"則回傳 ``False``。（此功能是透過呼叫 ``getattr(object, name)`` 並檢查是否引" +"發 :exc:`AttributeError` 來實作的。）" + +#: ../../library/functions.rst:894 +msgid "" +"Return the hash value of the object (if it has one). Hash values are " +"integers. They are used to quickly compare dictionary keys during a " +"dictionary lookup. Numeric values that compare equal have the same hash " +"value (even if they are of different types, as is the case for 1 and 1.0)." +msgstr "" +"回傳該物件的雜湊值（如果它有的話）。雜湊值是整數。它們在 dictionary 查詢元素" +"時用來快速比較 dictionary 的鍵。相同大小的數字數值有相同的雜湊值（即使它們型" +"別不同，如 1 和 1.0）。" + +#: ../../library/functions.rst:901 +msgid "" +"For objects with custom :meth:`~object.__hash__` methods, note that :func:" +"`hash` truncates the return value based on the bit width of the host machine." +msgstr "" +"請注意，如果物件帶有自訂的 :meth:`~object.__hash__` 方法，:func:`hash` 將根據" +"運行機器的位元長度來截斷回傳值。" + +#: ../../library/functions.rst:908 +msgid "" +"Invoke the built-in help system. (This function is intended for interactive " +"use.) If no argument is given, the interactive help system starts on the " +"interpreter console. If the argument is a string, then the string is looked " +"up as the name of a module, function, class, method, keyword, or " +"documentation topic, and a help page is printed on the console. If the " +"argument is any other kind of object, a help page on the object is generated." +msgstr "" +"啟動內建的幫助系統（此函式主要以互動式使用）。如果沒有引數，直譯器控制台裡會" +"啟動互動式幫助系統。如果引數是一個字串，則會在 module、函式、class、method、" +"關鍵字或說明文件主題中搜尋該字串，並在控制台上列印幫助資訊。如果引數是其他任" +"意物件，則會生成該物件的幫助頁。" + +#: ../../library/functions.rst:915 +msgid "" +"Note that if a slash(/) appears in the parameter list of a function when " +"invoking :func:`help`, it means that the parameters prior to the slash are " +"positional-only. For more info, see :ref:`the FAQ entry on positional-only " +"parameters `." +msgstr "" +"請注意，呼叫 :func:`help` 時，如果斜線 (/) 出現在函式的參數列表中，這表示斜線" +"前面的參數是僅限位置 (positional-only) 參數。有關更多資訊，請參閱\\ :ref:`常" +"見問答集中的僅限位置參數條目 `。" + +#: ../../library/functions.rst:920 +msgid "" +"This function is added to the built-in namespace by the :mod:`site` module." +msgstr "此函式會被 :mod:`site` module 加入到內建命名空間。" + +#: ../../library/functions.rst:922 +msgid "" +"Changes to :mod:`pydoc` and :mod:`inspect` mean that the reported signatures " +"for callables are now more comprehensive and consistent." +msgstr "" +"對於 :mod:`pydoc` 和 :mod:`inspect` 的變更，使得可呼叫物件回報的的簽名 " +"(signature) 更加全面和一致。" + +#: ../../library/functions.rst:929 +msgid "" +"Convert an integer number to a lowercase hexadecimal string prefixed with " +"\"0x\". If *integer* is not a Python :class:`int` object, it has to define " +"an :meth:`~object.__index__` method that returns an integer. Some examples:" +msgstr "" +"將整數轉換為以 \"0x\" 為前綴的小寫十六進位制字串。如果 *integer* 不是 " +"Python :class:`int` 物件，則必須定義一個 :meth:`~object.__index__` method 並" +"且回傳一個整數。舉例來說：" + +#: ../../library/functions.rst:938 +msgid "" +"If you want to convert an integer number to an uppercase or lower " +"hexadecimal string with prefix or not, you can use either of the following " +"ways:" +msgstr "" +"如果要將整數轉換為大寫或小寫的十六進位制字串，並可選擇有無 \"0x\" 前綴，則可" +"以使用如下方法：" + +#: ../../library/functions.rst:950 +msgid "" +"See also :func:`int` for converting a hexadecimal string to an integer using " +"a base of 16." +msgstr "另請參閱 :func:`int` 將十六進位制字串轉換為以 16 為基數的整數。" + +#: ../../library/functions.rst:955 +msgid "" +"To obtain a hexadecimal string representation for a float, use the :meth:" +"`float.hex` method." +msgstr "" +"如果要取得浮點數的十六進位制字串形式，請使用 :meth:`float.hex` method。" + +#: ../../library/functions.rst:961 +msgid "" +"Return the \"identity\" of an object. This is an integer which is " +"guaranteed to be unique and constant for this object during its lifetime. " +"Two objects with non-overlapping lifetimes may have the same :func:`id` " +"value." +msgstr "" +"回傳物件的 \"識別性\" 。該值是一個整數，在此物件的生命週期中保證是唯一且恆定" +"的。兩個生命期不重疊的物件可能具有相同的 :func:`id` 值。" + +#: ../../library/functions.rst:966 +msgid "This is the address of the object in memory." +msgstr "這是該物件在記憶體中的位址。" + +#: ../../library/functions.rst:968 +msgid "" +"Raises an :ref:`auditing event ` ``builtins.id`` with argument " +"``id``." +msgstr "" +"引發一個附帶引數 ``id`` 的\\ :ref:`稽核事件 ` ``builtins.id``。" + +#: ../../library/functions.rst:974 +msgid "" +"If the *prompt* argument is present, it is written to standard output " +"without a trailing newline. The function then reads a line from input, " +"converts it to a string (stripping a trailing newline), and returns that. " +"When EOF is read, :exc:`EOFError` is raised. Example::" +msgstr "" +"如果有提供 *prompt* 引數，則將其寫入標準輸出，末尾不帶換行符。接下來，該函式" +"從輸入中讀取一行，將其轉換為字串（去除末尾的換行符）並回傳。當讀取到 EOF 時，" +"則引發 :exc:`EOFError`。例如： ::" + +#: ../../library/functions.rst:979 +msgid "" +">>> s = input('--> ')\n" +"--> Monty Python's Flying Circus\n" +">>> s\n" +"\"Monty Python's Flying Circus\"" +msgstr "" +">>> s = input('--> ')\n" +"--> Monty Python's Flying Circus\n" +">>> s\n" +"\"Monty Python's Flying Circus\"" + +#: ../../library/functions.rst:984 +msgid "" +"If the :mod:`readline` module was loaded, then :func:`input` will use it to " +"provide elaborate line editing and history features." +msgstr "" +"如果載入了 :mod:`readline` module，:func:`input` 將使用它來提供複雜的行編輯和" +"歷史記錄功能。" + +#: ../../library/functions.rst:987 ../../library/functions.rst:989 +msgid "" +"Raises an :ref:`auditing event ` ``builtins.input`` with argument " +"``prompt`` before reading input" +msgstr "" +"引發一個附帶讀取輸入前的引數 ``prompt`` 的\\ :ref:`稽核事件 ` " +"``builtins.input``。" + +#: ../../library/functions.rst:992 ../../library/functions.rst:994 +msgid "" +"Raises an :ref:`auditing event ` ``builtins.input/result`` with " +"the result after successfully reading input." +msgstr "" +"引發一個附帶成功讀取結果的\\ :ref:`稽核事件 ` ``builtins.input/" +"result``。" + +#: ../../library/functions.rst:1001 +msgid "" +"Return an integer object constructed from a number or a string, or return " +"``0`` if no arguments are given." +msgstr "" + +#: ../../library/functions.rst:1006 +msgid "" +">>> int(123.45)\n" +"123\n" +">>> int('123')\n" +"123\n" +">>> int(' -12_345\\n')\n" +"-12345\n" +">>> int('FACE', 16)\n" +"64206\n" +">>> int('0xface', 0)\n" +"64206\n" +">>> int('01110011', base=2)\n" +"115" +msgstr "" +">>> int(123.45)\n" +"123\n" +">>> int('123')\n" +"123\n" +">>> int(' -12_345\\n')\n" +"-12345\n" +">>> int('FACE', 16)\n" +"64206\n" +">>> int('0xface', 0)\n" +"64206\n" +">>> int('01110011', base=2)\n" +"115" + +#: ../../library/functions.rst:1021 +msgid "" +"If the argument defines :meth:`~object.__int__`, ``int(x)`` returns ``x." +"__int__()``. If the argument defines :meth:`~object.__index__`, it returns " +"``x.__index__()``. For floating-point numbers, this truncates towards zero." +msgstr "" +"如果引數定義了 :meth:`~object.__int__`，則 ``int(x)`` 會回傳 ``x." +"__int__()``。如果引數定義了 :meth:`~object.__index__` 則回傳 ``x." +"__index__()``。對於浮點數，則會向零的方向無條件捨去。" + +#: ../../library/functions.rst:1026 +msgid "" +"If the argument is not a number or if *base* is given, then it must be a " +"string, :class:`bytes`, or :class:`bytearray` instance representing an " +"integer in radix *base*. Optionally, the string can be preceded by ``+`` or " +"``-`` (with no space in between), have leading zeros, be surrounded by " +"whitespace, and have single underscores interspersed between digits." +msgstr "" +"如果引數不是數字或如果有給定 *base*，則它必須是個字串、:class:`bytes` 或 :" +"class:`bytearray` 實例，表示基數 (radix) *base* 中的整數。可選地，字串之前可" +"以有 ``+`` 或 ``-``\\ （中間沒有空格）、可有個前導的零、也可被空格包圍、或在" +"數字間有單一底線。" + +#: ../../library/functions.rst:1032 +msgid "" +"A base-n integer string contains digits, each representing a value from 0 to " +"n-1. The values 0--9 can be represented by any Unicode decimal digit. The " +"values 10--35 can be represented by ``a`` to ``z`` (or ``A`` to ``Z``). The " +"default *base* is 10. The allowed bases are 0 and 2--36. Base-2, -8, and -16 " +"strings can be optionally prefixed with ``0b``/``0B``, ``0o``/``0O``, or " +"``0x``/``0X``, as with integer literals in code. For base 0, the string is " +"interpreted in a similar way to an :ref:`integer literal in code " +"`, in that the actual base is 2, 8, 10, or 16 as determined by the " +"prefix. Base 0 also disallows leading zeros: ``int('010', 0)`` is not legal, " +"while ``int('010')`` and ``int('010', 8)`` are." +msgstr "" +"一個 n 進制的整數字串，包含各個代表 0 到 n-1 的數字，0–9 可以用任何 Unicode " +"十進制數字表示，10–35 可以用 ``a`` 到 ``z``\\ （或 ``A`` 到 ``Z``\\ ）表示。" +"預設的 *base* 是 10。允許的進位制有 0、2–36。2、8、16 進位制的字串可以在程式" +"碼中用 ``0b``/``0B``、``0o``/``0O``、``0x``/``0X`` 前綴來表示，如同程式碼中的" +"整數文字。進位制為 0 的字串將以和\\ :ref:`程式碼整數字面值 (integer literal " +"in code) ` 類似的方式來直譯，最後由前綴決定的結果會是 2、8、10、16 " +"進制中的一個，所以 ``int('010', 0)`` 是非法的，但 ``int('010')`` 和 " +"``int('010', 8)`` 是有效的。" + +#: ../../library/functions.rst:1043 +msgid "The integer type is described in :ref:`typesnumeric`." +msgstr "整數型別定義請參閱\\ :ref:`typesnumeric`。" + +#: ../../library/functions.rst:1045 +msgid "" +"If *base* is not an instance of :class:`int` and the *base* object has a :" +"meth:`base.__index__ ` method, that method is called to " +"obtain an integer for the base. Previous versions used :meth:`base.__int__ " +"` instead of :meth:`base.__index__ `." +msgstr "" +"如果 *base* 不是 :class:`int` 的實例，但 *base* 物件有 :meth:`base.__index__ " +"` method，則會呼叫該 method 來取得此進位制所需的整數。以前" +"的版本使用 :meth:`base.__int__ ` 而不是 :meth:`base." +"__index__ `。" + +#: ../../library/functions.rst:1055 +msgid "The first parameter is now positional-only." +msgstr "第一個參數為僅限位置參數。" + +#: ../../library/functions.rst:1058 +msgid "" +"Falls back to :meth:`~object.__index__` if :meth:`~object.__int__` is not " +"defined." +msgstr "" +"如果未定義 :meth:`~object.__int__` 則會回退到 :meth:`~object.__index__`。" + +#: ../../library/functions.rst:1061 +msgid "" +":class:`int` string inputs and string representations can be limited to help " +"avoid denial of service attacks. A :exc:`ValueError` is raised when the " +"limit is exceeded while converting a string to an :class:`int` or when " +"converting an :class:`int` into a string would exceed the limit. See the :" +"ref:`integer string conversion length limitation ` " +"documentation." +msgstr "" +":class:`int` 的字串輸入和字串表示法可以被限制，以避免阻斷服務攻擊 (denial of " +"service attack)。在字串 *x* 轉換為 :class:`int` 時已超出限制，或是在 :class:" +"`int` 轉換為字串時將會超出限制時，會引發 :exc:`ValueError`。請參閱\\ :ref:`整" +"數字串轉換的長度限制 `\\ 說明文件。" + +#: ../../library/functions.rst:1069 +msgid "" +":func:`int` no longer delegates to the :meth:`~object.__trunc__` method." +msgstr ":func:`int` 不再委派給 :meth:`~object.__trunc__` method。" + +#: ../../library/functions.rst:1074 +msgid "" +"Return ``True`` if the *object* argument is an instance of the *classinfo* " +"argument, or of a (direct, indirect, or :term:`virtual `) subclass thereof. If *object* is not an object of the given type, " +"the function always returns ``False``. If *classinfo* is a tuple of type " +"objects (or recursively, other such tuples) or a :ref:`types-union` of " +"multiple types, return ``True`` if *object* is an instance of any of the " +"types. If *classinfo* is not a type or tuple of types and such tuples, a :" +"exc:`TypeError` exception is raised. :exc:`TypeError` may not be raised for " +"an invalid type if an earlier check succeeds." +msgstr "" +"如果 *object* 引數是 *classinfo* 引數的實例，或者是（直接、間接或 :term:" +"`virtual `）subclass 的實例，則回傳 ``True``。如果 " +"*object* 不是給定型別的物件，函式始終回傳 ``False``。如果 *classinfo* 是包含" +"物件型別的 tuple（或多個遞迴 tuple）或一個包含多種型別的 :ref:`types-union`，" +"若 *object* 是其中的任何一個物件的實例則回傳 ``True``。如果 *classinfo* 既不" +"是型別，也不是型別 tuple 或型別的遞迴 tuple，那麼會引發 :exc:`TypeError` 異" +"常。若是先前檢查已經成功，:exc:`TypeError` 可能不會再因為不合格的型別而被引" +"發。" + +#: ../../library/functions.rst:1085 ../../library/functions.rst:1099 +msgid "*classinfo* can be a :ref:`types-union`." +msgstr "*classinfo* 可以是一個 :ref:`types-union`。" + +#: ../../library/functions.rst:1091 +msgid "" +"Return ``True`` if *class* is a subclass (direct, indirect, or :term:" +"`virtual `) of *classinfo*. A class is considered a " +"subclass of itself. *classinfo* may be a tuple of class objects (or " +"recursively, other such tuples) or a :ref:`types-union`, in which case " +"return ``True`` if *class* is a subclass of any entry in *classinfo*. In " +"any other case, a :exc:`TypeError` exception is raised." +msgstr "" +"如果 *class* 是 *classinfo* 的 subclass（直接、間接或 :term:`virtual " +"`），則回傳 ``True``。*classinfo* 可以是 class 物件的 " +"tuple（或遞迴地其他類似 tuple）或是一個 :ref:`types-union`，此時若 *class* " +"是 *classinfo* 中任一元素的 subclass 時則回傳 ``True``。其他情況，會引發 :" +"exc:`TypeError`。" + +#: ../../library/functions.rst:1106 +msgid "" +"Return an :term:`iterator` object. The first argument is interpreted very " +"differently depending on the presence of the second argument. Without a " +"second argument, the single argument must be a collection object which " +"supports the :term:`iterable` protocol (the :meth:`~object.__iter__` " +"method), or it must support the sequence protocol (the :meth:`~object." +"__getitem__` method with integer arguments starting at ``0``). If it does " +"not support either of those protocols, :exc:`TypeError` is raised. If the " +"second argument, *sentinel*, is given, then the first argument must be a " +"callable object. The iterator created in this case will call *callable* " +"with no arguments for each call to its :meth:`~iterator.__next__` method; if " +"the value returned is equal to *sentinel*, :exc:`StopIteration` will be " +"raised, otherwise the value will be returned." +msgstr "" +"回傳一個 :term:`iterator` 物件。根據是否存在第二個引數，第一個引數的意義是非" +"常不同的。如果沒有第二個引數，該單一引數必須是支援 :term:`iterable` 協定" +"（有 :meth:`~object.__iter__` method）的集合物件，或必須支援序列協定（有 :" +"meth:`~object.__getitem__` 方法，且數字引數從 ``0`` 開始）。如果它不支援這些" +"協定，會引發 :exc:`TypeError`。如果有第二個引數 *sentinel*，那麼第一引數必須" +"是可呼叫的物件，這種情況下生成的 iterator，每次疊代呼叫 :meth:`~iterator." +"__next__` 時會不帶引數地呼叫 *callable*；如果回傳的結果是 *sentinel* 則引發 :" +"exc:`StopIteration`，否則回傳呼叫結果。" + +#: ../../library/functions.rst:1120 +msgid "See also :ref:`typeiter`." +msgstr "另請參閱 :ref:`typeiter`。" + +#: ../../library/functions.rst:1122 +msgid "" +"One useful application of the second form of :func:`iter` is to build a " +"block-reader. For example, reading fixed-width blocks from a binary database " +"file until the end of file is reached::" +msgstr "" +":func:`iter` 的第二種形式有一個好用的應用，是能夠建立一個區塊閱讀器 (block-" +"reader)。例如，從二進位資料庫檔案中讀取固定寬度的區塊，直到檔案的結尾： ::" + +#: ../../library/functions.rst:1126 +msgid "" +"from functools import partial\n" +"with open('mydata.db', 'rb') as f:\n" +" for block in iter(partial(f.read, 64), b''):\n" +" process_block(block)" +msgstr "" +"from functools import partial\n" +"with open('mydata.db', 'rb') as f:\n" +" for block in iter(partial(f.read, 64), b''):\n" +" process_block(block)" + +#: ../../library/functions.rst:1134 +msgid "" +"Return the length (the number of items) of an object. The argument may be a " +"sequence (such as a string, bytes, tuple, list, or range) or a collection " +"(such as a dictionary, set, or frozen set)." +msgstr "" +"回傳物件的長度（元素個數）。引數可以是序列（如 string、bytes、tuple、list 或 " +"range）或集合（如 dictionary、set 或 frozen set）。" + +#: ../../library/functions.rst:1140 +msgid "" +"``len`` raises :exc:`OverflowError` on lengths larger than :data:`sys." +"maxsize`, such as :class:`range(2 ** 100) `." +msgstr "" +"如果物件長度大於 :data:`sys.maxsize`，像是 :class:`range(2 ** 100) `，" +"則 ``len`` 會引發 :exc:`OverflowError`。" + +#: ../../library/functions.rst:1148 +msgid "" +"Rather than being a function, :class:`list` is actually a mutable sequence " +"type, as documented in :ref:`typesseq-list` and :ref:`typesseq`." +msgstr "" +"除了是函式，:class:`list` 也是可變序列型別，詳情請參閱 :ref:`typesseq-list` " +"和 :ref:`typesseq`。" + +#: ../../library/functions.rst:1154 +msgid "" +"Return a mapping object representing the current local symbol table, with " +"variable names as the keys, and their currently bound references as the " +"values." +msgstr "" + +#: ../../library/functions.rst:1158 +msgid "" +"At module scope, as well as when using :func:`exec` or :func:`eval` with a " +"single namespace, this function returns the same namespace as :func:" +"`globals`." +msgstr "" + +#: ../../library/functions.rst:1162 +msgid "" +"At class scope, it returns the namespace that will be passed to the " +"metaclass constructor." +msgstr "" + +#: ../../library/functions.rst:1165 +msgid "" +"When using ``exec()`` or ``eval()`` with separate local and global " +"arguments, it returns the local namespace passed in to the function call." +msgstr "" + +#: ../../library/functions.rst:1168 +msgid "" +"In all of the above cases, each call to ``locals()`` in a given frame of " +"execution will return the *same* mapping object. Changes made through the " +"mapping object returned from ``locals()`` will be visible as assigned, " +"reassigned, or deleted local variables, and assigning, reassigning, or " +"deleting local variables will immediately affect the contents of the " +"returned mapping object." +msgstr "" + +#: ../../library/functions.rst:1175 +msgid "" +"In an :term:`optimized scope` (including functions, generators, and " +"coroutines), each call to ``locals()`` instead returns a fresh dictionary " +"containing the current bindings of the function's local variables and any " +"nonlocal cell references. In this case, name binding changes made via the " +"returned dict are *not* written back to the corresponding local variables or " +"nonlocal cell references, and assigning, reassigning, or deleting local " +"variables and nonlocal cell references does *not* affect the contents of " +"previously returned dictionaries." +msgstr "" + +#: ../../library/functions.rst:1184 +msgid "" +"Calling ``locals()`` as part of a comprehension in a function, generator, or " +"coroutine is equivalent to calling it in the containing scope, except that " +"the comprehension's initialised iteration variables will be included. In " +"other scopes, it behaves as if the comprehension were running as a nested " +"function." +msgstr "" + +#: ../../library/functions.rst:1190 +msgid "" +"Calling ``locals()`` as part of a generator expression is equivalent to " +"calling it in a nested generator function." +msgstr "" + +#: ../../library/functions.rst:1193 +msgid "" +"The behaviour of ``locals()`` in a comprehension has been updated as " +"described in :pep:`709`." +msgstr "" + +#: ../../library/functions.rst:1197 +msgid "" +"As part of :pep:`667`, the semantics of mutating the mapping objects " +"returned from this function are now defined. The behavior in :term:" +"`optimized scopes ` is now as described above. Aside from " +"being defined, the behaviour in other scopes remains unchanged from previous " +"versions." +msgstr "" + +#: ../../library/functions.rst:1207 +msgid "" +"Return an iterator that applies *function* to every item of *iterable*, " +"yielding the results. If additional *iterables* arguments are passed, " +"*function* must take that many arguments and is applied to the items from " +"all iterables in parallel. With multiple iterables, the iterator stops when " +"the shortest iterable is exhausted. If *strict* is ``True`` and one of the " +"iterables is exhausted before the others, a :exc:`ValueError` is raised. For " +"cases where the function inputs are already arranged into argument tuples, " +"see :func:`itertools.starmap`." +msgstr "" +"產生一個將 *function* 應用於 *iterable* 中所有項目並 yield 回傳結果的疊代器。" +"如果傳遞了額外的 *iterables* 引數，則 *function* 必須接受相同個數的引數，且 " +"*function* 會平行地被應用於所有可疊代物件的項目。當有多個可疊代物件時，項目最" +"少的可疊代物件耗盡時疊代器也會結束。如果 *strict* 為 ``True`` 且其中一個可疊" +"代物件在其他可疊代物件之前耗盡，則會拋出 :exc:`ValueError`。如果函式的輸入已" +"經被編排為引數的元組，請參閱 :func:`itertools.starmap`。" + +#: ../../library/functions.rst:1216 +msgid "Added the *strict* parameter." +msgstr "增加了 *strict* 參數。" + +#: ../../library/functions.rst:1224 +msgid "" +"Return the largest item in an iterable or the largest of two or more " +"arguments." +msgstr "回傳 iterable 中最大的元素，或者回傳兩個以上的引數中最大的。" + +#: ../../library/functions.rst:1227 +msgid "" +"If one positional argument is provided, it should be an :term:`iterable`. " +"The largest item in the iterable is returned. If two or more positional " +"arguments are provided, the largest of the positional arguments is returned." +msgstr "" +"如果只提供了一個位置引數，它必須是個 :term:`iterable`，iterable 中最大的元素" +"會被回傳。如果提供了兩個或以上的位置引數，則回傳最大的位置引數。" + +#: ../../library/functions.rst:1232 ../../library/functions.rst:1270 +msgid "" +"There are two optional keyword-only arguments. The *key* argument specifies " +"a one-argument ordering function like that used for :meth:`list.sort`. The " +"*default* argument specifies an object to return if the provided iterable is " +"empty. If the iterable is empty and *default* is not provided, a :exc:" +"`ValueError` is raised." +msgstr "" +"這個函式有兩個選擇性的僅限關鍵字引數。*key* 引數能指定單一引數所使用的排序函" +"式，如同 :meth:`list.sort` 的使用方式。*default* 引數是當 iterable 為空時回傳" +"的物件。如果 iterable 為空，並且沒有提供 *default*，則會引發 :exc:" +"`ValueError`。" + +#: ../../library/functions.rst:1238 +msgid "" +"If multiple items are maximal, the function returns the first one " +"encountered. This is consistent with other sort-stability preserving tools " +"such as ``sorted(iterable, key=keyfunc, reverse=True)[0]`` and ``heapq." +"nlargest(1, iterable, key=keyfunc)``." +msgstr "" +"如果有多個最大元素，則此函式將回傳第一個找到的。這和其他穩定排序工具如 " +"``sorted(iterable, key=keyfunc, reverse=True)[0]`` 和 ``heapq.nlargest(1, " +"iterable, key=keyfunc)`` 一致。" + +#: ../../library/functions.rst:1243 ../../library/functions.rst:1281 +msgid "Added the *default* keyword-only parameter." +msgstr "新增 *default* 僅限關鍵字參數。" + +#: ../../library/functions.rst:1246 ../../library/functions.rst:1284 +msgid "The *key* can be ``None``." +msgstr "*key* 可以為 ``None``。" + +#: ../../library/functions.rst:1254 +msgid "" +"Return a \"memory view\" object created from the given argument. See :ref:" +"`typememoryview` for more information." +msgstr "" +"回傳由給定的引數所建立之「memory view（記憶體檢視）」物件。有關詳細資訊，請參" +"閱\\ :ref:`typememoryview`。" + +#: ../../library/functions.rst:1262 +msgid "" +"Return the smallest item in an iterable or the smallest of two or more " +"arguments." +msgstr "回傳 iterable 中最小的元素，或者回傳兩個以上的引數中最小的。" + +#: ../../library/functions.rst:1265 +msgid "" +"If one positional argument is provided, it should be an :term:`iterable`. " +"The smallest item in the iterable is returned. If two or more positional " +"arguments are provided, the smallest of the positional arguments is returned." +msgstr "" +"如果只提供了一個位置引數，它必須是 :term:`iterable`，iterable 中最小的元素會" +"被回傳。如果提供了兩個以上的位置引數，則回傳最小的位置引數。" + +#: ../../library/functions.rst:1276 +msgid "" +"If multiple items are minimal, the function returns the first one " +"encountered. This is consistent with other sort-stability preserving tools " +"such as ``sorted(iterable, key=keyfunc)[0]`` and ``heapq.nsmallest(1, " +"iterable, key=keyfunc)``." +msgstr "" +"如果有多個最小元素，則此函式將回傳第一個找到的。這和其他穩定排序工具如 " +"``sorted(iterable, key=keyfunc)[0]`` 和 ``heapq.nsmallest(1, iterable, " +"key=keyfunc)`` 一致。" + +#: ../../library/functions.rst:1291 +msgid "" +"Retrieve the next item from the :term:`iterator` by calling its :meth:" +"`~iterator.__next__` method. If *default* is given, it is returned if the " +"iterator is exhausted, otherwise :exc:`StopIteration` is raised." +msgstr "" +"透過呼叫 :term:`iterator` 的 :meth:`~iterator.__next__` method 取得下一個元" +"素。如果 iterator 耗盡，則回傳給定的預設值 *default*，如果沒有預設值則引發 :" +"exc:`StopIteration`。" + +#: ../../library/functions.rst:1298 +msgid "" +"This is the ultimate base class of all other classes. It has methods that " +"are common to all instances of Python classes. When the constructor is " +"called, it returns a new featureless object. The constructor does not accept " +"any arguments." +msgstr "" +"這是所有其他 class 的基礎，它具有所有 Python class 實例的通用 method。當建構" +"函式被呼叫時，它會回傳一個新的沒有特徵 (featureless) 的物件。這個建構函式不接" +"受任何引數。" + +#: ../../library/functions.rst:1305 +msgid "" +":class:`object` instances do *not* have :attr:`~object.__dict__` attributes, " +"so you can't assign arbitrary attributes to an instance of :class:`object`." +msgstr "" +"由於 :class:`object` 實例\\ *沒有* :attr:`~object.__dict__` 屬性，因此無法將" +"任意屬性賦給 :class:`object` 的實例。" + +#: ../../library/functions.rst:1312 +msgid "" +"Convert an integer number to an octal string prefixed with \"0o\". The " +"result is a valid Python expression. If *integer* is not a Python :class:" +"`int` object, it has to define an :meth:`~object.__index__` method that " +"returns an integer. For example:" +msgstr "" +"將一個整數轉變為一個前綴為 \"0o\" 的八進位制字串。回傳結果是一個有效的 " +"Python 運算式。如果 *integer* 不是 Python 的 :class:`int` 物件，那它需要定" +"義 :meth:`~object.__index__` method 回傳一個整數。舉例來說：" + +#: ../../library/functions.rst:1322 +msgid "" +"If you want to convert an integer number to an octal string either with the " +"prefix \"0o\" or not, you can use either of the following ways." +msgstr "" +"如果要將整數轉換為八進位制字串，不論是否具備 \"0o\" 前綴，都可以使用下面的方" +"法。" + +#: ../../library/functions.rst:1339 +msgid "" +"Open *file* and return a corresponding :term:`file object`. If the file " +"cannot be opened, an :exc:`OSError` is raised. See :ref:`tut-files` for more " +"examples of how to use this function." +msgstr "" +"開啟 *file* 並回傳對應的\\ :term:`檔案物件 `。如果該檔案不能開" +"啟，則引發 :exc:`OSError`。關於使用此函式的更多方法，請參閱\\ :ref:`tut-" +"files`。" + +#: ../../library/functions.rst:1343 +msgid "" +"*file* is a :term:`path-like object` giving the pathname (absolute or " +"relative to the current working directory) of the file to be opened or an " +"integer file descriptor of the file to be wrapped. (If a file descriptor is " +"given, it is closed when the returned I/O object is closed unless *closefd* " +"is set to ``False``.)" +msgstr "" +"*file* 是一個\\ :term:`類路徑物件 `，是將被開啟之檔案的路徑" +"（絕對路徑或目前工作目錄的相對路徑），或是要被包裝 (wrap) 檔案的整數檔案描述" +"器 (file descriptor)。（如果有給定檔案描述器，它會隨著回傳的 I/O 物件關閉而關" +"閉，除非 *closefd* 被設為 ``False``。）" + +#: ../../library/functions.rst:1349 +msgid "" +"*mode* is an optional string that specifies the mode in which the file is " +"opened. It defaults to ``'r'`` which means open for reading in text mode. " +"Other common values are ``'w'`` for writing (truncating the file if it " +"already exists), ``'x'`` for exclusive creation, and ``'a'`` for appending " +"(which on *some* Unix systems, means that *all* writes append to the end of " +"the file regardless of the current seek position). In text mode, if " +"*encoding* is not specified the encoding used is platform-dependent: :func:" +"`locale.getencoding` is called to get the current locale encoding. (For " +"reading and writing raw bytes use binary mode and leave *encoding* " +"unspecified.) The available modes are:" +msgstr "" +"*mode* 是一個選擇性字串，用於指定開啟檔案的模式。預設值是 ``'r'``，這意味著它" +"以文字模式開啟並讀取。其他常見模式有：寫入 ``'w'``\\ （會捨去已經存在的檔" +"案）、唯一性建立 ``'x'``、追加寫入 ``'a'``\\ （在\\ *一些* Unix 系統上，無論" +"目前的檔案指標在什麼位置，*所有* 寫入都會追加到檔案末尾）。在文字模式，如果沒" +"有指定 *encoding*，則根據電腦平臺來決定使用的編碼：呼叫 :func:`locale." +"getencoding` 來取得目前的本地編碼。（要讀取和寫入原始 bytes，請使用二進位制模" +"式且不要指定 *encoding*。）可用的模式有：" + +#: ../../library/functions.rst:1366 +msgid "Character" +msgstr "字元" + +#: ../../library/functions.rst:1366 +msgid "Meaning" +msgstr "意義" + +#: ../../library/functions.rst:1368 +msgid "``'r'``" +msgstr "``'r'``" + +#: ../../library/functions.rst:1368 +msgid "open for reading (default)" +msgstr "讀取（預設）" + +#: ../../library/functions.rst:1369 +msgid "``'w'``" +msgstr "``'w'``" + +#: ../../library/functions.rst:1369 +msgid "open for writing, truncating the file first" +msgstr "寫入，會先清除檔案內容" + +#: ../../library/functions.rst:1370 +msgid "``'x'``" +msgstr "``'x'``" + +#: ../../library/functions.rst:1370 +msgid "open for exclusive creation, failing if the file already exists" +msgstr "唯一性建立，如果文件已存在則會失敗" + +#: ../../library/functions.rst:1371 +msgid "``'a'``" +msgstr "``'a'``" + +#: ../../library/functions.rst:1371 +msgid "open for writing, appending to the end of file if it exists" +msgstr "寫入，如果檔案存在則在其末端附加內容" + +#: ../../library/functions.rst:1372 +msgid "``'b'``" +msgstr "``'b'``" + +#: ../../library/functions.rst:1372 ../../library/functions.rst:1516 +msgid "binary mode" +msgstr "二進制模式" + +#: ../../library/functions.rst:1373 +msgid "``'t'``" +msgstr "``'t'``" + +#: ../../library/functions.rst:1373 +msgid "text mode (default)" +msgstr "文字模式（預設）" + +#: ../../library/functions.rst:1374 +msgid "``'+'``" +msgstr "``'+'``" + +#: ../../library/functions.rst:1374 +msgid "open for updating (reading and writing)" +msgstr "更新（讀取並寫入）" + +#: ../../library/functions.rst:1377 +msgid "" +"The default mode is ``'r'`` (open for reading text, a synonym of ``'rt'``). " +"Modes ``'w+'`` and ``'w+b'`` open and truncate the file. Modes ``'r+'`` and " +"``'r+b'`` open the file with no truncation." +msgstr "" +"預設的模式是 ``'r'``\\ （開啟並讀取文字，同 ``'rt'``）。``'w+'`` 和 " +"``'w+b'`` 模式會開啟並清除檔案。``'r+'`` 和 ``'r+b'`` 模式會開啟且保留檔案內" +"容。" + +#: ../../library/functions.rst:1381 +msgid "" +"As mentioned in the :ref:`io-overview`, Python distinguishes between binary " +"and text I/O. Files opened in binary mode (including ``'b'`` in the *mode* " +"argument) return contents as :class:`bytes` objects without any decoding. " +"In text mode (the default, or when ``'t'`` is included in the *mode* " +"argument), the contents of the file are returned as :class:`str`, the bytes " +"having been first decoded using a platform-dependent encoding or using the " +"specified *encoding* if given." +msgstr "" +"如\\ :ref:`io-overview`\\ 中所述，Python 能區分二進制和文字的 I/O。在二進制模" +"式下開啟的檔案（*mode* 引數中含有 ``'b'``）會將其內容以 :class:`bytes` 物件回" +"傳，而不進行任何解碼。在文字模式（預設情況，或當 *mode* 引數中含有 " +"``'t'``），檔案的內容會以 :class:`str` 回傳，其位元組已經先被解碼，使用的是取" +"決於平台的編碼系統或是給定的 *encoding*。" + +#: ../../library/functions.rst:1391 +msgid "" +"Python doesn't depend on the underlying operating system's notion of text " +"files; all the processing is done by Python itself, and is therefore " +"platform-independent." +msgstr "" +"Python 不會使用底層作業系統對於文字檔案的操作概念；所有的處理都是由 Python 獨" +"自完成的，因此能獨立於不同平台。" + +#: ../../library/functions.rst:1395 +msgid "" +"*buffering* is an optional integer used to set the buffering policy. Pass 0 " +"to switch buffering off (only allowed in binary mode), 1 to select line " +"buffering (only usable when writing in text mode), and an integer > 1 to " +"indicate the size in bytes of a fixed-size chunk buffer. Note that " +"specifying a buffer size this way applies for binary buffered I/O, but " +"``TextIOWrapper`` (i.e., files opened with ``mode='r+'``) would have another " +"buffering. To disable buffering in ``TextIOWrapper``, consider using the " +"``write_through`` flag for :func:`io.TextIOWrapper.reconfigure`. When no " +"*buffering* argument is given, the default buffering policy works as follows:" +msgstr "" +"*buffering* 是一個選擇性的整數，用於設定緩衝策略。傳入 0 表示關閉緩衝（僅在二" +"進制模式下被允許），1 表示行緩衝（line buffering，僅在文字模式下可用），而 " +">1 的整數是指示一個大小固定的區塊緩衝區 (chunk buffer)，其位元組的數量。請注" +"意，此類指定緩衝區大小的方式適用於二進制緩衝 I/O，但是 ``TextIOWrapper``\\ " +"（以 ``mode='r+'`` 開啟的檔案）會有另一種緩衝方式。若要在 ``TextIOWrapper`` " +"中停用緩衝，可考慮使用 :func:`io.TextIOWrapper.reconfigure` 的 " +"``write_through`` 旗標。若未給定 *buffering* 引數，則預設的緩衝策略會運作如" +"下：" + +#: ../../library/functions.rst:1405 +msgid "" +"Binary files are buffered in fixed-size chunks; the size of the buffer is " +"``max(min(blocksize, 8 MiB), DEFAULT_BUFFER_SIZE)`` when the device block " +"size is available. On most systems, the buffer will typically be 128 " +"kilobytes long." +msgstr "" +"二進位檔案會以固定大小的區塊進行緩衝；緩衝區的大小為 ``max(min(blocksize, 8 " +"MiB), DEFAULT_BUFFER_SIZE)``，當裝置區塊大小可用時。在大多數系統上，緩衝區的" +"長度通常為 128 KB。" + +#: ../../library/functions.rst:1410 +msgid "" +"\"Interactive\" text files (files for which :meth:`~io.IOBase.isatty` " +"returns ``True``) use line buffering. Other text files use the policy " +"described above for binary files." +msgstr "" +"「互動式」文字檔（:meth:`~io.IOBase.isatty` 回傳 ``True`` 的檔案）會使用列緩" +"衝。其他文字檔則使用上述的二進制檔案緩衝策略。" + +#: ../../library/functions.rst:1414 +msgid "" +"*encoding* is the name of the encoding used to decode or encode the file. " +"This should only be used in text mode. The default encoding is platform " +"dependent (whatever :func:`locale.getencoding` returns), but any :term:`text " +"encoding` supported by Python can be used. See the :mod:`codecs` module for " +"the list of supported encodings." +msgstr "" +"*encoding* 是用於解碼或編碼檔案的編碼系統之名稱。它只應該在文字模式下使用。預" +"設的編碼系統會取決於平台（根據 :func:`locale.getencoding` 回傳的內容），但 " +"Python 支援的任何 :term:`text encoding`\\ （文字編碼）都是可以使用的。關於支" +"援的編碼系統清單，請參閱 :mod:`codecs` module。" + +#: ../../library/functions.rst:1420 +msgid "" +"*errors* is an optional string that specifies how encoding and decoding " +"errors are to be handled—this cannot be used in binary mode. A variety of " +"standard error handlers are available (listed under :ref:`error-handlers`), " +"though any error handling name that has been registered with :func:`codecs." +"register_error` is also valid. The standard names include:" +msgstr "" +"*errors* 是一個選擇性的字串，用於指定要如何處理編碼和解碼的錯誤——它不能在二進" +"制模式下使用。有許多不同的標準錯誤處理程式（error handler，在\\ :ref:`error-" +"handlers`\\ 有列出清單），不過任何已註冊到 :func:`codecs.register_error` 的錯" +"誤處理程式名稱也都是有效的。標準的名稱包括：" + +#: ../../library/functions.rst:1428 +msgid "" +"``'strict'`` to raise a :exc:`ValueError` exception if there is an encoding " +"error. The default value of ``None`` has the same effect." +msgstr "" +"``'strict'`` 如果發生編碼錯誤，則引發 :exc:`ValueError` 例外。預設值 " +"``None`` 也有相同的效果。" + +#: ../../library/functions.rst:1432 +msgid "" +"``'ignore'`` ignores errors. Note that ignoring encoding errors can lead to " +"data loss." +msgstr "``'ignore'`` 忽略錯誤。請注意，忽略編碼錯誤可能導致資料遺失。" + +#: ../../library/functions.rst:1435 +msgid "" +"``'replace'`` causes a replacement marker (such as ``'?'``) to be inserted " +"where there is malformed data." +msgstr "" +"``'replace'`` 會在格式不正確的資料位置插入一個替換標誌（像是 ``'?'``）。" + +#: ../../library/functions.rst:1438 +msgid "" +"``'surrogateescape'`` will represent any incorrect bytes as low surrogate " +"code units ranging from U+DC80 to U+DCFF. These surrogate code units will " +"then be turned back into the same bytes when the ``surrogateescape`` error " +"handler is used when writing data. This is useful for processing files in " +"an unknown encoding." +msgstr "" +"``'surrogateescape'`` 會將任何不正確的位元組表示為低位代理碼元 (low " +"surrogate code unit)，範圍從 U+DC80 到 U+DCFF。在寫入資料時，這些代理碼元將會" +"被還原回 ``surrogateescape`` 錯誤處理程式當時所處理的那些相同位元組。這對於處" +"理未知編碼方式的檔案會很好用。" + +#: ../../library/functions.rst:1445 +msgid "" +"``'xmlcharrefreplace'`` is only supported when writing to a file. Characters " +"not supported by the encoding are replaced with the appropriate XML " +"character reference :samp:`&#{nnn};`." +msgstr "" +"``'xmlcharrefreplace'`` 僅在寫入檔案時可支援。編碼系統不支援的字元會被替換為" +"適當的 XML 字元參考 (character reference) ``&#nnn;``。" + +#: ../../library/functions.rst:1449 +msgid "" +"``'backslashreplace'`` replaces malformed data by Python's backslashed " +"escape sequences." +msgstr "" +"``'backslashreplace'`` 會用 Python 的反斜線跳脫序列 (backslashed escape " +"sequence) 替換格式不正確的資料。" + +#: ../../library/functions.rst:1452 +msgid "" +"``'namereplace'`` (also only supported when writing) replaces unsupported " +"characters with ``\\N{...}`` escape sequences." +msgstr "" +"``'namereplace'``\\ （也僅在寫入時支援）會將不支援的字元替換為 ``\\N{...}`` " +"跳脫序列。" + +#: ../../library/functions.rst:1460 +msgid "" +"*newline* determines how to parse newline characters from the stream. It can " +"be ``None``, ``''``, ``'\\n'``, ``'\\r'``, and ``'\\r\\n'``. It works as " +"follows:" +msgstr "" +"*newline* 會決定如何剖析資料串流 (stream) 中的換行字元。它可以是 ``None``、" +"``''``、``'\\n'``、``'\\r'`` 或 ``'\\r\\n'``。它的運作規則如下：" + +#: ../../library/functions.rst:1464 +msgid "" +"When reading input from the stream, if *newline* is ``None``, universal " +"newlines mode is enabled. Lines in the input can end in ``'\\n'``, " +"``'\\r'``, or ``'\\r\\n'``, and these are translated into ``'\\n'`` before " +"being returned to the caller. If it is ``''``, universal newlines mode is " +"enabled, but line endings are returned to the caller untranslated. If it " +"has any of the other legal values, input lines are only terminated by the " +"given string, and the line ending is returned to the caller untranslated." +msgstr "" +"從資料串流讀取輸入時，如果 *newline* 是 ``None``，則會啟用通用換行模式。輸入" +"資料中的行結尾可以是 ``'\\n'``、``'\\r'`` 或 ``'\\r\\n'``，這些符號會被轉換" +"為 ``'\\n'`` 之後再回傳給呼叫方。如果是 ``''``，也會啟用通用換行模式，但在回" +"傳給呼叫方時，行尾符號不會被轉換。如果它是任何其他有效的值，則輸入資料的行只" +"會由給定的字串做結尾，且在回傳給呼叫方時，行尾符號不會被轉換。" + +#: ../../library/functions.rst:1472 +msgid "" +"When writing output to the stream, if *newline* is ``None``, any ``'\\n'`` " +"characters written are translated to the system default line separator, :" +"data:`os.linesep`. If *newline* is ``''`` or ``'\\n'``, no translation " +"takes place. If *newline* is any of the other legal values, any ``'\\n'`` " +"characters written are translated to the given string." +msgstr "" +"將輸出寫入資料串流時，如果 *newline* 是 ``None``，則被寫入的任何 ``'\\n'`` 字" +"元都會轉換為系統預設的行分隔符號 :data:`os.linesep`。如果 *newline* 是 " +"``''`` 或 ``'\\n'``，則不做任何轉換。如果 *newline* 是任何其他有效的值，則寫" +"入的任何 ``'\\n'`` 字元都將轉換為給定的字串。" + +#: ../../library/functions.rst:1478 +msgid "" +"If *closefd* is ``False`` and a file descriptor rather than a filename was " +"given, the underlying file descriptor will be kept open when the file is " +"closed. If a filename is given *closefd* must be ``True`` (the default); " +"otherwise, an error will be raised." +msgstr "" +"如果 *closefd* 是 ``False``，且給定的 *file* 引數是一個檔案描述器而不是檔名，" +"則當檔案關閉時，底層的檔案描述器會保持開啟狀態。如果有給定一個檔名，則 " +"*closefd* 必須是 ``True``\\ （預設值）；否則將引發錯誤。" + +#: ../../library/functions.rst:1483 +msgid "" +"A custom opener can be used by passing a callable as *opener*. The " +"underlying file descriptor for the file object is then obtained by calling " +"*opener* with (*file*, *flags*). *opener* must return an open file " +"descriptor (passing :mod:`os.open` as *opener* results in functionality " +"similar to passing ``None``)." +msgstr "" +"透過以 *opener* 傳遞一個可呼叫物件，就可以自訂開啟函式。然後透過以引數 " +"(*file*, *flags*) 呼叫 *opener*，就能取得檔案物件的底層檔案描述器。*opener* " +"必須回傳一個開啟的檔案描述器（將 :mod:`os.open` 作為 *opener* 傳入，在功能上" +"的結果會相當於傳入 ``None``）。" + +#: ../../library/functions.rst:1489 +msgid "The newly created file is :ref:`non-inheritable `." +msgstr "新建立的檔案是\\ :ref:`不可繼承的 `。" + +#: ../../library/functions.rst:1491 +msgid "" +"The following example uses the :ref:`dir_fd ` parameter of the :func:" +"`os.open` function to open a file relative to a given directory::" +msgstr "" +"下面的範例使用 :func:`os.open` 函式回傳值當作 :ref:`dir_fd ` 的參數，" +"從給定的目錄中用相對路徑開啟檔案： ::" + +#: ../../library/functions.rst:1494 +msgid "" +">>> import os\n" +">>> dir_fd = os.open('somedir', os.O_RDONLY)\n" +">>> def opener(path, flags):\n" +"... return os.open(path, flags, dir_fd=dir_fd)\n" +"...\n" +">>> with open('spamspam.txt', 'w', opener=opener) as f:\n" +"... print('This will be written to somedir/spamspam.txt', file=f)\n" +"...\n" +">>> os.close(dir_fd) # don't leak a file descriptor" +msgstr "" +">>> import os\n" +">>> dir_fd = os.open('somedir', os.O_RDONLY)\n" +">>> def opener(path, flags):\n" +"... return os.open(path, flags, dir_fd=dir_fd)\n" +"...\n" +">>> with open('spamspam.txt', 'w', opener=opener) as f:\n" +"... print('This will be written to somedir/spamspam.txt', file=f)\n" +"...\n" +">>> os.close(dir_fd) # don't leak a file descriptor" + +#: ../../library/functions.rst:1504 +msgid "" +"The type of :term:`file object` returned by the :func:`open` function " +"depends on the mode. When :func:`open` is used to open a file in a text " +"mode (``'w'``, ``'r'``, ``'wt'``, ``'rt'``, etc.), it returns a subclass of :" +"class:`io.TextIOBase` (specifically :class:`io.TextIOWrapper`). When used " +"to open a file in a binary mode with buffering, the returned class is a " +"subclass of :class:`io.BufferedIOBase`. The exact class varies: in read " +"binary mode, it returns an :class:`io.BufferedReader`; in write binary and " +"append binary modes, it returns an :class:`io.BufferedWriter`, and in read/" +"write mode, it returns an :class:`io.BufferedRandom`. When buffering is " +"disabled, the raw stream, a subclass of :class:`io.RawIOBase`, :class:`io." +"FileIO`, is returned." +msgstr "" +":func:`open` 函式回傳的 :term:`file object` 型別取決於模式。當 :func:`open` " +"是在文字模式中開啟檔案時（``'w'``、``'r'``、``'wt'``、``'rt'`` 等），它會回" +"傳 :class:`io.TextIOBase` 的一個 subclass（具體來說，就是 :class:`io." +"TextIOWrapper`）。使用有緩衝的二進制模式開啟檔案時，回傳的 class 則會是 :" +"class:`io.BufferedIOBase` 的 subclass。確切的 class 各不相同：在讀取的二進制" +"模式，它會回傳 :class:`io.BufferedReader`；在寫入和附加的二進制模式，它會回" +"傳 :class:`io.BufferedWriter`，而在讀／寫模式，它會回傳 :class:`io." +"BufferedRandom`。當緩衝被停用時，會回傳原始資料串流 :class:`io.FileIO`，它" +"是 :class:`io.RawIOBase` 的一個 subclass。" + +#: ../../library/functions.rst:1525 +msgid "" +"See also the file handling modules, such as :mod:`fileinput`, :mod:`io` " +"(where :func:`open` is declared), :mod:`os`, :mod:`os.path`, :mod:" +"`tempfile`, and :mod:`shutil`." +msgstr "" +"另請參閱檔案操作模組，例如 :mod:`fileinput`、:mod:`io`\\ （定義了 :func:" +"`open` 的 module ）、:mod:`os`、:mod:`os.path`、:mod:`tempfile` 以及 :mod:" +"`shutil`。" + +#: ../../library/functions.rst:1529 +msgid "" +"Raises an :ref:`auditing event ` ``open`` with arguments ``path``, " +"``mode``, ``flags``." +msgstr "" +"引發一個附帶引數 ``path``、``mode``、``flags`` 的\\ :ref:`稽核事件 " +"` ``open``。" + +#: ../../library/functions.rst:1531 +msgid "" +"The ``mode`` and ``flags`` arguments may have been modified or inferred from " +"the original call." +msgstr "``mode`` 和 ``flags`` 引數可能會被原始的呼叫所修改或推論 (infer)。" + +#: ../../library/functions.rst:1536 +msgid "The *opener* parameter was added." +msgstr "新增 *opener* 參數。" + +#: ../../library/functions.rst:1537 +msgid "The ``'x'`` mode was added." +msgstr "新增 ``'x'`` 模式。" + +#: ../../library/functions.rst:1538 +msgid ":exc:`IOError` used to be raised, it is now an alias of :exc:`OSError`." +msgstr "過去引發的 :exc:`IOError`，現在是 :exc:`OSError` 的別名。" + +#: ../../library/functions.rst:1539 +msgid "" +":exc:`FileExistsError` is now raised if the file opened in exclusive " +"creation mode (``'x'``) already exists." +msgstr "" +"如果檔案已存在但使用了唯一性建立模式 (``'x'``)，現在會引發 :exc:" +"`FileExistsError`。" + +#: ../../library/functions.rst:1544 +msgid "The file is now non-inheritable." +msgstr "檔案在此版本開始是不可繼承的。" + +#: ../../library/functions.rst:1548 +msgid "" +"If the system call is interrupted and the signal handler does not raise an " +"exception, the function now retries the system call instead of raising an :" +"exc:`InterruptedError` exception (see :pep:`475` for the rationale)." +msgstr "" +"如果系統呼叫被中斷，但訊號處理程式沒有引發例外，此函式現在會重試系統呼叫，而" +"不是引發 :exc:`InterruptedError` 例外（原因詳見 :pep:`475`）。" + +#: ../../library/functions.rst:1551 +msgid "The ``'namereplace'`` error handler was added." +msgstr "增加了 ``'namereplace'`` 錯誤處理程式。" + +#: ../../library/functions.rst:1555 +msgid "Support added to accept objects implementing :class:`os.PathLike`." +msgstr "增加對於實作 :class:`os.PathLike` 物件的支援。" + +#: ../../library/functions.rst:1556 +msgid "" +"On Windows, opening a console buffer may return a subclass of :class:`io." +"RawIOBase` other than :class:`io.FileIO`." +msgstr "" +"在 Windows 上，開啟一個控制臺緩衝區可能會回傳 :class:`io.RawIOBase` 的 " +"subclass，而不是 :class:`io.FileIO`。" + +#: ../../library/functions.rst:1559 +msgid "The ``'U'`` mode has been removed." +msgstr "``'U'`` 模式被移除。" + +#: ../../library/functions.rst:1564 +msgid "Return the ordinal value of a character." +msgstr "" + +#: ../../library/functions.rst:1566 +msgid "" +"If the argument is a one-character string, return the Unicode code point of " +"that character. For example, ``ord('a')`` returns the integer ``97`` and " +"``ord('€')`` (Euro sign) returns ``8364``. This is the inverse of :func:" +"`chr`." +msgstr "" +"如果引數是單字元字串，則回傳該字元的 Unicode 編碼位置。例如 ``ord('a')`` 回傳" +"整數 ``97``、``ord('€')``\\ （歐元符號）回傳 ``8364``。這是 :func:`chr` 的逆" +"函式。" + +#: ../../library/functions.rst:1571 +msgid "" +"If the argument is a :class:`bytes` or :class:`bytearray` object of length " +"1, return its single byte value. For example, ``ord(b'a')`` returns the " +"integer ``97``." +msgstr "" + +#: ../../library/functions.rst:1578 +msgid "" +"Return *base* to the power *exp*; if *mod* is present, return *base* to the " +"power *exp*, modulo *mod* (computed more efficiently than ``pow(base, exp) % " +"mod``). The two-argument form ``pow(base, exp)`` is equivalent to using the " +"power operator: ``base**exp``." +msgstr "" +"回傳 *base* 的 *exp* 次方；如果 *mod* 存在，則回傳 *base* 的 *exp* 次方對 " +"*mod* 取餘數（比直接呼叫 ``pow(base, exp) % mod`` 計算更高效）。兩個引數形式" +"的 ``pow(exp, exp)`` 等價於次方運算子：``base**exp``。" + +#: ../../library/functions.rst:1583 +msgid "" +"When arguments are builtin numeric types with mixed operand types, the " +"coercion rules for binary arithmetic operators apply. For :class:`int` " +"operands, the result has the same type as the operands (after coercion) " +"unless the second argument is negative; in that case, all arguments are " +"converted to float and a float result is delivered. For example, ``pow(10, " +"2)`` returns ``100``, but ``pow(10, -2)`` returns ``0.01``. For a negative " +"base of type :class:`int` or :class:`float` and a non-integral exponent, a " +"complex result is delivered. For example, ``pow(-9, 0.5)`` returns a value " +"close to ``3j``. Whereas, for a negative base of type :class:`int` or :class:" +"`float` with an integral exponent, a float result is delivered. For example, " +"``pow(-9, 2.0)`` returns ``81.0``." +msgstr "" +"當引數為內建數值型別且運算元型別為混合型別時，會套用二元算術運算子的強制轉型 " +"(coercion) 規則。對於 :class:`int` 運算元，運算結果會（在強制轉型後）與運算元" +"的型別相同，除非第二個引數是負數；在這種情況下，所有的引數都會被轉換為浮點數" +"並得到浮點數的結果。例如，``pow(10, 2)`` 會回傳 ``100``，但 ``pow(10, -2)`` " +"會回傳 ``0.01``。如果底數 (base) 是型別為 :class:`int` 或 :class:`float` 的負" +"數且指數 (exponent) 為非整數，則會傳回複數結果。例如 ``pow(-9, 0.5)`` 會回傳" +"一個接近 ``3j`` 的值。然而，如果底數 (base) 是型別為 :class:`int` 或 :class:" +"`float` 的負數且指數為整數，則會傳回浮點數結果。例如 ``pow(-9, 2.0)`` 會回傳 " +"``81.0``。" + +#: ../../library/functions.rst:1595 +msgid "" +"For :class:`int` operands *base* and *exp*, if *mod* is present, *mod* must " +"also be of integer type and *mod* must be nonzero. If *mod* is present and " +"*exp* is negative, *base* must be relatively prime to *mod*. In that case, " +"``pow(inv_base, -exp, mod)`` is returned, where *inv_base* is an inverse to " +"*base* modulo *mod*." +msgstr "" +"對於 :class:`int` 運算元 *base* 和 *exp*，如果有給定 *mod*，則 *mod* 也必須是" +"整數型別，且 *mod* 必須不為零。如果有給定 *mod* 且 *exp* 為負，則 *base* 必須" +"與 *mod* 互質。在這種情況下，會回傳 ``pow(inv_base, -exp, mod)``，其中 " +"*inv_base* 是 *base* 對 *mod* 的模倒數 (inverse modulo)。" + +#: ../../library/functions.rst:1601 +msgid "Here's an example of computing an inverse for ``38`` modulo ``97``::" +msgstr "以下是一個計算 ``38`` 對 ``97`` 取模倒數的範例： ::" + +#: ../../library/functions.rst:1603 +msgid "" +">>> pow(38, -1, mod=97)\n" +"23\n" +">>> 23 * 38 % 97 == 1\n" +"True" +msgstr "" +">>> pow(38, -1, mod=97)\n" +"23\n" +">>> 23 * 38 % 97 == 1\n" +"True" + +#: ../../library/functions.rst:1608 +msgid "" +"For :class:`int` operands, the three-argument form of ``pow`` now allows the " +"second argument to be negative, permitting computation of modular inverses." +msgstr "" +"對於 :class:`int` 運算元，現在 ``pow`` 的三引數形式允許第二個引數為負數，也容" +"許模倒數的計算。" + +#: ../../library/functions.rst:1613 +msgid "" +"Allow keyword arguments. Formerly, only positional arguments were supported." +msgstr "允許關鍵字引數。在此之前只支援位置引數。" + +#: ../../library/functions.rst:1620 +msgid "" +"Print *objects* to the text stream *file*, separated by *sep* and followed " +"by *end*. *sep*, *end*, *file*, and *flush*, if present, must be given as " +"keyword arguments." +msgstr "" +"將 *objects* 列印到文字資料串流 *file*，用 *sep* 分隔並以 *end* 結尾。如果有" +"給定 *sep*、*end*、*file* 和 *flush*，那麼它們必須是關鍵字引數的形式。" + +#: ../../library/functions.rst:1624 +msgid "" +"All non-keyword arguments are converted to strings like :func:`str` does and " +"written to the stream, separated by *sep* and followed by *end*. Both *sep* " +"and *end* must be strings; they can also be ``None``, which means to use the " +"default values. If no *objects* are given, :func:`print` will just write " +"*end*." +msgstr "" +"所有的非關鍵字引數都會像是 :func:`str` 操作一樣地被轉換為字串，並寫入資料串" +"流，彼此以 *sep* 分隔，並以 *end* 結尾。*sep* 和 *end* 都必須是字串；它們也可" +"以是 ``None``，這表示使用預設值。如果沒有給定 *objects*，:func:`print` 就只會" +"寫入 *end*。" + +#: ../../library/functions.rst:1630 +msgid "" +"The *file* argument must be an object with a ``write(string)`` method; if it " +"is not present or ``None``, :data:`sys.stdout` will be used. Since printed " +"arguments are converted to text strings, :func:`print` cannot be used with " +"binary mode file objects. For these, use ``file.write(...)`` instead." +msgstr "" +"*file* 引數必須是一個有 ``write(string)`` method 的物件；如果沒有給定或被設" +"為 ``None``，則將使用 :data:`sys.stdout`。因為要列印的引數會被轉換為文字字" +"串，所以 :func:`print` 不能用於二進位模式的檔案物件。對於此類物件，請改用 " +"``file.write(...)``。" + +#: ../../library/functions.rst:1635 +msgid "" +"Output buffering is usually determined by *file*. However, if *flush* is " +"true, the stream is forcibly flushed." +msgstr "" +"輸出緩衝通常會由 *file* 決定。但是如果 *flush* 為 true，則資料串流會被強制清" +"除。" + +#: ../../library/functions.rst:1639 +msgid "Added the *flush* keyword argument." +msgstr "增加了 *flush* 關鍵字引數。" + +#: ../../library/functions.rst:1645 +msgid "Return a property attribute." +msgstr "回傳 property 屬性。" + +#: ../../library/functions.rst:1647 +msgid "" +"*fget* is a function for getting an attribute value. *fset* is a function " +"for setting an attribute value. *fdel* is a function for deleting an " +"attribute value. And *doc* creates a docstring for the attribute." +msgstr "" +"*fget* 是一個用於取得屬性值的函式，*fset* 是一個用於設定屬性值的函式，*fdel* " +"是一個用於刪除屬性值的函式，而 *doc* 會為該屬性建立一個說明字串。" + +#: ../../library/functions.rst:1651 +msgid "A typical use is to define a managed attribute ``x``::" +msgstr "一個典型的用途是定義一個受管理的屬性 ``x``： ::" + +#: ../../library/functions.rst:1653 +msgid "" +"class C:\n" +" def __init__(self):\n" +" self._x = None\n" +"\n" +" def getx(self):\n" +" return self._x\n" +"\n" +" def setx(self, value):\n" +" self._x = value\n" +"\n" +" def delx(self):\n" +" del self._x\n" +"\n" +" x = property(getx, setx, delx, \"I'm the 'x' property.\")" +msgstr "" +"class C:\n" +" def __init__(self):\n" +" self._x = None\n" +"\n" +" def getx(self):\n" +" return self._x\n" +"\n" +" def setx(self, value):\n" +" self._x = value\n" +"\n" +" def delx(self):\n" +" del self._x\n" +"\n" +" x = property(getx, setx, delx, \"I'm the 'x' property.\")" + +#: ../../library/functions.rst:1668 +msgid "" +"If *c* is an instance of *C*, ``c.x`` will invoke the getter, ``c.x = " +"value`` will invoke the setter, and ``del c.x`` the deleter." +msgstr "" +"如果 *c* 是 *C* 的一個實例，則 ``c.x`` 將會叫用取得器 (getter)，``c.x = " +"value`` 會呼叫設定器 (setter)，而 ``del c.x`` 會叫用刪除器 (deleter)。" + +#: ../../library/functions.rst:1671 +msgid "" +"If given, *doc* will be the docstring of the property attribute. Otherwise, " +"the property will copy *fget*'s docstring (if it exists). This makes it " +"possible to create read-only properties easily using :func:`property` as a :" +"term:`decorator`::" +msgstr "" +"如果有給定 *doc*，它將會是 property 屬性的說明字串。否則，property 會複製 " +"*fget* 的說明字串（如果它存在的話）。這樣一來，就能夠輕鬆地使用 :func:" +"`property` 作為\\ :term:`裝飾器 `\\ 來建立唯讀屬性： ::" + +#: ../../library/functions.rst:1675 +msgid "" +"class Parrot:\n" +" def __init__(self):\n" +" self._voltage = 100000\n" +"\n" +" @property\n" +" def voltage(self):\n" +" \"\"\"Get the current voltage.\"\"\"\n" +" return self._voltage" +msgstr "" + +#: ../../library/functions.rst:1684 +msgid "" +"The ``@property`` decorator turns the :meth:`!voltage` method into a " +"\"getter\" for a read-only attribute with the same name, and it sets the " +"docstring for *voltage* to \"Get the current voltage.\"" +msgstr "" + +#: ../../library/functions.rst:1692 +msgid "" +"A property object has ``getter``, ``setter``, and ``deleter`` methods usable " +"as decorators that create a copy of the property with the corresponding " +"accessor function set to the decorated function. This is best explained " +"with an example:" +msgstr "" + +#: ../../library/functions.rst:1697 +msgid "" +"class C:\n" +" def __init__(self):\n" +" self._x = None\n" +"\n" +" @property\n" +" def x(self):\n" +" \"\"\"I'm the 'x' property.\"\"\"\n" +" return self._x\n" +"\n" +" @x.setter\n" +" def x(self, value):\n" +" self._x = value\n" +"\n" +" @x.deleter\n" +" def x(self):\n" +" del self._x" +msgstr "" +"class C:\n" +" def __init__(self):\n" +" self._x = None\n" +"\n" +" @property\n" +" def x(self):\n" +" \"\"\"I'm the 'x' property.\"\"\"\n" +" return self._x\n" +"\n" +" @x.setter\n" +" def x(self, value):\n" +" self._x = value\n" +"\n" +" @x.deleter\n" +" def x(self):\n" +" del self._x" + +#: ../../library/functions.rst:1716 +msgid "" +"This code is exactly equivalent to the first example. Be sure to give the " +"additional functions the same name as the original property (``x`` in this " +"case.)" +msgstr "" + +#: ../../library/functions.rst:1720 +msgid "" +"The returned property object also has the attributes ``fget``, ``fset``, and " +"``fdel`` corresponding to the constructor arguments." +msgstr "" + +#: ../../library/functions.rst:1723 +msgid "The docstrings of property objects are now writeable." +msgstr "" + +#: ../../library/functions.rst:1728 +msgid "" +"Attribute holding the name of the property. The name of the property can be " +"changed at runtime." +msgstr "" + +#: ../../library/functions.rst:1739 +msgid "" +"Rather than being a function, :class:`range` is actually an immutable " +"sequence type, as documented in :ref:`typesseq-range` and :ref:`typesseq`." +msgstr "" + +#: ../../library/functions.rst:1745 +msgid "" +"Return a string containing a printable representation of an object. For " +"many types, this function makes an attempt to return a string that would " +"yield an object with the same value when passed to :func:`eval`; otherwise, " +"the representation is a string enclosed in angle brackets that contains the " +"name of the type of the object together with additional information often " +"including the name and address of the object. A class can control what this " +"function returns for its instances by defining a :meth:`~object.__repr__` " +"method. If :func:`sys.displayhook` is not accessible, this function will " +"raise :exc:`RuntimeError`." +msgstr "" + +#: ../../library/functions.rst:1756 +msgid "This class has a custom representation that can be evaluated::" +msgstr "" + +#: ../../library/functions.rst:1758 +msgid "" +"class Person:\n" +" def __init__(self, name, age):\n" +" self.name = name\n" +" self.age = age\n" +"\n" +" def __repr__(self):\n" +" return f\"Person('{self.name}', {self.age})\"" +msgstr "" +"class Person:\n" +" def __init__(self, name, age):\n" +" self.name = name\n" +" self.age = age\n" +"\n" +" def __repr__(self):\n" +" return f\"Person('{self.name}', {self.age})\"" + +#: ../../library/functions.rst:1769 +msgid "" +"Return a reverse :term:`iterator`. The argument must be an object which has " +"a :meth:`~object.__reversed__` method or supports the sequence protocol " +"(the :meth:`~object.__len__` method and the :meth:`~object.__getitem__` " +"method with integer arguments starting at ``0``)." +msgstr "" + +#: ../../library/functions.rst:1777 +msgid "" +"Return *number* rounded to *ndigits* precision after the decimal point. If " +"*ndigits* is omitted or is ``None``, it returns the nearest integer to its " +"input." +msgstr "" + +#: ../../library/functions.rst:1781 +msgid "" +"For the built-in types supporting :func:`round`, values are rounded to the " +"closest multiple of 10 to the power minus *ndigits*; if two multiples are " +"equally close, rounding is done toward the even choice (so, for example, " +"both ``round(0.5)`` and ``round(-0.5)`` are ``0``, and ``round(1.5)`` is " +"``2``). Any integer value is valid for *ndigits* (positive, zero, or " +"negative). The return value is an integer if *ndigits* is omitted or " +"``None``. Otherwise, the return value has the same type as *number*." +msgstr "" + +#: ../../library/functions.rst:1790 +msgid "" +"For a general Python object ``number``, ``round`` delegates to ``number." +"__round__``." +msgstr "" + +#: ../../library/functions.rst:1795 +msgid "" +"The behavior of :func:`round` for floats can be surprising: for example, " +"``round(2.675, 2)`` gives ``2.67`` instead of the expected ``2.68``. This is " +"not a bug: it's a result of the fact that most decimal fractions can't be " +"represented exactly as a float. See :ref:`tut-fp-issues` for more " +"information." +msgstr "" + +#: ../../library/functions.rst:1806 +msgid "" +"Return a new :class:`set` object, optionally with elements taken from " +"*iterable*. ``set`` is a built-in class. See :class:`set` and :ref:`types-" +"set` for documentation about this class." +msgstr "" + +#: ../../library/functions.rst:1810 +msgid "" +"For other containers see the built-in :class:`frozenset`, :class:`list`, :" +"class:`tuple`, and :class:`dict` classes, as well as the :mod:`collections` " +"module." +msgstr "" + +#: ../../library/functions.rst:1817 +msgid "" +"This is the counterpart of :func:`getattr`. The arguments are an object, a " +"string, and an arbitrary value. The string may name an existing attribute " +"or a new attribute. The function assigns the value to the attribute, " +"provided the object allows it. For example, ``setattr(x, 'foobar', 123)`` " +"is equivalent to ``x.foobar = 123``." +msgstr "" + +#: ../../library/functions.rst:1823 +msgid "" +"*name* need not be a Python identifier as defined in :ref:`identifiers` " +"unless the object chooses to enforce that, for example in a custom :meth:" +"`~object.__getattribute__` or via :attr:`~object.__slots__`. An attribute " +"whose name is not an identifier will not be accessible using the dot " +"notation, but is accessible through :func:`getattr` etc.." +msgstr "" + +#: ../../library/functions.rst:1831 +msgid "" +"Since :ref:`private name mangling ` happens at " +"compilation time, one must manually mangle a private attribute's (attributes " +"with two leading underscores) name in order to set it with :func:`setattr`." +msgstr "" + +#: ../../library/functions.rst:1840 +msgid "" +"Return a :term:`slice` object representing the set of indices specified by " +"``range(start, stop, step)``. The *start* and *step* arguments default to " +"``None``." +msgstr "" + +#: ../../library/functions.rst:1844 +msgid "" +"Slice objects have read-only data attributes :attr:`!start`, :attr:`!stop`, " +"and :attr:`!step` which merely return the argument values (or their " +"default). They have no other explicit functionality; however, they are used " +"by NumPy and other third-party packages." +msgstr "" + +#: ../../library/functions.rst:1853 +msgid "" +"Slice objects are also generated when extended indexing syntax is used. For " +"example: ``a[start:stop:step]`` or ``a[start:stop, i]``. See :func:" +"`itertools.islice` for an alternate version that returns an :term:`iterator`." +msgstr "" + +#: ../../library/functions.rst:1858 +msgid "" +"Slice objects are now :term:`hashable` (provided :attr:`~slice.start`, :attr:" +"`~slice.stop`, and :attr:`~slice.step` are hashable)." +msgstr "" + +#: ../../library/functions.rst:1864 +msgid "Return a new sorted list from the items in *iterable*." +msgstr "" + +#: ../../library/functions.rst:1866 +msgid "" +"Has two optional arguments which must be specified as keyword arguments." +msgstr "有兩個選擇性引數，只能使用關鍵字引數來指定。" + +#: ../../library/functions.rst:1868 +msgid "" +"*key* specifies a function of one argument that is used to extract a " +"comparison key from each element in *iterable* (for example, ``key=str." +"lower``). The default value is ``None`` (compare the elements directly)." +msgstr "" + +#: ../../library/functions.rst:1872 +msgid "" +"*reverse* is a boolean value. If set to ``True``, then the list elements " +"are sorted as if each comparison were reversed." +msgstr "" + +#: ../../library/functions.rst:1875 +msgid "" +"Use :func:`functools.cmp_to_key` to convert an old-style *cmp* function to a " +"*key* function." +msgstr "" + +#: ../../library/functions.rst:1878 +msgid "" +"The built-in :func:`sorted` function is guaranteed to be stable. A sort is " +"stable if it guarantees not to change the relative order of elements that " +"compare equal --- this is helpful for sorting in multiple passes (for " +"example, sort by department, then by salary grade)." +msgstr "" + +#: ../../library/functions.rst:1883 +msgid "" +"The sort algorithm uses only ``<`` comparisons between items. While " +"defining an :meth:`~object.__lt__` method will suffice for sorting, :PEP:`8` " +"recommends that all six :ref:`rich comparisons ` be " +"implemented. This will help avoid bugs when using the same data with other " +"ordering tools such as :func:`max` that rely on a different underlying " +"method. Implementing all six comparisons also helps avoid confusion for " +"mixed type comparisons which can call the reflected :meth:`~object.__gt__` " +"method." +msgstr "" + +#: ../../library/functions.rst:1892 +msgid "" +"For sorting examples and a brief sorting tutorial, see :ref:`sortinghowto`." +msgstr "" + +#: ../../library/functions.rst:1896 +msgid "Transform a method into a static method." +msgstr "" + +#: ../../library/functions.rst:1898 +msgid "" +"A static method does not receive an implicit first argument. To declare a " +"static method, use this idiom::" +msgstr "" + +#: ../../library/functions.rst:1901 +msgid "" +"class C:\n" +" @staticmethod\n" +" def f(arg1, arg2, argN): ..." +msgstr "" +"class C:\n" +" @staticmethod\n" +" def f(arg1, arg2, argN): ..." + +#: ../../library/functions.rst:1905 +msgid "" +"The ``@staticmethod`` form is a function :term:`decorator` -- see :ref:" +"`function` for details." +msgstr "" +"``@staticmethod`` 語法是一個函式 :term:`decorator` - 參見 :ref:`function` 中" +"的詳細介紹。" + +#: ../../library/functions.rst:1908 +msgid "" +"A static method can be called either on the class (such as ``C.f()``) or on " +"an instance (such as ``C().f()``). Moreover, the static method :term:" +"`descriptor` is also callable, so it can be used in the class definition " +"(such as ``f()``)." +msgstr "" + +#: ../../library/functions.rst:1913 +msgid "" +"Static methods in Python are similar to those found in Java or C++. Also, " +"see :func:`classmethod` for a variant that is useful for creating alternate " +"class constructors." +msgstr "" + +#: ../../library/functions.rst:1917 +msgid "" +"Like all decorators, it is also possible to call ``staticmethod`` as a " +"regular function and do something with its result. This is needed in some " +"cases where you need a reference to a function from a class body and you " +"want to avoid the automatic transformation to instance method. For these " +"cases, use this idiom::" +msgstr "" + +#: ../../library/functions.rst:1923 +msgid "" +"def regular_function():\n" +" ...\n" +"\n" +"class C:\n" +" method = staticmethod(regular_function)" +msgstr "" +"def regular_function():\n" +" ...\n" +"\n" +"class C:\n" +" method = staticmethod(regular_function)" + +#: ../../library/functions.rst:1929 +msgid "For more information on static methods, see :ref:`types`." +msgstr "關於 static method 的更多資訊，請參考 :ref:`types`。" + +#: ../../library/functions.rst:1931 +msgid "" +"Static methods now inherit the method attributes (:attr:`~function." +"__module__`, :attr:`~function.__name__`, :attr:`~function.__qualname__`, :" +"attr:`~function.__doc__` and :attr:`~function.__annotations__`), have a new " +"``__wrapped__`` attribute, and are now callable as regular functions." +msgstr "" +"Static method 現在繼承了 method 屬性（:attr:`~function.__module__`、:attr:" +"`~function.__name__`、:attr:`~function.__qualname__`、:attr:`~function." +"__doc__` 和 :attr:`~function.__annotations__`），並擁有一個新的 " +"``__wrapped__`` 屬性，且為如一般函式的可呼叫物件。" + +#: ../../library/functions.rst:1949 +msgid "" +"Return a :class:`str` version of *object*. See :func:`str` for details." +msgstr "" + +#: ../../library/functions.rst:1951 +msgid "" +"``str`` is the built-in string :term:`class`. For general information about " +"strings, see :ref:`textseq`." +msgstr "" + +#: ../../library/functions.rst:1957 +msgid "" +"Sums *start* and the items of an *iterable* from left to right and returns " +"the total. The *iterable*'s items are normally numbers, and the start value " +"is not allowed to be a string." +msgstr "" + +#: ../../library/functions.rst:1961 +msgid "" +"For some use cases, there are good alternatives to :func:`sum`. The " +"preferred, fast way to concatenate a sequence of strings is by calling ``''." +"join(sequence)``. To add floating-point values with extended precision, " +"see :func:`math.fsum`\\. To concatenate a series of iterables, consider " +"using :func:`itertools.chain`." +msgstr "" + +#: ../../library/functions.rst:1967 +msgid "The *start* parameter can be specified as a keyword argument." +msgstr "*start* 參數可被指定為關鍵字引數。" + +#: ../../library/functions.rst:1970 +msgid "" +"Summation of floats switched to an algorithm that gives higher accuracy and " +"better commutativity on most builds." +msgstr "" + +#: ../../library/functions.rst:1973 +msgid "" +"Added specialization for summation of complexes, using same algorithm as for " +"summation of floats." +msgstr "" + +#: ../../library/functions.rst:1981 +msgid "" +"Return a proxy object that delegates method calls to a parent or sibling " +"class of *type*. This is useful for accessing inherited methods that have " +"been overridden in a class." +msgstr "" + +#: ../../library/functions.rst:1985 +msgid "" +"The *object_or_type* determines the :term:`method resolution order` to be " +"searched. The search starts from the class right after the *type*." +msgstr "" + +#: ../../library/functions.rst:1989 +msgid "" +"For example, if :attr:`~type.__mro__` of *object_or_type* is ``D -> B -> C -" +"> A -> object`` and the value of *type* is ``B``, then :func:`super` " +"searches ``C -> A -> object``." +msgstr "" + +#: ../../library/functions.rst:1993 +msgid "" +"The :attr:`~type.__mro__` attribute of the class corresponding to " +"*object_or_type* lists the method resolution search order used by both :func:" +"`getattr` and :func:`super`. The attribute is dynamic and can change " +"whenever the inheritance hierarchy is updated." +msgstr "" + +#: ../../library/functions.rst:1998 +msgid "" +"If the second argument is omitted, the super object returned is unbound. If " +"the second argument is an object, ``isinstance(obj, type)`` must be true. " +"If the second argument is a type, ``issubclass(type2, type)`` must be true " +"(this is useful for classmethods)." +msgstr "" + +#: ../../library/functions.rst:2003 +msgid "" +"When called directly within an ordinary method of a class, both arguments " +"may be omitted (\"zero-argument :func:`!super`\"). In this case, *type* will " +"be the enclosing class, and *obj* will be the first argument of the " +"immediately enclosing function (typically ``self``). (This means that zero-" +"argument :func:`!super` will not work as expected within nested functions, " +"including generator expressions, which implicitly create nested functions.)" +msgstr "" + +#: ../../library/functions.rst:2010 +msgid "" +"There are two typical use cases for *super*. In a class hierarchy with " +"single inheritance, *super* can be used to refer to parent classes without " +"naming them explicitly, thus making the code more maintainable. This use " +"closely parallels the use of *super* in other programming languages." +msgstr "" + +#: ../../library/functions.rst:2015 +msgid "" +"The second use case is to support cooperative multiple inheritance in a " +"dynamic execution environment. This use case is unique to Python and is not " +"found in statically compiled languages or languages that only support single " +"inheritance. This makes it possible to implement \"diamond diagrams\" where " +"multiple base classes implement the same method. Good design dictates that " +"such implementations have the same calling signature in every case (because " +"the order of calls is determined at runtime, because that order adapts to " +"changes in the class hierarchy, and because that order can include sibling " +"classes that are unknown prior to runtime)." +msgstr "" + +#: ../../library/functions.rst:2025 +msgid "For both use cases, a typical superclass call looks like this::" +msgstr "" + +#: ../../library/functions.rst:2027 +msgid "" +"class C(B):\n" +" def method(self, arg):\n" +" super().method(arg) # This does the same thing as:\n" +" # super(C, self).method(arg)" +msgstr "" + +#: ../../library/functions.rst:2032 +msgid "" +"In addition to method lookups, :func:`super` also works for attribute " +"lookups. One possible use case for this is calling :term:`descriptors " +"` in a parent or sibling class." +msgstr "" + +#: ../../library/functions.rst:2036 +msgid "" +"Note that :func:`super` is implemented as part of the binding process for " +"explicit dotted attribute lookups such as ``super().__getitem__(name)``. It " +"does so by implementing its own :meth:`~object.__getattribute__` method for " +"searching classes in a predictable order that supports cooperative multiple " +"inheritance. Accordingly, :func:`super` is undefined for implicit lookups " +"using statements or operators such as ``super()[name]``." +msgstr "" + +#: ../../library/functions.rst:2044 +msgid "" +"Also note that, aside from the zero argument form, :func:`super` is not " +"limited to use inside methods. The two argument form specifies the " +"arguments exactly and makes the appropriate references. The zero argument " +"form only works inside a class definition, as the compiler fills in the " +"necessary details to correctly retrieve the class being defined, as well as " +"accessing the current instance for ordinary methods." +msgstr "" + +#: ../../library/functions.rst:2051 +msgid "" +"For practical suggestions on how to design cooperative classes using :func:" +"`super`, see `guide to using super() `_." +msgstr "" + +#: ../../library/functions.rst:2055 +msgid "" +":class:`super` objects are now :mod:`pickleable ` and :mod:" +"`copyable `." +msgstr "" + +#: ../../library/functions.rst:2064 +msgid "" +"Rather than being a function, :class:`tuple` is actually an immutable " +"sequence type, as documented in :ref:`typesseq-tuple` and :ref:`typesseq`." +msgstr "" + +#: ../../library/functions.rst:2073 +msgid "" +"With one argument, return the type of an *object*. The return value is a " +"type object and generally the same object as returned by :attr:`object." +"__class__`." +msgstr "" + +#: ../../library/functions.rst:2077 +msgid "" +"The :func:`isinstance` built-in function is recommended for testing the type " +"of an object, because it takes subclasses into account." +msgstr "" + +#: ../../library/functions.rst:2080 +msgid "" +"With three arguments, return a new type object. This is essentially a " +"dynamic form of the :keyword:`class` statement. The *name* string is the " +"class name and becomes the :attr:`~type.__name__` attribute. The *bases* " +"tuple contains the base classes and becomes the :attr:`~type.__bases__` " +"attribute; if empty, :class:`object`, the ultimate base of all classes, is " +"added. The *dict* dictionary contains attribute and method definitions for " +"the class body; it may be copied or wrapped before becoming the :attr:`~type." +"__dict__` attribute. The following two statements create identical :class:`!" +"type` objects:" +msgstr "" + +#: ../../library/functions.rst:2095 +msgid "See also:" +msgstr "另請參閱：" + +#: ../../library/functions.rst:2097 +msgid "" +":ref:`Documentation on attributes and methods on classes `." +msgstr "" + +#: ../../library/functions.rst:2098 +msgid ":ref:`bltin-type-objects`" +msgstr ":ref:`bltin-type-objects`" + +#: ../../library/functions.rst:2100 +msgid "" +"Keyword arguments provided to the three argument form are passed to the " +"appropriate metaclass machinery (usually :meth:`~object.__init_subclass__`) " +"in the same way that keywords in a class definition (besides *metaclass*) " +"would." +msgstr "" + +#: ../../library/functions.rst:2105 +msgid "See also :ref:`class-customization`." +msgstr "另請參閱 :ref:`class-customization`。" + +#: ../../library/functions.rst:2107 +msgid "" +"Subclasses of :class:`!type` which don't override ``type.__new__`` may no " +"longer use the one-argument form to get the type of an object." +msgstr "" + +#: ../../library/functions.rst:2114 +msgid "" +"Return the :attr:`~object.__dict__` attribute for a module, class, instance, " +"or any other object with a :attr:`!__dict__` attribute." +msgstr "" + +#: ../../library/functions.rst:2117 +msgid "" +"Objects such as modules and instances have an updateable :attr:`~object." +"__dict__` attribute; however, other objects may have write restrictions on " +"their :attr:`!__dict__` attributes (for example, classes use a :class:`types." +"MappingProxyType` to prevent direct dictionary updates)." +msgstr "" + +#: ../../library/functions.rst:2122 +msgid "Without an argument, :func:`vars` acts like :func:`locals`." +msgstr "" + +#: ../../library/functions.rst:2124 +msgid "" +"A :exc:`TypeError` exception is raised if an object is specified but it " +"doesn't have a :attr:`~object.__dict__` attribute (for example, if its class " +"defines the :attr:`~object.__slots__` attribute)." +msgstr "" + +#: ../../library/functions.rst:2130 +msgid "" +"The result of calling this function without an argument has been updated as " +"described for the :func:`locals` builtin." +msgstr "" + +#: ../../library/functions.rst:2136 +msgid "" +"Iterate over several iterables in parallel, producing tuples with an item " +"from each one." +msgstr "" + +#: ../../library/functions.rst:2139 +msgid "Example::" +msgstr "例如： ::" + +#: ../../library/functions.rst:2141 +msgid "" +">>> for item in zip([1, 2, 3], ['sugar', 'spice', 'everything nice']):\n" +"... print(item)\n" +"...\n" +"(1, 'sugar')\n" +"(2, 'spice')\n" +"(3, 'everything nice')" +msgstr "" +">>> for item in zip([1, 2, 3], ['sugar', 'spice', 'everything nice']):\n" +"... print(item)\n" +"...\n" +"(1, 'sugar')\n" +"(2, 'spice')\n" +"(3, 'everything nice')" + +#: ../../library/functions.rst:2148 +msgid "" +"More formally: :func:`zip` returns an iterator of tuples, where the *i*-th " +"tuple contains the *i*-th element from each of the argument iterables." +msgstr "" + +#: ../../library/functions.rst:2151 +msgid "" +"Another way to think of :func:`zip` is that it turns rows into columns, and " +"columns into rows. This is similar to `transposing a matrix `_." +msgstr "" + +#: ../../library/functions.rst:2155 +msgid "" +":func:`zip` is lazy: The elements won't be processed until the iterable is " +"iterated on, e.g. by a :keyword:`!for` loop or by wrapping in a :class:" +"`list`." +msgstr "" + +#: ../../library/functions.rst:2159 +msgid "" +"One thing to consider is that the iterables passed to :func:`zip` could have " +"different lengths; sometimes by design, and sometimes because of a bug in " +"the code that prepared these iterables. Python offers three different " +"approaches to dealing with this issue:" +msgstr "" + +#: ../../library/functions.rst:2164 +msgid "" +"By default, :func:`zip` stops when the shortest iterable is exhausted. It " +"will ignore the remaining items in the longer iterables, cutting off the " +"result to the length of the shortest iterable::" +msgstr "" + +#: ../../library/functions.rst:2168 +msgid "" +">>> list(zip(range(3), ['fee', 'fi', 'fo', 'fum']))\n" +"[(0, 'fee'), (1, 'fi'), (2, 'fo')]" +msgstr "" +">>> list(zip(range(3), ['fee', 'fi', 'fo', 'fum']))\n" +"[(0, 'fee'), (1, 'fi'), (2, 'fo')]" + +#: ../../library/functions.rst:2171 +msgid "" +":func:`zip` is often used in cases where the iterables are assumed to be of " +"equal length. In such cases, it's recommended to use the ``strict=True`` " +"option. Its output is the same as regular :func:`zip`::" +msgstr "" + +#: ../../library/functions.rst:2175 +msgid "" +">>> list(zip(('a', 'b', 'c'), (1, 2, 3), strict=True))\n" +"[('a', 1), ('b', 2), ('c', 3)]" +msgstr "" +">>> list(zip(('a', 'b', 'c'), (1, 2, 3), strict=True))\n" +"[('a', 1), ('b', 2), ('c', 3)]" + +#: ../../library/functions.rst:2178 +msgid "" +"Unlike the default behavior, it raises a :exc:`ValueError` if one iterable " +"is exhausted before the others:" +msgstr "" + +#: ../../library/functions.rst:2196 +msgid "" +"Without the ``strict=True`` argument, any bug that results in iterables of " +"different lengths will be silenced, possibly manifesting as a hard-to-find " +"bug in another part of the program." +msgstr "" + +#: ../../library/functions.rst:2200 +msgid "" +"Shorter iterables can be padded with a constant value to make all the " +"iterables have the same length. This is done by :func:`itertools." +"zip_longest`." +msgstr "" + +#: ../../library/functions.rst:2204 +msgid "" +"Edge cases: With a single iterable argument, :func:`zip` returns an iterator " +"of 1-tuples. With no arguments, it returns an empty iterator." +msgstr "" + +#: ../../library/functions.rst:2207 +msgid "Tips and tricks:" +msgstr "" + +#: ../../library/functions.rst:2209 +msgid "" +"The left-to-right evaluation order of the iterables is guaranteed. This " +"makes possible an idiom for clustering a data series into n-length groups " +"using ``zip(*[iter(s)]*n, strict=True)``. This repeats the *same* iterator " +"``n`` times so that each output tuple has the result of ``n`` calls to the " +"iterator. This has the effect of dividing the input into n-length chunks." +msgstr "" + +#: ../../library/functions.rst:2215 +msgid "" +":func:`zip` in conjunction with the ``*`` operator can be used to unzip a " +"list::" +msgstr "" + +#: ../../library/functions.rst:2218 +msgid "" +">>> x = [1, 2, 3]\n" +">>> y = [4, 5, 6]\n" +">>> list(zip(x, y))\n" +"[(1, 4), (2, 5), (3, 6)]\n" +">>> x2, y2 = zip(*zip(x, y))\n" +">>> x == list(x2) and y == list(y2)\n" +"True" +msgstr "" +">>> x = [1, 2, 3]\n" +">>> y = [4, 5, 6]\n" +">>> list(zip(x, y))\n" +"[(1, 4), (2, 5), (3, 6)]\n" +">>> x2, y2 = zip(*zip(x, y))\n" +">>> x == list(x2) and y == list(y2)\n" +"True" + +#: ../../library/functions.rst:2226 +msgid "Added the ``strict`` argument." +msgstr "增加了 ``strict`` 引數。" + +#: ../../library/functions.rst:2238 +msgid "" +"This is an advanced function that is not needed in everyday Python " +"programming, unlike :func:`importlib.import_module`." +msgstr "" + +#: ../../library/functions.rst:2241 +msgid "" +"This function is invoked by the :keyword:`import` statement. It can be " +"replaced (by importing the :mod:`builtins` module and assigning to " +"``builtins.__import__``) in order to change semantics of the :keyword:`!" +"import` statement, but doing so is **strongly** discouraged as it is usually " +"simpler to use import hooks (see :pep:`302`) to attain the same goals and " +"does not cause issues with code which assumes the default import " +"implementation is in use. Direct use of :func:`__import__` is also " +"discouraged in favor of :func:`importlib.import_module`." +msgstr "" + +#: ../../library/functions.rst:2250 +msgid "" +"The function imports the module *name*, potentially using the given " +"*globals* and *locals* to determine how to interpret the name in a package " +"context. The *fromlist* gives the names of objects or submodules that should " +"be imported from the module given by *name*. The standard implementation " +"does not use its *locals* argument at all and uses its *globals* only to " +"determine the package context of the :keyword:`import` statement." +msgstr "" + +#: ../../library/functions.rst:2257 +msgid "" +"*level* specifies whether to use absolute or relative imports. ``0`` (the " +"default) means only perform absolute imports. Positive values for *level* " +"indicate the number of parent directories to search relative to the " +"directory of the module calling :func:`__import__` (see :pep:`328` for the " +"details)." +msgstr "" + +#: ../../library/functions.rst:2263 +msgid "" +"When the *name* variable is of the form ``package.module``, normally, the " +"top-level package (the name up till the first dot) is returned, *not* the " +"module named by *name*. However, when a non-empty *fromlist* argument is " +"given, the module named by *name* is returned." +msgstr "" + +#: ../../library/functions.rst:2268 +msgid "" +"For example, the statement ``import spam`` results in bytecode resembling " +"the following code::" +msgstr "" + +#: ../../library/functions.rst:2271 +msgid "spam = __import__('spam', globals(), locals(), [], 0)" +msgstr "spam = __import__('spam', globals(), locals(), [], 0)" + +#: ../../library/functions.rst:2273 +msgid "The statement ``import spam.ham`` results in this call::" +msgstr "" + +#: ../../library/functions.rst:2275 +msgid "spam = __import__('spam.ham', globals(), locals(), [], 0)" +msgstr "spam = __import__('spam.ham', globals(), locals(), [], 0)" + +#: ../../library/functions.rst:2277 +msgid "" +"Note how :func:`__import__` returns the toplevel module here because this is " +"the object that is bound to a name by the :keyword:`import` statement." +msgstr "" + +#: ../../library/functions.rst:2280 +msgid "" +"On the other hand, the statement ``from spam.ham import eggs, sausage as " +"saus`` results in ::" +msgstr "" + +#: ../../library/functions.rst:2283 +msgid "" +"_temp = __import__('spam.ham', globals(), locals(), ['eggs', 'sausage'], 0)\n" +"eggs = _temp.eggs\n" +"saus = _temp.sausage" +msgstr "" +"_temp = __import__('spam.ham', globals(), locals(), ['eggs', 'sausage'], 0)\n" +"eggs = _temp.eggs\n" +"saus = _temp.sausage" + +#: ../../library/functions.rst:2287 +msgid "" +"Here, the ``spam.ham`` module is returned from :func:`__import__`. From " +"this object, the names to import are retrieved and assigned to their " +"respective names." +msgstr "" + +#: ../../library/functions.rst:2291 +msgid "" +"If you simply want to import a module (potentially within a package) by " +"name, use :func:`importlib.import_module`." +msgstr "" + +#: ../../library/functions.rst:2294 +msgid "" +"Negative values for *level* are no longer supported (which also changes the " +"default value to 0)." +msgstr "" + +#: ../../library/functions.rst:2298 +msgid "" +"When the command line options :option:`-E` or :option:`-I` are being used, " +"the environment variable :envvar:`PYTHONCASEOK` is now ignored." +msgstr "" + +#: ../../library/functions.rst:2303 +msgid "Footnotes" +msgstr "註解" + +#: ../../library/functions.rst:2304 +msgid "" +"Note that the parser only accepts the Unix-style end of line convention. If " +"you are reading the code from a file, make sure to use newline conversion " +"mode to convert Windows or Mac-style newlines." +msgstr "" +"剖析器只接受 Unix 風格的行結束符。如果你從檔案中讀取程式碼，請確保用換行符號" +"轉換模式轉換 Windows 或 Mac 風格的換行符號。" + +#: ../../library/functions.rst:154 +msgid "Boolean" +msgstr "Boolean（布林值）" + +#: ../../library/functions.rst:154 ../../library/functions.rst:2071 +msgid "type" +msgstr "type（型別）" + +#: ../../library/functions.rst:652 +msgid "built-in function" +msgstr "built-in function（內建函式）" + +#: ../../library/functions.rst:652 +msgid "exec" +msgstr "exec" + +#: ../../library/functions.rst:750 +msgid "NaN" +msgstr "NaN" + +#: ../../library/functions.rst:750 +msgid "Infinity" +msgstr "Infinity（無窮）" + +#: ../../library/functions.rst:820 +msgid "__format__" +msgstr "__format__" + +#: ../../library/functions.rst:820 ../../library/functions.rst:1939 +msgid "string" +msgstr "string（字串）" + +#: ../../library/functions.rst:820 +msgid "format() (built-in function)" +msgstr "format()（內建函式）" + +#: ../../library/functions.rst:1334 +msgid "file object" +msgstr "file object（檔案物件）" + +#: ../../library/functions.rst:1334 ../../library/functions.rst:1455 +msgid "open() built-in function" +msgstr "open() 內建函式" + +#: ../../library/functions.rst:1362 +msgid "file" +msgstr "file（檔案）" + +#: ../../library/functions.rst:1362 +msgid "modes" +msgstr "modes（模式）" + +#: ../../library/functions.rst:1455 +msgid "universal newlines" +msgstr "universal newlines" + +#: ../../library/functions.rst:1516 +msgid "line-buffered I/O" +msgstr "line-buffered I/O（行緩衝 I/O）" + +#: ../../library/functions.rst:1516 +msgid "unbuffered I/O" +msgstr "unbuffered I/O（非緩衝 I/O）" + +#: ../../library/functions.rst:1516 +msgid "buffer size, I/O" +msgstr "buffer size, I/O（緩衝區大小、I/O）" + +#: ../../library/functions.rst:1516 +msgid "I/O control" +msgstr "I/O control（I/O 控制）" + +#: ../../library/functions.rst:1516 +msgid "buffering" +msgstr "buffering（緩衝）" + +#: ../../library/functions.rst:1516 +msgid "text mode" +msgstr "text mode（文字模式）" + +#: ../../library/functions.rst:1516 ../../library/functions.rst:2232 +msgid "module" +msgstr "module（模組）" + +#: ../../library/functions.rst:1516 +msgid "sys" +msgstr "sys" + +#: ../../library/functions.rst:1939 +msgid "str() (built-in function)" +msgstr "str() （內建函式）" + +#: ../../library/functions.rst:2071 +msgid "object" +msgstr "object（物件）" + +#: ../../library/functions.rst:2232 +msgid "statement" +msgstr "statement（陳述式）" + +#: ../../library/functions.rst:2232 +msgid "import" +msgstr "import（引入）" + +#: ../../library/functions.rst:2232 +msgid "builtins" +msgstr "builtins（內建）" diff --git a/library/functools.po b/library/functools.po index 60b55ae508..ecd9a4f981 100644 --- a/library/functools.po +++ b/library/functools.po @@ -1,1533 +1,1533 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Matt Wang , 2024 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-19 00:14+0000\n" -"PO-Revision-Date: 2024-05-11 16:02+0800\n" -"Last-Translator: Matt Wang \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/functools.rst:2 -msgid "" -":mod:`!functools` --- Higher-order functions and operations on callable " -"objects" -msgstr ":mod:`functools` --- 可呼叫物件上的高階函式與操作" - -#: ../../library/functools.rst:14 -msgid "**Source code:** :source:`Lib/functools.py`" -msgstr "**原始碼：**\\ :source:`Lib/functools.py`" - -#: ../../library/functools.rst:23 -msgid "" -"The :mod:`functools` module is for higher-order functions: functions that " -"act on or return other functions. In general, any callable object can be " -"treated as a function for the purposes of this module." -msgstr "" -":mod:`functools` 模組用於高階函式：作用於或回傳其他函式的函式。一般來說，任何" -"可呼叫物件都可以被視為用於此模組的函式。" - -#: ../../library/functools.rst:27 -msgid "The :mod:`functools` module defines the following functions:" -msgstr ":mod:`functools` 模組定義了以下函式：" - -#: ../../library/functools.rst:31 -msgid "" -"Simple lightweight unbounded function cache. Sometimes called `\"memoize\" " -"`_." -msgstr "" -"簡單的輕量級無繫結函式快取 (Simple lightweight unbounded function cache)。有" -"時稱之為 `\"memoize\"（記憶化） `_。" - -#: ../../library/functools.rst:34 -msgid "" -"Returns the same as ``lru_cache(maxsize=None)``, creating a thin wrapper " -"around a dictionary lookup for the function arguments. Because it never " -"needs to evict old values, this is smaller and faster than :func:`lru_cache` " -"with a size limit." -msgstr "" -"和 ``lru_cache(maxsize=None)`` 回傳相同的值，為函式引數建立一個字典查找的薄包" -"裝器。因為它永遠不需要丟棄舊值，所以這比有大小限制的 :func:`lru_cache` 更小、" -"更快。" - -#: ../../library/functools.rst:39 ../../library/functools.rst:297 -msgid "For example::" -msgstr "舉例來說： ::" - -#: ../../library/functools.rst:41 -msgid "" -"@cache\n" -"def factorial(n):\n" -" return n * factorial(n-1) if n else 1\n" -"\n" -">>> factorial(10) # no previously cached result, makes 11 recursive calls\n" -"3628800\n" -">>> factorial(5) # no new calls, just returns the cached result\n" -"120\n" -">>> factorial(12) # two new recursive calls, factorial(10) is cached\n" -"479001600" -msgstr "" -"@cache\n" -"def factorial(n):\n" -" return n * factorial(n-1) if n else 1\n" -"\n" -">>> factorial(10) # 沒有先前的快取結果，會進行 11 次遞迴呼叫\n" -"3628800\n" -">>> factorial(5) # 沒有新的呼叫，直接回傳被快取起來的結果\n" -"120\n" -">>> factorial(12) # 兩次新的遞迴呼叫，factorial(10) 有被快取起來\n" -"479001600" - -#: ../../library/functools.rst:52 ../../library/functools.rst:158 -msgid "" -"The cache is threadsafe so that the wrapped function can be used in multiple " -"threads. This means that the underlying data structure will remain coherent " -"during concurrent updates." -msgstr "" -"該快取是執行緒安全的 (threadsafe)，因此包裝的函式可以在多個執行緒中使用。這意" -"味著底層資料結構在並行更新期間將保持連貫 (coherent)。" - -#: ../../library/functools.rst:56 ../../library/functools.rst:162 -msgid "" -"It is possible for the wrapped function to be called more than once if " -"another thread makes an additional call before the initial call has been " -"completed and cached." -msgstr "" -"如果另一個執行緒在初始呼叫完成並快取之前進行額外的呼叫，則包裝的函式可能會被" -"多次呼叫。" - -#: ../../library/functools.rst:65 -msgid "" -"Transform a method of a class into a property whose value is computed once " -"and then cached as a normal attribute for the life of the instance. Similar " -"to :func:`property`, with the addition of caching. Useful for expensive " -"computed properties of instances that are otherwise effectively immutable." -msgstr "" -"將類別的一個方法轉換為屬性 (property)，其值會計算一次，然後在實例的生命週期內" -"快取為普通屬性。類似 :func:`property`，但增加了快取機制。對於除使用該裝飾器的" -"屬性外實質上幾乎是不可變 (immutable) 的實例，針對其所需要繁重計算會很有用。" - -#: ../../library/functools.rst:70 ../../library/functools.rst:142 -#: ../../library/functools.rst:438 -msgid "Example::" -msgstr "範例： ::" - -#: ../../library/functools.rst:72 -msgid "" -"class DataSet:\n" -"\n" -" def __init__(self, sequence_of_numbers):\n" -" self._data = tuple(sequence_of_numbers)\n" -"\n" -" @cached_property\n" -" def stdev(self):\n" -" return statistics.stdev(self._data)" -msgstr "" -"class DataSet:\n" -"\n" -" def __init__(self, sequence_of_numbers):\n" -" self._data = tuple(sequence_of_numbers)\n" -"\n" -" @cached_property\n" -" def stdev(self):\n" -" return statistics.stdev(self._data)" - -#: ../../library/functools.rst:81 -msgid "" -"The mechanics of :func:`cached_property` are somewhat different from :func:" -"`property`. A regular property blocks attribute writes unless a setter is " -"defined. In contrast, a *cached_property* allows writes." -msgstr "" -":func:`cached_property` 的機制與 :func:`property` 有所不同。除非定義了 " -"setter，否則常規屬性會阻止屬性的寫入。相反地，*cached_property* 則允許寫入。" - -#: ../../library/functools.rst:85 -msgid "" -"The *cached_property* decorator only runs on lookups and only when an " -"attribute of the same name doesn't exist. When it does run, the " -"*cached_property* writes to the attribute with the same name. Subsequent " -"attribute reads and writes take precedence over the *cached_property* method " -"and it works like a normal attribute." -msgstr "" -"*cached_property* 裝飾器僅在查找時且僅在同名屬性不存在時運行。當它運行時，" -"*cached_property* 會寫入同名的屬性。後續屬性讀取和寫入優先於 " -"*cached_property* 方法，並且它的工作方式與普通屬性類似。" - -#: ../../library/functools.rst:91 -msgid "" -"The cached value can be cleared by deleting the attribute. This allows the " -"*cached_property* method to run again." -msgstr "" -"可以透過刪除屬性來清除快取的值，這使得 *cached_property* 方法可以再次運行。" - -#: ../../library/functools.rst:94 -msgid "" -"The *cached_property* does not prevent a possible race condition in multi-" -"threaded usage. The getter function could run more than once on the same " -"instance, with the latest run setting the cached value. If the cached " -"property is idempotent or otherwise not harmful to run more than once on an " -"instance, this is fine. If synchronization is needed, implement the " -"necessary locking inside the decorated getter function or around the cached " -"property access." -msgstr "" -"*cached_property* 無法防止多執行緒使用中可能出現的競爭條件 (race condition)。" -"getter 函式可以在同一個實例上運行多次，最後一次運行會設定快取的值。所以快取的" -"屬性最好是冪等的 (idempotent)，或者在一個實例上運行多次不會有害，就不會有問" -"題。如果同步是必要的，請在裝飾的 getter 函式內部或在快取的屬性存取周圍實作必" -"要的鎖。" - -#: ../../library/functools.rst:102 -msgid "" -"Note, this decorator interferes with the operation of :pep:`412` key-sharing " -"dictionaries. This means that instance dictionaries can take more space " -"than usual." -msgstr "" -"請注意，此裝飾器會干擾 :pep:`412` 金鑰共用字典的操作。這意味著實例字典可能比" -"平常佔用更多的空間。" - -#: ../../library/functools.rst:106 -msgid "" -"Also, this decorator requires that the ``__dict__`` attribute on each " -"instance be a mutable mapping. This means it will not work with some types, " -"such as metaclasses (since the ``__dict__`` attributes on type instances are " -"read-only proxies for the class namespace), and those that specify " -"``__slots__`` without including ``__dict__`` as one of the defined slots (as " -"such classes don't provide a ``__dict__`` attribute at all)." -msgstr "" -"此外，此裝飾器要求每個實例上的 ``__dict__`` 屬性是可變對映 (mutable " -"mapping)。這意味著它不適用於某些型別，例如元類別 (metaclass)（因為型別實例上" -"的 ``__dict__`` 屬性是類別命名空間的唯讀代理），以及那些指定 ``__slots__`` 而" -"不包含 ``__dict__`` 的型別作為有定義的插槽之一（因為此種類別根本不提供 " -"``__dict__`` 屬性）。" - -#: ../../library/functools.rst:113 -msgid "" -"If a mutable mapping is not available or if space-efficient key sharing is " -"desired, an effect similar to :func:`cached_property` can also be achieved " -"by stacking :func:`property` on top of :func:`lru_cache`. See :ref:`faq-" -"cache-method-calls` for more details on how this differs from :func:" -"`cached_property`." -msgstr "" -"如果可變對映不可用或需要金鑰共享以節省空間，則也可以透過在 :func:`lru_cache` " -"之上堆疊 :func:`property` 來實作類似於 :func:`cached_property` 的效果。請參閱" -"\\ :ref:`faq-cache-method-calls`\\ 以了解有關這與 :func:`cached_property` 間" -"不同之處的更多詳細資訊。" - -#: ../../library/functools.rst:120 -msgid "" -"Prior to Python 3.12, ``cached_property`` included an undocumented lock to " -"ensure that in multi-threaded usage the getter function was guaranteed to " -"run only once per instance. However, the lock was per-property, not per-" -"instance, which could result in unacceptably high lock contention. In Python " -"3.12+ this locking is removed." -msgstr "" -"在 Python 3.12 之前，``cached_property`` 包含一個未以文件記錄的鎖，以確保在多" -"執行緒使用中能保證 getter 函式對於每個實例只會執行一次。然而，鎖是針對每個屬" -"性，而不是針對每個實例，這可能會導致無法被接受的嚴重鎖爭用 (lock " -"contention)。在 Python 3.12+ 中，此鎖已被刪除。" - -#: ../../library/functools.rst:130 -msgid "" -"Transform an old-style comparison function to a :term:`key function`. Used " -"with tools that accept key functions (such as :func:`sorted`, :func:`min`, :" -"func:`max`, :func:`heapq.nlargest`, :func:`heapq.nsmallest`, :func:" -"`itertools.groupby`). This function is primarily used as a transition tool " -"for programs being converted from Python 2 which supported the use of " -"comparison functions." -msgstr "" -"將舊式比較函式轉換為\\ :term:`鍵函式 `，能與接受鍵函式的工具一" -"起使用（例如 :func:`sorted`、:func:`min`、:func:`max`、:func:`heapq." -"nlargest`、:func:`heapq.nsmallest`、:func:`itertools.groupby`）。此函式主要作" -"為轉換工具，用於從有支援使用比較函式的 Python 2 轉換成的程式。" - -#: ../../library/functools.rst:137 -msgid "" -"A comparison function is any callable that accepts two arguments, compares " -"them, and returns a negative number for less-than, zero for equality, or a " -"positive number for greater-than. A key function is a callable that accepts " -"one argument and returns another value to be used as the sort key." -msgstr "" -"比較函式是任何能接受兩個引數、對它們進行比較，並回傳負數（小於）、零（相等）" -"或正數（大於）的可呼叫物件。鍵函式是接受一個引數並回傳另一個用作排序鍵之值的" -"可呼叫物件。" - -#: ../../library/functools.rst:144 -msgid "" -"sorted(iterable, key=cmp_to_key(locale.strcoll)) # locale-aware sort order" -msgstr "" - -#: ../../library/functools.rst:146 -msgid "" -"For sorting examples and a brief sorting tutorial, see :ref:`sortinghowto`." -msgstr "有關排序範例和簡短的排序教學，請參閱\\ :ref:`sortinghowto`。" - -#: ../../library/functools.rst:154 -msgid "" -"Decorator to wrap a function with a memoizing callable that saves up to the " -"*maxsize* most recent calls. It can save time when an expensive or I/O " -"bound function is periodically called with the same arguments." -msgstr "" -"以記憶化可呼叫物件來包裝函式的裝飾器，最多可省去 *maxsize* 個最近的呼叫。當使" -"用相同引數定期呼叫繁重的或 I/O 密集的函式時，它可以節省時間。" - -#: ../../library/functools.rst:166 -msgid "" -"Since a dictionary is used to cache results, the positional and keyword " -"arguments to the function must be :term:`hashable`." -msgstr "" -"由於字典用於快取結果，因此函式的位置引數和關鍵字引數必須是\\ :term:`可雜湊的 " -"`。" - -#: ../../library/functools.rst:169 -msgid "" -"Distinct argument patterns may be considered to be distinct calls with " -"separate cache entries. For example, ``f(a=1, b=2)`` and ``f(b=2, a=1)`` " -"differ in their keyword argument order and may have two separate cache " -"entries." -msgstr "" -"不同的引數模式可以被認為是具有不同快取條目的不同呼叫。例如，``f(a=1, b=2)`` " -"和 ``f(b=2, a=1)`` 的關鍵字引數順序不同，並且可能有兩個不同的快取條目。" - -#: ../../library/functools.rst:174 -msgid "" -"If *user_function* is specified, it must be a callable. This allows the " -"*lru_cache* decorator to be applied directly to a user function, leaving the " -"*maxsize* at its default value of 128::" -msgstr "" -"如果指定了 *user_function*，則它必須是個可呼叫物件。這使得 *lru_cache* 裝飾器" -"能夠直接應用於使用者函式，將 *maxsize* 保留為其預設值 128： ::" - -#: ../../library/functools.rst:178 -msgid "" -"@lru_cache\n" -"def count_vowels(sentence):\n" -" return sum(sentence.count(vowel) for vowel in 'AEIOUaeiou')" -msgstr "" -"@lru_cache\n" -"def count_vowels(sentence):\n" -" return sum(sentence.count(vowel) for vowel in 'AEIOUaeiou')" - -#: ../../library/functools.rst:182 -msgid "" -"If *maxsize* is set to ``None``, the LRU feature is disabled and the cache " -"can grow without bound." -msgstr "" -"如果 *maxsize* 設定為 ``None``，則 LRU 功能將被停用，且快取可以無限制地成長。" - -#: ../../library/functools.rst:185 -msgid "" -"If *typed* is set to true, function arguments of different types will be " -"cached separately. If *typed* is false, the implementation will usually " -"regard them as equivalent calls and only cache a single result. (Some types " -"such as *str* and *int* may be cached separately even when *typed* is false.)" -msgstr "" -"如果 *typed* 設定為 true，不同型別的函式引數將會被單獨快取起來。如果 *typed* " -"為 false，則實作通常會將它們視為等效呼叫，並且僅快取單一結果。（某些型別，例" -"如 *str* 和 *int* 可能會被單獨快取起來，即使 *typed* 為 false。）" - -#: ../../library/functools.rst:191 -msgid "" -"Note, type specificity applies only to the function's immediate arguments " -"rather than their contents. The scalar arguments, ``Decimal(42)`` and " -"``Fraction(42)`` are be treated as distinct calls with distinct results. In " -"contrast, the tuple arguments ``('answer', Decimal(42))`` and ``('answer', " -"Fraction(42))`` are treated as equivalent." -msgstr "" -"請注意，型別特異性 (type specificity) 僅適用於函式的直接引數而不是其內容。純" -"量 (scalar) 引數 ``Decimal(42)`` 和 ``Fraction(42)`` 被視為具有不同結果的不同" -"呼叫。相反地，元組引數 ``('answer', Decimal(42))`` 和 ``('answer', " -"Fraction(42))`` 被視為等效。" - -#: ../../library/functools.rst:197 -msgid "" -"The wrapped function is instrumented with a :func:`!cache_parameters` " -"function that returns a new :class:`dict` showing the values for *maxsize* " -"and *typed*. This is for information purposes only. Mutating the values " -"has no effect." -msgstr "" -"包裝的函式使用一個 :func:`!cache_parameters` 函式來進行偵測，該函式回傳一個新" -"的 :class:`dict` 以顯示 *maxsize* 和 *typed* 的值。這僅能顯示資訊，改變其值不" -"會有任何效果。" - -#: ../../library/functools.rst:205 -msgid "" -"To help measure the effectiveness of the cache and tune the *maxsize* " -"parameter, the wrapped function is instrumented with a :func:`!cache_info` " -"function that returns a :term:`named tuple` showing *hits*, *misses*, " -"*maxsize* and *currsize*." -msgstr "" -"為了輔助測量快取的有效性並調整 *maxsize* 參數，包裝的函式使用了一個 :func:`!" -"cache_info` 函式來做檢測，該函式會回傳一個\\ :term:`附名元組 `\\ 來顯示 *hits*、*misses*、*maxsize* 和 *currsize*。" - -#: ../../library/functools.rst:213 -msgid "" -"The decorator also provides a :func:`!cache_clear` function for clearing or " -"invalidating the cache." -msgstr "裝飾器還提供了一個 :func:`!cache_clear` 函式來清除或使快取失效。" - -#: ../../library/functools.rst:216 -msgid "" -"The original underlying function is accessible through the :attr:" -"`__wrapped__` attribute. This is useful for introspection, for bypassing " -"the cache, or for rewrapping the function with a different cache." -msgstr "" -"原本的底層函式可以透過 :attr:`__wrapped__` 屬性存取。這對於要自我檢查 " -"(introspection)、繞過快取或使用不同的快取重新包裝函式時非常有用。" - -#: ../../library/functools.rst:220 -msgid "" -"The cache keeps references to the arguments and return values until they age " -"out of the cache or until the cache is cleared." -msgstr "" -"快取會保留對引數和回傳值的參照，直到快取過時 (age out) 或快取被清除為止。" - -#: ../../library/functools.rst:223 -msgid "" -"If a method is cached, the ``self`` instance argument is included in the " -"cache. See :ref:`faq-cache-method-calls`" -msgstr "" -"如果方法被快取起來，則 ``self`` 實例引數將包含在快取中。請參閱\\ :ref:`faq-" -"cache-method-calls`" - -#: ../../library/functools.rst:226 -msgid "" -"An `LRU (least recently used) cache `_ works best when the " -"most recent calls are the best predictors of upcoming calls (for example, " -"the most popular articles on a news server tend to change each day). The " -"cache's size limit assures that the cache does not grow without bound on " -"long-running processes such as web servers." -msgstr "" -"當最近的呼叫是即將發生之呼叫的最佳預測因子時（例如新聞伺服器上最受歡迎的文章" -"往往每天都會發生變化），`LRU (least recently used) 快取 `_\\ " -"能發揮最好的效果。快取的大小限制可確保快取不會在長時間運行的行程（例如 Web 伺" -"服器）上無限制地成長。" - -#: ../../library/functools.rst:233 -msgid "" -"In general, the LRU cache should only be used when you want to reuse " -"previously computed values. Accordingly, it doesn't make sense to cache " -"functions with side-effects, functions that need to create distinct mutable " -"objects on each call (such as generators and async functions), or impure " -"functions such as time() or random()." -msgstr "" -"一般來說，僅當你想要重複使用先前計算的值時才應使用 LRU 快取。因此，快取具有 " -"side-effects 的函式、需要在每次呼叫時建立不同可變物件的函式（例如產生器和非同" -"步函式）或不純函式（impure function，例如 time() 或 random()）是沒有意義的。" - -#: ../../library/functools.rst:239 -msgid "Example of an LRU cache for static web content::" -msgstr "靜態網頁內容的 LRU 快取範例： ::" - -#: ../../library/functools.rst:241 -msgid "" -"@lru_cache(maxsize=32)\n" -"def get_pep(num):\n" -" 'Retrieve text of a Python Enhancement Proposal'\n" -" resource = f'https://peps.python.org/pep-{num:04d}'\n" -" try:\n" -" with urllib.request.urlopen(resource) as s:\n" -" return s.read()\n" -" except urllib.error.HTTPError:\n" -" return 'Not Found'\n" -"\n" -">>> for n in 8, 290, 308, 320, 8, 218, 320, 279, 289, 320, 9991:\n" -"... pep = get_pep(n)\n" -"... print(n, len(pep))\n" -"\n" -">>> get_pep.cache_info()\n" -"CacheInfo(hits=3, misses=8, maxsize=32, currsize=8)" -msgstr "" -"@lru_cache(maxsize=32)\n" -"def get_pep(num):\n" -" '取得 Python 改進提案的文字'\n" -" resource = f'https://peps.python.org/pep-{num:04d}'\n" -" try:\n" -" with urllib.request.urlopen(resource) as s:\n" -" return s.read()\n" -" except urllib.error.HTTPError:\n" -" return 'Not Found'\n" -"\n" -">>> for n in 8, 290, 308, 320, 8, 218, 320, 279, 289, 320, 9991:\n" -"... pep = get_pep(n)\n" -"... print(n, len(pep))\n" -"\n" -">>> get_pep.cache_info()\n" -"CacheInfo(hits=3, misses=8, maxsize=32, currsize=8)" - -#: ../../library/functools.rst:258 -msgid "" -"Example of efficiently computing `Fibonacci numbers `_ using a cache to implement a `dynamic " -"programming `_ technique::" -msgstr "" -"使用快取來實作\\ `動態規劃 (dynamic programming) `_ 技法以有效率地計算\\ `費波那契數 (Fibonacci " -"numbers) `_ 的範例： ::" - -#: ../../library/functools.rst:264 -msgid "" -"@lru_cache(maxsize=None)\n" -"def fib(n):\n" -" if n < 2:\n" -" return n\n" -" return fib(n-1) + fib(n-2)\n" -"\n" -">>> [fib(n) for n in range(16)]\n" -"[0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, 233, 377, 610]\n" -"\n" -">>> fib.cache_info()\n" -"CacheInfo(hits=28, misses=16, maxsize=None, currsize=16)" -msgstr "" -"@lru_cache(maxsize=None)\n" -"def fib(n):\n" -" if n < 2:\n" -" return n\n" -" return fib(n-1) + fib(n-2)\n" -"\n" -">>> [fib(n) for n in range(16)]\n" -"[0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, 233, 377, 610]\n" -"\n" -">>> fib.cache_info()\n" -"CacheInfo(hits=28, misses=16, maxsize=None, currsize=16)" - -#: ../../library/functools.rst:278 -msgid "Added the *typed* option." -msgstr "新增 *typed* 選項。" - -#: ../../library/functools.rst:281 -msgid "Added the *user_function* option." -msgstr "新增 *user_function* 選項。" - -#: ../../library/functools.rst:284 -msgid "Added the function :func:`!cache_parameters`" -msgstr "新增 :func:`!cache_parameters` 函式。" - -#: ../../library/functools.rst:289 -msgid "" -"Given a class defining one or more rich comparison ordering methods, this " -"class decorator supplies the rest. This simplifies the effort involved in " -"specifying all of the possible rich comparison operations:" -msgstr "" -"給定一個定義一個或多個 rich comparison 排序方法的類別，該類別裝飾器會提供其餘" -"部分。這簡化了指定所有可能的 rich comparison 操作所涉及的工作：" - -#: ../../library/functools.rst:293 -msgid "" -"The class must define one of :meth:`~object.__lt__`, :meth:`~object." -"__le__`, :meth:`~object.__gt__`, or :meth:`~object.__ge__`. In addition, the " -"class should supply an :meth:`~object.__eq__` method." -msgstr "" -"類別必須定義 :meth:`~object.__lt__`、:meth:`~object.__le__`、:meth:`~object." -"__gt__` 或 :meth:`~object.__ge__` 其中之一。此外，該類別應該提供 :meth:" -"`~object.__eq__` 方法。" - -#: ../../library/functools.rst:299 -msgid "" -"@total_ordering\n" -"class Student:\n" -" def _is_valid_operand(self, other):\n" -" return (hasattr(other, \"lastname\") and\n" -" hasattr(other, \"firstname\"))\n" -" def __eq__(self, other):\n" -" if not self._is_valid_operand(other):\n" -" return NotImplemented\n" -" return ((self.lastname.lower(), self.firstname.lower()) ==\n" -" (other.lastname.lower(), other.firstname.lower()))\n" -" def __lt__(self, other):\n" -" if not self._is_valid_operand(other):\n" -" return NotImplemented\n" -" return ((self.lastname.lower(), self.firstname.lower()) <\n" -" (other.lastname.lower(), other.firstname.lower()))" -msgstr "" -"@total_ordering\n" -"class Student:\n" -" def _is_valid_operand(self, other):\n" -" return (hasattr(other, \"lastname\") and\n" -" hasattr(other, \"firstname\"))\n" -" def __eq__(self, other):\n" -" if not self._is_valid_operand(other):\n" -" return NotImplemented\n" -" return ((self.lastname.lower(), self.firstname.lower()) ==\n" -" (other.lastname.lower(), other.firstname.lower()))\n" -" def __lt__(self, other):\n" -" if not self._is_valid_operand(other):\n" -" return NotImplemented\n" -" return ((self.lastname.lower(), self.firstname.lower()) <\n" -" (other.lastname.lower(), other.firstname.lower()))" - -#: ../../library/functools.rst:317 -msgid "" -"While this decorator makes it easy to create well behaved totally ordered " -"types, it *does* come at the cost of slower execution and more complex stack " -"traces for the derived comparison methods. If performance benchmarking " -"indicates this is a bottleneck for a given application, implementing all six " -"rich comparison methods instead is likely to provide an easy speed boost." -msgstr "" -"雖然此裝飾器可以輕鬆建立能好好運作的完全有序型別 (totally ordered types)，但" -"它\\ *的確*\\ 以衍生比較方法的執行速度較慢和堆疊追蹤 (stack trace) 較複雜做為" -"其代價。如果效能基準測試顯示這是給定應用程式的效能瓶頸，那麼實作全部六種 " -"rich comparison 方法通常能輕鬆地提升速度。" - -#: ../../library/functools.rst:326 -msgid "" -"This decorator makes no attempt to override methods that have been declared " -"in the class *or its superclasses*. Meaning that if a superclass defines a " -"comparison operator, *total_ordering* will not implement it again, even if " -"the original method is abstract." -msgstr "" -"此裝飾器不會嘗試覆寫類別\\ *或其超類別 (superclass)*\\ 中宣告的方法。這意味著" -"如果超類別定義了比較運算子，*total_ordering* 將不會再次實作它，即使原始方法是" -"抽象的。" - -#: ../../library/functools.rst:333 -msgid "" -"Returning ``NotImplemented`` from the underlying comparison function for " -"unrecognised types is now supported." -msgstr "現在支援從底層對於未識別型別的比較函式回傳 ``NotImplemented``。" - -#: ../../library/functools.rst:339 -msgid "" -"A singleton object used as a sentinel to reserve a place for positional " -"arguments when calling :func:`partial` and :func:`partialmethod`." -msgstr "" - -#: ../../library/functools.rst:347 -msgid "" -"Return a new :ref:`partial object` which when called will " -"behave like *func* called with the positional arguments *args* and keyword " -"arguments *keywords*. If more arguments are supplied to the call, they are " -"appended to *args*. If additional keyword arguments are supplied, they " -"extend and override *keywords*. Roughly equivalent to::" -msgstr "" -"回傳一個新的 :ref:`partial 物件 `，它在被呼叫時的行為類似於" -"使用位置引數 *args* 和關鍵字引數 *keywords* 呼叫的 *func*。如果向呼叫提供更多" -"引數，它們將被附加到 *args*。如果提供了額外的關鍵字引數，它們會擴充並覆寫 " -"*keywords*。大致相當於： ::" - -#: ../../library/functools.rst:354 -msgid "" -"def partial(func, /, *args, **keywords):\n" -" def newfunc(*more_args, **more_keywords):\n" -" return func(*args, *more_args, **(keywords | more_keywords))\n" -" newfunc.func = func\n" -" newfunc.args = args\n" -" newfunc.keywords = keywords\n" -" return newfunc" -msgstr "" -"def partial(func, /, *args, **keywords):\n" -" def newfunc(*more_args, **more_keywords):\n" -" return func(*args, *more_args, **(keywords | more_keywords))\n" -" newfunc.func = func\n" -" newfunc.args = args\n" -" newfunc.keywords = keywords\n" -" return newfunc" - -#: ../../library/functools.rst:362 -msgid "" -"The :func:`!partial` function is used for partial function application which " -"\"freezes\" some portion of a function's arguments and/or keywords resulting " -"in a new object with a simplified signature. For example, :func:`partial` " -"can be used to create a callable that behaves like the :func:`int` function " -"where the *base* argument defaults to ``2``:" -msgstr "" -":func:`!partial` 用於部分函式應用程序，它「凍結」函式引數和/或關鍵字的某些部" -"分，從而產生具有簡化簽名的新物件。例如，:func:`partial` 可用來建立可呼叫函" -"式，其行為類似於 :func:`int` 函式，其中 *base* 引數預設為 2：" - -#: ../../library/functools.rst:368 -msgid "" -">>> basetwo = partial(int, base=2)\n" -">>> basetwo.__doc__ = 'Convert base 2 string to an int.'\n" -">>> basetwo('10010')\n" -"18" -msgstr "" -">>> basetwo = partial(int, base=2)\n" -">>> basetwo.__doc__ = 'Convert base 2 string to an int.'\n" -">>> basetwo('10010')\n" -"18" - -#: ../../library/functools.rst:375 -msgid "" -"If :data:`Placeholder` sentinels are present in *args*, they will be filled " -"first when :func:`!partial` is called. This makes it possible to pre-fill " -"any positional argument with a call to :func:`!partial`; without :data:`!" -"Placeholder`, only the chosen number of leading positional arguments can be " -"pre-filled." -msgstr "" - -#: ../../library/functools.rst:380 -msgid "" -"If any :data:`!Placeholder` sentinels are present, all must be filled at " -"call time:" -msgstr "" - -#: ../../library/functools.rst:382 -msgid "" -">>> say_to_world = partial(print, Placeholder, Placeholder, \"world!\")\n" -">>> say_to_world('Hello', 'dear')\n" -"Hello dear world!" -msgstr "" -">>> say_to_world = partial(print, Placeholder, Placeholder, \"world!\")\n" -">>> say_to_world('Hello', 'dear')\n" -"Hello dear world!" - -#: ../../library/functools.rst:388 -msgid "" -"Calling ``say_to_world('Hello')`` raises a :exc:`TypeError`, because only " -"one positional argument is provided, but there are two placeholders that " -"must be filled in." -msgstr "" - -#: ../../library/functools.rst:392 -msgid "" -"If :func:`!partial` is applied to an existing :func:`!partial` object, :data:" -"`!Placeholder` sentinels of the input object are filled in with new " -"positional arguments. A placeholder can be retained by inserting a new :data:" -"`!Placeholder` sentinel to the place held by a previous :data:`!Placeholder`:" -msgstr "" - -#: ../../library/functools.rst:398 -msgid "" -">>> from functools import partial, Placeholder as _\n" -">>> remove = partial(str.replace, _, _, '')\n" -">>> message = 'Hello, dear dear world!'\n" -">>> remove(message, ' dear')\n" -"'Hello, world!'\n" -">>> remove_dear = partial(remove, _, ' dear')\n" -">>> remove_dear(message)\n" -"'Hello, world!'\n" -">>> remove_first_dear = partial(remove_dear, _, 1)\n" -">>> remove_first_dear(message)\n" -"'Hello, dear world!'" -msgstr "" -">>> from functools import partial, Placeholder as _\n" -">>> remove = partial(str.replace, _, _, '')\n" -">>> message = 'Hello, dear dear world!'\n" -">>> remove(message, ' dear')\n" -"'Hello, world!'\n" -">>> remove_dear = partial(remove, _, ' dear')\n" -">>> remove_dear(message)\n" -"'Hello, world!'\n" -">>> remove_first_dear = partial(remove_dear, _, 1)\n" -">>> remove_first_dear(message)\n" -"'Hello, dear world!'" - -#: ../../library/functools.rst:412 -msgid "" -":data:`!Placeholder` cannot be passed to :func:`!partial` as a keyword " -"argument." -msgstr "" - -#: ../../library/functools.rst:414 -msgid "Added support for :data:`Placeholder` in positional arguments." -msgstr "" - -#: ../../library/functools.rst:419 -msgid "" -"Return a new :class:`partialmethod` descriptor which behaves like :class:" -"`partial` except that it is designed to be used as a method definition " -"rather than being directly callable." -msgstr "" -"回傳一個新的 :class:`partialmethod` 描述器 (descriptor)，其行為類似於 :class:" -"`partial`，只不過它被設計為用於方法定義而不能直接呼叫。" - -#: ../../library/functools.rst:423 -msgid "" -"*func* must be a :term:`descriptor` or a callable (objects which are both, " -"like normal functions, are handled as descriptors)." -msgstr "" -"*func* 必須是一個 :term:`descriptor` 或可呼叫物件（兩者兼具的物件，就像普通函" -"式一樣，會被當作描述器處理）。" - -#: ../../library/functools.rst:426 -msgid "" -"When *func* is a descriptor (such as a normal Python function, :func:" -"`classmethod`, :func:`staticmethod`, :func:`~abc.abstractmethod` or another " -"instance of :class:`partialmethod`), calls to ``__get__`` are delegated to " -"the underlying descriptor, and an appropriate :ref:`partial object` returned as the result." -msgstr "" -"當 *func* 是描述器時（例如普通的 Python 函式、:func:`classmethod`、:func:" -"`staticmethod`、:func:`~abc.abstractmethod` 或 :class:`partialmethod` 的另一" -"個實例），對 ``__get__`` 的呼叫將被委託 (delegated) 給底層描述器，且一個適當" -"的 :ref:`partial 物件 `\\ 會被作為結果回傳。" - -#: ../../library/functools.rst:432 -msgid "" -"When *func* is a non-descriptor callable, an appropriate bound method is " -"created dynamically. This behaves like a normal Python function when used as " -"a method: the *self* argument will be inserted as the first positional " -"argument, even before the *args* and *keywords* supplied to the :class:" -"`partialmethod` constructor." -msgstr "" -"當 *func* 是非描述器可呼叫物件 (non-descriptor callable) 時，會動態建立適當的" -"繫結方法 (bound method)。當被作為方法使用時，其行為類似於普通的 Python 函式：" -"*self* 引數將作為第一個位置引數插入，甚至會在提供給 :class:`partialmethod` 建" -"構函式的 *args* 和 *keywords* 的前面。" - -#: ../../library/functools.rst:440 -msgid "" -">>> class Cell:\n" -"... def __init__(self):\n" -"... self._alive = False\n" -"... @property\n" -"... def alive(self):\n" -"... return self._alive\n" -"... def set_state(self, state):\n" -"... self._alive = bool(state)\n" -"... set_alive = partialmethod(set_state, True)\n" -"... set_dead = partialmethod(set_state, False)\n" -"...\n" -">>> c = Cell()\n" -">>> c.alive\n" -"False\n" -">>> c.set_alive()\n" -">>> c.alive\n" -"True" -msgstr "" -">>> class Cell:\n" -"... def __init__(self):\n" -"... self._alive = False\n" -"... @property\n" -"... def alive(self):\n" -"... return self._alive\n" -"... def set_state(self, state):\n" -"... self._alive = bool(state)\n" -"... set_alive = partialmethod(set_state, True)\n" -"... set_dead = partialmethod(set_state, False)\n" -"...\n" -">>> c = Cell()\n" -">>> c.alive\n" -"False\n" -">>> c.set_alive()\n" -">>> c.alive\n" -"True" - -#: ../../library/functools.rst:463 -msgid "" -"Apply *function* of two arguments cumulatively to the items of *iterable*, " -"from left to right, so as to reduce the iterable to a single value. For " -"example, ``reduce(lambda x, y: x+y, [1, 2, 3, 4, 5])`` calculates " -"``((((1+2)+3)+4)+5)``. The left argument, *x*, is the accumulated value and " -"the right argument, *y*, is the update value from the *iterable*. If the " -"optional *initial* is present, it is placed before the items of the iterable " -"in the calculation, and serves as a default when the iterable is empty. If " -"*initial* is not given and *iterable* contains only one item, the first item " -"is returned." -msgstr "" -"從左到右，將兩個引數的 *function* 累加運用到 *iterable* 的項目上，從而將可疊" -"代物件減少為單一值。例如，``reduce(lambda x, y: x+y, [1, 2, 3, 4, 5])`` 會計" -"算出 ``((((1+2)+3)+4)+5)``。左邊的引數 *x* 是累積值，右邊的引數 *y* 是來自 " -"*iterable* 的更新值。如果可選的 *initial* 存在，則在計算中會將其放置在可疊代" -"物件的項目之前，並在可疊代物件為空時作為預設值。如果未給定 *initial* 且 " -"*iterable* 僅包含一個項目，則回傳第一個項目。" - -#: ../../library/functools.rst:472 -msgid "Roughly equivalent to::" -msgstr "大致相當於： ::" - -#: ../../library/functools.rst:474 -msgid "" -"initial_missing = object()\n" -"\n" -"def reduce(function, iterable, /, initial=initial_missing):\n" -" it = iter(iterable)\n" -" if initial is initial_missing:\n" -" value = next(it)\n" -" else:\n" -" value = initial\n" -" for element in it:\n" -" value = function(value, element)\n" -" return value" -msgstr "" -"initial_missing = object()\n" -"\n" -"def reduce(function, iterable, /, initial=initial_missing):\n" -" it = iter(iterable)\n" -" if initial is initial_missing:\n" -" value = next(it)\n" -" else:\n" -" value = initial\n" -" for element in it:\n" -" value = function(value, element)\n" -" return value" - -#: ../../library/functools.rst:486 -msgid "" -"See :func:`itertools.accumulate` for an iterator that yields all " -"intermediate values." -msgstr "" -"請參閱 :func:`itertools.accumulate` 以了解產生 (yield) 所有中間值 " -"(intermediate value) 的疊代器。" - -#: ../../library/functools.rst:489 -msgid "*initial* is now supported as a keyword argument." -msgstr "" - -#: ../../library/functools.rst:494 -msgid "" -"Transform a function into a :term:`single-dispatch ` :term:" -"`generic function`." -msgstr "" -"將函式轉換為\\ :term:`單一調度 `\\ :term:`泛型函式 `。" - -#: ../../library/functools.rst:497 -msgid "" -"To define a generic function, decorate it with the ``@singledispatch`` " -"decorator. When defining a function using ``@singledispatch``, note that the " -"dispatch happens on the type of the first argument::" -msgstr "" -"若要定義泛型函式，請使用 ``@singledispatch`` 裝飾器對其裝飾。請注意，使用 " -"``@singledispatch`` 定義函式時，分派調度 (dispatch) 是發生在第一個引數的型別" -"上： ::" - -#: ../../library/functools.rst:501 -msgid "" -">>> from functools import singledispatch\n" -">>> @singledispatch\n" -"... def fun(arg, verbose=False):\n" -"... if verbose:\n" -"... print(\"Let me just say,\", end=\" \")\n" -"... print(arg)" -msgstr "" -">>> from functools import singledispatch\n" -">>> @singledispatch\n" -"... def fun(arg, verbose=False):\n" -"... if verbose:\n" -"... print(\"Let me just say,\", end=\" \")\n" -"... print(arg)" - -#: ../../library/functools.rst:511 -msgid "" -"To add overloaded implementations to the function, use the :func:`!register` " -"attribute of the generic function, which can be used as a decorator. For " -"functions annotated with types, the decorator will infer the type of the " -"first argument automatically::" -msgstr "" -"若要為函式新增過載實作，請使用泛型函式的 :func:`!register` 屬性，該屬性可用作" -"裝飾器。對於以型別來註釋的函式，裝飾器將自動推斷第一個引數的型別： ::" - -#: ../../library/functools.rst:516 -msgid "" -">>> @fun.register\n" -"... def _(arg: int, verbose=False):\n" -"... if verbose:\n" -"... print(\"Strength in numbers, eh?\", end=\" \")\n" -"... print(arg)\n" -"...\n" -">>> @fun.register\n" -"... def _(arg: list, verbose=False):\n" -"... if verbose:\n" -"... print(\"Enumerate this:\")\n" -"... for i, elem in enumerate(arg):\n" -"... print(i, elem)" -msgstr "" -">>> @fun.register\n" -"... def _(arg: int, verbose=False):\n" -"... if verbose:\n" -"... print(\"Strength in numbers, eh?\", end=\" \")\n" -"... print(arg)\n" -"...\n" -">>> @fun.register\n" -"... def _(arg: list, verbose=False):\n" -"... if verbose:\n" -"... print(\"Enumerate this:\")\n" -"... for i, elem in enumerate(arg):\n" -"... print(i, elem)" - -#: ../../library/functools.rst:529 -msgid ":class:`typing.Union` can also be used::" -msgstr "也可以使用 :data:`typing.Union`： ::" - -#: ../../library/functools.rst:531 -msgid "" -">>> @fun.register\n" -"... def _(arg: int | float, verbose=False):\n" -"... if verbose:\n" -"... print(\"Strength in numbers, eh?\", end=\" \")\n" -"... print(arg)\n" -"...\n" -">>> from typing import Union\n" -">>> @fun.register\n" -"... def _(arg: Union[list, set], verbose=False):\n" -"... if verbose:\n" -"... print(\"Enumerate this:\")\n" -"... for i, elem in enumerate(arg):\n" -"... print(i, elem)\n" -"..." -msgstr "" -">>> @fun.register\n" -"... def _(arg: int | float, verbose=False):\n" -"... if verbose:\n" -"... print(\"Strength in numbers, eh?\", end=\" \")\n" -"... print(arg)\n" -"...\n" -">>> from typing import Union\n" -">>> @fun.register\n" -"... def _(arg: Union[list, set], verbose=False):\n" -"... if verbose:\n" -"... print(\"Enumerate this:\")\n" -"... for i, elem in enumerate(arg):\n" -"... print(i, elem)\n" -"..." - -#: ../../library/functools.rst:546 -msgid "" -"For code which doesn't use type annotations, the appropriate type argument " -"can be passed explicitly to the decorator itself::" -msgstr "" -"對於不使用型別註釋的程式碼，可以將適當的型別引數明確傳遞給裝飾器本身： ::" - -#: ../../library/functools.rst:549 -msgid "" -">>> @fun.register(complex)\n" -"... def _(arg, verbose=False):\n" -"... if verbose:\n" -"... print(\"Better than complicated.\", end=\" \")\n" -"... print(arg.real, arg.imag)\n" -"..." -msgstr "" -">>> @fun.register(complex)\n" -"... def _(arg, verbose=False):\n" -"... if verbose:\n" -"... print(\"Better than complicated.\", end=\" \")\n" -"... print(arg.real, arg.imag)\n" -"..." - -#: ../../library/functools.rst:556 -msgid "" -"For code that dispatches on a collections type (e.g., ``list``), but wants " -"to typehint the items of the collection (e.g., ``list[int]``), the dispatch " -"type should be passed explicitly to the decorator itself with the typehint " -"going into the function definition::" -msgstr "" - -#: ../../library/functools.rst:561 -msgid "" -">>> @fun.register(list)\n" -"... def _(arg: list[int], verbose=False):\n" -"... if verbose:\n" -"... print(\"Enumerate this:\")\n" -"... for i, elem in enumerate(arg):\n" -"... print(i, elem)" -msgstr "" -">>> @fun.register(list)\n" -"... def _(arg: list[int], verbose=False):\n" -"... if verbose:\n" -"... print(\"Enumerate this:\")\n" -"... for i, elem in enumerate(arg):\n" -"... print(i, elem)" - -#: ../../library/functools.rst:570 -msgid "" -"At runtime the function will dispatch on an instance of a list regardless of " -"the type contained within the list i.e. ``[1,2,3]`` will be dispatched the " -"same as ``[\"foo\", \"bar\", \"baz\"]``. The annotation provided in this " -"example is for static type checkers only and has no runtime impact." -msgstr "" - -#: ../../library/functools.rst:576 -msgid "" -"To enable registering :term:`lambdas` and pre-existing functions, " -"the :func:`~singledispatch.register` attribute can also be used in a " -"functional form::" -msgstr "" -"若要啟用註冊 :term:`lambdas` 和預先存在的函式，:func:" -"`~singledispatch.register` 屬性也能以函式形式使用： ::" - -#: ../../library/functools.rst:579 -msgid "" -">>> def nothing(arg, verbose=False):\n" -"... print(\"Nothing.\")\n" -"...\n" -">>> fun.register(type(None), nothing)" -msgstr "" -">>> def nothing(arg, verbose=False):\n" -"... print(\"Nothing.\")\n" -"...\n" -">>> fun.register(type(None), nothing)" - -#: ../../library/functools.rst:584 -msgid "" -"The :func:`~singledispatch.register` attribute returns the undecorated " -"function. This enables decorator stacking, :mod:`pickling`, and the " -"creation of unit tests for each variant independently::" -msgstr "" -":func:`~singledispatch.register` 屬性回傳未加裝飾器的函式。這讓使得裝飾器堆" -"疊 (decorator stacking)、:mod:`pickling` 以及為每個變體獨立建立單元測" -"試成為可能：" - -#: ../../library/functools.rst:588 -msgid "" -">>> @fun.register(float)\n" -"... @fun.register(Decimal)\n" -"... def fun_num(arg, verbose=False):\n" -"... if verbose:\n" -"... print(\"Half of your number:\", end=\" \")\n" -"... print(arg / 2)\n" -"...\n" -">>> fun_num is fun\n" -"False" -msgstr "" -">>> @fun.register(float)\n" -"... @fun.register(Decimal)\n" -"... def fun_num(arg, verbose=False):\n" -"... if verbose:\n" -"... print(\"Half of your number:\", end=\" \")\n" -"... print(arg / 2)\n" -"...\n" -">>> fun_num is fun\n" -"False" - -#: ../../library/functools.rst:598 -msgid "" -"When called, the generic function dispatches on the type of the first " -"argument::" -msgstr "呼叫時，泛型函式會分派第一個引數的型別： ::" - -#: ../../library/functools.rst:601 -msgid "" -">>> fun(\"Hello, world.\")\n" -"Hello, world.\n" -">>> fun(\"test.\", verbose=True)\n" -"Let me just say, test.\n" -">>> fun(42, verbose=True)\n" -"Strength in numbers, eh? 42\n" -">>> fun(['spam', 'spam', 'eggs', 'spam'], verbose=True)\n" -"Enumerate this:\n" -"0 spam\n" -"1 spam\n" -"2 eggs\n" -"3 spam\n" -">>> fun(None)\n" -"Nothing.\n" -">>> fun(1.23)\n" -"0.615" -msgstr "" -">>> fun(\"Hello, world.\")\n" -"Hello, world.\n" -">>> fun(\"test.\", verbose=True)\n" -"Let me just say, test.\n" -">>> fun(42, verbose=True)\n" -"Strength in numbers, eh? 42\n" -">>> fun(['spam', 'spam', 'eggs', 'spam'], verbose=True)\n" -"Enumerate this:\n" -"0 spam\n" -"1 spam\n" -"2 eggs\n" -"3 spam\n" -">>> fun(None)\n" -"Nothing.\n" -">>> fun(1.23)\n" -"0.615" - -#: ../../library/functools.rst:618 -msgid "" -"Where there is no registered implementation for a specific type, its method " -"resolution order is used to find a more generic implementation. The original " -"function decorated with ``@singledispatch`` is registered for the base :" -"class:`object` type, which means it is used if no better implementation is " -"found." -msgstr "" -"如果沒有為特定型別註冊實作，則使用其方法解析順序 (method resolution order) 來" -"尋找更通用的實作。用 ``@singledispatch`` 裝飾的原始函式是為基底 :class:" -"`object` 型別註冊的，這意味著如果沒有找到更好的實作就會使用它。" - -#: ../../library/functools.rst:624 -msgid "" -"If an implementation is registered to an :term:`abstract base class`, " -"virtual subclasses of the base class will be dispatched to that " -"implementation::" -msgstr "" -"如果一個實作有被註冊到一個\\ :term:`抽象基底類別 `，則基" -"底類別的虛擬子類別將被分派到該實作： ::" - -#: ../../library/functools.rst:628 -msgid "" -">>> from collections.abc import Mapping\n" -">>> @fun.register\n" -"... def _(arg: Mapping, verbose=False):\n" -"... if verbose:\n" -"... print(\"Keys & Values\")\n" -"... for key, value in arg.items():\n" -"... print(key, \"=>\", value)\n" -"...\n" -">>> fun({\"a\": \"b\"})\n" -"a => b" -msgstr "" -">>> from collections.abc import Mapping\n" -">>> @fun.register\n" -"... def _(arg: Mapping, verbose=False):\n" -"... if verbose:\n" -"... print(\"Keys & Values\")\n" -"... for key, value in arg.items():\n" -"... print(key, \"=>\", value)\n" -"...\n" -">>> fun({\"a\": \"b\"})\n" -"a => b" - -#: ../../library/functools.rst:639 -msgid "" -"To check which implementation the generic function will choose for a given " -"type, use the ``dispatch()`` attribute::" -msgstr "" -"若要檢查泛型函式將為給定型別選擇哪種實作，請使用 ``dispatch()`` 屬性： ::" - -#: ../../library/functools.rst:642 -msgid "" -">>> fun.dispatch(float)\n" -"\n" -">>> fun.dispatch(dict) # note: default implementation\n" -"" -msgstr "" - -#: ../../library/functools.rst:647 -msgid "" -"To access all registered implementations, use the read-only ``registry`` " -"attribute::" -msgstr "若要存取所有已註冊的實作，請使用唯讀 ``registry`` 屬性： ::" - -#: ../../library/functools.rst:650 -msgid "" -">>> fun.registry.keys()\n" -"dict_keys([, , ,\n" -" , ,\n" -" ])\n" -">>> fun.registry[float]\n" -"\n" -">>> fun.registry[object]\n" -"" -msgstr "" -">>> fun.registry.keys()\n" -"dict_keys([, , ,\n" -" , ,\n" -" ])\n" -">>> fun.registry[float]\n" -"\n" -">>> fun.registry[object]\n" -"" - -#: ../../library/functools.rst:661 -msgid "" -"The :func:`~singledispatch.register` attribute now supports using type " -"annotations." -msgstr ":func:`~singledispatch.register` 屬性現在支援使用型別註釋。" - -#: ../../library/functools.rst:664 -msgid "" -"The :func:`~singledispatch.register` attribute now supports :class:`typing." -"Union` as a type annotation." -msgstr "" -":func:`~singledispatch.register` 屬性現在支援使用 :class:`typing.Union` 型別" -"註釋。" - -#: ../../library/functools.rst:671 -msgid "" -"Transform a method into a :term:`single-dispatch ` :term:" -"`generic function`." -msgstr "" -"將方法轉換為\\ :term:`單一調度 `\\ :term:`泛型函式 `。" - -#: ../../library/functools.rst:674 -msgid "" -"To define a generic method, decorate it with the ``@singledispatchmethod`` " -"decorator. When defining a method using ``@singledispatchmethod``, note that " -"the dispatch happens on the type of the first non-*self* or non-*cls* " -"argument::" -msgstr "" -"若要定義泛型方法，請使用 ``@singledispatchmethod`` 裝飾器對其裝飾。請注意，使" -"用 ``@singledispatchmethod`` 定義方法時，分派調度是發生在第一個非 *self* 或" -"非 *cls* 引數的型別上： ::" - -#: ../../library/functools.rst:679 -msgid "" -"class Negator:\n" -" @singledispatchmethod\n" -" def neg(self, arg):\n" -" raise NotImplementedError(\"Cannot negate a\")\n" -"\n" -" @neg.register\n" -" def _(self, arg: int):\n" -" return -arg\n" -"\n" -" @neg.register\n" -" def _(self, arg: bool):\n" -" return not arg" -msgstr "" -"class Negator:\n" -" @singledispatchmethod\n" -" def neg(self, arg):\n" -" raise NotImplementedError(\"Cannot negate a\")\n" -"\n" -" @neg.register\n" -" def _(self, arg: int):\n" -" return -arg\n" -"\n" -" @neg.register\n" -" def _(self, arg: bool):\n" -" return not arg" - -#: ../../library/functools.rst:692 -msgid "" -"``@singledispatchmethod`` supports nesting with other decorators such as :" -"deco:`classmethod`. Note that to allow for ``dispatcher.register``, " -"``singledispatchmethod`` must be the *outer most* decorator. Here is the " -"``Negator`` class with the ``neg`` methods bound to the class, rather than " -"an instance of the class::" -msgstr "" -"``@singledispatchmethod`` 支援與其他裝飾器巢狀使用 (nesting)，例如 :deco:" -"`classmethod`。請注意，為了使 ``dispatcher.register`` 可用，" -"``singledispatchmethod`` 必須是\\ *最外面的*\\ 裝飾器。以下範例是 " -"``Negator`` 類別，其 ``neg`` 方法繫結到該類別，而不是該類別的實例： ::" - -#: ../../library/functools.rst:698 -msgid "" -"class Negator:\n" -" @singledispatchmethod\n" -" @classmethod\n" -" def neg(cls, arg):\n" -" raise NotImplementedError(\"Cannot negate a\")\n" -"\n" -" @neg.register\n" -" @classmethod\n" -" def _(cls, arg: int):\n" -" return -arg\n" -"\n" -" @neg.register\n" -" @classmethod\n" -" def _(cls, arg: bool):\n" -" return not arg" -msgstr "" -"class Negator:\n" -" @singledispatchmethod\n" -" @classmethod\n" -" def neg(cls, arg):\n" -" raise NotImplementedError(\"Cannot negate a\")\n" -"\n" -" @neg.register\n" -" @classmethod\n" -" def _(cls, arg: int):\n" -" return -arg\n" -"\n" -" @neg.register\n" -" @classmethod\n" -" def _(cls, arg: bool):\n" -" return not arg" - -#: ../../library/functools.rst:714 -msgid "" -"The same pattern can be used for other similar decorators: :deco:" -"`staticmethod`, :deco:`~abc.abstractmethod`, and others." -msgstr "" -"相同的模式可用於其他類似的裝飾器：:deco:`staticmethod`、:deco:`~abc." -"abstractmethod` 等。" - -#: ../../library/functools.rst:722 -msgid "" -"Update a *wrapper* function to look like the *wrapped* function. The " -"optional arguments are tuples to specify which attributes of the original " -"function are assigned directly to the matching attributes on the wrapper " -"function and which attributes of the wrapper function are updated with the " -"corresponding attributes from the original function. The default values for " -"these arguments are the module level constants ``WRAPPER_ASSIGNMENTS`` " -"(which assigns to the wrapper function's :attr:`~function.__module__`, :attr:" -"`~function.__name__`, :attr:`~function.__qualname__`, :attr:`~function." -"__annotations__`, :attr:`~function.__type_params__`, and :attr:`~function." -"__doc__`, the documentation string) and ``WRAPPER_UPDATES`` (which updates " -"the wrapper function's :attr:`~function.__dict__`, i.e. the instance " -"dictionary)." -msgstr "" -"更新 *wrapper* 函式，使其看起來像 *wrapped* 函式。可選引數是元組，用於指定原" -"始函式的哪些屬性直接賦值給包裝函式上的匹配屬性，以及包裝函式的哪些屬性使用原" -"始函式中的對應屬性進行更新。這些引數的預設值是模組層級的常數 " -"``WRAPPER_ASSIGNMENTS``\\ （它賦值給包裝函式的 :attr:`~function." -"__module__`、:attr:`~function.__name__`、:attr:`~function.__qualname__`、:" -"attr:`~function.__annotations__`、:attr:`~function.__type_params__` 和 :attr:" -"`~function.__doc__` 文件字串 (docstring））和 ``WRAPPER_UPDATES``\\ （更新包" -"裝器函式的 :attr:`~function.__dict__`，即實例字典）。" - -#: ../../library/functools.rst:734 -msgid "" -"To allow access to the original function for introspection and other " -"purposes (e.g. bypassing a caching decorator such as :func:`lru_cache`), " -"this function automatically adds a ``__wrapped__`` attribute to the wrapper " -"that refers to the function being wrapped." -msgstr "" -"為了允許出於內省 (introspection) 和其他目的所對原始函式的存取（例如繞過快取裝" -"飾器，如 :func:`lru_cache`），此函式會自動向包裝器新增 ``__wrapped__`` 屬性，" -"該包裝器參照被包裝的函式。" - -#: ../../library/functools.rst:739 -msgid "" -"The main intended use for this function is in :term:`decorator` functions " -"which wrap the decorated function and return the wrapper. If the wrapper " -"function is not updated, the metadata of the returned function will reflect " -"the wrapper definition rather than the original function definition, which " -"is typically less than helpful." -msgstr "" -"此函式的主要用途是在 :term:`decorator` 函式中，它包裝函式並回傳包裝器。如果包" -"裝器函式未更新，則回傳函式的元資料 (metadata) 將反映包裝器定義而非原始函式定" -"義，這通常不太會有幫助。" - -#: ../../library/functools.rst:745 -msgid "" -":func:`update_wrapper` may be used with callables other than functions. Any " -"attributes named in *assigned* or *updated* that are missing from the object " -"being wrapped are ignored (i.e. this function will not attempt to set them " -"on the wrapper function). :exc:`AttributeError` is still raised if the " -"wrapper function itself is missing any attributes named in *updated*." -msgstr "" -":func:`update_wrapper` 可以與函式以外的可呼叫物件一起使用。被包裝的物件中缺少" -"的 *assigned* 或 *updated* 中指定的任何屬性都將被忽略（即此函式不會嘗試在包裝" -"器函式上設定它們）。如果包裝函式本身缺少 *updated* 中指定的任何屬性，仍然會引" -"發 :exc:`AttributeError`。" - -#: ../../library/functools.rst:751 -msgid "" -"The ``__wrapped__`` attribute is now automatically added. The :attr:" -"`~function.__annotations__` attribute is now copied by default. Missing " -"attributes no longer trigger an :exc:`AttributeError`." -msgstr "" -"現在會自動新增 ``__wrapped__`` 屬性。現在預設會複製 :attr:`~function." -"__annotations__` 屬性。缺少的屬性不再觸發 :exc:`AttributeError`。" - -#: ../../library/functools.rst:756 -msgid "" -"The ``__wrapped__`` attribute now always refers to the wrapped function, " -"even if that function defined a ``__wrapped__`` attribute. (see :issue:" -"`17482`)" -msgstr "" -"``__wrapped__`` 屬性現在都會參照包裝函式，即便函式有定義 ``__wrapped__`` 屬" -"性。（參見 :issue:`17482`）" - -#: ../../library/functools.rst:761 -msgid "" -"The :attr:`~function.__type_params__` attribute is now copied by default." -msgstr "現在預設會複製 :attr:`~function.__type_params__` 屬性。" - -#: ../../library/functools.rst:767 -msgid "" -"This is a convenience function for invoking :func:`update_wrapper` as a " -"function decorator when defining a wrapper function. It is equivalent to " -"``partial(update_wrapper, wrapped=wrapped, assigned=assigned, " -"updated=updated)``. For example::" -msgstr "" -"這是一個方便的函式，用於在定義包裝器函式時呼叫 :func:`update_wrapper` 作為函" -"式裝飾器。它相當於 ``partial(update_wrapper, wrapped=wrapped, " -"assigned=assigned, updated=updated)``。例如： ::" - -#: ../../library/functools.rst:772 -msgid "" -">>> from functools import wraps\n" -">>> def my_decorator(f):\n" -"... @wraps(f)\n" -"... def wrapper(*args, **kwds):\n" -"... print('Calling decorated function')\n" -"... return f(*args, **kwds)\n" -"... return wrapper\n" -"...\n" -">>> @my_decorator\n" -"... def example():\n" -"... \"\"\"Docstring\"\"\"\n" -"... print('Called example function')\n" -"...\n" -">>> example()\n" -"Calling decorated function\n" -"Called example function\n" -">>> example.__name__\n" -"'example'\n" -">>> example.__doc__\n" -"'Docstring'" -msgstr "" -">>> from functools import wraps\n" -">>> def my_decorator(f):\n" -"... @wraps(f)\n" -"... def wrapper(*args, **kwds):\n" -"... print('Calling decorated function')\n" -"... return f(*args, **kwds)\n" -"... return wrapper\n" -"...\n" -">>> @my_decorator\n" -"... def example():\n" -"... \"\"\"Docstring\"\"\"\n" -"... print('Called example function')\n" -"...\n" -">>> example()\n" -"Calling decorated function\n" -"Called example function\n" -">>> example.__name__\n" -"'example'\n" -">>> example.__doc__\n" -"'Docstring'" - -#: ../../library/functools.rst:793 -msgid "" -"Without the use of this decorator factory, the name of the example function " -"would have been ``'wrapper'``, and the docstring of the original :func:`!" -"example` would have been lost." -msgstr "" -"如果不使用這個裝飾器工廠 (decorator factory)，範例函式的名稱將會是 " -"``'wrapper'``，並且原始 :func:`!example` 的文件字串將會遺失。" - -#: ../../library/functools.rst:801 -msgid ":class:`partial` Objects" -msgstr ":class:`partial` 物件" - -#: ../../library/functools.rst:803 -msgid "" -":class:`partial` objects are callable objects created by :func:`partial`. " -"They have three read-only attributes:" -msgstr "" -":class:`partial` 物件是由 :func:`partial` 所建立的可呼叫物件。它們有三個唯讀" -"屬性：" - -#: ../../library/functools.rst:809 -msgid "" -"A callable object or function. Calls to the :class:`partial` object will be " -"forwarded to :attr:`func` with new arguments and keywords." -msgstr "" -"一個可呼叫的物件或函式。對 :class:`partial` 物件的呼叫將被轉送到帶有新引數和" -"關鍵字的 :attr:`func`。" - -#: ../../library/functools.rst:815 -msgid "" -"The leftmost positional arguments that will be prepended to the positional " -"arguments provided to a :class:`partial` object call." -msgstr "" -"最左邊的位置引數將會被加入到提供給 :class:`partial` 物件呼叫的位置引數的前" -"面。" - -#: ../../library/functools.rst:821 -msgid "" -"The keyword arguments that will be supplied when the :class:`partial` object " -"is called." -msgstr "呼叫 :class:`partial` 物件時將提供的關鍵字引數。" - -#: ../../library/functools.rst:824 -msgid "" -":class:`partial` objects are like :ref:`function objects ` in that they are callable, weak referenceable, and can have " -"attributes. There are some important differences. For instance, the :attr:" -"`~definition.__name__` and :attr:`~definition.__doc__` attributes are not " -"created automatically." -msgstr "" -":class:`partial` 物件與\\ :ref:`函式物件 `\\ 類似，因為它" -"們是可呼叫的、可弱參照的 (weak referencable) 且可以具有屬性的。但有一些重要的" -"區別，例如，:attr:`~definition.__name__` 和 :attr:`~definition.__doc__` 屬性" -"不會自動建立。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Matt Wang , 2024 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-19 00:14+0000\n" +"PO-Revision-Date: 2024-05-11 16:02+0800\n" +"Last-Translator: Matt Wang \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/functools.rst:2 +msgid "" +":mod:`!functools` --- Higher-order functions and operations on callable " +"objects" +msgstr ":mod:`functools` --- 可呼叫物件上的高階函式與操作" + +#: ../../library/functools.rst:14 +msgid "**Source code:** :source:`Lib/functools.py`" +msgstr "**原始碼：**\\ :source:`Lib/functools.py`" + +#: ../../library/functools.rst:23 +msgid "" +"The :mod:`functools` module is for higher-order functions: functions that " +"act on or return other functions. In general, any callable object can be " +"treated as a function for the purposes of this module." +msgstr "" +":mod:`functools` 模組用於高階函式：作用於或回傳其他函式的函式。一般來說，任何" +"可呼叫物件都可以被視為用於此模組的函式。" + +#: ../../library/functools.rst:27 +msgid "The :mod:`functools` module defines the following functions:" +msgstr ":mod:`functools` 模組定義了以下函式：" + +#: ../../library/functools.rst:31 +msgid "" +"Simple lightweight unbounded function cache. Sometimes called `\"memoize\" " +"`_." +msgstr "" +"簡單的輕量級無繫結函式快取 (Simple lightweight unbounded function cache)。有" +"時稱之為 `\"memoize\"（記憶化） `_。" + +#: ../../library/functools.rst:34 +msgid "" +"Returns the same as ``lru_cache(maxsize=None)``, creating a thin wrapper " +"around a dictionary lookup for the function arguments. Because it never " +"needs to evict old values, this is smaller and faster than :func:`lru_cache` " +"with a size limit." +msgstr "" +"和 ``lru_cache(maxsize=None)`` 回傳相同的值，為函式引數建立一個字典查找的薄包" +"裝器。因為它永遠不需要丟棄舊值，所以這比有大小限制的 :func:`lru_cache` 更小、" +"更快。" + +#: ../../library/functools.rst:39 ../../library/functools.rst:297 +msgid "For example::" +msgstr "舉例來說： ::" + +#: ../../library/functools.rst:41 +msgid "" +"@cache\n" +"def factorial(n):\n" +" return n * factorial(n-1) if n else 1\n" +"\n" +">>> factorial(10) # no previously cached result, makes 11 recursive calls\n" +"3628800\n" +">>> factorial(5) # no new calls, just returns the cached result\n" +"120\n" +">>> factorial(12) # two new recursive calls, factorial(10) is cached\n" +"479001600" +msgstr "" +"@cache\n" +"def factorial(n):\n" +" return n * factorial(n-1) if n else 1\n" +"\n" +">>> factorial(10) # 沒有先前的快取結果，會進行 11 次遞迴呼叫\n" +"3628800\n" +">>> factorial(5) # 沒有新的呼叫，直接回傳被快取起來的結果\n" +"120\n" +">>> factorial(12) # 兩次新的遞迴呼叫，factorial(10) 有被快取起來\n" +"479001600" + +#: ../../library/functools.rst:52 ../../library/functools.rst:158 +msgid "" +"The cache is threadsafe so that the wrapped function can be used in multiple " +"threads. This means that the underlying data structure will remain coherent " +"during concurrent updates." +msgstr "" +"該快取是執行緒安全的 (threadsafe)，因此包裝的函式可以在多個執行緒中使用。這意" +"味著底層資料結構在並行更新期間將保持連貫 (coherent)。" + +#: ../../library/functools.rst:56 ../../library/functools.rst:162 +msgid "" +"It is possible for the wrapped function to be called more than once if " +"another thread makes an additional call before the initial call has been " +"completed and cached." +msgstr "" +"如果另一個執行緒在初始呼叫完成並快取之前進行額外的呼叫，則包裝的函式可能會被" +"多次呼叫。" + +#: ../../library/functools.rst:65 +msgid "" +"Transform a method of a class into a property whose value is computed once " +"and then cached as a normal attribute for the life of the instance. Similar " +"to :func:`property`, with the addition of caching. Useful for expensive " +"computed properties of instances that are otherwise effectively immutable." +msgstr "" +"將類別的一個方法轉換為屬性 (property)，其值會計算一次，然後在實例的生命週期內" +"快取為普通屬性。類似 :func:`property`，但增加了快取機制。對於除使用該裝飾器的" +"屬性外實質上幾乎是不可變 (immutable) 的實例，針對其所需要繁重計算會很有用。" + +#: ../../library/functools.rst:70 ../../library/functools.rst:142 +#: ../../library/functools.rst:438 +msgid "Example::" +msgstr "範例： ::" + +#: ../../library/functools.rst:72 +msgid "" +"class DataSet:\n" +"\n" +" def __init__(self, sequence_of_numbers):\n" +" self._data = tuple(sequence_of_numbers)\n" +"\n" +" @cached_property\n" +" def stdev(self):\n" +" return statistics.stdev(self._data)" +msgstr "" +"class DataSet:\n" +"\n" +" def __init__(self, sequence_of_numbers):\n" +" self._data = tuple(sequence_of_numbers)\n" +"\n" +" @cached_property\n" +" def stdev(self):\n" +" return statistics.stdev(self._data)" + +#: ../../library/functools.rst:81 +msgid "" +"The mechanics of :func:`cached_property` are somewhat different from :func:" +"`property`. A regular property blocks attribute writes unless a setter is " +"defined. In contrast, a *cached_property* allows writes." +msgstr "" +":func:`cached_property` 的機制與 :func:`property` 有所不同。除非定義了 " +"setter，否則常規屬性會阻止屬性的寫入。相反地，*cached_property* 則允許寫入。" + +#: ../../library/functools.rst:85 +msgid "" +"The *cached_property* decorator only runs on lookups and only when an " +"attribute of the same name doesn't exist. When it does run, the " +"*cached_property* writes to the attribute with the same name. Subsequent " +"attribute reads and writes take precedence over the *cached_property* method " +"and it works like a normal attribute." +msgstr "" +"*cached_property* 裝飾器僅在查找時且僅在同名屬性不存在時運行。當它運行時，" +"*cached_property* 會寫入同名的屬性。後續屬性讀取和寫入優先於 " +"*cached_property* 方法，並且它的工作方式與普通屬性類似。" + +#: ../../library/functools.rst:91 +msgid "" +"The cached value can be cleared by deleting the attribute. This allows the " +"*cached_property* method to run again." +msgstr "" +"可以透過刪除屬性來清除快取的值，這使得 *cached_property* 方法可以再次運行。" + +#: ../../library/functools.rst:94 +msgid "" +"The *cached_property* does not prevent a possible race condition in multi-" +"threaded usage. The getter function could run more than once on the same " +"instance, with the latest run setting the cached value. If the cached " +"property is idempotent or otherwise not harmful to run more than once on an " +"instance, this is fine. If synchronization is needed, implement the " +"necessary locking inside the decorated getter function or around the cached " +"property access." +msgstr "" +"*cached_property* 無法防止多執行緒使用中可能出現的競爭條件 (race condition)。" +"getter 函式可以在同一個實例上運行多次，最後一次運行會設定快取的值。所以快取的" +"屬性最好是冪等的 (idempotent)，或者在一個實例上運行多次不會有害，就不會有問" +"題。如果同步是必要的，請在裝飾的 getter 函式內部或在快取的屬性存取周圍實作必" +"要的鎖。" + +#: ../../library/functools.rst:102 +msgid "" +"Note, this decorator interferes with the operation of :pep:`412` key-sharing " +"dictionaries. This means that instance dictionaries can take more space " +"than usual." +msgstr "" +"請注意，此裝飾器會干擾 :pep:`412` 金鑰共用字典的操作。這意味著實例字典可能比" +"平常佔用更多的空間。" + +#: ../../library/functools.rst:106 +msgid "" +"Also, this decorator requires that the ``__dict__`` attribute on each " +"instance be a mutable mapping. This means it will not work with some types, " +"such as metaclasses (since the ``__dict__`` attributes on type instances are " +"read-only proxies for the class namespace), and those that specify " +"``__slots__`` without including ``__dict__`` as one of the defined slots (as " +"such classes don't provide a ``__dict__`` attribute at all)." +msgstr "" +"此外，此裝飾器要求每個實例上的 ``__dict__`` 屬性是可變對映 (mutable " +"mapping)。這意味著它不適用於某些型別，例如元類別 (metaclass)（因為型別實例上" +"的 ``__dict__`` 屬性是類別命名空間的唯讀代理），以及那些指定 ``__slots__`` 而" +"不包含 ``__dict__`` 的型別作為有定義的插槽之一（因為此種類別根本不提供 " +"``__dict__`` 屬性）。" + +#: ../../library/functools.rst:113 +msgid "" +"If a mutable mapping is not available or if space-efficient key sharing is " +"desired, an effect similar to :func:`cached_property` can also be achieved " +"by stacking :func:`property` on top of :func:`lru_cache`. See :ref:`faq-" +"cache-method-calls` for more details on how this differs from :func:" +"`cached_property`." +msgstr "" +"如果可變對映不可用或需要金鑰共享以節省空間，則也可以透過在 :func:`lru_cache` " +"之上堆疊 :func:`property` 來實作類似於 :func:`cached_property` 的效果。請參閱" +"\\ :ref:`faq-cache-method-calls`\\ 以了解有關這與 :func:`cached_property` 間" +"不同之處的更多詳細資訊。" + +#: ../../library/functools.rst:120 +msgid "" +"Prior to Python 3.12, ``cached_property`` included an undocumented lock to " +"ensure that in multi-threaded usage the getter function was guaranteed to " +"run only once per instance. However, the lock was per-property, not per-" +"instance, which could result in unacceptably high lock contention. In Python " +"3.12+ this locking is removed." +msgstr "" +"在 Python 3.12 之前，``cached_property`` 包含一個未以文件記錄的鎖，以確保在多" +"執行緒使用中能保證 getter 函式對於每個實例只會執行一次。然而，鎖是針對每個屬" +"性，而不是針對每個實例，這可能會導致無法被接受的嚴重鎖爭用 (lock " +"contention)。在 Python 3.12+ 中，此鎖已被刪除。" + +#: ../../library/functools.rst:130 +msgid "" +"Transform an old-style comparison function to a :term:`key function`. Used " +"with tools that accept key functions (such as :func:`sorted`, :func:`min`, :" +"func:`max`, :func:`heapq.nlargest`, :func:`heapq.nsmallest`, :func:" +"`itertools.groupby`). This function is primarily used as a transition tool " +"for programs being converted from Python 2 which supported the use of " +"comparison functions." +msgstr "" +"將舊式比較函式轉換為\\ :term:`鍵函式 `，能與接受鍵函式的工具一" +"起使用（例如 :func:`sorted`、:func:`min`、:func:`max`、:func:`heapq." +"nlargest`、:func:`heapq.nsmallest`、:func:`itertools.groupby`）。此函式主要作" +"為轉換工具，用於從有支援使用比較函式的 Python 2 轉換成的程式。" + +#: ../../library/functools.rst:137 +msgid "" +"A comparison function is any callable that accepts two arguments, compares " +"them, and returns a negative number for less-than, zero for equality, or a " +"positive number for greater-than. A key function is a callable that accepts " +"one argument and returns another value to be used as the sort key." +msgstr "" +"比較函式是任何能接受兩個引數、對它們進行比較，並回傳負數（小於）、零（相等）" +"或正數（大於）的可呼叫物件。鍵函式是接受一個引數並回傳另一個用作排序鍵之值的" +"可呼叫物件。" + +#: ../../library/functools.rst:144 +msgid "" +"sorted(iterable, key=cmp_to_key(locale.strcoll)) # locale-aware sort order" +msgstr "" + +#: ../../library/functools.rst:146 +msgid "" +"For sorting examples and a brief sorting tutorial, see :ref:`sortinghowto`." +msgstr "有關排序範例和簡短的排序教學，請參閱\\ :ref:`sortinghowto`。" + +#: ../../library/functools.rst:154 +msgid "" +"Decorator to wrap a function with a memoizing callable that saves up to the " +"*maxsize* most recent calls. It can save time when an expensive or I/O " +"bound function is periodically called with the same arguments." +msgstr "" +"以記憶化可呼叫物件來包裝函式的裝飾器，最多可省去 *maxsize* 個最近的呼叫。當使" +"用相同引數定期呼叫繁重的或 I/O 密集的函式時，它可以節省時間。" + +#: ../../library/functools.rst:166 +msgid "" +"Since a dictionary is used to cache results, the positional and keyword " +"arguments to the function must be :term:`hashable`." +msgstr "" +"由於字典用於快取結果，因此函式的位置引數和關鍵字引數必須是\\ :term:`可雜湊的 " +"`。" + +#: ../../library/functools.rst:169 +msgid "" +"Distinct argument patterns may be considered to be distinct calls with " +"separate cache entries. For example, ``f(a=1, b=2)`` and ``f(b=2, a=1)`` " +"differ in their keyword argument order and may have two separate cache " +"entries." +msgstr "" +"不同的引數模式可以被認為是具有不同快取條目的不同呼叫。例如，``f(a=1, b=2)`` " +"和 ``f(b=2, a=1)`` 的關鍵字引數順序不同，並且可能有兩個不同的快取條目。" + +#: ../../library/functools.rst:174 +msgid "" +"If *user_function* is specified, it must be a callable. This allows the " +"*lru_cache* decorator to be applied directly to a user function, leaving the " +"*maxsize* at its default value of 128::" +msgstr "" +"如果指定了 *user_function*，則它必須是個可呼叫物件。這使得 *lru_cache* 裝飾器" +"能夠直接應用於使用者函式，將 *maxsize* 保留為其預設值 128： ::" + +#: ../../library/functools.rst:178 +msgid "" +"@lru_cache\n" +"def count_vowels(sentence):\n" +" return sum(sentence.count(vowel) for vowel in 'AEIOUaeiou')" +msgstr "" +"@lru_cache\n" +"def count_vowels(sentence):\n" +" return sum(sentence.count(vowel) for vowel in 'AEIOUaeiou')" + +#: ../../library/functools.rst:182 +msgid "" +"If *maxsize* is set to ``None``, the LRU feature is disabled and the cache " +"can grow without bound." +msgstr "" +"如果 *maxsize* 設定為 ``None``，則 LRU 功能將被停用，且快取可以無限制地成長。" + +#: ../../library/functools.rst:185 +msgid "" +"If *typed* is set to true, function arguments of different types will be " +"cached separately. If *typed* is false, the implementation will usually " +"regard them as equivalent calls and only cache a single result. (Some types " +"such as *str* and *int* may be cached separately even when *typed* is false.)" +msgstr "" +"如果 *typed* 設定為 true，不同型別的函式引數將會被單獨快取起來。如果 *typed* " +"為 false，則實作通常會將它們視為等效呼叫，並且僅快取單一結果。（某些型別，例" +"如 *str* 和 *int* 可能會被單獨快取起來，即使 *typed* 為 false。）" + +#: ../../library/functools.rst:191 +msgid "" +"Note, type specificity applies only to the function's immediate arguments " +"rather than their contents. The scalar arguments, ``Decimal(42)`` and " +"``Fraction(42)`` are be treated as distinct calls with distinct results. In " +"contrast, the tuple arguments ``('answer', Decimal(42))`` and ``('answer', " +"Fraction(42))`` are treated as equivalent." +msgstr "" +"請注意，型別特異性 (type specificity) 僅適用於函式的直接引數而不是其內容。純" +"量 (scalar) 引數 ``Decimal(42)`` 和 ``Fraction(42)`` 被視為具有不同結果的不同" +"呼叫。相反地，元組引數 ``('answer', Decimal(42))`` 和 ``('answer', " +"Fraction(42))`` 被視為等效。" + +#: ../../library/functools.rst:197 +msgid "" +"The wrapped function is instrumented with a :func:`!cache_parameters` " +"function that returns a new :class:`dict` showing the values for *maxsize* " +"and *typed*. This is for information purposes only. Mutating the values " +"has no effect." +msgstr "" +"包裝的函式使用一個 :func:`!cache_parameters` 函式來進行偵測，該函式回傳一個新" +"的 :class:`dict` 以顯示 *maxsize* 和 *typed* 的值。這僅能顯示資訊，改變其值不" +"會有任何效果。" + +#: ../../library/functools.rst:205 +msgid "" +"To help measure the effectiveness of the cache and tune the *maxsize* " +"parameter, the wrapped function is instrumented with a :func:`!cache_info` " +"function that returns a :term:`named tuple` showing *hits*, *misses*, " +"*maxsize* and *currsize*." +msgstr "" +"為了輔助測量快取的有效性並調整 *maxsize* 參數，包裝的函式使用了一個 :func:`!" +"cache_info` 函式來做檢測，該函式會回傳一個\\ :term:`附名元組 `\\ 來顯示 *hits*、*misses*、*maxsize* 和 *currsize*。" + +#: ../../library/functools.rst:213 +msgid "" +"The decorator also provides a :func:`!cache_clear` function for clearing or " +"invalidating the cache." +msgstr "裝飾器還提供了一個 :func:`!cache_clear` 函式來清除或使快取失效。" + +#: ../../library/functools.rst:216 +msgid "" +"The original underlying function is accessible through the :attr:" +"`__wrapped__` attribute. This is useful for introspection, for bypassing " +"the cache, or for rewrapping the function with a different cache." +msgstr "" +"原本的底層函式可以透過 :attr:`__wrapped__` 屬性存取。這對於要自我檢查 " +"(introspection)、繞過快取或使用不同的快取重新包裝函式時非常有用。" + +#: ../../library/functools.rst:220 +msgid "" +"The cache keeps references to the arguments and return values until they age " +"out of the cache or until the cache is cleared." +msgstr "" +"快取會保留對引數和回傳值的參照，直到快取過時 (age out) 或快取被清除為止。" + +#: ../../library/functools.rst:223 +msgid "" +"If a method is cached, the ``self`` instance argument is included in the " +"cache. See :ref:`faq-cache-method-calls`" +msgstr "" +"如果方法被快取起來，則 ``self`` 實例引數將包含在快取中。請參閱\\ :ref:`faq-" +"cache-method-calls`" + +#: ../../library/functools.rst:226 +msgid "" +"An `LRU (least recently used) cache `_ works best when the " +"most recent calls are the best predictors of upcoming calls (for example, " +"the most popular articles on a news server tend to change each day). The " +"cache's size limit assures that the cache does not grow without bound on " +"long-running processes such as web servers." +msgstr "" +"當最近的呼叫是即將發生之呼叫的最佳預測因子時（例如新聞伺服器上最受歡迎的文章" +"往往每天都會發生變化），`LRU (least recently used) 快取 `_\\ " +"能發揮最好的效果。快取的大小限制可確保快取不會在長時間運行的行程（例如 Web 伺" +"服器）上無限制地成長。" + +#: ../../library/functools.rst:233 +msgid "" +"In general, the LRU cache should only be used when you want to reuse " +"previously computed values. Accordingly, it doesn't make sense to cache " +"functions with side-effects, functions that need to create distinct mutable " +"objects on each call (such as generators and async functions), or impure " +"functions such as time() or random()." +msgstr "" +"一般來說，僅當你想要重複使用先前計算的值時才應使用 LRU 快取。因此，快取具有 " +"side-effects 的函式、需要在每次呼叫時建立不同可變物件的函式（例如產生器和非同" +"步函式）或不純函式（impure function，例如 time() 或 random()）是沒有意義的。" + +#: ../../library/functools.rst:239 +msgid "Example of an LRU cache for static web content::" +msgstr "靜態網頁內容的 LRU 快取範例： ::" + +#: ../../library/functools.rst:241 +msgid "" +"@lru_cache(maxsize=32)\n" +"def get_pep(num):\n" +" 'Retrieve text of a Python Enhancement Proposal'\n" +" resource = f'https://peps.python.org/pep-{num:04d}'\n" +" try:\n" +" with urllib.request.urlopen(resource) as s:\n" +" return s.read()\n" +" except urllib.error.HTTPError:\n" +" return 'Not Found'\n" +"\n" +">>> for n in 8, 290, 308, 320, 8, 218, 320, 279, 289, 320, 9991:\n" +"... pep = get_pep(n)\n" +"... print(n, len(pep))\n" +"\n" +">>> get_pep.cache_info()\n" +"CacheInfo(hits=3, misses=8, maxsize=32, currsize=8)" +msgstr "" +"@lru_cache(maxsize=32)\n" +"def get_pep(num):\n" +" '取得 Python 改進提案的文字'\n" +" resource = f'https://peps.python.org/pep-{num:04d}'\n" +" try:\n" +" with urllib.request.urlopen(resource) as s:\n" +" return s.read()\n" +" except urllib.error.HTTPError:\n" +" return 'Not Found'\n" +"\n" +">>> for n in 8, 290, 308, 320, 8, 218, 320, 279, 289, 320, 9991:\n" +"... pep = get_pep(n)\n" +"... print(n, len(pep))\n" +"\n" +">>> get_pep.cache_info()\n" +"CacheInfo(hits=3, misses=8, maxsize=32, currsize=8)" + +#: ../../library/functools.rst:258 +msgid "" +"Example of efficiently computing `Fibonacci numbers `_ using a cache to implement a `dynamic " +"programming `_ technique::" +msgstr "" +"使用快取來實作\\ `動態規劃 (dynamic programming) `_ 技法以有效率地計算\\ `費波那契數 (Fibonacci " +"numbers) `_ 的範例： ::" + +#: ../../library/functools.rst:264 +msgid "" +"@lru_cache(maxsize=None)\n" +"def fib(n):\n" +" if n < 2:\n" +" return n\n" +" return fib(n-1) + fib(n-2)\n" +"\n" +">>> [fib(n) for n in range(16)]\n" +"[0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, 233, 377, 610]\n" +"\n" +">>> fib.cache_info()\n" +"CacheInfo(hits=28, misses=16, maxsize=None, currsize=16)" +msgstr "" +"@lru_cache(maxsize=None)\n" +"def fib(n):\n" +" if n < 2:\n" +" return n\n" +" return fib(n-1) + fib(n-2)\n" +"\n" +">>> [fib(n) for n in range(16)]\n" +"[0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, 233, 377, 610]\n" +"\n" +">>> fib.cache_info()\n" +"CacheInfo(hits=28, misses=16, maxsize=None, currsize=16)" + +#: ../../library/functools.rst:278 +msgid "Added the *typed* option." +msgstr "新增 *typed* 選項。" + +#: ../../library/functools.rst:281 +msgid "Added the *user_function* option." +msgstr "新增 *user_function* 選項。" + +#: ../../library/functools.rst:284 +msgid "Added the function :func:`!cache_parameters`" +msgstr "新增 :func:`!cache_parameters` 函式。" + +#: ../../library/functools.rst:289 +msgid "" +"Given a class defining one or more rich comparison ordering methods, this " +"class decorator supplies the rest. This simplifies the effort involved in " +"specifying all of the possible rich comparison operations:" +msgstr "" +"給定一個定義一個或多個 rich comparison 排序方法的類別，該類別裝飾器會提供其餘" +"部分。這簡化了指定所有可能的 rich comparison 操作所涉及的工作：" + +#: ../../library/functools.rst:293 +msgid "" +"The class must define one of :meth:`~object.__lt__`, :meth:`~object." +"__le__`, :meth:`~object.__gt__`, or :meth:`~object.__ge__`. In addition, the " +"class should supply an :meth:`~object.__eq__` method." +msgstr "" +"類別必須定義 :meth:`~object.__lt__`、:meth:`~object.__le__`、:meth:`~object." +"__gt__` 或 :meth:`~object.__ge__` 其中之一。此外，該類別應該提供 :meth:" +"`~object.__eq__` 方法。" + +#: ../../library/functools.rst:299 +msgid "" +"@total_ordering\n" +"class Student:\n" +" def _is_valid_operand(self, other):\n" +" return (hasattr(other, \"lastname\") and\n" +" hasattr(other, \"firstname\"))\n" +" def __eq__(self, other):\n" +" if not self._is_valid_operand(other):\n" +" return NotImplemented\n" +" return ((self.lastname.lower(), self.firstname.lower()) ==\n" +" (other.lastname.lower(), other.firstname.lower()))\n" +" def __lt__(self, other):\n" +" if not self._is_valid_operand(other):\n" +" return NotImplemented\n" +" return ((self.lastname.lower(), self.firstname.lower()) <\n" +" (other.lastname.lower(), other.firstname.lower()))" +msgstr "" +"@total_ordering\n" +"class Student:\n" +" def _is_valid_operand(self, other):\n" +" return (hasattr(other, \"lastname\") and\n" +" hasattr(other, \"firstname\"))\n" +" def __eq__(self, other):\n" +" if not self._is_valid_operand(other):\n" +" return NotImplemented\n" +" return ((self.lastname.lower(), self.firstname.lower()) ==\n" +" (other.lastname.lower(), other.firstname.lower()))\n" +" def __lt__(self, other):\n" +" if not self._is_valid_operand(other):\n" +" return NotImplemented\n" +" return ((self.lastname.lower(), self.firstname.lower()) <\n" +" (other.lastname.lower(), other.firstname.lower()))" + +#: ../../library/functools.rst:317 +msgid "" +"While this decorator makes it easy to create well behaved totally ordered " +"types, it *does* come at the cost of slower execution and more complex stack " +"traces for the derived comparison methods. If performance benchmarking " +"indicates this is a bottleneck for a given application, implementing all six " +"rich comparison methods instead is likely to provide an easy speed boost." +msgstr "" +"雖然此裝飾器可以輕鬆建立能好好運作的完全有序型別 (totally ordered types)，但" +"它\\ *的確*\\ 以衍生比較方法的執行速度較慢和堆疊追蹤 (stack trace) 較複雜做為" +"其代價。如果效能基準測試顯示這是給定應用程式的效能瓶頸，那麼實作全部六種 " +"rich comparison 方法通常能輕鬆地提升速度。" + +#: ../../library/functools.rst:326 +msgid "" +"This decorator makes no attempt to override methods that have been declared " +"in the class *or its superclasses*. Meaning that if a superclass defines a " +"comparison operator, *total_ordering* will not implement it again, even if " +"the original method is abstract." +msgstr "" +"此裝飾器不會嘗試覆寫類別\\ *或其超類別 (superclass)*\\ 中宣告的方法。這意味著" +"如果超類別定義了比較運算子，*total_ordering* 將不會再次實作它，即使原始方法是" +"抽象的。" + +#: ../../library/functools.rst:333 +msgid "" +"Returning ``NotImplemented`` from the underlying comparison function for " +"unrecognised types is now supported." +msgstr "現在支援從底層對於未識別型別的比較函式回傳 ``NotImplemented``。" + +#: ../../library/functools.rst:339 +msgid "" +"A singleton object used as a sentinel to reserve a place for positional " +"arguments when calling :func:`partial` and :func:`partialmethod`." +msgstr "" + +#: ../../library/functools.rst:347 +msgid "" +"Return a new :ref:`partial object` which when called will " +"behave like *func* called with the positional arguments *args* and keyword " +"arguments *keywords*. If more arguments are supplied to the call, they are " +"appended to *args*. If additional keyword arguments are supplied, they " +"extend and override *keywords*. Roughly equivalent to::" +msgstr "" +"回傳一個新的 :ref:`partial 物件 `，它在被呼叫時的行為類似於" +"使用位置引數 *args* 和關鍵字引數 *keywords* 呼叫的 *func*。如果向呼叫提供更多" +"引數，它們將被附加到 *args*。如果提供了額外的關鍵字引數，它們會擴充並覆寫 " +"*keywords*。大致相當於： ::" + +#: ../../library/functools.rst:354 +msgid "" +"def partial(func, /, *args, **keywords):\n" +" def newfunc(*more_args, **more_keywords):\n" +" return func(*args, *more_args, **(keywords | more_keywords))\n" +" newfunc.func = func\n" +" newfunc.args = args\n" +" newfunc.keywords = keywords\n" +" return newfunc" +msgstr "" +"def partial(func, /, *args, **keywords):\n" +" def newfunc(*more_args, **more_keywords):\n" +" return func(*args, *more_args, **(keywords | more_keywords))\n" +" newfunc.func = func\n" +" newfunc.args = args\n" +" newfunc.keywords = keywords\n" +" return newfunc" + +#: ../../library/functools.rst:362 +msgid "" +"The :func:`!partial` function is used for partial function application which " +"\"freezes\" some portion of a function's arguments and/or keywords resulting " +"in a new object with a simplified signature. For example, :func:`partial` " +"can be used to create a callable that behaves like the :func:`int` function " +"where the *base* argument defaults to ``2``:" +msgstr "" +":func:`!partial` 用於部分函式應用程序，它「凍結」函式引數和/或關鍵字的某些部" +"分，從而產生具有簡化簽名的新物件。例如，:func:`partial` 可用來建立可呼叫函" +"式，其行為類似於 :func:`int` 函式，其中 *base* 引數預設為 2：" + +#: ../../library/functools.rst:368 +msgid "" +">>> basetwo = partial(int, base=2)\n" +">>> basetwo.__doc__ = 'Convert base 2 string to an int.'\n" +">>> basetwo('10010')\n" +"18" +msgstr "" +">>> basetwo = partial(int, base=2)\n" +">>> basetwo.__doc__ = 'Convert base 2 string to an int.'\n" +">>> basetwo('10010')\n" +"18" + +#: ../../library/functools.rst:375 +msgid "" +"If :data:`Placeholder` sentinels are present in *args*, they will be filled " +"first when :func:`!partial` is called. This makes it possible to pre-fill " +"any positional argument with a call to :func:`!partial`; without :data:`!" +"Placeholder`, only the chosen number of leading positional arguments can be " +"pre-filled." +msgstr "" + +#: ../../library/functools.rst:380 +msgid "" +"If any :data:`!Placeholder` sentinels are present, all must be filled at " +"call time:" +msgstr "" + +#: ../../library/functools.rst:382 +msgid "" +">>> say_to_world = partial(print, Placeholder, Placeholder, \"world!\")\n" +">>> say_to_world('Hello', 'dear')\n" +"Hello dear world!" +msgstr "" +">>> say_to_world = partial(print, Placeholder, Placeholder, \"world!\")\n" +">>> say_to_world('Hello', 'dear')\n" +"Hello dear world!" + +#: ../../library/functools.rst:388 +msgid "" +"Calling ``say_to_world('Hello')`` raises a :exc:`TypeError`, because only " +"one positional argument is provided, but there are two placeholders that " +"must be filled in." +msgstr "" + +#: ../../library/functools.rst:392 +msgid "" +"If :func:`!partial` is applied to an existing :func:`!partial` object, :data:" +"`!Placeholder` sentinels of the input object are filled in with new " +"positional arguments. A placeholder can be retained by inserting a new :data:" +"`!Placeholder` sentinel to the place held by a previous :data:`!Placeholder`:" +msgstr "" + +#: ../../library/functools.rst:398 +msgid "" +">>> from functools import partial, Placeholder as _\n" +">>> remove = partial(str.replace, _, _, '')\n" +">>> message = 'Hello, dear dear world!'\n" +">>> remove(message, ' dear')\n" +"'Hello, world!'\n" +">>> remove_dear = partial(remove, _, ' dear')\n" +">>> remove_dear(message)\n" +"'Hello, world!'\n" +">>> remove_first_dear = partial(remove_dear, _, 1)\n" +">>> remove_first_dear(message)\n" +"'Hello, dear world!'" +msgstr "" +">>> from functools import partial, Placeholder as _\n" +">>> remove = partial(str.replace, _, _, '')\n" +">>> message = 'Hello, dear dear world!'\n" +">>> remove(message, ' dear')\n" +"'Hello, world!'\n" +">>> remove_dear = partial(remove, _, ' dear')\n" +">>> remove_dear(message)\n" +"'Hello, world!'\n" +">>> remove_first_dear = partial(remove_dear, _, 1)\n" +">>> remove_first_dear(message)\n" +"'Hello, dear world!'" + +#: ../../library/functools.rst:412 +msgid "" +":data:`!Placeholder` cannot be passed to :func:`!partial` as a keyword " +"argument." +msgstr "" + +#: ../../library/functools.rst:414 +msgid "Added support for :data:`Placeholder` in positional arguments." +msgstr "" + +#: ../../library/functools.rst:419 +msgid "" +"Return a new :class:`partialmethod` descriptor which behaves like :class:" +"`partial` except that it is designed to be used as a method definition " +"rather than being directly callable." +msgstr "" +"回傳一個新的 :class:`partialmethod` 描述器 (descriptor)，其行為類似於 :class:" +"`partial`，只不過它被設計為用於方法定義而不能直接呼叫。" + +#: ../../library/functools.rst:423 +msgid "" +"*func* must be a :term:`descriptor` or a callable (objects which are both, " +"like normal functions, are handled as descriptors)." +msgstr "" +"*func* 必須是一個 :term:`descriptor` 或可呼叫物件（兩者兼具的物件，就像普通函" +"式一樣，會被當作描述器處理）。" + +#: ../../library/functools.rst:426 +msgid "" +"When *func* is a descriptor (such as a normal Python function, :func:" +"`classmethod`, :func:`staticmethod`, :func:`~abc.abstractmethod` or another " +"instance of :class:`partialmethod`), calls to ``__get__`` are delegated to " +"the underlying descriptor, and an appropriate :ref:`partial object` returned as the result." +msgstr "" +"當 *func* 是描述器時（例如普通的 Python 函式、:func:`classmethod`、:func:" +"`staticmethod`、:func:`~abc.abstractmethod` 或 :class:`partialmethod` 的另一" +"個實例），對 ``__get__`` 的呼叫將被委託 (delegated) 給底層描述器，且一個適當" +"的 :ref:`partial 物件 `\\ 會被作為結果回傳。" + +#: ../../library/functools.rst:432 +msgid "" +"When *func* is a non-descriptor callable, an appropriate bound method is " +"created dynamically. This behaves like a normal Python function when used as " +"a method: the *self* argument will be inserted as the first positional " +"argument, even before the *args* and *keywords* supplied to the :class:" +"`partialmethod` constructor." +msgstr "" +"當 *func* 是非描述器可呼叫物件 (non-descriptor callable) 時，會動態建立適當的" +"繫結方法 (bound method)。當被作為方法使用時，其行為類似於普通的 Python 函式：" +"*self* 引數將作為第一個位置引數插入，甚至會在提供給 :class:`partialmethod` 建" +"構函式的 *args* 和 *keywords* 的前面。" + +#: ../../library/functools.rst:440 +msgid "" +">>> class Cell:\n" +"... def __init__(self):\n" +"... self._alive = False\n" +"... @property\n" +"... def alive(self):\n" +"... return self._alive\n" +"... def set_state(self, state):\n" +"... self._alive = bool(state)\n" +"... set_alive = partialmethod(set_state, True)\n" +"... set_dead = partialmethod(set_state, False)\n" +"...\n" +">>> c = Cell()\n" +">>> c.alive\n" +"False\n" +">>> c.set_alive()\n" +">>> c.alive\n" +"True" +msgstr "" +">>> class Cell:\n" +"... def __init__(self):\n" +"... self._alive = False\n" +"... @property\n" +"... def alive(self):\n" +"... return self._alive\n" +"... def set_state(self, state):\n" +"... self._alive = bool(state)\n" +"... set_alive = partialmethod(set_state, True)\n" +"... set_dead = partialmethod(set_state, False)\n" +"...\n" +">>> c = Cell()\n" +">>> c.alive\n" +"False\n" +">>> c.set_alive()\n" +">>> c.alive\n" +"True" + +#: ../../library/functools.rst:463 +msgid "" +"Apply *function* of two arguments cumulatively to the items of *iterable*, " +"from left to right, so as to reduce the iterable to a single value. For " +"example, ``reduce(lambda x, y: x+y, [1, 2, 3, 4, 5])`` calculates " +"``((((1+2)+3)+4)+5)``. The left argument, *x*, is the accumulated value and " +"the right argument, *y*, is the update value from the *iterable*. If the " +"optional *initial* is present, it is placed before the items of the iterable " +"in the calculation, and serves as a default when the iterable is empty. If " +"*initial* is not given and *iterable* contains only one item, the first item " +"is returned." +msgstr "" +"從左到右，將兩個引數的 *function* 累加運用到 *iterable* 的項目上，從而將可疊" +"代物件減少為單一值。例如，``reduce(lambda x, y: x+y, [1, 2, 3, 4, 5])`` 會計" +"算出 ``((((1+2)+3)+4)+5)``。左邊的引數 *x* 是累積值，右邊的引數 *y* 是來自 " +"*iterable* 的更新值。如果可選的 *initial* 存在，則在計算中會將其放置在可疊代" +"物件的項目之前，並在可疊代物件為空時作為預設值。如果未給定 *initial* 且 " +"*iterable* 僅包含一個項目，則回傳第一個項目。" + +#: ../../library/functools.rst:472 +msgid "Roughly equivalent to::" +msgstr "大致相當於： ::" + +#: ../../library/functools.rst:474 +msgid "" +"initial_missing = object()\n" +"\n" +"def reduce(function, iterable, /, initial=initial_missing):\n" +" it = iter(iterable)\n" +" if initial is initial_missing:\n" +" value = next(it)\n" +" else:\n" +" value = initial\n" +" for element in it:\n" +" value = function(value, element)\n" +" return value" +msgstr "" +"initial_missing = object()\n" +"\n" +"def reduce(function, iterable, /, initial=initial_missing):\n" +" it = iter(iterable)\n" +" if initial is initial_missing:\n" +" value = next(it)\n" +" else:\n" +" value = initial\n" +" for element in it:\n" +" value = function(value, element)\n" +" return value" + +#: ../../library/functools.rst:486 +msgid "" +"See :func:`itertools.accumulate` for an iterator that yields all " +"intermediate values." +msgstr "" +"請參閱 :func:`itertools.accumulate` 以了解產生 (yield) 所有中間值 " +"(intermediate value) 的疊代器。" + +#: ../../library/functools.rst:489 +msgid "*initial* is now supported as a keyword argument." +msgstr "" + +#: ../../library/functools.rst:494 +msgid "" +"Transform a function into a :term:`single-dispatch ` :term:" +"`generic function`." +msgstr "" +"將函式轉換為\\ :term:`單一調度 `\\ :term:`泛型函式 `。" + +#: ../../library/functools.rst:497 +msgid "" +"To define a generic function, decorate it with the ``@singledispatch`` " +"decorator. When defining a function using ``@singledispatch``, note that the " +"dispatch happens on the type of the first argument::" +msgstr "" +"若要定義泛型函式，請使用 ``@singledispatch`` 裝飾器對其裝飾。請注意，使用 " +"``@singledispatch`` 定義函式時，分派調度 (dispatch) 是發生在第一個引數的型別" +"上： ::" + +#: ../../library/functools.rst:501 +msgid "" +">>> from functools import singledispatch\n" +">>> @singledispatch\n" +"... def fun(arg, verbose=False):\n" +"... if verbose:\n" +"... print(\"Let me just say,\", end=\" \")\n" +"... print(arg)" +msgstr "" +">>> from functools import singledispatch\n" +">>> @singledispatch\n" +"... def fun(arg, verbose=False):\n" +"... if verbose:\n" +"... print(\"Let me just say,\", end=\" \")\n" +"... print(arg)" + +#: ../../library/functools.rst:511 +msgid "" +"To add overloaded implementations to the function, use the :func:`!register` " +"attribute of the generic function, which can be used as a decorator. For " +"functions annotated with types, the decorator will infer the type of the " +"first argument automatically::" +msgstr "" +"若要為函式新增過載實作，請使用泛型函式的 :func:`!register` 屬性，該屬性可用作" +"裝飾器。對於以型別來註釋的函式，裝飾器將自動推斷第一個引數的型別： ::" + +#: ../../library/functools.rst:516 +msgid "" +">>> @fun.register\n" +"... def _(arg: int, verbose=False):\n" +"... if verbose:\n" +"... print(\"Strength in numbers, eh?\", end=\" \")\n" +"... print(arg)\n" +"...\n" +">>> @fun.register\n" +"... def _(arg: list, verbose=False):\n" +"... if verbose:\n" +"... print(\"Enumerate this:\")\n" +"... for i, elem in enumerate(arg):\n" +"... print(i, elem)" +msgstr "" +">>> @fun.register\n" +"... def _(arg: int, verbose=False):\n" +"... if verbose:\n" +"... print(\"Strength in numbers, eh?\", end=\" \")\n" +"... print(arg)\n" +"...\n" +">>> @fun.register\n" +"... def _(arg: list, verbose=False):\n" +"... if verbose:\n" +"... print(\"Enumerate this:\")\n" +"... for i, elem in enumerate(arg):\n" +"... print(i, elem)" + +#: ../../library/functools.rst:529 +msgid ":class:`typing.Union` can also be used::" +msgstr "也可以使用 :data:`typing.Union`： ::" + +#: ../../library/functools.rst:531 +msgid "" +">>> @fun.register\n" +"... def _(arg: int | float, verbose=False):\n" +"... if verbose:\n" +"... print(\"Strength in numbers, eh?\", end=\" \")\n" +"... print(arg)\n" +"...\n" +">>> from typing import Union\n" +">>> @fun.register\n" +"... def _(arg: Union[list, set], verbose=False):\n" +"... if verbose:\n" +"... print(\"Enumerate this:\")\n" +"... for i, elem in enumerate(arg):\n" +"... print(i, elem)\n" +"..." +msgstr "" +">>> @fun.register\n" +"... def _(arg: int | float, verbose=False):\n" +"... if verbose:\n" +"... print(\"Strength in numbers, eh?\", end=\" \")\n" +"... print(arg)\n" +"...\n" +">>> from typing import Union\n" +">>> @fun.register\n" +"... def _(arg: Union[list, set], verbose=False):\n" +"... if verbose:\n" +"... print(\"Enumerate this:\")\n" +"... for i, elem in enumerate(arg):\n" +"... print(i, elem)\n" +"..." + +#: ../../library/functools.rst:546 +msgid "" +"For code which doesn't use type annotations, the appropriate type argument " +"can be passed explicitly to the decorator itself::" +msgstr "" +"對於不使用型別註釋的程式碼，可以將適當的型別引數明確傳遞給裝飾器本身： ::" + +#: ../../library/functools.rst:549 +msgid "" +">>> @fun.register(complex)\n" +"... def _(arg, verbose=False):\n" +"... if verbose:\n" +"... print(\"Better than complicated.\", end=\" \")\n" +"... print(arg.real, arg.imag)\n" +"..." +msgstr "" +">>> @fun.register(complex)\n" +"... def _(arg, verbose=False):\n" +"... if verbose:\n" +"... print(\"Better than complicated.\", end=\" \")\n" +"... print(arg.real, arg.imag)\n" +"..." + +#: ../../library/functools.rst:556 +msgid "" +"For code that dispatches on a collections type (e.g., ``list``), but wants " +"to typehint the items of the collection (e.g., ``list[int]``), the dispatch " +"type should be passed explicitly to the decorator itself with the typehint " +"going into the function definition::" +msgstr "" + +#: ../../library/functools.rst:561 +msgid "" +">>> @fun.register(list)\n" +"... def _(arg: list[int], verbose=False):\n" +"... if verbose:\n" +"... print(\"Enumerate this:\")\n" +"... for i, elem in enumerate(arg):\n" +"... print(i, elem)" +msgstr "" +">>> @fun.register(list)\n" +"... def _(arg: list[int], verbose=False):\n" +"... if verbose:\n" +"... print(\"Enumerate this:\")\n" +"... for i, elem in enumerate(arg):\n" +"... print(i, elem)" + +#: ../../library/functools.rst:570 +msgid "" +"At runtime the function will dispatch on an instance of a list regardless of " +"the type contained within the list i.e. ``[1,2,3]`` will be dispatched the " +"same as ``[\"foo\", \"bar\", \"baz\"]``. The annotation provided in this " +"example is for static type checkers only and has no runtime impact." +msgstr "" + +#: ../../library/functools.rst:576 +msgid "" +"To enable registering :term:`lambdas` and pre-existing functions, " +"the :func:`~singledispatch.register` attribute can also be used in a " +"functional form::" +msgstr "" +"若要啟用註冊 :term:`lambdas` 和預先存在的函式，:func:" +"`~singledispatch.register` 屬性也能以函式形式使用： ::" + +#: ../../library/functools.rst:579 +msgid "" +">>> def nothing(arg, verbose=False):\n" +"... print(\"Nothing.\")\n" +"...\n" +">>> fun.register(type(None), nothing)" +msgstr "" +">>> def nothing(arg, verbose=False):\n" +"... print(\"Nothing.\")\n" +"...\n" +">>> fun.register(type(None), nothing)" + +#: ../../library/functools.rst:584 +msgid "" +"The :func:`~singledispatch.register` attribute returns the undecorated " +"function. This enables decorator stacking, :mod:`pickling`, and the " +"creation of unit tests for each variant independently::" +msgstr "" +":func:`~singledispatch.register` 屬性回傳未加裝飾器的函式。這讓使得裝飾器堆" +"疊 (decorator stacking)、:mod:`pickling` 以及為每個變體獨立建立單元測" +"試成為可能：" + +#: ../../library/functools.rst:588 +msgid "" +">>> @fun.register(float)\n" +"... @fun.register(Decimal)\n" +"... def fun_num(arg, verbose=False):\n" +"... if verbose:\n" +"... print(\"Half of your number:\", end=\" \")\n" +"... print(arg / 2)\n" +"...\n" +">>> fun_num is fun\n" +"False" +msgstr "" +">>> @fun.register(float)\n" +"... @fun.register(Decimal)\n" +"... def fun_num(arg, verbose=False):\n" +"... if verbose:\n" +"... print(\"Half of your number:\", end=\" \")\n" +"... print(arg / 2)\n" +"...\n" +">>> fun_num is fun\n" +"False" + +#: ../../library/functools.rst:598 +msgid "" +"When called, the generic function dispatches on the type of the first " +"argument::" +msgstr "呼叫時，泛型函式會分派第一個引數的型別： ::" + +#: ../../library/functools.rst:601 +msgid "" +">>> fun(\"Hello, world.\")\n" +"Hello, world.\n" +">>> fun(\"test.\", verbose=True)\n" +"Let me just say, test.\n" +">>> fun(42, verbose=True)\n" +"Strength in numbers, eh? 42\n" +">>> fun(['spam', 'spam', 'eggs', 'spam'], verbose=True)\n" +"Enumerate this:\n" +"0 spam\n" +"1 spam\n" +"2 eggs\n" +"3 spam\n" +">>> fun(None)\n" +"Nothing.\n" +">>> fun(1.23)\n" +"0.615" +msgstr "" +">>> fun(\"Hello, world.\")\n" +"Hello, world.\n" +">>> fun(\"test.\", verbose=True)\n" +"Let me just say, test.\n" +">>> fun(42, verbose=True)\n" +"Strength in numbers, eh? 42\n" +">>> fun(['spam', 'spam', 'eggs', 'spam'], verbose=True)\n" +"Enumerate this:\n" +"0 spam\n" +"1 spam\n" +"2 eggs\n" +"3 spam\n" +">>> fun(None)\n" +"Nothing.\n" +">>> fun(1.23)\n" +"0.615" + +#: ../../library/functools.rst:618 +msgid "" +"Where there is no registered implementation for a specific type, its method " +"resolution order is used to find a more generic implementation. The original " +"function decorated with ``@singledispatch`` is registered for the base :" +"class:`object` type, which means it is used if no better implementation is " +"found." +msgstr "" +"如果沒有為特定型別註冊實作，則使用其方法解析順序 (method resolution order) 來" +"尋找更通用的實作。用 ``@singledispatch`` 裝飾的原始函式是為基底 :class:" +"`object` 型別註冊的，這意味著如果沒有找到更好的實作就會使用它。" + +#: ../../library/functools.rst:624 +msgid "" +"If an implementation is registered to an :term:`abstract base class`, " +"virtual subclasses of the base class will be dispatched to that " +"implementation::" +msgstr "" +"如果一個實作有被註冊到一個\\ :term:`抽象基底類別 `，則基" +"底類別的虛擬子類別將被分派到該實作： ::" + +#: ../../library/functools.rst:628 +msgid "" +">>> from collections.abc import Mapping\n" +">>> @fun.register\n" +"... def _(arg: Mapping, verbose=False):\n" +"... if verbose:\n" +"... print(\"Keys & Values\")\n" +"... for key, value in arg.items():\n" +"... print(key, \"=>\", value)\n" +"...\n" +">>> fun({\"a\": \"b\"})\n" +"a => b" +msgstr "" +">>> from collections.abc import Mapping\n" +">>> @fun.register\n" +"... def _(arg: Mapping, verbose=False):\n" +"... if verbose:\n" +"... print(\"Keys & Values\")\n" +"... for key, value in arg.items():\n" +"... print(key, \"=>\", value)\n" +"...\n" +">>> fun({\"a\": \"b\"})\n" +"a => b" + +#: ../../library/functools.rst:639 +msgid "" +"To check which implementation the generic function will choose for a given " +"type, use the ``dispatch()`` attribute::" +msgstr "" +"若要檢查泛型函式將為給定型別選擇哪種實作，請使用 ``dispatch()`` 屬性： ::" + +#: ../../library/functools.rst:642 +msgid "" +">>> fun.dispatch(float)\n" +"\n" +">>> fun.dispatch(dict) # note: default implementation\n" +"" +msgstr "" + +#: ../../library/functools.rst:647 +msgid "" +"To access all registered implementations, use the read-only ``registry`` " +"attribute::" +msgstr "若要存取所有已註冊的實作，請使用唯讀 ``registry`` 屬性： ::" + +#: ../../library/functools.rst:650 +msgid "" +">>> fun.registry.keys()\n" +"dict_keys([, , ,\n" +" , ,\n" +" ])\n" +">>> fun.registry[float]\n" +"\n" +">>> fun.registry[object]\n" +"" +msgstr "" +">>> fun.registry.keys()\n" +"dict_keys([, , ,\n" +" , ,\n" +" ])\n" +">>> fun.registry[float]\n" +"\n" +">>> fun.registry[object]\n" +"" + +#: ../../library/functools.rst:661 +msgid "" +"The :func:`~singledispatch.register` attribute now supports using type " +"annotations." +msgstr ":func:`~singledispatch.register` 屬性現在支援使用型別註釋。" + +#: ../../library/functools.rst:664 +msgid "" +"The :func:`~singledispatch.register` attribute now supports :class:`typing." +"Union` as a type annotation." +msgstr "" +":func:`~singledispatch.register` 屬性現在支援使用 :class:`typing.Union` 型別" +"註釋。" + +#: ../../library/functools.rst:671 +msgid "" +"Transform a method into a :term:`single-dispatch ` :term:" +"`generic function`." +msgstr "" +"將方法轉換為\\ :term:`單一調度 `\\ :term:`泛型函式 `。" + +#: ../../library/functools.rst:674 +msgid "" +"To define a generic method, decorate it with the ``@singledispatchmethod`` " +"decorator. When defining a method using ``@singledispatchmethod``, note that " +"the dispatch happens on the type of the first non-*self* or non-*cls* " +"argument::" +msgstr "" +"若要定義泛型方法，請使用 ``@singledispatchmethod`` 裝飾器對其裝飾。請注意，使" +"用 ``@singledispatchmethod`` 定義方法時，分派調度是發生在第一個非 *self* 或" +"非 *cls* 引數的型別上： ::" + +#: ../../library/functools.rst:679 +msgid "" +"class Negator:\n" +" @singledispatchmethod\n" +" def neg(self, arg):\n" +" raise NotImplementedError(\"Cannot negate a\")\n" +"\n" +" @neg.register\n" +" def _(self, arg: int):\n" +" return -arg\n" +"\n" +" @neg.register\n" +" def _(self, arg: bool):\n" +" return not arg" +msgstr "" +"class Negator:\n" +" @singledispatchmethod\n" +" def neg(self, arg):\n" +" raise NotImplementedError(\"Cannot negate a\")\n" +"\n" +" @neg.register\n" +" def _(self, arg: int):\n" +" return -arg\n" +"\n" +" @neg.register\n" +" def _(self, arg: bool):\n" +" return not arg" + +#: ../../library/functools.rst:692 +msgid "" +"``@singledispatchmethod`` supports nesting with other decorators such as :" +"deco:`classmethod`. Note that to allow for ``dispatcher.register``, " +"``singledispatchmethod`` must be the *outer most* decorator. Here is the " +"``Negator`` class with the ``neg`` methods bound to the class, rather than " +"an instance of the class::" +msgstr "" +"``@singledispatchmethod`` 支援與其他裝飾器巢狀使用 (nesting)，例如 :deco:" +"`classmethod`。請注意，為了使 ``dispatcher.register`` 可用，" +"``singledispatchmethod`` 必須是\\ *最外面的*\\ 裝飾器。以下範例是 " +"``Negator`` 類別，其 ``neg`` 方法繫結到該類別，而不是該類別的實例： ::" + +#: ../../library/functools.rst:698 +msgid "" +"class Negator:\n" +" @singledispatchmethod\n" +" @classmethod\n" +" def neg(cls, arg):\n" +" raise NotImplementedError(\"Cannot negate a\")\n" +"\n" +" @neg.register\n" +" @classmethod\n" +" def _(cls, arg: int):\n" +" return -arg\n" +"\n" +" @neg.register\n" +" @classmethod\n" +" def _(cls, arg: bool):\n" +" return not arg" +msgstr "" +"class Negator:\n" +" @singledispatchmethod\n" +" @classmethod\n" +" def neg(cls, arg):\n" +" raise NotImplementedError(\"Cannot negate a\")\n" +"\n" +" @neg.register\n" +" @classmethod\n" +" def _(cls, arg: int):\n" +" return -arg\n" +"\n" +" @neg.register\n" +" @classmethod\n" +" def _(cls, arg: bool):\n" +" return not arg" + +#: ../../library/functools.rst:714 +msgid "" +"The same pattern can be used for other similar decorators: :deco:" +"`staticmethod`, :deco:`~abc.abstractmethod`, and others." +msgstr "" +"相同的模式可用於其他類似的裝飾器：:deco:`staticmethod`、:deco:`~abc." +"abstractmethod` 等。" + +#: ../../library/functools.rst:722 +msgid "" +"Update a *wrapper* function to look like the *wrapped* function. The " +"optional arguments are tuples to specify which attributes of the original " +"function are assigned directly to the matching attributes on the wrapper " +"function and which attributes of the wrapper function are updated with the " +"corresponding attributes from the original function. The default values for " +"these arguments are the module level constants ``WRAPPER_ASSIGNMENTS`` " +"(which assigns to the wrapper function's :attr:`~function.__module__`, :attr:" +"`~function.__name__`, :attr:`~function.__qualname__`, :attr:`~function." +"__annotations__`, :attr:`~function.__type_params__`, and :attr:`~function." +"__doc__`, the documentation string) and ``WRAPPER_UPDATES`` (which updates " +"the wrapper function's :attr:`~function.__dict__`, i.e. the instance " +"dictionary)." +msgstr "" +"更新 *wrapper* 函式，使其看起來像 *wrapped* 函式。可選引數是元組，用於指定原" +"始函式的哪些屬性直接賦值給包裝函式上的匹配屬性，以及包裝函式的哪些屬性使用原" +"始函式中的對應屬性進行更新。這些引數的預設值是模組層級的常數 " +"``WRAPPER_ASSIGNMENTS``\\ （它賦值給包裝函式的 :attr:`~function." +"__module__`、:attr:`~function.__name__`、:attr:`~function.__qualname__`、:" +"attr:`~function.__annotations__`、:attr:`~function.__type_params__` 和 :attr:" +"`~function.__doc__` 文件字串 (docstring））和 ``WRAPPER_UPDATES``\\ （更新包" +"裝器函式的 :attr:`~function.__dict__`，即實例字典）。" + +#: ../../library/functools.rst:734 +msgid "" +"To allow access to the original function for introspection and other " +"purposes (e.g. bypassing a caching decorator such as :func:`lru_cache`), " +"this function automatically adds a ``__wrapped__`` attribute to the wrapper " +"that refers to the function being wrapped." +msgstr "" +"為了允許出於內省 (introspection) 和其他目的所對原始函式的存取（例如繞過快取裝" +"飾器，如 :func:`lru_cache`），此函式會自動向包裝器新增 ``__wrapped__`` 屬性，" +"該包裝器參照被包裝的函式。" + +#: ../../library/functools.rst:739 +msgid "" +"The main intended use for this function is in :term:`decorator` functions " +"which wrap the decorated function and return the wrapper. If the wrapper " +"function is not updated, the metadata of the returned function will reflect " +"the wrapper definition rather than the original function definition, which " +"is typically less than helpful." +msgstr "" +"此函式的主要用途是在 :term:`decorator` 函式中，它包裝函式並回傳包裝器。如果包" +"裝器函式未更新，則回傳函式的元資料 (metadata) 將反映包裝器定義而非原始函式定" +"義，這通常不太會有幫助。" + +#: ../../library/functools.rst:745 +msgid "" +":func:`update_wrapper` may be used with callables other than functions. Any " +"attributes named in *assigned* or *updated* that are missing from the object " +"being wrapped are ignored (i.e. this function will not attempt to set them " +"on the wrapper function). :exc:`AttributeError` is still raised if the " +"wrapper function itself is missing any attributes named in *updated*." +msgstr "" +":func:`update_wrapper` 可以與函式以外的可呼叫物件一起使用。被包裝的物件中缺少" +"的 *assigned* 或 *updated* 中指定的任何屬性都將被忽略（即此函式不會嘗試在包裝" +"器函式上設定它們）。如果包裝函式本身缺少 *updated* 中指定的任何屬性，仍然會引" +"發 :exc:`AttributeError`。" + +#: ../../library/functools.rst:751 +msgid "" +"The ``__wrapped__`` attribute is now automatically added. The :attr:" +"`~function.__annotations__` attribute is now copied by default. Missing " +"attributes no longer trigger an :exc:`AttributeError`." +msgstr "" +"現在會自動新增 ``__wrapped__`` 屬性。現在預設會複製 :attr:`~function." +"__annotations__` 屬性。缺少的屬性不再觸發 :exc:`AttributeError`。" + +#: ../../library/functools.rst:756 +msgid "" +"The ``__wrapped__`` attribute now always refers to the wrapped function, " +"even if that function defined a ``__wrapped__`` attribute. (see :issue:" +"`17482`)" +msgstr "" +"``__wrapped__`` 屬性現在都會參照包裝函式，即便函式有定義 ``__wrapped__`` 屬" +"性。（參見 :issue:`17482`）" + +#: ../../library/functools.rst:761 +msgid "" +"The :attr:`~function.__type_params__` attribute is now copied by default." +msgstr "現在預設會複製 :attr:`~function.__type_params__` 屬性。" + +#: ../../library/functools.rst:767 +msgid "" +"This is a convenience function for invoking :func:`update_wrapper` as a " +"function decorator when defining a wrapper function. It is equivalent to " +"``partial(update_wrapper, wrapped=wrapped, assigned=assigned, " +"updated=updated)``. For example::" +msgstr "" +"這是一個方便的函式，用於在定義包裝器函式時呼叫 :func:`update_wrapper` 作為函" +"式裝飾器。它相當於 ``partial(update_wrapper, wrapped=wrapped, " +"assigned=assigned, updated=updated)``。例如： ::" + +#: ../../library/functools.rst:772 +msgid "" +">>> from functools import wraps\n" +">>> def my_decorator(f):\n" +"... @wraps(f)\n" +"... def wrapper(*args, **kwds):\n" +"... print('Calling decorated function')\n" +"... return f(*args, **kwds)\n" +"... return wrapper\n" +"...\n" +">>> @my_decorator\n" +"... def example():\n" +"... \"\"\"Docstring\"\"\"\n" +"... print('Called example function')\n" +"...\n" +">>> example()\n" +"Calling decorated function\n" +"Called example function\n" +">>> example.__name__\n" +"'example'\n" +">>> example.__doc__\n" +"'Docstring'" +msgstr "" +">>> from functools import wraps\n" +">>> def my_decorator(f):\n" +"... @wraps(f)\n" +"... def wrapper(*args, **kwds):\n" +"... print('Calling decorated function')\n" +"... return f(*args, **kwds)\n" +"... return wrapper\n" +"...\n" +">>> @my_decorator\n" +"... def example():\n" +"... \"\"\"Docstring\"\"\"\n" +"... print('Called example function')\n" +"...\n" +">>> example()\n" +"Calling decorated function\n" +"Called example function\n" +">>> example.__name__\n" +"'example'\n" +">>> example.__doc__\n" +"'Docstring'" + +#: ../../library/functools.rst:793 +msgid "" +"Without the use of this decorator factory, the name of the example function " +"would have been ``'wrapper'``, and the docstring of the original :func:`!" +"example` would have been lost." +msgstr "" +"如果不使用這個裝飾器工廠 (decorator factory)，範例函式的名稱將會是 " +"``'wrapper'``，並且原始 :func:`!example` 的文件字串將會遺失。" + +#: ../../library/functools.rst:801 +msgid ":class:`partial` Objects" +msgstr ":class:`partial` 物件" + +#: ../../library/functools.rst:803 +msgid "" +":class:`partial` objects are callable objects created by :func:`partial`. " +"They have three read-only attributes:" +msgstr "" +":class:`partial` 物件是由 :func:`partial` 所建立的可呼叫物件。它們有三個唯讀" +"屬性：" + +#: ../../library/functools.rst:809 +msgid "" +"A callable object or function. Calls to the :class:`partial` object will be " +"forwarded to :attr:`func` with new arguments and keywords." +msgstr "" +"一個可呼叫的物件或函式。對 :class:`partial` 物件的呼叫將被轉送到帶有新引數和" +"關鍵字的 :attr:`func`。" + +#: ../../library/functools.rst:815 +msgid "" +"The leftmost positional arguments that will be prepended to the positional " +"arguments provided to a :class:`partial` object call." +msgstr "" +"最左邊的位置引數將會被加入到提供給 :class:`partial` 物件呼叫的位置引數的前" +"面。" + +#: ../../library/functools.rst:821 +msgid "" +"The keyword arguments that will be supplied when the :class:`partial` object " +"is called." +msgstr "呼叫 :class:`partial` 物件時將提供的關鍵字引數。" + +#: ../../library/functools.rst:824 +msgid "" +":class:`partial` objects are like :ref:`function objects ` in that they are callable, weak referenceable, and can have " +"attributes. There are some important differences. For instance, the :attr:" +"`~definition.__name__` and :attr:`~definition.__doc__` attributes are not " +"created automatically." +msgstr "" +":class:`partial` 物件與\\ :ref:`函式物件 `\\ 類似，因為它" +"們是可呼叫的、可弱參照的 (weak referencable) 且可以具有屬性的。但有一些重要的" +"區別，例如，:attr:`~definition.__name__` 和 :attr:`~definition.__doc__` 屬性" +"不會自動建立。" diff --git a/library/gc.po b/library/gc.po index abcbc0941b..031c2460ac 100644 --- a/library/gc.po +++ b/library/gc.po @@ -1,629 +1,629 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Liang-Bo Wang , 2015 -# Matt Wang , 2022-2024 -# -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-29 00:15+0000\n" -"PO-Revision-Date: 2023-04-24 21:25+0800\n" -"Last-Translator: Matt Wang \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" -"X-Generator: Poedit 3.2.2\n" - -#: ../../library/gc.rst:2 -msgid ":mod:`!gc` --- Garbage Collector interface" -msgstr ":mod:`!gc` --- 垃圾回收器介面 (Garbage Collector interface)" - -#: ../../library/gc.rst:12 -msgid "" -"This module provides an interface to the optional garbage collector. It " -"provides the ability to disable the collector, tune the collection " -"frequency, and set debugging options. It also provides access to " -"unreachable objects that the collector found but cannot free. Since the " -"collector supplements the reference counting already used in Python, you can " -"disable the collector if you are sure your program does not create reference " -"cycles. Automatic collection can be disabled by calling ``gc.disable()``. " -"To debug a leaking program call ``gc.set_debug(gc.DEBUG_LEAK)``. Notice that " -"this includes ``gc.DEBUG_SAVEALL``, causing garbage-collected objects to be " -"saved in gc.garbage for inspection." -msgstr "" -"此 module（模組）提供可選的垃圾回收器介面，提供的功能包括：關閉回收器、調整回" -"收頻率、設定除錯選項。它同時提供對回收器有找到但是無法釋放的不可達物件 " -"(unreachable object) 的存取。由於 Python 使用了帶有參照計數的回收器，如果你確" -"定你的程式不會產生參照迴圈 (reference cycle)，你可以關閉回收器。可以透過呼叫 " -"``gc.disable()`` 關閉自動垃圾回收。若要為一個存在記憶體流失的程式 (leaking " -"program) 除錯，請呼叫 ``gc.set_debug(gc.DEBUG_LEAK)``；需要注意的是，它包含 " -"``gc.DEBUG_SAVEALL``，使得被回收的物件會被存放在 gc.garbage 中以待檢查。" - -#: ../../library/gc.rst:23 -msgid "The :mod:`gc` module provides the following functions:" -msgstr ":mod:`gc` module 提供下列函式：" - -#: ../../library/gc.rst:28 -msgid "Enable automatic garbage collection." -msgstr "啟用自動垃圾回收。" - -#: ../../library/gc.rst:33 -msgid "Disable automatic garbage collection." -msgstr "停用自動垃圾回收。" - -#: ../../library/gc.rst:38 -msgid "Return ``True`` if automatic collection is enabled." -msgstr "如果啟用了自動回收則回傳 ``True``。" - -#: ../../library/gc.rst:43 -msgid "" -"Perform a collection. The optional argument *generation* may be an integer " -"specifying which generation to collect (from 0 to 2). A :exc:`ValueError` " -"is raised if the generation number is invalid. The sum of collected objects " -"and uncollectable objects is returned." -msgstr "" -"啟動垃圾回收。可選的引數 *generation* 可以是一個指明需要回收哪一代垃圾的整數" -"（從 0 到 2）。當 generation 數值無效時，會引發 :exc:`ValueError` 例外。可回" -"收物件與不可回收物件的總和會被回傳。" - -#: ../../library/gc.rst:48 -msgid "" -"Calling ``gc.collect(0)`` will perform a GC collection on the young " -"generation." -msgstr "呼叫 ``gc.collect(0)`` 將對年輕代執行 GC 回收。" - -#: ../../library/gc.rst:50 -msgid "" -"Calling ``gc.collect(1)`` will perform a GC collection on the young " -"generation and an increment of the old generation." -msgstr "呼叫 ``gc.collect(1)`` 將對年輕代執行 GC 回收並對年老代執行增量回收。" - -#: ../../library/gc.rst:53 -msgid "" -"Calling ``gc.collect(2)`` or ``gc.collect()`` performs a full collection" -msgstr "呼叫 ``gc.collect(2)`` 或 ``gc.collect()`` 執行完整回收" - -#: ../../library/gc.rst:55 -msgid "" -"The free lists maintained for a number of built-in types are cleared " -"whenever a full collection or collection of the highest generation (2) is " -"run. Not all items in some free lists may be freed due to the particular " -"implementation, in particular :class:`float`." -msgstr "" -"每當執行完整回收或最高代 (2) 回收時，為多個內建型別所維護的空閒列表會被清空。" -"為了特定型別的實現，特別是 :class:`float`，在某些空閒列表中並非所有項目都會被" -"釋放。" - -#: ../../library/gc.rst:60 -msgid "" -"The effect of calling ``gc.collect()`` while the interpreter is already " -"performing a collection is undefined." -msgstr "當直譯器已經執行收集時呼叫 ``gc.collect()`` 的效果是未定義的。" - -#: ../../library/gc.rst:63 -msgid "``generation=1`` performs an increment of collection." -msgstr "``generation=1`` 會執行增量收集。" - -#: ../../library/gc.rst:69 -msgid "" -"Set the garbage collection debugging flags. Debugging information will be " -"written to ``sys.stderr``. See below for a list of debugging flags which " -"can be combined using bit operations to control debugging." -msgstr "" -"設定垃圾回收器的除錯旗標。除錯資訊會被寫入 ``sys.stderr``。請見下方的除錯旗標" -"列表，可以使用位元操作 (bit operation) 進行設定以控制除錯程式。" - -#: ../../library/gc.rst:76 -msgid "Return the debugging flags currently set." -msgstr "回傳目前設置的除錯旗標。" - -#: ../../library/gc.rst:82 -msgid "" -"Returns a list of all objects tracked by the collector, excluding the list " -"returned. If *generation* is not ``None``, return only the objects as " -"follows:" -msgstr "" -"回傳一個包含回收器正在追蹤的所有物件的 list，除去所回傳的 list。如果 " -"*generation* 不為 ``None``，只回傳以下物件。" - -#: ../../library/gc.rst:85 -msgid "0: All objects in the young generation" -msgstr "0: 年輕代中的所有物件。" - -#: ../../library/gc.rst:86 -msgid "1: No objects, as there is no generation 1 (as of Python 3.14)" -msgstr "1: 沒有物件，因為不存在第一代（截至 Python 3.14）" - -#: ../../library/gc.rst:87 -msgid "2: All objects in the old generation" -msgstr "2: 年老代中的所有物件。" - -#: ../../library/gc.rst:89 -msgid "New *generation* parameter." -msgstr "新增 *generation* 參數。" - -#: ../../library/gc.rst:92 -msgid "Generation 1 is removed" -msgstr "第一代已被刪除" - -#: ../../library/gc.rst:95 -msgid "" -"Raises an :ref:`auditing event ` ``gc.get_objects`` with argument " -"``generation``." -msgstr "" -"引發一個附帶引數 ``generation`` 的\\ :ref:`稽核事件 (auditing event) " -"` ``gc.get_objects``。" - -#: ../../library/gc.rst:99 -msgid "" -"Return a list of three per-generation dictionaries containing collection " -"statistics since interpreter start. The number of keys may change in the " -"future, but currently each dictionary will contain the following items:" -msgstr "" -"回傳一個包含三個字典物件的 list，每個字典分別包含對應代中自從直譯器開始執行後" -"的垃圾回收統計資料。字典的鍵的數目在將來可能會改變，但目前每個字典包含以下項" -"目：" - -#: ../../library/gc.rst:104 -msgid "``collections`` is the number of times this generation was collected;" -msgstr "``collections`` 是該代被回收的次數；" - -#: ../../library/gc.rst:106 -msgid "" -"``collected`` is the total number of objects collected inside this " -"generation;" -msgstr "``collected`` 是該代中被回收的物件總數；" - -#: ../../library/gc.rst:109 -msgid "" -"``uncollectable`` is the total number of objects which were found to be " -"uncollectable (and were therefore moved to the :data:`garbage` list) inside " -"this generation." -msgstr "" -"``uncollectable`` 是在這一代中被發現無法回收的物件總數（因此被移到 :data:" -"`garbage` list 中）。" - -#: ../../library/gc.rst:118 -msgid "" -"Set the garbage collection thresholds (the collection frequency). Setting " -"*threshold0* to zero disables collection." -msgstr "設定垃圾回收閾值（回收頻率）。 將 *threshold0* 設為零會停止回收。" - -#: ../../library/gc.rst:121 -msgid "" -"The GC classifies objects into two generations depending on whether they " -"have survived a collection. New objects are placed in the young generation. " -"If an object survives a collection it is moved into the old generation." -msgstr "" -"GC 根據物件是否在回收中倖存下來而將其分為兩代。新的物件會被放置在年輕代中。如果一" -"個物件在回收中倖存下來，它將被移動到年老代中。" - -#: ../../library/gc.rst:125 -msgid "" -"In order to decide when to run, the collector keeps track of the number of " -"object allocations and deallocations since the last collection. When the " -"number of allocations minus the number of deallocations exceeds " -"*threshold0*, collection starts. For each collection, all the objects in the " -"young generation and some fraction of the old generation is collected." -msgstr "" -"為了決定何時運行，回收器會追蹤自上次回收以來物件分配和釋放的數量。當分配數" -"量減去釋放數量超過 *threshold0* 時，回收就會開始。每次回收都會去回收年輕代中的所有物件" -"和年老代的部分物件。" - -#: ../../library/gc.rst:131 -msgid "" -"In the free-threaded build, the increase in process memory usage is also " -"checked before running the collector. If the memory usage has not increased " -"by 10% since the last collection and the net number of object allocations " -"has not exceeded 40 times *threshold0*, the collection is not run." -msgstr "" -"在自由執行緒建置 (free-threaded build) 中，在運行回收器之前還會檢查行程記憶體使用量的" -"增加。如果自上次回收以來記憶體使用量未增加 10%，且物件分配的淨數量未超過 *threshold0* " -"的 40 倍，則不會運行回收。" - -#: ../../library/gc.rst:136 -msgid "" -"The fraction of the old generation that is collected is **inversely** " -"proportional to *threshold1*. The larger *threshold1* is, the slower objects " -"in the old generation are collected. For the default value of 10, 1% of the " -"old generation is scanned during each collection." -msgstr "" -"年老代中被回收的物件比例與 *threshold1* 成\\ **反比**。*threshold1* 越大，年老代中" -"物件的回收就越慢。以預設值 10 來說，每次回收時會掃描年老代中的 1%。" - -#: ../../library/gc.rst:141 -msgid "*threshold2* is ignored." -msgstr "*threshold2* 會被忽略。" - -#: ../../library/gc.rst:143 -msgid "" -"See `Garbage collector design `_ for more information." -msgstr "" -"有關更多資訊，請參閱\\ `垃圾回收器設計 `_。" - -#: ../../library/gc.rst:145 -msgid "*threshold2* is ignored" -msgstr "*threshold2* 會被忽略" - -#: ../../library/gc.rst:151 -msgid "" -"Return the current collection counts as a tuple of ``(count0, count1, " -"count2)``." -msgstr "將目前回收計數以 ``(count0, count1, count2)`` 形式的 tuple 回傳。" - -#: ../../library/gc.rst:157 -msgid "" -"Return the current collection thresholds as a tuple of ``(threshold0, " -"threshold1, threshold2)``." -msgstr "" -"將目前回收閾值以 ``(threshold0, threshold1, threshold2)`` 形式的 tuple 回傳。" - -#: ../../library/gc.rst:163 -msgid "" -"Return the list of objects that directly refer to any of objs. This function " -"will only locate those containers which support garbage collection; " -"extension types which do refer to other objects but do not support garbage " -"collection will not be found." -msgstr "" -"回傳包含直接參照 objs 中任一個物件的物件 list。這個函式只定位支援垃圾回收的容" -"器；參照了其它物件但不支援垃圾回收的擴充套件型別無法被找到。" - -#: ../../library/gc.rst:168 -msgid "" -"Note that objects which have already been dereferenced, but which live in " -"cycles and have not yet been collected by the garbage collector can be " -"listed among the resulting referrers. To get only currently live objects, " -"call :func:`collect` before calling :func:`get_referrers`." -msgstr "" -"需要注意的是，已經解除參照的物件，但仍存在於參照迴圈中未被回收時，該物件仍然" -"會被作為參照者出現在回傳的 list 中。若只要取得目前正在參照的物件，需要在呼" -"叫 :func:`get_referrers` 之前呼叫 :func:`collect`。" - -#: ../../library/gc.rst:174 -msgid "" -"Care must be taken when using objects returned by :func:`get_referrers` " -"because some of them could still be under construction and hence in a " -"temporarily invalid state. Avoid using :func:`get_referrers` for any purpose " -"other than debugging." -msgstr "" -"在使用 :func:`get_referrers` 回傳的物件時必須要小心，因為其中的一些物件可能仍" -"在建構中而處於暫時無效的狀態。不要把 :func:`get_referrers` 用於除錯以外的其它" -"目的。" - -#: ../../library/gc.rst:179 -msgid "" -"Raises an :ref:`auditing event ` ``gc.get_referrers`` with " -"argument ``objs``." -msgstr "" -"引發一個附帶引數 ``objs`` 的\\ :ref:`稽核事件 ` ``gc." -"get_referrers``。" - -#: ../../library/gc.rst:184 -msgid "" -"Return a list of objects directly referred to by any of the arguments. The " -"referents returned are those objects visited by the arguments' C-level :c:" -"member:`~PyTypeObject.tp_traverse` methods (if any), and may not be all " -"objects actually directly reachable. :c:member:`~PyTypeObject.tp_traverse` " -"methods are supported only by objects that support garbage collection, and " -"are only required to visit objects that may be involved in a cycle. So, for " -"example, if an integer is directly reachable from an argument, that integer " -"object may or may not appear in the result list." -msgstr "" -"回傳包含被任意一個引數直接參照之物件的 list。回傳的被參照物件是有被引數的 C " -"語言級別 :c:member:`~PyTypeObject.tp_traverse` 方法（若存在）瀏覽到的物件，可" -"能不是所有的實際直接可達物件。只有支援垃圾回收的物件支援 :c:member:" -"`~PyTypeObject.tp_traverse` 方法，並且此方法只會瀏覽涉及參照迴圈的物件。因" -"此，可以有以下例子：一個整數對於一個引數是直接可達的，這個整數物件有可能出現" -"或不出現在結果的 list 當中。" - -#: ../../library/gc.rst:192 -msgid "" -"Raises an :ref:`auditing event ` ``gc.get_referents`` with " -"argument ``objs``." -msgstr "" -"引發一個附帶引數 ``objs`` 的\\ :ref:`稽核事件 ` ``gc." -"get_referents``。" - -#: ../../library/gc.rst:196 -msgid "" -"Returns ``True`` if the object is currently tracked by the garbage " -"collector, ``False`` otherwise. As a general rule, instances of atomic " -"types aren't tracked and instances of non-atomic types (containers, user-" -"defined objects...) are. However, some type-specific optimizations can be " -"present in order to suppress the garbage collector footprint of simple " -"instances (e.g. dicts containing only atomic keys and values)::" -msgstr "" -"當物件正在被垃圾回收器追蹤時回傳 ``True``，否則回傳 ``False``。一般來說，原子" -"型別 (atomic type) 的實例不會被追蹤，而非原子型別（如容器、使用者自己定義的物" -"件）會被追蹤。然而，有一些特定型別最佳化會被用來減少垃圾回收器在簡單實例（如" -"只含有原子性的鍵和值的字典）上的足跡： ::" - -#: ../../library/gc.rst:203 -msgid "" -">>> gc.is_tracked(0)\n" -"False\n" -">>> gc.is_tracked(\"a\")\n" -"False\n" -">>> gc.is_tracked([])\n" -"True\n" -">>> gc.is_tracked({})\n" -"False\n" -">>> gc.is_tracked({\"a\": 1})\n" -"True" -msgstr "" -">>> gc.is_tracked(0)\n" -"False\n" -">>> gc.is_tracked(\"a\")\n" -"False\n" -">>> gc.is_tracked([])\n" -"True\n" -">>> gc.is_tracked({})\n" -"False\n" -">>> gc.is_tracked({\"a\": 1})\n" -"True" - -#: ../../library/gc.rst:219 -msgid "" -"Returns ``True`` if the given object has been finalized by the garbage " -"collector, ``False`` otherwise. ::" -msgstr "" -"如果給定物件已被垃圾回收器終結則回傳 ``True``，否則回傳 ``False``。： ::" - -#: ../../library/gc.rst:222 -msgid "" -">>> x = None\n" -">>> class Lazarus:\n" -"... def __del__(self):\n" -"... global x\n" -"... x = self\n" -"...\n" -">>> lazarus = Lazarus()\n" -">>> gc.is_finalized(lazarus)\n" -"False\n" -">>> del lazarus\n" -">>> gc.is_finalized(x)\n" -"True" -msgstr "" -">>> x = None\n" -">>> class Lazarus:\n" -"... def __del__(self):\n" -"... global x\n" -"... x = self\n" -"...\n" -">>> lazarus = Lazarus()\n" -">>> gc.is_finalized(lazarus)\n" -"False\n" -">>> del lazarus\n" -">>> gc.is_finalized(x)\n" -"True" - -#: ../../library/gc.rst:240 -msgid "" -"Freeze all the objects tracked by the garbage collector; move them to a " -"permanent generation and ignore them in all the future collections." -msgstr "" -"凍結 (freeze) 垃圾回收器所追蹤的所有物件；將它們移至永久代並忽略所有未來的收" -"集動作。" - -#: ../../library/gc.rst:243 -msgid "" -"If a process will ``fork()`` without ``exec()``, avoiding unnecessary copy-" -"on-write in child processes will maximize memory sharing and reduce overall " -"memory usage. This requires both avoiding creation of freed \"holes\" in " -"memory pages in the parent process and ensuring that GC collections in child " -"processes won't touch the ``gc_refs`` counter of long-lived objects " -"originating in the parent process. To accomplish both, call ``gc.disable()`` " -"early in the parent process, ``gc.freeze()`` right before ``fork()``, and " -"``gc.enable()`` early in child processes." -msgstr "" -"如果一個行程將在沒有 ``exec()`` 的情況下進行 ``fork()``，避免子行程中不必要的" -"寫入時複製將最大化記憶體共享並減少整體記憶體使用。這需要避免在父行程的記憶體" -"頁面中建立已釋放的「漏洞」，並確保子行程中的 GC 收集不會觸及源自父行程的長壽" -"命物件的 ``gc_refs`` 計數器。要實現這兩個目標，請在父行程的早期呼叫 ``gc." -"disable()``，在 ``fork()`` 之前呼叫 ``gc.freeze()``，並儘早在子行程中呼叫 " -"``gc.enable()``。" - -#: ../../library/gc.rst:257 -msgid "" -"Unfreeze the objects in the permanent generation, put them back into the " -"oldest generation." -msgstr "解凍 (unfreeze) 永久代中的物件，並將它們放回到最年老代中。" - -#: ../../library/gc.rst:265 -msgid "Return the number of objects in the permanent generation." -msgstr "回傳永久代中的物件數量。" - -#: ../../library/gc.rst:270 -msgid "" -"The following variables are provided for read-only access (you can mutate " -"the values but should not rebind them):" -msgstr "以下變數僅供唯讀存取（你可以修改其值但不應該重新繫結 (rebind) 它們）：" - -#: ../../library/gc.rst:275 -msgid "" -"A list of objects which the collector found to be unreachable but could not " -"be freed (uncollectable objects). Starting with Python 3.4, this list " -"should be empty most of the time, except when using instances of C extension " -"types with a non-``NULL`` ``tp_del`` slot." -msgstr "" -"一個回收器發現不可達而又無法被釋放的物件（不可回收物件）list。從 Python 3.4 " -"開始，該 list 在大多數時候都應該是空的，除非使用了有非 ``NULL`` ``tp_del`` 槽" -"位的 C 擴充套件型別的實例。" - -#: ../../library/gc.rst:280 -msgid "" -"If :const:`DEBUG_SAVEALL` is set, then all unreachable objects will be added " -"to this list rather than freed." -msgstr "" -"如果設定了 :const:`DEBUG_SAVEALL`，則所有不可達物件將被加進該 list 而不會被釋" -"放。" - -#: ../../library/gc.rst:283 -msgid "" -"If this list is non-empty at :term:`interpreter shutdown`, a :exc:" -"`ResourceWarning` is emitted, which is silent by default. If :const:" -"`DEBUG_UNCOLLECTABLE` is set, in addition all uncollectable objects are " -"printed." -msgstr "" -"當 :term:`interpreter shutdown` 即直譯器關閉時，若此 list 非空，會產生 :exc:" -"`ResourceWarning`，在預設情況下此警告不會被提醒。如果設定了 :const:" -"`DEBUG_UNCOLLECTABLE`，所有無法被回收的物件會被印出。" - -#: ../../library/gc.rst:289 -msgid "" -"Following :pep:`442`, objects with a :meth:`~object.__del__` method don't " -"end up in :data:`gc.garbage` anymore." -msgstr "" -"根據 :pep:`442`，帶有 :meth:`~object.__del__` method 的物件最終不會在 :data:" -"`gc.garbage` 內。" - -#: ../../library/gc.rst:295 -msgid "" -"A list of callbacks that will be invoked by the garbage collector before and " -"after collection. The callbacks will be called with two arguments, *phase* " -"and *info*." -msgstr "" -"會被垃圾回收器在回收開始前和完成後叫用的一系列回呼函式 (callback) 。這些回呼" -"函式在被呼叫時附帶兩個引數：*phase* 和 *info*。" - -#: ../../library/gc.rst:299 -msgid "*phase* can be one of two values:" -msgstr "*phase* 可為以下兩者之一：" - -#: ../../library/gc.rst:301 -msgid "\"start\": The garbage collection is about to start." -msgstr "\"start\"：垃圾回收即將開始。" - -#: ../../library/gc.rst:303 -msgid "\"stop\": The garbage collection has finished." -msgstr "\"stop\"：垃圾回收已結束。" - -#: ../../library/gc.rst:305 -msgid "" -"*info* is a dict providing more information for the callback. The following " -"keys are currently defined:" -msgstr "*info* 是一個字典，提供回呼函式更多資訊。已有定義的鍵有：" - -#: ../../library/gc.rst:308 -msgid "\"generation\": The oldest generation being collected." -msgstr "\"generation\"（代）：正在被回收的最年老的一代。" - -#: ../../library/gc.rst:310 -msgid "" -"\"collected\": When *phase* is \"stop\", the number of objects successfully " -"collected." -msgstr "" -"\"collected\"（已回收的）：當 *phase* 為 \"stop\" 時，被成功回收的物件的數" -"目。" - -#: ../../library/gc.rst:313 -msgid "" -"\"uncollectable\": When *phase* is \"stop\", the number of objects that " -"could not be collected and were put in :data:`garbage`." -msgstr "" -"\"uncollectable\"（不可回收的）：當 *phase* 為 \"stop\" 時，不能被回收並被放" -"入 :data:`garbage` 的物件的數目。" - -#: ../../library/gc.rst:316 -msgid "" -"Applications can add their own callbacks to this list. The primary use " -"cases are:" -msgstr "應用程式可以把他們自己的回呼函式加入此 list。主要的使用場景有：" - -#: ../../library/gc.rst:319 -msgid "" -"Gathering statistics about garbage collection, such as how often various " -"generations are collected, and how long the collection takes." -msgstr "收集垃圾回收的統計資料，如：不同代的回收頻率、回收任務所花費的時間。" - -#: ../../library/gc.rst:323 -msgid "" -"Allowing applications to identify and clear their own uncollectable types " -"when they appear in :data:`garbage`." -msgstr "" -"讓應用程式可以識別和清理他們自己在 :data:`garbage` 中的不可回收型別物件。" - -#: ../../library/gc.rst:329 -msgid "The following constants are provided for use with :func:`set_debug`:" -msgstr "以下常數是為了和 :func:`set_debug` 一起使用所提供：" - -#: ../../library/gc.rst:334 -msgid "" -"Print statistics during collection. This information can be useful when " -"tuning the collection frequency." -msgstr "在回收完成後印出統計資訊。當調校回收頻率設定時，這些資訊會很有用。" - -#: ../../library/gc.rst:340 -msgid "Print information on collectable objects found." -msgstr "當發現可回收物件時印出資訊。" - -#: ../../library/gc.rst:345 -msgid "" -"Print information of uncollectable objects found (objects which are not " -"reachable but cannot be freed by the collector). These objects will be " -"added to the ``garbage`` list." -msgstr "" -"印出找到的不可回收物件的資訊（指不能被回收器回收的不可達物件）。這些物件會被" -"新增到 ``garbage`` list 中。" - -#: ../../library/gc.rst:349 -msgid "" -"Also print the contents of the :data:`garbage` list at :term:`interpreter " -"shutdown`, if it isn't empty." -msgstr "" -"當 :term:`interpreter shutdown`\\ （直譯器關閉）時，若 :data:`garbage` list " -"不是空的，那這些內容也會被印出。" - -#: ../../library/gc.rst:355 -msgid "" -"When set, all unreachable objects found will be appended to *garbage* rather " -"than being freed. This can be useful for debugging a leaking program." -msgstr "" -"設定後，所有回收器找到的不可達物件會被加進 *garbage* 而不是直接被釋放。這在為" -"一個記憶體流失的程式除錯時會很有用。" - -#: ../../library/gc.rst:361 -msgid "" -"The debugging flags necessary for the collector to print information about a " -"leaking program (equal to ``DEBUG_COLLECTABLE | DEBUG_UNCOLLECTABLE | " -"DEBUG_SAVEALL``)." -msgstr "" -"要印出記憶體流失程式之相關資訊時，回收器所需的除錯旗標。（等同於 " -"``DEBUG_COLLECTABLE | DEBUG_UNCOLLECTABLE | DEBUG_SAVEALL``）。" - -#~ msgid "" -#~ "The GC classifies objects into three generations depending on how many " -#~ "collection sweeps they have survived. New objects are placed in the " -#~ "youngest generation (generation ``0``). If an object survives a " -#~ "collection it is moved into the next older generation. Since generation " -#~ "``2`` is the oldest generation, objects in that generation remain there " -#~ "after a collection. In order to decide when to run, the collector keeps " -#~ "track of the number object allocations and deallocations since the last " -#~ "collection. When the number of allocations minus the number of " -#~ "deallocations exceeds *threshold0*, collection starts. Initially only " -#~ "generation ``0`` is examined. If generation ``0`` has been examined more " -#~ "than *threshold1* times since generation ``1`` has been examined, then " -#~ "generation ``1`` is examined as well. With the third generation, things " -#~ "are a bit more complicated, see `Collecting the oldest generation " -#~ "`_ for more information." -#~ msgstr "" -#~ "垃圾回收器會根據物件在多少次垃圾回收後仍倖存來把所有物件分類為三代。新建物" -#~ "件會被放在最年輕代（第 ``0`` 代）。 如果一個物件在一次垃圾回收後倖存，它會" -#~ "被移入下一個較老代。由於第 ``2`` 代是最老代，這一代的物件在一次垃圾回收後" -#~ "仍會保留原樣。為了確定何時要執行，垃圾回收器會追蹤自上一次回收後物件分配和" -#~ "釋放的數量。當分配數量減去釋放數量的結果大於 *threshold0* 時，垃圾回收就會" -#~ "開始。初始時只有第 ``0`` 代會被檢查。如果自第 ``1`` 代被檢查後第 ``0`` 代" -#~ "已被檢查超過 *threshold1* 次，則第 ``1`` 代也會被檢查。對於第三代來說，情" -#~ "況還會更復雜一些，請參閱 `Collecting the oldest generation `_ 來了解詳情。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Liang-Bo Wang , 2015 +# Matt Wang , 2022-2024 +# +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-29 00:15+0000\n" +"PO-Revision-Date: 2023-04-24 21:25+0800\n" +"Last-Translator: Matt Wang \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" +"X-Generator: Poedit 3.2.2\n" + +#: ../../library/gc.rst:2 +msgid ":mod:`!gc` --- Garbage Collector interface" +msgstr ":mod:`!gc` --- 垃圾回收器介面 (Garbage Collector interface)" + +#: ../../library/gc.rst:12 +msgid "" +"This module provides an interface to the optional garbage collector. It " +"provides the ability to disable the collector, tune the collection " +"frequency, and set debugging options. It also provides access to " +"unreachable objects that the collector found but cannot free. Since the " +"collector supplements the reference counting already used in Python, you can " +"disable the collector if you are sure your program does not create reference " +"cycles. Automatic collection can be disabled by calling ``gc.disable()``. " +"To debug a leaking program call ``gc.set_debug(gc.DEBUG_LEAK)``. Notice that " +"this includes ``gc.DEBUG_SAVEALL``, causing garbage-collected objects to be " +"saved in gc.garbage for inspection." +msgstr "" +"此 module（模組）提供可選的垃圾回收器介面，提供的功能包括：關閉回收器、調整回" +"收頻率、設定除錯選項。它同時提供對回收器有找到但是無法釋放的不可達物件 " +"(unreachable object) 的存取。由於 Python 使用了帶有參照計數的回收器，如果你確" +"定你的程式不會產生參照迴圈 (reference cycle)，你可以關閉回收器。可以透過呼叫 " +"``gc.disable()`` 關閉自動垃圾回收。若要為一個存在記憶體流失的程式 (leaking " +"program) 除錯，請呼叫 ``gc.set_debug(gc.DEBUG_LEAK)``；需要注意的是，它包含 " +"``gc.DEBUG_SAVEALL``，使得被回收的物件會被存放在 gc.garbage 中以待檢查。" + +#: ../../library/gc.rst:23 +msgid "The :mod:`gc` module provides the following functions:" +msgstr ":mod:`gc` module 提供下列函式：" + +#: ../../library/gc.rst:28 +msgid "Enable automatic garbage collection." +msgstr "啟用自動垃圾回收。" + +#: ../../library/gc.rst:33 +msgid "Disable automatic garbage collection." +msgstr "停用自動垃圾回收。" + +#: ../../library/gc.rst:38 +msgid "Return ``True`` if automatic collection is enabled." +msgstr "如果啟用了自動回收則回傳 ``True``。" + +#: ../../library/gc.rst:43 +msgid "" +"Perform a collection. The optional argument *generation* may be an integer " +"specifying which generation to collect (from 0 to 2). A :exc:`ValueError` " +"is raised if the generation number is invalid. The sum of collected objects " +"and uncollectable objects is returned." +msgstr "" +"啟動垃圾回收。可選的引數 *generation* 可以是一個指明需要回收哪一代垃圾的整數" +"（從 0 到 2）。當 generation 數值無效時，會引發 :exc:`ValueError` 例外。可回" +"收物件與不可回收物件的總和會被回傳。" + +#: ../../library/gc.rst:48 +msgid "" +"Calling ``gc.collect(0)`` will perform a GC collection on the young " +"generation." +msgstr "呼叫 ``gc.collect(0)`` 將對年輕代執行 GC 回收。" + +#: ../../library/gc.rst:50 +msgid "" +"Calling ``gc.collect(1)`` will perform a GC collection on the young " +"generation and an increment of the old generation." +msgstr "呼叫 ``gc.collect(1)`` 將對年輕代執行 GC 回收並對年老代執行增量回收。" + +#: ../../library/gc.rst:53 +msgid "" +"Calling ``gc.collect(2)`` or ``gc.collect()`` performs a full collection" +msgstr "呼叫 ``gc.collect(2)`` 或 ``gc.collect()`` 執行完整回收" + +#: ../../library/gc.rst:55 +msgid "" +"The free lists maintained for a number of built-in types are cleared " +"whenever a full collection or collection of the highest generation (2) is " +"run. Not all items in some free lists may be freed due to the particular " +"implementation, in particular :class:`float`." +msgstr "" +"每當執行完整回收或最高代 (2) 回收時，為多個內建型別所維護的空閒列表會被清空。" +"為了特定型別的實現，特別是 :class:`float`，在某些空閒列表中並非所有項目都會被" +"釋放。" + +#: ../../library/gc.rst:60 +msgid "" +"The effect of calling ``gc.collect()`` while the interpreter is already " +"performing a collection is undefined." +msgstr "當直譯器已經執行收集時呼叫 ``gc.collect()`` 的效果是未定義的。" + +#: ../../library/gc.rst:63 +msgid "``generation=1`` performs an increment of collection." +msgstr "``generation=1`` 會執行增量收集。" + +#: ../../library/gc.rst:69 +msgid "" +"Set the garbage collection debugging flags. Debugging information will be " +"written to ``sys.stderr``. See below for a list of debugging flags which " +"can be combined using bit operations to control debugging." +msgstr "" +"設定垃圾回收器的除錯旗標。除錯資訊會被寫入 ``sys.stderr``。請見下方的除錯旗標" +"列表，可以使用位元操作 (bit operation) 進行設定以控制除錯程式。" + +#: ../../library/gc.rst:76 +msgid "Return the debugging flags currently set." +msgstr "回傳目前設置的除錯旗標。" + +#: ../../library/gc.rst:82 +msgid "" +"Returns a list of all objects tracked by the collector, excluding the list " +"returned. If *generation* is not ``None``, return only the objects as " +"follows:" +msgstr "" +"回傳一個包含回收器正在追蹤的所有物件的 list，除去所回傳的 list。如果 " +"*generation* 不為 ``None``，只回傳以下物件。" + +#: ../../library/gc.rst:85 +msgid "0: All objects in the young generation" +msgstr "0: 年輕代中的所有物件。" + +#: ../../library/gc.rst:86 +msgid "1: No objects, as there is no generation 1 (as of Python 3.14)" +msgstr "1: 沒有物件，因為不存在第一代（截至 Python 3.14）" + +#: ../../library/gc.rst:87 +msgid "2: All objects in the old generation" +msgstr "2: 年老代中的所有物件。" + +#: ../../library/gc.rst:89 +msgid "New *generation* parameter." +msgstr "新增 *generation* 參數。" + +#: ../../library/gc.rst:92 +msgid "Generation 1 is removed" +msgstr "第一代已被刪除" + +#: ../../library/gc.rst:95 +msgid "" +"Raises an :ref:`auditing event ` ``gc.get_objects`` with argument " +"``generation``." +msgstr "" +"引發一個附帶引數 ``generation`` 的\\ :ref:`稽核事件 (auditing event) " +"` ``gc.get_objects``。" + +#: ../../library/gc.rst:99 +msgid "" +"Return a list of three per-generation dictionaries containing collection " +"statistics since interpreter start. The number of keys may change in the " +"future, but currently each dictionary will contain the following items:" +msgstr "" +"回傳一個包含三個字典物件的 list，每個字典分別包含對應代中自從直譯器開始執行後" +"的垃圾回收統計資料。字典的鍵的數目在將來可能會改變，但目前每個字典包含以下項" +"目：" + +#: ../../library/gc.rst:104 +msgid "``collections`` is the number of times this generation was collected;" +msgstr "``collections`` 是該代被回收的次數；" + +#: ../../library/gc.rst:106 +msgid "" +"``collected`` is the total number of objects collected inside this " +"generation;" +msgstr "``collected`` 是該代中被回收的物件總數；" + +#: ../../library/gc.rst:109 +msgid "" +"``uncollectable`` is the total number of objects which were found to be " +"uncollectable (and were therefore moved to the :data:`garbage` list) inside " +"this generation." +msgstr "" +"``uncollectable`` 是在這一代中被發現無法回收的物件總數（因此被移到 :data:" +"`garbage` list 中）。" + +#: ../../library/gc.rst:118 +msgid "" +"Set the garbage collection thresholds (the collection frequency). Setting " +"*threshold0* to zero disables collection." +msgstr "設定垃圾回收閾值（回收頻率）。 將 *threshold0* 設為零會停止回收。" + +#: ../../library/gc.rst:121 +msgid "" +"The GC classifies objects into two generations depending on whether they " +"have survived a collection. New objects are placed in the young generation. " +"If an object survives a collection it is moved into the old generation." +msgstr "" +"GC 根據物件是否在回收中倖存下來而將其分為兩代。新的物件會被放置在年輕代中。如果一" +"個物件在回收中倖存下來，它將被移動到年老代中。" + +#: ../../library/gc.rst:125 +msgid "" +"In order to decide when to run, the collector keeps track of the number of " +"object allocations and deallocations since the last collection. When the " +"number of allocations minus the number of deallocations exceeds " +"*threshold0*, collection starts. For each collection, all the objects in the " +"young generation and some fraction of the old generation is collected." +msgstr "" +"為了決定何時運行，回收器會追蹤自上次回收以來物件分配和釋放的數量。當分配數" +"量減去釋放數量超過 *threshold0* 時，回收就會開始。每次回收都會去回收年輕代中的所有物件" +"和年老代的部分物件。" + +#: ../../library/gc.rst:131 +msgid "" +"In the free-threaded build, the increase in process memory usage is also " +"checked before running the collector. If the memory usage has not increased " +"by 10% since the last collection and the net number of object allocations " +"has not exceeded 40 times *threshold0*, the collection is not run." +msgstr "" +"在自由執行緒建置 (free-threaded build) 中，在運行回收器之前還會檢查行程記憶體使用量的" +"增加。如果自上次回收以來記憶體使用量未增加 10%，且物件分配的淨數量未超過 *threshold0* " +"的 40 倍，則不會運行回收。" + +#: ../../library/gc.rst:136 +msgid "" +"The fraction of the old generation that is collected is **inversely** " +"proportional to *threshold1*. The larger *threshold1* is, the slower objects " +"in the old generation are collected. For the default value of 10, 1% of the " +"old generation is scanned during each collection." +msgstr "" +"年老代中被回收的物件比例與 *threshold1* 成\\ **反比**。*threshold1* 越大，年老代中" +"物件的回收就越慢。以預設值 10 來說，每次回收時會掃描年老代中的 1%。" + +#: ../../library/gc.rst:141 +msgid "*threshold2* is ignored." +msgstr "*threshold2* 會被忽略。" + +#: ../../library/gc.rst:143 +msgid "" +"See `Garbage collector design `_ for more information." +msgstr "" +"有關更多資訊，請參閱\\ `垃圾回收器設計 `_。" + +#: ../../library/gc.rst:145 +msgid "*threshold2* is ignored" +msgstr "*threshold2* 會被忽略" + +#: ../../library/gc.rst:151 +msgid "" +"Return the current collection counts as a tuple of ``(count0, count1, " +"count2)``." +msgstr "將目前回收計數以 ``(count0, count1, count2)`` 形式的 tuple 回傳。" + +#: ../../library/gc.rst:157 +msgid "" +"Return the current collection thresholds as a tuple of ``(threshold0, " +"threshold1, threshold2)``." +msgstr "" +"將目前回收閾值以 ``(threshold0, threshold1, threshold2)`` 形式的 tuple 回傳。" + +#: ../../library/gc.rst:163 +msgid "" +"Return the list of objects that directly refer to any of objs. This function " +"will only locate those containers which support garbage collection; " +"extension types which do refer to other objects but do not support garbage " +"collection will not be found." +msgstr "" +"回傳包含直接參照 objs 中任一個物件的物件 list。這個函式只定位支援垃圾回收的容" +"器；參照了其它物件但不支援垃圾回收的擴充套件型別無法被找到。" + +#: ../../library/gc.rst:168 +msgid "" +"Note that objects which have already been dereferenced, but which live in " +"cycles and have not yet been collected by the garbage collector can be " +"listed among the resulting referrers. To get only currently live objects, " +"call :func:`collect` before calling :func:`get_referrers`." +msgstr "" +"需要注意的是，已經解除參照的物件，但仍存在於參照迴圈中未被回收時，該物件仍然" +"會被作為參照者出現在回傳的 list 中。若只要取得目前正在參照的物件，需要在呼" +"叫 :func:`get_referrers` 之前呼叫 :func:`collect`。" + +#: ../../library/gc.rst:174 +msgid "" +"Care must be taken when using objects returned by :func:`get_referrers` " +"because some of them could still be under construction and hence in a " +"temporarily invalid state. Avoid using :func:`get_referrers` for any purpose " +"other than debugging." +msgstr "" +"在使用 :func:`get_referrers` 回傳的物件時必須要小心，因為其中的一些物件可能仍" +"在建構中而處於暫時無效的狀態。不要把 :func:`get_referrers` 用於除錯以外的其它" +"目的。" + +#: ../../library/gc.rst:179 +msgid "" +"Raises an :ref:`auditing event ` ``gc.get_referrers`` with " +"argument ``objs``." +msgstr "" +"引發一個附帶引數 ``objs`` 的\\ :ref:`稽核事件 ` ``gc." +"get_referrers``。" + +#: ../../library/gc.rst:184 +msgid "" +"Return a list of objects directly referred to by any of the arguments. The " +"referents returned are those objects visited by the arguments' C-level :c:" +"member:`~PyTypeObject.tp_traverse` methods (if any), and may not be all " +"objects actually directly reachable. :c:member:`~PyTypeObject.tp_traverse` " +"methods are supported only by objects that support garbage collection, and " +"are only required to visit objects that may be involved in a cycle. So, for " +"example, if an integer is directly reachable from an argument, that integer " +"object may or may not appear in the result list." +msgstr "" +"回傳包含被任意一個引數直接參照之物件的 list。回傳的被參照物件是有被引數的 C " +"語言級別 :c:member:`~PyTypeObject.tp_traverse` 方法（若存在）瀏覽到的物件，可" +"能不是所有的實際直接可達物件。只有支援垃圾回收的物件支援 :c:member:" +"`~PyTypeObject.tp_traverse` 方法，並且此方法只會瀏覽涉及參照迴圈的物件。因" +"此，可以有以下例子：一個整數對於一個引數是直接可達的，這個整數物件有可能出現" +"或不出現在結果的 list 當中。" + +#: ../../library/gc.rst:192 +msgid "" +"Raises an :ref:`auditing event ` ``gc.get_referents`` with " +"argument ``objs``." +msgstr "" +"引發一個附帶引數 ``objs`` 的\\ :ref:`稽核事件 ` ``gc." +"get_referents``。" + +#: ../../library/gc.rst:196 +msgid "" +"Returns ``True`` if the object is currently tracked by the garbage " +"collector, ``False`` otherwise. As a general rule, instances of atomic " +"types aren't tracked and instances of non-atomic types (containers, user-" +"defined objects...) are. However, some type-specific optimizations can be " +"present in order to suppress the garbage collector footprint of simple " +"instances (e.g. dicts containing only atomic keys and values)::" +msgstr "" +"當物件正在被垃圾回收器追蹤時回傳 ``True``，否則回傳 ``False``。一般來說，原子" +"型別 (atomic type) 的實例不會被追蹤，而非原子型別（如容器、使用者自己定義的物" +"件）會被追蹤。然而，有一些特定型別最佳化會被用來減少垃圾回收器在簡單實例（如" +"只含有原子性的鍵和值的字典）上的足跡： ::" + +#: ../../library/gc.rst:203 +msgid "" +">>> gc.is_tracked(0)\n" +"False\n" +">>> gc.is_tracked(\"a\")\n" +"False\n" +">>> gc.is_tracked([])\n" +"True\n" +">>> gc.is_tracked({})\n" +"False\n" +">>> gc.is_tracked({\"a\": 1})\n" +"True" +msgstr "" +">>> gc.is_tracked(0)\n" +"False\n" +">>> gc.is_tracked(\"a\")\n" +"False\n" +">>> gc.is_tracked([])\n" +"True\n" +">>> gc.is_tracked({})\n" +"False\n" +">>> gc.is_tracked({\"a\": 1})\n" +"True" + +#: ../../library/gc.rst:219 +msgid "" +"Returns ``True`` if the given object has been finalized by the garbage " +"collector, ``False`` otherwise. ::" +msgstr "" +"如果給定物件已被垃圾回收器終結則回傳 ``True``，否則回傳 ``False``。： ::" + +#: ../../library/gc.rst:222 +msgid "" +">>> x = None\n" +">>> class Lazarus:\n" +"... def __del__(self):\n" +"... global x\n" +"... x = self\n" +"...\n" +">>> lazarus = Lazarus()\n" +">>> gc.is_finalized(lazarus)\n" +"False\n" +">>> del lazarus\n" +">>> gc.is_finalized(x)\n" +"True" +msgstr "" +">>> x = None\n" +">>> class Lazarus:\n" +"... def __del__(self):\n" +"... global x\n" +"... x = self\n" +"...\n" +">>> lazarus = Lazarus()\n" +">>> gc.is_finalized(lazarus)\n" +"False\n" +">>> del lazarus\n" +">>> gc.is_finalized(x)\n" +"True" + +#: ../../library/gc.rst:240 +msgid "" +"Freeze all the objects tracked by the garbage collector; move them to a " +"permanent generation and ignore them in all the future collections." +msgstr "" +"凍結 (freeze) 垃圾回收器所追蹤的所有物件；將它們移至永久代並忽略所有未來的收" +"集動作。" + +#: ../../library/gc.rst:243 +msgid "" +"If a process will ``fork()`` without ``exec()``, avoiding unnecessary copy-" +"on-write in child processes will maximize memory sharing and reduce overall " +"memory usage. This requires both avoiding creation of freed \"holes\" in " +"memory pages in the parent process and ensuring that GC collections in child " +"processes won't touch the ``gc_refs`` counter of long-lived objects " +"originating in the parent process. To accomplish both, call ``gc.disable()`` " +"early in the parent process, ``gc.freeze()`` right before ``fork()``, and " +"``gc.enable()`` early in child processes." +msgstr "" +"如果一個行程將在沒有 ``exec()`` 的情況下進行 ``fork()``，避免子行程中不必要的" +"寫入時複製將最大化記憶體共享並減少整體記憶體使用。這需要避免在父行程的記憶體" +"頁面中建立已釋放的「漏洞」，並確保子行程中的 GC 收集不會觸及源自父行程的長壽" +"命物件的 ``gc_refs`` 計數器。要實現這兩個目標，請在父行程的早期呼叫 ``gc." +"disable()``，在 ``fork()`` 之前呼叫 ``gc.freeze()``，並儘早在子行程中呼叫 " +"``gc.enable()``。" + +#: ../../library/gc.rst:257 +msgid "" +"Unfreeze the objects in the permanent generation, put them back into the " +"oldest generation." +msgstr "解凍 (unfreeze) 永久代中的物件，並將它們放回到最年老代中。" + +#: ../../library/gc.rst:265 +msgid "Return the number of objects in the permanent generation." +msgstr "回傳永久代中的物件數量。" + +#: ../../library/gc.rst:270 +msgid "" +"The following variables are provided for read-only access (you can mutate " +"the values but should not rebind them):" +msgstr "以下變數僅供唯讀存取（你可以修改其值但不應該重新繫結 (rebind) 它們）：" + +#: ../../library/gc.rst:275 +msgid "" +"A list of objects which the collector found to be unreachable but could not " +"be freed (uncollectable objects). Starting with Python 3.4, this list " +"should be empty most of the time, except when using instances of C extension " +"types with a non-``NULL`` ``tp_del`` slot." +msgstr "" +"一個回收器發現不可達而又無法被釋放的物件（不可回收物件）list。從 Python 3.4 " +"開始，該 list 在大多數時候都應該是空的，除非使用了有非 ``NULL`` ``tp_del`` 槽" +"位的 C 擴充套件型別的實例。" + +#: ../../library/gc.rst:280 +msgid "" +"If :const:`DEBUG_SAVEALL` is set, then all unreachable objects will be added " +"to this list rather than freed." +msgstr "" +"如果設定了 :const:`DEBUG_SAVEALL`，則所有不可達物件將被加進該 list 而不會被釋" +"放。" + +#: ../../library/gc.rst:283 +msgid "" +"If this list is non-empty at :term:`interpreter shutdown`, a :exc:" +"`ResourceWarning` is emitted, which is silent by default. If :const:" +"`DEBUG_UNCOLLECTABLE` is set, in addition all uncollectable objects are " +"printed." +msgstr "" +"當 :term:`interpreter shutdown` 即直譯器關閉時，若此 list 非空，會產生 :exc:" +"`ResourceWarning`，在預設情況下此警告不會被提醒。如果設定了 :const:" +"`DEBUG_UNCOLLECTABLE`，所有無法被回收的物件會被印出。" + +#: ../../library/gc.rst:289 +msgid "" +"Following :pep:`442`, objects with a :meth:`~object.__del__` method don't " +"end up in :data:`gc.garbage` anymore." +msgstr "" +"根據 :pep:`442`，帶有 :meth:`~object.__del__` method 的物件最終不會在 :data:" +"`gc.garbage` 內。" + +#: ../../library/gc.rst:295 +msgid "" +"A list of callbacks that will be invoked by the garbage collector before and " +"after collection. The callbacks will be called with two arguments, *phase* " +"and *info*." +msgstr "" +"會被垃圾回收器在回收開始前和完成後叫用的一系列回呼函式 (callback) 。這些回呼" +"函式在被呼叫時附帶兩個引數：*phase* 和 *info*。" + +#: ../../library/gc.rst:299 +msgid "*phase* can be one of two values:" +msgstr "*phase* 可為以下兩者之一：" + +#: ../../library/gc.rst:301 +msgid "\"start\": The garbage collection is about to start." +msgstr "\"start\"：垃圾回收即將開始。" + +#: ../../library/gc.rst:303 +msgid "\"stop\": The garbage collection has finished." +msgstr "\"stop\"：垃圾回收已結束。" + +#: ../../library/gc.rst:305 +msgid "" +"*info* is a dict providing more information for the callback. The following " +"keys are currently defined:" +msgstr "*info* 是一個字典，提供回呼函式更多資訊。已有定義的鍵有：" + +#: ../../library/gc.rst:308 +msgid "\"generation\": The oldest generation being collected." +msgstr "\"generation\"（代）：正在被回收的最年老的一代。" + +#: ../../library/gc.rst:310 +msgid "" +"\"collected\": When *phase* is \"stop\", the number of objects successfully " +"collected." +msgstr "" +"\"collected\"（已回收的）：當 *phase* 為 \"stop\" 時，被成功回收的物件的數" +"目。" + +#: ../../library/gc.rst:313 +msgid "" +"\"uncollectable\": When *phase* is \"stop\", the number of objects that " +"could not be collected and were put in :data:`garbage`." +msgstr "" +"\"uncollectable\"（不可回收的）：當 *phase* 為 \"stop\" 時，不能被回收並被放" +"入 :data:`garbage` 的物件的數目。" + +#: ../../library/gc.rst:316 +msgid "" +"Applications can add their own callbacks to this list. The primary use " +"cases are:" +msgstr "應用程式可以把他們自己的回呼函式加入此 list。主要的使用場景有：" + +#: ../../library/gc.rst:319 +msgid "" +"Gathering statistics about garbage collection, such as how often various " +"generations are collected, and how long the collection takes." +msgstr "收集垃圾回收的統計資料，如：不同代的回收頻率、回收任務所花費的時間。" + +#: ../../library/gc.rst:323 +msgid "" +"Allowing applications to identify and clear their own uncollectable types " +"when they appear in :data:`garbage`." +msgstr "" +"讓應用程式可以識別和清理他們自己在 :data:`garbage` 中的不可回收型別物件。" + +#: ../../library/gc.rst:329 +msgid "The following constants are provided for use with :func:`set_debug`:" +msgstr "以下常數是為了和 :func:`set_debug` 一起使用所提供：" + +#: ../../library/gc.rst:334 +msgid "" +"Print statistics during collection. This information can be useful when " +"tuning the collection frequency." +msgstr "在回收完成後印出統計資訊。當調校回收頻率設定時，這些資訊會很有用。" + +#: ../../library/gc.rst:340 +msgid "Print information on collectable objects found." +msgstr "當發現可回收物件時印出資訊。" + +#: ../../library/gc.rst:345 +msgid "" +"Print information of uncollectable objects found (objects which are not " +"reachable but cannot be freed by the collector). These objects will be " +"added to the ``garbage`` list." +msgstr "" +"印出找到的不可回收物件的資訊（指不能被回收器回收的不可達物件）。這些物件會被" +"新增到 ``garbage`` list 中。" + +#: ../../library/gc.rst:349 +msgid "" +"Also print the contents of the :data:`garbage` list at :term:`interpreter " +"shutdown`, if it isn't empty." +msgstr "" +"當 :term:`interpreter shutdown`\\ （直譯器關閉）時，若 :data:`garbage` list " +"不是空的，那這些內容也會被印出。" + +#: ../../library/gc.rst:355 +msgid "" +"When set, all unreachable objects found will be appended to *garbage* rather " +"than being freed. This can be useful for debugging a leaking program." +msgstr "" +"設定後，所有回收器找到的不可達物件會被加進 *garbage* 而不是直接被釋放。這在為" +"一個記憶體流失的程式除錯時會很有用。" + +#: ../../library/gc.rst:361 +msgid "" +"The debugging flags necessary for the collector to print information about a " +"leaking program (equal to ``DEBUG_COLLECTABLE | DEBUG_UNCOLLECTABLE | " +"DEBUG_SAVEALL``)." +msgstr "" +"要印出記憶體流失程式之相關資訊時，回收器所需的除錯旗標。（等同於 " +"``DEBUG_COLLECTABLE | DEBUG_UNCOLLECTABLE | DEBUG_SAVEALL``）。" + +#~ msgid "" +#~ "The GC classifies objects into three generations depending on how many " +#~ "collection sweeps they have survived. New objects are placed in the " +#~ "youngest generation (generation ``0``). If an object survives a " +#~ "collection it is moved into the next older generation. Since generation " +#~ "``2`` is the oldest generation, objects in that generation remain there " +#~ "after a collection. In order to decide when to run, the collector keeps " +#~ "track of the number object allocations and deallocations since the last " +#~ "collection. When the number of allocations minus the number of " +#~ "deallocations exceeds *threshold0*, collection starts. Initially only " +#~ "generation ``0`` is examined. If generation ``0`` has been examined more " +#~ "than *threshold1* times since generation ``1`` has been examined, then " +#~ "generation ``1`` is examined as well. With the third generation, things " +#~ "are a bit more complicated, see `Collecting the oldest generation " +#~ "`_ for more information." +#~ msgstr "" +#~ "垃圾回收器會根據物件在多少次垃圾回收後仍倖存來把所有物件分類為三代。新建物" +#~ "件會被放在最年輕代（第 ``0`` 代）。 如果一個物件在一次垃圾回收後倖存，它會" +#~ "被移入下一個較老代。由於第 ``2`` 代是最老代，這一代的物件在一次垃圾回收後" +#~ "仍會保留原樣。為了確定何時要執行，垃圾回收器會追蹤自上一次回收後物件分配和" +#~ "釋放的數量。當分配數量減去釋放數量的結果大於 *threshold0* 時，垃圾回收就會" +#~ "開始。初始時只有第 ``0`` 代會被檢查。如果自第 ``1`` 代被檢查後第 ``0`` 代" +#~ "已被檢查超過 *threshold1* 次，則第 ``1`` 代也會被檢查。對於第三代來說，情" +#~ "況還會更復雜一些，請參閱 `Collecting the oldest generation `_ 來了解詳情。" diff --git a/library/getopt.po b/library/getopt.po index d96dc477a0..f1cc92be50 100644 --- a/library/getopt.po +++ b/library/getopt.po @@ -1,405 +1,405 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: 2016-01-31 07:19+0000\n" -"Last-Translator: Liang-Bo Wang \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/getopt.rst:2 -msgid ":mod:`!getopt` --- C-style parser for command line options" -msgstr ":mod:`!getopt` --- 用於命令列選項的 C 風格剖析器" - -#: ../../library/getopt.rst:8 -msgid "**Source code:** :source:`Lib/getopt.py`" -msgstr "**原始碼：**\\ :source:`Lib/getopt.py`" - -#: ../../library/getopt.rst:12 -msgid "" -"This module is considered feature complete. A more declarative and " -"extensible alternative to this API is provided in the :mod:`optparse` " -"module. Further functional enhancements for command line parameter " -"processing are provided either as third party modules on PyPI, or else as " -"features in the :mod:`argparse` module." -msgstr "" - -#: ../../library/getopt.rst:20 -msgid "" -"This module helps scripts to parse the command line arguments in " -"``sys.argv``. It supports the same conventions as the Unix :c:func:`!getopt` " -"function (including the special meanings of arguments of the form '``-``' " -"and '``--``'). Long options similar to those supported by GNU software may " -"be used as well via an optional third argument." -msgstr "" - -#: ../../library/getopt.rst:26 -msgid "" -"Users who are unfamiliar with the Unix :c:func:`!getopt` function should " -"consider using the :mod:`argparse` module instead. Users who are familiar " -"with the Unix :c:func:`!getopt` function, but would like to get equivalent " -"behavior while writing less code and getting better help and error messages " -"should consider using the :mod:`optparse` module. See :ref:`choosing-an-" -"argument-parser` for additional details." -msgstr "" - -#: ../../library/getopt.rst:33 -msgid "This module provides two functions and an exception:" -msgstr "這個模組提供兩個函式和一個例外：" - -#: ../../library/getopt.rst:39 -msgid "" -"Parses command line options and parameter list. *args* is the argument list " -"to be parsed, without the leading reference to the running program. " -"Typically, this means ``sys.argv[1:]``. *shortopts* is the string of option " -"letters that the script wants to recognize, with options that require an " -"argument followed by a colon (``':'``) and options that accept an optional " -"argument followed by two colons (``'::'``); i.e., the same format that " -"Unix :c:func:`!getopt` uses." -msgstr "" - -#: ../../library/getopt.rst:48 -msgid "" -"Unlike GNU :c:func:`!getopt`, after a non-option argument, all further " -"arguments are considered also non-options. This is similar to the way non-" -"GNU Unix systems work." -msgstr "" - -#: ../../library/getopt.rst:52 -msgid "" -"*longopts*, if specified, must be a list of strings with the names of the " -"long options which should be supported. The leading ``'--'`` characters " -"should not be included in the option name. Long options which require an " -"argument should be followed by an equal sign (``'='``). Long options which " -"accept an optional argument should be followed by an equal sign and question " -"mark (``'=?'``). To accept only long options, *shortopts* should be an empty " -"string. Long options on the command line can be recognized so long as they " -"provide a prefix of the option name that matches exactly one of the accepted " -"options. For example, if *longopts* is ``['foo', 'frob']``, the option ``--" -"fo`` will match as ``--foo``, but ``--f`` will not match uniquely, " -"so :exc:`GetoptError` will be raised." -msgstr "" - -#: ../../library/getopt.rst:65 -msgid "" -"The return value consists of two elements: the first is a list of ``(option, " -"value)`` pairs; the second is the list of program arguments left after the " -"option list was stripped (this is a trailing slice of *args*). Each option-" -"and-value pair returned has the option as its first element, prefixed with a " -"hyphen for short options (e.g., ``'-x'``) or two hyphens for long options " -"(e.g., ``'--long-option'``), and the option argument as its second element, " -"or an empty string if the option has no argument. The options occur in the " -"list in the same order in which they were found, thus allowing multiple " -"occurrences. Long and short options may be mixed." -msgstr "" - -#: ../../library/getopt.rst:75 -msgid "Optional arguments are supported." -msgstr "" - -#: ../../library/getopt.rst:81 -msgid "" -"This function works like :func:`getopt`, except that GNU style scanning mode " -"is used by default. This means that option and non-option arguments may be " -"intermixed. The :func:`getopt` function stops processing options as soon as " -"a non-option argument is encountered." -msgstr "" - -#: ../../library/getopt.rst:86 -msgid "" -"If the first character of the option string is ``'+'``, or if the " -"environment variable :envvar:`!POSIXLY_CORRECT` is set, then option " -"processing stops as soon as a non-option argument is encountered." -msgstr "" - -#: ../../library/getopt.rst:90 -msgid "" -"If the first character of the option string is ``'-'``, non-option arguments " -"that are followed by options are added to the list of option-and-value pairs " -"as a pair that has ``None`` as its first element and the list of non-option " -"arguments as its second element. The second element of the :func:`!" -"gnu_getopt` result is a list of program arguments after the last option." -msgstr "" - -#: ../../library/getopt.rst:97 -msgid "" -"Support for returning intermixed options and non-option arguments in order." -msgstr "" - -#: ../../library/getopt.rst:103 -msgid "" -"This is raised when an unrecognized option is found in the argument list or " -"when an option requiring an argument is given none. The argument to the " -"exception is a string indicating the cause of the error. For long options, " -"an argument given to an option which does not require one will also cause " -"this exception to be raised. The attributes :attr:`!msg` and :attr:`!opt` " -"give the error message and related option; if there is no specific option to " -"which the exception relates, :attr:`!opt` is an empty string." -msgstr "" - -#: ../../library/getopt.rst:114 -msgid "Alias for :exc:`GetoptError`; for backward compatibility." -msgstr "為了向後相容性而設的 :exc:`GetoptError` 別名。" - -#: ../../library/getopt.rst:116 -msgid "An example using only Unix style options:" -msgstr "一個僅使用 Unix 風格選項的範例：" - -#: ../../library/getopt.rst:118 -msgid "" -">>> import getopt\n" -">>> args = '-a -b -cfoo -d bar a1 a2'.split()\n" -">>> args\n" -"['-a', '-b', '-cfoo', '-d', 'bar', 'a1', 'a2']\n" -">>> optlist, args = getopt.getopt(args, 'abc:d:')\n" -">>> optlist\n" -"[('-a', ''), ('-b', ''), ('-c', 'foo'), ('-d', 'bar')]\n" -">>> args\n" -"['a1', 'a2']" -msgstr "" -">>> import getopt\n" -">>> args = '-a -b -cfoo -d bar a1 a2'.split()\n" -">>> args\n" -"['-a', '-b', '-cfoo', '-d', 'bar', 'a1', 'a2']\n" -">>> optlist, args = getopt.getopt(args, 'abc:d:')\n" -">>> optlist\n" -"[('-a', ''), ('-b', ''), ('-c', 'foo'), ('-d', 'bar')]\n" -">>> args\n" -"['a1', 'a2']" - -#: ../../library/getopt.rst:130 -msgid "Using long option names is equally easy:" -msgstr "使用長選項名稱同樣容易：" - -#: ../../library/getopt.rst:132 -msgid "" -">>> s = '--condition=foo --testing --output-file abc.def -x a1 a2'\n" -">>> args = s.split()\n" -">>> args\n" -"['--condition=foo', '--testing', '--output-file', 'abc.def', '-x', 'a1', " -"'a2']\n" -">>> optlist, args = getopt.getopt(args, 'x', [\n" -"... 'condition=', 'output-file=', 'testing'])\n" -">>> optlist\n" -"[('--condition', 'foo'), ('--testing', ''), ('--output-file', 'abc.def'), ('-" -"x', '')]\n" -">>> args\n" -"['a1', 'a2']" -msgstr "" -">>> s = '--condition=foo --testing --output-file abc.def -x a1 a2'\n" -">>> args = s.split()\n" -">>> args\n" -"['--condition=foo', '--testing', '--output-file', 'abc.def', '-x', 'a1', " -"'a2']\n" -">>> optlist, args = getopt.getopt(args, 'x', [\n" -"... 'condition=', 'output-file=', 'testing'])\n" -">>> optlist\n" -"[('--condition', 'foo'), ('--testing', ''), ('--output-file', 'abc.def'), ('-" -"x', '')]\n" -">>> args\n" -"['a1', 'a2']" - -#: ../../library/getopt.rst:145 -msgid "Optional arguments should be specified explicitly:" -msgstr "" - -#: ../../library/getopt.rst:147 -msgid "" -">>> s = '-Con -C --color=off --color a1 a2'\n" -">>> args = s.split()\n" -">>> args\n" -"['-Con', '-C', '--color=off', '--color', 'a1', 'a2']\n" -">>> optlist, args = getopt.getopt(args, 'C::', ['color=?'])\n" -">>> optlist\n" -"[('-C', 'on'), ('-C', ''), ('--color', 'off'), ('--color', '')]\n" -">>> args\n" -"['a1', 'a2']" -msgstr "" -">>> s = '-Con -C --color=off --color a1 a2'\n" -">>> args = s.split()\n" -">>> args\n" -"['-Con', '-C', '--color=off', '--color', 'a1', 'a2']\n" -">>> optlist, args = getopt.getopt(args, 'C::', ['color=?'])\n" -">>> optlist\n" -"[('-C', 'on'), ('-C', ''), ('--color', 'off'), ('--color', '')]\n" -">>> args\n" -"['a1', 'a2']" - -#: ../../library/getopt.rst:159 -msgid "The order of options and non-option arguments can be preserved:" -msgstr "" - -#: ../../library/getopt.rst:161 -msgid "" -">>> s = 'a1 -x a2 a3 a4 --long a5 a6'\n" -">>> args = s.split()\n" -">>> args\n" -"['a1', '-x', 'a2', 'a3', 'a4', '--long', 'a5', 'a6']\n" -">>> optlist, args = getopt.gnu_getopt(args, '-x:', ['long='])\n" -">>> optlist\n" -"[(None, ['a1']), ('-x', 'a2'), (None, ['a3', 'a4']), ('--long', 'a5')]\n" -">>> args\n" -"['a6']" -msgstr "" -">>> s = 'a1 -x a2 a3 a4 --long a5 a6'\n" -">>> args = s.split()\n" -">>> args\n" -"['a1', '-x', 'a2', 'a3', 'a4', '--long', 'a5', 'a6']\n" -">>> optlist, args = getopt.gnu_getopt(args, '-x:', ['long='])\n" -">>> optlist\n" -"[(None, ['a1']), ('-x', 'a2'), (None, ['a3', 'a4']), ('--long', 'a5')]\n" -">>> args\n" -"['a6']" - -#: ../../library/getopt.rst:173 -msgid "In a script, typical usage is something like this:" -msgstr "在腳本中，典型的用法如下：" - -#: ../../library/getopt.rst:175 -msgid "" -"import getopt, sys\n" -"\n" -"def main():\n" -" try:\n" -" opts, args = getopt.getopt(sys.argv[1:], \"ho:v\", [\"help\", " -"\"output=\"])\n" -" except getopt.GetoptError as err:\n" -" # print help information and exit:\n" -" print(err) # will print something like \"option -a not " -"recognized\"\n" -" usage()\n" -" sys.exit(2)\n" -" output = None\n" -" verbose = False\n" -" for o, a in opts:\n" -" if o == \"-v\":\n" -" verbose = True\n" -" elif o in (\"-h\", \"--help\"):\n" -" usage()\n" -" sys.exit()\n" -" elif o in (\"-o\", \"--output\"):\n" -" output = a\n" -" else:\n" -" assert False, \"unhandled option\"\n" -" process(args, output=output, verbose=verbose)\n" -"\n" -"if __name__ == \"__main__\":\n" -" main()" -msgstr "" -"import getopt, sys\n" -"\n" -"def main():\n" -" try:\n" -" opts, args = getopt.getopt(sys.argv[1:], \"ho:v\", [\"help\", " -"\"output=\"])\n" -" except getopt.GetoptError as err:\n" -" # 印出幫助訊息並退出：\n" -" print(err) # 會印出像是 \"option -a not recognized\" 的訊息\n" -" usage()\n" -" sys.exit(2)\n" -" output = None\n" -" verbose = False\n" -" for o, a in opts:\n" -" if o == \"-v\":\n" -" verbose = True\n" -" elif o in (\"-h\", \"--help\"):\n" -" usage()\n" -" sys.exit()\n" -" elif o in (\"-o\", \"--output\"):\n" -" output = a\n" -" else:\n" -" assert False, \"unhandled option\"\n" -" process(args, output=output, verbose=verbose)\n" -"\n" -"if __name__ == \"__main__\":\n" -" main()" - -#: ../../library/getopt.rst:204 -msgid "" -"Note that an equivalent command line interface could be produced with less " -"code and more informative help and error messages by using " -"the :mod:`optparse` module:" -msgstr "" - -#: ../../library/getopt.rst:207 -msgid "" -"import optparse\n" -"\n" -"if __name__ == '__main__':\n" -" parser = optparse.OptionParser()\n" -" parser.add_option('-o', '--output')\n" -" parser.add_option('-v', dest='verbose', action='store_true')\n" -" opts, args = parser.parse_args()\n" -" process(args, output=opts.output, verbose=opts.verbose)" -msgstr "" -"import optparse\n" -"\n" -"if __name__ == '__main__':\n" -" parser = optparse.OptionParser()\n" -" parser.add_option('-o', '--output')\n" -" parser.add_option('-v', dest='verbose', action='store_true')\n" -" opts, args = parser.parse_args()\n" -" process(args, output=opts.output, verbose=opts.verbose)" - -#: ../../library/getopt.rst:218 -msgid "" -"A roughly equivalent command line interface for this case can also be " -"produced by using the :mod:`argparse` module:" -msgstr "" - -#: ../../library/getopt.rst:221 -msgid "" -"import argparse\n" -"\n" -"if __name__ == '__main__':\n" -" parser = argparse.ArgumentParser()\n" -" parser.add_argument('-o', '--output')\n" -" parser.add_argument('-v', dest='verbose', action='store_true')\n" -" parser.add_argument('rest', nargs='*')\n" -" args = parser.parse_args()\n" -" process(args.rest, output=args.output, verbose=args.verbose)" -msgstr "" -"import argparse\n" -"\n" -"if __name__ == '__main__':\n" -" parser = argparse.ArgumentParser()\n" -" parser.add_argument('-o', '--output')\n" -" parser.add_argument('-v', dest='verbose', action='store_true')\n" -" parser.add_argument('rest', nargs='*')\n" -" args = parser.parse_args()\n" -" process(args.rest, output=args.output, verbose=args.verbose)" - -#: ../../library/getopt.rst:233 -msgid "" -"See :ref:`choosing-an-argument-parser` for details on how the ``argparse`` " -"version of this code differs in behaviour from the ``optparse`` (and " -"``getopt``) version." -msgstr "" -"參見 :ref:`choosing-an-argument-parser` 以瞭解這段程式碼的 ``argparse`` 版本" -"與 ``optparse``\\（以及 ``getopt``）版本在行為上的差異。" - -#: ../../library/getopt.rst:239 -msgid "Module :mod:`optparse`" -msgstr ":mod:`optparse` 模組" - -#: ../../library/getopt.rst:240 -msgid "Declarative command line option parsing." -msgstr "宣告式命令列選項剖析。" - -#: ../../library/getopt.rst:242 -msgid "Module :mod:`argparse`" -msgstr ":mod:`argparse` 模組" - -#: ../../library/getopt.rst:243 -msgid "More opinionated command line option and argument parsing library." -msgstr "" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: 2016-01-31 07:19+0000\n" +"Last-Translator: Liang-Bo Wang \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/getopt.rst:2 +msgid ":mod:`!getopt` --- C-style parser for command line options" +msgstr ":mod:`!getopt` --- 用於命令列選項的 C 風格剖析器" + +#: ../../library/getopt.rst:8 +msgid "**Source code:** :source:`Lib/getopt.py`" +msgstr "**原始碼：**\\ :source:`Lib/getopt.py`" + +#: ../../library/getopt.rst:12 +msgid "" +"This module is considered feature complete. A more declarative and " +"extensible alternative to this API is provided in the :mod:`optparse` " +"module. Further functional enhancements for command line parameter " +"processing are provided either as third party modules on PyPI, or else as " +"features in the :mod:`argparse` module." +msgstr "" + +#: ../../library/getopt.rst:20 +msgid "" +"This module helps scripts to parse the command line arguments in " +"``sys.argv``. It supports the same conventions as the Unix :c:func:`!getopt` " +"function (including the special meanings of arguments of the form '``-``' " +"and '``--``'). Long options similar to those supported by GNU software may " +"be used as well via an optional third argument." +msgstr "" + +#: ../../library/getopt.rst:26 +msgid "" +"Users who are unfamiliar with the Unix :c:func:`!getopt` function should " +"consider using the :mod:`argparse` module instead. Users who are familiar " +"with the Unix :c:func:`!getopt` function, but would like to get equivalent " +"behavior while writing less code and getting better help and error messages " +"should consider using the :mod:`optparse` module. See :ref:`choosing-an-" +"argument-parser` for additional details." +msgstr "" + +#: ../../library/getopt.rst:33 +msgid "This module provides two functions and an exception:" +msgstr "這個模組提供兩個函式和一個例外：" + +#: ../../library/getopt.rst:39 +msgid "" +"Parses command line options and parameter list. *args* is the argument list " +"to be parsed, without the leading reference to the running program. " +"Typically, this means ``sys.argv[1:]``. *shortopts* is the string of option " +"letters that the script wants to recognize, with options that require an " +"argument followed by a colon (``':'``) and options that accept an optional " +"argument followed by two colons (``'::'``); i.e., the same format that " +"Unix :c:func:`!getopt` uses." +msgstr "" + +#: ../../library/getopt.rst:48 +msgid "" +"Unlike GNU :c:func:`!getopt`, after a non-option argument, all further " +"arguments are considered also non-options. This is similar to the way non-" +"GNU Unix systems work." +msgstr "" + +#: ../../library/getopt.rst:52 +msgid "" +"*longopts*, if specified, must be a list of strings with the names of the " +"long options which should be supported. The leading ``'--'`` characters " +"should not be included in the option name. Long options which require an " +"argument should be followed by an equal sign (``'='``). Long options which " +"accept an optional argument should be followed by an equal sign and question " +"mark (``'=?'``). To accept only long options, *shortopts* should be an empty " +"string. Long options on the command line can be recognized so long as they " +"provide a prefix of the option name that matches exactly one of the accepted " +"options. For example, if *longopts* is ``['foo', 'frob']``, the option ``--" +"fo`` will match as ``--foo``, but ``--f`` will not match uniquely, " +"so :exc:`GetoptError` will be raised." +msgstr "" + +#: ../../library/getopt.rst:65 +msgid "" +"The return value consists of two elements: the first is a list of ``(option, " +"value)`` pairs; the second is the list of program arguments left after the " +"option list was stripped (this is a trailing slice of *args*). Each option-" +"and-value pair returned has the option as its first element, prefixed with a " +"hyphen for short options (e.g., ``'-x'``) or two hyphens for long options " +"(e.g., ``'--long-option'``), and the option argument as its second element, " +"or an empty string if the option has no argument. The options occur in the " +"list in the same order in which they were found, thus allowing multiple " +"occurrences. Long and short options may be mixed." +msgstr "" + +#: ../../library/getopt.rst:75 +msgid "Optional arguments are supported." +msgstr "" + +#: ../../library/getopt.rst:81 +msgid "" +"This function works like :func:`getopt`, except that GNU style scanning mode " +"is used by default. This means that option and non-option arguments may be " +"intermixed. The :func:`getopt` function stops processing options as soon as " +"a non-option argument is encountered." +msgstr "" + +#: ../../library/getopt.rst:86 +msgid "" +"If the first character of the option string is ``'+'``, or if the " +"environment variable :envvar:`!POSIXLY_CORRECT` is set, then option " +"processing stops as soon as a non-option argument is encountered." +msgstr "" + +#: ../../library/getopt.rst:90 +msgid "" +"If the first character of the option string is ``'-'``, non-option arguments " +"that are followed by options are added to the list of option-and-value pairs " +"as a pair that has ``None`` as its first element and the list of non-option " +"arguments as its second element. The second element of the :func:`!" +"gnu_getopt` result is a list of program arguments after the last option." +msgstr "" + +#: ../../library/getopt.rst:97 +msgid "" +"Support for returning intermixed options and non-option arguments in order." +msgstr "" + +#: ../../library/getopt.rst:103 +msgid "" +"This is raised when an unrecognized option is found in the argument list or " +"when an option requiring an argument is given none. The argument to the " +"exception is a string indicating the cause of the error. For long options, " +"an argument given to an option which does not require one will also cause " +"this exception to be raised. The attributes :attr:`!msg` and :attr:`!opt` " +"give the error message and related option; if there is no specific option to " +"which the exception relates, :attr:`!opt` is an empty string." +msgstr "" + +#: ../../library/getopt.rst:114 +msgid "Alias for :exc:`GetoptError`; for backward compatibility." +msgstr "為了向後相容性而設的 :exc:`GetoptError` 別名。" + +#: ../../library/getopt.rst:116 +msgid "An example using only Unix style options:" +msgstr "一個僅使用 Unix 風格選項的範例：" + +#: ../../library/getopt.rst:118 +msgid "" +">>> import getopt\n" +">>> args = '-a -b -cfoo -d bar a1 a2'.split()\n" +">>> args\n" +"['-a', '-b', '-cfoo', '-d', 'bar', 'a1', 'a2']\n" +">>> optlist, args = getopt.getopt(args, 'abc:d:')\n" +">>> optlist\n" +"[('-a', ''), ('-b', ''), ('-c', 'foo'), ('-d', 'bar')]\n" +">>> args\n" +"['a1', 'a2']" +msgstr "" +">>> import getopt\n" +">>> args = '-a -b -cfoo -d bar a1 a2'.split()\n" +">>> args\n" +"['-a', '-b', '-cfoo', '-d', 'bar', 'a1', 'a2']\n" +">>> optlist, args = getopt.getopt(args, 'abc:d:')\n" +">>> optlist\n" +"[('-a', ''), ('-b', ''), ('-c', 'foo'), ('-d', 'bar')]\n" +">>> args\n" +"['a1', 'a2']" + +#: ../../library/getopt.rst:130 +msgid "Using long option names is equally easy:" +msgstr "使用長選項名稱同樣容易：" + +#: ../../library/getopt.rst:132 +msgid "" +">>> s = '--condition=foo --testing --output-file abc.def -x a1 a2'\n" +">>> args = s.split()\n" +">>> args\n" +"['--condition=foo', '--testing', '--output-file', 'abc.def', '-x', 'a1', " +"'a2']\n" +">>> optlist, args = getopt.getopt(args, 'x', [\n" +"... 'condition=', 'output-file=', 'testing'])\n" +">>> optlist\n" +"[('--condition', 'foo'), ('--testing', ''), ('--output-file', 'abc.def'), ('-" +"x', '')]\n" +">>> args\n" +"['a1', 'a2']" +msgstr "" +">>> s = '--condition=foo --testing --output-file abc.def -x a1 a2'\n" +">>> args = s.split()\n" +">>> args\n" +"['--condition=foo', '--testing', '--output-file', 'abc.def', '-x', 'a1', " +"'a2']\n" +">>> optlist, args = getopt.getopt(args, 'x', [\n" +"... 'condition=', 'output-file=', 'testing'])\n" +">>> optlist\n" +"[('--condition', 'foo'), ('--testing', ''), ('--output-file', 'abc.def'), ('-" +"x', '')]\n" +">>> args\n" +"['a1', 'a2']" + +#: ../../library/getopt.rst:145 +msgid "Optional arguments should be specified explicitly:" +msgstr "" + +#: ../../library/getopt.rst:147 +msgid "" +">>> s = '-Con -C --color=off --color a1 a2'\n" +">>> args = s.split()\n" +">>> args\n" +"['-Con', '-C', '--color=off', '--color', 'a1', 'a2']\n" +">>> optlist, args = getopt.getopt(args, 'C::', ['color=?'])\n" +">>> optlist\n" +"[('-C', 'on'), ('-C', ''), ('--color', 'off'), ('--color', '')]\n" +">>> args\n" +"['a1', 'a2']" +msgstr "" +">>> s = '-Con -C --color=off --color a1 a2'\n" +">>> args = s.split()\n" +">>> args\n" +"['-Con', '-C', '--color=off', '--color', 'a1', 'a2']\n" +">>> optlist, args = getopt.getopt(args, 'C::', ['color=?'])\n" +">>> optlist\n" +"[('-C', 'on'), ('-C', ''), ('--color', 'off'), ('--color', '')]\n" +">>> args\n" +"['a1', 'a2']" + +#: ../../library/getopt.rst:159 +msgid "The order of options and non-option arguments can be preserved:" +msgstr "" + +#: ../../library/getopt.rst:161 +msgid "" +">>> s = 'a1 -x a2 a3 a4 --long a5 a6'\n" +">>> args = s.split()\n" +">>> args\n" +"['a1', '-x', 'a2', 'a3', 'a4', '--long', 'a5', 'a6']\n" +">>> optlist, args = getopt.gnu_getopt(args, '-x:', ['long='])\n" +">>> optlist\n" +"[(None, ['a1']), ('-x', 'a2'), (None, ['a3', 'a4']), ('--long', 'a5')]\n" +">>> args\n" +"['a6']" +msgstr "" +">>> s = 'a1 -x a2 a3 a4 --long a5 a6'\n" +">>> args = s.split()\n" +">>> args\n" +"['a1', '-x', 'a2', 'a3', 'a4', '--long', 'a5', 'a6']\n" +">>> optlist, args = getopt.gnu_getopt(args, '-x:', ['long='])\n" +">>> optlist\n" +"[(None, ['a1']), ('-x', 'a2'), (None, ['a3', 'a4']), ('--long', 'a5')]\n" +">>> args\n" +"['a6']" + +#: ../../library/getopt.rst:173 +msgid "In a script, typical usage is something like this:" +msgstr "在腳本中，典型的用法如下：" + +#: ../../library/getopt.rst:175 +msgid "" +"import getopt, sys\n" +"\n" +"def main():\n" +" try:\n" +" opts, args = getopt.getopt(sys.argv[1:], \"ho:v\", [\"help\", " +"\"output=\"])\n" +" except getopt.GetoptError as err:\n" +" # print help information and exit:\n" +" print(err) # will print something like \"option -a not " +"recognized\"\n" +" usage()\n" +" sys.exit(2)\n" +" output = None\n" +" verbose = False\n" +" for o, a in opts:\n" +" if o == \"-v\":\n" +" verbose = True\n" +" elif o in (\"-h\", \"--help\"):\n" +" usage()\n" +" sys.exit()\n" +" elif o in (\"-o\", \"--output\"):\n" +" output = a\n" +" else:\n" +" assert False, \"unhandled option\"\n" +" process(args, output=output, verbose=verbose)\n" +"\n" +"if __name__ == \"__main__\":\n" +" main()" +msgstr "" +"import getopt, sys\n" +"\n" +"def main():\n" +" try:\n" +" opts, args = getopt.getopt(sys.argv[1:], \"ho:v\", [\"help\", " +"\"output=\"])\n" +" except getopt.GetoptError as err:\n" +" # 印出幫助訊息並退出：\n" +" print(err) # 會印出像是 \"option -a not recognized\" 的訊息\n" +" usage()\n" +" sys.exit(2)\n" +" output = None\n" +" verbose = False\n" +" for o, a in opts:\n" +" if o == \"-v\":\n" +" verbose = True\n" +" elif o in (\"-h\", \"--help\"):\n" +" usage()\n" +" sys.exit()\n" +" elif o in (\"-o\", \"--output\"):\n" +" output = a\n" +" else:\n" +" assert False, \"unhandled option\"\n" +" process(args, output=output, verbose=verbose)\n" +"\n" +"if __name__ == \"__main__\":\n" +" main()" + +#: ../../library/getopt.rst:204 +msgid "" +"Note that an equivalent command line interface could be produced with less " +"code and more informative help and error messages by using " +"the :mod:`optparse` module:" +msgstr "" + +#: ../../library/getopt.rst:207 +msgid "" +"import optparse\n" +"\n" +"if __name__ == '__main__':\n" +" parser = optparse.OptionParser()\n" +" parser.add_option('-o', '--output')\n" +" parser.add_option('-v', dest='verbose', action='store_true')\n" +" opts, args = parser.parse_args()\n" +" process(args, output=opts.output, verbose=opts.verbose)" +msgstr "" +"import optparse\n" +"\n" +"if __name__ == '__main__':\n" +" parser = optparse.OptionParser()\n" +" parser.add_option('-o', '--output')\n" +" parser.add_option('-v', dest='verbose', action='store_true')\n" +" opts, args = parser.parse_args()\n" +" process(args, output=opts.output, verbose=opts.verbose)" + +#: ../../library/getopt.rst:218 +msgid "" +"A roughly equivalent command line interface for this case can also be " +"produced by using the :mod:`argparse` module:" +msgstr "" + +#: ../../library/getopt.rst:221 +msgid "" +"import argparse\n" +"\n" +"if __name__ == '__main__':\n" +" parser = argparse.ArgumentParser()\n" +" parser.add_argument('-o', '--output')\n" +" parser.add_argument('-v', dest='verbose', action='store_true')\n" +" parser.add_argument('rest', nargs='*')\n" +" args = parser.parse_args()\n" +" process(args.rest, output=args.output, verbose=args.verbose)" +msgstr "" +"import argparse\n" +"\n" +"if __name__ == '__main__':\n" +" parser = argparse.ArgumentParser()\n" +" parser.add_argument('-o', '--output')\n" +" parser.add_argument('-v', dest='verbose', action='store_true')\n" +" parser.add_argument('rest', nargs='*')\n" +" args = parser.parse_args()\n" +" process(args.rest, output=args.output, verbose=args.verbose)" + +#: ../../library/getopt.rst:233 +msgid "" +"See :ref:`choosing-an-argument-parser` for details on how the ``argparse`` " +"version of this code differs in behaviour from the ``optparse`` (and " +"``getopt``) version." +msgstr "" +"參見 :ref:`choosing-an-argument-parser` 以瞭解這段程式碼的 ``argparse`` 版本" +"與 ``optparse``\\（以及 ``getopt``）版本在行為上的差異。" + +#: ../../library/getopt.rst:239 +msgid "Module :mod:`optparse`" +msgstr ":mod:`optparse` 模組" + +#: ../../library/getopt.rst:240 +msgid "Declarative command line option parsing." +msgstr "宣告式命令列選項剖析。" + +#: ../../library/getopt.rst:242 +msgid "Module :mod:`argparse`" +msgstr ":mod:`argparse` 模組" + +#: ../../library/getopt.rst:243 +msgid "More opinionated command line option and argument parsing library." +msgstr "" diff --git a/library/getpass.po b/library/getpass.po index 93118b2782..988724400e 100644 --- a/library/getpass.po +++ b/library/getpass.po @@ -1,127 +1,127 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Matt Wang , 2022 -# Weilin Du, 2025 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-18 00:15+0000\n" -"PO-Revision-Date: 2022-02-11 12:04+0800\n" -"Last-Translator: Weilin Du\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/getpass.rst:2 -msgid ":mod:`!getpass` --- Portable password input" -msgstr ":mod:`!getpass` --- 可攜式密碼輸入工具" - -#: ../../library/getpass.rst:11 -msgid "**Source code:** :source:`Lib/getpass.py`" -msgstr "**原始碼：**\\ :source:`Lib/getpass.py`" - -#: ../../includes/wasm-notavail.rst:3 -msgid "Availability" -msgstr "可用性" - -#: ../../includes/wasm-notavail.rst:5 -msgid "" -"This module does not work or is not available on WebAssembly. See :ref:`wasm-" -"availability` for more information." -msgstr "" -"此模組在 WebAssembly 平台上不起作用或無法使用。更多資訊請參閱 :ref:`wasm-" -"availability`。" - -#: ../../library/getpass.rst:17 -msgid "The :mod:`getpass` module provides two functions:" -msgstr ":mod:`getpass` 模組 (module) 提供了兩個函式：" - -#: ../../library/getpass.rst:21 -msgid "" -"Prompt the user for a password without echoing. The user is prompted using " -"the string *prompt*, which defaults to ``'Password: '``. On Unix, the " -"prompt is written to the file-like object *stream* using the replace error " -"handler if needed. *stream* defaults to the controlling terminal (:file:`/" -"dev/tty`) or if that is unavailable to ``sys.stderr`` (this argument is " -"ignored on Windows)." -msgstr "" -"提示使用者輸入一個密碼且不會有回音 (echo)。使用者會看到字串 *prompt* 作為提" -"示，其預設值為 ``'Password: '``。在 Unix 上，如有必要的話會使用替換錯誤處理函" -"式 (replace error handler) 寫入到類檔案物件 (file-like object) *stream*\\ " -"中。*stream* 預設為主控終端機 (controlling terminal) (\\ :file:`/dev/" -"tty`\\ )，如果不可用則為 ``sys.stderr`` (此引數在 Windows 上會被忽略)。" - -#: ../../library/getpass.rst:28 -msgid "" -"The *echo_char* argument controls how user input is displayed while typing. " -"If *echo_char* is ``None`` (default), input remains hidden. Otherwise, " -"*echo_char* must be a single printable ASCII character and each typed " -"character is replaced by it. For example, ``echo_char='*'`` will display " -"asterisks instead of the actual input." -msgstr "" - -#: ../../library/getpass.rst:34 -msgid "" -"If echo free input is unavailable getpass() falls back to printing a warning " -"message to *stream* and reading from ``sys.stdin`` and issuing a :exc:" -"`GetPassWarning`." -msgstr "" -"如果無回音輸入 (echo-free input) 無法使用則 getpass() 將回退為印出一條警告訊" -"息到 *stream*，並從 ``sys.stdin`` 讀取且同時發出 :exc:`GetPassWarning`。" - -#: ../../library/getpass.rst:39 -msgid "" -"If you call getpass from within IDLE, the input may be done in the terminal " -"you launched IDLE from rather than the idle window itself." -msgstr "" -"如果你從 IDLE 內部呼叫 getpass，輸入可能會在你啟動 IDLE 的終端機中完成，而非" -"在 IDLE 視窗中。" - -#: ../../library/getpass.rst:43 -msgid "" -"On Unix systems, when *echo_char* is set, the terminal will be configured to " -"operate in :manpage:`noncanonical mode " -"`. In particular, this means " -"that line editing shortcuts such as :kbd:`Ctrl+U` will not work and may " -"insert unexpected characters into the input." -msgstr "" - -#: ../../library/getpass.rst:50 -msgid "Added the *echo_char* parameter for keyboard feedback." -msgstr "" - -#: ../../library/getpass.rst:55 -msgid "A :exc:`UserWarning` subclass issued when password input may be echoed." -msgstr "當密碼輸入可能被回音時會發出的 :exc:`UserWarning` 子類別。" - -#: ../../library/getpass.rst:60 -msgid "Return the \"login name\" of the user." -msgstr "回傳使用者的\"登入名稱\"。" - -#: ../../library/getpass.rst:62 -msgid "" -"This function checks the environment variables :envvar:`LOGNAME`, :envvar:" -"`USER`, :envvar:`!LNAME` and :envvar:`USERNAME`, in order, and returns the " -"value of the first one which is set to a non-empty string. If none are set, " -"the login name from the password database is returned on systems which " -"support the :mod:`pwd` module, otherwise, an :exc:`OSError` is raised." -msgstr "" -"此函式會按順序檢查環境變數 :envvar:`LOGNAME`、:envvar:`USER`、:envvar:`!" -"LNAME` 和 :envvar:`USERNAME`，並回傳其中第一個被設定成非空字串的值。如果均未" -"設定，則在支援 :mod:`pwd` 模組的系統上將會回傳來自密碼資料庫的登入名稱，否則" -"將引發一個 :exc:`OSError` 例外。" - -#: ../../library/getpass.rst:69 -msgid "In general, this function should be preferred over :func:`os.getlogin`." -msgstr "大部分情況下，此函式應該要比 :func:`os.getlogin` 優先使用。" - -#: ../../library/getpass.rst:71 -msgid "Previously, various exceptions beyond just :exc:`OSError` were raised." -msgstr "在過去，除了 :exc:`OSError` 外還會引發各種例外。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Matt Wang , 2022 +# Weilin Du, 2025 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-18 00:15+0000\n" +"PO-Revision-Date: 2022-02-11 12:04+0800\n" +"Last-Translator: Weilin Du\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/getpass.rst:2 +msgid ":mod:`!getpass` --- Portable password input" +msgstr ":mod:`!getpass` --- 可攜式密碼輸入工具" + +#: ../../library/getpass.rst:11 +msgid "**Source code:** :source:`Lib/getpass.py`" +msgstr "**原始碼：**\\ :source:`Lib/getpass.py`" + +#: ../../includes/wasm-notavail.rst:3 +msgid "Availability" +msgstr "可用性" + +#: ../../includes/wasm-notavail.rst:5 +msgid "" +"This module does not work or is not available on WebAssembly. See :ref:`wasm-" +"availability` for more information." +msgstr "" +"此模組在 WebAssembly 平台上不起作用或無法使用。更多資訊請參閱 :ref:`wasm-" +"availability`。" + +#: ../../library/getpass.rst:17 +msgid "The :mod:`getpass` module provides two functions:" +msgstr ":mod:`getpass` 模組 (module) 提供了兩個函式：" + +#: ../../library/getpass.rst:21 +msgid "" +"Prompt the user for a password without echoing. The user is prompted using " +"the string *prompt*, which defaults to ``'Password: '``. On Unix, the " +"prompt is written to the file-like object *stream* using the replace error " +"handler if needed. *stream* defaults to the controlling terminal (:file:`/" +"dev/tty`) or if that is unavailable to ``sys.stderr`` (this argument is " +"ignored on Windows)." +msgstr "" +"提示使用者輸入一個密碼且不會有回音 (echo)。使用者會看到字串 *prompt* 作為提" +"示，其預設值為 ``'Password: '``。在 Unix 上，如有必要的話會使用替換錯誤處理函" +"式 (replace error handler) 寫入到類檔案物件 (file-like object) *stream*\\ " +"中。*stream* 預設為主控終端機 (controlling terminal) (\\ :file:`/dev/" +"tty`\\ )，如果不可用則為 ``sys.stderr`` (此引數在 Windows 上會被忽略)。" + +#: ../../library/getpass.rst:28 +msgid "" +"The *echo_char* argument controls how user input is displayed while typing. " +"If *echo_char* is ``None`` (default), input remains hidden. Otherwise, " +"*echo_char* must be a single printable ASCII character and each typed " +"character is replaced by it. For example, ``echo_char='*'`` will display " +"asterisks instead of the actual input." +msgstr "" + +#: ../../library/getpass.rst:34 +msgid "" +"If echo free input is unavailable getpass() falls back to printing a warning " +"message to *stream* and reading from ``sys.stdin`` and issuing a :exc:" +"`GetPassWarning`." +msgstr "" +"如果無回音輸入 (echo-free input) 無法使用則 getpass() 將回退為印出一條警告訊" +"息到 *stream*，並從 ``sys.stdin`` 讀取且同時發出 :exc:`GetPassWarning`。" + +#: ../../library/getpass.rst:39 +msgid "" +"If you call getpass from within IDLE, the input may be done in the terminal " +"you launched IDLE from rather than the idle window itself." +msgstr "" +"如果你從 IDLE 內部呼叫 getpass，輸入可能會在你啟動 IDLE 的終端機中完成，而非" +"在 IDLE 視窗中。" + +#: ../../library/getpass.rst:43 +msgid "" +"On Unix systems, when *echo_char* is set, the terminal will be configured to " +"operate in :manpage:`noncanonical mode " +"`. In particular, this means " +"that line editing shortcuts such as :kbd:`Ctrl+U` will not work and may " +"insert unexpected characters into the input." +msgstr "" + +#: ../../library/getpass.rst:50 +msgid "Added the *echo_char* parameter for keyboard feedback." +msgstr "" + +#: ../../library/getpass.rst:55 +msgid "A :exc:`UserWarning` subclass issued when password input may be echoed." +msgstr "當密碼輸入可能被回音時會發出的 :exc:`UserWarning` 子類別。" + +#: ../../library/getpass.rst:60 +msgid "Return the \"login name\" of the user." +msgstr "回傳使用者的\"登入名稱\"。" + +#: ../../library/getpass.rst:62 +msgid "" +"This function checks the environment variables :envvar:`LOGNAME`, :envvar:" +"`USER`, :envvar:`!LNAME` and :envvar:`USERNAME`, in order, and returns the " +"value of the first one which is set to a non-empty string. If none are set, " +"the login name from the password database is returned on systems which " +"support the :mod:`pwd` module, otherwise, an :exc:`OSError` is raised." +msgstr "" +"此函式會按順序檢查環境變數 :envvar:`LOGNAME`、:envvar:`USER`、:envvar:`!" +"LNAME` 和 :envvar:`USERNAME`，並回傳其中第一個被設定成非空字串的值。如果均未" +"設定，則在支援 :mod:`pwd` 模組的系統上將會回傳來自密碼資料庫的登入名稱，否則" +"將引發一個 :exc:`OSError` 例外。" + +#: ../../library/getpass.rst:69 +msgid "In general, this function should be preferred over :func:`os.getlogin`." +msgstr "大部分情況下，此函式應該要比 :func:`os.getlogin` 優先使用。" + +#: ../../library/getpass.rst:71 +msgid "Previously, various exceptions beyond just :exc:`OSError` were raised." +msgstr "在過去，除了 :exc:`OSError` 外還會引發各種例外。" diff --git a/library/gettext.po b/library/gettext.po index bc20d1e31f..aa03181df3 100644 --- a/library/gettext.po +++ b/library/gettext.po @@ -1,959 +1,959 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-09-03 11:11+0800\n" -"PO-Revision-Date: 2018-05-23 16:02+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/gettext.rst:2 -msgid ":mod:`!gettext` --- Multilingual internationalization services" -msgstr ":mod:`!gettext` --- 多語言國際化服務" - -#: ../../library/gettext.rst:10 -msgid "**Source code:** :source:`Lib/gettext.py`" -msgstr "**原始碼：**\\ :source:`Lib/gettext.py`" - -#: ../../library/gettext.rst:14 -msgid "" -"The :mod:`gettext` module provides internationalization (I18N) and " -"localization (L10N) services for your Python modules and applications. It " -"supports both the GNU :program:`gettext` message catalog API and a higher " -"level, class-based API that may be more appropriate for Python files. The " -"interface described below allows you to write your module and application " -"messages in one natural language, and provide a catalog of translated " -"messages for running under different natural languages." -msgstr "" - -#: ../../library/gettext.rst:22 -msgid "" -"Some hints on localizing your Python modules and applications are also given." -msgstr "" - -#: ../../library/gettext.rst:26 -msgid "GNU :program:`gettext` API" -msgstr "GNU :program:`gettext` API" - -#: ../../library/gettext.rst:28 -msgid "" -"The :mod:`gettext` module defines the following API, which is very similar " -"to the GNU :program:`gettext` API. If you use this API you will affect the " -"translation of your entire application globally. Often this is what you " -"want if your application is monolingual, with the choice of language " -"dependent on the locale of your user. If you are localizing a Python " -"module, or if your application needs to switch languages on the fly, you " -"probably want to use the class-based API instead." -msgstr "" - -#: ../../library/gettext.rst:39 -msgid "" -"Bind the *domain* to the locale directory *localedir*. More concretely, :" -"mod:`gettext` will look for binary :file:`.mo` files for the given domain " -"using the path (on Unix): :file:`{localedir}/{language}/LC_MESSAGES/{domain}." -"mo`, where *language* is searched for in the environment variables :envvar:" -"`LANGUAGE`, :envvar:`LC_ALL`, :envvar:`LC_MESSAGES`, and :envvar:`LANG` " -"respectively." -msgstr "" - -#: ../../library/gettext.rst:45 -msgid "" -"If *localedir* is omitted or ``None``, then the current binding for *domain* " -"is returned. [#]_" -msgstr "" - -#: ../../library/gettext.rst:51 -msgid "" -"Change or query the current global domain. If *domain* is ``None``, then " -"the current global domain is returned, otherwise the global domain is set to " -"*domain*, which is returned." -msgstr "" - -#: ../../library/gettext.rst:59 -msgid "" -"Return the localized translation of *message*, based on the current global " -"domain, language, and locale directory. This function is usually aliased " -"as :func:`!_` in the local namespace (see examples below)." -msgstr "" - -#: ../../library/gettext.rst:66 -msgid "" -"Like :func:`.gettext`, but look the message up in the specified *domain*." -msgstr "" - -#: ../../library/gettext.rst:71 -msgid "" -"Like :func:`.gettext`, but consider plural forms. If a translation is found, " -"apply the plural formula to *n*, and return the resulting message (some " -"languages have more than two plural forms). If no translation is found, " -"return *singular* if *n* is 1; return *plural* otherwise." -msgstr "" - -#: ../../library/gettext.rst:76 -msgid "" -"The Plural formula is taken from the catalog header. It is a C or Python " -"expression that has a free variable *n*; the expression evaluates to the " -"index of the plural in the catalog. See `the GNU gettext documentation " -"`__ for the " -"precise syntax to be used in :file:`.po` files and the formulas for a " -"variety of languages." -msgstr "" - -#: ../../library/gettext.rst:86 -msgid "" -"Like :func:`ngettext`, but look the message up in the specified *domain*." -msgstr "" - -#: ../../library/gettext.rst:94 -msgid "" -"Similar to the corresponding functions without the ``p`` in the prefix (that " -"is, :func:`gettext`, :func:`dgettext`, :func:`ngettext`, :func:`dngettext`), " -"but the translation is restricted to the given message *context*." -msgstr "" - -#: ../../library/gettext.rst:101 -msgid "" -"Note that GNU :program:`gettext` also defines a :func:`!dcgettext` method, " -"but this was deemed not useful and so it is currently unimplemented." -msgstr "" - -#: ../../library/gettext.rst:104 -msgid "Here's an example of typical usage for this API::" -msgstr "" - -#: ../../library/gettext.rst:106 -msgid "" -"import gettext\n" -"gettext.bindtextdomain('myapplication', '/path/to/my/language/directory')\n" -"gettext.textdomain('myapplication')\n" -"_ = gettext.gettext\n" -"# ...\n" -"print(_('This is a translatable string.'))" -msgstr "" -"import gettext\n" -"gettext.bindtextdomain('myapplication', '/path/to/my/language/directory')\n" -"gettext.textdomain('myapplication')\n" -"_ = gettext.gettext\n" -"# ...\n" -"print(_('This is a translatable string.'))" - -#: ../../library/gettext.rst:115 -msgid "Class-based API" -msgstr "" - -#: ../../library/gettext.rst:117 -msgid "" -"The class-based API of the :mod:`gettext` module gives you more flexibility " -"and greater convenience than the GNU :program:`gettext` API. It is the " -"recommended way of localizing your Python applications and modules. :mod:`!" -"gettext` defines a :class:`GNUTranslations` class which implements the " -"parsing of GNU :file:`.mo` format files, and has methods for returning " -"strings. Instances of this class can also install themselves in the built-in " -"namespace as the function :func:`!_`." -msgstr "" - -#: ../../library/gettext.rst:127 -msgid "" -"This function implements the standard :file:`.mo` file search algorithm. It " -"takes a *domain*, identical to what :func:`textdomain` takes. Optional " -"*localedir* is as in :func:`bindtextdomain`. Optional *languages* is a list " -"of strings, where each string is a language code." -msgstr "" - -#: ../../library/gettext.rst:132 -msgid "" -"If *localedir* is not given, then the default system locale directory is " -"used. [#]_ If *languages* is not given, then the following environment " -"variables are searched: :envvar:`LANGUAGE`, :envvar:`LC_ALL`, :envvar:" -"`LC_MESSAGES`, and :envvar:`LANG`. The first one returning a non-empty " -"value is used for the *languages* variable. The environment variables should " -"contain a colon separated list of languages, which will be split on the " -"colon to produce the expected list of language code strings." -msgstr "" - -#: ../../library/gettext.rst:140 -msgid "" -":func:`find` then expands and normalizes the languages, and then iterates " -"through them, searching for an existing file built of these components:" -msgstr "" - -#: ../../library/gettext.rst:143 -msgid ":file:`{localedir}/{language}/LC_MESSAGES/{domain}.mo`" -msgstr ":file:`{localedir}/{language}/LC_MESSAGES/{domain}.mo`" - -#: ../../library/gettext.rst:145 -msgid "" -"The first such file name that exists is returned by :func:`find`. If no such " -"file is found, then ``None`` is returned. If *all* is given, it returns a " -"list of all file names, in the order in which they appear in the languages " -"list or the environment variables." -msgstr "" - -#: ../../library/gettext.rst:153 -msgid "" -"Return a ``*Translations`` instance based on the *domain*, *localedir*, and " -"*languages*, which are first passed to :func:`find` to get a list of the " -"associated :file:`.mo` file paths. Instances with identical :file:`.mo` " -"file names are cached. The actual class instantiated is *class_* if " -"provided, otherwise :class:`GNUTranslations`. The class's constructor must " -"take a single :term:`file object` argument." -msgstr "" - -#: ../../library/gettext.rst:160 -msgid "" -"If multiple files are found, later files are used as fallbacks for earlier " -"ones. To allow setting the fallback, :func:`copy.copy` is used to clone each " -"translation object from the cache; the actual instance data is still shared " -"with the cache." -msgstr "" - -#: ../../library/gettext.rst:165 -msgid "" -"If no :file:`.mo` file is found, this function raises :exc:`OSError` if " -"*fallback* is false (which is the default), and returns a :class:" -"`NullTranslations` instance if *fallback* is true." -msgstr "" - -#: ../../library/gettext.rst:169 -msgid ":exc:`IOError` used to be raised, it is now an alias of :exc:`OSError`." -msgstr ":exc:`IOError` 曾經被引發，現在它是一個 :exc:`OSError` 的別名。" - -#: ../../library/gettext.rst:172 -msgid "*codeset* parameter is removed." -msgstr "*codeset* 參數被移除。" - -#: ../../library/gettext.rst:177 -msgid "" -"This installs the function :func:`!_` in Python's builtins namespace, based " -"on *domain* and *localedir* which are passed to the function :func:" -"`translation`." -msgstr "" - -#: ../../library/gettext.rst:180 -msgid "" -"For the *names* parameter, please see the description of the translation " -"object's :meth:`~NullTranslations.install` method." -msgstr "" - -#: ../../library/gettext.rst:183 -msgid "" -"As seen below, you usually mark the strings in your application that are " -"candidates for translation, by wrapping them in a call to the :func:`!_` " -"function, like this::" -msgstr "" - -#: ../../library/gettext.rst:187 -msgid "print(_('This string will be translated.'))" -msgstr "print(_('This string will be translated.'))" - -#: ../../library/gettext.rst:189 -msgid "" -"For convenience, you want the :func:`!_` function to be installed in " -"Python's builtins namespace, so it is easily accessible in all modules of " -"your application." -msgstr "" - -#: ../../library/gettext.rst:193 -msgid "*names* is now a keyword-only parameter." -msgstr "" - -#: ../../library/gettext.rst:197 -msgid "The :class:`NullTranslations` class" -msgstr "" - -#: ../../library/gettext.rst:199 -msgid "" -"Translation classes are what actually implement the translation of original " -"source file message strings to translated message strings. The base class " -"used by all translation classes is :class:`NullTranslations`; this provides " -"the basic interface you can use to write your own specialized translation " -"classes. Here are the methods of :class:`!NullTranslations`:" -msgstr "" - -#: ../../library/gettext.rst:208 -msgid "" -"Takes an optional :term:`file object` *fp*, which is ignored by the base " -"class. Initializes \"protected\" instance variables *_info* and *_charset* " -"which are set by derived classes, as well as *_fallback*, which is set " -"through :meth:`add_fallback`. It then calls ``self._parse(fp)`` if *fp* is " -"not ``None``." -msgstr "" - -#: ../../library/gettext.rst:216 -msgid "" -"No-op in the base class, this method takes file object *fp*, and reads the " -"data from the file, initializing its message catalog. If you have an " -"unsupported message catalog file format, you should override this method to " -"parse your format." -msgstr "" - -#: ../../library/gettext.rst:224 -msgid "" -"Add *fallback* as the fallback object for the current translation object. A " -"translation object should consult the fallback if it cannot provide a " -"translation for a given message." -msgstr "" - -#: ../../library/gettext.rst:231 -msgid "" -"If a fallback has been set, forward :meth:`!gettext` to the fallback. " -"Otherwise, return *message*. Overridden in derived classes." -msgstr "" - -#: ../../library/gettext.rst:237 -msgid "" -"If a fallback has been set, forward :meth:`!ngettext` to the fallback. " -"Otherwise, return *singular* if *n* is 1; return *plural* otherwise. " -"Overridden in derived classes." -msgstr "" - -#: ../../library/gettext.rst:244 -msgid "" -"If a fallback has been set, forward :meth:`pgettext` to the fallback. " -"Otherwise, return the translated message. Overridden in derived classes." -msgstr "" - -#: ../../library/gettext.rst:252 -msgid "" -"If a fallback has been set, forward :meth:`npgettext` to the fallback. " -"Otherwise, return the translated message. Overridden in derived classes." -msgstr "" - -#: ../../library/gettext.rst:260 -msgid "" -"Return a dictionary containing the metadata found in the message catalog " -"file." -msgstr "" - -#: ../../library/gettext.rst:266 -msgid "Return the encoding of the message catalog file." -msgstr "" - -#: ../../library/gettext.rst:271 -msgid "" -"This method installs :meth:`.gettext` into the built-in namespace, binding " -"it to ``_``." -msgstr "" - -#: ../../library/gettext.rst:274 -msgid "" -"If the *names* parameter is given, it must be a sequence containing the " -"names of functions you want to install in the builtins namespace in addition " -"to :func:`!_`. Supported names are ``'gettext'``, ``'ngettext'``, " -"``'pgettext'``, and ``'npgettext'``." -msgstr "" - -#: ../../library/gettext.rst:279 -msgid "" -"Note that this is only one way, albeit the most convenient way, to make the :" -"func:`!_` function available to your application. Because it affects the " -"entire application globally, and specifically the built-in namespace, " -"localized modules should never install :func:`!_`. Instead, they should use " -"this code to make :func:`!_` available to their module::" -msgstr "" - -#: ../../library/gettext.rst:285 -msgid "" -"import gettext\n" -"t = gettext.translation('mymodule', ...)\n" -"_ = t.gettext" -msgstr "" -"import gettext\n" -"t = gettext.translation('mymodule', ...)\n" -"_ = t.gettext" - -#: ../../library/gettext.rst:289 -msgid "" -"This puts :func:`!_` only in the module's global namespace and so only " -"affects calls within this module." -msgstr "" - -#: ../../library/gettext.rst:292 -msgid "Added ``'pgettext'`` and ``'npgettext'``." -msgstr "新增 ``'pgettext'`` 與 ``'npgettext'``。" - -#: ../../library/gettext.rst:297 -msgid "The :class:`GNUTranslations` class" -msgstr "" - -#: ../../library/gettext.rst:299 -msgid "" -"The :mod:`!gettext` module provides one additional class derived from :class:" -"`NullTranslations`: :class:`GNUTranslations`. This class overrides :meth:`!" -"_parse` to enable reading GNU :program:`gettext` format :file:`.mo` files in " -"both big-endian and little-endian format." -msgstr "" - -#: ../../library/gettext.rst:304 -msgid "" -":class:`GNUTranslations` parses optional metadata out of the translation " -"catalog. It is convention with GNU :program:`gettext` to include metadata as " -"the translation for the empty string. This metadata is in :rfc:`822`\\ -" -"style ``key: value`` pairs, and should contain the ``Project-Id-Version`` " -"key. If the key ``Content-Type`` is found, then the ``charset`` property is " -"used to initialize the \"protected\" :attr:`!_charset` instance variable, " -"defaulting to ``None`` if not found. If the charset encoding is specified, " -"then all message ids and message strings read from the catalog are converted " -"to Unicode using this encoding, else ASCII is assumed." -msgstr "" - -#: ../../library/gettext.rst:314 -msgid "" -"Since message ids are read as Unicode strings too, all ``*gettext()`` " -"methods will assume message ids as Unicode strings, not byte strings." -msgstr "" - -#: ../../library/gettext.rst:317 -msgid "" -"The entire set of key/value pairs are placed into a dictionary and set as " -"the \"protected\" :attr:`!_info` instance variable." -msgstr "" - -#: ../../library/gettext.rst:320 -msgid "" -"If the :file:`.mo` file's magic number is invalid, the major version number " -"is unexpected, or if other problems occur while reading the file, " -"instantiating a :class:`GNUTranslations` class can raise :exc:`OSError`." -msgstr "" - -#: ../../library/gettext.rst:326 -msgid "" -"The following methods are overridden from the base class implementation:" -msgstr "" - -#: ../../library/gettext.rst:330 -msgid "" -"Look up the *message* id in the catalog and return the corresponding message " -"string, as a Unicode string. If there is no entry in the catalog for the " -"*message* id, and a fallback has been set, the look up is forwarded to the " -"fallback's :meth:`~NullTranslations.gettext` method. Otherwise, the " -"*message* id is returned." -msgstr "" - -#: ../../library/gettext.rst:339 -msgid "" -"Do a plural-forms lookup of a message id. *singular* is used as the message " -"id for purposes of lookup in the catalog, while *n* is used to determine " -"which plural form to use. The returned message string is a Unicode string." -msgstr "" - -#: ../../library/gettext.rst:343 -msgid "" -"If the message id is not found in the catalog, and a fallback is specified, " -"the request is forwarded to the fallback's :meth:`~NullTranslations." -"ngettext` method. Otherwise, when *n* is 1 *singular* is returned, and " -"*plural* is returned in all other cases." -msgstr "" - -#: ../../library/gettext.rst:348 -msgid "Here is an example::" -msgstr "以下是個範例： ::" - -#: ../../library/gettext.rst:350 -msgid "" -"n = len(os.listdir('.'))\n" -"cat = GNUTranslations(somefile)\n" -"message = cat.ngettext(\n" -" 'There is %(num)d file in this directory',\n" -" 'There are %(num)d files in this directory',\n" -" n) % {'num': n}" -msgstr "" -"n = len(os.listdir('.'))\n" -"cat = GNUTranslations(somefile)\n" -"message = cat.ngettext(\n" -" 'There is %(num)d file in this directory',\n" -" 'There are %(num)d files in this directory',\n" -" n) % {'num': n}" - -#: ../../library/gettext.rst:360 -msgid "" -"Look up the *context* and *message* id in the catalog and return the " -"corresponding message string, as a Unicode string. If there is no entry in " -"the catalog for the *message* id and *context*, and a fallback has been set, " -"the look up is forwarded to the fallback's :meth:`pgettext` method. " -"Otherwise, the *message* id is returned." -msgstr "" - -#: ../../library/gettext.rst:371 -msgid "" -"Do a plural-forms lookup of a message id. *singular* is used as the message " -"id for purposes of lookup in the catalog, while *n* is used to determine " -"which plural form to use." -msgstr "" - -#: ../../library/gettext.rst:375 -msgid "" -"If the message id for *context* is not found in the catalog, and a fallback " -"is specified, the request is forwarded to the fallback's :meth:`npgettext` " -"method. Otherwise, when *n* is 1 *singular* is returned, and *plural* is " -"returned in all other cases." -msgstr "" - -#: ../../library/gettext.rst:384 -msgid "Solaris message catalog support" -msgstr "" - -#: ../../library/gettext.rst:386 -msgid "" -"The Solaris operating system defines its own binary :file:`.mo` file format, " -"but since no documentation can be found on this format, it is not supported " -"at this time." -msgstr "" - -#: ../../library/gettext.rst:392 -msgid "The Catalog constructor" -msgstr "" - -#: ../../library/gettext.rst:396 -msgid "" -"GNOME uses a version of the :mod:`gettext` module by James Henstridge, but " -"this version has a slightly different API. Its documented usage was::" -msgstr "" - -#: ../../library/gettext.rst:399 -msgid "" -"import gettext\n" -"cat = gettext.Catalog(domain, localedir)\n" -"_ = cat.gettext\n" -"print(_('hello world'))" -msgstr "" -"import gettext\n" -"cat = gettext.Catalog(domain, localedir)\n" -"_ = cat.gettext\n" -"print(_('hello world'))" - -#: ../../library/gettext.rst:404 -msgid "" -"For compatibility with this older module, the function :func:`!Catalog` is " -"an alias for the :func:`translation` function described above." -msgstr "" - -#: ../../library/gettext.rst:407 -msgid "" -"One difference between this module and Henstridge's: his catalog objects " -"supported access through a mapping API, but this appears to be unused and so " -"is not currently supported." -msgstr "" - -#: ../../library/gettext.rst:414 -msgid "Internationalizing your programs and modules" -msgstr "" - -#: ../../library/gettext.rst:416 -msgid "" -"Internationalization (I18N) refers to the operation by which a program is " -"made aware of multiple languages. Localization (L10N) refers to the " -"adaptation of your program, once internationalized, to the local language " -"and cultural habits. In order to provide multilingual messages for your " -"Python programs, you need to take the following steps:" -msgstr "" - -#: ../../library/gettext.rst:422 -msgid "" -"prepare your program or module by specially marking translatable strings" -msgstr "" - -#: ../../library/gettext.rst:424 -msgid "" -"run a suite of tools over your marked files to generate raw messages catalogs" -msgstr "" - -#: ../../library/gettext.rst:426 -msgid "create language-specific translations of the message catalogs" -msgstr "" - -#: ../../library/gettext.rst:428 -msgid "" -"use the :mod:`gettext` module so that message strings are properly translated" -msgstr "" - -#: ../../library/gettext.rst:430 -msgid "" -"In order to prepare your code for I18N, you need to look at all the strings " -"in your files. Any string that needs to be translated should be marked by " -"wrapping it in ``_('...')`` --- that is, a call to the function :func:`_ " -"`. For example::" -msgstr "" - -#: ../../library/gettext.rst:434 -msgid "" -"filename = 'mylog.txt'\n" -"message = _('writing a log message')\n" -"with open(filename, 'w') as fp:\n" -" fp.write(message)" -msgstr "" -"filename = 'mylog.txt'\n" -"message = _('writing a log message')\n" -"with open(filename, 'w') as fp:\n" -" fp.write(message)" - -#: ../../library/gettext.rst:439 -msgid "" -"In this example, the string ``'writing a log message'`` is marked as a " -"candidate for translation, while the strings ``'mylog.txt'`` and ``'w'`` are " -"not." -msgstr "" - -#: ../../library/gettext.rst:442 -msgid "" -"There are a few tools to extract the strings meant for translation. The " -"original GNU :program:`gettext` only supported C or C++ source code but its " -"extended version :program:`xgettext` scans code written in a number of " -"languages, including Python, to find strings marked as translatable. `Babel " -"`__ is a Python internationalization library that " -"includes a :file:`pybabel` script to extract and compile message catalogs. " -"François Pinard's program called :program:`xpot` does a similar job and is " -"available as part of his `po-utils package `__." -msgstr "" - -#: ../../library/gettext.rst:452 -msgid "" -"(Python also includes pure-Python versions of these programs, called :" -"program:`pygettext.py` and :program:`msgfmt.py`; some Python distributions " -"will install them for you. :program:`pygettext.py` is similar to :program:" -"`xgettext`, but only understands Python source code and cannot handle other " -"programming languages such as C or C++. :program:`pygettext.py` supports a " -"command-line interface similar to :program:`xgettext`; for details on its " -"use, run ``pygettext.py --help``. :program:`msgfmt.py` is binary compatible " -"with GNU :program:`msgfmt`. With these two programs, you may not need the " -"GNU :program:`gettext` package to internationalize your Python applications.)" -msgstr "" - -#: ../../library/gettext.rst:464 -msgid "" -":program:`xgettext`, :program:`pygettext`, and similar tools generate :file:" -"`.po` files that are message catalogs. They are structured human-readable " -"files that contain every marked string in the source code, along with a " -"placeholder for the translated versions of these strings." -msgstr "" - -#: ../../library/gettext.rst:470 -msgid "" -"Copies of these :file:`.po` files are then handed over to the individual " -"human translators who write translations for every supported natural " -"language. They send back the completed language-specific versions as a :" -"file:`.po` file that's compiled into a machine-readable :file:" -"`.mo` binary catalog file using the :program:`msgfmt` program. The :file:`." -"mo` files are used by the :mod:`gettext` module for the actual translation " -"processing at run-time." -msgstr "" - -#: ../../library/gettext.rst:479 -msgid "" -"How you use the :mod:`gettext` module in your code depends on whether you " -"are internationalizing a single module or your entire application. The next " -"two sections will discuss each case." -msgstr "" - -#: ../../library/gettext.rst:485 -msgid "Localizing your module" -msgstr "" - -#: ../../library/gettext.rst:487 -msgid "" -"If you are localizing your module, you must take care not to make global " -"changes, e.g. to the built-in namespace. You should not use the GNU :program:" -"`gettext` API but instead the class-based API." -msgstr "" - -#: ../../library/gettext.rst:491 -msgid "" -"Let's say your module is called \"spam\" and the module's various natural " -"language translation :file:`.mo` files reside in :file:`/usr/share/locale` " -"in GNU :program:`gettext` format. Here's what you would put at the top of " -"your module::" -msgstr "" - -#: ../../library/gettext.rst:496 -msgid "" -"import gettext\n" -"t = gettext.translation('spam', '/usr/share/locale')\n" -"_ = t.gettext" -msgstr "" -"import gettext\n" -"t = gettext.translation('spam', '/usr/share/locale')\n" -"_ = t.gettext" - -#: ../../library/gettext.rst:502 -msgid "Localizing your application" -msgstr "" - -#: ../../library/gettext.rst:504 -msgid "" -"If you are localizing your application, you can install the :func:`!_` " -"function globally into the built-in namespace, usually in the main driver " -"file of your application. This will let all your application-specific files " -"just use ``_('...')`` without having to explicitly install it in each file." -msgstr "" - -#: ../../library/gettext.rst:509 -msgid "" -"In the simple case then, you need only add the following bit of code to the " -"main driver file of your application::" -msgstr "" - -#: ../../library/gettext.rst:512 -msgid "" -"import gettext\n" -"gettext.install('myapplication')" -msgstr "" -"import gettext\n" -"gettext.install('myapplication')" - -#: ../../library/gettext.rst:515 -msgid "" -"If you need to set the locale directory, you can pass it into the :func:" -"`install` function::" -msgstr "" - -#: ../../library/gettext.rst:518 -msgid "" -"import gettext\n" -"gettext.install('myapplication', '/usr/share/locale')" -msgstr "" -"import gettext\n" -"gettext.install('myapplication', '/usr/share/locale')" - -#: ../../library/gettext.rst:523 -msgid "Changing languages on the fly" -msgstr "" - -#: ../../library/gettext.rst:525 -msgid "" -"If your program needs to support many languages at the same time, you may " -"want to create multiple translation instances and then switch between them " -"explicitly, like so::" -msgstr "" - -#: ../../library/gettext.rst:529 -msgid "" -"import gettext\n" -"\n" -"lang1 = gettext.translation('myapplication', languages=['en'])\n" -"lang2 = gettext.translation('myapplication', languages=['fr'])\n" -"lang3 = gettext.translation('myapplication', languages=['de'])\n" -"\n" -"# start by using language1\n" -"lang1.install()\n" -"\n" -"# ... time goes by, user selects language 2\n" -"lang2.install()\n" -"\n" -"# ... more time goes by, user selects language 3\n" -"lang3.install()" -msgstr "" - -#: ../../library/gettext.rst:546 -msgid "Deferred translations" -msgstr "" - -#: ../../library/gettext.rst:548 -msgid "" -"In most coding situations, strings are translated where they are coded. " -"Occasionally however, you need to mark strings for translation, but defer " -"actual translation until later. A classic example is::" -msgstr "" - -#: ../../library/gettext.rst:552 -msgid "" -"animals = ['mollusk',\n" -" 'albatross',\n" -" 'rat',\n" -" 'penguin',\n" -" 'python', ]\n" -"# ...\n" -"for a in animals:\n" -" print(a)" -msgstr "" -"animals = ['mollusk',\n" -" 'albatross',\n" -" 'rat',\n" -" 'penguin',\n" -" 'python', ]\n" -"# ...\n" -"for a in animals:\n" -" print(a)" - -#: ../../library/gettext.rst:561 -msgid "" -"Here, you want to mark the strings in the ``animals`` list as being " -"translatable, but you don't actually want to translate them until they are " -"printed." -msgstr "" - -#: ../../library/gettext.rst:565 -msgid "Here is one way you can handle this situation::" -msgstr "" - -#: ../../library/gettext.rst:567 -msgid "" -"def _(message): return message\n" -"\n" -"animals = [_('mollusk'),\n" -" _('albatross'),\n" -" _('rat'),\n" -" _('penguin'),\n" -" _('python'), ]\n" -"\n" -"del _\n" -"\n" -"# ...\n" -"for a in animals:\n" -" print(_(a))" -msgstr "" -"def _(message): return message\n" -"\n" -"animals = [_('mollusk'),\n" -" _('albatross'),\n" -" _('rat'),\n" -" _('penguin'),\n" -" _('python'), ]\n" -"\n" -"del _\n" -"\n" -"# ...\n" -"for a in animals:\n" -" print(_(a))" - -#: ../../library/gettext.rst:581 -msgid "" -"This works because the dummy definition of :func:`!_` simply returns the " -"string unchanged. And this dummy definition will temporarily override any " -"definition of :func:`!_` in the built-in namespace (until the :keyword:`del` " -"command). Take care, though if you have a previous definition of :func:`!_` " -"in the local namespace." -msgstr "" - -#: ../../library/gettext.rst:587 -msgid "" -"Note that the second use of :func:`!_` will not identify \"a\" as being " -"translatable to the :program:`gettext` program, because the parameter is not " -"a string literal." -msgstr "" - -#: ../../library/gettext.rst:591 -msgid "Another way to handle this is with the following example::" -msgstr "" - -#: ../../library/gettext.rst:593 -msgid "" -"def N_(message): return message\n" -"\n" -"animals = [N_('mollusk'),\n" -" N_('albatross'),\n" -" N_('rat'),\n" -" N_('penguin'),\n" -" N_('python'), ]\n" -"\n" -"# ...\n" -"for a in animals:\n" -" print(_(a))" -msgstr "" -"def N_(message): return message\n" -"\n" -"animals = [N_('mollusk'),\n" -" N_('albatross'),\n" -" N_('rat'),\n" -" N_('penguin'),\n" -" N_('python'), ]\n" -"\n" -"# ...\n" -"for a in animals:\n" -" print(_(a))" - -#: ../../library/gettext.rst:605 -msgid "" -"In this case, you are marking translatable strings with the function :func:`!" -"N_`, which won't conflict with any definition of :func:`!_`. However, you " -"will need to teach your message extraction program to look for translatable " -"strings marked with :func:`!N_`. :program:`xgettext`, :program:`pygettext`, " -"``pybabel extract``, and :program:`xpot` all support this through the use of " -"the :option:`!-k` command-line switch. The choice of :func:`!N_` here is " -"totally arbitrary; it could have just as easily been :func:`!" -"MarkThisStringForTranslation`." -msgstr "" - -#: ../../library/gettext.rst:616 -msgid "Acknowledgements" -msgstr "致謝" - -#: ../../library/gettext.rst:618 -msgid "" -"The following people contributed code, feedback, design suggestions, " -"previous implementations, and valuable experience to the creation of this " -"module:" -msgstr "" - -#: ../../library/gettext.rst:621 -msgid "Peter Funk" -msgstr "Peter Funk" - -#: ../../library/gettext.rst:623 -msgid "James Henstridge" -msgstr "James Henstridge" - -#: ../../library/gettext.rst:625 -msgid "Juan David Ibáñez Palomar" -msgstr "Juan David Ibáñez Palomar" - -#: ../../library/gettext.rst:627 -msgid "Marc-André Lemburg" -msgstr "Marc-André Lemburg" - -#: ../../library/gettext.rst:629 -msgid "Martin von Löwis" -msgstr "Martin von Löwis" - -#: ../../library/gettext.rst:631 -msgid "François Pinard" -msgstr "François Pinard" - -#: ../../library/gettext.rst:633 -msgid "Barry Warsaw" -msgstr "Barry Warsaw" - -#: ../../library/gettext.rst:635 -msgid "Gustavo Niemeyer" -msgstr "Gustavo Niemeyer" - -#: ../../library/gettext.rst:638 -msgid "Footnotes" -msgstr "註解" - -#: ../../library/gettext.rst:639 -msgid "" -"The default locale directory is system dependent; for example, on Red Hat " -"Linux it is :file:`/usr/share/locale`, but on Solaris it is :file:`/usr/lib/" -"locale`. The :mod:`!gettext` module does not try to support these system " -"dependent defaults; instead its default is :file:`{sys.base_prefix}/share/" -"locale` (see :data:`sys.base_prefix`). For this reason, it is always best to " -"call :func:`bindtextdomain` with an explicit absolute path at the start of " -"your application." -msgstr "" - -#: ../../library/gettext.rst:647 -msgid "See the footnote for :func:`bindtextdomain` above." -msgstr "請見上方 :func:`bindtextdomain` 之註解。" - -#: ../../library/gettext.rst:56 -msgid "_ (underscore)" -msgstr "_ （底線）" - -#: ../../library/gettext.rst:56 -msgid "gettext" -msgstr "gettext" - -#: ../../library/gettext.rst:394 -msgid "GNOME" -msgstr "GNOME" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-09-03 11:11+0800\n" +"PO-Revision-Date: 2018-05-23 16:02+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/gettext.rst:2 +msgid ":mod:`!gettext` --- Multilingual internationalization services" +msgstr ":mod:`!gettext` --- 多語言國際化服務" + +#: ../../library/gettext.rst:10 +msgid "**Source code:** :source:`Lib/gettext.py`" +msgstr "**原始碼：**\\ :source:`Lib/gettext.py`" + +#: ../../library/gettext.rst:14 +msgid "" +"The :mod:`gettext` module provides internationalization (I18N) and " +"localization (L10N) services for your Python modules and applications. It " +"supports both the GNU :program:`gettext` message catalog API and a higher " +"level, class-based API that may be more appropriate for Python files. The " +"interface described below allows you to write your module and application " +"messages in one natural language, and provide a catalog of translated " +"messages for running under different natural languages." +msgstr "" + +#: ../../library/gettext.rst:22 +msgid "" +"Some hints on localizing your Python modules and applications are also given." +msgstr "" + +#: ../../library/gettext.rst:26 +msgid "GNU :program:`gettext` API" +msgstr "GNU :program:`gettext` API" + +#: ../../library/gettext.rst:28 +msgid "" +"The :mod:`gettext` module defines the following API, which is very similar " +"to the GNU :program:`gettext` API. If you use this API you will affect the " +"translation of your entire application globally. Often this is what you " +"want if your application is monolingual, with the choice of language " +"dependent on the locale of your user. If you are localizing a Python " +"module, or if your application needs to switch languages on the fly, you " +"probably want to use the class-based API instead." +msgstr "" + +#: ../../library/gettext.rst:39 +msgid "" +"Bind the *domain* to the locale directory *localedir*. More concretely, :" +"mod:`gettext` will look for binary :file:`.mo` files for the given domain " +"using the path (on Unix): :file:`{localedir}/{language}/LC_MESSAGES/{domain}." +"mo`, where *language* is searched for in the environment variables :envvar:" +"`LANGUAGE`, :envvar:`LC_ALL`, :envvar:`LC_MESSAGES`, and :envvar:`LANG` " +"respectively." +msgstr "" + +#: ../../library/gettext.rst:45 +msgid "" +"If *localedir* is omitted or ``None``, then the current binding for *domain* " +"is returned. [#]_" +msgstr "" + +#: ../../library/gettext.rst:51 +msgid "" +"Change or query the current global domain. If *domain* is ``None``, then " +"the current global domain is returned, otherwise the global domain is set to " +"*domain*, which is returned." +msgstr "" + +#: ../../library/gettext.rst:59 +msgid "" +"Return the localized translation of *message*, based on the current global " +"domain, language, and locale directory. This function is usually aliased " +"as :func:`!_` in the local namespace (see examples below)." +msgstr "" + +#: ../../library/gettext.rst:66 +msgid "" +"Like :func:`.gettext`, but look the message up in the specified *domain*." +msgstr "" + +#: ../../library/gettext.rst:71 +msgid "" +"Like :func:`.gettext`, but consider plural forms. If a translation is found, " +"apply the plural formula to *n*, and return the resulting message (some " +"languages have more than two plural forms). If no translation is found, " +"return *singular* if *n* is 1; return *plural* otherwise." +msgstr "" + +#: ../../library/gettext.rst:76 +msgid "" +"The Plural formula is taken from the catalog header. It is a C or Python " +"expression that has a free variable *n*; the expression evaluates to the " +"index of the plural in the catalog. See `the GNU gettext documentation " +"`__ for the " +"precise syntax to be used in :file:`.po` files and the formulas for a " +"variety of languages." +msgstr "" + +#: ../../library/gettext.rst:86 +msgid "" +"Like :func:`ngettext`, but look the message up in the specified *domain*." +msgstr "" + +#: ../../library/gettext.rst:94 +msgid "" +"Similar to the corresponding functions without the ``p`` in the prefix (that " +"is, :func:`gettext`, :func:`dgettext`, :func:`ngettext`, :func:`dngettext`), " +"but the translation is restricted to the given message *context*." +msgstr "" + +#: ../../library/gettext.rst:101 +msgid "" +"Note that GNU :program:`gettext` also defines a :func:`!dcgettext` method, " +"but this was deemed not useful and so it is currently unimplemented." +msgstr "" + +#: ../../library/gettext.rst:104 +msgid "Here's an example of typical usage for this API::" +msgstr "" + +#: ../../library/gettext.rst:106 +msgid "" +"import gettext\n" +"gettext.bindtextdomain('myapplication', '/path/to/my/language/directory')\n" +"gettext.textdomain('myapplication')\n" +"_ = gettext.gettext\n" +"# ...\n" +"print(_('This is a translatable string.'))" +msgstr "" +"import gettext\n" +"gettext.bindtextdomain('myapplication', '/path/to/my/language/directory')\n" +"gettext.textdomain('myapplication')\n" +"_ = gettext.gettext\n" +"# ...\n" +"print(_('This is a translatable string.'))" + +#: ../../library/gettext.rst:115 +msgid "Class-based API" +msgstr "" + +#: ../../library/gettext.rst:117 +msgid "" +"The class-based API of the :mod:`gettext` module gives you more flexibility " +"and greater convenience than the GNU :program:`gettext` API. It is the " +"recommended way of localizing your Python applications and modules. :mod:`!" +"gettext` defines a :class:`GNUTranslations` class which implements the " +"parsing of GNU :file:`.mo` format files, and has methods for returning " +"strings. Instances of this class can also install themselves in the built-in " +"namespace as the function :func:`!_`." +msgstr "" + +#: ../../library/gettext.rst:127 +msgid "" +"This function implements the standard :file:`.mo` file search algorithm. It " +"takes a *domain*, identical to what :func:`textdomain` takes. Optional " +"*localedir* is as in :func:`bindtextdomain`. Optional *languages* is a list " +"of strings, where each string is a language code." +msgstr "" + +#: ../../library/gettext.rst:132 +msgid "" +"If *localedir* is not given, then the default system locale directory is " +"used. [#]_ If *languages* is not given, then the following environment " +"variables are searched: :envvar:`LANGUAGE`, :envvar:`LC_ALL`, :envvar:" +"`LC_MESSAGES`, and :envvar:`LANG`. The first one returning a non-empty " +"value is used for the *languages* variable. The environment variables should " +"contain a colon separated list of languages, which will be split on the " +"colon to produce the expected list of language code strings." +msgstr "" + +#: ../../library/gettext.rst:140 +msgid "" +":func:`find` then expands and normalizes the languages, and then iterates " +"through them, searching for an existing file built of these components:" +msgstr "" + +#: ../../library/gettext.rst:143 +msgid ":file:`{localedir}/{language}/LC_MESSAGES/{domain}.mo`" +msgstr ":file:`{localedir}/{language}/LC_MESSAGES/{domain}.mo`" + +#: ../../library/gettext.rst:145 +msgid "" +"The first such file name that exists is returned by :func:`find`. If no such " +"file is found, then ``None`` is returned. If *all* is given, it returns a " +"list of all file names, in the order in which they appear in the languages " +"list or the environment variables." +msgstr "" + +#: ../../library/gettext.rst:153 +msgid "" +"Return a ``*Translations`` instance based on the *domain*, *localedir*, and " +"*languages*, which are first passed to :func:`find` to get a list of the " +"associated :file:`.mo` file paths. Instances with identical :file:`.mo` " +"file names are cached. The actual class instantiated is *class_* if " +"provided, otherwise :class:`GNUTranslations`. The class's constructor must " +"take a single :term:`file object` argument." +msgstr "" + +#: ../../library/gettext.rst:160 +msgid "" +"If multiple files are found, later files are used as fallbacks for earlier " +"ones. To allow setting the fallback, :func:`copy.copy` is used to clone each " +"translation object from the cache; the actual instance data is still shared " +"with the cache." +msgstr "" + +#: ../../library/gettext.rst:165 +msgid "" +"If no :file:`.mo` file is found, this function raises :exc:`OSError` if " +"*fallback* is false (which is the default), and returns a :class:" +"`NullTranslations` instance if *fallback* is true." +msgstr "" + +#: ../../library/gettext.rst:169 +msgid ":exc:`IOError` used to be raised, it is now an alias of :exc:`OSError`." +msgstr ":exc:`IOError` 曾經被引發，現在它是一個 :exc:`OSError` 的別名。" + +#: ../../library/gettext.rst:172 +msgid "*codeset* parameter is removed." +msgstr "*codeset* 參數被移除。" + +#: ../../library/gettext.rst:177 +msgid "" +"This installs the function :func:`!_` in Python's builtins namespace, based " +"on *domain* and *localedir* which are passed to the function :func:" +"`translation`." +msgstr "" + +#: ../../library/gettext.rst:180 +msgid "" +"For the *names* parameter, please see the description of the translation " +"object's :meth:`~NullTranslations.install` method." +msgstr "" + +#: ../../library/gettext.rst:183 +msgid "" +"As seen below, you usually mark the strings in your application that are " +"candidates for translation, by wrapping them in a call to the :func:`!_` " +"function, like this::" +msgstr "" + +#: ../../library/gettext.rst:187 +msgid "print(_('This string will be translated.'))" +msgstr "print(_('This string will be translated.'))" + +#: ../../library/gettext.rst:189 +msgid "" +"For convenience, you want the :func:`!_` function to be installed in " +"Python's builtins namespace, so it is easily accessible in all modules of " +"your application." +msgstr "" + +#: ../../library/gettext.rst:193 +msgid "*names* is now a keyword-only parameter." +msgstr "" + +#: ../../library/gettext.rst:197 +msgid "The :class:`NullTranslations` class" +msgstr "" + +#: ../../library/gettext.rst:199 +msgid "" +"Translation classes are what actually implement the translation of original " +"source file message strings to translated message strings. The base class " +"used by all translation classes is :class:`NullTranslations`; this provides " +"the basic interface you can use to write your own specialized translation " +"classes. Here are the methods of :class:`!NullTranslations`:" +msgstr "" + +#: ../../library/gettext.rst:208 +msgid "" +"Takes an optional :term:`file object` *fp*, which is ignored by the base " +"class. Initializes \"protected\" instance variables *_info* and *_charset* " +"which are set by derived classes, as well as *_fallback*, which is set " +"through :meth:`add_fallback`. It then calls ``self._parse(fp)`` if *fp* is " +"not ``None``." +msgstr "" + +#: ../../library/gettext.rst:216 +msgid "" +"No-op in the base class, this method takes file object *fp*, and reads the " +"data from the file, initializing its message catalog. If you have an " +"unsupported message catalog file format, you should override this method to " +"parse your format." +msgstr "" + +#: ../../library/gettext.rst:224 +msgid "" +"Add *fallback* as the fallback object for the current translation object. A " +"translation object should consult the fallback if it cannot provide a " +"translation for a given message." +msgstr "" + +#: ../../library/gettext.rst:231 +msgid "" +"If a fallback has been set, forward :meth:`!gettext` to the fallback. " +"Otherwise, return *message*. Overridden in derived classes." +msgstr "" + +#: ../../library/gettext.rst:237 +msgid "" +"If a fallback has been set, forward :meth:`!ngettext` to the fallback. " +"Otherwise, return *singular* if *n* is 1; return *plural* otherwise. " +"Overridden in derived classes." +msgstr "" + +#: ../../library/gettext.rst:244 +msgid "" +"If a fallback has been set, forward :meth:`pgettext` to the fallback. " +"Otherwise, return the translated message. Overridden in derived classes." +msgstr "" + +#: ../../library/gettext.rst:252 +msgid "" +"If a fallback has been set, forward :meth:`npgettext` to the fallback. " +"Otherwise, return the translated message. Overridden in derived classes." +msgstr "" + +#: ../../library/gettext.rst:260 +msgid "" +"Return a dictionary containing the metadata found in the message catalog " +"file." +msgstr "" + +#: ../../library/gettext.rst:266 +msgid "Return the encoding of the message catalog file." +msgstr "" + +#: ../../library/gettext.rst:271 +msgid "" +"This method installs :meth:`.gettext` into the built-in namespace, binding " +"it to ``_``." +msgstr "" + +#: ../../library/gettext.rst:274 +msgid "" +"If the *names* parameter is given, it must be a sequence containing the " +"names of functions you want to install in the builtins namespace in addition " +"to :func:`!_`. Supported names are ``'gettext'``, ``'ngettext'``, " +"``'pgettext'``, and ``'npgettext'``." +msgstr "" + +#: ../../library/gettext.rst:279 +msgid "" +"Note that this is only one way, albeit the most convenient way, to make the :" +"func:`!_` function available to your application. Because it affects the " +"entire application globally, and specifically the built-in namespace, " +"localized modules should never install :func:`!_`. Instead, they should use " +"this code to make :func:`!_` available to their module::" +msgstr "" + +#: ../../library/gettext.rst:285 +msgid "" +"import gettext\n" +"t = gettext.translation('mymodule', ...)\n" +"_ = t.gettext" +msgstr "" +"import gettext\n" +"t = gettext.translation('mymodule', ...)\n" +"_ = t.gettext" + +#: ../../library/gettext.rst:289 +msgid "" +"This puts :func:`!_` only in the module's global namespace and so only " +"affects calls within this module." +msgstr "" + +#: ../../library/gettext.rst:292 +msgid "Added ``'pgettext'`` and ``'npgettext'``." +msgstr "新增 ``'pgettext'`` 與 ``'npgettext'``。" + +#: ../../library/gettext.rst:297 +msgid "The :class:`GNUTranslations` class" +msgstr "" + +#: ../../library/gettext.rst:299 +msgid "" +"The :mod:`!gettext` module provides one additional class derived from :class:" +"`NullTranslations`: :class:`GNUTranslations`. This class overrides :meth:`!" +"_parse` to enable reading GNU :program:`gettext` format :file:`.mo` files in " +"both big-endian and little-endian format." +msgstr "" + +#: ../../library/gettext.rst:304 +msgid "" +":class:`GNUTranslations` parses optional metadata out of the translation " +"catalog. It is convention with GNU :program:`gettext` to include metadata as " +"the translation for the empty string. This metadata is in :rfc:`822`\\ -" +"style ``key: value`` pairs, and should contain the ``Project-Id-Version`` " +"key. If the key ``Content-Type`` is found, then the ``charset`` property is " +"used to initialize the \"protected\" :attr:`!_charset` instance variable, " +"defaulting to ``None`` if not found. If the charset encoding is specified, " +"then all message ids and message strings read from the catalog are converted " +"to Unicode using this encoding, else ASCII is assumed." +msgstr "" + +#: ../../library/gettext.rst:314 +msgid "" +"Since message ids are read as Unicode strings too, all ``*gettext()`` " +"methods will assume message ids as Unicode strings, not byte strings." +msgstr "" + +#: ../../library/gettext.rst:317 +msgid "" +"The entire set of key/value pairs are placed into a dictionary and set as " +"the \"protected\" :attr:`!_info` instance variable." +msgstr "" + +#: ../../library/gettext.rst:320 +msgid "" +"If the :file:`.mo` file's magic number is invalid, the major version number " +"is unexpected, or if other problems occur while reading the file, " +"instantiating a :class:`GNUTranslations` class can raise :exc:`OSError`." +msgstr "" + +#: ../../library/gettext.rst:326 +msgid "" +"The following methods are overridden from the base class implementation:" +msgstr "" + +#: ../../library/gettext.rst:330 +msgid "" +"Look up the *message* id in the catalog and return the corresponding message " +"string, as a Unicode string. If there is no entry in the catalog for the " +"*message* id, and a fallback has been set, the look up is forwarded to the " +"fallback's :meth:`~NullTranslations.gettext` method. Otherwise, the " +"*message* id is returned." +msgstr "" + +#: ../../library/gettext.rst:339 +msgid "" +"Do a plural-forms lookup of a message id. *singular* is used as the message " +"id for purposes of lookup in the catalog, while *n* is used to determine " +"which plural form to use. The returned message string is a Unicode string." +msgstr "" + +#: ../../library/gettext.rst:343 +msgid "" +"If the message id is not found in the catalog, and a fallback is specified, " +"the request is forwarded to the fallback's :meth:`~NullTranslations." +"ngettext` method. Otherwise, when *n* is 1 *singular* is returned, and " +"*plural* is returned in all other cases." +msgstr "" + +#: ../../library/gettext.rst:348 +msgid "Here is an example::" +msgstr "以下是個範例： ::" + +#: ../../library/gettext.rst:350 +msgid "" +"n = len(os.listdir('.'))\n" +"cat = GNUTranslations(somefile)\n" +"message = cat.ngettext(\n" +" 'There is %(num)d file in this directory',\n" +" 'There are %(num)d files in this directory',\n" +" n) % {'num': n}" +msgstr "" +"n = len(os.listdir('.'))\n" +"cat = GNUTranslations(somefile)\n" +"message = cat.ngettext(\n" +" 'There is %(num)d file in this directory',\n" +" 'There are %(num)d files in this directory',\n" +" n) % {'num': n}" + +#: ../../library/gettext.rst:360 +msgid "" +"Look up the *context* and *message* id in the catalog and return the " +"corresponding message string, as a Unicode string. If there is no entry in " +"the catalog for the *message* id and *context*, and a fallback has been set, " +"the look up is forwarded to the fallback's :meth:`pgettext` method. " +"Otherwise, the *message* id is returned." +msgstr "" + +#: ../../library/gettext.rst:371 +msgid "" +"Do a plural-forms lookup of a message id. *singular* is used as the message " +"id for purposes of lookup in the catalog, while *n* is used to determine " +"which plural form to use." +msgstr "" + +#: ../../library/gettext.rst:375 +msgid "" +"If the message id for *context* is not found in the catalog, and a fallback " +"is specified, the request is forwarded to the fallback's :meth:`npgettext` " +"method. Otherwise, when *n* is 1 *singular* is returned, and *plural* is " +"returned in all other cases." +msgstr "" + +#: ../../library/gettext.rst:384 +msgid "Solaris message catalog support" +msgstr "" + +#: ../../library/gettext.rst:386 +msgid "" +"The Solaris operating system defines its own binary :file:`.mo` file format, " +"but since no documentation can be found on this format, it is not supported " +"at this time." +msgstr "" + +#: ../../library/gettext.rst:392 +msgid "The Catalog constructor" +msgstr "" + +#: ../../library/gettext.rst:396 +msgid "" +"GNOME uses a version of the :mod:`gettext` module by James Henstridge, but " +"this version has a slightly different API. Its documented usage was::" +msgstr "" + +#: ../../library/gettext.rst:399 +msgid "" +"import gettext\n" +"cat = gettext.Catalog(domain, localedir)\n" +"_ = cat.gettext\n" +"print(_('hello world'))" +msgstr "" +"import gettext\n" +"cat = gettext.Catalog(domain, localedir)\n" +"_ = cat.gettext\n" +"print(_('hello world'))" + +#: ../../library/gettext.rst:404 +msgid "" +"For compatibility with this older module, the function :func:`!Catalog` is " +"an alias for the :func:`translation` function described above." +msgstr "" + +#: ../../library/gettext.rst:407 +msgid "" +"One difference between this module and Henstridge's: his catalog objects " +"supported access through a mapping API, but this appears to be unused and so " +"is not currently supported." +msgstr "" + +#: ../../library/gettext.rst:414 +msgid "Internationalizing your programs and modules" +msgstr "" + +#: ../../library/gettext.rst:416 +msgid "" +"Internationalization (I18N) refers to the operation by which a program is " +"made aware of multiple languages. Localization (L10N) refers to the " +"adaptation of your program, once internationalized, to the local language " +"and cultural habits. In order to provide multilingual messages for your " +"Python programs, you need to take the following steps:" +msgstr "" + +#: ../../library/gettext.rst:422 +msgid "" +"prepare your program or module by specially marking translatable strings" +msgstr "" + +#: ../../library/gettext.rst:424 +msgid "" +"run a suite of tools over your marked files to generate raw messages catalogs" +msgstr "" + +#: ../../library/gettext.rst:426 +msgid "create language-specific translations of the message catalogs" +msgstr "" + +#: ../../library/gettext.rst:428 +msgid "" +"use the :mod:`gettext` module so that message strings are properly translated" +msgstr "" + +#: ../../library/gettext.rst:430 +msgid "" +"In order to prepare your code for I18N, you need to look at all the strings " +"in your files. Any string that needs to be translated should be marked by " +"wrapping it in ``_('...')`` --- that is, a call to the function :func:`_ " +"`. For example::" +msgstr "" + +#: ../../library/gettext.rst:434 +msgid "" +"filename = 'mylog.txt'\n" +"message = _('writing a log message')\n" +"with open(filename, 'w') as fp:\n" +" fp.write(message)" +msgstr "" +"filename = 'mylog.txt'\n" +"message = _('writing a log message')\n" +"with open(filename, 'w') as fp:\n" +" fp.write(message)" + +#: ../../library/gettext.rst:439 +msgid "" +"In this example, the string ``'writing a log message'`` is marked as a " +"candidate for translation, while the strings ``'mylog.txt'`` and ``'w'`` are " +"not." +msgstr "" + +#: ../../library/gettext.rst:442 +msgid "" +"There are a few tools to extract the strings meant for translation. The " +"original GNU :program:`gettext` only supported C or C++ source code but its " +"extended version :program:`xgettext` scans code written in a number of " +"languages, including Python, to find strings marked as translatable. `Babel " +"`__ is a Python internationalization library that " +"includes a :file:`pybabel` script to extract and compile message catalogs. " +"François Pinard's program called :program:`xpot` does a similar job and is " +"available as part of his `po-utils package `__." +msgstr "" + +#: ../../library/gettext.rst:452 +msgid "" +"(Python also includes pure-Python versions of these programs, called :" +"program:`pygettext.py` and :program:`msgfmt.py`; some Python distributions " +"will install them for you. :program:`pygettext.py` is similar to :program:" +"`xgettext`, but only understands Python source code and cannot handle other " +"programming languages such as C or C++. :program:`pygettext.py` supports a " +"command-line interface similar to :program:`xgettext`; for details on its " +"use, run ``pygettext.py --help``. :program:`msgfmt.py` is binary compatible " +"with GNU :program:`msgfmt`. With these two programs, you may not need the " +"GNU :program:`gettext` package to internationalize your Python applications.)" +msgstr "" + +#: ../../library/gettext.rst:464 +msgid "" +":program:`xgettext`, :program:`pygettext`, and similar tools generate :file:" +"`.po` files that are message catalogs. They are structured human-readable " +"files that contain every marked string in the source code, along with a " +"placeholder for the translated versions of these strings." +msgstr "" + +#: ../../library/gettext.rst:470 +msgid "" +"Copies of these :file:`.po` files are then handed over to the individual " +"human translators who write translations for every supported natural " +"language. They send back the completed language-specific versions as a :" +"file:`.po` file that's compiled into a machine-readable :file:" +"`.mo` binary catalog file using the :program:`msgfmt` program. The :file:`." +"mo` files are used by the :mod:`gettext` module for the actual translation " +"processing at run-time." +msgstr "" + +#: ../../library/gettext.rst:479 +msgid "" +"How you use the :mod:`gettext` module in your code depends on whether you " +"are internationalizing a single module or your entire application. The next " +"two sections will discuss each case." +msgstr "" + +#: ../../library/gettext.rst:485 +msgid "Localizing your module" +msgstr "" + +#: ../../library/gettext.rst:487 +msgid "" +"If you are localizing your module, you must take care not to make global " +"changes, e.g. to the built-in namespace. You should not use the GNU :program:" +"`gettext` API but instead the class-based API." +msgstr "" + +#: ../../library/gettext.rst:491 +msgid "" +"Let's say your module is called \"spam\" and the module's various natural " +"language translation :file:`.mo` files reside in :file:`/usr/share/locale` " +"in GNU :program:`gettext` format. Here's what you would put at the top of " +"your module::" +msgstr "" + +#: ../../library/gettext.rst:496 +msgid "" +"import gettext\n" +"t = gettext.translation('spam', '/usr/share/locale')\n" +"_ = t.gettext" +msgstr "" +"import gettext\n" +"t = gettext.translation('spam', '/usr/share/locale')\n" +"_ = t.gettext" + +#: ../../library/gettext.rst:502 +msgid "Localizing your application" +msgstr "" + +#: ../../library/gettext.rst:504 +msgid "" +"If you are localizing your application, you can install the :func:`!_` " +"function globally into the built-in namespace, usually in the main driver " +"file of your application. This will let all your application-specific files " +"just use ``_('...')`` without having to explicitly install it in each file." +msgstr "" + +#: ../../library/gettext.rst:509 +msgid "" +"In the simple case then, you need only add the following bit of code to the " +"main driver file of your application::" +msgstr "" + +#: ../../library/gettext.rst:512 +msgid "" +"import gettext\n" +"gettext.install('myapplication')" +msgstr "" +"import gettext\n" +"gettext.install('myapplication')" + +#: ../../library/gettext.rst:515 +msgid "" +"If you need to set the locale directory, you can pass it into the :func:" +"`install` function::" +msgstr "" + +#: ../../library/gettext.rst:518 +msgid "" +"import gettext\n" +"gettext.install('myapplication', '/usr/share/locale')" +msgstr "" +"import gettext\n" +"gettext.install('myapplication', '/usr/share/locale')" + +#: ../../library/gettext.rst:523 +msgid "Changing languages on the fly" +msgstr "" + +#: ../../library/gettext.rst:525 +msgid "" +"If your program needs to support many languages at the same time, you may " +"want to create multiple translation instances and then switch between them " +"explicitly, like so::" +msgstr "" + +#: ../../library/gettext.rst:529 +msgid "" +"import gettext\n" +"\n" +"lang1 = gettext.translation('myapplication', languages=['en'])\n" +"lang2 = gettext.translation('myapplication', languages=['fr'])\n" +"lang3 = gettext.translation('myapplication', languages=['de'])\n" +"\n" +"# start by using language1\n" +"lang1.install()\n" +"\n" +"# ... time goes by, user selects language 2\n" +"lang2.install()\n" +"\n" +"# ... more time goes by, user selects language 3\n" +"lang3.install()" +msgstr "" + +#: ../../library/gettext.rst:546 +msgid "Deferred translations" +msgstr "" + +#: ../../library/gettext.rst:548 +msgid "" +"In most coding situations, strings are translated where they are coded. " +"Occasionally however, you need to mark strings for translation, but defer " +"actual translation until later. A classic example is::" +msgstr "" + +#: ../../library/gettext.rst:552 +msgid "" +"animals = ['mollusk',\n" +" 'albatross',\n" +" 'rat',\n" +" 'penguin',\n" +" 'python', ]\n" +"# ...\n" +"for a in animals:\n" +" print(a)" +msgstr "" +"animals = ['mollusk',\n" +" 'albatross',\n" +" 'rat',\n" +" 'penguin',\n" +" 'python', ]\n" +"# ...\n" +"for a in animals:\n" +" print(a)" + +#: ../../library/gettext.rst:561 +msgid "" +"Here, you want to mark the strings in the ``animals`` list as being " +"translatable, but you don't actually want to translate them until they are " +"printed." +msgstr "" + +#: ../../library/gettext.rst:565 +msgid "Here is one way you can handle this situation::" +msgstr "" + +#: ../../library/gettext.rst:567 +msgid "" +"def _(message): return message\n" +"\n" +"animals = [_('mollusk'),\n" +" _('albatross'),\n" +" _('rat'),\n" +" _('penguin'),\n" +" _('python'), ]\n" +"\n" +"del _\n" +"\n" +"# ...\n" +"for a in animals:\n" +" print(_(a))" +msgstr "" +"def _(message): return message\n" +"\n" +"animals = [_('mollusk'),\n" +" _('albatross'),\n" +" _('rat'),\n" +" _('penguin'),\n" +" _('python'), ]\n" +"\n" +"del _\n" +"\n" +"# ...\n" +"for a in animals:\n" +" print(_(a))" + +#: ../../library/gettext.rst:581 +msgid "" +"This works because the dummy definition of :func:`!_` simply returns the " +"string unchanged. And this dummy definition will temporarily override any " +"definition of :func:`!_` in the built-in namespace (until the :keyword:`del` " +"command). Take care, though if you have a previous definition of :func:`!_` " +"in the local namespace." +msgstr "" + +#: ../../library/gettext.rst:587 +msgid "" +"Note that the second use of :func:`!_` will not identify \"a\" as being " +"translatable to the :program:`gettext` program, because the parameter is not " +"a string literal." +msgstr "" + +#: ../../library/gettext.rst:591 +msgid "Another way to handle this is with the following example::" +msgstr "" + +#: ../../library/gettext.rst:593 +msgid "" +"def N_(message): return message\n" +"\n" +"animals = [N_('mollusk'),\n" +" N_('albatross'),\n" +" N_('rat'),\n" +" N_('penguin'),\n" +" N_('python'), ]\n" +"\n" +"# ...\n" +"for a in animals:\n" +" print(_(a))" +msgstr "" +"def N_(message): return message\n" +"\n" +"animals = [N_('mollusk'),\n" +" N_('albatross'),\n" +" N_('rat'),\n" +" N_('penguin'),\n" +" N_('python'), ]\n" +"\n" +"# ...\n" +"for a in animals:\n" +" print(_(a))" + +#: ../../library/gettext.rst:605 +msgid "" +"In this case, you are marking translatable strings with the function :func:`!" +"N_`, which won't conflict with any definition of :func:`!_`. However, you " +"will need to teach your message extraction program to look for translatable " +"strings marked with :func:`!N_`. :program:`xgettext`, :program:`pygettext`, " +"``pybabel extract``, and :program:`xpot` all support this through the use of " +"the :option:`!-k` command-line switch. The choice of :func:`!N_` here is " +"totally arbitrary; it could have just as easily been :func:`!" +"MarkThisStringForTranslation`." +msgstr "" + +#: ../../library/gettext.rst:616 +msgid "Acknowledgements" +msgstr "致謝" + +#: ../../library/gettext.rst:618 +msgid "" +"The following people contributed code, feedback, design suggestions, " +"previous implementations, and valuable experience to the creation of this " +"module:" +msgstr "" + +#: ../../library/gettext.rst:621 +msgid "Peter Funk" +msgstr "Peter Funk" + +#: ../../library/gettext.rst:623 +msgid "James Henstridge" +msgstr "James Henstridge" + +#: ../../library/gettext.rst:625 +msgid "Juan David Ibáñez Palomar" +msgstr "Juan David Ibáñez Palomar" + +#: ../../library/gettext.rst:627 +msgid "Marc-André Lemburg" +msgstr "Marc-André Lemburg" + +#: ../../library/gettext.rst:629 +msgid "Martin von Löwis" +msgstr "Martin von Löwis" + +#: ../../library/gettext.rst:631 +msgid "François Pinard" +msgstr "François Pinard" + +#: ../../library/gettext.rst:633 +msgid "Barry Warsaw" +msgstr "Barry Warsaw" + +#: ../../library/gettext.rst:635 +msgid "Gustavo Niemeyer" +msgstr "Gustavo Niemeyer" + +#: ../../library/gettext.rst:638 +msgid "Footnotes" +msgstr "註解" + +#: ../../library/gettext.rst:639 +msgid "" +"The default locale directory is system dependent; for example, on Red Hat " +"Linux it is :file:`/usr/share/locale`, but on Solaris it is :file:`/usr/lib/" +"locale`. The :mod:`!gettext` module does not try to support these system " +"dependent defaults; instead its default is :file:`{sys.base_prefix}/share/" +"locale` (see :data:`sys.base_prefix`). For this reason, it is always best to " +"call :func:`bindtextdomain` with an explicit absolute path at the start of " +"your application." +msgstr "" + +#: ../../library/gettext.rst:647 +msgid "See the footnote for :func:`bindtextdomain` above." +msgstr "請見上方 :func:`bindtextdomain` 之註解。" + +#: ../../library/gettext.rst:56 +msgid "_ (underscore)" +msgstr "_ （底線）" + +#: ../../library/gettext.rst:56 +msgid "gettext" +msgstr "gettext" + +#: ../../library/gettext.rst:394 +msgid "GNOME" +msgstr "GNOME" diff --git a/library/glob.po b/library/glob.po index b2f5820851..bc121e11cf 100644 --- a/library/glob.po +++ b/library/glob.po @@ -1,338 +1,338 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Matt Wang , 2023 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-10-21 00:14+0000\n" -"PO-Revision-Date: 2023-01-24 01:21+0800\n" -"Last-Translator: Matt Wang \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" -"X-Generator: Poedit 3.2.2\n" - -#: ../../library/glob.rst:2 -msgid ":mod:`!glob` --- Unix style pathname pattern expansion" -msgstr ":mod:`!glob` --- Unix 風格的路徑名稱模式擴展" - -#: ../../library/glob.rst:7 -msgid "**Source code:** :source:`Lib/glob.py`" -msgstr "**原始碼：**\\ :source:`Lib/glob.py`" - -#: ../../library/glob.rst:21 -msgid "" -"The :mod:`!glob` module finds pathnames using pattern matching rules similar " -"to the Unix shell. No tilde expansion is done, but ``*``, ``?``, and " -"character ranges expressed with ``[]`` will be correctly matched. This is " -"done by using the :func:`os.scandir` and :func:`fnmatch.fnmatch` functions " -"in concert, and not by actually invoking a subshell." -msgstr "" -":mod:`!glob` 模組使用類似於 Unix shell 的模式匹配規則來尋找路徑名稱。不會進" -"行波浪號擴展 (tilde expansion) ，但 ``*``、``?`` 和使用 ``[]`` 表達的字元範圍將會被正確匹配。這" -"是透過結合使用 :func:`os.scandir` 和 :func:`fnmatch.fnmatch` 函式來完成的，而沒有實際呼叫 subshell。" - -#: ../../library/glob.rst:29 -msgid "" -"The pathnames are returned in no particular order. If you need a specific " -"order, sort the results." -msgstr "" -"路徑名稱不會以特定順序回傳。如果你需要特定的順序，請對結果進行排序。" - -#: ../../library/glob.rst:32 -msgid "" -"Files beginning with a dot (``.``) can only be matched by patterns that also " -"start with a dot, unlike :func:`fnmatch.fnmatch` or :func:`pathlib.Path." -"glob`. For tilde and shell variable expansion, use :func:`os.path." -"expanduser` and :func:`os.path.expandvars`." -msgstr "" -"以點 (``.``) 開頭的檔案只能與同樣以點開頭的模式匹配，這與 :func:" -"`fnmatch.fnmatch` 或 :func:`pathlib.Path.glob` 不同。對於波浪號和 shell 變" -"數擴展，請使用 :func:`os.path.expanduser` 和 :func:`os.path.expandvars`。" - -#: ../../library/glob.rst:38 -msgid "" -"For a literal match, wrap the meta-characters in brackets. For example, " -"``'[?]'`` matches the character ``'?'``." -msgstr "" -"對於文本 (literal) 匹配，將元字元 (meta-character) 括在方括號中。例如，" -"``'[?]'`` 會匹配 ``'?'`` 字元。" - -#: ../../library/glob.rst:41 -msgid "The :mod:`!glob` module defines the following functions:" -msgstr ":mod:`!glob` 模組定義了以下函式：" - -#: ../../library/glob.rst:47 -msgid "" -"Return a possibly empty list of path names that match *pathname*, which must " -"be a string containing a path specification. *pathname* can be either " -"absolute (like :file:`/usr/src/Python-1.5/Makefile`) or relative (like :file:" -"`../../Tools/\\*/\\*.gif`), and can contain shell-style wildcards. Broken " -"symlinks are included in the results (as in the shell). Whether or not the " -"results are sorted depends on the file system. If a file that satisfies " -"conditions is removed or added during the call of this function, whether a " -"path name for that file will be included is unspecified." -msgstr "" -"回傳與 *pathname* 匹配、可能為空的路徑名稱 list，它必須是包含路徑規範的字" -"串。 *pathname* 可以是絕對的（如 :file:`/usr/src/Python-1.5/Makefile`）或相對" -"的（如 :file:`../../Tools/\\*/\\*.gif`），並且可以包含 shell 樣式的通用字元 " -"(wildcard)。已損壞的符號連接也會（如同在 shell）被包含在結果中。結果是否排序" -"取決於檔案系統 (file system)。如果在呼叫此函式期間刪除或新增滿足條件的檔案，" -"則結果不一定會包含該檔案的路徑名稱。" - -#: ../../library/glob.rst:56 -msgid "" -"If *root_dir* is not ``None``, it should be a :term:`path-like object` " -"specifying the root directory for searching. It has the same effect on :" -"func:`!glob` as changing the current directory before calling it. If " -"*pathname* is relative, the result will contain paths relative to *root_dir*." -msgstr "" -"如果 *root_dir* 不是 ``None``，它應該是一個指定搜尋根目錄的 :term:`path-like " -"object`。它在呼叫它之前更改目前目錄的影響與 :func:`!glob` 相同。如果 " -"*pathname* 是相對的，結果將包含相對於 *root_dir* 的路徑。" - -#: ../../library/glob.rst:62 -msgid "" -"This function can support :ref:`paths relative to directory descriptors " -"` with the *dir_fd* parameter." -msgstr "" -"此函式可以支援以 *dir_fd* 參數使用\\ :ref:`相對目錄描述器的路徑 `。" - -#: ../../library/glob.rst:68 -msgid "" -"If *recursive* is true, the pattern \"``**``\" will match any files and zero " -"or more directories, subdirectories and symbolic links to directories. If " -"the pattern is followed by an :data:`os.sep` or :data:`os.altsep` then files " -"will not match." -msgstr "" -"如果 *recursive* 為真，模式 \"``**``\" 將匹配任何檔案、零個或多個目錄、子目錄" -"和目錄的符號連結。如果模式後面有 :data:`os.sep` 或 :data:`os.altsep` 那麼檔案" -"將不會被匹配。" - -#: ../../library/glob.rst:73 -msgid "" -"If *include_hidden* is true, \"``**``\" pattern will match hidden " -"directories." -msgstr "如果 *include_hidden* 為真，\"``**``\" 模式將匹配被隱藏的目錄。" - -#: ../../library/glob.rst:75 ../../library/glob.rst:102 -msgid "" -"Raises an :ref:`auditing event ` ``glob.glob`` with arguments " -"``pathname``, ``recursive``." -msgstr "" -"引發一個附帶引數 ``pathname``、``recursive`` 的\\ :ref:`稽核事件 ` " -"``glob.glob``。" - -#: ../../library/glob.rst:76 ../../library/glob.rst:103 -msgid "" -"Raises an :ref:`auditing event ` ``glob.glob/2`` with arguments " -"``pathname``, ``recursive``, ``root_dir``, ``dir_fd``." -msgstr "" -"引發一個附帶引數 ``pathname``、``recursive``、``root_dir``、``dir_fd`` 的\\ :" -"ref:`稽核事件 ` ``glob.glob/2``。" - -#: ../../library/glob.rst:79 -msgid "" -"Using the \"``**``\" pattern in large directory trees may consume an " -"inordinate amount of time." -msgstr "在大型目錄樹中使用 \"``**``\" 模式可能會消耗過多的時間。" - -#: ../../library/glob.rst:83 ../../library/glob.rst:106 -msgid "" -"This function may return duplicate path names if *pathname* contains " -"multiple \"``**``\" patterns and *recursive* is true." -msgstr "" - -#: ../../library/glob.rst:86 ../../library/glob.rst:109 -msgid "Support for recursive globs using \"``**``\"." -msgstr "支援以 \"``**``\" 使用遞迴 glob。" - -#: ../../library/glob.rst:89 ../../library/glob.rst:112 -msgid "Added the *root_dir* and *dir_fd* parameters." -msgstr "新增 *root_dir* 與 *dir_fd* 參數。" - -#: ../../library/glob.rst:92 ../../library/glob.rst:115 -msgid "Added the *include_hidden* parameter." -msgstr "新增 *include_hidden* 參數。" - -#: ../../library/glob.rst:99 -msgid "" -"Return an :term:`iterator` which yields the same values as :func:`glob` " -"without actually storing them all simultaneously." -msgstr "" -"回傳一個會產生與 :func:`glob` 相同的值的 :term:`iterator` ，而不是同時儲存全" -"部的值。" - -#: ../../library/glob.rst:121 -msgid "" -"Escape all special characters (``'?'``, ``'*'`` and ``'['``). This is useful " -"if you want to match an arbitrary literal string that may have special " -"characters in it. Special characters in drive/UNC sharepoints are not " -"escaped, e.g. on Windows ``escape('//?/c:/Quo vadis?.txt')`` returns ``'//?/" -"c:/Quo vadis[?].txt'``." -msgstr "" -"跳脫 (escape) 所有特殊字元（``'?'``、``'*'`` 和 ``'['``）。如果你想匹配其中可" -"能包含特殊字元的任意文本字串，這將會很有用。驅動器 (drive)/UNC 共享點 " -"(sharepoints) 中的特殊字元不會被跳脫，例如在 Windows 上，``escape('//?/c:/" -"Quo vadis?.txt')`` 會回傳 ``'//?/c:/Quo vadis[?].txt'``。" - -#: ../../library/glob.rst:132 -msgid "" -"Convert the given path specification to a regular expression for use with :" -"func:`re.match`. The path specification can contain shell-style wildcards." -msgstr "" - -#: ../../library/glob.rst:135 -msgid "For example:" -msgstr "舉例來說：" - -#: ../../library/glob.rst:146 -msgid "" -"Path separators and segments are meaningful to this function, unlike :func:" -"`fnmatch.translate`. By default wildcards do not match path separators, and " -"``*`` pattern segments match precisely one path segment." -msgstr "" - -#: ../../library/glob.rst:150 -msgid "" -"If *recursive* is true, the pattern segment \"``**``\" will match any number " -"of path segments." -msgstr "" - -#: ../../library/glob.rst:153 -msgid "" -"If *include_hidden* is true, wildcards can match path segments that start " -"with a dot (``.``)." -msgstr "" - -#: ../../library/glob.rst:156 -msgid "" -"A sequence of path separators may be supplied to the *seps* argument. If not " -"given, :data:`os.sep` and :data:`~os.altsep` (if available) are used." -msgstr "" - -#: ../../library/glob.rst:161 -msgid "" -":meth:`pathlib.PurePath.full_match` and :meth:`pathlib.Path.glob` methods, " -"which call this function to implement pattern matching and globbing." -msgstr "" - -#: ../../library/glob.rst:169 -msgid "Examples" -msgstr "範例" - -#: ../../library/glob.rst:171 -msgid "" -"Consider a directory containing the following files: :file:`1.gif`, :file:`2." -"txt`, :file:`card.gif` and a subdirectory :file:`sub` which contains only " -"the file :file:`3.txt`. :func:`glob` will produce the following results. " -"Notice how any leading components of the path are preserved. ::" -msgstr "" -"例如，在一個包含以下檔案的目錄：:file:`1.gif`、:file:`2.txt`、:file:`card." -"gif`，和一個僅包含 :file:`3.txt` 檔案的子目錄 :file:`sub`，:func:`glob` 將產" -"生以下結果。請注意路徑的任何前導部分是如何保留的。 ::" - -#: ../../library/glob.rst:177 -msgid "" -">>> import glob\n" -">>> glob.glob('./[0-9].*')\n" -"['./1.gif', './2.txt']\n" -">>> glob.glob('*.gif')\n" -"['1.gif', 'card.gif']\n" -">>> glob.glob('?.gif')\n" -"['1.gif']\n" -">>> glob.glob('**/*.txt', recursive=True)\n" -"['2.txt', 'sub/3.txt']\n" -">>> glob.glob('./**/', recursive=True)\n" -"['./', './sub/']" -msgstr "" -">>> import glob\n" -">>> glob.glob('./[0-9].*')\n" -"['./1.gif', './2.txt']\n" -">>> glob.glob('*.gif')\n" -"['1.gif', 'card.gif']\n" -">>> glob.glob('?.gif')\n" -"['1.gif']\n" -">>> glob.glob('**/*.txt', recursive=True)\n" -"['2.txt', 'sub/3.txt']\n" -">>> glob.glob('./**/', recursive=True)\n" -"['./', './sub/']" - -#: ../../library/glob.rst:189 -msgid "" -"If the directory contains files starting with ``.`` they won't be matched by " -"default. For example, consider a directory containing :file:`card.gif` and :" -"file:`.card.gif`::" -msgstr "" -"如果目錄包含以 ``.`` 開頭的檔案，則預設情況下不會去匹配到它們。例如，一個包" -"含 :file:`card.gif` 和 :file:`.card.gif` 的目錄： ::" - -#: ../../library/glob.rst:193 -msgid "" -">>> import glob\n" -">>> glob.glob('*.gif')\n" -"['card.gif']\n" -">>> glob.glob('.c*')\n" -"['.card.gif']" -msgstr "" -">>> import glob\n" -">>> glob.glob('*.gif')\n" -"['card.gif']\n" -">>> glob.glob('.c*')\n" -"['.card.gif']" - -#: ../../library/glob.rst:200 -msgid "" -"The :mod:`fnmatch` module offers shell-style filename (not path) expansion." -msgstr ":mod:`fnmatch` 模組提供了 shell 風格檔案名（不是路徑）的擴展" - -#: ../../library/glob.rst:203 -msgid "The :mod:`pathlib` module offers high-level path objects." -msgstr ":mod:`pathlib` 模組提供高階路徑物件。" - -#: ../../library/glob.rst:9 -msgid "filenames" -msgstr "filenames（檔案名稱）" - -#: ../../library/glob.rst:9 -msgid "pathname expansion" -msgstr "pathname expansion（路徑名稱展開）" - -#: ../../library/glob.rst:13 -msgid "* (asterisk)" -msgstr "* （星號）" - -#: ../../library/glob.rst:13 ../../library/glob.rst:65 -msgid "in glob-style wildcards" -msgstr "於 glob 風格的萬用字元中" - -#: ../../library/glob.rst:13 -msgid "? (question mark)" -msgstr "? （問號）" - -#: ../../library/glob.rst:13 -msgid "[] (square brackets)" -msgstr "[] （方括號）" - -#: ../../library/glob.rst:13 -msgid "! (exclamation)" -msgstr "! （驚嘆號）" - -#: ../../library/glob.rst:13 -msgid "- (minus)" -msgstr "- （減號）" - -#: ../../library/glob.rst:13 -msgid ". (dot)" -msgstr ". （點）" - -#: ../../library/glob.rst:65 -msgid "**" -msgstr "**" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Matt Wang , 2023 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-10-21 00:14+0000\n" +"PO-Revision-Date: 2023-01-24 01:21+0800\n" +"Last-Translator: Matt Wang \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" +"X-Generator: Poedit 3.2.2\n" + +#: ../../library/glob.rst:2 +msgid ":mod:`!glob` --- Unix style pathname pattern expansion" +msgstr ":mod:`!glob` --- Unix 風格的路徑名稱模式擴展" + +#: ../../library/glob.rst:7 +msgid "**Source code:** :source:`Lib/glob.py`" +msgstr "**原始碼：**\\ :source:`Lib/glob.py`" + +#: ../../library/glob.rst:21 +msgid "" +"The :mod:`!glob` module finds pathnames using pattern matching rules similar " +"to the Unix shell. No tilde expansion is done, but ``*``, ``?``, and " +"character ranges expressed with ``[]`` will be correctly matched. This is " +"done by using the :func:`os.scandir` and :func:`fnmatch.fnmatch` functions " +"in concert, and not by actually invoking a subshell." +msgstr "" +":mod:`!glob` 模組使用類似於 Unix shell 的模式匹配規則來尋找路徑名稱。不會進" +"行波浪號擴展 (tilde expansion) ，但 ``*``、``?`` 和使用 ``[]`` 表達的字元範圍將會被正確匹配。這" +"是透過結合使用 :func:`os.scandir` 和 :func:`fnmatch.fnmatch` 函式來完成的，而沒有實際呼叫 subshell。" + +#: ../../library/glob.rst:29 +msgid "" +"The pathnames are returned in no particular order. If you need a specific " +"order, sort the results." +msgstr "" +"路徑名稱不會以特定順序回傳。如果你需要特定的順序，請對結果進行排序。" + +#: ../../library/glob.rst:32 +msgid "" +"Files beginning with a dot (``.``) can only be matched by patterns that also " +"start with a dot, unlike :func:`fnmatch.fnmatch` or :func:`pathlib.Path." +"glob`. For tilde and shell variable expansion, use :func:`os.path." +"expanduser` and :func:`os.path.expandvars`." +msgstr "" +"以點 (``.``) 開頭的檔案只能與同樣以點開頭的模式匹配，這與 :func:" +"`fnmatch.fnmatch` 或 :func:`pathlib.Path.glob` 不同。對於波浪號和 shell 變" +"數擴展，請使用 :func:`os.path.expanduser` 和 :func:`os.path.expandvars`。" + +#: ../../library/glob.rst:38 +msgid "" +"For a literal match, wrap the meta-characters in brackets. For example, " +"``'[?]'`` matches the character ``'?'``." +msgstr "" +"對於文本 (literal) 匹配，將元字元 (meta-character) 括在方括號中。例如，" +"``'[?]'`` 會匹配 ``'?'`` 字元。" + +#: ../../library/glob.rst:41 +msgid "The :mod:`!glob` module defines the following functions:" +msgstr ":mod:`!glob` 模組定義了以下函式：" + +#: ../../library/glob.rst:47 +msgid "" +"Return a possibly empty list of path names that match *pathname*, which must " +"be a string containing a path specification. *pathname* can be either " +"absolute (like :file:`/usr/src/Python-1.5/Makefile`) or relative (like :file:" +"`../../Tools/\\*/\\*.gif`), and can contain shell-style wildcards. Broken " +"symlinks are included in the results (as in the shell). Whether or not the " +"results are sorted depends on the file system. If a file that satisfies " +"conditions is removed or added during the call of this function, whether a " +"path name for that file will be included is unspecified." +msgstr "" +"回傳與 *pathname* 匹配、可能為空的路徑名稱 list，它必須是包含路徑規範的字" +"串。 *pathname* 可以是絕對的（如 :file:`/usr/src/Python-1.5/Makefile`）或相對" +"的（如 :file:`../../Tools/\\*/\\*.gif`），並且可以包含 shell 樣式的通用字元 " +"(wildcard)。已損壞的符號連接也會（如同在 shell）被包含在結果中。結果是否排序" +"取決於檔案系統 (file system)。如果在呼叫此函式期間刪除或新增滿足條件的檔案，" +"則結果不一定會包含該檔案的路徑名稱。" + +#: ../../library/glob.rst:56 +msgid "" +"If *root_dir* is not ``None``, it should be a :term:`path-like object` " +"specifying the root directory for searching. It has the same effect on :" +"func:`!glob` as changing the current directory before calling it. If " +"*pathname* is relative, the result will contain paths relative to *root_dir*." +msgstr "" +"如果 *root_dir* 不是 ``None``，它應該是一個指定搜尋根目錄的 :term:`path-like " +"object`。它在呼叫它之前更改目前目錄的影響與 :func:`!glob` 相同。如果 " +"*pathname* 是相對的，結果將包含相對於 *root_dir* 的路徑。" + +#: ../../library/glob.rst:62 +msgid "" +"This function can support :ref:`paths relative to directory descriptors " +"` with the *dir_fd* parameter." +msgstr "" +"此函式可以支援以 *dir_fd* 參數使用\\ :ref:`相對目錄描述器的路徑 `。" + +#: ../../library/glob.rst:68 +msgid "" +"If *recursive* is true, the pattern \"``**``\" will match any files and zero " +"or more directories, subdirectories and symbolic links to directories. If " +"the pattern is followed by an :data:`os.sep` or :data:`os.altsep` then files " +"will not match." +msgstr "" +"如果 *recursive* 為真，模式 \"``**``\" 將匹配任何檔案、零個或多個目錄、子目錄" +"和目錄的符號連結。如果模式後面有 :data:`os.sep` 或 :data:`os.altsep` 那麼檔案" +"將不會被匹配。" + +#: ../../library/glob.rst:73 +msgid "" +"If *include_hidden* is true, \"``**``\" pattern will match hidden " +"directories." +msgstr "如果 *include_hidden* 為真，\"``**``\" 模式將匹配被隱藏的目錄。" + +#: ../../library/glob.rst:75 ../../library/glob.rst:102 +msgid "" +"Raises an :ref:`auditing event ` ``glob.glob`` with arguments " +"``pathname``, ``recursive``." +msgstr "" +"引發一個附帶引數 ``pathname``、``recursive`` 的\\ :ref:`稽核事件 ` " +"``glob.glob``。" + +#: ../../library/glob.rst:76 ../../library/glob.rst:103 +msgid "" +"Raises an :ref:`auditing event ` ``glob.glob/2`` with arguments " +"``pathname``, ``recursive``, ``root_dir``, ``dir_fd``." +msgstr "" +"引發一個附帶引數 ``pathname``、``recursive``、``root_dir``、``dir_fd`` 的\\ :" +"ref:`稽核事件 ` ``glob.glob/2``。" + +#: ../../library/glob.rst:79 +msgid "" +"Using the \"``**``\" pattern in large directory trees may consume an " +"inordinate amount of time." +msgstr "在大型目錄樹中使用 \"``**``\" 模式可能會消耗過多的時間。" + +#: ../../library/glob.rst:83 ../../library/glob.rst:106 +msgid "" +"This function may return duplicate path names if *pathname* contains " +"multiple \"``**``\" patterns and *recursive* is true." +msgstr "" + +#: ../../library/glob.rst:86 ../../library/glob.rst:109 +msgid "Support for recursive globs using \"``**``\"." +msgstr "支援以 \"``**``\" 使用遞迴 glob。" + +#: ../../library/glob.rst:89 ../../library/glob.rst:112 +msgid "Added the *root_dir* and *dir_fd* parameters." +msgstr "新增 *root_dir* 與 *dir_fd* 參數。" + +#: ../../library/glob.rst:92 ../../library/glob.rst:115 +msgid "Added the *include_hidden* parameter." +msgstr "新增 *include_hidden* 參數。" + +#: ../../library/glob.rst:99 +msgid "" +"Return an :term:`iterator` which yields the same values as :func:`glob` " +"without actually storing them all simultaneously." +msgstr "" +"回傳一個會產生與 :func:`glob` 相同的值的 :term:`iterator` ，而不是同時儲存全" +"部的值。" + +#: ../../library/glob.rst:121 +msgid "" +"Escape all special characters (``'?'``, ``'*'`` and ``'['``). This is useful " +"if you want to match an arbitrary literal string that may have special " +"characters in it. Special characters in drive/UNC sharepoints are not " +"escaped, e.g. on Windows ``escape('//?/c:/Quo vadis?.txt')`` returns ``'//?/" +"c:/Quo vadis[?].txt'``." +msgstr "" +"跳脫 (escape) 所有特殊字元（``'?'``、``'*'`` 和 ``'['``）。如果你想匹配其中可" +"能包含特殊字元的任意文本字串，這將會很有用。驅動器 (drive)/UNC 共享點 " +"(sharepoints) 中的特殊字元不會被跳脫，例如在 Windows 上，``escape('//?/c:/" +"Quo vadis?.txt')`` 會回傳 ``'//?/c:/Quo vadis[?].txt'``。" + +#: ../../library/glob.rst:132 +msgid "" +"Convert the given path specification to a regular expression for use with :" +"func:`re.match`. The path specification can contain shell-style wildcards." +msgstr "" + +#: ../../library/glob.rst:135 +msgid "For example:" +msgstr "舉例來說：" + +#: ../../library/glob.rst:146 +msgid "" +"Path separators and segments are meaningful to this function, unlike :func:" +"`fnmatch.translate`. By default wildcards do not match path separators, and " +"``*`` pattern segments match precisely one path segment." +msgstr "" + +#: ../../library/glob.rst:150 +msgid "" +"If *recursive* is true, the pattern segment \"``**``\" will match any number " +"of path segments." +msgstr "" + +#: ../../library/glob.rst:153 +msgid "" +"If *include_hidden* is true, wildcards can match path segments that start " +"with a dot (``.``)." +msgstr "" + +#: ../../library/glob.rst:156 +msgid "" +"A sequence of path separators may be supplied to the *seps* argument. If not " +"given, :data:`os.sep` and :data:`~os.altsep` (if available) are used." +msgstr "" + +#: ../../library/glob.rst:161 +msgid "" +":meth:`pathlib.PurePath.full_match` and :meth:`pathlib.Path.glob` methods, " +"which call this function to implement pattern matching and globbing." +msgstr "" + +#: ../../library/glob.rst:169 +msgid "Examples" +msgstr "範例" + +#: ../../library/glob.rst:171 +msgid "" +"Consider a directory containing the following files: :file:`1.gif`, :file:`2." +"txt`, :file:`card.gif` and a subdirectory :file:`sub` which contains only " +"the file :file:`3.txt`. :func:`glob` will produce the following results. " +"Notice how any leading components of the path are preserved. ::" +msgstr "" +"例如，在一個包含以下檔案的目錄：:file:`1.gif`、:file:`2.txt`、:file:`card." +"gif`，和一個僅包含 :file:`3.txt` 檔案的子目錄 :file:`sub`，:func:`glob` 將產" +"生以下結果。請注意路徑的任何前導部分是如何保留的。 ::" + +#: ../../library/glob.rst:177 +msgid "" +">>> import glob\n" +">>> glob.glob('./[0-9].*')\n" +"['./1.gif', './2.txt']\n" +">>> glob.glob('*.gif')\n" +"['1.gif', 'card.gif']\n" +">>> glob.glob('?.gif')\n" +"['1.gif']\n" +">>> glob.glob('**/*.txt', recursive=True)\n" +"['2.txt', 'sub/3.txt']\n" +">>> glob.glob('./**/', recursive=True)\n" +"['./', './sub/']" +msgstr "" +">>> import glob\n" +">>> glob.glob('./[0-9].*')\n" +"['./1.gif', './2.txt']\n" +">>> glob.glob('*.gif')\n" +"['1.gif', 'card.gif']\n" +">>> glob.glob('?.gif')\n" +"['1.gif']\n" +">>> glob.glob('**/*.txt', recursive=True)\n" +"['2.txt', 'sub/3.txt']\n" +">>> glob.glob('./**/', recursive=True)\n" +"['./', './sub/']" + +#: ../../library/glob.rst:189 +msgid "" +"If the directory contains files starting with ``.`` they won't be matched by " +"default. For example, consider a directory containing :file:`card.gif` and :" +"file:`.card.gif`::" +msgstr "" +"如果目錄包含以 ``.`` 開頭的檔案，則預設情況下不會去匹配到它們。例如，一個包" +"含 :file:`card.gif` 和 :file:`.card.gif` 的目錄： ::" + +#: ../../library/glob.rst:193 +msgid "" +">>> import glob\n" +">>> glob.glob('*.gif')\n" +"['card.gif']\n" +">>> glob.glob('.c*')\n" +"['.card.gif']" +msgstr "" +">>> import glob\n" +">>> glob.glob('*.gif')\n" +"['card.gif']\n" +">>> glob.glob('.c*')\n" +"['.card.gif']" + +#: ../../library/glob.rst:200 +msgid "" +"The :mod:`fnmatch` module offers shell-style filename (not path) expansion." +msgstr ":mod:`fnmatch` 模組提供了 shell 風格檔案名（不是路徑）的擴展" + +#: ../../library/glob.rst:203 +msgid "The :mod:`pathlib` module offers high-level path objects." +msgstr ":mod:`pathlib` 模組提供高階路徑物件。" + +#: ../../library/glob.rst:9 +msgid "filenames" +msgstr "filenames（檔案名稱）" + +#: ../../library/glob.rst:9 +msgid "pathname expansion" +msgstr "pathname expansion（路徑名稱展開）" + +#: ../../library/glob.rst:13 +msgid "* (asterisk)" +msgstr "* （星號）" + +#: ../../library/glob.rst:13 ../../library/glob.rst:65 +msgid "in glob-style wildcards" +msgstr "於 glob 風格的萬用字元中" + +#: ../../library/glob.rst:13 +msgid "? (question mark)" +msgstr "? （問號）" + +#: ../../library/glob.rst:13 +msgid "[] (square brackets)" +msgstr "[] （方括號）" + +#: ../../library/glob.rst:13 +msgid "! (exclamation)" +msgstr "! （驚嘆號）" + +#: ../../library/glob.rst:13 +msgid "- (minus)" +msgstr "- （減號）" + +#: ../../library/glob.rst:13 +msgid ". (dot)" +msgstr ". （點）" + +#: ../../library/glob.rst:65 +msgid "**" +msgstr "**" diff --git a/library/graphlib.po b/library/graphlib.po index 25e220b4df..8fc277faf3 100644 --- a/library/graphlib.po +++ b/library/graphlib.po @@ -1,400 +1,400 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Matt Wang , 2023 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-08 15:25+0800\n" -"PO-Revision-Date: 2023-01-04 16:35+0800\n" -"Last-Translator: Matt Wang \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" -"X-Generator: Poedit 3.2.2\n" - -#: ../../library/graphlib.rst:2 -msgid "" -":mod:`!graphlib` --- Functionality to operate with graph-like structures" -msgstr ":mod:`!graphlib` —-- 使用類圖 (graph-like) 結構進行操作的功能" - -#: ../../library/graphlib.rst:8 -msgid "**Source code:** :source:`Lib/graphlib.py`" -msgstr "**原始碼：**\\ :source:`Lib/graphlib.py`" - -#: ../../library/graphlib.rst:20 -msgid "" -"Provides functionality to topologically sort a graph of :term:`hashable` " -"nodes." -msgstr "" -"提供對包含\\ :term:`可雜湊 (hashable) ` 節點之圖 (graph) 進行拓撲排" -"序 (topologically sort) 的功能。" - -#: ../../library/graphlib.rst:22 -msgid "" -"A topological order is a linear ordering of the vertices in a graph such " -"that for every directed edge u -> v from vertex u to vertex v, vertex u " -"comes before vertex v in the ordering. For instance, the vertices of the " -"graph may represent tasks to be performed, and the edges may represent " -"constraints that one task must be performed before another; in this example, " -"a topological ordering is just a valid sequence for the tasks. A complete " -"topological ordering is possible if and only if the graph has no directed " -"cycles, that is, if it is a directed acyclic graph." -msgstr "" -"拓撲排序是圖中頂點 (vertex) 的線性排序，使得對於從頂點 u 到頂點 v 的每條有向" -"邊 (directed edge) u -> v，頂點 u 在排序中會位於頂點 v 之前。例如，圖的頂點可" -"能代表要執行的任務，而邊可能代表一個任務必須在另一個任務之前執行的限制；在此" -"範例中，拓撲排序只是任務的一種有效序列。若且唯若 (if and only if) 圖沒有有向" -"環 (directed cycle) 時，即如果它是個有向無環圖 (directed acyclic graph)，則完" -"整的拓撲排序才是可行的。" - -#: ../../library/graphlib.rst:31 -msgid "" -"If the optional *graph* argument is provided it must be a dictionary " -"representing a directed acyclic graph where the keys are nodes and the " -"values are iterables of all predecessors of that node in the graph (the " -"nodes that have edges that point to the value in the key). Additional nodes " -"can be added to the graph using the :meth:`~TopologicalSorter.add` method." -msgstr "" -"如果提供了可選的 *graph* 引數，它必須是表示有向無環圖的字典，其中鍵是節點，值" -"是圖中該節點的包含所有前驅節點 (predecessor) 之可疊代物件（這些前驅節點具有指" -"向以鍵表示之節點的邊）。可以使用 :meth:`~TopologicalSorter.add` 方法將其他節" -"點新增到圖中。" - -#: ../../library/graphlib.rst:37 -msgid "" -"In the general case, the steps required to perform the sorting of a given " -"graph are as follows:" -msgstr "在一般情況下，對給定的圖執行排序所需的步驟如下：" - -#: ../../library/graphlib.rst:40 -msgid "" -"Create an instance of the :class:`TopologicalSorter` with an optional " -"initial graph." -msgstr "以選用的初始圖建立 :class:`TopologicalSorter` 的實例。" - -#: ../../library/graphlib.rst:42 -msgid "Add additional nodes to the graph." -msgstr "在圖中新增其他節點。" - -#: ../../library/graphlib.rst:43 -msgid "Call :meth:`~TopologicalSorter.prepare` on the graph." -msgstr "呼叫圖的 :meth:`~TopologicalSorter.prepare`。" - -#: ../../library/graphlib.rst:44 -msgid "" -"While :meth:`~TopologicalSorter.is_active` is ``True``, iterate over the " -"nodes returned by :meth:`~TopologicalSorter.get_ready` and process them. " -"Call :meth:`~TopologicalSorter.done` on each node as it finishes processing." -msgstr "" -"當 :meth:`~TopologicalSorter.is_active` 為 ``True`` 時，疊" -"代 :meth:`~TopologicalSorter.get_ready` 回傳的節點並處理它們。在每個節點完成" -"處理時呼叫 :meth:`~TopologicalSorter.done`。" - -#: ../../library/graphlib.rst:49 -msgid "" -"In case just an immediate sorting of the nodes in the graph is required and " -"no parallelism is involved, the convenience " -"method :meth:`TopologicalSorter.static_order` can be used directly:" -msgstr "" -"如果只需要立即對圖中的節點進行排序且不涉及平行性 (parallelism)，則可以直接使" -"用便捷方法 :meth:`TopologicalSorter.static_order`：" - -#: ../../library/graphlib.rst:53 -msgid "" -">>> graph = {\"D\": {\"B\", \"C\"}, \"C\": {\"A\"}, \"B\": {\"A\"}}\n" -">>> ts = TopologicalSorter(graph)\n" -">>> tuple(ts.static_order())\n" -"('A', 'C', 'B', 'D')" -msgstr "" -">>> graph = {\"D\": {\"B\", \"C\"}, \"C\": {\"A\"}, \"B\": {\"A\"}}\n" -">>> ts = TopologicalSorter(graph)\n" -">>> tuple(ts.static_order())\n" -"('A', 'C', 'B', 'D')" - -#: ../../library/graphlib.rst:60 -msgid "" -"The class is designed to easily support parallel processing of the nodes as " -"they become ready. For instance::" -msgstr "該類別設計為在節點準備就緒時，簡單支援節點的平行處理。例如： ::" - -#: ../../library/graphlib.rst:63 -msgid "" -"topological_sorter = TopologicalSorter()\n" -"\n" -"# Add nodes to 'topological_sorter'...\n" -"\n" -"topological_sorter.prepare()\n" -"while topological_sorter.is_active():\n" -" for node in topological_sorter.get_ready():\n" -" # Worker threads or processes take nodes to work on off the\n" -" # 'task_queue' queue.\n" -" task_queue.put(node)\n" -"\n" -" # When the work for a node is done, workers put the node in\n" -" # 'finalized_tasks_queue' so we can get more nodes to work on.\n" -" # The definition of 'is_active()' guarantees that, at this point, at\n" -" # least one node has been placed on 'task_queue' that hasn't yet\n" -" # been passed to 'done()', so this blocking 'get()' must (eventually)\n" -" # succeed. After calling 'done()', we loop back to call 'get_ready()'\n" -" # again, so put newly freed nodes on 'task_queue' as soon as\n" -" # logically possible.\n" -" node = finalized_tasks_queue.get()\n" -" topological_sorter.done(node)" -msgstr "" - -#: ../../library/graphlib.rst:87 -msgid "" -"Add a new node and its predecessors to the graph. Both the *node* and all " -"elements in *predecessors* must be :term:`hashable`." -msgstr "" -"向圖中新增新節點及其前驅節點。*node* 和 *predecessors* 中的所有元素都必須是" -"\\ :term:`可雜湊 `\\ 的。" - -#: ../../library/graphlib.rst:90 -msgid "" -"If called multiple times with the same node argument, the set of " -"dependencies will be the union of all dependencies passed in." -msgstr "" -"如果以相同節點引數多次呼叫，則依賴項的集合將會是傳入的所有依賴項的聯集。" - -#: ../../library/graphlib.rst:93 -msgid "" -"It is possible to add a node with no dependencies (*predecessors* is not " -"provided) or to provide a dependency twice. If a node that has not been " -"provided before is included among *predecessors* it will be automatically " -"added to the graph with no predecessors of its own." -msgstr "" -"可以新增一個沒有依賴關係的節點（*predecessors* 未提供）或提供兩次依賴關係。如" -"果有之前未曾提供的節點被包含在 *predecessors* 中，它將自動新增到沒有前驅節點" -"的圖中。" - -#: ../../library/graphlib.rst:98 -msgid "" -"Raises :exc:`ValueError` if called after :meth:`~TopologicalSorter.prepare`." -msgstr "" -"如果在 :meth:`~TopologicalSorter.prepare` 之後呼叫，則引" -"發 :exc:`ValueError`。" - -#: ../../library/graphlib.rst:102 -msgid "" -"Mark the graph as finished and check for cycles in the graph. If any cycle " -"is detected, :exc:`CycleError` will be raised, " -"but :meth:`~TopologicalSorter.get_ready` can still be used to obtain as many " -"nodes as possible until cycles block more progress. After a call to this " -"function, the graph cannot be modified, and therefore no more nodes can be " -"added using :meth:`~TopologicalSorter.add`." -msgstr "" -"將圖標記為已完成並檢查圖中的循環。如果檢測到任何循環，將引" -"發 :exc:`CycleError`，但 :meth:`~TopologicalSorter.get_ready` 仍可用於盡可能" -"獲得更多的節點，直到循環阻塞了進度。呼叫此函式後就無法修改圖，因此無法使" -"用 :meth:`~TopologicalSorter.add` 來新增更多節點。" - -#: ../../library/graphlib.rst:109 -msgid "" -"A :exc:`ValueError` will be raised if the sort has been started " -"by :meth:`~.static_order` or :meth:`~.get_ready`." -msgstr "" - -#: ../../library/graphlib.rst:114 -msgid "" -"``prepare()`` can now be called more than once as long as the sort has not " -"started. Previously this raised :exc:`ValueError`." -msgstr "" - -#: ../../library/graphlib.rst:119 -msgid "" -"Returns ``True`` if more progress can be made and ``False`` otherwise. " -"Progress can be made if cycles do not block the resolution and either there " -"are still nodes ready that haven't yet been returned " -"by :meth:`TopologicalSorter.get_ready` or the number of nodes " -"marked :meth:`TopologicalSorter.done` is less than the number that have been " -"returned by :meth:`TopologicalSorter.get_ready`." -msgstr "" -"如果可以有更多進度則回傳 ``True``，否則回傳 ``False``。如果循環不阻塞解析 " -"(resolution) 並且仍有節點準備就緒但尚未" -"由 :meth:`TopologicalSorter.get_ready` 回傳或標記" -"為 :meth:`TopologicalSorter.done` 的節點數量" -"較 :meth:`TopologicalSorter.get_ready` 所回傳的少，則可以繼續取得進度。" - -#: ../../library/graphlib.rst:126 -msgid "" -"The :meth:`~object.__bool__` method of this class defers to this function, " -"so instead of::" -msgstr "此類別的 :meth:`~object.__bool__` 方法遵循此函式，因此以下做法： ::" - -#: ../../library/graphlib.rst:129 -msgid "" -"if ts.is_active():\n" -" ..." -msgstr "" -"if ts.is_active():\n" -" ..." - -#: ../../library/graphlib.rst:132 -msgid "it is possible to simply do::" -msgstr "可以簡單地用以下方式替換： ::" - -#: ../../library/graphlib.rst:134 -msgid "" -"if ts:\n" -" ..." -msgstr "" -"if ts:\n" -" ..." - -#: ../../library/graphlib.rst:137 ../../library/graphlib.rst:160 -msgid "" -"Raises :exc:`ValueError` if called without " -"calling :meth:`~TopologicalSorter.prepare` previously." -msgstr "" -"如果呼叫之前沒有先呼叫 :meth:`~TopologicalSorter.prepare` 則引" -"發 :exc:`ValueError`。" - -#: ../../library/graphlib.rst:142 -msgid "" -"Marks a set of nodes returned by :meth:`TopologicalSorter.get_ready` as " -"processed, unblocking any successor of each node in *nodes* for being " -"returned in the future by a call to :meth:`TopologicalSorter.get_ready`." -msgstr "" -"將 :meth:`TopologicalSorter.get_ready` 回傳的一組節點標記為已處理，停止阻塞 " -"*nodes* 中每個節點的任何後繼節點 (successor)，以便將來透過呼" -"叫 :meth:`TopologicalSorter.get_ready` 回傳。" - -#: ../../library/graphlib.rst:146 -msgid "" -"Raises :exc:`ValueError` if any node in *nodes* has already been marked as " -"processed by a previous call to this method or if a node was not added to " -"the graph by using :meth:`TopologicalSorter.add`, if called without " -"calling :meth:`~TopologicalSorter.prepare` or if node has not yet been " -"returned by :meth:`~TopologicalSorter.get_ready`." -msgstr "" -"若沒有和該呼叫一起呼叫 :meth:`~TopologicalSorter.prepare` 或節點還沒有" -"被 :meth:`~TopologicalSorter.get_ready` 回傳，且如果 *nodes* 中有任何節點已被" -"先前對此方法的呼叫標記為已處理、或者未使用 :meth:`TopologicalSorter.add` 將節" -"點新增到圖中，則引發 :exc:`ValueError`。" - -#: ../../library/graphlib.rst:154 -msgid "" -"Returns a ``tuple`` with all the nodes that are ready. Initially it returns " -"all nodes with no predecessors, and once those are marked as processed by " -"calling :meth:`TopologicalSorter.done`, further calls will return all new " -"nodes that have all their predecessors already processed. Once no more " -"progress can be made, empty tuples are returned." -msgstr "" -"回傳一個包含所有準備就緒節點的 ``tuple``。最初它回傳沒有前驅節點的所有節點，" -"一旦透過呼叫 :meth:`TopologicalSorter.done` 來將這些節點標記為已處理後，進一" -"步的呼叫將回傳所有其全部前驅節點都已被處理的新節點。若無法取得更多進度，將回" -"傳空 tuple。" - -#: ../../library/graphlib.rst:165 -msgid "" -"Returns an iterator object which will iterate over nodes in a topological " -"order. When using this method, :meth:`~TopologicalSorter.prepare` " -"and :meth:`~TopologicalSorter.done` should not be called. This method is " -"equivalent to::" -msgstr "" -"回傳一個可疊代物件，它將按拓撲排序疊代節點。使用此方法時，不應呼" -"叫 :meth:`~TopologicalSorter.prepare` 和 :meth:`~TopologicalSorter.done`。此" -"方法等效於： ::" - -#: ../../library/graphlib.rst:170 -msgid "" -"def static_order(self):\n" -" self.prepare()\n" -" while self.is_active():\n" -" node_group = self.get_ready()\n" -" yield from node_group\n" -" self.done(*node_group)" -msgstr "" -"def static_order(self):\n" -" self.prepare()\n" -" while self.is_active():\n" -" node_group = self.get_ready()\n" -" yield from node_group\n" -" self.done(*node_group)" - -#: ../../library/graphlib.rst:177 -msgid "" -"The particular order that is returned may depend on the specific order in " -"which the items were inserted in the graph. For example:" -msgstr "回傳的特定順序可能取決於將項目插入圖中的特定順序。例如：" - -#: ../../library/graphlib.rst:180 -msgid "" -">>> ts = TopologicalSorter()\n" -">>> ts.add(3, 2, 1)\n" -">>> ts.add(1, 0)\n" -">>> print([*ts.static_order()])\n" -"[2, 0, 1, 3]\n" -"\n" -">>> ts2 = TopologicalSorter()\n" -">>> ts2.add(1, 0)\n" -">>> ts2.add(3, 2, 1)\n" -">>> print([*ts2.static_order()])\n" -"[0, 2, 1, 3]" -msgstr "" -">>> ts = TopologicalSorter()\n" -">>> ts.add(3, 2, 1)\n" -">>> ts.add(1, 0)\n" -">>> print([*ts.static_order()])\n" -"[2, 0, 1, 3]\n" -"\n" -">>> ts2 = TopologicalSorter()\n" -">>> ts2.add(1, 0)\n" -">>> ts2.add(3, 2, 1)\n" -">>> print([*ts2.static_order()])\n" -"[0, 2, 1, 3]" - -#: ../../library/graphlib.rst:194 -msgid "" -"This is due to the fact that \"0\" and \"2\" are in the same level in the " -"graph (they would have been returned in the same call " -"to :meth:`~TopologicalSorter.get_ready`) and the order between them is " -"determined by the order of insertion." -msgstr "" -"這是因為 \"0\" 和 \"2\" 在圖中處於同一級別（它們將在" -"對 :meth:`~TopologicalSorter.get_ready` 的同一呼叫中回傳）並且它們之間的順序" -"取決於插入順序。" - -#: ../../library/graphlib.rst:200 -msgid "If any cycle is detected, :exc:`CycleError` will be raised." -msgstr "如果檢測到任何循環，則引發 :exc:`CycleError`。" - -#: ../../library/graphlib.rst:206 -msgid "Exceptions" -msgstr "例外" - -#: ../../library/graphlib.rst:207 -msgid "The :mod:`graphlib` module defines the following exception classes:" -msgstr ":mod:`graphlib` 模組定義了以下例外類別：" - -#: ../../library/graphlib.rst:211 -msgid "" -"Subclass of :exc:`ValueError` raised by :meth:`TopologicalSorter.prepare` if " -"cycles exist in the working graph. If multiple cycles exist, only one " -"undefined choice among them will be reported and included in the exception." -msgstr "" -":exc:`ValueError` 的子類別，如果作用的圖中存在循環則" -"由 :meth:`TopologicalSorter.prepare` 引發。如果存在多個循環，則只會報告未定義" -"的其中一個並包含在例外中。" - -#: ../../library/graphlib.rst:215 -msgid "" -"The detected cycle can be accessed via the second element in " -"the :attr:`~BaseException.args` attribute of the exception instance and " -"consists in a list of nodes, such that each node is, in the graph, an " -"immediate predecessor of the next node in the list. In the reported list, " -"the first and the last node will be the same, to make it clear that it is " -"cyclic." -msgstr "" -"檢測到的循環可以透過例外實例的 :attr:`~BaseException.args` 屬性中第二個元素來" -"存取，其為一個節點列表，每個節點在圖中都是列表中下一個節點的直接前驅節點" -"（immediate predecessor，即父節點）。在報告列表中，第一個和最後一個節點將會是" -"相同的，用以明確表示它是循環的。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Matt Wang , 2023 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-08 15:25+0800\n" +"PO-Revision-Date: 2023-01-04 16:35+0800\n" +"Last-Translator: Matt Wang \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" +"X-Generator: Poedit 3.2.2\n" + +#: ../../library/graphlib.rst:2 +msgid "" +":mod:`!graphlib` --- Functionality to operate with graph-like structures" +msgstr ":mod:`!graphlib` —-- 使用類圖 (graph-like) 結構進行操作的功能" + +#: ../../library/graphlib.rst:8 +msgid "**Source code:** :source:`Lib/graphlib.py`" +msgstr "**原始碼：**\\ :source:`Lib/graphlib.py`" + +#: ../../library/graphlib.rst:20 +msgid "" +"Provides functionality to topologically sort a graph of :term:`hashable` " +"nodes." +msgstr "" +"提供對包含\\ :term:`可雜湊 (hashable) ` 節點之圖 (graph) 進行拓撲排" +"序 (topologically sort) 的功能。" + +#: ../../library/graphlib.rst:22 +msgid "" +"A topological order is a linear ordering of the vertices in a graph such " +"that for every directed edge u -> v from vertex u to vertex v, vertex u " +"comes before vertex v in the ordering. For instance, the vertices of the " +"graph may represent tasks to be performed, and the edges may represent " +"constraints that one task must be performed before another; in this example, " +"a topological ordering is just a valid sequence for the tasks. A complete " +"topological ordering is possible if and only if the graph has no directed " +"cycles, that is, if it is a directed acyclic graph." +msgstr "" +"拓撲排序是圖中頂點 (vertex) 的線性排序，使得對於從頂點 u 到頂點 v 的每條有向" +"邊 (directed edge) u -> v，頂點 u 在排序中會位於頂點 v 之前。例如，圖的頂點可" +"能代表要執行的任務，而邊可能代表一個任務必須在另一個任務之前執行的限制；在此" +"範例中，拓撲排序只是任務的一種有效序列。若且唯若 (if and only if) 圖沒有有向" +"環 (directed cycle) 時，即如果它是個有向無環圖 (directed acyclic graph)，則完" +"整的拓撲排序才是可行的。" + +#: ../../library/graphlib.rst:31 +msgid "" +"If the optional *graph* argument is provided it must be a dictionary " +"representing a directed acyclic graph where the keys are nodes and the " +"values are iterables of all predecessors of that node in the graph (the " +"nodes that have edges that point to the value in the key). Additional nodes " +"can be added to the graph using the :meth:`~TopologicalSorter.add` method." +msgstr "" +"如果提供了可選的 *graph* 引數，它必須是表示有向無環圖的字典，其中鍵是節點，值" +"是圖中該節點的包含所有前驅節點 (predecessor) 之可疊代物件（這些前驅節點具有指" +"向以鍵表示之節點的邊）。可以使用 :meth:`~TopologicalSorter.add` 方法將其他節" +"點新增到圖中。" + +#: ../../library/graphlib.rst:37 +msgid "" +"In the general case, the steps required to perform the sorting of a given " +"graph are as follows:" +msgstr "在一般情況下，對給定的圖執行排序所需的步驟如下：" + +#: ../../library/graphlib.rst:40 +msgid "" +"Create an instance of the :class:`TopologicalSorter` with an optional " +"initial graph." +msgstr "以選用的初始圖建立 :class:`TopologicalSorter` 的實例。" + +#: ../../library/graphlib.rst:42 +msgid "Add additional nodes to the graph." +msgstr "在圖中新增其他節點。" + +#: ../../library/graphlib.rst:43 +msgid "Call :meth:`~TopologicalSorter.prepare` on the graph." +msgstr "呼叫圖的 :meth:`~TopologicalSorter.prepare`。" + +#: ../../library/graphlib.rst:44 +msgid "" +"While :meth:`~TopologicalSorter.is_active` is ``True``, iterate over the " +"nodes returned by :meth:`~TopologicalSorter.get_ready` and process them. " +"Call :meth:`~TopologicalSorter.done` on each node as it finishes processing." +msgstr "" +"當 :meth:`~TopologicalSorter.is_active` 為 ``True`` 時，疊" +"代 :meth:`~TopologicalSorter.get_ready` 回傳的節點並處理它們。在每個節點完成" +"處理時呼叫 :meth:`~TopologicalSorter.done`。" + +#: ../../library/graphlib.rst:49 +msgid "" +"In case just an immediate sorting of the nodes in the graph is required and " +"no parallelism is involved, the convenience " +"method :meth:`TopologicalSorter.static_order` can be used directly:" +msgstr "" +"如果只需要立即對圖中的節點進行排序且不涉及平行性 (parallelism)，則可以直接使" +"用便捷方法 :meth:`TopologicalSorter.static_order`：" + +#: ../../library/graphlib.rst:53 +msgid "" +">>> graph = {\"D\": {\"B\", \"C\"}, \"C\": {\"A\"}, \"B\": {\"A\"}}\n" +">>> ts = TopologicalSorter(graph)\n" +">>> tuple(ts.static_order())\n" +"('A', 'C', 'B', 'D')" +msgstr "" +">>> graph = {\"D\": {\"B\", \"C\"}, \"C\": {\"A\"}, \"B\": {\"A\"}}\n" +">>> ts = TopologicalSorter(graph)\n" +">>> tuple(ts.static_order())\n" +"('A', 'C', 'B', 'D')" + +#: ../../library/graphlib.rst:60 +msgid "" +"The class is designed to easily support parallel processing of the nodes as " +"they become ready. For instance::" +msgstr "該類別設計為在節點準備就緒時，簡單支援節點的平行處理。例如： ::" + +#: ../../library/graphlib.rst:63 +msgid "" +"topological_sorter = TopologicalSorter()\n" +"\n" +"# Add nodes to 'topological_sorter'...\n" +"\n" +"topological_sorter.prepare()\n" +"while topological_sorter.is_active():\n" +" for node in topological_sorter.get_ready():\n" +" # Worker threads or processes take nodes to work on off the\n" +" # 'task_queue' queue.\n" +" task_queue.put(node)\n" +"\n" +" # When the work for a node is done, workers put the node in\n" +" # 'finalized_tasks_queue' so we can get more nodes to work on.\n" +" # The definition of 'is_active()' guarantees that, at this point, at\n" +" # least one node has been placed on 'task_queue' that hasn't yet\n" +" # been passed to 'done()', so this blocking 'get()' must (eventually)\n" +" # succeed. After calling 'done()', we loop back to call 'get_ready()'\n" +" # again, so put newly freed nodes on 'task_queue' as soon as\n" +" # logically possible.\n" +" node = finalized_tasks_queue.get()\n" +" topological_sorter.done(node)" +msgstr "" + +#: ../../library/graphlib.rst:87 +msgid "" +"Add a new node and its predecessors to the graph. Both the *node* and all " +"elements in *predecessors* must be :term:`hashable`." +msgstr "" +"向圖中新增新節點及其前驅節點。*node* 和 *predecessors* 中的所有元素都必須是" +"\\ :term:`可雜湊 `\\ 的。" + +#: ../../library/graphlib.rst:90 +msgid "" +"If called multiple times with the same node argument, the set of " +"dependencies will be the union of all dependencies passed in." +msgstr "" +"如果以相同節點引數多次呼叫，則依賴項的集合將會是傳入的所有依賴項的聯集。" + +#: ../../library/graphlib.rst:93 +msgid "" +"It is possible to add a node with no dependencies (*predecessors* is not " +"provided) or to provide a dependency twice. If a node that has not been " +"provided before is included among *predecessors* it will be automatically " +"added to the graph with no predecessors of its own." +msgstr "" +"可以新增一個沒有依賴關係的節點（*predecessors* 未提供）或提供兩次依賴關係。如" +"果有之前未曾提供的節點被包含在 *predecessors* 中，它將自動新增到沒有前驅節點" +"的圖中。" + +#: ../../library/graphlib.rst:98 +msgid "" +"Raises :exc:`ValueError` if called after :meth:`~TopologicalSorter.prepare`." +msgstr "" +"如果在 :meth:`~TopologicalSorter.prepare` 之後呼叫，則引" +"發 :exc:`ValueError`。" + +#: ../../library/graphlib.rst:102 +msgid "" +"Mark the graph as finished and check for cycles in the graph. If any cycle " +"is detected, :exc:`CycleError` will be raised, " +"but :meth:`~TopologicalSorter.get_ready` can still be used to obtain as many " +"nodes as possible until cycles block more progress. After a call to this " +"function, the graph cannot be modified, and therefore no more nodes can be " +"added using :meth:`~TopologicalSorter.add`." +msgstr "" +"將圖標記為已完成並檢查圖中的循環。如果檢測到任何循環，將引" +"發 :exc:`CycleError`，但 :meth:`~TopologicalSorter.get_ready` 仍可用於盡可能" +"獲得更多的節點，直到循環阻塞了進度。呼叫此函式後就無法修改圖，因此無法使" +"用 :meth:`~TopologicalSorter.add` 來新增更多節點。" + +#: ../../library/graphlib.rst:109 +msgid "" +"A :exc:`ValueError` will be raised if the sort has been started " +"by :meth:`~.static_order` or :meth:`~.get_ready`." +msgstr "" + +#: ../../library/graphlib.rst:114 +msgid "" +"``prepare()`` can now be called more than once as long as the sort has not " +"started. Previously this raised :exc:`ValueError`." +msgstr "" + +#: ../../library/graphlib.rst:119 +msgid "" +"Returns ``True`` if more progress can be made and ``False`` otherwise. " +"Progress can be made if cycles do not block the resolution and either there " +"are still nodes ready that haven't yet been returned " +"by :meth:`TopologicalSorter.get_ready` or the number of nodes " +"marked :meth:`TopologicalSorter.done` is less than the number that have been " +"returned by :meth:`TopologicalSorter.get_ready`." +msgstr "" +"如果可以有更多進度則回傳 ``True``，否則回傳 ``False``。如果循環不阻塞解析 " +"(resolution) 並且仍有節點準備就緒但尚未" +"由 :meth:`TopologicalSorter.get_ready` 回傳或標記" +"為 :meth:`TopologicalSorter.done` 的節點數量" +"較 :meth:`TopologicalSorter.get_ready` 所回傳的少，則可以繼續取得進度。" + +#: ../../library/graphlib.rst:126 +msgid "" +"The :meth:`~object.__bool__` method of this class defers to this function, " +"so instead of::" +msgstr "此類別的 :meth:`~object.__bool__` 方法遵循此函式，因此以下做法： ::" + +#: ../../library/graphlib.rst:129 +msgid "" +"if ts.is_active():\n" +" ..." +msgstr "" +"if ts.is_active():\n" +" ..." + +#: ../../library/graphlib.rst:132 +msgid "it is possible to simply do::" +msgstr "可以簡單地用以下方式替換： ::" + +#: ../../library/graphlib.rst:134 +msgid "" +"if ts:\n" +" ..." +msgstr "" +"if ts:\n" +" ..." + +#: ../../library/graphlib.rst:137 ../../library/graphlib.rst:160 +msgid "" +"Raises :exc:`ValueError` if called without " +"calling :meth:`~TopologicalSorter.prepare` previously." +msgstr "" +"如果呼叫之前沒有先呼叫 :meth:`~TopologicalSorter.prepare` 則引" +"發 :exc:`ValueError`。" + +#: ../../library/graphlib.rst:142 +msgid "" +"Marks a set of nodes returned by :meth:`TopologicalSorter.get_ready` as " +"processed, unblocking any successor of each node in *nodes* for being " +"returned in the future by a call to :meth:`TopologicalSorter.get_ready`." +msgstr "" +"將 :meth:`TopologicalSorter.get_ready` 回傳的一組節點標記為已處理，停止阻塞 " +"*nodes* 中每個節點的任何後繼節點 (successor)，以便將來透過呼" +"叫 :meth:`TopologicalSorter.get_ready` 回傳。" + +#: ../../library/graphlib.rst:146 +msgid "" +"Raises :exc:`ValueError` if any node in *nodes* has already been marked as " +"processed by a previous call to this method or if a node was not added to " +"the graph by using :meth:`TopologicalSorter.add`, if called without " +"calling :meth:`~TopologicalSorter.prepare` or if node has not yet been " +"returned by :meth:`~TopologicalSorter.get_ready`." +msgstr "" +"若沒有和該呼叫一起呼叫 :meth:`~TopologicalSorter.prepare` 或節點還沒有" +"被 :meth:`~TopologicalSorter.get_ready` 回傳，且如果 *nodes* 中有任何節點已被" +"先前對此方法的呼叫標記為已處理、或者未使用 :meth:`TopologicalSorter.add` 將節" +"點新增到圖中，則引發 :exc:`ValueError`。" + +#: ../../library/graphlib.rst:154 +msgid "" +"Returns a ``tuple`` with all the nodes that are ready. Initially it returns " +"all nodes with no predecessors, and once those are marked as processed by " +"calling :meth:`TopologicalSorter.done`, further calls will return all new " +"nodes that have all their predecessors already processed. Once no more " +"progress can be made, empty tuples are returned." +msgstr "" +"回傳一個包含所有準備就緒節點的 ``tuple``。最初它回傳沒有前驅節點的所有節點，" +"一旦透過呼叫 :meth:`TopologicalSorter.done` 來將這些節點標記為已處理後，進一" +"步的呼叫將回傳所有其全部前驅節點都已被處理的新節點。若無法取得更多進度，將回" +"傳空 tuple。" + +#: ../../library/graphlib.rst:165 +msgid "" +"Returns an iterator object which will iterate over nodes in a topological " +"order. When using this method, :meth:`~TopologicalSorter.prepare` " +"and :meth:`~TopologicalSorter.done` should not be called. This method is " +"equivalent to::" +msgstr "" +"回傳一個可疊代物件，它將按拓撲排序疊代節點。使用此方法時，不應呼" +"叫 :meth:`~TopologicalSorter.prepare` 和 :meth:`~TopologicalSorter.done`。此" +"方法等效於： ::" + +#: ../../library/graphlib.rst:170 +msgid "" +"def static_order(self):\n" +" self.prepare()\n" +" while self.is_active():\n" +" node_group = self.get_ready()\n" +" yield from node_group\n" +" self.done(*node_group)" +msgstr "" +"def static_order(self):\n" +" self.prepare()\n" +" while self.is_active():\n" +" node_group = self.get_ready()\n" +" yield from node_group\n" +" self.done(*node_group)" + +#: ../../library/graphlib.rst:177 +msgid "" +"The particular order that is returned may depend on the specific order in " +"which the items were inserted in the graph. For example:" +msgstr "回傳的特定順序可能取決於將項目插入圖中的特定順序。例如：" + +#: ../../library/graphlib.rst:180 +msgid "" +">>> ts = TopologicalSorter()\n" +">>> ts.add(3, 2, 1)\n" +">>> ts.add(1, 0)\n" +">>> print([*ts.static_order()])\n" +"[2, 0, 1, 3]\n" +"\n" +">>> ts2 = TopologicalSorter()\n" +">>> ts2.add(1, 0)\n" +">>> ts2.add(3, 2, 1)\n" +">>> print([*ts2.static_order()])\n" +"[0, 2, 1, 3]" +msgstr "" +">>> ts = TopologicalSorter()\n" +">>> ts.add(3, 2, 1)\n" +">>> ts.add(1, 0)\n" +">>> print([*ts.static_order()])\n" +"[2, 0, 1, 3]\n" +"\n" +">>> ts2 = TopologicalSorter()\n" +">>> ts2.add(1, 0)\n" +">>> ts2.add(3, 2, 1)\n" +">>> print([*ts2.static_order()])\n" +"[0, 2, 1, 3]" + +#: ../../library/graphlib.rst:194 +msgid "" +"This is due to the fact that \"0\" and \"2\" are in the same level in the " +"graph (they would have been returned in the same call " +"to :meth:`~TopologicalSorter.get_ready`) and the order between them is " +"determined by the order of insertion." +msgstr "" +"這是因為 \"0\" 和 \"2\" 在圖中處於同一級別（它們將在" +"對 :meth:`~TopologicalSorter.get_ready` 的同一呼叫中回傳）並且它們之間的順序" +"取決於插入順序。" + +#: ../../library/graphlib.rst:200 +msgid "If any cycle is detected, :exc:`CycleError` will be raised." +msgstr "如果檢測到任何循環，則引發 :exc:`CycleError`。" + +#: ../../library/graphlib.rst:206 +msgid "Exceptions" +msgstr "例外" + +#: ../../library/graphlib.rst:207 +msgid "The :mod:`graphlib` module defines the following exception classes:" +msgstr ":mod:`graphlib` 模組定義了以下例外類別：" + +#: ../../library/graphlib.rst:211 +msgid "" +"Subclass of :exc:`ValueError` raised by :meth:`TopologicalSorter.prepare` if " +"cycles exist in the working graph. If multiple cycles exist, only one " +"undefined choice among them will be reported and included in the exception." +msgstr "" +":exc:`ValueError` 的子類別，如果作用的圖中存在循環則" +"由 :meth:`TopologicalSorter.prepare` 引發。如果存在多個循環，則只會報告未定義" +"的其中一個並包含在例外中。" + +#: ../../library/graphlib.rst:215 +msgid "" +"The detected cycle can be accessed via the second element in " +"the :attr:`~BaseException.args` attribute of the exception instance and " +"consists in a list of nodes, such that each node is, in the graph, an " +"immediate predecessor of the next node in the list. In the reported list, " +"the first and the last node will be the same, to make it clear that it is " +"cyclic." +msgstr "" +"檢測到的循環可以透過例外實例的 :attr:`~BaseException.args` 屬性中第二個元素來" +"存取，其為一個節點列表，每個節點在圖中都是列表中下一個節點的直接前驅節點" +"（immediate predecessor，即父節點）。在報告列表中，第一個和最後一個節點將會是" +"相同的，用以明確表示它是循環的。" diff --git a/library/grp.po b/library/grp.po index 8c5ae5e20d..e77b80d9e1 100644 --- a/library/grp.po +++ b/library/grp.po @@ -1,155 +1,155 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Weilin Du, 2025 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-10-11 00:13+0000\n" -"PO-Revision-Date: 2025-06-28 17:17+0800\n" -"Last-Translator: Weilin Du\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/grp.rst:2 -msgid ":mod:`!grp` --- The group database" -msgstr ":mod:`!grp` --- 群組資料庫" - -#: ../../library/grp.rst:10 -msgid "" -"This module provides access to the Unix group database. It is available on " -"all Unix versions." -msgstr "該模組提供對 Unix 群組資料庫的存取， 所有 Unix 版本皆可使用。" - -#: ../../library/grp.rst:13 -msgid "Availability" -msgstr "可用性" - -#: ../../library/grp.rst:15 -msgid "" -"Group database entries are reported as a tuple-like object, whose attributes " -"correspond to the members of the ``group`` structure (Attribute field below, " -"see ````):" -msgstr "" -"群組資料庫條目以類似 tuple 物件的方式報傳入， 其屬性對應於 ``group`` 結構的成" -"員（屬性欄位如下， 請參閱 ````）：" - -#: ../../library/grp.rst:20 -msgid "Index" -msgstr "索引" - -#: ../../library/grp.rst:20 -msgid "Attribute" -msgstr "屬性" - -#: ../../library/grp.rst:20 -msgid "Meaning" -msgstr "含義" - -#: ../../library/grp.rst:22 -msgid "0" -msgstr "0" - -#: ../../library/grp.rst:22 -msgid "gr_name" -msgstr "gr_name" - -#: ../../library/grp.rst:22 -msgid "the name of the group" -msgstr "群組名稱" - -#: ../../library/grp.rst:24 -msgid "1" -msgstr "1" - -#: ../../library/grp.rst:24 -msgid "gr_passwd" -msgstr "gr_passwd" - -#: ../../library/grp.rst:24 -msgid "the (encrypted) group password; often empty" -msgstr "（被加密後的）群組密碼；大部分情況下是空的" - -#: ../../library/grp.rst:27 -msgid "2" -msgstr "2" - -#: ../../library/grp.rst:27 -msgid "gr_gid" -msgstr "gr_gid" - -#: ../../library/grp.rst:27 -msgid "the numerical group ID" -msgstr "群組的數字 ID" - -#: ../../library/grp.rst:29 -msgid "3" -msgstr "3" - -#: ../../library/grp.rst:29 -msgid "gr_mem" -msgstr "gr_mem" - -#: ../../library/grp.rst:29 -msgid "all the group member's user names" -msgstr "所有群組成員的使用者名稱" - -#: ../../library/grp.rst:33 -msgid "" -"The gid is an integer, name and password are strings, and the member list is " -"a list of strings. (Note that most users are not explicitly listed as " -"members of the group they are in according to the password database. Check " -"both databases to get complete membership information. Also note that a " -"``gr_name`` that starts with a ``+`` or ``-`` is likely to be a YP/NIS " -"reference and may not be accessible via :func:`getgrnam` or :func:" -"`getgrgid`.)" -msgstr "" -"gid 是整數，name 和 password 是字串， 而 member list 是字串串列。（請注" -"意， 根據密碼資料庫， 大多數使用者並未被明確列為其所在群組的成員。 請檢查這兩" -"個資料庫，以取得完整的成員資訊。 另外請注意，以 ``+`` 或 ``-`` 開頭的 " -"``gr_name`` 很可能是 YP/NIS 參照，可能無法透過 :func:`getgrnam` 或 :func:" -"`getgrgid` 取得）。" - -#: ../../library/grp.rst:40 -msgid "It defines the following items:" -msgstr "它定義了以下項目：" - -#: ../../library/grp.rst:45 -msgid "" -"Return the group database entry for the given numeric group ID. :exc:" -"`KeyError` is raised if the entry asked for cannot be found." -msgstr "" -"回傳給定群組 ID 的群組資料庫條目。 :exc:`KeyError` 會在找不到所要求的條目時被引" -"發。" - -#: ../../library/grp.rst:48 -msgid "" -":exc:`TypeError` is raised for non-integer arguments like floats or strings." -msgstr ":exc:`TypeError` 會在非整數的引數如浮點數或字串被傳入時被引發。" - -#: ../../library/grp.rst:53 -msgid "" -"Return the group database entry for the given group name. :exc:`KeyError` is " -"raised if the entry asked for cannot be found." -msgstr "" -"回傳給定群組名稱的群組資料庫條目。 :exc:`KeyError` 會在找不到所要求的條目時引" -"發。" - -#: ../../library/grp.rst:59 -msgid "Return a list of all available group entries, in arbitrary order." -msgstr "以任意順序傳回所有可用群組條目的串列。" - -#: ../../library/grp.rst:64 -msgid "Module :mod:`pwd`" -msgstr ":mod:`pwd` 模組" - -#: ../../library/grp.rst:65 -msgid "An interface to the user database, similar to this." -msgstr "使用者資料庫的介面，與此類似。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Weilin Du, 2025 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-10-11 00:13+0000\n" +"PO-Revision-Date: 2025-06-28 17:17+0800\n" +"Last-Translator: Weilin Du\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/grp.rst:2 +msgid ":mod:`!grp` --- The group database" +msgstr ":mod:`!grp` --- 群組資料庫" + +#: ../../library/grp.rst:10 +msgid "" +"This module provides access to the Unix group database. It is available on " +"all Unix versions." +msgstr "該模組提供對 Unix 群組資料庫的存取， 所有 Unix 版本皆可使用。" + +#: ../../library/grp.rst:13 +msgid "Availability" +msgstr "可用性" + +#: ../../library/grp.rst:15 +msgid "" +"Group database entries are reported as a tuple-like object, whose attributes " +"correspond to the members of the ``group`` structure (Attribute field below, " +"see ````):" +msgstr "" +"群組資料庫條目以類似 tuple 物件的方式報傳入， 其屬性對應於 ``group`` 結構的成" +"員（屬性欄位如下， 請參閱 ````）：" + +#: ../../library/grp.rst:20 +msgid "Index" +msgstr "索引" + +#: ../../library/grp.rst:20 +msgid "Attribute" +msgstr "屬性" + +#: ../../library/grp.rst:20 +msgid "Meaning" +msgstr "含義" + +#: ../../library/grp.rst:22 +msgid "0" +msgstr "0" + +#: ../../library/grp.rst:22 +msgid "gr_name" +msgstr "gr_name" + +#: ../../library/grp.rst:22 +msgid "the name of the group" +msgstr "群組名稱" + +#: ../../library/grp.rst:24 +msgid "1" +msgstr "1" + +#: ../../library/grp.rst:24 +msgid "gr_passwd" +msgstr "gr_passwd" + +#: ../../library/grp.rst:24 +msgid "the (encrypted) group password; often empty" +msgstr "（被加密後的）群組密碼；大部分情況下是空的" + +#: ../../library/grp.rst:27 +msgid "2" +msgstr "2" + +#: ../../library/grp.rst:27 +msgid "gr_gid" +msgstr "gr_gid" + +#: ../../library/grp.rst:27 +msgid "the numerical group ID" +msgstr "群組的數字 ID" + +#: ../../library/grp.rst:29 +msgid "3" +msgstr "3" + +#: ../../library/grp.rst:29 +msgid "gr_mem" +msgstr "gr_mem" + +#: ../../library/grp.rst:29 +msgid "all the group member's user names" +msgstr "所有群組成員的使用者名稱" + +#: ../../library/grp.rst:33 +msgid "" +"The gid is an integer, name and password are strings, and the member list is " +"a list of strings. (Note that most users are not explicitly listed as " +"members of the group they are in according to the password database. Check " +"both databases to get complete membership information. Also note that a " +"``gr_name`` that starts with a ``+`` or ``-`` is likely to be a YP/NIS " +"reference and may not be accessible via :func:`getgrnam` or :func:" +"`getgrgid`.)" +msgstr "" +"gid 是整數，name 和 password 是字串， 而 member list 是字串串列。（請注" +"意， 根據密碼資料庫， 大多數使用者並未被明確列為其所在群組的成員。 請檢查這兩" +"個資料庫，以取得完整的成員資訊。 另外請注意，以 ``+`` 或 ``-`` 開頭的 " +"``gr_name`` 很可能是 YP/NIS 參照，可能無法透過 :func:`getgrnam` 或 :func:" +"`getgrgid` 取得）。" + +#: ../../library/grp.rst:40 +msgid "It defines the following items:" +msgstr "它定義了以下項目：" + +#: ../../library/grp.rst:45 +msgid "" +"Return the group database entry for the given numeric group ID. :exc:" +"`KeyError` is raised if the entry asked for cannot be found." +msgstr "" +"回傳給定群組 ID 的群組資料庫條目。 :exc:`KeyError` 會在找不到所要求的條目時被引" +"發。" + +#: ../../library/grp.rst:48 +msgid "" +":exc:`TypeError` is raised for non-integer arguments like floats or strings." +msgstr ":exc:`TypeError` 會在非整數的引數如浮點數或字串被傳入時被引發。" + +#: ../../library/grp.rst:53 +msgid "" +"Return the group database entry for the given group name. :exc:`KeyError` is " +"raised if the entry asked for cannot be found." +msgstr "" +"回傳給定群組名稱的群組資料庫條目。 :exc:`KeyError` 會在找不到所要求的條目時引" +"發。" + +#: ../../library/grp.rst:59 +msgid "Return a list of all available group entries, in arbitrary order." +msgstr "以任意順序傳回所有可用群組條目的串列。" + +#: ../../library/grp.rst:64 +msgid "Module :mod:`pwd`" +msgstr ":mod:`pwd` 模組" + +#: ../../library/grp.rst:65 +msgid "An interface to the user database, similar to this." +msgstr "使用者資料庫的介面，與此類似。" diff --git a/library/gzip.po b/library/gzip.po index f78de511c3..e96e173228 100644 --- a/library/gzip.po +++ b/library/gzip.po @@ -1,455 +1,455 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Adrian Liaw , 2018 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-18 00:15+0000\n" -"PO-Revision-Date: 2018-05-23 16:03+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/gzip.rst:2 -msgid ":mod:`!gzip` --- Support for :program:`gzip` files" -msgstr ":mod:`!gzip` --- :program:`gzip` 檔案的支援" - -#: ../../library/gzip.rst:7 -msgid "**Source code:** :source:`Lib/gzip.py`" -msgstr "**原始碼：**\\ :source:`Lib/gzip.py`" - -#: ../../library/gzip.rst:11 -msgid "" -"This module provides a simple interface to compress and decompress files " -"just like the GNU programs :program:`gzip` and :program:`gunzip` would." -msgstr "" - -#: ../../includes/optional-module.rst:1 -msgid "" -"This is an :term:`optional module`. If it is missing from your copy of " -"CPython, look for documentation from your distributor (that is, whoever " -"provided Python to you). If you are the distributor, see :ref:`optional-" -"module-requirements`." -msgstr "" - -#: ../../library/gzip.rst:16 -msgid "The data compression is provided by the :mod:`zlib` module." -msgstr "" - -#: ../../library/gzip.rst:18 -msgid "" -"The :mod:`gzip` module provides the :class:`GzipFile` class, as well as the :" -"func:`.open`, :func:`compress` and :func:`decompress` convenience functions. " -"The :class:`GzipFile` class reads and writes :program:`gzip`\\ -format " -"files, automatically compressing or decompressing the data so that it looks " -"like an ordinary :term:`file object`." -msgstr "" - -#: ../../library/gzip.rst:24 -msgid "" -"Note that additional file formats which can be decompressed by the :program:" -"`gzip` and :program:`gunzip` programs, such as those produced by :program:" -"`compress` and :program:`pack`, are not supported by this module." -msgstr "" - -#: ../../library/gzip.rst:28 -msgid "The module defines the following items:" -msgstr "此模組定義了以下項目：" - -#: ../../library/gzip.rst:33 -msgid "" -"Open a gzip-compressed file in binary or text mode, returning a :term:`file " -"object`." -msgstr "" - -#: ../../library/gzip.rst:36 -msgid "" -"The *filename* argument can be an actual filename (a :class:`str` or :class:" -"`bytes` object), or an existing file object to read from or write to." -msgstr "" - -#: ../../library/gzip.rst:39 -msgid "" -"The *mode* argument can be any of ``'r'``, ``'rb'``, ``'a'``, ``'ab'``, " -"``'w'``, ``'wb'``, ``'x'`` or ``'xb'`` for binary mode, or ``'rt'``, " -"``'at'``, ``'wt'``, or ``'xt'`` for text mode. The default is ``'rb'``." -msgstr "" - -#: ../../library/gzip.rst:43 -msgid "" -"The *compresslevel* argument is an integer from 0 to 9, as for the :class:" -"`GzipFile` constructor." -msgstr "" - -#: ../../library/gzip.rst:46 -msgid "" -"For binary mode, this function is equivalent to the :class:`GzipFile` " -"constructor: ``GzipFile(filename, mode, compresslevel)``. In this case, the " -"*encoding*, *errors* and *newline* arguments must not be provided." -msgstr "" - -#: ../../library/gzip.rst:50 -msgid "" -"For text mode, a :class:`GzipFile` object is created, and wrapped in an :" -"class:`io.TextIOWrapper` instance with the specified encoding, error " -"handling behavior, and line ending(s)." -msgstr "" - -#: ../../library/gzip.rst:54 -msgid "" -"Added support for *filename* being a file object, support for text mode, and " -"the *encoding*, *errors* and *newline* arguments." -msgstr "" - -#: ../../library/gzip.rst:58 -msgid "Added support for the ``'x'``, ``'xb'`` and ``'xt'`` modes." -msgstr "新增 ``'x'``、``'xb'`` 和 ``'xt'`` 模式的支援。" - -#: ../../library/gzip.rst:61 ../../library/gzip.rst:175 -msgid "Accepts a :term:`path-like object`." -msgstr "接受\\ :term:`類路徑物件 `。" - -#: ../../library/gzip.rst:66 -msgid "" -"An exception raised for invalid gzip files. It inherits from :exc:" -"`OSError`. :exc:`EOFError` and :exc:`zlib.error` can also be raised for " -"invalid gzip files." -msgstr "" - -#: ../../library/gzip.rst:74 -msgid "" -"Constructor for the :class:`GzipFile` class, which simulates most of the " -"methods of a :term:`file object`, with the exception of the :meth:`~io." -"IOBase.truncate` method. At least one of *fileobj* and *filename* must be " -"given a non-trivial value." -msgstr "" - -#: ../../library/gzip.rst:79 -msgid "" -"The new class instance is based on *fileobj*, which can be a regular file, " -"an :class:`io.BytesIO` object, or any other object which simulates a file. " -"It defaults to ``None``, in which case *filename* is opened to provide a " -"file object." -msgstr "" - -#: ../../library/gzip.rst:84 -msgid "" -"When *fileobj* is not ``None``, the *filename* argument is only used to be " -"included in the :program:`gzip` file header, which may include the original " -"filename of the uncompressed file. It defaults to the filename of " -"*fileobj*, if discernible; otherwise, it defaults to the empty string, and " -"in this case the original filename is not included in the header." -msgstr "" - -#: ../../library/gzip.rst:90 -msgid "" -"The *mode* argument can be any of ``'r'``, ``'rb'``, ``'a'``, ``'ab'``, " -"``'w'``, ``'wb'``, ``'x'``, or ``'xb'``, depending on whether the file will " -"be read or written. The default is the mode of *fileobj* if discernible; " -"otherwise, the default is ``'rb'``. In future Python releases the mode of " -"*fileobj* will not be used. It is better to always specify *mode* for " -"writing." -msgstr "" - -#: ../../library/gzip.rst:96 -msgid "" -"Note that the file is always opened in binary mode. To open a compressed " -"file in text mode, use :func:`.open` (or wrap your :class:`GzipFile` with " -"an :class:`io.TextIOWrapper`)." -msgstr "" - -#: ../../library/gzip.rst:100 -msgid "" -"The *compresslevel* argument is an integer from ``0`` to ``9`` controlling " -"the level of compression; ``1`` is fastest and produces the least " -"compression, and ``9`` is slowest and produces the most compression. ``0`` " -"is no compression. The default is ``9``." -msgstr "" - -#: ../../library/gzip.rst:105 -msgid "" -"The optional *mtime* argument is the timestamp requested by gzip. The time " -"is in Unix format, i.e., seconds since 00:00:00 UTC, January 1, 1970. If " -"*mtime* is omitted or ``None``, the current time is used. Use *mtime* = 0 to " -"generate a compressed stream that does not depend on creation time." -msgstr "" - -#: ../../library/gzip.rst:110 -msgid "" -"See below for the :attr:`mtime` attribute that is set when decompressing." -msgstr "" - -#: ../../library/gzip.rst:112 -msgid "" -"Calling a :class:`GzipFile` object's :meth:`!close` method does not close " -"*fileobj*, since you might wish to append more material after the compressed " -"data. This also allows you to pass an :class:`io.BytesIO` object opened for " -"writing as *fileobj*, and retrieve the resulting memory buffer using the :" -"class:`io.BytesIO` object's :meth:`~io.BytesIO.getvalue` method." -msgstr "" - -#: ../../library/gzip.rst:118 -msgid "" -":class:`GzipFile` supports the :class:`io.BufferedIOBase` interface, " -"including iteration and the :keyword:`with` statement. Only the :meth:`~io." -"IOBase.truncate` method isn't implemented." -msgstr "" - -#: ../../library/gzip.rst:122 -msgid ":class:`GzipFile` also provides the following method and attribute:" -msgstr ":class:`GzipFile` 也提供了以下的方法和屬性：" - -#: ../../library/gzip.rst:126 -msgid "" -"Read *n* uncompressed bytes without advancing the file position. The number " -"of bytes returned may be more or less than requested." -msgstr "" - -#: ../../library/gzip.rst:129 -msgid "" -"While calling :meth:`peek` does not change the file position of the :class:" -"`GzipFile`, it may change the position of the underlying file object (e.g. " -"if the :class:`GzipFile` was constructed with the *fileobj* parameter)." -msgstr "" - -#: ../../library/gzip.rst:138 -msgid "``'rb'`` for reading and ``'wb'`` for writing." -msgstr "``'rb'`` 用於讀取、``'wb'`` 用於寫入。" - -#: ../../library/gzip.rst:140 -msgid "In previous versions it was an integer ``1`` or ``2``." -msgstr "在先前版本中它是整數 ``1`` 或 ``2``。" - -#: ../../library/gzip.rst:145 -msgid "" -"When decompressing, this attribute is set to the last timestamp in the most " -"recently read header. It is an integer, holding the number of seconds since " -"the Unix epoch (00:00:00 UTC, January 1, 1970). The initial value before " -"reading any headers is ``None``." -msgstr "" - -#: ../../library/gzip.rst:152 -msgid "" -"The path to the gzip file on disk, as a :class:`str` or :class:`bytes`. " -"Equivalent to the output of :func:`os.fspath` on the original input path, " -"with no other normalization, resolution or expansion." -msgstr "" - -#: ../../library/gzip.rst:156 -msgid "" -"Support for the :keyword:`with` statement was added, along with the *mtime* " -"constructor argument and :attr:`mtime` attribute." -msgstr "" - -#: ../../library/gzip.rst:160 -msgid "Support for zero-padded and unseekable files was added." -msgstr "" - -#: ../../library/gzip.rst:163 -msgid "The :meth:`io.BufferedIOBase.read1` method is now implemented." -msgstr ":meth:`io.BufferedIOBase.read1` 方法現在已有實作。" - -#: ../../library/gzip.rst:166 -msgid "Added support for the ``'x'`` and ``'xb'`` modes." -msgstr "新增 ``'x'`` 和 ``'xb'`` 模式的支援。" - -#: ../../library/gzip.rst:169 -msgid "" -"Added support for writing arbitrary :term:`bytes-like objects `. The :meth:`~io.BufferedIOBase.read` method now accepts an argument " -"of ``None``." -msgstr "" - -#: ../../library/gzip.rst:178 -msgid "" -"Opening :class:`GzipFile` for writing without specifying the *mode* argument " -"is deprecated." -msgstr "" - -#: ../../library/gzip.rst:182 -msgid "" -"Remove the ``filename`` attribute, use the :attr:`~GzipFile.name` attribute " -"instead." -msgstr "" - -#: ../../library/gzip.rst:189 -msgid "" -"Compress the *data*, returning a :class:`bytes` object containing the " -"compressed data. *compresslevel* and *mtime* have the same meaning as in " -"the :class:`GzipFile` constructor above, but *mtime* defaults to 0 for " -"reproducible output." -msgstr "" - -#: ../../library/gzip.rst:195 -msgid "Added the *mtime* parameter for reproducible output." -msgstr "" - -#: ../../library/gzip.rst:197 -msgid "" -"Speed is improved by compressing all data at once instead of in a streamed " -"fashion. Calls with *mtime* set to ``0`` are delegated to :func:`zlib." -"compress` for better speed. In this situation the output may contain a gzip " -"header \"OS\" byte value other than 255 \"unknown\" as supplied by the " -"underlying zlib implementation." -msgstr "" - -#: ../../library/gzip.rst:204 -msgid "" -"The gzip header OS byte is guaranteed to be set to 255 when this function is " -"used as was the case in 3.10 and earlier." -msgstr "" - -#: ../../library/gzip.rst:207 -msgid "" -"The *mtime* parameter now defaults to 0 for reproducible output. For the " -"previous behaviour of using the current time, pass ``None`` to *mtime*." -msgstr "" - -#: ../../library/gzip.rst:214 -msgid "" -"Decompress the *data*, returning a :class:`bytes` object containing the " -"uncompressed data. This function is capable of decompressing multi-member " -"gzip data (multiple gzip blocks concatenated together). When the data is " -"certain to contain only one member the :func:`zlib.decompress` function with " -"*wbits* set to 31 is faster." -msgstr "" - -#: ../../library/gzip.rst:221 -msgid "" -"Speed is improved by decompressing members at once in memory instead of in a " -"streamed fashion." -msgstr "" - -#: ../../library/gzip.rst:228 -msgid "Examples of usage" -msgstr "用法範例" - -#: ../../library/gzip.rst:230 -msgid "Example of how to read a compressed file::" -msgstr "如何讀取壓縮檔案的範例： ::" - -#: ../../library/gzip.rst:232 -msgid "" -"import gzip\n" -"with gzip.open('/home/joe/file.txt.gz', 'rb') as f:\n" -" file_content = f.read()" -msgstr "" -"import gzip\n" -"with gzip.open('/home/joe/file.txt.gz', 'rb') as f:\n" -" file_content = f.read()" - -#: ../../library/gzip.rst:236 -msgid "Example of how to create a compressed GZIP file::" -msgstr "如何建立一個壓縮的 GZIP 檔案的範例： ::" - -#: ../../library/gzip.rst:238 -msgid "" -"import gzip\n" -"content = b\"Lots of content here\"\n" -"with gzip.open('/home/joe/file.txt.gz', 'wb') as f:\n" -" f.write(content)" -msgstr "" -"import gzip\n" -"content = b\"Lots of content here\"\n" -"with gzip.open('/home/joe/file.txt.gz', 'wb') as f:\n" -" f.write(content)" - -#: ../../library/gzip.rst:243 -msgid "Example of how to GZIP compress an existing file::" -msgstr "如何壓縮一個已存在的檔案的範例： ::" - -#: ../../library/gzip.rst:245 -msgid "" -"import gzip\n" -"import shutil\n" -"with open('/home/joe/file.txt', 'rb') as f_in:\n" -" with gzip.open('/home/joe/file.txt.gz', 'wb') as f_out:\n" -" shutil.copyfileobj(f_in, f_out)" -msgstr "" -"import gzip\n" -"import shutil\n" -"with open('/home/joe/file.txt', 'rb') as f_in:\n" -" with gzip.open('/home/joe/file.txt.gz', 'wb') as f_out:\n" -" shutil.copyfileobj(f_in, f_out)" - -#: ../../library/gzip.rst:251 -msgid "Example of how to GZIP compress a binary string::" -msgstr "如何壓縮一個二進位字串的範例： ::" - -#: ../../library/gzip.rst:253 -msgid "" -"import gzip\n" -"s_in = b\"Lots of content here\"\n" -"s_out = gzip.compress(s_in)" -msgstr "" -"import gzip\n" -"s_in = b\"Lots of content here\"\n" -"s_out = gzip.compress(s_in)" - -#: ../../library/gzip.rst:259 -msgid "Module :mod:`zlib`" -msgstr ":mod:`zlib` 模組" - -#: ../../library/gzip.rst:260 -msgid "" -"The basic data compression module needed to support the :program:`gzip` file " -"format." -msgstr "" - -#: ../../library/gzip.rst:263 -msgid "" -"In case gzip (de)compression is a bottleneck, the `python-isal`_ package " -"speeds up (de)compression with a mostly compatible API." -msgstr "" - -#: ../../library/gzip.rst:273 -msgid "Command-line interface" -msgstr "命令列介面" - -#: ../../library/gzip.rst:275 -msgid "" -"The :mod:`gzip` module provides a simple command line interface to compress " -"or decompress files." -msgstr "" - -#: ../../library/gzip.rst:278 -msgid "Once executed the :mod:`gzip` module keeps the input file(s)." -msgstr "" - -#: ../../library/gzip.rst:282 -msgid "" -"Add a new command line interface with a usage. By default, when you will " -"execute the CLI, the default compression level is 6." -msgstr "" - -#: ../../library/gzip.rst:286 -msgid "Command-line options" -msgstr "命令列選項" - -#: ../../library/gzip.rst:290 -msgid "If *file* is not specified, read from :data:`sys.stdin`." -msgstr "如果未指定 *file*，則從 :data:`sys.stdin` 讀取。" - -#: ../../library/gzip.rst:294 -msgid "Indicates the fastest compression method (less compression)." -msgstr "" - -#: ../../library/gzip.rst:298 -msgid "Indicates the slowest compression method (best compression)." -msgstr "" - -#: ../../library/gzip.rst:302 -msgid "Decompress the given file." -msgstr "解壓縮指定的檔案。" - -#: ../../library/gzip.rst:306 -msgid "Show the help message." -msgstr "顯示幫助訊息。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Adrian Liaw , 2018 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-18 00:15+0000\n" +"PO-Revision-Date: 2018-05-23 16:03+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/gzip.rst:2 +msgid ":mod:`!gzip` --- Support for :program:`gzip` files" +msgstr ":mod:`!gzip` --- :program:`gzip` 檔案的支援" + +#: ../../library/gzip.rst:7 +msgid "**Source code:** :source:`Lib/gzip.py`" +msgstr "**原始碼：**\\ :source:`Lib/gzip.py`" + +#: ../../library/gzip.rst:11 +msgid "" +"This module provides a simple interface to compress and decompress files " +"just like the GNU programs :program:`gzip` and :program:`gunzip` would." +msgstr "" + +#: ../../includes/optional-module.rst:1 +msgid "" +"This is an :term:`optional module`. If it is missing from your copy of " +"CPython, look for documentation from your distributor (that is, whoever " +"provided Python to you). If you are the distributor, see :ref:`optional-" +"module-requirements`." +msgstr "" + +#: ../../library/gzip.rst:16 +msgid "The data compression is provided by the :mod:`zlib` module." +msgstr "" + +#: ../../library/gzip.rst:18 +msgid "" +"The :mod:`gzip` module provides the :class:`GzipFile` class, as well as the :" +"func:`.open`, :func:`compress` and :func:`decompress` convenience functions. " +"The :class:`GzipFile` class reads and writes :program:`gzip`\\ -format " +"files, automatically compressing or decompressing the data so that it looks " +"like an ordinary :term:`file object`." +msgstr "" + +#: ../../library/gzip.rst:24 +msgid "" +"Note that additional file formats which can be decompressed by the :program:" +"`gzip` and :program:`gunzip` programs, such as those produced by :program:" +"`compress` and :program:`pack`, are not supported by this module." +msgstr "" + +#: ../../library/gzip.rst:28 +msgid "The module defines the following items:" +msgstr "此模組定義了以下項目：" + +#: ../../library/gzip.rst:33 +msgid "" +"Open a gzip-compressed file in binary or text mode, returning a :term:`file " +"object`." +msgstr "" + +#: ../../library/gzip.rst:36 +msgid "" +"The *filename* argument can be an actual filename (a :class:`str` or :class:" +"`bytes` object), or an existing file object to read from or write to." +msgstr "" + +#: ../../library/gzip.rst:39 +msgid "" +"The *mode* argument can be any of ``'r'``, ``'rb'``, ``'a'``, ``'ab'``, " +"``'w'``, ``'wb'``, ``'x'`` or ``'xb'`` for binary mode, or ``'rt'``, " +"``'at'``, ``'wt'``, or ``'xt'`` for text mode. The default is ``'rb'``." +msgstr "" + +#: ../../library/gzip.rst:43 +msgid "" +"The *compresslevel* argument is an integer from 0 to 9, as for the :class:" +"`GzipFile` constructor." +msgstr "" + +#: ../../library/gzip.rst:46 +msgid "" +"For binary mode, this function is equivalent to the :class:`GzipFile` " +"constructor: ``GzipFile(filename, mode, compresslevel)``. In this case, the " +"*encoding*, *errors* and *newline* arguments must not be provided." +msgstr "" + +#: ../../library/gzip.rst:50 +msgid "" +"For text mode, a :class:`GzipFile` object is created, and wrapped in an :" +"class:`io.TextIOWrapper` instance with the specified encoding, error " +"handling behavior, and line ending(s)." +msgstr "" + +#: ../../library/gzip.rst:54 +msgid "" +"Added support for *filename* being a file object, support for text mode, and " +"the *encoding*, *errors* and *newline* arguments." +msgstr "" + +#: ../../library/gzip.rst:58 +msgid "Added support for the ``'x'``, ``'xb'`` and ``'xt'`` modes." +msgstr "新增 ``'x'``、``'xb'`` 和 ``'xt'`` 模式的支援。" + +#: ../../library/gzip.rst:61 ../../library/gzip.rst:175 +msgid "Accepts a :term:`path-like object`." +msgstr "接受\\ :term:`類路徑物件 `。" + +#: ../../library/gzip.rst:66 +msgid "" +"An exception raised for invalid gzip files. It inherits from :exc:" +"`OSError`. :exc:`EOFError` and :exc:`zlib.error` can also be raised for " +"invalid gzip files." +msgstr "" + +#: ../../library/gzip.rst:74 +msgid "" +"Constructor for the :class:`GzipFile` class, which simulates most of the " +"methods of a :term:`file object`, with the exception of the :meth:`~io." +"IOBase.truncate` method. At least one of *fileobj* and *filename* must be " +"given a non-trivial value." +msgstr "" + +#: ../../library/gzip.rst:79 +msgid "" +"The new class instance is based on *fileobj*, which can be a regular file, " +"an :class:`io.BytesIO` object, or any other object which simulates a file. " +"It defaults to ``None``, in which case *filename* is opened to provide a " +"file object." +msgstr "" + +#: ../../library/gzip.rst:84 +msgid "" +"When *fileobj* is not ``None``, the *filename* argument is only used to be " +"included in the :program:`gzip` file header, which may include the original " +"filename of the uncompressed file. It defaults to the filename of " +"*fileobj*, if discernible; otherwise, it defaults to the empty string, and " +"in this case the original filename is not included in the header." +msgstr "" + +#: ../../library/gzip.rst:90 +msgid "" +"The *mode* argument can be any of ``'r'``, ``'rb'``, ``'a'``, ``'ab'``, " +"``'w'``, ``'wb'``, ``'x'``, or ``'xb'``, depending on whether the file will " +"be read or written. The default is the mode of *fileobj* if discernible; " +"otherwise, the default is ``'rb'``. In future Python releases the mode of " +"*fileobj* will not be used. It is better to always specify *mode* for " +"writing." +msgstr "" + +#: ../../library/gzip.rst:96 +msgid "" +"Note that the file is always opened in binary mode. To open a compressed " +"file in text mode, use :func:`.open` (or wrap your :class:`GzipFile` with " +"an :class:`io.TextIOWrapper`)." +msgstr "" + +#: ../../library/gzip.rst:100 +msgid "" +"The *compresslevel* argument is an integer from ``0`` to ``9`` controlling " +"the level of compression; ``1`` is fastest and produces the least " +"compression, and ``9`` is slowest and produces the most compression. ``0`` " +"is no compression. The default is ``9``." +msgstr "" + +#: ../../library/gzip.rst:105 +msgid "" +"The optional *mtime* argument is the timestamp requested by gzip. The time " +"is in Unix format, i.e., seconds since 00:00:00 UTC, January 1, 1970. If " +"*mtime* is omitted or ``None``, the current time is used. Use *mtime* = 0 to " +"generate a compressed stream that does not depend on creation time." +msgstr "" + +#: ../../library/gzip.rst:110 +msgid "" +"See below for the :attr:`mtime` attribute that is set when decompressing." +msgstr "" + +#: ../../library/gzip.rst:112 +msgid "" +"Calling a :class:`GzipFile` object's :meth:`!close` method does not close " +"*fileobj*, since you might wish to append more material after the compressed " +"data. This also allows you to pass an :class:`io.BytesIO` object opened for " +"writing as *fileobj*, and retrieve the resulting memory buffer using the :" +"class:`io.BytesIO` object's :meth:`~io.BytesIO.getvalue` method." +msgstr "" + +#: ../../library/gzip.rst:118 +msgid "" +":class:`GzipFile` supports the :class:`io.BufferedIOBase` interface, " +"including iteration and the :keyword:`with` statement. Only the :meth:`~io." +"IOBase.truncate` method isn't implemented." +msgstr "" + +#: ../../library/gzip.rst:122 +msgid ":class:`GzipFile` also provides the following method and attribute:" +msgstr ":class:`GzipFile` 也提供了以下的方法和屬性：" + +#: ../../library/gzip.rst:126 +msgid "" +"Read *n* uncompressed bytes without advancing the file position. The number " +"of bytes returned may be more or less than requested." +msgstr "" + +#: ../../library/gzip.rst:129 +msgid "" +"While calling :meth:`peek` does not change the file position of the :class:" +"`GzipFile`, it may change the position of the underlying file object (e.g. " +"if the :class:`GzipFile` was constructed with the *fileobj* parameter)." +msgstr "" + +#: ../../library/gzip.rst:138 +msgid "``'rb'`` for reading and ``'wb'`` for writing." +msgstr "``'rb'`` 用於讀取、``'wb'`` 用於寫入。" + +#: ../../library/gzip.rst:140 +msgid "In previous versions it was an integer ``1`` or ``2``." +msgstr "在先前版本中它是整數 ``1`` 或 ``2``。" + +#: ../../library/gzip.rst:145 +msgid "" +"When decompressing, this attribute is set to the last timestamp in the most " +"recently read header. It is an integer, holding the number of seconds since " +"the Unix epoch (00:00:00 UTC, January 1, 1970). The initial value before " +"reading any headers is ``None``." +msgstr "" + +#: ../../library/gzip.rst:152 +msgid "" +"The path to the gzip file on disk, as a :class:`str` or :class:`bytes`. " +"Equivalent to the output of :func:`os.fspath` on the original input path, " +"with no other normalization, resolution or expansion." +msgstr "" + +#: ../../library/gzip.rst:156 +msgid "" +"Support for the :keyword:`with` statement was added, along with the *mtime* " +"constructor argument and :attr:`mtime` attribute." +msgstr "" + +#: ../../library/gzip.rst:160 +msgid "Support for zero-padded and unseekable files was added." +msgstr "" + +#: ../../library/gzip.rst:163 +msgid "The :meth:`io.BufferedIOBase.read1` method is now implemented." +msgstr ":meth:`io.BufferedIOBase.read1` 方法現在已有實作。" + +#: ../../library/gzip.rst:166 +msgid "Added support for the ``'x'`` and ``'xb'`` modes." +msgstr "新增 ``'x'`` 和 ``'xb'`` 模式的支援。" + +#: ../../library/gzip.rst:169 +msgid "" +"Added support for writing arbitrary :term:`bytes-like objects `. The :meth:`~io.BufferedIOBase.read` method now accepts an argument " +"of ``None``." +msgstr "" + +#: ../../library/gzip.rst:178 +msgid "" +"Opening :class:`GzipFile` for writing without specifying the *mode* argument " +"is deprecated." +msgstr "" + +#: ../../library/gzip.rst:182 +msgid "" +"Remove the ``filename`` attribute, use the :attr:`~GzipFile.name` attribute " +"instead." +msgstr "" + +#: ../../library/gzip.rst:189 +msgid "" +"Compress the *data*, returning a :class:`bytes` object containing the " +"compressed data. *compresslevel* and *mtime* have the same meaning as in " +"the :class:`GzipFile` constructor above, but *mtime* defaults to 0 for " +"reproducible output." +msgstr "" + +#: ../../library/gzip.rst:195 +msgid "Added the *mtime* parameter for reproducible output." +msgstr "" + +#: ../../library/gzip.rst:197 +msgid "" +"Speed is improved by compressing all data at once instead of in a streamed " +"fashion. Calls with *mtime* set to ``0`` are delegated to :func:`zlib." +"compress` for better speed. In this situation the output may contain a gzip " +"header \"OS\" byte value other than 255 \"unknown\" as supplied by the " +"underlying zlib implementation." +msgstr "" + +#: ../../library/gzip.rst:204 +msgid "" +"The gzip header OS byte is guaranteed to be set to 255 when this function is " +"used as was the case in 3.10 and earlier." +msgstr "" + +#: ../../library/gzip.rst:207 +msgid "" +"The *mtime* parameter now defaults to 0 for reproducible output. For the " +"previous behaviour of using the current time, pass ``None`` to *mtime*." +msgstr "" + +#: ../../library/gzip.rst:214 +msgid "" +"Decompress the *data*, returning a :class:`bytes` object containing the " +"uncompressed data. This function is capable of decompressing multi-member " +"gzip data (multiple gzip blocks concatenated together). When the data is " +"certain to contain only one member the :func:`zlib.decompress` function with " +"*wbits* set to 31 is faster." +msgstr "" + +#: ../../library/gzip.rst:221 +msgid "" +"Speed is improved by decompressing members at once in memory instead of in a " +"streamed fashion." +msgstr "" + +#: ../../library/gzip.rst:228 +msgid "Examples of usage" +msgstr "用法範例" + +#: ../../library/gzip.rst:230 +msgid "Example of how to read a compressed file::" +msgstr "如何讀取壓縮檔案的範例： ::" + +#: ../../library/gzip.rst:232 +msgid "" +"import gzip\n" +"with gzip.open('/home/joe/file.txt.gz', 'rb') as f:\n" +" file_content = f.read()" +msgstr "" +"import gzip\n" +"with gzip.open('/home/joe/file.txt.gz', 'rb') as f:\n" +" file_content = f.read()" + +#: ../../library/gzip.rst:236 +msgid "Example of how to create a compressed GZIP file::" +msgstr "如何建立一個壓縮的 GZIP 檔案的範例： ::" + +#: ../../library/gzip.rst:238 +msgid "" +"import gzip\n" +"content = b\"Lots of content here\"\n" +"with gzip.open('/home/joe/file.txt.gz', 'wb') as f:\n" +" f.write(content)" +msgstr "" +"import gzip\n" +"content = b\"Lots of content here\"\n" +"with gzip.open('/home/joe/file.txt.gz', 'wb') as f:\n" +" f.write(content)" + +#: ../../library/gzip.rst:243 +msgid "Example of how to GZIP compress an existing file::" +msgstr "如何壓縮一個已存在的檔案的範例： ::" + +#: ../../library/gzip.rst:245 +msgid "" +"import gzip\n" +"import shutil\n" +"with open('/home/joe/file.txt', 'rb') as f_in:\n" +" with gzip.open('/home/joe/file.txt.gz', 'wb') as f_out:\n" +" shutil.copyfileobj(f_in, f_out)" +msgstr "" +"import gzip\n" +"import shutil\n" +"with open('/home/joe/file.txt', 'rb') as f_in:\n" +" with gzip.open('/home/joe/file.txt.gz', 'wb') as f_out:\n" +" shutil.copyfileobj(f_in, f_out)" + +#: ../../library/gzip.rst:251 +msgid "Example of how to GZIP compress a binary string::" +msgstr "如何壓縮一個二進位字串的範例： ::" + +#: ../../library/gzip.rst:253 +msgid "" +"import gzip\n" +"s_in = b\"Lots of content here\"\n" +"s_out = gzip.compress(s_in)" +msgstr "" +"import gzip\n" +"s_in = b\"Lots of content here\"\n" +"s_out = gzip.compress(s_in)" + +#: ../../library/gzip.rst:259 +msgid "Module :mod:`zlib`" +msgstr ":mod:`zlib` 模組" + +#: ../../library/gzip.rst:260 +msgid "" +"The basic data compression module needed to support the :program:`gzip` file " +"format." +msgstr "" + +#: ../../library/gzip.rst:263 +msgid "" +"In case gzip (de)compression is a bottleneck, the `python-isal`_ package " +"speeds up (de)compression with a mostly compatible API." +msgstr "" + +#: ../../library/gzip.rst:273 +msgid "Command-line interface" +msgstr "命令列介面" + +#: ../../library/gzip.rst:275 +msgid "" +"The :mod:`gzip` module provides a simple command line interface to compress " +"or decompress files." +msgstr "" + +#: ../../library/gzip.rst:278 +msgid "Once executed the :mod:`gzip` module keeps the input file(s)." +msgstr "" + +#: ../../library/gzip.rst:282 +msgid "" +"Add a new command line interface with a usage. By default, when you will " +"execute the CLI, the default compression level is 6." +msgstr "" + +#: ../../library/gzip.rst:286 +msgid "Command-line options" +msgstr "命令列選項" + +#: ../../library/gzip.rst:290 +msgid "If *file* is not specified, read from :data:`sys.stdin`." +msgstr "如果未指定 *file*，則從 :data:`sys.stdin` 讀取。" + +#: ../../library/gzip.rst:294 +msgid "Indicates the fastest compression method (less compression)." +msgstr "" + +#: ../../library/gzip.rst:298 +msgid "Indicates the slowest compression method (best compression)." +msgstr "" + +#: ../../library/gzip.rst:302 +msgid "Decompress the given file." +msgstr "解壓縮指定的檔案。" + +#: ../../library/gzip.rst:306 +msgid "Show the help message." +msgstr "顯示幫助訊息。" diff --git a/library/hashlib.po b/library/hashlib.po index 91b8e4ca77..1a3be5fdcd 100644 --- a/library/hashlib.po +++ b/library/hashlib.po @@ -1,1331 +1,1331 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Matt Wang , 2024 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-10-03 00:13+0000\n" -"PO-Revision-Date: 2024-05-11 16:03+0800\n" -"Last-Translator: Matt Wang \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" -"X-Generator: Poedit 3.3.2\n" - -#: ../../library/hashlib.rst:2 -msgid ":mod:`!hashlib` --- Secure hashes and message digests" -msgstr ":mod:`!hashlib` --- 安全雜湊與訊息摘要" - -#: ../../library/hashlib.rst:10 -msgid "**Source code:** :source:`Lib/hashlib.py`" -msgstr "**原始碼：**\\ :source:`Lib/hashlib.py`" - -#: ../../library/hashlib.rst:23 -msgid "" -"This module implements a common interface to many different hash algorithms. " -"Included are the FIPS secure hash algorithms SHA224, SHA256, SHA384, SHA512, " -"(defined in `the FIPS 180-4 standard`_), the SHA-3 series (defined in `the " -"FIPS 202 standard`_) as well as the legacy algorithms SHA1 (`formerly part " -"of FIPS`_) and the MD5 algorithm (defined in internet :rfc:`1321`)." -msgstr "" -"該模組實作了許多不同雜湊演算法的通用介面，其中包括 FIPS 安全雜湊演算法 SHA1、" -"SHA224、SHA256、SHA384、SHA512（定義於 `FIPS 180-4 標準 `_）、SHA-3 系列（定義於 `FIPS 202 標準 `_）以及遺留的 SHA1 演算法（`先前為 FIPS 的一部分 `_）和 MD5 演算法（定義於網際網路 :rfc:`1321`）。" - -#: ../../library/hashlib.rst:31 -msgid "" -"If you want the adler32 or crc32 hash functions, they are available in the :" -"mod:`zlib` module." -msgstr "" -"如果你需要 adler32 或 crc32 雜湊函式，可以在 :mod:`zlib` 模組中找到它們。" - -#: ../../library/hashlib.rst:38 -msgid "Hash algorithms" -msgstr "雜湊演算法" - -#: ../../library/hashlib.rst:40 -msgid "" -"There is one constructor method named for each type of :dfn:`hash`. All " -"return a hash object with the same simple interface. For example: use :func:" -"`sha256` to create a SHA-256 hash object. You can now feed this object with :" -"term:`bytes-like objects ` (normally :class:`bytes`) " -"using the :meth:`update` method. At any point you can ask it " -"for the :dfn:`digest` of the concatenation of the data fed to it so far " -"using the :meth:`digest()` or :meth:`hexdigest()` methods." -msgstr "" -"每種種類的 :dfn:`hash` 都有一個以其命名的建構函式方法。全部都會回傳具有相同簡" -"單介面的雜湊物件。例如：可使用 :func:`sha256` 來建立 SHA-256 雜湊物件。現在你" -"可以使用 :meth:`update ` 方法向此物件提供\\ :term:`類位元組物件 " -"(bytes-like objects) `\\ （通常是 :class:`bytes`）。在任何" -"時候，你都可以使用 :meth:`digest() ` 或 :meth:`hexdigest() " -"` 方法來要求它提供迄今為止傳遞給它的資料串聯的\\ :dfn:`摘要 " -"(digest)`。" - -#: ../../library/hashlib.rst:48 -msgid "" -"To allow multithreading, the Python :term:`GIL` is released while computing " -"a hash supplied more than 2047 bytes of data at once in its constructor or :" -"meth:`.update` method." -msgstr "" -"為了允許多執行緒 (multithreading)，Python :term:`GIL` 被釋放，同時在其建構函" -"式或 :meth:`.update` 方法中計算一次提供超過 2047 位元組資料的雜" -"湊值。" - -#: ../../library/hashlib.rst:55 -msgid "" -"Constructors for hash algorithms that are always present in this module are :" -"func:`sha1`, :func:`sha224`, :func:`sha256`, :func:`sha384`, :func:" -"`sha512`, :func:`sha3_224`, :func:`sha3_256`, :func:`sha3_384`, :func:" -"`sha3_512`, :func:`shake_128`, :func:`shake_256`, :func:`blake2b`, and :func:" -"`blake2s`. :func:`md5` is normally available as well, though it may be " -"missing or blocked if you are using a rare \"FIPS compliant\" build of " -"Python. These correspond to :data:`algorithms_guaranteed`." -msgstr "" -"此模組中始終存在的雜湊演算法之建構函式有 :func:`sha1`、:func:`sha224`、:func:" -"`sha256`、:func:`sha384`、:func:`sha512`、:func:`sha3_224`、:func:" -"`sha3_256`、:func:`sha3_384`、:func:`sha3_512`、:func:`shake_128`、:func:" -"`shake_256`、:func:`blake2b` 和 :func:`blake2s`。:func:`md5` 通常也可用，但如" -"果你使用罕見的「符合 FIPS (FIPS compliant)」的 Python 建置版本，它可能不存在" -"或者不被允許使用。以上會對應到 :data:`algorithms_guaranteed`。" - -#: ../../library/hashlib.rst:63 -msgid "" -"Additional algorithms may also be available if your Python distribution's :" -"mod:`hashlib` was linked against a build of OpenSSL that provides others. " -"Others *are not guaranteed available* on all installations and will only be " -"accessible by name via :func:`new`. See :data:`algorithms_available`." -msgstr "" -"如果你的 Python 發行版的 :mod:`hashlib` 與提供其他演算法的 OpenSSL 版本鏈結，" -"也可能有其他演算法可用。其他則\\ *不保證可用*\\ 於在所有安裝上，並且只能以名" -"稱來透過 :func:`new` 存取。請參閱 :data:`algorithms_available`。" - -#: ../../library/hashlib.rst:70 -msgid "" -"Some algorithms have known hash collision weaknesses (including MD5 and " -"SHA1). Refer to `Attacks on cryptographic hash algorithms`_ and the `hashlib-" -"seealso`_ section at the end of this document." -msgstr "" -"某些演算法具有已知的雜湊碰撞 (hash collision) 弱點（包括 MD5 和 SHA1）。請參" -"閱 `Attacks on cryptographic hash algorithms`_ 和本文件後面的\\ `也參考 " -"`_\\ 部分。" - -#: ../../library/hashlib.rst:74 -msgid "" -"SHA3 (Keccak) and SHAKE constructors :func:`sha3_224`, :func:`sha3_256`, :" -"func:`sha3_384`, :func:`sha3_512`, :func:`shake_128`, :func:`shake_256` were " -"added. :func:`blake2b` and :func:`blake2s` were added." -msgstr "" -"新增了 SHA3 (Keccak) 和 SHAKE 建構函式 :func:`sha3_224`、:func:`sha3_256`、:" -"func:`sha3_384`、:func:`sha3_512`、:func:`shake_128`、:func:`shake_256`。也新" -"增了 :func:`blake2b` 和 :func:`blake2s`。" - -#: ../../library/hashlib.rst:82 -msgid "" -"All hashlib constructors take a keyword-only argument *usedforsecurity* with " -"default value ``True``. A false value allows the use of insecure and blocked " -"hashing algorithms in restricted environments. ``False`` indicates that the " -"hashing algorithm is not used in a security context, e.g. as a non-" -"cryptographic one-way compression function." -msgstr "" -"所有 hashlib 建構函式都採用一個僅限關鍵字引數 (keyword-only argument) " -"*usedforsecurity*，其預設值為 ``True``。False 值則會允許在受限環境中使用不安" -"全 (insecure) 和阻塞的 (blocked) 雜湊演算法。``False`` 表示雜湊演算法未在安全" -"情境中使用，例如作為一種非加密用途的單向壓縮函式。" - -#: ../../library/hashlib.rst:89 -msgid "Hashlib now uses SHA3 and SHAKE from OpenSSL if it provides it." -msgstr "Hashlib 現在使用 OpenSSL 中的 SHA3 和 SHAKE（如果有提供的話）。" - -#: ../../library/hashlib.rst:92 -msgid "" -"For any of the MD5, SHA1, SHA2, or SHA3 algorithms that the linked OpenSSL " -"does not provide we fall back to a verified implementation from the `HACL\\* " -"project`_." -msgstr "" -"對於鏈結之 OpenSSL 未提供的任何 MD5、SHA1、SHA2 或 SHA3 演算法，我們會回退使" -"用 `HACL\\* 專案 `_\\ 中經過驗證的實作。" - -#: ../../library/hashlib.rst:98 -msgid "Usage" -msgstr "用法" - -#: ../../library/hashlib.rst:100 -msgid "" -"To obtain the digest of the byte string ``b\"Nobody inspects the spammish " -"repetition\"``::" -msgstr "" -"取得位元組字串 ``b\"Nobody inspects the spammish repetition\"`` 的摘要： ::" - -#: ../../library/hashlib.rst:103 -msgid "" -">>> import hashlib\n" -">>> m = hashlib.sha256()\n" -">>> m.update(b\"Nobody inspects\")\n" -">>> m.update(b\" the spammish repetition\")\n" -">>> m.digest()\n" -"b'\\x03\\x1e\\xdd}Ae\\x15\\x93\\xc5\\xfe\\\\" -"\\x00o\\xa5u+7\\xfd\\xdf\\xf7\\xbcN\\x84:" -"\\xa6\\xaf\\x0c\\x95\\x0fK\\x94\\x06'\n" -">>> m.hexdigest()\n" -"'031edd7d41651593c5fe5c006fa5752b37fddff7bc4e843aa6af0c950f4b9406'" -msgstr "" -">>> import hashlib\n" -">>> m = hashlib.sha256()\n" -">>> m.update(b\"Nobody inspects\")\n" -">>> m.update(b\" the spammish repetition\")\n" -">>> m.digest()\n" -"b'\\x03\\x1e\\xdd}Ae\\x15\\x93\\xc5\\xfe\\\\" -"\\x00o\\xa5u+7\\xfd\\xdf\\xf7\\xbcN\\x84:" -"\\xa6\\xaf\\x0c\\x95\\x0fK\\x94\\x06'\n" -">>> m.hexdigest()\n" -"'031edd7d41651593c5fe5c006fa5752b37fddff7bc4e843aa6af0c950f4b9406'" - -#: ../../library/hashlib.rst:112 -msgid "More condensed:" -msgstr "更濃縮：" - -#: ../../library/hashlib.rst:118 -msgid "Constructors" -msgstr "建構函式" - -#: ../../library/hashlib.rst:122 -msgid "" -"Is a generic constructor that takes the string *name* of the desired " -"algorithm as its first parameter. It also exists to allow access to the " -"above listed hashes as well as any other algorithms that your OpenSSL " -"library may offer." -msgstr "" -"是一個通用建構函式，它將目標演算法的字串 *name* 作為其第一個參數。它還允許使" -"用者取得上面列出的雜湊值以及 OpenSSL 函式庫可能提供的任何其他演算法。" - -#: ../../library/hashlib.rst:127 -msgid "Using :func:`new` with an algorithm name:" -msgstr "使用 :func:`new` 和演算法名稱：" - -#: ../../library/hashlib.rst:146 -msgid "" -"Named constructors such as these are faster than passing an algorithm name " -"to :func:`new`." -msgstr "諸如此類的附名建構函式比將演算法名稱傳遞給 :func:`new` 更快。" - -#: ../../library/hashlib.rst:150 -msgid "Attributes" -msgstr "屬性" - -#: ../../library/hashlib.rst:152 -msgid "Hashlib provides the following constant module attributes:" -msgstr "Hashlib 提供以下常數模組屬性：" - -#: ../../library/hashlib.rst:156 -msgid "" -"A set containing the names of the hash algorithms guaranteed to be supported " -"by this module on all platforms. Note that 'md5' is in this list despite " -"some upstream vendors offering an odd \"FIPS compliant\" Python build that " -"excludes it." -msgstr "" -"包含所有平台上該模組保證支援的雜湊演算法名稱的集合。請注意，'md5' 有出現在此" -"列表中，儘管有一些上游供應商提供了奇怪的「符合 FIPS (FIPS compliant)」的 " -"Python 建置，並將其排除在外。" - -#: ../../library/hashlib.rst:165 -msgid "" -"A set containing the names of the hash algorithms that are available in the " -"running Python interpreter. These names will be recognized when passed to :" -"func:`new`. :attr:`algorithms_guaranteed` will always be a subset. The " -"same algorithm may appear multiple times in this set under different names " -"(thanks to OpenSSL)." -msgstr "" -"包含正在運行的 Python 直譯器中可用的雜湊演算法名稱的集合。這些名稱在傳遞給 :" -"func:`new` 時將被識別。:attr:`algorithms_guaranteed` 都會是它的一個子集。相同" -"的演算法可能會以不同的名稱多次出現在該集合中（多虧了 OpenSSL）。" - -#: ../../library/hashlib.rst:174 -msgid "Hash Objects" -msgstr "雜湊物件" - -#: ../../library/hashlib.rst:176 -msgid "" -"The following values are provided as constant attributes of the hash objects " -"returned by the constructors:" -msgstr "以下的值皆為建構函式回傳之雜湊物件的常數屬性：" - -#: ../../library/hashlib.rst:181 -msgid "The size of the resulting hash in bytes." -msgstr "生成雜湊的大小（以位元組為單位）。" - -#: ../../library/hashlib.rst:185 -msgid "The internal block size of the hash algorithm in bytes." -msgstr "雜湊演算法的內部區塊大小（以位元組為單位）。" - -#: ../../library/hashlib.rst:187 -msgid "A hash object has the following attributes:" -msgstr "雜湊物件具有以下屬性：" - -#: ../../library/hashlib.rst:191 -msgid "" -"The canonical name of this hash, always lowercase and always suitable as a " -"parameter to :func:`new` to create another hash of this type." -msgstr "" -"該雜湊的規範名稱，都會是小寫，且都會適合作為 :func:`new` 的參數以建立此型別的" -"另一個雜湊。" - -#: ../../library/hashlib.rst:194 -msgid "" -"The name attribute has been present in CPython since its inception, but " -"until Python 3.4 was not formally specified, so may not exist on some " -"platforms." -msgstr "" -"name 屬性自 CPython 誕生以來就存在於其中，但直到 Python 3.4 才正式確立，因此" -"在某些平台上可能不存在。" - -#: ../../library/hashlib.rst:199 -msgid "A hash object has the following methods:" -msgstr "雜湊物件具有以下方法：" - -#: ../../library/hashlib.rst:204 -msgid "" -"Update the hash object with the :term:`bytes-like object`. Repeated calls " -"are equivalent to a single call with the concatenation of all the arguments: " -"``m.update(a); m.update(b)`` is equivalent to ``m.update(a+b)``." -msgstr "" -"使用\\ :term:`類位元組物件 `\\ 來更新雜湊物件。重複呼叫相" -"當於連接所有引數的單一呼叫：``m.update(a); m.update(b)`` 等價於 ``m." -"update(a+b)``。" - -#: ../../library/hashlib.rst:212 -msgid "" -"Return the digest of the data passed to the :meth:`update` method so far. " -"This is a bytes object of size :attr:`digest_size` which may contain bytes " -"in the whole range from 0 to 255." -msgstr "" -"回傳目前有傳遞給 :meth:`update` 方法的資料之摘要。這是一個大小為 :attr:" -"`digest_size` 的位元組物件，它可能包含從 0 到 255 的整個範圍內的位元組。" - -#: ../../library/hashlib.rst:219 -msgid "" -"Like :meth:`digest` except the digest is returned as a string object of " -"double length, containing only hexadecimal digits. This may be used to " -"exchange the value safely in email or other non-binary environments." -msgstr "" -"與 :meth:`digest` 類似，只不過摘要會是作為雙倍長度的字串物件回傳，僅包含十六" -"進位數字。這可用於在電子郵件或其他非二進位環境中安全地交換值。" - -#: ../../library/hashlib.rst:226 -msgid "" -"Return a copy (\"clone\") of the hash object. This can be used to " -"efficiently compute the digests of data sharing a common initial substring." -msgstr "" -"回傳雜湊物件的副本（「複製 (clone)」），這可用於高效率地計算出共享同一初始子" -"字串的資料之摘要。" - -#: ../../library/hashlib.rst:231 -msgid "SHAKE variable length digests" -msgstr "SHAKE 可變長度摘要" - -#: ../../library/hashlib.rst:236 -msgid "" -"The :func:`shake_128` and :func:`shake_256` algorithms provide variable " -"length digests with length_in_bits//2 up to 128 or 256 bits of security. As " -"such, their digest methods require a length. Maximum length is not limited " -"by the SHAKE algorithm." -msgstr "" -":func:`shake_128` 和 :func:`shake_256` 演算法提供了可變長度摘要，其 " -"length_in_bits//2 最高為 128 或 256 位元安全性。因此，他們的摘要方法會需要長" -"度。最大長度不受 SHAKE 演算法限制。" - -#: ../../library/hashlib.rst:243 -msgid "" -"Return the digest of the data passed to the :meth:`~hash.update` method so " -"far. This is a bytes object of size *length* which may contain bytes in the " -"whole range from 0 to 255." -msgstr "" -"回傳目前有傳遞給 :meth:`~hash.update` 方法的資料之摘要。這是一個大小為 " -"*length* 的位元組物件，可能包含從 0 到 255 的整個範圍內的位元組。" - -#: ../../library/hashlib.rst:250 -msgid "" -"Like :meth:`digest` except the digest is returned as a string object of " -"double length, containing only hexadecimal digits. This may be used to " -"exchange the value in email or other non-binary environments." -msgstr "" -"與 :meth:`digest` 類似，只不過摘要作為雙倍長度的字串物件回傳，僅包含十六進位" -"數字。這可用於交換電子郵件或其他非二進位環境中的值。" - -#: ../../library/hashlib.rst:254 -msgid "Example use:" -msgstr "範例：" - -#: ../../library/hashlib.rst:261 -msgid "File hashing" -msgstr "檔案雜湊" - -#: ../../library/hashlib.rst:263 -msgid "" -"The hashlib module provides a helper function for efficient hashing of a " -"file or file-like object." -msgstr "" -"hashlib 模組提供了一個輔助函式，用於對檔案或類檔案物件 (file-like object) 進" -"行有效率的雜湊。" - -#: ../../library/hashlib.rst:268 -msgid "" -"Return a digest object that has been updated with contents of file object." -msgstr "回傳已用檔案物件內容更新的摘要物件。" - -#: ../../library/hashlib.rst:270 -msgid "" -"*fileobj* must be a file-like object opened for reading in binary mode. It " -"accepts file objects from builtin :func:`open`, :class:`~io.BytesIO` " -"instances, SocketIO objects from :meth:`socket.socket.makefile`, and " -"similar. *fileobj* must be opened in blocking mode, otherwise a :exc:" -"`BlockingIOError` may be raised." -msgstr "" -"*fileobj* 必須是以二進位模式讀取的類檔案物件。它接受來自內建 :func:`open` 的" -"檔案物件、:class:`~io.BytesIO` 實例、來自 :meth:`socket.socket.makefile` 的 " -"SocketIO 物件等。*fileobj* 必須以阻塞模式開啟，否則可能會引發 :exc:" -"`BlockingIOError`。" - -#: ../../library/hashlib.rst:276 -msgid "" -"The function may bypass Python's I/O and use the file descriptor from :meth:" -"`~io.IOBase.fileno` directly. *fileobj* must be assumed to be in an unknown " -"state after this function returns or raises. It is up to the caller to close " -"*fileobj*." -msgstr "" -"該函式可以繞過 Python 的 I/O 並直接使用 :meth:`~io.IOBase.fileno` 中的檔案描" -"述器 (file descriptor)。在此函式回傳或引發後，必須假定 *fileobj* 處於未知狀" -"態 (unknown state)。由呼叫者決定是否關閉 *fileobj*。" - -#: ../../library/hashlib.rst:281 -msgid "" -"*digest* must either be a hash algorithm name as a *str*, a hash " -"constructor, or a callable that returns a hash object." -msgstr "" -"*digest* 必須是名稱作為 *str* 的雜湊演算法、雜湊建構函式或會回傳雜湊物件的可" -"呼叫函式。" - -#: ../../library/hashlib.rst:284 -msgid "Example:" -msgstr "範例：" - -#: ../../library/hashlib.rst:305 -msgid "" -"Now raises a :exc:`BlockingIOError` if the file is opened in non-blocking " -"mode. Previously, spurious null bytes were added to the digest." -msgstr "" - -#: ../../library/hashlib.rst:311 -msgid "Key derivation" -msgstr "密鑰的生成" - -#: ../../library/hashlib.rst:313 -msgid "" -"Key derivation and key stretching algorithms are designed for secure " -"password hashing. Naive algorithms such as ``sha1(password)`` are not " -"resistant against brute-force attacks. A good password hashing function must " -"be tunable, slow, and include a `salt `_." -msgstr "" -"密鑰生成 (key derivation) 和密鑰延伸 (key stretching) 演算法專為安全密碼雜湊" -"而設計。像是 ``sha1(password)`` 這樣過於單純的演算法無法抵抗暴力攻擊。一個好" -"的密碼雜湊函式必須是可調校的 (tunable)、緩慢的，並且有包含 `salt（鹽） " -"`_。" - -#: ../../library/hashlib.rst:321 -msgid "" -"The function provides PKCS#5 password-based key derivation function 2. It " -"uses HMAC as pseudorandom function." -msgstr "" -"該函式提供基於密碼的 PKCS#5 密鑰生成函式 2。它使用 HMAC 作為偽隨機函式 " -"(pseudorandom function)。" - -#: ../../library/hashlib.rst:324 -msgid "" -"The string *hash_name* is the desired name of the hash digest algorithm for " -"HMAC, e.g. 'sha1' or 'sha256'. *password* and *salt* are interpreted as " -"buffers of bytes. Applications and libraries should limit *password* to a " -"sensible length (e.g. 1024). *salt* should be about 16 or more bytes from a " -"proper source, e.g. :func:`os.urandom`." -msgstr "" -"字串 *hash_name* 是 HMAC 的雜湊摘要演算法所需的名稱，例如 ``sha1`` 或 " -"``sha256``。*password* 和 *salt* 被直譯為位元組緩衝區。應用程式和函式庫應為 " -"*password* 設下合理的長度限制（例如 1024）。*salt* 應該是來自適當來源（例如 :" -"func:`os.urandom`）且大約 16 或更多位元組。" - -#: ../../library/hashlib.rst:330 -msgid "" -"The number of *iterations* should be chosen based on the hash algorithm and " -"computing power. As of 2022, hundreds of thousands of iterations of SHA-256 " -"are suggested. For rationale as to why and how to choose what is best for " -"your application, read *Appendix A.2.2* of NIST-SP-800-132_. The answers on " -"the `stackexchange pbkdf2 iterations question`_ explain in detail." -msgstr "" -"應根據雜湊演算法和計算能力選擇 *iterations* 次數。截至 2022 年，建議進行數十" -"萬次 SHA-256 疊代。有關為什麼以及如何選擇最適合你的應用程式的基本原理，請閱" -"讀 NIST-SP-800-132_ 的 *Appendix A.2.2*。`stackexchange pbkdf2 疊代問題`_\\ " -"上的答案有詳細解釋。" - -#: ../../library/hashlib.rst:336 -msgid "" -"*dklen* is the length of the derived key in bytes. If *dklen* is ``None`` " -"then the digest size of the hash algorithm *hash_name* is used, e.g. 64 for " -"SHA-512." -msgstr "" -"*dklen* 是生成的密鑰長度。如果 *dklen* 為 ``None``，則會使用雜湊演算法 " -"*hash_name* 的摘要大小，例如 SHA-512 為 64。" - -#: ../../library/hashlib.rst:345 -msgid "Function only available when Python is compiled with OpenSSL." -msgstr "僅當有使用 OpenSSL 編譯 Python 時該函式才可用。" - -#: ../../library/hashlib.rst:349 -msgid "" -"Function now only available when Python is built with OpenSSL. The slow pure " -"Python implementation has been removed." -msgstr "" -"該函式現在僅在有使用 OpenSSL 建置 Python 時可用。緩慢的純 Python 實作已被刪" -"除。" - -#: ../../library/hashlib.rst:355 -msgid "" -"The function provides scrypt password-based key derivation function as " -"defined in :rfc:`7914`." -msgstr "該函式提供（如 :rfc:`7914` 中所定義的）scrypt 基於密碼的密鑰衍生函式。" - -#: ../../library/hashlib.rst:358 -msgid "" -"*password* and *salt* must be :term:`bytes-like objects `. Applications and libraries should limit *password* to a sensible " -"length (e.g. 1024). *salt* should be about 16 or more bytes from a proper " -"source, e.g. :func:`os.urandom`." -msgstr "" -"*password* 和 *salt* 必須是\\ :term:`類位元組物件 `。應用" -"程式和函式庫應為 *password* 設下合理的長度限制（例如 1024）。*salt* 應該是來" -"自適當來源（例如 :func:`os.urandom`）且大約 16 或更多位元組。" - -#: ../../library/hashlib.rst:363 -msgid "" -"*n* is the CPU/Memory cost factor, *r* the block size, *p* parallelization " -"factor and *maxmem* limits memory (OpenSSL 1.1.0 defaults to 32 MiB). " -"*dklen* is the length of the derived key in bytes." -msgstr "" -"*n* 是 CPU/記憶體開銷係數、*r* 是區塊大小、*p* 為平行化係數、*maxmem* 為記憶" -"體限制（OpenSSL 1.1.0 預設為 32 MiB）。*dklen* 是生成密鑰的長度。" - -#: ../../library/hashlib.rst:373 -msgid "BLAKE2" -msgstr "BLAKE2" - -#: ../../library/hashlib.rst:380 -msgid "" -"BLAKE2_ is a cryptographic hash function defined in :rfc:`7693` that comes " -"in two flavors:" -msgstr "BLAKE2_ 是在 :rfc:`7693` 中定義的加密雜湊函式，有兩種類型：" - -#: ../../library/hashlib.rst:383 -msgid "" -"**BLAKE2b**, optimized for 64-bit platforms and produces digests of any size " -"between 1 and 64 bytes," -msgstr "" -"**BLAKE2b**，針對 64 位元平台進行了最佳化，可生成 1 到 64 位元組之間任意大小" -"的摘要，" - -#: ../../library/hashlib.rst:386 -msgid "" -"**BLAKE2s**, optimized for 8- to 32-bit platforms and produces digests of " -"any size between 1 and 32 bytes." -msgstr "" -"**BLAKE2s**，針對 8 至 32 位元平台進行了最佳化，可生成 1 至 32 位元組之間任意" -"大小的摘要。" - -#: ../../library/hashlib.rst:389 -msgid "" -"BLAKE2 supports **keyed mode** (a faster and simpler replacement for HMAC_), " -"**salted hashing**, **personalization**, and **tree hashing**." -msgstr "" -"BLAKE2 支援\\ **密鑰模式 (keyed mode)** （更快、更簡單的 HMAC_ 替代品）、**加" -"鹽雜湊 (salted hashing)**、**個人化**\\ 和\\ **樹狀雜湊**。" - -#: ../../library/hashlib.rst:392 -msgid "" -"Hash objects from this module follow the API of standard library's :mod:" -"`hashlib` objects." -msgstr "該模組中的雜湊物件遵循標準函式庫的 :mod:`hashlib` 物件 API。" - -#: ../../library/hashlib.rst:397 -msgid "Creating hash objects" -msgstr "建立雜湊物件" - -#: ../../library/hashlib.rst:399 -msgid "New hash objects are created by calling constructor functions:" -msgstr "新的雜湊物件是透過呼叫建構函式建立的：" - -#: ../../library/hashlib.rst:413 -msgid "" -"These functions return the corresponding hash objects for calculating " -"BLAKE2b or BLAKE2s. They optionally take these general parameters:" -msgstr "" -"這些函式回傳相應的雜湊物件以計算 BLAKE2b 或 BLAKE2s。他們可以選擇採用這些通用" -"參數：" - -#: ../../library/hashlib.rst:416 -msgid "" -"*data*: initial chunk of data to hash, which must be :term:`bytes-like " -"object`. It can be passed only as positional argument." -msgstr "" -"*data*：要雜湊的初始資料塊 (data chunk)，它必須是\\ :term:`類位元組物件 " -"`。它只能作為位置引數傳遞。" - -#: ../../library/hashlib.rst:419 -msgid "*digest_size*: size of output digest in bytes." -msgstr "*digest_size*：輸出摘要的大小（以位元組為單位）。" - -#: ../../library/hashlib.rst:421 -msgid "" -"*key*: key for keyed hashing (up to 64 bytes for BLAKE2b, up to 32 bytes for " -"BLAKE2s)." -msgstr "" -"*key*：用於密鑰雜湊的密鑰（BLAKE2b 最多 64 位元組、BLAKE2s 最多 32 位元組）。" - -#: ../../library/hashlib.rst:424 -msgid "" -"*salt*: salt for randomized hashing (up to 16 bytes for BLAKE2b, up to 8 " -"bytes for BLAKE2s)." -msgstr "" -"*salt*：用於隨機雜湊的鹽（BLAKE2b 最多 16 個位元組、BLAKE2s 最多 8 個位元" -"組）。" - -#: ../../library/hashlib.rst:427 -msgid "" -"*person*: personalization string (up to 16 bytes for BLAKE2b, up to 8 bytes " -"for BLAKE2s)." -msgstr "" -"*person*：個人化字串（BLAKE2b 最多 16 個位元組、BLAKE2s 最多 8 個位元組）。" - -#: ../../library/hashlib.rst:430 -msgid "The following table shows limits for general parameters (in bytes):" -msgstr "下表顯示了一般參數的限制（以位元組為單位）：" - -#: ../../library/hashlib.rst:433 -msgid "Hash" -msgstr "雜湊" - -#: ../../library/hashlib.rst:433 -msgid "digest_size" -msgstr "digest_size" - -#: ../../library/hashlib.rst:433 -msgid "len(key)" -msgstr "len(key)" - -#: ../../library/hashlib.rst:433 -msgid "len(salt)" -msgstr "len(salt)" - -#: ../../library/hashlib.rst:433 -msgid "len(person)" -msgstr "len(person)" - -#: ../../library/hashlib.rst:435 -msgid "BLAKE2b" -msgstr "BLAKE2b" - -#: ../../library/hashlib.rst:435 -msgid "64" -msgstr "64" - -#: ../../library/hashlib.rst:435 -msgid "16" -msgstr "16" - -#: ../../library/hashlib.rst:436 -msgid "BLAKE2s" -msgstr "BLAKE2s" - -#: ../../library/hashlib.rst:436 -msgid "32" -msgstr "32" - -#: ../../library/hashlib.rst:436 -msgid "8" -msgstr "8" - -#: ../../library/hashlib.rst:441 -msgid "" -"BLAKE2 specification defines constant lengths for salt and personalization " -"parameters, however, for convenience, this implementation accepts byte " -"strings of any size up to the specified length. If the length of the " -"parameter is less than specified, it is padded with zeros, thus, for " -"example, ``b'salt'`` and ``b'salt\\x00'`` is the same value. (This is not " -"the case for *key*.)" -msgstr "" -"BLAKE2 規範定義了鹽和個人化參數的恆定長度，但為了方便起見，此實作接受任意大小" -"的位元組字串，最多可達指定長度。如果參數的長度小於指定的長度，則用零補滿，所" -"以像是 ``b'salt`` 和 ``b'salt\\x00`` 是相同的值。（但 *key* 的情況並非如" -"此。）" - -#: ../../library/hashlib.rst:448 -msgid "These sizes are available as module `constants`_ described below." -msgstr "這些大小可作為模組\\ `常數 `_\\ 使用，如下所述。" - -#: ../../library/hashlib.rst:450 -msgid "" -"Constructor functions also accept the following tree hashing parameters:" -msgstr "建構函式還接受以下樹狀雜湊參數：" - -#: ../../library/hashlib.rst:452 -msgid "*fanout*: fanout (0 to 255, 0 if unlimited, 1 in sequential mode)." -msgstr "*fanout*：扇出（0 到 255，如果無限制則為 0、順序模式為 1）。" - -#: ../../library/hashlib.rst:454 -msgid "" -"*depth*: maximal depth of tree (1 to 255, 255 if unlimited, 1 in sequential " -"mode)." -msgstr "*depth*：樹的最大深度（1 到 255，如果無限制則為 255、順序模式為 1）。" - -#: ../../library/hashlib.rst:457 -msgid "" -"*leaf_size*: maximal byte length of leaf (0 to ``2**32-1``, 0 if unlimited " -"or in sequential mode)." -msgstr "" -"*leaf_size*：葉的最大位元組長度（0 到 ``2**32-1``，如果無限制或處於順序模式則" -"為 0）。" - -#: ../../library/hashlib.rst:460 -msgid "" -"*node_offset*: node offset (0 to ``2**64-1`` for BLAKE2b, 0 to ``2**48-1`` " -"for BLAKE2s, 0 for the first, leftmost, leaf, or in sequential mode)." -msgstr "" -"*node_offset*：節點偏移量（BLAKE2b 為 0 到 ``2**64-1``，BLAKE2s 為 0 到 " -"``2**48-1``，0 表示第一個、最左邊、葉子或在順序模式下）。" - -#: ../../library/hashlib.rst:463 -msgid "" -"*node_depth*: node depth (0 to 255, 0 for leaves, or in sequential mode)." -msgstr "*node_depth*：節點深度（0 到 255，葉為 0，或在順序模式下）。" - -#: ../../library/hashlib.rst:465 -msgid "" -"*inner_size*: inner digest size (0 to 64 for BLAKE2b, 0 to 32 for BLAKE2s, 0 " -"in sequential mode)." -msgstr "" -"*inner_size*：內部摘要大小（BLAKE2b 為 0 到 64，BLAKE2s 為 0 到 32，順序模式" -"為 0）。" - -#: ../../library/hashlib.rst:468 -msgid "" -"*last_node*: boolean indicating whether the processed node is the last one " -"(``False`` for sequential mode)." -msgstr "" -"*last_node*：布林值，代表處理的節點是否為最後一個（``False`` 代表順序模式）。" - -#: ../../library/hashlib.rst:471 -msgid "Explanation of tree mode parameters." -msgstr "樹狀模式參數說明。" - -#: ../../library/hashlib.rst:475 -msgid "" -"See section 2.10 in `BLAKE2 specification `_ for comprehensive review of tree hashing." -msgstr "" -"關於樹狀雜湊的綜合回顧，請參閱 `BLAKE2 規範 `_\\ 中的第 2.10 節。" - -#: ../../library/hashlib.rst:481 -msgid "Constants" -msgstr "常數" - -#: ../../library/hashlib.rst:486 -msgid "Salt length (maximum length accepted by constructors)." -msgstr "鹽長度（建構函式接受的最大長度）。" - -#: ../../library/hashlib.rst:492 -msgid "" -"Personalization string length (maximum length accepted by constructors)." -msgstr "個人化字串長度（建構函式接受的最大長度）。" - -#: ../../library/hashlib.rst:498 -msgid "Maximum key size." -msgstr "最大密鑰大小。" - -#: ../../library/hashlib.rst:504 -msgid "Maximum digest size that the hash function can output." -msgstr "雜湊函式可以輸出的最大摘要大小。" - -#: ../../library/hashlib.rst:508 -msgid "Examples" -msgstr "範例" - -#: ../../library/hashlib.rst:511 -msgid "Simple hashing" -msgstr "簡單雜湊" - -#: ../../library/hashlib.rst:513 -msgid "" -"To calculate hash of some data, you should first construct a hash object by " -"calling the appropriate constructor function (:func:`blake2b` or :func:" -"`blake2s`), then update it with the data by calling :meth:`~hash.update` on " -"the object, and, finally, get the digest out of the object by calling :meth:" -"`~hash.digest` (or :meth:`~hash.hexdigest` for hex-encoded string)." -msgstr "" -"要計算某些資料的雜湊值，你應該首先透過呼叫適當的建構函式（:func:`blake2b` " -"或 :func:`blake2s`）以建構一個雜湊物件，然後透過於物件呼叫 :meth:`~hash." -"update` 來以資料對它更新，最後透過呼叫 :meth:`~hash.digest`\\ （或對於十六進" -"位編碼字串則為 :meth:`~hash.hexdigest`）從物件中獲得摘要。" - -#: ../../library/hashlib.rst:526 -msgid "" -"As a shortcut, you can pass the first chunk of data to update directly to " -"the constructor as the positional argument:" -msgstr "" -"作為一個快捷方式，你可以將要更新的第一個資料塊作為位置引數直接傳遞給建構函" -"式：" - -#: ../../library/hashlib.rst:533 -msgid "" -"You can call :meth:`hash.update` as many times as you need to iteratively " -"update the hash:" -msgstr "你可以根據需求來多次呼叫 :meth:`hash.update` 以疊代更新雜湊：" - -#: ../../library/hashlib.rst:547 -msgid "Using different digest sizes" -msgstr "使用不同的摘要大小" - -#: ../../library/hashlib.rst:549 -msgid "" -"BLAKE2 has configurable size of digests up to 64 bytes for BLAKE2b and up to " -"32 bytes for BLAKE2s. For example, to replace SHA-1 with BLAKE2b without " -"changing the size of output, we can tell BLAKE2b to produce 20-byte digests:" -msgstr "" -"BLAKE2 有可調整的摘要大小，BLAKE2b 最多為 64 位元組，BLAKE2s 最多為 32 位元" -"組。例如，要在不改變輸出大小的情況下用 BLAKE2b 替換 SHA-1，我們可以指定 " -"BLAKE2b 生成 20 位元組的摘要：" - -#: ../../library/hashlib.rst:563 -msgid "" -"Hash objects with different digest sizes have completely different outputs " -"(shorter hashes are *not* prefixes of longer hashes); BLAKE2b and BLAKE2s " -"produce different outputs even if the output length is the same:" -msgstr "" -"具有不同摘要大小的雜湊物件具有完全不同的輸出（較短的雜湊值\\ *不是*\\ 較長雜" -"湊值的前綴）；即使輸出長度相同，BLAKE2b 和 BLAKE2s 也會產生不同的輸出：" - -#: ../../library/hashlib.rst:579 -msgid "Keyed hashing" -msgstr "密鑰雜湊 (Keyed hashing)" - -#: ../../library/hashlib.rst:581 -msgid "" -"Keyed hashing can be used for authentication as a faster and simpler " -"replacement for `Hash-based message authentication code `_ (HMAC). BLAKE2 can be securely used in prefix-MAC " -"mode thanks to the indifferentiability property inherited from BLAKE." -msgstr "" -"密鑰雜湊可用於身份驗證，作為\\ `基於雜湊的訊息驗證碼 (Hash-based message " -"authentication code) `_ (HMAC) 的更快、" -"更簡單的替代方案。由於繼承自 BLAKE 的不可微特性 (indifferentiability " -"property)，BLAKE2 可以安全地用於 prefix-MAC 模式。" - -#: ../../library/hashlib.rst:587 -msgid "" -"This example shows how to get a (hex-encoded) 128-bit authentication code " -"for message ``b'message data'`` with key ``b'pseudorandom key'``::" -msgstr "" -"此範例示範了如何使用密鑰 ``b'pseudorandom key'`` 取得訊息 ``b'message " -"data'`` 的（十六進位編碼）128 位元驗證碼： ::" - -#: ../../library/hashlib.rst:590 -msgid "" -">>> from hashlib import blake2b\n" -">>> h = blake2b(key=b'pseudorandom key', digest_size=16)\n" -">>> h.update(b'message data')\n" -">>> h.hexdigest()\n" -"'3d363ff7401e02026f4a4687d4863ced'" -msgstr "" -">>> from hashlib import blake2b\n" -">>> h = blake2b(key=b'pseudorandom key', digest_size=16)\n" -">>> h.update(b'message data')\n" -">>> h.hexdigest()\n" -"'3d363ff7401e02026f4a4687d4863ced'" - -#: ../../library/hashlib.rst:597 -msgid "" -"As a practical example, a web application can symmetrically sign cookies " -"sent to users and later verify them to make sure they weren't tampered with::" -msgstr "" -"舉一個實際的例子，網頁應用程式可以對發送給使用者的 cookie 進行對稱簽名 " -"(symmetrically sign)，然後驗證它們以確保它們沒有被篡改： ::" - -#: ../../library/hashlib.rst:600 -msgid "" -">>> from hashlib import blake2b\n" -">>> from hmac import compare_digest\n" -">>>\n" -">>> SECRET_KEY = b'pseudorandomly generated server secret key'\n" -">>> AUTH_SIZE = 16\n" -">>>\n" -">>> def sign(cookie):\n" -"... h = blake2b(digest_size=AUTH_SIZE, key=SECRET_KEY)\n" -"... h.update(cookie)\n" -"... return h.hexdigest().encode('utf-8')\n" -">>>\n" -">>> def verify(cookie, sig):\n" -"... good_sig = sign(cookie)\n" -"... return compare_digest(good_sig, sig)\n" -">>>\n" -">>> cookie = b'user-alice'\n" -">>> sig = sign(cookie)\n" -">>> print(\"{0},{1}\".format(cookie.decode('utf-8'), sig))\n" -"user-alice,b'43b3c982cf697e0c5ab22172d1ca7421'\n" -">>> verify(cookie, sig)\n" -"True\n" -">>> verify(b'user-bob', sig)\n" -"False\n" -">>> verify(cookie, b'0102030405060708090a0b0c0d0e0f00')\n" -"False" -msgstr "" -">>> from hashlib import blake2b\n" -">>> from hmac import compare_digest\n" -">>>\n" -">>> SECRET_KEY = b'pseudorandomly generated server secret key'\n" -">>> AUTH_SIZE = 16\n" -">>>\n" -">>> def sign(cookie):\n" -"... h = blake2b(digest_size=AUTH_SIZE, key=SECRET_KEY)\n" -"... h.update(cookie)\n" -"... return h.hexdigest().encode('utf-8')\n" -">>>\n" -">>> def verify(cookie, sig):\n" -"... good_sig = sign(cookie)\n" -"... return compare_digest(good_sig, sig)\n" -">>>\n" -">>> cookie = b'user-alice'\n" -">>> sig = sign(cookie)\n" -">>> print(\"{0},{1}\".format(cookie.decode('utf-8'), sig))\n" -"user-alice,b'43b3c982cf697e0c5ab22172d1ca7421'\n" -">>> verify(cookie, sig)\n" -"True\n" -">>> verify(b'user-bob', sig)\n" -"False\n" -">>> verify(cookie, b'0102030405060708090a0b0c0d0e0f00')\n" -"False" - -#: ../../library/hashlib.rst:626 -msgid "" -"Even though there's a native keyed hashing mode, BLAKE2 can, of course, be " -"used in HMAC construction with :mod:`hmac` module::" -msgstr "" -"儘管有原生密鑰雜湊模式，BLAKE2 還是可以透過 :mod:`hmac` 模組用於建構 " -"HMAC： ::" - -#: ../../library/hashlib.rst:629 -msgid "" -">>> import hmac, hashlib\n" -">>> m = hmac.new(b'secret key', digestmod=hashlib.blake2s)\n" -">>> m.update(b'message')\n" -">>> m.hexdigest()\n" -"'e3c8102868d28b5ff85fc35dda07329970d1a01e273c37481326fe0c861c8142'" -msgstr "" -">>> import hmac, hashlib\n" -">>> m = hmac.new(b'secret key', digestmod=hashlib.blake2s)\n" -">>> m.update(b'message')\n" -">>> m.hexdigest()\n" -"'e3c8102868d28b5ff85fc35dda07329970d1a01e273c37481326fe0c861c8142'" - -#: ../../library/hashlib.rst:637 -msgid "Randomized hashing" -msgstr "隨機雜湊 (Randomized hashing)" - -#: ../../library/hashlib.rst:639 -msgid "" -"By setting *salt* parameter users can introduce randomization to the hash " -"function. Randomized hashing is useful for protecting against collision " -"attacks on the hash function used in digital signatures." -msgstr "" -"透過設定 *salt* 參數，使用者可以向雜湊函式引入隨機化。隨機雜湊在防止針對數位" -"簽章中雜湊函式的碰撞攻擊 (collision attacks) 非常有用。" - -#: ../../library/hashlib.rst:643 -msgid "" -"Randomized hashing is designed for situations where one party, the message " -"preparer, generates all or part of a message to be signed by a second party, " -"the message signer. If the message preparer is able to find cryptographic " -"hash function collisions (i.e., two messages producing the same hash value), " -"then they might prepare meaningful versions of the message that would " -"produce the same hash value and digital signature, but with different " -"results (e.g., transferring $1,000,000 to an account, rather than $10). " -"Cryptographic hash functions have been designed with collision resistance as " -"a major goal, but the current concentration on attacking cryptographic hash " -"functions may result in a given cryptographic hash function providing less " -"collision resistance than expected. Randomized hashing offers the signer " -"additional protection by reducing the likelihood that a preparer can " -"generate two or more messages that ultimately yield the same hash value " -"during the digital signature generation process --- even if it is practical " -"to find collisions for the hash function. However, the use of randomized " -"hashing may reduce the amount of security provided by a digital signature " -"when all portions of the message are prepared by the signer." -msgstr "" -"隨機雜湊是為這樣的情況而設計的：一方（訊息準備者）生成全部或部分訊息並由另一" -"方（訊息簽名者）簽名。如果訊息準備者能夠發現加密雜湊函式發生碰撞（collision，" -"即兩條訊息產生相同的雜湊值），那麼他們可能會準備有意義的訊息版本，該版本將產" -"生相同的雜湊值和數位簽章，但結果不同（例如，將 $1,000,000 轉入賬戶，而不是 " -"$10）。加密雜湊函式的設計以抗碰撞性為主要目標，但目前對加密雜湊函式攻擊的關注" -"可能會導致給定的加密雜湊函式所提供的抗碰撞性低於預期。隨機雜湊透過降低準備者" -"在數位簽章生成過程中生成最終產生相同雜湊值的兩個或多個訊息的可能性，為簽名者" -"提供額外的保護 —— 即便嘗試去找到雜湊函式碰撞的發生是實際可行的。然而，若訊息" -"的所有部分都是由簽名者所準備好的，使用隨機雜湊可能會降低數位簽章提供的安全" -"性。" - -#: ../../library/hashlib.rst:662 -msgid "" -"(`NIST SP-800-106 \"Randomized Hashing for Digital Signatures\" `_)" -msgstr "" -"（`NIST SP-800-106 「數位簽章的隨機雜湊 (Randomized Hashing for Digital " -"Signatures)」 `_）" - -#: ../../library/hashlib.rst:665 -msgid "" -"In BLAKE2 the salt is processed as a one-time input to the hash function " -"during initialization, rather than as an input to each compression function." -msgstr "" -"在 BLAKE2 中，鹽在初始化期間作為雜湊函式的一次性輸入被處理，而不是作為每個壓" -"縮函式的輸入。" - -#: ../../library/hashlib.rst:670 -msgid "" -"*Salted hashing* (or just hashing) with BLAKE2 or any other general-purpose " -"cryptographic hash function, such as SHA-256, is not suitable for hashing " -"passwords. See `BLAKE2 FAQ `_ for more " -"information." -msgstr "" -"使用 BLAKE2 或任何其他通用加密雜湊函式（例如 SHA-256）的\\ *加鹽雜湊* （或單" -"純雜湊）不適合對密碼進行雜湊處理。有關更多資訊，請參閱 `BLAKE2 FAQ `_ 。" - -#: ../../library/hashlib.rst:693 -msgid "Personalization" -msgstr "個人化" - -#: ../../library/hashlib.rst:695 -msgid "" -"Sometimes it is useful to force hash function to produce different digests " -"for the same input for different purposes. Quoting the authors of the Skein " -"hash function:" -msgstr "" -"有時候強制雜湊函式為不同目的的相同輸入生成不同的摘要是很有用的。引用 Skein 雜" -"湊函式的作者的話：" - -#: ../../library/hashlib.rst:699 -msgid "" -"We recommend that all application designers seriously consider doing this; " -"we have seen many protocols where a hash that is computed in one part of the " -"protocol can be used in an entirely different part because two hash " -"computations were done on similar or related data, and the attacker can " -"force the application to make the hash inputs the same. Personalizing each " -"hash function used in the protocol summarily stops this type of attack." -msgstr "" -"我們建議所有應用程式設計者認真考慮這樣做；我們已經看到許多協定，其中在協定的" -"一個部分中計算的雜湊可以在完全不同的部分中使用，因為兩次雜湊計算是在相似或相" -"關的資料上完成的，並且攻擊者可以強制應用程式將雜湊輸入設為相同的。對協定中使" -"用的每個雜湊函式進行個人化可以立即阻止此類攻擊。" - -#: ../../library/hashlib.rst:706 -msgid "" -"(`The Skein Hash Function Family `_, p. 21)" -msgstr "" -"（`Skein 雜湊函式系列 `_，第 21 頁）" - -#: ../../library/hashlib.rst:710 -msgid "BLAKE2 can be personalized by passing bytes to the *person* argument::" -msgstr "BLAKE2 可以透過將位元組傳遞給 *person* 引數來做個人化： ::" - -#: ../../library/hashlib.rst:712 -msgid "" -">>> from hashlib import blake2b\n" -">>> FILES_HASH_PERSON = b'MyApp Files Hash'\n" -">>> BLOCK_HASH_PERSON = b'MyApp Block Hash'\n" -">>> h = blake2b(digest_size=32, person=FILES_HASH_PERSON)\n" -">>> h.update(b'the same content')\n" -">>> h.hexdigest()\n" -"'20d9cd024d4fb086aae819a1432dd2466de12947831b75c5a30cf2676095d3b4'\n" -">>> h = blake2b(digest_size=32, person=BLOCK_HASH_PERSON)\n" -">>> h.update(b'the same content')\n" -">>> h.hexdigest()\n" -"'cf68fb5761b9c44e7878bfb2c4c9aea52264a80b75005e65619778de59f383a3'" -msgstr "" -">>> from hashlib import blake2b\n" -">>> FILES_HASH_PERSON = b'MyApp Files Hash'\n" -">>> BLOCK_HASH_PERSON = b'MyApp Block Hash'\n" -">>> h = blake2b(digest_size=32, person=FILES_HASH_PERSON)\n" -">>> h.update(b'the same content')\n" -">>> h.hexdigest()\n" -"'20d9cd024d4fb086aae819a1432dd2466de12947831b75c5a30cf2676095d3b4'\n" -">>> h = blake2b(digest_size=32, person=BLOCK_HASH_PERSON)\n" -">>> h.update(b'the same content')\n" -">>> h.hexdigest()\n" -"'cf68fb5761b9c44e7878bfb2c4c9aea52264a80b75005e65619778de59f383a3'" - -#: ../../library/hashlib.rst:724 -msgid "" -"Personalization together with the keyed mode can also be used to derive " -"different keys from a single one." -msgstr "個人化與密鑰模式還可以一起用於從單個密鑰得出不同的密鑰。" - -#: ../../library/hashlib.rst:738 -msgid "Tree mode" -msgstr "樹狀模式" - -#: ../../library/hashlib.rst:740 -msgid "Here's an example of hashing a minimal tree with two leaf nodes::" -msgstr "下面是對具有兩個葉節點的最小樹進行雜湊處理的範例： ::" - -#: ../../library/hashlib.rst:742 -msgid "" -" 10\n" -" / \\\n" -"00 01" -msgstr "" -" 10\n" -" / \\\n" -"00 01" - -#: ../../library/hashlib.rst:746 -msgid "" -"This example uses 64-byte internal digests, and returns the 32-byte final " -"digest::" -msgstr "此範例使用 64-byte 內部摘要，並回傳 32-byte 最終摘要： ::" - -#: ../../library/hashlib.rst:749 -msgid "" -">>> from hashlib import blake2b\n" -">>>\n" -">>> FANOUT = 2\n" -">>> DEPTH = 2\n" -">>> LEAF_SIZE = 4096\n" -">>> INNER_SIZE = 64\n" -">>>\n" -">>> buf = bytearray(6000)\n" -">>>\n" -">>> # Left leaf\n" -"... h00 = blake2b(buf[0:LEAF_SIZE], fanout=FANOUT, depth=DEPTH,\n" -"... leaf_size=LEAF_SIZE, inner_size=INNER_SIZE,\n" -"... node_offset=0, node_depth=0, last_node=False)\n" -">>> # Right leaf\n" -"... h01 = blake2b(buf[LEAF_SIZE:], fanout=FANOUT, depth=DEPTH,\n" -"... leaf_size=LEAF_SIZE, inner_size=INNER_SIZE,\n" -"... node_offset=1, node_depth=0, last_node=True)\n" -">>> # Root node\n" -"... h10 = blake2b(digest_size=32, fanout=FANOUT, depth=DEPTH,\n" -"... leaf_size=LEAF_SIZE, inner_size=INNER_SIZE,\n" -"... node_offset=0, node_depth=1, last_node=True)\n" -">>> h10.update(h00.digest())\n" -">>> h10.update(h01.digest())\n" -">>> h10.hexdigest()\n" -"'3ad2a9b37c6070e374c7a8c508fe20ca86b6ed54e286e93a0318e95e881db5aa'" -msgstr "" -">>> from hashlib import blake2b\n" -">>>\n" -">>> FANOUT = 2\n" -">>> DEPTH = 2\n" -">>> LEAF_SIZE = 4096\n" -">>> INNER_SIZE = 64\n" -">>>\n" -">>> buf = bytearray(6000)\n" -">>>\n" -">>> # Left leaf\n" -"... h00 = blake2b(buf[0:LEAF_SIZE], fanout=FANOUT, depth=DEPTH,\n" -"... leaf_size=LEAF_SIZE, inner_size=INNER_SIZE,\n" -"... node_offset=0, node_depth=0, last_node=False)\n" -">>> # Right leaf\n" -"... h01 = blake2b(buf[LEAF_SIZE:], fanout=FANOUT, depth=DEPTH,\n" -"... leaf_size=LEAF_SIZE, inner_size=INNER_SIZE,\n" -"... node_offset=1, node_depth=0, last_node=True)\n" -">>> # Root node\n" -"... h10 = blake2b(digest_size=32, fanout=FANOUT, depth=DEPTH,\n" -"... leaf_size=LEAF_SIZE, inner_size=INNER_SIZE,\n" -"... node_offset=0, node_depth=1, last_node=True)\n" -">>> h10.update(h00.digest())\n" -">>> h10.update(h01.digest())\n" -">>> h10.hexdigest()\n" -"'3ad2a9b37c6070e374c7a8c508fe20ca86b6ed54e286e93a0318e95e881db5aa'" - -#: ../../library/hashlib.rst:776 -msgid "Credits" -msgstr "製作人員" - -#: ../../library/hashlib.rst:778 -msgid "" -"BLAKE2_ was designed by *Jean-Philippe Aumasson*, *Samuel Neves*, *Zooko " -"Wilcox-O'Hearn*, and *Christian Winnerlein* based on SHA-3_ finalist BLAKE_ " -"created by *Jean-Philippe Aumasson*, *Luca Henzen*, *Willi Meier*, and " -"*Raphael C.-W. Phan*." -msgstr "" -"BLAKE2_ 由 *Jean-Philippe Aumasson*、*Samuel Neves*、*Zooko Wilcox-O'Hearn* " -"和 *Christian Winnerlein* 設計，基於由 *Jean-Philippe Aumasson*、*Luca " -"Henzen*、*Willi Meier* 和 *Raphael C.-W. Phan* 所建立的 SHA-3_ 最終版本 " -"BLAKE_。" - -#: ../../library/hashlib.rst:783 -msgid "" -"It uses core algorithm from ChaCha_ cipher designed by *Daniel J. " -"Bernstein*." -msgstr "它使用 *Daniel J. Bernstein* 設計的 ChaCha_ 密碼的核心演算法。" - -#: ../../library/hashlib.rst:785 -msgid "" -"The stdlib implementation is based on pyblake2_ module. It was written by " -"*Dmitry Chestnykh* based on C implementation written by *Samuel Neves*. The " -"documentation was copied from pyblake2_ and written by *Dmitry Chestnykh*." -msgstr "" -"標準函式庫實作是基於 pyblake2_ 模組。它是由 *Dmitry Chestnykh* 在 *Samuel " -"Neves* 的 C 版本實作為基礎所編寫的。該文件是由 *Dmitry Chestnykh* 編寫並從 " -"pyblake2_ 複製過來的。" - -#: ../../library/hashlib.rst:789 -msgid "The C code was partly rewritten for Python by *Christian Heimes*." -msgstr "*Christian Heimes* 為 Python 重寫了部分 C 程式碼。" - -#: ../../library/hashlib.rst:791 -msgid "" -"The following public domain dedication applies for both C hash function " -"implementation, extension code, and this documentation:" -msgstr "以下公開領域貢獻適用於 C 雜湊函式實作、擴充程式碼和此文件：" - -#: ../../library/hashlib.rst:794 -msgid "" -"To the extent possible under law, the author(s) have dedicated all copyright " -"and related and neighboring rights to this software to the public domain " -"worldwide. This software is distributed without any warranty." -msgstr "" -"在法律允許的範圍內，作者已將該軟體的所有版權以及相關和鄰接權利奉獻給全球的公" -"開領域。該軟體的發布沒有任何授權 (warranty)。" - -#: ../../library/hashlib.rst:798 -msgid "" -"You should have received a copy of the CC0 Public Domain Dedication along " -"with this software. If not, see https://creativecommons.org/publicdomain/" -"zero/1.0/." -msgstr "" -"你應會隨本軟體一起收到一份 CC0 公眾領域貢獻宣告 (CC0 Public Domain " -"Dedication) 的副本。如果沒有，請參閱 https://creativecommons.org/" -"publicdomain/zero/1.0/ 。" - -#: ../../library/hashlib.rst:802 -msgid "" -"The following people have helped with development or contributed their " -"changes to the project and the public domain according to the Creative " -"Commons Public Domain Dedication 1.0 Universal:" -msgstr "" -"以下人員根據創用 CC 通用公眾領域貢獻宣告 1.0 (Creative Commons Public Domain " -"Dedication 1.0 Universal) 於專案和公開領域做出了開發或貢獻：" - -#: ../../library/hashlib.rst:806 -msgid "*Alexandr Sokolovskiy*" -msgstr "*Alexandr Sokolovskiy*" - -#: ../../library/hashlib.rst:827 -msgid "Module :mod:`hmac`" -msgstr ":mod:`hmac` 模組" - -#: ../../library/hashlib.rst:828 -msgid "A module to generate message authentication codes using hashes." -msgstr "使用雜湊生成訊息驗證程式碼的模組。" - -#: ../../library/hashlib.rst:830 -msgid "Module :mod:`base64`" -msgstr ":mod:`base64` 模組" - -#: ../../library/hashlib.rst:831 -msgid "Another way to encode binary hashes for non-binary environments." -msgstr "另一種在非二進位環境中編碼二進位雜湊的方法。" - -#: ../../library/hashlib.rst:833 -msgid "https://nvlpubs.nist.gov/nistpubs/fips/nist.fips.180-4.pdf" -msgstr "https://nvlpubs.nist.gov/nistpubs/fips/nist.fips.180-4.pdf" - -#: ../../library/hashlib.rst:834 -msgid "The FIPS 180-4 publication on Secure Hash Algorithms." -msgstr "有關安全雜湊演算法的 FIPS 180-4 出版物。" - -#: ../../library/hashlib.rst:836 -msgid "https://csrc.nist.gov/pubs/fips/202/final" -msgstr "https://csrc.nist.gov/pubs/fips/202/final" - -#: ../../library/hashlib.rst:837 -msgid "The FIPS 202 publication on the SHA-3 Standard." -msgstr "有關 SHA-3 標準的 FIPS 202 出版物。" - -#: ../../library/hashlib.rst:839 -msgid "https://www.blake2.net/" -msgstr "https://www.blake2.net/" - -#: ../../library/hashlib.rst:840 -msgid "Official BLAKE2 website." -msgstr "BLAKE2 官方網站。" - -#: ../../library/hashlib.rst:842 -msgid "https://en.wikipedia.org/wiki/Cryptographic_hash_function" -msgstr "https://en.wikipedia.org/wiki/Cryptographic_hash_function" - -#: ../../library/hashlib.rst:843 -msgid "" -"Wikipedia article with information on which algorithms have known issues and " -"what that means regarding their use." -msgstr "" -"包含有關哪些演算法存在已知問題以及這些問題對其使用意味著什麼資訊的維基百科文" -"章。" - -#: ../../library/hashlib.rst:846 -msgid "https://www.ietf.org/rfc/rfc8018.txt" -msgstr "https://www.ietf.org/rfc/rfc8018.txt" - -#: ../../library/hashlib.rst:847 -msgid "PKCS #5: Password-Based Cryptography Specification Version 2.1" -msgstr "PKCS #5：基於密碼的加密規範版本 2.1" - -#: ../../library/hashlib.rst:849 -msgid "" -"https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-132.pdf" -msgstr "" -"https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-132.pdf" - -#: ../../library/hashlib.rst:850 -msgid "NIST Recommendation for Password-Based Key Derivation." -msgstr "NIST（美國國家標準技術研究院）針對基於密碼的密鑰衍生的建議。" - -#: ../../library/hashlib.rst:12 -msgid "message digest, MD5" -msgstr "message digest（訊息摘要）、MD5" - -#: ../../library/hashlib.rst:12 -msgid "" -"secure hash algorithm, SHA1, SHA2, SHA224, SHA256, SHA384, SHA512, SHA3, " -"Shake, Blake2" -msgstr "" -"安全雜湊演算法、SHA1、SHA2、SHA224、SHA256、SHA384、SHA512、SHA3、Shake、" -"Blake2" - -#: ../../library/hashlib.rst:53 -msgid "OpenSSL" -msgstr "OpenSSL" - -#: ../../library/hashlib.rst:53 -msgid "(use in module hashlib)" -msgstr "（使用於 hashlib 模組中）" - -#: ../../library/hashlib.rst:377 -msgid "blake2b, blake2s" -msgstr "blake2b, blake2s" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Matt Wang , 2024 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-10-03 00:13+0000\n" +"PO-Revision-Date: 2024-05-11 16:03+0800\n" +"Last-Translator: Matt Wang \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" +"X-Generator: Poedit 3.3.2\n" + +#: ../../library/hashlib.rst:2 +msgid ":mod:`!hashlib` --- Secure hashes and message digests" +msgstr ":mod:`!hashlib` --- 安全雜湊與訊息摘要" + +#: ../../library/hashlib.rst:10 +msgid "**Source code:** :source:`Lib/hashlib.py`" +msgstr "**原始碼：**\\ :source:`Lib/hashlib.py`" + +#: ../../library/hashlib.rst:23 +msgid "" +"This module implements a common interface to many different hash algorithms. " +"Included are the FIPS secure hash algorithms SHA224, SHA256, SHA384, SHA512, " +"(defined in `the FIPS 180-4 standard`_), the SHA-3 series (defined in `the " +"FIPS 202 standard`_) as well as the legacy algorithms SHA1 (`formerly part " +"of FIPS`_) and the MD5 algorithm (defined in internet :rfc:`1321`)." +msgstr "" +"該模組實作了許多不同雜湊演算法的通用介面，其中包括 FIPS 安全雜湊演算法 SHA1、" +"SHA224、SHA256、SHA384、SHA512（定義於 `FIPS 180-4 標準 `_）、SHA-3 系列（定義於 `FIPS 202 標準 `_）以及遺留的 SHA1 演算法（`先前為 FIPS 的一部分 `_）和 MD5 演算法（定義於網際網路 :rfc:`1321`）。" + +#: ../../library/hashlib.rst:31 +msgid "" +"If you want the adler32 or crc32 hash functions, they are available in the :" +"mod:`zlib` module." +msgstr "" +"如果你需要 adler32 或 crc32 雜湊函式，可以在 :mod:`zlib` 模組中找到它們。" + +#: ../../library/hashlib.rst:38 +msgid "Hash algorithms" +msgstr "雜湊演算法" + +#: ../../library/hashlib.rst:40 +msgid "" +"There is one constructor method named for each type of :dfn:`hash`. All " +"return a hash object with the same simple interface. For example: use :func:" +"`sha256` to create a SHA-256 hash object. You can now feed this object with :" +"term:`bytes-like objects ` (normally :class:`bytes`) " +"using the :meth:`update` method. At any point you can ask it " +"for the :dfn:`digest` of the concatenation of the data fed to it so far " +"using the :meth:`digest()` or :meth:`hexdigest()` methods." +msgstr "" +"每種種類的 :dfn:`hash` 都有一個以其命名的建構函式方法。全部都會回傳具有相同簡" +"單介面的雜湊物件。例如：可使用 :func:`sha256` 來建立 SHA-256 雜湊物件。現在你" +"可以使用 :meth:`update ` 方法向此物件提供\\ :term:`類位元組物件 " +"(bytes-like objects) `\\ （通常是 :class:`bytes`）。在任何" +"時候，你都可以使用 :meth:`digest() ` 或 :meth:`hexdigest() " +"` 方法來要求它提供迄今為止傳遞給它的資料串聯的\\ :dfn:`摘要 " +"(digest)`。" + +#: ../../library/hashlib.rst:48 +msgid "" +"To allow multithreading, the Python :term:`GIL` is released while computing " +"a hash supplied more than 2047 bytes of data at once in its constructor or :" +"meth:`.update` method." +msgstr "" +"為了允許多執行緒 (multithreading)，Python :term:`GIL` 被釋放，同時在其建構函" +"式或 :meth:`.update` 方法中計算一次提供超過 2047 位元組資料的雜" +"湊值。" + +#: ../../library/hashlib.rst:55 +msgid "" +"Constructors for hash algorithms that are always present in this module are :" +"func:`sha1`, :func:`sha224`, :func:`sha256`, :func:`sha384`, :func:" +"`sha512`, :func:`sha3_224`, :func:`sha3_256`, :func:`sha3_384`, :func:" +"`sha3_512`, :func:`shake_128`, :func:`shake_256`, :func:`blake2b`, and :func:" +"`blake2s`. :func:`md5` is normally available as well, though it may be " +"missing or blocked if you are using a rare \"FIPS compliant\" build of " +"Python. These correspond to :data:`algorithms_guaranteed`." +msgstr "" +"此模組中始終存在的雜湊演算法之建構函式有 :func:`sha1`、:func:`sha224`、:func:" +"`sha256`、:func:`sha384`、:func:`sha512`、:func:`sha3_224`、:func:" +"`sha3_256`、:func:`sha3_384`、:func:`sha3_512`、:func:`shake_128`、:func:" +"`shake_256`、:func:`blake2b` 和 :func:`blake2s`。:func:`md5` 通常也可用，但如" +"果你使用罕見的「符合 FIPS (FIPS compliant)」的 Python 建置版本，它可能不存在" +"或者不被允許使用。以上會對應到 :data:`algorithms_guaranteed`。" + +#: ../../library/hashlib.rst:63 +msgid "" +"Additional algorithms may also be available if your Python distribution's :" +"mod:`hashlib` was linked against a build of OpenSSL that provides others. " +"Others *are not guaranteed available* on all installations and will only be " +"accessible by name via :func:`new`. See :data:`algorithms_available`." +msgstr "" +"如果你的 Python 發行版的 :mod:`hashlib` 與提供其他演算法的 OpenSSL 版本鏈結，" +"也可能有其他演算法可用。其他則\\ *不保證可用*\\ 於在所有安裝上，並且只能以名" +"稱來透過 :func:`new` 存取。請參閱 :data:`algorithms_available`。" + +#: ../../library/hashlib.rst:70 +msgid "" +"Some algorithms have known hash collision weaknesses (including MD5 and " +"SHA1). Refer to `Attacks on cryptographic hash algorithms`_ and the `hashlib-" +"seealso`_ section at the end of this document." +msgstr "" +"某些演算法具有已知的雜湊碰撞 (hash collision) 弱點（包括 MD5 和 SHA1）。請參" +"閱 `Attacks on cryptographic hash algorithms`_ 和本文件後面的\\ `也參考 " +"`_\\ 部分。" + +#: ../../library/hashlib.rst:74 +msgid "" +"SHA3 (Keccak) and SHAKE constructors :func:`sha3_224`, :func:`sha3_256`, :" +"func:`sha3_384`, :func:`sha3_512`, :func:`shake_128`, :func:`shake_256` were " +"added. :func:`blake2b` and :func:`blake2s` were added." +msgstr "" +"新增了 SHA3 (Keccak) 和 SHAKE 建構函式 :func:`sha3_224`、:func:`sha3_256`、:" +"func:`sha3_384`、:func:`sha3_512`、:func:`shake_128`、:func:`shake_256`。也新" +"增了 :func:`blake2b` 和 :func:`blake2s`。" + +#: ../../library/hashlib.rst:82 +msgid "" +"All hashlib constructors take a keyword-only argument *usedforsecurity* with " +"default value ``True``. A false value allows the use of insecure and blocked " +"hashing algorithms in restricted environments. ``False`` indicates that the " +"hashing algorithm is not used in a security context, e.g. as a non-" +"cryptographic one-way compression function." +msgstr "" +"所有 hashlib 建構函式都採用一個僅限關鍵字引數 (keyword-only argument) " +"*usedforsecurity*，其預設值為 ``True``。False 值則會允許在受限環境中使用不安" +"全 (insecure) 和阻塞的 (blocked) 雜湊演算法。``False`` 表示雜湊演算法未在安全" +"情境中使用，例如作為一種非加密用途的單向壓縮函式。" + +#: ../../library/hashlib.rst:89 +msgid "Hashlib now uses SHA3 and SHAKE from OpenSSL if it provides it." +msgstr "Hashlib 現在使用 OpenSSL 中的 SHA3 和 SHAKE（如果有提供的話）。" + +#: ../../library/hashlib.rst:92 +msgid "" +"For any of the MD5, SHA1, SHA2, or SHA3 algorithms that the linked OpenSSL " +"does not provide we fall back to a verified implementation from the `HACL\\* " +"project`_." +msgstr "" +"對於鏈結之 OpenSSL 未提供的任何 MD5、SHA1、SHA2 或 SHA3 演算法，我們會回退使" +"用 `HACL\\* 專案 `_\\ 中經過驗證的實作。" + +#: ../../library/hashlib.rst:98 +msgid "Usage" +msgstr "用法" + +#: ../../library/hashlib.rst:100 +msgid "" +"To obtain the digest of the byte string ``b\"Nobody inspects the spammish " +"repetition\"``::" +msgstr "" +"取得位元組字串 ``b\"Nobody inspects the spammish repetition\"`` 的摘要： ::" + +#: ../../library/hashlib.rst:103 +msgid "" +">>> import hashlib\n" +">>> m = hashlib.sha256()\n" +">>> m.update(b\"Nobody inspects\")\n" +">>> m.update(b\" the spammish repetition\")\n" +">>> m.digest()\n" +"b'\\x03\\x1e\\xdd}Ae\\x15\\x93\\xc5\\xfe\\\\" +"\\x00o\\xa5u+7\\xfd\\xdf\\xf7\\xbcN\\x84:" +"\\xa6\\xaf\\x0c\\x95\\x0fK\\x94\\x06'\n" +">>> m.hexdigest()\n" +"'031edd7d41651593c5fe5c006fa5752b37fddff7bc4e843aa6af0c950f4b9406'" +msgstr "" +">>> import hashlib\n" +">>> m = hashlib.sha256()\n" +">>> m.update(b\"Nobody inspects\")\n" +">>> m.update(b\" the spammish repetition\")\n" +">>> m.digest()\n" +"b'\\x03\\x1e\\xdd}Ae\\x15\\x93\\xc5\\xfe\\\\" +"\\x00o\\xa5u+7\\xfd\\xdf\\xf7\\xbcN\\x84:" +"\\xa6\\xaf\\x0c\\x95\\x0fK\\x94\\x06'\n" +">>> m.hexdigest()\n" +"'031edd7d41651593c5fe5c006fa5752b37fddff7bc4e843aa6af0c950f4b9406'" + +#: ../../library/hashlib.rst:112 +msgid "More condensed:" +msgstr "更濃縮：" + +#: ../../library/hashlib.rst:118 +msgid "Constructors" +msgstr "建構函式" + +#: ../../library/hashlib.rst:122 +msgid "" +"Is a generic constructor that takes the string *name* of the desired " +"algorithm as its first parameter. It also exists to allow access to the " +"above listed hashes as well as any other algorithms that your OpenSSL " +"library may offer." +msgstr "" +"是一個通用建構函式，它將目標演算法的字串 *name* 作為其第一個參數。它還允許使" +"用者取得上面列出的雜湊值以及 OpenSSL 函式庫可能提供的任何其他演算法。" + +#: ../../library/hashlib.rst:127 +msgid "Using :func:`new` with an algorithm name:" +msgstr "使用 :func:`new` 和演算法名稱：" + +#: ../../library/hashlib.rst:146 +msgid "" +"Named constructors such as these are faster than passing an algorithm name " +"to :func:`new`." +msgstr "諸如此類的附名建構函式比將演算法名稱傳遞給 :func:`new` 更快。" + +#: ../../library/hashlib.rst:150 +msgid "Attributes" +msgstr "屬性" + +#: ../../library/hashlib.rst:152 +msgid "Hashlib provides the following constant module attributes:" +msgstr "Hashlib 提供以下常數模組屬性：" + +#: ../../library/hashlib.rst:156 +msgid "" +"A set containing the names of the hash algorithms guaranteed to be supported " +"by this module on all platforms. Note that 'md5' is in this list despite " +"some upstream vendors offering an odd \"FIPS compliant\" Python build that " +"excludes it." +msgstr "" +"包含所有平台上該模組保證支援的雜湊演算法名稱的集合。請注意，'md5' 有出現在此" +"列表中，儘管有一些上游供應商提供了奇怪的「符合 FIPS (FIPS compliant)」的 " +"Python 建置，並將其排除在外。" + +#: ../../library/hashlib.rst:165 +msgid "" +"A set containing the names of the hash algorithms that are available in the " +"running Python interpreter. These names will be recognized when passed to :" +"func:`new`. :attr:`algorithms_guaranteed` will always be a subset. The " +"same algorithm may appear multiple times in this set under different names " +"(thanks to OpenSSL)." +msgstr "" +"包含正在運行的 Python 直譯器中可用的雜湊演算法名稱的集合。這些名稱在傳遞給 :" +"func:`new` 時將被識別。:attr:`algorithms_guaranteed` 都會是它的一個子集。相同" +"的演算法可能會以不同的名稱多次出現在該集合中（多虧了 OpenSSL）。" + +#: ../../library/hashlib.rst:174 +msgid "Hash Objects" +msgstr "雜湊物件" + +#: ../../library/hashlib.rst:176 +msgid "" +"The following values are provided as constant attributes of the hash objects " +"returned by the constructors:" +msgstr "以下的值皆為建構函式回傳之雜湊物件的常數屬性：" + +#: ../../library/hashlib.rst:181 +msgid "The size of the resulting hash in bytes." +msgstr "生成雜湊的大小（以位元組為單位）。" + +#: ../../library/hashlib.rst:185 +msgid "The internal block size of the hash algorithm in bytes." +msgstr "雜湊演算法的內部區塊大小（以位元組為單位）。" + +#: ../../library/hashlib.rst:187 +msgid "A hash object has the following attributes:" +msgstr "雜湊物件具有以下屬性：" + +#: ../../library/hashlib.rst:191 +msgid "" +"The canonical name of this hash, always lowercase and always suitable as a " +"parameter to :func:`new` to create another hash of this type." +msgstr "" +"該雜湊的規範名稱，都會是小寫，且都會適合作為 :func:`new` 的參數以建立此型別的" +"另一個雜湊。" + +#: ../../library/hashlib.rst:194 +msgid "" +"The name attribute has been present in CPython since its inception, but " +"until Python 3.4 was not formally specified, so may not exist on some " +"platforms." +msgstr "" +"name 屬性自 CPython 誕生以來就存在於其中，但直到 Python 3.4 才正式確立，因此" +"在某些平台上可能不存在。" + +#: ../../library/hashlib.rst:199 +msgid "A hash object has the following methods:" +msgstr "雜湊物件具有以下方法：" + +#: ../../library/hashlib.rst:204 +msgid "" +"Update the hash object with the :term:`bytes-like object`. Repeated calls " +"are equivalent to a single call with the concatenation of all the arguments: " +"``m.update(a); m.update(b)`` is equivalent to ``m.update(a+b)``." +msgstr "" +"使用\\ :term:`類位元組物件 `\\ 來更新雜湊物件。重複呼叫相" +"當於連接所有引數的單一呼叫：``m.update(a); m.update(b)`` 等價於 ``m." +"update(a+b)``。" + +#: ../../library/hashlib.rst:212 +msgid "" +"Return the digest of the data passed to the :meth:`update` method so far. " +"This is a bytes object of size :attr:`digest_size` which may contain bytes " +"in the whole range from 0 to 255." +msgstr "" +"回傳目前有傳遞給 :meth:`update` 方法的資料之摘要。這是一個大小為 :attr:" +"`digest_size` 的位元組物件，它可能包含從 0 到 255 的整個範圍內的位元組。" + +#: ../../library/hashlib.rst:219 +msgid "" +"Like :meth:`digest` except the digest is returned as a string object of " +"double length, containing only hexadecimal digits. This may be used to " +"exchange the value safely in email or other non-binary environments." +msgstr "" +"與 :meth:`digest` 類似，只不過摘要會是作為雙倍長度的字串物件回傳，僅包含十六" +"進位數字。這可用於在電子郵件或其他非二進位環境中安全地交換值。" + +#: ../../library/hashlib.rst:226 +msgid "" +"Return a copy (\"clone\") of the hash object. This can be used to " +"efficiently compute the digests of data sharing a common initial substring." +msgstr "" +"回傳雜湊物件的副本（「複製 (clone)」），這可用於高效率地計算出共享同一初始子" +"字串的資料之摘要。" + +#: ../../library/hashlib.rst:231 +msgid "SHAKE variable length digests" +msgstr "SHAKE 可變長度摘要" + +#: ../../library/hashlib.rst:236 +msgid "" +"The :func:`shake_128` and :func:`shake_256` algorithms provide variable " +"length digests with length_in_bits//2 up to 128 or 256 bits of security. As " +"such, their digest methods require a length. Maximum length is not limited " +"by the SHAKE algorithm." +msgstr "" +":func:`shake_128` 和 :func:`shake_256` 演算法提供了可變長度摘要，其 " +"length_in_bits//2 最高為 128 或 256 位元安全性。因此，他們的摘要方法會需要長" +"度。最大長度不受 SHAKE 演算法限制。" + +#: ../../library/hashlib.rst:243 +msgid "" +"Return the digest of the data passed to the :meth:`~hash.update` method so " +"far. This is a bytes object of size *length* which may contain bytes in the " +"whole range from 0 to 255." +msgstr "" +"回傳目前有傳遞給 :meth:`~hash.update` 方法的資料之摘要。這是一個大小為 " +"*length* 的位元組物件，可能包含從 0 到 255 的整個範圍內的位元組。" + +#: ../../library/hashlib.rst:250 +msgid "" +"Like :meth:`digest` except the digest is returned as a string object of " +"double length, containing only hexadecimal digits. This may be used to " +"exchange the value in email or other non-binary environments." +msgstr "" +"與 :meth:`digest` 類似，只不過摘要作為雙倍長度的字串物件回傳，僅包含十六進位" +"數字。這可用於交換電子郵件或其他非二進位環境中的值。" + +#: ../../library/hashlib.rst:254 +msgid "Example use:" +msgstr "範例：" + +#: ../../library/hashlib.rst:261 +msgid "File hashing" +msgstr "檔案雜湊" + +#: ../../library/hashlib.rst:263 +msgid "" +"The hashlib module provides a helper function for efficient hashing of a " +"file or file-like object." +msgstr "" +"hashlib 模組提供了一個輔助函式，用於對檔案或類檔案物件 (file-like object) 進" +"行有效率的雜湊。" + +#: ../../library/hashlib.rst:268 +msgid "" +"Return a digest object that has been updated with contents of file object." +msgstr "回傳已用檔案物件內容更新的摘要物件。" + +#: ../../library/hashlib.rst:270 +msgid "" +"*fileobj* must be a file-like object opened for reading in binary mode. It " +"accepts file objects from builtin :func:`open`, :class:`~io.BytesIO` " +"instances, SocketIO objects from :meth:`socket.socket.makefile`, and " +"similar. *fileobj* must be opened in blocking mode, otherwise a :exc:" +"`BlockingIOError` may be raised." +msgstr "" +"*fileobj* 必須是以二進位模式讀取的類檔案物件。它接受來自內建 :func:`open` 的" +"檔案物件、:class:`~io.BytesIO` 實例、來自 :meth:`socket.socket.makefile` 的 " +"SocketIO 物件等。*fileobj* 必須以阻塞模式開啟，否則可能會引發 :exc:" +"`BlockingIOError`。" + +#: ../../library/hashlib.rst:276 +msgid "" +"The function may bypass Python's I/O and use the file descriptor from :meth:" +"`~io.IOBase.fileno` directly. *fileobj* must be assumed to be in an unknown " +"state after this function returns or raises. It is up to the caller to close " +"*fileobj*." +msgstr "" +"該函式可以繞過 Python 的 I/O 並直接使用 :meth:`~io.IOBase.fileno` 中的檔案描" +"述器 (file descriptor)。在此函式回傳或引發後，必須假定 *fileobj* 處於未知狀" +"態 (unknown state)。由呼叫者決定是否關閉 *fileobj*。" + +#: ../../library/hashlib.rst:281 +msgid "" +"*digest* must either be a hash algorithm name as a *str*, a hash " +"constructor, or a callable that returns a hash object." +msgstr "" +"*digest* 必須是名稱作為 *str* 的雜湊演算法、雜湊建構函式或會回傳雜湊物件的可" +"呼叫函式。" + +#: ../../library/hashlib.rst:284 +msgid "Example:" +msgstr "範例：" + +#: ../../library/hashlib.rst:305 +msgid "" +"Now raises a :exc:`BlockingIOError` if the file is opened in non-blocking " +"mode. Previously, spurious null bytes were added to the digest." +msgstr "" + +#: ../../library/hashlib.rst:311 +msgid "Key derivation" +msgstr "密鑰的生成" + +#: ../../library/hashlib.rst:313 +msgid "" +"Key derivation and key stretching algorithms are designed for secure " +"password hashing. Naive algorithms such as ``sha1(password)`` are not " +"resistant against brute-force attacks. A good password hashing function must " +"be tunable, slow, and include a `salt `_." +msgstr "" +"密鑰生成 (key derivation) 和密鑰延伸 (key stretching) 演算法專為安全密碼雜湊" +"而設計。像是 ``sha1(password)`` 這樣過於單純的演算法無法抵抗暴力攻擊。一個好" +"的密碼雜湊函式必須是可調校的 (tunable)、緩慢的，並且有包含 `salt（鹽） " +"`_。" + +#: ../../library/hashlib.rst:321 +msgid "" +"The function provides PKCS#5 password-based key derivation function 2. It " +"uses HMAC as pseudorandom function." +msgstr "" +"該函式提供基於密碼的 PKCS#5 密鑰生成函式 2。它使用 HMAC 作為偽隨機函式 " +"(pseudorandom function)。" + +#: ../../library/hashlib.rst:324 +msgid "" +"The string *hash_name* is the desired name of the hash digest algorithm for " +"HMAC, e.g. 'sha1' or 'sha256'. *password* and *salt* are interpreted as " +"buffers of bytes. Applications and libraries should limit *password* to a " +"sensible length (e.g. 1024). *salt* should be about 16 or more bytes from a " +"proper source, e.g. :func:`os.urandom`." +msgstr "" +"字串 *hash_name* 是 HMAC 的雜湊摘要演算法所需的名稱，例如 ``sha1`` 或 " +"``sha256``。*password* 和 *salt* 被直譯為位元組緩衝區。應用程式和函式庫應為 " +"*password* 設下合理的長度限制（例如 1024）。*salt* 應該是來自適當來源（例如 :" +"func:`os.urandom`）且大約 16 或更多位元組。" + +#: ../../library/hashlib.rst:330 +msgid "" +"The number of *iterations* should be chosen based on the hash algorithm and " +"computing power. As of 2022, hundreds of thousands of iterations of SHA-256 " +"are suggested. For rationale as to why and how to choose what is best for " +"your application, read *Appendix A.2.2* of NIST-SP-800-132_. The answers on " +"the `stackexchange pbkdf2 iterations question`_ explain in detail." +msgstr "" +"應根據雜湊演算法和計算能力選擇 *iterations* 次數。截至 2022 年，建議進行數十" +"萬次 SHA-256 疊代。有關為什麼以及如何選擇最適合你的應用程式的基本原理，請閱" +"讀 NIST-SP-800-132_ 的 *Appendix A.2.2*。`stackexchange pbkdf2 疊代問題`_\\ " +"上的答案有詳細解釋。" + +#: ../../library/hashlib.rst:336 +msgid "" +"*dklen* is the length of the derived key in bytes. If *dklen* is ``None`` " +"then the digest size of the hash algorithm *hash_name* is used, e.g. 64 for " +"SHA-512." +msgstr "" +"*dklen* 是生成的密鑰長度。如果 *dklen* 為 ``None``，則會使用雜湊演算法 " +"*hash_name* 的摘要大小，例如 SHA-512 為 64。" + +#: ../../library/hashlib.rst:345 +msgid "Function only available when Python is compiled with OpenSSL." +msgstr "僅當有使用 OpenSSL 編譯 Python 時該函式才可用。" + +#: ../../library/hashlib.rst:349 +msgid "" +"Function now only available when Python is built with OpenSSL. The slow pure " +"Python implementation has been removed." +msgstr "" +"該函式現在僅在有使用 OpenSSL 建置 Python 時可用。緩慢的純 Python 實作已被刪" +"除。" + +#: ../../library/hashlib.rst:355 +msgid "" +"The function provides scrypt password-based key derivation function as " +"defined in :rfc:`7914`." +msgstr "該函式提供（如 :rfc:`7914` 中所定義的）scrypt 基於密碼的密鑰衍生函式。" + +#: ../../library/hashlib.rst:358 +msgid "" +"*password* and *salt* must be :term:`bytes-like objects `. Applications and libraries should limit *password* to a sensible " +"length (e.g. 1024). *salt* should be about 16 or more bytes from a proper " +"source, e.g. :func:`os.urandom`." +msgstr "" +"*password* 和 *salt* 必須是\\ :term:`類位元組物件 `。應用" +"程式和函式庫應為 *password* 設下合理的長度限制（例如 1024）。*salt* 應該是來" +"自適當來源（例如 :func:`os.urandom`）且大約 16 或更多位元組。" + +#: ../../library/hashlib.rst:363 +msgid "" +"*n* is the CPU/Memory cost factor, *r* the block size, *p* parallelization " +"factor and *maxmem* limits memory (OpenSSL 1.1.0 defaults to 32 MiB). " +"*dklen* is the length of the derived key in bytes." +msgstr "" +"*n* 是 CPU/記憶體開銷係數、*r* 是區塊大小、*p* 為平行化係數、*maxmem* 為記憶" +"體限制（OpenSSL 1.1.0 預設為 32 MiB）。*dklen* 是生成密鑰的長度。" + +#: ../../library/hashlib.rst:373 +msgid "BLAKE2" +msgstr "BLAKE2" + +#: ../../library/hashlib.rst:380 +msgid "" +"BLAKE2_ is a cryptographic hash function defined in :rfc:`7693` that comes " +"in two flavors:" +msgstr "BLAKE2_ 是在 :rfc:`7693` 中定義的加密雜湊函式，有兩種類型：" + +#: ../../library/hashlib.rst:383 +msgid "" +"**BLAKE2b**, optimized for 64-bit platforms and produces digests of any size " +"between 1 and 64 bytes," +msgstr "" +"**BLAKE2b**，針對 64 位元平台進行了最佳化，可生成 1 到 64 位元組之間任意大小" +"的摘要，" + +#: ../../library/hashlib.rst:386 +msgid "" +"**BLAKE2s**, optimized for 8- to 32-bit platforms and produces digests of " +"any size between 1 and 32 bytes." +msgstr "" +"**BLAKE2s**，針對 8 至 32 位元平台進行了最佳化，可生成 1 至 32 位元組之間任意" +"大小的摘要。" + +#: ../../library/hashlib.rst:389 +msgid "" +"BLAKE2 supports **keyed mode** (a faster and simpler replacement for HMAC_), " +"**salted hashing**, **personalization**, and **tree hashing**." +msgstr "" +"BLAKE2 支援\\ **密鑰模式 (keyed mode)** （更快、更簡單的 HMAC_ 替代品）、**加" +"鹽雜湊 (salted hashing)**、**個人化**\\ 和\\ **樹狀雜湊**。" + +#: ../../library/hashlib.rst:392 +msgid "" +"Hash objects from this module follow the API of standard library's :mod:" +"`hashlib` objects." +msgstr "該模組中的雜湊物件遵循標準函式庫的 :mod:`hashlib` 物件 API。" + +#: ../../library/hashlib.rst:397 +msgid "Creating hash objects" +msgstr "建立雜湊物件" + +#: ../../library/hashlib.rst:399 +msgid "New hash objects are created by calling constructor functions:" +msgstr "新的雜湊物件是透過呼叫建構函式建立的：" + +#: ../../library/hashlib.rst:413 +msgid "" +"These functions return the corresponding hash objects for calculating " +"BLAKE2b or BLAKE2s. They optionally take these general parameters:" +msgstr "" +"這些函式回傳相應的雜湊物件以計算 BLAKE2b 或 BLAKE2s。他們可以選擇採用這些通用" +"參數：" + +#: ../../library/hashlib.rst:416 +msgid "" +"*data*: initial chunk of data to hash, which must be :term:`bytes-like " +"object`. It can be passed only as positional argument." +msgstr "" +"*data*：要雜湊的初始資料塊 (data chunk)，它必須是\\ :term:`類位元組物件 " +"`。它只能作為位置引數傳遞。" + +#: ../../library/hashlib.rst:419 +msgid "*digest_size*: size of output digest in bytes." +msgstr "*digest_size*：輸出摘要的大小（以位元組為單位）。" + +#: ../../library/hashlib.rst:421 +msgid "" +"*key*: key for keyed hashing (up to 64 bytes for BLAKE2b, up to 32 bytes for " +"BLAKE2s)." +msgstr "" +"*key*：用於密鑰雜湊的密鑰（BLAKE2b 最多 64 位元組、BLAKE2s 最多 32 位元組）。" + +#: ../../library/hashlib.rst:424 +msgid "" +"*salt*: salt for randomized hashing (up to 16 bytes for BLAKE2b, up to 8 " +"bytes for BLAKE2s)." +msgstr "" +"*salt*：用於隨機雜湊的鹽（BLAKE2b 最多 16 個位元組、BLAKE2s 最多 8 個位元" +"組）。" + +#: ../../library/hashlib.rst:427 +msgid "" +"*person*: personalization string (up to 16 bytes for BLAKE2b, up to 8 bytes " +"for BLAKE2s)." +msgstr "" +"*person*：個人化字串（BLAKE2b 最多 16 個位元組、BLAKE2s 最多 8 個位元組）。" + +#: ../../library/hashlib.rst:430 +msgid "The following table shows limits for general parameters (in bytes):" +msgstr "下表顯示了一般參數的限制（以位元組為單位）：" + +#: ../../library/hashlib.rst:433 +msgid "Hash" +msgstr "雜湊" + +#: ../../library/hashlib.rst:433 +msgid "digest_size" +msgstr "digest_size" + +#: ../../library/hashlib.rst:433 +msgid "len(key)" +msgstr "len(key)" + +#: ../../library/hashlib.rst:433 +msgid "len(salt)" +msgstr "len(salt)" + +#: ../../library/hashlib.rst:433 +msgid "len(person)" +msgstr "len(person)" + +#: ../../library/hashlib.rst:435 +msgid "BLAKE2b" +msgstr "BLAKE2b" + +#: ../../library/hashlib.rst:435 +msgid "64" +msgstr "64" + +#: ../../library/hashlib.rst:435 +msgid "16" +msgstr "16" + +#: ../../library/hashlib.rst:436 +msgid "BLAKE2s" +msgstr "BLAKE2s" + +#: ../../library/hashlib.rst:436 +msgid "32" +msgstr "32" + +#: ../../library/hashlib.rst:436 +msgid "8" +msgstr "8" + +#: ../../library/hashlib.rst:441 +msgid "" +"BLAKE2 specification defines constant lengths for salt and personalization " +"parameters, however, for convenience, this implementation accepts byte " +"strings of any size up to the specified length. If the length of the " +"parameter is less than specified, it is padded with zeros, thus, for " +"example, ``b'salt'`` and ``b'salt\\x00'`` is the same value. (This is not " +"the case for *key*.)" +msgstr "" +"BLAKE2 規範定義了鹽和個人化參數的恆定長度，但為了方便起見，此實作接受任意大小" +"的位元組字串，最多可達指定長度。如果參數的長度小於指定的長度，則用零補滿，所" +"以像是 ``b'salt`` 和 ``b'salt\\x00`` 是相同的值。（但 *key* 的情況並非如" +"此。）" + +#: ../../library/hashlib.rst:448 +msgid "These sizes are available as module `constants`_ described below." +msgstr "這些大小可作為模組\\ `常數 `_\\ 使用，如下所述。" + +#: ../../library/hashlib.rst:450 +msgid "" +"Constructor functions also accept the following tree hashing parameters:" +msgstr "建構函式還接受以下樹狀雜湊參數：" + +#: ../../library/hashlib.rst:452 +msgid "*fanout*: fanout (0 to 255, 0 if unlimited, 1 in sequential mode)." +msgstr "*fanout*：扇出（0 到 255，如果無限制則為 0、順序模式為 1）。" + +#: ../../library/hashlib.rst:454 +msgid "" +"*depth*: maximal depth of tree (1 to 255, 255 if unlimited, 1 in sequential " +"mode)." +msgstr "*depth*：樹的最大深度（1 到 255，如果無限制則為 255、順序模式為 1）。" + +#: ../../library/hashlib.rst:457 +msgid "" +"*leaf_size*: maximal byte length of leaf (0 to ``2**32-1``, 0 if unlimited " +"or in sequential mode)." +msgstr "" +"*leaf_size*：葉的最大位元組長度（0 到 ``2**32-1``，如果無限制或處於順序模式則" +"為 0）。" + +#: ../../library/hashlib.rst:460 +msgid "" +"*node_offset*: node offset (0 to ``2**64-1`` for BLAKE2b, 0 to ``2**48-1`` " +"for BLAKE2s, 0 for the first, leftmost, leaf, or in sequential mode)." +msgstr "" +"*node_offset*：節點偏移量（BLAKE2b 為 0 到 ``2**64-1``，BLAKE2s 為 0 到 " +"``2**48-1``，0 表示第一個、最左邊、葉子或在順序模式下）。" + +#: ../../library/hashlib.rst:463 +msgid "" +"*node_depth*: node depth (0 to 255, 0 for leaves, or in sequential mode)." +msgstr "*node_depth*：節點深度（0 到 255，葉為 0，或在順序模式下）。" + +#: ../../library/hashlib.rst:465 +msgid "" +"*inner_size*: inner digest size (0 to 64 for BLAKE2b, 0 to 32 for BLAKE2s, 0 " +"in sequential mode)." +msgstr "" +"*inner_size*：內部摘要大小（BLAKE2b 為 0 到 64，BLAKE2s 為 0 到 32，順序模式" +"為 0）。" + +#: ../../library/hashlib.rst:468 +msgid "" +"*last_node*: boolean indicating whether the processed node is the last one " +"(``False`` for sequential mode)." +msgstr "" +"*last_node*：布林值，代表處理的節點是否為最後一個（``False`` 代表順序模式）。" + +#: ../../library/hashlib.rst:471 +msgid "Explanation of tree mode parameters." +msgstr "樹狀模式參數說明。" + +#: ../../library/hashlib.rst:475 +msgid "" +"See section 2.10 in `BLAKE2 specification `_ for comprehensive review of tree hashing." +msgstr "" +"關於樹狀雜湊的綜合回顧，請參閱 `BLAKE2 規範 `_\\ 中的第 2.10 節。" + +#: ../../library/hashlib.rst:481 +msgid "Constants" +msgstr "常數" + +#: ../../library/hashlib.rst:486 +msgid "Salt length (maximum length accepted by constructors)." +msgstr "鹽長度（建構函式接受的最大長度）。" + +#: ../../library/hashlib.rst:492 +msgid "" +"Personalization string length (maximum length accepted by constructors)." +msgstr "個人化字串長度（建構函式接受的最大長度）。" + +#: ../../library/hashlib.rst:498 +msgid "Maximum key size." +msgstr "最大密鑰大小。" + +#: ../../library/hashlib.rst:504 +msgid "Maximum digest size that the hash function can output." +msgstr "雜湊函式可以輸出的最大摘要大小。" + +#: ../../library/hashlib.rst:508 +msgid "Examples" +msgstr "範例" + +#: ../../library/hashlib.rst:511 +msgid "Simple hashing" +msgstr "簡單雜湊" + +#: ../../library/hashlib.rst:513 +msgid "" +"To calculate hash of some data, you should first construct a hash object by " +"calling the appropriate constructor function (:func:`blake2b` or :func:" +"`blake2s`), then update it with the data by calling :meth:`~hash.update` on " +"the object, and, finally, get the digest out of the object by calling :meth:" +"`~hash.digest` (or :meth:`~hash.hexdigest` for hex-encoded string)." +msgstr "" +"要計算某些資料的雜湊值，你應該首先透過呼叫適當的建構函式（:func:`blake2b` " +"或 :func:`blake2s`）以建構一個雜湊物件，然後透過於物件呼叫 :meth:`~hash." +"update` 來以資料對它更新，最後透過呼叫 :meth:`~hash.digest`\\ （或對於十六進" +"位編碼字串則為 :meth:`~hash.hexdigest`）從物件中獲得摘要。" + +#: ../../library/hashlib.rst:526 +msgid "" +"As a shortcut, you can pass the first chunk of data to update directly to " +"the constructor as the positional argument:" +msgstr "" +"作為一個快捷方式，你可以將要更新的第一個資料塊作為位置引數直接傳遞給建構函" +"式：" + +#: ../../library/hashlib.rst:533 +msgid "" +"You can call :meth:`hash.update` as many times as you need to iteratively " +"update the hash:" +msgstr "你可以根據需求來多次呼叫 :meth:`hash.update` 以疊代更新雜湊：" + +#: ../../library/hashlib.rst:547 +msgid "Using different digest sizes" +msgstr "使用不同的摘要大小" + +#: ../../library/hashlib.rst:549 +msgid "" +"BLAKE2 has configurable size of digests up to 64 bytes for BLAKE2b and up to " +"32 bytes for BLAKE2s. For example, to replace SHA-1 with BLAKE2b without " +"changing the size of output, we can tell BLAKE2b to produce 20-byte digests:" +msgstr "" +"BLAKE2 有可調整的摘要大小，BLAKE2b 最多為 64 位元組，BLAKE2s 最多為 32 位元" +"組。例如，要在不改變輸出大小的情況下用 BLAKE2b 替換 SHA-1，我們可以指定 " +"BLAKE2b 生成 20 位元組的摘要：" + +#: ../../library/hashlib.rst:563 +msgid "" +"Hash objects with different digest sizes have completely different outputs " +"(shorter hashes are *not* prefixes of longer hashes); BLAKE2b and BLAKE2s " +"produce different outputs even if the output length is the same:" +msgstr "" +"具有不同摘要大小的雜湊物件具有完全不同的輸出（較短的雜湊值\\ *不是*\\ 較長雜" +"湊值的前綴）；即使輸出長度相同，BLAKE2b 和 BLAKE2s 也會產生不同的輸出：" + +#: ../../library/hashlib.rst:579 +msgid "Keyed hashing" +msgstr "密鑰雜湊 (Keyed hashing)" + +#: ../../library/hashlib.rst:581 +msgid "" +"Keyed hashing can be used for authentication as a faster and simpler " +"replacement for `Hash-based message authentication code `_ (HMAC). BLAKE2 can be securely used in prefix-MAC " +"mode thanks to the indifferentiability property inherited from BLAKE." +msgstr "" +"密鑰雜湊可用於身份驗證，作為\\ `基於雜湊的訊息驗證碼 (Hash-based message " +"authentication code) `_ (HMAC) 的更快、" +"更簡單的替代方案。由於繼承自 BLAKE 的不可微特性 (indifferentiability " +"property)，BLAKE2 可以安全地用於 prefix-MAC 模式。" + +#: ../../library/hashlib.rst:587 +msgid "" +"This example shows how to get a (hex-encoded) 128-bit authentication code " +"for message ``b'message data'`` with key ``b'pseudorandom key'``::" +msgstr "" +"此範例示範了如何使用密鑰 ``b'pseudorandom key'`` 取得訊息 ``b'message " +"data'`` 的（十六進位編碼）128 位元驗證碼： ::" + +#: ../../library/hashlib.rst:590 +msgid "" +">>> from hashlib import blake2b\n" +">>> h = blake2b(key=b'pseudorandom key', digest_size=16)\n" +">>> h.update(b'message data')\n" +">>> h.hexdigest()\n" +"'3d363ff7401e02026f4a4687d4863ced'" +msgstr "" +">>> from hashlib import blake2b\n" +">>> h = blake2b(key=b'pseudorandom key', digest_size=16)\n" +">>> h.update(b'message data')\n" +">>> h.hexdigest()\n" +"'3d363ff7401e02026f4a4687d4863ced'" + +#: ../../library/hashlib.rst:597 +msgid "" +"As a practical example, a web application can symmetrically sign cookies " +"sent to users and later verify them to make sure they weren't tampered with::" +msgstr "" +"舉一個實際的例子，網頁應用程式可以對發送給使用者的 cookie 進行對稱簽名 " +"(symmetrically sign)，然後驗證它們以確保它們沒有被篡改： ::" + +#: ../../library/hashlib.rst:600 +msgid "" +">>> from hashlib import blake2b\n" +">>> from hmac import compare_digest\n" +">>>\n" +">>> SECRET_KEY = b'pseudorandomly generated server secret key'\n" +">>> AUTH_SIZE = 16\n" +">>>\n" +">>> def sign(cookie):\n" +"... h = blake2b(digest_size=AUTH_SIZE, key=SECRET_KEY)\n" +"... h.update(cookie)\n" +"... return h.hexdigest().encode('utf-8')\n" +">>>\n" +">>> def verify(cookie, sig):\n" +"... good_sig = sign(cookie)\n" +"... return compare_digest(good_sig, sig)\n" +">>>\n" +">>> cookie = b'user-alice'\n" +">>> sig = sign(cookie)\n" +">>> print(\"{0},{1}\".format(cookie.decode('utf-8'), sig))\n" +"user-alice,b'43b3c982cf697e0c5ab22172d1ca7421'\n" +">>> verify(cookie, sig)\n" +"True\n" +">>> verify(b'user-bob', sig)\n" +"False\n" +">>> verify(cookie, b'0102030405060708090a0b0c0d0e0f00')\n" +"False" +msgstr "" +">>> from hashlib import blake2b\n" +">>> from hmac import compare_digest\n" +">>>\n" +">>> SECRET_KEY = b'pseudorandomly generated server secret key'\n" +">>> AUTH_SIZE = 16\n" +">>>\n" +">>> def sign(cookie):\n" +"... h = blake2b(digest_size=AUTH_SIZE, key=SECRET_KEY)\n" +"... h.update(cookie)\n" +"... return h.hexdigest().encode('utf-8')\n" +">>>\n" +">>> def verify(cookie, sig):\n" +"... good_sig = sign(cookie)\n" +"... return compare_digest(good_sig, sig)\n" +">>>\n" +">>> cookie = b'user-alice'\n" +">>> sig = sign(cookie)\n" +">>> print(\"{0},{1}\".format(cookie.decode('utf-8'), sig))\n" +"user-alice,b'43b3c982cf697e0c5ab22172d1ca7421'\n" +">>> verify(cookie, sig)\n" +"True\n" +">>> verify(b'user-bob', sig)\n" +"False\n" +">>> verify(cookie, b'0102030405060708090a0b0c0d0e0f00')\n" +"False" + +#: ../../library/hashlib.rst:626 +msgid "" +"Even though there's a native keyed hashing mode, BLAKE2 can, of course, be " +"used in HMAC construction with :mod:`hmac` module::" +msgstr "" +"儘管有原生密鑰雜湊模式，BLAKE2 還是可以透過 :mod:`hmac` 模組用於建構 " +"HMAC： ::" + +#: ../../library/hashlib.rst:629 +msgid "" +">>> import hmac, hashlib\n" +">>> m = hmac.new(b'secret key', digestmod=hashlib.blake2s)\n" +">>> m.update(b'message')\n" +">>> m.hexdigest()\n" +"'e3c8102868d28b5ff85fc35dda07329970d1a01e273c37481326fe0c861c8142'" +msgstr "" +">>> import hmac, hashlib\n" +">>> m = hmac.new(b'secret key', digestmod=hashlib.blake2s)\n" +">>> m.update(b'message')\n" +">>> m.hexdigest()\n" +"'e3c8102868d28b5ff85fc35dda07329970d1a01e273c37481326fe0c861c8142'" + +#: ../../library/hashlib.rst:637 +msgid "Randomized hashing" +msgstr "隨機雜湊 (Randomized hashing)" + +#: ../../library/hashlib.rst:639 +msgid "" +"By setting *salt* parameter users can introduce randomization to the hash " +"function. Randomized hashing is useful for protecting against collision " +"attacks on the hash function used in digital signatures." +msgstr "" +"透過設定 *salt* 參數，使用者可以向雜湊函式引入隨機化。隨機雜湊在防止針對數位" +"簽章中雜湊函式的碰撞攻擊 (collision attacks) 非常有用。" + +#: ../../library/hashlib.rst:643 +msgid "" +"Randomized hashing is designed for situations where one party, the message " +"preparer, generates all or part of a message to be signed by a second party, " +"the message signer. If the message preparer is able to find cryptographic " +"hash function collisions (i.e., two messages producing the same hash value), " +"then they might prepare meaningful versions of the message that would " +"produce the same hash value and digital signature, but with different " +"results (e.g., transferring $1,000,000 to an account, rather than $10). " +"Cryptographic hash functions have been designed with collision resistance as " +"a major goal, but the current concentration on attacking cryptographic hash " +"functions may result in a given cryptographic hash function providing less " +"collision resistance than expected. Randomized hashing offers the signer " +"additional protection by reducing the likelihood that a preparer can " +"generate two or more messages that ultimately yield the same hash value " +"during the digital signature generation process --- even if it is practical " +"to find collisions for the hash function. However, the use of randomized " +"hashing may reduce the amount of security provided by a digital signature " +"when all portions of the message are prepared by the signer." +msgstr "" +"隨機雜湊是為這樣的情況而設計的：一方（訊息準備者）生成全部或部分訊息並由另一" +"方（訊息簽名者）簽名。如果訊息準備者能夠發現加密雜湊函式發生碰撞（collision，" +"即兩條訊息產生相同的雜湊值），那麼他們可能會準備有意義的訊息版本，該版本將產" +"生相同的雜湊值和數位簽章，但結果不同（例如，將 $1,000,000 轉入賬戶，而不是 " +"$10）。加密雜湊函式的設計以抗碰撞性為主要目標，但目前對加密雜湊函式攻擊的關注" +"可能會導致給定的加密雜湊函式所提供的抗碰撞性低於預期。隨機雜湊透過降低準備者" +"在數位簽章生成過程中生成最終產生相同雜湊值的兩個或多個訊息的可能性，為簽名者" +"提供額外的保護 —— 即便嘗試去找到雜湊函式碰撞的發生是實際可行的。然而，若訊息" +"的所有部分都是由簽名者所準備好的，使用隨機雜湊可能會降低數位簽章提供的安全" +"性。" + +#: ../../library/hashlib.rst:662 +msgid "" +"(`NIST SP-800-106 \"Randomized Hashing for Digital Signatures\" `_)" +msgstr "" +"（`NIST SP-800-106 「數位簽章的隨機雜湊 (Randomized Hashing for Digital " +"Signatures)」 `_）" + +#: ../../library/hashlib.rst:665 +msgid "" +"In BLAKE2 the salt is processed as a one-time input to the hash function " +"during initialization, rather than as an input to each compression function." +msgstr "" +"在 BLAKE2 中，鹽在初始化期間作為雜湊函式的一次性輸入被處理，而不是作為每個壓" +"縮函式的輸入。" + +#: ../../library/hashlib.rst:670 +msgid "" +"*Salted hashing* (or just hashing) with BLAKE2 or any other general-purpose " +"cryptographic hash function, such as SHA-256, is not suitable for hashing " +"passwords. See `BLAKE2 FAQ `_ for more " +"information." +msgstr "" +"使用 BLAKE2 或任何其他通用加密雜湊函式（例如 SHA-256）的\\ *加鹽雜湊* （或單" +"純雜湊）不適合對密碼進行雜湊處理。有關更多資訊，請參閱 `BLAKE2 FAQ `_ 。" + +#: ../../library/hashlib.rst:693 +msgid "Personalization" +msgstr "個人化" + +#: ../../library/hashlib.rst:695 +msgid "" +"Sometimes it is useful to force hash function to produce different digests " +"for the same input for different purposes. Quoting the authors of the Skein " +"hash function:" +msgstr "" +"有時候強制雜湊函式為不同目的的相同輸入生成不同的摘要是很有用的。引用 Skein 雜" +"湊函式的作者的話：" + +#: ../../library/hashlib.rst:699 +msgid "" +"We recommend that all application designers seriously consider doing this; " +"we have seen many protocols where a hash that is computed in one part of the " +"protocol can be used in an entirely different part because two hash " +"computations were done on similar or related data, and the attacker can " +"force the application to make the hash inputs the same. Personalizing each " +"hash function used in the protocol summarily stops this type of attack." +msgstr "" +"我們建議所有應用程式設計者認真考慮這樣做；我們已經看到許多協定，其中在協定的" +"一個部分中計算的雜湊可以在完全不同的部分中使用，因為兩次雜湊計算是在相似或相" +"關的資料上完成的，並且攻擊者可以強制應用程式將雜湊輸入設為相同的。對協定中使" +"用的每個雜湊函式進行個人化可以立即阻止此類攻擊。" + +#: ../../library/hashlib.rst:706 +msgid "" +"(`The Skein Hash Function Family `_, p. 21)" +msgstr "" +"（`Skein 雜湊函式系列 `_，第 21 頁）" + +#: ../../library/hashlib.rst:710 +msgid "BLAKE2 can be personalized by passing bytes to the *person* argument::" +msgstr "BLAKE2 可以透過將位元組傳遞給 *person* 引數來做個人化： ::" + +#: ../../library/hashlib.rst:712 +msgid "" +">>> from hashlib import blake2b\n" +">>> FILES_HASH_PERSON = b'MyApp Files Hash'\n" +">>> BLOCK_HASH_PERSON = b'MyApp Block Hash'\n" +">>> h = blake2b(digest_size=32, person=FILES_HASH_PERSON)\n" +">>> h.update(b'the same content')\n" +">>> h.hexdigest()\n" +"'20d9cd024d4fb086aae819a1432dd2466de12947831b75c5a30cf2676095d3b4'\n" +">>> h = blake2b(digest_size=32, person=BLOCK_HASH_PERSON)\n" +">>> h.update(b'the same content')\n" +">>> h.hexdigest()\n" +"'cf68fb5761b9c44e7878bfb2c4c9aea52264a80b75005e65619778de59f383a3'" +msgstr "" +">>> from hashlib import blake2b\n" +">>> FILES_HASH_PERSON = b'MyApp Files Hash'\n" +">>> BLOCK_HASH_PERSON = b'MyApp Block Hash'\n" +">>> h = blake2b(digest_size=32, person=FILES_HASH_PERSON)\n" +">>> h.update(b'the same content')\n" +">>> h.hexdigest()\n" +"'20d9cd024d4fb086aae819a1432dd2466de12947831b75c5a30cf2676095d3b4'\n" +">>> h = blake2b(digest_size=32, person=BLOCK_HASH_PERSON)\n" +">>> h.update(b'the same content')\n" +">>> h.hexdigest()\n" +"'cf68fb5761b9c44e7878bfb2c4c9aea52264a80b75005e65619778de59f383a3'" + +#: ../../library/hashlib.rst:724 +msgid "" +"Personalization together with the keyed mode can also be used to derive " +"different keys from a single one." +msgstr "個人化與密鑰模式還可以一起用於從單個密鑰得出不同的密鑰。" + +#: ../../library/hashlib.rst:738 +msgid "Tree mode" +msgstr "樹狀模式" + +#: ../../library/hashlib.rst:740 +msgid "Here's an example of hashing a minimal tree with two leaf nodes::" +msgstr "下面是對具有兩個葉節點的最小樹進行雜湊處理的範例： ::" + +#: ../../library/hashlib.rst:742 +msgid "" +" 10\n" +" / \\\n" +"00 01" +msgstr "" +" 10\n" +" / \\\n" +"00 01" + +#: ../../library/hashlib.rst:746 +msgid "" +"This example uses 64-byte internal digests, and returns the 32-byte final " +"digest::" +msgstr "此範例使用 64-byte 內部摘要，並回傳 32-byte 最終摘要： ::" + +#: ../../library/hashlib.rst:749 +msgid "" +">>> from hashlib import blake2b\n" +">>>\n" +">>> FANOUT = 2\n" +">>> DEPTH = 2\n" +">>> LEAF_SIZE = 4096\n" +">>> INNER_SIZE = 64\n" +">>>\n" +">>> buf = bytearray(6000)\n" +">>>\n" +">>> # Left leaf\n" +"... h00 = blake2b(buf[0:LEAF_SIZE], fanout=FANOUT, depth=DEPTH,\n" +"... leaf_size=LEAF_SIZE, inner_size=INNER_SIZE,\n" +"... node_offset=0, node_depth=0, last_node=False)\n" +">>> # Right leaf\n" +"... h01 = blake2b(buf[LEAF_SIZE:], fanout=FANOUT, depth=DEPTH,\n" +"... leaf_size=LEAF_SIZE, inner_size=INNER_SIZE,\n" +"... node_offset=1, node_depth=0, last_node=True)\n" +">>> # Root node\n" +"... h10 = blake2b(digest_size=32, fanout=FANOUT, depth=DEPTH,\n" +"... leaf_size=LEAF_SIZE, inner_size=INNER_SIZE,\n" +"... node_offset=0, node_depth=1, last_node=True)\n" +">>> h10.update(h00.digest())\n" +">>> h10.update(h01.digest())\n" +">>> h10.hexdigest()\n" +"'3ad2a9b37c6070e374c7a8c508fe20ca86b6ed54e286e93a0318e95e881db5aa'" +msgstr "" +">>> from hashlib import blake2b\n" +">>>\n" +">>> FANOUT = 2\n" +">>> DEPTH = 2\n" +">>> LEAF_SIZE = 4096\n" +">>> INNER_SIZE = 64\n" +">>>\n" +">>> buf = bytearray(6000)\n" +">>>\n" +">>> # Left leaf\n" +"... h00 = blake2b(buf[0:LEAF_SIZE], fanout=FANOUT, depth=DEPTH,\n" +"... leaf_size=LEAF_SIZE, inner_size=INNER_SIZE,\n" +"... node_offset=0, node_depth=0, last_node=False)\n" +">>> # Right leaf\n" +"... h01 = blake2b(buf[LEAF_SIZE:], fanout=FANOUT, depth=DEPTH,\n" +"... leaf_size=LEAF_SIZE, inner_size=INNER_SIZE,\n" +"... node_offset=1, node_depth=0, last_node=True)\n" +">>> # Root node\n" +"... h10 = blake2b(digest_size=32, fanout=FANOUT, depth=DEPTH,\n" +"... leaf_size=LEAF_SIZE, inner_size=INNER_SIZE,\n" +"... node_offset=0, node_depth=1, last_node=True)\n" +">>> h10.update(h00.digest())\n" +">>> h10.update(h01.digest())\n" +">>> h10.hexdigest()\n" +"'3ad2a9b37c6070e374c7a8c508fe20ca86b6ed54e286e93a0318e95e881db5aa'" + +#: ../../library/hashlib.rst:776 +msgid "Credits" +msgstr "製作人員" + +#: ../../library/hashlib.rst:778 +msgid "" +"BLAKE2_ was designed by *Jean-Philippe Aumasson*, *Samuel Neves*, *Zooko " +"Wilcox-O'Hearn*, and *Christian Winnerlein* based on SHA-3_ finalist BLAKE_ " +"created by *Jean-Philippe Aumasson*, *Luca Henzen*, *Willi Meier*, and " +"*Raphael C.-W. Phan*." +msgstr "" +"BLAKE2_ 由 *Jean-Philippe Aumasson*、*Samuel Neves*、*Zooko Wilcox-O'Hearn* " +"和 *Christian Winnerlein* 設計，基於由 *Jean-Philippe Aumasson*、*Luca " +"Henzen*、*Willi Meier* 和 *Raphael C.-W. Phan* 所建立的 SHA-3_ 最終版本 " +"BLAKE_。" + +#: ../../library/hashlib.rst:783 +msgid "" +"It uses core algorithm from ChaCha_ cipher designed by *Daniel J. " +"Bernstein*." +msgstr "它使用 *Daniel J. Bernstein* 設計的 ChaCha_ 密碼的核心演算法。" + +#: ../../library/hashlib.rst:785 +msgid "" +"The stdlib implementation is based on pyblake2_ module. It was written by " +"*Dmitry Chestnykh* based on C implementation written by *Samuel Neves*. The " +"documentation was copied from pyblake2_ and written by *Dmitry Chestnykh*." +msgstr "" +"標準函式庫實作是基於 pyblake2_ 模組。它是由 *Dmitry Chestnykh* 在 *Samuel " +"Neves* 的 C 版本實作為基礎所編寫的。該文件是由 *Dmitry Chestnykh* 編寫並從 " +"pyblake2_ 複製過來的。" + +#: ../../library/hashlib.rst:789 +msgid "The C code was partly rewritten for Python by *Christian Heimes*." +msgstr "*Christian Heimes* 為 Python 重寫了部分 C 程式碼。" + +#: ../../library/hashlib.rst:791 +msgid "" +"The following public domain dedication applies for both C hash function " +"implementation, extension code, and this documentation:" +msgstr "以下公開領域貢獻適用於 C 雜湊函式實作、擴充程式碼和此文件：" + +#: ../../library/hashlib.rst:794 +msgid "" +"To the extent possible under law, the author(s) have dedicated all copyright " +"and related and neighboring rights to this software to the public domain " +"worldwide. This software is distributed without any warranty." +msgstr "" +"在法律允許的範圍內，作者已將該軟體的所有版權以及相關和鄰接權利奉獻給全球的公" +"開領域。該軟體的發布沒有任何授權 (warranty)。" + +#: ../../library/hashlib.rst:798 +msgid "" +"You should have received a copy of the CC0 Public Domain Dedication along " +"with this software. If not, see https://creativecommons.org/publicdomain/" +"zero/1.0/." +msgstr "" +"你應會隨本軟體一起收到一份 CC0 公眾領域貢獻宣告 (CC0 Public Domain " +"Dedication) 的副本。如果沒有，請參閱 https://creativecommons.org/" +"publicdomain/zero/1.0/ 。" + +#: ../../library/hashlib.rst:802 +msgid "" +"The following people have helped with development or contributed their " +"changes to the project and the public domain according to the Creative " +"Commons Public Domain Dedication 1.0 Universal:" +msgstr "" +"以下人員根據創用 CC 通用公眾領域貢獻宣告 1.0 (Creative Commons Public Domain " +"Dedication 1.0 Universal) 於專案和公開領域做出了開發或貢獻：" + +#: ../../library/hashlib.rst:806 +msgid "*Alexandr Sokolovskiy*" +msgstr "*Alexandr Sokolovskiy*" + +#: ../../library/hashlib.rst:827 +msgid "Module :mod:`hmac`" +msgstr ":mod:`hmac` 模組" + +#: ../../library/hashlib.rst:828 +msgid "A module to generate message authentication codes using hashes." +msgstr "使用雜湊生成訊息驗證程式碼的模組。" + +#: ../../library/hashlib.rst:830 +msgid "Module :mod:`base64`" +msgstr ":mod:`base64` 模組" + +#: ../../library/hashlib.rst:831 +msgid "Another way to encode binary hashes for non-binary environments." +msgstr "另一種在非二進位環境中編碼二進位雜湊的方法。" + +#: ../../library/hashlib.rst:833 +msgid "https://nvlpubs.nist.gov/nistpubs/fips/nist.fips.180-4.pdf" +msgstr "https://nvlpubs.nist.gov/nistpubs/fips/nist.fips.180-4.pdf" + +#: ../../library/hashlib.rst:834 +msgid "The FIPS 180-4 publication on Secure Hash Algorithms." +msgstr "有關安全雜湊演算法的 FIPS 180-4 出版物。" + +#: ../../library/hashlib.rst:836 +msgid "https://csrc.nist.gov/pubs/fips/202/final" +msgstr "https://csrc.nist.gov/pubs/fips/202/final" + +#: ../../library/hashlib.rst:837 +msgid "The FIPS 202 publication on the SHA-3 Standard." +msgstr "有關 SHA-3 標準的 FIPS 202 出版物。" + +#: ../../library/hashlib.rst:839 +msgid "https://www.blake2.net/" +msgstr "https://www.blake2.net/" + +#: ../../library/hashlib.rst:840 +msgid "Official BLAKE2 website." +msgstr "BLAKE2 官方網站。" + +#: ../../library/hashlib.rst:842 +msgid "https://en.wikipedia.org/wiki/Cryptographic_hash_function" +msgstr "https://en.wikipedia.org/wiki/Cryptographic_hash_function" + +#: ../../library/hashlib.rst:843 +msgid "" +"Wikipedia article with information on which algorithms have known issues and " +"what that means regarding their use." +msgstr "" +"包含有關哪些演算法存在已知問題以及這些問題對其使用意味著什麼資訊的維基百科文" +"章。" + +#: ../../library/hashlib.rst:846 +msgid "https://www.ietf.org/rfc/rfc8018.txt" +msgstr "https://www.ietf.org/rfc/rfc8018.txt" + +#: ../../library/hashlib.rst:847 +msgid "PKCS #5: Password-Based Cryptography Specification Version 2.1" +msgstr "PKCS #5：基於密碼的加密規範版本 2.1" + +#: ../../library/hashlib.rst:849 +msgid "" +"https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-132.pdf" +msgstr "" +"https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-132.pdf" + +#: ../../library/hashlib.rst:850 +msgid "NIST Recommendation for Password-Based Key Derivation." +msgstr "NIST（美國國家標準技術研究院）針對基於密碼的密鑰衍生的建議。" + +#: ../../library/hashlib.rst:12 +msgid "message digest, MD5" +msgstr "message digest（訊息摘要）、MD5" + +#: ../../library/hashlib.rst:12 +msgid "" +"secure hash algorithm, SHA1, SHA2, SHA224, SHA256, SHA384, SHA512, SHA3, " +"Shake, Blake2" +msgstr "" +"安全雜湊演算法、SHA1、SHA2、SHA224、SHA256、SHA384、SHA512、SHA3、Shake、" +"Blake2" + +#: ../../library/hashlib.rst:53 +msgid "OpenSSL" +msgstr "OpenSSL" + +#: ../../library/hashlib.rst:53 +msgid "(use in module hashlib)" +msgstr "（使用於 hashlib 模組中）" + +#: ../../library/hashlib.rst:377 +msgid "blake2b, blake2s" +msgstr "blake2b, blake2s" diff --git a/library/heapq.po b/library/heapq.po index 5dd4ca0601..0e3fb3391b 100644 --- a/library/heapq.po +++ b/library/heapq.po @@ -1,717 +1,717 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Liang-Bo Wang , 2016 -# 周 忠毅 , 2016 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-07 00:14+0000\n" -"PO-Revision-Date: 2023-07-01 18:20+0800\n" -"Last-Translator: Liang-Bo Wang \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" -"X-Generator: Poedit 3.3.2\n" - -#: ../../library/heapq.rst:2 -msgid ":mod:`!heapq` --- Heap queue algorithm" -msgstr ":mod:`!heapq` --- 堆積佇列 (heap queue) 演算法" - -#: ../../library/heapq.rst:12 -msgid "**Source code:** :source:`Lib/heapq.py`" -msgstr "**原始碼：**\\ :source:`Lib/heapq.py`" - -#: ../../library/heapq.rst:16 -msgid "" -"This module provides an implementation of the heap queue algorithm, also " -"known as the priority queue algorithm." -msgstr "" -"這個模組實作了堆積佇列 (heap queue) 演算法，亦被稱為優先佇列 (priority " -"queue) 演算法。" - -#: ../../library/heapq.rst:19 -msgid "" -"Min-heaps are binary trees for which every parent node has a value less than " -"or equal to any of its children. We refer to this condition as the heap " -"invariant." -msgstr "" -"最小堆積 (min-heap) 是一顆二元樹，樹上每個父節點的值都小於或等於其子節點的" -"值。我們將這種情況稱為堆積性質不變 (heap invariant)。" - -#: ../../library/heapq.rst:23 -msgid "" -"For min-heaps, this implementation uses lists for which ``heap[k] <= " -"heap[2*k+1]`` and ``heap[k] <= heap[2*k+2]`` for all *k* for which the " -"compared elements exist. Elements are counted from zero. The interesting " -"property of a min-heap is that its smallest element is always the root, " -"``heap[0]``." -msgstr "" -"對於最小堆積，此實作使用串列，對於所有存在的被比較元素，*k* 都滿足 ``heap[k] " -"<= heap[2*k+1]`` 和 ``heap[k] <= heap[2*k+2]``。元素是從零開始計數。最小堆積" -"有一個有趣的性質：最小的元素永遠在根節點 ``heap[0]``。" - -#: ../../library/heapq.rst:29 -msgid "" -"Max-heaps satisfy the reverse invariant: every parent node has a value " -"*greater* than any of its children. These are implemented as lists for " -"which ``maxheap[2*k+1] <= maxheap[k]`` and ``maxheap[2*k+2] <= maxheap[k]`` " -"for all *k* for which the compared elements exist. The root, ``maxheap[0]``, " -"contains the *largest* element; ``heap.sort(reverse=True)`` maintains the " -"max-heap invariant." -msgstr "" - -#: ../../library/heapq.rst:36 -msgid "" -"The :mod:`!heapq` API differs from textbook heap algorithms in two aspects: " -"(a) We use zero-based indexing. This makes the relationship between the " -"index for a node and the indexes for its children slightly less obvious, but " -"is more suitable since Python uses zero-based indexing. (b) Textbooks often " -"focus on max-heaps, due to their suitability for in-place sorting. Our " -"implementation favors min-heaps as they better correspond to Python :class:" -"`lists `." -msgstr "" -":mod:`!heapq` API 與教科書上的堆積演算法在兩個方面不同：(a) 我們使用從零開始" -"的索引。這使得節點索引和其子節點索引之間的關係變得不那麼明顯，但由於 Python " -"使用從零開始的索引，所以這樣更適合。(b) 教科書通常專注於最大堆積，因為它們適" -"合原地排序。我們的實作偏向於最小堆積，因為它們更符合 Python :class:`串列 " -"`。" - -#: ../../library/heapq.rst:43 -msgid "" -"These two aspects make it possible to view the heap as a regular Python list " -"without surprises: ``heap[0]`` is the smallest item, and ``heap.sort()`` " -"maintains the heap invariant!" -msgstr "" -"這兩個特性使得可以將堆積視為一個普通的 Python 串列而不會有意外：``heap[0]`` " -"是最小的元素，而 ``heap.sort()`` 維持堆積性質不變！" - -#: ../../library/heapq.rst:47 -msgid "" -"Like :meth:`list.sort`, this implementation uses only the ``<`` operator for " -"comparisons, for both min-heaps and max-heaps." -msgstr "" - -#: ../../library/heapq.rst:50 -msgid "" -"In the API below, and in this documentation, the unqualified term *heap* " -"generally refers to a min-heap. The API for max-heaps is named using a " -"``_max`` suffix." -msgstr "" - -#: ../../library/heapq.rst:54 -msgid "" -"To create a heap, use a list initialized as ``[]``, or transform an existing " -"list into a min-heap or max-heap using the :func:`heapify` or :func:" -"`heapify_max` functions, respectively." -msgstr "" -"要建立一個堆積，使用初始化為 ``[]`` 的串列，或者分別使用 :func:`heapify` 或 :" -"func:`heapify_max` 函式將現有的串列轉換為最小堆積或最大堆積。" - -#: ../../library/heapq.rst:58 -msgid "The following functions are provided for min-heaps:" -msgstr "提供了以下針對最小堆積的函式：" - -#: ../../library/heapq.rst:63 -msgid "Transform list *x* into a min-heap, in-place, in linear time." -msgstr "在線性時間內將串列 *x* 原地轉換為最小堆積。" - -#: ../../library/heapq.rst:68 -msgid "" -"Push the value *item* onto the *heap*, maintaining the min-heap invariant." -msgstr "將值 *item* 推入 *heap*，並維持最小堆積性質不變。" - -#: ../../library/heapq.rst:73 -msgid "" -"Pop and return the smallest item from the *heap*, maintaining the min-heap " -"invariant. If the heap is empty, :exc:`IndexError` is raised. To access " -"the smallest item without popping it, use ``heap[0]``." -msgstr "" -"從 *heap* 取出並回傳最小的元素，維持最小堆積性質不變。如果堆積為空，會引發 :" -"exc:`IndexError`。若要在不取出的情況下存取最小元素，請使用 ``heap[0]``。" - -#: ../../library/heapq.rst:80 -msgid "" -"Push *item* on the heap, then pop and return the smallest item from the " -"*heap*. The combined action runs more efficiently than :func:`heappush` " -"followed by a separate call to :func:`heappop`." -msgstr "" -"將 *item* 放入 heap ，接著從 *heap* 取出並回傳最小的元素。這個組合函式比呼" -"叫 :func:`heappush` 之後呼叫 :func:`heappop` 更有效率。" - -#: ../../library/heapq.rst:87 -msgid "" -"Pop and return the smallest item from the *heap*, and also push the new " -"*item*. The heap size doesn't change. If the heap is empty, :exc:" -"`IndexError` is raised." -msgstr "" -"從 *heap* 取出並回傳最小的元素，接著將新的 *item* 放進heap。heap 的大小不會改" -"變。如果 heap 是空的會產生 :exc:`IndexError` 錯誤。" - -#: ../../library/heapq.rst:90 -msgid "" -"This one step operation is more efficient than a :func:`heappop` followed " -"by :func:`heappush` and can be more appropriate when using a fixed-size " -"heap. The pop/push combination always returns an element from the heap and " -"replaces it with *item*." -msgstr "" -"這個一次完成的操作會比呼叫 :func:`heappop` 之後呼叫 :func:`heappush` 更有效" -"率，並在維護 heap 的大小不變時更為適當，取出/放入的組合函式一定會從 heap 回傳" -"一個元素並用 *item* 取代他。" - -#: ../../library/heapq.rst:95 -msgid "" -"The value returned may be larger than the *item* added. If that isn't " -"desired, consider using :func:`heappushpop` instead. Its push/pop " -"combination returns the smaller of the two values, leaving the larger value " -"on the heap." -msgstr "" -"函式的回傳值可能會大於被加入的 *item* 。如果這不是你期望發生的，可以考慮使" -"用 :func:`heappushpop` 替代，他會回傳 heap 的最小值和 *item* 兩個當中比較小的" -"那個，並將大的留在 heap 內。" - -#: ../../library/heapq.rst:101 -msgid "For max-heaps, the following functions are provided:" -msgstr "提供以下針對最大堆積的函式：" - -#: ../../library/heapq.rst:106 -msgid "Transform list *x* into a max-heap, in-place, in linear time." -msgstr "在線性時間內將串列 *x* 原地轉換為最大堆積。" - -#: ../../library/heapq.rst:113 -msgid "" -"Push the value *item* onto the max-heap *heap*, maintaining the max-heap " -"invariant." -msgstr "將值 *item* 推入最大堆積 *heap*，維持最大堆積性質不變。" - -#: ../../library/heapq.rst:121 -msgid "" -"Pop and return the largest item from the max-heap *heap*, maintaining the " -"max-heap invariant. If the max-heap is empty, :exc:`IndexError` is raised. " -"To access the largest item without popping it, use ``maxheap[0]``." -msgstr "" -"從最大堆積 *heap* 取出並回傳最大的元素，維持最大堆積性質不變。如果最大堆積為" -"空，會引發 :exc:`IndexError`。若要在不取出的情況下存取最大元素，請使用 " -"``maxheap[0]``。" - -#: ../../library/heapq.rst:130 -msgid "" -"Push *item* on the max-heap *heap*, then pop and return the largest item " -"from *heap*. The combined action runs more efficiently than :func:" -"`heappush_max` followed by a separate call to :func:`heappop_max`." -msgstr "" -"將 *item* 推入 max-heap *heap*，然後取出並回傳 *heap* 中最大的元素。這個組合" -"動作比先呼叫 :func:`heappush_max` 再單獨呼叫 :func:`heappop_max` 更有效率。" - -#: ../../library/heapq.rst:140 -msgid "" -"Pop and return the largest item from the max-heap *heap* and also push the " -"new *item*. The max-heap size doesn't change. If the max-heap is empty, :exc:" -"`IndexError` is raised." -msgstr "" -"從最大堆積 *heap* 取出並回傳最大的元素，同時推入新的 *item*。最大堆積的大小不" -"會改變。如果最大堆積為空，會引發 :exc:`IndexError`。" - -#: ../../library/heapq.rst:145 -msgid "" -"The value returned may be smaller than the *item* added. Refer to the " -"analogous function :func:`heapreplace` for detailed usage notes." -msgstr "" - -#: ../../library/heapq.rst:151 -msgid "The module also offers three general purpose functions based on heaps." -msgstr "這個模組也提供三個利用 heap 實作的一般用途函式" - -#: ../../library/heapq.rst:156 -msgid "" -"Merge multiple sorted inputs into a single sorted output (for example, merge " -"timestamped entries from multiple log files). Returns an :term:`iterator` " -"over the sorted values." -msgstr "" -"合併多個已排序的輸入並產生單一且已排序的輸出（舉例：合併來自多個 log 檔中有時" -"間戳記的項目）。回傳一個 :term:`iterator` 包含已經排序的值。" - -#: ../../library/heapq.rst:160 -msgid "" -"Similar to ``sorted(itertools.chain(*iterables))`` but returns an iterable, " -"does not pull the data into memory all at once, and assumes that each of the " -"input streams is already sorted (smallest to largest)." -msgstr "" -"和 ``sorted(itertools.chain(*iterables))`` 類似但回傳值是一個 iterable ，不會" -"一次把所有資料都放進記憶體中，並且假設每一個輸入都已經（由小到大）排序過了。" - -#: ../../library/heapq.rst:164 -msgid "" -"Has two optional arguments which must be specified as keyword arguments." -msgstr "有兩個選用參數，指定時必須被當作關鍵字參數指定。" - -#: ../../library/heapq.rst:166 -msgid "" -"*key* specifies a :term:`key function` of one argument that is used to " -"extract a comparison key from each input element. The default value is " -"``None`` (compare the elements directly)." -msgstr "" -"*key* 參數指定了一個 :term:`key function` 引數，用來從每一個輸入的元素中決定" -"一個比較的依據。預設的值是 ``None`` （直接比較元素）。" - -#: ../../library/heapq.rst:170 -msgid "" -"*reverse* is a boolean value. If set to ``True``, then the input elements " -"are merged as if each comparison were reversed. To achieve behavior similar " -"to ``sorted(itertools.chain(*iterables), reverse=True)``, all iterables must " -"be sorted from largest to smallest." -msgstr "" -"*reverse* 是一個布林值，如果設定為 ``True`` ，則輸入的元素將以相反的比較順序" -"進行合併。為了達成類似 ``sorted(itertools.chain(*iterables), reverse=True)`` " -"的行為，所有 iterables 必須由大到小排序。" - -#: ../../library/heapq.rst:175 -msgid "Added the optional *key* and *reverse* parameters." -msgstr "加入選用參數 *key* 和 *reverse* 。" - -#: ../../library/heapq.rst:181 -msgid "" -"Return a list with the *n* largest elements from the dataset defined by " -"*iterable*. *key*, if provided, specifies a function of one argument that " -"is used to extract a comparison key from each element in *iterable* (for " -"example, ``key=str.lower``). Equivalent to: ``sorted(iterable, key=key, " -"reverse=True)[:n]``." -msgstr "" -"回傳一個包含資料 *iterable* 中前 *n* 大元素的 list 。如果有指定 *key* 引數，" -"*key* 會是只有一個引數的函式，用來從每一個在 *iterable* 中的元素提取一個比較" -"的依據（例如 ``key=str.lower`` ）。效果相當於 ``sorted(iterable, key=key, " -"reverse=True)[:n]`` 。" - -#: ../../library/heapq.rst:190 -msgid "" -"Return a list with the *n* smallest elements from the dataset defined by " -"*iterable*. *key*, if provided, specifies a function of one argument that " -"is used to extract a comparison key from each element in *iterable* (for " -"example, ``key=str.lower``). Equivalent to: ``sorted(iterable, key=key)[:" -"n]``." -msgstr "" -"回傳一個包含資料 *iterable* 中前 *n* 小元素的 list 。如果有指定 *key* 引數，" -"*key* 會是只有一個引數的函式，用來從每一個在 *iterable* 中的元素提取一個比較" -"的依據（例如 ``key=str.lower`` ）。效果相當於 ``sorted(iterable, key=key)[:" -"n]`` 。" - -#: ../../library/heapq.rst:196 -msgid "" -"The latter two functions perform best for smaller values of *n*. For larger " -"values, it is more efficient to use the :func:`sorted` function. Also, when " -"``n==1``, it is more efficient to use the built-in :func:`min` and :func:" -"`max` functions. If repeated usage of these functions is required, consider " -"turning the iterable into an actual heap." -msgstr "" -"後兩個函式在 *n* 值比較小時有最好的表現。對於較大的 *n* 值，只用 :func:" -"`sorted` 函式會更有效率。同樣地，當 ``n==1`` 時，使用內建函式 :func:`min` " -"和 :func:`max` 會有更好的效率。如果需要重複使用這些函式，可以考慮將 iterable " -"轉成真正的 heap 。" - -#: ../../library/heapq.rst:204 -msgid "Basic Examples" -msgstr "基礎範例" - -#: ../../library/heapq.rst:206 -msgid "" -"A `heapsort `_ can be implemented by " -"pushing all values onto a heap and then popping off the smallest values one " -"at a time::" -msgstr "" -"`堆積排序 (heapsort) `_ 可以透過將所" -"有的值推入一個 heap，並且從 heap 中一個接一個彈出最小元素來實作： ::" - -#: ../../library/heapq.rst:210 -msgid "" -">>> def heapsort(iterable):\n" -"... h = []\n" -"... for value in iterable:\n" -"... heappush(h, value)\n" -"... return [heappop(h) for i in range(len(h))]\n" -"...\n" -">>> heapsort([1, 3, 5, 7, 9, 2, 4, 6, 8, 0])\n" -"[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]" -msgstr "" -">>> def heapsort(iterable):\n" -"... h = []\n" -"... for value in iterable:\n" -"... heappush(h, value)\n" -"... return [heappop(h) for i in range(len(h))]\n" -"...\n" -">>> heapsort([1, 3, 5, 7, 9, 2, 4, 6, 8, 0])\n" -"[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]" - -#: ../../library/heapq.rst:219 -msgid "" -"This is similar to ``sorted(iterable)``, but unlike :func:`sorted`, this " -"implementation is not stable." -msgstr "" -"雖然類似 ``sorted(iterable)`` ，但跟 :func:`sorted` 不同的是，這個實作不是 " -"stable 的排序。" - -#: ../../library/heapq.rst:222 -msgid "" -"Heap elements can be tuples. This is useful for assigning comparison values " -"(such as task priorities) alongside the main record being tracked::" -msgstr "" -"Heap 中的元素可以是 tuple 。這有利於將要比較的值（例如一個 task 的優先度）和" -"主要資料放在一起排序： ::" - -#: ../../library/heapq.rst:225 -msgid "" -">>> h = []\n" -">>> heappush(h, (5, 'write code'))\n" -">>> heappush(h, (7, 'release product'))\n" -">>> heappush(h, (1, 'write spec'))\n" -">>> heappush(h, (3, 'create tests'))\n" -">>> heappop(h)\n" -"(1, 'write spec')" -msgstr "" -">>> h = []\n" -">>> heappush(h, (5, 'write code'))\n" -">>> heappush(h, (7, 'release product'))\n" -">>> heappush(h, (1, 'write spec'))\n" -">>> heappush(h, (3, 'create tests'))\n" -">>> heappop(h)\n" -"(1, 'write spec')" - -#: ../../library/heapq.rst:235 -msgid "Priority Queue Implementation Notes" -msgstr "優先佇列實作細節" - -#: ../../library/heapq.rst:237 -msgid "" -"A `priority queue `_ is common " -"use for a heap, and it presents several implementation challenges:" -msgstr "" -"`優先佇列 (priority queue) `_ " -"是 heap 的常見用途之一，實作優先佇列伴隨著下列挑戰：" - -#: ../../library/heapq.rst:240 -msgid "" -"Sort stability: how do you get two tasks with equal priorities to be " -"returned in the order they were originally added?" -msgstr "" -"排序的穩定性：如何將兩個擁有相同優先次序 (priority) 的 task 按照他們被加入的" -"順序回傳?" - -#: ../../library/heapq.rst:243 -msgid "" -"Tuple comparison breaks for (priority, task) pairs if the priorities are " -"equal and the tasks do not have a default comparison order." -msgstr "" -"Tuple的排序在某些情況下會壞掉，例如當 Tuple (priority, task) 的 priorities 相" -"等且 tasks 沒有一個預設的排序時。" - -#: ../../library/heapq.rst:246 -msgid "" -"If the priority of a task changes, how do you move it to a new position in " -"the heap?" -msgstr "" -"當一個 heap 中 task 的 priority 改變時，如何將它移到 heap 正確的位置上?" - -#: ../../library/heapq.rst:249 -msgid "" -"Or if a pending task needs to be deleted, how do you find it and remove it " -"from the queue?" -msgstr "" -"或者一個還沒被解決的 task 需要被刪除時，要如何從佇列中找到並刪除指定的 task?" - -#: ../../library/heapq.rst:252 -msgid "" -"A solution to the first two challenges is to store entries as 3-element list " -"including the priority, an entry count, and the task. The entry count " -"serves as a tie-breaker so that two tasks with the same priority are " -"returned in the order they were added. And since no two entry counts are the " -"same, the tuple comparison will never attempt to directly compare two tasks." -msgstr "" -"一個針對前兩個問題的解法是：儲存一個包含 priority、entry count 和 task 三個元" -"素的 tuple 。兩個 task 有相同 priority 時，entry count 會讓兩個 task 能根據加" -"入的順序排序。因為沒有任何兩個 task 擁有相同的 entry count，所以永遠不會直接" -"使用 task 做比較。" - -#: ../../library/heapq.rst:258 -msgid "" -"Another solution to the problem of non-comparable tasks is to create a " -"wrapper class that ignores the task item and only compares the priority " -"field::" -msgstr "" -"task 無法比較的另一個解決方案是建立一個包裝器類別，該類別忽略 task 項目，只比" -"較優先等級： ::" - -#: ../../library/heapq.rst:261 -msgid "" -"from dataclasses import dataclass, field\n" -"from typing import Any\n" -"\n" -"@dataclass(order=True)\n" -"class PrioritizedItem:\n" -" priority: int\n" -" item: Any=field(compare=False)" -msgstr "" -"from dataclasses import dataclass, field\n" -"from typing import Any\n" -"\n" -"@dataclass(order=True)\n" -"class PrioritizedItem:\n" -" priority: int\n" -" item: Any=field(compare=False)" - -#: ../../library/heapq.rst:269 -msgid "" -"The remaining challenges revolve around finding a pending task and making " -"changes to its priority or removing it entirely. Finding a task can be done " -"with a dictionary pointing to an entry in the queue." -msgstr "" -"剩下的問題可以藉由找到要刪除的 task 並更改它的 priority 或者直接將它移除。尋" -"找一個 task 可以使用一個 dictionary 指向佇列當中的 entry 。" - -#: ../../library/heapq.rst:273 -msgid "" -"Removing the entry or changing its priority is more difficult because it " -"would break the heap structure invariants. So, a possible solution is to " -"mark the entry as removed and add a new entry with the revised priority::" -msgstr "" -"移除 entry 或更改它的 priority 更為困難，因為這會破壞 heap 的性質。所以一個可" -"行的方案是將原本的 entry 做一個標記表示它已經被刪除，並新增一個擁有新的 " -"priority 的 entry： ::" - -#: ../../library/heapq.rst:277 -msgid "" -"pq = [] # list of entries arranged in a heap\n" -"entry_finder = {} # mapping of tasks to entries\n" -"REMOVED = '' # placeholder for a removed task\n" -"counter = itertools.count() # unique sequence count\n" -"\n" -"def add_task(task, priority=0):\n" -" 'Add a new task or update the priority of an existing task'\n" -" if task in entry_finder:\n" -" remove_task(task)\n" -" count = next(counter)\n" -" entry = [priority, count, task]\n" -" entry_finder[task] = entry\n" -" heappush(pq, entry)\n" -"\n" -"def remove_task(task):\n" -" 'Mark an existing task as REMOVED. Raise KeyError if not found.'\n" -" entry = entry_finder.pop(task)\n" -" entry[-1] = REMOVED\n" -"\n" -"def pop_task():\n" -" 'Remove and return the lowest priority task. Raise KeyError if empty.'\n" -" while pq:\n" -" priority, count, task = heappop(pq)\n" -" if task is not REMOVED:\n" -" del entry_finder[task]\n" -" return task\n" -" raise KeyError('pop from an empty priority queue')" -msgstr "" -"pq = [] # 在 heap 中的 entry 串列\n" -"entry_finder = {} # task 對應到 entry 的對映\n" -"REMOVED = '' # 被刪除的 task 的佔位器\n" -"counter = itertools.count() # 唯一的序列計數\n" -"\n" -"def add_task(task, priority=0):\n" -" '新增一個 task 或更新一個已存在 task 的 priority'\n" -" if task in entry_finder:\n" -" remove_task(task)\n" -" count = next(counter)\n" -" entry = [priority, count, task]\n" -" entry_finder[task] = entry\n" -" heappush(pq, entry)\n" -"\n" -"def remove_task(task):\n" -" '將一個已存在的 task 標記為 REMOVED。如果找不到會引發 KeyError。'\n" -" entry = entry_finder.pop(task)\n" -" entry[-1] = REMOVED\n" -"\n" -"def pop_task():\n" -" '移除並回傳最低 priority 的 task。如果 heap 是空的會引發 KeyError。'\n" -" while pq:\n" -" priority, count, task = heappop(pq)\n" -" if task is not REMOVED:\n" -" del entry_finder[task]\n" -" return task\n" -" raise KeyError('從空的優先佇列中 pop 出元素')" - -#: ../../library/heapq.rst:307 -msgid "Theory" -msgstr "原理" - -#: ../../library/heapq.rst:309 -msgid "" -"Heaps are arrays for which ``a[k] <= a[2*k+1]`` and ``a[k] <= a[2*k+2]`` for " -"all *k*, counting elements from 0. For the sake of comparison, non-existing " -"elements are considered to be infinite. The interesting property of a heap " -"is that ``a[0]`` is always its smallest element." -msgstr "" -"Heap 是一個陣列對於所有從0開始的 index *k* 都存在性質 ``a[k] <= a[2*k+1]`` " -"和 ``a[k] <= a[2*k+2]`` 。為了方便比較，不存在的元素被視為無限大。Heap 的一個" -"有趣的性質是：``a[0]`` 永遠是最小的元素。" - -#: ../../library/heapq.rst:314 -msgid "" -"The strange invariant above is meant to be an efficient memory " -"representation for a tournament. The numbers below are *k*, not ``a[k]``::" -msgstr "" -"上述乍看之下有些奇怪的不變式，是為了實作一個對記憶體來說有效率的方法，其表示" -"方式如同錦標賽一般。下列的數字為 *k*，而不是 ``a[k]``： ::" - -#: ../../library/heapq.rst:317 -msgid "" -" 0\n" -"\n" -" 1 2\n" -"\n" -" 3 4 5 6\n" -"\n" -" 7 8 9 10 11 12 13 14\n" -"\n" -"15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30" -msgstr "" -" 0\n" -"\n" -" 1 2\n" -"\n" -" 3 4 5 6\n" -"\n" -" 7 8 9 10 11 12 13 14\n" -"\n" -"15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30" - -#: ../../library/heapq.rst:327 -msgid "" -"In the tree above, each cell *k* is topping ``2*k+1`` and ``2*k+2``. In a " -"usual binary tournament we see in sports, each cell is the winner over the " -"two cells it tops, and we can trace the winner down the tree to see all " -"opponents s/he had. However, in many computer applications of such " -"tournaments, we do not need to trace the history of a winner. To be more " -"memory efficient, when a winner is promoted, we try to replace it by " -"something else at a lower level, and the rule becomes that a cell and the " -"two cells it tops contain three different items, but the top cell \"wins\" " -"over the two topped cells." -msgstr "" -"在上面的樹當中，每個單元 *k* 都會位在 ``2*k+1`` 與 ``2*k+2`` 上方。如同體育賽" -"事常見的錦標賽般，每個單元可視為其下方兩個單元當中的贏家，我們可以透過追溯整" -"棵樹來找到該贏家曾經對戰過的所有對手。然而，在許多電腦應用中，我們不需要追溯" -"贏家的完整對戰歷史。為了能更有效率地使用記憶體，當一個贏家晉級勝出時，我們用" -"下方較低層級的另一個項目來取代它，至此規則變為一個單元以及它下方兩個單元，包" -"含三個不同項目，但是最上方的單元「勝過」下方兩個單元。" - -#: ../../library/heapq.rst:336 -msgid "" -"If this heap invariant is protected at all time, index 0 is clearly the " -"overall winner. The simplest algorithmic way to remove it and find the " -"\"next\" winner is to move some loser (let's say cell 30 in the diagram " -"above) into the 0 position, and then percolate this new 0 down the tree, " -"exchanging values, until the invariant is re-established. This is clearly " -"logarithmic on the total number of items in the tree. By iterating over all " -"items, you get an *O*\\ (*n* log *n*) sort." -msgstr "" -"如果能確保滿足這個 heap 的不變式，那麼索引 0 顯然是最終的贏家。移除並找到「下" -"一個」贏家最簡單的演算法為：將一個輸家（例如上圖中的單元 30）移動到位置 0，然" -"後從新的位置 0 不斷與下方的位置交換值來向下傳遞，直到滿足不變式為止。這個過程" -"的複雜度顯然是樹的節點數目的對數級別。透過對所有項目疊代，可以得到一個複雜度" -"為 *O*\\ (*n* log *n*) 的排序。" - -#: ../../library/heapq.rst:343 -msgid "" -"A nice feature of this sort is that you can efficiently insert new items " -"while the sort is going on, provided that the inserted items are not " -"\"better\" than the last 0'th element you extracted. This is especially " -"useful in simulation contexts, where the tree holds all incoming events, and " -"the \"win\" condition means the smallest scheduled time. When an event " -"schedules other events for execution, they are scheduled into the future, so " -"they can easily go into the heap. So, a heap is a good structure for " -"implementing schedulers (this is what I used for my MIDI sequencer :-)." -msgstr "" -"這種排序有個好處，只要插入的項目沒有「贏過」你最後提取、索引為 0 的元素，你就" -"可以在排序進行的同時有效率地插入新項目。這在模擬情境當中特別有用，其中樹能夠" -"保存所有輸入事件，而「贏」意味著最小排程時間。當一個事件排程其它事件的執行" -"時，因這些事件仍在等待進行，所以很容易將它們插入 heap 當中。因此， heap 是一" -"個實現排程器的優秀資料結構（這就是我用以實作 MIDI 編曲器的方法 :-）。" - -#: ../../library/heapq.rst:352 -msgid "" -"Various structures for implementing schedulers have been extensively " -"studied, and heaps are good for this, as they are reasonably speedy, the " -"speed is almost constant, and the worst case is not much different than the " -"average case. However, there are other representations which are more " -"efficient overall, yet the worst cases might be terrible." -msgstr "" -"多種用於實作排程器的結構現今已被廣泛研究，heap 對此非常有用，因為它們速度相當" -"快，且速度幾乎不受其他因素影響，最壞情況與平均狀況差異無幾。也有其它整體說來" -"更有效率的方法，然而它們的最壞情況可能會非常糟糕。" - -#: ../../library/heapq.rst:358 -msgid "" -"Heaps are also very useful in big disk sorts. You most probably all know " -"that a big sort implies producing \"runs\" (which are pre-sorted sequences, " -"whose size is usually related to the amount of CPU memory), followed by a " -"merging passes for these runs, which merging is often very cleverly " -"organised [#]_. It is very important that the initial sort produces the " -"longest runs possible. Tournaments are a good way to achieve that. If, " -"using all the memory available to hold a tournament, you replace and " -"percolate items that happen to fit the current run, you'll produce runs " -"which are twice the size of the memory for random input, and much better for " -"input fuzzily ordered." -msgstr "" -"Heap 在為儲存於硬碟上的大量資料進行排序也非常有用。你可能已經知道，大量資料排" -"序涉及 \"runs\" 的產生（也就是預先排序的序列，其大小通常與 CPU 記憶體的大小有" -"關），之後再對這些 run 合併，而這些合併的過程通常相當巧妙 [#]_。很重要的一點" -"是，初始排序產生的 run 越長越好。錦標賽是達成這一點的好方法，若你用所有可用記" -"憶體來舉行一場錦標賽，並透過替換與向下交換來處理所有適配目前 run 的值，那麼對" -"於隨機產生的輸入，將可以產生長度兩倍於記憶體大小的 run。對於已模糊排序過的輸" -"入，效果更好。" - -#: ../../library/heapq.rst:368 -msgid "" -"Moreover, if you output the 0'th item on disk and get an input which may not " -"fit in the current tournament (because the value \"wins\" over the last " -"output value), it cannot fit in the heap, so the size of the heap " -"decreases. The freed memory could be cleverly reused immediately for " -"progressively building a second heap, which grows at exactly the same rate " -"the first heap is melting. When the first heap completely vanishes, you " -"switch heaps and start a new run. Clever and quite effective!" -msgstr "" -"此外，若你將索引為 0 的項目輸出至磁碟，並取得一個無法適配目前錦標賽的輸入（因" -"為該值「勝過」最後的輸出值），則該輸入值就無法插入至 heap 當中，因此 heap 的" -"大小會減小。釋放出來的記憶體可以巧妙地立即再被運用，逐步建構出第二個 heap，其" -"大小增加的速度會與第一個 heap 減少的速度一致。當第一個 heap 完全消失時，你可" -"以切換至第二個 heap 開啟一個新 run 。這真是個聰明且相當有效率的做法！" - -#: ../../library/heapq.rst:376 -msgid "" -"In a word, heaps are useful memory structures to know. I use them in a few " -"applications, and I think it is good to keep a 'heap' module around. :-)" -msgstr "" -"總結來說，heap 是值得了解的有用記憶體結構。我在一些應用中使用它們，我認為能有" -"一個 'heap' 模組是很棒的。:-)" - -#: ../../library/heapq.rst:380 -msgid "Footnotes" -msgstr "註解" - -#: ../../library/heapq.rst:381 -msgid "" -"The disk balancing algorithms which are current, nowadays, are more annoying " -"than clever, and this is a consequence of the seeking capabilities of the " -"disks. On devices which cannot seek, like big tape drives, the story was " -"quite different, and one had to be very clever to ensure (far in advance) " -"that each tape movement will be the most effective possible (that is, will " -"best participate at \"progressing\" the merge). Some tapes were even able " -"to read backwards, and this was also used to avoid the rewinding time. " -"Believe me, real good tape sorts were quite spectacular to watch! From all " -"times, sorting has always been a Great Art! :-)" -msgstr "" -"現今的磁碟平衡演算法因為硬碟查找能力而更加複雜難解。在沒有查找功能的裝置如大" -"型磁帶機，狀況又不一樣了，人們必須機智地確保（遠遠提前）每次於磁帶上移動都盡" -"可能是最有效率的（也就是盡可能更好地「推進」合併的過程）。有些磁帶甚至能夠向" -"後讀取，這也被用來避免倒轉的時間。相信我，真正優秀的磁帶排序看起來相當壯觀！" -"排序一直以來都是一門偉大的藝術！:-)" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Liang-Bo Wang , 2016 +# 周 忠毅 , 2016 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-11-07 00:14+0000\n" +"PO-Revision-Date: 2023-07-01 18:20+0800\n" +"Last-Translator: Liang-Bo Wang \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" +"X-Generator: Poedit 3.3.2\n" + +#: ../../library/heapq.rst:2 +msgid ":mod:`!heapq` --- Heap queue algorithm" +msgstr ":mod:`!heapq` --- 堆積佇列 (heap queue) 演算法" + +#: ../../library/heapq.rst:12 +msgid "**Source code:** :source:`Lib/heapq.py`" +msgstr "**原始碼：**\\ :source:`Lib/heapq.py`" + +#: ../../library/heapq.rst:16 +msgid "" +"This module provides an implementation of the heap queue algorithm, also " +"known as the priority queue algorithm." +msgstr "" +"這個模組實作了堆積佇列 (heap queue) 演算法，亦被稱為優先佇列 (priority " +"queue) 演算法。" + +#: ../../library/heapq.rst:19 +msgid "" +"Min-heaps are binary trees for which every parent node has a value less than " +"or equal to any of its children. We refer to this condition as the heap " +"invariant." +msgstr "" +"最小堆積 (min-heap) 是一顆二元樹，樹上每個父節點的值都小於或等於其子節點的" +"值。我們將這種情況稱為堆積性質不變 (heap invariant)。" + +#: ../../library/heapq.rst:23 +msgid "" +"For min-heaps, this implementation uses lists for which ``heap[k] <= " +"heap[2*k+1]`` and ``heap[k] <= heap[2*k+2]`` for all *k* for which the " +"compared elements exist. Elements are counted from zero. The interesting " +"property of a min-heap is that its smallest element is always the root, " +"``heap[0]``." +msgstr "" +"對於最小堆積，此實作使用串列，對於所有存在的被比較元素，*k* 都滿足 ``heap[k] " +"<= heap[2*k+1]`` 和 ``heap[k] <= heap[2*k+2]``。元素是從零開始計數。最小堆積" +"有一個有趣的性質：最小的元素永遠在根節點 ``heap[0]``。" + +#: ../../library/heapq.rst:29 +msgid "" +"Max-heaps satisfy the reverse invariant: every parent node has a value " +"*greater* than any of its children. These are implemented as lists for " +"which ``maxheap[2*k+1] <= maxheap[k]`` and ``maxheap[2*k+2] <= maxheap[k]`` " +"for all *k* for which the compared elements exist. The root, ``maxheap[0]``, " +"contains the *largest* element; ``heap.sort(reverse=True)`` maintains the " +"max-heap invariant." +msgstr "" + +#: ../../library/heapq.rst:36 +msgid "" +"The :mod:`!heapq` API differs from textbook heap algorithms in two aspects: " +"(a) We use zero-based indexing. This makes the relationship between the " +"index for a node and the indexes for its children slightly less obvious, but " +"is more suitable since Python uses zero-based indexing. (b) Textbooks often " +"focus on max-heaps, due to their suitability for in-place sorting. Our " +"implementation favors min-heaps as they better correspond to Python :class:" +"`lists `." +msgstr "" +":mod:`!heapq` API 與教科書上的堆積演算法在兩個方面不同：(a) 我們使用從零開始" +"的索引。這使得節點索引和其子節點索引之間的關係變得不那麼明顯，但由於 Python " +"使用從零開始的索引，所以這樣更適合。(b) 教科書通常專注於最大堆積，因為它們適" +"合原地排序。我們的實作偏向於最小堆積，因為它們更符合 Python :class:`串列 " +"`。" + +#: ../../library/heapq.rst:43 +msgid "" +"These two aspects make it possible to view the heap as a regular Python list " +"without surprises: ``heap[0]`` is the smallest item, and ``heap.sort()`` " +"maintains the heap invariant!" +msgstr "" +"這兩個特性使得可以將堆積視為一個普通的 Python 串列而不會有意外：``heap[0]`` " +"是最小的元素，而 ``heap.sort()`` 維持堆積性質不變！" + +#: ../../library/heapq.rst:47 +msgid "" +"Like :meth:`list.sort`, this implementation uses only the ``<`` operator for " +"comparisons, for both min-heaps and max-heaps." +msgstr "" + +#: ../../library/heapq.rst:50 +msgid "" +"In the API below, and in this documentation, the unqualified term *heap* " +"generally refers to a min-heap. The API for max-heaps is named using a " +"``_max`` suffix." +msgstr "" + +#: ../../library/heapq.rst:54 +msgid "" +"To create a heap, use a list initialized as ``[]``, or transform an existing " +"list into a min-heap or max-heap using the :func:`heapify` or :func:" +"`heapify_max` functions, respectively." +msgstr "" +"要建立一個堆積，使用初始化為 ``[]`` 的串列，或者分別使用 :func:`heapify` 或 :" +"func:`heapify_max` 函式將現有的串列轉換為最小堆積或最大堆積。" + +#: ../../library/heapq.rst:58 +msgid "The following functions are provided for min-heaps:" +msgstr "提供了以下針對最小堆積的函式：" + +#: ../../library/heapq.rst:63 +msgid "Transform list *x* into a min-heap, in-place, in linear time." +msgstr "在線性時間內將串列 *x* 原地轉換為最小堆積。" + +#: ../../library/heapq.rst:68 +msgid "" +"Push the value *item* onto the *heap*, maintaining the min-heap invariant." +msgstr "將值 *item* 推入 *heap*，並維持最小堆積性質不變。" + +#: ../../library/heapq.rst:73 +msgid "" +"Pop and return the smallest item from the *heap*, maintaining the min-heap " +"invariant. If the heap is empty, :exc:`IndexError` is raised. To access " +"the smallest item without popping it, use ``heap[0]``." +msgstr "" +"從 *heap* 取出並回傳最小的元素，維持最小堆積性質不變。如果堆積為空，會引發 :" +"exc:`IndexError`。若要在不取出的情況下存取最小元素，請使用 ``heap[0]``。" + +#: ../../library/heapq.rst:80 +msgid "" +"Push *item* on the heap, then pop and return the smallest item from the " +"*heap*. The combined action runs more efficiently than :func:`heappush` " +"followed by a separate call to :func:`heappop`." +msgstr "" +"將 *item* 放入 heap ，接著從 *heap* 取出並回傳最小的元素。這個組合函式比呼" +"叫 :func:`heappush` 之後呼叫 :func:`heappop` 更有效率。" + +#: ../../library/heapq.rst:87 +msgid "" +"Pop and return the smallest item from the *heap*, and also push the new " +"*item*. The heap size doesn't change. If the heap is empty, :exc:" +"`IndexError` is raised." +msgstr "" +"從 *heap* 取出並回傳最小的元素，接著將新的 *item* 放進heap。heap 的大小不會改" +"變。如果 heap 是空的會產生 :exc:`IndexError` 錯誤。" + +#: ../../library/heapq.rst:90 +msgid "" +"This one step operation is more efficient than a :func:`heappop` followed " +"by :func:`heappush` and can be more appropriate when using a fixed-size " +"heap. The pop/push combination always returns an element from the heap and " +"replaces it with *item*." +msgstr "" +"這個一次完成的操作會比呼叫 :func:`heappop` 之後呼叫 :func:`heappush` 更有效" +"率，並在維護 heap 的大小不變時更為適當，取出/放入的組合函式一定會從 heap 回傳" +"一個元素並用 *item* 取代他。" + +#: ../../library/heapq.rst:95 +msgid "" +"The value returned may be larger than the *item* added. If that isn't " +"desired, consider using :func:`heappushpop` instead. Its push/pop " +"combination returns the smaller of the two values, leaving the larger value " +"on the heap." +msgstr "" +"函式的回傳值可能會大於被加入的 *item* 。如果這不是你期望發生的，可以考慮使" +"用 :func:`heappushpop` 替代，他會回傳 heap 的最小值和 *item* 兩個當中比較小的" +"那個，並將大的留在 heap 內。" + +#: ../../library/heapq.rst:101 +msgid "For max-heaps, the following functions are provided:" +msgstr "提供以下針對最大堆積的函式：" + +#: ../../library/heapq.rst:106 +msgid "Transform list *x* into a max-heap, in-place, in linear time." +msgstr "在線性時間內將串列 *x* 原地轉換為最大堆積。" + +#: ../../library/heapq.rst:113 +msgid "" +"Push the value *item* onto the max-heap *heap*, maintaining the max-heap " +"invariant." +msgstr "將值 *item* 推入最大堆積 *heap*，維持最大堆積性質不變。" + +#: ../../library/heapq.rst:121 +msgid "" +"Pop and return the largest item from the max-heap *heap*, maintaining the " +"max-heap invariant. If the max-heap is empty, :exc:`IndexError` is raised. " +"To access the largest item without popping it, use ``maxheap[0]``." +msgstr "" +"從最大堆積 *heap* 取出並回傳最大的元素，維持最大堆積性質不變。如果最大堆積為" +"空，會引發 :exc:`IndexError`。若要在不取出的情況下存取最大元素，請使用 " +"``maxheap[0]``。" + +#: ../../library/heapq.rst:130 +msgid "" +"Push *item* on the max-heap *heap*, then pop and return the largest item " +"from *heap*. The combined action runs more efficiently than :func:" +"`heappush_max` followed by a separate call to :func:`heappop_max`." +msgstr "" +"將 *item* 推入 max-heap *heap*，然後取出並回傳 *heap* 中最大的元素。這個組合" +"動作比先呼叫 :func:`heappush_max` 再單獨呼叫 :func:`heappop_max` 更有效率。" + +#: ../../library/heapq.rst:140 +msgid "" +"Pop and return the largest item from the max-heap *heap* and also push the " +"new *item*. The max-heap size doesn't change. If the max-heap is empty, :exc:" +"`IndexError` is raised." +msgstr "" +"從最大堆積 *heap* 取出並回傳最大的元素，同時推入新的 *item*。最大堆積的大小不" +"會改變。如果最大堆積為空，會引發 :exc:`IndexError`。" + +#: ../../library/heapq.rst:145 +msgid "" +"The value returned may be smaller than the *item* added. Refer to the " +"analogous function :func:`heapreplace` for detailed usage notes." +msgstr "" + +#: ../../library/heapq.rst:151 +msgid "The module also offers three general purpose functions based on heaps." +msgstr "這個模組也提供三個利用 heap 實作的一般用途函式" + +#: ../../library/heapq.rst:156 +msgid "" +"Merge multiple sorted inputs into a single sorted output (for example, merge " +"timestamped entries from multiple log files). Returns an :term:`iterator` " +"over the sorted values." +msgstr "" +"合併多個已排序的輸入並產生單一且已排序的輸出（舉例：合併來自多個 log 檔中有時" +"間戳記的項目）。回傳一個 :term:`iterator` 包含已經排序的值。" + +#: ../../library/heapq.rst:160 +msgid "" +"Similar to ``sorted(itertools.chain(*iterables))`` but returns an iterable, " +"does not pull the data into memory all at once, and assumes that each of the " +"input streams is already sorted (smallest to largest)." +msgstr "" +"和 ``sorted(itertools.chain(*iterables))`` 類似但回傳值是一個 iterable ，不會" +"一次把所有資料都放進記憶體中，並且假設每一個輸入都已經（由小到大）排序過了。" + +#: ../../library/heapq.rst:164 +msgid "" +"Has two optional arguments which must be specified as keyword arguments." +msgstr "有兩個選用參數，指定時必須被當作關鍵字參數指定。" + +#: ../../library/heapq.rst:166 +msgid "" +"*key* specifies a :term:`key function` of one argument that is used to " +"extract a comparison key from each input element. The default value is " +"``None`` (compare the elements directly)." +msgstr "" +"*key* 參數指定了一個 :term:`key function` 引數，用來從每一個輸入的元素中決定" +"一個比較的依據。預設的值是 ``None`` （直接比較元素）。" + +#: ../../library/heapq.rst:170 +msgid "" +"*reverse* is a boolean value. If set to ``True``, then the input elements " +"are merged as if each comparison were reversed. To achieve behavior similar " +"to ``sorted(itertools.chain(*iterables), reverse=True)``, all iterables must " +"be sorted from largest to smallest." +msgstr "" +"*reverse* 是一個布林值，如果設定為 ``True`` ，則輸入的元素將以相反的比較順序" +"進行合併。為了達成類似 ``sorted(itertools.chain(*iterables), reverse=True)`` " +"的行為，所有 iterables 必須由大到小排序。" + +#: ../../library/heapq.rst:175 +msgid "Added the optional *key* and *reverse* parameters." +msgstr "加入選用參數 *key* 和 *reverse* 。" + +#: ../../library/heapq.rst:181 +msgid "" +"Return a list with the *n* largest elements from the dataset defined by " +"*iterable*. *key*, if provided, specifies a function of one argument that " +"is used to extract a comparison key from each element in *iterable* (for " +"example, ``key=str.lower``). Equivalent to: ``sorted(iterable, key=key, " +"reverse=True)[:n]``." +msgstr "" +"回傳一個包含資料 *iterable* 中前 *n* 大元素的 list 。如果有指定 *key* 引數，" +"*key* 會是只有一個引數的函式，用來從每一個在 *iterable* 中的元素提取一個比較" +"的依據（例如 ``key=str.lower`` ）。效果相當於 ``sorted(iterable, key=key, " +"reverse=True)[:n]`` 。" + +#: ../../library/heapq.rst:190 +msgid "" +"Return a list with the *n* smallest elements from the dataset defined by " +"*iterable*. *key*, if provided, specifies a function of one argument that " +"is used to extract a comparison key from each element in *iterable* (for " +"example, ``key=str.lower``). Equivalent to: ``sorted(iterable, key=key)[:" +"n]``." +msgstr "" +"回傳一個包含資料 *iterable* 中前 *n* 小元素的 list 。如果有指定 *key* 引數，" +"*key* 會是只有一個引數的函式，用來從每一個在 *iterable* 中的元素提取一個比較" +"的依據（例如 ``key=str.lower`` ）。效果相當於 ``sorted(iterable, key=key)[:" +"n]`` 。" + +#: ../../library/heapq.rst:196 +msgid "" +"The latter two functions perform best for smaller values of *n*. For larger " +"values, it is more efficient to use the :func:`sorted` function. Also, when " +"``n==1``, it is more efficient to use the built-in :func:`min` and :func:" +"`max` functions. If repeated usage of these functions is required, consider " +"turning the iterable into an actual heap." +msgstr "" +"後兩個函式在 *n* 值比較小時有最好的表現。對於較大的 *n* 值，只用 :func:" +"`sorted` 函式會更有效率。同樣地，當 ``n==1`` 時，使用內建函式 :func:`min` " +"和 :func:`max` 會有更好的效率。如果需要重複使用這些函式，可以考慮將 iterable " +"轉成真正的 heap 。" + +#: ../../library/heapq.rst:204 +msgid "Basic Examples" +msgstr "基礎範例" + +#: ../../library/heapq.rst:206 +msgid "" +"A `heapsort `_ can be implemented by " +"pushing all values onto a heap and then popping off the smallest values one " +"at a time::" +msgstr "" +"`堆積排序 (heapsort) `_ 可以透過將所" +"有的值推入一個 heap，並且從 heap 中一個接一個彈出最小元素來實作： ::" + +#: ../../library/heapq.rst:210 +msgid "" +">>> def heapsort(iterable):\n" +"... h = []\n" +"... for value in iterable:\n" +"... heappush(h, value)\n" +"... return [heappop(h) for i in range(len(h))]\n" +"...\n" +">>> heapsort([1, 3, 5, 7, 9, 2, 4, 6, 8, 0])\n" +"[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]" +msgstr "" +">>> def heapsort(iterable):\n" +"... h = []\n" +"... for value in iterable:\n" +"... heappush(h, value)\n" +"... return [heappop(h) for i in range(len(h))]\n" +"...\n" +">>> heapsort([1, 3, 5, 7, 9, 2, 4, 6, 8, 0])\n" +"[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]" + +#: ../../library/heapq.rst:219 +msgid "" +"This is similar to ``sorted(iterable)``, but unlike :func:`sorted`, this " +"implementation is not stable." +msgstr "" +"雖然類似 ``sorted(iterable)`` ，但跟 :func:`sorted` 不同的是，這個實作不是 " +"stable 的排序。" + +#: ../../library/heapq.rst:222 +msgid "" +"Heap elements can be tuples. This is useful for assigning comparison values " +"(such as task priorities) alongside the main record being tracked::" +msgstr "" +"Heap 中的元素可以是 tuple 。這有利於將要比較的值（例如一個 task 的優先度）和" +"主要資料放在一起排序： ::" + +#: ../../library/heapq.rst:225 +msgid "" +">>> h = []\n" +">>> heappush(h, (5, 'write code'))\n" +">>> heappush(h, (7, 'release product'))\n" +">>> heappush(h, (1, 'write spec'))\n" +">>> heappush(h, (3, 'create tests'))\n" +">>> heappop(h)\n" +"(1, 'write spec')" +msgstr "" +">>> h = []\n" +">>> heappush(h, (5, 'write code'))\n" +">>> heappush(h, (7, 'release product'))\n" +">>> heappush(h, (1, 'write spec'))\n" +">>> heappush(h, (3, 'create tests'))\n" +">>> heappop(h)\n" +"(1, 'write spec')" + +#: ../../library/heapq.rst:235 +msgid "Priority Queue Implementation Notes" +msgstr "優先佇列實作細節" + +#: ../../library/heapq.rst:237 +msgid "" +"A `priority queue `_ is common " +"use for a heap, and it presents several implementation challenges:" +msgstr "" +"`優先佇列 (priority queue) `_ " +"是 heap 的常見用途之一，實作優先佇列伴隨著下列挑戰：" + +#: ../../library/heapq.rst:240 +msgid "" +"Sort stability: how do you get two tasks with equal priorities to be " +"returned in the order they were originally added?" +msgstr "" +"排序的穩定性：如何將兩個擁有相同優先次序 (priority) 的 task 按照他們被加入的" +"順序回傳?" + +#: ../../library/heapq.rst:243 +msgid "" +"Tuple comparison breaks for (priority, task) pairs if the priorities are " +"equal and the tasks do not have a default comparison order." +msgstr "" +"Tuple的排序在某些情況下會壞掉，例如當 Tuple (priority, task) 的 priorities 相" +"等且 tasks 沒有一個預設的排序時。" + +#: ../../library/heapq.rst:246 +msgid "" +"If the priority of a task changes, how do you move it to a new position in " +"the heap?" +msgstr "" +"當一個 heap 中 task 的 priority 改變時，如何將它移到 heap 正確的位置上?" + +#: ../../library/heapq.rst:249 +msgid "" +"Or if a pending task needs to be deleted, how do you find it and remove it " +"from the queue?" +msgstr "" +"或者一個還沒被解決的 task 需要被刪除時，要如何從佇列中找到並刪除指定的 task?" + +#: ../../library/heapq.rst:252 +msgid "" +"A solution to the first two challenges is to store entries as 3-element list " +"including the priority, an entry count, and the task. The entry count " +"serves as a tie-breaker so that two tasks with the same priority are " +"returned in the order they were added. And since no two entry counts are the " +"same, the tuple comparison will never attempt to directly compare two tasks." +msgstr "" +"一個針對前兩個問題的解法是：儲存一個包含 priority、entry count 和 task 三個元" +"素的 tuple 。兩個 task 有相同 priority 時，entry count 會讓兩個 task 能根據加" +"入的順序排序。因為沒有任何兩個 task 擁有相同的 entry count，所以永遠不會直接" +"使用 task 做比較。" + +#: ../../library/heapq.rst:258 +msgid "" +"Another solution to the problem of non-comparable tasks is to create a " +"wrapper class that ignores the task item and only compares the priority " +"field::" +msgstr "" +"task 無法比較的另一個解決方案是建立一個包裝器類別，該類別忽略 task 項目，只比" +"較優先等級： ::" + +#: ../../library/heapq.rst:261 +msgid "" +"from dataclasses import dataclass, field\n" +"from typing import Any\n" +"\n" +"@dataclass(order=True)\n" +"class PrioritizedItem:\n" +" priority: int\n" +" item: Any=field(compare=False)" +msgstr "" +"from dataclasses import dataclass, field\n" +"from typing import Any\n" +"\n" +"@dataclass(order=True)\n" +"class PrioritizedItem:\n" +" priority: int\n" +" item: Any=field(compare=False)" + +#: ../../library/heapq.rst:269 +msgid "" +"The remaining challenges revolve around finding a pending task and making " +"changes to its priority or removing it entirely. Finding a task can be done " +"with a dictionary pointing to an entry in the queue." +msgstr "" +"剩下的問題可以藉由找到要刪除的 task 並更改它的 priority 或者直接將它移除。尋" +"找一個 task 可以使用一個 dictionary 指向佇列當中的 entry 。" + +#: ../../library/heapq.rst:273 +msgid "" +"Removing the entry or changing its priority is more difficult because it " +"would break the heap structure invariants. So, a possible solution is to " +"mark the entry as removed and add a new entry with the revised priority::" +msgstr "" +"移除 entry 或更改它的 priority 更為困難，因為這會破壞 heap 的性質。所以一個可" +"行的方案是將原本的 entry 做一個標記表示它已經被刪除，並新增一個擁有新的 " +"priority 的 entry： ::" + +#: ../../library/heapq.rst:277 +msgid "" +"pq = [] # list of entries arranged in a heap\n" +"entry_finder = {} # mapping of tasks to entries\n" +"REMOVED = '' # placeholder for a removed task\n" +"counter = itertools.count() # unique sequence count\n" +"\n" +"def add_task(task, priority=0):\n" +" 'Add a new task or update the priority of an existing task'\n" +" if task in entry_finder:\n" +" remove_task(task)\n" +" count = next(counter)\n" +" entry = [priority, count, task]\n" +" entry_finder[task] = entry\n" +" heappush(pq, entry)\n" +"\n" +"def remove_task(task):\n" +" 'Mark an existing task as REMOVED. Raise KeyError if not found.'\n" +" entry = entry_finder.pop(task)\n" +" entry[-1] = REMOVED\n" +"\n" +"def pop_task():\n" +" 'Remove and return the lowest priority task. Raise KeyError if empty.'\n" +" while pq:\n" +" priority, count, task = heappop(pq)\n" +" if task is not REMOVED:\n" +" del entry_finder[task]\n" +" return task\n" +" raise KeyError('pop from an empty priority queue')" +msgstr "" +"pq = [] # 在 heap 中的 entry 串列\n" +"entry_finder = {} # task 對應到 entry 的對映\n" +"REMOVED = '' # 被刪除的 task 的佔位器\n" +"counter = itertools.count() # 唯一的序列計數\n" +"\n" +"def add_task(task, priority=0):\n" +" '新增一個 task 或更新一個已存在 task 的 priority'\n" +" if task in entry_finder:\n" +" remove_task(task)\n" +" count = next(counter)\n" +" entry = [priority, count, task]\n" +" entry_finder[task] = entry\n" +" heappush(pq, entry)\n" +"\n" +"def remove_task(task):\n" +" '將一個已存在的 task 標記為 REMOVED。如果找不到會引發 KeyError。'\n" +" entry = entry_finder.pop(task)\n" +" entry[-1] = REMOVED\n" +"\n" +"def pop_task():\n" +" '移除並回傳最低 priority 的 task。如果 heap 是空的會引發 KeyError。'\n" +" while pq:\n" +" priority, count, task = heappop(pq)\n" +" if task is not REMOVED:\n" +" del entry_finder[task]\n" +" return task\n" +" raise KeyError('從空的優先佇列中 pop 出元素')" + +#: ../../library/heapq.rst:307 +msgid "Theory" +msgstr "原理" + +#: ../../library/heapq.rst:309 +msgid "" +"Heaps are arrays for which ``a[k] <= a[2*k+1]`` and ``a[k] <= a[2*k+2]`` for " +"all *k*, counting elements from 0. For the sake of comparison, non-existing " +"elements are considered to be infinite. The interesting property of a heap " +"is that ``a[0]`` is always its smallest element." +msgstr "" +"Heap 是一個陣列對於所有從0開始的 index *k* 都存在性質 ``a[k] <= a[2*k+1]`` " +"和 ``a[k] <= a[2*k+2]`` 。為了方便比較，不存在的元素被視為無限大。Heap 的一個" +"有趣的性質是：``a[0]`` 永遠是最小的元素。" + +#: ../../library/heapq.rst:314 +msgid "" +"The strange invariant above is meant to be an efficient memory " +"representation for a tournament. The numbers below are *k*, not ``a[k]``::" +msgstr "" +"上述乍看之下有些奇怪的不變式，是為了實作一個對記憶體來說有效率的方法，其表示" +"方式如同錦標賽一般。下列的數字為 *k*，而不是 ``a[k]``： ::" + +#: ../../library/heapq.rst:317 +msgid "" +" 0\n" +"\n" +" 1 2\n" +"\n" +" 3 4 5 6\n" +"\n" +" 7 8 9 10 11 12 13 14\n" +"\n" +"15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30" +msgstr "" +" 0\n" +"\n" +" 1 2\n" +"\n" +" 3 4 5 6\n" +"\n" +" 7 8 9 10 11 12 13 14\n" +"\n" +"15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30" + +#: ../../library/heapq.rst:327 +msgid "" +"In the tree above, each cell *k* is topping ``2*k+1`` and ``2*k+2``. In a " +"usual binary tournament we see in sports, each cell is the winner over the " +"two cells it tops, and we can trace the winner down the tree to see all " +"opponents s/he had. However, in many computer applications of such " +"tournaments, we do not need to trace the history of a winner. To be more " +"memory efficient, when a winner is promoted, we try to replace it by " +"something else at a lower level, and the rule becomes that a cell and the " +"two cells it tops contain three different items, but the top cell \"wins\" " +"over the two topped cells." +msgstr "" +"在上面的樹當中，每個單元 *k* 都會位在 ``2*k+1`` 與 ``2*k+2`` 上方。如同體育賽" +"事常見的錦標賽般，每個單元可視為其下方兩個單元當中的贏家，我們可以透過追溯整" +"棵樹來找到該贏家曾經對戰過的所有對手。然而，在許多電腦應用中，我們不需要追溯" +"贏家的完整對戰歷史。為了能更有效率地使用記憶體，當一個贏家晉級勝出時，我們用" +"下方較低層級的另一個項目來取代它，至此規則變為一個單元以及它下方兩個單元，包" +"含三個不同項目，但是最上方的單元「勝過」下方兩個單元。" + +#: ../../library/heapq.rst:336 +msgid "" +"If this heap invariant is protected at all time, index 0 is clearly the " +"overall winner. The simplest algorithmic way to remove it and find the " +"\"next\" winner is to move some loser (let's say cell 30 in the diagram " +"above) into the 0 position, and then percolate this new 0 down the tree, " +"exchanging values, until the invariant is re-established. This is clearly " +"logarithmic on the total number of items in the tree. By iterating over all " +"items, you get an *O*\\ (*n* log *n*) sort." +msgstr "" +"如果能確保滿足這個 heap 的不變式，那麼索引 0 顯然是最終的贏家。移除並找到「下" +"一個」贏家最簡單的演算法為：將一個輸家（例如上圖中的單元 30）移動到位置 0，然" +"後從新的位置 0 不斷與下方的位置交換值來向下傳遞，直到滿足不變式為止。這個過程" +"的複雜度顯然是樹的節點數目的對數級別。透過對所有項目疊代，可以得到一個複雜度" +"為 *O*\\ (*n* log *n*) 的排序。" + +#: ../../library/heapq.rst:343 +msgid "" +"A nice feature of this sort is that you can efficiently insert new items " +"while the sort is going on, provided that the inserted items are not " +"\"better\" than the last 0'th element you extracted. This is especially " +"useful in simulation contexts, where the tree holds all incoming events, and " +"the \"win\" condition means the smallest scheduled time. When an event " +"schedules other events for execution, they are scheduled into the future, so " +"they can easily go into the heap. So, a heap is a good structure for " +"implementing schedulers (this is what I used for my MIDI sequencer :-)." +msgstr "" +"這種排序有個好處，只要插入的項目沒有「贏過」你最後提取、索引為 0 的元素，你就" +"可以在排序進行的同時有效率地插入新項目。這在模擬情境當中特別有用，其中樹能夠" +"保存所有輸入事件，而「贏」意味著最小排程時間。當一個事件排程其它事件的執行" +"時，因這些事件仍在等待進行，所以很容易將它們插入 heap 當中。因此， heap 是一" +"個實現排程器的優秀資料結構（這就是我用以實作 MIDI 編曲器的方法 :-）。" + +#: ../../library/heapq.rst:352 +msgid "" +"Various structures for implementing schedulers have been extensively " +"studied, and heaps are good for this, as they are reasonably speedy, the " +"speed is almost constant, and the worst case is not much different than the " +"average case. However, there are other representations which are more " +"efficient overall, yet the worst cases might be terrible." +msgstr "" +"多種用於實作排程器的結構現今已被廣泛研究，heap 對此非常有用，因為它們速度相當" +"快，且速度幾乎不受其他因素影響，最壞情況與平均狀況差異無幾。也有其它整體說來" +"更有效率的方法，然而它們的最壞情況可能會非常糟糕。" + +#: ../../library/heapq.rst:358 +msgid "" +"Heaps are also very useful in big disk sorts. You most probably all know " +"that a big sort implies producing \"runs\" (which are pre-sorted sequences, " +"whose size is usually related to the amount of CPU memory), followed by a " +"merging passes for these runs, which merging is often very cleverly " +"organised [#]_. It is very important that the initial sort produces the " +"longest runs possible. Tournaments are a good way to achieve that. If, " +"using all the memory available to hold a tournament, you replace and " +"percolate items that happen to fit the current run, you'll produce runs " +"which are twice the size of the memory for random input, and much better for " +"input fuzzily ordered." +msgstr "" +"Heap 在為儲存於硬碟上的大量資料進行排序也非常有用。你可能已經知道，大量資料排" +"序涉及 \"runs\" 的產生（也就是預先排序的序列，其大小通常與 CPU 記憶體的大小有" +"關），之後再對這些 run 合併，而這些合併的過程通常相當巧妙 [#]_。很重要的一點" +"是，初始排序產生的 run 越長越好。錦標賽是達成這一點的好方法，若你用所有可用記" +"憶體來舉行一場錦標賽，並透過替換與向下交換來處理所有適配目前 run 的值，那麼對" +"於隨機產生的輸入，將可以產生長度兩倍於記憶體大小的 run。對於已模糊排序過的輸" +"入，效果更好。" + +#: ../../library/heapq.rst:368 +msgid "" +"Moreover, if you output the 0'th item on disk and get an input which may not " +"fit in the current tournament (because the value \"wins\" over the last " +"output value), it cannot fit in the heap, so the size of the heap " +"decreases. The freed memory could be cleverly reused immediately for " +"progressively building a second heap, which grows at exactly the same rate " +"the first heap is melting. When the first heap completely vanishes, you " +"switch heaps and start a new run. Clever and quite effective!" +msgstr "" +"此外，若你將索引為 0 的項目輸出至磁碟，並取得一個無法適配目前錦標賽的輸入（因" +"為該值「勝過」最後的輸出值），則該輸入值就無法插入至 heap 當中，因此 heap 的" +"大小會減小。釋放出來的記憶體可以巧妙地立即再被運用，逐步建構出第二個 heap，其" +"大小增加的速度會與第一個 heap 減少的速度一致。當第一個 heap 完全消失時，你可" +"以切換至第二個 heap 開啟一個新 run 。這真是個聰明且相當有效率的做法！" + +#: ../../library/heapq.rst:376 +msgid "" +"In a word, heaps are useful memory structures to know. I use them in a few " +"applications, and I think it is good to keep a 'heap' module around. :-)" +msgstr "" +"總結來說，heap 是值得了解的有用記憶體結構。我在一些應用中使用它們，我認為能有" +"一個 'heap' 模組是很棒的。:-)" + +#: ../../library/heapq.rst:380 +msgid "Footnotes" +msgstr "註解" + +#: ../../library/heapq.rst:381 +msgid "" +"The disk balancing algorithms which are current, nowadays, are more annoying " +"than clever, and this is a consequence of the seeking capabilities of the " +"disks. On devices which cannot seek, like big tape drives, the story was " +"quite different, and one had to be very clever to ensure (far in advance) " +"that each tape movement will be the most effective possible (that is, will " +"best participate at \"progressing\" the merge). Some tapes were even able " +"to read backwards, and this was also used to avoid the rewinding time. " +"Believe me, real good tape sorts were quite spectacular to watch! From all " +"times, sorting has always been a Great Art! :-)" +msgstr "" +"現今的磁碟平衡演算法因為硬碟查找能力而更加複雜難解。在沒有查找功能的裝置如大" +"型磁帶機，狀況又不一樣了，人們必須機智地確保（遠遠提前）每次於磁帶上移動都盡" +"可能是最有效率的（也就是盡可能更好地「推進」合併的過程）。有些磁帶甚至能夠向" +"後讀取，這也被用來避免倒轉的時間。相信我，真正優秀的磁帶排序看起來相當壯觀！" +"排序一直以來都是一門偉大的藝術！:-)" diff --git a/library/hmac.po b/library/hmac.po index 127397cc41..54fb738ff3 100644 --- a/library/hmac.po +++ b/library/hmac.po @@ -1,223 +1,223 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Adrian Liaw , 2018 -# Phil Lin , 2022 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-09-04 00:15+0000\n" -"PO-Revision-Date: 2022-03-30 00:16+0800\n" -"Last-Translator: Phil Lin \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" -"X-Generator: Poedit 3.0.1\n" - -#: ../../library/hmac.rst:2 -msgid ":mod:`!hmac` --- Keyed-Hashing for Message Authentication" -msgstr ":mod:`!hmac` --- 基於金鑰雜湊的訊息驗證" - -#: ../../library/hmac.rst:10 -msgid "**Source code:** :source:`Lib/hmac.py`" -msgstr "**原始碼：**\\ :source:`Lib/hmac.py`" - -#: ../../library/hmac.rst:14 -msgid "" -"This module implements the HMAC algorithm as described by :rfc:`2104`. The " -"interface allows to use any hash function with a *fixed* digest size. In " -"particular, extendable output functions such as SHAKE-128 or SHAKE-256 " -"cannot be used with HMAC." -msgstr "" -"此模組實作了 :rfc:`2014` 所描述的 HMAC 演算法。此介面允許使用具有\\ *固定*\\ " -"摘要 (digest) 長度的任意雜湊函式。要特別注意的是擴充輸出函式（如 SHAKE-128 " -"或 SHAKE-256）不能與 HMAC 一起使用。" - -#: ../../library/hmac.rst:22 -msgid "" -"Return a new hmac object. *key* is a bytes or bytearray object giving the " -"secret key. If *msg* is present, the method call ``update(msg)`` is made. " -"*digestmod* is the digest name, digest constructor or module for the HMAC " -"object to use. It may be any name suitable to :func:`hashlib.new`. Despite " -"its argument position, it is required." -msgstr "" -"回傳一個新的 hmac 物件。*key* 是一個指定密鑰的 bytes（位元組）或 bytearray 物" -"件。如果提供了 *msg*，將會呼叫 ``update(msg)`` 方法。*digestmod* 為 HMAC 物件" -"所用的摘要名稱、摘要建構函式 (constructor) 或模組。它可以是適用於 :func:" -"`hashlib.new` 的任何名稱。儘管該引數的位置在後，但它卻是必須的。" - -#: ../../library/hmac.rst:28 -msgid "" -"Parameter *key* can be a bytes or bytearray object. Parameter *msg* can be " -"of any type supported by :mod:`hashlib`. Parameter *digestmod* can be the " -"name of a hash algorithm." -msgstr "" -"參數 *key* 可以為 bytes 或 bytearray 物件。參數 *msg* 可以為 :mod:`hashlib` " -"所支援的任意型別。參數 *digestmod* 可以為雜湊演算法的名稱。" - -#: ../../library/hmac.rst:33 -msgid "" -"The *digestmod* argument is now required. Pass it as a keyword argument to " -"avoid awkwardness when you do not have an initial *msg*." -msgstr "" -"*digestmod* 引數現在是必須的。請將其作為關鍵字引數傳入以避免當你沒有初始 " -"*msg* 時導致的麻煩。" - -#: ../../library/hmac.rst:40 -msgid "" -"Return digest of *msg* for given secret *key* and *digest*. The function is " -"equivalent to ``HMAC(key, msg, digest).digest()``, but uses an optimized C " -"or inline implementation, which is faster for messages that fit into memory. " -"The parameters *key*, *msg*, and *digest* have the same meaning as in :func:" -"`~hmac.new`." -msgstr "" -"基於給定密鑰 *key* 和 *digest* 回傳 *msg* 的摘要。此函式等價於 ``HMAC(key, " -"msg, digest).digest()``，但使用了最佳化的 C 或 行內實作（inline " -"implementation），對放入記憶體的訊息能處理得更快。參數 *key*、*msg* 和 " -"*digest* 在 :func:`~hmac.new` 中具有相同含義。" - -#: ../../library/hmac.rst:46 -msgid "" -"CPython implementation detail, the optimized C implementation is only used " -"when *digest* is a string and name of a digest algorithm, which is supported " -"by OpenSSL." -msgstr "" -"作為 CPython 的實現細節，C 的最佳化實作只有當 *digest* 為字串並且是一個 " -"OpenSSL 所支援的摘要演算法的名稱時才會被使用。" - -#: ../../library/hmac.rst:55 -msgid "An HMAC object has the following methods:" -msgstr "HMAC 物件具有下列方法 (method)：" - -#: ../../library/hmac.rst:59 -msgid "" -"Update the hmac object with *msg*. Repeated calls are equivalent to a " -"single call with the concatenation of all the arguments: ``m.update(a); m." -"update(b)`` is equivalent to ``m.update(a + b)``." -msgstr "" -"用 *msg* 來更新 hmac 物件。重複呼叫相當於單次呼叫並傳入所有引數的拼接結果：" -"``m.update(a); m.update(b)`` 等價於 ``m.update(a + b)``。" - -#: ../../library/hmac.rst:63 -msgid "Parameter *msg* can be of any type supported by :mod:`hashlib`." -msgstr "參數 *msg* 可以是 :mod:`hashlib` 所支援的任何型別。" - -#: ../../library/hmac.rst:69 -msgid "" -"Return the digest of the bytes passed to the :meth:`update` method so far. " -"This bytes object will be the same length as the *digest_size* of the digest " -"given to the constructor. It may contain non-ASCII bytes, including NUL " -"bytes." -msgstr "" -"回傳目前已傳給 :meth:`update` 方法的 bytes 摘要。這個 bytes 物件的長度會與傳" -"給建構函式的摘要 *digest_size* 的長度相同。它可以包含 NUL bytes 以及 non-" -"ASCII bytes。" - -#: ../../library/hmac.rst:76 -msgid "" -"When comparing the output of :meth:`digest` to an externally supplied digest " -"during a verification routine, it is recommended to use the :func:" -"`compare_digest` function instead of the ``==`` operator to reduce the " -"vulnerability to timing attacks." -msgstr "" -"在一個例行的驗證事務運行期間，將 :meth:`digest` 的輸出與外部提供的摘要進行比" -"較時，建議使用 :func:`compare_digest` 函式而不是 ``==`` 運算子以減少被定時攻" -"擊時的漏洞。" - -#: ../../library/hmac.rst:84 -msgid "" -"Like :meth:`digest` except the digest is returned as a string twice the " -"length containing only hexadecimal digits. This may be used to exchange the " -"value safely in email or other non-binary environments." -msgstr "" -"像是 :meth:`digest` 但摘要的回傳形式為兩倍長度的字串，且此字串只包含十六進位" -"數位。這可以被用於在電子郵件或其他非二進位制環境中安全地交換數據。" - -#: ../../library/hmac.rst:90 -msgid "" -"When comparing the output of :meth:`hexdigest` to an externally supplied " -"digest during a verification routine, it is recommended to use the :func:" -"`compare_digest` function instead of the ``==`` operator to reduce the " -"vulnerability to timing attacks." -msgstr "" -"在一個例行的驗證事務運行期間，將 :meth:`hexdigest` 的輸出與外部提供的摘要進行" -"比較時，建議使用 :func:`compare_digest` 函式而不是 ``==`` 運算子以減少被定時" -"攻擊時的漏洞。" - -#: ../../library/hmac.rst:98 -msgid "" -"Return a copy (\"clone\") of the hmac object. This can be used to " -"efficiently compute the digests of strings that share a common initial " -"substring." -msgstr "" -"回傳 hmac 物件的拷貝 (\"clone\")。這可以被用來有效率地計算那些共享相同初始子" -"字串的字串的摘要。" - -#: ../../library/hmac.rst:102 -msgid "A hash object has the following attributes:" -msgstr "一個 hash 物件具有以下屬性：" - -#: ../../library/hmac.rst:106 -msgid "The size of the resulting HMAC digest in bytes." -msgstr "以 bytes 表示最終 HMAC 摘要的大小。" - -#: ../../library/hmac.rst:110 -msgid "The internal block size of the hash algorithm in bytes." -msgstr "以 bytes 表示雜湊演算法的內部區塊大小。" - -#: ../../library/hmac.rst:116 -msgid "The canonical name of this HMAC, always lowercase, e.g. ``hmac-md5``." -msgstr "HMAC 的正準名稱總是為小寫形式，例如 ``hmac-md5``。" - -#: ../../library/hmac.rst:121 -msgid "" -"Removed the undocumented attributes ``HMAC.digest_cons``, ``HMAC.inner``, " -"and ``HMAC.outer``." -msgstr "" -"未寫入文件的屬性 ``HMAC.digest_cons``，``HMAC.inner`` 和 ``HMAC.outer`` 已被" -"移除。" - -#: ../../library/hmac.rst:125 -msgid "This module also provides the following helper function:" -msgstr "這個模組還提供了下列輔助函式：" - -#: ../../library/hmac.rst:129 -msgid "" -"Return ``a == b``. This function uses an approach designed to prevent " -"timing analysis by avoiding content-based short circuiting behaviour, making " -"it appropriate for cryptography. *a* and *b* must both be of the same type: " -"either :class:`str` (ASCII only, as e.g. returned by :meth:`HMAC." -"hexdigest`), or a :term:`bytes-like object`." -msgstr "" -"回傳 ``a == b``。此函式使用一種經專門設計的方式透過避免基於內容的短路行為來防" -"止定時分析，使得它適合處理密碼學。*a* 和 *b* 必須為相同的型別：可以是 :class:" -"`str`\\ （僅限 ASCII，如 :meth:`HMAC.hexdigest` 的回傳值），或者是 :term:" -"`bytes-like object`。" - -#: ../../library/hmac.rst:137 -msgid "" -"If *a* and *b* are of different lengths, or if an error occurs, a timing " -"attack could theoretically reveal information about the types and lengths of " -"*a* and *b*—but not their values." -msgstr "" -"如果 *a* 和 *b* 具有不同的長度，或者如果發生了錯誤，定時攻擊在理論上可以取得" -"有關 *a* 和 *b* 的型別和長度的訊息 — 但不能取得他們的值。" - -#: ../../library/hmac.rst:145 -msgid "" -"The function uses OpenSSL's ``CRYPTO_memcmp()`` internally when available." -msgstr "此函式在可能的情況下會在內部使用 OpenSSL 的 ``CRYPTO_memcmp()``。" - -#: ../../library/hmac.rst:151 -msgid "Module :mod:`hashlib`" -msgstr ":mod:`hashlib` 模組" - -#: ../../library/hmac.rst:152 -msgid "The Python module providing secure hash functions." -msgstr "Python 模組提供安全的雜湊函式。" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Adrian Liaw , 2018 +# Phil Lin , 2022 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-09-04 00:15+0000\n" +"PO-Revision-Date: 2022-03-30 00:16+0800\n" +"Last-Translator: Phil Lin \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" +"X-Generator: Poedit 3.0.1\n" + +#: ../../library/hmac.rst:2 +msgid ":mod:`!hmac` --- Keyed-Hashing for Message Authentication" +msgstr ":mod:`!hmac` --- 基於金鑰雜湊的訊息驗證" + +#: ../../library/hmac.rst:10 +msgid "**Source code:** :source:`Lib/hmac.py`" +msgstr "**原始碼：**\\ :source:`Lib/hmac.py`" + +#: ../../library/hmac.rst:14 +msgid "" +"This module implements the HMAC algorithm as described by :rfc:`2104`. The " +"interface allows to use any hash function with a *fixed* digest size. In " +"particular, extendable output functions such as SHAKE-128 or SHAKE-256 " +"cannot be used with HMAC." +msgstr "" +"此模組實作了 :rfc:`2014` 所描述的 HMAC 演算法。此介面允許使用具有\\ *固定*\\ " +"摘要 (digest) 長度的任意雜湊函式。要特別注意的是擴充輸出函式（如 SHAKE-128 " +"或 SHAKE-256）不能與 HMAC 一起使用。" + +#: ../../library/hmac.rst:22 +msgid "" +"Return a new hmac object. *key* is a bytes or bytearray object giving the " +"secret key. If *msg* is present, the method call ``update(msg)`` is made. " +"*digestmod* is the digest name, digest constructor or module for the HMAC " +"object to use. It may be any name suitable to :func:`hashlib.new`. Despite " +"its argument position, it is required." +msgstr "" +"回傳一個新的 hmac 物件。*key* 是一個指定密鑰的 bytes（位元組）或 bytearray 物" +"件。如果提供了 *msg*，將會呼叫 ``update(msg)`` 方法。*digestmod* 為 HMAC 物件" +"所用的摘要名稱、摘要建構函式 (constructor) 或模組。它可以是適用於 :func:" +"`hashlib.new` 的任何名稱。儘管該引數的位置在後，但它卻是必須的。" + +#: ../../library/hmac.rst:28 +msgid "" +"Parameter *key* can be a bytes or bytearray object. Parameter *msg* can be " +"of any type supported by :mod:`hashlib`. Parameter *digestmod* can be the " +"name of a hash algorithm." +msgstr "" +"參數 *key* 可以為 bytes 或 bytearray 物件。參數 *msg* 可以為 :mod:`hashlib` " +"所支援的任意型別。參數 *digestmod* 可以為雜湊演算法的名稱。" + +#: ../../library/hmac.rst:33 +msgid "" +"The *digestmod* argument is now required. Pass it as a keyword argument to " +"avoid awkwardness when you do not have an initial *msg*." +msgstr "" +"*digestmod* 引數現在是必須的。請將其作為關鍵字引數傳入以避免當你沒有初始 " +"*msg* 時導致的麻煩。" + +#: ../../library/hmac.rst:40 +msgid "" +"Return digest of *msg* for given secret *key* and *digest*. The function is " +"equivalent to ``HMAC(key, msg, digest).digest()``, but uses an optimized C " +"or inline implementation, which is faster for messages that fit into memory. " +"The parameters *key*, *msg*, and *digest* have the same meaning as in :func:" +"`~hmac.new`." +msgstr "" +"基於給定密鑰 *key* 和 *digest* 回傳 *msg* 的摘要。此函式等價於 ``HMAC(key, " +"msg, digest).digest()``，但使用了最佳化的 C 或 行內實作（inline " +"implementation），對放入記憶體的訊息能處理得更快。參數 *key*、*msg* 和 " +"*digest* 在 :func:`~hmac.new` 中具有相同含義。" + +#: ../../library/hmac.rst:46 +msgid "" +"CPython implementation detail, the optimized C implementation is only used " +"when *digest* is a string and name of a digest algorithm, which is supported " +"by OpenSSL." +msgstr "" +"作為 CPython 的實現細節，C 的最佳化實作只有當 *digest* 為字串並且是一個 " +"OpenSSL 所支援的摘要演算法的名稱時才會被使用。" + +#: ../../library/hmac.rst:55 +msgid "An HMAC object has the following methods:" +msgstr "HMAC 物件具有下列方法 (method)：" + +#: ../../library/hmac.rst:59 +msgid "" +"Update the hmac object with *msg*. Repeated calls are equivalent to a " +"single call with the concatenation of all the arguments: ``m.update(a); m." +"update(b)`` is equivalent to ``m.update(a + b)``." +msgstr "" +"用 *msg* 來更新 hmac 物件。重複呼叫相當於單次呼叫並傳入所有引數的拼接結果：" +"``m.update(a); m.update(b)`` 等價於 ``m.update(a + b)``。" + +#: ../../library/hmac.rst:63 +msgid "Parameter *msg* can be of any type supported by :mod:`hashlib`." +msgstr "參數 *msg* 可以是 :mod:`hashlib` 所支援的任何型別。" + +#: ../../library/hmac.rst:69 +msgid "" +"Return the digest of the bytes passed to the :meth:`update` method so far. " +"This bytes object will be the same length as the *digest_size* of the digest " +"given to the constructor. It may contain non-ASCII bytes, including NUL " +"bytes." +msgstr "" +"回傳目前已傳給 :meth:`update` 方法的 bytes 摘要。這個 bytes 物件的長度會與傳" +"給建構函式的摘要 *digest_size* 的長度相同。它可以包含 NUL bytes 以及 non-" +"ASCII bytes。" + +#: ../../library/hmac.rst:76 +msgid "" +"When comparing the output of :meth:`digest` to an externally supplied digest " +"during a verification routine, it is recommended to use the :func:" +"`compare_digest` function instead of the ``==`` operator to reduce the " +"vulnerability to timing attacks." +msgstr "" +"在一個例行的驗證事務運行期間，將 :meth:`digest` 的輸出與外部提供的摘要進行比" +"較時，建議使用 :func:`compare_digest` 函式而不是 ``==`` 運算子以減少被定時攻" +"擊時的漏洞。" + +#: ../../library/hmac.rst:84 +msgid "" +"Like :meth:`digest` except the digest is returned as a string twice the " +"length containing only hexadecimal digits. This may be used to exchange the " +"value safely in email or other non-binary environments." +msgstr "" +"像是 :meth:`digest` 但摘要的回傳形式為兩倍長度的字串，且此字串只包含十六進位" +"數位。這可以被用於在電子郵件或其他非二進位制環境中安全地交換數據。" + +#: ../../library/hmac.rst:90 +msgid "" +"When comparing the output of :meth:`hexdigest` to an externally supplied " +"digest during a verification routine, it is recommended to use the :func:" +"`compare_digest` function instead of the ``==`` operator to reduce the " +"vulnerability to timing attacks." +msgstr "" +"在一個例行的驗證事務運行期間，將 :meth:`hexdigest` 的輸出與外部提供的摘要進行" +"比較時，建議使用 :func:`compare_digest` 函式而不是 ``==`` 運算子以減少被定時" +"攻擊時的漏洞。" + +#: ../../library/hmac.rst:98 +msgid "" +"Return a copy (\"clone\") of the hmac object. This can be used to " +"efficiently compute the digests of strings that share a common initial " +"substring." +msgstr "" +"回傳 hmac 物件的拷貝 (\"clone\")。這可以被用來有效率地計算那些共享相同初始子" +"字串的字串的摘要。" + +#: ../../library/hmac.rst:102 +msgid "A hash object has the following attributes:" +msgstr "一個 hash 物件具有以下屬性：" + +#: ../../library/hmac.rst:106 +msgid "The size of the resulting HMAC digest in bytes." +msgstr "以 bytes 表示最終 HMAC 摘要的大小。" + +#: ../../library/hmac.rst:110 +msgid "The internal block size of the hash algorithm in bytes." +msgstr "以 bytes 表示雜湊演算法的內部區塊大小。" + +#: ../../library/hmac.rst:116 +msgid "The canonical name of this HMAC, always lowercase, e.g. ``hmac-md5``." +msgstr "HMAC 的正準名稱總是為小寫形式，例如 ``hmac-md5``。" + +#: ../../library/hmac.rst:121 +msgid "" +"Removed the undocumented attributes ``HMAC.digest_cons``, ``HMAC.inner``, " +"and ``HMAC.outer``." +msgstr "" +"未寫入文件的屬性 ``HMAC.digest_cons``，``HMAC.inner`` 和 ``HMAC.outer`` 已被" +"移除。" + +#: ../../library/hmac.rst:125 +msgid "This module also provides the following helper function:" +msgstr "這個模組還提供了下列輔助函式：" + +#: ../../library/hmac.rst:129 +msgid "" +"Return ``a == b``. This function uses an approach designed to prevent " +"timing analysis by avoiding content-based short circuiting behaviour, making " +"it appropriate for cryptography. *a* and *b* must both be of the same type: " +"either :class:`str` (ASCII only, as e.g. returned by :meth:`HMAC." +"hexdigest`), or a :term:`bytes-like object`." +msgstr "" +"回傳 ``a == b``。此函式使用一種經專門設計的方式透過避免基於內容的短路行為來防" +"止定時分析，使得它適合處理密碼學。*a* 和 *b* 必須為相同的型別：可以是 :class:" +"`str`\\ （僅限 ASCII，如 :meth:`HMAC.hexdigest` 的回傳值），或者是 :term:" +"`bytes-like object`。" + +#: ../../library/hmac.rst:137 +msgid "" +"If *a* and *b* are of different lengths, or if an error occurs, a timing " +"attack could theoretically reveal information about the types and lengths of " +"*a* and *b*—but not their values." +msgstr "" +"如果 *a* 和 *b* 具有不同的長度，或者如果發生了錯誤，定時攻擊在理論上可以取得" +"有關 *a* 和 *b* 的型別和長度的訊息 — 但不能取得他們的值。" + +#: ../../library/hmac.rst:145 +msgid "" +"The function uses OpenSSL's ``CRYPTO_memcmp()`` internally when available." +msgstr "此函式在可能的情況下會在內部使用 OpenSSL 的 ``CRYPTO_memcmp()``。" + +#: ../../library/hmac.rst:151 +msgid "Module :mod:`hashlib`" +msgstr ":mod:`hashlib` 模組" + +#: ../../library/hmac.rst:152 +msgid "The Python module providing secure hash functions." +msgstr "Python 模組提供安全的雜湊函式。" diff --git a/library/html.entities.po b/library/html.entities.po index 4f108d3e57..a6428018c3 100644 --- a/library/html.entities.po +++ b/library/html.entities.po @@ -1,77 +1,77 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Liang-Bo Wang , 2017 -# Matt Wang , 2022 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-05-09 00:03+0000\n" -"PO-Revision-Date: 2022-06-27 09:38+0800\n" -"Last-Translator: Matt Wang \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" -"X-Generator: Poedit 3.1\n" - -#: ../../library/html.entities.rst:2 -msgid ":mod:`!html.entities` --- Definitions of HTML general entities" -msgstr ":mod:`!html.entities` --- HTML 一般實體的定義" - -#: ../../library/html.entities.rst:9 -msgid "**Source code:** :source:`Lib/html/entities.py`" -msgstr "**原始碼：**\\ :source:`Lib/html/entities.py`" - -#: ../../library/html.entities.rst:13 -msgid "" -"This module defines four dictionaries, :data:`html5`, :data:" -"`name2codepoint`, :data:`codepoint2name`, and :data:`entitydefs`." -msgstr "" -"該 module（模組）定義了四個字典：:data:`html5`、:data:`name2codepoint`、:" -"data:`codepoint2name` 以及 :data:`entitydefs`。" - -#: ../../library/html.entities.rst:19 -msgid "" -"A dictionary that maps HTML5 named character references [#]_ to the " -"equivalent Unicode character(s), e.g. ``html5['gt;'] == '>'``. Note that the " -"trailing semicolon is included in the name (e.g. ``'gt;'``), however some of " -"the names are accepted by the standard even without the semicolon: in this " -"case the name is present with and without the ``';'``. See also :func:`html." -"unescape`." -msgstr "" -"將 HTML5 命名字元引用 [#]_ 對映到同等 Unicode 字元的字典，例如 " -"``html5['gt;'] == '>'``。請注意，後面的的分號包含在名稱中（例如 ``'gt;'``），" -"但有些名稱即使沒有分號也會被此標準接受：在這種情況下，名稱可帶有或不帶有 " -"``';'``。請見 :func:`html.unescape`。" - -#: ../../library/html.entities.rst:31 -msgid "" -"A dictionary mapping XHTML 1.0 entity definitions to their replacement text " -"in ISO Latin-1." -msgstr "將 XHTML 1.0 實體定義對映到 ISO Latin-1 中的替換文字的字典。" - -#: ../../library/html.entities.rst:37 -msgid "A dictionary that maps HTML4 entity names to the Unicode code points." -msgstr "將 HTML4 實體名稱對映到 Unicode 程式點的字典。" - -#: ../../library/html.entities.rst:42 -msgid "A dictionary that maps Unicode code points to HTML4 entity names." -msgstr "將 Unicode 程式點對映到 HTML4 實體名稱的字典。" - -#: ../../library/html.entities.rst:46 -msgid "Footnotes" -msgstr "註解" - -#: ../../library/html.entities.rst:47 -msgid "" -"See https://html.spec.whatwg.org/multipage/named-characters.html#named-" -"character-references" -msgstr "" -"請見 https://html.spec.whatwg.org/multipage/named-characters.html#named-" -"character-references" +# Copyright (C) 2001 Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Liang-Bo Wang , 2017 +# Matt Wang , 2022 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.14\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-05-09 00:03+0000\n" +"PO-Revision-Date: 2022-06-27 09:38+0800\n" +"Last-Translator: Matt Wang \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" +"X-Generator: Poedit 3.1\n" + +#: ../../library/html.entities.rst:2 +msgid ":mod:`!html.entities` --- Definitions of HTML general entities" +msgstr ":mod:`!html.entities` --- HTML 一般實體的定義" + +#: ../../library/html.entities.rst:9 +msgid "**Source code:** :source:`Lib/html/entities.py`" +msgstr "**原始碼：**\\ :source:`Lib/html/entities.py`" + +#: ../../library/html.entities.rst:13 +msgid "" +"This module defines four dictionaries, :data:`html5`, :data:" +"`name2codepoint`, :data:`codepoint2name`, and :data:`entitydefs`." +msgstr "" +"該 module（模組）定義了四個字典：:data:`html5`、:data:`name2codepoint`、:" +"data:`codepoint2name` 以及 :data:`entitydefs`。" + +#: ../../library/html.entities.rst:19 +msgid "" +"A dictionary that maps HTML5 named character references [#]_ to the " +"equivalent Unicode character(s), e.g. ``html5['gt;'] == '>'``. Note that the " +"trailing semicolon is included in the name (e.g. ``'gt;'``), however some of " +"the names are accepted by the standard even without the semicolon: in this " +"case the name is present with and without the ``';'``. See also :func:`html." +"unescape`." +msgstr "" +"將 HTML5 命名字元引用 [#]_ 對映到同等 Unicode 字元的字典，例如 " +"``html5['gt;'] == '>'``。請注意，後面的的分號包含在名稱中（例如 ``'gt;'``），" +"但有些名稱即使沒有分號也會被此標準接受：在這種情況下，名稱可帶有或不帶有 " +"``';'``。請見 :func:`html.unescape`。" + +#: ../../library/html.entities.rst:31 +msgid "" +"A dictionary mapping XHTML 1.0 entity definitions to their replacement text " +"in ISO Latin-1." +msgstr "將 XHTML 1.0 實體定義對映到 ISO Latin-1 中的替換文字的字典。" + +#: ../../library/html.entities.rst:37 +msgid "A dictionary that maps HTML4 entity names to the Unicode code points." +msgstr "將 HTML4 實體名稱對映到 Unicode 程式點的字典。" + +#: ../../library/html.entities.rst:42 +msgid "A dictionary that maps Unicode code points to HTML4 entity names." +msgstr "將 Unicode 程式點對映到 HTML4 實體名稱的字典。" + +#: ../../library/html.entities.rst:46 +msgid "Footnotes" +msgstr "註解" + +#: ../../library/html.entities.rst:47 +msgid "" +"See https://html.spec.whatwg.org/multipage/named-characters.html#named-" +"character-references" +msgstr "" +"請見 https://html.spec.whatwg.org/multipage/named-characters.html#named-" +"character-references" diff --git a/library/html.parser.po b/library/html.parser.po index 0e2c714153..9a313fc0f0 100644 --- a/library/html.parser.po +++ b/library/html.parser.po @@ -1,654 +1,654 @@ -# Copyright (C) 2001 Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Matt Wang , 2023 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.14\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-11-01 00:16+0000\n" -"PO-Revision-Date: 2023-05-04 22:54+0800\n" -"Last-Translator: Matt Wang \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" -"X-Generator: Poedit 3.2.2\n" - -#: ../../library/html.parser.rst:2 -msgid ":mod:`!html.parser` --- Simple HTML and XHTML parser" -msgstr ":mod:`!html.parser` --- 簡單的 HTML 和 XHTML 剖析器" - -#: ../../library/html.parser.rst:7 -msgid "**Source code:** :source:`Lib/html/parser.py`" -msgstr "**原始碼：**\\ :source:`Lib/html/parser.py`" - -#: ../../library/html.parser.rst:15 -msgid "" -"This module defines a class :class:`HTMLParser` which serves as the basis " -"for parsing text files formatted in HTML (HyperText Mark-up Language) and " -"XHTML." -msgstr "" -"該模組定義了一個類別 :class:`HTMLParser`，是剖析 (parse) HTML（HyperText " -"Mark-up Language、超文本標記語言）和 XHTML 格式文本檔案的基礎。" - -#: ../../library/html.parser.rst:20 -msgid "Create a parser instance able to parse invalid markup." -msgstr "建立一個能夠剖析無效標記的剖析器實例。" - -#: ../../library/html.parser.rst:22 -msgid "" -"If *convert_charrefs* is true (the default), all character references " -"(except the ones in elements like ``script`` and ``style``) are " -"automatically converted to the corresponding Unicode characters." -msgstr "" -"如果 *convert_charrefs* 為 true （預設值），所有字元參照 (reference)" -"（元素中的參照除外，像是 ``script`` 和 ``style`` ）將自動轉換為相應的 Unicode 字元。" - -#: ../../library/html.parser.rst:26 -msgid "" -"If *scripting* is false (the default), the content of the ``noscript`` " -"element is parsed normally; if it's true, it's returned as is without being " -"parsed." -msgstr "" - -#: ../../library/html.parser.rst:30 -msgid "" -"An :class:`.HTMLParser` instance is fed HTML data and calls handler methods " -"when start tags, end tags, text, comments, and other markup elements are " -"encountered. The user should subclass :class:`.HTMLParser` and override its " -"methods to implement the desired behavior." -msgstr "" -":class:`.HTMLParser` 實例被提供 HTML 資料，並在遇到開始標籤、結束標籤、文本、" -"註解和其他標記元素時呼叫處理程式 (handler) 方法。使用者應該繼承 :class:`." -"HTMLParser` 並覆蓋其方法以實作所需的行為。" - -#: ../../library/html.parser.rst:35 -msgid "" -"This parser does not check that end tags match start tags or call the end-" -"tag handler for elements which are closed implicitly by closing an outer " -"element." -msgstr "" -"此剖析器不檢查結束標籤是否與開始標籤匹配，也不會為透過結束外部元素來隱晦地被" -"結束的元素呼叫結束標籤處理程式。" - -#: ../../library/html.parser.rst:38 -msgid "*convert_charrefs* keyword argument added." -msgstr "新增關鍵字引數 *convert_charrefs*。" - -#: ../../library/html.parser.rst:41 -msgid "The default value for argument *convert_charrefs* is now ``True``." -msgstr "引數 *convert_charrefs* 的預設值現在是 ``True``。" - -#: ../../library/html.parser.rst:44 -msgid "Added the *scripting* parameter." -msgstr "" - -#: ../../library/html.parser.rst:49 -msgid "Example HTML Parser Application" -msgstr "HTML 剖析器應用程式範例" - -#: ../../library/html.parser.rst:51 -msgid "" -"As a basic example, below is a simple HTML parser that uses the :class:" -"`HTMLParser` class to print out start tags, end tags, and data as they are " -"encountered:" -msgstr "" -"以下的基礎範例是一個簡單的 HTML 剖析器，它使用 :class:`HTMLParser` 類別，當遇" -"到開始標籤、結束標籤和資料時將它們印出：" - -#: ../../library/html.parser.rst:55 -msgid "" -"from html.parser import HTMLParser\n" -"\n" -"class MyHTMLParser(HTMLParser):\n" -" def handle_starttag(self, tag, attrs):\n" -" print(\"Encountered a start tag:\", tag)\n" -"\n" -" def handle_endtag(self, tag):\n" -" print(\"Encountered an end tag :\", tag)\n" -"\n" -" def handle_data(self, data):\n" -" print(\"Encountered some data :\", data)\n" -"\n" -"parser = MyHTMLParser()\n" -"parser.feed('Test'\n" -" '

Parse me!

')" -msgstr "" -"from html.parser import HTMLParser\n" -"\n" -"class MyHTMLParser(HTMLParser):\n" -" def handle_starttag(self, tag, attrs):\n" -" print(\"Encountered a start tag:\", tag)\n" -"\n" -" def handle_endtag(self, tag):\n" -" print(\"Encountered an end tag :\", tag)\n" -"\n" -" def handle_data(self, data):\n" -" print(\"Encountered some data :\", data)\n" -"\n" -"parser = MyHTMLParser()\n" -"parser.feed('Test'\n" -" '

Parse me!

')" - -#: ../../library/html.parser.rst:73 -msgid "The output will then be:" -msgstr "輸出將是：" - -#: ../../library/html.parser.rst:75 -msgid "" -"Encountered a start tag: html\n" -"Encountered a start tag: head\n" -"Encountered a start tag: title\n" -"Encountered some data : Test\n" -"Encountered an end tag : title\n" -"Encountered an end tag : head\n" -"Encountered a start tag: body\n" -"Encountered a start tag: h1\n" -"Encountered some data : Parse me!\n" -"Encountered an end tag : h1\n" -"Encountered an end tag : body\n" -"Encountered an end tag : html" -msgstr "" -"Encountered a start tag: html\n" -"Encountered a start tag: head\n" -"Encountered a start tag: title\n" -"Encountered some data : Test\n" -"Encountered an end tag : title\n" -"Encountered an end tag : head\n" -"Encountered a start tag: body\n" -"Encountered a start tag: h1\n" -"Encountered some data : Parse me!\n" -"Encountered an end tag : h1\n" -"Encountered an end tag : body\n" -"Encountered an end tag : html" - -#: ../../library/html.parser.rst:92 -msgid ":class:`.HTMLParser` Methods" -msgstr ":class:`.HTMLParser` 方法" - -#: ../../library/html.parser.rst:94 -msgid ":class:`HTMLParser` instances have the following methods:" -msgstr ":class:`HTMLParser` 實例具有以下方法：" - -#: ../../library/html.parser.rst:99 -msgid "" -"Feed some text to the parser. It is processed insofar as it consists of " -"complete elements; incomplete data is buffered until more data is fed or :" -"meth:`close` is called. *data* must be :class:`str`." -msgstr "" -"向剖析器提供一些文本。只要它由完整的元素組成，它就會被處理；不完整的資料會被" -"緩衝，直到輸入更多資料或呼叫 :meth:`close`。 *data* 必須是 :class:`str`。" - -#: ../../library/html.parser.rst:106 -msgid "" -"Force processing of all buffered data as if it were followed by an end-of-" -"file mark. This method may be redefined by a derived class to define " -"additional processing at the end of the input, but the redefined version " -"should always call the :class:`HTMLParser` base class method :meth:`close`." -msgstr "" -"強制處理所有緩衝資料，如同它後面跟有文件結束標籤一樣。此方法可能有被衍生類別" -"重新定義，以在輸入末尾定義額外的處理，但重新定義的版本仍應要呼叫 :class:" -"`HTMLParser` 基底類別方法 :meth:`close`。" - -#: ../../library/html.parser.rst:114 -msgid "" -"Reset the instance. Loses all unprocessed data. This is called implicitly " -"at instantiation time." -msgstr "重置實例。丟棄所有未處理的資料。這在實例化時被會隱晦地呼叫。" - -#: ../../library/html.parser.rst:120 -msgid "Return current line number and offset." -msgstr "回傳目前列號 (line number) 和偏移量 (offset)。" - -#: ../../library/html.parser.rst:125 -msgid "" -"Return the text of the most recently opened start tag. This should not " -"normally be needed for structured processing, but may be useful in dealing " -"with HTML \"as deployed\" or for re-generating input with minimal changes " -"(whitespace between attributes can be preserved, etc.)." -msgstr "" -"回傳最近開啟 (open) 的開始標籤的文本。這對於結構化處理通常不必要，但在處理" -"「已部署」的 HTML 或以最少的更改重新生成輸入（可以保留屬性之間的空白等）時可" -"能很有用。" - -#: ../../library/html.parser.rst:131 -msgid "" -"The following methods are called when data or markup elements are " -"encountered and they are meant to be overridden in a subclass. The base " -"class implementations do nothing (except for :meth:`~HTMLParser." -"handle_startendtag`):" -msgstr "" -"當遇到資料或標記元素時將呼叫以下方法，並且它們應在子類別中被覆蓋。基底類別實" -"作什麼都不做（除了 :meth:`~HTMLParser.handle_startendtag`）：" - -#: ../../library/html.parser.rst:138 -msgid "" -"This method is called to handle the start tag of an element (e.g. ``
``)." -msgstr "呼叫此方法來處理元素的開始標籤（例如 ``
``）。" - -#: ../../library/html.parser.rst:140 -msgid "" -"The *tag* argument is the name of the tag converted to lower case. The " -"*attrs* argument is a list of ``(name, value)`` pairs containing the " -"attributes found inside the tag's ``<>`` brackets. The *name* will be " -"translated to lower case, and quotes in the *value* have been removed, and " -"character and entity references have been replaced." -msgstr "" -"*tag* 引數是轉換為小寫的標籤名稱。 *attrs* 引數是一個 ``(name, value)`` 對的" -"列表，包含在標籤的 ``<>`` 括號內找到的屬性。 *name* 將被轉成小寫，*value* 中" -"的引號會被刪除，字元和實體參照也會被替換。" - -#: ../../library/html.parser.rst:146 -msgid "" -"For instance, for the tag ````, this method " -"would be called as ``handle_starttag('a', [('href', 'https://www.cwi." -"nl/')])``." -msgstr "" -"例如，對於標籤 ````，這個方法會以 " -"``handle_starttag('a', [('href', 'https://www.cwi.nl/')])`` 的形式被呼叫。" - -#: ../../library/html.parser.rst:149 -msgid "" -"All entity references from :mod:`html.entities` are replaced in the " -"attribute values." -msgstr "在屬性值中來自 :mod:`html.entities` 的所有實體參照都會被替換。" - -#: ../../library/html.parser.rst:155 -msgid "" -"This method is called to handle the end tag of an element (e.g. ``
``)." -msgstr "呼叫此方法來處理元素的結束標籤（例如 ``
``）。" - -#: ../../library/html.parser.rst:157 -msgid "The *tag* argument is the name of the tag converted to lower case." -msgstr "*tag* 引數是轉換為小寫的標籤名稱。" - -#: ../../library/html.parser.rst:162 -msgid "" -"Similar to :meth:`handle_starttag`, but called when the parser encounters an " -"XHTML-style empty tag (````). This method may be overridden by " -"subclasses which require this particular lexical information; the default " -"implementation simply calls :meth:`handle_starttag` and :meth:" -"`handle_endtag`." -msgstr "" -"與 :meth:`handle_starttag` 類似，但在剖析器遇到 XHTML 樣式的空標籤 " -"(````) 時呼叫。這個方法可能被需要這個特定詞彙資訊 (lexical " -"information) 的子類別覆蓋；預設實作只是呼叫 :meth:`handle_starttag` 和 :meth:" -"`handle_endtag`。" - -#: ../../library/html.parser.rst:170 -msgid "" -"This method is called to process arbitrary data (e.g. text nodes and the " -"content of elements like ``script`` and ``style``)." -msgstr "" -"呼叫此方法來處理任意資料（例如文本節點與像是 ``script`` 和 ``style`` 元素的內容）。" - -#: ../../library/html.parser.rst:176 -msgid "" -"This method is called to process a named character reference of the form " -"``&name;`` (e.g. ``>``), where *name* is a general entity reference (e.g. " -"``'gt'``). This method is only called if *convert_charrefs* is false." -msgstr "" -"呼叫此方法來處理形式為 ``&name;`` （例如 ``>``）的附名字元參照，其中 " -"*name* 是一般實體參照（例如 ``'gt'``）。此方法只有在 *convert_charrefs* 為 " -"false 時才會被呼叫。" - -#: ../../library/html.parser.rst:184 -msgid "" -"This method is called to process decimal and hexadecimal numeric character " -"references of the form :samp:`&#{NNN};` and :samp:`&#x{NNN};`. For example, " -"the decimal equivalent for ``>`` is ``>``, whereas the hexadecimal is " -"``>``; in this case the method will receive ``'62'`` or ``'x3E'``. This " -"method is only called if *convert_charrefs* is false." -msgstr "" -"呼叫此方法來處理 :samp:`&#{NNN};` 和 :samp:`&#x{NNN};` 形式的十進位和十六進位" -"數字字元參照。例如，``>`` 的十進位等效為 ``>``，而十六進位為 ``>" -"``；在這種情況下，該方法將收到 ``'62'`` 或 ``'x3E'``。此方法只有在 *convert_charrefs* 為 " -"false 時才會被呼叫。" - -#: ../../library/html.parser.rst:193 -msgid "" -"This method is called when a comment is encountered (e.g. ````）。" - -#: ../../library/html.parser.rst:195 -msgid "" -"For example, the comment ```` will cause this method to be " -"called with the argument ``' comment '``." -msgstr "" -"舉例來說，註解 ```` 會使得此方法被以引數 ``' comment '`` 來呼" -"叫。" - -#: ../../library/html.parser.rst:198 -msgid "" -"The content of Internet Explorer conditional comments (condcoms) will also " -"be sent to this method, so, for ````, this method will receive ``'[if IE 9]>IE9-specific contentIE9-specific content`` 為例，" -"這個方法將會收到 ``'[if IE 9]>IE9-specific content``)." -msgstr "" -"呼叫此方法來處理 HTML 文件類型聲明 (doctype declaration)（例如 ````）。" - -#: ../../library/html.parser.rst:208 -msgid "" -"The *decl* parameter will be the entire contents of the declaration inside " -"the ```` markup (e.g. ``'DOCTYPE html'``)." -msgstr "" -"*decl* 參數將是 ```` 標記內聲明部分的全部內容（例如 ``'DOCTYPE " -"html'``）。" - -#: ../../library/html.parser.rst:214 -msgid "" -"Method called when a processing instruction is encountered. The *data* " -"parameter will contain the entire processing instruction. For example, for " -"the processing instruction ````, this method would be " -"called as ``handle_pi(\"proc color='red'\")``. It is intended to be " -"overridden by a derived class; the base class implementation does nothing." -msgstr "" -"遇到處理指示 (processing instruction) 時會呼叫的方法。 *data* 參數將包含整個" -"處理指示。例如，對於處理指示 ````，這個方法將以 " -"``handle_pi(\"proc color='red'\")`` 形式被呼叫。它旨在被衍生類別覆蓋；基底類" -"別實作中什麼都不做。" - -#: ../../library/html.parser.rst:222 -msgid "" -"The :class:`HTMLParser` class uses the SGML syntactic rules for processing " -"instructions. An XHTML processing instruction using the trailing ``'?'`` " -"will cause the ``'?'`` to be included in *data*." -msgstr "" -":class:`HTMLParser` 類別使用 SGML 語法規則來處理指示。使用有 ``?`` 跟隨在後面" -"的 XHTML 處理指示將導致 ``?`` 被包含在 *data* 中。" - -#: ../../library/html.parser.rst:229 -msgid "" -"This method is called when an unrecognized declaration is read by the parser." -msgstr "當剖析器讀取無法識別的聲明時會呼叫此方法。" - -#: ../../library/html.parser.rst:231 -msgid "" -"The *data* parameter will be the entire contents of the declaration inside " -"the ```` markup. It is sometimes useful to be overridden by a " -"derived class. The base class implementation does nothing." -msgstr "" -"*data* 參數將是 ```` 標記內聲明的全部內容。有時被衍生類別被覆蓋會是好" -"用的。在基底類別實作中什麼都不做。" - -#: ../../library/html.parser.rst:239 -msgid "Examples" -msgstr "範例" - -#: ../../library/html.parser.rst:241 -msgid "" -"The following class implements a parser that will be used to illustrate more " -"examples:" -msgstr "以下類別實作了一個剖析器，將用於解說更多範例：" - -#: ../../library/html.parser.rst:244 -msgid "" -"from html.parser import HTMLParser\n" -"from html.entities import name2codepoint\n" -"\n" -"class MyHTMLParser(HTMLParser):\n" -" def handle_starttag(self, tag, attrs):\n" -" print(\"Start tag:\", tag)\n" -" for attr in attrs:\n" -" print(\" attr:\", attr)\n" -"\n" -" def handle_endtag(self, tag):\n" -" print(\"End tag :\", tag)\n" -"\n" -" def handle_data(self, data):\n" -" print(\"Data :\", data)\n" -"\n" -" def handle_comment(self, data):\n" -" print(\"Comment :\", data)\n" -"\n" -" def handle_entityref(self, name):\n" -" c = chr(name2codepoint[name])\n" -" print(\"Named ent:\", c)\n" -"\n" -" def handle_charref(self, name):\n" -" if name.startswith('x'):\n" -" c = chr(int(name[1:], 16))\n" -" else:\n" -" c = chr(int(name))\n" -" print(\"Num ent :\", c)\n" -"\n" -" def handle_decl(self, data):\n" -" print(\"Decl :\", data)\n" -"\n" -"parser = MyHTMLParser()" -msgstr "" -"from html.parser import HTMLParser\n" -"from html.entities import name2codepoint\n" -"\n" -"class MyHTMLParser(HTMLParser):\n" -" def handle_starttag(self, tag, attrs):\n" -" print(\"Start tag:\", tag)\n" -" for attr in attrs:\n" -" print(\" attr:\", attr)\n" -"\n" -" def handle_endtag(self, tag):\n" -" print(\"End tag :\", tag)\n" -"\n" -" def handle_data(self, data):\n" -" print(\"Data :\", data)\n" -"\n" -" def handle_comment(self, data):\n" -" print(\"Comment :\", data)\n" -"\n" -" def handle_entityref(self, name):\n" -" c = chr(name2codepoint[name])\n" -" print(\"Named ent:\", c)\n" -"\n" -" def handle_charref(self, name):\n" -" if name.startswith('x'):\n" -" c = chr(int(name[1:], 16))\n" -" else:\n" -" c = chr(int(name))\n" -" print(\"Num ent :\", c)\n" -"\n" -" def handle_decl(self, data):\n" -" print(\"Decl :\", data)\n" -"\n" -"parser = MyHTMLParser()" - -#: ../../library/html.parser.rst:280 -msgid "Parsing a doctype:" -msgstr "剖析文件類型：" - -#: ../../library/html.parser.rst:282 -msgid "" -">>> parser.feed('')\n" -"Decl : DOCTYPE HTML PUBLIC \"-//W3C//DTD HTML 4.01//EN\" \"http://www.w3." -"org/TR/html4/strict.dtd\"" -msgstr "" -">>> parser.feed('')\n" -"Decl : DOCTYPE HTML PUBLIC \"-//W3C//DTD HTML 4.01//EN\" \"http://www.w3." -"org/TR/html4/strict.dtd\"" - -#: ../../library/html.parser.rst:288 -msgid "Parsing an element with a few attributes and a title:" -msgstr "剖析一個具有一些屬性和標題的元素：" - -#: ../../library/html.parser.rst:290 -msgid "" -">>> parser.feed('\"The')\n" -"Start tag: img\n" -" attr: ('src', 'python-logo.png')\n" -" attr: ('alt', 'The Python logo')\n" -">>>\n" -">>> parser.feed('

Python

')\n" -"Start tag: h1\n" -"Data : Python\n" -"End tag : h1" -msgstr "" -">>> parser.feed('\"The')\n" -"Start tag: img\n" -" attr: ('src', 'python-logo.png')\n" -" attr: ('alt', 'The Python logo')\n" -">>>\n" -">>> parser.feed('

Python

')\n" -"Start tag: h1\n" -"Data : Python\n" -"End tag : h1" - -#: ../../library/html.parser.rst:302 -msgid "" -"The content of elements like ``script`` and ``style`` is returned as is, " -"without further parsing:" -msgstr "像是 ``script`` 和 ``style`` 這類元素的內容將按原樣回傳，無需進一步的剖析：" - -#: ../../library/html.parser.rst:305 -msgid "" -">>> parser.feed('